@michaelmagan/dnumb 0.1.0

package/dist/digest/parse.d.cts

@@ -0,0 +1,80 @@
+/**
+ * Parses one line of a rendered digest back into structured data. This is what
+ * makes the format machine-readable as well as agent-readable: a consumer that
+ * wants numbers rather than text does not have to re-implement the grammar.
+ *
+ * Ported from the prototype, where it round-tripped every golden digest, plus
+ * the v2 addition: facts.
+ */
+export interface ParsedGap {
+    direction: 'down' | 'right';
+    value: number;
+    overlap: boolean;
+}
+export interface ParsedElementLine {
+    kind: 'element';
+    id: string;
+    tag: string;
+    /** From `.role` or `#testid`, whichever was rendered; bare, no sigil. */
+    annotation: string | null;
+    text: string | null;
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    flow: 'row' | 'column' | 'grid' | 'none';
+    gap: ParsedGap | null;
+    /** Fact bodies, without their brackets, in the order rendered. */
+    facts: string[];
+    belowFold: boolean;
+    /** Tree depth, from the line's indentation. */
+    depth: number;
+}
+export interface ParsedFoldEntry {
+    id: string;
+    x: number;
+    y: number;
+    gap: ParsedGap | null;
+}
+export interface ParsedFoldLine {
+    kind: 'fold';
+    count: number;
+    likeId: string;
+    /** Size of the repeating unit the fold covers. `1` for a plain run of
+     * identical siblings; `>1` for a periodic run (story/subtext/spacer, `dt`/
+     * `dd`, ...) where only the first whole period was printed in full. */
+    period: number;
+    /** The `(...)` size-spread token, verbatim and unparsed, or `null` when the
+     * folded members were uniform enough that none was emitted. A `period > 1`
+     * fold's spread is per phase (`phase0 h 2-90`) rather than pooled. */
+    variance: string | null;
+    entries: ParsedFoldEntry[];
+}
+export interface ParsedCollapsedLine {
+    kind: 'collapsed';
+    nodeCount: number;
+    /** Elements carrying a fact inside the collapsed subtree. `0` when the
+     * renderer omitted the clause -- a real, counted zero, not "unknown" --
+     * see `digest/render.ts#countFacts`. */
+    factCount: number;
+    bbox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * The id `--focus` reaches this collapsed subtree through -- always
+     * present; `digest/render.ts#renderChildren` prints it on every
+     * `[folded: …]` line unconditionally (it is the collapsed container's own
+     * id, already printed on the line directly above), unlike the fold line's
+     * `…+N not listed (--focus <id>)` hint, which is conditional on there
+     * being a hidden tail at all.
+     */
+    focusHint: string;
+}
+export type ParsedLine = ParsedElementLine | ParsedFoldLine | ParsedCollapsedLine;
+/** Comment (`#…`) and blank lines carry no per-node data and parse to `null`. */
+export declare function parseDigestLine(line: string): ParsedLine | null;

package/dist/digest/parse.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Parses one line of a rendered digest back into structured data. This is what
+ * makes the format machine-readable as well as agent-readable: a consumer that
+ * wants numbers rather than text does not have to re-implement the grammar.
+ *
+ * Ported from the prototype, where it round-tripped every golden digest, plus
+ * the v2 addition: facts.
+ */
+export interface ParsedGap {
+    direction: 'down' | 'right';
+    value: number;
+    overlap: boolean;
+}
+export interface ParsedElementLine {
+    kind: 'element';
+    id: string;
+    tag: string;
+    /** From `.role` or `#testid`, whichever was rendered; bare, no sigil. */
+    annotation: string | null;
+    text: string | null;
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    flow: 'row' | 'column' | 'grid' | 'none';
+    gap: ParsedGap | null;
+    /** Fact bodies, without their brackets, in the order rendered. */
+    facts: string[];
+    belowFold: boolean;
+    /** Tree depth, from the line's indentation. */
+    depth: number;
+}
+export interface ParsedFoldEntry {
+    id: string;
+    x: number;
+    y: number;
+    gap: ParsedGap | null;
+}
+export interface ParsedFoldLine {
+    kind: 'fold';
+    count: number;
+    likeId: string;
+    /** Size of the repeating unit the fold covers. `1` for a plain run of
+     * identical siblings; `>1` for a periodic run (story/subtext/spacer, `dt`/
+     * `dd`, ...) where only the first whole period was printed in full. */
+    period: number;
+    /** The `(...)` size-spread token, verbatim and unparsed, or `null` when the
+     * folded members were uniform enough that none was emitted. A `period > 1`
+     * fold's spread is per phase (`phase0 h 2-90`) rather than pooled. */
+    variance: string | null;
+    entries: ParsedFoldEntry[];
+}
+export interface ParsedCollapsedLine {
+    kind: 'collapsed';
+    nodeCount: number;
+    /** Elements carrying a fact inside the collapsed subtree. `0` when the
+     * renderer omitted the clause -- a real, counted zero, not "unknown" --
+     * see `digest/render.ts#countFacts`. */
+    factCount: number;
+    bbox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * The id `--focus` reaches this collapsed subtree through -- always
+     * present; `digest/render.ts#renderChildren` prints it on every
+     * `[folded: …]` line unconditionally (it is the collapsed container's own
+     * id, already printed on the line directly above), unlike the fold line's
+     * `…+N not listed (--focus <id>)` hint, which is conditional on there
+     * being a hidden tail at all.
+     */
+    focusHint: string;
+}
+export type ParsedLine = ParsedElementLine | ParsedFoldLine | ParsedCollapsedLine;
+/** Comment (`#…`) and blank lines carry no per-node data and parse to `null`. */
+export declare function parseDigestLine(line: string): ParsedLine | null;

package/dist/digest/parse.js

@@ -0,0 +1,160 @@
+/**
+ * Parses one line of a rendered digest back into structured data. This is what
+ * makes the format machine-readable as well as agent-readable: a consumer that
+ * wants numbers rather than text does not have to re-implement the grammar.
+ *
+ * Ported from the prototype, where it round-tripped every golden digest, plus
+ * the v2 addition: facts.
+ */
+const GAP_RE = /([↓→])(-?\d+)( OVERLAP)?/;
+const POS_SIZE_RE = /@(-?\d+),(-?\d+)\s+(\d+)x(\d+)/;
+function parseGapToken(token) {
+    if (!token)
+        return null;
+    const match = GAP_RE.exec(token);
+    if (!match)
+        return null;
+    const [, arrow, valueStr, overlapStr] = match;
+    return {
+        direction: arrow === '↓' ? 'down' : 'right',
+        value: Number(valueStr),
+        overlap: Boolean(overlapStr),
+    };
+}
+/** A fold line's per-entry list: `id @x,y [gap], id @x,y [gap], ...`. */
+function parseFoldEntries(list) {
+    const entries = [];
+    // Entries never contain a literal ", " -- ids, positions and gaps cannot --
+    // so a plain split is safe.
+    for (const part of list.split(', ')) {
+        const match = /^(\S+)\s+@(-?\d+),(-?\d+)(.*)$/.exec(part.trim());
+        if (!match)
+            continue;
+        const [, id, xStr, yStr, rest] = match;
+        if (!id || xStr === undefined || yStr === undefined)
+            continue;
+        entries.push({ id, x: Number(xStr), y: Number(yStr), gap: parseGapToken(rest ?? null) });
+    }
+    return entries;
+}
+/**
+ * Every `[...]` group after the geometry that is not a known structural token.
+ * Facts are open-ended by design — the renderer must be able to add one without
+ * the parser needing to know its name first.
+ */
+function parseFacts(after) {
+    const structural = /^(row|column|grid|below fold|wraps \d+)$/;
+    const facts = [];
+    for (const match of after.matchAll(/\[([^\]]+)\]/g)) {
+        const body = match[1];
+        if (body && !structural.test(body))
+            facts.push(body);
+    }
+    return facts;
+}
+/** Comment (`#…`) and blank lines carry no per-node data and parse to `null`. */
+export function parseDigestLine(line) {
+    const trimmed = line.trim();
+    if (trimmed === '' || trimmed.startsWith('#'))
+        return null;
+    const depth = Math.floor((line.length - line.trimStart().length) / 2);
+    // The `, <K> facts` clause is optional -- present only when the collapsed
+    // subtree hides at least one fact-carrying element (`digest/render.ts`'s
+    // `renderChildren`) -- so it is its own optional group rather than folded
+    // into a catch-all, the same discipline the fold line's variance token
+    // uses. `(--focus <id>)` is not optional in what the renderer emits (every
+    // `[folded: …]` line carries it -- P1-1: the collapse line used to be the
+    // one place in the whole format that disclosed the most while pointing
+    // nowhere), but the group here is still `?` so a hand-built or
+    // differently-versioned line missing it still parses rather than going
+    // `null`.
+    const collapsed = /^\[folded:\s*(\d+)\s*nodes(?:,\s*(\d+)\s*facts)?,\s*bbox\s*@(-?\d+),(-?\d+)\s+(\d+)x(\d+)(?:\s*\(--focus\s+(\S+)\))?\]$/.exec(trimmed);
+    if (collapsed) {
+        const [, count, facts, x, y, w, h, focusHint] = collapsed;
+        return {
+            kind: 'collapsed',
+            nodeCount: Number(count),
+            factCount: facts ? Number(facts) : 0,
+            bbox: { x: Number(x), y: Number(y), width: Number(w), height: Number(h) },
+            focusHint: focusHint ?? '',
+        };
+    }
+    // `×N[/period] more like <id>[ (variance)] — entries`. The variance and
+    // period groups are both explicit and optional rather than folded into a
+    // catch-all `\S+` for `likeId` -- a variance token has a space in it
+    // (`r0 (h 30-90)`), and `(\S+)\s*—` alone cannot span that, which used to
+    // make every folded id on a page with a size spread unparseable.
+    const fold = /^\[fold:\s*×(\d+)(?:\/(\d+))?\s*more like (\S+)(?:\s*(\([^()]*\)))?\s*—\s*(.+)\]$/.exec(trimmed);
+    if (fold) {
+        const [, count, period, likeId, variance, list] = fold;
+        if (!likeId || !list)
+            return null;
+        return {
+            kind: 'fold',
+            count: Number(count),
+            likeId,
+            period: period ? Number(period) : 1,
+            variance: variance ?? null,
+            entries: parseFoldEntries(list),
+        };
+    }
+    const posSize = POS_SIZE_RE.exec(trimmed);
+    if (!posSize)
+        return null;
+    const [, xStr, yStr, wStr, hStr] = posSize;
+    if (xStr === undefined || yStr === undefined || wStr === undefined || hStr === undefined) {
+        return null;
+    }
+    const before = trimmed.slice(0, posSize.index).trim();
+    const after = trimmed.slice(posSize.index + posSize[0].length);
+    // Text is split off first, then id/tag/annotation are parsed from what's
+    // left -- not one combined regex -- because the renderer does not escape
+    // the text it quotes, and a real accessible name can contain a literal
+    // `"` (ar.wikipedia.org link titles quote a word inline: `"الملحوظة"`
+    // inside the name). `(.*?)` is lazy, so it finds the *first* `\s+"` in
+    // `before` -- right after tag/annotation, since neither ever contains
+    // `\s+"` itself -- and the greedy `(.*)"$` then takes everything from
+    // there to the final `"` at the very end of the line as the text,
+    // embedded quotes included. Without this split, a naive `"([^"]*)"$`
+    // stops at the first embedded quote and the anchored `$` never matches,
+    // so the whole line -- id, tag, position, every fact on it -- was
+    // discarded.
+    const textMatch = /^(.*?)\s+"(.*)"$/.exec(before);
+    const head = textMatch ? textMatch[1] : before;
+    const text = textMatch ? textMatch[2] : undefined;
+    if (head === undefined)
+        return null;
+    // Tag: an optional `::` pseudo-element prefix (`::before`, `::after`,
+    // `::marker` -- real tokens on a real capture; the CDP snapshot path
+    // reports a pseudo-element's node name verbatim) followed by a plain tag
+    // name, which on a modern page is routinely a hyphenated custom-element
+    // name (`sl-button`, or any other web component). Annotation, when
+    // present, is greedy (`.*`) rather than `[^\s"]+` from its `.`/`#` sigil to
+    // the end of what's left: a role (`.heading`) never has whitespace in it,
+    // but a `data-testid` value is raw attribute text, and real pages put
+    // whitespace in it -- e.g. grafana.com renders
+    // `data-testid="data-testid navigation mega-menu"` verbatim, so the
+    // annotation itself is `data-testid navigation mega-menu`. The text (if
+    // any) is already stripped off above, so there is nothing after the
+    // annotation left to over-consume.
+    const idTagMatch = /^(\S+)\s+((?:::)?[a-zA-Z][a-zA-Z0-9-]*)([.#].*)?$/.exec(head);
+    if (!idTagMatch)
+        return null;
+    const [, id, tag, annotation] = idTagMatch;
+    if (!id || !tag)
+        return null;
+    const flow = /\[(row|column|grid)\]/.exec(after);
+    return {
+        kind: 'element',
+        id,
+        tag,
+        annotation: annotation ? annotation.slice(1) : null,
+        text: text ?? null,
+        rect: { x: Number(xStr), y: Number(yStr), width: Number(wStr), height: Number(hStr) },
+        flow: flow?.[1] ?? 'none',
+        gap: parseGapToken(GAP_RE.exec(after)?.[0] ?? null),
+        facts: parseFacts(after),
+        belowFold: /\[below fold\]/.test(after),
+        depth,
+    };
+}