summaryrefslogtreecommitdiff
path: root/docs/render-pipeline.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/render-pipeline.md')
-rw-r--r--docs/render-pipeline.md949
1 files changed, 44 insertions, 905 deletions
diff --git a/docs/render-pipeline.md b/docs/render-pipeline.md
index c04ccd33..49180ad3 100644
--- a/docs/render-pipeline.md
+++ b/docs/render-pipeline.md
@@ -1,915 +1,54 @@
-# pardes render pipeline: one frame, one clock, one order
+# pardes render pipeline: the core's frame, then the frontend's own
-Status: DESIGN, FINAL (draft 2 plus the adversary's two convergence fixes; converged with the adversary; the adversary's 17 objections to draft 1 are folded in, each marked "draft-2 fix" where it changed the design). Nothing here is implemented. Line numbers are
-the working copy of 2026-09-28 (`losuylsy`, mid tag→Text refactor; they drift).
+What a frame is and who draws it, as it stands. The effects programme this
+document planned (eleven panel transitions in two tracks, a Shadertoy post
+chain with Crt, Bloom, Vignette and Grain, Lift and its soft shadows, the
+glows, the terminal's chip shadow and thumb flash, the lapis ornament and
+its parallax, the message fall and dissolve, the theme crossfade, five
+Motion flavours with anticipation and squash, tiers and track groups) is
+gone: the core keeps no motion and no clock but its deadlines, and each
+frontend keeps the little it draws on its own.
-Goal, in the user's words: an algorithm for the ordering of rendering, how each
-part is selected and joined, the shader passes after that, and one animation
-model. Consumers: the lapis theme (shader effects on specific parts), multi-line
-tags, the full-screen post pass (now Shadertoy-compatible), images/PDF, and
-animations. Added requirements: a game-quality GUI effects catalogue, a separate
-terminal effects track (audit + new cell-native effects), and a motion / colour /
-performance / "feel" discipline.
+## The core's frame
----------------------------------------------------------------------------------
+- `Pardes.pump` drives the host: `wait_input`, with the core's next
+ deadline (`nextWake`: a message's linger, the look-hover preview, a
+ question's hint, a paused Grep, work that resumes a frame at a time);
+ `now`; `poll_frame`; `render` and `present` only when a frame is owed
+ (`needs_frame`); and `post_present`, whose `Pardes.presented` lets a
+ drag's moving end and a look-hover follow what is under the pointer now.
+- `advance(now)` steps `.tick`s a `frame_ns` (16 ms) at a time, for the
+ work that resumes a frame at a time; a wait is jumped in one step.
+- `render` (draw.zig) paints one `Surface`: the canonical grid (`/screen`,
+ the snapshot goldens, the tty), the regions (each part's rectangle,
+ owner and focus; a body's first line and the text it shows,
+ `Region.line` and `Region.doc`), the layers a pixel shell draws at the
+ tagline's pitch and with compact context rows, the images, the cursor
+ and the palette (`Chrome`). Nothing on it moves.
-## 1. Today's frame, end to end
+## The frontends' own
-### 1.1 Who drives a frame
+Each draws these on its own clock, from the Surface alone, and draws their
+frames itself while they move (the last frame again: the tty's
+`poll_frame`, the window's loop), pacing its own waits:
-`Pardes.pump` (pardes.zig:4607) is the only loop body every shell runs:
-`wait_input(timeout = animationActive ? 16 : 0)` → queued events → `update` →
-effects → `poll_frame` → **skip unless `needs_frame or animationActive()`** →
-`frame_arena.reset` → `render` → `present` → `needs_frame = present_skipped` →
-`post_present`.
-
-Ticks (`Event.tick`) are produced by six different clocks:
-
-| shell | who ticks | cadence |
-|---|---|---|
-| tty | `tickWatch` thread: nanosleep 16 ms **after** the wait asked, then `postEvent(.tick)` (tui.zig:1513) | 16 ms + frame time: drifts slow, worse over ssh |
-| gui | `AnimationClock.due` in `postPresent` re-arms `now+16ms` (gui.zig:203, 221, 4095) | a tick only once ≥16 ms have passed since the re-arm: at 144 Hz every 3rd frame (20.8 ms) → animations ~25% slow; at 120 Hz every 2nd; a slow frame slows them further |
-| gui grid mode | every `poll_frame` while active (gui.zig ~4114) | as fast as the loop |
-| web | JS rAF fixed-step bank, capped (app.mjs:566) | correct average rate, always ticking |
-| macOS | `spendTickTime` bank (macos.zig:868, 1549) | correct average rate |
-| detached server | after a timed `poll` (server.zig:816, 828) | ≥16 ms |
-
-So the same animation runs at different speeds per shell. Everything counts
-16 ms frames (`layout.Animation.frame_ms`, layout.zig:2041).
-
-Acknowledgement is also per shell: tty `postPresent` acks the tracks it drew
-(tui.zig:1187), GUI acks then ticks (`finishPresentedAnimationFrame`), grid mode
-acks `&.{}`, macOS acks via `pardes_frame_presented`, **web never acks**.
-
-### 1.2 Core render (`Pardes.render`, pardes.zig:5950), in code order
-
-1. `File.refreshHighlights`; size the grid; reset cursor/pointer shape, **clear
- every cell's hover bit** (5979 — stale state that exists only because paint
- passes do not own their output), zero layers/images/tracks.
-2. Fill the whole screen with `chrome.border` (5991).
-3. Per pane: `collectNotices` → `renderPane` (6580): `clearRect` + page fill
- ("two full passes over every cell in the pane", 6596) → grip → `paintPaneTag`
- → PDF / image / `renderBody` (+scrollbar) → `renderBodyLayer` (body_layer.zig:243)
- which **renders the whole body again** into a temporary Surface by
- `std.mem.swap(Surface, &p.surface, &temporary)` (body_layer.zig:266-272).
-4. Notice chips painted on the grid (6000-6065).
-5. Workspace tag, column tags, their hover word and header selection/caret on
- the grid (6068-6155).
-6. `renderTagLayers` (6396): **paints every pane tag a second time** into a
- temp Surface via the same swap (6414-6419); builds notice layers (re-deriving
- chip geometry, text, caret the grid pass already computed) and column /
- workspace layers (`renderHeaderLayer` 6520, which re-does hover and header
- selection).
-7. Drag overlays (`overlayDash`, glyph-only rewrites, 6158); the column-move
- rail shrinks layer viewports by one cell so the rail stays visible.
-8. Debug box (6244).
-9. `presentation.submit` (6301): tracks, previous grid, per-cell diffs.
-10. `composeAsciiTransitions` (6305): character effects composed in the core
- into an arena copy of the cells.
-
-Implicit orderings that matter and are written nowhere: body layers before tag
-layers (notice chip over a context band); images after cells, which is why an
-image pane "gives up the rows" under its notices (6629) instead of having z;
-tag layer array index order (panes, columns, workspace, notices) is paint order.
-
-### 1.3 Surface: what the shells get (surface.zig)
-
-`cells` (the canonical grid), `cursor`, `pointer_shape`, `images`
-(`ImagePlace`, with `patch` rows), `body_layers[16]` (compact context rows +
-body rows), `tag_layers[MAX_TAG_LAYERS]` (one row each; the tag refactor just
-added `line` — one layer per tag line), `panel_tracks`, `previous_*` + `cell_diffs`
-while a transition needs them, `mark_hover` (a flag that makes `Surface.at`
-set `cell.hover`, 378-385 — a side channel for macOS glass).
-
-### 1.4 Shells
-
-- **tty** (tui.zig:1100): `panel_compositor.compose` rewrites cells for
- slide/zoom/dissolve/vertical → `paintCells` (win.clear + every cell) → kitty
- images (hidden while geometry moves) → cursor → `vx.render` (vaxis diffs
- against its last screen, wraps in sync 2026). Layers are ignored.
-- **gui** (`renderFrame`, gui.zig:5035): one render pass. `makePaintPlan`
- (2048) = one batch per active track + static batch. Per batch: grid cells not
- covered by a layer (`coverLayers` 5656) → body layers → tag layers → previous
- layers/cells for transitions → that batch's images. Then the overlay
- (`buildOverlay` 7258: pet, topbar rule, column rule, bottom fill, pane chrome
- 7468, grips 7543, bar cursors, touch). Then optional crt pass scene_tex →
- swapchain (5439). Cell = one instance drawing bg + glyph (ui.frag.glsl).
-- **web**: DOM spans for the grid + absolutely positioned divs for tag and body
- layers. No images, tracks, scene; never acks.
-- **detached** (wire.zig, `version = 7`): cells + body/tag layers, delta coded.
- A GUI attached client has `core == null` → no pane chrome (appendPaneChrome
- reads `core.rects`): a per-shell divergence caused by the shell reading core.
-- **macOS** (out of scope): its own copies of tag/body layer ABIs, its own
- tick bank, Metal crt.
-
-### 1.5 Duplicated logic, smells, bugs
-
-1. Paint twice: pane tags (grid + layer), bodies with context rows (grid + layer),
- notices (grid + layer, text/geometry/caret recomputed), workspace/column tags
- and their hover/selection/caret (grid + layer). The two copies already
- disagree: a notice layer highlights the hovered word, the grid chip does not;
- the column-tag grid hover is suppressed during `column_move`, the layer's is not.
-2. `std.mem.swap(Surface, &p.surface, …)` as the way to "paint into something
- else": every paint function writes `p.surface` directly.
-3. Geometry recomputed everywhere: `tag_y = if tag_bottom …` appears in
- renderPane, paintPaneTag, renderBody, renderTagLayers, appendPaneChrome,
- taglineBaseRgb; `bodyTop`; BOX_H == 1 assumed throughout (multi-line tags
- break all of these).
-4. The GUI infers semantics from painted cells: scrollbar thumb from
- `cellBackgroundIs(scroll_thumb)` (7468ff), topbar rule from "row 1 has a
- tagline cell" (5509), bottom band (5519), grips from tagline cells
- (`paneGripCell` 5872), focus tint recomputed from `core.active`
- (`taglineBaseRgb` 5609). Any theme where two roles share a colour breaks it.
-5. Six clocks (1.1), four ack sites, and a web that never acks.
-6. `animationActive` (5884) is true while crt/ripple/glitch are on → the whole
- core render (double paints included) and `capturePrevious` run every 16 ms
- for a time-only uniform.
-7. `acknowledge(&.{})` → `capturePrevious` memcpys all cells and all layer
- cells on **every idle presented frame, even with `panel_transition = .off`**
- (layout.zig:283-290).
-8. A lingering message (`message_linger_ms`) keeps `needs_frame` true every
- tick for its whole linger (Messages.zig:238-250): seconds of full 60 Hz
- renders that change nothing. Look-hover delay likewise ticks every frame.
-9. `Animation.Transition.retarget` (layout.zig:2064) restarts from the displayed
- value with step 0: position continuous, velocity snaps to zero.
-10. Colour fades mix sRGB bytes (`interpolateRgb` layout.zig:2111,
- `Messages.blendRgb`, `colors.mix`): muddy mid-fades.
-11. Shell-side animations each have their own time: crt uniform
- (`SDL_GetTicksNS`), pet (`SDL_GetTicks`), smooth scroll lag (per poll),
- touch flash (per rendered frame), macOS coasting.
-12. `mark_hover` hack and the hover-bit reset (1.2 step 1).
-
----------------------------------------------------------------------------------
-
-## 2. Principles
-
-1. **Core decides WHAT and WHERE; shells decide HOW.** The core emits an ordered
- region list with geometry, z, and resolved styles. No shell reads
- `core.rects`, `core.active`, settings or theme to decide what something is.
-2. **Paint once.** Every part is painted exactly once, into its own target; the
- grid is produced by joining those targets.
-3. **One clock.** Time is the shell's monotonic `now_ns`, passed in; the core
- never reads a clock. Animations are functions of `now - start` (tweens) or
- closed-form springs, never frame counters.
-4. **A fixed, named order**, written as straight-line code in one function per
- side. No pass objects, graphs or vtables.
-5. **Zero cost when off; zero work when idle.** A disabled effect emits nothing.
- Idle means the earliest deadline is "never".
-6. **Decorations never change cell geometry.** Grid, hit testing, 9P cells and
- snapshot goldens are unaffected by any GUI effect.
-
----------------------------------------------------------------------------------
-
-## 3. The frame
-
-### 3.1 Loop (pump, all shells)
-
-```
-pump(h, now_ns):
- wait_input(timeout = min(core.nextWake(now), shell's own next wake))
- drain events → update ; drain effects → perform
- core.advance(now) // settles animations whose time passed; sets
- // needs_frame if something core-visible moved
- poll_frame
- if needs_frame or core.running(now):
- render(now) → present → if present said "shown": core.acknowledge(tracks)
- else if shell has a presentation-only animation:
- shell redraws at level A (post chain only) or B (decor only), §5.5;
- no core render, no cell-instance rebuild
-```
-
-`animationActive: bool` becomes `nextWake(now) ?u64` (null = idle, 0 = run
-every frame, >0 = sleep until). `acknowledge` moves into `pump` (present returns
-whether it showed the frame); the four shell ack sites and GUI's
-`finishPresentedAnimationFrame` go. `capturePrevious` runs only when
-`panel_transition != .off`.
-
-### 3.2 Core `render` (moves to `src/draw.zig`, `pub const render = draw.render`)
-
-Straight-line, in this order:
-
-```
-render(p, arena, now):
- 0. BEGIN size grid; reset regions, layers, images, cursor, tracks
- 1. PLACE compute every part's rect ONCE and append a Region, in z order:
- page; per pane: body, tag (h = tag lines), grip, rail(+thumb),
- notices; per column: tag + grip; workspace tag; drag overlays;
- debug box; cursor
- 2. PAINT for each region: paint its cells once into its target — its
- layer (tags, notices, bodies with compact rows) or the grid
- 3. JOIN copy each layer's grid-visible cells into the grid at its
- viewport, in region order → the canonical grid (tty/9P/wire)
- 4. GRID-ONLY glyph-only overlays (drag dashes) and the debug box on the grid
- 5. PRESENT presentation.submit (tracks, diffs); region tier from role
- and track phase (§3.4)
- 6. STYLE resolve region styles: lift, dim (focus animation), the
- theme's decor per region kind, style_alpha, per-pane view origin
-```
-
-Paint functions take the target `s: *Surface` instead of writing `p.surface`
-(mechanical signature change through body_layer, File, Terminal, Image, Pdf);
-the swap hack and the second tag/body/notice paint are deleted. Where the
-old grid and layer copies disagree, **the grid's behaviour wins** so goldens
-stay byte-identical. Every disagreement is listed in the change and decided
-on its merits later (e.g. the column_move hover suppression is right for both;
-notice-word hover could go either way). JOIN traps: (a) a wide grapheme at the
-viewport's right edge. `print` drops a width-2 glyph that does not fit
-(`col + 1 >= end`), but the layer has columns beyond it, so the copy must
-re-clip at the edge and never leave a head without its spacer. (b) The body
-layer's first `r.h − tag_rows` rows must equal today's grid rows with
-`tag_bottom` both on and off (`first_row`, body_layer.zig ~275).
-
-### 3.3 Which parts render, and from what
-
-- A region is emitted iff its rect intersects the screen and its owner is
- visible (collapsed pane → tag region only).
-- Pixel shells draw a region **from its layer if it has one, else from the grid
- cells in its rect**. The page region draws only grid cells no other region
- covers (today's `coverLayers`, generalised to regions).
-- Cell shells (tty, detached tty) draw the grid; layers exist only for pixel
- shells.
-
-### 3.4 Composition order (GUI): fixed tiers by ROLE
-
-A region's tier comes from its **role** and is fixed for the frame. Animated
-elevation (`Region.lift`, 0..1) only drives shadow offset, σ and strength, so
-nothing changes draw order partway through a lift (draft-2 fix: an animated
-`z` whose floor is the tier makes the draw order pop mid-animation).
-
-| tier | role | overlap inside the tier? |
-|---|---|---|
-| 0 | page, static panes, their chrome (rails, grip marks, rings, rules) | no |
-| 1 | the active pane (only when focus lift is on) | no |
-| 2 | panes moving/opening in a transition | **yes**: split per track, in `paintOrder` |
-| 3 | closing tombstones (frozen previous cells) | **yes**: split per track |
-| 4 | floating: notice chips, debug box, drag preview | no |
-| 5 | true overlays: cursor, touch/pet (debug) | no |
-
-A pane's own chrome (rail, grip marks, rings, rules) is decor of the pane's
-tier and carries its track transform, so it moves with the pane. Today it is
-hidden during transitions (`transient_on`, gui.zig ~7299) because it doesn't
-move. Only real overlays live in tier 5.
-
-Straight-line GUI draw, one render pass:
-
-```
-for tier 0..5:
- for each group in tier // one group per tier, except tiers 2 and 3:
- // one group per track, in paintOrder
- decor-under fills, patterns, rings under content [decor]
- cells bg + glyph; text-shadow regions in 3 phases [ui]
- images the group's images [image]
- cast shadows this group's shadows, darken-only, each with
- its caster's rect as an exclude rect [decor]
- decor-over rings over edges, rails, rules, grip marks [decor]
-post chain (§6) → present
-```
-
-Why cast shadows come AFTER cells (draft-2 fix): static panes share tier 0. If
-the shadow were drawn before the tier's cells, the neighbour's opaque cells
-would paint over a shadow cast onto its gutter or tag row, which is exactly the
-lapis case. Each shadow instance discards inside its caster's rect, so it only
-darkens what lies beside or under it. An elevated tier's shadow onto lower
-tiers works the same way.
-
-Draw calls: ≤ 5 per group. Tiers 0, 1, 4 and 5 are one group each, so ~20 draws.
-Tiers 2 and 3 add ≤ 16 groups, and only while a transition runs. Empty draws are
-skipped. The per-track batching that exists today (PaintPlan) survives only in
-tiers 2 and 3, as groups. The vertical effect's scissor becomes a per-instance
-clip rect. A notice chip (tier 4) ends up above an image, so the image pane can
-stop "giving up the rows" (its own visual-change step).
-
----------------------------------------------------------------------------------
-
-## 4. Data the core hands the shells
-
-Additions to `Surface` (all POD, fixed-size):
-
-```zig
-pub const Region = struct {
- kind: enum(u8) { page, body, tag, grip, rail, column_tag, workspace_tag,
- notice, overlay, debug },
- pane: u8 = none, column: u8 = none, serial: u32 = 0,
- rect: Rect, // grid cells: the hit-test geometry
- tier: u8 = 0, // fixed by role (§3.4)
- lift: f32 = 0, // animated elevation 0..1: shadow only
- dim: f32 = 0, // 0..1 pull toward the page (unfocused)
- layer: u16 = none, // layer index, or draw the grid cells in rect
- style: u8 = 0, // index into Surface.styles (0 = plain)
- style_alpha: f32 = 1, // decor weight; theme crossfade (below)
- active: bool = false,
- thumb: struct { y: u16, h: u16 } = .{}, // rail only
-};
-regions: [MAX_REGIONS]Region, nregions: u16,
-styles: [8]Style, // resolved per frame from theme + settings
-view: [MAX_PANES]struct { serial: u32, top_line: i32, wrap_at: i32 }, // ABSOLUTE per-pane view origin (§5.4)
-```
-
-`Style` holds a theme's decor for one region kind. Hard-edged geometry is in
-**logical pixels** and snapped to whole device pixels by the shell (logical px ×
-display scale, rounded): ring widths, pattern periods, hard-shadow offsets.
-Lapis is pixel art (2/3/1 px rings, 6 px checker, 5-6 px hard shadow). In
-fractional cell units those would blur and change with font size (draft-2 fix).
-Fields: `fill`, `ring[3] {px, rgba}`, `pattern {none|checker|stripes|dots, px,
-duty, a, b, see_through}`, `hard_shadow {dx_px, dy_px, rgba}`, `text_shadow
-{dx_px, dy_px, rgba}`. Soft elevation shadows are not per style. They come from
-`lift` and one global `shadow {rgba, σ_px, offset_px}` per theme.
-
-`see_through`: a region style with an under-pattern (the lapis dot grid under
-pane bodies) marks page-coloured cell backgrounds as clear, using the existing
-ui.frag clear-bg flag (0x40000000), so the pattern shows between glyphs. In a
-tiled layout the page region is almost never visible, so the pattern has to sit
-under the bodies.
-
-Theme crossfade: switching into or out of a decorated theme fades
-`style_alpha` from 0→1 or 1→0 over the same Tween as the colours. Decor never
-snaps while colours fade. Schema: `decor` is an optional field on `Theme`. The
-comptime `fold` and the ZON ThemeFile parser (colors.zig:266) both walk the
-same struct, so theme files get decor with no separate schema. Lapis ships
-compiled in first.
-
-Layers: once the tag refactor lands, `TagLayer` and `BodyLayer` merge into one
-`Layer { kind, id, serial, viewport, cols, rows, compact_rows, cells, cursor
-{x,y,bar}, bg, slide, fade, separators }`. A tag is all compact rows. A body is
-`context_rows` compact rows followed by body rows. A notice is one compact row.
-There is one `rowTop/rowHeight/hitAt`. Multi-line tags are `rows > 1`, which
-replaces the refactor's one-layer-per-line `line` field. This is the only part
-that touches the other agent's files, and it waits for them.
-
-Time: `Surface.now_ns`, the core's time for this frame.
-
-Wire: regions and styles go over the detached wire (`version` 7 → 8). The
-attached GUI then draws chrome from them, which fixes the core==null
-divergence. Web ignores the new data at first. Its lapis could later map styles
-onto CSS box-shadow, borders and gradients, a natural fit since the reference
-IS CSS.
-
-Deleted from the shell once regions exist: `taglineBaseRgb`,
-`topbarPaneBorderHeight`, `bottomTaglinePresent`, the scrollbar inference in
-`appendPaneChrome`, `cellBackgroundIs`, `paneGripCell`'s scan, and `mark_hover`.
-The hover affordance becomes an `overlay` region.
-
----------------------------------------------------------------------------------
-
-## 5. Region effects on the GPU
-
-### 5.1 One decor pipeline, instanced
-
-New `shaders/decor.{vert,frag}.glsl`. Each decoration is one instance:
-`{ rect_px, clip_px, exclude_px, kind, params vec4, color0..2 (premultiplied),
-transition header (the same fields as CellInstance) }`.
-
-- **Hard-edged kinds, no AA, snapped edges**: `solid`, `ring` (up to 3 inset
- rings), `checker`, `stripes`, `dots`, `hard_shadow`. Rules, rails and grip
- marks become `solid` decor emitted from regions. Because they are snapped and
- un-anti-aliased, stage 8's "PPM goldens byte-identical" is achievable.
-- **Soft kinds, fwidth AA, dithered**: `soft_shadow` (a rectangle convolved
- with a Gaussian in erf closed form, as Wallace and GPUI do: one quad grown by
- 3σ, no blur pass), `inner_shadow`, `glow`, and `cursor` (rounded corners).
- Wide gradients get ±0.5/255 interleaved-gradient-noise dither.
-
-The triangle overlay pipeline stays only for the pet and the cursor's glide.
-
-### 5.2 Shadows and gamma
-
-A pane's right and down shadow lands on its neighbour's gutter or tag row
-(chrome), because pane rects tile. With `tag_bottom` it lands on the first body
-row instead, which is simply what a shadow does. §3.4 guarantees it is drawn
-over the neighbour and never over the caster.
-
-Gamma decision (draft-2 fix, one rule instead of two). Decor blends on the
-UNORM target, so blending happens in sRGB space, as CSS does.
-- Dark shadows: alpha is pre-warped so the result matches linear light,
- `a' = 1 − (1 − a)^(1/2.2)`. This is exact for black.
-- Coloured decor (glows, selection halo, tinted shadows) is capped at ≤ 25%
- alpha, where sRGB-space falloff is only slightly dark. That is documented, and
- it is accepted by the feel review, not by maths.
-- Opaque decor (lapis hard shadows, rings) has no gamma issue.
-- Measured experiment in the fx set: render the scene into RGBA16F linear
- (ui.frag writes a linearised `mix(bg,fg,a)`, so glyphs look identical) and add
- one encode pass that also produces the sRGB iChannel0. It is adopted only if
- its cost at 4K on the iGPU fits §8.3.
-
-### 5.3 Text shadow
-
-Only for regions whose style has `text_shadow` (lapis titles). The region's
-cells are emitted in three phases in its group: all bg instances (glyph = the
-space slot), then shadow glyph instances (offset, shadow colour, clear bg), then
-glyph instances (clear bg). Every other region keeps its single bg+glyph
-instance. Within a group, bodies come before tags, so a tag's shadow can hang
-over the body's top edge.
-
-### 5.4 Cursor (shell-owned presentation)
-
-The cursor is decor in tier 5, not a reversed cell. It is a quad whose 4 corners
-follow the target on critically damped springs. The leading corners are stiffer
-than the trailing ones, which gives a smear along the motion that collapses at
-rest.
-- **Distance rule** (draft-2 fix): a move of ≤ 1 cell, or any move in insert
- mode, snaps or settles in ≤ 40 ms. Only jumps glide (90-150 ms), as neovide
- does. At key-repeat rate (~33 ms per cell) a 120 ms spring would trail 3-4
- cells behind and feel sluggish.
-- **Scroll-aware**: the core exposes each pane's ABSOLUTE view origin
- (`view[pane]`: serial, first line, wrap offset). The shell diffs it against
- the origin it last drew and shifts its spring state by the difference in
- pixels, so the cursor does not glide against text that jumped. It is absolute,
- not a per-frame delta, because frames get dropped: the detached server skips
- clients with pending output (server.zig ~712), and a GUI can skip a present.
- G6 smooth scroll uses the same origin.
-- **Legible during the glide**: glyphs under the quad are re-emitted in the
- cursor-text colour, clipped to the quad (per-instance clip), as neovide does.
-- **Geometry**: the pixel rect comes from the layer the cursor sits in (body
- layer compact rows, or tag layer pitch plus band offset), not from `cols × cell_w`.
-- **Blink**: default OFF, as pardes never blinked. When on, it is a square wave
- with an ~80 ms ease at each edge, so it redraws only at the edges, held solid
- while typing and for 500 ms after, and it stops after 10 s idle.
-
-### 5.5 Presentation-only redraw levels (draft-2 fix: zero idle cost must be real)
-
-| level | trigger | work |
-|---|---|---|
-| A: chain only | iTime or ShaderAnimation, scene unchanged | re-run only the post chain from the retained `scene_tex` |
-| B: decor only | cursor glide, blink edge, hover fade | reuse the uploaded cell vbuf and image draws; rebuild and upload the decor instances AND the cursor-legibility glyph instances (the glyphs under the cursor quad in cursor-text colour, ui pipeline, clipped to the quad); redraw the scene, then the chain |
-| C: core frame | `needs_frame` or a core animation | full render and instance build |
-
-Cell instances are rebuilt only at level C. With a chain active, the cursor
-lives in the scene, so cursor motion is level B, not A (a documented choice:
-iCurrentCursor shaders still get exact uniforms).
-
-### 5.6 tty / web / wire
-
-GUI decor is GUI-only. The tty realises nothing from `styles` beyond the colours
-that are already in cells; its own effects are in §9.2. Web ignores the new
-data. The wire carries regions and styles so an attached GUI draws the same
-frame.
-
----------------------------------------------------------------------------------
-
-## 6. Post passes: a Shadertoy-compatible chain (GUI)
-
-Mirror ghostty 1.4.0 (`zig-pkg/ghostty-*/src/renderer/shadertoy.zig`,
-`shaders/shadertoy_prefix.glsl`, `generic.zig:2106-2230, ~1692`):
-
-- **Source format**: user file with `void mainImage(out vec4 fragColor, in vec2
- fragCoord)`, untouched. pardes prepends its OWN prefix with ghostty's exact
- uniform names, types and std140 order (iResolution, iTime, iTimeDelta,
- iFrameRate, iFrame, iChannelTime[4], iChannelResolution[4], iMouse, iDate,
- iSampleRate, iCurrentCursor, iPreviousCursor, iCurrentCursorColor,
- iPreviousCursorColor, iCurrentCursorStyle, iPreviousCursorStyle,
- iCursorVisible, iTimeCursorChange, iTimeFocus, iFocus, iPalette[256],
- iBackgroundColor, iForegroundColor, iCursorColor, iCursorText,
- iSelectionForegroundColor, iSelectionBackgroundColor; CURSORSTYLE_* defines;
- `#define texture2D texture`), but SDL GPU bindings: `iChannel0` at set 2
- binding 0, the block at set 3 bindings 0 to 2 (cut before and after
- iPalette: SDL GPU binds at most 4 KiB of a block, so one block left
- the colours after the palette at zero until G4), pardes's own at 3. `main()` calls
- `mainImage(_fragColor, gl_FragCoord.xy)`. Trap found: ghostty's Zig
- `Uniforms` (shadertoy.zig:13) orders selection_background before
- selection_foreground while its GLSL block orders Foreground before Background,
- so in ghostty the two arrive swapped. pardes fills by the GLSL names (the
- documented meaning); a unit test checks our Zig mirror's std140 offsets
- against the prefix (≈4.6 KB block, pushed with SDL_PushGPUFragmentUniformData).
-- **Y is down**, exactly like ghostty on Metal (`custom_shader_y_is_down`):
- fragCoord, iChannel0 UV and cursor uniforms share one top-left space, no flip.
- `iCurrentCursor = (left x, BOTTOM-edge y, w, h)` in framebuffer pixels (the
- "+Y edge" rule community cursor shaders rely on). Directional shaders appear
- flipped versus Linux ghostty (OpenGL, y-up); documented, not emulated.
-- **Chain**: a list of paths, run in order; ping-pong two UNORM textures
- (cleared to 0), the last pass writes the swapchain. iChannel0 holds
- sRGB-encoded values (scene_tex and swapchain are UNORM today — keep it so; if
- the scene ever moves to an _SRGB/float target, encode before the chain). Empty
- chain → render straight to the swapchain, no scene texture (today's cost).
-- **Uniform sources** (shell): iTime since the first post frame, iTimeDelta
- between draws, iFrame per draw (ghostty semantics, shell wall clock); iMouse =
- real Shadertoy mouse (superset; ghostty leaves it 0); cursor rect/colour/style
- from the region cursor (5.4 geometry), iTimeCursorChange stamped when rect or
- colour changes; iFocus/iTimeFocus from window focus events; palette,
- background, foreground, selection from the theme.
-- **Alpha**: forced to 1 unless WindowOpacity < 100 (then passed through
- premultiplied). Transparent grounds keep working.
-- **Input mapping**: identity. The bundled CRT has NO geometric distortion
- (beam-profile scanlines, aperture mask, bloom, vignette), so input stays exact.
- Barrel exists only in user shaders, with the drift documented: 1.6% is ~30 px,
- ≈3 cells, at the corners of a 4K screen, where the grips and rails are.
- `crt.zig` is deleted. If the user insists on barrel in the bundled CRT, keep
- `crt.zig`'s inverse keyed to "bundled crt active".
-- **Compile** (decision 3): a user's file is compiled by spawning `glslc` with
- the build's own flags, prefix and file on its stdin, SPIR-V on its stdout
- (no file of ours anywhere; std's spawn allocates before fork), on a thread of its own when the file joins the chain, never on the
- frame path; the result is taken in at the next loop step. The prefix ends in
- `#line 1`, so glslc's errors count the file's own lines, and they name the
- file, not `<stdin>`. Level A redraws once a refresh of the window's display. A failed compile keeps the file's last good
- pipeline and says glslc's first line as a message; glslc missing is said
- once, and only files stay off (the bundled passes are compiled with the
- build, through the same prefix). The files' directories are watched
- (file_watch shader slots): a change there has each file read and hashed,
- and one whose bytes moved compiles again; the same bytes (good or bad)
- compile nothing and say nothing twice. The process that holds the core
- compiles (ShaderBuild.zig): a local GUI, or a detached session, which
- sends its attached GUIs the chain with each file's SPIR-V (wire `post`,
- on attach and on every change), so an attached GUI runs the same passes,
- levels and ShaderAnimation as a local one and still reads no disk and runs
- no program.
-- **Animation mode**: `ShaderAnimation off|on|always` (ghostty's
- `custom-shader-animation`): off = redraw only when content changes; on =
- continuous while the window is focused; always = continuous. Continuous means
- the shell redraws its retained Surface (3.1), never a core tick or render.
-- **Existing crt** becomes a bundled Shadertoy file in `shaders/post/` under
- the same builtin; `scene_effects` and `crt.frag.glsl`/`crt.zig` are deleted.
- It takes a level, `Crt 0..3` (0 off, `on` the default 2, `off` and bare
- still work), passed as `pardesLevel`: 2 is the polished rewrite, 3 at least
- as strong as the old CRT (pixels changed by more than 8 in a channel against
- a plain frame: 18.3% vs 17.4%). Ripple and Glitch were rewritten too, then
- removed at the user's word after a live look (decision 8). The chain is
- `Crt` and `Shader <path>` in the order they were put in
- (`Shader off` empties it of files), `ShaderAnimation off|on|always`
- (default on). The core keeps no clock for it: level A redraws are the
- shell's.
-- macOS (out of scope) would need spirv-cross → MSL, as ghostty does.
-
-Region filters (e.g. "tint/blur one pane") are NOT built. If one is ever needed:
-one post pass reading a uniform array of ≤16 region rects+kinds, not a pass per
-region.
-
----------------------------------------------------------------------------------
-
-## 7. Animation model
-
-### 7.1 Time
-
-- The shell's monotonic `now_ns` is the only clock. It enters the core with each
- `pump` (and a `.tick = now_ns` event for shells without pump, e.g. esp32).
- Tests inject a fixed clock: a helper steps `now` by 16.67 ms.
-- Two domains, one clock:
- - **core animations** (change what hit-testing or the grid show, or state):
- panel geometry, message life, notice slide/fade, look-hover delay, chrome
- theme crossfade, focus lift/dim. Stored in the core, deterministic in tests.
- - **presentation-only animations** (never touch core state): cursor glide/
- trail/blink, shader iTime, smooth-scroll pixel offset, pet, touch flash.
- Owned by the shell, redraw the retained Surface, never tick the core.
-
-### 7.2 Two primitives, closed form
-
-```zig
-Tween { start_ns, duration_ns, from, to, curve } // value = lerp(from,to, curve(t))
-Spring { start_ns, x0, v0, target, omega } // critically damped:
- x(t) = target + (c1 + c2 t) e^{-ωt}, c1 = x0-target, c2 = v0 + ω c1
-```
-
-Both are pure functions of `now`: frame-rate independent, free catch-up after a
-sleep, no per-tick `advance` loops. Retarget: a Spring evaluates `(x, v)` at now
-and restarts from them (velocity kept); a Tween retargets from the displayed
-value with an ease-out curve (starts moving at once, no ease-in stall).
-Colours interpolate in OKLab (small CPU function), not sRGB bytes.
-
-Settling (draft-2 fix: a critically damped spring never reaches its target).
-Each quantity has an end rule: position springs end when |x − target| < 0.5
-device px and |v| < 1 px/s, lift/elevation when < 0.002, and then they snap to
-the target and stop. A test checks that `nextWake` returns null after settle.
-A Tween ends at `start + duration`.
-
-### 7.3 Idle and wakes
-
-`nextWake(now)` is ONE straight-line function listing every core animation
-(the same list `advance` settles):
-
-- running tween/spring → 0 (frame now)
-- holding phase (message linger, look-hover delay) → its end time
-- nothing → null
-
-Shells wait `min(core wake, own wake, input)`. A lingering message now costs
-zero frames until it starts to dissolve. `advance(now)` performs the state
-changes at phase ends (message entering→shown→lingering→leaving→removed,
-track done → drop, hover wait → preview) and sets `needs_frame` only when
-something visible changed.
-
-### 7.4 What each animation becomes
-
-| today | becomes |
-|---|---|
-| `ChromeAnimation` 10 steps sRGB (colors.zig:192) | Tween, 200 ms, OKLab, ease-in-out; retarget ease-out |
-| panel `Track.frame` counters (layout.zig:1583) | geometry Spring per track (retarget-safe); content crossfade Tween |
-| `MessageLife.frame` (Messages.zig) | phase + start_ns; motion from Tween curves |
-| look-hover wait frames (look.zig:902) | deadline |
-| GUI `AnimationClock`, tty `tickWatch` cadence, web `animationTicks`, macOS `spendTickTime`, detached tick | deleted; each shell passes `now_ns` and sleeps to `nextWake` |
-| crt time uniform, pet, touch flash, scroll lag | shell-owned, same now_ns source |
-
----------------------------------------------------------------------------------
-
-## 8. Motion, colour, performance, feel (both tracks)
-
-### 8.1 Motion spec
-
-| class | examples | curve | duration |
-|---|---|---|---|
-| micro-feedback | hover affordance, button/word highlight, selection appear | ease-out (cubic) | 80–120 ms |
-| follows input | cursor, smooth scroll, drag preview, pane geometry under interaction | critically damped spring | settles 90–150 ms (cursor), 180–260 ms (layout) |
-| arriving | notice drop-in, pane open | ease-out (cubic / quint), no overshoot | 150–220 ms |
-| leaving | notice dissolve, pane close | ease-in (cubic), shorter than arriving | 100–160 ms |
-| state change | focus lift/dim, theme crossfade | ease-in-out (smooth) | 150–250 ms |
-| anything > 300 ms | — | must be justified in the feel review | — |
-
-Rules: leaving is faster than arriving; nothing overshoots at text scale
-(a 2 px bounce reads as jitter); interruptions retarget (7.2), never snap or
-restart from zero; **input is never gated**: hit testing uses logical geometry
-(`presentation.pointer` already does), keys act on the logical state
-immediately, animations only lag the picture.
-
-### 8.2 Colour and contrast spec
-
-- Targets (WCAG ratio via `colors.themeContrast`, colors.zig:113): body text vs
- page ≥ 4.5 (aim 7); secondary ink (comments, line numbers) ≥ 3; tag/chrome text
- vs its band ≥ 4.5; non-text chrome (rules, grips, scroll thumb) ≥ 3 vs
- neighbours; selection text vs selection bg ≥ 4.5.
-- Absolute targets apply to the 15 native themes only, matching the existing
- test (colors.zig ~465), including its deliberate 2.5-4 band for line numbers
- (lineno is the exception to "secondary ≥ 3"). Imported themes get a RELATIVE
- rule: with every effect at its maximum (shadow darkening, unfocused dim, glow),
- no text/ground pair may drop below min(its original contrast, the target).
- Measured against the composited ground. If an effect would break the rule, its
- strength is clamped for that theme.
-- Subtlety budget: elevation shadow max 30% darkening at the edge, σ 0.4–0.8
- cell; unfocused dim ≤ 10% toward the page; glows ≤ 25% alpha; bloom threshold
- high (only true highlights), strength ≤ 5%.
-- Gamma: effect maths in linear light (shaders convert), shadows via pre-warped
- alpha (5.2), crossfades in OKLab; glyph coverage untouched (ui.frag stays).
- Wide gradients dithered.
-- Focus hierarchy by light, not only hue: the active pane is lifted (shadow),
- unfocused panes recede (dim), the cursor is the brightest thing on screen,
- chrome is quieter than text.
-
-### 8.3 Performance budget
-
-- Targets: 60 Hz → 16.6 ms, 144 Hz → 6.9 ms end to end. Shares (144 Hz,
- 200×60 grid, 4K, iGPU): core render ≤ 1.5 ms (only on state change), GUI
- instance build ≤ 1 ms, scene GPU ≤ 2 ms, decor+text-shadow ≤ 0.5 ms, post
- chain ≤ 2 ms for two passes (bloom at half res). Measured with the existing
- tracy zones plus GPU timestamps; numbers are budgets to verify, not facts.
-- Idle: zero ticks, zero renders, zero presents (7.3); blink stops after 10 s.
-- Presentation-only animation: shell redraw only, no core render.
-- Degrade order: post chain to half res → bloom off → soft shadows become hard
- (σ = 0) → cursor trail off → transitions snap. Hysteresis: step down after 30
- of the last 60 frames miss the budget; step up only after 10 s with none
- missed; at most one step per 2 s, reset on theme or window-size change. A step
- is never taken mid-transition, only at the next idle, and each one is logged
- (and shown in Debug). Input handling is never deferred for effects.
-
-### 8.4 Feel review (gate before an effect is kept)
-
-Each effect lands behind its own toggle, default off. Before "keep": render a
-frame sequence with the injected clock (GUI capture mode, PPM per frame, at 60
-and 144 Hz; tty via the snapshot harness `snapstyle` per frame) and a live
-screen recording; judge in motion against a reference (the lapis page, ghostty
-cursor trail, neovide smear); record keep / polish / drop with one line of why
-in `docs/effects.md`. Code review never substitutes for this.
-
----------------------------------------------------------------------------------
-
-## 9. Effects catalogues
-
-Every effect: a toggle (one `Fx` bitset in settings + builtin words, like
-`scene_effects` today), zero instances/passes/uniforms when off.
-
-### 9.1 GUI track
-
-Existing, verdicts: crt → REWRITE as bundled Shadertoy (Lottes-style mask,
-proper scanline beam profile, subtle); ripple → DROP; glitch → DROP (or a
-tasteful rewrite only if the feel review asks); pet → keep as-is, out of scope;
-transitions slide → POLISH (spring + elevation shadow while moving); zoom → DROP;
-dissolve → REPLACE with a linear-light crossfade; vertical → POLISH timing; the
-character effects (ascii…typewriter) → not a GUI effect (terminal track).
-
-| # | effect | needs from pipeline | pri |
+| what | tty | window | from |
|---|---|---|---|
-| G1 | soft elevation shadows onto lower panes (active lifted, floating chips, dragged pane) | regions + z tiers, decor `soft_shadow` | P1 |
-| G2 | focus transition: lift (spring) + unfocused dim | core focus Tween, `Region.dim`, cell-instance dim | P1 |
-| G3 | cursor: jumps glide on springs, adjacent moves snap (≤40 ms), 4-corner smear with glyphs re-drawn legibly inside it, optional edge-eased blink | layer geometry, per-pane view origin, shell time, decor `cursor`, redraw level B | P1 |
-| G4 | Shadertoy chain + bundled CRT, bloom (half-res dual-Kawase), vignette+grain | post chain, offscreen ping-pong, shell time | P1 |
-| G5 | lapis decor: rings, checker, stripes, hard offset shadows, title text shadow | styles, decor kinds, 3-phase text shadow | P1 (lapis set) |
-| G6 | smooth scroll: pixel offset on a spring, momentum for touchpads | shell-side; replaces scroll_lag stepping | P2 |
-| G7 | panel transitions redone: spring geometry, shadow while moving, linear crossfade | Track as Spring, tiers | P2 |
-| G8 | notice chips: elevation, shadow, ease-out drop, ease-in fade | tier 4, existing slide/fade | P2 |
-| G9 | selection glow: soft halo behind selection runs, 100 ms fade-in | selection runs as regions (overlay kind) | P2 |
-| G10 | theme crossfade in OKLab, 200 ms | Tween | P2 |
-| G11 | look-hover affordance: soft underline glow, 80 ms | hover region | P3 |
-| G12 | pane edge ambient occlusion (inner shadow, 1–2%) | decor `inner_shadow` | P3 |
-| G13 | parallax body pattern (lapis dots under see-through bodies at 0.25× scroll) | `see_through` style, per-pane view origin | P3 |
-| G14 | damage afterglow (changed cells glow briefly) | removed: a pane whose whole text changed flashed whole (the user: "really bad, just remove it") | — |
-
-### 9.2 Terminal track (tty, cell-native; separate, smaller)
-
-Where: presentation-only cell rewrites in the tui shell after the canonical
-grid (`tui/panel_compositor.zig` grows into the tty compositor), never in the
-canonical grid, so 9P/goldens stay clean with effects off. Gated on truecolor
-(vaxis caps / COLORTERM) — static effects may quantise to 256, animated ones
-turn off below truecolor. Safe glyph set by default (░▒▓ ▀▄▌▐ ▖▗▘▝);
-sextants/octants behind a setting. Budget: an animated frame ≤ 8 KB of output
-(≤ 4 KB and 30 Hz when `SSH_CONNECTION` is set); prefer effects whose per-frame
-delta is a moving edge, not a full-pane rewrite; without sync 2026, animated
-effects are off (static ones stay). vaxis has `caps.rgb` but no 2026 cap: the
-tty sends its own `CSI ? 2026 $ p` (DECRQM) at startup, next to the kitty shm
-probe; no answer = assume unsupported. Under tmux, tmux answers for itself (its
-own 2026 handling; old tmux does not answer → animated effects off), which is
-correct, because tmux is the thing that repaints the outer terminal.
-
-Enforcing the budget (draft-2 fix): tty animations are time-based, so dropping
-samples is free and correct. After each `vx.render` the shell counts the bytes
-written. If a frame exceeded the budget, the next sample is deferred by
-`bytes / budget × frame` ms. Slide and vertical therefore get fewer samples over
-ssh; they are not exempt. Effects are designed so each cell changes as few
-times as possible over the whole animation.
-
-Audit of what exists:
-
-| effect | where | verdict | why |
-|---|---|---|---|
-| ascii (byte walk) | core compose | REMOVE | slot-machine noise, rewrites every changed cell every tick |
-| edges | core compose | REMOVE | gimmick, full-pane churn |
-| fall | core compose | REMOVE | gimmick |
-| wave | core compose | REMOVE | gimmick, illegible mid-motion |
-| scramble | core compose | REMOVE | noise every tick, worst byte cost |
-| typewriter | core compose | REMOVE | slow on big panes, row-major reveal reads as lag |
-| curtain | core compose | POLISH → wipe | a directional reveal is good; give it a 2-cell soft truecolor edge |
-| slide | tty compositor | POLISH | ≤150 ms ease-out, pane open/close only; a full-pane rewrite per sample, so the byte budget thins it to few samples over ssh |
-| zoom | tty compositor | REMOVE | nearest-neighbour cell scaling is garbage |
-| dissolve | tty compositor | POLISH → ordered swap | Bayer 4×4 threshold per cell; each cell swaps old→new ONCE at its threshold (no continuous colour lerp), so the total output is one pane's worth spread over the animation |
-| vertical | tty compositor | KEEP (timing polish) | reads as a drawer, cheap |
-| message fade | core (grid colours) | KEEP (OKLab) | |
-| theme crossfade | core | KEEP (OKLab, fewer steps over ssh) | |
-
-Removing the six core-composed effects deletes `composeAsciiTransitions`,
-`charSource`, `AsciiDiff`, `PanelCellDiff.ascii` and their shader/GUI paths
-(user decides).
-
-New, cell-native:
-
-| # | effect | technique | pri |
-|---|---|---|---|
-| T1 | floating shadow for chips/debug box/drag preview | 1 cell right/down darkened in OKLab; blank edge cells get ▗▄/▐ half-cell edges | P1 |
-| T2 | cursor jump trail | on jumps ≥ 3 cells: 3–5 cells along the path, bg ramp cursor→page, 120 ms; tiny delta | P1 |
-| T3 | wipe transition | 2-cell soft leading edge; only the edge changes per frame | P2 |
-| T4 | ordered swap transition | = polished dissolve: Bayer threshold, one swap per cell | P2 |
-| T5 | unfocused dim | fg 15% toward bg, instant (no animation over ssh) | P2 |
-| T6 | active tag gradient | subtle horizontal truecolor ramp on the active tag band | P3 |
-| T7 | scroll thumb flash | rail thumb brightens 300 ms on scroll | P3 |
-
----------------------------------------------------------------------------------
-
-## 10. Lapis on this pipeline
-
-Colours: a normal theme file (lapis #0f1a4a, deep #0a1030, ink #050a24, gold
-#e8c46a, vermilion #d4412f/#ff6a4a, vellum #eee6d2/#9aa6d9). No fonts. Styles:
-
-- workspace/column/pane tag (the "trail"): lapis fill, 2 px gold ring, hard
- shadow 5×5 px vermilion (px snapped to device pixels, no AA), 3 px title
- text shadow for the file name.
-- pane (the "panel"): gutter (2 cells ≈ the CSS 18 px band) carries the
- ornament pattern (checker gold/lapis), inset rings gold/lapis/vermilion
- (2/3/1 px) on the pane edge, soft black shadow from its tier.
-- column tag bar / notice chips: striped gold/lapis (`stripes`, period 4 px)
- behind the text band, ring gold, hard vermilion shadow.
-- page: lapis-deep. The dot grid sits under the pane BODIES (`dots` pattern
- with `see_through`, so page-coloured cell backgrounds let it show between
- glyphs). It is fixed to the pane, not to the text, so it does not track
- scroll. G13 parallax is retargeted to this body pattern at 0.25× scroll and
- stays P3.
-
-Where the pixels come from: left band = the pane's own gutter; top = its tag
-row (the band has vertical slack above/below the tagline glyphs); right/bottom
-= 1–2 px rings over the last column/row's side bearings; shadows fall on the
-neighbour's gutter/tag row (§5.2, drawn after the neighbour's cells, §3.4). No
-layout change. If the user wants the CSS
-look with real gaps between panes, that is a separate layout knob (question 1).
-
----------------------------------------------------------------------------------
-
-## 11. Damage / dirty tracking
-
-No new dirty bits without a measurement. Existing: `needs_frame` (frame-level),
-vaxis cell diff (tty output), wire deltas, web node caches. The pipeline makes
-two savings free: (a) presentation-only animations skip the core render
-entirely; (b) deadlines replace per-tick renders for holding phases. Region
-lists make per-region instance caching possible later, if tracy shows the
-instance build matters.
-
----------------------------------------------------------------------------------
-
-## 12. What gets deleted or merged
-
-Core: second pane-tag paint, second body paint, grid-notice pass (joined from
-layers), duplicated header hover/selection/caret, `std.mem.swap` of the Surface,
-hover-bit reset + `mark_hover`, per-animation `advance` counters and frame
-constants, `animationActive` (→ `nextWake`), `SceneEffect` (→ shader list),
-`capturePrevious` on idle frames with transitions off; if the user agrees, the
-six core-composed character effects.
-Types: TagLayer + BodyLayer → Layer; layout.zig's Presentation/Track/Easing/
-Animation move to `src/Presentation.zig` and `src/animation.zig` (pure moves).
-GUI: AnimationClock, finishPresentedAnimationFrame, PaintPlan/PaintBatch,
-coverLayers-as-cell-loop (→ page cover), the five inference functions (4),
-crt.zig mapping, crt.frag.glsl, `scene_failures` plumbing folds into the chain.
-Shells: four ack sites, six tick drivers.
-
----------------------------------------------------------------------------------
-
-## 13. Staged plan (jj changes on a bookmark `render-pipeline`; effects on top of it on `fx`, droppable)
-
-Gate for every stage: `zig build snap` byte-identical, `zig build unit-test`
-and `unit-test -Dplatform=gui` pass, `-Dplatform=web` builds, tracy frame time
-not worse at 200×60. Builds redirected to files; `-Dplatform` always; PARDES_*
-stripped. No visual change until stage 9 unless stated.
-
-| # | change | notes / risk |
-|---|---|---|
-| 0 | GUI capture goldens: a handful of scenes rendered hidden in capture mode, PPM hashes checked in (same machine/driver) | the safety net the GUI stages need; machine- and driver-specific, so a LOCAL gate only, never CI |
-| 1 | pure moves: render → `src/draw.zig`; Presentation/animation out of layout.zig | no behaviour |
-| 2a | clock plumbing: `Host.now` (the shell's monotonic ns) and `Pardes.advance(now)`, which runs one `.tick` per whole 16 ms frame since core time last stood still; `nextWake()` lists every core animation and answers the next frame while anything moves, the wait's end while something only waits (message linger, look-hover delay), null when idle; the pump sleeps to it and draws only stepped frames. No shell posts `.tick` any more (tty's timer thread only wakes the wait; GUI's AnimationClock, web's JS tick bank and the detached server's and the board's ticks are gone; grid mode moves its virtual clock straight to the next wake). `acknowledgePanelPresentation` stays in the shells (revisit at stage 8: grid mode acks `&.{}` on purpose). capturePrevious only when transitions are on. `.tick` stays as the one-frame step `advance` and the unit tests use, so every curve and every asserted number is unchanged | pacing is corrected (144 Hz no longer ~25% slow, ssh no longer drifts): a bug fix allowed in this phase. PARDES_TEST_CLOCK (set by the snapshot harness): tty and the detached server answer a virtual clock that a timed-out wait moves exactly to the core's next wake, so goldens replay the same frame sequence on any machine load. Review fixes: tty's wake timer is interruptible (a newer, shorter request cuts short an older sleep); a wait (linger, hover delay) is jumped to its end in one step, never counted against the 240-frame catch-up cap; an overshoot under 1.5 ms after a step is let go, so 60 and 120 Hz take exactly one step per display frame. Known exceptions: the GUI still polls every 16 ms when idle (SDL events, gamepad, fs tick, smooth scroll depend on it; revisit at stage 8); a minimized GUI renders every stepped frame of a running animation (stage 8) |
-| 2b | (on `fx`, feel-reviewed) Tween/Spring curves, settle rules, OKLab crossfades, new durations from §8.1 | a look change, kept apart from 2a so either can be bisected |
-| 3 | paint functions take `s: *Surface`; delete the swap hack | mechanical, wide |
-| 4 | PLACE: Region list built once; renderPane/tags/notices read their rects from it | wait for tag→Text; the refactor is already replacing BOX_H with `pane.tag_rows` and `p.tagTop/bodyTop(pane, r)` — PLACE absorbs those into the region rects |
-| 5 | JOIN: paint tags/notices/headers once into layers, copy into grid; the grid wins where the copies disagree, and each disagreement is listed for a later decision | goldens are the oracle; wide-grapheme re-clip at the edge (§3.2) |
-| 6 | body layer joined the same way (paint once, copy visible rows) | riskiest join; A/B the old double paint in a temporary test with tag_bottom on and off, then delete it |
-| 7 | Layer merge (TagLayer + BodyLayer), wire v8, web accessors | after the other agent lands; touches mouse hit paths; breaks the macOS shell's layer ABI (accepted: macOS build ignored for now); done: one `Layer` (src/Layer.zig) with `rows` (0 = no layer) and a `cursor{x, y}`; a tag of N rows is ONE layer of N grid rows (`tagHit` answers the row as `line`, `bodyHit` keeps its meaning), so the per-line layer bases are gone. Wire v8 ships rows, cursor y and the region list in the one bump; v7 and v9 peers are refused in both directions (tests). web: `tag_layer_value` 11 = rows, 12 = cursor y, and app.mjs lays every row. macOS: its Zig side compiles against `Layer`, but pardes.h still sees one row per tag layer (a taller tag shows its first row there) |
-| 8 | GUI draws from regions: role tiers with track groups in tiers 2-3, page cover, hard-edged snapped decor for rules/rails/grips (pane chrome in the pane's tier), per-instance clip; delete inference functions, `transient_on` and `mark_hover` (breaks macOS glass hover; accepted, macOS ignored for now) | stage-0 PPM goldens byte-identical (possible only because hard decor is snapped and not anti-aliased); pane chrome now also shows during transitions, which is the one allowed visible delta, listed Done: the frame is drawn in groups (makeGroups): tier 0, one group per track in paint order (tiers 2 and 3), tier 4 as two groups (the notices; then the guides and the debug box, which the core paints over them), tier 5 (bar cursors), each drawing cells, images, decor. Decor is every rule, rail, thumb, grip mark, spine, the workspace and column rules, the bottom band, notice rules and bar cursors: whole-pixel rects drawn by `decor.frag` over `ui.vert` as cell instances (colour in the ground, coverage in fg.r, blended like the overlay), so each carries its track's transition and clip; a closing pane's comes from the last frame's regions (`Surface.previous_regions`). Only `solid` exists yet: `decor.vert` and the other kinds (§5.1) come with the first effect that needs them. Deleted: taglineBaseRgb, topbarPaneBorderHeight, bottomTaglinePresent, frameChromeBg, cellBackgroundIs and the rail inference, paneGripCell's scan, transient_on, PaintPlan; one cover map (coverFrame: layer, grip and offset, focus, anchor, floating) is marked from layers and regions once a frame. New regions: `column` (spines, anchors, the focused column's tint), `guide`, `debug`; `Surface.chrome` is the palette, on the wire in v8 (not yet shipped, so no bump), and an attached GUI draws the same chrome (test). Per-instance clip (`CellInstance.clip_*`, 104 → 120 bytes an instance, ~15% more upload a frame) replaces the vertical transition's scissor. While any pane moves, opens or closes, notices stay in their own panes' groups, under whatever slides over them; tier 4 holds them only when nothing moves. Goldens: 01-12 byte-identical; 13-17 differ only in pixels past the grid (with a picture on screen the image pass left the scissor at the grid's size, cutting every rule end, rail foot and band that runs into the leftover pixels; they now run to the edge as in every scene without one); 16-debug shows the debug box (it was drawn from the grid under the source's context-row layer, so the GUI never showed it there); 18-mid-transition is new (virtual clock, PanelSlide Newcol with the picture, frame 6 of 12: chrome moves with its pane). Other deltas, outside the goldens: a guide over a tag or a context-row body now shows; with WindowOpacity < 100 a layer's bar cursor is ink like the grid's; an attached GUI gains the focus tint, notice rules, spines and the theme's page and caret colours. Deferrals fixed: the GUI sleeps when idle (SDL and queue events wake it; a smooth scroll, a gamepad, the test feed, a shell's kill deadline, a present to retry still poll), and a minimized or occluded window sleeps through animation. Tracy, `gui frame build`, 200x60, terminal output plus scrolling, ReleaseFast, two interleaved runs of ~180 frames: before 992/1015 µs median, after 989/987 µs |
-| 9 | post chain: glslang, Shadertoy prefix, ping-pong, ShaderAnimation, redraw levels A/B (§5.5); bundled CRT without barrel; delete scene_effects/crt.zig/crt.frag | first visual change (the CRT look) Done: src/gui/Post.zig, shaders/post/ (prefix, crt, ripple, glitch), post.vert. glslc (decision 3) with compileGlsl's flags, off the frame path; ghostty's Uniforms matched offset for offset by a test against a copy, and the prefix's block checked name by name; ghostty's test_shadertoy_crt and _focus compile, _invalid fails with glslc's words. Level A measured (Tracy, 200x60, Crt, idle 10 s): 215 chain-only redraws at 34 µs median CPU each, 6 core frames (957 µs) in the same time; the core's clock stays idle. Input is identity (test: the corner click with Crt on). The three bundled passes were rewritten: Crt without barrel or tube edge, scanlines and mask that average to one, dithered vignette; Ripple as rings in pixels, eased in, lit on their slopes in linear light, dithered; Glitch as short eased bursts of torn bands with an RGB split, keyed to iTime. Before/after stills for the user's judgement. |
-| 10+ | `fx` bookmark: G1–G3 → feel review → G4 bundled → G5 lapis theme → P2s; tty T1–T2 → feel review → removals of audited effects (after user decision) → T3–T5 | each effect its own change, default off |
-
-Tests to add: fixed-clock animation tests (Tween/Spring closed form, retarget
-velocity continuity, `nextWake` for each holding phase); region placement vs
-old ad-hoc geometry (all layouts, tag_bottom, collapsed, multi-line tags);
-contrast test (absolute targets on the native themes, relative rule on all themes × effect maxima);
-settle tests (`nextWake` is null after every spring settles); Shadertoy prefix compile test with
-ghostty's test shaders (`test_shadertoy_crt.glsl`, `_focus`, `_invalid`) and
-uniform-offset checks against ghostty's `Uniforms` struct; tty byte budget test
-(bytes per animated frame via the snapshot harness).
-
-Risks: the tag refactor moving under stages 4–7; body-layer join parity; glslang
-build time and size (C++, ~minutes on the ~10 min build); machine-specific GPU
-goldens; ssh/tty byte budgets; wire version bump breaks mixed-version attach.
-
----------------------------------------------------------------------------------
-
-## 14. Recorded open points (agreed with the adversary: not blockers)
-
-1. Selection colours: because ghostty swaps them (§6), Shadertoy shaders tuned
- on ghostty will see iSelectionForeground and iSelectionBackground swapped in
- pardes, which fills them by their GLSL names. Documented.
-2. A same-tier cast shadow over a neighbour sits under that neighbour's
- decor-over rings, because rings are drawn last. Accepted as the look; check it
- in the feel review.
-3. Gamma is a compromise (sRGB-space blending with pre-warped alpha). Coloured
- glows keep a slightly dark falloff until the RGBA16F experiment is measured.
-4. The macOS shell breaks at stages 7 and 8 (Layer ABI, mark_hover). Accepted,
- since the macOS build is ignored for now.
-5. Stage-0 GPU goldens gate locally only.
-6. Revisit at the first visual stage (from stage 5): the notice layer lost
- its hover word to keep the grid's behaviour. Notice words are Look/Exec
- targets, so bring the hover affordance back in BOTH the grid and the
- layer then. Done right after stage 8: a notice's word under the pointer
- is lit as a header's is, in the layer and so in the grid's copy joined
- from it. The same change deleted `mark_hover`, the `Cell.hover` bit and
- the per-frame reset of it (never set since stage 5; macOS loses its
- glass hover rect, accepted with open point 4).
-7. Revisit at stage 8 (from stage 6): a body without context rows has no
- layer (paint once, straight onto the grid). If the GUI is to read every
- body from a layer, give every body one then and measure the copy. The
- context-row path also still builds the body's text twice (a pre-pass
- with body_rows 0 decides the context rows, renderBody builds it again at
- the layer's rows); the paint is single. Measure both there. Decided at
- stage 8, measured (Tracy, 200x60, TreeContext on a scrolled source,
- ReleaseFast): the pre-pass text build is 5 µs median and the layer's
- copies 10 µs per context-row body per frame. Kept as they are: nothing in
- the GUI reads a layerless body from anything but the grid, which is
- exact, so a layer for every body would be ~10 µs a body a frame for no
- pixel.
-
-## 15. Questions for the user
+| a scroll's glide (glide.zig) | whole rows | the pixel | a body's line and doc between two frames, and the last frame's cells |
+| the caret's ease | (the terminal's cursor) | its quad on critically damped springs (gui.zig's `Caret`) | the cursor and the focused body |
+| the blink (`CursorBlink`) | (the terminal's) | the cursor's alpha | the window's last key or click |
+| a jump's trail (`JumpTrail`, jump_trail.zig) | the ground behind the cursor, truecolor terminals | drawn over it, in the overlay | the cursor between two frames |
+| `InactiveDim` | (kept, not drawn) | the unfocused panes' ink faded, never below its contrast floor | the regions' focus |
+| `Pet` | (unsupported) | a sprite in the workspace tag's blank end (gui/pet.zig) | the grid's first row; SDL's ticks |
-1. Lapis geometry: decorations inside existing chrome (gutter band, tag row,
- thin edge rings; no layout change — recommended), or real pixel/cell gaps
- between panes like the CSS page (layout + hit-testing change)?
-2. Remove the six core-composed character transitions (ascii, edges, fall,
- wave, scramble, typewriter) and GUI zoom/ripple/glitch?
-3. Runtime shader compile: link glslang (C++, from ghostty's vendored pkg,
- allocator-policy exception), or spawn `glslc` at load time (no new dep, needs
- glslc installed)?
-4. Focus lift/dim on by default once it passes the feel review, or opt-in?
-5. Stage 2a corrects animation pacing (144 Hz is ~25% slow today, and ssh
- drifts) while keeping every curve. OK as a bug fix inside the "no visual
- change" phase?
-6. Cursor blink: pardes never blinked. Keep it off by default (recommended),
- with an opt-in eased square-wave blink?
-7. Bundled CRT without barrel distortion (exact clicks, recommended), or barrel
- plus keeping crt.zig's inverse mapping for the bundled shader?
+The settings these read are plain bytes in the core's settings, dumped
+and replicated as any other; nothing a frontend keeps goes back to the
+core.
-## Decisions (user, 2026-09-28)
+## The window's composition
-1. Lapis is drawn inside the existing pane chrome; no gaps between panes.
-2. Keep every whimsical effect (the six terminal transitions, GUI zoom, ripple,
- glitch): the problem is their quality, so polish each until it feels good
- instead of removing it.
-3. Shadertoy shaders are compiled by spawning `glslc`, not by linking glslang.
-4. Focus lift/dim default: undecided, ask when that stage lands.
-5. The animation pacing fix goes into the no-visual-change phase.
-6. Cursor blink is on by default.
-7. The bundled CRT has no barrel distortion, so clicks stay exact.
-8. (After trying them live) Ripple and Glitch are removed entirely; Crt stays.
+Four fixed draw groups, bottom to top: the page and the panes, the
+notices, the guides and the debug box the core paints over them, and the
+ink (bar cursors); then the overlay (the pet, a jump's trail, the caret's
+quad). Decor is flat: rules, rails, grips, spines, notice rules and bar
+cursors as hard-edged rectangles read from the regions.