@runtypelabs/persona 3.6.0 → 3.8.0

package/src/types.ts

@@ -552,10 +552,32 @@ export type AgentWidgetArtifactsFeature = {
   }) => HTMLElement | null;
 };
 
+export type AgentWidgetScrollToBottomFeature = {
+  /**
+   * When true, Persona shows a scroll-to-bottom affordance when the user breaks
+   * away from the latest transcript or event stream content.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * Lucide icon name used for the affordance.
+   * @default "arrow-down"
+   */
+  iconName?: string;
+  /**
+   * Optional label text shown next to the icon. Set to an empty string for an
+   * icon-only affordance.
+   * @default ""
+   */
+  label?: string;
+};
+
 export type AgentWidgetFeatureFlags = {
   showReasoning?: boolean;
   showToolCalls?: boolean;
   showEventStreamToggle?: boolean;
+  /** Shared transcript + event stream scroll-to-bottom affordance. */
+  scrollToBottom?: AgentWidgetScrollToBottomFeature;
   /** Configuration for the Event Stream inspector view */
   eventStream?: EventStreamConfig;
   /** Optional artifact sidebar (split pane / mobile drawer) */
@@ -791,11 +813,16 @@ export type AgentWidgetLauncherConfig = {
    */
   mobileBreakpoint?: number;
   /**
-   * CSS z-index applied to the widget wrapper when it is in a positioned mode
-   * (floating panel, mobile fullscreen, or sidebar). Increase this value if
-   * other elements on the host page appear on top of the widget.
+   * CSS z-index applied to the widget wrapper and launcher button in all
+   * positioned modes (floating panel, mobile fullscreen, sidebar, docked
+   * mobile fullscreen). Increase this value if other elements on the host
+   * page appear on top of the widget.
+   *
+   * In viewport-covering modes (sidebar, mobile fullscreen), the widget
+   * also elevates the host element's stacking context and locks
+   * document scroll to prevent background scrolling.
    *
-   * @default 9999 in overlay modes (mobile fullscreen / sidebar); 50 for the regular floating panel
+   * @default 100000
    */
   zIndex?: number;
   callToActionIconText?: string;

package/src/ui.overlay-z-index.test.ts

@@ -39,7 +39,7 @@ describe("createAgentExperience overlay z-index", () => {
     const wrapper = mount.firstElementChild as HTMLElement | null;
 
     expect(wrapper).not.toBeNull();
-    expect(wrapper?.style.zIndex).toBe("9999");
+    expect(wrapper?.style.zIndex).toBe("100000");
 
     controller.destroy();
   });
@@ -55,7 +55,39 @@ describe("createAgentExperience overlay z-index", () => {
     const wrapper = mount.firstElementChild as HTMLElement | null;
 
     expect(wrapper).not.toBeNull();
-    expect(wrapper?.style.zIndex).toBe("9999");
+    expect(wrapper?.style.zIndex).toBe("100000");
+
+    controller.destroy();
+  });
+
+  it("defaults floating panel wrapper to the overlay z-index", () => {
+    setInnerWidth(1024);
+
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+    });
+
+    const wrapper = mount.firstElementChild as HTMLElement | null;
+
+    expect(wrapper).not.toBeNull();
+    expect(wrapper?.style.zIndex).toBe("100000");
+
+    controller.destroy();
+  });
+
+  it("respects a custom zIndex", () => {
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: {
+        sidebarMode: true,
+        zIndex: 42,
+      },
+    });
+
+    const wrapper = mount.firstElementChild as HTMLElement | null;
+    expect(wrapper?.style.zIndex).toBe("42");
 
     controller.destroy();
   });

package/src/ui.scroll.test.ts

@@ -0,0 +1,554 @@
+// @vitest-environment jsdom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createAgentExperience } from "./ui";
+
+type RafCallback = (time: number) => void;
+
+const STREAM_MESSAGE_ID = "ast-stream";
+const STREAM_CREATED_AT = "2026-03-29T00:00:00.000Z";
+
+const createMount = () => {
+  const mount = document.createElement("div");
+  document.body.appendChild(mount);
+  return mount;
+};
+
+const getScrollToBottomButton = (mount: HTMLElement) =>
+  mount.querySelector<HTMLElement>("[data-persona-scroll-to-bottom]");
+
+const installRafMock = () => {
+  let nextId = 1;
+  let now = performance.now();
+  const callbacks = new Map<number, RafCallback>();
+
+  vi.stubGlobal("requestAnimationFrame", (callback: RafCallback) => {
+    const id = nextId++;
+    callbacks.set(id, callback);
+    return id;
+  });
+
+  vi.stubGlobal("cancelAnimationFrame", (id: number) => {
+    callbacks.delete(id);
+  });
+
+  return {
+    flush(maxFrames = 80) {
+      let frames = 0;
+      while (callbacks.size > 0 && frames < maxFrames) {
+        const pending = [...callbacks.entries()];
+        callbacks.clear();
+        frames += 1;
+        now += 16;
+        pending.forEach(([, callback]) => callback(now));
+      }
+
+      if (callbacks.size > 0) {
+        throw new Error("requestAnimationFrame queue did not settle");
+      }
+    }
+  };
+};
+
+const installScrollMetrics = (
+  element: HTMLElement,
+  initial: { scrollHeight: number; clientHeight: number }
+) => {
+  let scrollTop = 0;
+  let scrollHeight = initial.scrollHeight;
+  const clientHeight = initial.clientHeight;
+
+  Object.defineProperties(element, {
+    scrollTop: {
+      configurable: true,
+      get: () => scrollTop,
+      set: (value: number) => {
+        const maxScrollTop = Math.max(0, scrollHeight - clientHeight);
+        scrollTop = Math.max(0, Math.min(value, maxScrollTop));
+      }
+    },
+    scrollHeight: {
+      configurable: true,
+      get: () => scrollHeight
+    },
+    clientHeight: {
+      configurable: true,
+      get: () => clientHeight
+    }
+  });
+
+  return {
+    getScrollTop: () => scrollTop,
+    getBottomScrollTop: () => Math.max(0, scrollHeight - clientHeight),
+    setScrollTop: (value: number) => {
+      element.scrollTop = value;
+    },
+    setScrollHeight: (value: number) => {
+      scrollHeight = value;
+      if (scrollTop > scrollHeight - clientHeight) {
+        scrollTop = Math.max(0, scrollHeight - clientHeight);
+      }
+    }
+  };
+};
+
+const emitStreamingStatus = (controller: ReturnType<typeof createAgentExperience>) => {
+  controller.injectTestMessage({ type: "status", status: "connecting" });
+};
+
+const emitStreamingMessage = (
+  controller: ReturnType<typeof createAgentExperience>,
+  content: string
+) => {
+  controller.injectTestMessage({
+    type: "message",
+    message: {
+      id: STREAM_MESSAGE_ID,
+      role: "assistant",
+      content,
+      createdAt: STREAM_CREATED_AT,
+      streaming: true
+    }
+  });
+};
+
+const emitReasoningMessage = (
+  controller: ReturnType<typeof createAgentExperience>,
+  chunks: string[]
+) => {
+  controller.injectTestMessage({
+    type: "message",
+    message: {
+      id: STREAM_MESSAGE_ID,
+      role: "assistant",
+      content: "",
+      createdAt: STREAM_CREATED_AT,
+      streaming: true,
+      variant: "reasoning",
+      reasoning: {
+        id: "reason-1",
+        status: "streaming",
+        chunks
+      }
+    }
+  });
+};
+
+const createCustomComposer = () => {
+  const footer = document.createElement("div");
+  footer.className = "persona-widget-footer";
+
+  const form = document.createElement("form");
+  form.setAttribute("data-persona-composer-form", "");
+
+  const textarea = document.createElement("textarea");
+  textarea.setAttribute("data-persona-composer-input", "");
+
+  const status = document.createElement("div");
+  status.setAttribute("data-persona-composer-status", "");
+
+  form.appendChild(textarea);
+  footer.append(form, status);
+  return footer;
+};
+
+describe("createAgentExperience streaming scroll", () => {
+  beforeEach(() => {
+    installRafMock();
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  it("stops auto-follow after a small upward scroll during streaming", () => {
+    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: 1000,
+      clientHeight: 400
+    });
+
+    emitStreamingStatus(controller);
+    emitStreamingMessage(controller, "First chunk");
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(metrics.getBottomScrollTop());
+
+    metrics.setScrollTop(metrics.getBottomScrollTop() - 3);
+    scrollContainer!.dispatchEvent(new Event("scroll"));
+
+    metrics.setScrollHeight(1040);
+    emitStreamingMessage(controller, "Second chunk");
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(597);
+
+    controller.destroy();
+  });
+
+  it("pauses auto-follow on upward wheel intent before the next streamed update", () => {
+    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: 1000,
+      clientHeight: 400
+    });
+
+    emitStreamingStatus(controller);
+    emitStreamingMessage(controller, "First chunk");
+    raf.flush();
+
+    scrollContainer!.dispatchEvent(new WheelEvent("wheel", { deltaY: -24 }));
+    metrics.setScrollTop(580);
+    metrics.setScrollHeight(1060);
+
+    emitStreamingMessage(controller, "Second chunk");
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(580);
+
+    controller.destroy();
+  });
+
+  it("resumes auto-follow when the user scrolls back to the bottom", () => {
+    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: 1000,
+      clientHeight: 400
+    });
+
+    emitStreamingStatus(controller);
+    emitStreamingMessage(controller, "First chunk");
+    raf.flush();
+
+    scrollContainer!.dispatchEvent(new WheelEvent("wheel", { deltaY: -24 }));
+    metrics.setScrollTop(560);
+    metrics.setScrollHeight(1060);
+    emitStreamingMessage(controller, "Second chunk");
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(560);
+
+    metrics.setScrollTop(metrics.getBottomScrollTop() - 2);
+    scrollContainer!.dispatchEvent(new Event("scroll"));
+
+    metrics.setScrollHeight(1100);
+    emitStreamingMessage(controller, "Third chunk");
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(metrics.getBottomScrollTop());
+
+    controller.destroy();
+  });
+
+  it("does not immediately resume after an upward scroll while still near the bottom", () => {
+    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: 1000,
+      clientHeight: 400
+    });
+
+    emitStreamingStatus(controller);
+    emitStreamingMessage(controller, "First chunk");
+    raf.flush();
+
+    scrollContainer!.dispatchEvent(new WheelEvent("wheel", { deltaY: -24 }));
+    metrics.setScrollTop(metrics.getBottomScrollTop() - 3);
+    scrollContainer!.dispatchEvent(new Event("scroll"));
+
+    metrics.setScrollHeight(1040);
+    emitStreamingMessage(controller, "Second chunk");
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(597);
+    expect(getScrollToBottomButton(mount)?.style.display).not.toBe("none");
+
+    controller.destroy();
+  });
+
+  it("keeps following the stream when the user does not scroll", () => {
+    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(980);
+    emitStreamingMessage(controller, "Chunk two");
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(metrics.getBottomScrollTop());
+
+    controller.destroy();
+  });
+
+  it("lets the user break away during reasoning streaming", () => {
+    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: 960,
+      clientHeight: 400
+    });
+
+    emitStreamingStatus(controller);
+    emitReasoningMessage(controller, ["Thinking"]);
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(metrics.getBottomScrollTop());
+
+    scrollContainer!.dispatchEvent(new WheelEvent("wheel", { deltaY: -18 }));
+    metrics.setScrollTop(metrics.getBottomScrollTop() - 4);
+    metrics.setScrollHeight(1010);
+
+    emitReasoningMessage(controller, ["Thinking", " harder"]);
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(556);
+
+    controller.destroy();
+  });
+
+  it("uses icon-only arrow-down defaults for the transcript affordance", () => {
+    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: 1000,
+      clientHeight: 400
+    });
+
+    emitStreamingStatus(controller);
+    emitStreamingMessage(controller, "First chunk");
+    raf.flush();
+
+    scrollContainer!.dispatchEvent(new WheelEvent("wheel", { deltaY: -18 }));
+    metrics.setScrollTop(560);
+    metrics.setScrollHeight(1060);
+    emitStreamingMessage(controller, "Second chunk");
+    raf.flush();
+
+    const button = getScrollToBottomButton(mount);
+    expect(button).not.toBeNull();
+    expect(button?.textContent?.trim()).toBe("");
+    expect(button?.querySelector("svg")).not.toBeNull();
+
+    controller.destroy();
+  });
+
+  it("anchors the transcript affordance outside the scroll container", () => {
+    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: 1000,
+      clientHeight: 400
+    });
+
+    emitStreamingStatus(controller);
+    emitStreamingMessage(controller, "First chunk");
+    raf.flush();
+
+    scrollContainer!.dispatchEvent(new WheelEvent("wheel", { deltaY: -18 }));
+    metrics.setScrollTop(560);
+    metrics.setScrollHeight(1060);
+    emitStreamingMessage(controller, "Second chunk");
+    raf.flush();
+
+    const button = getScrollToBottomButton(mount);
+    expect(button).not.toBeNull();
+    expect(button?.parentElement).not.toBe(scrollContainer);
+
+    controller.destroy();
+  });
+
+  it("keeps the transcript affordance outside the scroll container with a custom composer", () => {
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      plugins: [
+        {
+          id: "custom-composer",
+          renderComposer: () => createCustomComposer()
+        }
+      ]
+    } as any);
+
+    const scrollContainer = mount.querySelector<HTMLElement>("#persona-scroll-container");
+    expect(scrollContainer).not.toBeNull();
+
+    const metrics = installScrollMetrics(scrollContainer!, {
+      scrollHeight: 1000,
+      clientHeight: 400
+    });
+
+    emitStreamingStatus(controller);
+    emitStreamingMessage(controller, "First chunk");
+    raf.flush();
+
+    scrollContainer!.dispatchEvent(new WheelEvent("wheel", { deltaY: -18 }));
+    metrics.setScrollTop(560);
+    metrics.setScrollHeight(1060);
+    emitStreamingMessage(controller, "Second chunk");
+    raf.flush();
+
+    const button = getScrollToBottomButton(mount);
+    expect(button).not.toBeNull();
+    expect(button?.parentElement).not.toBe(scrollContainer);
+
+    controller.destroy();
+  });
+
+  it("hides the transcript affordance when scroll-to-bottom is disabled", () => {
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      features: {
+        scrollToBottom: {
+          enabled: false
+        }
+      }
+    } as any);
+
+    const scrollContainer = mount.querySelector<HTMLElement>("#persona-scroll-container");
+    expect(scrollContainer).not.toBeNull();
+
+    const metrics = installScrollMetrics(scrollContainer!, {
+      scrollHeight: 1000,
+      clientHeight: 400
+    });
+
+    emitStreamingStatus(controller);
+    emitStreamingMessage(controller, "First chunk");
+    raf.flush();
+
+    scrollContainer!.dispatchEvent(new WheelEvent("wheel", { deltaY: -18 }));
+    metrics.setScrollTop(560);
+    metrics.setScrollHeight(1060);
+    emitStreamingMessage(controller, "Second chunk");
+    raf.flush();
+
+    expect(getScrollToBottomButton(mount)).toBeNull();
+
+    controller.destroy();
+  });
+
+  it("renders the transcript affordance as icon-only when label is empty", () => {
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      features: {
+        scrollToBottom: {
+          enabled: true,
+          iconName: "arrow-down",
+          label: ""
+        }
+      }
+    } as any);
+
+    const scrollContainer = mount.querySelector<HTMLElement>("#persona-scroll-container");
+    expect(scrollContainer).not.toBeNull();
+
+    const metrics = installScrollMetrics(scrollContainer!, {
+      scrollHeight: 1000,
+      clientHeight: 400
+    });
+
+    emitStreamingStatus(controller);
+    emitStreamingMessage(controller, "First chunk");
+    raf.flush();
+
+    scrollContainer!.dispatchEvent(new WheelEvent("wheel", { deltaY: -18 }));
+    metrics.setScrollTop(560);
+    metrics.setScrollHeight(1060);
+    emitStreamingMessage(controller, "Second chunk");
+    raf.flush();
+
+    const button = getScrollToBottomButton(mount);
+    expect(button).not.toBeNull();
+    expect(button?.textContent?.trim()).toBe("");
+    expect(button?.querySelector("svg")).not.toBeNull();
+
+    controller.destroy();
+  });
+
+});