@helpai/elements 0.72.1 → 1.1.0

package/package.json

@@ -80,5 +80,5 @@
   ],
   "type": "module",
   "types": "./index.d.ts",
-  "version": "0.72.1"
+  "version": "1.1.0"
 }

package/schema.d.ts

@@ -268,10 +268,6 @@ declare const voiceModeSchema: z.ZodEnum<{
   disabled: "disabled";
 }>;
 type VoiceMode = z.infer<typeof voiceModeSchema>;
-declare const toolRefSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-  code: z.ZodString;
-  config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, z.core.$loose>]>;
 declare const featureFlagsSchema: z.ZodObject<{
   disableFileUpload: z.ZodDefault<z.ZodBoolean>;
   voice: z.ZodDefault<z.ZodEnum<{
@@ -279,10 +275,6 @@ declare const featureFlagsSchema: 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>;
@@ -1110,10 +1102,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>>;
@@ -1230,10 +1218,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>;
@@ -1449,10 +1437,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>>;
@@ -1787,10 +1771,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>>>;
@@ -2085,10 +2065,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>>>;
@@ -2245,9 +2221,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
@@ -2440,10 +2417,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>>>;
@@ -2730,10 +2703,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>>>;
@@ -2861,5 +2830,5 @@ declare const ALL_MODES: readonly Mode[];
  */
 declare function emitJsonSchema(): unknown;
 //#endregion
-export { ALL_MODES, ActionName, Asset, AttachmentLimits, Behavior, BlocksConfig, CalloutPosition, CalloutShape, ComposerOptions, ConnectionConfig, ConnectionConfigPartial, Endpoints, FeatureFlags, FeedbackEvent, FeedbackOptions, FieldOption, FieldType, FieldValidation, FooterOptions, FormCondition, FormDef, FormField, FormTranslation, Forms, HandshakeResponse, HapticsOptions, HeaderActions, HeaderOptions, I18nOptions, LauncherCallout, LauncherOptions, LauncherSize, LauncherVariant, Link, Mode, ModuleLayout, ModuleOptions, ModulesOptions, PAGE_AREA_SUGGESTIONS, PageContext, Position, PoweredBy, Presentation, ResizeOptions, ResponseMode, SendButtonOptions, ServerConfig, SiteConfig, SizeOptions, SoundOptions, StringsOverride, ThemeOverrides, ThemePreference, TrackingSettings, UserContext, VoiceMode, WidgetConfig, WidgetConfigPartial, WidgetSettings, WidgetSettingsPartial, actionNameSchema, assetSchema, attachmentLimitsSchema, behaviorSchema, blocksConfigSchema, calloutPositionSchema, calloutShapeSchema, composerOptionsSchema, connectionConfigPartialSchema, connectionConfigSchema, cssColorSchema, cssLengthSchema, emitJsonSchema, endpointsSchema, featureFlagsSchema, feedbackEventSchema, feedbackSchema, fieldOptionSchema, fieldOptionTranslationSchema, fieldTypeSchema, fieldValidationSchema, footerSchema, formConditionSchema, formDefSchema, formFieldSchema, formFieldTranslationSchema, formTranslationSchema, formTriggerSchema, formsSchema, handshakeResponseSchema, hapticsOptionsSchema, headerActionsSchema, headerSchema, i18nSchema, initialSizeSchema, launcherCalloutSchema, launcherOptionsSchema, launcherSizeSchema, launcherVariantSchema, linkSchema, localeSchema, modeSchema, moduleLayoutSchema, moduleSchema, modulesSchema, pageContextSchema, positionSchema, poweredBySchema, presentationSchema, resizeOptionsSchema, responseModeSchema, sendButtonIconSchema, sendButtonOptionsSchema, sendButtonShapeSchema, sendButtonVariantSchema, serverConfigSchema, siteConfigSchema, sizeOptionsSchema, soundOptionsSchema, stringsOverrideSchema, themeFieldSchema, themeOverridesSchema, themePreferenceSchema, toolRefSchema, trackingSchema, userContextSchema, uuid7Schema, voiceModeSchema, widgetConfigPartialSchema, widgetConfigSchema, widgetSettingsPartialSchema, widgetSettingsSchema, widgetSettingsSchemaForMode };
+export { ALL_MODES, ActionName, Asset, AttachmentLimits, Behavior, BlocksConfig, CalloutPosition, CalloutShape, ComposerOptions, ConnectionConfig, ConnectionConfigPartial, Endpoints, FeatureFlags, FeedbackEvent, FeedbackOptions, FieldOption, FieldType, FieldValidation, FooterOptions, FormCondition, FormDef, FormField, FormTranslation, Forms, HandshakeResponse, HapticsOptions, HeaderActions, HeaderOptions, I18nOptions, LauncherCallout, LauncherOptions, LauncherSize, LauncherVariant, Link, Mode, ModuleLayout, ModuleOptions, ModulesOptions, PAGE_AREA_SUGGESTIONS, PageContext, Position, PoweredBy, Presentation, ResizeOptions, ResponseMode, SendButtonOptions, ServerConfig, SiteConfig, SizeOptions, SoundOptions, StringsOverride, ThemeOverrides, ThemePreference, TrackingSettings, UserContext, VoiceMode, WidgetConfig, WidgetConfigPartial, WidgetSettings, WidgetSettingsPartial, actionNameSchema, assetSchema, attachmentLimitsSchema, behaviorSchema, blocksConfigSchema, calloutPositionSchema, calloutShapeSchema, composerOptionsSchema, connectionConfigPartialSchema, connectionConfigSchema, cssColorSchema, cssLengthSchema, emitJsonSchema, endpointsSchema, featureFlagsSchema, feedbackEventSchema, feedbackSchema, fieldOptionSchema, fieldOptionTranslationSchema, fieldTypeSchema, fieldValidationSchema, footerSchema, formConditionSchema, formDefSchema, formFieldSchema, formFieldTranslationSchema, formTranslationSchema, formTriggerSchema, formsSchema, handshakeResponseSchema, hapticsOptionsSchema, headerActionsSchema, headerSchema, i18nSchema, initialSizeSchema, launcherCalloutSchema, launcherOptionsSchema, launcherSizeSchema, launcherVariantSchema, linkSchema, localeSchema, modeSchema, moduleLayoutSchema, moduleSchema, modulesSchema, pageContextSchema, positionSchema, poweredBySchema, presentationSchema, resizeOptionsSchema, responseModeSchema, sendButtonIconSchema, sendButtonOptionsSchema, sendButtonShapeSchema, sendButtonVariantSchema, serverConfigSchema, siteConfigSchema, sizeOptionsSchema, soundOptionsSchema, stringsOverrideSchema, themeFieldSchema, themeOverridesSchema, themePreferenceSchema, trackingSchema, userContextSchema, uuid7Schema, voiceModeSchema, widgetConfigPartialSchema, widgetConfigSchema, widgetSettingsPartialSchema, widgetSettingsSchema, widgetSettingsSchemaForMode };
 //# sourceMappingURL=schema.d.ts.map

package/schema.json

@@ -472,7 +472,7 @@
             },
             "showReasoning": {
               "default": false,
-              "description": "Show the model's reasoning (\"thoughts\") as a collapsible block above each answer. `false` (default) hides it — a loading indicator still shows while the model works. Reasoning is never persisted; it only appears live.",
+              "description": "Show the model's reasoning (\"thoughts\") as a collapsible block above each answer. `false` (default) hides it — a loading indicator still shows while the model works. Reasoning is absent from durable history, but the current turn's short-lived resume backlog may replay it after an immediate reconnect or reload.",
               "type": "boolean"
             },
             "showToolCalls": {
@@ -1283,41 +1283,6 @@
                 "disabled"
               ]
             },
-            "tools": {
-              "description": "Backend tools the assistant may invoke. Bare codes (`'tool:send-money'`) or rich refs (`{ code, config }`).",
-              "maxItems": 200,
-              "type": "array",
-              "items": {
-                "anyOf": [
-                  {
-                    "type": "string",
-                    "minLength": 1,
-                    "maxLength": 200
-                  },
-                  {
-                    "type": "object",
-                    "properties": {
-                      "code": {
-                        "type": "string",
-                        "minLength": 1,
-                        "maxLength": 200
-                      },
-                      "config": {
-                        "type": "object",
-                        "propertyNames": {
-                          "type": "string"
-                        },
-                        "additionalProperties": {}
-                      }
-                    },
-                    "required": [
-                      "code"
-                    ],
-                    "additionalProperties": {}
-                  }
-                ]
-              }
-            },
             "disableHumanInLoop": {
               "default": false,
               "description": "Turn OFF the human-in-the-loop tool UI — the inline ask-questions form + approve/reject controls for gated tools. Unset/`false` = shown (default), `true` = suppressed (the wire still carries the signals).",
@@ -1336,7 +1301,7 @@
             "enableOperatorRequest"
           ],
           "additionalProperties": {},
-          "description": "Capability flags — file upload, voice mode, and the tools the assistant may invoke.",
+          "description": "Capability flags — file upload, voice mode, HITL, and operator requests.",
           "examples": [
             {
               "voice": "local"
@@ -1347,9 +1312,7 @@
             },
             {
               "voice": "server",
-              "tools": [
-                "tool:send-money"
-              ]
+              "enableOperatorRequest": true
             }
           ]
         },
@@ -1993,7 +1956,7 @@
               "format": "uri"
             },
             "sampleRate": {
-              "description": "Per-visitor sampling 0..1 (decided once per page load, keeping funnels intact). Default `1`.",
+              "description": "Per-widget-runtime sampling 0..1 (one decision per mounted runtime, keeping that runtime's funnel intact). Default `1`.",
               "type": "number",
               "minimum": 0,
               "maximum": 1
@@ -2005,7 +1968,7 @@
             }
           },
           "additionalProperties": {},
-          "description": "Anonymous usage tracking for the widget owner — GA-style pixel events (open, send, form submit, …) with page / device / locale dimensions. Never includes message content; visitors are identified only by the widget's anonymous visitorId.",
+          "description": "Anonymous usage tracking for the widget owner — GA-style pixel events (open, send, form submit, …) with page / device / locale dimensions. Never includes message or form content; the only visitor identifier is the widget's anonymous visitorId.",
           "examples": [
             {
               "enabled": true
@@ -2028,7 +1991,7 @@
         "theme"
       ],
       "additionalProperties": {},
-      "description": "Full client widget config — connection (where + auth) + widget settings (look + behaviour) + page-mode extras. This is what the runtime parses on `mount()` / `init()`. Mode-specific constraints (e.g. `position` only meaningful in `floating`) are NOT enforced here — the runtime silently ignores irrelevant fields rather than rejecting them so the same object can flow across mode changes.",
+      "description": "Full tooling config — connection (where + auth) + widget settings (look + behaviour) + page-mode handshake extras. The production widget does not import this Zod schema. Mode-specific constraints (e.g. `position` only meaningful in `floating`) are NOT enforced here so the same object can flow across mode changes.",
       "examples": [
         {
           "publicKey": "agent_pk_demo",
@@ -2355,7 +2318,7 @@
                 },
                 "showReasoning": {
                   "default": false,
-                  "description": "Show the model's reasoning (\"thoughts\") as a collapsible block above each answer. `false` (default) hides it — a loading indicator still shows while the model works. Reasoning is never persisted; it only appears live.",
+                  "description": "Show the model's reasoning (\"thoughts\") as a collapsible block above each answer. `false` (default) hides it — a loading indicator still shows while the model works. Reasoning is absent from durable history, but the current turn's short-lived resume backlog may replay it after an immediate reconnect or reload.",
                   "type": "boolean"
                 },
                 "showToolCalls": {
@@ -3166,41 +3129,6 @@
                     "disabled"
                   ]
                 },
-                "tools": {
-                  "description": "Backend tools the assistant may invoke. Bare codes (`'tool:send-money'`) or rich refs (`{ code, config }`).",
-                  "maxItems": 200,
-                  "type": "array",
-                  "items": {
-                    "anyOf": [
-                      {
-                        "type": "string",
-                        "minLength": 1,
-                        "maxLength": 200
-                      },
-                      {
-                        "type": "object",
-                        "properties": {
-                          "code": {
-                            "type": "string",
-                            "minLength": 1,
-                            "maxLength": 200
-                          },
-                          "config": {
-                            "type": "object",
-                            "propertyNames": {
-                              "type": "string"
-                            },
-                            "additionalProperties": {}
-                          }
-                        },
-                        "required": [
-                          "code"
-                        ],
-                        "additionalProperties": {}
-                      }
-                    ]
-                  }
-                },
                 "disableHumanInLoop": {
                   "default": false,
                   "description": "Turn OFF the human-in-the-loop tool UI — the inline ask-questions form + approve/reject controls for gated tools. Unset/`false` = shown (default), `true` = suppressed (the wire still carries the signals).",
@@ -3219,7 +3147,7 @@
                 "enableOperatorRequest"
               ],
               "additionalProperties": {},
-              "description": "Capability flags — file upload, voice mode, and the tools the assistant may invoke.",
+              "description": "Capability flags — file upload, voice mode, HITL, and operator requests.",
               "examples": [
                 {
                   "voice": "local"
@@ -3230,9 +3158,7 @@
                 },
                 {
                   "voice": "server",
-                  "tools": [
-                    "tool:send-money"
-                  ]
+                  "enableOperatorRequest": true
                 }
               ]
             },
@@ -3416,7 +3342,7 @@
                   "format": "uri"
                 },
                 "sampleRate": {
-                  "description": "Per-visitor sampling 0..1 (decided once per page load, keeping funnels intact). Default `1`.",
+                  "description": "Per-widget-runtime sampling 0..1 (one decision per mounted runtime, keeping that runtime's funnel intact). Default `1`.",
                   "type": "number",
                   "minimum": 0,
                   "maximum": 1
@@ -3428,7 +3354,7 @@
                 }
               },
               "additionalProperties": {},
-              "description": "Anonymous usage tracking for the widget owner — GA-style pixel events (open, send, form submit, …) with page / device / locale dimensions. Never includes message content; visitors are identified only by the widget's anonymous visitorId.",
+              "description": "Anonymous usage tracking for the widget owner — GA-style pixel events (open, send, form submit, …) with page / device / locale dimensions. Never includes message or form content; the only visitor identifier is the widget's anonymous visitorId.",
               "examples": [
                 {
                   "enabled": true

package/schema.mjs

@@ -1,2 +1,2 @@
-import{z as e}from"zod";const t=e.object({url:e.string().min(1).max(2048).describe(`Public URL of the image. Must be a full URL or root-relative path.`),alt:e.string().min(1).max(200).optional().describe(`Alt text for screen readers. Omit only for purely decorative images.`)}).strict().describe(`A single image asset (logo, hero, icon).`),n=e.object({id:e.string().min(1).max(100).optional().describe(`Stable id used as Preact key + analytics target.`),label:e.string().min(1).max(120).describe(`Visible link text.`),href:e.string().min(1).max(2048).optional().describe(`Click target. Optional — when omitted the link renders as a non-clickable heading.`),icon:e.string().min(1).max(100).optional().describe(`Built-in icon preset name (chat / spark / message / help / wand) or a custom string.`),description:e.string().min(1).max(300).optional().describe(`Subtitle shown below the label. Used by link cards in page mode.`)}).loose().describe(`A navigation link / link card.`),r=e.string().min(1).max(120).describe("Any CSS length — `640px`, `80vh`, `calc(100vh - 64px)`, etc. Validated only for size, not syntax."),i=e.string().min(1).max(120).describe("Any CSS colour — hex, `rgb()`, `hsl()`, `oklch()`, a named colour, or a `var(--token)`."),a=e.string().min(1).max(35).describe("BCP-47 locale tag (e.g. `en`, `fr-CA`, `zh-Hant-HK`)."),ee=e.uuidv7().describe(`UUID v7 (RFC 9562) — the single id format for visitor / conversation / message / file / content ids.`),o=e.enum([`normal`,`expanded`,`fullscreen`,`auto`]),s=e.object({enabled:e.boolean().default(!1).describe(`Show a corner-grip handle the user can drag to resize the panel.`),minWidth:r.optional().describe(`Smallest width the user can drag the panel to.`),maxWidth:r.optional().describe(`Largest width the user can drag the panel to.`),minHeight:r.optional().describe(`Smallest height the user can drag the panel to.`),maxHeight:r.optional().describe(`Largest height the user can drag the panel to.`)}).loose().describe("Drag-resize controls. When `enabled`, a corner grip lets users resize the panel within the optional min/max bounds.").meta({examples:[{enabled:!1},{enabled:!0,minWidth:`320px`,maxWidth:`720px`,minHeight:`400px`,maxHeight:`90vh`}]}),te=e.object({width:r.optional().describe("Panel width (CSS length). Mode-specific defaults — floating `380px`, modal `min(960px, 92vw)`, drawer `min(440px, calc(100vw - 32px))`. Set this to override; inline/standalone/page modes ignore it."),height:r.optional().describe("Panel height (CSS length). Mode-specific defaults — floating `600px`, modal `min(720px, 88vh)`, drawer `100vh` (clamped to `100vh − inset-y × 2`). Set this to override."),expanded:e.object({width:r.optional().describe(`Width when the user clicks the expand button.`),height:r.optional().describe(`Height when the user clicks the expand button.`)}).loose().optional().describe("Dimensions when the panel is in its `expanded` tier (between normal and fullscreen). Applies to floating / modal / drawer; ignored in inline / standalone / page where the panel always fills its parent."),resize:s.optional().describe(`Drag-resize controls — adds a corner grip the user can drag.`),inset:r.optional().describe("Drawer-mode edge inset — gap from each viewport edge (top/bottom/left/right). Single value applied to all four sides. Defaults to `3vh` vertical / `12px` horizontal. Use `0` for a full-edge drawer (no gap), or `5vh` for a centered-looking flyout with extra breathing room. Ignored by every other mode."),initialSize:o.default(`auto`).describe("Which size tier to open with on the first mount: `normal` / `expanded` / `fullscreen` / `auto`. Default `auto` is responsive by viewport: phones (< 640 px) open `fullscreen` edge-to-edge, tablets (640 px … `autoSizeBreakpoint`) open `normal`, and desktop/laptop (≥ `autoSizeBreakpoint`) open `expanded` — so the panel is right for the device out of the box. Set a literal to pin one tier everywhere; the user's own resize is remembered per-device and wins on reload."),autoSizeBreakpoint:e.number().int().min(0).max(1e4).default(900).describe("Viewport width (px) at/above which `initialSize: auto` opens `expanded` instead of `normal`. (Phones below 640 px always open `fullscreen`.)")}).loose().describe("Panel dimensions and drawer inset. Width/height override the mode-specific defaults (floating compact popover, modal centered dialog, drawer flyout). `inset` only affects drawer mode.").meta({examples:[{width:`420px`,height:`640px`},{width:`min(560px, 92vw)`,height:`min(640px, 90vh)`},{width:`420px`,expanded:{width:`640px`,height:`780px`},initialSize:`auto`,autoSizeBreakpoint:900},{width:`min(1100px, 95vw)`,height:`min(820px, 92vh)`},{width:`360px`,inset:`8vh`},{width:`420px`,height:`100vh`,inset:`0`},{width:`420px`,height:`60vh`,inset:`20vh`}]}),ne=e.enum([`floating`,`inline`,`standalone`,`page`,`modal`,`drawer`]),re=e.enum([`bottom-right`,`bottom-left`,`top-right`,`top-left`]),c=e.object({mode:ne.default(`floating`).describe("Rendering shape. `floating` (FAB + popover), `inline` (in-flow block), `standalone` (full viewport), `page` (sidebar + chat), `modal` (centered overlay), `drawer` (side dock)."),position:re.default(`bottom-right`).describe("Anchor corner. `floating` uses it for the FAB; `drawer` uses the `*-left` / `*-right` suffix to pick the dock side. Ignored in other modes."),iframe:e.boolean().default(!1).describe(`Wrap the widget in a same-origin iframe for stricter JS + CSS isolation from the host page. Composes with every mode.`),size:te.optional().describe("Panel dimensions. Mode-aware defaults (floating compact popover, modal centered dialog, drawer flyout) — fields here override them. Includes `inset` (drawer flyout gap), `expanded` tier, drag-resize grip.")}).loose().describe(`Layout fundamentals — mode, anchor corner, iframe isolation, panel size + drawer inset.`).meta({examples:[{mode:`floating`,position:`bottom-right`},{mode:`modal`,size:{width:`min(1100px, 95vw)`,height:`min(820px, 92vh)`}},{mode:`drawer`,position:`bottom-right`},{mode:`drawer`,position:`top-right`,size:{width:`360px`,inset:`8vh`}},{mode:`drawer`,position:`bottom-right`,size:{width:`420px`,height:`100vh`,inset:`0`}}]}),l=e.enum([`streaming`,`buffered`]),u=e.object({startMinimized:e.boolean().default(!0).describe("Don't auto-open the floating panel on first visit. `true` (default) shows the FAB collapsed; `false` opens the panel on mount."),responseMode:l.default(`streaming`).describe("How the assistant's reply arrives. `streaming` (default) types tokens as they generate; `buffered` waits + shows the full reply at once."),showReasoning:e.boolean().default(!1).describe('Show the model\'s reasoning ("thoughts") as a collapsible block above each answer. `false` (default) hides it — a loading indicator still shows while the model works. Reasoning is never persisted; it only appears live.'),showToolCalls:e.boolean().default(!1).describe("Show automatic tool/function calls the model makes (e.g. search) as collapsible detail+result cards in the transcript. `false` (default) hides them. Interactive tools (ask-questions / approval) always show."),showSources:e.boolean().default(!1).describe("Show the citation sources behind an answer (web links + document/file references) in the transcript. `false` (default) hides them."),disableMessageFeedback:e.boolean().default(!1).describe("Turn OFF the 👍/👎 feedback controls under each rateable reply (AI or operator). Unset/`false` = shown (default), `true` = hidden. A choice fires the `messageFeedback` event and is POSTed best-effort to `/pai/message-feedback`."),autoSendSuggestions:e.boolean().default(!1).describe("Auto-send a suggestion chip's text the moment it's tapped. `false` (default) fills the composer with the text so the visitor can edit before sending; `true` sends it immediately.")}).loose().describe(`Conversation behaviour — lifecycle, streaming, and the transcript surface (scroll, feedback).`).meta({examples:[{startMinimized:!0,responseMode:`streaming`},{startMinimized:!1,responseMode:`buffered`,disableMessageFeedback:!0}]}),d=e.enum([`auto`,`light`,`dark`]),f=e.object({accent:i.optional().describe(`Brand accent colour. Drives the FAB, send button, links, and active states. CSS colour.`),accentText:i.optional().describe(`Foreground colour rendered ON the accent (FAB icon, send-button glyph). CSS colour.`),radius:r.optional().describe("Corner radius for the panel + buttons. CSS length (`8px`, `0.75rem`, `12px`)."),fontFamily:e.string().min(1).max(200).optional().describe("Font stack used inside the widget. Standard CSS `font-family` value."),contentMaxWidth:r.optional().describe("Max width of the readable content column (messages, history, home, composer) on a wide surface — content centres, full-bleed bars keep their edges. CSS length; default `768px`. Set `100%` to fill the surface (no cap). Modal + drawer already fill their card by default.")}).loose().describe(`Theme token overrides. Any field left unset falls through to the brand's default theme.`).meta({examples:[{accent:`#10b981`,radius:`12px`},{accent:`#7c3aed`,accentText:`#ffffff`,radius:`16px`,fontFamily:`'Inter', system-ui`},{accent:`oklch(0.7 0.2 145)`,radius:`0.5rem`},{accent:`#5b5bd6`,contentMaxWidth:`960px`}]}),p=e.union([d,f]).describe(`'auto' | 'light' | 'dark', or a tokens override object.`).meta({examples:[`auto`,`dark`,{accent:`#10b981`,radius:`12px`},{accent:`#7c3aed`,accentText:`#fff`,radius:`16px`,fontFamily:`'Inter', system-ui`}]}),m=e.enum([`circle`,`pill`,`bar`,`minimal`]),h=e.enum([`sm`,`md`,`lg`]),g=e.enum([`pill`,`bubble`,`callout`]),_=e.enum([`auto`,`horizontal`,`vertical`]),v=e.object({text:e.string().min(1).max(500).default(`👋 Hi! Need any help?`).describe("The message to show in the bubble. Defaults to a friendly greeting; replace with your own copy (e.g. 'Click here →'). May also be an i18n key (e.g. `launcherCallout`) resolved against `i18n.strings` for per-locale copy; a non-key literal renders as-is."),shape:g.default(`pill`).describe("Visual shape — `pill` (slim label + arrow), `bubble` (speech-bubble tail), `callout` (loud variant)."),position:_.default(`auto`).describe("Where the bubble sits relative to the FAB. `auto` (default) picks the side facing into the page. `horizontal` anchors beside the FAB (left/right depending on the FAB's corner). `vertical` anchors above/below the FAB. Concrete left/right/top/bottom is derived from the FAB's corner so the bubble always stays on-screen."),delayMs:e.number().int().min(0).max(6e4).default(1200).describe(`How long to wait after page load before the bubble appears, in milliseconds.`),autoDismissMs:e.number().int().min(0).max(6e5).default(0).describe("Auto-hide the bubble after this many milliseconds. `0` (default) keeps it until the user dismisses."),animated:e.boolean().default(!0).describe("Subtle horizontal nudge to draw the eye. Disabled automatically by `prefers-reduced-motion`."),persistent:e.boolean().default(!0).describe("How dismissals stick. `true` (default) — re-show on every visit regardless of prior dismissal (the 'recurring greeting' behaviour). `false` — clicking X stores the message text and that exact message stays hidden across visits (the 'one-time hint' behaviour).")}).loose().describe(`Pre-engagement message bubble next to the FAB. Use it for a greeting ('Hi, need help?'), an attention-grabbing nudge ('Click here →'), or any one-time onboarding tip — same component, configured for the use case.`),y=e.object({variant:m.default(`circle`).describe("FAB visual style. `circle` — round bubble (icon only). `pill` — icon + label. `bar` — wide rectangular button. `minimal` — text-only outline."),size:h.default(`md`).describe(`FAB size preset — small / medium / large.`),label:e.string().max(200).optional().describe("Text rendered on the FAB (only shown for `pill` / `bar` / `minimal` variants)."),icon:e.string().max(8e3).optional().describe("Icon shown on the FAB / drawer edge tab. Built-in presets: `chat` / `message` / `bubbles` / `spark` / `wand` / `bot` / `help` / `lifebuoy` / `headset`. Anything else is treated as raw SVG."),hidden:e.boolean().default(!1).describe("Hide the FAB entirely (page brings its own trigger that calls `instance.open()`)."),callout:v.optional()}).loose().describe(`Floating-launcher (FAB) appearance and behaviour. The FAB is the round button in the corner that opens the chat panel. Floating mode only.`).meta({examples:[{variant:`circle`,size:`md`},{variant:`pill`,label:`Ask AI`,icon:`spark`},{variant:`circle`,callout:{text:`👋 Need help?`,shape:`bubble`,persistent:!0}},{variant:`circle`,callout:{text:`Click to start`,shape:`pill`,delayMs:1200}}]}),b=e.enum([`local`,`server`,`disabled`]),x=e.union([e.string().min(1).max(200),e.object({code:e.string().min(1).max(200),config:e.record(e.string(),e.unknown()).optional()}).loose()]),S=e.object({disableFileUpload:e.boolean().default(!1).describe("Turn OFF file uploads — hide the paperclip button + reject drag/drop/paste. Unset/`false` = enabled (default), `true` = disabled."),voice:b.default(`local`).describe("Voice input mode. `local` — Web Speech API in the browser (free, runs on-device). `server` — record audio + upload to the transcribe endpoint. `disabled` — hide the mic button."),tools:e.array(x).max(200).optional().describe("Backend tools the assistant may invoke. Bare codes (`'tool:send-money'`) or rich refs (`{ code, config }`)."),disableHumanInLoop:e.boolean().default(!1).describe("Turn OFF the human-in-the-loop tool UI — the inline ask-questions form + approve/reject controls for gated tools. Unset/`false` = shown (default), `true` = suppressed (the wire still carries the signals)."),enableOperatorRequest:e.boolean().default(!1).describe("Opt IN operator control — expose the 'Talk to an operator' affordance + connected-to-operator states for this deployment. Unset/`false` = off (default), `true` = on. Unlike the `disable*` flags this is a positive opt-in for a new capability.")}).loose().describe(`Capability flags — file upload, voice mode, and the tools the assistant may invoke.`).meta({examples:[{voice:`local`},{disableFileUpload:!0,voice:`disabled`},{voice:`server`,tools:[`tool:send-money`]}]}),C=e.enum([`clear`,`expand`,`fullscreen`,`sound`,`history`,`language`,`theme`,`textSize`,`close`]),w=e.array(C).max(10).describe("Which actions the header exposes. `history` + `close` are dedicated buttons; the rest appear in the ⋯ menu. Unlisted actions are hidden; order is irrelevant. Pick from: `clear`, `expand`, `fullscreen`, `sound`, `history`, `language`, `theme`, `textSize`, `close`. Per-mode defaults live in `DEFAULT_ACTIONS_BY_MODE`.").meta({examples:[[`theme`,`history`,`close`,`clear`,`fullscreen`,`sound`,`language`],[`theme`,`history`,`clear`,`language`],[`close`]]}),T=e.object({actions:w.optional().describe(`Which header actions are enabled (history/✕ buttons + ⋯ menu).`)}).loose().describe(`Panel-header configuration.`).meta({examples:[{actions:[`theme`,`history`,`close`,`clear`,`fullscreen`]}]}),E=e.enum([`messageReceived`,`messageSent`,`error`,`voiceStart`,`voiceStop`]),D=e.object({enabled:e.boolean().default(!0).describe(`Master on/off for audible notifications. On by default — browser autoplay policy still requires a prior user gesture before any sound plays.`),volume:e.number().min(0).max(1).default(.3).describe("Global volume 0..1. `0.3` (default) is intentionally subtle."),events:e.partialRecord(E,e.union([e.boolean(),e.string().min(1).max(2048)])).optional().describe("Per-event override map. Value: `true` = built-in tone, `false` = silent, `string` = URL to a custom audio file (mp3/wav/ogg).")}).loose().describe("Audible notifications. `events` accepts true (default tone), false (off), or a URL to an audio file.").meta({examples:[{enabled:!0,volume:.3},{enabled:!0,volume:.5,events:{messageReceived:!0,error:!1}},{enabled:!0,events:{messageReceived:`https://cdn.help.ai/ping.mp3`}}]}),O=e.object({enabled:e.boolean().default(!0).describe(`Master on/off. Default: on for touch devices, silently ignored elsewhere.`),events:e.partialRecord(E,e.union([e.boolean(),e.number().int(),e.array(e.number().int())])).optional().describe("Per-event vibration pattern. Value: `true` = default pattern, `false` = silent, number = single vibrate ms, array = `[vibrate, pause, vibrate, …]`.")}).loose().describe("Touch-device vibration. `events` accepts true (default), number (single vibrate ms), or [vibrate,pause,vibrate,…].").meta({examples:[{enabled:!0},{enabled:!0,events:{messageReceived:30,error:[40,60,40]}}]}),k=e.object({sound:D.optional(),haptics:O.optional()}).loose().describe(`Audible + tactile feedback.`).meta({examples:[{sound:{enabled:!0,volume:.3},haptics:{enabled:!0}},{sound:{enabled:!1},haptics:{enabled:!1}}]}),A=e.enum([`circle`,`square`,`pill`]),j=e.enum([`arrowUp`,`paperPlane`,`send`,`chevron`]),M=e.enum([`filled`,`outline`,`ghost`]),N=e.object({shape:A.default(`circle`).describe("Send button outline shape — `circle` / `square` / `pill`."),icon:j.default(`arrowUp`).describe("Icon inside the send button — `arrowUp` / `paperPlane` / `send` / `chevron`."),variant:M.default(`filled`).describe("Fill treatment — `filled` (solid accent), `outline` (border only), `ghost` (no border, no fill).")}).loose().describe(`Send-button styling — shape, icon, and fill treatment.`).meta({examples:[{shape:`circle`,icon:`arrowUp`,variant:`filled`},{shape:`pill`,icon:`send`,variant:`outline`},{shape:`square`,icon:`paperPlane`,variant:`ghost`}]}),P=e.object({maxBytes:e.number().int().min(0).max(1024*1024*1024).default(10*1024*1024).describe("Maximum size per uploaded file, in bytes. `10 MiB` (10485760) by default."),maxCount:e.number().int().min(0).max(100).default(10).describe(`Maximum number of attachments per message.`),accept:e.string().max(2e3).default(`*/*`).describe("Allowed MIME types — comma-separated `accept` attribute string, e.g. `image/*,application/pdf`.")}).loose().describe(`Client-side attachment limits. Server enforcement is still required.`).meta({examples:[{maxBytes:10485760,maxCount:10,accept:`*/*`},{maxBytes:5242880,maxCount:3,accept:`image/*,application/pdf`}]}),F=e.object({sendButton:N.optional(),attachments:P.optional()}).loose().describe(`Composer chrome — send-button styling + attachment limits.`).meta({examples:[{sendButton:{shape:`circle`,icon:`arrowUp`,variant:`filled`}},{sendButton:{shape:`pill`,icon:`send`,variant:`outline`}},{attachments:{maxBytes:5242880,maxCount:3,accept:`image/*,application/pdf`}}]}),I=e.object({text:e.string().max(200).optional().describe("Visible attribution text (e.g. `Powered by Help AI`)."),href:e.url().max(2048).optional().describe("Click target — the attribution becomes a link. Must be a full URL (`https://…`)."),logoUrl:e.url().max(2048).optional().describe(`Small logo rendered before the text. Must be a full URL.`)}).loose().describe(`"Powered by …" attribution shown below the composer.`).meta({examples:[{text:`Powered by Help AI`},{text:`Powered by Help AI`,href:`https://help.ai`,logoUrl:`https://help.ai/logo.svg`}]}),L=e.object({poweredBy:I.optional(),composerDisclaimer:e.string().max(500).optional().describe(`Small muted text under the composer (like ChatGPT's 'ChatGPT can make mistakes.'). Empty = hidden.`)}).loose().describe(`Footer — attribution + composer disclaimer.`).meta({examples:[{poweredBy:{text:`Powered by Help AI`,href:`https://help.ai`}},{composerDisclaimer:`AI responses may be inaccurate.`}]}),R=e.enum([`text`,`email`,`tel`,`url`,`number`,`date`,`time`,`textarea`,`select`,`radio`,`checkbox`,`multiselect`]),z=e.object({value:e.string().min(1).max(200).describe(`The value recorded when this choice is picked.`),label:e.string().min(1).max(200).optional().describe("Display text; falls back to `value`."),description:e.string().max(280).optional().describe(`Optional sub-label under the choice.`)}).loose(),B=e.object({pattern:e.string().max(500).optional().describe("Regex source string — text-like fields (e.g. `^\\d{5}$`)."),minLength:e.number().int().min(0).max(1e4).optional(),maxLength:e.number().int().min(1).max(1e4).optional(),min:e.number().optional().describe("Minimum — `number` fields."),max:e.number().optional().describe("Maximum — `number` fields."),minSelections:e.number().int().min(0).max(50).optional().describe("Minimum picks — `multiselect`."),maxSelections:e.number().int().min(1).max(50).optional().describe("Maximum picks — `multiselect`.")}).loose(),V=e.object({name:e.string().min(1).max(80).describe("Stable key the answer is recorded under (e.g. `email`)."),label:e.string().min(1).max(200).describe(`Visible field label.`),type:R.describe(`Field renderer + built-in validation (email/tel/url/number/date/time checked).`),placeholder:e.string().max(200).optional(),required:e.boolean().optional().default(!0).describe("Must be answered to submit. `false` allows skipping."),defaultValue:e.string().max(2e3).optional().describe("Pre-filled value (comma-join for `multiselect`)."),options:e.array(z).max(50).optional().describe("Choices for `select` / `radio` / `multiselect`."),validation:B.optional(),allowOther:e.boolean().optional().describe("`select`/`radio`/`multiselect` — allow a free-text 'Other' answer."),validationHint:e.string().max(280).optional().describe(`Small helper line under the field.`)}).loose(),H=e.string().regex(/^(pre-chat|conversation-closed|panel-close|manual|after-messages:\d+|idle:\d+|page-area:.+)$/,`Unrecognised form trigger`).describe("When the form fires: `pre-chat`, `after-messages:N`, `conversation-closed`, `panel-close`, `idle:Nseconds`, `page-area:<area>`, or `manual`."),U=e.object({missingContext:e.array(e.string().max(80)).max(20).optional().describe("Only show if `userContext` lacks ALL of these keys (progressive profiling)."),pageArea:e.union([e.string().max(64),e.array(e.string().max(64)).max(20)]).optional().describe("Only on these `pageContext.area` values."),minMessages:e.number().int().min(0).max(1e3).optional(),maxMessages:e.number().int().min(0).max(1e3).optional()}).loose(),ie=e.object({value:e.string().min(1).max(200).describe("The canonical option `value` this localizes."),label:e.string().min(1).max(200).optional(),description:e.string().max(280).optional()}).loose(),W=e.object({name:e.string().min(1).max(80).describe("The canonical field `name` this localizes."),label:e.string().min(1).max(200).optional(),placeholder:e.string().max(200).optional(),validationHint:e.string().max(280).optional(),options:e.array(ie).max(50).optional()}).loose(),G=e.object({locale:a,title:e.string().max(120).optional(),description:e.string().max(500).optional(),submitLabel:e.string().max(60).optional(),fields:e.array(W).max(50).optional()}).loose(),K=e.object({id:e.string().min(1).max(80).describe("Stable id — persistence dedupe + `manual` openForm(id)."),on:e.union([H,e.array(H).min(1).max(8)]).describe(`Trigger(s) that surface this form.`),when:U.optional().describe(`Extra eligibility predicate evaluated when a trigger fires.`),fields:e.array(V).max(20).default([]).describe(`The questions, in order. ≥1 required to show.`),title:e.string().max(120).optional(),description:e.string().max(500).optional(),submitLabel:e.string().max(60).optional(),skippable:e.boolean().default(!1).describe(`Show a Skip control so the visitor can dismiss the form.`),frequency:e.enum([`once`,`conversation`,`always`]).default(`once`).describe("`once` (per device, persisted), `conversation` (re-eligible each new conversation), or `always`."),mirrorToContext:e.boolean().default(!0).describe("Mirror the answers into `userContext` so they ride every request. Set `false` for PII (DOB, policy #, symptoms) — those then go only to the submit endpoint."),reopenable:e.boolean().default(!0).describe('Skipped marker offers a "Fill out" button that reopens the form. Set `false` when a skip must be final (e.g. a consent ask that should not be re-surfaced).'),reviewable:e.boolean().default(!0).describe("Submitted marker expands in place to a read-only list of the visitor's answers. Set `false` for sensitive answers that shouldn't linger on screen."),defaultLocale:a.optional().describe(`BCP-47 locale the top-level strings (title / fields copy) are authored in.`),translations:e.array(G).max(50).optional().describe("Per-locale string overrides — the data module trims to the bootstrap `?locale=` (≤1); the widget overlays it onto the default copy.")}).loose(),q=e.array(K).max(20).describe("Event-driven forms — an ordered list (order = priority). Each binds to trigger event(s), gates the chat until submit/skip, dedupes by frequency, and records via `endpoints.submitForm`. Generic across verticals.").meta({examples:[[{id:`intake`,on:`pre-chat`,fields:[{name:`email`,label:`Email`,type:`email`}]}],[{id:`signal`,on:`pre-chat`,title:`Before we start`,fields:[{name:`name`,label:`Your name`,type:`text`},{name:`email`,label:`Work email`,type:`email`}]},{id:`csat`,on:`conversation-closed`,frequency:`always`,fields:[{name:`rating`,label:`How did we do?`,type:`radio`,options:[{value:`good`},{value:`bad`}]}]},{id:`appointment`,on:[`page-area:booking`,`manual`],mirrorToContext:!1,fields:[{name:`department`,label:`Department`,type:`select`,options:[{value:`dermatology`},{value:`cardiology`}]},{name:`date`,label:`Preferred date`,type:`date`},{name:`consent`,label:`I consent to be contacted`,type:`checkbox`}]}]]}),J=e.record(e.string(),e.string()),Y=e.union([J,e.record(a,J)]).describe(`Per-instance UI string overrides. Flat = active-locale only; nested = multi-locale map. Both forms are partial — missing keys fall through to built-in defaults.`).meta({examples:[{send:`Click`,stop:`Halt`,composerPlaceholder:`Type your question…`},{en:{send:`Send`,composerPlaceholder:`Type a message…`},fr:{send:`Envoyer`,composerPlaceholder:`Tapez un message…`}}]}),X=e.object({locale:a.optional().describe("BCP-47 locale tag forced for this widget instance (e.g. `fr-CA`). Page-owner explicit override."),defaultLocale:e.union([e.literal(`auto`),a]).default(`auto`).describe("Initial / fallback locale for users who haven't picked one. `auto` sniffs `navigator.language`."),availableLocales:e.array(a).max(200).optional().describe(`BCP-47 locale tags shown in the runtime language switcher. Hidden when fewer than 2 entries.`),strings:Y.optional()}).loose().describe(`Locale + i18n overrides.`).meta({examples:[{defaultLocale:`auto`},{defaultLocale:`en`,availableLocales:[`en`,`fr`,`de`]},{locale:`fr-CA`,strings:{send:`Envoyer`}}]}),ae=e.enum([`chat`,`home`,`help`,`news`]),oe=e.object({label:e.string().min(1).max(40).describe("Tab label — an i18n key (resolved against the i18n strings, e.g. `tabHome`) or a literal. Translations ride `i18n.strings`."),layout:ae.describe("UI layout that renders this tab: `chat` (the conversation), `home`, `help`, or `news`."),contentTags:e.array(e.string().max(60)).max(20).optional().describe("Content tags this tab scopes to — the `tags` filter on `GET /content` (matches content tagged with ANY of them). Omit for the `chat` layout."),id:e.string().max(60).optional().describe("Stable id for navigation + last-tab persistence. Defaults to the first `contentTags` entry, else `layout`."),brandName:e.string().max(80).optional().describe("`home` — hero wordmark (e.g. your company name)."),hideGreeting:e.boolean().optional().describe("`home` — hide the greeting hero. Unset/`false` = shown (default), `true` = hidden."),greetingText:e.string().max(280).optional().describe("`home` — override the greeting headline (default 'How can we help?'); supports a `{name}` token."),userAvatars:e.array(e.object({name:e.string().min(1).max(80),avatar:e.string().max(2048).optional().describe("Image URL; falls back to initials of `name`."),role:e.string().max(80).optional()}).loose()).max(10).optional().describe("`home` — team/agent avatars shown in the hero."),hideSearchBar:e.boolean().optional().describe("`home` — hide the 'Search for help' bar. Unset/`false` = shown (default), `true` = hidden."),hideRecentConversations:e.boolean().optional().describe("`home` — hide the visitor's most recent conversation card. Unset/`false` = shown (default), `true` = hidden."),status:e.object({text:e.string().min(1).max(120).optional().describe("`home` — status line; an i18n key or a literal (resolved via `localizeText`). Omit to use the built-in generic `homeStatus` string (localized, no custom key needed)."),level:e.string().max(40).optional().describe("`home` — status severity, drives the status icon colour. Free text; `operational` (green, default), `degraded` (amber), and `down` (red) are styled, any other value falls back to the operational style.").meta({examples:[`operational`,`degraded`,`down`]}),url:e.string().max(2048).optional().describe(`Opens in an in-widget iframe when tapped.`)}).optional().describe("`home` — system-status card. Omit to hide."),contentBlockTitle:e.string().max(80).optional().describe("`home` — heading for the content list built from `contentTags` (default 'Popular articles').")}).loose(),se=e.array(oe).max(4).describe("Messenger tabs — an ordered list of up to 4 tabs, each picking a `layout` + optional content `contentTags` (the content scope) + a translatable `label`. One tab → no tab bar (just that content); zero → an empty state. Floating / drawer / modal only.").meta({examples:[[{label:`tabConversations`,layout:`chat`}],[{label:`tabHome`,layout:`home`,brandName:`Acme`,contentBlockTitle:`Popular articles`,contentTags:[`popular`]},{label:`tabConversations`,layout:`chat`},{label:`tabHelp`,layout:`help`,contentTags:[`help`,`guides`]},{label:`tabNews`,layout:`news`,contentTags:[`news`]}]]}),ce=e.object({enabled:e.boolean().optional().describe("Master switch. Default `true` — the widget always fires; the data module gates ingestion per deployment server-side. Set `false` to silence the client entirely."),endpoint:e.url().max(2048).optional().describe("Pixel collector URL. Default: `${dataApiBaseUrl}/pai/elements-px.gif` (e.g. `https://help.ai/api/data/pai/elements-px.gif`). Must be a full URL."),sampleRate:e.number().min(0).max(1).optional().describe("Per-visitor sampling 0..1 (decided once per page load, keeping funnels intact). Default `1`."),token:e.string().max(512).optional().describe("Anti-forgery token, echoed as `tk=` on every hit. Server-issued in the `/handshake` response — never set by hand (see `docs/api/tracking-collector.md`).")}).loose().describe(`Anonymous usage tracking for the widget owner — GA-style pixel events (open, send, form submit, …) with page / device / locale dimensions. Never includes message content; visitors are identified only by the widget's anonymous visitorId.`).meta({examples:[{enabled:!0},{enabled:!0,sampleRate:.5}]}),le=e.object({upload:e.string().min(1).max(2048).default(`/pai/upload-file`),transcribe:e.string().min(1).max(2048).default(`/pai/transcribe-audio`),submitForm:e.string().min(1).max(2048).default(`/pai/submit-form`).describe("Form submission endpoint. The widget POSTs each completed form's values here (fire-and-forget), keyed by the same visitorId + conversationId as the conversation; the payload carries `formId` + `trigger` so the backend can route. Optional — a 404 is ignored.")}).loose().describe("HTTP endpoint overrides. `upload` / `transcribe` paths are appended to the agent base (`${baseUrl}/api/agent`), `submitForm` to the data base (`dataApiBaseUrl`); absolute URLs are accepted too.").meta({examples:[{upload:`/pai/upload-file`,transcribe:`/pai/transcribe-audio`},{upload:`https://help.ai/uploads/presign`},{submitForm:`https://crm.acme.com/contacts`}]}),ue=e.object({id:e.string().min(1).max(200).optional().describe(`Host's stable id for the user — informational context the agent/backend can key on (not auth).`),email:e.string().min(1).max(320).optional().describe(`User email — surfaced to the agent for context (optional).`),name:e.string().min(1).max(200).optional().describe("Display name — shown in the Home greeting (`{name}`) and conversation transcripts (optional)."),plan:e.string().min(1).max(120).optional().describe("Subscription / pricing tier, e.g. `pro` (optional)."),role:e.string().min(1).max(120).optional().describe("The user's role on the host site, e.g. `admin` (optional)."),phone:e.string().min(1).max(40).optional().describe(`Phone number (optional).`)}).catchall(e.union([e.string(),e.number(),e.boolean()])).describe("Host-asserted end-user context (informational, untrusted — not authentication). Recognised `id` / `email` / `name` / `plan` / `role` / `phone` plus any extra custom scalar fields forwarded to the agent.").meta({examples:[{id:`u_123`},{id:`u_123`,email:`alex@acme.com`,name:`Alex Lee`,plan:`pro`}]}),de=[`home`,`docs`,`help-desk`,`support`,`pricing`,`checkout`,`orders`,`account`,`blog`],fe=e.object({area:e.string().min(1).max(64).optional().describe(`Host-defined surface the visitor is on. Free-form; suggested: ${de.join(` | `)}.`),url:e.string().min(1).max(2048).optional().describe(`Full page URL. Auto-filled from the host page when omitted.`),path:e.string().min(1).max(2048).optional().describe("Page path, e.g. `/pricing/enterprise`."),title:e.string().min(1).max(300).optional().describe(`Human-readable page title.`)}).catchall(e.union([e.string(),e.number(),e.boolean()])).describe("Host-asserted page/visit context (informational, untrusted). Where the visitor is + the surface (`area`) they're using, plus any custom scalar fields, forwarded to the agent.").meta({examples:[{area:`pricing`,path:`/pricing`},{area:`help-desk`}]}),Z=e.object({widgetId:e.string().min(1).max(80).default(`default`).describe(`Stable per-instance id used to namespace localStorage keys. Set this when mounting more than one widget on the same page so their conversation state doesn't collide.`),publicKey:e.string().min(1).max(200).optional().describe("Workspace-scoped public key (`agent_pk_…`) issued from the dashboard. Sent on every API call as the `x-public-key` header."),aiAgentDeploymentId:e.string().min(1).max(200).optional().describe("Deployment UUID from the dashboard. Picks which agent / settings bundle answers this mount. Sent as `x-ai-agent-deployment-id`."),baseUrl:e.string().min(1).max(2048).optional().describe("MAIN site origin (e.g. `https://help.ai`) — the API modules derive from it: agent API at `${baseUrl}/api/agent`, data API at `${baseUrl}/api/data`. Set this to point at your staging / self-hosted / custom backend. Default: the brand's `defaultBaseUrl` baked at build time."),agentApiBaseUrl:e.string().min(1).max(2048).optional().describe("Full agent-API base — set it to reach a STANDALONE `module-help-ai-agent-api` directly (local module on its own port, e.g. `http://localhost:3087`; routes attach as-is: `/pai/handshake`). Precedence: this option > derived from the main origin (`${baseUrl}/api/agent`). Not server-pushable."),dataApiBaseUrl:e.string().min(1).max(2048).optional().describe("Full data-API base (e.g. `https://help.ai/api/data`, or a standalone local module like `http://localhost:3106`) — the service serving content, form definitions (`GET /pai/bootstrap`), and form submissions at root-level paths. Precedence: this option > server-pushed `config.dataApiBaseUrl` > derived from the main origin (`${baseUrl}/api/data`)."),userContext:ue.optional(),pageContext:fe.optional(),endpoints:le.optional(),debug:e.union([e.boolean(),e.enum([`off`,`error`,`warn`,`info`,`debug`,`trace`])]).optional().describe('Console log verbosity. `false` / `"off"` silences everything (default in production). `true` → `"debug"`. Levels `error` / `warn` / `info` / `debug` / `trace` gate output additively. Use `"trace"` to capture per-chunk SSE frames + every state transition. Also toggleable at runtime via `chat.setDebug(level)` or `?<brand>-debug=trace` in the page URL — the URL beats this option, this option beats the persisted `localStorage` value.')}).loose().describe("Where the widget talks to and how it authenticates. Owned by the embedding developer (typically baked into the page template / env var) — distinct from `userPrefs`, which is the dashboard-pushable UX surface.").meta({examples:[{publicKey:`agent_pk_demo`,aiAgentDeploymentId:`01900000-0000-7000-8000-000000000001`},{publicKey:`agent_pk_demo`,aiAgentDeploymentId:`01900000-0000-7000-8000-000000000001`,widgetId:`support`},{publicKey:`agent_pk_demo`,aiAgentDeploymentId:`01900000-0000-7000-8000-000000000001`,baseUrl:`https://api.acme.com`}]}),Q=e.object({presentation:c.optional(),behavior:u.optional(),theme:p.default(`auto`).describe("Theme preference (`auto` follows OS) or a tokens override object (`accent`, `radius`, `fontFamily`)."),launcher:y.optional(),header:T.optional(),composer:F.optional(),feedback:k.optional(),i18n:X.optional(),footer:L.optional(),features:S.optional(),forms:q.optional(),modules:se.optional(),tracking:ce.optional()}).loose().describe("Portal-configurable widget settings — fourteen sections, one per dashboard tab. The backend pushes this same shape on `/pai/handshake` under `config`.").meta({examples:[{presentation:{mode:`floating`,position:`bottom-right`},theme:`auto`},{presentation:{mode:`floating`},theme:{accent:`#7c3aed`,radius:`12px`},launcher:{variant:`pill`,label:`Ask AI`,callout:{text:`👋 Need help?`}}},{presentation:{mode:`inline`},behavior:{responseMode:`streaming`},features:{voice:`local`}}]}),$=Z.extend({...Q.shape,site:e.unknown().optional().describe('Site config — applies in `mode: "page"`. Comes from the handshake response, not user-edited.'),blocks:e.unknown().optional().describe('Blocks (nav + link cards) — applies in `mode: "page"`. Comes from the handshake response.')}).describe("Full client widget config — connection (where + auth) + widget settings (look + behaviour) + page-mode extras. This is what the runtime parses on `mount()` / `init()`. Mode-specific constraints (e.g. `position` only meaningful in `floating`) are NOT enforced here — the runtime silently ignores irrelevant fields rather than rejecting them so the same object can flow across mode changes.").meta({examples:[{publicKey:`agent_pk_demo`,aiAgentDeploymentId:`01900000-0000-7000-8000-000000000001`,presentation:{mode:`floating`},theme:`auto`},{publicKey:`agent_pk_demo`,aiAgentDeploymentId:`01900000-0000-7000-8000-000000000001`,presentation:{mode:`modal`,size:{width:`720px`,height:`640px`}}}]}),pe=$.partial(),me=Q.partial(),he=Z.partial(),ge=Q.partial().omit({forms:!0}).extend({dataApiBaseUrl:e.string().min(1).max(2048).optional(),storageVersion:e.string().min(1).max(64).optional()}),_e=e.object({title:e.string().min(1).max(120).optional().describe(`Brand / site name. Used as the logo's alt-text fallback.`),logo:t.optional().describe(`Brand logo shown at the top of the page-mode sidebar.`),logoDark:t.optional().describe("Optional dark-theme logo variant. Falls back to `logo` when the active theme is light or `logoDark` is unset.")}).loose(),ve=e.object({navigation:e.array(n).max(100).optional().describe(`Sidebar navigation links (vertical list, primary nav).`),linkCards:e.array(n).max(100).optional().describe("Sidebar link cards (richer entries with optional `description`).")}).loose(),ye=e.object({id:e.string(),role:e.enum([`assistant`,`system`]),text:e.string()}).loose(),be=e.object({id:e.string(),label:e.string(),text:e.string().optional()}).loose(),xe=e.enum([`conflict`,`expired`,`invalid`]),Se=e.object({deployment:e.object({id:e.string(),name:e.string(),slug:e.string().optional(),publicKey:e.string().optional()}).loose(),agent:e.object({id:e.string(),name:e.string(),title:e.string().optional(),status:e.enum([`online`,`away`,`offline`]).optional()}).loose(),config:ge.optional(),site:_e.optional(),blocks:ve.optional(),welcome:e.object({messages:e.array(ye).optional(),suggestions:e.array(be).optional()}).loose().optional(),visitorId:e.string(),conversationId:e.string(),userPrefs:e.record(e.string(),e.unknown()).optional(),rebind:e.object({visitorId:xe.optional(),conversationId:xe.optional()}).loose().optional()}).loose(),Ce=[`theme`,`header`,`composer`,`footer`,`i18n`,`features`,`feedback`,`tracking`],we={floating:[`presentation`,`behavior`,`modules`,`launcher`],inline:[`presentation`,`behavior`],modal:[`presentation`,`behavior`,`modules`],drawer:[`presentation`,`behavior`,`modules`,`launcher`],page:[`presentation`],standalone:[`presentation`]};function Te(e){let t=[...we[e],...Ce],n={};for(let e of t)n[e]=!0;return Q.pick(n)}const Ee=[`floating`,`inline`,`standalone`,`page`,`modal`,`drawer`];function De(){return{$schema:`https://json-schema.org/draft/2020-12/schema`,title:`@helpai/elements config`,description:`Canonical config schemas for the embeddable AI agent elements widget.`,definitions:{WidgetConfig:e.toJSONSchema($),HandshakeResponse:e.toJSONSchema(Se)}}}export{Ee as ALL_MODES,de as PAGE_AREA_SUGGESTIONS,C as actionNameSchema,t as assetSchema,P as attachmentLimitsSchema,u as behaviorSchema,ve as blocksConfigSchema,_ as calloutPositionSchema,g as calloutShapeSchema,F as composerOptionsSchema,he as connectionConfigPartialSchema,Z as connectionConfigSchema,i as cssColorSchema,r as cssLengthSchema,De as emitJsonSchema,le as endpointsSchema,S as featureFlagsSchema,E as feedbackEventSchema,k as feedbackSchema,z as fieldOptionSchema,ie as fieldOptionTranslationSchema,R as fieldTypeSchema,B as fieldValidationSchema,L as footerSchema,U as formConditionSchema,K as formDefSchema,V as formFieldSchema,W as formFieldTranslationSchema,G as formTranslationSchema,H as formTriggerSchema,q as formsSchema,Se as handshakeResponseSchema,O as hapticsOptionsSchema,w as headerActionsSchema,T as headerSchema,X as i18nSchema,o as initialSizeSchema,v as launcherCalloutSchema,y as launcherOptionsSchema,h as launcherSizeSchema,m as launcherVariantSchema,n as linkSchema,a as localeSchema,ne as modeSchema,ae as moduleLayoutSchema,oe as moduleSchema,se as modulesSchema,fe as pageContextSchema,re as positionSchema,I as poweredBySchema,c as presentationSchema,s as resizeOptionsSchema,l as responseModeSchema,j as sendButtonIconSchema,N as sendButtonOptionsSchema,A as sendButtonShapeSchema,M as sendButtonVariantSchema,ge as serverConfigSchema,_e as siteConfigSchema,te as sizeOptionsSchema,D as soundOptionsSchema,Y as stringsOverrideSchema,p as themeFieldSchema,f as themeOverridesSchema,d as themePreferenceSchema,x as toolRefSchema,ce as trackingSchema,ue as userContextSchema,ee as uuid7Schema,b as voiceModeSchema,pe as widgetConfigPartialSchema,$ as widgetConfigSchema,me as widgetSettingsPartialSchema,Q as widgetSettingsSchema,Te as widgetSettingsSchemaForMode};
+import{z as e}from"zod";const t=e.object({url:e.string().min(1).max(2048).describe(`Public URL of the image. Must be a full URL or root-relative path.`),alt:e.string().min(1).max(200).optional().describe(`Alt text for screen readers. Omit only for purely decorative images.`)}).strict().describe(`A single image asset (logo, hero, icon).`),n=e.object({id:e.string().min(1).max(100).optional().describe(`Stable id used as Preact key + analytics target.`),label:e.string().min(1).max(120).describe(`Visible link text.`),href:e.string().min(1).max(2048).optional().describe(`Click target. Optional — when omitted the link renders as a non-clickable heading.`),icon:e.string().min(1).max(100).optional().describe(`Built-in icon preset name (chat / spark / message / help / wand) or a custom string.`),description:e.string().min(1).max(300).optional().describe(`Subtitle shown below the label. Used by link cards in page mode.`)}).loose().describe(`A navigation link / link card.`),r=e.string().min(1).max(120).describe("Any CSS length — `640px`, `80vh`, `calc(100vh - 64px)`, etc. Validated only for size, not syntax."),i=e.string().min(1).max(120).describe("Any CSS colour — hex, `rgb()`, `hsl()`, `oklch()`, a named colour, or a `var(--token)`."),a=e.string().min(1).max(35).describe("BCP-47 locale tag (e.g. `en`, `fr-CA`, `zh-Hant-HK`)."),ee=e.uuidv7().describe(`UUID v7 (RFC 9562) — the single id format for visitor / conversation / message / file / content ids.`),o=e.enum([`normal`,`expanded`,`fullscreen`,`auto`]),te=e.object({enabled:e.boolean().default(!1).describe(`Show a corner-grip handle the user can drag to resize the panel.`),minWidth:r.optional().describe(`Smallest width the user can drag the panel to.`),maxWidth:r.optional().describe(`Largest width the user can drag the panel to.`),minHeight:r.optional().describe(`Smallest height the user can drag the panel to.`),maxHeight:r.optional().describe(`Largest height the user can drag the panel to.`)}).loose().describe("Drag-resize controls. When `enabled`, a corner grip lets users resize the panel within the optional min/max bounds.").meta({examples:[{enabled:!1},{enabled:!0,minWidth:`320px`,maxWidth:`720px`,minHeight:`400px`,maxHeight:`90vh`}]}),ne=e.object({width:r.optional().describe("Panel width (CSS length). Mode-specific defaults — floating `380px`, modal `min(960px, 92vw)`, drawer `min(440px, calc(100vw - 32px))`. Set this to override; inline/standalone/page modes ignore it."),height:r.optional().describe("Panel height (CSS length). Mode-specific defaults — floating `600px`, modal `min(720px, 88vh)`, drawer `100vh` (clamped to `100vh − inset-y × 2`). Set this to override."),expanded:e.object({width:r.optional().describe(`Width when the user clicks the expand button.`),height:r.optional().describe(`Height when the user clicks the expand button.`)}).loose().optional().describe("Dimensions when the panel is in its `expanded` tier (between normal and fullscreen). Applies to floating / modal / drawer; ignored in inline / standalone / page where the panel always fills its parent."),resize:te.optional().describe(`Drag-resize controls — adds a corner grip the user can drag.`),inset:r.optional().describe("Drawer-mode edge inset — gap from each viewport edge (top/bottom/left/right). Single value applied to all four sides. Defaults to `3vh` vertical / `12px` horizontal. Use `0` for a full-edge drawer (no gap), or `5vh` for a centered-looking flyout with extra breathing room. Ignored by every other mode."),initialSize:o.default(`auto`).describe("Which size tier to open with on the first mount: `normal` / `expanded` / `fullscreen` / `auto`. Default `auto` is responsive by viewport: phones (< 640 px) open `fullscreen` edge-to-edge, tablets (640 px … `autoSizeBreakpoint`) open `normal`, and desktop/laptop (≥ `autoSizeBreakpoint`) open `expanded` — so the panel is right for the device out of the box. Set a literal to pin one tier everywhere; the user's own resize is remembered per-device and wins on reload."),autoSizeBreakpoint:e.number().int().min(0).max(1e4).default(900).describe("Viewport width (px) at/above which `initialSize: auto` opens `expanded` instead of `normal`. (Phones below 640 px always open `fullscreen`.)")}).loose().describe("Panel dimensions and drawer inset. Width/height override the mode-specific defaults (floating compact popover, modal centered dialog, drawer flyout). `inset` only affects drawer mode.").meta({examples:[{width:`420px`,height:`640px`},{width:`min(560px, 92vw)`,height:`min(640px, 90vh)`},{width:`420px`,expanded:{width:`640px`,height:`780px`},initialSize:`auto`,autoSizeBreakpoint:900},{width:`min(1100px, 95vw)`,height:`min(820px, 92vh)`},{width:`360px`,inset:`8vh`},{width:`420px`,height:`100vh`,inset:`0`},{width:`420px`,height:`60vh`,inset:`20vh`}]}),re=e.enum([`floating`,`inline`,`standalone`,`page`,`modal`,`drawer`]),ie=e.enum([`bottom-right`,`bottom-left`,`top-right`,`top-left`]),s=e.object({mode:re.default(`floating`).describe("Rendering shape. `floating` (FAB + popover), `inline` (in-flow block), `standalone` (full viewport), `page` (sidebar + chat), `modal` (centered overlay), `drawer` (side dock)."),position:ie.default(`bottom-right`).describe("Anchor corner. `floating` uses it for the FAB; `drawer` uses the `*-left` / `*-right` suffix to pick the dock side. Ignored in other modes."),iframe:e.boolean().default(!1).describe(`Wrap the widget in a same-origin iframe for stricter JS + CSS isolation from the host page. Composes with every mode.`),size:ne.optional().describe("Panel dimensions. Mode-aware defaults (floating compact popover, modal centered dialog, drawer flyout) — fields here override them. Includes `inset` (drawer flyout gap), `expanded` tier, drag-resize grip.")}).loose().describe(`Layout fundamentals — mode, anchor corner, iframe isolation, panel size + drawer inset.`).meta({examples:[{mode:`floating`,position:`bottom-right`},{mode:`modal`,size:{width:`min(1100px, 95vw)`,height:`min(820px, 92vh)`}},{mode:`drawer`,position:`bottom-right`},{mode:`drawer`,position:`top-right`,size:{width:`360px`,inset:`8vh`}},{mode:`drawer`,position:`bottom-right`,size:{width:`420px`,height:`100vh`,inset:`0`}}]}),c=e.enum([`streaming`,`buffered`]),l=e.object({startMinimized:e.boolean().default(!0).describe("Don't auto-open the floating panel on first visit. `true` (default) shows the FAB collapsed; `false` opens the panel on mount."),responseMode:c.default(`streaming`).describe("How the assistant's reply arrives. `streaming` (default) types tokens as they generate; `buffered` waits + shows the full reply at once."),showReasoning:e.boolean().default(!1).describe(`Show the model's reasoning ("thoughts") as a collapsible block above each answer. \`false\` (default) hides it — a loading indicator still shows while the model works. Reasoning is absent from durable history, but the current turn's short-lived resume backlog may replay it after an immediate reconnect or reload.`),showToolCalls:e.boolean().default(!1).describe("Show automatic tool/function calls the model makes (e.g. search) as collapsible detail+result cards in the transcript. `false` (default) hides them. Interactive tools (ask-questions / approval) always show."),showSources:e.boolean().default(!1).describe("Show the citation sources behind an answer (web links + document/file references) in the transcript. `false` (default) hides them."),disableMessageFeedback:e.boolean().default(!1).describe("Turn OFF the 👍/👎 feedback controls under each rateable reply (AI or operator). Unset/`false` = shown (default), `true` = hidden. A choice fires the `messageFeedback` event and is POSTed best-effort to `/pai/message-feedback`."),autoSendSuggestions:e.boolean().default(!1).describe("Auto-send a suggestion chip's text the moment it's tapped. `false` (default) fills the composer with the text so the visitor can edit before sending; `true` sends it immediately.")}).loose().describe(`Conversation behaviour — lifecycle, streaming, and the transcript surface (scroll, feedback).`).meta({examples:[{startMinimized:!0,responseMode:`streaming`},{startMinimized:!1,responseMode:`buffered`,disableMessageFeedback:!0}]}),u=e.enum([`auto`,`light`,`dark`]),ae=e.object({accent:i.optional().describe(`Brand accent colour. Drives the FAB, send button, links, and active states. CSS colour.`),accentText:i.optional().describe(`Foreground colour rendered ON the accent (FAB icon, send-button glyph). CSS colour.`),radius:r.optional().describe("Corner radius for the panel + buttons. CSS length (`8px`, `0.75rem`, `12px`)."),fontFamily:e.string().min(1).max(200).optional().describe("Font stack used inside the widget. Standard CSS `font-family` value."),contentMaxWidth:r.optional().describe("Max width of the readable content column (messages, history, home, composer) on a wide surface — content centres, full-bleed bars keep their edges. CSS length; default `768px`. Set `100%` to fill the surface (no cap). Modal + drawer already fill their card by default.")}).loose().describe(`Theme token overrides. Any field left unset falls through to the brand's default theme.`).meta({examples:[{accent:`#10b981`,radius:`12px`},{accent:`#7c3aed`,accentText:`#ffffff`,radius:`16px`,fontFamily:`'Inter', system-ui`},{accent:`oklch(0.7 0.2 145)`,radius:`0.5rem`},{accent:`#5b5bd6`,contentMaxWidth:`960px`}]}),d=e.union([u,ae]).describe(`'auto' | 'light' | 'dark', or a tokens override object.`).meta({examples:[`auto`,`dark`,{accent:`#10b981`,radius:`12px`},{accent:`#7c3aed`,accentText:`#fff`,radius:`16px`,fontFamily:`'Inter', system-ui`}]}),f=e.enum([`circle`,`pill`,`bar`,`minimal`]),p=e.enum([`sm`,`md`,`lg`]),m=e.enum([`pill`,`bubble`,`callout`]),h=e.enum([`auto`,`horizontal`,`vertical`]),g=e.object({text:e.string().min(1).max(500).default(`👋 Hi! Need any help?`).describe("The message to show in the bubble. Defaults to a friendly greeting; replace with your own copy (e.g. 'Click here →'). May also be an i18n key (e.g. `launcherCallout`) resolved against `i18n.strings` for per-locale copy; a non-key literal renders as-is."),shape:m.default(`pill`).describe("Visual shape — `pill` (slim label + arrow), `bubble` (speech-bubble tail), `callout` (loud variant)."),position:h.default(`auto`).describe("Where the bubble sits relative to the FAB. `auto` (default) picks the side facing into the page. `horizontal` anchors beside the FAB (left/right depending on the FAB's corner). `vertical` anchors above/below the FAB. Concrete left/right/top/bottom is derived from the FAB's corner so the bubble always stays on-screen."),delayMs:e.number().int().min(0).max(6e4).default(1200).describe(`How long to wait after page load before the bubble appears, in milliseconds.`),autoDismissMs:e.number().int().min(0).max(6e5).default(0).describe("Auto-hide the bubble after this many milliseconds. `0` (default) keeps it until the user dismisses."),animated:e.boolean().default(!0).describe("Subtle horizontal nudge to draw the eye. Disabled automatically by `prefers-reduced-motion`."),persistent:e.boolean().default(!0).describe("How dismissals stick. `true` (default) — re-show on every visit regardless of prior dismissal (the 'recurring greeting' behaviour). `false` — clicking X stores the message text and that exact message stays hidden across visits (the 'one-time hint' behaviour).")}).loose().describe(`Pre-engagement message bubble next to the FAB. Use it for a greeting ('Hi, need help?'), an attention-grabbing nudge ('Click here →'), or any one-time onboarding tip — same component, configured for the use case.`),_=e.object({variant:f.default(`circle`).describe("FAB visual style. `circle` — round bubble (icon only). `pill` — icon + label. `bar` — wide rectangular button. `minimal` — text-only outline."),size:p.default(`md`).describe(`FAB size preset — small / medium / large.`),label:e.string().max(200).optional().describe("Text rendered on the FAB (only shown for `pill` / `bar` / `minimal` variants)."),icon:e.string().max(8e3).optional().describe("Icon shown on the FAB / drawer edge tab. Built-in presets: `chat` / `message` / `bubbles` / `spark` / `wand` / `bot` / `help` / `lifebuoy` / `headset`. Anything else is treated as raw SVG."),hidden:e.boolean().default(!1).describe("Hide the FAB entirely (page brings its own trigger that calls `instance.open()`)."),callout:g.optional()}).loose().describe(`Floating-launcher (FAB) appearance and behaviour. The FAB is the round button in the corner that opens the chat panel. Floating mode only.`).meta({examples:[{variant:`circle`,size:`md`},{variant:`pill`,label:`Ask AI`,icon:`spark`},{variant:`circle`,callout:{text:`👋 Need help?`,shape:`bubble`,persistent:!0}},{variant:`circle`,callout:{text:`Click to start`,shape:`pill`,delayMs:1200}}]}),v=e.enum([`local`,`server`,`disabled`]),y=e.object({disableFileUpload:e.boolean().default(!1).describe("Turn OFF file uploads — hide the paperclip button + reject drag/drop/paste. Unset/`false` = enabled (default), `true` = disabled."),voice:v.default(`local`).describe("Voice input mode. `local` — Web Speech API in the browser (free, runs on-device). `server` — record audio + upload to the transcribe endpoint. `disabled` — hide the mic button."),disableHumanInLoop:e.boolean().default(!1).describe("Turn OFF the human-in-the-loop tool UI — the inline ask-questions form + approve/reject controls for gated tools. Unset/`false` = shown (default), `true` = suppressed (the wire still carries the signals)."),enableOperatorRequest:e.boolean().default(!1).describe("Opt IN operator control — expose the 'Talk to an operator' affordance + connected-to-operator states for this deployment. Unset/`false` = off (default), `true` = on. Unlike the `disable*` flags this is a positive opt-in for a new capability.")}).loose().describe(`Capability flags — file upload, voice mode, HITL, and operator requests.`).meta({examples:[{voice:`local`},{disableFileUpload:!0,voice:`disabled`},{voice:`server`,enableOperatorRequest:!0}]}),b=e.enum([`clear`,`expand`,`fullscreen`,`sound`,`history`,`language`,`theme`,`textSize`,`close`]),x=e.array(b).max(10).describe("Which actions the header exposes. `history` + `close` are dedicated buttons; the rest appear in the ⋯ menu. Unlisted actions are hidden; order is irrelevant. Pick from: `clear`, `expand`, `fullscreen`, `sound`, `history`, `language`, `theme`, `textSize`, `close`. Per-mode defaults live in `DEFAULT_ACTIONS_BY_MODE`.").meta({examples:[[`theme`,`history`,`close`,`clear`,`fullscreen`,`sound`,`language`],[`theme`,`history`,`clear`,`language`],[`close`]]}),S=e.object({actions:x.optional().describe(`Which header actions are enabled (history/✕ buttons + ⋯ menu).`)}).loose().describe(`Panel-header configuration.`).meta({examples:[{actions:[`theme`,`history`,`close`,`clear`,`fullscreen`]}]}),C=e.enum([`messageReceived`,`messageSent`,`error`,`voiceStart`,`voiceStop`]),w=e.object({enabled:e.boolean().default(!0).describe(`Master on/off for audible notifications. On by default — browser autoplay policy still requires a prior user gesture before any sound plays.`),volume:e.number().min(0).max(1).default(.3).describe("Global volume 0..1. `0.3` (default) is intentionally subtle."),events:e.partialRecord(C,e.union([e.boolean(),e.string().min(1).max(2048)])).optional().describe("Per-event override map. Value: `true` = built-in tone, `false` = silent, `string` = URL to a custom audio file (mp3/wav/ogg).")}).loose().describe("Audible notifications. `events` accepts true (default tone), false (off), or a URL to an audio file.").meta({examples:[{enabled:!0,volume:.3},{enabled:!0,volume:.5,events:{messageReceived:!0,error:!1}},{enabled:!0,events:{messageReceived:`https://cdn.help.ai/ping.mp3`}}]}),T=e.object({enabled:e.boolean().default(!0).describe(`Master on/off. Default: on for touch devices, silently ignored elsewhere.`),events:e.partialRecord(C,e.union([e.boolean(),e.number().int(),e.array(e.number().int())])).optional().describe("Per-event vibration pattern. Value: `true` = default pattern, `false` = silent, number = single vibrate ms, array = `[vibrate, pause, vibrate, …]`.")}).loose().describe("Touch-device vibration. `events` accepts true (default), number (single vibrate ms), or [vibrate,pause,vibrate,…].").meta({examples:[{enabled:!0},{enabled:!0,events:{messageReceived:30,error:[40,60,40]}}]}),E=e.object({sound:w.optional(),haptics:T.optional()}).loose().describe(`Audible + tactile feedback.`).meta({examples:[{sound:{enabled:!0,volume:.3},haptics:{enabled:!0}},{sound:{enabled:!1},haptics:{enabled:!1}}]}),D=e.enum([`circle`,`square`,`pill`]),O=e.enum([`arrowUp`,`paperPlane`,`send`,`chevron`]),k=e.enum([`filled`,`outline`,`ghost`]),A=e.object({shape:D.default(`circle`).describe("Send button outline shape — `circle` / `square` / `pill`."),icon:O.default(`arrowUp`).describe("Icon inside the send button — `arrowUp` / `paperPlane` / `send` / `chevron`."),variant:k.default(`filled`).describe("Fill treatment — `filled` (solid accent), `outline` (border only), `ghost` (no border, no fill).")}).loose().describe(`Send-button styling — shape, icon, and fill treatment.`).meta({examples:[{shape:`circle`,icon:`arrowUp`,variant:`filled`},{shape:`pill`,icon:`send`,variant:`outline`},{shape:`square`,icon:`paperPlane`,variant:`ghost`}]}),j=e.object({maxBytes:e.number().int().min(0).max(1024*1024*1024).default(10*1024*1024).describe("Maximum size per uploaded file, in bytes. `10 MiB` (10485760) by default."),maxCount:e.number().int().min(0).max(100).default(10).describe(`Maximum number of attachments per message.`),accept:e.string().max(2e3).default(`*/*`).describe("Allowed MIME types — comma-separated `accept` attribute string, e.g. `image/*,application/pdf`.")}).loose().describe(`Client-side attachment limits. Server enforcement is still required.`).meta({examples:[{maxBytes:10485760,maxCount:10,accept:`*/*`},{maxBytes:5242880,maxCount:3,accept:`image/*,application/pdf`}]}),M=e.object({sendButton:A.optional(),attachments:j.optional()}).loose().describe(`Composer chrome — send-button styling + attachment limits.`).meta({examples:[{sendButton:{shape:`circle`,icon:`arrowUp`,variant:`filled`}},{sendButton:{shape:`pill`,icon:`send`,variant:`outline`}},{attachments:{maxBytes:5242880,maxCount:3,accept:`image/*,application/pdf`}}]}),N=e.object({text:e.string().max(200).optional().describe("Visible attribution text (e.g. `Powered by Help AI`)."),href:e.url().max(2048).optional().describe("Click target — the attribution becomes a link. Must be a full URL (`https://…`)."),logoUrl:e.url().max(2048).optional().describe(`Small logo rendered before the text. Must be a full URL.`)}).loose().describe(`"Powered by …" attribution shown below the composer.`).meta({examples:[{text:`Powered by Help AI`},{text:`Powered by Help AI`,href:`https://help.ai`,logoUrl:`https://help.ai/logo.svg`}]}),P=e.object({poweredBy:N.optional(),composerDisclaimer:e.string().max(500).optional().describe(`Small muted text under the composer (like ChatGPT's 'ChatGPT can make mistakes.'). Empty = hidden.`)}).loose().describe(`Footer — attribution + composer disclaimer.`).meta({examples:[{poweredBy:{text:`Powered by Help AI`,href:`https://help.ai`}},{composerDisclaimer:`AI responses may be inaccurate.`}]}),F=e.enum([`text`,`email`,`tel`,`url`,`number`,`date`,`time`,`textarea`,`select`,`radio`,`checkbox`,`multiselect`]),I=e.object({value:e.string().min(1).max(200).describe(`The value recorded when this choice is picked.`),label:e.string().min(1).max(200).optional().describe("Display text; falls back to `value`."),description:e.string().max(280).optional().describe(`Optional sub-label under the choice.`)}).loose(),L=e.object({pattern:e.string().max(500).optional().describe("Regex source string — text-like fields (e.g. `^\\d{5}$`)."),minLength:e.number().int().min(0).max(1e4).optional(),maxLength:e.number().int().min(1).max(1e4).optional(),min:e.number().optional().describe("Minimum — `number` fields."),max:e.number().optional().describe("Maximum — `number` fields."),minSelections:e.number().int().min(0).max(50).optional().describe("Minimum picks — `multiselect`."),maxSelections:e.number().int().min(1).max(50).optional().describe("Maximum picks — `multiselect`.")}).loose(),R=e.object({name:e.string().min(1).max(80).describe("Stable key the answer is recorded under (e.g. `email`)."),label:e.string().min(1).max(200).describe(`Visible field label.`),type:F.describe(`Field renderer + built-in validation (email/tel/url/number/date/time checked).`),placeholder:e.string().max(200).optional(),required:e.boolean().optional().default(!0).describe("Must be answered to submit. `false` allows skipping."),defaultValue:e.string().max(2e3).optional().describe("Pre-filled value (comma-join for `multiselect`)."),options:e.array(I).max(50).optional().describe("Choices for `select` / `radio` / `multiselect`."),validation:L.optional(),allowOther:e.boolean().optional().describe("`select`/`radio`/`multiselect` — allow a free-text 'Other' answer."),validationHint:e.string().max(280).optional().describe(`Small helper line under the field.`)}).loose(),z=e.string().regex(/^(pre-chat|conversation-closed|panel-close|manual|after-messages:\d+|idle:\d+|page-area:.+)$/,`Unrecognised form trigger`).describe("When the form fires: `pre-chat`, `after-messages:N`, `conversation-closed`, `panel-close`, `idle:Nseconds`, `page-area:<area>`, or `manual`."),B=e.object({missingContext:e.array(e.string().max(80)).max(20).optional().describe("Only show if `userContext` lacks ALL of these keys (progressive profiling)."),pageArea:e.union([e.string().max(64),e.array(e.string().max(64)).max(20)]).optional().describe("Only on these `pageContext.area` values."),minMessages:e.number().int().min(0).max(1e3).optional(),maxMessages:e.number().int().min(0).max(1e3).optional()}).loose(),V=e.object({value:e.string().min(1).max(200).describe("The canonical option `value` this localizes."),label:e.string().min(1).max(200).optional(),description:e.string().max(280).optional()}).loose(),H=e.object({name:e.string().min(1).max(80).describe("The canonical field `name` this localizes."),label:e.string().min(1).max(200).optional(),placeholder:e.string().max(200).optional(),validationHint:e.string().max(280).optional(),options:e.array(V).max(50).optional()}).loose(),U=e.object({locale:a,title:e.string().max(120).optional(),description:e.string().max(500).optional(),submitLabel:e.string().max(60).optional(),fields:e.array(H).max(50).optional()}).loose(),W=e.object({id:e.string().min(1).max(80).describe("Stable id — persistence dedupe + `manual` openForm(id)."),on:e.union([z,e.array(z).min(1).max(8)]).describe(`Trigger(s) that surface this form.`),when:B.optional().describe(`Extra eligibility predicate evaluated when a trigger fires.`),fields:e.array(R).max(20).default([]).describe(`The questions, in order. ≥1 required to show.`),title:e.string().max(120).optional(),description:e.string().max(500).optional(),submitLabel:e.string().max(60).optional(),skippable:e.boolean().default(!1).describe(`Show a Skip control so the visitor can dismiss the form.`),frequency:e.enum([`once`,`conversation`,`always`]).default(`once`).describe("`once` (per device, persisted), `conversation` (re-eligible each new conversation), or `always`."),mirrorToContext:e.boolean().default(!0).describe("Mirror the answers into `userContext` so they ride every request. Set `false` for PII (DOB, policy #, symptoms) — those then go only to the submit endpoint."),reopenable:e.boolean().default(!0).describe('Skipped marker offers a "Fill out" button that reopens the form. Set `false` when a skip must be final (e.g. a consent ask that should not be re-surfaced).'),reviewable:e.boolean().default(!0).describe("Submitted marker expands in place to a read-only list of the visitor's answers. Set `false` for sensitive answers that shouldn't linger on screen."),defaultLocale:a.optional().describe(`BCP-47 locale the top-level strings (title / fields copy) are authored in.`),translations:e.array(U).max(50).optional().describe("Per-locale string overrides — the data module trims to the bootstrap `?locale=` (≤1); the widget overlays it onto the default copy.")}).loose(),G=e.array(W).max(20).describe("Event-driven forms — an ordered list (order = priority). Each binds to trigger event(s), gates the chat until submit/skip, dedupes by frequency, and records via `endpoints.submitForm`. Generic across verticals.").meta({examples:[[{id:`intake`,on:`pre-chat`,fields:[{name:`email`,label:`Email`,type:`email`}]}],[{id:`signal`,on:`pre-chat`,title:`Before we start`,fields:[{name:`name`,label:`Your name`,type:`text`},{name:`email`,label:`Work email`,type:`email`}]},{id:`csat`,on:`conversation-closed`,frequency:`always`,fields:[{name:`rating`,label:`How did we do?`,type:`radio`,options:[{value:`good`},{value:`bad`}]}]},{id:`appointment`,on:[`page-area:booking`,`manual`],mirrorToContext:!1,fields:[{name:`department`,label:`Department`,type:`select`,options:[{value:`dermatology`},{value:`cardiology`}]},{name:`date`,label:`Preferred date`,type:`date`},{name:`consent`,label:`I consent to be contacted`,type:`checkbox`}]}]]}),K=e.record(e.string(),e.string()),q=e.union([K,e.record(a,K)]).describe(`Per-instance UI string overrides. Flat = active-locale only; nested = multi-locale map. Both forms are partial — missing keys fall through to built-in defaults.`).meta({examples:[{send:`Click`,stop:`Halt`,composerPlaceholder:`Type your question…`},{en:{send:`Send`,composerPlaceholder:`Type a message…`},fr:{send:`Envoyer`,composerPlaceholder:`Tapez un message…`}}]}),J=e.object({locale:a.optional().describe("BCP-47 locale tag forced for this widget instance (e.g. `fr-CA`). Page-owner explicit override."),defaultLocale:e.union([e.literal(`auto`),a]).default(`auto`).describe("Initial / fallback locale for users who haven't picked one. `auto` sniffs `navigator.language`."),availableLocales:e.array(a).max(200).optional().describe(`BCP-47 locale tags shown in the runtime language switcher. Hidden when fewer than 2 entries.`),strings:q.optional()}).loose().describe(`Locale + i18n overrides.`).meta({examples:[{defaultLocale:`auto`},{defaultLocale:`en`,availableLocales:[`en`,`fr`,`de`]},{locale:`fr-CA`,strings:{send:`Envoyer`}}]}),Y=e.enum([`chat`,`home`,`help`,`news`]),oe=e.object({label:e.string().min(1).max(40).describe("Tab label — an i18n key (resolved against the i18n strings, e.g. `tabHome`) or a literal. Translations ride `i18n.strings`."),layout:Y.describe("UI layout that renders this tab: `chat` (the conversation), `home`, `help`, or `news`."),contentTags:e.array(e.string().max(60)).max(20).optional().describe("Content tags this tab scopes to — the `tags` filter on `GET /content` (matches content tagged with ANY of them). Omit for the `chat` layout."),id:e.string().max(60).optional().describe("Stable id for navigation + last-tab persistence. Defaults to the first `contentTags` entry, else `layout`."),brandName:e.string().max(80).optional().describe("`home` — hero wordmark (e.g. your company name)."),hideGreeting:e.boolean().optional().describe("`home` — hide the greeting hero. Unset/`false` = shown (default), `true` = hidden."),greetingText:e.string().max(280).optional().describe("`home` — override the greeting headline (default 'How can we help?'); supports a `{name}` token."),userAvatars:e.array(e.object({name:e.string().min(1).max(80),avatar:e.string().max(2048).optional().describe("Image URL; falls back to initials of `name`."),role:e.string().max(80).optional()}).loose()).max(10).optional().describe("`home` — team/agent avatars shown in the hero."),hideSearchBar:e.boolean().optional().describe("`home` — hide the 'Search for help' bar. Unset/`false` = shown (default), `true` = hidden."),hideRecentConversations:e.boolean().optional().describe("`home` — hide the visitor's most recent conversation card. Unset/`false` = shown (default), `true` = hidden."),status:e.object({text:e.string().min(1).max(120).optional().describe("`home` — status line; an i18n key or a literal (resolved via `localizeText`). Omit to use the built-in generic `homeStatus` string (localized, no custom key needed)."),level:e.string().max(40).optional().describe("`home` — status severity, drives the status icon colour. Free text; `operational` (green, default), `degraded` (amber), and `down` (red) are styled, any other value falls back to the operational style.").meta({examples:[`operational`,`degraded`,`down`]}),url:e.string().max(2048).optional().describe(`Opens in an in-widget iframe when tapped.`)}).optional().describe("`home` — system-status card. Omit to hide."),contentBlockTitle:e.string().max(80).optional().describe("`home` — heading for the content list built from `contentTags` (default 'Popular articles').")}).loose(),se=e.array(oe).max(4).describe("Messenger tabs — an ordered list of up to 4 tabs, each picking a `layout` + optional content `contentTags` (the content scope) + a translatable `label`. One tab → no tab bar (just that content); zero → an empty state. Floating / drawer / modal only.").meta({examples:[[{label:`tabConversations`,layout:`chat`}],[{label:`tabHome`,layout:`home`,brandName:`Acme`,contentBlockTitle:`Popular articles`,contentTags:[`popular`]},{label:`tabConversations`,layout:`chat`},{label:`tabHelp`,layout:`help`,contentTags:[`help`,`guides`]},{label:`tabNews`,layout:`news`,contentTags:[`news`]}]]}),ce=e.object({enabled:e.boolean().optional().describe("Master switch. Default `true` — the widget always fires; the data module gates ingestion per deployment server-side. Set `false` to silence the client entirely."),endpoint:e.url().max(2048).optional().describe("Pixel collector URL. Default: `${dataApiBaseUrl}/pai/elements-px.gif` (e.g. `https://help.ai/api/data/pai/elements-px.gif`). Must be a full URL."),sampleRate:e.number().min(0).max(1).optional().describe("Per-widget-runtime sampling 0..1 (one decision per mounted runtime, keeping that runtime's funnel intact). Default `1`."),token:e.string().max(512).optional().describe("Anti-forgery token, echoed as `tk=` on every hit. Server-issued in the `/handshake` response — never set by hand (see `docs/api/tracking-collector.md`).")}).loose().describe(`Anonymous usage tracking for the widget owner — GA-style pixel events (open, send, form submit, …) with page / device / locale dimensions. Never includes message or form content; the only visitor identifier is the widget's anonymous visitorId.`).meta({examples:[{enabled:!0},{enabled:!0,sampleRate:.5}]}),le=e.object({upload:e.string().min(1).max(2048).default(`/pai/upload-file`),transcribe:e.string().min(1).max(2048).default(`/pai/transcribe-audio`),submitForm:e.string().min(1).max(2048).default(`/pai/submit-form`).describe("Form submission endpoint. The widget POSTs each completed form's values here (fire-and-forget), keyed by the same visitorId + conversationId as the conversation; the payload carries `formId` + `trigger` so the backend can route. Optional — a 404 is ignored.")}).loose().describe("HTTP endpoint overrides. `upload` / `transcribe` paths are appended to the agent base (`${baseUrl}/api/agent`), `submitForm` to the data base (`dataApiBaseUrl`); absolute URLs are accepted too.").meta({examples:[{upload:`/pai/upload-file`,transcribe:`/pai/transcribe-audio`},{upload:`https://help.ai/uploads/presign`},{submitForm:`https://crm.acme.com/contacts`}]}),ue=e.object({id:e.string().min(1).max(200).optional().describe(`Host's stable id for the user — informational context the agent/backend can key on (not auth).`),email:e.string().min(1).max(320).optional().describe(`User email — surfaced to the agent for context (optional).`),name:e.string().min(1).max(200).optional().describe("Display name — shown in the Home greeting (`{name}`) and conversation transcripts (optional)."),plan:e.string().min(1).max(120).optional().describe("Subscription / pricing tier, e.g. `pro` (optional)."),role:e.string().min(1).max(120).optional().describe("The user's role on the host site, e.g. `admin` (optional)."),phone:e.string().min(1).max(40).optional().describe(`Phone number (optional).`)}).catchall(e.union([e.string(),e.number(),e.boolean()])).describe("Host-asserted end-user context (informational, untrusted — not authentication). Recognised `id` / `email` / `name` / `plan` / `role` / `phone` plus any extra custom scalar fields forwarded to the agent.").meta({examples:[{id:`u_123`},{id:`u_123`,email:`alex@acme.com`,name:`Alex Lee`,plan:`pro`}]}),de=[`home`,`docs`,`help-desk`,`support`,`pricing`,`checkout`,`orders`,`account`,`blog`],fe=e.object({area:e.string().min(1).max(64).optional().describe(`Host-defined surface the visitor is on. Free-form; suggested: ${de.join(` | `)}.`),url:e.string().min(1).max(2048).optional().describe(`Full page URL. Auto-filled from the host page when omitted.`),path:e.string().min(1).max(2048).optional().describe("Page path, e.g. `/pricing/enterprise`."),title:e.string().min(1).max(300).optional().describe(`Human-readable page title.`)}).catchall(e.union([e.string(),e.number(),e.boolean()])).describe("Host-asserted page/visit context (informational, untrusted). Where the visitor is + the surface (`area`) they're using, plus any custom scalar fields, forwarded to the agent.").meta({examples:[{area:`pricing`,path:`/pricing`},{area:`help-desk`}]}),X=e.object({widgetId:e.string().min(1).max(80).default(`default`).describe(`Stable per-instance id used to namespace localStorage keys. Set this when mounting more than one widget on the same page so their conversation state doesn't collide.`),publicKey:e.string().min(1).max(200).optional().describe("Workspace-scoped public key (`agent_pk_…`) issued from the dashboard. Sent on every API call as the `x-public-key` header."),aiAgentDeploymentId:e.string().min(1).max(200).optional().describe("Deployment UUID from the dashboard. Picks which agent / settings bundle answers this mount. Sent as `x-ai-agent-deployment-id`."),baseUrl:e.string().min(1).max(2048).optional().describe("MAIN site origin (e.g. `https://help.ai`) — the API modules derive from it: agent API at `${baseUrl}/api/agent`, data API at `${baseUrl}/api/data`. Set this to point at your staging / self-hosted / custom backend. Default: the brand's `defaultBaseUrl` baked at build time."),agentApiBaseUrl:e.string().min(1).max(2048).optional().describe("Full agent-API base — set it to reach a STANDALONE `module-help-ai-agent-api` directly (local module on its own port, e.g. `http://localhost:3087`; routes attach as-is: `/pai/handshake`). Precedence: this option > derived from the main origin (`${baseUrl}/api/agent`). Not server-pushable."),dataApiBaseUrl:e.string().min(1).max(2048).optional().describe("Full data-API base (e.g. `https://help.ai/api/data`, or a standalone local module like `http://localhost:3106`) — the service serving content, form definitions (`GET /pai/bootstrap`), and form submissions at root-level paths. Precedence: this option > server-pushed `config.dataApiBaseUrl` > derived from the main origin (`${baseUrl}/api/data`)."),userContext:ue.optional(),pageContext:fe.optional(),endpoints:le.optional(),debug:e.union([e.boolean(),e.enum([`off`,`error`,`warn`,`info`,`debug`,`trace`])]).optional().describe('Console log verbosity. `false` / `"off"` silences everything (default in production). `true` → `"debug"`. Levels `error` / `warn` / `info` / `debug` / `trace` gate output additively. Use `"trace"` to capture per-chunk SSE frames + every state transition. Also toggleable at runtime via `chat.setDebug(level)` or `?<brand>-debug=trace` in the page URL — the URL beats this option, this option beats the persisted `localStorage` value.')}).loose().describe("Where the widget talks to and how it authenticates. Owned by the embedding developer (typically baked into the page template / env var) — distinct from `userPrefs`, which is the dashboard-pushable UX surface.").meta({examples:[{publicKey:`agent_pk_demo`,aiAgentDeploymentId:`01900000-0000-7000-8000-000000000001`},{publicKey:`agent_pk_demo`,aiAgentDeploymentId:`01900000-0000-7000-8000-000000000001`,widgetId:`support`},{publicKey:`agent_pk_demo`,aiAgentDeploymentId:`01900000-0000-7000-8000-000000000001`,baseUrl:`https://api.acme.com`}]}),Z=e.object({presentation:s.optional(),behavior:l.optional(),theme:d.default(`auto`).describe("Theme preference (`auto` follows OS) or a tokens override object (`accent`, `radius`, `fontFamily`)."),launcher:_.optional(),header:S.optional(),composer:M.optional(),feedback:E.optional(),i18n:J.optional(),footer:P.optional(),features:y.optional(),forms:G.optional(),modules:se.optional(),tracking:ce.optional()}).loose().describe("Portal-configurable widget settings — thirteen sections, one per dashboard tab. The backend pushes this shape on `/pai/handshake` under `config`, except `forms`, which the data API serves separately.").meta({examples:[{presentation:{mode:`floating`,position:`bottom-right`},theme:`auto`},{presentation:{mode:`floating`},theme:{accent:`#7c3aed`,radius:`12px`},launcher:{variant:`pill`,label:`Ask AI`,callout:{text:`👋 Need help?`}}},{presentation:{mode:`inline`},behavior:{responseMode:`streaming`},features:{voice:`local`}}]}),Q=X.extend({...Z.shape,site:e.unknown().optional().describe('Site config — applies in `mode: "page"`. Comes from the handshake response, not user-edited.'),blocks:e.unknown().optional().describe('Blocks (nav + link cards) — applies in `mode: "page"`. Comes from the handshake response.')}).describe("Full tooling config — connection (where + auth) + widget settings (look + behaviour) + page-mode handshake extras. The production widget does not import this Zod schema. Mode-specific constraints (e.g. `position` only meaningful in `floating`) are NOT enforced here so the same object can flow across mode changes.").meta({examples:[{publicKey:`agent_pk_demo`,aiAgentDeploymentId:`01900000-0000-7000-8000-000000000001`,presentation:{mode:`floating`},theme:`auto`},{publicKey:`agent_pk_demo`,aiAgentDeploymentId:`01900000-0000-7000-8000-000000000001`,presentation:{mode:`modal`,size:{width:`720px`,height:`640px`}}}]}),pe=Q.partial(),me=Z.partial(),he=X.partial(),ge=Z.partial().omit({forms:!0}).extend({dataApiBaseUrl:e.string().min(1).max(2048).optional(),storageVersion:e.string().min(1).max(64).optional()}),$=e.object({title:e.string().min(1).max(120).optional().describe(`Brand / site name. Used as the logo's alt-text fallback.`),logo:t.optional().describe(`Brand logo shown at the top of the page-mode sidebar.`),logoDark:t.optional().describe("Optional dark-theme logo variant. Falls back to `logo` when the active theme is light or `logoDark` is unset.")}).loose(),_e=e.object({navigation:e.array(n).max(100).optional().describe(`Sidebar navigation links (vertical list, primary nav).`),linkCards:e.array(n).max(100).optional().describe("Sidebar link cards (richer entries with optional `description`).")}).loose(),ve=e.object({id:e.string(),role:e.enum([`assistant`,`system`]),text:e.string()}).loose(),ye=e.object({id:e.string(),label:e.string(),text:e.string().optional()}).loose(),be=e.enum([`conflict`,`expired`,`invalid`]),xe=e.object({deployment:e.object({id:e.string(),name:e.string(),slug:e.string().optional(),publicKey:e.string().optional()}).loose(),agent:e.object({id:e.string(),name:e.string(),title:e.string().optional(),status:e.enum([`online`,`away`,`offline`]).optional()}).loose(),config:ge.optional(),site:$.optional(),blocks:_e.optional(),welcome:e.object({messages:e.array(ve).optional(),suggestions:e.array(ye).optional()}).loose().optional(),visitorId:e.string(),conversationId:e.string(),userPrefs:e.record(e.string(),e.unknown()).optional(),rebind:e.object({visitorId:be.optional(),conversationId:be.optional()}).loose().optional()}).loose(),Se=[`theme`,`header`,`composer`,`footer`,`i18n`,`features`,`feedback`,`tracking`],Ce={floating:[`presentation`,`behavior`,`modules`,`launcher`],inline:[`presentation`,`behavior`],modal:[`presentation`,`behavior`,`modules`],drawer:[`presentation`,`behavior`,`modules`,`launcher`],page:[`presentation`],standalone:[`presentation`]};function we(e){let t=[...Ce[e],...Se],n={};for(let e of t)n[e]=!0;return Z.pick(n)}const Te=[`floating`,`inline`,`standalone`,`page`,`modal`,`drawer`];function Ee(){return{$schema:`https://json-schema.org/draft/2020-12/schema`,title:`@helpai/elements config`,description:`Canonical config schemas for the embeddable AI agent elements widget.`,definitions:{WidgetConfig:e.toJSONSchema(Q),HandshakeResponse:e.toJSONSchema(xe)}}}export{Te as ALL_MODES,de as PAGE_AREA_SUGGESTIONS,b as actionNameSchema,t as assetSchema,j as attachmentLimitsSchema,l as behaviorSchema,_e as blocksConfigSchema,h as calloutPositionSchema,m as calloutShapeSchema,M as composerOptionsSchema,he as connectionConfigPartialSchema,X as connectionConfigSchema,i as cssColorSchema,r as cssLengthSchema,Ee as emitJsonSchema,le as endpointsSchema,y as featureFlagsSchema,C as feedbackEventSchema,E as feedbackSchema,I as fieldOptionSchema,V as fieldOptionTranslationSchema,F as fieldTypeSchema,L as fieldValidationSchema,P as footerSchema,B as formConditionSchema,W as formDefSchema,R as formFieldSchema,H as formFieldTranslationSchema,U as formTranslationSchema,z as formTriggerSchema,G as formsSchema,xe as handshakeResponseSchema,T as hapticsOptionsSchema,x as headerActionsSchema,S as headerSchema,J as i18nSchema,o as initialSizeSchema,g as launcherCalloutSchema,_ as launcherOptionsSchema,p as launcherSizeSchema,f as launcherVariantSchema,n as linkSchema,a as localeSchema,re as modeSchema,Y as moduleLayoutSchema,oe as moduleSchema,se as modulesSchema,fe as pageContextSchema,ie as positionSchema,N as poweredBySchema,s as presentationSchema,te as resizeOptionsSchema,c as responseModeSchema,O as sendButtonIconSchema,A as sendButtonOptionsSchema,D as sendButtonShapeSchema,k as sendButtonVariantSchema,ge as serverConfigSchema,$ as siteConfigSchema,ne as sizeOptionsSchema,w as soundOptionsSchema,q as stringsOverrideSchema,d as themeFieldSchema,ae as themeOverridesSchema,u as themePreferenceSchema,ce as trackingSchema,ue as userContextSchema,ee as uuid7Schema,v as voiceModeSchema,pe as widgetConfigPartialSchema,Q as widgetConfigSchema,me as widgetSettingsPartialSchema,Z as widgetSettingsSchema,we as widgetSettingsSchemaForMode};
 //# sourceMappingURL=schema.mjs.map