@runtypelabs/persona 4.23.2 → 4.25.0

package/src/types.ts

@@ -2254,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"
@@ -2284,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.
    *
@@ -2319,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
@@ -3078,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.
@@ -3483,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[];
   /**
@@ -3702,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;
@@ -4496,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
@@ -4510,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;
   /**
@@ -4524,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"
@@ -4572,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;
@@ -4587,6 +4614,24 @@ export type AgentWidgetStatusIndicatorConfig = {
   resumingText?: string;
 };
 
+/** Built-in `voiceRecognition.prewarm` triggers. See {@link AgentWidgetVoiceRecognitionConfig.prewarm}. */
+export type AgentWidgetVoicePrewarmTrigger = 'hover';
+
+/**
+ * Custom `voiceRecognition.prewarm` trigger. Runs while the composer has a mic
+ * button, and again when the button is rebuilt or `update()` swaps in a
+ * different function. Call `warm()` whenever the visitor shows intent to talk
+ * (it is safe to call repeatedly). Return a cleanup to run on replacement.
+ */
+export type AgentWidgetVoicePrewarmHook = (context: {
+  /** Fire-and-forget voice warm-up; latched and error-swallowing. */
+  warm: () => void;
+  /** The composer's current mic button. */
+  micButton: HTMLButtonElement;
+  /** The widget's mount element. */
+  mount: HTMLElement;
+}) => void | (() => void);
+
 export type AgentWidgetVoiceRecognitionConfig = {
   /**
    * Enable the mic button and voice input. The mic still only renders when the
@@ -4658,6 +4703,30 @@ export type AgentWidgetVoiceRecognitionConfig = {
    */
   onMetrics?: (metrics: VoiceMetrics) => void;
 
+  /**
+   * Warm the voice path when the visitor shows intent to talk, before the mic
+   * click, so the call starts faster.
+   *
+   * - `'hover'`: when the pointer enters the mic button, it receives focus, or
+   *   (on touch) the first pointer-down on it.
+   * - `false`: never.
+   * - A function: custom trigger. Called with `{ warm, micButton, mount }`
+   *   while the mic button exists (and again when the button is rebuilt or
+   *   `update()` swaps in a different function); call `warm()` whenever you
+   *   decide, e.g. when the panel opens. May return a cleanup that runs on
+   *   destroy, rebuild, or replacement. Replaces the built-in trigger.
+   *
+   * What `warm()` does depends on the provider: `runtype` fires its prewarm
+   * (see `provider.runtype.prewarmMode`), a `custom` provider's optional
+   * {@link VoiceProvider.prewarm} runs, and the browser (Web Speech) path
+   * starts the client-token session init (as `sessionInit` does), since speech
+   * recognition itself cannot start before the click. Warming is
+   * fire-and-forget, latched, and never surfaces an error or UI state.
+   *
+   * @default 'hover' in client token mode, otherwise `false`
+   */
+  prewarm?: AgentWidgetVoicePrewarmTrigger | AgentWidgetVoicePrewarmHook | false;
+
   // Voice provider configuration
   provider?: {
     type: 'browser' | 'runtype' | 'custom';
@@ -4680,6 +4749,23 @@ export type AgentWidgetVoiceRecognitionConfig = {
        * `@runtypelabs/persona/voice-worklet-player` for a jitter-buffered engine.
        */
       createPlaybackEngine?: () => VoicePlaybackEngine | Promise<VoicePlaybackEngine>;
+      /**
+       * How `prewarm()` warms the voice path (see `voiceRecognition.prewarm`).
+       *
+       * - `'request'` (default): a fire-and-forget
+       *   `POST {host}/v1/client/agents/{agentId}/voice/prewarm`.
+       * - `'attach'`: open the voice WebSocket ahead of the click without
+       *   starting a call; the click then starts the call on that socket. It can
+       *   create server work before the visitor clicks, so it is opt-in.
+       * @default 'request'
+       */
+      prewarmMode?: 'request' | 'attach';
+      /**
+       * `'attach'` mode: how long (ms) an attached socket waits for the click
+       * before it closes. The server clamps it to 30000..600000.
+       * @default 30000
+       */
+      attachIdleMs?: number;
       /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
       pauseDuration?: number;
       /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
@@ -4987,6 +5073,10 @@ export type VoiceConfig = {
      * `@runtypelabs/persona/voice-worklet-player` for a jitter-buffered engine.
      */
     createPlaybackEngine?: () => VoicePlaybackEngine | Promise<VoicePlaybackEngine>;
+    /** See `voiceRecognition.provider.runtype.prewarmMode`. @default 'request' */
+    prewarmMode?: 'request' | 'attach';
+    /** See `voiceRecognition.provider.runtype.attachIdleMs`. @default 30000 */
+    attachIdleMs?: number;
     /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
     pauseDuration?: number;
     /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
@@ -5058,6 +5148,14 @@ export interface VoiceProvider {
 
   /** Stop playback / cancel in-flight request without starting recording */
   stopPlayback?(): void;
+
+  /**
+   * Warm the provider ahead of `startListening()` (the widget calls it on mic
+   * intent, see `voiceRecognition.prewarm`). Must be fire-and-forget: never
+   * throw, emit errors or status, or acquire the microphone. May be called
+   * repeatedly; throttle as needed.
+   */
+  prewarm?(): void;
 }
 
 /**
@@ -5443,7 +5541,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;
@@ -5454,7 +5553,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;
 };
 
@@ -5518,8 +5617,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";
 
@@ -5571,7 +5670,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
@@ -5584,19 +5686,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.
@@ -5604,7 +5709,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;
   /**
@@ -5941,6 +6047,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';
@@ -6323,6 +6431,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;
 };
 
 // ============================================================================
@@ -6951,7 +7062,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;
   /**
@@ -7106,6 +7242,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
@@ -7138,13 +7314,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.
@@ -7840,6 +8023,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();
+  });
 });