Skip to content

Commit 60ead03

Browse files
committed
Document that the landing clocks pre-session snow
The monitor stays quiet when idle, which is correct for turn chrome. The landing is idle by definition and still wants motion, so it owns a mount-scoped timer for its lifetime. Driving the mark from the renderer FRAME event was rejected because FRAME follows dirty rows and self-starves under throttle.
1 parent df0dbe4 commit 60ead03

2 files changed

Lines changed: 20 additions & 4 deletions

File tree

docs/TUI.md

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -155,8 +155,10 @@ The notice is a live diagnosis, not a sticky banner: it comes down on the
155155
same paint as the activity that ends the silence, including when the turn
156156
settles before the next monitor tick.
157157

158-
An idle session animates nothing at all: the monitor tick stops entirely
159-
rather than repainting an unchanging frame.
158+
An idle session's turn chrome animates nothing at all: the monitor tick
159+
stops entirely rather than repainting an unchanging frame. Pre-session
160+
motion belongs to the landing's mount lifetime, not the monitor (see the
161+
idle landing below).
160162

161163
Color is a small, deliberate palette, not decoration
162164
(`src/tui/theme.ts`). Dimmed text is a dimmed cream, never a neutral
@@ -427,6 +429,20 @@ landing screen at, say, 23 rows gets an 8-row cap instead of 9. This is a
427429
known, accepted cost of the badge rather than an oversight — see
428430
`terminalForGeometry`'s doc comment in `shell.ts` for the exact mechanism.
429431

432+
While the landing is mounted, a mount-scoped ~8 fps timer
433+
(`LANDING_IDLE_REPAINT_INTERVAL_MS` in `src/tui/shell.ts`) advances snow
434+
across a frozen mountain. It is cancelled on the first real transcript
435+
row (`clearLandingMark`) or on shell dispose, and does not run during a
436+
session. `still` freezes the mountain's draw/fill/fade timeline only;
437+
snow still drifts on the idle landing. Reduced-motion, when a setting
438+
exists, suppresses snow via `reducedMotion` on `renderMark` — not via
439+
`still`. There is no live TUI setting yet.
440+
441+
The mark is not driven from the renderer's FRAME event: FRAME follows
442+
dirty rows, not a clock, so that path self-starves under throttle.
443+
Keeping the monitor ticking on idle would mix turn-chrome cadence into a
444+
pre-session surface; the monitor idle-stop stays correct for turn chrome.
445+
430446
The model/provider picker is one flat, type-to-filter list
431447
(`src/tui/product-host.ts` + `openModelPickerOverlay({ typeToFilter: true })`):
432448
recent and favorite provider+model pairs sit at the top, then every

src/tui/mark-anim.ts

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,8 @@
1616
* that does suppress snow. Mountain cells always win over flakes.
1717
*
1818
* Everything here is pure and clock-injected: `nowMs` is the only time source,
19-
* so the caller's existing 250 ms status tick drives the animation and tests
20-
* drive it deterministically. There is no timer in this module.
19+
* so tests drive it deterministically. The idle caller is the landing timer;
20+
* the turn caller is the monitor. There is no timer in this module.
2121
*/
2222

2323
import { MARK_SMALL, type MarkGrid } from "./mark-shape.js";

0 commit comments

Comments
 (0)