@cubenest/rrweb-core 0.1.0-alpha.0

package/NOTICE

@@ -0,0 +1,15 @@
+rrweb-stack
+Copyright 2026 Cubenest
+
+This product includes software developed by:
+- PostHog (https://posthog.com) — vendored rrweb fork:
+    @posthog/rrweb 0.0.34 (MIT License)
+    @posthog/rrweb-types 0.0.24 (MIT License)
+  Forked from upstream rrweb-io/rrweb 2.0.0-alpha.17.
+- rrweb-io (https://github.com/rrweb-io/rrweb) — upstream rrweb plugin:
+    @rrweb/rrweb-plugin-console-record 2.0.0-alpha.20 (MIT License)
+  Used to provide getRecordConsolePlugin because the PostHog fork at
+  0.0.34 doesn't bundle it (it shipped separately since upstream 2.x).
+
+This product is licensed under the Apache License, Version 2.0.
+See the LICENSE file for details.

package/README.md

@@ -0,0 +1,26 @@
+# @cubenest/rrweb-core
+
+Shared rrweb-based capture substrate. Used by [`tracelane`](https://github.com/Cubenest/rrweb-stack/tree/main/packages/tracelane-core) and [`peek`](https://github.com/Cubenest/rrweb-stack/tree/main/packages/peek-extension). Not generally intended for direct consumption — depend on a product package instead.
+
+## What's in here
+
+See [ADR-0002](https://github.com/Cubenest/rrweb-stack/blob/main/prds/adrs/0002-rrweb-posthog-fork-substrate.md) for the full inventory.
+
+- Vendored PostHog rrweb fork (`@posthog/rrweb@0.0.34`)
+- PII masking primitives (selectors + regex bank + body/header redaction)
+- Large-DOM throttling defaults (mutation guard, data-URL guard, single-event size cap)
+- Shadow DOM adapter
+- Screenshot fallback interface
+- Network capture abstraction (CDP and `chrome.webRequest` implementations)
+- Console capture
+- Compression helpers (`fflate`)
+- IndexedDB persistence helper
+- Compatibility matrix
+
+## Versioning
+
+Independent semver. Breaking changes are coordinated across `tracelane` and `peek` releases per [ADR-0002](https://github.com/Cubenest/rrweb-stack/blob/main/prds/adrs/0002-rrweb-posthog-fork-substrate.md).
+
+## License
+
+Apache 2.0. Vendored rrweb fork remains MIT-licensed; see NOTICE.

package/dist/compat/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A single entry in the compatibility matrix. Documents how
+ * rrweb-based capture behaves on a specific target application or
+ * page kind.
+ *
+ * Sources: PostHog's session-replay compatibility docs
+ * (https://posthog.com/docs/session-replay/troubleshooting),
+ * rrweb-io issue tracker, and our own first-party observations as
+ * they accumulate. Updates go via a Changesets PR.
+ */
+export interface CompatEntry {
+    /**
+     * Identifying URL or pattern. Doesn't need to be a real URL — can
+     * be a category like 'youtube.com' or 'github.com/*'.
+     */
+    readonly url: string;
+    /** Coarse category — pick the most representative. */
+    readonly category: 'developer-tools' | 'spa-framework' | 'rich-text-editor' | 'video-streaming' | 'canvas-webgl' | 'chat-messaging' | 'email-webmail' | 'docs-collaboration' | 'social-feed' | 'commerce' | 'auth-flow' | 'iframe-heavy' | 'pdf-viewer' | 'other';
+    /** Coarse status — set by the maintainer based on the latest evidence. */
+    readonly status: 'good' | 'caveats' | 'poor';
+    /**
+     * Short, factual description of what works / doesn't / mitigations.
+     * Keep < 240 chars per entry.
+     */
+    readonly notes: string;
+    /** Last verified date (YYYY-MM-DD). */
+    readonly lastVerified: string;
+}
+/**
+ * Seed entries — 5 known-good, 5 known-caveats/poor. Sourced from
+ * PostHog's published session-replay docs and the rrweb-io issue
+ * tracker. Each entry is defensible against external documentation;
+ * future updates go through Changesets PRs with a link to the
+ * supporting evidence.
+ */
+export declare const COMPATIBILITY_MATRIX: readonly CompatEntry[];
+//# sourceMappingURL=index.d.ts.map

package/dist/compat/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/compat/index.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EACb,iBAAiB,GACjB,eAAe,GACf,kBAAkB,GAClB,iBAAiB,GACjB,cAAc,GACd,gBAAgB,GAChB,eAAe,GACf,oBAAoB,GACpB,aAAa,GACb,UAAU,GACV,WAAW,GACX,cAAc,GACd,YAAY,GACZ,OAAO,CAAC;IACZ,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;IAC7C;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,WAAW,EAkFrD,CAAC"}

package/dist/compat/index.js

@@ -0,0 +1,97 @@
+// Compatibility matrix — Task 1.11.
+//
+// Locked surface per IMPLEMENTATION_PLAN.md Public API contract (line
+// 732):
+//
+//   export { COMPATIBILITY_MATRIX, type CompatEntry } from './compat';
+//
+// One frozen array of entries + one entry type. The TypeScript source
+// is authoritative; `packages/rrweb-core/COMPATIBILITY.md` mirrors it
+// for human readers and a drift-free test guards both stay in sync.
+//
+// ADR-0002: "A published list of target applications that are known to
+// record cleanly, record with caveats, or record poorly. Both products
+// inherit rrweb's limits; both products inherit the matrix. Updating it
+// once benefits both."
+/**
+ * Seed entries — 5 known-good, 5 known-caveats/poor. Sourced from
+ * PostHog's published session-replay docs and the rrweb-io issue
+ * tracker. Each entry is defensible against external documentation;
+ * future updates go through Changesets PRs with a link to the
+ * supporting evidence.
+ */
+export const COMPATIBILITY_MATRIX = Object.freeze([
+    // ─── Good (records cleanly) ───────────────────────────────────────
+    Object.freeze({
+        url: 'posthog.com',
+        category: 'developer-tools',
+        status: 'good',
+        notes: 'Recorded by PostHog themselves in production; canonical baseline for the fork. DOM-only, no canvas, no closed shadow roots in critical paths.',
+        lastVerified: '2026-05-26',
+    }),
+    Object.freeze({
+        url: 'github.com',
+        category: 'developer-tools',
+        status: 'good',
+        notes: 'DOM-heavy SPA, no embedded canvas/WebGL; recording captures full session including code-review UIs and PR diff views.',
+        lastVerified: '2026-05-26',
+    }),
+    Object.freeze({
+        url: 'cypress.io',
+        category: 'developer-tools',
+        status: 'good',
+        notes: 'Static marketing pages + dashboards; clean capture, no special handling required.',
+        lastVerified: '2026-05-26',
+    }),
+    Object.freeze({
+        url: 'vercel.com',
+        category: 'developer-tools',
+        status: 'good',
+        notes: 'Dashboard SPA; Next.js + RSC; clean capture, streaming HTML islands settle predictably.',
+        lastVerified: '2026-05-26',
+    }),
+    Object.freeze({
+        url: 'linear.app',
+        category: 'spa-framework',
+        status: 'good',
+        notes: "Heavy React SPA with high mutation rates; rrweb's mutation guard (10k cap) recommended to bound replay size.",
+        lastVerified: '2026-05-26',
+    }),
+    // ─── Caveats / poor (records with limits) ─────────────────────────
+    Object.freeze({
+        url: 'figma.com',
+        category: 'canvas-webgl',
+        status: 'poor',
+        notes: 'Canvas-based editor; rrweb sees the parent DOM but not the canvas contents. Use screenshot fallback for the canvas region.',
+        lastVerified: '2026-05-26',
+    }),
+    Object.freeze({
+        url: 'youtube.com',
+        category: 'video-streaming',
+        status: 'caveats',
+        notes: '<video> tags record but media playback is not part of the snapshot; replay shows poster frames + UI mutations only.',
+        lastVerified: '2026-05-26',
+    }),
+    Object.freeze({
+        url: 'gmail.com',
+        category: 'email-webmail',
+        status: 'caveats',
+        notes: 'Heavy custom elements + shadow DOM; closed shadow roots in MAIN world are unreachable. ISOLATED-world relay via chrome.dom.openOrClosedShadowRoot (peek path) closes the gap.',
+        lastVerified: '2026-05-26',
+    }),
+    Object.freeze({
+        url: 'notion.so',
+        category: 'rich-text-editor',
+        status: 'caveats',
+        notes: 'Slate-based editor with high mutation rates; rely on the mutation guard (10k cap) to avoid runaway recordings.',
+        lastVerified: '2026-05-26',
+    }),
+    Object.freeze({
+        url: 'docs.google.com',
+        category: 'docs-collaboration',
+        status: 'poor',
+        notes: 'Custom rendering layer (not real DOM text nodes); rrweb captures empty containers. Use screenshot fallback for content. Selection state not recoverable.',
+        lastVerified: '2026-05-26',
+    }),
+]);
+//# sourceMappingURL=index.js.map

package/dist/compat/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/compat/index.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,EAAE;AACF,sEAAsE;AACtE,QAAQ;AACR,EAAE;AACF,uEAAuE;AACvE,EAAE;AACF,sEAAsE;AACtE,sEAAsE;AACtE,oEAAoE;AACpE,EAAE;AACF,uEAAuE;AACvE,uEAAuE;AACvE,wEAAwE;AACxE,uBAAuB;AA6CvB;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA2B,MAAM,CAAC,MAAM,CAAC;IACxE,qEAAqE;IACrE,MAAM,CAAC,MAAM,CAAC;QACZ,GAAG,EAAE,aAAa;QAClB,QAAQ,EAAE,iBAAiB;QAC3B,MAAM,EAAE,MAAM;QACd,KAAK,EACH,+IAA+I;QACjJ,YAAY,EAAE,YAAY;KAC3B,CAAC;IACF,MAAM,CAAC,MAAM,CAAC;QACZ,GAAG,EAAE,YAAY;QACjB,QAAQ,EAAE,iBAAiB;QAC3B,MAAM,EAAE,MAAM;QACd,KAAK,EACH,uHAAuH;QACzH,YAAY,EAAE,YAAY;KAC3B,CAAC;IACF,MAAM,CAAC,MAAM,CAAC;QACZ,GAAG,EAAE,YAAY;QACjB,QAAQ,EAAE,iBAAiB;QAC3B,MAAM,EAAE,MAAM;QACd,KAAK,EAAE,mFAAmF;QAC1F,YAAY,EAAE,YAAY;KAC3B,CAAC;IACF,MAAM,CAAC,MAAM,CAAC;QACZ,GAAG,EAAE,YAAY;QACjB,QAAQ,EAAE,iBAAiB;QAC3B,MAAM,EAAE,MAAM;QACd,KAAK,EACH,yFAAyF;QAC3F,YAAY,EAAE,YAAY;KAC3B,CAAC;IACF,MAAM,CAAC,MAAM,CAAC;QACZ,GAAG,EAAE,YAAY;QACjB,QAAQ,EAAE,eAAe;QACzB,MAAM,EAAE,MAAM;QACd,KAAK,EACH,8GAA8G;QAChH,YAAY,EAAE,YAAY;KAC3B,CAAC;IACF,qEAAqE;IACrE,MAAM,CAAC,MAAM,CAAC;QACZ,GAAG,EAAE,WAAW;QAChB,QAAQ,EAAE,cAAc;QACxB,MAAM,EAAE,MAAM;QACd,KAAK,EACH,4HAA4H;QAC9H,YAAY,EAAE,YAAY;KAC3B,CAAC;IACF,MAAM,CAAC,MAAM,CAAC;QACZ,GAAG,EAAE,aAAa;QAClB,QAAQ,EAAE,iBAAiB;QAC3B,MAAM,EAAE,SAAS;QACjB,KAAK,EACH,qHAAqH;QACvH,YAAY,EAAE,YAAY;KAC3B,CAAC;IACF,MAAM,CAAC,MAAM,CAAC;QACZ,GAAG,EAAE,WAAW;QAChB,QAAQ,EAAE,eAAe;QACzB,MAAM,EAAE,SAAS;QACjB,KAAK,EACH,+KAA+K;QACjL,YAAY,EAAE,YAAY;KAC3B,CAAC;IACF,MAAM,CAAC,MAAM,CAAC;QACZ,GAAG,EAAE,WAAW;QAChB,QAAQ,EAAE,kBAAkB;QAC5B,MAAM,EAAE,SAAS;QACjB,KAAK,EACH,gHAAgH;QAClH,YAAY,EAAE,YAAY;KAC3B,CAAC;IACF,MAAM,CAAC,MAAM,CAAC;QACZ,GAAG,EAAE,iBAAiB;QACtB,QAAQ,EAAE,oBAAoB;QAC9B,MAAM,EAAE,MAAM;QACd,KAAK,EACH,0JAA0J;QAC5J,YAAY,EAAE,YAAY;KAC3B,CAAC;CACH,CAAC,CAAC"}

package/dist/compression/index.d.ts

@@ -0,0 +1,24 @@
+import type { eventWithTime } from '../rrweb';
+/**
+ * Per-batch gzip compression of an rrweb event array.
+ *
+ * Always operates on the entire array — never per-event.
+ *
+ * @param events  the rrweb event array to compress
+ * @returns gzipped bytes; suitable for base64-embedding in a self-contained
+ *          HTML report or persisting to IndexedDB
+ * @throws {TypeError} if `events` is not an array
+ */
+export declare function compress(events: eventWithTime[]): Uint8Array;
+/**
+ * Inverse of `compress`. Decompresses gzipped bytes back into the original
+ * event array.
+ *
+ * @param bytes  gzipped output from `compress`
+ * @returns the original event array
+ * @throws {TypeError} if `bytes` is not a Uint8Array, if the gzip frame is
+ *                    malformed (fflate's own error), or if the inflated
+ *                    payload does not deserialize to a JSON array
+ */
+export declare function decompress(bytes: Uint8Array): eventWithTime[];
+//# sourceMappingURL=index.d.ts.map

package/dist/compression/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/compression/index.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,UAAU,CAO5D;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,aAAa,EAAE,CAW7D"}

package/dist/compression/index.js

@@ -0,0 +1,61 @@
+// Compression helpers — Task 1.9.
+//
+// Two thin functions, backed by fflate's synchronous gzip APIs. Per ADR-0002
+// + PostHog's own guidance, the shared core does NOT register a packFn for
+// per-event compression — per-event compression is inefficient compared to
+// per-batch. These helpers always operate on an entire event array at once.
+//
+// Use cases:
+//   • Embedding a session into a self-contained HTML report (base64 the
+//     gzipped bytes, drop into a <script> tag).
+//   • Persisting batched chunks to IndexedDB before upload.
+//   • Sending batched payloads to a backend.
+//
+// Intentional non-features (YAGNI per ADR-0002):
+//   • No streaming / async APIs — synchronous gzip is fine for batch sizes
+//     we care about (under ~25 MB by report-size guard).
+//   • No options block — level=6 is fflate's default and a sane sweet spot
+//     between speed and ratio for repetitive rrweb payloads.
+//   • No custom dictionaries.
+import { gunzipSync, gzipSync, strFromU8, strToU8 } from 'fflate';
+/**
+ * Per-batch gzip compression of an rrweb event array.
+ *
+ * Always operates on the entire array — never per-event.
+ *
+ * @param events  the rrweb event array to compress
+ * @returns gzipped bytes; suitable for base64-embedding in a self-contained
+ *          HTML report or persisting to IndexedDB
+ * @throws {TypeError} if `events` is not an array
+ */
+export function compress(events) {
+    if (!Array.isArray(events)) {
+        throw new TypeError('compress: events must be an array');
+    }
+    const json = JSON.stringify(events);
+    const bytes = strToU8(json);
+    return gzipSync(bytes, { level: 6 });
+}
+/**
+ * Inverse of `compress`. Decompresses gzipped bytes back into the original
+ * event array.
+ *
+ * @param bytes  gzipped output from `compress`
+ * @returns the original event array
+ * @throws {TypeError} if `bytes` is not a Uint8Array, if the gzip frame is
+ *                    malformed (fflate's own error), or if the inflated
+ *                    payload does not deserialize to a JSON array
+ */
+export function decompress(bytes) {
+    if (!(bytes instanceof Uint8Array)) {
+        throw new TypeError('decompress: bytes must be a Uint8Array');
+    }
+    const decompressed = gunzipSync(bytes);
+    const json = strFromU8(decompressed);
+    const parsed = JSON.parse(json);
+    if (!Array.isArray(parsed)) {
+        throw new TypeError('decompress: payload did not deserialize to an array');
+    }
+    return parsed;
+}
+//# sourceMappingURL=index.js.map

package/dist/compression/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/compression/index.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,2EAA2E;AAC3E,4EAA4E;AAC5E,EAAE;AACF,aAAa;AACb,wEAAwE;AACxE,gDAAgD;AAChD,4DAA4D;AAC5D,6CAA6C;AAC7C,EAAE;AACF,iDAAiD;AACjD,2EAA2E;AAC3E,yDAAyD;AACzD,2EAA2E;AAC3E,6DAA6D;AAC7D,8BAA8B;AAE9B,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAGlE;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAuB;IAC9C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,SAAS,CAAC,mCAAmC,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACpC,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,OAAO,QAAQ,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CAAC,KAAiB;IAC1C,IAAI,CAAC,CAAC,KAAK,YAAY,UAAU,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,SAAS,CAAC,wCAAwC,CAAC,CAAC;IAChE,CAAC;IACD,MAAM,YAAY,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,SAAS,CAAC,YAAY,CAAC,CAAC;IACrC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,SAAS,CAAC,qDAAqD,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,MAAyB,CAAC;AACnC,CAAC"}

package/dist/console/buffer.d.ts

@@ -0,0 +1,99 @@
+import { getRecordConsolePlugin } from '../rrweb';
+import type { eventWithTime } from '../rrweb';
+import type { ConsoleEvent, ConsoleLevel } from './types';
+/**
+ * Factory-time configuration for `createConsoleCaptureBuffer`.
+ */
+export interface ConsoleCaptureOptions {
+    /**
+     * Console levels to capture. When omitted, the plugin's default level
+     * list is used (the full 19-level vocabulary documented on `ConsoleLevel`).
+     * Most consumers will narrow this to the `BasicConsoleLevel` quartet.
+     */
+    level?: ConsoleLevel[];
+    /**
+     * Max number of plugin-side log records before the plugin emits a
+     * single threshold warning and stops invoking the callback. Forwarded
+     * to the plugin verbatim — this is NOT the same as `maxBuffered` (which
+     * is OUR ring-buffer cap, applied after the plugin emits).
+     * Default: 10_000.
+     */
+    lengthThreshold?: number;
+    /**
+     * Serializer knobs forwarded to the plugin's `stringify` step. Defaults
+     * favor short, shallow output — long string clip at 1000 chars, object
+     * keys clip at 100, depth clips at 1.
+     */
+    stringifyOptions?: {
+        stringLengthLimit?: number;
+        numOfKeysLimit?: number;
+        depthOfLimit?: number;
+    };
+    /**
+     * Max number of `ConsoleEvent`s retained in the buffer. When `push()`
+     * would push beyond this cap, the OLDEST entries are dropped (FIFO).
+     * Default: 5000.
+     */
+    maxBuffered?: number;
+}
+/**
+ * The public buffer surface. Consumers register `plugin` with the rrweb
+ * recorder AND forward every emitted rrweb event into `push()`:
+ *
+ *   const buf = createConsoleCaptureBuffer();
+ *   record({
+ *     emit: (event) => { buf.push(event); ...your other sinks... },
+ *     plugins: [buf.plugin],
+ *   });
+ *
+ * The split (plugin registration ↔ event forwarding) is intentional:
+ * rrweb owns the recording lifecycle, we own the normalized buffer.
+ */
+export interface ConsoleCaptureBuffer {
+    /**
+     * The rrweb plugin instance to pass into `record({ plugins: [...] })`.
+     * Same shape as a direct `getRecordConsolePlugin(...)` call — the buffer
+     * wrapper does not re-shape it.
+     */
+    readonly plugin: ReturnType<typeof getRecordConsolePlugin>;
+    /**
+     * Feed an rrweb event into the buffer. Events of type
+     * `EventType.Plugin` (6) with `data.plugin === 'rrweb/console@1'` are
+     * normalized into `ConsoleEvent` and pushed onto the ring buffer; all
+     * other events are silently ignored (this method is safe to wire
+     * unconditionally inside the rrweb `emit` callback).
+     *
+     * Malformed plugin events (missing fields, wrong types) are silently
+     * dropped — see "Recursion guard" in the module header for why we
+     * never throw or log from this path.
+     */
+    push(event: eventWithTime): void;
+    /**
+     * Returns and EMPTIES the buffer. Used by P1 on test-fail to ship the
+     * captured console alongside the rrweb event stream, and by P2 on MCP
+     * tool invocation to surface recent logs to the model.
+     */
+    drain(): ConsoleEvent[];
+    /**
+     * Returns a read-only snapshot of the buffer WITHOUT emptying it. Used
+     * by surfaces that want to render the current state without disturbing
+     * the buffer (e.g. live debug overlays).
+     */
+    peek(): readonly ConsoleEvent[];
+    /**
+     * Current number of `ConsoleEvent`s retained in the buffer.
+     */
+    size(): number;
+}
+/**
+ * Create a console capture buffer.
+ *
+ * The returned `plugin` field is the rrweb plugin instance — consumers
+ * pass it into `record({ plugins: [...] })`. The returned `push`/`drain`/
+ * `peek`/`size` methods operate on the bounded ring buffer.
+ *
+ * @see ConsoleCaptureOptions for tuning knobs.
+ * @see ConsoleCaptureBuffer for the runtime API.
+ */
+export declare function createConsoleCaptureBuffer(options?: ConsoleCaptureOptions): ConsoleCaptureBuffer;
+//# sourceMappingURL=buffer.d.ts.map

package/dist/console/buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer.d.ts","sourceRoot":"","sources":["../../src/console/buffer.ts"],"names":[],"mappings":"AA8CA,OAAO,EAAa,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AA+B1D;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE;QACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;IACF;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC;IAC3D;;;;;;;;;;OAUG;IACH,IAAI,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IACjC;;;;OAIG;IACH,KAAK,IAAI,YAAY,EAAE,CAAC;IACxB;;;;OAIG;IACH,IAAI,IAAI,SAAS,YAAY,EAAE,CAAC;IAChC;;OAEG;IACH,IAAI,IAAI,MAAM,CAAC;CAChB;AAyBD;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAuEtB"}

package/dist/console/buffer.js

@@ -0,0 +1,169 @@
+// Console capture buffer — Task 1.8.
+//
+// Wraps the upstream `@rrweb/rrweb-plugin-console-record` (re-exported via
+// `../rrweb` per Task 1.2) with two concerns the plugin doesn't own:
+//
+//   1. A bounded in-memory buffer that consumers can `drain()` on demand
+//      (P1: dump-on-fail; P2: dump-on-MCP-tool-call). The plugin only
+//      emits events into rrweb's event stream — it doesn't buffer them
+//      itself.
+//
+//   2. A normalized event shape (`ConsoleEvent`) that hides the awkward
+//      double-`payload` naming in the raw rrweb plugin event
+//      (`event.data.payload.payload` is the args array).
+//
+// The plugin's emitted shape, verified against
+// `@rrweb/rrweb-plugin-console-record@2.0.0-alpha.20`'s `dist/index.d.ts`
+// and source (`initLogObserver` → `cb({ level, trace, payload })` →
+// rrweb's `wrappedEmit({ type: 6, data: { plugin: 'rrweb/console@1',
+// payload: <LogData> } })`), is:
+//
+//   {
+//     type: 6 /* EventType.Plugin */,
+//     timestamp: number,
+//     data: {
+//       plugin: 'rrweb/console@1',
+//       payload: {
+//         level: LogLevel,
+//         trace: string[],
+//         payload: string[]  /* the stringified args */
+//       }
+//     }
+//   }
+//
+// ── Recursion guard ────────────────────────────────────────────────────────
+// The plugin patches `console.*` to call `cb(…)` AFTER invoking the
+// original. If our buffer code itself called `console.*`, that would
+// re-enter the patch and emit a synthetic event for every event we
+// process — fast path to infinite recursion (the plugin has its own
+// `inStack` guard but we should not rely on it, since we sit OUTSIDE
+// the plugin in the rrweb event pipeline).
+//
+// Therefore: no `console.*` calls from this module. If `push()` sees a
+// malformed plugin event (wrong shape, missing fields), it silently
+// ignores it — better to lose one buggy event than risk a recursive
+// flood from a defensive log line. Tests cover this contract.
+import { EventType, getRecordConsolePlugin } from '../rrweb';
+/** Vendor's plugin name string — emitted as `event.data.plugin`. */
+const CONSOLE_PLUGIN_NAME = 'rrweb/console@1';
+/** Default cap on retained events before FIFO eviction kicks in. */
+const DEFAULT_MAX_BUFFERED = 5000;
+/** Default per-argument string truncation cap (matches plugin default). */
+const DEFAULT_STRING_LENGTH_LIMIT = 1000;
+/** Default object-key count cap when serializing arguments. */
+const DEFAULT_NUM_OF_KEYS_LIMIT = 100;
+/**
+ * Default object-graph depth limit. Kept SHALLOW (1) because console.log
+ * is often called with whole DOM nodes or huge state objects, and a
+ * deeper serializer would inflate event size into the multi-MB range.
+ * Consumers that actually want deep object dumps can override.
+ */
+const DEFAULT_DEPTH_OF_LIMIT = 1;
+/**
+ * Default plugin-level event cap (the plugin has its own `lengthThreshold`
+ * that emits a warning + stops calling cb once exceeded — defaults to 1000
+ * in the plugin, but we raise it slightly so the plugin's own cap doesn't
+ * bite before our buffer cap does. Set to 10_000 to match what the plan
+ * documents as the per-event size budget across the substrate.
+ */
+const DEFAULT_LENGTH_THRESHOLD = 10_000;
+/**
+ * Type guard for the structural shape of a console-plugin event's payload.
+ * Returns true ONLY when `value` matches the LogData contract:
+ * `{ level: string, trace: string[], payload: string[] }`. Anything else
+ * is treated as malformed and dropped by `push()`.
+ */
+function isConsoleLogData(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const candidate = value;
+    if (typeof candidate.level !== 'string')
+        return false;
+    if (!Array.isArray(candidate.trace))
+        return false;
+    if (!Array.isArray(candidate.payload))
+        return false;
+    // All trace + payload entries must be strings (plugin enforces this; we
+    // double-check to keep the consumer-facing shape strict).
+    for (const t of candidate.trace)
+        if (typeof t !== 'string')
+            return false;
+    for (const p of candidate.payload)
+        if (typeof p !== 'string')
+            return false;
+    return true;
+}
+/**
+ * Create a console capture buffer.
+ *
+ * The returned `plugin` field is the rrweb plugin instance — consumers
+ * pass it into `record({ plugins: [...] })`. The returned `push`/`drain`/
+ * `peek`/`size` methods operate on the bounded ring buffer.
+ *
+ * @see ConsoleCaptureOptions for tuning knobs.
+ * @see ConsoleCaptureBuffer for the runtime API.
+ */
+export function createConsoleCaptureBuffer(options = {}) {
+    const maxBuffered = options.maxBuffered ?? DEFAULT_MAX_BUFFERED;
+    const stringifyOptions = {
+        stringLengthLimit: options.stringifyOptions?.stringLengthLimit ?? DEFAULT_STRING_LENGTH_LIMIT,
+        numOfKeysLimit: options.stringifyOptions?.numOfKeysLimit ?? DEFAULT_NUM_OF_KEYS_LIMIT,
+        depthOfLimit: options.stringifyOptions?.depthOfLimit ?? DEFAULT_DEPTH_OF_LIMIT,
+    };
+    // Build the plugin. Only forward `level` when the caller specified it —
+    // otherwise the plugin's own default-level list applies (the full 19-
+    // level vocabulary), which is what consumers usually want.
+    const plugin = getRecordConsolePlugin({
+        ...(options.level !== undefined ? { level: options.level } : {}),
+        lengthThreshold: options.lengthThreshold ?? DEFAULT_LENGTH_THRESHOLD,
+        stringifyOptions,
+    });
+    // Ring buffer. We use a plain array + shift() for eviction; for the
+    // sizes we expect (single-digit thousands), the O(n) shift is fine and
+    // the code is dramatically simpler than a circular index.
+    const buffer = [];
+    function push(event) {
+        // Filter: only plugin events from the console-record plugin reach the
+        // buffer. Everything else (DOM mutations, mouse moves, snapshots) is
+        // ignored — consumers can forward the full event stream into push()
+        // without filtering upstream.
+        if (event.type !== EventType.Plugin)
+            return;
+        const data = event.data;
+        if (data === null || typeof data !== 'object')
+            return;
+        const { plugin: pluginName, payload } = data;
+        if (pluginName !== CONSOLE_PLUGIN_NAME)
+            return;
+        if (!isConsoleLogData(payload))
+            return;
+        // Normalize: drop trace if empty (no signal in an empty array), and
+        // freeze the args array so consumers can't mutate buffered state.
+        const normalized = {
+            ts: event.timestamp,
+            level: payload.level,
+            args: [...payload.payload],
+            ...(payload.trace.length > 0 ? { trace: [...payload.trace] } : {}),
+        };
+        buffer.push(normalized);
+        // FIFO eviction. The buffer can be over capacity by exactly one entry
+        // after push, so a single shift suffices — but keep the loop in case
+        // a future caller mutates maxBuffered downward at runtime.
+        while (buffer.length > maxBuffered) {
+            buffer.shift();
+        }
+    }
+    function drain() {
+        const out = buffer.slice();
+        buffer.length = 0;
+        return out;
+    }
+    function peek() {
+        return buffer.slice();
+    }
+    function size() {
+        return buffer.length;
+    }
+    return { plugin, push, drain, peek, size };
+}
+//# sourceMappingURL=buffer.js.map

package/dist/console/buffer.js.map

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

package/dist/console/index.d.ts

@@ -0,0 +1,3 @@
+export { createConsoleCaptureBuffer, type ConsoleCaptureBuffer, type ConsoleCaptureOptions, } from './buffer';
+export type { BasicConsoleLevel, ConsoleEvent, ConsoleLevel } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/console/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/console/index.ts"],"names":[],"mappings":"AAeA,OAAO,EACL,0BAA0B,EAC1B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC"}

package/dist/console/index.js

@@ -0,0 +1,16 @@
+// Public barrel for the console capture module.
+//
+// Locked surface per IMPLEMENTATION_PLAN.md Public API contract (line 703):
+//
+//   export { createConsoleCaptureBuffer, type ConsoleEvent } from './console';
+//
+// The factory + companion option/buffer types are re-exported so consumers
+// can declare-and-pass without reaching into `./buffer` directly.
+//
+// `getRecordConsolePlugin` is intentionally NOT re-exported from this
+// barrel — it's already exported from the package-level `./rrweb` barrel
+// (Task 1.2's wiring), and a second re-export would create two import
+// paths for the same symbol. Consumers who want the raw plugin import it
+// from `@cubenest/rrweb-core`.
+export { createConsoleCaptureBuffer, } from './buffer';
+//# sourceMappingURL=index.js.map

package/dist/console/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/console/index.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,EAAE;AACF,4EAA4E;AAC5E,EAAE;AACF,+EAA+E;AAC/E,EAAE;AACF,2EAA2E;AAC3E,kEAAkE;AAClE,EAAE;AACF,sEAAsE;AACtE,yEAAyE;AACzE,sEAAsE;AACtE,yEAAyE;AACzE,+BAA+B;AAE/B,OAAO,EACL,0BAA0B,GAG3B,MAAM,UAAU,CAAC"}