@runtypelabs/persona 3.34.1 → 3.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "3.34.1",
+  "version": "3.36.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

@@ -2,6 +2,7 @@ import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { AgentWidgetClient, preferFinalStructuredContent } from './client';
 import { AgentWidgetEvent, AgentWidgetMessage } from './types';
 import { createJsonStreamParser } from './utils/formatting';
+import { VERSION } from './version';
 
 describe('AgentWidgetClient - Empty Message Filtering', () => {
   let client: AgentWidgetClient;
@@ -2348,7 +2349,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 +2387,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 +2426,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 +2519,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 +2608,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 +2768,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 +3005,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 +3197,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 +3240,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 +3648,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 +3756,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 +4005,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';
@@ -4176,3 +4177,46 @@ describe('AgentWidgetClient - Feedback request builder', () => {
     expect(feedbackBodies[0].rating).toBe(5);
   });
 });
+
+describe('AgentWidgetClient - version header', () => {
+  function captureHeaders() {
+    const headers: Array<Record<string, string>> = [];
+    global.fetch = vi.fn().mockImplementation(async (_url: string, options: { headers: Record<string, string> }) => {
+      headers.push(options.headers);
+      const encoder = new TextEncoder();
+      const stream = new ReadableStream({
+        start(c) {
+          c.enqueue(encoder.encode('data: {"type":"flow_complete","success":true}\n\n'));
+          c.close();
+        },
+      });
+      return { ok: true, body: stream };
+    });
+    return headers;
+  }
+
+  const msg = () => ({
+    messages: [{ id: 'u1', role: 'user' as const, content: 'hi', createdAt: '2025-01-01T00:00:00.000Z' }],
+  });
+
+  it('broadcasts X-Persona-Version on the dispatch request', async () => {
+    const headers = captureHeaders();
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:8000' });
+
+    await client.dispatch(msg(), () => undefined);
+
+    expect(headers[0]['X-Persona-Version']).toBe(VERSION);
+  });
+
+  it('lets an explicit config header override the version', async () => {
+    const headers = captureHeaders();
+    const client = new AgentWidgetClient({
+      apiUrl: 'http://localhost:8000',
+      headers: { 'X-Persona-Version': 'override' },
+    });
+
+    await client.dispatch(msg(), () => undefined);
+
+    expect(headers[0]['X-Persona-Version']).toBe('override');
+  });
+});