@runtypelabs/persona 3.11.0 → 3.13.0

package/src/install.ts

@@ -22,6 +22,10 @@ interface SiteAgentInstallConfig {
   previewQueryParam?: string;
   // Shadow DOM option (defaults to false for better CSS compatibility)
   useShadowDom?: boolean;
+  // Expose the widget handle on window[windowKey] for programmatic access
+  windowKey?: string;
+  // Called when the widget is initialized and ready for interaction
+  onReady?: (handle: any) => void;
 }
 
 declare global {
@@ -55,7 +59,10 @@ declare global {
     const configJson = script.getAttribute('data-config');
     if (configJson) {
       try {
-        const parsedConfig = JSON.parse(configJson);
+        // HTML attributes preserve literal newlines/tabs which are invalid
+        // control characters inside JSON string literals — strip them.
+        const normalizedJson = configJson.replace(/[\r\n]+\s*/g, '');
+        const parsedConfig = JSON.parse(normalizedJson);
         // If it has nested 'config' property, use it; otherwise treat as widget config
         if (parsedConfig.config) {
           // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -270,12 +277,16 @@ declare global {
     }
 
     try {
-      window.AgentWidget.initAgentWidget({
+      const handle = window.AgentWidget.initAgentWidget({
         target,
         config: widgetConfig,
         // Explicitly disable shadow DOM for better CSS compatibility with host page
-        useShadowDom: config.useShadowDom ?? false
+        useShadowDom: config.useShadowDom ?? false,
+        windowKey: config.windowKey
       });
+
+      config.onReady?.(handle);
+      window.dispatchEvent(new CustomEvent("persona:ready", { detail: handle }));
     } catch (error) {
       console.error("Failed to initialize AgentWidget:", error);
     }

package/src/runtime/init.test.ts

@@ -85,6 +85,138 @@ function createMockController(config?: { launcher?: { enabled?: boolean; autoExp
   };
 }
 
+describe("initAgentWidget windowKey and ready notifications", () => {
+  beforeEach(() => {
+    document.body.innerHTML = "";
+    createAgentExperienceMock.mockReset();
+    createAgentExperienceMock.mockImplementation((_mount, config) => createMockController(config));
+  });
+
+  it("assigns the handle to window[windowKey] when windowKey is provided", async () => {
+    const { initAgentWidget } = await import("./init");
+    document.body.innerHTML = `<div id="target"></div>`;
+
+    const handle = initAgentWidget({
+      target: "#target",
+      windowKey: "testWidget",
+      config: { launcher: { enabled: false } },
+    });
+
+    expect((window as any).testWidget).toBe(handle);
+
+    handle.destroy();
+    expect((window as any).testWidget).toBeUndefined();
+  });
+
+  it("does not set a window key when windowKey is omitted", async () => {
+    const { initAgentWidget } = await import("./init");
+    document.body.innerHTML = `<div id="target"></div>`;
+
+    const handle = initAgentWidget({
+      target: "#target",
+      config: { launcher: { enabled: false } },
+    });
+
+    // No arbitrary key should have been set
+    expect((window as any).testWidget2).toBeUndefined();
+    handle.destroy();
+  });
+
+  it("calls onReady after initialization", async () => {
+    const { initAgentWidget } = await import("./init");
+    document.body.innerHTML = `<div id="target"></div>`;
+
+    const onReady = vi.fn();
+    const handle = initAgentWidget({
+      target: "#target",
+      onReady,
+      config: { launcher: { enabled: false } },
+    });
+
+    expect(onReady).toHaveBeenCalledOnce();
+    handle.destroy();
+  });
+
+  it("the window key handle proxies controller methods", async () => {
+    const { initAgentWidget } = await import("./init");
+    document.body.innerHTML = `<div id="target"></div>`;
+
+    initAgentWidget({
+      target: "#target",
+      windowKey: "proxyTest",
+      config: { launcher: { enabled: false } },
+    });
+
+    const proxy = (window as any).proxyTest;
+    expect(proxy).toBeDefined();
+    expect(typeof proxy.open).toBe("function");
+    expect(typeof proxy.close).toBe("function");
+    expect(typeof proxy.on).toBe("function");
+    expect(typeof proxy.destroy).toBe("function");
+    expect(typeof proxy.getState).toBe("function");
+
+    proxy.destroy();
+  });
+});
+
+describe("install script onReady and persona:ready event", () => {
+  beforeEach(() => {
+    document.body.innerHTML = "";
+    createAgentExperienceMock.mockReset();
+    createAgentExperienceMock.mockImplementation((_mount, config) => createMockController(config));
+  });
+
+  it("persona:ready event fires with the handle as detail", async () => {
+    const { initAgentWidget } = await import("./init");
+    document.body.innerHTML = `<div id="target"></div>`;
+
+    const eventPromise = new Promise<any>((resolve) => {
+      window.addEventListener("persona:ready", (e) => {
+        resolve((e as CustomEvent).detail);
+      }, { once: true });
+    });
+
+    const handle = initAgentWidget({
+      target: "#target",
+      windowKey: "eventTest",
+      config: { launcher: { enabled: false } },
+    });
+
+    // Simulate what install.ts does after initAgentWidget returns
+    window.dispatchEvent(new CustomEvent("persona:ready", { detail: handle }));
+
+    const detail = await eventPromise;
+    expect(detail).toBe(handle);
+    expect(typeof detail.open).toBe("function");
+    expect(typeof detail.on).toBe("function");
+
+    handle.destroy();
+  });
+
+  it("persona:ready event listener set up before init receives the handle", async () => {
+    const { initAgentWidget } = await import("./init");
+    document.body.innerHTML = `<div id="target"></div>`;
+
+    const received: any[] = [];
+    window.addEventListener("persona:ready", (e) => {
+      received.push((e as CustomEvent).detail);
+    }, { once: true });
+
+    const handle = initAgentWidget({
+      target: "#target",
+      config: { launcher: { enabled: false } },
+    });
+
+    // Simulate install.ts dispatching the event
+    window.dispatchEvent(new CustomEvent("persona:ready", { detail: handle }));
+
+    expect(received).toHaveLength(1);
+    expect(received[0]).toBe(handle);
+
+    handle.destroy();
+  });
+});
+
 describe("initAgentWidget docked mode", () => {
   beforeEach(() => {
     document.body.innerHTML = "";

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/code-generators.test.ts

@@ -620,3 +620,60 @@ describe("CDN Version", () => {
     expect(VERSION).toMatch(/^\d+\.\d+\.\d+/);
   });
 });
+
+// =============================================================================
+// windowKey option
+// =============================================================================
+
+describe("windowKey option", () => {
+  it("script-installer with windowKey nests config and includes windowKey in JSON", () => {
+    const code = generateCodeSnippet(minimalConfig, "script-installer", { windowKey: "myWidget" });
+
+    // Parse the data-config JSON from the output
+    const match = code.match(/data-config='([^']*)'/);
+    expect(match).not.toBeNull();
+    const parsed = JSON.parse(match![1]);
+
+    expect(parsed.windowKey).toBe("myWidget");
+    expect(parsed.config).toBeDefined();
+    expect(parsed.config.apiUrl).toBe(minimalConfig.apiUrl);
+  });
+
+  it("script-installer without windowKey uses flat config (no nesting)", () => {
+    const code = generateCodeSnippet(minimalConfig, "script-installer");
+
+    const match = code.match(/data-config='([^']*)'/);
+    expect(match).not.toBeNull();
+    const parsed = JSON.parse(match![1]);
+
+    expect(parsed.windowKey).toBeUndefined();
+    expect(parsed.config).toBeUndefined();
+    expect(parsed.apiUrl).toBe(minimalConfig.apiUrl);
+  });
+
+  it("script-manual with windowKey includes windowKey and captures handle", () => {
+    const code = generateCodeSnippet(minimalConfig, "script-manual", { windowKey: "myWidget" });
+
+    expect(code).toContain("var handle = window.AgentWidget.initAgentWidget(");
+    expect(code).toContain("windowKey: 'myWidget'");
+  });
+
+  it("script-manual without windowKey still captures handle but omits windowKey", () => {
+    const code = generateCodeSnippet(minimalConfig, "script-manual");
+
+    expect(code).toContain("var handle = window.AgentWidget.initAgentWidget(");
+    expect(code).not.toContain("windowKey");
+  });
+
+  it("script-advanced with windowKey includes windowKey in initAgentWidget call", () => {
+    const code = generateCodeSnippet(minimalConfig, "script-advanced", { windowKey: "myWidget" });
+
+    expect(code).toContain("windowKey: 'myWidget'");
+  });
+
+  it("script-advanced without windowKey omits windowKey", () => {
+    const code = generateCodeSnippet(minimalConfig, "script-advanced");
+
+    expect(code).not.toContain("windowKey");
+  });
+});

package/src/utils/code-generators.ts

@@ -134,6 +134,13 @@ export type CodeGeneratorOptions = {
    * @default true
    */
   includeHookComments?: boolean;
+
+  /**
+   * If provided, emits `windowKey` in the generated `initAgentWidget()` call
+   * so the widget handle is stored on `window[windowKey]`.
+   * Only affects script formats (script-installer, script-manual, script-advanced).
+   */
+  windowKey?: string;
 };
 
 // Internal type for normalized hooks (always strings)
@@ -551,7 +558,7 @@ export function generateCodeSnippet(
   if (format === "esm") {
     return generateESMCode(cleanConfig, normalizedOptions);
   } else if (format === "script-installer") {
-    return generateScriptInstallerCode(cleanConfig);
+    return generateScriptInstallerCode(cleanConfig, normalizedOptions);
   } else if (format === "script-advanced") {
     return generateScriptAdvancedCode(cleanConfig, normalizedOptions);
   } else if (format === "react-component") {
@@ -1346,12 +1353,18 @@ function buildSerializableConfig(config: any): Record<string, any> {
   return serializableConfig;
 }
 
-function generateScriptInstallerCode(config: any): string {
+function generateScriptInstallerCode(config: any, options?: CodeGeneratorOptions): string {
   const serializableConfig = buildSerializableConfig(config);
-  
+
+  // When windowKey is provided, nest the widget config under `config` so the
+  // install script's parsedConfig.config detection picks it up alongside windowKey.
+  const payload = options?.windowKey
+    ? { config: serializableConfig, windowKey: options.windowKey }
+    : serializableConfig;
+
   // Escape single quotes in JSON for HTML attribute
-  const configJson = JSON.stringify(serializableConfig, null, 0).replace(/'/g, "&#39;");
-  
+  const configJson = JSON.stringify(payload, null, 0).replace(/'/g, "&#39;");
+
   return `<script src="https://cdn.jsdelivr.net/npm/@runtypelabs/persona@${VERSION}/dist/install.global.js" data-config='${configJson}'></script>`;
 }
 
@@ -1369,8 +1382,9 @@ function generateScriptManualCode(config: any, options?: CodeGeneratorOptions):
     "",
     "<!-- Initialize widget -->",
     "<script>",
-    "  window.AgentWidget.initAgentWidget({",
+    "  var handle = window.AgentWidget.initAgentWidget({",
     "    target: 'body',",
+    ...(options?.windowKey ? [`    windowKey: '${options.windowKey}',`] : []),
     "    config: {"
   ];
 
@@ -1723,6 +1737,7 @@ function generateScriptAdvancedCode(config: any, options?: CodeGeneratorOptions)
     "    var handle = agentWidget.initAgentWidget({",
     "      target: 'body',",
     "      useShadowDom: false,",
+    ...(options?.windowKey ? [`      windowKey: '${options.windowKey}',`] : []),
     "      config: widgetConfig",
     "    });",
     "",

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;
           }
         }