@groeponline/pi-wishcraft 1.16.0 → 1.23.0

package/src/extension/session/session-lifecycle.ts

@@ -4,6 +4,7 @@ import { BashTranscriptStore } from "../../../bash-mode/transcript.ts";
 import { BashCompletionEngine } from "../../../bash-mode/completion.ts";
 import { parsePowerlineConfig } from "../../config/powerline-config.ts";
 import { policyFromEnvironment } from "../../motion/accessibility.ts";
+import { defaultMotionFor } from "../../motion/catalog.ts";
 import { registerCustomSegments } from "../../segments/index.ts";
 import { registerCustomPresets } from "../../config/presets.ts";
 import { invalidateGitStatus } from "../../git/status.ts";
@@ -34,6 +35,7 @@ import {
   requestImmediateStatusRender,
   requestStatusRender,
   resetLayoutCache,
+  sampleTpsFromSession,
 } from "../core/segment-context.ts";
 import { getQueueContext } from "../queue/queue-context.ts";
 import {
@@ -62,6 +64,10 @@ import {
   clearSkillsCountPublisher,
 } from "../skills/skill-status.ts";
 import { maybeAppendReadHint } from "./read-hints.ts";
+import {
+  applyNativeWorkingIndicator,
+  resetNativeWorkingIndicator,
+} from "../../working-vibes/native-indicator.ts";
 import {
   dispatchSignalEvent,
   settleSignal,
@@ -181,7 +187,7 @@ export function registerSessionLifecycle(
     }
   });
 
-  pi.on("session_shutdown", async (_event, ctx) => {
+  pi.on("session_shutdown", async (_event, _ctx) => {
     clearSkillsCountPublisher();
     rt.sessionGeneration++;
     rt.dismissWelcomeOverlay?.();
@@ -260,9 +266,16 @@ export function registerSessionLifecycle(
 
   // Generate themed working message before agent starts (has access to user's prompt)
   pi.on("before_agent_start", async (event, ctx) => {
-    rt.lastUserPrompt = event.prompt;
+    const prompt =
+      event.messageType === "user"
+        ? event.prompt
+        : event.message.display && typeof event.message.content === "string"
+          ? event.message.content
+          : "";
+    rt.lastUserPrompt = prompt;
     if (ctx.hasUI) {
-      onVibeBeforeAgentStart(event.prompt, ctx.ui.setWorkingMessage);
+      onVibeBeforeAgentStart(prompt, ctx.ui.setWorkingMessage);
+      applyNativeWorkingIndicator(ctx.ui, rt.motionPolicy, defaultMotionFor("thinking"));
     }
   });
 
@@ -270,6 +283,7 @@ export function registerSessionLifecycle(
   // Also dismiss welcome when agent starts responding (handles `p "command"` case)
   pi.on("agent_start", async (_event, ctx) => {
     rt.isStreaming = true;
+    rt.turnStartedAt = Date.now();
     rt.liveAssistantUsage = null;
     onVibeAgentStart();
     dismissWelcome(rt, ctx);
@@ -287,6 +301,11 @@ export function registerSessionLifecycle(
       rt.liveAssistantUsage = event.message.usage;
       rt.currentCtx = ctx;
       rt.layoutDirty = true;
+      try {
+        sampleTpsFromSession(rt, ctx);
+      } catch (error) {
+        if (!isStaleExtensionContextError(error)) throw error;
+      }
       rt.statusRenderScheduler.schedule(CONTEXT_STATUS_RENDER_MS);
       if (rt.signal.event !== "streaming") {
         dispatchSignalEvent(rt, config.appearance, "streaming");
@@ -406,6 +425,7 @@ export function registerSessionLifecycle(
 
   pi.on("agent_end", async (_event, ctx) => {
     rt.isStreaming = false;
+    rt.turnStartedAt = null;
     rt.liveAssistantUsage = null;
     rt.coreContextUsageCache.reset();
     dispatchSignalEvent(rt, config.appearance, "success");
@@ -423,6 +443,7 @@ export function registerSessionLifecycle(
     try {
       if (hasUI) {
         onVibeAgentEnd(ctx.ui.setWorkingMessage); // working-vibes internal state + reset message
+        resetNativeWorkingIndicator(ctx.ui);
         if (rt.stashedEditorText !== null) {
           if (ctx.ui.getEditorText().trim() === "") {
             ctx.ui.setEditorText(rt.stashedEditorText);

package/src/extension/skills/inline-invocation.ts

@@ -162,7 +162,7 @@ export function expandInlineTriggers(text: string): string {
  */
 export function setupInlineInvocation(
   pi: ExtensionAPI,
-  rt: RuntimeState,
+  _rt: RuntimeState,
 ): void {
   pi.on("input", async (event: any) => {
     // Alleen interactive input verwerken

package/src/extension/ui/custom-editor.ts

@@ -48,14 +48,10 @@ import {
   runPowerlineShortcut,
   stashOrRestoreEditorText,
 } from "../shortcuts/shortcuts-router.ts";
-import {
-  dismissWelcome,
-  scheduleDismissWelcome,
-} from "../welcome/welcome-control.ts";
+import { scheduleDismissWelcome } from "../welcome/welcome-control.ts";
 import { config } from "../core/state.ts";
 import type { RuntimeState } from "../core/types.ts";
 import {
-  ensureShellSession,
   getShellCwd,
   getShellHistoryEntries,
   getShellPath,

package/src/extension/ui/deck/config-diagnostic-lines.ts

@@ -19,12 +19,6 @@ const MAX_CONFLICTS = 3;
 const MAX_UNKNOWN = 3;
 const MAX_INVALID = 4;
 
-const MARK: Record<"ok" | "warn" | "fail", string> = {
-  ok: "✓",
-  warn: "!",
-  fail: "✗",
-};
-
 /** Localised heading for the config diagnosis block. */
 export function configDiagnosticTitle(): string {
   return tr("diag.title", "Config diagnosis");

package/src/extension/ui/ports-panel.ts

@@ -21,7 +21,6 @@ import { matchesKey, type SelectItem, SelectList } from "@earendil-works/pi-tui"
 import { tr } from "../../i18n/index.ts";
 import { config } from "../core/state.ts";
 import {
-  filterPorts,
   formatAddresses,
   formatOwner,
   formatPortsSummary,

package/src/extension/ui/token-overlays.ts

@@ -35,7 +35,7 @@ export function buildTpsOverlayItems(rt: RuntimeState, ctx: any): SelectItem[] {
   const summary = summarizeTpsRing(
     tpsSamples,
     Date.now(),
-    { input: snap.input, output: snap.output },
+    { input: snap.input, output: snap.output, cacheRead: snap.cacheRead },
     {
       windowMs: config.segmentOptions?.tps?.windowMs ?? 1000,
       override: process.env.POWERLINE_TPS,

package/src/extension/welcome/welcome-integration.ts

@@ -183,7 +183,7 @@ export function setupWelcomeOverlay(rt: RuntimeState, ctx: any) {
         (
           tui: any,
           _theme: any,
-          _keybindings: any,
+          keybindings: any,
           done: (result: void) => void,
         ) => {
           const welcome = new WelcomeComponent(
@@ -205,22 +205,51 @@ export function setupWelcomeOverlay(rt: RuntimeState, ctx: any) {
           let countdown = 30;
           let dismissed = false;
           let interval: ReturnType<typeof setInterval> | null = null;
+          let revealTimer: ReturnType<typeof setInterval> | null = null;
+
+          const stopTimers = () => {
+            if (interval) clearInterval(interval);
+            if (revealTimer) clearInterval(revealTimer);
+            interval = null;
+            revealTimer = null;
+          };
 
           const dismiss = () => {
             if (dismissed) return;
             dismissed = true;
-            if (interval) clearInterval(interval);
+            stopTimers();
             rt.dismissWelcomeOverlay = null;
             done();
           };
 
           interval = setInterval(() => {
-            if (dismissed) return;
+            if (dismissed || welcome.isTimerPaused()) return;
             countdown--;
             welcome.setCountdown(countdown);
             tui.requestRender();
             if (countdown <= 0) dismiss();
           }, 1000);
+          interval.unref?.();
+
+          // The countdown only repaints once a second, which stepped the boot
+          // reveal at 1 FPS. Repaint on the ambient heartbeat: bounded while
+          // the reveal window is open, continuous while the lantern animates.
+          const revealStartedAt = Date.now();
+          const animateArt = artSettings.animate;
+          revealTimer = setInterval(() => {
+            if (dismissed) {
+              if (revealTimer) clearInterval(revealTimer);
+              revealTimer = null;
+              return;
+            }
+            if (!animateArt && !bootRevealActive(revealStartedAt, Date.now())) {
+              if (revealTimer) clearInterval(revealTimer);
+              revealTimer = null;
+              return;
+            }
+            tui.requestRender();
+          }, BOOT_REVEAL_HEARTBEAT_MS);
+          revealTimer.unref?.();
 
           rt.dismissWelcomeOverlay = dismiss;
 
@@ -233,10 +262,41 @@ export function setupWelcomeOverlay(rt: RuntimeState, ctx: any) {
             focused: false,
             invalidate: () => welcome.invalidate(),
             render: (width: number) => welcome.render(width),
-            handleInput: () => dismiss(),
+            handleInput: (data: string) => {
+              // Only non-printable navigation is intercepted; Tab/Shift+Tab
+              // switch section, arrows move inside it, Enter (only once the
+              // countdown is paused) primes the focused quick-launch row.
+              // Every printable key still just dismisses, so typing is never
+              // swallowed by the overlay.
+              const nextSection = data === "\t";
+              const prevSection = data === "\x1b[Z";
+              if (nextSection || prevSection) {
+                welcome.cycleSection(prevSection ? -1 : 1);
+                tui.requestRender();
+                return;
+              }
+              const up = keybindings?.matches?.(data, "tui.select.up") || data === "\x1b[A";
+              const down = keybindings?.matches?.(data, "tui.select.down") || data === "\x1b[B";
+              if (up || down) {
+                welcome.moveFocus(up ? -1 : 1);
+                tui.requestRender();
+                return;
+              }
+              const enter =
+                keybindings?.matches?.(data, "tui.select.confirm") ||
+                data === "\r" ||
+                data === "\n";
+              if (enter && welcome.isTimerPaused()) {
+                const insert = welcome.activate();
+                dismiss();
+                if (insert) ctx.ui.setEditorText?.(insert);
+                return;
+              }
+              dismiss();
+            },
             dispose: () => {
               dismissed = true;
-              if (interval) clearInterval(interval);
+              stopTimers();
             },
           };
         },

package/src/i18n/nl.ts

@@ -311,6 +311,9 @@ export const NL: Record<string, string> = {
   "welcome.tagline": "Schrijf het op, laat het stijgen, houd je focus helder.",
   "welcome.title": " pi-wishcraft ",
   "welcome.countdown": "Druk op een toets om verder te gaan ({n}s)",
+  "welcome.pausedHint": "↑/↓ nieuws bekijken · andere toets gaat verder",
+  "welcome.pausedHint.sessions": "↑/↓ sessies bekijken · tab wisselt sectie · andere toets gaat verder",
+  "welcome.pausedHint.shortcuts": "↑/↓ kiezen · enter vult de prompt · tab wisselt sectie",
   "welcome.whatsNew": "Wat is nieuw",
   "welcome.firstRun": "Aan de slag",
   "welcome.firstRun.1": "# <idee> — leg een gedachte vast zonder te onderbreken",

package/src/segments/core.ts

@@ -1,7 +1,6 @@
 import { hostname as osHostname } from "node:os";
 import { basename } from "node:path";
 import type {
-  SegmentContext,
   SemanticColor,
   StatusLineSegment,
 } from "../config/types.ts";

package/src/segments/system.ts

@@ -226,17 +226,26 @@ export const tpsSegment: StatusLineSegment = {
       };
     }
     const windowMs = ctx.options.tps?.windowMs ?? 1000;
-    const { output, input } = ctx.usageStats ?? { output: 0, input: 0 };
+    const { output, input, cacheRead } = ctx.usageStats ?? {
+      output: 0,
+      input: 0,
+      cacheRead: 0,
+    };
     const now = Date.now();
     pushTpsSample(
       tpsSamples,
-      { at: now, output, input },
+      {
+        at: now,
+        output,
+        input,
+        uncachedInput: Math.max(0, input - cacheRead),
+      },
       ringMsForWindow(windowMs),
     );
     const { inRate, outRate } = ratesFromRing(
       tpsSamples,
       now,
-      { input, output },
+      { input, output, cacheRead },
       windowMs,
     );
     const icons = getIcons();

package/src/studio/component.ts

@@ -126,7 +126,6 @@ function renderList(
 
 function renderDetail(theme: Theme, width: number, entry: SkillEntry | null, usage: ReadonlyMap<string, SkillUsage>): string[] {
   if (!entry) return [theme.fg("accent", "DETAIL"), theme.fg("dim", "Select a skill from the list")];
-  const body = readSkillBody(entry.filePath);
   const refs = safeReadReferences(entry);
   const use = usage.get(entry.name);
   const health = entry.warning ? theme.fg("warning", "warn") : theme.fg("success", "ok");

package/src/theme/theme.ts

@@ -1,4 +1,4 @@
-import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";

package/src/tools/graph.ts

@@ -1,8 +1,5 @@
 const BRAILLE_CHAR_BASE = 0x2800;
 
-// Braille dot heights (0-7 for 4 vertical levels in 2 columns)
-const BRAILLE_MAP = [0x40, 0x4, 0x20, 0x2, 0x10, 0x1, 0x80, 0x8];
-
 /**
  * Render a sequence of numeric data points as a Braille sparkline string.
  */

package/src/usage/tps-ring.ts

@@ -1,17 +1,38 @@
 /**
- * Shared TPS ring math. The segment writes samples; `/tps` and Status → TPS
- * read the same ring. No second sampler.
+ * Shared TPS ring math. Stream events (`message_update`) and the segment both
+ * write samples; `/tps` and Status → TPS read the same ring.
+ *
+ * Three things the plain delta maths got wrong:
+ * - prompt tokens arrive once per turn, so a window delta reports the cache
+ *   read (or nothing at all) instead of the rate the prompt was processed at;
+ * - output arrives in chunks, so a single 1s window is noisy;
+ * - a burst that lands right after a repaint looks like thousands of tokens/s.
+ * The ring therefore carries the turn start and the uncached input count on a
+ * sample, derives TTFT from them, and smooths output with an EMA. All of it
+ * lives on the ring: nothing here keeps state beyond the samples themselves.
  */
 
 export interface TpsSample {
   at: number;
   output: number;
   input: number;
+  /** Prompt tokens excluding `cacheRead`; falls back to `input`. */
+  uncachedInput?: number;
+  /**
+   * Timestamp (ms) the turn began (`agent_start`). Set on the first sample of
+   * a turn only, so the marker identifies where that turn starts in the ring.
+   */
+  turnStartAt?: number;
 }
 
 export interface TpsRates {
+  /** Uncached prompt tokens per second; TTFT-based while a turn is active. */
   inRate: number;
   outRate: number;
+  /** EMA over the pairwise output rates — the steady-state estimate. */
+  emaOutRate?: number;
+  /** Time to first token of the current turn; null when no turn is measured. */
+  ttftMs?: number | null;
 }
 
 export interface TpsSummary extends TpsRates {
@@ -26,14 +47,29 @@ export interface TpsSummary extends TpsRates {
 
 export const TPS_MIN_RING_MS = 5000;
 export const TPS_MAX_SAMPLES = 480;
+/**
+ * Pairwise buckets shorter than this are coalesced into the next sample. Two
+ * repaints a couple of ms apart that straddle one token burst would otherwise
+ * report that burst as thousands of tokens per second.
+ */
+export const TPS_MIN_PAIRWISE_DT_MS = 80;
+/** Samples with identical counts closer together than this carry no signal. */
+const TPS_DEDUPE_MS = 40;
+/** Smoothing factor for the output EMA (0..1; higher = more reactive). */
+export const TPS_EMA_ALPHA = 0.32;
 
-/** Live ring filled by the tps segment renderer. */
+/** Live ring filled by stream events and the tps segment renderer. */
 export const tpsSamples: TpsSample[] = [];
 
 export function ringMsForWindow(windowMs: number): number {
   return Math.max(TPS_MIN_RING_MS, windowMs * 2);
 }
 
+/** Prompt tokens that actually had to be processed for this sample. */
+function uncachedOf(sample: TpsSample): number {
+  return sample.uncachedInput ?? sample.input;
+}
+
 export function pruneTpsRing(
   samples: TpsSample[],
   now: number,
@@ -50,14 +86,103 @@ export function pushTpsSample(
   sample: TpsSample,
   ringMs: number,
 ): void {
+  const tail = samples[samples.length - 1];
+  if (
+    tail &&
+    tail.output === sample.output &&
+    tail.input === sample.input &&
+    sample.at - tail.at < TPS_DEDUPE_MS
+  ) {
+    pruneTpsRing(samples, sample.at, ringMs);
+    return;
+  }
   samples.push(sample);
   pruneTpsRing(samples, sample.at, ringMs);
 }
 
+/**
+ * Locate the current turn in the ring and the first sample that produced
+ * tokens for it. Returns null when no turn marker is present, which is the
+ * normal case for a preset that never streams (`/tps` alone, replay, tests).
+ */
+function measureTurn(samples: readonly TpsSample[]): {
+  turnStartAt: number;
+  firstTokenAt: number;
+  baseInput: number;
+  baseOutput: number;
+} | null {
+  let marker = -1;
+  for (let i = samples.length - 1; i >= 0; i--) {
+    if (samples[i]!.turnStartAt !== undefined) {
+      marker = i;
+      break;
+    }
+  }
+  if (marker < 0) return null;
+
+  const start = samples[marker]!.turnStartAt!;
+  const before = samples[marker - 1];
+  const baseInput = before ? uncachedOf(before) : 0;
+  const baseOutput = before ? before.output : 0;
+
+  for (let i = marker; i < samples.length; i++) {
+    const cur = samples[i]!;
+    if (cur.output > baseOutput || uncachedOf(cur) > baseInput) {
+      return {
+        turnStartAt: start,
+        firstTokenAt: cur.at,
+        baseInput,
+        baseOutput,
+      };
+    }
+  }
+  return null;
+}
+
+/** Pairwise buckets for peak/average reporting. */
+function pairwiseRates(samples: readonly TpsSample[]): {
+  ins: number[];
+  outs: number[];
+} {
+  const ins: number[] = [];
+  const outs: number[] = [];
+  if (samples.length < 2) return { ins, outs };
+  let anchor = samples[0]!;
+  for (let i = 1; i < samples.length; i++) {
+    const cur = samples[i]!;
+    const dtMs = cur.at - anchor.at;
+    if (dtMs < TPS_MIN_PAIRWISE_DT_MS) continue;
+    const dtSec = dtMs / 1000;
+    const dOut = cur.output - anchor.output;
+    const dIn = uncachedOf(cur) - uncachedOf(anchor);
+    if (dOut > 0) outs.push(dOut / dtSec);
+    if (dIn > 0) ins.push(dIn / dtSec);
+    anchor = cur;
+  }
+  return { ins, outs };
+}
+
+/** EMA over the pairwise output rates; undefined when nothing was generated. */
+function emaOf(values: readonly number[]): number | undefined {
+  if (values.length === 0) return undefined;
+  let ema = values[0]!;
+  for (let i = 1; i < values.length; i++) {
+    ema = TPS_EMA_ALPHA * values[i]! + (1 - TPS_EMA_ALPHA) * ema;
+  }
+  return ema;
+}
+
+export interface TpsUsage {
+  input: number;
+  output: number;
+  /** Cached prompt tokens to exclude from the processed-input rate. */
+  cacheRead?: number;
+}
+
 export function ratesFromRing(
   samples: readonly TpsSample[],
   now: number,
-  usage: { input: number; output: number },
+  usage: TpsUsage,
   windowMs: number,
 ): TpsRates {
   let ref: TpsSample | null = null;
@@ -72,35 +197,40 @@ export function ratesFromRing(
       ref = s;
     }
   }
+
   let outRate = 0;
-  let inRate = 0;
+  let windowInRate = 0;
   if (ref) {
     const dt = (now - ref.at) / 1000;
     const dOut = usage.output - ref.output;
     const dIn = usage.input - ref.input;
-    if (dt > 0 && dOut >= 0) outRate = dOut / dt;
-    if (dt > 0 && dIn >= 0) inRate = dIn / dt;
+    if (dt > 0 && dOut > 0) outRate = dOut / dt;
+    if (dt > 0 && dIn > 0) windowInRate = dIn / dt;
   }
-  return { inRate, outRate };
-}
 
-function pairwiseRates(samples: readonly TpsSample[]): {
-  ins: number[];
-  outs: number[];
-} {
-  const ins: number[] = [];
-  const outs: number[] = [];
-  for (let i = 1; i < samples.length; i++) {
-    const prev = samples[i - 1]!;
-    const cur = samples[i]!;
-    const dt = (cur.at - prev.at) / 1000;
-    if (dt <= 0) continue;
-    const dOut = cur.output - prev.output;
-    const dIn = cur.input - prev.input;
-    if (dOut >= 0) outs.push(dOut / dt);
-    if (dIn >= 0) ins.push(dIn / dt);
+  const turn = measureTurn(samples);
+  let ttftMs: number | null = null;
+  let inRate = windowInRate;
+  if (turn) {
+    // Prompt processing happens once, up front: its rate is the uncached
+    // token count over the time it took to produce the first token. Dividing
+    // it by the 1s window (and counting cacheRead) is what produced the
+    // nonsense input rates this replaces.
+    ttftMs = Math.max(1, turn.firstTokenAt - turn.turnStartAt);
+    const processed = Math.max(
+      0,
+      usage.input - (usage.cacheRead ?? 0) - turn.baseInput,
+    );
+    inRate = processed > 0 ? processed / (ttftMs / 1000) : 0;
   }
-  return { ins, outs };
+
+  const { outs } = pairwiseRates(samples);
+  return {
+    inRate,
+    outRate,
+    emaOutRate: emaOf(outs),
+    ttftMs,
+  };
 }
 
 function avg(values: readonly number[]): number {
@@ -111,18 +241,20 @@ function avg(values: readonly number[]): number {
 export function summarizeTpsRing(
   samples: readonly TpsSample[],
   now: number,
-  usage: { input: number; output: number },
+  usage: TpsUsage,
   options: { windowMs?: number; override?: string | null } = {},
 ): TpsSummary {
   const windowMs = options.windowMs ?? 1000;
   const override = options.override?.trim() || null;
-  const { inRate, outRate } = ratesFromRing(samples, now, usage, windowMs);
+  const rates = ratesFromRing(samples, now, usage, windowMs);
   const { ins, outs } = pairwiseRates(samples);
   return {
     override,
     windowMs,
-    inRate,
-    outRate,
+    inRate: rates.inRate,
+    outRate: rates.outRate,
+    emaOutRate: rates.emaOutRate,
+    ttftMs: rates.ttftMs,
     peakIn: ins.length ? Math.max(...ins) : 0,
     peakOut: outs.length ? Math.max(...outs) : 0,
     avgIn: avg(ins),
@@ -142,10 +274,18 @@ export function tpsOverlayLines(summary: TpsSummary): string[] {
       "clear with Configure or /tps (empty to show live)",
     ];
   }
-  return [
+  const lines = [
     `window ${summary.windowMs}ms over ${TPS_MIN_RING_MS}ms ring`,
-    `out  ${formatTpsRate(summary.outRate)}   peak ${formatTpsRate(summary.peakOut)}   avg ${formatTpsRate(summary.avgOut)}`,
+    `out  ${formatTpsRate(summary.outRate)}   peak ${formatTpsRate(summary.peakOut)}   avg ${formatTpsRate(summary.avgOut)}${
+      summary.emaOutRate === undefined
+        ? ""
+        : `   ema ${formatTpsRate(summary.emaOutRate)}`
+    }`,
     `in   ${formatTpsRate(summary.inRate)}   peak ${formatTpsRate(summary.peakIn)}   avg ${formatTpsRate(summary.avgIn)}`,
-    `samples ${summary.samples}`,
   ];
+  if (summary.ttftMs !== null && summary.ttftMs !== undefined) {
+    lines.push(`ttft ${Math.round(summary.ttftMs)}ms`);
+  }
+  lines.push(`samples ${summary.samples}`);
+  return lines;
 }

package/src/welcome/banner.ts

@@ -70,6 +70,20 @@ export function bootRevealActive(startedAt: number, now: number): boolean {
   return now - startedAt < BOOT_REVEAL_MS;
 }
 
+/**
+ * Reveal time to hand the art renderer, or `undefined` when the steady layout
+ * should take over. After the reveal window an animated lantern keeps its own
+ * override (elapsed 0 = no fade, live frames) so the flame never freezes on
+ * the first paint; a still lantern falls back to the plain box art.
+ */
+export function revealElapsedForArt(
+  elapsedMs: number,
+  animate: boolean,
+): number | undefined {
+  if (elapsedMs < BOOT_REVEAL_MS) return elapsedMs;
+  return animate ? 0 : undefined;
+}
+
 /**
  * Welcome header - same layout as overlay but persistent (no countdown).
  * Used when quietStartup: true. The first ~1.5s after mount fades the art