@michaelmagan/dnumb 0.1.0 → 0.1.2

package/docs/digest.md

@@ -0,0 +1,1600 @@
+# The dnumb digest format
+
+Spec version 1. Digest grammar version 2. Produced by `renderDigest`, read back by
+`parseDigestLine`. Both are exported from the package root.
+
+A digest is a rendered page written as text: one line per element that stands on its own, one fold
+line standing in for a whole run of repeated siblings at once (see [The fold
+line](#the-fold-line)), positions and sizes in CSS pixels, plus the measurements that say whether
+content fits inside its box. It exists so a model can answer *where is this and how big is it*
+without looking at an image.
+
+It reports. It does not adjudicate. Every number that could mean two things is printed beside the
+CSS that decides which, and the reader draws the conclusion. See
+[Facts](#facts) and [Reading a fact](#reading-a-fact).
+
+## Producing one
+
+```ts
+import { capture, renderDigest } from '@michaelmagan/dnumb';
+
+const snapshot = await capture(page); // page: any object with `evaluate`
+const digest = renderDigest(snapshot, {
+  url: page.url(),
+  viewport: { width: 1024, height: 768 },
+  state: 'menu-open',
+});
+```
+
+Or from a bundle written earlier, on a machine with no browser:
+
+```ts
+import { parseBundle, renderDigest } from '@michaelmagan/dnumb';
+import { readFileSync } from 'node:fs';
+
+const bundle = parseBundle(readFileSync('.dnumb/settings-desktop.json', 'utf8'));
+const digest = renderDigest(bundle, {
+  url: bundle.url,
+  viewport: bundle.viewport,
+  state: bundle.name,
+});
+```
+
+A `Bundle` satisfies the `Snapshot` shape `renderDigest` takes, so no conversion step exists.
+
+`renderDigest(snapshot, meta, options?)`:
+
+| Argument | Shape |
+|---|---|
+| `snapshot` | `{ elements: ElementRecord[]; truncated: boolean; viewport: { width, height }; notMeasured?: NotMeasured }` |
+| `meta` | `{ url: string; viewport: { name?, width, height }; state?: string; capturedAt?: string; strategy?: 'cdp' \| 'walk'; cdpFellBack?: boolean }` |
+| `options.budgetChars` | Soft character budget for the body — the standing meter, always active. Default `32768`. |
+| `options.budgetLines` | Soft line budget for the body. Optional, no default of its own; when a caller passes it, it is an *additional* ceiling on top of `options.budgetChars`, never a replacement for it. |
+| `options.focus` | Element id or tag name. Scopes output to that subtree. Neither budget applies once focused. |
+| `options.edges` | `true` adds the edge-cluster header. Default `false`. |
+
+The return value is one string ending in `\n`.
+
+## A complete digest
+
+Captured from `test/fixtures/clipped-menu.html` at 1024x768, after the menu was opened:
+
+**Live example** (`fixture=test/fixtures/clipped-menu.html url=file://.../clipped-menu.html state=menu-open after=__toB`) — regenerated fresh by `test/browser/doc-examples.test.ts` every run; if the renderer's output ever drifts from this block, that test fails before a reader trusts it.
+
+```text
+# dnumb digest v2 — file://.../clipped-menu.html — 1024x768 — menu-open — cdp
+# 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: 1024x213 (10 records → 10 layout nodes, 0 dropped, 0 wrappers folded)
+# facts: 5 elements carry facts
+# colors: 4 fg/bg pairs across 7 text elements; ratio 18.26–18.88; lowest e3 #000000 on #efefef self 13.3px/400; 1 unmeasured (1 under)
+e0 body @0,0 1024x181
+  e1 h1.heading "Account settings" @24,24 976x25
+  e2 div @24,65 976x44 [row] ↓16 [overflow-y +105px; clip]
+    e3 button.button "Actions" @39,77 60x21
+    e4 span "3 selected" @111,75 90x24 →12
+    e5 nav.menu "Actions" @39,104 182x109 →-110 [clipped by e2 div; overflow:hidden, not scrollable; 103.8px below, 182x5 visible]
+      e6 a.menuitem "Rename" @40,105 180x36 [clipped by e2 div; overflow:hidden, not scrollable; 31.6px below, 180x4 visible]
+      e7 a.menuitem "Duplicate" @40,141 180x36 ↓0 [clipped by e2 div; overflow:hidden, not scrollable; 67.2px below, nothing visible]
+      e8 a.menuitem "Delete" @40,176 180x36 ↓0 [clipped by e2 div; overflow:hidden, not scrollable; 102.8px below, nothing visible]
+  e9 p.paragraph "The menu is clipped by the too…" @24,123 976x20 ↓14
+```
+
+The 44px-tall toolbar `e2` reports 105px of vertical overflow with `clip` beside it, and the menu
+`e5` overlaps its own previous sibling `e4` — negative, per [gap](#gap) below. Neither line says
+"bug". The reader combines them. `e6`, `e7` and `e8` do not fold together despite sharing a tag,
+role and box size: a `clipped` fact is part of the fold signature the same way an `overflow-x` fact
+is, and `e6` is genuinely different from the other two — it still shows a 4px sliver where they
+show nothing.
+
+## Header lines
+
+Every header line starts with `#`. `parseDigestLine` returns `null` for all of them. They are
+emitted in this order; lines 4-10 are conditional. **One condition is not merely conditional but
+exclusive: under sparse capture (item 4), items 2 and 3 below do not print at all, nothing after
+item 4 prints either, and item 4 itself becomes four different lines replacing the entire body —
+see item 4 for why and exactly what prints instead.** Every "always" below should be read as "always,
+except when item 4's refusal condition has already replaced the body.
+
+**1. Identity — always, including under the item 4 refusal.**
+
+**Grammar template** — placeholders, not real output; see the complete digest above for what the
+segments look like filled in.
+
+```text
+# dnumb digest v2 — <url> — <viewport> — <state> — <strategy>
+```
+
+`<url>` is `meta.url` verbatim. `<viewport>` is `meta.viewport.name` when set, otherwise
+`<width>x<height>`. The ` — <state>` segment is omitted entirely when `meta.state` is absent.
+Two captures of one URL are only distinguishable by `state`, so name it.
+
+**The literal string `dnumb` in this line is a wire-format identifier, not the npm package name.**
+It names the digest grammar (`dnumb digest v2`), the same way an HTTP response names `HTTP/1.1` —
+a label a parser matches on, not a product name that tracks the registry. The package publishes as
+`@michaelmagan/dnumb`; this header does not follow it, on purpose: `parseDigestLine` and every tool
+that reads a digest by scanning for this literal string would break on a scope-only rename that
+changed nothing about what the format actually is. Do not "fix" this line to read `@michaelmagan/dnumb
+digest v2` if the package is ever renamed or rescoped again — the two names are allowed to diverge,
+and this one is pinned.
+
+The ` — <strategy>` segment is omitted when `meta.strategy` is absent, otherwise one of `cdp`,
+`walk`, `walk (cdp fell back)`, `walk (closed shadow roots undetectable)`, or `walk (cdp fell back,
+closed shadow roots undetectable)`. A reader comparing two digests needs to know which capability
+tier produced each one, not just what it found — see [Not
+measured](#7-not-measured--only-when-there-is-something-to-disclose) for what `cdp` and `walk` do
+and do not see on a page with shadow DOM, and why that gap is not as clean as "cdp sees it, walk
+does not." `walk (cdp fell back)` is the case worth noticing on its own: it means the CDP fast path
+was tried on a Chromium page and its own protocol call failed, so this is an unplanned downgrade
+rather than a deliberate portable capture on a browser CDP never covers. The `closed shadow roots
+undetectable` clause is a permanent property of the `walk` path itself, not a measurement of this
+particular page — every `walk` capture carries it, regardless of whether the page has any shadow
+DOM at all, which is why it lives here rather than on the page-specific `# not measured:` line (see
+below).
+
+**2. Grammar — always, byte-identical every time, except under the item 4 refusal, where there is no grammar to explain because there is no body.**
+
+**Live example** (`synthetic=header-grammar-line`) — the literal string, not a template; checked
+verbatim against `renderDigest`'s own output by `test/unit/doc-examples.test.ts` on every run.
+
+```text
+# 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
+```
+
+**3. Page — always, except under the item 4 refusal, which reports the same dropped/kept counts in its own sentence instead.**
+
+**Grammar template** — placeholders; the plain form is real and checked in place in the complete
+digest above. The dominance-clause form is a live example right below.
+
+```text
+# page: [@<x>,<y> ]<W>x<H> (<N> records → <M> layout nodes, <D> dropped, <K> wrappers folded)
+# page: [@<x>,<y> ]<W>x<H> (<N> records → <M> layout nodes, <D> dropped, <K> wrappers folded; <id> extends the page <width|height> by <Npx> beyond the next element)
+# page: [@<x>,<y> ]<W>x<H> (<N> records → <M> layout nodes)
+```
+
+**Live example** (`synthetic=page-dominance-line`) — `e2`'s own bottom edge is the page bbox's `y`
+bound, and the gap to the runner-up (`e1`) is more than 10x `e1`'s own height; `e0`, the root, is
+excluded from the comparison on principle even though it is taller still.
+
+```text
+# page: 1024x500 (3 records → 3 layout nodes, 0 dropped, 0 wrappers folded; e2 extends the page height by 460px beyond the next element)
+```
+
+`<W>x<H>` is the bounding box of everything rendered, rounded to integers. `<N>` is the number of
+captured `ElementRecord`s. `<M>` is the number of nodes in the rendered tree. `<D>` counts
+elements dropped for having no visible box plus SVG internals. `<K>` counts single-child wrapper
+elements folded into their parent's line.
+
+`M` is smaller than `N` on any page with hidden or decorative markup, and the difference is not
+an error. A dropped element
+never takes its subtree with it: surviving children are spliced up to the nearest surviving
+ancestor.
+
+**`@<x>,<y> ` prefixes the size when the bbox's own top-left is not the document origin — omitted
+entirely, and byte-identical to before this existed, when it is `0,0`.** A bare `<W>x<H>` looks
+like a size with no origin, and a reader who has only ever seen ordinary pages reasonably assumes
+it is measured from `y=0` — true on almost every real page, but not on one whose own content starts
+below the top. Measured: a rater reading an honest `# page: 1024x610` against a body that itself
+opens at `@0,40` subtracted a child's absolute bottom edge from `610` as if `610` were also
+measured from `y=0`, and reported a fabricated "content overflows the page by 7px" — the true
+absolute bottom, measured correctly from the bbox's own top at `y=40`, was `650`, comfortably
+inside. The element-line grammar (`@x,y WxH`) never produced this failure in the same testing; only
+this header's size-with-no-origin form did, so the fix reuses that exact, already-trusted token
+order rather than adding a sentence of prose. The [complete digest](#a-complete-digest) and every
+other example on this page happen to open at the document origin, so none of them show the prefix;
+[the sparse-capture example](#header-lines) below does (`@-1,-1`), and a real production page can
+carry a large negative one — `ar.wikipedia.org`'s own pinned capture reports `@0,-99791`, from a
+visually-hidden accessibility label parked far above the visible page.
+
+**The third grammar form, with no `<D> dropped, <K> wrappers folded` clause at all, is what
+`--focus` prints.** Both counts are computed over the *whole* capture, unscoped by focus, while `M`
+is scoped to the focused subtree — printing all of them together used to produce numbers that look
+like one equation and are not (`985 records → 797 layout nodes, 127 dropped, 46 wrappers folded`,
+where `797 + 127 + 46 ≠ 985`, because two of the four describe the subtree and two describe the
+whole page). Rather than resolve that by rescoping `D`/`K` to the subtree — which would need its own
+second `N` to make sense of, more numbers, not fewer — a focused header just omits the clause: `M`
+out of the whole capture's `N` records, and nothing about drops or wrapper folds.
+
+**`<W>x<H>` is the real, undiscarded bounding box, and it can be huge.** A virtualization
+spacer, a visually-hidden accessibility label parked thousands of pixels off-canvas, or a hidden
+cookie-notice heading positioned far to one side each push it to a size that has nothing to do
+with what a reader would call "the page" — measured on real sites: `4512x3802616`, `1441x106410`,
+`11414x4272`. This package does not clamp or discard that number; it is a real measurement, and
+the element responsible is often folded or dropped out of the body, so the header would otherwise
+be the only trace of it.
+
+**The trailing `; <id> extends the page <width|height> by <Npx> beyond the next element` clause
+names the element responsible, when one is identifiable.** It only fires for a candidate whose own
+edge literally *is* one of the page bbox's four bounds (leftmost, rightmost, topmost, or
+bottommost) — being merely the biggest element on the page is not enough, and is not what this
+checks. Given such a candidate, if the gap from it to the runner-up on that same side is more than
+~10x the runner-up's own size on that axis, the clause names it. This is deliberately not "biggest
+element by raw size": a plain header/hero/footer page has one element bigger than the rest by a wide
+margin with nothing anomalous about the page total, and would be wrongly named by a same-size
+comparison; the actual real-world case this clause exists for — an off-canvas accessibility label
+tens of thousands of pixels from everything else — is often a `1x1` box with no size to speak of at
+all, and is only findable by *position* (its edge reaching far past where anything else on the page
+reaches), which is what this checks instead. Root containers are excluded from candidacy — their own
+box reflects their content's extent by construction, so if every non-root candidate falls short of
+the true bound, a root's box is what reaches it, and a container being large is not itself the
+finding.
+
+**4. Sparse capture — replaces the entire digest body, not a header line among the others.**
+
+**This item is structurally different from every other item on this list, and the exception
+belongs stated up front: under this one condition, items 2 and 3 above (the grammar line and the
+`# page:` line) do not print at all, and neither does anything below — no element lines, no
+`[...]` brackets, no `# facts:`, no `# colors:`.** `look` declines to render a digest body and
+renders a capture-level refusal instead. The identity line (item 1) is the only other line that
+still prints, because capture provenance is a fact about the capture, which is exactly what this
+surface reports.
+
+**The general rule — this is worth internalizing on its own, because it now governs three
+different scopes in this format, and it is the sharpest statement of this project's own
+discipline:**
+
+> Every output surface carries an implicit claim in its form, and dnumb never emits a form whose
+> implicit claim the capture cannot support.
+
+Three rungs of the same rule, smallest scope to largest:
+
+- **Token scope.** `ratio unmeasured (gradient)`, `unknown (canvas)`, `walk (closed shadow roots
+  undetectable)` — a single value the capture cannot honestly produce prints its reason instead of
+  a guessed number.
+- **Line scope.** `# not measured: 2 iframes (1 cross-origin)` — a whole disclosure line reports
+  what a capture path walked past rather than leaving its absence to be discovered by silence.
+- **Body scope — this item.** A digest body's own form claims "here is this page's layout." On a
+  capture where the overwhelming majority of records never reached a layout node and the entire
+  rendered extent is a degenerate sliver, that claim is false even though every individual line in
+  such a body would be true. So the body itself does not print; a refusal surface describing the
+  *capture* prints instead.
+
+**Why a refusal, not one more wording fix — this is measured, not a first attempt.** Four rounds
+of reader testing tried five different placements of a caveat explaining a genuinely clean
+mid-hydration capture, each on real, honest, unaltered output: trailing after the numbers,
+interrupting the `zero-box`/`content` pairing, header-only, parenthetical on the fact, and leading
+the header with its own explanation. None got a blind rater's fabrication rate ("this page is
+broken") below roughly a third, and one made it measurably worse (33%→50% on a larger sample).
+Removing the `zero-box` fact from the element line entirely and moving its content into the header
+sentence — a structural change, not a wording one — roughly halved the rate (down to ~43%, pooled
+across two fixtures) but still did not clear it, because a header restating the same numbers above
+a body whose element lines still wear the form of a page description gave readers exactly as much
+to reason from. The diagnosis that survived four rounds: fabrication tracks the *form* of the
+output, not the prose next to it. This refusal is the completion of that diagnosis, not a new
+idea — it is what removing the fact bracket was already pointing at.
+
+**Gated on the same condition that has gated this disclosure throughout its evolution, unchanged:
+`!options.focus && elements.length >= 20 && dropped/total >= 0.9 && page.height <= 2`.** Swept
+directly against every committed real-site bundle in this repo (`ar-wikipedia`, `excalidraw`,
+`grafana-play`, `hackernews`, `mdn-array`, `shoelace-docs`, `shoelace-docs-walk`,
+`tailwind-docs`) — verified here, not merely cited: **0 of 8 fire**, none of them close on either
+leg (the worst real site's dropped-ratio is tens of points under the 0.9 threshold, and every real
+site's page height is hundreds of pixels or more against the ≤2px leg). The gate cannot fire on a
+page where a partial digest would have served, because firing requires that no partial digest
+exists.
+
+**Live example** (`fixture=test/fixtures/hydration-race.html url=file://.../hydration-race.html state=race strategy=walk`)
+— `test/fixtures/hydration-race.html` reproduces, with a plain `setTimeout` and no framework, the
+exact shape a production soak found mid-render on a real site: dozens of nodes mounted but not yet
+laid out, and a body collapsed toward zero height. Regenerated fresh by
+`test/browser/doc-examples.test.ts`.
+
+```text
+# dnumb digest v2 — file://.../hydration-race.html — 1024x768 — race — walk (closed shadow roots undetectable)
+# no layout to digest: 36 of 38 records never reached a layout node (94.7%), and the 2 that did fit in a 1025x1 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.
+# text present but not yet laid out: e0 body carries "Loading Row 1 Row 2 Row 3 Row 4 Row 5 Ro".
+# to measure the page, capture later in its life: dnumb capture file://.../hydration-race.html --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.
+```
+
+**Three things this surface does that a bare "cannot render" would not:**
+
+1. **Nothing was discarded.** `q facts`, `q describe <id>`, `q find <text>`, and `look --focus
+   <id>` all bypass this gate and return the full, unrerouted measurement — verified directly:
+   `q facts` on this same capture still returns `e0`'s complete `zero-box` fact, brackets and all,
+   because `src/snapshot/facts.ts` (what those verbs read from) was deliberately left untouched.
+   This changes what `look` prints by default; it does not change what was measured or what
+   remains reachable.
+2. **The persistence protocol is the more interesting half.** One capture cannot distinguish "still
+   loading" (re-capture later and it will look normal) from "never lays out" (a real, permanently
+   broken page) — which is precisely why *one* capture must not render a body that invites a
+   reader to guess between them. The refusal instead turns that ambiguity into a two-capture
+   protocol with a genuine answer: if a second capture, later, still refuses the same way, that
+   repetition is itself a measurement no single capture could make — a page that never lays out,
+   not a page caught mid-load. A refusal that names its own escape hatch is a diagnostic step, not
+   a dead end.
+3. **The gate is a presentation threshold, not a fact threshold — the plan's "no thresholds beyond
+   subpixel noise" still holds.** `sparseCapture` decides which *surface* renders; it does not
+   round, suppress, or soften a single number in the bundle. Every value this surface states is
+   the same real value the pre-refusal header sentence stated.
+
+**Verify this against a live blind read before trusting the specific wording above as settled.**
+As of this writing this exact surface is unproven by the same discipline as every version before
+it: the team that built it does not claim it works, and a pre-registered blind-read run (bar: 0
+fabrications in n≥30; any single fabrication reopens the item, per this project's own kill
+criterion) is open against it now. What is not provisional is the rule three rounds of evidence
+converged on — a capture-state observation must not be rendered in a form whose implicit claim it
+cannot support — and the three-rung ladder above, which holds regardless of how this specific
+surface's wording resolves.
+
+**5. Facts — only when at least one element carries one.**
+
+**Grammar template** — the two real forms are singular/plural of the same line; the plural form is
+checked live in the complete digest above (`5 elements carry facts`). No shipped fixture in this
+document currently produces the singular count, so the `1 element carries facts` form above is a
+template, not a live-checked instance.
+
+```text
+# facts: 1 element carries facts
+# facts: 2 elements carry facts
+```
+
+**6. Colors — only when at least one element carries a color fact.** Full grammar, worked
+examples, and the adjudication rules that keep it a measurement rather than a verdict are in
+[Color](#color) below — including why the clause is a measurement of *this page* (`# colors:`)
+rather than a permanent property of the capture path (which is why it does not live on the
+identity line the way `# not measured:`'s shadow-DOM caveat does).
+
+**7. The collapse cue — only when a stage-3 collapse (see [The line
+budget](#the-line-budget)) has hidden at least half of what this render had to show.**
+
+**Grammar template** — placeholders; the live example right below is a real instance.
+
+```text
+# most of this page is behind collapse at budget <B> chars|lines: <H> of <M> layout nodes[ and <HF> of <TF> facts] (--focus <id>)
+```
+
+**Live example** (`synthetic=collapse-cue-header`) — the same ten-child scenario as [The collapsed
+line](#the-collapsed-line) above, rendered with an explicit `budgetLines: 3` and no `budgetChars`
+override, full digest this time so the header itself is visible: all 3 of the page's facts sit
+inside the one collapse, so the hidden fraction reads 100%.
+
+```text
+# dnumb digest v2 — https://example.test/page — 1024x768
+# 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: 1024x800 (12 records → 12 layout nodes, 0 dropped, 0 wrappers folded)
+# facts: 3 elements carry facts
+# most of this page is behind collapse at budget 3 lines: 10 of 12 layout nodes and 3 of 3 facts (--focus e1)
+e0 body @0,0 1024x800
+  e1 div @0,0 300x400
+    [folded: 10 nodes, 3 facts, bbox @0,0 300x390 (--focus e1)]
+```
+
+**`<B>` names whichever meter actually bound this render, with its own unit attached — `chars` or
+`lines` — never a bare number.** This matters because the two meters usually are not both real
+constraints at once: a bare `look` (or `renderDigest` call with no options) is bound only by
+`budgetChars` (the standing default, 32768), so the cue names chars; the example above passed
+`budgetLines: 3` and nothing for `budgetChars`, so the cue names *that* — the one real constraint
+this particular render had. Naming the wrong meter used to be a real bug: a render bound by
+`budgetLines` that got told "the budget is 32768" pointed a reader at a knob (`--budget-chars`)
+that would not change anything, because raising the char budget does nothing when the line budget
+is what actually stopped the render. `<H>` and `<M>` are node counts — how many layout nodes are
+hidden behind every collapse on this render, out of how many this render produced in total; the `
+and <HF> of <TF> facts` clause is present only when the page has at least one fact at all, and
+names the same fraction in terms of measurements instead of nodes, which is usually the number
+that matters more. `<id>` is the first collapsed container's own id — the same one printed on its
+own `[folded: …]` line — so the cue is never a dead end.
+
+**The gate is a real fraction, not "any collapse happened."** A collapse hiding one heavy sidebar
+out of an otherwise-unremarkable page is the budget ladder working exactly as intended, and does
+not need a header-level flag; a collapse that ate most of what this render had to show is a
+different situation a reader should notice before trusting the body as representative. The
+threshold is 50%, computed against both the layout-node fraction and, when the page has any facts,
+the fact fraction — the cue fires when either reaches it, whichever is worse. A page can hide most
+of its *structure* while its facts stay mostly visible, or the reverse (measured on a real page:
+`linear.app` hid 69% of its layout nodes behind collapse while only 27.5% of its facts were caught
+up in that same collapse — checking facts alone would have left the cue silent on a page whose
+structure was two-thirds invisible). The fact total is scoped to the current render's roots — the
+focused subtree under `--focus`, the whole page otherwise — not the whole capture, matching every
+other number on this line. [The collapsed line](#the-collapsed-line)'s own per-collapse `(--focus
+<id>)` answers "how do I see inside this one collapse"; this line answers "do I need to."
+
+**8. Truncation — only when the capture hit the element cap (5000).**
+
+**Grammar template** — `<N>` is `snapshot.elements.length`; this package's test suite does not ship
+a 5000-element fixture, so this line is not exercised as a live example here. It is exercised
+directly in `test/unit/digest.test.ts`.
+
+```text
+# TRUNCATED: the capture stopped at the element cap; this page has more than <N> elements
+```
+
+The page has more elements than the digest describes. Re-capture a narrower region rather than
+reasoning about what is missing.
+
+**9. Not measured — only when there is a real, counted, page-specific number to disclose.**
+
+**Illustrative** — hand-composed to show the iframe segment, which no shipped fixture in this
+document exercises, alongside the shadow-root segment; a real, checked instance of the shadow-root
+form alone is in the sparse-capture example above.
+
+```text
+# not measured: 2 iframes (1 cross-origin), 14 shadow roots
+# not measured: 1 open shadow root
+```
+
+Neither capture path enters an iframe's content document. `collect.ts`'s portable walk also never
+enters a shadow root — it reads `el.children`, and shadow content is not part of that, open or
+closed.
+
+**The CDP fast path can flatten shadow content in instead of missing it, but this is not
+guaranteed, and it fails silently when it does not.** Chromium's `DOMSnapshot.captureSnapshot` is
+capable of flattening an author-created shadow root's content directly under its host, open and
+closed both, with nothing on the record to say it came from behind a shadow boundary — verified
+against `test/fixtures/shadow-dom-test.html`, a small page with one simple open shadow root. But a
+real captured page in this repo's own fixtures falsifies "cdp always does this": `cdp` capturing
+`shoelace.style` (`test/fixtures/real-sites/shoelace-docs.json`) reports zero shadow roots, while
+`walk` capturing the *same page* (`test/fixtures/real-sites/shoelace-docs-walk.json`) reports four
+real open ones. CDP did not flatten those four in — it never saw them, which is a different and
+worse failure than "flattened them in with nothing to disclose," because it also has nothing to
+disclose about the ones it missed. **A `cdp` digest with no shadow-root segment on this line is not
+proof the page has no shadow DOM, or that whatever shadow DOM it has was captured.** It means
+either of those, and this line cannot currently tell you which. Confirm shadow DOM presence
+independently (devtools, or grep the app's source for `attachShadow`) when it matters, rather than
+trusting a `cdp` digest's silence on the subject.
+
+The line lists, in order, an iframe segment and a shadow-root segment, each present only when
+there is a nonzero count to report:
+
+- **iframes** — `<N> iframe<s>`, where `<N>` is every `<iframe>` element either path found
+  (neither path is blind to the element itself, only to what is inside it), with a parenthetical
+  naming how many of those were `<K> cross-origin` and/or `<K> origin unknown` when either is
+  greater than zero. An iframe with no parenthetical is same-origin.
+- **shadow roots** — `<N> shadow root<s>`, with `(<K> closed)` appended when some of them are
+  closed and the path can count that. On `walk`, `<N>` only ever counts *open* roots (see below);
+  on `cdp`, per the caveat above, `<N>` counts however many shadow roots CDP actually flattened in,
+  which is not a reliable count of every shadow root the page has.
+
+**Whether `walk` can even count *closed* shadow roots at all is not this line's business any
+more — it is a permanent property of the `walk` path, disclosed once on the digest's identity
+line** (`— walk (closed shadow roots undetectable)`; see [Identity](#header-lines) above) rather
+than repeated here on every single `walk` capture regardless of what the page contains. The reason
+it is undetectable at all: `Element.shadowRoot` is a live reference to an *open* root, so an open
+one is countable by its mere presence even though the walk never enters it, but a *closed* root
+returns `null` from that same property — indistinguishable from "no shadow root here at all" — and
+there is no other DOM API that tells the two apart once the page's own script has moved on.
+Reporting `0` closed roots would be a specific, false claim this whole package exists to refuse;
+disclosing the gap on the identity line is the honest alternative, once per capture rather than
+buried in a line that is otherwise about counted, page-specific numbers.
+
+**10. Edges — only with `{ edges: true }`.**
+
+**Illustrative** — plausible numbers on an invented page, not one real capture's clusters.
+
+```text
+# left edges: 0×6 · right edges: 300×5, 1024×1 · top edges: 0×2, 40×1, 80×1, 120×1, 160×1
+```
+
+Edge coordinates of every element the capture marked visible, grouped by adjacent-gap chaining
+with a 2px tolerance. The five largest clusters per axis, ordered by count, written
+`<coordinate>×<count>`, where the coordinate is the cluster's mean rounded to an integer.
+
+Nothing in this package adjudicates alignment. This is the raw distribution, offered so a reader
+can notice that four cards share a left edge and a fifth does not.
+
+## The element line
+
+**Grammar template** — placeholders; every element line in every live example elsewhere in this
+document is a real instance of this template.
+
+```text
+<indent><id> <tag><annotation> "<text>" @<x>,<y> <W>x<H> [<flow>] <gap> [<fact>]… [below fold]
+```
+
+Every token after `<W>x<H>` is optional. Order is fixed: flow, then gap, then facts, then below
+fold.
+
+| Token | Form | Emitted when |
+|---|---|---|
+| indent | two spaces per tree depth | depth > 0 |
+| id | `e13` | always |
+| tag | lowercase tag name, `div`, `h1`, `svg` | always |
+| annotation | `#save-btn` or `.heading` | see below |
+| text | `"Quarterly revenue review for t…"` | the element has an accessible name or own text |
+| position | `@71,164` | always |
+| size | `263x18` | always |
+| flow | `[row]` or `[grid]` | the element's `display` is flex-ish or grid-ish |
+| gap | `↓12` or `→-110` | there is a previous rendered sibling |
+| facts | `[overflow-x +147px; clip, ellipsis]` | the element carries that fact |
+| below fold | `[below fold]` | `y` > viewport height |
+
+### id
+
+`e` followed by the element's index in capture order: `e0`, `e1`, `e13`. Assigned by the
+collector, document order, starting at the `<body>` element.
+
+**These ids are stable within one capture and nowhere else.** They are not DOM ids, not
+selectors, and not hashes. Re-capturing the same unchanged page produces the same ids only by
+coincidence of the DOM being identical; inserting one element earlier in the document shifts
+every id after it. Never carry an `e13` from one capture into a claim about another, and never
+persist one as a test expectation. To refer to an element across two captures, match on the
+element's own identity — its test id, its accessible name, its role — or use a diff, which does
+the matching for you.
+
+The authored DOM id, when the element has one, is kept on the record as `domId`, and a test id
+(`data-testid`, `data-test-id`, `data-test`, `data-qa`) as `testId`. Those are the fields that
+travel.
+
+### annotation
+
+`#<testId>` when the element has a test id. Otherwise `.<role>` when it has a computed ARIA role.
+Otherwise nothing. Test id wins; both are never printed.
+
+The role is the *computed* role, not the `role` attribute: a bare `<button>` renders
+`.button`, an `<h1>` renders `.heading`. Elements with no implicit role, `<div>` and `<span>`
+among them, get no annotation.
+
+### text
+
+The element's accessible name if it has one, otherwise its own direct text content — direct child
+text nodes only, not descendants. Whitespace collapsed and trimmed by the collector, then cut to
+30 characters with a trailing `…` when longer. Quoted with plain `"`. Omitted when both are empty.
+
+The record itself keeps more than the line shows: 60 characters of own text, 80 of accessible
+name.
+
+The name is preferred over the text, so a `<nav aria-label="Actions">` renders `"Actions"` even
+though the nav's own text is empty.
+
+### position and size
+
+`@<x>,<y> <W>x<H>`, all four `Math.round`ed to integers, in CSS pixels, in **viewport
+coordinates at capture time**. `x` and `y` are the border-box top-left and may be negative. `W`
+and `H` are border-box dimensions.
+
+Both capture paths normalise to viewport coordinates, so a page captured while scrolled reports
+`y` relative to the current scroll position, not to the document.
+
+### flow
+
+`[row]` when the element's computed `display` contains `flex` and `flex-direction` is not
+`column`/`column-reverse`; `[column]` when `display` contains `flex` and `flex-direction` is
+`column` or `column-reverse`; `[grid]` when `display` contains `grid`. Absent otherwise.
+
+**Live example** (`synthetic=flow-column`) — a `flex-direction: column` container: the token prints
+`[column]`, and its children's gap is measured vertically, on the same axis the token names.
+
+```text
+e0 body @0,0 1024x500 [column]
+  e1 div @0,0 300x40
+  e2 div @0,60 300x40 ↓20
+```
+
+The token is what decides the *gap arrow* on that element's children (see [gap](#gap) below), and
+both come from the same underlying `flow` value, so they always agree: a `flex-direction: column`
+container's children are measured **vertically** (`↓`), the way you would expect from the name.
+
+### gap
+
+The signed distance from the previous rendered sibling's trailing edge, along the parent's flow
+axis, rounded to an integer.
+
+- `→N` when the parent's flow is `row`. Measured on x.
+- `↓N` when the parent's flow is `column`, `grid`, `none`, or the document root. Measured on y.
+
+Negative means the two boxes overlap along that axis: `→-110` in the [complete digest](#a-complete-digest)
+example above is `e5` overlapping its own previous sibling. The value is signed rather than
+clamped because an overlap is a fact worth seeing.
+<!-- checked-claim: gap-sign-overlap -->
+
+
+The first sibling in any group has no gap token.
+
+**The gap is direction-agnostic, including the sign and magnitude of a genuine overlap.** It does
+not assume the previous sibling is positioned before the current one in screen space — only that it
+comes first in DOM order. On an RTL flex row the DOM-order previous sibling is drawn to the
+*right*, and a naive "current minus previous" always reports which one is *later in the DOM*, not
+which one is *later on screen*: it cannot tell a real gap from an overlap in that layout (measured
+on `ar.wikipedia.org`: two header regions 16px apart rendered as a fabricated `→-1352`), and even
+inside a genuine overlap it can report the wrong *magnitude* by pairing the wrong pair of edges
+(measured on a synthetic case: two boxes overlapping by exactly 1.0px rendered as `→-474`). The
+renderer checks which box is actually first on the axis before deciding which edges to subtract —
+for a real gap, for a fabricated one, and for a genuine overlap alike — which needs no
+`direction`/`writing-mode` data and gives the identical number to the naive computation in every LTR
+case, where DOM order and screen order already agree. See `test/fixtures/rtl-flex-row-gap.html`
+(checked by `test/browser/rtl-gap.test.ts`) for the non-overlapping case, cross-checked against `q
+distance`.
+
+### below fold
+
+`[below fold]` when the node's `y` exceeds `meta.viewport.height`. Strictly greater, and based on
+`y` alone — a tall element that starts above the fold and ends below it is not marked.
+
+## Facts
+
+A fact is a bracketed group after the geometry. Facts are computed from the same records the
+lines are and carried on the element by id, so a fact can never land on the wrong line.
+
+Four kinds exist. They are emitted in this order when an element has more than one.
+
+### `overflow-x`
+
+**Illustrative** — four hand-picked cases side by side to show every token combination. The first
+and last are real (the heading in [A truncated heading](#a-truncated-heading) and the column in
+[A column that collapsed to zero width](#a-column-that-collapsed-to-zero-width), both below); the
+middle two show `scroll` and a plain `clip, wraps`, which neither fixture exercises.
+
+```text
+[overflow-x +147px; clip, ellipsis]
+[overflow-x +227px; clip, wraps]
+[overflow-x +90px; scroll, nowrap]
+[overflow-x +60px; visible, wraps]
+```
+
+`scrollWidth - clientWidth`, emitted whenever that exceeds 1px. Two consequence tokens follow the
+`;`.
+
+The first is exactly one of `clip` / `scroll` / `visible`, a partition of the computed
+`overflow-x` value:
+
+| Token | `overflow-x` is |
+|---|---|
+| `clip` | `hidden` or `clip` |
+| `scroll` | `auto`, `scroll` or `overlay` |
+| `visible` | anything else |
+
+The second describes what the text does:
+
+| Token | Condition |
+|---|---|
+| `ellipsis` | `text-overflow: ellipsis` **and** the box clips or scrolls |
+| `wraps` | not `ellipsis`, and `white-space` is not `nowrap` or `pre` |
+| `nowrap` | not `ellipsis`, and `white-space` is `nowrap` or `pre` |
+
+`ellipsis` suppresses `wraps` because `text-overflow` only takes effect once wrapping is already
+off. Printing both would restate one CSS rule twice.
+
+### `overflow-y`
+
+**Illustrative** — one line pulled out for its own subsection; it is real, and already checked
+in place on `e2` in the complete digest above.
+
+```text
+[overflow-y +105px; clip]
+```
+
+`scrollHeight - clientHeight`, emitted whenever that exceeds 1px. One consequence token,
+`clip` / `scroll` / `visible`, from `overflow-y`. There is no wrapping token on this axis.
+
+### `zero-box`
+
+**Illustrative** — the first line is real (checked in place in [A column that collapsed to zero
+width](#a-column-that-collapsed-to-zero-width) below); the second shows the descendant-count
+fallback, which no shipped fixture exercises.
+
+```text
+[0x1239 zero-box; content "Filters and saved views"]
+[0x480 zero-box; content 7 elements]
+```
+
+Emitted when an element is still in the layout — `display` is not `none` — and its width or its
+height is under 1px, **and** it has something inside it. A `0x0` element with no children is
+ordinary spacing and produces nothing.
+
+The content clause is what separates the two cases: a collapsed spacer is uninteresting, and a
+column that computed to `0x1239` around a page of content is the defect. The clause is the
+element's own text when it has any, otherwise text gathered breadth-first from its descendants
+and cut to 40 characters, otherwise a count of the descendant elements found.
+
+**On the same rare, whole-capture condition covered in [Header lines, item
+4](#header-lines) above, a `zero-box` fact on the affected element is not emitted as an
+element-line bracket at all — because under that condition there is no element-line body to put it
+on.** `look` declines to render a digest body under sparse capture and renders a capture-level
+refusal instead; the `zero-box` fact's content — the id, the tag, the content clause — is one line
+of that refusal (`# text present but not yet laid out: …`), not a bracket on `<body>`'s own line.
+See item 4 for the exact current form, the full argument, and the general rule this is one instance
+of: **dnumb never emits a form whose implicit claim the capture cannot support**, applied here at
+whole-body scope because four rounds of reader testing established that no wording placed next to
+a `[...]` bracket could out-argue what the bracket's own form claims — "a measured, adjudicable
+finding about this element" — on a capture where the element in question never really got measured
+into a page at all. An ordinary `zero-box` fact — outside this rare condition, a real measurement
+about the page rather than an artifact of when the capture ran — is completely unaffected and still
+prints exactly as described above.
+
+### `clipped`
+
+**Illustrative** — one line pulled out for its own subsection; it is real, and already checked
+in place on `e5` in the complete digest above.
+
+```text
+[clipped by e2 div; overflow:hidden, not scrollable; 103.8px below, 182x5 visible]
+```
+
+Emitted when an element extends past an ancestor whose `overflow` is not `visible` — the same
+measurement `ElementRecord.clip` carries (see [What is not in the digest](#what-is-not-in-the-digest)
+for the full-precision record fields), rendered as a fact so it lands on the digest line instead of
+requiring a reader to go back to the raw records for it. `by`/`byTag` name the clipping ancestor;
+`overflow` is its computed `overflow` value, `x/y` when the two axes differ; `scrollable` is
+whether a user could actually scroll that ancestor to reveal the hidden part — not the same
+question as whether it clips, since an `overflow:hidden` box has scroll extent and no
+reachability; the free-text clause names which sides are hidden and by how much, then how much of
+the box survives (`WxH visible`, or `nothing visible`).
+
+### Numbers inside facts
+
+Integers when exact, otherwise one decimal place: `+147px`, `+103.8px`. Geometry tokens on the
+line are always integers; fact numbers are not.
+
+### Reading a fact
+
+The same number means different things:
+
+**Illustrative** — hand-composed to contrast the three cases, with the plain-English gloss (not
+real output) aligned after each.
+
+```text
+[overflow-x +147px; clip, ellipsis]     147px of a heading is unreadable, and it ends in three dots
+[overflow-x +227px; clip, wraps]        the box clips, but the text wrapped; this is height, not truncation
+[overflow-x +90px;  scroll, wraps]      a scroll region working as designed
+```
+
+The number is identical in kind across all three. The difference is never in the number. Do not
+treat an `overflow-x` fact as a finding, and do not treat its absence as a clean bill of health —
+report the measurement and the consequence tokens together, and say which one you concluded from.
+
+## ⚠ Ellipsis inflates the reported overflow
+
+Chromium reserves layout space for the ellipsis glyph on an ellipsized element, and that reserved
+space is included in `scrollWidth`. So an `overflow-x` number on a line that also says `ellipsis`
+**includes the ellipsis**, and is larger than the width of the content that is actually hidden.
+
+Measured while building the archaeology fixture: **+10px at font-size 10, +17px at font-size 20**.
+Reproduced at +8px and +15px on a different font stack. The amount is the ellipsis glyph's advance
+width in the element's own font, so it scales with `font-size` and varies with `font-family`.
+Setting `text-overflow: clip` on the same element and re-measuring returns the uninflated number.
+
+Three consequences for a reader:
+
+1. **Do not subtract a constant.** There is no fixed correction. The inflation is font-dependent.
+2. **Treat the number as an upper bound on hidden content** when `ellipsis` is present, and as
+   exact when it is not.
+3. **Do not conclude "nothing is hidden" from a small number.** A `+12px` overflow at font-size 16
+   may be almost entirely the glyph.
+
+`test/fixtures/flex-min-width-ellipsis.html` pins its content width with a block-level child
+specifically so its numbers do not move with the installed font. A fixture whose expected value
+depends on the CI machine's font is a fixture that goes red for a reason nobody enjoys diagnosing.
+
+## Color
+
+**Not a digest-body fact.** Everything else in [Facts](#facts) — `overflow-x`, `overflow-y`,
+`zero-box`, `clipped` — prints inline, bracketed, on the element line it measures. Color is a fifth
+kind of fact, computed the same way (a measurement plus the CSS that decides what it means) but
+never printed there: see [Where color lives](#where-color-lives) below for why. It reaches a
+reader through the `# colors:` header line (this section), `q color`, and `q describe`.
+
+**The gate: a visible element with its own text.** No text, no ink-on-backdrop question to answer,
+no color fact. This is the same gate `overflow-x`/`overflow-y`/`zero-box` use, applied to a
+different question.
+
+### Why the compositing walk exists
+
+Reading an element's own `background-color` sounds like it should answer "what is this text on."
+On real pages it almost never does: measured across 10,834 resolved real text elements, only
+**2.4%** have an opaque *own* `background-color`. For the other **97.6%**, `background-color` is
+transparent or translucent — `getComputedStyle` returns exactly `rgba(0, 0, 0, 0)` for most of
+them, which is not a slightly-wrong color, it is no color at all. A tool that reported raw
+`background-color` would be `unmeasured` (or worse, silently wrong) for nearly all real text on the
+web. dnumb instead walks up from the element, compositing every ancestor's `background-color`
+layer by alpha until it reaches an opaque one (the canvas is the final opaque layer), and reports
+that composited result as the *effective backdrop* — the color actually behind the text, not the
+element's own unhelpful claim about itself. The element's own `background-color` is still on the
+record as a counter-fact (it is what invalidates a backdrop when it is itself a gradient or image),
+just never trusted as the answer on its own.
+
+### The per-element grammar
+
+Seen via `q describe <id>` and `q color --all`, never on a digest body line.
+
+**Grammar template** — placeholders; the worked examples throughout this section are real
+instances of it.
+
+```text
+color <fg> on <bg>; ratio <r>; <size>px/<weight>[; opacity ×<o>][; shadow <color>][; stroke <w>px <color>]
+```
+
+`<fg>` is the *effective* ink — the computed `color`, composited at effective opacity over the
+backdrop when opacity is under 1 (with `opacity ×<o>` printed alongside so the raw value is
+recoverable). Colors print as lowercase hex, or verbatim when the color space could not be
+converted (see `color-space` below). `ratio` is the WCAG 2.x relative-luminance contrast ratio,
+two decimals — the name of a formula, not a threshold; see [Never a
+verdict](#never-a-verdict-just-the-number) below.
+
+**Live example** (`fixture=test/fixtures/color-alpha-chain.html url=file://.../color-alpha-chain.html`)
+— regenerated fresh by `test/browser/doc-examples.test.ts` every run.
+
+```text
+# dnumb digest v2 — file://.../color-alpha-chain.html — 1024x768 — cdp
+# 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: 1024x226 (9 records → 7 layout nodes, 0 dropped, 2 wrappers folded)
+# colors: 3 fg/bg pairs across 3 text elements; ratio 3.58–21.00; lowest e7 #000000 on #0d743d via e4 (α×2) 16px/400
+e0 body @0,0 1024x226
+  e2 div @20,20 984x64
+    e3 span "Alpha chain text" @40,40 160x24
+  e4 div @0,104 1024x84 ↓20
+    e6 div @20,124 984x44
+      e7 span "Nested alpha text" @30,134 170x24
+  e8 p.paragraph "Plain text, no background set …" @0,204 1024x22 ↓16
+```
+
+`e7`'s own color fact (via `q describe e7` or `q color --all`, not shown on the digest line above)
+is `color #000000 on #0d743d via e4 (α×2); ratio 3.58; 16px/400` — two translucent layers
+composited on the way to `e4`'s opaque background, disclosed as `(α×2)`.
+
+### The `<bg>` forms
+
+| Form | Meaning |
+|---|---|
+| `<hex> via <id>` | Composited backdrop — `<id>` is the ancestor whose opaque background closed the composite, the counter-fact a reader can go inspect. `(α×N)` appended when `N` translucent layers were composited on the way. |
+| `<hex> via canvas` | Composited backdrop that resolved all the way to the browser's own default canvas fill — see [`via canvas`](#via-canvas) below. |
+| `<hex> self` | The element's own background is opaque; nothing to walk. |
+| `gradient(<hex>→<hex>) <id>` | A gradient background on `<id>` sits behind the text. First and last stops are shown so a reader can judge whether both ends sit the same side of the ink's luminance without a precise ratio. `ratio` becomes `unmeasured`. |
+| `image <id> (<W>x<H> of <W>x<H>)` | A `url()` background on `<id>` sits behind the text. `ratio unmeasured`. See [The image footprint](#the-image-footprint) for what the two sizes mean and why both are there. |
+| `unknown (under <id>)` / `unknown (behind <id>)` | A non-ancestor element paints over the text (`under`) or behind it but above the real backdrop (`behind`) — a positioned overlay, an open modal's scrim, a cookie banner. `ratio unmeasured`. |
+| `unknown (canvas)` | The walk ran off the top of the page with no ancestor background *and* no resolvable canvas fill — see [`via canvas`](#via-canvas) below. `ratio unmeasured (canvas)`. |
+| `unknown (not captured <id>)` | This specific capture never measured `<id>`'s `background-image` at all — see [`unknown (not captured <id>)`](#unknown-not-captured-id) below. `ratio unmeasured (not-captured)`. |
+
+Every form but the first two ends in `ratio unmeasured` — see `ratioLabel`'s exceptions,
+`color-space`, `canvas`, and `not-captured`, below.
+
+### `via canvas`
+
+The compositing walk starts at the text element and climbs its ancestor chain looking for an
+opaque `background-color` — but the capture itself starts at `<body>`, and a page's real
+background can live above that: on `<html>`, or nowhere at all, resolved only by the browser's own
+default canvas fill and the page's `color-scheme`. Neither is an element the ancestor walk can
+name, so before this fix the walk simply ran off the top of `<body>` with nothing left to check and
+had no honest way to describe what came next.
+
+**Live example** (line `# colors: 1 fg/bg pair …` in [A column that collapsed to zero
+width](#a-column-that-collapsed-to-zero-width) below) — `e6`'s paragraph sits on no declared
+background anywhere in its ancestor chain, all the way up through `body`; the digest names the
+backdrop `via canvas`, not `via e0` (`body`'s own id) or any other element that never actually
+declared it.
+
+Two Chromium-verified facts make this resolvable rather than another `unmeasured`: an explicit
+opaque `<html>` background-color wins outright regardless of `color-scheme`, and `color-scheme:
+dark` with no background set anywhere resolves to Chromium's real default fill, `rgb(18, 18, 18)`
+— not white. Guessing white for every unresolved page used to fabricate a real number: a dark page
+with light text and no declared background anywhere used to resolve `via <body-id>` on an assumed
+white canvas and report a contrast ratio *worse* than the truth, or — on a page whose `color-scheme:
+dark` made the ink itself dark-on-dark by design — a fabricated `ratio 1.00` for text that was
+never unreadable at all, because it was never actually on white. `unknown (canvas)` is the honest
+fallback for the residual case: an unconvertible `<html>` background-color, or `color-scheme:
+light dark`, which genuinely depends on the reader's own OS preference and cannot be resolved from
+the page alone.
+
+### `unknown (not captured <id>)`
+
+`ElementRecord.backgroundImage` is `null`, not `'none'`, when a particular capture never measured
+that field at all — a bundle written before color capture existed. The compositor refuses to
+continue past an element whose `background-image` it does not know: that field is what tells the
+walk whether a gradient or an image sits behind the text, so an unknown value cannot honestly be
+treated as "none of those." This is the same rule the `# not measured:` header line's closed
+shadow roots already follow — `Element.shadowRoot` is `null` for both "no shadow root" and "closed
+shadow root," and rather than guess `0`, the digest reports the honest gap — applied here to a
+second field that can be silently missing for a different reason (an old bundle) instead of a
+different DOM API limitation. Both are one rule, not two coincidences: **a value this package never
+measured is never reported as a measured zero.**
+
+**Live example** (`synthetic=color-not-captured`) — one element with `backgroundImage: null` set
+directly; `el()`'s own default is `'none'`, a real measured value, so this has to be set
+explicitly to reach the case.
+
+```text
+e1 color #000000 on unknown (not captured e1); ratio unmeasured (not-captured); 16px/400
+```
+
+**Live example** (`fixture=test/fixtures/color-modal-scrim.html url=file://.../color-modal-scrim.html`)
+— regenerated fresh by `test/browser/doc-examples.test.ts` every run. `e2`'s own sibling `e3` covers
+it; `e6` sits behind `e5`, which paints above the ancestor chain's own backdrop.
+
+```text
+# dnumb digest v2 — file://.../color-modal-scrim.html — 1024x768 — cdp
+# 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: 1024x240 (7 records → 7 layout nodes, 0 dropped, 0 wrappers folded)
+# colors: 2 fg/bg pairs across 2 text elements; 2 unmeasured (1 under, 1 behind)
+e0 body @0,0 1024x240
+  e1 div @0,0 300x100
+    e2 span "Text under a scrim" @0,0 170x28
+    e3 div @0,0 300x100 ↓-28
+  e4 div @0,140 300x100 ↓40
+    e5 div @0,140 300x100
+    e6 span "Text over a sibling's backgrou…" @0,140 280x24 ↓-100
+```
+
+`e2`'s own color fact is `color #000000 on unknown (under e3); ratio unmeasured; 16px/400` — this
+is the most actionable `unmeasured` reason there is. The `<id>` names the actual covering element,
+annotation and all (`e3` here is a plain `div`; on a real page it reads as something like `under
+iframe#consent-frame` or `under div.modal-scrim`), which tells an agent *what* is sitting over the
+text without a further tool call to find out.
+
+### The image footprint
+
+`image <id> (<W>x<H> of <W>x<H>)` carries two sizes: the first is the image-bearing element `<id>`'s
+own rendered box; the second is the text element's own box. This exists because the token used to
+be indistinguishable in a genuinely useful way: Wikipedia's sortable-table column headers flag
+`unmeasured (image ...)` because of a 12×12px decorative sort-arrow icon in one corner of the cell,
+and without a size, that token read identically to a full-bleed 1440×600 hero photo sitting behind
+a page heading. An agent reading either line alone cannot tell "irrelevant corner decoration, the
+ratio is almost certainly fine" from "genuinely unmeasurable, do not trust anything here" without
+spending a screenshot round-trip — exactly the cost this whole feature exists to avoid. The two
+sizes are a size *proxy*, not the image's true painted footprint: `background-size` and
+`background-position` can still make a small box crop-and-fill a dominant image, or a large box
+tile a small icon, so `image e_th (12x12 of 180x40)` narrows the question honestly rather than
+closing it.
+
+**Live example** (`fixture=test/fixtures/color-gradient-hero.html url=file://.../color-gradient-hero.html`)
+— regenerated fresh by `test/browser/doc-examples.test.ts` every run.
+
+```text
+# dnumb digest v2 — file://.../color-gradient-hero.html — 1024x768 — cdp
+# 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: 1024x160 (5 records → 5 layout nodes, 0 dropped, 0 wrappers folded)
+# colors: 2 fg/bg pairs across 2 text elements; 2 unmeasured (1 gradient, 1 image)
+e0 body @0,0 1024x160
+  e1 div @0,0 1024x76
+    e2 span "Text over a gradient" @20,20 320x36
+  e3 div @0,96 1024x64 ↓20
+    e4 span "Text over an image" @20,116 190x24
+```
+
+`e2`'s color fact is `color #ffffff on gradient(#4285f4→#0d47a2) e1; ratio unmeasured; 24px/700`;
+`e4`'s is `color #ffffff on image e3 (1024x64 of 190x24); ratio unmeasured; 16px/400` — the
+image-bearing box (`e3`, 1024×64) is far larger than the text's own box (190×24), which is itself
+already a signal about how much of the surrounding context the image plausibly dominates.
+
+### Modern color syntax
+
+Computed colors are not always `rgb()`. `oklch()`, `oklab()`, `lab()`, `lch()`, `color(srgb …)` and
+`color(display-p3 …)` all survive verbatim to `getComputedStyle` and to CDP's own string table —
+Tailwind v4 ships its default palette in `oklch`, and real component-library stylesheets'
+*computed* serialization skews toward `oklab`/`lab` even more than `oklch`. dnumb converts all of
+these deterministically to sRGB hex (display-p3 values outside the sRGB gamut are clamped, and the
+line still reports the number, not the color); anything it cannot convert prints the color
+verbatim with `ratio unmeasured (color-space)` rather than guessing.
+
+**Live example** (`fixture=test/fixtures/color-oklch-tailwind.html url=file://.../color-oklch-tailwind.html`)
+— regenerated fresh by `test/browser/doc-examples.test.ts` every run. Four pairs convert cleanly;
+`e10`'s `color(rec2020 1 0 0)` does not.
+
+```text
+# dnumb digest v2 — file://.../color-oklch-tailwind.html — 1024x768 — cdp
+# 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: 1024x400 (11 records → 11 layout nodes, 0 dropped, 0 wrappers folded)
+# colors: 5 fg/bg pairs across 5 text elements; ratio 2.52–10.06; lowest e4 #f4f9ff on #4ba3f7 via e3 16px/400; 1 unmeasured (1 color-space)
+e0 body @0,0 1024x400
+  e1 div @0,0 1024x64
+    e2 span "Real Tailwind-v4-shaped comput…" @20,20 400x24
+  [fold: ×4 more like e1 — e3 @0,84 ↓20, e5 @0,168 ↓20, e7 @0,252 ↓20, e9 @0,336 ↓20]
+```
+
+`e10`'s own color fact is `color color(rec2020 1 0 0) on #202124 via e9; ratio unmeasured
+(color-space); 16px/400` — the ink prints verbatim because it could not be converted; the backdrop,
+which did convert, still prints as hex.
+
+### The `# colors:` header line
+
+**Grammar template** — placeholders; the live examples above are real instances, and the two below
+show the `ratio`/`lowest` clause and the `unmeasured` breakdown each independently omitted.
+
+```text
+# colors: <P> fg/bg pairs across <T> text elements[; ratio <min>–<max>; lowest <id> <fg> on <bg> <size>px/<weight>][; <U> unmeasured (<breakdown>)]
+```
+
+Emitted whenever at least one element carries a color fact, omitted otherwise — placed after
+`# facts:` and before `# TRUNCATED:` / `# not measured:`, because it is a measurement *of this
+page*, not a permanent property of the capture path (that distinction is what puts `— cdp`/`—
+walk` on the identity line instead). `<P>` is the count of distinct (ink, backdrop) pairs — the
+same one-row-per-pair discipline `q color` uses, not one row per element — and `<T>` is the count
+of gated text elements.
+
+**The `ratio`/`lowest` clause is present only when at least one fact resolved to a real number.**
+A page that is entirely gradients, images and overlays has nothing to report there, and omitting
+the clause is more honest than printing a range over zero measured elements — the gradient-hero
+example above has none. Naming the `lowest` reports the minimum of a measured distribution with
+its own counter-facts inline, following the precedent the page-dominance clause already set (`;
+<id> extends the page height by <N>px beyond the next element`, [Page](#header-lines) above): the
+page's lowest-contrast text may be a disabled placeholder, and the line does not say otherwise.
+
+**The `unmeasured` tally is the honesty clause.** It names how much of the page's text the
+distribution above does not cover, broken down by reason, most-common-first:
+`<count> gradient`, `<count> image`, `<count> under`, `<count> behind`, `<count> color-space` —
+whichever of those are nonzero, in that order. A reason with a zero count is omitted, not printed
+as `0 gradient`.
+
+### The capture-path asymmetry
+
+Overlap detection — the `under`/`behind` reasons — is the one place the two capture paths differ
+mechanically, and it is not a footnote. The portable walk samples one point, the text box's
+*centre*, via `document.elementsFromPoint`; the CDP path checks the *whole rect* against paint
+order and intersection, Node-side. Both read the same fields into the same grammar, but they can
+disagree on partially-overlapped text: a cookie banner or sticky nav covering the top third of a
+heading but not its centre reads as no overlay on `walk` while `cdp`'s whole-rect check would catch
+it. Measured on a real soak: a raw overlay rate of 1.9% rose to roughly **8.5%** — about 4× —
+among candidates that otherwise got a clean, confident verdict, which is the direction and rough
+scale of undercount a centre-point sample on `walk` should be expected to carry. A reader comparing
+a `walk` capture against a `cdp` capture of the same page should expect *more* `unmeasured
+(under/behind ...)` reasons on `cdp`, not fewer, independent of anything about the page changing —
+the same shape of disagreement `# not measured:`'s `cdp`-vs-`walk` shadow DOM gap already has (see
+[Not measured](#header-lines) above): two capture paths that can silently disagree about what a
+page contains, disclosed rather than papered over.
+
+### Never a verdict, just the number
+
+Same discipline as every other fact in this format, stated in full because color is the one most
+likely to be misread as a check:
+
+1. dnumb prints measurements, and deterministic functions of its own measurements — a contrast
+   ratio is `f(two measured colors)`, the same standing as `scrollWidth − clientWidth`.
+2. It never compares a measurement to a constant that was not measured from the page. `4.5`,
+   `3:1`, "large text" are not on any line. No token ever says `pass`, `fail`, `AA`, `AAA`, `low`,
+   or `poor`. "WCAG" appears only as the name of the ratio formula.
+<!-- checked-claim: color-never-verdicts -->
+3. No emission, fold, or ordering decision depends on such a comparison. `q color`'s rows sort by
+   ratio ascending because that is a useful reading order, not because anything below a line is
+   hidden.
+4. A number this package cannot establish the truth of is never printed. `unmeasured`, with a
+   named reason, instead.
+
+The agent reading the ratio adjudicates whether it matters, exactly as with every overflow and
+clip fact in this package. dnumb's job ends at the number being true — composited, overlay-checked,
+color-space-converted — with the size, weight, opacity and shadow that decide what it means printed
+right beside it.
+
+### Where color lives
+
+Not on a digest body line, by design, for the same reason a color fact is measurement-heavy:
+folding is deliberately signature-based, and a color fact in the fold signature would make a
+zebra-striped table — alternating row backgrounds, the most ordinary pattern on the web — refuse to
+fold at all. `q describe <id>` prints the [per-element grammar](#the-per-element-grammar) for one
+element; `q color` prints one row per (ink, backdrop) pair across the whole capture, sorted by
+ratio ascending with `unmeasured` last; `q color --all` prints one line per gated element under the
+usual `--limit` convention. `# colors:` (above) is the only place color reaches the digest itself.
+
+
+## The fold line
+
+**Grammar template** — placeholders; the live example right below is a real instance of it.
+
+```text
+[fold: ×<N>[/<period>] more like <id>[ (<variance>)] — <id> @<x>,<y><gap>, <id> @<x>,<y><gap>, …]
+```
+
+When a run of siblings repeats with some period from one to six (three consecutive identical
+siblings is a period-1 run of length three; a `dt`/`dd` list is a period-2 run), the first whole
+period is printed in full — with each member's own children — and the rest collapse into one fold
+line at the same indentation, immediately after.
+
+**Live example** (`synthetic=fold-basic`) — five identical `<div>Row</div>` siblings, period 1.
+Regenerated and diffed against this block by `test/unit/doc-examples.test.ts` on every run — this
+is the exact scenario the one hand-pinned "spec drift guard" test used to check on its own; this
+mechanism now covers it and every other example on this page the same way.
+
+```text
+  r0 div "Row" @0,0 300x30
+  [fold: ×4 more like r0 — r1 @0,40 ↓10, r2 @0,80 ↓10, r3 @0,120 ↓10, r4 @0,160 ↓10]
+```
+
+`×4` is the count of *additional* siblings, not the run length: five identical rows produce `×4`.
+Every folded sibling keeps its id and its position, so nothing a fold covers becomes
+unaddressable. Gaps inside the list are measured against the preceding entry in the run.
+
+**A folded sibling's own descendants do not print anywhere in the fold line — the fold line names
+siblings, never their children.** For a fold member covered only by `[fold: ...]`'s own entry
+(id, position, gap), nothing about what it contains reaches the digest text. This is not a gap
+in disguise: an element with a fact *anywhere in its own descendants* is excluded from folding
+entirely, not merely grouped by a coarser match (see the signature list below) — it always gets
+its own full line, with its own children printed beneath it, so a fact never goes missing by way
+of a sibling's fold swallowing it. What a fold can still hide is a folded sibling's descendant
+*structure and content* when nothing under it carries a fact — the fold line's `id @x,y<gap>` for
+that sibling is everything the digest says about it; `--focus <id>` on that specific id renders its
+subtree in full when you need to see it (see "The `--focus` hint" below).
+
+The signature that decides sameness is tag, computed role, flow, child count, a coarse
+order-of-magnitude size bucket for width and height, the element's own fact *signatures* — kind
+plus consequence tokens, with the numeric magnitude stripped — and whether a fact exists *anywhere
+in its descendants* at all. All of this is deliberate, and narrower than it looks:
+
+- **The size bucket is coarse on purpose.** Exact-dimension matching was tried and meant nothing
+  on a real page ever folded (thirty story rows with differently-long titles are thirty different
+  heights); no size check at all was also tried and meant a page's own skeleton — a `header`, `nav`,
+  `main` and `footer` sharing a tag, with wildly different heights — folded into itself, its
+  content vanishing with it. The bucket groups sizes within roughly one order of magnitude, which
+  keeps ordinary content variation folding while still splitting a 40px row from a 3000px one.
+- **Own facts are part of it by kind and consequence, not by exact text.** An element that overflows
+  is not interchangeable with one that does not, however alike their boxes are — but the difference
+  that matters is `clip` vs `scroll`, `ellipsis` vs `wraps`, never the pixel count beside it. Two
+  rows overflowing by 12px and 14px, both `clip, ellipsis`, are the same kind of thing and fold; a
+  row overflowing by 900px and `clip, ellipsis` does not fold with one overflowing by 2px and
+  `scroll, wraps`, however close their boxes are otherwise. This grouping is safe precisely because
+  the representative's own line, printed right above the fold, already shows a fact of the same
+  kind — nothing is lost by treating "12px" and "14px" as interchangeable there.
+- **A fact anywhere in an element's descendants is not grouped at all — it is excluded from folding,
+  full stop.** No representative stands in for a grandchild's measurement the way it stands in for
+  an own fact, because the fold line names siblings, never grandchildren. So instead of a coarser
+  match, any node with a fact below it gets a signature unique to itself: it can never match another
+  position, and must always 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 (see [The line budget](#the-line-budget)), never silently absorbed as an
+  unlabelled fold member. Measured on real captures before this was fixed: `shoelace-docs` had 115
+  of 301 fact-bearing elements, and `grafana-play` 97 of 166, missing from the rendered text
+  entirely, with no `[folded:]` line to mark the gap — not folded-and-disclosed, just gone. On the
+  same eight real fixtures now: zero.
+<!-- checked-claim: fold-never-drops-a-fact -->
+
+**Live example** (`synthetic=fold-outlier-fact`) — four otherwise-identical rows; the fourth carries
+an `overflow-x` fact *of its own* the other three do not, so it prints its own line instead of
+joining their fold, gap token and all.
+
+```text
+  r0 div "Row" @0,0 300x30
+  [fold: ×2 more like r0 — r1 @0,40 ↓10, r2 @0,80 ↓10]
+  r3 div "Row" @0,120 300x30 ↓10 [overflow-x +900px; clip, ellipsis]
+```
+
+**Live example** (`synthetic=fold-descendant-fact`) — four otherwise-identical rows again, but this
+time the fourth carries no fact of its own; its *child* does. `r3` still breaks out of the fold, and
+its child `c3` — with the fact — prints beneath it, exactly as it would if `r3` had never been a
+fold candidate at all.
+
+```text
+  r0 div "Row" @0,0 300x30
+    c0 span "Label" @4,4 100x20
+  [fold: ×2 more like r0 — r1 @0,40 ↓10, r2 @0,80 ↓10]
+  r3 div "Row" @0,120 300x30 ↓10
+    c3 span "Label" @4,124 100x20 [overflow-x +400px; clip, ellipsis]
+```
+
+### Period
+
+A run does not have to be *consecutively* identical to fold. Real lists are periodic, not
+uniform — Hacker News alternates story row, subtext row, spacer row; a definition list alternates
+`dt`, `dd`. The renderer searches periods from one up to six and folds whichever period covers the
+most siblings; when the period is greater than one, the count is followed by `/<period>`:
+
+**Live example** (`synthetic=fold-period-dtdd`) — a five-entry `dt`/`dd` definition list, period 2.
+
+```text
+  x0 dt "Name" @0,0 300x20
+  x1 dd "Ada Lovelace" @0,20 300x20 ↓0
+  [fold: ×8/2 more like x0 — x2 @0,40 ↓0, x3 @0,60 ↓0, x4 @0,80 ↓0, x5 @0,100 ↓0, x6 @0,120 ↓0, x7 @0,140 ↓0, x8 @0,160 ↓0, x9 @0,180 ↓0]
+```
+
+The first whole period (one `dt` and one `dd` here) prints in full; the fold covers everything
+after it. `period` is omitted from the line (and defaults to `1` when parsed) for a plain
+consecutive run.
+
+### Variance
+
+Dimensions are not part of the signature beyond the coarse bucket above, so members of a fold can
+still differ in size — a row three times taller than its neighbours would otherwise hide silently
+inside a fold, which is the exact failure this format exists to prevent. When the folded members
+are not all the same size, a `(...)` token right after the representative's id reports the range —
+`(w-range <min>-<max> across <count>)`, `(h-range <min>-<max> across <count>)`, or both,
+comma-joined, when both axes vary. `<count>` is the number of siblings the range was pooled from,
+including the fully-printed representative.
+
+**The `-range`/`across <count>` wording is deliberate, not decoration.** A blind read on a *clean*
+page found a rater treat the older, terser `(h 32-48)` form as if it described one specific
+element, back-computed an overflow from it, and opened with "Likely issue" — a fabricated
+`overflow-x` fact the renderer never emitted. The current wording makes that misreading require
+overriding two explicit words (that this is a *range*, pooled *across* several siblings) rather
+than simply failing to notice an absent one.
+
+**Live example** (`synthetic=fold-variance`) — eight rows, one three times taller than the other
+seven.
+
+```text
+  r0 div "Row" @0,0 300x30
+  [fold: ×7 more like r0 (h-range 30-90 across 8) — r1 @0,40 ↓10, r2 @0,80 ↓10, r3 @0,120 ↓10, r4 @0,160 ↓-50, r5 @0,200 ↓10, r6 @0,240 ↓10, r7 @0,280 ↓10]
+```
+
+Sub-pixel differences (a 0.2px rounding wobble reported as `100-101`) are not a real spread and are
+suppressed — the comparison uses the same 1px epsilon `facts.ts` uses for overflow, and rounds only
+for display.
+
+For a periodic fold, the spread is computed *per phase* rather than pooled across all of them: a
+story/subtext/spacer list's own inherent height variation is not a defect, and pooling it would
+make a real outlier in one phase indistinguishable from that healthy variation. Phases with no
+real spread say nothing; a phase that has one gets its own `phase<k>` token in front of its own
+`-range`/`across` clause:
+
+**Live example** (`synthetic=fold-phase`) — a five-period story/subtext/spacer list (heights 30/12/2,
+its own healthy per-phase variation) with one real outlier: the very first `row` is 90px instead of
+30px. The pooled reading (spanning all three phases' own normal spread) does not appear; only the
+phase that actually has an outlier gets a token.
+
+```text
+  n0 div.row @0,0 1024x90
+  n1 div.subtext @0,90 1024x12 ↓0
+  n2 div.spacer @0,102 1024x2 ↓0
+  [fold: ×12/3 more like n0 (phase0 h-range 30-90 across 5) — n3 @0,104 ↓0, n4 @0,134 ↓0, n5 @0,146 ↓0, n6 @0,148 ↓0, n7 @0,178 ↓0, n8 @0,190 ↓0, n9 @0,192 ↓0, n10 @0,222 ↓0, n11 @0,234 ↓0, n12 @0,236 ↓0, n13 @0,266 ↓0, n14 @0,278 ↓0]
+```
+
+At most 40 siblings are named. Past that the line says what it dropped:
+
+**Live example** (`synthetic=fold-cap-40 elide=true`) — 200 identical rows, no line-budget pressure
+at all; the 40-name cap on one fold line is independent of `options.budgetLines`. `⋯` below is this
+document's own elision mark for a block too long to paste in full — deliberately not `…`, which the
+renderer itself prints (see the real `…+159 not listed` at the end of this same line) — and the
+check this caption asks for only verifies the real text before and after it, not what `⋯` stands
+for.
+
+```text
+  r0 div "Row" @0,0 300x30
+  [fold: ×199 more like r0 — r1 @0,40 ↓10, r2 @0,80 ↓10, r3 @0,120 ↓10, r4 @0,160 ↓10, r5 @0,200 ↓10, r6 @0,240 ↓10, r7 @0,280 ↓10, r8 @0,320 ↓10, r9 @0,360 ↓10, r10 @0,400 ↓10, ⋯, r40 @0,1600 ↓10, …+159 not listed (--focus e0)]
+```
+
+### The `--focus` hint
+
+`--focus <id>` (`renderDigest(snapshot, meta, { focus: 'r0' })` in the library, `--focus <id>` on
+the CLI) accepts *any* element id or tag name present in the capture and renders that element's own
+subtree in full. It works identically whether `<id>` is the fold's representative, one of the
+up-to-40 entries named on the fold line, or an id past the 40-name cap that you already know from
+elsewhere (`q find`, devtools, an earlier capture of the same element).
+
+**The `…+N not listed` hint names the fold's *parent*, not the representative — `--focus e0` above,
+not `--focus r0`.** The representative (`r0`) is already fully expanded on the line right above the
+fold; focusing it would just re-print what is already on screen. The `…+159 not listed` entries are
+`r0`'s *siblings*, and the only id whose own subtree is guaranteed to contain every one of them is
+the container they all share — here, `e0`, the `body`. Focusing a specific sibling directly (`--focus
+r41`, once you have its id from another source) also works and is more direct when you already know
+which one you want; the parent hint is what to reach for when you don't.
+
+**Folding, aggressive shape-widening, and subtree collapse are all disabled entirely once
+`--focus` has scoped the output — a focused render always converges.** Re-rendering a fold's parent
+under `--focus` would otherwise just reapply the same period detection and the same 40-name cap to
+its children, reproducing an identical `…+N not listed` line one level in and making the hint's
+promise false again, one hop later; collapse used to have the identical problem one stage later —
+it picked its own candidates *inside* the focused subtree and hid them behind a fresh `[folded:
+…]` line, so the collapsed line's own `(--focus <id>)` escape hatch led nowhere. Measured on a real
+capture before this was fixed: focusing `ar.wikipedia.org`'s own `e143`→`e445`→`e1691`→`e1702`
+chain peeled exactly one structural wrapper per hop while the collapsed fraction stayed
+97–99.9% the whole way — every hop's ids and arithmetic were correct, but stage 3 was reapplying
+the same budget to a subtree that was, on that page, itself bigger than the budget, so it just
+moved the frontier one level down and hid the rest again. Now, `--focus e143` on the same fixture
+returns the real article prose in full, zero `[folded: …]` lines anywhere in it.
+
+`--focus` exists so a reader can ask for full detail on one thing; folding and collapsing are both
+compression devices for output the reader is not zoomed into, so once they are, neither has
+anything left to justify. **A focused render is deliberately unbounded by either budget option —
+`options.budgetChars` and `options.budgetLines` alike** — the caller asked to see everything under
+that id, and re-hiding parts of it would defeat the request rather than serve it. This can make a
+focused render large when the focused id 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, and since nothing under a focused render can be
+further collapsed, one `--focus <id>` call now always reaches every fact in that subtree with no
+further hint to chase. This is also the shape a reader should expect from *manually* naming a
+coarse id rather than following the cue's own hint: `--focus e143` on `ar.wikipedia.org` — a whole
+article's own root — returns 192,868 characters fully expanded, not a mistake or a regression, but
+the literal cost of "show me everything under here" applied to something that is itself most of the
+page. Following the cue's own hint id, by contrast, converges cheaply because the cue always names
+the collapse actually blocking the render, not an arbitrary ancestor — see [the two-call
+idiom](#the-line-budget) below.
+
+`--focus` also changes the `# page:` line: see [item 3, "Page"](#header-lines) under [Header
+lines](#header-lines) above.
+
+## The collapsed line
+
+**Grammar template** — placeholders; the live examples below are real instances.
+
+```text
+[folded: <N> nodes, bbox @<x>,<y> <W>x<H> (--focus <id>)]
+[folded: <N> nodes, <K> facts, bbox @<x>,<y> <W>x<H> (--focus <id>)]
+```
+
+Emitted in place of a container's entire child list when the digest is over budget and folding was
+not enough. `<N>` counts every descendant node, not just direct children. The bbox is the union of
+their boxes.
+
+**Live example** (`synthetic=collapsed-line`) — ten children sharing no signature at any setting
+(ten different tags: `p`, `span`, `a`, `h2`, `ul`, `button`, `label`, `em`, `strong`, `code`), so
+folding cannot help under a tight budget and `e1`'s child list collapses instead.
+
+```text
+e0 body @0,0 1024x800
+  e1 div @0,0 300x400
+    [folded: 10 nodes, bbox @0,0 300x390 (--focus e1)]
+```
+
+The container's own line (`e1`) is still printed. The subtree is summarised, never silently
+dropped — a cap the reader cannot see is indistinguishable from complete output.
+
+**`(--focus <id>)` names the collapsed container itself — the same id printed one line above, on
+the container's own line — so a reader always has a printed route from "this is summarised" to
+"here is how to see inside it," not just an id they could in principle have copied down themselves.
+This is the render's heaviest disclosure: a whole subtree, facts among them, reduced to one line,
+and a reader told how many facts are in there with no printed way to reach them is being taunted,
+not informed. `--focus e1` on the example above re-renders `e1`'s subtree in full.
+
+**`, <K> facts` names how many of the collapsed subtree's elements carry a fact — omitted when
+zero, present whenever at least one of them does.** A collapsed line used to disclose a node count
+and a bounding box but nothing about what was inside. `<K>` is counted from the same per-element
+fact map the digest body reads facts from, so it can never disagree with what an uncollapsed render
+of the same subtree would show. It counts the same digest-body facts `# facts: N` counts
+(`overflow-x`/`overflow-y`/`zero-box`/`clipped`) — color facts are never in this count, because they
+are never digest-body facts at all (see [Color](#color) below).
+
+**Live example** (`synthetic=collapsed-line-with-facts`) — the same ten children, but three of them
+now carry an `overflow-x` fact each.
+
+```text
+e0 body @0,0 1024x800
+  e1 div @0,0 300x400
+    [folded: 10 nodes, 3 facts, bbox @0,0 300x390 (--focus e1)]
+```
+
+`<K>` says only *how many* facts are hidden, not what they are — a reader who needs the actual
+measurements follows `(--focus <id>)`, captures narrower, or loosens `--budget`, rather than
+reasoning about what a collapsed line does not show.
+
+**When a collapse eats most of the page, the header says so too — see [the collapse
+cue](#header-lines) below.** The collapsed line's own `(--focus <id>)` answers "how do I see
+inside this one collapse"; the header cue answers "do I need to," which matters more on a page
+where several collapses together hide most of what this render had to show.
+
+## The line budget
+
+**The meter is characters, not lines.** `options.budgetChars` (default `32768`) is the standing
+budget — always active, whether a caller sets it or not — and `options.budgetLines` is an
+*optional additional* ceiling with no default of its own: when a caller passes it, the render
+stays under whichever of the two limits is stricter, and passing one never turns the other off.
+Characters replaced lines as the primary meter because lines were a poor proxy for what the budget
+actually protects — a reader's token cost. A digest line runs anywhere from about 40 to over 900
+characters (a full 40-entry fold line can exceed 1000), so a line-count budget could not predict
+token cost within better than roughly a factor of 15; characters predict it within about ±20%
+(measured chars-per-token across a real soak: 2.51–3.50, median 2.84) with no dependency on which
+tokenizer the *consuming* model happens to use. `32768` chars is about 11.5K tokens at that
+median — the measured "knee" of the trade: half it and a real page's skeleton starts losing
+section-level structure; double it and an ordinary production page's default `look` costs 20K+
+tokens again, the exact cost this design exists to bound.
+
+Over budget, the renderer degrades in three stages, in this order:
+
+1. **Normal.** Fold runs that match on tag, role, flow, child count, a coarse size bucket, own
+   facts, and whether a fact exists anywhere in their descendants.
+2. **Aggressive.** Widen only the *shape* half of that match — drop the size bucket, so a page's
+   own wildly different container heights fold more readily. Never widens the fact half: no
+   degradation stage can make two elements fold together if they differ in what they measure, own
+   or descendant. This is a fix, not a restatement of old behaviour — the previous aggressive stage
+   dropped facts from the signature entirely, so a row that overflowed and a row that did not could
+   fold together under budget pressure, with only the representative's fact text left to (silently,
+   incorrectly) stand in for both. See [The fold line](#the-fold-line) for what "a fact anywhere in
+   their descendants" means for folding.
+3. **Collapse.** Replace a container's children with a `[folded: …]` line, one container at a
+   time, until the budget is met. Candidates are ranked **shallowest first** — by subtree height
+   ascending (a container of only leaves collapses before its parent, which collapses before *its*
+   parent, and so on upward: "peel from the leaves"), ties broken by descendant count ascending —
+   with every non-root candidate tried before any root: collapsing a root can leave nothing else
+   behind to read, so it is the true last resort rather than one more option competing on size. A
+   candidate already inside a just-collapsed container is skipped rather than collapsed again,
+   since it would change nothing, and a candidate whose own collapse would save fewer than two
+   lines (a single-child wrapper, mostly) is skipped too — trading one line for one `[folded: …]`
+   line buys nothing.
+
+A page with no non-root container at all — a `body` of only leaf children, for instance — has no
+candidate until stage 3 reaches its root rung. Stage 3 can therefore still collapse the whole page
+to one `[folded: …]` line under a tight enough budget; that is the intended last resort, not a bug.
+
+**Why the collapse order changed, and why raising the old line default alone never could have
+fixed this.** Ranking candidates *biggest first* — the previous order — meant the first collapse
+tried on a real production page was almost always a whole-page wrapper, so output was a step
+function with no middle: measured on real captures, `stripe.com`, `bbc.com`, and `tailwindcss.com`
+each rendered 12 lines at every budget up to some threshold and 1,050–1,363 lines immediately past
+it, with nothing achievable in between at *any* budget value. No default and no sweep of that one
+number could fix a step function with no middle rung to land on — the ordering was the defect, not
+the constant. Ranking shallowest-first instead means a page degrades through its own actual depth
+structure: measured after the reorder, sweeping the same three sites' budgets from 1K to 200K
+characters produces smooth, monotonic growth with no cliff anywhere in the range. `stripe.com`
+itself goes from a 12-line dead end to a 318-line skeleton at the default budget, with 97 disclosed
+collapses standing in for what a reader isn't looking at — every page in the investigating soak
+landed between roughly 1.5K and 11.6K tokens, none reduced to near-nothing and none an unbounded
+dump. Full numbers, method, and the sites involved are in `docs/notes/06-budget.md`; I have not
+independently reproduced the multi-site sweep here (it depends on soak bundles this environment
+does not have), so treat the specific figures as reported rather than re-verified by this pass —
+what I have verified directly is the shallowest-first ordering and the `budgetChars`/`budgetLines`
+relationship, against this repo's own synthetic fixtures and the shipped `render.ts`.
+
+It never truncates mid-tree. Folding harder is always preferred to hiding a subtree, and hiding a
+subtree is always preferred to stopping in the middle.
+
+### The two-call idiom
+
+Treat `look` and a follow-up `--focus` as the intended shape of reading an unfamiliar page, not as
+a fallback for when the default output is too big. A bare `look` is bounded on every page — at
+most about 11.5K tokens, by design — and answers "where is everything, and where do the
+measurements live"; the collapse cue and every `[folded: …]` line's own `(--focus <id>)` then name
+exactly where to point a second, equally bounded call. Reported results from the budget
+investigation (`docs/notes/06-budget.md` §6; not independently reproduced here — real external
+sites, not fixtures this repo ships):
+
+| site | `look` (default budget) | `--focus <cue id>` |
+|---|---|---|
+| stripe.com | 32,626 chars / ~11.5K tok / 318 lines | 1,529 chars / 18 lines, 0 folds |
+| bbc.com | 33,345 chars / ~11.7K tok / 382 lines | 701 chars / 12 lines, 0 folds |
+| tailwindcss.com | 20,808 chars / ~7.3K tok / 226 lines | 1,149 chars / 20 lines, 0 folds |
+| ar.wikipedia.org | 32,871 chars / ~11.6K tok / 402 lines | 1,329 chars / 18 lines, 0 folds |
+
+Two bounded calls following the cue cost roughly what one of the *old* mid-size dumps cost, and the
+old failure mode — a 300-token render hiding 99%+ of the page with no printed route anywhere in
+it — no longer exists to fall into. **This is a different question from manually naming a coarse
+id.** Following the cue's own hint converges cheaply because the cue always names the collapse
+actually blocking the render; asking for a large, arbitrary subtree by hand is unbounded by design
+and pays the honest cost of what you asked for — see "The `--focus` hint" above for the
+`ar.wikipedia.org` example where that cost is 192,868 characters.
+
+## What is not in the digest
+
+**Full clip precision.** `capture` attaches a `ClipFact` to every element that extends past a
+clipping ancestor — which ancestor, its `overflow` value, how far past on each side, how much
+survives, and whether a user could scroll to reveal the rest. The summary of that renders inline as
+the [`clipped`](#clipped) fact, but `ElementRecord.clip` itself carries more precision than the
+line does: in the menu example above, `e5`'s record has `hidden.bottom: 103.78` where the digest
+line rounds to `103.8px`. Read the record rather than the line when a fractional pixel matters.
+
+**Verdicts, severities, confidences and scores.** None exist anywhere in this package.
+
+**Contrast, alignment, spacing and density.** Not measured. The predecessor's `spacing` and
+`alignment` checks produced zero confirmed true positives across their whole life and were deleted
+rather than ported.
+
+**Elements folded away as wrappers.** A single-child wrapper whose child exactly fills its content
+box is folded into one line, and the line carries the *inner* element's id and tag. Element ids in
+a digest are therefore not contiguous.
+
+**Anything after the element cap.** 5000 elements, both capture paths, flagged in the header.
+
+## Parsing
+
+```ts
+import { parseDigestLine } from '@michaelmagan/dnumb';
+
+for (const line of digest.split('\n')) {
+  const parsed = parseDigestLine(line);
+  if (parsed?.kind === 'element' && parsed.facts.length > 0) {
+    console.log(parsed.id, parsed.rect, parsed.facts);
+  }
+}
+```
+
+`parseDigestLine(line)` returns one of four things.
+
+`null` — comment lines, blank lines, and anything it does not recognise.
+
+`{ kind: 'element' }`:
+
+```ts
+{
+  kind: 'element';
+  id: string;             // 'e13'
+  tag: string;            // 'span'
+  annotation: string | null;  // 'heading' — bare, the `.` or `#` sigil stripped
+  text: string | null;    // as rendered, including the trailing '…' if truncated
+  rect: { x: number; y: number; width: number; height: number };
+  flow: 'row' | 'column' | 'grid' | 'none';
+  gap: { direction: 'down' | 'right'; value: number; overlap: boolean } | null;
+  facts: string[];        // fact bodies, brackets stripped, in rendered order
+  belowFold: boolean;
+  depth: number;          // from the indentation, two spaces per level
+}
+```
+
+`{ kind: 'fold' }`:
+
+```ts
+{
+  kind: 'fold';
+  count: number;
+  likeId: string;
+  period: number;          // 1 for a plain run; >1 for a periodic fold
+  variance: string | null; // the `(...)` spread token, verbatim, or null
+  entries: Array<{ id, x, y, gap }>;
+}
+```
+
+`{ kind: 'collapsed' }`:
+
+```ts
+{ kind: 'collapsed'; nodeCount: number; bbox: { x, y, width, height } }
+```
+
+Four things about the parser are worth knowing before relying on it.
+
+**`annotation` does not say which sigil it came from.** `#save-btn` and `.button` both parse to a
+bare string. If the distinction matters, read the record rather than the line.
+
+**`facts` is open-ended by design.** The parser keeps every bracketed group that is not a known
+structural token, so the renderer can add a fact kind without the parser learning its name first.
+The tokens it excludes are `row`, `column`, `grid`, `below fold`, and `wraps <n>`.
+
+**It accepts tokens the renderer does not emit.** A gap may carry an ` OVERLAP` suffix and `flow`
+may be `column`; neither is produced by the current renderer. Do not write a producer that emits
+them and expect other readers to cope.
+
+**Text containing `@x,y WxH` breaks the split.** The parser locates the geometry by regex, and an
+element whose rendered text looks like a coordinate pair will be mis-parsed. Text is capped at 30
+characters, so this is rare and not defended against.
+
+Round-tripping is tested: `test/unit/digest.test.ts` parses element lines and fold lines back out
+of real renderer output and asserts on the numbers.
+
+## Two worked examples
+
+### A truncated heading
+
+`test/fixtures/flex-min-width-ellipsis.html`, the reconstruction of a real merged fix. A flex
+heading that shrank to 668px around 815px of content.
+
+**Live example** (`fixture=test/fixtures/flex-min-width-ellipsis.html url=file://.../flex-min-width-ellipsis.html`)
+— regenerated fresh by `test/browser/doc-examples.test.ts` every run.
+
+```text
+# dnumb digest v2 — file://.../flex-min-width-ellipsis.html — 1024x768 — cdp
+# 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: 1024x28 (6 records → 6 layout nodes, 0 dropped, 0 wrappers folded)
+# facts: 2 elements carry facts
+# colors: 2 fg/bg pairs across 2 text elements; ratio 18.26–21.00; lowest e5 #000000 on #efefef self 13.3px/400
+e0 body @0,0 1024x28
+  e1 div @0,0 723x28 [row]
+    e2 h1.heading "Quarterly revenue review for t…" @0,0 668x28 [overflow-x +147px; clip, ellipsis]
+      e3 span "Quarterly revenue review for t…" @0,0 815x28 [clipped by e2 h1; overflow:hidden, not scrollable; 147px right, 668x28 visible]
+    e4 div @684,3 39x23 [row] →16
+      e5 button.button "Edit" @684,4 39x21
+```
+
+The predecessor to this tool measured exactly this pair — `scrollWidth: 815, clientWidth: 668` —
+on the real page this fixture reconstructs, and then discarded the finding, because the rule that
+owned the measurement read `text-overflow: ellipsis` as absolution. Both facts are now on one line and neither is a verdict. 147px of a heading is
+unreadable whether or not it ends in three dots; whether that matters depends on whether the full
+title matters, which is not something a threshold can know.
+
+`e3`'s box is 815px wide inside a 668px parent. That is the same fact from the other side, rendered
+as its own `clipped` fact naming `e2` as the clipper.
+
+### A column that collapsed to zero width
+
+`test/fixtures/zero-width-column.html`. A flex column with `flex: 0 1 0` and nothing to grow into,
+whose own `.sidebar` also carries `overflow: hidden`.
+
+**Live example** (`fixture=test/fixtures/zero-width-column.html url=file://.../zero-width-column.html`)
+— regenerated fresh by `test/browser/doc-examples.test.ts` every run.
+
+```text
+# dnumb digest v2 — file://.../zero-width-column.html — 1024x768 — cdp
+# 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: 1024x1239 (7 records → 5 layout nodes, 1 dropped, 1 wrappers folded)
+# facts: 2 elements carry facts
+# colors: 1 fg/bg pair across 1 text element; ratio 21.00–21.00; lowest e6 #000000 on #ffffff via canvas 16px/400
+e1 div @0,0 1024x1239 [row]
+  e2 aside.complementary @0,0 0x1239 [overflow-x +60px; clip, wraps] [0x1239 zero-box; content "Filters and saved views"]
+    e3 div "Filters and saved views" @0,0 0x1239 [overflow-x +60px; visible, wraps] [0x1239 zero-box; content "Filters and saved views"]
+  e5 main.main @0,0 1024x54 →0
+    e6 p.paragraph "Report body" @0,16 1024x22
+```
+
+Three things to notice. `e0` has no line — it is the one single-child wrapper here whose child
+exactly fills its content box, so it folds, which is why the header says `1 wrappers folded` and
+the first line is `e1`. `e2` (the `.sidebar` element itself) *does* get its own line, and this is
+the more interesting half: a wrapper is only folded away when it has nothing of its own to say, and
+`e2` carries a fact its child does not share — its own `overflow: hidden` versus `e3`'s `visible` —
+so folding it would have discarded a genuinely different measurement, the exact failure a wrapper
+fold exists to avoid. `e2` and `e3` are the facts-and-counter-facts pairing this whole format is
+built around, on two lines instead of the one this fixture used to show: the parent clips
+(`overflow-x +60px; clip, wraps`) while its own child, inside it, computes as unclipped
+(`overflow-x +60px; visible, wraps`) — same number, opposite consequence, because the box that
+overflows and the box that hides the overflow are not the same element.
+
+Neither `e2` nor `e3` has a visible box at all, so the layout filter would normally drop both.
+Elements carrying facts are exempt from that filter, because the collapsed column is the entire
+point.
+
+Notice, too, what is *not* in the `# page:` line any more: no `; <id> extends the page … beyond the
+next element` clause. This fixture used to have a single 1239px-tall element standing out from a
+54px `main`, and the clause named it. Now `e2` and `e3` are both 1239px tall — the wrapper fold that
+used to hide `e2` behind `e3` is gone — so the candidate that reaches the page bbox's bottom edge has
+a *tied* runner-up on that same edge, the gap between them is ~0, and `pageOutlier` correctly
+declines to name either one "the" outlier rather than guessing. That is the dominance heuristic
+behaving properly on a page that no longer has a single dominant element, not a regression in the
+clause itself — see item 3 ("Page") under [Header lines](#header-lines) above for a live example of
+a page where the clause still fires.