@helpai/elements 0.29.1 → 0.30.0

package/web-component.mjs

@@ -509,8 +509,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 +553,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 +584,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 +737,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 +790,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) {
@@ -1477,6 +1487,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 +1518,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 +1543,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;
@@ -6725,7 +6751,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 +6816,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 +6836,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,12 +7493,26 @@ 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");
+var ErrorBoundary = class extends Component {
+  constructor() {
+    super(...arguments);
+    __publicField(this, "state", { crashed: false });
+  }
+  componentDidCatch(error, info) {
+    log17.error("widget render crashed", { error, componentStack: info?.componentStack });
+    this.setState({ crashed: true });
+    this.props.onError(error, info?.componentStack);
+  }
+  render() {
+    return this.state.crashed ? this.props.fallback : this.props.children;
+  }
+};
+
+// src/index.ts
+import { h, render } from "preact";
 
 // src/shadow/iframe-mount.ts
 var log18 = logger.scope("iframe");
@@ -7648,9 +7709,13 @@ var ChatElement = class extends HTMLElement {
      * 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.
+     * without a shared `widgetId` registry), so everything `mount()` composes
+     * around `<App>` must be mirrored here: the handshake-config merge, the
+     * usage tracker, and the ErrorBoundary wrapper. This has drifted three
+     * times now (mode-merge, tracker, ErrorBoundary). The proper fix is to
+     * extract the shared `<App>` composition into one `bootWidget(opts,
+     * { hostElement })` helper both entry points call — tracked as a
+     * follow-up; until then, keep these two boot paths in lockstep.
      */
     __publicField(this, "resolved", null);
     /** Tracker unsubscribe — released on disconnect. */
@@ -7707,7 +7772,14 @@ var ChatElement = class extends HTMLElement {
     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);
+    render2(
+      h2(
+        ErrorBoundary,
+        { onError: (error) => this.bus.emit("error", error) },
+        h2(App, { bus: this.bus, hostElement: host, options: resolved })
+      ),
+      this.mountResult.appRoot
+    );
   }
 };
 var registered = false;