@helpai/elements 0.20.0 → 0.21.0

package/schema.mjs

@@ -17,7 +17,7 @@ var localeSchema = z.string().min(1).max(35).describe("BCP-47 locale tag (e.g. `
 var uuid7Schema = z.uuidv7().describe("UUID v7 (RFC 9562) \u2014 the single id format for visitor / conversation / message / file / content ids.");
 
 // src/schema/widget.ts
-import { z as z16 } from "zod";
+import { z as z15 } from "zod";
 
 // src/schema/widget/presentation.ts
 import { z as z3 } from "zod";
@@ -341,33 +341,21 @@ var composerOptionsSchema = z10.object({
   ]
 });
 
-// src/schema/widget/welcome.ts
-import { z as z11 } from "zod";
-var welcomeAnimationSchema = z11.enum(["typewriter", "instant"]);
-var welcomeOptionsSchema = z11.object({
-  animation: welcomeAnimationSchema.default("instant").describe(
-    "How welcome messages render \u2014 `typewriter` types each message in character-by-character; `instant` shows them whole."
-  ),
-  speed: z11.number().int().min(1).max(2e3).default(60).describe("Typewriter speed in characters per second. Only meaningful when `animation = typewriter`.")
-}).loose().describe("How welcome messages render \u2014 instant by default; opt into a typewriter effect with adjustable cps speed.").meta({
-  examples: [{ animation: "instant" }, { animation: "typewriter", speed: 60 }]
-});
-
 // src/schema/widget/footer.ts
-import { z as z12 } from "zod";
-var poweredBySchema = z12.object({
-  text: z12.string().max(200).optional().describe("Visible attribution text (e.g. `Powered by Help AI`)."),
-  href: z12.url().max(2048).optional().describe("Click target \u2014 the attribution becomes a link. Must be a full URL (`https://\u2026`)."),
-  logoUrl: z12.url().max(2048).optional().describe("Small logo rendered before the text. Must be a full URL.")
+import { z as z11 } from "zod";
+var poweredBySchema = z11.object({
+  text: z11.string().max(200).optional().describe("Visible attribution text (e.g. `Powered by Help AI`)."),
+  href: z11.url().max(2048).optional().describe("Click target \u2014 the attribution becomes a link. Must be a full URL (`https://\u2026`)."),
+  logoUrl: z11.url().max(2048).optional().describe("Small logo rendered before the text. Must be a full URL.")
 }).loose().describe('"Powered by \u2026" 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" }
   ]
 });
-var footerSchema = z12.object({
+var footerSchema = z11.object({
   poweredBy: poweredBySchema.optional(),
-  composerDisclaimer: z12.string().max(500).optional().describe("Small muted text under the composer (like ChatGPT's 'ChatGPT can make mistakes.'). Empty = hidden.")
+  composerDisclaimer: z11.string().max(500).optional().describe("Small muted text under the composer (like ChatGPT's 'ChatGPT can make mistakes.'). Empty = hidden.")
 }).loose().describe("Footer \u2014 attribution + composer disclaimer.").meta({
   examples: [
     { poweredBy: { text: "Powered by Help AI", href: "https://help.ai" } },
@@ -376,8 +364,8 @@ var footerSchema = z12.object({
 });
 
 // src/schema/widget/forms.ts
-import { z as z13 } from "zod";
-var fieldTypeSchema = z13.enum([
+import { z as z12 } from "zod";
+var fieldTypeSchema = z12.enum([
   "text",
   "email",
   "tel",
@@ -391,59 +379,59 @@ var fieldTypeSchema = z13.enum([
   "checkbox",
   "multiselect"
 ]);
-var fieldOptionSchema = z13.object({
-  value: z13.string().min(1).max(200).describe("The value recorded when this choice is picked."),
-  label: z13.string().min(1).max(200).optional().describe("Display text; falls back to `value`."),
-  description: z13.string().max(280).optional().describe("Optional sub-label under the choice.")
+var fieldOptionSchema = z12.object({
+  value: z12.string().min(1).max(200).describe("The value recorded when this choice is picked."),
+  label: z12.string().min(1).max(200).optional().describe("Display text; falls back to `value`."),
+  description: z12.string().max(280).optional().describe("Optional sub-label under the choice.")
 }).loose();
-var fieldValidationSchema = z13.object({
-  pattern: z13.string().max(500).optional().describe("Regex source string \u2014 text-like fields (e.g. `^\\d{5}$`)."),
-  minLength: z13.number().int().min(0).max(1e4).optional(),
-  maxLength: z13.number().int().min(1).max(1e4).optional(),
-  min: z13.number().optional().describe("Minimum \u2014 `number` fields."),
-  max: z13.number().optional().describe("Maximum \u2014 `number` fields."),
-  minSelections: z13.number().int().min(0).max(50).optional().describe("Minimum picks \u2014 `multiselect`."),
-  maxSelections: z13.number().int().min(1).max(50).optional().describe("Maximum picks \u2014 `multiselect`.")
+var fieldValidationSchema = z12.object({
+  pattern: z12.string().max(500).optional().describe("Regex source string \u2014 text-like fields (e.g. `^\\d{5}$`)."),
+  minLength: z12.number().int().min(0).max(1e4).optional(),
+  maxLength: z12.number().int().min(1).max(1e4).optional(),
+  min: z12.number().optional().describe("Minimum \u2014 `number` fields."),
+  max: z12.number().optional().describe("Maximum \u2014 `number` fields."),
+  minSelections: z12.number().int().min(0).max(50).optional().describe("Minimum picks \u2014 `multiselect`."),
+  maxSelections: z12.number().int().min(1).max(50).optional().describe("Maximum picks \u2014 `multiselect`.")
 }).loose();
-var formFieldSchema = z13.object({
-  name: z13.string().min(1).max(80).describe("Stable key the answer is recorded under (e.g. `email`)."),
-  label: z13.string().min(1).max(200).describe("Visible field label."),
+var formFieldSchema = z12.object({
+  name: z12.string().min(1).max(80).describe("Stable key the answer is recorded under (e.g. `email`)."),
+  label: z12.string().min(1).max(200).describe("Visible field label."),
   type: fieldTypeSchema.describe("Field renderer + built-in validation (email/tel/url/number/date/time checked)."),
-  placeholder: z13.string().max(200).optional(),
-  required: z13.boolean().optional().default(true).describe("Must be answered to submit. `false` allows skipping."),
-  defaultValue: z13.string().max(2e3).optional().describe("Pre-filled value (comma-join for `multiselect`)."),
-  options: z13.array(fieldOptionSchema).max(50).optional().describe("Choices for `select` / `radio` / `multiselect`."),
+  placeholder: z12.string().max(200).optional(),
+  required: z12.boolean().optional().default(true).describe("Must be answered to submit. `false` allows skipping."),
+  defaultValue: z12.string().max(2e3).optional().describe("Pre-filled value (comma-join for `multiselect`)."),
+  options: z12.array(fieldOptionSchema).max(50).optional().describe("Choices for `select` / `radio` / `multiselect`."),
   validation: fieldValidationSchema.optional(),
-  allowOther: z13.boolean().optional().describe("`select`/`radio`/`multiselect` \u2014 allow a free-text 'Other' answer."),
-  validationHint: z13.string().max(280).optional().describe("Small helper line under the field.")
+  allowOther: z12.boolean().optional().describe("`select`/`radio`/`multiselect` \u2014 allow a free-text 'Other' answer."),
+  validationHint: z12.string().max(280).optional().describe("Small helper line under the field.")
 }).loose();
-var formTriggerSchema = z13.string().regex(
+var formTriggerSchema = z12.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`."
 );
-var formConditionSchema = z13.object({
-  missingContext: z13.array(z13.string().max(80)).max(20).optional().describe("Only show if `userContext` lacks ALL of these keys (progressive profiling)."),
-  pageArea: z13.union([z13.string().max(64), z13.array(z13.string().max(64)).max(20)]).optional().describe("Only on these `pageContext.area` values."),
-  minMessages: z13.number().int().min(0).max(1e3).optional(),
-  maxMessages: z13.number().int().min(0).max(1e3).optional()
+var formConditionSchema = z12.object({
+  missingContext: z12.array(z12.string().max(80)).max(20).optional().describe("Only show if `userContext` lacks ALL of these keys (progressive profiling)."),
+  pageArea: z12.union([z12.string().max(64), z12.array(z12.string().max(64)).max(20)]).optional().describe("Only on these `pageContext.area` values."),
+  minMessages: z12.number().int().min(0).max(1e3).optional(),
+  maxMessages: z12.number().int().min(0).max(1e3).optional()
 }).loose();
-var formDefSchema = z13.object({
-  id: z13.string().min(1).max(80).describe("Stable id \u2014 persistence dedupe + `manual` openForm(id)."),
-  on: z13.union([formTriggerSchema, z13.array(formTriggerSchema).min(1).max(8)]).describe("Trigger(s) that surface this form."),
+var formDefSchema = z12.object({
+  id: z12.string().min(1).max(80).describe("Stable id \u2014 persistence dedupe + `manual` openForm(id)."),
+  on: z12.union([formTriggerSchema, z12.array(formTriggerSchema).min(1).max(8)]).describe("Trigger(s) that surface this form."),
   when: formConditionSchema.optional().describe("Extra eligibility predicate evaluated when a trigger fires."),
-  fields: z13.array(formFieldSchema).max(20).default([]).describe("The questions, in order. \u22651 required to show."),
-  title: z13.string().max(120).optional(),
-  description: z13.string().max(500).optional(),
-  submitLabel: z13.string().max(60).optional(),
-  skippable: z13.boolean().default(false).describe("Show a Skip control so the visitor can dismiss the form."),
-  frequency: z13.enum(["once", "conversation", "always"]).default("once").describe("`once` (per device, persisted), `conversation` (re-eligible each new conversation), or `always`."),
-  mirrorToContext: z13.boolean().default(true).describe(
+  fields: z12.array(formFieldSchema).max(20).default([]).describe("The questions, in order. \u22651 required to show."),
+  title: z12.string().max(120).optional(),
+  description: z12.string().max(500).optional(),
+  submitLabel: z12.string().max(60).optional(),
+  skippable: z12.boolean().default(false).describe("Show a Skip control so the visitor can dismiss the form."),
+  frequency: z12.enum(["once", "conversation", "always"]).default("once").describe("`once` (per device, persisted), `conversation` (re-eligible each new conversation), or `always`."),
+  mirrorToContext: z12.boolean().default(true).describe(
     "Mirror the answers into `userContext` so they ride every request. Set `false` for PII (DOB, policy #, symptoms) \u2014 those then go only to the submit endpoint."
   )
 }).loose();
-var formsSchema = z13.array(formDefSchema).max(20).describe(
+var formsSchema = z12.array(formDefSchema).max(20).describe(
   "Event-driven forms \u2014 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: [
@@ -486,9 +474,9 @@ var formsSchema = z13.array(formDefSchema).max(20).describe(
 });
 
 // src/schema/widget/i18n.ts
-import { z as z14 } from "zod";
-var localeStringsSchema = z14.record(z14.string(), z14.string());
-var stringsOverrideSchema = z14.union([localeStringsSchema, z14.record(localeSchema, localeStringsSchema)]).describe(
+import { z as z13 } from "zod";
+var localeStringsSchema = z13.record(z13.string(), z13.string());
+var stringsOverrideSchema = z13.union([localeStringsSchema, z13.record(localeSchema, localeStringsSchema)]).describe(
   "Per-instance UI string overrides. Flat = active-locale only; nested = multi-locale map. Both forms are partial \u2014 missing keys fall through to built-in defaults."
 ).meta({
   examples: [
@@ -499,10 +487,10 @@ var stringsOverrideSchema = z14.union([localeStringsSchema, z14.record(localeSch
     }
   ]
 });
-var i18nSchema = z14.object({
+var i18nSchema = z13.object({
   locale: localeSchema.optional().describe("BCP-47 locale tag forced for this widget instance (e.g. `fr-CA`). Page-owner explicit override."),
-  defaultLocale: z14.union([z14.literal("auto"), localeSchema]).default("auto").describe("Initial / fallback locale for users who haven't picked one. `auto` sniffs `navigator.language`."),
-  availableLocales: z14.array(localeSchema).max(200).optional().describe("BCP-47 locale tags shown in the runtime language switcher. Hidden when fewer than 2 entries."),
+  defaultLocale: z13.union([z13.literal("auto"), localeSchema]).default("auto").describe("Initial / fallback locale for users who haven't picked one. `auto` sniffs `navigator.language`."),
+  availableLocales: z13.array(localeSchema).max(200).optional().describe("BCP-47 locale tags shown in the runtime language switcher. Hidden when fewer than 2 entries."),
   strings: stringsOverrideSchema.optional()
 }).loose().describe("Locale + i18n overrides.").meta({
   examples: [
@@ -513,44 +501,44 @@ var i18nSchema = z14.object({
 });
 
 // src/schema/widget/modules.ts
-import { z as z15 } from "zod";
-var moduleLayoutSchema = z15.enum(["chat", "home", "help", "news"]);
-var moduleSchema = z15.object({
-  label: z15.string().min(1).max(40).describe(
+import { z as z14 } from "zod";
+var moduleLayoutSchema = z14.enum(["chat", "home", "help", "news"]);
+var moduleSchema = z14.object({
+  label: z14.string().min(1).max(40).describe(
     "Tab label \u2014 an i18n key (resolved against the i18n strings, e.g. `tabHome`) or a literal. Translations ride `i18n.strings`."
   ),
   layout: moduleLayoutSchema.describe(
     "UI layout that renders this tab: `chat` (the conversation), `home`, `help`, or `news`."
   ),
-  contentTags: z15.array(z15.string().max(60)).max(20).optional().describe(
+  contentTags: z14.array(z14.string().max(60)).max(20).optional().describe(
     "Content tags this tab scopes to \u2014 the `tags` filter on `GET /ai/agent/content` (matches content tagged with ANY of them). Omit for the `chat` layout."
   ),
-  id: z15.string().max(60).optional().describe(
+  id: z14.string().max(60).optional().describe(
     "Stable id for navigation + last-tab persistence. Defaults to the first `contentTags` entry, else `layout`."
   ),
   // ── `home` layout config (flat feature flags — no block authoring) ──────
-  brandName: z15.string().max(80).optional().describe("`home` \u2014 hero wordmark (e.g. your company name)."),
-  showGreeting: z15.boolean().optional().describe("`home` \u2014 show the greeting hero (default true)."),
-  greetingText: z15.string().max(280).optional().describe("`home` \u2014 override the greeting headline (default 'How can we help?'); supports a `{name}` token."),
-  userAvatars: z15.array(
-    z15.object({
-      name: z15.string().min(1).max(80),
-      avatar: z15.string().max(2048).optional().describe("Image URL; falls back to initials of `name`."),
-      role: z15.string().max(80).optional()
+  brandName: z14.string().max(80).optional().describe("`home` \u2014 hero wordmark (e.g. your company name)."),
+  showGreeting: z14.boolean().optional().describe("`home` \u2014 show the greeting hero (default true)."),
+  greetingText: z14.string().max(280).optional().describe("`home` \u2014 override the greeting headline (default 'How can we help?'); supports a `{name}` token."),
+  userAvatars: z14.array(
+    z14.object({
+      name: z14.string().min(1).max(80),
+      avatar: z14.string().max(2048).optional().describe("Image URL; falls back to initials of `name`."),
+      role: z14.string().max(80).optional()
     }).loose()
   ).max(10).optional().describe("`home` \u2014 team/agent avatars shown in the hero."),
-  showSearchBar: z15.boolean().optional().describe("`home` \u2014 show the 'Search for help' bar (default true)."),
-  showRecentConversations: z15.boolean().optional().describe("`home` \u2014 show the visitor's most recent conversation card (default true)."),
-  status: z15.object({
-    text: z15.string().min(1).max(120),
-    level: z15.string().max(40).optional().describe(
+  showSearchBar: z14.boolean().optional().describe("`home` \u2014 show the 'Search for help' bar (default true)."),
+  showRecentConversations: z14.boolean().optional().describe("`home` \u2014 show the visitor's most recent conversation card (default true)."),
+  status: z14.object({
+    text: z14.string().min(1).max(120),
+    level: z14.string().max(40).optional().describe(
       "`home` \u2014 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: z15.string().max(2048).optional().describe("Opens in an in-widget iframe when tapped.")
+    url: z14.string().max(2048).optional().describe("Opens in an in-widget iframe when tapped.")
   }).optional().describe("`home` \u2014 system-status card. Omit to hide."),
-  contentBlockTitle: z15.string().max(80).optional().describe("`home` \u2014 heading for the content list built from `contentTags` (default 'Popular articles').")
+  contentBlockTitle: z14.string().max(80).optional().describe("`home` \u2014 heading for the content list built from `contentTags` (default 'Popular articles').")
 }).loose();
-var modulesSchema = z15.array(moduleSchema).max(4).describe(
+var modulesSchema = z14.array(moduleSchema).max(4).describe(
   "Messenger tabs \u2014 an ordered list of up to 4 tabs, each picking a `layout` + optional content `contentTags` (the content scope) + a translatable `label`. One tab \u2192 no tab bar (just that content); zero \u2192 an empty state. Floating / drawer / modal only."
 ).meta({
   examples: [
@@ -573,10 +561,10 @@ var modulesSchema = z15.array(moduleSchema).max(4).describe(
 });
 
 // src/schema/widget.ts
-var endpointsSchema = z16.object({
-  upload: z16.string().min(1).max(2048).default("/ai/agent/upload-file"),
-  transcribe: z16.string().min(1).max(2048).default("/ai/agent/transcribe-audio"),
-  submitForm: z16.string().min(1).max(2048).default("/ai/agent/submit-form").describe(
+var endpointsSchema = z15.object({
+  upload: z15.string().min(1).max(2048).default("/ai/agent/upload-file"),
+  transcribe: z15.string().min(1).max(2048).default("/ai/agent/transcribe-audio"),
+  submitForm: z15.string().min(1).max(2048).default("/ai/agent/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 \u2014 a 404 is ignored."
   )
 }).loose().describe("HTTP endpoint overrides. Paths are appended to baseUrl; absolute URLs are accepted too.").meta({
@@ -586,14 +574,14 @@ var endpointsSchema = z16.object({
     { submitForm: "https://crm.acme.com/leads" }
   ]
 });
-var userContextSchema = z16.object({
-  id: z16.string().min(1).max(200).optional().describe("Host's stable id for the user \u2014 informational context the agent/backend can key on (not auth)."),
-  email: z16.string().min(1).max(320).optional().describe("User email \u2014 surfaced to the agent for context (optional)."),
-  name: z16.string().min(1).max(200).optional().describe("Display name \u2014 shown in the Home greeting (`{name}`) and conversation transcripts (optional)."),
-  plan: z16.string().min(1).max(120).optional().describe("Subscription / pricing tier, e.g. `pro` (optional)."),
-  role: z16.string().min(1).max(120).optional().describe("The user's role on the host site, e.g. `admin` (optional)."),
-  phone: z16.string().min(1).max(40).optional().describe("Phone number (optional).")
-}).catchall(z16.union([z16.string(), z16.number(), z16.boolean()])).describe(
+var userContextSchema = z15.object({
+  id: z15.string().min(1).max(200).optional().describe("Host's stable id for the user \u2014 informational context the agent/backend can key on (not auth)."),
+  email: z15.string().min(1).max(320).optional().describe("User email \u2014 surfaced to the agent for context (optional)."),
+  name: z15.string().min(1).max(200).optional().describe("Display name \u2014 shown in the Home greeting (`{name}`) and conversation transcripts (optional)."),
+  plan: z15.string().min(1).max(120).optional().describe("Subscription / pricing tier, e.g. `pro` (optional)."),
+  role: z15.string().min(1).max(120).optional().describe("The user's role on the host site, e.g. `admin` (optional)."),
+  phone: z15.string().min(1).max(40).optional().describe("Phone number (optional).")
+}).catchall(z15.union([z15.string(), z15.number(), z15.boolean()])).describe(
   "Host-asserted end-user context (informational, untrusted \u2014 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" }]
@@ -609,31 +597,31 @@ var PAGE_AREA_SUGGESTIONS = [
   "account",
   "blog"
 ];
-var pageContextSchema = z16.object({
-  area: z16.string().min(1).max(64).optional().describe(`Host-defined surface the visitor is on. Free-form; suggested: ${PAGE_AREA_SUGGESTIONS.join(" | ")}.`),
-  url: z16.string().min(1).max(2048).optional().describe("Full page URL. Auto-filled from the host page when omitted."),
-  path: z16.string().min(1).max(2048).optional().describe("Page path, e.g. `/pricing/enterprise`."),
-  title: z16.string().min(1).max(300).optional().describe("Human-readable page title.")
-}).catchall(z16.union([z16.string(), z16.number(), z16.boolean()])).describe(
+var pageContextSchema = z15.object({
+  area: z15.string().min(1).max(64).optional().describe(`Host-defined surface the visitor is on. Free-form; suggested: ${PAGE_AREA_SUGGESTIONS.join(" | ")}.`),
+  url: z15.string().min(1).max(2048).optional().describe("Full page URL. Auto-filled from the host page when omitted."),
+  path: z15.string().min(1).max(2048).optional().describe("Page path, e.g. `/pricing/enterprise`."),
+  title: z15.string().min(1).max(300).optional().describe("Human-readable page title.")
+}).catchall(z15.union([z15.string(), z15.number(), z15.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" }] });
-var connectionConfigSchema = z16.object({
-  widgetId: z16.string().min(1).max(80).default("default").describe(
+var connectionConfigSchema = z15.object({
+  widgetId: z15.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: z16.string().min(1).max(200).optional().describe(
+  publicKey: z15.string().min(1).max(200).optional().describe(
     "Workspace-scoped public key (`agent_pk_\u2026`) issued from the dashboard. Sent on every API call as the `x-public-key` header."
   ),
-  aiAgentDeploymentId: z16.string().min(1).max(200).optional().describe(
+  aiAgentDeploymentId: z15.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: z16.string().min(1).max(2048).optional().describe(
+  baseUrl: z15.string().min(1).max(2048).optional().describe(
     "Full backend origin (e.g. `https://help.ai/api`). Set this to point at your staging / self-hosted / custom backend. Default: the brand's `defaultBaseUrl` baked at build time."
   ),
   userContext: userContextSchema.optional(),
   pageContext: pageContextSchema.optional(),
   endpoints: endpointsSchema.optional(),
-  debug: z16.union([z16.boolean(), z16.enum(["off", "error", "warn", "info", "debug", "trace"])]).optional().describe(
+  debug: z15.union([z15.boolean(), z15.enum(["off", "error", "warn", "info", "debug", "trace"])]).optional().describe(
     'Console log verbosity. `false` / `"off"` silences everything (default in production). `true` \u2192 `"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 \u2014 the URL beats this option, this option beats the persisted `localStorage` value.'
   )
 }).loose().describe(
@@ -653,14 +641,13 @@ var connectionConfigSchema = z16.object({
     }
   ]
 });
-var widgetSettingsSchema = z16.object({
+var widgetSettingsSchema = z15.object({
   presentation: presentationSchema.optional(),
   behavior: behaviorSchema.optional(),
   theme: themeFieldSchema.default("auto").describe("Theme preference (`auto` follows OS) or a tokens override object (`accent`, `radius`, `fontFamily`)."),
   launcher: launcherOptionsSchema.optional(),
   header: headerSchema.optional(),
   composer: composerOptionsSchema.optional(),
-  welcome: welcomeOptionsSchema.optional(),
   feedback: feedbackSchema.optional(),
   i18n: i18nSchema.optional(),
   footer: footerSchema.optional(),
@@ -686,10 +673,10 @@ var widgetSettingsSchema = z16.object({
 });
 var widgetConfigSchema = connectionConfigSchema.extend({
   ...widgetSettingsSchema.shape,
-  site: z16.unknown().optional().describe(
+  site: z15.unknown().optional().describe(
     'Site config \u2014 applies in `mode: "page"`. Comes from the start-conversation response, not user-edited.'
   ),
-  blocks: z16.unknown().optional().describe('Blocks (nav + link cards) \u2014 applies in `mode: "page"`. Comes from the start-conversation response.')
+  blocks: z15.unknown().optional().describe('Blocks (nav + link cards) \u2014 applies in `mode: "page"`. Comes from the start-conversation response.')
 }).describe(
   "Full client widget config \u2014 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 \u2014 the runtime silently ignores irrelevant fields rather than rejecting them so the same object can flow across mode changes."
 ).meta({
@@ -712,49 +699,49 @@ var widgetSettingsPartialSchema = widgetSettingsSchema.partial();
 var connectionConfigPartialSchema = connectionConfigSchema.partial();
 
 // src/schema/deployment.ts
-import { z as z17 } from "zod";
+import { z as z16 } from "zod";
 var serverConfigSchema = widgetSettingsSchema.partial();
-var siteConfigSchema = z17.object({
-  title: z17.string().min(1).max(120).optional().describe("Brand / site name. Used as the logo's alt-text fallback."),
+var siteConfigSchema = z16.object({
+  title: z16.string().min(1).max(120).optional().describe("Brand / site name. Used as the logo's alt-text fallback."),
   logo: assetSchema.optional().describe("Brand logo shown at the top of the page-mode sidebar."),
   logoDark: assetSchema.optional().describe(
     "Optional dark-theme logo variant. Falls back to `logo` when the active theme is light or `logoDark` is unset."
   )
 }).loose();
-var blocksConfigSchema = z17.object({
-  navigation: z17.array(linkSchema).max(100).optional().describe("Sidebar navigation links (vertical list, primary nav)."),
-  linkCards: z17.array(linkSchema).max(100).optional().describe("Sidebar link cards (richer entries with optional `description`).")
+var blocksConfigSchema = z16.object({
+  navigation: z16.array(linkSchema).max(100).optional().describe("Sidebar navigation links (vertical list, primary nav)."),
+  linkCards: z16.array(linkSchema).max(100).optional().describe("Sidebar link cards (richer entries with optional `description`).")
 }).loose();
-var handshakeWelcomeMessageSchema = z17.object({
-  id: z17.string(),
-  role: z17.enum(["assistant", "system"]),
-  text: z17.string()
+var handshakeWelcomeMessageSchema = z16.object({
+  id: z16.string(),
+  role: z16.enum(["assistant", "system"]),
+  text: z16.string()
 }).loose();
-var handshakeWelcomeSuggestionSchema = z17.object({
-  id: z17.string(),
-  label: z17.string(),
-  text: z17.string().optional()
+var handshakeWelcomeSuggestionSchema = z16.object({
+  id: z16.string(),
+  label: z16.string(),
+  text: z16.string().optional()
 }).loose();
-var rebindReasonSchema = z17.enum(["conflict", "expired", "invalid"]);
-var startConversationResponseSchema = z17.object({
-  deployment: z17.object({
-    id: z17.string(),
-    name: z17.string(),
+var rebindReasonSchema = z16.enum(["conflict", "expired", "invalid"]);
+var startConversationResponseSchema = z16.object({
+  deployment: z16.object({
+    id: z16.string(),
+    name: z16.string(),
     // Page URL identifier — present on every deployment; unique per host.
     // Used to mount page deployments via `?slug=…`.
-    slug: z17.string().optional(),
-    publicKey: z17.string().optional()
+    slug: z16.string().optional(),
+    publicKey: z16.string().optional()
     // Deliberately no `type` / `channel` here. Deployment-level
     // taxonomy is a backend categorization concern — the widget's
     // rendering choice flows from `widget.presentation.mode`, not
     // the deployment record's category. `.loose()` lets any such
     // backend field pass through without typing.
   }).loose(),
-  agent: z17.object({
-    id: z17.string(),
-    name: z17.string(),
-    title: z17.string().optional(),
-    status: z17.enum(["online", "away", "offline"]).optional()
+  agent: z16.object({
+    id: z16.string(),
+    name: z16.string(),
+    title: z16.string().optional(),
+    status: z16.enum(["online", "away", "offline"]).optional()
   }).loose(),
   /**
    * Deployment-wide widget configuration the dashboard admin saved
@@ -764,26 +751,26 @@ var startConversationResponseSchema = z17.object({
   config: serverConfigSchema.optional(),
   site: siteConfigSchema.optional(),
   blocks: blocksConfigSchema.optional(),
-  welcome: z17.object({
-    messages: z17.array(handshakeWelcomeMessageSchema).optional(),
-    suggestions: z17.array(handshakeWelcomeSuggestionSchema).optional()
+  welcome: z16.object({
+    messages: z16.array(handshakeWelcomeMessageSchema).optional(),
+    suggestions: z16.array(handshakeWelcomeSuggestionSchema).optional()
   }).loose().optional(),
-  visitorId: z17.string(),
-  conversationId: z17.string(),
-  canContinue: z17.boolean(),
-  messages: z17.array(z17.unknown()),
+  visitorId: z16.string(),
+  conversationId: z16.string(),
+  canContinue: z16.boolean(),
+  messages: z16.array(z16.unknown()),
   /**
    * Form submissions recorded for this conversation — echoed like
    * `messages` so the widget reconstructs the collapsed "form submitted"
    * timeline markers on resume. `createdAt` is ISO-8601 (a serialized
    * Mongo ISODate — same format as message `createdAt`).
    */
-  formSubmissions: z17.array(
-    z17.object({
-      formId: z17.string(),
-      trigger: z17.string(),
-      skipped: z17.boolean().optional(),
-      createdAt: z17.iso.datetime().optional()
+  formSubmissions: z16.array(
+    z16.object({
+      formId: z16.string(),
+      trigger: z16.string(),
+      skipped: z16.boolean().optional(),
+      createdAt: z16.iso.datetime().optional()
     }).loose()
   ).optional(),
   /**
@@ -792,11 +779,11 @@ var startConversationResponseSchema = z17.object({
    * what THIS visitor toggled inside the widget, not the
    * deployment's admin-set defaults.
    */
-  userPrefs: z17.record(z17.string(), z17.unknown()).optional(),
+  userPrefs: z16.record(z16.string(), z16.unknown()).optional(),
   // Present only when the server rotated the request `visitorId` /
   // `conversationId`. Purely advisory — client must adopt the response ids
   // verbatim regardless of whether this block is present.
-  rebind: z17.object({
+  rebind: z16.object({
     visitorId: rebindReasonSchema.optional(),
     conversationId: rebindReasonSchema.optional()
   }).loose().optional()
@@ -806,7 +793,6 @@ var startConversationResponseSchema = z17.object({
 import "zod";
 var COMMON_SECTIONS = [
   "theme",
-  "welcome",
   "header",
   "composer",
   "footer",
@@ -833,15 +819,15 @@ function widgetSettingsSchemaForMode(mode) {
 var ALL_MODES = ["floating", "inline", "standalone", "page", "modal", "drawer"];
 
 // src/schema/json-schema.ts
-import { z as z19 } from "zod";
+import { z as z18 } from "zod";
 function emitJsonSchema() {
   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: z19.toJSONSchema(widgetConfigSchema),
-      StartConversationResponse: z19.toJSONSchema(startConversationResponseSchema)
+      WidgetConfig: z18.toJSONSchema(widgetConfigSchema),
+      StartConversationResponse: z18.toJSONSchema(startConversationResponseSchema)
     }
   };
 }
@@ -912,8 +898,6 @@ export {
   userContextSchema,
   uuid7Schema,
   voiceModeSchema,
-  welcomeAnimationSchema,
-  welcomeOptionsSchema,
   widgetConfigPartialSchema,
   widgetConfigSchema,
   widgetSettingsPartialSchema,

package/style.css

@@ -1,4 +1,4 @@
-:host{--helpai-accent-user: #5B5BD6;--helpai-accent: var(--helpai-accent-user);--helpai-accent-text: #FFFFFF;--helpai-radius: 12px;--helpai-radius-sm: 8px;--helpai-radius-md: 10px;--helpai-radius-lg: 16px;--helpai-font: Inter, system-ui, -apple-system, 'Segoe UI', sans-serif;--helpai-font-display: var(--helpai-font);--helpai-font-mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;--helpai-bg: oklch(1 0 0);--helpai-bg-elevated: oklch(.9789 .0029 278.3);--helpai-surface: var(--helpai-bg-elevated);--helpai-muted: var(--helpai-fg-muted);--helpai-hover: oklch(.1686 .011 278.3 / .06);--helpai-fg: oklch(.1686 .011 278.3);--helpai-fg-muted: oklch(.4932 .0301 278.3);--helpai-border: oklch(.9312 .0084 278.3);--helpai-border-strong: oklch(.8757 .0131 278.3);--helpai-bubble-user: var(--helpai-accent);--helpai-bubble-user-text: var(--helpai-accent-text);--helpai-bubble-assistant: oklch(.9638 .0058 278.3);--helpai-bubble-assistant-text: var(--helpai-fg);--helpai-on-accent: var(--helpai-accent-text);--helpai-success: oklch(.6456 .1654 151.53);--helpai-warning: oklch(.7135 .1494 74.05);--helpai-danger: oklch(.5966 .1818 24.51);--helpai-danger-text: oklch(.5054 .1905 27.52);--helpai-danger-bg: oklch(.5966 .1818 24.51 / .1);--helpai-neutral: oklch(.7137 .0192 278.3);--helpai-focus: var(--helpai-accent);--helpai-shadow-panel: 0 8px 24px -8px rgba(13, 15, 20, .18), 0 24px 64px -24px rgba(13, 15, 20, .24);--helpai-shadow-card: 0 1px 2px rgba(13, 15, 20, .06), 0 4px 12px -6px rgba(13, 15, 20, .12);--helpai-backdrop: oklch(.1686 .011 278.3 / .55);--helpai-shadow-fab: 0 6px 16px -4px color-mix(in oklch, var(--helpai-accent) 45%, transparent), 0 12px 32px -12px rgba(13, 15, 20, .25);--helpai-z-fab: 2147483600;--helpai-z-panel: 2147483601;--helpai-panel-w: 380px;--helpai-panel-h: 600px;--helpai-fab-size: 56px;--helpai-space-1: 4px;--helpai-space-2: 8px;--helpai-space-3: 12px;--helpai-space-4: 16px;--helpai-space-5: 20px;--helpai-space-6: 24px;--helpai-space-8: 32px;--helpai-text-scale: 1;--helpai-text-xs: calc(12px * var(--helpai-text-scale));--helpai-text-sm: calc(13px * var(--helpai-text-scale));--helpai-text-base: calc(15px * var(--helpai-text-scale));--helpai-text-md: calc(16px * var(--helpai-text-scale));--helpai-text-lg: calc(18px * var(--helpai-text-scale));--helpai-text-xl: calc(22px * var(--helpai-text-scale));--helpai-text-2xl: calc(30px * var(--helpai-text-scale))}:host([data-text-size="small"]){--helpai-text-scale: .9}:host([data-text-size="large"]){--helpai-text-scale: 1.15}:host{--helpai-ease: cubic-bezier(.2, .7, .2, 1);--helpai-ease-out: cubic-bezier(.2, .7, .2, 1);--helpai-ease-in: cubic-bezier(.4, 0, 1, 1);--helpai-ease-in-out: cubic-bezier(.65, 0, .35, 1);--helpai-dur-quick: .12s;--helpai-dur-base: .22s;--helpai-dur-slow: .32s;font-family:var(--helpai-font);color:var(--helpai-fg);color-scheme:light;--helpai-color-scheme: light}:host([data-theme="dark"]){--helpai-bg: oklch(.1783 .0128 278.3);--helpai-bg-elevated: oklch(.2232 .0182 278.3);--helpai-fg: oklch(.9368 .01 278.3);--helpai-fg-muted: oklch(.7048 .0296 278.3);--helpai-border: oklch(.2752 .0266 278.3);--helpai-border-strong: oklch(.335 .0291 278.3);--helpai-hover: oklch(.9368 .01 278.3 / .08);--helpai-bubble-assistant: oklch(.2474 .0311 278.3);--helpai-bubble-assistant-text: var(--helpai-fg);--helpai-danger-text: oklch(.8077 .1035 19.57);--helpai-danger-bg: oklch(.5966 .1818 24.51 / .18);--helpai-shadow-panel: 0 8px 24px -8px rgba(0, 0, 0, .6), 0 24px 64px -24px rgba(0, 0, 0, .7);--helpai-shadow-card: 0 1px 2px rgba(0, 0, 0, .4), 0 4px 12px -6px rgba(0, 0, 0, .5);--helpai-backdrop: rgba(0, 0, 0, .65);color-scheme:dark;--helpai-color-scheme: dark}@media(prefers-color-scheme:dark){:host([data-theme="auto"]){--helpai-bg: oklch(.1783 .0128 278.3);--helpai-bg-elevated: oklch(.2232 .0182 278.3);--helpai-fg: oklch(.9368 .01 278.3);--helpai-fg-muted: oklch(.7048 .0296 278.3);--helpai-border: oklch(.2752 .0266 278.3);--helpai-border-strong: oklch(.335 .0291 278.3);--helpai-hover: oklch(.9368 .01 278.3 / .08);--helpai-bubble-assistant: oklch(.2474 .0311 278.3);--helpai-bubble-assistant-text: var(--helpai-fg);--helpai-shadow-panel: 0 8px 24px -8px rgba(0, 0, 0, .6), 0 24px 64px -24px rgba(0, 0, 0, .7);color-scheme:dark;--helpai-color-scheme: dark}}@supports (color: oklch(from red l c h)){:host{--helpai-accent: oklch(from var(--helpai-accent-user) clamp(.3, l, .62) c h);--helpai-accent-text: oklch(from var(--helpai-accent) clamp(0, (l / .623 - 1) * -infinity, 1) 0 h)}:host([data-theme="dark"]){--helpai-accent: oklch(from var(--helpai-accent-user) clamp(.65, l, .85) c h)}@media(prefers-color-scheme:dark){:host([data-theme="auto"]){--helpai-accent: oklch(from var(--helpai-accent-user) clamp(.65, l, .85) c h)}}}@media(prefers-reduced-motion:reduce){:host{--helpai-dur-quick: 1ms;--helpai-dur-base: 1ms;--helpai-dur-slow: 1ms}}
+:host{--helpai-accent-user: #5B5BD6;--helpai-accent: var(--helpai-accent-user);--helpai-accent-text-user: #FFFFFF;--helpai-accent-text: var(--helpai-accent-text-user);--helpai-radius: 12px;--helpai-radius-sm: 8px;--helpai-radius-md: 10px;--helpai-radius-lg: 16px;--helpai-font: Inter, system-ui, -apple-system, 'Segoe UI', sans-serif;--helpai-font-display: var(--helpai-font);--helpai-font-mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;--helpai-bg: oklch(1 0 0);--helpai-bg-elevated: oklch(.9789 .0029 278.3);--helpai-surface: var(--helpai-bg-elevated);--helpai-muted: var(--helpai-fg-muted);--helpai-hover: oklch(.1686 .011 278.3 / .06);--helpai-fg: oklch(.1686 .011 278.3);--helpai-fg-muted: oklch(.4932 .0301 278.3);--helpai-border: oklch(.9312 .0084 278.3);--helpai-border-strong: oklch(.8757 .0131 278.3);--helpai-bubble-user: var(--helpai-accent);--helpai-bubble-user-text: var(--helpai-accent-text);--helpai-bubble-assistant: oklch(.9638 .0058 278.3);--helpai-bubble-assistant-text: var(--helpai-fg);--helpai-on-accent: var(--helpai-accent-text);--helpai-success: oklch(.6456 .1654 151.53);--helpai-warning: oklch(.7135 .1494 74.05);--helpai-danger: oklch(.5966 .1818 24.51);--helpai-danger-text: oklch(.5054 .1905 27.52);--helpai-danger-bg: oklch(.5966 .1818 24.51 / .1);--helpai-neutral: oklch(.7137 .0192 278.3);--helpai-focus: var(--helpai-accent);--helpai-shadow-panel: 0 8px 24px -8px rgba(13, 15, 20, .18), 0 24px 64px -24px rgba(13, 15, 20, .24);--helpai-shadow-card: 0 1px 2px rgba(13, 15, 20, .06), 0 4px 12px -6px rgba(13, 15, 20, .12);--helpai-backdrop: oklch(.1686 .011 278.3 / .55);--helpai-shadow-fab: 0 6px 16px -4px color-mix(in oklch, var(--helpai-accent) 45%, transparent), 0 12px 32px -12px rgba(13, 15, 20, .25);--helpai-z-fab: 2147483600;--helpai-z-panel: 2147483601;--helpai-panel-w: 380px;--helpai-panel-h: 600px;--helpai-fab-size: 56px;--helpai-space-1: 4px;--helpai-space-2: 8px;--helpai-space-3: 12px;--helpai-space-4: 16px;--helpai-space-5: 20px;--helpai-space-6: 24px;--helpai-space-8: 32px;--helpai-text-scale: 1;--helpai-text-xs: calc(12px * var(--helpai-text-scale));--helpai-text-sm: calc(13px * var(--helpai-text-scale));--helpai-text-base: calc(15px * var(--helpai-text-scale));--helpai-text-md: calc(16px * var(--helpai-text-scale));--helpai-text-lg: calc(18px * var(--helpai-text-scale));--helpai-text-xl: calc(22px * var(--helpai-text-scale));--helpai-text-2xl: calc(30px * var(--helpai-text-scale))}:host([data-text-size="small"]){--helpai-text-scale: .9}:host([data-text-size="large"]){--helpai-text-scale: 1.15}:host{--helpai-ease: cubic-bezier(.2, .7, .2, 1);--helpai-ease-out: cubic-bezier(.2, .7, .2, 1);--helpai-ease-in: cubic-bezier(.4, 0, 1, 1);--helpai-ease-in-out: cubic-bezier(.65, 0, .35, 1);--helpai-dur-quick: .12s;--helpai-dur-base: .22s;--helpai-dur-slow: .32s;font-family:var(--helpai-font);color:var(--helpai-fg);color-scheme:light;--helpai-color-scheme: light}:host([data-theme="dark"]){--helpai-bg: oklch(.1783 .0128 278.3);--helpai-bg-elevated: oklch(.2232 .0182 278.3);--helpai-fg: oklch(.9368 .01 278.3);--helpai-fg-muted: oklch(.7048 .0296 278.3);--helpai-border: oklch(.2752 .0266 278.3);--helpai-border-strong: oklch(.335 .0291 278.3);--helpai-hover: oklch(.9368 .01 278.3 / .08);--helpai-bubble-assistant: oklch(.2474 .0311 278.3);--helpai-bubble-assistant-text: var(--helpai-fg);--helpai-danger-text: oklch(.8077 .1035 19.57);--helpai-danger-bg: oklch(.5966 .1818 24.51 / .18);--helpai-shadow-panel: 0 8px 24px -8px rgba(0, 0, 0, .6), 0 24px 64px -24px rgba(0, 0, 0, .7);--helpai-shadow-card: 0 1px 2px rgba(0, 0, 0, .4), 0 4px 12px -6px rgba(0, 0, 0, .5);--helpai-backdrop: rgba(0, 0, 0, .65);color-scheme:dark;--helpai-color-scheme: dark}@media(prefers-color-scheme:dark){:host([data-theme="auto"]){--helpai-bg: oklch(.1783 .0128 278.3);--helpai-bg-elevated: oklch(.2232 .0182 278.3);--helpai-fg: oklch(.9368 .01 278.3);--helpai-fg-muted: oklch(.7048 .0296 278.3);--helpai-border: oklch(.2752 .0266 278.3);--helpai-border-strong: oklch(.335 .0291 278.3);--helpai-hover: oklch(.9368 .01 278.3 / .08);--helpai-bubble-assistant: oklch(.2474 .0311 278.3);--helpai-bubble-assistant-text: var(--helpai-fg);--helpai-shadow-panel: 0 8px 24px -8px rgba(0, 0, 0, .6), 0 24px 64px -24px rgba(0, 0, 0, .7);color-scheme:dark;--helpai-color-scheme: dark}}@supports (color: oklch(from red l c h)){:host{--helpai-accent: oklch(from var(--helpai-accent-user) clamp(.3, l, .62) c h);--helpai-accent-text: oklch(from var(--helpai-accent) clamp(0, (l / .623 - 1) * -infinity, 1) 0 h)}:host([data-theme="dark"]){--helpai-accent: oklch(from var(--helpai-accent-user) clamp(.65, l, .85) c h)}@media(prefers-color-scheme:dark){:host([data-theme="auto"]){--helpai-accent: oklch(from var(--helpai-accent-user) clamp(.65, l, .85) c h)}}}@media(prefers-reduced-motion:reduce){:host{--helpai-dur-quick: 1ms;--helpai-dur-base: 1ms;--helpai-dur-slow: 1ms}}
 
 *,*:before,*:after{box-sizing:border-box;margin:0;padding:0;border:0}button{font:inherit;color:inherit;background:none;cursor:pointer;-webkit-appearance:none;appearance:none;line-height:1}button:focus-visible,[tabindex]:focus-visible,textarea:focus-visible,input:focus-visible{outline:2px solid var(--helpai-accent);outline-offset:2px}textarea,input{font:inherit;color:inherit;background:none;border:0;outline:0;resize:none}a{color:var(--helpai-accent);text-decoration:underline;text-underline-offset:2px}img,svg{display:block;max-width:100%}ul,ol{list-style:none}.helpai-app{display:block;width:100%;height:100%;font-family:var(--helpai-font);-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale;font-feature-settings:"cv11","ss01","ss03"}.helpai-sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}