@runtypelabs/persona 3.21.3 → 3.22.0

package/README.md

@@ -459,6 +459,72 @@ const myRules: ParseRule[] = [
 ];
 ```
 
+#### Optional: smart-dom-reader provider
+
+The default reader above is a zero-dependency `TreeWalker` and **does not pierce shadow
+DOM**. For pages built from web components, an optional provider backed by a
+vendored copy of [`@mcp-b/smart-dom-reader`](https://github.com/WebMCP-org/npm-packages/tree/main/packages/smart-dom-reader)
+ships as a **separate entry point**, `@runtypelabs/persona/smart-dom-reader`. It is **not**
+imported by the main bundle, so consumers who never import this subpath pay nothing — no
+extra install, no bundle weight, no IIFE/CDN impact.
+
+It adds, over the default reader: **Shadow-DOM piercing**, form grouping, and page
+landmarks/state — while still emitting Persona's `EnrichedPageElement[]` shape so it
+formats and flows through the same pipeline.
+
+```ts
+import initAgentWidget from '@runtypelabs/persona';
+import { createSmartDomReaderContextProvider } from '@runtypelabs/persona/smart-dom-reader';
+
+initAgentWidget({
+  // ...config
+  contextProviders: [
+    createSmartDomReaderContextProvider({
+      // 'interactive' (default) | 'full' — full adds semantic content AND is required
+      // for shadow-DOM piercing (shadow descendants surface only in full mode).
+      mode: 'full',
+      contextKey: 'pageContext',            // key under payload.context (default)
+      // root: document.querySelector('main') // optional: scope to a subtree, skip chrome
+    })
+  ]
+});
+```
+
+`contextProviders` are honored on the **agent** send path (`buildAgentPayload` merges each
+provider's result into `payload.context` on every request). If you drive the legacy
+flow/`buildPayload` path, call `collectSmartDomContext()` yourself and inject the result.
+
+You can also use the pieces directly:
+
+```ts
+import {
+  collectSmartDomContext,      // → EnrichedPageElement[] (parity with collectEnrichedPageContext)
+  smartDomResultToEnriched     // pure mapper: SmartDOMResult → EnrichedPageElement[]
+} from '@runtypelabs/persona/smart-dom-reader';
+import { formatEnrichedContext } from '@runtypelabs/persona';
+
+const pageContext = formatEnrichedContext(collectSmartDomContext({ mode: 'full' }));
+```
+
+Both `collectSmartDomContext()` and `createSmartDomReaderContextProvider()` accept a
+`root` element to scope extraction to a subtree (parity with `collectEnrichedPageContext`'s
+`root`) — useful to read only your main content region and skip nav/sidebars. Shadow DOM
+inside the subtree is still pierced.
+
+> **Actionability caveat.** Persona's click loop (`utils/actions.ts`) drives
+> `document.querySelector`, which cannot pierce shadow roots or evaluate XPath. The adapter
+> therefore prefers plain-CSS selectors; elements reachable only via shadow-piercing or
+> XPath selectors are surfaced to the model as **context only** and are **not clickable**
+> through the current `message_and_click` handler.
+
+> **Why vendored, not a dependency.** Every published version of `@mcp-b/smart-dom-reader`
+> (2.3.1–3.0.0) is mis-published — its `package.json` points to `dist/index.js` /
+> `dist/index.d.ts` while the build only ships `.mjs` / `.d.mts`, so it cannot be imported
+> by name in Node or any bundler. The library (MIT, zero-dep) is therefore vendored under
+> `packages/widget/src/vendor/smart-dom-reader/`; see that directory's `README.md` for
+> provenance and update steps. Once upstream republishes correctly this can revert to a
+> normal optional peer dependency.
+
 ### DOM Events
 
 The widget dispatches custom DOM events that you can listen to for integration with your application:
@@ -2278,6 +2344,7 @@ config: {
 | `showReasoning` | `boolean?` | Show thinking/reasoning bubbles. Default: `true`. |
 | `showToolCalls` | `boolean?` | Show tool usage bubbles. Default: `true`. |
 | `showEventStreamToggle` | `boolean?` | Show the event stream inspector toggle in the header. Default: `false`. |
+| `composerHistory` | `boolean?` | `Up`/`Down` arrows in the composer navigate previously sent user messages for re-entry/editing (shell / Slack style). Entered only when the caret is at the start of the input, so multi-line cursor movement is preserved. Default: `true`. |
 | `eventStream` | `EventStreamConfig?` | Event stream inspector configuration: `badgeColors`, `timestampFormat`, `showSequenceNumbers`, `maxEvents`, `descriptionFields`, `classNames`. |
 | `artifacts` | `AgentWidgetArtifactsFeature?` | Artifact sidebar: `enabled`, `allowedTypes`, optional `layout` (see below). |
 

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

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

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

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

package/dist/animations/{types-CWPIj66R.d.cts → types-BZVr1YOV.d.cts}

@@ -73,6 +73,16 @@ type AgentMessageMetadata = {
      * `POST /v1/dispatch/resume` with the user's answer keyed by tool name.
      */
     awaitingLocalTool?: boolean;
+    /**
+     * The provider per-call id (`toolu_…`) carried on the `step_await` /
+     * `flow_await` events for a LOCAL tool (core#3878). Present only when the
+     * server emits it. Two PARALLEL calls to the same tool in one turn share a
+     * `toolName` (and a collapsed `toolId`) but get DISTINCT `webMcpToolCallId`s,
+     * so this is the key the widget batches a single `/resume` on — preferred
+     * over tool name, which collides for same-tool parallel calls. Absent →
+     * fall back to the legacy name-keyed resume contract.
+     */
+    webMcpToolCallId?: string;
     /**
      * Set to `true` once the user has picked / typed / dismissed an answer for
      * an `ask_user_question` tool call, so renderers stop re-mounting the

package/dist/animations/{types-CWPIj66R.d.ts → types-BZVr1YOV.d.ts}

@@ -73,6 +73,16 @@ type AgentMessageMetadata = {
      * `POST /v1/dispatch/resume` with the user's answer keyed by tool name.
      */
     awaitingLocalTool?: boolean;
+    /**
+     * The provider per-call id (`toolu_…`) carried on the `step_await` /
+     * `flow_await` events for a LOCAL tool (core#3878). Present only when the
+     * server emits it. Two PARALLEL calls to the same tool in one turn share a
+     * `toolName` (and a collapsed `toolId`) but get DISTINCT `webMcpToolCallId`s,
+     * so this is the key the widget batches a single `/resume` on — preferred
+     * over tool name, which collides for same-tool parallel calls. Absent →
+     * fall back to the legacy name-keyed resume contract.
+     */
+    webMcpToolCallId?: string;
     /**
      * Set to `true` once the user has picked / typed / dismissed an answer for
      * an `ask_user_question` tool call, so renderers stop re-mounting the

package/dist/animations/wipe.d.cts

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

package/dist/animations/wipe.d.ts

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