@runtypelabs/persona 3.11.0 → 3.12.0

package/src/theme-reference.ts

@@ -218,9 +218,12 @@ export const THEME_TOKEN_DOCS = {
         '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:
@@ -285,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, expandable, loadingAnimation), reasoningDisplay (activePreview, activeMinHeight, previewMaxLines, expandable), 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

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

package/src/types.ts

@@ -656,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 = {
@@ -1390,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.
@@ -1402,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/utils/formatting.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { createJsonStreamParser, parseFormattedTemplate } from "./formatting";
+import { createJsonStreamParser, parseFormattedTemplate, computeReasoningElapsed } from "./formatting";
 
 describe("JSON Stream Parser", () => {
   it("should extract text field incrementally as JSON streams in", () => {
@@ -244,3 +244,27 @@ describe("parseFormattedTemplate", () => {
     ]);
   });
 });
+
+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");
+  });
+});

package/src/utils/formatting.ts

@@ -115,6 +115,21 @@ export const computeToolElapsed = (tool: AgentWidgetToolCall): string => {
   return formatElapsedMs(durationMs);
 };
 
+/**
+ * Computes the current elapsed time string for a reasoning block.
+ */
+export const computeReasoningElapsed = (reasoning: AgentWidgetReasoning): string => {
+  const durationMs =
+    reasoning.durationMs !== undefined
+      ? reasoning.durationMs
+      : Math.max(
+          0,
+          (reasoning.completedAt ?? Date.now()) -
+            (reasoning.startedAt ?? reasoning.completedAt ?? Date.now())
+        );
+  return formatElapsedMs(durationMs);
+};
+
 /**
  * Resolves a text template with tool call placeholders.
  * Supported placeholders: {toolName}, {duration}

package/src/utils/message-fingerprint.test.ts

@@ -90,6 +90,18 @@ describe("computeMessageFingerprint", () => {
     expect(fp1).not.toBe(fp2);
   });
 
+  it("changes when toolCall name changes", () => {
+    const fp1 = computeMessageFingerprint(
+      makeMessage({ toolCall: { status: "running" } }),
+      0
+    );
+    const fp2 = computeMessageFingerprint(
+      makeMessage({ toolCall: { status: "running", name: "UCP Search Catalog" } }),
+      0
+    );
+    expect(fp1).not.toBe(fp2);
+  });
+
   it("changes when toolCall chunks change", () => {
     const fp1 = computeMessageFingerprint(
       makeMessage({ toolCall: { status: "running", chunks: ["Loaded tools"] } }),

package/src/utils/message-fingerprint.ts

@@ -53,6 +53,7 @@ export function computeMessageFingerprint(
     message.llmContent?.length ?? 0,
     message.approval?.status ?? "",
     message.toolCall?.status ?? "",
+    message.toolCall?.name ?? "",
     message.toolCall?.chunks?.length ?? 0,
     message.toolCall?.chunks?.[message.toolCall.chunks.length - 1]?.slice(-32) ?? "",
     typeof message.toolCall?.args === "string"

package/src/utils/morph.test.ts

@@ -0,0 +1,86 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from "vitest";
+import { morphMessages } from "./morph";
+
+function makeContainer(html: string): HTMLElement {
+  const div = document.createElement("div");
+  div.innerHTML = html;
+  return div;
+}
+
+function makeNewContent(html: string): HTMLElement {
+  const div = document.createElement("div");
+  div.innerHTML = html;
+  return div;
+}
+
+describe("morphMessages", () => {
+  describe("data-preserve-animation", () => {
+    it("preserves animated element when old and new both have data-preserve-animation with same text", () => {
+      const container = makeContainer(
+        '<span data-preserve-animation="true">Calling tool... 0.1s</span>'
+      );
+      const oldSpan = container.querySelector("span")!;
+
+      morphMessages(
+        container,
+        makeNewContent(
+          '<span data-preserve-animation="true">Calling tool... 0.1s</span>'
+        )
+      );
+
+      expect(container.querySelector("span")).toBe(oldSpan);
+    });
+
+    it("allows morph when new node drops data-preserve-animation (tool completed)", () => {
+      const container = makeContainer(
+        '<span data-preserve-animation="true">Calling tool... 0.5s</span>'
+      );
+
+      morphMessages(
+        container,
+        makeNewContent("<span>Finished tool 0.5s</span>")
+      );
+
+      expect(container.querySelector("span")!.textContent).toBe(
+        "Finished tool 0.5s"
+      );
+      expect(
+        container.querySelector("span")!.hasAttribute("data-preserve-animation")
+      ).toBe(false);
+    });
+
+    it("allows morph when text content changes despite both having data-preserve-animation", () => {
+      const container = makeContainer(
+        '<span data-preserve-animation="true">Calling tool... 0.1s</span>'
+      );
+
+      morphMessages(
+        container,
+        makeNewContent(
+          '<span data-preserve-animation="true">Calling UCP Search Catalog... 0.2s</span>'
+        )
+      );
+
+      expect(container.querySelector("span")!.textContent).toBe(
+        "Calling UCP Search Catalog... 0.2s"
+      );
+    });
+
+    it("does not preserve when preserveTypingAnimation is false", () => {
+      const container = makeContainer(
+        '<span data-preserve-animation="true">Old text</span>'
+      );
+
+      morphMessages(
+        container,
+        makeNewContent(
+          '<span data-preserve-animation="true">New text</span>'
+        ),
+        { preserveTypingAnimation: false }
+      );
+
+      expect(container.querySelector("span")!.textContent).toBe("New text");
+    });
+  });
+});

package/src/utils/morph.ts

@@ -35,6 +35,14 @@ export const morphMessages = (
             if (newNode instanceof HTMLElement && !newNode.hasAttribute("data-preserve-animation")) {
               return;
             }
+            // Allow morph when content has meaningfully changed (e.g. tool name arrived)
+            if (newNode instanceof HTMLElement && newNode.hasAttribute("data-preserve-animation")) {
+              const oldText = oldNode.textContent ?? "";
+              const newText = newNode.textContent ?? "";
+              if (oldText !== newText) {
+                return;
+              }
+            }
             return false;
           }
         }