@jini-ai/chat 0.5.6 → 0.5.8

package/dist/core/tool-call-detail.js

@@ -0,0 +1,67 @@
+/**
+ * The expanded body of a tool-call row: what the agent sent, what came back, and — when nothing
+ * came back — why. Shared by every card in `react/components/ToolCard.tsx` so no row kind (a CLI
+ * built-in like WebFetch, an unknown MCP tool, a card tool such as `assistant_ask_choice` still
+ * waiting on the person's answer) is left without a readable call.
+ */
+import { formatToolOutputForDisplay } from './tool-output.js';
+import { redactUserText } from './user-text-redaction.js';
+const DEFAULT_MAX_CHARS = 10_000;
+/**
+ * Builds the readable detail for one tool call.
+ *
+ * @param required.input - The `tool_use` event's input, any shape.
+ * @param required.result - The paired `tool_result`, when one arrived.
+ * @param options - Run state that explains a missing result, the display cap, and the redactor.
+ * @returns Display-ready input and output text plus a note when the output is absent.
+ * @complexity O(n) in the serialized input plus result length.
+ */
+export function describeToolCallDetail({ input, result }, { runStreaming = false, runSucceeded = false, maxChars = DEFAULT_MAX_CHARS, redact = redactUserText } = {}) {
+    const show = (text) => (text === null ? null : truncate(redact({ text: text }).text, maxChars));
+    const inputText = show(serializeInput(input));
+    if (!result)
+        return { inputText, outputText: null, noteKey: missingResultNote({ runStreaming, runSucceeded }) };
+    if (!result.content.trim())
+        return { inputText, outputText: null, noteKey: result.isError ? 'Failed without an error message.' : 'Finished with no output.' };
+    return { inputText, outputText: show(formatToolOutputForDisplay({ text: result.content })), noteKey: null };
+}
+/** Per-block cap for the text a collapsed row keeps mounted — see {@link describeCollapsedToolCall}. */
+export const COLLAPSED_DETAIL_MAX_CHARS = 400;
+/**
+ * The short, single-node text a collapsed row keeps in the DOM in place of its full detail. A long
+ * chat mounts hundreds of collapsed rows (713 in a 38-message chat, 3.45 MB of hidden text at the
+ * full 10 000-char cap), so the full panel is mounted only while open; this keeps the gist —
+ * input, then output or the note explaining its absence — readable through the row's
+ * `textContent` for a `page.*` DOM reader that never clicks.
+ *
+ * @param required - Same as {@link describeToolCallDetail}.
+ * @param options - Same as {@link describeToolCallDetail}; `maxChars` defaults to {@link COLLAPSED_DETAIL_MAX_CHARS}.
+ * @returns Input (when it has a JSON form) and output or note, joined by a newline — never empty, since a missing output always carries a note.
+ * @complexity O(n) in the serialized input plus result length (redaction runs before the cap).
+ */
+export function describeCollapsedToolCall(required, options = {}) {
+    const detail = describeToolCallDetail(required, { maxChars: COLLAPSED_DETAIL_MAX_CHARS, ...options });
+    return [detail.inputText, detail.outputText ?? detail.noteKey].filter((part) => part !== null).join('\n');
+}
+function missingResultNote({ runStreaming, runSucceeded }) {
+    if (runStreaming)
+        return 'Waiting for the result or answer…';
+    return runSucceeded ? 'No result was recorded for this call.' : 'The run ended before this call returned a result.';
+}
+/** A string input is shown as given (re-indented only when it is itself a JSON object/array); anything else is pretty JSON, or `null` when it has no JSON form (circular, a function). */
+function serializeInput(input) {
+    if (input === null || input === undefined)
+        return null;
+    if (typeof input === 'string')
+        return formatToolOutputForDisplay({ text: input });
+    try {
+        return JSON.stringify(input, null, 2) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function truncate(text, max) {
+    return text.length <= max ? text : text.slice(0, max - 1) + '…';
+}
+//# sourceMappingURL=tool-call-detail.js.map

package/dist/core/turn-usage.d.ts

@@ -0,0 +1,50 @@
+import type { AgentEvent } from './events.js';
+import type { ChatMessage } from './messages.js';
+type UsageEvent = Extract<AgentEvent, {
+    kind: 'usage';
+}>;
+/** A turn's reported usage plus the conversation's prefix total. `segments` is present only when the
+ * message holds more than one reply (a mid-run message started a new one): one entry per reply, in
+ * order, each with its own prefix total, so every reply can show its own "Done" line. */
+export type ChatUsageSummary = UsageEvent & {
+    totalCostUsd?: number;
+    segments?: readonly (ChatUsageSummary | undefined)[];
+};
+type SessionCost = {
+    sessionId: string;
+    chargedUsd: number;
+};
+/** The ext event a message sent mid-run arrives as (the daemon's `user_message` run event). The agent
+ * answers it as a new reply inside the same run, so it ends the reply before it. */
+export declare const MID_RUN_USER_MESSAGE_EVENT_NAME = "user_message";
+/** Whether this event is a mid-run user message, i.e. the boundary between two replies of one run. */
+export declare function isReplyBoundary({ event }: {
+    event: AgentEvent;
+}, _optional?: {}): boolean;
+/** Split one assistant message's events into replies at each mid-run user message. A usage event
+ * that lands after a boundary but before the next reply produced anything is the interrupted
+ * reply's own result (the daemon notes it can arrive after the interrupt ack), so it stays with
+ * the reply before. Event order is otherwise preserved. O(n) for n events.
+ * @example replySegments({ events }).length // 1 + number of mid-run user messages */
+export declare function replySegments({ events }: {
+    events: readonly AgentEvent[] | undefined;
+}, _optional?: {}): AgentEvent[][];
+/** Sum reported segment usage for a turn, including aborted segments and recovered attempts.
+ * Optional projection state is updated to reconcile session snapshots across turns.
+ * Missing fields stay absent; money is never inferred. O(n) time for n events.
+ * @example turnUsage({ events: message.events }) */
+export declare function turnUsage({ events }: {
+    events: readonly AgentEvent[] | undefined;
+}, { sessions, agentId }?: {
+    sessions?: Map<string, SessionCost>;
+    agentId?: string;
+}): UsageEvent | undefined;
+/** Derive per-turn charges and prefix totals from persisted events_json, for live and reloaded
+ * chats alike. A message with mid-run replies also gets per-reply `segments`. O(e + m) for e events
+ * and m messages; no per-row transcript scans or I/O.
+ * @example conversationUsage({ messages: savedMessages }).get('assistant-2') */
+export declare function conversationUsage({ messages }: {
+    messages: readonly ChatMessage[];
+}, _optional?: {}): Map<string, ChatUsageSummary>;
+export {};
+//# sourceMappingURL=turn-usage.d.ts.map

package/dist/core/turn-usage.js

@@ -0,0 +1,114 @@
+/** The ext event a message sent mid-run arrives as (the daemon's `user_message` run event). The agent
+ * answers it as a new reply inside the same run, so it ends the reply before it. */
+export const MID_RUN_USER_MESSAGE_EVENT_NAME = 'user_message';
+/** Whether this event is a mid-run user message, i.e. the boundary between two replies of one run. */
+export function isReplyBoundary({ event }, _optional = {}) {
+    return event.kind === 'ext' && event.name === MID_RUN_USER_MESSAGE_EVENT_NAME;
+}
+/** Split one assistant message's events into replies at each mid-run user message. A usage event
+ * that lands after a boundary but before the next reply produced anything is the interrupted
+ * reply's own result (the daemon notes it can arrive after the interrupt ack), so it stays with
+ * the reply before. Event order is otherwise preserved. O(n) for n events.
+ * @example replySegments({ events }).length // 1 + number of mid-run user messages */
+export function replySegments({ events }, _optional = {}) {
+    const segments = [[]];
+    let started = false;
+    for (const event of events ?? []) {
+        if (isReplyBoundary({ event })) {
+            segments.push([]);
+            started = false;
+            continue;
+        }
+        const target = event.kind === 'usage' && !started && segments.length > 1 ? segments.length - 2 : segments.length - 1;
+        if (event.kind !== 'usage' && event.kind !== 'status' && event.kind !== 'raw')
+            started = true;
+        segments[target].push(event);
+    }
+    return segments;
+}
+/** Resolve one charge against this agent/session's last snapshot. State is local to an
+ * ordered transcript projection; revisiting a session keeps its baseline. A lower snapshot
+ * starts a new counter epoch (some CLIs reset their counter on resume). O(1) map access. */
+function usageCost({ event, agentId, sessions }, _optional = {}) {
+    const sessionId = event.costSessionId;
+    if (!sessionId)
+        return validCost(event.costUsd);
+    const key = JSON.stringify([agentId, sessionId]);
+    const chargedUsd = sessions.get(key)?.chargedUsd ?? 0;
+    const cumulative = validCost(event.cumulativeCostUsd);
+    const cost = cumulative === undefined ? validCost(event.costUsd)
+        : cumulative < chargedUsd ? cumulative : cumulative - chargedUsd;
+    // Interim interrupted-segment charges are already paid; later snapshots subtract them.
+    // After a counter reset the new snapshot, rather than the old epoch's total, is the baseline.
+    sessions.set(key, { sessionId, chargedUsd: cumulative ?? chargedUsd + (cost ?? 0) });
+    return cost;
+}
+/** Missing or malformed costs stay unknown; never infer charges from tokens. */
+function validCost(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+/** Sum reported segment usage for a turn, including aborted segments and recovered attempts.
+ * Optional projection state is updated to reconcile session snapshots across turns.
+ * Missing fields stay absent; money is never inferred. O(n) time for n events.
+ * @example turnUsage({ events: message.events }) */
+export function turnUsage({ events }, { sessions = new Map(), agentId = '' } = {}) {
+    let total;
+    for (const event of events ?? []) {
+        if (event.kind !== 'usage')
+            continue;
+        total ??= { kind: 'usage' };
+        for (const field of ['inputTokens', 'outputTokens', 'durationMs']) {
+            const value = event[field];
+            if (typeof value === 'number' && Number.isFinite(value) && value >= 0)
+                total[field] = (total[field] ?? 0) + value;
+        }
+        const cost = usageCost({ event, agentId, sessions });
+        if (cost !== undefined)
+            total.costUsd = (total.costUsd ?? 0) + cost;
+    }
+    return total;
+}
+/** Add one reply's usage into a message total; fields absent from both stay absent. O(1). */
+function addUsage({ total, usage }, _optional = {}) {
+    if (!usage)
+        return total;
+    const next = { ...(total ?? { kind: 'usage' }) };
+    for (const field of ['inputTokens', 'outputTokens', 'durationMs', 'costUsd']) {
+        const value = usage[field];
+        if (value !== undefined)
+            next[field] = (next[field] ?? 0) + value;
+    }
+    return next;
+}
+/** Derive per-turn charges and prefix totals from persisted events_json, for live and reloaded
+ * chats alike. A message with mid-run replies also gets per-reply `segments`. O(e + m) for e events
+ * and m messages; no per-row transcript scans or I/O.
+ * @example conversationUsage({ messages: savedMessages }).get('assistant-2') */
+export function conversationUsage({ messages }, _optional = {}) {
+    const sessions = new Map();
+    const summaries = new Map();
+    let totalCostUsd;
+    for (const message of messages) {
+        if (message.role !== 'assistant')
+            continue;
+        // Replies run in event order through one session map, so their sum equals the whole-message charge.
+        const segments = [];
+        let usage;
+        for (const events of replySegments({ events: message.events })) {
+            const segment = turnUsage({ events }, { sessions, agentId: message.agentId ?? '' });
+            usage = addUsage({ total: usage, usage: segment });
+            if (segment?.costUsd !== undefined)
+                totalCostUsd = (totalCostUsd ?? 0) + segment.costUsd;
+            segments.push(segment && { ...segment, ...(totalCostUsd === undefined ? {} : { totalCostUsd }) });
+        }
+        if (!usage)
+            continue;
+        summaries.set(message.id, {
+            ...usage,
+            ...(totalCostUsd === undefined ? {} : { totalCostUsd }),
+            ...(segments.length > 1 ? { segments } : {}),
+        });
+    }
+    return summaries;
+}
+//# sourceMappingURL=turn-usage.js.map

package/dist/core/usage-format.d.ts

@@ -0,0 +1,10 @@
+/** Format a known turn charge, and its conversation prefix total only when one is passed; round only
+ * for display. The total is the chat's running total as of that turn, so an earlier turn's line never
+ * changes when later turns run (owner, 2026-10-10: "Done · 16s · $0.39 · total $3.95").
+ * @example formatUsageCost({ costUsd: 0.445, totalCostUsd: 2.5 }) // '$0.45 · total $2.50'
+ * @example formatUsageCost({ costUsd: 0.445 }) // '$0.45' */
+export declare function formatUsageCost({ costUsd, totalCostUsd }: {
+    costUsd: number;
+    totalCostUsd?: number | undefined;
+}, _optional?: {}): string;
+//# sourceMappingURL=usage-format.d.ts.map

package/dist/core/usage-format.js

@@ -0,0 +1,15 @@
+/** Round reported USD upward to cents after clearing arithmetic noise at 1e-8 USD precision.
+ * Keep the minimum cent for any positive reported charge, even below the noise precision. */
+function dollars(usd) {
+    const cents = usd > 0 ? Math.max(1, Math.ceil(Math.round(usd * 1e8) / 1e6)) : 0;
+    return `$${(cents / 100).toFixed(2)}`;
+}
+/** Format a known turn charge, and its conversation prefix total only when one is passed; round only
+ * for display. The total is the chat's running total as of that turn, so an earlier turn's line never
+ * changes when later turns run (owner, 2026-10-10: "Done · 16s · $0.39 · total $3.95").
+ * @example formatUsageCost({ costUsd: 0.445, totalCostUsd: 2.5 }) // '$0.45 · total $2.50'
+ * @example formatUsageCost({ costUsd: 0.445 }) // '$0.45' */
+export function formatUsageCost({ costUsd, totalCostUsd }, _optional = {}) {
+    return totalCostUsd === undefined ? dollars(costUsd) : `${dollars(costUsd)} · total ${dollars(totalCostUsd)}`;
+}
+//# sourceMappingURL=usage-format.js.map

package/dist/embed-widget/browser/lazy-loader.d.ts

@@ -0,0 +1,34 @@
+/** Shared bubble styles for server placeholders and mounted DOM widgets; no runtime dependencies. */
+export declare const CHAT_BUBBLE_STYLE = ".jini-chat-bubble{position:fixed;right:var(--jini-embed-right,24px);bottom:24px;width:56px;height:56px;border:0;border-radius:50%;background:var(--jini-chat-accent,var(--color-primary,#2563eb));color:var(--jini-chat-accent-text,#fff);box-shadow:0 4px 16px #0003;cursor:pointer;z-index:var(--jini-embed-z-index,1000);display:grid;place-items:center}\n.jini-chat-bubble[hidden]{display:none!important}\n.jini-chat-bubble svg{width:24px;height:24px}\n.jini-chat-bubble:focus-visible{outline:3px solid var(--jini-chat-accent,#2563eb);outline-offset:3px}\n@media(max-width:480px){.jini-chat-bubble{right:16px;bottom:16px}}\n.jini-chat-bubble[aria-busy=\"true\"]{cursor:progress;opacity:.65}\n.jini-chat-bubble[data-load-failed=\"true\"]{outline:2px solid var(--jini-chat-error,#b91c1c);outline-offset:3px}";
+export interface LazyChatLoaderArgs {
+    readonly button: HTMLButtonElement;
+    readonly load: (args: Record<string, never>) => Promise<void>;
+    readonly open: (args: {
+        focus?: boolean;
+    }) => void;
+    readonly resume: boolean;
+    readonly deepLink: boolean;
+    readonly preload?: boolean;
+    readonly loadingLabel: string;
+    readonly retryLabel: string;
+}
+/**
+ * Activates a host-rendered button without importing chat, React, icons or storage.
+ * One in-flight load serves repeated activation; failures remain retryable. Native button
+ * keyboard activation also emits click; preventDefault avoids a second toggle after keydown.
+ */
+export declare function installLazyChatLoader(args: LazyChatLoaderArgs, _options?: {}): {
+    activate: ({ open, focus }?: {
+        open?: boolean;
+        focus?: boolean;
+    }, _options?: {}) => Promise<void>;
+    dispose(_input?: Record<string, never>, _options?: {}): void;
+};
+/** Loads CSS before a self-mounting classic script; failed elements are removed for retry. */
+export declare function loadChatAssets({ document, scriptUrl, styleUrl, mount }: {
+    document: Document;
+    scriptUrl: string;
+    styleUrl: string;
+    mount?: HTMLElement;
+}, _options?: {}): Promise<void>;
+//# sourceMappingURL=lazy-loader.d.ts.map

package/dist/embed-widget/browser/lazy-loader.js

@@ -0,0 +1,116 @@
+/** Shared bubble styles for server placeholders and mounted DOM widgets; no runtime dependencies. */
+export const CHAT_BUBBLE_STYLE = '.jini-chat-bubble{position:fixed;right:var(--jini-embed-right,24px);bottom:24px;width:56px;height:56px;border:0;border-radius:50%;background:var(--jini-chat-accent,var(--color-primary,#2563eb));color:var(--jini-chat-accent-text,#fff);box-shadow:0 4px 16px #0003;cursor:pointer;z-index:var(--jini-embed-z-index,1000);display:grid;place-items:center}\n.jini-chat-bubble[hidden]{display:none!important}\n.jini-chat-bubble svg{width:24px;height:24px}\n.jini-chat-bubble:focus-visible{outline:3px solid var(--jini-chat-accent,#2563eb);outline-offset:3px}\n@media(max-width:480px){.jini-chat-bubble{right:16px;bottom:16px}}\n.jini-chat-bubble[aria-busy="true"]{cursor:progress;opacity:.65}\n.jini-chat-bubble[data-load-failed="true"]{outline:2px solid var(--jini-chat-error,#b91c1c);outline-offset:3px}';
+/**
+ * Activates a host-rendered button without importing chat, React, icons or storage.
+ * One in-flight load serves repeated activation; failures remain retryable. Native button
+ * keyboard activation also emits click; preventDefault avoids a second toggle after keydown.
+ */
+export function installLazyChatLoader(args, _options = {}) {
+    let pending = null;
+    let ready = false;
+    let disposed = false;
+    let shouldOpen = false;
+    let shouldFocus = false;
+    const initialContent = args.button.innerHTML;
+    const label = args.button.getAttribute('aria-label') ?? '';
+    const activate = async ({ open = true, focus = open } = {}, _options = {}) => {
+        if (disposed)
+            return;
+        if (!pending) {
+            shouldOpen = false;
+            shouldFocus = false;
+        }
+        shouldOpen ||= open;
+        shouldFocus ||= focus;
+        if (pending)
+            return pending;
+        args.button.setAttribute('aria-busy', 'true');
+        args.button.setAttribute('aria-label', args.loadingLabel);
+        args.button.textContent = args.loadingLabel;
+        delete args.button.dataset.loadFailed;
+        // Defer through a promise so a synchronous host load failure follows the same retry path.
+        pending = Promise.resolve().then(() => { if (!ready)
+            return args.load({}); }).then(() => {
+            if (disposed)
+                return;
+            // Asset readiness survives an open failure; retry must never evaluate the script twice.
+            ready = true;
+            if (shouldOpen)
+                args.open({ focus: shouldFocus });
+            args.button.setAttribute('aria-label', label);
+            args.button.innerHTML = initialContent;
+            args.button.hidden = true;
+        }).catch(() => {
+            if (!disposed) {
+                args.button.hidden = false;
+                args.button.dataset.loadFailed = 'true';
+                args.button.setAttribute('aria-label', args.retryLabel);
+                args.button.textContent = args.retryLabel;
+            }
+        }).finally(() => {
+            pending = null;
+            args.button.removeAttribute('aria-busy');
+        });
+        return pending;
+    };
+    const click = () => { void activate({}); };
+    const keydown = (event) => {
+        if (event.key !== 'Enter' && event.key !== ' ')
+            return;
+        event.preventDefault();
+        void activate({});
+    };
+    args.button.addEventListener('click', click);
+    args.button.addEventListener('keydown', keydown);
+    args.button.dataset.loaderReady = 'true';
+    if (args.resume || args.deepLink)
+        void activate({ focus: args.deepLink });
+    else if (args.preload)
+        void activate({ open: false });
+    return {
+        activate,
+        dispose(_input = {}, _options = {}) {
+            disposed = true;
+            args.button.removeEventListener('click', click);
+            args.button.removeEventListener('keydown', keydown);
+            args.button.setAttribute('aria-label', label);
+            args.button.innerHTML = initialContent;
+            args.button.removeAttribute('aria-busy');
+            delete args.button.dataset.loadFailed;
+            delete args.button.dataset.loaderReady;
+        },
+    };
+}
+/** Loads CSS before a self-mounting classic script; failed elements are removed for retry. */
+export async function loadChatAssets({ document, scriptUrl, styleUrl, mount }, _options = {}) {
+    const stylesheet = document.createElement('link');
+    stylesheet.rel = 'stylesheet';
+    stylesheet.href = styleUrl;
+    const script = document.createElement('script');
+    script.src = scriptUrl;
+    const loaded = (element) => new Promise((resolve, reject) => {
+        element.onload = () => resolve();
+        element.onerror = () => reject(new Error('Chat assets could not be loaded'));
+        document.head.appendChild(element);
+    });
+    try {
+        await loaded(stylesheet);
+        await loaded(script);
+        // A classic script's load event proves evaluation, not React commit or a successful mount.
+        // Optional for legacy hosts; lazy visitor hosts supply their root as the readiness boundary.
+        if (mount && mount.dataset.chatMounted !== 'true') {
+            await new Promise((resolve, reject) => {
+                const ready = () => { cleanup(); resolve(); };
+                const timeout = setTimeout(() => { cleanup(); reject(new Error('Chat widget did not mount')); }, 10_000);
+                const cleanup = () => { clearTimeout(timeout); mount.removeEventListener('jini-chat-mounted', ready); };
+                mount.addEventListener('jini-chat-mounted', ready);
+            });
+        }
+    }
+    catch (error) {
+        stylesheet.remove();
+        script.remove();
+        throw error;
+    }
+}
+//# sourceMappingURL=lazy-loader.js.map

package/dist/embed-widget/react/dialog.hooks.d.ts

@@ -0,0 +1,28 @@
+import { type RefObject } from 'react';
+/**
+ * Shares the panel-kit trap across embeds. Escape respects a child popup's preventDefault;
+ * Closing restores the mounted launcher, including after a lazy-loader handoff.
+ * A changed resetKey focuses the replacement composer after the host remounts the pane.
+ * @complexity O(focusable controls) per Tab; O(1) listeners and retained state.
+ */
+export declare function useEmbedChatDialog({ open, onClose, panelRef, launcherRef }: {
+    open: boolean;
+    onClose: () => void;
+    panelRef: RefObject<HTMLElement | null>;
+    launcherRef: RefObject<HTMLElement | null>;
+}, { resetKey }?: {
+    resetKey?: number | undefined;
+}): void;
+/** Reusable state/ref wiring for the packaged embed. O(1) besides the shared trap's Tab scan. */
+export declare function useEmbedChatSurface({ initialOpen }: {
+    initialOpen: boolean;
+}, { resetKey }?: {
+    resetKey?: number | undefined;
+}): {
+    open: boolean;
+    toggle: () => void;
+    panelRef: RefObject<HTMLDivElement | null>;
+    launcherRef: RefObject<HTMLDivElement | null>;
+    panelId: string;
+};
+//# sourceMappingURL=dialog.hooks.d.ts.map

package/dist/embed-widget/react/dialog.hooks.js

@@ -0,0 +1,54 @@
+import { useCallback, useEffect, useId, useLayoutEffect, useRef, useState } from 'react';
+import { useFocusTrap } from '@jini-ai/ui/panel-kit';
+/**
+ * Shares the panel-kit trap across embeds. Escape respects a child popup's preventDefault;
+ * Closing restores the mounted launcher, including after a lazy-loader handoff.
+ * A changed resetKey focuses the replacement composer after the host remounts the pane.
+ * @complexity O(focusable controls) per Tab; O(1) listeners and retained state.
+ */
+export function useEmbedChatDialog({ open, onClose, panelRef, launcherRef }, { resetKey } = {}) {
+    const wasOpen = useRef(open);
+    const previousResetKey = useRef(resetKey);
+    useFocusTrap({ containerRef: panelRef }, { active: open });
+    useLayoutEffect(() => {
+        if (open && previousResetKey.current !== resetKey) {
+            panelRef.current?.querySelector('textarea:not(:disabled)')?.focus();
+        }
+        previousResetKey.current = resetKey;
+    }, [open, resetKey, panelRef]);
+    useEffect(() => {
+        if (wasOpen.current && !open) {
+            const launcher = launcherRef.current;
+            (launcher?.querySelector('button') ?? launcher)?.focus();
+        }
+        wasOpen.current = open;
+    }, [open, launcherRef]);
+    useEffect(() => {
+        if (!open)
+            return;
+        const panel = panelRef.current;
+        const view = panel?.ownerDocument.defaultView;
+        if (!panel || !view)
+            return;
+        const onKeyDown = (event) => {
+            if (event.key === 'Escape' && !event.defaultPrevented) {
+                event.preventDefault();
+                onClose();
+            }
+        };
+        view.addEventListener('keydown', onKeyDown);
+        return () => view.removeEventListener('keydown', onKeyDown);
+    }, [open, onClose, panelRef]);
+}
+/** Reusable state/ref wiring for the packaged embed. O(1) besides the shared trap's Tab scan. */
+export function useEmbedChatSurface({ initialOpen }, { resetKey } = {}) {
+    const [open, setOpen] = useState(initialOpen);
+    const panelRef = useRef(null);
+    const launcherRef = useRef(null);
+    const panelId = useId();
+    const close = useCallback(() => setOpen(false), []);
+    const toggle = useCallback(() => setOpen(current => !current), []);
+    useEmbedChatDialog({ open, onClose: close, panelRef, launcherRef }, { resetKey });
+    return { open, toggle, panelRef, launcherRef, panelId };
+}
+//# sourceMappingURL=dialog.hooks.js.map

package/dist/embed-widget/react/embed.d.ts

@@ -2,6 +2,7 @@ import type { ChatTransport } from '../../core/transport.js';
 import type { ChatPaneAgent } from '../../react/chat-pane.js';
 import type { BrowserSessionStore } from '../browser/session-store.js';
 import type { PageActionPort } from '../../core/browser/page-actions.js';
+export { useEmbedChatDialog } from './dialog.hooks.js';
 import type { EmbedHeaderCopy, EscapeKeyPort } from './header.js';
 export { EmbedChatHeader } from './header.js';
 export type { EmbedChatHeaderArgs, EmbedHeaderCopy, EscapeKeyPort } from './header.js';

package/dist/embed-widget/react/embed.js

@@ -7,6 +7,8 @@ import { ChatFab } from '../../react/components/ChatFab.js';
 import { JiniChatProvider } from '../../react/components/JiniChatProvider.js';
 import { extractPageActions, splitPageActions, isQueuedPageAction } from '../../core/browser/page-actions.js';
 import { EmbedChatHeader } from './header.js';
+import { useEmbedChatSurface } from './dialog.hooks.js';
+export { useEmbedChatDialog } from './dialog.hooks.js';
 export { EmbedChatHeader } from './header.js';
 const shellStyles = `
 .jini-chat-embed__panel { position:fixed; right:var(--jini-embed-right,24px); bottom:var(--jini-embed-bottom,88px); width:min(var(--jini-embed-width,440px),calc(100vw - 32px)); height:min(var(--jini-embed-height,620px),calc(100dvh - 120px)); z-index:var(--jini-embed-z-index,1000); display:flex; flex-direction:column; }
@@ -25,9 +27,9 @@ const shellStyles = `
 export function EmbedChatWidget(args) {
     const { agent, copy, transport, session, pageActions, directiveEventName, keyboard, scheduleFrame } = args;
     const [initial] = useState(() => session.load({}));
-    const [open, setOpen] = useState(initial.open);
-    const [messages, setMessages] = useState(initial.messages);
     const [paneKey, setPaneKey] = useState(0);
+    const { open, toggle, panelRef, launcherRef, panelId } = useEmbedChatSurface({ initialOpen: initial.open }, { resetKey: paneKey });
+    const [messages, setMessages] = useState(initial.messages);
     const [pending, setPending] = useState(null);
     const processed = useRef(new Set(initial.messages.map(message => message.id)));
     useEffect(() => { session.save({ state: { open, messages } }); }, [session, open, messages]);
@@ -76,7 +78,7 @@ export function EmbedChatWidget(args) {
         else
             setPending(proposal);
     }, [directiveEventName, pageActions, go]);
-    return _jsxs("div", { className: "jini-chat-embed", children: [_jsx("style", { children: shellStyles }), _jsx(ChatFab, { open: open, onToggle: () => setOpen(current => !current), label: copy.fabLabel }), _jsx(JiniChatProvider, { transport: transport, children: _jsxs("div", { className: "jini-chat-embed__panel", hidden: !open, children: [_jsx(ChatPane, { transport: transport, agents: [agent], initialSelection: { agentId: agent.id }, initialMessages: messages, title: copy.title, placeholder: copy.placeholder, workingDirectoryControlPlacement: "none", header: _jsx(EmbedChatHeader, { title: copy.title, hasMessages: messages.length > 0, onReset: reset, copy: copy, keyboard: keyboard }), onMessagesChange: onMessagesChange }, paneKey), pending ? _jsxs("div", { className: "jini-chat-embed__proposal", children: [_jsx("span", { children: copy.proposalLabel({ title: pending.navigate.target.title }) }), _jsx("button", { type: "button", onClick: () => { setPending(null); go(pending, messages); }, children: copy.proposalGo })] }) : null] }) })] });
+    return _jsxs("div", { className: "jini-chat-embed", children: [_jsx("style", { children: shellStyles }), _jsx("div", { ref: launcherRef, tabIndex: -1, children: _jsx(ChatFab, { open: open, onToggle: toggle, "aria-label": copy.fabLabel, label: copy.fabLabel, "aria-controls": panelId, "aria-haspopup": "dialog" }) }), _jsx(JiniChatProvider, { transport: transport, children: _jsxs("div", { id: panelId, className: "jini-chat-embed__panel", hidden: !open, ref: panelRef, role: "dialog", "aria-modal": "true", "aria-label": copy.title, children: [_jsx(ChatPane, { transport: transport, agents: [agent], initialSelection: { agentId: agent.id }, initialMessages: messages, title: copy.title, placeholder: copy.placeholder, variant: "embed", header: _jsx(EmbedChatHeader, { title: copy.title, hasMessages: messages.length > 0, onReset: reset, copy: copy, keyboard: keyboard }), onMessagesChange: onMessagesChange }, paneKey), pending ? _jsxs("div", { className: "jini-chat-embed__proposal", children: [_jsx("span", { children: copy.proposalLabel({ title: pending.navigate.target.title }) }), _jsx("button", { type: "button", onClick: () => { setPending(null); go(pending, messages); }, children: copy.proposalGo })] }) : null] }) })] });
 }
 /** Mounts into a host-provided node and returns lifecycle cleanup. O(1) plus React rendering. */
 export function mountEmbedChat({ element, widget }) {

package/dist/embed-widget/react/header.d.ts

@@ -1,3 +1,4 @@
+import type { ReactNode } from 'react';
 export interface EmbedHeaderCopy {
     readonly eyebrow: string;
     readonly newThread: string;
@@ -15,7 +16,8 @@ export interface EmbedChatHeaderArgs {
     readonly onReset: () => void;
     readonly copy: EmbedHeaderCopy;
     readonly keyboard: EscapeKeyPort;
+    readonly closeAction?: ReactNode;
 }
 /** Two-step reset with safe initial focus, Cancel and host-wide Escape. O(1) state and listeners. */
-export declare function EmbedChatHeader({ title, hasMessages, onReset, copy, keyboard }: EmbedChatHeaderArgs): import("react").JSX.Element;
+export declare function EmbedChatHeader({ title, hasMessages, onReset, copy, keyboard, closeAction }: EmbedChatHeaderArgs): import("react").JSX.Element;
 //# sourceMappingURL=header.d.ts.map

package/dist/embed-widget/react/header.hooks.d.ts

@@ -0,0 +1,13 @@
+import type { EmbedChatHeaderArgs } from './header.js';
+/** Confirm discarding messages or a live draft; Cancel/Escape restore the reset button.
+ * @complexity O(pane controls + draft length) per request; O(1) retained state.
+ */
+export declare function useEmbedChatHeader({ hasMessages, onReset, keyboard }: Pick<EmbedChatHeaderArgs, 'hasMessages' | 'onReset' | 'keyboard'>, _options?: {}): {
+    confirming: boolean;
+    cancel: () => void;
+    headerRef: import("react").RefObject<HTMLDivElement | null>;
+    resetButtonRef: import("react").RefObject<HTMLButtonElement | null>;
+    requestReset: () => void;
+    confirmReset: () => void;
+};
+//# sourceMappingURL=header.hooks.d.ts.map

package/dist/embed-widget/react/header.hooks.js

@@ -0,0 +1,32 @@
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+/** Confirm discarding messages or a live draft; Cancel/Escape restore the reset button.
+ * @complexity O(pane controls + draft length) per request; O(1) retained state.
+ */
+export function useEmbedChatHeader({ hasMessages, onReset, keyboard }, _options = {}) {
+    const [confirming, setConfirming] = useState(false);
+    const headerRef = useRef(null);
+    const resetButtonRef = useRef(null);
+    const wasConfirming = useRef(false);
+    const cancel = () => setConfirming(false);
+    useLayoutEffect(() => {
+        if (wasConfirming.current && !confirming)
+            resetButtonRef.current?.focus();
+        wasConfirming.current = confirming;
+    }, [confirming]);
+    useEffect(() => {
+        if (!confirming)
+            return;
+        return keyboard.subscribe({ onEscape: () => setConfirming(false) });
+    }, [confirming, keyboard]);
+    return { confirming, cancel, headerRef, resetButtonRef,
+        requestReset: () => {
+            // The pane owns the draft; inspect its live composer rather than keeping a second copy.
+            const composer = headerRef.current?.closest('.jini-chat-pane')?.querySelector('.jini-composer-input');
+            if (hasMessages || composer?.value)
+                setConfirming(true);
+            else
+                onReset();
+        },
+        confirmReset: () => { setConfirming(false); onReset(); }, };
+}
+//# sourceMappingURL=header.hooks.js.map

package/dist/embed-widget/react/header.js

@@ -1,18 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useState } from 'react';
+import { useEmbedChatHeader } from './header.hooks.js';
 /** Two-step reset with safe initial focus, Cancel and host-wide Escape. O(1) state and listeners. */
-export function EmbedChatHeader({ title, hasMessages, onReset, copy, keyboard }) {
-    const [confirming, setConfirming] = useState(false);
-    useEffect(() => {
-        if (!confirming)
-            return;
-        return keyboard.subscribe({ onEscape: () => setConfirming(false) });
-    }, [confirming, keyboard]);
-    return _jsxs("div", { className: "jini-chat-pane__header", children: [_jsxs("div", { className: "jini-chat-pane__heading", children: [_jsx("span", { className: "jini-chat-pane__eyebrow", children: copy.eyebrow }), _jsx("h2", { className: "jini-chat-pane__title", children: title })] }), confirming ? _jsxs("div", { className: "jini-chat-embed__reset-confirm", children: [_jsx("button", { type: "button", className: "jini-chat-embed__reset-cancel", autoFocus: true, onClick: () => setConfirming(false), children: copy.cancel }), _jsx("button", { type: "button", className: "jini-chat-pane__new-thread", onClick: () => { setConfirming(false); onReset(); }, children: copy.discard })] }) : _jsx("button", { type: "button", className: "jini-chat-pane__new-thread", onClick: () => {
-                    if (hasMessages)
-                        setConfirming(true);
-                    else
-                        onReset();
-                }, children: copy.newThread })] });
+export function EmbedChatHeader({ title, hasMessages, onReset, copy, keyboard, closeAction }) {
+    const { confirming, cancel, requestReset, confirmReset, headerRef, resetButtonRef } = useEmbedChatHeader({ hasMessages, onReset, keyboard });
+    return _jsxs("div", { className: "jini-chat-pane__header", ref: headerRef, children: [_jsxs("div", { className: "jini-chat-pane__heading", children: [copy.eyebrow && _jsx("span", { className: "jini-chat-pane__eyebrow", children: copy.eyebrow }), _jsx("h2", { className: "jini-chat-pane__title", children: title })] }), confirming ? _jsxs("div", { className: "jini-chat-embed__reset-confirm", children: [_jsx("button", { type: "button", className: "jini-chat-embed__reset-cancel", autoFocus: true, onClick: cancel, children: copy.cancel }), _jsx("button", { type: "button", className: "jini-chat-pane__new-thread", onClick: confirmReset, children: copy.discard })] }) : _jsx("button", { type: "button", className: "jini-chat-pane__new-thread", ref: resetButtonRef, onClick: requestReset, children: copy.newThread }), closeAction] });
 }
 //# sourceMappingURL=header.js.map