@runtypelabs/persona 4.23.2 → 4.24.0

package/src/types/theme.ts

@@ -212,6 +212,8 @@ export interface InputTokens extends ComponentTokenSet {
 }
 
 export interface LauncherTokens extends ComponentTokenSet {
+  /** Distance from the viewport edges. Circle default: 20px; pill: 24px. */
+  offset?: string;
   size: string;
   iconSize: string;
   shadow: TokenReference<'shadow'>;
@@ -235,6 +237,15 @@ export interface PanelTokens extends ComponentTokenSet {
   inset?: string;
   /** Background of the region revealed behind a detached panel. */
   canvasBackground?: string;
+  /** Chrome defaults by rendered panel mode. */
+  modes?: Partial<Record<'floating' | 'inline' | 'sidebar' | 'docked' | 'mobile', {
+    /** Full border shorthand (for example, `"1px solid var(--persona-border)"`). */
+    border?: string;
+    /** Box-shadow token reference or raw CSS shadow. */
+    shadow?: string;
+    /** Corner radius token reference or raw CSS radius. */
+    borderRadius?: TokenReference<'radius'>;
+  }>>;
 }
 
 /** Per-element text styling shared by themable text surfaces. */
@@ -263,10 +274,16 @@ export interface HeaderTokens extends ComponentTokenSet {
    */
   border?: TokenReference<'color'>;
   borderRadius: TokenReference<'radius'>;
+  /** Standard-header padding. @default "20px 24px" */
+  padding?: string;
+  /** Minimal-header padding. Explicitly wins over `padding`. @default "16px 24px" */
+  minimalPadding?: string;
   /** Background of the rounded avatar tile next to the title (Lucide / emoji / image). */
   iconBackground: TokenReference<'color'>;
   /** Foreground (glyph stroke or emoji text) on the header avatar tile. */
   iconForeground: TokenReference<'color'>;
+  /** Header identity glyph size as a fraction of its icon box. @default "0.6" */
+  iconScale?: string;
   /**
    * Legacy alias of `title.color`; `title.color` wins when both are set.
    * Unset, the title takes `foreground`, then the primary color.
@@ -305,6 +322,14 @@ export interface HeaderTokens extends ComponentTokenSet {
    * sibling. @default "1.5"
    */
   controlStrokeWidth?: string;
+  /** Header control corner radius. Per-control radius overrides win. */
+  controlBorderRadius?: string;
+  /** Default control hover/focus fill. Explicit button backgrounds win. */
+  controlHoverBackground?: TokenReference<'color'>;
+  /** Default control hover/focus icon color. Explicit button colors win. */
+  controlHoverForeground?: TokenReference<'color'>;
+  /** Keyboard focus outline; unset preserves the browser default. */
+  controlFocusOutline?: string;
   /** Box-shadow on the header (e.g., a fade shadow to replace the default border). */
   shadow?: string;
   /** Override the header bottom border (e.g., `none`). */
@@ -484,6 +509,12 @@ export interface MessageGeometryTokens {
 }
 
 export interface MessageTokens {
+  /** Height of the optional transcript top fade. Default 18px. */
+  topFadeHeight?: string;
+  /** Vertical gap between transcript turns. @default "12px" */
+  gap?: string;
+  /** Gap between turns in fullscreen mode; falls back to `gap`. */
+  fullscreenGap?: string;
   user: MessageGeometryTokens & {
     background: TokenReference<'color'>;
     text: TokenReference<'color'>;
@@ -497,6 +528,8 @@ export interface MessageTokens {
     borderRadius: TokenReference<'radius'>;
     /** Assistant bubble border color (CSS color). */
     border?: TokenReference<'color'>;
+    /** Border width; set to 0px for a flat assistant response. @default "1px" */
+    borderWidth?: string;
     /** Assistant bubble box-shadow (token ref or raw CSS, e.g. `none`). */
     shadow?: string;
   };
@@ -622,13 +655,42 @@ export interface AttachmentTokens {
 }
 
 /** Tool-call row chrome (collapsible tool bubbles). */
-export interface ToolBubbleTokens {
+export interface ActivityTokens {
+  /** Minimum activity row height. */
+  rowHeight?: string;
+  /** Group child indentation; falls back to indent when unset. V5: 0px. */
+  groupIndent?: string;
+  /** Extra vertical gap between grouped rows. V5: 0px. */
+  groupGap?: string;
+  /** Padding around expanded group children. V5: 0px. */
+  groupPadding?: string;
+  /** Gap between consecutive activity entries. V5: 0px. */
+  transcriptGap?: string;
+  /** Gap from activity to an assistant response. V5: 12px. */
+  responseGap?: string;
+  /** Expanded body padding. V5: 4px 0. */
+  bodyPadding?: string;
+  /** Expanded reasoning text size. V5: 13px. */
+  bodySize?: string;
+  /** Expanded reasoning line height. V5: 1.5. */
+  bodyLineHeight?: string;
+  /** Expanded reasoning font weight. V5: 400. */
+  bodyFontWeight?: string;
+  /** Gap between expanded detail sections. V5: 8px. */
+  sectionGap?: string;
+  labelSize?: string;
+  iconSize?: string;
+  indent?: string;
+  bodySurface?: TokenReference<'color'>;
+}
+
+export interface ToolBubbleTokens extends ActivityTokens {
   /** Box-shadow for tool bubbles (token ref or raw CSS, e.g. `none`). */
   shadow: string;
 }
 
 /** Reasoning / “thinking” row chrome. */
-export interface ReasoningBubbleTokens {
+export interface ReasoningBubbleTokens extends ActivityTokens {
   shadow: string;
 }
 
@@ -769,6 +831,10 @@ export interface ComposerChromeTokens {
   shadow: string;
   /** Border color of the composer form. @default semantic.colors.border */
   borderColor?: TokenReference<'color'>;
+  /** Focused form border color; falls back to borderColor. V5: a stronger neutral border. */
+  focusBorderColor?: TokenReference<'color'>;
+  /** Outer focus ring (CSS outline shorthand). V4: none; V5: a thin neutral ring. */
+  focusRing?: string;
   /** Inner padding of the composer form (raw CSS shorthand). @default "0.75rem 1rem" */
   padding?: string;
   /** Gap between the textarea row and the actions row. @default "0.5rem" */
@@ -787,12 +853,18 @@ export interface ComposerChromeTokens {
   controlSize?: string;
   /** Glyph box inside those controls. @default "24px" */
   controlIconSize?: string;
+  /** Send/stop glyph size. Explicit sendButton.iconSize wins. V5: 18px. */
+  sendIconSize?: string;
+  /** Icon-mode submit button radius. V4 inherits the primary button; V5: 9999px. */
+  sendButtonRadius?: string;
+  /** Footer top border (CSS shorthand). V4: 1px solid divider; V5: none. */
+  footerBorder?: string;
   /**
    * Background painted behind an overlaid composer footer
    * (`composer.placement: "overlay"`). Any CSS `background` value, gradients
    * included — same convention as the shadow tokens. Inert under
    * `placement: "block"`.
-   * @default "transparent"
+   * @default "transparent" (V4); a theme-aware 24px fade (V5)
    */
   overlayBand?: string;
   /** Segmented mode-group track. */
@@ -979,6 +1051,8 @@ export interface ScrollToBottomTokens extends ComponentTokenSet {
 
 /** Visual tokens shared by one suggestion presentation variant. */
 export interface SuggestionVariantTokens extends ComponentTokenSet {
+  /** Label weight. V4: 500; V5: 400. */
+  fontWeight?: string;
   /** Space inside one item, between its icon and its copy. */
   gap?: string;
   /** Space between suggestion items in the container. */
@@ -1030,6 +1104,7 @@ export interface ComponentTokens {
   voice: VoiceTokens;
   approval: ApprovalTokens;
   attachment: AttachmentTokens;
+  activity?: ActivityTokens;
   toolBubble: ToolBubbleTokens;
   reasoningBubble: ReasoningBubbleTokens;
   /** Event-stream inspector badge chips. */
@@ -1124,4 +1199,6 @@ export interface CreateThemeOptions {
   plugins?: PersonaThemePlugin[];
   validate?: boolean;
   extend?: PersonaTheme;
+  /** Selects the defaults overlay; explicit theme tokens always take precedence. */
+  future?: { v5Defaults?: boolean };
 }

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;
@@ -5443,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;
@@ -5454,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;
 };
 
@@ -5518,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";
 
@@ -5571,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
@@ -5584,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.
@@ -5604,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;
   /**
@@ -5941,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';
@@ -6323,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;
 };
 
 // ============================================================================
@@ -6951,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;
   /**
@@ -7106,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
@@ -7138,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.
@@ -7840,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');
+  }
+});