@michaelmagan/dnumb 0.1.0

package/dist/diff/identity.cjs

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MATCH_THRESHOLD = exports.WEAK_ROLES = void 0;
+exports.isGeneratedId = isGeneratedId;
+exports.hardKey = hardKey;
+exports.textSimilarity = textSimilarity;
+exports.similarity = similarity;
+exports.geometryTiebreak = geometryTiebreak;
+/** qain's set, verbatim. Roles too generic to identify anything. */
+exports.WEAK_ROLES = new Set([
+    'generic',
+    'none',
+    'presentation',
+    'GenericContainer',
+    'InlineTextBox',
+]);
+/**
+ * Ids that differ between two renders of the identical page.
+ *
+ * No source in the step-1 prior-art read has this guard: qain trusts `#id`
+ * unconditionally, and browser-use's dynamic filter covers classes only. React
+ * 18's `useId`, Radix, Headless UI, MUI, Emotion, styled-components and Angular
+ * all emit ids that change on every render, and treating one as a stable key
+ * makes an unchanged element look replaced.
+ */
+const GENERATED_ID = [
+    /:/, // React 18 useId -> ":r0:", ":R1mcq:"; Radix and Headless UI wrap it
+    /^mui-\d+$/,
+    /^ember\d+$/,
+    /^ng-tns-c\d+-\d+$/,
+    /^_ngcontent-\w+-c\d+$/,
+    /^css-[0-9a-z]{6,}$/i,
+    /^sc-[A-Za-z]{6,}$/,
+    /^[0-9a-f]{8,}$/i, // a bare hex or uuid run
+];
+function isGeneratedId(id) {
+    return GENERATED_ID.some((pattern) => pattern.test(id));
+}
+/**
+ * Rungs 1 and 2: a key identifying the element wherever it sits.
+ *
+ * `null` when the element offers nothing document-unique and trustworthy, in
+ * which case it falls through to the scored rungs.
+ */
+function hardKey(el) {
+    if (el.testId)
+        return `@${el.testId}`;
+    if (el.domId && !isGeneratedId(el.domId))
+        return `#${el.domId}`;
+    return null;
+}
+/**
+ * Feature weights.
+ *
+ * Similo's table puts location, area and shape in its lowest tier (0.5) even
+ * for its own task, which is finding an element on a page that is *supposed* to
+ * be unchanged. Here they are absent entirely; the rest is scaled around role
+ * and accessible name being the strongest available evidence of sameness.
+ */
+const W = {
+    role: 2.0,
+    name: 2.0,
+    tag: 1.5,
+    ownText: 1.0,
+    subtreeText: 1.0,
+    ordinal: 0.5,
+};
+const normalise = (s) => (s ?? '').replace(/\s+/g, ' ').trim().toLowerCase();
+/**
+ * Levenshtein similarity in [0, 1], or `null` when neither side has the feature
+ * at all — which is different from both sides having it and disagreeing, and
+ * has to be, or two elements with no accessible name would be punished for it.
+ *
+ * Inputs are capped at 80 characters upstream, so O(n·m) is fine.
+ */
+function textSimilarity(a, b) {
+    const x = normalise(a);
+    const y = normalise(b);
+    if (!x && !y)
+        return null;
+    if (!x || !y)
+        return 0;
+    if (x === y)
+        return 1;
+    const m = x.length;
+    const n = y.length;
+    let previous = Array.from({ length: n + 1 }, (_, j) => j);
+    for (let i = 1; i <= m; i++) {
+        const current = [i];
+        for (let j = 1; j <= n; j++) {
+            const substitution = (previous[j - 1] ?? 0) + (x[i - 1] === y[j - 1] ? 0 : 1);
+            current[j] = Math.min((previous[j] ?? 0) + 1, (current[j - 1] ?? 0) + 1, substitution);
+        }
+        previous = current;
+    }
+    return 1 - (previous[n] ?? 0) / Math.max(m, n);
+}
+const usableRole = (el) => el.role && !exports.WEAK_ROLES.has(el.role) ? el.role : null;
+/**
+ * Rungs 3 and 4, as a normalised score in [0, 1].
+ *
+ * The denominator is the sum of weights of *applicable* features — those where
+ * at least one side has a value. Two bare divs therefore score 1.0 on tag and
+ * ordinal alone rather than being punished for having no role or name.
+ */
+function similarity(a, b, input) {
+    let got = 0;
+    let possible = 0;
+    const roleA = usableRole(a);
+    const roleB = usableRole(b);
+    if (roleA || roleB) {
+        possible += W.role;
+        if (roleA && roleA === roleB)
+            got += W.role;
+    }
+    const nameSimilarity = textSimilarity(a.name, b.name);
+    if (nameSimilarity !== null) {
+        possible += W.name;
+        got += W.name * nameSimilarity;
+    }
+    possible += W.tag;
+    if (a.tag === b.tag)
+        got += W.tag;
+    const ownSimilarity = textSimilarity(a.text, b.text);
+    if (ownSimilarity !== null) {
+        possible += W.ownText;
+        got += W.ownText * ownSimilarity;
+    }
+    // Subtree text is a weighted feature with a graded comparator, never part of
+    // a key, and it never propagates into a parent's identity. That is the whole
+    // difference between it and the text-hash approach the critique showed
+    // cascading: there, one child's text edit re-keyed its ancestors.
+    const subtreeSimilarity = textSimilarity(input.subtreeTextA, input.subtreeTextB);
+    if (subtreeSimilarity !== null) {
+        possible += W.subtreeText;
+        got += W.subtreeText * subtreeSimilarity;
+    }
+    possible += W.ordinal;
+    if (input.ordinalA === input.ordinalB)
+        got += W.ordinal;
+    return possible === 0 ? 0 : got / possible;
+}
+/**
+ * A tiebreak, and only a tiebreak.
+ *
+ * Geometry is the payload being diffed. Score it and an element that moved far
+ * enough scores worse against itself than against some stationary neighbour, so
+ * the diff reports a removal plus an addition — erasing the single line the
+ * whole tool exists to print, and doing it *more* the bigger the layout change
+ * is. That is the wrong direction on every axis.
+ *
+ * Scaled to 1e-6 so it can only order candidates that already scored equal —
+ * three identical Delete buttons in a table row, where position is genuinely
+ * the only discriminator — and can never outvote role and name.
+ */
+function geometryTiebreak(a, b) {
+    const dx = a.rect.x - b.rect.x;
+    const dy = a.rect.y - b.rect.y;
+    return 1e-6 / (1 + Math.sqrt(dx * dx + dy * dy));
+}
+/**
+ * Below this, two elements are not the same thing. Deliberately permissive:
+ * a missed match costs a phantom add plus a phantom remove, which is two wrong
+ * lines, while a wrong match costs one wrong line. The renderer can survive a
+ * loose match; it cannot reconstruct a missed one.
+ */
+exports.MATCH_THRESHOLD = 0.5;

package/dist/diff/identity.d.cts

@@ -0,0 +1,62 @@
+/**
+ * Element identity across two captures. The ladder from
+ * `docs/notes/01-identity-ladder.md`, made executable.
+ *
+ * Two hard rungs resolved before any scoring, then a scored match. The
+ * counter-intuitive part, and the one thing here most likely to be "fixed" back
+ * into a bug: **geometry is never a scoring feature.** See `geometryTiebreak`.
+ */
+import type { ElementRecord } from "../snapshot/types.cjs";
+/** qain's set, verbatim. Roles too generic to identify anything. */
+export declare const WEAK_ROLES: ReadonlySet<string>;
+export declare function isGeneratedId(id: string): boolean;
+/**
+ * Rungs 1 and 2: a key identifying the element wherever it sits.
+ *
+ * `null` when the element offers nothing document-unique and trustworthy, in
+ * which case it falls through to the scored rungs.
+ */
+export declare function hardKey(el: ElementRecord): string | null;
+/**
+ * Levenshtein similarity in [0, 1], or `null` when neither side has the feature
+ * at all — which is different from both sides having it and disagreeing, and
+ * has to be, or two elements with no accessible name would be punished for it.
+ *
+ * Inputs are capped at 80 characters upstream, so O(n·m) is fine.
+ */
+export declare function textSimilarity(a: string | null | undefined, b: string | null | undefined): number | null;
+export interface SimilarityInput {
+    ordinalA: number | undefined;
+    ordinalB: number | undefined;
+    subtreeTextA: string | undefined;
+    subtreeTextB: string | undefined;
+}
+/**
+ * Rungs 3 and 4, as a normalised score in [0, 1].
+ *
+ * The denominator is the sum of weights of *applicable* features — those where
+ * at least one side has a value. Two bare divs therefore score 1.0 on tag and
+ * ordinal alone rather than being punished for having no role or name.
+ */
+export declare function similarity(a: ElementRecord, b: ElementRecord, input: SimilarityInput): number;
+/**
+ * A tiebreak, and only a tiebreak.
+ *
+ * Geometry is the payload being diffed. Score it and an element that moved far
+ * enough scores worse against itself than against some stationary neighbour, so
+ * the diff reports a removal plus an addition — erasing the single line the
+ * whole tool exists to print, and doing it *more* the bigger the layout change
+ * is. That is the wrong direction on every axis.
+ *
+ * Scaled to 1e-6 so it can only order candidates that already scored equal —
+ * three identical Delete buttons in a table row, where position is genuinely
+ * the only discriminator — and can never outvote role and name.
+ */
+export declare function geometryTiebreak(a: ElementRecord, b: ElementRecord): number;
+/**
+ * Below this, two elements are not the same thing. Deliberately permissive:
+ * a missed match costs a phantom add plus a phantom remove, which is two wrong
+ * lines, while a wrong match costs one wrong line. The renderer can survive a
+ * loose match; it cannot reconstruct a missed one.
+ */
+export declare const MATCH_THRESHOLD = 0.5;

package/dist/diff/identity.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Element identity across two captures. The ladder from
+ * `docs/notes/01-identity-ladder.md`, made executable.
+ *
+ * Two hard rungs resolved before any scoring, then a scored match. The
+ * counter-intuitive part, and the one thing here most likely to be "fixed" back
+ * into a bug: **geometry is never a scoring feature.** See `geometryTiebreak`.
+ */
+import type { ElementRecord } from "../snapshot/types.js";
+/** qain's set, verbatim. Roles too generic to identify anything. */
+export declare const WEAK_ROLES: ReadonlySet<string>;
+export declare function isGeneratedId(id: string): boolean;
+/**
+ * Rungs 1 and 2: a key identifying the element wherever it sits.
+ *
+ * `null` when the element offers nothing document-unique and trustworthy, in
+ * which case it falls through to the scored rungs.
+ */
+export declare function hardKey(el: ElementRecord): string | null;
+/**
+ * Levenshtein similarity in [0, 1], or `null` when neither side has the feature
+ * at all — which is different from both sides having it and disagreeing, and
+ * has to be, or two elements with no accessible name would be punished for it.
+ *
+ * Inputs are capped at 80 characters upstream, so O(n·m) is fine.
+ */
+export declare function textSimilarity(a: string | null | undefined, b: string | null | undefined): number | null;
+export interface SimilarityInput {
+    ordinalA: number | undefined;
+    ordinalB: number | undefined;
+    subtreeTextA: string | undefined;
+    subtreeTextB: string | undefined;
+}
+/**
+ * Rungs 3 and 4, as a normalised score in [0, 1].
+ *
+ * The denominator is the sum of weights of *applicable* features — those where
+ * at least one side has a value. Two bare divs therefore score 1.0 on tag and
+ * ordinal alone rather than being punished for having no role or name.
+ */
+export declare function similarity(a: ElementRecord, b: ElementRecord, input: SimilarityInput): number;
+/**
+ * A tiebreak, and only a tiebreak.
+ *
+ * Geometry is the payload being diffed. Score it and an element that moved far
+ * enough scores worse against itself than against some stationary neighbour, so
+ * the diff reports a removal plus an addition — erasing the single line the
+ * whole tool exists to print, and doing it *more* the bigger the layout change
+ * is. That is the wrong direction on every axis.
+ *
+ * Scaled to 1e-6 so it can only order candidates that already scored equal —
+ * three identical Delete buttons in a table row, where position is genuinely
+ * the only discriminator — and can never outvote role and name.
+ */
+export declare function geometryTiebreak(a: ElementRecord, b: ElementRecord): number;
+/**
+ * Below this, two elements are not the same thing. Deliberately permissive:
+ * a missed match costs a phantom add plus a phantom remove, which is two wrong
+ * lines, while a wrong match costs one wrong line. The renderer can survive a
+ * loose match; it cannot reconstruct a missed one.
+ */
+export declare const MATCH_THRESHOLD = 0.5;

package/dist/diff/identity.js

@@ -0,0 +1,159 @@
+/** qain's set, verbatim. Roles too generic to identify anything. */
+export const WEAK_ROLES = new Set([
+    'generic',
+    'none',
+    'presentation',
+    'GenericContainer',
+    'InlineTextBox',
+]);
+/**
+ * Ids that differ between two renders of the identical page.
+ *
+ * No source in the step-1 prior-art read has this guard: qain trusts `#id`
+ * unconditionally, and browser-use's dynamic filter covers classes only. React
+ * 18's `useId`, Radix, Headless UI, MUI, Emotion, styled-components and Angular
+ * all emit ids that change on every render, and treating one as a stable key
+ * makes an unchanged element look replaced.
+ */
+const GENERATED_ID = [
+    /:/, // React 18 useId -> ":r0:", ":R1mcq:"; Radix and Headless UI wrap it
+    /^mui-\d+$/,
+    /^ember\d+$/,
+    /^ng-tns-c\d+-\d+$/,
+    /^_ngcontent-\w+-c\d+$/,
+    /^css-[0-9a-z]{6,}$/i,
+    /^sc-[A-Za-z]{6,}$/,
+    /^[0-9a-f]{8,}$/i, // a bare hex or uuid run
+];
+export function isGeneratedId(id) {
+    return GENERATED_ID.some((pattern) => pattern.test(id));
+}
+/**
+ * Rungs 1 and 2: a key identifying the element wherever it sits.
+ *
+ * `null` when the element offers nothing document-unique and trustworthy, in
+ * which case it falls through to the scored rungs.
+ */
+export function hardKey(el) {
+    if (el.testId)
+        return `@${el.testId}`;
+    if (el.domId && !isGeneratedId(el.domId))
+        return `#${el.domId}`;
+    return null;
+}
+/**
+ * Feature weights.
+ *
+ * Similo's table puts location, area and shape in its lowest tier (0.5) even
+ * for its own task, which is finding an element on a page that is *supposed* to
+ * be unchanged. Here they are absent entirely; the rest is scaled around role
+ * and accessible name being the strongest available evidence of sameness.
+ */
+const W = {
+    role: 2.0,
+    name: 2.0,
+    tag: 1.5,
+    ownText: 1.0,
+    subtreeText: 1.0,
+    ordinal: 0.5,
+};
+const normalise = (s) => (s ?? '').replace(/\s+/g, ' ').trim().toLowerCase();
+/**
+ * Levenshtein similarity in [0, 1], or `null` when neither side has the feature
+ * at all — which is different from both sides having it and disagreeing, and
+ * has to be, or two elements with no accessible name would be punished for it.
+ *
+ * Inputs are capped at 80 characters upstream, so O(n·m) is fine.
+ */
+export function textSimilarity(a, b) {
+    const x = normalise(a);
+    const y = normalise(b);
+    if (!x && !y)
+        return null;
+    if (!x || !y)
+        return 0;
+    if (x === y)
+        return 1;
+    const m = x.length;
+    const n = y.length;
+    let previous = Array.from({ length: n + 1 }, (_, j) => j);
+    for (let i = 1; i <= m; i++) {
+        const current = [i];
+        for (let j = 1; j <= n; j++) {
+            const substitution = (previous[j - 1] ?? 0) + (x[i - 1] === y[j - 1] ? 0 : 1);
+            current[j] = Math.min((previous[j] ?? 0) + 1, (current[j - 1] ?? 0) + 1, substitution);
+        }
+        previous = current;
+    }
+    return 1 - (previous[n] ?? 0) / Math.max(m, n);
+}
+const usableRole = (el) => el.role && !WEAK_ROLES.has(el.role) ? el.role : null;
+/**
+ * Rungs 3 and 4, as a normalised score in [0, 1].
+ *
+ * The denominator is the sum of weights of *applicable* features — those where
+ * at least one side has a value. Two bare divs therefore score 1.0 on tag and
+ * ordinal alone rather than being punished for having no role or name.
+ */
+export function similarity(a, b, input) {
+    let got = 0;
+    let possible = 0;
+    const roleA = usableRole(a);
+    const roleB = usableRole(b);
+    if (roleA || roleB) {
+        possible += W.role;
+        if (roleA && roleA === roleB)
+            got += W.role;
+    }
+    const nameSimilarity = textSimilarity(a.name, b.name);
+    if (nameSimilarity !== null) {
+        possible += W.name;
+        got += W.name * nameSimilarity;
+    }
+    possible += W.tag;
+    if (a.tag === b.tag)
+        got += W.tag;
+    const ownSimilarity = textSimilarity(a.text, b.text);
+    if (ownSimilarity !== null) {
+        possible += W.ownText;
+        got += W.ownText * ownSimilarity;
+    }
+    // Subtree text is a weighted feature with a graded comparator, never part of
+    // a key, and it never propagates into a parent's identity. That is the whole
+    // difference between it and the text-hash approach the critique showed
+    // cascading: there, one child's text edit re-keyed its ancestors.
+    const subtreeSimilarity = textSimilarity(input.subtreeTextA, input.subtreeTextB);
+    if (subtreeSimilarity !== null) {
+        possible += W.subtreeText;
+        got += W.subtreeText * subtreeSimilarity;
+    }
+    possible += W.ordinal;
+    if (input.ordinalA === input.ordinalB)
+        got += W.ordinal;
+    return possible === 0 ? 0 : got / possible;
+}
+/**
+ * A tiebreak, and only a tiebreak.
+ *
+ * Geometry is the payload being diffed. Score it and an element that moved far
+ * enough scores worse against itself than against some stationary neighbour, so
+ * the diff reports a removal plus an addition — erasing the single line the
+ * whole tool exists to print, and doing it *more* the bigger the layout change
+ * is. That is the wrong direction on every axis.
+ *
+ * Scaled to 1e-6 so it can only order candidates that already scored equal —
+ * three identical Delete buttons in a table row, where position is genuinely
+ * the only discriminator — and can never outvote role and name.
+ */
+export function geometryTiebreak(a, b) {
+    const dx = a.rect.x - b.rect.x;
+    const dy = a.rect.y - b.rect.y;
+    return 1e-6 / (1 + Math.sqrt(dx * dx + dy * dy));
+}
+/**
+ * Below this, two elements are not the same thing. Deliberately permissive:
+ * a missed match costs a phantom add plus a phantom remove, which is two wrong
+ * lines, while a wrong match costs one wrong line. The renderer can survive a
+ * loose match; it cannot reconstruct a missed one.
+ */
+export const MATCH_THRESHOLD = 0.5;

package/dist/diff/index.cjs

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiffViewportMismatchError = exports.renderDiff = exports.prepare = exports.match = exports.WEAK_ROLES = exports.textSimilarity = exports.similarity = exports.MATCH_THRESHOLD = exports.isGeneratedId = exports.hardKey = exports.geometryTiebreak = exports.computeChanges = void 0;
+exports.diffCaptures = diffCaptures;
+const changes_js_1 = require("./changes.cjs");
+const match_js_1 = require("./match.cjs");
+const render_js_1 = require("./render.cjs");
+var changes_js_2 = require("./changes.cjs");
+Object.defineProperty(exports, "computeChanges", { enumerable: true, get: function () { return changes_js_2.computeChanges; } });
+var identity_js_1 = require("./identity.cjs");
+Object.defineProperty(exports, "geometryTiebreak", { enumerable: true, get: function () { return identity_js_1.geometryTiebreak; } });
+Object.defineProperty(exports, "hardKey", { enumerable: true, get: function () { return identity_js_1.hardKey; } });
+Object.defineProperty(exports, "isGeneratedId", { enumerable: true, get: function () { return identity_js_1.isGeneratedId; } });
+Object.defineProperty(exports, "MATCH_THRESHOLD", { enumerable: true, get: function () { return identity_js_1.MATCH_THRESHOLD; } });
+Object.defineProperty(exports, "similarity", { enumerable: true, get: function () { return identity_js_1.similarity; } });
+Object.defineProperty(exports, "textSimilarity", { enumerable: true, get: function () { return identity_js_1.textSimilarity; } });
+Object.defineProperty(exports, "WEAK_ROLES", { enumerable: true, get: function () { return identity_js_1.WEAK_ROLES; } });
+var match_js_2 = require("./match.cjs");
+Object.defineProperty(exports, "match", { enumerable: true, get: function () { return match_js_2.match; } });
+Object.defineProperty(exports, "prepare", { enumerable: true, get: function () { return match_js_2.prepare; } });
+var render_js_2 = require("./render.cjs");
+Object.defineProperty(exports, "renderDiff", { enumerable: true, get: function () { return render_js_2.renderDiff; } });
+/**
+ * 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.
+ */
+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;
+    }
+}
+exports.DiffViewportMismatchError = DiffViewportMismatchError;
+/**
+ * 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.
+ */
+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 = (0, match_js_1.prepare)(before);
+    const preparedAfter = (0, match_js_1.prepare)(after);
+    const matched = (0, match_js_1.match)(preparedBefore, preparedAfter);
+    const changes = (0, changes_js_1.computeChanges)(preparedBefore, preparedAfter, matched);
+    const viewport = (snapshot) => `${snapshot.viewport.width}x${snapshot.viewport.height}`;
+    const text = (0, render_js_1.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/index.d.cts

@@ -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.cjs";
+import type { DiffOptions, DiffResult } from "./types.cjs";
+export { computeChanges } from "./changes.cjs";
+export { geometryTiebreak, hardKey, isGeneratedId, MATCH_THRESHOLD, similarity, textSimilarity, WEAK_ROLES, } from "./identity.cjs";
+export { match, prepare } from "./match.cjs";
+export { renderDiff } from "./render.cjs";
+export type { BoxDelta, Cause, Change, ChangeKind, Derivation, DiffMeta, DiffOptions, DiffResult, Match, Prepared, Subsumption, } from "./types.cjs";
+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;