Make the landing snow actually render on an idle screen

Three independent gates kept the falling-snow decoration over the landing
mountain from ever drawing: the mount-time paint was still=true, which the
old snowOn check tied directly to snow visibility; paintLanding early-returned
whenever it wasn't re-entered with animating=true, which never happens while
idle; and its only caller was the turn monitor, which deliberately stops
ticking once idle.

Fix: snow visibility no longer depends on `still` (that flag now only freezes
the mountain's own draw/fill/fade timeline, not the flakes over it), the
early-return is gone so idle repaints actually happen, and the shell's
createAppShell now repaints the landing off the renderer's own FRAME event
whenever the landing is up and not mid-turn-animation. That event is already
scoped to shell lifetime (wired at construction, unwired in dispose) and
paintLanding already no-ops once the landing tears down, so this needed no
new timer to arm or leak, and it doesn't touch the turn monitor's cadence at
all. The alternative — a separate timer armed from createLandingAbove and
stopped in the landing teardown — was rejected: it would duplicate the
monitor's own cadence-management responsibility for no real gain, since the
FRAME event already has the right lifetime.

Added a real-mount-path regression test in landing.test.ts that goes through
createAppShell and lets the renderer's FRAME event drive the repaint, unlike
every existing test in that file, which drives the mark by calling
paintLanding directly with a hand-picked clock. That gap is exactly why this
shipped broken and nobody caught it.

This supersedes PR #380, which added the snow-drawing code but never made it
reachable; that PR should stay open until this one is reviewed and can then
be closed in favor of this one.

Author: TheGreatAxios

src/tui-opentui/landing.test.ts

@@ -38,6 +38,7 @@ import {
 import { LOCKUP_WORDMARK } from "./lockup"
 import pkg from "../../package.json" with { type: "json" }
 import { MARK_LARGE, MARK_MID, MARK_SMALL } from "./mark-shape"
+import { SNOW_CHAR } from "./mark-anim"
 import { UI } from "./theme"
 
 const SIZE = { width: 80, height: 24 } as const
@@ -229,11 +230,14 @@ describe("landing screen", () => {
       try {
         await settle(h)
         const still = markRows(h).join("\n")
+        const stripSnow = (text: string) => text.replaceAll(SNOW_CHAR, " ")
 
-        // Idle re-entry holds the filled frame however far the clock moves.
+        // Idle re-entry holds the mountain's filled frame however far the
+        // clock moves — but the snow drifting over it is not still, since the
+        // idle landing screen is exactly where it needs to animate.
         paintLanding(shell, 1_700, false)
         await settle(h)
-        expect(markRows(h).join("\n")).toBe(still)
+        expect(stripSnow(markRows(h).join("\n"))).toBe(stripSnow(still))
 
         const frames = new Set<string>()
         for (const nowMs of [0, 500, 1_100, 1_900, 2_600, 3_400]) {
@@ -248,6 +252,49 @@ describe("landing screen", () => {
     }, SIZE)
   })
 
+  test(
+    "an idle mount keeps the snow drifting on the renderer's own frame event",
+    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`.
+      await withTestRenderer(async (h) => {
+        const shell = createAppShell(h.renderer, {
+          terminal: { columns: 80, rows: 24 },
+          wireKeys: false,
+          run: "idle",
+        })
+        try {
+          await settle(h)
+          const before = markRows(h).join("\n")
+
+          // 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()
+          }
+          const after = markRows(h).join("\n")
+
+          expect(after).not.toBe(before)
+
+          const stripSnow = (text: string) => text.replaceAll(SNOW_CHAR, " ")
+          expect(stripSnow(after)).toBe(stripSnow(before))
+        } finally {
+          shell.dispose()
+        }
+      }, SIZE)
+    },
+    15_000,
+  )
+
   test("a starter key fills the prompt; a typed prompt keeps its digits", async () => {
     await withTestRenderer(async (h) => {
       const shell = createAppShell(h.renderer, {

src/tui-opentui/mark-anim.test.ts

@@ -106,19 +106,38 @@ describe("renderMark", () => {
     const grid = renderMark({ nowMs: 0, still: true, grid: MARK_LARGE })
     grid.forEach((row, y) => {
       row.forEach((cell, x) => {
-        // Still mode has no snow — only space or mountain blocks.
-        expect(` ${MOUNTAIN_CHARS}`).toContain(cell.char)
+        // Still mode freezes the mountain, but snow still drifts over the sky.
+        expect(` ${MOUNTAIN_CHARS}${SNOW_CHAR}`).toContain(cell.char)
         if ((MARK_LARGE.coverage[y]?.[x] ?? 0) === 1) expect(cell.char).toBe("█")
       })
     })
   })
 
-  test("the still frame is clock-independent and has no snow", () => {
-    const a = markText(renderMark({ nowMs: 0, still: true }))
-    const b = markText(renderMark({ nowMs: 987_654, still: true }))
+  test("still holds the mountain fixed while the clock advances", () => {
+    // Snow moves with the clock even in still mode (the idle landing screen),
+    // so isolate the mountain by stripping snow before comparing.
+    const stripSnow = (text: string) => text.replaceAll(SNOW_CHAR, " ")
+    const a = stripSnow(markText(renderMark({ nowMs: 0, still: true })))
+    const b = stripSnow(markText(renderMark({ nowMs: 987_654, still: true })))
     expect(b).toBe(a)
     expect(a.replace(/[\s\n]/g, "").length).toBeGreaterThan(0)
-    expect(a.includes(SNOW_CHAR)).toBe(false)
+  })
+
+  test("snow keeps drifting in still mode while the mountain stays frozen", () => {
+    const times = [0, 1500, 3000, 4500, 6000, 7500]
+    const snowSets = times.map((nowMs) => {
+      const grid = renderMark({ nowMs, still: true, grid: MARK_LARGE })
+      const snow: string[] = []
+      grid.forEach((row, y) => {
+        row.forEach((cell, x) => {
+          if (isSnow(cell.char)) snow.push(`${y},${x}`)
+        })
+      })
+      return snow.join("|")
+    })
+    const withSnow = snowSets.filter((s) => s.length > 0)
+    expect(withSnow.length).toBeGreaterThan(1)
+    expect(new Set(withSnow).size).toBeGreaterThan(1)
   })
 
   test("the animated frame advances with the injected clock", () => {
@@ -203,11 +222,12 @@ describe("renderMark", () => {
     expect(mountains).toBeGreaterThan(flakes)
   })
 
-  test("still mode freezes the mark with no snow motion", () => {
+  test("still mode freezes the mountain but not the snow", () => {
     const a = renderMark({ nowMs: 0, still: true, grid: MARK_SMALL })
     const b = renderMark({ nowMs: 50_000, still: true, grid: MARK_SMALL })
-    expect(markText(b)).toBe(markText(a))
-    expect(a.flat().some((cell) => isSnow(cell.char))).toBe(false)
+    const mountainText = (grid: typeof a) =>
+      grid.map((row) => row.map((cell) => (isMountain(cell.char) ? cell.char : " ")).join("")).join("\n")
+    expect(mountainText(b)).toBe(mountainText(a))
   })
 
   test("snow drops out during the fade-out phase, matching the mark", () => {

src/tui-opentui/mark-anim.ts

@@ -9,8 +9,11 @@
  *
  * Over the sky (zero-coverage cells) a sparse field of pixel snow falls on the
  * same injected clock. Density and speed stay low so the ridgeline keeps its
- * silhouette; `still` (idle or reduced motion) freezes the mark and drops the
- * snow entirely. Mountain cells always win over flakes.
+ * silhouette; `still` (idle or reduced motion) freezes the mountain's own
+ * draw/fill/fade timeline to its fully-filled frame, but snow keeps drifting —
+ * the landing screen is idle by definition, so tying snow to the same flag
+ * that freezes the mountain would mean it never falls. Mountain cells always
+ * win over flakes.
  *
  * Everything here is pure and clock-injected: `nowMs` is the only time source,
  * so the caller's existing 250 ms status tick drives the animation and tests
@@ -94,7 +97,11 @@ export type MarkCell = {
 
 export type MarkInput = {
   readonly nowMs: number
-  /** Hold the mark still: idle session, or reduced motion. */
+  /**
+   * Hold the mountain's draw/fill/fade timeline on its fully-filled frame:
+   * idle session, or reduced motion. Snow is not gated by this — see
+   * `snowOn` in `renderMark`.
+   */
   readonly still: boolean
   /** Which baked rasterization to composite. Defaults to the compact grid. */
   readonly grid?: MarkGrid
@@ -149,9 +156,10 @@ export function renderMark(input: MarkInput): readonly (readonly MarkCell[])[] {
   const { drawProg, fillProg, alpha } = markFrame(seconds, input.still)
   const revealed = drawProg * shape.cols
   const fillLine = shape.rows * (1 - fillProg)
-  // Fade out drops the snow too so the decoration doesn't outlast the mark
-  // it drifts over.
-  const snowOn = !input.still && alpha === 1
+  // Independent of `still`: the mountain can be frozen full while snow still
+  // drifts (the idle landing screen). Fade out drops the snow too so the
+  // decoration doesn't outlast the mark it drifts over.
+  const snowOn = alpha === 1
 
   const grid: MarkCell[][] = []
   for (let row = 0; row < shape.rows; row++) {

src/tui-opentui/shell.ts

@@ -2556,13 +2556,15 @@ function clearLandingMark(shell: AppShell): void {
 }
 
 /**
- * Repaint the landing mark for `nowMs`. `animating` runs the draw/fill/fade
- * timeline; anything else holds the filled frame. No-op once the landing is
- * gone, so the caller can drive it unconditionally.
+ * Repaint the landing mark for `nowMs`. `animating` runs the mountain's
+ * draw/fill/fade timeline; anything else holds its filled frame. No-op once
+ * the landing is gone, so the caller can drive it unconditionally.
  *
- * A still mark draws the same frame for every clock value, so repainting it
- * only dirties renderables; the guard mirrors `setLockupFrame` and lets an idle
- * session sit without touching the paint tree.
+ * 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. `paintLandingMark`/`renderMark`
+ * only touch the rows whose content actually changed, so the unchanging
+ * mountain rows cost nothing extra here.
  */
 export function paintLanding(
   shell: AppShell,
@@ -2572,7 +2574,6 @@ export function paintLanding(
   const bag = internals.get(shell)
   const landing = bag?.landing
   if (bag === undefined || landing === null || landing === undefined) return
-  if (!animating && !bag.landingAnimating) return
   bag.landingAnimating = animating
   bag.landingNowMs = nowMs
   paintLandingMark(landing.above, nowMs, !animating)
@@ -5599,6 +5600,21 @@ 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.
+    const landingBag = internals.get(shell)
+    if (landingBag?.landing != null && !landingBag.landingAnimating) {
+      paintLanding(shell, Date.now(), false)
+    }
   }
 
   const onResize = (width: number, height: number): void => {