@michaelmagan/dnumb 0.1.0

package/AGENTS.md

@@ -0,0 +1,180 @@
+# dnumb — for agents
+
+You are the intended reader. This package has no HTML report, no dashboard, and nothing to open
+in a browser. Every output is text a model reads.
+
+## What it is
+
+`dnumb` turns a rendered page into measurements: element geometry, overflow, clipping, and the
+CSS that says what those measurements mean. It renders them as a linear text digest — one line per
+element that stands on its own, and one fold line standing in for a whole run of repeated siblings
+at once, each still addressable by id (see [`docs/digest.md`](https://github.com/michaelmagan/dnumb/blob/main/docs/digest.md#the-fold-line)) — and
+writes them to a self-contained JSON bundle you can query later on a machine with no app and no
+browser.
+
+**Live example** (`fixture=test/fixtures/flex-min-width-ellipsis.html line=e2`) — one real line out
+of a real capture, checked by `test/browser/doc-examples.test.ts`; the full capture is in
+[`docs/digest.md`](https://github.com/michaelmagan/dnumb/blob/main/docs/digest.md#a-truncated-heading).
+
+```text
+e2 h1.heading "Quarterly revenue review for t…" @0,0 668x28 [overflow-x +147px; clip, ellipsis]
+```
+
+That line says a heading is 668px wide around 815px of content, that the box clips, and that the
+clipped edge ends in an ellipsis. It does not say whether that is a bug.
+
+## When to reach for this instead of a screenshot
+
+Reach for it when the question is *where things are*, not *what they look like*:
+
+- Is this text truncated, and by how much?
+- Does this container overflow, and can a user scroll to what is hidden?
+- Did this element move, and by how much, between two states?
+- Is this menu clipped by an ancestor's `overflow: hidden`?
+- What is at this coordinate in the screenshot I am looking at?
+- How far apart are these two boxes, exactly?
+- Is this text's contrast against what it is actually drawn on a real number, and what is that
+  number — not "does it look readable," a composited ratio with the size and weight beside it.
+
+Stay with the screenshot for *paint* — imagery, typography, and overall visual impression, and
+anything painted rather than styled (a photo, a canvas, video, a gradient's true value at the
+glyphs). Color is the one item that moved off this list: dnumb now measures the ink and the
+composited backdrop text is actually drawn on, and reports a WCAG contrast ratio, never a
+pass/fail — see [`docs/digest.md`](https://github.com/michaelmagan/dnumb/blob/main/docs/digest.md#color).
+The two tools still compose well: use the image to form a suspicion and the numbers to check it.
+
+Honest cost: on the predecessor to this tool, tool-grounded review cost **25–30% more tokens**
+than screenshot-only, driven by round-trip count rather than payload size. In the same
+experiment, vision alone reported 4 fabricated findings on a provably clean page, and 10 on
+replication; both tool-grounded arms reported zero, twice. Spend round-trips when a visual
+impression needs checking. Do not sweep.
+
+## Facts, with counter-facts
+
+Nothing in this package decides. A fact is emitted whenever the measurement exists — no
+thresholds beyond subpixel noise, no severity, no confidence, no suppression — and it carries the
+adjacent CSS that determines what the measurement means:
+
+**Illustrative** — hand-composed to contrast three cases; the first is real (see above), the gloss
+after each is plain English, not renderer output.
+
+```text
+[overflow-x +147px; clip, ellipsis]   147px of text is cut off, and it ends in three dots
+[overflow-x +227px; clip, wraps]      same clip, but the text wrapped; this is height, not truncation
+[overflow-x +90px; scroll, wraps]     a scroll region, working as intended
+```
+
+Same number, three situations, and the difference is never in the number.
+
+Five kinds of fact exist, and this is what each one *is* — none of them says whether it is a
+problem:
+
+- **`overflow-x` / `overflow-y`** — `scrollWidth`/`scrollHeight` exceeds `clientWidth`/
+  `clientHeight` by the stated number of px. Carries what happens to the extra content: clipped,
+  scrolled, or visible, and (on the x axis) whether the text wraps, doesn't wrap, or ends in an
+  ellipsis.
+- **`zero-box`** — the element is still in the layout but has collapsed to under 1px on one axis,
+  and there is content inside it. Carries that content, so a collapsed spacer (nothing inside) and
+  a collapsed column (a page of content inside) don't look the same.
+- **`clipped`** — an ancestor's `overflow` hides part of the box. Carries which ancestor, how much
+  is hidden on each side, how much survives, and whether it is `scrollable` — i.e. whether a user
+  could ever reach the hidden part.
+- **`color`** — the different one: not printed inline on an element line at all. Every visible
+  element with its own text gets an *effective backdrop* (the real, composited color behind it,
+  not its own usually-transparent `background-color`) and, where both ink and backdrop resolve, a
+  WCAG contrast ratio — never a pass/fail. Reachable via the digest's `# colors:` header line, `q
+  color`, and `q describe`, per [`docs/digest.md`](https://github.com/michaelmagan/dnumb/blob/main/docs/digest.md#color).
+
+Full grammar, every token, in [`docs/digest.md`](https://github.com/michaelmagan/dnumb/blob/main/docs/digest.md).
+
+**Do not treat a fact as a verdict.** Do not report `[overflow-x +147px]` as "an overflow bug"
+without the consequence tokens beside it, and do not treat the absence of facts as a clean bill of
+health — this package does not measure typography or alignment at all, and even where it does
+measure color and contrast, it never says whether a ratio is good enough; that threshold lives in
+the reader, not the tool. When you draw a conclusion, name the fact you drew it from, so a reader
+can check the inference separately from the measurement.
+
+The predecessor to this tool died of exactly this. It measured `scrollWidth: 815, clientWidth:
+668` on a real truncated heading, then discarded the finding because the rule that owned the
+measurement read `text-overflow: ellipsis` as absolution. The full account is in
+[`docs/01-POSTMORTEM.md`](https://github.com/michaelmagan/dnumb/blob/main/docs/01-POSTMORTEM.md).
+
+## Two things that will trip you up
+
+**Element ids are stable within one capture only.** `e13` is the element's index in capture order.
+It is not a DOM id and not a selector. Inserting one element earlier in the document shifts every
+id after it. Never carry an id from one capture into a claim about another, and never write one
+into a test expectation. Match on `testId`, `domId`, accessible name, or role instead.
+
+**An overflow number on an ellipsized element includes the ellipsis.** Chromium reserves layout
+space for the ellipsis glyph and counts it in `scrollWidth`. Measured at +10px at font-size 10 and
++17px at font-size 20; the amount is that glyph's advance width, so it tracks font-size and varies
+with font-family. When a line says `ellipsis`, treat the number as an upper bound on the hidden
+content, not an exact width, and do not subtract a constant. Full detail in
+[`docs/digest.md`](https://github.com/michaelmagan/dnumb/blob/main/docs/digest.md).
+
+## The library surface that exists today
+
+```ts
+import {
+  capture,          // capture(page, options?) -> CaptureResult. `page` is anything with `evaluate`.
+  renderDigest,     // renderDigest(snapshot, meta, options?) -> string
+  parseDigestLine,  // parseDigestLine(line) -> element | fold | collapsed | null
+  diffCaptures,     // diffCaptures(before, after, options?) -> { text, changes, truncated }
+  factsFor,         // factsFor(el, byId) -> Fact[]
+  factsForAll,      // factsForAll(elements) -> Array<{ element, facts }>
+  renderFacts,      // renderFacts(facts) -> "[fact] [fact]"
+  clipFactFor,      // clipFactFor(el, byId) -> ClipFact | undefined
+  attachClipFacts,  // attachClipFacts(elements) -> elements, `clip` attached in place
+  formatNotMeasured, // formatNotMeasured(notMeasured) -> "not measured: …" | null
+  buildBundle,      // buildBundle(captureResult, { name, url, capturedAt, ... }) -> Bundle
+  parseBundle,      // parseBundle(text, source?) -> Bundle, throws BundleFormatError
+  serializeBundle,  // serializeBundle(bundle) -> string
+  SPEC_VERSION,     // 1
+} from '@michaelmagan/dnumb';
+```
+
+`diffCaptures` is the other core verb — what changed between two captures, and why, at the same
+"report, do not adjudicate" register as everything else in this package. See the CLI's `diff` verb
+and [Reading a diff](https://github.com/michaelmagan/dnumb/blob/main/README.md#reading-a-diff) in
+the README for the grammar and a worked example.
+
+Plus the geometry primitives — `intersect`, `contains`, `gapAlong`, `area`, `center` — all pure
+functions over plain `{ x, y, width, height }` rects.
+
+From a Playwright suite:
+
+```ts
+import { capture } from '@michaelmagan/dnumb/playwright';
+
+test('settings page', async ({ page }, testInfo) => {
+  await page.goto('/settings');
+  await capture(page, 'settings-desktop', { testInfo });
+});
+```
+
+That writes `.dnumb/settings-desktop.json` and attaches it to the test report. The two `capture`
+functions are not the same: the root export returns records in memory, `@michaelmagan/dnumb/playwright`'s takes
+a name and writes a bundle to disk.
+
+Types are also exported standalone from `@michaelmagan/dnumb/spec` — `ElementRecord`, `Snapshot`, `ClipFact`,
+`Rect`, `BoxSides`, `SPEC_VERSION` — with zero runtime code and zero dependencies.
+
+`playwright-core` is an optional peer. Capture needs a driver; everything downstream of a bundle
+does not.
+
+## Status
+
+**Pre-release, not yet on npm.** The library surface above is built and tested. The CLI has a
+stable verb set — `capture`, `look`, `diff`, and `q describe|find|at|within|distance|nearest|facts|color`
+— documented with worked examples in
+[README § From the CLI](https://github.com/michaelmagan/dnumb/blob/main/README.md#from-the-cli) and
+[§ Reading a diff](https://github.com/michaelmagan/dnumb/blob/main/README.md#reading-a-diff). This
+file still does not restate flags, on purpose: run `dnumb --help` for the exhaustive, versioned
+list of what your installed copy actually supports, and treat it as authoritative over any prose
+here or there.
+
+The digest format is specified in
+[`docs/digest.md`](https://github.com/michaelmagan/dnumb/blob/main/docs/digest.md). Build progress,
+including what was tried and what was wrong, is in
+[`LOG.md`](https://github.com/michaelmagan/dnumb/blob/main/LOG.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Magan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,297 @@
+# dnumb
+
+**Design, in numbers.** Turns a rendered page into measurements an agent can read — element
+geometry, overflow, clipping, and the CSS that says what each measurement means.
+
+The consumer is always an agent. There is no HTML report, no dashboard, and nothing to open in a
+browser.
+
+**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. The identical capture, spelled
+out line by line, is in [`docs/digest.md`](docs/digest.md#a-complete-digest).
+
+```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,77 68x20 →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
+```
+
+That is real output, rendered from `test/fixtures/clipped-menu.html`, captured via the CDP path
+(the trailing `— cdp` on the identity line; see [`docs/digest.md`](docs/digest.md#header-lines)).
+A 44px toolbar reporting 105px of vertical overflow with `clip` beside it, a menu overlapping its
+own previous sibling (negative gap, `→-110`), and a menu plus its first item that survive as a
+4-5px sliver while the last two items are entirely hidden — `e6`, `e7` and `e8` share a tag, role
+and box size but do not fold together, because that sliver is a real difference the fold signature
+is built to keep visible. Neither line says "bug". The reader combines them.
+
+The `# colors:` line is a fifth kind of fact — never printed inline on an element line the way the
+other four are, only in this one header line and the `q color` verb — naming every ink-on-backdrop
+pair on the page with a WCAG contrast ratio beside it, and never a pass/fail. See
+[`docs/digest.md`](docs/digest.md#color) for the full grammar.
+
+> **Status: pre-release.** Not published to npm. The library — capture, digest, facts, clip
+> analysis, bundles, the Playwright integration — is built and tested. The CLI (`capture`, `look`,
+> `diff`, `q`) has a stable verb set, worked below in [From the CLI](#from-the-cli) and
+> [Reading a diff](#reading-a-diff); `dnumb --help` stays the exhaustive, versioned option list.
+> Build journal in [`LOG.md`](LOG.md); the plan is
+> [`docs/00-PLAN-OF-RECORD.md`](docs/00-PLAN-OF-RECORD.md).
+
+## The idea
+
+A screenshot tells a model what a page looks like. It does not tell it that a heading is truncated
+by 147 pixels, or that a menu opened 104 pixels below the bottom of an `overflow: hidden` toolbar
+and is therefore unreachable. Those are numbers the DOM already has.
+
+`dnumb` collects them, renders them as text, and then refuses to draw the conclusion. Every fact
+comes with the adjacent fact that disambiguates it:
+
+**Illustrative** — hand-composed to contrast three cases; the first is real (see the digest above),
+the gloss after each is plain English, not renderer output.
+
+```text
+[overflow-x +147px; clip, ellipsis]     truncated
+[overflow-x +227px; clip, wraps]        fine — the text wrapped
+[overflow-x +90px; scroll, wraps]       fine — a scroll region
+```
+
+Same measurement, three different situations, and the difference is never in the number. A rule
+engine standing between the measurement and the model is what the predecessor to this tool got
+wrong, at length, in [`docs/01-POSTMORTEM.md`](docs/01-POSTMORTEM.md).
+
+Five kinds of fact exist in total — `overflow-x`, `overflow-y`, `zero-box`, `clipped`, and
+`color` (the one that never prints inline, only in the `# colors:` header line and `q color`; see
+[`docs/digest.md`](docs/digest.md#color)) — one line each on what the measurement *is* in
+[AGENTS.md](AGENTS.md#facts-with-counter-facts).
+
+## In a Playwright suite
+
+The whole adoption thesis is one import and one call in a test somebody already wrote:
+
+```ts
+import { capture } from '@michaelmagan/dnumb/playwright';
+
+test('settings page', async ({ page }, testInfo) => {
+  await page.goto('/settings');
+  await page.getByRole('heading', { name: 'Settings' }).waitFor(); // wait for real content, not just `load`
+  await capture(page, 'settings-desktop', { testInfo });
+});
+```
+
+**Capture takes no wait of its own — it measures whatever is on screen the instant it runs.**
+`goto()`'s default `load` event fires on a client-rendered page before hydration has painted
+anything, so capturing right after it can write a bundle that is almost entirely empty: hundreds
+of real DOM nodes present but zero-size and invisible, a body box collapsed to `0` height, while
+the actual page renders a heartbeat later. This is not theoretical — it reproduced on roughly half
+of repeated captures of a live production SPA in soak testing, following this exact
+`goto()`-then-`capture()` pattern. Wait for something you know should be there — a locator, as
+above, is the most reliable signal; `page.waitForLoadState('networkidle')` is a weaker fallback
+that can hang on pages that poll or hold a websocket open. On a capture this sparse, `look` does
+not print a half-empty digest and let you notice — it declines to render a body at all and prints
+a `# no layout to digest: …` refusal instead, naming the same shape (records that never reached a
+layout node, a near-zero page bbox) and how to re-capture; see
+[`docs/digest.md`](docs/digest.md#header-lines) item 4. Treat that as "re-run this capture," not as
+a description of the real page — and if a second capture, later, still refuses the same way, that
+repetition is itself a finding: the page never lays out, not that it was merely caught mid-load.
+`q facts`, `q describe`, `q find`, and `look --focus <id>` all still read the underlying bundle in
+full regardless. The CLI's `capture` verb has the same hazard and the same knob, `--wait`; see
+[From the CLI](#from-the-cli) below.
+
+**A capture can also take seconds instead of milliseconds, for a reason that has nothing to do with
+dnumb.** Measured on a real page: 927 elements took 5–10.7s, where a comparable page captured 2,918
+elements in 124ms. Root cause, isolated down to a raw no-op CDP call (500ms+ on the slow page,
+under 2ms on the control) and confirmed idle on Blink's own render thread the whole time: a
+full-viewport `requestAnimationFrame` animation (a WebGL hero, a large animated canvas) running
+under **headless Chromium with no GPU access** falls back to a CPU software rasterizer, and that
+pegs the browser's GPU process at 600%+ CPU — every CDP round trip, dnumb's included, queues behind
+it. This is not a dnumb defect: both capture paths are affected equally and identically, dnumb's
+own work on the page is not what is slow, and the cost is **unbounded** — it scales with the page's
+own pixel count × shader cost × frame rate, which dnumb has no visibility into. It hits precisely
+where dnumb is meant to run: headless, no GPU passthrough, is the default for most CI and most
+agent sandboxes. If a capture is inexplicably slow, suspect a full-bleed animated canvas or WebGL
+element on the page before suspecting dnumb.
+
+**Giving the browser real GPU access is the only known remedy — measured, not theorised — because
+the two mechanisms that looked like they should stop the animation both fail to.** Pausing Web
+Animations (`document.getAnimations()`) does not help: you cannot `cancelAnimationFrame` a loop the
+page's own script owns, not yours. Freezing the page around the capture window
+(`Page.setWebLifecycleState({ state: 'frozen' })`) looked like it should target the actual
+mechanism, but tested against a real stalling page, it froze nothing — the `requestAnimationFrame`
+callbacks and timers kept running at full rate straight through it. A third candidate, overriding
+`requestAnimationFrame` in a page-init script, only takes effect across a navigation dnumb itself
+performs, so it can never apply to the library's usual mode, where the caller hands in a page
+that has already navigated. With no in-page mechanism that survives, GPU passthrough is what is
+left.
+
+**This is a performance hazard, not a geometry-correctness one, and the two do not imply each
+other.** A page under heavy GPU load simply takes longer to capture; separately, some pages are
+genuinely in motion at the instant they are captured (the settledness hazard above). The two can
+co-occur, but neither one means the other is happening: the real page measured for this section —
+the one that stalls every CDP round trip for half a second — produced **zero** moving elements
+between two samples taken 100ms apart. Its canvas repaints continuously; nothing in its layout
+moves. A slow capture is a reason to expect a wait, not a reason to distrust a measurement that
+came back stable.
+
+That writes `.dnumb/settings-desktop.json` and attaches it to the test report. The bundle is one
+self-contained file: it can be committed, emailed, or attached to CI, and queried later on a
+machine with neither the app nor a browser.
+
+Render a digest from it any time after:
+
+```ts
+import { parseBundle, renderDigest } from '@michaelmagan/dnumb';
+import { readFileSync } from 'node:fs';
+
+const bundle = parseBundle(readFileSync('.dnumb/settings-desktop.json', 'utf8'));
+console.log(renderDigest(bundle, { url: bundle.url, viewport: bundle.viewport, state: bundle.name }));
+```
+
+`playwright-core` is an optional peer, `>=1.17.0`. Capture needs a driver; everything downstream
+of a bundle does not — the offline `--from <bundle>` path has no peer at all, and nothing in this
+package ever imports `playwright-core` except the CLI's `capture` verb, which loads it lazily and
+tells you how to install it if it is absent.
+
+The floor is the version, and only the version, that the code can justify: `page.goto`'s
+`waitUntil: 'commit'` — which `dnumb capture --wait commit` exposes — landed in 1.17.0. Verified in
+both directions: 1.16.0 answers `waitUntil: expected one of (load|domcontentloaded|networkidle)`,
+and 1.17.0 completes a full CDP-fast-path capture. The library entrypoints (`dnumb`,
+`dnumb/playwright`) need less than that: any object with `evaluate`.
+
+## From the CLI
+
+No test suite yet, or just want a bundle right now? The shortest path from a URL to a digest is
+two commands:
+
+```bash
+dnumb capture https://example.com/settings --name settings-desktop
+dnumb --from .dnumb/settings-desktop.json look
+```
+
+`capture` launches a browser, navigates, captures, and writes `.dnumb/settings-desktop.json` —
+printing the path it wrote. `look` reads that bundle back and renders the digest. Every other verb
+— `q describe`, `q find`, `diff` — reads the same bundle the same way; none of them need a browser.
+
+`capture` takes `--name`, `--dir` (default `.dnumb`), `--viewport WIDTHxHEIGHT`, `--wait
+<load|domcontentloaded|networkidle|commit>`, and `--timeout`. It needs `playwright-core` — no
+other verb does — and says so plainly if it is missing.
+
+**Capture measures one instant.** A page still hydrating, still animating, or still fetching is
+reported exactly as it looked at that instant — skeleton screen included — with no way for dnumb to
+tell settled from loading. Pick `--wait` deliberately and re-run if a digest looks wrong. On a
+capture sparse enough that there is no real page to describe, `look` refuses to render a body at
+all rather than print one — see [`docs/digest.md`](docs/digest.md#header-lines) item 4;
+`npx dnumb --from ... look --json` adds a `"sparseCapture": true|false` field so a script can
+branch on this without parsing the digest text. If the capture itself takes seconds rather than
+milliseconds, see [the animated-canvas hazard](#in-a-playwright-suite) above before suspecting
+dnumb — headless Chromium without GPU access can turn a full-viewport WebGL or canvas animation
+into a CPU cost dnumb only queues behind.
+
+`dnumb --help` is the authoritative option list. `dnumb --version` prints two numbers, `dnumb
+<package version> (spec <N>)` — the installed package version (`package.json`'s own, not restated
+here since it moves independently of this file) and the bundle format's own `SPEC_VERSION`. The two
+move independently on purpose: the package can ship a new CLI verb or renderer improvement without
+the bundle shape changing at all.
+
+`q find` matches a needle against tag, role, test id, DOM id, text and accessible name — and, since
+a digest line's own annotation (`li.listitem`, `button#save-btn`) is something you will often copy
+straight off one, `q find` also accepts that exact compound shape as a conjunctive tag+role or
+tag+test-id search, and strips a trailing `…` a needle picks up from a truncated digest line before
+matching. Pasting an `e13`-shaped id in gets a pointer to `q describe` instead of a silent zero
+matches — ids are not text, and `find` does not search them.
+
+**`look`'s own fact count can be bigger than the facts `look` actually shows you.** `# facts: N
+elements carry facts` in a digest header counts every element with a fact, but folding and the line
+budget can still hide most of those facts from the body: a run of siblings can fold together with
+only their shared representative keeping its `[...]` bracket, or an entire subtree can collapse into
+one `[folded: …]` line, taking every fact inside it out of view. `q facts` is the verb that does not
+do this — it lists every fact-carrying element, one per line, independent of the digest's fold and
+collapse rules, capped by `--limit` (default 50) like every other list verb. `q facts --limit 0`
+prints all of them; reach for it whenever you need to know you have seen every fact, not just the
+ones the digest chose to keep on-screen.
+<!-- checked-claim: facts-limit-0-is-complete -->
+
+
+## Reading a diff
+
+`dnumb --from before.json diff after.json` is the other core verb: not one moment, but what
+changed between two. Six independent readers, given only this format and nothing else, scored 6/6
+correct accounts with zero fabrications in the format's original validation — including a control
+capture where nothing changed at all, which is why the fabrication guard below exists.
+
+**Live example** (`fixture=test/fixtures/state-01-menu-open.html source=diff transition=__toB before-name=menu-closed after-name=menu-open`)
+— a real transition on a real fixture, regenerated fresh by `test/browser/doc-examples.test.ts`
+every run.
+
+```text
+menu-closed → menu-open  1024x768 → 1024x768  cdp → cdp
+1 added  0 removed  3 changed  0 derived  43 folded
+
++ e5 nav.menu "Actions" @39,104.2 182x108.8 (was display:none) +3 inside
+~ e3 button.button "Actions" aria-expanded false → true
+! e5 nav.menu "Actions" clipped by e2 div [overflow:hidden, not scrollable] — 103.8px below it, 182x5 visible
+~ e2 div class-name bar → bar open
+```
+
+The header names the two captures and their viewports, then — when both sides know it — the two
+captures' own strategy (`cdp → cdp` above; see [`docs/digest.md`](docs/digest.md#header-lines) for
+what `cdp` and `walk` do and do not see), then how many primary changes each kind
+covers; `43 folded` means 43 more changes (mostly other elements pushed down by the menu opening)
+were subsumed into the four lines shown rather than printed on their own — nothing is dropped
+silently, `derived`/`folded` count what got rolled up. The body is one line per change, ranked
+structure-then-visibility-then-content-then-facts-then-geometry-then-paint so an agent reading
+top-down meets the act before its consequences:
+
+| Glyph | Means |
+|---|---|
+| `+` / `-` | added / removed |
+| `~` | changed (text, an attribute, a box, a style) |
+| `!` | now clipped by an ancestor — the same measurement the digest's `clipped` fact carries |
+| `✓` | a clip or an overflow that resolved — the fact is gone, stated rather than left silent |
+| `?` | boundary-ambiguous: both captures hit the 5000-element cap, and this element's presence or absence could be a real change or just the document-order shift the cap induces. Never printed as a plain `+`/`-`, because either would assert an answer this diff does not have. |
+
+`TRUNCATED: before capped at <N> elements, after capped at <N> elements — this diff compares a
+window of the page, not the whole thing` appears as a caveat line under the header whenever either
+capture hit that same 5000-element cap — the diff's own counterpart to the digest's `# TRUNCATED:`
+header line.
+
+A diff is capped at 15 body lines by default (`--limit` on the CLI); past that, the line says what
+it dropped rather than stopping silently, the same rule every cap in this package follows. A page
+where nothing observable changed prints `(no observable change)` rather than nothing at all — an
+empty body and a page that did not change would otherwise look identical.
+
+## Documentation
+
+| Doc | What it is |
+|---|---|
+| [docs/digest.md](docs/digest.md) | **The digest format.** Every token, every fact form, the fold and collapse syntax, the parser contract |
+| [AGENTS.md](AGENTS.md) | For the model that will use it. Ships in the tarball |
+| [skills/dnumb/SKILL.md](skills/dnumb/SKILL.md) | The agent skill. Ships in the tarball, discoverable via `@tanstack/intent` |
+| [LOG.md](LOG.md) | Build journal, one entry per step |
+| [docs/00-PLAN-OF-RECORD](docs/00-PLAN-OF-RECORD.md) | **Authoritative.** Decisions, build order, kill criteria |
+| [docs/01-POSTMORTEM](docs/01-POSTMORTEM.md) | Why the `layout-audit` prototype failed |
+| [docs/02-PLAN-fable](docs/02-PLAN-fable.md) | Product design: verbs, digest v2, diff grammar, validation |
+| [docs/03-SCAFFOLD](docs/03-SCAFFOLD.md) | Repo/build/CI/publish spec |
+| [docs/04-CRITIQUE](docs/04-CRITIQUE.md) | Build-vs-buy evidence, live-verified CDP tests |
+| [docs/notes/](docs/notes/) | Per-step working notes and validation results |
+
+The prototype this succeeds is a worktree of another repo, not part of this one:
+
+```bash
+git -C ~/workspace/github/tambo-ai/charming worktree add ~/Projects/dnumb-prototype \
+  origin/claude/agent-design-tool-checks-pw2heg
+```
+
+## License
+
+MIT © 2026 Michael Magan

package/dist/analysis/cluster.cjs

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * 1-D numeric clustering and spacing-grid detection — pure arithmetic over
+ * plain `number[]`, no `LayoutNode`/`ElementRecord` knowledge at all (the
+ * caller decides whether the numbers are x-coordinates, gaps, or anything
+ * else). Same boundary rules as the rest of `src/analysis/`: no imports
+ * beyond `../snapshot/types.js` and sibling `analysis/` modules — this file
+ * needs neither, so it has no imports.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clusterEdges = clusterEdges;
+exports.detectBaseUnit = detectBaseUnit;
+exports.spacingStats = spacingStats;
+/**
+ * Groups `values` into 1-D clusters using adjacent-gap chaining: sort
+ * ascending, then start a new cluster whenever the gap between two
+ * consecutive sorted values exceeds `tolerance`. This is deliberately
+ * "adjacent" rather than "each within `tolerance` of the cluster's running
+ * mean" — a run of values 2px apart (0, 2, 4, 6, 8) chains into one cluster
+ * under either rule, but the two rules diverge once a cluster's span grows
+ * past `tolerance`; adjacent-gap chaining is the simpler rule to reason
+ * about and to test, and matches "group any within tolerance px of each
+ * other" read as a chain of pairwise closeness rather than a fixed-radius
+ * ball around one center.
+ */
+function clusterEdges(values, tolerance = 2) {
+    if (values.length === 0)
+        return [];
+    const sorted = values.map((value, index) => ({ value, index })).sort((a, b) => a.value - b.value);
+    const clusters = [];
+    let current = [];
+    function flush() {
+        if (current.length === 0)
+            return;
+        const sum = current.reduce((total, entry) => total + entry.value, 0);
+        clusters.push({
+            value: sum / current.length,
+            count: current.length,
+            members: current.map((entry) => entry.index),
+        });
+        current = [];
+    }
+    for (const entry of sorted) {
+        const prev = current.at(-1);
+        if (prev !== undefined && entry.value - prev.value > tolerance)
+            flush();
+        current.push(entry);
+    }
+    flush();
+    return clusters;
+}
+const MIN_GAP_SAMPLES = 5;
+const MIN_ON_GRID_SHARE = 0.5;
+const GRID_TOLERANCE = 1;
+/**
+ * Picks the candidate spacing unit (default `[4, 8]`) that best explains
+ * `gaps`: for each candidate, the fraction of non-zero gaps within 1px of a
+ * multiple of that unit. Zero-valued gaps are excluded from both the sample
+ * count and the coverage fraction — a touching pair (gap 0) is trivially "on
+ * every grid" and would inflate the score without saying anything about the
+ * page's actual spacing rhythm.
+ *
+ * Requires at least `MIN_GAP_SAMPLES` non-zero gaps and at least
+ * `MIN_ON_GRID_SHARE` coverage from the best candidate; otherwise returns
+ * `{unit: null, onGridShare: 0, offGrid: gaps}` (the *original*, unfiltered
+ * `gaps` — a caller with too little data to trust gets everything back as
+ * "off-grid" rather than a partially-filtered list) instead of a
+ * low-confidence guess. Ties are broken toward the smaller candidate — the
+ * candidates are tried in the order given and a later candidate only wins by
+ * strictly exceeding the current best share.
+ */
+function detectBaseUnit(gaps, candidates = [4, 8]) {
+    const nonZero = gaps.filter((gap) => gap !== 0);
+    if (nonZero.length < MIN_GAP_SAMPLES) {
+        return { unit: null, onGridShare: 0, offGrid: gaps };
+    }
+    let bestUnit = null;
+    let bestShare = 0;
+    let bestOffGrid = gaps;
+    for (const unit of candidates) {
+        if (unit <= 0)
+            continue;
+        const offGrid = [];
+        let onGrid = 0;
+        for (const gap of nonZero) {
+            const nearestMultiple = Math.round(gap / unit) * unit;
+            if (Math.abs(gap - nearestMultiple) <= GRID_TOLERANCE)
+                onGrid++;
+            else
+                offGrid.push(gap);
+        }
+        const share = onGrid / nonZero.length;
+        if (share > bestShare) {
+            bestShare = share;
+            bestUnit = unit;
+            bestOffGrid = offGrid;
+        }
+    }
+    if (bestUnit === null || bestShare < MIN_ON_GRID_SHARE) {
+        return { unit: null, onGridShare: 0, offGrid: gaps };
+    }
+    return { unit: bestUnit, onGridShare: bestShare, offGrid: bestOffGrid };
+}
+/** Histogram of `gaps`, each value rounded to the nearest px before being
+ * used as the key — the digest and the (future) spacing check use this to
+ * summarize "column gaps: 24×4" rather than listing every raw float. */
+function spacingStats(gaps) {
+    const distinct = {};
+    for (const gap of gaps) {
+        const key = String(Math.round(gap));
+        distinct[key] = (distinct[key] ?? 0) + 1;
+    }
+    return { distinct };
+}