perf(render): skip frame-to-frame unchanged cells (appearance diff)

[mparrett]

What

Skips redrawing map cells whose appearance hasn't changed since the last frame.
render-map-tile now computes a cell's [glyph fg bg], compares it against a
per-cell buffer of what was last drawn there, and emits only on a difference.
Visible output is unchanged — a skipped cell is one already showing the right
thing.

Stacked on the SGR-elision PR (perf/render-sgr-elision); review/merge that
first.

Why

render-dirty re-emits the entire visible FOV on every move. But the game's
lights are static terrain sources (torches, lava, fire — collected once), so with
the camera held, most visible cells are byte-identical to the previous frame; we
were repainting them for nothing. On a movement burst this is the dominant
render-side cost.

Measured over a fixed movement sequence on a water-heavy map: ~35% fewer
set-fg/set-bg and ~21% fewer output bytes. Drier maps do better (less
animation); the WASM build should benefit more, since each skipped emit is a
crossing into the JS host avoided. Animated tiles (dancing water/lava, fire)
differ every frame by design and still redraw; what drops out is the static
stone, floor, and wall away from the move.

Keeping the buffer honest

A cell's appearance is only part of what's on screen, so three cases would
otherwise leave stale pixels; each is handled:

• Full repaints clear the buffer. render-map (used by render-full, camera
  shift, floor change, resize) draws over a freshly blanked or scrolled screen,
  so the buffer is dropped and everything redraws. The FOV-delta path never calls
  it, so there the diff stays live.
• Moved entities. Entities are drawn over their tile by a separate pass, not
  through the buffer, so a monster that moved would leave a ghost glyph on the
  vacated cell (the tile "didn't change"). Every current-or-former entity cell is
  invalidated each frame so its tile repaints beneath the entities.
• VFX overlays paint raw over cells without updating the buffer, so the
  restore step invalidates the cells it redraws — otherwise the overlay tint
  would stick.

This buffer-coherence bookkeeping is the real cost of the approach. It also makes
the case for a longer-term move to a full back-buffer (paint-to-buffer, diff on
flush) where that coherence is structural rather than a set of targeted
invalidations — a bigger change, noted here as the natural next step, not part of
this PR.

Safety

Render-only — no effect on the seed, action log, or world state, so determinism
and replay are unaffected. Verified by comparing the displayed cells (colors
included) over a fixed input sequence: static terrain and glyphs are identical
before and after. Animated tiles already vary run to run via the unseeded rand
stream, unaffected either way.

This PR also adds golden tests that lock the losslessness down: driving
render-map-tile through with-out-str, they assert a seeded render is
reproducible, a static tile's color is independent of rand state, the diff
skips an unchanged cell and re-emits a changed one, and the pen emits one
set-fg for two same-color cells. They close a coverage gap a review flagged —
the earlier check was glyph-only and would not have caught a color-order
regression.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-20 20:45 UTC

[mparrett]

Reviews complete:

• [#145](perf(render): elide redundant SGR escapes in the map render #145): Looks sound. Pen state is reset at the relevant raw-render boundaries, including VFX restoration and dirty-map batches.

• [#146](perf(render): skip frame-to-frame unchanged cells (appearance diff) #146): Looks sound atop perf(render): elide redundant SGR escapes in the map render #145. The appearance cache is correctly cleared for full/camera redraws and invalidated for entity movement and VFX restoration.

• [#149](perf(render): synchronized output (DEC 2026) across all frame renders #149): Needs a fix before I’d merge it.

  It claims to synchronize every full-screen frame, but only updates xsofy.render. The animated title (xsofy.title/draw-frame), animated descent screen, and xsofy.screenfx/clear-screen still emit large frames with plain term/flush, so they remain prone to the tearing this PR targets. The sync helpers should be shared (likely via screenfx) and used for those paths too.

All three PR heads are mergeable and their CI test runs are green. The stack wiring is correct: #145 → #146 → #149. After merging each lower PR, retarget/rebase the next PR onto main before merging it.