@michaelmagan/dnumb 0.1.0

package/dist/digest/render.d.cts

@@ -0,0 +1,41 @@
+/**
+ * Renders a capture as the text an agent reads instead of raw JSON.
+ *
+ * The line grammar is carried over from the prototype unchanged. It survived
+ * two cold reads there and a third here, and it is the one part of this project
+ * that five registry searches found no substitute for, so it is deliberately
+ * not being redesigned:
+ *
+ * ```
+ * # dnumb digest v2 — <url> — <viewport> — <state>
+ * # 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
+ * e13 span "Task Board 1" @71,164 263x18 →10
+ * ```
+ *
+ * Two things are new in v2.
+ *
+ * **Facts are joined by element id, not by selector.** The prototype matched
+ * check findings to digest lines through a CSS selector string, which is how it
+ * shipped the Step 16 misattribution bug: two elements resolving to the same
+ * selector meant a fact landing on the wrong line. Facts here are computed from
+ * the same records the lines are, and carried on the record.
+ *
+ * **The header names the state.** Without it two captures of one URL are
+ * indistinguishable in their own headers, and the whole point of the format is
+ * to describe more than one moment of a page.
+ */
+import type { Snapshot } from "../snapshot/types.cjs";
+import type { DigestMeta, RenderDigestOptions } from "./types.cjs";
+/**
+ * The refusal surface's second line always opens with this exact prefix --
+ * the single signal a caller needs to detect `sparseCapture` from rendered
+ * text alone, without re-deriving `renderDigest`'s own gate expression a
+ * second time somewhere else (the CLI's `--json` envelope, in particular --
+ * see `src/cli.ts`). `docs/notes/07-refusal.md` §4: "Keep the single source;
+ * do not re-derive it." A rendered digest is the one place that decision is
+ * already made; this constant is how a caller reads it back off the text
+ * instead of recomputing `elements >= 20 && dropped/total >= 0.9 &&
+ * page.height <= 2` against a bundle it may not even have the same shape of.
+ */
+export declare const SPARSE_CAPTURE_MARKER = "# no layout to digest:";
+export declare function renderDigest(snapshot: Snapshot, meta: DigestMeta, options?: RenderDigestOptions): string;

package/dist/digest/render.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Renders a capture as the text an agent reads instead of raw JSON.
+ *
+ * The line grammar is carried over from the prototype unchanged. It survived
+ * two cold reads there and a third here, and it is the one part of this project
+ * that five registry searches found no substitute for, so it is deliberately
+ * not being redesigned:
+ *
+ * ```
+ * # dnumb digest v2 — <url> — <viewport> — <state>
+ * # 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
+ * e13 span "Task Board 1" @71,164 263x18 →10
+ * ```
+ *
+ * Two things are new in v2.
+ *
+ * **Facts are joined by element id, not by selector.** The prototype matched
+ * check findings to digest lines through a CSS selector string, which is how it
+ * shipped the Step 16 misattribution bug: two elements resolving to the same
+ * selector meant a fact landing on the wrong line. Facts here are computed from
+ * the same records the lines are, and carried on the record.
+ *
+ * **The header names the state.** Without it two captures of one URL are
+ * indistinguishable in their own headers, and the whole point of the format is
+ * to describe more than one moment of a page.
+ */
+import type { Snapshot } from "../snapshot/types.js";
+import type { DigestMeta, RenderDigestOptions } from "./types.js";
+/**
+ * The refusal surface's second line always opens with this exact prefix --
+ * the single signal a caller needs to detect `sparseCapture` from rendered
+ * text alone, without re-deriving `renderDigest`'s own gate expression a
+ * second time somewhere else (the CLI's `--json` envelope, in particular --
+ * see `src/cli.ts`). `docs/notes/07-refusal.md` §4: "Keep the single source;
+ * do not re-derive it." A rendered digest is the one place that decision is
+ * already made; this constant is how a caller reads it back off the text
+ * instead of recomputing `elements >= 20 && dropped/total >= 0.9 &&
+ * page.height <= 2` against a bundle it may not even have the same shape of.
+ */
+export declare const SPARSE_CAPTURE_MARKER = "# no layout to digest:";
+export declare function renderDigest(snapshot: Snapshot, meta: DigestMeta, options?: RenderDigestOptions): string;