@runtypelabs/persona 3.34.1 → 3.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "3.34.1",
+  "version": "3.35.0",
   "description": "Themeable, pluggable streaming agent widget for websites, in plain JS with support for voice input and reasoning / tool output.",
   "type": "module",
   "main": "dist/index.cjs",
@@ -27,6 +27,11 @@
       "import": "./dist/theme-editor.js",
       "require": "./dist/theme-editor.cjs"
     },
+    "./theme-editor/preview": {
+      "types": "./dist/theme-editor-preview.d.ts",
+      "import": "./dist/theme-editor-preview.js",
+      "require": "./dist/theme-editor-preview.cjs"
+    },
     "./testing": {
       "types": "./dist/testing.d.ts",
       "import": "./dist/testing.js",
@@ -37,6 +42,11 @@
       "import": "./dist/smart-dom-reader.js",
       "require": "./dist/smart-dom-reader.cjs"
     },
+    "./voice-worklet-player": {
+      "types": "./dist/voice-worklet-player.d.ts",
+      "import": "./dist/voice-worklet-player.js",
+      "require": "./dist/voice-worklet-player.cjs"
+    },
     "./plugin-kit": {
       "types": "./dist/plugin-kit.d.ts",
       "import": "./dist/plugin-kit.js",
@@ -109,17 +119,21 @@
     "access": "public"
   },
   "scripts": {
-    "build": "rimraf dist && pnpm run build:styles && pnpm run build:client && pnpm run build:installer && pnpm run build:launcher && pnpm run build:webmcp-polyfill && pnpm run build:theme-ref && pnpm run build:codegen && pnpm run build:theme-editor && pnpm run build:testing && pnpm run build:smart-dom-reader && pnpm run build:plugin-kit && pnpm run build:animations",
+    "build": "rimraf dist && pnpm run build:styles && pnpm run build:markdown-parsers && pnpm run build:client && pnpm run build:installer && pnpm run build:launcher && pnpm run build:webmcp-polyfill && pnpm run build:runtype-tts && pnpm run build:theme-ref && pnpm run build:codegen && pnpm run build:theme-editor && pnpm run build:theme-editor-preview && pnpm run build:testing && pnpm run build:smart-dom-reader && pnpm run build:voice-worklet-player && pnpm run build:plugin-kit && pnpm run build:animations",
+    "build:markdown-parsers": "tsup --config tsup.markdown-parsers.config.ts",
     "build:plugin-kit": "tsup src/plugin-kit.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",
     "build:theme-editor": "tsup src/theme-editor.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",
+    "build:theme-editor-preview": "tsup src/theme-editor-preview.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",
     "build:testing": "tsup src/testing.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",
     "build:smart-dom-reader": "tsup src/smart-dom-reader.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",
+    "build:voice-worklet-player": "tsup src/voice-worklet-player.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",
     "build:animations": "tsup src/animations/glyph-cycle.ts src/animations/wipe.ts --format esm,cjs --minify --dts --out-dir dist/animations --no-splitting",
     "build:theme-ref": "tsup src/theme-reference.ts --format esm,cjs --minify --dts",
     "build:codegen": "tsup src/codegen.ts --format esm,cjs --minify --dts",
     "build:styles": "node -e \"const fs=require('fs');fs.mkdirSync('dist',{recursive:true});fs.copyFileSync('src/styles/widget.css','dist/widget.css');\"",
     "build:client": "tsup src/index.ts --format esm,cjs --minify --sourcemap --splitting false --dts --loader \".css=text\" && tsup --config tsup.global.config.ts && node -e \"const fs=require('fs');for(const ext of ['.global.js','.global.js.map']){const from='dist/index-global'+ext;if(fs.existsSync(from))fs.renameSync(from,'dist/index'+ext);}\"",
     "build:webmcp-polyfill": "tsup --config tsup.webmcp-polyfill.config.ts",
+    "build:runtype-tts": "tsup --config tsup.runtype-tts.config.ts",
     "build:installer": "tsup src/install.ts --format iife --global-name SiteAgentInstaller --out-dir dist --minify --sourcemap --no-splitting",
     "build:launcher": "tsup src/launcher-global.ts --format iife --global-name AgentWidgetLauncher --minify --sourcemap --splitting false --out-dir dist && node -e \"const fs=require('fs');for(const ext of ['.global.js','.global.js.map']){const from='dist/launcher-global'+ext;if(fs.existsSync(from))fs.renameSync(from,'dist/launcher'+ext);}\"",
     "lint": "eslint . --ext .ts",

package/src/animations/glyph-cycle.ts

@@ -2,14 +2,13 @@ import type { StreamAnimationPlugin } from "../types";
 import { registerStreamAnimationPlugin } from "../utils/stream-animation";
 
 /**
- * Glyph-cycle animation — "hacker-settling" reveal.
+ * Glyph-cycle animation: "hacker-settling" reveal.
  *
  * Each arriving char briefly cycles through a sequence of random glyphs
  * before locking in to its final character. Unlike a pure CSS effect, this
  * needs JS because it mutates `textContent` per tick. To keep idiomorph from
  * clobbering mid-cycle work, each cycling span carries
- * `data-preserve-runtime="stream-glyph-cycle"` until its cycle completes —
- * morph honors that attribute as an absolute skip marker.
+ * `data-preserve-runtime="stream-glyph-cycle"` until its cycle completes: * morph honors that attribute as an absolute skip marker.
  *
  * A short buffer (`BUFFER_THRESHOLD`) holds the bubble empty (with the
  * typing indicator) until enough text has arrived to run a visible reveal.
@@ -19,7 +18,7 @@ import { registerStreamAnimationPlugin } from "../utils/stream-animation";
  * settling wave flows through the full message.
  *
  * Ships as a subpath module so consumers who don't want it pay zero cost.
- * Importing this module auto-registers the plugin globally — just add the
+ * Importing this module auto-registers the plugin globally: just add the
  * import and set `features.streamAnimation.type = "glyph-cycle"`.
  *
  * ```ts
@@ -54,8 +53,7 @@ const STYLES = `
 const GLYPHS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789#$%&@";
 const TICK_COUNT = 10;
 // Base interval between glyph swaps (ms). Scaled by the widget's configured
-// `speed` so the cycle feels coherent with the rest of the stream animation —
-// faster speed → snappier cycling, slower speed → more deliberate flicker.
+// `speed` so the cycle feels coherent with the rest of the stream animation:// faster speed → snappier cycling, slower speed → more deliberate flicker.
 const BASE_TICK_MS = 120;
 const DEFAULT_STEP_MS = 120;
 // Probability that each later still-cycling sibling gets re-randomized on
@@ -63,7 +61,7 @@ const DEFAULT_STEP_MS = 120;
 const CROSS_FLICKER_PROBABILITY = 0.4;
 // Hold the stream back until at least this many chars have arrived. Once
 // released, every char is rendered as a random glyph and settles in order
-// from the start — so the visible animation carries through the full text.
+// from the start, so the visible animation carries through the full text.
 const BUFFER_THRESHOLD = 50;
 
 const getStepMs = (container: HTMLElement | null): number => {
@@ -96,7 +94,7 @@ const flickerLaterSiblings = (span: HTMLElement): void => {
   const container = span.closest(".persona-stream-glyph-cycle") as HTMLElement | null;
   if (!container) return;
   // Any scheduled char that still has its final char stashed is "pending
-  // or cycling" — both kinds are valid flicker targets. Settled chars have
+  // or cycling": both kinds are valid flicker targets. Settled chars have
   // `data-glyph-cycle-final` deleted and are excluded.
   const unsettled = container.querySelectorAll<HTMLElement>(
     ".persona-stream-char[data-glyph-cycle-final]"
@@ -115,8 +113,8 @@ const flickerLaterSiblings = (span: HTMLElement): void => {
 };
 
 // Per-container timestamp tracking: when the next char's cycle should settle.
-// Each char starts cycling immediately on schedule — no static placeholder
-// wait — and finishes when `Date.now() >= settleAt`. This slot advances by
+// Each char starts cycling immediately on schedule: no static placeholder
+// wait, and finishes when `Date.now() >= settleAt`. This slot advances by
 // one stagger step per schedule, so the burst settles left-to-right while
 // every char is visibly flickering from the moment it enters the DOM.
 const containerNextSettleAt = new WeakMap<Element, number>();
@@ -139,8 +137,7 @@ const observeStagger = (container: Element | null, now: number): number => {
   let observed = containerArrivalMs.get(container) ?? DEFAULT_ARRIVAL_MS;
   if (last !== undefined) {
     const interval = now - last;
-    // Skip near-zero intervals (burst within one MutationObserver batch) —
-    // they don't reflect the real stream cadence.
+    // Skip near-zero intervals (burst within one MutationObserver batch):    // they don't reflect the real stream cadence.
     if (interval > 1) {
       observed = observed * (1 - EMA_ALPHA) + interval * EMA_ALPHA;
       containerArrivalMs.set(container, observed);
@@ -180,7 +177,7 @@ const scheduleCycle = (span: HTMLElement): void => {
   span.dataset.glyphCycleScheduled = "true";
   // Stash the target char and immediately paint a random glyph so the span
   // reads as "cycling" even before its staggered kickoff. Also opt out of
-  // morph — without this, streamed token re-renders would overwrite our
+  // morph: without this, streamed token re-renders would overwrite our
   // placeholder glyph with the final char.
   span.dataset.glyphCycleFinal = finalChar;
   span.setAttribute("data-preserve-runtime", "stream-glyph-cycle");
@@ -275,7 +272,7 @@ export const glyphCycle: StreamAnimationPlugin = {
     // `**template literal**`) would trigger a render of the partial
     // `**template`, which markdown emits as literal asterisks, gets
     // wrapped + marked `data-preserve-runtime`, and leaks through later
-    // morphs — the final structure can't reconcile.
+    // morphs: the final structure can't reconcile.
     let boldPairs = 0;
     let lastSafe = -1;
     let i = 0;

package/src/animations/wipe.ts

@@ -2,7 +2,7 @@ import type { StreamAnimationPlugin } from "../types";
 import { registerStreamAnimationPlugin } from "../utils/stream-animation";
 
 /**
- * Wipe animation — per-word left-to-right mask reveal.
+ * Wipe animation: per-word left-to-right mask reveal.
  *
  * Each arriving word is revealed via a soft feathered mask that sweeps from
  * right to left. Uses `mask-image` (not `background-clip: text`) so the

package/src/ask-user-question-tool.test.ts

@@ -137,7 +137,7 @@ describe("AgentWidgetClient - built-in ask_user_question exposure", () => {
 
   it("changes the clientTools fingerprint when toggled (diff-only resend)", () => {
     // In client-token mode the widget only resends the full clientTools[]
-    // when the fingerprint changes — toggling expose must change it so the
+    // when the fingerprint changes: toggling expose must change it so the
     // server actually learns about (or forgets) the built-in tool.
     const webMcpOnly = [{ name: "search", description: "s" }];
     const withBuiltIn = [ASK_USER_QUESTION_CLIENT_TOOL, ...webMcpOnly];

package/src/ask-user-question-tool.ts

@@ -2,7 +2,7 @@
  * Built-in `ask_user_question` client tool.
  *
  * The widget can advertise this tool to the agent on every dispatch via
- * `clientTools[]` (set `features.askUserQuestion.expose: true`) — the same
+ * `clientTools[]` (set `features.askUserQuestion.expose: true`): the same
  * wire surface WebMCP page tools ride. The server registers it as a LOCAL
  * tool under its bare name (`origin: 'sdk'` tools are not `webmcp:`-prefixed),
  * so when the model calls it the execution pauses with a `step_await`
@@ -13,7 +13,7 @@
  * This replaces the previous integrator burden of hand-declaring the tool in
  * a flow's `runtimeTools` and keeping that schema in sync with the renderer.
  * Flows that already declare `ask_user_question` server-side should leave
- * `expose` off — the model would otherwise see the tool twice.
+ * `expose` off: the model would otherwise see the tool twice.
  */
 
 import {
@@ -28,8 +28,7 @@ import type { AgentWidgetConfig, ClientToolDefinition } from "./types";
 
 /**
  * JSON Schema for the tool's parameters. Mirrors {@link AskUserQuestionPayload}
- * — the shape `parseAskUserQuestionPayload` hydrates the answer sheet from —
- * so the schema the model is held to and the schema the renderer expects can
+ *, the shape `parseAskUserQuestionPayload` hydrates the answer sheet from,  * so the schema the model is held to and the schema the renderer expects can
  * never drift.
  */
 export const ASK_USER_QUESTION_PARAMETERS_SCHEMA = {
@@ -57,7 +56,7 @@ export const ASK_USER_QUESTION_PARAMETERS_SCHEMA = {
             minItems: 2,
             maxItems: 4,
             description:
-              '2-4 distinct choices. Do NOT add an "Other" option — free text is automatic.',
+              '2-4 distinct choices. Do NOT add an "Other" option: free text is automatic.',
             items: {
               type: "object",
               properties: {
@@ -102,7 +101,7 @@ export const ASK_USER_QUESTION_CLIENT_TOOL: ClientToolDefinition = {
   name: ASK_USER_QUESTION_TOOL_NAME,
   description:
     "Ask the user multiple-choice questions and wait for their answers. Use " +
-    "only when blocked on a decision that is the user's to make — a " +
+    "only when blocked on a decision that is the user's to make: a " +
     "preference, a choice between valid approaches, or information you " +
     "cannot infer. Each question offers 2-4 options plus an automatic " +
     "free-text input. The result maps each question to its answer (an array " +
@@ -119,8 +118,7 @@ export const ASK_USER_QUESTION_CLIENT_TOOL: ClientToolDefinition = {
  *
  * Each tool is gated on BOTH of its feature flags: `expose` opts the tool
  * into the agent's catalog, and `enabled !== false` guarantees the widget can
- * actually render UI (and, for fire-and-forget tools, auto-resume) for it —
- * exposing a tool with its feature disabled would park the execution on a
+ * actually render UI (and, for fire-and-forget tools, auto-resume) for it: * exposing a tool with its feature disabled would park the execution on a
  * generic tool bubble with no way to advance.
  */
 export const builtInClientToolsForDispatch = (

package/src/client.test.ts

@@ -2348,7 +2348,7 @@ describe('AgentWidgetClient - Out-of-Order Sequence Reordering', () => {
           };
           e({ type: 'flow_start', flowId: 'f1', flowName: 'Test', totalSteps: 1 });
           e({ type: 'step_start', id: 's1', name: 'Prompt', stepType: 'prompt', index: 1, totalSteps: 1 });
-          // No seq field — should append in arrival order
+          // No seq field: should append in arrival order
           e({ type: 'step_delta', id: 's1', text: 'Hello ' });
           e({ type: 'step_delta', id: 's1', text: 'world' });
           e({ type: 'step_delta', id: 's1', text: '!' });
@@ -2386,7 +2386,7 @@ describe('AgentWidgetClient - Out-of-Order Sequence Reordering', () => {
           };
           e({ type: 'flow_start', flowId: 'f1', flowName: 'Test', totalSteps: 1 });
           e({ type: 'step_start', id: 's1', name: 'Prompt', stepType: 'prompt', index: 1, totalSteps: 1 });
-          // seq=3 arrives first (leading gap — seq 1 and 2 arrive later)
+          // seq=3 arrives first (leading gap: seq 1 and 2 arrive later)
           e({ type: 'step_delta', id: 's1', text: 'c', partId: 'text_0', seq: 3 });
           e({ type: 'step_delta', id: 's1', text: 'a', partId: 'text_0', seq: 1 });
           e({ type: 'step_delta', id: 's1', text: 'b', partId: 'text_0', seq: 2 });
@@ -2425,7 +2425,7 @@ describe('AgentWidgetClient - Out-of-Order Sequence Reordering', () => {
           };
           e({ type: 'flow_start', flowId: 'f1', flowName: 'Test', totalSteps: 1 });
           e({ type: 'step_start', id: 's1', name: 'Prompt', stepType: 'prompt', index: 1, totalSteps: 1 });
-          // reason_delta uses sequenceIndex, step_delta uses seq — same counter
+          // reason_delta uses sequenceIndex, step_delta uses seq: same counter
           e({ type: 'reason_start', reasoningId: 'r1', hidden: false, done: false });
           e({ type: 'reason_delta', reasoningId: 'r1', reasoningText: 'thinking', hidden: false, done: false, sequenceIndex: 1 });
           e({ type: 'reason_complete', reasoningId: 'r1', hidden: false, done: true });
@@ -2518,7 +2518,7 @@ describe('AgentWidgetClient - Out-of-Order Sequence Reordering', () => {
           };
           e({ type: 'flow_start', flowId: 'f1', flowName: 'Test', totalSteps: 1 });
           e({ type: 'step_start', id: 's1', name: 'Prompt', stepType: 'prompt', index: 1, totalSteps: 1 });
-          // Only a seq=3 event arrives — seq=1 and seq=2 are never delivered.
+          // Only a seq=3 event arrives: seq=1 and seq=2 are never delivered.
           // Without the end-of-stream flush, this event would be stranded in
           // the reorder buffer and never emitted.
           e({ type: 'step_delta', id: 's1', text: 'tail', partId: 'text_0', seq: 3 });
@@ -2607,7 +2607,7 @@ describe('AgentWidgetClient - Out-of-Order Sequence Reordering', () => {
             controller.enqueue(encoder.encode(`data: ${JSON.stringify(data)}\n\n`));
           };
           e({ type: 'flow_start', flowId: 'f1', flowName: 'Test', totalSteps: 1 });
-          // Only sequenced event — but seq > 1 so it would be buffered.
+          // Only sequenced event, but seq > 1 so it would be buffered.
           e({ type: 'error', error: 'boom', seq: 2 });
           controller.close();
         },
@@ -2767,7 +2767,7 @@ describe('AgentWidgetClient - stopReason propagation', () => {
 });
 
 // ============================================================================
-// Within-turn text/tool interleaving — assistant text bubbles must seal at
+// Within-turn text/tool interleaving: assistant text bubbles must seal at
 // each agent_tool_start so the chronological text→tool→text→tool sequence
 // renders as distinct timeline entries instead of one merged bubble that
 // appears below all the tool cards.
@@ -3004,7 +3004,7 @@ describe('AgentWidgetClient - agent_turn text/tool interleaving', () => {
 // step_await (LOCAL tool pause) + resumeFlow
 // ============================================================================
 
-describe('AgentWidgetClient — step_await parsing', () => {
+describe('AgentWidgetClient: step_await parsing', () => {
   const buildStepAwaitStream = (payload: Record<string, unknown>): ReadableStream<Uint8Array> => {
     const encoder = new TextEncoder();
     const body = `event: step_await\ndata: ${JSON.stringify({ type: 'step_await', ...payload })}\n\n`;
@@ -3196,7 +3196,7 @@ describe('AgentWidgetClient.resumeFlow', () => {
 
     await client.resumeFlow('exec_xyz', { toolu_A: { ok: true } });
 
-    // Session-authed sibling of /v1/client/chat — no Bearer key, sessionId in body.
+    // Session-authed sibling of /v1/client/chat: no Bearer key, sessionId in body.
     expect(capturedUrl).toBe('https://api.runtype.com/v1/client/resume');
     expect(capturedBody).toEqual({
       executionId: 'exec_xyz',
@@ -3239,7 +3239,7 @@ describe('AgentWidgetClient.resumeFlow', () => {
       clientToken: 'ct_live_demo',
       apiUrl: 'https://api.runtype.com',
     });
-    // A stale session that has already expired — a long WebMCP approval wait can
+    // A stale session that has already expired: a long WebMCP approval wait can
     // outlive it, so resumeFlow must not trust this.clientSession directly.
     (client as unknown as { clientSession: { sessionId: string; expiresAt: Date } }).clientSession = {
       sessionId: 'cs_stale',
@@ -3647,7 +3647,7 @@ describe('AgentWidgetClient - agent_media events', () => {
       sseEvent('agent_iteration_start', { executionId: execId, iteration: 1, maxTurns: 1, startedAt: new Date().toISOString(), seq: 2 }),
       sseEvent('agent_turn_start', { executionId: execId, iteration: 1, turnIndex: 0, role: 'assistant', turnId: 'turn_1', seq: 3 }),
       sseEvent('agent_turn_delta', { executionId: execId, iteration: 1, delta: 'Streaming...', contentType: 'text', turnId: 'turn_1', seq: 4 }),
-      // Media arrives mid-stream — earlier text bubble is still streaming.
+      // Media arrives mid-stream: earlier text bubble is still streaming.
       sseEvent('agent_media', {
         executionId: execId, iteration: 1, toolCallId: 'tc_seal', toolName: 'shot',
         media: [{ type: 'media', data: 'PNG', mediaType: 'image/png' }],
@@ -3755,7 +3755,7 @@ describe('AgentWidgetClient - agent_media events', () => {
       sseEvent('agent_iteration_start', { executionId: execId, iteration: 1, maxTurns: 1, startedAt: new Date().toISOString(), seq: 2 }),
       sseEvent('agent_media', {
         executionId: execId, iteration: 1, toolCallId: 'tc_blob', toolName: 'opaque',
-        // mediaType is empty — should not produce a malformed `data:;base64,...` URI.
+        // mediaType is empty: should not produce a malformed `data:;base64,...` URI.
         media: [{ type: 'media', data: 'AAAA', mediaType: '' }],
         seq: 3,
       }),
@@ -4004,7 +4004,7 @@ describe('AgentWidgetClient - diff-only clientTools (client-token)', () => {
       return sse();
     });
     const client = makeClient(TOOLS);
-    // Pre-seed the cache so the first attempt would be fingerprint-only — the
+    // Pre-seed the cache so the first attempt would be fingerprint-only: the
     // server then forces a resend.
     (client as unknown as { lastSentClientToolsFingerprint: string | null; clientToolsFingerprintSessionId: string | null }).lastSentClientToolsFingerprint =
       'stale';

package/src/client.ts

@@ -180,7 +180,7 @@ export class AgentWidgetClient {
   private lastSentClientToolsFingerprint: string | null = null;
   private clientToolsFingerprintSessionId: string | null = null;
 
-  // WebMCP — page-discovered tool consumption (see ./webmcp-bridge).
+  // WebMCP: page-discovered tool consumption (see ./webmcp-bridge).
   // Constructed lazily: null when `config.webmcp?.enabled !== true`.
   private readonly webMcpBridge: WebMcpBridge | null;
 
@@ -206,8 +206,8 @@ export class AgentWidgetClient {
    * Refresh config in place WITHOUT tearing down the live connection or the
    * WebMCP bridge. `AgentWidgetSession.updateConfig` calls this when only
    * connection-irrelevant fields changed (theme, copy, layout, suggestions, …),
-   * so a UI update that lands mid-turn — e.g. a `webmcp:*` tool restyling the
-   * widget while the agent's turn is still streaming — doesn't abandon the
+   * so a UI update that lands mid-turn: e.g. a `webmcp:*` tool restyling the
+   * widget while the agent's turn is still streaming: doesn't abandon the
    * in-flight stream/resume. Connection or request-shaping changes (apiUrl,
    * clientToken, webmcp, headers, parser, …) take the full client rebuild path
    * in the session instead, which is the only place the bridge is recreated.
@@ -215,7 +215,7 @@ export class AgentWidgetClient {
    * Only the live-read `config` is refreshed (e.g. `iterationDisplay`); the
    * constructor-derived request-shaping fields (apiUrl, headers, parser,
    * contextProviders, middleware, …) are left untouched because the session
-   * routes any change to those down the full-rebuild path instead — so they are
+   * routes any change to those down the full-rebuild path instead, so they are
    * guaranteed unchanged here. The `webMcpBridge` instance and its
    * installed-polyfill memo are deliberately preserved, which keeps any
    * in-flight resolve alive.
@@ -254,7 +254,7 @@ export class AgentWidgetClient {
    * WebMCP: execute a returned `webmcp:<name>` tool call against the page's
    * registry and return the normalized MCP-shaped result for `/resume`. The
    * bridge handles confirm-bubble gating, the 30s timeout, error
-   * normalization, and `signal`-driven abort — callers never see throws.
+   * normalization, and `signal`-driven abort: callers never see throws.
    *
    * Returns `null` when WebMCP is not enabled on this client (signal to the
    * session that it should fall back to the legacy local-tool resume path,
@@ -701,7 +701,7 @@ export class AgentWidgetClient {
             this.lastSentClientToolsFingerprint = null;
             continue;
           }
-          // Some other 409 — keep the parsed body for the handler below.
+          // Some other 409: keep the parsed body for the handler below.
           errorData = body ?? { error: 'Chat request failed' };
         }
         break;
@@ -971,10 +971,10 @@ export class AgentWidgetClient {
    * Routes by mode:
    *  - **client-token mode**: POST `${apiBase}/v1/client/resume` (the
    *    session-authenticated sibling of `/v1/client/chat`; runtypelabs/core#3889),
-   *    with the active `sessionId` in the body and no Bearer key — a browser
+   *    with the active `sessionId` in the body and no Bearer key: a browser
    *    client-token page holds no secret. `clientTools` are already persisted
    *    server-side from the dispatch turn, so only `toolOutputs` is re-sent.
-   *  - **dispatch / proxy mode**: POST `${apiUrl}/resume` — Runtype mounts
+   *  - **dispatch / proxy mode**: POST `${apiUrl}/resume`: Runtype mounts
    *    resume as a child of `/v1/dispatch`, so the URL is `${apiUrl}/resume`,
    *    and proxies follow the same shape (`/api/chat/dispatch/resume`).
    *
@@ -998,8 +998,8 @@ export class AgentWidgetClient {
     // The client-token resume route authenticates the session, not a Bearer
     // key. A WebMCP approval can sit awaiting user input for a long time, so by
     // the time we resume the original session may have expired. Re-validate (and
-    // silently re-init if needed) via initSession() — which returns the live
-    // session when `new Date() < expiresAt`, else mints a fresh one — instead of
+    // silently re-init if needed) via initSession(): which returns the live
+    // session when `new Date() < expiresAt`, else mints a fresh one: instead of
     // trusting the possibly-stale `this.clientSession`. (core#3889; BugBot
     // PR #214 r3367875360.)
     let resumeSessionId: string | undefined;
@@ -1069,7 +1069,7 @@ export class AgentWidgetClient {
 
     // Client tools: built-in widget tools (ask_user_question, when exposed)
     // plus the per-turn WebMCP page-registry snapshot. Name collisions are
-    // impossible — WebMCP entries are `webmcp:`-prefixed server-side while
+    // impossible: WebMCP entries are `webmcp:`-prefixed server-side while
     // `sdk`-origin built-ins keep bare names. Both kinds ride the same
     // diff-only fingerprint path in client-token mode. Kept to a single await
     // so dispatch microtask timing is unchanged.
@@ -1185,7 +1185,7 @@ export class AgentWidgetClient {
           // dropping `clientTools` accidentally; the WebMCP wire surface
           // is invisible to them. The integrator can still set
           // `clientTools: []` or `clientTools: undefined` explicitly to
-          // strip them on purpose — we only fall back when the field is
+          // strip them on purpose: we only fall back when the field is
           // entirely absent from the returned object.
           if (
             payload.clientTools !== undefined &&
@@ -1258,7 +1258,7 @@ export class AgentWidgetClient {
           createNewAssistant(result.partId);
         }
 
-        // Update partId tracking (only when partId is provided — backward compatible)
+        // Update partId tracking (only when partId is provided: backward compatible)
         if (result.partId !== undefined) {
           partIdState.current = result.partId;
         }
@@ -1381,7 +1381,7 @@ export class AgentWidgetClient {
     // Messages produced by steps inside a nested flow executed as a tool.
     // Keyed by `${parentToolId}::${nestedStepId}::${partId}` so each nested
     // step (send-stream, prompt) gets its own assistant message, and prompts
-    // with inner tool calls split into one message per text segment — still
+    // with inner tool calls split into one message per text segment: still
     // attributable to the parent tool call.
     const nestedStepMessages = new Map<string, AgentWidgetMessage>();
     // Most-recent partId seen for a given `${toolId}::${stepId}` scope, used
@@ -1406,7 +1406,7 @@ export class AgentWidgetClient {
     ) => `${toolId}::${stepId}::${partId}`;
 
     // Prefix used to sweep every nested message belonging to a single
-    // (toolId, stepId) scope — needed on step_complete to seal any segments
+    // (toolId, stepId) scope: needed on step_complete to seal any segments
     // that are still streaming.
     const getNestedStepPrefix = (toolId: string, stepId: string) =>
       `${toolId}::${stepId}::`;
@@ -1728,7 +1728,7 @@ export class AgentWidgetClient {
         const cur = msg.content ?? "";
         if (mergedDisplay.trim() === "") return;
         // Only replace when empty, or when the stream left a strict prefix of the
-        // authoritative final (truncation). Do not use length alone — multi-segment
+        // authoritative final (truncation). Do not use length alone: multi-segment
         // flows can have a short last bubble whose content is not a prefix of the
         // full step response.
         if (
@@ -1810,7 +1810,7 @@ export class AgentWidgetClient {
     // Declared here so scheduleReadyQueueDrain can reference it; assigned
     // after all handler-scoped variables are initialised (before the SSE loop).
     let drainReadyQueue: () => void;
-    // Two drain paths — both are intentional, do not remove either:
+    // Two drain paths: both are intentional, do not remove either:
     //   1. Microtask drain (scheduleReadyQueueDrain): required when the
     //      buffer's emitter fires from the gap-timeout setTimeout callback,
     //      because there is no surrounding synchronous drain site there.
@@ -1931,7 +1931,7 @@ export class AgentWidgetClient {
           const toolId =
             resolveToolId(payload, true) ?? `tool-${nextSequence()}`;
           const toolName = payload.toolName ?? payload.name;
-          // Suppress tool UI for artifact emit tools — artifacts are handled via artifact_* events
+          // Suppress tool UI for artifact emit tools: artifacts are handled via artifact_* events
           if (isArtifactEmitToolName(toolName)) {
             artifactToolCallIds.add(toolId);
             continue;
@@ -2056,7 +2056,7 @@ export class AgentWidgetClient {
           // Key the message by the per-call `toolCallId` (provider `toolu_…`;
           // core#3878) when present. Two PARALLEL calls to the SAME tool in one
           // turn collapse to an identical `toolId` (`runtime_webmcp:<name>_<ms>`)
-          // and `index: 0` — only `toolCallId` distinguishes them. Keying on it
+          // and `index: 0`: only `toolCallId` distinguishes them. Keying on it
           // (a) keeps the two awaits as DISTINCT messages with their own args
           // instead of the second clobbering the first, and (b) merges each
           // await into the matching `tool_start` bubble (also keyed by
@@ -2105,7 +2105,7 @@ export class AgentWidgetClient {
           emitMessage(toolMessage);
         } else if (payloadType === "text_start") {
           // Lifecycle event: a new text segment is beginning (emitted at tool boundaries).
-          // When toolContext is present this fired inside a nested flow — it must not
+          // When toolContext is present this fired inside a nested flow: it must not
           // seal or rotate the outer assistant message. Nested prompt segmentation is
           // handled via nestedStepMessages keyed by (toolId, stepId).
           if ((payload as any).toolContext?.toolId) {
@@ -2127,7 +2127,7 @@ export class AgentWidgetClient {
           }
         } else if (payloadType === "text_end") {
           // Lifecycle event: current text segment ended (tool call about to start).
-          // When toolContext is present the boundary belongs to a nested flow — leave
+          // When toolContext is present the boundary belongs to a nested flow: leave
           // outer assistant state alone so the outer stream is never interrupted by
           // nested activity.
           if ((payload as any).toolContext?.toolId) {
@@ -2155,7 +2155,7 @@ export class AgentWidgetClient {
           // originated inside a nested flow executed as a tool. Surface it as
           // its own assistant message keyed by the nested step id, so authors
           // who add send-stream / prompt steps inside their flow see them as
-          // real messages in the timeline, in order — rather than merging
+          // real messages in the timeline, in order: rather than merging
           // into the outer assistant bubble or getting buried in the tool
           // card. Each nested step id gets its own message; the parent tool
           // bubble continues to represent the invocation via tool_* events.
@@ -2304,7 +2304,7 @@ export class AgentWidgetClient {
                 const text = typeof result === 'string' ? result : result?.text ?? null;
                 
                 if (text !== null && text.trim() !== "") {
-                  // Parser successfully extracted text — update the chunk's assistant
+                  // Parser successfully extracted text: update the chunk's assistant
                   // (not assistantMessage; text_end may have cleared that ref before microtasks run)
                   assistant.content = text;
                   emitMessage(assistant);
@@ -2478,14 +2478,14 @@ export class AgentWidgetClient {
 
           // Capture optional per-step stopReason emitted by the runtime
           // (e.g. `'max_tool_calls'`, `'length'`). This is the dispatch-mode
-          // fallback — `agent_turn_complete` will overwrite it later in
+          // fallback: `agent_turn_complete` will overwrite it later in
           // agent-loop streams.
           const stepStopReason = (payload as any).stopReason as
             | StopReasonKind
             | undefined;
 
           if (didSplitByPartId) {
-            // Sealed segment(s) — do not create a second bubble from step_complete.
+            // Sealed segment(s): do not create a second bubble from step_complete.
             // Merge authoritative final response into the last sealed segment (fixes async lag).
             if (assistantMessage !== null) {
               const msg: AgentWidgetMessage = assistantMessage;
@@ -2635,7 +2635,7 @@ export class AgentWidgetClient {
         } else if (payloadType === "flow_complete") {
           const finalContent = payload.result?.response;
           if (didSplitByPartId) {
-            // Content was split into multiple assistant messages — the full response
+            // Content was split into multiple assistant messages: the full response
             // in flow_complete would overwrite the last segment. Just finalize streaming.
             if (assistantMessage !== null) {
               const msg: AgentWidgetMessage = assistantMessage;
@@ -2808,8 +2808,7 @@ export class AgentWidgetClient {
           }
 
           // Attach the turn-level stopReason to the assistant message
-          // produced by this turn. Only overwrite the current message —
-          // prior turns already sealed their own stopReason via step_complete.
+          // produced by this turn. Only overwrite the current message:          // prior turns already sealed their own stopReason via step_complete.
           // Falls back to lastAssistantInTurn when the current bubble was
           // sealed at a tool-call boundary mid-turn, so the notice still
           // attaches to the final visible text segment.
@@ -2895,7 +2894,7 @@ export class AgentWidgetClient {
         } else if (payloadType === "agent_media") {
           // A tool produced media (image / audio / video / file). Render it
           // as a synthetic assistant message inserted at the point the tool
-          // completed — between the tool bubble and the next text turn.
+          // completed: between the tool bubble and the next text turn.
           //
           // Wire format is the AI SDK–aligned `MediaContentPart` from
           // @runtypelabs/shared:
@@ -2922,7 +2921,7 @@ export class AgentWidgetClient {
               const data = typeof rec.data === "string" ? rec.data : undefined;
               if (!data) continue;
               // Empty/missing mediaType yields `data:;base64,...` which RFC 2397
-              // resolves to `text/plain` — stamp a default so the data URI is
+              // resolves to `text/plain`: stamp a default so the data URI is
               // well-formed and the part lands in the file bucket.
               mediaType = rawMediaType.length > 0 ? rawMediaType : "application/octet-stream";
               src = `data:${mediaType};base64,${data}`;
@@ -2999,7 +2998,7 @@ export class AgentWidgetClient {
 
             // Seal any in-flight assistant text bubble before splitting the
             // stream. Without this, an orphan bubble retains `streaming: true`
-            // forever — `agent_complete` only finalizes the latest
+            // forever: `agent_complete` only finalizes the latest
             // `assistantMessage`, so the typing/caret indicator would stay on
             // the prior bubble even though no more deltas will arrive.
             const prevAssistant = assistantMessage as AgentWidgetMessage | null;

package/src/codegen.test.ts

@@ -5,7 +5,7 @@ import { VERSION } from "./version";
 
 // The `@runtypelabs/persona/codegen` subpath is the server/Worker-safe entry for
 // snippet generation. It must expose the exact same generator as the internal
-// module (and, transitively, the main barrel) — no fork, no drift.
+// module (and, transitively, the main barrel): no fork, no drift.
 describe("codegen subpath", () => {
   const config = {
     apiUrl: "https://api.example.com/chat",

package/src/codegen.ts

@@ -1,7 +1,7 @@
 /**
  * Pure code-snippet generation entry (`@runtypelabs/persona/codegen`).
  *
- * `generateCodeSnippet` is pure string-templating — it builds install snippets
+ * `generateCodeSnippet` is pure string-templating: it builds install snippets
  * from a widget config and depends only on a type import + the `VERSION`
  * constant. The main `index.ts` barrel re-exports it too, but that barrel pulls
  * in the full widget runtime (`index-core` → idiomorph / marked / DOM), which is

package/src/components/approval-bubble.test.ts

@@ -280,7 +280,7 @@ describe("createApprovalBubble agent reason", () => {
     expect(reasonLine.textContent).toContain(
       "Adds the <b>large</b> blue tee to your cart as you asked."
     );
-    // Plain text rendering — markup in the agent-authored string must not
+    // Plain text rendering: markup in the agent-authored string must not
     // become elements (prompt-injection surface).
     expect(reasonLine.querySelector("b")).toBeNull();
   });

package/src/components/approval-bubble.ts

@@ -173,7 +173,7 @@ export const createApprovalBubble = (
   bubble.id = `bubble-${message.id}`;
   bubble.setAttribute("data-message-id", message.id);
 
-  // Apply styling — use semantic tokens with config overrides
+  // Apply styling: use semantic tokens with config overrides
   bubble.style.backgroundColor = approvalConfig?.backgroundColor ?? "var(--persona-approval-bg, #fefce8)";
   bubble.style.borderColor = approvalConfig?.borderColor ?? "var(--persona-approval-border, #fef08a)";
   bubble.style.boxShadow =
@@ -242,7 +242,7 @@ export const createApprovalBubble = (
 
   // User-facing summary line. The wire `description` is the tool's
   // agent-facing description (prompt prose, usage rules), so it is not shown
-  // here — it lives in the collapsible details section below. Label priority:
+  // here: it lives in the collapsible details section below. Label priority:
   // formatDescription → declared WebMCP `title` → humanized tool name →
   // raw description (no tool name at all).
   const isWebMcpTool =
@@ -276,7 +276,7 @@ export const createApprovalBubble = (
 
   // Agent-authored justification for this specific call. It is the agent's
   // own claim about its intent (attacker-writable under prompt injection), so
-  // it is rendered as plain text via textContent — never markdown/HTML — and
+  // it is rendered as plain text via textContent, never markdown/HTML, and
   // explicitly attributed to the agent rather than spoken in system voice.
   if (approval.reason) {
     const reasonLine = createElement("p", "persona-text-sm persona-mt-1 persona-text-persona-muted");