Drive the idle landing repaint off a mount-scoped timer, not a throttled FRAME hook

The FRAME-driven throttle added in the previous commit killed the landing's
self-driving loop entirely: the renderer only keeps rendering because each
paint dirties a row, which schedules the next FRAME; skipping a paint on a
throttled tick breaks that chain on the very next frame and the snow freezes
after the first paint. Any throttle above zero frames has the same effect,
since the throttle and the frame source were the same mechanism.

Replace it with a plain ~125ms interval armed when the shell mounts (the
landing exists for the lifetime of the shell until the first transcript row
tears it down) and cleared on whichever teardown happens first: the landing
going away, or the shell disposing. The timer self-cancels once the renderer
reports destroyed, so headless test harnesses that skip explicit
shell.dispose() don't leave it firing against torn-down renderables.

Also replace the test's manual renderOnce-loop clock with a real wall-clock
wait and no frame pumping at all, so the test can no longer stay green while
production's self-driving mechanism is dead — that blind spot is exactly how
the frozen throttle shipped in the first place.

Author: TheGreatAxios

src/tui-opentui/landing.test.ts

@@ -253,16 +253,17 @@ describe("landing screen", () => {
   })
 
   test(
-    "an idle mount keeps the snow drifting on the renderer's own frame event",
+    "an idle mount keeps the snow drifting on its own, with nothing pumping frames by hand",
     async () => {
       // Regression for CL-5737: every other test in this file drives the mark
       // by calling `paintLanding` directly with a hand-picked clock. That is
       // exactly why the landing snow shipped completely unreachable — none of
       // those tests go through the real driver a running session actually
-      // uses. This one mounts the shell for real and lets the renderer's own
-      // FRAME event (wired in `createAppShell`, unwired in `shell.dispose`)
-      // drive the repaint, the same as production, with no direct calls to
-      // `paintLanding` or `renderMark`.
+      // uses. This one mounts the shell for real and lets it repaint itself:
+      // no `paintLanding`/`renderMark` calls, and critically no `renderOnce`
+      // loop either while waiting — a test that pumps frames by hand can stay
+      // green even when production's self-driving mechanism is dead, which is
+      // exactly the blind spot that let the throttled build ship frozen snow.
       await withTestRenderer(async (h) => {
         const shell = createAppShell(h.renderer, {
           terminal: { columns: 80, rows: 24 },
@@ -273,24 +274,13 @@ describe("landing screen", () => {
           await settle(h)
           const before = markRows(h).join("\n")
 
-          // A burst of frames faster than the ~125ms idle-repaint throttle
-          // must not each produce a distinct paint: the FRAME event fires
-          // from inside the render loop, so an unthrottled repaint here is
-          // exactly the uncapped render-loop regression this guards against.
-          const burstStart = Date.now()
-          while (Date.now() - burstStart < 60) {
-            await h.renderOnce()
-          }
-          expect(markRows(h).join("\n")).toBe(before)
-
-          // Real elapsed time, not an injected clock: the production driver
-          // reads the wall clock, so this is the only way to exercise it.
-          // At the fall speed in mark-anim.ts a few real seconds is enough
-          // for at least one active flake column to cross a row boundary.
-          const start = Date.now()
-          while (Date.now() - start < 5_000) {
-            await h.renderOnce()
-          }
+          // Real wall-clock wait, no renderOnce in between: only the mount's
+          // own idle-repaint timer can be advancing the snow here. `flush`
+          // waits on the renderer's own scheduler settling rather than
+          // forcing frames, so it does not manufacture the motion itself.
+          await new Promise((resolve) => setTimeout(resolve, 3_000))
+
+          await h.flush()
           const after = markRows(h).join("\n")
 
           expect(after).not.toBe(before)

src/tui-opentui/shell.ts

@@ -471,7 +471,7 @@ function dispatchOverlayAccept(
 /** Renderer surface required by the shell (CliRenderer / createTestRenderer). */
 export type ShellRenderer = Pick<
   CliRenderer,
-  "root" | "width" | "height" | "keyInput" | "on" | "off"
+  "root" | "width" | "height" | "keyInput" | "on" | "off" | "isDestroyed"
 >
 
 export type AppShellOptions = {
@@ -1931,11 +1931,12 @@ type ShellInternals = {
   /** Clock of the last painted mark frame, so a resize can redraw in place. */
   landingNowMs: number
   /**
-   * Wall-clock time of the last idle-driven landing repaint (the FRAME-event
-   * path in `createAppShell`'s `onFrame`), so that path can throttle itself
-   * to ~8fps instead of repainting on every render pass.
+   * Cancels the mount-scoped idle repaint timer (see `armLandingIdleTimer`
+   * in `createAppShell`), or null while none is armed. Cleared by whichever
+   * teardown happens first — the landing going away (`clearLandingMark`) or
+   * the whole shell disposing (`dispose`) — so it can never outlive either.
    */
-  landingLastIdlePaintMs: number
+  landingIdleTimerCancel: (() => void) | null
   /** Chrome content (empty array = zone off). */
   chrome: {
     /**
@@ -2539,6 +2540,8 @@ function clearLandingMark(shell: AppShell): void {
   const landing = bag?.landing
   if (bag === undefined || landing === null || landing === undefined) return
   bag.landing = null
+  bag.landingIdleTimerCancel?.()
+  bag.landingIdleTimerCancel = null
   shell.transcript.remove(landing.above.box)
   destroySubtree(landing.above.box)
   shell.root.remove(landing.below)
@@ -2562,10 +2565,9 @@ function clearLandingMark(shell: AppShell): void {
 }
 
 /**
- * Minimum spacing between idle-driven landing repaints (~8fps). The snow
- * only needs to advance about half a row per second, so this is well above
- * the animation's actual needs while staying far below the render engine's
- * uncapped max rate.
+ * Cadence of the mount-scoped idle repaint timer (see `armLandingIdleTimer`
+ * in `createAppShell`). The snow only needs to advance about half a row per
+ * second, so ~8fps is comfortably enough to read as motion.
  */
 const LANDING_IDLE_REPAINT_INTERVAL_MS = 125
 
@@ -2576,11 +2578,10 @@ const LANDING_IDLE_REPAINT_INTERVAL_MS = 125
  *
  * Always repaints while the landing is up, even when `animating` is false:
  * the landing is idle by definition (no turn processing), and snow still
- * needs to drift across a frozen mountain. Every call reassigns a fresh
- * `StyledText` to every row regardless of whether its content changed, which
- * unconditionally dirties the renderables and requests another render — the
- * idle-driven call site in `createAppShell`'s `onFrame` throttles how often
- * it calls this rather than relying on this function to skip unchanged rows.
+ * needs to drift across a frozen mountain. Driven by the mount-scoped timer
+ * armed in `createAppShell` (see `armLandingIdleTimer`) rather than a render
+ * event, so the repaint cadence is independent of however often the renderer
+ * happens to paint.
  */
 export function paintLanding(
   shell: AppShell,
@@ -5617,38 +5618,6 @@ export function createAppShell(
     // starves that pass of room to lay the row out in.
     syncTranscriptSpacer(shell)
     syncNoticeAfterLayout(shell)
-    // The landing's snow needs a frame source that keeps running while the
-    // turn monitor is deliberately quiet (idle, no session yet). The renderer
-    // FRAME event is already scoped to shell lifetime (wired here, unwired in
-    // `dispose` below) and `paintLanding` no-ops once the landing tears down,
-    // so riding it costs no extra timer to arm or leak.
-    //
-    // Only re-enters while idle (`landingAnimating` already false): while a
-    // turn is processing, `paintPhaseAt` in runtime-bridge.ts drives the
-    // mountain's own draw/fill/fade loop off the turn monitor's clock, and
-    // this re-entry must not stomp that with an unrelated real-clock value
-    // every render pass.
-    //
-    // FRAME fires from inside the render loop itself, and `paintLanding`
-    // always reassigns fresh row content (see its docblock), which
-    // unconditionally dirties the renderables and requests another render.
-    // Left unthrottled that turns into a perpetual render loop at the
-    // engine's max frame rate rather than the app's configured target, for
-    // as long as the landing sits idle on screen. The snow only needs to
-    // advance about half a row per second, so gating repaints to roughly
-    // every `LANDING_IDLE_REPAINT_INTERVAL_MS` keeps the animation smooth
-    // at a fraction of the render cost.
-    const landingBag = internals.get(shell)
-    if (landingBag?.landing != null && !landingBag.landingAnimating) {
-      const nowMs = Date.now()
-      if (
-        nowMs - landingBag.landingLastIdlePaintMs >=
-        LANDING_IDLE_REPAINT_INTERVAL_MS
-      ) {
-        landingBag.landingLastIdlePaintMs = nowMs
-        paintLanding(shell, nowMs, false)
-      }
-    }
   }
 
   const onResize = (width: number, height: number): void => {
@@ -5737,6 +5706,7 @@ export function createAppShell(
       }
       renderer.off(CliRenderEvents.FRAME, onFrame)
       renderer.off(CliRenderEvents.RESIZE, onResize)
+      internals.get(shell)?.landingIdleTimerCancel?.()
       flashTimers.get(shell)?.()
       flashTimers.delete(shell)
       try {
@@ -5776,10 +5746,48 @@ export function createAppShell(
     landingSuggestionsVisible: true,
     landingAnimating: false,
     landingNowMs: 0,
-    landingLastIdlePaintMs: 0,
+    landingIdleTimerCancel: null,
     chrome: { task: [], tasksRaw: [], agents: [] },
     tasksPanelHidden: false,
   })
+  // The landing's snow needs a frame source that keeps running while the
+  // turn monitor is deliberately quiet (idle, no session yet). A plain timer
+  // armed at mount is that source: it does not depend on the renderer
+  // scheduling further frames, so it cannot stall the way riding the
+  // renderer's own FRAME event did (see CL-5737 history in the PR).
+  //
+  // Only repaints while idle (`landingAnimating` false): while a turn is
+  // processing, `paintPhaseAt` in runtime-bridge.ts drives the mountain's
+  // own draw/fill/fade loop off the turn monitor's clock, and this timer
+  // must not stomp that with an unrelated real-clock value.
+  //
+  // Cleared on whichever teardown happens first: the landing going away
+  // (`clearLandingMark`, first transcript row) or the whole shell disposing
+  // (`dispose` below, e.g. tests that never grow a transcript).
+  //
+  // Also self-cancels on `renderer.isDestroyed`: a real terminal session
+  // always disposes the shell, but headless test harnesses commonly destroy
+  // the renderer directly (`withTestRenderer`'s cleanup) without ever
+  // calling `shell.dispose()`. Without this check the timer would keep
+  // firing against renderables the harness already tore down.
+  const landingIdleHandle = setInterval(() => {
+    if (renderer.isDestroyed) {
+      clearInterval(landingIdleHandle)
+      return
+    }
+    const bag = internals.get(shell)
+    if (bag?.landing == null || bag.landingAnimating) return
+    paintLanding(shell, Date.now(), false)
+  }, LANDING_IDLE_REPAINT_INTERVAL_MS)
+  landingIdleHandle.unref?.()
+  {
+    const bag = internals.get(shell)
+    if (bag !== undefined) {
+      bag.landingIdleTimerCancel = () => clearInterval(landingIdleHandle)
+    } else {
+      clearInterval(landingIdleHandle)
+    }
+  }
   transcriptSpacers.set(shell, transcriptSpacer)
   if (onCommandOpt) setPaletteOnCommand(shell, onCommandOpt)
   if (onObserveRequestOpt) {