@michaelmagan/dnumb 0.1.0 → 0.1.2

package/AGENTS.md

@@ -8,13 +8,13 @@ in a browser. Every output is text a model reads.
 `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
+at once, each still addressable by id (see [`docs/digest.md`](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).
+[`docs/digest.md`](docs/digest.md#a-truncated-heading).
 
 ```text
 e2 h1.heading "Quarterly revenue review for t…" @0,0 668x28 [overflow-x +147px; clip, ellipsis]
@@ -40,7 +40,7 @@ Stay with the screenshot for *paint* — imagery, typography, and overall visual
 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).
+pass/fail — see [`docs/digest.md`](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**
@@ -83,9 +83,9 @@ problem:
   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).
+  color`, and `q describe`, per [`docs/digest.md`](docs/digest.md#color).
 
-Full grammar, every token, in [`docs/digest.md`](https://github.com/michaelmagan/dnumb/blob/main/docs/digest.md).
+Full grammar, every token, in [`docs/digest.md`](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
@@ -96,8 +96,7 @@ 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).
+measurement read `text-overflow: ellipsis` as absolution.
 
 ## Two things that will trip you up
 
@@ -111,7 +110,7 @@ space for the ellipsis glyph and counts it in `scrollWidth`. Measured at +10px a
 +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).
+[`docs/digest.md`](docs/digest.md).
 
 ## The library surface that exists today
 
@@ -136,7 +135,7 @@ import {
 
 `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
+and [Reading a diff](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
@@ -165,16 +164,27 @@ 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`
+**Published.** `npm install --save-dev @michaelmagan/dnumb` — MIT, zero dependencies. 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
+[README § From the CLI](README.md#from-the-cli) and
+[§ Reading a diff](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).
+**Invoking it — three forms, not one.** Nothing installed yet, any package manager: `npx
+@michaelmagan/dnumb --help` (or `bunx @michaelmagan/dnumb --help`) — the zero-install form, works
+everywhere. Already a dependency — installed via `npm install`, `pnpm add`, or `bun add`, all of
+which populate `node_modules/.bin/dnumb` the same way: `npx dnumb --help` or `bunx dnumb --help`,
+either resolves the local bin regardless of which tool installed it (verified: `npx` correctly
+resolves a bun-installed bin, including under bun's isolated linker). **If a bare `npx dnumb ...` or
+`bunx dnumb ...` 404s, that means nothing is installed locally, not that the package doesn't
+exist** — both tools then resolve `dnumb` as a *package* name against the registry, and there is no
+unscoped `dnumb` package on npm (permanently blocked by npm's similarity filter); retry with the
+scoped form above, or install first: `npm install --save-dev @michaelmagan/dnumb` / `bun add -d
+@michaelmagan/dnumb`.
+
+The digest format is specified in [`docs/digest.md`](docs/digest.md), shipped alongside this file
+in the installed package — no network access needed to read it.

package/README.md

@@ -20,7 +20,7 @@ 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
+    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]
@@ -41,12 +41,13 @@ other four are, only in this one header line and the `q color` verb — naming e
 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).
+> **Status: published.** `npm install --save-dev @michaelmagan/dnumb` — MIT, zero dependencies. 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 release history is
+> [`docs/06-RELEASE.md`](docs/06-RELEASE.md).
 
 ## The idea
 
@@ -174,8 +175,23 @@ No test suite yet, or just want a bundle right now? The shortest path from a URL
 two commands:
 
 ```bash
-dnumb capture https://example.com/settings --name settings-desktop
-dnumb --from .dnumb/settings-desktop.json look
+npx @michaelmagan/dnumb capture https://example.com/settings --name settings-desktop  # no install
+npx @michaelmagan/dnumb --from .dnumb/settings-desktop.json look
+```
+
+On a bun project, `bunx` is the equivalent zero-install form: `bunx @michaelmagan/dnumb --help`.
+
+Already installed it (`npm install --save-dev @michaelmagan/dnumb`, or `bun add -d
+@michaelmagan/dnumb`)? Drop the scope — `npx dnumb` and `bunx dnumb` both resolve the local `dnumb`
+bin the same way, since npm, pnpm, and bun all populate `node_modules/.bin/dnumb` identically.
+Without a local install, either tool takes `dnumb` as a *package* name, not a bin name, and there is
+no unscoped `dnumb` package on npm (see [`docs/06-RELEASE.md` §0](docs/06-RELEASE.md)) — so a bare
+`npx dnumb` or `bunx dnumb` with nothing installed 404s.
+
+```bash
+npx dnumb capture https://example.com/settings --name settings-desktop  # after install
+npx dnumb --from .dnumb/settings-desktop.json look
+# or, in a bun project: bunx dnumb capture ...  /  bunx dnumb --from ... look
 ```
 
 `capture` launches a browser, navigates, captures, and writes `.dnumb/settings-desktop.json` —
@@ -274,7 +290,7 @@ empty body and a page that did not change would otherwise look identical.
 
 | 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 |
+| [docs/digest.md](docs/digest.md) | **The digest format.** Every token, every fact form, the fold and collapse syntax, the parser contract. Ships in the tarball |
 | [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 |

package/dist/digest/render.cjs

@@ -151,10 +151,86 @@ function edgeDistance(nodeStart, nodeSize, prevStart, prevSize) {
         return -(nodeEnd - prevStart);
     return nodeStart - prevEnd;
 }
+/**
+ * Which axis `gapToken` should measure and print, for one sibling pair.
+ *
+ * For `row` and `column` flex containers this is not a judgment call: flexbox
+ * has exactly one main axis, fixed by `flex-direction`, and every child is
+ * placed along it by the spec regardless of what the cross axis happens to
+ * measure between any two of them. `docs/digest.md`'s own pinned example
+ * (`clipped-menu.html`) is a real case where trusting the cross axis instead
+ * would have been wrong: `e5` (a dropdown flown out below the toolbar) and
+ * `e4` (a toolbar button) sit in a `[row]` container, genuinely 5px apart on
+ * y (the dropdown starts below the row, not overlapping it) and 110px
+ * overlapping on x -- the row's own axis. The declared axis wins there
+ * unconditionally, which is why this function never second-guesses `row` or
+ * `column`.
+ *
+ * `grid` is different in kind, not degree: CSS Grid is two-dimensional, and
+ * `analysis/neighbors.ts#siblingGaps` and `analysis/uniformity.ts#
+ * consecutiveGaps` already encode this ("`flow: 'grid'` has no single
+ * well-defined axis") by skipping grid containers outright for the analyses
+ * that need one global axis per container. The element line cannot skip --
+ * every non-first sibling gets a gap token -- so it asks the only question
+ * that has an honest answer for a *specific pair*: are these two boxes
+ * actually adjacent along x, along y, or is the relationship genuinely
+ * ambiguous? Two consecutive DOM-order children of a `grid-template-columns:
+ * repeat(N, ...)` row (the common case -- a stat-card row, a two-column
+ * article layout) sit at the same y with the same height and a real x gutter
+ * between them; before this function existed, `gapToken` always measured
+ * grid children vertically, so that real horizontal gutter (`ar.wikipedia.org`,
+ * real capture: a 24px column gutter between the TOC sidebar and the main
+ * content) came out as `↓-11195` and `↓-11167` -- values with the *shape* of
+ * a fabricated near-total vertical overlap, which is exactly the mechanism
+ * `docs/notes/07-refusal.md` §6 and a blind-read rater on `dashboard-
+ * defect.html`'s 4-column `stats-grid` (`↓-112`, one card's full height) both
+ * hit: a direction-agnostic negative number, printed on the one flow kind
+ * with no declared axis to check it against, read as a literal overlap
+ * claim.
+ *
+ * The rule, applied only when `flow === 'grid'`:
+ *
+ *  - One axis shows a real separation (no overlap, i.e. `>= 0`) and the
+ *    other shows overlap: the boxes are unambiguously adjacent along the
+ *    separated axis (aligned/overlapping on the other is what "in the same
+ *    row/column" looks like) -- print that axis. This is the fix for the
+ *    stat-card and Wikipedia cases above.
+ *  - Both axes show a real separation: a diagonal case with no overlap on
+ *    either axis at all, the shape of a grid-auto-flow row-wrap boundary
+ *    (last card of row N to first card of row N+1) -- the smaller of the two
+ *    magnitudes is kept, since the wrap boundary's "distance" back across the
+ *    whole row width is an artifact of printing one linear sequence for a
+ *    2-D layout, while the real row-to-row gap is usually the smaller number
+ *    and is what a reader means by "the gap to the next one".
+ *  - Both axes overlap: no separation anywhere to anchor a choice on (a
+ *    decorative full-bleed overlay sibling, e.g., `linear-app`'s `e347`) --
+ *    falls back to the same vertical default every other ambiguous flow kind
+ *    (`column`, `none`) already uses, unchanged from before this fix.
+ *
+ * None of this touches `row`, `column`, or `none`: their gap arithmetic and
+ * axis were already correct (see `edgeDistance`'s own doc comment for the
+ * direction-agnostic RTL fix), and `07-refusal.md` §6 names the fabrication
+ * as specific to grid/row-flow siblings, not flex row/column.
+ */
+function resolveGapAxis(node, previous, flow) {
+    if (flow !== 'grid')
+        return flow !== 'row';
+    const h = edgeDistance(node.rect.x, node.rect.width, previous.rect.x, previous.rect.width);
+    const v = edgeDistance(node.rect.y, node.rect.height, previous.rect.y, previous.rect.height);
+    const hSeparated = Number.isFinite(h) && h >= 0;
+    const vSeparated = Number.isFinite(v) && v >= 0;
+    if (hSeparated && !vSeparated)
+        return false;
+    if (vSeparated && !hSeparated)
+        return true;
+    if (hSeparated && vSeparated)
+        return Math.abs(v) <= Math.abs(h);
+    return true; // both overlap: no separated axis to anchor on, keep the old default.
+}
 function gapToken(node, previous, flow) {
     if (!previous)
         return '';
-    const vertical = flow !== 'row';
+    const vertical = resolveGapAxis(node, previous, flow);
     const value = vertical
         ? edgeDistance(node.rect.y, node.rect.height, previous.rect.y, previous.rect.height)
         : edgeDistance(node.rect.x, node.rect.width, previous.rect.x, previous.rect.width);

package/dist/digest/render.js

@@ -147,10 +147,86 @@ function edgeDistance(nodeStart, nodeSize, prevStart, prevSize) {
         return -(nodeEnd - prevStart);
     return nodeStart - prevEnd;
 }
+/**
+ * Which axis `gapToken` should measure and print, for one sibling pair.
+ *
+ * For `row` and `column` flex containers this is not a judgment call: flexbox
+ * has exactly one main axis, fixed by `flex-direction`, and every child is
+ * placed along it by the spec regardless of what the cross axis happens to
+ * measure between any two of them. `docs/digest.md`'s own pinned example
+ * (`clipped-menu.html`) is a real case where trusting the cross axis instead
+ * would have been wrong: `e5` (a dropdown flown out below the toolbar) and
+ * `e4` (a toolbar button) sit in a `[row]` container, genuinely 5px apart on
+ * y (the dropdown starts below the row, not overlapping it) and 110px
+ * overlapping on x -- the row's own axis. The declared axis wins there
+ * unconditionally, which is why this function never second-guesses `row` or
+ * `column`.
+ *
+ * `grid` is different in kind, not degree: CSS Grid is two-dimensional, and
+ * `analysis/neighbors.ts#siblingGaps` and `analysis/uniformity.ts#
+ * consecutiveGaps` already encode this ("`flow: 'grid'` has no single
+ * well-defined axis") by skipping grid containers outright for the analyses
+ * that need one global axis per container. The element line cannot skip --
+ * every non-first sibling gets a gap token -- so it asks the only question
+ * that has an honest answer for a *specific pair*: are these two boxes
+ * actually adjacent along x, along y, or is the relationship genuinely
+ * ambiguous? Two consecutive DOM-order children of a `grid-template-columns:
+ * repeat(N, ...)` row (the common case -- a stat-card row, a two-column
+ * article layout) sit at the same y with the same height and a real x gutter
+ * between them; before this function existed, `gapToken` always measured
+ * grid children vertically, so that real horizontal gutter (`ar.wikipedia.org`,
+ * real capture: a 24px column gutter between the TOC sidebar and the main
+ * content) came out as `↓-11195` and `↓-11167` -- values with the *shape* of
+ * a fabricated near-total vertical overlap, which is exactly the mechanism
+ * `docs/notes/07-refusal.md` §6 and a blind-read rater on `dashboard-
+ * defect.html`'s 4-column `stats-grid` (`↓-112`, one card's full height) both
+ * hit: a direction-agnostic negative number, printed on the one flow kind
+ * with no declared axis to check it against, read as a literal overlap
+ * claim.
+ *
+ * The rule, applied only when `flow === 'grid'`:
+ *
+ *  - One axis shows a real separation (no overlap, i.e. `>= 0`) and the
+ *    other shows overlap: the boxes are unambiguously adjacent along the
+ *    separated axis (aligned/overlapping on the other is what "in the same
+ *    row/column" looks like) -- print that axis. This is the fix for the
+ *    stat-card and Wikipedia cases above.
+ *  - Both axes show a real separation: a diagonal case with no overlap on
+ *    either axis at all, the shape of a grid-auto-flow row-wrap boundary
+ *    (last card of row N to first card of row N+1) -- the smaller of the two
+ *    magnitudes is kept, since the wrap boundary's "distance" back across the
+ *    whole row width is an artifact of printing one linear sequence for a
+ *    2-D layout, while the real row-to-row gap is usually the smaller number
+ *    and is what a reader means by "the gap to the next one".
+ *  - Both axes overlap: no separation anywhere to anchor a choice on (a
+ *    decorative full-bleed overlay sibling, e.g., `linear-app`'s `e347`) --
+ *    falls back to the same vertical default every other ambiguous flow kind
+ *    (`column`, `none`) already uses, unchanged from before this fix.
+ *
+ * None of this touches `row`, `column`, or `none`: their gap arithmetic and
+ * axis were already correct (see `edgeDistance`'s own doc comment for the
+ * direction-agnostic RTL fix), and `07-refusal.md` §6 names the fabrication
+ * as specific to grid/row-flow siblings, not flex row/column.
+ */
+function resolveGapAxis(node, previous, flow) {
+    if (flow !== 'grid')
+        return flow !== 'row';
+    const h = edgeDistance(node.rect.x, node.rect.width, previous.rect.x, previous.rect.width);
+    const v = edgeDistance(node.rect.y, node.rect.height, previous.rect.y, previous.rect.height);
+    const hSeparated = Number.isFinite(h) && h >= 0;
+    const vSeparated = Number.isFinite(v) && v >= 0;
+    if (hSeparated && !vSeparated)
+        return false;
+    if (vSeparated && !hSeparated)
+        return true;
+    if (hSeparated && vSeparated)
+        return Math.abs(v) <= Math.abs(h);
+    return true; // both overlap: no separated axis to anchor on, keep the old default.
+}
 function gapToken(node, previous, flow) {
     if (!previous)
         return '';
-    const vertical = flow !== 'row';
+    const vertical = resolveGapAxis(node, previous, flow);
     const value = vertical
         ? edgeDistance(node.rect.y, node.rect.height, previous.rect.y, previous.rect.height)
         : edgeDistance(node.rect.x, node.rect.width, previous.rect.x, previous.rect.width);