@runtypelabs/persona 3.10.0 → 3.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "3.10.0",
+  "version": "3.10.1",
   "description": "Themeable, pluggable streaming agent widget for websites, in plain JS with support for voice input and reasoning / tool output.",
   "type": "module",
   "main": "dist/index.cjs",

package/src/styles/widget.css

@@ -93,6 +93,35 @@
   gap: 1.5rem;
 }
 
+[data-persona-root] .persona-widget-container .persona-attachment-drop-overlay {
+  display: none;
+  position: absolute;
+  inset: var(--persona-drop-overlay-inset, 0);
+  z-index: 50;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  pointer-events: none;
+  background: var(--persona-drop-overlay-bg, rgba(59, 130, 246, 0.08));
+  -webkit-backdrop-filter: blur(var(--persona-drop-overlay-blur, 8px));
+  backdrop-filter: blur(var(--persona-drop-overlay-blur, 8px));
+  border: var(--persona-drop-overlay-border, 2px dashed rgba(59, 130, 246, 0.4));
+  border-radius: var(--persona-drop-overlay-radius, inherit);
+  transition: opacity 0.15s ease;
+}
+
+[data-persona-root] .persona-widget-container .persona-attachment-drop-overlay .persona-drop-overlay-label {
+  font-size: var(--persona-drop-overlay-label-size, 0.875rem);
+  color: var(--persona-drop-overlay-label-color, rgba(59, 130, 246, 0.8));
+  font-weight: 500;
+  user-select: none;
+}
+
+[data-persona-root] .persona-widget-container.persona-attachment-drop-active .persona-attachment-drop-overlay {
+  display: flex;
+}
+
 /* Widget CSS Variables - scoped to widget root to avoid polluting global namespace */
 [data-persona-root] {
   --persona-radius-sm: 0.125rem;
@@ -935,6 +964,7 @@
 }
 
 .persona-widget-container {
+  position: relative;
   border-radius: var(--persona-panel-radius, var(--persona-radius-xl, 0.75rem));
 }
 

package/src/types.ts

@@ -2081,6 +2081,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

@@ -472,6 +472,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();

package/src/ui.ts

@@ -147,6 +147,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 +402,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 +915,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 +1017,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,6 +1987,7 @@ export const createAgentExperience = (
   let lastScrollTop = 0;
   let scrollRAF: number | null = null;
   let isAutoScrolling = false;
+  let hasPendingAutoScroll = false;
 
   const USER_SCROLL_THRESHOLD = 1;
   const BOTTOM_THRESHOLD = 8;
@@ -2041,6 +2104,7 @@ export const createAgentExperience = (
       cancelAnimationFrame(scrollRAF);
       scrollRAF = null;
     }
+    hasPendingAutoScroll = false;
     cancelSmoothScroll();
   };
 
@@ -2076,10 +2140,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);
     });
@@ -3776,7 +3855,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 +3994,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 +4074,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 +5119,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 +5153,8 @@ export const createAgentExperience = (
         if (attachmentManager) {
           attachmentManager.clearAttachments();
         }
+        // Remove drop overlay
+        container.querySelector(".persona-attachment-drop-overlay")?.remove();
       }
 
       // Update send button styling