@runtypelabs/persona 3.10.0 → 3.11.0

package/src/theme-reference.ts

@@ -210,9 +210,12 @@ 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.',
@@ -282,7 +285,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), 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",
     });
   });
 

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 = {
@@ -1234,22 +1259,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 +1305,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 +1335,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 = {
@@ -2081,6 +2172,35 @@ export type AgentWidgetAttachmentsConfig = {
    * Callback when a file is rejected (wrong type or too large).
    */
   onFileRejected?: (file: File, reason: 'type' | 'size' | 'count') => void;
+  /**
+   * Customize the drag-and-drop overlay that appears when files are dragged over the widget.
+   */
+  dropOverlay?: {
+    /** Background color/value of the overlay. @default 'rgba(59, 130, 246, 0.08)' */
+    background?: string;
+    /** Backdrop blur applied behind the overlay (CSS value). @default '8px' */
+    backdropBlur?: string;
+    /** Border style shown during drag. @default '2px dashed rgba(59, 130, 246, 0.4)' */
+    border?: string;
+    /** Border radius of the overlay. @default 'inherit' */
+    borderRadius?: string;
+    /** Inset/margin pulling the overlay away from the container edges (CSS value). @default '0' */
+    inset?: string;
+    /** Lucide icon name displayed in the center. @default 'upload' */
+    iconName?: string;
+    /** Icon size (CSS value). @default '48px' */
+    iconSize?: string;
+    /** Icon stroke color. @default 'rgba(59, 130, 246, 0.6)' */
+    iconColor?: string;
+    /** Icon stroke width. @default 0.5 */
+    iconStrokeWidth?: number;
+    /** Optional label text shown below the icon. */
+    label?: string;
+    /** Label font size. @default '0.875rem' */
+    labelSize?: string;
+    /** Label color. @default 'rgba(59, 130, 246, 0.8)' */
+    labelColor?: string;
+  };
 };
 
 /**

package/src/ui.attachments-drop.test.ts

@@ -0,0 +1,188 @@
+// @vitest-environment jsdom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createAgentExperience } from "./ui";
+import { AttachmentManager } from "./utils/attachment-manager";
+
+const createMount = () => {
+  const mount = document.createElement("div");
+  document.body.appendChild(mount);
+  return mount;
+};
+
+/** jsdom does not expose `DataTransfer`; real browsers set `dropEffect` on dragover. */
+function createFileDataTransfer(files: File[]): DataTransfer {
+  const list: File[] = [...files];
+  const fileList = list as unknown as FileList;
+  return {
+    dropEffect: "none",
+    effectAllowed: "all",
+    files: fileList,
+    items: {
+      add: () => {},
+      clear: () => {},
+      remove: () => {}
+    } as unknown as DataTransferItemList,
+    types: files.length > 0 ? ["Files"] : [],
+    clearData: () => {},
+    getData: () => "",
+    setData: () => {},
+    setDragImage: () => {}
+  } as unknown as DataTransfer;
+}
+
+function createDragEvent(type: string, dataTransfer: DataTransfer): DragEvent {
+  const ev = new Event(type, { bubbles: true, cancelable: true }) as unknown as DragEvent;
+  Object.defineProperty(ev, "dataTransfer", { value: dataTransfer, enumerable: true });
+  return ev;
+}
+
+describe("createAgentExperience attachment file drop", () => {
+  beforeEach(() => {
+    vi.stubGlobal("requestAnimationFrame", (cb: (time: number) => void) => {
+      cb(0);
+      return 1;
+    });
+    vi.stubGlobal("cancelAnimationFrame", () => {});
+    window.scrollTo = vi.fn();
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  it("calls AttachmentManager.handleFiles when files are dropped on the mount", () => {
+    const handleFilesSpy = vi.spyOn(AttachmentManager.prototype, "handleFiles");
+
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      attachments: { enabled: true, maxFiles: 4 },
+    });
+
+    const file = new File(["x"], "test.png", { type: "image/png" });
+    const dt = createFileDataTransfer([file]);
+
+    // dragover/drop are on mount so the browser default is suppressed everywhere
+    const dragOver = createDragEvent("dragover", dt);
+    mount.dispatchEvent(dragOver);
+    expect(dragOver.defaultPrevented).toBe(true);
+    expect(dt.dropEffect).toBe("copy");
+
+    const drop = createDragEvent("drop", dt);
+    mount.dispatchEvent(drop);
+    expect(drop.defaultPrevented).toBe(true);
+
+    expect(handleFilesSpy).toHaveBeenCalledTimes(1);
+    const passed = handleFilesSpy.mock.calls[0]?.[0] as File[];
+    expect(passed).toHaveLength(1);
+    expect(passed[0]?.name).toBe("test.png");
+
+    handleFilesSpy.mockRestore();
+    controller.destroy();
+  });
+
+  it("shows drop-active highlight on container during dragenter", () => {
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      attachments: { enabled: true, maxFiles: 4 },
+    });
+
+    const container = mount.querySelector(".persona-widget-container")!;
+    const file = new File(["x"], "test.png", { type: "image/png" });
+    const dt = createFileDataTransfer([file]);
+
+    container.dispatchEvent(createDragEvent("dragenter", dt));
+    expect(container.classList.contains("persona-attachment-drop-active")).toBe(true);
+
+    container.dispatchEvent(createDragEvent("dragleave", dt));
+    expect(container.classList.contains("persona-attachment-drop-active")).toBe(false);
+
+    controller.destroy();
+  });
+
+  it("renders drop overlay with icon inside container", () => {
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      attachments: { enabled: true, maxFiles: 4 },
+    });
+
+    const overlay = mount.querySelector(".persona-attachment-drop-overlay");
+    expect(overlay).not.toBeNull();
+    expect(overlay!.querySelector("svg")).not.toBeNull();
+
+    controller.destroy();
+  });
+
+  it("applies custom dropOverlay config as CSS variables", () => {
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      attachments: {
+        enabled: true,
+        maxFiles: 4,
+        dropOverlay: {
+          background: "rgba(255, 0, 0, 0.1)",
+          backdropBlur: "12px",
+          border: "2px solid red",
+          inset: "8px",
+          iconName: "image-plus",
+          label: "Drop here",
+        },
+      },
+    });
+
+    const overlay = mount.querySelector<HTMLElement>(".persona-attachment-drop-overlay")!;
+    expect(overlay).not.toBeNull();
+    expect(overlay.style.getPropertyValue("--persona-drop-overlay-bg")).toBe("rgba(255, 0, 0, 0.1)");
+    expect(overlay.style.getPropertyValue("--persona-drop-overlay-blur")).toBe("12px");
+    expect(overlay.style.getPropertyValue("--persona-drop-overlay-border")).toBe("2px solid red");
+    expect(overlay.style.getPropertyValue("--persona-drop-overlay-inset")).toBe("8px");
+
+    const label = overlay.querySelector(".persona-drop-overlay-label");
+    expect(label).not.toBeNull();
+    expect(label!.textContent).toBe("Drop here");
+
+    controller.destroy();
+  });
+
+  it("does not render drop overlay when attachments are disabled", () => {
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      attachments: { enabled: false },
+    });
+
+    const overlay = mount.querySelector(".persona-attachment-drop-overlay");
+    expect(overlay).toBeNull();
+
+    controller.destroy();
+  });
+
+  it("does not prevent dragover when attachments are disabled", () => {
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      attachments: { enabled: false },
+    });
+
+    const file = new File(["x"], "test.png", { type: "image/png" });
+    const dt = createFileDataTransfer([file]);
+
+    const dragOver = createDragEvent("dragover", dt);
+    mount.dispatchEvent(dragOver);
+    expect(dragOver.defaultPrevented).toBe(false);
+
+    controller.destroy();
+  });
+});

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();
@@ -472,6 +515,52 @@ describe("createAgentExperience streaming scroll", () => {
     controller.destroy();
   });
 
+  it("ignores layout-driven scroll events before a scheduled auto-scroll starts", () => {
+    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: 960,
+      clientHeight: 400,
+    });
+
+    emitStreamingStatus(controller);
+    emitToolMessage(controller, { id: "tool-1", chunks: ["Loaded tools"] });
+    emitToolMessage(controller, { id: "tool-2", chunks: ["Fetched docs"] });
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(metrics.getBottomScrollTop());
+
+    metrics.setScrollHeight(1035);
+    emitToolMessage(controller, {
+      id: "tool-3",
+      chunks: ["Compared layouts and noted launcher sizing"],
+    });
+
+    // Simulate the browser emitting a scroll event caused by layout/scroll
+    // anchoring before the scheduled auto-scroll rAF has started.
+    metrics.setScrollTop(metrics.getScrollTop() - 2);
+    scrollContainer!.dispatchEvent(new Event("scroll"));
+
+    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();