@runtypelabs/persona 3.10.0 → 3.11.0

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";
@@ -147,6 +148,19 @@ function getClipboardImageFiles(clipboardData: DataTransfer | null): File[] {
   return imageFiles;
 }
 
+function dataTransferHasFiles(
+  dataTransfer: DataTransfer | null
+): dataTransfer is DataTransfer {
+  if (!dataTransfer) return false;
+  const types = dataTransfer.types;
+  if (!types) return false;
+  // Real browsers return DOMStringList which has .contains(); test polyfills use plain arrays.
+  if (typeof (types as unknown as { contains?: unknown }).contains === "function") {
+    return (types as unknown as DOMStringList).contains("Files");
+  }
+  return Array.from(types).includes("Files");
+}
+
 // ============================================================================
 // PERSIST STATE HELPERS
 // ============================================================================
@@ -389,11 +403,43 @@ const buildPostprocessor = (
   };
 };
 
+function buildDropOverlay(
+  dropCfg?: NonNullable<AgentWidgetConfig["attachments"]>["dropOverlay"]
+): HTMLElement {
+  const overlay = createElement("div", "persona-attachment-drop-overlay");
+  if (dropCfg?.background) overlay.style.setProperty("--persona-drop-overlay-bg", dropCfg.background);
+  if (dropCfg?.backdropBlur !== undefined) overlay.style.setProperty("--persona-drop-overlay-blur", dropCfg.backdropBlur);
+  if (dropCfg?.border) overlay.style.setProperty("--persona-drop-overlay-border", dropCfg.border);
+  if (dropCfg?.borderRadius) overlay.style.setProperty("--persona-drop-overlay-radius", dropCfg.borderRadius);
+  if (dropCfg?.inset) overlay.style.setProperty("--persona-drop-overlay-inset", dropCfg.inset);
+  if (dropCfg?.labelSize) overlay.style.setProperty("--persona-drop-overlay-label-size", dropCfg.labelSize);
+  if (dropCfg?.labelColor) overlay.style.setProperty("--persona-drop-overlay-label-color", dropCfg.labelColor);
+
+  const iconName = dropCfg?.iconName ?? "upload";
+  const iconSize = dropCfg?.iconSize ?? "48px";
+  const iconColor = dropCfg?.iconColor ?? "rgba(59, 130, 246, 0.6)";
+  const iconStrokeWidth = dropCfg?.iconStrokeWidth ?? 0.5;
+  const iconSvg = renderLucideIcon(iconName, iconSize, iconColor, iconStrokeWidth);
+  if (iconSvg) overlay.appendChild(iconSvg);
+
+  if (dropCfg?.label) {
+    const labelEl = createElement("span", "persona-drop-overlay-label");
+    labelEl.textContent = dropCfg.label;
+    overlay.appendChild(labelEl);
+  }
+  return overlay;
+}
+
 export const createAgentExperience = (
   mount: HTMLElement,
   initialConfig?: AgentWidgetConfig,
   runtimeOptions?: { debugTools?: boolean }
 ): Controller => {
+  if (mount == null) {
+    throw new Error(
+      "createAgentExperience: mount must be a non-null HTMLElement (e.g. pass document.getElementById(\"my-root\") after the node exists)."
+    );
+  }
   // Preserve original mount id as data attribute for window event instance scoping
   if (mount.id && !mount.getAttribute("data-persona-instance")) {
     mount.setAttribute("data-persona-instance", mount.id);
@@ -870,8 +916,21 @@ export const createAgentExperience = (
         return composerElements.footer;
       },
       onSubmit: (text: string) => {
-        if (session && !session.isStreaming()) {
-          session.sendMessage(text);
+        if (!session || session.isStreaming()) return;
+        const value = text.trim();
+        const hasAttachments = attachmentManager?.hasAttachments() ?? false;
+        if (!value && !hasAttachments) return;
+        let contentParts: ContentPart[] | undefined;
+        if (hasAttachments) {
+          contentParts = [];
+          contentParts.push(...attachmentManager!.getContentParts());
+          if (value) {
+            contentParts.push(createTextPart(value));
+          }
+        }
+        session.sendMessage(value, { contentParts });
+        if (hasAttachments) {
+          attachmentManager!.clearAttachments();
         }
       },
       streaming: false,
@@ -959,6 +1018,10 @@ export const createAgentExperience = (
       attachmentManager?.handleFileSelect(target.files);
       target.value = "";
     });
+
+    const dropCfg = config.attachments.dropOverlay;
+    const overlay = buildDropOverlay(dropCfg);
+    container.appendChild(overlay);
   }
 
   // Slot system: allow custom content injection into specific regions
@@ -1925,9 +1988,15 @@ export const createAgentExperience = (
   let lastScrollTop = 0;
   let scrollRAF: number | null = null;
   let isAutoScrolling = false;
-
-  const USER_SCROLL_THRESHOLD = 1;
-  const BOTTOM_THRESHOLD = 8;
+  let hasPendingAutoScroll = false;
+
+  // 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"] }
@@ -2041,6 +2110,7 @@ export const createAgentExperience = (
       cancelAnimationFrame(scrollRAF);
       scrollRAF = null;
     }
+    hasPendingAutoScroll = false;
     cancelSmoothScroll();
   };
 
@@ -2076,10 +2146,25 @@ export const createAgentExperience = (
 
     if (!force && !isStreaming) return;
 
-    cancelAutoScroll();
+    // Only cancel the pending schedule rAF — keep the ongoing smooth scroll
+    // animation alive so isAutoScrolling stays true.  This prevents scroll
+    // events fired by DOM morphing (between cancel and the next rAF) from
+    // being misinterpreted as user-initiated upward scrolls that would
+    // permanently pause auto-follow during streaming.
+    // smoothScrollToBottom() already calls cancelSmoothScroll() internally
+    // before starting its new animation.
+    if (scrollRAF !== null) {
+      cancelAnimationFrame(scrollRAF);
+      scrollRAF = null;
+    }
 
+    // Treat the render -> next-rAF window as programmatic scrolling too.
+    // This prevents layout/scroll-anchoring scroll events fired before the
+    // actual smooth scroll starts from being misread as user intent.
+    hasPendingAutoScroll = true;
     scrollRAF = requestAnimationFrame(() => {
       scrollRAF = null;
+      hasPendingAutoScroll = false;
       if (!autoFollow.isFollowing()) return;
       smoothScrollToBottom(getScrollableContainer(), force ? 220 : 140);
     });
@@ -2098,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();
 
@@ -2881,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) {
@@ -3776,7 +3897,7 @@ export const createAgentExperience = (
       lastScrollTop,
       nearBottom: isElementNearBottom(body, BOTTOM_THRESHOLD),
       userScrollThreshold: USER_SCROLL_THRESHOLD,
-      isAutoScrolling,
+      isAutoScrolling: isAutoScrolling || hasPendingAutoScroll,
       pauseOnUpwardScroll: true,
       pauseWhenAwayFromBottom: false,
       resumeRequiresDownwardScroll: true
@@ -3915,6 +4036,78 @@ export const createAgentExperience = (
   textarea?.addEventListener("keydown", handleInputEnter);
   textarea?.addEventListener("paste", handleInputPaste);
 
+  const ATTACHMENT_DROP_ACTIVE_CLASS = "persona-attachment-drop-active";
+  let attachmentFileDragDepth = 0;
+
+  const clearAttachmentDropVisual = () => {
+    attachmentFileDragDepth = 0;
+    container.classList.remove(ATTACHMENT_DROP_ACTIVE_CLASS);
+  };
+
+  const attachmentDropHandlingActive = (): boolean =>
+    config.attachments?.enabled === true && attachmentManager !== null;
+
+  // Visual highlight tracked on `container` (the chat column).
+  const handleAttachmentDragEnterCapture = (e: DragEvent) => {
+    if (!dataTransferHasFiles(e.dataTransfer) || !attachmentDropHandlingActive()) return;
+    attachmentFileDragDepth++;
+    if (attachmentFileDragDepth === 1) {
+      container.classList.add(ATTACHMENT_DROP_ACTIVE_CLASS);
+    }
+  };
+
+  const handleAttachmentDragLeaveCapture = (e: DragEvent) => {
+    if (!dataTransferHasFiles(e.dataTransfer) || !attachmentDropHandlingActive()) return;
+    attachmentFileDragDepth--;
+    if (attachmentFileDragDepth <= 0) {
+      clearAttachmentDropVisual();
+    }
+  };
+
+  // dragover + drop registered on `mount` so the browser default (open file)
+  // is suppressed across the entire widget surface (artifact pane, gaps, etc.).
+  const handleAttachmentDragOverCapture = (e: DragEvent) => {
+    if (!dataTransferHasFiles(e.dataTransfer) || !attachmentDropHandlingActive()) return;
+    e.preventDefault();
+    e.dataTransfer.dropEffect = "copy";
+  };
+
+  const handleAttachmentDropCapture = (e: DragEvent) => {
+    if (!dataTransferHasFiles(e.dataTransfer) || !attachmentDropHandlingActive()) return;
+    e.preventDefault();
+    e.stopPropagation();
+    clearAttachmentDropVisual();
+    const files = Array.from(e.dataTransfer.files ?? []);
+    if (files.length === 0) return;
+    void attachmentManager!.handleFiles(files);
+  };
+
+  const attachmentDropCapture = true;
+  container.addEventListener("dragenter", handleAttachmentDragEnterCapture, attachmentDropCapture);
+  container.addEventListener("dragleave", handleAttachmentDragLeaveCapture, attachmentDropCapture);
+  mount.addEventListener("dragover", handleAttachmentDragOverCapture, attachmentDropCapture);
+  mount.addEventListener("drop", handleAttachmentDropCapture, attachmentDropCapture);
+
+  // Prevent the browser from navigating to/opening a dropped file anywhere on
+  // the page while this widget instance has attachments enabled.  These guards
+  // intentionally skip the `dataTransferHasFiles` check because real OS drags
+  // may expose `dataTransfer.types` as a DOMStringList or restrict access
+  // during certain drag phases.  The cost is minimal: we suppress the native
+  // "open file" default for ALL drag-overs while the widget is alive and
+  // attachments are on — text drags into the textarea still work because
+  // element-level handlers are unaffected (we don't stopPropagation here).
+  const ownerDoc = mount.ownerDocument;
+  const handleDocDragOver = (e: DragEvent) => {
+    if (!attachmentDropHandlingActive()) return;
+    e.preventDefault();
+  };
+  const handleDocDrop = (e: DragEvent) => {
+    if (!attachmentDropHandlingActive()) return;
+    e.preventDefault();
+  };
+  ownerDoc.addEventListener("dragover", handleDocDragOver);
+  ownerDoc.addEventListener("drop", handleDocDrop);
+
   destroyCallbacks.push(() => {
     if (composerForm) {
       composerForm.removeEventListener("submit", handleSubmit);
@@ -3923,6 +4116,16 @@ export const createAgentExperience = (
     textarea?.removeEventListener("paste", handleInputPaste);
   });
 
+  destroyCallbacks.push(() => {
+    container.removeEventListener("dragenter", handleAttachmentDragEnterCapture, attachmentDropCapture);
+    container.removeEventListener("dragleave", handleAttachmentDragLeaveCapture, attachmentDropCapture);
+    mount.removeEventListener("dragover", handleAttachmentDragOverCapture, attachmentDropCapture);
+    mount.removeEventListener("drop", handleAttachmentDropCapture, attachmentDropCapture);
+    ownerDoc.removeEventListener("dragover", handleDocDragOver);
+    ownerDoc.removeEventListener("drop", handleDocDrop);
+    clearAttachmentDropVisual();
+  });
+
   destroyCallbacks.push(() => {
     session.cancel();
   });
@@ -4958,6 +5161,11 @@ export const createAgentExperience = (
               }
             });
           }
+
+          // Create drop overlay if missing
+          if (!container.querySelector(".persona-attachment-drop-overlay")) {
+            container.appendChild(buildDropOverlay(attachmentsConfig.dropOverlay));
+          }
         } else {
           // Show existing attachment button and update config
           attachmentButtonWrapper.style.display = "";
@@ -4987,6 +5195,8 @@ export const createAgentExperience = (
         if (attachmentManager) {
           attachmentManager.clearAttachments();
         }
+        // Remove drop overlay
+        container.querySelector(".persona-attachment-drop-overlay")?.remove();
       }
 
       // Update send button styling
@@ -5548,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 } from "./formatting";
 
 describe("JSON Stream Parser", () => {
   it("should extract text field incrementally as JSON streams in", () => {
@@ -170,3 +170,77 @@ 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: [] },
+    ]);
+  });
+});

package/src/utils/formatting.ts

@@ -87,6 +87,136 @@ export const describeToolTitle = (tool: AgentWidgetToolCall) => {
   return "Using tool...";
 };
 
+/**
+ * Formats a millisecond duration as a short human-readable string.
+ * Returns "2.3s", "15s", or "<0.1s".
+ */
+export const formatElapsedMs = (ms: number): string => {
+  const seconds = ms / 1000;
+  if (seconds < 0.1) return "<0.1s";
+  if (seconds >= 10) return `${Math.round(seconds)}s`;
+  return `${seconds.toFixed(1).replace(/\.0$/, "")}s`;
+};
+
+/**
+ * Computes the current elapsed time string for a tool call.
+ */
+export const computeToolElapsed = (tool: AgentWidgetToolCall): string => {
+  const durationMs =
+    typeof tool.duration === "number"
+      ? tool.duration
+      : typeof tool.durationMs === "number"
+        ? tool.durationMs
+        : Math.max(
+            0,
+            (tool.completedAt ?? Date.now()) -
+              (tool.startedAt ?? tool.completedAt ?? Date.now())
+          );
+  return formatElapsedMs(durationMs);
+};
+
+/**
+ * Resolves a text template with tool call placeholders.
+ * Supported placeholders: {toolName}, {duration}
+ * Returns the fallback if template is undefined.
+ */
+export const resolveToolHeaderText = (
+  tool: AgentWidgetToolCall,
+  template: string | undefined,
+  fallback: string
+): string => {
+  if (!template) return fallback;
+
+  const toolName = tool.name?.trim() || "tool";
+  const duration = computeToolElapsed(tool);
+
+  return template
+    .replace(/\{toolName\}/g, toolName)
+    .replace(/\{duration\}/g, duration);
+};
+
+/**
+ * A segment of parsed template text with optional inline formatting.
+ */
+export interface TemplateSegment {
+  /** The text content (or "{duration}" for duration placeholders) */
+  text: string;
+  /** CSS modifier names to apply: "dim", "bold", "italic" */
+  styles: string[];
+  /** True when this segment represents a {duration} placeholder */
+  isDuration?: boolean;
+}
+
+/**
+ * Parses a template string with inline formatting markers into segments.
+ *
+ * Supported markers (Markdown-like):
+ * - `**text**` → bold
+ * - `*text*`  → italic
+ * - `~text~`  → dim / muted
+ *
+ * Placeholders `{toolName}` are resolved; `{duration}` is preserved as a
+ * typed segment so the caller can render it as a live-updating DOM node.
+ *
+ * @example
+ * parseFormattedTemplate("Finished {toolName} ~{duration}~", "Get Weather")
+ * // → [
+ * //   { text: "Finished Get Weather ", styles: [] },
+ * //   { text: "{duration}", styles: ["dim"], isDuration: true }
+ * // ]
+ */
+export const parseFormattedTemplate = (
+  template: string,
+  toolName: string
+): TemplateSegment[] => {
+  const resolved = template.replace(/\{toolName\}/g, toolName);
+  const segments: TemplateSegment[] = [];
+  // Order matters: ** must match before *
+  const regex = /\*\*(.+?)\*\*|\*(.+?)\*|~(.+?)~/g;
+
+  let lastIndex = 0;
+  let match;
+
+  while ((match = regex.exec(resolved)) !== null) {
+    if (match.index > lastIndex) {
+      pushSegments(segments, resolved.slice(lastIndex, match.index), []);
+    }
+
+    if (match[1] !== undefined) {
+      pushSegments(segments, match[1], ["bold"]);
+    } else if (match[2] !== undefined) {
+      pushSegments(segments, match[2], ["italic"]);
+    } else if (match[3] !== undefined) {
+      pushSegments(segments, match[3], ["dim"]);
+    }
+
+    lastIndex = match.index + match[0].length;
+  }
+
+  if (lastIndex < resolved.length) {
+    pushSegments(segments, resolved.slice(lastIndex), []);
+  }
+
+  return segments;
+};
+
+/** Splits text on {duration} and pushes typed segments. */
+const pushSegments = (
+  segments: TemplateSegment[],
+  text: string,
+  styles: string[]
+): void => {
+  const parts = text.split("{duration}");
+  for (let i = 0; i < parts.length; i++) {
+    if (parts[i]) {
+      segments.push({ text: parts[i], styles });
+    }
+    if (i < parts.length - 1) {
+      segments.push({ text: "{duration}", styles, isDuration: true });
+    }
+  }
+};
+
 /**
  * Creates a regex-based parser for extracting text from JSON streams.
  * This is a simpler alternative to schema-stream that uses regex to extract

package/src/utils/morph.ts

@@ -21,14 +21,20 @@ export const morphMessages = (
   Idiomorph.morph(container, newContent.innerHTML, {
     morphStyle: "innerHTML",
     callbacks: {
-      beforeNodeMorphed(oldNode: Node, _newNode: Node): boolean | void {
+      beforeNodeMorphed(oldNode: Node, newNode: Node): boolean | void {
         if (!(oldNode instanceof HTMLElement)) return;
 
         // Preserve typing indicator dots to maintain animation continuity
         // Also preserve elements with data-preserve-animation attribute for custom loading indicators
         if (preserveTypingAnimation) {
-          if (oldNode.classList.contains("persona-animate-typing") ||
-              oldNode.hasAttribute("data-preserve-animation")) {
+          if (oldNode.classList.contains("persona-animate-typing")) {
+            return false;
+          }
+          if (oldNode.hasAttribute("data-preserve-animation")) {
+            // Allow morph when the new node drops the attribute (e.g. tool completed)
+            if (newNode instanceof HTMLElement && !newNode.hasAttribute("data-preserve-animation")) {
+              return;
+            }
             return false;
           }
         }