@michaelmagan/dnumb 0.1.0

package/dist/diff/index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The state diff: what changed between two captures, and why.
+ *
+ * `look` describes one moment. This describes the transition — which is what
+ * makes an agent's own actions legible to it. Click something, get back a
+ * bounded account of what the click did, instead of re-reading the whole digest
+ * and comparing by hand.
+ *
+ * The hard part is not the arithmetic. 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` is that, and
+ * its central finding is that geometry must count for *zero* when matching.
+ */
+import type { Snapshot } from "../snapshot/types.js";
+import type { DiffOptions, DiffResult } from "./types.js";
+export { computeChanges } from "./changes.js";
+export { geometryTiebreak, hardKey, isGeneratedId, MATCH_THRESHOLD, similarity, textSimilarity, WEAK_ROLES, } from "./identity.js";
+export { match, prepare } from "./match.js";
+export { renderDiff } from "./render.js";
+export type { BoxDelta, Cause, Change, ChangeKind, Derivation, DiffMeta, DiffOptions, DiffResult, Match, Prepared, Subsumption, } from "./types.js";
+export interface DiffCapturesOptions extends DiffOptions {
+    /** Names for the two captures, used in the header. Default `before`/`after`. */
+    beforeName?: string;
+    afterName?: string;
+}
+/**
+ * What `diffCaptures` actually needs beyond a bare `Snapshot`: which capture
+ * path produced it, when the caller has one to give.
+ *
+ * `strategy` lives on `CaptureResult` and `Bundle`, not on `Snapshot` itself —
+ * this package's diff layer only depends on `snapshot/types.ts`. Both real
+ * capture shapes are structural supersets of `Snapshot`, so a caller passing
+ * a real `CaptureResult` or `Bundle` satisfies this type for free; only a
+ * hand-built `Snapshot` fixture has no opinion, which is why the field is
+ * optional here exactly as `DiffMeta.strategyBefore` is.
+ */
+export interface DiffableSnapshot extends Snapshot {
+    strategy?: 'cdp' | 'walk';
+}
+/**
+ * Two captures were taken at different viewports.
+ *
+ * Nearly every box moves on a viewport change, so a diff would faithfully
+ * report hundreds of consequences of something the reader already knows
+ * instead of the change they are looking for. `cli.ts` has refused this for
+ * as long as the `diff` verb has existed; `diffCaptures` itself did not,
+ * which meant any other caller of the library — not just the CLI — could
+ * diff 1440×900 against 375×812 and get a diff that describes a resize.
+ */
+export declare class DiffViewportMismatchError extends Error {
+    readonly before: {
+        width: number;
+        height: number;
+    };
+    readonly after: {
+        width: number;
+        height: number;
+    };
+    name: string;
+    constructor(before: {
+        width: number;
+        height: number;
+    }, after: {
+        width: number;
+        height: number;
+    });
+}
+/**
+ * Diff two captures end to end.
+ *
+ * Returns both the rendered text and the structured changes, so a caller that
+ * wants numbers does not have to parse the text back — the same discipline the
+ * query verbs follow, and for the same reason: two renderings built from one
+ * computation cannot disagree.
+ */
+export declare function diffCaptures(before: DiffableSnapshot, after: DiffableSnapshot, options?: DiffCapturesOptions): DiffResult;

package/dist/diff/index.js

@@ -0,0 +1,68 @@
+import { computeChanges } from "./changes.js";
+import { match, prepare } from "./match.js";
+import { renderDiff } from "./render.js";
+export { computeChanges } from "./changes.js";
+export { geometryTiebreak, hardKey, isGeneratedId, MATCH_THRESHOLD, similarity, textSimilarity, WEAK_ROLES, } from "./identity.js";
+export { match, prepare } from "./match.js";
+export { renderDiff } from "./render.js";
+/**
+ * Two captures were taken at different viewports.
+ *
+ * Nearly every box moves on a viewport change, so a diff would faithfully
+ * report hundreds of consequences of something the reader already knows
+ * instead of the change they are looking for. `cli.ts` has refused this for
+ * as long as the `diff` verb has existed; `diffCaptures` itself did not,
+ * which meant any other caller of the library — not just the CLI — could
+ * diff 1440×900 against 375×812 and get a diff that describes a resize.
+ */
+export class DiffViewportMismatchError extends Error {
+    before;
+    after;
+    name = 'DiffViewportMismatchError';
+    constructor(before, after) {
+        super(`dnumb: these captures were taken at different viewports (${before.width}x${before.height} ` +
+            `vs ${after.width}x${after.height}). Nearly every box moved, so the diff would describe ` +
+            'the resize rather than the change you are looking for. Capture both states at one ' +
+            'viewport, or read each with `look`.');
+        this.before = before;
+        this.after = after;
+    }
+}
+/**
+ * Diff two captures end to end.
+ *
+ * Returns both the rendered text and the structured changes, so a caller that
+ * wants numbers does not have to parse the text back — the same discipline the
+ * query verbs follow, and for the same reason: two renderings built from one
+ * computation cannot disagree.
+ */
+export function diffCaptures(before, after, options = {}) {
+    if (before.viewport.width !== after.viewport.width ||
+        before.viewport.height !== after.viewport.height) {
+        throw new DiffViewportMismatchError(before.viewport, after.viewport);
+    }
+    const preparedBefore = prepare(before);
+    const preparedAfter = prepare(after);
+    const matched = match(preparedBefore, preparedAfter);
+    const changes = computeChanges(preparedBefore, preparedAfter, matched);
+    const viewport = (snapshot) => `${snapshot.viewport.width}x${snapshot.viewport.height}`;
+    const text = renderDiff(changes, {
+        before: options.beforeName ?? 'before',
+        after: options.afterName ?? 'after',
+        viewportBefore: viewport(before),
+        viewportAfter: viewport(after),
+        truncatedBefore: before.truncated,
+        truncatedAfter: after.truncated,
+        beforeCount: before.elements.length,
+        afterCount: after.elements.length,
+        // `exactOptionalPropertyTypes` treats `key: undefined` as distinct from
+        // the key being absent, so an `undefined` strategy/notMeasured (a
+        // hand-built `Snapshot` fixture with no opinion) has to be omitted
+        // entirely, not assigned.
+        ...(before.strategy !== undefined ? { strategyBefore: before.strategy } : {}),
+        ...(after.strategy !== undefined ? { strategyAfter: after.strategy } : {}),
+        ...(before.notMeasured !== undefined ? { notMeasuredBefore: before.notMeasured } : {}),
+        ...(after.notMeasured !== undefined ? { notMeasuredAfter: after.notMeasured } : {}),
+    }, options.maxLines === undefined ? {} : { maxLines: options.maxLines });
+    return { changes, text, truncated: { before: before.truncated, after: after.truncated } };
+}

package/dist/diff/match.cjs

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepare = prepare;
+exports.match = match;
+const identity_js_1 = require("./identity.cjs");
+/** Matches the accessible-name cap, so one long paragraph cannot dominate a score. */
+const SUBTREE_TEXT_LIMIT = 80;
+const MAX_SUBTREE_DEPTH = 6;
+function computeSubtreeText(byId, el, depth = 0) {
+    if (depth > MAX_SUBTREE_DEPTH)
+        return el.text;
+    let out = el.text;
+    for (const childId of el.childIds) {
+        const child = byId.get(childId);
+        if (!child)
+            continue;
+        out = `${out} ${computeSubtreeText(byId, child, depth + 1)}`.trim();
+        if (out.length > SUBTREE_TEXT_LIMIT)
+            break;
+    }
+    return out.slice(0, SUBTREE_TEXT_LIMIT);
+}
+/**
+ * Index a capture for matching, without touching its records — they belong to
+ * whoever loaded the bundle.
+ */
+function prepare(snapshot) {
+    const byId = new Map(snapshot.elements.map((el) => [el.id, el]));
+    const subtreeText = new Map();
+    const docIndex = new Map();
+    const ordinal = new Map();
+    const counters = new Map();
+    snapshot.elements.forEach((el, i) => {
+        subtreeText.set(el.id, computeSubtreeText(byId, el));
+        docIndex.set(el.id, i);
+        const key = `${el.parentId ?? 'root'}|${el.tag}`;
+        const n = counters.get(key) ?? 0;
+        counters.set(key, n + 1);
+        ordinal.set(el.id, n);
+    });
+    // Reverse document order, so every child is counted before its parent asks.
+    const descendantCount = new Map();
+    for (let i = snapshot.elements.length - 1; i >= 0; i--) {
+        const el = snapshot.elements[i];
+        if (!el)
+            continue;
+        descendantCount.set(el.id, el.childIds.reduce((sum, childId) => sum + 1 + (descendantCount.get(childId) ?? 0), 0));
+    }
+    return {
+        elements: snapshot.elements,
+        byId,
+        ordinal,
+        subtreeText,
+        docIndex,
+        descendantCount,
+        roots: snapshot.elements.filter((el) => el.parentId === null).map((el) => el.id),
+        viewport: snapshot.viewport,
+        truncated: snapshot.truncated,
+    };
+}
+function match(before, after) {
+    const pairs = new Map();
+    const reverse = new Map();
+    const link = (b, a) => {
+        pairs.set(b, a);
+        reverse.set(a, b);
+    };
+    // --- Rungs 1-2: hard keys, matched anywhere in the tree -------------------
+    // Absolute by contract, so an element that moved to a different parent still
+    // matches itself. Resolved before any scoring, so a strong key is never
+    // outvoted by a well-scoring impostor in the right position.
+    const afterByHardKey = new Map();
+    for (const el of after.elements) {
+        const key = (0, identity_js_1.hardKey)(el);
+        if (!key)
+            continue;
+        // A duplicated id is not document-unique in fact, whatever the spec says,
+        // so it stops being a key rather than becoming a coin flip.
+        afterByHardKey.set(key, afterByHardKey.has(key) ? null : el.id);
+    }
+    for (const el of before.elements) {
+        const key = (0, identity_js_1.hardKey)(el);
+        if (!key)
+            continue;
+        const hit = afterByHardKey.get(key);
+        if (hit && !reverse.has(hit))
+            link(el.id, hit);
+    }
+    // There is one <body> on each side; roots pair positionally.
+    const rootCount = Math.min(before.roots.length, after.roots.length);
+    for (let i = 0; i < rootCount; i++) {
+        const b = before.roots[i];
+        const a = after.roots[i];
+        if (b === undefined || a === undefined)
+            continue;
+        if (!pairs.has(b) && !reverse.has(a))
+            link(b, a);
+    }
+    // --- Rungs 3-4: scored assignment, breadth-first from every matched pair --
+    // Seeded with the hard-keyed pairs as well as the roots: a hard-keyed element
+    // deep in the tree is an entry point that its unmatched ancestors are not,
+    // which is why this is a queue over matched pairs and not a tree walk.
+    const queue = [...pairs];
+    const visited = new Set();
+    while (queue.length > 0) {
+        const next = queue.shift();
+        if (!next)
+            break;
+        const [beforeParent, afterParent] = next;
+        if (visited.has(beforeParent))
+            continue;
+        visited.add(beforeParent);
+        const bParent = before.byId.get(beforeParent);
+        const aParent = after.byId.get(afterParent);
+        if (!bParent || !aParent)
+            continue;
+        const bKids = bParent.childIds.filter((id) => !pairs.has(id));
+        const aKids = aParent.childIds.filter((id) => !reverse.has(id));
+        const candidates = [];
+        for (const bid of bKids) {
+            const b = before.byId.get(bid);
+            if (!b)
+                continue;
+            for (const aid of aKids) {
+                const a = after.byId.get(aid);
+                if (!a)
+                    continue;
+                const score = (0, identity_js_1.similarity)(b, a, {
+                    ordinalA: before.ordinal.get(bid),
+                    ordinalB: after.ordinal.get(aid),
+                    subtreeTextA: before.subtreeText.get(bid),
+                    subtreeTextB: after.subtreeText.get(aid),
+                });
+                if (score < identity_js_1.MATCH_THRESHOLD)
+                    continue;
+                candidates.push({ bid, aid, score: score + (0, identity_js_1.geometryTiebreak)(b, a) });
+            }
+        }
+        candidates.sort((x, y) => y.score - x.score);
+        const takenBefore = new Set();
+        const takenAfter = new Set();
+        for (const candidate of candidates) {
+            if (takenBefore.has(candidate.bid) || takenAfter.has(candidate.aid))
+                continue;
+            takenBefore.add(candidate.bid);
+            takenAfter.add(candidate.aid);
+            link(candidate.bid, candidate.aid);
+        }
+        for (const bid of bParent.childIds) {
+            const aid = pairs.get(bid);
+            if (aid)
+                queue.push([bid, aid]);
+        }
+    }
+    return { pairs, reverse };
+}

package/dist/diff/match.d.cts

@@ -0,0 +1,17 @@
+/**
+ * Global one-to-one assignment, scoped to matched parents.
+ *
+ * qain and browser-use both take the first hit and cannot express "these two
+ * candidates both want the same partner". This assigns instead. Scoping the
+ * assignment to a matched parent's children keeps each candidate set small
+ * enough that greedy-by-descending-score is near-optimal at O(n log n);
+ * Hungarian is O(n³) and unusable at the collector's 5,000-element cap.
+ */
+import type { Snapshot } from "../snapshot/types.cjs";
+import type { Match, Prepared } from "./types.cjs";
+/**
+ * Index a capture for matching, without touching its records — they belong to
+ * whoever loaded the bundle.
+ */
+export declare function prepare(snapshot: Snapshot): Prepared;
+export declare function match(before: Prepared, after: Prepared): Match;

package/dist/diff/match.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Global one-to-one assignment, scoped to matched parents.
+ *
+ * qain and browser-use both take the first hit and cannot express "these two
+ * candidates both want the same partner". This assigns instead. Scoping the
+ * assignment to a matched parent's children keeps each candidate set small
+ * enough that greedy-by-descending-score is near-optimal at O(n log n);
+ * Hungarian is O(n³) and unusable at the collector's 5,000-element cap.
+ */
+import type { Snapshot } from "../snapshot/types.js";
+import type { Match, Prepared } from "./types.js";
+/**
+ * Index a capture for matching, without touching its records — they belong to
+ * whoever loaded the bundle.
+ */
+export declare function prepare(snapshot: Snapshot): Prepared;
+export declare function match(before: Prepared, after: Prepared): Match;

package/dist/diff/match.js

@@ -0,0 +1,152 @@
+import { geometryTiebreak, hardKey, MATCH_THRESHOLD, similarity } from "./identity.js";
+/** Matches the accessible-name cap, so one long paragraph cannot dominate a score. */
+const SUBTREE_TEXT_LIMIT = 80;
+const MAX_SUBTREE_DEPTH = 6;
+function computeSubtreeText(byId, el, depth = 0) {
+    if (depth > MAX_SUBTREE_DEPTH)
+        return el.text;
+    let out = el.text;
+    for (const childId of el.childIds) {
+        const child = byId.get(childId);
+        if (!child)
+            continue;
+        out = `${out} ${computeSubtreeText(byId, child, depth + 1)}`.trim();
+        if (out.length > SUBTREE_TEXT_LIMIT)
+            break;
+    }
+    return out.slice(0, SUBTREE_TEXT_LIMIT);
+}
+/**
+ * Index a capture for matching, without touching its records — they belong to
+ * whoever loaded the bundle.
+ */
+export function prepare(snapshot) {
+    const byId = new Map(snapshot.elements.map((el) => [el.id, el]));
+    const subtreeText = new Map();
+    const docIndex = new Map();
+    const ordinal = new Map();
+    const counters = new Map();
+    snapshot.elements.forEach((el, i) => {
+        subtreeText.set(el.id, computeSubtreeText(byId, el));
+        docIndex.set(el.id, i);
+        const key = `${el.parentId ?? 'root'}|${el.tag}`;
+        const n = counters.get(key) ?? 0;
+        counters.set(key, n + 1);
+        ordinal.set(el.id, n);
+    });
+    // Reverse document order, so every child is counted before its parent asks.
+    const descendantCount = new Map();
+    for (let i = snapshot.elements.length - 1; i >= 0; i--) {
+        const el = snapshot.elements[i];
+        if (!el)
+            continue;
+        descendantCount.set(el.id, el.childIds.reduce((sum, childId) => sum + 1 + (descendantCount.get(childId) ?? 0), 0));
+    }
+    return {
+        elements: snapshot.elements,
+        byId,
+        ordinal,
+        subtreeText,
+        docIndex,
+        descendantCount,
+        roots: snapshot.elements.filter((el) => el.parentId === null).map((el) => el.id),
+        viewport: snapshot.viewport,
+        truncated: snapshot.truncated,
+    };
+}
+export function match(before, after) {
+    const pairs = new Map();
+    const reverse = new Map();
+    const link = (b, a) => {
+        pairs.set(b, a);
+        reverse.set(a, b);
+    };
+    // --- Rungs 1-2: hard keys, matched anywhere in the tree -------------------
+    // Absolute by contract, so an element that moved to a different parent still
+    // matches itself. Resolved before any scoring, so a strong key is never
+    // outvoted by a well-scoring impostor in the right position.
+    const afterByHardKey = new Map();
+    for (const el of after.elements) {
+        const key = hardKey(el);
+        if (!key)
+            continue;
+        // A duplicated id is not document-unique in fact, whatever the spec says,
+        // so it stops being a key rather than becoming a coin flip.
+        afterByHardKey.set(key, afterByHardKey.has(key) ? null : el.id);
+    }
+    for (const el of before.elements) {
+        const key = hardKey(el);
+        if (!key)
+            continue;
+        const hit = afterByHardKey.get(key);
+        if (hit && !reverse.has(hit))
+            link(el.id, hit);
+    }
+    // There is one <body> on each side; roots pair positionally.
+    const rootCount = Math.min(before.roots.length, after.roots.length);
+    for (let i = 0; i < rootCount; i++) {
+        const b = before.roots[i];
+        const a = after.roots[i];
+        if (b === undefined || a === undefined)
+            continue;
+        if (!pairs.has(b) && !reverse.has(a))
+            link(b, a);
+    }
+    // --- Rungs 3-4: scored assignment, breadth-first from every matched pair --
+    // Seeded with the hard-keyed pairs as well as the roots: a hard-keyed element
+    // deep in the tree is an entry point that its unmatched ancestors are not,
+    // which is why this is a queue over matched pairs and not a tree walk.
+    const queue = [...pairs];
+    const visited = new Set();
+    while (queue.length > 0) {
+        const next = queue.shift();
+        if (!next)
+            break;
+        const [beforeParent, afterParent] = next;
+        if (visited.has(beforeParent))
+            continue;
+        visited.add(beforeParent);
+        const bParent = before.byId.get(beforeParent);
+        const aParent = after.byId.get(afterParent);
+        if (!bParent || !aParent)
+            continue;
+        const bKids = bParent.childIds.filter((id) => !pairs.has(id));
+        const aKids = aParent.childIds.filter((id) => !reverse.has(id));
+        const candidates = [];
+        for (const bid of bKids) {
+            const b = before.byId.get(bid);
+            if (!b)
+                continue;
+            for (const aid of aKids) {
+                const a = after.byId.get(aid);
+                if (!a)
+                    continue;
+                const score = similarity(b, a, {
+                    ordinalA: before.ordinal.get(bid),
+                    ordinalB: after.ordinal.get(aid),
+                    subtreeTextA: before.subtreeText.get(bid),
+                    subtreeTextB: after.subtreeText.get(aid),
+                });
+                if (score < MATCH_THRESHOLD)
+                    continue;
+                candidates.push({ bid, aid, score: score + geometryTiebreak(b, a) });
+            }
+        }
+        candidates.sort((x, y) => y.score - x.score);
+        const takenBefore = new Set();
+        const takenAfter = new Set();
+        for (const candidate of candidates) {
+            if (takenBefore.has(candidate.bid) || takenAfter.has(candidate.aid))
+                continue;
+            takenBefore.add(candidate.bid);
+            takenAfter.add(candidate.aid);
+            link(candidate.bid, candidate.aid);
+        }
+        for (const bid of bParent.childIds) {
+            const aid = pairs.get(bid);
+            if (aid)
+                queue.push([bid, aid]);
+        }
+    }
+    return { pairs, reverse };
+}