@agent-native/core 0.98.3 → 0.98.5

package/corpus/core/src/client/session-replay.ts

@@ -1,3 +1,12 @@
+import {
+  SESSION_REPLAY_IFRAME_ATTRIBUTE,
+  SESSION_REPLAY_IFRAME_PROBE,
+  SESSION_REPLAY_IFRAME_START,
+  SESSION_REPLAY_IFRAME_STOP,
+  type SessionReplayIframePrivacyOptions,
+  type SessionReplayIframeStartMessage,
+  type SessionReplayIframeStopMessage,
+} from "../session-replay-iframe-protocol.js";
 import {
   getOrCreateAnalyticsAnonymousId,
   getOrCreateAnalyticsSessionId,
@@ -7,10 +16,17 @@ import { scrubUrl } from "./url-scrub.js";
 type ReplayEvent = Record<string, unknown>;
 type QueuedReplayEvent = {
   json: string;
+  byteLength: number;
   timestampMs: number;
   type: number | null;
 };
 type ReplayStopFn = () => void;
+type ReplayResourceNode = {
+  tagName: string;
+  rel: string;
+  as: string;
+  type: string;
+};
 export type SessionReplayUrlMatcher =
   | string
   | RegExp
@@ -59,15 +75,37 @@ interface SessionReplayState {
   flushTimer: number | null;
   maxDurationTimer: number | null;
   flushing: boolean;
+  /** Highest-priority flush requested while an upload was already in flight. */
+  pendingFlushReason: string | null;
+  /** Callers awaiting the coalesced flush tail. */
+  pendingFlushWaiters: Array<() => void>;
+  /** Drop incremental events until a new FullSnapshot can re-anchor the DOM. */
+  awaitingFullSnapshot: boolean;
   stopRecorder: ReplayStopFn | null;
   restoreUrlMonitor: (() => void) | null;
   removeLifecycleListeners: (() => void) | null;
+  /** Stops the cooperative child-iframe bridge and notifies active children. */
+  restoreIframeBridge: (() => void) | null;
   /** rrweb's `record.addCustomEvent`, captured at start (null when absent). */
   addCustomEvent: ((tag: string, payload: unknown) => void) | null;
   /** Uninstalls console/network interceptors and flushes pending duplicates. */
   restoreCaptures: (() => void) | null;
   options: NormalizedSessionReplayOptions | null;
   lastAuthenticatedProperties: Record<string, unknown> | null;
+  /** Resource tag metadata used to classify later rrweb attribute mutations. */
+  resourceNodes: Map<number, ReplayResourceNode>;
+  /**
+   * Prevents a permanently misconfigured endpoint from causing an automatic
+   * 409 -> restart -> 409 loop. A successful upload resets the allowance, so
+   * a later, independent sequence conflict can still recover in-place.
+   */
+  automaticConflictRestartAttempted: boolean;
+  /**
+   * Cross-tab "who is recording this replayId" channel, open for the
+   * lifetime of an active recording. See `getOrCreateReplaySession` for why
+   * this exists (duplicated-tab guard against a shared `replayId`).
+   */
+  broadcastChannel: BroadcastChannel | null;
 }
 
 interface StoredReplaySession {
@@ -77,6 +115,27 @@ interface StoredReplaySession {
   sequence?: number;
 }
 
+/** Broadcast on `SESSION_REPLAY_BROADCAST_CHANNEL_NAME` by a tab resuming a
+ * stored replay session, to check whether another tab is already recording
+ * that same `replayId` (see the duplicated-tab guard in
+ * `getOrCreateReplaySession`'s doc comment). */
+interface ReplayClaimMessage {
+  type: "an-replay-claim";
+  replayId: string;
+  instanceNonce: string;
+}
+
+/** Reply from a tab that is actively recording the claimed `replayId`. */
+interface ReplayClaimTakenMessage {
+  type: "an-replay-claim-taken";
+  replayId: string;
+  /** Only the claimant with this nonce should yield the stored replay id.
+   * Optional while older recorder bundles can still be open during rollout. */
+  claimantNonce?: string;
+}
+
+type ReplayBroadcastMessage = ReplayClaimMessage | ReplayClaimTakenMessage;
+
 /** rrweb `sampling` shape (mousemove/scroll/media throttles, input strategy). */
 export type ReplayEventSampling = Record<string, unknown>;
 
@@ -107,6 +166,13 @@ export interface SessionReplayNetworkOptions {
   maxErrorBodyLength?: number;
 }
 
+export interface SessionReplayUploadRejectedDetails {
+  status: number;
+  restartAttempted: boolean;
+  restartSucceeded: boolean;
+  restartReason?: SessionReplayStartResult["reason"];
+}
+
 export interface SessionReplayOptions {
   enabled?: boolean;
   /** Rechecked immediately before rrweb starts to cancel deferred startup. */
@@ -157,6 +223,8 @@ export interface SessionReplayOptions {
    * disable, or an options object to override caps.
    */
   network?: boolean | SessionReplayNetworkOptions;
+  /** Rare recorder lifecycle signal; never includes replay content or URLs. */
+  onUploadRejected?: (details: SessionReplayUploadRejectedDetails) => void;
   extraProperties?:
     | Record<string, unknown>
     | (() => Record<string, unknown> | undefined);
@@ -209,6 +277,7 @@ interface NormalizedSessionReplayOptions {
   console: NormalizedCaptureOptions | null;
   /** Null disables network capture entirely. */
   network: NormalizedCaptureOptions | null;
+  onUploadRejected?: SessionReplayOptions["onUploadRejected"];
   extraProperties?: SessionReplayOptions["extraProperties"];
   shouldStart?: SessionReplayOptions["shouldStart"];
 }
@@ -240,7 +309,9 @@ const SESSION_REPLAY_STATE_KEY = Symbol.for(
   "agent-native.client.sessionReplay",
 );
 const SESSION_REPLAY_ID_STORAGE_KEY = "agent-native.session_replay_id";
+const SESSION_REPLAY_IFRAME_BLOCK_SELECTOR = `iframe[${SESSION_REPLAY_IFRAME_ATTRIBUTE}]`;
 const DEFAULT_BLOCK_SELECTOR = [
+  SESSION_REPLAY_IFRAME_BLOCK_SELECTOR,
   "[data-sensitive]",
   "[data-an-block]",
   "[data-an-private]",
@@ -260,12 +331,35 @@ const DEFAULT_BLOCK_SELECTOR = [
 const DEFAULT_IGNORE_SELECTOR = ".an-ignore, [data-an-ignore]";
 const DEFAULT_MASK_TEXT_CLASS = "an-mask";
 const DEFAULT_MASK_TEXT_SELECTOR = "[data-an-mask]";
+const DEFAULT_MASK_INPUT_OPTIONS: Record<string, boolean> = {
+  color: true,
+  date: true,
+  "datetime-local": true,
+  email: true,
+  month: true,
+  number: true,
+  password: true,
+  range: true,
+  search: true,
+  tel: true,
+  text: true,
+  time: true,
+  url: true,
+  week: true,
+};
 const DEFAULT_FLUSH_INTERVAL_MS = 5000;
 const DEFAULT_MAX_DURATION_MS = 30 * 60 * 1000;
 const DEFAULT_MAX_EVENTS_PER_BATCH = 50;
 const DEFAULT_MAX_BATCH_BYTES = 256 * 1024;
 const MAX_KEEPALIVE_REPLAY_UPLOAD_BYTES = 60 * 1024;
+const REPLAY_TEXT_ENCODER =
+  typeof TextEncoder !== "undefined" ? new TextEncoder() : null;
 const RRWEB_FULL_SNAPSHOT_EVENT_TYPE = 2;
+/** Cross-tab channel name used by the duplicated-tab claim guard. */
+const SESSION_REPLAY_BROADCAST_CHANNEL_NAME = "agent-native-session-replay";
+/** How long a resuming tab waits for a "someone else already owns this
+ * replayId" reply before proceeding to record with the resumed id. */
+const SESSION_REPLAY_CLAIM_TIMEOUT_MS = 150;
 
 /** rrweb custom-event tag for captured console/window-error entries. */
 export const SESSION_REPLAY_CONSOLE_EVENT_TAG = "agent-native.console";
@@ -347,34 +441,79 @@ function getState(): SessionReplayState {
       flushTimer: null,
       maxDurationTimer: null,
       flushing: false,
+      pendingFlushReason: null,
+      pendingFlushWaiters: [],
+      awaitingFullSnapshot: false,
       stopRecorder: null,
       restoreUrlMonitor: null,
       removeLifecycleListeners: null,
+      restoreIframeBridge: null,
       addCustomEvent: null,
       restoreCaptures: null,
       options: null,
       lastAuthenticatedProperties: null,
+      resourceNodes: new Map(),
+      automaticConflictRestartAttempted: false,
+      broadcastChannel: null,
     };
   }
-  return g[SESSION_REPLAY_STATE_KEY]!;
+  const state = g[SESSION_REPLAY_STATE_KEY]!;
+  // Keep Vite HMR safe when an older recorder state survives a module reload.
+  state.resourceNodes ??= new Map();
+  state.restoreIframeBridge ??= null;
+  state.pendingFlushReason ??= null;
+  state.pendingFlushWaiters ??= [];
+  state.awaitingFullSnapshot ??= false;
+  return state;
+}
+
+// The replay session record (replayId + sequence counter) lives in
+// `sessionStorage`, not `localStorage`: `localStorage` is shared by every
+// open tab of the origin, which would hand every tab the same `replayId` and
+// the same sequence counter. See the guard comment above
+// `getOrCreateReplaySession` for the corruption that causes.
+function safeSessionStorageGet(key: string): string | null {
+  try {
+    return window.sessionStorage.getItem(key);
+  } catch {
+    return null;
+  }
 }
 
-function safeStorageGet(key: string): string | null {
+function safeSessionStorageSet(key: string, value: string): void {
   try {
-    return window.localStorage.getItem(key);
+    window.sessionStorage.setItem(key, value);
   } catch {
-    return null;
+    // private browsing / storage disabled -- replay still works for this page
   }
 }
 
-function safeStorageSet(key: string, value: string): void {
+function safeSessionStorageRemove(key: string): void {
   try {
-    window.localStorage.setItem(key, value);
+    window.sessionStorage.removeItem(key);
   } catch {
     // private browsing / storage disabled -- replay still works for this page
   }
 }
 
+let legacyLocalStorageReplaySessionCleared = false;
+
+/**
+ * Best-effort, one-time removal of the pre-fix replay session record that
+ * used to live in `localStorage`. Never read from it -- adopting its
+ * `replayId` would recreate the exact shared-identity bug this file now
+ * avoids by using `sessionStorage` instead.
+ */
+function clearLegacyLocalStorageReplaySession(): void {
+  if (legacyLocalStorageReplaySessionCleared) return;
+  legacyLocalStorageReplaySessionCleared = true;
+  try {
+    window.localStorage.removeItem(SESSION_REPLAY_ID_STORAGE_KEY);
+  } catch {
+    // best-effort only -- a stray legacy record is harmless once ignored
+  }
+}
+
 function generateReplayId(): string {
   try {
     if (
@@ -390,7 +529,7 @@ function generateReplayId(): string {
 }
 
 function readStoredReplaySession(): StoredReplaySession | null {
-  const raw = safeStorageGet(SESSION_REPLAY_ID_STORAGE_KEY);
+  const raw = safeSessionStorageGet(SESSION_REPLAY_ID_STORAGE_KEY);
   if (!raw) return null;
   try {
     const parsed = JSON.parse(raw) as StoredReplaySession;
@@ -402,14 +541,47 @@ function readStoredReplaySession(): StoredReplaySession | null {
 }
 
 function writeStoredReplaySession(value: StoredReplaySession): void {
-  safeStorageSet(SESSION_REPLAY_ID_STORAGE_KEY, JSON.stringify(value));
+  safeSessionStorageSet(SESSION_REPLAY_ID_STORAGE_KEY, JSON.stringify(value));
+}
+
+function removeStoredReplaySession(replayId: string): void {
+  if (readStoredReplaySession()?.replayId !== replayId) return;
+  safeSessionStorageRemove(SESSION_REPLAY_ID_STORAGE_KEY);
 }
 
+/**
+ * Per-tab replay identity is deliberate -- do not "fix" this by reading or
+ * writing the session record through `localStorage` again.
+ *
+ * `sessionStorage` is scoped to a single tab (and survives reloads/
+ * navigations within that tab, which is exactly the lifetime a recording
+ * needs). `localStorage` is shared by every open tab of the origin. If this
+ * record lived there, two tabs open to the same app would read/write the
+ * *same* `replayId` and the *same* sequence counter, so rrweb in each tab
+ * would record independently but upload chunks under one shared identity.
+ * The two interleaved DOM mutation streams get merged into a single
+ * recording server-side: mutations reference the other tab's node ids
+ * (broken CSS), the viewport/meta events reflect whichever tab resized last
+ * (wrong or ultra-wide viewport), and lost mousemove batches from the
+ * "other" tab's chunks read as a frozen cursor or a fake inactivity gap. A
+ * chunk-sequence collision with a different checksum gets rejected
+ * server-side (409) rather than merged, so one tab's batches are silently
+ * dropped -- there is no way to reconstruct or repair this at playback time.
+ * Keep this per-tab. A tab *duplicated* mid-session still shares a
+ * `sessionStorage` snapshot, which is what the `BroadcastChannel` claim
+ * check in `startSessionReplayRecorder` guards against.
+ */
 function getOrCreateReplaySession(sessionId: string): {
   replayId: string;
   startedAtMs: number;
   sequence: number;
+  /** True when resuming a session found in this tab's `sessionStorage`
+   * (e.g. a reload), as opposed to minting a brand-new id. Only the resumed
+   * case needs the duplicated-tab claim check -- a fresh id can never
+   * collide with anything already recording. */
+  resumed: boolean;
 } {
+  clearLegacyLocalStorageReplaySession();
   const parsed = readStoredReplaySession();
   if (parsed?.sessionId === sessionId && parsed.replayId) {
     const startedAtMs =
@@ -424,12 +596,127 @@ function getOrCreateReplaySession(sessionId: string): {
       parsed.sequence >= 0
         ? Math.floor(parsed.sequence)
         : 0;
-    return { replayId: parsed.replayId, startedAtMs, sequence };
+    return { replayId: parsed.replayId, startedAtMs, sequence, resumed: true };
   }
   const replayId = generateReplayId();
   const startedAtMs = Date.now();
   writeStoredReplaySession({ sessionId, replayId, startedAtMs, sequence: 0 });
-  return { replayId, startedAtMs, sequence: 0 };
+  return { replayId, startedAtMs, sequence: 0, resumed: false };
+}
+
+/**
+ * Open the cross-tab claim channel used to detect a *duplicated* tab (a
+ * browser "duplicate tab" or same-origin `window.open` copies
+ * `sessionStorage`, so two tabs can legitimately start with the same
+ * resumed `replayId`). Returns `null` when `BroadcastChannel` is
+ * unavailable -- callers must treat that as "skip the guard", never as an
+ * error.
+ */
+function openReplayBroadcastChannel(): BroadcastChannel | null {
+  if (typeof BroadcastChannel === "undefined") return null;
+  try {
+    return new BroadcastChannel(SESSION_REPLAY_BROADCAST_CHANNEL_NAME);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Wires up the duplicated-tab claim channel for one recorder lifetime.
+ * `respond` keeps listening for the whole life of the channel (any tab may
+ * later claim the `replayId` this tab is actively recording); `probeClaim`
+ * is used once, only when resuming a stored session, to ask "is anyone else
+ * already recording this id?" and wait up to
+ * `SESSION_REPLAY_CLAIM_TIMEOUT_MS` for a reply.
+ */
+function createReplayClaimChannel(
+  state: SessionReplayState,
+  instanceNonce: string,
+): {
+  channel: BroadcastChannel | null;
+  probeClaim: (replayId: string) => Promise<boolean>;
+} {
+  const channel = openReplayBroadcastChannel();
+  if (!channel) {
+    return { channel: null, probeClaim: async () => false };
+  }
+  let pending: {
+    replayId: string;
+    resolve: (taken: boolean) => void;
+    timer: number;
+  } | null = null;
+  channel.onmessage = (event: MessageEvent) => {
+    const data = event?.data as ReplayBroadcastMessage | undefined | null;
+    if (!data || typeof data !== "object") return;
+    if (data.type === "an-replay-claim") {
+      if (data.instanceNonce === instanceNonce) return;
+      const ownsReplayId = state.active && state.replayId === data.replayId;
+      const winsSimultaneousClaim =
+        pending?.replayId === data.replayId &&
+        instanceNonce.localeCompare(data.instanceNonce) < 0;
+      if (!ownsReplayId && !winsSimultaneousClaim) {
+        // If both duplicated tabs start simultaneously, deterministically
+        // yield to the lower nonce rather than letting both probes time out
+        // and record under the copied replay id.
+        if (
+          pending?.replayId === data.replayId &&
+          data.instanceNonce.localeCompare(instanceNonce) < 0
+        ) {
+          window.clearTimeout(pending.timer);
+          const resolve = pending.resolve;
+          pending = null;
+          resolve(true);
+        }
+        return;
+      }
+      try {
+        const reply: ReplayClaimTakenMessage = {
+          type: "an-replay-claim-taken",
+          replayId: data.replayId,
+          claimantNonce: data.instanceNonce,
+        };
+        channel.postMessage(reply);
+      } catch {
+        // best-effort -- a lost reply just means the duplicate tab resumes
+        // recording under the shared id; later 409s still protect the
+        // stream from getting corrupted merges.
+      }
+      return;
+    }
+    if (data.type === "an-replay-claim-taken") {
+      if (
+        pending &&
+        data.replayId === pending.replayId &&
+        (!data.claimantNonce || data.claimantNonce === instanceNonce)
+      ) {
+        window.clearTimeout(pending.timer);
+        const resolve = pending.resolve;
+        pending = null;
+        resolve(true);
+      }
+    }
+  };
+  const probeClaim = (replayId: string): Promise<boolean> =>
+    new Promise((resolve) => {
+      const timer = window.setTimeout(() => {
+        pending = null;
+        resolve(false);
+      }, SESSION_REPLAY_CLAIM_TIMEOUT_MS);
+      pending = { replayId, resolve, timer };
+      try {
+        const claim: ReplayClaimMessage = {
+          type: "an-replay-claim",
+          replayId,
+          instanceNonce,
+        };
+        channel.postMessage(claim);
+      } catch {
+        window.clearTimeout(timer);
+        pending = null;
+        resolve(false);
+      }
+    });
+  return { channel, probeClaim };
 }
 
 function persistReplaySequence(
@@ -640,13 +927,20 @@ function normalizeOptions(
     checkoutEveryNth: options.checkoutEveryNth,
     checkoutEveryNms: options.checkoutEveryNms,
     inlineStylesheet: options.inlineStylesheet ?? true,
-    blockSelector: options.blockSelector || DEFAULT_BLOCK_SELECTOR,
+    blockSelector: mergeReplayBlockSelector(
+      options.blockSelector || DEFAULT_BLOCK_SELECTOR,
+    ),
     ignoreSelector: options.ignoreSelector || DEFAULT_IGNORE_SELECTOR,
     maskTextClass: options.maskTextClass || DEFAULT_MASK_TEXT_CLASS,
     maskTextSelector: options.maskTextSelector || DEFAULT_MASK_TEXT_SELECTOR,
     maskAllInputs: options.maskAllInputs ?? true,
     recordCanvas: options.recordCanvas ?? false,
-    recordCrossOriginIframes: options.recordCrossOriginIframes ?? false,
+    // A top-level app can safely aggregate cooperative child recorders. An
+    // app embedded by an unrelated cross-origin host must continue emitting
+    // and uploading its own events, so it only forwards to a parent when the
+    // caller explicitly opts in.
+    recordCrossOriginIframes:
+      options.recordCrossOriginIframes ?? window.parent === window,
     collectFonts: options.collectFonts ?? false,
     inlineImages: options.inlineImages ?? false,
     eventSampling: options.eventSampling ?? DEFAULT_EVENT_SAMPLING,
@@ -658,11 +952,18 @@ function normalizeOptions(
       options.network,
       DEFAULT_MAX_NETWORK_EVENTS,
     ),
+    onUploadRejected: options.onUploadRejected,
     extraProperties: options.extraProperties,
     shouldStart: options.shouldStart,
   };
 }
 
+function mergeReplayBlockSelector(blockSelector: string): string {
+  return blockSelector.includes(SESSION_REPLAY_IFRAME_BLOCK_SELECTOR)
+    ? blockSelector
+    : `${blockSelector}, ${SESSION_REPLAY_IFRAME_BLOCK_SELECTOR}`;
+}
+
 /**
  * Console/network capture default to ON whenever session replay records;
  * `false` disables a category, an object form overrides its caps. Network
@@ -732,8 +1033,159 @@ function scrubReplayValue(
  * the scrub into the single serialization pass avoids a separate deep-clone of
  * every emitted event (FullSnapshots are large DOM trees) on the hot path.
  */
-function scrubReplayReplacer(key: string, value: unknown): unknown {
-  return typeof value === "string" ? scrubStringValue(key, value) : value;
+const REPLAY_RESOURCE_LINK_RELS = new Set([
+  "stylesheet",
+  "icon",
+  "apple-touch-icon",
+  "mask-icon",
+]);
+const REPLAY_RESOURCE_PRELOAD_TYPES = new Set([
+  "style",
+  "font",
+  "image",
+  "audio",
+  "video",
+  "track",
+]);
+const REPLAY_RESOURCE_TAGS = new Set([
+  "img",
+  "source",
+  "video",
+  "audio",
+  "track",
+  "input",
+  "link",
+]);
+const NO_REPLAY_RESOURCE_ATTRIBUTES = new Set<string>();
+const REPLAY_SRC_ATTRIBUTES = new Set(["src"]);
+const REPLAY_SRCSET_ATTRIBUTES = new Set(["src", "srcset"]);
+const REPLAY_VIDEO_ATTRIBUTES = new Set(["src", "poster"]);
+const REPLAY_HREF_ATTRIBUTES = new Set(["href"]);
+
+function replayAttributeString(
+  attributes: Record<string, unknown>,
+  key: string,
+): string {
+  return typeof attributes[key] === "string"
+    ? attributes[key].toLowerCase()
+    : "";
+}
+
+function updateReplayResourceNode(
+  current: ReplayResourceNode,
+  attributes: Record<string, unknown>,
+): ReplayResourceNode {
+  return {
+    tagName: current.tagName,
+    rel: Object.hasOwn(attributes, "rel")
+      ? replayAttributeString(attributes, "rel")
+      : current.rel,
+    as: Object.hasOwn(attributes, "as")
+      ? replayAttributeString(attributes, "as")
+      : current.as,
+    type: Object.hasOwn(attributes, "type")
+      ? replayAttributeString(attributes, "type")
+      : current.type,
+  };
+}
+
+function replayPreservedResourceAttributes(
+  node: ReplayResourceNode,
+): ReadonlySet<string> {
+  switch (node.tagName) {
+    case "img":
+    case "source":
+      return REPLAY_SRCSET_ATTRIBUTES;
+    case "video":
+      return REPLAY_VIDEO_ATTRIBUTES;
+    case "audio":
+    case "track":
+      return REPLAY_SRC_ATTRIBUTES;
+    case "input":
+      return node.type === "image"
+        ? REPLAY_SRC_ATTRIBUTES
+        : NO_REPLAY_RESOURCE_ATTRIBUTES;
+    case "link": {
+      const rels = node.rel.split(/\s+/);
+      const isLoadBearingResource =
+        rels.some((rel) => REPLAY_RESOURCE_LINK_RELS.has(rel)) ||
+        (rels.includes("preload") &&
+          REPLAY_RESOURCE_PRELOAD_TYPES.has(node.as));
+      return isLoadBearingResource
+        ? REPLAY_HREF_ATTRIBUTES
+        : NO_REPLAY_RESOURCE_ATTRIBUTES;
+    }
+    default:
+      return NO_REPLAY_RESOURCE_ATTRIBUTES;
+  }
+}
+
+/**
+ * Build a path-aware replay serializer without cloning the rrweb event.
+ *
+ * Privacy still wins for Meta/navigation URLs, executable/embed URLs, anchor
+ * hrefs, and custom console/network diagnostics. The narrow exception is
+ * load-bearing stylesheet, font, image, and media attributes: changing those
+ * signed URLs makes rrweb rebuild a page that never existed. JSON.stringify
+ * calls a replacer for an `attributes` object before its children, so the
+ * WeakMap lets the child callback recognize only that bag.
+ */
+function createReplayScrubReplacer(
+  resourceNodes: Map<number, ReplayResourceNode>,
+): (this: unknown, key: string, value: unknown) => unknown {
+  const preservedAttributes = new WeakMap<object, ReadonlySet<string>>();
+
+  return function replayScrubReplacer(
+    this: unknown,
+    key: string,
+    value: unknown,
+  ): unknown {
+    if (key === "attributes" && value && typeof value === "object") {
+      const attributes = value as Record<string, unknown>;
+      const holder =
+        this && typeof this === "object"
+          ? (this as Record<string, unknown>)
+          : undefined;
+      const tagName =
+        typeof holder?.tagName === "string" ? holder.tagName.toLowerCase() : "";
+      const nodeId =
+        typeof holder?.id === "number" && Number.isFinite(holder.id)
+          ? holder.id
+          : undefined;
+      let resourceNode: ReplayResourceNode | undefined;
+      if (tagName && REPLAY_RESOURCE_TAGS.has(tagName)) {
+        resourceNode = updateReplayResourceNode(
+          { tagName, rel: "", as: "", type: "" },
+          attributes,
+        );
+      } else if (nodeId !== undefined && !tagName) {
+        const current = resourceNodes.get(nodeId);
+        if (current) {
+          resourceNode = updateReplayResourceNode(current, attributes);
+        }
+      }
+      if (nodeId !== undefined && resourceNode) {
+        resourceNodes.set(nodeId, resourceNode);
+      }
+
+      const resourceKeys = resourceNode
+        ? replayPreservedResourceAttributes(resourceNode)
+        : NO_REPLAY_RESOURCE_ATTRIBUTES;
+
+      if (resourceKeys.size > 0) preservedAttributes.set(value, resourceKeys);
+      return value;
+    }
+
+    if (
+      typeof value === "string" &&
+      this &&
+      typeof this === "object" &&
+      preservedAttributes.get(this)?.has(key.toLowerCase())
+    ) {
+      return value;
+    }
+    return typeof value === "string" ? scrubStringValue(key, value) : value;
+  };
 }
 
 /**
@@ -741,9 +1193,13 @@ function scrubReplayReplacer(key: string, value: unknown): unknown {
  * directly on the queue and reused verbatim at flush, so each event is
  * stringified exactly once (was: deep-clone + size-stringify + flush-stringify).
  */
-function serializeReplayEvent(event: ReplayEvent): string {
+function serializeReplayEvent(
+  event: ReplayEvent,
+  resourceNodes: Map<number, ReplayResourceNode>,
+): string {
   try {
-    return JSON.stringify(event, scrubReplayReplacer);
+    if (event.type === 2) resourceNodes.clear();
+    return JSON.stringify(event, createReplayScrubReplacer(resourceNodes));
   } catch {
     return "";
   }
@@ -766,9 +1222,14 @@ function enqueueReplayEvent(
   event: ReplayEvent,
 ): void {
   if (!state.options) return;
-  const serialized = serializeReplayEvent(event);
+  const eventType = typeof event.type === "number" ? event.type : null;
+  if (state.awaitingFullSnapshot) {
+    if (eventType !== RRWEB_FULL_SNAPSHOT_EVENT_TYPE) return;
+    state.awaitingFullSnapshot = false;
+  }
+  const serialized = serializeReplayEvent(event, state.resourceNodes);
   if (!serialized) return;
-  const estimatedBytes = serialized.length;
+  const estimatedBytes = replaySerializedBytes(serialized);
   if (
     state.queue.length > 0 &&
     state.queuedBytes + estimatedBytes > state.options.maxBatchBytes
@@ -777,8 +1238,9 @@ function enqueueReplayEvent(
   }
   state.queue.push({
     json: serialized,
+    byteLength: estimatedBytes,
     timestampMs: replayEventTimestampMs(event),
-    type: typeof event.type === "number" ? event.type : null,
+    type: eventType,
   });
   state.queuedBytes += estimatedBytes;
   flushQueuedReplayIfNeeded(state);
@@ -977,6 +1439,27 @@ function canUseReplayKeepalive(body: BodyInit): boolean {
   return replayUploadBodyBytes(body) <= MAX_KEEPALIVE_REPLAY_UPLOAD_BYTES;
 }
 
+/** Thrown by `sendReplayUpload` on a non-ok HTTP response, carrying the
+ * status so `flushSessionReplay` can tell a permanent client rejection
+ * (e.g. a 409 checksum conflict, which can never succeed on retry) apart
+ * from a transient failure worth retrying. */
+class ReplayUploadHttpError extends Error {
+  readonly status: number;
+  constructor(status: number) {
+    super(`Session replay upload failed with HTTP ${status}`);
+    this.name = "ReplayUploadHttpError";
+    this.status = status;
+  }
+}
+
+/** 4xx statuses where retrying the exact same batch can never succeed --
+ * e.g. a 409 chunk-sequence/checksum conflict, or a 400 the server will
+ * reject again. 408 (timeout) and 429 (rate limit) are excluded because a
+ * later retry can plausibly succeed. */
+function isDefinitiveReplayUploadClientError(status: number): boolean {
+  return status >= 400 && status < 500 && status !== 408 && status !== 429;
+}
+
 async function sendReplayUpload(
   options: NormalizedSessionReplayOptions,
   body: string,
@@ -992,9 +1475,7 @@ async function sendReplayUpload(
       headers: { "Content-Type": "text/plain;charset=UTF-8" },
     });
     if (!response.ok) {
-      throw new Error(
-        `Session replay upload failed with HTTP ${response.status}`,
-      );
+      throw new ReplayUploadHttpError(response.status);
     }
     return;
   }
@@ -1012,9 +1493,7 @@ async function sendReplayUpload(
     },
   });
   if (!response.ok) {
-    throw new Error(
-      `Session replay upload failed with HTTP ${response.status}`,
-    );
+    throw new ReplayUploadHttpError(response.status);
   }
 }
 
@@ -1029,6 +1508,25 @@ function isFinalFlushReason(reason: string): boolean {
   ].includes(reason);
 }
 
+function flushReasonPriority(reason: string): number {
+  // Unload reasons must retain their keepalive sequence reservation even when
+  // another final request (for example, an explicit manual stop) is coalesced.
+  if (reason === "pagehide" || reason === "beforeunload") return 3;
+  if (isFinalFlushReason(reason)) return 2;
+  if (reason === "visibility-hidden") return 1;
+  return 0;
+}
+
+function mergePendingFlushReason(
+  current: string | null,
+  requested: string,
+): string {
+  if (!current) return requested;
+  return flushReasonPriority(requested) > flushReasonPriority(current)
+    ? requested
+    : current;
+}
+
 function shouldReserveSequenceBeforeKeepalive(reason: string): boolean {
   return (
     reason === "pagehide" ||
@@ -1068,7 +1566,99 @@ function flushQueuedReplayIfNeeded(state: SessionReplayState): void {
 }
 
 function queuedReplayBytes(events: QueuedReplayEvent[]): number {
-  return events.reduce((total, event) => total + event.json.length, 0);
+  return events.reduce(
+    (total, event) => total + queuedReplayEventBytes(event),
+    0,
+  );
+}
+
+function replaySerializedBytes(value: string): number {
+  if (REPLAY_TEXT_ENCODER) return REPLAY_TEXT_ENCODER.encode(value).byteLength;
+  if (typeof Blob !== "undefined") return new Blob([value]).size;
+  return value.length;
+}
+
+function queuedReplayEventBytes(event: QueuedReplayEvent): number {
+  return Number.isFinite(event.byteLength)
+    ? event.byteLength
+    : replaySerializedBytes(event.json);
+}
+
+/**
+ * Remove one bounded FIFO prefix from the live queue.
+ *
+ * Threshold-triggered flushes may arrive while another upload is active. The
+ * old `queue.splice(0)` drained that entire accumulated backlog on the next
+ * flush, bypassing both byte and event caps. Keep FullSnapshots isolated and
+ * always take at least one event so an individually large snapshot can still
+ * make progress.
+ */
+function takeQueuedReplayBatch(state: SessionReplayState): QueuedReplayEvent[] {
+  const options = state.options;
+  if (!options || state.queue.length === 0) return [];
+
+  let count = 0;
+  let bytes = 0;
+  for (const event of state.queue) {
+    if (count > 0 && event.type === RRWEB_FULL_SNAPSHOT_EVENT_TYPE) break;
+    if (
+      count > 0 &&
+      (count >= options.maxEventsPerBatch ||
+        bytes + queuedReplayEventBytes(event) > options.maxBatchBytes)
+    ) {
+      break;
+    }
+    count += 1;
+    bytes += queuedReplayEventBytes(event);
+    if (event.type === RRWEB_FULL_SNAPSHOT_EVENT_TYPE) break;
+  }
+
+  const events = state.queue.splice(0, Math.max(1, count));
+  state.queuedBytes = queuedReplayBytes(state.queue);
+  return events;
+}
+
+function splitReplayBatch(
+  events: QueuedReplayEvent[],
+): [QueuedReplayEvent[], QueuedReplayEvent[]] | null {
+  if (events.length < 2) return null;
+  const targetBytes = queuedReplayBytes(events) / 2;
+  let splitAt = 1;
+  let bytes = events[0] ? queuedReplayEventBytes(events[0]) : 0;
+  while (splitAt < events.length - 1 && bytes < targetBytes) {
+    const event = events[splitAt];
+    if (event) bytes += queuedReplayEventBytes(event);
+    splitAt += 1;
+  }
+  return [events.slice(0, splitAt), events.slice(splitAt)];
+}
+
+function replayBatchNeedsDomReset(events: QueuedReplayEvent[]): boolean {
+  return events.some((event) => {
+    if (event.type === RRWEB_FULL_SNAPSHOT_EVENT_TYPE) return true;
+    if (event.type !== 3) return false;
+    try {
+      const parsed = JSON.parse(event.json) as { data?: { source?: unknown } };
+      // rrweb IncrementalSource.Mutation is zero. Dropping one may leave later
+      // node references dangling until another FullSnapshot resets the mirror.
+      return parsed.data?.source === 0;
+    } catch {
+      return true;
+    }
+  });
+}
+
+function quarantinePendingReplayUntilFullSnapshot(
+  state: SessionReplayState,
+): void {
+  const pending = [...state.retryBatches.flat(), ...state.queue];
+  const resetAt = pending.findIndex(
+    (event) => event.type === RRWEB_FULL_SNAPSHOT_EVENT_TYPE,
+  );
+  state.retryBatches = [];
+  state.queue = resetAt >= 0 ? pending.slice(resetAt) : [];
+  state.queuedBytes = queuedReplayBytes(state.queue);
+  state.awaitingFullSnapshot = resetAt < 0;
 }
 
 function restoreReplayEvents(
@@ -1109,9 +1699,18 @@ function rollbackReplaySequenceReservation(
 
 export async function flushSessionReplay(reason = "manual"): Promise<void> {
   const state = getState();
-  if (!state.options || !hasPendingReplayBatch(state) || state.flushing) return;
-  const events = state.retryBatches.shift() ?? state.queue.splice(0);
-  state.queuedBytes = queuedReplayBytes(state.queue);
+  if (!state.options) return;
+  if (state.flushing) {
+    state.pendingFlushReason = mergePendingFlushReason(
+      state.pendingFlushReason,
+      reason,
+    );
+    return new Promise<void>((resolve) => {
+      state.pendingFlushWaiters.push(resolve);
+    });
+  }
+  if (!hasPendingReplayBatch(state)) return;
+  const events = state.retryBatches.shift() ?? takeQueuedReplayBatch(state);
   const payload = buildReplayBody(state, reason, events);
   if (!payload || !state.options) {
     restoreReplayEvents(state, events);
@@ -1120,6 +1719,9 @@ export async function flushSessionReplay(reason = "manual"): Promise<void> {
   state.flushing = true;
   let uploaded = false;
   let reservedSequence = false;
+  let splitRejectedBatch = false;
+  let droppedOversizedBatch = false;
+  let definitiveClientErrorStatus: number | null = null;
   try {
     await sendReplayUpload(state.options, payload.body, {
       beforeKeepaliveUpload: shouldReserveSequenceBeforeKeepalive(reason)
@@ -1130,25 +1732,207 @@ export async function flushSessionReplay(reason = "manual"): Promise<void> {
         : undefined,
     });
     if (!reservedSequence) advanceReplaySequence(state, payload);
+    state.automaticConflictRestartAttempted = false;
     uploaded = true;
   } catch (error) {
     if (reservedSequence) rollbackReplaySequenceReservation(state, payload);
-    restoreReplayEvents(state, events);
+    // A definitive 4xx (e.g. a 409 chunk-sequence/checksum conflict) can
+    // never succeed by retrying the exact same batch -- requeuing it would
+    // just spin forever, blocking every later batch behind it (flushes are
+    // FIFO via `retryBatches`). Drop it and move on instead.
+    const rejectedStatus =
+      error instanceof ReplayUploadHttpError ? error.status : null;
+    const splitBatch = rejectedStatus === 413 ? splitReplayBatch(events) : null;
+    const isUnsplittableOversizedBatch =
+      rejectedStatus === 413 && splitBatch === null;
+    const isDefinitiveClientError =
+      error instanceof ReplayUploadHttpError &&
+      isDefinitiveReplayUploadClientError(error.status) &&
+      !splitBatch &&
+      !isUnsplittableOversizedBatch;
+    if (splitBatch) {
+      // A server or platform can enforce a stricter decompressed-body limit
+      // than the recorder's configured queue cap. Bisect in FIFO order and
+      // retry both halves at the same sequence; only successful halves advance
+      // it, so no event is duplicated or skipped.
+      state.retryBatches.unshift(...splitBatch);
+      splitRejectedBatch = true;
+    } else if (isUnsplittableOversizedBatch) {
+      // This one event cannot be made any smaller. Drop only the rejected
+      // singleton and keep later retry halves/live batches in FIFO order. If
+      // it carried DOM structure, quarantine dependent mutations until a new
+      // FullSnapshot can safely re-anchor rrweb's node mirror.
+      droppedOversizedBatch = true;
+      if (replayBatchNeedsDomReset(events)) {
+        quarantinePendingReplayUntilFullSnapshot(state);
+      }
+    } else if (isDefinitiveClientError) {
+      // Continuing after a checksum/sequence conflict would reuse the same
+      // rejected sequence forever. More importantly, advancing past it would
+      // append mutations to a replay whose DOM stream may belong to another
+      // tab. End this recorder and clear its persisted identity so the next
+      // start creates a clean replay instead of producing corrupt playback.
+      state.queue = [];
+      state.queuedBytes = 0;
+      state.retryBatches = [];
+      removeStoredReplaySession(payload.replayId);
+      definitiveClientErrorStatus = error.status;
+    } else {
+      restoreReplayEvents(state, events);
+    }
     // Guard the recorder's own warning so console capture never records it
     // (a captured warning would enqueue an event and retrigger a flush).
     const previousInternal = replayCaptureInternal;
     replayCaptureInternal = true;
     try {
-      console.warn("[session-replay] upload failed", error);
+      if (splitRejectedBatch) {
+        console.warn(
+          "[session-replay] splitting oversized upload (HTTP 413)",
+          error,
+        );
+      } else if (droppedOversizedBatch) {
+        console.warn(
+          "[session-replay] dropping oversized replay event (HTTP 413)",
+          error,
+        );
+      } else if (isDefinitiveClientError) {
+        console.warn(
+          `[session-replay] dropping upload (HTTP ${(error as ReplayUploadHttpError).status})`,
+          error,
+        );
+      } else {
+        console.warn("[session-replay] upload failed", error);
+      }
     } finally {
       replayCaptureInternal = previousInternal;
     }
   } finally {
     state.flushing = false;
   }
-  if (uploaded && hasPendingReplayBatch(state)) {
-    flushQueuedReplayIfNeeded(state);
+  const coalescedReason = state.pendingFlushReason;
+  const coalescedWaiters = coalescedReason
+    ? state.pendingFlushWaiters.splice(0)
+    : [];
+  if (coalescedReason) state.pendingFlushReason = null;
+
+  if (coalescedReason) {
+    // A stop/unload request that arrived during this upload owns the tail.
+    // Its higher-priority reason must replace threshold/internal reasons so a
+    // small final batch is not stranded or mislabeled as active.
+    await flushSessionReplay(coalescedReason);
+  } else if (splitRejectedBatch || droppedOversizedBatch) {
+    // Preserve final-status and unload semantics through every half. In
+    // particular, pagehide/beforeunload retries must still reserve their
+    // sequence before a keepalive fetch, and completed flushes must not be
+    // rewritten to an internal recovery reason/status.
+    await flushSessionReplay(reason);
+  } else if (uploaded && hasPendingReplayBatch(state)) {
+    const mustContinue =
+      state.retryBatches.length > 0 ||
+      isFinalFlushReason(reason) ||
+      shouldFlushQueuedReplay(state);
+    if (mustContinue) {
+      if (isFinalFlushReason(reason)) {
+        await flushSessionReplay(reason);
+      } else void flushSessionReplay(reason);
+    }
+  }
+  if (
+    definitiveClientErrorStatus !== null &&
+    state.replayId === payload.replayId
+  ) {
+    const rejectedOptions = state.options;
+    const shouldRestartAfterConflict =
+      definitiveClientErrorStatus === 409 &&
+      state.active &&
+      !isFinalFlushReason(reason) &&
+      !state.automaticConflictRestartAttempted;
+    if (shouldRestartAfterConflict) {
+      state.automaticConflictRestartAttempted = true;
+    }
+
+    await stopSessionReplay("upload-rejected");
+
+    // A 409 means this replay identity can no longer append safely (usually a
+    // duplicated tab that inherited sessionStorage, or an old shared identity
+    // still open during rollout). Do not leave a long-lived SPA tab silently
+    // unrecorded until its next page load: restart rrweb under a fresh per-tab
+    // id so it emits a new Meta + FullSnapshot stream. Limit this to one retry
+    // until an upload succeeds; other definitive 4xx responses usually reflect
+    // configuration/input errors and must not create a restart loop.
+    let restartResult: SessionReplayStartResult | null = null;
+    if (shouldRestartAfterConflict && rejectedOptions) {
+      restartResult = await restartSessionReplayAfterConflict(
+        state,
+        rejectedOptions,
+        payload.sessionId,
+      );
+    }
+
+    // Rare recovery-path telemetry lets Analytics owners quantify conflicts
+    // without recording the rejected replay id, URL, or any captured content.
+    try {
+      rejectedOptions?.onUploadRejected?.({
+        status: definitiveClientErrorStatus,
+        restartAttempted: shouldRestartAfterConflict,
+        restartSucceeded: restartResult?.started === true,
+        ...(restartResult?.reason
+          ? { restartReason: restartResult.reason }
+          : {}),
+      });
+    } catch {
+      // best-effort telemetry must never interfere with recording recovery
+    }
+  }
+  for (const resolve of coalescedWaiters) resolve();
+}
+
+/**
+ * Restart a recorder whose replay identity was rejected without routing the
+ * already-normalized options back through the public start API.
+ *
+ * The original recording already passed whole-session sampling. Re-entering
+ * `startSessionReplay` here would ask `getOrCreateAnalyticsSessionId` again;
+ * if the analytics session rotated while the upload was in flight, recovery
+ * could be sampled out and leave a long-lived SPA tab silently unrecorded.
+ * Keeping the original session id and accepted sampling decision also lets us
+ * reuse the exact normalized console/network capture caps instead of relying
+ * on internal option shapes continuing to round-trip through the public API.
+ */
+async function restartSessionReplayAfterConflict(
+  state: SessionReplayState,
+  options: NormalizedSessionReplayOptions,
+  sessionId: string,
+): Promise<SessionReplayStartResult> {
+  if (options.shouldStart && !options.shouldStart()) {
+    return { started: false, reason: "disabled", sessionId, sampled: true };
+  }
+
+  const initialProperties = replayExtraProperties(options);
+  if (options.requireSignedInUser && !replayUserEmail(initialProperties)) {
+    return {
+      started: false,
+      reason: "missing-user-id",
+      sessionId,
+      sampled: true,
+    };
+  }
+  if (!isUrlRecordable(window.location.href, options)) {
+    return {
+      started: false,
+      reason: "url-blocked",
+      sessionId,
+      sampled: true,
+    };
   }
+
+  return startSessionReplayRecorder(
+    state,
+    options,
+    sessionId,
+    true,
+    initialProperties,
+  );
 }
 
 function installUrlMonitor(state: SessionReplayState): void {
@@ -1199,6 +1983,101 @@ function installLifecycleListeners(state: SessionReplayState): void {
   };
 }
 
+function markedSessionReplayIframes(): HTMLIFrameElement[] {
+  if (typeof document.querySelectorAll !== "function") return [];
+  return Array.from(
+    document.querySelectorAll<HTMLIFrameElement>(
+      `iframe[${SESSION_REPLAY_IFRAME_ATTRIBUTE}]`,
+    ),
+  );
+}
+
+function markedSessionReplayIframeForSource(
+  source: MessageEventSource | null,
+): HTMLIFrameElement | null {
+  if (!source) return null;
+  return (
+    markedSessionReplayIframes().find(
+      (iframe) => iframe.contentWindow === source,
+    ) ?? null
+  );
+}
+
+function sessionReplayIframePrivacyOptions(
+  options: NormalizedSessionReplayOptions,
+): SessionReplayIframePrivacyOptions {
+  return {
+    blockSelector: options.blockSelector,
+    ignoreSelector: options.ignoreSelector,
+    maskTextClass: options.maskTextClass,
+    maskTextSelector: options.maskTextSelector,
+    maskAllInputs: options.maskAllInputs,
+    maskInputOptions: DEFAULT_MASK_INPUT_OPTIONS,
+    recordCanvas: options.recordCanvas,
+    collectFonts: options.collectFonts,
+    inlineImages: options.inlineImages,
+    sampling: options.eventSampling,
+  };
+}
+
+function postSessionReplayIframeMessage(
+  iframe: HTMLIFrameElement,
+  message: SessionReplayIframeStartMessage | SessionReplayIframeStopMessage,
+): void {
+  try {
+    iframe.contentWindow?.postMessage(message, "*");
+  } catch {
+    // The frame may have navigated or detached between discovery and send.
+  }
+}
+
+/**
+ * Cooperative opaque/cross-origin iframe recording.
+ *
+ * rrweb cannot inspect these documents from the host. Framework-owned child
+ * frames carry a marker and inject a tiny recorder that probes its direct
+ * parent. Only an active host recorder responds, and only when the probe's
+ * source is the contentWindow of a currently marked direct iframe.
+ */
+function installSessionReplayIframeBridge(
+  state: SessionReplayState,
+  options: NormalizedSessionReplayOptions,
+): void {
+  if (!options.recordCrossOriginIframes || state.restoreIframeBridge) return;
+
+  const startMessage: SessionReplayIframeStartMessage = {
+    type: SESSION_REPLAY_IFRAME_START,
+    options: sessionReplayIframePrivacyOptions(options),
+  };
+  const stopMessage: SessionReplayIframeStopMessage = {
+    type: SESSION_REPLAY_IFRAME_STOP,
+  };
+  const sendStart = (iframe: HTMLIFrameElement) =>
+    postSessionReplayIframeMessage(iframe, startMessage);
+  const onMessage = (event: MessageEvent) => {
+    if (!state.active) return;
+    if (
+      !event.data ||
+      typeof event.data !== "object" ||
+      event.data.type !== SESSION_REPLAY_IFRAME_PROBE
+    ) {
+      return;
+    }
+    const iframe = markedSessionReplayIframeForSource(event.source);
+    if (iframe) sendStart(iframe);
+  };
+
+  window.addEventListener("message", onMessage);
+  for (const iframe of markedSessionReplayIframes()) sendStart(iframe);
+  state.restoreIframeBridge = () => {
+    window.removeEventListener("message", onMessage);
+    for (const iframe of markedSessionReplayIframes()) {
+      postSessionReplayIframeMessage(iframe, stopMessage);
+    }
+    state.restoreIframeBridge = null;
+  };
+}
+
 function truncateCaptureText(value: string, maxLength: number): string {
   return value.length > maxLength ? value.slice(0, maxLength) : value;
 }
@@ -2043,7 +2922,34 @@ async function startSessionReplayRecorder(
     return { started: false, reason: "disabled", sessionId, sampled };
   }
 
-  const replaySession = getOrCreateReplaySession(sessionId);
+  let replaySession = getOrCreateReplaySession(sessionId);
+  const instanceNonce = generateReplayId();
+  const { channel: replayChannel, probeClaim } = createReplayClaimChannel(
+    state,
+    instanceNonce,
+  );
+  // Only a *resumed* id needs the duplicated-tab check -- a freshly minted
+  // id can never collide with a recorder that's already running, so this
+  // never adds startup latency for the common "new tab" case.
+  if (replaySession.resumed && replayChannel) {
+    const taken = await probeClaim(replaySession.replayId);
+    if (taken) {
+      const freshReplayId = generateReplayId();
+      const freshStartedAtMs = Date.now();
+      writeStoredReplaySession({
+        sessionId,
+        replayId: freshReplayId,
+        startedAtMs: freshStartedAtMs,
+        sequence: 0,
+      });
+      replaySession = {
+        replayId: freshReplayId,
+        startedAtMs: freshStartedAtMs,
+        sequence: 0,
+        resumed: false,
+      };
+    }
+  }
   state.options = normalized;
   state.replayId = replaySession.replayId;
   state.startedAtMs = replaySession.startedAtMs;
@@ -2051,7 +2957,12 @@ async function startSessionReplayRecorder(
   state.queue = [];
   state.queuedBytes = 0;
   state.retryBatches = [];
+  state.pendingFlushReason = null;
+  for (const resolve of state.pendingFlushWaiters.splice(0)) resolve();
+  state.awaitingFullSnapshot = false;
+  state.resourceNodes.clear();
   state.stopRecorder = null;
+  state.broadcastChannel = replayChannel;
   state.lastAuthenticatedProperties = replayUserEmail(initialProperties)
     ? { ...initialProperties }
     : null;
@@ -2073,22 +2984,7 @@ async function startSessionReplayRecorder(
       recordCrossOriginIframes: normalized.recordCrossOriginIframes,
       collectFonts: normalized.collectFonts,
       inlineImages: normalized.inlineImages,
-      maskInputOptions: {
-        color: true,
-        date: true,
-        "datetime-local": true,
-        email: true,
-        month: true,
-        number: true,
-        password: true,
-        range: true,
-        search: true,
-        tel: true,
-        text: true,
-        time: true,
-        url: true,
-        week: true,
-      },
+      maskInputOptions: DEFAULT_MASK_INPUT_OPTIONS,
     });
     if (typeof stopRecorder !== "function") {
       state.active = false;
@@ -2096,6 +2992,12 @@ async function startSessionReplayRecorder(
       state.replayId = null;
       state.startedAtMs = null;
       state.lastAuthenticatedProperties = null;
+      try {
+        state.broadcastChannel?.close();
+      } catch {
+        // best-effort cleanup
+      }
+      state.broadcastChannel = null;
       return { started: false, reason: "record-failed", sessionId, sampled };
     }
     state.stopRecorder = stopRecorder;
@@ -2109,6 +3011,7 @@ async function startSessionReplayRecorder(
     );
     installUrlMonitor(state);
     installLifecycleListeners(state);
+    installSessionReplayIframeBridge(state, normalized);
     state.addCustomEvent =
       typeof rrweb.record.addCustomEvent === "function"
         ? rrweb.record.addCustomEvent
@@ -2127,12 +3030,19 @@ async function startSessionReplayRecorder(
       // best-effort interceptor teardown
     }
     state.restoreCaptures = null;
+    state.restoreIframeBridge?.();
     state.addCustomEvent = null;
     state.active = false;
     state.options = null;
     state.replayId = null;
     state.startedAtMs = null;
     state.lastAuthenticatedProperties = null;
+    try {
+      state.broadcastChannel?.close();
+    } catch {
+      // best-effort cleanup
+    }
+    state.broadcastChannel = null;
     return { started: false, reason: "record-failed", sessionId, sampled };
   }
 }
@@ -2149,6 +3059,7 @@ export async function stopSessionReplay(reason = "manual"): Promise<void> {
     // best-effort interceptor teardown
   }
   state.restoreCaptures = null;
+  state.restoreIframeBridge?.();
   state.active = false;
   state.addCustomEvent = null;
   try {
@@ -2167,6 +3078,12 @@ export async function stopSessionReplay(reason = "manual"): Promise<void> {
   }
   state.restoreUrlMonitor?.();
   state.removeLifecycleListeners?.();
+  try {
+    state.broadcastChannel?.close();
+  } catch {
+    // best-effort cleanup
+  }
+  state.broadcastChannel = null;
   await flushSessionReplay(reason);
 }
 
@@ -2182,9 +3099,10 @@ export function isSessionReplayActive(): boolean {
 
 /**
  * The active session replay id when a recording is running, or the last one
- * persisted for this analytics session in `localStorage`. First-party error
- * capture uses this to tie each captured exception to the replay it happened
- * in, so triage can jump straight to `/sessions/<recordingId>`.
+ * persisted for this analytics session in this tab's `sessionStorage`.
+ * First-party error capture uses this to tie each captured exception to the
+ * replay it happened in, so triage can jump straight to
+ * `/sessions/<recordingId>`.
  */
 export function getSessionReplayId(): string | null {
   const state = getState();