@scalebun-release/web 2.2.2

package/dist/features/replay/lifecycle/recorder.js

@@ -0,0 +1,644 @@
+import { uuid, now } from '../../../core/index.js';
+import { PersistentBuffer } from '../../../storage/idb.js';
+import { capBytes, PERSIST_MAX_BYTES } from '../../../core/prune.js';
+import { approxBytes } from './segmentBuffer.js';
+import { DeltaBatcher } from './deltaBatcher.js';
+import { AdaptiveController, adapt } from './adaptive.js';
+import { redactFrame } from './pii.js';
+import { shouldDeferHeavyEgress } from './deviceSignals.js';
+import { getTabId, getViewId, getRoute } from './viewContext.js';
+import { reserveSeq, ensureSeqAtLeast } from '../../session/sessionStore.js';
+const SEGMENT_MAX_FRAMES = 120;
+const SEGMENT_MAX_BYTES = 200000; // seal a segment at ~200KB even if it hasn't hit the frame cap
+const MAX_SEGMENTS = 8; // ring depth (count guard; the byte budget is the real bound)
+/**
+ * Pre-roll cap, DERIVED from the budget the pre-roll has to survive rather than picked.
+ *
+ * It was a standalone 3MB against `PERSIST_MAX_BYTES` of 2MB, so a pre-roll allowed to fill
+ * completely was 1MB over the limit by construction and could never be persisted whole — it was
+ * guaranteed to be trimmed on its way to IndexedDB. Two constants in two files that have to relate
+ * and didn't. Deriving it means raising the persist budget raises this one with it.
+ *
+ * This is an upper bound, not a guarantee: the persisted queue also carries events, perf and network
+ * items, so a full pre-roll can still be trimmed to make room — which is now a graceful shed of the
+ * oldest segments rather than the loss of every frame.
+ */
+const MAX_BUFFER_BYTES = PERSIST_MAX_BYTES;
+const KEYFRAME_INTERVAL_MS = 30000; // periodic checkpoint cadence (also drains the hidden-tab pile)
+// B1: even on a genuinely idle page, force a keyframe at least this often so a long session keeps a
+// recent checkpoint (durable crash-mirror freshness + backend retention windows stay seekable).
+const MAX_IDLE_KEYFRAME_MS = 5 * 60000;
+// Packaging window for the DOM lane (mutations + CSSOM + iframe ops, via DeltaBatcher): producers keep
+// their capture cadence, frames ship at most every this-many ms. Caps the worst case (a 60fps DOM
+// animation) at ~10 frames/sec instead of 60 — no ops are lost, only the envelopes.
+const DELTA_BATCH_MS = 100;
+// Move-only interaction batches pool this long before shipping (clicks flush them instantly — see
+// InteractionRecorder.queue). ~3 cursor frames/sec instead of 10 during continuous movement.
+const MOVE_FLUSH_MS = 300;
+/** Attribute a frame to the producer lane it came from (for the stats counters). */
+function classifyFrame(frame) {
+    if (frame.frameType === 'keyframe')
+        return 'keyframe';
+    const muts = frame.mutations;
+    if (muts?.length)
+        return muts.every((m) => m.op === 'canvas') ? 'canvas' : 'mutation';
+    const events = frame.events;
+    if (events?.length) {
+        if (events.some((e) => e.k === 'click' || e.k === 'deadclick' || e.k === 'input'))
+            return 'interaction';
+        if (events.some((e) => e.k === 'scroll' || e.k === 'viewport'))
+            return 'scroll';
+        return 'move';
+    }
+    return 'other';
+}
+export async function createRecorder(ctx, decision) {
+    const c = new RecorderController(ctx, decision);
+    await c.init();
+    return c;
+}
+export class RecorderController {
+    /**
+     * Take the next sequence number and persist the advance (survives reload / shared tabs).
+     *
+     * CALLED FROM push(), AFTER every decision that can discard the frame — never from the builders.
+     *
+     * It used to be called while constructing the frame object, which push() could then drop outright:
+     * adaptive quality shedding a cursor-move frame, or SegmentBuffer refusing a delta that has no open
+     * segment. The number was never reused, so a deliberate shed and a frame genuinely lost in transit
+     * left the SAME hole in the stored sequence. That made our own reliability figure unprovable —
+     * production measures 1.16% of numbered frames missing, and nobody could say how much of it was
+     * intentional. Assigning at emission makes a gap mean exactly one thing: a frame that left the
+     * recorder and did not arrive.
+     */
+    nextSeq() {
+        const n = reserveSeq(1);
+        this.seq = n + 1;
+        return n;
+    }
+    constructor(ctx, decision) {
+        this.ctx = ctx;
+        this.decision = decision;
+        this.active = false;
+        /**
+         * Replay frame sequence, PER SESSION rather than per document.
+         *
+         * A session now survives a refresh (features/session/sessionStore), and the backend both orders
+         * frames by this number and resolves a keyframe's deltas as the frames in [seq, nextSeq). A
+         * counter that restarted at 0 on each page load would therefore emit a second frame 0, 1, 2…
+         * that sorts BEFORE the first load's later frames and scrambles the replay. Seed from the store
+         * so a resumed session keeps counting.
+         */
+        this.seq = reserveSeq(0);
+        this.keyframeId = '';
+        this.checkpointing = false;
+        // B1: set by any delta pushed since the last keyframe; the periodic 'time' checkpoint skips its
+        // redundant full re-snapshot when a page is genuinely idle (no deltas). `lastKeyframeAt` bounds that
+        // skip via MAX_IDLE_KEYFRAME_MS so a keyframe still lands eventually.
+        this.dirtySinceKeyframe = false;
+        this.lastKeyframeAt = 0;
+        // R0.6 — streaming delta-chain budget. The BUFFERED path bounds a chain via SegmentBuffer.currentBytes
+        // in push(); the STREAMING path emits deltas directly with no buffer, so without this a busy live page
+        // builds an unbounded delta chain between the 30s time-keyframes → unbounded seek/reconstruction cost.
+        // Charge each streamed delta with the SAME approxBytes measure and force a keyframe at the same budget;
+        // reset when a keyframe opens a fresh chain (in checkpoint()).
+        this.streamChainBytes = 0;
+        this.streamChainFrames = 0;
+        /** Last `egressDropped` reading — a RISE means the pipeline shed a chain (see push()). */
+        this.lastShed = 0;
+        this.pendingEncodes = new Set();
+        this.shed = 0; // delta frames dropped by adaptive quality (for stats in M7)
+        this.producerCounts = {};
+        this.redactPII = false; // strict privacy on UNMASKED replay (M8)
+        this.paused = false; // runtime pause() — capture disarmed, session/buffer retained
+        this.streaming = decision.streamFromStart; // 'sampled'/'always' → emit live from frame 0
+        // P3/D1 — cost-aware egress: on Save-Data / slow link / ultra-low-memory, DON'T stream live; keep
+        // recording into the buffered pre-roll (on-error/crash replay preserved), upload only on signal.
+        if (this.streaming && shouldDeferHeavyEgress()) {
+            this.streaming = false;
+            ctx.log('[replay] save-data/slow → buffered');
+        }
+        this.persistBuffer = !!ctx.replaySampling?.persistBuffer && !this.streaming; // only the ARMED pre-roll
+        this.maskText = ctx.maskReplayText ?? false; // default: show text (config/setPrivacy() can mask); inputs always masked
+    }
+    get isActive() {
+        return this.active;
+    }
+    /** Live diagnostics. */
+    stats() {
+        const b = this.segBuf;
+        return {
+            recording: this.active && !this.paused,
+            paused: this.paused,
+            streaming: this.streaming,
+            sampleReason: this.decision.reason,
+            sampleBucket: this.decision.bucket,
+            qualityLevel: this.adaptive?.level ?? 0,
+            segments: b?.segmentCount ?? 0,
+            frames: b?.frameCount ?? 0,
+            captured: !!this.keyframeId,
+            bufferBytes: b?.totalBytes ?? 0,
+            droppedSegments: b?.dropped ?? 0,
+            shedFrames: this.shed,
+            producers: Object.fromEntries(Object.entries(this.producerCounts).map(([k, v]) => [k, { ...v }])),
+        };
+    }
+    /** Force a re-keyframe (e.g. ScaleBun.replay.checkpoint() before a risky flow). */
+    forceCheckpoint(reason) {
+        this.checkpoint(reason);
+    }
+    /** One-time bring-up: segment buffer + crash-survival mirror + encoder (survive pause/resume), then
+     *  ARM the capture pipeline (observers + first keyframe). The re-armable part lives in `arm()`. */
+    async init() {
+        const [{ ReplayEncoder }, { SegmentBuffer }] = await Promise.all([
+            import('../engine/replayWorker.js'),
+            import('./segmentBuffer.js'),
+        ]);
+        this.segBuf = new SegmentBuffer(MAX_SEGMENTS, MAX_BUFFER_BYTES);
+        // M6 crash-survival (opt-in): recover a PRIOR session's pre-roll if it was retained (i.e. the
+        // last load didn't clean-close → likely a crash). Emit it as a standalone segment, then continue
+        // seq past it so the new session's frames never collide. Guards clear it on a clean close.
+        if (this.persistBuffer) {
+            this.replayStore = new PersistentBuffer('pending-replay');
+            await this.recoverPriorPreRoll();
+            this.installPersistGuards();
+        }
+        // Encoder is one-time (survives pause/resume) — arm()/checkpoints reuse it for gzip-in-place.
+        this.encoder = new ReplayEncoder();
+        this.disposeEncoder = () => this.encoder?.dispose();
+        await this.arm();
+        // Capture-on-signal flush is one-time (an error while paused still drains an empty buffer safely).
+        this.unsubSignal = this.ctx.onSignal(() => this.flush());
+        this.active = true;
+    }
+    /**
+     * ARM the capture pipeline: fresh NodeRegistry + a keyframe of the CURRENT DOM, then wire + observe
+     * the mutation/interaction/CSSOM/iframe/canvas recorders, adaptive quality, and checkpoint cadence.
+     * Idempotent-safe to call after `disarm()` — this is exactly what resume()/setPrivacy() do, and why a
+     * resume takes a fresh keyframe (the DOM changed while paused, so old deltas can't rebase).
+     */
+    async arm() {
+        if (typeof document === 'undefined')
+            return;
+        const ctx = this.ctx;
+        const [{ NodeRegistry }, { takeSnapshot }, { MutationRecorder }, { InteractionRecorder }, { CssomRecorder }, { IframeManager },] = await Promise.all([
+            import('../engine/nodeRegistry.js'),
+            import('../engine/snapshot.js'),
+            import('../engine/mutations.js'),
+            import('../engine/interactions.js'),
+            import('../engine/cssom.js'),
+            // R3: folded into the same Promise.all. As a separate `await` it added a round trip to
+            // time-to-first-keyframe for no reason — nothing above it depends on the iframe manager.
+            import('../engine/iframe.js'),
+        ]);
+        // Baseline the shed counter BEFORE the first frame: drops from before recording started (a
+        // consent-gated emit, a previous feature's overflow) are not this chain's problem, and counting
+        // them would fire a redundant checkpoint against the keyframe taken moments earlier.
+        this.lastShed = ctx.egressDropped?.() ?? 0;
+        const reg = new NodeRegistry();
+        // maskAllText defaults FALSE (text shown); host masks via privacy.maskReplayText or setPrivacy(). Inputs always masked.
+        // Inputs stay masked. Held on `this.maskText` so setPrivacy() can flip it + re-arm.
+        const snapOpts = { maskAllText: this.maskText, maskAllInputs: ctx.maskInputs ?? true, maskSelectors: ctx.maskSelectors };
+        // M8: strict-mode PII redaction only matters when text is UNMASKED (masked text has no PII to find).
+        this.redactPII = ctx.replaySampling?.privacyLevel === 'strict' && !snapOpts.maskAllText;
+        this.reg = reg;
+        this.snapOpts = snapOpts;
+        this.takeSnapshotFn = takeSnapshot;
+        const snapshot = takeSnapshot(document, reg, snapOpts);
+        this.keyframeId = `f_${uuid()}`;
+        // Keyframe ships RAW immediately (always valid wire) and is upgraded to gzip in-place as the worker
+        // finishes — encoding stays OFF the critical path; a race with egress just sends the raw payload.
+        const keyframe = {
+            kind: 'frame',
+            renderer: 'dom',
+            frameType: 'keyframe',
+            frameId: this.keyframeId,
+            snapshot,
+            viewport: viewport(),
+            href: href(),
+            tabId: getTabId(),
+            viewId: getViewId(),
+            route: getRoute(),
+            masked: true,
+            timestamp: now(),
+        };
+        this.push(keyframe);
+        this.compressInPlace(keyframe, snapshot);
+        this.persistPreRoll(); // make the very first pre-roll durable too (before the 1st checkpoint)
+        this.dirtySinceKeyframe = false; // B1: fresh keyframe = clean baseline
+        this.lastKeyframeAt = now();
+        // The DOM lane's single packaging point: mutation/CSSOM/iframe producers keep their capture
+        // cadence but append ops HERE; one delta frame ships per DELTA_BATCH_MS window (ops in arrival
+        // order, so DOM and CSSOM changes from the same tick share one envelope).
+        const batcher = new DeltaBatcher(DELTA_BATCH_MS, (mutations) => this.push(this.delta({ mutations })));
+        this.deltaBatcher = batcher;
+        const interactions = new InteractionRecorder(reg, (events) => {
+            this.push(this.delta({ events }));
+        }, {
+            maskText: !!snapOpts.maskAllText, // click labels omit page text when replay text is masked
+            moveFlushMs: MOVE_FLUSH_MS,
+            // A click frame flushes synchronously; drain the DOM lane first so a click on a just-added
+            // node never ships before the mutation that adds it.
+            beforeImmediateFlush: () => batcher.flush(),
+        });
+        const recorder = new MutationRecorder(reg, (mutations) => {
+            interactions.notifyDomActivity(); // a real DOM change → not a dead click (never delayed by batching)
+            batcher.append(mutations);
+        }, snapOpts);
+        const cssom = new CssomRecorder(reg, (mutations) => {
+            interactions.notifyDomActivity(); // a style change is a real visual effect, not a dead click
+            batcher.append(mutations);
+        });
+        const iframes = new IframeManager(reg, (mutations) => {
+            interactions.notifyDomActivity();
+            batcher.append(mutations);
+        }, snapOpts, {
+            onFrame: (doc, getOffset) => interactions.observeFrame(doc, getOffset),
+            onUnframe: (doc) => interactions.unobserveFrame(doc),
+            frameOrigins: ctx.replayFrameOrigins ?? [],
+        });
+        if ((ctx.replayFrameOrigins ?? []).length) {
+            void import('../engine/crossOrigin.js').then(({ installChildSatellite }) => {
+                this.childSatelliteStop = installChildSatellite(ctx.replayFrameOrigins ?? [], snapOpts);
+            });
+        }
+        this.mutationRec = recorder;
+        this.cssomRec = cssom;
+        recorder.observe(document.documentElement);
+        interactions.observe();
+        cssom.install();
+        iframes.start();
+        this.disconnectRecorder = () => recorder.disconnect();
+        this.disconnectInteractions = () => interactions.disconnect();
+        this.disconnectCssom = () => cssom.disconnect();
+        this.disconnectIframes = () => iframes.disconnect();
+        if (ctx.replayCanvas) {
+            const { CanvasRecorder } = await import('../engine/canvas.js');
+            const canvas = new CanvasRecorder(reg, (mutations) => {
+                interactions.notifyDomActivity();
+                this.push(this.delta({ mutations }));
+            }, (...a) => ctx.log(...a));
+            canvas.start();
+            this.disconnectCanvas = () => canvas.disconnect();
+        }
+        // Adaptive quality — shed canvas→mousemove→scroll (never mutations/CSSOM/input) under CPU or
+        // egress pressure; recovers automatically when pressure clears.
+        this.adaptive = new AdaptiveController(ctx.egressPending);
+        // Checkpoint cadence: time / visibility-return / SPA URL change / UI state change → re-keyframe.
+        const { installCadence } = await import('./cadence.js');
+        /**
+         * The state reader is NOT passed here — installCadence takes it from the shared cell in core,
+         * which the journey feature registers at init.
+         *
+         * That indirection is a measured size decision, not a style one. Every direct import path cost
+         * eager bundle against 97 B of headroom: 56 B for a dynamic import here, 59 B for a static one
+         * inside cadence.ts, because naming journey/uiState from the lazy replay graph makes it shared
+         * and the bundler hoists it into core. Registering through core — already imported by both
+         * sides — costs the cell alone and leaves 45 B. See core/uiStateReader.
+         */
+        this.disconnectCadence = installCadence({
+            keyframeIntervalMs: KEYFRAME_INTERVAL_MS,
+            onCheckpoint: (reason) => this.checkpoint(reason),
+        });
+    }
+    /** DISARM the capture pipeline: stop every observer + adaptive + cadence and drop the capture-scoped
+     *  state, WITHOUT touching the segment buffer / crash-mirror / encoder / session (those survive a
+     *  pause). The inverse of `arm()`; shared by pause() and teardown(). Idempotent. */
+    disarm() {
+        // Drain captured-but-unpackaged work BEFORE disconnecting (disconnect drops producer queues):
+        // pending ops become a final delta frame, so a pause/teardown never loses observed changes.
+        try {
+            this.mutationRec?.flush();
+            this.cssomRec?.flush();
+            this.deltaBatcher?.dispose();
+        }
+        catch {
+            /* best-effort tail drain */
+        }
+        this.deltaBatcher = undefined;
+        this.disconnectRecorder?.();
+        this.disconnectInteractions?.();
+        this.disconnectCssom?.();
+        this.disconnectCanvas?.();
+        this.disconnectIframes?.();
+        this.childSatelliteStop?.();
+        this.disconnectCadence?.();
+        this.adaptive?.dispose();
+        this.disconnectRecorder = undefined;
+        this.disconnectInteractions = undefined;
+        this.disconnectCssom = undefined;
+        this.disconnectCanvas = undefined;
+        this.disconnectIframes = undefined;
+        this.childSatelliteStop = undefined;
+        this.disconnectCadence = undefined;
+        this.adaptive = undefined;
+        // Null the capture-scoped refs so a stray checkpoint()/forceCheckpoint() no-ops while paused.
+        this.reg = undefined;
+        this.mutationRec = undefined;
+        this.cssomRec = undefined;
+        this.takeSnapshotFn = undefined;
+        this.snapOpts = undefined;
+    }
+    // ── Runtime control (ScaleBun.replay.pause/start/setPrivacy) ────────────────
+    /** Pause capture (stop observers) while keeping the session + buffered pre-roll intact. No-op when
+     *  not recording or already paused. */
+    pause() {
+        if (!this.active || this.paused)
+            return;
+        this.disarm();
+        this.paused = true;
+        this.ctx.log('[replay] paused');
+    }
+    /** Resume capture after pause(): re-arm with a FRESH keyframe of the current DOM (the DOM changed
+     *  while paused, so a new base is required). No-op when not recording or not paused. */
+    resume() {
+        if (!this.active || !this.paused)
+            return;
+        this.paused = false;
+        void this.arm().then(() => this.ctx.log('[replay] resumed'));
+    }
+    /** Change replay masking at runtime (e.g. entering a sensitive screen). Re-arms with a fresh keyframe
+     *  so the new masking takes effect from here on; the already-captured pre-roll keeps its old masking. */
+    setPrivacy(policy) {
+        if (typeof policy?.maskAllText !== 'boolean' || policy.maskAllText === this.maskText)
+            return;
+        this.maskText = policy.maskAllText;
+        if (this.active && !this.paused) {
+            this.disarm();
+            void this.arm();
+        }
+        this.ctx.log('[replay] privacy set: maskAllText=' + this.maskText);
+    }
+    /** Build a delta frame against the current keyframe. `seq` is assigned in push(), not here — see
+     *  the note on nextSeq(). */
+    delta(payload) {
+        return {
+            kind: 'frame',
+            renderer: 'dom',
+            frameType: 'delta',
+            frameId: `f_${uuid()}`,
+            baseFrameId: this.keyframeId,
+            ...payload,
+            tabId: getTabId(),
+            viewId: getViewId(),
+            route: getRoute(),
+            masked: true,
+            timestamp: now(),
+        };
+    }
+    push(frame) {
+        var _a;
+        // B1: any delta (even one later shed by adaptive quality) means the page changed since the last
+        // keyframe → the next 'time' checkpoint must actually re-snapshot.
+        if (frame.frameType === 'delta')
+            this.dirtySinceKeyframe = true;
+        // M8: scrub PII before the frame is buffered/encoded (keyframe snapshot + delta mutation values).
+        if (this.redactPII)
+            redactFrame(frame);
+        // Adaptive quality: under pressure, shed low-priority deltas (canvas/move/scroll). Keyframes and
+        // mutation/CSSOM/input deltas always pass — the correctness + signal floor.
+        if (frame.frameType === 'delta' && this.adaptive && this.adaptive.level > 0) {
+            const adapted = adapt(frame, this.adaptive.level);
+            if (!adapted) {
+                this.shed++;
+                return;
+            }
+            frame = adapted;
+        }
+        /**
+         * THE SEQUENCE IS TAKEN HERE, past every decision that can discard this frame.
+         *
+         * A shed above returns without consuming a number, so the stored sequence has a hole only when a
+         * frame actually left the recorder and failed to arrive. That is what makes the gap measurable:
+         * before this, an adaptive shed and a lost frame were indistinguishable in the database.
+         */
+        frame.seq = this.nextSeq();
+        // Per-producer attribution of everything that actually ships/buffers (post-shed) — the
+        // measurement the flush-policy tuning is judged against.
+        const producer = classifyFrame(frame);
+        const pc = ((_a = this.producerCounts)[producer] ?? (_a[producer] = { frames: 0, bytes: 0 }));
+        pc.frames++;
+        pc.bytes += approxBytes(frame);
+        if (this.streaming) {
+            this.ctx.emit(frame);
+            /**
+             * A SHED IS A CHAIN BREAK — restart the chain here, not at the next scheduled checkpoint.
+             *
+             * `Pipeline.evictChain` drops the oldest frame chain whole when the egress queue is full. Every
+             * delta emitted after that still carries `baseFrameId` of a keyframe the server will never
+             * receive, so without this the shed keeps costing frames until the next 30-second checkpoint —
+             * which is precisely how 1.16% frame loss came to break 13.5% of sessions in production.
+             * Re-keyframing on the rise bounds the damage to the frames already in flight.
+             *
+             * Read here rather than on a timer because the counter only moves inside `emit`, so this is the
+             * first moment it can have changed; the cost is one function call against the `approxBytes`
+             * walk this method already does per frame. Buffered (pre-roll) capture never reaches the queue,
+             * so it cannot shed and does not need the check.
+             */
+            const shed = this.ctx.egressDropped?.() ?? 0;
+            if (shed > this.lastShed) {
+                this.lastShed = shed;
+                this.checkpoint('shed');
+            }
+            // R0.6: bound the LIVE delta chain the same way the buffered path bounds an open segment — force a
+            // re-keyframe once the chain crosses the segment budget so seek/reconstruction cost stays O(segment).
+            if (frame.frameType === 'delta') {
+                this.streamChainBytes += approxBytes(frame);
+                this.streamChainFrames++;
+                if (!this.checkpointing &&
+                    (this.streamChainFrames >= SEGMENT_MAX_FRAMES || this.streamChainBytes >= SEGMENT_MAX_BYTES)) {
+                    this.checkpoint(this.streamChainBytes >= SEGMENT_MAX_BYTES ? 'segment-bytes' : 'segment-frames');
+                }
+            }
+            return;
+        }
+        const buf = this.segBuf;
+        if (!buf)
+            return;
+        if (frame.frameType === 'keyframe')
+            buf.openSegment(frame);
+        else
+            buf.append(frame);
+        // Once the current segment fills, re-keyframe so the ring evicts whole OLD segments (consistent)
+        // instead of dropping an interior delta. Guarded against re-entrancy from checkpoint()'s drain.
+        if (!this.checkpointing &&
+            frame.frameType === 'delta' &&
+            (buf.currentFrameCount >= SEGMENT_MAX_FRAMES || buf.currentBytes >= SEGMENT_MAX_BYTES)) {
+            this.checkpoint(buf.currentBytes >= SEGMENT_MAX_BYTES ? 'segment-bytes' : 'segment-frames');
+        }
+    }
+    /** Re-keyframe: drain queued records onto the OLD keyframe, snapshot the live DOM, open a new
+     *  segment with the keyframe (raw → gzip in-place). Subsequent deltas auto-rebase via `keyframeId`. */
+    checkpoint(reason) {
+        if (this.checkpointing || !this.reg || !this.takeSnapshotFn || typeof document === 'undefined')
+            return;
+        this.checkpointing = true;
+        try {
+            // Drain producers + the DOM batcher FIRST, for two reasons: pending ops must ship as deltas
+            // against the OLD keyframe (they describe changes the new snapshot will already contain), and
+            // the idle check below is only honest after the drain — a hidden-tab pile that hasn't been
+            // packaged yet still counts as "the page changed".
+            this.mutationRec?.flush();
+            this.cssomRec?.flush();
+            this.deltaBatcher?.flush();
+            // B1: the periodic 'time' checkpoint — and a tab-return 'visible' — are no-ops on a genuinely
+            // idle page: skip the redundant full re-snapshot when nothing changed since the last keyframe
+            // (bounded by MAX_IDLE_KEYFRAME_MS). Alt-tabbing used to cost a full DOM snapshot per return.
+            // url / segment-* / manual always re-keyframe.
+            if ((reason === 'time' || reason === 'visible') &&
+                !this.dirtySinceKeyframe &&
+                now() - this.lastKeyframeAt < MAX_IDLE_KEYFRAME_MS) {
+                return;
+            }
+            const snapshot = this.takeSnapshotFn(document, this.reg, this.snapOpts);
+            const id = `f_${uuid()}`;
+            this.keyframeId = id;
+            this.streamChainBytes = 0; // R0.6: a fresh keyframe starts a fresh chain
+            this.streamChainFrames = 0;
+            const keyframe = {
+                kind: 'frame',
+                renderer: 'dom',
+                frameType: 'keyframe',
+                frameId: id,
+                snapshot,
+                viewport: viewport(),
+                href: href(),
+                masked: true,
+                trigger: reason,
+                timestamp: now(),
+            };
+            this.push(keyframe);
+            this.compressInPlace(keyframe, snapshot);
+            this.persistPreRoll(); // refresh the durable crash-mirror at each checkpoint
+            this.dirtySinceKeyframe = false; // B1: this keyframe is the new clean baseline
+            this.lastKeyframeAt = now();
+        }
+        finally {
+            this.checkpointing = false;
+        }
+    }
+    // ── M6 crash-survivable pre-roll (opt-in) ──────────────────────────────────
+    async recoverPriorPreRoll() {
+        if (!this.replayStore)
+            return;
+        try {
+            const prev = (await this.replayStore.load());
+            if (Array.isArray(prev) && prev.length) {
+                let maxSeq = 0;
+                for (const f of prev) {
+                    this.ctx.emit(f); // standalone segment — the player resets per keyframe
+                    maxSeq = Math.max(maxSeq, f.seq ?? 0);
+                }
+                // Raise the SESSION's floor, not just this instance's mirror: the counter is persisted now,
+                // so a local assignment would be overwritten by the next reserve() and the recovered frames'
+                // numbers would be handed out a second time.
+                this.seq = ensureSeqAtLeast(maxSeq + 1);
+                await this.replayStore.clear();
+            }
+        }
+        catch {
+            /* ignore — recovery is best-effort */
+        }
+    }
+    /** Mirror the current pre-roll to IDB (byte-capped). A crash retains it; a clean close clears it.
+     *  Every item here IS a frame, so `isHeavy` is constant — the predicates exist to tell capBytes
+     *  which of them is a base, so a trimmed pre-roll starts at a keyframe instead of at deltas that
+     *  reconstruct against a snapshot no longer present. */
+    persistPreRoll() {
+        if (!this.replayStore || !this.segBuf || this.streaming)
+            return;
+        void this.replayStore.save(capBytes(this.segBuf.drainFrames(), () => true, (f) => f.frameType === 'keyframe'));
+    }
+    installPersistGuards() {
+        if (typeof window === 'undefined')
+            return;
+        // Clean close → discard the pre-roll (onError: no error fired). A real crash skips pagehide, so
+        // the last-checkpoint mirror survives for recovery on the next load.
+        this.onPageHide = () => void this.replayStore?.clear();
+        window.addEventListener('pagehide', this.onPageHide);
+        // C1: mobile Safari frequently kills a BACKGROUNDED tab without ever firing pagehide. Refresh the
+        // durable pre-roll mirror at the last reliable lifecycle point (visibility→hidden) so a later OS
+        // kill recovers the most recent frames. This PERSISTS (never clears) — the tab may still resume;
+        // a genuine clean close still clears via pagehide.
+        this.onVisHidden = () => {
+            if (typeof document !== 'undefined' && document.visibilityState === 'hidden')
+                this.persistPreRoll();
+        };
+        if (typeof document !== 'undefined')
+            document.addEventListener('visibilitychange', this.onVisHidden);
+    }
+    /**
+     * Upgrade a keyframe's already-emitted RAW snapshot to gzip in-place as the worker finishes. The
+     * frame object is shared with the SegmentBuffer / pipeline queue, so filling `.snapshot` swaps the
+     * payload before egress IF the encode wins the race; otherwise the valid raw payload ships. No
+     * await, no ordering hazard — correctness over a few uncompressed bytes on a lost race.
+     */
+    compressInPlace(frame, snapshot) {
+        const enc = this.encoder;
+        if (!enc)
+            return;
+        const p = enc
+            .encodeSnapshot(snapshot)
+            .then((out) => {
+            frame.snapshot = out;
+        })
+            .catch(() => {
+            /* keep the raw snapshot on failure */
+        })
+            .finally(() => {
+            this.pendingEncodes.delete(p);
+        });
+        this.pendingEncodes.add(p);
+    }
+    /** Capture-on-signal: drain pending records, flush the pre-roll segments, then stream live. */
+    flush() {
+        this.mutationRec?.flush();
+        this.cssomRec?.flush();
+        this.deltaBatcher?.flush(); // package the drained ops before the pre-roll ships
+        if (this.segBuf)
+            for (const f of this.segBuf.drainFrames())
+                this.ctx.emit(f);
+        this.segBuf?.clear();
+        this.streaming = true;
+        void this.replayStore?.clear(); // pre-roll now egressed via the durable pipeline → drop the mirror
+    }
+    teardown() {
+        this.disarm(); // stop every observer + adaptive + cadence + null the capture-scoped refs
+        // One-time teardown of the state that survives pause():
+        this.disposeEncoder?.();
+        if (this.onPageHide && typeof window !== 'undefined')
+            window.removeEventListener('pagehide', this.onPageHide);
+        this.onPageHide = undefined;
+        if (this.onVisHidden && typeof document !== 'undefined')
+            document.removeEventListener('visibilitychange', this.onVisHidden);
+        this.onVisHidden = undefined;
+        void this.replayStore?.clear(); // clean teardown → discard the pre-roll mirror
+        this.replayStore = undefined;
+        this.unsubSignal?.();
+        this.segBuf?.clear();
+        this.segBuf = undefined;
+        this.encoder = undefined;
+        this.pendingEncodes.clear(); // in-flight encodes resolve harmlessly onto GC'd frames
+        this.streaming = false;
+        this.checkpointing = false;
+        this.paused = false;
+        this.active = false;
+    }
+}
+function viewport() {
+    try {
+        return typeof window !== 'undefined' ? { width: window.innerWidth, height: window.innerHeight } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function href() {
+    try {
+        return typeof location !== 'undefined' ? location.href : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=recorder.js.map