@michaelmagan/dnumb 0.1.0

package/dist/digest/types.cjs

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Shared types for `src/digest/*`.
+ *
+ * The digest reads `ElementRecord[]` and the facts derived from them, and
+ * nothing else — no CLI types, no Playwright, no check engine. The prototype
+ * enforced the same boundary and it is the reason the digest and the diff read
+ * one geometry implementation rather than two that quietly diverge.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/digest/types.d.cts

@@ -0,0 +1,86 @@
+/**
+ * Shared types for `src/digest/*`.
+ *
+ * The digest reads `ElementRecord[]` and the facts derived from them, and
+ * nothing else — no CLI types, no Playwright, no check engine. The prototype
+ * enforced the same boundary and it is the reason the digest and the diff read
+ * one geometry implementation rather than two that quietly diverge.
+ */
+export interface DigestMeta {
+    url: string;
+    viewport: {
+        name?: string;
+        width: number;
+        height: number;
+    };
+    /**
+     * The state this capture was taken in — `menu-open`, `dark`, `after-submit`.
+     * New in v2, and the reason the format can describe more than one moment of a
+     * page: without it, two captures of the same URL are indistinguishable in
+     * their own headers.
+     */
+    state?: string;
+    capturedAt?: string;
+    /**
+     * Which capture path produced this snapshot. Surfaced in the header because
+     * `cdp` and `walk` do not see the same page on any page using shadow DOM —
+     * `walk` cannot enter a shadow root at all, `cdp` flattens one in — so a
+     * reader comparing two digests needs to know which capability tier each one
+     * came from, not just what it found.
+     */
+    strategy?: 'cdp' | 'walk';
+    /**
+     * True when `strategy` is `'walk'` only because the CDP fast path was tried
+     * on a Chromium page and its own protocol call failed — an unplanned
+     * downgrade, not a deliberate portable capture. See
+     * `CaptureResult.cdpFellBack`.
+     */
+    cdpFellBack?: boolean;
+}
+export interface RenderDigestOptions {
+    /**
+     * Soft target for total body characters. Default 32768 (~11.5K tokens at
+     * the corpus's measured 2.84 chars/token) -- see `DEFAULT_BUDGET_CHARS`'s
+     * own doc comment in `digest/render.ts` and `docs/notes/06-budget.md` §2
+     * and §5 for why characters replaced lines as the meter, and why that
+     * number. Exceeding it makes folding progressively more aggressive, then
+     * collapses subtrees leaf-up (`collapseCandidates`, shallowest subtree
+     * first), rather than truncating -- a digest that stops mid-tree is worse
+     * than one that summarises the repetitive parts. Not applied under
+     * `--focus`/`options.focus` -- see that option's doc comment.
+     */
+    budgetChars?: number;
+    /**
+     * Soft target for total body *lines* -- the budget's original unit, before
+     * `docs/notes/06-budget.md` replaced it with `budgetChars` (lines predict
+     * a reader's real token cost within a factor of ~15 on ordinary bodies,
+     * characters within ±20%). Still honored when a caller passes it
+     * explicitly: `src/cli.ts`'s `--budget` flag and `src/query.ts`'s
+     * `QueryOptions` both still type and forward it, and this package is not
+     * the sole owner of either tonight, so this stays a real, working option
+     * rather than a silently-dropped one. It carries no default of its own,
+     * though -- a bare `renderDigest(snapshot, meta)` call is bounded by
+     * `budgetChars` alone -- and when both are set, the render stays under
+     * whichever limit is stricter.
+     */
+    budgetLines?: number;
+    /**
+     * Scope to one element's subtree, by element id or tag. Neither budget
+     * option applies once focused: stage 2 (fold) and stage 3 (collapse) are
+     * both disabled entirely under `--focus`, so a focused render can exceed
+     * `budgetChars`/`budgetLines` when the focused subtree itself is large.
+     * That is deliberate, not an oversight -- see `renderDigest`'s own doc
+     * comment on the stage-3 loop for why re-applying a budget-driven collapse
+     * inside an already-focused subtree would reopen the exact non-convergence
+     * bug disabling it there was written to fix (chasing a `(--focus <id>)`
+     * hint that lands on another partial, re-collapsed view of the same
+     * subtree instead of the full content the caller asked for).
+     */
+    focus?: string;
+    /**
+     * Emit the edge-cluster histogram header. Off by default: it is a page-wide
+     * summary that costs several dense lines and answers a question most captures
+     * are not asking.
+     */
+    edges?: boolean;
+}

package/dist/digest/types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Shared types for `src/digest/*`.
+ *
+ * The digest reads `ElementRecord[]` and the facts derived from them, and
+ * nothing else — no CLI types, no Playwright, no check engine. The prototype
+ * enforced the same boundary and it is the reason the digest and the diff read
+ * one geometry implementation rather than two that quietly diverge.
+ */
+export interface DigestMeta {
+    url: string;
+    viewport: {
+        name?: string;
+        width: number;
+        height: number;
+    };
+    /**
+     * The state this capture was taken in — `menu-open`, `dark`, `after-submit`.
+     * New in v2, and the reason the format can describe more than one moment of a
+     * page: without it, two captures of the same URL are indistinguishable in
+     * their own headers.
+     */
+    state?: string;
+    capturedAt?: string;
+    /**
+     * Which capture path produced this snapshot. Surfaced in the header because
+     * `cdp` and `walk` do not see the same page on any page using shadow DOM —
+     * `walk` cannot enter a shadow root at all, `cdp` flattens one in — so a
+     * reader comparing two digests needs to know which capability tier each one
+     * came from, not just what it found.
+     */
+    strategy?: 'cdp' | 'walk';
+    /**
+     * True when `strategy` is `'walk'` only because the CDP fast path was tried
+     * on a Chromium page and its own protocol call failed — an unplanned
+     * downgrade, not a deliberate portable capture. See
+     * `CaptureResult.cdpFellBack`.
+     */
+    cdpFellBack?: boolean;
+}
+export interface RenderDigestOptions {
+    /**
+     * Soft target for total body characters. Default 32768 (~11.5K tokens at
+     * the corpus's measured 2.84 chars/token) -- see `DEFAULT_BUDGET_CHARS`'s
+     * own doc comment in `digest/render.ts` and `docs/notes/06-budget.md` §2
+     * and §5 for why characters replaced lines as the meter, and why that
+     * number. Exceeding it makes folding progressively more aggressive, then
+     * collapses subtrees leaf-up (`collapseCandidates`, shallowest subtree
+     * first), rather than truncating -- a digest that stops mid-tree is worse
+     * than one that summarises the repetitive parts. Not applied under
+     * `--focus`/`options.focus` -- see that option's doc comment.
+     */
+    budgetChars?: number;
+    /**
+     * Soft target for total body *lines* -- the budget's original unit, before
+     * `docs/notes/06-budget.md` replaced it with `budgetChars` (lines predict
+     * a reader's real token cost within a factor of ~15 on ordinary bodies,
+     * characters within ±20%). Still honored when a caller passes it
+     * explicitly: `src/cli.ts`'s `--budget` flag and `src/query.ts`'s
+     * `QueryOptions` both still type and forward it, and this package is not
+     * the sole owner of either tonight, so this stays a real, working option
+     * rather than a silently-dropped one. It carries no default of its own,
+     * though -- a bare `renderDigest(snapshot, meta)` call is bounded by
+     * `budgetChars` alone -- and when both are set, the render stays under
+     * whichever limit is stricter.
+     */
+    budgetLines?: number;
+    /**
+     * Scope to one element's subtree, by element id or tag. Neither budget
+     * option applies once focused: stage 2 (fold) and stage 3 (collapse) are
+     * both disabled entirely under `--focus`, so a focused render can exceed
+     * `budgetChars`/`budgetLines` when the focused subtree itself is large.
+     * That is deliberate, not an oversight -- see `renderDigest`'s own doc
+     * comment on the stage-3 loop for why re-applying a budget-driven collapse
+     * inside an already-focused subtree would reopen the exact non-convergence
+     * bug disabling it there was written to fix (chasing a `(--focus <id>)`
+     * hint that lands on another partial, re-collapsed view of the same
+     * subtree instead of the full content the caller asked for).
+     */
+    focus?: string;
+    /**
+     * Emit the edge-cluster histogram header. Off by default: it is a page-wide
+     * summary that costs several dense lines and answers a question most captures
+     * are not asking.
+     */
+    edges?: boolean;
+}

package/dist/digest/types.js

@@ -0,0 +1,9 @@
+/**
+ * Shared types for `src/digest/*`.
+ *
+ * The digest reads `ElementRecord[]` and the facts derived from them, and
+ * nothing else — no CLI types, no Playwright, no check engine. The prototype
+ * enforced the same boundary and it is the reason the digest and the diff read
+ * one geometry implementation rather than two that quietly diverge.
+ */
+export {};

package/dist/index.cjs

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * Public library entrypoint.
+ *
+ * The capture bundle, not the browser session, is the load-bearing object here.
+ * Everything in this package is a pure function over `ElementRecord[]` plus a
+ * thin host that produces them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPEC_VERSION = exports.formatNotMeasured = exports.renderFacts = exports.factsForAll = exports.factsFor = exports.toHex = exports.resolveBackdrop = exports.renderColorFact = exports.relativeLuminance = exports.parseCssColor = exports.groupColorFacts = exports.detectOverlay = exports.contrastRatio = exports.colorFactsForAll = exports.colorFactFor = exports.backdropLabel = exports.collectSnapshot = exports.clipFactFor = exports.attachClipFacts = exports.capture = exports.viewportOf = exports.isCDPCapable = exports.SPARSE_CAPTURE_MARKER = exports.renderDigest = exports.parseDigestLine = exports.renderDiff = exports.prepare = exports.match = exports.diffCaptures = exports.computeChanges = exports.serializeBundle = exports.parseBundle = exports.buildBundle = exports.BundleFormatError = exports.intersect = exports.gapAlong = exports.contains = exports.center = exports.area = void 0;
+var geometry_js_1 = require("./analysis/geometry.cjs");
+Object.defineProperty(exports, "area", { enumerable: true, get: function () { return geometry_js_1.area; } });
+Object.defineProperty(exports, "center", { enumerable: true, get: function () { return geometry_js_1.center; } });
+Object.defineProperty(exports, "contains", { enumerable: true, get: function () { return geometry_js_1.contains; } });
+Object.defineProperty(exports, "gapAlong", { enumerable: true, get: function () { return geometry_js_1.gapAlong; } });
+Object.defineProperty(exports, "intersect", { enumerable: true, get: function () { return geometry_js_1.intersect; } });
+var bundle_js_1 = require("./bundle.cjs");
+Object.defineProperty(exports, "BundleFormatError", { enumerable: true, get: function () { return bundle_js_1.BundleFormatError; } });
+Object.defineProperty(exports, "buildBundle", { enumerable: true, get: function () { return bundle_js_1.buildBundle; } });
+Object.defineProperty(exports, "parseBundle", { enumerable: true, get: function () { return bundle_js_1.parseBundle; } });
+Object.defineProperty(exports, "serializeBundle", { enumerable: true, get: function () { return bundle_js_1.serializeBundle; } });
+var index_js_1 = require("./diff/index.cjs");
+Object.defineProperty(exports, "computeChanges", { enumerable: true, get: function () { return index_js_1.computeChanges; } });
+Object.defineProperty(exports, "diffCaptures", { enumerable: true, get: function () { return index_js_1.diffCaptures; } });
+Object.defineProperty(exports, "match", { enumerable: true, get: function () { return index_js_1.match; } });
+Object.defineProperty(exports, "prepare", { enumerable: true, get: function () { return index_js_1.prepare; } });
+Object.defineProperty(exports, "renderDiff", { enumerable: true, get: function () { return index_js_1.renderDiff; } });
+var index_js_2 = require("./digest/index.cjs");
+Object.defineProperty(exports, "parseDigestLine", { enumerable: true, get: function () { return index_js_2.parseDigestLine; } });
+Object.defineProperty(exports, "renderDigest", { enumerable: true, get: function () { return index_js_2.renderDigest; } });
+Object.defineProperty(exports, "SPARSE_CAPTURE_MARKER", { enumerable: true, get: function () { return index_js_2.SPARSE_CAPTURE_MARKER; } });
+var page_js_1 = require("./page.cjs");
+Object.defineProperty(exports, "isCDPCapable", { enumerable: true, get: function () { return page_js_1.isCDPCapable; } });
+Object.defineProperty(exports, "viewportOf", { enumerable: true, get: function () { return page_js_1.viewportOf; } });
+var capture_js_1 = require("./snapshot/capture.cjs");
+Object.defineProperty(exports, "capture", { enumerable: true, get: function () { return capture_js_1.capture; } });
+var clip_js_1 = require("./snapshot/clip.cjs");
+Object.defineProperty(exports, "attachClipFacts", { enumerable: true, get: function () { return clip_js_1.attachClipFacts; } });
+Object.defineProperty(exports, "clipFactFor", { enumerable: true, get: function () { return clip_js_1.clipFactFor; } });
+var collect_js_1 = require("./snapshot/collect.cjs");
+Object.defineProperty(exports, "collectSnapshot", { enumerable: true, get: function () { return collect_js_1.collectSnapshot; } });
+var color_js_1 = require("./snapshot/color.cjs");
+Object.defineProperty(exports, "backdropLabel", { enumerable: true, get: function () { return color_js_1.backdropLabel; } });
+Object.defineProperty(exports, "colorFactFor", { enumerable: true, get: function () { return color_js_1.colorFactFor; } });
+Object.defineProperty(exports, "colorFactsForAll", { enumerable: true, get: function () { return color_js_1.colorFactsForAll; } });
+Object.defineProperty(exports, "contrastRatio", { enumerable: true, get: function () { return color_js_1.contrastRatio; } });
+Object.defineProperty(exports, "detectOverlay", { enumerable: true, get: function () { return color_js_1.detectOverlay; } });
+Object.defineProperty(exports, "groupColorFacts", { enumerable: true, get: function () { return color_js_1.groupColorFacts; } });
+Object.defineProperty(exports, "parseCssColor", { enumerable: true, get: function () { return color_js_1.parseCssColor; } });
+Object.defineProperty(exports, "relativeLuminance", { enumerable: true, get: function () { return color_js_1.relativeLuminance; } });
+Object.defineProperty(exports, "renderColorFact", { enumerable: true, get: function () { return color_js_1.renderColorFact; } });
+Object.defineProperty(exports, "resolveBackdrop", { enumerable: true, get: function () { return color_js_1.resolveBackdrop; } });
+Object.defineProperty(exports, "toHex", { enumerable: true, get: function () { return color_js_1.toHex; } });
+var facts_js_1 = require("./snapshot/facts.cjs");
+Object.defineProperty(exports, "factsFor", { enumerable: true, get: function () { return facts_js_1.factsFor; } });
+Object.defineProperty(exports, "factsForAll", { enumerable: true, get: function () { return facts_js_1.factsForAll; } });
+Object.defineProperty(exports, "renderFacts", { enumerable: true, get: function () { return facts_js_1.renderFacts; } });
+var not_measured_js_1 = require("./snapshot/not-measured.cjs");
+Object.defineProperty(exports, "formatNotMeasured", { enumerable: true, get: function () { return not_measured_js_1.formatNotMeasured; } });
+var index_js_3 = require("./spec/index.cjs");
+Object.defineProperty(exports, "SPEC_VERSION", { enumerable: true, get: function () { return index_js_3.SPEC_VERSION; } });

package/dist/index.d.cts

@@ -0,0 +1,27 @@
+/**
+ * Public library entrypoint.
+ *
+ * The capture bundle, not the browser session, is the load-bearing object here.
+ * Everything in this package is a pure function over `ElementRecord[]` plus a
+ * thin host that produces them.
+ */
+export { area, center, contains, gapAlong, intersect } from "./analysis/geometry.cjs";
+export type { BuildBundleOptions, Bundle } from "./bundle.cjs";
+export { BundleFormatError, buildBundle, parseBundle, serializeBundle } from "./bundle.cjs";
+export type { BoxDelta, Change, ChangeKind, DiffCapturesOptions, DiffMeta, DiffOptions, DiffResult, Match, Prepared, } from "./diff/index.cjs";
+export { computeChanges, diffCaptures, match, prepare, renderDiff } from "./diff/index.cjs";
+export type { DigestMeta, ParsedElementLine, ParsedLine, RenderDigestOptions, } from "./digest/index.cjs";
+export { parseDigestLine, renderDigest, SPARSE_CAPTURE_MARKER } from "./digest/index.cjs";
+export type { CDPCapablePage, CDPSessionLike, PageLike } from "./page.cjs";
+export { isCDPCapable, viewportOf } from "./page.cjs";
+export type { CaptureOptions, CaptureResult } from "./snapshot/capture.cjs";
+export { capture } from "./snapshot/capture.cjs";
+export { attachClipFacts, clipFactFor } from "./snapshot/clip.cjs";
+export { collectSnapshot } from "./snapshot/collect.cjs";
+export type { Backdrop, BackdropLayer, ColorFact, ColorPair, ParsedColor, RatioReason, ResolvedBackdrop, RGBA, } from "./snapshot/color.cjs";
+export { backdropLabel, colorFactFor, colorFactsForAll, contrastRatio, detectOverlay, groupColorFacts, parseCssColor, relativeLuminance, renderColorFact, resolveBackdrop, toHex, } from "./snapshot/color.cjs";
+export type { Fact, FactKind } from "./snapshot/facts.cjs";
+export { factsFor, factsForAll, renderFacts } from "./snapshot/facts.cjs";
+export { formatNotMeasured } from "./snapshot/not-measured.cjs";
+export type { BoxSides, ClipFact, ElementRecord, NotMeasured, Rect, Snapshot, } from "./snapshot/types.cjs";
+export { SPEC_VERSION } from "./spec/index.cjs";

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Public library entrypoint.
+ *
+ * The capture bundle, not the browser session, is the load-bearing object here.
+ * Everything in this package is a pure function over `ElementRecord[]` plus a
+ * thin host that produces them.
+ */
+export { area, center, contains, gapAlong, intersect } from "./analysis/geometry.js";
+export type { BuildBundleOptions, Bundle } from "./bundle.js";
+export { BundleFormatError, buildBundle, parseBundle, serializeBundle } from "./bundle.js";
+export type { BoxDelta, Change, ChangeKind, DiffCapturesOptions, DiffMeta, DiffOptions, DiffResult, Match, Prepared, } from "./diff/index.js";
+export { computeChanges, diffCaptures, match, prepare, renderDiff } from "./diff/index.js";
+export type { DigestMeta, ParsedElementLine, ParsedLine, RenderDigestOptions, } from "./digest/index.js";
+export { parseDigestLine, renderDigest, SPARSE_CAPTURE_MARKER } from "./digest/index.js";
+export type { CDPCapablePage, CDPSessionLike, PageLike } from "./page.js";
+export { isCDPCapable, viewportOf } from "./page.js";
+export type { CaptureOptions, CaptureResult } from "./snapshot/capture.js";
+export { capture } from "./snapshot/capture.js";
+export { attachClipFacts, clipFactFor } from "./snapshot/clip.js";
+export { collectSnapshot } from "./snapshot/collect.js";
+export type { Backdrop, BackdropLayer, ColorFact, ColorPair, ParsedColor, RatioReason, ResolvedBackdrop, RGBA, } from "./snapshot/color.js";
+export { backdropLabel, colorFactFor, colorFactsForAll, contrastRatio, detectOverlay, groupColorFacts, parseCssColor, relativeLuminance, renderColorFact, resolveBackdrop, toHex, } from "./snapshot/color.js";
+export type { Fact, FactKind } from "./snapshot/facts.js";
+export { factsFor, factsForAll, renderFacts } from "./snapshot/facts.js";
+export { formatNotMeasured } from "./snapshot/not-measured.js";
+export type { BoxSides, ClipFact, ElementRecord, NotMeasured, Rect, Snapshot, } from "./snapshot/types.js";
+export { SPEC_VERSION } from "./spec/index.js";

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * Public library entrypoint.
+ *
+ * The capture bundle, not the browser session, is the load-bearing object here.
+ * Everything in this package is a pure function over `ElementRecord[]` plus a
+ * thin host that produces them.
+ */
+export { area, center, contains, gapAlong, intersect } from "./analysis/geometry.js";
+export { BundleFormatError, buildBundle, parseBundle, serializeBundle } from "./bundle.js";
+export { computeChanges, diffCaptures, match, prepare, renderDiff } from "./diff/index.js";
+export { parseDigestLine, renderDigest, SPARSE_CAPTURE_MARKER } from "./digest/index.js";
+export { isCDPCapable, viewportOf } from "./page.js";
+export { capture } from "./snapshot/capture.js";
+export { attachClipFacts, clipFactFor } from "./snapshot/clip.js";
+export { collectSnapshot } from "./snapshot/collect.js";
+export { backdropLabel, colorFactFor, colorFactsForAll, contrastRatio, detectOverlay, groupColorFacts, parseCssColor, relativeLuminance, renderColorFact, resolveBackdrop, toHex, } from "./snapshot/color.js";
+export { factsFor, factsForAll, renderFacts } from "./snapshot/facts.js";
+export { formatNotMeasured } from "./snapshot/not-measured.js";
+export { SPEC_VERSION } from "./spec/index.js";

package/dist/page.cjs

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * The driver interface, defined structurally so the core of this package needs
+ * no Playwright at all.
+ *
+ * A caller passes whatever `Page` they already have — Playwright's, or anything
+ * that answers `evaluate`. `playwright-core` is an *optional* peer precisely so
+ * that a consumer who never captures live (offline `dnumb --from <bundle>`)
+ * pays nothing for it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCDPCapable = isCDPCapable;
+exports.viewportOf = viewportOf;
+function isCDPCapable(page) {
+    const context = page.context;
+    if (typeof context !== 'function')
+        return false;
+    try {
+        return typeof context.call(page)?.newCDPSession === 'function';
+    }
+    catch {
+        // Some drivers throw rather than returning a context. Not CDP-capable.
+        return false;
+    }
+}
+/**
+ * The viewport, read from inside the page.
+ *
+ * Playwright's `page.viewportSize()` returns **null** over `connectOverCDP`,
+ * which is exactly the mode the interactive path uses — so it cannot be the
+ * source of truth. `innerWidth`/`innerHeight` are always right.
+ */
+async function viewportOf(page) {
+    return page.evaluate(() => ({ width: window.innerWidth, height: window.innerHeight }));
+}

package/dist/page.d.cts

@@ -0,0 +1,40 @@
+/**
+ * The driver interface, defined structurally so the core of this package needs
+ * no Playwright at all.
+ *
+ * A caller passes whatever `Page` they already have — Playwright's, or anything
+ * that answers `evaluate`. `playwright-core` is an *optional* peer precisely so
+ * that a consumer who never captures live (offline `dnumb --from <bundle>`)
+ * pays nothing for it.
+ */
+/** The minimum a page must answer for the portable capture path. */
+export interface PageLike {
+    evaluate<R>(pageFunction: () => R): Promise<R>;
+}
+/** A Chrome DevTools Protocol session. Chromium only. */
+export interface CDPSessionLike {
+    send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    detach(): Promise<void>;
+}
+/**
+ * A page that can open a CDP session. Chromium only, and the shape is loose on
+ * purpose: `newCDPSession` takes the page itself, and we do not want this
+ * package's types to depend on Playwright's.
+ */
+export interface CDPCapablePage extends PageLike {
+    context(): {
+        newCDPSession(page: unknown): Promise<CDPSessionLike>;
+    };
+}
+export declare function isCDPCapable(page: PageLike): page is CDPCapablePage;
+/**
+ * The viewport, read from inside the page.
+ *
+ * Playwright's `page.viewportSize()` returns **null** over `connectOverCDP`,
+ * which is exactly the mode the interactive path uses — so it cannot be the
+ * source of truth. `innerWidth`/`innerHeight` are always right.
+ */
+export declare function viewportOf(page: PageLike): Promise<{
+    width: number;
+    height: number;
+}>;

package/dist/page.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The driver interface, defined structurally so the core of this package needs
+ * no Playwright at all.
+ *
+ * A caller passes whatever `Page` they already have — Playwright's, or anything
+ * that answers `evaluate`. `playwright-core` is an *optional* peer precisely so
+ * that a consumer who never captures live (offline `dnumb --from <bundle>`)
+ * pays nothing for it.
+ */
+/** The minimum a page must answer for the portable capture path. */
+export interface PageLike {
+    evaluate<R>(pageFunction: () => R): Promise<R>;
+}
+/** A Chrome DevTools Protocol session. Chromium only. */
+export interface CDPSessionLike {
+    send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    detach(): Promise<void>;
+}
+/**
+ * A page that can open a CDP session. Chromium only, and the shape is loose on
+ * purpose: `newCDPSession` takes the page itself, and we do not want this
+ * package's types to depend on Playwright's.
+ */
+export interface CDPCapablePage extends PageLike {
+    context(): {
+        newCDPSession(page: unknown): Promise<CDPSessionLike>;
+    };
+}
+export declare function isCDPCapable(page: PageLike): page is CDPCapablePage;
+/**
+ * The viewport, read from inside the page.
+ *
+ * Playwright's `page.viewportSize()` returns **null** over `connectOverCDP`,
+ * which is exactly the mode the interactive path uses — so it cannot be the
+ * source of truth. `innerWidth`/`innerHeight` are always right.
+ */
+export declare function viewportOf(page: PageLike): Promise<{
+    width: number;
+    height: number;
+}>;

package/dist/page.js

@@ -0,0 +1,31 @@
+/**
+ * The driver interface, defined structurally so the core of this package needs
+ * no Playwright at all.
+ *
+ * A caller passes whatever `Page` they already have — Playwright's, or anything
+ * that answers `evaluate`. `playwright-core` is an *optional* peer precisely so
+ * that a consumer who never captures live (offline `dnumb --from <bundle>`)
+ * pays nothing for it.
+ */
+export function isCDPCapable(page) {
+    const context = page.context;
+    if (typeof context !== 'function')
+        return false;
+    try {
+        return typeof context.call(page)?.newCDPSession === 'function';
+    }
+    catch {
+        // Some drivers throw rather than returning a context. Not CDP-capable.
+        return false;
+    }
+}
+/**
+ * The viewport, read from inside the page.
+ *
+ * Playwright's `page.viewportSize()` returns **null** over `connectOverCDP`,
+ * which is exactly the mode the interactive path uses — so it cannot be the
+ * source of truth. `innerWidth`/`innerHeight` are always right.
+ */
+export async function viewportOf(page) {
+    return page.evaluate(() => ({ width: window.innerWidth, height: window.innerHeight }));
+}

package/dist/playwright.cjs

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_OUTPUT_DIR = void 0;
+exports.safeName = safeName;
+exports.bundlePath = bundlePath;
+exports.writeBundle = writeBundle;
+exports.capture = capture;
+/**
+ * `dnumb/playwright` — one import and one call inside a suite that already has
+ * a running app, an authenticated session, and a `page` in scope.
+ *
+ * This is the wedge: the cost of a capture has to be a single line in a test
+ * someone already wrote, or the bundle never gets produced and nothing
+ * downstream of it matters.
+ *
+ * Nothing here imports Playwright, not even as a type. `playwright-core` is an
+ * *optional* peer, so a `import type { Page } from 'playwright-core'` in this
+ * file would break typechecking for a consumer who installed dnumb for the
+ * offline `--from <bundle>` path alone. The interfaces are structural instead,
+ * and a real `Page` / `TestInfo` satisfies them by shape.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const bundle_js_1 = require("./bundle.cjs");
+const capture_js_1 = require("./snapshot/capture.cjs");
+/** Mirrors Playwright's own `.playwright-artifacts` habit: hidden, gitignorable, per-repo. */
+exports.DEFAULT_OUTPUT_DIR = '.dnumb';
+/** Everything a filename can carry without quoting on any of the three platforms. */
+const UNSAFE = /[^a-zA-Z0-9._-]+/g;
+/** ext4 and APFS both cap a name at 255 bytes; leave room for the extension. */
+const MAX_NAME = 120;
+/**
+ * A capture name is caller-chosen text that becomes a path segment, so it is
+ * the one untrusted input here. Separators collapse into `-` rather than being
+ * rejected, because `settings/desktop` is a reasonable thing to type and
+ * failing a test over it would be hostile — but a leading run of dots or dashes
+ * is stripped outright, which is what turns `../../etc/passwd` into
+ * `etc-passwd` instead of a traversal.
+ */
+function safeName(name) {
+    const flat = name
+        .trim()
+        .replace(UNSAFE, '-')
+        .replace(/^[-.]+/, '')
+        .replace(/[-.]+$/, '');
+    if (!flat) {
+        throw new Error(`dnumb: capture name ${JSON.stringify(name)} has no filesystem-safe characters in it. ` +
+            'Names become filenames; use letters, digits, "." "_" or "-".');
+    }
+    return flat.slice(0, MAX_NAME);
+}
+/** Where `writeBundle` puts a bundle of this name. Exported so a caller can predict it. */
+function bundlePath(dir, name) {
+    return (0, node_path_1.join)(dir, `${safeName(name)}.json`);
+}
+/**
+ * The bundle keeps the caller's name verbatim — it is the state label the
+ * digest header prints — and only the *path* is sanitized. Two names that
+ * differ solely in punctuation therefore land on one file: `settings/desktop`
+ * and `settings-desktop` both write `settings-desktop.json`.
+ *
+ * Re-capturing the same name overwrites, which is what a test re-run should do.
+ * A *different* name landing on an existing file is a collision, and silently
+ * discarding one of two captures a suite meant to keep is the kind of data loss
+ * that gets noticed weeks later, on the run that mattered. So that case throws,
+ * and the message names both captures and the fix.
+ */
+function writeBundle(bundle, dir = exports.DEFAULT_OUTPUT_DIR) {
+    const path = bundlePath(dir, bundle.name);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+    if ((0, node_fs_1.existsSync)(path)) {
+        const existing = readExistingName(path);
+        if (existing !== null && existing !== bundle.name) {
+            throw new Error(`dnumb: capture ${JSON.stringify(bundle.name)} and capture ${JSON.stringify(existing)} ` +
+                `both write to ${path}, because names become filenames. Rename one of them.`);
+        }
+    }
+    (0, node_fs_1.writeFileSync)(path, (0, bundle_js_1.serializeBundle)(bundle), 'utf8');
+    return path;
+}
+/**
+ * The `name` of the bundle already at `path`, or `null` if it cannot be read as
+ * one. Unreadable is not a collision — an unrelated file in the output
+ * directory should not stop a capture — so it falls through to the overwrite.
+ */
+function readExistingName(path) {
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+        if (typeof parsed !== 'object' || parsed === null)
+            return null;
+        const name = parsed.name;
+        return typeof name === 'string' ? name : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Capture `page` as a bundle on disk.
+ *
+ * ```ts
+ * import { capture } from '@michaelmagan/dnumb/playwright';
+ *
+ * test('settings page', async ({ page }, testInfo) => {
+ *   await page.goto('/settings');
+ *   await capture(page, 'settings-desktop', { testInfo });
+ * });
+ * ```
+ */
+async function capture(page, name, options = {}) {
+    const dir = options.outputDir ?? exports.DEFAULT_OUTPUT_DIR;
+    // Fail on an unusable name before spending a capture on it.
+    safeName(name);
+    const result = await (0, capture_js_1.capture)(page, options.strategy ? { strategy: options.strategy } : {});
+    // The URL is read from inside the page rather than taken from the caller for
+    // the same reason the viewport is (`page.viewportSize()` is null over
+    // `connectOverCDP`): the page is the only thing that knows where it ended up
+    // after redirects, and a bundle that names the URL the test *asked* for is a
+    // bundle that lies six months later.
+    const url = await page.evaluate(() => location.href);
+    const bundle = (0, bundle_js_1.buildBundle)(result, {
+        name,
+        url,
+        capturedAt: new Date().toISOString(),
+        ...(options.viewportName ? { viewportName: options.viewportName } : {}),
+        ...(options.labels ? { labels: options.labels } : {}),
+    });
+    const path = writeBundle(bundle, dir);
+    if (options.testInfo) {
+        // `body`, not `path`: the attachment has to survive the output directory
+        // being cleaned between the run and the report being read in CI.
+        await options.testInfo.attach(`${safeName(name)}.dnumb.json`, {
+            body: (0, bundle_js_1.serializeBundle)(bundle),
+            contentType: 'application/json',
+        });
+    }
+    return { bundle, path };
+}