From f2b02c455f2bcdfb905a015eefbb630a28b4b12e Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Thu, 12 Nov 2026 10:56:42 -0300 Subject: addons: an addon can hand the frontend a GPU scene (ABI 3.1), and a snake drawn by shaders does; a commit's patch keeps its own +Diff pane; a real ZLS checked through the window build ABI 3.1 appends an optional `gpu` callback and its context to pa_paint: one self-contained sketchbook SGPU v1 scene for the pane, at most 4 MiB, copied during the call, the last successful call winning. The SDL frontend runs it on its own GPU through sketchbook's executor and composites its target texture into the pane; replicas carry the scene beside the authoritative pane frame; cells and rasters stay the fallback for terminals, older hosts and frontends without an executor. addons/snake_shader is such an addon (`zig build snake-shader`, the SnakeShader word: a board that follows its pane, buffered turns, a CRT look), with test/gpu_snake.py, test/gpu_snake_interaction.py and test/gpu_upgrade.py. Commit patches open as `+Diff-` and reuse only their own commit's pane, so another paged patch no longer replaces one already open. The language-server client looks in the standard per-user bin directory, which desktop launchers often leave out of PATH, and takes an empty answer that beats the startup progress notification onto the wire; test/real_zls.py checks imports, hover, references, rename previews, diagnostics and completion against a real ZLS from a private home. The dump's schema reader skips two fields older builds persisted, and a replica's shadow of a kind ticks when the authority's does. The reference, the guide, the building and setup notes and the changelog say so. The working copy as it stood on 2026-11-12; message written by Claude from the diff, at the author's request. --- docs/typ/building.typ | 15 +++++++++++++-- docs/typ/guide.typ | 3 ++- docs/typ/reference.typ | 27 +++++++++++++++++++++++++++ docs/typ/setup.typ | 3 ++- 4 files changed, 44 insertions(+), 4 deletions(-) (limited to 'docs/typ') diff --git a/docs/typ/building.typ b/docs/typ/building.typ index 31019116..6bf7dfce 100644 --- a/docs/typ/building.typ +++ b/docs/typ/building.typ @@ -41,8 +41,10 @@ system takes the SDK SDL needs with `-Dmacos-sdk=`. A bare `zig build` installs into the prefix (`zig-out`, or `--prefix `) and copies the binaries into `~/.local/bin`; `-Dhome-install=false` leaves that copy out. Zig 0.17 keeps the prefix from the build script, so -`--prefix` alone no longer stops it. With `-Dplatform` nothing is copied, -so always pass `-Dplatform` while developing. Test, benchmark and run steps build what they need +`--prefix` alone no longer stops it. With `-Dplatform` binaries are not copied. The `image`, `pdf` and +`addons` steps also install into `$XDG_DATA_HOME/pardes/addons` (else +`~/.local/share/pardes/addons`); `-Dhome-install=false` skips that copy. +Pass `-Dplatform` and `-Dhome-install=false` while developing. Test, benchmark and run steps build what they need without installing. `pardes --version` prints `pardes ` (from `build.zig.zon`), plus the commit for release builds and the `~/.local` install, and on a second line the build's semantics hash, which a replica @@ -183,6 +185,15 @@ zig build cheatsheet render the cheatsheet PDF (needs typst) - `python3 -B test/agent_session.py --ready 'text' --min-rows N -- command args` drives an interactive command in a private shell and checks it through 9P. +The optional real-server check +`python3 -B test/real_zls.py GUI_BINARY ZLS_BINARY OUTPUT_DIRECTORY` +uses a private home and a restricted desktop `PATH`. It checks a build-module +import as the first query without retries, standard and relative imports, +paths with spaces, imported symbols, +hover, references, rename previews, diagnostics and completion while editing. +It requires Zig and ZLS; `core-test -Dtest-filter=lsp_client` checks the +protocol client's own tests without installed language servers. + == Release gates A release passes all of these first: `unit-test` with `-Dplatform=tui` and diff --git a/docs/typ/guide.typ b/docs/typ/guide.typ index df53d0b9..c602927d 100644 --- a/docs/typ/guide.typ +++ b/docs/typ/guide.typ @@ -273,7 +273,8 @@ is drawn as a diff, each hunk in its file's language. #btn("B3") on: ) A `.diff` or `.patch` looked at, and a diff paged (`git show`), opens as -a `+Diff`, stacked as delta shows one: each hunk under its `path:line` +a `+Diff` (`+Diff-` for a commit, each commit keeping its own +pane), stacked as delta shows one: each hunk under its `path:line` (`Space j n`/`Space j p` step through them, #btn("B3") opens it) and the declarations around it, a `+`/`-` before each line, the words a changed line changed tinted and a line added or removed whole faintly. A mailed patch keeps its diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ index 030b7c6a..7360179f 100644 --- a/docs/typ/reference.typ +++ b/docs/typ/reference.typ @@ -1375,3 +1375,30 @@ with Client(sys.argv[1]) as c: # a socket path, or (ip, port) [`pty/run` output], [64 KiB], [file name component], [255 bytes], ) + +== Optional GPU scenes + +ABI 3.1 appends an optional `gpu` callback and its context to `pa_paint`. +An addon checks `api->abi >= 0x30001` before reading it; a null callback +means unsupported. `addon.Paint.gpu(bytes)` does both checks. The callback +copies at most 4 MiB during the call, so a stack buffer is valid. It takes +one self-contained sketchbook SGPU v1 scene, not device pointers. Paint +cells or a raster too: terminals, older hosts and frontends without a GPU +scene executor keep that fallback. Acceptance means the host can carry +the scene, not that every view can render it. + +The SDL frontend runs scenes on its own GPU and composites their target +textures; replicas carry the scene alongside the authoritative pane frame. +The scene codec and executor live in sketchbook (`src/gpu/scene.zig` and +`src/gpu/Executor.zig`). GPU support adds no required addon operation. + +`zig build snake-shader` builds `zig-out/lib/libsnake_shader.so` (with +`glslc`). Load it with `Addon load /absolute/path/libsnake_shader.so`, then +run `SnakeShader`: a GPU board with square cells that expands and shrinks +with its pane. `h j k l` or arrows steer, and `r` restarts. Two turns can +be buffered; a late turn gets 60 ms of grace. Losing focus pauses movement. +Hover highlights a cell; bloom, colour mapping, RGB phosphors and scanlines +give it a CRT appearance, with a subtle food pulse and phosphor shimmer +while paused. A severe shrink can shorten the tail, keeping the score. +The text fallback remains available. A running older host must be upgraded +to display the GPU version. diff --git a/docs/typ/setup.typ b/docs/typ/setup.typ index 2a10c52c..c9556c61 100644 --- a/docs/typ/setup.typ +++ b/docs/typ/setup.typ @@ -119,7 +119,8 @@ script on that `PATH` is a word you can click. = Language servers -pardes starts a language server for a file it knows, from `PATH`: +pardes starts a language server for a file it knows, searching `PATH` first +and then `~/.local/bin` (desktop launchers may leave it out of `PATH`): #pairs( [`.zig`], [`zls` (`PARDES_LSP_ZIG`)], -- cgit v1.3