@jini-ai/chat 0.1.0

package/dist/react/hooks/useConversation.js

@@ -0,0 +1,163 @@
+/**
+ * @module useConversation
+ *
+ * Owns the message array, an optimistic user-message append, a scroll-intent
+ * flag, and the active conversation id. Reconciles `useRunStream`'s live
+ * `AgentEvent[]` into the streaming assistant message's `events`/`content`
+ * as they arrive, and finalizes it once the run reaches a terminal status.
+ * Per `ADS-memory/reports/jini-port/recon/r4b-webui-design.md` §4.
+ *
+ * Mutations reach the transport only through the composed `useRunStream` —
+ * this hook never imports `fetch`/`EventSource` itself.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { isTerminalRunStatus } from '../../core/index.js';
+import { useRunStream } from './useRunStream.js';
+let fallbackIdCounter = 0;
+function defaultCreateMessageId() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function')
+        return crypto.randomUUID();
+    fallbackIdCounter += 1;
+    return `msg-${Date.now()}-${fallbackIdCounter}`;
+}
+function assistantContentFromEvents(events) {
+    let out = '';
+    for (const ev of events) {
+        if (ev.kind === 'text')
+            out += ev.text;
+    }
+    return out;
+}
+export function useConversation(options) {
+    const { transport, conversationId = null, agentId, createMessageId = defaultCreateMessageId } = options;
+    const [messages, setMessagesState] = useState(options.initialMessages ?? []);
+    const [scrollIntent, setScrollIntent] = useState(false);
+    const run = useRunStream(transport);
+    // The assistant message id the currently-active run is writing into.
+    const activeAssistantIdRef = useRef(null);
+    const messagesRef = useRef(messages);
+    messagesRef.current = messages;
+    const setMessages = useCallback((updater) => {
+        setMessagesState((prev) => (typeof updater === 'function' ? updater(prev) : updater));
+    }, []);
+    const applyRunToAssistantMessage = useCallback(() => {
+        const assistantId = activeAssistantIdRef.current;
+        if (!assistantId)
+            return;
+        setMessagesState((prev) => prev.map((m) => {
+            if (m.id !== assistantId)
+                return m;
+            // A plain if/else chain (not a nested ternary) — deliberately, so
+            // each of the four mapped statuses is its own independently
+            // trackable branch under coverage instrumentation. The initial
+            // value is asserted non-null: this reconciliation effect only ever
+            // runs after `sendMessage`/`retry` has called `run.start()`/
+            // `reattach` (both set the message's `runStatus: 'queued'` via
+            // `activeAssistantIdRef` first), so `m.runStatus` is always defined
+            // and `run.status` is never `'idle'` by the time this callback
+            // fires — one of the four branches below always reassigns it.
+            let runStatus = m.runStatus;
+            if (run.status === 'streaming')
+                runStatus = 'running';
+            else if (run.status === 'done')
+                runStatus = 'succeeded';
+            else if (run.status === 'error')
+                runStatus = 'failed';
+            else if (run.status === 'canceled')
+                runStatus = 'canceled';
+            const nextRunId = run.runId ?? m.runId;
+            return {
+                ...m,
+                ...(nextRunId !== undefined ? { runId: nextRunId } : {}),
+                events: run.events,
+                content: assistantContentFromEvents(run.events),
+                runStatus,
+                ...(isTerminalRunStatus(runStatus) ? { endedAt: Date.now() } : {}),
+            };
+        }));
+        setScrollIntent(true);
+    }, [run.events, run.runId, run.status]);
+    // Reconcile the live run's events onto the streaming assistant message
+    // whenever any of them changes identity. `run.runId` must be included:
+    // an event can arrive (and get reconciled) before `start()`'s promise
+    // resolves with the real id, and if the id then resolves with no further
+    // event/status change, omitting it here would leave the message's runId
+    // permanently unset.
+    useEffect(() => {
+        applyRunToAssistantMessage();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [run.events, run.status, run.runId]);
+    const sendMessage = useCallback(async (content, sendOptions = {}) => {
+        const userMessage = {
+            id: createMessageId(),
+            role: 'user',
+            content,
+            createdAt: Date.now(),
+            ...(sendOptions.attachments ? { attachments: sendOptions.attachments } : {}),
+        };
+        const resolvedAgentId = sendOptions.agentId ?? agentId;
+        const assistantMessage = {
+            id: createMessageId(),
+            role: 'assistant',
+            content: '',
+            ...(resolvedAgentId !== undefined ? { agentId: resolvedAgentId } : {}),
+            runStatus: 'queued',
+            createdAt: Date.now(),
+            startedAt: Date.now(),
+        };
+        activeAssistantIdRef.current = assistantMessage.id;
+        const history = [...messagesRef.current, userMessage];
+        setMessagesState([...history, assistantMessage]);
+        setScrollIntent(true);
+        await run.start({
+            history,
+            ...(resolvedAgentId !== undefined ? { agentId: resolvedAgentId } : {}),
+            conversationId,
+            ...(sendOptions.attachments !== undefined ? { attachments: sendOptions.attachments } : {}),
+            ...(sendOptions.context !== undefined ? { context: sendOptions.context } : {}),
+        });
+    }, [agentId, conversationId, createMessageId, run]);
+    const retry = useCallback(async (assistantMessageId) => {
+        const idx = messagesRef.current.findIndex((m) => m.id === assistantMessageId);
+        if (idx <= 0)
+            return;
+        const priorUser = messagesRef.current[idx - 1];
+        if (!priorUser || priorUser.role !== 'user')
+            return;
+        const history = messagesRef.current.slice(0, idx);
+        const resetAssistant = { ...messagesRef.current[idx], content: '', events: [], runStatus: 'queued' };
+        activeAssistantIdRef.current = resetAssistant.id;
+        setMessagesState([...history, resetAssistant]);
+        setScrollIntent(true);
+        const resolvedAgentId = resetAssistant.agentId ?? agentId;
+        // `priorUser`'s attachments go back out with the retry. They were located above and then
+        // dropped: `sendMessage` forwards `attachments` to `run.start`, this path did not, so
+        // retrying an image or file prompt re-sent the TEXT alone. The model then answered a question
+        // about a picture it could no longer see — and because the transcript still renders the
+        // attachment beside the user turn, the failure reads as the model ignoring it rather than as
+        // the client never having sent it.
+        await run.start({
+            history,
+            ...(resolvedAgentId !== undefined ? { agentId: resolvedAgentId } : {}),
+            conversationId,
+            ...(priorUser.attachments !== undefined ? { attachments: priorUser.attachments } : {}),
+        });
+    }, [agentId, conversationId, run]);
+    const cancel = useCallback(() => run.cancel(), [run]);
+    const acknowledgeScroll = useCallback(() => setScrollIntent(false), []);
+    const suppressScroll = useCallback(() => setScrollIntent(false), []);
+    return useMemo(() => ({
+        messages,
+        conversationId,
+        isStreaming: run.isStreaming,
+        error: run.error,
+        scrollIntent,
+        sendMessage,
+        cancel,
+        retry,
+        setMessages,
+        acknowledgeScroll,
+        suppressScroll,
+    }), [messages, conversationId, run.isStreaming, run.error, scrollIntent, sendMessage, cancel, retry, setMessages, acknowledgeScroll, suppressScroll]);
+}
+//# sourceMappingURL=useConversation.js.map

package/dist/react/hooks/useConversation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useConversation.js","sourceRoot":"","sources":["../../../src/react/hooks/useConversation.ts"],"names":[],"mappings":"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"}

package/dist/react/hooks/useCopyToClipboard.d.ts

@@ -0,0 +1,14 @@
+export interface UseCopyToClipboardResult {
+    /** `true` for `COPIED_RESET_MS` after a successful `copy()` call, then reverts to `false` on its own. */
+    copied: boolean;
+    /** Copies `text` verbatim. Resolves to whether the copy actually succeeded. */
+    copy: (text: string) => Promise<boolean>;
+}
+/**
+ * React hook wrapping the copy-to-clipboard logic above with the transient
+ * `copied` UI flag callers use to drive an icon swap or status announcement.
+ * @returns The current `copied` flag and a `copy` function to invoke it.
+ * @complexity O(1) per `copy()` call (excluding the clipboard API's own cost).
+ */
+export declare function useCopyToClipboard(): UseCopyToClipboardResult;
+//# sourceMappingURL=useCopyToClipboard.d.ts.map

package/dist/react/hooks/useCopyToClipboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCopyToClipboard.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/useCopyToClipboard.ts"],"names":[],"mappings":"AA8DA,MAAM,WAAW,wBAAwB;IACvC,yGAAyG;IACzG,MAAM,EAAE,OAAO,CAAC;IAChB,+EAA+E;IAC/E,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1C;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,wBAAwB,CA8B7D"}

package/dist/react/hooks/useCopyToClipboard.js

@@ -0,0 +1,98 @@
+/**
+ * @module useCopyToClipboard
+ *
+ * Copies a string to the system clipboard and exposes a transient `copied`
+ * flag a UI affordance can key off of (icon swap, status text, ...). This is
+ * the shared primitive behind the per-message copy button in `MessageRow.tsx`
+ * -- kept here, not inlined there, so the per-block copy button
+ * `Markdown.tsx` still has as a TODO can reuse the same copy/fallback logic
+ * once it's built, without duplicating the secure-context handling below.
+ *
+ * Two copy paths, tried in order:
+ * 1. `navigator.clipboard.writeText` -- the modern async Clipboard API.
+ *    Requires a secure context (HTTPS, or `localhost`); rejects everywhere
+ *    else, and can also reject in a secure context that denies clipboard
+ *    permission.
+ * 2. A hidden, focused, selected `<textarea>` + `document.execCommand('copy')`
+ *    -- deprecated, but still the only synchronous copy path browsers expose
+ *    outside a secure context. This package ships to hosts beyond localhost,
+ *    so the secure-context requirement above can't be assumed.
+ *
+ * Both paths report their own success back to the caller (rather than being
+ * assumed to have worked) so a caller can decide how to react to a copy that
+ * silently failed instead of showing a false "Copied" state.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+/** How long the `copied` flag stays true after a successful copy before it reverts on its own. */
+const COPIED_RESET_MS = 1500;
+/**
+ * Synchronous fallback copy path for non-secure contexts: a hidden textarea
+ * gets the text, is selected, and `execCommand('copy')` is invoked against
+ * that selection. Returns whether the browser reports the command as
+ * executed -- `execCommand` itself throws in some embedding contexts (e.g. a
+ * sandboxed iframe without clipboard-write) rather than just returning
+ * `false`, so this also guards with try/catch.
+ * @param text - The exact string to place on the clipboard.
+ * @returns Whether the copy command executed successfully.
+ * @complexity O(1) -- one DOM node created, selected, and removed.
+ */
+function copyViaExecCommand(text) {
+    if (typeof document === 'undefined')
+        return false;
+    const textarea = document.createElement('textarea');
+    textarea.value = text;
+    // Off-screen but still focusable/selectable: a `display:none` element can't hold a selection.
+    textarea.style.position = 'fixed';
+    textarea.style.top = '-1000px';
+    textarea.style.left = '-1000px';
+    textarea.setAttribute('readonly', '');
+    document.body.appendChild(textarea);
+    textarea.focus();
+    textarea.select();
+    let ok = false;
+    try {
+        ok = document.execCommand('copy');
+    }
+    catch {
+        ok = false;
+    }
+    document.body.removeChild(textarea);
+    return ok;
+}
+/**
+ * React hook wrapping the copy-to-clipboard logic above with the transient
+ * `copied` UI flag callers use to drive an icon swap or status announcement.
+ * @returns The current `copied` flag and a `copy` function to invoke it.
+ * @complexity O(1) per `copy()` call (excluding the clipboard API's own cost).
+ */
+export function useCopyToClipboard() {
+    const [copied, setCopied] = useState(false);
+    const resetTimer = useRef(undefined);
+    // Clears any pending reset on unmount so a copy just before navigating away never calls
+    // setState on an unmounted component.
+    useEffect(() => () => clearTimeout(resetTimer.current), []);
+    const copy = useCallback(async (text) => {
+        let ok = false;
+        if (typeof navigator !== 'undefined' && navigator.clipboard?.writeText) {
+            try {
+                await navigator.clipboard.writeText(text);
+                ok = true;
+            }
+            catch {
+                // Denied permission, or a non-secure context where the API exists but rejects every call.
+                ok = copyViaExecCommand(text);
+            }
+        }
+        else {
+            ok = copyViaExecCommand(text);
+        }
+        if (ok) {
+            setCopied(true);
+            clearTimeout(resetTimer.current);
+            resetTimer.current = setTimeout(() => setCopied(false), COPIED_RESET_MS);
+        }
+        return ok;
+    }, []);
+    return { copied, copy };
+}
+//# sourceMappingURL=useCopyToClipboard.js.map

package/dist/react/hooks/useCopyToClipboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCopyToClipboard.js","sourceRoot":"","sources":["../../../src/react/hooks/useCopyToClipboard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEjE,kGAAkG;AAClG,MAAM,eAAe,GAAG,IAAI,CAAC;AAE7B;;;;;;;;;;GAUG;AACH,SAAS,kBAAkB,CAAC,IAAY;IACtC,IAAI,OAAO,QAAQ,KAAK,WAAW;QAAE,OAAO,KAAK,CAAC;IAClD,MAAM,QAAQ,GAAG,QAAQ,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;IACpD,QAAQ,CAAC,KAAK,GAAG,IAAI,CAAC;IACtB,8FAA8F;IAC9F,QAAQ,CAAC,KAAK,CAAC,QAAQ,GAAG,OAAO,CAAC;IAClC,QAAQ,CAAC,KAAK,CAAC,GAAG,GAAG,SAAS,CAAC;IAC/B,QAAQ,CAAC,KAAK,CAAC,IAAI,GAAG,SAAS,CAAC;IAChC,QAAQ,CAAC,YAAY,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IACtC,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,CAAC;IACjB,QAAQ,CAAC,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,GAAG,KAAK,CAAC;IACf,IAAI,CAAC;QACH,EAAE,GAAG,QAAQ,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,EAAE,GAAG,KAAK,CAAC;IACb,CAAC;IACD,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IACpC,OAAO,EAAE,CAAC;AACZ,CAAC;AASD;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC5C,MAAM,UAAU,GAAG,MAAM,CAA4C,SAAS,CAAC,CAAC;IAEhF,wFAAwF;IACxF,sCAAsC;IACtC,SAAS,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;IAE5D,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,EAAE,IAAY,EAAoB,EAAE;QAChE,IAAI,EAAE,GAAG,KAAK,CAAC;QACf,IAAI,OAAO,SAAS,KAAK,WAAW,IAAI,SAAS,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC;YACvE,IAAI,CAAC;gBACH,MAAM,SAAS,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;gBAC1C,EAAE,GAAG,IAAI,CAAC;YACZ,CAAC;YAAC,MAAM,CAAC;gBACP,0FAA0F;gBAC1F,EAAE,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;YAChC,CAAC;QACH,CAAC;aAAM,CAAC;YACN,EAAE,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;QAChC,CAAC;QACD,IAAI,EAAE,EAAE,CAAC;YACP,SAAS,CAAC,IAAI,CAAC,CAAC;YAChB,YAAY,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;YACjC,UAAU,CAAC,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC,CAAC;QAC3E,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAC1B,CAAC"}

package/dist/react/hooks/useExtEventGroups.d.ts

@@ -0,0 +1,7 @@
+import type { AgentEvent } from '../../core/index.js';
+export interface ExtEventGroup {
+    name: string;
+    events: unknown[];
+}
+export declare function useExtEventGroups(events: AgentEvent[] | undefined): ExtEventGroup[];
+//# sourceMappingURL=useExtEventGroups.d.ts.map

package/dist/react/hooks/useExtEventGroups.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useExtEventGroups.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/useExtEventGroups.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,EAAE,CAAC;CACnB;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,SAAS,GAAG,aAAa,EAAE,CAgBnF"}

package/dist/react/hooks/useExtEventGroups.js

@@ -0,0 +1,32 @@
+/**
+ * @module useExtEventGroups
+ *
+ * Groups a message's `kind: 'ext'` events by `name`. Groups are ordered by each name's first
+ * occurrence; within a group, events keep arrival order regardless of what's interleaved between
+ * them in the raw stream — `a2ui`, `a2ui`, `foo`, `a2ui` yields `[{name:'a2ui', events:[e1,e2,e3]},
+ * {name:'foo', events:[e2]}]` (indices illustrative), since `ExtEventRenderer` needs the full
+ * ordered sequence for a name, not just a contiguous run of it. Pure over `AgentEvent[]` — zero
+ * I/O, no React state, unlike `useToolTimeline` (which also tracks expand/collapse UI state
+ * ext-event renderers don't need since `MessageRow` doesn't own any generic collapsed/expanded
+ * chrome for them).
+ */
+import { useMemo } from 'react';
+export function useExtEventGroups(events) {
+    return useMemo(() => {
+        const order = [];
+        const byName = new Map();
+        for (const ev of events ?? []) {
+            if (ev.kind !== 'ext')
+                continue;
+            let group = byName.get(ev.name);
+            if (!group) {
+                group = [];
+                byName.set(ev.name, group);
+                order.push(ev.name);
+            }
+            group.push(ev.data);
+        }
+        return order.map((name) => ({ name, events: byName.get(name) }));
+    }, [events]);
+}
+//# sourceMappingURL=useExtEventGroups.js.map

package/dist/react/hooks/useExtEventGroups.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useExtEventGroups.js","sourceRoot":"","sources":["../../../src/react/hooks/useExtEventGroups.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAQhC,MAAM,UAAU,iBAAiB,CAAC,MAAgC;IAChE,OAAO,OAAO,CAAC,GAAG,EAAE;QAClB,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,IAAI,GAAG,EAAqB,CAAC;QAC5C,KAAK,MAAM,EAAE,IAAI,MAAM,IAAI,EAAE,EAAE,CAAC;YAC9B,IAAI,EAAE,CAAC,IAAI,KAAK,KAAK;gBAAE,SAAS;YAChC,IAAI,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;YAChC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,KAAK,GAAG,EAAE,CAAC;gBACX,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;gBAC3B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;YACtB,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;QACD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAE,EAAE,CAAC,CAAC,CAAC;IACpE,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;AACf,CAAC"}

package/dist/react/hooks/useLatestOperation.d.ts

@@ -0,0 +1,31 @@
+export interface OperationToken {
+    /**
+     * Abandons the surrounding {@link LatestOperation.run} body unless this is still the newest
+     * operation on a mounted component. Call it after each await, in place of a guard clause.
+     */
+    ensureCurrent(): void;
+    /** Whether this is still the newest operation and the component is still mounted. */
+    isCurrent(): boolean;
+}
+export interface LatestOperation {
+    /**
+     * Runs `body` as the newest operation, superseding any still in flight.
+     *
+     * `onError` is invoked only for a genuine failure of an operation that is *still* current — a
+     * superseded or unmounted one is discarded silently, which is what the hand-written guards did.
+     */
+    run(body: (token: OperationToken) => Promise<void>, onError: (error: Error) => void): Promise<void>;
+    /** Supersedes whatever is in flight without starting a new operation. */
+    supersede(): void;
+}
+/** Preserves native Error objects while normalizing opaque host-bridge rejections. */
+export declare function normalizeOperationError(error: unknown): Error;
+/**
+ * Owns the mounted flag and the generation counter that decide which async attempt is allowed to
+ * write state. One instance per hook: every operation started through it supersedes the previous
+ * one, so a validation still in flight cannot clobber the result of the pick that replaced it.
+ *
+ * @complexity Time/space: O(1).
+ */
+export declare function useLatestOperation(): LatestOperation;
+//# sourceMappingURL=useLatestOperation.d.ts.map

package/dist/react/hooks/useLatestOperation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLatestOperation.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/useLatestOperation.ts"],"names":[],"mappings":"AA4BA,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,aAAa,IAAI,IAAI,CAAC;IACtB,qFAAqF;IACrF,SAAS,IAAI,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,GAAG,CACD,IAAI,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,EAC9C,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAC9B,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,yEAAyE;IACzE,SAAS,IAAI,IAAI,CAAC;CACnB;AAED,sFAAsF;AACtF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAE7D;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAwCpD"}

package/dist/react/hooks/useLatestOperation.js

@@ -0,0 +1,74 @@
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+/**
+ * "Only the newest attempt may write state" — the rule every async hook in this package needs, and
+ * the one that produced the worst complexity in the feature.
+ *
+ * Written by hand it is a `if (!mountedRef.current || generation !== generationRef.current) return;`
+ * after *every* await, repeated again inside the `catch`, inside a `useCallback` inside a hook — so
+ * each of those guards is scored at nesting level 2 or 3 and costs 3 cognitive points rather than 1.
+ * `useChatPaneWorkingDirectory` carried four near-identical copies of the shape.
+ *
+ * Here the guard throws instead of returning, and {@link LatestOperation.run} swallows it. The body
+ * then reads as a straight line of awaits with `token.ensureCurrent()` between them, and the branch
+ * exists once — in this file.
+ */
+/**
+ * Thrown by {@link OperationToken.ensureCurrent} once its operation has been superseded or the
+ * component has unmounted. Never escapes {@link LatestOperation.run}, and callers neither construct
+ * nor catch it.
+ */
+class SupersededOperation extends Error {
+    constructor() {
+        super('operation superseded');
+        this.name = 'SupersededOperation';
+    }
+}
+/** Preserves native Error objects while normalizing opaque host-bridge rejections. */
+export function normalizeOperationError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+/**
+ * Owns the mounted flag and the generation counter that decide which async attempt is allowed to
+ * write state. One instance per hook: every operation started through it supersedes the previous
+ * one, so a validation still in flight cannot clobber the result of the pick that replaced it.
+ *
+ * @complexity Time/space: O(1).
+ */
+export function useLatestOperation() {
+    const mountedRef = useRef(true);
+    const generationRef = useRef(0);
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+            generationRef.current += 1;
+        };
+    }, []);
+    const supersede = useCallback(() => {
+        generationRef.current += 1;
+    }, []);
+    const run = useCallback(async (body, onError) => {
+        const generation = ++generationRef.current;
+        const isCurrent = () => mountedRef.current && generation === generationRef.current;
+        const token = {
+            isCurrent,
+            ensureCurrent: () => {
+                // A generation only ever increases and unmount bumps it, so once stale always stale —
+                // which is why `run`'s catch needs no `instanceof` test to tell this apart from a real
+                // failure. `isCurrent()` is already false for anything thrown from here.
+                if (!isCurrent())
+                    throw new SupersededOperation();
+            },
+        };
+        try {
+            await body(token);
+        }
+        catch (error) {
+            if (!isCurrent())
+                return;
+            onError(normalizeOperationError(error));
+        }
+    }, []);
+    return useMemo(() => ({ run, supersede }), [run, supersede]);
+}
+//# sourceMappingURL=useLatestOperation.js.map

package/dist/react/hooks/useLatestOperation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLatestOperation.js","sourceRoot":"","sources":["../../../src/react/hooks/useLatestOperation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAEhE;;;;;;;;;;;;GAYG;AAEH;;;;GAIG;AACH,MAAM,mBAAoB,SAAQ,KAAK;IACrC;QACE,KAAK,CAAC,sBAAsB,CAAC,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AA2BD,sFAAsF;AACtF,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACpD,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAChC,MAAM,aAAa,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IAEhC,SAAS,CAAC,GAAG,EAAE;QACb,UAAU,CAAC,OAAO,GAAG,IAAI,CAAC;QAC1B,OAAO,GAAG,EAAE;YACV,UAAU,CAAC,OAAO,GAAG,KAAK,CAAC;YAC3B,aAAa,CAAC,OAAO,IAAI,CAAC,CAAC;QAC7B,CAAC,CAAC;IACJ,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE;QACjC,aAAa,CAAC,OAAO,IAAI,CAAC,CAAC;IAC7B,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,GAAG,GAAG,WAAW,CAAC,KAAK,EAC3B,IAA8C,EAC9C,OAA+B,EAChB,EAAE;QACjB,MAAM,UAAU,GAAG,EAAE,aAAa,CAAC,OAAO,CAAC;QAC3C,MAAM,SAAS,GAAG,GAAG,EAAE,CAAC,UAAU,CAAC,OAAO,IAAI,UAAU,KAAK,aAAa,CAAC,OAAO,CAAC;QACnF,MAAM,KAAK,GAAmB;YAC5B,SAAS;YACT,aAAa,EAAE,GAAG,EAAE;gBAClB,sFAAsF;gBACtF,uFAAuF;gBACvF,yEAAyE;gBACzE,IAAI,CAAC,SAAS,EAAE;oBAAE,MAAM,IAAI,mBAAmB,EAAE,CAAC;YACpD,CAAC;SACF,CAAC;QACF,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,KAAK,CAAC,CAAC;QACpB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,SAAS,EAAE;gBAAE,OAAO;YACzB,OAAO,CAAC,uBAAuB,CAAC,KAAK,CAAC,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC;AAC/D,CAAC"}

package/dist/react/hooks/usePinnedTodos.d.ts

@@ -0,0 +1,15 @@
+import type { ChatMessage, TodoItem } from '../../core/index.js';
+export interface UsePinnedTodosResult {
+    todos: TodoItem[];
+    total: number;
+    completed: number;
+    inProgress: TodoItem | undefined;
+    /** `true` once every todo in the latest plan is `completed`. */
+    allComplete: boolean;
+    /** `false` when there's no plan yet, or the user dismissed the current (all-complete) plan. */
+    visible: boolean;
+    /** Dismisses the currently-pinned card. Only meaningful once `allComplete`; re-appears automatically once the plan changes again. */
+    dismiss: () => void;
+}
+export declare function usePinnedTodos(messages: ReadonlyArray<ChatMessage> | undefined): UsePinnedTodosResult;
+//# sourceMappingURL=usePinnedTodos.d.ts.map

package/dist/react/hooks/usePinnedTodos.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePinnedTodos.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/usePinnedTodos.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAGjE,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,QAAQ,GAAG,SAAS,CAAC;IACjC,gEAAgE;IAChE,WAAW,EAAE,OAAO,CAAC;IACrB,+FAA+F;IAC/F,OAAO,EAAE,OAAO,CAAC;IACjB,qIAAqI;IACrI,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,SAAS,GAAG,oBAAoB,CAkBrG"}

package/dist/react/hooks/usePinnedTodos.js

@@ -0,0 +1,43 @@
+/**
+ * @module usePinnedTodos
+ *
+ * The latest `TodoWrite`-style plan snapshot across a conversation, a
+ * dismissed-key so a user's dismissal sticks until the plan actually
+ * changes again, and progress counts for a pinned progress-card UI. Pure
+ * over `messages` — built on `@jini-ai/chat/core`'s
+ * `latestTodoWriteInputForPinnedCard`/`parseTodoWriteInput`. Per
+ * `ADS-memory/reports/jini-port/recon/r4b-webui-design.md` §4 (origin: OD's
+ * `runtime/todos.ts` pinned-card logic, `components/ToolCard.tsx`'s
+ * `TodoCard`'s `onDismiss` convention).
+ */
+import { useCallback, useMemo, useState } from 'react';
+import { latestTodoWriteInputForPinnedCard, parseTodoWriteInput } from '../../core/index.js';
+export function usePinnedTodos(messages) {
+    const [dismissedKey, setDismissedKey] = useState(null);
+    const rawInput = useMemo(() => latestTodoWriteInputForPinnedCard(messages), [messages]);
+    const todos = useMemo(() => parseTodoWriteInput(rawInput), [rawInput]);
+    const key = useMemo(() => (rawInput === null ? null : safeStableKey(rawInput)), [rawInput]);
+    const total = todos.length;
+    const completed = todos.filter((t) => t.status === 'completed').length;
+    const allComplete = total > 0 && completed === total;
+    const inProgress = todos.find((t) => t.status === 'in_progress');
+    const visible = total > 0 && !(allComplete && key !== null && key === dismissedKey);
+    const dismiss = useCallback(() => {
+        if (key !== null)
+            setDismissedKey(key);
+    }, [key]);
+    return { todos, total, completed, inProgress, allComplete, visible, dismiss };
+}
+// A plan-tool `input` is arbitrary JSON; stringify gives a cheap, stable
+// identity for "has the plan actually changed since dismissal" without
+// depending on object reference equality (a fresh event array on every
+// stream tick would otherwise always look "new").
+function safeStableKey(input) {
+    try {
+        return JSON.stringify(input);
+    }
+    catch {
+        return String(input);
+    }
+}
+//# sourceMappingURL=usePinnedTodos.js.map

package/dist/react/hooks/usePinnedTodos.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePinnedTodos.js","sourceRoot":"","sources":["../../../src/react/hooks/usePinnedTodos.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEvD,OAAO,EAAE,iCAAiC,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAe7F,MAAM,UAAU,cAAc,CAAC,QAAgD;IAC7E,MAAM,CAAC,YAAY,EAAE,eAAe,CAAC,GAAG,QAAQ,CAAgB,IAAI,CAAC,CAAC;IAEtE,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,iCAAiC,CAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;IACxF,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,mBAAmB,CAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;IACvE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;IAE5F,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC;IAC3B,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,MAAM,CAAC;IACvE,MAAM,WAAW,GAAG,KAAK,GAAG,CAAC,IAAI,SAAS,KAAK,KAAK,CAAC;IACrD,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,aAAa,CAAC,CAAC;IACjE,MAAM,OAAO,GAAG,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC,WAAW,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,YAAY,CAAC,CAAC;IAEpF,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE;QAC/B,IAAI,GAAG,KAAK,IAAI;YAAE,eAAe,CAAC,GAAG,CAAC,CAAC;IACzC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAEV,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAChF,CAAC;AAED,yEAAyE;AACzE,uEAAuE;AACvE,uEAAuE;AACvE,kDAAkD;AAClD,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/react/hooks/useQuestionForms.d.ts

@@ -0,0 +1,28 @@
+import type { ChatMessage, QuestionForm } from '../../core/index.js';
+export type QuestionFormAnswers = Record<string, string | string[]>;
+export interface ParsedQuestionForm {
+    form: QuestionForm;
+    raw: string;
+    /** The assistant message this form was found in. */
+    messageId: string;
+    /** `true` when this is the most recent assistant message with no reply after it yet — i.e. still answerable. */
+    interactive: boolean;
+    /** Recovered from the next user message's `[form answers — ...]` text, if one exists. */
+    submittedAnswers: QuestionFormAnswers | undefined;
+}
+export interface UseQuestionFormsResult {
+    /** Every question-form found across the conversation, oldest first. */
+    forms: ParsedQuestionForm[];
+    /** The most recent form that is still `interactive` (unanswered), or `null`. */
+    activeForm: ParsedQuestionForm | null;
+    /** Formats `answers` into the prose user-message text the host sends back. */
+    buildSubmission: (form: QuestionForm, answers: QuestionFormAnswers) => string;
+}
+export declare function useQuestionForms(messages: ReadonlyArray<ChatMessage> | undefined): UseQuestionFormsResult;
+/**
+ * Reverse of `formatFormAnswers` — given the user message that (maybe)
+ * answered `form`, recover the answers map so the form can render in its
+ * locked "answered" state with the user's picks visible.
+ */
+export declare function parseSubmittedAnswers(form: QuestionForm, userMessageContent: string): QuestionFormAnswers | null;
+//# sourceMappingURL=useQuestionForms.d.ts.map

package/dist/react/hooks/useQuestionForms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useQuestionForms.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/useQuestionForms.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,WAAW,EAAgB,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnF,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;AAEpE,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,YAAY,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,gHAAgH;IAChH,WAAW,EAAE,OAAO,CAAC;IACrB,yFAAyF;IACzF,gBAAgB,EAAE,mBAAmB,GAAG,SAAS,CAAC;CACnD;AAED,MAAM,WAAW,sBAAsB;IACrC,uEAAuE;IACvE,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,gFAAgF;IAChF,UAAU,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACtC,8EAA8E;IAC9E,eAAe,EAAE,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,mBAAmB,KAAK,MAAM,CAAC;CAC/E;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,SAAS,GAAG,sBAAsB,CA6BzG;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAkChH"}