@cubenest/rrweb-core 0.1.0-alpha.0

package/dist/persistence/store.js

@@ -0,0 +1,327 @@
+// IndexedDB-backed session chunk store — Task 1.10.
+//
+// `createSessionStore(sessionId)` opens (or creates) the @cubenest/rrweb-core
+// IDB database, returns a `SessionStore` handle whose methods append/read
+// gzipped event chunks keyed by `[sessionId, seq]`. The store is purpose-
+// built for one consumer (@peekdev's MV3 extension) and one shape of
+// payload (the `Uint8Array` output of `../compression`); we keep the
+// abstraction deliberately thin per ADR-0002's "core stays minimal" pact.
+//
+// Why a separate seq column (vs. autoIncrement on the object store)?
+//   - autoIncrement is per-store, not per-session. With many sessions
+//     interleaved, the keys would still be globally monotonic but the
+//     per-session sequence would have gaps, defeating range reads.
+//   - A composite primary key of `[sessionId, seq]` lets us range-scan
+//     by session cheaply via the natural keyspace ordering. No secondary
+//     index needed for reads.
+//   - `count()` on the `by-session` index gives us the next `seq` cheaply
+//     (no full scan) without persisting a counter row. For the v0.1
+//     throughput target (a few hundred chunks per session) this is fine;
+//     a future optimization could cache `lastSeq` in memory but adds a
+//     correctness hazard across multi-tab opens of the same session.
+//
+// Why no transactions across awaits?
+//   - IDB transactions auto-close at the end of the current microtask
+//     queue tick (the "task" boundary). Awaiting an unrelated promise
+//     between two operations on the SAME transaction is undefined on
+//     Chromium and outright broken on Safari (the spec was tightened
+//     post-Firefox/Edge convergence; older patterns that relied on
+//     "transactions stay open as long as you keep doing IDB" no longer
+//     hold). Each public method opens its own transaction and only
+//     awaits the wrapped Promise. We pay an extra `transaction()` call
+//     per op; in exchange we get portability and predictable behavior.
+//
+// Why structured-clone-safe `bytes` (Uint8Array)?
+//   - IDB stores values via structured clone. `Uint8Array` is on the
+//     supported list; `ArrayBuffer` would also work, but `Uint8Array`
+//     is what `compress()` returns, so we avoid a useless view shuffle.
+const DEFAULT_DB_NAME = '@cubenest/rrweb-core';
+const DEFAULT_STORE_NAME = 'session-chunks';
+const SCHEMA_VERSION = 1;
+const SESSION_INDEX = 'by-session';
+/**
+ * Promisify a single `IDBRequest`. Resolves on `success`, rejects on `error`.
+ *
+ * Keep the body tight — the listeners run on the IDB callback queue and
+ * must NOT do work that could throw before binding both handlers, or the
+ * UA will swallow the rejection and the caller's `await` will hang
+ * forever. This is the standard `req<T>` pattern; we lift it into a
+ * helper because every method below uses it ≥1 time.
+ */
+function req(r) {
+    return new Promise((resolve, reject) => {
+        r.onsuccess = () => {
+            resolve(r.result);
+        };
+        r.onerror = () => {
+            reject(r.error ?? new Error('IDBRequest failed without an error object'));
+        };
+    });
+}
+/**
+ * Promisify an `IDBTransaction` completion. Resolves on `complete`,
+ * rejects on `error` / `abort`. Use after firing all writes so the
+ * caller knows the transaction has actually committed before returning.
+ */
+function txDone(tx) {
+    return new Promise((resolve, reject) => {
+        tx.oncomplete = () => {
+            resolve();
+        };
+        tx.onerror = () => {
+            reject(tx.error ?? new Error('IDBTransaction failed without an error object'));
+        };
+        tx.onabort = () => {
+            reject(tx.error ?? new Error('IDBTransaction aborted'));
+        };
+    });
+}
+/**
+ * Open the database, creating the object store + index on first run.
+ *
+ * The `onupgradeneeded` path is the ONLY place schema mutations are
+ * allowed. We pin to `SCHEMA_VERSION = 1` for v0.1; future schema
+ * changes bump the version and add a migration branch here. Bumping
+ * the version triggers a `versionchange` event on any other open
+ * connection — callers in long-lived MV3 service workers should be
+ * prepared to close-and-reopen.
+ */
+function openDb(idb, dbName, storeName) {
+    return new Promise((resolve, reject) => {
+        const request = idb.open(dbName, SCHEMA_VERSION);
+        request.onupgradeneeded = () => {
+            const db = request.result;
+            if (!db.objectStoreNames.contains(storeName)) {
+                // Composite key `[sessionId, seq]` gives us natural range scans
+                // by session without a secondary index for reads. The `by-session`
+                // index is used for `count()`-based seq assignment and for
+                // prune/clear cursors.
+                const store = db.createObjectStore(storeName, { keyPath: ['sessionId', 'seq'] });
+                store.createIndex(SESSION_INDEX, 'sessionId', { unique: false });
+            }
+        };
+        request.onsuccess = () => {
+            resolve(request.result);
+        };
+        request.onerror = () => {
+            reject(request.error ?? new Error('IDB open failed'));
+        };
+        request.onblocked = () => {
+            // A previous connection with an older version is still open and
+            // blocking our upgrade. We can't make progress; surface it as a
+            // rejection rather than hanging forever.
+            reject(new Error(`IDB open blocked by another open connection to ${dbName}`));
+        };
+    });
+}
+/**
+ * Open an IDB-backed chunk store for a session.
+ *
+ * The returned `SessionStore` is scoped to `sessionId`; all read/write
+ * operations are filtered by it. Multiple stores for different sessions
+ * can be opened concurrently — they share the same DB connection's
+ * keyspace but are isolated by the composite key.
+ *
+ * @param sessionId  non-empty session identifier; used as the first
+ *                   component of every chunk's composite key
+ * @param options    optional overrides (dbName, storeName, IDBFactory)
+ * @throws {Error} if `sessionId` is empty / non-string, or if no
+ *                 `IDBFactory` is available (`globalThis.indexedDB`
+ *                 undefined and `options.indexedDB` not provided)
+ */
+export async function createSessionStore(sessionId, options) {
+    if (typeof sessionId !== 'string' || sessionId.length === 0) {
+        throw new Error('createSessionStore: sessionId must be a non-empty string');
+    }
+    const dbName = options?.dbName ?? DEFAULT_DB_NAME;
+    const storeName = options?.storeName ?? DEFAULT_STORE_NAME;
+    // Resolve the IDBFactory. Explicit injection wins so tests / non-browser
+    // environments can opt out of `globalThis.indexedDB`. The lookup
+    // happens at construction time (not lazily per-op) so misconfiguration
+    // fails fast with a clear error instead of a confusing "undefined is
+    // not a function" deep inside an op.
+    const idb = options?.indexedDB ?? globalThis.indexedDB;
+    if (!idb) {
+        throw new Error('createSessionStore: no IDBFactory available — pass options.indexedDB or run in a browser');
+    }
+    const db = await openDb(idb, dbName, storeName);
+    // `closed` is the public-visible "is this store usable" flag. We flip
+    // it to true on `close()` and check it at the top of every op. Doing
+    // this in user-space (rather than relying on the IDB connection's
+    // own closed state) lets us surface a clean, package-branded error
+    // instead of whatever cryptic message the UA produces on a closed
+    // connection (Chromium's "TransactionInactiveError" vs Safari's
+    // various "InvalidStateError" wordings).
+    let closed = false;
+    function assertOpen() {
+        if (closed) {
+            throw new Error('SessionStore: connection is closed');
+        }
+    }
+    async function append(bytes, meta) {
+        assertOpen();
+        if (!(bytes instanceof Uint8Array)) {
+            throw new TypeError('SessionStore.append: bytes must be a Uint8Array');
+        }
+        // Step 1 — figure out the next `seq` by counting existing rows for
+        // this session. We do this in a `readonly` transaction so it doesn't
+        // contend with concurrent reads on other sessions; the cost is one
+        // extra `transaction()` per append vs. doing the count + put in a
+        // single `readwrite` (which would also work, but is harder to read
+        // and gives no measurable benefit for our throughput).
+        const countTx = db.transaction(storeName, 'readonly');
+        const countStore = countTx.objectStore(storeName);
+        const idx = countStore.index(SESSION_INDEX);
+        const seq = await req(idx.count(IDBKeyRange.only(sessionId)));
+        // Step 2 — write the row. Use `add()` (not `put()`) so a duplicate
+        // composite key throws instead of silently overwriting; this guards
+        // against the multi-tab race where two writers compute the same
+        // `seq` concurrently. The caller can retry on the rejection.
+        const writeTx = db.transaction(storeName, 'readwrite');
+        const writeStore = writeTx.objectStore(storeName);
+        const row = {
+            sessionId,
+            seq,
+            ts: Date.now(),
+            bytes,
+            ...(meta !== undefined ? { meta } : {}),
+        };
+        await req(writeStore.add(row));
+        await txDone(writeTx);
+        return seq;
+    }
+    async function read(fromSeq, toSeq) {
+        assertOpen();
+        if (!Number.isFinite(fromSeq) || fromSeq < 0) {
+            throw new RangeError('SessionStore.read: fromSeq must be a non-negative number');
+        }
+        // Bound the range. When toSeq is omitted we want "everything ≥ fromSeq",
+        // which we express as `[sessionId, fromSeq] .. [sessionId, +Infinity]`.
+        // IDB compares composite keys lexicographically, so the upper bound
+        // `[sessionId, +Infinity]` correctly stops before keys with a larger
+        // sessionId. Note: `[sessionId, undefined]` does NOT work — undefined
+        // is not a valid key component.
+        const upper = toSeq ?? Number.POSITIVE_INFINITY;
+        const range = IDBKeyRange.bound([sessionId, fromSeq], [sessionId, upper]);
+        const tx = db.transaction(storeName, 'readonly');
+        const store = tx.objectStore(storeName);
+        const all = await req(store.getAll(range));
+        // The cursor would already return rows in key order, but `getAll`
+        // also returns them sorted by key. We assert the invariant anyway
+        // — defensive, since downstream consumers depend on it.
+        const chunks = all.map((r) => ({
+            seq: r.seq,
+            ts: r.ts,
+            bytes: r.bytes,
+            ...(r.meta !== undefined ? { meta: r.meta } : {}),
+        }));
+        for (let i = 1; i < chunks.length; i++) {
+            const prev = chunks[i - 1];
+            const curr = chunks[i];
+            if (prev && curr && prev.seq >= curr.seq) {
+                // Should never happen given the composite-key sort, but if the
+                // UA ever returns out-of-order rows we want a loud failure here
+                // rather than a silently-corrupted replay.
+                throw new Error(`SessionStore.read: rows out of order at index ${i} (${prev.seq} >= ${curr.seq})`);
+            }
+        }
+        return chunks;
+    }
+    async function readLastN(n) {
+        assertOpen();
+        if (!Number.isFinite(n) || n < 0) {
+            throw new RangeError('SessionStore.readLastN: n must be a non-negative number');
+        }
+        if (n === 0)
+            return [];
+        const total = await size();
+        const fromSeq = Math.max(0, total - n);
+        return read(fromSeq);
+    }
+    async function size() {
+        assertOpen();
+        const tx = db.transaction(storeName, 'readonly');
+        const store = tx.objectStore(storeName);
+        const idx = store.index(SESSION_INDEX);
+        return req(idx.count(IDBKeyRange.only(sessionId)));
+    }
+    async function totalBytes() {
+        assertOpen();
+        // We walk the keyspace via `getAll` and sum byteLength. For v0.1
+        // session sizes (a few hundred chunks at most), this is fine; if
+        // future workloads need true streaming sums we'd switch to a
+        // cursor and accumulate without materializing the rows.
+        const range = IDBKeyRange.bound([sessionId, 0], [sessionId, Number.POSITIVE_INFINITY]);
+        const tx = db.transaction(storeName, 'readonly');
+        const store = tx.objectStore(storeName);
+        const all = (await req(store.getAll(range)));
+        let sum = 0;
+        for (const row of all) {
+            sum += row.bytes.byteLength;
+        }
+        return sum;
+    }
+    async function prune(beforeSeq) {
+        assertOpen();
+        if (!Number.isFinite(beforeSeq) && beforeSeq !== Number.POSITIVE_INFINITY) {
+            throw new RangeError('SessionStore.prune: beforeSeq must be a finite number or +Infinity');
+        }
+        if (beforeSeq <= 0)
+            return 0;
+        // Range covers `[sessionId, 0] .. [sessionId, beforeSeq)` — open
+        // upper bound excludes `beforeSeq` itself, matching the docstring
+        // "delete chunks with seq < beforeSeq".
+        const range = IDBKeyRange.bound([sessionId, 0], [sessionId, beforeSeq], false, true);
+        const tx = db.transaction(storeName, 'readwrite');
+        const store = tx.objectStore(storeName);
+        // Cursor-based delete is the IDB idiom for "delete range". We can't
+        // use `delete(range)` here without losing the count of deleted
+        // rows, and the count is part of the public return value.
+        const deleted = await new Promise((resolve, reject) => {
+            const cursorReq = store.openCursor(range);
+            let count = 0;
+            cursorReq.onsuccess = () => {
+                const cursor = cursorReq.result;
+                if (!cursor) {
+                    resolve(count);
+                    return;
+                }
+                cursor.delete();
+                count++;
+                cursor.continue();
+            };
+            cursorReq.onerror = () => {
+                reject(cursorReq.error ?? new Error('SessionStore.prune: cursor failed'));
+            };
+        });
+        await txDone(tx);
+        return deleted;
+    }
+    async function clear() {
+        assertOpen();
+        // `prune(+Infinity)` deletes everything `seq < +Infinity` for this
+        // session — i.e. every row scoped to `sessionId`. Other sessions'
+        // rows are untouched because the range is bounded on the lower
+        // side by `[sessionId, 0]` and on the upper by `[sessionId, ∞)`.
+        await prune(Number.POSITIVE_INFINITY);
+    }
+    function close() {
+        if (closed)
+            return Promise.resolve();
+        closed = true;
+        db.close();
+        return Promise.resolve();
+    }
+    return {
+        sessionId,
+        append,
+        read,
+        readLastN,
+        size,
+        totalBytes,
+        prune,
+        clear,
+        close,
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/persistence/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/persistence/store.ts"],"names":[],"mappings":"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"}

package/dist/persistence/types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * One stored chunk: a gzipped rrweb-event batch plus the bookkeeping the
+ * store assigns at append time. `seq` is monotonically increasing per
+ * session; `ts` is the wall-clock at append; `bytes` is the gzipped output
+ * of `compress()`, persisted verbatim and never re-encoded by the store.
+ *
+ * `meta` is an opt-in escape hatch for adapter-supplied metadata
+ * (e.g. `{ url, isFirst, viewportWidth }`). Keys are plain strings;
+ * values are restricted to JSON-safe scalars so the structured-clone
+ * write path stays predictable across browsers.
+ */
+export interface SessionChunk {
+    /** Monotonically increasing per session. The store assigns this on append. */
+    readonly seq: number;
+    /** ms epoch when the chunk was created. */
+    readonly ts: number;
+    /** Gzipped event bytes (from compress()). Persisted as-is. */
+    readonly bytes: Uint8Array;
+    /** Optional adapter-supplied metadata. */
+    readonly meta?: Record<string, string | number | boolean>;
+}
+/**
+ * The handle returned by `createSessionStore`. All operations are async
+ * and back onto the underlying IDB connection opened by the factory.
+ *
+ * Operations don't share transactions — each call opens its own. This is
+ * the safest pattern under IndexedDB's "transactions auto-close at the
+ * end of the current task" rule: holding a transaction across an `await`
+ * boundary is undefined behaviour on most engines and outright broken on
+ * Safari. The internal helper wraps each `IDBRequest` in a Promise that
+ * resolves on `onsuccess` and rejects on `onerror`.
+ *
+ * After `close()`, every subsequent op rejects with an Error rather than
+ * silently queueing — callers can race on the rejection to decide whether
+ * to reopen.
+ */
+export interface SessionStore {
+    /** The session id this store was opened for. Immutable after construction. */
+    readonly sessionId: string;
+    /** Append a chunk. Returns the assigned seq. */
+    append(bytes: Uint8Array, meta?: SessionChunk['meta']): Promise<number>;
+    /** Read chunks with seq in [fromSeq, toSeq] inclusive (toSeq optional = unlimited). */
+    read(fromSeq: number, toSeq?: number): Promise<SessionChunk[]>;
+    /** Read the last N chunks. */
+    readLastN(n: number): Promise<SessionChunk[]>;
+    /** Total chunk count for the session. */
+    size(): Promise<number>;
+    /** Total compressed bytes across all chunks for the session. */
+    totalBytes(): Promise<number>;
+    /** Delete chunks with seq < beforeSeq (used by the extension to keep recent-N). */
+    prune(beforeSeq: number): Promise<number>;
+    /** Delete every chunk for this session. */
+    clear(): Promise<void>;
+    /** Close the underlying IDB connection. */
+    close(): Promise<void>;
+}
+/**
+ * Options for `createSessionStore`. Every field is optional; defaults
+ * are picked so a plain `createSessionStore(sessionId)` call works in
+ * any browser that exposes `globalThis.indexedDB`.
+ *
+ * `indexedDB` is the test/polyfill seam. Pass `fake-indexeddb`'s factory
+ * here in unit tests, or your environment's polyfill in non-standard
+ * runtimes (worker shims, jsdom, etc.). When omitted, the store reads
+ * `globalThis.indexedDB` at construction time and throws if it's
+ * undefined — fail fast beats lazy null-deref.
+ */
+export interface SessionStoreOptions {
+    /** IDB database name. Default '@cubenest/rrweb-core'. */
+    dbName?: string;
+    /** IDB object-store name. Default 'session-chunks'. */
+    storeName?: string;
+    /** Optional injection for tests / non-browser environments. */
+    indexedDB?: IDBFactory;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/persistence/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/persistence/types.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CAC3D;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gDAAgD;IAChD,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACxE,uFAAuF;IACvF,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAC/D,8BAA8B;IAC9B,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAC9C,yCAAyC;IACzC,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB,gEAAgE;IAChE,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9B,mFAAmF;IACnF,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1C,2CAA2C;IAC3C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,2CAA2C;IAC3C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,UAAU,CAAC;CACxB"}

package/dist/persistence/types.js

@@ -0,0 +1,21 @@
+// IndexedDB persistence types — Task 1.10.
+//
+// Public shapes for the IDB-backed chunk store used by the @peekdev extension
+// to persist rrweb recordings across MV3 service-worker restarts. Tracelane
+// ignores this module — its self-contained HTML report path doesn't need
+// crash-safe persistence.
+//
+// A "chunk" is the output of `compress(events)` — gzipped event bytes that
+// land here as-is. The store does NOT decode them; the caller round-trips
+// via `decompress` (see ../compression).
+//
+// Public API contract (IMPLEMENTATION_PLAN.md line 726):
+//
+//   export { createSessionStore, type SessionChunk } from './persistence';
+//
+// The factory and the chunk type are the "locked" surface. The store
+// interface and options interface are re-exported for declare-and-pass
+// ergonomics but are not part of the contract line; their shape can
+// evolve under semver.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/persistence/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/persistence/types.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,yEAAyE;AACzE,0BAA0B;AAC1B,EAAE;AACF,2EAA2E;AAC3E,0EAA0E;AAC1E,yCAAyC;AACzC,EAAE;AACF,yDAAyD;AACzD,EAAE;AACF,2EAA2E;AAC3E,EAAE;AACF,qEAAqE;AACrE,uEAAuE;AACvE,oEAAoE;AACpE,uBAAuB"}

package/dist/rrweb.d.ts

@@ -0,0 +1,5 @@
+export { record, Replayer, EventType, IncrementalSource, MouseInteractions, } from '@posthog/rrweb';
+export { getRecordConsolePlugin } from '@rrweb/rrweb-plugin-console-record';
+export type { eventWithTime, customEvent, } from '@posthog/rrweb-types';
+export type { recordOptions } from '@posthog/rrweb';
+//# sourceMappingURL=rrweb.d.ts.map

package/dist/rrweb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rrweb.d.ts","sourceRoot":"","sources":["../src/rrweb.ts"],"names":[],"mappings":"AAUA,OAAO,EACL,MAAM,EACN,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAE5E,YAAY,EACV,aAAa,EACb,WAAW,GACZ,MAAM,sBAAsB,CAAC;AAI9B,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/rrweb.js

@@ -0,0 +1,13 @@
+// Re-export the vendored capture surface.
+//
+// Engine comes from the PostHog fork (@posthog/rrweb), which is feature-frozen
+// at 0.0.34 — see ADR-0002. The fork inherits upstream rrweb 2.x's package
+// split, so plugin code is NOT in the main bundle. We pull the console-record
+// plugin from the upstream MIT package because event shapes are compatible
+// (both descend from rrweb@2.0.0-alpha.17).
+//
+// If PostHog renames an export, or upstream renames a plugin export, this
+// file is where the build will break — that is the smoke test.
+export { record, Replayer, EventType, IncrementalSource, MouseInteractions, } from '@posthog/rrweb';
+export { getRecordConsolePlugin } from '@rrweb/rrweb-plugin-console-record';
+//# sourceMappingURL=rrweb.js.map

package/dist/rrweb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rrweb.js","sourceRoot":"","sources":["../src/rrweb.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,EAAE;AACF,+EAA+E;AAC/E,2EAA2E;AAC3E,8EAA8E;AAC9E,2EAA2E;AAC3E,4CAA4C;AAC5C,EAAE;AACF,0EAA0E;AAC1E,+DAA+D;AAC/D,OAAO,EACL,MAAM,EACN,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC"}

package/dist/screenshot/base64.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Decode a base64 string to bytes using the platform-native `atob`.
+ *
+ * @throws DOMException ("InvalidCharacterError") if the input is not
+ *         well-formed base64 — caller decides whether to wrap.
+ */
+export declare function decodeBase64(base64: string): Uint8Array;
+//# sourceMappingURL=base64.d.ts.map

package/dist/screenshot/base64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64.d.ts","sourceRoot":"","sources":["../../src/screenshot/base64.ts"],"names":[],"mappings":"AAWA;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAGvD"}

package/dist/screenshot/base64.js

@@ -0,0 +1,21 @@
+// Platform-native base64 decoder — Task 1.6.
+//
+// The substrate must stay environment-agnostic. `Buffer.from(str, 'base64')`
+// would tie us to Node; pulling in a JS-side decoder bloats the bundle. Both
+// targets (Node 20.10+ and modern browsers) ship `atob` on globalThis, so
+// we use it.
+//
+// `atob` returns a binary string — each char's `.charCodeAt(0)` is the
+// corresponding byte. We materialise that into a Uint8Array with
+// `Uint8Array.from`, which is O(n) and allocates exactly once.
+/**
+ * Decode a base64 string to bytes using the platform-native `atob`.
+ *
+ * @throws DOMException ("InvalidCharacterError") if the input is not
+ *         well-formed base64 — caller decides whether to wrap.
+ */
+export function decodeBase64(base64) {
+    const bin = atob(base64);
+    return Uint8Array.from(bin, (ch) => ch.charCodeAt(0));
+}
+//# sourceMappingURL=base64.js.map

package/dist/screenshot/base64.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64.js","sourceRoot":"","sources":["../../src/screenshot/base64.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,0EAA0E;AAC1E,aAAa;AACb,EAAE;AACF,uEAAuE;AACvE,iEAAiE;AACjE,+DAA+D;AAE/D;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IACzB,OAAO,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AACxD,CAAC"}

package/dist/screenshot/cdp.d.ts

@@ -0,0 +1,50 @@
+import type { ScreenshotAdapter } from './types';
+/**
+ * Structural shape of a CDP transport — typically a thin wrapper around
+ * `chrome-remote-interface`, a WebDriver CDP bridge (e.g.
+ * `browser.cdp` in WDIO), or Playwright's `CDPSession.send`.
+ *
+ * The factory only calls `.send`; emitting events back is the consumer's
+ * problem and lives outside this contract.
+ */
+export interface CDPTransport {
+    send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+/**
+ * Factory-time options for the CDP screenshot adapter. All fields map
+ * directly onto the [`Page.captureScreenshot`][cdp] parameters; defaults
+ * are applied at `capture()` time, not at factory time, so a single adapter
+ * can be reused across captures without mutation.
+ *
+ * [cdp]: https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-captureScreenshot
+ */
+export interface CDPScreenshotOptions {
+    /** PNG (default) or JPEG. JPEG is smaller but lossy. */
+    format?: 'png' | 'jpeg';
+    /** 0-100. Only meaningful when `format === 'jpeg'`; CDP ignores it for PNG. */
+    quality?: number;
+    /**
+     * `true` (default) — capture from the render surface, bypassing window
+     * compositing and avoiding the OS cursor. `false` mirrors a screen grab.
+     */
+    fromSurface?: boolean;
+    /**
+     * When `true`, capture the full scrollable area, not just the viewport.
+     * Defaults to `false` because the contract is "the visible viewport" and
+     * full-page captures are dramatically larger.
+     */
+    captureBeyondViewport?: boolean;
+}
+/**
+ * Build a `ScreenshotAdapter` that captures via CDP `Page.captureScreenshot`.
+ *
+ * The returned adapter is stateless beyond its closure: it can be called
+ * concurrently, and `dispose()` is a no-op (the transport's lifecycle is
+ * owned by the caller).
+ *
+ * @param transport Any object that can `.send('Page.captureScreenshot', …)`.
+ * @param options Factory-time defaults; `capture()` forwards them as
+ *                CDP params.
+ */
+export declare function createCDPScreenshotAdapter(transport: CDPTransport, options?: CDPScreenshotOptions): ScreenshotAdapter;
+//# sourceMappingURL=cdp.d.ts.map

package/dist/screenshot/cdp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp.d.ts","sourceRoot":"","sources":["../../src/screenshot/cdp.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1E;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC,wDAAwD;IACxD,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACxB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,YAAY,EACvB,OAAO,GAAE,oBAAyB,GACjC,iBAAiB,CAuCnB"}

package/dist/screenshot/cdp.js

@@ -0,0 +1,65 @@
+// CDP screenshot adapter — Task 1.6.
+//
+// Wraps a caller-supplied CDP transport and exposes the `ScreenshotAdapter`
+// surface. Used by P1/tracelane against the WebDriver-supplied CDP session
+// (every framework adapter — `@tracelane/wdio`, `@tracelane/playwright`,
+// `@tracelane/cypress` — converges on a `cdp(domain, command, params)` shim
+// per P1 PRD §A, and our factory talks to that shim through the
+// `CDPTransport` shape below).
+//
+// Why injection-by-parameter (rather than `import { CDP } from 'chrome-remote-interface'`):
+// it keeps the substrate environment-agnostic and lets each framework
+// reuse the CDP session it *already* has — re-attaching a second client
+// would duplicate event streams and consume a connection slot. The
+// transport is structural: anything with `.send(method, params)` returning
+// a Promise will do.
+//
+// We deliberately do not implement retry, throttling, or queueing. The
+// caller schedules captures (typically 0.2-1 Hz per ADR-0002's screenshot
+// fallback note), and a single in-flight rejection propagates verbatim.
+import { decodeBase64 } from './base64';
+/**
+ * Build a `ScreenshotAdapter` that captures via CDP `Page.captureScreenshot`.
+ *
+ * The returned adapter is stateless beyond its closure: it can be called
+ * concurrently, and `dispose()` is a no-op (the transport's lifecycle is
+ * owned by the caller).
+ *
+ * @param transport Any object that can `.send('Page.captureScreenshot', …)`.
+ * @param options Factory-time defaults; `capture()` forwards them as
+ *                CDP params.
+ */
+export function createCDPScreenshotAdapter(transport, options = {}) {
+    const format = options.format ?? 'png';
+    const fromSurface = options.fromSurface ?? true;
+    const captureBeyondViewport = options.captureBeyondViewport ?? false;
+    // `quality` is left undefined unless explicitly set — CDP rejects unknown
+    // undefineds in some language bindings, and the param is meaningful only
+    // for JPEG anyway.
+    const quality = options.quality;
+    return {
+        async capture() {
+            const params = {
+                format,
+                fromSurface,
+                captureBeyondViewport,
+            };
+            if (quality !== undefined) {
+                params.quality = quality;
+            }
+            const reply = (await transport.send('Page.captureScreenshot', params));
+            const data = reply && typeof reply === 'object' ? reply.data : undefined;
+            if (typeof data !== 'string') {
+                const got = data === undefined ? 'undefined' : typeof data;
+                throw new Error(`Page.captureScreenshot returned no base64 \`data\` field — got ${got}`);
+            }
+            return decodeBase64(data);
+        },
+        async dispose() {
+            // The transport lifecycle is owned by the caller — there is nothing
+            // for the substrate to release. The hook stays present for symmetry
+            // with adapters that *do* hold subscriptions.
+        },
+    };
+}
+//# sourceMappingURL=cdp.js.map

package/dist/screenshot/cdp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp.js","sourceRoot":"","sources":["../../src/screenshot/cdp.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,EAAE;AACF,4EAA4E;AAC5E,2EAA2E;AAC3E,yEAAyE;AACzE,4EAA4E;AAC5E,gEAAgE;AAChE,+BAA+B;AAC/B,EAAE;AACF,4FAA4F;AAC5F,sEAAsE;AACtE,wEAAwE;AACxE,mEAAmE;AACnE,2EAA2E;AAC3E,qBAAqB;AACrB,EAAE;AACF,uEAAuE;AACvE,0EAA0E;AAC1E,wEAAwE;AAExE,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAyCxC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,0BAA0B,CACxC,SAAuB,EACvB,UAAgC,EAAE;IAElC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC;IACvC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,IAAI,CAAC;IAChD,MAAM,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,IAAI,KAAK,CAAC;IACrE,0EAA0E;IAC1E,yEAAyE;IACzE,mBAAmB;IACnB,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAEhC,OAAO;QACL,KAAK,CAAC,OAAO;YACX,MAAM,MAAM,GAA4B;gBACtC,MAAM;gBACN,WAAW;gBACX,qBAAqB;aACtB,CAAC;YACF,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC;YAC3B,CAAC;YAED,MAAM,KAAK,GAAG,CAAC,MAAM,SAAS,CAAC,IAAI,CAAC,wBAAwB,EAAE,MAAM,CAAC,CAGxD,CAAC;YAEd,MAAM,IAAI,GAAG,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;YACzE,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC7B,MAAM,GAAG,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC;gBAC3D,MAAM,IAAI,KAAK,CAAC,kEAAkE,GAAG,EAAE,CAAC,CAAC;YAC3F,CAAC;YAED,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;QACD,KAAK,CAAC,OAAO;YACX,oEAAoE;YACpE,oEAAoE;YACpE,8CAA8C;QAChD,CAAC;KACF,CAAC;AACJ,CAAC"}