@runtypelabs/persona 3.31.1 → 3.34.0

package/README.md

@@ -17,6 +17,8 @@ pnpm build
 - `dist/index.js` (ESM), `dist/index.cjs` (CJS), and `dist/index.global.js` (IIFE) provide different module formats.
 - `dist/widget.css` is the prefixed Tailwind bundle.
 - `dist/install.global.js` is the automatic installer script for easy script tag installation.
+- `dist/launcher.global.js` is the tiny critical launcher used by deferred script-tag installs before the full panel bundle loads.
+- `dist/webmcp-polyfill.js` is the lazy WebMCP polyfill chunk used by the IIFE bundle only when `config.webmcp.enabled` is true and the page has no `document.modelContext`.
 
 ### Using with modules
 
@@ -92,33 +94,36 @@ const docked = initAgentWidget({
 | --- | --- | --- |
 | `target` | `string \| HTMLElement` | CSS selector or element where widget mounts. |
 | `config` | `AgentWidgetConfig` | Widget configuration object (see the [Configuration Reference](./docs/CONFIGURATION-REFERENCE.md)). |
-| `useShadowDom` | `boolean` | Use Shadow DOM for style isolation (default: `true`). |
+| `useShadowDom` | `boolean` | Use Shadow DOM for style isolation (default: `false`). |
 | `onChatReady` | `() => void` | Callback fired when the widget is initialized and its API is callable. |
 | `onReady` | `() => void` | **Deprecated** alias of `onChatReady`; still works, removed in the next major. |
 | `windowKey` | `string` | If provided, stores the controller on `window[windowKey]` for global access. Automatically cleaned up on `destroy()`. |
 
 When `config.launcher.mountMode` is `'docked'`, `target` is treated as the page container that Persona should wrap. Use a concrete element such as `#workspace-main`; `body` and `html` are rejected.
 
+**Height contract:** the docked shell sizes itself with `height: 100%`, so give it a definite height — usually `html, body { height: 100% }` or a fixed-height app-shell container around the target. If no ancestor provides one, the panel is clamped to `dock.maxHeight` (default `100dvh`; `resize`/`emerge` are also sticky-pinned — `push`/`overlay` get the cap only) so it stays viewport-sized and scrolls internally, and a console warning explains the fix. Override the cap with a CSS length or disable the guard with `dock.maxHeight: false`.
+
 With **`dock.reveal: 'resize'`** (default), a **closed** dock uses a **`0px`** column. **`'emerge'`** uses the same **column width** animation (content reflows) but the chat panel stays **`dock.width`** wide and is **clipped** by the growing slot—like a normal-width widget emerging from the edge. **`'overlay'`** overlays with `transform`. **`'push'`** uses a sliding track (Shopify-style). The built-in launcher stays hidden in docked mode—open with **`controller.open()`** (or your own chrome).
 
 **Rounded / card layout:** `initAgentWidget` inserts a flex **shell** as the **direct child** of your target’s **parent**, with your `target` in the content column and the dock beside it. Put border-radius, border, and `overflow: hidden` on that **parent** (or an ancestor that wraps only the shell) so the dock column sits inside the same visual card as your content.
 
-**Inner push/overlay:** With `reveal: 'push'` or `'overlay'`, only the wrapped node moves. Use a **narrow `target`** (e.g. a main canvas div). For **`dock.side: 'left'`**, place a persistent rail **in flow** next to the stage (e.g. flex `[nav | stage]`) so the dock doesn’t open **under** the sidebar. For a **right** dock, you can instead use a **full-width** stage with an **absolute** left rail if you want the canvas to translate **behind** that rail.
+**Inner push/overlay:** With `reveal: 'push'` or `'overlay'`, only the wrapped node moves. Use a **narrow `target`** (e.g. a main canvas div). For **`dock.side: 'left'`**, place a persistent rail **in flow** next to the stage (e.g. flex `[nav | stage]`) so the dock doesn’t open **under** the sidebar. For a **right** dock, you can instead use a **full-width** stage with an **absolute** left rail if you want the canvas to translate **behind** that rail. `position: fixed`/`sticky` content inside the target stays **viewport-anchored** (it is not pushed), so offset it while the dock is open if needed, e.g. `[data-persona-dock-open="true"] .my-fixed-bar { right: 420px; }`.
 
-> **Security note:** When you return HTML from `postprocessMessage`, make sure you sanitise it before injecting into the page. The provided postprocessors (`markdownPostprocessor`, `directivePostprocessor`) do not perform sanitisation.
+> **Security note:** Persona sanitizes rendered message HTML with DOMPurify by default (`sanitize: true`), including output returned from `postprocessMessage`, `markdownPostprocessor`, and `directivePostprocessor`. If your custom postprocessor intentionally returns tags or attributes outside the built-in allowlist, provide `sanitize: (html) => ...`; only set `sanitize: false` for fully trusted content.
 
 ### Documentation
 
 The full reference lives in [`docs/`](./docs/) and the theming guide:
 
 - [Programmatic Control & Events](./docs/PROGRAMMATIC-CONTROL.md) — controller API, message hooks and injection, enriched DOM context, WebMCP page tools, DOM and controller events, state loading
-- [UI Features & Components](./docs/UI-COMPONENTS.md) — message actions and feedback, loading indicators, ask-user-question, dropdown menus, button utilities, dynamic forms
-- [Script Tag Installation & Framework Integration](./docs/INSTALLATION-FRAMEWORKS.md) — automatic installer, manual script tag setup, React, Next.js, Remix, Gatsby, and Astro guides
-- [Configuration Reference](./docs/CONFIGURATION-REFERENCE.md) — every config option: core, client token mode, agent mode, UI & theme, launcher, layout, voice, tool calls, suggestion chips, state & storage
+- [UI Features & Components](./docs/UI-COMPONENTS.md) — message actions and feedback, loading/idle indicators, approvals, built-in `ask_user_question` and `suggest_replies` tools, dropdown menus, button utilities, dynamic forms
+- [Script Tag Installation & Framework Integration](./docs/INSTALLATION-FRAMEWORKS.md) — automatic installer, deferred launcher lifecycle hooks, manual script tag setup, React, Next.js, Remix, Gatsby, and Astro guides
+- [Configuration Reference](./docs/CONFIGURATION-REFERENCE.md) — every config option: core, client token mode, agent mode, UI & theme, launcher/docking, layout, voice, WebMCP, tool calls, features, suggestion chips, state & storage
 - [Stream Parser Configuration](./docs/STREAM-PARSERS.md) — JSON, XML, and plain-text stream parsers and custom parser factories
-- [THEME-CONFIG.md](./THEME-CONFIG.md) — the complete theme and design-token reference
 - [Message Injection](./docs/MESSAGE-INJECTION.md) — full injection and component-directive reference
 - [Dynamic Forms](./docs/DYNAMIC-FORMS.md) — field schema, form styles, and recipes
+- [Code Generator](./docs/CODE-GENERATOR.md) — `@runtypelabs/persona/codegen` options for CLI/server-side snippet generation
+- [THEME-CONFIG.md](./THEME-CONFIG.md) — the complete theme and design-token reference
 
 ### Optional proxy server
 
@@ -196,7 +201,9 @@ Add `RUNTYPE_API_KEY` to your environment. The proxy constructs the Runtype payl
 
 ### Development notes
 
-- The widget streams results using SSE and mirrors the backend `flow_complete`/`step_chunk` events.
-- Tailwind-esc classes are prefixed with `tvw-` and scoped to `[data-persona-root]`, so they won't collide with the host page.
-- Run `pnpm dev` from the repository root to boot the example proxy (`examples/proxy`) and the vanilla demo (`examples/embedded-app`).
+- The widget streams results using SSE and mirrors Runtype flow/agent events, including `step_await` local-tool pauses and `/resume` continuations.
+- Tailwind classes are prefixed with `tvw-` and scoped to `[data-persona-root]`, so they won't collide with the host page.
+- Run `pnpm dev` from the repository root to boot the example proxy (`examples/vercel-edge`) and the vanilla demo (`examples/embedded-app`).
 - The proxy prefers port `43111` but automatically selects the next free port if needed.
+- `features.askUserQuestion.expose` and `features.suggestReplies.expose` advertise built-in LOCAL client tools through `clientTools[]`; leave `expose` off if the flow already declares those tools server-side.
+- `webmcp: { enabled: true }` snapshots page-registered tools on `document.modelContext`, sends them as `clientTools[]`, executes returned `webmcp:*` calls in the browser, and resumes the paused execution.

package/dist/animations/glyph-cycle.d.cts

@@ -1,4 +1,4 @@
-import { S as StreamAnimationPlugin } from './types-quh7NmYD.cjs';
+import { S as StreamAnimationPlugin } from './types-CthJFfNx.cjs';
 
 declare const glyphCycle: StreamAnimationPlugin;
 

package/dist/animations/glyph-cycle.d.ts

@@ -1,4 +1,4 @@
-import { S as StreamAnimationPlugin } from './types-quh7NmYD.js';
+import { S as StreamAnimationPlugin } from './types-CthJFfNx.js';
 
 declare const glyphCycle: StreamAnimationPlugin;
 

package/dist/animations/{types-quh7NmYD.d.cts → types-CthJFfNx.d.cts}

@@ -659,6 +659,13 @@ type AgentMessageMetadata = {
      * paginated stepper. Persists alongside `askUserQuestionAnswers`.
      */
     askUserQuestionIndex?: number;
+    /**
+     * Set to `true` once a `suggest_replies` tool call's fire-and-forget
+     * `/resume` has been accepted by the server. Persisted belt-and-suspenders
+     * mirror of the in-memory resolved-key dedupe, so hydration/re-emit paths
+     * never re-resume the call.
+     */
+    suggestRepliesResolved?: boolean;
 };
 /**
  * Context passed to plugin lifecycle hooks. Carries the live DOM references

package/dist/animations/{types-quh7NmYD.d.ts → types-CthJFfNx.d.ts}

@@ -659,6 +659,13 @@ type AgentMessageMetadata = {
      * paginated stepper. Persists alongside `askUserQuestionAnswers`.
      */
     askUserQuestionIndex?: number;
+    /**
+     * Set to `true` once a `suggest_replies` tool call's fire-and-forget
+     * `/resume` has been accepted by the server. Persisted belt-and-suspenders
+     * mirror of the in-memory resolved-key dedupe, so hydration/re-emit paths
+     * never re-resume the call.
+     */
+    suggestRepliesResolved?: boolean;
 };
 /**
  * Context passed to plugin lifecycle hooks. Carries the live DOM references

package/dist/animations/wipe.d.cts

@@ -1,4 +1,4 @@
-import { S as StreamAnimationPlugin } from './types-quh7NmYD.cjs';
+import { S as StreamAnimationPlugin } from './types-CthJFfNx.cjs';
 
 declare const wipe: StreamAnimationPlugin;
 

package/dist/animations/wipe.d.ts

@@ -1,4 +1,4 @@
-import { S as StreamAnimationPlugin } from './types-quh7NmYD.js';
+import { S as StreamAnimationPlugin } from './types-CthJFfNx.js';
 
 declare const wipe: StreamAnimationPlugin;
 

package/dist/codegen.cjs

@@ -1,4 +1,4 @@
-"use strict";var $=Object.defineProperty;var M=Object.getOwnPropertyDescriptor;var R=Object.getOwnPropertyNames;var v=Object.prototype.hasOwnProperty;var I=(e,r)=>{for(var n in r)$(e,n,{get:r[n],enumerable:!0})},W=(e,r,n,s)=>{if(r&&typeof r=="object"||typeof r=="function")for(let o of R(r))!v.call(e,o)&&o!==n&&$(e,o,{get:()=>r[o],enumerable:!(s=M(r,o))||s.enumerable});return e};var H=e=>W($({},"__esModule",{value:!0}),e);var B={};I(B,{generateCodeSnippet:()=>_});module.exports=H(B);var x="3.31.1";var c=x;function u(e){if(e!==void 0)return typeof e=="string"?e:Array.isArray(e)?`[${e.map(r=>r.toString()).join(", ")}]`:e.toString()}function D(e){if(e)return{getHeaders:u(e.getHeaders),onFeedback:u(e.onFeedback),onCopy:u(e.onCopy),requestMiddleware:u(e.requestMiddleware),actionHandlers:u(e.actionHandlers),actionParsers:u(e.actionParsers),postprocessMessage:u(e.postprocessMessage),contextProviders:u(e.contextProviders),streamParser:u(e.streamParser)}}var A=`({ text, message }: any) => {
+"use strict";var $=Object.defineProperty;var M=Object.getOwnPropertyDescriptor;var R=Object.getOwnPropertyNames;var v=Object.prototype.hasOwnProperty;var I=(e,r)=>{for(var n in r)$(e,n,{get:r[n],enumerable:!0})},W=(e,r,n,s)=>{if(r&&typeof r=="object"||typeof r=="function")for(let o of R(r))!v.call(e,o)&&o!==n&&$(e,o,{get:()=>r[o],enumerable:!(s=M(r,o))||s.enumerable});return e};var H=e=>W($({},"__esModule",{value:!0}),e);var B={};I(B,{generateCodeSnippet:()=>_});module.exports=H(B);var x="3.34.0";var c=x;function u(e){if(e!==void 0)return typeof e=="string"?e:Array.isArray(e)?`[${e.map(r=>r.toString()).join(", ")}]`:e.toString()}function D(e){if(e)return{getHeaders:u(e.getHeaders),onFeedback:u(e.onFeedback),onCopy:u(e.onCopy),requestMiddleware:u(e.requestMiddleware),actionHandlers:u(e.actionHandlers),actionParsers:u(e.actionParsers),postprocessMessage:u(e.postprocessMessage),contextProviders:u(e.contextProviders),streamParser:u(e.streamParser)}}var A=`({ text, message }: any) => {
   const jsonSource = (message as any).rawContent || text || message.content;
   if (!jsonSource || typeof jsonSource !== 'string') return null;
   let cleanJson = jsonSource

package/dist/codegen.js

@@ -1,4 +1,4 @@
-var S="3.31.1";var c=S;function u(e){if(e!==void 0)return typeof e=="string"?e:Array.isArray(e)?`[${e.map(r=>r.toString()).join(", ")}]`:e.toString()}function T(e){if(e)return{getHeaders:u(e.getHeaders),onFeedback:u(e.onFeedback),onCopy:u(e.onCopy),requestMiddleware:u(e.requestMiddleware),actionHandlers:u(e.actionHandlers),actionParsers:u(e.actionParsers),postprocessMessage:u(e.postprocessMessage),contextProviders:u(e.contextProviders),streamParser:u(e.streamParser)}}var x=`({ text, message }: any) => {
+var S="3.34.0";var c=S;function u(e){if(e!==void 0)return typeof e=="string"?e:Array.isArray(e)?`[${e.map(r=>r.toString()).join(", ")}]`:e.toString()}function T(e){if(e)return{getHeaders:u(e.getHeaders),onFeedback:u(e.onFeedback),onCopy:u(e.onCopy),requestMiddleware:u(e.requestMiddleware),actionHandlers:u(e.actionHandlers),actionParsers:u(e.actionParsers),postprocessMessage:u(e.postprocessMessage),contextProviders:u(e.contextProviders),streamParser:u(e.streamParser)}}var x=`({ text, message }: any) => {
   const jsonSource = (message as any).rawContent || text || message.content;
   if (!jsonSource || typeof jsonSource !== 'string') return null;
   let cleanJson = jsonSource