@helpai/elements 0.72.1 → 1.1.0

package/index.d.ts

@@ -32,8 +32,8 @@ interface ClientStorage {
  *
  * 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({ strings })`) or the
- * SaaS backend in the `connect` response — both pushed *partially*: only the keys
+ * 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**
@@ -41,7 +41,7 @@ interface ClientStorage {
  * 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" | "attach" | "micStart" | "micStop" | "micUnsupported" | "expand" | "collapse" | "fullscreen" | "exitFullscreen" | "resizeHandle" | "scrollToBottom" | "close" | "moreActions" | "soundOn" | "soundOff" | "language" | "theme" | "themeAuto" | "themeLight" | "themeDark" | "textSize" | "textSizeSmall" | "textSizeNormal" | "textSizeLarge" | "history" | "historyTitle" | "historyEmpty" | "historyLoading" | "historyBack" | "historyContinue" | "conversationLoading" | "conversationClosed" | "startNewConversation" | "talkToOperator" | "connectingOperator" | "noOperatorAvailable" | "chattingWithOperator" | "cancelOperatorRequest" | "dateToday" | "dateYesterday" | "dateLastWeek" | "dateOlder" | "newConversation" | "dropZone" | "attachmentTooLarge" | "attachmentTooMany" | "attachmentMimeRejected" | "errorRetry" | "errorGeneric" | "errorRateLimited" | "loading" | "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" | "homeGreeting" | "homeGreetingNamed" | "homeGreetingLead" | "homeSearchPlaceholder" | "homeContentTitle" | "homeStatus" | "helpTitle" | "helpSearchPlaceholder" | "helpEmpty" | "helpLoading" | "helpSearchEmpty" | "newsTitle" | "newsEmpty" | "newsLoading" | "newsBack" | "newsPublishedAt";
+type StringKey = "launcherOpen" | "launcherLabel" | "panelTitle" | "composerPlaceholder" | "send" | "stop" | "attach" | "micStart" | "micStop" | "micUnsupported" | "expand" | "collapse" | "fullscreen" | "exitFullscreen" | "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" | "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" | "homeGreeting" | "homeGreetingNamed" | "homeGreetingLead" | "homeSearchPlaceholder" | "homeContentTitle" | "homeStatus" | "helpTitle" | "helpSearchPlaceholder" | "helpEmpty" | "helpLoading" | "helpSearchEmpty" | "newsTitle" | "newsEmpty" | "newsLoading" | "newsBack" | "newsPublishedAt";
 /** A partial map for one locale — what overrides look like on the wire. */
 type LocaleStrings = Partial<Record<StringKey, string>>;
 /**
@@ -50,8 +50,8 @@ type LocaleStrings = Partial<Record<StringKey, string>>;
  */
 type Strings = Record<StringKey, string>;
 /**
- * Override shape accepted by both `init({ strings })` and the server's
- * `settings.strings`. Two forms supported:
+ * 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.
@@ -66,161 +66,6 @@ type Strings = Record<StringKey, string>;
  */
 type StringsOverride = LocaleStrings | Partial<Record<string, LocaleStrings>>;
 //#endregion
-//#region src/core/persistence.d.ts
-/** Drag-resized panel dimensions. Persisted only when resize is enabled. */
-interface WidgetSize {
-  width: number;
-  height: number;
-}
-/**
- * User-changeable preferences. Sent to the backend on every request as a
- * `userPrefs` field so the server can detect drift (e.g. user changed
- * locale on another tab) and reconcile.
- *
- * Every field is optional — an unset key inherits the server / page-owner
- * default. Empty object `{}` means "no preference recorded yet."
- */
-interface UserPrefs {
-  /** BCP-47 tag picked from the language switcher. */
-  locale?: string;
-  /** Drag-resized panel dimensions. */
-  widgetSize?: WidgetSize;
-  /** Sound on/off toggle (icon button). */
-  soundMuted?: boolean;
-  /** Theme picked from the theme switcher. */
-  themeMode?: "auto" | "light" | "dark";
-  /** Text size picked from the text-size switcher. */
-  textSize?: "small" | "normal" | "large";
-}
-//#endregion
-//#region src/stream/types.d.ts
-/** A 👍/👎 reaction on a rateable (assistant/operator) message; `null` clears a prior choice. */
-type FeedbackValue = "up" | "down" | null;
-//#endregion
-//#region src/stream/protocol.d.ts
-/** A tool reference on the wire: `{ code, config }`. `config` is opaque. */
-interface ToolRef {
-  code: string;
-  config?: Record<string, unknown>;
-}
-/**
- * Who is driving replies in a conversation — the widget mirrors the backend `controlMode`.
- *   - `ai-agent`: the AI agent answers (normal operation).
- *   - `awaiting_operator`: operator-control requested, the AI no longer answers — the turn routes to the
- *      operator — while waiting in the operator queue.
- *   - `operator`: a workspace operator took over and is replying.
- *
- * Carried on `HandshakeResponse.controlState`, `LoadConversationResponse.controlState` (resume +
- * history-switch), and the `data-control-state` stream part (on the reply stream). Absent / unknown →
- * treated as `"ai-agent"`.
- */
-type ControlMode = "ai-agent" | "awaiting_operator" | "operator";
-/**
- * The control-state snapshot the widget reads to render composer/typing/banner state. The optional
- * `operatorAvailable` (set on the operator-request response + the awaiting terminal part) tells the
- * widget whether to show "connecting…" or the async-capture ("leave your details") copy.
- */
-interface ControlState {
-  controlMode: ControlMode;
-  /**
-   * The operator's 2-letter initials (operator mode only) — shown in the bubble chrome + banner. The
-   * visitor never sees the full name (privacy); the backend derives the initials. `assignedOperatorId`
-   * also rides the wire but the widget doesn't render it, so it isn't modeled here.
-   */
-  assignedOperatorInitials?: string;
-  /** Whether anyone was in the operator pool when operator-control was requested (awaiting mode advisory). */
-  operatorAvailable?: boolean;
-}
-/** One-shot bot persona shown in the panel header. */
-interface ConversationAgent {
-  name: string;
-  /** Image URL or data URI. When omitted, initials render from `name`. */
-  avatar?: string;
-  /** Subtitle ("AI Assistant", "Support team", …). */
-  title?: string;
-  /** Presence indicator. Default: `'online'`. */
-  status?: "online" | "away" | "offline";
-}
-/** A clickable quick-reply chip. */
-interface ConversationSuggestion {
-  id: string;
-  /** What the chip displays. */
-  label: string;
-  /** What actually gets sent when clicked. Defaults to `label`. */
-  text?: string;
-}
-/** Welcome payload pushed into the message list on first open. */
-interface ConversationWelcome {
-  messages?: Array<{
-    id: string;
-    role: "assistant" | "system";
-    text: string;
-  }>;
-  suggestions?: ConversationSuggestion[];
-}
-/**
- * Response from `POST /pai/handshake` — the widget's one mount-time
- * round-trip. Deliberately LIGHT: identity + deployment surface only
- * (config, agent persona, welcome, page-mode site/blocks, userPrefs).
- * The conversation THREAD is a separate, lazily-fetched read
- * (`GET /conversation`) that only runs once the widget is activated
- * (opened) — a closed launcher costs the page exactly one request.
- *
- * The `userPrefs` field (when present) is the server's authoritative
- * copy of per-visitor preferences — the client should adopt it and update
- * its local cache. Lets a user picking French on their phone see the
- * widget in French when they open it on their laptop (assuming the same
- * `visitorId`, e.g. via authenticated conversation — out of scope for v1).
- */
-interface HandshakeResponse$1 {
-  /**
-   * Public runtime conversation id. The widget mints this UUIDv7 and the backend
-   * validates that it belongs to the public deployment + visitor.
-   */
-  conversationId: string;
-  visitorId?: string;
-  /** Bot persona in the panel header (name, avatar, status). */
-  agent?: ConversationAgent;
-  /** Initial assistant messages + quick-reply chips. */
-  welcome?: ConversationWelcome;
-  /**
-   * Deployment-wide widget configuration the dashboard admin saved
-   * (mode / theme / launcher / actions / composer / features / …).
-   * Client adopts as defaults; customer's `init({...})` still wins
-   * per-field. Same for every visitor of this deployment.
-   */
-  config?: ServerConfig$1;
-  /** Page-mode site config (logo, title). Backend ships it whenever the deployment renders the page-shell sidebar. */
-  site?: Record<string, unknown>;
-  /** Page-mode sidebar blocks (navigation, link cards). Backend ships it whenever the deployment renders the page-shell sidebar. */
-  blocks?: Record<string, unknown>;
-  /** Current control state — seeds the composer/typing/banner state on connect. Absent → `ai-agent`. */
-  controlState?: ControlState;
-  /**
-   * Server's authoritative copy of the visitor's preferences. When present,
-   * client adopts it (overrides local cache) and re-applies it to the UI
-   * (locale, panel size, sound mute). Absent → client keeps its cache.
-   */
-  userPrefs?: UserPrefs;
-  /**
-   * Optional rebind metadata. When the server returns a `visitorId` /
-   * `conversationId` different from what the client sent, this block tells
-   * the client WHY — useful for telemetry and the `visitorRebound` /
-   * `conversationRebound` events fired into the host page. Server is free to
-   * omit it: the client detects rebinding by comparing request vs
-   * response ids regardless.
-   *
-   * Common reasons: `"conflict"` (the id collided with an existing
-   * record), `"expired"` (the id is too old to be re-used), `"invalid"`
-   * (malformed / not a UUIDv7). Custom strings are passed through to
-   * listeners verbatim.
-   */
-  rebind?: {
-    visitorId?: string;
-    conversationId?: string;
-  };
-}
-//#endregion
 //#region src/core/config/types/common.d.ts
 /**
  * Primitive type aliases shared across every config section. Kept in
@@ -290,6 +135,11 @@ type ActionName = "clear" | "expand" | "fullscreen" | "sound" | "history" | "lan
 type ActionList = ActionName[];
 //#endregion
 //#region src/core/config/types/composer.d.ts
+/**
+ * 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.
  *
@@ -304,12 +154,6 @@ type VoiceMode = "local" | "server" | "disabled";
 interface FeatureFlags {
   /** Voice input behaviour (see {@link VoiceMode}). Default: `'local'`. */
   voice?: VoiceMode;
-  /**
-   * Backend tools the assistant may invoke. Accepts either a bare tool code
-   * (`"tool:send-money"`) or a rich ref (`{ code, config }`) — the wire
-   * format always uses the rich shape.
-   */
-  tools?: Array<string | ToolRef>;
   /**
    * 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`
@@ -337,7 +181,6 @@ interface ResolvedFeatures {
   voice: VoiceMode;
   humanInLoop: boolean;
   operatorRequest: boolean;
-  tools?: Array<string | ToolRef>;
 }
 /**
  * Client-side attachment limits. Server enforcement is still required —
@@ -371,7 +214,7 @@ interface ComposerOptions {
 //#endregion
 //#region src/core/config/types/feedback.d.ts
 /**
- * Audible + tactile feedback knobs. Both default to enabled (browser
+ * Audible + tactile feedback knobs. Both channels default to enabled (browser
  * autoplay policy still gates audio playback).
  */
 /** Lifecycle events the feedback bus can react to. */
@@ -385,7 +228,7 @@ type FeedbackEvent = "messageReceived" | "messageSent" | "error" | "voiceStart"
  */
 type SoundEventValue = boolean | string;
 interface SoundOptions {
-  /** Master on/off. Default: `false` (opt-in). */
+  /** Master on/off. Default: `true` (browser autoplay policy still applies). */
   enabled?: boolean;
   /** Global volume 0..1. Default: `0.3` (subtle). */
   volume?: number;
@@ -410,7 +253,7 @@ interface HapticsOptions {
   events?: Partial<Record<FeedbackEvent, HapticEventValue>>;
 }
 /**
- * Section: audible + tactile feedback. Both default to enabled
+ * Section: audible + tactile feedback. Both channels default to enabled
  * (browser autoplay policy still gates audio playback).
  */
 interface FeedbackOptions {
@@ -1006,9 +849,11 @@ interface Endpoints {
  * use the widget: events, pages, devices, locales, funnels.
  *
  * Privacy contract (enforced in `src/core/tracking.ts`):
- *   - never sends message text, form values, or any user content —
+ *   - never sends message text or form values —
  *     event payloads pass through a static per-event allowlist;
- *   - the only identifier is the widget's existing anonymous `visitorId`;
+ *   - 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
@@ -1028,8 +873,9 @@ interface TrackingOptions {
    */
   endpoint?: string;
   /**
-   * Per-visitor sampling 0..1. `0.25` tracks ~a quarter of visitors
-   * (decided once per page load, so funnels stay intact). Default `1`.
+   * 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;
   /**
@@ -1061,7 +907,8 @@ interface ResolvedTracking {
  *     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`, `welcome`, `feedback`, `i18n`, `footer`, `features`.
+ *     `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
@@ -1129,7 +976,7 @@ interface ChatWidgetOptions {
   feedback?: FeedbackOptions;
   i18n?: I18nOptions;
   footer?: FooterOptions;
-  /** Capability flags (file upload, voice mode, tools). Server-pushable. */
+  /** 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;
@@ -1256,7 +1103,7 @@ interface ResolvedOptions {
   onError?: ChatWidgetOptions["onError"];
 }
 /**
- * Shape of the server-pushed `widget` object in `HandshakeResponse`.
+ * Shape of the server-pushed `config` object in `HandshakeResponse`.
  *
  * Matches a subset of {@link ChatWidgetOptions} — anything the server can
  * reasonably dictate (UI, behaviour, routing). Callbacks (`onMessage` etc.)
@@ -1326,6 +1173,158 @@ interface LogEntry {
   payload?: unknown;
 }
 //#endregion
+//#region src/core/persistence.d.ts
+/** Drag-resized panel dimensions. Persisted only when resize is enabled. */
+interface WidgetSize {
+  width: number;
+  height: number;
+}
+/**
+ * User-changeable preferences. Sent to the backend on every request as a
+ * `userPrefs` field so the server can detect drift (e.g. user changed
+ * locale on another tab) and reconcile.
+ *
+ * Every field is optional — an unset key inherits the server / page-owner
+ * default. Empty object `{}` means "no preference recorded yet."
+ */
+interface UserPrefs {
+  /** BCP-47 tag picked from the language switcher. */
+  locale?: string;
+  /** Drag-resized panel dimensions. */
+  widgetSize?: WidgetSize;
+  /** Sound on/off toggle (icon button). */
+  soundMuted?: boolean;
+  /** Theme picked from the theme switcher. */
+  themeMode?: "auto" | "light" | "dark";
+  /** Text size picked from the text-size switcher. */
+  textSize?: "small" | "normal" | "large";
+}
+//#endregion
+//#region src/stream/types.d.ts
+/** A 👍/👎 reaction on a rateable (assistant/operator) message; `null` clears a prior choice. */
+type FeedbackValue = "up" | "down" | null;
+//#endregion
+//#region src/stream/protocol.d.ts
+/**
+ * Who is driving replies in a conversation — the widget mirrors the backend `controlMode`.
+ *   - `ai-agent`: the AI agent answers (normal operation).
+ *   - `awaiting_operator`: operator-control requested, the AI no longer answers — the turn routes to the
+ *      operator — while waiting in the operator queue.
+ *   - `operator`: a workspace operator took over and is replying.
+ *
+ * Carried on `HandshakeResponse.controlState`, `LoadConversationResponse.controlState` (resume +
+ * history-switch), and the `data-control-state` stream part (on the reply stream). Absent / unknown →
+ * treated as `"ai-agent"`.
+ */
+type ControlMode = "ai-agent" | "awaiting_operator" | "operator";
+/**
+ * The control-state snapshot the widget reads to render composer/typing/banner state. The optional
+ * `operatorAvailable` (set on the operator-request response + the awaiting terminal part) tells the
+ * widget whether to show "connecting…" or the async-capture ("leave your details") copy.
+ */
+interface ControlState {
+  controlMode: ControlMode;
+  /** Monotonic state version: orders received snapshots and fences request/cancel retries to their observed cycle. */
+  controlRevision?: number;
+  /**
+   * The operator's 2-letter initials (operator mode only) — shown in the bubble chrome + banner. The
+   * visitor never sees the full name (privacy); the backend derives the initials. `assignedOperatorId`
+   * also rides the wire but the widget doesn't render it, so it isn't modeled here.
+   */
+  assignedOperatorInitials?: string;
+  /** Whether anyone was in the operator pool when operator-control was requested (awaiting mode advisory). */
+  operatorAvailable?: boolean;
+}
+/** One-shot bot persona shown in the panel header. */
+interface ConversationAgent {
+  name: string;
+  /** Image URL or data URI. When omitted, initials render from `name`. */
+  avatar?: string;
+  /** Subtitle ("AI Assistant", "Support team", …). */
+  title?: string;
+  /** Presence indicator. Default: `'online'`. */
+  status?: "online" | "away" | "offline";
+}
+/** A clickable quick-reply chip. */
+interface ConversationSuggestion {
+  id: string;
+  /** What the chip displays. */
+  label: string;
+  /** What actually gets sent when clicked. Defaults to `label`. */
+  text?: string;
+}
+/** Welcome payload pushed into the message list on first open. */
+interface ConversationWelcome {
+  messages?: Array<{
+    id: string;
+    role: "assistant" | "system";
+    text: string;
+  }>;
+  suggestions?: ConversationSuggestion[];
+}
+/**
+ * Response from `POST /pai/handshake` — the widget's one mount-time
+ * round-trip. Deliberately LIGHT: identity + deployment surface only
+ * (config, agent persona, welcome, page-mode site/blocks, userPrefs).
+ * The conversation THREAD is a separate, lazily-fetched read
+ * (`GET /conversation`) that only runs once the widget is activated
+ * (opened) — a closed launcher costs the page exactly one request.
+ *
+ * The `userPrefs` field (when present) is the server's authoritative
+ * copy of per-visitor preferences — the client should adopt it and update
+ * its local cache. Lets a user picking French on their phone see the
+ * widget in French when they open it on their laptop (assuming the same
+ * `visitorId`, e.g. via authenticated conversation — out of scope for v1).
+ */
+interface HandshakeResponse$1 {
+  /**
+   * Public runtime conversation id. The widget mints this UUIDv7 and the backend
+   * validates that it belongs to the public deployment + visitor.
+   */
+  conversationId: string;
+  visitorId?: string;
+  /** Bot persona in the panel header (name, avatar, status). */
+  agent?: ConversationAgent;
+  /** Initial assistant messages + quick-reply chips. */
+  welcome?: ConversationWelcome;
+  /**
+   * Deployment-wide widget configuration the dashboard admin saved
+   * (mode / theme / launcher / actions / composer / features / …).
+   * Client adopts as defaults; customer's `init({...})` still wins
+   * per-field. Same for every visitor of this deployment.
+   */
+  config?: ServerConfig$1;
+  /** Page-mode site config (logo, title). Backend ships it whenever the deployment renders the page-shell sidebar. */
+  site?: Record<string, unknown>;
+  /** Page-mode sidebar blocks (navigation, link cards). Backend ships it whenever the deployment renders the page-shell sidebar. */
+  blocks?: Record<string, unknown>;
+  /** Current control state — seeds the composer/typing/banner state on connect. Absent → `ai-agent`. */
+  controlState?: ControlState;
+  /**
+   * Server's authoritative copy of the visitor's preferences. When present,
+   * client adopts it (overrides local cache) and re-applies it to the UI
+   * (locale, panel size, sound mute). Absent → client keeps its cache.
+   */
+  userPrefs?: UserPrefs;
+  /**
+   * Optional rebind metadata. When the server returns a `visitorId` /
+   * `conversationId` different from what the client sent, this block tells
+   * the client WHY — useful for telemetry and the `visitorRebound` /
+   * `conversationRebound` events fired into the host page. Server is free to
+   * omit it: the client detects rebinding by comparing request vs
+   * response ids regardless.
+   *
+   * Common reasons: `"conflict"` (the id collided with an existing
+   * record), `"expired"` (the id is too old to be re-used), `"invalid"`
+   * (malformed / not a UUIDv7). Custom strings are passed through to
+   * listeners verbatim.
+   */
+  rebind?: {
+    visitorId?: string;
+    conversationId?: string;
+  };
+}
+//#endregion
 //#region src/core/events.d.ts
 /**
  * Payload shape per event. Keyed by event name; use `void` for events that
@@ -1779,10 +1778,6 @@ declare const widgetSettingsSchema: z.ZodObject<{
       server: "server";
       disabled: "disabled";
     }>>;
-    tools: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-      code: z.ZodString;
-      config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    }, z.core.$loose>]>>>;
     disableHumanInLoop: z.ZodDefault<z.ZodBoolean>;
     enableOperatorRequest: z.ZodDefault<z.ZodBoolean>;
   }, z.core.$loose>>;
@@ -1899,10 +1894,10 @@ declare const widgetSettingsSchema: z.ZodObject<{
 }, z.core.$loose>;
 type WidgetSettings = z.infer<typeof widgetSettingsSchema>;
 /**
- * Full client widget config — connection + widget settings + page-mode
- * extras. The dashboard / dev configurator typically only edits one
- * of the two halves at a time (`widgetSettingsSchema` for the dashboard
- * surface, `connectionConfigSchema` for the developer-facing fields).
+ * Full tooling schema — connection + widget settings + page-mode
+ * handshake extras. The dashboard / dev configurator typically only
+ * edits one part at a time (`widgetSettingsSchema` for the dashboard
+ * surface, `connectionConfigSchema` for developer-facing fields).
  */
 declare const widgetConfigSchema: z.ZodObject<{
   widgetId: z.ZodDefault<z.ZodString>;
@@ -2118,10 +2113,6 @@ declare const widgetConfigSchema: z.ZodObject<{
       server: "server";
       disabled: "disabled";
     }>>;
-    tools: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-      code: z.ZodString;
-      config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    }, z.core.$loose>]>>>;
     disableHumanInLoop: z.ZodDefault<z.ZodBoolean>;
     enableOperatorRequest: z.ZodDefault<z.ZodBoolean>;
   }, z.core.$loose>>;
@@ -2456,10 +2447,6 @@ declare const widgetConfigPartialSchema: z.ZodObject<{
       server: "server";
       disabled: "disabled";
     }>>;
-    tools: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-      code: z.ZodString;
-      config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    }, z.core.$loose>]>>>;
     disableHumanInLoop: z.ZodDefault<z.ZodBoolean>;
     enableOperatorRequest: z.ZodDefault<z.ZodBoolean>;
   }, z.core.$loose>>>;
@@ -2754,10 +2741,6 @@ declare const widgetSettingsPartialSchema: z.ZodObject<{
       server: "server";
       disabled: "disabled";
     }>>;
-    tools: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-      code: z.ZodString;
-      config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    }, z.core.$loose>]>>>;
     disableHumanInLoop: z.ZodDefault<z.ZodBoolean>;
     enableOperatorRequest: z.ZodDefault<z.ZodBoolean>;
   }, z.core.$loose>>>;
@@ -2914,9 +2897,10 @@ type ConnectionConfigPartial = z.infer<typeof connectionConfigPartialSchema>;
 /**
  * Server-pushable widget settings. Same surface as the editable
  * {@link widgetSettingsSchema} but every field is optional (the server
- * pushes patches, not full configs). Connection fields (publicKey,
- * aiAgentDeploymentId, baseUrl, user, iframe) are deliberately
- * excluded — those are client concerns.
+ * pushes patches, not full configs). Embed identity, host context,
+ * the agent endpoint, storage, and callbacks are deliberately excluded
+ * because they are client concerns. `presentation.iframe` remains a
+ * server-pushable widget setting.
  *
  * Two deltas vs the editable surface:
  *   - `forms` is omitted — resolved form definitions are served by the
@@ -3109,10 +3093,6 @@ declare const serverConfigSchema: z.ZodObject<{
       server: "server";
       disabled: "disabled";
     }>>;
-    tools: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-      code: z.ZodString;
-      config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    }, z.core.$loose>]>>>;
     disableHumanInLoop: z.ZodDefault<z.ZodBoolean>;
     enableOperatorRequest: z.ZodDefault<z.ZodBoolean>;
   }, z.core.$loose>>>;
@@ -3399,10 +3379,6 @@ declare const handshakeResponseSchema: z.ZodObject<{
         server: "server";
         disabled: "disabled";
       }>>;
-      tools: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-        code: z.ZodString;
-        config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-      }, z.core.$loose>]>>>;
       disableHumanInLoop: z.ZodDefault<z.ZodBoolean>;
       enableOperatorRequest: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$loose>>>;
@@ -3593,7 +3569,7 @@ interface ChatWidgetInstance {
  *
  * @example Single widget (default):
  * ```ts
- * mount({ publicKey, mode: 'inline', target: document.getElementById('chat') });
+ * mount({ publicKey, presentation: { mode: 'inline' }, target: document.getElementById('chat') });
  * ```
  * @example Two widgets on one page:
  * ```ts