@runtypelabs/persona 3.34.1 → 3.35.0

package/src/components/message-bubble.ts

@@ -28,7 +28,7 @@ import {
  * Default copy for the inline notice rendered when a turn ends with a
  * non-natural stop reason. Deployers override per-reason via
  * `config.copy.stopReasonNotice`. Returns `null` for natural completions
- * (`end_turn`) and uninformative reasons (`unknown`) — those never render
+ * (`end_turn`) and uninformative reasons (`unknown`): those never render
  * an affordance.
  */
 export const getDefaultStopReasonNoticeCopy = (
@@ -62,7 +62,7 @@ export const resolveStopReasonNoticeText = (
 ): string | null => {
   if (!stopReason) return null;
   const fallback = getDefaultStopReasonNoticeCopy(stopReason);
-  // Reasons without a default (end_turn, unknown) never render — overrides
+  // Reasons without a default (end_turn, unknown) never render: overrides
   // for those keys are intentionally ignored.
   if (fallback === null) return null;
   const override = overrides?.[stopReason];
@@ -498,10 +498,11 @@ const createAvatar = (
  */
 const createTimestamp = (
   message: AgentWidgetMessage,
-  timestampConfig: AgentWidgetTimestampConfig
+  timestampConfig: AgentWidgetTimestampConfig,
+  tagName: "div" | "span" = "div"
 ): HTMLElement => {
   const timestamp = createElement(
-    "div",
+    tagName,
     "persona-text-xs persona-text-persona-muted"
   );
 
@@ -629,9 +630,10 @@ export const createMessageActions = (
   const showCopy = actionsConfig.showCopy ?? true;
   const showUpvote = actionsConfig.showUpvote ?? true;
   const showDownvote = actionsConfig.showDownvote ?? true;
+  const showReadAloud = actionsConfig.showReadAloud ?? false;
 
   // Don't render the container at all when no actions are visible
-  if (!showCopy && !showUpvote && !showDownvote) {
+  if (!showCopy && !showUpvote && !showDownvote && !showReadAloud) {
     const empty = createElement("div");
     empty.style.display = "none";
     empty.id = `actions-${message.id}`;
@@ -686,6 +688,12 @@ export const createMessageActions = (
     container.appendChild(createActionButton("copy", "Copy message", "copy"));
   }
 
+  // Read-aloud button. Click handling and play/pause/resume state are managed
+  // in ui.ts (event delegation + ReadAloudController) so they survive morphs.
+  if (showReadAloud) {
+    container.appendChild(createActionButton("volume-2", "Read aloud", "read-aloud"));
+  }
+
   // Upvote button
   if (showUpvote) {
     container.appendChild(createActionButton("thumbs-up", "Upvote", "upvote"));
@@ -768,7 +776,7 @@ export const createStandardBubble = (
       ? resolveStreamAnimationPlugin(streamAnimation.type, streamPluginOverrides)
       : null;
   // Stay in "streaming-animated" mode while the plugin reports in-flight
-  // work for this message — e.g. glyph-cycle's tick loops still walking
+  // work for this message: e.g. glyph-cycle's tick loops still walking
   // through the tail after the last token arrived. Without this, the final
   // non-animated render rips out the cycling spans mid-animation.
   const pluginStillAnimating =
@@ -861,11 +869,17 @@ export const createStandardBubble = (
     }
   }
 
-  // Add inline timestamp if configured
+  // Usung <span>, not <div> for timestamp 
+  // because a block child of a <p> gets re-parented outside of it on re-render (idiomorph).
   if (showTimestamp && timestampPosition === "inline" && message.createdAt) {
-    const timestamp = createTimestamp(message, timestampConfig!);
-    timestamp.classList.add("persona-ml-2", "persona-inline");
-    contentDiv.appendChild(timestamp);
+    const timestamp = createTimestamp(message, timestampConfig!, "span");
+    timestamp.classList.add("persona-timestamp-inline");
+    const lastBlock = contentDiv.lastElementChild;
+    if (lastBlock) {
+      lastBlock.appendChild(timestamp);
+    } else {
+      contentDiv.appendChild(timestamp);
+    }
   }
 
   if (imageParts.length > 0) {
@@ -930,7 +944,7 @@ export const createStandardBubble = (
       : null;
 
   // Add typing indicator (or skeleton placeholder) for streaming assistant
-  // messages. Check the buffered content — a plugin's `bufferContent` may
+  // messages. Check the buffered content: a plugin's `bufferContent` may
   // hold back the first N chars (e.g. glyph-cycle waits for 50 chars), during
   // which the bubble would otherwise appear empty.
   //

package/src/components/messages.ts

@@ -34,7 +34,7 @@ export const renderMessages = (
       if (!showReasoning) return;
       bubble = createReasoningBubble(message, config);
     } else if (isAskUserQuestionMessage(message)) {
-      // No transcript bubble — the overlay sheet is the only question UI.
+      // No transcript bubble: the overlay sheet is the only question UI.
       if (config?.features?.askUserQuestion?.enabled === false) return;
       if (!message.agentMetadata?.askUserQuestionAnswered) {
         if (message.toolCall?.id) liveAskToolIds.add(message.toolCall.id);
@@ -45,7 +45,7 @@ export const renderMessages = (
       isSuggestRepliesMessage(message) &&
       config?.features?.suggestReplies?.enabled !== false
     ) {
-      // No transcript bubble — the chips above the composer are the only UI.
+      // No transcript bubble: the chips above the composer are the only UI.
       // When the feature is disabled the message falls through to the generic
       // tool bubble below (and is never auto-resumed), making the parked
       // execution visible instead of silently swallowed.

package/src/components/panel.test.ts

@@ -4,7 +4,7 @@ import { describe, expect, it } from "vitest";
 import { createWrapper } from "./panel";
 import type { AgentWidgetConfig } from "../types";
 
-describe("createWrapper — composer-bar mode", () => {
+describe("createWrapper: composer-bar mode", () => {
   it("marks the wrapper with composer-bar data-attrs and leaves geometry to updateOpenState", () => {
     const config: AgentWidgetConfig = {
       apiUrl: "/api",

package/src/components/panel.ts

@@ -1,4 +1,4 @@
-import { createElement } from "../utils/dom";
+import { createElement, createNode } from "../utils/dom";
 import { DEFAULT_FLOATING_LAUNCHER_WIDTH } from "../defaults";
 import { AgentWidgetConfig } from "../types";
 import { positionMap } from "../utils/positioning";
@@ -16,8 +16,7 @@ export interface PanelWrapper {
   /**
    * Composer-bar mode only: viewport-fixed sibling of `wrapper` that owns
    * the persistent pill (`footer`) and peek banner. Lives outside the
-   * wrapper so it never inherits the wrapper's geometry transitions —
-   * critical for modal mode where the wrapper is `transform: translate(-50%, -50%)`
+   * wrapper so it never inherits the wrapper's geometry transitions:   * critical for modal mode where the wrapper is `transform: translate(-50%, -50%)`
    * (a transformed ancestor establishes a containing block for `position: fixed`
    * descendants, which would trap the pill inside the wrapper otherwise).
    */
@@ -32,7 +31,7 @@ export const createWrapper = (config?: AgentWidgetConfig): PanelWrapper => {
   if (composerBarMode) {
     const cb = config?.launcher?.composerBar ?? {};
     // Geometry (left/transform/bottom/top/width/max-width) is intentionally
-    // NOT set here — it's owned entirely by `applyComposerBarGeometry()` in
+    // NOT set here: it's owned entirely by `applyComposerBarGeometry()` in
     // ui.ts so that collapsed → expanded transitions can clear the previous
     // state's inline styles cleanly. Setting geometry here would persist
     // across state changes and override the per-state values, which
@@ -55,7 +54,7 @@ export const createWrapper = (config?: AgentWidgetConfig): PanelWrapper => {
     panel.style.width = "100%";
     wrapper.appendChild(panel);
 
-    // Pill lives in a separate viewport-fixed sibling — see PanelWrapper
+    // Pill lives in a separate viewport-fixed sibling: see PanelWrapper
     // docs above. ui.ts appends `peekBanner` and `footer` here, then
     // appends pillRoot to `mount` immediately after the wrapper.
     const pillRoot = createElement("div", "persona-widget-pill-root");
@@ -182,7 +181,7 @@ export interface PanelElements {
 /**
  * Composer-bar panel: minimal close-only header (× in the top-right of the
  * chat chrome). The pill (`footer`) and `peekBanner` are NOT children of
- * the panel — caller (`ui.ts`) appends them to the `pillRoot` returned by
+ * the panel: caller (`ui.ts`) appends them to the `pillRoot` returned by
  * `createWrapper`, which is a viewport-fixed sibling of the wrapper.
  * This decouples the pill from the wrapper's geometry transitions (so the
  * pill stays anchored at the viewport bottom regardless of expanded mode).
@@ -200,7 +199,7 @@ const buildComposerBarPanel = (
   );
   container.setAttribute("data-persona-theme-zone", "container");
 
-  // Minimal header — just an absolutely-positioned close button.
+  // Minimal header: just an absolutely-positioned close button.
   // The wrapper uses inline styles (top/right/z-index values) because the
   // widget's hand-authored CSS doesn't ship every Tailwind utility.
   // Composer-bar's defaults are roughly half the floating-launcher's
@@ -220,7 +219,7 @@ const buildComposerBarPanel = (
   closeButtonWrapper.style.right = "8px";
   closeButtonWrapper.style.zIndex = "10";
 
-  // Clear / "start over" button — sits immediately to the left of the close
+  // Clear / "start over" button: sits immediately to the left of the close
   // button in the panel chrome's top-right corner. Same minimal sizing as
   // the close icon (16px button, 14px icon) so the two read as a paired
   // action group rather than a header strip. Wired by `setupClearChatButton()`
@@ -246,46 +245,50 @@ const buildComposerBarPanel = (
   }
   // Placeholder header element so PanelElements.header exists (some downstream
   // code reads it). It carries `data-persona-widget-header` for plugin /
-  // selector parity but renders nothing visible — the close button is the only
+  // selector parity but renders nothing visible: the close button is the only
   // header chrome in composer-bar mode.
-  const headerPlaceholder = createElement("span", "persona-widget-header");
-  headerPlaceholder.setAttribute("data-persona-theme-zone", "header");
-  headerPlaceholder.style.display = "none";
+  const headerPlaceholder = createNode("span", {
+    className: "persona-widget-header",
+    attrs: { "data-persona-theme-zone": "header" },
+    style: { display: "none" },
+  });
 
-  // Body — extra top padding (set inline so the hand-authored widget.css
+  // Body: extra top padding (set inline so the hand-authored widget.css
   // doesn't need a `pt-12` utility) so the absolute close button doesn't
   // overlap the welcome card / first message.
-  const body = createElement(
-    "div",
-    "persona-widget-body persona-flex persona-flex-1 persona-min-h-0 persona-flex-col persona-gap-6 persona-overflow-y-auto persona-bg-persona-container persona-px-6 persona-py-6"
-  );
-  body.style.paddingTop = "48px";
-  body.id = "persona-scroll-container";
-  body.setAttribute("data-persona-theme-zone", "messages");
+  const body = createNode("div", {
+    className:
+      "persona-widget-body persona-flex persona-flex-1 persona-min-h-0 persona-flex-col persona-gap-6 persona-overflow-y-auto persona-bg-persona-container persona-px-6 persona-py-6",
+    attrs: { id: "persona-scroll-container", "data-persona-theme-zone": "messages" },
+    style: { paddingTop: "48px" },
+  });
   // Reserve the scrollbar gutter so the transcript doesn't shift horizontally
   // when streaming content first overflows and the scrollbar appears.
   body.style.setProperty("scrollbar-gutter", "stable");
 
-  const introCard = createElement(
+  const introTitle = createNode("h2", {
+    className: "persona-text-lg persona-font-semibold persona-text-persona-primary",
+    text: config?.copy?.welcomeTitle ?? "Hello 👋",
+  });
+  const introSubtitle = createNode("p", {
+    className: "persona-mt-2 persona-text-sm persona-text-persona-muted",
+    text:
+      config?.copy?.welcomeSubtitle ??
+      "Ask anything about your account or products.",
+  });
+  const introCard = createNode(
     "div",
-    "persona-rounded-2xl persona-bg-persona-surface persona-p-6"
-  );
-  introCard.style.boxShadow =
-    "var(--persona-intro-card-shadow, 0 5px 15px rgba(15, 23, 42, 0.08))";
-  introCard.setAttribute("data-persona-intro-card", "");
-  const introTitle = createElement(
-    "h2",
-    "persona-text-lg persona-font-semibold persona-text-persona-primary"
-  );
-  introTitle.textContent = config?.copy?.welcomeTitle ?? "Hello 👋";
-  const introSubtitle = createElement(
-    "p",
-    "persona-mt-2 persona-text-sm persona-text-persona-muted"
+    {
+      className: "persona-rounded-2xl persona-bg-persona-surface persona-p-6",
+      attrs: { "data-persona-intro-card": "" },
+      style: {
+        boxShadow:
+          "var(--persona-intro-card-shadow, 0 5px 15px rgba(15, 23, 42, 0.08))",
+      },
+    },
+    introTitle,
+    introSubtitle
   );
-  introSubtitle.textContent =
-    config?.copy?.welcomeSubtitle ??
-    "Ask anything about your account or products.";
-  introCard.append(introTitle, introSubtitle);
 
   const messagesWrapper = createElement(
     "div",
@@ -309,23 +312,18 @@ const buildComposerBarPanel = (
 
   // Composer overlay (interactive sheets like ask_user_question slide up here).
   // Anchored to the bottom of the container (which is `position: relative`),
-  // so sheets render at the bottom of the chat chrome — just above the gap +
+  // so sheets render at the bottom of the chat chrome: just above the gap +
   // pill that sit below the container.
-  const composerOverlay = createElement(
-    "div",
-    "persona-composer-overlay persona-pointer-events-none"
-  );
-  composerOverlay.setAttribute("data-persona-composer-overlay", "");
-  composerOverlay.style.position = "absolute";
-  composerOverlay.style.left = "0";
-  composerOverlay.style.right = "0";
-  composerOverlay.style.bottom = "0";
-  composerOverlay.style.zIndex = "20";
-
-  // Pill composer — caller appends as a sibling of container in the panel.
+  const composerOverlay = createNode("div", {
+    className: "persona-composer-overlay persona-pointer-events-none",
+    attrs: { "data-persona-composer-overlay": "" },
+    style: { position: "absolute", left: "0", right: "0", bottom: "0", zIndex: "20" },
+  });
+
+  // Pill composer: caller appends as a sibling of container in the panel.
   const composerElements: ComposerElements = buildPillComposer({ config });
 
-  // Peek banner — caller inserts as a sibling of container/footer between
+  // Peek banner: caller inserts as a sibling of container/footer between
   // them in the panel. Hidden by default; ui.ts toggles visibility.
   const { root: peekBanner, textNode: peekTextNode } = buildPillPeekBanner();
 
@@ -382,11 +380,11 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
     return buildComposerBarPanel(config, showClose);
   }
 
-  const container = createElement(
-    "div",
-    "persona-widget-container persona-flex persona-h-full persona-w-full persona-flex-1 persona-min-h-0 persona-flex-col persona-text-persona-primary persona-bg-persona-surface persona-rounded-2xl persona-overflow-hidden persona-border persona-border-persona-border"
-  );
-  container.setAttribute("data-persona-theme-zone", "container");
+  const container = createNode("div", {
+    className:
+      "persona-widget-container persona-flex persona-h-full persona-w-full persona-flex-1 persona-min-h-0 persona-flex-col persona-text-persona-primary persona-bg-persona-surface persona-rounded-2xl persona-overflow-hidden persona-border persona-border-persona-border",
+    attrs: { "data-persona-theme-zone": "container" },
+  });
 
   // Build header using layout config if available, otherwise use standard builder
   const headerLayoutConfig = config?.layout?.header;
@@ -396,40 +394,43 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
     : buildHeader({ config, showClose });
 
   // Build body with intro card and messages wrapper
-  const body = createElement(
-    "div",
-    "persona-widget-body persona-flex persona-flex-1 persona-min-h-0 persona-flex-col persona-gap-6 persona-overflow-y-auto persona-bg-persona-container persona-px-6 persona-py-6"
-  );
-  body.id = "persona-scroll-container";
-  body.setAttribute("data-persona-theme-zone", "messages");
+  const body = createNode("div", {
+    className:
+      "persona-widget-body persona-flex persona-flex-1 persona-min-h-0 persona-flex-col persona-gap-6 persona-overflow-y-auto persona-bg-persona-container persona-px-6 persona-py-6",
+    attrs: { id: "persona-scroll-container", "data-persona-theme-zone": "messages" },
+  });
   // Reserve the scrollbar gutter so the transcript doesn't shift horizontally
   // when streaming content first overflows and the scrollbar appears.
   body.style.setProperty("scrollbar-gutter", "stable");
 
-  const introCard = createElement(
-    "div",
-    "persona-rounded-2xl persona-bg-persona-surface persona-p-6"
-  );
+  const introTitle = createNode("h2", {
+    className: "persona-text-lg persona-font-semibold persona-text-persona-primary",
+    text: config?.copy?.welcomeTitle ?? "Hello 👋",
+  });
+  const introSubtitle = createNode("p", {
+    className: "persona-mt-2 persona-text-sm persona-text-persona-muted",
+    text:
+      config?.copy?.welcomeSubtitle ??
+      "Ask anything about your account or products.",
+  });
   // Box-shadow flows through the themable `components.introCard.shadow` token
   // (--persona-intro-card-shadow). Docked mode keeps a flat look by default;
   // floating mode falls back to the legacy `persona-shadow-sm` value when no
   // token is set.
-  introCard.style.boxShadow = isDockedMountMode(config)
-    ? "none"
-    : "var(--persona-intro-card-shadow, 0 5px 15px rgba(15, 23, 42, 0.08))";
-  const introTitle = createElement(
-    "h2",
-    "persona-text-lg persona-font-semibold persona-text-persona-primary"
-  );
-  introTitle.textContent = config?.copy?.welcomeTitle ?? "Hello 👋";
-  const introSubtitle = createElement(
-    "p",
-    "persona-mt-2 persona-text-sm persona-text-persona-muted"
+  const introCard = createNode(
+    "div",
+    {
+      className: "persona-rounded-2xl persona-bg-persona-surface persona-p-6",
+      attrs: { "data-persona-intro-card": "" },
+      style: {
+        boxShadow: isDockedMountMode(config)
+          ? "none"
+          : "var(--persona-intro-card-shadow, 0 5px 15px rgba(15, 23, 42, 0.08))",
+      },
+    },
+    introTitle,
+    introSubtitle
   );
-  introSubtitle.textContent =
-    config?.copy?.welcomeSubtitle ??
-    "Ask anything about your account or products.";
-  introCard.append(introTitle, introSubtitle);
 
   const messagesWrapper = createElement(
     "div",
@@ -444,7 +445,6 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
     messagesWrapper.style.width = "100%";
   }
 
-  introCard.setAttribute("data-persona-intro-card", "");
   const showWelcomeCard = config?.copy?.showWelcomeCard !== false;
   if (!showWelcomeCard) {
     introCard.style.display = "none";
@@ -473,21 +473,16 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
   // above the composer so sheets (e.g. the ask_user_question answer-pill sheet)
   // can slide up without reflowing the chat transcript above. Uses inline
   // styles for left/right/bottom because widget.css is hand-authored and
-  // doesn't ship `.persona-left-0` / `.persona-right-0` rules — without
+  // doesn't ship `.persona-left-0` / `.persona-right-0` rules: without
   // them the overlay shrink-wraps to content and collapses the sheet width.
-  const composerOverlay = createElement(
-    "div",
-    "persona-composer-overlay persona-pointer-events-none"
-  );
-  composerOverlay.setAttribute("data-persona-composer-overlay", "");
-  composerOverlay.style.position = "absolute";
-  composerOverlay.style.left = "0";
-  composerOverlay.style.right = "0";
-  composerOverlay.style.bottom = "0";
-  // Above .persona-scroll-to-bottom-indicator (z-index 10, sibling in the
-  // container) so suggestion chips and the ask-user-question sheet are not
-  // covered by the "jump to latest" button.
-  composerOverlay.style.zIndex = "20";
+  // zIndex 20 sits above .persona-scroll-to-bottom-indicator (z-index 10,
+  // sibling in the container) so suggestion chips and the ask-user-question
+  // sheet are not covered by the "jump to latest" button.
+  const composerOverlay = createNode("div", {
+    className: "persona-composer-overlay persona-pointer-events-none",
+    attrs: { "data-persona-composer-overlay": "" },
+    style: { position: "absolute", left: "0", right: "0", bottom: "0", zIndex: "20" },
+  });
 
   if (showFooter) {
     container.append(composerElements.footer);

package/src/components/pill-composer-builder.ts

@@ -1,4 +1,4 @@
-import { createElement } from "../utils/dom";
+import { createElement, createNode } from "../utils/dom";
 import { renderLucideIcon } from "../utils/icons";
 import { ComposerBuildContext, ComposerElements } from "./composer-builder";
 import {
@@ -12,7 +12,7 @@ import {
 
 export interface PillPeekBanner {
   /**
-   * The peek button itself — a chrome-less row that floats above the pill,
+   * The peek button itself: a chrome-less row that floats above the pill,
    * showing a chat-bubble icon, a trailing-100-char preview of the most
    * recent assistant message, and a chevron-up. Rendered hidden by default
    * (opacity 0, pointer-events none); ui.ts toggles
@@ -25,8 +25,7 @@ export interface PillPeekBanner {
 
 /**
  * Build the peek banner for `launcher.mountMode: "composer-bar"`. The peek
- * is the user's path back into the expanded chat from the collapsed pill —
- * it fades in during streaming OR on composer hover, and clicking it opens
+ * is the user's path back into the expanded chat from the collapsed pill: * it fades in during streaming OR on composer hover, and clicking it opens
  * the panel. ui.ts owns visibility + content updates via
  * `syncComposerBarPeek`; this factory just produces the inert DOM shell.
  *
@@ -34,11 +33,15 @@ export interface PillPeekBanner {
  * just above the pill in the collapsed-state UI.
  */
 export const buildPillPeekBanner = (): PillPeekBanner => {
-  const root = createElement("button", "persona-pill-peek") as HTMLButtonElement;
-  root.type = "button";
-  root.setAttribute("data-persona-pill-peek", "");
-  root.setAttribute("aria-label", "Show conversation");
-  root.setAttribute("tabindex", "-1");
+  const root = createNode("button", {
+    className: "persona-pill-peek",
+    attrs: {
+      type: "button",
+      "data-persona-pill-peek": "",
+      "aria-label": "Show conversation",
+      tabindex: "-1",
+    },
+  });
 
   const iconHolder = createElement("span", "persona-pill-peek__icon");
   const messageIcon = renderLucideIcon("message-square", 16, "currentColor", 1.5);
@@ -61,7 +64,7 @@ export const buildPillPeekBanner = (): PillPeekBanner => {
 /**
  * Single-row pill composer for `launcher.mountMode: "composer-bar"`.
  *
- * Same control factories as `buildComposer` — the only difference is the
+ * Same control factories as `buildComposer`: the only difference is the
  * layout shell + className. The form ships with `persona-pill-composer`
  * (no `persona-flex-col` / `persona-rounded-2xl` baggage), so the CSS
  * layout rules apply at normal specificity without `!important` fights.
@@ -71,7 +74,7 @@ export const buildPillPeekBanner = (): PillPeekBanner => {
  *
  * Suggestions row + status text are built (so plugin code that mutates
  * them keeps working and `bindComposerRefsFromFooter` finds them) but are
- * `display: none` by default — pill UX is just textarea + 3 buttons.
+ * `display: none` by default: pill UX is just textarea + 3 buttons.
  *
  * Attachment previews float ABOVE the pill in their own row when
  * AttachmentManager toggles the previews container's `display` property
@@ -80,8 +83,10 @@ export const buildPillPeekBanner = (): PillPeekBanner => {
 export const buildPillComposer = (context: ComposerBuildContext): ComposerElements => {
   const { config } = context;
 
-  const footer = createElement("div", "persona-widget-footer persona-widget-footer--pill");
-  footer.setAttribute("data-persona-theme-zone", "composer");
+  const footer = createNode("div", {
+    className: "persona-widget-footer persona-widget-footer--pill",
+    attrs: { "data-persona-theme-zone": "composer" },
+  });
 
   const suggestions = createSuggestionsRow();
   suggestions.style.display = "none";
@@ -105,12 +110,11 @@ export const buildPillComposer = (context: ComposerBuildContext): ComposerElemen
 
   // Pill form: NO `persona-flex-col`. Only the marker classes that the rest
   // of the codebase queries by name.
-  const composerForm = createElement(
-    "form",
-    "persona-widget-composer persona-pill-composer"
-  ) as HTMLFormElement;
-  composerForm.setAttribute("data-persona-composer-form", "");
-  composerForm.style.outline = "none";
+  const composerForm = createNode("form", {
+    className: "persona-widget-composer persona-pill-composer",
+    attrs: { "data-persona-composer-form": "" },
+    style: { outline: "none" },
+  });
 
   // Three columns of the grid: [paperclip?] · textarea · mic + send.
   // The empty leftActions wrapper still ships when attachments are off so
@@ -154,11 +158,11 @@ export const buildPillComposer = (context: ComposerBuildContext): ComposerElemen
 
   // The pill flattens left/right into the form's grid; there's no separate
   // wrapper. Surface the form itself as `actionsRow` to satisfy the
-  // ComposerElements contract — downstream code only treats it as an
-  // opaque ref. `bindComposerRefsFromFooter` queries for the legacy
-  // `.persona-flex.persona-items-center.persona-justify-between` class
-  // selector and won't find one in pill mode; that lookup writes to
-  // `_actionsRow` (the underscore prefix marks it as soft-optional).
+  // ComposerElements contract: downstream code only treats it as an
+  // opaque ref. The pill form intentionally carries no
+  // `data-persona-composer-actions` marker, so `bindComposerRefsFromFooter`
+  // finds no actions row in pill mode; that lookup writes to `_actionsRow`
+  // (the underscore prefix marks it as soft-optional).
   const actionsRow = composerForm;
 
   return {

package/src/components/reasoning-bubble.ts

@@ -114,7 +114,7 @@ export const createReasoningBubble = (message: AgentWidgetMessage, config?: Agen
   const defaultSummary = "Thinking...";
   const reasoningConfig = config?.reasoning ?? {};
 
-  // Elapsed helpers — defined early so they're available to renderCollapsedSummary
+  // Elapsed helpers: defined early so they're available to renderCollapsedSummary
   const startedAt = String(reasoning.startedAt ?? Date.now());
 
   const createElapsedSpan = (): HTMLElement => {
@@ -144,7 +144,7 @@ export const createReasoningBubble = (message: AgentWidgetMessage, config?: Agen
     headerContent.appendChild(title);
   }
 
-  // Status span — used in the legacy (no-template) path
+  // Status span: used in the legacy (no-template) path
   const status = createElement("span", "persona-text-xs persona-text-persona-primary");
   status.textContent = describeReasonStatus(reasoning);
   headerContent.appendChild(status);

package/src/components/suggestions.ts

@@ -45,7 +45,7 @@ export const createSuggestions = (container: HTMLElement): SuggestionButtons =>
     if (!chips || !chips.length) return;
 
     // Hide config suggestions after the first user message is sent.
-    // Agent-pushed chips skip this gate — their visibility is the caller's
+    // Agent-pushed chips skip this gate: their visibility is the caller's
     // latest-turn rule (last suggest_replies call with no user message after).
     // Use provided messages or get from session
     if (!agentPushed) {

package/src/components/tool-bubble.ts

@@ -197,7 +197,7 @@ export const createToolBubble = (message: AgentWidgetMessage, config?: AgentWidg
     title.style.color = toolCallConfig.headerTextColor;
   }
 
-  // Elapsed helpers — defined early so they're available to renderCollapsedSummary
+  // Elapsed helpers: defined early so they're available to renderCollapsedSummary
   const startedAt = String(tool.startedAt ?? Date.now());
 
   // Helper: build a <span data-tool-elapsed> that the global timer in ui.ts updates