@michaelmagan/dnumb 0.1.1 → 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
@@ -169,8 +168,8 @@ does not.
 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.
@@ -187,7 +186,5 @@ unscoped `dnumb` package on npm (permanently blocked by npm's similarity filter)
 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`](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).
+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

@@ -290,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);