@michaelmagan/dnumb 0.1.0

package/dist/diff/types.d.cts

@@ -0,0 +1,211 @@
+/**
+ * The contract for the state diff.
+ *
+ * A diff answers "what changed between these two captures, and why" — a harder
+ * question than it sounds, because before anything can say `e12 moved down
+ * 21px` it has to know that `e12` in one capture and `e12` in the other are the
+ * same element, across a DOM that just changed.
+ *
+ * `identity.ts` and `match.ts` establish that. `changes.ts` turns matched pairs
+ * into facts and folds consequences under their causes. `render.ts` writes it
+ * down.
+ */
+import type { ElementRecord, NotMeasured } from "../snapshot/types.cjs";
+/**
+ * A capture indexed for matching.
+ *
+ * The derived values live in side maps rather than on the records. A bundle's
+ * elements belong to the caller, and the step-2 spike mutated them — which
+ * meant diffing the same bundle twice gave a different answer the second time.
+ */
+export interface Prepared {
+    elements: readonly ElementRecord[];
+    byId: ReadonlyMap<string, ElementRecord>;
+    /** Position among siblings that produce the same tag. Identity rung 4. */
+    ordinal: ReadonlyMap<string, number>;
+    /**
+     * Inner text of the subtree, capped.
+     *
+     * Similo's "visible text" is inner text, not own text, and the distinction is
+     * load-bearing: a list item's own text is empty when its content sits in
+     * child spans, which is exactly the case the matcher has to get right. Own
+     * text alone leaves every `<li>` scoring identically and the match falls
+     * through to the sibling ordinal, which is the cascade the critique measured.
+     */
+    subtreeText: ReadonlyMap<string, string>;
+    /** Document order, so a renderer can print an act before its consequences. */
+    docIndex: ReadonlyMap<string, number>;
+    /** How many elements sit underneath. Used for label heuristics. */
+    descendantCount: ReadonlyMap<string, number>;
+    roots: readonly string[];
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /**
+     * From `Snapshot.truncated` (`src/snapshot/limits.ts`): this capture is a
+     * window bounded by the element cap, not the whole page. `match.ts` and
+     * `changes.ts` both read this rather than re-deriving it, so "truncated"
+     * means one thing everywhere a diff asks the question.
+     */
+    truncated: boolean;
+}
+/** before-id → after-id, and the inverse. */
+export interface Match {
+    pairs: ReadonlyMap<string, string>;
+    reverse: ReadonlyMap<string, string>;
+}
+export interface BoxDelta {
+    dx: number;
+    dy: number;
+    dw: number;
+    dh: number;
+}
+export type ChangeKind = 'added' | 'removed' | 'appeared' | 'disappeared' | 'text' | 'attr' | 'style' | 'overflow' | 'clip' | 'box';
+/**
+ * Why a change does not get a line of its own.
+ *
+ * `subsumed` means another line already says it: a `display: none → block` and
+ * a box arriving from `@0,0` are both the sentence "it appeared", and a
+ * `display:none` element's `@0,0` box is an artefact rather than an
+ * observation. `derived` means it is a genuine separate consequence, printed
+ * folded under the act that caused it.
+ *
+ * Nothing is dropped on a judgement about importance — only on a demonstrable
+ * causal relationship between two measurements already in hand.
+ */
+export type Subsumption = 'visibility' | 'subtree';
+export type Cause = 'primary' | 'derived';
+export type Derivation = 'carried' | 'pushed' | 'absorbed' | 'reflowed' | 'inherited';
+export interface Change {
+    kind: ChangeKind;
+    /**
+     * After-state id. Present on everything except `removed`, because the next
+     * thing a reader does is query the state they are now in.
+     */
+    afterId?: string;
+    beforeId?: string;
+    before?: ElementRecord | undefined;
+    after?: ElementRecord | undefined;
+    /** `style` only: the record property that changed, camelCase. */
+    prop?: string;
+    /** `style` only: whether this property can move or resize a box. */
+    geometric?: boolean;
+    /** `appeared` / `disappeared` only: `display:none` or `hidden`. */
+    reason?: string;
+    /** `overflow` only: whether the element overflows *now*. */
+    now?: boolean;
+    /** `box` only. */
+    delta?: BoxDelta;
+    /** Set by the subsumption pass in `changes.ts`. */
+    subsumed?: Subsumption;
+    subsumedBy?: string;
+    /** How many descendants folded into this one. */
+    descendants?: number;
+    cause?: Cause;
+    how?: Derivation;
+    /** The immediate cause's after-id. */
+    via?: string;
+    /**
+     * The cause at the end of the `via` chain, and its kind.
+     *
+     * Without this, a pushed row and the four words inside it become five groups
+     * that all mean "because e6 was inserted".
+     */
+    rootVia?: string;
+    rootHow?: Derivation;
+    /**
+     * `removed` / `added` only, and only when the capture whose window could
+     * have excluded the counterpart is truncated — for `removed`, the *after*
+     * capture; for `added`, the *before* capture. The precondition is per-kind,
+     * not "both captures truncated": a `removed` change only needs to ask
+     * whether the after capture is a window, because the before side already
+     * produced this element in hand regardless of its own truncation, and the
+     * mirror is true for `added`. Requiring both sides truncated used to
+     * silently drop this flag whenever the complete side happened to be the
+     * one whose window actually explains the gap.
+     *
+     * An element with no partner reads the same whether the page genuinely lost
+     * it or the truncation window simply no longer includes it — inserting one
+     * element earlier in the document shifts every later index, which can push
+     * real, still-present content past a fixed element cap. `changes.ts`'s
+     * `markBoundaryAmbiguous` tells the two apart using the document-order
+     * shift the matcher already measured on this element's nearest matched
+     * neighbour: when that shift would place its hypothetical counterpart
+     * outside the other capture's window, this is set instead of reporting a
+     * bare removal or addition. Never suppressed — see `render.ts`'s `?` line.
+     */
+    boundaryAmbiguous?: boolean;
+    /**
+     * The element count of the capture whose window boundary explains the
+     * ambiguity: for `removed`, the *after* capture (its cap is what could have
+     * cut the surviving counterpart off); for `added`, the *before* capture
+     * (its cap is what could have missed an element that was already there).
+     * `render.ts`'s `boundaryLine` must name the same capture this counts —
+     * printing this number under the other capture's label is F2.
+     */
+    capSize?: number;
+}
+export interface DiffOptions {
+    /**
+     * Maximum body lines. Default 15 — the diff-ack budget.
+     *
+     * A diff exists to collapse act-then-look into one round trip. One that costs
+     * more than re-reading the digest has defeated its own purpose.
+     */
+    maxLines?: number;
+}
+export interface DiffMeta {
+    /** What the two captures are called. */
+    before: string;
+    after: string;
+    viewportBefore: string;
+    viewportAfter: string;
+    /**
+     * From each side's `Snapshot.truncated`. Optional so a hand-built `DiffMeta`
+     * in a test fixture need not opine on it — the same posture
+     * `Snapshot.notMeasured` takes; `undefined` reads as "not truncated", never
+     * as "unknown", because both real capture paths always set the source
+     * `Snapshot.truncated` explicitly. `diffCaptures` always passes both.
+     */
+    truncatedBefore?: boolean;
+    truncatedAfter?: boolean;
+    /** Element count of each capture. Only used to word the truncation caveat. */
+    beforeCount?: number;
+    afterCount?: number;
+    /**
+     * Which capture path produced each side — `cdp` and `walk` do not see the
+     * same page on shadow DOM (`DigestMeta.strategy`'s doc comment), so a diff
+     * across the two is comparing capability, not just state. Optional for the
+     * same reason `truncatedBefore` is: a hand-built `DiffMeta` need not opine,
+     * and a `Snapshot` fixture with no `strategy` field carries none. Real
+     * captures (`CaptureResult`, `Bundle`) always have one, and `diffCaptures`
+     * forwards it structurally without the caller naming it explicitly.
+     */
+    strategyBefore?: 'cdp' | 'walk';
+    strategyAfter?: 'cdp' | 'walk';
+    /**
+     * Shadow DOM and iframe content each side walked past uncounted. Carried
+     * for `--json` and for `render.ts`'s `NOT MEASURED:` header line (B7 —
+     * this was measured and threaded all the way here, then rendered nowhere,
+     * for as long as the field existed) — the same structural-availability
+     * posture as `strategy` above. Rendering it makes no claim that two
+     * captures with different `notMeasured` are comparable or not, only that
+     * the fact is disclosed rather than silently dropped.
+     */
+    notMeasuredBefore?: NotMeasured;
+    notMeasuredAfter?: NotMeasured;
+}
+export interface DiffResult {
+    changes: readonly Change[];
+    text: string;
+    /**
+     * Whether either side of this diff is a window rather than a whole page —
+     * lifted out of `Snapshot.truncated` so a `--json` consumer learns it
+     * structurally, without re-parsing the prose caveat `text` carries.
+     */
+    truncated: {
+        before: boolean;
+        after: boolean;
+    };
+}

package/dist/diff/types.d.ts

@@ -0,0 +1,211 @@
+/**
+ * The contract for the state diff.
+ *
+ * A diff answers "what changed between these two captures, and why" — a harder
+ * question than it sounds, because before anything can say `e12 moved down
+ * 21px` it has to know that `e12` in one capture and `e12` in the other are the
+ * same element, across a DOM that just changed.
+ *
+ * `identity.ts` and `match.ts` establish that. `changes.ts` turns matched pairs
+ * into facts and folds consequences under their causes. `render.ts` writes it
+ * down.
+ */
+import type { ElementRecord, NotMeasured } from "../snapshot/types.js";
+/**
+ * A capture indexed for matching.
+ *
+ * The derived values live in side maps rather than on the records. A bundle's
+ * elements belong to the caller, and the step-2 spike mutated them — which
+ * meant diffing the same bundle twice gave a different answer the second time.
+ */
+export interface Prepared {
+    elements: readonly ElementRecord[];
+    byId: ReadonlyMap<string, ElementRecord>;
+    /** Position among siblings that produce the same tag. Identity rung 4. */
+    ordinal: ReadonlyMap<string, number>;
+    /**
+     * Inner text of the subtree, capped.
+     *
+     * Similo's "visible text" is inner text, not own text, and the distinction is
+     * load-bearing: a list item's own text is empty when its content sits in
+     * child spans, which is exactly the case the matcher has to get right. Own
+     * text alone leaves every `<li>` scoring identically and the match falls
+     * through to the sibling ordinal, which is the cascade the critique measured.
+     */
+    subtreeText: ReadonlyMap<string, string>;
+    /** Document order, so a renderer can print an act before its consequences. */
+    docIndex: ReadonlyMap<string, number>;
+    /** How many elements sit underneath. Used for label heuristics. */
+    descendantCount: ReadonlyMap<string, number>;
+    roots: readonly string[];
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /**
+     * From `Snapshot.truncated` (`src/snapshot/limits.ts`): this capture is a
+     * window bounded by the element cap, not the whole page. `match.ts` and
+     * `changes.ts` both read this rather than re-deriving it, so "truncated"
+     * means one thing everywhere a diff asks the question.
+     */
+    truncated: boolean;
+}
+/** before-id → after-id, and the inverse. */
+export interface Match {
+    pairs: ReadonlyMap<string, string>;
+    reverse: ReadonlyMap<string, string>;
+}
+export interface BoxDelta {
+    dx: number;
+    dy: number;
+    dw: number;
+    dh: number;
+}
+export type ChangeKind = 'added' | 'removed' | 'appeared' | 'disappeared' | 'text' | 'attr' | 'style' | 'overflow' | 'clip' | 'box';
+/**
+ * Why a change does not get a line of its own.
+ *
+ * `subsumed` means another line already says it: a `display: none → block` and
+ * a box arriving from `@0,0` are both the sentence "it appeared", and a
+ * `display:none` element's `@0,0` box is an artefact rather than an
+ * observation. `derived` means it is a genuine separate consequence, printed
+ * folded under the act that caused it.
+ *
+ * Nothing is dropped on a judgement about importance — only on a demonstrable
+ * causal relationship between two measurements already in hand.
+ */
+export type Subsumption = 'visibility' | 'subtree';
+export type Cause = 'primary' | 'derived';
+export type Derivation = 'carried' | 'pushed' | 'absorbed' | 'reflowed' | 'inherited';
+export interface Change {
+    kind: ChangeKind;
+    /**
+     * After-state id. Present on everything except `removed`, because the next
+     * thing a reader does is query the state they are now in.
+     */
+    afterId?: string;
+    beforeId?: string;
+    before?: ElementRecord | undefined;
+    after?: ElementRecord | undefined;
+    /** `style` only: the record property that changed, camelCase. */
+    prop?: string;
+    /** `style` only: whether this property can move or resize a box. */
+    geometric?: boolean;
+    /** `appeared` / `disappeared` only: `display:none` or `hidden`. */
+    reason?: string;
+    /** `overflow` only: whether the element overflows *now*. */
+    now?: boolean;
+    /** `box` only. */
+    delta?: BoxDelta;
+    /** Set by the subsumption pass in `changes.ts`. */
+    subsumed?: Subsumption;
+    subsumedBy?: string;
+    /** How many descendants folded into this one. */
+    descendants?: number;
+    cause?: Cause;
+    how?: Derivation;
+    /** The immediate cause's after-id. */
+    via?: string;
+    /**
+     * The cause at the end of the `via` chain, and its kind.
+     *
+     * Without this, a pushed row and the four words inside it become five groups
+     * that all mean "because e6 was inserted".
+     */
+    rootVia?: string;
+    rootHow?: Derivation;
+    /**
+     * `removed` / `added` only, and only when the capture whose window could
+     * have excluded the counterpart is truncated — for `removed`, the *after*
+     * capture; for `added`, the *before* capture. The precondition is per-kind,
+     * not "both captures truncated": a `removed` change only needs to ask
+     * whether the after capture is a window, because the before side already
+     * produced this element in hand regardless of its own truncation, and the
+     * mirror is true for `added`. Requiring both sides truncated used to
+     * silently drop this flag whenever the complete side happened to be the
+     * one whose window actually explains the gap.
+     *
+     * An element with no partner reads the same whether the page genuinely lost
+     * it or the truncation window simply no longer includes it — inserting one
+     * element earlier in the document shifts every later index, which can push
+     * real, still-present content past a fixed element cap. `changes.ts`'s
+     * `markBoundaryAmbiguous` tells the two apart using the document-order
+     * shift the matcher already measured on this element's nearest matched
+     * neighbour: when that shift would place its hypothetical counterpart
+     * outside the other capture's window, this is set instead of reporting a
+     * bare removal or addition. Never suppressed — see `render.ts`'s `?` line.
+     */
+    boundaryAmbiguous?: boolean;
+    /**
+     * The element count of the capture whose window boundary explains the
+     * ambiguity: for `removed`, the *after* capture (its cap is what could have
+     * cut the surviving counterpart off); for `added`, the *before* capture
+     * (its cap is what could have missed an element that was already there).
+     * `render.ts`'s `boundaryLine` must name the same capture this counts —
+     * printing this number under the other capture's label is F2.
+     */
+    capSize?: number;
+}
+export interface DiffOptions {
+    /**
+     * Maximum body lines. Default 15 — the diff-ack budget.
+     *
+     * A diff exists to collapse act-then-look into one round trip. One that costs
+     * more than re-reading the digest has defeated its own purpose.
+     */
+    maxLines?: number;
+}
+export interface DiffMeta {
+    /** What the two captures are called. */
+    before: string;
+    after: string;
+    viewportBefore: string;
+    viewportAfter: string;
+    /**
+     * From each side's `Snapshot.truncated`. Optional so a hand-built `DiffMeta`
+     * in a test fixture need not opine on it — the same posture
+     * `Snapshot.notMeasured` takes; `undefined` reads as "not truncated", never
+     * as "unknown", because both real capture paths always set the source
+     * `Snapshot.truncated` explicitly. `diffCaptures` always passes both.
+     */
+    truncatedBefore?: boolean;
+    truncatedAfter?: boolean;
+    /** Element count of each capture. Only used to word the truncation caveat. */
+    beforeCount?: number;
+    afterCount?: number;
+    /**
+     * Which capture path produced each side — `cdp` and `walk` do not see the
+     * same page on shadow DOM (`DigestMeta.strategy`'s doc comment), so a diff
+     * across the two is comparing capability, not just state. Optional for the
+     * same reason `truncatedBefore` is: a hand-built `DiffMeta` need not opine,
+     * and a `Snapshot` fixture with no `strategy` field carries none. Real
+     * captures (`CaptureResult`, `Bundle`) always have one, and `diffCaptures`
+     * forwards it structurally without the caller naming it explicitly.
+     */
+    strategyBefore?: 'cdp' | 'walk';
+    strategyAfter?: 'cdp' | 'walk';
+    /**
+     * Shadow DOM and iframe content each side walked past uncounted. Carried
+     * for `--json` and for `render.ts`'s `NOT MEASURED:` header line (B7 —
+     * this was measured and threaded all the way here, then rendered nowhere,
+     * for as long as the field existed) — the same structural-availability
+     * posture as `strategy` above. Rendering it makes no claim that two
+     * captures with different `notMeasured` are comparable or not, only that
+     * the fact is disclosed rather than silently dropped.
+     */
+    notMeasuredBefore?: NotMeasured;
+    notMeasuredAfter?: NotMeasured;
+}
+export interface DiffResult {
+    changes: readonly Change[];
+    text: string;
+    /**
+     * Whether either side of this diff is a window rather than a whole page —
+     * lifted out of `Snapshot.truncated` so a `--json` consumer learns it
+     * structurally, without re-parsing the prose caveat `text` carries.
+     */
+    truncated: {
+        before: boolean;
+        after: boolean;
+    };
+}

package/dist/diff/types.js

@@ -0,0 +1 @@
+export {};

package/dist/digest/index.cjs

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPARSE_CAPTURE_MARKER = exports.renderDigest = exports.parseDigestLine = void 0;
+var parse_js_1 = require("./parse.cjs");
+Object.defineProperty(exports, "parseDigestLine", { enumerable: true, get: function () { return parse_js_1.parseDigestLine; } });
+var render_js_1 = require("./render.cjs");
+Object.defineProperty(exports, "renderDigest", { enumerable: true, get: function () { return render_js_1.renderDigest; } });
+Object.defineProperty(exports, "SPARSE_CAPTURE_MARKER", { enumerable: true, get: function () { return render_js_1.SPARSE_CAPTURE_MARKER; } });

package/dist/digest/index.d.cts

@@ -0,0 +1,4 @@
+export type { ParsedCollapsedLine, ParsedElementLine, ParsedFoldEntry, ParsedFoldLine, ParsedGap, ParsedLine, } from "./parse.cjs";
+export { parseDigestLine } from "./parse.cjs";
+export { renderDigest, SPARSE_CAPTURE_MARKER } from "./render.cjs";
+export type { DigestMeta, RenderDigestOptions } from "./types.cjs";

package/dist/digest/index.d.ts

@@ -0,0 +1,4 @@
+export type { ParsedCollapsedLine, ParsedElementLine, ParsedFoldEntry, ParsedFoldLine, ParsedGap, ParsedLine, } from "./parse.js";
+export { parseDigestLine } from "./parse.js";
+export { renderDigest, SPARSE_CAPTURE_MARKER } from "./render.js";
+export type { DigestMeta, RenderDigestOptions } from "./types.js";

package/dist/digest/index.js

@@ -0,0 +1,2 @@
+export { parseDigestLine } from "./parse.js";
+export { renderDigest, SPARSE_CAPTURE_MARKER } from "./render.js";

package/dist/digest/parse.cjs

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDigestLine = parseDigestLine;
+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`. */
+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,
+    };
+}