@michaelmagan/dnumb 0.1.0

package/dist/spec/index.cjs

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPEC_VERSION = void 0;
+/**
+ * Bumped when the capture format changes in a way a reader must know about.
+ * Independent of the package version: a patch release does not move it, and a
+ * major release does not necessarily move it either.
+ */
+exports.SPEC_VERSION = 1;

package/dist/spec/index.d.cts

@@ -0,0 +1,15 @@
+/**
+ * The interop contract: types and a version constant, zero runtime logic and
+ * zero dependencies.
+ *
+ * This exists as a subpath (`dnumb/spec`) rather than a separate package
+ * because a second implementer does not exist yet. If one appears, the move to
+ * its own package is a re-export away and nothing that imports from here breaks.
+ */
+export type { BoxSides, ClipFact, DocumentBackground, ElementRecord, NotMeasured, Rect, Snapshot, } from "../snapshot/types.cjs";
+/**
+ * Bumped when the capture format changes in a way a reader must know about.
+ * Independent of the package version: a patch release does not move it, and a
+ * major release does not necessarily move it either.
+ */
+export declare const SPEC_VERSION: 1;

package/dist/spec/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The interop contract: types and a version constant, zero runtime logic and
+ * zero dependencies.
+ *
+ * This exists as a subpath (`dnumb/spec`) rather than a separate package
+ * because a second implementer does not exist yet. If one appears, the move to
+ * its own package is a re-export away and nothing that imports from here breaks.
+ */
+export type { BoxSides, ClipFact, DocumentBackground, ElementRecord, NotMeasured, Rect, Snapshot, } from "../snapshot/types.js";
+/**
+ * Bumped when the capture format changes in a way a reader must know about.
+ * Independent of the package version: a patch release does not move it, and a
+ * major release does not necessarily move it either.
+ */
+export declare const SPEC_VERSION: 1;

package/dist/spec/index.js

@@ -0,0 +1,6 @@
+/**
+ * Bumped when the capture format changes in a way a reader must know about.
+ * Independent of the package version: a patch release does not move it, and a
+ * major release does not necessarily move it either.
+ */
+export const SPEC_VERSION = 1;

package/package.json

@@ -0,0 +1,141 @@
+{
+  "name": "@michaelmagan/dnumb",
+  "version": "0.1.0",
+  "description": "Turns a rendered page into measurements an agent can read: element geometry, overflow, clipping, and a text diff of what changed between two states.",
+  "keywords": [
+    "agent",
+    "ai-agent",
+    "playwright",
+    "layout",
+    "dom",
+    "geometry",
+    "e2e",
+    "testing",
+    "cli",
+    "accessibility",
+    "contrast"
+  ],
+  "license": "MIT",
+  "author": "Michael Magan <michael.magan92@gmail.com>",
+  "homepage": "https://github.com/michaelmagan/dnumb#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/michaelmagan/dnumb.git"
+  },
+  "bugs": {
+    "url": "https://github.com/michaelmagan/dnumb/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "AGENTS.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "pnpm@11.24.0",
+  "intent": {
+    "version": 1,
+    "repo": "michaelmagan/dnumb",
+    "docs": "https://github.com/michaelmagan/dnumb#readme"
+  },
+  "zshy": {
+    "exports": {
+      ".": "./src/index.ts",
+      "./playwright": "./src/playwright.ts",
+      "./spec": "./src/spec/index.ts",
+      "./package.json": "./package.json"
+    },
+    "bin": {
+      "dnumb": "./src/cli.ts"
+    }
+  },
+  "scripts": {
+    "build": "zshy --project tsconfig.build.json && node scripts/exports-map.mjs",
+    "postbuild": "node scripts/exports-map.mjs",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check --error-on-warnings .",
+    "format": "biome check --write .",
+    "test": "vitest run --project unit",
+    "test:browser": "vitest run --project browser",
+    "test:all": "vitest run",
+    "test:travel": "bash scripts/travel-test.sh",
+    "check:package": "publint --strict && attw --pack .",
+    "prepack": "pnpm run build",
+    "prepublishOnly": "pnpm run typecheck && pnpm run lint && pnpm run test && pnpm run test:browser && pnpm run check:package",
+    "release": "changeset publish"
+  },
+  "peerDependencies": {
+    "playwright-core": ">=1.17.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright-core": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@biomejs/biome": "^2.3.0",
+    "@changesets/cli": "^3.0.1",
+    "@types/node": "^24.0.0",
+    "playwright-core": "^1.62.1",
+    "publint": "^0.3.24",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.0",
+    "zshy": "^0.7.3"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./playwright": {
+      "import": {
+        "types": "./dist/playwright.d.ts",
+        "default": "./dist/playwright.js"
+      },
+      "require": {
+        "types": "./dist/playwright.d.cts",
+        "default": "./dist/playwright.cjs"
+      }
+    },
+    "./spec": {
+      "import": {
+        "types": "./dist/spec/index.d.ts",
+        "default": "./dist/spec/index.js"
+      },
+      "require": {
+        "types": "./dist/spec/index.d.cts",
+        "default": "./dist/spec/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "dnumb": "./dist/cli.cjs"
+  },
+  "typesVersions": {
+    "*": {
+      "playwright": [
+        "./dist/playwright.d.cts"
+      ],
+      "spec": [
+        "./dist/spec/index.d.cts"
+      ]
+    }
+  }
+}

package/skills/dnumb/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: dnumb
+description: Use when a layout or design question needs the page's real numbers instead of a screenshot — is this text truncated and by how much, does this box overflow, is this menu clipped by an ancestor, how far apart are these two elements, what moved between two states, what is at this coordinate. Captures a rendered page as element geometry plus the CSS that says what each measurement means, and renders it as a compact text digest. Load before investigating a layout bug or answering a layout question; it reports measurements and never issues a verdict.
+type: package
+---
+
+# dnumb
+
+**Design, in numbers.** A rendered page as measurements a model can read.
+
+**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`.
+
+```text
+e2 h1.heading "Quarterly revenue review for t…" @0,0 668x28 [overflow-x +147px; clip, ellipsis]
+```
+
+A heading 668px wide around 815px of content, the box clips, the clipped edge ends in an ellipsis.
+
+**Live example** (`fixture=test/fixtures/clipped-menu.html state=menu-open after=__toB line=e5`) —
+one real line out of a real capture, checked the same way.
+
+```text
+e5 nav.menu "Actions" @39,104 182x109 →-110 [clipped by e2 div; overflow:hidden, not scrollable; 103.8px below, 182x5 visible]
+```
+
+A menu overlapping the sibling before it — negative gap — clipped by its own parent's
+`overflow: hidden` with only a 5px sliver surviving. Neither line says "bug". You decide that.
+
+## Status: pre-release
+
+Not yet published to npm. The library surface below is built and tested. The CLI has a stable verb
+set — `capture`, `look`, `diff`, and `q describe|find|at|within|distance|nearest|facts|color` — worked 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 does not restate flags: run `dnumb --help` for the exhaustive, versioned list of what your
+installed copy supports, and trust it over any prose here or there.
+
+## The two-call loop
+
+In a Playwright test, or any script that has a `page`:
+
+```ts
+import { capture } from '@michaelmagan/dnumb/playwright';
+import { renderDigest } from '@michaelmagan/dnumb';
+
+await page.goto('/settings');
+const { bundle } = await capture(page, 'settings-desktop'); // writes .dnumb/settings-desktop.json
+console.log(renderDigest(bundle, { url: bundle.url, viewport: bundle.viewport, state: bundle.name }));
+```
+
+Read the digest. The header names the URL, the viewport, the capture state, and how many elements
+carry facts. Most elements get their own line; a run of repeated siblings (a list, a table body)
+folds into one summary line instead, naming each folded sibling's id and position but not its
+descendants — see [`docs/digest.md` § The fold
+line](https://github.com/michaelmagan/dnumb/blob/main/docs/digest.md#the-fold-line) before reading
+an absent element in a fold as absent from the page. Anything measurable that does not fit its box
+gets a bracketed fact on its own line.
+
+The bundle is a single self-contained JSON file. It travels: attach it to a CI report, commit it,
+send it, and answer questions about that page months later on a machine with no app and no browser.
+
+## Install
+
+```bash
+npm install --save-dev @michaelmagan/dnumb
+```
+
+`playwright-core` is an optional peer. If your e2e suite already has Playwright, you have
+everything — dnumb reuses your browsers and never downloads its own. If it does not, everything
+downstream of a saved bundle still works with no browser at all.
+
+## Read this before you use the output
+
+**Facts come with counter-facts, and a fact is not a verdict.** The same number means different
+things depending on the CSS beside it:
+
+**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]   truncated text
+[overflow-x +227px; clip, wraps]      the text wrapped; this is height, not truncation
+[overflow-x +90px; scroll, wraps]     a scroll region working as intended
+```
+
+Report the measurement *and* the consequence tokens, and say which one your conclusion rests on.
+Never report a bare number as a bug. And do not read an absence of facts as "the page is fine" —
+this tool does not measure typography or alignment at all, and where it does measure color and
+contrast, it never says whether a ratio is good enough — that threshold lives in the reader.
+
+Five kinds of fact exist in total — `overflow-x`, `overflow-y`, `zero-box`, `clipped`, and `color`
+(the one that never prints inline on an element line — only in the digest's `# colors:` header and
+`q color`) — one line each on what the measurement *is* in
+[AGENTS.md](https://github.com/michaelmagan/dnumb/blob/main/AGENTS.md#facts-with-counter-facts),
+full grammar in
+[`docs/digest.md`](https://github.com/michaelmagan/dnumb/blob/main/docs/digest.md#color).
+
+**Element ids are stable within one capture only.** `e13` is an index in capture order, not a DOM
+id. Inserting one element earlier in the document shifts every id after it. Never carry an id
+between captures and never write one into a test expectation; match on the test id, the accessible
+name, or the role.
+
+**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, scaling with the font. When a line says `ellipsis`, the number is an
+upper bound on the hidden content, not an exact width. Do not subtract a constant.
+
+**`# facts: N elements carry facts` in the header can be larger than the facts `look` prints.**
+Folding and the line budget hide facts from the body — a folded sibling's own `[...]` bracket
+never shows, only its representative's does — without shrinking that count. `q facts --limit 0`
+(the default `--limit` is 50) lists every fact-carrying element, one per line, unaffected by
+folding or the budget. Reach for it whenever the header's count and what `look` shows disagree, or
+whenever a claim depends on having seen *all* the facts, not just the ones still on-screen.
+
+## What it costs
+
+Measured 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 blind
+experiment, vision alone reported 4 fabricated findings on a provably clean page and 10 on
+replication; both tool-grounded arms reported zero, twice.
+
+Spend a round-trip when a visual impression needs checking. Do not sweep a page with it.
+
+## Full library surface
+
+`capture`, `renderDigest`, `parseDigestLine`, `diffCaptures`, `factsFor`, `factsForAll`,
+`renderFacts`, `clipFactFor`, `attachClipFacts`, `formatNotMeasured`, `buildBundle`, `parseBundle`,
+`serializeBundle`, `SPEC_VERSION`, and the geometry primitives `intersect` / `contains` /
+`gapAlong` / `area` / `center`. Types alone, with no runtime code, from `@michaelmagan/dnumb/spec`.
+
+The digest grammar — every token, every fact form, the fold and collapse syntax, and the parser
+contract — is specified in
+[`docs/digest.md`](https://github.com/michaelmagan/dnumb/blob/main/docs/digest.md). `diffCaptures`
+and the CLI's `diff` verb share one grammar, worked in
+[README § Reading a diff](https://github.com/michaelmagan/dnumb/blob/main/README.md#reading-a-diff).