@askdkc/dsh-cli 0.11.3

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

@@ -0,0 +1,25 @@
+import React from 'react';
+/**
+ * `/recap` panel (pi-recap semantics), in the picker/dialog visual
+ * language: a permission-colored Pane with a title bar (会话回顾), a
+ * scrollable summary body (error / summary / answering spinner), the
+ * proposed session title row (apply via `a` or clicking the chip), and a
+ * dim italic hint line (click to copy, same as `c`). Owns the keyboard
+ * while open, mirroring BtwPanel.
+ */
+export declare function RecapPanel({ summary, title, error, streaming, titleApplied, onClose, onCopy, onApplyTitle, }: {
+    /** The one-line recap summary (streamed raw, then replaced on settle). */
+    summary: string;
+    /** Proposed session title from the recap call, when the model offered one. */
+    title?: string;
+    /** Human-readable failure reason. */
+    error?: string;
+    /** True while the recap call is in flight. */
+    streaming: boolean;
+    /** True once the proposed title was applied via renameSession. */
+    titleApplied: boolean;
+    onClose: () => void;
+    onCopy: () => void;
+    onApplyTitle: () => void;
+}): React.ReactNode;
+//# sourceMappingURL=RecapPanel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RecapPanel.d.ts","sourceRoot":"","sources":["../../../src/components/RecapPanel.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAOzB;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,EACzB,OAAO,EACP,KAAK,EACL,KAAK,EACL,SAAS,EACT,YAAY,EACZ,OAAO,EACP,MAAM,EACN,YAAY,GACb,EAAE;IACD,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAA;IACf,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8CAA8C;IAC9C,SAAS,EAAE,OAAO,CAAA;IAClB,kEAAkE;IAClE,YAAY,EAAE,OAAO,CAAA;IACrB,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,YAAY,EAAE,MAAM,IAAI,CAAA;CACzB,GAAG,KAAK,CAAC,SAAS,CAuFlB"}

package/lib/types/components/RecapPanel.js

@@ -0,0 +1,55 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from 'react';
+import { Box, Text, useInput, ScrollBox, useTerminalSize } from '../ui.js';
+import { SpinnerGlyph } from './Spinner/SpinnerGlyph.js';
+import { Pane } from './design-system/Pane.js';
+import { t } from '../i18n.js';
+import { isPlainReturnInput } from '../utils/modifiers.js';
+/**
+ * `/recap` panel (pi-recap semantics), in the picker/dialog visual
+ * language: a permission-colored Pane with a title bar (会话回顾), a
+ * scrollable summary body (error / summary / answering spinner), the
+ * proposed session title row (apply via `a` or clicking the chip), and a
+ * dim italic hint line (click to copy, same as `c`). Owns the keyboard
+ * while open, mirroring BtwPanel.
+ */
+export function RecapPanel({ summary, title, error, streaming, titleApplied, onClose, onCopy, onApplyTitle, }) {
+    const scrollRef = React.useRef(null);
+    const { rows } = useTerminalSize();
+    // Spinner frame (80ms cadence, only while waiting for the first text).
+    const [frame, setFrame] = React.useState(0);
+    React.useEffect(() => {
+        if (!streaming || summary !== '')
+            return;
+        const interval = setInterval(() => setFrame(f => f + 1), 80);
+        return () => clearInterval(interval);
+    }, [streaming, summary]);
+    const canApply = title !== undefined && title !== '' && !titleApplied;
+    useInput((input, key, event) => {
+        if (key.escape || isPlainReturnInput(input, key) || input === ' ') {
+            event.stopImmediatePropagation();
+            onClose();
+            return;
+        }
+        if (key.upArrow || key.downArrow) {
+            scrollRef.current?.scrollBy(key.upArrow ? -3 : 3);
+            event.stopImmediatePropagation();
+            return;
+        }
+        if (input === 'c' && !key.ctrl) {
+            event.stopImmediatePropagation();
+            onCopy();
+            return;
+        }
+        if (input === 'a' && !key.ctrl && canApply) {
+            event.stopImmediatePropagation();
+            onApplyTitle();
+            return;
+        }
+        // The overlay owns the keyboard while open: swallow everything else so
+        // nothing leaks into the prompt input behind it.
+        event.stopImmediatePropagation();
+    });
+    const settled = summary !== '' || error !== undefined;
+    return (_jsx(Pane, { color: "permission", children: _jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { marginBottom: 1, children: [_jsx(Text, { color: "remember", bold: true, children: t('recap-panel-title') }), _jsxs(Text, { dimColor: true, children: [" \u00B7 ", t('recap-panel-subtitle')] })] }), _jsx(Box, { flexDirection: "column", maxHeight: Math.max(5, rows - 11), children: _jsx(ScrollBox, { ref: scrollRef, flexDirection: "column", flexGrow: 1, children: error !== undefined ? (_jsx(Text, { color: "error", children: error })) : summary !== '' ? (_jsx(Text, { children: summary })) : (_jsxs(Box, { children: [_jsx(SpinnerGlyph, { frame: frame, messageColor: "warning" }), _jsxs(Text, { color: "warning", children: [" ", t('recap-answering')] })] })) }) }), title !== undefined && (_jsxs(Box, { flexDirection: "row", marginTop: 1, children: [_jsxs(Text, { dimColor: true, children: [t('recap-title-label'), ": "] }), _jsx(Text, { color: "suggestion", children: title }), titleApplied ? (_jsxs(Text, { color: "success", children: [" \u2713 ", t('recap-title-applied')] })) : (_jsx(Box, { onClick: canApply ? onApplyTitle : undefined, children: _jsxs(Text, { color: "success", bold: true, children: [' ', "[", t('recap-apply-title'), "]"] }) }))] })), _jsx(Box, { onClick: settled ? onCopy : undefined, children: _jsx(Text, { dimColor: true, italic: true, children: t('recap-hint', { apply: canApply ? ' · a ' + t('recap-apply-title') : '' }) }) })] }) }));
+}

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

@@ -0,0 +1,37 @@
+import React from 'react';
+import type { ChatRow } from '../dsh-adapter/channel.js';
+import type { TuiRewindMode } from '../dsh-adapter/extension-events.js';
+/**
+ * Double-Esc rewind picker (double-tap Esc rewinds the selected message and/or
+ * conversation to a previous point in time: lists the user's past messages
+ * newest-first; selecting one and confirming rewinds the conversation to
+ * that point (the message comes back into the input for re-editing).
+ *
+ * The confirm pane has two shapes: the plain one (Enter rewinds), and —
+ * when a plugin answered the tui/rewind-prompt decision with extra modes —
+ * a choice list whose option zero is always the built-in conversation-only
+ * rewind, followed by the plugin's modes (e.g. "also restore files").
+ */
+export declare function RewindPicker({ rows, focusIndex, confirmRow, modes, modeIndex, busy, onPickRow, onConfirm, onPickMode, }: {
+    rows: readonly ChatRow[];
+    focusIndex: number;
+    confirmRow: ChatRow | null;
+    /** Plugin-offered rewind modes (tui/rewind-prompt); null = plain confirm. */
+    modes?: readonly TuiRewindMode[] | null;
+    /** Focused option in the modes list (0 = conversation-only). */
+    modeIndex?: number;
+    /** True while the plugin decision is in flight. */
+    busy?: boolean;
+    /**
+     * Mouse pick on a list row (fullscreen): sets focus only — rewind is a
+     * high-risk invisible-confirm operation, so stepping into the confirm
+     * state stays an explicit keyboard Enter.
+     */
+    onPickRow?: (index: number) => void;
+    /** Mouse click on the plain confirm row: executes the rewind directly —
+     *  the confirm pane itself is the explicit confirmation layer. */
+    onConfirm?: () => void;
+    /** Mouse pick on a modes-list option: executes that mode directly. */
+    onPickMode?: (index: number) => void;
+}): React.ReactNode;
+//# sourceMappingURL=RewindPicker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RewindPicker.d.ts","sourceRoot":"","sources":["../../../src/components/RewindPicker.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAGzB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAA;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAA;AAOvE;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,EAC3B,IAAI,EACJ,UAAU,EACV,UAAU,EACV,KAAY,EACZ,SAAa,EACb,IAAY,EACZ,SAAS,EACT,SAAS,EACT,UAAU,GACX,EAAE;IACD,IAAI,EAAE,SAAS,OAAO,EAAE,CAAA;IACxB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,OAAO,GAAG,IAAI,CAAA;IAC1B,6EAA6E;IAC7E,KAAK,CAAC,EAAE,SAAS,aAAa,EAAE,GAAG,IAAI,CAAA;IACvC,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,mDAAmD;IACnD,IAAI,CAAC,EAAE,OAAO,CAAA;IACd;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACnC;sEACkE;IAClE,SAAS,CAAC,EAAE,MAAM,IAAI,CAAA;IACtB,sEAAsE;IACtE,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CACrC,GAAG,KAAK,CAAC,SAAS,CAyHlB"}

package/lib/types/components/RewindPicker.js

@@ -0,0 +1,66 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { t } from '../i18n.js';
+import { Box, Text } from '../ui.js';
+import { Pane } from './design-system/Pane.js';
+import { ListItem } from './design-system/ListItem.js';
+import { HintLine } from './design-system/HintLine.js';
+import { listWindow } from './listWindow.js';
+import { useOverlayListRows } from './OverlayAbove.js';
+/**
+ * Double-Esc rewind picker (double-tap Esc rewinds the selected message and/or
+ * conversation to a previous point in time: lists the user's past messages
+ * newest-first; selecting one and confirming rewinds the conversation to
+ * that point (the message comes back into the input for re-editing).
+ *
+ * The confirm pane has two shapes: the plain one (Enter rewinds), and —
+ * when a plugin answered the tui/rewind-prompt decision with extra modes —
+ * a choice list whose option zero is always the built-in conversation-only
+ * rewind, followed by the plugin's modes (e.g. "also restore files").
+ */
+export function RewindPicker({ rows, focusIndex, confirmRow, modes = null, modeIndex = 0, busy = false, onPickRow, onConfirm, onPickMode, }) {
+    // 两个列表的行预算都来自最近一层 OverlayAbove 的有效高度（已钳到输入簇
+    // 上方的真实空间，#493/#698）。hook 不进条件分支：无论当前画的是模式列
+    // 表、纯确认页还是消息列表，调用顺序都一致。框架行按实际渲染数：
+    // 模式列表：挂载包裹 marginTop 1 + Pane 2 + 标题/预览同一行 1 + marginBottom 1
+    //   + 页脚 1 = 6（rowCosts 只算选项行，首项是带描述的"仅对话"选项）；
+    // 消息列表：挂载包裹 marginTop 1 + Pane 2 + 标题+副标题 2 + marginBottom 1
+    //   + 页脚 1 = 7，插件决策在途时再多一行「等待插件」状态行（busy）。
+    const modeListRows = useOverlayListRows(6);
+    const listRows = useOverlayListRows(confirmRow === null && busy ? 8 : 7);
+    if (confirmRow !== null) {
+        if (modes !== null) {
+            // Plugin modes: a described choice list (one extra row per
+            // description), windowed like the message list below.
+            const rowCosts = [2, ...modes.map(mode => (mode.description === undefined ? 1 : 2))];
+            const { start, end } = listWindow(rowCosts, modeIndex, modeListRows);
+            const options = [
+                { key: 'conversation', label: t('rewind-mode-default'), description: t('rewind-confirm-desc') },
+                ...modes.map(mode => ({
+                    key: mode.id,
+                    label: mode.label,
+                    ...(mode.description === undefined ? {} : { description: mode.description }),
+                })),
+            ];
+            return (_jsxs(Pane, { color: "permission", children: [_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { marginBottom: 1, children: [_jsx(Text, { color: "remember", bold: true, children: t('rewind-confirm-title') }), _jsx(Text, { dimColor: true, children: preview(confirmRow.text) })] }), options.slice(start, end).map((option, index) => {
+                                const absoluteIndex = start + index;
+                                return (_jsx(ListItem, { isFocused: absoluteIndex === modeIndex, description: option.description, showScrollUp: absoluteIndex === start && start > 0, showScrollDown: absoluteIndex === end - 1 && end < options.length, onClick: onPickMode === undefined ? undefined : () => onPickMode(absoluteIndex), children: option.label }, option.key));
+                            })] }), _jsx(Text, { dimColor: true, italic: true, children: _jsx(HintLine, { text: t('hint-select-exit') }) })] }));
+        }
+        return (_jsx(Pane, { color: "permission", children: _jsxs(Box, { flexDirection: "column", children: [_jsx(Box, { marginBottom: 1, children: _jsx(Text, { color: "remember", bold: true, children: t('rewind-confirm-title') }) }), _jsx(ListItem, { isFocused: false, description: t('rewind-confirm-desc'), onClick: onConfirm, children: preview(confirmRow.text) }), _jsx(Text, { dimColor: true, italic: true, children: _jsx(HintLine, { text: t('hint-rewind-back') }) })] }) }));
+    }
+    // 焦点窗口化按行预算：首项带 'last message' 描述占 2 行、其余 1 行
+    //（ListItem 保证单行截断）。rewind 是不可见确认的高危操作，焦点必须
+    // 始终在屏。
+    const { start, end } = listWindow(rows.map((_, i) => (i === 0 ? 2 : 1)), focusIndex, listRows);
+    return (_jsxs(Pane, { color: "permission", children: [_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { marginBottom: 1, flexDirection: "column", children: [_jsx(Text, { color: "remember", bold: true, children: t('rewind-title') }), _jsx(Text, { dimColor: true, children: t('rewind-subtitle') })] }), rows.length === 0 ? (_jsx(ListItem, { isFocused: false, children: t('rewind-empty') })) : (rows.slice(start, end).map((row, index) => {
+                        const absoluteIndex = start + index;
+                        return (_jsx(ListItem, { isFocused: absoluteIndex === focusIndex, description: absoluteIndex === 0 ? t('rewind-last-message') : undefined, showScrollUp: absoluteIndex === start && start > 0, showScrollDown: absoluteIndex === end - 1 && end < rows.length, onClick: onPickRow !== undefined && !busy
+                                ? () => onPickRow(absoluteIndex)
+                                : undefined, children: preview(row.text) }, row.id));
+                    })), busy && _jsx(Text, { dimColor: true, children: t('rewind-waiting-plugins') })] }), _jsx(Text, { dimColor: true, italic: true, children: _jsx(HintLine, { text: t('hint-select-exit') }) })] }));
+}
+/** One-line preview of a message (newlines flattened, capped). */
+function preview(text) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    return flat.length <= 80 ? flat : `${flat.slice(0, 80)}…`;
+}

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

@@ -0,0 +1,43 @@
+import React from 'react';
+import { type ScrollBoxHandle } from '../ui.js';
+/**
+ * Proportional scrollbar for the fullscreen transcript's gutter — the
+ * `scrollbar` option of the `dsh-tui.scrollGutter` setting (the timeline
+ * rail's sibling; same 2-column slot, same chrome rules):
+ *
+ *  - the thumb (██) shows the visible window's position AND size over the
+ *    whole content (viewport²/content tall, positioned by scrollTop);
+ *  - clicking the track scrolls the clicked position to the viewport top
+ *    (classic scrollbar semantics — the thumb centers under the click
+ *    through the follow-up renders);
+ *  - dragging the track scrubs the transcript: the drag protocol's
+ *    per-target localRow maps through the SAME trackScrollTop as a click
+ *    (absolute mapping — drag to point, no grabbed thumb offset), so a
+ *    drag is a continuous run of click-to-position jumps. The mapping only
+ *    reads the render-time maxScroll/trackH and never re-reads scrollTop
+ *    mid-gesture, so a throttled/clamped scrollTo cannot feed back into the
+ *    pointer mapping (no jitter). Dragging the thumb therefore lands the
+ *    pointer's row at the viewport top, exactly like clicking that row;
+ *  - a landing (drag or the back-to-bottom affordance) breaks and re-pins
+ *    sticky, which unmounts the chrome that had shrunk the transcript row;
+ *    the re-pinning Ink pass follows the commit and fires no subscriber
+ *    notify, so the gutter re-reads the handle once that frame lands (see
+ *    the subscribe effect). Without it the thumb stays painted from the
+ *    shrunken viewport and floats a few rows above the bottom until an
+ *    unrelated render (hover) re-reads the handle;
+ *  - the gutter is permanent while scrollable (Qwen's rule: an
+ *    auto-hiding gutter that changes content width rewraps everything);
+ *    hidden below 60 terminal columns or when the content fits (inline
+ *    mode keeps the terminal's native scrollback);
+ *  - NoSelect fences the glyphs out of click-drag text selection; the
+ *    wheel over the gutter scrolls the transcript. Because the track is a
+ *    drag target, an unmodified left drag scrubs instead of selecting, and
+ *    multi-clicks on the track no longer feed the select-line chain;
+ *    Shift/Alt/Ctrl drags never open a drag session and keep the
+ *    selection path.
+ */
+export declare function ScrollbarGutter({ handle, terminalWidth, }: {
+    handle: ScrollBoxHandle | null;
+    terminalWidth: number;
+}): React.ReactNode;
+//# sourceMappingURL=ScrollbarGutter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ScrollbarGutter.d.ts","sourceRoot":"","sources":["../../../src/components/ScrollbarGutter.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AACzB,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,UAAU,CAAA;AAqBpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,eAAe,CAAC,EAC9B,MAAM,EACN,aAAa,GACd,EAAE;IACD,MAAM,EAAE,eAAe,GAAG,IAAI,CAAA;IAC9B,aAAa,EAAE,MAAM,CAAA;CACtB,GAAG,KAAK,CAAC,SAAS,CA6LlB"}

package/lib/types/components/ScrollbarGutter.js

@@ -0,0 +1,197 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from 'react';
+import { Box, Text, NoSelect } from '../ui.js';
+import { FRAME_INTERVAL_MS } from '../ink/constants.js';
+import { RAIL_MIN_TERMINAL_WIDTH, RAIL_WIDTH } from '../ink/timeline-rail.js';
+/** Thumb glyph across the 2-col gutter: solid, clearly positional —
+ *  deliberately distinct from the timeline's ━━ active tick. */
+const THUMB = '██';
+/** Rest time before the hover position chip pops (anti-flash sweep gate). */
+const CHIP_DWELL_MS = 250;
+/**
+ * Post-landing settle reads (see the subscribe effect): how many deferred
+ * re-reads follow a landing before giving up. The re-pinning Ink pass lands
+ * a frame or two after the commit, so a single read can still catch the
+ * pre-landing geometry — the bound only exists so a frame that never
+ * settles cannot chain renders forever.
+ */
+const PIN_SETTLE_CHECKS = 3;
+/**
+ * Proportional scrollbar for the fullscreen transcript's gutter — the
+ * `scrollbar` option of the `dsh-tui.scrollGutter` setting (the timeline
+ * rail's sibling; same 2-column slot, same chrome rules):
+ *
+ *  - the thumb (██) shows the visible window's position AND size over the
+ *    whole content (viewport²/content tall, positioned by scrollTop);
+ *  - clicking the track scrolls the clicked position to the viewport top
+ *    (classic scrollbar semantics — the thumb centers under the click
+ *    through the follow-up renders);
+ *  - dragging the track scrubs the transcript: the drag protocol's
+ *    per-target localRow maps through the SAME trackScrollTop as a click
+ *    (absolute mapping — drag to point, no grabbed thumb offset), so a
+ *    drag is a continuous run of click-to-position jumps. The mapping only
+ *    reads the render-time maxScroll/trackH and never re-reads scrollTop
+ *    mid-gesture, so a throttled/clamped scrollTo cannot feed back into the
+ *    pointer mapping (no jitter). Dragging the thumb therefore lands the
+ *    pointer's row at the viewport top, exactly like clicking that row;
+ *  - a landing (drag or the back-to-bottom affordance) breaks and re-pins
+ *    sticky, which unmounts the chrome that had shrunk the transcript row;
+ *    the re-pinning Ink pass follows the commit and fires no subscriber
+ *    notify, so the gutter re-reads the handle once that frame lands (see
+ *    the subscribe effect). Without it the thumb stays painted from the
+ *    shrunken viewport and floats a few rows above the bottom until an
+ *    unrelated render (hover) re-reads the handle;
+ *  - the gutter is permanent while scrollable (Qwen's rule: an
+ *    auto-hiding gutter that changes content width rewraps everything);
+ *    hidden below 60 terminal columns or when the content fits (inline
+ *    mode keeps the terminal's native scrollback);
+ *  - NoSelect fences the glyphs out of click-drag text selection; the
+ *    wheel over the gutter scrolls the transcript. Because the track is a
+ *    drag target, an unmodified left drag scrubs instead of selecting, and
+ *    multi-clicks on the track no longer feed the select-line chain;
+ *    Shift/Alt/Ctrl drags never open a drag session and keep the
+ *    selection path.
+ */
+export function ScrollbarGutter({ handle, terminalWidth, }) {
+    const [, setTick] = React.useState(0);
+    // Geometry the last render painted with. The Ink render pass runs AFTER
+    // React's commit, so the commit that lands a pinned view can paint from
+    // geometry that pass is about to change (see the subscribe effect).
+    const geomRef = React.useRef('');
+    // Hover readout: the row under the pointer brightens the thumb when it is
+    // the hovered one, and floats a `62% · 340/540` chip left of the gutter
+    // naming the position a click there would jump to. The chip is
+    // dwell-gated (TimelineRail's preview-card rule): a sweep across the
+    // track brightens rows but never pops chips — only ~250ms of rest does.
+    // Once shown it follows row changes immediately; leaving hides it.
+    const [hoverRow, setHoverRow] = React.useState(null);
+    const [chipRow, setChipRow] = React.useState(null);
+    const dwellTimer = React.useRef(null);
+    const clearDwell = () => {
+        if (dwellTimer.current !== null) {
+            clearTimeout(dwellTimer.current);
+            dwellTimer.current = null;
+        }
+    };
+    const clearChip = () => {
+        clearDwell();
+        setChipRow(null);
+    };
+    React.useEffect(() => clearDwell, []);
+    React.useEffect(() => {
+        if (!handle)
+            return;
+        const readGeom = () => `${handle.getScrollTop()}:${handle.getScrollHeight()}:${handle.getViewportHeight()}`;
+        let timer = null;
+        let checksLeft = 0;
+        // Landing settle re-read. Reaching the bottom breaks and then re-pins
+        // sticky; the commit that consumes the notification paints while the
+        // chrome that shrank the transcript row (`PinnedTurnHeader` +
+        // "return to bottom" pill, both `!isSticky`) is still mounted, and the
+        // NEXT Ink pass then grows the viewport back and re-pins scrollTop to
+        // the taller maxScroll — with NO subscriber notify, because sticky
+        // never flips again (ScrollBox's subscribe contract). Nothing would
+        // re-read the handle, so the thumb stays painted from the shrunken
+        // viewport and floats above the bottom until an unrelated render
+        // (hover) rescues it. Re-read once that pass has landed and re-render
+        // if the geometry moved; only pinned notifications arm this (a landing
+        // is the one shape that can be re-pinned after the commit), so the
+        // cost is a couple of timers per landing, never per scroll frame.
+        const settle = () => {
+            timer = null;
+            if (readGeom() !== geomRef.current)
+                setTick(t => t + 1);
+            if (--checksLeft > 0)
+                timer = setTimeout(settle, FRAME_INTERVAL_MS);
+        };
+        const unsubscribe = handle.subscribe(() => {
+            setTick(t => t + 1);
+            if (!handle.isSticky())
+                return;
+            checksLeft = PIN_SETTLE_CHECKS;
+            if (timer === null)
+                timer = setTimeout(settle, FRAME_INTERVAL_MS);
+        });
+        return () => {
+            unsubscribe();
+            if (timer !== null)
+                clearTimeout(timer);
+        };
+    }, [handle]);
+    // Geometry the last COMMITTED render painted with: captured during render,
+    // but the ref write happens in the layout effect below — this root is a
+    // ConcurrentRoot, so a render pass can be discarded, and a render-phase
+    // write would leak a frame that never painted into settle()'s diff.
+    const viewport = handle === null ? 0 : handle.getViewportHeight();
+    const content = handle === null ? 0 : handle.getScrollHeight();
+    const scrollTop = handle === null ? 0 : handle.getScrollTop();
+    const geom = handle === null ? null : `${scrollTop}:${content}:${viewport}`;
+    React.useLayoutEffect(() => {
+        if (geom !== null)
+            geomRef.current = geom;
+    }, [geom]);
+    if (!handle)
+        return null;
+    const maxScroll = Math.max(0, content - viewport);
+    if (viewport < 2 || content <= viewport || terminalWidth < RAIL_MIN_TERMINAL_WIDTH)
+        return null;
+    // Thumb: the visible window mapped onto the gutter. Height proportional
+    // to the visible fraction (≥2 rows so it is always grabbable-looking);
+    // top follows scrollTop over the scroll range.
+    const thumbH = Math.max(2, Math.round((viewport * viewport) / content));
+    const trackH = Math.max(1, viewport - thumbH);
+    const thumbTop = Math.round((scrollTop / Math.max(1, maxScroll)) * trackH);
+    const thumbBottom = Math.min(viewport, thumbTop + thumbH);
+    // Clicking the track maps the clicked row's position on the track back
+    // to a scrollTop and scrolls that content position to the viewport top.
+    // Dragging reuses the same mapping per motion through the drag protocol's
+    // target-relative localRow (the outer track is the single drag target).
+    const trackScrollTop = (y) => {
+        if (y <= 0)
+            return 0;
+        if (y >= trackH)
+            return maxScroll;
+        return Math.round((y / trackH) * maxScroll);
+    };
+    const applyDragRow = (event) => {
+        handle.scrollTo(trackScrollTop(event.localRow));
+    };
+    const rows = [];
+    for (let y = 0; y < viewport; y++) {
+        const inThumb = y >= thumbTop && y < thumbBottom;
+        rows.push(_jsx(Box, { height: 1, flexShrink: 0, onClick: () => handle.scrollTo(trackScrollTop(y)), onMouseEnter: () => {
+                setHoverRow(y);
+                // Resting pointer: chip follows immediately once dwell has
+                // opened it; a sweep re-arms the dwell instead of flashing.
+                clearDwell();
+                if (chipRow !== null) {
+                    setChipRow(y);
+                }
+                else {
+                    dwellTimer.current = setTimeout(() => setChipRow(y), CHIP_DWELL_MS);
+                }
+            }, onMouseLeave: () => {
+                setHoverRow(current => (current === y ? null : current));
+                clearChip();
+            }, children: _jsx(Text, { color: inThumb
+                    ? hoverRow !== null && hoverRow >= thumbTop && hoverRow < thumbBottom
+                        ? 'professionalBlue'
+                        : 'inactive'
+                    : undefined, children: inThumb ? THUMB : '  ' }) }, y));
+    }
+    // The floating position chip, anchored left of the gutter on the
+    // dwell-armed row (TimelineRail's preview-card geometry, one line tall).
+    // Absolute + zero layout contribution: popping it never moves anything.
+    // Fenced with noSelect: it floats over selectable transcript text.
+    let hoverChip = null;
+    if (chipRow !== null && maxScroll > 0) {
+        const jumpTop = trackScrollTop(chipRow);
+        const pct = Math.round((jumpTop / maxScroll) * 100);
+        const line = Math.min(content, jumpTop + 1);
+        hoverChip = (_jsx(Box, { position: "absolute", top: chipRow, right: RAIL_WIDTH + 1, flexShrink: 0, backgroundColor: "toolCardBackgroundDim", paddingX: 1, noSelect: true, children: _jsx(Text, { color: "text", children: `${pct}% · ${line}/${content}` }) }));
+    }
+    return (_jsx(NoSelect, { children: _jsxs("ink-box", { onWheel: e => {
+                if (e.deltaY !== 0)
+                    handle.scrollBy(e.deltaY);
+            }, onDragStart: applyDragRow, onDragMove: applyDragRow, onDragEnd: applyDragRow, style: { flexDirection: 'column', flexShrink: 0, width: RAIL_WIDTH }, children: [rows, hoverChip] }) }));
+}

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

@@ -0,0 +1,24 @@
+import React from 'react';
+/**
+ * A single-line search input in a round-bordered box: `⌕ ` prefix, block
+ * cursor at `cursorOffset` (inverse cell).
+ * When empty and focused, a solid block caret sits at the start and the
+ * placeholder is right-aligned (dimmed) — kept off the caret's cell so the
+ * terminal-painted IME preedit (pinyin) can never be overlaid on it during
+ * CJK composition.
+ *
+ * The query row is strictly single-line: an overlong query is windowed
+ * around the caret (horizontal scroll) instead of wrapping, so the native
+ * cursor declaration below stays exact for any query length.
+ */
+export declare function SearchBox({ query, placeholder, isFocused, isTerminalFocused, prefix, width, cursorOffset, borderless, }: {
+    query: string;
+    placeholder?: string;
+    isFocused: boolean;
+    isTerminalFocused: boolean;
+    prefix?: string;
+    width?: number | string;
+    cursorOffset?: number;
+    borderless?: boolean;
+}): React.ReactNode;
+//# sourceMappingURL=SearchBox.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SearchBox.d.ts","sourceRoot":"","sources":["../../../src/components/SearchBox.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAyD,MAAM,OAAO,CAAA;AAyD7E;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,EACxB,KAAK,EACL,WAAuB,EACvB,SAAS,EACT,iBAAiB,EACjB,MAAY,EACZ,KAAK,EACL,YAAY,EACZ,UAAkB,GACnB,EAAE;IACD,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,OAAO,CAAA;IAClB,iBAAiB,EAAE,OAAO,CAAA;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACvB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB,GAAG,KAAK,CAAC,SAAS,CA0GlB"}

package/lib/types/components/SearchBox.js

@@ -0,0 +1,132 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useLayoutEffect, useRef, useState } from 'react';
+import Box from './design-system/ThemedBox.js';
+import Text from './design-system/ThemedText.js';
+import measureElement from '../ink/measure-element.js';
+import { useDeclaredCursor } from '../ink/hooks/use-declared-cursor.js';
+import { useTerminalSize } from '../ink/hooks/use-terminal-size.js';
+import { stringWidth } from '../ink/stringWidth.js';
+/**
+ * Window a single-line query around the caret so the visible slice fits
+ * `avail` display cells (CJK display width, code-point safe — `[...s]`
+ * iterates code points, not UTF-16 units). The caret character itself
+ * always stays inside the window: leading characters are dropped until
+ * before-caret text + caret fit, then after-caret text fills what remains.
+ * `offset` arrives in UTF-16 units (callers move the caret by key count);
+ * a mid-surrogate offset would split an emoji, so it snaps back to the
+ * pair's start first.
+ */
+function windowQuery(query, offset, avail) {
+    const budget = Math.max(avail, 1);
+    let caret = Math.max(0, Math.min(offset, query.length));
+    if (caret > 0 &&
+        caret < query.length &&
+        query.charCodeAt(caret - 1) >= 0xd800 &&
+        query.charCodeAt(caret - 1) <= 0xdbff &&
+        query.charCodeAt(caret) >= 0xdc00 &&
+        query.charCodeAt(caret) <= 0xdfff) {
+        caret--; // mid-surrogate: snap to the emoji's start
+    }
+    const beforeChars = [...query.slice(0, caret)];
+    const at = caret < query.length ? [...query.slice(caret)][0] : ' ';
+    const atWidth = Math.max(1, stringWidth(at));
+    let caretColumn = 0;
+    for (const ch of beforeChars)
+        caretColumn += stringWidth(ch);
+    let start = 0;
+    while (start < beforeChars.length && caretColumn + atWidth > budget) {
+        caretColumn -= stringWidth(beforeChars[start]);
+        start++;
+    }
+    let rest = budget - caretColumn - atWidth;
+    let after = '';
+    for (const ch of [...query.slice(caret + at.length)]) {
+        const w = stringWidth(ch);
+        if (w > rest)
+            break;
+        after += ch;
+        rest -= w;
+    }
+    return { before: beforeChars.slice(start).join(''), at, after, caretColumn };
+}
+/**
+ * A single-line search input in a round-bordered box: `⌕ ` prefix, block
+ * cursor at `cursorOffset` (inverse cell).
+ * When empty and focused, a solid block caret sits at the start and the
+ * placeholder is right-aligned (dimmed) — kept off the caret's cell so the
+ * terminal-painted IME preedit (pinyin) can never be overlaid on it during
+ * CJK composition.
+ *
+ * The query row is strictly single-line: an overlong query is windowed
+ * around the caret (horizontal scroll) instead of wrapping, so the native
+ * cursor declaration below stays exact for any query length.
+ */
+export function SearchBox({ query, placeholder = 'Search…', isFocused, isTerminalFocused, prefix = '⌕', width, cursorOffset, borderless = false, }) {
+    const offset = cursorOffset ?? query.length;
+    const borderStyle = borderless ? undefined : 'round';
+    const borderColor = isFocused ? 'suggestion' : undefined;
+    const borderDimColor = !isFocused;
+    // Focused + empty + terminal focused: inline caret row (block caret at the
+    // start, placeholder right-aligned) instead of the inline placeholder.
+    const inlineCaret = isFocused && query === '' && isTerminalFocused;
+    // Content width of the box in display cells. Measured from yoga after
+    // layout (resize re-layouts without any prop/state change, so measure on
+    // every commit — the setState is a no-op when the width is unchanged);
+    // the terminal-columns estimate only covers the very first frame.
+    const { columns } = useTerminalSize();
+    const chrome = borderless ? 0 : 4; // 2 border cells + paddingX 2
+    const [measuredWidth, setMeasuredWidth] = useState(null);
+    const contentWidth = measuredWidth ?? Math.max(8, columns - chrome - 2);
+    const prefixWidth = stringWidth(`${prefix} `);
+    const win = windowQuery(query, offset, contentWidth - prefixWidth);
+    // Park the native terminal cursor at the caret so IME preedit (pinyin)
+    // renders inline at the input instead of the screen's bottom row (same
+    // mechanism as PromptInput). The declaration hangs on the outer Box —
+    // content stays a single Text (splitting it into flex siblings
+    // reorders/drops glyphs on narrow widths), so the position is computed:
+    // border (1) + paddingX (1) per edge when bordered, then the `prefix `
+    // run and the windowed before-caret text, all in display cells.
+    const showCaret = isFocused && isTerminalFocused;
+    // Clamp into the box's content area: on absurdly narrow layouts the
+    // prefix alone can meet or exceed the content width, and the park must
+    // never land outside the box's rect.
+    const edge = borderless ? 0 : 2;
+    const maxColumn = edge + Math.max(0, contentWidth - 1);
+    const caretColumn = Math.min(edge + prefixWidth + win.caretColumn, maxColumn);
+    const declarationRef = useDeclaredCursor({
+        line: borderless ? 0 : 1,
+        column: caretColumn,
+        active: showCaret,
+    });
+    const boxNodeRef = useRef(null);
+    const boxRef = useCallback((node) => {
+        boxNodeRef.current = node;
+        declarationRef(node);
+    }, [declarationRef]);
+    useLayoutEffect(() => {
+        const node = boxNodeRef.current;
+        if (!node)
+            return;
+        // Layout runs before layout effects (reconciler resetAfterCommit), so a
+        // zero raw width means a genuinely zero-width box — but a zero CONTENT
+        // width (chrome eats the whole box) is a real, must-clamp case.
+        const raw = measureElement(node).width;
+        if (raw > 0) {
+            const w = Math.max(0, raw - chrome);
+            setMeasuredWidth(prev => (prev === w ? prev : w));
+        }
+    });
+    let content;
+    if (isFocused) {
+        if (query) {
+            content = isTerminalFocused ? (_jsxs(_Fragment, { children: [_jsx(Text, { children: win.before }), _jsx(Text, { inverse: true, children: win.at }), win.after !== '' && _jsx(Text, { children: win.after })] })) : (_jsx(Text, { children: query }));
+        }
+        else if (!isTerminalFocused) {
+            content = _jsx(Text, { dimColor: true, children: placeholder });
+        }
+    }
+    else {
+        content = query ? _jsx(Text, { children: query }) : _jsx(Text, { children: placeholder });
+    }
+    return (_jsx(Box, { ref: boxRef, flexShrink: 0, borderStyle: borderStyle, borderColor: borderColor, borderDimColor: borderDimColor, paddingX: borderless ? 0 : 1, width: width, children: inlineCaret ? (_jsxs(Box, { flexDirection: "row", width: "100%", children: [_jsxs(Text, { children: [prefix, " "] }), _jsx(Text, { inverse: true, children: " " }), _jsx(Box, { flexGrow: 1 }), _jsx(Text, { dimColor: true, wrap: "truncate", children: placeholder })] })) : (_jsxs(Text, { dimColor: !isFocused, wrap: "truncate-end", children: [prefix, " ", content] })) }));
+}

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

@@ -0,0 +1,29 @@
+import React from 'react';
+import type { ClickEvent } from '../ink/events/click-event.js';
+export type SelectOption = {
+    value: string;
+    /** Row content; plain strings render inline, richer rows may carry color swatches. */
+    label: React.ReactNode;
+    description?: string;
+};
+/**
+ * A single-choice select list with the standard dsh-TUI visual treatment:
+ * ListItem rows with ❯ focus pointer, ✓ selected checkmark, descriptions,
+ * scroll arrows). Keyboard navigation is owned by the parent dialog, which
+ * passes focus/selection indices back in.
+ */
+export declare function Select({ options, focusIndex, selectedValue, visibleOptionCount, onPick, }: {
+    options: readonly SelectOption[];
+    /** Index of the keyboard-focused row (shows the ❯ pointer). */
+    focusIndex: number;
+    /** Value of the chosen row (shows the ✓ checkmark). */
+    selectedValue: string | undefined;
+    visibleOptionCount?: number;
+    /**
+     * Mouse pick handler (fullscreen). Clicking a row reports the row's
+     * absolute index — the parent typically applies it with the same code
+     * path as the keyboard Enter. Absent → rows are not clickable.
+     */
+    onPick?: (index: number, value: string, event: ClickEvent) => void;
+}): React.ReactNode;
+//# sourceMappingURL=Select.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Select.d.ts","sourceRoot":"","sources":["../../../src/components/Select.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAEzB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAA;AAG9D,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,sFAAsF;IACtF,KAAK,EAAE,KAAK,CAAC,SAAS,CAAA;IACtB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,EACrB,OAAO,EACP,UAAU,EACV,aAAa,EACb,kBAAsB,EACtB,MAAM,GACP,EAAE;IACD,OAAO,EAAE,SAAS,YAAY,EAAE,CAAA;IAChC,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAA;IAClB,uDAAuD;IACvD,aAAa,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,KAAK,IAAI,CAAA;CACnE,GAAG,KAAK,CAAC,SAAS,CAsClB"}