@helpai/elements 1.9.0 → 1.10.0

package/llms-full.txt

@@ -1,6 +1,6 @@
-# Help AI Elements: the full SDK docs (@helpai/elements@1.9.0)
+# Help AI Elements: the full SDK docs (@helpai/elements@1.10.0)
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.9.0/docs/quickstart.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/quickstart.md -->
 
 # Quickstart
 
@@ -67,7 +67,7 @@ kebab-case `data-*` attribute. Common ones:
 ></script>
 ```
 
-Full list: [Installation § script data attributes](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/installation.md#path-a--script-data--auto-boot).
+Full list: [Installation § script data attributes](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/installation.md#path-a--script-data--auto-boot).
 
 ---
 
@@ -149,7 +149,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 ### Vue / Svelte / Angular / any bundler
 
 Call `init(...)` once on mount and `destroy()` on unmount, or use the `<web-ai-chat>` element (path D).
-Full framework-by-framework walkthrough: [Framework integrations](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/frameworks.md).
+Full framework-by-framework walkthrough: [Framework integrations](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md).
 
 ---
 
@@ -186,20 +186,20 @@ round chat bubble with an accent color.
 - **Close the panel** → the bubble returns.
 - **Reload the page** → your chat history stays intact.
 
-Something not showing up? → [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/troubleshooting.md).
+Something not showing up? → [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/troubleshooting.md).
 
 ---
 
 ## 4. Common next steps
 
-- **Match your brand** — [Theming](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/theming.md) has every color,
+- **Match your brand** — [Theming](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md) has every color,
   radius, and font knob.
-- **Change the launcher label / icon** — [`launcher` options](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/configuration.md#launcher).
+- **Change the launcher label / icon** — [`launcher` options](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md#launcher).
 - **Know who the visitor is** — pass `userContext: { id, email, name }`
   (and `pageContext: { area }`) for personalization.
-- **Forward chat events to analytics** — [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/events-and-hooks.md).
+- **Forward chat events to analytics** — [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md).
 - **Add a second widget** (one for sales, one for support) — [Recipes
-  § Multiple widgets](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/recipes.md#multiple-widgets-on-one-page).
+  § Multiple widgets](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md#multiple-widgets-on-one-page).
 
 ---
 
@@ -230,15 +230,15 @@ the same deployment:
 | Remix                   | read from `window.ENV` |
 | Create React App        | `REACT_APP_*`          |
 
-Full security notes: [Security & privacy](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/security-privacy.md).
+Full security notes: [Security & privacy](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md).
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.9.0/docs/installation.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/installation.md -->
 
 # Installation
 
-Deep-dive for every install path. See [Quickstart](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/quickstart.md)
+Deep-dive for every install path. See [Quickstart](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/quickstart.md)
 for the 5-minute version.
 
 ---
@@ -250,7 +250,7 @@ for the 5-minute version.
 | [A. `<script data-*>` auto-boot](#path-a--script-data--auto-boot) | Static HTML, WordPress, no build step               | CDN        |
 | [B. Async loader snippet](#path-b--async-loader-snippet)          | Tag managers, analytics pipelines                   | CDN        |
 | [C. NPM package](#path-c--npm-package)                            | React, Next.js, Vue, Svelte, SolidJS, any bundler   | NPM        |
-| [React kit](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/frameworks.md#react)                                | React, Next.js, Remix: `<HelpAI />` + `useHelpAI()` | NPM        |
+| [React kit](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md#react)                                | React, Next.js, Remix: `<HelpAI />` + `useHelpAI()` | NPM        |
 | [D. Web Component](#path-d--web-component)                        | Declarative tags in any framework                   | CDN or NPM |
 
 > ### CDN URL
@@ -271,9 +271,9 @@ for the 5-minute version.
 All four paths:
 
 - Load the same JS bundle.
-- Accept the same [configuration options](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/configuration.md).
-- Emit the same [events](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/events-and-hooks.md).
-- Respect the same [isolation guarantees](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/security-privacy.md#shadow-dom--iframe).
+- Accept the same [configuration options](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md).
+- Emit the same [events](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md).
+- Respect the same [isolation guarantees](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md#shadow-dom--iframe).
 
 You can combine them — e.g., a Next.js page can use path C, and a
 marketing landing can use path A, both pointing at the same deployment.
@@ -327,13 +327,13 @@ The zero-JavaScript path intentionally exposes a small, flat subset of
 | `data-page-context`                            | `pageContext` extras (JSON)       | `'{"experiment":"b"}'`          |
 
 Unknown attributes are ignored. Full option semantics:
-[Configuration](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/configuration.md).
+[Configuration](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md).
 
 > Explicit scalar attributes (`data-user-id`, `data-page-area`, …) win
 > over keys in the `data-user-context` / `data-page-context` JSON. For
 > SPAs where the visitor logs in after load or navigates between pages,
 > set context dynamically with
-> [`instance.setUserContext(...)` / `setPageContext(...)`](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/configuration.md#setting-context-after-login--on-navigation).
+> [`instance.setUserContext(...)` / `setPageContext(...)`](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md#setting-context-after-login--on-navigation).
 > The `data-user-*` / `data-page-*` attributes are reactive — updating
 > one re-handshakes with the same anonymous visitor/conversation. This
 > context is informational for the AI, never an auth credential.
@@ -436,7 +436,7 @@ arrays or objects to it before the bundle arrives:
 </script>
 ```
 
-Full details: [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/events-and-hooks.md#global-lifecycle-hooks).
+Full details: [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md#global-lifecycle-hooks).
 
 ### After boot
 
@@ -458,7 +458,7 @@ window.HelpAI.brand                      // { id, displayName, cdnUrl, ... }
 ## Path C — NPM package
 
 For sites with a bundler. Full framework-specific walkthroughs:
-[Framework integrations](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/frameworks.md).
+[Framework integrations](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md).
 
 ### Install
 
@@ -650,7 +650,7 @@ declare module 'react' {
 
 **Angular** — add `CUSTOM_ELEMENTS_SCHEMA` to your module.
 
-Framework-by-framework details: [Framework integrations](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/frameworks.md).
+Framework-by-framework details: [Framework integrations](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md).
 
 ---
 
@@ -858,14 +858,14 @@ weigh chunking (see [Caching, versioning & self-hosting](#caching-versioning--se
 
 ## Next
 
-- [Configuration](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/configuration.md) — every option explained with examples.
-- [Theming & customization](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/theming.md) — matching your brand.
-- [Framework integrations](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/frameworks.md) — framework-specific recipes.
-- [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/troubleshooting.md) — "my widget isn't showing up".
+- [Configuration](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md) — every option explained with examples.
+- [Theming & customization](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md) — matching your brand.
+- [Framework integrations](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md) — framework-specific recipes.
+- [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/troubleshooting.md) — "my widget isn't showing up".
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.9.0/docs/frameworks.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md -->
 
 # Framework integrations
 
@@ -954,18 +954,21 @@ function PricingHelp() {
 }
 ```
 
-- **`<HelpAI {...options} />`** takes every [widget option](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/configuration.md) as a prop; `aiAgentDeploymentId` is
+- **`<HelpAI {...options} />`** takes every [widget option](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md) as a prop; `aiAgentDeploymentId` is
   required. It renders nothing itself: the widget mounts once the page is in the browser, a prop change re-configures
   the live widget without a remount, and unmounting removes it. Callback props (`onOpen`, `onMessage`, …) can be new
   functions on every render; the widget always calls the latest one.
 - **`useHelpAI(widgetId?)`** returns `{ state, ask, open, close, reset }`. `state` is
-  [`{ open, ready, unread, conversationId? }`](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/api-reference.md#state-and-ready) and re-renders the component when it changes;
+  [`{ open, ready, unread, conversationId? }`](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/api-reference.md#state-and-ready) and re-renders the component when it changes;
   the server render sees the initial state. The commands are stable across renders and do nothing until the widget
   has mounted (`state.ready`). `ask(text)` fills the composer; `ask(text, { send: true })` sends it. Call `reset()`
   when your user logs out.
 - **One import path.** The kit carries the whole widget API (`getInstance`, `hook`, the types), so import everything
   from `@helpai/elements/react`; the package's other entries are separate copies with their own widgets.
 - **Two widgets** on one page: give each `<HelpAI widgetId='support' … />` and read it with `useHelpAI('support')`.
+- **Signed-in users:** pass `userToken`, a function that fetches the token your server signs
+  ([Verified users](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md#verified-users-usertoken)). Keep it stable for one user (a module function, or
+  `useCallback` keyed on your user id): a different function signs in afresh, and dropping it signs out.
 
 The kit bundles the widget and imports only React from your app, so you don't need Preact installed.
 
@@ -987,7 +990,7 @@ function Chat() {
 `import type {} from '@helpai/elements/jsx/react';` once (in your entry file or a `.d.ts`) registers `<web-ai-chat>`
 in React 19's JSX: every attribute the element reads autocompletes, `ai-agent-deployment-id` is required, and a `ref`
 is the typed element with `ask`, `open`, `state`, `ready` and `reset`. Vue and Svelte have `@helpai/elements/jsx/vue`
-and `@helpai/elements/jsx/svelte` ([JSX typings](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/api-reference.md#jsx-typings)).
+and `@helpai/elements/jsx/svelte` ([JSX typings](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/api-reference.md#jsx-typings)).
 
 ```tsx
 import { useRef } from 'react';
@@ -1496,21 +1499,21 @@ sometimes mounts duplicate instances. Always pair your `useEffect` /
 
 **CSP blocks the widget** — the widget inlines styles inside a shadow
 root (requires `style-src 'unsafe-inline'` or a nonce pattern). See
-[Security & privacy § CSP](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/security-privacy.md#content-security-policy).
+[Security & privacy § CSP](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md#content-security-policy).
 
-More: [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/troubleshooting.md).
+More: [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/troubleshooting.md).
 
 ---
 
 ## Next
 
-- [Recipes](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/recipes.md) — programmatic control patterns.
-- [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/events-and-hooks.md) — analytics integration.
-- [Configuration](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/configuration.md) — every option in detail.
+- [Recipes](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md) — programmatic control patterns.
+- [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md) — analytics integration.
+- [Configuration](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md) — every option in detail.
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.9.0/docs/configuration.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md -->
 
 # Configuration reference
 
@@ -1518,7 +1521,7 @@ Every option you can pass to `init(...)` / `mount(...)` / set via
 `data-*` attributes / set via web-component attributes.
 
 Group-by-group walkthrough with realistic examples. For an at-a-glance
-lookup, see [API reference](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/api-reference.md).
+lookup, see [API reference](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/api-reference.md).
 
 ---
 
@@ -1603,7 +1606,7 @@ init({ widgetId: 'support', publicKey: SUPPORT_KEY, aiAgentDeploymentId: SUPPORT
 init({ widgetId: 'sales', publicKey: SALES_KEY, aiAgentDeploymentId: SALES_DEPLOYMENT_ID });
 ```
 
-See [Recipes § Multiple widgets](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/recipes.md#multiple-widgets-on-one-page).
+See [Recipes § Multiple widgets](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md#multiple-widgets-on-one-page).
 
 ### `baseUrl`
 
@@ -1616,6 +1619,19 @@ Override if you use:
 - A custom domain (`your-company.com`).
 - A local dev backend.
 
+### `userToken`
+
+`string | () => string | Promise<string>` · default: none (anonymous)
+
+Signs the visitor in as your logged-in user: a JWT your server signs with the deployment's secret key, or a function
+returning a fresh one. Their conversations then follow them to any device, and the AI gets their name and email as
+verified facts. Runtime-only: not an attribute or `data-*` option, so the token stays out of the page's markup. See
+[Security → Verified users](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md#verified-users-usertoken) for signing it.
+
+```ts
+init({ publicKey: 'agent_pk_...', aiAgentDeploymentId: '01900000-0000-7000-8000-000000000000', userToken: () => fetch('/api/help-ai-token').then((res) => res.text()) });
+```
+
 ### `userContext`
 
 `object | undefined`
@@ -1735,8 +1751,8 @@ widget.clearUserContext();
 ```
 
 You can also seed context at load time via `data-user-*` /
-`data-page-*` tag attributes — see [Installation](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/installation.md) and
-the framework recipes in [`frameworks.md`](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/frameworks.md).
+`data-page-*` tag attributes — see [Installation](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/installation.md) and
+the framework recipes in [`frameworks.md`](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md).
 
 ---
 
@@ -1791,7 +1807,7 @@ init({ presentation: { mode: 'floating', iframe: true }, publicKey: 'agent_pk_..
 ```
 
 Composes with any `mode`. Default is `false` — shadow DOM alone is
-enough for 95% of deployments. [Security § Iframe isolation](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/security-privacy.md#iframe-isolation).
+enough for 95% of deployments. [Security § Iframe isolation](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md#iframe-isolation).
 
 ### `presentation.position`
 
@@ -1856,7 +1872,7 @@ mode via the header picker regardless of palette overrides.
 End users can flip the theme via the header picker. Their choice is
 persisted per device + synced cross-device.
 
-Full customization guide: [Theming](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/theming.md).
+Full customization guide: [Theming](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md).
 
 ---
 
@@ -1956,7 +1972,7 @@ init({
 ```
 
 Variants + callout fully explained in
-[Theming § Launcher](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/theming.md#launcher).
+[Theming § Launcher](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md#launcher).
 
 ### `launcher.hidden`
 
@@ -2195,7 +2211,7 @@ Full behavior + wire contract:
 `boolean` · default: `false`
 
 Turn OFF the 👍/👎 feedback controls under each rateable reply (AI or operator) — unset/`false` shows them (default). While
-shown, a choice fires the [`messageFeedback`](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/events-and-hooks.md) event and is sent to the backend.
+shown, a choice fires the [`messageFeedback`](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md) event and is sent to the backend.
 
 ```ts
 init({ behavior: { disableMessageFeedback: true } }); // hide the controls
@@ -2284,7 +2300,7 @@ init({
 });
 ```
 
-Full key list: [i18n](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/theming.md#internationalization) or
+Full key list: [i18n](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md#internationalization) or
 `src/i18n/strings.ts` in the source.
 
 ---
@@ -2367,7 +2383,7 @@ init({
 });
 ```
 
-For richer event handling, see [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/events-and-hooks.md).
+For richer event handling, see [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md).
 
 ---
 
@@ -2403,7 +2419,7 @@ The widget itself does not include drafts in Help AI network requests before
 Send. Use an encrypted adapter when same-origin plaintext storage is not
 acceptable; an in-memory adapter disables reload restoration.
 
-Full adapter contract: [Security & privacy § custom storage](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/security-privacy.md#custom-storage).
+Full adapter contract: [Security & privacy § custom storage](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md#custom-storage).
 
 ---
 
@@ -2509,14 +2525,14 @@ const chat = init({
 
 ## Not covered here
 
-- **Events** → [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/events-and-hooks.md)
-- **Theming deep-dive** → [Theming](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/theming.md)
-- **Framework-specific wiring** → [Frameworks](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/frameworks.md)
+- **Events** → [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md)
+- **Theming deep-dive** → [Theming](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md)
+- **Framework-specific wiring** → [Frameworks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md)
 - **Backend API** → Backend contract (internal)
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.9.0/docs/options.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/options.md -->
 
 # Configuration — `ChatWidgetOptions`
 
@@ -2844,13 +2860,13 @@ Pass `footer: { poweredBy: { text: "" } }` to opt out of the brand attribution.
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.9.0/docs/api-reference.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/api-reference.md -->
 
 # API reference
 
 Compact lookup for the SDK's exported functions, types, and events.
-For explanations + examples, see the [Configuration](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/configuration.md)
-and [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/events-and-hooks.md) guides.
+For explanations + examples, see the [Configuration](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md)
+and [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md) guides.
 
 ---
 
@@ -2900,7 +2916,7 @@ import {
 } from '@helpai/elements/react';
 ```
 
-See [Frameworks → React](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/frameworks.md#react).
+See [Frameworks → React](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md#react).
 
 ---
 
@@ -2987,6 +3003,7 @@ interface ChatWidgetInstance {
 
   // Lifecycle
   reset(): void; // start over as a new anonymous visitor (on logout)
+  login(userToken: UserTokenSource): void; // sign the visitor in as your logged-in user (a signed token, or a function returning one)
   destroy(): void;
 
   // Events
@@ -3013,7 +3030,7 @@ interface ChatWidgetInstance {
 ## `ChatWidgetOptions`
 
 The generated, schema-backed field reference is
-[`docs/api/configuration.md`](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/options.md); it is authoritative.
+[`docs/api/configuration.md`](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/options.md); it is authoritative.
 The public input keeps embed identity, context, endpoint overrides, storage,
 and callbacks at the top level. Serializable widget settings use focused
 nested sections. `mount()` and `init()` require `aiAgentDeploymentId`; the
@@ -3053,7 +3070,7 @@ init({
 ```
 
 The complete type also exposes `features`, `forms`, `modules`, and `tracking`.
-See [Configuration](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/configuration.md) for behavior and examples.
+See [Configuration](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md) for behavior and examples.
 
 ### `ActionName`
 
@@ -3180,6 +3197,20 @@ visitor, their current conversation (draft and queued messages included), prefer
 `setUserContext`, then reconnects as a first visit. Listeners added with `on()` stay, and the handle keeps working.
 On `<web-ai-chat>`, also remove a `user-context` attribute you set.
 
+### `login(userToken)`
+
+Signs the visitor in as your logged-in user. `userToken` is a JWT your server signs with the deployment's secret key,
+or a function returning a fresh one (called again when the server rejects the current token as expired). The widget
+reconnects as that user: their conversations on this browser move to them, and they reach their conversations on any
+device where they're signed in. Call `reset()` when they sign out; switching to another user's token starts over the
+same way. Also `HelpAI('login', userToken)`, `element.login(userToken)` on `<web-ai-chat>` (not an attribute, so the
+token stays out of the DOM), the `userToken` option at `init()`, and `<HelpAI userToken={…} />`. Signing and the
+guarantees: [Security → Verified users](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md#verified-users-usertoken).
+
+```ts
+chat.login(() => fetch('/api/help-ai-token').then((res) => res.text()));
+```
+
 ---
 
 ## Events
@@ -3257,7 +3288,7 @@ The auto-boot parser exposes the documented flat `data-*` subset.
 ></script>
 ```
 
-Full attribute list: [Installation § script data attributes](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/installation.md#attributes).
+Full attribute list: [Installation § script data attributes](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/installation.md#attributes).
 
 `data-no-autoboot` — loads the bundle but doesn't auto-mount. For
 deferred init via JS.
@@ -3464,14 +3495,14 @@ Or use `/v1/` for the latest 1.x.x (auto-patches, no major breaks).
 
 ## See also
 
-- [Configuration](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/configuration.md) — options with examples + context.
-- [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/events-and-hooks.md) — event handling deep-dive.
-- [Recipes](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/recipes.md) — copy-paste scenarios.
-- [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/troubleshooting.md) — when things go wrong.
+- [Configuration](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md) — options with examples + context.
+- [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md) — event handling deep-dive.
+- [Recipes](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md) — copy-paste scenarios.
+- [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/troubleshooting.md) — when things go wrong.
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.9.0/docs/events-and-hooks.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md -->
 
 # Events & lifecycle hooks
 
@@ -3945,21 +3976,21 @@ explicit `off()` is belt-and-suspenders. Either way works.
 | No events at all                    | `.on()` called before the instance was fully constructed. Use `init()`'s return value or a pre-boot hook |
 | Pre-boot hook never fires           | Widget never mounted — check the public-key/deployment-id pair                                           |
 
-[Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/troubleshooting.md) has the full diagnostic
+[Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/troubleshooting.md) has the full diagnostic
 checklist.
 
 ---
 
 ## Next
 
-- [Analytics integration](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/analytics.md) — GA4, Mixpanel, Segment, Amplitude, PostHog, Sentry, multi-provider
-- [Recipes](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/recipes.md) — copy-paste scenarios
-- [API reference § events](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/api-reference.md#events) — compact lookup
-- [Configuration § callbacks](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/configuration.md#callbacks-shortcut-for-events)
+- [Analytics integration](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/analytics.md) — GA4, Mixpanel, Segment, Amplitude, PostHog, Sentry, multi-provider
+- [Recipes](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md) — copy-paste scenarios
+- [API reference § events](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/api-reference.md#events) — compact lookup
+- [Configuration § callbacks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md#callbacks-shortcut-for-events)
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.9.0/docs/theming.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md -->
 
 # Theming & customization
 
@@ -4286,7 +4317,7 @@ init({
 
 ## Header actions
 
-See [Configuration § Header actions](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/configuration.md#header-actions)
+See [Configuration § Header actions](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md#header-actions)
 for the full semantics. Quick customization examples:
 
 ### Minimal chrome
@@ -4493,7 +4524,7 @@ are for what tokens don't cover (shadows, corners, borders).
 
 For truly bespoke designs (e.g., replacing the launcher with your
 own component), use `launcher.hidden: true` + custom trigger, or a
-[no-script trigger](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/api-reference.md#no-script-triggers).
+[no-script trigger](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/api-reference.md#no-script-triggers).
 
 ---
 
@@ -4525,16 +4556,16 @@ can always override.
 
 ## Next
 
-- [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/events-and-hooks.md) — listening to chat
+- [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md) — listening to chat
   interactions, integrating with analytics.
-- [Recipes](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/recipes.md) — copy-paste examples for common
+- [Recipes](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md) — copy-paste examples for common
   customization scenarios.
-- [Configuration reference](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/configuration.md) — the full option
+- [Configuration reference](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md) — the full option
   table.
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.9.0/docs/recipes.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md -->
 
 # Recipes
 
@@ -5258,13 +5289,13 @@ brand accent set in the dashboard.
 
 ## Next
 
-- [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/events-and-hooks.md) — full event API
-- [Configuration](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/configuration.md) — every option
-- [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/troubleshooting.md) — when things go wrong
+- [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md) — full event API
+- [Configuration](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md) — every option
+- [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/troubleshooting.md) — when things go wrong
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.9.0/docs/analytics.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/analytics.md -->
 
 # Analytics integration
 
@@ -5320,7 +5351,7 @@ event.
 
 Every interactive action emits one event with a typed payload. Subscribe
 via `chat.on(name, fn)` (instance) or `HelpAI.hook(widgetId, name, fn)`
-(global, pre-boot-safe). Full schema in [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/events-and-hooks.md).
+(global, pre-boot-safe). Full schema in [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md).
 
 | Category         | Event                 | Payload                                            |
 | ---------------- | --------------------- | -------------------------------------------------- |
@@ -5813,14 +5844,14 @@ yourself — see the snippets above.
 
 ## See also
 
-- [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/events-and-hooks.md) — full event reference, payload shapes, pre-boot queue semantics
-- [API reference](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/api-reference.md) — `ChatWidgetInstance` shape
-- [Recipes](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/recipes.md) — other end-to-end snippets
-- [Security & privacy](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/security-privacy.md) — what data flows where
+- [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md) — full event reference, payload shapes, pre-boot queue semantics
+- [API reference](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/api-reference.md) — `ChatWidgetInstance` shape
+- [Recipes](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md) — other end-to-end snippets
+- [Security & privacy](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md) — what data flows where
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.9.0/docs/security-privacy.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md -->
 
 # Security & privacy
 
@@ -6012,7 +6043,7 @@ unsent text values in addition to identity and UI state, so adapter code owns
 their storage destination, retention, and privacy behavior. Use cases include
 encrypted `localStorage`, `sessionStorage`, and in-memory consent fallbacks.
 
-[Recipes § Custom storage](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/recipes.md#custom-storage-adapter).
+[Recipes § Custom storage](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md#custom-storage-adapter).
 
 ---
 
@@ -6164,7 +6195,8 @@ the pinned version URL (`/v1.2.0/`) supports SRI — the floating URL
 ## Authentication
 
 Browser access is scoped by `aiAgentDeploymentId`; a `publicKey` adds
-workspace authorization. There is **no per-end-user token.**
+workspace authorization. Visitors are anonymous unless your server signs a
+[user token](#verified-users-usertoken) for your logged-in user.
 
 ### public key (default)
 
@@ -6189,6 +6221,64 @@ What your public key does NOT grant:
 Omit `publicKey` but keep `aiAgentDeploymentId`; the widget connects to
 that public deployment as a guest without an auth header.
 
+### Verified users (`userToken`)
+
+To show a logged-in user their own conversations on any device, and to let the AI rely on who they are, your
+server signs a short-lived JWT for them with the deployment's **secret key** (on the deployment's Install page;
+never put it in the browser):
+
+| Claim   | Required | What it is                                                 |
+| ------- | -------- | ---------------------------------------------------------- |
+| `sub`   | yes      | Your own id for the user (a string, up to 255 characters)  |
+| `exp`   | yes      | Expiry, in seconds since the epoch; keep it short (1 hour) |
+| `name`  | no       | Their name, given to the AI as a verified fact             |
+| `email` | no       | Their email, given to the AI as a verified fact            |
+
+Sign it with HS256:
+
+```js
+// Node (jose)
+import { SignJWT } from 'jose';
+
+const secret = new TextEncoder().encode(process.env.HELPAI_SECRET_KEY);
+const userToken = await new SignJWT({ name: user.name, email: user.email }).setProtectedHeader({ alg: 'HS256' }).setSubject(String(user.id)).setExpirationTime('1h').sign(secret);
+```
+
+```python
+# Python (PyJWT)
+import os, time, jwt
+
+user_token = jwt.encode({"sub": str(user.id), "exp": int(time.time()) + 3600, "name": user.name, "email": user.email}, os.environ["HELPAI_SECRET_KEY"], algorithm="HS256")
+```
+
+```php
+// PHP (firebase/php-jwt)
+use Firebase\JWT\JWT;
+
+$userToken = JWT::encode(['sub' => (string) $user->id, 'exp' => time() + 3600, 'name' => $user->name, 'email' => $user->email], getenv('HELPAI_SECRET_KEY'), 'HS256');
+```
+
+Serve it from an endpoint only your signed-in user can reach, and hand the widget a function that fetches it:
+
+```ts
+const userToken = () => fetch('/api/help-ai-token').then((res) => res.text());
+
+init({ publicKey: 'agent_pk_...', aiAgentDeploymentId: '01900000-0000-7000-8000-000000000000', userToken }); // signed in at load
+chat.login(userToken); // or after your sign-in (`HelpAI('login', userToken)`, `<HelpAI userToken={userToken} />`)
+chat.reset(); // on sign-out (`HelpAI('reset')`)
+```
+
+- The widget sends the token only to the agent API, as the `x-user-token` header. The function is called when a token
+  is first needed and again when the server answers `401 USER_TOKEN_INVALID` (expired or rejected); the request is
+  then sent once more. A fixed string can't be refreshed, so an expired one fails until you call `login()` again.
+- A token the server can't verify is refused; it never falls back to an anonymous visitor.
+- Signing in moves the visitor's conversations on that browser to the user. From then on they reach them on any device
+  where they're signed in, and nobody else does, the signed-out browser included.
+- Signing out (`reset()`, or dropping the token) or switching to another user starts over as a new visitor: nothing of
+  the previous user stays in the browser.
+- Keep the function's identity stable for one user (a module function, or `useCallback` keyed on your user id): a
+  different function counts as a different user.
+
 ### user / page context is NOT auth
 
 ```ts
@@ -6230,13 +6320,13 @@ flowchart TB
     direction TB
     B1["Authenticates the HOST's agent deployment<br/>(NOT the end user)"]
     B2["Treats userContext / pageContext as<br/>informational + untrusted"]
-    B3["Never registers / authenticates end users"]
+    B3["Never registers end users; verifies a signed userToken when the host sends one"]
   end
 
   Host -->|"context (untrusted)"| Widget
   Widget -->|"HTTPS/TLS + headers + context field"| Backend
 
-  note["publicKey + aiAgentDeploymentId auth the host's agent, NOT the end user — no end-user token anywhere."]
+  note["publicKey + aiAgentDeploymentId auth the host's agent; only a userToken signed by the host's server identifies the end user."]
   Backend -.-> note
 ```
 
@@ -6254,6 +6344,8 @@ and anyone can base64url-decode it. Never put a secret in context.
 
 - **public keys** — rotate from the dashboard. Old keys are deactivated
   instantly; update your embeds.
+- **secret key** — user tokens signed with a replaced secret key stop verifying, so every verified user is signed out
+  until your server signs new ones with the new key.
 
 ---
 
@@ -6400,7 +6492,7 @@ We respond within 24 hours and coordinate disclosure on your schedule.
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.9.0/docs/browser-support.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/browser-support.md -->
 
 # Browser support
 
@@ -6707,7 +6799,7 @@ with:
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.9.0/docs/troubleshooting.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/troubleshooting.md -->
 
 # Troubleshooting
 
@@ -6803,7 +6895,7 @@ for (const k of Object.keys(localStorage)) {
 3. **Any CSP errors in the console?** — `"Refused to connect to
    https://help.ai/api/agent because it violates the following Content
    Security Policy…"` means you need to add `help.ai` to your
-   `connect-src`. See [Security § CSP](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/security-privacy.md#content-security-policy).
+   `connect-src`. See [Security § CSP](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md#content-security-policy).
 
 ---
 
@@ -6886,7 +6978,7 @@ first.
 ### Symptom: widget ignores my CSS
 
 That's by design. The widget lives inside a shadow root — your page
-CSS can't reach inside. Use the [theming options](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/theming.md)
+CSS can't reach inside. Use the [theming options](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md)
 instead.
 
 For advanced customization, override CSS custom properties on the
@@ -7151,7 +7243,7 @@ font-src 'self' https:;
 media-src 'self' blob:;                      # For voice recording
 ```
 
-Full CSP guide: [Security § CSP](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/security-privacy.md#content-security-policy).
+Full CSP guide: [Security § CSP](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md#content-security-policy).
 
 ---
 
@@ -7216,7 +7308,7 @@ provide `i18n.availableLocales` and include `language` in `header.actions`.
 
 ## Getting more help
 
-1. **Read the [FAQ](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/faq.md)** — most common questions answered
+1. **Read the [FAQ](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/faq.md)** — most common questions answered
    there.
 
 2. **Check our GitHub issues**: [github.com/help-ai/elements](https://github.com/help-ai/elements/issues).
@@ -7235,7 +7327,7 @@ provide `i18n.availableLocales` and include `language` in `header.actions`.
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.9.0/docs/faq.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/faq.md -->
 
 # FAQ
 
@@ -7275,7 +7367,7 @@ own builds. Your public key gates the backend, not the frontend.
 ### What browsers are supported?
 
 Chrome/Edge 100+, Safari 15+, Firefox 100+, iOS Safari 15+. No IE11.
-See [Browser support](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/browser-support.md).
+See [Browser support](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/browser-support.md).
 
 ---
 
@@ -7294,11 +7386,11 @@ yourself) and serve it from your CDN. Point your `<script src>` at your hosted
 URL. Self-hosting is also what unlocks **chunked delivery** (only changed code
 re-downloads across releases) behind a single stable URL the customer never has
 to change — see
-[Caching, versioning & self-hosting](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/installation.md#caching-versioning--self-hosting).
+[Caching, versioning & self-hosting](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/installation.md#caching-versioning--self-hosting).
 
 ### Can I use this with a tag manager (GTM)?
 
-Yes. Use the async loader snippet ([Path B](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/installation.md#path-b--async-loader-snippet))
+Yes. Use the async loader snippet ([Path B](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/installation.md#path-b--async-loader-snippet))
 inside a Custom HTML tag. All `HelpAI(...)` calls queue until the
 bundle lands.
 
@@ -7306,7 +7398,7 @@ bundle lands.
 
 Yes — and there's an optional `presentation.iframe: true` flag that wraps the
 widget in its OWN iframe for extra isolation. See
-[Configuration § presentation.iframe](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/configuration.md#presentationiframe).
+[Configuration § presentation.iframe](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md#presentationiframe).
 
 ### Does it work in shadow DOM?
 
@@ -7316,15 +7408,15 @@ custom element on your page). Everything just works.
 
 ### Does it work with React / Next.js?
 
-Yes. Full walkthrough: [Framework integrations § Next.js](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/frameworks.md#nextjs).
+Yes. Full walkthrough: [Framework integrations § Next.js](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md#nextjs).
 
 ### Does it work with Vue / Svelte / SolidJS / Angular?
 
-Yes. See [Framework integrations](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/frameworks.md).
+Yes. See [Framework integrations](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md).
 
 ### Does it work with WordPress / Shopify / Webflow / Squarespace?
 
-Yes. [Framework integrations § CMS](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/frameworks.md#wordpress).
+Yes. [Framework integrations § CMS](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md#wordpress).
 
 ---
 
@@ -7333,12 +7425,12 @@ Yes. [Framework integrations § CMS](https://cdn.help.ai/sdk/js/elements/1.9.0/d
 ### Can I change the launcher icon?
 
 Yes. Pick from presets (`chat`, `spark`, `message`, `help`, `wand`)
-or pass raw SVG. See [Theming § Icons](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/theming.md#icons).
+or pass raw SVG. See [Theming § Icons](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md#icons).
 
 ### Can I match my brand colors?
 
 Yes. Set `theme.accent`, `theme.accentText`, `theme.radius`,
-`theme.fontFamily`. See [Theming § Colors](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/theming.md#color-overrides).
+`theme.fontFamily`. See [Theming § Colors](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md#color-overrides).
 
 ### Can I change the font?
 
@@ -7348,7 +7440,7 @@ respects any CSS font stack you provide.
 ### Can I hide the launcher and open the widget from my own button?
 
 Yes. Set `launcher: { hidden: true }`, then call `chat.open()` from
-your button's click handler. [Recipes § Custom launcher](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/recipes.md#custom-launcher-button).
+your button's click handler. [Recipes § Custom launcher](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md#custom-launcher-button).
 
 ### Can I change the welcome message?
 
@@ -7357,24 +7449,24 @@ widget just renders what the backend sends.
 
 ### Can I override UI strings?
 
-Yes, per-locale or flat. See [Theming § Strings](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/theming.md#strings-overrides).
+Yes, per-locale or flat. See [Theming § Strings](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md#strings-overrides).
 
 ### Can I have multiple widgets on one page?
 
 Yes — with distinct `widgetId` values. Each gets its own chat
-thread, storage, and events. [Recipes § Multi-widget](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/recipes.md#multiple-widgets-on-one-page).
+thread, storage, and events. [Recipes § Multi-widget](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md#multiple-widgets-on-one-page).
 
 ### Can I show the widget only on certain pages?
 
 Yes — just skip the `init()` call on pages where you don't want it.
 Or conditionally mount/unmount based on the URL.
-[Recipes § Conditional show](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/recipes.md#conditionally-show-based-on-url).
+[Recipes § Conditional show](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md#conditionally-show-based-on-url).
 
 ### Can I use it in a specific language?
 
 Yes. Force via `i18n.locale: 'fr-CA'`. Let users switch via
 `i18n.availableLocales: ['en', 'fr', 'es']`. Full details: [Theming §
-Internationalization](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/theming.md#internationalization).
+Internationalization](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md#internationalization).
 
 ### Can I change the widget's position on mobile?
 
@@ -7411,7 +7503,7 @@ allowlisted event metadata through 1×1 pixel requests; it never sends message
 text or form values and can be disabled with `tracking.enabled: false`. GPC and
 DNT disable it automatically. No cookies or fingerprinting.
 
-Full breakdown: [Security & privacy § data collected](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/security-privacy.md#what-data-the-widget-collects).
+Full breakdown: [Security & privacy § data collected](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md#what-data-the-widget-collects).
 
 ### Does the widget use cookies?
 
@@ -7431,7 +7523,7 @@ Help AI API + your deployment's configured model provider.
 It stores data about identified users (when you pass `user.id`) or
 anonymous visitors. Your DPA (Data Processing Agreement) with Help
 AI covers the processing terms. For consent management, see
-[Recipes § Gate behind consent](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/recipes.md#gate-the-widget-behind-consent).
+[Recipes § Gate behind consent](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md#gate-the-widget-behind-consent).
 
 ### Can visitors delete their chat history?
 
@@ -7446,7 +7538,7 @@ Yes — pass a custom in-memory storage adapter. Adapter-managed identity,
 conversation, draft, preference, and UI state then evaporates on reload. The
 optional logger debug level is separate: calling `setDebug` persists
 `helpai.debug` directly in `localStorage` until the host clears it.
-[Recipes § Custom storage adapter](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/recipes.md#custom-storage-adapter).
+[Recipes § Custom storage adapter](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md#custom-storage-adapter).
 
 ### Does the widget track visitors across sites?
 
@@ -7471,7 +7563,7 @@ init({
 not an auth credential. Browser public access uses the matching
 `publicKey` + `aiAgentDeploymentId` pair, or the deployment ID alone for
 intentional guest mode.
-See [Recipes § Logged-in user personalization](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/recipes.md#logged-in-user-personalization).
+See [Recipes § Logged-in user personalization](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md#logged-in-user-personalization).
 
 ### How do I integrate with my analytics (GA / Segment / Mixpanel)?
 
@@ -7490,7 +7582,7 @@ One-line pre-boot hook forwards every event:
 </script>
 ```
 
-Full examples: [Recipes § Analytics forwarding](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/recipes.md#analytics-forwarding).
+Full examples: [Recipes § Analytics forwarding](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md#analytics-forwarding).
 
 ### How do I capture errors in Sentry / Datadog?
 
@@ -7675,7 +7767,7 @@ table.
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.9.0/docs/README.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/README.md -->
 
 # Help AI Elements — SDK Documentation
 
@@ -7704,7 +7796,7 @@ it → the panel opens → they can chat.
 Get the public key and deployment ID from [help.ai](https://help.ai) →
 **Dashboard → Deployments**.
 
-[**Continue with the quickstart →**](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/quickstart.md)
+[**Continue with the quickstart →**](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/quickstart.md)
 
 ---
 
@@ -7712,19 +7804,19 @@ Get the public key and deployment ID from [help.ai](https://help.ai) →
 
 | You want to…                                                | Read                                          |
 | ----------------------------------------------------------- | --------------------------------------------- |
-| Install the widget end-to-end                               | [**Quickstart**](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/quickstart.md)             |
-| See every install method (NPM, Web Component, React)        | [Installation](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/installation.md)             |
-| Customize every option                                      | [Configuration reference](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/configuration.md) |
-| Match my brand colors and typography                        | [Theming & customization](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/theming.md)       |
-| Send chat events to my analytics                            | [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/events-and-hooks.md)       |
-| Wire GA4 / Mixpanel / Segment / multi-provider              | [Analytics integration](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/analytics.md)       |
-| Integrate with Next.js / Vue / Svelte / WordPress / Shopify | [Framework integrations](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/frameworks.md)     |
-| Copy a working example                                      | [Recipes](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/recipes.md)                       |
-| Diagnose "why isn't this working"                           | [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/troubleshooting.md)       |
-| Quick answer to a common question                           | [FAQ](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/faq.md)                               |
-| Compact API reference for lookup                            | [API reference](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/api-reference.md)           |
-| Understand what data the widget sees                        | [Security & privacy](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/security-privacy.md)   |
-| Check browser compatibility                                 | [Browser support](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/browser-support.md)       |
+| Install the widget end-to-end                               | [**Quickstart**](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/quickstart.md)             |
+| See every install method (NPM, Web Component, React)        | [Installation](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/installation.md)             |
+| Customize every option                                      | [Configuration reference](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md) |
+| Match my brand colors and typography                        | [Theming & customization](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md)       |
+| Send chat events to my analytics                            | [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md)       |
+| Wire GA4 / Mixpanel / Segment / multi-provider              | [Analytics integration](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/analytics.md)       |
+| Integrate with Next.js / Vue / Svelte / WordPress / Shopify | [Framework integrations](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md)     |
+| Copy a working example                                      | [Recipes](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md)                       |
+| Diagnose "why isn't this working"                           | [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/troubleshooting.md)       |
+| Quick answer to a common question                           | [FAQ](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/faq.md)                               |
+| Compact API reference for lookup                            | [API reference](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/api-reference.md)           |
+| Understand what data the widget sees                        | [Security & privacy](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md)   |
+| Check browser compatibility                                 | [Browser support](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/browser-support.md)       |
 
 ---
 
@@ -7786,7 +7878,7 @@ Five ways to install. Pick whichever fits your site:
 | **ESM via CDN**          | Plain HTML, sandboxes, MDX — no build, no NPM install          | `import { mount } from 'https://cdn.jsdelivr.net/npm/@helpai/elements@<version>/elements.esm.js'` |
 
 All five use the same underlying library. Same options, same events,
-same behavior. Full comparison: [Installation](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/installation.md).
+same behavior. Full comparison: [Installation](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/installation.md).
 
 ---
 
@@ -7841,14 +7933,14 @@ fuller example showing the most common options in one place:
 </script>
 ```
 
-Every option explained in [Configuration](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/configuration.md). Every
-customization path in [Theming](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/theming.md).
+Every option explained in [Configuration](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md). Every
+customization path in [Theming](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md).
 
 ---
 
 ## Support
 
-- **Questions?** [FAQ](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/faq.md) — common answers first. [support@help.ai](mailto:support@help.ai) for anything else.
+- **Questions?** [FAQ](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/faq.md) — common answers first. [support@help.ai](mailto:support@help.ai) for anything else.
 - **Found a bug?** File an issue at [github.com/help-ai/elements](https://github.com/help-ai/elements/issues).
 - **Need a feature?** Same place — we read every request.
 - **Status page:** [help.ai/status](https://help.ai/status).