@helpai/elements 0.29.0 → 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;
@@ -6280,7 +6306,7 @@ function ContentView({ id, title, transport, strings, onBack, actions }) {
     return /* @__PURE__ */ jsxs28("article", { class: `${p29}-content`, "data-testid": TID.contentView, children: [
       item.image ? /* @__PURE__ */ jsx33("img", { class: `${p29}-content-hero`, src: item.image, alt: "", loading: "lazy" }) : null,
       item.description ? /* @__PURE__ */ jsx33("p", { class: `${p29}-content-subtitle`, children: item.description }) : null,
-      item.tags && item.tags.length > 0 ? /* @__PURE__ */ jsx33("span", { class: `${p29}-news-tags`, children: item.tags.map((t) => /* @__PURE__ */ jsx33("span", { class: `${p29}-news-tag`, children: t }, t)) }) : null,
+      item.tags?.length ? /* @__PURE__ */ jsx33("span", { class: `${p29}-news-tags`, children: item.tags.map((t) => /* @__PURE__ */ jsx33("span", { class: `${p29}-news-tag`, children: t }, t)) }) : null,
       /* @__PURE__ */ jsx33(StaticMarkdown, { text: item.content ?? "" })
     ] });
   }
@@ -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");
@@ -7494,6 +7555,121 @@ var EventBus = class {
   }
 };
 
+// src/core/tracking.ts
+var PROTOCOL_VERSION = "1";
+var MAX_HITS_PER_MINUTE = 60;
+var MAX_URL_LENGTH = 2e3;
+var TRACKED = {
+  // Panel lifecycle — the owner's "is the widget used at all" funnel.
+  open: () => void 0,
+  close: () => void 0,
+  expand: (on) => ({ on }),
+  fullscreen: (on) => ({ on }),
+  popOut: () => void 0,
+  // Conversation funnel. `send` is the key conversion; text never rides.
+  send: (p33) => ({ attachments: p33.attachmentCount }),
+  message: (p33) => ({ role: p33.role }),
+  stop: () => void 0,
+  clear: () => void 0,
+  suggestion: () => void 0,
+  toggleHistory: (p33) => ({ view: p33.view }),
+  handshake: () => void 0,
+  // Forms + human-in-the-loop — ids and outcomes, never values.
+  formSubmit: (p33) => ({ formId: p33.formId, skipped: p33.skipped }),
+  toolResult: () => void 0,
+  toolDecision: (p33) => ({ approved: p33.approved }),
+  // Composer / attachments / voice.
+  attach: (p33) => ({ count: p33.count, bytes: p33.totalBytes }),
+  voiceStart: () => void 0,
+  voiceStop: (p33) => ({ ms: p33.durationMs }),
+  voiceCancel: () => void 0,
+  // Preferences — how visitors tune the surface.
+  localeChange: (locale) => ({ locale }),
+  themeChange: (theme) => ({ theme }),
+  textSizeChange: (size) => ({ size }),
+  soundToggle: (p33) => ({ muted: p33.muted }),
+  sidebarToggle: (p33) => ({ collapsed: p33.collapsed }),
+  calloutDismiss: () => void 0,
+  // Health signal only — the error object itself never leaves the page.
+  error: () => void 0
+};
+function privacySignalsOff() {
+  const nav = navigator;
+  return nav.globalPrivacyControl === true || nav.doNotTrack === "1";
+}
+function pageUrl() {
+  return location.origin + location.pathname;
+}
+function referrerOrigin() {
+  try {
+    return document.referrer ? new URL(document.referrer).origin : "";
+  } catch {
+    return "";
+  }
+}
+function createTracker(bus, deps) {
+  const sampleRoll = Math.random();
+  let windowStart = 0;
+  let windowHits = 0;
+  const inflight = /* @__PURE__ */ new Set();
+  const hit = (event, dims) => {
+    const { tracking, publicKey, aiAgentDeploymentId, mode, themeMode } = deps.getOptions();
+    if (!tracking.enabled || privacySignalsOff()) return;
+    if (sampleRoll >= tracking.sampleRate) return;
+    const now = performance.now();
+    if (now - windowStart > 6e4) {
+      windowStart = now;
+      windowHits = 0;
+    }
+    if (++windowHits > MAX_HITS_PER_MINUTE) return;
+    const params = new URLSearchParams();
+    params.set("v", PROTOCOL_VERSION);
+    params.set("e", event);
+    if (tracking.token) params.set("tk", tracking.token);
+    if (publicKey) params.set("pk", publicKey);
+    if (aiAgentDeploymentId) params.set("dep", aiAgentDeploymentId);
+    params.set("vid", deps.getVisitorId());
+    const cid = deps.getConversationId();
+    if (cid) params.set("cid", cid);
+    params.set("url", pageUrl());
+    const ref = referrerOrigin();
+    if (ref) params.set("ref", ref);
+    params.set("sw", String(screen.width));
+    params.set("sh", String(screen.height));
+    params.set("vw", String(innerWidth));
+    params.set("vh", String(innerHeight));
+    params.set("dpr", String(devicePixelRatio));
+    params.set("lang", navigator.language);
+    try {
+      params.set("tz", Intl.DateTimeFormat().resolvedOptions().timeZone);
+    } catch {
+    }
+    params.set("m", mode);
+    params.set("th", themeMode);
+    if (dims) {
+      for (const [k, val] of Object.entries(dims)) {
+        if (val !== void 0) params.set(k, String(val));
+      }
+    }
+    params.set("ts", String(Date.now()));
+    const url = `${tracking.endpoint}?${params}`;
+    if (url.length > MAX_URL_LENGTH) return;
+    const img = new Image(1, 1);
+    inflight.add(img);
+    const settle = () => inflight.delete(img);
+    img.addEventListener("load", settle, { once: true });
+    img.addEventListener("error", settle, { once: true });
+    img.src = url;
+  };
+  const offs = Object.keys(TRACKED).map(
+    (event) => bus.on(event, (payload) => hit(event, TRACKED[event]?.(payload)))
+  );
+  return () => {
+    for (const off of offs) off();
+    inflight.clear();
+  };
+}
+
 // src/core/hooks.ts
 var log19 = logger.scope("hooks");
 
@@ -7527,6 +7703,23 @@ var ChatElement = class extends HTMLElement {
      * 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 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. */
+    __publicField(this, "untrack", null);
   }
   static get observedAttributes() {
     return REACTIVE_ATTRS;
@@ -7536,6 +7729,8 @@ var ChatElement = class extends HTMLElement {
   }
   disconnectedCallback() {
     if (!this.mountResult) return;
+    this.untrack?.();
+    this.untrack = null;
     render2(null, this.mountResult.appRoot);
     this.bus.clear();
   }
@@ -7555,6 +7750,12 @@ var ChatElement = class extends HTMLElement {
         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();
   }
@@ -7565,12 +7766,20 @@ var ChatElement = class extends HTMLElement {
   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);
+    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;