@runtypelabs/persona 4.33.0 → 4.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "4.33.0",
+  "version": "4.34.0",
   "description": "Themeable, pluggable streaming agent widget for websites, in plain JS with support for voice input and reasoning / tool output.",
   "type": "module",
   "main": "dist/index.cjs",
@@ -191,7 +191,7 @@
     "@types/jsdom": "^30.0.0",
     "@types/node": "^20.12.7",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
-    "@vitest/ui": "^5.0.3",
+    "@vitest/ui": "^5.0.5",
     "acorn": "^8.15.0",
     "fake-indexeddb": "^6.2.5",
     "jsdom": "^28.1.0",
@@ -199,9 +199,9 @@
     "rimraf": "^5.0.5",
     "size-limit": "^12.1.0",
     "terser": "^5.49.0",
-    "tsdown": "^0.23.0",
+    "tsdown": "^0.23.2",
     "typescript": "^6.0.3",
-    "vitest": "^5.0.3",
+    "vitest": "^5.0.5",
     "webmcp-polyfill-v6": "npm:@mcp-b/webmcp-polyfill@6.0.0"
   },
   "engines": {

package/src/components/event-stream-view.test.ts

@@ -36,6 +36,11 @@ function createMockElement(tag = "div"): any {
     clientHeight: 300,
     // For <select>
     options: [] as any[],
+    append(...nodes: (Node | string)[]) {
+      for (const node of nodes) {
+        el.appendChild(typeof node === "string" ? { nodeType: 3, textContent: node } : node);
+      }
+    },
     appendChild(child: any) {
       // Handle DocumentFragment: move its children into this element
       if (child.tagName === "FRAGMENT") {

package/src/components/message-bubble.ts

@@ -25,6 +25,11 @@ import { createMentionTokenElement } from "../utils/mention-token";
 import { createIconButton } from "../utils/buttons";
 import { renderLucideIcon } from "../utils/icons";
 import { IMAGE_ONLY_MESSAGE_FALLBACK_TEXT } from "../utils/content";
+import {
+  applyUserCollapseState,
+  createUserCollapseRegion,
+  type UserMessageCollapseRender,
+} from "./user-message-collapse";
 import {
   applyStreamBuffer,
   createSkeletonPlaceholder,
@@ -998,6 +1003,11 @@ export type CreateStandardBubbleOptions = {
    * Full widget config (needed for loading indicator context)
    */
   widgetConfig?: import("../types").AgentWidgetConfig;
+  /**
+   * Long user message collapse (`features.userMessageCollapse`). When set on
+   * a user bubble, its content is wrapped in a clip region with the toggle.
+   */
+  userCollapse?: UserMessageCollapseRender;
 };
 
 /**
@@ -1238,6 +1248,12 @@ export const createStandardBubble = (
     }
   }
 
+  // Everything a long user message can spill (attachments, chips, text) goes
+  // in the collapse region; the timestamp and actions stay outside the clip.
+  const userCollapse = message.role === "user" ? options?.userCollapse : undefined;
+  const collapseRegion = userCollapse ? createUserCollapseRegion(message.id, userCollapse.maxHeight) : null;
+  const contentParent = collapseRegion ?? bubble;
+
   if (imageParts.length > 0) {
     const imagePreviews = createMessageImagePreviews(
       imageParts,
@@ -1250,7 +1266,7 @@ export const createStandardBubble = (
     );
 
     if (imagePreviews) {
-      bubble.appendChild(imagePreviews);
+      contentParent.appendChild(imagePreviews);
     } else if (shouldHideTextUntilPreviewFails && textContentDiv) {
       textContentDiv.style.display = "";
     }
@@ -1260,7 +1276,7 @@ export const createStandardBubble = (
   if (audioParts.length > 0) {
     const audioPreviews = createMessageAudioPreviews(audioParts);
     if (audioPreviews) {
-      bubble.appendChild(audioPreviews);
+      contentParent.appendChild(audioPreviews);
     }
   }
 
@@ -1268,7 +1284,7 @@ export const createStandardBubble = (
   if (videoParts.length > 0) {
     const videoPreviews = createMessageVideoPreviews(videoParts);
     if (videoPreviews) {
-      bubble.appendChild(videoPreviews);
+      contentParent.appendChild(videoPreviews);
     }
   }
 
@@ -1276,7 +1292,7 @@ export const createStandardBubble = (
   if (fileParts.length > 0) {
     const filePreviews = createMessageFilePreviews(fileParts);
     if (filePreviews) {
-      bubble.appendChild(filePreviews);
+      contentParent.appendChild(filePreviews);
     }
   }
 
@@ -1286,10 +1302,14 @@ export const createStandardBubble = (
     ? null
     : createMessageMentionChips(message.contextMentions);
   if (mentionChips) {
-    bubble.appendChild(mentionChips);
+    contentParent.appendChild(mentionChips);
   }
 
-  bubble.appendChild(contentDiv);
+  contentParent.appendChild(contentDiv);
+  if (collapseRegion && userCollapse) {
+    bubble.appendChild(collapseRegion);
+    applyUserCollapseState(bubble, collapseRegion, message.id, userCollapse);
+  }
 
   // Add timestamp below if configured
   if (showTimestamp && timestampPosition === "below" && message.createdAt) {

package/src/components/scroll-to-bottom.test.ts

@@ -40,6 +40,49 @@ describe("scroll-to-bottom chrome", () => {
     control.destroy();
   });
 
+  it("names a pending approval below with a labelled shield pill, then reverts", () => {
+    const control = createScrollToBottomControl(icon, "transcript");
+    const config: AgentWidgetConfig = { future: { v5Defaults: true } };
+    control.update(config, true, false, 2, true);
+    const el = control.element;
+    expect(el.hasAttribute("data-persona-scroll-to-bottom-approval")).toBe(true);
+    expect(el.getAttribute("data-persona-scroll-to-bottom-has-label")).toBe("true");
+    expect(el.textContent).toBe("Approval needed");
+    expect(el.querySelector("svg")?.getAttribute("data-icon")).toBe("shield-check");
+    // The label replaces the unread count; assistive tech hears where it leads.
+    expect(el.querySelector<HTMLElement>("[data-persona-scroll-to-bottom-count]")?.style.display).toBe("none");
+    expect(el.getAttribute("aria-label")).toBe("Approval needed below. Jump to latest");
+
+    // Hidden, the approval state never shows.
+    control.update(config, false, false, 0, true);
+    expect(el.hasAttribute("data-persona-scroll-to-bottom-approval")).toBe(false);
+
+    control.update(config, true, false, 2, false);
+    expect(el.hasAttribute("data-persona-scroll-to-bottom-approval")).toBe(false);
+    expect(el.getAttribute("data-persona-scroll-to-bottom-has-label")).toBe("false");
+    expect(el.querySelector("svg")?.getAttribute("data-icon")).toBe("arrow-down");
+    expect(el.getAttribute("aria-label")).toBe("Jump to latest (2 new)");
+    control.destroy();
+  });
+
+  it("uses a custom approval label, opts out with an empty one, and tells custom glyphs", () => {
+    const states: string[] = [];
+    const renderIcon = vi.fn((_context: AgentWidgetScrollToBottomIconContext) => ({
+      element: document.createElement("span"),
+      update: (next: AgentWidgetScrollToBottomIconContext) => { states.push(next.state.activity); },
+    }));
+    const control = createScrollToBottomControl(icon, "transcript");
+    control.update({ features: { scrollToBottom: { approvalLabel: "Review request", renderIcon } } }, true, false, 0, true);
+    expect(control.element.textContent).toBe("Review request");
+    expect(renderIcon.mock.calls[0][0].state.activity).toBe("approval-below");
+    control.update({ features: { scrollToBottom: { approvalLabel: "", renderIcon } } }, true, false, 1, true);
+    expect(control.element.getAttribute("data-persona-scroll-to-bottom-has-label")).toBe("false");
+    expect(control.element.getAttribute("aria-label")).toBe("Approval needed below. Jump to latest");
+    control.update({ features: { scrollToBottom: { renderIcon } } }, true, false, 0, false);
+    expect(states.at(-1)).toBe("idle");
+    control.destroy();
+  });
+
   it("makes fading controls inert immediately and returns focus only when owned, including Shadow DOM", () => {
     const host = document.createElement("div"); document.body.appendChild(host);
     const root = host.attachShadow({ mode: "open" });
@@ -122,6 +165,98 @@ describe("scroll-to-bottom chrome", () => {
     control.destroy(); warning.mockRestore();
   });
 
+  describe("approval morph", () => {
+    const stubAnimate = () => {
+      const calls: { target: Element; keyframes: Keyframe[]; options: KeyframeAnimationOptions; animation: { cancel: ReturnType<typeof vi.fn> } }[] = [];
+      const original = (HTMLElement.prototype as { animate?: unknown }).animate;
+      (HTMLElement.prototype as { animate?: unknown }).animate = function (this: Element, keyframes: Keyframe[], options: KeyframeAnimationOptions) {
+        const animation = { cancel: vi.fn(), finished: new Promise<void>(() => {}) };
+        calls.push({ target: this, keyframes, options, animation });
+        return animation;
+      };
+      return { calls, restore: () => { (HTMLElement.prototype as { animate?: unknown }).animate = original; } };
+    };
+
+    it("morphs a visible arrow into the pill on the theme's motion tokens, and back", () => {
+      const { calls, restore } = stubAnimate();
+      try {
+        const control = createScrollToBottomControl(icon, "transcript");
+        document.body.appendChild(control.element);
+        control.element.style.setProperty("--persona-motion-duration-base", "0.3s");
+        control.element.style.setProperty("--persona-motion-easing", "cubic-bezier(0.2, 0, 0, 1)");
+        const config: AgentWidgetConfig = { future: { v5Defaults: true } };
+        control.update(config, true);
+        expect(calls).toHaveLength(0);
+
+        control.update(config, true, false, 0, true);
+        const [own, labelFade] = calls;
+        expect(own.target).toBe(control.element);
+        expect(own.keyframes).toHaveLength(2);
+        expect(own.keyframes[0]).toMatchObject({ overflow: "hidden" });
+        expect(own.keyframes[0]).toHaveProperty("width");
+        expect(own.keyframes[1]).toHaveProperty("backgroundColor");
+        expect(own.options).toEqual({ duration: 300, easing: "cubic-bezier(0.2, 0, 0, 1)" });
+        // The label fades in as the clipped pill widens.
+        expect(labelFade.target.textContent).toBe("Approval needed");
+        expect(calls).toHaveLength(2);
+
+        // Ordinary syncs in the same state leave a running morph alone.
+        control.update(config, true, false, 0, true);
+        expect(calls).toHaveLength(2);
+        expect(calls.every((call) => call.animation.cancel.mock.calls.length === 0)).toBe(true);
+
+        // Back to the arrow: the running morph is replaced, unclipped (the
+        // count badge hangs outside the button).
+        control.update(config, true, false, 2, false);
+        expect(calls.slice(0, 2).every((call) => call.animation.cancel.mock.calls.length === 1)).toBe(true);
+        expect(calls).toHaveLength(3);
+        expect(calls[2].keyframes[0]).not.toHaveProperty("overflow");
+        control.destroy();
+      } finally { restore(); }
+    });
+
+    it("swaps instantly when the theme turns motion off, and falls back when the duration is missing", () => {
+      const { calls, restore } = stubAnimate();
+      try {
+        const config: AgentWidgetConfig = { future: { v5Defaults: true } };
+        const off = createScrollToBottomControl(icon, "transcript");
+        off.element.style.setProperty("--persona-motion-duration-base", "0ms");
+        off.update(config, true);
+        off.update(config, true, false, 0, true);
+        expect(calls).toHaveLength(0);
+        expect(off.element.hasAttribute("data-persona-scroll-to-bottom-approval")).toBe(true);
+        off.destroy();
+
+        const unset = createScrollToBottomControl(icon, "transcript");
+        unset.update(config, true);
+        unset.update(config, true, false, 0, true);
+        expect(calls[0].options.duration).toBe(200);
+        unset.destroy();
+      } finally { restore(); }
+    });
+
+    it("does not morph a control that appears, hides, or prefers reduced motion", () => {
+      const { calls, restore } = stubAnimate();
+      try {
+        const config: AgentWidgetConfig = { future: { v5Defaults: true } };
+        const control = createScrollToBottomControl(icon, "transcript");
+        control.update(config, false);
+        control.update(config, true, false, 0, true); // appears already as the pill
+        control.update(config, false, false, 0, true); // hides
+        expect(calls).toHaveLength(0);
+        control.destroy();
+
+        vi.stubGlobal("matchMedia", () => ({ matches: true, addEventListener: vi.fn(), removeEventListener: vi.fn() }));
+        const reduced = createScrollToBottomControl(icon, "transcript");
+        reduced.update(config, true);
+        reduced.update(config, true, false, 0, true);
+        expect(calls).toHaveLength(0);
+        expect(reduced.element.hasAttribute("data-persona-scroll-to-bottom-approval")).toBe(true);
+        reduced.destroy();
+      } finally { restore(); }
+    });
+  });
+
   it("provides live reduced-motion changes and releases its media listener", () => {
     let change: (() => void) | undefined;
     const media = { matches: true, addEventListener: vi.fn((_event, callback) => { change = callback; }), removeEventListener: vi.fn() };

package/src/components/scroll-to-bottom.ts

@@ -25,9 +25,7 @@ export function createScrollToBottomControl(
   const label = createElement("span", "");
   const badge = createElement("span", "");
   badge.setAttribute("data-persona-scroll-to-bottom-count", "");
-  element.appendChild(glyph);
-  element.appendChild(label);
-  element.appendChild(badge);
+  element.append(glyph, label, badge);
   let config: AgentWidgetConfig = {};
   let state: AgentWidgetScrollToBottomIconState = { activity: "idle", visible: false, hovered: false, focused: false, reducedMotion: false };
   // Keep renderer identity separate from its handle, including null fallbacks.
@@ -36,6 +34,26 @@ export function createScrollToBottomControl(
   let abort: AbortController | undefined;
   let builtin = "";
   const media = typeof matchMedia === "function" ? matchMedia("(prefers-reduced-motion: reduce)") : undefined;
+  // Arrow <-> "Approval needed" pill: one button changing shape, so morph its
+  // width and colors on the theme's motion tokens while the new label fades in.
+  let morphs: Animation[] = [];
+  const paint = () => {
+    const style = getComputedStyle(element);
+    return { width: `${element.offsetWidth}px`, backgroundColor: style.backgroundColor, borderColor: style.borderColor, color: style.color };
+  };
+  const morph = (from: Keyframe) => {
+    const style = getComputedStyle(element);
+    const value = style.getPropertyValue("--persona-motion-duration-base");
+    const ms = parseFloat(value) * (value.includes("ms") ? 1 : 1000);
+    // "0ms" turns motion off; only a missing or invalid value falls back.
+    if (ms === 0) return;
+    const timing = { duration: ms > 0 ? ms : 200, easing: style.getPropertyValue("--persona-motion-easing").trim() || "ease-out" };
+    // Clip only while widening into the pill: the arrow's count badge hangs
+    // outside the button.
+    const clip = label.style.display === "none" ? null : { overflow: "hidden" };
+    morphs = [element.animate([{ ...from, ...clip }, { ...paint(), ...clip }], timing)];
+    if (clip) morphs.push(label.animate([{ opacity: 0 }, { opacity: 1 }], timing));
+  };
   state.reducedMotion = media?.matches ?? false;
   const warn = (error: unknown) => console.warn("Persona scroll icon failed", error);
   const context = (): AgentWidgetScrollToBottomIconContext => ({ config, state: { ...state }, view, signal: abort!.signal });
@@ -51,7 +69,9 @@ export function createScrollToBottomControl(
     if (handle?.element) return;
     const feature = config.features?.scrollToBottom;
     const dots = state.activity === "generating-below" && (feature?.streamingIndicator ?? (config.future?.v5Defaults ? "dots" : "arrow")) === "dots";
-    const key = dots ? "dots" : `arrow:${feature?.iconName ?? "arrow-down"}`;
+    // Same glyph as the approval card it points at, so the two read as one thing.
+    const iconName = state.activity === "approval-below" ? "shield-check" : feature?.iconName ?? "arrow-down";
+    const key = dots ? "dots" : `arrow:${iconName}`;
     if (builtin === key) return;
     builtin = key;
     glyph.innerHTML = "";
@@ -64,7 +84,7 @@ export function createScrollToBottomControl(
       }
       glyph.appendChild(dotGroup);
     } else {
-      const icon = renderIcon(feature?.iconName ?? "arrow-down", "14px", "currentColor", 2);
+      const icon = renderIcon(iconName, "14px", "currentColor", 2);
       if (icon) glyph.appendChild(icon);
     }
   };
@@ -106,11 +126,12 @@ export function createScrollToBottomControl(
 
   return {
     element,
-    update(nextConfig: AgentWidgetConfig, visible: boolean, active = false, count = 0) {
+    /** `approval` marks a pending approval below the fold: the control names it. */
+    update(nextConfig: AgentWidgetConfig, visible: boolean, active = false, count = 0, approval = false) {
       const previous = config.features?.scrollToBottom;
       const next = nextConfig.features?.scrollToBottom;
       const configChanged = config.future?.v5Defaults !== nextConfig.future?.v5Defaults ||
-        (["enabled", "iconName", "label", "streamingIndicator", "transition", "scrollBehavior", "scrollDurationMs"] as (keyof AgentWidgetScrollToBottomFeature)[])
+        (["enabled", "iconName", "label", "approvalLabel", "streamingIndicator", "transition", "scrollBehavior", "scrollDurationMs"] as (keyof AgentWidgetScrollToBottomFeature)[])
           .some((key) => previous?.[key] !== next?.[key]);
       config = nextConfig;
       const feature = config.features?.scrollToBottom;
@@ -132,21 +153,37 @@ export function createScrollToBottomControl(
           focusTarget.focus({ preventScroll: true });
         }
       }
-      const text = feature?.label ?? "";
-      const base = text || "Jump to latest";
-      element.setAttribute("aria-label", `${base}${count > 0 ? ` (${count} new)` : ""}${active && visible ? " (response streaming below)" : ""}`);
+      // A waiting approval outranks streaming and the unread count: the turn is
+      // blocked on the reader, so the control says so in words.
+      const waiting = approval && visible;
+      // Morph only a visible control changing shape, never its fade in or out.
+      const reshape = state.visible && visible && (state.activity === "approval-below") !== waiting;
+      if (reshape || !visible) morphs.forEach((animation) => animation.cancel());
+      const from = reshape && !state.reducedMotion && typeof element.animate === "function" ? paint() : null;
+      const approvalText = feature?.approvalLabel ?? "Approval needed";
+      const text = waiting && approvalText ? approvalText : feature?.label ?? "";
+      const base = feature?.label || "Jump to latest";
+      element.setAttribute("aria-label", waiting
+        ? `${approvalText || "Approval needed"} below. ${base}`
+        : `${base}${count > 0 ? ` (${count} new)` : ""}${active && visible ? " (response streaming below)" : ""}`);
       element.title = text;
       element.setAttribute("data-persona-scroll-to-bottom-has-label", String(Boolean(text)));
+      if (waiting) element.setAttribute("data-persona-scroll-to-bottom-approval", "");
+      else element.removeAttribute("data-persona-scroll-to-bottom-approval");
       label.textContent = text;
       label.style.display = text ? "" : "none";
-      badge.textContent = count > 0 ? String(count) : "";
-      badge.style.display = count > 0 ? "" : "none";
-      const nextState = { ...state, visible, hovered: visible && state.hovered, focused: visible && state.focused, activity: active && visible ? "generating-below" as const : "idle" as const };
+      const shownCount = waiting ? 0 : count;
+      badge.textContent = shownCount > 0 ? String(shownCount) : "";
+      badge.style.display = shownCount > 0 ? "" : "none";
+      const activity = waiting ? "approval-below" as const : active && visible ? "generating-below" as const : "idle" as const;
+      const nextState = { ...state, visible, hovered: visible && state.hovered, focused: visible && state.focused, activity };
       const changed = configChanged || stateChanged(nextState);
       state = nextState;
       updateRenderer(changed);
+      if (from) morph(from);
     },
     destroy() {
+      morphs.forEach((animation) => animation.cancel());
       dispose();
       lifetime.abort();
       media?.removeEventListener?.("change", motion);

package/src/components/user-message-collapse.ts

@@ -0,0 +1,117 @@
+import type { AgentWidgetConfig } from "../types";
+import { createNode } from "../utils/dom";
+
+/**
+ * Long user message collapse ("Show more" / "Show less").
+ *
+ * The default user bubble wraps its content (attachments, mention chips and
+ * text) in a clip region. ui.ts measures the region's real rendered height
+ * after each morph and decides whether it overflows; the bubble is then
+ * re-rendered from that state, so morphs and cached wrappers always agree
+ * with the live DOM. The full text stays in the DOM in every state (no nested
+ * scroller), so find-in-page, selection, copy and screen readers still reach it.
+ */
+
+/**
+ * Default collapsed height. A bubble line is ~22–24px (0.875rem at
+ * leading-relaxed/1.75), so 240px shows about ten lines: enough to recognise
+ * the message, while leaving most of a ~640px panel for the reply that
+ * anchor-top streams in beneath it.
+ */
+export const DEFAULT_USER_MESSAGE_COLLAPSE_MAX_HEIGHT = 240;
+
+/**
+ * Content within this many px (about two lines) of the limit stays expanded,
+ * so the toggle never hides just a line or two behind a button of its own size.
+ */
+export const USER_MESSAGE_COLLAPSE_SLACK = 48;
+
+/**
+ * - `fit`: not measured yet, or short enough; no toggle.
+ * - `live`: an interim voice transcript; expanded so the speaker can watch it.
+ * - `settling`: the transcript's first final render, still expanded; the
+ *   post-morph measurement settles it in the same pass, holding the viewport.
+ * - `collapsed` / `expanded`: overflowing, with the toggle.
+ */
+export type UserMessageCollapseState = "fit" | "live" | "settling" | "collapsed" | "expanded";
+
+export type UserMessageCollapseRender = {
+  state: UserMessageCollapseState;
+  maxHeight: number;
+  showMoreLabel: string;
+  showLessLabel: string;
+};
+
+export const USER_COLLAPSE_REGION_ATTR = "data-persona-user-collapse";
+export const USER_COLLAPSE_TOGGLE_ATTR = "data-persona-user-collapse-toggle";
+
+export const isUserMessageCollapseEnabled = (config: AgentWidgetConfig): boolean =>
+  config.features?.userMessageCollapse?.enabled === true;
+
+export const resolveUserMessageCollapseMaxHeight = (config: AgentWidgetConfig): number => {
+  const value = config.features?.userMessageCollapse?.maxHeight;
+  return typeof value === "number" && Number.isFinite(value) && value > 0
+    ? value
+    : DEFAULT_USER_MESSAGE_COLLAPSE_MAX_HEIGHT;
+};
+
+export const resolveUserMessageCollapseLabels = (
+  config: AgentWidgetConfig
+): Pick<UserMessageCollapseRender, "showMoreLabel" | "showLessLabel"> => ({
+  showMoreLabel: config.copy?.showMoreLabel?.trim() || "Show more",
+  showLessLabel: config.copy?.showLessLabel?.trim() || "Show less",
+});
+
+/** Whether a measured natural content height warrants collapsing. */
+export const userMessageOverflows = (naturalHeight: number, maxHeight: number): boolean =>
+  naturalHeight > maxHeight + USER_MESSAGE_COLLAPSE_SLACK;
+
+const regionId = (messageId: string) => `persona-user-collapse-${messageId}`;
+
+export const createUserCollapseRegion = (
+  messageId: string,
+  maxHeight: number
+): HTMLElement => {
+  const region = createNode("div", {
+    className: "persona-user-collapse-region",
+    attrs: { id: regionId(messageId), [USER_COLLAPSE_REGION_ATTR]: "fit" },
+  });
+  region.style.setProperty("--persona-user-collapse-max-height", `${maxHeight}px`);
+  return region;
+};
+
+/**
+ * Apply a state to a region and its sibling toggle. Used both while building a
+ * fresh bubble and to patch the live bubble in place on a toggle or a new
+ * measurement, so the toggle keeps its identity (and focus) across states.
+ */
+export const applyUserCollapseState = (
+  bubble: HTMLElement,
+  region: HTMLElement,
+  messageId: string,
+  render: UserMessageCollapseRender
+): void => {
+  const { state } = render;
+  region.setAttribute(USER_COLLAPSE_REGION_ATTR, state);
+  region.style.setProperty("--persona-user-collapse-max-height", `${render.maxHeight}px`);
+  let toggle = bubble.querySelector<HTMLButtonElement>(`button[${USER_COLLAPSE_TOGGLE_ATTR}]`);
+  if (state !== "collapsed" && state !== "expanded") {
+    toggle?.remove();
+    return;
+  }
+  if (!toggle) {
+    toggle = createNode("button", {
+      className: "persona-user-collapse-toggle",
+      attrs: {
+        type: "button",
+        id: `persona-user-collapse-toggle-${messageId}`,
+        [USER_COLLAPSE_TOGGLE_ATTR]: "",
+        "aria-controls": regionId(messageId),
+      },
+    }) as HTMLButtonElement;
+    region.after(toggle);
+  }
+  const expanded = state === "expanded";
+  toggle.setAttribute("aria-expanded", expanded ? "true" : "false");
+  toggle.textContent = expanded ? render.showLessLabel : render.showMoreLabel;
+};

package/src/defaults.ts

@@ -266,6 +266,9 @@ export const DEFAULTS_V5: Partial<AgentWidgetConfig> = {
   features: {
     artifacts: { enabled: true },
     scrollToBottom: { streamingIndicator: "dots", transition: "fade", scrollBehavior: "smooth" },
+    // Long sent messages (pasted text, voice transcripts) would otherwise fill
+    // the viewport under the anchor-top pin and push the reply out of view.
+    userMessageCollapse: { enabled: true },
     toolCallDisplay: DEFAULT_TOOL_CALL_DISPLAY_V5,
     reasoningDisplay: DEFAULT_REASONING_DISPLAY_V5,
   },
@@ -382,6 +385,8 @@ export function mergeWithDefaults(
       const csa = config.features?.streamAnimation;
       const dau = defaults.features?.askUserQuestion;
       const cau = config.features?.askUserQuestion;
+      const duc = defaults.features?.userMessageCollapse;
+      const cuc = config.features?.userMessageCollapse;
       const dh = defaults.features?.history;
       const ch = config.features?.history;
       const mergedArtifacts =
@@ -459,6 +464,7 @@ export function mergeWithDefaults(
         ...(mergedStreamAnimation !== undefined ? { streamAnimation: mergedStreamAnimation } : {}),
         ...(mergedAskUserQuestion !== undefined ? { askUserQuestion: mergedAskUserQuestion } : {}),
         ...(mergedHistory !== undefined ? { history: mergedHistory } : {}),
+        ...(duc !== undefined || cuc !== undefined ? { userMessageCollapse: { ...duc, ...cuc } } : {}),
       };
     })(),
     suggestionChips: config.suggestionChips ?? defaults.suggestionChips,

package/src/styles/widget.css

@@ -3109,6 +3109,52 @@
   box-shadow: var(--persona-message-user-shadow);
 }
 
+/* Long user message collapse (features.userMessageCollapse). The region clips
+   without becoming a scroller (overflow: clip), so the full text stays in the
+   DOM for find, copy and screen readers with no nested scroll area. The fade
+   is a mask rather than a gradient overlay, so it works on any bubble fill in
+   light and dark schemes; the toggle inherits the bubble's text color. */
+.persona-user-collapse-region[data-persona-user-collapse="collapsed"] {
+  max-height: var(--persona-user-collapse-max-height, 240px);
+  overflow: clip;
+  -webkit-mask-image: linear-gradient(to bottom, #000 calc(100% - var(--persona-user-collapse-fade-height, 48px)), transparent);
+  mask-image: linear-gradient(to bottom, #000 calc(100% - var(--persona-user-collapse-fade-height, 48px)), transparent);
+}
+
+.persona-user-collapse-toggle {
+  display: inline-flex;
+  align-items: center;
+  margin-top: 0.25rem;
+  padding: 0.125rem 0;
+  border: 0;
+  background: none;
+  color: var(--persona-user-collapse-toggle-fg, inherit);
+  font-family: inherit;
+  font-size: var(--persona-user-collapse-toggle-font-size, 0.8125rem);
+  font-weight: var(--persona-user-collapse-toggle-font-weight, 600);
+  line-height: 1.25rem;
+  cursor: pointer;
+  text-decoration: underline;
+  text-decoration-color: transparent;
+  text-underline-offset: 2px;
+  transition: text-decoration-color 150ms ease;
+}
+
+.persona-user-collapse-toggle:hover {
+  text-decoration-color: currentColor;
+}
+
+.persona-user-collapse-toggle:focus-visible {
+  outline: 2px solid currentColor;
+  outline-offset: 2px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .persona-user-collapse-toggle {
+    transition: none;
+  }
+}
+
 [data-persona-root] .persona-tool-bubble.persona-shadow-sm {
   box-shadow: var(--persona-tool-bubble-shadow);
 }
@@ -4869,6 +4915,16 @@
   text-align: center;
 }
 
+/* A pending approval below the fold: the control widens to a labelled pill.
+   Unset approval tokens keep the pill's own colors. */
+[data-persona-root] .persona-scroll-to-bottom-indicator[data-persona-scroll-to-bottom-approval] {
+  border-color: var(--persona-scroll-to-bottom-approval-border, var(--persona-scroll-to-bottom-border, var(--persona-primary, #111827)));
+  background: var(--persona-scroll-to-bottom-approval-bg, var(--persona-scroll-to-bottom-bg, var(--persona-button-primary-bg, var(--persona-accent, #0f0f0f))));
+  color: var(--persona-scroll-to-bottom-approval-fg, var(--persona-scroll-to-bottom-fg, var(--persona-button-primary-fg, var(--persona-text-inverse, #ffffff))));
+  font-weight: var(--persona-scroll-to-bottom-approval-font-weight, 500);
+  white-space: nowrap;
+}
+
 [data-persona-root] .persona-scroll-to-bottom-indicator:hover {
   opacity: 0.92;
 }

package/src/theme-reference.ts

@@ -171,7 +171,7 @@ export const THEME_TOKEN_DOCS = {
       askUserQuestion: 'sheet (background, border, shadow), pill (background, foreground, borderRadius, selectedBackground, selectedForeground), customInput.background. Local features.askUserQuestion.styles still wins; navigation, labels and slide timing remain feature config.',
       attachment: 'image (background, border).',
       scrollToBottom:
-        'Floating scroll-to-bottom affordance shared by transcript and event stream: background, foreground, border, size, borderRadius, shadow, padding, gap, fontSize, iconSize.',
+        'Floating scroll-to-bottom affordance shared by transcript and event stream: background, foreground, border, size, borderRadius, shadow, padding, gap, fontSize, iconSize; approval (background, foreground, border, fontWeight) for the labelled "Approval needed" state, falling back to the control colors.',
       toolBubble: 'shadow, background, borderColor, borderWidth, borderRadius; header (background, foreground, padding), content (background, foreground, padding), codeBlock (background, foreground, borderColor), toggleForeground, labelForeground, loading (primary, secondary, duration). Applies to card and activity-row variants without changing their distinct defaults. CSS duration uses ms/s; legacy numeric milliseconds must convert explicitly. Theme content.padding precedes activity.bodyPadding/toolBubble.bodyPadding fallbacks; explicit legacy axes override only their axis.',
       scrollbar:
         'Shared scrollbar appearance for every scroller: thumb (default semantic.colors.border), track (default transparent).',
@@ -250,7 +250,7 @@ export const THEME_TOKEN_DOCS = {
       description:
         'Shared transcript + event-stream jump-to-latest affordance.',
       properties:
-        'features.scrollToBottom.enabled, features.scrollToBottom.iconName, features.scrollToBottom.label (empty string renders icon-only). Defaults: enabled=true, iconName="arrow-down", label="".',
+        'features.scrollToBottom.enabled, features.scrollToBottom.iconName, features.scrollToBottom.label (empty string renders icon-only), features.scrollToBottom.approvalLabel (shown while a pending approval is below the fold; empty string keeps the regular control). Defaults: enabled=true, iconName="arrow-down", label="", approvalLabel="Approval needed".',
     },
     toolCall: {
       description: