@itookit/dsht 0.5.1 → 0.5.2

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/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 {};

package/dist/ui/input/use-history-recall.js

@@ -0,0 +1,47 @@
+/** Lazy prompt recall owns its scan; the composer decides whether the result still belongs to it. */
+import { useRef } from 'react';
+import { errorText } from "../../text.js";
+/** Bound one key press even when many tool-only pages separate user messages. */
+const PAGE_SCAN_LIMIT = 20;
+/** No Controller or Transcript dependency: only the paging and recall capabilities it needs. */
+export function useHistoryRecall(options) {
+    const loading = useRef(false);
+    return async () => {
+        if (loading.current)
+            return;
+        const receipt = options.capture();
+        const { source, draft } = options;
+        const restore = () => options.restore(receipt, () => options.previous(draft));
+        if (options.refill() || options.hasPrevious() || !source.hasMore) {
+            restore();
+            return;
+        }
+        loading.current = true;
+        try {
+            const found = await options.run(async (signal) => {
+                for (let page = 0; page < PAGE_SCAN_LIMIT; page++) {
+                    signal.throwIfAborted();
+                    if (source.beforeSeq === undefined || !source.hasMore)
+                        break;
+                    if (!await options.older(signal, source))
+                        break;
+                    signal.throwIfAborted();
+                    // Startup backfill may have inserted the same prompts while this page was in flight.
+                    if (options.refill() || options.hasPrevious())
+                        return true;
+                }
+                return false;
+            });
+            if (found)
+                restore();
+        }
+        catch (error) {
+            // Foreground cancellation is an expected end to a user-triggered scan.
+            if (!(error instanceof Error && error.name === 'AbortError'))
+                options.notify(errorText(error));
+        }
+        finally {
+            loading.current = false;
+        }
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itookit/dsht",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "type": "module",
   "description": "Remote-first TUI for DeepSeek Harness with SSH-friendly mobile access and request-level cost tracking",
   "engines": {