@helpai/elements 1.12.6 → 1.12.8

package/schema.d.ts

@@ -634,6 +634,7 @@ export declare const formDefSchema: z.ZodObject<{
   description: z.ZodOptional<z.ZodString>;
   submitLabel: z.ZodOptional<z.ZodString>;
   skippable: z.ZodDefault<z.ZodBoolean>;
+  blocking: z.ZodDefault<z.ZodBoolean>;
   frequency: z.ZodDefault<z.ZodEnum<{
     always: "always";
     conversation: "conversation";
@@ -712,6 +713,7 @@ export declare const formsSchema: z.ZodArray<z.ZodObject<{
   description: z.ZodOptional<z.ZodString>;
   submitLabel: z.ZodOptional<z.ZodString>;
   skippable: z.ZodDefault<z.ZodBoolean>;
+  blocking: z.ZodDefault<z.ZodBoolean>;
   frequency: z.ZodDefault<z.ZodEnum<{
     always: "always";
     conversation: "conversation";
@@ -1152,6 +1154,7 @@ export declare const widgetSettingsSchema: z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
     submitLabel: z.ZodOptional<z.ZodString>;
     skippable: z.ZodDefault<z.ZodBoolean>;
+    blocking: z.ZodDefault<z.ZodBoolean>;
     frequency: z.ZodDefault<z.ZodEnum<{
       always: "always";
       conversation: "conversation";
@@ -1494,6 +1497,7 @@ export declare const widgetConfigSchema: z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
     submitLabel: z.ZodOptional<z.ZodString>;
     skippable: z.ZodDefault<z.ZodBoolean>;
+    blocking: z.ZodDefault<z.ZodBoolean>;
     frequency: z.ZodDefault<z.ZodEnum<{
       always: "always";
       conversation: "conversation";
@@ -1837,6 +1841,7 @@ export declare const widgetConfigPartialSchema: z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
     submitLabel: z.ZodOptional<z.ZodString>;
     skippable: z.ZodDefault<z.ZodBoolean>;
+    blocking: z.ZodDefault<z.ZodBoolean>;
     frequency: z.ZodDefault<z.ZodEnum<{
       always: "always";
       conversation: "conversation";
@@ -2142,6 +2147,7 @@ export declare const widgetSettingsPartialSchema: z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
     submitLabel: z.ZodOptional<z.ZodString>;
     skippable: z.ZodDefault<z.ZodBoolean>;
+    blocking: z.ZodDefault<z.ZodBoolean>;
     frequency: z.ZodDefault<z.ZodEnum<{
       always: "always";
       conversation: "conversation";

package/schema.json

@@ -1557,6 +1557,11 @@
                 "description": "Show a Skip control so the visitor can dismiss the form.",
                 "type": "boolean"
               },
+              "blocking": {
+                "default": false,
+                "description": "Lock the message box until the visitor submits or skips.",
+                "type": "boolean"
+              },
               "frequency": {
                 "default": "once",
                 "description": "`once` (per device, persisted), `conversation` (re-eligible each new conversation), or `always`.",
@@ -1686,6 +1691,7 @@
               "on",
               "fields",
               "skippable",
+              "blocking",
               "frequency",
               "mirrorToContext",
               "reopenable",
@@ -1693,7 +1699,7 @@
             ],
             "additionalProperties": {}
           },
-          "description": "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.",
+          "description": "Event-driven forms — an ordered list (order = priority). Each binds to trigger event(s), shows in the conversation (a `blocking` one locks the message box until submit/skip), dedupes by frequency, and records via `endpoints.submitForm`. Generic across verticals.",
           "examples": [
             [
               {

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`)."),o=e.uuidv7().describe(`UUID v7 (RFC 9562) — the single id format for visitor / conversation / message / file / content ids.`),s=e.enum([`normal`,`expanded`,`fullscreen`,`auto`]),c=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`}]}),ee=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:c.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:s.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`}]}),te=e.enum([`floating`,`inline`,`standalone`,`page`,`modal`,`drawer`]),ne=e.enum([`bottom-right`,`bottom-left`,`top-right`,`top-left`]),re=e.object({mode:te.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:ne.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:ee.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 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."),popOutUrl:e.string().trim().min(1).max(2048).optional().describe("URL opened by the `popOut` header action. The widget adds the active conversation, widget, and deployment identity as query parameters.")}).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`,`host`]),f=e.object({mode:d.optional().describe("Light/dark beside the token overrides: `auto` (the OS, default), `light`, `dark`, or `host` (the page's own light/dark, flipping with the site's toggle)."),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`}]}),ie=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`}]}),p=e.enum([`circle`,`pill`,`bar`,`minimal`]),m=e.enum([`sm`,`md`,`lg`]),h=e.enum([`pill`,`bubble`,`callout`]),g=e.enum([`auto`,`horizontal`,`vertical`]),_=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:h.default(`pill`).describe("Visual shape — `pill` (slim label + arrow), `bubble` (speech-bubble tail), `callout` (loud variant)."),position:g.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.`),v=e.object({variant:p.default(`circle`).describe("FAB visual style. `circle` — round bubble (icon only). `pill` — icon + label. `bar` — wide rectangular button. `minimal` — text-only outline."),size:m.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:_.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}}]}),y=e.enum([`local`,`server`,`disabled`]),b=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:y.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 a person' 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}]}),x=e.enum([`clear`,`expand`,`fullscreen`,`popOut`,`sound`,`history`,`language`,`theme`,`textSize`,`close`]),S=e.array(x).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`, `popOut`, `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`]]}),C=e.object({actions:S.optional().describe(`Which header actions are enabled (history/✕ buttons + ⋯ menu).`)}).loose().describe(`Panel-header configuration.`).meta({examples:[{actions:[`theme`,`history`,`close`,`clear`,`fullscreen`]}]}),w=e.enum([`messageReceived`,`messageSent`,`error`,`voiceStart`,`voiceStop`]),T=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(w,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`}}]}),E=e.object({enabled:e.boolean().default(!0).describe(`Master on/off. Default: on for touch devices, silently ignored elsewhere.`),events:e.partialRecord(w,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]}}]}),D=e.object({sound:T.optional(),haptics:E.optional()}).loose().describe(`Audible + tactile feedback.`).meta({examples:[{sound:{enabled:!0,volume:.3},haptics:{enabled:!0}},{sound:{enabled:!1},haptics:{enabled:!1}}]}),O=e.enum([`circle`,`square`,`pill`]),k=e.enum([`arrowUp`,`paperPlane`,`send`,`chevron`]),A=e.enum([`filled`,`outline`,`ghost`]),j=e.object({shape:O.default(`circle`).describe("Send button outline shape — `circle` / `square` / `pill`."),icon:k.default(`arrowUp`).describe("Icon inside the send button — `arrowUp` / `paperPlane` / `send` / `chevron`."),variant:A.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`}]}),M=e.object({maxBytes:e.number().int().min(0).max(1073741824).default(10485760).describe("Maximum total size of the files attached to one message, 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`}]}),N=e.object({sendButton:j.optional(),attachments:M.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`}}]}),P=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`}]}),F=e.object({poweredBy:P.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.`}]}),I=e.enum([`text`,`email`,`tel`,`url`,`number`,`date`,`time`,`textarea`,`select`,`radio`,`checkbox`,`multiselect`]),L=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(),R=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(),z=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:I.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(L).max(50).optional().describe("Choices for `select` / `radio` / `multiselect`."),validation:R.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(),B=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`."),V=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(),H=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(),U=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(H).max(50).optional()}).loose(),W=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(U).max(50).optional()}).loose(),G=e.object({id:e.string().min(1).max(80).describe("Stable id — persistence dedupe + `manual` openForm(id)."),on:e.union([B,e.array(B).min(1).max(8)]).describe(`Trigger(s) that surface this form.`),when:V.optional().describe(`Extra eligibility predicate evaluated when a trigger fires.`),fields:e.array(z).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(W).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(),K=e.array(G).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`}]}]]}),q=e.record(e.string(),e.string()),J=e.union([q,e.record(a,q)]).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…`}}]}),Y=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:J.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`."),contentCollectionIds:e.array(o).max(20).optional().describe("Content collections this tab shows, in order — the `contentCollectionIds` filter on `GET /pai/content`; Help groups its sections by them. Omit for the `chat` layout."),id:e.string().max(60).optional().describe("Stable id for navigation + last-tab persistence. Defaults to the first `contentCollectionIds` 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: the pinned items of the tab's `contentCollectionIds` (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` + the content collections it shows (`contentCollectionIds`) + 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`,contentCollectionIds:[`019a0b6c-7e2a-7000-9d3e-4a5b6c7d8e01`]},{label:`tabConversations`,layout:`chat`},{id:`help`,label:`tabHelp`,layout:`help`,contentCollectionIds:[`019a0b6c-7e2a-7000-9d3e-4a5b6c7d8e01`,`019a0b6c-7e2a-7000-9d3e-4a5b6c7d8e02`]},{id:`news`,label:`tabNews`,layout:`news`,contentCollectionIds:[`019a0b6c-7e2a-7000-9d3e-4a5b6c7d8e03`]}]]}),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("Deployment public key (`agent_pk_…`) issued from the dashboard. Sent on every API call as the `x-public-key` header when present."),aiAgentDeploymentId:e.string().min(1).max(200).describe("Required 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-agent-api` directly (local module on its own port, e.g. `http://localhost:3069`; 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:3071`) — 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:re.optional(),behavior:u.optional(),theme:ie.default(`auto`).describe("Theme preference (`auto` follows OS) or a tokens override object (`accent`, `radius`, `fontFamily`)."),launcher:v.optional(),header:C.optional(),composer:N.optional(),feedback:D.optional(),i18n:Y.optional(),footer:F.optional(),features:b.optional(),forms:K.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(),history:e.object({enabled:e.boolean().optional().describe("`false` hides the history button and never lists past conversations. Default `true`.")}).loose().optional().describe(`The deployment's Keep conversations setting.`)}),$=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.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({conversationId:e.string()}).strict().optional()}).loose(),xe=[`theme`,`header`,`composer`,`footer`,`i18n`,`features`,`feedback`,`tracking`],Se={floating:[`presentation`,`behavior`,`modules`,`launcher`],inline:[`presentation`,`behavior`],modal:[`presentation`,`behavior`,`modules`],drawer:[`presentation`,`behavior`,`modules`,`launcher`],page:[`presentation`],standalone:[`presentation`]};function Ce(e){let t=[...Se[e],...xe],n={};for(let e of t)n[e]=!0;return Z.pick(n)}const we=[`floating`,`inline`,`standalone`,`page`,`modal`,`drawer`];function Te(){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(be)}}}export{we as ALL_MODES,de as PAGE_AREA_SUGGESTIONS,x as actionNameSchema,t as assetSchema,M as attachmentLimitsSchema,u as behaviorSchema,_e as blocksConfigSchema,g as calloutPositionSchema,h as calloutShapeSchema,N as composerOptionsSchema,he as connectionConfigPartialSchema,X as connectionConfigSchema,i as cssColorSchema,r as cssLengthSchema,Te as emitJsonSchema,le as endpointsSchema,b as featureFlagsSchema,w as feedbackEventSchema,D as feedbackSchema,L as fieldOptionSchema,H as fieldOptionTranslationSchema,I as fieldTypeSchema,R as fieldValidationSchema,F as footerSchema,V as formConditionSchema,G as formDefSchema,z as formFieldSchema,U as formFieldTranslationSchema,W as formTranslationSchema,B as formTriggerSchema,K as formsSchema,be as handshakeResponseSchema,E as hapticsOptionsSchema,S as headerActionsSchema,C as headerSchema,Y as i18nSchema,s as initialSizeSchema,_ as launcherCalloutSchema,v as launcherOptionsSchema,m as launcherSizeSchema,p as launcherVariantSchema,n as linkSchema,a as localeSchema,te as modeSchema,ae as moduleLayoutSchema,oe as moduleSchema,se as modulesSchema,fe as pageContextSchema,ne as positionSchema,P as poweredBySchema,re as presentationSchema,c as resizeOptionsSchema,l as responseModeSchema,k as sendButtonIconSchema,j as sendButtonOptionsSchema,O as sendButtonShapeSchema,A as sendButtonVariantSchema,ge as serverConfigSchema,$ as siteConfigSchema,ee as sizeOptionsSchema,T as soundOptionsSchema,J as stringsOverrideSchema,ie as themeFieldSchema,f as themeOverridesSchema,d as themePreferenceSchema,ce as trackingSchema,ue as userContextSchema,o as uuid7Schema,y as voiceModeSchema,pe as widgetConfigPartialSchema,Q as widgetConfigSchema,me as widgetSettingsPartialSchema,Z as widgetSettingsSchema,Ce 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`)."),o=e.uuidv7().describe(`UUID v7 (RFC 9562) — the single id format for visitor / conversation / message / file / content ids.`),s=e.enum([`normal`,`expanded`,`fullscreen`,`auto`]),c=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`}]}),ee=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:c.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:s.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`}]}),te=e.enum([`floating`,`inline`,`standalone`,`page`,`modal`,`drawer`]),ne=e.enum([`bottom-right`,`bottom-left`,`top-right`,`top-left`]),re=e.object({mode:te.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:ne.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:ee.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 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."),popOutUrl:e.string().trim().min(1).max(2048).optional().describe("URL opened by the `popOut` header action. The widget adds the active conversation, widget, and deployment identity as query parameters.")}).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`,`host`]),f=e.object({mode:d.optional().describe("Light/dark beside the token overrides: `auto` (the OS, default), `light`, `dark`, or `host` (the page's own light/dark, flipping with the site's toggle)."),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`}]}),ie=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`}]}),p=e.enum([`circle`,`pill`,`bar`,`minimal`]),m=e.enum([`sm`,`md`,`lg`]),h=e.enum([`pill`,`bubble`,`callout`]),g=e.enum([`auto`,`horizontal`,`vertical`]),_=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:h.default(`pill`).describe("Visual shape — `pill` (slim label + arrow), `bubble` (speech-bubble tail), `callout` (loud variant)."),position:g.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.`),v=e.object({variant:p.default(`circle`).describe("FAB visual style. `circle` — round bubble (icon only). `pill` — icon + label. `bar` — wide rectangular button. `minimal` — text-only outline."),size:m.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:_.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}}]}),y=e.enum([`local`,`server`,`disabled`]),b=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:y.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 a person' 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}]}),x=e.enum([`clear`,`expand`,`fullscreen`,`popOut`,`sound`,`history`,`language`,`theme`,`textSize`,`close`]),S=e.array(x).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`, `popOut`, `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`]]}),C=e.object({actions:S.optional().describe(`Which header actions are enabled (history/✕ buttons + ⋯ menu).`)}).loose().describe(`Panel-header configuration.`).meta({examples:[{actions:[`theme`,`history`,`close`,`clear`,`fullscreen`]}]}),w=e.enum([`messageReceived`,`messageSent`,`error`,`voiceStart`,`voiceStop`]),T=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(w,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`}}]}),E=e.object({enabled:e.boolean().default(!0).describe(`Master on/off. Default: on for touch devices, silently ignored elsewhere.`),events:e.partialRecord(w,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]}}]}),D=e.object({sound:T.optional(),haptics:E.optional()}).loose().describe(`Audible + tactile feedback.`).meta({examples:[{sound:{enabled:!0,volume:.3},haptics:{enabled:!0}},{sound:{enabled:!1},haptics:{enabled:!1}}]}),O=e.enum([`circle`,`square`,`pill`]),k=e.enum([`arrowUp`,`paperPlane`,`send`,`chevron`]),A=e.enum([`filled`,`outline`,`ghost`]),j=e.object({shape:O.default(`circle`).describe("Send button outline shape — `circle` / `square` / `pill`."),icon:k.default(`arrowUp`).describe("Icon inside the send button — `arrowUp` / `paperPlane` / `send` / `chevron`."),variant:A.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`}]}),M=e.object({maxBytes:e.number().int().min(0).max(1073741824).default(10485760).describe("Maximum total size of the files attached to one message, 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`}]}),N=e.object({sendButton:j.optional(),attachments:M.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`}}]}),P=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`}]}),F=e.object({poweredBy:P.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.`}]}),I=e.enum([`text`,`email`,`tel`,`url`,`number`,`date`,`time`,`textarea`,`select`,`radio`,`checkbox`,`multiselect`]),L=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(),R=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(),z=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:I.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(L).max(50).optional().describe("Choices for `select` / `radio` / `multiselect`."),validation:R.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(),B=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`."),V=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(),H=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(),U=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(H).max(50).optional()}).loose(),W=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(U).max(50).optional()}).loose(),G=e.object({id:e.string().min(1).max(80).describe("Stable id — persistence dedupe + `manual` openForm(id)."),on:e.union([B,e.array(B).min(1).max(8)]).describe(`Trigger(s) that surface this form.`),when:V.optional().describe(`Extra eligibility predicate evaluated when a trigger fires.`),fields:e.array(z).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.`),blocking:e.boolean().default(!1).describe(`Lock the message box until the visitor submits or skips.`),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(W).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(),K=e.array(G).max(20).describe("Event-driven forms — an ordered list (order = priority). Each binds to trigger event(s), shows in the conversation (a `blocking` one locks the message box 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`}]}]]}),q=e.record(e.string(),e.string()),J=e.union([q,e.record(a,q)]).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…`}}]}),Y=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:J.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`."),contentCollectionIds:e.array(o).max(20).optional().describe("Content collections this tab shows, in order — the `contentCollectionIds` filter on `GET /pai/content`; Help groups its sections by them. Omit for the `chat` layout."),id:e.string().max(60).optional().describe("Stable id for navigation + last-tab persistence. Defaults to the first `contentCollectionIds` 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: the pinned items of the tab's `contentCollectionIds` (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` + the content collections it shows (`contentCollectionIds`) + 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`,contentCollectionIds:[`019a0b6c-7e2a-7000-9d3e-4a5b6c7d8e01`]},{label:`tabConversations`,layout:`chat`},{id:`help`,label:`tabHelp`,layout:`help`,contentCollectionIds:[`019a0b6c-7e2a-7000-9d3e-4a5b6c7d8e01`,`019a0b6c-7e2a-7000-9d3e-4a5b6c7d8e02`]},{id:`news`,label:`tabNews`,layout:`news`,contentCollectionIds:[`019a0b6c-7e2a-7000-9d3e-4a5b6c7d8e03`]}]]}),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("Deployment public key (`agent_pk_…`) issued from the dashboard. Sent on every API call as the `x-public-key` header when present."),aiAgentDeploymentId:e.string().min(1).max(200).describe("Required 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-agent-api` directly (local module on its own port, e.g. `http://localhost:3069`; 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:3071`) — 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:re.optional(),behavior:u.optional(),theme:ie.default(`auto`).describe("Theme preference (`auto` follows OS) or a tokens override object (`accent`, `radius`, `fontFamily`)."),launcher:v.optional(),header:C.optional(),composer:N.optional(),feedback:D.optional(),i18n:Y.optional(),footer:F.optional(),features:b.optional(),forms:K.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(),history:e.object({enabled:e.boolean().optional().describe("`false` hides the history button and never lists past conversations. Default `true`.")}).loose().optional().describe(`The deployment's Keep conversations setting.`)}),$=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.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({conversationId:e.string()}).strict().optional()}).loose(),xe=[`theme`,`header`,`composer`,`footer`,`i18n`,`features`,`feedback`,`tracking`],Se={floating:[`presentation`,`behavior`,`modules`,`launcher`],inline:[`presentation`,`behavior`],modal:[`presentation`,`behavior`,`modules`],drawer:[`presentation`,`behavior`,`modules`,`launcher`],page:[`presentation`],standalone:[`presentation`]};function Ce(e){let t=[...Se[e],...xe],n={};for(let e of t)n[e]=!0;return Z.pick(n)}const we=[`floating`,`inline`,`standalone`,`page`,`modal`,`drawer`];function Te(){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(be)}}}export{we as ALL_MODES,de as PAGE_AREA_SUGGESTIONS,x as actionNameSchema,t as assetSchema,M as attachmentLimitsSchema,u as behaviorSchema,_e as blocksConfigSchema,g as calloutPositionSchema,h as calloutShapeSchema,N as composerOptionsSchema,he as connectionConfigPartialSchema,X as connectionConfigSchema,i as cssColorSchema,r as cssLengthSchema,Te as emitJsonSchema,le as endpointsSchema,b as featureFlagsSchema,w as feedbackEventSchema,D as feedbackSchema,L as fieldOptionSchema,H as fieldOptionTranslationSchema,I as fieldTypeSchema,R as fieldValidationSchema,F as footerSchema,V as formConditionSchema,G as formDefSchema,z as formFieldSchema,U as formFieldTranslationSchema,W as formTranslationSchema,B as formTriggerSchema,K as formsSchema,be as handshakeResponseSchema,E as hapticsOptionsSchema,S as headerActionsSchema,C as headerSchema,Y as i18nSchema,s as initialSizeSchema,_ as launcherCalloutSchema,v as launcherOptionsSchema,m as launcherSizeSchema,p as launcherVariantSchema,n as linkSchema,a as localeSchema,te as modeSchema,ae as moduleLayoutSchema,oe as moduleSchema,se as modulesSchema,fe as pageContextSchema,ne as positionSchema,P as poweredBySchema,re as presentationSchema,c as resizeOptionsSchema,l as responseModeSchema,k as sendButtonIconSchema,j as sendButtonOptionsSchema,O as sendButtonShapeSchema,A as sendButtonVariantSchema,ge as serverConfigSchema,$ as siteConfigSchema,ee as sizeOptionsSchema,T as soundOptionsSchema,J as stringsOverrideSchema,ie as themeFieldSchema,f as themeOverridesSchema,d as themePreferenceSchema,ce as trackingSchema,ue as userContextSchema,o as uuid7Schema,y as voiceModeSchema,pe as widgetConfigPartialSchema,Q as widgetConfigSchema,me as widgetSettingsPartialSchema,Z as widgetSettingsSchema,Ce as widgetSettingsSchemaForMode};
 //# sourceMappingURL=schema.mjs.map

package/web-component.d.ts

@@ -242,8 +242,9 @@ interface FeedbackOptions {
  * interfaces are what the resolver, controller, and form UI consume.
  *
  * A deployment declares an array of {@link FormDef}s; each is bound to trigger
- * event(s) and shown as a gate that replaces the composer (locking the chat
- * until submit/skip). Its answers are recorded via one shared submit endpoint.
+ * event(s) and shown as the last conversation row; a `blocking` one also locks
+ * the message box until submit/skip. Its answers are recorded via one shared
+ * submit endpoint.
  * Generic across verticals — there is NO industry logic; a clinic intake, an
  * insurance claim form, a CSAT survey, and a sales signal capture are all just
  * different config.
@@ -324,6 +325,8 @@ interface FormDef {
   description?: string;
   submitLabel?: string;
   skippable?: boolean;
+  /** Lock the message box until the visitor submits or skips. Default `false`. */
+  blocking?: boolean;
   /** Default `once`. */
   frequency?: FormFrequency;
   /**