@michaelmagan/dnumb 0.1.0

package/dist/digest/render.cjs

@@ -0,0 +1,1575 @@
+"use strict";
+/**
+ * Renders a capture as the text an agent reads instead of raw JSON.
+ *
+ * The line grammar is carried over from the prototype unchanged. It survived
+ * two cold reads there and a third here, and it is the one part of this project
+ * that five registry searches found no substitute for, so it is deliberately
+ * not being redesigned:
+ *
+ * ```
+ * # dnumb digest v2 — <url> — <viewport> — <state>
+ * # grammar: id tag[.role|#testid] ["text"] @x,y WxH [flow] [↓gap|→gap to prev sibling] [facts]; px, integers; y>viewport.height is below the fold
+ * e13 span "Task Board 1" @71,164 263x18 →10
+ * ```
+ *
+ * Two things are new in v2.
+ *
+ * **Facts are joined by element id, not by selector.** The prototype matched
+ * check findings to digest lines through a CSS selector string, which is how it
+ * shipped the Step 16 misattribution bug: two elements resolving to the same
+ * selector meant a fact landing on the wrong line. Facts here are computed from
+ * the same records the lines are, and carried on the record.
+ *
+ * **The header names the state.** Without it two captures of one URL are
+ * indistinguishable in their own headers, and the whole point of the format is
+ * to describe more than one moment of a page.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPARSE_CAPTURE_MARKER = void 0;
+exports.renderDigest = renderDigest;
+const cluster_js_1 = require("../analysis/cluster.cjs");
+const layout_tree_js_1 = require("../analysis/layout-tree.cjs");
+const color_js_1 = require("../snapshot/color.cjs");
+const facts_js_1 = require("../snapshot/facts.cjs");
+const not_measured_js_1 = require("../snapshot/not-measured.cjs");
+/**
+ * P1-1 (superseded -- see `docs/notes/06-budget.md`, the design of record for
+ * everything in this comment and the two below it). Raising `DEFAULT_BUDGET`
+ * from 300 to 1000 lines was tuned against eight committed fixtures and at
+ * most four live-site stand-ins, and a later 28-page live soak falsified the
+ * frame it was tuned in, not just the number. Two things were wrong at once,
+ * and only one of them was the constant:
+ *
+ * 1. **Lines are a poor proxy for the thing the budget protects.** A digest
+ *    line runs 40-900+ characters (a 40-entry fold line alone can hit 1088);
+ *    the real constraint is the reader's context window, denominated in
+ *    tokens, and characters predict tokens to within ±20% (2.51-3.50
+ *    chars/token, median 2.84, measured across the soak's real cl100k
+ *    counts) with no tokenizer dependency. Lines predict tokens far worse,
+ *    and not at all once folds appear.
+ * 2. **The scalar was never the real defect -- the collapse ladder's
+ *    ordering was.** Stage 3 (`collapseCandidates`, below) used to rank
+ *    candidates biggest-first, so the first collapse tried on a real page
+ *    was a wrapper containing nearly the whole document: output was a step
+ *    function, 12 lines or the whole page, nothing in between at any
+ *    budget. No default line count could fix that -- `stripe.com`,
+ *    `bbc.com`, and `tailwindcss.com` all had *no* budget between 1200 and
+ *    1300 that produced anything but those two extremes (measured against
+ *    this repo's own soak bundles). See `collapseCandidates`'s doc comment
+ *    for the leaf-up reordering that replaced it.
+ *
+ * The budget is now `budgetChars` (`DEFAULT_BUDGET_CHARS`, below), not
+ * lines. `budgetLines` still works when a caller passes it explicitly --
+ * this package has two other call sites (`src/cli.ts`, `src/query.ts`) that
+ * type and pass it through, both owned by crews mid-flight the night this
+ * landed, so an outright removal would have broken code this change could
+ * not also fix -- but it carries no default of its own any more and is not
+ * how a bare `renderDigest(snapshot, meta)` call is bounded.
+ */
+/**
+ * Default `budgetChars` -- the measured knee, not a round number.
+ * `docs/notes/06-budget.md` §5: the soak's median natural page (3.6K tokens)
+ * fits with 3× headroom, 11 of 28 pages render in full untouched, and every
+ * page that degrades still yields a 200-450-line skeleton once stage 3 peels
+ * leaf-up (`collapseCandidates`) instead of biggest-first. Half it and
+ * `stripe.com`'s skeleton loses its section internals; double it and the
+ * default `look` is back to 20K+ tokens on a third of the web -- the exact
+ * cost the soak flagged. 32768 chars is ~11.5K tokens at the corpus's
+ * measured 2.84 chars/token (§2), comfortably inside the range the old
+ * line-based sweep itself called "the honest price of a real page's
+ * content" (9-22K tokens), at the bottom of it because the soak showed
+ * expensive pages are the common case, not the sweep's assumed exception.
+ */
+const DEFAULT_BUDGET_CHARS = 32768;
+const TEXT_TRUNCATE = 30;
+/** A run shorter than this is cheaper to print in full than to describe. */
+const MIN_FOLD_RUN = 3;
+const round = (n) => Math.round(n);
+function label(node, ctx) {
+    const el = ctx.byId.get(node.elementId);
+    let head = `${node.elementId} ${node.tag}`;
+    if (el?.testId)
+        head += `#${el.testId}`;
+    else if (el?.role)
+        head += `.${el.role}`;
+    const text = el?.name || el?.text;
+    if (text) {
+        head += ` "${text.length > TEXT_TRUNCATE ? `${text.slice(0, TEXT_TRUNCATE)}…` : text}"`;
+    }
+    return head;
+}
+function geometry(node) {
+    return `@${round(node.rect.x)},${round(node.rect.y)} ${round(node.rect.width)}x${round(node.rect.height)}`;
+}
+/**
+ * Signed edge-to-edge distance between two boxes along one axis, in DOM
+ * order (`previous` before `node`). Positive is a real gap; negative is a
+ * genuine overlap, measured from the earlier box's trailing edge to the
+ * later box's leading edge -- the same "positioned back over its sibling"
+ * measurement the docs' menu example describes.
+ *
+ * All three branches are direction-agnostic: each checks which box is
+ * actually first on the axis before deciding which pair of edges to
+ * subtract, rather than assuming `previous` is always the one with the
+ * smaller coordinate. The naive DOM-order subtraction -- `node.start -
+ * previous.end`, unconditionally -- is an LTR-only assumption. On an RTL
+ * flex row the DOM-order previous sibling is drawn to the *right*, so that
+ * subtraction pairs the wrong edges and reports a number with no
+ * relationship to the real geometry: a huge fabricated overlap for two boxes
+ * that do not touch at all (measured on `ar.wikipedia.org`: two header
+ * regions 16px apart rendered as `→-1352`), and, in the third branch, a
+ * wrong magnitude for boxes that genuinely do overlap (two rows overlapping
+ * by exactly 1.0px rendered as `→-474` -- the pre-fix third branch was still
+ * `node.start - previous.end` unconditionally, the identical LTR-only bug
+ * one branch later). `analysis/distances.ts#distance` (the `q distance`
+ * verb) never had this bug because `gapAlong` already checks direction this
+ * way; the first two branches mirror that logic exactly (same result in
+ * every LTR case, since `previous` really is first on the axis there). The
+ * third branch cannot just mirror `gapAlong`'s overlap arm, though --
+ * `gapAlong` reports the *intersection length*, a different and smaller
+ * number than "how far back" a box was positioned, which is what this token
+ * has always reported and what `docs/digest.md`'s worked example pins -- so
+ * it picks the correct pair of edges (the later-on-screen box's leading edge
+ * against the earlier-on-screen box's trailing edge) itself, the same
+ * direction check as the other two branches, applied to this branch's own
+ * arithmetic instead of borrowing `gapAlong`'s.
+ */
+function edgeDistance(nodeStart, nodeSize, prevStart, prevSize) {
+    const nodeEnd = nodeStart + nodeSize;
+    const prevEnd = prevStart + prevSize;
+    if (nodeStart >= prevEnd)
+        return nodeStart - prevEnd;
+    if (prevStart >= nodeEnd)
+        return prevStart - nodeEnd;
+    // Overlap. `previous` is only the box drawn first on screen when
+    // `prevStart <= nodeStart` (every LTR case). When it is not -- an RTL
+    // sibling pair, `previous` drawn to the right -- the box actually first on
+    // screen is `node`, so the pair to subtract is `node`'s trailing edge
+    // against `previous`'s leading edge instead.
+    if (prevStart > nodeStart)
+        return -(nodeEnd - prevStart);
+    return nodeStart - prevEnd;
+}
+function gapToken(node, previous, flow) {
+    if (!previous)
+        return '';
+    const vertical = flow !== 'row';
+    const value = vertical
+        ? edgeDistance(node.rect.y, node.rect.height, previous.rect.y, previous.rect.height)
+        : edgeDistance(node.rect.x, node.rect.width, previous.rect.x, previous.rect.width);
+    if (!Number.isFinite(value))
+        return '';
+    return ` ${vertical ? '↓' : '→'}${round(value)}`;
+}
+function lineFor(node, previous, parentFlow, depth, ctx) {
+    const parts = [`${'  '.repeat(depth)}${label(node, ctx)} ${geometry(node)}`];
+    if (node.flow !== 'none')
+        parts.push(`[${node.flow}]`);
+    const gap = gapToken(node, previous, parentFlow);
+    if (gap)
+        parts.push(gap.trim());
+    for (const fact of ctx.factsById.get(node.elementId) ?? [])
+        parts.push(`[${fact}]`);
+    if (node.rect.y > ctx.viewportHeight)
+        parts.push('[below fold]');
+    return parts.join(' ');
+}
+/**
+ * Coarse order-of-magnitude size class for one dimension.
+ *
+ * The signature needs *some* notion of size -- without one, a page skeleton
+ * (four sibling containers 60/40/3000/400px tall) is one signature, and the
+ * 3000px one folds into the others along with everything inside it. But
+ * requiring exact dimensions was tried before this and meant nothing on a real
+ * page ever folded (thirty story rows whose titles are different lengths are
+ * thirty different heights). A bucket a few pixels wide is as bad as no
+ * bucket; one that spans three orders of magnitude is as bad as exact
+ * matching. This buckets by ~8x (three bits of `log2`), which keeps rows that
+ * merely differ in wrapped line count together while still splitting a 40px
+ * row from a 3000px one.
+ */
+const SIZE_BUCKET_BITS = 3;
+function sizeBucket(n) {
+    if (!Number.isFinite(n) || n <= 0)
+        return 0;
+    return Math.round(Math.log2(n) / SIZE_BUCKET_BITS);
+}
+/**
+ * A fact's meaning for folding purposes: kind plus consequence tokens, with
+ * the numeric magnitude stripped. `[overflow-x +900px; clip, ellipsis]` and
+ * `[overflow-x +2px; scroll, wraps]` are not interchangeable even though both
+ * are `overflow-x` -- the consequence tokens are where the difference that
+ * matters actually lives, per `docs/digest.md`'s facts section. Two rows that
+ * only differ in *how much* they overflow (`+12px` vs `+14px`, same
+ * consequence tokens) are the same kind of thing and still fold.
+ */
+function factSignature(fact) {
+    return `${fact.kind}|${fact.text.replace(/[+-]?\d+(\.\d+)?px/g, '')}`;
+}
+/**
+ * Every fact signature found anywhere in a subtree -- the node's own plus
+ * every descendant's, deduped and sorted for a stable comparison key.
+ *
+ * Computed bottom-up, once per render call, over the whole tree, and cached
+ * by element id rather than recomputed per comparison: without memoizing,
+ * this is a walk of the node's whole subtree, and `signature()` is called
+ * once per sibling at every level, so recomputing it inline would make an
+ * n-node tree's total work O(n * average subtree size) instead of O(n).
+ *
+ * This is the F1 fix: folding a subtree containing a fact into one that
+ * lacks it was invisible to the old `signature()`, which was built from each
+ * node's own box and its own facts only -- never what the box contains. A
+ * `li` that folds identically to seven others at the top level can still
+ * hide the one `span` inside it that overflows; nothing about the `li`'s own
+ * tag/role/size/fact-list changes when its child does, and the fold line
+ * only ever named the folded `li`'s id and position, never its child's.
+ * Measured on real captures before this fix: `shoelace-docs` had 115 of 301
+ * fact-bearing ids, and `grafana-play` 97 of 166, absent from the rendered
+ * text entirely -- not folded-and-disclosed, just gone, budget-independent
+ * (folding runs at every budget, not only over it).
+ *
+ * Returns only the boolean "has a fact somewhere below" (`hasDescendantFact`
+ * on `Ctx`), not the descendant signatures themselves: unlike an element's
+ * *own* fact, which the representative line still stands in for when a fold
+ * groups matching own-fact signatures (see `signature()`), a descendant's
+ * fact has no representative once its parent has folded away -- the fold
+ * line names siblings, never grandchildren (`real-sites-facts-reach-output.
+ * test.ts`'s "fold-named" route checks exactly this and does not extend to
+ * descendants). So a coarser *match* on descendant fact kind buys nothing;
+ * what matters is presence at all, which is what forces the node out of
+ * folding entirely in `signature()`.
+ */
+function computeDeepFactIds(roots, factSignaturesById) {
+    const hasDescendantFact = new Set();
+    function subtreeHasFact(node) {
+        let childHasFact = false;
+        for (const child of node.children) {
+            if (subtreeHasFact(child))
+                childHasFact = true;
+        }
+        if (childHasFact)
+            hasDescendantFact.add(node.elementId);
+        return childHasFact || (factSignaturesById.get(node.elementId)?.length ?? 0) > 0;
+    }
+    for (const root of roots)
+        subtreeHasFact(root);
+    return hasDescendantFact;
+}
+/**
+ * What makes two siblings "the same" for folding.
+ *
+ * Own facts (`factSignaturesById`) are part of it by matching kind and
+ * consequence, not exact text, same as before -- this is what keeps `docs/
+ * digest.md`'s own worked example true ("two rows overflowing by 12px and
+ * 14px, both clip, ellipsis, are the same kind of thing and fold"), because
+ * the folded-away member's own fact is still "the same kind" as the
+ * representative's, printed on the line right above it.
+ *
+ * A fact anywhere in a node's *descendants* (`ctx.hasDescendantFact`) is
+ * different: there is no representative standing in for it (see
+ * `computeDeepFactIds`'s doc comment), so instead of grouping by a coarser
+ * match, such a node is excluded from folding altogether -- its signature is
+ * made unique to it (the element id itself, which nothing else shares) so it
+ * can never match any other position, fact-bearing or not, and must always
+ * either print its own line (with its own children, so the descendant's
+ * fact prints too) or be swept into an explicitly-disclosed `[folded: N
+ * nodes, bbox ...]` collapse under real budget pressure -- never silently
+ * absorbed as an unlabelled fold member (F1 in the audit).
+ *
+ * Aggressive mode (`ctx.aggressive`) still widens *something* under budget
+ * pressure -- dropping the size bucket from the shape half, so a page's own
+ * wildly different container heights fold more readily. That trade is fine
+ * for shape; it was never fine for facts, own or descendant (F2 in the
+ * audit -- stage 2 used to strip facts from the signature entirely, so two
+ * rows differing only in *what they measure* folded together and the
+ * representative's fact text silently stood in for both). Neither the own-
+ * fact signature nor the descendant-fact marker below is ever dropped here.
+ */
+function signature(node, ctx) {
+    const el = ctx.byId.get(node.elementId);
+    const shape = ctx.aggressive
+        ? `${node.tag}|${el?.role ?? ''}|${node.flow}|${node.children.length}`
+        : `${node.tag}|${el?.role ?? ''}|${node.flow}|${node.children.length}|${sizeBucket(node.rect.width)}x${sizeBucket(node.rect.height)}`;
+    const ownFacts = (ctx.factSignaturesById.get(node.elementId) ?? []).join(';');
+    const deepMarker = ctx.hasDescendantFact.has(node.elementId) ? `#${node.elementId}` : '';
+    return `${shape}|${ownFacts}${deepMarker}`;
+}
+/**
+ * How many folded siblings get named individually.
+ *
+ * The fold line keeps each id and position so that nothing a fold covers
+ * becomes unaddressable -- but a 200-row table produces one *line* of 2,400
+ * characters, and a budget measured in lines does not bound tokens at all. Past
+ * this many the line says how many it dropped and how to get at them, because a
+ * cap the reader cannot see is indistinguishable from complete output.
+ */
+const MAX_FOLD_ENTRIES = 40;
+/**
+ * `[fold: ×N[/period] more like <id>[ (variance)] — entries]`. The count and
+ * the optional period sit before `more like` and the optional variance sits
+ * in parens right after the id -- both stay clear of the ` — ` separator on
+ * purpose. `parse.ts`'s fold regex used to require `(\S+)` immediately before
+ * ` — `, so a variance token with a space in it (`r0 (h-range 30-90 across
+ * 8)`) made the whole line unparseable; the parser now has an explicit
+ * optional group for exactly this shape, but a future token added here still
+ * has to stay inside one of the two designated slots or it will break parsing
+ * again.
+ */
+function foldLine(run, parentFlow, depth, parentId, period = 1) {
+    const first = run[0];
+    if (!first)
+        return '';
+    const rest = run.slice(period);
+    const named = rest.slice(0, MAX_FOLD_ENTRIES);
+    const entries = named.map((node, i) => {
+        const previous = i === 0 ? run[period - 1] : rest[i - 1];
+        return `${node.elementId} @${round(node.rect.x)},${round(node.rect.y)}${gapToken(node, previous, parentFlow)}`;
+    });
+    const hidden = rest.length - named.length;
+    // F3 in the audit: `--focus` has to name an id whose subtree actually
+    // contains every entry this line is about to drop. `first` is one of the
+    // SIBLINGS the fold covers -- `--focus <first>` re-shows only that one
+    // sibling's own subtree, not the ones `…+N not listed` refers to, and a
+    // real case (`--focus e47` on a tailwind capture) returned exactly one
+    // line for it. The parent -- the container all these siblings share -- is
+    // the only id whose subtree covers all of them. `first`'s own id remains
+    // the fallback for the one case with no addressable container: a fold
+    // among multiple top-level document roots, which have no shared parent id
+    // to point at.
+    const hint = parentId ?? first.elementId;
+    const tail = hidden > 0 ? `, …+${hidden} not listed (--focus ${hint})` : '';
+    const periodToken = period > 1 ? `/${period}` : '';
+    return `${'  '.repeat(depth)}[fold: ×${rest.length}${periodToken} more like ${first.elementId}${variance(run, period)} — ${entries.join(', ')}${tail}]`;
+}
+/**
+ * The min/max of one dimension across a set of values, or `null` when they
+ * are the same box within rounding noise.
+ *
+ * Compares the *raw* values against `OVERFLOW_EPSILON` -- the same 1px
+ * threshold `facts.ts` uses for overflow -- and rounds only for display.
+ * Rounding first and comparing rounded integers (what shipped) turns
+ * `100.4, 100.6, 100.6, 100.6` into a reported `100-101`: a manufactured 1px
+ * spread out of what is really 0.2px of subpixel layout. Non-finite values
+ * (a hand-edited bundle, a NaN rect) are dropped rather than propagated --
+ * `round(NaN)` is `NaN`, and `NaN !== NaN` would otherwise print `w NaN-NaN`.
+ */
+function spread(rawValues) {
+    const values = rawValues.filter((v) => Number.isFinite(v));
+    if (values.length === 0)
+        return null;
+    const min = Math.min(...values);
+    const max = Math.max(...values);
+    if (max - min <= facts_js_1.OVERFLOW_EPSILON)
+        return null;
+    return [round(min), round(max)];
+}
+/**
+ * The size range across a fold, when the members are not all the same size.
+ *
+ * Dimensions are deliberately not part of the fold signature (beyond the
+ * coarse bucket in `signature()`) -- requiring an exact match meant nothing on
+ * a real page ever folded. But that trade hides exactly the thing this tool
+ * exists to surface: fold eighty-eight rows and one of them is three times
+ * taller than the rest, and the digest says nothing. Facts already break a
+ * fold, so an overflowing row stays visible; a merely misshapen one would not.
+ *
+ * For a periodic fold (`period > 1`) the spread is computed *per phase* --
+ * story row, subtext row, spacer row are each a different shape on purpose,
+ * and pooling their heights together reports the list's own inherent
+ * variation as if it were an outlier. A phase with no real spread says
+ * nothing; a phase with one gets its own `phaseN` token.
+ *
+ * **`w-range`/`h-range`, not bare `w`/`h`, and `across <count>` on every
+ * token.** `docs/notes/05-v3-control.md` SECOND RUN §3/§5/§7 measured what
+ * the bare form (`(w 32-48)`) does to a careful reader on a real, clean
+ * control page: 1 of 5 blind raters read it as data precise enough to belong
+ * to one specific folded sibling, picked the range's upper bound as that
+ * sibling's own width, and derived a right edge from it -- a specific,
+ * invented `overflow-x` the renderer never emitted, on a page carrying zero
+ * facts. The entries printed right after this token give x-position and gap
+ * for each folded id, in the same px units, which is exactly what makes the
+ * reconstruction *look* well-founded; nothing in the old token's own text
+ * said it was an aggregate rather than a per-entry lookup. `w-range`/`h-range`
+ * names what kind of number this is (a spread, not a measurement of one box),
+ * and `across <count>` states how many boxes it was pooled from -- the same
+ * count as the fold's own representative-plus-entries -- so a reader has to
+ * override two explicit words to make the mistake the old token invited
+ * silently.
+ */
+function variance(run, period) {
+    const parts = [];
+    for (let phase = 0; phase < period; phase++) {
+        const members = run.filter((_, i) => i % period === phase);
+        const w = spread(members.map((node) => node.rect.width));
+        const h = spread(members.map((node) => node.rect.height));
+        const phaseParts = [];
+        if (w)
+            phaseParts.push(`w-range ${w[0]}-${w[1]} across ${members.length}`);
+        if (h)
+            phaseParts.push(`h-range ${h[0]}-${h[1]} across ${members.length}`);
+        if (phaseParts.length === 0)
+            continue;
+        const label = period > 1 ? `phase${phase} ` : '';
+        parts.push(`${label}${phaseParts.join(', ')}`);
+    }
+    return parts.length > 0 ? ` (${parts.join('; ')})` : '';
+}
+function countNodes(node) {
+    let total = 1;
+    for (const child of node.children)
+        total += countNodes(child);
+    return total;
+}
+/**
+ * How many of a subtree's elements carry a fact -- what a `[folded: N nodes,
+ * bbox ...]` collapse takes with it, unstated until now. The line already
+ * disclosed the node count and the box; a reader had no way to tell "796
+ * ordinary nodes" from "796 nodes, 448 of which were measurements" without
+ * re-running an uncollapsed capture. Counted from the same `factsById` map
+ * `lineFor` reads facts from, so this can never disagree with what the
+ * uncollapsed render would have shown.
+ */
+function countFacts(node, factsById) {
+    let total = factsById.has(node.elementId) ? 1 : 0;
+    for (const child of node.children)
+        total += countFacts(child, factsById);
+    return total;
+}
+function bbox(nodes) {
+    let x0 = Number.POSITIVE_INFINITY;
+    let y0 = Number.POSITIVE_INFINITY;
+    let x1 = Number.NEGATIVE_INFINITY;
+    let y1 = Number.NEGATIVE_INFINITY;
+    const visit = (n) => {
+        x0 = Math.min(x0, n.rect.x);
+        y0 = Math.min(y0, n.rect.y);
+        x1 = Math.max(x1, n.rect.x + n.rect.width);
+        y1 = Math.max(y1, n.rect.y + n.rect.height);
+        for (const child of n.children)
+            visit(child);
+    };
+    for (const n of nodes)
+        visit(n);
+    if (!Number.isFinite(x0))
+        return { x: 0, y: 0, width: 0, height: 0 };
+    return { x: round(x0), y: round(y0), width: round(x1 - x0), height: round(y1 - y0) };
+}
+function flatten(nodes) {
+    const out = [];
+    const visit = (n) => {
+        out.push(n);
+        for (const child of n.children)
+            visit(child);
+    };
+    for (const n of nodes)
+        visit(n);
+    return out;
+}
+/** How many times the runner-up's own size the gap between the bbox-defining
+ * node and its runner-up must be, before that node is called out by name. */
+const PAGE_OUTLIER_RATIO = 10;
+/** Rounding tolerance for "is this candidate's edge the bbox bound". */
+const BOUND_EPSILON = 0.5;
+/**
+ * Every element id's set of ancestor ids (not including itself), computed
+ * once per `pageOutlier` call. Exists for exactly one purpose: telling a
+ * *structural* tie at the bbox extreme apart from a genuine second
+ * occurrence of it -- see the tie-handling loop below.
+ */
+function buildAncestry(roots) {
+    const ancestry = new Map();
+    const visit = (node, ancestors) => {
+        ancestry.set(node.elementId, ancestors);
+        const withSelf = new Set(ancestors);
+        withSelf.add(node.elementId);
+        for (const child of node.children)
+            visit(child, withSelf);
+    };
+    for (const root of roots)
+        visit(root, new Set());
+    return ancestry;
+}
+function isLineage(a, b, ancestry) {
+    return ((ancestry.get(a.elementId)?.has(b.elementId) ?? false) ||
+        (ancestry.get(b.elementId)?.has(a.elementId) ?? false));
+}
+/**
+ * The single element responsible when the page's bounding box is dominated
+ * by one wildly out-of-scale node, and which axis it dominates on.
+ *
+ * `# page: WxH` is the first line of every digest, so it is the number a
+ * reader is most likely to trust without checking. On real sites it has
+ * measured `4512x3802616` -- a grid's virtualization spacer, real
+ * `scrollHeight` -- `1441x106410` from a visually-hidden a11y label parked at
+ * `y: -99836`, and `11414x4272` from a hidden cookie-notice heading at
+ * `x: -9974`. Three unrelated causes, one symptom: a single node pushes the
+ * honest bbox to a size nothing else on the page approaches, and that node is
+ * often folded or dropped out of the body, so the header is the only trace of
+ * it.
+ *
+ * This does not clamp or discard the measurement -- it is real, and nothing
+ * in this package adjudicates what a reader should see. It identifies which
+ * one node is responsible so a reader can get from the header number to the
+ * element without leaving the digest.
+ *
+ * F5 in the audit: the previous version compared each candidate's own SIZE
+ * (`rect.width`/`rect.height`) against the next-largest candidate's size,
+ * which is the wrong quantity twice over. First, it fabricates a causal
+ * claim: a plain header/hero/footer page has one non-root element (the hero)
+ * bigger than the rest by a wide margin, and that comparison alone flagged
+ * it as "accounting for" the page height even though every element there is
+ * ordinary in-flow content, nothing anomalous about the total. A 300px modal
+ * in a 900px page reproduces the same false attribution the moment some
+ * other, smaller element happens to be the next-largest by chance -- the
+ * 900px total has nothing to do with the modal at all. Second, and this is
+ * why it stayed silent on all eight real captures including the ar-wikipedia
+ * case its own doc comment cites as motivation: the actual off-canvas
+ * a11y-label case is a 1x1 box. It has no size to speak of; what makes it
+ * responsible is its *position* -- its own top edge is the page bbox's `y0`,
+ * tens of thousands of px beyond anything else on the page -- and a
+ * same-size comparison can never see that.
+ *
+ * This version asks the question the header line's own arithmetic asks:
+ * which node's `x`/`x+w` or `y`/`y+h` literally IS one of the bbox's four
+ * bounds (`BOUND_EPSILON` of rounding slack), and how far beyond the
+ * *runner-up* on that same side that bound reaches, relative to the
+ * runner-up's own size on that axis -- the same "is this gap big compared to
+ * the scale of what's next to it" question `PAGE_OUTLIER_RATIO` always
+ * asked, just computed from the right pair of numbers. Requiring the exact
+ * bound match is what keeps this from ever naming a node that is not
+ * actually why the number in `<W>x<H>` is what it is: if every non-root
+ * candidate falls short of the true extreme, the *root's own* box is what
+ * reaches it (a container's box reflects its content's extent by
+ * construction), and roots are deliberately never named here -- a container
+ * being large is not itself the finding, and this is also why the modal case
+ * is silent even when a modal happens to be the largest non-root candidate
+ * by raw size: if its own edges do not reach the page's actual bbox bounds,
+ * it is not a candidate for any of the four probes below at all.
+ */
+function pageOutlier(flat, roots) {
+    const rootIds = new Set(roots.map((n) => n.elementId));
+    const candidates = flat.filter((n) => !rootIds.has(n.elementId));
+    if (candidates.length < 2)
+        return null;
+    // The bbox's own four bounds, from every node including roots -- the same
+    // extremes `<W>x<H>` in the header is built from.
+    const trueBound = {
+        xMin: Math.min(...flat.map((n) => n.rect.x)),
+        xMax: Math.max(...flat.map((n) => n.rect.x + n.rect.width)),
+        yMin: Math.min(...flat.map((n) => n.rect.y)),
+        yMax: Math.max(...flat.map((n) => n.rect.y + n.rect.height)),
+    };
+    const probes = [
+        { axis: 'width', target: trueBound.xMin, dir: 1, value: (n) => n.rect.x },
+        { axis: 'width', target: trueBound.xMax, dir: -1, value: (n) => n.rect.x + n.rect.width },
+        { axis: 'height', target: trueBound.yMin, dir: 1, value: (n) => n.rect.y },
+        { axis: 'height', target: trueBound.yMax, dir: -1, value: (n) => n.rect.y + n.rect.height },
+    ];
+    const ancestry = buildAncestry(roots);
+    let winner = null;
+    for (const probe of probes) {
+        const sorted = [...candidates].sort((a, b) => probe.dir * (probe.value(a) - probe.value(b)));
+        const first = sorted[0];
+        // Only a candidate whose own edge actually IS the page's bbox bound on
+        // this side is eligible -- see the doc comment above for why (the root
+        // owns this bound instead when no non-root candidate reaches it).
+        if (!first || Math.abs(probe.value(first) - probe.target) > BOUND_EPSILON)
+            continue;
+        // The runner-up. Two ways a candidate can tie with `first` at the
+        // extreme, and they mean opposite things:
+        //  - a STRUCTURAL tie -- `first`'s own parent or child -- is the SAME
+        //    measurement seen at two nesting levels, not independent evidence
+        //    (`docs/digest.md`'s own worked example: a zero-width column and its
+        //    single child both compute to the page's full 1239px height, and the
+        //    doc explicitly wants this to stay silent -- "no unique second-
+        //    largest box... to compare the largest one against"). Such a tie
+        //    IS the runner-up: it belongs in the comparison, and its ~0px gap
+        //    correctly suppresses the probe.
+        //  - an INDEPENDENT tie -- an unrelated element elsewhere in the tree
+        //    that happens to reach the same extreme -- is a second, separate
+        //    occurrence of the same anomaly, not a competing measurement (five
+        //    unrelated 1x1 off-canvas labels on a real `ar-wikipedia` capture,
+        //    all parked at the identical `y:-99791`). Comparing `first` against
+        //    one of ITS OWN kind would report a 0px gap and wrongly suppress the
+        //    exact case this rewrite exists to surface, so these are skipped in
+        //    favor of the next candidate whose value is either genuinely
+        //    different or a structural tie.
+        let second;
+        for (const candidate of sorted.slice(1)) {
+            const tied = Math.abs(probe.value(candidate) - probe.value(first)) <= facts_js_1.OVERFLOW_EPSILON;
+            if (tied && !isLineage(first, candidate, ancestry))
+                continue;
+            second = candidate;
+            break;
+        }
+        if (!second)
+            continue;
+        const gap = Math.abs(probe.value(second) - probe.value(first));
+        const secondSize = probe.axis === 'width' ? second.rect.width : second.rect.height;
+        const ratio = gap / Math.max(secondSize, 1);
+        if (ratio <= PAGE_OUTLIER_RATIO)
+            continue;
+        if (!winner || ratio > winner.ratio) {
+            winner = { id: first.elementId, axis: probe.axis, extent: round(gap), ratio };
+        }
+    }
+    return winner ? { id: winner.id, axis: winner.axis, extent: winner.extent } : null;
+}
+const MAX_FOLD_PERIOD = 6;
+/**
+ * The longest run of siblings starting at `from` that repeats with some period.
+ *
+ * Real lists are periodic, not uniform. Hacker News alternates story row,
+ * subtext row, spacer row; a definition list alternates `dt`, `dd`; a table
+ * body alternates header and data rows. Looking only for *consecutive
+ * identical* signatures -- which is what this did -- finds runs of length one
+ * or two in all of those, never reaches the fold threshold, and leaves the
+ * budget ladder no option but to collapse the page's actual content into a
+ * single `[folded: 626 nodes]` line. That is what shipped, and it made the
+ * digest useless on every list-heavy page, which is most of them.
+ *
+ * Periods beyond a handful stop being a pattern a reader would recognise, so
+ * the search is bounded; the period covering the most siblings wins.
+ *
+ * `signatures` is the *whole* sibling level's signatures, computed once by
+ * `renderNodes` -- this used to take the raw node list and rebuild the
+ * signature array itself on every call, which made an n-sibling level's
+ * `renderNodes` loop O(n^2): each of the n positions re-signed every
+ * remaining sibling. Taking the precomputed array plus an offset turns that
+ * into O(n) total.
+ */
+function periodicRun(signatures, from) {
+    const remaining = signatures.length - from;
+    let best = { length: 1, period: 1 };
+    for (let period = 1; period <= Math.min(MAX_FOLD_PERIOD, remaining); period++) {
+        let repeats = 1;
+        while ((repeats + 1) * period <= remaining) {
+            let matches = true;
+            for (let k = 0; k < period; k++) {
+                // No array allocation per attempt -- this loop can run many times per
+                // sibling position, and `Array.from(...).every(...)` (what shipped)
+                // allocated a fresh array on every single one of them.
+                if (signatures[from + repeats * period + k] !== signatures[from + k]) {
+                    matches = false;
+                    break;
+                }
+            }
+            if (!matches)
+                break;
+            repeats++;
+        }
+        // Two repeats of a three-row pattern is six lines described in seven; the
+        // fold has to cover more than it costs.
+        if (repeats >= MIN_FOLD_RUN && repeats * period > best.length) {
+            best = { length: repeats * period, period };
+        }
+    }
+    return best;
+}
+function renderNodes(nodes, parentFlow, depth, ctx, out, 
+/** The container id all of `nodes` share, or `null` for the top-level
+ * roots (which have no shared parent id) -- threaded through to
+ * `foldLine`'s `--focus` hint. See F3 in the audit. */
+parentId) {
+    // Computed once for the whole sibling level, not once per position -- see
+    // `periodicRun`'s doc comment for why the previous version, which rebuilt
+    // this from `i` at every index, made an n-sibling level O(n^2). Skipped
+    // entirely under `--focus` (see `Ctx.focused`'s doc comment) -- there is
+    // nothing to fold *into*, since the whole render already stopped there.
+    const signatures = ctx.focused ? [] : nodes.map((node) => signature(node, ctx));
+    let i = 0;
+    while (i < nodes.length) {
+        const node = nodes[i];
+        if (!node)
+            break;
+        const previous = nodes[i - 1];
+        const { length, period } = ctx.focused ? { length: 1, period: 1 } : periodicRun(signatures, i);
+        if (length >= MIN_FOLD_RUN) {
+            // The first whole period is printed in full and stands for the rest --
+            // for an alternating story/subtext/spacer table that means one of each,
+            // not one row of three. The fold line keeps every remaining id and
+            // position, so nothing it covers becomes unaddressable.
+            for (let k = 0; k < period; k++) {
+                const member = nodes[i + k];
+                if (!member)
+                    break;
+                out.push(lineFor(member, nodes[i + k - 1], parentFlow, depth, ctx));
+                renderChildren(member, depth + 1, ctx, out);
+            }
+            out.push(foldLine(nodes.slice(i, i + length), parentFlow, depth, parentId, period));
+            i += length;
+            continue;
+        }
+        out.push(lineFor(node, previous, parentFlow, depth, ctx));
+        renderChildren(node, depth + 1, ctx, out);
+        i++;
+    }
+}
+/**
+ * The only place that knows about collapsing.
+ *
+ * It used to be guarded here *and* at both call sites, so a collapsed container
+ * emitted nothing at all rather than its summary line -- the subtree vanished
+ * from the digest with no trace that it had been dropped. A cap the reader
+ * cannot see is worse than no cap.
+ *
+ * `(--focus <id>)` at the end is the same disclosure the fold line already
+ * makes for its own `…+N not listed` tail (see `foldLine` above) -- the id is
+ * `node.elementId`, printed on the container's own line directly above this
+ * one, so a reader could always work it out by hand. Making it explicit here
+ * matters more than it does on the fold line, not less: this is the render's
+ * *heaviest* disclosure -- a whole subtree, `K facts` among them, reduced to
+ * one line -- and a reader told "827 facts are in here" with no printed route
+ * to them is being taunted, not informed.
+ */
+function renderChildren(node, depth, ctx, out) {
+    if (node.children.length === 0)
+        return;
+    if (ctx.collapsed.has(node.elementId)) {
+        const box = bbox(node.children);
+        const count = node.children.reduce((sum, c) => sum + countNodes(c), 0);
+        const facts = node.children.reduce((sum, c) => sum + countFacts(c, ctx.factsById), 0);
+        // Only when nonzero -- omitted entirely rather than printing `0 facts` on
+        // the common case where a collapse hides nothing measured, so the token
+        // stays reserved for the case a reader actually needs to notice.
+        const factsClause = facts > 0 ? `, ${facts} facts` : '';
+        out.push(`${'  '.repeat(depth)}[folded: ${count} nodes${factsClause}, bbox @${box.x},${box.y} ${box.width}x${box.height} (--focus ${node.elementId})]`);
+        // This is the single source of truth for "which collapses actually
+        // reached the reader" -- see `Ctx.printedCollapsed`'s doc comment for
+        // why summing/naming from `ctx.collapsed` directly can diverge from
+        // this.
+        ctx.printedCollapsed.push(node.elementId);
+        return;
+    }
+    renderNodes(node.children, node.flow, depth, ctx, out, node.elementId);
+}
+/**
+ * Containers worth collapsing, shallowest first -- "peel from the leaves"
+ * (`docs/notes/06-budget.md` §3-4, a 28-site soak's finding, verified
+ * independently against this repo's own built renderer before this change
+ * landed, not taken on the note's word: patching only this comparator,
+ * nothing else, already turns `stripe.com` from a 12-line-or-1290-line step
+ * function into a smooth curve at every budget from 300 lines up -- 304
+ * lines at budget 300, 1006 at 1000, no cliff anywhere in between).
+ *
+ * The previous key was raw size, descending -- collapse the biggest
+ * container first. On a real production page the biggest container is
+ * always a whole-page wrapper, so the very first collapse ate essentially
+ * the entire document and every budget from "small" to "the page's own
+ * size" produced the identical single collapse: output was a step function,
+ * nothing between "12 lines" and "everything," on `stripe.com`, `bbc.com`
+ * and `tailwindcss.com` alike (measured across 17 budgets, 300-50,000, on
+ * real soak captures). No amount of retuning `DEFAULT_BUDGET` fixes a step
+ * function -- the ladder had no middle rungs to land on.
+ *
+ * Depth-from-root was also tried, as the obvious alternative reading of
+ * "start from the bottom," and is the wrong key -- verified directly here,
+ * not assumed: patching depth-descending (deepest node first) into the real
+ * renderer collapses `linear.app` down to 68 lines / 4.6KB at the same
+ * 32KB-char budget height-ascending renders at 209 lines / 16.7KB, because
+ * `linear.app`'s deepest nodes sit inside whole 200-500-node page sections
+ * that are deep-rooted *and* tall -- "deepest first" swallows one of those
+ * whole and overshoots well under budget, the same failure mode as
+ * size-descending one level removed. Height measures a subtree's own
+ * *tallness*, not its distance from the root, so a shallow-but-bushy
+ * wrapper and a deep-but-thin one are told apart correctly: a container of
+ * only leaves (height 0) collapses before its parent (height 1), which
+ * collapses before *its* parent, and so on upward -- exactly "peel from the
+ * leaves." Ties within one height class break by descendant count
+ * ascending, same reasoning one level down: several small disclosed
+ * collapses at one level tell a reader strictly more than swallowing the
+ * biggest one first.
+ *
+ * "Heaviest × depth" (an earlier scoring attempt, before either of the
+ * above) was also wrong, on a plain `descendants × depth` chain: a 30-deep
+ * wrapper chain scores higher than a 200-item list next to it (240 vs 201),
+ * so the renderer spent its collapse budget on a chain that barely moves the
+ * line count instead of the list that actually would.
+ *
+ * A root is still a candidate here, sorted into its own rung after every
+ * non-root container regardless of height or size: collapsing a root can
+ * leave nothing else behind to read, so it only happens once nothing
+ * shallower was enough -- the true last resort, not competing on score with
+ * the rest of the tree. This is also what makes the flat-page case (a `body`
+ * of only leaf children) work: `depth > 0` used to exclude the root and
+ * `children.length > 0` excludes leaves, so a page with no non-root
+ * container at all had *zero* collapse candidates and could never make
+ * budget.
+ *
+ * Height and descendant count are computed once per node, bottom-up, in the
+ * same tree walk that collects candidates -- an n-candidate sort calls its
+ * comparator O(n log n) times, and recomputing either number from scratch on
+ * every comparison (what both the old `countNodes` call and an unmemoized
+ * height calculation would do) turns a linear pass into a much more
+ * expensive one on a page with hundreds of candidates.
+ */
+function collapseCandidates(tree) {
+    const nonRoot = [];
+    const roots = [];
+    const visit = (node, depth, ancestorIds) => {
+        let height = 0;
+        let size = 1;
+        for (const child of node.children) {
+            const c = visit(child, depth + 1, [node.elementId, ...ancestorIds]);
+            height = Math.max(height, c.height + 1);
+            size += c.size;
+        }
+        if (node.children.length > 0) {
+            const candidate = {
+                node,
+                ancestorIds,
+                height,
+                descendants: size - 1,
+            };
+            (depth > 0 ? nonRoot : roots).push(candidate);
+        }
+        return { height, size };
+    };
+    for (const node of tree)
+        visit(node, 0, []);
+    const bySize = (a, b) => a.height - b.height || a.descendants - b.descendants;
+    return [...nonRoot.sort(bySize), ...roots.sort(bySize)];
+}
+function findFocus(nodes, focus) {
+    for (const node of nodes) {
+        if (node.elementId === focus || node.tag === focus)
+            return node;
+        const hit = findFocus(node.children, focus);
+        if (hit)
+            return hit;
+    }
+    return null;
+}
+/** Majority, not "any" -- the cue below exists for the moment a reader is
+ * told almost nothing, not every partial collapse. A page that collapses one
+ * 20-node sidebar out of 900 nodes is the mechanism working quietly, exactly
+ * as designed; this is for the P1-1 case, where the collapse ate the page. */
+const COLLAPSE_CUE_THRESHOLD = 0.5;
+/**
+ * How much of the page's own measurements and structure are sitting behind
+ * this render's collapse(s), summed across every collapsed container --
+ * the same per-container arithmetic `renderChildren` already prints on each
+ * `[folded: …]` line, just totalled rather than left for a reader to add up
+ * by hand across however many collapses fired.
+ *
+ * `ids` must be `ctx.printedCollapsed` from the render this is reporting on
+ * -- the ids that actually printed a `[folded: …]` line -- not the raw
+ * `ctx.collapsed`. Two ways the two sets can diverge, both real, both found
+ * on soak captures rather than constructed:
+ *
+ * - **Nested collapses.** Under the old size-descending stage-3 order the
+ *   first (usually only) collapse was always the page's one dominant
+ *   subtree, so `ctx.collapsed` and "what the reader actually sees
+ *   collapsed" were always the same set. Height-ascending peeling
+ *   (`collapseCandidates`) can collapse a small child on one iteration and,
+ *   later in the same render, a bigger ancestor of that same child on a
+ *   later one -- the ancestor-skip check in `renderDigest`'s stage-3 loop
+ *   only ever stops a candidate whose *own* ancestor is already collapsed,
+ *   not the reverse, and a root candidate's `ancestorIds` is always `[]`, so
+ *   nothing stops a root from collapsing after its own descendants already
+ *   did. `ctx.collapsed` ends up holding both ids; the render only ever
+ *   prints one `[folded: …]` line, for the outer one.
+ * - **A collapsed candidate that stage 1 also folds away.**
+ *   `collapseCandidates` picks candidates from the raw `LayoutNode` tree,
+ *   with no awareness of stage-1 folding. If a node chosen for collapse is
+ *   *also* a non-representative member of a plain or periodic sibling fold
+ *   at its own level, `renderNodes` never calls `renderChildren` on it at
+ *   all -- folded-away members never do -- so its `[folded: …]` line never
+ *   prints either, even though nothing about it looks nested in
+ *   `ctx.collapsed`.
+ *
+ * Summing the raw `ctx.collapsed` set over both cases is what printed an
+ * impossible `3506 of 1483 layout nodes` (hidden greater than the page has)
+ * on one real render and a merely-wrong `550 of 812` against a body whose
+ * own `[folded: …]` lines summed to 530 on another (`tailwind-docs` at the
+ * shipped default) -- one bug caught by a synthetic fixture, the other only
+ * by a real capture, which is why `ctx.printedCollapsed` records the ground
+ * truth as it happens rather than trying to re-derive it after the fact from
+ * either the tree or `ctx.collapsed` alone. See that field's own doc comment
+ * on `Ctx`.
+ */
+function collapsedTotals(ids, roots, factsById) {
+    let nodes = 0;
+    let facts = 0;
+    for (const id of ids) {
+        const node = findFocus(roots, id);
+        if (!node)
+            continue;
+        for (const child of node.children) {
+            nodes += countNodes(child);
+            facts += countFacts(child, factsById);
+        }
+    }
+    return { nodes, facts };
+}
+/**
+ * The ` — <strategy>` segment of the identity line.
+ *
+ * `cdp` and `walk` do not see the same page on shadow DOM -- see
+ * `DigestMeta.strategy` -- so a reader needs to know which one produced this
+ * capture, and whether `walk` here means "no other option" or "the fast path
+ * just failed" (`cdpFellBack`).
+ *
+ * `walk` also carries a second, permanent caveat that belongs here rather
+ * than on the `# not measured:` line (see `not-measured.ts#
+ * shadowRootSegment`'s doc comment, which points back to this function): a
+ * closed shadow root's count is unknowable on this path on *every* page,
+ * whether or not the page in front of it has any -- a property of the
+ * capture path, not a measurement of this particular page, so it does not
+ * belong crowded onto a line that otherwise reports only counted totals
+ * (mixing the two taught a reader to skip the whole line, including the runs
+ * where it carried a real count). `cdp` gets no matching caveat here because
+ * it is not blind to shadow content the way `walk` is -- it flattens shadow
+ * roots into the element tree instead of skipping them -- but that is not
+ * the same as "sees everything": on the committed `shoelace-docs.json`
+ * capture, the `cdp` path flattened zero shadow content on a page where
+ * `walk` found 4 open shadow roots. That gap is data-dependent per capture,
+ * not a constant property of the `cdp` path, so unlike `walk`'s blindness it
+ * has no fixed wording to state unconditionally here.
+ */
+function strategyLabelFor(meta) {
+    if (meta.strategy !== 'walk')
+        return meta.strategy ?? null;
+    const fellBack = meta.cdpFellBack ? 'cdp fell back, ' : '';
+    return `walk (${fellBack}closed shadow roots undetectable)`;
+}
+const colorPx = (n) => Number.isInteger(n) ? String(n) : n.toFixed(1).replace(/\.0$/, '');
+/**
+ * Priority for the order reasons appear in the `# colors:` unmeasured
+ * breakdown -- roughly most to least common on a real page, so the reader
+ * sees the dominant cause first rather than an alphabetical shuffle every
+ * capture. Priority only, never presence: `colorHeaderLine` below sorts the
+ * counts it actually saw by this table, it does not filter by membership in
+ * it, so a `RatioReason` with no entry here still prints (last, via the `??`
+ * fallback) instead of silently vanishing.
+ *
+ * That distinction is not decorative. The previous version was a plain
+ * five-entry array standing in for both roles at once, and `colorHeaderLine`
+ * built the breakdown as `RATIO_REASON_ORDER.filter((r) => counts.has(r))` --
+ * using the ordering array as a whitelist. `RatioReason` has seven members;
+ * `not-captured` and `canvas` were never in the five, so both were computed
+ * correctly on every fact and then discarded before the line printed,
+ * reducing every capture that hit either one to a bare count with the cause
+ * stripped off (`314 unmeasured`, no breakdown) -- exactly the distinction
+ * ("predates colour capture" vs "this page is all gradients") this tally
+ * exists to draw, silent because the two whitelists (ordering, filtering)
+ * were the same array and nothing forced them to agree. `satisfies
+ * Record<RatioReason, number>` is what makes that recur as a type error
+ * instead of a silent drop: adding an eighth `RatioReason` member without a
+ * priority entry here fails the build, rather than shipping green with the
+ * new reason invisible.
+ */
+const RATIO_REASON_PRIORITY = {
+    gradient: 0,
+    image: 1,
+    under: 2,
+    behind: 3,
+    'color-space': 4,
+    'not-captured': 5,
+    canvas: 6,
+};
+/**
+ * `# colors: <P> fg/bg pairs across <T> text elements; ratio <min>–<max>;
+ * lowest <id> <fg> on <bg> <size>px/<weight>; <U> unmeasured (<breakdown>)`
+ * -- `docs/notes/03-color.md` §6, following the page-dominance clause's own
+ * precedent (`# page:`'s "`<id>` extends the page ... by `<N>`px"): naming
+ * the minimum of a measured distribution, with its own counter-facts inline,
+ * is a measurement of this page, not a verdict about it. A measurement of
+ * *this page* belongs in the conditional block (this line), not the identity
+ * line, which is reserved for permanent properties of the capture path.
+ *
+ * The `ratio`/`lowest` clause is present only when at least one fact
+ * resolved to a real number -- a page that is entirely gradients and
+ * overlays has nothing to report there, and saying so by omission is more
+ * honest than printing a range over zero measured elements.
+ */
+function colorHeaderLine(colorFacts) {
+    const pairs = (0, color_js_1.groupColorFacts)(colorFacts);
+    let line = `# colors: ${pairs.length} fg/bg ${pairs.length === 1 ? 'pair' : 'pairs'} across ` +
+        `${colorFacts.length} text ${colorFacts.length === 1 ? 'element' : 'elements'}`;
+    const measured = colorFacts.filter((f) => f.ratio !== null);
+    if (measured.length > 0) {
+        const ratios = measured.map((f) => f.ratio);
+        const min = Math.min(...ratios).toFixed(2);
+        const max = Math.max(...ratios).toFixed(2);
+        const lowest = measured.reduce((a, b) => (b.ratio < a.ratio ? b : a));
+        line +=
+            `; ratio ${min}–${max}; lowest ${lowest.elementId} ${lowest.fg} on ${(0, color_js_1.backdropLabel)(lowest.backdrop)} ` +
+                `${colorPx(lowest.fontSizePx)}px/${lowest.fontWeight}`;
+    }
+    const unmeasured = colorFacts.length - measured.length;
+    if (unmeasured > 0) {
+        const counts = new Map();
+        for (const f of colorFacts) {
+            if (f.ratio === null && f.ratioReason)
+                counts.set(f.ratioReason, (counts.get(f.ratioReason) ?? 0) + 1);
+        }
+        // Every reason actually seen, sorted by priority -- never filtered by
+        // membership in `RATIO_REASON_PRIORITY`, so a reason that table has no
+        // entry for still prints (see that constant's own doc comment for why
+        // this is not the same code as before).
+        const breakdown = [...counts.entries()]
+            .sort(([a], [b]) => (RATIO_REASON_PRIORITY[a] ?? 99) - (RATIO_REASON_PRIORITY[b] ?? 99))
+            .map(([reason, count]) => `${count} ${reason}`);
+        line += `; ${unmeasured} unmeasured${breakdown.length > 0 ? ` (${breakdown.join(', ')})` : ''}`;
+    }
+    return line;
+}
+/**
+ * Total body size in characters, the way a reader's context actually pays
+ * for it -- `docs/notes/06-budget.md` §2's cost function verified directly
+ * against this file's own ladder: `body.reduce((a, l) => a + l.length + 1,
+ * 0)`, the `+1` for the newline every line but the last still costs once
+ * this array is joined into text. This is the file's *only* char-counting
+ * cost function; every ladder checkpoint below calls through `overBudget`
+ * rather than reimplementing the sum, so the meter cannot drift between
+ * checkpoints the way `budget`/`DEFAULT_BUDGET` never had to worry about
+ * when a length check was just `.length`.
+ */
+function charLength(lines) {
+    return lines.reduce((total, line) => total + line.length + 1, 0);
+}
+/**
+ * The refusal surface's second line always opens with this exact prefix --
+ * the single signal a caller needs to detect `sparseCapture` from rendered
+ * text alone, without re-deriving `renderDigest`'s own gate expression a
+ * second time somewhere else (the CLI's `--json` envelope, in particular --
+ * see `src/cli.ts`). `docs/notes/07-refusal.md` §4: "Keep the single source;
+ * do not re-derive it." A rendered digest is the one place that decision is
+ * already made; this constant is how a caller reads it back off the text
+ * instead of recomputing `elements >= 20 && dropped/total >= 0.9 &&
+ * page.height <= 2` against a bundle it may not even have the same shape of.
+ */
+exports.SPARSE_CAPTURE_MARKER = '# no layout to digest:';
+/**
+ * `docs/notes/07-refusal.md` §2 -- the exact surface, verbatim except for
+ * substituting the real captured URL into the re-capture line (§7 point 1).
+ *
+ * Four runs (`docs/notes/05-v3-control.md`) tried five placements of a
+ * caveat next to a `zero-box` fact on a sparse capture's own `<body>` line --
+ * trailing on the bracket, interrupting it, parenthetical, header-led,
+ * header-only -- and the best of them still fabricated a "broken page"
+ * finding 40-50% of the time, because a `[...]` fact bracket on an element
+ * line *is* the grammar for "a measured, adjudicable finding about this
+ * element," independent of any prose beside it (run 3's diagnosis, run 4's
+ * confirmation). The fix run 4 stopped short of: this function is called
+ * *instead of* the normal render, under the same `sparseCapture` gate
+ * (computed once in `renderDigest`, this function's only caller, and never
+ * re-derived here or anywhere else) -- so no element line, no `[...]`
+ * bracket, no `# facts:` line, and no grammar line (there is no grammar to
+ * explain when there is no body) ever reaches the reader on a capture this
+ * sparse. Nothing is discarded: every number below is real (the same
+ * `droppedFromTree`/`droppedRatio`/`page`/content values the pre-refusal
+ * header sentence used to carry), and `q facts` / `q describe` / `q find` /
+ * `look --focus` all still read the full, unrerouted bundle -- this changes
+ * only what `look` prints by default (`src/snapshot/facts.ts` is untouched).
+ *
+ * This is unproven, not a confirmed fix -- `docs/notes/07-refusal.md` §5
+ * commits in advance that if a pre-registered blind read scores this surface
+ * above 0/30 fabrications, the next move is not a sixth wording, it is
+ * escalating back to the format level.
+ */
+function renderSparseRefusal(identity, meta, totalRecords, droppedFromTree, droppedRatio, nodeCount, page, sparseZeroBoxNotes) {
+    // The per-element clause used to carry `<id> <tag> is <w>x<h> and still
+    // carries content <content>` when it lived in the pre-refusal header
+    // sentence -- the size is dropped here because this surface already states
+    // an aggregate size (`the <M> that did fit in a <W>x<H> box`, next line),
+    // and a per-element `<w>x<h>` here would be exactly the fact-shaped
+    // measurement §2 argues this surface must not print. The size is not lost:
+    // `q describe <id>` returns it, and the escape-hatch line below names that
+    // command.
+    const contentClause = sparseZeroBoxNotes.length > 0
+        ? `# text present but not yet laid out: ${sparseZeroBoxNotes.join('; ')}.`
+        : '# no surviving record carries text outside a laid-out box.';
+    const lines = [
+        identity,
+        `${exports.SPARSE_CAPTURE_MARKER} ${droppedFromTree} of ${totalRecords} records never reached a ` +
+            `layout node (${(droppedRatio * 100).toFixed(1)}%), and the ${nodeCount} that did fit in a ` +
+            `${page.width}x${page.height} box. A capture taken mid-hydration or mid-fetch looks exactly ` +
+            `like this — the page had not laid out at the instant this capture ran.`,
+        contentClause,
+        `# to measure the page, capture later in its life: dnumb capture ${meta.url} --wait ` +
+            `networkidle, or re-run --wait load after a settle delay. If a later capture still looks ` +
+            `like this, that repetition is itself a measurement — the page never lays out, and two ` +
+            `captures agreeing on that is the fact to report.`,
+        '# nothing was discarded: q facts, q describe <id>, q find <text>, and look --focus <id> ' +
+            'read this bundle in full; this gate changes only what look prints by default.',
+    ];
+    return `${lines.join('\n')}\n`;
+}
+function renderDigest(snapshot, meta, options = {}) {
+    // `budgetChars` is the standing meter (`DEFAULT_BUDGET_CHARS`'s doc
+    // comment, `docs/notes/06-budget.md` §2/§5) and always applies.
+    // `budgetLines`, when a caller passes it, is an *additional* ceiling on
+    // top of it, never a replacement -- see `RenderDigestOptions.budgetLines`.
+    // `overBudget` is the single predicate every stage-3 checkpoint below
+    // calls, so "what counts as over budget" cannot drift between them.
+    const budgetChars = options.budgetChars ?? DEFAULT_BUDGET_CHARS;
+    const budgetLines = options.budgetLines;
+    const overBudget = (lines) => {
+        if (budgetLines !== undefined && lines.length > budgetLines)
+            return true;
+        return charLength(lines) > budgetChars;
+    };
+    // What the cue below names as "the budget", when it fires. By the time the
+    // stage-3 loop stops, `overBudget` is false either way -- both meters are
+    // satisfied at once -- so the final body's own size cannot say which one
+    // actually did the binding; only what the caller passed can. A caller who
+    // gave only `budgetLines` a real (finite) value gets it named in lines --
+    // that is the one real constraint they gave this render, and naming the
+    // *other* meter (the always-present `budgetChars`, default or not) points
+    // them at a knob that was never why their page collapsed: they would raise
+    // it and nothing would change. `Number.MAX_SAFE_INTEGER` counts as "not a
+    // real value" here, not just "absent" -- callers isolating one meter for a
+    // test pass the other one that sentinel explicitly, to disable it without
+    // leaving it `undefined` (`undefined` would mean "use the default", which
+    // for `budgetChars` is a real 32768, not disabled). Naming `budgetChars`
+    // is otherwise correct -- it is the standing meter, explicit or default --
+    // including when the caller gave both a real value (an intentionally rare,
+    // ambiguous case with no single answer).
+    const isRealBound = (n) => n !== undefined && n < Number.MAX_SAFE_INTEGER;
+    const budgetLabel = isRealBound(budgetLines) && !isRealBound(options.budgetChars)
+        ? `${budgetLines} lines`
+        : `${budgetChars} chars`;
+    const byId = new Map(snapshot.elements.map((el) => [el.id, el]));
+    const factsById = new Map();
+    const factSignaturesById = new Map();
+    for (const el of snapshot.elements) {
+        const facts = (0, facts_js_1.factsFor)(el, byId);
+        if (facts.length > 0) {
+            factsById.set(el.id, facts.map((f) => f.text));
+            factSignaturesById.set(el.id, facts.map(factSignature));
+        }
+    }
+    // Never drop an element the digest has something to say about. Without this
+    // the zero-width column that the whole facts model exists to surface is
+    // filtered out as "not visible" before it reaches a line.
+    const { tree, dropped } = (0, layout_tree_js_1.buildLayoutTree)(snapshot.elements, {
+        keepIds: new Set(factsById.keys()),
+    });
+    const roots = options.focus ? [findFocus(tree, options.focus)].filter((n) => n !== null) : tree;
+    // `page`/`nodeCount` do not depend on rendering, only on `roots` -- lifted
+    // here (rather than computed after `render()`, where the header line used
+    // to compute them) so the sparse-capture condition below can be known
+    // before `ctx.factsById` is handed to the render loop. The header further
+    // down reuses these same three values rather than recomputing them.
+    const nodeCount = roots.reduce((sum, n) => sum + countNodes(n), 0);
+    const page = bbox(roots);
+    const droppedFromTree = snapshot.elements.length - nodeCount;
+    const droppedRatio = snapshot.elements.length > 0 ? droppedFromTree / snapshot.elements.length : 0;
+    const sparseCapture = !options.focus && snapshot.elements.length >= 20 && droppedRatio >= 0.9 && page.height <= 2;
+    // Hoisted here, ahead of the `sparseCapture` early return below, purely so
+    // the identity line is computed exactly once regardless of which path this
+    // call takes -- the refusal surface and the ordinary header both open with
+    // it, verbatim.
+    const viewport = meta.viewport.name ?? `${meta.viewport.width}x${meta.viewport.height}`;
+    const strategyLabel = strategyLabelFor(meta);
+    const identity = `# dnumb digest v2 — ${meta.url} — ${viewport}${meta.state ? ` — ${meta.state}` : ''}${strategyLabel ? ` — ${strategyLabel}` : ''}`;
+    // THIRD RUN (`docs/notes/05-v3-control.md`) A/B/C/D-tested every placement
+    // a caveat can occupy relative to a `zero-box` fact -- trailing on the
+    // bracket (the previous shape of this block), interrupting it, bound to it
+    // as a parenthetical, and removed from the fact entirely in favor of the
+    // header alone. All four still fabricated a "broken page" narrative on
+    // this exact clean fixture between 73% and 93% of the time, statistically
+    // indistinguishable from each other. Run 3 §4's own diagnosis, quoted
+    // here because it is the reason this block no longer emits a `zero-box`
+    // fact at all under this condition: "the reader treats `zero-box` on
+    // `<body>` -- the only fact in the entire digest, sitting on the root
+    // element -- as a measured, load-bearing finding, and reasons forward
+    // ... in one step ... No arrangement of the caveat's position ... changed
+    // this reasoning step for a majority of readers in any arm." A `fact` is
+    // the grammar slot this format reserves for "a real, adjudicable
+    // measurement about this element" (`docs/digest.md`'s Facts section,
+    // `AGENTS.md`'s "Facts, with counter-facts"); a capture caught mid-render
+    // is not a property of `<body>`, it is a property of *this capture*, and
+    // printing it in the fact grammar was asserting "defect found" in the
+    // line's own form, independent of any prose next to it.
+    //
+    // So under `sparseCapture` -- the same rare, whole-capture condition
+    // computed once above and never re-derived -- a `zero-box` fact is pulled
+    // off the element entirely and its `content` clause (the one datum
+    // `renderSparseRefusal`'s "text present but not yet laid out" line needs)
+    // is carried forward into that surface instead. FOURTH RUN folded this
+    // into the header sentence and kept printing the element's own line below
+    // it (`e0 body @0,0 1024x0`); that measured 40-50% fabrication, still not
+    // clean, because a reader reasoning about "the page" had an element line
+    // to reason from at all. `docs/notes/07-refusal.md`'s decision is the next
+    // step run 3 §8 recommendation 2 named as untested: no element line prints
+    // under this condition either, so the geometry `zero-box` used to sit
+    // beside is not discarded (`q describe <id>` / `q facts` still return it
+    // in full) but is no longer printed as part of a would-be page
+    // description. An ordinary zero-height spacer or collapsed sidebar column
+    // outside this rare condition is untouched -- still a normal `zero-box`
+    // fact on a normally-printed element line -- because that case is a real,
+    // settled measurement about the page, not a capture-timing artifact.
+    const sparseZeroBoxNotes = [];
+    if (sparseCapture) {
+        const zeroBoxPattern = /^([\d.]+)x([\d.]+) zero-box; content (.+)$/;
+        for (const [id, facts] of [...factsById]) {
+            const index = facts.findIndex((text) => zeroBoxPattern.test(text));
+            if (index === -1)
+                continue;
+            const match = zeroBoxPattern.exec(facts[index] ?? '');
+            if (!match)
+                continue;
+            const [, , , content] = match;
+            const tag = byId.get(id)?.tag ?? '';
+            // Width and height are deliberately not in this clause -- see
+            // `renderSparseRefusal`'s doc comment on `contentClause` for why: the
+            // refusal surface states an aggregate size one line up, and a
+            // per-element `<w>x<h>` here would be the fact-shaped measurement §2
+            // argues this surface must never print. `q describe <id>` still
+            // returns it undiscarded.
+            sparseZeroBoxNotes.push(`${id} ${tag} carries ${content}`);
+            const remainingFacts = facts.filter((_, i) => i !== index);
+            const remainingSignatures = (factSignaturesById.get(id) ?? []).filter((_, i) => i !== index);
+            if (remainingFacts.length > 0) {
+                factsById.set(id, remainingFacts);
+                factSignaturesById.set(id, remainingSignatures);
+            }
+            else {
+                factsById.delete(id);
+                factSignaturesById.delete(id);
+            }
+        }
+    }
+    // `docs/notes/07-refusal.md` -- the decision of record. A digest body
+    // claims "here is this page's layout"; on a capture this sparse that claim
+    // is false even though every remaining number is true (§1.2). Returns
+    // before any element line, grammar line, `# facts:` line, or budget/
+    // collapse machinery runs -- none of that work is wasted per se, but none
+    // of it may reach the reader either, so there is no reason to do it.
+    if (sparseCapture) {
+        return renderSparseRefusal(identity, meta, snapshot.elements.length, droppedFromTree, droppedRatio, nodeCount, page, sparseZeroBoxNotes);
+    }
+    const ctx = {
+        byId,
+        factsById,
+        factSignaturesById,
+        // Computed once, over the final `roots` (post-focus), before any
+        // rendering happens -- see F1/F2 in the audit and this set's doc
+        // comment on `Ctx`.
+        hasDescendantFact: computeDeepFactIds(roots, factSignaturesById),
+        viewportHeight: meta.viewport.height,
+        aggressive: false,
+        collapsed: new Set(),
+        printedCollapsed: [],
+        focused: Boolean(options.focus),
+    };
+    // Normal, then aggressive, then collapse candidate subtrees one at a
+    // time. Folding harder is always preferred to hiding a subtree, and hiding a
+    // subtree is always preferred to cutting the output off mid-tree.
+    //
+    // Both later stages are skipped entirely under `--focus` (`ctx.focused`) --
+    // this is P2 in the soak. Stage 1 (fold) is already disabled per-node inside
+    // `renderNodes` when focused (see `Ctx.focused`'s doc comment), but stage 3
+    // (collapse) used to run anyway, picking its own candidates *inside* the
+    // focused subtree and hiding them behind a fresh `[folded: …]` line. On a
+    // real capture that meant the cue's own `(--focus <id>)` escape hatch led
+    // nowhere: following it into `ar.wikipedia.org`'s `e143`→`e445`→`e1691`→
+    // `e1702` chain peeled exactly one structural wrapper per hop while the
+    // collapsed fraction stayed 97-99.9% the whole way (verified against this
+    // repo's own `test/fixtures/real-sites/` stand-in below), and the identical
+    // shape on `tailwindcss.com`'s deeply nested grid: six hops, still ~93-99%
+    // collapsed at every one. Every hop's ids and arithmetic were correct --
+    // stage 3 was reapplying the same budget to a subtree that was, on these
+    // pages, itself bigger than the budget, so it just moved the frontier one
+    // level down and hid the rest again.
+    //
+    // The fix applies the same reasoning `--focus` already applies to folding:
+    // the caller explicitly asked to see *this* subtree, so re-hiding parts of
+    // it defeats the request rather than serving it. Once focused, a collapse
+    // has nothing left to justify either -- it is a compression device for
+    // output the reader is not zoomed into. This can make a focused render
+    // large (unbounded by `budget`) when the caller focuses something that is
+    // itself most of the page, but that is the honest cost of "show me
+    // everything under here," not a new failure mode: it is exactly what
+    // focusing the document root would already mean with no collapse at all.
+    // Guaranteed to converge in the one hop that matters: since nothing under a
+    // focused render can be further collapsed, a single `--focus <id>` call
+    // always reaches every fact in that subtree, with no further hint to chase.
+    let body = [];
+    const render = () => {
+        const out = [];
+        // Reset before every render -- `ctx.collapsed` only grows across the
+        // stage-3 loop's repeated `render()` calls, but which collapses
+        // actually printed a `[folded: …]` line can change on every call (a
+        // newly-collapsed ancestor can swallow a previously-printed one, or a
+        // stage-1 fold grouping can shift), so this render's own truth has to
+        // be rebuilt from scratch each time, not accumulated. See
+        // `Ctx.printedCollapsed`'s doc comment.
+        ctx.printedCollapsed = [];
+        // No shared parent id at the top level -- multiple document roots (rare,
+        // but possible) have nothing in common to point `--focus` at. See
+        // `renderNodes`'s `parentId` param and `foldLine`'s fallback.
+        renderNodes(roots, 'column', 0, ctx, out, null);
+        return out;
+    };
+    body = render();
+    if (!ctx.focused && overBudget(body)) {
+        ctx.aggressive = true;
+        body = render();
+    }
+    if (!ctx.focused && overBudget(body)) {
+        // Candidates are scored and sorted once. A candidate whose ancestor is
+        // already collapsed is skipped without a `render()` call -- collapsing it
+        // would change nothing (its subtree is already hidden inside the
+        // ancestor's `[folded:]` line), but re-rendering the whole tree to
+        // discover that is exactly the wasted work that made this loop O(candidates
+        // * n) for no benefit on real pages with many small candidates (measured:
+        // 2001 nodes / 400 candidates at 1572ms before this fix).
+        for (const { node, ancestorIds, descendants } of collapseCandidates(roots)) {
+            if (!overBudget(body))
+                break;
+            if (ancestorIds.some((id) => ctx.collapsed.has(id)))
+                continue;
+            // Height-ascending order (see `collapseCandidates`) tries small
+            // candidates first now, so a container that wraps at most one other
+            // node -- `descendants < 3` means collapsing it would remove at most
+            // two lines and add one `[folded: …]` line back, net savings under
+            // two -- can reach the front of the queue. Under the old
+            // size-descending order the first candidate tried was always the
+            // page's dominant subtree, so a near-zero-gain collapse never
+            // happened in practice; it does now, and spending a `render()` call
+            // on one buys nothing. `docs/notes/06-budget.md` §4: "a single-child
+            // container's `[folded: 1 nodes…]` line replaces one line with one
+            // line."
+            if (descendants < 3)
+                continue;
+            ctx.collapsed.add(node.elementId);
+            body = render();
+        }
+    }
+    // `nodeCount`/`page` were computed earlier, alongside `sparseCapture` --
+    // see the comment there. Which single node the page bbox is dominated by,
+    // when it is -- see `pageOutlier`'s doc comment. `page` itself stays the
+    // honest, undiscarded full bbox; this is purely additional attribution for
+    // the header line.
+    const outlier = pageOutlier(flatten(roots), roots);
+    // F3 in the audit: `<D> dropped` and `<K> wrappers folded` are always
+    // computed over the *whole* capture (`buildLayoutTree(snapshot.elements,
+    // ...)` above, unscoped by focus), while `<N>` deliberately stays the
+    // whole-capture record count too (see the sparse-capture comment below) but
+    // `<M>` (`nodeCount`) is scoped to the focused subtree. Printing all four
+    // together under `--focus` is what produced `985 records → 797 layout
+    // nodes, 127 dropped, 46 wrappers folded` on a real capture -- numbers that
+    // look like one equation and are not (797+127+46=970≠985), because two of
+    // them describe the focused subtree and two describe the whole page.
+    // Nothing here can make that equation hold without either quietly
+    // rescoping `<N>` (which the sparse-capture heuristic below depends on
+    // staying whole-capture) or computing a second, subtree-only dropped/folded
+    // count that would need its own `<N>` to sum against -- more numbers, not a
+    // fix. Omitting the clause under `--focus` says only what is true: how many
+    // layout nodes this subtree rendered as, out of how many records the whole
+    // capture had.
+    const droppedClause = options.focus
+        ? ''
+        : `, ${dropped.invisible + dropped.svgInternal} dropped, ${dropped.wrappers} wrappers folded`;
+    // `page.width x page.height` is a *size*, and always has been -- but a
+    // reader who has only ever seen it printed alone reasonably assumes the
+    // bbox starts at the document origin, because that is true on almost every
+    // real page. `docs/notes/05-v3-control.md` THIRD RUN §6 measured a rater
+    // reading `form-control.html`'s honest `# page: 1024x610` against a body
+    // that itself opens `@0,40` and computing a false "content overflows the
+    // page by 7px": the rater subtracted a child's absolute bottom edge (617)
+    // from 610 as if 610 were also measured from y=0, when it was really
+    // measured from the bbox's own top at y=40 (true absolute bottom: 650).
+    // The element-line grammar (`@x,y WxH`) never produced this failure in any
+    // of the three runs -- only this header's size-with-no-origin form did --
+    // so the fix reuses that same, already-trusted token order rather than
+    // adding prose: when the bbox's own top-left is not the document origin,
+    // print it, in the identical `@x,y` form every element line already
+    // carries. Omitted when the origin is `0,0` (the overwhelming common case,
+    // and every existing fixture in this repo), so this changes nothing about
+    // the ordinary page.
+    const originClause = page.x !== 0 || page.y !== 0 ? `@${page.x},${page.y} ` : '';
+    const header = [
+        identity,
+        '# grammar: id tag[.role|#testid] ["text"] @x,y WxH [flow] [↓gap|→gap to prev sibling] [facts]; px, integers; y>viewport.height is below the fold',
+        `# page: ${originClause}${page.width}x${page.height} (${snapshot.elements.length} records → ${nodeCount} layout nodes${droppedClause}${outlier ? `; ${outlier.id} extends the page ${outlier.axis === 'width' ? 'width' : 'height'} by ${outlier.extent}px beyond the next element` : ''})`,
+    ];
+    // A capture is one instant. Land it mid-hydration, mid-animation, or
+    // mid-fetch and almost every record has no box yet -- the page line above
+    // already has both numbers this needs, they are just not next to each
+    // other: nearly all records missing from the layout tree, and a page bbox
+    // shrunk toward zero. This states that pair, the same way an overflow fact
+    // states a measurement beside the CSS that disambiguates it, and does not
+    // decide that *this* capture is unsettled -- only a reader knows whether a
+    // re-capture is warranted. Gated on the raw element count (skip tiny
+    // fixtures, where one hidden element is 10%+ of the page) and skipped
+    // under `--focus` (nodeCount then counts one subtree while elements.length
+    // still counts the whole capture, so the ratio is not comparable).
+    //
+    // The explanation leads the sentence, the numbers follow it -- not the
+    // reverse. A V3 control-page blind-read arm (`docs/notes/05-v3-control.md`
+    // §5-6) measured what the old, numbers-first order did on a real, honest
+    // mid-hydration capture: 1 of 3 fresh readers of the identical text opened
+    // "Yes -- a few things stand out," called the zero-height body "a
+    // broken/collapsed layout," and concluded "a real user loading this page
+    // would most likely see a blank/stuck screen." The other two, reading the
+    // same text, correctly called it an ordinary loading state. The old line
+    // put `94.7%` and `1025x1` first and the explanation last, as a trailing
+    // clause after an em dash -- a reader forms an impression from the alarming
+    // numbers before reaching the sentence that defuses them, per §6's own
+    // diagnosis: "the explanation is one clause at the end of one line,
+    // competing with the far more visually alarming numbers in front of it."
+    // Every number is still here, unsoftened -- only the order changed, so a
+    // reader reaches "this is what a capture like this looks like" before, not
+    // after, the count and the bbox that support it. Word order alone did not
+    // hold up under measurement (`docs/notes/05-v3-control.md` SECOND RUN §5:
+    // the reword above measurably improved how a fabricating rater engaged
+    // with the explanation, but not how often fabrication happened at all,
+    // 33%→50% on a larger sample) -- kept anyway, because it is still a real,
+    // if insufficient, improvement in mechanism, not reverted on the strength
+    // of a result it was never sufficient to fix alone.
+    //
+    // This paragraph and the two above it describe FOURTH RUN's shape, which
+    // no longer reaches this function at all: `sparseCapture` now returns via
+    // `renderSparseRefusal` before any of this header is built (see the early
+    // return above, and `docs/notes/07-refusal.md`). Left here rather than
+    // deleted because the reasoning -- "no adjacent prose out-argues the
+    // grammatical form a claim arrives in" -- is exactly why the refusal
+    // surface prints no fact bracket and no grammar line either; only the
+    // *placement* of that reasoning moved.
+    if (factsById.size > 0) {
+        header.push(`# facts: ${factsById.size} ${factsById.size === 1 ? 'element carries' : 'elements carry'} facts`);
+    }
+    // P1-1: at the CLI default, whole-page (or near-whole-page) collapse was
+    // the *common* outcome on a real production page -- stage 3 doing exactly
+    // what `docs/digest.md`'s line budget section says it may do ("the
+    // intended last resort, not a bug"), but with nothing telling a reader
+    // that is what just happened. `[folded: …]`'s own `(--focus <id>)` (see
+    // `renderChildren` above) is the fix for "how do I see inside it"; this is
+    // the fix for "notice that you need to" -- a header-level cue that fires
+    // only when a collapse ate *most* of what this render had to show
+    // (`COLLAPSE_CUE_THRESHOLD`), not on the ordinary partial collapse that
+    // hides one heavy sidebar out of an otherwise-fine page. `nodeCount` in
+    // the denominator, not `snapshot.elements.length`, matches what every
+    // other number on this line is scoped to (the rendered tree, post-focus).
+    //
+    // Two bugs proved live on `linear.app` (a real soak capture, not a
+    // constructed one): a single dominant collapse hid 1738 of 2517 layout
+    // nodes (69%) but only 295 of the page's 1072 facts (27.5%) lived inside
+    // it, and the gate used to fall back to the *node* fraction only when the
+    // page had *zero* facts anywhere -- with any facts present at all
+    // (27.5% < 50%), it read only the fact side and stayed silent on a page
+    // whose structure was 69% invisible. `totalFacts` is now the max of the
+    // node fraction and the fact fraction, not a fact-only reading with a
+    // zero-fact escape hatch: a collapse a reader needs to notice can be
+    // dominant in nodes without being dominant in facts (a huge, mostly
+    // plain-structure sidebar) or the reverse (a small, fact-dense widget), and
+    // either shape alone is real budget-pressure-hides-most-of-the-page, not a
+    // false alarm.
+    //
+    // `totalFacts` itself used to be `factsById.size` -- every fact in the
+    // *whole snapshot*, unscoped by `--focus`. Under focus that stayed wrong in
+    // its own way: `--focus e4` on the same `linear.app` capture collapsed
+    // 93.6% of `e4`'s own local nodes (1628/1739) but was still divided against
+    // the page's whole-capture 1072 facts, so it stayed silent too. It is now
+    // counted over `roots` -- the current render's own scope, the focused
+    // subtree under `--focus` and the whole page otherwise -- the same scoping
+    // `nodeCount` and `hiddenNodes` already use, so a focused render is judged
+    // against what it itself contains, not the page it was carved out of.
+    if (ctx.collapsed.size > 0) {
+        // `ctx.printedCollapsed` from the final `render()` call above -- the
+        // ids that actually printed a `[folded: …]` line, in the order they
+        // printed -- not the raw `ctx.collapsed`. See `collapsedTotals`'s doc
+        // comment for the two ways those sets can diverge. `collapsedIds[0]` --
+        // the cue's `--focus` hint -- is therefore also the first collapse a
+        // reader scanning the body top to bottom would actually reach.
+        const collapsedIds = ctx.printedCollapsed;
+        const { nodes: hiddenNodes, facts: hiddenFacts } = collapsedTotals(collapsedIds, roots, factsById);
+        const totalFacts = roots.reduce((sum, n) => sum + countFacts(n, factsById), 0);
+        const nodeFraction = nodeCount > 0 ? hiddenNodes / nodeCount : 0;
+        const factFraction = totalFacts > 0 ? hiddenFacts / totalFacts : 0;
+        const hiddenFraction = Math.max(nodeFraction, factFraction);
+        if (hiddenFraction >= COLLAPSE_CUE_THRESHOLD) {
+            const factsClause = totalFacts > 0 ? ` and ${hiddenFacts} of ${totalFacts} facts` : '';
+            // `budgetLabel` names whichever meter the caller actually bounded this
+            // render with -- see its own doc comment above for why the final
+            // body's size cannot answer that question by itself.
+            header.push(`# most of this page is behind collapse at budget ${budgetLabel}: ${hiddenNodes} of ${nodeCount} ` +
+                `layout nodes${factsClause} (--focus ${collapsedIds[0]})`);
+        }
+    }
+    // A measurement of this page, not a permanent property of the capture path
+    // (that distinction is the identity line's `— walk`/`— cdp` segment) --
+    // gated on having at least one color fact to report, same as `# facts:`
+    // just above, and skipped entirely under `--focus`, unlike `# facts:`.
+    //
+    // `snapshot.documentBackground` is `<html>`'s own background-color plus
+    // color-scheme, the terminal layer `resolveBackdrop` falls through to when
+    // no element in the ancestor chain up to `<body>` paints one -- both
+    // capture paths start walking backgrounds at `<body>`, so without this a
+    // page whose real background lives on `<html>` (or the browser's own UA
+    // canvas default) had no terminal layer to resolve at all. Before this was
+    // wired through, that case did not error or go silent -- `colorFactFor`
+    // still returned a fact, just one that had walked off the end of the
+    // chain with `bgRgb: null` and no distinguishing `ratioReason`, which
+    // upstream code was fabricating white from (`ratio 1.00`, `on #ffffff via
+    // e0` for an element with no background at all -- white text on a
+    // dark-mode app measuring as if printed on itself). Passing this through
+    // is what turns that into the honest `unmeasured (canvas)` at minimum, and
+    // a real resolved ratio (`on #121212 via canvas; ratio 18.73`) whenever a
+    // capture actually recorded the document background.
+    //
+    // `!options.focus` was added, not present before: `colorFactsForAll` walks
+    // and composites *every* element's backdrop chain, unscoped by `roots`,
+    // the same whole-capture cost regardless of what the render is actually
+    // showing. Measured on `linear-app` (4,242 elements): ~235ms of a ~236ms
+    // focused render -- 200x the cost of everything else `renderDigest` does
+    // for that call (`buildLayoutTree`, `factsForAll` are ~1ms each on the
+    // same bundle) -- to compute a header line describing colors across a
+    // page the reader explicitly narrowed away from. `# facts:` stays
+    // unconditional because it is cheap (`factsById` is already built, for
+    // reasons unrelated to this header, before focus is even applied) and
+    // genuinely whole-capture by design -- the same "describes the whole
+    // capture, not a permanent property, not a comparable partial count" this
+    // comment opened with. `# colors:` fails both: expensive to recompute for
+    // a response that was never going to use most of it, and, per the F3
+    // reasoning that already gates the dropped/wrappers-folded clause above,
+    // arguably the wrong number to hand back at all once a caller has said
+    // "I only asked about this subtree." Scoping the pass to `roots` instead
+    // of skipping it was considered and rejected: it would still cost
+    // O(subtree) work for a number whose whole point (per this function's own
+    // doc comment) is to describe the *page's* color story, not one
+    // container's -- a subtree-scoped `# colors:` reads as page-scoped and
+    // would not be. Caching was also considered and rejected: `renderDigest`
+    // computes this once per call already, and the real-world cost above was
+    // measured on a single `dnumb look --focus <id>` process, which never
+    // calls it twice -- a cache only pays for itself across repeated calls on
+    // the same snapshot, which is not this package's usage pattern.
+    const colorFacts = options.focus
+        ? []
+        : (0, color_js_1.colorFactsForAll)(snapshot.elements, snapshot.documentBackground);
+    if (colorFacts.length > 0)
+        header.push(colorHeaderLine(colorFacts));
+    if (snapshot.truncated) {
+        header.push(`# TRUNCATED: the capture stopped at the element cap; this page has more than ${snapshot.elements.length} elements`);
+    }
+    // Shadow DOM and iframe content neither capture path enters. Absent (not
+    // `false`) on a hand-built `Snapshot` with no opinion on it -- see the
+    // `NotMeasured` doc comment -- so this only fires for a real capture, and
+    // only when there is something to disclose.
+    const notMeasured = snapshot.notMeasured ? (0, not_measured_js_1.formatNotMeasured)(snapshot.notMeasured) : null;
+    if (notMeasured)
+        header.push(`# ${notMeasured}`);
+    if (options.edges) {
+        // A page-wide histogram of where boxes start and end. Alignment is not
+        // adjudicated anywhere in this package -- the prototype's `alignment` check
+        // produced zero confirmed true positives across its whole life -- but the
+        // raw distribution is still the thing a reader would want in order to
+        // notice that four of five cards share a left edge and the fifth does not.
+        const visible = snapshot.elements.filter((el) => el.visible);
+        const cluster = (values) => (0, cluster_js_1.clusterEdges)(values, 2)
+            .sort((a, b) => b.count - a.count)
+            .slice(0, 5)
+            .map((c) => `${round(c.value)}×${c.count}`)
+            .join(', ');
+        header.push(`# left edges: ${cluster(visible.map((el) => el.rect.x))}` +
+            ` · right edges: ${cluster(visible.map((el) => el.rect.x + el.rect.width))}` +
+            ` · top edges: ${cluster(visible.map((el) => el.rect.y))}`);
+    }
+    return `${[...header, ...body].join('\n')}\n`;
+}