@jini-ai/chat 0.6.6 → 0.6.7

package/dist/react/hooks/composer-draft-cache.js

@@ -66,6 +66,18 @@ const stagedAttachments = new Map();
 // attachments-only signature: `useComposer` persists the list and never sees a batch id, while
 // `useChatPane` (the one caller that uploads in batches) records the batch here.
 const stagedBatchIds = new Map();
+/**
+ * Sets `key` in one of the in-memory tiers, evicting the oldest-inserted entry first if this would
+ * introduce a new key past {@link MAX_CACHED_CONVERSATION_DRAFTS}.
+ * @complexity Time/space: O(1) amortized.
+ */
+function setBounded(map, { key, value }) {
+    if (!map.has(key) && map.size >= MAX_CACHED_CONVERSATION_DRAFTS) {
+        // `size >= MAX_CACHED_CONVERSATION_DRAFTS > 0`, so there is always a first key to evict.
+        map.delete(map.keys().next().value);
+    }
+    map.set(key, value);
+}
 /**
  * The origin's `localStorage`, or `null` when it cannot be used.
  *
@@ -83,32 +95,29 @@ function storage() {
     }
 }
 /**
- * Reads and validates the stored draft for `conversationId`.
+ * Reads the entry at `prefix + conversationId` and hands its parsed JSON to `decode`.
  *
- * Anything that does not parse as this module's own envelope is treated as foreign or corrupt and
- * deleted rather than returned — a stale format, another tool writing under a colliding key, or a
- * truncated write must not surface as composer text.
+ * Anything `decode` rejects (returns `null` for) is treated as foreign or corrupt and deleted rather
+ * than returned — a stale format, another tool writing under a colliding key, or a truncated write
+ * must not surface as composer state.
  *
- * @returns The stored draft, or `null` when there is none, storage is unavailable, or the entry
+ * @returns The decoded value, or `null` when there is no entry, storage is unavailable, or the entry
  * failed validation.
- * @complexity Time/space: O(n) in the stored draft's length (the JSON parse).
+ * @complexity Time/space: O(n) in the stored entry's length (the JSON parse) plus `decode`.
  */
-function readStoredDraft(conversationId) {
+function readStoredEnvelope(prefix, { conversationId, decode }) {
     const store = storage();
     if (!store)
         return null;
-    const key = `${COMPOSER_DRAFT_STORAGE_PREFIX}${conversationId}`;
+    const key = `${prefix}${conversationId}`;
     try {
         const raw = store.getItem(key);
         if (raw === null)
             return null;
-        const parsed = JSON.parse(raw);
-        const draft = parsed?.d;
-        if (typeof draft !== 'string' || draft === '') {
+        const decoded = decode(JSON.parse(raw));
+        if (decoded === null)
             store.removeItem(key);
-            return null;
-        }
-        return draft;
+        return decoded;
     }
     catch {
         // A parse failure leaves the bad entry behind on purpose when `removeItem` is what threw —
@@ -122,6 +131,22 @@ function readStoredDraft(conversationId) {
         return null;
     }
 }
+/**
+ * Validates a parsed draft envelope.
+ * @returns Its draft, or `null` when it is not this module's envelope or holds a blank draft.
+ * @complexity Time/space: O(1).
+ */
+function decodeStoredDraft(parsed) {
+    const draft = parsed?.d;
+    return typeof draft === 'string' && draft !== '' ? draft : null;
+}
+/**
+ * Reads and validates the stored draft for `conversationId`; see {@link readStoredEnvelope}.
+ * @complexity Time/space: O(n) in the stored draft's length (the JSON parse).
+ */
+function readStoredDraft(conversationId) {
+    return readStoredEnvelope(COMPOSER_DRAFT_STORAGE_PREFIX, { conversationId, decode: decodeStoredDraft });
+}
 /**
  * Deletes every stored draft past the cap, oldest write first, so an operator who abandons drafts
  * in many conversations cannot fill the origin's quota and silently break persistence for the
@@ -138,21 +163,7 @@ function pruneStored(prefix, keep) {
     if (!store)
         return;
     try {
-        const entries = [];
-        for (let i = 0; i < store.length; i += 1) {
-            const key = store.key(i);
-            if (key === null || !key.startsWith(prefix))
-                continue;
-            let at = 0;
-            try {
-                const parsed = JSON.parse(store.getItem(key) ?? '');
-                at = typeof parsed?.t === 'number' ? parsed.t : 0;
-            }
-            catch {
-                at = 0;
-            }
-            entries.push({ key, at });
-        }
+        const entries = storedEntries(store, { prefix });
         if (entries.length <= keep)
             return;
         entries.sort((a, b) => a.at - b.at);
@@ -164,44 +175,78 @@ function pruneStored(prefix, keep) {
     }
 }
 /**
- * Writes or removes the stored copy for `conversationId`.
+ * Every stored key under `prefix`, with its envelope's write timestamp (`0` when the envelope does
+ * not parse or carries none).
+ * @complexity Time/space: O(n) in the number of stored keys.
+ */
+function storedEntries(store, { prefix }) {
+    const entries = [];
+    for (let i = 0; i < store.length; i += 1) {
+        const key = store.key(i);
+        if (key?.startsWith(prefix))
+            entries.push({ key, at: storedTimestamp(store, { key }) });
+    }
+    return entries;
+}
+/**
+ * The write timestamp of the envelope at `key`, or `0` when it cannot be read or parsed.
+ * @complexity Time/space: O(n) in the stored entry's length.
+ */
+function storedTimestamp(store, { key }) {
+    try {
+        // `String(null)` is `'null'`, which parses to `null` and so reads as timestamp `0` — the same
+        // answer a missing entry got before, without a branch for a key `store.key` just returned.
+        const parsed = JSON.parse(String(store.getItem(key)));
+        return typeof parsed?.t === 'number' ? parsed.t : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Writes or removes the stored entry at `prefix + conversationId`.
  *
- * @param draft A blank draft removes the entry. A quota rejection is swallowed: the in-memory tier
- * has already accepted the draft, so the composer keeps working and only reload-survival is lost.
- * @complexity Time O(n) in the draft's length, plus a prune (see {@link pruneStored}) only
- * when this introduces a new key at the cap. Space O(n) in the draft's length.
+ * @param envelope `null` removes the entry. A quota rejection is swallowed: the in-memory tier
+ * has already accepted the value, so the composer keeps working and only reload-survival is lost.
+ * @complexity Time O(n) in the envelope's size, plus a prune (see {@link pruneStored}) only
+ * when this introduces a new key at the cap. Space O(n) in the envelope's size.
  */
-function writeStoredDraft(conversationId, draft) {
+function writeStoredEnvelope(prefix, { conversationId, envelope }) {
     const store = storage();
     if (!store)
         return;
-    const key = `${COMPOSER_DRAFT_STORAGE_PREFIX}${conversationId}`;
+    const key = `${prefix}${conversationId}`;
     try {
-        if (draft === '') {
+        if (envelope === null) {
             store.removeItem(key);
             return;
         }
         if (store.getItem(key) === null)
-            pruneStored(COMPOSER_DRAFT_STORAGE_PREFIX, MAX_CACHED_CONVERSATION_DRAFTS - 1);
-        const envelope = { v: 1, t: Date.now(), d: draft };
+            pruneStored(prefix, MAX_CACHED_CONVERSATION_DRAFTS - 1);
         store.setItem(key, JSON.stringify(envelope));
     }
     catch {
         /* blocked, full, or unusable storage — memory-only is the documented degraded mode */
+        /* (on a removal: blocked storage; the in-memory tier is already correct) */
     }
 }
+/**
+ * Writes or removes the stored copy for `conversationId`.
+ *
+ * @param draft A blank draft removes the entry; see {@link writeStoredEnvelope}.
+ * @complexity Time O(n) in the draft's length; see {@link writeStoredEnvelope}.
+ */
+function writeStoredDraft(conversationId, draft) {
+    const envelope = draft === '' ? null : { v: 1, t: Date.now(), d: draft };
+    writeStoredEnvelope(COMPOSER_DRAFT_STORAGE_PREFIX, { conversationId, envelope });
+}
 /**
  * Records `draft` in the in-memory tier, evicting the oldest-inserted conversation first if this
  * would introduce a new entry past {@link MAX_CACHED_CONVERSATION_DRAFTS}.
  * @complexity Time/space: O(1) amortized.
  */
 function rememberInMemory(conversationId, draft) {
-    if (!drafts.has(conversationId) && drafts.size >= MAX_CACHED_CONVERSATION_DRAFTS) {
-        const oldest = drafts.keys().next().value;
-        if (oldest !== undefined)
-            drafts.delete(oldest);
-    }
-    drafts.set(conversationId, draft);
+    setBounded(drafts, { key: conversationId, value: draft });
 }
 /**
  * Reads the cached draft for `conversationId`, in memory first and storage second.
@@ -239,13 +284,8 @@ export function readCachedDraft({ conversationId }) {
 export function writeCachedDraft({ conversationId, draft }) {
     if (!conversationId)
         return;
-    if (draft.trim() === '') {
-        drafts.delete(conversationId);
-        writeStoredDraft(conversationId, '');
-        return;
-    }
-    rememberInMemory(conversationId, draft);
-    writeStoredDraft(conversationId, draft);
+    rememberCachedDraft({ conversationId: conversationId, draft: draft });
+    writeStoredDraft(conversationId, draft.trim() === '' ? '' : draft);
 }
 /**
  * Stores `draft` for `conversationId` in the in-memory tier only, leaving `localStorage` alone.
@@ -299,11 +339,11 @@ function isChatAttachment(candidate) {
         return false;
     if (kind !== 'image' && kind !== 'file')
         return false;
-    if (size !== undefined && typeof size !== 'number')
-        return false;
-    if (order !== undefined && typeof order !== 'number')
-        return false;
-    return true;
+    return isOptionalNumber(size) && isOptionalNumber(order);
+}
+/** @complexity Time/space: O(1). */
+function isOptionalNumber(value) {
+    return value === undefined || typeof value === 'number';
 }
 /**
  * Reads the stored attachment references (and their upload batch) for `conversationId`.
@@ -317,37 +357,21 @@ function isChatAttachment(candidate) {
  * @complexity Time/space: O(n) in the number of stored references.
  */
 function readStoredAttachments(conversationId) {
-    const store = storage();
-    if (!store)
+    return readStoredEnvelope(COMPOSER_ATTACHMENTS_STORAGE_PREFIX, { conversationId, decode: decodeStoredAttachments });
+}
+/**
+ * Validates a parsed attachments envelope; see {@link readStoredAttachments} for the rules.
+ * @complexity Time/space: O(n) in the number of stored references.
+ */
+function decodeStoredAttachments(parsed) {
+    const list = parsed?.a;
+    const batchId = parsed?.b;
+    if (!Array.isArray(list))
         return null;
-    const key = `${COMPOSER_ATTACHMENTS_STORAGE_PREFIX}${conversationId}`;
-    try {
-        const raw = store.getItem(key);
-        if (raw === null)
-            return null;
-        const parsed = JSON.parse(raw);
-        const list = parsed?.a;
-        const batchId = parsed?.b;
-        if (!Array.isArray(list)) {
-            store.removeItem(key);
-            return null;
-        }
-        const valid = list.filter(isChatAttachment);
-        if (valid.length === 0) {
-            store.removeItem(key);
-            return null;
-        }
-        return { attachments: valid, batchId: typeof batchId === 'string' && batchId !== '' ? batchId : null };
-    }
-    catch {
-        try {
-            store.removeItem(key);
-        }
-        catch {
-            /* storage is unusable; the in-memory tier still serves this conversation */
-        }
+    const valid = list.filter(isChatAttachment);
+    if (valid.length === 0)
         return null;
-    }
+    return { attachments: valid, batchId: typeof batchId === 'string' && batchId !== '' ? batchId : null };
 }
 /**
  * Reads the cached attachment references for `conversationId`, in memory first, storage second.
@@ -407,12 +431,7 @@ export function readCachedAttachmentBatchId({ conversationId }, _options = {}) {
 export function writeCachedAttachmentBatchId({ conversationId, batchId }, _options = {}) {
     if (!conversationId)
         return;
-    if (!stagedBatchIds.has(conversationId) && stagedBatchIds.size >= MAX_CACHED_CONVERSATION_DRAFTS) {
-        const oldest = stagedBatchIds.keys().next().value;
-        if (oldest !== undefined)
-            stagedBatchIds.delete(oldest);
-    }
-    stagedBatchIds.set(conversationId, batchId);
+    setBounded(stagedBatchIds, { key: conversationId, value: batchId });
 }
 /**
  * Stores `attachments` for `conversationId` in both tiers.
@@ -424,38 +443,17 @@ export function writeCachedAttachmentBatchId({ conversationId, batchId }, _optio
 export function writeCachedAttachments({ conversationId, attachments }) {
     if (!conversationId)
         return;
-    const key = `${COMPOSER_ATTACHMENTS_STORAGE_PREFIX}${conversationId}`;
-    const store = storage();
     if (attachments.length === 0) {
         stagedAttachments.delete(conversationId);
         // A sent or cleared turn's batch is spent; the next upload starts a fresh one.
         stagedBatchIds.delete(conversationId);
-        try {
-            store?.removeItem(key);
-        }
-        catch {
-            /* blocked storage; the in-memory tier is already correct */
-        }
-        return;
-    }
-    if (!stagedAttachments.has(conversationId) && stagedAttachments.size >= MAX_CACHED_CONVERSATION_DRAFTS) {
-        const oldest = stagedAttachments.keys().next().value;
-        if (oldest !== undefined)
-            stagedAttachments.delete(oldest);
-    }
-    stagedAttachments.set(conversationId, attachments);
-    if (!store)
+        writeStoredEnvelope(COMPOSER_ATTACHMENTS_STORAGE_PREFIX, { conversationId, envelope: null });
         return;
-    try {
-        if (store.getItem(key) === null)
-            pruneStored(COMPOSER_ATTACHMENTS_STORAGE_PREFIX, MAX_CACHED_CONVERSATION_DRAFTS - 1);
-        const batchId = stagedBatchIds.get(conversationId);
-        const envelope = { v: 1, t: Date.now(), a: attachments, ...(batchId === undefined ? {} : { b: batchId }) };
-        store.setItem(key, JSON.stringify(envelope));
-    }
-    catch {
-        /* blocked, full, or unusable storage — memory-only is the documented degraded mode */
     }
+    setBounded(stagedAttachments, { key: conversationId, value: attachments });
+    const batchId = stagedBatchIds.get(conversationId);
+    const envelope = { v: 1, t: Date.now(), a: attachments, ...(batchId === undefined ? {} : { b: batchId }) };
+    writeStoredEnvelope(COMPOSER_ATTACHMENTS_STORAGE_PREFIX, { conversationId, envelope });
 }
 /**
  * Test-only: empties the cache so test cases cannot leak drafts into each other.

package/dist/react/hooks/composer-history-storage.js

@@ -7,13 +7,13 @@ export function createBrowserComposerHistoryStorage(_required, { storage, prefix
         return storage ?? globalThis.localStorage;
     }
     return {
-        async read({ scope }, _optional = {}) {
+        async read({ scope }, { cap = 100 } = {}) {
             try {
                 const raw = resolveStorage()?.getItem(prefix + encodeURIComponent(scope));
                 if (raw) {
                     const parsed = JSON.parse(raw);
                     if (Array.isArray(parsed)) {
-                        const entries = normalizeComposerHistory({ entries: parsed.filter((value) => typeof value === 'string') });
+                        const entries = normalizeComposerHistory({ entries: parsed.filter((value) => typeof value === 'string') }, { cap });
                         memory.set(scope, entries);
                         return entries;
                     }
@@ -22,10 +22,10 @@ export function createBrowserComposerHistoryStorage(_required, { storage, prefix
             catch {
                 // Storage denial/corruption must not disable draft editing or in-memory recall.
             }
-            return memory.get(scope) ?? [];
+            return normalizeComposerHistory({ entries: memory.get(scope) ?? [] }, { cap });
         },
-        async write({ scope, entries }, _optional = {}) {
-            const normalized = normalizeComposerHistory({ entries });
+        async write({ scope, entries }, { cap = 100 } = {}) {
+            const normalized = normalizeComposerHistory({ entries }, { cap });
             memory.set(scope, normalized);
             try {
                 resolveStorage()?.setItem(prefix + encodeURIComponent(scope), JSON.stringify(normalized));

package/dist/react/hooks/fab-position.js

@@ -116,6 +116,13 @@ export function useFabPosition(options, _optional = {}) {
     const draggingRef = useRef(false);
     const didDragRef = useRef(false);
     const liveRef = useRef(null);
+    /**
+     * Set by `onPointerDown` immediately BEFORE it attaches the document `pointermove`/`pointerup`/
+     * `pointercancel` listeners, and cleared by `handlePointerUp` in the same synchronous step that
+     * detaches them — so whenever either handler below can run, a drag start is recorded. That
+     * invariant is why the handlers read it with a cast rather than an `if (!start) return` guard: the
+     * guard that used to sit there could never be taken.
+     */
     const dragStart = useRef(null);
     /** Bumped to force a re-render on every pointermove and on resize — `liveRef`/`window.innerWidth`
      *  are read directly in `style`'s `useMemo` below, neither of which React tracks as a reactive
@@ -141,8 +148,6 @@ export function useFabPosition(options, _optional = {}) {
     // never depend on state that would force a re-subscribe mid-gesture.
     const handlePointerMove = useCallback((e) => {
         const start = dragStart.current;
-        if (!start)
-            return;
         const dx = e.clientX - start.startX;
         const dy = e.clientY - start.startY;
         if (!draggingRef.current && Math.hypot(dx, dy) > DRAG_THRESHOLD_PX) {
@@ -159,8 +164,6 @@ export function useFabPosition(options, _optional = {}) {
     }, []);
     const handlePointerUp = useCallback((e) => {
         const start = dragStart.current;
-        if (!start)
-            return;
         e.target.releasePointerCapture?.(start.pointerId);
         document.removeEventListener("pointermove", handlePointerMove);
         document.removeEventListener("pointerup", handlePointerUp);

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

@@ -1,20 +1,37 @@
-import type { IsAnsweredCard } from '../../core/index.js';
+import { type ChatRunStatus } from '../../core/messages.js';
+import type { ExtEventGroup } from './useExtEventGroups.js';
+import type { AgentEvent, IsAnsweredCard } from '../../core/index.js';
 export interface AnsweredCards {
+    /** Live rendering state; a terminal run overrides a stale streaming prop. */
+    runStreaming: boolean;
     /** Whether the slot's card was answered. */
     isAnswered(slot: string): boolean;
     /** Records the slot's card as answered. Idempotent. */
-    markAnswered(slot: string): void;
+    markAnswered(slot: string, answerText?: string): void;
+    /** The receipt text takes precedence over the transient delivery text. */
+    answerText(slot: string): string | undefined;
+    /** Whether a user_message event already renders this answer. */
+    isRecorded(slot: string): boolean;
     /** The same answer as `isAnswered`, keyed by an event — for `deriveRunActivity`. Stable while nothing new is answered. */
     isAnsweredCard: IsAnsweredCard;
 }
 /**
  * @param slotOf - Maps an ext event to its render slot (`extEventSlot`).
- * @complexity O(1) per lookup; O(answered cards) space.
+ * @param events - Accepted-input-projected events, including persisted or optimistic answer receipts.
+ * @param runStreaming - Host streaming state, constrained by the message's runStatus.
+ * @param runStatus - Persisted run lifecycle, including terminal status on reload.
+ * @param groups - Groups carrying their original tool id; equal answer text is never identity.
+ * @returns Slot lookups and an idempotent delivery recorder; only that recorder changes React state.
+ * @complexity O(events + groups) projection, O(1) lookups; O(events + answered cards) space.
  */
-export declare function useAnsweredCards({ slotOf }: {
+export declare function useAnsweredCards({ slotOf, events, groups, runStreaming, runStatus }: {
+    runStreaming: boolean;
+    runStatus: ChatRunStatus | undefined;
     slotOf: (card: {
         name: string;
         data: unknown;
     }) => string;
+    events?: readonly AgentEvent[];
+    groups?: readonly ExtEventGroup[];
 }): AnsweredCards;
 //# sourceMappingURL=useAnsweredCards.d.ts.map

package/dist/react/hooks/useAnsweredCards.js

@@ -3,21 +3,48 @@
  *
  * Which of a message's cards the person has already answered, by ext-event slot. A held-open
  * question's tool call stays open after the click while the confirmed work runs, so the event
- * stream alone still reads "waiting for an answer"; the card reports its own delivered answer here
- * and the activity line and countdown clear at once (owner, 2026-10-11).
+ * stream alone can still read "waiting for an answer"; persisted receipts or the card delivery report
+ * clear the activity line and countdown. The receipt owns the bubble once it arrives.
  */
-import { useCallback, useState } from 'react';
+import { useCallback, useMemo, useState } from 'react';
+import { isTerminalRunStatus } from '../../core/messages.js';
+import { acceptedInputEvent } from '../../core/accepted-input.js';
 /**
  * @param slotOf - Maps an ext event to its render slot (`extEventSlot`).
- * @complexity O(1) per lookup; O(answered cards) space.
+ * @param events - Accepted-input-projected events, including persisted or optimistic answer receipts.
+ * @param runStreaming - Host streaming state, constrained by the message's runStatus.
+ * @param runStatus - Persisted run lifecycle, including terminal status on reload.
+ * @param groups - Groups carrying their original tool id; equal answer text is never identity.
+ * @returns Slot lookups and an idempotent delivery recorder; only that recorder changes React state.
+ * @complexity O(events + groups) projection, O(1) lookups; O(events + answered cards) space.
  */
-export function useAnsweredCards({ slotOf }) {
-    const [answered, setAnswered] = useState(() => new Set());
-    const markAnswered = useCallback((slot) => {
-        setAnswered((current) => (current.has(slot) ? current : new Set(current).add(slot)));
+export function useAnsweredCards({ slotOf, events = [], groups = [], runStreaming, runStatus }) {
+    const [answered, setAnswered] = useState(() => new Map());
+    // MOVE: Match by tool identity so receipt replay hides only its own card, even for equal answers.
+    const recorded = useMemo(() => {
+        const receipts = new Map();
+        for (const event of events) {
+            const receipt = acceptedInputEvent({ event });
+            if (receipt?.data.toolUseId)
+                receipts.set(receipt.data.toolUseId, receipt.data.text);
+        }
+        const slots = new Map();
+        for (const group of groups) {
+            const text = group.call?.id === undefined ? undefined : receipts.get(group.call.id);
+            if (text !== undefined)
+                slots.set(group.slot, text);
+        }
+        return slots;
+    }, [events, groups]);
+    const markAnswered = useCallback((slot, answerText) => {
+        setAnswered((current) => (current.has(slot) ? current : new Map(current).set(slot, answerText)));
     }, []);
-    const isAnswered = useCallback((slot) => answered.has(slot), [answered]);
-    const isAnsweredCard = useCallback((card) => answered.has(slotOf(card)), [answered, slotOf]);
-    return { isAnswered, markAnswered, isAnsweredCard };
+    const isAnswered = useCallback((slot) => recorded.has(slot) || answered.has(slot), [answered, recorded]);
+    const answerText = useCallback((slot) => recorded.get(slot) ?? answered.get(slot), [answered, recorded]);
+    const isRecorded = useCallback((slot) => recorded.has(slot), [recorded]);
+    const isAnsweredCard = useCallback((card) => isAnswered(slotOf(card)), [isAnswered, slotOf]);
+    // MOVE: Finished runs must keep orphaned questions closed even when the host still reports streaming.
+    return { isAnswered, markAnswered, isAnsweredCard, answerText, isRecorded,
+        runStreaming: runStreaming && runStatus !== undefined && !isTerminalRunStatus({ status: runStatus }) };
 }
 //# sourceMappingURL=useAnsweredCards.js.map

package/dist/react/hooks/useArtifactStream.js

@@ -14,12 +14,33 @@
  */
 import { useMemo } from 'react';
 import { parseArtifacts, splitStreamingArtifact } from '../../core/index.js';
-function toFile(item) {
-    return { name: item.identifier || item.title || 'artifact', kind: item.artifactType, content: item.content };
+function toItem(base, { registry }) {
+    const file = { name: base.identifier || base.title || 'artifact', kind: base.artifactType, content: base.content };
+    return { ...base, file, match: registry?.resolve({ file }) ?? null };
+}
+/**
+ * Completed artifacts in `head`, oldest first. Only `artifact:start` (for the
+ * metadata) and `artifact:end` (whose `fullContent` is the whole body) are
+ * needed — `artifact:chunk` deltas are already folded into `fullContent`.
+ * `createArtifactParser` never nests and always emits an `artifact:end` with
+ * the same identifier right after its `artifact:start`'s chunks, so `meta` is
+ * always set when an end arrives.
+ */
+function collectCompleted(head, { registry }) {
+    const items = [];
+    let meta = null;
+    for (const ev of parseArtifacts({ content: head })) {
+        if (ev.type === 'artifact:start') {
+            meta = { identifier: ev.identifier, artifactType: ev.artifactType, title: ev.title };
+        }
+        else if (ev.type === 'artifact:end') {
+            items.push(toItem({ ...meta, content: ev.fullContent, status: 'complete' }, { registry }));
+        }
+    }
+    return items;
 }
 export function useArtifactStream({ content }, { registry } = {}) {
     return useMemo(() => {
-        const items = [];
         // `splitStreamingArtifact` is the authority on "is there a trailing,
         // still-open artifact": split first so `parseArtifacts` (a one-shot
         // feed+flush that synthesizes an `artifact:end` for whatever is still
@@ -29,27 +50,12 @@ export function useArtifactStream({ content }, { registry } = {}) {
         // once (wrongly) as "complete" via the synthetic flush, and again (correctly)
         // as "streaming" below.
         const { head, live } = splitStreamingArtifact({ content: content });
-        let current = null;
-        for (const ev of parseArtifacts({ content: head })) {
-            if (ev.type === 'artifact:start') {
-                current = { identifier: ev.identifier, artifactType: ev.artifactType, title: ev.title, content: '' };
-            }
-            else if (ev.type === 'artifact:chunk' && current && current.identifier === ev.identifier) {
-                current.content += ev.delta;
-            }
-            else if (ev.type === 'artifact:end' && current && current.identifier === ev.identifier) {
-                const finished = { ...current, content: ev.fullContent, status: 'complete' };
-                items.push({ ...finished, file: toFile(finished), match: registry?.resolve({ file: toFile(finished) }) ?? null });
-                current = null;
-            }
-        }
+        const items = collectCompleted(head, { registry });
         // A trailing artifact whose close tag hasn't streamed in yet — surfaced
         // separately so a live preview can render mid-generation.
-        if (live) {
-            const streaming = { identifier: live.identifier, artifactType: live.artifactType, title: live.title, content: live.content, status: 'streaming' };
-            items.push({ ...streaming, file: toFile(streaming), match: registry?.resolve({ file: toFile(streaming) }) ?? null });
-        }
-        return { items, current: items.length > 0 ? items[items.length - 1] : null };
+        if (live)
+            items.push(toItem({ ...live, status: 'streaming' }, { registry }));
+        return { items, current: items.at(-1) ?? null };
     }, [content, registry]);
 }
 //# sourceMappingURL=useArtifactStream.js.map

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

@@ -13,6 +13,8 @@ export interface UseComposerOptions {
     /** Scopes recent prompts across conversations. Hosts with multiple users must supply an id. */
     historyScope?: string;
     historyStorage?: ComposerHistoryStoragePort;
+    /** Recall retention; defaults to 100, with existing duplicate collapse. */
+    historyCap?: number;
     initialAgent?: AgentSelection;
     project?: ProjectContextValue;
     composerSlots?: ComposerSlots;
@@ -41,7 +43,25 @@ export interface UseComposerOptions {
      * Captured in a ref, so an inline arrow is safe and will not re-run the restore on every render.
      */
     validateAttachments?: (attachments: readonly ChatAttachment[]) => Promise<readonly ChatAttachment[]>;
+    /**
+     * Where the page-exit signals that flush a pending draft write come from (`pagehide` on the
+     * window, `visibilitychange` to hidden on the document). Defaults to the browser's own
+     * {@link browserPageLifecycle}; `null` means there is no page to leave (a non-DOM renderer runs
+     * effects without `window`), so only unmount, send and switch flush. Captured once at mount.
+     */
+    pageLifecycle?: ComposerPageLifecycle | null;
+}
+/** The page-exit event sources {@link useComposer} listens to, injectable so a host or test can supply its own. */
+export interface ComposerPageLifecycle {
+    readonly window: Pick<Window, 'addEventListener' | 'removeEventListener'>;
+    readonly document: Pick<Document, 'addEventListener' | 'removeEventListener' | 'visibilityState'>;
 }
+/**
+ * The real window/document pair, or `null` when this runtime has no `window` — a non-DOM React
+ * renderer still runs effects, and subscribing there would throw.
+ * @complexity Time/space: O(1).
+ */
+export declare function browserPageLifecycle(): ComposerPageLifecycle | null;
 export interface MentionPopoverState {
     open: boolean;
     query: string;