@agent-native/core 0.98.4 → 0.98.5

package/dist/client/session-replay.js

@@ -1,3 +1,4 @@
+import { SESSION_REPLAY_IFRAME_ATTRIBUTE, SESSION_REPLAY_IFRAME_PROBE, SESSION_REPLAY_IFRAME_START, SESSION_REPLAY_IFRAME_STOP, } from "../session-replay-iframe-protocol.js";
 import { getOrCreateAnalyticsAnonymousId, getOrCreateAnalyticsSessionId, } from "./analytics-session.js";
 import { scrubUrl } from "./url-scrub.js";
 const DEFAULT_REPLAY_PATH = "/api/analytics/replay";
@@ -16,7 +17,9 @@ const DEFAULT_EVENT_SAMPLING = {
 };
 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]",
@@ -36,11 +39,28 @@ 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 = {
+    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";
@@ -109,9 +129,13 @@ function getState() {
             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,
@@ -124,6 +148,10 @@ function getState() {
     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
@@ -522,13 +550,17 @@ function normalizeOptions(options) {
         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,
@@ -539,6 +571,11 @@ function normalizeOptions(options) {
         shouldStart: options.shouldStart,
     };
 }
+function mergeReplayBlockSelector(blockSelector) {
+    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
@@ -753,18 +790,25 @@ function replayEventTimestampMs(event) {
 function enqueueReplayEvent(state, event) {
     if (!state.options)
         return;
+    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) {
         void flushSessionReplay("max-bytes");
     }
     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);
@@ -989,6 +1033,24 @@ function isFinalFlushReason(reason) {
         "max-duration",
     ].includes(reason);
 }
+function flushReasonPriority(reason) {
+    // 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, requested) {
+    if (!current)
+        return requested;
+    return flushReasonPriority(requested) > flushReasonPriority(current)
+        ? requested
+        : current;
+}
 function shouldReserveSequenceBeforeKeepalive(reason) {
     return (reason === "pagehide" ||
         reason === "beforeunload" ||
@@ -1023,7 +1085,90 @@ function flushQueuedReplayIfNeeded(state) {
     void flushSessionReplay(reason);
 }
 function queuedReplayBytes(events) {
-    return events.reduce((total, event) => total + event.json.length, 0);
+    return events.reduce((total, event) => total + queuedReplayEventBytes(event), 0);
+}
+function replaySerializedBytes(value) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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);
+            // 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) {
+    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(state, events) {
     state.retryBatches.unshift(events);
@@ -1044,10 +1189,17 @@ function rollbackReplaySequenceReservation(state, payload) {
 }
 export async function flushSessionReplay(reason = "manual") {
     const state = getState();
-    if (!state.options || !hasPendingReplayBatch(state) || state.flushing)
+    if (!state.options)
         return;
-    const events = state.retryBatches.shift() ?? state.queue.splice(0);
-    state.queuedBytes = queuedReplayBytes(state.queue);
+    if (state.flushing) {
+        state.pendingFlushReason = mergePendingFlushReason(state.pendingFlushReason, reason);
+        return new Promise((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);
@@ -1056,6 +1208,8 @@ export async function flushSessionReplay(reason = "manual") {
     state.flushing = true;
     let uploaded = false;
     let reservedSequence = false;
+    let splitRejectedBatch = false;
+    let droppedOversizedBatch = false;
     let definitiveClientErrorStatus = null;
     try {
         await sendReplayUpload(state.options, payload.body, {
@@ -1078,9 +1232,32 @@ export async function flushSessionReplay(reason = "manual") {
         // 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);
-        if (isDefinitiveClientError) {
+            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
@@ -1100,7 +1277,13 @@ export async function flushSessionReplay(reason = "manual") {
         const previousInternal = replayCaptureInternal;
         replayCaptureInternal = true;
         try {
-            if (isDefinitiveClientError) {
+            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.status})`, error);
             }
             else {
@@ -1114,8 +1297,36 @@ export async function flushSessionReplay(reason = "manual") {
     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) {
@@ -1155,6 +1366,8 @@ export async function flushSessionReplay(reason = "manual") {
             // 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
@@ -1239,6 +1452,80 @@ function installLifecycleListeners(state) {
         state.removeLifecycleListeners = null;
     };
 }
+function markedSessionReplayIframes() {
+    if (typeof document.querySelectorAll !== "function")
+        return [];
+    return Array.from(document.querySelectorAll(`iframe[${SESSION_REPLAY_IFRAME_ATTRIBUTE}]`));
+}
+function markedSessionReplayIframeForSource(source) {
+    if (!source)
+        return null;
+    return (markedSessionReplayIframes().find((iframe) => iframe.contentWindow === source) ?? null);
+}
+function sessionReplayIframePrivacyOptions(options) {
+    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, message) {
+    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, options) {
+    if (!options.recordCrossOriginIframes || state.restoreIframeBridge)
+        return;
+    const startMessage = {
+        type: SESSION_REPLAY_IFRAME_START,
+        options: sessionReplayIframePrivacyOptions(options),
+    };
+    const stopMessage = {
+        type: SESSION_REPLAY_IFRAME_STOP,
+    };
+    const sendStart = (iframe) => postSessionReplayIframeMessage(iframe, startMessage);
+    const onMessage = (event) => {
+        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, maxLength) {
     return value.length > maxLength ? value.slice(0, maxLength) : value;
 }
@@ -1952,6 +2239,10 @@ async function startSessionReplayRecorder(state, normalized, sessionId, sampled,
     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;
@@ -1975,22 +2266,7 @@ async function startSessionReplayRecorder(state, normalized, sessionId, sampled,
             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;
@@ -2012,6 +2288,7 @@ async function startSessionReplayRecorder(state, normalized, sessionId, sampled,
         state.maxDurationTimer = window.setTimeout(() => stopSessionReplay("max-duration"), normalized.maxDurationMs);
         installUrlMonitor(state);
         installLifecycleListeners(state);
+        installSessionReplayIframeBridge(state, normalized);
         state.addCustomEvent =
             typeof rrweb.record.addCustomEvent === "function"
                 ? rrweb.record.addCustomEvent
@@ -2032,6 +2309,7 @@ async function startSessionReplayRecorder(state, normalized, sessionId, sampled,
             // best-effort interceptor teardown
         }
         state.restoreCaptures = null;
+        state.restoreIframeBridge?.();
         state.addCustomEvent = null;
         state.active = false;
         state.options = null;
@@ -2062,6 +2340,7 @@ export async function stopSessionReplay(reason = "manual") {
         // best-effort interceptor teardown
     }
     state.restoreCaptures = null;
+    state.restoreIframeBridge?.();
     state.active = false;
     state.addCustomEvent = null;
     try {