Epic: Render emit performance

[mparrett]

TL;DR: a lane for cutting xsofy's terminal render cost — fewer escape sequences per frame, no change to what's drawn. A three-PR stack up, more scoped behind it. The payoff concentrates on the WASM/web build, where every emit crosses into xterm.js.

What this tracks

Render-side emit efficiency in render.lg: trimming redundant terminal output without changing the rendered result. Distinct from the generation/native perf work (perf/native-xxh3, perf/wander-lights-cache), which targets map generation and the native build.

An independent lane off main: no dependency on the mobile shell epic (#128), upstream-mergeable on its own, and it flows back to every build once landed. The payoff is largest where mobile runs. On the WASM path each skipped emit is a Go→JS→xterm.js crossing avoided, on the most constrained target, so treat it as a mobile-readiness enabler judged on the phone-feel harness rather than native byte counts.

Slices

• sgr-elision (perf(render): elide redundant SGR escapes in the map render #145): a render-only pen that skips a redundant set-fg/set-bg; move-cursor/write and iteration order are unchanged, so it's lossless. Does most of its work on the full-screen repaints (floor change, camera pan, resize). Off main.
• appearance-diff (perf(render): skip frame-to-frame unchanged cells (appearance diff) #146): skip map cells unchanged since the last frame, since static lights mean most visible cells repeat frame to frame. ~35% fewer set-fg/set-bg and ~21% fewer bytes over a movement burst. Stacks on perf(render): elide redundant SGR escapes in the map render #145. Carries the golden tests (see below).
• synchronized output (perf(render): synchronized output (DEC 2026) across all frame renders #149, draft): wrap the frames that repaint in succession (render-full, render-dirty, and the vfx animation per frame) in DEC mode 2026 so each presents atomically, for anti-tearing most visible on xterm.js. Stacks on perf(render): skip frame-to-frame unchanged cells (appearance diff) #146 (additive: keeps the emit reduction, adds atomic presentation). One-shot modal screens stay on a plain flush, since nothing streams after them to tear. Mode 2026 is a boolean (never nested); no feature detection (unsupported terminals ignore it); sync-output? is a source opt-out. A let-go term begin/end-sync primitive could factor out the escapes later if other TUIs want them, but xsofy owns the frame boundaries, so it lives here. Verdict pending a clean-machine xterm.js A/B.
• back-buffer render model (larger, scoped): a paint-to-buffer plus diff-on-flush layer that folds elision, the appearance diff, and the panel/entity/vfx paths into one place, making buffer coherence structural instead of the targeted invalidations perf(render): skip frame-to-frame unchanged cells (appearance diff) #146 carries. Those invalidations are the argument for it.

Shelved: color quantization, measured ~1% in-game (animated jitter exceeds the quantization bucket). Kept in the testbed, dropped from ship.

Probe tool

• lighttest (tool: lighttest — interactive lighting + render-perf testbed #148, draft): tools/lighttest.lg, an interactive lighting and render-perf testbed — a generated dungeon and a movable light, driven by keyboard or a screensaver demo, with a three-way render A/B (delta / sgr-off / naive), depth and sync toggles, and demo paths including a full-map scroll used as the tearing stressor. The vehicle behind these measurements.

Landing order and independence

• perf(render): elide redundant SGR escapes in the map render #145 → perf(render): skip frame-to-frame unchanged cells (appearance diff) #146 → perf(render): synchronized output (DEC 2026) across all frame renders #149 is a linear stack: merge perf(render): elide redundant SGR escapes in the map render #145 first (perf(render): skip frame-to-frame unchanged cells (appearance diff) #146 retargets to main), then perf(render): skip frame-to-frame unchanged cells (appearance diff) #146, then perf(render): synchronized output (DEC 2026) across all frame renders #149.
• The back-buffer is an independent follow-up off main.
• No ordering tie to the mobile epic (Epic: Mobile and responsive shell #128): mobile inherits this lane on its next rebase onto main. Land here first rather than folding it into the mobile branch, so a cross-cutting win isn't trapped behind mobile-specific churn.

Held in draft pending

• Render golden test: done, in perf(render): skip frame-to-frame unchanged cells (appearance diff) #146. Seeds the global rand and asserts a reproducible render, plus diff-skip and pen-elision behavior, driving render-map-tile through with-out-str. Closes the coverage gap a review flagged (the earlier check was glyph-only and missed a color-order regression).