@helpai/elements 1.7.0 → 1.9.0

package/web-component.d.ts

@@ -1,23 +1,1567 @@
+import { z } from "zod";
 /**
- * Custom element `<web-ai-chat>`.
+ * Pluggable client-side key-value storage.
  *
- * Attributes are a curated flat projection of {@link ChatWidgetOptions}:
- * `mode` maps to `presentation.mode`, `response-mode` to
- * `behavior.responseMode`, and so on. Reactive attributes trigger a
- * re-resolve when they change at runtime — see {@link REACTIVE_ATTRS}.
+ * Drop in a custom adapter to:
+ * - Add logging / analytics around reads + writes
+ * - Encrypt or sign values
+ * - Use a different backing store (sessionStorage, IndexedDB shim, in-memory)
+ * - Add quota / migration handling
  *
- * Mode resolution: the tag itself doesn't pin a default mode. When no
- * `mode=…` attribute is set, the resolver default (`"floating"`) seeds
- * the very first frame — which the App's handshake gate keeps blank
- * — then the server's pushed `config.presentation.mode` wins via the
- * shared runtime's handshake merge. Drop a bare `<web-ai-chat
- * public-key="…" ai-agent-deployment-id="…">` on the page and the
- * deployment's dashboard config drives the layout.
+ * The default implementation is {@link LocalStorageAdapter} — a thin wrapper
+ * over `localStorage` with try/catch around every call so storage being
+ * disabled (private mode pre-iOS 11, floating webviews, quota exceeded)
+ * silently degrades to no-op rather than throwing.
  *
- * Everything between `<App>` and the shadow host — the ErrorBoundary, the
- * handshake-config merge, the usage tracker, host-attribute application — lives
- * in the shared {@link createWidgetRuntime} that `mount()` (`src/index.ts`) also
- * uses, so the two boot paths can't drift. This file owns only what's specific
- * to the custom element: attribute parsing and the connect/disconnect lifecycle.
+ * Values are stored as opaque strings — the persistence layer above
+ * serialises typed values to JSON before calling `set`.
  */
+interface ClientStorage {
+  /** Returns the stored string for `key`, or `null` when absent / unreadable. */
+  get(key: string): string | null;
+  /** Stores `value` under `key`. Best-effort — silent on quota / disabled storage. */
+  set(key: string, value: string): void;
+  /** Removes `key`. No-op if absent. */
+  remove(key: string): void;
+}
+/**
+ * UI strings — built-in defaults, type contracts, and runtime resolution.
+ *
+ * The widget bundles five complete locales (en/fr/ar/es/he — English is also the
+ * fallback for any missing key; see {@link BUILTIN_STRINGS}). Further locales, or
+ * per-key overrides, are supplied by the page owner (`init({ i18n: { strings } })`)
+ * or the SaaS backend in `config.i18n.strings` — both pushed *partially*: only the keys
+ * they want to override.
+ *
+ * To keep render hot-paths cheap, the merged shape is **pre-computed once**
+ * (at config-resolve time and after each server-settings merge) into a fully
+ * populated {@link Strings} map. UI components then read `strings.send` as a
+ * normal property access — no per-render lookup, no per-render allocation.
+ */
+type StringKey = 'launcherOpen' | 'launcherLabel' | 'panelTitle' | 'composerPlaceholder' | 'send' | 'stop' | 'queueMessage' | 'removeQueuedMessage' | 'compactingContext' | 'attach' | 'micStart' | 'micStop' | 'micUnsupported' | 'expand' | 'collapse' | 'fullscreen' | 'exitFullscreen' | 'popOut' | 'resizeHandle' | 'scrollToBottom' | 'close' | 'moreActions' | 'soundOn' | 'soundOff' | 'language' | 'theme' | 'themeAuto' | 'themeLight' | 'themeDark' | 'textSize' | 'textSizeSmall' | 'textSizeNormal' | 'textSizeLarge' | 'history' | 'historyTitle' | 'historyEmpty' | 'historyLoading' | 'historyBack' | 'historyContinue' | 'loadMoreConversations' | 'conversationLoading' | 'loadPreviousMessages' | 'conversationClosed' | 'startNewConversation' | 'talkToOperator' | 'connectingOperator' | 'noOperatorAvailable' | 'chattingWithOperator' | 'cancelOperatorRequest' | 'dateToday' | 'dateYesterday' | 'dateLastWeek' | 'dateOlder' | 'newConversation' | 'dropZone' | 'attachmentTooLarge' | 'attachmentTooMany' | 'attachmentMimeRejected' | 'errorRetry' | 'errorGeneric' | 'errorRateLimited' | 'loading' | 'visualPreparing' | 'visualError' | 'visualPartial' | 'thinking' | 'thoughts' | 'toolResult' | 'sources' | 'feedbackUp' | 'feedbackDown' | 'feedbackThanks' | 'copy' | 'copied' | 'collapseSidebar' | 'expandSidebar' | 'formSubmit' | 'formSkip' | 'formSubmitted' | 'formSkipped' | 'formFillOut' | 'formRequired' | 'formInvalidEmail' | 'formInvalidTel' | 'formInvalidUrl' | 'formInvalidNumber' | 'formTooShort' | 'formTooLong' | 'formNumberTooSmall' | 'formNumberTooLarge' | 'formPatternMismatch' | 'formChooseAtLeast' | 'formChooseAtMost' | 'formOther' | 'formOtherPlaceholder' | 'inputRequired' | 'inputBadge' | 'inputAnswered' | 'inputSkipped' | 'inputSubmit' | 'inputSubmitHint' | 'inputSkip' | 'showOptions' | 'hideOptions' | 'qtypeText' | 'qtypeEmail' | 'qtypePhone' | 'qtypeNumber' | 'qtypeDate' | 'qtypeChooseOne' | 'qtypeChooseAny' | 'qtypeBoolean' | 'confirmYes' | 'confirmNo' | 'approve' | 'reject' | 'approvalPrompt' | 'approvalBody' | 'approvalYourResponse' | 'approvalEditHint' | 'approvalSubmitting' | 'edit' | 'toolParameters' | 'statusAwaiting' | 'statusResponded' | 'statusCompleted' | 'statusDenied' | 'statusError' | 'statusRunning' | 'statusSuperseded' | 'tabHome' | 'tabConversations' | 'tabHelp' | 'tabNews' | 'modulesEmpty' | 'moduleBack' | 'contentLoading' | 'contentHelpful' | 'homeGreeting' | 'homeGreetingNamed' | 'homeGreetingLead' | 'homeSearchPlaceholder' | 'homeAskPlaceholder' | 'homeWhatsNew' | 'homeContentTitle' | 'homeStatus' | 'helpTitle' | 'helpSearchPlaceholder' | 'helpEmpty' | 'helpLoading' | 'helpSearchEmpty' | 'helpShowMore' | 'newsTitle' | 'newsEmpty' | 'newsLoading' | 'newsBack' | 'newsPublishedAt' | 'newsShowMore' | 'newsUnseen';
+/** A partial map for one locale — what overrides look like on the wire. */
+type LocaleStrings = Partial<Record<StringKey, string>>;
+/**
+ * Override shape accepted by both `init({ i18n: { strings } })` and the server's
+ * `config.i18n.strings`. Two forms supported:
+ *
+ * 1. **Flat** — `{ send: "Click", stop: "Halt" }`. Applies to the active
+ *    locale. Convenient for single-language deployments.
+ * 2. **Nested** — `{ en: { send: "Click" }, fr: { send: "Cliquer" } }`.
+ *    Lets a multilingual backend push every translation in one payload —
+ *    the widget picks the entry matching the user's locale and falls back
+ *    to the `en` entry (then to built-in English) for any missing keys.
+ *
+ * Both forms may be **partial** at every level — anything you don't supply
+ * inherits the built-in default. Detection is by value type: if any
+ * top-level value is an object, the whole override is treated as nested.
+ */
+type StringsOverride = LocaleStrings | Partial<Record<string, LocaleStrings>>;
+/**
+ * Primitive type aliases shared across every config section. Kept in
+ * one file so a domain-specific change (adding a new `Mode` value,
+ * say) doesn't churn many files.
+ */
+/** Screen corner the floating launcher anchors to (ignored in `inline` / `standalone`). */
+type Position = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+/**
+ * Runtime rendering mode — what the widget *looks like* on the page.
+ *
+ * - `floating`   — floating launcher FAB + popover panel.
+ * - `inline`     — full chat in normal flow, sized to its container.
+ * - `standalone` — fills the viewport (panel only, no sidebar).
+ * - `page`       — full viewport with sidebar (logo + nav blocks + conversation list) + chat.
+ * - `modal`      — centered modal with dimmed backdrop. No launcher FAB —
+ *                  the page brings its own trigger and calls
+ *                  `instance.open()`. Sized via `size.width` / `size.height`.
+ *                  Defaults: `startMinimized: true` (so it doesn't auto-open),
+ *                  Escape + backdrop-click close.
+ * - `drawer`     — side-docked flyout. The page stays interactive
+ *                  alongside (no backdrop). Width comes from `size.width`
+ *                  (default 440px). Side comes from `position`. Defaults
+ *                  to a flyout with `size.inset: "3vh"` vertical /
+ *                  `"12px"` horizontal — restore the legacy full-edge
+ *                  slab with `size: { width: "100vw", height: "100vh", inset: "0" }`.
+ *
+ * Page mode reads `site` and `blocks` from the handshake response.
+ */
+type Mode = 'floating' | 'inline' | 'standalone' | 'page' | 'modal' | 'drawer';
+/** End-user text-size preference — scales the whole type ramp. */
+type TextSize = 'small' | 'normal' | 'large';
+/** Theme preference. `auto` follows `prefers-color-scheme`; `host` follows the page's own light/dark. */
+type ThemePreference = 'auto' | 'light' | 'dark' | 'host';
+/**
+ * How the assistant's reply is delivered.
+ *
+ * - `'streaming'` (default) — per-token deltas arrive as the model generates;
+ *   user sees a typewriter effect in real time.
+ * - `'buffered'` — server buffers the complete reply, then sends it as one
+ *   chunk. The UI shows a "thinking…" indicator until the reply appears
+ *   whole.
+ */
+type ResponseMode = 'streaming' | 'buffered';
+/**
+ * Identifiers for every header action the widget can render.
+ *
+ * `history` + `close` render as dedicated header buttons; the rest appear in
+ * the ⋯ overflow menu. The enabled set is a flat {@link ActionList}; order is
+ * irrelevant (the menu has a fixed layout). Unlisted actions are hidden.
+ *
+ * - `clear`       — Start a new conversation (compose icon).
+ * - `expand`      — Toggle `normal` ↔ `expanded` (1.5× panel).
+ * - `fullscreen`  — Toggle `normal` ↔ `fullscreen` (viewport fill).
+ * - `popOut`      — Open the active conversation in a dedicated tab.
+ * - `sound`       — Toggle notification sounds + haptics on/off (switch-style).
+ * - `language`    — Switch the UI locale at runtime.
+ * - `theme`       — Cycle `auto` / `light` / `dark`.
+ * - `textSize`    — Cycle `normal` / `large` / `small`.
+ * - `close`       — Close the floating panel.
+ */
+type ActionName = 'clear' | 'expand' | 'fullscreen' | 'popOut' | 'sound' | 'history' | 'language' | 'theme' | 'textSize' | 'close';
+/**
+ * The header's enabled actions. Unlisted actions are hidden; order is
+ * irrelevant. Per-mode defaults (`DEFAULT_ACTIONS_BY_MODE`) pick a sensible
+ * set for each mode; a deployment can replace the whole list.
+ */
+type ActionList = ActionName[];
+/**
+ * Composer chrome and capability flags. `ChatWidgetOptions.composer` owns the
+ * send-button skin + attachment limits; `ChatWidgetOptions.features` owns voice,
+ * file-upload, HITL, and operator gates.
+ */
+/**
+ * How voice input is captured and transcribed.
+ *
+ * - `'local'` (default when supported) — Web Speech API, runs in the browser.
+ *   Free, no audio ever leaves the device; quality varies by browser.
+ * - `'server'` — record audio with `MediaRecorder`, upload to the transcribe
+ *   endpoint, receive text back. Consistent quality; uses your upload quota.
+ * - `'disabled'` — hide the mic button entirely.
+ */
+type VoiceMode = 'local' | 'server' | 'disabled';
+/** Capability flags. Any field left `undefined` uses its default. */
+interface FeatureFlags {
+  /** Voice input behaviour (see {@link VoiceMode}). Default: `'local'`. */
+  voice?: VoiceMode;
+  /**
+   * Turn OFF the human-in-the-loop tool UI — the inline ask-questions form and the
+   * approve/reject controls for gated tools. Unset/`false` = shown (default); `true`
+   * suppresses the UI (the wire still carries the signals; they just won't show).
+   */
+  disableHumanInLoop?: boolean;
+  /**
+   * Turn OFF file uploads — hide the paperclip button + reject drag/drop/paste.
+   * Unset/`false` = enabled (default); `true` disables them.
+   */
+  disableFileUpload?: boolean;
+  /**
+   * Opt IN operator control — exposes the "Talk to a person" affordance + connected-to-operator
+   * states. Positive opt-in (unlike the `disable*` flags) for a new capability; default off.
+   */
+  enableOperatorRequest?: boolean;
+}
+/**
+ * Client-side attachment limits. Server enforcement is still required —
+ * these prevent wasted upload bandwidth and give the user fast feedback.
+ */
+interface AttachmentLimits {
+  maxBytes?: number;
+  maxCount?: number;
+  /** Comma-separated MIME allowlist, e.g. `'image/*,application/pdf'`. */
+  accept?: string;
+}
+/** Outline shape of the send button. */
+type SendButtonShape = 'circle' | 'square' | 'pill';
+/** Icon shown inside the send button. */
+type SendButtonIcon = 'arrowUp' | 'paperPlane' | 'send' | 'chevron';
+/** Fill/stroke treatment. */
+type SendButtonVariant = 'filled' | 'outline' | 'ghost';
+interface SendButtonOptions {
+  /** Outline shape. Default: `"circle"`. */
+  shape?: SendButtonShape;
+  /** Icon inside the button. Default: `"arrowUp"`. */
+  icon?: SendButtonIcon;
+  /** Fill treatment. Default: `"filled"`. */
+  variant?: SendButtonVariant;
+}
+interface ComposerOptions {
+  sendButton?: SendButtonOptions;
+  /** Client-side attachment limits. Server still validates at upload time. */
+  attachments?: AttachmentLimits;
+}
+/**
+ * Audible + tactile feedback knobs. Both channels default to enabled (browser
+ * autoplay policy still gates audio playback).
+ */
+/** Lifecycle events the feedback bus can react to. */
+type FeedbackEvent = 'messageReceived' | 'messageSent' | 'error' | 'voiceStart' | 'voiceStop';
+/**
+ * Per-event sound configuration.
+ *
+ * - `true`   — use the built-in synthesised tone.
+ * - `false`  — disable this event's sound.
+ * - `string` — URL to a custom audio file (MP3, WAV, OGG). Decoded once + cached.
+ */
+type SoundEventValue = boolean | string;
+interface SoundOptions {
+  /** Master on/off. Default: `true` (browser autoplay policy still applies). */
+  enabled?: boolean;
+  /** Global volume 0..1. Default: `0.3` (subtle). */
+  volume?: number;
+  /** Per-event overrides. Missing keys use the built-in default (see feedback/defaults). */
+  events?: Partial<Record<FeedbackEvent, SoundEventValue>>;
+}
+/**
+ * Per-event haptic pattern. Android `navigator.vibrate()` shape.
+ *
+ * - `true`                — use the default pattern for this event.
+ * - `false`               — disable haptics for this event.
+ * - `number`              — single vibration of that many ms.
+ * - `number[]`            — alternating `[vibrate, pause, vibrate, …]`.
+ *
+ * iOS Safari has no custom-pattern support; supported events fire a single
+ * system haptic via the `<input type=checkbox switch>` trick.
+ */
+type HapticEventValue = boolean | number | number[];
+interface HapticsOptions {
+  /** Default: `true` on touch devices, silently ignored elsewhere. */
+  enabled?: boolean;
+  events?: Partial<Record<FeedbackEvent, HapticEventValue>>;
+}
+/**
+ * Section: audible + tactile feedback. Both channels default to enabled
+ * (browser autoplay policy still gates audio playback).
+ */
+interface FeedbackOptions {
+  sound?: SoundOptions;
+  haptics?: HapticsOptions;
+}
+/**
+ * Event-driven forms engine — framework-free runtime types (mirror of
+ * `src/schema/widget/forms.ts`). The IIFE path has no Zod, so these plain
+ * interfaces are what the resolver, controller, and form UI consume.
+ *
+ * A deployment declares an array of {@link FormDef}s; each is bound to trigger
+ * event(s) and shown as a gate that replaces the composer (locking the chat
+ * until submit/skip). Its answers are recorded via one shared submit endpoint.
+ * Generic across verticals — there is NO industry logic; a clinic intake, an
+ * insurance claim form, a CSAT survey, and a sales signal capture are all just
+ * different config.
+ *
+ * The same {@link FormField} shape powers the AI-driven ask-questions tool.
+ */
+/** A renderable field type. `multiselect` collects an array of values. */
+type FieldType = 'text' | 'email' | 'tel' | 'url' | 'number' | 'date' | 'time' | 'textarea' | 'select' | 'radio' | 'checkbox' | 'multiselect';
+/** One choice for `select` / `radio` / `multiselect` fields. */
+interface FieldOption {
+  value: string;
+  /** Display text; falls back to `value`. */
+  label?: string;
+  description?: string;
+}
+/** Validation constraints applied client-side (the backend still validates). */
+interface FieldValidation {
+  /** Regex source string (anchored as written) — text-like fields. */
+  pattern?: string;
+  minLength?: number;
+  maxLength?: number;
+  /** Numeric range — `number` fields. */
+  min?: number;
+  max?: number;
+  /** Selection-count bounds — `multiselect` fields. */
+  minSelections?: number;
+  maxSelections?: number;
+}
+/** One field in a form. */
+interface FormField {
+  /** Stable key the value is recorded under (e.g. `email`). */
+  name: string;
+  label: string;
+  type: FieldType;
+  placeholder?: string;
+  required?: boolean;
+  /** Pre-filled value (string for scalars; comma-joined for `multiselect`). */
+  defaultValue?: string;
+  /** Choices for `select` / `radio` / `multiselect`. */
+  options?: FieldOption[];
+  validation?: FieldValidation;
+  /** `select`/`radio`/`multiselect` — allow a free-text "Other" answer. */
+  allowOther?: boolean;
+  /** Small helper line under the field. */
+  validationHint?: string;
+}
+/**
+ * Trigger that surfaces a form. Terse string with an optional `:param` so it's
+ * serializable + server-pushable. `after-messages:3`, `idle:30`,
+ * `page-area:pricing`.
+ */
+type FormTrigger = 'pre-chat' | `after-messages:${number}` | 'conversation-closed' | 'panel-close' | `idle:${number}` | `page-area:${string}` | 'manual';
+/**
+ * Extra eligibility predicate, evaluated when a trigger fires. Small and
+ * declarative on purpose — richer routing belongs to the agent / backend.
+ */
+interface FormCondition {
+  /** Only show if `userContext` lacks ALL of these keys (progressive profiling). */
+  missingContext?: string[];
+  /** Only on these page areas (`pageContext.area`). */
+  pageArea?: string | string[];
+  minMessages?: number;
+  maxMessages?: number;
+}
+/**
+ * How often a form may show: `once` per device (persisted), once per
+ * `conversation` (re-eligible when a new conversation starts), or `always`.
+ */
+type FormFrequency = 'once' | 'conversation' | 'always';
+/** One form as authored in config (raw input). */
+interface FormDef {
+  /** Stable id — persistence dedupe + `manual` `openForm(id)`. */
+  id: string;
+  on: FormTrigger | FormTrigger[];
+  when?: FormCondition;
+  fields: FormField[];
+  title?: string;
+  description?: string;
+  submitLabel?: string;
+  skippable?: boolean;
+  /** Default `once`. */
+  frequency?: FormFrequency;
+  /**
+   * Mirror the submitted answers into `userContext` so they ride every
+   * subsequent request (the agent sees them in-conversation). Default `true`.
+   * Set `false` for PII (DOB, policy #, symptoms) — those then go ONLY to the
+   * submit endpoint, never onto the always-on context envelope.
+   */
+  mirrorToContext?: boolean;
+  /**
+   * Skipped marker offers a "Fill out" button that reopens the form (skip is
+   * a deferral, not a refusal). Default `true`. Set `false` when a skip must
+   * be final — e.g. a consent ask that should not be re-surfaced.
+   */
+  reopenable?: boolean;
+  /**
+   * Submitted marker expands in place to a read-only list of the visitor's
+   * answers. Default `true`. Set `false` to keep the marker plain — e.g.
+   * sensitive answers that shouldn't linger on screen (pairs with
+   * `mirrorToContext: false`; the backend should also omit `values` from the
+   * `bootstrap` `formSubmissions` records for such forms).
+   */
+  reviewable?: boolean;
+  /** BCP-47 locale the top-level strings (title / fields copy) are authored in. */
+  defaultLocale?: string;
+  /**
+   * Per-locale string overrides. The data module trims this to the requested
+   * `?locale=` (≤1 entry); the widget overlays it onto the default copy at
+   * resolve time (`overlayFormDef`). Absent strings fall back to the default.
+   */
+  translations?: FormTranslation[];
+}
+/**
+ * Per-locale overrides of a form's HUMAN-FACING strings only. Structure (field
+ * `name` / `type` / `validation`, option `value`) is shared across locales and
+ * stays canonical, so submissions + validation are locale-independent — a
+ * translation matches the canonical form by the stable `name` (field) / `value`
+ * (option) keys. Absent strings fall back to the top-level (defaultLocale) copy.
+ *
+ * The data module trims `FormDef.translations` to the requested `?locale=` (≤1
+ * entry) on read; the widget overlays that entry onto the default fields. Mirror
+ * of `module-data-api` `FormTranslation`.
+ */
+interface FieldOptionTranslation {
+  /** The canonical option `value` this localizes. */
+  value: string;
+  label?: string;
+  description?: string;
+}
+interface FormFieldTranslation {
+  /** The canonical field `name` this localizes. */
+  name: string;
+  label?: string;
+  placeholder?: string;
+  validationHint?: string;
+  options?: FieldOptionTranslation[];
+}
+interface FormTranslation {
+  locale: string;
+  title?: string;
+  description?: string;
+  submitLabel?: string;
+  fields?: FormFieldTranslation[];
+}
+/** The `forms` block is an ordered list (max 20); order = priority. */
+type FormsOptions = FormDef[];
+/**
+ * Launcher (floating-mode FAB) + the pre-engagement callout bubble.
+ * Inputs are option-bag shaped; the resolved variant lives in `widget.ts`.
+ */
+/**
+ * Launcher visual variant.
+ *
+ * - `circle` — icon only, round bubble (default).
+ * - `pill` — icon + label, pill-shaped.
+ * - `bar` — rectangular button, stretches with content.
+ * - `minimal` — transparent outline, text-only.
+ */
+type LauncherVariant = 'circle' | 'pill' | 'bar' | 'minimal';
+/** Launcher size preset. Resolves to concrete CSS lengths in panel.css. */
+type LauncherSize = 'sm' | 'md' | 'lg';
+/**
+ * Visual variant of the launcher callout bubble.
+ *
+ * - `pill`    — short, rounded label with a tiny arrow toward the FAB.
+ *               Best for one-liners like "Click here →".
+ * - `bubble`  — speech-bubble shape with a tail. Friendly persona feel.
+ * - `callout` — larger pill with a louder arrow. Most attention-grabbing.
+ */
+type CalloutShape = 'pill' | 'bubble' | 'callout';
+/**
+ * Side of the launcher the callout anchors to. `auto` picks the side
+ * facing into the page based on the FAB's corner. Picks pointing AT the
+ * FAB's own viewport edge auto-flip to the opposite side.
+ */
+type CalloutPosition = 'auto' | 'horizontal' | 'vertical';
+/**
+ * Pre-engagement message bubble next to the FAB. Use it for a greeting
+ * ("👋 Hi, need help?"), an attention-grabbing nudge ("Click here →"),
+ * or an onboarding tip — same component, configured for the use case.
+ *
+ * `persistent: true` (default) → re-show on every visit regardless of
+ *                                 dismissal.
+ * `persistent: false` → clicking X stores this exact text and keeps it
+ *                       hidden across visits.
+ */
+interface LauncherCalloutOptions {
+  /** Text content. Empty string hides the callout. */
+  text: string;
+  /** Visual shape. Default: `"pill"`. */
+  shape?: CalloutShape;
+  /** Side of the launcher to anchor on. Default: `"auto"`. */
+  position?: CalloutPosition;
+  /** Delay before the bubble appears (ms). Default: `1200`. */
+  delayMs?: number;
+  /** Auto-dismiss after this many ms. Default: never (`0`). */
+  autoDismissMs?: number;
+  /** Animate with a subtle horizontal nudge. Default: `true`. */
+  animated?: boolean;
+  /** Re-show on every visit regardless of prior dismissal. Default: `true`. */
+  persistent?: boolean;
+}
+/** Launcher appearance + behaviour. Only applies in `floating` mode. */
+interface LauncherOptions {
+  variant?: LauncherVariant;
+  size?: LauncherSize;
+  label?: string;
+  icon?: string;
+  hidden?: boolean;
+  /** Pre-engagement bubble next to the FAB. See {@link LauncherCalloutOptions}. */
+  callout?: LauncherCalloutOptions;
+}
+/**
+ * Messenger "modules" runtime config types — framework-free mirror of
+ * `src/schema/widget/modules.ts`. The IIFE runtime path has no Zod, so
+ * these plain interfaces are what the resolver + UI consume.
+ *
+ * `modules` is an ordered list of tabs; each picks a UI `layout`, the content
+ * collections it shows (`contentCollectionIds` — the filter on `GET /pai/content`),
+ * and a translatable `label`.
+ */
+/** The UI layouts a tab can render with. `chat` is the conversation; the rest render content. */
+type ModuleLayout = 'chat' | 'home' | 'help' | 'news';
+/** A team/agent avatar shown in the Home hero. */
+interface ModuleAvatar {
+  name: string;
+  /** Image URL; initials of `name` are shown when omitted. */
+  avatar?: string;
+  role?: string;
+}
+/** The Home status card. */
+interface ModuleStatus {
+  /**
+   * Status line. An i18n key or a literal (resolved via `localizeText`).
+   * Omit to use the built-in generic `homeStatus` string — so a deployment can
+   * show a localized status without authoring copy or a custom key per locale.
+   */
+  text?: string;
+  /**
+   * Status severity → status-icon colour. Free text; `operational` (default),
+   * `degraded`, and `down` are styled, any other value uses the operational style.
+   */
+  level?: string;
+  /** Opens in an in-widget iframe when tapped. */
+  url?: string;
+}
+/**
+ * `home` layout config — flat feature flags (no block authoring). The Home tab
+ * is assembled from these in a fixed order: greeting → search → recent conversation
+ * → status → a content list (the pinned items of the tab's `contentCollectionIds`,
+ * titled `contentBlockTitle`).
+ */
+interface HomeConfig {
+  brandName?: string;
+  hideGreeting?: boolean;
+  greetingText?: string;
+  userAvatars?: ModuleAvatar[];
+  hideSearchBar?: boolean;
+  hideRecentConversations?: boolean;
+  status?: ModuleStatus;
+  contentBlockTitle?: string;
+}
+/** One tab as authored in config (raw input). */
+interface ModuleOptions extends HomeConfig {
+  label: string;
+  layout: ModuleLayout;
+  /** Content collections this tab shows, in order (max 20). */
+  contentCollectionIds?: string[];
+  id?: string;
+}
+/** The `modules` block is an ordered list of tabs (max 4). */
+type ModulesOptions = ModuleOptions[];
+/** CSS-custom-property overrides applied as inline styles on the host. */
+interface ThemeOverrides {
+  /** Light/dark beside the overrides — `host` keeps a deployment's accent while the page sets the mode. */
+  mode?: ThemePreference;
+  accent?: string;
+  accentText?: string;
+  radius?: string;
+  fontFamily?: string;
+  /** Readable content-column cap (→ `--conversation-max`). CSS length; default `768px`. */
+  contentMaxWidth?: string;
+}
+/**
+ * Widget sizing overrides. Each field accepts any valid CSS length
+ * (`'640px'`, `'80vh'`, `'calc(100vh - 64px)'`).
+ *
+ * Three display sizes are supported (in order from compact to largest):
+ * 1. **normal** — default. Uses `width`/`height` (or CSS defaults).
+ * 2. **expanded** — triggered by the expand header button. Uses
+ *    `expanded.width`/`expanded.height`.
+ * 3. **fullscreen** — triggered by the fullscreen header button. Always
+ *    fills the viewport regardless of other dimensions.
+ */
+interface SizeOptions {
+  /** Normal-mode width. Default: mode-specific (see `src/styles/panel.css`). */
+  width?: string;
+  /** Normal-mode height. Default: mode-specific. */
+  height?: string;
+  /** Dimensions when the user clicks the expand button. */
+  expanded?: {
+    width?: string;
+    height?: string;
+  };
+  /**
+   * Edge inset for `drawer` mode — turns the side dock into a flyout
+   * with the given gap from each viewport edge (`16px`, `2vh`,
+   * `min(24px, 4vw)`, …). Combine with a partial `height` (`80vh`,
+   * `min(720px, calc(100vh - 32px))`) for the classic floating
+   * side-panel look. Ignored by every other mode.
+   */
+  inset?: string;
+  /** Enable + configure user-drag resize of the panel in normal mode. */
+  resize?: ResizeOptions;
+  /**
+   * Which size to open with on the **first** render.
+   *
+   * - `"auto"` (**default**, also when omitted) — responsive by viewport: phones
+   *   (`window.innerWidth < 640`) open `fullscreen` edge-to-edge, tablets
+   *   (`640 … autoSizeBreakpoint`) open `normal`, desktop/laptop
+   *   (`≥ autoSizeBreakpoint`) open `expanded`. Right for the device with no config;
+   *   the backend can tune the desktop breakpoint without baking it into the frontend.
+   * - `"normal"` — force the compact panel everywhere.
+   * - `"expanded"` — force-start at the configured `expanded.width/height`.
+   * - `"fullscreen"` — force-start at viewport fill.
+   *
+   * Only applies to the very first mount. The user's last size is
+   * preserved across close → reopen; a page reload re-evaluates.
+   * Standalone / page mode always overrides to `fullscreen`.
+   *
+   * Default: `"auto"`.
+   */
+  initialSize?: 'auto' | 'normal' | 'expanded' | 'fullscreen';
+  /**
+   * Viewport-width threshold (px) above which `initialSize: "auto"` picks
+   * `"expanded"`. Default: `900`.
+   */
+  autoSizeBreakpoint?: number;
+}
+/**
+ * Drag-resize configuration. When `enabled`, a corner grip appears on the
+ * panel; the user drags it to resize. The resolved dimensions persist via
+ * `userPrefs.widgetSize` (cached client-side + synced to the backend).
+ */
+interface ResizeOptions {
+  /** Show the resize grip. Default: `false`. */
+  enabled?: boolean;
+  minWidth?: string;
+  maxWidth?: string;
+  minHeight?: string;
+  maxHeight?: string;
+}
+/**
+ * Section: how the widget physically presents itself on the page.
+ */
+interface PresentationOptions {
+  mode?: Mode;
+  position?: Position;
+  /**
+   * Wrap the widget in a same-origin iframe for strict JS + CSS isolation
+   * beyond what shadow DOM provides. Composes with every mode.
+   */
+  iframe?: boolean;
+  size?: SizeOptions;
+}
+/**
+ * Section: conversation runtime behaviour — auto-open, streaming mode, and the
+ * transcript surface (what renders, how it scrolls, reaction controls).
+ */
+interface BehaviorOptions {
+  /** When `true`, don't auto-open the panel on first visit. */
+  startMinimized?: boolean;
+  /** Streaming vs. buffered reply delivery. */
+  responseMode?: ResponseMode;
+  /** Show the model's reasoning ("thoughts") as a collapsible block. Default `false`. */
+  showReasoning?: boolean;
+  /** Show automatic tool/function calls (details + result) in the transcript. Default `false`. */
+  showToolCalls?: boolean;
+  /** Show citation sources (web links + document references) in the transcript. Default `false`. */
+  showSources?: boolean;
+  /** Turn OFF the 👍/👎 feedback controls on rateable (assistant/operator) replies. Unset/`false` = shown (default). */
+  disableMessageFeedback?: boolean;
+  /** Auto-send a suggestion chip's text on tap. Unset/`false` = fill the composer to edit (default). */
+  autoSendSuggestions?: boolean;
+  /** URL opened by the `popOut` header action. */
+  popOutUrl?: string;
+}
+/**
+ * Section: panel header actions — the enabled set (`history`/`close` buttons +
+ * ⋯ menu). Unlisted actions are hidden.
+ */
+interface HeaderOptions {
+  actions?: ActionList;
+}
+/**
+ * Section: locale resolution + per-instance string overrides.
+ *
+ * Order of precedence at startup:
+ * 1. End-user's persisted picker choice (if matches `availableLocales`).
+ * 2. `i18n.locale` (page-owner explicit override).
+ * 3. Server-pushed `i18n.defaultLocale`.
+ * 4. `navigator.language` (when default is `"auto"`).
+ * 5. `"en"` ultimate fallback.
+ */
+interface I18nOptions {
+  locale?: string;
+  defaultLocale?: string;
+  availableLocales?: string[];
+  strings?: StringsOverride;
+}
+/**
+ * "Powered by …" attribution shown below the composer. Any combination of
+ * logo + text + href is valid; all three absent hides the element.
+ */
+interface PoweredByOption {
+  /** Visible text (e.g. `"Powered by Help AI"`). */
+  text?: string;
+  /** If set, the attribution is an `<a>` pointing here (`noopener noreferrer`). */
+  href?: string;
+  /** Optional small logo URL rendered before the text. */
+  logoUrl?: string;
+}
+/**
+ * Section: footer area below the composer — brand attribution and
+ * the optional ChatGPT-style "AI can make mistakes" disclaimer.
+ */
+interface FooterOptions {
+  /** Optional "Powered by …" attribution rendered below the disclaimer. */
+  poweredBy?: PoweredByOption;
+  /**
+   * Small muted text rendered below the composer. Same pattern as ChatGPT's
+   * "ChatGPT can make mistakes." When absent / empty, the line is hidden.
+   */
+  composerDisclaimer?: string;
+}
+/**
+ * Host-asserted context about the current end-user, forwarded to the backend
+ * and the agent purely as **informational context** — never as an auth
+ * credential. The widget runs on third-party sites (e.g. `example.com`); some
+ * have their own login, others are guest-only. We don't register or
+ * authenticate these users (browser access always identifies a deployment;
+ * a public key is optional for intentional guest mode).
+ *
+ * `id` / `email` / `name` are recognised fields used for the Home greeting and
+ * transcripts; any extra scalar fields become custom context the agent can use
+ * (plan, role, signup date, …). Untrusted input — sanitised client-side via
+ * `sanitizeUserContext` before it goes on the wire.
+ */
+interface UserContext {
+  id?: string;
+  email?: string;
+  name?: string;
+  /** Subscription / pricing tier (e.g. `"pro"`). */
+  plan?: string;
+  /** The user's role on the host site (e.g. `"admin"`, `"member"`). */
+  role?: string;
+  /** Phone number. */
+  phone?: string;
+  /** Arbitrary extra scalar context forwarded to the agent. */
+  [key: string]: string | number | boolean | undefined;
+}
+/**
+ * Suggested values for {@link PageContext.area} — the host-defined surface the
+ * visitor is currently on. **Free-form**: any string is accepted; these are
+ * the common ones (they also drive editor autocomplete). The agent uses it to
+ * adapt routing / tone — a pricing-page visitor differs from a docs reader,
+ * a help-desk ticket, or a checkout.
+ */
+type PageArea = 'home' | 'docs' | 'help-desk' | 'support' | 'pricing' | 'checkout' | 'orders' | 'account' | 'blog' | (string & {});
+/**
+ * Host-asserted context about the *page / visit* — where on the site the
+ * visitor is and which surface they're using. Informational context for the
+ * agent, separate from {@link UserContext} (who the visitor is). `url`
+ * auto-fills from the host page's `location.href` when omitted. Untrusted —
+ * sanitised client-side before sending.
+ */
+interface PageContext {
+  /** Host-defined surface the visitor is on (see {@link PageArea}). */
+  area?: PageArea;
+  /** Full page URL. Auto-filled from `location.href` when omitted. */
+  url?: string;
+  /** Page path, e.g. `/pricing/enterprise`. */
+  path?: string;
+  /** Human-readable page title. */
+  title?: string;
+  /** Arbitrary extra scalar context about this page / visit. */
+  [key: string]: string | number | boolean | undefined;
+}
+/**
+ * Override the HTTP endpoints the widget calls. `upload` / `transcribe`
+ * paths are appended to the agent base (`${baseUrl}/api/agent`);
+ * `submitForm` is appended to the data base (`dataApiBaseUrl`). Absolute URLs
+ * also work (useful when the upload endpoint lives on a different origin
+ * like a CDN presign service).
+ */
+interface Endpoints {
+  /** File upload endpoint. Default: `'/pai/upload-file'`. */
+  upload?: string;
+  /** Voice transcription endpoint. Default: `'/pai/transcribe-audio'`. */
+  transcribe?: string;
+  /**
+   * Form submission endpoint. Default: `'/submit-form'`. When any form
+   * (a pre-chat signal capture, a CSAT survey, etc.) is completed, the widget POSTs
+   * the captured values here (fire-and-forget), keyed by the same `visitorId` +
+   * `conversationId` the conversation uses; the payload carries `formId` + `trigger`
+   * so the backend can route. Optional: a backend that doesn't implement it just
+   * 404s and the submission is ignored.
+   */
+  submitForm?: string;
+}
+/**
+ * Built-in anonymous usage tracking — utm.gif-style pixel hits that give
+ * the widget OWNER (the site embedding it) insights about how visitors
+ * use the widget: events, pages, devices, locales, funnels.
+ *
+ * Privacy contract (enforced in `src/core/tracking.ts`):
+ *   - never sends message text or form values —
+ *     event payloads pass through a static per-event allowlist;
+ *   - the only visitor identifier is the widget's existing anonymous
+ *     `visitorId`; deployment and anonymous conversation ids provide context;
+ *   - page metadata is origin + pathname, with query/hash removed;
+ *   - geo + browser are derived server-side (IP + User-Agent header),
+ *     never collected client-side;
+ *   - `navigator.globalPrivacyControl` / Do-Not-Track force it off
+ *     regardless of config.
+ */
+/** Section: anonymous owner-facing usage tracking. */
+interface TrackingOptions {
+  /**
+   * Master switch. Default `true` — the widget always fires; the data
+   * module gates ingestion per deployment server-side. Set `false`
+   * (deployment config or init) to silence the client entirely.
+   */
+  enabled?: boolean;
+  /**
+   * Pixel collector URL. Default: `${dataApiBaseUrl}/pai/elements-px.gif`
+   * (e.g. `https://help.ai/api/data/pai/elements-px.gif`).
+   */
+  endpoint?: string;
+  /**
+   * Per-widget-runtime sampling 0..1. `0.25` samples roughly a quarter of
+   * mounted runtimes; one decision is reused for that runtime's funnel.
+   * Default `1`.
+   */
+  sampleRate?: number;
+  /**
+   * Anti-forgery token, echoed as `tk=` on every hit. **Server-issued,
+   * never set by hand** — the backend mints it in the
+   * `/handshake` response (HMAC over `pk`/`vid`/expiry with a
+   * server-side secret; see `docs/api/tracking-collector.md`) and the
+   * collector verifies it statelessly. Opaque to the client.
+   */
+  token?: string;
+}
+/**
+ * Raw options passed to {@link mount}, {@link init}, the Web Component, or
+ * the `<script data-*>` auto-boot path. The public `mount()` / `init()`
+ * boundary requires `aiAgentDeploymentId`; parsers keep it optional while
+ * assembling an attribute snapshot so a missing value can fail at that boundary.
+ *
+ * Two layers:
+ *
+ *   - **Embed (L2)** — top-level fields owned by the customer's
+ *     developer (`publicKey`, `aiAgentDeploymentId`, `userContext`, …).
+ *     Issued by the SaaS portal, pasted into their site code.
+ *   - **Widget settings (L3)** — nested sections owned by the portal
+ *     admin: `presentation`, `behavior`, `theme`, `launcher`, `header`,
+ *     `composer`, `feedback`, `i18n`, `footer`, `features`, and the other
+ *     schema-backed sections below.
+ *
+ * Runtime-only fields (`target`, `storage`, `onMessage` callbacks) live
+ * alongside at the top level — they're function / DOM types that can't be
+ * serialised on the wire.
+ */
+interface ChatWidgetOptions {
+  /**
+   * Stable identifier for this widget instance. Use when mounting more
+   * than one widget on the same page (different deployments, different
+   * targets). Isolates client-storage namespaces (visitorId, active conversationId,
+   * cached userPrefs). Default: `"default"`.
+   */
+  widgetId?: string;
+  /** Deployment public key (`agent_pk_...`). Sent as `x-public-key` when present. */
+  publicKey?: string;
+  /** Deployment ID (UUID). Required by every public mount and sent as `x-ai-agent-deployment-id`. */
+  aiAgentDeploymentId?: string;
+  /**
+   * MAIN site origin (no trailing slash, e.g. `https://help.ai`). The API
+   * modules derive from it — the production edge mounts the agent API at
+   * `${baseUrl}/api/agent` and the data API at `${baseUrl}/api/data`.
+   * Defaults to the brand's origin.
+   */
+  baseUrl?: string;
+  /**
+   * Agent-API base (no trailing slash) — set it when the
+   * `module-agent-api` service is reached DIRECTLY (a standalone
+   * local module, e.g. `http://localhost:3069`) instead of through the
+   * edge. Routes attach as-is (`${agentApiBaseUrl}/pai/handshake`).
+   * Precedence: this option > derived from the main origin
+   * (`${baseUrl}/api/agent`). Not server-pushable — the handshake already
+   * travelled over it.
+   */
+  agentApiBaseUrl?: string;
+  /**
+   * Data-API base (no trailing slash) — the `module-data-api`
+   * service serving content, form definitions, and form submissions under
+   * `/pai/*` (`content`, `bootstrap`, `submit-form`).
+   * Set it for a standalone local module (e.g. `http://localhost:3071`).
+   * Precedence: this option > server-pushed `config.dataApiBaseUrl` > derived
+   * from the main origin (`${baseUrl}/api/data`, e.g.
+   * `https://help.ai/api/data`).
+   */
+  dataApiBaseUrl?: string;
+  /** Host-asserted, informational end-user context (untrusted; not auth). */
+  userContext?: UserContext;
+  /** Host-asserted, informational page/visit context (untrusted; `area`, url, …). */
+  pageContext?: PageContext;
+  /** HTTP endpoint overrides. */
+  endpoints?: Endpoints;
+  /**
+   * Console log verbosity. `false` / `"off"` silences everything,
+   * `true` → `"debug"`. Levels `error` / `warn` / `info` / `debug` /
+   * `trace` gate output additively. Runtime-toggleable via
+   * `chat.setDebug(level)` or `?<brand>-debug=trace` in the page URL.
+   */
+  debug?: boolean | 'off' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
+  presentation?: PresentationOptions;
+  behavior?: BehaviorOptions;
+  /** Theme preference (`'auto' | 'light' | 'dark'`) or overrides object. */
+  theme?: ThemePreference | ThemeOverrides;
+  launcher?: LauncherOptions;
+  header?: HeaderOptions;
+  composer?: ComposerOptions;
+  feedback?: FeedbackOptions;
+  i18n?: I18nOptions;
+  footer?: FooterOptions;
+  /** Capability flags (file upload, voice mode, HITL, operator request). Server-pushable. */
+  features?: FeatureFlags;
+  /** Event-driven forms (signal capture, CSAT, intake, consent…). Server-pushable. */
+  forms?: FormsOptions;
+  /** Messenger modules (Chat / Home / Messages / Help / News tabs). Server-pushable. */
+  modules?: ModulesOptions;
+  /** Anonymous owner-facing usage tracking (pixel hits). Server-pushable. */
+  tracking?: TrackingOptions;
+  /**
+   * Custom client-side storage adapter. Implements the {@link ClientStorage}
+   * interface (`get` / `set` / `remove` / `clear`).
+   */
+  storage?: ClientStorage;
+  onMessage?: (msg: {
+    role: string;
+    text: string;
+  }) => void;
+  onOpen?: () => void;
+  onClose?: () => void;
+  onError?: (err: unknown) => void;
+}
+/** `true` for any string other than the literal `"false"`. Useful for boolean attrs. */
+declare function boolAttr(v: string): boolean;
+/**
+ * Attributes that don't fit a generic table because their parser
+ * needs custom logic (multi-attr aggregation, empty-string accepted,
+ * etc.). Listed here so they're folded into `REACTIVE_ATTRS` without
+ * a free-floating string literal further down.
+ */
+declare const SPECIAL_REACTIVE_ATTRS: readonly ['launcher-label', 'callout-text', 'callout-delay', 'actions', 'user-context', 'page-context'];
+/**
+ * Every flat-attribute table in this file. Single source of truth —
+ * both the runtime parser and `REACTIVE_ATTRS` derive from this list.
+ */
+declare const ATTR_TABLES: readonly [readonly [["public-key", "publicKey"], ["ai-agent-deployment-id", "aiAgentDeploymentId"], ["base-url", "baseUrl"], ["agent-api-base-url", "agentApiBaseUrl"], ["data-api-base-url", "dataApiBaseUrl"], ["theme", "theme", (v: string) => string]], readonly [["mode", "mode", (v: string) => string], ["position", "position", (v: string) => string], ["iframe", "iframe", typeof boolAttr]], readonly [["width", "width"], ["height", "height"]], readonly [["response-mode", "responseMode", (v: string) => string], ["start-minimized", "startMinimized", typeof boolAttr], ["show-reasoning", "showReasoning", typeof boolAttr], ["show-tool-calls", "showToolCalls", typeof boolAttr], ["show-sources", "showSources", typeof boolAttr], ["disable-message-feedback", "disableMessageFeedback", typeof boolAttr], ["auto-send-suggestions", "autoSendSuggestions", typeof boolAttr], ["pop-out-url", "popOutUrl"]], readonly [["locale", "locale"]], readonly [["launcher-variant", "variant", (v: string) => string], ["launcher-size", "size", (v: string) => string], ["launcher-icon", "icon"], ["launcher-hidden", "hidden", typeof boolAttr]], readonly [["features-disable-file-upload", "disableFileUpload", typeof boolAttr], ["features-voice", "voice", (v: string) => string]], readonly [["endpoint-upload", "upload"], ["endpoint-transcribe", "transcribe"]], readonly [["user-id", "id"], ["user-email", "email"], ["user-name", "name"]], readonly [["page-area", "area"], ["page-url", "url"], ["page-path", "path"], ["page-title", "title"]]];
+/** Every attribute `<web-ai-chat>` reads, as written in HTML — the names its JSX typings offer. */
+type WebAiChatAttributeName = (typeof ATTR_TABLES)[number][number][0] | (typeof SPECIAL_REACTIVE_ATTRS)[number];
+declare const handshakeResponseSchema: z.ZodObject<{
+  deployment: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    slug: z.ZodOptional<z.ZodString>;
+    publicKey: z.ZodOptional<z.ZodString>;
+  }, z.core.$loose>;
+  agent: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+      away: "away";
+      offline: "offline";
+      online: "online";
+    }>>;
+  }, z.core.$loose>;
+  config: z.ZodOptional<z.ZodObject<{
+    presentation: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+      mode: z.ZodDefault<z.ZodEnum<{
+        drawer: "drawer";
+        floating: "floating";
+        inline: "inline";
+        modal: "modal";
+        page: "page";
+        standalone: "standalone";
+      }>>;
+      position: z.ZodDefault<z.ZodEnum<{
+        "bottom-left": "bottom-left";
+        "bottom-right": "bottom-right";
+        "top-left": "top-left";
+        "top-right": "top-right";
+      }>>;
+      iframe: z.ZodDefault<z.ZodBoolean>;
+      size: z.ZodOptional<z.ZodObject<{
+        width: z.ZodOptional<z.ZodString>;
+        height: z.ZodOptional<z.ZodString>;
+        expanded: z.ZodOptional<z.ZodObject<{
+          width: z.ZodOptional<z.ZodString>;
+          height: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        resize: z.ZodOptional<z.ZodObject<{
+          enabled: z.ZodDefault<z.ZodBoolean>;
+          minWidth: z.ZodOptional<z.ZodString>;
+          maxWidth: z.ZodOptional<z.ZodString>;
+          minHeight: z.ZodOptional<z.ZodString>;
+          maxHeight: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        inset: z.ZodOptional<z.ZodString>;
+        initialSize: z.ZodDefault<z.ZodEnum<{
+          auto: "auto";
+          expanded: "expanded";
+          fullscreen: "fullscreen";
+          normal: "normal";
+        }>>;
+        autoSizeBreakpoint: z.ZodDefault<z.ZodNumber>;
+      }, z.core.$loose>>;
+    }, z.core.$loose>>>;
+    behavior: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+      startMinimized: z.ZodDefault<z.ZodBoolean>;
+      responseMode: z.ZodDefault<z.ZodEnum<{
+        buffered: "buffered";
+        streaming: "streaming";
+      }>>;
+      showReasoning: z.ZodDefault<z.ZodBoolean>;
+      showToolCalls: z.ZodDefault<z.ZodBoolean>;
+      showSources: z.ZodDefault<z.ZodBoolean>;
+      disableMessageFeedback: z.ZodDefault<z.ZodBoolean>;
+      autoSendSuggestions: z.ZodDefault<z.ZodBoolean>;
+      popOutUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    theme: z.ZodOptional<z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
+      auto: "auto";
+      dark: "dark";
+      host: "host";
+      light: "light";
+    }>, z.ZodObject<{
+      mode: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        dark: "dark";
+        host: "host";
+        light: "light";
+      }>>;
+      accent: z.ZodOptional<z.ZodString>;
+      accentText: z.ZodOptional<z.ZodString>;
+      radius: z.ZodOptional<z.ZodString>;
+      fontFamily: z.ZodOptional<z.ZodString>;
+      contentMaxWidth: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>]>>>;
+    launcher: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+      variant: z.ZodDefault<z.ZodEnum<{
+        bar: "bar";
+        circle: "circle";
+        minimal: "minimal";
+        pill: "pill";
+      }>>;
+      size: z.ZodDefault<z.ZodEnum<{
+        lg: "lg";
+        md: "md";
+        sm: "sm";
+      }>>;
+      label: z.ZodOptional<z.ZodString>;
+      icon: z.ZodOptional<z.ZodString>;
+      hidden: z.ZodDefault<z.ZodBoolean>;
+      callout: z.ZodOptional<z.ZodObject<{
+        text: z.ZodDefault<z.ZodString>;
+        shape: z.ZodDefault<z.ZodEnum<{
+          bubble: "bubble";
+          callout: "callout";
+          pill: "pill";
+        }>>;
+        position: z.ZodDefault<z.ZodEnum<{
+          auto: "auto";
+          horizontal: "horizontal";
+          vertical: "vertical";
+        }>>;
+        delayMs: z.ZodDefault<z.ZodNumber>;
+        autoDismissMs: z.ZodDefault<z.ZodNumber>;
+        animated: z.ZodDefault<z.ZodBoolean>;
+        persistent: z.ZodDefault<z.ZodBoolean>;
+      }, z.core.$loose>>;
+    }, z.core.$loose>>>;
+    header: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+      actions: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        clear: "clear";
+        close: "close";
+        expand: "expand";
+        fullscreen: "fullscreen";
+        history: "history";
+        language: "language";
+        popOut: "popOut";
+        sound: "sound";
+        textSize: "textSize";
+        theme: "theme";
+      }>>>;
+    }, z.core.$loose>>>;
+    composer: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+      sendButton: z.ZodOptional<z.ZodObject<{
+        shape: z.ZodDefault<z.ZodEnum<{
+          circle: "circle";
+          pill: "pill";
+          square: "square";
+        }>>;
+        icon: z.ZodDefault<z.ZodEnum<{
+          arrowUp: "arrowUp";
+          chevron: "chevron";
+          paperPlane: "paperPlane";
+          send: "send";
+        }>>;
+        variant: z.ZodDefault<z.ZodEnum<{
+          filled: "filled";
+          ghost: "ghost";
+          outline: "outline";
+        }>>;
+      }, z.core.$loose>>;
+      attachments: z.ZodOptional<z.ZodObject<{
+        maxBytes: z.ZodDefault<z.ZodNumber>;
+        maxCount: z.ZodDefault<z.ZodNumber>;
+        accept: z.ZodDefault<z.ZodString>;
+      }, z.core.$loose>>;
+    }, z.core.$loose>>>;
+    feedback: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+      sound: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        volume: z.ZodDefault<z.ZodNumber>;
+        events: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+          error: "error";
+          messageReceived: "messageReceived";
+          messageSent: "messageSent";
+          voiceStart: "voiceStart";
+          voiceStop: "voiceStop";
+        }> & z.core.$partial, z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>>;
+      }, z.core.$loose>>;
+      haptics: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        events: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+          error: "error";
+          messageReceived: "messageReceived";
+          messageSent: "messageSent";
+          voiceStart: "voiceStart";
+          voiceStop: "voiceStop";
+        }> & z.core.$partial, z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodArray<z.ZodNumber>]>>>;
+      }, z.core.$loose>>;
+    }, z.core.$loose>>>;
+    i18n: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+      locale: z.ZodOptional<z.ZodString>;
+      defaultLocale: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodString]>>;
+      availableLocales: z.ZodOptional<z.ZodArray<z.ZodString>>;
+      strings: z.ZodOptional<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodString>, z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>>]>>;
+    }, z.core.$loose>>>;
+    footer: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+      poweredBy: z.ZodOptional<z.ZodObject<{
+        text: z.ZodOptional<z.ZodString>;
+        href: z.ZodOptional<z.ZodURL>;
+        logoUrl: z.ZodOptional<z.ZodURL>;
+      }, z.core.$loose>>;
+      composerDisclaimer: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    features: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+      disableFileUpload: z.ZodDefault<z.ZodBoolean>;
+      voice: z.ZodDefault<z.ZodEnum<{
+        disabled: "disabled";
+        local: "local";
+        server: "server";
+      }>>;
+      disableHumanInLoop: z.ZodDefault<z.ZodBoolean>;
+      enableOperatorRequest: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$loose>>>;
+    modules: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
+      label: z.ZodString;
+      layout: z.ZodEnum<{
+        chat: "chat";
+        help: "help";
+        home: "home";
+        news: "news";
+      }>;
+      contentCollectionIds: z.ZodOptional<z.ZodArray<z.ZodUUID>>;
+      id: z.ZodOptional<z.ZodString>;
+      brandName: z.ZodOptional<z.ZodString>;
+      hideGreeting: z.ZodOptional<z.ZodBoolean>;
+      greetingText: z.ZodOptional<z.ZodString>;
+      userAvatars: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        avatar: z.ZodOptional<z.ZodString>;
+        role: z.ZodOptional<z.ZodString>;
+      }, z.core.$loose>>>;
+      hideSearchBar: z.ZodOptional<z.ZodBoolean>;
+      hideRecentConversations: z.ZodOptional<z.ZodBoolean>;
+      status: z.ZodOptional<z.ZodObject<{
+        text: z.ZodOptional<z.ZodString>;
+        level: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+      }, z.core.$strip>>;
+      contentBlockTitle: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>>;
+    tracking: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+      enabled: z.ZodOptional<z.ZodBoolean>;
+      endpoint: z.ZodOptional<z.ZodURL>;
+      sampleRate: z.ZodOptional<z.ZodNumber>;
+      token: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    dataApiBaseUrl: z.ZodOptional<z.ZodString>;
+    storageVersion: z.ZodOptional<z.ZodString>;
+  }, z.core.$loose>>;
+  site: z.ZodOptional<z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    logo: z.ZodOptional<z.ZodObject<{
+      url: z.ZodString;
+      alt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    logoDark: z.ZodOptional<z.ZodObject<{
+      url: z.ZodString;
+      alt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+  }, z.core.$loose>>;
+  blocks: z.ZodOptional<z.ZodObject<{
+    navigation: z.ZodOptional<z.ZodArray<z.ZodObject<{
+      id: z.ZodOptional<z.ZodString>;
+      label: z.ZodString;
+      href: z.ZodOptional<z.ZodString>;
+      icon: z.ZodOptional<z.ZodString>;
+      description: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    linkCards: z.ZodOptional<z.ZodArray<z.ZodObject<{
+      id: z.ZodOptional<z.ZodString>;
+      label: z.ZodString;
+      href: z.ZodOptional<z.ZodString>;
+      icon: z.ZodOptional<z.ZodString>;
+      description: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+  }, z.core.$loose>>;
+  welcome: z.ZodOptional<z.ZodObject<{
+    messages: z.ZodOptional<z.ZodArray<z.ZodObject<{
+      id: z.ZodString;
+      role: z.ZodEnum<{
+        assistant: "assistant";
+        system: "system";
+      }>;
+      text: z.ZodString;
+    }, z.core.$loose>>>;
+    suggestions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+      id: z.ZodString;
+      label: z.ZodString;
+      text: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+  }, z.core.$loose>>;
+  visitorId: z.ZodString;
+  conversationId: z.ZodString;
+  userPrefs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  rebind: z.ZodOptional<z.ZodObject<{
+    conversationId: z.ZodString;
+  }, z.core.$strict>>;
+}, z.core.$loose>;
+type HandshakeResponse = z.infer<typeof handshakeResponseSchema>;
+/** A 👍/👎 reaction on a rateable (assistant/operator) message; `null` clears a prior choice. */
+type FeedbackValue = 'up' | 'down' | null;
+/**
+ * Payload shape per event. Keyed by event name; use `void` for events that
+ * carry no data.
+ *
+ * **Every user-visible action fires here.** Subscribe via
+ * `chat.on("eventName", fn)` to add analytics, side effects, or audit
+ * trails without forking the widget. The same names also stream to the
+ * structured logger at `info` level when `debug` is enabled.
+ */
+interface EventMap {
+  /** Panel opened (floating / modal / drawer). */
+  open: void;
+  /** Panel closed. */
+  close: void;
+  /** Expanded mode toggled (1.5× size). Payload is the new state. */
+  expand: boolean;
+  /** Fullscreen mode toggled. Payload is the new state. */
+  fullscreen: boolean;
+  /** End-user dragged the resize grip — payload is the resolved size. */
+  resize: {
+    width: number;
+    height: number;
+  };
+  /** A message was exchanged. Fires for user, assistant, and operator messages. */
+  message: {
+    role: string;
+    text: string;
+  };
+  /** User submitted a message (fires before the request is sent). */
+  send: {
+    text: string;
+    attachmentCount: number;
+  };
+  /** User cancelled an in-flight stream. */
+  stop: void;
+  /** Clear / new-conversation requested. */
+  clear: void;
+  /** User picked a chat from the history pane / sidebar. */
+  selectConversation: {
+    conversationId: string;
+  };
+  /** User clicked a suggested-message chip. */
+  suggestion: {
+    text: string;
+  };
+  /** History pane toggled. Payload is the resulting view. */
+  toggleHistory: {
+    view: 'chat' | 'history';
+  };
+  /** A form (intake, CSAT, …) was completed or skipped. */
+  formSubmit: {
+    formId: string;
+    values: Record<string, string>;
+    skipped: boolean;
+  };
+  /** User answered an ask-questions tool request (re-POST follows). */
+  toolResult: {
+    toolCallId: string;
+  };
+  /** User approved / rejected a gated tool call (re-POST follows). */
+  toolDecision: {
+    toolCallId: string;
+    approved: boolean;
+  };
+  /**
+   * User gave feedback on a rateable reply (AI or operator). `value` is `"up"` / `"down"`, or
+   * `null` when they cleared a prior choice. `messageId` is the backend message
+   * id. Also POSTed best-effort to `/pai/message-feedback`; a host listener can
+   * mirror it to analytics.
+   */
+  messageFeedback: {
+    messageId: string;
+    value: FeedbackValue;
+  };
+  /** A content list (news / help / home block) rendered. */
+  contentView: {
+    section: string;
+    count: number;
+  };
+  /** An article / content item was opened — with the collection it belongs to. */
+  contentOpen: {
+    contentId: string;
+    contentCollectionId: string;
+  };
+  /** The help search ran. Length + hit count only — never the query text. */
+  contentSearch: {
+    queryLength: number;
+    hitCount: number;
+  };
+  /** An opened article was read (dwell threshold passed). Fires once per open. */
+  contentRead: {
+    contentId: string;
+  };
+  /** A link inside an opened article was followed. */
+  contentLinkClick: {
+    contentId: string;
+  };
+  /** Files attached (drag-drop, file picker, paste). */
+  attach: {
+    count: number;
+    totalBytes: number;
+  };
+  /** An attachment was removed before send. */
+  removeAttachment: {
+    id: string;
+  };
+  /** Voice recording started. */
+  voiceStart: void;
+  /** Voice recording stopped and was sent for transcription. */
+  voiceStop: {
+    durationMs: number;
+  };
+  /** Voice recording cancelled (e.g. user released outside the button). */
+  voiceCancel: void;
+  /** End-user picked a different UI locale. Payload is the new BCP-47 tag. */
+  localeChange: string;
+  /** End-user picked a different theme mode (`auto` / `light` / `dark`). */
+  themeChange: ThemePreference;
+  /** End-user picked a different text size (`small` / `normal` / `large`). */
+  textSizeChange: TextSize;
+  /** End-user toggled the global sound mute. */
+  soundToggle: {
+    muted: boolean;
+  };
+  /** Page-mode sidebar collapsed / expanded. */
+  sidebarToggle: {
+    collapsed: boolean;
+  };
+  /** Pre-engagement launcher callout dismissed. */
+  calloutDismiss: void;
+  /** An unhandled error occurred somewhere in the transport or UI. */
+  error: unknown;
+  /** Connect bootstrap succeeded. Payload is the typed server response. */
+  handshake: HandshakeResponse;
+  /** Server replaced the requested conversationId and the widget adopted it. */
+  conversationRebound: {
+    previous: string;
+    current: string;
+  };
+  /** The widget's state changed — open, ready, unread or the conversation. Payload is the whole new state. */
+  state: WidgetState;
+  /** How many conversations have replies the visitor hasn't read changed. Payload is the new count. */
+  unread: number;
+}
+/** What a page can read about the widget at any moment (`chat.state`), and the `state` event's payload. */
+interface WidgetState {
+  /** The panel is showing. Always `true` for `inline`, `page` and `standalone`. */
+  open: boolean;
+  /** The widget has connected (its first handshake settled) and takes commands right away. */
+  ready: boolean;
+  /**
+   * Conversations with replies the visitor hasn't read. Known once the widget has been opened in this page load
+   * (a closed widget makes no requests beyond the handshake), and kept live from then on.
+   */
+  unread: number;
+  /** The visitor's current conversation, once there is one. */
+  conversationId?: string;
+}
+type EventName = keyof EventMap;
+/**
+ * Host-element command bus.
+ *
+ * The programmatic API (`chat.open()`, `.close()`, `.ask()`, …) and the
+ * `<web-ai-chat>` element's methods dispatch `CustomEvent`s on the shadow
+ * host element. The App listens for those same events and routes them to
+ * its state handlers. That keeps the two modules decoupled — `index.ts`
+ * doesn't hold a ref to App state, App doesn't know about the public
+ * instance handle.
+ *
+ * This module is the single source of truth for the event names + the
+ * tiny helpers on both sides of the bridge.
+ */
+/** Where `open()` lands: a tab, and in Help or News optionally one article or post (its content id). */
+interface OpenTarget {
+  to: 'home' | 'chats' | 'help' | 'news';
+  id?: string;
+}
+/** How `ask(text, options)` lands: in the composer for the visitor to send (default), or sent right away. */
+interface AskOptions {
+  /** Send the text as the visitor's message instead of filling the composer with it. Default `false`. */
+  send?: boolean;
+}
+/**
+ * Comprehensive logger for the widget runtime.
+ *
+ * Designed for "I have a customer reporting a weird bug on their
+ * site, I want every relevant detail without rebuilding" debugging:
+ *
+ *   • Five levels (off / error / warn / info / debug / trace) that
+ *     gate output. Default `warn` — errors + warnings always go
+ *     through, info / debug / trace stay silent until opted in.
+ *   • Scoped child loggers — `logger.scope("transport")` returns a
+ *     logger that tags every line `[helpai:transport] …`. Every
+ *     subsystem has its own scope so the console transcript reads
+ *     like a flight recorder.
+ *   • Structured payloads — every call accepts an object as the
+ *     second arg; the browser console renders it inline, expandable.
+ *   • Remote toggle — `chat.setDebug("trace")`, `HelpAI.setDebug(…)`,
+ *     `?helpai-debug=trace`, or the `options.debug` mount param all
+ *     converge on the same internal level. Persisted to
+ *     `localStorage["helpai.debug"]` so a refresh keeps visibility.
+ *   • Co-hosted safety — every signal (query, global key, log tag) is
+ *     brand-prefixed so two widgets on the same page don't fight over
+ *     flags or pollute each other's transcripts.
+ */
+type LogLevel = 'off' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
+/** One structured line, as forwarded to an external {@link setLogSink} sink. */
+interface LogEntry {
+  level: LogLevel;
+  /** Subsystem tag, e.g. `"transport"` or `"core:hooks"`. */
+  scope: string;
+  message: string;
+  payload?: unknown;
+}
+/**
+ * Handle returned by {@link mount} / {@link init}. All methods are safe to call
+ * after `destroy()` — they become no-ops rather than throwing.
+ */
+interface ChatWidgetInstance {
+  /** Stable identifier — matches `options.widgetId ?? "default"`. */
+  readonly widgetId: string;
+  /**
+   * Open the floating panel (no-op in `inline` / `standalone` mode). With a target it also shows that tab at its
+   * root, or one Help article / News post in it by content id — for a site's own "Help" or "What's new" button. A
+   * tab the widget doesn't have just opens the panel.
+   *
+   * @example
+   * ```ts
+   * chat.open({ to: 'news' });
+   * chat.open({ to: 'help', id: '019a0b6c-7e2a-7000-9d3e-4a5b6c7d8e01' });
+   * ```
+   */
+  open: (target?: OpenTarget) => void;
+  /** Close the floating panel (no-op in `inline` / `standalone` mode). */
+  close: () => void;
+  /** Unmount the widget and release all subscriptions. */
+  destroy: () => void;
+  /** Toggle fullscreen mode. In `standalone` mode this is a no-op. */
+  expand: () => void;
+  /**
+   * Surface a configured form by id (a form with a `manual` trigger). Lets the
+   * host open, say, an appointment or feedback form from its own button. No-op
+   * if no form with that id + a `manual` trigger exists.
+   */
+  openForm: (id: string) => void;
+  /**
+   * Open the chat with `text` in the composer, ready for the visitor to edit and send — for a site's own "Ask about
+   * pricing" button. With `{ send: true }` it goes out as the visitor's message instead. Either way it waits until
+   * the chat can take it (still connecting, a pre-chat form to answer; a send also waits for a reply still arriving).
+   *
+   * @example
+   * ```ts
+   * chat.ask('How do I book a session?'); // open the chat with the question in the composer
+   * chat.ask('How do I book a session?', { send: true }); // open the chat and send it
+   * ```
+   */
+  ask: (text: string, options?: AskOptions) => void;
+  /**
+   * The widget's state right now: `open`, `ready`, `unread` (conversations with unread replies) and the current
+   * `conversationId`. The `state` event delivers each change; `unread` fires when the count changes.
+   *
+   * @example
+   * ```ts
+   * helpLink.dataset.unread = String(chat.state.unread);
+   * chat.on('unread', (count) => (helpLink.dataset.unread = String(count)));
+   * ```
+   */
+  readonly state: WidgetState;
+  /** Resolves once the widget has connected; commands sent after it act at once. Resolves once, never rejects. */
+  readonly ready: Promise<void>;
+  /**
+   * Start over as a new anonymous visitor — call it when your user logs out. Forgets the stored visitor, their current
+   * conversation, preferences and the user context set with `setUserContext`, then reconnects as a first visit.
+   * Listeners added with `on()` stay.
+   */
+  reset: () => void;
+  /**
+   * Subscribe to a lifecycle event. Returns an `off` function. See
+   * {@link EventMap} for the full set + payload shapes — currently
+   * `open | close | message | error | expand | fullscreen |
+   * handshake | localeChange`.
+   */
+  on: <E extends EventName>(name: E, fn: (payload: EventMap[E]) => void) => () => void;
+  /**
+   * Merge new options into the running instance without a full remount.
+   * Useful for theme toggles or other live config tweaks.
+   */
+  update: (patch: Partial<ChatWidgetOptions>) => void;
+  /**
+   * Set / merge the host-asserted end-user context (`id`, `email`, `name`, plus
+   * any custom scalar fields). Informational only — not auth. Merges into the
+   * current context, refreshes the Home greeting, and re-handshakes so the
+   * agent gets it. Call this after the visitor logs in. Untrusted input is
+   * sanitised; bad fields are dropped with a `warn`.
+   *
+   * @example
+   * ```ts
+   * getInstance().setUserContext({ id: "u_1", name: "Mohamed", email: "mo@acme.com", plan: "pro" });
+   * ```
+   */
+  setUserContext: (userContext: UserContext) => void;
+  /** Clear the end-user context (e.g. on logout) and re-handshake anonymously. */
+  clearUserContext: () => void;
+  /**
+   * Set / merge the host-asserted page/visit context (`area`, `url`, `path`,
+   * `title`, plus custom scalar fields). Use it to tell the agent which surface
+   * the visitor is on (e.g. `area: "pricing"`) and update it on SPA navigation.
+   * Merges into the current context and re-handshakes.
+   *
+   * @example
+   * ```ts
+   * getInstance().setPageContext({ area: "pricing", path: "/pricing/enterprise" });
+   * ```
+   */
+  setPageContext: (pageContext: PageContext) => void;
+  /** Clear the page/visit context and re-handshake. */
+  clearPageContext: () => void;
+  /**
+   * Set the runtime log level. Accepts `"off"` / `"error"` / `"warn"` /
+   * `"info"` / `"debug"` / `"trace"`, or `true` (→ `"debug"`) /
+   * `false` (→ `"off"`), or a number 0..5. Persists to localStorage so
+   * a page refresh keeps the same verbosity — useful for asking a
+   * customer to reproduce a bug and capture the console transcript.
+   *
+   * Affects every widget on the page (logger is module-global; setting
+   * it from one instance applies everywhere). Equivalent to calling
+   * `HelpAI.setDebug(level)` on the brand global.
+   */
+  setDebug: (level: boolean | number | string) => void;
+  /** Current log level. Read-only. */
+  readonly debugLevel: () => LogLevel;
+  /**
+   * Forward every log line (that passes the active level) to an external sink —
+   * pipe errors/warnings/debug into Sentry, Datadog, your own logger, etc. Pass
+   * `null` to clear. One global sink per bundle (logger is module-global); use
+   * `setDebug("trace")` to capture everything, not just warnings + errors.
+   */
+  onLog: (sink: ((entry: LogEntry) => void) | null) => void;
+}
+/** The attributes a page sets on `<web-ai-chat>`, as HTML strings; `ai-agent-deployment-id` is required. */
+export type WebAiChatAttributes = Partial<Record<WebAiChatAttributeName, string>> & {
+  'ai-agent-deployment-id': string;
+};
+/** A page's `<web-ai-chat>`: the same commands, state and events as the `mount()` handle. */
+export type WebAiChatElement = HTMLElement & Pick<ChatWidgetInstance, 'open' | 'close' | 'expand' | 'openForm' | 'ask' | 'on' | 'state' | 'ready' | 'reset'>;
+declare global {
+  interface HTMLElementTagNameMap {
+    'web-ai-chat': WebAiChatElement;
+  }
+}
 export declare function registerWebComponent(): void;
+export {};