@askdkc/dsh-cli 0.11.3

package/lib/types/components/ThinkingToggle.js

@@ -0,0 +1,25 @@
+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 { Select } from './Select.js';
+import { HintLine } from './design-system/HintLine.js';
+/**
+ * The `/thinking` display dialog: a permission-colored Pane with a bold
+ * title, the Shown/Hidden select, and the Enter/Esc hint line.
+ */
+export function ThinkingToggle({ currentValue, focusIndex, onPick, }) {
+    const options = [
+        {
+            value: 'true',
+            label: t('thinking-enabled'),
+            description: t('thinking-enabled-desc'),
+        },
+        {
+            value: 'false',
+            label: t('thinking-disabled'),
+            description: t('thinking-disabled-desc'),
+        },
+    ];
+    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('thinking-title') }), _jsx(Text, { dimColor: true, children: t('thinking-subtitle') })] }), _jsx(Box, { flexDirection: "column", marginBottom: 1, children: _jsx(Select, { options: options, focusIndex: focusIndex, selectedValue: currentValue ? 'true' : 'false', visibleOptionCount: 2, onPick: onPick === undefined ? undefined : (index) => onPick(index) }) })] }), _jsx(Text, { dimColor: true, italic: true, children: _jsx(HintLine, { text: t('hint-confirm-exit') }) })] }));
+}

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

@@ -0,0 +1,53 @@
+import React from 'react';
+import { type ScrollBoxHandle } from '../ui.js';
+import { type TimelineTurn } from '../ink/timeline-rail.js';
+/**
+ * Timeline rail: the fullscreen transcript's turn navigator — a 2-column
+ * gutter REPLACING the classic scrollbar (Grok Build's timeline sidebar,
+ * ported to the dsh Ink tree).
+ *
+ *  - one tick per user turn; tick position encodes conversation order,
+ *    not scroll proportion (a long answer must not skew the timeline);
+ *  - the tick of the turn owning the viewport top row (the turn being
+ *    read — same anchor the sticky prompt header pins) renders as `━━`;
+ *    hovering a tick widens it to `──` and pops a preview card left of
+ *    the rail; idle ticks are a short dim ` ─`;
+ *  - ▲ / ▾ step between turns by STRICT geometry (nearest prompt above /
+ *    below the viewport top — never `active ± 1`, which can name a turn
+ *    no scroll reaches), so a dim chevron is always a guaranteed no-op;
+ *  - clicking a tick (or chevron) jumps by content coordinate — the
+ *    prompt's measured top — no element seek, no force-mount race;
+ *  - more turns than rows: the window slides around the active tick, and
+ *    pins to the tail while at the bottom (never excluding active);
+ *  - hidden below 60 terminal columns, under 2 turns, under 3 viewport
+ *    rows, or when the content fits (inline mode keeps the terminal's
+ *    native scrollback).
+ *
+ * The whole 2-column width is the hit target; the rail is fenced with
+ * NoSelect so click-drag text selection never picks up its glyphs, and
+ * the wheel scrolls the transcript (the rail has no scroll of its own).
+ */
+export declare function TimelineRail({ handle, turns, activeId, upId, downId, terminalWidth, hoverEnabled, onRevealTurn, }: {
+    handle: ScrollBoxHandle | null;
+    /** Turns in conversation order (MessageList's measured snapshot). */
+    turns: ReadonlyArray<TimelineTurn>;
+    /** Turn owning the viewport top row (rail highlight target). */
+    activeId: number | null;
+    /** ▲ target: nearest turn strictly above the viewport top. */
+    upId: number | null;
+    /** ▼ target: nearest turn below the viewport top that a scroll can
+     *  still bring to the top row. */
+    downId: number | null;
+    terminalWidth: number;
+    /** False while a modal overlay owns the screen — suppress the hover
+     *  card (the rail itself stays, but stops narrating). */
+    hoverEnabled: boolean;
+    /**
+     * Reveal-and-seek for FOLDED turns (older than the recent-rows window):
+     * Chat expands the fold (showAll) and seeks through the force-mount
+     * path — the row's top is unknown until it mounts, so the coordinate
+     * jump below does not apply to it.
+     */
+    onRevealTurn: (rowId: number) => void;
+}): React.ReactNode;
+//# sourceMappingURL=TimelineRail.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TimelineRail.d.ts","sourceRoot":"","sources":["../../../src/components/TimelineRail.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AACzB,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,UAAU,CAAA;AAEpE,OAAO,EAKL,KAAK,YAAY,EAClB,MAAM,yBAAyB,CAAA;AAwBhC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,YAAY,CAAC,EAC3B,MAAM,EACN,KAAK,EACL,QAAQ,EACR,IAAI,EACJ,MAAM,EACN,aAAa,EACb,YAAY,EACZ,YAAY,GACb,EAAE;IACD,MAAM,EAAE,eAAe,GAAG,IAAI,CAAA;IAC9B,qEAAqE;IACrE,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,CAAA;IAClC,gEAAgE;IAChE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,8DAA8D;IAC9D,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB;sCACkC;IAClC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB;6DACyD;IACzD,YAAY,EAAE,OAAO,CAAA;IACrB;;;;;OAKG;IACH,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CACtC,GAAG,KAAK,CAAC,SAAS,CAuNlB"}

package/lib/types/components/TimelineRail.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 { stringWidth } from '../ink/stringWidth.js';
+import { RAIL_WIDTH, railEligible, computeRailGeometry, wrapPreviewLines, } from '../ink/timeline-rail.js';
+/** ▴ / ▾ (U+25B4 / U+25BE — the small triangles; CP437-safe on ConHost too). */
+const CHEVRON_UP = ' ▴';
+const CHEVRON_DOWN = ' ▾';
+/** Tick glyphs, right-aligned across the 2-col rail (Grok Build spec):
+ *  active = heavy stroke, hover = wide light stroke, idle = short dim
+ *  stroke in the rightmost cell. */
+const TICK_ACTIVE = '━━';
+const TICK_HOVER = '──';
+const TICK_IDLE = ' ─';
+/** Pointer rest time before the hover preview card pops (ms). Sweeps
+ *  never mount a card; only a deliberate pause does. */
+const HOVER_DWELL_MS = 120;
+/**
+ * Timeline rail: the fullscreen transcript's turn navigator — a 2-column
+ * gutter REPLACING the classic scrollbar (Grok Build's timeline sidebar,
+ * ported to the dsh Ink tree).
+ *
+ *  - one tick per user turn; tick position encodes conversation order,
+ *    not scroll proportion (a long answer must not skew the timeline);
+ *  - the tick of the turn owning the viewport top row (the turn being
+ *    read — same anchor the sticky prompt header pins) renders as `━━`;
+ *    hovering a tick widens it to `──` and pops a preview card left of
+ *    the rail; idle ticks are a short dim ` ─`;
+ *  - ▲ / ▾ step between turns by STRICT geometry (nearest prompt above /
+ *    below the viewport top — never `active ± 1`, which can name a turn
+ *    no scroll reaches), so a dim chevron is always a guaranteed no-op;
+ *  - clicking a tick (or chevron) jumps by content coordinate — the
+ *    prompt's measured top — no element seek, no force-mount race;
+ *  - more turns than rows: the window slides around the active tick, and
+ *    pins to the tail while at the bottom (never excluding active);
+ *  - hidden below 60 terminal columns, under 2 turns, under 3 viewport
+ *    rows, or when the content fits (inline mode keeps the terminal's
+ *    native scrollback).
+ *
+ * The whole 2-column width is the hit target; the rail is fenced with
+ * NoSelect so click-drag text selection never picks up its glyphs, and
+ * the wheel scrolls the transcript (the rail has no scroll of its own).
+ */
+export function TimelineRail({ handle, turns, activeId, upId, downId, terminalWidth, hoverEnabled, onRevealTurn, }) {
+    const [, setTick] = React.useState(0);
+    const [hover, setHover] = React.useState(null);
+    // Dwell-gated preview card: the card pops only after the pointer RESTS
+    // on a tick for HOVER_DWELL_MS. Sweeping the rail fires enter/leave per
+    // cell — without the gate each crossing mounts an absolute-positioned
+    // card at a new spot (flapping previews, absolute-rect churn, and the
+    // fast-sweep residue users reported). The glyph highlight stays instant
+    // (cheap, no overlay); only the card waits for intent.
+    const [cardIndex, setCardIndex] = React.useState(null);
+    const dwellTimerRef = React.useRef(null);
+    const clearDwell = React.useCallback(() => {
+        if (dwellTimerRef.current !== null) {
+            clearTimeout(dwellTimerRef.current);
+            dwellTimerRef.current = null;
+        }
+        setCardIndex(null);
+    }, []);
+    const armDwell = React.useCallback((index) => {
+        if (dwellTimerRef.current !== null)
+            clearTimeout(dwellTimerRef.current);
+        dwellTimerRef.current = setTimeout(() => {
+            dwellTimerRef.current = null;
+            setCardIndex(index);
+        }, HOVER_DWELL_MS);
+    }, []);
+    React.useEffect(() => () => {
+        if (dwellTimerRef.current !== null)
+            clearTimeout(dwellTimerRef.current);
+    }, []);
+    React.useEffect(() => {
+        if (!handle)
+            return;
+        return handle.subscribe(() => {
+            setTick(t => t + 1);
+            // A scroll (wheel over the rail, tick/chevron jump, header click)
+            // slides the tick window under a STATIONARY pointer — without this,
+            // the hover card keeps re-narrating whatever turn now sits under the
+            // pointer cell, flapping previews across turns every frame (reads as
+            // ghosting). OpenCode's modality rule: only a real mouse move may
+            // re-enter hover; Grok likewise clears the hover popup on tick click.
+            // setHover(null) on an already-null hover is a React no-op.
+            setHover(null);
+            clearDwell();
+        });
+    }, [handle, clearDwell]);
+    if (!handle)
+        return null;
+    const viewport = handle.getViewportHeight();
+    const content = handle.getScrollHeight();
+    const maxScroll = Math.max(0, content - viewport);
+    if (!railEligible({
+        turnCount: turns.length,
+        terminalWidth,
+        viewportRows: viewport,
+        scrollable: content > viewport,
+    }))
+        return null;
+    const activeIndex = turns.findIndex(t => t.id === activeId);
+    // Tail-pin the tick window while the viewport sits at the bottom
+    // (sticky flag OR positional) — newest ticks stay on screen.
+    const atBottom = handle.isSticky() || handle.getScrollTop() >= maxScroll;
+    const geo = computeRailGeometry(turns.length, viewport, activeIndex === -1 ? null : activeIndex, atBottom);
+    if (!geo)
+        return null;
+    // Jump by CONTENT COORDINATE, not by element: the target row is usually
+    // unmounted (virtualization), and the element-based seek's force-mount
+    // path races React's synchronous re-render (the renderer's deferred
+    // Yoga read can see a detached anchor and silently no-op). The turn's
+    // reported top is the measured text position — scrollTo() lands the
+    // prompt exactly at the viewport top; the renderer clamps unreachable
+    // tail tops to maxScroll (their turns stay on screen, just short of
+    // owning the top row — and ▼ never names them, see timeline-rail.ts).
+    // FOLDDED turns have no measured top (-1): their click (and ▲ naming
+    // one) routes through onRevealTurn instead — expand the fold, then the
+    // existing force-mount seek lands the row once it measures.
+    const jumpToIndex = (index) => {
+        const turn = turns[index];
+        if (!turn)
+            return;
+        if (turn.folded)
+            onRevealTurn(turn.id);
+        else
+            handle.scrollTo(turn.top);
+    };
+    const jumpToId = (id) => {
+        if (id === null)
+            return;
+        const index = turns.findIndex(t => t.id === id);
+        if (index !== -1)
+            jumpToIndex(index);
+    };
+    const shown = geo.windowEnd - geo.windowStart;
+    const chevron = (kind) => {
+        const enabled = (kind === 'up' ? upId : downId) !== null;
+        const hovered = hover?.kind === kind;
+        const glyph = kind === 'up' ? CHEVRON_UP : CHEVRON_DOWN;
+        const color = !enabled ? 'subtle' : hovered ? 'text' : 'inactive';
+        return (_jsx(Box, { height: 1, flexShrink: 0, onClick: () => jumpToId(kind === 'up' ? upId : downId), onMouseEnter: () => setHover({ kind }), onMouseLeave: () => setHover(null), children: _jsx(Text, { color: color, children: glyph }) }, kind));
+    };
+    const tickRows = [];
+    for (let k = 0; k < shown; k++) {
+        const index = geo.windowStart + k;
+        const turn = turns[index];
+        const isActive = index === activeIndex;
+        const isHovered = hover?.kind === 'tick' && hover.index === index;
+        const glyph = isActive ? TICK_ACTIVE : isHovered ? TICK_HOVER : TICK_IDLE;
+        const color = isActive || isHovered ? 'text' : 'subtle';
+        tickRows.push(_jsx(Box, { height: 1, flexShrink: 0, onClick: () => jumpToIndex(index), onMouseEnter: () => {
+                setHover({ kind: 'tick', index });
+                armDwell(index);
+            }, onMouseLeave: () => {
+                setHover(null);
+                clearDwell();
+            }, children: _jsx(Text, { color: color, children: glyph }) }, turn.id));
+    }
+    // Hover preview card, anchored left of the rail and vertically centered
+    // on the hovered tick (shrink-to-fit, rounded chrome). Dwell-gated: only
+    // cardIndex (armed after HOVER_DWELL_MS of rest) draws — a sweep keeps
+    // hover flashing on glyphs but never mounts the overlay. Suppressed
+    // while an overlay owns the screen — the rail stops narrating over
+    // dialogs.
+    let card = null;
+    if (hoverEnabled && cardIndex !== null) {
+        const turn = turns[cardIndex];
+        if (turn && turn.preview.length > 0) {
+            const tickRow = geo.tickTop + cardIndex - geo.windowStart;
+            if (tickRow >= geo.tickTop && tickRow < geo.downRow) {
+                const budget = Math.min(32, Math.max(16, Math.floor((terminalWidth - RAIL_WIDTH) / 2)));
+                const lines = wrapPreviewLines(turn.preview, budget);
+                if (lines.length > 0 && lines.some(l => l.length > 0)) {
+                    const widest = Math.max(...lines.map(l => stringWidth(l)));
+                    const cardW = widest + 4; // rounded border ×2 + padding ×2
+                    const cardH = lines.length + 2;
+                    if (cardH <= viewport) {
+                        const top = Math.max(0, Math.min(tickRow - Math.floor(cardH / 2), viewport - cardH));
+                        card = (_jsx(Box, { position: "absolute", top: top, right: RAIL_WIDTH + 1, width: cardW, height: cardH, flexDirection: "column", flexShrink: 0, borderStyle: "round", borderColor: "inactive", paddingX: 1, 
+                            // The card floats LEFT of the rail over selectable
+                            // transcript text; fence its own rect so a drag that
+                            // happens under a dwell-popped preview never copies the
+                            // card's preview glyphs. On the box itself (not a NoSelect
+                            // wrapper): absolute children don't contribute to a flow
+                            // wrapper's layout, so a wrapper's region would be 0×0.
+                            noSelect: true, children: lines.map((line, i) => (_jsx(Text, { color: "text", wrap: "truncate-end", children: line }, i))) }));
+                    }
+                }
+            }
+        }
+    }
+    return (_jsx(NoSelect, { children: _jsxs("ink-box", { onWheel: e => {
+                if (e.deltaY !== 0)
+                    handle.scrollBy(e.deltaY);
+            }, style: { flexDirection: 'column', flexShrink: 0, width: RAIL_WIDTH }, children: [_jsx(Box, { height: geo.upRow, flexShrink: 0 }), chevron('up'), tickRows, chevron('down'), card] }) }));
+}

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

@@ -0,0 +1,14 @@
+import React from 'react';
+/**
+ * `/tips` usage-tips panel (inline-pane form like the local pickers and the
+ * /btw panel): grouped one-line tips on shortcuts, commands, workflow,
+ * display, and gotchas. Owns the keyboard while open — every key it sees is
+ * consumed here.
+ *
+ * The panel is a static list (no paging): the ScrollBox keeps it bounded,
+ * and tips are intentionally one-liners so the whole pool stays scannable.
+ */
+export declare function TipsPanel({ onClose }: {
+    onClose: () => void;
+}): React.ReactNode;
+//# sourceMappingURL=TipsPanel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TipsPanel.d.ts","sourceRoot":"","sources":["../../../src/components/TipsPanel.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAQzB;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,EAAE,OAAO,EAAE,EAAE;IAAE,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,GAAG,KAAK,CAAC,SAAS,CAkD/E"}

package/lib/types/components/TipsPanel.js

@@ -0,0 +1,37 @@
+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 { getLang, t } from '../i18n.js';
+import { isPlainReturnInput } from '../utils/modifiers.js';
+import { TIPS, TIP_GROUP_LABELS } from '../tips.js';
+const GROUP_ORDER = ['keys', 'commands', 'workflow', 'display', 'pitfalls'];
+/**
+ * `/tips` usage-tips panel (inline-pane form like the local pickers and the
+ * /btw panel): grouped one-line tips on shortcuts, commands, workflow,
+ * display, and gotchas. Owns the keyboard while open — every key it sees is
+ * consumed here.
+ *
+ * The panel is a static list (no paging): the ScrollBox keeps it bounded,
+ * and tips are intentionally one-liners so the whole pool stays scannable.
+ */
+export function TipsPanel({ onClose }) {
+    const scrollRef = React.useRef(null);
+    const { rows } = useTerminalSize();
+    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;
+        }
+        // The panel owns the keyboard while open: swallow everything else so
+        // nothing leaks into the prompt input behind it.
+        event.stopImmediatePropagation();
+    });
+    const lang = getLang();
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { children: [_jsx(Text, { color: "warning", bold: true, children: "/tips " }), _jsx(Text, { dimColor: true, children: t('tips-title') })] }), _jsx(Box, { flexDirection: "column", maxHeight: Math.max(5, rows - 8), children: _jsx(Box, { marginLeft: 2, flexDirection: "column", flexGrow: 1, children: _jsx(ScrollBox, { ref: scrollRef, flexDirection: "column", flexGrow: 1, children: GROUP_ORDER.map(group => (_jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [_jsx(Text, { bold: true, color: "accent", children: lang === 'zh' ? TIP_GROUP_LABELS[group].zh : TIP_GROUP_LABELS[group].en }), TIPS.filter(tip => tip.group === group).map(tip => (_jsxs(Text, { dimColor: true, children: ['  · ', lang === 'zh' ? tip.zh : tip.en] }, tip.id)))] }, group))) }) }) }), _jsx(Text, { dimColor: true, children: t('tips-hint') })] }));
+}

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

@@ -0,0 +1,18 @@
+import React from 'react';
+type Props = {
+    isError: boolean;
+    isUnresolved: boolean;
+    shouldAnimate: boolean;
+    /** Raw tool id (bash/read/edit/…) — picks the category color for a settled dot. */
+    toolName?: string;
+};
+/**
+ * The status dot on tool-call rows. State shapes the glyph, the tool
+ * category picks the settled color: blinking `●` while running (attention),
+ * a smaller category-colored `•` once settled (quiet), and a red `✗` on
+ * error — a glyph swap, not just a hue, so failures read at a glance
+ * (Codex-style category colors; every color is a theme token).
+ */
+export declare function ToolUseLoader({ isError, isUnresolved, shouldAnimate, toolName, }: Props): React.ReactNode;
+export {};
+//# sourceMappingURL=ToolUseLoader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ToolUseLoader.d.ts","sourceRoot":"","sources":["../../../src/components/ToolUseLoader.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAOzB,KAAK,KAAK,GAAG;IACX,OAAO,EAAE,OAAO,CAAA;IAChB,YAAY,EAAE,OAAO,CAAA;IACrB,aAAa,EAAE,OAAO,CAAA;IACtB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAmCD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,EAC5B,OAAO,EACP,YAAY,EACZ,aAAa,EACb,QAAQ,GACT,EAAE,KAAK,GAAG,KAAK,CAAC,SAAS,CAoBzB"}

package/lib/types/components/ToolUseLoader.js

@@ -0,0 +1,51 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import Box from '../ink/components/Box.js';
+import { Text } from '../ui.js';
+import { useBlink } from '../hooks/useBlink.js';
+import { BLACK_CIRCLE, BULLET, MULTIPLICATION_X } from '../terminal-utils/figures.js';
+const CATEGORY_BY_TOOL = {
+    bash: 'exec',
+    powershell: 'exec',
+    pwsh: 'exec',
+    read: 'read',
+    grep: 'read',
+    glob: 'read',
+    search: 'read',
+    file_search: 'read',
+    edit: 'write',
+    write: 'write',
+    str_replace_editor: 'write',
+    multiedit: 'write',
+    web_search: 'web',
+    web_fetch: 'web',
+    browser: 'web',
+    subagent: 'task',
+    task: 'task',
+    job: 'task',
+    workflow: 'task',
+};
+const CATEGORY_TOKEN = {
+    exec: 'toolDotExec',
+    read: 'toolDotRead',
+    write: 'toolDotWrite',
+    web: 'toolDotWeb',
+    task: 'toolDotTask',
+    default: 'success',
+};
+/**
+ * The status dot on tool-call rows. State shapes the glyph, the tool
+ * category picks the settled color: blinking `●` while running (attention),
+ * a smaller category-colored `•` once settled (quiet), and a red `✗` on
+ * error — a glyph swap, not just a hue, so failures read at a glance
+ * (Codex-style category colors; every color is a theme token).
+ */
+export function ToolUseLoader({ isError, isUnresolved, shouldAnimate, toolName, }) {
+    const [ref, isBlinking] = useBlink(shouldAnimate);
+    if (isError) {
+        return (_jsx(Box, { ref: ref, minWidth: 2, children: _jsx(Text, { color: "error", children: MULTIPLICATION_X }) }));
+    }
+    const category = CATEGORY_BY_TOOL[toolName ?? ''] ?? 'default';
+    const color = isUnresolved ? undefined : CATEGORY_TOKEN[category];
+    const char = shouldAnimate ? (isBlinking ? BLACK_CIRCLE : ' ') : BULLET;
+    return (_jsx(Box, { ref: ref, minWidth: 2, children: _jsx(Text, { color: color, dimColor: isUnresolved, children: char }) }));
+}

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

@@ -0,0 +1,67 @@
+import React from 'react';
+import type { PointerEvent } from '../ink/events/pointer-event.js';
+/** Tooltip content: a fixed string or a getter resolved at show time. */
+export type TooltipContent = string | (() => string);
+export type TooltipOptions = {
+    /** Dwell before the tooltip appears. Default 600ms. */
+    delayMs?: number;
+};
+/** Hover props returned by {@link useTooltip}; spread onto a Box. */
+export type TooltipHoverProps = {
+    onMouseEnter: (event?: PointerEvent) => void;
+    onMouseLeave: () => void;
+};
+/**
+ * Per-attachment owner: identifies which element's timer is pending and
+ * which element owns the shown tooltip (so one element's leave can never
+ * hide another's tooltip).
+ */
+type TooltipOwner = {
+    timer: ReturnType<typeof setTimeout> | null;
+};
+type TooltipState = {
+    owner: TooltipOwner;
+    anchorCol: number;
+    anchorRow: number;
+    content: string;
+};
+/** Subscribe to tooltip show/hide; returns an unsubscribe function. */
+export declare function subscribeTooltip(listener: () => void): () => void;
+/** Stable snapshot for useSyncExternalStore (identity kept until changed). */
+export declare function getTooltipSnapshot(): TooltipState | null;
+/** Hide shown content and invalidate every pending dwell timer. */
+export declare function clearTooltip(): void;
+/**
+ * Hover props that pop a tooltip with the full content after a dwell.
+ *
+ * The pointer position (screen col/row) is taken from the PointerEvent the
+ * renderer hands to `onMouseEnter` — the runtime always passes one even
+ * though the prop type is `() => void`, which is why the handler's parameter
+ * is optional (a `() => void` prop accepts a function with only optional
+ * parameters).
+ */
+export declare function useTooltip(content: TooltipContent, opts?: TooltipOptions): TooltipHoverProps;
+/**
+ * Convenience wrapper for list rows built from data (a component boundary
+ * makes the hook call legal per item). Renders a plain Box carrying the
+ * hover props around `children`.
+ */
+export declare function TooltipTarget({ content, children, }: {
+    content: TooltipContent;
+    children: React.ReactNode;
+}): React.ReactNode;
+/**
+ * The singleton floating layer: subscribes to the tooltip store and renders
+ * the rounded card above the anchor row (below it when there is no room),
+ * horizontally clamped inside the terminal. Mount once, LAST in the tree so
+ * it paints over everything else. Terminal resize hides the tooltip — its
+ * anchor is screen geometry that just went stale.
+ */
+export declare function TooltipLayer({ invalidationKey, subscribeInvalidation, }?: {
+    /** Changes when a modal/screen geometry transition makes the anchor stale. */
+    invalidationKey?: unknown;
+    /** Scroll/viewport subscription; every notification invalidates the anchor. */
+    subscribeInvalidation?: (listener: () => void) => () => void;
+}): React.ReactNode;
+export {};
+//# sourceMappingURL=Tooltip.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Tooltip.d.ts","sourceRoot":"","sources":["../../../src/components/Tooltip.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AASzB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAA;AA0BlE,yEAAyE;AACzE,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAA;AAEpD,MAAM,MAAM,cAAc,GAAG;IAC3B,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,qEAAqE;AACrE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,YAAY,EAAE,CAAC,KAAK,CAAC,EAAE,YAAY,KAAK,IAAI,CAAA;IAC5C,YAAY,EAAE,MAAM,IAAI,CAAA;CACzB,CAAA;AAED;;;;GAIG;AACH,KAAK,YAAY,GAAG;IAAE,KAAK,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,IAAI,CAAA;CAAE,CAAA;AAEnE,KAAK,YAAY,GAAG;IAClB,KAAK,EAAE,YAAY,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAYD,uEAAuE;AACvE,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAKjE;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,IAAI,YAAY,GAAG,IAAI,CAExD;AAcD,mEAAmE;AACnE,wBAAgB,YAAY,IAAI,IAAI,CAMnC;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,iBAAiB,CAuC5F;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,EAC5B,OAAO,EACP,QAAQ,GACT,EAAE;IACD,OAAO,EAAE,cAAc,CAAA;IACvB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAC1B,GAAG,KAAK,CAAC,SAAS,CAGlB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,EAC3B,eAAe,EACf,qBAAqB,GACtB,GAAE;IACD,8EAA8E;IAC9E,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,+EAA+E;IAC/E,qBAAqB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAA;CACxD,GAAG,KAAK,CAAC,SAAS,CA8GvB"}