@runtypelabs/persona 3.34.1 → 3.36.0

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

package/src/components/widget-view.test.ts

@@ -0,0 +1,181 @@
+// @vitest-environment jsdom
+
+import { describe, expect, it, vi } from "vitest";
+import { createWidgetView, resolveLauncher } from "./widget-view";
+import type { HeaderElements } from "./header-builder";
+import type { AgentWidgetConfig } from "../types";
+import type { AgentWidgetPlugin } from "../plugins/types";
+
+describe("createWidgetView: default assembly", () => {
+  const config: AgentWidgetConfig = {
+    apiUrl: "/api",
+    voiceRecognition: { enabled: true, provider: { type: "runtype" } },
+    attachments: { enabled: true },
+  };
+
+  it("groups shell, transcript, header, and composer refs over the real nodes", () => {
+    const view = createWidgetView({ config, showClose: true });
+
+    // Shell. The empty `panel` is wired to the `container` later by ui.ts
+    // (panel.appendChild(container)); createWidgetView preserves that split.
+    expect(view.shell.wrapper.contains(view.shell.panel)).toBe(true);
+    expect(view.shell.pillRoot).toBeUndefined();
+
+    // Transcript subtree is wired by buildPanel
+    expect(view.transcript.container.contains(view.transcript.body)).toBe(true);
+    expect(view.transcript.body.contains(view.transcript.messagesWrapper)).toBe(true);
+
+    // Header + composer are mounted in the container
+    expect(view.transcript.container.contains(view.header.element)).toBe(true);
+    expect(view.transcript.container.contains(view.composer.footer)).toBe(true);
+
+    // Grouped refs are the same nodes as the raw flat panelElements
+    expect(view.composer.textarea).toBe(view.panelElements.textarea);
+    expect(view.composer.footer).toBe(view.panelElements.footer);
+    expect(view.header.element).toBe(view.panelElements.header);
+  });
+
+  it("exposes the stable composer ref attributes", () => {
+    const view = createWidgetView({ config, showClose: true });
+
+    expect(view.composer.textarea.getAttribute("data-persona-composer-input")).toBe("");
+    expect(view.composer.sendButton.getAttribute("data-persona-composer-submit")).toBe("");
+    expect(view.composer.statusText.getAttribute("data-persona-composer-status")).toBe("");
+    expect(view.composer.suggestions.getAttribute("data-persona-composer-suggestions")).toBe("");
+    expect(view.composer.actionsRow.getAttribute("data-persona-composer-actions")).toBe("");
+    expect(view.composer.micButton).not.toBeNull();
+    expect(
+      view.composer.attachmentButton?.getAttribute("data-persona-composer-attachment-button")
+    ).toBe("");
+    expect(
+      view.composer.attachmentInput?.getAttribute("data-persona-composer-attachment-input")
+    ).toBe("");
+    expect(
+      view.composer.attachmentPreviewsContainer?.getAttribute(
+        "data-persona-composer-attachment-previews"
+      )
+    ).toBe("");
+  });
+
+  it("hides header and footer when layout disables them", () => {
+    const view = createWidgetView({
+      config: { apiUrl: "/api", layout: { showHeader: false, showFooter: false } },
+      showClose: true,
+    });
+
+    expect(view.header.element.style.display).toBe("none");
+    expect(view.composer.footer.style.display).toBe("none");
+  });
+});
+
+describe("createWidgetView: composer-bar assembly", () => {
+  const config: AgentWidgetConfig = {
+    apiUrl: "/api",
+    launcher: { mountMode: "composer-bar" },
+  };
+
+  it("exposes the pill root and peek banner", () => {
+    const view = createWidgetView({ config, showClose: true });
+
+    expect(view.shell.pillRoot).toBeInstanceOf(HTMLElement);
+    expect(view.composer.peekBanner).toBeInstanceOf(HTMLElement);
+    expect(view.composer.peekTextNode).toBeInstanceOf(HTMLElement);
+    // Composer-bar uses a hidden placeholder header (close button is the chrome).
+    expect(view.header.element.style.display).toBe("none");
+  });
+});
+
+describe("createWidgetView: replacement helpers", () => {
+  it("replaceHeader swaps the mounted element and mirrors sub-refs", () => {
+    const view = createWidgetView({ config: { apiUrl: "/api" }, showClose: true });
+    const original = view.header.element;
+    const parent = original.parentElement;
+
+    const next: HeaderElements = {
+      header: document.createElement("header"),
+      iconHolder: document.createElement("span"),
+      headerTitle: document.createElement("span"),
+      headerSubtitle: document.createElement("span"),
+      closeButton: document.createElement("button"),
+      closeButtonWrapper: document.createElement("div"),
+      clearChatButton: null,
+      clearChatButtonWrapper: null,
+    };
+
+    const returned = view.replaceHeader(next);
+
+    expect(returned).toBe(next);
+    expect(view.header.element).toBe(next.header);
+    expect(view.header.iconHolder).toBe(next.iconHolder);
+    expect(view.header.closeButton).toBe(next.closeButton);
+    expect(parent?.contains(next.header)).toBe(true);
+    expect(parent?.contains(original)).toBe(false);
+  });
+
+  it("replaceComposer swaps the mounted footer and updates the ref", () => {
+    const view = createWidgetView({ config: { apiUrl: "/api" }, showClose: true });
+    const original = view.composer.footer;
+    const parent = original.parentElement;
+    const nextFooter = document.createElement("div");
+
+    view.replaceComposer(nextFooter);
+
+    expect(view.composer.footer).toBe(nextFooter);
+    expect(parent?.contains(nextFooter)).toBe(true);
+    expect(parent?.contains(original)).toBe(false);
+  });
+});
+
+describe("resolveLauncher", () => {
+  const config: AgentWidgetConfig = { apiUrl: "/api" };
+
+  it("builds the default launcher controller and wires onToggle", () => {
+    const onToggle = vi.fn();
+    const { instance, element } = resolveLauncher({ config, plugins: [], onToggle });
+
+    expect(instance).not.toBeNull();
+    expect(element).toBe(instance?.element);
+    expect(element.tagName).toBe("BUTTON");
+
+    element.dispatchEvent(new Event("click"));
+    expect(onToggle).toHaveBeenCalledTimes(1);
+  });
+
+  it("uses a plugin-provided launcher element and returns no controller", () => {
+    const custom = document.createElement("div");
+    custom.id = "custom-launcher";
+    const plugin: AgentWidgetPlugin = {
+      id: "custom",
+      renderLauncher: ({ defaultRenderer }) => {
+        // The default renderer is still callable; the plugin opts to ignore it.
+        expect(defaultRenderer().tagName).toBe("BUTTON");
+        return custom;
+      },
+    };
+
+    const { instance, element } = resolveLauncher({
+      config,
+      plugins: [plugin],
+      onToggle: () => {},
+    });
+
+    expect(instance).toBeNull();
+    expect(element).toBe(custom);
+  });
+
+  it("falls back to the default launcher when the plugin returns null", () => {
+    const plugin: AgentWidgetPlugin = {
+      id: "passthrough",
+      renderLauncher: () => null,
+    };
+
+    const { instance, element } = resolveLauncher({
+      config,
+      plugins: [plugin],
+      onToggle: () => {},
+    });
+
+    expect(instance).not.toBeNull();
+    expect(element).toBe(instance?.element);
+  });
+});