@runtypelabs/persona 4.11.1 → 4.13.0

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

package/src/utils/auto-follow.test.ts

@@ -6,10 +6,12 @@ import {
   createFollowStateController,
   getScrollBottomOffset,
   hasSelectionWithin,
+  isAttentionWorthyMessage,
   isElementNearBottom,
   resolveFollowStateFromScroll,
   resolveFollowStateFromWheel
 } from "./auto-follow";
+import type { AgentWidgetMessage } from "../types";
 
 describe("auto-follow utilities", () => {
   it("tracks pause and resume state", () => {
@@ -199,3 +201,39 @@ describe("auto-follow utilities", () => {
     ).toBe("resume");
   });
 });
+
+describe("isAttentionWorthyMessage", () => {
+  const msg = (over: Partial<AgentWidgetMessage>): AgentWidgetMessage => ({
+    id: "m",
+    role: "assistant",
+    content: "",
+    createdAt: "2026-07-28T00:00:00.000Z",
+    ...over,
+  });
+
+  it("treats prose, artifacts/components, images and approvals as output", () => {
+    expect(isAttentionWorthyMessage(msg({ content: "Here is the answer." }))).toBe(true);
+    // Artifact / component blocks carry their payload in rawContent with an
+    // empty `content` — the case a text-only test silently drops.
+    expect(
+      isAttentionWorthyMessage(msg({ rawContent: '{"component":"Chart","props":{}}' }))
+    ).toBe(true);
+    expect(
+      isAttentionWorthyMessage(
+        msg({ contentParts: [{ type: "image", image: "data:image/png;base64,x" }] as never })
+      )
+    ).toBe(true);
+    // Blocked on the reader deciding: must never sit off-screen.
+    expect(isAttentionWorthyMessage(msg({ variant: "approval" }))).toBe(true);
+  });
+
+  it("treats tool calls and reasoning as progress chrome", () => {
+    expect(isAttentionWorthyMessage(msg({ variant: "tool", content: "searching" }))).toBe(false);
+    expect(isAttentionWorthyMessage(msg({ variant: "reasoning", content: "thinking" }))).toBe(false);
+  });
+
+  it("skips the empty streaming placeholder and non-assistant roles", () => {
+    expect(isAttentionWorthyMessage(msg({ content: "   " }))).toBe(false);
+    expect(isAttentionWorthyMessage(msg({ role: "user", content: "hi" }))).toBe(false);
+  });
+});

package/src/utils/auto-follow.ts

@@ -1,3 +1,38 @@
+import type { AgentWidgetMessage } from "../types";
+
+/**
+ * Is this message *output a human came for*, as opposed to progress chrome?
+ *
+ * This is the classifier behind anchor-top's "first unread" positioning: the
+ * transcript anchors to the first attention-worthy block of a response and
+ * leaves everything else to scroll past underneath. Two categories:
+ *
+ * - **Chrome** — tool calls and reasoning. Rendered so the reader *can* audit
+ *   the work, never positioned to. A response that opens with six tool calls
+ *   should not park the reader on the sixth one.
+ * - **Attention-worthy** — anything that carries the answer: prose, an
+ *   artifact or component block (charts, forms, documents — these carry their
+ *   payload in `rawContent` with an EMPTY `content`, so testing text alone
+ *   silently drops them), multi-modal parts (images), and approval requests
+ *   (which are the strongest case of all: the turn is blocked on the reader
+ *   deciding, so it must never sit off-screen).
+ *
+ * The empty streaming placeholder — an assistant bubble created at
+ * `text_start` before its first token — is deliberately NOT attention-worthy,
+ * so the anchor waits for content rather than jumping to a blank bubble.
+ */
+export function isAttentionWorthyMessage(message: AgentWidgetMessage): boolean {
+  if (message.role !== "assistant") return false;
+  if (message.variant === "tool" || message.variant === "reasoning") return false;
+  // Blocked on the reader: attention-worthy even with no text of its own.
+  if (message.variant === "approval") return true;
+  return Boolean(
+    message.content?.trim() ||
+      message.rawContent?.trim() ||
+      message.contentParts?.length
+  );
+}
+
 export type FollowStateAction = "none" | "pause" | "resume";
 
 export type FollowStateController = {

package/src/utils/code-generators.ts

@@ -151,8 +151,33 @@ export type CodeGeneratorOptions = {
    * @default "body"
    */
   target?: string;
+
+  /**
+   * Base URL of the directory holding the widget assets (install.global.js,
+   * index.global.js, widget.css) for the script formats (script-installer,
+   * script-manual, script-advanced). Pass a first-party base such as
+   * "https://cdn.runtype.com/persona/latest" when the embedding page's CSP
+   * does not allow third-party CDNs. A trailing slash is tolerated.
+   * @default the jsDelivr dist directory pinned to this package version
+   */
+  cdnBase?: string;
 };
 
+/**
+ * Asset directory for script formats: explicit cdnBase or the version-pinned
+ * jsDelivr dist. The base is emitted into single-quoted JS literals AND
+ * double-quoted HTML attributes, so percent-encode the characters that could
+ * break out of either context. All of them are illegal unencoded in a URL
+ * (RFC 3986), so encoding never changes the meaning of a valid base URL.
+ */
+function resolveCdnBase(options?: CodeGeneratorOptions): string {
+  const base = options?.cdnBase
+    ?.trim()
+    .replace(/\/+$/, "")
+    .replace(/[\\'"<>`]/g, (ch) => `%${ch.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`);
+  return base || `https://cdn.jsdelivr.net/npm/@runtypelabs/persona@${VERSION}/dist`;
+}
+
 // Internal type for normalized hooks (always strings)
 type NormalizedHooks = {
   [K in keyof CodeGeneratorHooks]: string | undefined;
@@ -1402,7 +1427,7 @@ function generateScriptInstallerCode(config: any, options?: CodeGeneratorOptions
   // Escape single quotes in JSON for HTML attribute
   const configJson = JSON.stringify(payload, null, 0).replace(/'/g, "&#39;");
 
-  return `<script src="https://cdn.jsdelivr.net/npm/@runtypelabs/persona@${VERSION}/dist/install.global.js" data-config='${configJson}'></script>`;
+  return `<script src="${resolveCdnBase(options)}/install.global.js" data-config='${configJson}'></script>`;
 }
 
 function generateScriptManualCode(config: any, options?: CodeGeneratorOptions): string {
@@ -1410,12 +1435,13 @@ function generateScriptManualCode(config: any, options?: CodeGeneratorOptions):
   const parserType = getParserTypeFromConfig(config as AgentWidgetConfig);
   const shouldEmitParserType = parserType !== "plain";
 
+  const cdnBase = resolveCdnBase(options);
   const lines: string[] = [
     "<!-- Load CSS -->",
-    `<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@runtypelabs/persona@${VERSION}/dist/widget.css" />`,
+    `<link rel="stylesheet" href="${cdnBase}/widget.css" />`,
     "",
     "<!-- Load JavaScript -->",
-    `<script src="https://cdn.jsdelivr.net/npm/@runtypelabs/persona@${VERSION}/dist/index.global.js"></script>`,
+    `<script src="${cdnBase}/index.global.js"></script>`,
     "",
     "<!-- Initialize widget -->",
     "<script>",
@@ -1565,7 +1591,7 @@ function generateScriptAdvancedCode(config: any, options?: CodeGeneratorOptions)
     `  var CONFIG = ${configJson.split('\n').map((line, i) => i === 0 ? line : '  ' + line).join('\n')};`,
     "",
     "  // Constants",
-    `  var CDN_BASE = 'https://cdn.jsdelivr.net/npm/@runtypelabs/persona@${VERSION}/dist';`,
+    `  var CDN_BASE = '${resolveCdnBase(options)}';`,
     "  var STORAGE_KEY = 'chat-widget-state';",
     "  var PROCESSED_ACTIONS_KEY = 'chat-widget-processed-actions';",
     "",