@runtypelabs/persona 4.12.0 → 4.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "4.12.0",
+  "version": "4.13.0",
   "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/ui.scroll-additive.test.ts

@@ -449,3 +449,368 @@ describe("scrollBehavior.announce (Principle 15)", () => {
     controller.destroy();
   });
 });
+
+
+// Anchor-top parks on the first UNREAD attention-worthy block of a turn:
+// tool calls and reasoning are chrome and never targeted, so a response that
+// opens with them scrolls them past rather than stranding the answer below
+// the fold.
+describe("anchor-top first-unread positioning", () => {
+  beforeEach(() => {
+    installRafMock();
+  });
+
+  const anchorTopConfig = () =>
+    baseConfig({
+      features: { scrollBehavior: { mode: "anchor-top", anchorTopOffset: 16 } },
+    });
+
+  const emitToolMessage = (
+    controller: ReturnType<typeof createAgentExperience>,
+    id: string
+  ) => {
+    controller.injectTestMessage({
+      type: "message",
+      message: {
+        id,
+        role: "assistant",
+        content: "",
+        createdAt: CREATED_AT,
+        variant: "tool",
+        toolCall: { id, name: "search", status: "complete" },
+      },
+    });
+  };
+
+  // An artifact / component block: substance lives in rawContent, `content`
+  // is empty. Testing text alone would silently skip these.
+  const emitArtifactMessage = (
+    controller: ReturnType<typeof createAgentExperience>,
+    id: string
+  ) => {
+    controller.injectTestMessage({
+      type: "message",
+      message: {
+        id,
+        role: "assistant",
+        content: "",
+        createdAt: CREATED_AT,
+        rawContent: JSON.stringify({
+          text: "",
+          component: "PersonaArtifactInline",
+          props: { artifactId: "art-1", title: "Report" },
+        }),
+      },
+    });
+  };
+
+  const setBubbleOffsetTop = (mount: HTMLElement, id: string, value: number) => {
+    const bubble = getScrollContainer(mount).querySelector<HTMLElement>(
+      `[data-message-id="${id}"]`
+    );
+    expect(bubble).not.toBeNull();
+    Object.defineProperty(bubble!, "offsetTop", { configurable: true, value });
+  };
+
+  const startTurn = (
+    controller: ReturnType<typeof createAgentExperience>,
+    mount: HTMLElement,
+    raf: ReturnType<typeof installRafMock>
+  ) => {
+    emitAssistantMessage(controller, "seed", "Earlier reply");
+    emitUserMessage(controller, "u1", "Where is my order?");
+    setBubbleOffsetTop(mount, "u1", 300);
+    raf.flush();
+  };
+
+  it("skips a run of tool calls and anchors the answer", () => {
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(mount, anchorTopConfig());
+    const metrics = installScrollMetrics(getScrollContainer(mount), {
+      scrollHeight: 1000,
+      clientHeight: 400,
+    });
+
+    startTurn(controller, mount, raf);
+    expect(metrics.getScrollTop()).toBe(284); // parked on the sent message
+
+    for (let i = 0; i < 6; i += 1) emitToolMessage(controller, `t${i}`);
+    metrics.setScrollHeight(1500);
+    raf.flush();
+    // Tool calls are chrome: they never move the anchor.
+    expect(metrics.getScrollTop()).toBe(284);
+
+    emitStreamingAssistant(controller, "a1", "Good news — your order is on track.");
+    setBubbleOffsetTop(mount, "a1", 700);
+    raf.flush();
+    expect(metrics.getScrollTop()).toBe(684);
+
+    controller.destroy();
+  });
+
+  it("anchors an artifact block, whose content lives in rawContent", () => {
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(mount, anchorTopConfig());
+    const metrics = installScrollMetrics(getScrollContainer(mount), {
+      scrollHeight: 1000,
+      clientHeight: 400,
+    });
+
+    startTurn(controller, mount, raf);
+    for (let i = 0; i < 3; i += 1) emitToolMessage(controller, `t${i}`);
+    metrics.setScrollHeight(1500);
+    raf.flush();
+
+    emitArtifactMessage(controller, "art-msg");
+    setBubbleOffsetTop(mount, "art-msg", 620);
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(604);
+    controller.destroy();
+  });
+
+  it("holds the FIRST unread block when more text streams in after it", () => {
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(mount, anchorTopConfig());
+    const metrics = installScrollMetrics(getScrollContainer(mount), {
+      scrollHeight: 1000,
+      clientHeight: 400,
+    });
+
+    startTurn(controller, mount, raf);
+    emitStreamingAssistant(controller, "a1", "First segment.");
+    setBubbleOffsetTop(mount, "a1", 500);
+    metrics.setScrollHeight(1400);
+    raf.flush();
+    expect(metrics.getScrollTop()).toBe(484);
+
+    // Interleaved: tool, then a second text segment. The anchor stays on the
+    // first unread block — later blocks stream in below it.
+    emitToolMessage(controller, "t0");
+    emitStreamingAssistant(controller, "a2", "Second segment.");
+    setBubbleOffsetTop(mount, "a2", 900);
+    metrics.setScrollHeight(1800);
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(484);
+    controller.destroy();
+  });
+
+  it("stands down once the reader scrolls", () => {
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(mount, anchorTopConfig());
+    const sc = getScrollContainer(mount);
+    const metrics = installScrollMetrics(sc, { scrollHeight: 1000, clientHeight: 400 });
+
+    startTurn(controller, mount, raf);
+    for (let i = 0; i < 6; i += 1) emitToolMessage(controller, `t${i}`);
+    metrics.setScrollHeight(1500);
+    raf.flush();
+
+    // The reader takes over: wheels down to watch the tools run. Engagement
+    // is keyed on real input, NOT on the scroll event (streaming content
+    // clamps and restores scrollTop on its own — see the regression test
+    // below), so the wheel is what must register here.
+    metrics.setScrollTop(520);
+    sc.dispatchEvent(new WheelEvent("wheel", { deltaY: -120, bubbles: true }));
+    sc.dispatchEvent(new Event("scroll"));
+
+    emitStreamingAssistant(controller, "a1", "Good news — your order is on track.");
+    setBubbleOffsetTop(mount, "a1", 700);
+    raf.flush();
+
+    // Their position wins: no re-anchor under them.
+    expect(metrics.getScrollTop()).toBe(520);
+    controller.destroy();
+  });
+
+  it("re-arms on the next send after the reader scrolled away", () => {
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(mount, anchorTopConfig());
+    const sc = getScrollContainer(mount);
+    const metrics = installScrollMetrics(sc, { scrollHeight: 1000, clientHeight: 400 });
+
+    startTurn(controller, mount, raf);
+    metrics.setScrollTop(520);
+    sc.dispatchEvent(new WheelEvent("wheel", { deltaY: -120, bubbles: true }));
+    sc.dispatchEvent(new Event("scroll"));
+
+    // A new send is an explicit "take me along".
+    emitUserMessage(controller, "u2", "And the second order?");
+    setBubbleOffsetTop(mount, "u2", 600);
+    metrics.setScrollHeight(1400);
+    raf.flush();
+
+    emitStreamingAssistant(controller, "a2", "That one shipped Tuesday.");
+    setBubbleOffsetTop(mount, "a2", 800);
+    metrics.setScrollHeight(1600);
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(784);
+    controller.destroy();
+  });
+});
+
+// Two shapes the browser testbed covers but that are worth pinning down here,
+// since they are where the policy's judgement calls actually bite.
+describe("anchor-top first-unread — edge shapes", () => {
+  beforeEach(() => {
+    installRafMock();
+  });
+
+  const anchorTopConfig = () =>
+    baseConfig({
+      features: { scrollBehavior: { mode: "anchor-top", anchorTopOffset: 16 } },
+    });
+
+  const emitTool = (
+    controller: ReturnType<typeof createAgentExperience>,
+    id: string
+  ) => {
+    controller.injectTestMessage({
+      type: "message",
+      message: {
+        id,
+        role: "assistant",
+        content: "",
+        createdAt: CREATED_AT,
+        variant: "tool",
+        toolCall: { id, name: "search", status: "complete" },
+      },
+    });
+  };
+
+  const setTop = (mount: HTMLElement, id: string, value: number) => {
+    const bubble = getScrollContainer(mount).querySelector<HTMLElement>(
+      `[data-message-id="${id}"]`
+    );
+    expect(bubble).not.toBeNull();
+    Object.defineProperty(bubble!, "offsetTop", { configurable: true, value });
+  };
+
+  // KNOWN TRADEOFF: a chatty preamble ("Let me look that up…") is itself the
+  // first unread block, so the anchor lands there and the tool run still
+  // pushes the real answer toward the fold. That is the policy behaving as
+  // specified — chronological, honest about what arrived first — but it is
+  // the case most likely to want revisiting.
+  it("anchors a preamble, not the answer that follows the tool run", () => {
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(mount, anchorTopConfig());
+    const metrics = installScrollMetrics(getScrollContainer(mount), {
+      scrollHeight: 1000,
+      clientHeight: 400,
+    });
+
+    emitAssistantMessage(controller, "seed", "Earlier reply");
+    emitUserMessage(controller, "u1", "Look into my order");
+    setTop(mount, "u1", 300);
+    raf.flush();
+
+    emitStreamingAssistant(controller, "pre", "Sure — let me pull that up.");
+    setTop(mount, "pre", 420);
+    metrics.setScrollHeight(1200);
+    raf.flush();
+    expect(metrics.getScrollTop()).toBe(404);
+
+    for (let i = 0; i < 6; i += 1) emitTool(controller, `t${i}`);
+    emitStreamingAssistant(controller, "answer", "Good news — it is on track.");
+    setTop(mount, "answer", 900);
+    metrics.setScrollHeight(1800);
+    raf.flush();
+
+    // Still parked on the preamble: the answer is NOT re-targeted.
+    expect(metrics.getScrollTop()).toBe(404);
+    controller.destroy();
+  });
+
+  it("holds the sent message when a turn produces only tool calls", () => {
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(mount, anchorTopConfig());
+    const metrics = installScrollMetrics(getScrollContainer(mount), {
+      scrollHeight: 1000,
+      clientHeight: 400,
+    });
+
+    emitAssistantMessage(controller, "seed", "Earlier reply");
+    emitUserMessage(controller, "u1", "Just refresh the tracking data");
+    setTop(mount, "u1", 300);
+    raf.flush();
+    expect(metrics.getScrollTop()).toBe(284);
+
+    for (let i = 0; i < 6; i += 1) emitTool(controller, `t${i}`);
+    metrics.setScrollHeight(1600);
+    raf.flush();
+
+    // Nothing attention-worthy ever arrived: never chase the tool bubbles.
+    expect(metrics.getScrollTop()).toBe(284);
+    controller.destroy();
+  });
+});
+
+// Regression: streaming content under a pinned anchor makes the browser clamp
+// scrollTop and then restore it — a matched pair of real scroll events with no
+// user involved (observed live as -12 then +12 during a tool run). Treating
+// those as reader intent silently disabled every later re-anchor, so a
+// response that opened with tool calls stayed stuck on the sent message.
+describe("anchor-top first-unread — layout scroll is not reader intent", () => {
+  beforeEach(() => {
+    installRafMock();
+  });
+
+  it("still anchors the answer after a clamp/restore scroll pair", () => {
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(
+      mount,
+      baseConfig({
+        features: { scrollBehavior: { mode: "anchor-top", anchorTopOffset: 16 } },
+      })
+    );
+    const sc = getScrollContainer(mount);
+    const metrics = installScrollMetrics(sc, { scrollHeight: 1000, clientHeight: 400 });
+
+    emitAssistantMessage(controller, "seed", "Earlier reply");
+    emitUserMessage(controller, "u1", "Where is my order?");
+    const userBubble = sc.querySelector<HTMLElement>('[data-message-id="u1"]');
+    Object.defineProperty(userBubble!, "offsetTop", { configurable: true, value: 300 });
+    raf.flush();
+    expect(metrics.getScrollTop()).toBe(284);
+
+    // Tool run: the spacer shrinks, scrollTop is clamped down, then the
+    // growing transcript restores it. Both are layout, not the reader.
+    for (let i = 0; i < 6; i += 1) {
+      controller.injectTestMessage({
+        type: "message",
+        message: {
+          id: `t${i}`,
+          role: "assistant",
+          content: "",
+          createdAt: CREATED_AT,
+          variant: "tool",
+          toolCall: { id: `t${i}`, name: "search", status: "complete" },
+        },
+      });
+    }
+    metrics.setScrollTop(272);
+    sc.dispatchEvent(new Event("scroll"));
+    metrics.setScrollHeight(1500);
+    metrics.setScrollTop(284);
+    sc.dispatchEvent(new Event("scroll"));
+    raf.flush();
+
+    emitStreamingAssistant(controller, "a1", "Good news — your order is on track.");
+    const answer = sc.querySelector<HTMLElement>('[data-message-id="a1"]');
+    Object.defineProperty(answer!, "offsetTop", { configurable: true, value: 700 });
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(684);
+    controller.destroy();
+  });
+});

package/src/ui.scroll.test.ts

@@ -991,7 +991,7 @@ describe("createAgentExperience streaming scroll", () => {
     controller.destroy();
   });
 
-  it("anchor-top mode pins the sent user message near the viewport top and never follows the stream", () => {
+  it("anchor-top mode pins the turn's first unread block near the viewport top and never follows the stream", () => {
     const raf = installRafMock();
     const resize = installResizeObserverMock();
     const mount = createMount();
@@ -1034,16 +1034,29 @@ describe("createAgentExperience streaming scroll", () => {
     raf.flush();
     expect(metrics.getScrollTop()).toBe(684);
 
-    // Streaming below the anchor never moves the viewport.
-    metrics.setScrollHeight(1150);
+    // The response's first block is the turn's first unread output, so the
+    // anchor hands off to it: target = 900 - 16 = 884, and with content at
+    // 1284 - 84 = 1200 the spacer re-sizes to 884 + 400 - 1200 = 84.
+    metrics.setScrollHeight(1284);
     emitStreamingMessage(controller, "Streaming response");
+    const streamBubble = scrollContainer!.querySelector<HTMLElement>(
+      `[data-message-id="${STREAM_MESSAGE_ID}"]`
+    );
+    expect(streamBubble).not.toBeNull();
+    Object.defineProperty(streamBubble!, "offsetTop", { value: 900 });
     raf.flush();
-    expect(metrics.getScrollTop()).toBe(684);
+    expect(metrics.getScrollTop()).toBe(884);
+
+    // Continuing to stream below that anchor never moves the viewport again.
+    metrics.setScrollHeight(1324);
+    emitStreamingMessage(controller, "Streaming response, now longer");
+    raf.flush();
+    expect(metrics.getScrollTop()).toBe(884);
 
     // As real content grows, the spacer gives room back (shrink-only):
-    // content grew from 1000 to 1150 - 84 = 1066, so spacer 84 - 66 = 18.
+    // content grew from 1200 to 1324 - 84 = 1240, so spacer 84 - 40 = 44.
     resize.trigger();
-    expect(spacer?.style.height).toBe("18px");
+    expect(spacer?.style.height).toBe("44px");
 
     // Jumping to the latest abandons the anchor: the spacer is dropped so
     // "bottom" is the real end of content.

package/src/ui.ts

@@ -64,6 +64,7 @@ import {
   createFollowStateController,
   getScrollBottomOffset,
   hasSelectionWithin,
+  isAttentionWorthyMessage,
   isElementNearBottom,
   resolveFollowStateFromScroll,
   resolveFollowStateFromWheel
@@ -3537,6 +3538,24 @@ export const createAgentExperience = (
   // pinned and never re-arms the fallback, so a late-loading embed can't yank
   // the viewport down to the bottom.
   let currentTurnAnchored = false;
+  // Which message the anchor is currently parked on. Starts as the sent user
+  // message and moves once to the turn's first attention-worthy block (see
+  // `maybeAnchorToFirstUnread`).
+  let anchoredMessageId: string | null = null;
+  // Has the reader taken over positioning this turn? First-unread anchoring is
+  // a guess about where someone who ISN'T watching wants to land; the moment
+  // they demonstrably are watching, the guess stands down and never moves the
+  // viewport under them. Reset on each user send (an explicit "take me along").
+  //
+  // Driven by real INPUT (wheel, touch drag, pointer press, transcript
+  // keyboard nav, focus, selection) rather than by scroll deltas: streaming
+  // content under a pinned anchor makes the browser clamp and then restore
+  // scrollTop, which is indistinguishable from a deliberate scroll if you only
+  // look at the scroll event.
+  let readerEngagedThisTurn = false;
+  const markReaderEngaged = () => {
+    readerEngagedThisTurn = true;
+  };
   // Dedupes assistant-turn detection across token-by-token re-renders.
   let lastHandledAssistantId: string | null = null;
 
@@ -3940,6 +3959,24 @@ export const createAgentExperience = (
     return top;
   };
 
+  // Defined here (rather than beside the scroll listeners) because
+  // `maybeAnchorToFirstUnread` runs on every render and would otherwise hit
+  // these consts in their temporal dead zone on a synchronous first paint.
+  const getTranscriptSelection = (): Selection | null => {
+    // Selections inside a shadow root are not always reflected by
+    // document.getSelection(); prefer the shadow root's view when available
+    // (non-standard but supported where it matters).
+    const root = body.getRootNode();
+    const shadowSelection =
+      typeof (root as ShadowRoot & { getSelection?: () => Selection | null })
+        .getSelection === "function"
+        ? (root as ShadowRoot & { getSelection: () => Selection | null }).getSelection()
+        : null;
+    return shadowSelection ?? body.ownerDocument.getSelection();
+  };
+  const hasActiveTranscriptSelection = () =>
+    hasSelectionWithin(getTranscriptSelection(), body);
+
   // Principle 11: reopen where the reader left off. When `restorePosition` is
   // "last-user-turn" and there is pre-existing history, land with the last user
   // message pinned near the top of the viewport instead of jumping to the
@@ -4002,11 +4039,10 @@ export const createAgentExperience = (
     anchorSpacer.style.height = "0px";
   };
 
-  // Anchor-top mode: scroll the just-sent user message to rest
-  // `anchorTopOffset` px below the viewport top and hold it there while the
-  // response streams in beneath it. Deferred one frame so the message bubble
-  // has been rendered and laid out.
-  const scheduleAnchorToUserMessage = (messageId: string) => {
+  // Anchor-top mode: scroll `messageId` to rest `anchorTopOffset` px below the
+  // viewport top and hold it there while the response streams in beneath it.
+  // Deferred one frame so the message bubble has been rendered and laid out.
+  const scheduleAnchorToMessage = (messageId: string) => {
     if (anchorRAF !== null) {
       cancelAnimationFrame(anchorRAF);
     }
@@ -4087,7 +4123,11 @@ export const createAgentExperience = (
       // next user send.
       followFallbackActive = false;
       currentTurnAnchored = true;
-      scheduleAnchorToUserMessage(messageId);
+      // A send is an explicit "take me along": it re-arms first-unread
+      // positioning even if the reader had scrolled away during the last turn.
+      readerEngagedThisTurn = false;
+      anchoredMessageId = messageId;
+      scheduleAnchorToMessage(messageId);
     }
   };
 
@@ -4110,6 +4150,44 @@ export const createAgentExperience = (
     scheduleAutoScroll(true);
   };
 
+  // Anchor-top positioning: park on the turn's FIRST UNREAD attention-worthy
+  // block.
+  //
+  // The read boundary is the last user send — the reader wrote it, so it (and
+  // everything above) is read; every attention-worthy block after it is not.
+  // Tool calls and reasoning are chrome and never targeted, so they scroll
+  // past underneath rather than parking the reader on progress output.
+  //
+  // The policy assumes the reader is NOT watching the stream, and picks the
+  // best place for them to land when they look back: the start of what they
+  // haven't seen. `readerEngagedThisTurn` is the escape hatch — once someone
+  // is demonstrably driving, their position wins and this stands down until
+  // the next send.
+  //
+  // Anchoring to the first unread (not the newest) block means this fires at
+  // most once per turn in practice, and later blocks stream in below the
+  // anchor exactly as they do today.
+  const maybeAnchorToFirstUnread = (messages: AgentWidgetMessage[]) => {
+    if (getScrollMode() !== "anchor-top") return;
+    if (!currentTurnAnchored) return;
+    if (readerEngagedThisTurn) return;
+    if (hasActiveTranscriptSelection()) return;
+
+    let pastReadBoundary = lastSentUserMessageId === null;
+    for (const message of messages) {
+      if (!pastReadBoundary) {
+        if (message.id === lastSentUserMessageId) pastReadBoundary = true;
+        continue;
+      }
+      if (!isAttentionWorthyMessage(message)) continue;
+      // Already parked on it: hold still while it streams.
+      if (message.id === anchoredMessageId) return;
+      anchoredMessageId = message.id;
+      scheduleAnchorToMessage(message.id);
+      return;
+    }
+  };
+
   const trackMessages = (messages: AgentWidgetMessage[]) => {
     const nextState = new Map<
       string,
@@ -5998,6 +6076,8 @@ export const createAgentExperience = (
       resetAnchorState();
       followFallbackActive = true;
       currentTurnAnchored = false;
+      anchoredMessageId = null;
+      readerEngagedThisTurn = false;
     }
     if (!scrollSendSeeded || suppressScrollSend) {
       scrollSendSeeded = true;
@@ -6013,6 +6093,7 @@ export const createAgentExperience = (
       handleAssistantTurnStarted();
     }
     if (lastAssistantMessage) lastHandledAssistantId = lastAssistantMessage.id;
+    maybeAnchorToFirstUnread(messages);
 
     const prevLastUserMessageId = voiceState.lastUserMessageId;
     if (lastUserMessage && lastUserMessage.id !== prevLastUserMessageId) {
@@ -7341,21 +7422,6 @@ export const createAgentExperience = (
   lastScrollTop = body.scrollTop;
   let lastBottomOffset = getScrollBottomOffset(body);
 
-  const getTranscriptSelection = (): Selection | null => {
-    // Selections inside a shadow root are not always reflected by
-    // document.getSelection(); prefer the shadow root's view when available
-    // (non-standard but supported where it matters).
-    const root = body.getRootNode();
-    const shadowSelection =
-      typeof (root as ShadowRoot & { getSelection?: () => Selection | null })
-        .getSelection === "function"
-        ? (root as ShadowRoot & { getSelection: () => Selection | null }).getSelection()
-        : null;
-    return shadowSelection ?? body.ownerDocument.getSelection();
-  };
-  const hasActiveTranscriptSelection = () =>
-    hasSelectionWithin(getTranscriptSelection(), body);
-
   const handleScroll = () => {
     const scrollTop = body.scrollTop;
     // When content mutates (e.g. stream-animation plugins re-rendering text)
@@ -7373,6 +7439,14 @@ export const createAgentExperience = (
     if (!isFollowEffective()) {
       // No follow state to manage (anchored anchor-top / none): just keep the
       // scroll-to-bottom affordance in sync with the user's position.
+      //
+      // Reader intent is deliberately NOT inferred from scroll deltas here.
+      // Growing the transcript under a pinned anchor makes the browser clamp
+      // scrollTop and then restore it, which lands as a matched pair of real
+      // scroll events (e.g. -12 then +12) with no user involved. The restore
+      // arrives while the bottom offset is GROWING, so the shrink mask above
+      // doesn't cover it, and it reads as a deliberate scroll. Engagement is
+      // tracked from actual input instead (see `markReaderEngaged` callers).
       lastScrollTop = scrollTop;
       syncScrollToBottomButton();
       return;
@@ -7459,21 +7533,23 @@ export const createAgentExperience = (
     "ArrowDown",
   ]);
   const handleTranscriptKeydown = (event: KeyboardEvent) => {
+    if (!NAV_KEYS.has(event.key)) return;
+    // Reader intent for first-unread anchoring is tracked unconditionally;
+    // only the follow-mode *pause* below stays behind the opt-in flag.
+    markReaderEngaged();
     if (!isPauseOnInteractionEnabled()) return;
     if (!isFollowEffective()) return;
     if (!autoFollow.isFollowing()) return;
-    if (NAV_KEYS.has(event.key)) {
-      pauseAutoScroll();
-    }
+    pauseAutoScroll();
   };
   const handleTranscriptFocusIn = (event: FocusEvent) => {
+    const target = event.target as Element | null;
+    if (!target?.closest("a, button, [tabindex], input, textarea, select")) return;
+    markReaderEngaged();
     if (!isPauseOnInteractionEnabled()) return;
     if (!isFollowEffective()) return;
     if (!autoFollow.isFollowing()) return;
-    const target = event.target as Element | null;
-    if (target && target.closest("a, button, [tabindex], input, textarea, select")) {
-      pauseAutoScroll();
-    }
+    pauseAutoScroll();
   };
   body.addEventListener("keydown", handleTranscriptKeydown);
   body.addEventListener("focusin", handleTranscriptFocusIn);
@@ -7483,6 +7559,9 @@ export const createAgentExperience = (
   });
 
   const handleWheel = (event: WheelEvent) => {
+    // A wheel tick is unambiguous reader intent in every mode — including
+    // anchored anchor-top, where there is no follow state to pause.
+    if (event.deltaY !== 0) markReaderEngaged();
     if (!isFollowEffective()) return;
     const action = resolveFollowStateFromWheel({
       following: autoFollow.isFollowing(),
@@ -7498,6 +7577,14 @@ export const createAgentExperience = (
     }
   };
   body.addEventListener("wheel", handleWheel, { passive: true });
+  // Touch drag and pointer press (scrollbar drags, tapping a tool bubble open)
+  // are the remaining ways a reader takes over without a wheel or key event.
+  body.addEventListener("touchmove", markReaderEngaged, { passive: true });
+  body.addEventListener("pointerdown", markReaderEngaged, { passive: true });
+  destroyCallbacks.push(() => {
+    body.removeEventListener("touchmove", markReaderEngaged);
+    body.removeEventListener("pointerdown", markReaderEngaged);
+  });
   destroyCallbacks.push(() => body.removeEventListener("wheel", handleWheel));
   scrollToBottomButton.addEventListener("click", () => {
     // Jumping to the latest abandons the current anchor: drop the spacer