@constructor-io/constructorio-ui-pia 2.16.1 → 2.18.0

package/lib/cjs/utils/conversationStorage.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearPersistedConversations = exports.moveGuestConversations = exports.saveConversation = exports.loadConversation = exports.isRestorableEntry = exports.isGuest = exports.PERSISTENCE_TTL_MS = void 0;
+const tslib_1 = require("tslib");
+const KEY_PREFIX = 'cio-pia:chat:v1';
+const STORED_VERSION = 1;
+/** Matches how long the agent remembers a thread. */
+exports.PERSISTENCE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const isGuest = (userId) => userId == null || userId === '';
+exports.isGuest = isGuest;
+function isRestorableEntry(entry) {
+    if (typeof entry !== 'object' || entry === null)
+        return false;
+    const { question, answer, items } = entry;
+    return (typeof question === 'string' &&
+        typeof answer === 'string' &&
+        (items === undefined || items === null || Array.isArray(items)));
+}
+exports.isRestorableEntry = isRestorableEntry;
+function isPersistedConversation(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const { threadId, entries, updatedAt } = value;
+    return (typeof threadId === 'string' &&
+        threadId !== '' &&
+        typeof updatedAt === 'number' &&
+        Array.isArray(entries) &&
+        entries.every(isRestorableEntry));
+}
+function storageKeyFor({ apiKey, userId }) {
+    const parts = (0, exports.isGuest)(userId) ? [apiKey] : [apiKey, String(userId)];
+    return [KEY_PREFIX, ...parts.map(encodeURIComponent)].join(':');
+}
+// A guest's conversations end with the tab, so the next person at that browser never sees them.
+function storageFor({ userId }) {
+    try {
+        if (typeof window === 'undefined')
+            return null;
+        return (0, exports.isGuest)(userId) ? window.sessionStorage : window.localStorage;
+    }
+    catch (_a) {
+        return null;
+    }
+}
+function readItems(storage, key) {
+    var _a;
+    try {
+        const parsed = JSON.parse((_a = storage.getItem(key)) !== null && _a !== void 0 ? _a : 'null');
+        if ((parsed === null || parsed === void 0 ? void 0 : parsed.version) !== STORED_VERSION || typeof parsed.items !== 'object' || !parsed.items) {
+            return {};
+        }
+        const cutoff = Date.now() - exports.PERSISTENCE_TTL_MS;
+        return Object.fromEntries(Object.entries(parsed.items).filter((pair) => isPersistedConversation(pair[1]) && pair[1].updatedAt >= cutoff));
+    }
+    catch (_b) {
+        return {};
+    }
+}
+function tryWrite(storage, key, items) {
+    try {
+        if (Object.keys(items).length === 0)
+            storage.removeItem(key);
+        else
+            storage.setItem(key, JSON.stringify({ version: STORED_VERSION, items }));
+        return true;
+    }
+    catch (_a) {
+        return false;
+    }
+}
+// When storage is full, shed other products' conversations oldest first, then this one's oldest
+// turns. If not even one turn fits, this conversation is left out rather than stored half-written.
+function writeFitting(storage, key, items, itemId) {
+    if (tryWrite(storage, key, items))
+        return;
+    const _a = items, _b = itemId, saved = _a[_b], others = tslib_1.__rest(_a, [typeof _b === "symbol" ? _b : _b + ""]);
+    const oldestFirst = Object.keys(others).sort((a, b) => others[a].updatedAt - others[b].updatedAt);
+    const fitsAfterEviction = oldestFirst.some((_, index) => {
+        const kept = Object.fromEntries(oldestFirst.slice(index + 1).map((id) => [id, others[id]]));
+        return tryWrite(storage, key, Object.assign(Object.assign({}, kept), { [itemId]: saved }));
+    });
+    if (fitsAfterEviction)
+        return;
+    const fitsTrimmed = saved.entries
+        .slice(1)
+        .some((_, i) => tryWrite(storage, key, { [itemId]: Object.assign(Object.assign({}, saved), { entries: saved.entries.slice(i + 1) }) }));
+    if (fitsTrimmed)
+        return;
+    tryWrite(storage, key, others);
+}
+function loadConversation(owner, itemId) {
+    const storage = storageFor(owner);
+    return storage ? readItems(storage, storageKeyFor(owner))[itemId] : undefined;
+}
+exports.loadConversation = loadConversation;
+/** Stores the answered turns of one product's conversation. A turn still waiting on its answer is left out. */
+function saveConversation(owner, itemId, threadId, history) {
+    const entries = history.filter((entry) => entry.answer !== '');
+    const storage = storageFor(owner);
+    if (!storage || entries.length === 0)
+        return;
+    const key = storageKeyFor(owner);
+    const items = readItems(storage, key);
+    writeFitting(storage, key, Object.assign(Object.assign({}, items), { [itemId]: { threadId, entries, updatedAt: Date.now() } }), itemId);
+}
+exports.saveConversation = saveConversation;
+/** On login: every guest conversation moves into the shopper's store, so none is left for the next guest. */
+function moveGuestConversations(apiKey, userId) {
+    const guest = { apiKey };
+    const shopper = { apiKey, userId };
+    const guestStorage = storageFor(guest);
+    const shopperStorage = storageFor(shopper);
+    if (!guestStorage || !shopperStorage)
+        return;
+    const guestKey = storageKeyFor(guest);
+    const moved = readItems(guestStorage, guestKey);
+    if (Object.keys(moved).length === 0)
+        return;
+    const shopperKey = storageKeyFor(shopper);
+    const merged = readItems(shopperStorage, shopperKey);
+    Object.entries(moved).forEach(([itemId, conversation]) => {
+        var _a, _b;
+        if (((_b = (_a = merged[itemId]) === null || _a === void 0 ? void 0 : _a.updatedAt) !== null && _b !== void 0 ? _b : -Infinity) <= conversation.updatedAt) {
+            merged[itemId] = conversation;
+        }
+    });
+    if (tryWrite(shopperStorage, shopperKey, merged))
+        tryWrite(guestStorage, guestKey, {});
+}
+exports.moveGuestConversations = moveGuestConversations;
+/**
+ * Deletes every stored conversation of one shopper, or of the current tab's guest when `userId` is
+ * omitted. A widget already showing one keeps it on screen until its `itemId` or `userId` changes.
+ */
+function clearPersistedConversations({ apiKey, userId, }) {
+    const owner = { apiKey, userId };
+    const storage = storageFor(owner);
+    if (storage)
+        tryWrite(storage, storageKeyFor(owner), {});
+}
+exports.clearPersistedConversations = clearPersistedConversations;

package/lib/cjs/version.js

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

package/lib/mjs/components/CioPia/CioPiaQna.js

@@ -5,9 +5,11 @@ import SuggestedQuestionsContainer from '../SuggestedQuestionsContainer/Suggeste
 import SuggestedQuestionsSkeleton from '../SuggestedQuestionsContainer/SuggestedQuestionsSkeleton';
 import useCioPia from '../../hooks/useCioPia';
 import useConversation from '../../hooks/useConversation';
+import usePersistedConversation from '../../hooks/usePersistedConversation';
 import useTracking from '../../hooks/useTracking';
 import useViewportTracking from '../../hooks/useViewportTracking';
 import useViewportCallbacks from '../../hooks/useViewportCallbacks';
+import useReturnFocusToInput from '../../hooks/useReturnFocusToInput';
 import ErrorBlock from '../Error/ErrorBlock';
 import LoadingSkeleton from '../LoadingSkeleton/LoadingSkeleton';
 import { translate } from '../../utils/translate';
@@ -19,14 +21,21 @@ import CheckoutTriggerBar from './CheckoutTriggerBar';
 /** The question-and-answer experience: `mode: 'default'`, `mode: 'conversation'`, and the modal. */
 // eslint-disable-next-line complexity
 export default function CioPiaQna(props) {
-    const { apiKey, itemId, itemName, threadId, variationId, cioClient, displayConfigs, componentOverrides, callbacks, formatters, productCardProps, children, translations, suggestedQuestionsParameters, answerParameters, parameters, trackingConfigs, checkoutTriggers, abTest, initialConversationHistory, } = props;
+    const { apiKey, itemId, itemName, threadId, variationId, cioClient, displayConfigs, componentOverrides, callbacks, formatters, productCardProps, children, translations, suggestedQuestionsParameters, answerParameters, parameters, trackingConfigs, checkoutTriggers, abTest, initialConversationHistory, persistConversation, userId, } = props;
     const { learnMoreUrl, showFeedback, mode = 'default', type = 'inline', showPreviousItems, disclaimerPosition = 'bottom', } = displayConfigs || {};
     const isConversation = mode === 'conversation' || type === 'modal';
     const { priceCurrency } = productCardProps || {};
-    const pia = useCioPia({
+    const persisted = usePersistedConversation({
+        enabled: Boolean(persistConversation?.enabled) && isConversation,
         apiKey,
+        userId,
         itemId,
         threadId,
+    });
+    const pia = useCioPia({
+        apiKey,
+        itemId,
+        threadId: persisted?.threadId ?? threadId,
         variationId,
         cioClient,
         suggestedQuestionsParameters,
@@ -34,6 +43,7 @@ export default function CioPiaQna(props) {
         parameters,
         formatImageUrl: formatters?.formatImageUrl,
         testCells: abTest?.testCells,
+        userId,
     });
     const tracking = useTracking({
         cioClient: pia.cioClient,
@@ -49,7 +59,17 @@ export default function CioPiaQna(props) {
         callbacks,
         tracking,
         initialConversationHistory,
+        persisted,
     });
+    const { inputRef, returnFocusAfterLoading } = useReturnFocusToInput(isLoading);
+    const handleInlineSubmit = useCallback((question) => {
+        handleSubmitQuestion(question);
+        returnFocusAfterLoading();
+    }, [handleSubmitQuestion, returnFocusAfterLoading]);
+    const handleInlineQuestionClick = useCallback((question) => {
+        handleQuestionClick(question);
+        returnFocusAfterLoading();
+    }, [handleQuestionClick, returnFocusAfterLoading]);
     const { containerRef: viewportContainerRef } = useViewportTracking({
         tracking,
         questions: displayedQuestions,
@@ -113,12 +133,12 @@ export default function CioPiaQna(props) {
     return (React.createElement("div", { ref: containerRef, className: 'cio-pia-container', "data-testid": 'cio-pia-container' },
         React.createElement(RenderPropsWrapper, { props: renderProps, override: children || componentOverrides?.reactNode },
             React.createElement("p", { className: 'cio-pia-title', "data-testid": 'cio-pia-title' }, translate('Any questions about this product?', translations)),
-            React.createElement(Input, { onSubmit: handleSubmitQuestion, onFocus: handleInputFocus, value: currentQuestion, translations: translations, componentOverride: componentOverrides?.input }),
+            React.createElement(Input, { onSubmit: handleInlineSubmit, onFocus: handleInputFocus, inputRef: inputRef, disabled: isLoading, value: currentQuestion, translations: translations, componentOverride: componentOverrides?.input }),
             isAnswerLoading && React.createElement(LoadingSkeleton, { componentOverride: componentOverrides?.loading }),
             !isAnswerLoading && error && (React.createElement(ErrorBlock, { key: error.message || translate('Unexpected error', translations), message: error.message, translations: translations })),
             !isAnswerLoading && !error && currentAnswer && (React.createElement(PiaInlineAnswer, { currentAnswer: currentAnswer, currentItems: currentItems, showFeedback: showFeedback, learnMoreUrl: learnMoreUrl, disclaimerPosition: disclaimerPosition, translations: translations, callbacks: callbacks, componentOverrides: componentOverrides, onFeedback: handleFeedback, onResultClick: tracking.trackResultClick, question: currentQuestion, qnaResultId: qnaResultId, priceCurrency: priceCurrency })),
             isLoading && React.createElement(SuggestedQuestionsSkeleton, null),
-            !isLoading && !error && (React.createElement(SuggestedQuestionsContainer, { questions: displayedQuestions, onQuestionClick: handleQuestionClick, componentOverride: componentOverrides?.suggestedQuestions })),
+            !isLoading && !error && (React.createElement(SuggestedQuestionsContainer, { questions: displayedQuestions, onQuestionClick: handleInlineQuestionClick, componentOverride: componentOverrides?.suggestedQuestions })),
             checkoutElement),
         React.createElement(StatusRegion, { message: answerStatus, "data-testid": 'answer-status' })));
 }

package/lib/mjs/components/CioPiaRecs/RecsPodRefinement.js

@@ -1,10 +1,11 @@
-import React from 'react';
+import React, { useCallback } from 'react';
 import Input from '../Input/Input';
 import SuggestedQuestion from '../SuggestedQuestion/SuggestedQuestion';
 import { SparklesIcon } from '../icons';
 import RecsOptionsSkeleton from './RecsOptionsSkeleton';
 import { resolveRefinementQuestion } from '../../utils/recs';
 import { RECS_INPUT_PLACEHOLDER } from '../../constants';
+import useReturnFocusToInput from '../../hooks/useReturnFocusToInput';
 /**
  * The row under the products: a prompt line, the short options the API suggested, and a box for
  * anything it did not think of. The prompt line is held still while the rest reloads, so the row
@@ -12,11 +13,20 @@ import { RECS_INPUT_PLACEHOLDER } from '../../constants';
  */
 export default function RecsPodRefinement({ refinement, isLoading, inputError, showInput, translations, componentOverrides, onRefine, onSubmit, onInputFocus, }) {
     const options = refinement?.options || [];
+    const { inputRef, returnFocusAfterLoading } = useReturnFocusToInput(isLoading);
+    const refine = useCallback((text) => {
+        onRefine(text);
+        returnFocusAfterLoading();
+    }, [onRefine, returnFocusAfterLoading]);
+    const submit = useCallback((value) => {
+        onSubmit(value);
+        returnFocusAfterLoading();
+    }, [onSubmit, returnFocusAfterLoading]);
     return (React.createElement("div", { className: 'cio-pia-recs-pod__refinement' },
         React.createElement("span", { className: 'cio-pia-recs-pod__refinement-label' }, resolveRefinementQuestion(refinement, translations)),
-        isLoading ? (React.createElement(RecsOptionsSkeleton, { count: options.length || undefined })) : (options.map((option) => (React.createElement(SuggestedQuestion, { key: option, question: option, icon: React.createElement(SparklesIcon, null), onClick: () => onRefine(option) })))),
+        isLoading ? (React.createElement(RecsOptionsSkeleton, { count: options.length || undefined })) : (options.map((option) => (React.createElement(SuggestedQuestion, { key: option, question: option, icon: React.createElement(SparklesIcon, null), onClick: () => refine(option) })))),
         showInput && (React.createElement("div", { className: 'cio-pia-recs-pod__input' },
-            React.createElement(Input, { onSubmit: onSubmit, onFocus: onInputFocus, disabled: isLoading, error: inputError ?? undefined, placeholderKey: RECS_INPUT_PLACEHOLDER, 
+            React.createElement(Input, { onSubmit: submit, onFocus: onInputFocus, inputRef: inputRef, disabled: isLoading, error: inputError ?? undefined, placeholderKey: RECS_INPUT_PLACEHOLDER, 
                 // The pod's box sits in a row beside the options and submits on Enter. Q&A keeps
                 // its button; this one has none in the mocks.
                 showSendButton: false, translations: translations, componentOverride: componentOverrides?.input })))));

package/lib/mjs/components/Input/Input.js

@@ -13,7 +13,7 @@ import { SendIcon } from '../icons';
  * across its re-renders.
  */
 let inputIdCounter = 0;
-function Input({ value: providedValue, placeholder, disabled = false, onSubmit, onFocus, translations, componentOverride, error, placeholderKey = 'Ask anything', showSendButton = true, }) {
+function Input({ value: providedValue, placeholder, disabled = false, onSubmit, onFocus, translations, componentOverride, error, inputRef, placeholderKey = 'Ask anything', showSendButton = true, }) {
     const [value, setValue] = useState(providedValue || '');
     const [errorId] = useState(() => {
         inputIdCounter += 1;
@@ -50,10 +50,11 @@ function Input({ value: providedValue, placeholder, disabled = false, onSubmit,
             onFocus,
             translations,
             error,
+            inputRef,
         }, override: componentOverride?.reactNode },
         React.createElement(React.Fragment, null,
             React.createElement("div", { className: 'cio-pia-input-container' },
-                React.createElement("input", { type: 'text', value: value, onChange: (e) => setValue(e.target.value), onKeyDown: handleSubmitOnEnter, onFocus: onFocus, placeholder: resolvedPlaceholder, "aria-label": accessibleName, disabled: disabled, className: cx('cio-pia-input', error && 'cio-pia-input--error', !showSendButton && 'cio-pia-input--no-send'), "aria-invalid": error ? true : undefined, "aria-describedby": error ? errorId : undefined }),
+                React.createElement("input", { ref: inputRef, type: 'text', value: value, onChange: (e) => setValue(e.target.value), onKeyDown: handleSubmitOnEnter, onFocus: onFocus, placeholder: resolvedPlaceholder, "aria-label": accessibleName, disabled: disabled, className: cx('cio-pia-input', error && 'cio-pia-input--error', !showSendButton && 'cio-pia-input--no-send'), "aria-invalid": error ? true : undefined, "aria-describedby": error ? errorId : undefined }),
                 showSendButton && (React.createElement("button", { type: 'button', onClick: () => handleSubmit(value), className: 'cio-pia-send-button', disabled: disabled },
                     translate('Send', translations),
                     React.createElement(SendIcon, null)))),

package/lib/mjs/components/PiaConversation/PiaConversation.js

@@ -1,17 +1,33 @@
-import React from 'react';
+import React, { useCallback, useContext } from 'react';
 import Input from '../Input/Input';
 import SuggestedQuestionsContainer from '../SuggestedQuestionsContainer/SuggestedQuestionsContainer';
 import SuggestedQuestionsSkeleton from '../SuggestedQuestionsContainer/SuggestedQuestionsSkeleton';
 import { translate } from '../../utils/translate';
+import useReturnFocusToInput from '../../hooks/useReturnFocusToInput';
+import { ModalInputRefContext } from './PiaModal';
 import ConversationHistory from '../ConversationHistory/ConversationHistory';
 export default function PiaConversation({ conversationHistory, isLoading, error, currentItems, showFeedback, showPreviousItems, learnMoreUrl, disclaimerPosition, translations, callbacks, componentOverrides, displayedQuestions, handleSubmitQuestion, handleQuestionClick, containerRef, handleFeedback, onResultClick, qnaResultId, onInputFocus, priceCurrency, checkoutElement, }) {
     const hasHistory = conversationHistory.length > 0;
+    const { inputRef, returnFocusAfterLoading } = useReturnFocusToInput(isLoading);
+    const modalInputRef = useContext(ModalInputRefContext);
+    const attachInput = useCallback((node) => {
+        inputRef(node);
+        modalInputRef?.(node);
+    }, [inputRef, modalInputRef]);
+    const submitQuestion = useCallback((question) => {
+        handleSubmitQuestion(question);
+        returnFocusAfterLoading();
+    }, [handleSubmitQuestion, returnFocusAfterLoading]);
+    const clickQuestion = useCallback((question) => {
+        handleQuestionClick(question);
+        returnFocusAfterLoading();
+    }, [handleQuestionClick, returnFocusAfterLoading]);
     return (React.createElement("div", { ref: containerRef, className: 'cio-pia-container cio-pia-conversation', "data-testid": 'cio-pia-container' },
         !hasHistory && (React.createElement("p", { className: 'cio-pia-title', "data-testid": 'cio-pia-title' }, translate('Any questions about this product?', translations))),
         React.createElement(ConversationHistory, { conversationHistory: conversationHistory, isLoading: isLoading, error: error, currentItems: currentItems, showFeedback: showFeedback, showPreviousItems: showPreviousItems, learnMoreUrl: learnMoreUrl, disclaimerPosition: disclaimerPosition, translations: translations, callbacks: callbacks, componentOverrides: componentOverrides, handleFeedback: handleFeedback, onResultClick: onResultClick, qnaResultId: qnaResultId, priceCurrency: priceCurrency }),
         checkoutElement && React.createElement("div", { className: 'cio-pia-conversation-checkout' }, checkoutElement),
         React.createElement("div", { className: 'cio-pia-conversation-footer' },
             isLoading && !error && React.createElement(SuggestedQuestionsSkeleton, null),
-            !isLoading && !error && (React.createElement(SuggestedQuestionsContainer, { questions: displayedQuestions, onQuestionClick: handleQuestionClick, componentOverride: componentOverrides?.suggestedQuestions })),
-            React.createElement(Input, { onSubmit: handleSubmitQuestion, onFocus: onInputFocus, disabled: isLoading, translations: translations, componentOverride: componentOverrides?.input }))));
+            !isLoading && !error && (React.createElement(SuggestedQuestionsContainer, { questions: displayedQuestions, onQuestionClick: clickQuestion, componentOverride: componentOverrides?.suggestedQuestions })),
+            React.createElement(Input, { onSubmit: submitQuestion, onFocus: onInputFocus, inputRef: attachInput, disabled: isLoading, translations: translations, componentOverride: componentOverrides?.input }))));
 }

package/lib/mjs/components/PiaConversation/PiaModal.js

@@ -1,8 +1,10 @@
-import React, { useCallback, useEffect, useRef, useState } from 'react';
+import React, { createContext, useCallback, useEffect, useRef, useState, } from 'react';
 import Input from '../Input/Input';
 import { translate } from '../../utils/translate';
 import SuggestedQuestionsContainer from '../SuggestedQuestionsContainer/SuggestedQuestionsContainer';
 const OVERFLOW_HIDDEN_CLASS = 'cio-pia-modal-open';
+/** Lets the conversation rendered as the modal's children hand it the node of its input. */
+export const ModalInputRefContext = createContext(undefined);
 function CloseIcon() {
     return (React.createElement("svg", { width: '20', height: '20', viewBox: '0 0 20 20', fill: 'none', xmlns: 'http://www.w3.org/2000/svg', "aria-hidden": 'true', focusable: 'false' },
         React.createElement("path", { d: 'M15.8334 5.34166L14.6584 4.16666L10.0001 8.82499L5.34175 4.16666L4.16675 5.34166L8.82508 9.99999L4.16675 14.6583L5.34175 15.8333L10.0001 11.175L14.6584 15.8333L15.8334 14.6583L11.1751 9.99999L15.8334 5.34166Z', fill: 'currentColor' })));
@@ -11,6 +13,11 @@ export default function PiaModal({ initialQuestions, handleSubmitQuestion, handl
     const [isOpen, setIsOpen] = useState(false);
     const dialogRef = useRef(null);
     const triggerRef = useRef(null);
+    const initialFocusRef = useRef(null);
+    const inputNodeRef = useRef(null);
+    const setInputNode = useCallback((node) => {
+        inputNodeRef.current = node;
+    }, []);
     const openModal = useCallback(() => {
         const active = document.activeElement;
         const isRealTrigger = !!active && active !== document.body && active !== document.documentElement;
@@ -27,6 +34,7 @@ export default function PiaModal({ initialQuestions, handleSubmitQuestion, handl
             return undefined;
         if (isOpen) {
             dialog.showModal();
+            initialFocusRef.current = document.activeElement;
             document.body.classList.add(OVERFLOW_HIDDEN_CLASS);
         }
         else {
@@ -38,6 +46,18 @@ export default function PiaModal({ initialQuestions, handleSubmitQuestion, handl
             document.body.classList.remove(OVERFLOW_HIDDEN_CLASS);
         };
     }, [isOpen]);
+    // The input is disabled when the dialog opens, so showModal() parks focus on the first enabled
+    // control. Hand it to the input once the answer has loaded, unless the shopper has moved it.
+    useEffect(() => {
+        if (!isOpen || isLoading || !initialFocusRef.current)
+            return;
+        const placed = initialFocusRef.current;
+        initialFocusRef.current = null;
+        const active = document.activeElement;
+        if (active !== placed && active !== document.body)
+            return;
+        inputNodeRef.current?.focus();
+    }, [isOpen, isLoading]);
     // Restore focus to the trigger. Re-runs on `isLoading`: the input trigger is
     // disabled while a request is in flight and `focus()` would no-op.
     useEffect(() => {
@@ -89,5 +109,6 @@ export default function PiaModal({ initialQuestions, handleSubmitQuestion, handl
                     React.createElement("p", { className: 'cio-pia-title', id: 'cio-pia-modal-title' }, translate('Ask about this product', translations)),
                     React.createElement("button", { type: 'button', className: 'cio-pia-modal-close-button', "aria-label": translate('Close', translations), onClick: closeModal },
                         React.createElement(CloseIcon, null))),
-                React.createElement("div", { className: 'cio-pia-modal-body' }, children)))));
+                React.createElement("div", { className: 'cio-pia-modal-body' },
+                    React.createElement(ModalInputRefContext.Provider, { value: setInputNode }, children))))));
 }

package/lib/mjs/hooks/useAnswerResults.js

@@ -11,34 +11,50 @@ export default function useAnswerResults({ itemId, variationId, threadId, cioCli
     useEffect(() => {
         cioClientRef.current = cioClient;
     }, [cioClient]);
+    const requestIdRef = useRef(0);
     const fetchResult = useCallback((question) => {
         const client = cioClientRef.current;
         if (!client)
             return;
+        requestIdRef.current += 1;
+        const requestId = requestIdRef.current;
+        const isCurrent = () => requestId === requestIdRef.current;
         setIsLoading(true);
         setError(null);
         setAnswerResults(null);
         client.agent.pia
             .getAnswerResults(itemId, question, { threadId, variationId, ...parameters })
             .then((response) => {
+            if (!isCurrent())
+                return;
             setAnswerResults(response);
             setError(null);
         })
             .catch((err) => {
+            if (!isCurrent())
+                return;
             setError(err instanceof Error ? err : new Error('Error fetching answer'));
             setAnswerResults(null);
         })
             .finally(() => {
-            setIsLoading(false);
+            if (isCurrent())
+                setIsLoading(false);
         });
     }, 
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [itemId, variationId, threadId, serializedParameters]);
+    const clear = useCallback(() => {
+        requestIdRef.current += 1;
+        setAnswerResults(null);
+        setError(null);
+        setIsLoading(false);
+    }, []);
     return {
         data: answerResults,
         items,
         isLoading,
         error,
         getAnswer: fetchResult,
+        clear,
     };
 }

package/lib/mjs/hooks/useCioPia.js

@@ -37,12 +37,13 @@ function mapDeprecatedParameters(params) {
     return hasEntries ? mapped : undefined;
 }
 export default function useCioPia(props) {
-    const { apiKey, itemId, variationId, threadId: providedThreadId, cioClient: providedClient, suggestedQuestionsParameters, answerParameters, parameters, formatImageUrl, testCells, } = props;
+    const { apiKey, itemId, variationId, threadId: providedThreadId, cioClient: providedClient, suggestedQuestionsParameters, answerParameters, parameters, formatImageUrl, testCells, userId, } = props;
     const { cioClient: client, threadId } = usePiaClient({
         apiKey,
         threadId: providedThreadId,
         cioClient: providedClient,
         testCells,
+        userId,
     });
     const mappedDeprecated = mapDeprecatedParameters(parameters);
     const mergedSuggestedParams = mappedDeprecated || suggestedQuestionsParameters

package/lib/mjs/hooks/useConversation.js

@@ -1,12 +1,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-function isRestorableEntry(entry) {
-    if (typeof entry !== 'object' || entry === null)
-        return false;
-    const { question, answer, items } = entry;
-    return (typeof question === 'string' &&
-        typeof answer === 'string' &&
-        (items === undefined || items === null || Array.isArray(items)));
-}
+import { isRestorableEntry } from '../utils/conversationStorage';
+// `id` is the React key, so ids from outside the widget cannot be trusted to be unique.
+const renumber = (entries) => entries.map((entry, index) => ({ ...entry, id: index + 1 }));
 // The seed comes from the host's own storage, typed or not: a malformed one must not take the widget down.
 function restoreHistory(seed) {
     if (!Array.isArray(seed)) {
@@ -17,21 +12,27 @@ function restoreHistory(seed) {
     if (entries.length < seed.length) {
         console.warn(`[CioPia] ${seed.length - entries.length} initialConversationHistory entries were ignored. Each needs a string question and answer, and items must be an array.`);
     }
-    // Seeded ids are replaced: `id` is the React key, so a caller's values cannot be trusted to be unique.
-    return entries.map((entry, index) => ({ ...entry, id: index + 1 }));
+    return renumber(entries);
+}
+function initialHistory(isConversation, seed, persisted) {
+    if (!isConversation)
+        return [];
+    if (seed !== undefined)
+        return restoreHistory(seed);
+    return persisted ? renumber(persisted.history) : [];
 }
-export default function useConversation({ pia, itemId, isConversation, callbacks, tracking, initialConversationHistory, }) {
+export default function useConversation({ pia, itemId, isConversation, callbacks, tracking, initialConversationHistory, persisted, }) {
     const { suggestedQuestions, answers, threadId } = pia;
     const { getAnswer } = answers;
     const context = useMemo(() => ({ itemId, threadId }), [itemId, threadId]);
     const [currentQuestion, setCurrentQuestion] = useState('');
     const [displayedQuestions, setDisplayedQuestions] = useState([]);
-    const [conversationHistory, setConversationHistory] = useState(() => isConversation && initialConversationHistory !== undefined
-        ? restoreHistory(initialConversationHistory)
-        : []);
+    const [conversationHistory, setConversationHistory] = useState(() => initialHistory(isConversation, initialConversationHistory, persisted));
     const entryIdRef = useRef(conversationHistory.length);
     const conversationHistoryRef = useRef(conversationHistory);
     const prevItemIdRef = useRef(itemId);
+    const persistedRef = useRef(persisted);
+    const prevPersistedKeyRef = useRef(persisted?.key);
     const prevAnswerDataRef = useRef(answers.data);
     const hasTrackedCurrentAnswerRef = useRef(false);
     const answersRef = useRef(answers);
@@ -58,6 +59,9 @@ export default function useConversation({ pia, itemId, isConversation, callbacks
     useEffect(() => {
         conversationHistoryRef.current = conversationHistory;
     }, [conversationHistory]);
+    useEffect(() => {
+        persistedRef.current = persisted;
+    }, [persisted]);
     const submitQuestion = useCallback((question, source) => {
         lastSourceRef.current = source;
         lastQuestionRef.current = question;
@@ -94,7 +98,9 @@ export default function useConversation({ pia, itemId, isConversation, callbacks
     const resetState = useCallback(() => {
         setCurrentQuestion('');
         setDisplayedQuestions(suggestedQuestions.data);
-        setConversationHistory([]);
+        // A stored conversation outlives the modal: it is there again when the modal reopens.
+        if (!persistedRef.current)
+            setConversationHistory([]);
         prevAnswerDataRef.current = null;
         showsFollowUpsRef.current = false;
     }, [suggestedQuestions.data]);
@@ -109,6 +115,19 @@ export default function useConversation({ pia, itemId, isConversation, callbacks
         prevAnswerDataRef.current = null;
         showsFollowUpsRef.current = false;
     }, [itemId]);
+    useEffect(() => {
+        // Runs after the itemId reset above, so another product's stored conversation replaces the empty one.
+        if (!persisted || prevPersistedKeyRef.current === persisted.key)
+            return;
+        prevPersistedKeyRef.current = persisted.key;
+        // The live answer belongs to the conversation being replaced: left in place, the restored last
+        // turn would show its products and credit its feedback.
+        answersRef.current.clear();
+        const restored = renumber(persisted.history);
+        entryIdRef.current = restored.length;
+        setConversationHistory(restored);
+        setCurrentQuestion('');
+    }, [persisted]);
     useEffect(() => {
         // The ref, not `answers.data`, which outlives the item it answered.
         if (showsFollowUpsRef.current)
@@ -140,7 +159,9 @@ export default function useConversation({ pia, itemId, isConversation, callbacks
         const qnaResultId = answers.data?.qna_result_id;
         if (isConversation) {
             setConversationHistory((prev) => {
-                if (prev.length === 0)
+                // Only a question still waiting is answered: after a switch of product or shopper, a late
+                // answer must not overwrite a settled turn of the conversation that replaced it.
+                if (prev.length === 0 || prev[prev.length - 1].answer !== '')
                     return prev;
                 const updated = [...prev];
                 updated[updated.length - 1] = {
@@ -151,6 +172,7 @@ export default function useConversation({ pia, itemId, isConversation, callbacks
                     qnaResultId,
                 };
                 callbacksRef.current?.onAnswer?.(updated, contextRef.current);
+                persistedRef.current?.save(updated);
                 return updated;
             });
         }

package/lib/mjs/hooks/usePersistedConversation.js

@@ -0,0 +1,73 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { isGuest, loadConversation, moveGuestConversations, saveConversation, } from '../utils/conversationStorage';
+function loadIfEnabled({ enabled, apiKey, userId, itemId, threadIdProp, }) {
+    if (!enabled)
+        return { threadId: '', history: [] };
+    const stored = loadConversation({ apiKey, userId }, itemId);
+    if (stored && (!threadIdProp || stored.threadId === threadIdProp)) {
+        return { threadId: stored.threadId, history: stored.entries };
+    }
+    // A product with nothing stored starts its own thread, so returning to another product resumes
+    // a thread that only ever heard about that product.
+    return { threadId: threadIdProp || crypto.randomUUID(), history: [] };
+}
+/** The stored conversation for this product and shopper, or `undefined` while persistence is off. */
+export default function usePersistedConversation({ enabled, apiKey, userId: userIdProp, itemId, threadId: threadIdProp, }) {
+    const userId = isGuest(userIdProp) ? undefined : String(userIdProp);
+    const userIdOmitted = userIdProp === undefined;
+    // An omitted id stores a signed-in shopper as a guest, so say so rather than fail silently.
+    useEffect(() => {
+        if (!enabled || !userIdOmitted)
+            return;
+        console.warn('[CioPia] persistConversation is on but no userId was passed, so conversations are stored as a guest. Pass the signed-in shopper id, or null for a guest.');
+    }, [enabled, userIdOmitted]);
+    const target = { enabled, apiKey, userId, itemId, threadIdProp };
+    const [shown, setShown] = useState(() => ({
+        ...target,
+        key: 0,
+        loggedIn: false,
+        ...loadIfEnabled(target),
+    }));
+    // Adjusted during render, not in an effect: React re-renders before committing, so the first
+    // request after a switch of product or shopper already goes out on the new thread. See
+    // https://react.dev/learn/you-might-not-need-an-effect#adjusting-some-state-when-a-prop-changes
+    let current = shown;
+    if (shown.enabled !== enabled ||
+        shown.apiKey !== apiKey ||
+        shown.userId !== userId ||
+        shown.itemId !== itemId ||
+        shown.threadIdProp !== threadIdProp) {
+        const loggedIn = enabled &&
+            shown.enabled &&
+            shown.apiKey === apiKey &&
+            shown.userId === undefined &&
+            userId !== undefined;
+        // A login continues the guest's conversation as the shopper's own. With none to carry over,
+        // the shopper's own stored conversation is shown, rather than replaced by an empty one.
+        const keepsConversation = loggedIn &&
+            shown.itemId === itemId &&
+            shown.threadIdProp === threadIdProp &&
+            loadConversation({ apiKey }, itemId) !== undefined;
+        const conversation = keepsConversation
+            ? { key: shown.key, threadId: shown.threadId, history: shown.history }
+            : { key: shown.key + 1, ...loadIfEnabled(target) };
+        current = { ...target, loggedIn, ...conversation };
+        setShown(current);
+    }
+    useEffect(() => {
+        if (shown.loggedIn && shown.userId)
+            moveGuestConversations(shown.apiKey, shown.userId);
+    }, [shown]);
+    const shownRef = useRef(shown);
+    useEffect(() => {
+        shownRef.current = shown;
+    }, [shown]);
+    const save = useCallback((history) => {
+        const latest = shownRef.current;
+        if (!latest.enabled)
+            return;
+        saveConversation({ apiKey: latest.apiKey, userId: latest.userId }, latest.itemId, latest.threadId, history);
+    }, []);
+    const { key, threadId, history } = current;
+    return useMemo(() => (current.enabled ? { key, threadId, history, save } : undefined), [current.enabled, key, threadId, history, save]);
+}