@runtypelabs/persona 3.30.0 → 3.31.1

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

@@ -1,8 +1,11 @@
 import { describe, expect, it } from "vitest";
 
 import {
+  computeAnchorScrollState,
+  computeShrunkSpacerHeight,
   createFollowStateController,
   getScrollBottomOffset,
+  hasSelectionWithin,
   isElementNearBottom,
   resolveFollowStateFromScroll,
   resolveFollowStateFromWheel
@@ -90,6 +93,94 @@ describe("auto-follow utilities", () => {
     expect(resume.action).toBe("resume");
   });
 
+  it("detects an active selection touching the container", () => {
+    const inside = { name: "inside" } as unknown as Node;
+    const outside = { name: "outside" } as unknown as Node;
+    const container = {
+      contains: (node: Node | null) => node === inside
+    };
+
+    expect(hasSelectionWithin(null, container)).toBe(false);
+    expect(
+      hasSelectionWithin(
+        { isCollapsed: true, anchorNode: inside, focusNode: inside },
+        container
+      )
+    ).toBe(false);
+    expect(
+      hasSelectionWithin(
+        { isCollapsed: false, anchorNode: outside, focusNode: outside },
+        container
+      )
+    ).toBe(false);
+    expect(
+      hasSelectionWithin(
+        { isCollapsed: false, anchorNode: inside, focusNode: outside },
+        container
+      )
+    ).toBe(true);
+    expect(
+      hasSelectionWithin(
+        { isCollapsed: false, anchorNode: outside, focusNode: inside },
+        container
+      )
+    ).toBe(true);
+  });
+
+  it("computes anchor-top scroll geometry", () => {
+    // Anchored message deep in the transcript: spacer fills the shortfall so
+    // the target position is reachable.
+    expect(
+      computeAnchorScrollState({
+        anchorOffsetTop: 700,
+        topOffset: 16,
+        viewportHeight: 400,
+        contentHeight: 1000
+      })
+    ).toEqual({ targetScrollTop: 684, spacerHeight: 84 });
+
+    // Message near the top of the transcript: target clamps to 0.
+    expect(
+      computeAnchorScrollState({
+        anchorOffsetTop: 10,
+        topOffset: 16,
+        viewportHeight: 400,
+        contentHeight: 1000
+      }).targetScrollTop
+    ).toBe(0);
+
+    // Already enough content below: no spacer needed.
+    expect(
+      computeAnchorScrollState({
+        anchorOffsetTop: 500,
+        topOffset: 16,
+        viewportHeight: 400,
+        contentHeight: 2000
+      }).spacerHeight
+    ).toBe(0);
+  });
+
+  it("shrinks the anchor spacer as content grows, never below zero or above initial", () => {
+    const base = {
+      initialSpacerHeight: 100,
+      contentHeightAtAnchor: 1000
+    };
+
+    expect(
+      computeShrunkSpacerHeight({ ...base, currentContentHeight: 1000 })
+    ).toBe(100);
+    expect(
+      computeShrunkSpacerHeight({ ...base, currentContentHeight: 1040 })
+    ).toBe(60);
+    expect(
+      computeShrunkSpacerHeight({ ...base, currentContentHeight: 1500 })
+    ).toBe(0);
+    // Content shrank (e.g. a collapsed tool row): spacer never grows back.
+    expect(
+      computeShrunkSpacerHeight({ ...base, currentContentHeight: 900 })
+    ).toBe(100);
+  });
+
   it("resolves wheel intent for pause and resume", () => {
     expect(
       resolveFollowStateFromWheel({

package/src/utils/auto-follow.ts

@@ -110,3 +110,71 @@ export function resolveFollowStateFromWheel(
 
   return "none";
 }
+
+export type SelectionLike = Pick<Selection, "isCollapsed"> & {
+  anchorNode: Node | null;
+  focusNode: Node | null;
+};
+
+/**
+ * True when the user has a non-collapsed text selection that touches the
+ * given container. Used to pause auto-follow while the user is selecting
+ * transcript text, so the streaming scroll doesn't drag content out from
+ * under an in-progress drag-selection.
+ */
+export function hasSelectionWithin(
+  selection: SelectionLike | null,
+  container: Pick<Node, "contains">
+): boolean {
+  if (!selection || selection.isCollapsed) return false;
+  return (
+    container.contains(selection.anchorNode) ||
+    container.contains(selection.focusNode)
+  );
+}
+
+export type AnchorScrollInput = {
+  /** Top of the anchored user message, relative to the scroll content. */
+  anchorOffsetTop: number;
+  /** Desired gap kept between the anchored message and the viewport top. */
+  topOffset: number;
+  /** clientHeight of the scroll container. */
+  viewportHeight: number;
+  /** scrollHeight of the scroll container, excluding any anchor spacer. */
+  contentHeight: number;
+};
+
+/**
+ * Geometry for anchor-top ("pin the sent user message near the viewport
+ * top") scrolling. The spacer height is the extra scrollable room needed so
+ * the target scroll position is reachable before the streamed response has
+ * grown tall enough to provide it naturally.
+ */
+export function computeAnchorScrollState(input: AnchorScrollInput): {
+  targetScrollTop: number;
+  spacerHeight: number;
+} {
+  const targetScrollTop = Math.max(0, input.anchorOffsetTop - input.topOffset);
+  const spacerHeight = Math.max(
+    0,
+    targetScrollTop + input.viewportHeight - input.contentHeight
+  );
+  return { targetScrollTop, spacerHeight };
+}
+
+/**
+ * Shrink-only spacer update: as streamed content grows beneath the anchored
+ * message, the spacer gives back exactly that much room so total scroll
+ * height stays constant and nothing jumps. Never grows after anchoring.
+ */
+export function computeShrunkSpacerHeight(input: {
+  initialSpacerHeight: number;
+  contentHeightAtAnchor: number;
+  currentContentHeight: number;
+}): number {
+  const growth = Math.max(
+    0,
+    input.currentContentHeight - input.contentHeightAtAnchor
+  );
+  return Math.max(0, input.initialSpacerHeight - growth);
+}

package/src/version.ts

@@ -1,7 +1,10 @@
-import packageJson from "../package.json";
+// Named import (not default) so esbuild tree-shakes the JSON module down to
+// the one field we read — a default import inlines the entire package.json
+// (~4.8 kB minified) into every bundle.
+import { version } from "../package.json";
 
 /**
  * The current version of the @runtypelabs/persona package.
  * This is automatically derived from package.json.
  */
-export const VERSION = packageJson.version;
+export const VERSION = version;

package/src/webmcp-bridge.test.ts

@@ -31,6 +31,7 @@ import {
   isWebMcpToolName,
   stripWebMcpPrefix,
   computeClientToolsFingerprint,
+  setWebMcpPolyfillLoader,
 } from "./webmcp-bridge";
 import type { ClientToolDefinition } from "./types";
 
@@ -114,6 +115,9 @@ beforeEach(() => {
 
 afterEach(() => {
   vi.unstubAllGlobals();
+  // The loader is module-global (page-global in production); reset so a test
+  // that registers one can't leak into the default-import tests.
+  setWebMcpPolyfillLoader(null);
 });
 
 describe("stripWebMcpPrefix", () => {
@@ -150,6 +154,9 @@ describe("WebMcpBridge.snapshotForDispatch", () => {
   });
 
   it("returns empty when initializeWebMCPPolyfill() throws", async () => {
+    // No pre-existing modelContext — otherwise install() short-circuits
+    // before importing the polyfill and the throwing init never runs.
+    vi.stubGlobal("document", {});
     polyfillMock.initThrows = true;
     const bridge = new WebMcpBridge({ enabled: true });
     expect(await bridge.snapshotForDispatch()).toEqual([]);
@@ -204,6 +211,59 @@ describe("WebMcpBridge.snapshotForDispatch", () => {
   });
 });
 
+describe("setWebMcpPolyfillLoader", () => {
+  it("uses the registered loader instead of the bare import when no modelContext exists", async () => {
+    // Start with no modelContext so install() actually loads the polyfill;
+    // the loader's init then installs the registry, like the real one would.
+    const doc: { modelContext?: ReturnType<typeof makeModelContext> } = {};
+    vi.stubGlobal("document", doc);
+    registry.tools = [fakeTool({ name: "search" })];
+    const loader = vi.fn(async () => ({
+      initializeWebMCPPolyfill: () => {
+        doc.modelContext = makeModelContext();
+      },
+    }));
+    setWebMcpPolyfillLoader(loader);
+
+    const bridge = new WebMcpBridge({ enabled: true });
+    const snap = await bridge.snapshotForDispatch();
+
+    expect(loader).toHaveBeenCalledTimes(1);
+    expect(snap.map((t) => t.name)).toEqual(["search"]);
+    expect(bridge.isOperational()).toBe(true);
+  });
+
+  it("disables WebMCP (with a warning) when the loader rejects", async () => {
+    vi.stubGlobal("document", {});
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    setWebMcpPolyfillLoader(() => Promise.reject(new Error("chunk 404")));
+
+    const bridge = new WebMcpBridge({ enabled: true });
+    expect(await bridge.snapshotForDispatch()).toEqual([]);
+    expect(bridge.isOperational()).toBe(false);
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining("Failed to load @mcp-b/webmcp-polyfill"),
+      expect.any(Error),
+    );
+    warn.mockRestore();
+  });
+
+  it("never invokes the loader when a compatible modelContext is already present", async () => {
+    // beforeEach stubs a compatible document.modelContext — the install
+    // short-circuit must win, so a failing loader is irrelevant.
+    registry.tools = [fakeTool({ name: "search" })];
+    const loader = vi.fn(() => Promise.reject(new Error("should not load")));
+    setWebMcpPolyfillLoader(loader);
+
+    const bridge = new WebMcpBridge({ enabled: true });
+    const snap = await bridge.snapshotForDispatch();
+
+    expect(loader).not.toHaveBeenCalled();
+    expect(snap.map((t) => t.name)).toEqual(["search"]);
+    expect(bridge.isOperational()).toBe(true);
+  });
+});
+
 describe("WebMCP display titles", () => {
   it("records declared titles on snapshot and exposes them via getWebMcpToolDisplayTitle", async () => {
     registry.tools = [

package/src/webmcp-bridge.ts

@@ -131,6 +131,28 @@ const log = {
   },
 };
 
+/** The slice of `@mcp-b/webmcp-polyfill` the bridge consumes on install. */
+export type WebMcpPolyfillModule = {
+  initializeWebMCPPolyfill: () => void;
+};
+
+/**
+ * Override how the polyfill module is obtained. By default the bridge does
+ * `import("@mcp-b/webmcp-polyfill")`, which bundlers resolve for npm
+ * consumers. The IIFE/CDN build can't resolve a bare specifier at runtime, so
+ * its entry (`index-global.ts`) registers a loader that imports the
+ * self-contained `webmcp-polyfill.js` chunk from a URL derived from the
+ * widget script's own `src`. Page-global, like `document.modelContext`
+ * itself. Pass `null` to restore the default (used by tests).
+ */
+let polyfillLoader: (() => Promise<WebMcpPolyfillModule>) | null = null;
+
+export const setWebMcpPolyfillLoader = (
+  loader: (() => Promise<WebMcpPolyfillModule>) | null,
+): void => {
+  polyfillLoader = loader;
+};
+
 /**
  * Compute a stable, order-independent fingerprint of a `ClientToolDefinition[]`
  * snapshot, for the diff-only / send-once dispatch path (client-token mode).
@@ -449,7 +471,18 @@ export class WebMcpBridge {
 
   private async install(): Promise<void> {
     try {
-      const mod = await import("@mcp-b/webmcp-polyfill");
+      // A compatible registry is already on the page (the host installed the
+      // polyfill, or a native impl) — initialize would no-op against it, so
+      // skip loading the module entirely. Pages that register tools before
+      // Persona's first dispatch always land here, because registering
+      // requires `document.modelContext` to exist.
+      if (this.getModelContext()) {
+        this.installed = true;
+        return;
+      }
+      const mod = polyfillLoader
+        ? await polyfillLoader()
+        : await import("@mcp-b/webmcp-polyfill");
       // Idempotent: no-ops if `document.modelContext` already exists (native or
       // a prior install by the host page).
       mod.initializeWebMCPPolyfill();

package/src/webmcp-polyfill.ts

@@ -0,0 +1,16 @@
+/**
+ * Standalone WebMCP polyfill chunk (`dist/webmcp-polyfill.js`).
+ *
+ * The IIFE/CDN widget bundle marks `@mcp-b/webmcp-polyfill` external so the
+ * ~35 kB (minified) polyfill + its transitive `@cfworker/json-schema` never
+ * ship to consumers who don't enable WebMCP. When `config.webmcp.enabled` is
+ * true and no `document.modelContext` exists yet, the bridge dynamically
+ * imports this chunk from a URL derived from the widget script's own `src`
+ * (see the loader registered in `index-global.ts`).
+ *
+ * Built self-contained (`--no-external`) — it must work standalone on a CDN
+ * with no module resolution. npm/bundler consumers never load this file;
+ * their bundlers resolve the bare `import("@mcp-b/webmcp-polyfill")` in
+ * `webmcp-bridge.ts` directly.
+ */
+export { initializeWebMCPPolyfill } from "@mcp-b/webmcp-polyfill";