@scalebun/web 1.0.0

package/dist/features/replay/lifecycle/recorder.d.ts

@@ -0,0 +1,129 @@
+/**
+ * RecorderController — the entire DOM-replay recording lifecycle, lazy-loaded by the thin
+ * `ReplayFeature` shell only for a SAMPLED session. Keeping this out of the eager feature class
+ * means none of the orchestration (segments, checkpoints, cadence, wiring) weighs down the core
+ * bundle — the shell in core is ~a dozen lines.
+ *
+ * Owns: keyframe snapshot (worker-compressed) → mutation/CSSOM/interaction/iframe/canvas deltas →
+ * the SegmentBuffer pre-roll → capture-on-signal flush → re-keyframe checkpoints (segment-full /
+ * time / visibility / URL). In 'sampled'/'always' mode it streams from the first frame instead.
+ */
+import type { FeatureContext } from '@scalebun/sdk-contracts';
+import type { SampleDecision } from './sampling';
+/** Diagnostics surfaced via ScaleBun.replay.stats() + the Dev Panel. */
+export interface ReplayStats {
+    recording: boolean;
+    paused: boolean;
+    streaming: boolean;
+    sampleReason: string;
+    sampleBucket: number;
+    qualityLevel: number;
+    segments: number;
+    frames: number;
+    bufferBytes: number;
+    droppedSegments: number;
+    shedFrames: number;
+}
+export declare function createRecorder(ctx: FeatureContext, decision: SampleDecision): Promise<RecorderController>;
+export declare class RecorderController {
+    private readonly ctx;
+    private readonly decision;
+    /** Take the next sequence number and persist the advance (survives reload / shared tabs). */
+    private nextSeq;
+    private active;
+    private streaming;
+    /**
+     * 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.
+     */
+    private seq;
+    private keyframeId;
+    private checkpointing;
+    private dirtySinceKeyframe;
+    private lastKeyframeAt;
+    private streamChainBytes;
+    private streamChainFrames;
+    private segBuf?;
+    private reg?;
+    private snapOpts?;
+    private takeSnapshotFn?;
+    private mutationRec?;
+    private cssomRec?;
+    private encoder?;
+    private readonly pendingEncodes;
+    private adaptive?;
+    private shed;
+    private readonly persistBuffer;
+    private replayStore?;
+    private onPageHide?;
+    private onVisHidden?;
+    private redactPII;
+    private paused;
+    private maskText;
+    private disconnectRecorder?;
+    private disconnectInteractions?;
+    private disconnectCssom?;
+    private disconnectCanvas?;
+    private disconnectIframes?;
+    private disposeEncoder?;
+    private unsubSignal?;
+    private disconnectCadence?;
+    private childSatelliteStop?;
+    constructor(ctx: FeatureContext, decision: SampleDecision);
+    get isActive(): boolean;
+    /** Live diagnostics. */
+    stats(): ReplayStats;
+    /** Force a re-keyframe (e.g. ScaleBun.replay.checkpoint() before a risky flow). */
+    forceCheckpoint(reason: string): void;
+    /** 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()`. */
+    init(): Promise<void>;
+    /**
+     * 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).
+     */
+    private arm;
+    /** 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. */
+    private disarm;
+    /** Pause capture (stop observers) while keeping the session + buffered pre-roll intact. No-op when
+     *  not recording or already paused. */
+    pause(): void;
+    /** 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(): void;
+    /** 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: {
+        maskAllText?: boolean;
+    }): void;
+    /** Build a delta frame against the current keyframe. */
+    private delta;
+    private push;
+    /** 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`. */
+    private checkpoint;
+    private recoverPriorPreRoll;
+    /** Mirror the current pre-roll to IDB (byte-capped). A crash retains it; a clean close clears it. */
+    private persistPreRoll;
+    private installPersistGuards;
+    /**
+     * 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.
+     */
+    private compressInPlace;
+    /** Capture-on-signal: drain pending records, flush the pre-roll segments, then stream live. */
+    flush(): void;
+    teardown(): void;
+}
+//# sourceMappingURL=recorder.d.ts.map

package/dist/features/replay/lifecycle/recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../../../../src/features/replay/lifecycle/recorder.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,509 @@
+import { uuid, now } from '../../../core';
+import { PersistentBuffer } from '../../../storage/idb';
+import { capBytes } from '../../../core/prune';
+import { approxBytes } from './segmentBuffer';
+import { AdaptiveController, adapt } from './adaptive';
+import { redactFrame } from './pii';
+import { shouldDeferHeavyEgress } from './deviceSignals';
+import { getTabId, getViewId, getRoute } from './viewContext';
+import { reserveSeq, ensureSeqAtLeast } from '../../session/sessionStore';
+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)
+const MAX_BUFFER_BYTES = 3000000; // ~3MB pre-roll cap — a few large frames can't blow memory
+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;
+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). */
+    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;
+        this.pendingEncodes = new Set();
+        this.shed = 0; // delta frames dropped by adaptive quality (for stats in M7)
+        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,
+            bufferBytes: b?.totalBytes ?? 0,
+            droppedSegments: b?.dropped ?? 0,
+            shedFrames: this.shed,
+        };
+    }
+    /** 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'),
+            import('./segmentBuffer'),
+        ]);
+        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'),
+            import('../engine/snapshot'),
+            import('../engine/mutations'),
+            import('../engine/interactions'),
+            import('../engine/cssom'),
+            // 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'),
+        ]);
+        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,
+            seq: this.nextSeq(),
+            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();
+        const interactions = new InteractionRecorder(reg, (events) => {
+            this.push(this.delta({ events }));
+        }, { maskText: !!snapOpts.maskAllText });
+        const recorder = new MutationRecorder(reg, (mutations) => {
+            interactions.notifyDomActivity(); // a real DOM change → not a dead click
+            this.push(this.delta({ mutations }));
+        }, snapOpts);
+        const cssom = new CssomRecorder(reg, (mutations) => {
+            interactions.notifyDomActivity(); // a style change is a real visual effect, not a dead click
+            this.push(this.delta({ mutations }));
+        });
+        const iframes = new IframeManager(reg, (mutations) => {
+            interactions.notifyDomActivity();
+            this.push(this.delta({ 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').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');
+            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 → re-keyframe.
+        const { installCadence } = await import('./cadence');
+        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() {
+        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. */
+    delta(payload) {
+        return {
+            kind: 'frame',
+            renderer: 'dom',
+            frameType: 'delta',
+            frameId: `f_${uuid()}`,
+            baseFrameId: this.keyframeId,
+            seq: this.nextSeq(),
+            ...payload,
+            tabId: getTabId(),
+            viewId: getViewId(),
+            route: getRoute(),
+            masked: true,
+            timestamp: now(),
+        };
+    }
+    push(frame) {
+        // 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;
+        }
+        if (this.streaming) {
+            this.ctx.emit(frame);
+            // 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;
+        // B1: the periodic 'time' checkpoint is a no-op on a genuinely idle page — skip the redundant full
+        // re-snapshot when nothing changed since the last keyframe (bounded by MAX_IDLE_KEYFRAME_MS). Every
+        // other reason (visible / url / segment-* / manual) always re-keyframes.
+        if (reason === 'time' && !this.dirtySinceKeyframe && now() - this.lastKeyframeAt < MAX_IDLE_KEYFRAME_MS)
+            return;
+        this.checkpointing = true;
+        try {
+            this.mutationRec?.flush();
+            this.cssomRec?.flush();
+            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,
+                seq: this.nextSeq(),
+                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. */
+    persistPreRoll() {
+        if (!this.replayStore || !this.segBuf || this.streaming)
+            return;
+        void this.replayStore.save(capBytes(this.segBuf.drainFrames()));
+    }
+    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();
+        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