@askdkc/dsh-cli 0.11.3

package/lib/types/components/sessions/SessionPreview.js

@@ -0,0 +1,62 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from '../../ui.js';
+import { t } from '../../i18n.js';
+import { formatProject, formatWhen, kindLabel, truncateWidth, wrapWidth } from '../../sessions/format.js';
+/** Role marker and colour for a preview entry. */
+const ROLE = {
+    user: { glyph: '❯', color: 'suggestion' },
+    assistant: { glyph: '✦', color: 'accent' },
+};
+/**
+ * The preview pane: what this session actually says.
+ *
+ * It shows the END of the conversation, not the beginning, for two reasons.
+ * The title already carries the beginning — it is usually the first prompt —
+ * so repeating it would spend the pane on something the list already said. And
+ * the question a person asks at this moment is "is this the one I was in the
+ * middle of", which only the last exchange answers.
+ *
+ * It is also the reason the pane costs nothing: the tail of a log is exactly
+ * what a bounded read already has in hand, so opening the preview on a 4 MB
+ * session is the same amount of work as on a 40 KB one.
+ */
+export function SessionPreview({ session, entries, loading, width, height, home, now, }) {
+    const framed = width >= 24 && height >= 4;
+    const body = Math.max(8, width - (framed ? 4 : 2));
+    const bodyHeight = Math.max(0, height - (framed ? 2 : 0));
+    // The pane is a fixed-height box, so its content is laid out as a flat list
+    // of lines and cut to fit. Letting several adaptive paragraphs share a fixed
+    // box lets them overlap once their natural height exceeds it.
+    const lines = [];
+    let key = 0;
+    const push = (node) => {
+        lines.push(_jsx(Box, { flexShrink: 0, children: node }, key++));
+    };
+    push(_jsx(Text, { color: "remember", bold: true, children: truncateWidth(session.title.text, body) }));
+    push(_jsx(Text, { dimColor: true, children: truncateWidth([kindLabel(session.kind), formatProject(session.cwd, home)].join(' · '), body) }));
+    push(_jsx(Text, { dimColor: true, children: truncateWidth(t('session-preview-times', {
+            created: formatWhen(session.createdAt, now),
+            updated: formatWhen(session.updatedAt, now),
+        }), body) }));
+    push(_jsx(Text, { children: " " }));
+    if (loading) {
+        push(_jsx(Text, { dimColor: true, italic: true, children: t('session-preview-loading') }));
+    }
+    else if (entries.length === 0) {
+        push(_jsx(Text, { dimColor: true, italic: true, children: t('session-preview-empty') }));
+    }
+    else {
+        for (const entry of entries) {
+            const role = ROLE[entry.role];
+            const wrapped = wrapWidth(entry.text, body - 2);
+            wrapped.forEach((line, index) => {
+                push(_jsx(Text, { color: index === 0 ? role.color : undefined, dimColor: entry.role === 'assistant', children: `${index === 0 ? `${role.glyph} ` : '  '}${line}` }));
+            });
+            push(_jsx(Text, { children: " " }));
+        }
+    }
+    // Keep the newest content: an overlong preview is cut at the TOP, so the
+    // last thing said is always the last thing visible.
+    const visible = lines.length > bodyHeight ? lines.slice(lines.length - bodyHeight) : lines;
+    return (_jsx(Box, { flexDirection: "column", width: width, height: height, flexShrink: 0, borderStyle: framed ? 'round' : undefined, borderColor: framed ? 'permission' : undefined, borderDimColor: true, paddingX: framed ? 1 : 0, paddingLeft: framed ? 1 : 2, overflow: "hidden", children: visible }));
+}

package/lib/types/components/sessions/WorkspaceListRow.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+import type { ClickEvent } from '../../ink/events/click-event.js';
+import type { WorkspaceGroup } from '../../sessions/view.js';
+/** One two-line working-directory choice in the /resume browser. */
+export declare function WorkspaceListRow({ workspace, all, totalProjects, totalSessions, width, focused, selected, home, now, onClick, }: {
+    workspace?: WorkspaceGroup;
+    all?: boolean;
+    totalProjects: number;
+    totalSessions: number;
+    width: number;
+    focused: boolean;
+    selected: boolean;
+    home: string;
+    now: number;
+    onClick?(event: ClickEvent): void;
+}): React.ReactNode;
+//# sourceMappingURL=WorkspaceListRow.d.ts.map

package/lib/types/components/sessions/WorkspaceListRow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkspaceListRow.d.ts","sourceRoot":"","sources":["../../../../src/components/sessions/WorkspaceListRow.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAmB,MAAM,OAAO,CAAA;AAGvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAEjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAE5D,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,EAC/B,SAAS,EACT,GAAG,EACH,aAAa,EACb,aAAa,EACb,KAAK,EACL,OAAO,EACP,QAAQ,EACR,IAAI,EACJ,GAAG,EACH,OAAO,GACR,EAAE;IACD,SAAS,CAAC,EAAE,cAAc,CAAA;IAC1B,GAAG,CAAC,EAAE,OAAO,CAAA;IACb,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,OAAO,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,CAAC,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAA;CAClC,GAAG,KAAK,CAAC,SAAS,CAwClB"}

package/lib/types/components/sessions/WorkspaceListRow.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Box, Text } from '../../ui.js';
+import { t } from '../../i18n.js';
+import { formatProject, formatWhen, projectName, spreadRow, truncateWidth } from '../../sessions/format.js';
+/** One two-line working-directory choice in the /resume browser. */
+export function WorkspaceListRow({ workspace, all, totalProjects, totalSessions, width, focused, selected, home, now, onClick, }) {
+    const [hovered, setHovered] = useState(false);
+    const body = Math.max(8, width - 4);
+    const count = all ? totalSessions : workspace?.count ?? 0;
+    const title = all ? t('session-workspace-all') : projectName(workspace?.cwd ?? '');
+    const badge = all
+        ? t('session-workspace-project-count', { n: totalProjects })
+        : workspace?.current
+            ? `${t('session-workspace-current')} · ${t('session-count-shown', { n: count })}`
+            : t('session-count-shown', { n: count });
+    const heading = spreadRow(`${all ? '◎' : '▣'} ${title}`, `${selected ? '✓ ' : ''}${badge}`, body);
+    const detail = all
+        ? t('session-workspace-all-detail', { n: count })
+        : [
+            formatProject(workspace?.cwd ?? '', home),
+            count > 0 && workspace !== undefined
+                ? formatWhen(workspace.updatedAt, now)
+                : t('session-workspace-empty'),
+        ].filter(Boolean).join(' · ');
+    return (_jsxs(Box, { flexDirection: "column", flexShrink: 0, paddingX: 1, onClick: onClick, onMouseEnter: onClick === undefined ? undefined : () => setHovered(true), onMouseLeave: onClick === undefined ? undefined : () => setHovered(false), backgroundColor: focused || hovered ? 'userMessageBackgroundHover' : undefined, children: [_jsxs(Box, { height: 1, flexShrink: 0, overflow: "hidden", children: [_jsx(Text, { color: focused ? 'suggestion' : 'subtle', children: focused ? '❯ ' : '  ' }), _jsx(Text, { color: focused ? 'suggestion' : selected ? 'success' : 'text', bold: focused || selected, children: heading.left }), _jsx(Text, { dimColor: !focused, children: `${' '.repeat(heading.gap)}${heading.right}` })] }), _jsx(Text, { dimColor: true, wrap: "truncate-end", children: `  ${truncateWidth(detail, body - 2)}` })] }));
+}

package/lib/types/components/shimmer.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared shimmer utilities: the blue-white color ladder of the header and a
+ * moving-highlight text painter used by the header wordmark/tagline and the
+ * working-activity status line.
+ */
+export interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+}
+/** Header blue-white ladder: brand → ice → pale → soft ice flash.
+ *  FLASH stays visibly blue (never pure white) — the highlight reads as a
+ *  mist-brightened crest, not a white strobe. */
+export declare const BRAND: Rgb;
+/** Header ladder ice blue (`#93BEFF`). */
+export declare const ICE: Rgb;
+/** Header ladder pale blue (`#D7E4FF`). */
+export declare const PALE: Rgb;
+/** Soft ice flash blue (`#C6D8F8`); stays visibly blue, never pure white. */
+export declare const FLASH: Rgb;
+/**
+ * Paint `word` with a 10-column highlight window sweeping across it. The
+ * window advances one column per `stepMs` and the brightness pulse follows
+ * the same cadence (period 2π·stepMs·... — one full sine per ~6 steps).
+ * The shimmer cadence is configurable; callers pass 60 for the lively
+ * sweep.
+ * @param word - Text to paint.
+ * @param time - Elapsed time in milliseconds; drives the sweep position and the brightness pulse.
+ * @param base - Color for cells outside the highlight window.
+ * @param highlight - Color mixed into the sweeping highlight window.
+ * @param stepMs - Milliseconds per column of sweep advance (default 60).
+ * @returns The ANSI bold-colored word with the moving highlight.
+ */
+export declare function sweep(word: string, time: number, base: Rgb, highlight: Rgb, stepMs?: number): string;
+//# sourceMappingURL=shimmer.d.ts.map

package/lib/types/components/shimmer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shimmer.d.ts","sourceRoot":"","sources":["../../../src/components/shimmer.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AAEH,MAAM,WAAW,GAAG;IAClB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACV;AAED;;iDAEiD;AACjD,eAAO,MAAM,KAAK,EAAE,GAA+B,CAAA;AACnD,0CAA0C;AAC1C,eAAO,MAAM,GAAG,EAAE,GAAgC,CAAA;AAClD,2CAA2C;AAC3C,eAAO,MAAM,IAAI,EAAE,GAAgC,CAAA;AACnD,6EAA6E;AAC7E,eAAO,MAAM,KAAK,EAAE,GAAgC,CAAA;AAEpD;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,SAAK,GAAG,MAAM,CAehG"}

package/lib/types/components/shimmer.js

@@ -0,0 +1,43 @@
+import chalk from 'chalk';
+import { stringWidth } from '../ink/stringWidth.js';
+import { getGraphemeSegmenter } from '../utils/intl.js';
+import { interpolateColor } from '../components/Spinner/spinnerUtils.js';
+/** Header blue-white ladder: brand → ice → pale → soft ice flash.
+ *  FLASH stays visibly blue (never pure white) — the highlight reads as a
+ *  mist-brightened crest, not a white strobe. */
+export const BRAND = { r: 77, g: 107, b: 254 };
+/** Header ladder ice blue (`#93BEFF`). */
+export const ICE = { r: 147, g: 190, b: 255 };
+/** Header ladder pale blue (`#D7E4FF`). */
+export const PALE = { r: 215, g: 228, b: 255 };
+/** Soft ice flash blue (`#C6D8F8`); stays visibly blue, never pure white. */
+export const FLASH = { r: 198, g: 216, b: 248 };
+/**
+ * Paint `word` with a 10-column highlight window sweeping across it. The
+ * window advances one column per `stepMs` and the brightness pulse follows
+ * the same cadence (period 2π·stepMs·... — one full sine per ~6 steps).
+ * The shimmer cadence is configurable; callers pass 60 for the lively
+ * sweep.
+ * @param word - Text to paint.
+ * @param time - Elapsed time in milliseconds; drives the sweep position and the brightness pulse.
+ * @param base - Color for cells outside the highlight window.
+ * @param highlight - Color mixed into the sweeping highlight window.
+ * @param stepMs - Milliseconds per column of sweep advance (default 60).
+ * @returns The ANSI bold-colored word with the moving highlight.
+ */
+export function sweep(word, time, base, highlight, stepMs = 60) {
+    const width = stringWidth(word);
+    const cycle = width + 20;
+    const glimmerStart = (Math.floor(time / stepMs) % cycle) - 10;
+    let out = '';
+    let col = 0;
+    for (const { segment } of getGraphemeSegmenter().segment(word)) {
+        const segWidth = stringWidth(segment);
+        const highlighted = col >= glimmerStart && col + segWidth <= glimmerStart + 10;
+        const opacity = highlighted ? (Math.sin(time / (stepMs * 2)) + 1) / 2 : 0;
+        const rgb = highlighted ? interpolateColor(base, highlight, opacity) : base;
+        out += chalk.rgb(rgb.r, rgb.g, rgb.b).bold(segment);
+        col += segWidth;
+    }
+    return out;
+}

package/lib/types/components/smoothReveal.d.ts

@@ -0,0 +1,57 @@
+/** Reveal tick cadence — ~30fps, matching oh-my-pi's controller. */
+export declare const REVEAL_FRAME_MS: number;
+/** Minimum units (code units or lines) advanced per tick while work remains. */
+export declare const REVEAL_MIN_STEP = 3;
+/** Catch-up bound: the reveal settles any backlog within this many frames. */
+export declare const REVEAL_CATCHUP_FRAMES = 8;
+/** Adaptive per-frame step for a backlog (exported for tests). */
+export declare function revealStep(backlog: number): number;
+/** Subscribe to reveal-frame wakeups (MessageList + tool cards). */
+export declare function subscribeReveal(listener: () => void): () => void;
+/** Snapshot for useSyncExternalStore; bumps once per advancing tick. */
+export declare function getRevealVersion(): number;
+/** Force-complete (and forget) a cursor: expanded card, replaced view, … */
+export declare function snapReveal(key: string): void;
+export type RevealReadOptions = {
+    /** Master switch (settings `dsh-tui.smoothStreaming`); false = full text. */
+    enabled: boolean;
+    /**
+     * Whether this content arrived "just now" (live streaming row, freshly
+     * settled row, live-created tool card). The FIRST read with active=true
+     * creates the cursor at zero — that is what turns a one-shot
+     * non-streaming delivery into a smooth paint. Reading with active=false
+     * (history / replayed content) never creates one: replaying a transcript
+     * must not typewrite every row. `active` only matters for cursor creation;
+     * settling mid-reveal deliberately keeps revealing (the "non-streaming
+     * becomes streaming" contract).
+     */
+    active: boolean;
+};
+/**
+ * Revealed length of `text` for `key` — the cursor logic of
+ * {@link revealTextOf} without the slice allocation (layout signatures read
+ * this every render for every visible row).
+ */
+export declare function revealLengthOf(key: string, text: string, options: RevealReadOptions): number;
+/**
+ * Revealed prefix of `text` for `key`. Monotonic appends (streaming deltas)
+ * keep the cursor; a non-prefix replacement (rewind, folded preview
+ * truncation) snaps to the new text — never animate across a discontinuity
+ * the reader did not witness as streaming. Feed the result into the
+ * streaming renderer (StreamingMarkdown); the monotonic prefix it receives
+ * keeps its stable-prefix memoization fully effective.
+ */
+export declare function revealTextOf(key: string, text: string, options: RevealReadOptions): string;
+/**
+ * Revealed unit count for `key` over `total` units (tool-card body lines,
+ * split-diff rows). A SMALLER total always snaps (content that shrank is a
+ * replacement, not an append); growth keeps the cursor. Callers own the
+ * append-vs-replace decision for growing totals (pass a fresh key or call
+ * {@link snapReveal} when the content behind the same key is replaced).
+ */
+export declare function revealLinesOf(key: string, total: number, options: RevealReadOptions): number;
+/** Clear every cursor/listener/timer (verify scripts between cases). */
+export declare function resetRevealForTest(): void;
+/** Whether the shared scheduler currently runs (refcount assertions). */
+export declare function isRevealTimerRunning(): boolean;
+//# sourceMappingURL=smoothReveal.d.ts.map

package/lib/types/components/smoothReveal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smoothReveal.d.ts","sourceRoot":"","sources":["../../../src/components/smoothReveal.ts"],"names":[],"mappings":"AA0CA,oEAAoE;AACpE,eAAO,MAAM,eAAe,QAAY,CAAA;AACxC,gFAAgF;AAChF,eAAO,MAAM,eAAe,IAAI,CAAA;AAChC,8EAA8E;AAC9E,eAAO,MAAM,qBAAqB,IAAI,CAAA;AAEtC,kEAAkE;AAClE,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD;AAiID,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAKhE;AAED,wEAAwE;AACxE,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE5C;AAMD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAA;IAChB;;;;;;;;;OASG;IACH,MAAM,EAAE,OAAO,CAAA;CAChB,CAAA;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAiC5F;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAI1F;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAqC5F;AAMD,wEAAwE;AACxE,wBAAgB,kBAAkB,IAAI,IAAI,CAUzC;AAED,yEAAyE;AACzE,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C"}

package/lib/types/components/smoothReveal.js

@@ -0,0 +1,305 @@
+/**
+ * Smooth streaming reveal — decouples "text the provider has delivered" from
+ * "text the screen is showing" (the oh-my-pi `display.smoothStreaming` idea,
+ * see their `StreamingRevealController`). A shared ~30fps scheduler advances
+ * each reveal cursor by an adaptive catch-up step, so burst-delivered text (a
+ * slow provider dumping a large batch, or a non-streaming response arriving
+ * whole) paints as a brief even flow instead of one jarring jump, while
+ * genuinely streaming text is re-paced to a steady cadence regardless of
+ * chunk timing.
+ *
+ * Step math (per frame): `max(MIN_STEP, ceil(backlog / CATCHUP_FRAMES))` —
+ * an EXPONENTIAL decay over the backlog (each frame removes ~1/8 of what is
+ * still unrevealed, the oh-my-pi semantics exactly): a large burst lands its
+ * first three quarters within a few frames, the remainder tapers, and the
+ * MIN_STEP floor turns the tail into a steady linear crawl so the reveal
+ * always finishes. A ~2000-character one-shot delivery paints fully in
+ * roughly 1.5s; genuinely streaming text (small backlogs) paces at a steady
+ * per-frame rate. The reveal never runs ahead of what has arrived.
+ *
+ * ARCHITECTURE — module-level cursors, not component state. dsh-tui's
+ * transcript virtualization feeds on MemoRow prop changes (flattened
+ * primitives) and re-measures mounted rows after every MessageList commit;
+ * a reveal living in child-component state would change row heights without
+ * touching those props, and the memo/signature/height-measure chain would
+ * never notice (stale cached heights → blank bands). Instead the cursors
+ * live here keyed by row identity, the READS happen during render (they feed
+ * the same flattened `text` prop the streaming path already uses), and the
+ * WRITES happen on the scheduler tick, which bumps a version that
+ * MessageList subscribes to via useSyncExternalStore. A reveal therefore
+ * rides the exact same update pipeline as an arriving chunk: prop change →
+ * memo miss → re-render → post-commit measurement. Render-phase reads are
+ * idempotent and safe to re-run (a discarded concurrent render at worst
+ * creates a cursor the tick soon retires).
+ *
+ * Unit model: reveal positions are UTF-16 code units (Chinese text is one
+ * unit per character). Surrogate pairs are never split (see {@link
+ * safeSliceEnd}); grapheme clusters longer than a surrogate pair (emoji ZWJ
+ * chains) may briefly show a partial cluster mid-reveal — transient frames
+ * repaint within 33ms, and settled rendering is always the full text.
+ */
+import { registerOverflowQuench, swallowNestedUpdateOverflow } from '../ink/update-overflow-guard.js';
+/** Reveal tick cadence — ~30fps, matching oh-my-pi's controller. */
+export const REVEAL_FRAME_MS = 1000 / 30;
+/** Minimum units (code units or lines) advanced per tick while work remains. */
+export const REVEAL_MIN_STEP = 3;
+/** Catch-up bound: the reveal settles any backlog within this many frames. */
+export const REVEAL_CATCHUP_FRAMES = 8;
+/** Adaptive per-frame step for a backlog (exported for tests). */
+export function revealStep(backlog) {
+    return Math.max(REVEAL_MIN_STEP, Math.ceil(Math.max(0, backlog) / REVEAL_CATCHUP_FRAMES));
+}
+/**
+ * Slice boundary guard: never split a surrogate pair. When the boundary lands
+ * between a high and a low surrogate, take the pair if the low half has
+ * arrived, otherwise step back one unit — showing one fewer character for a
+ * frame beats feeding a lone surrogate into markdown rendering.
+ */
+function safeSliceEnd(text, end) {
+    if (end <= 0)
+        return 0;
+    if (end >= text.length)
+        return text.length;
+    const code = text.charCodeAt(end - 1);
+    if (code >= 0xd800 && code <= 0xdbff) {
+        return end + 1 < text.length ? end + 1 : end - 1;
+    }
+    return end;
+}
+const textCursors = new Map();
+const countCursors = new Map();
+/**
+ * Keys whose reveal has COMPLETED (caught up, snapped, or replaced). A
+ * completed key must not re-create a cursor on a later active read — the
+ * content is already fully on screen, and re-revealing would blank it and
+ * typewrite again. Bounded FIFO: well past the cap these are all ancient
+ * history (the row ids are gone); dropping the oldest half only risks a
+ * long-unmounted row re-revealing, which is harmless (it paints full via
+ * the active=false path anyway once unmounted... and a remounted streaming
+ * row WANTS the reveal).
+ */
+const completedReveals = new Set();
+const COMPLETED_REVEALS_MAX = 2048;
+function markRevealCompleted(key) {
+    if (completedReveals.size >= COMPLETED_REVEALS_MAX) {
+        let drop = COMPLETED_REVEALS_MAX / 2;
+        for (const old of completedReveals) {
+            if (drop-- <= 0)
+                break;
+            completedReveals.delete(old);
+        }
+    }
+    completedReveals.add(key);
+}
+// ---------------------------------------------------------------------------
+// Scheduler + version store (useSyncExternalStore-compatible)
+// ---------------------------------------------------------------------------
+let revealTimer = undefined;
+let revealVersionValue = 0;
+const revealListeners = new Set();
+function ensureRevealTimer() {
+    if (revealTimer === undefined) {
+        revealTimer = setInterval(revealTick, REVEAL_FRAME_MS);
+        revealTimer.unref?.();
+    }
+}
+function stopRevealTimerIfIdle() {
+    if (textCursors.size === 0 && countCursors.size === 0 && revealTimer !== undefined) {
+        clearInterval(revealTimer);
+        revealTimer = undefined;
+    }
+}
+// Circuit-breaker quench: a sustained #185 oscillation surfacing at the
+// reveal tick pauses this scheduler for the backoff window (cursors freeze
+// in place; the resume timer — or a later render reading an active cursor —
+// restarts it). Absorbing forever would leave the process alive but laggy.
+registerOverflowQuench('reveal.tick', ms => {
+    if (revealTimer !== undefined) {
+        clearInterval(revealTimer);
+        revealTimer = undefined;
+        const resume = setTimeout(() => {
+            if (revealTimer === undefined && (textCursors.size > 0 || countCursors.size > 0)) {
+                ensureRevealTimer();
+            }
+        }, ms);
+        resume.unref?.();
+    }
+});
+function revealTick() {
+    let advanced = false;
+    for (const [key, cursor] of textCursors) {
+        const total = cursor.text.length;
+        if (cursor.revealed >= total) {
+            textCursors.delete(key);
+            markRevealCompleted(key);
+            continue;
+        }
+        cursor.revealed = Math.min(total, cursor.revealed + revealStep(total - cursor.revealed));
+        advanced = true;
+    }
+    for (const [key, cursor] of countCursors) {
+        if (cursor.revealed >= cursor.total) {
+            countCursors.delete(key);
+            markRevealCompleted(key);
+            continue;
+        }
+        cursor.revealed = Math.min(cursor.total, cursor.revealed + revealStep(cursor.total - cursor.revealed));
+        advanced = true;
+    }
+    if (advanced) {
+        revealVersionValue += 1;
+        // #185 self-heal: a forceStoreRerender enqueue can surface the overflow
+        // here; React resets the counter on throw, so absorb and drop the tick.
+        for (const listener of [...revealListeners]) {
+            try {
+                listener();
+            }
+            catch (error) {
+                if (!swallowNestedUpdateOverflow(error, 'reveal.tick'))
+                    throw error;
+            }
+        }
+    }
+    else {
+        stopRevealTimerIfIdle();
+    }
+}
+/** Subscribe to reveal-frame wakeups (MessageList + tool cards). */
+export function subscribeReveal(listener) {
+    revealListeners.add(listener);
+    return () => {
+        revealListeners.delete(listener);
+    };
+}
+/** Snapshot for useSyncExternalStore; bumps once per advancing tick. */
+export function getRevealVersion() {
+    return revealVersionValue;
+}
+/** Force-complete (and forget) a cursor: expanded card, replaced view, … */
+export function snapReveal(key) {
+    if (textCursors.delete(key) || countCursors.delete(key))
+        markRevealCompleted(key);
+}
+/**
+ * Revealed length of `text` for `key` — the cursor logic of
+ * {@link revealTextOf} without the slice allocation (layout signatures read
+ * this every render for every visible row).
+ */
+export function revealLengthOf(key, text, options) {
+    if (!options.enabled) {
+        // Mid-stream settings toggle off: retire any cursor, show everything.
+        if (textCursors.delete(key)) {
+            markRevealCompleted(key);
+            stopRevealTimerIfIdle();
+        }
+        return text.length;
+    }
+    const existing = textCursors.get(key);
+    if (existing === undefined) {
+        // Completed earlier (caught up / snapped / replaced): paint full — a
+        // re-reveal would blank the already-complete content and typewrite it
+        // again.
+        if (completedReveals.has(key))
+            return text.length;
+        if (!options.active)
+            return text.length;
+        textCursors.set(key, { text, revealed: 0 });
+        ensureRevealTimer();
+        return 0;
+    }
+    if (text !== existing.text) {
+        if (text.startsWith(existing.text)) {
+            existing.text = text;
+            ensureRevealTimer();
+        }
+        else {
+            // Replacement: snap to the new text in full.
+            textCursors.delete(key);
+            markRevealCompleted(key);
+            stopRevealTimerIfIdle();
+            return text.length;
+        }
+    }
+    return Math.min(existing.revealed, text.length);
+}
+/**
+ * Revealed prefix of `text` for `key`. Monotonic appends (streaming deltas)
+ * keep the cursor; a non-prefix replacement (rewind, folded preview
+ * truncation) snaps to the new text — never animate across a discontinuity
+ * the reader did not witness as streaming. Feed the result into the
+ * streaming renderer (StreamingMarkdown); the monotonic prefix it receives
+ * keeps its stable-prefix memoization fully effective.
+ */
+export function revealTextOf(key, text, options) {
+    const len = revealLengthOf(key, text, options);
+    if (len >= text.length)
+        return text;
+    return text.slice(0, safeSliceEnd(text, len));
+}
+/**
+ * Revealed unit count for `key` over `total` units (tool-card body lines,
+ * split-diff rows). A SMALLER total always snaps (content that shrank is a
+ * replacement, not an append); growth keeps the cursor. Callers own the
+ * append-vs-replace decision for growing totals (pass a fresh key or call
+ * {@link snapReveal} when the content behind the same key is replaced).
+ */
+export function revealLinesOf(key, total, options) {
+    if (total <= REVEAL_MIN_STEP) {
+        // Nothing worth animating (a one-line "Running…" card): retire and
+        // return full — also covers total === 0.
+        if (countCursors.delete(key)) {
+            markRevealCompleted(key);
+            stopRevealTimerIfIdle();
+        }
+        return total;
+    }
+    if (!options.enabled) {
+        if (countCursors.delete(key)) {
+            markRevealCompleted(key);
+            stopRevealTimerIfIdle();
+        }
+        return total;
+    }
+    const existing = countCursors.get(key);
+    if (existing === undefined) {
+        if (completedReveals.has(key))
+            return total;
+        if (!options.active)
+            return total;
+        countCursors.set(key, { total, revealed: 0 });
+        ensureRevealTimer();
+        return 0;
+    }
+    if (total !== existing.total) {
+        if (total > existing.total) {
+            existing.total = total;
+            ensureRevealTimer();
+        }
+        else {
+            countCursors.delete(key);
+            markRevealCompleted(key);
+            stopRevealTimerIfIdle();
+            return total;
+        }
+    }
+    return Math.min(existing.revealed, total);
+}
+// ---------------------------------------------------------------------------
+// Test seams
+// ---------------------------------------------------------------------------
+/** Clear every cursor/listener/timer (verify scripts between cases). */
+export function resetRevealForTest() {
+    textCursors.clear();
+    countCursors.clear();
+    completedReveals.clear();
+    revealListeners.clear();
+    if (revealTimer !== undefined) {
+        clearInterval(revealTimer);
+        revealTimer = undefined;
+    }
+    revealVersionValue = 0;
+}
+/** Whether the shared scheduler currently runs (refcount assertions). */
+export function isRevealTimerRunning() {
+    return revealTimer !== undefined;
+}

package/lib/types/components/trajectory/HotspotView.d.ts

@@ -0,0 +1,20 @@
+import React from 'react';
+import type { HotspotRow, HotspotSort, TrajAggregate } from '../../dsh-adapter/types.js';
+/** Flatten the three sections into the single list the cursor walks. */
+export declare function hotspotRows(agg: TrajAggregate): HotspotRow[];
+export declare function HotspotView({ agg, sort, width, height, cursor, tick, switchTick, onRowClick, }: {
+    agg: TrajAggregate;
+    sort: HotspotSort;
+    width: number;
+    height: number;
+    cursor: number;
+    tick: number;
+    switchTick: number;
+    /**
+     * Mouse pick (fullscreen): reports the clicked row's cursor index — the
+     * scene jumps back to the timeline positioned on the group's first member
+     * (same path as the keyboard Enter). Hover shows a dim `▸` pointer.
+     */
+    onRowClick?: (cursorIndex: number) => void;
+}): React.ReactNode;
+//# sourceMappingURL=HotspotView.d.ts.map

package/lib/types/components/trajectory/HotspotView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HotspotView.d.ts","sourceRoot":"","sources":["../../../../src/components/trajectory/HotspotView.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAMzB,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AA6CxF,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,GAAG,EAAE,aAAa,GAAG,UAAU,EAAE,CAE5D;AAOD,wBAAgB,WAAW,CAAC,EAC1B,GAAG,EACH,IAAI,EACJ,KAAK,EACL,MAAM,EACN,MAAM,EACN,IAAI,EACJ,UAAU,EACV,UAAU,GACX,EAAE;IACD,GAAG,EAAE,aAAa,CAAA;IAClB,IAAI,EAAE,WAAW,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAA;CAC3C,GAAG,KAAK,CAAC,SAAS,CA6FlB"}