@michaelmagan/dnumb 0.1.0

package/dist/snapshot/clip.js

@@ -0,0 +1,96 @@
+/** `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.
+ */
+export 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`. */
+export 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/collect.cjs

@@ -0,0 +1,358 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectSnapshot = collectSnapshot;
+function collectSnapshot() {
+    // Inlined, not imported: `page.evaluate` serializes only this function's own
+    // source, so nothing from module scope survives the trip into the page.
+    // Kept in sync with `limits.ts` by `test/unit/limits.test.ts`.
+    const MAX_ELEMENTS = 5000;
+    const SKIPPED_TAGS = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE', 'SVG']);
+    const TEXT_PREVIEW_LENGTH = 60;
+    const NAME_LENGTH = 80;
+    const TESTID_ATTRS = ['data-testid', 'data-test-id', 'data-test', 'data-qa'];
+    // Kept in sync with `limits.ts#COLOR_TOKEN_CAP` by `test/unit/limits.test.ts` --
+    // duplicated, not imported, for the same reason `MAX_ELEMENTS` is: this
+    // function's source is serialized whole into the page, and a runtime import
+    // from another module would not survive that trip.
+    const COLOR_TOKEN_CAP = 120;
+    // Kept in sync with `limits.ts#capBackgroundImage` -- same reason, same
+    // discipline. Preserves both ends of a long gradient string rather than a
+    // plain prefix cut, so the *last* color stop survives capture; see that
+    // function's doc comment (A4).
+    function capBackgroundImage(raw) {
+        if (raw.length <= COLOR_TOKEN_CAP)
+            return raw;
+        const ELLIPSIS = '…';
+        const half = Math.max(0, Math.floor((COLOR_TOKEN_CAP - ELLIPSIS.length) / 2));
+        return `${raw.slice(0, half)}${ELLIPSIS}${raw.slice(raw.length - half)}`;
+    }
+    // ---- computed role ------------------------------------------------------
+    // The prototype captured `getAttribute('role')`, which is null on nearly
+    // every real element, so the identity ladder's strongest rung was dead on
+    // arrival. This is the implicit-role mapping that fixes it.
+    // biome-ignore format: a lookup table reads as a table; one tag per line is 37
+    // lines of noise for the same information.
+    const IMPLICIT_ROLE = {
+        ARTICLE: 'article', ASIDE: 'complementary', BUTTON: 'button', DIALOG: 'dialog',
+        FIELDSET: 'group', FIGURE: 'figure', FOOTER: 'contentinfo', FORM: 'form',
+        H1: 'heading', H2: 'heading', H3: 'heading', H4: 'heading', H5: 'heading',
+        H6: 'heading', HEADER: 'banner', HR: 'separator', IMG: 'img', LI: 'listitem',
+        MAIN: 'main', NAV: 'navigation', OL: 'list', OPTION: 'option', OUTPUT: 'status',
+        P: 'paragraph', PROGRESS: 'progressbar', SECTION: 'region', SELECT: 'combobox',
+        SUMMARY: 'button', TABLE: 'table', TBODY: 'rowgroup', TD: 'cell',
+        TEXTAREA: 'textbox', TFOOT: 'rowgroup', TH: 'columnheader', THEAD: 'rowgroup',
+        TR: 'row', UL: 'list',
+    };
+    // biome-ignore format: see above.
+    const INPUT_ROLE = {
+        button: 'button', checkbox: 'checkbox', email: 'textbox', image: 'button',
+        number: 'spinbutton', radio: 'radio', range: 'slider', reset: 'button',
+        search: 'searchbox', submit: 'button', tel: 'textbox', text: 'textbox',
+        url: 'textbox',
+    };
+    /** Roles whose accessible name comes from their own content. */
+    // biome-ignore format: see above.
+    const NAME_FROM_CONTENT = new Set([
+        'button', 'cell', 'checkbox', 'columnheader', 'gridcell', 'heading', 'link',
+        'menuitem', 'menuitemcheckbox', 'menuitemradio', 'option', 'radio', 'row',
+        'rowheader', 'switch', 'tab', 'tooltip', 'treeitem',
+    ]);
+    function computedRole(el) {
+        const explicit = (el.getAttribute('role') ?? '').trim().split(/\s+/)[0];
+        if (explicit)
+            return explicit;
+        const tag = el.tagName.toUpperCase();
+        if (tag === 'A' || tag === 'AREA')
+            return el.hasAttribute('href') ? 'link' : null;
+        if (tag === 'INPUT') {
+            const type = (el.getAttribute('type') ?? 'text').toLowerCase();
+            return INPUT_ROLE[type] ?? 'textbox';
+        }
+        // `header` and `footer` are landmarks only at the top level.
+        if ((tag === 'HEADER' || tag === 'FOOTER') && el.closest('article,aside,main,nav,section')) {
+            return null;
+        }
+        // `section` is a region only when it has an accessible name.
+        if (tag === 'SECTION' &&
+            !el.getAttribute('aria-label') &&
+            !el.getAttribute('aria-labelledby')) {
+            return null;
+        }
+        return IMPLICIT_ROLE[tag] ?? null;
+    }
+    function trimName(value) {
+        const text = (value ?? '').replace(/\s+/g, ' ').trim();
+        return text ? text.slice(0, NAME_LENGTH) : null;
+    }
+    function accessibleName(el, role) {
+        const label = trimName(el.getAttribute('aria-label'));
+        if (label)
+            return label;
+        const labelledby = el.getAttribute('aria-labelledby');
+        if (labelledby) {
+            const parts = [];
+            for (const id of labelledby.split(/\s+/)) {
+                parts.push(document.getElementById(id)?.textContent ?? '');
+            }
+            const joined = trimName(parts.join(' '));
+            if (joined)
+                return joined;
+        }
+        const tag = el.tagName.toUpperCase();
+        if (tag === 'INPUT' || tag === 'SELECT' || tag === 'TEXTAREA') {
+            if (el.id) {
+                const forLabel = document.querySelector(`label[for="${CSS.escape(el.id)}"]`);
+                const text = trimName(forLabel?.textContent);
+                if (text)
+                    return text;
+            }
+            const wrapping = trimName(el.closest('label')?.textContent);
+            if (wrapping)
+                return wrapping;
+            const placeholder = trimName(el.getAttribute('placeholder'));
+            if (placeholder)
+                return placeholder;
+        }
+        if (tag === 'IMG')
+            return trimName(el.getAttribute('alt'));
+        if (role && NAME_FROM_CONTENT.has(role)) {
+            const text = trimName(el.textContent);
+            if (text)
+                return text;
+        }
+        return trimName(el.getAttribute('title'));
+    }
+    // ---- geometry / style ---------------------------------------------------
+    function childrenOf(el) {
+        const result = [];
+        for (let i = 0; i < el.children.length; i++) {
+            const child = el.children[i];
+            if (child)
+                result.push(child);
+        }
+        return result;
+    }
+    function boxSides(cs, prefix) {
+        const suffix = prefix === 'border' ? 'Width' : '';
+        return {
+            top: Number.parseFloat(cs.getPropertyValue(`${prefix}-top${suffix}`)) || 0,
+            right: Number.parseFloat(cs.getPropertyValue(`${prefix}-right${suffix}`)) || 0,
+            bottom: Number.parseFloat(cs.getPropertyValue(`${prefix}-bottom${suffix}`)) || 0,
+            left: Number.parseFloat(cs.getPropertyValue(`${prefix}-left${suffix}`)) || 0,
+        };
+    }
+    function headingLevel(el) {
+        const ariaLevel = el.getAttribute('aria-level');
+        if (ariaLevel && Number.isFinite(Number(ariaLevel)))
+            return Number(ariaLevel);
+        const match = /^H([1-6])$/.exec(el.tagName);
+        return match?.[1] ? Number(match[1]) : null;
+    }
+    function ownText(el) {
+        let text = '';
+        for (const node of el.childNodes) {
+            if (node.nodeType === 3 /* TEXT_NODE */)
+                text += node.textContent ?? '';
+        }
+        return text.replace(/\s+/g, ' ').trim().slice(0, TEXT_PREVIEW_LENGTH);
+    }
+    const elements = [];
+    const byId = new Map();
+    // The DOM element behind each captured record, kept only long enough for
+    // the second, post-walk pass below to hit-test it -- `visit` is a pre-order
+    // walk, so an *unrelated* overlay elsewhere in the document (a modal
+    // appended near the end of `<body>`, positioned over content captured
+    // earlier) would not have an id yet if this ran inline during the walk.
+    const domById = new Map();
+    let nextId = 0;
+    let truncated = false;
+    // `NotMeasured` counters. See the doc comment on the type: this walk never
+    // enters a shadow root or an iframe document, so these are the only record
+    // of what it walked past.
+    let shadowRootsOpen = 0;
+    let iframesSameOrigin = 0;
+    let iframesUnknownOrigin = 0;
+    function visit(el, parentId) {
+        if (elements.length >= MAX_ELEMENTS) {
+            truncated = true;
+            return;
+        }
+        // SVG-namespace elements report a lowercase `tagName`, unlike HTML
+        // elements which are always uppercase — so this comparison must normalize
+        // case or the skip never fires for SVG internals.
+        const tagName = el.tagName.toUpperCase();
+        if (SKIPPED_TAGS.has(tagName))
+            return;
+        // `NotMeasured`: this walk reads `el.children`, which is light-DOM only --
+        // it never descends into a shadow root or an iframe document, so this is
+        // the only place either is ever seen at all.
+        //
+        // An *open* shadow root is detectable after the fact: `el.shadowRoot` is
+        // the live reference `attachShadow({mode:'open'})` returned. A *closed*
+        // one returns `null` from that same property -- indistinguishable from
+        // "no shadow root here" -- so closed roots stay uncounted; see the
+        // `NotMeasured` doc comment for why the header reports that as 'unknown'
+        // rather than guessing zero.
+        if (el.shadowRoot)
+            shadowRootsOpen++;
+        if (tagName === 'IFRAME') {
+            // `contentDocument` is `null` and does not throw whenever this document
+            // cannot read the frame's document -- but that is not only true
+            // cross-origin. It is also `null` for a same-origin frame on `file://`
+            // (no origin to compare against), a `sandbox`-ed frame missing
+            // `allow-same-origin` (an opaque origin, even when the `src` is the same
+            // server), and a frame that has not navigated yet. All four look
+            // identical from here, so a `null` reading can only ever mean "this walk
+            // cannot resolve the origin", never a positive cross-origin
+            // classification -- that is what `unknownOrigin` is for. A non-null
+            // `contentDocument` *is* a reliable same-origin signal, so that half
+            // stays a real count.
+            if (el.contentDocument !== null)
+                iframesSameOrigin++;
+            else
+                iframesUnknownOrigin++;
+        }
+        const cs = getComputedStyle(el);
+        const rect = el.getBoundingClientRect();
+        const opacity = Number.parseFloat(cs.getPropertyValue('opacity'));
+        const display = cs.getPropertyValue('display');
+        const visibility = cs.getPropertyValue('visibility');
+        const visible = display !== 'none' &&
+            visibility !== 'hidden' &&
+            !(Number.isFinite(opacity) && opacity === 0) &&
+            rect.width > 0 &&
+            rect.height > 0;
+        const id = `e${nextId}`;
+        nextId++;
+        let testId = null;
+        for (const attr of TESTID_ATTRS) {
+            const value = el.getAttribute(attr);
+            if (value) {
+                testId = value;
+                break;
+            }
+        }
+        const role = computedRole(el);
+        const record = {
+            id,
+            tag: el.tagName.toLowerCase(),
+            testId,
+            domId: el.id || null,
+            role,
+            name: accessibleName(el, role),
+            className: el.getAttribute('class') ?? '',
+            headingLevel: headingLevel(el),
+            rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
+            scrollWidth: el.scrollWidth,
+            scrollHeight: el.scrollHeight,
+            clientWidth: el.clientWidth,
+            clientHeight: el.clientHeight,
+            overflowX: cs.getPropertyValue('overflow-x'),
+            overflowY: cs.getPropertyValue('overflow-y'),
+            position: cs.getPropertyValue('position'),
+            display,
+            visibility,
+            opacity: Number.isFinite(opacity) ? opacity : 1,
+            margin: boxSides(cs, 'margin'),
+            padding: boxSides(cs, 'padding'),
+            gap: {
+                row: Number.parseFloat(cs.getPropertyValue('row-gap')) || 0,
+                column: Number.parseFloat(cs.getPropertyValue('column-gap')) || 0,
+            },
+            border: boxSides(cs, 'border'),
+            color: cs.getPropertyValue('color'),
+            backgroundColor: cs.getPropertyValue('background-color'),
+            backgroundImage: capBackgroundImage(cs.getPropertyValue('background-image')),
+            textShadow: cs.getPropertyValue('text-shadow').slice(0, COLOR_TOKEN_CAP),
+            textStrokeWidth: cs.getPropertyValue('-webkit-text-stroke-width'),
+            textStrokeColor: cs.getPropertyValue('-webkit-text-stroke-color'),
+            fontSize: cs.getPropertyValue('font-size'),
+            fontWeight: Number.parseFloat(cs.getPropertyValue('font-weight')) || 400,
+            textAlign: cs.getPropertyValue('text-align'),
+            flexDirection: cs.getPropertyValue('flex-direction'),
+            gridTemplateColumns: cs.getPropertyValue('grid-template-columns'),
+            textOverflow: cs.getPropertyValue('text-overflow'),
+            whiteSpace: cs.getPropertyValue('white-space'),
+            overflowWrap: cs.getPropertyValue('overflow-wrap'),
+            text: ownText(el),
+            parentId,
+            childIds: [],
+            visible,
+            ariaExpanded: el.getAttribute('aria-expanded'),
+            // Filled in by the second pass below, once every id in the document
+            // exists to resolve a hit-test against -- see `domById`'s doc comment.
+            hitStackIds: null,
+            paintOrder: null,
+        };
+        elements.push(record);
+        byId.set(id, record);
+        domById.set(id, el);
+        if (parentId)
+            byId.get(parentId)?.childIds.push(id);
+        for (const child of childrenOf(el)) {
+            if (elements.length >= MAX_ELEMENTS) {
+                truncated = true;
+                break;
+            }
+            visit(child, id);
+        }
+    }
+    visit(document.body, null);
+    // The overlap signal `snapshot/color.ts` needs to tell "a real ancestor
+    // backdrop" from "some unrelated element painted over or behind this
+    // text" -- see `ElementRecord.hitStackIds`'s doc comment for why this is a
+    // second pass rather than done inline above. Gated on the same "visible,
+    // has its own text" condition the color fact itself uses (§4 of
+    // `docs/notes/03-color.md`): no text, no ink-on-backdrop question to probe,
+    // so no reason to pay for a hit test.
+    const reverseId = new Map();
+    for (const [id, domEl] of domById)
+        reverseId.set(domEl, id);
+    for (const [id, domEl] of domById) {
+        const record = byId.get(id);
+        if (!record?.visible || !record.text)
+            continue;
+        const rect = domEl.getBoundingClientRect();
+        const cx = rect.x + rect.width / 2;
+        const cy = rect.y + rect.height / 2;
+        const stack = document.elementsFromPoint(cx, cy);
+        const ids = [];
+        for (const hit of stack) {
+            const hitId = reverseId.get(hit);
+            // An entry this capture never assigned an id to (an `SVG` internal, a
+            // node past the element cap) carries no signal `color.ts` can act on --
+            // dropped rather than guessed at, the same discipline `NotMeasured`
+            // uses for what a capture walked past without measuring.
+            if (hitId)
+                ids.push(hitId);
+        }
+        record.hitStackIds = ids;
+    }
+    // `<html>` (`documentElement`) is never part of `elements` -- this walk
+    // starts at `<body>` (see this function's own `visit(document.body, null)`
+    // call below) -- so without reading it here, a compositing walk that runs
+    // off the top of the ancestor chain has no way to know the browser's real
+    // default canvas fill and no honest option but to guess (A2). See
+    // `DocumentBackground`'s doc comment.
+    const htmlStyle = getComputedStyle(document.documentElement);
+    return {
+        elements,
+        truncated,
+        viewport: { width: window.innerWidth, height: window.innerHeight },
+        notMeasured: {
+            shadowRoots: { open: shadowRootsOpen, closed: 'unknown' },
+            iframes: {
+                sameOrigin: iframesSameOrigin,
+                // This walk has no positive signal for cross-origin -- see the check
+                // above -- so it never asserts one. An unreachable frame is always
+                // counted as `unknownOrigin`, never guessed into `crossOrigin`.
+                crossOrigin: 0,
+                unknownOrigin: iframesUnknownOrigin,
+            },
+        },
+        documentBackground: {
+            backgroundColor: htmlStyle.getPropertyValue('background-color'),
+            colorScheme: htmlStyle.getPropertyValue('color-scheme'),
+        },
+    };
+}

package/dist/snapshot/collect.d.cts

@@ -0,0 +1,18 @@
+/**
+ * `collectSnapshot` is a function reference, not a call site — the capture path
+ * passes it straight to `page.evaluate(collectSnapshot)`. Its body executes
+ * inside the page, so it must not close over or import anything that only
+ * exists on the Node side; only type-only imports (erased at compile time) are
+ * safe, and every constant the walk needs lives inside the function body.
+ *
+ * This is the **portable** capture path: it works in Chromium, Firefox and
+ * WebKit alike. The CDP fast path in `cdp.ts` is ~6x quicker and returns facts
+ * this cannot (paint order, real line boxes, blended backgrounds) but is
+ * Chromium-only and experimental, so this one is not going away.
+ *
+ * Ported from the prototype's `snapshot/collect.ts`, with the computed role and
+ * accessible name that step 2 proved rung 3 cannot work without. Clipping is
+ * deliberately *not* computed here — see `clip.ts`.
+ */
+import type { Snapshot } from "./types.cjs";
+export declare function collectSnapshot(): Snapshot;

package/dist/snapshot/collect.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `collectSnapshot` is a function reference, not a call site — the capture path
+ * passes it straight to `page.evaluate(collectSnapshot)`. Its body executes
+ * inside the page, so it must not close over or import anything that only
+ * exists on the Node side; only type-only imports (erased at compile time) are
+ * safe, and every constant the walk needs lives inside the function body.
+ *
+ * This is the **portable** capture path: it works in Chromium, Firefox and
+ * WebKit alike. The CDP fast path in `cdp.ts` is ~6x quicker and returns facts
+ * this cannot (paint order, real line boxes, blended backgrounds) but is
+ * Chromium-only and experimental, so this one is not going away.
+ *
+ * Ported from the prototype's `snapshot/collect.ts`, with the computed role and
+ * accessible name that step 2 proved rung 3 cannot work without. Clipping is
+ * deliberately *not* computed here — see `clip.ts`.
+ */
+import type { Snapshot } from "./types.js";
+export declare function collectSnapshot(): Snapshot;