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

package/lib/cjs/utils/localStoragePersistence.js

@@ -0,0 +1,391 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sharedLocalStoragePersistence = exports.createLocalStoragePersistence = exports.clearPersistedConversations = exports.persistenceNamespace = exports.storageAreaFor = exports.shopperId = exports.isGuest = void 0;
+const tslib_1 = require("tslib");
+const chatThreads_1 = require("./chatThreads");
+const chatRecordValidation_1 = tslib_1.__importDefault(require("./chatRecordValidation"));
+/** Keeps the last `maxTurns` user/assistant pairs, always starting on a user message. */
+function trimToTurns(messages, maxTurns) {
+    if (maxTurns <= 0)
+        return [];
+    let trimmed = Number.isFinite(maxTurns) ? messages.slice(-maxTurns * 2) : messages;
+    while (trimmed.length && trimmed[0].role !== 'user')
+        trimmed = trimmed.slice(1);
+    return trimmed;
+}
+// Web Locks where available; elsewhere the cycle runs synchronously.
+function withStorageLock(name, fn) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const locks = typeof navigator !== 'undefined' ? navigator.locks : undefined;
+        if (!(locks === null || locks === void 0 ? void 0 : locks.request)) {
+            fn();
+            return;
+        }
+        let ran = false;
+        try {
+            yield locks.request(name, () => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                ran = true;
+                fn();
+            }));
+        }
+        catch (_a) {
+            if (!ran)
+                fn();
+        }
+    });
+}
+/** The storage to use, or `null` when none is available (server, or access blocked). */
+function resolveStorage(storage, area) {
+    if (storage)
+        return storage;
+    try {
+        if (typeof window === 'undefined')
+            return null;
+        return area === 'session' ? window.sessionStorage : window.localStorage;
+    }
+    catch (_a) {
+        return null;
+    }
+}
+/** No user id, or an empty one: the conversation belongs to a guest. */
+const isGuest = (userId) => userId == null || userId === '';
+exports.isGuest = isGuest;
+/** The id the client and storage use: `undefined` for a guest (no id, `null` or empty). */
+const shopperId = (userId) => (0, exports.isGuest)(userId) ? undefined : String(userId);
+exports.shopperId = shopperId;
+/** Guests live in `sessionStorage`, so their history ends with the tab; shoppers keep theirs in `localStorage`. */
+function storageAreaFor(userId) {
+    return (0, exports.isGuest)(userId) ? 'session' : 'local';
+}
+exports.storageAreaFor = storageAreaFor;
+/** Namespace the provider stores under: api key, domain and, for a signed-in shopper, the user id. */
+function persistenceNamespace(parts) {
+    var _a;
+    return [parts.apiKey, (_a = parts.domain) !== null && _a !== void 0 ? _a : 'default', (0, exports.shopperId)(parts.userId)]
+        .filter((part) => part !== undefined)
+        .map(encodeURIComponent)
+        .join(':');
+}
+exports.persistenceNamespace = persistenceNamespace;
+function storageKeyFor(key, namespace) {
+    return [key, `v${chatThreads_1.PERSISTED_CHAT_VERSION}`, namespace].filter(Boolean).join(':');
+}
+const emptyStored = () => ({
+    version: chatThreads_1.PERSISTED_CHAT_VERSION,
+    threads: {},
+    deleted: {},
+});
+function parseStored(raw) {
+    var _a;
+    if (!raw)
+        return emptyStored();
+    try {
+        const parsed = JSON.parse(raw);
+        if ((parsed === null || parsed === void 0 ? void 0 : parsed.version) !== chatThreads_1.PERSISTED_CHAT_VERSION || !parsed.threads)
+            return emptyStored();
+        const threads = Object.fromEntries(Object.entries(parsed.threads).filter(([, chat]) => (0, chatRecordValidation_1.default)(chat)));
+        const deleted = Object.fromEntries(Object.entries((_a = parsed.deleted) !== null && _a !== void 0 ? _a : {}).filter(([, at]) => typeof at === 'number'));
+        return { version: chatThreads_1.PERSISTED_CHAT_VERSION, threads, deleted };
+    }
+    catch (_b) {
+        return emptyStored();
+    }
+}
+function readItem(storage, key) {
+    try {
+        return storage.getItem(key);
+    }
+    catch (_a) {
+        return null;
+    }
+}
+/**
+ * Deletes every stored conversation of one shopper, or of the guest without `userId`; open tabs
+ * follow. Resolves once the deletion is recorded.
+ */
+function clearPersistedConversations(options) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const { apiKey, domain = 'chatbot', userId, storage: storageOption } = options;
+        const storage = resolveStorage(storageOption, storageAreaFor(userId));
+        if (!storage)
+            return;
+        const key = storageKeyFor(chatThreads_1.DEFAULT_PERSISTENCE_KEY, persistenceNamespace({ apiKey, domain, userId }));
+        let cleared = false;
+        // Under the store's lock, and as tombstones rather than a bare removal: a save still queued in
+        // some tab, holding a copy of a thread, must find it deleted instead of writing it back.
+        yield withStorageLock(key, () => {
+            var _a;
+            try {
+                const raw = readItem(storage, key);
+                if (raw === null) {
+                    cleared = true;
+                    return;
+                }
+                const current = parseStored(raw);
+                const now = Date.now();
+                const deleted = Object.keys(current.threads).reduce((all, threadId) => (Object.assign(Object.assign({}, all), { [threadId]: now })), (_a = current.deleted) !== null && _a !== void 0 ? _a : {});
+                if (Object.keys(deleted).length === 0)
+                    storage.removeItem(key);
+                else
+                    storage.setItem(key, JSON.stringify(Object.assign(Object.assign({}, emptyStored()), { deleted })));
+                cleared = true;
+            }
+            catch (_b) {
+                /* storage unavailable */
+            }
+        });
+        if (!cleared)
+            return;
+        // Other tabs get a native storage event; this tab does not, so dispatch one for a mounted chat.
+        if (typeof window === 'undefined' || typeof StorageEvent === 'undefined')
+            return;
+        try {
+            window.dispatchEvent(new StorageEvent('storage', { key, storageArea: storage }));
+        }
+        catch (_a) {
+            /* a non-Storage `storage` option cannot be attached to the event */
+        }
+    });
+}
+exports.clearPersistedConversations = clearPersistedConversations;
+/** Conversation store on top of `localStorage`; one key per namespace, merged across tabs. */
+function createLocalStoragePersistence(options = {}) {
+    const { key = chatThreads_1.DEFAULT_PERSISTENCE_KEY, namespace, ttlMs = chatThreads_1.DEFAULT_PERSISTENCE_TTL_MS, maxTurns = Infinity, maxThreads = Infinity, storageArea = 'local', storage: storageOption, } = options;
+    const storageKey = storageKeyFor(key, namespace);
+    const readRaw = (storage) => readItem(storage, storageKey);
+    // One sync reads the same key several times; parse and validate the blob once per distinct value.
+    let lastParsed = null;
+    const parse = (raw) => {
+        var _a;
+        if (!raw)
+            return emptyStored();
+        if ((lastParsed === null || lastParsed === void 0 ? void 0 : lastParsed.raw) !== raw)
+            lastParsed = { raw, data: parseStored(raw) };
+        const cutoff = Date.now() - ttlMs;
+        const { data } = lastParsed;
+        return {
+            version: chatThreads_1.PERSISTED_CHAT_VERSION,
+            threads: Object.fromEntries(Object.entries(data.threads).filter(([, chat]) => chat.updatedAt >= cutoff)),
+            deleted: Object.fromEntries(Object.entries((_a = data.deleted) !== null && _a !== void 0 ? _a : {}).filter(([, at]) => at >= cutoff)),
+        };
+    };
+    const read = () => {
+        const storage = resolveStorage(storageOption, storageArea);
+        return parse(storage ? readRaw(storage) : null);
+    };
+    const sortedThreads = (data) => Object.values(data.threads).sort((a, b) => b.updatedAt - a.updatedAt);
+    const tryWrite = (storage, data) => {
+        try {
+            storage.setItem(storageKey, JSON.stringify(data));
+            return true;
+        }
+        catch (_a) {
+            return false;
+        }
+    };
+    const remove = (storage) => {
+        try {
+            storage.removeItem(storageKey);
+        }
+        catch (_a) {
+            /* ignore */
+        }
+    };
+    const isEmpty = (data) => { var _a; return Object.keys(data.threads).length === 0 && Object.keys((_a = data.deleted) !== null && _a !== void 0 ? _a : {}).length === 0; };
+    // Retries without tombstones, oldest first: the last thing to shed, see `write`.
+    const tryWriteShedding = (storage, data) => {
+        var _a, _b;
+        if (tryWrite(storage, data))
+            return true;
+        const oldestFirst = Object.entries((_a = data.deleted) !== null && _a !== void 0 ? _a : {})
+            .sort((a, b) => a[1] - b[1])
+            .map(([id]) => id);
+        let next = data;
+        for (let i = 0; i < oldestFirst.length; i += 1) {
+            const _c = (_b = next.deleted) !== null && _b !== void 0 ? _b : {}, _d = oldestFirst[i], shed = _c[_d], deleted = tslib_1.__rest(_c, [typeof _d === "symbol" ? _d : _d + ""]);
+            next = Object.assign(Object.assign({}, next), { deleted });
+            if (tryWrite(storage, next))
+                return true;
+        }
+        return false;
+    };
+    // A tombstone is the only thing stopping another tab from writing a deleted thread back, while an
+    // evicted thread is written back by the tab holding it. So when storage is full, shed other
+    // threads oldest first, then the saved thread's oldest turns, and only then tombstones.
+    const write = (storage, data, priorityThreadId) => {
+        if (isEmpty(data)) {
+            remove(storage);
+            return;
+        }
+        if (tryWrite(storage, data))
+            return;
+        const priority = priorityThreadId ? data.threads[priorityThreadId] : undefined;
+        const oldestFirst = sortedThreads(data)
+            .filter((chat) => chat.threadId !== (priority === null || priority === void 0 ? void 0 : priority.threadId))
+            .reverse();
+        let next = data;
+        for (let i = 0; i < oldestFirst.length; i += 1) {
+            const _a = next.threads, _b = oldestFirst[i].threadId, evicted = _a[_b], threads = tslib_1.__rest(_a, [typeof _b === "symbol" ? _b : _b + ""]);
+            next = Object.assign(Object.assign({}, next), { threads });
+            if (tryWrite(storage, next))
+                return;
+        }
+        if (!priority) {
+            // Not even the tombstones fit without the threads; keep the threads rather than wipe them.
+            if (Object.keys(data.threads).length === 0)
+                remove(storage);
+            else
+                tryWriteShedding(storage, data);
+            return;
+        }
+        let chat = priority;
+        while (chat.messages.length > 2) {
+            chat = Object.assign(Object.assign({}, chat), { messages: trimToTurns(chat.messages.slice(2), maxTurns) });
+            next = Object.assign(Object.assign({}, next), { threads: Object.assign(Object.assign({}, next.threads), { [chat.threadId]: chat }) });
+            if (tryWrite(storage, next))
+                return;
+        }
+        if (tryWriteShedding(storage, next))
+            return;
+        // Nothing fits: drop the stored copy too, so no in-flight record is left behind.
+        const _c = data.threads, _d = priority.threadId, dropped = _c[_d], rest = tslib_1.__rest(_c, [typeof _d === "symbol" ? _d : _d + ""]);
+        const others = Object.assign(Object.assign({}, data), { threads: rest });
+        if (isEmpty(others))
+            remove(storage);
+        else
+            tryWriteShedding(storage, others);
+    };
+    // Redo the merge if another tab wrote between our read and this write.
+    const MAX_COMMIT_ATTEMPTS = 3;
+    const transact = (mutate, priorityThreadId) => {
+        const storage = resolveStorage(storageOption, storageArea);
+        if (!storage)
+            return;
+        for (let attempt = 0; attempt < MAX_COMMIT_ATTEMPTS; attempt += 1) {
+            const raw = readRaw(storage);
+            const next = mutate(parse(raw));
+            if (!next)
+                return;
+            if (readRaw(storage) === raw) {
+                write(storage, next, priorityThreadId);
+                return;
+            }
+        }
+        // The key kept changing under us: skip rather than overwrite another tab's turns. Without
+        // Web Locks this check is best effort; a write between the compare and the set can still win.
+    };
+    /** The record to store once `chat` is merged in, or `null` to leave storage alone. */
+    const mergeThread = (current, chat) => {
+        var _a, _b, _c, _d;
+        const now = Date.now();
+        const createdAt = (_a = chat.createdAt) !== null && _a !== void 0 ? _a : now;
+        const deletedAt = (_b = current.deleted) === null || _b === void 0 ? void 0 : _b[chat.threadId];
+        if (deletedAt !== undefined && deletedAt >= createdAt)
+            return null;
+        const stored = current.threads[chat.threadId];
+        const incomingAt = (_c = chat.updatedAt) !== null && _c !== void 0 ? _c : now;
+        // An older snapshot may add turns but must not regress ones already settled.
+        const stale = Boolean(stored) && incomingAt < stored.updatedAt;
+        // Merging keeps turns other tabs added. The tab that wrote the stored record is instead
+        // writing a newer full view of it, and may have dropped a message (an aborted reply), so
+        // merging its own older copy back would resurrect what it just removed.
+        const ownsStored = (stored === null || stored === void 0 ? void 0 : stored.owner) !== undefined && chat.owner !== undefined && stored.owner === chat.owner;
+        const replace = !stored || (ownsStored && !stale);
+        const messages = replace ? chat.messages : (0, chatThreads_1.mergeMessages)(stored.messages, chat.messages, stale);
+        const base = stale ? stored : chat;
+        // A record holding turns its owner has not seen is nobody's full view, so the next save merges too.
+        const absorbed = !replace && messages.length > base.messages.length;
+        const merged = Object.assign(Object.assign({}, base), { owner: absorbed ? undefined : base.owner, version: chatThreads_1.PERSISTED_CHAT_VERSION, threadId: chat.threadId, messages: trimToTurns(messages, maxTurns), createdAt, updatedAt: Math.max(incomingAt, (_d = stored === null || stored === void 0 ? void 0 : stored.updatedAt) !== null && _d !== void 0 ? _d : 0) });
+        let next = Object.assign(Object.assign({}, current), { threads: Object.assign(Object.assign({}, current.threads), { [chat.threadId]: merged }) });
+        if (Number.isFinite(maxThreads)) {
+            const kept = sortedThreads(next).slice(0, Math.max(0, maxThreads));
+            next = Object.assign(Object.assign({}, next), { threads: Object.fromEntries(kept.map((t) => [t.threadId, t])) });
+            if (!next.threads[chat.threadId])
+                return null;
+        }
+        return next;
+    };
+    const retire = (data, staleId) => {
+        const _a = data.threads, _b = staleId, retired = _a[_b], threads = tslib_1.__rest(_a, [typeof _b === "symbol" ? _b : _b + ""]);
+        return Object.assign(Object.assign({}, data), { threads, deleted: Object.assign(Object.assign({}, data.deleted), { [staleId]: Date.now() }) });
+    };
+    return {
+        listThreads() {
+            return tslib_1.__awaiter(this, void 0, void 0, function* () {
+                const now = Date.now();
+                return sortedThreads(read()).map((chat) => ({
+                    threadId: chat.threadId,
+                    title: (0, chatThreads_1.getThreadTitle)(chat.messages),
+                    createdAt: chat.createdAt,
+                    updatedAt: chat.updatedAt,
+                    inFlight: (0, chatThreads_1.isThreadStreaming)(chat, now),
+                }));
+            });
+        },
+        getThread(threadId) {
+            var _a;
+            return tslib_1.__awaiter(this, void 0, void 0, function* () {
+                return (_a = read().threads[threadId]) !== null && _a !== void 0 ? _a : null;
+            });
+        },
+        isThreadDeleted(threadId) {
+            var _a;
+            return tslib_1.__awaiter(this, void 0, void 0, function* () {
+                // Deletes leave tombstones, so a missing key means the store was cleared from outside.
+                const storage = resolveStorage(storageOption, storageArea);
+                if (!storage || readRaw(storage) === null)
+                    return true;
+                return ((_a = read().deleted) === null || _a === void 0 ? void 0 : _a[threadId]) !== undefined;
+            });
+        },
+        saveThread(chat) {
+            return withStorageLock(storageKey, () => transact((current) => mergeThread(current, chat), chat.threadId));
+        },
+        saveThreadSync(chat, staleIds = []) {
+            // No Web Lock: its callback is a task, and tasks do not run while the document unloads.
+            transact((current) => {
+                const merged = mergeThread(current, chat);
+                if (!merged)
+                    return null;
+                return staleIds
+                    .filter((id) => id !== chat.threadId)
+                    .reduce((next, id) => retire(next, id), merged);
+            }, chat.threadId);
+        },
+        deleteThread(threadId) {
+            return withStorageLock(storageKey, () => transact((current) => retire(current, threadId)));
+        },
+        subscribe(listener) {
+            if (typeof window === 'undefined')
+                return () => { };
+            const onStorage = (event) => {
+                const area = resolveStorage(storageOption, storageArea);
+                if (area && event.storageArea && event.storageArea !== area)
+                    return;
+                if (event.key === null || event.key === storageKey)
+                    listener();
+            };
+            window.addEventListener('storage', onStorage);
+            return () => window.removeEventListener('storage', onStorage);
+        },
+    };
+}
+exports.createLocalStoragePersistence = createLocalStoragePersistence;
+const sharedStores = new Map();
+/**
+ * One store per namespace and area for the page, so a chat mounted again finds the answers still
+ * streaming into it. Not shared on the server, where the map would outlive the request.
+ */
+function sharedLocalStoragePersistence(namespace, storageArea) {
+    if (typeof window === 'undefined')
+        return createLocalStoragePersistence({ namespace, storageArea });
+    const id = `${storageArea}:${namespace}`;
+    const existing = sharedStores.get(id);
+    if (existing)
+        return existing;
+    const store = createLocalStoragePersistence({ namespace, storageArea });
+    sharedStores.set(id, store);
+    return store;
+}
+exports.sharedLocalStoragePersistence = sharedLocalStoragePersistence;
+exports.default = createLocalStoragePersistence;

package/lib/cjs/utils/translate.js

@@ -21,6 +21,7 @@ const defaultTranslations = {
     'CioAsa.results.saleBadge': 'Sale',
     'CioAsa.refinement.ariaLabel': 'Refine your results',
     'CioAsa.error.message': "I can't assist you with that request.",
+    'CioAsa.error.interrupted': 'The answer was interrupted. Please send your question again.',
 };
 function translate(key, translations) {
     var _a;

package/lib/cjs/version.js

@@ -1,3 +1,3 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = '1.7.2';
+exports.default = '1.9.0';

package/lib/mjs/components/Button/Button.js

@@ -1,8 +1,31 @@
-import React from 'react';
+import React, { useCallback } from 'react';
 import { Button as CioButton } from '@constructor-io/constructorio-ui-components';
 import { ChatBubbleDarkIcon, ChatBubbleLightIcon } from '../icons';
-export default function Button({ theme = 'dark', size = 'sm', onClick, label = 'Shopping assistant', }) {
-    return (React.createElement(CioButton, { className: `cio-asa-button cio-asa-button--${theme} cio-asa-button--${size}`, size: size === 'lg' ? 'default' : 'sm', onClick: onClick },
+import { useCioAsaContext } from '../../hooks/useCioAsaContext';
+import useAsaTracking from '../../hooks/useAsaTracking';
+const AGENT_BUTTON_CLICK_MODE = 'chat';
+export default function Button({ theme = 'dark', size = 'sm', onClick, label = 'Shopping assistant', positionOnPage, pageType, instanceId, }) {
+    const context = useCioAsaContext();
+    const agentDomain = context?.staticRequestConfigs?.domain;
+    const tracking = useAsaTracking({
+        tracker: context?.cioClient?.tracker ?? undefined,
+        section: context?.section,
+    });
+    const handleClick = useCallback(() => {
+        if (agentDomain) {
+            const payload = {
+                mode: AGENT_BUTTON_CLICK_MODE,
+                agentDomain,
+                ...(positionOnPage && { positionOnPage }),
+                ...(pageType && { pageType }),
+                ...(instanceId && { instanceId }),
+            };
+            tracking.trackAgentButtonClick(payload);
+            context?.callbacks?.onAgentButtonClick?.(payload);
+        }
+        onClick?.();
+    }, [agentDomain, positionOnPage, pageType, instanceId, tracking, context, onClick]);
+    return (React.createElement(CioButton, { className: `cio-asa-button cio-asa-button--${theme} cio-asa-button--${size}`, size: size === 'lg' ? 'default' : 'sm', onClick: handleClick },
         theme === 'dark' ? React.createElement(ChatBubbleDarkIcon, null) : React.createElement(ChatBubbleLightIcon, null),
         React.createElement("span", { className: 'cio-asa-button__label' }, label)));
 }

package/lib/mjs/components/Chat/AiMessage.js

@@ -8,9 +8,8 @@ export default function AiMessage({ message, componentOverrides, translations })
     const hasGroups = !!message.groups?.length;
     // On error, fall back to the (translatable) error message when the agent
     // returned no partial text of its own.
-    const text = isError
-        ? message.text || translate('CioAsa.error.message', translations)
-        : message.text || '';
+    const errorKey = message.interrupted ? 'CioAsa.error.interrupted' : 'CioAsa.error.message';
+    const text = isError ? message.text || translate(errorKey, translations) : message.text || '';
     const hasText = text.length > 0;
     const loaderRenderProps = { translations };
     const textRenderProps = { text };

package/lib/mjs/components/Chat/Chat.js

@@ -1,6 +1,9 @@
 import React, { useRef, useEffect, useImperativeHandle, forwardRef } from 'react';
 import useAsaResults from '../../hooks/useAsaResults';
+import { useCioAsaContext } from '../../hooks/useCioAsaContext';
 import useFocusTrap from '../../hooks/useFocusTrap';
+import useLatest from '../../hooks/useLatest';
+import { normalizeItemToProduct } from '../../utils/productNormalizer';
 import translate from '../../utils/translate';
 import ChatHeader from './ChatHeader';
 import WelcomeScreen from './WelcomeScreen';
@@ -22,20 +25,54 @@ function getAnnouncement(messages, translations) {
     }
     return '';
 }
-const Chat = forwardRef(({ onClose, className, initialSuggestions, termsText, onProductClick, onViewMore, onAddToCart, aspectRatio, currency, normalizeItem, componentOverrides, translations, initialThreadId, showStopButton = false, }, ref) => {
-    const { messages, sendMessage, isStreaming, abort, clearHistory } = useAsaResults({
+const Chat = forwardRef(({ onClose, className, initialSuggestions, termsText, onProductClick, onViewMore, onAddToCart, aspectRatio, currency, normalizeItem, componentOverrides, translations, initialThreadId, initialPrompt, onThreadsChange, showStopButton = false, }, ref) => {
+    const { messages, sendMessage, isStreaming, canAbort, abort, clearHistory, isHydrating, threads, activeThreadId, newThread, switchThread, } = useAsaResults({
         initialThreadId,
+        normalizeItem: (item) => (normalizeItem ?? normalizeItemToProduct)(item, {
+            saleBadgeText: translate('CioAsa.results.saleBadge', translations),
+        }),
     });
     const chatViewRef = useRef(null);
     const containerRef = useRef(null);
     const isWelcome = messages.length === 0;
+    // While another thread loads, keep the chat frame (header, close button) instead of a blank body.
+    const lastViewRef = useRef(null);
+    if (!isHydrating)
+        lastViewRef.current = isWelcome ? 'welcome' : 'chat';
+    const showWelcome = !isHydrating && isWelcome;
+    const showChat = !isHydrating && !isWelcome;
+    const showChatFrame = showChat || (isHydrating && lastViewRef.current === 'chat');
     const isModal = typeof onClose === 'function';
     const announcement = getAnnouncement(messages, translations);
     useImperativeHandle(ref, () => ({
         abort,
         clearHistory,
-    }));
+        newThread,
+        switchThread,
+        sendMessage: (text, options) => sendMessage(text, 'external', options),
+    }), [abort, clearHistory, newThread, switchThread, sendMessage]);
+    // Sent from a timer so StrictMode's mount, unmount, mount cannot cancel the stream it starts.
+    const initialPromptRef = useRef(initialPrompt);
     useEffect(() => {
+        const prompt = initialPromptRef.current;
+        if (isHydrating || !prompt)
+            return undefined;
+        const timer = setTimeout(() => {
+            initialPromptRef.current = undefined;
+            sendMessage(prompt, 'external');
+        });
+        return () => clearTimeout(timer);
+    }, [isHydrating, sendMessage]);
+    const hasPersistence = Boolean(useCioAsaContext()?.persistence);
+    const onThreadsChangeRef = useLatest(onThreadsChange);
+    useEffect(() => {
+        if (!hasPersistence || isHydrating)
+            return;
+        onThreadsChangeRef.current?.(threads, activeThreadId);
+    }, [threads, activeThreadId, isHydrating, hasPersistence, onThreadsChangeRef]);
+    useEffect(() => {
+        if (isHydrating)
+            return;
         const root = isWelcome ? containerRef.current : chatViewRef.current;
         const input = root?.querySelector('input');
         if (input) {
@@ -48,15 +85,17 @@ const Chat = forwardRef(({ onClose, className, initialSuggestions, termsText, on
                 input.focus();
             }
         }
-    }, [isWelcome]);
+    }, [isWelcome, isHydrating]);
     useFocusTrap(containerRef, { onEscape: onClose, trapFocus: isModal });
     return (React.createElement("div", { className: ['cio-asa', 'cio-asa-chat', className].filter(Boolean).join(' '), ref: containerRef, role: 'dialog', "aria-modal": isModal ? 'true' : undefined, "aria-label": translate(isWelcome ? 'CioAsa.welcome.title' : 'CioAsa.header.title', translations) },
         React.createElement("div", { className: 'cio-sr-only', role: 'status' }, announcement),
-        React.createElement("div", { className: 'cio-asa-chat-body' }, isWelcome ? (React.createElement("div", { className: 'cio-asa-chat-view cio-asa-chat-view--welcome' },
-            React.createElement(WelcomeScreen, { suggestions: initialSuggestions, onSend: sendMessage, onClose: onClose, termsText: termsText, translations: translations, componentOverrides: componentOverrides?.welcomeScreen }))) : (React.createElement("div", { className: 'cio-asa-chat-view cio-asa-chat-view--chat', ref: chatViewRef },
-            React.createElement(ChatHeader, { onClose: onClose, translations: translations, componentOverrides: componentOverrides?.header }),
-            React.createElement(ChatMessageList, { messages: messages, onProductClick: onProductClick, onViewMore: onViewMore, onAddToCart: onAddToCart, aspectRatio: aspectRatio, currency: currency, normalizeItem: normalizeItem, addToCartText: translate('CioAsa.results.addToCart', translations), viewMoreText: translate('CioAsa.results.viewMore', translations), aiMessageOverrides: componentOverrides?.aiMessage, userMessageOverrides: componentOverrides?.userMessage, resultsBlockOverrides: componentOverrides?.resultsBlock, translations: translations, onSend: sendMessage, isStreaming: isStreaming }),
-            React.createElement(ChatInput, { onSubmit: sendMessage, isDisabled: isStreaming, isStreaming: isStreaming, onAbort: abort, showStopButton: showStopButton, translations: translations, componentOverrides: componentOverrides?.input }))))));
+        React.createElement("div", { className: 'cio-asa-chat-body' },
+            showWelcome && (React.createElement("div", { className: 'cio-asa-chat-view cio-asa-chat-view--welcome' },
+                React.createElement(WelcomeScreen, { suggestions: initialSuggestions, onSend: sendMessage, onClose: onClose, termsText: termsText, translations: translations, componentOverrides: componentOverrides?.welcomeScreen }))),
+            showChatFrame && (React.createElement("div", { className: 'cio-asa-chat-view cio-asa-chat-view--chat', ref: chatViewRef },
+                React.createElement(ChatHeader, { onClose: onClose, translations: translations, componentOverrides: componentOverrides?.header }),
+                React.createElement(ChatMessageList, { messages: messages, onProductClick: onProductClick, onViewMore: onViewMore, onAddToCart: onAddToCart, aspectRatio: aspectRatio, currency: currency, normalizeItem: normalizeItem, addToCartText: translate('CioAsa.results.addToCart', translations), viewMoreText: translate('CioAsa.results.viewMore', translations), aiMessageOverrides: componentOverrides?.aiMessage, userMessageOverrides: componentOverrides?.userMessage, resultsBlockOverrides: componentOverrides?.resultsBlock, translations: translations, onSend: sendMessage, isStreaming: isStreaming }),
+                React.createElement(ChatInput, { onSubmit: sendMessage, isDisabled: isStreaming || isHydrating, isStreaming: isStreaming, onAbort: canAbort ? abort : undefined, showStopButton: showStopButton, translations: translations, componentOverrides: componentOverrides?.input }))))));
 });
 Chat.displayName = 'Chat';
 export default Chat;

package/lib/mjs/components/CioAsa/CioAsa.js

@@ -12,8 +12,12 @@ import Chat from '../Chat/Chat';
 const CioAsa = React.forwardRef((props, ref) => {
     const { 
     // Provider configuration — everything else belongs to Chat.
-    apiKey, cioClient, testCells, staticRequestConfigs, formatters, urlHelpers, callbacks, section, ...chatProps } = props;
-    return (React.createElement(CioAsaProvider, { apiKey: apiKey, cioClient: cioClient, testCells: testCells, staticRequestConfigs: staticRequestConfigs, formatters: formatters, urlHelpers: urlHelpers, callbacks: callbacks, section: section },
+    apiKey, cioClient, testCells, staticRequestConfigs, formatters, urlHelpers, callbacks, section, persistConversation, userId = null, ...chatProps } = props;
+    // Split so TypeScript can match the pair against the provider's props.
+    const persistenceProps = persistConversation
+        ? { persistConversation, userId }
+        : { userId };
+    return (React.createElement(CioAsaProvider, { apiKey: apiKey, cioClient: cioClient, testCells: testCells, staticRequestConfigs: staticRequestConfigs, formatters: formatters, urlHelpers: urlHelpers, callbacks: callbacks, section: section, ...persistenceProps },
         React.createElement(Chat, { ...chatProps, ref: ref })));
 });
 CioAsa.displayName = 'CioAsa';

package/lib/mjs/components/CioAsaProvider/CioAsaProvider.js

@@ -1,17 +1,43 @@
-import React, { useMemo, useState } from 'react';
+import React, { useEffect, useMemo, useRef, useState } from 'react';
 import useCioClient from '../../hooks/useCioClient';
 import { AsaContext } from '../../hooks/useCioAsaContext';
 import * as defaultFormatters from '../../utils/formatters';
 import * as defaultUrlHelpers from '../../utils/urlHelpers';
+import { readClientOptions } from '../../utils/clientOptions';
+import { persistenceNamespace, sharedLocalStoragePersistence, shopperId, storageAreaFor, } from '../../utils/localStoragePersistence';
 export default function CioAsaProvider(props) {
-    const { apiKey, formatters, urlHelpers, staticRequestConfigs = { domain: 'chatbot' }, cioClient: customCioClient, testCells, callbacks, section = 'Products', children, } = props;
+    const { apiKey, formatters, urlHelpers, staticRequestConfigs = { domain: 'chatbot' }, cioClient: customCioClient, testCells, callbacks, section = 'Products', persistConversation: persistOptions, userId: userIdProp, children, } = props;
+    // Read field by field: an inline options object is a new reference on every render.
+    const persistenceEnabled = Boolean(persistOptions?.enabled);
     const [cioClientOptions, setCioClientOptions] = useState({});
+    const initialUserId = useRef(userIdProp).current;
+    const clientInit = useMemo(() => initialUserId === undefined
+        ? cioClientOptions
+        : { ...cioClientOptions, userId: shopperId(initialUserId) }, [cioClientOptions, initialUserId]);
     const cioClient = useCioClient({
         apiKey,
         cioClient: customCioClient,
-        cioClientOptions,
+        cioClientOptions: clientInit,
         testCells,
     });
+    const userId = shopperId(userIdProp);
+    const syncUserId = persistenceEnabled || userIdProp !== undefined;
+    useEffect(() => {
+        if (customCioClient || !cioClient || !syncUserId)
+            return;
+        cioClient.setClientOptions({ userId });
+    }, [cioClient, customCioClient, syncUserId, userId]);
+    const resolvedApiKey = apiKey ?? readClientOptions(cioClient)?.apiKey;
+    const { domain } = staticRequestConfigs;
+    const persistence = useMemo(() => {
+        if (!persistenceEnabled || resolvedApiKey === undefined)
+            return undefined;
+        return sharedLocalStoragePersistence(persistenceNamespace({ apiKey: resolvedApiKey, domain, userId }), storageAreaFor(userId));
+    }, [persistenceEnabled, resolvedApiKey, domain, userId]);
+    const persistenceScope = persistence && (userId === undefined ? 'guest' : 'user');
+    const persistenceIndex = persistence && resolvedApiKey !== undefined
+        ? persistenceNamespace({ apiKey: resolvedApiKey, domain })
+        : undefined;
     const contextValue = useMemo(() => ({
         cioClient,
         cioClientOptions,
@@ -21,6 +47,20 @@ export default function CioAsaProvider(props) {
         urlHelpers: { ...defaultUrlHelpers, ...urlHelpers },
         callbacks,
         section,
-    }), [cioClient, cioClientOptions, formatters, urlHelpers, staticRequestConfigs, callbacks, section]);
+        persistence,
+        persistenceScope,
+        persistenceIndex,
+    }), [
+        cioClient,
+        cioClientOptions,
+        formatters,
+        urlHelpers,
+        staticRequestConfigs,
+        callbacks,
+        section,
+        persistence,
+        persistenceScope,
+        persistenceIndex,
+    ]);
     return (React.createElement(AsaContext.Provider, { value: contextValue }, typeof children === 'function' ? children(contextValue) : children));
 }

package/lib/mjs/components/ResultsBlock/ResultsGroup.js

@@ -18,7 +18,8 @@ function NextButton() {
  */
 export default function ResultsGroup({ groupData, label, slidesToShow, gap, showTitle, viewMoreText, addToCartText, saleBadgeText, currency, intent, intentResultId, normalizeItem, onProductClick, onAddToCart, onViewMore, componentOverrides, tracking, callbacks, }) {
     const { searchResultId } = groupData;
-    const products = groupData.searchResults.map((item) => normalizeItem(item, { saleBadgeText }));
+    const products = groupData.products ??
+        groupData.searchResults.map((item) => normalizeItem(item, { saleBadgeText }));
     const canTrack = !!intent && !!searchResultId;
     const { ref: viewRef } = useViewportTracking({
         enabled: canTrack,