@runtypelabs/persona 3.10.1 → 3.12.0

package/src/theme-reference.ts

@@ -210,14 +210,20 @@ 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 and collapsed/grouped rendering hooks.',
+      description:
+        'Tool call display styling, text templates, loading animations, and rendering hooks. ' +
+        'Text templates support placeholders ({toolName}, {duration}) and inline formatting (~dim~, *italic*, **bold**). ' +
+        'renderCollapsedSummary receives elapsed (static string) and createElapsedElement() (live-updating span) in its context.',
       properties:
-        'shadow, backgroundColor, borderColor, borderWidth, borderRadius, headerBackgroundColor, headerTextColor, headerPaddingX, headerPaddingY, contentBackgroundColor, contentTextColor, contentPaddingX, contentPaddingY, codeBlockBackgroundColor, codeBlockBorderColor, codeBlockTextColor, toggleTextColor, labelTextColor, renderCollapsedSummary, renderCollapsedPreview, renderGroupedSummary.',
+        'shadow, backgroundColor, borderColor, borderWidth, borderRadius, headerBackgroundColor, headerTextColor, headerPaddingX, headerPaddingY, contentBackgroundColor, contentTextColor, contentPaddingX, contentPaddingY, codeBlockBackgroundColor, codeBlockBorderColor, codeBlockTextColor, toggleTextColor, labelTextColor, activeTextTemplate, completeTextTemplate, loadingAnimationColor, loadingAnimationSecondaryColor, loadingAnimationDuration, renderCollapsedSummary, renderCollapsedPreview, renderGroupedSummary.',
     },
     reasoning: {
-      description: 'Reasoning/thinking row rendering hooks.',
+      description:
+        'Reasoning/thinking row rendering hooks, text templates, and loading animations. ' +
+        'Text templates support {duration} placeholder and inline formatting (~dim~, *italic*, **bold**). ' +
+        'renderCollapsedSummary receives elapsed (static string) and createElapsedElement() (live-updating span) in its context.',
       properties:
-        'renderCollapsedSummary, renderCollapsedPreview.',
+        'renderCollapsedSummary, renderCollapsedPreview, activeTextTemplate, completeTextTemplate, loadingAnimationColor, loadingAnimationSecondaryColor, loadingAnimationDuration.',
     },
     approval: {
       description:
@@ -282,7 +288,7 @@ export const THEME_TOKEN_DOCS = {
     features: {
       description: 'Feature flags.',
       properties:
-        'showReasoning (AI thinking steps), showToolCalls (tool invocations), toolCallDisplay (collapsedMode, activePreview, activeMinHeight, previewMaxLines, grouped), reasoningDisplay (activePreview, activeMinHeight, previewMaxLines), artifacts (sidebar config).',
+        'showReasoning (AI thinking steps), showToolCalls (tool invocations), toolCallDisplay (collapsedMode, activePreview, activeMinHeight, previewMaxLines, grouped, expandable, loadingAnimation), reasoningDisplay (activePreview, activeMinHeight, previewMaxLines, expandable, loadingAnimation), artifacts (sidebar config).',
     },
   },
 }

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

@@ -10,6 +10,7 @@ describe("tool call display defaults", () => {
       grouped: false,
       previewMaxLines: 3,
       expandable: true,
+      loadingAnimation: "none",
     });
   });
 
@@ -18,6 +19,7 @@ describe("tool call display defaults", () => {
       activePreview: false,
       previewMaxLines: 3,
       expandable: true,
+      loadingAnimation: "none",
     });
   });
 });

package/src/types.ts

@@ -577,6 +577,19 @@ export type AgentWidgetToolCallCollapsedMode =
   | "tool-name"
   | "tool-preview";
 
+/**
+ * Animation mode applied to tool call header text while the tool is running.
+ * Character-by-character modes (`shimmer`, `shimmer-color`, `rainbow`) wrap each
+ * character in a span with staggered `animation-delay`. `pulse` applies to the
+ * entire text container. Honors `prefers-reduced-motion`.
+ */
+export type AgentWidgetToolCallLoadingAnimation =
+  | "none"
+  | "pulse"
+  | "shimmer"
+  | "shimmer-color"
+  | "rainbow";
+
 export type AgentWidgetToolCallDisplayFeature = {
   /**
    * Controls what collapsed tool call rows show in their header/summary area.
@@ -590,6 +603,8 @@ export type AgentWidgetToolCallDisplayFeature = {
   activePreview?: boolean;
   /**
    * Optional CSS min-height applied to active collapsed tool call rows.
+   * @default undefined (no min-height)
+   * @example "100px"
    */
   activeMinHeight?: string;
   /**
@@ -608,6 +623,16 @@ export type AgentWidgetToolCallDisplayFeature = {
    * @default true
    */
   expandable?: boolean;
+  /**
+   * Animation mode applied to the tool call header text while the tool is active.
+   * - "none" — static text, no animation
+   * - "pulse" — opacity pulse on the entire header text
+   * - "shimmer" — monochrome opacity sweep per character
+   * - "shimmer-color" — color gradient sweep per character
+   * - "rainbow" — rainbow color cycle per character
+   * @default "none"
+   */
+  loadingAnimation?: AgentWidgetToolCallLoadingAnimation;
 };
 
 export type AgentWidgetReasoningDisplayFeature = {
@@ -631,6 +656,17 @@ export type AgentWidgetReasoningDisplayFeature = {
    * @default true
    */
   expandable?: boolean;
+  /**
+   * Animation mode applied to the reasoning header text while reasoning is active.
+   * Reuses the same modes as tool call animations.
+   * - "none" — static text, no animation
+   * - "pulse" — opacity pulse on the entire header text
+   * - "shimmer" — monochrome opacity sweep per character
+   * - "shimmer-color" — color gradient sweep per character
+   * - "rainbow" — rainbow color cycle per character
+   * @default "none"
+   */
+  loadingAnimation?: AgentWidgetToolCallLoadingAnimation;
 };
 
 export type AgentWidgetFeatureFlags = {
@@ -1234,22 +1270,39 @@ export type AgentWidgetApprovalConfig = {
 export type AgentWidgetToolCallConfig = {
   /** Box-shadow for tool-call bubbles; overrides `theme.toolBubbleShadow` when set. */
   shadow?: string;
+  /** Background color of the tool call bubble container. */
   backgroundColor?: string;
+  /** Border color of the tool call bubble container. */
   borderColor?: string;
+  /** Border width of the tool call bubble container (CSS value, e.g. `"1px"`). */
   borderWidth?: string;
+  /** Border radius of the tool call bubble container (CSS value, e.g. `"12px"`). */
   borderRadius?: string;
+  /** Background color of the collapsed header row. */
   headerBackgroundColor?: string;
+  /** Text color of the collapsed header row (tool name / summary). */
   headerTextColor?: string;
+  /** Horizontal padding of the collapsed header row (CSS value). */
   headerPaddingX?: string;
+  /** Vertical padding of the collapsed header row (CSS value). */
   headerPaddingY?: string;
+  /** Background color of the expanded content area. */
   contentBackgroundColor?: string;
+  /** Text color of the expanded content area. */
   contentTextColor?: string;
+  /** Horizontal padding of the expanded content area (CSS value). */
   contentPaddingX?: string;
+  /** Vertical padding of the expanded content area (CSS value). */
   contentPaddingY?: string;
+  /** Background color of code blocks (arguments / result) in the expanded area. */
   codeBlockBackgroundColor?: string;
+  /** Border color of code blocks in the expanded area. */
   codeBlockBorderColor?: string;
+  /** Text color of code blocks in the expanded area. */
   codeBlockTextColor?: string;
+  /** Color of the expand/collapse toggle icon. */
   toggleTextColor?: string;
+  /** Color of section labels ("Arguments", "Result", "Activity") in the expanded area. */
   labelTextColor?: string;
   /**
    * Override the collapsed summary row content for a tool call bubble.
@@ -1263,6 +1316,14 @@ export type AgentWidgetToolCallConfig = {
     collapsedMode: AgentWidgetToolCallCollapsedMode;
     isActive: boolean;
     config: AgentWidgetConfig;
+    /** Static elapsed time snapshot, e.g. "2.6s". */
+    elapsed: string;
+    /**
+     * Returns a `<span>` whose text content is automatically updated every
+     * 100ms by the widget's global timer. Place it anywhere in your returned
+     * HTMLElement to get a live-ticking duration display.
+     */
+    createElapsedElement: () => HTMLElement;
   }) => HTMLElement | string | null;
   /**
    * Override the lightweight collapsed preview content shown for active tool rows.
@@ -1285,6 +1346,47 @@ export type AgentWidgetToolCallConfig = {
     defaultSummary: string;
     config: AgentWidgetConfig;
   }) => HTMLElement | string | null;
+  /**
+   * Template string for the header text while a tool call is active (running).
+   *
+   * **Placeholders:** `{toolName}` (tool name), `{duration}` (live-updating elapsed time).
+   *
+   * **Inline formatting:** `~dim~`, `*italic*`, `**bold**` — parsed at render time and
+   * applied as styled `<span>` elements. Works with all animation modes.
+   *
+   * When not set, falls back to the current `collapsedMode` behavior.
+   * @example "Calling {toolName}... ~{duration}~"
+   * @example "**Searching** *{toolName}*..."
+   */
+  activeTextTemplate?: string;
+  /**
+   * Template string for the header text when a tool call is complete.
+   *
+   * **Placeholders:** `{toolName}` (tool name), `{duration}` (final elapsed time).
+   *
+   * **Inline formatting:** `~dim~`, `*italic*`, `**bold**` — same syntax as `activeTextTemplate`.
+   *
+   * When not set, falls back to the existing "Used tool for X seconds" text.
+   * @example "Finished {toolName} ~{duration}~"
+   */
+  completeTextTemplate?: string;
+  /**
+   * Primary color for shimmer-color animation mode.
+   * Defaults to the current text color.
+   */
+  loadingAnimationColor?: string;
+  /**
+   * Secondary/end color for shimmer-color animation mode.
+   * Creates a gradient sweep between `loadingAnimationColor` and this color.
+   * @default "#3b82f6"
+   */
+  loadingAnimationSecondaryColor?: string;
+  /**
+   * Duration of one full animation cycle in milliseconds.
+   * Applies to pulse, shimmer, shimmer-color, and rainbow modes.
+   * @default 2000
+   */
+  loadingAnimationDuration?: number;
 };
 
 export type AgentWidgetReasoningConfig = {
@@ -1299,6 +1401,14 @@ export type AgentWidgetReasoningConfig = {
     previewText: string;
     isActive: boolean;
     config: AgentWidgetConfig;
+    /** Static elapsed time snapshot, e.g. "2.6s". */
+    elapsed: string;
+    /**
+     * Returns a `<span>` whose text content is automatically updated every
+     * 100ms by the widget's global timer. Place it anywhere in your returned
+     * HTMLElement to get a live-ticking duration display.
+     */
+    createElapsedElement: () => HTMLElement;
   }) => HTMLElement | string | null;
   /**
    * Override the lightweight collapsed preview content shown for active reasoning rows.
@@ -1311,6 +1421,45 @@ export type AgentWidgetReasoningConfig = {
     isActive: boolean;
     config: AgentWidgetConfig;
   }) => HTMLElement | string | null;
+  /**
+   * Template string for the header text while reasoning is active (streaming).
+   *
+   * **Placeholders:** `{duration}` (live-updating elapsed time).
+   *
+   * **Inline formatting:** `~dim~`, `*italic*`, `**bold**` — parsed at render time.
+   *
+   * When not set, falls back to the default "Thinking..." text.
+   * @example "Thinking... ~{duration}~"
+   */
+  activeTextTemplate?: string;
+  /**
+   * Template string for the header text when reasoning is complete.
+   *
+   * **Placeholders:** `{duration}` (final elapsed time).
+   *
+   * **Inline formatting:** `~dim~`, `*italic*`, `**bold**` — same syntax as `activeTextTemplate`.
+   *
+   * When not set, falls back to the default "Thought for X seconds" text.
+   * @example "Thought for ~{duration}~"
+   */
+  completeTextTemplate?: string;
+  /**
+   * Primary color for shimmer-color animation mode.
+   * Defaults to the current text color.
+   */
+  loadingAnimationColor?: string;
+  /**
+   * Secondary/end color for shimmer-color animation mode.
+   * Creates a gradient sweep between `loadingAnimationColor` and this color.
+   * @default "#3b82f6"
+   */
+  loadingAnimationSecondaryColor?: string;
+  /**
+   * Duration of one full animation cycle in milliseconds.
+   * Applies to pulse, shimmer, shimmer-color, and rainbow modes.
+   * @default 2000
+   */
+  loadingAnimationDuration?: number;
 };
 
 export type AgentWidgetSuggestionChipsConfig = {

package/src/ui.scroll.test.ts

@@ -34,6 +34,16 @@ const installRafMock = () => {
   });
 
   return {
+    step(frameCount = 1) {
+      let frames = 0;
+      while (callbacks.size > 0 && frames < frameCount) {
+        const pending = [...callbacks.entries()];
+        callbacks.clear();
+        frames += 1;
+        now += 16;
+        pending.forEach(([, callback]) => callback(now));
+      }
+    },
     flush(maxFrames = 80) {
       let frames = 0;
       while (callbacks.size > 0 && frames < maxFrames) {
@@ -215,14 +225,14 @@ describe("createAgentExperience streaming scroll", () => {
 
     expect(metrics.getScrollTop()).toBe(metrics.getBottomScrollTop());
 
-    metrics.setScrollTop(metrics.getBottomScrollTop() - 3);
+    metrics.setScrollTop(metrics.getBottomScrollTop() - 6);
     scrollContainer!.dispatchEvent(new Event("scroll"));
 
     metrics.setScrollHeight(1040);
     emitStreamingMessage(controller, "Second chunk");
     raf.flush();
 
-    expect(metrics.getScrollTop()).toBe(597);
+    expect(metrics.getScrollTop()).toBe(594);
 
     controller.destroy();
   });
@@ -364,6 +374,39 @@ describe("createAgentExperience streaming scroll", () => {
     controller.destroy();
   });
 
+  it("catches up immediately when a streamed update lands far behind", () => {
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false }
+    });
+
+    const scrollContainer = mount.querySelector<HTMLElement>("#persona-scroll-container");
+    expect(scrollContainer).not.toBeNull();
+
+    const metrics = installScrollMetrics(scrollContainer!, {
+      scrollHeight: 900,
+      clientHeight: 400
+    });
+
+    emitStreamingStatus(controller);
+    emitStreamingMessage(controller, "Chunk one");
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(metrics.getBottomScrollTop());
+
+    metrics.setScrollHeight(1080);
+    emitStreamingMessage(controller, "Chunk two");
+
+    // Only run the scheduled auto-scroll frame, not the whole animation.
+    raf.step(1);
+
+    expect(metrics.getScrollTop()).toBe(metrics.getBottomScrollTop());
+
+    controller.destroy();
+  });
+
   it("lets the user break away during reasoning streaming", () => {
     const raf = installRafMock();
     const mount = createMount();

package/src/ui.ts

@@ -54,6 +54,7 @@ import { MessageTransform, MessageActionCallbacks, LoadingIndicatorRenderer } fr
 import { createStandardBubble, createTypingIndicator } from "./components/message-bubble";
 import { createReasoningBubble, reasoningExpansionState, updateReasoningBubbleUI } from "./components/reasoning-bubble";
 import { createToolBubble, toolExpansionState, updateToolBubbleUI } from "./components/tool-bubble";
+import { formatElapsedMs } from "./utils/formatting";
 import { createApprovalBubble } from "./components/approval-bubble";
 import { createSuggestions } from "./components/suggestions";
 import { EventStreamBuffer } from "./utils/event-stream-buffer";
@@ -1989,8 +1990,13 @@ export const createAgentExperience = (
   let isAutoScrolling = false;
   let hasPendingAutoScroll = false;
 
-  const USER_SCROLL_THRESHOLD = 1;
-  const BOTTOM_THRESHOLD = 8;
+  // Scroll events caused by layout, scroll anchoring, and smooth-scroll
+  // easing can easily move by a couple pixels. Keep manual wheel intent
+  // responsive, but require a slightly larger raw scroll delta before we
+  // treat a plain scroll event as the user breaking away.
+  const USER_SCROLL_THRESHOLD = 4;
+  const BOTTOM_THRESHOLD = 24;
+  const AUTO_SCROLL_SNAP_THRESHOLD = 80;
   const messageState = new Map<
     string,
     { streaming?: boolean; role: AgentWidgetMessage["role"] }
@@ -2177,6 +2183,18 @@ export const createAgentExperience = (
       return;
     }
 
+    // If the transcript has fallen noticeably behind, catch up immediately
+    // instead of easing over multiple frames. This keeps fast streaming /
+    // bursty tool and reasoning updates pinned to the bottom.
+    if (Math.abs(distance) >= AUTO_SCROLL_SNAP_THRESHOLD) {
+      cancelSmoothScroll();
+      isAutoScrolling = true;
+      element.scrollTop = target;
+      lastScrollTop = element.scrollTop;
+      isAutoScrolling = false;
+      return;
+    }
+
     // Cancel any ongoing smooth scroll animation
     cancelSmoothScroll();
 
@@ -2960,9 +2978,33 @@ export const createAgentExperience = (
     };
   }
 
+  // Global timer for live-updating tool elapsed time spans.
+  // Runs at 100ms while any [data-tool-elapsed] span exists in the message area,
+  // auto-stops when none remain. Operates on real DOM after morph, not temp elements.
+  let toolElapsedTimerId: ReturnType<typeof setInterval> | null = null;
+  const ensureToolElapsedTimer = () => {
+    if (toolElapsedTimerId != null) return;
+    toolElapsedTimerId = setInterval(() => {
+      const spans = messagesWrapper.querySelectorAll<HTMLElement>("[data-tool-elapsed]");
+      if (spans.length === 0) {
+        clearInterval(toolElapsedTimerId!);
+        toolElapsedTimerId = null;
+        return;
+      }
+      const now = Date.now();
+      spans.forEach((span) => {
+        const startedAt = Number(span.getAttribute("data-tool-elapsed"));
+        if (!startedAt) return;
+        span.textContent = formatElapsedMs(now - startedAt);
+      });
+    }, 100);
+  };
+
   session = new AgentWidgetSession(config, {
     onMessagesChanged(messages) {
       renderMessagesWithPlugins(messagesWrapper, messages, postprocess);
+      // Start elapsed timer if any active tool has a live duration span
+      ensureToolElapsedTimer();
       // Re-render suggestions to hide them after first user message
       // Pass messages directly to avoid calling session.getMessages() during construction
       if (session) {
@@ -5716,6 +5758,10 @@ export const createAgentExperience = (
       return session.submitNPSFeedback(rating, comment);
     },
     destroy() {
+      if (toolElapsedTimerId != null) {
+        clearInterval(toolElapsedTimerId);
+        toolElapsedTimerId = null;
+      }
       destroyCallbacks.forEach((cb) => cb());
       wrapper.remove();
       launcherButtonInstance?.destroy();

package/src/utils/formatting.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { createJsonStreamParser } from "./formatting";
+import { createJsonStreamParser, parseFormattedTemplate, computeReasoningElapsed } from "./formatting";
 
 describe("JSON Stream Parser", () => {
   it("should extract text field incrementally as JSON streams in", () => {
@@ -170,3 +170,101 @@ describe("JSON Stream Parser", () => {
     expect(finalResult).toBe("You're welcome! Enjoy your browsing, and I'm here if you need anything!");
   });
 });
+
+describe("parseFormattedTemplate", () => {
+  it("returns plain text segments when no formatting markers are present", () => {
+    const segments = parseFormattedTemplate("Calling {toolName}...", "Get Weather");
+    expect(segments).toEqual([
+      { text: "Calling Get Weather...", styles: [] },
+    ]);
+  });
+
+  it("resolves {toolName} placeholder", () => {
+    const segments = parseFormattedTemplate("{toolName} running", "Search Catalog");
+    expect(segments).toEqual([
+      { text: "Search Catalog running", styles: [] },
+    ]);
+  });
+
+  it("parses ~dim~ markers", () => {
+    const segments = parseFormattedTemplate("Finished {toolName} ~{duration}~", "Get Weather");
+    expect(segments).toEqual([
+      { text: "Finished Get Weather ", styles: [] },
+      { text: "{duration}", styles: ["dim"], isDuration: true },
+    ]);
+  });
+
+  it("parses *italic* markers", () => {
+    const segments = parseFormattedTemplate("*{toolName}* completed", "Search");
+    expect(segments).toEqual([
+      { text: "Search", styles: ["italic"] },
+      { text: " completed", styles: [] },
+    ]);
+  });
+
+  it("parses **bold** markers", () => {
+    const segments = parseFormattedTemplate("**Calling** {toolName}", "Lookup");
+    expect(segments).toEqual([
+      { text: "Calling", styles: ["bold"] },
+      { text: " Lookup", styles: [] },
+    ]);
+  });
+
+  it("handles multiple formatting markers in one template", () => {
+    const segments = parseFormattedTemplate("**Done** *{toolName}* ~{duration}~", "API");
+    expect(segments).toEqual([
+      { text: "Done", styles: ["bold"] },
+      { text: " ", styles: [] },
+      { text: "API", styles: ["italic"] },
+      { text: " ", styles: [] },
+      { text: "{duration}", styles: ["dim"], isDuration: true },
+    ]);
+  });
+
+  it("handles {duration} without formatting markers", () => {
+    const segments = parseFormattedTemplate("Ran for {duration}", "Tool");
+    expect(segments).toEqual([
+      { text: "Ran for ", styles: [] },
+      { text: "{duration}", styles: [], isDuration: true },
+    ]);
+  });
+
+  it("handles template with no placeholders", () => {
+    const segments = parseFormattedTemplate("Running...", "Ignored");
+    expect(segments).toEqual([
+      { text: "Running...", styles: [] },
+    ]);
+  });
+
+  it("handles empty tool name fallback in template", () => {
+    const segments = parseFormattedTemplate("{toolName}", "  ");
+    // toolName is resolved before parsing, so whitespace stays
+    expect(segments).toEqual([
+      { text: "  ", styles: [] },
+    ]);
+  });
+});
+
+describe("computeReasoningElapsed", () => {
+  it("uses durationMs when provided", () => {
+    const result = computeReasoningElapsed({
+      id: "r1", status: "complete", chunks: [], durationMs: 2600,
+    });
+    expect(result).toBe("2.6s");
+  });
+
+  it("computes from startedAt/completedAt when durationMs is undefined", () => {
+    const result = computeReasoningElapsed({
+      id: "r2", status: "complete", chunks: [],
+      startedAt: 1000, completedAt: 16000,
+    });
+    expect(result).toBe("15s");
+  });
+
+  it("returns <0.1s for very short durations", () => {
+    const result = computeReasoningElapsed({
+      id: "r3", status: "complete", chunks: [], durationMs: 50,
+    });
+    expect(result).toBe("<0.1s");
+  });
+});