perf(render): synchronized output (DEC 2026) across all frame renders

[mparrett]

What

Wraps every full-screen frame render in DEC private mode 2026 (begin/end synchronized update). The terminal holds the previous frame while we emit, then presents the whole batch at once, so a player never sees a half-drawn frame.

Reference + compat notes: https://github.com/contour-terminal/vt-extensions/blob/master/synchronized-output.md

Stacked on the appearance-diff PR (perf/render-appearance-diff, #146); review/merge that first. It's additive: #145/#146 cut how much we send, this makes what we send land in one piece. Both wins compose.

Why

A render pass emits a lot of escapes. If the terminal repaints partway through, the result is tearing: part of the screen at the new state, part still at the old. It's worst on the frames that repaint in succession — a map scroll, VFX, the pulsing death screen — and most visible on xterm.js (the web build), where a pan clearly tore.

The trap is thinking only those repeating frames tear. A single full-screen paint is itself a burst of escapes, and the terminal can composite it mid-draw — so a one-shot modal that clears and redraws a full inventory can also show a half-built frame. Every full-screen render is a candidate, so every one gets wrapped.

Coverage

The sync helpers live in xsofy.screenfx — the shared screen-effects namespace that both render and title already depend on and that reaches into neither — so every full-screen emitter shares one implementation rather than render owning it:

• Game frames (xsofy.render): render-full, render-dirty, animate-vfx! (per frame), render-death-screen (animated — it pulses per frame through the ui run-loop), and the six modal screens (render-inventory-screen, render-messages-screen, render-help-screen, render-quick-menu, render-rune-codex, render-inscribe-screen)
• Boot screens (xsofy.title): the animated title (draw-frame) and the descent screen (per frame)
• screenfx/clear-screen — a full-screen paint on its own

render-vfx-frame no longer flushes on its own; the animation loop presents each frame. Only render-hazard-prompt stays on a plain flush — it's a one-line overlay, not a frame. A sync-begin! opens each frame; a flush-frame! (end-sync then flush) closes it.

Also fixes an unpaired begin: the final vfx frame opened a synchronized update but closed with a bare flush, leaving the mode set until the terminal's own timeout.

Design notes

• Boolean mode, not a nesting counter. A single end-sync closes it, so only top-level frame entries are wrapped, never their inner helpers, and animate-vfx! gets one begin/end pair per frame rather than one around the whole loop.
• No feature detection. The DECRQM probe (CSI ?2026$p) needs a fragile async read at boot, and unsupported terminals ignore the sequences, so worst case is a couple of wasted bytes per frame. sync-output? (default true) is a source opt-out for a terminal that composites 2026 poorly; the web target wants it on.
• One caveat: a frame that throws before end-sync leaves the mode on, but the terminal's own 2026 timeout releases it, and a throw in the render path crashes to shutdown anyway.

Safety

Render-only, with no effect on the seed, action log, or world state, so determinism and replay are unaffected. The change is confined to frame boundaries; the per-cell render path is untouched, so the golden tests that drive render-map-tile see no synchronization bytes. Verified live: every frame emits exactly one balanced begin/end pair (equal counts across moves, all modal screens, and combat), with no unpaired begin that could freeze the display. Escape-sequence guard tests and the existing suite pass.

[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.

[mparrett]

Review is valid - only xsofy.render was wrapped.

Fixed by hoisting the sync helpers into xsofy.screenfx (the shared screen-effects ns that render and title already depend on and that reaches into neither), exactly as you suggested. They're now used at every full-screen emitter:

• the animated title (title/draw-frame) and the descent screen — one begin/end pair per frame
• screenfx/clear-screen — a full-screen paint on its own
• plus the render.lg frames from before

One bonus fix en route: the final vfx frame opened a synchronized update but closed with a bare term/flush, leaving mode 2026 set until the terminal's timeout at the end of every animation. Now paired.

Verified across a full boot-to-game session with the title and descent animations included: begin and end counts match exactly (75/75), strictly alternating, no unpaired begin. Full suite green (288 tests, 2745 assertions). Force-pushed — new head 0993a11.

[github-actions]

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

[mparrett]

👍 Re-reviewed after the rebase — the earlier concern is fully addressed. The sync helpers no longer live in render; they moved to xsofy.screenfx (sync-begin! / flush-frame!, plus the begin-sync/end-sync constants), which is the shared screen-effects ns both render and title already depend on. Every full-screen emitter now goes through that one implementation:

• xsofy.title/draw-frame (animated title) — wrapped with sfx/sync-begin! … sfx/flush-frame!.
• Animated descent screen — the per-frame dotimes loop is now wrapped per frame, not left on a bare term/flush.
• screenfx/clear-screen — wrapped; the only remaining term/flush in that file is the one inside flush-frame! itself.

So the three paths called out before (title, descent, clear-screen) no longer emit large frames with a plain flush. Grepped title.lg / screenfx.lg to confirm there are no stray unwrapped frame flushes left.

Rebased onto latest main so the diff is now a single clean commit (#145/#146 already merged; picked up #170/#171). Verified locally: compile smoke passes, and the full suite is green — 305 tests / 2801 assertions, 0 failures — including the new escape-guard tests that lock the exact CSI ?2026 h/l sequences.

LGTM.

[mparrett]

@nnunley Double checked, this one is now rebased and ready for a final look.

[nnunley]

So. I think having something like (with-frame ...) that controls the boundaries of the sync, with a (finally...) block that completes the action might avoid having a stack of accidentally nested syncs, or dangling syncs.

[mparrett]

Follow-up on the earlier suggestion — the (with-frame ...) idea (a try/finally that guarantees the sync closes even if a frame throws, so begin/end can't drift or dangle) is implemented in #174, stacked on this branch. Kept it separate so it doesn't reset the review here; the diff there is just the refactor on top of this PR.

[mparrett]

@nnunley Thanks again for the nudge, it's definitely better. If you're good with it, I'll merge this one after re-approval, and we can continue the discussion and land #174 - curious if you lean a certain way on whether to explicitly handle nesting/depth. (I think we probably should but there are nuances)