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

package/lib/mjs/utils/localStoragePersistence.js

@@ -64,21 +64,31 @@ const emptyStored = () => ({
     threads: {},
     deleted: {},
 });
-function parseStored(raw) {
-    if (!raw)
-        return emptyStored();
+/** The record `raw` holds, or `null` when it is not one of this version. */
+function readStored(raw) {
     try {
         const parsed = JSON.parse(raw);
         if (parsed?.version !== PERSISTED_CHAT_VERSION || !parsed.threads)
-            return emptyStored();
+            return null;
         const threads = Object.fromEntries(Object.entries(parsed.threads).filter(([, chat]) => isPersistedChat(chat)));
         const deleted = Object.fromEntries(Object.entries(parsed.deleted ?? {}).filter(([, at]) => typeof at === 'number'));
         return { version: PERSISTED_CHAT_VERSION, threads, deleted };
     }
     catch {
-        return emptyStored();
+        return null;
     }
 }
+function parseStored(raw) {
+    return (raw && readStored(raw)) || emptyStored();
+}
+function dropExpired(data, cutoff) {
+    return {
+        version: PERSISTED_CHAT_VERSION,
+        threads: Object.fromEntries(Object.entries(data.threads).filter(([, chat]) => chat.updatedAt >= cutoff)),
+        deleted: Object.fromEntries(Object.entries(data.deleted ?? {}).filter(([, at]) => at >= cutoff)),
+    };
+}
+const entryCount = (data) => Object.keys(data.threads).length + Object.keys(data.deleted ?? {}).length;
 function readItem(storage, key) {
     try {
         return storage.getItem(key);
@@ -87,6 +97,42 @@ function readItem(storage, key) {
         return null;
     }
 }
+/** How often a write is redone when another tab changed the key between its read and its write. */
+const MAX_COMMIT_ATTEMPTS = 3;
+/** Drops expired threads and tombstones under every namespace of `key`, other shoppers' included. */
+async function sweepExpired(storage, key, ttlMs) {
+    const prefix = storageKeyFor(key);
+    let keys;
+    try {
+        keys = Array.from({ length: storage.length }, (_, i) => storage.key(i)).filter((k) => k === prefix || Boolean(k?.startsWith(`${prefix}:`)));
+    }
+    catch {
+        return;
+    }
+    await Promise.all(keys.map((k) => withStorageLock(k, () => {
+        for (let attempt = 0; attempt < MAX_COMMIT_ATTEMPTS; attempt += 1) {
+            const raw = readItem(storage, k);
+            const stored = raw === null ? null : readStored(raw);
+            if (!stored)
+                return;
+            const kept = dropExpired(stored, Date.now() - ttlMs);
+            if (entryCount(kept) === entryCount(stored))
+                return;
+            if (readItem(storage, k) === raw) {
+                try {
+                    if (entryCount(kept) === 0)
+                        storage.removeItem(k);
+                    else
+                        storage.setItem(k, JSON.stringify(kept));
+                }
+                catch {
+                    /* storage unavailable */
+                }
+                return;
+            }
+        }
+    })));
+}
 /**
  * Deletes every stored conversation of one shopper, or of the guest without `userId`; open tabs
  * follow. Resolves once the deletion is recorded.
@@ -132,6 +178,23 @@ export async function clearPersistedConversations(options) {
         /* a non-Storage `storage` option cannot be attached to the event */
     }
 }
+/** The channel abort requests travel on between tabs, or `null` where none can be opened. */
+function openAbortChannel(name, onRequest) {
+    if (typeof window === 'undefined' || typeof BroadcastChannel === 'undefined')
+        return null;
+    try {
+        const channel = new BroadcastChannel(name);
+        channel.onmessage = ({ data }) => {
+            if (typeof data?.threadId !== 'string' || typeof data?.messageId !== 'string')
+                return;
+            onRequest({ threadId: data.threadId, messageId: data.messageId });
+        };
+        return channel;
+    }
+    catch {
+        return null;
+    }
+}
 /** Conversation store on top of `localStorage`; one key per namespace, merged across tabs. */
 export function createLocalStoragePersistence(options = {}) {
     const { key = DEFAULT_PERSISTENCE_KEY, namespace, ttlMs = DEFAULT_PERSISTENCE_TTL_MS, maxTurns = Infinity, maxThreads = Infinity, storageArea = 'local', storage: storageOption, } = options;
@@ -144,15 +207,20 @@ export function createLocalStoragePersistence(options = {}) {
             return emptyStored();
         if (lastParsed?.raw !== raw)
             lastParsed = { raw, data: parseStored(raw) };
-        const cutoff = Date.now() - ttlMs;
-        const { data } = lastParsed;
-        return {
-            version: PERSISTED_CHAT_VERSION,
-            threads: Object.fromEntries(Object.entries(data.threads).filter(([, chat]) => chat.updatedAt >= cutoff)),
-            deleted: Object.fromEntries(Object.entries(data.deleted ?? {}).filter(([, at]) => at >= cutoff)),
-        };
+        return dropExpired(lastParsed.data, Date.now() - ttlMs);
+    };
+    // Other shoppers' records expire only here: their own store may never run again on this device.
+    let swept = false;
+    const sweepOnce = () => {
+        if (swept)
+            return;
+        swept = true;
+        const local = resolveStorage(storageOption, 'local');
+        if (local)
+            sweepExpired(local, key, ttlMs).catch(() => { });
     };
     const read = () => {
+        sweepOnce();
         const storage = resolveStorage(storageOption, storageArea);
         return parse(storage ? readRaw(storage) : null);
     };
@@ -174,7 +242,7 @@ export function createLocalStoragePersistence(options = {}) {
             /* ignore */
         }
     };
-    const isEmpty = (data) => Object.keys(data.threads).length === 0 && Object.keys(data.deleted ?? {}).length === 0;
+    const isEmpty = (data) => entryCount(data) === 0;
     // Retries without tombstones, oldest first: the last thing to shed, see `write`.
     const tryWriteShedding = (storage, data) => {
         if (tryWrite(storage, data))
@@ -238,8 +306,8 @@ export function createLocalStoragePersistence(options = {}) {
             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) => {
+        sweepOnce();
         const storage = resolveStorage(storageOption, storageArea);
         if (!storage)
             return;
@@ -297,6 +365,29 @@ export function createLocalStoragePersistence(options = {}) {
         }
         return next;
     };
+    const abortListeners = new Set();
+    // Only `localStorage` is shared between tabs; a guest's `sessionStorage` thread streams in this tab alone.
+    const channel = storageArea === 'local'
+        ? openAbortChannel(`${storageKey}:abort`, (request) => abortListeners.forEach((listener) => listener(request)))
+        : null;
+    const abortMethods = channel
+        ? {
+            requestAbort(threadId, messageId) {
+                try {
+                    channel.postMessage({ threadId, messageId });
+                }
+                catch {
+                    /* channel closed */
+                }
+            },
+            subscribeAbort(listener) {
+                abortListeners.add(listener);
+                return () => {
+                    abortListeners.delete(listener);
+                };
+            },
+        }
+        : {};
     const retire = (data, staleId) => {
         const { [staleId]: retired, ...threads } = data.threads;
         return { ...data, threads, deleted: { ...data.deleted, [staleId]: Date.now() } };
@@ -352,6 +443,7 @@ export function createLocalStoragePersistence(options = {}) {
             window.addEventListener('storage', onStorage);
             return () => window.removeEventListener('storage', onStorage);
         },
+        ...abortMethods,
     };
 }
 const sharedStores = new Map();

package/lib/mjs/utils/markdown.js

@@ -0,0 +1,53 @@
+import DOMPurify from 'dompurify';
+import { marked } from 'marked';
+// The text comes from an LLM a shopper can steer, so only the tags `marked` outputs are kept.
+// Images, media and SVG would load a URL with no click and could leak data; form controls and
+// `style` could fake a form.
+const purifyConfig = {
+    ALLOWED_TAGS: 'p br strong em del a ul ol li blockquote hr code pre table thead tbody tr th td h1 h2 h3 h4 h5 h6'.split(' '),
+    ALLOWED_ATTR: ['href', 'tabindex', 'align', 'start'],
+};
+// Text the agent reads (catalog, knowledge base, reviews) could plant a phishing link, so only
+// links to this site, its subdomains, email and phone stay clickable.
+function isOnThisSite(href) {
+    try {
+        const url = new URL(href, window.location.href);
+        if (url.protocol === 'mailto:' || url.protocol === 'tel:')
+            return true;
+        if (url.protocol !== 'http:' && url.protocol !== 'https:')
+            return false;
+        const site = window.location.hostname.replace(/^www\./, '');
+        return url.hostname === site || url.hostname.endsWith(`.${site}`);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Turns the agent's markdown into sanitized HTML: paragraphs, bold, links, lists and tables.
+ * Links to other sites become plain text. Browser only: without a DOM to sanitize with (server
+ * rendering) it returns `''`, so render the plain text instead.
+ */
+export function renderMarkdown(markdown) {
+    if (!markdown || !DOMPurify.isSupported)
+        return '';
+    const html = marked.parse(markdown, { async: false, breaks: true })
+        // A wide table scrolls (AiMessage.css), so keyboard users need to be able to focus it.
+        .replace(/<table>/g, '<table tabindex="0">');
+    const doc = new DOMParser().parseFromString(DOMPurify.sanitize(html, purifyConfig), 'text/html');
+    doc.querySelectorAll('a[href]').forEach((link) => {
+        if (!isOnThisSite(link.getAttribute('href')))
+            link.replaceWith(...Array.from(link.childNodes));
+    });
+    return doc.body.innerHTML;
+}
+/** The agent's markdown as plain text, one space between blocks and table cells, for screen readers. */
+export function markdownToText(markdown) {
+    const html = renderMarkdown(markdown);
+    if (!html)
+        return markdown;
+    // An inert document: nothing in it loads or runs.
+    const { body } = new DOMParser().parseFromString(html, 'text/html');
+    body.querySelectorAll('p, li, th, td, br').forEach((node) => node.append(' '));
+    return (body.textContent ?? '').replace(/\s+/g, ' ').trim();
+}

package/lib/mjs/version.js

@@ -1 +1 @@
-export default '1.9.0';
+export default '1.10.0';

package/lib/types/hooks/persistence/backgroundTurns.d.ts

@@ -15,6 +15,7 @@ export declare class BackgroundTurn {
     readonly ids: Set<string>;
     /** Its writes, in order; a chat that takes the turn back writes after them. */
     writes: Promise<void>;
+    private stopListening?;
     constructor(turn: LiveTurn, params: {
         store: ChatPersistence;
         session: ChatSession;
@@ -24,6 +25,11 @@ export declare class BackgroundTurn {
     save(): Promise<void>;
     /** Later writes go into `store`. */
     moveTo(store: ChatPersistence): void;
+    /** Stops the answer when another tab asks to, through the store it is saved into. */
+    listen(): void;
+    release(): void;
+    /** Stops the answer and stores it settled, as the stop button does on screen. */
+    abort(): void;
     /** Stores the conversation settled, without awaiting: the page is going away. */
     flush(): void;
 }

package/lib/types/hooks/persistence/useChatPersistence.d.ts

@@ -18,6 +18,8 @@ interface Params {
     turnRef: MutableRefObject<LiveTurn | null>;
     /** Stop the answer currently streaming in this tab, if any. */
     cancelStream: () => void;
+    /** Stop this tab's answer as the stop button does: settled and stored. */
+    abortTurn: () => void;
 }
 /** Restores, saves and syncs the conversation with `store`; inert when `store` is undefined. */
 export default function useChatPersistence(params: Params): {
@@ -25,6 +27,8 @@ export default function useChatPersistence(params: Params): {
     threads: import("../../types").ThreadSummary[];
     activeThreadId: string | null;
     foreignInFlight: boolean;
+    canAbortForeign: boolean;
+    abortForeign: () => void;
     beginTurn: () => void;
     screenOwner: (turn: LiveTurn) => TurnOwner;
     clearHistory: () => void;

package/lib/types/index.d.ts

@@ -13,6 +13,7 @@ export { default as useCioAsaContext } from './hooks/useCioAsaContext';
 export type { UseAsaTrackingProps, UseAsaTrackingReturn, TrackAgentButtonClickArgs, } from './hooks/useAsaTracking';
 export { normalizeItemToProduct } from './utils/productNormalizer';
 export { clearPersistedConversations } from './utils/localStoragePersistence';
+export { renderMarkdown } from './utils/markdown';
 export type { Product, NormalizeOptions } from './utils/productNormalizer';
 export { ConstructorIOClient } from './types';
 export type { Nullable, CioAsaProviderProps, PersistConversationOptions, AsaContextValue, CioClientOptions, RequestConfigs, Formatters, UrlHelpers, QueryParamEncodingOptions, DefaultQueryStringMap, Translations, ChatMessage, ChatMessageStatus, FollowUpRefinement, ResultGroup, ResultGroupMeta, SearchResultEventRequest, UseAsaResultsOptions, UseChatReturn, SendMessageOptions, ClearPersistedConversationsOptions, ThreadSummary, AsaCallbacks, AssistantSubmitSource, AssistantTrackedItem, AgentButtonClickMode, AgentButtonClickPayload, AgentButtonClickPageType, AgentButtonClickPlacement, ChatComponentOverrides, WelcomeScreenOverrides, ChatInputOverrides, AiMessageOverrides, ResultsBlockOverrides, ComponentOverrideProps, IncludeComponentOverrides, ChatHeaderRenderProps, ChatInputRenderProps, WelcomeScreenTitleRenderProps, WelcomeScreenInputRenderProps, SuggestedQuestionsRenderProps, UserMessageRenderProps, AiMessageLoaderRenderProps, AiMessageTextRenderProps, FollowUpRefinementRenderProps, ResultsGroupTitleRenderProps, ResultsViewMoreRenderProps, } from './types';

package/lib/types/types.d.ts

@@ -193,7 +193,10 @@ export interface UseChatReturn {
     sendMessage: (text: string, source?: AssistantSubmitSource, options?: SendMessageOptions) => void;
     /** True while an answer is streaming, here or, with persistence on, in another tab on the same thread. */
     isStreaming: boolean;
-    /** True while this tab's own answer is streaming, the one `abort` can stop. */
+    /**
+     * True while `abort` can stop the answer: this tab's own, or, when the store can reach it, one
+     * streaming in another tab.
+     */
     canAbort: boolean;
     /**
      * Cancel the in-flight request, keeping the conversation. The partial reply is settled
@@ -270,6 +273,18 @@ export interface ChatPersistence {
      * Returns an unsubscribe function.
      */
     subscribe?(listener: () => void): () => void;
+    /** Optional. Ask the tab streaming `messageId` into `threadId` to stop it. */
+    requestAbort?(threadId: string, messageId: string): void;
+    /**
+     * Optional. Notify when another tab asks to stop an answer, see `requestAbort`. Returns an
+     * unsubscribe function. Without both, an answer streaming in another tab cannot be stopped.
+     */
+    subscribeAbort?(listener: (request: AbortRequest) => void): () => void;
+}
+/** Another tab asks to stop the answer `messageId` streaming into `threadId`. */
+export interface AbortRequest {
+    threadId: string;
+    messageId: string;
 }
 /** Which stored history `clearPersistedConversations` deletes; mirror what the provider was given. */
 export interface ClearPersistedConversationsOptions {
@@ -416,12 +431,13 @@ export interface ChatInputRenderProps {
     onSubmit: () => void;
     placeholder: string;
     isDisabled: boolean;
+    /** Whether a reply is currently streaming, here or in another tab; for status and disabled state. */
+    isStreaming: boolean;
     /**
-     * Whether a reply is currently streaming. Pair it with `onAbort` to offer a cancel
-     * control while it is true — the built-in stop button is off by default, so an override
-     * is often the only way a user can cancel.
+     * Whether `onAbort` can stop the reply streaming now; show a cancel control only then. The
+     * built-in stop button is off by default, so an override is often the only way a user can cancel.
      */
-    isStreaming: boolean;
+    canAbort: boolean;
     /** Cancel the in-flight reply. Keeps the conversation and the thread. */
     onAbort: () => void;
 }

package/lib/types/utils/chatThreads.d.ts

@@ -8,6 +8,8 @@ export declare const DEFAULT_PERSISTENCE_KEY = "cio-asa:chat";
 export declare const DEFAULT_PERSISTENCE_TTL_MS: number;
 /** How long a stored answer written by another tab is still shown as "typing" before it is settled. */
 export declare const IN_FLIGHT_GRACE_MS: number;
+/** How long to wait for the tab streaming an answer to store it stopped, before settling it here. */
+export declare const FOREIGN_ABORT_TIMEOUT_MS: number;
 /** Random token for the ids that must not collide between tabs: threads, tabs and messages. */
 export declare function randomId(): string;
 /** Client-side thread id for a conversation the server has not named yet. */
@@ -28,6 +30,8 @@ export declare function nextMessageCounter(messages: ChatMessage[]): number;
 export declare function isInFlight(messages: ChatMessage[]): boolean;
 /** Settles answers stored mid-stream: `done` when they have content, an interrupted `error` otherwise. */
 export declare function normalizeHydratedMessages(messages: ChatMessage[]): ChatMessage[];
+/** `messages` with the cancelled reply settled: `done` when it has content, dropped otherwise. */
+export declare function settleCancelledReply(messages: ChatMessage[], assistantId: string): ChatMessage[];
 /** Makes the product card for a raw search-result item. */
 export type ItemNormalizer = (item: Record<string, unknown>) => Product;
 /** Messages as stored: raw items replaced by the cards `normalize` makes; a restored group keeps its cards. */

package/lib/types/utils/markdown.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Turns the agent's markdown into sanitized HTML: paragraphs, bold, links, lists and tables.
+ * Links to other sites become plain text. Browser only: without a DOM to sanitize with (server
+ * rendering) it returns `''`, so render the plain text instead.
+ */
+export declare function renderMarkdown(markdown: string): string;
+/** The agent's markdown as plain text, one space between blocks and table cells, for screen readers. */
+export declare function markdownToText(markdown: string): string;

package/lib/types/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "1.9.0";
+declare const _default: "1.10.0";
 export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructor-io/constructorio-ui-asa",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Constructor.io AI Shopping Agent UI library for web applications",
   "author": "constructor.io",
   "license": "MIT",
@@ -148,5 +148,9 @@
   "volta": {
     "node": "22.18.0",
     "npm": "10.9.3"
+  },
+  "dependencies": {
+    "dompurify": "3.4.17",
+    "marked": "15.0.12"
   }
 }