@runtypelabs/persona 3.17.0 → 3.19.0

package/src/components/panel.ts

@@ -2,20 +2,72 @@ import { createElement } from "../utils/dom";
 import { DEFAULT_FLOATING_LAUNCHER_WIDTH } from "../defaults";
 import { AgentWidgetConfig } from "../types";
 import { positionMap } from "../utils/positioning";
-import { isDockedMountMode } from "../utils/dock";
+import { isComposerBarMountMode, isDockedMountMode } from "../utils/dock";
 import { DEFAULT_OVERLAY_Z_INDEX } from "../utils/constants";
 import { buildHeader, attachHeaderToContainer, HeaderElements } from "./header-builder";
 import { buildHeaderWithLayout } from "./header-layouts";
+import { createCloseButton, createClearChatButton } from "./header-parts";
 import { buildComposer, ComposerElements } from "./composer-builder";
+import { buildPillComposer, buildPillPeekBanner } from "./pill-composer-builder";
 
 export interface PanelWrapper {
   wrapper: HTMLElement;
   panel: HTMLElement;
+  /**
+   * 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%)`
+   * (a transformed ancestor establishes a containing block for `position: fixed`
+   * descendants, which would trap the pill inside the wrapper otherwise).
+   */
+  pillRoot?: HTMLElement;
 }
 
 export const createWrapper = (config?: AgentWidgetConfig): PanelWrapper => {
   const launcherEnabled = config?.launcher?.enabled ?? true;
   const dockedMode = isDockedMountMode(config);
+  const composerBarMode = isComposerBarMountMode(config);
+
+  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
+    // 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
+    // previously caused expanded panels to render at collapsed dimensions.
+    const wrapper = createElement(
+      "div",
+      "persona-widget-wrapper persona-fixed persona-transition"
+    );
+    wrapper.setAttribute("data-persona-composer-bar", "");
+    wrapper.dataset.state = "collapsed";
+    wrapper.dataset.expandedSize = cb.expandedSize ?? "anchored";
+    wrapper.style.zIndex = String(
+      config?.launcher?.zIndex ?? DEFAULT_OVERLAY_Z_INDEX
+    );
+
+    const panel = createElement(
+      "div",
+      "persona-widget-panel persona-relative persona-flex persona-flex-1 persona-min-h-0 persona-flex-col"
+    );
+    panel.style.width = "100%";
+    wrapper.appendChild(panel);
+
+    // 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");
+    pillRoot.setAttribute("data-persona-composer-bar", "");
+    pillRoot.dataset.state = "collapsed";
+    pillRoot.dataset.expandedSize = cb.expandedSize ?? "anchored";
+    pillRoot.style.zIndex = String(
+      config?.launcher?.zIndex ?? DEFAULT_OVERLAY_Z_INDEX
+    );
+
+    return { wrapper, panel, pillRoot };
+  }
 
   if (dockedMode) {
     const wrapper = createElement(
@@ -81,6 +133,12 @@ export interface PanelElements {
   container: HTMLElement;
   body: HTMLElement;
   messagesWrapper: HTMLElement;
+  /**
+   * Absolute-positioned slot above the composer footer. Interactive sheets
+   * (e.g. the answer-pill sheet for the ask_user_question tool) mount here
+   * so they slide in without reflowing the chat transcript.
+   */
+  composerOverlay: HTMLElement;
   suggestions: HTMLElement;
   textarea: HTMLTextAreaElement;
   sendButton: HTMLButtonElement;
@@ -112,14 +170,218 @@ export interface PanelElements {
   rightActions: HTMLElement;
   /** Swap the send button between its send and stop appearances. */
   setSendButtonMode: (mode: "send" | "stop") => void;
+  /**
+   * Composer-bar peek banner: the chrome-less row above the pill that
+   * shows a trailing preview of the most recent assistant message.
+   * Undefined for non-composer-bar modes.
+   */
+  peekBanner?: HTMLButtonElement;
+  peekTextNode?: HTMLElement;
 }
 
+/**
+ * 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
+ * `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).
+ */
+const buildComposerBarPanel = (
+  config: AgentWidgetConfig | undefined,
+  showClose: boolean,
+): PanelElements => {
+  // Container = the chat panel chrome (border + bg + radius + shadow applied
+  // inline by `applyFullHeightStyles` in ui.ts). `position: relative` anchors
+  // the absolute close button + composerOverlay.
+  const container = createElement(
+    "div",
+    "persona-widget-container persona-relative persona-flex persona-flex-1 persona-min-h-0 persona-flex-col persona-text-persona-primary"
+  );
+  container.setAttribute("data-persona-theme-zone", "container");
+
+  // 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
+  // (button 16px, icon 14px) to match the minimal aesthetic; the user can
+  // still override via `launcher.closeButtonSize`.
+  const { button: closeButton, wrapper: closeButtonWrapper } = createCloseButton(
+    config,
+    {
+      showClose,
+      wrapperClassName: "persona-composer-bar-close",
+      buttonSize: "16px",
+      iconSize: "14px",
+    }
+  );
+  closeButtonWrapper.style.position = "absolute";
+  closeButtonWrapper.style.top = "8px";
+  closeButtonWrapper.style.right = "8px";
+  closeButtonWrapper.style.zIndex = "10";
+
+  // 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()`
+  // in ui.ts via the `clearChatButton` field on PanelElements.
+  //
+  // Right offset = close button right (8px) + close button width (16px) +
+  // 8px inter-button gap = 32px.
+  const clearChatEnabled = config?.launcher?.clearChat?.enabled ?? true;
+  let clearChatButton: HTMLButtonElement | null = null;
+  let clearChatButtonWrapper: HTMLElement | null = null;
+  if (clearChatEnabled) {
+    const parts = createClearChatButton(config, {
+      wrapperClassName: "persona-composer-bar-clear-chat",
+      buttonSize: "16px",
+      iconSize: "14px",
+    });
+    clearChatButton = parts.button;
+    clearChatButtonWrapper = parts.wrapper;
+    clearChatButtonWrapper.style.position = "absolute";
+    clearChatButtonWrapper.style.top = "8px";
+    clearChatButtonWrapper.style.right = "32px";
+    clearChatButtonWrapper.style.zIndex = "10";
+  }
+  // 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
+  // header chrome in composer-bar mode.
+  const headerPlaceholder = createElement("span", "persona-widget-header");
+  headerPlaceholder.setAttribute("data-persona-theme-zone", "header");
+  headerPlaceholder.style.display = "none";
+
+  // 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 introCard = createElement(
+    "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"
+  );
+  introSubtitle.textContent =
+    config?.copy?.welcomeSubtitle ??
+    "Ask anything about your account or products.";
+  introCard.append(introTitle, introSubtitle);
+
+  const messagesWrapper = createElement(
+    "div",
+    "persona-flex persona-flex-col persona-gap-3"
+  );
+  const contentMaxWidth = config?.layout?.contentMaxWidth;
+  if (contentMaxWidth) {
+    messagesWrapper.style.maxWidth = contentMaxWidth;
+    messagesWrapper.style.marginLeft = "auto";
+    messagesWrapper.style.marginRight = "auto";
+    messagesWrapper.style.width = "100%";
+  }
+
+  const showWelcomeCard = config?.copy?.showWelcomeCard !== false;
+  if (!showWelcomeCard) {
+    introCard.style.display = "none";
+    body.classList.remove("persona-gap-6");
+    body.classList.add("persona-gap-3");
+  }
+  body.append(introCard, messagesWrapper);
+
+  // 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 +
+  // 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 composerElements: ComposerElements = buildPillComposer({ config });
+
+  // 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();
+
+  // Container = [close button (absolute), placeholder header, body, overlay].
+  // Footer (pill) is intentionally NOT appended here.
+  container.append(headerPlaceholder, closeButtonWrapper, body, composerOverlay);
+  if (clearChatButtonWrapper) {
+    container.appendChild(clearChatButtonWrapper);
+  }
+
+  return {
+    container,
+    body,
+    messagesWrapper,
+    composerOverlay,
+    suggestions: composerElements.suggestions,
+    textarea: composerElements.textarea,
+    sendButton: composerElements.sendButton,
+    sendButtonWrapper: composerElements.sendButtonWrapper,
+    micButton: composerElements.micButton,
+    micButtonWrapper: composerElements.micButtonWrapper,
+    composerForm: composerElements.composerForm,
+    statusText: composerElements.statusText,
+    introTitle,
+    introSubtitle,
+    closeButton,
+    closeButtonWrapper,
+    clearChatButton,
+    clearChatButtonWrapper,
+    iconHolder: createElement("span"),
+    headerTitle: createElement("span"),
+    headerSubtitle: createElement("span"),
+    header: headerPlaceholder,
+    footer: composerElements.footer,
+    attachmentButton: composerElements.attachmentButton,
+    attachmentButtonWrapper: composerElements.attachmentButtonWrapper,
+    attachmentInput: composerElements.attachmentInput,
+    attachmentPreviewsContainer: composerElements.attachmentPreviewsContainer,
+    actionsRow: composerElements.actionsRow,
+    leftActions: composerElements.leftActions,
+    rightActions: composerElements.rightActions,
+    setSendButtonMode: composerElements.setSendButtonMode,
+    peekBanner,
+    peekTextNode,
+  };
+};
+
 export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelElements => {
-  // Use flex-1 and min-h-0 to ensure the container fills its parent and allows
-  // the body (chat messages area) to scroll while header/footer stay fixed
+  // Composer-bar mode renders a purpose-built panel: minimal close-only
+  // header (small × in the top-right of the chat panel chrome), and the
+  // pill (footer) is a SIBLING of the container so it stays visible/usable
+  // when the chat is expanded above it.
+  if (isComposerBarMountMode(config)) {
+    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-bg-persona-surface persona-text-persona-primary persona-rounded-2xl persona-overflow-hidden persona-border persona-border-persona-border"
+    "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");
 
@@ -138,10 +400,17 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
   body.id = "persona-scroll-container";
   body.setAttribute("data-persona-theme-zone", "messages");
   
-  const introCardClasses = isDockedMountMode(config)
-    ? "persona-rounded-2xl persona-bg-persona-surface persona-p-6"
-    : "persona-rounded-2xl persona-bg-persona-surface persona-p-6 persona-shadow-sm";
-  const introCard = createElement("div", introCardClasses);
+  const introCard = createElement(
+    "div",
+    "persona-rounded-2xl persona-bg-persona-surface persona-p-6"
+  );
+  // 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"
@@ -178,7 +447,8 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
   }
   body.append(introCard, messagesWrapper);
 
-  // Build composer/footer using extracted builder
+  // composer-bar mode early-returned above with its own pill builder; this
+  // path always uses the standard column-stacked composer card.
   const composerElements: ComposerElements = buildComposer({ config });
   const showFooter = config?.layout?.showFooter !== false; // default to true
 
@@ -193,6 +463,26 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
   
   container.append(body);
   
+  // Composer overlay slot: sits between body and footer, absolutely positioned
+  // 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
+  // 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";
+
   if (showFooter) {
     container.append(composerElements.footer);
   } else {
@@ -201,10 +491,14 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
     container.append(composerElements.footer);
   }
 
+  // Append overlay last so it stacks above the footer / body content.
+  container.append(composerOverlay);
+
   return {
     container,
     body,
     messagesWrapper,
+    composerOverlay,
     suggestions: composerElements.suggestions,
     textarea: composerElements.textarea,
     sendButton: composerElements.sendButton,

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

@@ -0,0 +1,85 @@
+// @vitest-environment jsdom
+
+import { describe, expect, it } from "vitest";
+import { buildPillComposer } from "./pill-composer-builder";
+import type { AgentWidgetConfig } from "../types";
+
+describe("buildPillComposer (single-row pill composer)", () => {
+  it("returns a footer wrapping the pill form, with stable selectors preserved", () => {
+    const config: AgentWidgetConfig = {
+      apiUrl: "/api",
+      attachments: { enabled: true },
+      voiceRecognition: { enabled: true, provider: { type: "runtype" } },
+    };
+    const elements = buildPillComposer({ config });
+
+    expect(elements.footer.classList.contains("persona-widget-footer--pill")).toBe(true);
+    expect(elements.composerForm.classList.contains("persona-pill-composer")).toBe(true);
+    expect(elements.composerForm.classList.contains("persona-widget-composer")).toBe(true);
+    // Crucial: the pill form does NOT carry the column-stack utility classes
+    // that fight CSS layout rules.
+    expect(elements.composerForm.classList.contains("persona-flex-col")).toBe(false);
+    expect(elements.composerForm.classList.contains("persona-rounded-2xl")).toBe(false);
+
+    expect(elements.composerForm.getAttribute("data-persona-composer-form")).toBe("");
+    expect(elements.textarea.getAttribute("data-persona-composer-input")).toBe("");
+    expect(elements.sendButton.getAttribute("data-persona-composer-submit")).toBe("");
+  });
+
+  it("hides suggestions and status text by default in pill mode", () => {
+    const elements = buildPillComposer({ config: { apiUrl: "/api" } });
+    expect(elements.suggestions.style.display).toBe("none");
+    expect(elements.statusText.style.display).toBe("none");
+  });
+
+  it("renders the paperclip in the leftActions cell when attachments are enabled", () => {
+    const elements = buildPillComposer({
+      config: { apiUrl: "/api", attachments: { enabled: true } },
+    });
+    expect(elements.attachmentButton).not.toBeNull();
+    expect(elements.leftActions.contains(elements.attachmentButtonWrapper!)).toBe(true);
+  });
+
+  it("renders the mic in the rightActions cell when voice is enabled", () => {
+    const elements = buildPillComposer({
+      config: {
+        apiUrl: "/api",
+        voiceRecognition: { enabled: true, provider: { type: "runtype" } },
+      },
+    });
+    expect(elements.micButton).not.toBeNull();
+    expect(elements.rightActions.contains(elements.micButtonWrapper!)).toBe(true);
+  });
+
+  it("places the previews container ABOVE the pill (in the footer, before the form)", () => {
+    const elements = buildPillComposer({
+      config: { apiUrl: "/api", attachments: { enabled: true } },
+    });
+    const footerChildren = Array.from(elements.footer.children);
+    expect(footerChildren.indexOf(elements.attachmentPreviewsContainer!)).toBeLessThan(
+      footerChildren.indexOf(elements.composerForm)
+    );
+    expect(elements.attachmentPreviewsContainer!.classList.contains("persona-pill-composer__previews")).toBe(true);
+  });
+
+  it("forms a 3-cell layout: leftActions · textarea · rightActions inside the form", () => {
+    const elements = buildPillComposer({
+      config: { apiUrl: "/api", attachments: { enabled: true } },
+    });
+    // After the (hidden) file input, the next three children are the grid cells.
+    const formChildren = Array.from(elements.composerForm.children).filter(
+      (c) => (c as HTMLElement).tagName !== "INPUT"
+    );
+    expect(formChildren[0]).toBe(elements.leftActions);
+    expect(formChildren[1]).toBe(elements.textarea);
+    expect(formChildren[2]).toBe(elements.rightActions);
+  });
+
+  it("returns null for optional controls when disabled (matching ComposerElements contract)", () => {
+    const elements = buildPillComposer({ config: { apiUrl: "/api" } });
+    expect(elements.attachmentButton).toBeNull();
+    expect(elements.attachmentInput).toBeNull();
+    expect(elements.attachmentPreviewsContainer).toBeNull();
+    expect(elements.micButton).toBeNull();
+  });
+});

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

@@ -0,0 +1,183 @@
+import { createElement } from "../utils/dom";
+import { renderLucideIcon } from "../utils/icons";
+import { ComposerBuildContext, ComposerElements } from "./composer-builder";
+import {
+  createAttachmentControls,
+  createComposerTextarea,
+  createMicButton,
+  createSendButton,
+  createStatusText,
+  createSuggestionsRow,
+} from "./composer-parts";
+
+export interface PillPeekBanner {
+  /**
+   * 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
+   * `.persona-pill-peek--visible` based on streaming/hover/open state.
+   */
+  root: HTMLButtonElement;
+  /** Wrapper around the trailing message preview text. */
+  textNode: HTMLElement;
+}
+
+/**
+ * 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
+ * the panel. ui.ts owns visibility + content updates via
+ * `syncComposerBarPeek`; this factory just produces the inert DOM shell.
+ *
+ * Placed in the panel between `container` and `footer` so it visually sits
+ * 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 iconHolder = createElement("span", "persona-pill-peek__icon");
+  const messageIcon = renderLucideIcon("message-square", 16, "currentColor", 1.5);
+  if (messageIcon) {
+    iconHolder.appendChild(messageIcon);
+  }
+
+  const textNode = createElement("span", "persona-pill-peek__text");
+
+  const caret = createElement("span", "persona-pill-peek__caret");
+  const caretIcon = renderLucideIcon("chevron-up", 16, "currentColor", 1.5);
+  if (caretIcon) {
+    caret.appendChild(caretIcon);
+  }
+
+  root.append(iconHolder, textNode, caret);
+  return { root, textNode };
+};
+
+/**
+ * Single-row pill composer for `launcher.mountMode: "composer-bar"`.
+ *
+ * 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.
+ *
+ * Returns the same `ComposerElements` shape as `buildComposer` so panel.ts
+ * and ui.ts plumbing is unconditional past the choice of builder.
+ *
+ * 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.
+ *
+ * Attachment previews float ABOVE the pill in their own row when
+ * AttachmentManager toggles the previews container's `display` property
+ * as items are added/removed.
+ */
+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 suggestions = createSuggestionsRow();
+  suggestions.style.display = "none";
+  const statusText = createStatusText(config);
+  statusText.style.display = "none";
+
+  const { textarea, attachAutoResize } = createComposerTextarea(config);
+  // Pill textarea: starts single-line, allowed to grow up to ~5 lines so
+  // expanded mode still supports multi-line composition. attachAutoResize
+  // reads max-height at event time, so this override flows through.
+  textarea.style.maxHeight = "100px";
+  attachAutoResize();
+
+  const send = createSendButton(config);
+  const mic = createMicButton(config);
+  const attachment = createAttachmentControls(config);
+
+  if (attachment) {
+    attachment.previewsContainer.classList.add("persona-pill-composer__previews");
+  }
+
+  // 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";
+
+  // Three columns of the grid: [paperclip?] · textarea · mic + send.
+  // The empty leftActions wrapper still ships when attachments are off so
+  // the grid has a consistent first cell (auto width → collapses to 0).
+  const leftActions = createElement(
+    "div",
+    "persona-widget-composer__left-actions persona-pill-composer__left"
+  );
+  if (attachment) leftActions.append(attachment.wrapper);
+
+  const rightActions = createElement(
+    "div",
+    "persona-widget-composer__right-actions persona-pill-composer__right"
+  );
+  if (mic) rightActions.append(mic.wrapper);
+  rightActions.append(send.wrapper);
+
+  composerForm.addEventListener("click", (e) => {
+    if (
+      e.target !== send.button &&
+      e.target !== send.wrapper &&
+      e.target !== mic?.button &&
+      e.target !== mic?.wrapper &&
+      e.target !== attachment?.button &&
+      e.target !== attachment?.wrapper
+    ) {
+      textarea.focus();
+    }
+  });
+
+  if (attachment) composerForm.append(attachment.input);
+  composerForm.append(leftActions, textarea, rightActions);
+
+  // Footer assembly:
+  //   [previews row, hidden until attachments exist]
+  //   [pill form]
+  //   [hidden suggestions]
+  //   [hidden status]
+  if (attachment) footer.append(attachment.previewsContainer);
+  footer.append(composerForm, suggestions, statusText);
+
+  // 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).
+  const actionsRow = composerForm;
+
+  return {
+    footer,
+    suggestions,
+    composerForm,
+    textarea,
+    sendButton: send.button,
+    sendButtonWrapper: send.wrapper,
+    micButton: mic?.button ?? null,
+    micButtonWrapper: mic?.wrapper ?? null,
+    statusText,
+    attachmentButton: attachment?.button ?? null,
+    attachmentButtonWrapper: attachment?.wrapper ?? null,
+    attachmentInput: attachment?.input ?? null,
+    attachmentPreviewsContainer: attachment?.previewsContainer ?? null,
+    actionsRow,
+    leftActions,
+    rightActions,
+    setSendButtonMode: send.setMode,
+  };
+};