@runtypelabs/persona 3.34.1 → 3.35.0

package/src/utils/speech-text.test.ts

@@ -0,0 +1,122 @@
+import { describe, it, expect } from "vitest";
+import { stripMarkdownForSpeech, resolveSpeakableText, extractActionMessageText } from "./speech-text";
+
+describe("stripMarkdownForSpeech", () => {
+  it("returns empty string for empty/undefined input", () => {
+    expect(stripMarkdownForSpeech("")).toBe("");
+    // @ts-expect-error testing defensive undefined handling
+    expect(stripMarkdownForSpeech(undefined)).toBe("");
+  });
+
+  it("strips bold and italic markers but keeps the words", () => {
+    expect(stripMarkdownForSpeech("This is **bold** and *italic* text")).toBe(
+      "This is bold and italic text"
+    );
+    expect(stripMarkdownForSpeech("__strong__ and _em_")).toBe("strong and em");
+  });
+
+  it("keeps inline code text without backticks", () => {
+    expect(stripMarkdownForSpeech("Run `npm install` first")).toBe("Run npm install first");
+  });
+
+  it("drops fenced code blocks entirely", () => {
+    const md = "Here is code:\n```js\nconst x = 1;\n```\nDone.";
+    const out = stripMarkdownForSpeech(md);
+    expect(out).not.toContain("const x");
+    expect(out).toContain("Here is code:");
+    expect(out).toContain("Done.");
+  });
+
+  it("speaks link text, not the URL", () => {
+    expect(stripMarkdownForSpeech("See [the docs](https://example.com/x) now")).toBe(
+      "See the docs now"
+    );
+  });
+
+  it("speaks image alt text", () => {
+    expect(stripMarkdownForSpeech("![a red car](car.png)")).toBe("a red car");
+  });
+
+  it("strips heading, blockquote, and list markers", () => {
+    expect(stripMarkdownForSpeech("# Title")).toBe("Title");
+    expect(stripMarkdownForSpeech("> quoted")).toBe("quoted");
+    expect(stripMarkdownForSpeech("- item one\n- item two")).toBe("item one\nitem two");
+    expect(stripMarkdownForSpeech("1. first\n2. second")).toBe("first\nsecond");
+  });
+
+  it("strips raw HTML tags", () => {
+    expect(stripMarkdownForSpeech("Hello <strong>world</strong>!")).toBe("Hello world !");
+  });
+
+  it("decodes common HTML entities", () => {
+    expect(stripMarkdownForSpeech("Tom &amp; Jerry &lt;3")).toBe("Tom & Jerry <3");
+  });
+
+  it("collapses excess whitespace and trims", () => {
+    expect(stripMarkdownForSpeech("  lots   of\n\n\nspace  ")).toBe("lots of\nspace");
+  });
+
+  it("handles a realistic mixed message", () => {
+    const md = [
+      "## Summary",
+      "",
+      "I'd **ship** `approval.choices.alwaysAllow` and [this one](https://x.y).",
+      "",
+      "```ts",
+      "const skip = true;",
+      "```",
+      "",
+      "- point A",
+      "- point B",
+    ].join("\n");
+    const out = stripMarkdownForSpeech(md);
+    expect(out).toContain("Summary");
+    expect(out).toContain("I'd ship approval.choices.alwaysAllow and this one.");
+    expect(out).toContain("point A");
+    expect(out).not.toContain("```");
+    expect(out).not.toContain("const skip");
+    expect(out).not.toContain("https://x.y");
+  });
+});
+
+describe("extractActionMessageText", () => {
+  it("extracts text from a bare action envelope", () => {
+    expect(extractActionMessageText('{"action":"message","text":"Hello there"}')).toBe("Hello there");
+  });
+
+  it("extracts text from a fenced ```json envelope", () => {
+    const raw = '```json\n{\n  "action": "message",\n  "text": "Why don\'t scientists trust atoms?"\n}\n```';
+    expect(extractActionMessageText(raw)).toBe("Why don't scientists trust atoms?");
+  });
+
+  it("returns null for plain prose", () => {
+    expect(extractActionMessageText("Just a normal reply")).toBeNull();
+  });
+
+  it("returns null for JSON without a string text field", () => {
+    expect(extractActionMessageText('{"action":"navigate","url":"/x"}')).toBeNull();
+  });
+
+  it("returns null for malformed JSON", () => {
+    expect(extractActionMessageText('{"action":"message", "text":')).toBeNull();
+  });
+});
+
+describe("resolveSpeakableText", () => {
+  it("speaks the action text, not the JSON envelope", () => {
+    const raw = '```json\n{"action":"message","text":"Why don\'t scientists trust atoms?"}\n```';
+    expect(resolveSpeakableText(raw)).toBe("Why don't scientists trust atoms?");
+  });
+
+  it("strips markdown from action text", () => {
+    expect(resolveSpeakableText('{"action":"message","text":"Ship **it** now"}')).toBe("Ship it now");
+  });
+
+  it("falls back to markdown stripping for plain prose", () => {
+    expect(resolveSpeakableText("This is **bold**")).toBe("This is bold");
+  });
+
+  it("returns empty string for empty input", () => {
+    expect(resolveSpeakableText("")).toBe("");
+  });
+});

package/src/utils/speech-text.ts

@@ -0,0 +1,101 @@
+/**
+ * Resolve the text that should be spoken for an assistant message.
+ *
+ * Some flows return an action-format envelope as the message body — e.g.
+ * `{"action":"message","text":"Hello"}`, often inside a ```json fence — rather
+ * than plain prose. Speaking the raw JSON (or, after fenced-code stripping,
+ * nothing at all) is useless, so we first try to extract the human `text` field
+ * (mirroring the widget's `defaultJsonActionParser`, which also keys on
+ * `.text`), and otherwise fall back to stripping Markdown from the raw content.
+ */
+export function resolveSpeakableText(raw: string): string {
+  if (!raw) return "";
+  const actionText = extractActionMessageText(raw);
+  if (actionText !== null) return stripMarkdownForSpeech(actionText);
+  return stripMarkdownForSpeech(raw);
+}
+
+/**
+ * If `raw` is (or wraps, in a ```json fence) a JSON object with a string `text`
+ * property, return that text; otherwise return `null`. Matches the action
+ * envelope shape `{ action, text, ... }` used by the widget's action system.
+ */
+export function extractActionMessageText(raw: string): string | null {
+  let body = raw.trim();
+  const fence = body.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+  if (fence) body = fence[1].trim();
+  if (!body.startsWith("{")) return null;
+  try {
+    const parsed = JSON.parse(body);
+    if (parsed && typeof parsed === "object" && typeof (parsed as { text?: unknown }).text === "string") {
+      return (parsed as { text: string }).text;
+    }
+  } catch {
+    // Not valid JSON — fall through to the Markdown path.
+  }
+  return null;
+}
+
+/**
+ * Convert Markdown to plain text suitable for text-to-speech.
+ *
+ * Read-aloud should speak the prose a user sees, not the markup: code fences,
+ * backticks, emphasis markers, link/image syntax and raw HTML are all noise
+ * when spoken. This is intentionally lightweight (regex-based, no full Markdown
+ * parser) — it favours predictable, dependency-free output over perfect
+ * fidelity. Speech engines receive the result of this function, never raw
+ * Markdown.
+ */
+export function stripMarkdownForSpeech(markdown: string): string {
+  if (!markdown) return "";
+  let text = markdown;
+
+  // Fenced code blocks: drop entirely (reading source aloud is noise).
+  text = text.replace(/```[\s\S]*?```/g, " ");
+  text = text.replace(/~~~[\s\S]*?~~~/g, " ");
+
+  // Inline code: keep the inner text, drop the backticks.
+  text = text.replace(/`([^`]+)`/g, "$1");
+
+  // Images: speak the alt text only.
+  text = text.replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1");
+
+  // Inline links: speak the link text, drop the URL.
+  text = text.replace(/\[([^\]]+)\]\([^)]*\)/g, "$1");
+
+  // Reference-style links/images: [text][ref] -> text.
+  text = text.replace(/\[([^\]]+)\]\[[^\]]*\]/g, "$1");
+
+  // Raw HTML tags.
+  text = text.replace(/<\/?[a-zA-Z][^>]*>/g, " ");
+
+  // Line-leading markers: headings, blockquotes, list bullets, ordered items.
+  text = text.replace(/^[ \t]*#{1,6}[ \t]+/gm, "");
+  text = text.replace(/^[ \t]*>[ \t]?/gm, "");
+  text = text.replace(/^[ \t]*[-*+][ \t]+/gm, "");
+  text = text.replace(/^[ \t]*\d+\.[ \t]+/gm, "");
+
+  // Horizontal rules.
+  text = text.replace(/^[ \t]*([-*_])([ \t]*\1){2,}[ \t]*$/gm, " ");
+
+  // Emphasis / strikethrough markers (bold before italic so ** is consumed).
+  text = text.replace(/(\*\*|__)(.*?)\1/g, "$2");
+  text = text.replace(/(\*|_)(.*?)\1/g, "$2");
+  text = text.replace(/~~(.*?)~~/g, "$1");
+
+  // Decode a few common HTML entities so they aren't spoken literally.
+  text = text
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&nbsp;/g, " ");
+
+  // Collapse whitespace.
+  text = text.replace(/[ \t]+/g, " ");
+  text = text.replace(/[ \t]*\n[ \t]*/g, "\n");
+  text = text.replace(/\n{2,}/g, "\n");
+
+  return text.trim();
+}

package/src/utils/stream-animation.test.ts

@@ -22,7 +22,7 @@ import type { AgentWidgetMessage, StreamAnimationPlugin } from "../types";
 import "../animations/wipe";
 import "../animations/glyph-cycle";
 
-describe("wrapStreamAnimation — char mode", () => {
+describe("wrapStreamAnimation: char mode", () => {
   it("wraps every character in a plain paragraph into a stream-char span", () => {
     const out = wrapStreamAnimation("<p>Hi!</p>", "char", "m1");
     const parser = document.createElement("div");
@@ -145,7 +145,7 @@ describe("wrapStreamAnimation — char mode", () => {
     };
     const firstSpans = parse(first);
     const secondSpans = parse(second);
-    // First two ids are stable — idiomorph match contract. The space between
+    // First two ids are stable: idiomorph match contract. The space between
     // "Hi" and "there" is a plain text node, not a span, so the next wrapped
     // char after "Hi" jumps to index 2 for "t" in "there".
     expect(firstSpans[0].id).toBe(secondSpans[0].id);
@@ -161,7 +161,7 @@ describe("wrapStreamAnimation — char mode", () => {
   });
 });
 
-describe("wrapStreamAnimation — word mode", () => {
+describe("wrapStreamAnimation: word mode", () => {
   it("splits on whitespace and wraps each non-whitespace token", () => {
     const out = wrapStreamAnimation("<p>Hello brave world</p>", "word", "m1");
     const parser = document.createElement("div");

package/src/utils/stream-animation.ts

@@ -42,11 +42,11 @@ export const resolveStreamAnimation = (
    ============================================================ */
 
 /**
- * Built-in animations ship with the core widget — CSS lives in widget.css
+ * Built-in animations ship with the core widget: CSS lives in widget.css
  * and no subpath import is required. They register automatically.
  *
  * Other animations (`letter-rise`, `word-fade`, `wipe`, `glyph-cycle`) are
- * tree-shakeable subpath plugins — consumers import them from
+ * tree-shakeable subpath plugins: consumers import them from
  * `@runtypelabs/persona/animations/<name>` and they auto-register on load.
  */
 const BUILTIN_PLUGINS: StreamAnimationPlugin[] = [
@@ -268,7 +268,7 @@ const wrapTextNodeWords = (
  *
  * Each wrapped span carries a stable `id` (`stream-c-{messageId}-{N}` or
  * `stream-w-{messageId}-{N}`) so idiomorph preserves existing spans across
- * token-by-token re-renders — animations on already-streamed characters never
+ * token-by-token re-renders: animations on already-streamed characters never
  * restart.
  */
 export const wrapStreamAnimation = (
@@ -297,7 +297,7 @@ export const wrapStreamAnimation = (
   // `startIndex` lets callers number spans by their absolute position in a
   // larger string, even when only a slice is being wrapped. The peek banner
   // uses this so per-char span IDs stay stable as the trailing-100-char
-  // window shifts each chunk — idiomorph then preserves animations on
+  // window shifts each chunk: idiomorph then preserves animations on
   // already-revealed chars instead of restarting them.
   const counterRef = { value: options?.startIndex ?? 0 };
   const wrap = mode === "char" ? wrapTextNodeChars : wrapTextNodeWords;
@@ -326,7 +326,7 @@ export const createStreamCaret = (doc: Document = document): HTMLElement => {
 };
 
 /**
- * Shimmer placeholder shown before the first token arrives — and, when the
+ * Shimmer placeholder shown before the first token arrives, and, when the
  * `"line"` buffer strategy is active, reshown between lines. A single
  * full-width bar; we don't know ahead of time how wide the next line will be,
  * so committing to one width avoids implying structure the stream won't match.
@@ -415,7 +415,7 @@ export const detachAllPlugins = (root: HTMLElement | ShadowRoot): void => {
 
 /**
  * Ensure the plugin's one-time side effects (style injection, onAttach) have
- * run for this widget root. Idempotent — safe to call on every render.
+ * run for this widget root. Idempotent: safe to call on every render.
  */
 export const ensurePluginActive = (
   plugin: StreamAnimationPlugin,

package/src/utils/theme.test.ts

@@ -297,7 +297,7 @@ describe('theme utils', () => {
           toolBubble: { shadow: '0 1px 2px rgba(255,0,0,0.5)' },
         },
       },
-      // config.toolCall.shadow no longer rewrites the root variable — the
+      // config.toolCall.shadow no longer rewrites the root variable: the
       // override is applied inline by createToolBubble (see tool-bubble tests).
       toolCall: { shadow: 'none' },
     });

package/src/utils/throughput-tracker.test.ts

@@ -35,7 +35,7 @@ describe("estimateOutputTokens", () => {
   });
 });
 
-describe("ThroughputTracker — live estimate", () => {
+describe("ThroughputTracker: live estimate", () => {
   it("estimates output tokens live from visible text deltas", () => {
     const h = makeTracker();
 
@@ -97,7 +97,7 @@ describe("ThroughputTracker — live estimate", () => {
   });
 });
 
-describe("ThroughputTracker — exact usage finalization", () => {
+describe("ThroughputTracker: exact usage finalization", () => {
   it("prefers exact output tokens from the terminal event over the estimate", () => {
     const h = makeTracker();
     h.at(1000).processEvent("step_delta", { type: "step_delta", text: text(40) });
@@ -160,7 +160,7 @@ describe("ThroughputTracker — exact usage finalization", () => {
   });
 });
 
-describe("ThroughputTracker — non-visible deltas ignored", () => {
+describe("ThroughputTracker: non-visible deltas ignored", () => {
   it("ignores agent thinking and tool_input deltas", () => {
     const h = makeTracker();
 
@@ -223,7 +223,7 @@ describe("ThroughputTracker — non-visible deltas ignored", () => {
   });
 });
 
-describe("ThroughputTracker — intermediate completes do not finalize", () => {
+describe("ThroughputTracker: intermediate completes do not finalize", () => {
   it("keeps the run running across step_complete / agent_turn_complete", () => {
     const h = makeTracker();
     h.at(1000).processEvent("step_delta", { type: "step_delta", text: text(40) });
@@ -245,7 +245,7 @@ describe("ThroughputTracker — intermediate completes do not finalize", () => {
   });
 });
 
-describe("ThroughputTracker — error handling", () => {
+describe("ThroughputTracker: error handling", () => {
   it.each(["step_error", "flow_error", "agent_error", "error"])(
     "marks the metric unavailable on %s",
     (errorType: string) => {
@@ -278,7 +278,7 @@ describe("ThroughputTracker — error handling", () => {
   });
 });
 
-describe("ThroughputTracker — reset & re-run", () => {
+describe("ThroughputTracker: reset & re-run", () => {
   it("reset() returns to idle", () => {
     const h = makeTracker();
     h.at(1000).processEvent("step_delta", { type: "step_delta", text: text(40) });
@@ -302,7 +302,7 @@ describe("ThroughputTracker — reset & re-run", () => {
   it("resets a stale run on the next request's start event (no bleed)", () => {
     const h = makeTracker();
     // First request streams visible output but never terminates (e.g. the
-    // user cancels mid-stream — no flow_complete / error frame is emitted).
+    // user cancels mid-stream: no flow_complete / error frame is emitted).
     h.at(1000).processEvent("step_delta", { type: "step_delta", text: text(120) });
     expect(h.metric().outputTokens).toBe(30);
     expect(h.metric().status).toBe("running");
@@ -328,7 +328,7 @@ describe("ThroughputTracker — reset & re-run", () => {
   });
 });
 
-describe("ThroughputTracker — exact usage never drops mid-run", () => {
+describe("ThroughputTracker: exact usage never drops mid-run", () => {
   it("keeps exact tokens as a floor when later steps stream more text", () => {
     const h = makeTracker();
     h.at(1000).processEvent("step_delta", { type: "step_delta", text: text(40) });
@@ -342,7 +342,7 @@ describe("ThroughputTracker — exact usage never drops mid-run", () => {
     expect(m.outputTokens).toBe(50);
     expect(m.source).toBe("usage");
 
-    // Step 2 streams more visible text — the total must grow from 50, not
+    // Step 2 streams more visible text: the total must grow from 50, not
     // collapse back to a bare 10-token estimate of the new text.
     h.at(2000).processEvent("step_delta", { type: "step_delta", text: text(40) });
     m = h.metric();
@@ -351,14 +351,14 @@ describe("ThroughputTracker — exact usage never drops mid-run", () => {
   });
 });
 
-describe("ThroughputTracker — live rate decays while paused", () => {
+describe("ThroughputTracker: live rate decays while paused", () => {
   it("recomputes duration/tok-s from the clock between events", () => {
     const h = makeTracker();
     h.at(1000).processEvent("step_delta", { type: "step_delta", text: text(400) });
     // 100 tokens over a 1s window read at t=2000 → ~100 tok/s.
     h.at(2000);
     expect(h.metric().tokensPerSecond).toBeCloseTo(100);
-    // Same tokens, but the model has paused — reading at t=5000 (4s window)
+    // Same tokens, but the model has paused: reading at t=5000 (4s window)
     // must decay the displayed rate even though no new event arrived.
     h.at(5000);
     expect(h.metric().tokensPerSecond).toBeCloseTo(25);

package/src/utils/throughput-tracker.ts

@@ -5,7 +5,7 @@
 // Derives an output tokens-per-second metric from the widget's existing SSE
 // event stream, for display in the Events diagnostics screen. This is a passive
 // consumer: it never mutates dispatch payloads, never forces debug mode, and
-// never changes the wire contract — it only inspects the `(type, payload)`
+// never changes the wire contract: it only inspects the `(type, payload)`
 // events that already flow through the SSE tap.
 //
 // Throughput is estimated live from visible text deltas while a run streams,
@@ -62,7 +62,7 @@ const REQUEST_START_EVENTS = new Set([
 ]);
 
 // Per-step markers that fire repeatedly WITHIN a single request (a flow emits
-// one per step). These only lazily begin a run — they must never reset, or a
+// one per step). These only lazily begin a run: they must never reset, or a
 // multi-step response would restart the metric between steps. If no request- or
 // step-start event is emitted, the first visible delta lazily starts the run.
 const STEP_START_EVENTS = new Set(["step_start", "execution_start"]);
@@ -151,8 +151,8 @@ function getTextDelta(payload: Record<string, unknown>): string {
  * other value, and a missing contentType are ignored so throughput never
  * includes deltas the chat UI doesn't render.
  *
- * For `step_delta` / `step_chunk`, skip tool and context steps — those carry
- * tool I/O, not model-visible text — mirroring the widget's own renderer.
+ * For `step_delta` / `step_chunk`, skip tool and context steps: those carry
+ * tool I/O, not model-visible text: mirroring the widget's own renderer.
  */
 function isVisibleTextDelta(
   type: string,
@@ -298,13 +298,13 @@ export class ThroughputTracker {
     const now = this.now();
 
     if (REQUEST_START_EVENTS.has(type)) {
-      // New request — start fresh, discarding any incomplete prior run.
+      // New request: start fresh, discarding any incomplete prior run.
       this.startRun(now);
       return;
     }
 
     if (STEP_START_EVENTS.has(type)) {
-      // Mid-request step marker — only begin a run if none is active.
+      // Mid-request step marker: only begin a run if none is active.
       if (!this.run) this.startRun(now);
       return;
     }
@@ -323,7 +323,7 @@ export class ThroughputTracker {
 
       // Add the live char estimate of the CURRENT (not-yet-completed) step on
       // top of any exact usage already booked from completed steps, so the
-      // count only grows — it never drops back to a bare estimate mid-run.
+      // count only grows: it never drops back to a bare estimate mid-run.
       const outputTokens =
         stats.exactOutputTokens +
         estimateTokensFromCharCount(stats.visibleCharCount);
@@ -339,7 +339,7 @@ export class ThroughputTracker {
     }
 
     if (INTERMEDIATE_COMPLETE_EVENTS.has(type)) {
-      // Accumulate exact usage but keep the run going — these fire per
+      // Accumulate exact usage but keep the run going: these fire per
       // step/turn, not at the end of the whole run.
       if (!this.run) return;
       const stats = this.run;
@@ -347,7 +347,7 @@ export class ThroughputTracker {
       if (exact !== undefined) {
         stats.exactOutputTokens += exact;
         // This step's visible text is now represented exactly by provider
-        // usage — drop it from the running char estimate so the two don't
+        // usage: drop it from the running char estimate so the two don't
         // double-count once the next step starts streaming.
         stats.visibleCharCount = 0;
       }

package/src/utils/tokens.ts

@@ -194,23 +194,23 @@ export const DEFAULT_SEMANTIC: SemanticTokens = {
   colors: {
     primary: 'palette.colors.primary.500',
     secondary: 'palette.colors.secondary.500',
-    // Links/Focus role — solid primary
+    // Links/Focus role: solid primary
     accent: 'palette.colors.primary.600',
-    // Surfaces role — soft gray
+    // Surfaces role: soft gray
     surface: 'palette.colors.gray.50',
     background: 'palette.colors.gray.50',
     container: 'palette.colors.gray.50',
     text: 'palette.colors.gray.900',
     textMuted: 'palette.colors.gray.500',
     textInverse: 'palette.colors.gray.50',
-    // Borders role — soft gray
+    // Borders role: soft gray
     border: 'palette.colors.gray.200',
     divider: 'palette.colors.gray.200',
     interactive: {
-      // Primary Actions role — solid primary
+      // Primary Actions role: solid primary
       default: 'palette.colors.primary.600',
       hover: 'palette.colors.primary.700',
-      // Links/Focus role — solid primary
+      // Links/Focus role: solid primary
       focus: 'palette.colors.primary.600',
       active: 'palette.colors.primary.600',
       disabled: 'palette.colors.gray.300',
@@ -241,7 +241,7 @@ export const DEFAULT_SEMANTIC: SemanticTokens = {
 export const DEFAULT_COMPONENTS: ComponentTokens = {
   button: {
     primary: {
-      // Primary Actions role — solid primary
+      // Primary Actions role: solid primary
       background: 'palette.colors.primary.500',
       foreground: 'palette.colors.primary.50',
       borderRadius: 'palette.radius.lg',
@@ -261,7 +261,7 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
     },
   },
   input: {
-    // Input role — soft gray
+    // Input role: soft gray
     background: 'palette.colors.gray.50',
     placeholder: 'palette.colors.gray.400',
     borderRadius: 'palette.radius.lg',
@@ -289,7 +289,7 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
     shadow: 'palette.shadows.xl',
   },
   header: {
-    // Header role — solid primary
+    // Header role: solid primary
     background: 'palette.colors.primary.500',
     border: 'palette.colors.primary.600',
     borderRadius: 'palette.radius.xl palette.radius.xl 0 0',
@@ -302,14 +302,14 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
   },
   message: {
     user: {
-      // User Messages role — solid primary
+      // User Messages role: solid primary
       background: 'palette.colors.primary.500',
       text: 'palette.colors.primary.50',
       borderRadius: 'palette.radius.lg',
       shadow: 'palette.shadows.sm',
     },
     assistant: {
-      // Assistant Messages role — soft gray
+      // Assistant Messages role: soft gray
       background: 'palette.colors.gray.50',
       text: 'palette.colors.gray.900',
       borderRadius: 'palette.radius.lg',
@@ -341,7 +341,7 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
       foreground: 'palette.colors.gray.900',
     },
     link: {
-      // Links/Focus role — solid primary
+      // Links/Focus role: solid primary
       foreground: 'palette.colors.primary.600',
     },
     prose: {
@@ -755,7 +755,7 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
     cssVars['--persona-radius-lg'] ??
     '0.5rem';
 
-  // Component-level color overrides — these map component tokens to
+  // Component-level color overrides: these map component tokens to
   // dedicated CSS variables that the widget CSS reads for individual elements.
   cssVars['--persona-header-bg'] =
     cssVars['--persona-components-header-background'] ?? cssVars['--persona-surface'];
@@ -776,7 +776,7 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
   if (headerTokens?.shadow) cssVars['--persona-header-shadow'] = headerTokens.shadow;
   if (headerTokens?.borderBottom) cssVars['--persona-header-border-bottom'] = headerTokens.borderBottom;
 
-  // Intro card aliases — short names the panel inline-styles read directly.
+  // Intro card aliases: short names the panel inline-styles read directly.
   // The full-path `--persona-components-introCard-*` variables auto-emit above;
   // these mirror them with sensible fallbacks so existing pages keep their look.
   const introCardTokens = theme.components?.introCard;

package/src/utils/virtual-scroller.ts

@@ -55,7 +55,7 @@ export class VirtualScroller {
   setTotalCount(count: number): void {
     this.totalCount = count;
     this.spacer.style.height = `${count * this.rowHeight}px`;
-    // Always invalidate cached rows — data may have changed even at the same count
+    // Always invalidate cached rows: data may have changed even at the same count
     for (const [, el] of this.visibleRows) {
       el.remove();
     }

package/src/vendor/smart-dom-reader/README.md

@@ -34,15 +34,15 @@ and never touches a package resolver. Consumers who never import the
 
 ## Files
 
-- `index.js` — upstream `dist/index.mjs`, with two local edits (see header comment).
-- `index.d.ts` — upstream `dist/index.d.mts` verbatim (sourceMappingURL stripped).
-- `LICENSE` — upstream MIT license.
+- `index.js`: upstream `dist/index.mjs`, with two local edits (see header comment).
+- `index.d.ts`: upstream `dist/index.d.mts` verbatim (sourceMappingURL stripped).
+- `LICENSE`: upstream MIT license.
 
 ## Local modifications to `index.js`
 
 The **only** changes from upstream `dist/index.mjs` are:
 
-1. Removed the top-level `import { createRequire } from "node:module";` — a
+1. Removed the top-level `import { createRequire } from "node:module";`: a
    Node-only builtin that breaks browser bundling.
 2. Replaced `var __require = createRequire(import.meta.url);` with
    `var __require = void 0;`. `__require` is referenced only inside a guarded

package/src/vendor/smart-dom-reader/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * VENDORED type declarations — @mcp-b/smart-dom-reader v2.3.1 (MIT).
+ * VENDORED type declarations: @mcp-b/smart-dom-reader v2.3.1 (MIT).
  * Copied verbatim from upstream dist/index.d.mts (only the trailing sourceMappingURL
  * comment removed). See ./index.js and ./README.md for why this is vendored.
  */

package/src/vendor/smart-dom-reader/index.js

@@ -1,5 +1,5 @@
 /**
- * VENDORED — @mcp-b/smart-dom-reader v2.3.1 (MIT, (c) 2025 mcp-b contributors).
+ * VENDORED: @mcp-b/smart-dom-reader v2.3.1 (MIT, (c) 2025 mcp-b contributors).
  * Source: https://github.com/WebMCP-org/npm-packages/tree/main/packages/smart-dom-reader
  *
  * Vendored rather than installed as a dependency because every published version
@@ -864,7 +864,7 @@ function renderRegionInfo(region) {
 	if (region.linkCount) stats.push(`${region.linkCount} links`);
 	if (region.inputCount) stats.push(`${region.inputCount} inputs`);
 	if (region.textPreview) stats.push(`“${truncate(region.textPreview, 80)}”`);
-	const statsLine = stats.length ? ` — ${stats.join(", ")}` : "";
+	const statsLine = stats.length ? `: ${stats.join(", ")}` : "";
 	return `${icon} ${label} → \`${region.selector}\` [${id}]${statsLine}`;
 }
 function wrapXml(body, meta, type = "section") {

package/src/version.ts

@@ -1,5 +1,5 @@
 // Named import (not default) so esbuild tree-shakes the JSON module down to
-// the one field we read — a default import inlines the entire package.json
+// the one field we read: a default import inlines the entire package.json
 // (~4.8 kB minified) into every bundle.
 import { version } from "../package.json";