@michaelmagan/dnumb 0.1.0

package/dist/snapshot/facts.cjs

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OVERFLOW_EPSILON = void 0;
+exports.factsFor = factsFor;
+exports.renderFacts = renderFacts;
+exports.factsForAll = factsForAll;
+/**
+ * Subpixel layout noise. Below this, an "overflow" is a rounding artefact.
+ * Exported so `render.ts`'s fold variance uses the same threshold rather than
+ * its own magic number -- a fold reporting a 1px spread that is really 0.2px
+ * of rounding is the same bug this constant exists to prevent here.
+ */
+exports.OVERFLOW_EPSILON = 1;
+/** A box narrower or shorter than this has collapsed, whatever it intended. */
+const ZERO_EPSILON = 1;
+const CLIPS = /^(hidden|clip)$/;
+const SCROLLS = /^(auto|scroll|overlay)$/;
+/** White-space values under which text will not wrap. */
+const NO_WRAP = /^(nowrap|pre)$/;
+const round = (n) => Number.isInteger(n) ? String(n) : n.toFixed(1).replace(/\.0$/, '');
+/**
+ * What happens to content that exceeds the box on this axis.
+ *
+ * Exactly one of `clip` / `scroll` / `visible` always applies -- it is a
+ * partition of the `overflow` values. The wrapping facts are additional, and
+ * `ellipsis` suppresses `wraps` because `text-overflow` only takes effect when
+ * wrapping is already off; printing both would be restating one CSS rule twice.
+ */
+function consequences(el, axis) {
+    const overflow = axis === 'x' ? el.overflowX : el.overflowY;
+    const out = [];
+    const clips = CLIPS.test(overflow);
+    if (clips)
+        out.push('clip');
+    else if (SCROLLS.test(overflow))
+        out.push('scroll');
+    else
+        out.push('visible');
+    if (axis === 'x') {
+        const ellipsis = el.textOverflow === 'ellipsis' && (clips || SCROLLS.test(overflow));
+        if (ellipsis)
+            out.push('ellipsis');
+        else if (!NO_WRAP.test(el.whiteSpace))
+            out.push('wraps');
+        else
+            out.push('nowrap');
+    }
+    return out;
+}
+/**
+ * Whether a collapsed box is hiding anything.
+ *
+ * A `0x0` spacer is ordinary and uninteresting; a `0x1239` column with a page
+ * of content inside it is the bug the prototype measured and discarded. The
+ * difference is entirely in what the box contains, so that is what the fact
+ * carries.
+ */
+function contentOf(el, byId) {
+    if (el.text)
+        return `"${el.text}"`;
+    let text = '';
+    let elements = 0;
+    const queue = [...el.childIds];
+    while (queue.length > 0 && text.length < 40) {
+        const child = byId.get(queue.shift() ?? '');
+        if (!child)
+            continue;
+        elements++;
+        if (child.text)
+            text = `${text} ${child.text}`.trim();
+        queue.push(...child.childIds);
+    }
+    if (text)
+        return `"${text.slice(0, 40)}"`;
+    return elements > 0 ? `${elements} element${elements === 1 ? '' : 's'}` : null;
+}
+/**
+ * How much of an element an ancestor hides, and whether anyone can get to it.
+ *
+ * `attachClipFacts` has populated `ElementRecord.clip` on both capture paths
+ * since step 4, and until now nothing rendered it — the digest emitted the
+ * three fact kinds above and silently dropped this one. The V1 cold read's
+ * single strongest result came from the step-2 spike's renderer, not from
+ * shipped code, and nobody noticed because the tests asserted on `clip` the
+ * field rather than on the output.
+ *
+ * `scrollable` is the counter-fact that carries the whole meaning. A box
+ * outside an `overflow:auto` ancestor is a scroll region working as intended;
+ * the same box outside an `overflow:hidden` ancestor is content nobody can
+ * reach. Printing the extent without the reachability is a measurement the
+ * reader cannot act on.
+ */
+function clipFact(el) {
+    const clip = el.clip;
+    if (!clip)
+        return null;
+    const where = [
+        clip.hidden.top ? `${round(clip.hidden.top)}px above` : null,
+        clip.hidden.bottom ? `${round(clip.hidden.bottom)}px below` : null,
+        clip.hidden.left ? `${round(clip.hidden.left)}px left` : null,
+        clip.hidden.right ? `${round(clip.hidden.right)}px right` : null,
+    ]
+        .filter(Boolean)
+        .join(', ');
+    const visible = clip.visible.width < ZERO_EPSILON || clip.visible.height < ZERO_EPSILON
+        ? 'nothing visible'
+        : `${round(clip.visible.width)}x${round(clip.visible.height)} visible`;
+    return {
+        kind: 'clipped',
+        text: `clipped by ${clip.by} ${clip.byTag}; overflow:${clip.overflow}, ` +
+            `${clip.scrollable ? 'scrollable' : 'not scrollable'}; ${where}, ${visible}`,
+    };
+}
+/**
+ * Every fact this element has. Unconditional: no thresholds beyond subpixel
+ * noise, no severity, no suppression.
+ */
+function factsFor(el, byId) {
+    const facts = [];
+    const overflowX = el.scrollWidth - el.clientWidth;
+    if (overflowX > exports.OVERFLOW_EPSILON) {
+        facts.push({
+            kind: 'overflow-x',
+            text: `overflow-x +${round(overflowX)}px; ${consequences(el, 'x').join(', ')}`,
+        });
+    }
+    const overflowY = el.scrollHeight - el.clientHeight;
+    if (overflowY > exports.OVERFLOW_EPSILON) {
+        facts.push({
+            kind: 'overflow-y',
+            text: `overflow-y +${round(overflowY)}px; ${consequences(el, 'y').join(', ')}`,
+        });
+    }
+    // Only for elements that are still in the layout. `display:none` collapses
+    // everything to 0x0 and saying so about every hidden node is noise.
+    const collapsed = el.display !== 'none' &&
+        (el.rect.width < ZERO_EPSILON || el.rect.height < ZERO_EPSILON) &&
+        !(el.rect.width < ZERO_EPSILON && el.rect.height < ZERO_EPSILON && !el.childIds.length);
+    if (collapsed) {
+        const content = contentOf(el, byId);
+        if (content) {
+            facts.push({
+                kind: 'zero-box',
+                text: `${round(el.rect.width)}x${round(el.rect.height)} zero-box; content ${content}`,
+            });
+        }
+    }
+    const clipped = clipFact(el);
+    if (clipped)
+        facts.push(clipped);
+    return facts;
+}
+/** `[fact] [fact]` — the form these take on a digest line. */
+function renderFacts(facts) {
+    return facts.map((f) => `[${f.text}]`).join(' ');
+}
+/** Every element that has at least one fact, in document order. */
+function factsForAll(elements) {
+    const byId = new Map(elements.map((e) => [e.id, e]));
+    const out = [];
+    for (const element of elements) {
+        const facts = factsFor(element, byId);
+        if (facts.length > 0)
+            out.push({ element, facts });
+    }
+    return out;
+}

package/dist/snapshot/facts.d.cts

@@ -0,0 +1,48 @@
+/**
+ * Facts, with the facts that disambiguate them.
+ *
+ * This is the structural fix for how the prototype died. It shipped checks: a
+ * rule looked at `scrollWidth - clientWidth`, compared it to a threshold, and
+ * emitted a finding. On PR #4813 it measured `scrollWidth: 815, clientWidth:
+ * 668` -- a real 147px of truncated heading -- and threw the measurement away
+ * because the rule that owned it did not fire. Three separate false-positive
+ * classes in its final week all had the same shape: the check lacked a fact the
+ * DOM already had.
+ *
+ * So nothing here decides. A fact is emitted whenever the measurement exists,
+ * unconditionally, carrying the adjacent CSS that determines what the
+ * measurement *means*:
+ *
+ *     [overflow-x +147px; clip, ellipsis]   text is being cut off
+ *     [overflow-x +227px; clip, wraps]      same clip, text just got taller
+ *     [overflow-x +90px; scroll]            a scroll region, working as intended
+ *
+ * Same number, three different situations, and the difference is never in the
+ * number. The reader draws the conclusion; this file refuses to.
+ */
+import type { ElementRecord } from "./types.cjs";
+export type FactKind = 'overflow-x' | 'overflow-y' | 'zero-box' | 'clipped';
+export interface Fact {
+    kind: FactKind;
+    /** The rendered body, without the surrounding brackets. */
+    text: string;
+}
+/**
+ * Subpixel layout noise. Below this, an "overflow" is a rounding artefact.
+ * Exported so `render.ts`'s fold variance uses the same threshold rather than
+ * its own magic number -- a fold reporting a 1px spread that is really 0.2px
+ * of rounding is the same bug this constant exists to prevent here.
+ */
+export declare const OVERFLOW_EPSILON = 1;
+/**
+ * Every fact this element has. Unconditional: no thresholds beyond subpixel
+ * noise, no severity, no suppression.
+ */
+export declare function factsFor(el: ElementRecord, byId: Map<string, ElementRecord>): Fact[];
+/** `[fact] [fact]` — the form these take on a digest line. */
+export declare function renderFacts(facts: Fact[]): string;
+/** Every element that has at least one fact, in document order. */
+export declare function factsForAll(elements: ElementRecord[]): Array<{
+    element: ElementRecord;
+    facts: Fact[];
+}>;

package/dist/snapshot/facts.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Facts, with the facts that disambiguate them.
+ *
+ * This is the structural fix for how the prototype died. It shipped checks: a
+ * rule looked at `scrollWidth - clientWidth`, compared it to a threshold, and
+ * emitted a finding. On PR #4813 it measured `scrollWidth: 815, clientWidth:
+ * 668` -- a real 147px of truncated heading -- and threw the measurement away
+ * because the rule that owned it did not fire. Three separate false-positive
+ * classes in its final week all had the same shape: the check lacked a fact the
+ * DOM already had.
+ *
+ * So nothing here decides. A fact is emitted whenever the measurement exists,
+ * unconditionally, carrying the adjacent CSS that determines what the
+ * measurement *means*:
+ *
+ *     [overflow-x +147px; clip, ellipsis]   text is being cut off
+ *     [overflow-x +227px; clip, wraps]      same clip, text just got taller
+ *     [overflow-x +90px; scroll]            a scroll region, working as intended
+ *
+ * Same number, three different situations, and the difference is never in the
+ * number. The reader draws the conclusion; this file refuses to.
+ */
+import type { ElementRecord } from "./types.js";
+export type FactKind = 'overflow-x' | 'overflow-y' | 'zero-box' | 'clipped';
+export interface Fact {
+    kind: FactKind;
+    /** The rendered body, without the surrounding brackets. */
+    text: string;
+}
+/**
+ * Subpixel layout noise. Below this, an "overflow" is a rounding artefact.
+ * Exported so `render.ts`'s fold variance uses the same threshold rather than
+ * its own magic number -- a fold reporting a 1px spread that is really 0.2px
+ * of rounding is the same bug this constant exists to prevent here.
+ */
+export declare const OVERFLOW_EPSILON = 1;
+/**
+ * Every fact this element has. Unconditional: no thresholds beyond subpixel
+ * noise, no severity, no suppression.
+ */
+export declare function factsFor(el: ElementRecord, byId: Map<string, ElementRecord>): Fact[];
+/** `[fact] [fact]` — the form these take on a digest line. */
+export declare function renderFacts(facts: Fact[]): string;
+/** Every element that has at least one fact, in document order. */
+export declare function factsForAll(elements: ElementRecord[]): Array<{
+    element: ElementRecord;
+    facts: Fact[];
+}>;

package/dist/snapshot/facts.js

@@ -0,0 +1,161 @@
+/**
+ * Subpixel layout noise. Below this, an "overflow" is a rounding artefact.
+ * Exported so `render.ts`'s fold variance uses the same threshold rather than
+ * its own magic number -- a fold reporting a 1px spread that is really 0.2px
+ * of rounding is the same bug this constant exists to prevent here.
+ */
+export const OVERFLOW_EPSILON = 1;
+/** A box narrower or shorter than this has collapsed, whatever it intended. */
+const ZERO_EPSILON = 1;
+const CLIPS = /^(hidden|clip)$/;
+const SCROLLS = /^(auto|scroll|overlay)$/;
+/** White-space values under which text will not wrap. */
+const NO_WRAP = /^(nowrap|pre)$/;
+const round = (n) => Number.isInteger(n) ? String(n) : n.toFixed(1).replace(/\.0$/, '');
+/**
+ * What happens to content that exceeds the box on this axis.
+ *
+ * Exactly one of `clip` / `scroll` / `visible` always applies -- it is a
+ * partition of the `overflow` values. The wrapping facts are additional, and
+ * `ellipsis` suppresses `wraps` because `text-overflow` only takes effect when
+ * wrapping is already off; printing both would be restating one CSS rule twice.
+ */
+function consequences(el, axis) {
+    const overflow = axis === 'x' ? el.overflowX : el.overflowY;
+    const out = [];
+    const clips = CLIPS.test(overflow);
+    if (clips)
+        out.push('clip');
+    else if (SCROLLS.test(overflow))
+        out.push('scroll');
+    else
+        out.push('visible');
+    if (axis === 'x') {
+        const ellipsis = el.textOverflow === 'ellipsis' && (clips || SCROLLS.test(overflow));
+        if (ellipsis)
+            out.push('ellipsis');
+        else if (!NO_WRAP.test(el.whiteSpace))
+            out.push('wraps');
+        else
+            out.push('nowrap');
+    }
+    return out;
+}
+/**
+ * Whether a collapsed box is hiding anything.
+ *
+ * A `0x0` spacer is ordinary and uninteresting; a `0x1239` column with a page
+ * of content inside it is the bug the prototype measured and discarded. The
+ * difference is entirely in what the box contains, so that is what the fact
+ * carries.
+ */
+function contentOf(el, byId) {
+    if (el.text)
+        return `"${el.text}"`;
+    let text = '';
+    let elements = 0;
+    const queue = [...el.childIds];
+    while (queue.length > 0 && text.length < 40) {
+        const child = byId.get(queue.shift() ?? '');
+        if (!child)
+            continue;
+        elements++;
+        if (child.text)
+            text = `${text} ${child.text}`.trim();
+        queue.push(...child.childIds);
+    }
+    if (text)
+        return `"${text.slice(0, 40)}"`;
+    return elements > 0 ? `${elements} element${elements === 1 ? '' : 's'}` : null;
+}
+/**
+ * How much of an element an ancestor hides, and whether anyone can get to it.
+ *
+ * `attachClipFacts` has populated `ElementRecord.clip` on both capture paths
+ * since step 4, and until now nothing rendered it — the digest emitted the
+ * three fact kinds above and silently dropped this one. The V1 cold read's
+ * single strongest result came from the step-2 spike's renderer, not from
+ * shipped code, and nobody noticed because the tests asserted on `clip` the
+ * field rather than on the output.
+ *
+ * `scrollable` is the counter-fact that carries the whole meaning. A box
+ * outside an `overflow:auto` ancestor is a scroll region working as intended;
+ * the same box outside an `overflow:hidden` ancestor is content nobody can
+ * reach. Printing the extent without the reachability is a measurement the
+ * reader cannot act on.
+ */
+function clipFact(el) {
+    const clip = el.clip;
+    if (!clip)
+        return null;
+    const where = [
+        clip.hidden.top ? `${round(clip.hidden.top)}px above` : null,
+        clip.hidden.bottom ? `${round(clip.hidden.bottom)}px below` : null,
+        clip.hidden.left ? `${round(clip.hidden.left)}px left` : null,
+        clip.hidden.right ? `${round(clip.hidden.right)}px right` : null,
+    ]
+        .filter(Boolean)
+        .join(', ');
+    const visible = clip.visible.width < ZERO_EPSILON || clip.visible.height < ZERO_EPSILON
+        ? 'nothing visible'
+        : `${round(clip.visible.width)}x${round(clip.visible.height)} visible`;
+    return {
+        kind: 'clipped',
+        text: `clipped by ${clip.by} ${clip.byTag}; overflow:${clip.overflow}, ` +
+            `${clip.scrollable ? 'scrollable' : 'not scrollable'}; ${where}, ${visible}`,
+    };
+}
+/**
+ * Every fact this element has. Unconditional: no thresholds beyond subpixel
+ * noise, no severity, no suppression.
+ */
+export function factsFor(el, byId) {
+    const facts = [];
+    const overflowX = el.scrollWidth - el.clientWidth;
+    if (overflowX > OVERFLOW_EPSILON) {
+        facts.push({
+            kind: 'overflow-x',
+            text: `overflow-x +${round(overflowX)}px; ${consequences(el, 'x').join(', ')}`,
+        });
+    }
+    const overflowY = el.scrollHeight - el.clientHeight;
+    if (overflowY > OVERFLOW_EPSILON) {
+        facts.push({
+            kind: 'overflow-y',
+            text: `overflow-y +${round(overflowY)}px; ${consequences(el, 'y').join(', ')}`,
+        });
+    }
+    // Only for elements that are still in the layout. `display:none` collapses
+    // everything to 0x0 and saying so about every hidden node is noise.
+    const collapsed = el.display !== 'none' &&
+        (el.rect.width < ZERO_EPSILON || el.rect.height < ZERO_EPSILON) &&
+        !(el.rect.width < ZERO_EPSILON && el.rect.height < ZERO_EPSILON && !el.childIds.length);
+    if (collapsed) {
+        const content = contentOf(el, byId);
+        if (content) {
+            facts.push({
+                kind: 'zero-box',
+                text: `${round(el.rect.width)}x${round(el.rect.height)} zero-box; content ${content}`,
+            });
+        }
+    }
+    const clipped = clipFact(el);
+    if (clipped)
+        facts.push(clipped);
+    return facts;
+}
+/** `[fact] [fact]` — the form these take on a digest line. */
+export function renderFacts(facts) {
+    return facts.map((f) => `[${f.text}]`).join(' ');
+}
+/** Every element that has at least one fact, in document order. */
+export function factsForAll(elements) {
+    const byId = new Map(elements.map((e) => [e.id, e]));
+    const out = [];
+    for (const element of elements) {
+        const facts = factsFor(element, byId);
+        if (facts.length > 0)
+            out.push({ element, facts });
+    }
+    return out;
+}

package/dist/snapshot/limits.cjs

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * 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".
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COLOR_TOKEN_CAP = exports.SKIPPED_TAGS = exports.TESTID_ATTRS = exports.NAME_LENGTH = exports.TEXT_PREVIEW_LENGTH = exports.MAX_ELEMENTS = void 0;
+exports.capBackgroundImage = capBackgroundImage;
+/**
+ * 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.
+ */
+exports.MAX_ELEMENTS = 5000;
+/** Own-text preview length, in characters. */
+exports.TEXT_PREVIEW_LENGTH = 60;
+/** Accessible-name length, in characters. */
+exports.NAME_LENGTH = 80;
+/** Attributes treated as a stable test id, in priority order. */
+exports.TESTID_ATTRS = ['data-testid', 'data-test-id', 'data-test', 'data-qa'];
+/** Tags whose subtrees carry no layout worth measuring. */
+exports.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.
+ */
+exports.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.
+ */
+function capBackgroundImage(raw, cap = exports.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/limits.d.cts

@@ -0,0 +1,59 @@
+/**
+ * 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 declare const MAX_ELEMENTS = 5000;
+/** Own-text preview length, in characters. */
+export declare const TEXT_PREVIEW_LENGTH = 60;
+/** Accessible-name length, in characters. */
+export declare const NAME_LENGTH = 80;
+/** Attributes treated as a stable test id, in priority order. */
+export declare const TESTID_ATTRS: readonly ["data-testid", "data-test-id", "data-test", "data-qa"];
+/** Tags whose subtrees carry no layout worth measuring. */
+export declare const SKIPPED_TAGS: readonly ["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 declare 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 declare function capBackgroundImage(raw: string, cap?: number): string;

package/dist/snapshot/limits.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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 declare const MAX_ELEMENTS = 5000;
+/** Own-text preview length, in characters. */
+export declare const TEXT_PREVIEW_LENGTH = 60;
+/** Accessible-name length, in characters. */
+export declare const NAME_LENGTH = 80;
+/** Attributes treated as a stable test id, in priority order. */
+export declare const TESTID_ATTRS: readonly ["data-testid", "data-test-id", "data-test", "data-qa"];
+/** Tags whose subtrees carry no layout worth measuring. */
+export declare const SKIPPED_TAGS: readonly ["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 declare 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 declare function capBackgroundImage(raw: string, cap?: number): string;