@cubenest/rrweb-core 0.1.0-alpha.0

package/dist/screenshot/index.d.ts

@@ -0,0 +1,4 @@
+export type { ScreenshotAdapter } from './types';
+export { createCDPScreenshotAdapter, type CDPTransport, type CDPScreenshotOptions, } from './cdp';
+export { createTabsScreenshotAdapter, type CaptureVisibleTabFn, type TabsScreenshotOptions, } from './tabs';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/screenshot/index.ts"],"names":[],"mappings":"AAQA,YAAY,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EACL,0BAA0B,EAC1B,KAAK,YAAY,EACjB,KAAK,oBAAoB,GAC1B,MAAM,OAAO,CAAC;AACf,OAAO,EACL,2BAA2B,EAC3B,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,GAC3B,MAAM,QAAQ,CAAC"}

package/dist/screenshot/index.js

@@ -0,0 +1,10 @@
+// Public barrel for the screenshot fallback module.
+//
+// Locked surface per IMPLEMENTATION_PLAN.md Public API contract (lines
+// 721-723): one type (`ScreenshotAdapter`) and two factories
+// (`createCDPScreenshotAdapter`, `createTabsScreenshotAdapter`). The
+// transport-shape and option types are re-exported so consumers can
+// declare-and-pass without importing internal paths.
+export { createCDPScreenshotAdapter, } from './cdp';
+export { createTabsScreenshotAdapter, } from './tabs';
+//# sourceMappingURL=index.js.map

package/dist/screenshot/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/screenshot/index.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,EAAE;AACF,uEAAuE;AACvE,6DAA6D;AAC7D,qEAAqE;AACrE,oEAAoE;AACpE,qDAAqD;AAGrD,OAAO,EACL,0BAA0B,GAG3B,MAAM,OAAO,CAAC;AACf,OAAO,EACL,2BAA2B,GAG5B,MAAM,QAAQ,CAAC"}

package/dist/screenshot/tabs.d.ts

@@ -0,0 +1,44 @@
+import type { ScreenshotAdapter } from './types';
+/**
+ * Structural shape of `chrome.tabs.captureVisibleTab`. The Chrome API
+ * resolves to a `data:image/<fmt>;base64,...` URL (or an empty string on
+ * failure in older Chromium builds — handled below).
+ *
+ * The argument order matches the Chrome API: `(windowId?, options?)`.
+ * Passing `undefined` for `windowId` selects the current window.
+ */
+export type CaptureVisibleTabFn = (windowId?: number, options?: {
+    format?: 'png' | 'jpeg';
+    quality?: number;
+}) => Promise<string>;
+/**
+ * Factory-time options for the tabs screenshot adapter. `windowId` is
+ * passed through verbatim; `format` and `quality` are forwarded to the
+ * Chrome API's `options` bag.
+ */
+export interface TabsScreenshotOptions {
+    /**
+     * The browser window to capture from. Defaults to `undefined`, which the
+     * Chrome API interprets as "the currently focused window".
+     */
+    windowId?: number;
+    /** PNG (default) or JPEG. */
+    format?: 'png' | 'jpeg';
+    /** 0-100. JPEG only; Chrome ignores it for PNG. */
+    quality?: number;
+}
+/**
+ * Build a `ScreenshotAdapter` that captures via `chrome.tabs.captureVisibleTab`.
+ *
+ * The factory takes the `captureVisibleTab` reference as a parameter so the
+ * substrate is not coupled to the `chrome.*` namespace — pass
+ * `chrome.tabs.captureVisibleTab.bind(chrome.tabs)` from the extension
+ * service worker.
+ *
+ * The returned adapter is stateless; `dispose()` is a no-op.
+ *
+ * @param captureVisibleTab A function with the `chrome.tabs.captureVisibleTab` shape.
+ * @param options Factory-time defaults.
+ */
+export declare function createTabsScreenshotAdapter(captureVisibleTab: CaptureVisibleTabFn, options?: TabsScreenshotOptions): ScreenshotAdapter;
+//# sourceMappingURL=tabs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tabs.d.ts","sourceRoot":"","sources":["../../src/screenshot/tabs.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAChC,QAAQ,CAAC,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,KACpD,OAAO,CAAC,MAAM,CAAC,CAAC;AAErB;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6BAA6B;IAC7B,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACxB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,2BAA2B,CACzC,iBAAiB,EAAE,mBAAmB,EACtC,OAAO,GAAE,qBAA0B,GAClC,iBAAiB,CAqCnB"}

package/dist/screenshot/tabs.js

@@ -0,0 +1,63 @@
+// chrome.tabs.captureVisibleTab adapter — Task 1.6.
+//
+// Used by P2/peek from the extension service worker. The MV3 service worker
+// has access to `chrome.tabs.captureVisibleTab(windowId?, options?)`, which
+// returns a `data:image/<fmt>;base64,...` URL. We accept the function as a
+// parameter rather than reading `chrome.tabs` off a global so the substrate
+// stays environment-agnostic and trivially testable.
+//
+// The function's argument ergonomics (windowId first, options second) match
+// the Chrome API exactly — when no windowId is configured the factory
+// passes `undefined`, mirroring `chrome.tabs.captureVisibleTab(undefined, opts)`,
+// which the API treats as "the current window".
+//
+// Why not just `globalThis.chrome?.tabs?.captureVisibleTab`: (1) we want
+// the substrate to typecheck and bundle outside an extension context;
+// (2) callers often want to wrap the call with permission checks or
+// telemetry; (3) tests stay synchronous-fixture-friendly.
+import { decodeBase64 } from './base64';
+/**
+ * Build a `ScreenshotAdapter` that captures via `chrome.tabs.captureVisibleTab`.
+ *
+ * The factory takes the `captureVisibleTab` reference as a parameter so the
+ * substrate is not coupled to the `chrome.*` namespace — pass
+ * `chrome.tabs.captureVisibleTab.bind(chrome.tabs)` from the extension
+ * service worker.
+ *
+ * The returned adapter is stateless; `dispose()` is a no-op.
+ *
+ * @param captureVisibleTab A function with the `chrome.tabs.captureVisibleTab` shape.
+ * @param options Factory-time defaults.
+ */
+export function createTabsScreenshotAdapter(captureVisibleTab, options = {}) {
+    const windowId = options.windowId;
+    const format = options.format ?? 'png';
+    const quality = options.quality;
+    return {
+        async capture() {
+            const tabOptions = { format };
+            if (quality !== undefined) {
+                tabOptions.quality = quality;
+            }
+            const dataUrl = await captureVisibleTab(windowId, tabOptions);
+            if (typeof dataUrl !== 'string' || dataUrl.length === 0) {
+                // Chrome historically resolved with an empty string on permission
+                // failures rather than rejecting; surface that as a useful error.
+                throw new Error('chrome.tabs.captureVisibleTab returned an empty result');
+            }
+            // Expected shape: `data:image/png;base64,AAAA…` — but we accept any
+            // mime-type, only the `;base64,` segment matters for decoding.
+            const marker = ';base64,';
+            const idx = dataUrl.indexOf(marker);
+            if (idx === -1) {
+                throw new Error('captureVisibleTab result is not a base64-encoded data URL (missing `;base64,` segment)');
+            }
+            const payload = dataUrl.slice(idx + marker.length);
+            return decodeBase64(payload);
+        },
+        async dispose() {
+            // No listeners or session state to release.
+        },
+    };
+}
+//# sourceMappingURL=tabs.js.map

package/dist/screenshot/tabs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tabs.js","sourceRoot":"","sources":["../../src/screenshot/tabs.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,EAAE;AACF,4EAA4E;AAC5E,4EAA4E;AAC5E,2EAA2E;AAC3E,4EAA4E;AAC5E,qDAAqD;AACrD,EAAE;AACF,4EAA4E;AAC5E,sEAAsE;AACtE,kFAAkF;AAClF,gDAAgD;AAChD,EAAE;AACF,yEAAyE;AACzE,sEAAsE;AACtE,oEAAoE;AACpE,0DAA0D;AAE1D,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAiCxC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,2BAA2B,CACzC,iBAAsC,EACtC,UAAiC,EAAE;IAEnC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAClC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC;IACvC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAEhC,OAAO;QACL,KAAK,CAAC,OAAO;YACX,MAAM,UAAU,GAAiD,EAAE,MAAM,EAAE,CAAC;YAC5E,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,UAAU,CAAC,OAAO,GAAG,OAAO,CAAC;YAC/B,CAAC;YAED,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;YAE9D,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACxD,kEAAkE;gBAClE,kEAAkE;gBAClE,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;YAC5E,CAAC;YAED,oEAAoE;YACpE,+DAA+D;YAC/D,MAAM,MAAM,GAAG,UAAU,CAAC;YAC1B,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACpC,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;gBACf,MAAM,IAAI,KAAK,CACb,wFAAwF,CACzF,CAAC;YACJ,CAAC;YAED,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;YACnD,OAAO,YAAY,CAAC,OAAO,CAAC,CAAC;QAC/B,CAAC;QACD,KAAK,CAAC,OAAO;YACX,4CAA4C;QAC9C,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/screenshot/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Capture the visible viewport as PNG (or JPEG, if the factory was
+ * configured with `format: 'jpeg'`) bytes.
+ *
+ * The bytes are the raw image payload — callers can persist directly, embed
+ * via `data:image/<fmt>;base64,...` URLs, or stream into a video assembler.
+ * No framing, no envelope.
+ */
+export interface ScreenshotAdapter {
+    /**
+     * Capture the visible viewport. Resolves to a Uint8Array of image bytes
+     * in the format configured at factory time (PNG by default).
+     *
+     * Rejections propagate the transport error verbatim — the substrate does
+     * not retry, throttle, or wrap. The caller decides whether a missed
+     * frame is recoverable.
+     */
+    capture(): Promise<Uint8Array>;
+    /**
+     * Optional cleanup hook. The reference adapters resolve immediately — the
+     * field exists so product-specific adapters that *do* hold listeners
+     * (e.g. a long-lived CDP event subscription) can be torn down without a
+     * contract change.
+     */
+    dispose?(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/screenshot/types.ts"],"names":[],"mappings":"AAiBA;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;OAOG;IACH,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAE/B;;;;;OAKG;IACH,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B"}

package/dist/screenshot/types.js

@@ -0,0 +1,18 @@
+// Screenshot fallback interface — Task 1.6.
+//
+// ADR-0002: when rrweb misbehaves on hard sites (canvas/webgl heavy, hostile
+// CSS, very large DOMs throttled out of full-fidelity capture), a periodic
+// screenshot keeps the recording useful for triage. Both products consume
+// the same `ScreenshotAdapter` contract; the transport differs:
+//
+//   - P1/tracelane → CDP `Page.captureScreenshot` via a WebDriver-supplied
+//     CDP session (see `createCDPScreenshotAdapter`).
+//   - P2/peek     → `chrome.tabs.captureVisibleTab` from the extension
+//     service worker (see `createTabsScreenshotAdapter`).
+//
+// The substrate stays environment-agnostic by injecting the transport as a
+// parameter rather than importing `chrome.*` or any CDP client library.
+// Tests at this layer cover the contract; real-environment integration
+// tests live in the product packages.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/screenshot/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/screenshot/types.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,0EAA0E;AAC1E,gEAAgE;AAChE,EAAE;AACF,2EAA2E;AAC3E,sDAAsD;AACtD,uEAAuE;AACvE,0DAA0D;AAC1D,EAAE;AACF,2EAA2E;AAC3E,wEAAwE;AACxE,uEAAuE;AACvE,sCAAsC"}

package/dist/shadow-dom/index.d.ts

@@ -0,0 +1,3 @@
+export { traverseShadowRoots } from './traverse';
+export type { ShadowRootInfo } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/shadow-dom/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/shadow-dom/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC"}

package/dist/shadow-dom/index.js

@@ -0,0 +1,8 @@
+// Public barrel for the shadow-DOM module.
+//
+// Locked surface per IMPLEMENTATION_PLAN.md Public API contract (lines
+// 715-716): the `traverseShadowRoots` function plus the `ShadowRootInfo`
+// type. The traversal options interface stays internal — callers pass an
+// inline object literal and TS infers the shape.
+export { traverseShadowRoots } from './traverse';
+//# sourceMappingURL=index.js.map

package/dist/shadow-dom/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/shadow-dom/index.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,EAAE;AACF,uEAAuE;AACvE,yEAAyE;AACzE,yEAAyE;AACzE,iDAAiD;AAEjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC"}

package/dist/shadow-dom/traverse.d.ts

@@ -0,0 +1,54 @@
+import type { ShadowRootInfo } from './types';
+export interface TraverseShadowRootsOptions {
+    /**
+     * Maximum shadow-root nesting depth to recurse into. Defaults to 16.
+     * Hosts at exactly `maxDepth - 1` are recorded; their shadow contents
+     * are not recursed into.
+     */
+    maxDepth?: number;
+    /**
+     * Called once for every host we detected but could not reach into. Fires
+     * for both the closed-shadow-root MAIN-world case and the custom-element
+     * heuristic. Throws are swallowed so a noisy consumer can't break the
+     * walk.
+     */
+    onUnreachable?: (host: Element) => void;
+    /**
+     * When `true`, the walker will call `openOrClosedShadowRoot` (if
+     * provided) to try to reach closed shadow roots. Defaults to `false` —
+     * MAIN-world callers should leave this off; ISOLATED-world content
+     * scripts that have wired `chrome.dom.openOrClosedShadowRoot` should
+     * pass `true`.
+     */
+    includeClosed?: boolean;
+    /**
+     * Caller-injected helper, intended to be
+     * `chrome.dom.openOrClosedShadowRoot` in an ISOLATED-world content
+     * script. Returning `null`/`undefined` is interpreted as "no shadow
+     * root on this element"; returning a `ShadowRoot` is interpreted as
+     * "this element has a (probably closed) shadow root, here it is."
+     *
+     * Only consulted when `includeClosed === true`.
+     */
+    openOrClosedShadowRoot?: (el: Element) => ShadowRoot | null | undefined;
+}
+/**
+ * Walk the DOM from `root` and return every shadow host found.
+ *
+ * Open shadow roots are resolved via `el.shadowRoot`. Closed shadow roots
+ * are only reachable if the caller injects `openOrClosedShadowRoot` AND
+ * passes `includeClosed: true` — typically a content script forwarding
+ * `chrome.dom.openOrClosedShadowRoot` from an ISOLATED world. In MAIN
+ * world, closed shadow hosts are recorded as `'unreachable'`; browser
+ * encapsulation is respected (we do NOT reflect-hack into closed shadows).
+ *
+ * Does not descend into iframes — `iframe.contentDocument` is usually
+ * cross-origin and rrweb has its own iframe recording pathway.
+ *
+ * @param root    Document, fragment, or element to walk.
+ * @param options See {@link TraverseShadowRootsOptions}.
+ * @returns A flat array of `ShadowRootInfo`, ordered by traversal (DFS
+ *          pre-order). Each host appears at most once.
+ */
+export declare function traverseShadowRoots(root: Document | DocumentFragment | Element, options?: TraverseShadowRootsOptions): ShadowRootInfo[];
+//# sourceMappingURL=traverse.d.ts.map

package/dist/shadow-dom/traverse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traverse.d.ts","sourceRoot":"","sources":["../../src/shadow-dom/traverse.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAK9C,MAAM,WAAW,0BAA0B;IACzC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IACxC;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;;OAQG;IACH,sBAAsB,CAAC,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC;CACzE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,QAAQ,GAAG,gBAAgB,GAAG,OAAO,EAC3C,OAAO,GAAE,0BAA+B,GACvC,cAAc,EAAE,CA+ClB"}

package/dist/shadow-dom/traverse.js

@@ -0,0 +1,209 @@
+// Shadow DOM walker — Task 1.5.
+//
+// Walks the DOM from a given root and reports every shadow host it finds.
+// Pure enumeration — does NOT serialize shadow contents, does NOT subscribe
+// to mutations. rrweb does that elsewhere; we just answer "where are the
+// hosts and what can we see through them?".
+//
+// Why this exists despite the PostHog fork already handling shadow hosts:
+// ADR-0002 calls it "a thin wrapper around the PostHog fork's shadow-host
+// handling that closes known gaps in custom-element traversal and documents
+// the gaps that remain." The fork's logic is internal; we re-implement at
+// this layer so consumers have a stable surface (`ShadowRootInfo[]`) and a
+// single seam to inject the ISOLATED-world `chrome.dom.openOrClosedShadowRoot`
+// helper from a content script.
+//
+// Closed shadow roots in MAIN world: the browser intentionally hides
+// `el.shadowRoot` for `attachShadow({mode:'closed'})`. We respect that —
+// no reflect-hacking, no Proxy tricks. Such hosts land on the
+// `'unreachable'` path and (if the caller wired one) fire
+// `options.onUnreachable(el)` so the consumer can log/breadcrumb.
+//
+// We do NOT traverse into `iframe.contentDocument`. In real usage iframes
+// are very often cross-origin, where `contentDocument` access throws. Even
+// when same-origin, iframes have independent recording semantics in rrweb
+// and should be handled by the recorder's `recordCrossOriginIframes`
+// pathway, not by us.
+/** Default `maxDepth` — pathological apps have been observed nesting ~8 deep. */
+const DEFAULT_MAX_DEPTH = 16;
+/**
+ * Walk the DOM from `root` and return every shadow host found.
+ *
+ * Open shadow roots are resolved via `el.shadowRoot`. Closed shadow roots
+ * are only reachable if the caller injects `openOrClosedShadowRoot` AND
+ * passes `includeClosed: true` — typically a content script forwarding
+ * `chrome.dom.openOrClosedShadowRoot` from an ISOLATED world. In MAIN
+ * world, closed shadow hosts are recorded as `'unreachable'`; browser
+ * encapsulation is respected (we do NOT reflect-hack into closed shadows).
+ *
+ * Does not descend into iframes — `iframe.contentDocument` is usually
+ * cross-origin and rrweb has its own iframe recording pathway.
+ *
+ * @param root    Document, fragment, or element to walk.
+ * @param options See {@link TraverseShadowRootsOptions}.
+ * @returns A flat array of `ShadowRootInfo`, ordered by traversal (DFS
+ *          pre-order). Each host appears at most once.
+ */
+export function traverseShadowRoots(root, options = {}) {
+    const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const includeClosed = options.includeClosed ?? false;
+    const openOrClosed = options.openOrClosedShadowRoot;
+    const onUnreachable = options.onUnreachable;
+    const seen = new Set();
+    const results = [];
+    // Avoid recursion to keep stack depth bounded for pathological nesting.
+    // The work list carries (subtree-root, depth) — depth is the depth the
+    // hosts inside that subtree-root will land at.
+    const work = [
+        { subtree: root, depth: 0 },
+    ];
+    while (work.length > 0) {
+        const item = work.shift();
+        if (!item)
+            break;
+        const { subtree, depth } = item;
+        if (depth >= maxDepth)
+            continue;
+        for (const el of iterDescendantElements(subtree)) {
+            if (seen.has(el))
+                continue;
+            const info = resolveHost(el, depth, includeClosed, openOrClosed);
+            if (!info)
+                continue;
+            seen.add(el);
+            results.push(info);
+            if (info.source === 'unreachable') {
+                if (onUnreachable) {
+                    try {
+                        onUnreachable(el);
+                    }
+                    catch {
+                        // Consumer callback errors must not abort the walk.
+                    }
+                }
+            }
+            else if (info.root) {
+                // Queue the shadow root for traversal; nested hosts land at depth+1.
+                work.push({ subtree: info.root, depth: depth + 1 });
+            }
+        }
+    }
+    return results;
+}
+/**
+ * Resolve a single element into a `ShadowRootInfo`, or `null` if it isn't a
+ * shadow host. Implements the per-host resolution algorithm from
+ * IMPLEMENTATION_PLAN.md Task 1.5.
+ */
+function resolveHost(el, depth, includeClosed, openOrClosed) {
+    // Step 1: open shadow root via the standard reflection.
+    const openRoot = el.shadowRoot;
+    if (openRoot) {
+        return {
+            host: el,
+            root: openRoot,
+            mode: 'open',
+            source: 'attachShadow',
+            depth,
+        };
+    }
+    // Step 2: caller-provided helper (chrome.dom.openOrClosedShadowRoot).
+    if (includeClosed && openOrClosed) {
+        let injectedRoot;
+        try {
+            injectedRoot = openOrClosed(el);
+        }
+        catch {
+            // The helper may throw on detached nodes etc; treat as "no root".
+            injectedRoot = null;
+        }
+        if (injectedRoot) {
+            return {
+                host: el,
+                root: injectedRoot,
+                mode: 'closed',
+                source: 'chrome.dom',
+                depth,
+            };
+        }
+    }
+    // Step 3: best-effort heuristic — a custom element (tag name contains a
+    // hyphen) with no light-DOM children is *probably* a closed shadow host.
+    // This is intentionally permissive; the consumer's `onUnreachable`
+    // callback exists precisely so callers can downgrade these reports if
+    // they have richer information. See ADR-0002 — "closes known gaps in
+    // custom-element traversal and documents the gaps that remain."
+    if (isLikelyClosedCustomElementHost(el)) {
+        return {
+            host: el,
+            root: null,
+            mode: 'unknown',
+            source: 'unreachable',
+            depth,
+        };
+    }
+    // Step 4: not a shadow host.
+    return null;
+}
+/**
+ * Cheap heuristic: an element is "probably a closed shadow host" if its
+ * tag name contains a hyphen (Custom Elements v1 requirement) and it has
+ * no child nodes in the light DOM. False positives are intentional — the
+ * consumer's `onUnreachable` is the escape hatch.
+ */
+function isLikelyClosedCustomElementHost(el) {
+    const tag = el.tagName;
+    if (!tag)
+        return false;
+    // Built-ins like `<div>`/`<span>` have no hyphen. Custom elements must.
+    if (!tag.includes('-'))
+        return false;
+    // If we can see light DOM children, it's almost certainly not a closed
+    // shadow host (or, if it is, we'd still walk into the light tree below
+    // anyway — no information is lost by skipping it here).
+    if (el.childNodes.length > 0)
+        return false;
+    return true;
+}
+/**
+ * Iterate the element descendants of a subtree root (the root itself is
+ * NOT yielded — the caller has already considered it on the previous
+ * iteration if it was a host).
+ *
+ * Uses a manual stack rather than `TreeWalker` to keep semantics
+ * predictable across jsdom/Chromium/WebKit, all of which have had
+ * shadow-related TreeWalker quirks.
+ */
+function* iterDescendantElements(subtree) {
+    // For a Document, start at documentElement (the <html>); for fragments
+    // and elements, start at the first child.
+    const starts = [];
+    if (isDocument(subtree)) {
+        if (subtree.documentElement)
+            starts.push(subtree.documentElement);
+    }
+    else {
+        for (const child of Array.from(subtree.children)) {
+            starts.push(child);
+        }
+    }
+    const stack = [...starts].reverse();
+    while (stack.length > 0) {
+        const el = stack.pop();
+        if (!el)
+            break;
+        yield el;
+        // Push children in reverse so we visit them left-to-right (pre-order).
+        const children = el.children;
+        for (let i = children.length - 1; i >= 0; i--) {
+            const child = children[i];
+            if (child)
+                stack.push(child);
+        }
+    }
+}
+function isDocument(x) {
+    // Document.nodeType === 9; DocumentFragment.nodeType === 11; Element.nodeType === 1.
+    return x.nodeType === 9;
+}
+//# sourceMappingURL=traverse.js.map

package/dist/shadow-dom/traverse.js.map

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

package/dist/shadow-dom/types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A single shadow host detected by `traverseShadowRoots`.
+ */
+export interface ShadowRootInfo {
+    /** The host element on the light-DOM side of the boundary. */
+    host: Element;
+    /**
+     * The shadow root if we could reach it, otherwise `null`. `null` is
+     * always paired with `source: 'unreachable'`.
+     */
+    root: ShadowRoot | null;
+    /**
+     * What the host's shadow root is declared as.
+     *
+     * - `'open'`    — resolved via `el.shadowRoot`.
+     * - `'closed'`  — confirmed closed (resolved via the injected helper, or
+     *                 attached as closed via `attachShadow({mode:'closed'})`
+     *                 and we noticed via the helper).
+     * - `'unknown'` — heuristic detection without confirmation (e.g.
+     *                 custom-element heuristic).
+     */
+    mode: 'open' | 'closed' | 'unknown';
+    /**
+     * How the root was resolved.
+     *
+     * - `'attachShadow'` — `el.shadowRoot` reflection (open roots only).
+     * - `'chrome.dom'`   — caller-injected `openOrClosedShadowRoot` helper,
+     *                      typically backed by `chrome.dom.openOrClosedShadowRoot`
+     *                      in an ISOLATED-world content script.
+     * - `'unreachable'`  — host detected but root not accessible from this
+     *                      execution context. Browser encapsulation is being
+     *                      respected; this is the intended outcome in MAIN
+     *                      world for closed shadow roots.
+     */
+    source: 'attachShadow' | 'chrome.dom' | 'unreachable';
+    /**
+     * Nesting depth. The first generation of hosts found directly under the
+     * traversal `root` is `0`; hosts inside those hosts' shadow roots are
+     * `1`, and so on.
+     */
+    depth: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/shadow-dom/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shadow-dom/types.ts"],"names":[],"mappings":"AAwBA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,8DAA8D;IAC9D,IAAI,EAAE,OAAO,CAAC;IACd;;;OAGG;IACH,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IACxB;;;;;;;;;OASG;IACH,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;IACpC;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,cAAc,GAAG,YAAY,GAAG,aAAa,CAAC;IACtD;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;CACf"}

package/dist/shadow-dom/types.js

@@ -0,0 +1,25 @@
+// Shadow DOM adapter types — Task 1.5.
+//
+// `ShadowRootInfo` is the single value the walker emits per host element.
+// It captures both the resolved root (when reachable) and enough provenance
+// for the consumer to understand WHY a given root is or is not in hand:
+//
+//   - `mode`   — what the host's shadow root was declared as. `'unknown'`
+//                is reserved for the heuristic "probably closed shadow,
+//                couldn't confirm" path so we don't lie and say `'closed'`
+//                when we never asked attachShadow at all.
+//   - `source` — how we resolved the root. `'attachShadow'` is the plain
+//                `el.shadowRoot` reflection (open roots). `'chrome.dom'`
+//                is the ISOLATED-world `chrome.dom.openOrClosedShadowRoot`
+//                helper that callers can inject. `'unreachable'` means we
+//                detected a host but couldn't reach into it (closed shadow
+//                in MAIN world, or the custom-element heuristic).
+//
+// `host` always points at the element on the document side. `root` is null
+// only on the `'unreachable'` path — the consumer should not treat null as
+// a value-tagged optional but as the literal "we cannot see inside this."
+//
+// See P2 PRD §A.3 for the closed-shadow-root MAIN-world limitation this
+// shape documents.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/shadow-dom/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/shadow-dom/types.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,EAAE;AACF,0EAA0E;AAC1E,4EAA4E;AAC5E,wEAAwE;AACxE,EAAE;AACF,0EAA0E;AAC1E,wEAAwE;AACxE,2EAA2E;AAC3E,0DAA0D;AAC1D,yEAAyE;AACzE,yEAAyE;AACzE,2EAA2E;AAC3E,0EAA0E;AAC1E,2EAA2E;AAC3E,kEAAkE;AAClE,EAAE;AACF,2EAA2E;AAC3E,2EAA2E;AAC3E,0EAA0E;AAC1E,EAAE;AACF,wEAAwE;AACxE,mBAAmB"}

package/dist/throttling/apply.d.ts

@@ -0,0 +1,59 @@
+import type { customEvent, eventWithTime, recordOptions } from '../rrweb';
+import { LARGE_DOM_DEFAULTS } from './defaults';
+/**
+ * Options for `applyLargeDomGuards`. Everything is optional — the function
+ * defaults to `LARGE_DOM_DEFAULTS` and a no-op `onWarn` / `onLimit`.
+ */
+export interface ApplyLargeDomGuardsOptions {
+    /**
+     * Override the bundled defaults. Useful for products that want to tune the
+     * mutation thresholds for their workload — but per IMPLEMENTATION_PLAN.md,
+     * tuning happens after we have real-world session data. Use sparingly.
+     */
+    defaults?: typeof LARGE_DOM_DEFAULTS;
+    /**
+     * Invoked with the `tracelane.mutation.warn` and `tracelane.event.dropped`
+     * breadcrumb custom events. Consumers can forward these to their own
+     * telemetry pipeline. Default: no-op.
+     */
+    onWarn?: (event: customEvent & {
+        timestamp: number;
+    }) => void;
+    /**
+     * Invoked exactly once when the cumulative mutation count exceeds
+     * `defaults.mutationLimit`. After this fires, the guard's emit wrapper
+     * stops forwarding events. Consumers should call rrweb's `record()`
+     * teardown from here if they want to truly halt the recorder.
+     */
+    onLimit?: () => void;
+}
+/**
+ * Compose the throttling defaults and guard chain onto an rrweb
+ * `recordOptions` object.
+ *
+ * Returns a new `recordOptions` with:
+ *   - the first six `LARGE_DOM_DEFAULTS` (mousemoveWait, sampling,
+ *     inlineImages, collectFonts, recordCanvas, plus the
+ *     `checkoutEveryNms` mapped from `defaults.checkoutEveryMs`) merged in
+ *     where the caller didn't already set them; and
+ *   - an `emit` wrapper that runs dataUrl → eventSize → mutation in order.
+ *
+ * Note on semantics: because `applyLargeDomGuards` does not own the rrweb
+ * subscription, the hard mutation limit can only stop events from being
+ * forwarded from this wrapper onward — it cannot tear down the rrweb
+ * `record()` subscription on its own. Wire your own teardown via `onLimit`
+ * if you need the recorder itself to stop.
+ *
+ * @example
+ *   const stop = record(
+ *     applyLargeDomGuards(
+ *       { emit: forwardToTransport },
+ *       {
+ *         onWarn: (e) => forwardToTransport(e),
+ *         onLimit: () => stop?.(),
+ *       },
+ *     ),
+ *   );
+ */
+export declare function applyLargeDomGuards(recordOpts: recordOptions<eventWithTime>, options?: ApplyLargeDomGuardsOptions): recordOptions<eventWithTime>;
+//# sourceMappingURL=apply.d.ts.map

package/dist/throttling/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../src/throttling/apply.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAQhD;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,kBAAkB,CAAC;IACrC;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,GAAG;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC9D;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,aAAa,CAAC,aAAa,CAAC,EACxC,OAAO,GAAE,0BAA+B,GACvC,aAAa,CAAC,aAAa,CAAC,CAiD9B"}