@runtypelabs/persona 4.23.1 → 4.24.0

package/src/types.ts

@@ -593,10 +593,34 @@ export type AgentWidgetContextMentionTokenRenderContext = {
   readonly: boolean;
 };
 
+/** One earlier client-tool call replayed to the model, in `/v1/dispatch` shape. */
+export type AgentWidgetReplayedToolCall = {
+  toolCallId: string;
+  /** Model-facing (sanitized) name, e.g. `webmcp_search`. */
+  toolName: string;
+  args: Record<string, unknown>;
+};
+
+/** The browser's answer to an {@link AgentWidgetReplayedToolCall}. */
+export type AgentWidgetReplayedToolResult = {
+  toolCallId: string;
+  toolName: string;
+  result: unknown;
+};
+
+/**
+ * A message in the proxy/agent request payload. Earlier client-tool calls the
+ * browser answered replay as an assistant message carrying `toolCalls`,
+ * followed by a `tool` message carrying the matching `toolResults`; both have
+ * empty `content`. Client-token mode never sends them: the server replays
+ * from its own stored transcript there.
+ */
 export type AgentWidgetRequestPayloadMessage = {
-  role: AgentWidgetMessageRole;
+  role: AgentWidgetMessageRole | "tool";
   content: MessageContent;
   createdAt: string;
+  toolCalls?: AgentWidgetReplayedToolCall[];
+  toolResults?: AgentWidgetReplayedToolResult[];
 };
 
 export type AgentWidgetRequestPayload = {
@@ -1032,6 +1056,24 @@ export type AgentMessageMetadata = {
    * never re-resume the call.
    */
   suggestRepliesResolved?: boolean;
+  /**
+   * The client-tool answer the server accepted through `/resume`, kept so
+   * later proxy/agent turns can replay the call and its result to the model.
+   * `toolName` is the widget's internal name (`webmcp:<name>` or a bare
+   * built-in). Set only after the resume succeeds; preserved across
+   * re-emissions of the tool message.
+   */
+  clientToolAnswer?: {
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+    result: unknown;
+    /**
+     * Shared by the answers posted in one `/resume`, i.e. one assistant
+     * turn's parallel calls; a chained call gets a new batch.
+     */
+    batch?: string;
+  };
 };
 
 export type AgentWidgetRequestMiddlewareContext = {
@@ -2212,6 +2254,14 @@ export type AgentWidgetToolCallLoadingAnimation =
   | "rainbow";
 
 export type AgentWidgetToolCallDisplayFeature = {
+  /** Activity chrome. Defaults to card in V4 and row with future.v5Defaults. */
+  variant?: "card" | "row";
+  /** Row status icons: always, active/attention-needed only, or never. V5 defaults to active; V4 to always. */
+  iconVisibility?: "always" | "active" | "never";
+  /** Row variant: open when the first content chunk arrives. Default false in V5; true in V4. */
+  autoExpand?: boolean;
+  /** Row variant: collapse once after completion, in ms; false disables. Default 1000. */
+  autoCollapseDelay?: number | false;
   /**
    * Controls what collapsed tool call rows show in their header/summary area.
    * @default "tool-call"
@@ -2242,9 +2292,10 @@ export type AgentWidgetToolCallDisplayFeature = {
    * Controls how a grouped tool sequence is rendered.
    * - `"stack"`: show the group summary and each child tool row.
    * - `"summary"`: show one consolidated summary row only.
+   * - `"collapsible"`: expandable activity group (V5 default).
    * @default "stack"
    */
-  groupedMode?: "stack" | "summary";
+  groupedMode?: "stack" | "summary" | "collapsible";
   /**
    * What happens to a tool call row once it completes.
    *
@@ -2277,6 +2328,14 @@ export type AgentWidgetToolCallDisplayFeature = {
 export type AgentWidgetToolCallCompletedVisibility = "kept" | "removed";
 
 export type AgentWidgetReasoningDisplayFeature = {
+  /** Activity chrome. Defaults to card in V4 and row with future.v5Defaults. */
+  variant?: "card" | "row";
+  /** Row status icons: always, active/attention-needed only, or never. V5 defaults to active; V4 to always. */
+  iconVisibility?: "always" | "active" | "never";
+  /** Row variant: open when the first content chunk arrives. Default false in V5; true in V4. */
+  autoExpand?: boolean;
+  /** Row variant: collapse once after completion, in ms; false disables. Default 1000. */
+  autoCollapseDelay?: number | false;
   /**
    * When true, active collapsed reasoning rows can render a lightweight preview block.
    * @default false
@@ -3036,8 +3095,8 @@ export interface AgentWidgetHistoryFeature {
    * otherwise `"browser"`) and narrows it to what the provider advertises, so a
    * browser-only provider is never asked for a scope it cannot serve. An
    * explicit `features.history.scope` is a hard request and still fails closed
-   * with `unsupported_scope`. `getIdentityProof` is never called for a supplied
-   * provider, and `HistoryOperationContext` carries only the resolved scope;
+   * with `unsupported_scope`. History operations on a supplied provider never
+   * call `getIdentityProof`, and `HistoryOperationContext` carries only the resolved scope;
    * report your own identity through `getIdentityStatus()` /
    * `subscribeIdentityStatus()`, which is what the scope banner and its retry
    * affordance read.
@@ -3441,7 +3500,7 @@ export type EventStreamConfig = {
   /**
    * Fields to extract from event payloads for description text.
    * The first matching field value is displayed after the badge.
-   * @default ["flowName", "stepName", "name", "tool", "toolName"]
+   * @default ["flowName", "stepName", "reasoningText", "text", "name", "tool", "toolName"]
    */
   descriptionFields?: string[];
   /**
@@ -3660,6 +3719,8 @@ export type AgentWidgetComposerBarPeekConfig = {
 };
 
 export type AgentWidgetLauncherConfig = {
+  /** Collapsed launcher shape. V4 defaults to pill; V5 defaults to circle. */
+  variant?: "pill" | "circle";
   enabled?: boolean;
   title?: string;
   subtitle?: string;
@@ -4454,9 +4515,9 @@ export type AgentWidgetComposerConfig = {
   /**
    * Where the composer footer sits relative to the transcript.
    *
-   * - `"block"` (default): the footer is a flex sibling below the scroll body.
+   * - `"block"` (V4 default): the footer is a flex sibling below the scroll body.
    *   Nothing scrolls behind it.
-   * - `"overlay"`: the footer is absolutely overlaid on the scroll body, so the
+   * - `"overlay"` (V5 default): the footer is absolutely overlaid on the scroll body, so the
    *   transcript scrolls behind it (the chatgpt.com / claude.ai model, where the
    *   composer is sticky inside the scroller). The widget reserves the footer's
    *   live height as bottom padding on the scroll body and on a plugin welcome
@@ -4468,7 +4529,7 @@ export type AgentWidgetComposerConfig = {
    * included) and `theme.components.input.backdropFilter`.
    *
    * Ignored in composer-bar mount mode, which owns its own geometry.
-   * @default "block"
+   * @default "block" (V4), "overlay" (V5)
    */
   placement?: ComposerPlacement;
   /**
@@ -4482,8 +4543,9 @@ export type AgentWidgetComposerConfig = {
    *
    * `"single-row"` describes the IDLE composer only. It composes with the
    * compact state, so a wrapped draft, chips, attachment previews, a quote, a
-   * pending card, or live dictation all fall back to the stacked card, exactly
-   * as `data-persona-composer-compact` does today.
+   * pending card all fall back to the stacked card, exactly
+   * as `data-persona-composer-compact` does today. Recording alone does not
+   * expand the composer; dictated text expands it when it wraps.
    *
    * Ignored in composer-bar mount mode, whose pill is already one row.
    * @default "stacked"
@@ -4530,7 +4592,14 @@ export type AgentWidgetClearChatConfig = {
 };
 
 export type AgentWidgetStatusIndicatorConfig = {
+  /** Show the indicator. Explicit false also hides transient connection states. */
   visible?: boolean;
+  /**
+   * "always" shows status beneath the composer; "transient" shows connecting,
+   * reconnecting, and error status above it, hiding normal idle/streaming status.
+   * Available in both defaults states. Default: "always" in v4, "transient" in v5.
+   */
+  mode?: "always" | "transient";
   /** Text alignment. Default: 'right'. */
   align?: 'left' | 'center' | 'right';
   idleText?: string;
@@ -5401,7 +5470,8 @@ export type AgentWidgetResolvedSuggestion = {
 
 /** Presentation keys shared by every suggestion surface. */
 export type AgentWidgetSuggestionSurfaceConfig = {
-  /** Item density. Defaults to `card` for starters and `chip` for follow-ups. */
+  /** Item density. V4 starters: card. V5 starters: chip, or card in fullscreen.
+   * Follow-ups default to chip. */
   variant?: AgentWidgetSuggestionVariant;
   /** Default click behavior, overridable per item. Defaults to `send`. */
   behavior?: AgentWidgetSuggestionBehavior;
@@ -5412,7 +5482,7 @@ export type AgentWidgetSuggestionSurfaceConfig = {
    * own stacking.
    */
   overflow?: "scroll" | "wrap";
-  /** Maximum visible items. Defaults to 4. */
+  /** Maximum visible items. Defaults to 4, or 3 for V5 non-fullscreen starters. */
   maxItems?: number;
 };
 
@@ -5476,8 +5546,8 @@ export type AgentWidgetWelcomeVariant = "card" | "hero" | "none";
 
 /**
  * When the welcome surface goes away. `"never"` is the default for `"card"`;
- * `"on-first-message"` is the default for `"hero"` and cannot be overridden
- * there.
+ * `"on-first-message"` is forced for legacy V4 `"hero"`. V5 defaults every
+ * variant to `"on-first-message"`. Explicit layout opts into overridable dismissal.
  */
 export type AgentWidgetWelcomeDismiss = "never" | "on-first-message";
 
@@ -5529,7 +5599,10 @@ export type AgentWidgetWelcomeAlign = "start" | "center";
  * host-set value from a filled-in default.
  */
 export interface AgentWidgetWelcomeConfig {
-  /** Card or hero title. Defaults to "Hello 👋". */
+  /** Vertical placement: V4 defaults to top; V5 to centered. Fullscreen centered
+   * welcomes also raise the empty composer unless `anchor` is explicitly set. */
+  layout?: "top" | "centered";
+  /** Card or hero title. V4: "Hello 👋". V5: "What can I help with?". */
   title?: string;
   /**
    * Small muted line above the title, e.g. a section name. Omitted when unset
@@ -5542,19 +5615,22 @@ export interface AgentWidgetWelcomeConfig {
   icon?: AgentWidgetWelcomeIcon;
   /**
    * Horizontal alignment of the kicker, title, subtitle, and starter
-   * suggestions. Unset follows the variant: `card` starts, `hero` centers.
+   * suggestions. Centered layouts default to center. Otherwise unset follows
+   * the variant: `card` starts, `hero` centers.
    */
   align?: AgentWidgetWelcomeAlign;
   /** @default "card" */
   variant?: AgentWidgetWelcomeVariant;
-  /** @default "never" for `card`, always `"on-first-message"` for `hero`. */
+  /** V4: never for card, forced on-first-message for hero. V5: on-first-message
+   * for all variants; explicit values win. Explicit layout also allows overriding
+   * the legacy hero dismissal in V4. */
   dismiss?: AgentWidgetWelcomeDismiss;
   /**
    * Vertical anchoring of the greeting-plus-composer pair in the EMPTY
    * conversation only. On the first message the pair drops to the bottom
    * (animated; see `data-persona-conversation-state`).
    *
-   * - `"bottom"` (default): the composer stays pinned at the bottom.
+   * - `"bottom"`: the composer stays pinned at the bottom.
    * - `"center"`: greeting and composer float together so the composer's top
    *   edge lands at `anchorComposerTop` of the panel column, and the welcome
    *   surface is end-anchored `composerGap` above it.
@@ -5562,7 +5638,8 @@ export interface AgentWidgetWelcomeConfig {
    * Composes with either `composer.placement`. Ignored in composer-bar mount
    * mode. `renderWelcome` plugin content inherits the anchor: the widget
    * positions the overlay host and reserves the composer zone.
-   * @default "bottom"
+   * Defaults to bottom, except centered fullscreen layouts, which center the
+   * measured greeting/composer group when no anchor override is supplied.
    */
   anchor?: AgentWidgetWelcomeAnchor;
   /**
@@ -5899,6 +5976,8 @@ export interface WidgetHistoryInternals {
  */
 export type ClientChatRequest = {
   sessionId: string;
+  /** Fresh identity proof for this execution, independent of visitor history. */
+  identityProof?: RuntypeClientChatRequest['identityProof'];
   messages: Array<{
     id?: string;
     role: 'user' | 'assistant' | 'system';
@@ -6281,6 +6360,9 @@ export type AgentWidgetLayoutConfig = {
    * `launcher.composerBar.contentMaxWidth`)
    */
   contentMaxWidth?: string;
+  /** Fade the transcript's top edge when content is scrolled above it.
+   * Defaults to false in V4 and true with future.v5Defaults. */
+  topFade?: boolean;
 };
 
 // ============================================================================
@@ -6909,7 +6991,32 @@ export type AgentWidgetLoadingIndicatorConfig = {
   renderIdle?: (context: IdleIndicatorRenderContext) => HTMLElement | null;
 };
 
+/** Built-in `sessionInit` triggers. See {@link AgentWidgetConfig.sessionInit}. */
+export type AgentWidgetSessionInitTrigger = 'input' | 'focus' | 'mount' | 'send';
+
+/**
+ * Custom `sessionInit` trigger. Runs when the widget mounts in client token mode,
+ * and again if `update()` swaps in a different function. Call `warm()` whenever
+ * the visitor shows intent (it is safe to call repeatedly). Return a cleanup to
+ * run when the widget is destroyed or the hook is replaced.
+ */
+export type AgentWidgetSessionInitHook = (context: {
+  /** Fire-and-forget early session init; latched and error-swallowing. */
+  warm: () => void;
+  /** The widget's mount element. */
+  mount: HTMLElement;
+}) => void | (() => void);
+
 export type AgentWidgetConfig = {
+  /** Opt in to upcoming major-version defaults without changing explicit settings. */
+  future?: {
+    /**
+     * Use the v5 default styling as it rolls out in 4.x. Every affected setting
+     * remains independently configurable. Explicit options and theme tokens win.
+     * @default false
+     */
+    v5Defaults?: boolean;
+  };
   apiUrl?: string;
   flowId?: string;
   /**
@@ -7064,6 +7171,46 @@ export type AgentWidgetConfig = {
    * ```
    */
   onSessionExpired?: () => void;
+  /**
+   * When the widget calls `/v1/client/init` in client token mode, ahead of the
+   * first send. Ignored outside client token mode.
+   *
+   * - `'input'` (default): on the composer's first user keystroke that leaves
+   *   non-empty text. Programmatic value changes (restored drafts,
+   *   `setMessage()`, history recall) do not count.
+   * - `'focus'`: when the visitor focuses the composer by pointer or Tab (and
+   *   on first input, as a fallback). Programmatic focus, such as
+   *   `autoFocusInput` on open or mount, does not count.
+   * - `'mount'`: as soon as the widget mounts (the behavior before this option
+   *   existed). Use it when a server-configured welcome message, which arrives
+   *   with the init response, must show before the visitor types.
+   * - `'send'`: no early init; the first send initializes the session.
+   * - A function: custom trigger. Called on mount (and when `update()` swaps
+   *   in a different function) with a `warm` callback to call whenever you
+   *   decide (e.g. on hover); may return a cleanup that runs on destroy or
+   *   replacement. Replaces the built-in triggers.
+   *
+   * The early init is fire-and-forget: it runs at most once per session
+   * lifetime (re-armed after expiry or a new conversation), sends exactly the
+   * same request the send would, and swallows errors. A failure resurfaces
+   * when the send retries init. A send during an in-flight early init reuses
+   * it, so only one `/v1/client/init` is issued. When visitor history is
+   * enabled the widget still initializes on mount to restore the conversation.
+   * Hosts can also trigger it imperatively with `controller.warmSession()`.
+   *
+   * @default 'input'
+   *
+   * @example
+   * ```typescript
+   * config: {
+   *   clientToken: 'ct_live_...',
+   *   sessionInit: ({ warm, mount }) => {
+   *     mount.addEventListener('pointerenter', warm, { once: true });
+   *   }
+   * }
+   * ```
+   */
+  sessionInit?: AgentWidgetSessionInitTrigger | AgentWidgetSessionInitHook;
   /**
    * Get stored session ID for session resumption (client token mode only).
    * Called when initializing a new session to check if there's a previous session_id
@@ -7096,13 +7243,20 @@ export type AgentWidgetConfig = {
    */
   setStoredSessionId?: (sessionId: string) => void;
   /**
-   * Called immediately before any cross-device history request and before a
+   * With identityProvider, called before every client-token chat POST, including retries, independently of history.
+   * Also called immediately before any cross-device history request and before a
    * conversationId resume of a conversation discovered on another device.
-   * Return a fresh end-user access token (rt_eu_… / JWT). Null uses exact-browser
-   * scope only for a never-bound visitor; a previously bound visitor fails closed
-   * until resetHistoryIdentity() runs. Never cached by the widget.
+   * Return a fresh end-user access token (rt_eu_… / JWT). Null stops identity-enabled chat.
+   * For history only, null uses exact-browser scope for a never-bound visitor;
+   * a bound visitor fails closed until resetHistoryIdentity(). Never cached.
    */
   getIdentityProof?: () => string | null | Promise<string | null>;
+  /**
+   * Provider name registered with Runtype, for example "clerk". Enables per-request
+   * chat identity through getIdentityProof without enabling history. A missing or
+   * failed proof stops the turn; omitting this preserves history-only callbacks.
+   */
+  identityProvider?: string;
   /**
    * Read the persisted active conversation id (client token mode only).
    * Called only after the internal stored-state bootstrap gate resolves.
@@ -7798,6 +7952,8 @@ export type AgentWidgetReasoning = {
 };
 
 export type AgentWidgetToolCall = {
+  /** Optional approval state for activity-row status chrome. */
+  approvalStatus?: "pending" | "approved" | "denied" | "timeout";
   id: string;
   name?: string;
   status: "pending" | "running" | "complete";

package/src/ui.activity-row.test.ts

@@ -0,0 +1,91 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createAgentExperience, type AgentWidgetController } from './ui';
+import type { AgentWidgetConfig, AgentWidgetMessage } from './types';
+let controller: AgentWidgetController;
+let mount: HTMLElement;
+beforeEach(() => { window.localStorage.clear(); window.scrollTo = vi.fn(); mount = document.createElement('div'); document.body.appendChild(mount); });
+afterEach(() => { controller?.destroy(); document.body.replaceChildren(); vi.useRealTimers(); });
+const inject = (id: string, status: 'running' | 'complete', chunks: string[] = []) => controller.injectTestMessage({ type: 'message', message: { id, role: 'assistant', content: '', createdAt: '2026-01-01T00:00:00Z', sequence: Number(id.slice(-1)), variant: 'tool', toolCall: { id, name: 'Search', status, chunks } } });
+const header = (id: string) => mount.querySelector<HTMLButtonElement>(`[data-message-id="${id}"] > button`)!;
+const start = (v5Defaults: boolean, toolCallDisplay: NonNullable<AgentWidgetConfig['features']>['toolCallDisplay']) => { controller = createAgentExperience(mount, { future: { v5Defaults }, apiUrl: '/test', persistState: false, launcher: { enabled: false }, features: { toolCallDisplay } }); };
+describe.each([false, true])('activity UI (V5 %s)', v5Defaults => {
+  it('uses version defaults for streaming tool and reasoning disclosure', () => {
+    start(v5Defaults, { variant: 'row', grouped: false });
+    inject('tool1', 'running', ['one']);
+    expect(header('tool1').getAttribute('aria-expanded')).toBe(String(!v5Defaults));
+    if (v5Defaults) {
+      inject('tool1', 'running', ['one', 'two']);
+      expect(header('tool1').getAttribute('aria-expanded')).toBe('false');
+      header('tool1').click();
+      expect(header('tool1').getAttribute('aria-expanded')).toBe('true');
+    }
+    controller.destroy();
+    controller = createAgentExperience(mount, { future: { v5Defaults }, apiUrl: '/test', persistState: false, launcher: { enabled: false }, features: { reasoningDisplay: { variant: 'row' } } });
+    controller.injectTestMessage({ type: 'message', message: { id: 'r1', role: 'assistant', content: '', createdAt: '2026-01-01', variant: 'reasoning', reasoning: { id: 'r1', status: 'streaming', chunks: ['Thinking'] } } });
+    expect(header('r1').getAttribute('aria-expanded')).toBe(String(!v5Defaults));
+  });
+  it('opens on first token, collapses once, and preserves a manual decision', () => {
+    start(v5Defaults, { variant: 'row', grouped: false, autoExpand: true }); vi.useFakeTimers();
+    inject('tool1', 'running'); expect(header('tool1').getAttribute('aria-expanded')).toBe('false');
+    inject('tool1', 'running', ['one']); expect(header('tool1').getAttribute('aria-expanded')).toBe('true');
+    inject('tool1', 'complete', ['one']); vi.advanceTimersByTime(1000); expect(header('tool1').getAttribute('aria-expanded')).toBe('false');
+    header('tool1').click(); expect(header('tool1').getAttribute('aria-expanded')).toBe('true');
+    inject('tool1', 'complete', ['one']); vi.advanceTimersByTime(2000); expect(header('tool1').getAttribute('aria-expanded')).toBe('true');
+  });
+  it('cancels pending collapse on clear and supports reused message IDs', () => {
+    start(v5Defaults, { variant: 'row', grouped: false, autoExpand: true }); vi.useFakeTimers();
+    inject('tool1', 'running', ['one']); inject('tool1', 'complete', ['one']); controller.clearChat();
+    inject('tool1', 'running', ['new']); vi.advanceTimersByTime(1100); expect(header('tool1').getAttribute('aria-expanded')).toBe('true');
+    controller.destroy(); vi.advanceTimersByTime(1100);
+  });
+  it('groups consecutive calls with a collapsible label and staggered children', () => {
+    start(v5Defaults, { variant: 'row', grouped: true, groupedMode: 'collapsible' });
+    inject('tool1', 'complete', ['one']); inject('tool2', 'complete', ['two']);
+    const group = mount.querySelector('[data-persona-tool-group]')!;
+    expect(group.querySelector('button')?.textContent).toContain('Used 2 tools');
+    const children = group.querySelectorAll<HTMLElement>('.persona-activity-group-child'); expect(children).toHaveLength(2);
+    expect(children[1].style.getPropertyValue('--persona-activity-stagger')).toBe('40ms');
+    const chevron = () => header('tool-group-tool1').querySelector('.persona-activity-chevron svg')!.outerHTML;
+    const collapsedChevron = chevron();
+    expect(header('tool-group-tool1').querySelector('svg[stroke="currentColor"]')).not.toBeNull();
+    header('tool-group-tool1').click(); expect(header('tool-group-tool1').getAttribute('aria-expanded')).toBe('true');
+    expect(chevron()).not.toBe(collapsedChevron);
+    header('tool-group-tool1').click();
+    expect(header('tool-group-tool1').getAttribute('aria-expanded')).toBe('false');
+    expect(chevron()).toBe(collapsedChevron);
+    controller.injectTestMessage({ type: 'message', message: { id: 'text3', sequence: 3, role: 'assistant', content: 'Break', createdAt: '2026-01-01T00:00:00Z' } });
+    inject('tool4', 'complete', ['four']); expect(mount.querySelectorAll('[data-persona-tool-group]')).toHaveLength(1);
+  });
+  it('honors explicit static display and content renderers', () => {
+    start(v5Defaults, { variant: 'row', grouped: false, expandable: false });
+    inject('tool1', 'running', ['one']); expect(header('tool1').hasAttribute('data-expand-header')).toBe(false);
+  });
+  it('uses the same first-token lifecycle for reasoning', () => {
+    controller = createAgentExperience(mount, { future: { v5Defaults }, apiUrl: '/test', persistState: false, launcher: { enabled: false }, features: { reasoningDisplay: { variant: 'row', autoExpand: true, autoCollapseDelay: 50 } } });
+    vi.useFakeTimers();
+    const m: AgentWidgetMessage = { id: 'r1', role: 'assistant', content: '', createdAt: '2026-01-01', variant: 'reasoning', reasoning: { id: 'r1', status: 'streaming', chunks: ['Thinking'] } };
+    controller.injectTestMessage({ type: 'message', message: m }); expect(header('r1').getAttribute('aria-expanded')).toBe('true');
+    controller.injectTestMessage({ type: 'message', message: { ...m, reasoning: { ...m.reasoning!, status: 'complete' } } });
+    vi.advanceTimersByTime(50); expect(header('r1').getAttribute('aria-expanded')).toBe('false');
+  });
+});
+
+it('copies current tool output after a streaming DOM update', async () => {
+  start(true, { grouped: false });
+  const writeText = vi.fn().mockResolvedValue(undefined);
+  const original = Object.getOwnPropertyDescriptor(navigator, 'clipboard');
+  Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText } });
+  try {
+    inject('tool1', 'running', ['first']);
+    header('tool1').click();
+    inject('tool1', 'complete', ['updated output']);
+    mount.querySelector<HTMLButtonElement>('[data-persona-copy-tool-detail]')!.click();
+    await Promise.resolve();
+    expect(writeText).toHaveBeenCalledWith('updated output');
+    expect(header('tool1').getAttribute('aria-expanded')).toBe('true');
+  } finally {
+    if (original) Object.defineProperty(navigator, 'clipboard', original);
+    else Reflect.deleteProperty(navigator, 'clipboard');
+  }
+});

package/src/ui.approval-plugin.test.ts

@@ -20,6 +20,18 @@ const createMount = () => {
   return mount;
 };
 
+const approvalDetails = (mount: HTMLElement): HTMLElement => {
+  const details = mount.querySelector<HTMLElement>('[data-role="params"]');
+  expect(details).not.toBeNull();
+  return details!;
+};
+
+const toggleApprovalDetails = (mount: HTMLElement): void => {
+  const toggle = mount.querySelector<HTMLElement>('[data-action="toggle-params"]');
+  expect(toggle).not.toBeNull();
+  toggle!.click();
+};
+
 const injectApproval = (
   controller: ReturnType<typeof createAgentExperience>,
   {
@@ -210,4 +222,55 @@ describe("renderApproval plugin hook", () => {
     expect(mount.querySelector('[data-test-id="custom-pending"]')).toBeNull();
     expect(mount.querySelector(".persona-approval-bubble")).not.toBeNull();
   });
+
+  it("keeps approval disclosure expansion separate for widgets with matching message ids", () => {
+    const firstMount = createMount();
+    const first = createAgentExperience(firstMount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+    } as unknown as Parameters<typeof createAgentExperience>[1]);
+    injectApproval(first, { id: "shared" });
+    toggleApprovalDetails(firstMount);
+    expect(approvalDetails(firstMount).hidden).toBe(false);
+
+    // The transcript derives DOM ids from the message id. Keep both widgets
+    // mounted while removing only the first rendered row ids so the fixture
+    // can model equal message ids without duplicate document ids.
+    firstMount.querySelectorAll("[id]").forEach((element) => element.removeAttribute("id"));
+
+    const secondMount = createMount();
+    const second = createAgentExperience(secondMount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+    } as unknown as Parameters<typeof createAgentExperience>[1]);
+    injectApproval(second, { id: "shared" });
+
+    expect(approvalDetails(secondMount).hidden).toBe(true);
+    first.destroy();
+    second.destroy();
+  });
+
+  it("resets approval disclosure expansion on clearChat and destroy", () => {
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+    } as unknown as Parameters<typeof createAgentExperience>[1]);
+    injectApproval(controller, { id: "after-clear" });
+    toggleApprovalDetails(mount);
+    expect(approvalDetails(mount).hidden).toBe(false);
+    controller.clearChat();
+    injectApproval(controller, { id: "after-clear" });
+    expect(approvalDetails(mount).hidden).toBe(true);
+    controller.destroy();
+
+    const replacementMount = createMount();
+    const replacement = createAgentExperience(replacementMount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+    } as unknown as Parameters<typeof createAgentExperience>[1]);
+    injectApproval(replacement, { id: "after-clear" });
+    expect(approvalDetails(replacementMount).hidden).toBe(true);
+    replacement.destroy();
+  });
 });

package/src/ui.composer-compact.test.ts

@@ -7,6 +7,8 @@ import { createAgentExperience } from "./ui";
 const mounts: HTMLElement[] = [];
 const controllers: ReturnType<typeof createAgentExperience>[] = [];
 
+let selectedDefaults = false;
+
 const makeController = (config: Record<string, unknown> = {}) => {
   const mount = document.createElement("div");
   document.body.appendChild(mount);
@@ -15,6 +17,7 @@ const makeController = (config: Record<string, unknown> = {}) => {
     apiUrl: "https://api.example.com/chat",
     launcher: { enabled: false },
     persistState: false,
+    future: { v5Defaults: selectedDefaults },
     suggestionChips: [],
     ...config,
   } as unknown as Parameters<typeof createAgentExperience>[1]);
@@ -68,12 +71,17 @@ const capturingFetch = () =>
       }),
     }) as unknown as Response;
 
-describe("composer compact state", () => {
+describe.each([false, true])("composer compact state (v5Defaults: %s)", (v5Defaults) => {
   beforeEach(() => {
+    selectedDefaults = v5Defaults;
     window.scrollTo = vi.fn();
   });
 
   afterEach(() => {
+    if (v5Defaults) for (const mount of mounts) {
+      expect(mount.style.getPropertyValue("--persona-input-radius")).toBe("9999px");
+      expect(mount.style.getPropertyValue("--persona-composer-control-size")).toBe("32px");
+    }
     controllers.splice(0).forEach((controller) => {
       try {
         controller.destroy();
@@ -149,7 +157,7 @@ describe("composer compact state", () => {
     expect(isCompact(mount)).toBe(true);
   });
 
-  it("expands while dictation is active", async () => {
+  it("keeps recording compact until its text needs more space", async () => {
     class FakeRecognition {
       continuous = false;
       interimResults = false;
@@ -163,12 +171,26 @@ describe("composer compact state", () => {
     vi.stubGlobal("SpeechRecognition", FakeRecognition);
     const { mount, controller } = makeController({
       voiceRecognition: { enabled: true },
+      composer: { layout: "single-row" },
     });
     await flush();
     expect(isCompact(mount)).toBe(true);
     controller.startVoiceRecognition();
     await type(mount, "");
+    expect(isCompact(mount)).toBe(true);
+    const mic = mount.querySelector<HTMLElement>('[data-persona-composer-mic]')!;
+    expect(mic.dataset.state).toBe('recording');
+    expect(mic.getAttribute('aria-label')).toBe('Stop voice recognition');
+    await type(mount, "Short dictated text");
+    expect(isCompact(mount)).toBe(true);
+    await type(mount, "First line\nSecond line");
     expect(isCompact(mount)).toBe(false);
+    expect(mic.dataset.state).toBe('recording');
+    controller.stopVoiceRecognition();
+    expect(isCompact(mount)).toBe(false);
+    expect(mic.dataset.state).toBe('idle');
+    await type(mount, "");
+    expect(isCompact(mount)).toBe(true);
     vi.unstubAllGlobals();
   });
 });

package/src/ui.composer-placement.test.ts

@@ -175,3 +175,26 @@ describe("observer lifecycle", () => {
     expect(disconnect).toHaveBeenCalled();
   });
 });
+
+describe.each([false, true])('transcript top fade (V5 %s)', v5Defaults => {
+  it('tracks scroll position, explicit overrides, and clear', () => {
+    const { mount, controller } = makeController({ future: { v5Defaults } });
+    const body = mount.querySelector<HTMLElement>('.persona-widget-body')!;
+    expect(body.hasAttribute('data-persona-top-fade')).toBe(false);
+    body.scrollTop = 80;
+    body.dispatchEvent(new Event('scroll'));
+    expect(body.hasAttribute('data-persona-top-fade')).toBe(v5Defaults);
+    controller.update({ layout: { topFade: true } });
+    expect(body.hasAttribute('data-persona-top-fade')).toBe(true);
+    controller.update({ layout: { topFade: false } });
+    expect(body.hasAttribute('data-persona-top-fade')).toBe(false);
+    controller.update({ layout: { topFade: true } });
+    body.scrollTop = 0;
+    body.dispatchEvent(new Event('scroll'));
+    expect(body.hasAttribute('data-persona-top-fade')).toBe(false);
+    body.scrollTop = 80;
+    body.dispatchEvent(new Event('scroll'));
+    controller.clearChat();
+    expect(body.hasAttribute('data-persona-top-fade')).toBe(false);
+  });
+});