@runtypelabs/persona 3.9.2 → 3.10.0

package/src/theme-editor/preview-utils.ts

@@ -197,7 +197,195 @@ export function buildSrcdoc(
 
 export type PreviewScene = 'home' | 'conversation' | 'minimized' | 'artifact';
 
-export function createPreviewMessages(scene: PreviewScene): AgentWidgetMessage[] {
+export type PreviewTranscriptEntryPreset =
+  | 'user-message'
+  | 'assistant-message'
+  | 'reasoning-streaming'
+  | 'reasoning-complete'
+  | 'tool-running'
+  | 'tool-complete';
+
+const PREVIEW_TRANSCRIPT_PRESET_LABELS: Record<PreviewTranscriptEntryPreset, string> = {
+  'user-message': 'User message',
+  'assistant-message': 'Assistant message',
+  'reasoning-streaming': 'Reasoning (streaming)',
+  'reasoning-complete': 'Reasoning (complete)',
+  'tool-running': 'Tool call (running)',
+  'tool-complete': 'Tool call (complete)',
+};
+
+export function getPreviewTranscriptPresetLabel(preset: PreviewTranscriptEntryPreset): string {
+  return PREVIEW_TRANSCRIPT_PRESET_LABELS[preset];
+}
+
+export function createPreviewTranscriptEntry(
+  preset: PreviewTranscriptEntryPreset,
+  index = 0
+): AgentWidgetMessage {
+  const createdAt = new Date(Date.now() - Math.max(0, 60 - index) * 1000).toISOString();
+  const suffix = `${preset}-${index}`;
+
+  switch (preset) {
+    case 'user-message':
+      return {
+        id: `preview-seq-user-${suffix}`,
+        role: 'user',
+        content: 'Can you continue with the next step?',
+        createdAt,
+      };
+    case 'assistant-message':
+      return {
+        id: `preview-seq-assistant-${suffix}`,
+        role: 'assistant',
+        content: 'Absolutely. I can keep going and explain what happens next.',
+        createdAt,
+      };
+    case 'reasoning-streaming':
+      return {
+        id: `preview-seq-reasoning-stream-${suffix}`,
+        role: 'assistant',
+        content: '',
+        createdAt,
+        streaming: true,
+        variant: 'reasoning',
+        reasoning: {
+          id: `preview-reasoning-stream-${suffix}`,
+          status: 'streaming',
+          chunks: ['Thinking through the next step in the workflow...'],
+        },
+      };
+    case 'reasoning-complete':
+      return {
+        id: `preview-seq-reasoning-complete-${suffix}`,
+        role: 'assistant',
+        content: '',
+        createdAt,
+        streaming: false,
+        variant: 'reasoning',
+        reasoning: {
+          id: `preview-reasoning-complete-${suffix}`,
+          status: 'complete',
+          chunks: ['Reviewed the requirements and finalized the reasoning output.'],
+          durationMs: 1200,
+        },
+      };
+    case 'tool-complete':
+      return {
+        id: `preview-seq-tool-complete-${suffix}`,
+        role: 'assistant',
+        content: '',
+        createdAt,
+        streaming: false,
+        variant: 'tool',
+        toolCall: {
+          id: `preview-tool-complete-${suffix}`,
+          name: 'Create build instructions',
+          status: 'complete',
+          chunks: ['Prepared the build instructions and validated the inputs.'],
+          result: { ok: true },
+          duration: 420,
+        },
+      };
+    case 'tool-running':
+    default:
+      return {
+        id: `preview-seq-tool-running-${suffix}`,
+        role: 'assistant',
+        content: '',
+        createdAt,
+        streaming: true,
+        variant: 'tool',
+        toolCall: {
+          id: `preview-tool-running-${suffix}`,
+          name: 'Get platform documentation',
+          status: 'running',
+          chunks: ['Fetching the relevant platform documentation...'],
+        },
+      };
+  }
+}
+
+export function appendPreviewTranscriptEntry(
+  messages: AgentWidgetMessage[],
+  preset: PreviewTranscriptEntryPreset
+): AgentWidgetMessage[] {
+  return [...messages, createPreviewTranscriptEntry(preset, messages.length)];
+}
+
+const createAdvancedTranscriptPreviewMessages = (): AgentWidgetMessage[] => [
+  {
+    id: "preview-adv-1",
+    role: "user",
+    content: "Can you create the product and gather the docs?",
+    createdAt: new Date(Date.now() - 180000).toISOString(),
+  },
+  {
+    id: "preview-adv-2",
+    role: "assistant",
+    content: "",
+    createdAt: new Date(Date.now() - 150000).toISOString(),
+    streaming: true,
+    variant: "reasoning",
+    reasoning: {
+      id: "preview-reasoning",
+      status: "streaming",
+      chunks: [
+        "Now let me get the Persona embed documentation and builtin tools catalog.",
+      ],
+    },
+  },
+  {
+    id: "preview-adv-3",
+    role: "assistant",
+    content: "",
+    createdAt: new Date(Date.now() - 120000).toISOString(),
+    streaming: true,
+    variant: "tool",
+    toolCall: {
+      id: "preview-tool-1",
+      name: "Load tools",
+      status: "running",
+      chunks: ["Loaded tools, used Runtype integration"],
+    },
+  },
+  {
+    id: "preview-adv-4",
+    role: "assistant",
+    content: "",
+    createdAt: new Date(Date.now() - 90000).toISOString(),
+    streaming: true,
+    variant: "tool",
+    toolCall: {
+      id: "preview-tool-2",
+      name: "Get platform documentation",
+      status: "running",
+      chunks: ["Get platform documentation"],
+    },
+  },
+  {
+    id: "preview-adv-5",
+    role: "assistant",
+    content: "I loaded the tools and fetched the docs. Next I can assemble the product details.",
+    createdAt: new Date(Date.now() - 30000).toISOString(),
+  },
+];
+
+const shouldSeedAdvancedTranscriptPreview = (
+  config?: Partial<AgentWidgetConfig>
+): boolean =>
+  Boolean(
+    config?.features?.toolCallDisplay?.activePreview ||
+      config?.features?.toolCallDisplay?.grouped ||
+      (config?.features?.toolCallDisplay?.collapsedMode &&
+        config.features.toolCallDisplay.collapsedMode !== "tool-call") ||
+      config?.features?.reasoningDisplay?.activePreview
+  );
+
+export function createPreviewMessages(
+  scene: PreviewScene,
+  config?: Partial<AgentWidgetConfig>,
+  appendedMessages: AgentWidgetMessage[] = []
+): AgentWidgetMessage[] {
   if (scene === 'home') {
     return [{ id: 'preview-home-1', role: 'assistant', content: 'Hi there! How can we help today?', createdAt: new Date().toISOString() }];
   }
@@ -210,22 +398,30 @@ export function createPreviewMessages(scene: PreviewScene): AgentWidgetMessage[]
       { id: 'preview-art-2', role: 'assistant', content: 'Here\u2019s a project overview document for you.', createdAt: new Date(Date.now() - 60000).toISOString() },
     ];
   }
+  if (scene === 'conversation' && shouldSeedAdvancedTranscriptPreview(config)) {
+    return [...createAdvancedTranscriptPreviewMessages(), ...appendedMessages];
+  }
   return [
     { id: 'preview-conv-1', role: 'assistant', content: 'Hello! How can I help you today?', createdAt: new Date(Date.now() - 180000).toISOString() },
     { id: 'preview-conv-2', role: 'user', content: 'I want to customize the theme editor preview.', createdAt: new Date(Date.now() - 120000).toISOString() },
     { id: 'preview-conv-3', role: 'assistant', content: 'Absolutely. Check out the [getting started guide](https://example.com) to see what\u2019s possible, then adjust colors and tokens to match your brand.', createdAt: new Date(Date.now() - 60000).toISOString() },
+    ...appendedMessages,
   ];
 }
 
 // ─── Scene Config ───────────────────────────────────────────────
 
-export function applySceneConfig(base: AgentWidgetConfig, scene: PreviewScene): AgentWidgetConfig {
+export function applySceneConfig(
+  base: AgentWidgetConfig,
+  scene: PreviewScene,
+  appendedMessages: AgentWidgetMessage[] = []
+): AgentWidgetConfig {
   const launcher = { ...base.launcher, enabled: true, autoExpand: scene !== 'minimized' };
   const config = {
     ...base,
     launcher,
     suggestionChips: scene === 'home' ? (base.suggestionChips?.length ? base.suggestionChips : HOME_SUGGESTION_CHIPS) : base.suggestionChips,
-    initialMessages: createPreviewMessages(scene),
+    initialMessages: createPreviewMessages(scene, base, appendedMessages),
     storageAdapter: PREVIEW_STORAGE_ADAPTER,
   } as AgentWidgetConfig;
 
@@ -244,6 +440,7 @@ export interface PreviewConfigOptions {
   theme?: DeepPartial<PersonaTheme>;
   darkTheme?: DeepPartial<PersonaTheme>;
   scene?: PreviewScene;
+  appendedMessages?: AgentWidgetMessage[];
 }
 
 export function buildPreviewConfig(
@@ -261,5 +458,24 @@ export function buildPreviewConfig(
     colorScheme: shellModeOverride ?? (options.config?.colorScheme as string) ?? 'light',
   } as AgentWidgetConfig;
 
-  return applySceneConfig(base, scene);
+  return applySceneConfig(base, scene, options.appendedMessages ?? []);
+}
+
+export function buildPreviewConfigWithMessages(
+  options: PreviewConfigOptions,
+  messages: AgentWidgetMessage[],
+  shellModeOverride?: 'light' | 'dark'
+): AgentWidgetConfig {
+  const theme = options.theme ? createTheme(options.theme, { validate: false }) : createTheme();
+  const scene = options.scene ?? 'conversation';
+
+  const base = {
+    ...DEFAULT_WIDGET_CONFIG,
+    ...options.config,
+    theme,
+    darkTheme: options.darkTheme,
+    colorScheme: shellModeOverride ?? (options.config?.colorScheme as string) ?? 'light',
+  } as AgentWidgetConfig;
+
+  return applySceneConfig(base, scene, messages);
 }

package/src/theme-editor/sections.test.ts

@@ -40,4 +40,24 @@ describe("theme editor scroll-to-bottom controls", () => {
     );
     expect(INTERFACE_ROLES_SECTION.fields.some((field) => field.id === "role-scroll-to-bottom")).toBe(true);
   });
+
+  it("exposes grouped and collapsed tool call preview controls", () => {
+    const debugSection = CONFIGURE_SECTIONS.find((section) => section.id === "debug-inspection");
+
+    expect(debugSection?.fields.some((field) => field.path === "features.toolCallDisplay.collapsedMode")).toBe(true);
+    expect(debugSection?.fields.some((field) => field.path === "features.toolCallDisplay.activePreview")).toBe(true);
+    expect(debugSection?.fields.some((field) => field.path === "features.toolCallDisplay.previewMaxLines")).toBe(true);
+    expect(debugSection?.fields.some((field) => field.path === "features.toolCallDisplay.activeMinHeight")).toBe(true);
+    expect(debugSection?.fields.some((field) => field.path === "features.toolCallDisplay.expandable")).toBe(true);
+    expect(debugSection?.fields.some((field) => field.path === "features.toolCallDisplay.grouped")).toBe(true);
+  });
+
+  it("exposes collapsed reasoning preview controls", () => {
+    const debugSection = CONFIGURE_SECTIONS.find((section) => section.id === "debug-inspection");
+
+    expect(debugSection?.fields.some((field) => field.path === "features.reasoningDisplay.expandable")).toBe(true);
+    expect(debugSection?.fields.some((field) => field.path === "features.reasoningDisplay.activePreview")).toBe(true);
+    expect(debugSection?.fields.some((field) => field.path === "features.reasoningDisplay.previewMaxLines")).toBe(true);
+    expect(debugSection?.fields.some((field) => field.path === "features.reasoningDisplay.activeMinHeight")).toBe(true);
+  });
 });

package/src/theme-editor/sections.ts

@@ -743,6 +743,16 @@ const debugSectionDef: SectionDef = {
   fields: [
     { id: 'dev-reasoning', label: 'Show Reasoning', description: 'Display AI reasoning steps', type: 'toggle', path: 'features.showReasoning', defaultValue: false },
     { id: 'dev-tool-calls', label: 'Show Tool Calls', description: 'Display tool call details', type: 'toggle', path: 'features.showToolCalls', defaultValue: false },
+    { id: 'dev-tool-collapsed-mode', label: 'Tool Call Summary', description: 'Choose what collapsed tool rows show by default', type: 'select', path: 'features.toolCallDisplay.collapsedMode', defaultValue: 'tool-call', options: [{ value: 'tool-call', label: 'Tool Call' }, { value: 'tool-name', label: 'Tool Name' }, { value: 'tool-preview', label: 'Tool Preview' }] },
+    { id: 'dev-tool-active-preview', label: 'Tool Preview While Active', description: 'Show a lightweight preview in collapsed active tool rows', type: 'toggle', path: 'features.toolCallDisplay.activePreview', defaultValue: false },
+    { id: 'dev-tool-preview-lines', label: 'Tool Preview Lines', type: 'select', path: 'features.toolCallDisplay.previewMaxLines', defaultValue: 3, options: [{ value: '1', label: '1' }, { value: '2', label: '2' }, { value: '3', label: '3' }, { value: '4', label: '4' }, { value: '5', label: '5' }], formatValue: (v: unknown) => String(v ?? 3), parseValue: (v: unknown) => Number(v) },
+    { id: 'dev-tool-active-min-height', label: 'Tool Active Min Height', description: 'CSS min-height for collapsed active tool rows (e.g. 5rem)', type: 'text', path: 'features.toolCallDisplay.activeMinHeight', defaultValue: '' },
+    { id: 'dev-tool-expandable', label: 'Tool Calls Expandable', description: 'Allow expanding tool call rows to see full details', type: 'toggle', path: 'features.toolCallDisplay.expandable', defaultValue: true },
+    { id: 'dev-tool-grouped', label: 'Group Sequential Tool Calls', description: 'Render consecutive tool rows inside a grouped container', type: 'toggle', path: 'features.toolCallDisplay.grouped', defaultValue: false },
+    { id: 'dev-reasoning-expandable', label: 'Reasoning Expandable', description: 'Allow expanding reasoning rows to see full details', type: 'toggle', path: 'features.reasoningDisplay.expandable', defaultValue: true },
+    { id: 'dev-reasoning-active-preview', label: 'Reasoning Preview While Active', description: 'Show a lightweight preview in collapsed active reasoning rows', type: 'toggle', path: 'features.reasoningDisplay.activePreview', defaultValue: false },
+    { id: 'dev-reasoning-preview-lines', label: 'Reasoning Preview Lines', type: 'select', path: 'features.reasoningDisplay.previewMaxLines', defaultValue: 3, options: [{ value: '1', label: '1' }, { value: '2', label: '2' }, { value: '3', label: '3' }, { value: '4', label: '4' }, { value: '5', label: '5' }], formatValue: (v: unknown) => String(v ?? 3), parseValue: (v: unknown) => Number(v) },
+    { id: 'dev-reasoning-active-min-height', label: 'Reasoning Active Min Height', description: 'CSS min-height for collapsed active reasoning rows (e.g. 5rem)', type: 'text', path: 'features.reasoningDisplay.activeMinHeight', defaultValue: '' },
     { id: 'dev-debug', label: 'Debug Mode', description: 'Show debug information', type: 'toggle', path: 'debug', defaultValue: false },
   ],
 };

package/src/theme-reference.ts

@@ -210,9 +210,14 @@ export const THEME_TOKEN_DOCS = {
         'features.scrollToBottom.enabled, features.scrollToBottom.iconName, features.scrollToBottom.label (empty string renders icon-only). Defaults: enabled=true, iconName="arrow-down", label="".',
     },
     toolCall: {
-      description: 'Tool call display styling.',
+      description: 'Tool call display styling and collapsed/grouped rendering hooks.',
       properties:
-        'shadow, backgroundColor, borderColor, borderWidth, borderRadius, headerBackgroundColor, headerTextColor, headerPaddingX, headerPaddingY, contentBackgroundColor, contentTextColor, contentPaddingX, contentPaddingY, codeBlockBackgroundColor, codeBlockBorderColor, codeBlockTextColor, toggleTextColor, labelTextColor.',
+        'shadow, backgroundColor, borderColor, borderWidth, borderRadius, headerBackgroundColor, headerTextColor, headerPaddingX, headerPaddingY, contentBackgroundColor, contentTextColor, contentPaddingX, contentPaddingY, codeBlockBackgroundColor, codeBlockBorderColor, codeBlockTextColor, toggleTextColor, labelTextColor, renderCollapsedSummary, renderCollapsedPreview, renderGroupedSummary.',
+    },
+    reasoning: {
+      description: 'Reasoning/thinking row rendering hooks.',
+      properties:
+        'renderCollapsedSummary, renderCollapsedPreview.',
     },
     approval: {
       description:
@@ -277,7 +282,7 @@ export const THEME_TOKEN_DOCS = {
     features: {
       description: 'Feature flags.',
       properties:
-        'showReasoning (AI thinking steps), showToolCalls (tool invocations), artifacts (sidebar config).',
+        'showReasoning (AI thinking steps), showToolCalls (tool invocations), toolCallDisplay (collapsedMode, activePreview, activeMinHeight, previewMaxLines, grouped), reasoningDisplay (activePreview, activeMinHeight, previewMaxLines), artifacts (sidebar config).',
     },
   },
 }

package/src/tool-call-display-defaults.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+
+import { DEFAULT_WIDGET_CONFIG } from "./defaults";
+
+describe("tool call display defaults", () => {
+  it("keeps advanced tool call transcript modes disabled by default", () => {
+    expect(DEFAULT_WIDGET_CONFIG.features?.toolCallDisplay).toEqual({
+      collapsedMode: "tool-call",
+      activePreview: false,
+      grouped: false,
+      previewMaxLines: 3,
+      expandable: true,
+    });
+  });
+
+  it("keeps advanced reasoning transcript modes disabled by default", () => {
+    expect(DEFAULT_WIDGET_CONFIG.features?.reasoningDisplay).toEqual({
+      activePreview: false,
+      previewMaxLines: 3,
+      expandable: true,
+    });
+  });
+});

package/src/types.ts

@@ -572,12 +572,77 @@ export type AgentWidgetScrollToBottomFeature = {
   label?: string;
 };
 
+export type AgentWidgetToolCallCollapsedMode =
+  | "tool-call"
+  | "tool-name"
+  | "tool-preview";
+
+export type AgentWidgetToolCallDisplayFeature = {
+  /**
+   * Controls what collapsed tool call rows show in their header/summary area.
+   * @default "tool-call"
+   */
+  collapsedMode?: AgentWidgetToolCallCollapsedMode;
+  /**
+   * When true, active collapsed tool calls can render a lightweight preview block.
+   * @default false
+   */
+  activePreview?: boolean;
+  /**
+   * Optional CSS min-height applied to active collapsed tool call rows.
+   */
+  activeMinHeight?: string;
+  /**
+   * Maximum preview lines shown for collapsed active tool calls.
+   * @default 3
+   */
+  previewMaxLines?: number;
+  /**
+   * When true, consecutive tool call rows can be visually grouped.
+   * @default false
+   */
+  grouped?: boolean;
+  /**
+   * When false, tool call bubbles show only the collapsed summary with no
+   * expand/collapse toggle. Users see tool awareness without full details.
+   * @default true
+   */
+  expandable?: boolean;
+};
+
+export type AgentWidgetReasoningDisplayFeature = {
+  /**
+   * When true, active collapsed reasoning rows can render a lightweight preview block.
+   * @default false
+   */
+  activePreview?: boolean;
+  /**
+   * Optional CSS min-height applied to active collapsed reasoning rows.
+   */
+  activeMinHeight?: string;
+  /**
+   * Maximum preview lines shown for collapsed active reasoning rows.
+   * @default 3
+   */
+  previewMaxLines?: number;
+  /**
+   * When false, reasoning bubbles show only the collapsed summary with no
+   * expand/collapse toggle. Users see reasoning awareness without full details.
+   * @default true
+   */
+  expandable?: boolean;
+};
+
 export type AgentWidgetFeatureFlags = {
   showReasoning?: boolean;
   showToolCalls?: boolean;
   showEventStreamToggle?: boolean;
   /** Shared transcript + event stream scroll-to-bottom affordance. */
   scrollToBottom?: AgentWidgetScrollToBottomFeature;
+  /** Collapsed transcript behavior for tool call rows. */
+  toolCallDisplay?: AgentWidgetToolCallDisplayFeature;
+  /** Collapsed transcript behavior for reasoning rows. */
+  reasoningDisplay?: AgentWidgetReasoningDisplayFeature;
   /** Configuration for the Event Stream inspector view */
   eventStream?: EventStreamConfig;
   /** Optional artifact sidebar (split pane / mobile drawer) */
@@ -1186,6 +1251,66 @@ export type AgentWidgetToolCallConfig = {
   codeBlockTextColor?: string;
   toggleTextColor?: string;
   labelTextColor?: string;
+  /**
+   * Override the collapsed summary row content for a tool call bubble.
+   * Return `null` to fall back to the built-in summary for the active display mode.
+   */
+  renderCollapsedSummary?: (context: {
+    message: AgentWidgetMessage;
+    toolCall: AgentWidgetToolCall;
+    defaultSummary: string;
+    previewText: string;
+    collapsedMode: AgentWidgetToolCallCollapsedMode;
+    isActive: boolean;
+    config: AgentWidgetConfig;
+  }) => HTMLElement | string | null;
+  /**
+   * Override the lightweight collapsed preview content shown for active tool rows.
+   * Return `null` to fall back to the built-in preview text.
+   */
+  renderCollapsedPreview?: (context: {
+    message: AgentWidgetMessage;
+    toolCall: AgentWidgetToolCall;
+    defaultPreview: string;
+    isActive: boolean;
+    config: AgentWidgetConfig;
+  }) => HTMLElement | string | null;
+  /**
+   * Override the summary content for grouped consecutive tool-call containers.
+   * Return `null` to fall back to the built-in `Called [x] tools` summary.
+   */
+  renderGroupedSummary?: (context: {
+    messages: AgentWidgetMessage[];
+    toolCalls: AgentWidgetToolCall[];
+    defaultSummary: string;
+    config: AgentWidgetConfig;
+  }) => HTMLElement | string | null;
+};
+
+export type AgentWidgetReasoningConfig = {
+  /**
+   * Override the collapsed summary row content for a reasoning bubble.
+   * Return `null` to fall back to the built-in summary.
+   */
+  renderCollapsedSummary?: (context: {
+    message: AgentWidgetMessage;
+    reasoning: AgentWidgetReasoning;
+    defaultSummary: string;
+    previewText: string;
+    isActive: boolean;
+    config: AgentWidgetConfig;
+  }) => HTMLElement | string | null;
+  /**
+   * Override the lightweight collapsed preview content shown for active reasoning rows.
+   * Return `null` to fall back to the built-in preview text.
+   */
+  renderCollapsedPreview?: (context: {
+    message: AgentWidgetMessage;
+    reasoning: AgentWidgetReasoning;
+    defaultPreview: string;
+    isActive: boolean;
+    config: AgentWidgetConfig;
+  }) => HTMLElement | string | null;
 };
 
 export type AgentWidgetSuggestionChipsConfig = {
@@ -2358,6 +2483,7 @@ export type AgentWidgetConfig = {
    */
   textToSpeech?: TextToSpeechConfig;
   toolCall?: AgentWidgetToolCallConfig;
+  reasoning?: AgentWidgetReasoningConfig;
   /**
    * Configuration for tool approval bubbles.
    * Set to `false` to disable built-in approval handling entirely.

package/src/ui.scroll.test.ts

@@ -135,6 +135,36 @@ const emitReasoningMessage = (
   });
 };
 
+const emitToolMessage = (
+  controller: ReturnType<typeof createAgentExperience>,
+  {
+    id = STREAM_MESSAGE_ID,
+    status = "running",
+    chunks,
+  }: {
+    id?: string;
+    status?: "pending" | "running" | "complete";
+    chunks: string[];
+  }
+) => {
+  controller.injectTestMessage({
+    type: "message",
+    message: {
+      id,
+      role: "assistant",
+      content: "",
+      createdAt: STREAM_CREATED_AT,
+      streaming: status !== "complete",
+      variant: "tool",
+      toolCall: {
+        id,
+        status,
+        chunks,
+      }
+    }
+  });
+};
+
 const createCustomComposer = () => {
   const footer = document.createElement("div");
   footer.className = "persona-widget-footer";
@@ -368,6 +398,80 @@ describe("createAgentExperience streaming scroll", () => {
     controller.destroy();
   });
 
+  it("keeps following collapsed tool preview updates while active", () => {
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      features: {
+        toolCallDisplay: {
+          activePreview: true,
+        },
+      },
+    } as any);
+
+    const scrollContainer = mount.querySelector<HTMLElement>("#persona-scroll-container");
+    expect(scrollContainer).not.toBeNull();
+
+    const metrics = installScrollMetrics(scrollContainer!, {
+      scrollHeight: 980,
+      clientHeight: 400
+    });
+
+    emitStreamingStatus(controller);
+    emitToolMessage(controller, { chunks: ["Loaded tools"] });
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(metrics.getBottomScrollTop());
+
+    metrics.setScrollHeight(1045);
+    emitToolMessage(controller, {
+      chunks: ["Loaded tools", "\nFetched platform documentation"]
+    });
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(metrics.getBottomScrollTop());
+
+    controller.destroy();
+  });
+
+  it("keeps following grouped tool sequences as new tool rows arrive", () => {
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      features: {
+        toolCallDisplay: {
+          grouped: true,
+        },
+      },
+    } as any);
+
+    const scrollContainer = mount.querySelector<HTMLElement>("#persona-scroll-container");
+    expect(scrollContainer).not.toBeNull();
+
+    const metrics = installScrollMetrics(scrollContainer!, {
+      scrollHeight: 960,
+      clientHeight: 400
+    });
+
+    emitStreamingStatus(controller);
+    emitToolMessage(controller, { id: "tool-1", chunks: ["Loaded tools"] });
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(metrics.getBottomScrollTop());
+
+    metrics.setScrollHeight(1030);
+    emitToolMessage(controller, { id: "tool-2", chunks: ["Fetched platform documentation"] });
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(metrics.getBottomScrollTop());
+
+    controller.destroy();
+  });
+
   it("uses icon-only arrow-down defaults for the transcript affordance", () => {
     const raf = installRafMock();
     const mount = createMount();