@helpai/elements 1.8.0 → 1.10.0

package/docs/configuration.md

@@ -0,0 +1,1014 @@
+# Configuration reference
+
+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](./api-reference.md).
+
+---
+
+## How options arrive
+
+Options resolve in this order (highest priority wins):
+
+1. **Options you pass to `init()`** — always win.
+2. **Server-pushed settings** — your Help AI dashboard settings for this
+   deployment. Fill in anything you left unset.
+3. **Built-in defaults** — sensible fallbacks shipped with the widget.
+
+This means you can:
+
+- Hardcode `publicKey` in code, tune the rest from the dashboard.
+- Ship all config in `init()` and ignore the dashboard.
+- Override a specific field (e.g., force `theme: "dark"`) while letting
+  the dashboard control everything else.
+
+### Canonical option shape
+
+Embed identity, routing, context, endpoint overrides, storage, and callbacks stay
+at the top level. Serializable widget settings are grouped by ownership:
+
+| Section        | Fields described in this guide                                                       |
+| -------------- | ------------------------------------------------------------------------------------ |
+| `presentation` | `mode`, `iframe`, `position`, `size`                                                 |
+| `behavior`     | `startMinimized`, `responseMode`, transcript visibility, feedback, suggestion policy |
+| `header`       | `actions`                                                                            |
+| `composer`     | `sendButton`, `attachments`                                                          |
+| `feedback`     | `sound`, `haptics`                                                                   |
+| `i18n`         | `locale`, `defaultLocale`, `availableLocales`, `strings`                             |
+| `footer`       | `composerDisclaimer`, `poweredBy`                                                    |
+
+The flat HTML attributes remain intentionally short (`data-mode`, `data-actions`,
+and so on); the attribute parser maps them into this nested JavaScript shape.
+
+---
+
+## Required
+
+### `publicKey`
+
+`string` · required for authenticated browser deployments
+
+Your deployment's public key from the Help AI dashboard. Looks like
+`agent_pk_...`.
+
+```ts
+init({ publicKey: 'agent_pk_abc123...', aiAgentDeploymentId: '01900000-0000-7000-8000-000000000000' });
+```
+
+The public key authorizes the public widget surface. Pair it with that same
+deployment's `aiAgentDeploymentId`; the backend requires both values to match.
+Intentional guest mode omits the key but still supplies the deployment ID.
+There is no per-end-user token — see
+[`userContext`](#usercontext) below.
+
+### `aiAgentDeploymentId`
+
+`string` · required for browser deployments
+
+The deployment UUID from the same Dashboard → Deployments install panel as the
+public key. It selects the exact agent/configuration and acts as a
+defense-in-depth match for authenticated mounts. Send it on every browser
+mount; also send the public key unless guest mode is intentional.
+
+---
+
+## Identity + routing
+
+### `widgetId`
+
+`string` · default: `"default"`
+
+A name you pick for this widget instance. Matters when you run more
+than one widget on a page — each widgetId gets its own chat thread,
+settings, and storage.
+
+```ts
+init({ widgetId: 'support', publicKey: SUPPORT_KEY, aiAgentDeploymentId: SUPPORT_DEPLOYMENT_ID });
+init({ widgetId: 'sales', publicKey: SALES_KEY, aiAgentDeploymentId: SALES_DEPLOYMENT_ID });
+```
+
+See [Recipes § Multiple widgets](./recipes.md#multiple-widgets-on-one-page).
+
+### `baseUrl`
+
+`string` · default: `https://help.ai`
+
+The MAIN site origin the widget calls — the API modules derive from it
+(agent API at `${baseUrl}/api/agent`, data API at `${baseUrl}/api/data`).
+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](./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`
+
+Host-asserted information about the end user, passed to the AI as
+**context only — never an authentication credential.** The backend does
+not register or authenticate these users. Optional — omit it for
+anonymous chats. Recommended for logged-in users so the AI has context.
+
+```ts
+init({
+  publicKey: 'agent_pk_...',
+  aiAgentDeploymentId: '01900000-0000-7000-8000-000000000000',
+  userContext: {
+    id: 'user_42', // your user id
+    email: 'jane@help.ai',
+    name: 'Jane Doe',
+    plan: 'pro',
+    role: 'admin',
+    phone: '+15551234567',
+    seats: 12, // arbitrary custom scalar field
+  },
+});
+```
+
+A flat object. Recognised fields (all optional):
+
+- `id` — your user's stable identifier.
+- `email` — for personalization.
+- `name` — for personalization (also drives the Home tab greeting,
+  e.g. "Hi Jane 👋").
+- `plan` — subscription / pricing tier (e.g. `"pro"`).
+- `role` — the user's role on your site (e.g. `"admin"`).
+- `phone` — phone number.
+
+Plus any arbitrary custom scalar fields (`string | number | boolean`) —
+account age, feature flags, etc.
+
+Because this is untrusted external input, it is sanitized client-side
+before it leaves the page: non-scalar values are dropped, reserved keys
+(`visitorId`, `conversationId`, `conversationId`, `jwt`, `token`, `authorization`,
+`password`) are stripped, a malformed `email` is dropped, strings are
+trimmed and capped at 1024 chars, max 50 keys. Sanitization warns to the
+debug log and never throws.
+
+> **This is YOUR site's logged-in user — not the widget's own visitor.**
+> The widget independently mints and persists an anonymous
+> `visitorId` / `conversationId` for the device; `userContext` never overrides
+> those. Setting `userContext` simply attaches your context to the same
+> visitor.
+
+### `pageContext`
+
+`object | undefined`
+
+Host-asserted context about the page/visit (separate from `userContext`),
+so the AI can adapt to where the visitor is — a pricing visitor is not a
+docs reader is not a help-desk ticket.
+
+```ts
+init({
+  publicKey: 'agent_pk_...',
+  aiAgentDeploymentId: '01900000-0000-7000-8000-000000000000',
+  pageContext: {
+    area: 'pricing', // host-defined surface
+    path: '/pricing/enterprise',
+    title: 'Enterprise plans',
+    // url auto-filled from location.href when omitted
+  },
+});
+```
+
+Recognised fields (all optional):
+
+- `area` — host-defined surface the visitor is on. Free-form string;
+  suggested values: `home`, `docs`, `help-desk`, `support`, `pricing`,
+  `checkout`, `orders`, `account`, `blog` (any string accepted).
+- `url` — full page URL. Auto-filled from the host page's
+  `location.href` when omitted.
+- `path` — page path, e.g. `/pricing/enterprise`.
+- `title` — page title.
+
+Plus arbitrary custom scalar fields. Sanitized client-side with the same
+rules as `userContext`.
+
+> **On the wire:** `userContext` + `pageContext` are bundled into one
+> `context` field — `base64url(JSON.stringify({ user, page }))` — sent on
+> **every** request (body for POSTs, `?context=` for GETs), so the backend
+> always has the visitor's latest context as they navigate. base64url is
+> encoding, **not encryption** (the transport is already TLS); it just keeps
+> PII out of plaintext access logs / the devtools network tab.
+
+### Setting context after login / on navigation
+
+In a typical SPA the visitor is anonymous on first load and logs in
+later. Update context dynamically via the instance handle. The new context
+rides the **next** request automatically (no reconnect) — and a
+`setUserContext` identity change additionally re-personalizes the greeting,
+keeping the **same** visitor/conversation so the conversation is continuous:
+
+```ts
+const widget = HelpAI.init({ publicKey: 'agent_pk_...', aiAgentDeploymentId: '01900000-0000-7000-8000-000000000000' });
+
+// after your app authenticates the user:
+widget.setUserContext({
+  id: 'user_42',
+  email: 'jane@help.ai',
+  name: 'Jane Doe',
+  plan: 'pro',
+});
+
+// on SPA navigation:
+widget.setPageContext({ area: 'checkout', path: '/checkout' });
+
+// on logout:
+widget.clearUserContext();
+```
+
+You can also seed context at load time via `data-user-*` /
+`data-page-*` tag attributes — see [Installation](./installation.md) and
+the framework recipes in [`frameworks.md`](./frameworks.md).
+
+---
+
+## Rendering
+
+### `presentation.mode`
+
+`"floating" | "inline" | "standalone" | "modal" | "drawer" | "page"` · default: `"floating"`
+
+How the widget renders on the page.
+
+- **`"floating"`** (default) — floating chat bubble in a corner.
+  Clicking opens the panel. Best for marketing sites, support chat.
+- **`"inline"`** — a block element that fills its parent container. No
+  bubble, no popover. Best for in-app assistants, sidebar chats.
+- **`"standalone"`** — full viewport. The dedicated chat tab; renders
+  the full module surface (no sidebar).
+- **`"modal"`** — a centered dialog over a backdrop. The host opens it
+  (no launcher); call `open()` from your own trigger.
+- **`"drawer"`** — docks to a screen edge; the launcher becomes a
+  vertical edge tab.
+- **`"page"`** — full-viewport split: a conversation **sidebar** plus
+  the module surface in the main area.
+
+`target` controls where every mode's shadow host is inserted. It is most
+important for `inline` / `standalone` / `page`; overlay modes remain
+viewport-positioned even when their host is inserted under a custom target.
+See `../features/modes.md` for the full behavior matrix.
+
+```ts
+init({ presentation: { mode: 'inline' }, target: document.getElementById('chat')! });
+```
+
+### `target`
+
+`HTMLElement | undefined`
+
+Where to insert the widget's shadow host. Recommended for `inline` /
+`standalone` / `page` modes. Floating, drawer, and modal hosts also use
+it, while their panels remain viewport-positioned. Defaults to `<body>`.
+
+### `presentation.iframe`
+
+`boolean` · default: `false`
+
+Wrap the widget in a same-origin iframe for strict JS + CSS isolation.
+Useful when the host page has aggressive global scripts that mangle
+`window.*` or inject hostile CSS.
+
+```ts
+init({ presentation: { mode: 'floating', iframe: true }, publicKey: 'agent_pk_...', aiAgentDeploymentId: '01900000-0000-7000-8000-000000000000' });
+```
+
+Composes with any `mode`. Default is `false` — shadow DOM alone is
+enough for 95% of deployments. [Security § Iframe isolation](./security-privacy.md#iframe-isolation).
+
+### `presentation.position`
+
+`"bottom-right" | "bottom-left" | "top-right" | "top-left"` · default: `"bottom-right"`
+
+Launcher corner. Only applies in `floating` mode.
+
+```ts
+init({ presentation: { position: 'bottom-left' } });
+```
+
+### `behavior.startMinimized`
+
+`boolean` · default: `true`
+
+Whether the floating panel starts closed (showing only the launcher).
+Only applies in `floating` mode.
+
+```ts
+// Start open on every fresh page load
+init({ behavior: { startMinimized: false } });
+```
+
+User's last open/close choice is remembered per device — so even with
+`behavior.startMinimized: false`, closing the widget and reloading keeps it
+closed.
+
+---
+
+## Theming
+
+### `theme`
+
+`"auto" | "light" | "dark" | ThemeOverrides` · default: `"auto"`
+
+Three forms:
+
+**1. Preset mode:**
+
+```ts
+init({ theme: 'auto' }); // follows OS prefers-color-scheme
+init({ theme: 'light' }); // force light
+init({ theme: 'dark' }); // force dark
+```
+
+**2. Color overrides (stays in auto mode):**
+
+```ts
+init({
+  theme: {
+    accent: '#ff3e00', // primary brand color
+    accentText: '#ffffff', // text on the accent color
+    radius: '12px', // corner rounding
+    fontFamily: 'Inter, system-ui, sans-serif',
+  },
+});
+```
+
+**3. Both at once** — not supported in one call, but users can pick a
+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](./theming.md).
+
+---
+
+## Sizing
+
+### `presentation.size`
+
+`SizeOptions | undefined`
+
+Control the panel's dimensions across three tiers:
+
+```ts
+init({
+  presentation: {
+    size: {
+      // Normal tier (default panel size)
+      width: '420px',
+      height: '640px',
+
+      // Expanded tier (when user clicks the ⤢ button)
+      expanded: { width: '80vw', height: '80vh' },
+
+      // User drag-resize
+      resize: {
+        enabled: true,
+        minWidth: '360px',
+        maxWidth: '900px',
+        minHeight: '480px',
+        maxHeight: '90vh',
+      },
+
+      // First-render pick
+      initialSize: 'auto', // auto / normal / expanded / fullscreen
+      autoSizeBreakpoint: 900, // "auto" → expanded if viewport ≥ 900px
+    },
+  },
+});
+```
+
+### Size tiers
+
+- **Normal** — `width`/`height` or mode-specific CSS defaults.
+- **Expanded** — ⤢ header button, configurable dimensions.
+- **Fullscreen** — ⛶ header button, always 100vw × 100vh.
+
+### Drag-resize
+
+`presentation.size.resize.enabled: true` shows a corner grip on the panel. Users drag
+it to resize; dimensions persist per device + sync cross-device.
+`presentation.size.resize.minWidth` etc. clamp the drag range.
+
+### `presentation.size.initialSize`
+
+Which tier to open at on the user's **first** mount. After that, user
+interactions own the size.
+
+- `"normal"` — force the normal tier.
+- `"expanded"` — open roomy.
+- `"fullscreen"` — open full-screen.
+- `"auto"` (default) — `fullscreen` below 640 px, `normal` from 640 px
+  to `autoSizeBreakpoint`, then `expanded` on wider viewports.
+
+---
+
+## Launcher
+
+### `launcher`
+
+`LauncherOptions | undefined` · only applies in `presentation.mode: "floating"`
+
+The FAB and its nudges.
+
+```ts
+init({
+  launcher: {
+    variant: 'pill', // circle / pill / bar / minimal
+    size: 'md', // sm / md / lg
+    label: 'Ask us anything',
+    icon: 'chat', // chat / message / bubbles / spark / wand / bot / help / lifebuoy / headset / search / sparkles / concierge / wave / raw SVG
+    hidden: false, // true = no FAB
+
+    // Unified pre-engagement bubble (optional). Same component
+    // for greetings, nudges, onboarding tips — pick the
+    // visuals + dismissal lifecycle for the use case.
+    callout: {
+      text: '👋 Hi! Need any help?',
+      shape: 'pill', // pill / bubble / callout
+      position: 'auto', // auto / horizontal / vertical
+      delayMs: 1200,
+      autoDismissMs: 0,
+      animated: true,
+      persistent: true, // true (default) = re-show on every visit
+      // false = dismiss-once, hidden across visits
+    },
+  },
+});
+```
+
+Variants + callout fully explained in
+[Theming § Launcher](./theming.md#launcher).
+
+### `launcher.hidden`
+
+Hide the launcher FAB entirely. Use when you want to trigger the widget
+from your own UI:
+
+```ts
+const chat = init({ launcher: { hidden: true } });
+document.getElementById('my-custom-chat-button').onclick = () => chat.open();
+```
+
+---
+
+## Header actions
+
+### `header.actions`
+
+`ActionName[]` · per-mode defaults
+
+The list is a flat enabled set. `history` and `close` render as dedicated
+buttons; the rest live in the ⋯ menu in a fixed internal order. Unlisted actions
+are hidden, so input order does not choose placement.
+
+```ts
+init({
+  header: {
+    actions: ['theme', 'textSize', 'history', 'close', 'clear', 'fullscreen', 'popOut', 'sound', 'language'],
+  },
+});
+```
+
+Available actions:
+
+| Name         | What it does                                                                |
+| ------------ | --------------------------------------------------------------------------- |
+| `clear`      | Start a new conversation (trash icon)                                       |
+| `expand`     | Toggle normal ↔ expanded tier (⤢)                                           |
+| `fullscreen` | Toggle normal ↔ fullscreen (⛶)                                              |
+| `popOut`     | Open the active conversation in `behavior.popOutUrl`                        |
+| `sound`      | Toggle notification sounds (switch-style)                                   |
+| `history`    | Toggle the chat history pane                                                |
+| `language`   | Open the language picker (renders as globe icon or inline rows in overflow) |
+| `theme`      | Open the theme picker (auto/light/dark)                                     |
+| `textSize`   | Cycle the conversation text size                                            |
+| `close`      | Close the panel (X)                                                         |
+
+`popOut` renders only when `behavior.popOutUrl` is configured. The new tab
+receives `chat`, `widgetId`, `public_key` (when present), and
+`ai_agent_deployment_id` query parameters so it can resume the same thread.
+
+Per-mode defaults and visibility rules are maintained in
+Header actions.
+
+> `header.actions` is always a complete replacement for the per-mode default;
+> arrays are never merged. An explicit client list wins over the server list.
+
+---
+
+## Composer
+
+### `composer.sendButton`
+
+Send-button chrome.
+
+```ts
+init({
+  composer: {
+    sendButton: {
+      shape: 'pill', // circle / square / pill
+      icon: 'arrowUp', // arrowUp / paperPlane / send / chevron
+      variant: 'filled', // filled / outline / ghost
+    },
+  },
+});
+```
+
+3 shapes × 4 icons × 3 variants = 36 combinations. Pick what matches
+your brand.
+
+---
+
+## Footer
+
+### `footer.composerDisclaimer`
+
+Small grey text below the textarea. Classic "AI can make mistakes"
+pattern.
+
+```ts
+init({ footer: { composerDisclaimer: 'AI can make mistakes. Check important info.' } });
+```
+
+Empty / omitted = no disclaimer shown.
+
+### `footer.poweredBy`
+
+Attribution row below the disclaimer. Defaults to the active
+brand: `Powered by <BRAND.displayName>` linking to `BRAND.siteUrl`
+(e.g. `Powered by Help AI` → `https://help.ai` for `@helpai/elements`).
+Override fields per-deployment when you want different copy or to add a logo;
+omit fields to inherit the brand defaults.
+
+```ts
+init({
+  footer: {
+    poweredBy: {
+      text: 'Powered by Acme', // overrides brand default
+      href: 'https://acme.com', // overrides brand default
+      logoUrl: 'https://yoursite.com/helpai-logo.svg',
+    },
+  },
+});
+```
+
+To opt out of the attribution entirely, pass an empty `text` (and no
+logo): `footer: { poweredBy: { text: "" } }` collapses the element.
+
+---
+
+## Attachments + features
+
+### `composer.attachments`
+
+Client-side limits. Server enforces its own — these are to give users
+fast feedback before upload.
+
+```ts
+init({
+  composer: {
+    attachments: {
+      maxBytes: 10 * 1024 * 1024, // 10 MB, default
+      maxCount: 10, // default
+      accept: 'image/*,application/pdf', // comma-separated MIME globs
+    },
+  },
+});
+```
+
+### `features.disableFileUpload`
+
+`boolean` · default: `false`
+
+Turn OFF file uploads — hide the paperclip button and reject drag-drop / paste.
+Unset/`false` = enabled (default); set `true` to disable attachments entirely.
+
+### `features.enableOperatorRequest`
+
+`boolean` · default: `false`
+
+Opt IN **operator control** — exposes a "Talk to a person" control in the
+composer and the connected-to-operator states (a status banner while the conversation
+is routed to the operator, and operator reply bubbles). This is a **positive opt-in**
+for a new capability (unlike the `disable*` flags): unset/`false` = off (default), `true` = on.
+
+Every deployment holds one long-lived `GET /pai/stream-resume`; this flag does not gate
+the stream. It only exposes the visitor's `request-operator` control. AI replies, operator
+replies, and control-state changes continue to arrive on the resume channel and deduplicate
+by message id whether the request control is visible or not. The composer stays open while
+operator-routed so the visitor can keep typing. Operator requests require backend support.
+
+```ts
+init({ features: { enableOperatorRequest: true } });
+```
+
+### `features.voice`
+
+`"local" | "server" | "disabled"` · default: `"local"`
+
+How voice input works:
+
+- `"local"` — uses the browser's Web Speech API. Zero upload, free,
+  quality varies by browser.
+- `"server"` — records audio via `MediaRecorder`, uploads to
+  `/pai/transcribe-audio`, receives text. Consistent quality, uses your
+  upload quota.
+- `"disabled"` — hides the mic button entirely.
+
+## Messenger modules
+
+### `modules`
+
+Turns the panel into an Intercom-style **messenger** with a bottom tab
+bar. `modules` is an **ordered array of up to 4 tabs**; each tab picks a UI
+`layout`, the content collections it shows (`contentCollectionIds`), and a
+translatable `label`. The surface renders in
+**every** mode (in `page` mode it fills the main area beside the sidebar). With nothing set, just the **chat** shows —
+today's single-chat widget, no tab bar.
+
+```ts
+init({
+  publicKey: 'agent_pk_...',
+  aiAgentDeploymentId: '01900000-0000-7000-8000-000000000000',
+  modules: [
+    { label: 'tabHome', layout: 'home', contentCollectionIds: [GUIDES_ID], greetingText: 'Hi {name} 👋', brandName: 'Acme' }, // "Popular articles" = the collections' pinned items
+    { label: 'tabConversations', layout: 'chat' }, // the conversation
+    { id: 'help', label: 'tabHelp', layout: 'help', contentCollectionIds: [GUIDES_ID, BILLING_ID] },
+    { id: 'news', label: 'tabNews', layout: 'news', contentCollectionIds: [NEWS_ID] },
+  ],
+});
+```
+
+| Field                  | Required | Meaning                                                                                            |
+| ---------------------- | -------- | -------------------------------------------------------------------------------------------------- |
+| `label`                | yes      | Tab label — an i18n key (e.g. `tabHome`) or literal; translated via `i18n.strings`.                |
+| `layout`               | yes      | `chat` (the conversation), `home`, `help`, or `news`.                                              |
+| `contentCollectionIds` | no       | Content collection ids (UUIDv7, max 20) this tab shows, in order; Help sections follow this order. |
+| `id`                   | no       | Stable id for nav + last-tab memory (defaults to the first `contentCollectionIds`, else `layout`). |
+| home extras            | no       | `greetingText` (supports `{name}`), `hideSearchBar`, `brandName`, … (`home` layout only).          |
+
+- **Order is the array order** (left → right). One tab → no tab bar; zero
+  tabs (`[]`) → an empty state.
+- The first tab is the first-open default; the widget then remembers the
+  user's last tab (per device).
+- The deployment can also push `modules` from the dashboard via the
+  handshake (`config.modules`); your `init({ modules })` wins (replace-whole).
+
+Each tab's content is fetched lazily from `GET /content` (data-api) on first open.
+Full behavior + wire contract:
+`features/messenger-modules.md`.
+
+---
+
+## Response mode
+
+### `behavior.responseMode`
+
+`"streaming" | "buffered"` · default: `"streaming"`
+
+- `"streaming"` — paint replies token-by-token as they arrive. Default.
+- `"buffered"` — show a neutral loading indicator until the reply
+  finishes, then render it whole. The backend always streams; this is a
+  client-rendering choice. Useful when token-by-token feels stuttery.
+
+### `behavior.disableMessageFeedback`
+
+`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`](./events-and-hooks.md) event and is sent to the backend.
+
+```ts
+init({ behavior: { disableMessageFeedback: true } }); // hide the controls
+```
+
+### `behavior.autoSendSuggestions`
+
+`boolean` · default: `false`
+
+Controls what tapping a suggestion chip does. Unset/`false` (default) **fills the composer** with the chip's
+text so the visitor can edit before sending; `true` **sends** it immediately.
+
+```ts
+init({ behavior: { autoSendSuggestions: true } }); // send on tap instead of filling
+```
+
+---
+
+## Internationalization
+
+### `i18n.locale`
+
+`string | undefined`
+
+Force a specific BCP-47 locale, overriding the visitor's browser
+setting.
+
+```ts
+init({ i18n: { locale: 'fr-CA' } });
+```
+
+### `i18n.defaultLocale`
+
+`"auto" | string` · default: `"auto"`
+
+Initial / fallback locale when the user hasn't picked one.
+
+- `"auto"` — sniff `navigator.language`.
+- Explicit tag (e.g., `"es-MX"`) — force that one.
+
+### `i18n.availableLocales`
+
+`string[]` · optional
+
+Locales offered in the language switcher. Omission defaults to the active
+locale as a one-entry list; zero or one entries hide the picker.
+
+```ts
+init({
+  i18n: {
+    availableLocales: ['en', 'fr', 'es', 'de'],
+    defaultLocale: 'auto',
+  },
+});
+```
+
+### `i18n.strings`
+
+Per-key overrides for any UI string. Two shapes:
+
+**Flat** (applies to active locale):
+
+```ts
+init({
+  i18n: {
+    strings: {
+      send: 'Go',
+      composerPlaceholder: 'Ask me anything…',
+      newConversation: 'Start fresh',
+    },
+  },
+});
+```
+
+**Nested** (per-locale):
+
+```ts
+init({
+  i18n: {
+    strings: {
+      en: { send: 'Go' },
+      fr: { send: 'Envoyer' },
+      es: { send: 'Enviar' },
+    },
+  },
+});
+```
+
+Full key list: [i18n](./theming.md#internationalization) or
+`src/i18n/strings.ts` in the source.
+
+---
+
+## Sound + haptics
+
+### `feedback.sound`
+
+Notification sounds.
+
+```ts
+init({
+  feedback: {
+    sound: {
+      enabled: true, // default
+      volume: 0.3, // 0..1, default 0.3
+      events: {
+        messageReceived: true, // built-in synth tone
+        messageSent: true,
+        error: 'https://cdn.your-site.com/error.mp3', // custom audio file
+        voiceStart: false, // silence this one
+        voiceStop: false,
+      },
+    },
+  },
+});
+```
+
+Per-event values:
+
+- `true` — use the built-in synthesized tone.
+- `false` — silence this event.
+- `"url"` — URL to a custom audio file (decoded once + cached).
+
+End users can mute via the sound action in the header. Their choice
+is remembered.
+
+### `feedback.haptics`
+
+Tactile feedback on touch devices.
+
+```ts
+init({
+  feedback: {
+    haptics: {
+      enabled: true, // default: true on touch devices
+      events: {
+        messageSent: [6], // single 6ms tap
+        error: [10, 50, 10], // two taps with a 50ms pause
+      },
+    },
+  },
+});
+```
+
+Per-event values:
+
+- `true` — default pattern.
+- `false` — silence.
+- number — single vibration of N ms.
+- number[] — alternating `[vibrate, pause, vibrate, …]`.
+
+iOS: WebKit only supports a single tick; arrays are flattened.
+
+---
+
+## Callbacks (shortcut for events)
+
+Quick inline callbacks for common events. Same as calling `.on(...)`
+on the returned instance.
+
+```ts
+init({
+  publicKey: 'agent_pk_...',
+  aiAgentDeploymentId: '01900000-0000-7000-8000-000000000000',
+  onMessage: (msg) => console.log(msg),
+  onOpen: () => console.log('opened'),
+  onClose: () => console.log('closed'),
+  onError: (err) => Sentry.captureException(err),
+});
+```
+
+For richer event handling, see [Events & hooks](./events-and-hooks.md).
+
+---
+
+## Storage
+
+### `storage`
+
+`ChatWidgetOptions["storage"]`
+
+Custom synchronous storage adapter. Default is `localStorage`. Swap for:
+
+- `sessionStorage`.
+- Encrypted wrapper.
+- In-memory shim (for environments without `localStorage`).
+
+```ts
+import type { ChatWidgetOptions } from '@helpai/elements';
+
+type StorageAdapter = NonNullable<ChatWidgetOptions['storage']>;
+
+const myStorage: StorageAdapter = {
+  get: (key) => sessionStorage.getItem(key),
+  set: (key, value) => sessionStorage.setItem(key, value),
+  remove: (key) => sessionStorage.removeItem(key),
+};
+
+init({ publicKey: 'agent_pk_...', aiAgentDeploymentId: '01900000-0000-7000-8000-000000000000', storage: myStorage });
+```
+
+The adapter also receives `draft.<conversationId>` keys containing exact
+unsent textarea text and owns their storage, retention, and privacy behavior.
+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](./security-privacy.md#custom-storage).
+
+---
+
+## Runtime changes
+
+You can change most options after mount via `chat.update(...)`:
+
+```ts
+const chat = init({ publicKey: 'agent_pk_...', aiAgentDeploymentId: '01900000-0000-7000-8000-000000000000' });
+
+// Later — flip to dark mode
+chat.update({ theme: 'dark' });
+
+// Or change the launcher label
+chat.update({ launcher: { variant: 'pill', label: 'New message!' } });
+```
+
+`update()` is a **shallow merge** at the top level. Nested objects are
+replaced, not merged:
+
+```ts
+chat.update({ presentation: { size: { expanded: { width: '800px' } } } });
+// This replaces the whole `presentation` section — mode, iframe, and the other size fields are gone!
+
+// Keep the current section in your application state and spread each nested level you preserve:
+chat.update({
+  presentation: {
+    ...currentPresentation,
+    size: {
+      ...currentPresentation.size,
+      expanded: { width: '800px' },
+    },
+  },
+});
+```
+
+The `publicKey`, `widgetId`, `presentation.mode`, and `presentation.iframe` can't change at runtime
+— they require a full remount (`destroy()` + `mount()`).
+
+---
+
+## Putting it all together — full example
+
+```ts
+import { init } from '@helpai/elements';
+
+const chat = init({
+  // Identity
+  publicKey: process.env.NEXT_PUBLIC_HELPAI_KEY!,
+  aiAgentDeploymentId: process.env.NEXT_PUBLIC_HELPAI_DEPLOYMENT_ID!,
+  widgetId: 'support',
+  userContext: { id: currentUser.id, email: currentUser.email, name: currentUser.name },
+  pageContext: { area: 'support', path: location.pathname },
+
+  // Presentation + behavior
+  presentation: {
+    mode: 'floating',
+    position: 'bottom-right',
+    size: {
+      expanded: { width: '720px', height: '85vh' },
+      resize: { enabled: true, minWidth: '360px', maxWidth: '900px' },
+      initialSize: 'auto',
+      autoSizeBreakpoint: 1024,
+    },
+  },
+  behavior: { startMinimized: true },
+  theme: { accent: '#ff3e00', radius: '12px' },
+
+  // Launcher
+  launcher: {
+    variant: 'pill',
+    label: 'Ask us anything',
+    icon: 'chat',
+    callout: { text: 'Hey there 👋', delayMs: 2000 },
+  },
+
+  // i18n
+  i18n: {
+    availableLocales: ['en', 'fr', 'es'],
+    defaultLocale: 'auto',
+    strings: {
+      en: { composerPlaceholder: 'Ask about anything…' },
+      fr: { composerPlaceholder: 'Demandez-moi…' },
+    },
+  },
+
+  // Feedback
+  feedback: { sound: { enabled: true, volume: 0.25 } },
+
+  // Footer
+  footer: {
+    composerDisclaimer: 'AI-generated answers may contain mistakes.',
+    poweredBy: { text: 'Powered by Help AI', href: 'https://help.ai' },
+  },
+
+  // Events
+  onMessage: (m) => analytics.track('chat_message', m),
+  onError: (err) => Sentry.captureException(err),
+});
+```
+
+---
+
+## Not covered here
+
+- **Events** → [Events & hooks](./events-and-hooks.md)
+- **Theming deep-dive** → [Theming](./theming.md)
+- **Framework-specific wiring** → [Frameworks](./frameworks.md)
+- **Backend API** → Backend contract (internal)