@helpai/elements 1.12.7 → 1.12.9

package/llms.txt

@@ -1,11 +1,11 @@
 # Help AI Elements
 
-> Help AI's AI chat widget for any website: an AI agent that answers visitors from the customer's own help content, can hand the chat to a person, and shows Help articles and News. Install it with one script tag, the `<web-ai-chat>` element, the npm API or the React kit. These docs match @helpai/elements@1.12.7.
+> Help AI's AI chat widget for any website: an AI agent that answers visitors from the customer's own help content, can hand the chat to a person, and shows Help articles and News. Install it with one script tag, the `<web-ai-chat>` element, the npm API or the React kit. These docs match @helpai/elements@1.12.9.
 
 What a coding agent needs to install it right the first time:
 
 - Two values come from the deployment's Install page in the Help AI dashboard: the public key (`agent_pk_…`) and the AI agent deployment id (a UUID). Both belong in browser code. The deployment's secret key never does.
-- Plain HTML, WordPress or any CMS: `<script src="https://cdn.help.ai/sdk/js/elements/1.12.7/elements.js" data-public-key="agent_pk_…" data-ai-agent-deployment-id="…" defer></script>`.
+- Plain HTML, WordPress or any CMS: `<script src="https://cdn.help.ai/sdk/js/elements/1.12.9/elements.js" data-public-key="agent_pk_…" data-ai-agent-deployment-id="…" defer></script>`.
 - React, Next.js, Remix: install `@helpai/elements` and render `<HelpAI publicKey="…" aiAgentDeploymentId="…" />` from `@helpai/elements/react` once, in the root layout. `useHelpAI()` in any component returns `{ state, ask, open, close, reset }`. It is server-render safe; import everything from `@helpai/elements/react`.
 - Vue, Svelte, Angular and other bundlers: `import '@helpai/elements/web-component'`, then `<web-ai-chat public-key="…" ai-agent-deployment-id="…"></web-ai-chat>`. JSX typings: `@helpai/elements/jsx/react`, `/jsx/vue`, `/jsx/svelte`.
 - Site buttons need no JavaScript: `data-helpai-ask="Which plan fits a team of 10?"` puts the question in the chat, `data-helpai-open="help"` opens a tab (`home`, `chats`, `help`, `news`). In code, `ask(text)` fills the composer and sends only with `{ send: true }`.
@@ -18,23 +18,23 @@ What a coding agent needs to install it right the first time:
 
 ## Docs
 
-- [Quickstart](https://cdn.help.ai/sdk/js/elements/1.12.7/docs/quickstart.md): credentials, the install paths and a first check, in five minutes
-- [Installation](https://cdn.help.ai/sdk/js/elements/1.12.7/docs/installation.md): every install path in depth: script tag, async loader, npm, web component, CDN URLs and version pinning
-- [Frameworks](https://cdn.help.ai/sdk/js/elements/1.12.7/docs/frameworks.md): the React kit (`<HelpAI />`, `useHelpAI()`), Next.js, Remix, Vue, Nuxt, Svelte, Astro, Angular, WordPress, Shopify, Webflow
-- [Configuration](https://cdn.help.ai/sdk/js/elements/1.12.7/docs/configuration.md): every option by group, with examples
-- [Option reference](https://cdn.help.ai/sdk/js/elements/1.12.7/docs/options.md): the table of every option, generated from the schemas; authoritative
-- [API reference](https://cdn.help.ai/sdk/js/elements/1.12.7/docs/api-reference.md): exports, instance methods (`ask`, `open`, `state`, `ready`, `reset`, …), the global API, no-script triggers, deep links, JSX typings
-- [Events and hooks](https://cdn.help.ai/sdk/js/elements/1.12.7/docs/events-and-hooks.md): every event and its payload, `on()` and `hook()`
-- [Page tools](https://cdn.help.ai/sdk/js/elements/1.12.7/docs/page-tools.md): WebMCP-shaped tools the AI agent calls on your page (`registerTool`, `tools`, `useHelpAITool`, `<form toolname>`), run once in the browser
-- [Theming](https://cdn.help.ai/sdk/js/elements/1.12.7/docs/theming.md): colors, shapes, fonts, launcher styles, `theme: "host"` and `::part()` styling
-- [Recipes](https://cdn.help.ai/sdk/js/elements/1.12.7/docs/recipes.md): copy-paste solutions for common integrations
-- [Analytics](https://cdn.help.ai/sdk/js/elements/1.12.7/docs/analytics.md): sending widget activity to Google Analytics, Segment, PostHog and other trackers
-- [Security and privacy](https://cdn.help.ai/sdk/js/elements/1.12.7/docs/security-privacy.md): isolation, CSP, what the widget stores and sends
-- [Browser support](https://cdn.help.ai/sdk/js/elements/1.12.7/docs/browser-support.md): supported browsers and fallbacks
-- [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.12.7/docs/troubleshooting.md): an install that does not show, connect or answer
-- [FAQ](https://cdn.help.ai/sdk/js/elements/1.12.7/docs/faq.md): short answers to common questions
-- [Overview](https://cdn.help.ai/sdk/js/elements/1.12.7/docs/README.md): the whole SDK on one page
+- [Quickstart](https://cdn.help.ai/sdk/js/elements/1.12.9/docs/quickstart.md): credentials, the install paths and a first check, in five minutes
+- [Installation](https://cdn.help.ai/sdk/js/elements/1.12.9/docs/installation.md): every install path in depth: script tag, async loader, npm, web component, CDN URLs and version pinning
+- [Frameworks](https://cdn.help.ai/sdk/js/elements/1.12.9/docs/frameworks.md): the React kit (`<HelpAI />`, `useHelpAI()`), Next.js, Remix, Vue, Nuxt, Svelte, Astro, Angular, WordPress, Shopify, Webflow
+- [Configuration](https://cdn.help.ai/sdk/js/elements/1.12.9/docs/configuration.md): every option by group, with examples
+- [Option reference](https://cdn.help.ai/sdk/js/elements/1.12.9/docs/options.md): the table of every option, generated from the schemas; authoritative
+- [API reference](https://cdn.help.ai/sdk/js/elements/1.12.9/docs/api-reference.md): exports, instance methods (`ask`, `open`, `state`, `ready`, `reset`, …), the global API, no-script triggers, deep links, JSX typings
+- [Events and hooks](https://cdn.help.ai/sdk/js/elements/1.12.9/docs/events-and-hooks.md): every event and its payload, `on()` and `hook()`
+- [Page tools](https://cdn.help.ai/sdk/js/elements/1.12.9/docs/page-tools.md): WebMCP-shaped tools the AI agent calls on your page (`registerTool`, `tools`, `useHelpAITool`, `<form toolname>`), run once in the browser
+- [Theming](https://cdn.help.ai/sdk/js/elements/1.12.9/docs/theming.md): colors, shapes, fonts, launcher styles, `theme: "host"` and `::part()` styling
+- [Recipes](https://cdn.help.ai/sdk/js/elements/1.12.9/docs/recipes.md): copy-paste solutions for common integrations
+- [Analytics](https://cdn.help.ai/sdk/js/elements/1.12.9/docs/analytics.md): sending widget activity to Google Analytics, Segment, PostHog and other trackers
+- [Security and privacy](https://cdn.help.ai/sdk/js/elements/1.12.9/docs/security-privacy.md): isolation, CSP, what the widget stores and sends
+- [Browser support](https://cdn.help.ai/sdk/js/elements/1.12.9/docs/browser-support.md): supported browsers and fallbacks
+- [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.12.9/docs/troubleshooting.md): an install that does not show, connect or answer
+- [FAQ](https://cdn.help.ai/sdk/js/elements/1.12.9/docs/faq.md): short answers to common questions
+- [Overview](https://cdn.help.ai/sdk/js/elements/1.12.9/docs/README.md): the whole SDK on one page
 
 ## Optional
 
-- [Every doc in one file](https://cdn.help.ai/sdk/js/elements/1.12.7/llms-full.txt): the docs above, concatenated
+- [Every doc in one file](https://cdn.help.ai/sdk/js/elements/1.12.9/llms-full.txt): the docs above, concatenated

package/package.json

@@ -117,5 +117,5 @@
   ],
   "type": "module",
   "types": "./index.d.ts",
-  "version": "1.12.7"
+  "version": "1.12.9"
 }

package/react.d.ts

@@ -39,7 +39,7 @@ interface ClientStorage {
  * populated {@link Strings} map. UI components then read `strings.send` as a
  * normal property access — no per-render lookup, no per-render allocation.
  */
-type StringKey = 'launcherOpen' | 'launcherLabel' | 'panelTitle' | 'composerPlaceholder' | 'send' | 'stop' | 'queueMessage' | 'removeQueuedMessage' | 'compactingContext' | 'attach' | 'micStart' | 'micStop' | 'micUnsupported' | 'expand' | 'collapse' | 'fullscreen' | 'exitFullscreen' | 'popOut' | 'resizeHandle' | 'scrollToBottom' | 'close' | 'moreActions' | 'soundOn' | 'soundOff' | 'language' | 'theme' | 'themeAuto' | 'themeLight' | 'themeDark' | 'textSize' | 'textSizeSmall' | 'textSizeNormal' | 'textSizeLarge' | 'history' | 'historyTitle' | 'historyEmpty' | 'historyLoading' | 'historyBack' | 'historyContinue' | 'loadMoreConversations' | 'conversationLoading' | 'loadPreviousMessages' | 'conversationClosed' | 'startNewConversation' | 'talkToOperator' | 'connectingOperator' | 'noOperatorAvailable' | 'chattingWithOperator' | 'cancelOperatorRequest' | 'dateToday' | 'dateYesterday' | 'dateLastWeek' | 'dateOlder' | 'newConversation' | 'dropZone' | 'attachmentTooLarge' | 'attachmentTooMany' | 'attachmentMimeRejected' | 'errorRetry' | 'errorGeneric' | 'errorRateLimited' | 'loading' | 'visualPreparing' | 'visualError' | 'visualPartial' | 'thinking' | 'thoughts' | 'toolResult' | 'sources' | 'feedbackUp' | 'feedbackDown' | 'feedbackThanks' | 'copy' | 'copied' | 'collapseSidebar' | 'expandSidebar' | 'formSubmit' | 'formSkip' | 'formSubmitted' | 'formSkipped' | 'formFillOut' | 'formRequired' | 'formInvalidEmail' | 'formInvalidTel' | 'formInvalidUrl' | 'formInvalidNumber' | 'formTooShort' | 'formTooLong' | 'formNumberTooSmall' | 'formNumberTooLarge' | 'formPatternMismatch' | 'formChooseAtLeast' | 'formChooseAtMost' | 'formOther' | 'formOtherPlaceholder' | 'inputRequired' | 'inputBadge' | 'inputAnswered' | 'inputSkipped' | 'inputSubmit' | 'inputSubmitHint' | 'inputSkip' | 'showOptions' | 'hideOptions' | 'qtypeText' | 'qtypeEmail' | 'qtypePhone' | 'qtypeNumber' | 'qtypeDate' | 'qtypeChooseOne' | 'qtypeChooseAny' | 'qtypeBoolean' | 'confirmYes' | 'confirmNo' | 'approve' | 'reject' | 'approvalPrompt' | 'approvalBody' | 'approvalYourResponse' | 'approvalEditHint' | 'approvalSubmitting' | 'edit' | 'toolParameters' | 'statusAwaiting' | 'statusResponded' | 'statusCompleted' | 'statusDenied' | 'statusError' | 'statusRunning' | 'statusSuperseded' | 'statusIncomplete' | 'tabHome' | 'tabConversations' | 'tabHelp' | 'tabNews' | 'modulesEmpty' | 'moduleBack' | 'contentLoading' | 'contentHelpful' | 'homeGreeting' | 'homeGreetingNamed' | 'homeGreetingLead' | 'homeSearchPlaceholder' | 'homeAskPlaceholder' | 'homeWhatsNew' | 'homeContentTitle' | 'homeStatus' | 'helpTitle' | 'helpSearchPlaceholder' | 'helpEmpty' | 'helpLoading' | 'helpSearchEmpty' | 'helpShowMore' | 'newsTitle' | 'newsEmpty' | 'newsLoading' | 'newsBack' | 'newsPublishedAt' | 'newsShowMore' | 'newsUnseen';
+type StringKey = 'launcherOpen' | 'launcherLabel' | 'panelTitle' | 'composerPlaceholder' | 'send' | 'stop' | 'queueMessage' | 'removeQueuedMessage' | 'compactingContext' | 'attach' | 'file' | 'micStart' | 'micStop' | 'micUnsupported' | 'expand' | 'collapse' | 'fullscreen' | 'exitFullscreen' | 'popOut' | 'resizeHandle' | 'scrollToBottom' | 'close' | 'moreActions' | 'soundOn' | 'soundOff' | 'language' | 'theme' | 'themeAuto' | 'themeLight' | 'themeDark' | 'textSize' | 'textSizeSmall' | 'textSizeNormal' | 'textSizeLarge' | 'history' | 'historyTitle' | 'historyEmpty' | 'historyLoading' | 'historyBack' | 'historyContinue' | 'loadMoreConversations' | 'conversationLoading' | 'loadPreviousMessages' | 'conversationClosed' | 'startNewConversation' | 'talkToOperator' | 'connectingOperator' | 'noOperatorAvailable' | 'chattingWithOperator' | 'cancelOperatorRequest' | 'dateToday' | 'dateYesterday' | 'dateLastWeek' | 'dateOlder' | 'newConversation' | 'dropZone' | 'attachmentTooLarge' | 'attachmentTooMany' | 'attachmentMimeRejected' | 'errorRetry' | 'errorGeneric' | 'errorRateLimited' | 'loading' | 'visualPreparing' | 'visualError' | 'visualPartial' | 'thinking' | 'thoughts' | 'toolResult' | 'sources' | 'feedbackUp' | 'feedbackDown' | 'feedbackThanks' | 'copy' | 'copied' | 'collapseSidebar' | 'expandSidebar' | 'formSubmit' | 'formSkip' | 'formSubmitted' | 'formSkipped' | 'formFillOut' | 'formRequired' | 'formInvalidEmail' | 'formInvalidTel' | 'formInvalidUrl' | 'formInvalidNumber' | 'formTooShort' | 'formTooLong' | 'formNumberTooSmall' | 'formNumberTooLarge' | 'formPatternMismatch' | 'formChooseAtLeast' | 'formChooseAtMost' | 'formOther' | 'formOtherPlaceholder' | 'inputRequired' | 'inputBadge' | 'inputAnswered' | 'inputSkipped' | 'inputSubmit' | 'inputSubmitHint' | 'inputSkip' | 'showOptions' | 'hideOptions' | 'qtypeText' | 'qtypeEmail' | 'qtypePhone' | 'qtypeNumber' | 'qtypeDate' | 'qtypeChooseOne' | 'qtypeChooseAny' | 'qtypeBoolean' | 'confirmYes' | 'confirmNo' | 'approve' | 'reject' | 'approvalPrompt' | 'approvalBody' | 'approvalYourResponse' | 'approvalEditHint' | 'approvalSubmitting' | 'edit' | 'toolParameters' | 'statusAwaiting' | 'statusResponded' | 'statusCompleted' | 'statusDenied' | 'statusError' | 'statusRunning' | 'statusSuperseded' | 'statusIncomplete' | 'tabHome' | 'tabConversations' | 'tabHelp' | 'tabNews' | 'modulesEmpty' | 'moduleBack' | 'contentLoading' | 'contentHelpful' | 'homeGreeting' | 'homeGreetingNamed' | 'homeGreetingLead' | 'homeSearchPlaceholder' | 'homeAskPlaceholder' | 'homeWhatsNew' | 'homeContentTitle' | 'homeStatus' | 'helpTitle' | 'helpSearchPlaceholder' | 'helpEmpty' | 'helpLoading' | 'helpSearchEmpty' | 'helpShowMore' | 'newsTitle' | 'newsEmpty' | 'newsLoading' | 'newsBack' | 'newsPublishedAt' | 'newsShowMore' | 'newsUnseen';
 /** A partial map for one locale — what overrides look like on the wire. */
 type LocaleStrings = Partial<Record<StringKey, string>>;
 /**
@@ -259,8 +259,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.
@@ -349,6 +350,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;
   /**
@@ -425,6 +428,8 @@ interface ResolvedForm {
   description?: string;
   submitLabel?: string;
   skippable: boolean;
+  /** Locks the message box until submit/skip (false → the visitor keeps chatting). */
+  blocking: boolean;
   frequency: FormFrequency;
   /** Mirror answers into `userContext` (false → PII, endpoint only). */
   mirrorToContext: boolean;
@@ -1459,6 +1464,7 @@ 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";
@@ -1801,6 +1807,7 @@ 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";
@@ -2144,6 +2151,7 @@ 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";
@@ -2449,6 +2457,7 @@ 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";