refactor(render): (with-frame ...) — RAII-style synced frame boundaries

[mparrett]

Re-opens #174, which GitHub auto-closed as a side effect of deleting #149's
branch on merge (its base, perf/render-sync-output, no longer existed, and
GitHub refuses to reopen or retarget a PR once that happens) — not a
concern about the code. Same branch, same commit (087ec53), already
reviewed and approved by nnunley on #174 against this exact diff.

What

Replaces the hand-written (sfx/sync-begin!) … (sfx/flush-frame!) pairs at
every full-screen frame boundary with a single macro:

(defmacro with-frame
  [& body]
  `(do
     (xsofy.screenfx/sync-begin!)
     (try
       ~@body
       (finally (xsofy.screenfx/flush-frame!)))))

Every frame emitter becomes (sfx/with-frame …): render-full, render-dirty, animate-vfx!, the six modal screens, screenfx/clear-screen, and title's draw-frame + descent loop.

Why

Addresses the review note on #149: a with-frame with a finally makes the sync boundary structural instead of a matched pair a future edit can split.

• Dangling syncs — fixed deterministically. perf(render): synchronized output (DEC 2026) across all frame renders #149's own design note admits a frame that throws before end-sync "leaves the mode on, but the terminal's own 2026 timeout releases it." The finally closes it immediately, no reliance on that timeout.
• Begin/end can't drift. They're generated as one form, so an early return or a newly inserted branch can't skip the close.

Notes

• Not nesting-safe, by design — mode 2026 is a boolean, so an inner with-frame's finally would close the outer frame early. Preserves perf(render): synchronized output (DEC 2026) across all frame renders #149's "wrap only top-level frames" discipline. Documented in the macro's docstring.
• commit-camera! hoisted just past the frame boundary in render-full/render-dirty — it only mutates the @last-camera atom (no terminal output), behavior-preserving.
• let-go quirk: the macro fully-qualifies xsofy.screenfx/* since let-go's syntax-quote doesn't auto-namespace symbols (let-go#48), matching the existing with-folded-salt convention.

Tests

just check clean; full suite green — 307 tests / 2803 assertions, 0 failures — including the existing render golden tests and two new guards: the balanced begin/body/end pair, and end-sync-on-throw.

[mparrett]

Superseded by #174 — retargeting that one to main now that the branch is rebased/conflict-resolved (this duplicate was only needed while #174 couldn't be reopened).

[github-actions]

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