@itookit/dsht 0.5.1 → 0.6.0

package/dist/ui/chat/use-history-view.d.ts

@@ -0,0 +1,69 @@
+/** Reading position, folds and asynchronous navigation belong to this mounted conversation view. */
+import { type SetStateAction } from 'react';
+import type { Reasoning, SessionRender, ShellBlock } from '../../contracts.ts';
+interface HistorySource {
+    readonly version: number;
+    readonly memoryRevision: number;
+    readonly beforeSeq: number | undefined;
+    readonly ready: boolean;
+    readonly hasMore: boolean;
+    readonly liveAttemptKey: string | undefined;
+}
+interface HistoryViewOptions<S extends HistorySource> {
+    sessionId?: string;
+    source: S;
+    display: S;
+    detached: boolean;
+    width: number;
+    rows: number;
+    showHint: boolean;
+    protect: boolean;
+    enabled: boolean;
+    online: boolean;
+    busy: boolean;
+    revision: number;
+    blocks: readonly ShellBlock[];
+    current(source: S): boolean;
+    render(input: {
+        transcript: S;
+        width: number;
+        folds: ReadonlySet<number>;
+        liveReasoning: Reasoning;
+    }): SessionRender;
+    run<T>(work: (signal: AbortSignal) => Promise<T>, label: string): Promise<T | undefined>;
+    older(signal: AbortSignal, source: S): Promise<boolean>;
+    open(target: number, signal: AbortSignal): Promise<boolean>;
+    pin(value: boolean): void;
+    closePanels(): void;
+    notify(message: string): void;
+}
+export declare function useHistoryView<S extends HistorySource>(options: HistoryViewOptions<S>): {
+    layout: {
+        messages: import("../../contracts.ts").Message[];
+        offsets: Map<number, number>;
+        first: number | undefined;
+        length: number;
+        liveOffset: number;
+        viewport: (start: number, end: number) => import("../../contracts.ts").HistoryRow[];
+        readonly cachedRowCount: number;
+        readonly lines: string[];
+    };
+    merged: {
+        total: number;
+        hostRow(row: number): number;
+        sources: ReadonlyMap<number, string>;
+        viewport(start: number, end: number): import("../../contracts.ts").HistoryRow[];
+    };
+    totalRows: number;
+    pageSize: number;
+    position: number;
+    reasoningOverrides: ReadonlySet<number>;
+    liveReasoning: Reasoning;
+    setScroll: (value: SetStateAction<number>) => void;
+    setReasoningOverrides: (value: SetStateAction<ReadonlySet<number>>) => void;
+    setLiveReasoning: (value: SetStateAction<Reasoning>) => void;
+    scrollHistory: (delta: number) => void;
+    jumpHistory: (target: number) => Promise<void>;
+    historyOperation: <T>(work: (signal: AbortSignal) => Promise<T>, label?: string) => Promise<T | undefined>;
+};
+export {};

package/dist/ui/chat/use-history-view.js

@@ -0,0 +1,123 @@
+/** Reading position, folds and asynchronous navigation belong to this mounted conversation view. */
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { errorText } from "../../text.js";
+import { mergeShellRuns } from "./shell-view.js";
+export function useHistoryView(options) {
+    const [scroll, setScroll] = useState(0);
+    const [folds, setFolds] = useState(new Set());
+    const [liveReasoning, setLive] = useState('row');
+    const [anchor, setAnchor] = useState();
+    const latest = useRef(options);
+    latest.current = options;
+    const mounted = useRef(true);
+    const intent = useRef(0);
+    const jumpAbort = useRef(undefined);
+    const pageAbort = useRef(undefined);
+    const lifetime = useRef(new AbortController());
+    const paging = useRef(false);
+    const invalidate = () => { intent.current++; jumpAbort.current?.abort(); setAnchor(undefined); };
+    useEffect(() => {
+        if (lifetime.current.signal.aborted)
+            lifetime.current = new AbortController();
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+            intent.current++;
+            lifetime.current.abort();
+            jumpAbort.current?.abort();
+            pageAbort.current?.abort();
+            latest.current.pin(false);
+        };
+    }, []);
+    useEffect(() => {
+        invalidate();
+        pageAbort.current?.abort();
+        setScroll(0);
+    }, [options.source]);
+    useEffect(() => { setFolds(new Set()); setLive('row'); }, [options.sessionId]);
+    useEffect(() => { setLive('row'); }, [options.source, options.source.liveAttemptKey]);
+    useEffect(() => {
+        const first = options.display.beforeSeq;
+        if (first !== undefined)
+            setFolds(previous => {
+                const next = new Set([...previous].filter(seq => seq >= first));
+                return next.size === previous.size ? previous : next;
+            });
+    }, [options.display, options.display.memoryRevision]);
+    const { source, display, width } = options;
+    const layout = useMemo(() => options.render({ transcript: display, width, folds, liveReasoning }), [display, display.version, width, folds, liveReasoning]);
+    const merged = useMemo(() => mergeShellRuns(layout, options.blocks, width), [layout, options.blocks, options.revision, width]);
+    const pageSize = Math.max(1, options.rows - (options.showHint ? 1 : 0));
+    const totalRows = merged.total;
+    const maxScroll = Math.max(0, totalRows - pageSize);
+    const previousView = useRef({ source, display, count: totalRows, first: layout.first, folds, liveReasoning });
+    const previous = previousView.current;
+    const prepended = previous.first !== undefined && layout.first !== undefined && layout.first < previous.first;
+    const adjusted = previous.source !== source ? 0
+        : scroll > 0 && previous.display === display && !prepended && previous.folds === folds && previous.liveReasoning === liveReasoning
+            ? Math.max(0, scroll + totalRows - previous.count) : scroll;
+    const row = anchor?.source === source ? layout.offsets.get(anchor.target) : undefined;
+    const position = Math.max(0, Math.min(row === undefined ? adjusted : totalRows - pageSize - merged.hostRow(row), maxScroll));
+    useLayoutEffect(() => {
+        previousView.current = { source, display, count: totalRows, first: layout.first, folds, liveReasoning };
+        if (position !== scroll)
+            setScroll(position);
+        if (anchor)
+            setAnchor(undefined);
+    }, [source, display, totalRows, position, scroll, folds, liveReasoning, anchor]);
+    useLayoutEffect(() => { options.pin(!options.detached && (position > 0 || options.protect)); }, [options.detached, position, options.protect, source]);
+    function scrollTo(value) { invalidate(); setScroll(value); }
+    function setReasoningOverrides(value) { invalidate(); setFolds(value); }
+    function setLiveReasoning(value) { invalidate(); setLive(value); }
+    function historyOperation(work, label = 'Loading history…') {
+        return options.run(signal => work(AbortSignal.any([signal, lifetime.current.signal])), label);
+    }
+    function scrollHistory(delta) {
+        if (!options.enabled)
+            return;
+        invalidate();
+        const own = intent.current;
+        const next = Math.max(0, Math.min(maxScroll, position + delta));
+        setScroll(next);
+        if (delta <= 0 || next < maxScroll || paging.current || options.busy || !options.online || !display.ready || !display.hasMore)
+            return;
+        paging.current = true;
+        const abort = new AbortController();
+        pageAbort.current = abort;
+        void historyOperation(signal => options.older(AbortSignal.any([signal, abort.signal]), display)).then(accepted => {
+            if (accepted && mounted.current && latest.current.display === display && options.current(source) && intent.current === own) {
+                setScroll(position + delta);
+            }
+        }).catch(error => {
+            if (mounted.current && !(error instanceof Error && error.name === 'AbortError'))
+                latest.current.notify(errorText(error));
+        }).finally(() => { paging.current = false; if (pageAbort.current === abort)
+            pageAbort.current = undefined; });
+    }
+    async function jumpHistory(target) {
+        if (!options.enabled)
+            throw new Error('Select a session first');
+        invalidate();
+        const own = intent.current;
+        const abort = new AbortController();
+        jumpAbort.current = abort;
+        try {
+            await historyOperation(async (foreground) => {
+                const signal = AbortSignal.any([foreground, abort.signal]);
+                if (!await options.open(target, signal))
+                    return;
+                signal.throwIfAborted();
+                if (!mounted.current || intent.current !== own || !options.current(source))
+                    return;
+                setAnchor({ source, target });
+                latest.current.closePanels();
+            }, 'Jumping to a message…');
+        }
+        finally {
+            if (jumpAbort.current === abort)
+                jumpAbort.current = undefined;
+        }
+    }
+    return { layout, merged, totalRows, pageSize, position, reasoningOverrides: folds, liveReasoning,
+        setScroll: scrollTo, setReasoningOverrides, setLiveReasoning, scrollHistory, jumpHistory, historyOperation };
+}

package/dist/ui/dialogs/cost.d.ts

@@ -9,6 +9,8 @@ export interface CostLine {
 export interface CostSource {
     session?: CostLine;
     today: CostLine;
+    week: CostLine;
+    month: CostLine;
     scanning: boolean;
     coverage: Coverage;
     scannedAt?: number;
@@ -17,6 +19,10 @@ export interface CostSource {
     missing: readonly string[];
 }
 /** Render cached totals while the independent HTTP cost scan refreshes.
+ *
+ * The three periods are natural Beijing periods counted from their own start through today, not
+ * sliding windows, so "this week" and "this month" match what an invoice would name. They only reach
+ * back as far as the retained ledger does, which is why the panel says how old its cached totals are.
  * @param source - Plain billing summary, absent when this run has no ledger.
  * @returns Billing panel, including unpriced models and refresh errors.
  */

package/dist/ui/dialogs/cost.js

@@ -4,6 +4,10 @@ import { useTheme } from "../theme/index.js";
 import { Box, Text } from 'ink';
 import { safeText } from "../../text.js";
 /** Render cached totals while the independent HTTP cost scan refreshes.
+ *
+ * The three periods are natural Beijing periods counted from their own start through today, not
+ * sliding windows, so "this week" and "this month" match what an invoice would name. They only reach
+ * back as far as the retained ledger does, which is why the panel says how old its cached totals are.
  * @param source - Plain billing summary, absent when this run has no ledger.
  * @returns Billing panel, including unpriced models and refresh errors.
  */
@@ -12,7 +16,7 @@ export function CostPanel({ source }) {
     const costs = source;
     if (!costs)
         return _jsx(Text, { children: "Cost tracking is unavailable" });
-    const rows = [['Session', costs.session], ['Today', costs.today]];
+    const rows = [['Session', costs.session], ['Today', costs.today], ['This week', costs.week], ['This month', costs.month]];
     return _jsxs(Box, { flexDirection: "column", borderStyle: "single", paddingX: 1, children: [_jsx(Text, { bold: true, children: "Cost \u00B7 CNY estimate \u00B7 Asia/Shanghai \u00B7 /cost closes" }), rows.map(([label, total]) => _jsxs(Text, { children: [label, ": ", total ? `${total.text} · ${total.unknown} unpriced / ${total.records} requests` : '?'] }, label)), _jsx(Text, { dimColor: true, children: costs.scanning ? 'Refreshing all visible sessions…'
                     : costs.coverage === 'partial' ? 'Partial totals · awaiting a complete scan'
                         : costs.scannedAt ? `Last refresh: ${new Date(costs.scannedAt).toISOString()}`

package/dist/ui/dialogs/loop.d.ts

@@ -1,4 +1,4 @@
-import type { LoopLimits, LoopRecord } from '../../contracts.ts';
+import type { LoopLimits, LoopRecord, LoopSourceInfo } from '../../contracts.ts';
 /** The numeric fields the form edits, in the order a run reads them. */
 export type LoopField = 'from' | 'to' | 'score' | 'tries';
 /** What the form hands to the runner: the four numbers and the record's variables as confirmed. */
@@ -15,12 +15,13 @@ export declare function loopRecordDefaults(record: LoopRecord): LoopLimits;
  *
  * It offers the same names and defaults the runner reads, so choosing from it cannot start a run
  * other than the one the row describes.
- * @param props - Matching records and the highlighted row.
- * @returns The key line and up to six record rows.
+ * @param props - Matching records, the highlighted row, and where the records came from.
+ * @returns The key line, the source line, any warning, and up to six record rows.
  */
-export declare function LoopMenu({ records, index }: {
+export declare function LoopMenu({ records, index, source }: {
     records: readonly LoopRecord[];
     index: number;
+    source?: LoopSourceInfo;
 }): import("react").JSX.Element;
 /** The loop parameter form: one record's variables and defaults, editable in place, then a Start.
  *

package/dist/ui/dialogs/loop.js

@@ -47,20 +47,28 @@ function labelWidth(rows) {
  *
  * It offers the same names and defaults the runner reads, so choosing from it cannot start a run
  * other than the one the row describes.
- * @param props - Matching records and the highlighted row.
- * @returns The key line and up to six record rows.
+ * @param props - Matching records, the highlighted row, and where the records came from.
+ * @returns The key line, the source line, any warning, and up to six record rows.
  */
-export function LoopMenu({ records, index }) {
+export function LoopMenu({ records, index, source }) {
     const theme = useTheme();
     const start = Math.max(0, index - 5);
-    return _jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: "Loop records \u00B7 \u2191 \u2193 select \u00B7 Enter confirm defaults \u00B7 Tab finish the name \u00B7 Esc close" }), records.slice(start, start + 6).map((record, offset) => {
+    // Records are configuration now: whenever a user file supplied or replaced one, the list says so,
+    // because an operator who overrode a shipped record cannot tell the two apart from the name alone.
+    const origin = source?.file === undefined ? undefined : [
+        `Records from ${source.file}`,
+        ...(source.overridden.length === 0 ? [] : [`replaced: ${source.overridden.join(', ')}`]),
+        ...(source.added.length === 0 ? [] : [`added: ${source.added.join(', ')}`]),
+    ].join(' · ');
+    return _jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: "Loop records \u00B7 \u2191 \u2193 select \u00B7 Enter confirm defaults \u00B7 Tab finish the name \u00B7 Esc close" }), origin !== undefined && _jsx(Text, { dimColor: true, wrap: "truncate-end", children: safeText(origin) }), (source?.warnings ?? []).map(warning => _jsx(Text, { color: theme.colors.error, wrap: "truncate-end", children: safeText(warning) }, warning)), records.slice(start, start + 6).map((record, offset) => {
                 const current = start + offset === index;
                 // The record's own inputs come before the artifact file: they are what the form will edit, and
                 // the first thing a narrow row must not lose.
                 const vars = Object.entries(record.vars).map(([name, value]) => `${name} ${value}`).join(' · ');
                 const target = vars === '' ? '' : ` · ${vars}`;
                 const artifact = record.artifact === undefined ? '' : ` · ${record.artifact}`;
-                return _jsxs(Text, { color: current ? theme.accent : undefined, wrap: "truncate-end", children: [current ? '❯ ' : '  ', record.name, " \u00B7 ", record.title, " \u00B7 ", record.steps, " rounds \u00B7 pass ", record.defaultScore, " \u00B7 \u2264", record.defaultTries, " tries", target, artifact] }, record.name);
+                const mine = record.fromFile === true ? ' · yours' : '';
+                return _jsxs(Text, { color: current ? theme.accent : undefined, wrap: "truncate-end", children: [current ? '❯ ' : '  ', record.name, " \u00B7 ", record.title, " \u00B7 ", record.steps, " rounds \u00B7 pass ", record.defaultScore, " \u00B7 \u2264", record.defaultTries, " tries", target, artifact, mine] }, record.name);
             })] });
 }
 /** The loop parameter form: one record's variables and defaults, editable in place, then a Start.
@@ -207,7 +215,7 @@ export function LoopDialog({ record, enabled, onStart, onBack, onClose }) {
         }
         onStart({ limits: values, vars });
     }, { isActive: !copyMode });
-    return _jsxs(Box, { flexDirection: "column", marginY: 1, children: [_jsxs(Text, { bold: true, children: ["Run loop record \u00B7 ", safeText(record.name), " \u00B7 Esc close"] }), _jsxs(Text, { dimColor: true, wrap: "truncate-end", children: [record.steps, " rounds", record.artifact === undefined ? '' : ` · ${safeText(record.artifact)}`, " \u00B7 \u2191 \u2193 to a row, then type"] }), rows.map((item, index) => {
+    return _jsxs(Box, { flexDirection: "column", marginY: 1, children: [_jsxs(Text, { bold: true, children: ["Run loop record \u00B7 ", safeText(record.name), record.fromFile === true ? ' · your file' : '', " \u00B7 Esc close"] }), _jsxs(Text, { dimColor: true, wrap: "truncate-end", children: [record.steps, " rounds", record.artifact === undefined ? '' : ` · ${safeText(record.artifact)}`, " \u00B7 \u2191 \u2193 to a row, then type"] }), rows.map((item, index) => {
                 const selected = index === row;
                 const cursor = selected ? '❯ ' : '  ';
                 if (item.kind === 'start' || item.kind === 'back')

package/dist/ui/dialogs/use-panels.d.ts

@@ -0,0 +1,53 @@
+/** UI-owned dialog state and the keyboard traits shared by routing and rendering. */
+import { type SetStateAction } from 'react';
+import type { HistoryPanel, ModelState, PanelName, RemovalTarget, SearchPanel } from '../../contracts.ts';
+type SurfaceName = PanelName | 'peek';
+interface PanelState {
+    thoughts: boolean;
+    queue: boolean;
+    prompts: boolean;
+    help: boolean;
+    cost: boolean;
+    status: boolean;
+    model?: ModelState;
+    history?: HistoryPanel;
+    search?: SearchPanel;
+    removal?: RemovalTarget;
+    loop?: {
+        name: string;
+    };
+}
+interface Surface {
+    name: SurfaceName;
+    open: boolean;
+    arrows?: boolean;
+    blocksKeys?: boolean;
+    reserved?: readonly string[];
+}
+/** The externally owned peek view participates in routing without duplicating its state. */
+export declare function usePanels(options: {
+    sessionId: string | undefined;
+    pendingId: string | undefined;
+    peekOpen: boolean;
+    closePeek(): void;
+}): {
+    state: PanelState;
+    openSurfaces: Surface[];
+    close: (name: SurfaceName) => void;
+    closeExcept: (keep?: SurfaceName) => void;
+    reservedKeys: string[];
+    openThoughts: (value: SetStateAction<boolean>) => void;
+    openQueue: (value: SetStateAction<boolean>) => void;
+    openPrompts: (value: SetStateAction<boolean>) => void;
+    setModelPanel: (value: SetStateAction<ModelState | undefined>) => void;
+    setHistoryPanel: (value: SetStateAction<HistoryPanel | undefined>) => void;
+    setSearchPanel: (value: SetStateAction<SearchPanel | undefined>) => void;
+    setRemoval: (value: SetStateAction<RemovalTarget | undefined>) => void;
+    setLoopForm: (value: SetStateAction<{
+        name: string;
+    } | undefined>) => void;
+    setHelp: (value: SetStateAction<boolean>) => void;
+    setCostExpanded: (value: SetStateAction<boolean>) => void;
+    setStatusExpanded: (value: SetStateAction<boolean>) => void;
+};
+export {};

package/dist/ui/dialogs/use-panels.js

@@ -0,0 +1,51 @@
+/** UI-owned dialog state and the keyboard traits shared by routing and rendering. */
+import { useEffect, useState } from 'react';
+const EMPTY = { thoughts: false, queue: false, prompts: false, help: false, cost: false, status: false };
+const TRAITS = [
+    { name: 'queue', reserved: ['d'] },
+    { name: 'prompts', arrows: true, blocksKeys: true, reserved: ['d', 'e'] },
+    ...['removal', 'model', 'loop', 'thoughts', 'history', 'search'].map(name => ({ name, arrows: true, blocksKeys: true })),
+    ...['help', 'cost', 'status'].map(name => ({ name, blocksKeys: true })),
+];
+/** The externally owned peek view participates in routing without duplicating its state. */
+export function usePanels(options) {
+    const [state, setState] = useState(EMPTY);
+    const setter = (key) => (value) => {
+        setState(current => {
+            const next = typeof value === 'function' ? value(current[key]) : value;
+            return current[key] === next ? current : { ...current, [key]: next };
+        });
+    };
+    useEffect(() => {
+        // Read-only client panels and a chosen removal target survive navigation as before.
+        setState(current => ({ ...EMPTY, help: current.help, cost: current.cost, status: current.status, removal: current.removal }));
+    }, [options.sessionId]);
+    useEffect(() => {
+        setState(current => ({ ...current, queue: false, loop: options.pendingId === undefined ? current.loop : undefined }));
+    }, [options.sessionId, options.pendingId]);
+    const surfaces = [
+        { name: 'peek', open: options.peekOpen, arrows: true, blocksKeys: true },
+        ...TRAITS.map(trait => ({ ...trait, open: trait.name === 'queue' ? state.queue && options.pendingId === undefined
+                : !!state[trait.name] })),
+    ];
+    const openSurfaces = surfaces.filter(surface => surface.open);
+    function close(name) {
+        if (name === 'peek')
+            options.closePeek();
+        else
+            setState(current => ({ ...current, [name]: EMPTY[name] }));
+    }
+    function closeExcept(keep) {
+        if (keep !== 'peek')
+            options.closePeek();
+        setState(current => keep === undefined || keep === 'peek' ? EMPTY : { ...EMPTY, [keep]: current[keep] });
+    }
+    return {
+        state, openSurfaces, close, closeExcept,
+        reservedKeys: [...new Set(openSurfaces.flatMap(surface => surface.reserved ?? []))],
+        openThoughts: setter('thoughts'), openQueue: setter('queue'), openPrompts: setter('prompts'),
+        setModelPanel: setter('model'), setHistoryPanel: setter('history'), setSearchPanel: setter('search'),
+        setRemoval: setter('removal'), setLoopForm: setter('loop'),
+        setHelp: setter('help'), setCostExpanded: setter('cost'), setStatusExpanded: setter('status'),
+    };
+}

package/dist/ui/input/use-composer.d.ts

@@ -0,0 +1,35 @@
+/** A local editor borrows Enter until it is saved or dismissed. */
+export interface ComposerIntent {
+    hint: string;
+    emptyNotice: string;
+    successNotice?: string;
+    commit(text: string): Promise<boolean>;
+}
+/** Identity of a submitted draft, even if a later edit has identical text. */
+export interface DraftReceipt {
+    readonly sessionId: string | undefined;
+    readonly revision: number;
+}
+interface ComposerOptions {
+    sessionId: string | undefined;
+    /** Read at completion too, before React necessarily renders a session change. */
+    currentSession(): string | undefined;
+    resetRecall(): void;
+    messageStarted(): void;
+    notify(message: string): void;
+}
+/** Owns editor state only; command interpretation and keyboard routing stay in App. */
+export declare function useComposer(options: ComposerOptions): {
+    input: string;
+    cursor: number;
+    intent: ComposerIntent | undefined;
+    setInput: (value: string, recalled?: boolean) => void;
+    setCursor: import("react").Dispatch<import("react").SetStateAction<number>>;
+    setIntent: (value: ComposerIntent | undefined) => void;
+    capture: () => DraftReceipt;
+    consume: (receipt: DraftReceipt) => void;
+    recallIfCurrent: (receipt: DraftReceipt, read: () => string) => void;
+    commit: (raw: string) => Promise<boolean>;
+    interactionChanged: (answerPending: boolean, pending: boolean) => void;
+};
+export {};

package/dist/ui/input/use-composer.js

@@ -0,0 +1,109 @@
+/** Session-owned draft, temporary editors and async submission ownership. */
+import { useLayoutEffect, useRef, useState } from 'react';
+import { errorText } from "../../text.js";
+/** Owns editor state only; command interpretation and keyboard routing stay in App. */
+export function useComposer(options) {
+    const [input, setInputValue] = useState('');
+    const [cursor, setCursor] = useState(0);
+    const [intent, publishIntent] = useState();
+    const current = useRef({ sessionId: options.sessionId, revision: 0, input: '', parked: '', intent: undefined });
+    const mounted = useRef(false);
+    const saving = useRef(new WeakSet());
+    function replace(value) {
+        current.current.input = value;
+        current.current.revision += 1;
+        setInputValue(value);
+        setCursor(value.length);
+    }
+    function setIntent(value) {
+        current.current.intent = value;
+        publishIntent(value);
+    }
+    useLayoutEffect(() => {
+        mounted.current = true;
+        return () => { mounted.current = false; };
+    }, []);
+    useLayoutEffect(() => {
+        if (current.current.sessionId === options.sessionId)
+            return;
+        current.current.sessionId = options.sessionId;
+        current.current.parked = '';
+        setIntent(undefined);
+        replace('');
+    }, [options.sessionId]);
+    function setInput(value, recalled = false) {
+        if (!recalled)
+            options.resetRecall();
+        if (current.current.input === '' && value !== '' && !value.startsWith('/'))
+            options.messageStarted();
+        replace(value);
+    }
+    function capture() {
+        return { sessionId: current.current.sessionId, revision: current.current.revision };
+    }
+    function owns(receipt) {
+        return mounted.current && receipt.sessionId === options.currentSession()
+            && receipt.sessionId === current.current.sessionId && receipt.revision === current.current.revision;
+    }
+    function consume(receipt) {
+        if (owns(receipt))
+            setInput('');
+    }
+    /** A slow recall must neither replace newer typing nor move its recall cursor. */
+    function recallIfCurrent(receipt, read) {
+        if (owns(receipt))
+            setInput(read(), true);
+    }
+    /** Returns true whenever an editor handled Enter, including an already pending save. */
+    async function commit(raw) {
+        const editor = current.current.intent;
+        if (!editor)
+            return false;
+        if (saving.current.has(editor))
+            return true;
+        const text = raw.trim();
+        if (!text) {
+            options.notify(editor.emptyNotice);
+            return true;
+        }
+        const receipt = capture();
+        const active = () => mounted.current && current.current.intent === editor
+            && receipt.sessionId === options.currentSession() && receipt.sessionId === current.current.sessionId;
+        saving.current.add(editor);
+        try {
+            if (await editor.commit(text) && active()) {
+                if (editor.successNotice)
+                    options.notify(editor.successNotice);
+                // Continued typing remains in edit mode for the next explicit save.
+                if (owns(receipt)) {
+                    setIntent(undefined);
+                    consume(receipt);
+                }
+            }
+        }
+        catch (error) {
+            if (active())
+                options.notify(errorText(error));
+        }
+        finally {
+            saving.current.delete(editor);
+        }
+        return true;
+    }
+    /** Parking/restoring is not a recall or a new message, so it does not move the reader. */
+    function interactionChanged(answerPending, pending) {
+        if (answerPending) {
+            setIntent(undefined);
+            if (current.current.input !== '') {
+                current.current.parked = current.current.input;
+                replace('');
+            }
+        }
+        else if (!pending && current.current.parked !== '') {
+            const parked = current.current.parked;
+            current.current.parked = '';
+            replace(parked);
+        }
+    }
+    return { input, cursor, intent, setInput, setCursor, setIntent, capture, consume, recallIfCurrent, commit, interactionChanged };
+}

package/dist/ui/input/use-deferred-lines.d.ts

@@ -0,0 +1,16 @@
+import { type AuthorizeFacts, type DeferReason, type LineCommand } from '../../slash/index.ts';
+interface DeferredFacts extends AuthorizeFacts {
+    sessionId: string | undefined;
+    /** Both the connection baseline and the selected conversation snapshot must be restored. */
+    ready: boolean;
+}
+interface DeferredOptions {
+    facts(): DeferredFacts;
+    run(command: LineCommand): Promise<void>;
+    notify(message: string): void;
+}
+/** Owns FIFO and in-flight state, independent of Controller and the composer's current draft. */
+export declare function useDeferredLines(options: DeferredOptions): {
+    enqueue(command: LineCommand, defer: DeferReason): void;
+};
+export {};

package/dist/ui/input/use-deferred-lines.js

@@ -0,0 +1,54 @@
+/** Commands explicitly accepted by the operator, waiting for their execution policy. */
+import { useEffect, useRef, useState } from 'react';
+import { authorize } from "../../slash/index.js";
+import { errorText } from "../../text.js";
+/** Owns FIFO and in-flight state, independent of Controller and the composer's current draft. */
+export function useDeferredLines(options) {
+    const [lines, setLines] = useState([]);
+    const draining = useRef(false);
+    const mounted = useRef(false);
+    useEffect(() => {
+        mounted.current = true;
+        return () => { mounted.current = false; };
+    }, []);
+    // Re-evaluate on UI publications, including connection/snapshot readiness and a completed run.
+    // A synchronous reservation prevents a re-render or StrictMode replay from starting it twice.
+    useEffect(() => {
+        const next = lines[0];
+        if (!next || draining.current)
+            return;
+        const facts = options.facts();
+        if (next.sessionId !== facts.sessionId) {
+            setLines(current => current.filter(line => line.sessionId === facts.sessionId));
+            options.notify('Dropped a queued line: the selected session changed');
+            return;
+        }
+        if (!facts.ready || facts.foreground || (next.defer !== 'busy' && facts.during !== 'idle'))
+            return;
+        const verdict = authorize(next.command, facts);
+        if (verdict.allow && verdict.defer !== undefined)
+            return;
+        draining.current = true;
+        setLines(current => current.slice(1));
+        void (async () => {
+            try {
+                await options.run(verdict.allow ? verdict.command : verdict.error);
+            }
+            catch (error) {
+                if (mounted.current)
+                    options.notify(errorText(error));
+            }
+            finally {
+                draining.current = false;
+                if (mounted.current)
+                    setLines(current => [...current]);
+            }
+        })();
+    });
+    return {
+        enqueue(command, defer) {
+            const sessionId = options.facts().sessionId;
+            setLines(current => [...current, { command, defer, sessionId }]);
+        },
+    };
+}

package/dist/ui/input/use-history-recall.d.ts

@@ -0,0 +1,20 @@
+import type { DraftReceipt } from './use-composer.ts';
+interface RecallSource {
+    readonly hasMore: boolean;
+    readonly beforeSeq: number | undefined;
+}
+interface RecallOptions<Source extends RecallSource> {
+    source: Source;
+    draft: string;
+    capture(): DraftReceipt;
+    restore(receipt: DraftReceipt, read: () => string): void;
+    previous(draft: string): string;
+    refill(): boolean;
+    hasPrevious(): boolean;
+    older(signal: AbortSignal, source: Source): Promise<boolean>;
+    run(work: (signal: AbortSignal) => Promise<boolean>): Promise<boolean | undefined>;
+    notify(message: string): void;
+}
+/** No Controller or Transcript dependency: only the paging and recall capabilities it needs. */
+export declare function useHistoryRecall<Source extends RecallSource>(options: RecallOptions<Source>): () => Promise<void>;
+export {};