@agent-native/core-corpus 0.204.1-nightly-20261008153353 → 0.205.0

package/corpus/README.md

@@ -32,4 +32,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core-corpus/corpu
 
 ## Generated Counts
 
-- template files: 11511
+- template files: 11555

package/corpus/templates/analytics/.agents/skills/onboarding-journeys/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: onboarding-journeys
+description: >-
+  Build the onboarding journey tree (signup to first output, with % splits,
+  drop-off per step, and example replays) and render a screenshot per step. Use
+  when asked for an onboarding storyboard, where new users drop off, or frames
+  for each onboarding step.
+scope: dev
+---
+
+# Onboarding Journeys
+
+The pipeline runs without a UI. Codex does all four steps from the terminal:
+
+1. Call `get-onboarding-journey` as an MCP tool of the deployed Analytics app.
+   Save the JSON result as `tree.json`.
+2. Run the capture CLI from the agent-native checkout:
+   `pnpm --filter analytics journey:capture --tree tree.json --out ./frames`
+   (`--per-node 2 --concurrency 3`, `--min-aspect` / `--max-aspect`, `--dry-run`
+   to print the plan, `--upload` for private `attachmentRef`s).
+3. Call Design's `create-journey-canvas` with
+   `{ title, tree, frames: [{ nodeKey, exampleIndex, imageUrl?, attachmentRef?, width, height, capturedAt }], designId? }`
+   -> `{ designId, url, nodeCount, frameCount }`. Build `frames` from
+   `frames/manifest.json`.
+4. Lay out and review the canvas.
+
+## The tree
+
+`get-onboarding-journey` returns `JourneyTree`; `format: "summary"` returns the
+same counts as an indented `outline` with no examples. Use it first to choose a
+window, `app`, `maxDepth`, `minNodeSessions` (small branches merge into an
+`other` node), and `maxNodes`.
+
+```ts
+type JourneyExample = { sessionId: string; recordingId: string | null; ts: string; offsetMs: number | null; viewport: { width: number; height: number } | null; viewportReason?: string; replayUrl?: string };
+type JourneyNode = { key: string; label: string; parentKey: string | null; depth: number; kind: "step" | "other"; n: number; pctOfRoot: number; pctOfParent: number; dropoffN: number; dropoffPct: number; examples: JourneyExample[] };
+type JourneyTree = { window: { from: string; to: string }; app: string; rootN: number; coverage: { sessionsWithEvents: number; sessionsWithReplay: number; truncated: boolean }; nodes: JourneyNode[]; notes?: string[] };
+```
+
+- Nodes come parents first. `key` is the path of step keys joined with ` > `;
+  `pctOf*` are percents (0-100).
+- `dropoffN` is sessions whose last observed step is that node. It is not a
+  confirmed exit: a blocked tracker or an event outside the window reads the
+  same. A node at `maxDepth` where `n - dropoffN - sum(children n)` is above
+  zero has sessions that carried on.
+- A session is an analytics session id. One that began before `dateFrom`
+  starts mid-journey, so start the window a day early.
+- Read `coverage` before using the numbers. `truncated: true` means the event
+  read hit `maxEventRows` or the node list hit `maxNodes`; `notes` says which.
+  Never report a truncated tree as the whole window.
+- An example with `recordingId: null` has no replay the caller can open, and
+  `viewportReason` says why the viewport is unknown (`no_recording`,
+  `not_captured` for recordings before viewport capture, `unreadable`).
+- Test identities are always excluded; `emailFilter` defaults to
+  `exclude_builder`, as in the onboarding metrics. A session with any excluded
+  identity is dropped whole.
+
+## Capture
+
+The CLI mints a two-hour tokenized replay link per recording with
+`create-session-replay-agent-link`, opens each recording once in headless
+Chromium at `/sessions/:id?frame=1&agent_access=...`, seeks to each `offsetMs`,
+and uses the Sessions screenshot compositor. It writes `<nodeKey>-<n>.png` and
+`manifest.json` with `frames`, `failures` (explicit, with a reason), and
+`skipped`. Fix failures or report them; do not paint over a missing frame.
+
+Authenticate to the deployed app, never a local database: run
+`npx -y @agent-native/core@latest connect https://analytics.agent-native.com --client codex`
+(the CLI reads the bearer it writes to `~/.codex/config.toml`), or pass
+`--token` / set `AGENT_NATIVE_TOKEN`. `--app-url` overrides the app. Frame mode
+needs a deployment that includes `/sessions/:id?frame=1`.
+
+Frame mode renders without a login; the signed link is the only credential. It
+masks and scrubs exactly as the Sessions viewer does. Do not add viewport
+clamping or pointer projection to it (see `session-replay`).
+
+Viewport comes from the recording's first rrweb Meta event, stored by replay
+ingest in `session_recordings.metadata.viewport` (`first` and `last`). Older
+recordings have none.

package/corpus/templates/analytics/.agents/skills/session-replay/SKILL.md

@@ -154,10 +154,12 @@ agent answers about browser recordings in the Analytics template.
   clients send no id and are skipped: followed together, two tabs would look
   like one tab going back.
 - A replay row counts only while `processed_chunks` equals the recording's
-  `chunk_count`. Each batch must continue from the stored detector state and
-  its chunk seqs must start exactly at `processed_chunks`, so a batch that
-  cannot be measured, or arrives out of order, leaves the row behind and the
-  recording reads as unmeasured; never restart from fresh state. An event row
+  `chunk_count`. Each batch continues from the stored detector state, whose
+  `lastSeq` is the highest chunk measured; a seq the recorder lost is skipped.
+  A batch that cannot be measured, or a chunk below `lastSeq`, leaves the row
+  behind and the recording reads as unmeasured until it ends. Then
+  `remeasureReplayFriction` measures every stored chunk again in seq order;
+  never continue a row that fell behind from fresh state. An event row
   counts only when the tenant's friction coverage began before every
   recording of the session and the session has neither an event index gap
   nor a friction gap (`analytics_session_friction_gaps`). A friction write

package/corpus/templates/analytics/CHANGELOG.md

@@ -3,14 +3,44 @@
 All notable user-facing changes to Agent-Native Analytics are documented here. Open it any
 time from the command menu (Cmd+K → "What's new") or from Settings.
 
+## 2026-10-08
+
+### Added
+
+- Agents can build the onboarding journey tree with drop-off per step and render a screenshot of each step from session replays.
+
+### Improved
+
+- Session replay screenshots capture directly without requesting screen sharing.
+
+### Fixed
+
+- Analytics now reports uncertain storyboard saves without implying the export definitely failed.
+- Replay screenshot exports now report upload timeouts and incomplete cleanup.
+- Storyboard exports now ask you to check Design when Analytics cannot confirm a save.
+
 ## 2026-10-07
 
 ### Added
 
+- Selected session replays can be captured at exact timestamps and sent together to a private Design storyboard.
 - Session replay screenshots can be copied directly into Design.
 
+### Improved
+
+- Analytics chat follows short follow-ups like "what about EMEA?" and recovers from an unknown BigQuery column in one step
+- Thumbs-down on a chat answer now offers quick reasons and a Copy details button that copies the run id and thread link for a report
+
 ### Fixed
 
+- Analytics now treats chart filter changes as data requests and reports when reference catalogs are incomplete.
+- Analytics chat no longer stays on "running" after the agent has finished; the thread reloads so the change is visible without asking again
+- Analytics chat stops retrying a data source that is not connected and says who can connect it
+- Analytics keeps S3 replay setup available when storage status cannot be checked.
+- Automatic learning captures stay private to the user, and shared learning updates require approval.
+- Builder storage setup now waits for renewed file access before confirming it is ready.
+- Personal Analytics memories stay limited to unscoped conversations, keeping organization-specific guidance from following users between organizations.
+- Session replay storyboard screenshots upload directly to Design's private storage, so Analytics does not need its own blob storage provider.
 - Session replay screenshot export captures readable video frames and safe poster images.
 
 ## 2026-10-06

package/corpus/templates/analytics/actions/get-onboarding-journey.ts

@@ -0,0 +1,211 @@
+import { defineAction, fail } from "@agent-native/core/action";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+import {
+  FIRST_PARTY_TEMPLATE_NAMES,
+  isCalendarDate,
+} from "../server/lib/first-party-metric-catalog.js";
+import {
+  getOnboardingJourney,
+  JourneyRecordingsError,
+} from "../server/lib/onboarding-journey.js";
+
+const MAX_WINDOW_DAYS = 90;
+
+function resolveScope() {
+  const userEmail = getRequestUserEmail();
+  if (!userEmail)
+    fail("Sign in to use this action.", {
+      errorCode: "unauthenticated",
+      statusCode: 401,
+    });
+  return { userEmail, orgId: getRequestOrgId() || null };
+}
+
+const isoDate = z
+  .string()
+  .regex(/^\d{4}-\d{2}-\d{2}$/)
+  .refine(isCalendarDate, { message: "must be a real calendar date" });
+
+export default defineAction({
+  description:
+    'Build the onboarding journey tree for a date window: per-session step sequences (signup, onboarding questions, setup method, app entry, first action, first output) folded into a prefix tree. format "tree" returns { window, app, rootN, coverage, nodes }: each node has n, pctOfRoot, pctOfParent, dropoffN/dropoffPct (sessions whose last observed step is that node, not a confirmed exit) and example sessions with recordingId, offsetMs to seek to, and the recording\'s viewport. format "summary" returns the same counts as an indented text outline with no examples. Check coverage.truncated first: true means counts are a partial sample or the node list was cut (see notes). Use it to plan onboarding storyboards or find where new users stop; feed the tree to the journey:capture CLI to render frames.',
+  schema: z.object({
+    dateFrom: isoDate.describe(
+      "Inclusive UTC start date, YYYY-MM-DD. Sessions that began earlier appear mid-journey, so start a day before the period you care about.",
+    ),
+    dateTo: isoDate.describe(
+      `Inclusive UTC end date, YYYY-MM-DD, at most ${MAX_WINDOW_DAYS} days after dateFrom. Events are windowed before any join.`,
+    ),
+    app: z
+      .enum(["all", ...FIRST_PARTY_TEMPLATE_NAMES])
+      .optional()
+      .default("all")
+      .describe(
+        'Template filter: "all" or one first-party template such as clips, design, or slides. Defaults to "all".',
+      ),
+    emailFilter: z
+      .enum(["all", "exclude_builder", "only_builder"])
+      .optional()
+      .default("exclude_builder")
+      .describe(
+        'Builder-employee scope, as in the onboarding metrics: "exclude_builder" (default), "only_builder", or "all". Test identities are always excluded.',
+      ),
+    format: z
+      .enum(["tree", "summary"])
+      .optional()
+      .default("tree")
+      .describe(
+        'Output shape: "tree" (default) with example sessions, or "summary", an indented text outline of counts and drop-off with no examples.',
+      ),
+    maxNodes: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(500)
+      .optional()
+      .default(60)
+      .describe(
+        "Most nodes returned, largest first. When the tree has more, coverage.truncated is true and notes says how many were cut. Defaults to 60.",
+      ),
+    maxDepth: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(20)
+      .optional()
+      .default(8)
+      .describe(
+        "Steps kept per session before sessions are folded into the deeperN count of the node at this depth. Defaults to 8.",
+      ),
+    minNodeSessions: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .optional()
+      .default(1)
+      .describe(
+        'Branches with fewer sessions than this merge into one "other" child per parent. Defaults to 1 (nothing merges).',
+      ),
+    examplesPerNode: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(10)
+      .optional()
+      .default(3)
+      .describe("Example sessions returned per node. Defaults to 3."),
+    maxEventRows: z.coerce
+      .number()
+      .int()
+      .min(1000)
+      .max(200000)
+      .optional()
+      .default(40000)
+      .describe(
+        "Event rows to read before stopping and reporting coverage.truncated. Each 4,000 rows is one query; raise it only for a wide window. Defaults to 40000.",
+      ),
+    recency: z
+      .enum(["newest", "none"])
+      .optional()
+      .default("newest")
+      .describe(
+        'Example order after replay availability: "newest" (default) prefers recent sessions, "none" orders by session id.',
+      ),
+    settleMs: z.coerce
+      .number()
+      .int()
+      .min(0)
+      .max(5000)
+      .optional()
+      .default(300)
+      .describe(
+        "Added to each example's offsetMs so the frame has rendered. Defaults to 300.",
+      ),
+    minAspect: z.coerce
+      .number()
+      .positive()
+      .optional()
+      .describe("Only examples whose viewport width/height is at least this."),
+    maxAspect: z.coerce
+      .number()
+      .positive()
+      .optional()
+      .describe("Only examples whose viewport width/height is at most this."),
+    minWidth: z.coerce
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe("Only examples whose viewport is at least this many px wide."),
+    maxWidth: z.coerce
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe("Only examples whose viewport is at most this many px wide."),
+    requireKnownViewport: z
+      .boolean()
+      .optional()
+      .describe(
+        "Leave out examples whose viewport was not recorded or cannot be read. Without it they are kept with viewport null and a viewportReason.",
+      ),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  mcpTool: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  grounding: true,
+  run: async (args) => {
+    const days =
+      (Date.parse(`${args.dateTo}T00:00:00Z`) -
+        Date.parse(`${args.dateFrom}T00:00:00Z`)) /
+      86_400_000;
+    if (days < 0) fail("dateTo must not be before dateFrom.");
+    if (days > MAX_WINDOW_DAYS) {
+      fail(`The window may span at most ${MAX_WINDOW_DAYS} days.`);
+    }
+    const viewport = {
+      ...(args.minAspect !== undefined ? { minAspect: args.minAspect } : {}),
+      ...(args.maxAspect !== undefined ? { maxAspect: args.maxAspect } : {}),
+      ...(args.minWidth !== undefined ? { minWidth: args.minWidth } : {}),
+      ...(args.maxWidth !== undefined ? { maxWidth: args.maxWidth } : {}),
+      ...(args.requireKnownViewport ? { requireKnown: true } : {}),
+    };
+    const scope = resolveScope();
+    try {
+      return await getOnboardingJourney(scope, {
+        dateFrom: args.dateFrom,
+        dateTo: args.dateTo,
+        app: args.app,
+        emailFilter: args.emailFilter,
+        format: args.format,
+        maxNodes: args.maxNodes,
+        maxDepth: args.maxDepth,
+        minNodeSessions: args.minNodeSessions,
+        examplesPerNode: args.examplesPerNode,
+        maxEventRows: args.maxEventRows,
+        settleMs: args.settleMs,
+        recency: args.recency,
+        viewport: Object.keys(viewport).length ? viewport : undefined,
+      });
+    } catch (error) {
+      // Causes can quote database details; the server log keeps them.
+      console.error("[get-onboarding-journey] failed", error);
+      if (error instanceof JourneyRecordingsError) {
+        fail(
+          `${error.message} Examples would misreport which sessions have a replay, so no tree was built; retry, or use format "summary" for counts only.`,
+          { errorCode: "journey_recordings_unreadable", statusCode: 502 },
+        );
+      }
+      fail(
+        "Onboarding journey events could not be read, so no tree was built. Retry with a narrower window or app.",
+        { errorCode: "journey_events_unreadable", statusCode: 502 },
+      );
+    }
+  },
+});

package/corpus/templates/analytics/actions/upload-journey-frame.ts

@@ -0,0 +1,88 @@
+import { defineAction, fail } from "@agent-native/core/action";
+import { mintAttachmentRef } from "@agent-native/core/private-blob";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+import { getSessionReplaySummary } from "../server/lib/session-replay.js";
+import { pngDimensions } from "../shared/png.js";
+
+const MAX_PNG_BYTES = 3_500_000;
+
+export default defineAction({
+  description:
+    "Store one onboarding journey frame (a PNG screenshot of a session replay) in the caller's private storage and return an opaque attachmentRef. Used by the journey:capture CLI with --upload; frames are never public and only the caller can open the ref. The caller must be able to open the recording.",
+  schema: z.object({
+    recordingId: z
+      .string()
+      .min(1)
+      .max(128)
+      .describe("The recording the frame shows"),
+    offsetMs: z.coerce
+      .number()
+      .int()
+      .min(0)
+      .describe("Where in the recording the frame was captured"),
+    png: z
+      .string()
+      .min(1)
+      .max(Math.ceil((MAX_PNG_BYTES * 4) / 3) + 8)
+      .describe(`Base64 PNG, at most ${MAX_PNG_BYTES} bytes decoded`),
+  }),
+  agentTool: false,
+  run: async (args) => {
+    const userEmail = getRequestUserEmail();
+    if (!userEmail) {
+      fail("Sign in to use this action.", {
+        errorCode: "unauthenticated",
+        statusCode: 401,
+      });
+    }
+    const orgId = getRequestOrgId() || null;
+    const recording = await getSessionReplaySummary(args.recordingId, {
+      userEmail,
+      orgId,
+    });
+    const data = Buffer.from(args.png, "base64");
+    if (data.byteLength === 0 || data.byteLength > MAX_PNG_BYTES) {
+      fail(`The frame must be a PNG of at most ${MAX_PNG_BYTES} bytes.`, {
+        errorCode: "journey_frame_invalid",
+        statusCode: 413,
+      });
+    }
+    const dimensions = pngDimensions(data);
+    if (!dimensions) {
+      fail("The frame is not a PNG of a plausible screenshot size.", {
+        errorCode: "journey_frame_invalid",
+      });
+    }
+    const minted = await mintAttachmentRef({
+      data,
+      filename: `${recording.id}-${String(args.offsetMs).padStart(8, "0")}.png`,
+      mimeType: "image/png",
+      ownerEmail: userEmail,
+      orgId: null,
+      metadata: {
+        appId: "analytics",
+        resourceType: "journey-frame",
+        resourceId: recording.id,
+        replayId: recording.id,
+        offsetMs: args.offsetMs,
+      },
+    });
+    if (minted.status !== "ok") {
+      fail(
+        "Private frame storage is not available for Analytics, so the frame was not stored.",
+        { errorCode: "private_storage_unavailable", statusCode: 503 },
+      );
+    }
+    return {
+      attachmentRef: minted.ref,
+      width: dimensions.width,
+      height: dimensions.height,
+      bytes: data.byteLength,
+    };
+  },
+});

package/corpus/templates/analytics/app/i18n/en-US.ts

@@ -1698,8 +1698,12 @@ export default {
     storyboardNoDesignResponse: "Design returned no storyboard result.",
     storyboardTemporaryCleanupPending:
       "The storyboard was saved, but temporary screenshot files could not be removed.",
+    storyboardTemporaryCleanupFailed:
+      "Temporary screenshot cleanup is still pending.",
     storyboardUnexpectedResponse:
       "The screenshot export returned an unreadable response. Retry the export.",
+    storyboardSaveOutcomeUnknown:
+      "Design may have saved the storyboard. Check Design before retrying.",
     openStoryboard: "Open storyboard in Design",
     cancelStoryboardCapture: "Cancel capture",
     captureToDesign: "Capture and add to Design",

package/corpus/templates/analytics/app/pages/sessions/SessionReplayFrame.tsx

@@ -0,0 +1,192 @@
+import { isScreenshotSize } from "@shared/png";
+import { SESSION_REPLAY_AGENT_ACCESS_PARAM } from "@shared/session-replay-agent-access";
+import { useEffect, useRef, useState } from "react";
+
+import {
+  blobToBase64,
+  replayFrameFailureReason,
+  replayFramePath,
+  type ReplayFrameCapture,
+} from "./session-replay-frame";
+import { captureReplayScreenshot } from "./session-replay-screenshot";
+import {
+  buildReplayViewportTimeline,
+  fetchSessionReplayPlayback,
+  normalizeReplayEvents,
+  REPLAY_OVERLAY_STYLE_RULES,
+  replayAvailabilityErrorKey,
+  replayInitialViewportDimensions,
+  replayRouteAtOffset,
+  replayViewportDimensionsAtTime,
+} from "./SessionDetailPage";
+
+function nextPaint(): Promise<void> {
+  return new Promise((resolve) =>
+    requestAnimationFrame(() => requestAnimationFrame(() => resolve())),
+  );
+}
+
+export default function SessionReplayFrame({
+  recordingId,
+}: {
+  recordingId: string;
+}) {
+  const stageRef = useRef<HTMLDivElement>(null);
+  const stageRootRef = useRef<HTMLDivElement>(null);
+  const [status, setStatus] = useState<"loading" | "ready" | "error">(
+    "loading",
+  );
+
+  useEffect(() => {
+    let cancelled = false;
+    let replayer: any = null;
+    window.__anReplayFrame = { status: "loading" };
+
+    const fail = (error: unknown) => {
+      if (cancelled) return;
+      window.__anReplayFrame = {
+        status: "error",
+        reason: replayFrameFailureReason(error),
+      };
+      setStatus("error");
+    };
+
+    async function boot() {
+      const stage = stageRef.current;
+      const stageRoot = stageRootRef.current;
+      if (!stage || !stageRoot) throw new Error("frame_not_mounted");
+      const agentAccessToken =
+        new URLSearchParams(window.location.search).get(
+          SESSION_REPLAY_AGENT_ACCESS_PARAM,
+        ) ?? "";
+      const playback = await fetchSessionReplayPlayback(recordingId, {
+        agentAccessToken,
+      });
+      if (
+        !playback.isComplete ||
+        playback.unavailableChunks > 0 ||
+        playback.chunks.some((chunk) => chunk.unavailable)
+      ) {
+        throw new Error("replay_incomplete");
+      }
+      const events = normalizeReplayEvents(
+        playback.chunks.flatMap((chunk) => chunk.events),
+      );
+      const unavailable = replayAvailabilityErrorKey(events);
+      if (unavailable) throw new Error(unavailable);
+      const initial = replayInitialViewportDimensions(events);
+      if (!initial) throw new Error("viewport_unavailable");
+      const timeline = buildReplayViewportTimeline(events);
+      // Sizes come from the recorded events, so one the browser could not
+      // render is refused before any surface is allocated for it.
+      if (
+        !timeline.every((change) =>
+          isScreenshotSize(change.width, change.height),
+        )
+      ) {
+        throw new Error("viewport_out_of_range");
+      }
+
+      await import("@rrweb/replay/dist/style.css");
+      const { Replayer } = await import("@rrweb/replay");
+      if (cancelled) return;
+
+      const sizeStage = (width: number, height: number) => {
+        stageRoot.style.width = `${width}px`;
+        stageRoot.style.height = `${height}px`;
+        stageRoot.style.transform = "none";
+        stageRoot.style.setProperty("--an-replay-cursor-scale", "1");
+      };
+      sizeStage(initial.width, initial.height);
+      replayer = new Replayer(events as any[], {
+        root: stageRoot,
+        speed: 1,
+        skipInactive: false,
+        showWarning: false,
+        showDebug: false,
+        mouseTail: false,
+        triggerFocus: true,
+        insertStyleRules: REPLAY_OVERLAY_STYLE_RULES,
+      });
+      replayer.iframe?.setAttribute?.("referrerpolicy", "no-referrer");
+      const totalTimeMs = Number(replayer.getMetaData?.().totalTime ?? 0);
+      try {
+        replayer.play?.(0);
+      } catch {
+        // rrweb throws when the first event cannot start playback; a pause at
+        // 0 still builds the first snapshot, which is all a seek needs.
+        replayer.pause?.(0);
+      }
+      await nextPaint();
+
+      let queue: Promise<unknown> = Promise.resolve();
+      const captureOne = async (
+        offsetMs: number,
+      ): Promise<ReplayFrameCapture> => {
+        if (!Number.isFinite(offsetMs) || offsetMs < 0) {
+          throw new Error("offset_invalid");
+        }
+        if (offsetMs > totalTimeMs) throw new Error("offset_out_of_range");
+        const dimensions =
+          replayViewportDimensionsAtTime(timeline, offsetMs) ?? initial;
+        replayer.pause(offsetMs);
+        replayer.handleResize?.(dimensions);
+        sizeStage(dimensions.width, dimensions.height);
+        await nextPaint();
+        const iframe = replayer.iframe as HTMLIFrameElement | undefined;
+        if (!iframe) throw new Error("replay_frame_missing");
+        const blob = await captureReplayScreenshot(stage, stageRoot, iframe);
+        return {
+          offsetMs,
+          width: dimensions.width,
+          height: dimensions.height,
+          route: replayFramePath(replayRouteAtOffset(events, offsetMs)),
+          capturedAt: new Date().toISOString(),
+          png: await blobToBase64(blob),
+        };
+      };
+
+      window.__anReplayFrame = {
+        status: "ready",
+        recordingId,
+        totalTimeMs,
+        eventCount: playback.recording.eventCount,
+        // One seek at a time: rrweb has a single playhead.
+        capture: (offsetMs) => {
+          const run = queue.then(() => captureOne(offsetMs));
+          queue = run.catch(() => undefined);
+          return run;
+        },
+      };
+      setStatus("ready");
+    }
+
+    boot().catch(fail);
+    return () => {
+      cancelled = true;
+      try {
+        replayer?.pause?.();
+        replayer?.destroy?.();
+        // coercion-ok: teardown of a player the page is leaving; nothing can act on a failure here.
+      } catch {
+        // Nothing to report: the page is going away.
+      }
+      window.__anReplayFrame = undefined;
+    };
+  }, [recordingId]);
+
+  return (
+    <div
+      ref={stageRef}
+      data-replay-frame={status}
+      // guard:allow-raw-color — a recording with no page background renders on the browser's default white, and the frame must match it in every theme
+      style={{ position: "fixed", left: 0, top: 0, background: "#fff" }}
+    >
+      <div
+        ref={stageRootRef}
+        className="an-replay-stage-root"
+        style={{ position: "relative", overflow: "hidden" }}
+      />
+    </div>
+  );
+}