@runtypelabs/persona 4.4.2 → 4.6.0

package/src/types.ts

@@ -386,6 +386,28 @@ export type AgentExecutionState = {
   stopReason?: 'complete' | 'end_turn' | 'max_turns' | 'max_cost' | 'timeout' | 'error';
 };
 
+/**
+ * The coordinates needed to resume a durable agent turn after the SSE
+ * connection drops (any resumable, server-persisted execution, e.g. Claude
+ * Managed agents or async/background runs). Held on the session while a
+ * resumable stream is in flight
+ * and surfaced to the host via {@link AgentWidgetConfig.onExecutionState} so it
+ * can persist `{ executionId, lastEventId }` next to its own `conversationId`
+ * for the tab-reload path.
+ *
+ * `conversationId` is intentionally absent: it is host-owned (it lives in the
+ * host's `reconnectStream`/`customFetch` closure; the widget never sees it).
+ */
+export type ResumableHandle = {
+  /** The durable turn to reconnect to (from `agentMetadata.executionId`). */
+  executionId: string;
+  /** Highest SSE `id:` seq applied: the `?after=` reconnect cursor. */
+  lastEventId: string;
+  /** The open assistant message being streamed into, kept open on resume. */
+  assistantMessageId: string;
+  status: 'running';
+};
+
 /**
  * Metadata attached to messages created during agent execution.
  */
@@ -689,6 +711,12 @@ export type AgentWidgetControllerEventMap = {
   "eventStream:closed": { timestamp: number };
   "approval:requested": { approval: AgentWidgetApproval; message: AgentWidgetMessage };
   "approval:resolved": { approval: AgentWidgetApproval; decision: string };
+  /** A durable stream dropped; the widget is about to reconnect. */
+  "stream:paused": { executionId: string; after: string };
+  /** A reconnect attempt is in flight (`attempt` is 1-based). */
+  "stream:resuming": { executionId: string; after: string; attempt: number };
+  /** The durable turn resumed and reached its terminal after a reconnect. */
+  "stream:resumed": { executionId: string; after: string };
 };
 
 /**
@@ -847,26 +875,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 = {
@@ -1801,6 +1879,10 @@ export type AgentWidgetStatusIndicatorConfig = {
   connectingText?: string;
   connectedText?: string;
   errorText?: string;
+  /** Status text while a dropped durable stream is awaiting reconnect. */
+  pausedText?: string;
+  /** Status text while a reconnect attempt is in flight. */
+  resumingText?: string;
 };
 
 export type AgentWidgetVoiceRecognitionConfig = {
@@ -4110,6 +4192,62 @@ export type AgentWidgetConfig = {
    * ```
    */
   customFetch?: AgentWidgetCustomFetch;
+  /**
+   * Durable-session reconnect transport (host-owned, symmetric to
+   * {@link customFetch}). When a durable agent stream drops mid-turn (any
+   * resumable, server-persisted execution, e.g. Claude Managed agents or
+   * async/background runs), the widget calls this to fetch the read-only
+   * reconnect stream and pipes its body through the normal event pipeline to
+   * resume from where it left off.
+   *
+   * The host closure owns `agentId` / `conversationId` / base URL / auth and
+   * builds the events request, e.g.:
+   *
+   * ```typescript
+   * reconnectStream: ({ executionId, after, signal }) =>
+   *   fetch(
+   *     `${baseUrl}/v1/agents/${agentId}/executions/${executionId}` +
+   *       `/events?conversationId=${conversationId}&after=${after}`,
+   *     { headers: { Authorization: `Bearer ${token}`, "X-Persona-Version": ver }, signal }
+   *   )
+   * ```
+   *
+   * Resolve with a `text/event-stream` `Response`. Throw or resolve non-ok to
+   * signal "this attempt failed" (the widget backs off and retries, then gives
+   * up after the bounded attempts). Reconnect only ever arms on the durable
+   * lane (streams carrying SSE `id:` lines); without this hook a drop finalizes
+   * exactly as before.
+   */
+  reconnectStream?: (ctx: {
+    executionId: string;
+    after: string;
+    signal: AbortSignal;
+  }) => Promise<Response>;
+  /**
+   * Tuning for the auto-reconnect backoff. Defaults to ~5 attempts over ~30s
+   * (`backoffMs: [1000, 2000, 4000, 8000, 8000]`).
+   */
+  reconnect?: {
+    /** Max reconnect attempts before giving up and finalizing. @default backoffMs.length */
+    maxAttempts?: number;
+    /** Per-attempt delay (ms) before each retry. @default [1000, 2000, 4000, 8000, 8000] */
+    backoffMs?: number[];
+  };
+  /**
+   * Called whenever the durable resume handle changes: created when a durable
+   * turn starts streaming, updated as the cursor advances (throttled), and
+   * `null` when the turn finishes, errors, or is torn down. Persist
+   * `{ executionId, lastEventId }` next to your `conversationId` and pass it
+   * back via {@link resume} on the next mount to survive a tab reload.
+   */
+  onExecutionState?: (handle: ResumableHandle | null) => void;
+  /**
+   * Resume a durable turn on boot (tab-reload path). When present alongside
+   * {@link reconnectStream}, the widget enters `resuming` immediately on mount
+   * and reconnects from `after`, replaying everything past the cursor into the
+   * restored conversation.
+   */
+  resume?: { executionId: string; after: string };
   /**
    * Custom SSE event parser for non-standard streaming response formats.
    *
@@ -4686,8 +4824,26 @@ export type PersonaArtifactManualUpsert =
 
 export type AgentWidgetEvent =
   | { type: "message"; message: AgentWidgetMessage }
-  | { type: "status"; status: "connecting" | "connected" | "error" | "idle" }
+  | {
+      type: "status";
+      status: "connecting" | "connected" | "error" | "idle";
+      /**
+       * Set on the `idle` emitted from a graceful execution terminal
+       * (`execution_complete`). Distinguishes a real finish from the plain
+       * `idle` the dispatch wrappers emit in their `finally` on a dropped
+       * connection. The durable-reconnect drop detection keys off this.
+       */
+      terminal?: boolean;
+    }
   | { type: "error"; error: Error }
+  /**
+   * Durable-session reconnect cursor. Carries the SSE `id:` line (the durable
+   * row seq) of a fully-parsed frame so the session can track `lastEventId`
+   * and resume from `?after=<id>` after a drop. Only emitted on the durable
+   * lane (any resumable execution that stamps `id:` lines, e.g. Claude Managed
+   * agents or async/background runs).
+   */
+  | { type: "cursor"; id: string }
   | {
       type: "artifact_start";
       id: string;

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();
+  });
+});