big slow change: prebuilt shaders (SPIR-V/Metal), core gui reflow, docs, web + snapshot refresh

1 files changed, 123 insertions, 9 deletions

diff --git a/docs/config.md b/docs/config.md
index 30962ddb..7e27216b 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -16,15 +16,39 @@ still resolves, because "nothing is there yet" is the answer `Config` exists
 to give. There is one case with no path at all: a native launch with no `HOME`
 set, which `Config` reports as such.
 
-`Config` (`SPC f c`, or the word executed anywhere) prints the resolved path
-into a `+Config` output pane, so the machine answers this rather than the list
-above. The path is printed whether or not a file is there — that is the case
-you ask in — and the row is ordinary text, so a right click on it opens the
-file.
+`Config` (`SPC f c`, or the word executed anywhere) opens one refreshable
+`+Config` pane. It reports the startup path and every live config-like value:
+theme, colors, wrapping, tag position, debug mode, the requested shell and the
+executable actually resolved at the last spawn, requested/effective GUI font
+and size, tagline scale, panel transition,
+scene effects, hover delay, platform, native-image support, and (on SDL) whether
+the executable uses live-built shaders or the paired prebuilt shader snapshot.
+Platform-dependent rows say `unsupported` instead of looking like an off or
+empty supported setting: TTY reports Font and scene shaders as unsupported;
+web reports Font, panel transitions, and scene shaders as unsupported. Tagline
+font size is its own row and capability — GUI font selection is native-only,
+while the browser still applies the compiled tagline percentage to its DOM.
+The startup path is printed whether or not a file exists — that is usually when
+it is most useful — and is ordinary selectable text, so a right click on it
+opens the file. Shell follows the same requested/effective/pending model as
+Font. `Compiled default shell` is the command built into the binary; `Shell
+effective (last spawn)` is the executable the native host really chose after
+installation lookup and fallback. A changed request remains pending until a
+terminal is spawned, because the core does not resolve native executables.
+
+The mutable global values live together in the plain `runtime_config.State` record.
+One plain capability record gates the setting registry, leader table,
+`EffectCode`, and report; the compile-time setting table generates both setter
+builtins and their `Config` rows. Exhaustive checks require every table-backed
+toggle, transition, and scene-effect switch to occur exactly once, so those
+generated setting builtins cannot quietly lose their query row or leave a
+renderer switch unnamed. Manual pane-local actions remain with their payload (for
+example an image tag reports its renderer choices); they are not global
+configuration.
 
 The browser build has no local user-config path and does not load this file.
-(Nor does it have the `Font` builtin, or a language backend, or ptys of its
-own — see `docs/web.md`.)
+(Nor does it have `Font`, the effect builtins or `EffectCode`, a language
+backend, or ptys of its own — see `docs/web.md`.)
 
 The format is one existing builtin command per line, using the same spelling
 and argument parsing as commands executed inside pardes:
@@ -32,14 +56,16 @@ and argument parsing as commands executed inside pardes:
 ```text
 Theme acme
 Font DejaVuSansMono-Regular
+TaglineSize 82
 Shell zsh
 Wrap
 ```
 
 A line matches a builtin whose name takes NO argument only as that whole word:
 `Kill` runs, `Kill something` does not. Builtins that take one (`Theme`,
-`Font`, `Shell`, `Restore`, `Find`, `Grep`, `Rename`, `WsSymbols`, `Look`,
-`Exec`) take everything after the name as the argument.
+`Font`, `TaglineSize`, `Shell`, `Restore`, `Find`, `Grep`, `Rename`,
+`WsSymbols`, `Look`, `Exec`, `EffectCode`) take everything after the name as
+the argument.
 
 `Theme <name>` wants one of the 228 names in the ring. Do not derive the
 spelling — read it off `ThemeSel` (`SPC t t`), which lists every one as the
@@ -60,6 +86,20 @@ terminal's font belongs to its emulator and a browser's to the page — so a
 resolve the name by walking the font directories on every lookup, so a face
 installed a moment ago is findable.
 
+`Font` is asynchronous at the renderer boundary. `Config` therefore keeps
+requested name/path, pending state, and the effective face/point-or-pixel size
+as separate facts; a failed request never gets reported as the face on screen.
+Taglines use a distinct face size in both native GUI renderers. Execute
+`TaglineSize <percent>` to change it live, for example `TaglineSize 70`; the
+accepted range is 1 through 100 and the default comes from
+`gui_tagline_font_percent` in `src/config.zig` (82). The native renderer
+remeasures both the glyph and its visible tag band while retaining the body's
+cell grid. The 100% ceiling is deliberate: a tagline remains exactly one
+logical grid row, so a larger face or band would overlap its pane body or a
+neighbour instead of leaving the body grid stable. `Config` reports the active
+percentage. The browser applies the same compiled percentage to its DOM glyphs
+but has no runtime setter.
+
 What happens to a codepoint the chosen face has no glyph for differs by shell.
 The SDL GUI falls back through a chain it builds itself: embedded Adwaita
 Mono, then installed `NotoSansMono-Regular`, `DejaVuSansMono`,
@@ -76,3 +116,77 @@ bad line does not prevent later lines from running. Top-level text that is not
 a builtin is not sent to a shell. (`Exec ...` remains an ordinary builtin and
 therefore keeps its normal behavior.) Key bindings remain compile-time choices
 in `src/config.zig`; this startup file does not remap them.
+
+## Panel and scene effects
+
+Exactly one panel transition is selected at a time. Executing its builtin a
+second time turns it off; selecting another replaces it:
+
+```text
+PanelSlide
+PanelZoom
+PanelDissolve
+PanelAscii
+PanelVertical
+```
+
+All panel transitions start off. Slide uses cubic ease-out and zoom uses an
+overshooting ease-out-back. Dissolve and ASCII compare the last successfully
+presented grid with the new one: cells which did not change are immediately
+canonical, while changed cells cross from old to new through smoothstep or
+stable themed punctuation. Vertical is a pane-lifecycle effect: a newly added
+pane rises from below inside its own fixed box, and a deleted pane's frozen
+content rises out; surviving panes are never animated. The TTY implementation
+performs those operations directly on a copy of the canonical cell grid.
+The SDL and native macOS GUI implementations pass plain panel tracks to their
+GPU shaders, including native image/PDF pixels; layout itself commits
+immediately and remains the one authoritative geometry. DOM web intentionally
+does not expose these builtins: its renderer is selectable HTML/CSS and has no
+canvas or shader stage.
+
+The scene effects are independent switches and can be combined:
+
+```text
+Crt
+Ripple
+Glitch
+```
+
+They share one full-scene shader pass in SDL and macOS. With all three off the
+pass is bypassed. CRT works in linear light with restrained scanlines, mask,
+bloom, curvature, and noise rather than remapping the theme to a strong fixed
+palette; Ripple and Glitch primarily perturb sample coordinates.
+
+`EffectCode <effect-builtin>` opens the build-embedded effect math, host
+paint/submission path, and backend shader/grid sources, for example
+`EffectCode PanelAscii` or, in a GUI build, `EffectCode Crt`. TTY exposes it
+for its grid transitions; native GUI builds
+expose it for transitions and scene shaders. It is absent on web, where no
+effect argument could succeed. Shared
+passes are shown as shared source segments rather than manufactured per-effect
+copies. The command works from an installed binary and does not need the source
+checkout beside it. SDL output also labels its shader provenance. An ordinary
+build prints the live GLSL that `glslc` compiled for that executable;
+`-Dprebuilt-shaders` prints the tracked GLSL snapshot paired with the committed
+SPIR-V instead and labels those segments with their `shaders/prebuilt/` paths.
+`zig build shaders` refreshes both files of every pair together,
+so editing live GLSL without that explicit refresh changes neither half of a
+prebuilt executable.
+
+## Delayed Look preview
+
+The preview is enabled by default. Moving the pointer onto selectable text and
+leaving it still for `look_preview_delay_frames` (2 animation ticks, roughly
+33 ms at the 60 Hz animation cadence) paints a
+subtle theme-derived preview of the exact operand a right-click Look would receive.
+Repeated motion reports in the same semantic grid cell do not restart the
+delay. The preview uses the same side-effect-free word/path expansion as Look;
+it does not focus a pane, move a cursor, install a selection, activate a PDF
+page, or execute anything. Motion to another operand, pointer leave, input,
+pane teardown, and relevant content changes cancel it.
+
+Set this compile-time option in `src/config.zig` to disable the feature:
+
+```zig
+pub const look_preview_delay_frames: ?u16 = null;
+```