@helpai/elements 0.29.1 → 0.30.1

package/web-component.mjs

@@ -3,11 +3,7 @@ var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { en
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 
 // src/web-component.ts
-import { h as h2, render as render2 } 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 { render } from "preact";
 
 // src/core/brand.ts
 var BRAND = {
@@ -509,8 +505,9 @@ function resolveOptions(rawOpts) {
   const header = opts.header ?? {};
   const { themeMode, themeOverrides } = parseTheme(opts.theme);
   const mode = presentation.mode ?? "floating";
-  const locale = i18n.locale ?? resolveDefaultLocale(i18n.defaultLocale);
-  const availableLocales = i18n.availableLocales ?? [locale];
+  const defaultLocale = resolveDefaultLocale(i18n.defaultLocale);
+  const availableLocales = i18n.availableLocales ?? [i18n.locale ?? defaultLocale];
+  const locale = clampLocale(i18n.locale ?? defaultLocale, availableLocales, defaultLocale);
   const baseUrl = (opts.baseUrl ?? BRAND.defaultBaseUrl).replace(/\/$/, "");
   const agentApiBaseUrl = (opts.agentApiBaseUrl ?? `${baseUrl}/api/agent`).replace(/\/$/, "");
   const dataApiBaseUrl = (opts.dataApiBaseUrl ?? `${baseUrl}/api/data`).replace(/\/$/, "");
@@ -552,6 +549,7 @@ function resolveOptions(rawOpts) {
       maxCount: opts.composer?.attachments?.maxCount ?? DEFAULT_ATTACHMENTS.maxCount
     },
     locale,
+    defaultLocale,
     availableLocales,
     startMinimized: behavior.startMinimized ?? true,
     actions: resolveActions(mode, header.actions),
@@ -582,6 +580,11 @@ function resolveDefaultLocale(input) {
   if (input && input !== "auto") return input;
   return typeof navigator !== "undefined" && navigator.language ? navigator.language : "en";
 }
+function clampLocale(desired, availableLocales, defaultLocale) {
+  if (availableLocales.length <= 1 || availableLocales.includes(desired)) return desired;
+  if (availableLocales.includes(defaultLocale)) return defaultLocale;
+  return availableLocales[0] ?? desired;
+}
 function resolveActions(mode, overrides) {
   return overrides ?? DEFAULT_ACTIONS_BY_MODE[mode];
 }
@@ -730,13 +733,14 @@ function resolveLauncher(overrides) {
 
 // src/core/config/overrides.ts
 function applyOptionOverrides(options, activeLocale, activeThemeMode, activeTextSize) {
-  if (activeLocale === options.locale && activeThemeMode === options.themeMode && activeTextSize === options.textSize) {
+  const locale = clampLocale(activeLocale, options.availableLocales, options.defaultLocale);
+  if (locale === options.locale && activeThemeMode === options.themeMode && activeTextSize === options.textSize) {
     return options;
   }
   const next = { ...options };
-  if (activeLocale !== options.locale) {
-    next.locale = activeLocale;
-    next.strings = resolveStrings(activeLocale, options.stringsOverride);
+  if (locale !== options.locale) {
+    next.locale = locale;
+    next.strings = resolveStrings(locale, options.stringsOverride);
   }
   if (activeThemeMode !== options.themeMode) next.themeMode = activeThemeMode;
   if (activeTextSize !== options.textSize) next.textSize = activeTextSize;
@@ -782,6 +786,8 @@ function mergeServerConfig(user, server) {
       serverI18n ?? {},
       userI18n
     );
+    if (serverI18n?.availableLocales !== void 0) merged.availableLocales = serverI18n.availableLocales;
+    if (serverI18n?.defaultLocale !== void 0) merged.defaultLocale = serverI18n.defaultLocale;
     const userStrings = userI18n?.strings;
     const serverStrings = serverI18n?.strings;
     if (userStrings || serverStrings) {
@@ -983,35 +989,153 @@ function parseLauncher(get, str2) {
   return Object.keys(base).length > 0 ? base : null;
 }
 
-// src/core/handshake-shape.ts
-function isPlainObject(raw) {
-  return !!raw && typeof raw === "object" && !Array.isArray(raw);
-}
-function isSiteConfigShape(raw) {
-  return isPlainObject(raw);
+// src/core/ids.ts
+function uuid7() {
+  const ts = Date.now();
+  const bytes = new Uint8Array(16);
+  bytes[0] = Math.floor(ts / 2 ** 40) & 255;
+  bytes[1] = Math.floor(ts / 2 ** 32) & 255;
+  bytes[2] = ts >>> 24 & 255;
+  bytes[3] = ts >>> 16 & 255;
+  bytes[4] = ts >>> 8 & 255;
+  bytes[5] = ts & 255;
+  fillRandom(bytes.subarray(6));
+  bytes[6] = bytes[6] & 15 | 112;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
 }
-function isBlocksConfigShape(raw) {
-  if (!isPlainObject(raw)) return false;
-  if (raw.navigation !== void 0 && !Array.isArray(raw.navigation)) return false;
-  if (raw.linkCards !== void 0 && !Array.isArray(raw.linkCards)) return false;
-  return true;
+function fillRandom(view) {
+  if (typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function") {
+    crypto.getRandomValues(view);
+    return;
+  }
+  for (let i = 0; i < view.length; i++) view[i] = Math.floor(Math.random() * 256);
 }
 
-// src/core/host-commands.ts
-function commandEventName(cmd) {
-  return `${BRAND.cssPrefix}:${cmd}`;
-}
-function bindHostCommands(host, handlers) {
-  const entries = Object.entries(handlers);
-  const wrapped = entries.map(([cmd, fn]) => {
-    const event = commandEventName(cmd);
-    const listener = (e) => fn(e.detail);
-    host.addEventListener(event, listener);
-    return [event, listener];
-  });
-  return () => {
-    for (const [event, listener] of wrapped) host.removeEventListener(event, listener);
+// src/core/persistence.ts
+var log2 = logger.scope("persistence");
+function createPersistence(widgetId, storage = defaultStorage) {
+  const prefix = `${BRAND.cssPrefix}.${widgetId}`;
+  const KEY_VISITOR = `${prefix}.visitorId`;
+  const KEY_CONVERSATION = `${prefix}.conversationId`;
+  const KEY_USER_PREFS = `${prefix}.userPrefs`;
+  const KEY_PANEL_OPEN = `${prefix}.panelOpen`;
+  const KEY_PANEL_SIZE = `${prefix}.panelSize`;
+  const KEY_CALLOUT_DISMISSED = `${prefix}.calloutDismissed`;
+  const KEY_SIDEBAR_COLLAPSED = `${prefix}.sidebarCollapsed`;
+  const KEY_ACTIVE_MODULE = `${prefix}.activeModule`;
+  const KEY_FORMS_DONE = `${prefix}.formsDone`;
+  const persistence = {
+    getVisitorId() {
+      const existing = storage.get(KEY_VISITOR);
+      if (existing) return existing;
+      const minted = uuid7();
+      storage.set(KEY_VISITOR, minted);
+      return minted;
+    },
+    setVisitorId(id) {
+      log2.debug("setVisitorId (rebind)", { id, widgetId });
+      storage.set(KEY_VISITOR, id);
+    },
+    loadConversationId() {
+      return storage.get(KEY_CONVERSATION) ?? void 0;
+    },
+    saveConversationId(id) {
+      log2.trace("saveConversationId", { id, widgetId });
+      if (id) storage.set(KEY_CONVERSATION, id);
+      else storage.remove(KEY_CONVERSATION);
+    },
+    loadUserPrefs() {
+      const raw = storage.get(KEY_USER_PREFS);
+      if (!raw) return {};
+      try {
+        const parsed = JSON.parse(raw);
+        return isPlainObject(parsed) ? parsed : {};
+      } catch (error) {
+        log2.warn("loadUserPrefs parse failed", { error });
+        return {};
+      }
+    },
+    saveUserPrefs(s) {
+      try {
+        storage.set(KEY_USER_PREFS, JSON.stringify(s));
+      } catch (error) {
+        log2.warn("saveUserPrefs serialise failed", { error });
+      }
+    },
+    patchUserPrefs(patch) {
+      const current = persistence.loadUserPrefs();
+      persistence.saveUserPrefs({ ...current, ...patch });
+    },
+    loadPanelOpen() {
+      const raw = storage.get(KEY_PANEL_OPEN);
+      if (raw === "1") return true;
+      if (raw === "0") return false;
+      return null;
+    },
+    savePanelOpen(open) {
+      storage.set(KEY_PANEL_OPEN, open ? "1" : "0");
+    },
+    loadPanelSize() {
+      const raw = storage.get(KEY_PANEL_SIZE);
+      return raw === "normal" || raw === "expanded" || raw === "fullscreen" ? raw : null;
+    },
+    savePanelSize(size) {
+      storage.set(KEY_PANEL_SIZE, size);
+    },
+    loadCalloutDismissed(currentText) {
+      if (!currentText) return false;
+      const dismissedText = storage.get(KEY_CALLOUT_DISMISSED);
+      return !!dismissedText && dismissedText === currentText;
+    },
+    saveCalloutDismissed(currentText) {
+      if (currentText) storage.set(KEY_CALLOUT_DISMISSED, currentText);
+      else storage.remove(KEY_CALLOUT_DISMISSED);
+    },
+    loadSidebarCollapsed() {
+      const raw = storage.get(KEY_SIDEBAR_COLLAPSED);
+      if (raw === "1") return true;
+      if (raw === "0") return false;
+      return null;
+    },
+    saveSidebarCollapsed(collapsed) {
+      storage.set(KEY_SIDEBAR_COLLAPSED, collapsed ? "1" : "0");
+    },
+    loadActiveModule() {
+      return storage.get(KEY_ACTIVE_MODULE) || null;
+    },
+    saveActiveModule(id) {
+      storage.set(KEY_ACTIVE_MODULE, id);
+    },
+    loadFormsDone() {
+      const raw = storage.get(KEY_FORMS_DONE);
+      if (!raw) return {};
+      try {
+        const parsed = JSON.parse(raw);
+        return isPlainObject(parsed) ? parsed : {};
+      } catch (error) {
+        log2.warn("loadFormsDone parse failed", { error });
+        return {};
+      }
+    },
+    saveFormDone(id) {
+      try {
+        const done = persistence.loadFormsDone();
+        done[id] = Date.now();
+        storage.set(KEY_FORMS_DONE, JSON.stringify(done));
+      } catch (error) {
+        log2.warn("saveFormDone serialise failed", { error });
+      }
+    },
+    clearConversation() {
+      storage.remove(KEY_CONVERSATION);
+    }
   };
+  return persistence;
+}
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
 }
 
 // src/styles/tokens.css
@@ -1038,7 +1162,7 @@ var FONT = true ? "Inter, system-ui, -apple-system, 'Segoe UI', sans-serif" : "I
 var CSS_TEXT = [tokens_default, reset_default, panel_default, standalone_default, page_default].join("\n").replace(/__P__/g, PREFIX).replaceAll("__BRAND_ACCENT_TEXT__", ACCENT_TEXT).replaceAll("__BRAND_ACCENT__", ACCENT).replaceAll("__BRAND_RADIUS__", RADIUS).replaceAll("__BRAND_FONT__", FONT);
 
 // src/shadow/mount.ts
-var log2 = logger.scope("mount");
+var log3 = logger.scope("mount");
 var sheetsByDocument = /* @__PURE__ */ new WeakMap();
 var HOST_CSS = {
   floating: "all: initial; position: fixed; z-index: 2147483600;",
@@ -1055,7 +1179,7 @@ function hostPositionForMode(mode) {
 }
 function createShadowMount(opts = {}) {
   const position = opts.position ?? "flow";
-  log2.debug("createShadowMount", { position, hasTarget: !!opts.target, hasHost: !!opts.existingHost });
+  log3.debug("createShadowMount", { position, hasTarget: !!opts.target, hasHost: !!opts.existingHost });
   const tagName = `${BRAND.cssPrefix}-chat-host`;
   if (typeof customElements !== "undefined" && !customElements.get(tagName)) {
     customElements.define(tagName, class extends HTMLElement {
@@ -1139,6 +1263,44 @@ function applyHostAttributes(host, resolved) {
   applySize(host, resolved.size);
 }
 
+// src/core/boot.ts
+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";
+
+// src/core/handshake-shape.ts
+function isPlainObject2(raw) {
+  return !!raw && typeof raw === "object" && !Array.isArray(raw);
+}
+function isSiteConfigShape(raw) {
+  return isPlainObject2(raw);
+}
+function isBlocksConfigShape(raw) {
+  if (!isPlainObject2(raw)) return false;
+  if (raw.navigation !== void 0 && !Array.isArray(raw.navigation)) return false;
+  if (raw.linkCards !== void 0 && !Array.isArray(raw.linkCards)) return false;
+  return true;
+}
+
+// src/core/host-commands.ts
+function commandEventName(cmd) {
+  return `${BRAND.cssPrefix}:${cmd}`;
+}
+function bindHostCommands(host, handlers) {
+  const entries = Object.entries(handlers);
+  const wrapped = entries.map(([cmd, fn]) => {
+    const event = commandEventName(cmd);
+    const listener = (e) => fn(e.detail);
+    host.addEventListener(event, listener);
+    return [event, listener];
+  });
+  return () => {
+    for (const [event, listener] of wrapped) host.removeEventListener(event, listener);
+  };
+}
+
 // src/ui/host-mode.ts
 function computeHostMode(configured, panelSize, isOpen) {
   if (configured === "page") return "page";
@@ -1189,30 +1351,6 @@ function createAuth(opts) {
   };
 }
 
-// src/core/ids.ts
-function uuid7() {
-  const ts = Date.now();
-  const bytes = new Uint8Array(16);
-  bytes[0] = Math.floor(ts / 2 ** 40) & 255;
-  bytes[1] = Math.floor(ts / 2 ** 32) & 255;
-  bytes[2] = ts >>> 24 & 255;
-  bytes[3] = ts >>> 16 & 255;
-  bytes[4] = ts >>> 8 & 255;
-  bytes[5] = ts & 255;
-  fillRandom(bytes.subarray(6));
-  bytes[6] = bytes[6] & 15 | 112;
-  bytes[8] = bytes[8] & 63 | 128;
-  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
-  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
-}
-function fillRandom(view) {
-  if (typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function") {
-    crypto.getRandomValues(view);
-    return;
-  }
-  for (let i = 0; i < view.length; i++) view[i] = Math.floor(Math.random() * 256);
-}
-
 // src/stream/types.ts
 var StreamError = class extends Error {
   constructor(message, code, status, cause) {
@@ -1225,7 +1363,7 @@ var StreamError = class extends Error {
 };
 
 // src/stream/parser.ts
-var log3 = logger.scope("parser");
+var log4 = logger.scope("parser");
 async function* parseChatStream(response, signal7) {
   if (!response.ok) {
     const text = await response.text().catch(() => "");
@@ -1277,10 +1415,10 @@ ${part}` : part;
   if (!dataPayload || dataPayload === "[DONE]") return null;
   try {
     const chunk = JSON.parse(dataPayload);
-    log3.trace("chunk", { type: chunk.type, eventId });
+    log4.trace("chunk", { type: chunk.type, eventId });
     return { chunk, eventId };
   } catch (err) {
-    log3.trace("frame parse failed", { err, payload: dataPayload.slice(0, 200) });
+    log4.trace("frame parse failed", { err, payload: dataPayload.slice(0, 200) });
     return null;
   }
 }
@@ -1435,7 +1573,7 @@ function messageToWireParts(m) {
 }
 
 // src/stream/transport.ts
-var log4 = logger.scope("transport");
+var log5 = logger.scope("transport");
 var MAX_RESUME_ATTEMPTS = 3;
 var RESUME_BACKOFF_MS = 400;
 var CONTENT_CACHE_TTL_MS = 6e4;
@@ -1477,6 +1615,12 @@ var AgentTransport = class {
     // always sees the visitor's latest context as they navigate.
     __publicField(this, "userContext");
     __publicField(this, "pageContext");
+    // Active BCP-47 locale, carried as the envelope's `locale` on EVERY request
+    // so the backend can localize replies AND the data module can return
+    // localized content + forms. Refreshed via `setLocale` whenever the visitor
+    // switches (no re-handshake needed). Resolved + clamped to the deployment's
+    // availableLocales by `resolveOptions` before it reaches here.
+    __publicField(this, "locale");
     // ---- Data API (content / forms — module-help-ai-data-api) --------------
     //
     // The DATA surfaces live on `dataApiBaseUrl` (default `${baseUrl}/api/data`)
@@ -1502,6 +1646,15 @@ var AgentTransport = class {
     this.userContext = userContext;
     this.pageContext = pageContext;
   }
+  /**
+   * Update the active locale carried on every subsequent request. Call on
+   * mount (before the first handshake) and whenever the user picks a new
+   * locale — the next content / forms / message request reflects it with no
+   * extra round-trip.
+   */
+  setLocale(locale) {
+    this.locale = locale;
+  }
   /**
    * Seed the visitor + conversation identity from persistence BEFORE the first
    * `handshake` resolves. A mount-time `resumeStream()` runs in parallel
@@ -1518,6 +1671,7 @@ var AgentTransport = class {
     const out = {};
     if (this.visitorId) out.visitorId = this.visitorId;
     if (this.conversationId) out.conversationId = this.conversationId;
+    if (this.locale) out.locale = this.locale;
     const context = encodeContext(this.userContext, this.pageContext);
     if (context) out[CONTEXT_PARAM] = context;
     return out;
@@ -1545,13 +1699,13 @@ var AgentTransport = class {
   }
   /** One-shot runtime bootstrap. Called once after the widget mounts. */
   async handshake(body) {
-    log4.debug("handshake \u2192", {
+    log5.debug("handshake \u2192", {
       visitorId: body.visitorId,
       conversationId: body.conversationId,
       locale: body.locale
     });
     const res = await this.postJson(DEFAULT_PATHS.handshake, body, "handshake");
-    log4.debug("handshake \u2190", {
+    log5.debug("handshake \u2190", {
       visitorId: res.visitorId,
       conversationId: res.conversationId,
       hasWelcome: !!res.welcome,
@@ -1559,7 +1713,7 @@ var AgentTransport = class {
       rebind: res.rebind
     });
     if (!isHandshakeResponseShape(res)) {
-      log4.warn("handshake response did not match expected shape; using raw response", { response: res });
+      log5.warn("handshake response did not match expected shape; using raw response", { response: res });
     }
     this.visitorId = res.visitorId ?? body.visitorId;
     this.conversationId = res.conversationId;
@@ -1567,11 +1721,11 @@ var AgentTransport = class {
   }
   /** Upload a file attachment. Returns the `{id, url}` the backend assigns. */
   async uploadFile(file) {
-    log4.debug("uploadFile \u2192", { name: file.name, size: file.size, type: file.type });
+    log5.debug("uploadFile \u2192", { name: file.name, size: file.size, type: file.type });
     const fd = new FormData();
     fd.append("file", file, file.name);
     const res = await this.postForm(this.uploadPath, fd, "upload");
-    log4.debug("uploadFile \u2190", { id: res.id, url: res.url });
+    log5.debug("uploadFile \u2190", { id: res.id, url: res.url });
     return res;
   }
   /**
@@ -1579,12 +1733,12 @@ var AgentTransport = class {
    * Only used when `features.voice === 'server'`.
    */
   async transcribe(audio, mimeType = "audio/webm") {
-    log4.debug("transcribe \u2192", { size: audio.size, mimeType });
+    log5.debug("transcribe \u2192", { size: audio.size, mimeType });
     const fd = new FormData();
     fd.append("audio", audio, `voice.${extensionFor(mimeType)}`);
     fd.append("mimeType", mimeType);
     const res = await this.postForm(this.transcribePath, fd, "transcribe");
-    log4.debug("transcribe \u2190", { textLen: res.text.length });
+    log5.debug("transcribe \u2190", { textLen: res.text.length });
     return res;
   }
   async listConversations(params = {}) {
@@ -1592,14 +1746,14 @@ var AgentTransport = class {
     if (params.visitorId) url.searchParams.set("visitorId", params.visitorId);
     if (params.limit) url.searchParams.set("limit", String(params.limit));
     if (params.cursor) url.searchParams.set("cursor", params.cursor);
-    log4.debug("listConversations \u2192", {
+    log5.debug("listConversations \u2192", {
       visitorId: params.visitorId ?? this.visitorId,
       limit: params.limit,
       cursor: params.cursor
     });
     const res = await this.getJson(url.toString(), "listConversations");
     const conversations = res.conversations ?? [];
-    log4.debug("listConversations \u2190", { count: conversations.length, nextCursor: res.nextCursor });
+    log5.debug("listConversations \u2190", { count: conversations.length, nextCursor: res.nextCursor });
     return {
       conversations: conversations.map((conversation) => ({
         conversationId: conversation.conversationId,
@@ -1615,10 +1769,10 @@ var AgentTransport = class {
   async loadConversation(conversationId) {
     const url = new URL(this.url(DEFAULT_PATHS.listMessages));
     url.searchParams.set("conversationId", conversationId);
-    log4.debug("loadConversation \u2192", { conversationId, visitorId: this.visitorId });
+    log5.debug("loadConversation \u2192", { conversationId, visitorId: this.visitorId });
     const res = await this.getJson(url.toString(), "loadConversation");
     const messages = res.messages ?? [];
-    log4.debug("loadConversation \u2190", {
+    log5.debug("loadConversation \u2190", {
       conversationId: res.conversationId,
       canContinue: res.canContinue,
       messageCount: messages.length,
@@ -1640,11 +1794,11 @@ var AgentTransport = class {
    */
   async markRead(conversationId) {
     if (!this.visitorId || !conversationId) return;
-    log4.debug("markRead \u2192", { conversationId, visitorId: this.visitorId });
+    log5.debug("markRead \u2192", { conversationId, visitorId: this.visitorId });
     try {
       await this.postJson(DEFAULT_PATHS.markRead, { conversationId }, "markRead");
     } catch (err) {
-      log4.debug("markRead failed (non-fatal)", { err });
+      log5.debug("markRead failed (non-fatal)", { err });
     }
   }
   /** Fetch content rows by filter. `GET /pai/content` (data-API), TTL-cached. */
@@ -1652,7 +1806,7 @@ var AgentTransport = class {
     const key = JSON.stringify(query, Object.keys(query).toSorted());
     const cached = this.contentCache.get(key);
     if (cached && Date.now() - cached.at < CONTENT_CACHE_TTL_MS) {
-      log4.debug("listContent \u2192 cache", query);
+      log5.debug("listContent \u2192 cache", query);
       return cached.result;
     }
     const result = this.fetchContent(query).catch((err) => {
@@ -1668,10 +1822,10 @@ var AgentTransport = class {
       if (value === void 0) continue;
       url.searchParams.set(key, Array.isArray(value) ? value.join(",") : String(value));
     }
-    log4.debug("listContent \u2192", query);
+    log5.debug("listContent \u2192", query);
     const res = await this.getJson(url.toString(), "listContent");
     const items = res.items ?? [];
-    log4.debug("listContent \u2190", { count: items.length, total: res.pagination?.total });
+    log5.debug("listContent \u2190", { count: items.length, total: res.pagination?.total });
     return { ...res, items };
   }
   /**
@@ -1689,21 +1843,21 @@ var AgentTransport = class {
   async bootstrap(conversationId) {
     const url = new URL(this.dataUrl(DEFAULT_PATHS.bootstrap));
     if (conversationId) url.searchParams.set("conversationId", conversationId);
-    log4.debug("bootstrap \u2192", { conversationId: conversationId ?? this.conversationId });
+    log5.debug("bootstrap \u2192", { conversationId: conversationId ?? this.conversationId });
     const res = await this.getJson(url.toString(), "bootstrap");
     const forms = res.forms ?? [];
     const formSubmissions = res.formSubmissions ?? [];
-    log4.debug("bootstrap \u2190", { forms: forms.length, formSubmissions: formSubmissions.length });
+    log5.debug("bootstrap \u2190", { forms: forms.length, formSubmissions: formSubmissions.length });
     return { forms, formSubmissions };
   }
   async saveUserPrefs(userPrefs) {
-    log4.debug("saveUserPrefs \u2192", {
+    log5.debug("saveUserPrefs \u2192", {
       visitorId: this.visitorId,
       conversationId: this.conversationId,
       settingsKeys: Object.keys(userPrefs)
     });
     const res = await this.postJson(DEFAULT_PATHS.updateSettings, { userPrefs }, "saveUserPrefs");
-    log4.debug("saveUserPrefs \u2190", { ok: res.ok });
+    log5.debug("saveUserPrefs \u2190", { ok: res.ok });
     return res;
   }
   get uploadPath() {
@@ -1724,15 +1878,15 @@ var AgentTransport = class {
    * that doesn't implement the endpoint) is non-fatal, so callers don't await.
    */
   async submitForm(body) {
-    log4.debug("submitForm \u2192", { formId: body.formId, trigger: body.trigger, fields: Object.keys(body.values).length });
+    log5.debug("submitForm \u2192", { formId: body.formId, trigger: body.trigger, fields: Object.keys(body.values).length });
     try {
       await this.postJson(this.dataUrl(this.submitFormPath), body, "submitForm");
     } catch (err) {
-      log4.debug("submitForm failed (non-fatal)", { err });
+      log5.debug("submitForm failed (non-fatal)", { err });
     }
   }
   sendMessage(body) {
-    log4.debug("message \u2192", {
+    log5.debug("message \u2192", {
       conversationId: body.conversationId,
       visitorId: body.visitorId,
       messageCount: body.messages.length,
@@ -1812,17 +1966,17 @@ var AgentTransport = class {
         });
       } catch (err) {
         if (ctrl.signal.aborted) return;
-        log4.debug("resume fetch failed \u2014 retrying", { attempt, err });
+        log5.debug("resume fetch failed \u2014 retrying", { attempt, err });
         continue;
       }
       if (res.status === 204 || !res.ok) {
-        log4.debug("resume \u2192 no in-flight stream", { status: res.status });
+        log5.debug("resume \u2192 no in-flight stream", { status: res.status });
         return;
       }
       const before = seenIds.size;
       if (yield* this.drain(parseChatStream(res, ctrl.signal), seenIds, ctrl)) return;
       if (seenIds.size === before) {
-        log4.debug("resume \u2192 stream closed with no new events; nothing to resume");
+        log5.debug("resume \u2192 stream closed with no new events; nothing to resume");
         return;
       }
     }
@@ -1849,14 +2003,14 @@ var AgentTransport = class {
     } catch (err) {
       if (ctrl.signal.aborted) return true;
       if (err instanceof StreamError && err.status !== void 0) throw err;
-      log4.debug("stream segment dropped", { err });
+      log5.debug("stream segment dropped", { err });
     }
     return false;
   }
   /** Abort + fire-and-forget POST to `/pai/cancel-stream`. Idempotent. */
   cancelStream(ctrl, conversationId) {
     if (ctrl.signal.aborted) return;
-    log4.debug("cancel stream", { conversationId, visitorId: this.visitorId });
+    log5.debug("cancel stream", { conversationId, visitorId: this.visitorId });
     ctrl.abort();
     if (!this.visitorId || !conversationId) return;
     this.fetchImpl(this.url(DEFAULT_PATHS.cancelStream), {
@@ -1865,7 +2019,7 @@ var AgentTransport = class {
       headers: { "content-type": "application/json", ...this.opts.auth.headers() },
       body: JSON.stringify(this.withEnvelope({})),
       keepalive: true
-    }).catch((err) => log4.debug("cancel POST failed (non-fatal)", { err }));
+    }).catch((err) => log5.debug("cancel POST failed (non-fatal)", { err }));
   }
   // ---- Low-level fetch helpers ------------------------------------------
   async *openMessageStream(body, signal7) {
@@ -1947,13 +2101,13 @@ var AgentTransport = class {
         if (attempt >= MAX_REQUEST_RETRIES) {
           throw new StreamError(`${label} failed: network error`, "network", void 0, err);
         }
-        log4.debug("request network error \u2014 retrying", { label, attempt });
+        log5.debug("request network error \u2014 retrying", { label, attempt });
         await sleep(backoffMs(attempt));
         continue;
       }
       if (res.ok || !RETRYABLE_STATUS.has(res.status) || attempt >= MAX_REQUEST_RETRIES) return res;
       const wait = retryAfterMs(res.headers) ?? backoffMs(attempt);
-      log4.debug("request retryable status \u2014 retrying", { label, status: res.status, attempt, wait });
+      log5.debug("request retryable status \u2014 retrying", { label, status: res.status, attempt, wait });
       await sleep(wait);
     }
   }
@@ -2148,7 +2302,7 @@ var TRIGGER = {
 };
 
 // src/stream/reducer.ts
-var log5 = logger.scope("reducer");
+var log6 = logger.scope("reducer");
 var StreamReducer = class {
   constructor(messagesSig) {
     __publicField(this, "messagesSig", messagesSig);
@@ -2170,13 +2324,13 @@ var StreamReducer = class {
       case "finish-step":
         return;
       case "finish":
-        log5.debug("finish", { reason: chunk.finishReason, canContinue: chunk.canContinue });
+        log6.debug("finish", { reason: chunk.finishReason, canContinue: chunk.canContinue });
         m.status = "complete";
         if (chunk.finishReason) m.finishReason = chunk.finishReason;
         this.bumpDone(m);
         return;
       case "error":
-        log5.warn("stream error chunk", { errorText: chunk.errorText });
+        log6.warn("stream error chunk", { errorText: chunk.errorText });
         m.status = "error";
         m.errorText = chunk.errorText;
         this.bumpDone(m);
@@ -2305,131 +2459,6 @@ function applyTool(m, chunk) {
   }
 }
 
-// src/core/persistence.ts
-var log6 = logger.scope("persistence");
-function createPersistence(widgetId, storage = defaultStorage) {
-  const prefix = `${BRAND.cssPrefix}.${widgetId}`;
-  const KEY_VISITOR = `${prefix}.visitorId`;
-  const KEY_CONVERSATION = `${prefix}.conversationId`;
-  const KEY_USER_PREFS = `${prefix}.userPrefs`;
-  const KEY_PANEL_OPEN = `${prefix}.panelOpen`;
-  const KEY_PANEL_SIZE = `${prefix}.panelSize`;
-  const KEY_CALLOUT_DISMISSED = `${prefix}.calloutDismissed`;
-  const KEY_SIDEBAR_COLLAPSED = `${prefix}.sidebarCollapsed`;
-  const KEY_ACTIVE_MODULE = `${prefix}.activeModule`;
-  const KEY_FORMS_DONE = `${prefix}.formsDone`;
-  const persistence = {
-    getVisitorId() {
-      const existing = storage.get(KEY_VISITOR);
-      if (existing) return existing;
-      const minted = uuid7();
-      storage.set(KEY_VISITOR, minted);
-      return minted;
-    },
-    setVisitorId(id) {
-      log6.debug("setVisitorId (rebind)", { id, widgetId });
-      storage.set(KEY_VISITOR, id);
-    },
-    loadConversationId() {
-      return storage.get(KEY_CONVERSATION) ?? void 0;
-    },
-    saveConversationId(id) {
-      log6.trace("saveConversationId", { id, widgetId });
-      if (id) storage.set(KEY_CONVERSATION, id);
-      else storage.remove(KEY_CONVERSATION);
-    },
-    loadUserPrefs() {
-      const raw = storage.get(KEY_USER_PREFS);
-      if (!raw) return {};
-      try {
-        const parsed = JSON.parse(raw);
-        return isPlainObject2(parsed) ? parsed : {};
-      } catch (error) {
-        log6.warn("loadUserPrefs parse failed", { error });
-        return {};
-      }
-    },
-    saveUserPrefs(s) {
-      try {
-        storage.set(KEY_USER_PREFS, JSON.stringify(s));
-      } catch (error) {
-        log6.warn("saveUserPrefs serialise failed", { error });
-      }
-    },
-    patchUserPrefs(patch) {
-      const current = persistence.loadUserPrefs();
-      persistence.saveUserPrefs({ ...current, ...patch });
-    },
-    loadPanelOpen() {
-      const raw = storage.get(KEY_PANEL_OPEN);
-      if (raw === "1") return true;
-      if (raw === "0") return false;
-      return null;
-    },
-    savePanelOpen(open) {
-      storage.set(KEY_PANEL_OPEN, open ? "1" : "0");
-    },
-    loadPanelSize() {
-      const raw = storage.get(KEY_PANEL_SIZE);
-      return raw === "normal" || raw === "expanded" || raw === "fullscreen" ? raw : null;
-    },
-    savePanelSize(size) {
-      storage.set(KEY_PANEL_SIZE, size);
-    },
-    loadCalloutDismissed(currentText) {
-      if (!currentText) return false;
-      const dismissedText = storage.get(KEY_CALLOUT_DISMISSED);
-      return !!dismissedText && dismissedText === currentText;
-    },
-    saveCalloutDismissed(currentText) {
-      if (currentText) storage.set(KEY_CALLOUT_DISMISSED, currentText);
-      else storage.remove(KEY_CALLOUT_DISMISSED);
-    },
-    loadSidebarCollapsed() {
-      const raw = storage.get(KEY_SIDEBAR_COLLAPSED);
-      if (raw === "1") return true;
-      if (raw === "0") return false;
-      return null;
-    },
-    saveSidebarCollapsed(collapsed) {
-      storage.set(KEY_SIDEBAR_COLLAPSED, collapsed ? "1" : "0");
-    },
-    loadActiveModule() {
-      return storage.get(KEY_ACTIVE_MODULE) || null;
-    },
-    saveActiveModule(id) {
-      storage.set(KEY_ACTIVE_MODULE, id);
-    },
-    loadFormsDone() {
-      const raw = storage.get(KEY_FORMS_DONE);
-      if (!raw) return {};
-      try {
-        const parsed = JSON.parse(raw);
-        return isPlainObject2(parsed) ? parsed : {};
-      } catch (error) {
-        log6.warn("loadFormsDone parse failed", { error });
-        return {};
-      }
-    },
-    saveFormDone(id) {
-      try {
-        const done = persistence.loadFormsDone();
-        done[id] = Date.now();
-        storage.set(KEY_FORMS_DONE, JSON.stringify(done));
-      } catch (error) {
-        log6.warn("saveFormDone serialise failed", { error });
-      }
-    },
-    clearConversation() {
-      storage.remove(KEY_CONVERSATION);
-    }
-  };
-  return persistence;
-}
-function isPlainObject2(v) {
-  return typeof v === "object" && v !== null && !Array.isArray(v);
-}
-
 // src/core/feedback/index.ts
 import { signal as signal3 } from "@preact/signals";
 
@@ -6725,7 +6754,10 @@ function App({ options, hostElement, bus }) {
           visitorId,
           conversationId,
           userPrefs: persistence.loadUserPrefs(),
-          locale: options.locale
+          // The visitor's ACTIVE locale (persisted pick, else auto-detected) —
+          // not the config baseline — so the handshake learns what the visitor
+          // wants. The response's availableLocales then clamps it for the rest.
+          locale: activeLocale
         });
       } catch (err) {
         if (isStale()) return;
@@ -6787,7 +6819,18 @@ function App({ options, hostElement, bus }) {
         setConversationReady(true);
       }
     },
-    [transport, visitorId, persistence, options, bus, conversationIdSig, feedback, playWelcome, loadThread]
+    [
+      transport,
+      visitorId,
+      persistence,
+      options,
+      bus,
+      conversationIdSig,
+      feedback,
+      playWelcome,
+      loadThread,
+      activeLocale
+    ]
   );
   const userSig = JSON.stringify(options.userContext ?? null);
   const pageSig = JSON.stringify(options.pageContext ?? null);
@@ -6796,6 +6839,13 @@ function App({ options, hostElement, bus }) {
     const merged = Object.keys(formContext).length ? { ...formContext, ...options.userContext } : options.userContext;
     transport.setContext(merged, toWirePageContext(options.pageContext));
   }, [transport, userSig, pageSig, formCtxSig]);
+  const effectiveLocale = clampLocale(activeLocale, options.availableLocales, options.defaultLocale);
+  useEffect17(() => {
+    transport.setLocale(effectiveLocale);
+  }, [transport, effectiveLocale]);
+  useEffect17(() => {
+    if (effectiveLocale !== activeLocale) setActiveLocale(effectiveLocale);
+  }, [effectiveLocale, activeLocale]);
   const runResume = useCallback6(
     async (handle) => {
       let bubble = null;
@@ -7446,51 +7496,21 @@ function emitMessage(bus, options, role, text) {
   options.onMessage?.(payload);
 }
 
-// src/index.ts
-import { h, render } from "preact";
-
 // src/ui/error-boundary.tsx
 import { Component } from "preact";
 var log17 = logger.scope("error-boundary");
-
-// src/shadow/iframe-mount.ts
-var log18 = logger.scope("iframe");
-
-// src/core/events.ts
-var EventBus = class {
+var ErrorBoundary = class extends Component {
   constructor() {
-    __publicField(this, "handlers", /* @__PURE__ */ new Map());
-  }
-  /**
-   * Register a listener for `name`.
-   * @returns an `off` function that removes this listener.
-   */
-  on(name, fn) {
-    let set = this.handlers.get(name);
-    if (!set) {
-      set = /* @__PURE__ */ new Set();
-      this.handlers.set(name, set);
-    }
-    set.add(fn);
-    return () => this.handlers.get(name)?.delete(fn);
+    super(...arguments);
+    __publicField(this, "state", { crashed: false });
   }
-  /**
-   * Dispatch an event synchronously to all listeners.
-   * Listener errors are swallowed — the widget must not crash on user callbacks.
-   */
-  emit(name, payload) {
-    const set = this.handlers.get(name);
-    if (!set) return;
-    for (const fn of set) {
-      try {
-        fn(payload);
-      } catch {
-      }
-    }
+  componentDidCatch(error, info) {
+    log17.error("widget render crashed", { error, componentStack: info?.componentStack });
+    this.setState({ crashed: true });
+    this.props.onError(error, info?.componentStack);
   }
-  /** Remove every listener. Called by the instance `destroy()`. */
-  clear() {
-    this.handlers.clear();
+  render() {
+    return this.state.crashed ? this.props.fallback : this.props.children;
   }
 };
 
@@ -7609,10 +7629,60 @@ function createTracker(bus, deps) {
   };
 }
 
-// src/core/hooks.ts
-var log19 = logger.scope("hooks");
-
-// src/index.ts
+// src/core/boot.ts
+function createWidgetRuntime(params) {
+  const { bus, host, appRoot, persistence, reportError } = params;
+  let userRaw = params.initialRaw;
+  let serverConfig;
+  let currentOptions = resolveOptions(userRaw);
+  let firstRender = true;
+  const recompute = () => {
+    currentOptions = resolveOptions(serverConfig ? mergeServerConfig(userRaw, serverConfig) : userRaw);
+  };
+  const applyHostStyling = () => {
+    applyHostPosition(host, hostPositionForMode(currentOptions.mode));
+    const cachedThemeMode = persistence.loadUserPrefs().themeMode;
+    applyHostAttributes(host, cachedThemeMode ? { ...currentOptions, themeMode: cachedThemeMode } : currentOptions);
+    if (firstRender) {
+      applyMode(host, resolveInitialHostMode(currentOptions));
+      firstRender = false;
+    }
+  };
+  const render2 = () => {
+    applyHostStyling();
+    renderPreact(
+      h(ErrorBoundary, { onError: reportError }, h(App, { bus, hostElement: host, options: currentOptions })),
+      appRoot
+    );
+  };
+  bus.on("handshake", (response) => {
+    if (!response.config) return;
+    serverConfig = response.config;
+    recompute();
+    render2();
+  });
+  const untrack = createTracker(bus, {
+    getOptions: () => currentOptions,
+    getVisitorId: () => persistence.getVisitorId(),
+    getConversationId: () => persistence.loadConversationId()
+  });
+  return {
+    getOptions: () => currentOptions,
+    getUserOptions: () => userRaw,
+    render: render2,
+    setUserOptions: (raw) => {
+      userRaw = raw;
+      recompute();
+      render2();
+    },
+    patchUserOptions: (patch) => {
+      userRaw = { ...userRaw, ...patch };
+      recompute();
+      render2();
+    },
+    destroy: () => untrack()
+  };
+}
 function resolveInitialHostMode(options) {
   if (options.mode === "standalone") return "standalone";
   if (options.mode === "inline") return "inline";
@@ -7626,35 +7696,52 @@ function resolveInitialHostMode(options) {
   return computeHostMode(options.mode, panelSize, panelOpen);
 }
 
+// src/core/events.ts
+var EventBus = class {
+  constructor() {
+    __publicField(this, "handlers", /* @__PURE__ */ new Map());
+  }
+  /**
+   * Register a listener for `name`.
+   * @returns an `off` function that removes this listener.
+   */
+  on(name, fn) {
+    let set = this.handlers.get(name);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.handlers.set(name, set);
+    }
+    set.add(fn);
+    return () => this.handlers.get(name)?.delete(fn);
+  }
+  /**
+   * Dispatch an event synchronously to all listeners.
+   * Listener errors are swallowed — the widget must not crash on user callbacks.
+   */
+  emit(name, payload) {
+    const set = this.handlers.get(name);
+    if (!set) return;
+    for (const fn of set) {
+      try {
+        fn(payload);
+      } catch {
+      }
+    }
+  }
+  /** Remove every listener. Called by the instance `destroy()`. */
+  clear() {
+    this.handlers.clear();
+  }
+};
+
 // src/web-component.ts
 var ChatElement = class extends HTMLElement {
   constructor() {
     super(...arguments);
     __publicField(this, "bus", new EventBus());
     __publicField(this, "mountResult", null);
-    /**
-     * Raw options accumulator. Starts as whatever the page-owner set via
-     * HTML attributes; gets server-side settings merged in on the
-     * `handshake` event so subsequent re-renders pick up the server's
-     * mode / theme / launcher / etc.
-     *
-     * Mirrors `index.ts`'s `rawOptions` so both entry points share the
-     * same user-wins-per-field merge policy.
-     */
-    __publicField(this, "rawOptions", {});
-    /**
-     * Latest resolved options — refreshed every `renderApp()` so the usage
-     * tracker (created once in `boot`) reads live, post-handshake-merge
-     * values (`tracking.enabled` / `endpoint` / `token`).
-     *
-     * This path is independent of `mount()` (it supports N elements per page
-     * without a shared `widgetId` registry), so anything `mount()` wires onto
-     * the bus must be wired here too — the tracker is the current example;
-     * keep them in lockstep.
-     */
-    __publicField(this, "resolved", null);
-    /** Tracker unsubscribe — released on disconnect. */
-    __publicField(this, "untrack", null);
+    /** Live widget composition — null between disconnect and the next connect. */
+    __publicField(this, "runtime", null);
   }
   static get observedAttributes() {
     return REACTIVE_ATTRS;
@@ -7664,50 +7751,37 @@ var ChatElement = class extends HTMLElement {
   }
   disconnectedCallback() {
     if (!this.mountResult) return;
-    this.untrack?.();
-    this.untrack = null;
-    render2(null, this.mountResult.appRoot);
+    this.runtime?.destroy();
+    this.runtime = null;
+    render(null, this.mountResult.appRoot);
     this.bus.clear();
   }
   attributeChangedCallback() {
     if (this.isConnected) this.boot();
   }
   boot() {
-    this.rawOptions = parseAttributes((name) => this.getAttribute(name));
+    const rawOptions = parseAttributes((name) => this.getAttribute(name));
+    if (this.runtime) {
+      this.runtime.setUserOptions(rawOptions);
+      return;
+    }
+    const resolved = resolveOptions(rawOptions);
     if (!this.mountResult) {
-      const resolved = resolveOptions(this.rawOptions);
       this.mountResult = createShadowMount({
         existingHost: this,
         position: hostPositionForMode(resolved.mode)
       });
-      this.bus.on("handshake", (response) => {
-        if (!response.config) return;
-        this.rawOptions = mergeServerConfig(this.rawOptions, response.config);
-        this.renderApp();
-      });
-      const persistence = createPersistence(resolved.widgetId, resolved.storage);
-      this.untrack = createTracker(this.bus, {
-        getOptions: () => this.resolved ?? resolved,
-        getVisitorId: () => persistence.getVisitorId(),
-        getConversationId: () => persistence.loadConversationId()
-      });
     }
-    this.renderApp();
-  }
-  /**
-   * Apply the current `rawOptions` to the host element + App tree.
-   * Called by both the initial boot and every `handshake` merge.
-   */
-  renderApp() {
-    if (!this.mountResult) return;
-    const resolved = resolveOptions(this.rawOptions);
-    this.resolved = resolved;
-    const host = this.mountResult.hostElement;
-    applyHostPosition(host, hostPositionForMode(resolved.mode));
-    const cachedThemeMode = createPersistence(resolved.widgetId, resolved.storage).loadUserPrefs().themeMode;
-    applyHostAttributes(host, cachedThemeMode ? { ...resolved, themeMode: cachedThemeMode } : resolved);
-    applyMode(host, resolveInitialHostMode(resolved));
-    render2(h2(App, { bus: this.bus, hostElement: host, options: resolved }), this.mountResult.appRoot);
+    const persistence = createPersistence(resolved.widgetId, resolved.storage);
+    this.runtime = createWidgetRuntime({
+      bus: this.bus,
+      host: this.mountResult.hostElement,
+      appRoot: this.mountResult.appRoot,
+      persistence,
+      initialRaw: rawOptions,
+      reportError: (error) => this.bus.emit("error", error)
+    });
+    this.runtime.render();
   }
 };
 var registered = false;