Honor reduced motion on the landing mount path

Author: TheGreatAxios

docs/TUI.md

@@ -434,9 +434,10 @@ across a frozen mountain. It is cancelled on the first real transcript
 row or on shell dispose. Deferred system notices do not count. While
 the landing is still up, the callback no-ops if a turn is already
 driving the mark. `still` freezes the mountain's draw/fill/fade
-timeline only; snow still drifts. Reduced motion drops snow at
-`renderMark` independently of `still`; the idle timer always paints
-with that hook off.
+timeline only; snow still drifts. Reduced motion
+(`AppShellOptions.reducedMotion`, forwarded from `ProductHostConfig`)
+never starts that timer and paints a still mountain with no snow, even
+when a caller asks `paintLanding` to animate.
 
 That timer is the pre-session frame source. The renderer FRAME event
 follows dirty rows, not a clock, and starves under throttle. The turn

src/tui/landing.test.ts

@@ -56,7 +56,6 @@ const nativeClearInterval = globalThis.clearInterval;
  * export.
  */
 const LANDING_IDLE_REPAINT_INTERVAL_MS = 125;
-const SNOW_SAMPLE_CLOCKS_MS = [0, 1500, 3000, 4500, 6000, 7500] as const;
 const stripSnow = (text: string) => text.replaceAll(SNOW_CHAR, " ");
 
 interface IdleTimerHandle {
@@ -363,36 +362,31 @@ describe("landing screen", () => {
       globalThis.clearInterval = nativeClearInterval;
     });
 
-    test("paintLanding with reducedMotion draws no snow on a clock that otherwise snows", async () => {
-      wrapLandingIdleTimer();
+    test("reduced-motion mount never arms the idle timer and never draws snow", async () => {
+      const { armed } = wrapLandingIdleTimer();
       await withTestRenderer(async (h) => {
         const shell = createAppShell(h.renderer, {
           terminal: { columns: 80, rows: 24 },
           wireKeys: false,
           run: "idle",
+          reducedMotion: true,
         });
         try {
+          expect(armed).toHaveLength(0);
           await settle(h);
-          let snowingAt: number | undefined;
-          let snowing = "";
-          for (const nowMs of SNOW_SAMPLE_CLOCKS_MS) {
-            paintLanding(shell, nowMs, false, false);
+          const first = markRows(h).join("\n");
+          expect(first.includes(SNOW_CHAR)).toBe(false);
+          expect(first.length).toBeGreaterThan(0);
+
+          const frames = new Set<string>([first]);
+          for (const nowMs of [0, 500, 1_100, 1_900, 2_600, 3_400]) {
+            paintLanding(shell, nowMs, true);
             await settle(h);
             const frame = markRows(h).join("\n");
-            if (frame.includes(SNOW_CHAR)) {
-              snowingAt = nowMs;
-              snowing = frame;
-              break;
-            }
-          }
-          if (snowingAt === undefined) {
-            throw new Error("expected a still-mode clock that draws snow through paintLanding");
+            expect(frame.includes(SNOW_CHAR)).toBe(false);
+            frames.add(frame);
           }
-          paintLanding(shell, snowingAt, false, true);
-          await settle(h);
-          const quiet = markRows(h).join("\n");
-          expect(quiet.includes(SNOW_CHAR)).toBe(false);
-          expect(stripSnow(quiet)).toBe(stripSnow(snowing));
+          expect(frames.size).toBe(1);
         } finally {
           shell.dispose();
         }

src/tui/landing.ts

@@ -290,7 +290,7 @@ export interface LandingAbove {
  * Rows are allocated for the largest tier once and hidden from the top down as
  * smaller tiers are selected, so a resize never rebuilds the subtree.
  */
-export function createLandingAbove(ctx: CliRenderer): LandingAbove {
+export function createLandingAbove(ctx: CliRenderer, reducedMotion = false): LandingAbove {
   const box = new BoxRenderable(ctx, {
     id: "shell-landing-above",
     width: "100%",
@@ -346,7 +346,7 @@ export function createLandingAbove(ctx: CliRenderer): LandingAbove {
     grid: MARK_SMALL,
   };
   fitLandingMark(above, MARK_SMALL);
-  paintLandingMark(above, 0, true);
+  paintLandingMark(above, 0, true, reducedMotion);
   return above;
 }
 

src/tui/product-host.ts

@@ -175,6 +175,11 @@ export interface ProductHostConfig {
   readonly turnMonitor?: TurnMonitorOptions;
   /** First-run telemetry disclosure, shown on the landing screen. */
   readonly telemetryNotice?: string;
+  /**
+   * Suppress landing snow and mountain motion. Forwarded to the shell at
+   * mount; the idle timer is never armed.
+   */
+  readonly reducedMotion?: boolean;
   /**
    * Take DEC mouse reporting. Default true: wheel/trackpad scroll only
    * reaches OpenTUI when the terminal is told to report it, otherwise the
@@ -311,6 +316,7 @@ export async function mountProductHost(config: ProductHostConfig): Promise<Produ
     ...(config.onCommand !== undefined ? { onCommand: config.onCommand } : {}),
     ...(config.onObserveRequest !== undefined ? { onObserveRequest: config.onObserveRequest } : {}),
     ...(config.telemetryNotice !== undefined ? { telemetryNotice: config.telemetryNotice } : {}),
+    ...(config.reducedMotion === true ? { reducedMotion: true } : {}),
   });
 
   // Announced on the notice strip (or transcript once the session has content)

src/tui/shell.ts

@@ -505,6 +505,11 @@ export interface AppShellOptions {
    * notice has been shown, so it is not permanent chrome.
    */
   readonly telemetryNotice?: string;
+  /**
+   * Suppress landing snow and mountain motion. The idle timer is not
+   * armed, and `paintLanding` holds a still mountain with no flakes.
+   */
+  readonly reducedMotion?: boolean;
   /**
    * Clipboard port for Alt+C and drag-select auto-copy. Defaults to an
    * in-memory recorder so tests and demos never shell out; the product host
@@ -1811,7 +1816,7 @@ export function applyLayout(shell: AppShell, layout: GeometryLayout): void {
     // A new zone can seat a different tier, and a tier is a different grid, so
     // the mark is redrawn rather than left showing the previous size's frame.
     fitLandingMark(landing.above, resolveMarkGrid(split.above, layout.contentWidth));
-    paintLandingMark(landing.above, bag.landingNowMs, !bag.landingAnimating);
+    paintLandingMark(landing.above, bag.landingNowMs, !bag.landingAnimating, bag.reducedMotion);
     landing.below.height = Math.max(0, split.below);
     landing.below.visible = split.below > 0;
   }
@@ -2109,6 +2114,12 @@ interface ShellInternals {
   landingAnimating: boolean;
   /** Clock of the last painted mark frame, so a resize can redraw in place. */
   landingNowMs: number;
+  /**
+   * Mount-time reduced-motion flag. When true, the idle snow timer is
+   * never armed and every landing paint holds a still mountain with no
+   * flakes. Set once at `createAppShell`; not a per-paint argument.
+   */
+  reducedMotion: boolean;
   /**
    * Cancels the mount-scoped idle repaint timer armed in `createAppShell`,
    * or null while none is armed. Cleared by whichever teardown happens
@@ -2813,19 +2824,19 @@ const LANDING_IDLE_REPAINT_INTERVAL_MS = 125;
  * needs to drift across a frozen mountain. Driven by the mount-scoped timer
  * armed in `createAppShell` rather than a render event, so the repaint
  * cadence is independent of however often the renderer happens to paint.
+ *
+ * Reduced motion is a mount-time flag on the shell, not a per-paint
+ * argument: it freezes the mountain and drops snow even when a caller
+ * asks for `animating`.
  */
-export function paintLanding(
-  shell: AppShell,
-  nowMs: number,
-  animating: boolean,
-  reducedMotion = false,
-): void {
+export function paintLanding(shell: AppShell, nowMs: number, animating: boolean): void {
   const bag = internals.get(shell);
   const landing = bag?.landing;
   if (bag === undefined || landing === null || landing === undefined) return;
-  bag.landingAnimating = animating;
+  const motion = bag.reducedMotion ? false : animating;
+  bag.landingAnimating = motion;
   bag.landingNowMs = nowMs;
-  paintLandingMark(landing.above, nowMs, !animating, reducedMotion);
+  paintLandingMark(landing.above, nowMs, !motion, bag.reducedMotion);
 }
 
 /** True while the landing composition is still mounted. */
@@ -5749,6 +5760,7 @@ export function createAppShell(renderer: ShellRenderer, options?: AppShellOption
   const paletteCatalogOpt = options?.paletteCatalog ?? null;
   const onCommandOpt = options?.onCommand;
   const onObserveRequestOpt = options?.onObserveRequest;
+  const reducedMotion = options?.reducedMotion === true;
 
   const terminal = terminalOf(renderer, options?.terminal);
   const layout = resolveGeometry({
@@ -5865,7 +5877,7 @@ export function createAppShell(renderer: ShellRenderer, options?: AppShellOption
   });
   transcript.add(transcriptSpacer);
 
-  const landingAbove = createLandingAbove(ctx);
+  const landingAbove = createLandingAbove(ctx, reducedMotion);
   const landingBelowState = landingBelowContent({
     rows: splitLandingRows(layout.heights.transcript).below,
     columns: layout.contentWidth,
@@ -6650,6 +6662,7 @@ export function createAppShell(renderer: ShellRenderer, options?: AppShellOption
     landingSuggestionsVisible: true,
     landingAnimating: false,
     landingNowMs: 0,
+    reducedMotion,
     landingIdleTimerCancel: null,
     chrome: { task: [], tasksRaw: [], agents: [] },
     // CL-5847: the manage_tasks checklist panel is hidden by default. The
@@ -6679,22 +6692,27 @@ export function createAppShell(renderer: ShellRenderer, options?: AppShellOption
   // 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);
+  //
+  // Reduced motion never starts the timer: there is no snow to advance
+  // and the mountain stays on its filled frame.
+  if (!reducedMotion) {
+    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);