@runtypelabs/persona 3.34.1 → 3.36.0

package/src/client.ts

@@ -33,6 +33,7 @@ import {
   createXmlParser
 } from "./utils/formatting";
 import { SequenceReorderBuffer } from "./utils/sequence-buffer";
+import { VERSION } from "./version";
 // artifactsSidebarEnabled is used in ui.ts to gate the sidebar pane rendering;
 // artifact events are always processed here regardless of config.
 
@@ -180,7 +181,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;
 
@@ -188,6 +189,7 @@ export class AgentWidgetClient {
     this.apiUrl = config.apiUrl ?? DEFAULT_ENDPOINT;
     this.headers = {
       "Content-Type": "application/json",
+      "X-Persona-Version": VERSION,
       ...config.headers
     };
     this.debug = Boolean(config.debug);
@@ -206,8 +208,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 +217,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 +256,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,
@@ -355,6 +357,7 @@ export class AgentWidgetClient {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
+        'X-Persona-Version': VERSION,
       },
       body: JSON.stringify(requestBody),
     });
@@ -495,6 +498,7 @@ export class AgentWidgetClient {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
+        'X-Persona-Version': VERSION,
       },
       body: JSON.stringify(requestBody),
     });
@@ -682,6 +686,7 @@ export class AgentWidgetClient {
           method: 'POST',
           headers: {
             'Content-Type': 'application/json',
+            'X-Persona-Version': VERSION,
           },
           body: JSON.stringify(chatRequest),
           signal: controller.signal,
@@ -701,7 +706,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 +976,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 +1003,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 +1074,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 +1190,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 +1263,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 +1386,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 +1411,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 +1733,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 +1815,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 +1936,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 +2061,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 +2110,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 +2132,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 +2160,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 +2309,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 +2483,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 +2640,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 +2813,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 +2899,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 +2926,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 +3003,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");

package/src/components/artifact-pane.ts

@@ -36,7 +36,7 @@ export function createArtifactPane(
   config: AgentWidgetConfig,
   options: {
     onSelect: (id: string) => void;
-    /** User closed the pane (mobile drawer or split sidebar) — parent should persist “hidden until reopened”. */
+    /** User closed the pane (mobile drawer or split sidebar): parent should persist “hidden until reopened”. */
     onDismiss?: () => void;
   }
 ): ArtifactPaneApi {
@@ -203,7 +203,7 @@ export function createArtifactPane(
   });
 
   if (copyMenuChevronBtn && copyMenuItems?.length) {
-    // Resolve the portal target — widget root for CSS var inheritance, escaping overflow: hidden
+    // Resolve the portal target: widget root for CSS var inheritance, escaping overflow: hidden
     const resolvePortal = (): HTMLElement => shell.closest("[data-persona-root]") as HTMLElement ?? document.body;
 
     const initDropdown = () => {
@@ -414,7 +414,7 @@ export function createArtifactPane(
         backdrop.classList.add("persona-hidden");
         shell.classList.remove("persona-artifact-drawer-open");
       } else {
-        // isMobile && !(has && mobileOpen): e.g. dismissed drawer — keep closed chrome in sync
+        // isMobile && !(has && mobileOpen): e.g. dismissed drawer: keep closed chrome in sync
         backdrop.classList.add("persona-hidden");
         shell.classList.remove("persona-artifact-drawer-open");
       }

package/src/components/ask-user-question-bubble.test.ts

@@ -103,11 +103,11 @@ describe("ensureAskUserQuestionSheet", () => {
     expect(sheet).not.toBeNull();
     const pills = sheet!.querySelectorAll('[data-ask-user-action="pick"]');
     expect(pills.length).toBe(3);
-    // Default rows layout — label is in `.persona-ask-row-label`, alongside
+    // Default rows layout: label is in `.persona-ask-row-label`, alongside
     // a number-badge affordance. Read the dedicated label slot.
     const firstLabel = pills[0].querySelector(".persona-ask-row-label");
     expect(firstLabel?.textContent).toBe("Hobbyists");
-    // Free-text affordance present by default — rows mode embeds the input
+    // Free-text affordance present by default: rows mode embeds the input
     // inside the Other row via `focus-free-text` (digit shortcut + click chrome).
     const custom = sheet!.querySelector('[data-ask-user-action="focus-free-text"]');
     expect(custom).not.toBeNull();
@@ -144,7 +144,7 @@ describe("ensureAskUserQuestionSheet", () => {
     });
     ensureAskUserQuestionSheet(msg, {} as AgentWidgetConfig, overlay);
 
-    // Simulate more chunks arriving — options now parseable
+    // Simulate more chunks arriving: options now parseable
     msg.toolCall!.chunks = ['{"questions":[{"question":"X","options":[{"label":"A"},{"label":"B"}'];
     ensureAskUserQuestionSheet(msg, {} as AgentWidgetConfig, overlay);
 
@@ -155,7 +155,7 @@ describe("ensureAskUserQuestionSheet", () => {
     expect(pills[1].querySelector(".persona-ask-row-label")?.textContent).toBe("B");
   });
 
-  it("is idempotent — re-invoking does not duplicate sheets", () => {
+  it("is idempotent: re-invoking does not duplicate sheets", () => {
     const overlay = makeOverlay();
     ensureAskUserQuestionSheet(makeMessage(), {} as AgentWidgetConfig, overlay);
     ensureAskUserQuestionSheet(makeMessage(), {} as AgentWidgetConfig, overlay);
@@ -163,7 +163,7 @@ describe("ensureAskUserQuestionSheet", () => {
     expect(sheets.length).toBe(1);
   });
 
-  it("respects enabled: false — sheet is not mounted", () => {
+  it("respects enabled: false: sheet is not mounted", () => {
     const overlay = makeOverlay();
     ensureAskUserQuestionSheet(
       makeMessage(),
@@ -192,7 +192,7 @@ describe("ensureAskUserQuestionSheet", () => {
     expect(sheet.getAttribute("data-multi-select")).toBe("true");
   });
 
-  it("does not render a dismiss button — Skip in the nav row is the canonical escape", () => {
+  it("does not render a dismiss button: Skip in the nav row is the canonical escape", () => {
     const overlay = makeOverlay();
     ensureAskUserQuestionSheet(makeMessage(), {} as AgentWidgetConfig, overlay);
     const sheet = overlay.querySelector('[data-persona-ask-sheet-for="tool-1"]')!;
@@ -221,7 +221,7 @@ describe("removeAskUserQuestionSheet", () => {
     ensureAskUserQuestionSheet(makeMessage(), {} as AgentWidgetConfig, overlay);
     expect(overlay.querySelector('[data-persona-ask-sheet-for="tool-1"]')).not.toBeNull();
     removeAskUserQuestionSheet(overlay, "tool-1");
-    // The implementation defers removal with setTimeout — flush it.
+    // The implementation defers removal with setTimeout: flush it.
     await new Promise((resolve) => setTimeout(resolve, 250));
     expect(overlay.querySelector('[data-persona-ask-sheet-for="tool-1"]')).toBeNull();
   });
@@ -249,7 +249,7 @@ const makeGroupedMessage = (
 const sheetFor = (overlay: Element, toolCallId: string): HTMLElement =>
   overlay.querySelector<HTMLElement>(`[data-persona-ask-sheet-for="${toolCallId}"]`)!;
 
-describe("grouped questions — stepper UI", () => {
+describe("grouped questions: stepper UI", () => {
   it("renders 'Question 1 of N' chip and Back/Next nav row when N > 1", () => {
     const overlay = makeOverlay();
     const msg = makeGroupedMessage([
@@ -384,7 +384,7 @@ describe("grouped questions — stepper UI", () => {
     });
   });
 
-  it("hydrates from agentMetadata — restores index and prior answers on a fresh mount", () => {
+  it("hydrates from agentMetadata: restores index and prior answers on a fresh mount", () => {
     const overlay = makeOverlay();
     const msg = makeGroupedMessage(
       [
@@ -464,7 +464,7 @@ describe("rows layout (default)", () => {
     expect(firstRow.querySelector(".persona-ask-row-description")?.textContent).toBe(
       "Real Discord invite to link"
     );
-    // No title-attr fallback in rows layout — description is inline.
+    // No title-attr fallback in rows layout: description is inline.
     expect(firstRow.getAttribute("title")).toBeNull();
   });
 
@@ -507,11 +507,11 @@ describe("rows layout (default)", () => {
     expect(rows[0].querySelector(".persona-ask-row-badge")).toBeNull();
   });
 
-  it("embeds the free-text input INSIDE the Other row (rows mode) — no separate row, no Send button", () => {
+  it("embeds the free-text input INSIDE the Other row (rows mode): no separate row, no Send button", () => {
     const overlay = makeOverlay();
     ensureAskUserQuestionSheet(makeMessage(), {} as AgentWidgetConfig, overlay);
     const sheet = overlay.querySelector('[data-persona-ask-sheet-for="tool-1"]')!;
-    // No standalone free-text row in rows mode — input lives inside the Other row.
+    // No standalone free-text row in rows mode: input lives inside the Other row.
     expect(sheet.querySelector('[data-ask-free-text-row="true"]')).toBeNull();
     const otherRow = sheet.querySelector<HTMLElement>('[data-ask-other-row="true"]')!;
     expect(otherRow).not.toBeNull();
@@ -520,12 +520,12 @@ describe("rows layout (default)", () => {
     expect(otherRow.querySelector('[data-ask-user-action="submit-free-text"]')).toBeNull();
     // Other row carries the focus-free-text action (digit shortcut + click chrome).
     expect(otherRow.getAttribute("data-ask-user-action")).toBe("focus-free-text");
-    // Number badge for the Other row (N+1 — 3 real options + Other = 4).
+    // Number badge for the Other row (N+1: 3 real options + Other = 4).
     const badge = otherRow.querySelector<HTMLElement>(".persona-ask-row-badge");
     expect(badge?.textContent).toBe("4");
   });
 
-  it("respects layout: 'pills' opt-out — no row affordances, free-text starts hidden, Send button still rendered", () => {
+  it("respects layout: 'pills' opt-out: no row affordances, free-text starts hidden, Send button still rendered", () => {
     const overlay = makeOverlay();
     const config = {
       features: { askUserQuestion: { layout: "pills" } },

package/src/components/ask-user-question-bubble.ts

@@ -60,7 +60,7 @@ const resolveFeature = (config?: AgentWidgetConfig): AgentWidgetAskUserQuestionF
 
 /**
  * Parse an `ask_user_question` tool-variant message into a partial payload.
- * Safe to call mid-stream — will walk the tool call's `chunks` via
+ * Safe to call mid-stream: will walk the tool call's `chunks` via
  * `partial-json` and return `{ payload: null, complete: false }` when there
  * isn't enough data yet. `complete` flips to `true` once the tool call
  * reports status `"complete"`.
@@ -570,7 +570,7 @@ const syncNavState = (sheet: HTMLElement): void => {
   );
   if (next) next.disabled = !hasAnswer;
 
-  // Multi-select submit (1-question mode) — keep existing behavior.
+  // Multi-select submit (1-question mode): keep existing behavior.
   const multi = sheet.querySelector<HTMLButtonElement>('[data-ask-user-action="submit-multi"]');
   if (multi) {
     const labels = Array.from(
@@ -625,7 +625,7 @@ const renderCurrentPage = (
     pillList.replaceWith(fresh);
   }
 
-  // Free-text row — re-build to clear stale input value across pages.
+  // Free-text row: re-build to clear stale input value across pages.
   // Only present in pills (legacy) mode; in rows mode the input lives inside
   // the Other row of the pill list, which is rebuilt above.
   if (layout !== "rows") {
@@ -633,7 +633,7 @@ const renderCurrentPage = (
     if (oldFree) oldFree.replaceWith(buildFreeTextRow(feature, layout));
   }
 
-  // Multi-select action row — only relevant in 1-question mode.
+  // Multi-select action row: only relevant in 1-question mode.
   const oldMulti = sheet.querySelector<HTMLElement>('[data-ask-multi-actions="true"]');
   if (!grouped && multiSelect && !oldMulti) {
     sheet.appendChild(buildMultiSelectActions(feature));
@@ -698,7 +698,7 @@ const buildSheet = (
 
   // Header: question text (flex-1) + compact "N/M" stepper indicator on the
   // right (grouped only). Skip in the nav row is the canonical escape hatch
-  // — plugins that want a different escape model render their own UX.
+  //: plugins that want a different escape model render their own UX.
   const header = createElement(
     "div",
     "persona-ask-sheet-header persona-flex persona-items-center persona-gap-3"
@@ -721,7 +721,7 @@ const buildSheet = (
 
   sheet.appendChild(header);
 
-  // Skeleton placeholders — these get replaced wholesale by renderCurrentPage.
+  // Skeleton placeholders: these get replaced wholesale by renderCurrentPage.
   const skeletonClass =
     layout === "rows"
       ? "persona-ask-pills persona-ask-pills--rows persona-flex persona-flex-col persona-gap-2"
@@ -768,7 +768,7 @@ const syncSheetFromMessage = (
 
 /**
  * Create the small in-transcript stub for an `ask_user_question` tool call.
- * The stub is passive — the interactive sheet is mounted separately into
+ * The stub is passive: the interactive sheet is mounted separately into
  * the composer overlay via `ensureAskUserQuestionSheet`.
  */
 export const createAskUserQuestionBubble = (
@@ -796,7 +796,7 @@ export const createAskUserQuestionBubble = (
 
 /**
  * Mount or update the interactive answer-pill sheet for a given message.
- * Idempotent — if a sheet already exists for the tool-call id, it is hydrated
+ * Idempotent: if a sheet already exists for the tool-call id, it is hydrated
  * in-place instead of remounted, so streaming updates don't flicker.
  */
 export const ensureAskUserQuestionSheet = (
@@ -812,7 +812,7 @@ export const ensureAskUserQuestionSheet = (
 
   const toolCallId = message.toolCall!.id;
 
-  // Only keep the latest sheet in the overlay — clear any stale siblings.
+  // Only keep the latest sheet in the overlay: clear any stale siblings.
   const siblings = overlay.querySelectorAll<HTMLElement>(`[${SHEET_SENTINEL}]`);
   siblings.forEach((el) => {
     if (el.getAttribute(SHEET_SENTINEL) !== toolCallId) {
@@ -916,7 +916,7 @@ export const refreshNavState = (sheet: HTMLElement): void => {
 };
 
 /**
- * Test seam — reset the one-shot truncation warning so each test can assert
+ * Test seam: reset the one-shot truncation warning so each test can assert
  * the warn fires exactly once.
  */
 export const __resetTruncateWarn = (): void => {

package/src/components/composer-builder.ts

@@ -1,4 +1,4 @@
-import { createElement } from "../utils/dom";
+import { createElement, createNode } from "../utils/dom";
 import { AgentWidgetConfig, ContentPart } from "../types";
 import {
   createAttachmentControls,
@@ -57,20 +57,20 @@ export interface ComposerBuildContext {
 export const buildComposer = (context: ComposerBuildContext): ComposerElements => {
   const { config } = context;
 
-  const footer = createElement(
-    "div",
-    "persona-widget-footer persona-border-t-persona-divider persona-bg-persona-surface persona-px-6 persona-py-4"
-  );
-  footer.setAttribute("data-persona-theme-zone", "composer");
+  const footer = createNode("div", {
+    className:
+      "persona-widget-footer persona-border-t-persona-divider persona-bg-persona-surface persona-px-6 persona-py-4",
+    attrs: { "data-persona-theme-zone": "composer" },
+  });
 
   const suggestions = createSuggestionsRow();
 
-  const composerForm = createElement(
-    "form",
-    "persona-widget-composer persona-flex persona-flex-col persona-gap-2 persona-rounded-2xl persona-border persona-border-gray-200 persona-bg-persona-input-background persona-px-4 persona-py-3"
-  ) as HTMLFormElement;
-  composerForm.setAttribute("data-persona-composer-form", "");
-  composerForm.style.outline = "none";
+  const composerForm = createNode("form", {
+    className:
+      "persona-widget-composer persona-flex persona-flex-col persona-gap-2 persona-rounded-2xl persona-border persona-border-gray-200 persona-bg-persona-input-background persona-px-4 persona-py-3",
+    attrs: { "data-persona-composer-form": "" },
+    style: { outline: "none" },
+  });
 
   const { textarea, attachAutoResize } = createComposerTextarea(config);
   attachAutoResize();
@@ -93,10 +93,11 @@ export const buildComposer = (context: ComposerBuildContext): ComposerElements =
   // The bare class names (persona-widget-composer__actions / __left-actions /
   // __right-actions) are stable CSS hooks. The pill composer reuses
   // __left-actions / __right-actions as semantic markers in its grid.
-  const actionsRow = createElement(
-    "div",
-    "persona-widget-composer__actions persona-flex persona-items-center persona-justify-between persona-w-full"
-  );
+  const actionsRow = createNode("div", {
+    className:
+      "persona-widget-composer__actions persona-flex persona-items-center persona-justify-between persona-w-full",
+    attrs: { "data-persona-composer-actions": "" },
+  });
   const leftActions = createElement(
     "div",
     "persona-widget-composer__left-actions persona-flex persona-items-center persona-gap-2"