@michaelmagan/dnumb 0.1.0

package/dist/snapshot/cdp.d.cts

@@ -0,0 +1,36 @@
+/**
+ * The `DOMSnapshot.captureSnapshot` fast path. Chromium only.
+ *
+ * One round trip returns the whole document: per-node bounds, scroll/client
+ * rects, paint order, and any computed style requested by name. Measured ~6x
+ * faster than an equivalent in-page walk (68ms vs 412ms on a Wikipedia
+ * article) with a smaller payload. `scrollRects[2] === el.scrollWidth` and
+ * `clientRects[2] === el.clientWidth` natively — the pair the whole overflow
+ * fact rests on.
+ *
+ * The cost is that everything arrives as flat parallel arrays of indexes into a
+ * shared string table, so rebuilding `ElementRecord[]` is genuine index
+ * juggling. Three things that are easy to get wrong, all handled below:
+ *
+ * 1. **Coordinates are document-space and scroll-invariant.** The in-page walk
+ *    returns viewport-space rects from `getBoundingClientRect`. Subtracting the
+ *    document scroll offset is what makes the two paths agree.
+ * 2. **A node with no layout row has no box at all.** That absence *is* the
+ *    `display:none` signal, and it is cleaner than a boolean.
+ * 3. **Style names are validated server-side and one bad name throws the whole
+ *    call.** They must be kebab-case and Blink-recognized; custom properties
+ *    cannot be requested at all.
+ *
+ * `DOMSnapshot` is an experimental domain. Every failure here falls back to the
+ * portable walk rather than surfacing.
+ */
+import type { CDPCapablePage } from "../page.cjs";
+import type { Snapshot } from "./types.cjs";
+/**
+ * Capture via CDP, or `null` if this page or this Chromium cannot.
+ *
+ * Returning null rather than throwing is deliberate: the caller's job is to
+ * fall back to the portable walk, and an experimental domain failing is an
+ * expected outcome, not an error.
+ */
+export declare function captureViaCDP(page: CDPCapablePage): Promise<Snapshot | null>;

package/dist/snapshot/cdp.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The `DOMSnapshot.captureSnapshot` fast path. Chromium only.
+ *
+ * One round trip returns the whole document: per-node bounds, scroll/client
+ * rects, paint order, and any computed style requested by name. Measured ~6x
+ * faster than an equivalent in-page walk (68ms vs 412ms on a Wikipedia
+ * article) with a smaller payload. `scrollRects[2] === el.scrollWidth` and
+ * `clientRects[2] === el.clientWidth` natively — the pair the whole overflow
+ * fact rests on.
+ *
+ * The cost is that everything arrives as flat parallel arrays of indexes into a
+ * shared string table, so rebuilding `ElementRecord[]` is genuine index
+ * juggling. Three things that are easy to get wrong, all handled below:
+ *
+ * 1. **Coordinates are document-space and scroll-invariant.** The in-page walk
+ *    returns viewport-space rects from `getBoundingClientRect`. Subtracting the
+ *    document scroll offset is what makes the two paths agree.
+ * 2. **A node with no layout row has no box at all.** That absence *is* the
+ *    `display:none` signal, and it is cleaner than a boolean.
+ * 3. **Style names are validated server-side and one bad name throws the whole
+ *    call.** They must be kebab-case and Blink-recognized; custom properties
+ *    cannot be requested at all.
+ *
+ * `DOMSnapshot` is an experimental domain. Every failure here falls back to the
+ * portable walk rather than surfacing.
+ */
+import type { CDPCapablePage } from "../page.js";
+import type { Snapshot } from "./types.js";
+/**
+ * Capture via CDP, or `null` if this page or this Chromium cannot.
+ *
+ * Returning null rather than throwing is deliberate: the caller's job is to
+ * fall back to the portable walk, and an experimental domain failing is an
+ * expected outcome, not an error.
+ */
+export declare function captureViaCDP(page: CDPCapablePage): Promise<Snapshot | null>;

package/dist/snapshot/cdp.js

@@ -0,0 +1,447 @@
+import { COLOR_TOKEN_CAP, capBackgroundImage, MAX_ELEMENTS, NAME_LENGTH, SKIPPED_TAGS, TESTID_ATTRS, TEXT_PREVIEW_LENGTH, } from "./limits.js";
+/**
+ * Requested in this exact order; `layout.styles[i]` comes back in it. Every
+ * name is kebab-case because Blink rejects camelCase and takes the whole call
+ * down with it (`whiteSpace` -> "Protocol error: invalid CSS property").
+ */
+// biome-ignore format: the order of this list is the wire format -- one name per
+// line would hide the grouping that makes a mismatch with `S` visible.
+const STYLES = [
+    'color', 'background-color', 'font-size', 'font-weight', 'text-align',
+    'overflow-x', 'overflow-y', 'position', 'display', 'visibility', 'opacity',
+    'flex-direction', 'grid-template-columns', 'row-gap', 'column-gap',
+    'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
+    'padding-top', 'padding-right', 'padding-bottom', 'padding-left',
+    'border-top-width', 'border-right-width', 'border-bottom-width', 'border-left-width',
+    'text-overflow', 'white-space', 'overflow-wrap',
+    'background-image', 'text-shadow', '-webkit-text-stroke-width', '-webkit-text-stroke-color',
+    // Requested so `build()` can read `<html>`'s own values off this same
+    // per-node styles array -- see `DocumentBackground` (A2). Not per-element
+    // data; every other record's slot for this name is simply unused.
+    'color-scheme',
+];
+const S = Object.fromEntries(STYLES.map((name, i) => [name, i]));
+const ELEMENT_NODE = 1;
+const TEXT_NODE = 3;
+/** Roles too generic to be worth carrying; matches the identity ladder's set. */
+const WEAK_AX_ROLES = new Set(['generic', 'none', 'presentation', 'InlineTextBox']);
+function rect(r, dx = 0, dy = 0) {
+    return {
+        x: (r?.[0] ?? 0) - dx,
+        y: (r?.[1] ?? 0) - dy,
+        width: r?.[2] ?? 0,
+        height: r?.[3] ?? 0,
+    };
+}
+function sides(values, strings, keys) {
+    const num = (i) => Number.parseFloat(strings[values?.[i] ?? -1] ?? '') || 0;
+    return { top: num(keys[0]), right: num(keys[1]), bottom: num(keys[2]), left: num(keys[3]) };
+}
+function trimName(value) {
+    const text = (value ?? '').replace(/\s+/g, ' ').trim();
+    return text ? text.slice(0, NAME_LENGTH) : null;
+}
+/**
+ * Same-origin vs cross-origin for an `<iframe>` found in `documents[0]`, using
+ * only that document's own data: resolve `src` against the document's own
+ * `baseURL`, exactly as the browser resolves it when it assigns `iframe.src`.
+ * This never reads `documents[1..]` -- the slots `captureViaCDP` does not use,
+ * per the file header -- classifying an iframe's origin is not the same as
+ * reading what is inside it.
+ */
+function iframeOrigin(attrs, baseURL) {
+    // `srcdoc` and no `src` both resolve to a document that inherits the
+    // parent's origin (`about:srcdoc` / `about:blank`), not the frame's own.
+    if (attrs.has('srcdoc'))
+        return 'same';
+    const src = (attrs.get('src') ?? '').trim();
+    if (src === '' || src.toLowerCase() === 'about:blank')
+        return 'same';
+    try {
+        return new URL(src, baseURL).origin === new URL(baseURL).origin ? 'same' : 'cross';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * Real open/closed shadow root counts from `nodes.shadowRootType`, or the
+ * honest "cannot know" shape when the payload has no such field at all.
+ *
+ * Every node flattened out of a shadow root is tagged `'open'` or `'closed'`
+ * (see `NodeArrays.shadowRootType`'s doc comment), not just the root itself,
+ * so counting tagged *nodes* would count a shadow root once per descendant it
+ * flattened in. Instead, for each tagged node this walks `parentIndex` up
+ * through other tagged nodes until it reaches the first untagged ancestor --
+ * that ancestor is the shadow host -- and counts each distinct host once,
+ * keyed by the type its tagged descendants carried. A shadow root with no
+ * flattened content at all (empty) has no tagged node to find and is not
+ * counted; a shadow root nested inside another shadow root is counted once
+ * under the outer host rather than twice, because the walk does not stop at
+ * the inner boundary -- an known, narrow gap on real pages, which is why this
+ * function is a best-effort count, not a claim of perfect precision.
+ */
+function countShadowRoots(nodes, strings) {
+    const srt = nodes.shadowRootType;
+    // The field is absent, not merely empty, on a payload this build has never
+    // seen shaped this way -- report the same "cannot know" shape the walk
+    // path uses rather than assuming zero.
+    if (!srt)
+        return { open: 0, closed: 'unknown' };
+    const typeByNode = new Map();
+    for (let i = 0; i < srt.index.length; i++) {
+        const nodeIdx = srt.index[i];
+        const valueIdx = srt.value[i];
+        if (nodeIdx === undefined || valueIdx === undefined)
+            continue;
+        const value = strings[valueIdx];
+        // `'user-agent'` (a browser-internal shadow root, e.g. inside `<video>`)
+        // is a real `ShadowRootType` this field can carry but which this package
+        // has no author-facing fact to report -- excluded from both counts rather
+        // than folded into either.
+        typeByNode.set(nodeIdx, value === 'open' ? 'open' : value === 'closed' ? 'closed' : null);
+    }
+    const hostType = new Map();
+    for (const [nodeIdx, type] of typeByNode) {
+        if (!type)
+            continue;
+        let cursor = nodes.parentIndex[nodeIdx];
+        while (cursor !== undefined && cursor >= 0 && typeByNode.has(cursor)) {
+            cursor = nodes.parentIndex[cursor];
+        }
+        if (cursor === undefined || cursor < 0)
+            continue;
+        hostType.set(cursor, type);
+    }
+    let open = 0;
+    let closed = 0;
+    for (const type of hostType.values()) {
+        if (type === 'open')
+            open++;
+        else
+            closed++;
+    }
+    return { open, closed };
+}
+/**
+ * Computed role and accessible name, which `captureSnapshot` does not return —
+ * it carries only the literal `role=` attribute, so a `<button>` comes back
+ * with no role at all. This is a second experimental call joined on
+ * `backendDOMNodeId`.
+ *
+ * Failure is non-fatal: without it the records simply carry the attribute role,
+ * which is the state the prototype shipped in.
+ */
+async function axIndex(cdp) {
+    const out = new Map();
+    let tree;
+    try {
+        tree = (await cdp.send('Accessibility.getFullAXTree'));
+    }
+    catch {
+        return out;
+    }
+    for (const node of tree.nodes ?? []) {
+        if (node.backendDOMNodeId === undefined || node.ignored)
+            continue;
+        const role = typeof node.role?.value === 'string' ? node.role.value : null;
+        const name = typeof node.name?.value === 'string' ? node.name.value : null;
+        out.set(node.backendDOMNodeId, {
+            role: role && !WEAK_AX_ROLES.has(role) ? role : null,
+            name: trimName(name),
+        });
+    }
+    return out;
+}
+/**
+ * Capture via CDP, or `null` if this page or this Chromium cannot.
+ *
+ * Returning null rather than throwing is deliberate: the caller's job is to
+ * fall back to the portable walk, and an experimental domain failing is an
+ * expected outcome, not an error.
+ */
+export async function captureViaCDP(page) {
+    let cdp;
+    try {
+        cdp = await page.context().newCDPSession(page);
+    }
+    catch {
+        return null;
+    }
+    try {
+        const snapshot = (await cdp.send('DOMSnapshot.captureSnapshot', {
+            computedStyles: [...STYLES],
+            includeDOMRects: true,
+            includePaintOrder: true,
+        }));
+        const viewport = await page.evaluate(() => ({
+            width: window.innerWidth,
+            height: window.innerHeight,
+        }));
+        const ax = await axIndex(cdp);
+        const doc = snapshot.documents[0];
+        if (!doc)
+            return null;
+        return { ...build(doc, snapshot.strings, ax), viewport };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await cdp.detach().catch(() => { });
+    }
+}
+function build(doc, strings, ax) {
+    const { nodes, layout } = doc;
+    const str = (i) => i === undefined || i < 0 ? '' : (strings[i] ?? '');
+    // layout rows are sparse: only nodes that generated a box have one.
+    const layoutOf = new Map();
+    for (let layoutIdx = 0; layoutIdx < layout.nodeIndex.length; layoutIdx++) {
+        const nodeIdx = layout.nodeIndex[layoutIdx];
+        if (nodeIdx !== undefined)
+            layoutOf.set(nodeIdx, layoutIdx);
+    }
+    const attrsOf = (nodeIdx) => {
+        const flat = nodes.attributes[nodeIdx] ?? [];
+        const map = new Map();
+        for (let i = 0; i + 1 < flat.length; i += 2) {
+            map.set(str(flat[i]), str(flat[i + 1]));
+        }
+        return map;
+    };
+    // Own text: direct text-node children only, matching the walk's `ownText`.
+    const ownText = new Map();
+    nodes.nodeType.forEach((type, nodeIdx) => {
+        if (type !== TEXT_NODE)
+            return;
+        const parent = nodes.parentIndex[nodeIdx];
+        if (parent === undefined || parent < 0)
+            return;
+        ownText.set(parent, (ownText.get(parent) ?? '') + str(nodes.nodeValue[nodeIdx]));
+    });
+    // `<html>`'s own `background-color` / `color-scheme` -- the real terminal
+    // layer a compositing walk that runs off the top of `<body>`'s ancestor
+    // chain reaches (A2). Read the same way any element's own styles are, off
+    // this same per-node `layout.styles` array -- `<html>` itself is never one
+    // of `elements` below, this walk stays inside the <body> subtree exactly
+    // like the portable walk does, so without this it would be unreachable.
+    //
+    // The `nodeType === ELEMENT_NODE` guard is required, not defensive
+    // decoration: `<!doctype html>` is its own node in this same
+    // `nodes.nodeName` array (a `DocumentType` node, name `"html"`), and it
+    // sorts *before* the real `<html>` element -- an unguarded search finds
+    // the doctype first, which has no layout row at all, and every style
+    // this function reads off it comes back the empty string. *Verified*:
+    // this is exactly what happened on the first pass of this fix, caught by
+    // `test/browser/color-canvas.test.ts`'s `cdp`-path case.
+    const htmlIndex = nodes.nodeName.findIndex((name, i) => nodes.nodeType[i] === ELEMENT_NODE && str(name).toUpperCase() === 'HTML');
+    const htmlLayoutIdx = htmlIndex < 0 ? undefined : layoutOf.get(htmlIndex);
+    const htmlStyles = htmlLayoutIdx === undefined ? undefined : layout.styles[htmlLayoutIdx];
+    const htmlStyle = (name) => str(htmlStyles?.[S[name]]);
+    const documentBackground = {
+        backgroundColor: htmlStyle('background-color'),
+        colorScheme: htmlStyle('color-scheme'),
+    };
+    // Only the <body> subtree, matching the walk's entry point.
+    const bodyIndex = nodes.nodeName.findIndex((name) => str(name).toUpperCase() === 'BODY');
+    if (bodyIndex < 0) {
+        return {
+            elements: [],
+            truncated: false,
+            notMeasured: {
+                shadowRoots: countShadowRoots(nodes, strings),
+                iframes: { sameOrigin: 0, crossOrigin: 0, unknownOrigin: 0 },
+            },
+            documentBackground,
+        };
+    }
+    const SKIPPED = new Set(SKIPPED_TAGS);
+    const idOf = new Map();
+    const elements = [];
+    let truncated = false;
+    const baseURL = str(doc.baseURL);
+    let iframesSameOrigin = 0;
+    let iframesCrossOrigin = 0;
+    let iframesUnknownOrigin = 0;
+    const inBody = (nodeIdx) => {
+        let cursor = nodeIdx;
+        while (cursor !== undefined && cursor >= 0) {
+            if (cursor === bodyIndex)
+                return true;
+            cursor = nodes.parentIndex[cursor];
+        }
+        return false;
+    };
+    // Document order is array order, so one forward pass keys parents before
+    // children — the same invariant the recursive walk gets for free.
+    for (let nodeIdx = 0; nodeIdx < nodes.nodeType.length; nodeIdx++) {
+        // Same ceiling as the walk, so `truncated` means one thing across paths.
+        if (elements.length >= MAX_ELEMENTS) {
+            truncated = true;
+            break;
+        }
+        if (nodes.nodeType[nodeIdx] !== ELEMENT_NODE)
+            continue;
+        if (!inBody(nodeIdx))
+            continue;
+        const tagName = str(nodes.nodeName[nodeIdx]).toUpperCase();
+        if (SKIPPED.has(tagName))
+            continue;
+        // `documents[0]` is the only slot this path reads (see the file header),
+        // so an iframe's own content document is never entered -- counted here
+        // regardless of whether the iframe itself survives the ancestor check
+        // below, because it was encountered either way.
+        if (tagName === 'IFRAME') {
+            switch (iframeOrigin(attrsOf(nodeIdx), baseURL)) {
+                case 'same':
+                    iframesSameOrigin++;
+                    break;
+                case 'cross':
+                    iframesCrossOrigin++;
+                    break;
+                case 'unknown':
+                    iframesUnknownOrigin++;
+                    break;
+            }
+        }
+        // An ancestor that was skipped takes its subtree with it.
+        let parentIdx = nodes.parentIndex[nodeIdx];
+        while (parentIdx !== undefined && parentIdx >= 0 && !idOf.has(parentIdx)) {
+            if (parentIdx === bodyIndex)
+                break;
+            parentIdx = nodes.parentIndex[parentIdx];
+        }
+        const parentId = parentIdx !== undefined && parentIdx >= 0 ? (idOf.get(parentIdx) ?? null) : null;
+        if (nodeIdx !== bodyIndex && parentId === null)
+            continue;
+        const id = `e${elements.length}`;
+        idOf.set(nodeIdx, id);
+        const attrs = attrsOf(nodeIdx);
+        const layoutIdx = layoutOf.get(nodeIdx);
+        const styles = layoutIdx === undefined ? undefined : layout.styles[layoutIdx];
+        const box = rect(layoutIdx === undefined ? undefined : layout.bounds[layoutIdx], doc.scrollOffsetX, doc.scrollOffsetY);
+        const scrollRect = layoutIdx === undefined ? undefined : layout.scrollRects?.[layoutIdx];
+        const clientRect = layoutIdx === undefined ? undefined : layout.clientRects?.[layoutIdx];
+        const style = (name) => str(styles?.[S[name]]);
+        // A node with no layout row generated no box: that absence is the signal.
+        const display = layoutIdx === undefined ? 'none' : style('display') || 'block';
+        const visibility = style('visibility') || 'visible';
+        const opacity = Number.parseFloat(style('opacity'));
+        let testId = null;
+        for (const attr of TESTID_ATTRS) {
+            const value = attrs.get(attr);
+            if (value) {
+                testId = value;
+                break;
+            }
+        }
+        const backendId = nodes.backendNodeId[nodeIdx];
+        const computed = backendId === undefined ? undefined : ax.get(backendId);
+        const attrRole = (attrs.get('role') ?? '').trim().split(/\s+/)[0] || null;
+        const ariaLevel = Number(attrs.get('aria-level'));
+        const headingMatch = /^H([1-6])$/.exec(tagName);
+        elements.push({
+            id,
+            tag: tagName.toLowerCase(),
+            testId,
+            domId: attrs.get('id') ?? null,
+            role: computed?.role ?? attrRole,
+            name: computed?.name ?? null,
+            className: attrs.get('class') ?? '',
+            headingLevel: Number.isFinite(ariaLevel) && attrs.has('aria-level')
+                ? ariaLevel
+                : headingMatch?.[1]
+                    ? Number(headingMatch[1])
+                    : null,
+            rect: box,
+            scrollWidth: scrollRect?.[2] ?? box.width,
+            scrollHeight: scrollRect?.[3] ?? box.height,
+            clientWidth: clientRect?.[2] ?? box.width,
+            clientHeight: clientRect?.[3] ?? box.height,
+            overflowX: style('overflow-x') || 'visible',
+            overflowY: style('overflow-y') || 'visible',
+            position: style('position') || 'static',
+            display,
+            visibility,
+            opacity: Number.isFinite(opacity) ? opacity : 1,
+            margin: sides(styles, strings, [
+                S['margin-top'],
+                S['margin-right'],
+                S['margin-bottom'],
+                S['margin-left'],
+            ]),
+            padding: sides(styles, strings, [
+                S['padding-top'],
+                S['padding-right'],
+                S['padding-bottom'],
+                S['padding-left'],
+            ]),
+            gap: {
+                row: Number.parseFloat(style('row-gap')) || 0,
+                column: Number.parseFloat(style('column-gap')) || 0,
+            },
+            border: sides(styles, strings, [
+                S['border-top-width'],
+                S['border-right-width'],
+                S['border-bottom-width'],
+                S['border-left-width'],
+            ]),
+            color: style('color'),
+            backgroundColor: style('background-color'),
+            backgroundImage: capBackgroundImage(style('background-image')),
+            textShadow: style('text-shadow').slice(0, COLOR_TOKEN_CAP),
+            textStrokeWidth: style('-webkit-text-stroke-width') || '0px',
+            textStrokeColor: style('-webkit-text-stroke-color'),
+            fontSize: style('font-size'),
+            fontWeight: Number.parseFloat(style('font-weight')) || 400,
+            textAlign: style('text-align'),
+            flexDirection: style('flex-direction'),
+            gridTemplateColumns: style('grid-template-columns'),
+            textOverflow: style('text-overflow') || 'clip',
+            whiteSpace: style('white-space') || 'normal',
+            overflowWrap: style('overflow-wrap') || 'normal',
+            text: (ownText.get(nodeIdx) ?? '').replace(/\s+/g, ' ').trim().slice(0, TEXT_PREVIEW_LENGTH),
+            parentId,
+            childIds: [],
+            visible: display !== 'none' &&
+                visibility !== 'hidden' &&
+                !(Number.isFinite(opacity) && opacity === 0) &&
+                box.width > 0 &&
+                box.height > 0,
+            ariaExpanded: attrs.get('aria-expanded') ?? null,
+            // `cdp` never calls `elementsFromPoint` -- it has `paintOrder` plus
+            // rects instead, which is the whole-rect answer to the same question
+            // `hitStackIds` answers on the `walk` path. See both fields' doc
+            // comments on `ElementRecord`.
+            hitStackIds: null,
+            paintOrder: layoutIdx === undefined ? null : (layout.paintOrders?.[layoutIdx] ?? null),
+        });
+    }
+    const byId = new Map(elements.map((el) => [el.id, el]));
+    for (const el of elements) {
+        if (el.parentId)
+            byId.get(el.parentId)?.childIds.push(el.id);
+    }
+    return {
+        elements,
+        truncated,
+        notMeasured: {
+            // Counted from `nodes.shadowRootType`, not assumed: `DOMSnapshot`
+            // flattens an author shadow root's content directly under its host
+            // (both open and closed -- verified in `test/browser/not-measured.test.ts`)
+            // and tags every flattened node, so `countShadowRoots` recovers the real
+            // per-host counts from those tags instead of asserting a permanent zero.
+            // A page whose shadow content this specific capture failed to flatten
+            // for any reason now reports that failure as a nonzero count rather
+            // than silence -- see `countShadowRoots`'s doc comment for the one
+            // known narrow gap (nested shadow roots) and the absent-field fallback.
+            shadowRoots: countShadowRoots(nodes, strings),
+            iframes: {
+                sameOrigin: iframesSameOrigin,
+                crossOrigin: iframesCrossOrigin,
+                unknownOrigin: iframesUnknownOrigin,
+            },
+        },
+        documentBackground,
+    };
+}

package/dist/snapshot/clip.cjs

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clipFactFor = clipFactFor;
+exports.attachClipFacts = attachClipFacts;
+/** `overflow` values that actually clip. Everything else lets content escape. */
+const CLIPS = /^(hidden|scroll|auto|clip|overlay)$/;
+/** …and of those, the ones a user can scroll to reveal what is hidden. */
+const REACHABLE = /^(auto|scroll|overlay)$/;
+/**
+ * The nearest ancestor that establishes this element's containing block.
+ *
+ * - `position: fixed` escapes every scroll container: its containing block is
+ *   the viewport, so nothing in the DOM chain clips it.
+ * - `position: absolute` skips ancestors that are `position: static`.
+ * - everything else is clipped by its DOM ancestors, in order.
+ */
+function* clippingAncestors(el, byId) {
+    if (el.position === 'fixed')
+        return;
+    const absolute = el.position === 'absolute';
+    let cursor = el.parentId;
+    while (cursor) {
+        const ancestor = byId.get(cursor);
+        if (!ancestor)
+            return;
+        if (!absolute || ancestor.position !== 'static')
+            yield ancestor;
+        cursor = ancestor.parentId;
+    }
+}
+function overflowLabel(el) {
+    return el.overflowX === el.overflowY ? el.overflowX : `${el.overflowX}/${el.overflowY}`;
+}
+/**
+ * How far `el` extends past `clipper` on each side. All four are >= 0; a zero
+ * on every side means the element is fully inside.
+ */
+function hiddenExtents(el, clipper) {
+    return {
+        top: Math.max(0, clipper.rect.y - el.rect.y),
+        left: Math.max(0, clipper.rect.x - el.rect.x),
+        bottom: Math.max(0, el.rect.y + el.rect.height - (clipper.rect.y + clipper.rect.height)),
+        right: Math.max(0, el.rect.x + el.rect.width - (clipper.rect.x + clipper.rect.width)),
+    };
+}
+/**
+ * The clip fact for one element, or `undefined` when nothing hides any of it.
+ *
+ * The returned fact deliberately carries `overflow` and `scrollable` beside the
+ * hidden extents. A box outside an `overflow:auto` ancestor is a scroll region;
+ * the same box outside an `overflow:hidden` ancestor is content nobody can
+ * reach. Reporting the extent without the reachability would be a measurement
+ * the reader cannot act on.
+ */
+function clipFactFor(el, byId) {
+    if (!el.visible)
+        return undefined;
+    for (const ancestor of clippingAncestors(el, byId)) {
+        const clipsX = CLIPS.test(ancestor.overflowX);
+        const clipsY = CLIPS.test(ancestor.overflowY);
+        if (!clipsX && !clipsY)
+            continue;
+        const hidden = hiddenExtents(el, ancestor);
+        // An axis that does not clip cannot hide anything on that axis.
+        if (!clipsX) {
+            hidden.left = 0;
+            hidden.right = 0;
+        }
+        if (!clipsY) {
+            hidden.top = 0;
+            hidden.bottom = 0;
+        }
+        if (!hidden.top && !hidden.bottom && !hidden.left && !hidden.right)
+            return undefined;
+        const visibleWidth = Math.max(0, el.rect.width - hidden.left - hidden.right);
+        const visibleHeight = Math.max(0, el.rect.height - hidden.top - hidden.bottom);
+        return {
+            by: ancestor.id,
+            byTag: ancestor.tag,
+            overflow: overflowLabel(ancestor),
+            hidden,
+            visible: { width: visibleWidth, height: visibleHeight },
+            // Not the same question as `scrollHeight > clientHeight`: an
+            // `overflow:hidden` box has scroll extent and no reachability.
+            scrollable: (REACHABLE.test(ancestor.overflowY) && ancestor.scrollHeight - ancestor.clientHeight > 1) ||
+                (REACHABLE.test(ancestor.overflowX) && ancestor.scrollWidth - ancestor.clientWidth > 1),
+        };
+    }
+    return undefined;
+}
+/** Attach `clip` to every element it applies to. Mutates and returns `elements`. */
+function attachClipFacts(elements) {
+    const byId = new Map(elements.map((el) => [el.id, el]));
+    for (const el of elements) {
+        const clip = clipFactFor(el, byId);
+        if (clip)
+            el.clip = clip;
+    }
+    return elements;
+}

package/dist/snapshot/clip.d.cts

@@ -0,0 +1,26 @@
+/**
+ * Ancestor clip-rect intersection.
+ *
+ * This runs on the Node side over already-collected records, not inside the
+ * page, for two reasons: both capture paths (the in-page walk and the CDP fast
+ * path) need it and neither should own it, and as a pure function over an array
+ * it is unit-testable without a browser.
+ *
+ * CDP does not solve this and makes it harder, not easier: `parentIndex` is the
+ * DOM parent chain, and for `position: fixed | absolute` the real clipping
+ * ancestor is on the *containing block* chain, which has to be reconstructed
+ * from the ancestors' `position` values.
+ */
+import type { ClipFact, ElementRecord } from "./types.cjs";
+/**
+ * The clip fact for one element, or `undefined` when nothing hides any of it.
+ *
+ * The returned fact deliberately carries `overflow` and `scrollable` beside the
+ * hidden extents. A box outside an `overflow:auto` ancestor is a scroll region;
+ * the same box outside an `overflow:hidden` ancestor is content nobody can
+ * reach. Reporting the extent without the reachability would be a measurement
+ * the reader cannot act on.
+ */
+export declare function clipFactFor(el: ElementRecord, byId: Map<string, ElementRecord>): ClipFact | undefined;
+/** Attach `clip` to every element it applies to. Mutates and returns `elements`. */
+export declare function attachClipFacts(elements: ElementRecord[]): ElementRecord[];

package/dist/snapshot/clip.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Ancestor clip-rect intersection.
+ *
+ * This runs on the Node side over already-collected records, not inside the
+ * page, for two reasons: both capture paths (the in-page walk and the CDP fast
+ * path) need it and neither should own it, and as a pure function over an array
+ * it is unit-testable without a browser.
+ *
+ * CDP does not solve this and makes it harder, not easier: `parentIndex` is the
+ * DOM parent chain, and for `position: fixed | absolute` the real clipping
+ * ancestor is on the *containing block* chain, which has to be reconstructed
+ * from the ancestors' `position` values.
+ */
+import type { ClipFact, ElementRecord } from "./types.js";
+/**
+ * The clip fact for one element, or `undefined` when nothing hides any of it.
+ *
+ * The returned fact deliberately carries `overflow` and `scrollable` beside the
+ * hidden extents. A box outside an `overflow:auto` ancestor is a scroll region;
+ * the same box outside an `overflow:hidden` ancestor is content nobody can
+ * reach. Reporting the extent without the reachability would be a measurement
+ * the reader cannot act on.
+ */
+export declare function clipFactFor(el: ElementRecord, byId: Map<string, ElementRecord>): ClipFact | undefined;
+/** Attach `clip` to every element it applies to. Mutates and returns `elements`. */
+export declare function attachClipFacts(elements: ElementRecord[]): ElementRecord[];