animation: core publishes transition records; gui evaluates via shaders, tty over grid cells

3 files changed, 38 insertions, 14 deletions

diff --git a/docs/config.md b/docs/config.md
index 7e27216b..6485d46a 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -100,6 +100,13 @@ 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.
 
+The SDL GUI joins the reduced-height global and pane tagline bands with
+`gui_topbar_pane_border_px` physical pixels. Set it to zero for a direct join.
+`gui_topbar_pane_border_rgb` can pin an RGB color; its default `null` follows
+the active theme's scrollbar-track color. With `Tagbottom` enabled, a tagline
+on the final grid row is bottom-aligned so the same unused half-band does not
+show beneath it.
+
 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`,
@@ -132,12 +139,20 @@ 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
+presented grid with the new one. Dissolve switches visually changed cells at
+stable noise thresholds. ASCII walks every changed single-byte printable glyph
+from its old `u8` value to its new one. Nearby values increment or decrement
+once per frame; longer distances use ease-out character skips, moving quickly
+at first and settling exactly on the destination. Glyph-stable style changes
+and non-ASCII graphemes become canonical immediately. A walk is capped at
+twelve movement frames, and each pane lasts only as long as its longest walk.
+The core computes and composes that semantic diff once for every backend;
+pixel attachments, which have no character value, pass through unchanged.
+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.
+content drops back down; surviving panes are never animated. The TTY
+implementation performs its remaining geometry/dissolve operations directly
+on a copy of the core-composed presentation 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
diff --git a/docs/design.typ b/docs/design.typ
index 8dd14cdf..1c50cfde 100644
--- a/docs/design.typ
+++ b/docs/design.typ
@@ -178,24 +178,30 @@ weight.
 their easing, exact endpoint progress, stable per-cell noise, and a POD track.
 The core detects opening/moving rectangles when it commits layout and publishes
 only active tracks. It retains the last successfully presented canonical grid
-and a semantic old/new cell mask; unused grapheme bytes do not manufacture a
+and a typed old/new cell diff; unused grapheme bytes do not manufacture a
 change. A separate dense closing-track list is presentation-only state for a
 pane whose functional lifetime has already ended. Pointer input inverts the
 presented slide/zoom/vertical rectangle back to the canonical grid, lets
 unchanged dissolve/ASCII cells through immediately, and rejects closing
 pixels, so pixels and gestures cannot disagree during a transition.
 
-TTY copies the canonical `Surface` grid into a compositor scratch grid, clears
+Pardes core first composes each ASCII-qualified diff by incrementing or
+decrementing its printable byte. Short walks move once per frame; longer walks
+use integer ease-out skips and finish within twelve movements. Style-only and
+non-ASCII changes pass through, and every backend receives the same
+presentation cells.
+TTY copies that `Surface` grid into a compositor scratch grid, clears
 slide/zoom destinations, then paints moving, opening, and closing panels in
 order.
 Cleared geometry uses the theme page color when it is explicit and the host
 terminal default only for transparent themes, so a light theme cannot flash a
 dark gap. Slide/zoom change the copied rectangle. Dissolve changes only diff
-cells from their old value to their new value; ASCII takes the same cells
-through punctuation; vertical raises only an opening or frozen closing pane
+cells from their old value to their new value; vertical raises only an opening
+or frozen closing pane
 inside its own clip. SDL supplies old/new glyph data, diff flags,
 final/presented boxes, and effect parameters to the glyph and native-image
-shaders. macOS passes the same records across its plain C ABI and composites
+shaders. Pixel attachments bypass ASCII because they have no character byte.
+macOS passes the same records across its plain C ABI and composites
 old/new panel images in Metal/Core Image. Scene `Crt`, `Ripple`, and
 `Glitch` bits share one full-window pass in each native GUI. DOM web is a
 separate platform, not a shader GUI: retaining selectable HTML/CSS is more
@@ -218,7 +224,7 @@ Pardes
   rects:     [16]Rect       // where each pane landed, this frame
   panel_tracks: [16]?Track          // live panes, serial-guarded
   closing_panel_tracks: [16]Track   // dense visual tombstones, no pane owner
-  presented_cells + changed_cells  // acknowledged baseline + semantic diff
+  presented_cells + panel_cell_diffs  // acknowledged baseline + semantic diff
   effects:   [4096]Effect + head/len   // a fixed ring
 
 Pane
diff --git a/docs/macos.md b/docs/macos.md
index b800513f..5e5f13e3 100644
--- a/docs/macos.md
+++ b/docs/macos.md
@@ -655,13 +655,16 @@ against the Zig extern struct on Linux. The exported list is already stable
 paint order—moving panes by slot, then opening panes by slot—so Swift only
 consumes it.
 
-CoreText still renders one canonical complete frame. When tracks exist, the
+CoreText renders the complete frame supplied by the core. PanelAscii bytes are
+already interpolated there, identically to the TTY and SDL paths. When tracks
+exist, the
 same retained bitmap used by scene effects is fed through two kernels in
 `shaders/crt.ci.metal`: `pardesPanelClear` removes every final target first,
 then `pardesPanel` samples each target into its eased presented box. Slide uses
 ease-out cubic, zoom uses ease-out-back, dissolve uses stable pane/cell noise,
-and ASCII materialization replaces not-yet-revealed cells with procedural
-punctuation. Because the input is the finished bitmap rather than a glyph-only
+while ASCII only clips the already-composed core cells; pixel attachments have
+no ASCII value and pass through unchanged. Because the input is the finished
+bitmap rather than a glyph-only
 batch, backgrounds, glyphs, taglines, rules, the caret, PDF pages, and image
 panes move and dissolve together. Scene CRT/ripple/glitch runs once after the
 panel composition.