@vitrinka/web 0.1.0

package/build/recorder/capture/net.js

@@ -0,0 +1,506 @@
+/**
+ * Network capture — JS-level fetch + XHR monkey-patch (design decision).
+ *
+ * A consuming app's API client may ride axios, which uses XHR — that patch
+ * carries the API waterfall. The fetch patch covers manual fetches. Bodies
+ * are captured whole up to BODY_CAP (D7 capture-everything: recording is
+ * opt-in per session and the tester chooses what to record; nothing leaves the
+ * device except to the configured vitrinka host); native-level requests (image
+ * loads, native SDKs) are out of scope.
+ *
+ * Recorder's own vitrinka traffic is excluded to avoid feedback loops.
+ * Patches observe only — errors in capture code must never break the app's
+ * request, and responses are never consumed (XHR reads responseText after
+ * completion; fetch clones).
+ */
+import { isVitrinkaUrl } from '../config';
+import { getState, pushEvent, trackCapture } from '../queue';
+import { currentRoute } from '../state';
+import { redactAndCap, redactHeaders, redactUrl } from './redact';
+const BODY_CAP = 64 * 1024;
+/**
+ * Responses larger than this are recorded WITHOUT their body. `capBody` can
+ * only slice a string that was already materialized, so the cap alone does not
+ * bound decode/allocation work — the length check does.
+ */
+const BODY_READ_LIMIT = 512 * 1024;
+/**
+ * Wall-clock bound on a single body read. Keeps a streaming/stalled response
+ * from pinning a capture (and therefore Stop) open indefinitely.
+ */
+let BODY_READ_DEADLINE_MS = 3000;
+/** Test-only: shorten the read deadline so suites don't burn real seconds. */
+export function __setBodyReadDeadlineForTests(ms) {
+    const prev = BODY_READ_DEADLINE_MS;
+    BODY_READ_DEADLINE_MS = ms;
+    return () => {
+        BODY_READ_DEADLINE_MS = prev;
+    };
+}
+/** Is a session actively capturing right now? Gates all body work. */
+function capturing() {
+    return activeSessionId() !== null;
+}
+/** Id of the capturing session, else null (paused AND dead count as null). */
+function activeSessionId() {
+    const rec = getState();
+    return rec !== null && !rec.paused && !rec.dead ? rec.sessionId : null;
+}
+/**
+ * Is `id` STILL the capturing session? In-flight requests must be bound to the
+ * session they started in: a request begun in session A that completes after A
+ * stopped and B started would otherwise be appended to B, with B's route
+ * attached.
+ */
+function stillCapturing(id) {
+    return id !== null && activeSessionId() === id;
+}
+/**
+ * Redact + cap in the shape-appropriate ORDER — see `redactAndCap`
+ *.
+ */
+function capBody(body, contentType) {
+    if (typeof body === 'string')
+        return redactAndCap(body, BODY_CAP, contentType);
+    // URLSearchParams is a form body by construction — serialize it and let the
+    // engine's form transform scrub it like any other string.
+    if (typeof URLSearchParams !== 'undefined' && body instanceof URLSearchParams) {
+        return redactAndCap(body.toString(), BODY_CAP, 'application/x-www-form-urlencoded');
+    }
+    return describeOpaqueBody(body);
+}
+/**
+ * Non-string bodies are recorded as a TYPED PLACEHOLDER, never their bytes:
+ * a FormData routinely carries files and credentials and cannot be scrubbed
+ * without parsing it; a Blob/ArrayBuffer is binary. The placeholder keeps
+ * the timeline honest (a body WAS sent, this shape, this size) without the
+ * content.
+ */
+export function describeOpaqueBody(body) {
+    if (body == null)
+        return undefined;
+    if (typeof FormData !== 'undefined' && body instanceof FormData) {
+        let n = 0;
+        try {
+            body.forEach(() => n++);
+        }
+        catch {
+            // a stubbed FormData without forEach — count unknown
+        }
+        return `[formdata body omitted: ${n} field(s)]`;
+    }
+    if (typeof Blob !== 'undefined' && body instanceof Blob) {
+        return `[blob body omitted: ${body.size} bytes${body.type ? `, ${body.type}` : ''}]`;
+    }
+    if (body instanceof ArrayBuffer)
+        return `[buffer body omitted: ${body.byteLength} bytes]`;
+    if (ArrayBuffer.isView(body))
+        return `[buffer body omitted: ${body.byteLength} bytes]`;
+    if (typeof ReadableStream !== 'undefined' && body instanceof ReadableStream) {
+        return '[stream body omitted]';
+    }
+    return `[${typeof body} body omitted]`;
+}
+/** Content-type from a raw (pre-redaction) header object, '' when absent. */
+function ctOf(h) {
+    for (const [k, v] of Object.entries(h ?? {})) {
+        if (k.toLowerCase().replace(/[-_]/g, '') === 'contenttype')
+            return v;
+    }
+    return '';
+}
+/** Narrow a RequestInfo to its object form for property access. */
+function init0(input) {
+    return typeof input === 'string' || input instanceof URL ? {} : input;
+}
+function recordNet(payload) {
+    // Query strings carry secrets too (?token=…, ?otp=…) — redact the URL
+    // centrally, with the engine's dedicated URL scrub (query AND fragment,
+    // split on both `&` and `;`).
+    const url = typeof payload.url === 'string' ? redactUrl(payload.url) : payload.url;
+    pushEvent('net', { ...payload, url }, { tabId: currentRoute.tabId, tabHost: currentRoute.tabHost });
+}
+/**
+ * Normalize any HeadersInit shape (Headers, pair array, plain record) into a
+ * plain object for the redaction engine. Returns undefined when there is
+ * nothing to record; never throws — header capture must not break a request.
+ */
+function headersToObject(h) {
+    if (!h)
+        return undefined;
+    try {
+        const out = {};
+        const headers = h;
+        if (typeof headers.forEach === 'function') {
+            // Headers instance (also covers Maps and arrays via their forEach shapes
+            // differing — arrays are handled below instead).
+            if (Array.isArray(h)) {
+                for (const pair of h) {
+                    if (Array.isArray(pair) && pair.length >= 2)
+                        out[String(pair[0])] = String(pair[1]);
+                }
+            }
+            else {
+                headers.forEach((value, key) => {
+                    out[key] = String(value);
+                });
+            }
+        }
+        else if (typeof h === 'object') {
+            for (const [k, v] of Object.entries(h)) {
+                out[k] = String(v);
+            }
+        }
+        return Object.keys(out).length > 0 ? out : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** RAW request headers for a fetch call (init wins over Request) — redact before recording. */
+function rawFetchReqHeaders(input, init) {
+    const fromInit = headersToObject(init?.headers);
+    if (fromInit)
+        return fromInit;
+    const obj = init0(input);
+    return headersToObject(obj.headers);
+}
+/** Parse XHR's getAllResponseHeaders() CRLF block into a plain object. */
+function parseRawHeaders(raw) {
+    if (!raw)
+        return undefined;
+    const out = {};
+    for (const line of raw.split(/\r?\n/)) {
+        const i = line.indexOf(':');
+        if (i > 0)
+            out[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * Release a clone we are not going to read. Every early return MUST call this:
+ * an abandoned clone keeps its tee branch buffering the entire response
+ *.
+ */
+function discard(clone) {
+    try {
+        const body = clone.body;
+        void body?.cancel?.().catch(() => undefined);
+    }
+    catch {
+        // nothing to release
+    }
+}
+/** Declared body size when the server sent one, else null. */
+function declaredLength(headers) {
+    const raw = headers.get('content-length');
+    if (!raw)
+        return null;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : null;
+}
+/**
+ * Read a response body with a HARD byte bound in every path.
+ *
+ * - declared length over the limit → never read at all;
+ * - streamable body → read chunk-by-chunk and stop at the limit, so a chunked
+ *   or compressed (length-less) response can no longer buffer without bound;
+ * - no stream support and no declared length → omit the body rather than risk
+ *   an unbounded `text()`.
+ *
+ * Always reads from a CLONE, so the app's own consumption of `res` is untouched.
+ */
+async function readBoundedBody(clone, headers) {
+    const raw = await readBoundedText(clone, headers);
+    if (raw === undefined)
+        return undefined;
+    let ct = '';
+    try {
+        ct = headers.get('content-type') ?? '';
+    }
+    catch {
+        // stubbed Headers without get() — the engine falls back to shape sniffing
+    }
+    return capBody(raw, ct);
+}
+/**
+ * The BOUNDED read itself, returning raw text. Split from the capping wrapper so
+ * the bound can be asserted directly: every observable path in `readBoundedBody`
+ * runs through `capBody`, which caps to 64 KiB regardless of how much was read —
+ * a test on the recorded body cannot tell a bounded read from an unbounded one
+ *.
+ */
+async function readBoundedText(clone, headers) {
+    const size = declaredLength(headers);
+    if (size !== null && size > BODY_READ_LIMIT) {
+        // Abandoning the clone unread leaves its tee branch buffering the whole
+        // body in memory — cancel it.
+        discard(clone);
+        return `[body omitted: ${size} bytes]`;
+    }
+    const stream = clone.body;
+    if (stream?.getReader) {
+        const reader = stream.getReader();
+        const chunks = [];
+        let total = 0;
+        let truncated = false;
+        let stalled = false;
+        const readDeadline = Date.now() + BODY_READ_DEADLINE_MS;
+        try {
+            while (total < BODY_READ_LIMIT) {
+                // A long-lived stream (SSE/NDJSON) or a stalled connection reaches
+                // neither EOF nor the byte bound, which would keep this capture — and
+                // therefore Stop — waiting indefinitely.
+                const left = readDeadline - Date.now();
+                if (left <= 0) {
+                    stalled = true;
+                    break;
+                }
+                // The deadline timer MUST be cleared when the read wins, or every loop
+                // iteration leaves a live timer behind — a length-less response yielding
+                // tiny chunks could strand hundreds of thousands of them
+                //.
+                let timer;
+                const next = await Promise.race([
+                    reader.read(),
+                    new Promise((res) => {
+                        timer = setTimeout(() => res('timeout'), left);
+                    }),
+                ]).finally(() => {
+                    if (timer !== undefined)
+                        clearTimeout(timer);
+                });
+                if (next === 'timeout') {
+                    stalled = true;
+                    break;
+                }
+                const { done, value } = next;
+                if (done)
+                    break;
+                if (value) {
+                    // Slice to the REMAINING allowance: a single multi-megabyte chunk
+                    // would otherwise push total (and the joined allocation) arbitrarily
+                    // past the advertised bound.
+                    const room = BODY_READ_LIMIT - total;
+                    const part = value.byteLength > room ? value.subarray(0, room) : value;
+                    chunks.push(part);
+                    total += part.byteLength;
+                }
+            }
+            // Stop pulling once the bound is hit; the rest of the body is discarded.
+            truncated = total >= BODY_READ_LIMIT;
+            void reader.cancel().catch(() => undefined);
+        }
+        catch {
+            return undefined;
+        }
+        const joined = new Uint8Array(total);
+        let at = 0;
+        for (const c of chunks) {
+            joined.set(c, at);
+            at += c.byteLength;
+        }
+        let text;
+        try {
+            text = new TextDecoder().decode(joined);
+        }
+        catch {
+            return `[body omitted: ${total} bytes, undecodable]`;
+        }
+        if (stalled)
+            return `${text}…[body read timed out after ${BODY_READ_DEADLINE_MS}ms]`;
+        return truncated ? `${text}…[truncated at ${BODY_READ_LIMIT} bytes]` : text;
+    }
+    // No stream API (RN's fetch polyfill): only safe when the length is known.
+    if (size === null) {
+        discard(clone);
+        return '[body omitted: length-less response, no stream API]';
+    }
+    try {
+        return await clone.text();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Test-only: the RAW bounded read, before capping — see `readBoundedText`. */
+export function __readBoundedTextForTests(clone, headers) {
+    return readBoundedText(clone, headers);
+}
+/**
+ * The patched flag lives on globalThis, NOT in module scope: Fast Refresh can
+ * re-evaluate this module, which would reset a module-level boolean and stack a
+ * second patch on top of the first — double-recording every request and
+ * unbounded wrapper nesting across reloads. Keyed by a
+ * string so a re-evaluated module sees the previous evaluation's mark.
+ */
+const PATCH_MARK = '__vitrinkaRecorderNetPatched';
+/** The uninstaller of the live patch, kept on globalThis for the same reason as the mark. */
+const UNPATCH_MARK = '__vitrinkaRecorderNetUnpatch';
+/**
+ * Remove the fetch/XHR wrappers installed by `patchNetwork` — the provider's
+ * unmount calls it so the recorder never outlives its tree. Each global is
+ * restored only while it is STILL our wrapper: a later patch by someone else
+ * (a devtools, an APM agent) stacked on top must not be torn out from under
+ * them, so such a global is left in place and only our capture goes quiet
+ * (no session ⇒ the wrapper passes straight through).
+ */
+export function unpatchNetwork() {
+    const g = globalThis;
+    g[UNPATCH_MARK]?.();
+}
+export function patchNetwork() {
+    const g = globalThis;
+    if (g[PATCH_MARK])
+        return;
+    g[PATCH_MARK] = true;
+    const restores = [];
+    g[UNPATCH_MARK] = () => {
+        for (const r of restores.splice(0))
+            r();
+        delete g[PATCH_MARK];
+        delete g[UNPATCH_MARK];
+    };
+    const origFetch = globalThis.fetch;
+    const wrappedFetch = async (input, init) => {
+        const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+        // Not recording (or recorder's own traffic) → pass straight through: no
+        // clone, no body read, zero added cost.
+        const origin = activeSessionId();
+        if (isVitrinkaUrl(url) || origin === null)
+            return origFetch(input, init);
+        const method = init?.method ??
+            ('method' in init0(input) ? init0(input).method : 'GET');
+        const started = Date.now();
+        try {
+            const res = await origFetch(input, init);
+            const ms = Date.now() - started;
+            // Clone SYNCHRONOUSLY (before the caller can consume the body), then read
+            // and record OFF the caller's critical path: awaiting the body read here
+            // delayed the app's own `await fetch(...)` by however long the recorder
+            // took to pull up to 512 KiB.
+            let clone;
+            try {
+                clone = res.clone();
+            }
+            catch {
+                clone = undefined; // opaque/consumed body — never disturb the original
+            }
+            const headers = res.headers;
+            const status = res.status;
+            trackCapture((async () => {
+                // Re-check AFTER the await, and require the SAME session — the run may
+                // have been paused/stopped meanwhile.
+                if (!stillCapturing(origin))
+                    return;
+                const resBody = clone ? await readBoundedBody(clone, headers) : undefined;
+                if (!stillCapturing(origin))
+                    return;
+                const rawReqHeaders = rawFetchReqHeaders(input, init);
+                recordNet({
+                    method,
+                    url,
+                    status,
+                    ms,
+                    reqHeaders: redactHeaders(rawReqHeaders),
+                    resHeaders: redactHeaders(headersToObject(headers)),
+                    reqBody: capBody(init?.body, ctOf(rawReqHeaders)),
+                    resBody,
+                    via: 'fetch',
+                });
+            })());
+            return res;
+        }
+        catch (e) {
+            if (stillCapturing(origin)) {
+                recordNet({ method, url, error: String(e), ms: Date.now() - started, via: 'fetch' });
+            }
+            throw e;
+        }
+    };
+    // Bun/undici type `fetch` with static extras (preconnect) the wrapper does
+    // not carry; the runtime contract is the call signature alone.
+    globalThis.fetch = wrappedFetch;
+    restores.push(() => {
+        if (globalThis.fetch === wrappedFetch)
+            globalThis.fetch = origFetch;
+    });
+    const XHR = globalThis.XMLHttpRequest;
+    // A runtime without XHR (or a stubbed one) must not take the recorder down —
+    // patchNetwork() runs during provider mount, so a throw here would break the
+    // whole app tree, not just capture.
+    if (!XHR?.prototype)
+        return;
+    const origOpen = XHR.prototype.open;
+    const origSend = XHR.prototype.send;
+    const origSetHeader = XHR.prototype.setRequestHeader;
+    restores.push(() => {
+        const p = XHR.prototype;
+        if (p.open === patchedOpen)
+            p.open = origOpen;
+        if (p.send === patchedSend)
+            p.send = origSend;
+        if (p.setRequestHeader === patchedSetHeader)
+            p.setRequestHeader = origSetHeader;
+    });
+    const patchedOpen = (XHR.prototype.open = function (...args) {
+        this.__vt = {
+            method: args[0],
+            url: String(args[1]),
+        };
+        return origOpen.apply(this, args);
+    });
+    // Request headers are only observable at the call site — record them as the
+    // app sets them (redaction happens at event build, against the live rules).
+    // The original may be absent on a stubbed XHR; observing must survive that.
+    const patchedSetHeader = (XHR.prototype.setRequestHeader = function (name, value) {
+        const meta = this.__vt;
+        if (meta)
+            (meta.reqHeaders ??= {})[name] = value;
+        return origSetHeader?.call(this, name, value);
+    });
+    const patchedSend = (XHR.prototype.send = function (body) {
+        const meta = this.__vt;
+        const origin = activeSessionId();
+        if (meta && !isVitrinkaUrl(meta.url) && origin !== null) {
+            const started = Date.now();
+            this.addEventListener('loadend', () => {
+                // Re-check at COMPLETION, and require the SAME session: a pause/stop
+                // mid-flight means no event is recorded (so reading responseText would
+                // be waste), and a request that outlives its session must
+                // not be attributed to the next one.
+                if (!stillCapturing(origin))
+                    return;
+                let rawResHeaders;
+                try {
+                    rawResHeaders = parseRawHeaders(this.getAllResponseHeaders());
+                }
+                catch {
+                    rawResHeaders = undefined;
+                }
+                let resBody;
+                try {
+                    resBody =
+                        this.responseType === '' || this.responseType === 'text'
+                            ? capBody(this.responseText, ctOf(rawResHeaders))
+                            : undefined;
+                }
+                catch {
+                    resBody = undefined;
+                }
+                recordNet({
+                    method: meta.method,
+                    url: meta.url,
+                    status: this.status,
+                    ms: Date.now() - started,
+                    reqHeaders: redactHeaders(meta.reqHeaders),
+                    resHeaders: redactHeaders(rawResHeaders),
+                    reqBody: capBody(body, ctOf(meta.reqHeaders)),
+                    resBody,
+                    via: 'xhr',
+                });
+            });
+        }
+        return origSend.call(this, body);
+    });
+}

package/build/recorder/capture/redact.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Redaction bridge — binds the shared engine (@vitrinka/redact) to the
+ * CURRENT session's workspace policy.
+ *
+ * The engine itself owns all semantics (key classification, JSON/form/
+ * multipart bodies, URL query+fragment scrubbing, patterns, fullFidelity);
+ * this module owns which RULES apply right now: the safe defaults until a
+ * session starts, the session's fetched policy after. FAIL CLOSED — a failed
+ * or slow policy fetch means the defaults, never capture-everything.
+ *
+ * Capture layers import the bound helpers below so every call site stays a
+ * one-liner and can never forget to pass the rules.
+ */
+import { type MaskDirectives, type RedactionPolicy, type RuleSet } from '@vitrinka/redact';
+export { isSecretKey, REDACTED, type RedactionPolicy } from '@vitrinka/redact';
+/**
+ * Apply a session's workspace policy (null = the safe defaults). Called at
+ * session start when the fetch resolves, and on provider mount when a session
+ * (with its policy) is recovered from storage after a reload.
+ */
+export declare function setRedactionPolicy(policy: RedactionPolicy | null | undefined): void;
+/** The active rule set (test + capture-layer introspection). */
+export declare function currentRules(): RuleSet;
+/** Redact a captured body/log string under the active rules. Never throws. */
+export declare function redactText(text: string | undefined): string | undefined;
+/**
+ * Redact then cap (shape-aware order) under the active rules. Pass the
+ * captured content type when known — the engine dispatches its form-encoded
+ * and multipart transforms on it; without it those bodies only get the
+ * generic text scanner.
+ */
+export declare function redactAndCap(body: string, cap: number, contentType?: string): string | undefined;
+/** Scrub URL query/fragment secrets under the active rules. */
+export declare function redactUrl(url: string): string;
+/** Scrub + cap a captured header map under the active rules. */
+export declare function redactHeaders(headers: Record<string, unknown> | undefined): Record<string, string> | undefined;
+/** rrweb masking options under the active rules (maskAllInputs / maskAllText). */
+export declare function maskDirectives(): MaskDirectives;

package/build/recorder/capture/redact.js

@@ -0,0 +1,54 @@
+/**
+ * Redaction bridge — binds the shared engine (@vitrinka/redact) to the
+ * CURRENT session's workspace policy.
+ *
+ * The engine itself owns all semantics (key classification, JSON/form/
+ * multipart bodies, URL query+fragment scrubbing, patterns, fullFidelity);
+ * this module owns which RULES apply right now: the safe defaults until a
+ * session starts, the session's fetched policy after. FAIL CLOSED — a failed
+ * or slow policy fetch means the defaults, never capture-everything.
+ *
+ * Capture layers import the bound helpers below so every call site stays a
+ * one-liner and can never forget to pass the rules.
+ */
+import { compileRules, redactAndCap as engineRedactAndCap, redactHeaders as engineRedactHeaders, redactText as engineRedactText, redactUrl as engineRedactUrl, maskDirectives as engineMaskDirectives, } from '@vitrinka/redact';
+// Engine primitives that need no binding, re-exported for tests and callers.
+export { isSecretKey, REDACTED } from '@vitrinka/redact';
+let rules = compileRules(null);
+/**
+ * Apply a session's workspace policy (null = the safe defaults). Called at
+ * session start when the fetch resolves, and on provider mount when a session
+ * (with its policy) is recovered from storage after a reload.
+ */
+export function setRedactionPolicy(policy) {
+    rules = compileRules(policy ?? null);
+}
+/** The active rule set (test + capture-layer introspection). */
+export function currentRules() {
+    return rules;
+}
+/** Redact a captured body/log string under the active rules. Never throws. */
+export function redactText(text) {
+    return engineRedactText(rules, text);
+}
+/**
+ * Redact then cap (shape-aware order) under the active rules. Pass the
+ * captured content type when known — the engine dispatches its form-encoded
+ * and multipart transforms on it; without it those bodies only get the
+ * generic text scanner.
+ */
+export function redactAndCap(body, cap, contentType) {
+    return engineRedactAndCap(rules, body, cap, contentType);
+}
+/** Scrub URL query/fragment secrets under the active rules. */
+export function redactUrl(url) {
+    return engineRedactUrl(rules, url);
+}
+/** Scrub + cap a captured header map under the active rules. */
+export function redactHeaders(headers) {
+    return engineRedactHeaders(rules, headers);
+}
+/** rrweb masking options under the active rules (maskAllInputs / maskAllText). */
+export function maskDirectives() {
+    return engineMaskDirectives(rules);
+}

package/build/recorder/capture/rrweb.d.ts

@@ -0,0 +1,10 @@
+/** Elements carrying this attribute are never recorded (the HUD host). */
+export declare const RRWEB_BLOCK_ATTR = "data-vitrinka-recorder";
+/** Start recording the DOM; idempotent. */
+export declare function startRRWeb(): void;
+/** Ship the tail and stop recording. */
+export declare function stopRRWeb(): void;
+/** Take a fresh full snapshot (resume after pause, policy change). */
+export declare function checkoutRRWeb(): void;
+/** Flush the current batch now (pagehide, stop). */
+export declare function flushRRWeb(): void;

package/build/recorder/capture/rrweb.js

@@ -0,0 +1,76 @@
+import { record } from 'rrweb';
+import { pushRRWebBatch } from '../queue';
+import { currentRoute } from '../state';
+import { maskDirectives } from './redact';
+const BATCH_MS = 2000;
+/** A fresh full snapshot every 5 min keeps long recordings seekable. */
+const CHECKOUT_MS = 5 * 60 * 1000;
+/** Elements carrying this attribute are never recorded (the HUD host). */
+export const RRWEB_BLOCK_ATTR = 'data-vitrinka-recorder';
+let stop = null;
+let buf = [];
+let timer = null;
+function ship() {
+    if (!buf.length)
+        return;
+    const events = buf;
+    buf = [];
+    // Not capturing (paused): the batch is dropped on purpose — paused means
+    // paused, and the next resume starts from a fresh checkout.
+    pushRRWebBatch(events, { tabId: currentRoute.tabId, tabHost: currentRoute.tabHost });
+}
+/** Start recording the DOM; idempotent. */
+export function startRRWeb() {
+    if (stop)
+        return;
+    const mask = maskDirectives();
+    try {
+        const stopFn = record({
+            emit: (ev) => {
+                buf.push(ev);
+            },
+            checkoutEveryNms: CHECKOUT_MS,
+            inlineImages: true,
+            collectFonts: true,
+            maskAllInputs: mask.maskAllInputs,
+            ...(mask.maskTextSelector ? { maskTextSelector: mask.maskTextSelector } : {}),
+            blockSelector: `[${RRWEB_BLOCK_ATTR}]`,
+        });
+        stop = stopFn ?? null;
+    }
+    catch (e) {
+        console.warn('vitrinka: rrweb failed to start', e);
+        return;
+    }
+    timer = setInterval(ship, BATCH_MS);
+}
+/** Ship the tail and stop recording. */
+export function stopRRWeb() {
+    if (timer)
+        clearInterval(timer);
+    timer = null;
+    ship();
+    try {
+        stop?.();
+    }
+    catch {
+        // already torn down
+    }
+    stop = null;
+    buf = [];
+}
+/** Take a fresh full snapshot (resume after pause, policy change). */
+export function checkoutRRWeb() {
+    if (!stop)
+        return;
+    try {
+        record.takeFullSnapshot?.(true);
+    }
+    catch {
+        // older rrweb — the periodic checkout covers it
+    }
+}
+/** Flush the current batch now (pagehide, stop). */
+export function flushRRWeb() {
+    ship();
+}