@runtypelabs/persona 4.32.2 → 4.34.0

package/src/components/message-bubble.ts

@@ -2,6 +2,7 @@ import { getLoadingLabelRuntimeSync } from "../loading-label-runtime-loader";
 import { createElement, createNode } from "../utils/dom";
 import {
   AgentWidgetMessage,
+  AgentWidgetMessageRole,
   AgentWidgetMessageLayoutConfig,
   AgentWidgetAvatarConfig,
   AgentWidgetTimestampConfig,
@@ -24,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,
@@ -577,40 +583,47 @@ export const renderLoadingIndicatorWithFallback = (
  */
 const createAvatar = (
   avatarConfig: AgentWidgetAvatarConfig,
-  role: "user" | "assistant"
+  role: AgentWidgetMessageRole
 ): HTMLElement => {
   const avatar = createElement(
     "div",
     "persona-flex-shrink-0 persona-w-8 persona-h-8 persona-rounded-full persona-flex persona-items-center persona-justify-center persona-text-sm"
   );
 
-  const avatarContent = role === "user" 
-    ? avatarConfig.userAvatar 
-    : avatarConfig.assistantAvatar;
+  const isOperator = role === "operator";
+  const avatarContent = role === "user"
+    ? avatarConfig.userAvatar
+    : isOperator
+      ? avatarConfig.operatorAvatar
+      : avatarConfig.assistantAvatar;
+
+  // The operator avatar is a neutral outlined chip, apart from the solid
+  // user and assistant fills.
+  const applyFill = () => {
+    avatar.classList.add(
+      ...(isOperator
+        ? ["persona-bg-persona-container", "persona-text-persona-text", "persona-border"]
+        : [role === "user" ? "persona-bg-persona-accent" : "persona-bg-persona-primary", "persona-text-white"])
+    );
+  };
 
   if (avatarContent) {
     // Check if it's a URL or emoji/text
     if (avatarContent.startsWith("http") || avatarContent.startsWith("/") || avatarContent.startsWith("data:")) {
       const img = createElement("img") as HTMLImageElement;
       img.src = avatarContent;
-      img.alt = role === "user" ? "User" : "Assistant";
+      img.alt = role === "user" ? "User" : isOperator ? "Operator" : "Assistant";
       img.className = "persona-w-full persona-h-full persona-rounded-full persona-object-cover";
       avatar.appendChild(img);
     } else {
       // Emoji or text
       avatar.textContent = avatarContent;
-      avatar.classList.add(
-        role === "user" ? "persona-bg-persona-accent" : "persona-bg-persona-primary",
-        "persona-text-white"
-      );
+      applyFill();
     }
   } else {
     // Default avatar
-    avatar.textContent = role === "user" ? "U" : "A";
-    avatar.classList.add(
-      role === "user" ? "persona-bg-persona-accent" : "persona-bg-persona-primary",
-      "persona-text-white"
-    );
+    avatar.textContent = role === "user" ? "U" : isOperator ? "O" : "A";
+    applyFill();
   }
 
   return avatar;
@@ -644,13 +657,32 @@ const createTimestamp = (
   return timestamp;
 };
 
+/** Assistant color utilities an operator bubble replaces with its own tokens. */
+const OPERATOR_DROPPED_CLASSES = new Set([
+  "persona-bg-persona-container",
+  "persona-text-persona-text",
+  "persona-border-persona-message-border",
+]);
+
 /**
  * Get bubble classes based on layout preset
  */
 export const getBubbleClasses = (
-  role: "user" | "assistant" | "system",
+  role: AgentWidgetMessageRole,
   layout: AgentWidgetMessageLayoutConfig["layout"] = "bubble"
 ): string[] => {
+  // Operator bubbles share the assistant's geometry per layout; only the role
+  // class changes, and the colors come from the operator tokens instead.
+  if (role === "operator") {
+    const classes = getBubbleClasses("assistant", layout).flatMap((name) =>
+      name === "persona-message-assistant-bubble"
+        ? ["persona-message-operator-bubble"]
+        : OPERATOR_DROPPED_CLASSES.has(name) ? [] : [name]
+    );
+    // Flat drops the assistant's fill, not the operator's: the operator keeps
+    // its background, so it needs the minimal layout's side padding.
+    return layout === "flat" ? [...classes, "persona-px-3"] : classes;
+  }
   const baseClasses = ["persona-message-bubble"];
 
   switch (layout) {
@@ -763,7 +795,7 @@ export const applyBubbleGeometry = (
   tokens?: MessageGeometryTokens
 ): void => {
   if (!tokens) return;
-  const key = role === "user" ? "user" : "assistant";
+  const key = role === "user" || role === "operator" ? role : "assistant";
   const preset = BUBBLE_GEOMETRY_DEFAULTS[layout ?? "bubble"] ?? BUBBLE_GEOMETRY_DEFAULTS.bubble;
   if (tokens.padding) {
     bubble.style.padding = `var(--persona-message-${key}-padding, ${preset.padding})`;
@@ -787,13 +819,14 @@ export const customMessageActionDataAction = (id: string): string =>
 
 /**
  * Host-contributed actions this message's role qualifies for. Assistant-only by
- * default, matching every built-in except edit and quote.
+ * default, matching every built-in except edit and quote; an action reaches
+ * operator messages only when its `roles` lists `"operator"`.
  */
 export const customMessageActionsForRole = (
   actionsConfig: AgentWidgetMessageActionsConfig | undefined,
   role: AgentWidgetMessage["role"]
 ): AgentWidgetCustomMessageAction[] => {
-  if (role !== "user" && role !== "assistant") return [];
+  if (role !== "user" && role !== "assistant" && role !== "operator") return [];
   return (actionsConfig?.custom ?? []).filter((action) =>
     (action.roles ?? ["assistant"]).includes(role)
   );
@@ -970,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;
 };
 
 /**
@@ -1000,21 +1038,33 @@ export const createStandardBubble = (
   bubble.id = `bubble-${message.id}`;
   bubble.setAttribute("data-message-id", message.id);
 
-  bubble.setAttribute("data-persona-theme-zone", message.role === "user" ? "user-message" : "assistant-message");
+  const isOperator = message.role === "operator";
+  // The V5 operator is outlined, not filled, so every layout needs the border
+  // style that only the bubble layout's classes carry.
+  if (isOperator && options?.widgetConfig?.future?.v5Defaults === true) bubble.classList.add("persona-border");
+  bubble.setAttribute(
+    "data-persona-theme-zone",
+    message.role === "user" ? "user-message" : isOperator ? "operator-message" : "assistant-message"
+  );
 
   const defaultMessageTokens = resolveThemeDefaults(options?.widgetConfig?.future).components.message;
   const messageTokens = options?.widgetConfig?.theme?.components?.message;
+  const darkMessageTokens = options?.widgetConfig?.darkTheme?.components?.message;
   applyBubbleGeometry(
     bubble,
     message.role,
     layout,
     message.role === "user"
-      ? { ...defaultMessageTokens.user, ...messageTokens?.user, ...options?.widgetConfig?.darkTheme?.components?.message?.user }
-      : { ...defaultMessageTokens.assistant, ...messageTokens?.assistant, ...options?.widgetConfig?.darkTheme?.components?.message?.assistant }
+      ? { ...defaultMessageTokens.user, ...messageTokens?.user, ...darkMessageTokens?.user }
+      : isOperator
+        ? { ...defaultMessageTokens.operator, ...messageTokens?.operator, ...darkMessageTokens?.operator }
+        : { ...defaultMessageTokens.assistant, ...messageTokens?.assistant, ...darkMessageTokens?.assistant }
   );
 
-  // Apply component-level color overrides via CSS variables
-  if (layout === "flat") {
+  // Apply component-level color overrides via CSS variables. Flat clears the
+  // user and assistant fills; an operator keeps its own background token so it
+  // stays apart from the assistant prose on the same side.
+  if (layout === "flat" && !isOperator) {
     bubble.style.backgroundColor = "transparent";
     bubble.style.color =
       message.role === "user"
@@ -1026,6 +1076,23 @@ export const createStandardBubble = (
   } else if (message.role === "assistant") {
     bubble.style.backgroundColor = 'var(--persona-message-assistant-bg, var(--persona-container))';
     bubble.style.color = 'var(--persona-message-assistant-text, var(--persona-text))';
+  } else if (isOperator) {
+    bubble.style.backgroundColor = 'var(--persona-components-message-operator-background, var(--persona-container))';
+    bubble.style.color = 'var(--persona-components-message-operator-text, var(--persona-text))';
+  }
+
+  if (isOperator) {
+    const authorLabel = createElement("div", "persona-message-author persona-text-xs persona-font-medium persona-mb-1");
+    const configuredLabel = options?.widgetConfig?.copy?.operatorLabel;
+    const operatorLabel = typeof configuredLabel === "string" && configuredLabel.trim()
+      ? configuredLabel.trim() : "Human operator";
+    const displayName = typeof message.author?.displayName === "string"
+      ? message.author.displayName.trim() : "";
+    authorLabel.textContent = displayName ? `${displayName} · ${operatorLabel}` : operatorLabel;
+    // A visible name is also the accessible name for the human-authored group.
+    bubble.setAttribute("role", "group");
+    bubble.setAttribute("aria-label", authorLabel.textContent);
+    bubble.appendChild(authorLabel);
   }
 
   const imageParts = getMessageImageParts(message);
@@ -1181,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,
@@ -1193,7 +1266,7 @@ export const createStandardBubble = (
     );
 
     if (imagePreviews) {
-      bubble.appendChild(imagePreviews);
+      contentParent.appendChild(imagePreviews);
     } else if (shouldHideTextUntilPreviewFails && textContentDiv) {
       textContentDiv.style.display = "";
     }
@@ -1203,7 +1276,7 @@ export const createStandardBubble = (
   if (audioParts.length > 0) {
     const audioPreviews = createMessageAudioPreviews(audioParts);
     if (audioPreviews) {
-      bubble.appendChild(audioPreviews);
+      contentParent.appendChild(audioPreviews);
     }
   }
 
@@ -1211,7 +1284,7 @@ export const createStandardBubble = (
   if (videoParts.length > 0) {
     const videoPreviews = createMessageVideoPreviews(videoParts);
     if (videoPreviews) {
-      bubble.appendChild(videoPreviews);
+      contentParent.appendChild(videoPreviews);
     }
   }
 
@@ -1219,7 +1292,7 @@ export const createStandardBubble = (
   if (fileParts.length > 0) {
     const filePreviews = createMessageFilePreviews(fileParts);
     if (filePreviews) {
-      bubble.appendChild(filePreviews);
+      contentParent.appendChild(filePreviews);
     }
   }
 
@@ -1229,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) {
@@ -1293,14 +1370,15 @@ export const createStandardBubble = (
     bubble.appendChild(createStopReasonNotice(message.stopReason, stopReasonNoticeText));
   }
 
-  // Add message actions for assistant messages (only when not streaming and has content)
+  // Add message actions for assistant and operator messages (only when not
+  // streaming and has content). Operator rows get copy and opted-in custom
+  // actions only: feedback, read-aloud and regenerate are about model output.
   const shouldShowActions =
-    message.role === "assistant" &&
+    (message.role === "assistant" || isOperator) &&
     !message.streaming &&
     // A voice caption (the voice model's own speech) is display-only.
     !message.voiceCaption &&
-    message.content &&
-    message.content.trim() &&
+    (messageContentText.length > 0 || (isOperator && customMessageActionsForRole(actionsConfig, "operator").length > 0)) &&
     actionsConfig?.enabled !== false;
 
   // User bubbles carry actions only when this message is edit- or quote-eligible;
@@ -1321,7 +1399,18 @@ export const createStandardBubble = (
       shouldShowUserActions
         ? // A user bubble never hosts the assistant-only controls.
           { ...actionsConfig, showCopy: false, showUpvote: false, showDownvote: false, showReadAloud: false }
-        : actionsConfig,
+        : isOperator
+          ? {
+              ...actionsConfig,
+              showCopy: messageContentText.length > 0 && actionsConfig.showCopy !== false,
+              showUpvote: false,
+              showDownvote: false,
+              showReadAloud: false,
+              showRegenerate: false,
+              showEdit: false,
+              showQuote: false,
+            }
+          : actionsConfig,
       actionCallbacks,
       eligibility,
       options?.widgetConfig?.future?.v5Defaults === true && actionsConfig.visibility === undefined

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);