@askdkc/dsh-cli 0.11.3

package/lib/types/screens/TrajectoryScene.js

@@ -0,0 +1,374 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import React from 'react';
+import { Box, Text, useInput, useTerminalSize } from '../ui.js';
+import { useAnimationFrame } from '../ink/hooks/use-animation-frame.js';
+import { Divider } from '../components/design-system/Divider.js';
+import { HintLine } from '../components/design-system/HintLine.js';
+import { WaveBand } from '../components/trajectory/WaveBand.js';
+import { Ledger } from '../components/trajectory/Ledger.js';
+import { Inspector } from '../components/trajectory/Inspector.js';
+import { HotspotView, hotspotRows } from '../components/trajectory/HotspotView.js';
+import { applyQuery, parseQuery } from '../trajectory/query.js';
+import { MOTION_TICK_MS } from '../trajectory/motion.js';
+import { formatDuration, formatTokens, truncateWidth } from '../trajectory/format.js';
+import { stringWidth } from '../ink/stringWidth.js';
+import { t } from '../i18n.js';
+import { aggregate, burstErrors, columnOfIndex, inspectNode, projectWave, } from '../dsh-adapter/trajectory/index.js';
+import { HOTSPOT_SORTS, WAVE_PROJECTIONS } from '../dsh-adapter/trajectory/index.js';
+/**
+ * The trajectory scene — the session's own screen.
+ *
+ * Rather than carving a panel out of the conversation, the trajectory takes
+ * the whole terminal the way `less`, `fzf` and `lazygit` do, and gives it back
+ * untouched on exit. That is not only a layout choice: the alternate screen
+ * has no scrollback, so none of the frame churn this view generates can reach
+ * the transcript — the inline shrink-frame path that once deposited UI copies
+ * into scrollback (issues #38/#39/#19/#10) is structurally out of reach here.
+ *
+ * Four regions, top to bottom: the header, the wake (whole session as one
+ * band), the ledger, and the inspector. Every region except the ledger has a
+ * fixed height, so moving the cursor never resizes the frame.
+ */
+/** Inspector height in the default (unexpanded) layout. */
+const INSPECTOR_ROWS = 6;
+/**
+ * Rows the ledger does not get: header, tabs, the wake's two rows, one blank
+ * line under the wake, the hint line, and one blank line above it.
+ *
+ * The two blank lines are deliberate. A view that fills every row edge to edge
+ * reads as pressure regardless of how good the individual rows are; giving the
+ * chrome and the content a line of ground between them costs two rows out of
+ * thirty and buys the whole screen room to breathe.
+ */
+const CHROME_ROWS = 2 + 2 + 1 + 1 + 1;
+export function TrajectoryScene({ channel, build, onClose, }) {
+    const { columns, rows } = useTerminalSize();
+    const [ref, time] = useAnimationFrame(MOTION_TICK_MS);
+    const tick = Math.floor(time / MOTION_TICK_MS);
+    const [view, setView] = React.useState('timeline');
+    const [cursor, setCursor] = React.useState(0);
+    const [hotCursor, setHotCursor] = React.useState(0);
+    const [queryOpen, setQueryOpen] = React.useState(false);
+    const [queryText, setQueryText] = React.useState('');
+    // Compressed wall-clock is the default: it reads as a session profile — busy
+    // stretches are wide AND tall, idle gaps collapse to a thin flat run — while
+    // the pure sequence axis is the specialist view for scanning what happened.
+    const [projection, setProjection] = React.useState('compressed');
+    const [sort, setSort] = React.useState('duration');
+    const [expanded, setExpanded] = React.useState(false);
+    const [inspectScroll, setInspectScroll] = React.useState(0);
+    /** Ticks at which one-shot motion verbs were triggered. */
+    const [switchTick, setSwitchTick] = React.useState(0);
+    const [alertTick, setAlertTick] = React.useState(0);
+    const [arrivalTick, setArrivalTick] = React.useState(0);
+    const [arrivalFrom, setArrivalFrom] = React.useState(Number.MAX_SAFE_INTEGER);
+    /** Cursor pinned to the tail until the user scrolls away from it. */
+    const [follow, setFollow] = React.useState(true);
+    /** Mouse hover states for the tab segments and the sort/projection label. */
+    const [hoverTab, setHoverTab] = React.useState(null);
+    const [hoverAxis, setHoverAxis] = React.useState(false);
+    /** Hover state for the header ✕ exit button. */
+    const [closeHovered, setCloseHovered] = React.useState(false);
+    // ── projection ───────────────────────────────────────────────────────────
+    const nodes = build.nodes;
+    const query = React.useMemo(() => parseQuery(queryText), [queryText]);
+    const { rows: filtered, indexes } = React.useMemo(() => applyQuery(nodes, query), 
+    // `nodes` is mutated in place by the incremental fold, so its length is
+    // the honest dependency — the array identity never changes.
+    // oxlint-disable-next-line react-hooks/exhaustive-deps
+    [nodes, nodes.length, query]);
+    const agg = React.useMemo(
+    // oxlint-disable-next-line react-hooks/exhaustive-deps
+    () => aggregate(build, sort), [build, nodes.length, sort]);
+    // ── arrival + alert detection ────────────────────────────────────────────
+    const seenRef = React.useRef(0);
+    const errorsRef = React.useRef(0);
+    React.useEffect(() => {
+        if (nodes.length > seenRef.current) {
+            setArrivalFrom(seenRef.current);
+            setArrivalTick(tick);
+            seenRef.current = nodes.length;
+            if (follow)
+                setCursor(Math.max(0, filtered.length - 1));
+        }
+        if (agg.totals.errors > errorsRef.current) {
+            errorsRef.current = agg.totals.errors;
+            setAlertTick(tick);
+        }
+    }, [nodes.length, agg.totals.errors, tick, follow, filtered.length]);
+    // ── geometry ─────────────────────────────────────────────────────────────
+    const inspectorRows = expanded ? Math.max(4, rows - CHROME_ROWS - 3) : INSPECTOR_ROWS;
+    const ledgerRows = Math.max(1, rows - CHROME_ROWS - inspectorRows - 1);
+    const bandWidth = Math.max(1, columns - 4);
+    const clampedCursor = filtered.length === 0 ? 0 : Math.min(cursor, filtered.length - 1);
+    const windowStart = Math.max(0, Math.min(clampedCursor - Math.floor(ledgerRows / 2), filtered.length - ledgerRows));
+    const band = React.useMemo(
+    // oxlint-disable-next-line react-hooks/exhaustive-deps
+    () => projectWave(nodes, bandWidth, projection), [nodes, nodes.length, bandWidth, projection]);
+    const matchColumns = React.useMemo(() => {
+        if (query.empty)
+            return undefined;
+        const set = new Set();
+        for (const index of indexes)
+            set.add(columnOfIndex(band, index));
+        return set;
+    }, [band, indexes, query.empty]);
+    const focused = filtered[clampedCursor];
+    const detail = React.useMemo(() => (focused === undefined ? undefined : inspectNode(focused, channel.traceEvents())), [focused, channel]);
+    // ── navigation helpers ───────────────────────────────────────────────────
+    const move = React.useCallback((delta) => {
+        setExpanded(false);
+        setInspectScroll(0);
+        setCursor(previous => {
+            const next = Math.max(0, Math.min(filtered.length - 1, previous + delta));
+            setFollow(next >= filtered.length - 1);
+            return next;
+        });
+    }, [filtered.length]);
+    const seek = React.useCallback((predicate, forward) => {
+        const from = clampedCursor;
+        const limit = filtered.length;
+        for (let step = 1; step <= limit; step++) {
+            const index = forward ? from + step : from - step;
+            if (index < 0 || index >= limit)
+                continue;
+            if (predicate(index)) {
+                setExpanded(false);
+                setInspectScroll(0);
+                setCursor(index);
+                setFollow(index >= limit - 1);
+                return;
+            }
+        }
+    }, [clampedCursor, filtered.length]);
+    const isFailure = React.useCallback((index) => {
+        const node = filtered[index];
+        return (node !== undefined &&
+            (node.status === 'error' || node.kind === 'retry' || (node.burst !== undefined && burstErrors(node.burst) > 0)));
+    }, [filtered]);
+    const switchView = React.useCallback((next) => {
+        setView(next);
+        setSwitchTick(tick);
+        setExpanded(false);
+        setInspectScroll(0);
+    }, [tick]);
+    /**
+     * Jump back to the timeline, positioned on a hotspot group's first member —
+     * the keyboard Enter path, shared with the mouse row click.
+     */
+    const jumpFromHotspot = React.useCallback((row) => {
+        switchView('timeline');
+        if (row !== undefined) {
+            const target = indexes.indexOf(row.firstIndex);
+            setCursor(target >= 0 ? target : 0);
+            setFollow(false);
+        }
+    }, [indexes, switchView]);
+    /** Mouse wheel over the content area: move the selection, not a viewport. */
+    const handleWheel = React.useCallback((event) => {
+        if (view === 'hotspot') {
+            const total = hotspotRows(agg).length;
+            const direction = event.deltaY >= 0 ? 1 : -1;
+            setHotCursor(previous => Math.max(0, Math.min(total - 1, previous + direction)));
+            return;
+        }
+        if (expanded) {
+            // Expanded inspector owns the wheel: same page step as j/k.
+            const direction = event.deltaY >= 0 ? 1 : -1;
+            setInspectScroll(previous => Math.max(0, previous + direction * Math.max(1, inspectorRows - 2)));
+            return;
+        }
+        move(event.deltaY);
+    }, [view, agg, expanded, inspectorRows, move]);
+    /** Jump the timeline cursor to a filtered index (keyboard jump semantics). */
+    const jumpTo = React.useCallback((index) => {
+        setInspectScroll(0);
+        setCursor(index);
+        setFollow(index >= filtered.length - 1);
+    }, [filtered.length]);
+    // ── keys ─────────────────────────────────────────────────────────────────
+    useInput((input, key) => {
+        // The query line owns the keyboard while open, so a `q` typed into a
+        // search does not close the scene.
+        if (queryOpen) {
+            if (key.escape) {
+                setQueryOpen(false);
+                setQueryText('');
+                return;
+            }
+            if (key.return) {
+                setQueryOpen(false);
+                return;
+            }
+            if (key.backspace || key.delete) {
+                setQueryText(previous => previous.slice(0, -1));
+                setCursor(0);
+                return;
+            }
+            if (input && !key.ctrl && !key.meta) {
+                setQueryText(previous => previous + input);
+                setCursor(0);
+            }
+            return;
+        }
+        if (key.escape || input === 'q') {
+            if (expanded) {
+                setExpanded(false);
+                setInspectScroll(0);
+                return;
+            }
+            if (!query.empty) {
+                setQueryText('');
+                return;
+            }
+            onClose();
+            return;
+        }
+        if (key.leftArrow)
+            return switchView('timeline');
+        if (key.rightArrow)
+            return switchView('hotspot');
+        if (input === 'h')
+            return switchView(view === 'hotspot' ? 'timeline' : 'hotspot');
+        if (input === '/') {
+            setQueryOpen(true);
+            return;
+        }
+        if (view === 'hotspot') {
+            const total = hotspotRows(agg).length;
+            if (key.upArrow)
+                return setHotCursor(previous => Math.max(0, previous - 1));
+            if (key.downArrow)
+                return setHotCursor(previous => Math.min(total - 1, previous + 1));
+            if (input === 't') {
+                setSort(previous => HOTSPOT_SORTS[(HOTSPOT_SORTS.indexOf(previous) + 1) % HOTSPOT_SORTS.length]);
+                setSwitchTick(tick);
+                return;
+            }
+            if (key.return) {
+                // Jump back to the timeline, positioned on the group's first member.
+                return jumpFromHotspot(hotspotRows(agg)[hotCursor]);
+            }
+            return;
+        }
+        if (key.upArrow)
+            return move(-1);
+        if (key.downArrow)
+            return move(1);
+        if (key.pageUp)
+            return move(-ledgerRows);
+        if (key.pageDown)
+            return move(ledgerRows);
+        // Bare-letter jumps must not fire on Ctrl+G (the prompt's external-editor
+        // key) or other modified chords that share the letter.
+        if (input === 'g' && !key.ctrl && !key.meta && !key.super) {
+            setCursor(0);
+            setFollow(false);
+            return;
+        }
+        if (input === 'G' && !key.ctrl && !key.meta && !key.super) {
+            setCursor(Math.max(0, filtered.length - 1));
+            setFollow(true);
+            return;
+        }
+        if (input === '[')
+            return seek(isFailure, false);
+        if (input === ']')
+            return seek(isFailure, true);
+        if (input === '{')
+            return seek(index => filtered[index]?.kind === 'turn', false);
+        if (input === '}')
+            return seek(index => filtered[index]?.kind === 'turn', true);
+        if (input === 'm') {
+            setProjection(previous => WAVE_PROJECTIONS[(WAVE_PROJECTIONS.indexOf(previous) + 1) % WAVE_PROJECTIONS.length]);
+            setSwitchTick(tick);
+            return;
+        }
+        if (key.return) {
+            setExpanded(previous => !previous);
+            setInspectScroll(0);
+            return;
+        }
+        if (expanded && (input === 'j' || input === 'k')) {
+            setInspectScroll(previous => Math.max(0, previous + (input === 'j' ? inspectorRows - 2 : -(inspectorRows - 2))));
+        }
+    });
+    // ── header ───────────────────────────────────────────────────────────────
+    //
+    // Both chrome rows are composed as ONE pre-measured line each rather than as
+    // a flex row of groups. Flex plus `wrap="truncate"` proved unreliable here:
+    // a right-hand group laid out at its natural width lost its last character,
+    // and under other splits the overflow reflowed onto the row below — which
+    // pushes every region beneath it down and breaks the fixed geometry the
+    // whole scene depends on. Padding to an exact column count is deterministic,
+    // CJK-aware, and cheap (two strings per frame).
+    const { totals } = agg;
+    /** Left text, a computed gap, right text — clipped to `width` columns. */
+    const spread = (left, right, width) => {
+        const rightText = truncateWidth(right, Math.max(0, width - 4));
+        const room = width - stringWidth(rightText);
+        const leftText = truncateWidth(left, Math.max(0, room - 1));
+        return {
+            left: leftText,
+            gap: ' '.repeat(Math.max(1, room - stringWidth(leftText))),
+            right: rightText,
+        };
+    };
+    const totalsText = t('traj-totals', { turns: totals.turns, steps: totals.rows }) +
+        (totals.errors > 0 ? ` \u00b7 ${t('traj-errors', { n: totals.errors })}` : '') +
+        (totals.retries > 0 ? ` \u00b7 ${t('traj-retries', { n: totals.retries })}` : '') +
+        ` \u00b7 ${formatDuration(totals.spanMs)}`;
+    // ✕ 退出按钮占 2 格（` ✕`）：预量测行给右端留出预算，按钮钉在末列
+    const CLOSE_WIDTH = 2;
+    const headerLine = spread(`\u2726 ${t('traj-title')}  ${channel.sessionTitle ?? channel.cwd}`, totalsText, bandWidth - CLOSE_WIDTH);
+    const header = (_jsxs(Box, { width: "100%", height: 1, flexShrink: 0, children: [_jsx(Box, { flexShrink: 0, width: bandWidth - CLOSE_WIDTH, children: _jsxs(Text, { children: [_jsx(Text, { color: "accent", bold: true, children: `\u2726 ${t('traj-title')}` }), _jsx(Text, { color: "subtle", children: headerLine.left.slice((`\u2726 ${t('traj-title')}`).length) }), _jsx(Text, { children: headerLine.gap }), _jsx(Text, { color: totals.errors > 0 ? 'error' : 'subtle', children: headerLine.right })] }) }), _jsx(Box, { flexShrink: 0, width: CLOSE_WIDTH, 
+                // 可点击退出（q/Esc 的鼠标等价）——hover 提亮给出可点指示
+                onClick: () => onClose(), onMouseEnter: () => setCloseHovered(true), onMouseLeave: () => setCloseHovered(false), children: _jsx(Text, { color: closeHovered ? 'text' : 'subtle', children: ' ✕' }) })] }));
+    const axisLabel = view === 'hotspot' ? t(`traj-sort-${sort}`) : t(`traj-proj-${projection}`);
+    const tabTimelineText = `${view === 'timeline' ? '\u25cf' : '\u25cb'} ${t('traj-tab-timeline')}  `;
+    const tabHotspotText = `${view === 'hotspot' ? '\u25cf' : '\u25cb'} ${t('traj-tab-hotspot')}`;
+    const queryText_ = queryOpen || !query.empty
+        ? `   / ${queryText}${queryOpen ? '\u258c' : ''}  ${t('traj-matches', { n: filtered.length, total: nodes.length })}`
+        : '';
+    const tabsLeft = tabTimelineText + tabHotspotText;
+    const tabsLine = spread(tabsLeft + queryText_, axisLabel, bandWidth);
+    // Segment truncation mirrors spread's left-clip: the query tail yields
+    // first, then the far tab label — the line stays exactly one row.
+    const leftRoom = stringWidth(tabsLine.left);
+    const hotspotShown = truncateWidth(tabHotspotText, Math.max(0, leftRoom - stringWidth(tabTimelineText)));
+    const queryShown = queryText_ === ''
+        ? ''
+        : truncateWidth(queryText_, Math.max(0, leftRoom - stringWidth(tabTimelineText) - stringWidth(hotspotShown)));
+    const tabs = (_jsxs(Box, { width: "100%", height: 1, flexShrink: 0, children: [_jsx(Box, { flexShrink: 0, width: stringWidth(tabTimelineText), onClick: () => switchView('timeline'), onMouseEnter: () => setHoverTab('timeline'), onMouseLeave: () => setHoverTab(previous => (previous === 'timeline' ? null : previous)), children: _jsx(Text, { color: view === 'timeline' ? 'permission' : hoverTab === 'timeline' ? 'text' : 'subtle', bold: view === 'timeline', children: tabTimelineText }) }), _jsx(Box, { flexShrink: 0, width: stringWidth(hotspotShown), onClick: () => switchView('hotspot'), onMouseEnter: () => setHoverTab('hotspot'), onMouseLeave: () => setHoverTab(previous => (previous === 'hotspot' ? null : previous)), children: _jsx(Text, { color: view === 'hotspot' ? 'permission' : hoverTab === 'hotspot' ? 'text' : 'subtle', bold: view === 'hotspot', children: hotspotShown }) }), queryShown !== '' && (_jsx(Box, { flexShrink: 0, width: stringWidth(queryShown), onClick: () => setQueryOpen(true), children: _jsx(Text, { color: "suggestion", children: queryShown }) })), _jsx(Box, { flexGrow: 1, flexShrink: 1, onClick: () => { if (!queryOpen)
+                    setQueryOpen(true); }, children: _jsx(Text, { children: tabsLine.gap }) }), _jsx(Box, { flexShrink: 0, 
+                // +1 slack: ink breaks a wrap line exactly AT the box width, so a
+                // wide-char-ending label (按耗时) at an exact fit loses its last
+                // glyph to a clipped second line (the truncateWidth doc's trap).
+                // The flexGrow gap absorbs the extra cell.
+                width: stringWidth(tabsLine.right) + 1, onClick: () => {
+                    if (view === 'hotspot') {
+                        setSort(previous => HOTSPOT_SORTS[(HOTSPOT_SORTS.indexOf(previous) + 1) % HOTSPOT_SORTS.length]);
+                    }
+                    else {
+                        setProjection(previous => WAVE_PROJECTIONS[(WAVE_PROJECTIONS.indexOf(previous) + 1) % WAVE_PROJECTIONS.length]);
+                    }
+                    setSwitchTick(tick);
+                }, onMouseEnter: () => setHoverAxis(true), onMouseLeave: () => setHoverAxis(false), children: _jsx(Text, { color: hoverAxis ? 'text' : 'subtle', children: tabsLine.right }) })] }));
+    const hints = view === 'hotspot'
+        ? t('traj-hint-hotspot')
+        : queryOpen
+            ? t('traj-hint-query')
+            : expanded
+                ? t('traj-hint-expanded')
+                : t('traj-hint-timeline');
+    return (_jsxs(Box, { ref: ref, flexDirection: "column", width: "100%", paddingX: 1, children: [header, tabs, _jsx(WaveBand, { band: band, width: bandWidth, cursorColumn: columnOfIndex(band, indexes[clampedCursor] ?? 0), viewportStart: columnOfIndex(band, indexes[windowStart] ?? 0), viewportEnd: columnOfIndex(band, indexes[Math.min(filtered.length - 1, windowStart + ledgerRows - 1)] ?? 0), matches: matchColumns, tick: tick, alertTick: alertTick, onColumnClick: column => {
+                    // 点击波形列（或标尺行）= 跳到该列最近事件；空列继承前驱的
+                    // firstIndex，空档区点击落在空档开始处。查询过滤掉的行不跳。
+                    const nodeIndex = band.buckets[column]?.firstIndex ?? -1;
+                    if (nodeIndex < 0)
+                        return;
+                    const target = indexes.indexOf(nodeIndex);
+                    if (target >= 0)
+                        jumpTo(target);
+                } }), _jsx(Box, { height: 1, flexShrink: 0, children: _jsx(Text, { children: " " }) }), _jsx("ink-box", { style: { flexDirection: 'column', flexGrow: 1, flexShrink: 1, overflow: 'hidden', width: '100%' }, onWheel: handleWheel, children: view === 'timeline' ? (_jsxs(_Fragment, { children: [_jsx(Ledger, { rows: filtered, start: windowStart, height: ledgerRows, cursor: clampedCursor, width: columns - 4, tick: tick, arrivalTick: arrivalTick, arrivalFrom: arrivalFrom, onRowClick: index => jumpTo(index) }), _jsx(Divider, { color: "permission", width: bandWidth }), _jsx(Inspector, { node: focused, detail: detail, height: inspectorRows, width: columns - 4, expanded: expanded, scroll: inspectScroll })] })) : (_jsx(HotspotView, { agg: agg, sort: sort, width: columns - 4, height: ledgerRows + inspectorRows + 1, cursor: hotCursor, tick: tick, switchTick: switchTick, onRowClick: index => jumpFromHotspot(hotspotRows(agg)[index]) })) }), _jsx(Box, { height: 1, flexShrink: 0, children: _jsx(Text, { children: " " }) }), _jsx(Box, { width: "100%", height: 1, flexShrink: 0, children: _jsxs(Text, { dimColor: true, italic: true, wrap: "truncate", children: [_jsx(HintLine, { text: hints }), totals.tokens.input > 0 ? (_jsx(Text, { color: "subtle", children: `   ${formatTokens(totals.tokens.input)}→${formatTokens(totals.tokens.output)}` })) : ('')] }) })] }));
+}

package/lib/types/screens/chatOverlay.d.ts

@@ -0,0 +1,267 @@
+/**
+ * The chat screen's transient-dialog layer (the pickers, dialogs and panels
+ * that float above the prompt in `<OverlayAbove>`, plus /tips) as one
+ * explicit state machine.
+ *
+ * Previously this layer lived in ~28 sibling `useState` booleans+indices in
+ * Chat.tsx, with mutual exclusion emerging from "an open picker makes the
+ * prompt inert, so no second open command can be typed", and with two
+ * hand-maintained OR-aggregates (`promptSelectionActive`,
+ * `dialogOverlayOpen`) whose comments warned they must stay exactly in sync
+ * with the per-panel render conditions. A single discriminated union makes
+ * the exclusion structural — one variable can only hold one variant — and
+ * turns both aggregates into derivations that cannot drift.
+ *
+ * Design constraints, in order:
+ *   1. Behavior-preserving: every keyboard path, open/close side effect and
+ *      async-callback landing keeps its observable behavior. The one
+ *      deliberate change: an async OPEN landing while another overlay is up
+ *      (e.g. `/effort`'s listEfforts resolving after the user opened
+ *      `/model`) now REPLACES it instead of stacking two panels — the
+ *      stacked rendering was an unreachable-by-keyboard race, not a feature.
+ *   2. Pure and total: the reducer is a plain function, unit-tested by
+ *      scripts/verify-chat-overlay.ts without a renderer. Actions that no
+ *      longer apply (an async result landing after the overlay changed) are
+ *      ignored rather than writing orphan state.
+ *   3. Async data caches (model list, preset roster, …) stay OUTSIDE the
+ *      union in Chat.tsx: they persist across open/close so a reopened
+ *      picker can paint the previous list while the fresh one loads,
+ *      exactly as before.
+ */
+import type { ChatRow, PermissionPresetSnapshot } from '../dsh-adapter/channel.js';
+import type { TranscriptImage } from '../dsh-adapter/transcript-images.js';
+import type { TuiRewindMode } from '../dsh-adapter/extension-events.js';
+import type { TuiWorkspaceCommandResult } from '../workspaces.js';
+/** The `kind: 'choices'` result a workspace command can return. */
+export type WorkspaceFlowChoices = Extract<TuiWorkspaceCommandResult, {
+    kind: 'choices';
+}>;
+/** Text-entry sub-state of the workspace flow (Tab into a choice's input). */
+export type WorkspaceFlowInput = {
+    choiceId: string;
+    value: string;
+    cursor: number;
+    placeholder?: string;
+};
+export type ChatOverlay = {
+    kind: 'none';
+} | {
+    kind: 'thinking';
+    focus: number;
+} | {
+    kind: 'workspace-picker';
+    index: number;
+} | {
+    kind: 'workspace-menu';
+    index: number;
+} | {
+    kind: 'workspace-flow';
+    flow: WorkspaceFlowChoices;
+    index: number;
+    busy: boolean;
+    input: WorkspaceFlowInput | null;
+} | {
+    kind: 'model';
+    index: number;
+} | {
+    kind: 'skills';
+    index: number;
+} | {
+    kind: 'migrate';
+    index: number;
+} | {
+    kind: 'migrate-confirm';
+} | {
+    kind: 'activity';
+    index: number;
+} | {
+    kind: 'color';
+    index: number;
+} | {
+    kind: 'effort';
+    index: number;
+} | {
+    kind: 'preset';
+    index: number;
+} | {
+    kind: 'theme';
+    index: number;
+} | {
+    kind: 'permission';
+    index: number;
+    snapshot: PermissionPresetSnapshot;
+} | {
+    kind: 'plan';
+    index: number;
+} | {
+    kind: 'lang';
+    index: number;
+} | {
+    kind: 'history';
+    query: string;
+    cursor: number;
+    focus: number;
+} | {
+    kind: 'rewind';
+    index: number;
+    confirm: ChatRow | null;
+    modes: readonly TuiRewindMode[] | null;
+    modeIndex: number;
+    busy: boolean;
+} | {
+    kind: 'search';
+} | {
+    kind: 'tips';
+}
+/**
+ * Click-to-act file menu: opened by clicking a file path in the
+ * transcript (tool cards, markdown code spans / plain text, file://
+ * links). `index` is the focused action row (0 = open, 1 = reveal in
+ * file manager, 2 = copy absolute path). `isDir` tells the panel whether
+ * the target is a directory (first row reads "open folder").
+ */
+ | {
+    kind: 'file-actions';
+    path: string;
+    index: number;
+    isDir: boolean;
+}
+/**
+ * Modal image preview: opened by clicking a transcript thumbnail. Renders
+ * as its own centered layer (not inside `<OverlayAbove>`); Esc /
+ * click-outside closes. The composer's caret-driven preview (the caret on
+ * a staged `[Image #N]`) is NOT an overlay: it is derived state in Chat,
+ * shows only while this union is `none`, and leaves the keyboard with the
+ * prompt.
+ */
+ | {
+    kind: 'image-preview';
+    image: TranscriptImage;
+    title?: string;
+    gallery?: readonly {
+        image: TranscriptImage;
+        title?: string;
+    }[];
+    index?: number;
+};
+export declare const NO_OVERLAY: ChatOverlay;
+export type ChatOverlayAction = 
+/** Open a variant, replacing whatever is up (including `none`). */
+{
+    type: 'open';
+    overlay: ChatOverlay;
+}
+/** Close unconditionally (only dispatched from the open overlay's own keys). */
+ | {
+    type: 'close';
+}
+/** Navigate the frozen gallery without wrapping or changing another modal. */
+ | {
+    type: 'image-step';
+    delta: 1 | -1;
+}
+/** Close only if the given kind is still up — the safe form for async
+ *  callbacks (a loader failing after the user already moved on). */
+ | {
+    type: 'close-if';
+    kind: ChatOverlay['kind'];
+}
+/**
+ * Open only while the current kind is one of `when` — the safe form for an
+ * OPEN that arrives from an async callback (`/effort`'s level list, the
+ * workspace target list, a workspace command's choices). A user who opened
+ * something else during the round trip keeps what they opened; the stale
+ * open is dropped. Synchronous opens keep using plain `open`.
+ */
+ | {
+    type: 'open-if';
+    overlay: ChatOverlay;
+    when: readonly ChatOverlay['kind'][];
+}
+/**
+ * Move the focused row by one with wrap-around, over a list of `count`
+ * entries. On `rewind` this targets whichever cursor the sub-state focuses
+ * (mode list when a plugin offered modes, else the candidate list). A
+ * `count <= 0` move is a no-op (an empty list has no focus to move).
+ */
+ | {
+    type: 'move';
+    delta: 1 | -1;
+    count: number;
+}
+/** Set the focused row to an absolute index — an async loader landing
+ *  with the authoritative focus (model list / preset roster), or a mouse
+ *  click on a row of a panel that stays open (effort slider, workspace
+ *  flow). Ignored unless that panel is still up. */
+ | {
+    type: 'set-index';
+    kind: 'model' | 'preset' | 'effort' | 'permission' | 'workspace-flow' | 'rewind' | 'file-actions';
+    index: number;
+}
+/** Edit the history-search draft (query text, caret, focused match). */
+ | {
+    type: 'history-edit';
+    query?: string;
+    cursor?: number;
+    focus?: number;
+}
+/** Workspace flow: an action is running (keys except Esc are swallowed). */
+ | {
+    type: 'flow-busy';
+    busy: boolean;
+}
+/** Workspace flow: enter (object) or leave (null) the text-input state. */
+ | {
+    type: 'flow-input';
+    input: WorkspaceFlowInput | null;
+}
+/** Workspace flow: edit the text-input draft in place. */
+ | {
+    type: 'flow-input-edit';
+    value: string;
+    cursor: number;
+}
+/** Rewind: the plugin decision round-trip started / was abandoned. */
+ | {
+    type: 'rewind-busy';
+    busy: boolean;
+}
+/** Rewind: the plugin decision landed — show the confirm pane (modes turn
+ *  it into a choice list). Stale decisions are dropped by the caller's
+ *  request token before dispatch; a changed overlay drops them here. */
+ | {
+    type: 'rewind-decision';
+    confirm: ChatRow;
+    modes: readonly TuiRewindMode[] | null;
+}
+/** Rewind: Esc from the confirm/modes pane back to the candidate list. */
+ | {
+    type: 'rewind-back';
+};
+/**
+ * One-step wrap-around cursor move — the single source of the wrapping rule
+ * every list overlay uses (Chat.tsx's effort slider reads it too, to apply
+ * the newly focused level in the same keystroke that dispatches the move).
+ */
+export declare function wrapIndex(index: number, delta: 1 | -1, count: number): number;
+export declare function chatOverlayReducer(state: ChatOverlay, action: ChatOverlayAction): ChatOverlay;
+/**
+ * Whether the `<OverlayAbove>` wrapper mounts. Mounting is all-or-nothing:
+ * the renderer's removed-absolute-node blit detection only fires when the
+ * removed subtree itself is `position: absolute` (dom.ts
+ * collectRemovedRects), so the whole overlay must leave the tree when its
+ * last panel closes — see the mount-site comment in Chat.tsx.
+ *
+ * The per-kind data gates mirror the per-panel render conditions verbatim:
+ * a picker whose async list has not landed (or came back trivially small)
+ * paints nothing, so the wrapper must not mount for it either. `tips`
+ * returns true even though the panel renders in the prompt slot rather than
+ * inside the overlay — preserved verbatim from the boolean-era aggregate
+ * (the empty absolute wrapper is zero-size and paints nothing).
+ */
+export declare function dialogOverlayVisible(overlay: ChatOverlay, gates: {
+    workspaceTargetCount: number;
+    effortOptionCount: number;
+    presetOptionCount: number;
+}): boolean;
+//# sourceMappingURL=chatOverlay.d.ts.map

package/lib/types/screens/chatOverlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chatOverlay.d.ts","sourceRoot":"","sources":["../../../src/screens/chatOverlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAA;AAClF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAA;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAA;AACvE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAA;AAEjE,mEAAmE;AACnE,MAAM,MAAM,oBAAoB,GAAG,OAAO,CAAC,yBAAyB,EAAE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,CAAA;AAE1F,8EAA8E;AAC9E,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACzC;IACE,IAAI,EAAE,gBAAgB,CAAA;IACtB,IAAI,EAAE,oBAAoB,CAAA;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,OAAO,CAAA;IACb,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAA;CACjC,GACD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,iBAAiB,CAAA;CAAE,GAC3B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,wBAAwB,CAAA;CAAE,GACzE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjE;IACE,IAAI,EAAE,QAAQ,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;IACvB,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,IAAI,CAAA;IACtC,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,OAAO,CAAA;CACd,GAID;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;AAClB;;;;;;GAMG;GACD;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE;AACvE;;;;;;;GAOG;GACD;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,eAAe,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAC9D,OAAO,CAAC,EAAE,SAAS;QAAE,KAAK,EAAE,eAAe,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAEvF,eAAO,MAAM,UAAU,EAAE,WAA8B,CAAA;AAEvD,MAAM,MAAM,iBAAiB;AAC3B,mEAAmE;AACjE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,WAAW,CAAA;CAAE;AACxC,gFAAgF;GAC9E;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE;AACnB,8EAA8E;GAC5E;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,CAAA;CAAE;AACvC;oEACoE;GAClE;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAAE;AACjD;;;;;;GAMG;GACD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,SAAS,WAAW,CAAC,MAAM,CAAC,EAAE,CAAA;CAAE;AACjF;;;;;GAKG;GACD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AAChD;;;oDAGoD;GAClD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,YAAY,GAAG,gBAAgB,GAAG,QAAQ,GAAG,cAAc,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AACzI,wEAAwE;GACtE;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE;AAC3E,4EAA4E;GAC1E;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE;AACtC,2EAA2E;GACzE;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAA;CAAE;AAC1D,0DAA0D;GACxD;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AAC5D,sEAAsE;GACpE;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE;AACxC;;wEAEwE;GACtE;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,IAAI,CAAA;CAAE;AACvF,0EAA0E;GACxE;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAA;AAE3B;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAI7E;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,iBAAiB,GAAG,WAAW,CAqF7F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE;IACL,oBAAoB,EAAE,MAAM,CAAA;IAC5B,iBAAiB,EAAE,MAAM,CAAA;IACzB,iBAAiB,EAAE,MAAM,CAAA;CAC1B,GACA,OAAO,CAmBT"}