@clivly/chat-widget 0.16.0 → 0.17.0

package/dist/browser.mjs

@@ -1,7 +1,7 @@
 import { createRoot } from "react-dom/client";
 import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-//#region src/theme.ts
+// src/theme.ts
 const DARK_MEDIA_QUERY = "(prefers-color-scheme: dark)";
 /** The attribute set by next-themes, daisyUI, and most `data-*` theme setups. */
 const THEME_ATTRIBUTE = "data-theme";
@@ -109,8 +109,51 @@ function parseTheme(value) {
 	if (value === "auto" || value === "dark" || value === "light") return value;
 	return "auto";
 }
-//#endregion
-//#region src/chat-widget.tsx
+// src/visitor-token-storage.ts
+/** Normalised the way the server matches contacts: trimmed, lower-case. */
+function normalizeVisitorEmail(email) {
+	return email.trim().toLowerCase();
+}
+const HASH_MODULUS = 4294967291;
+/**
+* A polynomial string hash, reduced mod a prime below 2^32: stable,
+* synchronous, and exact in doubles (every intermediate stays under 2^53).
+* Not a security primitive.
+*/
+function shortHash(value) {
+	let hash = 5381;
+	for (const char of value) hash = (hash * 33 + (char.codePointAt(0) ?? 0)) % HASH_MODULUS;
+	return hash.toString(16).padStart(8, "0");
+}
+function visitorTokenKey(widgetId, email) {
+	return `clivly-chat-widget:${widgetId}:visitor-token:${shortHash(normalizeVisitorEmail(email))}`;
+}
+/** The single per-widget key every widget before this change wrote. */
+function legacyVisitorTokenKey(widgetId) {
+	return `clivly-chat-widget:${widgetId}:visitor-token`;
+}
+/**
+* The token to offer for this person. Falls back to the legacy per-widget
+* token once, so visitors who chatted before this change still resume — the
+* server only honours it if they are the identity that thread belongs to.
+*/
+function readVisitorToken(storage, widgetId, email) {
+	if (!storage) return null;
+	try {
+		return storage.getItem(visitorTokenKey(widgetId, email)) ?? storage.getItem(legacyVisitorTokenKey(widgetId));
+	} catch {
+		return null;
+	}
+}
+/** Store this person's token and retire the legacy shared one. */
+function writeVisitorToken(storage, widgetId, email, token) {
+	if (!storage) return;
+	try {
+		storage.setItem(visitorTokenKey(widgetId, email), token);
+		storage.removeItem?.(legacyVisitorTokenKey(widgetId));
+	} catch {}
+}
+// src/chat-widget.tsx
 const DELIVERY_LABELS = {
 	failed: "Failed to send",
 	pending: "Sending…",
@@ -532,9 +575,6 @@ function createLocalMessage(message, delivery = "sent") {
 		delivery
 	};
 }
-function createStorageKey(widgetId) {
-	return `clivly-chat-widget:${widgetId}:visitor-token`;
-}
 function formatTimestamp(value) {
 	const date = new Date(value);
 	if (Number.isNaN(date.getTime())) return "";
@@ -960,6 +1000,33 @@ function useLiveConnection({ actions, createTransport, refreshSession, session,
 	}, [createTransport, session]);
 	return reconnecting;
 }
+/** Who the host says is signed in: their normalised email, or null. */
+function hostIdentityOf(defaultVisitor) {
+	return isCompleteVisitor(defaultVisitor) ? normalizeVisitorEmail(defaultVisitor.email) : null;
+}
+/**
+* The host's signed-in visitor changed under an open session — a sign-out, or
+* a different account signing in without a page reload. The session on
+* screen is the previous person's: drop it, its transcript and its socket, so
+* the next open starts as whoever is signed in now (chat widget session
+* review 2026-10-28, S1). A session the visitor started from the pre-chat
+* form is theirs and is left alone.
+*/
+function useResetOnHostIdentityChange({ generationRef, hostIdentity, identityRef, reset, sessionSourceRef }) {
+	const resetRef = useRef(reset);
+	useEffect(() => {
+		resetRef.current = reset;
+	});
+	useEffect(() => {
+		const current = identityRef.current;
+		if (!(current && sessionSourceRef.current === "host")) return;
+		if (hostIdentity === normalizeVisitorEmail(current.email)) return;
+		generationRef.current += 1;
+		identityRef.current = null;
+		sessionSourceRef.current = null;
+		resetRef.current();
+	}, [hostIdentity]);
+}
 function ChatWidget({ className, createTransport, defaultVisitor, getSession, initiallyOpen = false, launcher = "auto", launcherLabel = "Chat with us", placement = "bottom-right", storage = DEFAULT_STORAGE, style, theme = "auto", widgetId }) {
 	const [isOpen, setIsOpen] = useState(initiallyOpen);
 	const panelId = useId();
@@ -978,6 +1045,11 @@ function ChatWidget({ className, createTransport, defaultVisitor, getSession, in
 	const transportRef = useRef(null);
 	const listRef = useRef(null);
 	const identityRef = useRef(null);
+	const sessionSourceRef = useRef(null);
+	const generationRef = useRef(0);
+	const hostIdentity = hostIdentityOf(defaultVisitor);
+	const latestHostIdentityRef = useRef(hostIdentity);
+	latestHostIdentityRef.current = hostIdentity;
 	useEffect(() => {
 		if (createTransport) return;
 		console.warn("[clivly] <ChatWidget> was given no createTransport, so messages cannot be sent. Pass createTransport={createClivlyTransport()} — see https://www.npmjs.com/package/@clivly/chat-widget#five-minute-quick-start");
@@ -1004,12 +1076,14 @@ function ChatWidget({ className, createTransport, defaultVisitor, getSession, in
 		refreshSession: async (current) => {
 			const identity = identityRef.current;
 			if (!identity) throw new Error("No visitor to reconnect as.");
+			const generation = generationRef.current;
 			const next = await getSession({
 				visitor: identity,
 				visitorToken: current.visitorToken,
 				widgetId
 			});
-			storage?.setItem(createStorageKey(widgetId), next.visitorToken);
+			if (generation !== generationRef.current) return;
+			writeVisitorToken(storage, widgetId, identity.email, next.visitorToken);
 			setSupportState(next.support?.state ?? null);
 			setSession(next);
 		},
@@ -1034,31 +1108,53 @@ function ChatWidget({ className, createTransport, defaultVisitor, getSession, in
 		isReady,
 		messages
 	]);
-	const startSession = useCallback(async (identity) => {
+	const startSession = useCallback(async (identity, source = "form") => {
 		setError(null);
 		setIsConnecting(true);
+		const generation = generationRef.current;
+		const isStale = () => generation !== generationRef.current || source === "host" && normalizeVisitorEmail(identity.email) !== latestHostIdentityRef.current;
 		try {
 			const nextSession = await getSession({
 				visitor: identity,
-				visitorToken: storage?.getItem(createStorageKey(widgetId)) ?? null,
+				visitorToken: readVisitorToken(storage, widgetId, identity.email),
 				widgetId
 			});
-			storage?.setItem(createStorageKey(widgetId), nextSession.visitorToken);
+			if (isStale()) return;
+			writeVisitorToken(storage, widgetId, identity.email, nextSession.visitorToken);
 			identityRef.current = identity;
+			sessionSourceRef.current = source;
 			setSupportState(nextSession.support?.state ?? null);
 			setSession(nextSession);
 			setMessages(sortMessages(nextSession.messages.map((message) => createLocalMessage(message))));
 		} catch (sessionError) {
+			if (isStale()) return;
 			const resolved = sessionError instanceof Error ? sessionError : /* @__PURE__ */ new Error("Failed to start the conversation.");
 			setError(resolved.message);
 		} finally {
-			setIsConnecting(false);
+			if (generation === generationRef.current) setIsConnecting(false);
 		}
 	}, [
 		getSession,
 		storage,
 		widgetId
 	]);
+	useResetOnHostIdentityChange({
+		generationRef,
+		hostIdentity,
+		identityRef,
+		reset: () => {
+			setSession(null);
+			setMessages([]);
+			setSupportState(null);
+			setError(null);
+			setIsConnecting(false);
+			setVisitor({
+				email: defaultVisitor?.email ?? "",
+				name: defaultVisitor?.name ?? ""
+			});
+		},
+		sessionSourceRef
+	});
 	const submitVisitor = async (event) => {
 		event.preventDefault();
 		await startSession(visitor);
@@ -1069,7 +1165,7 @@ function ChatWidget({ className, createTransport, defaultVisitor, getSession, in
 		startSession({
 			email: defaultVisitor.email.trim(),
 			name: defaultVisitor.name.trim()
-		}).catch(() => {});
+		}, "host").catch(() => {});
 	}, [
 		defaultVisitor,
 		error,
@@ -1298,8 +1394,7 @@ function ChatWidget({ className, createTransport, defaultVisitor, getSession, in
 		]
 	});
 }
-//#endregion
-//#region src/transport.ts
+// src/transport.ts
 function isServerEvent(value) {
 	if (typeof value !== "object" || value === null) return false;
 	return typeof value.type === "string";
@@ -1344,8 +1439,7 @@ function createWebSocketTransport({ createSocket = (url, protocols) => new WebSo
 		};
 	};
 }
-//#endregion
-//#region src/clivly-transport.ts
+// src/clivly-transport.ts
 /**
 * The transport a host app should use against a real Clivly backend.
 *
@@ -1362,8 +1456,7 @@ function createClivlyTransport(options = {}) {
 		}
 	});
 }
-//#endregion
-//#region src/layout.ts
+// src/layout.ts
 const PLACEMENTS = [
 	"bottom-left",
 	"bottom-right",
@@ -1382,8 +1475,7 @@ function parsePlacement(value) {
 function parseLauncher(value) {
 	return LAUNCHERS.find((launcher) => launcher === value) ?? "auto";
 }
-//#endregion
-//#region src/session.ts
+// src/session.ts
 function isWidgetSessionPayload(value) {
 	return typeof value === "object" && value !== null;
 }
@@ -1405,8 +1497,7 @@ function createSessionFetcher({ fetchImpl = fetch, sessionUrl }) {
 		return data;
 	};
 }
-//#endregion
-//#region src/browser-mount.tsx
+// src/browser-mount.tsx
 const MOUNTED_DATA_ATTR = "clivlyMounted";
 /**
 * The identity a script-tag host already knows, read off the tag.
@@ -1498,11 +1589,9 @@ function autoMountChatWidgetScript$1(script = document.currentScript) {
 	if (!script || scriptAlreadyMounted(script)) return null;
 	return mountChatWidgetScript$1(script);
 }
-//#endregion
-//#region src/browser.tsx
+// src/browser.tsx
 const mountChatWidget = mountChatWidget$1;
 const mountChatWidgetScript = mountChatWidgetScript$1;
 const autoMountChatWidgetScript = autoMountChatWidgetScript$1;
 if (typeof document !== "undefined") autoMountChatWidgetScript();
-//#endregion
 export { autoMountChatWidgetScript, mountChatWidget, mountChatWidgetScript };

package/dist/index.cjs

@@ -2,7 +2,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let react_dom_client = require("react-dom/client");
 let react = require("react");
 let react_jsx_runtime = require("react/jsx-runtime");
-//#region src/theme.ts
+// src/theme.ts
 const DARK_MEDIA_QUERY = "(prefers-color-scheme: dark)";
 /** The attribute set by next-themes, daisyUI, and most `data-*` theme setups. */
 const THEME_ATTRIBUTE = "data-theme";
@@ -110,8 +110,51 @@ function parseTheme(value) {
 	if (value === "auto" || value === "dark" || value === "light") return value;
 	return "auto";
 }
-//#endregion
-//#region src/chat-widget.tsx
+// src/visitor-token-storage.ts
+/** Normalised the way the server matches contacts: trimmed, lower-case. */
+function normalizeVisitorEmail(email) {
+	return email.trim().toLowerCase();
+}
+const HASH_MODULUS = 4294967291;
+/**
+* A polynomial string hash, reduced mod a prime below 2^32: stable,
+* synchronous, and exact in doubles (every intermediate stays under 2^53).
+* Not a security primitive.
+*/
+function shortHash(value) {
+	let hash = 5381;
+	for (const char of value) hash = (hash * 33 + (char.codePointAt(0) ?? 0)) % HASH_MODULUS;
+	return hash.toString(16).padStart(8, "0");
+}
+function visitorTokenKey(widgetId, email) {
+	return `clivly-chat-widget:${widgetId}:visitor-token:${shortHash(normalizeVisitorEmail(email))}`;
+}
+/** The single per-widget key every widget before this change wrote. */
+function legacyVisitorTokenKey(widgetId) {
+	return `clivly-chat-widget:${widgetId}:visitor-token`;
+}
+/**
+* The token to offer for this person. Falls back to the legacy per-widget
+* token once, so visitors who chatted before this change still resume — the
+* server only honours it if they are the identity that thread belongs to.
+*/
+function readVisitorToken(storage, widgetId, email) {
+	if (!storage) return null;
+	try {
+		return storage.getItem(visitorTokenKey(widgetId, email)) ?? storage.getItem(legacyVisitorTokenKey(widgetId));
+	} catch {
+		return null;
+	}
+}
+/** Store this person's token and retire the legacy shared one. */
+function writeVisitorToken(storage, widgetId, email, token) {
+	if (!storage) return;
+	try {
+		storage.setItem(visitorTokenKey(widgetId, email), token);
+		storage.removeItem?.(legacyVisitorTokenKey(widgetId));
+	} catch {}
+}
+// src/chat-widget.tsx
 const DELIVERY_LABELS = {
 	failed: "Failed to send",
 	pending: "Sending…",
@@ -533,9 +576,6 @@ function createLocalMessage(message, delivery = "sent") {
 		delivery
 	};
 }
-function createStorageKey(widgetId) {
-	return `clivly-chat-widget:${widgetId}:visitor-token`;
-}
 function formatTimestamp(value) {
 	const date = new Date(value);
 	if (Number.isNaN(date.getTime())) return "";
@@ -961,6 +1001,33 @@ function useLiveConnection({ actions, createTransport, refreshSession, session,
 	}, [createTransport, session]);
 	return reconnecting;
 }
+/** Who the host says is signed in: their normalised email, or null. */
+function hostIdentityOf(defaultVisitor) {
+	return isCompleteVisitor(defaultVisitor) ? normalizeVisitorEmail(defaultVisitor.email) : null;
+}
+/**
+* The host's signed-in visitor changed under an open session — a sign-out, or
+* a different account signing in without a page reload. The session on
+* screen is the previous person's: drop it, its transcript and its socket, so
+* the next open starts as whoever is signed in now (chat widget session
+* review 2026-10-28, S1). A session the visitor started from the pre-chat
+* form is theirs and is left alone.
+*/
+function useResetOnHostIdentityChange({ generationRef, hostIdentity, identityRef, reset, sessionSourceRef }) {
+	const resetRef = (0, react.useRef)(reset);
+	(0, react.useEffect)(() => {
+		resetRef.current = reset;
+	});
+	(0, react.useEffect)(() => {
+		const current = identityRef.current;
+		if (!(current && sessionSourceRef.current === "host")) return;
+		if (hostIdentity === normalizeVisitorEmail(current.email)) return;
+		generationRef.current += 1;
+		identityRef.current = null;
+		sessionSourceRef.current = null;
+		resetRef.current();
+	}, [hostIdentity]);
+}
 function ChatWidget({ className, createTransport, defaultVisitor, getSession, initiallyOpen = false, launcher = "auto", launcherLabel = "Chat with us", placement = "bottom-right", storage = DEFAULT_STORAGE, style, theme = "auto", widgetId }) {
 	const [isOpen, setIsOpen] = (0, react.useState)(initiallyOpen);
 	const panelId = (0, react.useId)();
@@ -979,6 +1046,11 @@ function ChatWidget({ className, createTransport, defaultVisitor, getSession, in
 	const transportRef = (0, react.useRef)(null);
 	const listRef = (0, react.useRef)(null);
 	const identityRef = (0, react.useRef)(null);
+	const sessionSourceRef = (0, react.useRef)(null);
+	const generationRef = (0, react.useRef)(0);
+	const hostIdentity = hostIdentityOf(defaultVisitor);
+	const latestHostIdentityRef = (0, react.useRef)(hostIdentity);
+	latestHostIdentityRef.current = hostIdentity;
 	(0, react.useEffect)(() => {
 		if (createTransport) return;
 		console.warn("[clivly] <ChatWidget> was given no createTransport, so messages cannot be sent. Pass createTransport={createClivlyTransport()} — see https://www.npmjs.com/package/@clivly/chat-widget#five-minute-quick-start");
@@ -1005,12 +1077,14 @@ function ChatWidget({ className, createTransport, defaultVisitor, getSession, in
 		refreshSession: async (current) => {
 			const identity = identityRef.current;
 			if (!identity) throw new Error("No visitor to reconnect as.");
+			const generation = generationRef.current;
 			const next = await getSession({
 				visitor: identity,
 				visitorToken: current.visitorToken,
 				widgetId
 			});
-			storage?.setItem(createStorageKey(widgetId), next.visitorToken);
+			if (generation !== generationRef.current) return;
+			writeVisitorToken(storage, widgetId, identity.email, next.visitorToken);
 			setSupportState(next.support?.state ?? null);
 			setSession(next);
 		},
@@ -1035,31 +1109,53 @@ function ChatWidget({ className, createTransport, defaultVisitor, getSession, in
 		isReady,
 		messages
 	]);
-	const startSession = (0, react.useCallback)(async (identity) => {
+	const startSession = (0, react.useCallback)(async (identity, source = "form") => {
 		setError(null);
 		setIsConnecting(true);
+		const generation = generationRef.current;
+		const isStale = () => generation !== generationRef.current || source === "host" && normalizeVisitorEmail(identity.email) !== latestHostIdentityRef.current;
 		try {
 			const nextSession = await getSession({
 				visitor: identity,
-				visitorToken: storage?.getItem(createStorageKey(widgetId)) ?? null,
+				visitorToken: readVisitorToken(storage, widgetId, identity.email),
 				widgetId
 			});
-			storage?.setItem(createStorageKey(widgetId), nextSession.visitorToken);
+			if (isStale()) return;
+			writeVisitorToken(storage, widgetId, identity.email, nextSession.visitorToken);
 			identityRef.current = identity;
+			sessionSourceRef.current = source;
 			setSupportState(nextSession.support?.state ?? null);
 			setSession(nextSession);
 			setMessages(sortMessages(nextSession.messages.map((message) => createLocalMessage(message))));
 		} catch (sessionError) {
+			if (isStale()) return;
 			const resolved = sessionError instanceof Error ? sessionError : /* @__PURE__ */ new Error("Failed to start the conversation.");
 			setError(resolved.message);
 		} finally {
-			setIsConnecting(false);
+			if (generation === generationRef.current) setIsConnecting(false);
 		}
 	}, [
 		getSession,
 		storage,
 		widgetId
 	]);
+	useResetOnHostIdentityChange({
+		generationRef,
+		hostIdentity,
+		identityRef,
+		reset: () => {
+			setSession(null);
+			setMessages([]);
+			setSupportState(null);
+			setError(null);
+			setIsConnecting(false);
+			setVisitor({
+				email: defaultVisitor?.email ?? "",
+				name: defaultVisitor?.name ?? ""
+			});
+		},
+		sessionSourceRef
+	});
 	const submitVisitor = async (event) => {
 		event.preventDefault();
 		await startSession(visitor);
@@ -1070,7 +1166,7 @@ function ChatWidget({ className, createTransport, defaultVisitor, getSession, in
 		startSession({
 			email: defaultVisitor.email.trim(),
 			name: defaultVisitor.name.trim()
-		}).catch(() => {});
+		}, "host").catch(() => {});
 	}, [
 		defaultVisitor,
 		error,
@@ -1314,8 +1410,7 @@ function PreChatForm() {
 function ConversationView() {
 	return null;
 }
-//#endregion
-//#region src/transport.ts
+// src/transport.ts
 function isServerEvent(value) {
 	if (typeof value !== "object" || value === null) return false;
 	return typeof value.type === "string";
@@ -1417,8 +1512,7 @@ function createLoopbackTransport({ operatorName = "Clivly", operatorReply = (bod
 		};
 	};
 }
-//#endregion
-//#region src/clivly-transport.ts
+// src/clivly-transport.ts
 /**
 * The transport a host app should use against a real Clivly backend.
 *
@@ -1435,8 +1529,7 @@ function createClivlyTransport$1(options = {}) {
 		}
 	});
 }
-//#endregion
-//#region src/layout.ts
+// src/layout.ts
 const PLACEMENTS = [
 	"bottom-left",
 	"bottom-right",
@@ -1455,8 +1548,7 @@ function parsePlacement(value) {
 function parseLauncher(value) {
 	return LAUNCHERS.find((launcher) => launcher === value) ?? "auto";
 }
-//#endregion
-//#region src/session.ts
+// src/session.ts
 function isWidgetSessionPayload(value) {
 	return typeof value === "object" && value !== null;
 }
@@ -1478,8 +1570,7 @@ function createSessionFetcher({ fetchImpl = fetch, sessionUrl }) {
 		return data;
 	};
 }
-//#endregion
-//#region src/browser-mount.tsx
+// src/browser-mount.tsx
 const MOUNTED_DATA_ATTR = "clivlyMounted";
 /**
 * The identity a script-tag host already knows, read off the tag.
@@ -1571,13 +1662,11 @@ function autoMountChatWidgetScript$1(script = document.currentScript) {
 	if (!script || scriptAlreadyMounted(script)) return null;
 	return mountChatWidgetScript$1(script);
 }
-//#endregion
-//#region src/index.ts
+// src/index.ts
 const autoMountChatWidgetScript = autoMountChatWidgetScript$1;
 const createClivlyTransport = createClivlyTransport$1;
 const mountChatWidget = mountChatWidget$1;
 const mountChatWidgetScript = mountChatWidgetScript$1;
-//#endregion
 exports.ChatLauncher = ChatLauncher;
 exports.ChatPanel = ChatPanel;
 exports.ChatWidget = ChatWidget;

package/dist/index.d.cts

@@ -1,6 +1,5 @@
 import { Root } from "react-dom/client";
 import { CSSProperties, ReactElement } from "react";
-//#region src/layout.d.ts
 /**
  * Where the widget sits on the host page, and what its launcher looks like.
  *
@@ -20,8 +19,6 @@ type ChatWidgetPlacement = "bottom-left" | "bottom-right" | "inline";
  * The label stays the button's accessible name in every variant.
  */
 type ChatWidgetLauncher = "auto" | "icon" | "pill";
-//#endregion
-//#region src/theme.d.ts
 /**
  * Theme resolution for the widget.
  *
@@ -46,8 +43,6 @@ interface ResolveThemeOptions {
  * the majority of pages.
  */
 export declare function resolveTheme(theme: ChatWidgetTheme, { root, view }?: ResolveThemeOptions): ResolvedTheme;
-//#endregion
-//#region src/types.d.ts
 type WidgetSenderType = "visitor" | "operator" | "system";
 interface WidgetConfig {
   brandColor?: string | null;
@@ -164,8 +159,6 @@ interface WidgetErrorEvent {
   type: "error";
 }
 type WidgetServerEvent = WidgetAssistantStatusEvent | WidgetConversationSnapshotEvent | WidgetErrorEvent | WidgetMessageAckEvent | WidgetMessageCreatedEvent | WidgetSessionReadyEvent | WidgetSupportStateEvent;
-//#endregion
-//#region src/transport.d.ts
 interface ChatTransportHandlers {
   onClose: () => void;
   onError: (error: Error) => void;
@@ -204,8 +197,21 @@ interface CreateLoopbackTransportOptions {
   replyDelayMs?: number;
 }
 export declare function createLoopbackTransport({ operatorName, operatorReply, replyDelayMs }?: CreateLoopbackTransportOptions): CreateChatTransport;
-//#endregion
-//#region src/chat-widget.d.ts
+/**
+ * Where the widget keeps the visitor token that resumes a conversation.
+ *
+ * Keyed by widget AND by who the token was issued to. One key per widget used
+ * to hand the token to whoever opened the widget next on that browser — after
+ * a sign-out, or between two people who don't sign in at all — and the server
+ * resumed the previous person's thread for them (chat widget session review
+ * 2026-10-28, S1). The server now refuses that resume on its own; this keeps
+ * each person's token to themselves so a returning visitor still resumes.
+ *
+ * The identity part is a short hash of the normalised email, so the address
+ * itself isn't written into storage keys. It only partitions storage: the
+ * server's identity check is the security boundary, not this.
+ */
+type VisitorTokenStorage = Pick<Storage, "getItem" | "setItem"> & Partial<Pick<Storage, "removeItem">>;
 interface ChatWidgetProps {
   className?: string;
   createTransport?: CreateChatTransport;
@@ -240,7 +246,12 @@ interface ChatWidgetProps {
    * `style` to sit beneath the host's own dialogs.
    */
   placement?: ChatWidgetPlacement;
-  storage?: Pick<Storage, "getItem" | "setItem">;
+  /**
+   * Where the visitor token is kept, per widget and per visitor (see
+   * visitor-token-storage.ts). `removeItem` is optional; with it, the
+   * pre-0.16 shared token is retired after its first use.
+   */
+  storage?: VisitorTokenStorage;
   /**
    * Inline styles on the widget root. The intended use is overriding palette
    * tokens — `{ "--clivly-chat-panel": "#0b0f19" }` — which works because
@@ -261,8 +272,6 @@ export declare function ChatPanel(): null;
 export declare function MessageComposer(): null;
 export declare function PreChatForm(): null;
 export declare function ConversationView(): null;
-//#endregion
-//#region src/browser-mount.d.ts
 interface MountChatWidgetOptions$1 extends Omit<ChatWidgetProps, "getSession" | "widgetId"> {
   container: Element | ShadowRoot;
   sessionUrl: string;
@@ -287,8 +296,6 @@ interface ScriptMountResult$1 extends ChatWidgetMount$1 {
 }
 declare function mountChatWidgetScript$1(script?: HTMLScriptElement): ScriptMountResult$1;
 declare function autoMountChatWidgetScript$1(script?: HTMLScriptElement | null): ScriptMountResult$1 | null;
-//#endregion
-//#region src/clivly-transport.d.ts
 interface CreateClivlyTransportOptions$1 {
   createSocket?: (url: string, protocols?: string | string[]) => WebSocket;
 }
@@ -300,15 +307,11 @@ interface CreateClivlyTransportOptions$1 {
  * produce a silently dead socket.
  */
 declare function createClivlyTransport$1(options?: CreateClivlyTransportOptions$1): CreateChatTransport;
-//#endregion
-//#region src/session.d.ts
 interface CreateSessionFetcherOptions {
   fetchImpl?: typeof fetch;
   sessionUrl: string;
 }
 export declare function createSessionFetcher({ fetchImpl, sessionUrl }: CreateSessionFetcherOptions): GetSession;
-//#endregion
-//#region src/index.d.ts
 export type ChatWidgetMount = ChatWidgetMount$1;
 export type MountChatWidgetOptions = MountChatWidgetOptions$1;
 export type ScriptMountResult = ScriptMountResult$1;
@@ -317,5 +320,4 @@ export type CreateClivlyTransportOptions = CreateClivlyTransportOptions$1;
 export declare const createClivlyTransport: typeof createClivlyTransport$1;
 export declare const mountChatWidget: typeof mountChatWidget$1;
 export declare const mountChatWidgetScript: typeof mountChatWidgetScript$1;
-//#endregion
 export type { ChatTransportConnection, ChatTransportHandlers, ChatWidgetLauncher, ChatWidgetPlacement, ChatWidgetProps, ChatWidgetTheme, ChatWidgetVisitor, CreateChatTransport, CreateChatTransportOptions, CreateLoopbackTransportOptions, CreateWebSocketTransportOptions, GetSession, GetSessionOptions, ResolvedTheme, WidgetAssistantStatusEvent, WidgetClientCreateMessageEvent, WidgetClientEvent, WidgetClientReadEvent, WidgetClientTopicEvent, WidgetConfig, WidgetContact, WidgetConversation, WidgetConversationSnapshotEvent, WidgetErrorEvent, WidgetMessage, WidgetMessageAckEvent, WidgetMessageCreatedEvent, WidgetSenderType, WidgetServerEvent, WidgetSessionPayload, WidgetSessionReadyEvent, WidgetSummary, WidgetSupport, WidgetSupportState, WidgetSupportStateEvent, WidgetSupportTopic };