@michaelmagan/dnumb 0.1.0

package/dist/snapshot/limits.js

@@ -0,0 +1,65 @@
+/**
+ * Limits shared by both capture paths.
+ *
+ * They live here rather than in either collector because a capture has to mean
+ * the same thing whichever path produced it. The first benchmark caught them
+ * disagreeing: on a Wikipedia article the in-page walk stopped at 5,000
+ * elements and reported `truncated: true`, while the CDP path returned 6,927
+ * and hardcoded `truncated: false`. Two captures of one page that are not
+ * comparable, and a flag that silently means "maybe".
+ */
+/**
+ * The element ceiling. Not a performance guard -- both paths are fast enough
+ * at this size -- but a token guard: a digest of 5,000 elements is already far
+ * past what any consumer will read, and past it the honest answer is
+ * `truncated: true` plus a narrower capture.
+ */
+export const MAX_ELEMENTS = 5000;
+/** Own-text preview length, in characters. */
+export const TEXT_PREVIEW_LENGTH = 60;
+/** Accessible-name length, in characters. */
+export const NAME_LENGTH = 80;
+/** Attributes treated as a stable test id, in priority order. */
+export const TESTID_ATTRS = ['data-testid', 'data-test-id', 'data-test', 'data-qa'];
+/** Tags whose subtrees carry no layout worth measuring. */
+export const SKIPPED_TAGS = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE', 'SVG'];
+/**
+ * `background-image` / `text-shadow` string cap, in characters.
+ *
+ * A gradient or shadow's computed value can run to hundreds of characters
+ * (many stops, multiple shadows) — `docs/notes/03-color.md` §7 estimates real
+ * bundle growth at ~105 bytes/element for the naive uncapped fields, so this
+ * caps the two least-bounded ones at the point of capture rather than on
+ * render. `snapshot/color.ts` only ever reads the first and last gradient
+ * stop and the first shadow color — but "only reads the ends" is exactly
+ * why a *plain prefix* cut is wrong for `background-image`: a real 137-char
+ * gradient truncated at 120 chars loses its own last stop, the one the
+ * gradient token needs (verified against a real capture; A4). See
+ * `capBackgroundImage` below for the fix. `text-shadow` has no such gap —
+ * `firstShadowColor` only ever reads the *first* comma-separated segment's
+ * first color token, so a plain prefix cut is still exactly right for it.
+ */
+export const COLOR_TOKEN_CAP = 120;
+/**
+ * Caps `raw` to `cap` characters while preserving *both* ends, joined by an
+ * ellipsis, instead of a plain prefix cut. `background-image`'s only two
+ * downstream readers (`resolveBackdrop`'s gradient-stop parse and `q color`'s
+ * display) need the *first* and *last* color token, never the middle — a
+ * plain `slice(0, cap)` can and does drop the last stop off a real multi-stop
+ * gradient whose computed string runs past `cap` (A4). Splitting the budget
+ * across both ends fixes that regardless of how many stops sit in the middle:
+ * the string might read `linear-gradient(...) 0%, …, rgb(255,255,255) 100%)`
+ * instead of every stop, but the two that matter always survive.
+ *
+ * `collect.ts` restates this inline (`page.evaluate` serializes only its own
+ * function source, so it cannot import this module) — kept in sync by
+ * `test/unit/limits.test.ts`, the same discipline `MAX_ELEMENTS` and the
+ * other capture-path constants already use.
+ */
+export function capBackgroundImage(raw, cap = COLOR_TOKEN_CAP) {
+    if (raw.length <= cap)
+        return raw;
+    const ELLIPSIS = '…';
+    const half = Math.max(0, Math.floor((cap - ELLIPSIS.length) / 2));
+    return `${raw.slice(0, half)}${ELLIPSIS}${raw.slice(raw.length - half)}`;
+}

package/dist/snapshot/not-measured.cjs

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatNotMeasured = formatNotMeasured;
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+function iframeSegment(iframes) {
+    const total = iframes.sameOrigin + iframes.crossOrigin + iframes.unknownOrigin;
+    if (total === 0)
+        return null;
+    const detail = [];
+    if (iframes.crossOrigin > 0)
+        detail.push(`${iframes.crossOrigin} cross-origin`);
+    if (iframes.unknownOrigin > 0)
+        detail.push(`${iframes.unknownOrigin} origin unknown`);
+    return `${plural(total, 'iframe')}${detail.length > 0 ? ` (${detail.join(', ')})` : ''}`;
+}
+function shadowRootSegment(shadowRoots) {
+    // `closed: 'unknown'` is a constant property of the *capture path*, not a
+    // measurement of *this page* -- every walk capture and every legacy bundle
+    // carries it regardless of what the page contains, so it does not belong on
+    // this counted, page-specific line. That permanent caveat belongs on the
+    // digest identity line's strategy segment instead (`— walk (closed shadow
+    // roots undetectable)`, in `digest/render.ts`) -- see the `NotMeasured` doc
+    // comment for why the count is genuinely unknowable here. This line reports
+    // only what was actually counted: the real open-root total, when there is
+    // one.
+    if (shadowRoots.closed === 'unknown') {
+        if (shadowRoots.open === 0)
+            return null;
+        return plural(shadowRoots.open, 'open shadow root');
+    }
+    const total = shadowRoots.open + shadowRoots.closed;
+    if (total === 0)
+        return null;
+    const detail = shadowRoots.closed > 0 ? ` (${shadowRoots.closed} closed)` : '';
+    return `${plural(total, 'shadow root')}${detail}`;
+}
+/** `"not measured: 2 iframes (1 cross-origin), 14 shadow roots"`, or `null` when there is nothing to disclose. */
+function formatNotMeasured(notMeasured) {
+    const segments = [
+        iframeSegment(notMeasured.iframes),
+        shadowRootSegment(notMeasured.shadowRoots),
+    ].filter((segment) => segment !== null);
+    return segments.length > 0 ? `not measured: ${segments.join(', ')}` : null;
+}

package/dist/snapshot/not-measured.d.cts

@@ -0,0 +1,14 @@
+/**
+ * Renders `NotMeasured` into the one line both the digest header and the CLI
+ * query verbs show. One formatter so the two never describe the same counts
+ * in different words -- the failure mode `digest/render.ts`'s own header
+ * lines are built to avoid for every other fact this package prints.
+ *
+ * Returns `null` when there is nothing to disclose, so every call site can
+ * treat "print nothing" and "call this" as the same decision -- a page with
+ * no shadow DOM and no iframes must not gain a line just because the field
+ * exists on the record.
+ */
+import type { NotMeasured } from "./types.cjs";
+/** `"not measured: 2 iframes (1 cross-origin), 14 shadow roots"`, or `null` when there is nothing to disclose. */
+export declare function formatNotMeasured(notMeasured: NotMeasured): string | null;

package/dist/snapshot/not-measured.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Renders `NotMeasured` into the one line both the digest header and the CLI
+ * query verbs show. One formatter so the two never describe the same counts
+ * in different words -- the failure mode `digest/render.ts`'s own header
+ * lines are built to avoid for every other fact this package prints.
+ *
+ * Returns `null` when there is nothing to disclose, so every call site can
+ * treat "print nothing" and "call this" as the same decision -- a page with
+ * no shadow DOM and no iframes must not gain a line just because the field
+ * exists on the record.
+ */
+import type { NotMeasured } from "./types.js";
+/** `"not measured: 2 iframes (1 cross-origin), 14 shadow roots"`, or `null` when there is nothing to disclose. */
+export declare function formatNotMeasured(notMeasured: NotMeasured): string | null;

package/dist/snapshot/not-measured.js

@@ -0,0 +1,41 @@
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+function iframeSegment(iframes) {
+    const total = iframes.sameOrigin + iframes.crossOrigin + iframes.unknownOrigin;
+    if (total === 0)
+        return null;
+    const detail = [];
+    if (iframes.crossOrigin > 0)
+        detail.push(`${iframes.crossOrigin} cross-origin`);
+    if (iframes.unknownOrigin > 0)
+        detail.push(`${iframes.unknownOrigin} origin unknown`);
+    return `${plural(total, 'iframe')}${detail.length > 0 ? ` (${detail.join(', ')})` : ''}`;
+}
+function shadowRootSegment(shadowRoots) {
+    // `closed: 'unknown'` is a constant property of the *capture path*, not a
+    // measurement of *this page* -- every walk capture and every legacy bundle
+    // carries it regardless of what the page contains, so it does not belong on
+    // this counted, page-specific line. That permanent caveat belongs on the
+    // digest identity line's strategy segment instead (`— walk (closed shadow
+    // roots undetectable)`, in `digest/render.ts`) -- see the `NotMeasured` doc
+    // comment for why the count is genuinely unknowable here. This line reports
+    // only what was actually counted: the real open-root total, when there is
+    // one.
+    if (shadowRoots.closed === 'unknown') {
+        if (shadowRoots.open === 0)
+            return null;
+        return plural(shadowRoots.open, 'open shadow root');
+    }
+    const total = shadowRoots.open + shadowRoots.closed;
+    if (total === 0)
+        return null;
+    const detail = shadowRoots.closed > 0 ? ` (${shadowRoots.closed} closed)` : '';
+    return `${plural(total, 'shadow root')}${detail}`;
+}
+/** `"not measured: 2 iframes (1 cross-origin), 14 shadow roots"`, or `null` when there is nothing to disclose. */
+export function formatNotMeasured(notMeasured) {
+    const segments = [
+        iframeSegment(notMeasured.iframes),
+        shadowRootSegment(notMeasured.shadowRoots),
+    ].filter((segment) => segment !== null);
+    return segments.length > 0 ? `not measured: ${segments.join(', ')}` : null;
+}

package/dist/snapshot/types.cjs

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/snapshot/types.d.cts

@@ -0,0 +1,238 @@
+/**
+ * The record shape everything downstream reads. `collect.ts` builds
+ * `ElementRecord[]` inside the page; nothing in this file depends on the DOM or
+ * on Playwright, so pure Node-side code — the digest, the diff, the query
+ * verbs — can import it freely.
+ *
+ * Ported from the prototype's `snapshot/types.ts`, with the fields the step-2
+ * spike proved load-bearing added: a *computed* role and accessible name (the
+ * prototype captured `getAttribute('role')`, which is null on nearly every real
+ * element), and the clip fact.
+ */
+import type { BoxSides, Rect } from "../analysis/types.cjs";
+export type { BoxSides, Rect };
+/**
+ * Why an element is not fully on screen, and the facts needed to judge whether
+ * that matters.
+ *
+ * Carrying `overflow` and `scrollable` beside the hidden extents is the
+ * facts-with-counter-facts model: a clipped box inside `overflow:auto` is a
+ * scroll region, and the same box inside `overflow:hidden` is content nobody
+ * can reach. The tool reports both and does not decide which one this is.
+ */
+export interface ClipFact {
+    /** Id of the nearest ancestor whose `overflow` is not `visible`. */
+    by: string;
+    byTag: string;
+    /** The clipper's `overflow-x`, or `x/y` when the two axes differ. */
+    overflow: string;
+    /** How far the element extends past the clipper on each side, in px. */
+    hidden: BoxSides;
+    /** The part of the element that survives the clip. */
+    visible: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Whether a user could scroll the clipper to reveal the hidden part.
+     * Not the same question as `scrollHeight > clientHeight`: an
+     * `overflow:hidden` box has scroll extent and no reachability.
+     */
+    scrollable: boolean;
+}
+export interface ElementRecord {
+    /** Stable within one capture only — not a DOM id, not stable across runs. */
+    id: string;
+    tag: string;
+    /** `data-testid` / `data-test-id` / `data-test` / `data-qa`, first one present. */
+    testId: string | null;
+    /** The authored `id` attribute, unfiltered. Identity applies its own guard. */
+    domId: string | null;
+    /** Computed role — explicit `role` if present, otherwise the implicit one. */
+    role: string | null;
+    /** Computed accessible name. */
+    name: string | null;
+    className: string;
+    /** From the tag (`h1`-`h6`) or `aria-level`; `null` for non-headings. */
+    headingLevel: number | null;
+    rect: Rect;
+    scrollWidth: number;
+    scrollHeight: number;
+    clientWidth: number;
+    clientHeight: number;
+    overflowX: string;
+    overflowY: string;
+    position: string;
+    display: string;
+    visibility: string;
+    opacity: number;
+    margin: BoxSides;
+    padding: BoxSides;
+    /** Row/column gap in px; only meaningful on grid and flex containers. */
+    gap: {
+        row: number;
+        column: number;
+    };
+    border: BoxSides;
+    color: string;
+    backgroundColor: string;
+    /**
+     * Computed `background-image`, capped to ~120 chars (both ends preserved —
+     * see `limits.ts#capBackgroundImage`), `'none'` when unset. Not captured
+     * for its own sake — it is the counter-fact that invalidates a resolved
+     * backdrop: a gradient or `url()` background means no single color exists
+     * behind text painted over it. See `snapshot/color.ts` and
+     * `docs/notes/03-color.md` §2–3.
+     *
+     * Required, like every other field on this interface — both real capture
+     * paths always set it to a string. `null` is a distinct, legitimate third
+     * state: "this specific capture never measured this field at all" — a
+     * bundle written before color capture existed, read back through
+     * `bundle.ts#normalizeElement`, which backfills `null` here rather than the
+     * false positive claim `'none'` used to be (A3). `resolveBackdrop` and
+     * `hasPaint` in `snapshot/color.ts` treat `null` the same way they treat an
+     * unresolvable non-ancestor overlay: refuse to guess, report
+     * `unmeasured (not-captured ...)`, never silently assume "no image here".
+     *
+     * A record built by hand (not via `capture()`/`parseBundle`) that omits
+     * this field entirely (`undefined`, not `null`), or any of the other three
+     * color-capture fields below, gets a clear thrown error naming the missing
+     * field the first time `snapshot/color.ts` needs it, rather than an
+     * internal `TypeError`; see `requireColorField` there.
+     */
+    backgroundImage: string | null;
+    /**
+     * Computed `text-shadow`, capped to ~120 chars, `'none'` when unset. A
+     * counter-fact only — dnumb cannot measure what a shadow does perceptually
+     * to a low-contrast ratio, so it discloses that one exists rather than
+     * guessing. Required — see `backgroundImage`'s doc comment above.
+     */
+    textShadow: string;
+    /**
+     * Computed `-webkit-text-stroke-width` / `-color`. `'0px'` when unset.
+     * Required — see `backgroundImage`'s doc comment above.
+     */
+    textStrokeWidth: string;
+    textStrokeColor: string;
+    fontSize: string;
+    fontWeight: number;
+    textAlign: string;
+    flexDirection: string;
+    gridTemplateColumns: string;
+    /**
+     * The three properties that decide what overflowing content *does*. Without
+     * them a measurement of 147px past the box is unreadable: it is truncation if
+     * the box clips, a scroll region if it scrolls, harmless paint-over if the
+     * overflow is visible, and not a text problem at all if the text can wrap.
+     */
+    textOverflow: string;
+    whiteSpace: string;
+    overflowWrap: string;
+    /** First ~60 chars of the element's own direct text content, trimmed. */
+    text: string;
+    parentId: string | null;
+    childIds: string[];
+    /** `false` if `display:none`, `visibility:hidden`, `opacity:0`, or zero size. */
+    visible: boolean;
+    /** Present only when the element extends past a clipping ancestor. */
+    clip?: ClipFact;
+    ariaExpanded: string | null;
+    /**
+     * `document.elementsFromPoint` at this element's own box centre, front to
+     * back, resolved to the ids of elements this capture knows about -- the
+     * `walk` path's raw input for detecting a non-ancestor element painted over
+     * or behind this one's text (`snapshot/color.ts`'s overlap check). Computed
+     * only for a visible element with its own direct text (the same gate the
+     * color fact itself uses -- no text, no ink-on-backdrop question to
+     * probe), `null` otherwise. Always `null` on a `cdp` capture, which derives
+     * the same signal from `paintOrder` plus rect intersection instead: see
+     * `docs/notes/03-color.md` §3 and §7 for why the two paths take different
+     * inputs to the identical question.
+     */
+    hitStackIds: string[] | null;
+    /**
+     * CDP `DOMSnapshot`'s paint order for this node. Combined Node-side with
+     * rect intersection as the `cdp` path's overlap signal, in place of
+     * `hitStackIds` -- see that field's doc comment. `null` on a `walk`
+     * capture, and on a `cdp` node with no layout row (nothing painted).
+     */
+    paintOrder: number | null;
+}
+/**
+ * `<html>` (`documentElement`)'s own computed `background-color` and
+ * `color-scheme` — the two facts that decide what the browser's default
+ * canvas fill actually is, which is the *true* terminal layer a compositing
+ * walk that runs out of ancestors reaches (A2). Neither capture path visits
+ * `<html>` as part of the element tree (both start at `<body>` — see
+ * `collect.ts`/`cdp.ts`), so without this, `resolveBackdrop`'s ancestor walk
+ * has no way to see it and no honest way to know what is behind a
+ * fully-transparent `<body>`: guessing white is exactly the fabrication this
+ * package exists to refuse, since `color-scheme: dark` with no explicit
+ * background anywhere measures as `rgb(18, 18, 18)` on real Chromium, not
+ * white (verified, `docs/notes/03-color.md` and this feature's own probes).
+ *
+ * `colorScheme` is the raw computed string (`'normal'`, `'light'`, `'dark'`,
+ * `'light dark'`, ...) rather than a resolved color, because a page that
+ * lists both `light` and `dark` genuinely has no single determinable default
+ * — it depends on the reader's OS preference, which this capture cannot see
+ * — and `snapshot/color.ts#canvasBackground` reports that honestly as
+ * `unmeasured (canvas)` rather than picking one.
+ */
+export interface DocumentBackground {
+    backgroundColor: string;
+    colorScheme: string;
+}
+/**
+ * Content this capture walked past without measuring it: shadow DOM and iframe
+ * documents that no `ElementRecord` in `elements` describes. Neither capture
+ * path enters an iframe, and the portable walk does not enter a shadow root
+ * either — so an element living inside one is not folded, not dropped, not
+ * marked invisible; it is simply absent, with nothing on this record to say
+ * so. That absence is indistinguishable from "does not exist" unless it is
+ * disclosed here.
+ *
+ * A closed shadow root has no signal at all from outside it after the fact —
+ * `Element.shadowRoot` is `null` for both "no shadow root" and "closed shadow
+ * root", and nothing else in the DOM tells them apart post-hoc. `'unknown'` on
+ * that one field is not a placeholder for zero; a portable-walk capture
+ * genuinely cannot say whether the count is 0 or 40, and reporting 0 would be
+ * exactly the false zero this package exists to refuse. Every other field here
+ * is always a real, counted number.
+ */
+export interface NotMeasured {
+    shadowRoots: {
+        open: number;
+        closed: number | 'unknown';
+    };
+    iframes: {
+        sameOrigin: number;
+        crossOrigin: number;
+        /** Encountered, but this capture path could not resolve its origin. */
+        unknownOrigin: number;
+    };
+}
+export interface Snapshot {
+    elements: ElementRecord[];
+    /** True when the collector hit its element cap before finishing the tree. */
+    truncated: boolean;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Optional only so a hand-built `Snapshot` in a test fixture need not name a
+     * value it has no opinion about. Both real capture paths — `collect.ts` and
+     * `cdp.ts` — always set it; `Bundle.notMeasured` is the field that actually
+     * has to be trusted, and it is not optional there.
+     */
+    notMeasured?: NotMeasured;
+    /**
+     * See `DocumentBackground`'s doc comment. Optional for the same reason
+     * `notMeasured` is: both real capture paths always set it; a hand-built
+     * `Snapshot` need not. `| null` because `Bundle.documentBackground` (which
+     * structurally widens this same field — see `bundle.ts`) uses `null` for
+     * "a real bundle that predates color capture", and the two need to stay
+     * assignable to each other.
+     */
+    documentBackground?: DocumentBackground | null;
+}

package/dist/snapshot/types.d.ts

@@ -0,0 +1,238 @@
+/**
+ * The record shape everything downstream reads. `collect.ts` builds
+ * `ElementRecord[]` inside the page; nothing in this file depends on the DOM or
+ * on Playwright, so pure Node-side code — the digest, the diff, the query
+ * verbs — can import it freely.
+ *
+ * Ported from the prototype's `snapshot/types.ts`, with the fields the step-2
+ * spike proved load-bearing added: a *computed* role and accessible name (the
+ * prototype captured `getAttribute('role')`, which is null on nearly every real
+ * element), and the clip fact.
+ */
+import type { BoxSides, Rect } from "../analysis/types.js";
+export type { BoxSides, Rect };
+/**
+ * Why an element is not fully on screen, and the facts needed to judge whether
+ * that matters.
+ *
+ * Carrying `overflow` and `scrollable` beside the hidden extents is the
+ * facts-with-counter-facts model: a clipped box inside `overflow:auto` is a
+ * scroll region, and the same box inside `overflow:hidden` is content nobody
+ * can reach. The tool reports both and does not decide which one this is.
+ */
+export interface ClipFact {
+    /** Id of the nearest ancestor whose `overflow` is not `visible`. */
+    by: string;
+    byTag: string;
+    /** The clipper's `overflow-x`, or `x/y` when the two axes differ. */
+    overflow: string;
+    /** How far the element extends past the clipper on each side, in px. */
+    hidden: BoxSides;
+    /** The part of the element that survives the clip. */
+    visible: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Whether a user could scroll the clipper to reveal the hidden part.
+     * Not the same question as `scrollHeight > clientHeight`: an
+     * `overflow:hidden` box has scroll extent and no reachability.
+     */
+    scrollable: boolean;
+}
+export interface ElementRecord {
+    /** Stable within one capture only — not a DOM id, not stable across runs. */
+    id: string;
+    tag: string;
+    /** `data-testid` / `data-test-id` / `data-test` / `data-qa`, first one present. */
+    testId: string | null;
+    /** The authored `id` attribute, unfiltered. Identity applies its own guard. */
+    domId: string | null;
+    /** Computed role — explicit `role` if present, otherwise the implicit one. */
+    role: string | null;
+    /** Computed accessible name. */
+    name: string | null;
+    className: string;
+    /** From the tag (`h1`-`h6`) or `aria-level`; `null` for non-headings. */
+    headingLevel: number | null;
+    rect: Rect;
+    scrollWidth: number;
+    scrollHeight: number;
+    clientWidth: number;
+    clientHeight: number;
+    overflowX: string;
+    overflowY: string;
+    position: string;
+    display: string;
+    visibility: string;
+    opacity: number;
+    margin: BoxSides;
+    padding: BoxSides;
+    /** Row/column gap in px; only meaningful on grid and flex containers. */
+    gap: {
+        row: number;
+        column: number;
+    };
+    border: BoxSides;
+    color: string;
+    backgroundColor: string;
+    /**
+     * Computed `background-image`, capped to ~120 chars (both ends preserved —
+     * see `limits.ts#capBackgroundImage`), `'none'` when unset. Not captured
+     * for its own sake — it is the counter-fact that invalidates a resolved
+     * backdrop: a gradient or `url()` background means no single color exists
+     * behind text painted over it. See `snapshot/color.ts` and
+     * `docs/notes/03-color.md` §2–3.
+     *
+     * Required, like every other field on this interface — both real capture
+     * paths always set it to a string. `null` is a distinct, legitimate third
+     * state: "this specific capture never measured this field at all" — a
+     * bundle written before color capture existed, read back through
+     * `bundle.ts#normalizeElement`, which backfills `null` here rather than the
+     * false positive claim `'none'` used to be (A3). `resolveBackdrop` and
+     * `hasPaint` in `snapshot/color.ts` treat `null` the same way they treat an
+     * unresolvable non-ancestor overlay: refuse to guess, report
+     * `unmeasured (not-captured ...)`, never silently assume "no image here".
+     *
+     * A record built by hand (not via `capture()`/`parseBundle`) that omits
+     * this field entirely (`undefined`, not `null`), or any of the other three
+     * color-capture fields below, gets a clear thrown error naming the missing
+     * field the first time `snapshot/color.ts` needs it, rather than an
+     * internal `TypeError`; see `requireColorField` there.
+     */
+    backgroundImage: string | null;
+    /**
+     * Computed `text-shadow`, capped to ~120 chars, `'none'` when unset. A
+     * counter-fact only — dnumb cannot measure what a shadow does perceptually
+     * to a low-contrast ratio, so it discloses that one exists rather than
+     * guessing. Required — see `backgroundImage`'s doc comment above.
+     */
+    textShadow: string;
+    /**
+     * Computed `-webkit-text-stroke-width` / `-color`. `'0px'` when unset.
+     * Required — see `backgroundImage`'s doc comment above.
+     */
+    textStrokeWidth: string;
+    textStrokeColor: string;
+    fontSize: string;
+    fontWeight: number;
+    textAlign: string;
+    flexDirection: string;
+    gridTemplateColumns: string;
+    /**
+     * The three properties that decide what overflowing content *does*. Without
+     * them a measurement of 147px past the box is unreadable: it is truncation if
+     * the box clips, a scroll region if it scrolls, harmless paint-over if the
+     * overflow is visible, and not a text problem at all if the text can wrap.
+     */
+    textOverflow: string;
+    whiteSpace: string;
+    overflowWrap: string;
+    /** First ~60 chars of the element's own direct text content, trimmed. */
+    text: string;
+    parentId: string | null;
+    childIds: string[];
+    /** `false` if `display:none`, `visibility:hidden`, `opacity:0`, or zero size. */
+    visible: boolean;
+    /** Present only when the element extends past a clipping ancestor. */
+    clip?: ClipFact;
+    ariaExpanded: string | null;
+    /**
+     * `document.elementsFromPoint` at this element's own box centre, front to
+     * back, resolved to the ids of elements this capture knows about -- the
+     * `walk` path's raw input for detecting a non-ancestor element painted over
+     * or behind this one's text (`snapshot/color.ts`'s overlap check). Computed
+     * only for a visible element with its own direct text (the same gate the
+     * color fact itself uses -- no text, no ink-on-backdrop question to
+     * probe), `null` otherwise. Always `null` on a `cdp` capture, which derives
+     * the same signal from `paintOrder` plus rect intersection instead: see
+     * `docs/notes/03-color.md` §3 and §7 for why the two paths take different
+     * inputs to the identical question.
+     */
+    hitStackIds: string[] | null;
+    /**
+     * CDP `DOMSnapshot`'s paint order for this node. Combined Node-side with
+     * rect intersection as the `cdp` path's overlap signal, in place of
+     * `hitStackIds` -- see that field's doc comment. `null` on a `walk`
+     * capture, and on a `cdp` node with no layout row (nothing painted).
+     */
+    paintOrder: number | null;
+}
+/**
+ * `<html>` (`documentElement`)'s own computed `background-color` and
+ * `color-scheme` — the two facts that decide what the browser's default
+ * canvas fill actually is, which is the *true* terminal layer a compositing
+ * walk that runs out of ancestors reaches (A2). Neither capture path visits
+ * `<html>` as part of the element tree (both start at `<body>` — see
+ * `collect.ts`/`cdp.ts`), so without this, `resolveBackdrop`'s ancestor walk
+ * has no way to see it and no honest way to know what is behind a
+ * fully-transparent `<body>`: guessing white is exactly the fabrication this
+ * package exists to refuse, since `color-scheme: dark` with no explicit
+ * background anywhere measures as `rgb(18, 18, 18)` on real Chromium, not
+ * white (verified, `docs/notes/03-color.md` and this feature's own probes).
+ *
+ * `colorScheme` is the raw computed string (`'normal'`, `'light'`, `'dark'`,
+ * `'light dark'`, ...) rather than a resolved color, because a page that
+ * lists both `light` and `dark` genuinely has no single determinable default
+ * — it depends on the reader's OS preference, which this capture cannot see
+ * — and `snapshot/color.ts#canvasBackground` reports that honestly as
+ * `unmeasured (canvas)` rather than picking one.
+ */
+export interface DocumentBackground {
+    backgroundColor: string;
+    colorScheme: string;
+}
+/**
+ * Content this capture walked past without measuring it: shadow DOM and iframe
+ * documents that no `ElementRecord` in `elements` describes. Neither capture
+ * path enters an iframe, and the portable walk does not enter a shadow root
+ * either — so an element living inside one is not folded, not dropped, not
+ * marked invisible; it is simply absent, with nothing on this record to say
+ * so. That absence is indistinguishable from "does not exist" unless it is
+ * disclosed here.
+ *
+ * A closed shadow root has no signal at all from outside it after the fact —
+ * `Element.shadowRoot` is `null` for both "no shadow root" and "closed shadow
+ * root", and nothing else in the DOM tells them apart post-hoc. `'unknown'` on
+ * that one field is not a placeholder for zero; a portable-walk capture
+ * genuinely cannot say whether the count is 0 or 40, and reporting 0 would be
+ * exactly the false zero this package exists to refuse. Every other field here
+ * is always a real, counted number.
+ */
+export interface NotMeasured {
+    shadowRoots: {
+        open: number;
+        closed: number | 'unknown';
+    };
+    iframes: {
+        sameOrigin: number;
+        crossOrigin: number;
+        /** Encountered, but this capture path could not resolve its origin. */
+        unknownOrigin: number;
+    };
+}
+export interface Snapshot {
+    elements: ElementRecord[];
+    /** True when the collector hit its element cap before finishing the tree. */
+    truncated: boolean;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Optional only so a hand-built `Snapshot` in a test fixture need not name a
+     * value it has no opinion about. Both real capture paths — `collect.ts` and
+     * `cdp.ts` — always set it; `Bundle.notMeasured` is the field that actually
+     * has to be trusted, and it is not optional there.
+     */
+    notMeasured?: NotMeasured;
+    /**
+     * See `DocumentBackground`'s doc comment. Optional for the same reason
+     * `notMeasured` is: both real capture paths always set it; a hand-built
+     * `Snapshot` need not. `| null` because `Bundle.documentBackground` (which
+     * structurally widens this same field — see `bundle.ts`) uses `null` for
+     * "a real bundle that predates color capture", and the two need to stay
+     * assignable to each other.
+     */
+    documentBackground?: DocumentBackground | null;
+}

package/dist/snapshot/types.js

@@ -0,0 +1 @@
+export {};