@runtypelabs/persona 4.4.2 → 4.5.0

package/src/types.ts

@@ -847,26 +847,76 @@ export type AgentWidgetArtifactsFeature = {
 /**
  * How the transcript scrolls while an assistant response streams in.
  *
- * - `"follow"` (default): keep the newest content pinned to the bottom of the
- *   viewport, pausing when the user scrolls up and resuming when they return
- *   to the bottom.
- * - `"anchor-top"`: on send, scroll the user's message near the top of the
- *   viewport and hold it there while the response streams in beneath it
- *   (ChatGPT-style). The transcript never auto-scrolls during streaming.
+ * - `"anchor-top"` (default): on send, scroll the user's message near the top
+ *   of the viewport and hold it there while the response streams in beneath it
+ *   (ChatGPT-style). When a turn has no user send to anchor to (a proactive
+ *   greeting, an injected assistant message, a resubmit, or first-load
+ *   streaming), it falls back to `"follow"` for that turn so content never
+ *   streams in off-screen.
+ * - `"follow"`: keep the newest content pinned to the bottom of the viewport,
+ *   pausing when the user scrolls up and resuming when they return to the
+ *   bottom. This was the default before 4.x.
  * - `"none"`: never auto-scroll; the scroll-to-bottom affordance is the only
  *   way back to the latest content.
  */
 export type AgentWidgetScrollMode = "follow" | "anchor-top" | "none";
 
+/**
+ * Where the transcript lands when a *saved* conversation is reopened (restored
+ * from the storage adapter / `initialMessages`), as opposed to a fresh send.
+ *
+ * - `"bottom"` (default): jump to the absolute end of the transcript, matching
+ *   the historical behavior.
+ * - `"last-user-turn"`: pin the last user message near the top of the viewport
+ *   (the last point the reader was actively driving the conversation) so a long
+ *   restored thread opens at a readable place rather than at the very bottom.
+ */
+export type AgentWidgetScrollRestorePosition = "bottom" | "last-user-turn";
+
 export type AgentWidgetScrollBehaviorFeature = {
-  /** Scroll behavior during streamed responses. @default "follow" */
+  /** Scroll behavior during streamed responses. @default "anchor-top" */
   mode?: AgentWidgetScrollMode;
   /**
    * Gap (px) kept between the anchored user message and the top of the
-   * viewport in `"anchor-top"` mode.
+   * viewport in `"anchor-top"` mode. Also used as the gap for
+   * `restorePosition: "last-user-turn"`.
    * @default 16
    */
   anchorTopOffset?: number;
+  /**
+   * Where to land when a saved conversation reopens. Additive and opt-in: the
+   * default preserves the historical "jump to the bottom" behavior.
+   * @default "bottom"
+   */
+  restorePosition?: AgentWidgetScrollRestorePosition;
+  /**
+   * When true, interactions beyond text selection — keyboard navigation
+   * (PageUp/PageDown/Home/End/arrows) inside the transcript and focusing a
+   * link or other interactive element within it — also pause auto-follow in
+   * `"follow"` mode. Treats "the reader is doing something here" as intent to
+   * stay put, not just "the reader dragged a selection". Opt-in; default keeps
+   * only the existing wheel/scroll/selection triggers.
+   * @default false
+   */
+  pauseOnInteraction?: boolean;
+  /**
+   * When true, the scroll-to-bottom affordance also surfaces new-content and
+   * still-streaming activity while the reader is pinned away from the latest
+   * content in `"anchor-top"` mode. Lets the reader know a response is arriving
+   * offscreen below. Defaults on alongside the `"anchor-top"` default; set
+   * `false` to keep the count + streaming hint silent while pinned.
+   * @default true
+   */
+  showActivityWhilePinned?: boolean;
+  /**
+   * When true, Persona maintains a visually-hidden `aria-live="polite"` region
+   * that announces important transcript events — a response starting, a
+   * response finishing, and "N new messages below" while the reader is scrolled
+   * away — at a comfortable cadence (never token-by-token). Opt-in so existing
+   * embeds don't suddenly gain screen-reader announcements.
+   * @default false
+   */
+  announce?: boolean;
 };
 
 export type AgentWidgetScrollToBottomFeature = {

package/src/ui.scroll-additive.test.ts

@@ -0,0 +1,451 @@
+// @vitest-environment jsdom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createAgentExperience } from "./ui";
+import type { AgentWidgetConfig, AgentWidgetMessage } from "./types";
+
+type RafCallback = (time: number) => void;
+
+const CREATED_AT = "2026-03-29T00:00:00.000Z";
+
+const createMount = () => {
+  const mount = document.createElement("div");
+  document.body.appendChild(mount);
+  return mount;
+};
+
+const getScrollContainer = (mount: HTMLElement) =>
+  mount.querySelector<HTMLElement>("#persona-scroll-container")!;
+
+const getScrollToBottomButton = (mount: HTMLElement) =>
+  mount.querySelector<HTMLElement>("[data-persona-scroll-to-bottom]")!;
+
+const getCountBadge = (mount: HTMLElement) =>
+  mount.querySelector<HTMLElement>("[data-persona-scroll-to-bottom-count]")!;
+
+const getLiveRegion = (mount: HTMLElement) =>
+  mount.querySelector<HTMLElement>("[data-persona-live-region]");
+
+const installRafMock = () => {
+  let nextId = 1;
+  const callbacks = new Map<number, RafCallback>();
+  let now = 0;
+  vi.stubGlobal("requestAnimationFrame", (cb: RafCallback) => {
+    const id = nextId++;
+    callbacks.set(id, cb);
+    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.values()];
+        callbacks.clear();
+        frames += 1;
+        now += 16;
+        pending.forEach((cb) => cb(now));
+      }
+    },
+  };
+};
+
+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) => {
+        scrollTop = Math.max(0, Math.min(value, Math.max(0, scrollHeight - clientHeight)));
+      },
+    },
+    scrollHeight: { configurable: true, get: () => scrollHeight },
+    clientHeight: { configurable: true, get: () => clientHeight },
+  });
+  return {
+    getScrollTop: () => scrollTop,
+    getBottom: () => Math.max(0, scrollHeight - clientHeight),
+    setScrollTop: (v: number) => {
+      element.scrollTop = v;
+    },
+    setScrollHeight: (v: number) => {
+      scrollHeight = v;
+      if (scrollTop > scrollHeight - clientHeight) {
+        scrollTop = Math.max(0, scrollHeight - clientHeight);
+      }
+    },
+  };
+};
+
+const emitStreamingMessage = (
+  controller: ReturnType<typeof createAgentExperience>,
+  id: string,
+  content: string
+) => {
+  controller.injectTestMessage({
+    type: "message",
+    message: { id, role: "assistant", content, createdAt: CREATED_AT, streaming: true },
+  });
+};
+
+const emitAssistantMessage = (
+  controller: ReturnType<typeof createAgentExperience>,
+  id: string,
+  content: string
+) => {
+  controller.injectTestMessage({
+    type: "message",
+    message: { id, role: "assistant", content, createdAt: CREATED_AT },
+  });
+};
+
+const emitUserMessage = (
+  controller: ReturnType<typeof createAgentExperience>,
+  id: string,
+  content: string
+) => {
+  controller.injectTestMessage({
+    type: "message",
+    message: { id, role: "user", content, createdAt: CREATED_AT },
+  });
+};
+
+const emitStreamingAssistant = (
+  controller: ReturnType<typeof createAgentExperience>,
+  id: string,
+  content: string
+) => {
+  controller.injectTestMessage({
+    type: "message",
+    message: { id, role: "assistant", content, createdAt: CREATED_AT, streaming: true },
+  });
+};
+
+// Establish a real anchor-top turn: a prior assistant message seeds
+// send-detection, then a user send anchors. The next assistant message is the
+// anchored response (so it does NOT hit the no-anchor follow fallback) — the
+// scenario `showActivityWhilePinned` is about: the answer streaming in below a
+// pinned question the reader is still reading from the top.
+const anchorUserTurn = (
+  controller: ReturnType<typeof createAgentExperience>
+) => {
+  emitAssistantMessage(controller, "seed", "Earlier reply");
+  emitUserMessage(controller, "u1", "Question");
+};
+
+const baseConfig = (overrides: AgentWidgetConfig): AgentWidgetConfig => ({
+  apiUrl: "https://api.example.com/chat",
+  launcher: { enabled: false },
+  // Hermetic: never restore persisted history at construction. Otherwise a
+  // prior test's transcript (sharing message ids like "u1") leaks via
+  // localStorage and a user send reads as already-seen, so the anchor never
+  // takes and the assertion sees a follow-to-bottom instead.
+  persistState: false,
+  ...overrides,
+});
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  localStorage.clear();
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+});
+
+describe("scrollBehavior.pauseOnInteraction (Principle 3)", () => {
+  beforeEach(() => {
+    installRafMock();
+  });
+
+  it("pauses auto-follow on a transcript navigation keypress when enabled", () => {
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(
+      mount,
+      baseConfig({ features: { scrollBehavior: { mode: "follow", pauseOnInteraction: true } } })
+    );
+    const sc = getScrollContainer(mount);
+    const metrics = installScrollMetrics(sc, { scrollHeight: 1000, clientHeight: 400 });
+
+    emitStreamingMessage(controller, "a1", "First chunk");
+    raf.flush();
+    expect(metrics.getScrollTop()).toBe(metrics.getBottom());
+
+    sc.dispatchEvent(new KeyboardEvent("keydown", { key: "PageUp", bubbles: true }));
+
+    metrics.setScrollHeight(1080);
+    emitStreamingMessage(controller, "a1", "First chunk + more");
+    raf.flush();
+
+    // Paused: the stream no longer chases the bottom.
+    expect(metrics.getScrollTop()).toBe(600);
+    controller.destroy();
+  });
+
+  it("does NOT pause on keypress when the option is off (default)", () => {
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(
+      mount,
+      baseConfig({ features: { scrollBehavior: { mode: "follow" } } })
+    );
+    const sc = getScrollContainer(mount);
+    const metrics = installScrollMetrics(sc, { scrollHeight: 1000, clientHeight: 400 });
+
+    emitStreamingMessage(controller, "a1", "First chunk");
+    raf.flush();
+
+    sc.dispatchEvent(new KeyboardEvent("keydown", { key: "PageUp", bubbles: true }));
+
+    metrics.setScrollHeight(1080);
+    emitStreamingMessage(controller, "a1", "First chunk + more");
+    raf.flush();
+
+    // Still following: chases the new bottom.
+    expect(metrics.getScrollTop()).toBe(metrics.getBottom());
+    controller.destroy();
+  });
+});
+
+describe("scrollBehavior.showActivityWhilePinned (Principle 8)", () => {
+  beforeEach(() => {
+    installRafMock();
+  });
+
+  it("counts the anchored response arriving below the pinned turn by default", () => {
+    const mount = createMount();
+    // showActivityWhilePinned now defaults on (alongside the anchor-top default).
+    const controller = createAgentExperience(
+      mount,
+      baseConfig({ features: { scrollBehavior: { mode: "anchor-top" } } })
+    );
+    const sc = getScrollContainer(mount);
+    const metrics = installScrollMetrics(sc, { scrollHeight: 1000, clientHeight: 400 });
+    anchorUserTurn(controller);
+    metrics.setScrollTop(0); // reading the pinned question, away from the bottom
+
+    emitAssistantMessage(controller, "a1", "Arrived below");
+
+    expect(getCountBadge(mount).textContent).toBe("1");
+    expect(getScrollToBottomButton(mount).getAttribute("aria-label")).toContain("1 new");
+    controller.destroy();
+  });
+
+  it("stays silent when showActivityWhilePinned is disabled", () => {
+    const mount = createMount();
+    const controller = createAgentExperience(
+      mount,
+      baseConfig({
+        features: {
+          scrollBehavior: { mode: "anchor-top", showActivityWhilePinned: false },
+        },
+      })
+    );
+    const sc = getScrollContainer(mount);
+    const metrics = installScrollMetrics(sc, { scrollHeight: 1000, clientHeight: 400 });
+    anchorUserTurn(controller);
+    metrics.setScrollTop(0);
+
+    emitAssistantMessage(controller, "a1", "Arrived below");
+
+    expect(getCountBadge(mount).textContent).toBe("");
+    controller.destroy();
+  });
+});
+
+describe("scrollBehavior anchor-top no-anchor fallback", () => {
+  let raf: ReturnType<typeof installRafMock>;
+  beforeEach(() => {
+    raf = installRafMock();
+  });
+
+  const makeAnchorTop = (mount: HTMLElement) =>
+    createAgentExperience(
+      mount,
+      baseConfig({ features: { scrollBehavior: { mode: "anchor-top" } } })
+    );
+
+  it("follows to the bottom for an assistant turn with no user anchor", () => {
+    const mount = createMount();
+    const controller = makeAnchorTop(mount);
+    const sc = getScrollContainer(mount);
+    const metrics = installScrollMetrics(sc, { scrollHeight: 1000, clientHeight: 400 });
+
+    // A proactive/first-load assistant stream with no preceding user send: it
+    // has no anchor, so it falls back to follow-to-bottom rather than streaming
+    // in off-screen.
+    emitStreamingAssistant(controller, "a1", "Proactive reply");
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(metrics.getBottom());
+    controller.destroy();
+  });
+
+  it("anchors near the top (does not follow) when the turn follows a user send", () => {
+    const mount = createMount();
+    const controller = makeAnchorTop(mount);
+    const sc = getScrollContainer(mount);
+    const metrics = installScrollMetrics(sc, { scrollHeight: 1000, clientHeight: 400 });
+
+    anchorUserTurn(controller); // seed + user send → real anchor
+    raf.flush();
+    emitStreamingAssistant(controller, "a1", "Answer below the pinned question");
+    raf.flush();
+
+    // The anchored response is pinned near the top (jsdom offsetTop 0 → 0), not
+    // chased to the bottom.
+    expect(metrics.getScrollTop()).toBe(0);
+    controller.destroy();
+  });
+
+  it("keeps follow-on assistant content in an anchored turn pinned (no late-embed yank)", () => {
+    const mount = createMount();
+    const controller = makeAnchorTop(mount);
+    const sc = getScrollContainer(mount);
+    const metrics = installScrollMetrics(sc, { scrollHeight: 1000, clientHeight: 400 });
+
+    anchorUserTurn(controller); // user send → anchor
+    raf.flush();
+    emitAssistantMessage(controller, "a1", "Anchored answer");
+    raf.flush();
+    metrics.setScrollTop(0); // reading the pinned question from the top
+
+    // A second assistant message in the same anchored conversation — a
+    // multi-part reply or a late-injected embed (tweet/image/tool result) — must
+    // NOT re-arm the fallback or yank the viewport to the bottom.
+    emitStreamingAssistant(controller, "a2", "Late-injected embed content");
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(0);
+    controller.destroy();
+  });
+});
+
+describe("scrollBehavior.restorePosition (Principle 11)", () => {
+  beforeEach(() => {
+    installRafMock();
+  });
+
+  const history: AgentWidgetMessage[] = [
+    { id: "u1", role: "user", content: "First question", createdAt: CREATED_AT },
+    { id: "a1", role: "assistant", content: "First answer", createdAt: CREATED_AT },
+    { id: "u2", role: "user", content: "Second question", createdAt: CREATED_AT },
+    { id: "a2", role: "assistant", content: "Second answer", createdAt: CREATED_AT },
+  ];
+
+  it("pins the last user message near the top on open when set to last-user-turn", () => {
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(
+      mount,
+      baseConfig({
+        launcher: { enabled: true, autoExpand: false },
+        initialMessages: history,
+        features: { scrollBehavior: { mode: "follow", restorePosition: "last-user-turn" } },
+      })
+    );
+    const sc = getScrollContainer(mount);
+    const metrics = installScrollMetrics(sc, { scrollHeight: 1000, clientHeight: 400 });
+
+    // jsdom computes no layout; give the last user bubble a known offsetTop so
+    // the anchor geometry has something to target.
+    const lastUserBubble = sc.querySelector<HTMLElement>('[data-message-id="u2"]')!;
+    Object.defineProperty(lastUserBubble, "offsetTop", { configurable: true, get: () => 320 });
+
+    controller.open();
+    raf.flush();
+
+    // 320 - 16 (anchorTopOffset) = 304, above the bottom (600).
+    expect(metrics.getScrollTop()).toBe(304);
+    controller.destroy();
+  });
+
+  it("jumps to the bottom on open by default", () => {
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(
+      mount,
+      baseConfig({
+        launcher: { enabled: true, autoExpand: false },
+        initialMessages: history,
+        features: { scrollBehavior: { mode: "follow" } },
+      })
+    );
+    const sc = getScrollContainer(mount);
+    const metrics = installScrollMetrics(sc, { scrollHeight: 1000, clientHeight: 400 });
+
+    controller.open();
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(metrics.getBottom());
+    controller.destroy();
+  });
+});
+
+describe("scrollBehavior.announce (Principle 15)", () => {
+  it("always creates a polite live region", () => {
+    installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(mount, baseConfig({}));
+    const region = getLiveRegion(mount);
+    expect(region).not.toBeNull();
+    expect(region!.getAttribute("aria-live")).toBe("polite");
+    controller.destroy();
+  });
+
+  it("announces new-content arrival at a debounced cadence when enabled", () => {
+    vi.useFakeTimers();
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(
+      mount,
+      baseConfig({ features: { scrollBehavior: { mode: "follow", announce: true } } })
+    );
+    const sc = getScrollContainer(mount);
+    const metrics = installScrollMetrics(sc, { scrollHeight: 1000, clientHeight: 400 });
+
+    emitStreamingMessage(controller, "seed", "hi");
+    raf.flush();
+    // Scroll up so the next message counts as "below".
+    metrics.setScrollTop(100);
+    sc.dispatchEvent(new Event("scroll"));
+
+    emitAssistantMessage(controller, "a1", "Arrived below");
+    vi.advanceTimersByTime(400);
+
+    expect(getLiveRegion(mount)!.textContent).toContain("new message");
+    controller.destroy();
+  });
+
+  it("stays silent when announce is off (default)", () => {
+    vi.useFakeTimers();
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(
+      mount,
+      baseConfig({ features: { scrollBehavior: { mode: "follow" } } })
+    );
+    const sc = getScrollContainer(mount);
+    const metrics = installScrollMetrics(sc, { scrollHeight: 1000, clientHeight: 400 });
+
+    emitStreamingMessage(controller, "seed", "hi");
+    raf.flush();
+    metrics.setScrollTop(100);
+    sc.dispatchEvent(new Event("scroll"));
+
+    emitAssistantMessage(controller, "a1", "Arrived below");
+    vi.advanceTimersByTime(400);
+
+    expect(getLiveRegion(mount)!.textContent).toBe("");
+    controller.destroy();
+  });
+});

package/src/ui.scroll.test.ts

@@ -912,9 +912,12 @@ describe("createAgentExperience streaming scroll", () => {
   it("re-sticks to the bottom when the user sends a message after scrolling up", () => {
     const raf = installRafMock();
     const mount = createMount();
+    // Follow-specific: a user send re-sticks to the bottom (anchor-top, the
+    // default, would pin the sent message near the top instead).
     const controller = createAgentExperience(mount, {
       apiUrl: "https://api.example.com/chat",
-      launcher: { enabled: false }
+      launcher: { enabled: false },
+      features: { scrollBehavior: { mode: "follow" } }
     });
 
     const scrollContainer = mount.querySelector<HTMLElement>("#persona-scroll-container");
@@ -941,9 +944,12 @@ describe("createAgentExperience streaming scroll", () => {
   it("shows a count badge for messages that arrive while paused", () => {
     const raf = installRafMock();
     const mount = createMount();
+    // Follow-specific paused-badge semantics (wheel-up pauses auto-follow, then
+    // a message arrives while paused and below the fold).
     const controller = createAgentExperience(mount, {
       apiUrl: "https://api.example.com/chat",
-      launcher: { enabled: false }
+      launcher: { enabled: false },
+      features: { scrollBehavior: { mode: "follow" } }
     });
 
     const scrollContainer = mount.querySelector<HTMLElement>("#persona-scroll-container");