@agent-native/core 0.98.3 → 0.98.4

package/dist/client/session-replay.js

@@ -42,6 +42,11 @@ const DEFAULT_MAX_EVENTS_PER_BATCH = 50;
 const DEFAULT_MAX_BATCH_BYTES = 256 * 1024;
 const MAX_KEEPALIVE_REPLAY_UPLOAD_BYTES = 60 * 1024;
 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";
 /** rrweb custom-event tag for captured fetch/XHR request summaries. */
@@ -111,26 +116,63 @@ function getState() {
             restoreCaptures: null,
             options: null,
             lastAuthenticatedProperties: null,
+            resourceNodes: new Map(),
+            automaticConflictRestartAttempted: false,
+            broadcastChannel: null,
         };
     }
-    return g[SESSION_REPLAY_STATE_KEY];
-}
-function safeStorageGet(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();
+    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) {
     try {
-        return window.localStorage.getItem(key);
+        return window.sessionStorage.getItem(key);
     }
     catch {
         return null;
     }
 }
-function safeStorageSet(key, value) {
+function safeSessionStorageSet(key, value) {
+    try {
+        window.sessionStorage.setItem(key, value);
+    }
+    catch {
+        // private browsing / storage disabled -- replay still works for this page
+    }
+}
+function safeSessionStorageRemove(key) {
     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() {
+    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() {
     try {
         if (typeof crypto !== "undefined" &&
@@ -144,7 +186,7 @@ function generateReplayId() {
     return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
 }
 function readStoredReplaySession() {
-    const raw = safeStorageGet(SESSION_REPLAY_ID_STORAGE_KEY);
+    const raw = safeSessionStorageGet(SESSION_REPLAY_ID_STORAGE_KEY);
     if (!raw)
         return null;
     try {
@@ -158,9 +200,37 @@ function readStoredReplaySession() {
     }
 }
 function writeStoredReplaySession(value) {
-    safeStorageSet(SESSION_REPLAY_ID_STORAGE_KEY, JSON.stringify(value));
+    safeSessionStorageSet(SESSION_REPLAY_ID_STORAGE_KEY, JSON.stringify(value));
 }
+function removeStoredReplaySession(replayId) {
+    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) {
+    clearLegacyLocalStorageReplaySession();
     const parsed = readStoredReplaySession();
     if (parsed?.sessionId === sessionId && parsed.replayId) {
         const startedAtMs = typeof parsed.startedAtMs === "number" &&
@@ -173,12 +243,115 @@ function getOrCreateReplaySession(sessionId) {
             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() {
+    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, instanceNonce) {
+    const channel = openReplayBroadcastChannel();
+    if (!channel) {
+        return { channel: null, probeClaim: async () => false };
+    }
+    let pending = null;
+    channel.onmessage = (event) => {
+        const data = event?.data;
+        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 = {
+                    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) => new Promise((resolve) => {
+        const timer = window.setTimeout(() => {
+            pending = null;
+            resolve(false);
+        }, SESSION_REPLAY_CLAIM_TIMEOUT_MS);
+        pending = { replayId, resolve, timer };
+        try {
+            const claim = {
+                type: "an-replay-claim",
+                replayId,
+                instanceNonce,
+            };
+            channel.postMessage(claim);
+        }
+        catch {
+            window.clearTimeout(timer);
+            pending = null;
+            resolve(false);
+        }
+    });
+    return { channel, probeClaim };
 }
 function persistReplaySequence(sessionId, replayId, startedAtMs, sequence) {
     writeStoredReplaySession({
@@ -361,6 +534,7 @@ function normalizeOptions(options) {
         eventSampling: options.eventSampling ?? DEFAULT_EVENT_SAMPLING,
         console: normalizeCaptureToggle(options.console, DEFAULT_MAX_CONSOLE_EVENTS),
         network: normalizeCaptureToggle(options.network, DEFAULT_MAX_NETWORK_EVENTS),
+        onUploadRejected: options.onUploadRejected,
         extraProperties: options.extraProperties,
         shouldStart: options.shouldStart,
     };
@@ -424,17 +598,141 @@ function scrubReplayValue(value, key = "", depth = 0, seen = new WeakSet()) {
  * 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, value) {
-    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();
+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, key) {
+    return typeof attributes[key] === "string"
+        ? attributes[key].toLowerCase()
+        : "";
+}
+function updateReplayResourceNode(current, attributes) {
+    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) {
+    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) {
+    const preservedAttributes = new WeakMap();
+    return function replayScrubReplacer(key, value) {
+        if (key === "attributes" && value && typeof value === "object") {
+            const attributes = value;
+            const holder = this && typeof this === "object"
+                ? this
+                : 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;
+            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;
+    };
 }
 /**
  * Serialize + scrub one event in a single pass. The resulting string is stored
  * 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) {
+function serializeReplayEvent(event, resourceNodes) {
     try {
-        return JSON.stringify(event, scrubReplayReplacer);
+        if (event.type === 2)
+            resourceNodes.clear();
+        return JSON.stringify(event, createReplayScrubReplacer(resourceNodes));
     }
     catch {
         return "";
@@ -455,7 +753,7 @@ function replayEventTimestampMs(event) {
 function enqueueReplayEvent(state, event) {
     if (!state.options)
         return;
-    const serialized = serializeReplayEvent(event);
+    const serialized = serializeReplayEvent(event, state.resourceNodes);
     if (!serialized)
         return;
     const estimatedBytes = serialized.length;
@@ -629,6 +927,25 @@ function replayUploadBodyBytes(body) {
 function canUseReplayKeepalive(body) {
     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 {
+    status;
+    constructor(status) {
+        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) {
+    return status >= 400 && status < 500 && status !== 408 && status !== 429;
+}
 async function sendReplayUpload(options, body, callbacks = {}) {
     if (isCrossOriginReplayEndpoint(options.endpoint)) {
         const canUseKeepalive = canUseReplayKeepalive(body);
@@ -641,7 +958,7 @@ async function sendReplayUpload(options, body, callbacks = {}) {
             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;
     }
@@ -659,7 +976,7 @@ async function sendReplayUpload(options, body, callbacks = {}) {
         },
     });
     if (!response.ok) {
-        throw new Error(`Session replay upload failed with HTTP ${response.status}`);
+        throw new ReplayUploadHttpError(response.status);
     }
 }
 function isFinalFlushReason(reason) {
@@ -739,6 +1056,7 @@ export async function flushSessionReplay(reason = "manual") {
     state.flushing = true;
     let uploaded = false;
     let reservedSequence = false;
+    let definitiveClientErrorStatus = null;
     try {
         await sendReplayUpload(state.options, payload.body, {
             beforeKeepaliveUpload: shouldReserveSequenceBeforeKeepalive(reason)
@@ -750,18 +1068,44 @@ export async function flushSessionReplay(reason = "manual") {
         });
         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 isDefinitiveClientError = error instanceof ReplayUploadHttpError &&
+            isDefinitiveReplayUploadClientError(error.status);
+        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 (isDefinitiveClientError) {
+                console.warn(`[session-replay] dropping upload (HTTP ${error.status})`, error);
+            }
+            else {
+                console.warn("[session-replay] upload failed", error);
+            }
         }
         finally {
             replayCaptureInternal = previousInternal;
@@ -773,6 +1117,79 @@ export async function flushSessionReplay(reason = "manual") {
     if (uploaded && hasPendingReplayBatch(state)) {
         flushQueuedReplayIfNeeded(state);
     }
+    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 = 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
+        }
+    }
+}
+/**
+ * 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, options, sessionId) {
+    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) {
     if (!state.options || state.restoreUrlMonitor)
@@ -1503,7 +1920,31 @@ async function startSessionReplayRecorder(state, normalized, sessionId, sampled,
     if (normalized.shouldStart && !normalized.shouldStart()) {
         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;
@@ -1511,7 +1952,9 @@ async function startSessionReplayRecorder(state, normalized, sessionId, sampled,
     state.queue = [];
     state.queuedBytes = 0;
     state.retryBatches = [];
+    state.resourceNodes.clear();
     state.stopRecorder = null;
+    state.broadcastChannel = replayChannel;
     state.lastAuthenticatedProperties = replayUserEmail(initialProperties)
         ? { ...initialProperties }
         : null;
@@ -1555,6 +1998,13 @@ async function startSessionReplayRecorder(state, normalized, sessionId, sampled,
             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;
@@ -1588,6 +2038,13 @@ async function startSessionReplayRecorder(state, normalized, sessionId, sampled,
         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 };
     }
 }
@@ -1624,6 +2081,13 @@ export async function stopSessionReplay(reason = "manual") {
     }
     state.restoreUrlMonitor?.();
     state.removeLifecycleListeners?.();
+    try {
+        state.broadcastChannel?.close();
+    }
+    catch {
+        // best-effort cleanup
+    }
+    state.broadcastChannel = null;
     await flushSessionReplay(reason);
 }
 export function maybeStartSessionReplay(options = {}) {
@@ -1634,9 +2098,10 @@ export function isSessionReplayActive() {
 }
 /**
  * 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() {
     const state = getState();