@constructor-io/constructorio-ui-asa 1.7.2 → 1.9.0

package/lib/mjs/hooks/useAsaResults.js

@@ -1,188 +1,140 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { useCioAsaContext } from './useCioAsaContext';
-import { handleSearchResult, handleMessage, handleFollowUpRefinement, handleServerError, handleStreamEnd, handleStreamError, } from './asaStreamHandlers';
 import useAsaTracking from './useAsaTracking';
+import useChatPersistence from './persistence/useChatPersistence';
+import { startTurn } from './agentStream';
+import { createChatSession, nextMessageId } from '../utils/chatSession';
+import { normalizeItemToProduct } from '../utils/productNormalizer';
+import { isLocalThreadId } from '../utils/chatThreads';
+import useLatest from './useLatest';
 export default function useAsaResults(options) {
-    const [messages, setMessages] = useState([]);
-    const [isStreaming, setIsStreaming] = useState(false);
-    const isStreamingRef = useRef(false);
-    const killSwitchRef = useRef(false);
-    const readerRef = useRef(null);
-    const threadIdRef = useRef(options?.initialThreadId ?? null);
-    const idCounterRef = useRef(0);
-    // The assistant message the in-flight stream is writing into, so `abort` can
-    // settle it without having to guess which message that is.
-    const activeAssistantIdRef = useRef(null);
     const contextValue = useCioAsaContext();
     if (!contextValue) {
         throw new Error('useAsaResults must be used within a CioAsaProvider.');
     }
-    const { cioClient, staticRequestConfigs, callbacks, section } = contextValue;
+    const { cioClient, staticRequestConfigs, callbacks, section, persistence, persistenceScope, persistenceIndex, } = contextValue;
     const { domain } = staticRequestConfigs || {};
     if (!cioClient || !domain) {
         throw new Error('useAsaResults requires a configured cioClient and domain. Check your CioAsaProvider props.');
     }
+    const [messages, setMessages] = useState([]);
+    const [isStreaming, setIsStreaming] = useState(false);
+    const normalizeItemRef = useLatest(options?.normalizeItem);
+    const sessionRef = useRef(null);
+    if (!sessionRef.current) {
+        sessionRef.current = createChatSession(options?.initialThreadId, (item) => (normalizeItemRef.current ?? normalizeItemToProduct)(item));
+    }
+    const session = sessionRef.current;
+    const turnRef = useRef(null);
     const tracking = useAsaTracking({
         tracker: cioClient.tracker,
         section,
-        threadId: threadIdRef.current ?? undefined,
+        threadId: session.serverThreadId ?? undefined,
     });
-    const trackingRef = useRef(tracking);
-    trackingRef.current = tracking;
-    const callbacksRef = useRef(callbacks);
-    callbacksRef.current = callbacks;
-    const staticRequestConfigsRef = useRef(staticRequestConfigs);
-    staticRequestConfigsRef.current = staticRequestConfigs;
-    /**
-     * Stops the in-flight stream. The kill switch is raised *before* cancelling because
-     * cancelling makes the pending `reader.read()` resolve `{ done: true }` — identical
-     * to a stream that ended on its own. Without the flag already set, the read loop
-     * would take the end-of-stream branch and report a load that never finished.
-     *
-     * Deliberately touches no state, so the unmount cleanup can share it.
-     */
-    const teardownStream = useCallback(() => {
-        killSwitchRef.current = true;
-        if (readerRef.current) {
-            readerRef.current.cancel();
-            readerRef.current = null;
-        }
+    const trackingRef = useLatest(tracking);
+    const callbacksRef = useLatest(callbacks);
+    const staticRequestConfigsRef = useLatest(staticRequestConfigs);
+    /** Stops this tab's stream, if any. `readAgentStream` settles its `done` without touching state. */
+    const cancelStream = useCallback(() => {
+        turnRef.current?.cancel();
+        turnRef.current = null;
     }, []);
-    const nextMessageId = useCallback(() => {
-        idCounterRef.current += 1;
-        return `msg-${idCounterRef.current}-${Date.now()}`;
-    }, []);
-    const sendMessage = useCallback((text, source = 'input') => {
+    const store = useChatPersistence({
+        store: persistence,
+        scope: persistenceScope,
+        index: persistenceIndex,
+        session,
+        initialThreadId: options?.initialThreadId,
+        messages,
+        setMessages,
+        isStreaming,
+        setIsStreaming,
+        turnRef,
+        cancelStream,
+    });
+    const { beginTurn, screenOwner } = store;
+    useEffect(() => cancelStream, [cancelStream]);
+    const sendToCurrentThread = useCallback((text, source) => {
         const intent = text.trim();
-        if (!intent || isStreamingRef.current)
+        if (!intent || session.isStreaming || session.foreignInFlight)
             return;
-        trackingRef.current.trackSubmit(intent);
+        beginTurn();
+        trackingRef.current.trackSubmit(intent, source);
         callbacksRef.current?.onAssistantSubmit?.({ intent, source });
         const userMessage = {
-            id: nextMessageId(),
+            id: nextMessageId(session),
             role: 'user',
             text: intent,
             status: 'done',
         };
         const assistantMessage = {
-            id: nextMessageId(),
+            id: nextMessageId(session),
             role: 'assistant',
             text: '',
             groups: [],
             status: 'loading',
             intent,
         };
-        activeAssistantIdRef.current = assistantMessage.id;
         setMessages((prev) => [...prev, userMessage, assistantMessage]);
         setIsStreaming(true);
-        isStreamingRef.current = true;
-        killSwitchRef.current = false;
-        // `intent` is passed as the first argument and `threadId` is managed per-stream
-        // below, so both are stripped here. Everything else configured on the provider
-        // (filters, guard, numResultsPerEvent, numResultEvents, qsParam,
-        // preFilterExpression, fmtOptions, ...) is forwarded to the agent as-is.
+        session.isStreaming = true;
         const agentParams = { ...staticRequestConfigsRef.current };
         delete agentParams.intent;
         delete agentParams.threadId;
         const stream = cioClient.agent.getAgentResultsStream(intent, {
             ...agentParams,
             domain,
-            ...(threadIdRef.current && { threadId: threadIdRef.current }),
+            ...(session.serverThreadId && { threadId: session.serverThreadId }),
         });
-        const reader = stream.getReader();
-        readerRef.current = reader;
-        // Mutable per-stream state kept on an object so the closures below don't capture
-        // reassigned loop-locals (which eslint's no-loop-func forbids).
-        const streamState = {
-            pendingGroup: null,
-            intentResultId: undefined,
-            loadStartFired: false,
-            groupCount: 0,
-        };
-        const patchAssistant = (patch) => {
-            setMessages((prev) => prev.map((m) => (m.id === assistantMessage.id ? { ...m, ...patch } : m)));
-        };
-        const fireLoadStart = () => {
-            if (streamState.loadStartFired)
-                return;
-            streamState.loadStartFired = true;
-            const args = { intent, intentResultId: streamState.intentResultId };
-            trackingRef.current.trackResultLoadStarted(args);
-            callbacksRef.current?.onResultLoadStart?.(args);
-        };
+        turnRef.current = startTurn(stream, assistantMessage, screenOwner, {
+            onLoadStart: (intentResultId) => {
+                const args = { intent, intentResultId };
+                trackingRef.current.trackResultLoadStarted(args);
+                callbacksRef.current?.onResultLoadStart?.(args);
+            },
+            onFinish: ({ threadId, ...result }) => {
+                const args = { intent, ...result };
+                // The turn may have finished in the background, after the chat moved to another thread.
+                trackingRef.current.trackResultLoadFinished({ ...args, threadId });
+                callbacksRef.current?.onResultLoadFinish?.(args);
+            },
+        });
+    }, [
+        cioClient,
+        domain,
+        session,
+        beginTurn,
+        screenOwner,
+        trackingRef,
+        callbacksRef,
+        staticRequestConfigsRef,
+    ]);
+    const { newThread, switchThread } = store;
+    /**
+     * Sends `text`. With `threadId`, first moves to that conversation, loading it from storage
+     * when persistence has it and otherwise continuing it on the server with an empty screen.
+     */
+    const sendMessage = useCallback((text, source = 'input', { threadId } = {}) => {
+        if (!threadId ||
+            threadId === session.serverThreadId ||
+            threadId === session.storageThreadId) {
+            sendToCurrentThread(text, source);
+            return;
+        }
         (async () => {
-            try {
-                // eslint-disable-next-line no-await-in-loop
-                while (!killSwitchRef.current) {
-                    // eslint-disable-next-line no-await-in-loop
-                    const res = await reader.read();
-                    if (killSwitchRef.current)
-                        break;
-                    if (res.done) {
-                        handleStreamEnd(assistantMessage.id, setMessages);
-                        const finishArgs = {
-                            intent,
-                            searchResultCount: streamState.groupCount,
-                            intentResultId: streamState.intentResultId,
-                        };
-                        trackingRef.current.trackResultLoadFinished(finishArgs);
-                        callbacksRef.current?.onResultLoadFinish?.(finishArgs);
-                        break;
-                    }
-                    const { type, data } = res.value;
-                    // `intent_result_id` is shared across the stream; capture it from the first
-                    // event that carries it so load-start/finish can attribute correctly.
-                    if (!streamState.intentResultId && data?.intent_result_id) {
-                        streamState.intentResultId = data.intent_result_id;
-                        patchAssistant({ intentResultId: streamState.intentResultId });
-                    }
-                    if (type === 'start') {
-                        if (data?.thread_id) {
-                            threadIdRef.current = data.thread_id;
-                            patchAssistant({ threadId: data.thread_id });
-                        }
-                        fireLoadStart();
-                    }
-                    else if (type === 'group') {
-                        streamState.pendingGroup = {
-                            display_name: data?.display_name ?? data?.group ?? '',
-                            value: data?.value ?? data?.group ?? '',
-                        };
-                    }
-                    else if (type === 'search_result') {
-                        fireLoadStart();
-                        streamState.groupCount += 1;
-                        streamState.pendingGroup = handleSearchResult(data, streamState.pendingGroup, assistantMessage.id, setMessages);
-                    }
-                    else if (type === 'message') {
-                        fireLoadStart();
-                        handleMessage(data, assistantMessage.id, setMessages);
-                    }
-                    else if (type === 'follow_up_refinement') {
-                        fireLoadStart();
-                        handleFollowUpRefinement(data, assistantMessage.id, setMessages);
-                    }
-                    else if (type === 'server_error') {
-                        handleServerError(assistantMessage.id, setMessages);
-                        break;
-                    }
-                }
-            }
-            catch {
-                handleStreamError(assistantMessage.id, setMessages);
-            }
-            finally {
-                if (readerRef.current === reader) {
-                    reader.cancel();
-                    readerRef.current = null;
-                    activeAssistantIdRef.current = null;
-                    setIsStreaming(false);
-                    isStreamingRef.current = false;
-                }
+            if (persistence)
+                await switchThread(threadId);
+            else
+                newThread();
+            // A turn that started meanwhile (or one still streaming in the background) owns the screen.
+            if (session.isStreaming || session.foreignInFlight)
+                return;
+            if (!session.serverThreadId && !isLocalThreadId(threadId)) {
+                session.serverThreadId = threadId;
             }
+            sendToCurrentThread(text, source);
         })();
-    }, [cioClient, domain, nextMessageId]);
-    useEffect(() => () => teardownStream(), [teardownStream]);
+    }, [session, persistence, newThread, switchThread, sendToCurrentThread]);
     /**
      * Cancels the in-flight request while keeping the conversation: the partial reply is
      * settled as `done` (so the typing indicator stops and streamed text survives) and the
@@ -199,13 +151,12 @@ export default function useAsaResults(options) {
      * `assistant_result_load_started` with no matching finished event.
      */
     const abort = useCallback(() => {
-        if (!isStreamingRef.current)
+        if (!session.isStreaming)
             return;
-        teardownStream();
+        const abortedId = turnRef.current?.assistantId;
+        cancelStream();
+        session.isStreaming = false;
         setIsStreaming(false);
-        isStreamingRef.current = false;
-        const abortedId = activeAssistantIdRef.current;
-        activeAssistantIdRef.current = null;
         if (abortedId) {
             setMessages((prev) => prev.flatMap((msg) => {
                 if (msg.id !== abortedId)
@@ -215,14 +166,20 @@ export default function useAsaResults(options) {
                 return [{ ...msg, status: 'done' }];
             }));
         }
-    }, [teardownStream]);
-    const clearHistory = useCallback(() => {
-        teardownStream();
-        threadIdRef.current = null;
-        activeAssistantIdRef.current = null;
-        setMessages([]);
-        setIsStreaming(false);
-        isStreamingRef.current = false;
-    }, [teardownStream]);
-    return { messages, sendMessage, isStreaming, abort, clearHistory };
+        // With persistence on, the cancelled turn is stored as it stands.
+        session.dirty = true;
+    }, [session, cancelStream]);
+    return {
+        messages,
+        sendMessage,
+        isStreaming: isStreaming || store.foreignInFlight,
+        canAbort: isStreaming,
+        abort,
+        clearHistory: store.clearHistory,
+        isHydrating: store.isHydrating,
+        threads: store.threads,
+        activeThreadId: store.activeThreadId,
+        newThread,
+        switchThread,
+    };
 }

package/lib/mjs/hooks/useAsaTracking.js

@@ -1,5 +1,14 @@
 import { useCallback, useMemo } from 'react';
+/** Beacon `source` values, aligned with the ones the behavioral-actions API documents. */
+const BEACON_SUBMIT_SOURCES = {
+    input: 'input',
+    suggestion: 'suggestion',
+    refinement: 'follow_up',
+    // A prompt the host page sent, typically a suggested question clicked outside the chat.
+    external: 'suggestion',
+};
 const NOOP_TRACKING = {
+    trackAgentButtonClick: () => { },
     trackSubmit: () => { },
     trackResultLoadStarted: () => { },
     trackResultLoadFinished: () => { },
@@ -13,31 +22,45 @@ const NOOP_TRACKING = {
  * Mirrors the tracking-hook pattern used by constructorio-ui-pia.
  */
 export default function useAsaTracking({ tracker, section, threadId, }) {
-    const assistant = tracker;
     const base = useMemo(() => ({
         ...(section && { section }),
         ...(threadId && { threadId }),
     }), [section, threadId]);
-    const trackSubmit = useCallback((intent) => {
-        assistant?.trackAssistantSubmit({ intent, ...base });
-    }, [assistant, base]);
+    const trackAgentButtonClick = useCallback(({ mode, agentDomain, positionOnPage, pageType, instanceId }) => {
+        tracker?.trackAgentButtonClick?.({
+            mode,
+            agentDomain,
+            ...(positionOnPage && { positionOnPage }),
+            ...(pageType && { pageType }),
+            ...(instanceId && { instanceId }),
+            ...(section && { section }),
+        });
+    }, [tracker, section]);
+    const trackSubmit = useCallback((intent, source) => {
+        tracker?.trackAssistantSubmit({
+            intent,
+            ...(source && { source: BEACON_SUBMIT_SOURCES[source] }),
+            ...base,
+        });
+    }, [tracker, base]);
     const trackResultLoadStarted = useCallback(({ intent, intentResultId }) => {
-        assistant?.trackAssistantResultLoadStarted({
+        tracker?.trackAssistantResultLoadStarted({
             intent,
             ...(intentResultId && { intentResultId }),
             ...base,
         });
-    }, [assistant, base]);
-    const trackResultLoadFinished = useCallback(({ intent, searchResultCount, intentResultId }) => {
-        assistant?.trackAssistantResultLoadFinished({
+    }, [tracker, base]);
+    const trackResultLoadFinished = useCallback(({ intent, searchResultCount, intentResultId, threadId: turnThreadId, }) => {
+        tracker?.trackAssistantResultLoadFinished({
             intent,
             searchResultCount,
             ...(intentResultId && { intentResultId }),
             ...base,
+            ...(turnThreadId && { threadId: turnThreadId }),
         });
-    }, [assistant, base]);
+    }, [tracker, base]);
     const trackResultClick = useCallback(({ intent, searchResultId, intentResultId, itemId, itemName, variationId, }) => {
-        assistant?.trackAssistantResultClick({
+        tracker?.trackAssistantResultClick({
             intent,
             searchResultId,
             ...(intentResultId && { intentResultId }),
@@ -46,9 +69,9 @@ export default function useAsaTracking({ tracker, section, threadId, }) {
             ...(variationId && { variationId }),
             ...base,
         });
-    }, [assistant, base]);
+    }, [tracker, base]);
     const trackResultView = useCallback(({ intent, searchResultId, numResultsViewed, intentResultId, items }) => {
-        assistant?.trackAssistantResultView({
+        tracker?.trackAssistantResultView({
             intent,
             searchResultId,
             numResultsViewed,
@@ -56,9 +79,9 @@ export default function useAsaTracking({ tracker, section, threadId, }) {
             ...(items && items.length > 0 && { items }),
             ...base,
         });
-    }, [assistant, base]);
+    }, [tracker, base]);
     const trackSearchSubmit = useCallback(({ intent, searchTerm, userInput, searchResultId, intentResultId, groupId, }) => {
-        assistant?.trackAssistantSearchSubmit({
+        tracker?.trackAssistantSearchSubmit({
             intent,
             searchTerm,
             userInput,
@@ -67,11 +90,12 @@ export default function useAsaTracking({ tracker, section, threadId, }) {
             ...(groupId && { groupId }),
             ...base,
         });
-    }, [assistant, base]);
+    }, [tracker, base]);
     return useMemo(() => {
-        if (!assistant)
+        if (!tracker)
             return NOOP_TRACKING;
         return {
+            trackAgentButtonClick,
             trackSubmit,
             trackResultLoadStarted,
             trackResultLoadFinished,
@@ -80,7 +104,8 @@ export default function useAsaTracking({ tracker, section, threadId, }) {
             trackSearchSubmit,
         };
     }, [
-        assistant,
+        tracker,
+        trackAgentButtonClick,
         trackSubmit,
         trackResultLoadStarted,
         trackResultLoadFinished,

package/lib/mjs/hooks/useIsMounted.js

@@ -0,0 +1,12 @@
+import { useEffect, useRef } from 'react';
+/** A ref that is `true` while mounted, for async work that must not land after unmount. */
+export default function useIsMounted() {
+    const ref = useRef(true);
+    useEffect(() => {
+        ref.current = true;
+        return () => {
+            ref.current = false;
+        };
+    }, []);
+    return ref;
+}

package/lib/mjs/hooks/useLatest.js

@@ -0,0 +1,7 @@
+import { useRef } from 'react';
+/** A ref that always holds the latest `value`, for async code that must not read stale props. */
+export default function useLatest(value) {
+    const ref = useRef(value);
+    ref.current = value;
+    return ref;
+}

package/lib/mjs/hooks/useViewportTracking.js

@@ -1,12 +1,12 @@
 import { useCallback, useEffect, useRef } from 'react';
+import useLatest from './useLatest';
 /**
  * Fires `onView` once when the observed element scrolls into the viewport, modeling a
  * per-pod `assistant_search_result_view` impression. Unlike the PIA widget-level view
  * tracker, this fires a single impression per pod (not repeated enter/exit cycles).
  */
 export default function useViewportTracking({ onView, enabled = true, }) {
-    const onViewRef = useRef(onView);
-    onViewRef.current = onView;
+    const onViewRef = useLatest(onView);
     const firedRef = useRef(false);
     const cleanupRef = useRef(null);
     const ref = useCallback((node) => {
@@ -27,7 +27,7 @@ export default function useViewportTracking({ onView, enabled = true, }) {
         }, { threshold: 0.5 });
         observer.observe(node);
         cleanupRef.current = () => observer.disconnect();
-    }, [enabled]);
+    }, [enabled, onViewRef]);
     useEffect(() => () => {
         if (cleanupRef.current)
             cleanupRef.current();

package/lib/mjs/index.js

@@ -10,5 +10,6 @@ export { default as useAsaTracking } from './hooks/useAsaTracking';
 export { default as useCioAsaContext } from './hooks/useCioAsaContext';
 // Utils
 export { normalizeItemToProduct } from './utils/productNormalizer';
+export { clearPersistedConversations } from './utils/localStoragePersistence';
 // Re-exported client value from the JS client (used to construct/type a cioClient)
 export { ConstructorIOClient } from './types';

package/lib/mjs/utils/chatRecordValidation.js

@@ -0,0 +1,51 @@
+import { PERSISTED_CHAT_VERSION } from './chatThreads';
+const MESSAGE_ROLES = new Set(['user', 'assistant']);
+const MESSAGE_STATUSES = new Set(['idle', 'loading', 'streaming', 'done', 'error']);
+function isProduct(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const p = value;
+    return typeof p.id === 'string' && typeof p.name === 'string';
+}
+function isResultGroup(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const g = value;
+    return (Boolean(g.group) &&
+        typeof g.group === 'object' &&
+        typeof g.group.display_name === 'string' &&
+        Array.isArray(g.searchResults) &&
+        g.searchResults.every((r) => Boolean(r) && typeof r === 'object') &&
+        (g.products === undefined || (Array.isArray(g.products) && g.products.every(isProduct))));
+}
+function isRefinement(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const r = value;
+    return (typeof r.question === 'string' &&
+        Array.isArray(r.options) &&
+        r.options.every((o) => typeof o === 'string'));
+}
+function isChatMessage(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const m = value;
+    return (typeof m.id === 'string' &&
+        MESSAGE_ROLES.has(m.role) &&
+        typeof m.text === 'string' &&
+        MESSAGE_STATUSES.has(m.status) &&
+        (m.groups === undefined || (Array.isArray(m.groups) && m.groups.every(isResultGroup))) &&
+        (m.refinement === undefined || isRefinement(m.refinement)));
+}
+export default function isPersistedChat(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const chat = value;
+    return (chat.version === PERSISTED_CHAT_VERSION &&
+        typeof chat.threadId === 'string' &&
+        Array.isArray(chat.messages) &&
+        chat.messages.every(isChatMessage) &&
+        typeof chat.createdAt === 'number' &&
+        typeof chat.updatedAt === 'number' &&
+        (chat.owner === undefined || typeof chat.owner === 'string'));
+}

package/lib/mjs/utils/chatSession.js

@@ -0,0 +1,86 @@
+import { PERSISTED_CHAT_VERSION, compactMessages, createLocalThreadId, getTabId, isLocalThreadId, nextMessageCounter, randomId, } from './chatThreads';
+import { normalizeItemToProduct } from './productNormalizer';
+export function createChatSession(initialThreadId, normalizeItem = normalizeItemToProduct) {
+    return {
+        normalizeItem,
+        serverThreadId: initialThreadId && !isLocalThreadId(initialThreadId) ? initialThreadId : null,
+        storageThreadId: null,
+        orphanIds: [],
+        createdAt: null,
+        lastSyncedAt: 0,
+        dirty: false,
+        interacted: false,
+        loadRequest: 0,
+        isStreaming: false,
+        foreignInFlight: false,
+        idCounter: 0,
+        idSuffix: randomId().slice(0, 6),
+    };
+}
+/** Forget the current conversation. Returns the id it was stored under, if any. */
+export function resetConversation(session) {
+    const storedId = session.storageThreadId;
+    session.serverThreadId = null;
+    session.storageThreadId = null;
+    session.orphanIds = [];
+    session.createdAt = null;
+    session.lastSyncedAt = 0;
+    session.dirty = false;
+    session.loadRequest += 1;
+    session.isStreaming = false;
+    session.foreignInFlight = false;
+    return storedId;
+}
+export function nextMessageId(session) {
+    session.idCounter += 1;
+    return `msg-${session.idCounter}-${Date.now()}-${session.idSuffix}`;
+}
+/** Whether `messageId` was minted by this session rather than by another tab. */
+export function isOwnMessage(session, messageId) {
+    return messageId.endsWith(`-${session.idSuffix}`);
+}
+/** Makes a stored conversation the one this session continues. */
+export function adoptStoredChat(session, chat) {
+    session.storageThreadId = chat.threadId;
+    session.createdAt = chat.createdAt;
+    session.serverThreadId = isLocalThreadId(chat.threadId) ? null : chat.threadId;
+    session.idCounter = nextMessageCounter(chat.messages);
+    session.lastSyncedAt = chat.updatedAt;
+}
+/** A copy that keeps the conversation `session` holds while `session` itself moves on. */
+export function forkSession(session) {
+    return { ...session, orphanIds: [...session.orphanIds] };
+}
+/** Makes `session` continue the conversation `from` kept, showing `messages`. */
+export function adoptSession(session, from, messages) {
+    session.serverThreadId = from.serverThreadId;
+    session.storageThreadId = from.storageThreadId;
+    session.orphanIds = [...from.orphanIds];
+    session.createdAt = from.createdAt;
+    session.lastSyncedAt = from.lastSyncedAt;
+    session.idCounter = nextMessageCounter(messages);
+}
+/** Builds the record to write and moves the session onto its key; `staleIds` are the records to retire once stored. */
+export function prepareSnapshot(session, messages, now = Date.now()) {
+    const previousId = session.storageThreadId;
+    const threadId = session.serverThreadId ?? previousId ?? createLocalThreadId();
+    const staleIds = [previousId !== threadId ? previousId : null, ...session.orphanIds].filter((id) => id !== null && id !== threadId);
+    // Strictly increasing so other tabs read a same-millisecond save as newer.
+    const updatedAt = Math.max(now, session.lastSyncedAt + 1);
+    const createdAt = session.createdAt ?? updatedAt;
+    session.storageThreadId = threadId;
+    session.orphanIds = [];
+    session.createdAt = createdAt;
+    session.lastSyncedAt = updatedAt;
+    return {
+        staleIds: Array.from(new Set(staleIds)),
+        snapshot: {
+            version: PERSISTED_CHAT_VERSION,
+            threadId,
+            messages: compactMessages(messages, session.normalizeItem),
+            createdAt,
+            updatedAt,
+            owner: getTabId(),
+        },
+    };
+}