@helpai/elements 0.39.0 → 0.40.0

package/index.d.ts

@@ -1,4 +1,4 @@
-export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, H as HandshakeResponse, L as Link, S as ServerConfig, b as SiteConfig, W as WidgetConfig, c as WidgetConfigPartial, d as WidgetSettings, e as WidgetSettingsPartial } from './deployment-CrsbcoCF.js';
+export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, H as HandshakeResponse, L as Link, S as ServerConfig, b as SiteConfig, W as WidgetConfig, c as WidgetConfigPartial, d as WidgetSettings, e as WidgetSettingsPartial } from './deployment-MbF78Pdq.js';
 import 'zod';
 
 /**
@@ -89,6 +89,11 @@ type StringsOverride = LocaleStrings | Partial<Record<string, LocaleStrings>>;
  * `visitorId` is the deliberate exception: it stays global so the same browser
  * is one anonymous visitor everywhere (`${brand.cssPrefix}.visitorId`).
  *
+ * A `storageVersion` (when set) folds a `.v<version>` segment into EVERY key —
+ * including the global `visitorId` — so bumping it force-resets the entire
+ * client-side namespace for all users (a full fresh start: new visitor id,
+ * conversation, prefs, panel state). Unset → the unversioned keys.
+ *
  * Storage is pluggable via {@link ClientStorage} — pass a custom adapter
  * to add encryption, logging, or use a non-localStorage backend.
  */
@@ -1248,6 +1253,14 @@ interface ResolvedOptions {
 interface ServerConfig {
     /** Data-API base override — adopted only when the host didn't set one. */
     dataApiBaseUrl?: string;
+    /**
+     * Storage-schema version — the deployment-owned force-reset lever, pushed ONLY
+     * via the handshake (deliberately not an embed attribute / `init` option).
+     * Pushing a new value abandons every client's prior storage namespace
+     * (visitor id, conversation, prefs, panel state, caches) on next load. The
+     * widget stashes it and the next mount folds `.v<version>` into every key.
+     */
+    storageVersion?: string;
     presentation?: PresentationOptions;
     behavior?: BehaviorOptions;
     theme?: ThemePreference | ThemeOverrides;

package/index.mjs

@@ -1049,8 +1049,11 @@ function fillRandom(view) {
 var log2 = logger.scope("persistence");
 function createPersistence(widgetId, storage = defaultStorage, deploymentId) {
   const scope = deploymentId ? `${widgetId}.${deploymentId}` : widgetId;
-  const prefix = `${BRAND.cssPrefix}.${scope}`;
-  const KEY_VISITOR = `${BRAND.cssPrefix}.visitorId`;
+  const KEY_STORAGE_VERSION = `${BRAND.cssPrefix}.storageVersion`;
+  const activeVersion = storage.get(KEY_STORAGE_VERSION) ?? void 0;
+  const version2 = activeVersion ? `.v${activeVersion}` : "";
+  const prefix = `${BRAND.cssPrefix}.${scope}${version2}`;
+  const KEY_VISITOR = `${BRAND.cssPrefix}${version2}.visitorId`;
   const KEY_CONVERSATION = `${prefix}.conversationId`;
   const KEY_USER_PREFS = `${prefix}.userPrefs`;
   const KEY_PANEL_OPEN = `${prefix}.panelOpen`;
@@ -1161,6 +1164,12 @@ function createPersistence(widgetId, storage = defaultStorage, deploymentId) {
         log2.warn("saveFormDone serialise failed", { error });
       }
     },
+    rememberStorageVersion(serverVersion) {
+      if (serverVersion && serverVersion !== storage.get(KEY_STORAGE_VERSION)) {
+        log2.debug("rememberStorageVersion (force-reset on next load)", { version: serverVersion });
+        storage.set(KEY_STORAGE_VERSION, serverVersion);
+      }
+    },
     clearConversation() {
       storage.remove(KEY_CONVERSATION);
     }
@@ -1397,7 +1406,7 @@ import { h, render as renderPreact } from "preact";
 
 // src/ui/app.tsx
 import { useCallback as useCallback6, useEffect as useEffect17, useMemo as useMemo3, useRef as useRef9, useState as useState13 } from "preact/hooks";
-import { useComputed as useComputed7, useSignal as useSignal2 } from "@preact/signals";
+import { batch, useComputed as useComputed7, useSignal as useSignal2 } from "@preact/signals";
 
 // src/core/handshake-shape.ts
 function isPlainObject2(raw) {
@@ -6738,6 +6747,9 @@ function useLauncherCallout({ callout, persistence }) {
 import { jsx as jsx36, jsxs as jsxs31 } from "preact/jsx-runtime";
 var log17 = logger.scope("app");
 var p32 = BRAND.cssPrefix;
+function makeLocalizedWelcome(w, strings) {
+  return makeInstantWelcomeMessage({ ...w, text: localizeText(strings, w.text) });
+}
 function App({ options, hostElement, bus }) {
   const [persistence] = useState13(
     () => createPersistence(options.widgetId, options.storage, options.aiAgentDeploymentId)
@@ -6808,6 +6820,7 @@ function App({ options, hostElement, bus }) {
   const [agent, setAgent] = useState13(null);
   const [suggestions, setSuggestions] = useState13([]);
   const [activeCancel, setActiveCancel] = useState13(null);
+  const stringsRef = useRef9(options.strings);
   const [parsedSite, setParsedSite] = useState13(void 0);
   const [parsedBlocks, setParsedBlocks] = useState13(void 0);
   const [sidebarCollapsed, setSidebarCollapsed] = useState13(() => persistence.loadSidebarCollapsed() ?? false);
@@ -6892,7 +6905,7 @@ function App({ options, hostElement, bus }) {
   const playWelcome = useCallback6(
     (welcomeMessages) => {
       if (!welcomeMessages || welcomeMessages.length === 0) return;
-      messagesSig.value = welcomeMessages.map(makeInstantWelcomeMessage);
+      messagesSig.value = welcomeMessages.map((w) => makeLocalizedWelcome(w, stringsRef.current));
     },
     [messagesSig]
   );
@@ -6925,7 +6938,7 @@ function App({ options, hostElement, bus }) {
     const welcomeAnchor = (timelineStamps.length ? Math.min(...timelineStamps) : Date.now()) - 1;
     const loadedIds = new Set(loaded.map((m) => m.id));
     const welcomeRows = (welcomeRef.current?.messages ?? []).filter((w) => !loadedIds.has(w.id)).map((w) => {
-      const row = makeInstantWelcomeMessage(w);
+      const row = makeLocalizedWelcome(w, stringsRef.current);
       row.createdAt = welcomeAnchor;
       return row;
     });
@@ -7012,7 +7025,6 @@ function App({ options, hostElement, bus }) {
         });
       }
       if (res.agent) setAgent(res.agent);
-      if (res.welcome?.suggestions) setSuggestions(res.welcome.suggestions);
       if (options.mode === "page") {
         if (res.site && isSiteConfigShape(res.site)) setParsedSite(res.site);
         else if (res.site) log17.warn("invalid site config, using fallback", { site: res.site });
@@ -7027,6 +7039,17 @@ function App({ options, hostElement, bus }) {
         if (res.userPrefs.textSize) setActiveTextSize(res.userPrefs.textSize);
       }
       welcomeRef.current = res.welcome;
+      if (!newConversation) bus.emit("handshake", res);
+      if (res.welcome?.suggestions) {
+        const strings = stringsRef.current;
+        setSuggestions(
+          res.welcome.suggestions.map((sg) => ({
+            ...sg,
+            label: localizeText(strings, sg.label),
+            ...sg.text === void 0 ? {} : { text: localizeText(strings, sg.text) }
+          }))
+        );
+      }
       const isResume = !newConversation && persistedChatId && res.conversationId === persistedChatId;
       if (isResume) {
         if (activatedRef.current) void loadThread(persistedChatId);
@@ -7036,10 +7059,7 @@ function App({ options, hostElement, bus }) {
         persistence.saveConversationId(res.conversationId);
         playWelcome(res.welcome?.messages);
       }
-      if (!newConversation) {
-        bus.emit("handshake", res);
-        setConversationReady(true);
-      }
+      if (!newConversation) setConversationReady(true);
     },
     [
       transport,
@@ -7427,8 +7447,10 @@ function App({ options, hostElement, bus }) {
     log17.info("clear \u2192 new conversation", { wasStreaming: streaming });
     bus.emit("clear", void 0);
     if (streaming) activeCancel?.();
-    messagesSig.value = [];
-    conversationIdSig.value = void 0;
+    batch(() => {
+      messagesSig.value = [];
+      conversationIdSig.value = void 0;
+    });
     persistence.clearConversation();
     setCanSend(true);
     setFormMarkers([]);
@@ -7527,9 +7549,11 @@ function App({ options, hostElement, bus }) {
           fetchFormMarkers(targetConversationId)
         ]);
         const hydrated = res.messages.map(fromWireMessage);
-        messagesSig.value = withWelcomeRows(hydrated, markers);
+        batch(() => {
+          messagesSig.value = withWelcomeRows(hydrated, markers);
+          conversationIdSig.value = res.conversationId;
+        });
         setFormMarkers(markers);
-        conversationIdSig.value = res.conversationId;
         persistence.saveConversationId(res.conversationId);
         if (res.agent) setAgent(res.agent);
         setCanSend(res.canContinue);
@@ -7583,6 +7607,7 @@ function App({ options, hostElement, bus }) {
     () => applyOptionOverrides(options, activeLocale, activeThemeMode, activeTextSize),
     [options, activeLocale, activeThemeMode, activeTextSize]
   );
+  stringsRef.current = effectiveOptions.strings;
   const enrichedFormMarkers = useMemo3(
     () => formMarkers.map((m) => {
       const def = effectiveForms.list.find((f) => f.id === m.formId);
@@ -7903,6 +7928,7 @@ function createWidgetRuntime(params) {
   };
   bus.on("handshake", (response) => {
     if (!response.config) return;
+    if (response.config.storageVersion) persistence.rememberStorageVersion(response.config.storageVersion);
     serverConfig = response.config;
     recompute();
     render2();

package/package.json

@@ -80,5 +80,5 @@
   ],
   "type": "module",
   "types": "./index.d.ts",
-  "version": "0.39.0"
+  "version": "0.40.0"
 }

package/schema.d.ts

@@ -1,4 +1,4 @@
-export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, E as Endpoints, H as HandshakeResponse, L as Link, P as PAGE_AREA_SUGGESTIONS, f as PageContext, S as ServerConfig, b as SiteConfig, U as UserContext, W as WidgetConfig, c as WidgetConfigPartial, d as WidgetSettings, e as WidgetSettingsPartial, g as assetSchema, h as blocksConfigSchema, i as connectionConfigPartialSchema, j as connectionConfigSchema, k as cssColorSchema, l as cssLengthSchema, m as endpointsSchema, n as handshakeResponseSchema, o as linkSchema, p as localeSchema, q as pageContextSchema, s as serverConfigSchema, r as siteConfigSchema, u as userContextSchema, t as uuid7Schema, w as widgetConfigPartialSchema, v as widgetConfigSchema, x as widgetSettingsPartialSchema, y as widgetSettingsSchema } from './deployment-CrsbcoCF.js';
+export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, E as Endpoints, H as HandshakeResponse, L as Link, P as PAGE_AREA_SUGGESTIONS, f as PageContext, S as ServerConfig, b as SiteConfig, U as UserContext, W as WidgetConfig, c as WidgetConfigPartial, d as WidgetSettings, e as WidgetSettingsPartial, g as assetSchema, h as blocksConfigSchema, i as connectionConfigPartialSchema, j as connectionConfigSchema, k as cssColorSchema, l as cssLengthSchema, m as endpointsSchema, n as handshakeResponseSchema, o as linkSchema, p as localeSchema, q as pageContextSchema, s as serverConfigSchema, r as siteConfigSchema, u as userContextSchema, t as uuid7Schema, w as widgetConfigPartialSchema, v as widgetConfigSchema, x as widgetSettingsPartialSchema, y as widgetSettingsSchema } from './deployment-MbF78Pdq.js';
 import { z } from 'zod';
 
 /**

package/schema.json

@@ -3403,6 +3403,11 @@
               "type": "string",
               "minLength": 1,
               "maxLength": 2048
+            },
+            "storageVersion": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 64
             }
           },
           "additionalProperties": {}

package/schema.mjs

@@ -758,7 +758,8 @@ var connectionConfigPartialSchema = connectionConfigSchema.partial();
 // src/schema/deployment.ts
 import { z as z17 } from "zod";
 var serverConfigSchema = widgetSettingsSchema.partial().omit({ forms: true }).extend({
-  dataApiBaseUrl: z17.string().min(1).max(2048).optional()
+  dataApiBaseUrl: z17.string().min(1).max(2048).optional(),
+  storageVersion: z17.string().min(1).max(64).optional()
 });
 var siteConfigSchema = z17.object({
   title: z17.string().min(1).max(120).optional().describe("Brand / site name. Used as the logo's alt-text fallback."),

package/web-component.mjs

@@ -1087,8 +1087,11 @@ function fillRandom(view) {
 var log2 = logger.scope("persistence");
 function createPersistence(widgetId, storage = defaultStorage, deploymentId) {
   const scope = deploymentId ? `${widgetId}.${deploymentId}` : widgetId;
-  const prefix = `${BRAND.cssPrefix}.${scope}`;
-  const KEY_VISITOR = `${BRAND.cssPrefix}.visitorId`;
+  const KEY_STORAGE_VERSION = `${BRAND.cssPrefix}.storageVersion`;
+  const activeVersion = storage.get(KEY_STORAGE_VERSION) ?? void 0;
+  const version = activeVersion ? `.v${activeVersion}` : "";
+  const prefix = `${BRAND.cssPrefix}.${scope}${version}`;
+  const KEY_VISITOR = `${BRAND.cssPrefix}${version}.visitorId`;
   const KEY_CONVERSATION = `${prefix}.conversationId`;
   const KEY_USER_PREFS = `${prefix}.userPrefs`;
   const KEY_PANEL_OPEN = `${prefix}.panelOpen`;
@@ -1199,6 +1202,12 @@ function createPersistence(widgetId, storage = defaultStorage, deploymentId) {
         log2.warn("saveFormDone serialise failed", { error });
       }
     },
+    rememberStorageVersion(serverVersion) {
+      if (serverVersion && serverVersion !== storage.get(KEY_STORAGE_VERSION)) {
+        log2.debug("rememberStorageVersion (force-reset on next load)", { version: serverVersion });
+        storage.set(KEY_STORAGE_VERSION, serverVersion);
+      }
+    },
     clearConversation() {
       storage.remove(KEY_CONVERSATION);
     }
@@ -1339,7 +1348,7 @@ import { h, render as renderPreact } from "preact";
 
 // src/ui/app.tsx
 import { useCallback as useCallback6, useEffect as useEffect17, useMemo as useMemo3, useRef as useRef9, useState as useState13 } from "preact/hooks";
-import { useComputed as useComputed7, useSignal as useSignal2 } from "@preact/signals";
+import { batch, useComputed as useComputed7, useSignal as useSignal2 } from "@preact/signals";
 
 // src/core/handshake-shape.ts
 function isPlainObject2(raw) {
@@ -6697,6 +6706,9 @@ function useLauncherCallout({ callout, persistence }) {
 import { jsx as jsx36, jsxs as jsxs31 } from "preact/jsx-runtime";
 var log16 = logger.scope("app");
 var p32 = BRAND.cssPrefix;
+function makeLocalizedWelcome(w, strings) {
+  return makeInstantWelcomeMessage({ ...w, text: localizeText(strings, w.text) });
+}
 function App({ options, hostElement, bus }) {
   const [persistence] = useState13(
     () => createPersistence(options.widgetId, options.storage, options.aiAgentDeploymentId)
@@ -6767,6 +6779,7 @@ function App({ options, hostElement, bus }) {
   const [agent, setAgent] = useState13(null);
   const [suggestions, setSuggestions] = useState13([]);
   const [activeCancel, setActiveCancel] = useState13(null);
+  const stringsRef = useRef9(options.strings);
   const [parsedSite, setParsedSite] = useState13(void 0);
   const [parsedBlocks, setParsedBlocks] = useState13(void 0);
   const [sidebarCollapsed, setSidebarCollapsed] = useState13(() => persistence.loadSidebarCollapsed() ?? false);
@@ -6851,7 +6864,7 @@ function App({ options, hostElement, bus }) {
   const playWelcome = useCallback6(
     (welcomeMessages) => {
       if (!welcomeMessages || welcomeMessages.length === 0) return;
-      messagesSig.value = welcomeMessages.map(makeInstantWelcomeMessage);
+      messagesSig.value = welcomeMessages.map((w) => makeLocalizedWelcome(w, stringsRef.current));
     },
     [messagesSig]
   );
@@ -6884,7 +6897,7 @@ function App({ options, hostElement, bus }) {
     const welcomeAnchor = (timelineStamps.length ? Math.min(...timelineStamps) : Date.now()) - 1;
     const loadedIds = new Set(loaded.map((m) => m.id));
     const welcomeRows = (welcomeRef.current?.messages ?? []).filter((w) => !loadedIds.has(w.id)).map((w) => {
-      const row = makeInstantWelcomeMessage(w);
+      const row = makeLocalizedWelcome(w, stringsRef.current);
       row.createdAt = welcomeAnchor;
       return row;
     });
@@ -6971,7 +6984,6 @@ function App({ options, hostElement, bus }) {
         });
       }
       if (res.agent) setAgent(res.agent);
-      if (res.welcome?.suggestions) setSuggestions(res.welcome.suggestions);
       if (options.mode === "page") {
         if (res.site && isSiteConfigShape(res.site)) setParsedSite(res.site);
         else if (res.site) log16.warn("invalid site config, using fallback", { site: res.site });
@@ -6986,6 +6998,17 @@ function App({ options, hostElement, bus }) {
         if (res.userPrefs.textSize) setActiveTextSize(res.userPrefs.textSize);
       }
       welcomeRef.current = res.welcome;
+      if (!newConversation) bus.emit("handshake", res);
+      if (res.welcome?.suggestions) {
+        const strings = stringsRef.current;
+        setSuggestions(
+          res.welcome.suggestions.map((sg) => ({
+            ...sg,
+            label: localizeText(strings, sg.label),
+            ...sg.text === void 0 ? {} : { text: localizeText(strings, sg.text) }
+          }))
+        );
+      }
       const isResume = !newConversation && persistedChatId && res.conversationId === persistedChatId;
       if (isResume) {
         if (activatedRef.current) void loadThread(persistedChatId);
@@ -6995,10 +7018,7 @@ function App({ options, hostElement, bus }) {
         persistence.saveConversationId(res.conversationId);
         playWelcome(res.welcome?.messages);
       }
-      if (!newConversation) {
-        bus.emit("handshake", res);
-        setConversationReady(true);
-      }
+      if (!newConversation) setConversationReady(true);
     },
     [
       transport,
@@ -7386,8 +7406,10 @@ function App({ options, hostElement, bus }) {
     log16.info("clear \u2192 new conversation", { wasStreaming: streaming });
     bus.emit("clear", void 0);
     if (streaming) activeCancel?.();
-    messagesSig.value = [];
-    conversationIdSig.value = void 0;
+    batch(() => {
+      messagesSig.value = [];
+      conversationIdSig.value = void 0;
+    });
     persistence.clearConversation();
     setCanSend(true);
     setFormMarkers([]);
@@ -7486,9 +7508,11 @@ function App({ options, hostElement, bus }) {
           fetchFormMarkers(targetConversationId)
         ]);
         const hydrated = res.messages.map(fromWireMessage);
-        messagesSig.value = withWelcomeRows(hydrated, markers);
+        batch(() => {
+          messagesSig.value = withWelcomeRows(hydrated, markers);
+          conversationIdSig.value = res.conversationId;
+        });
         setFormMarkers(markers);
-        conversationIdSig.value = res.conversationId;
         persistence.saveConversationId(res.conversationId);
         if (res.agent) setAgent(res.agent);
         setCanSend(res.canContinue);
@@ -7542,6 +7566,7 @@ function App({ options, hostElement, bus }) {
     () => applyOptionOverrides(options, activeLocale, activeThemeMode, activeTextSize),
     [options, activeLocale, activeThemeMode, activeTextSize]
   );
+  stringsRef.current = effectiveOptions.strings;
   const enrichedFormMarkers = useMemo3(
     () => formMarkers.map((m) => {
       const def = effectiveForms.list.find((f) => f.id === m.formId);
@@ -7862,6 +7887,7 @@ function createWidgetRuntime(params) {
   };
   bus.on("handshake", (response) => {
     if (!response.config) return;
+    if (response.config.storageVersion) persistence.rememberStorageVersion(response.config.storageVersion);
     serverConfig = response.config;
     recompute();
     render2();