dungbeetle 0.1.1

package/dist/desktop/ocr.d.ts

@@ -0,0 +1,17 @@
+import type { MaskRule } from "../config.js";
+import { type DesktopSnapshot } from "./a11y.js";
+export type ShellRunner = (command: string, options: {
+    cwd: string;
+    timeoutMs: number;
+}) => Promise<string>;
+export type DesktopOcrOptions = {
+    app?: string;
+    screenshot?: string;
+    screenshotCommand?: string;
+    ocrCommand?: string;
+    cwd: string;
+    timeoutMs: number;
+    maskRules: MaskRule[];
+    run?: ShellRunner;
+};
+export declare function captureDesktopOcr(options: DesktopOcrOptions): Promise<DesktopSnapshot>;

package/dist/desktop/ocr.js

@@ -0,0 +1,99 @@
+import { exec } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { normalizeA11yTree } from "./a11y.js";
+const execAsync = promisify(exec);
+// Screenshot + OCR fallback for desktop targets without reliable structured
+// (accessibility) access. Following the same shell-out philosophy as the
+// macos-ax and `command` drivers, the pixels never become a bundled dependency:
+// a screenshot command captures an image and an OCR command turns it into text.
+// The recognized lines are normalized into the *same* desktop a11y snapshot the
+// structured path produces — one AXStaticText node per line — so the existing
+// desktop comparer diffs OCR output with no special-casing.
+// Default OCR command. Tesseract is the de-facto open-source OCR CLI; `{image}`
+// is replaced with the screenshot path. Override via the target's `ocrCommand`.
+const DEFAULT_OCR_COMMAND = "tesseract {image} stdout";
+export async function captureDesktopOcr(options) {
+    const run = options.run ?? defaultRun;
+    let tempDir;
+    let imagePath;
+    if (options.screenshot) {
+        imagePath = path.resolve(options.cwd, options.screenshot);
+    }
+    else if (options.screenshotCommand) {
+        tempDir = await mkdtemp(path.join(os.tmpdir(), "dungbeetle-ocr-"));
+        imagePath = path.join(tempDir, "screenshot.png");
+        const command = options.screenshotCommand.replace(/\{out\}/g, shellQuote(imagePath));
+        try {
+            await run(command, { cwd: options.cwd, timeoutMs: options.timeoutMs });
+        }
+        catch (error) {
+            await cleanup(tempDir);
+            throw new Error(`Desktop screenshot command failed: ${messageOf(error)}`);
+        }
+    }
+    else {
+        throw new Error('Desktop OCR needs a "screenshot" file or a "screenshotCommand".');
+    }
+    try {
+        const ocrCommand = (options.ocrCommand ?? DEFAULT_OCR_COMMAND).replace(/\{image\}/g, shellQuote(imagePath));
+        let text;
+        try {
+            text = await run(ocrCommand, { cwd: options.cwd, timeoutMs: options.timeoutMs });
+        }
+        catch (error) {
+            throw new Error(translateOcrError(error, options.ocrCommand));
+        }
+        return ocrTextToSnapshot(text, options.app, options.maskRules);
+    }
+    finally {
+        if (tempDir) {
+            await cleanup(tempDir);
+        }
+    }
+}
+// Build a desktop snapshot from recognized text: collapse whitespace, drop blank
+// lines, and emit one AXStaticText leaf per line under a synthetic app root.
+// Routing the raw tree through normalizeA11yTree reuses masking + normalization,
+// and tags `tool: "ocr"` so a reader can tell pixels-derived snapshots apart.
+function ocrTextToSnapshot(text, app, maskRules) {
+    const lines = text
+        .split(/\r?\n/)
+        .map((line) => line.replace(/\s+/g, " ").trim())
+        .filter((line) => line.length > 0);
+    const root = {
+        role: "AXApplication",
+        children: lines.map((line) => ({ role: "AXStaticText", value: line }))
+    };
+    if (app) {
+        root.name = app;
+    }
+    return normalizeA11yTree({ tool: "ocr", root }, { maskRules });
+}
+async function defaultRun(command, options) {
+    const { stdout } = await execAsync(command, {
+        cwd: options.cwd,
+        timeout: options.timeoutMs,
+        maxBuffer: 32 * 1024 * 1024
+    });
+    return stdout;
+}
+// POSIX single-quote quoting so a screenshot path with spaces survives the shell.
+function shellQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+async function cleanup(dir) {
+    await rm(dir, { recursive: true, force: true });
+}
+function translateOcrError(error, ocrCommand) {
+    const message = messageOf(error);
+    if (!ocrCommand && /ENOENT|not found|not recognized/i.test(message)) {
+        return 'OCR failed: "tesseract" was not found. Install Tesseract OCR, or set "ocrCommand" to your own OCR tool (use {image} for the screenshot path).';
+    }
+    return `OCR command failed: ${message}`;
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/diff/lcs.d.ts

@@ -0,0 +1,5 @@
+export declare function buildLcsTable<T>(left: T[], right: T[], eq?: (a: T, b: T) => boolean): number[][];
+export declare function lcsPairs<T>(left: T[], right: T[], eq?: (a: T, b: T) => boolean): Array<{
+    i: number;
+    j: number;
+}>;

package/dist/diff/lcs.js

@@ -0,0 +1,42 @@
+// Single longest-common-subsequence implementation shared by the text (token)
+// and DOM-tree diffs. Previously this table was hand-rolled in three places
+// (the line, token, and tree diffs) with copies that had already drifted.
+// Bottom-up LCS length table: table[i][j] is the LCS length of left[i:] and
+// right[j:]. `eq` defaults to strict equality (used for string tokens/keys).
+export function buildLcsTable(left, right, eq = (a, b) => a === b) {
+    const table = Array.from({ length: left.length + 1 }, () => new Array(right.length + 1).fill(0));
+    for (let i = left.length - 1; i >= 0; i -= 1) {
+        for (let j = right.length - 1; j >= 0; j -= 1) {
+            const row = table[i];
+            if (eq(left[i], right[j])) {
+                row[j] = (table[i + 1]?.[j + 1] ?? 0) + 1;
+            }
+            else {
+                row[j] = Math.max(table[i + 1]?.[j] ?? 0, table[i]?.[j + 1] ?? 0);
+            }
+        }
+    }
+    return table;
+}
+// The index pairs (i in left, j in right) of a longest common subsequence, in
+// order — what the tree diff aligns on.
+export function lcsPairs(left, right, eq = (a, b) => a === b) {
+    const table = buildLcsTable(left, right, eq);
+    const pairs = [];
+    let i = 0;
+    let j = 0;
+    while (i < left.length && j < right.length) {
+        if (eq(left[i], right[j])) {
+            pairs.push({ i, j });
+            i += 1;
+            j += 1;
+        }
+        else if ((table[i + 1]?.[j] ?? 0) >= (table[i]?.[j + 1] ?? 0)) {
+            i += 1;
+        }
+        else {
+            j += 1;
+        }
+    }
+    return pairs;
+}

package/dist/diff/numeric.d.ts

@@ -0,0 +1,6 @@
+export type NumericTolerance = {
+    absolute?: number;
+    relative?: number;
+};
+export declare function numbersWithinTolerance(left: number, right: number, tolerance?: NumericTolerance): boolean;
+export declare function isNumericTolerant(tolerance: NumericTolerance | undefined): boolean;

package/dist/diff/numeric.js

@@ -0,0 +1,24 @@
+// Two numbers are "equal enough" when they are exactly equal, or within an
+// absolute and/or relative epsilon. With no tolerance configured (both 0) this
+// collapses to strict equality, keeping default behavior exact.
+export function numbersWithinTolerance(left, right, tolerance = {}) {
+    if (left === right) {
+        return true;
+    }
+    if (!Number.isFinite(left) || !Number.isFinite(right)) {
+        return false;
+    }
+    const absolute = tolerance.absolute ?? 0;
+    const relative = tolerance.relative ?? 0;
+    const delta = Math.abs(left - right);
+    if (absolute > 0 && delta <= absolute) {
+        return true;
+    }
+    if (relative > 0 && delta <= relative * Math.max(Math.abs(left), Math.abs(right))) {
+        return true;
+    }
+    return false;
+}
+export function isNumericTolerant(tolerance) {
+    return Boolean(tolerance && ((tolerance.absolute ?? 0) > 0 || (tolerance.relative ?? 0) > 0));
+}

package/dist/diff/pixel.d.ts

@@ -0,0 +1,23 @@
+export type PixelTolerance = {
+    maxChangedRatio?: number;
+    perChannelThreshold?: number;
+};
+export type PixelDiffResult = {
+    width: number;
+    height: number;
+    dimensionsMatch: boolean;
+    totalPixels: number;
+    changedPixels: number;
+    changedRatio: number;
+    withinTolerance: boolean;
+};
+export type DecodedImage = {
+    width: number;
+    height: number;
+    data: Uint8Array;
+};
+export declare function decodePng(buffer: Buffer): DecodedImage;
+export declare function encodePng(image: DecodedImage): Buffer;
+export declare function diffPng(before: Buffer, after: Buffer, tolerance?: PixelTolerance): PixelDiffResult;
+export declare function diffImages(before: DecodedImage, after: DecodedImage, tolerance?: PixelTolerance): PixelDiffResult;
+export declare function renderDiffImage(before: DecodedImage, after: DecodedImage, tolerance?: PixelTolerance): Buffer | undefined;

package/dist/diff/pixel.js

@@ -0,0 +1,97 @@
+import { PNG } from "pngjs";
+// PNG decode/encode is delegated to `pngjs` (a vetted dependency) rather than
+// hand-rolled: it handles interlacing, 16-bit, and palette images, and rejects
+// malformed input loudly. The diff and overlay logic below works on the decoded
+// RGBA buffer and is independent of the codec.
+export function decodePng(buffer) {
+    const png = PNG.sync.read(buffer);
+    return { width: png.width, height: png.height, data: png.data };
+}
+export function encodePng(image) {
+    const png = new PNG({ width: image.width, height: image.height });
+    png.data = Buffer.from(image.data);
+    return PNG.sync.write(png);
+}
+export function diffPng(before, after, tolerance = {}) {
+    return diffImages(decodePng(before), decodePng(after), tolerance);
+}
+export function diffImages(before, after, tolerance = {}) {
+    const perChannelThreshold = tolerance.perChannelThreshold ?? 0;
+    const maxChangedRatio = tolerance.maxChangedRatio ?? 0;
+    const dimensionsMatch = before.width === after.width && before.height === after.height;
+    if (!dimensionsMatch) {
+        const totalPixels = Math.max(before.width * before.height, after.width * after.height);
+        return {
+            width: after.width,
+            height: after.height,
+            dimensionsMatch: false,
+            totalPixels,
+            changedPixels: totalPixels,
+            changedRatio: 1,
+            withinTolerance: false
+        };
+    }
+    const totalPixels = before.width * before.height;
+    let changedPixels = 0;
+    for (let pixel = 0; pixel < totalPixels; pixel += 1) {
+        const offset = pixel * 4;
+        if (channelDelta(before.data, after.data, offset) > perChannelThreshold ||
+            channelDelta(before.data, after.data, offset + 1) > perChannelThreshold ||
+            channelDelta(before.data, after.data, offset + 2) > perChannelThreshold ||
+            channelDelta(before.data, after.data, offset + 3) > perChannelThreshold) {
+            changedPixels += 1;
+        }
+    }
+    const changedRatio = totalPixels === 0 ? 0 : changedPixels / totalPixels;
+    return {
+        width: before.width,
+        height: before.height,
+        dimensionsMatch: true,
+        totalPixels,
+        changedPixels,
+        changedRatio,
+        withinTolerance: changedRatio <= maxChangedRatio
+    };
+}
+// Render a human-facing diff overlay: changed pixels are painted solid red on
+// top of a faint ghost of the "after" image, so the regression is obvious at a
+// glance. Takes already-decoded images so the diff path decodes each PNG once.
+// Returns undefined when the two images differ in size (there is no meaningful
+// per-pixel overlay), in which case callers fall back to showing the
+// before/after images alone.
+export function renderDiffImage(before, after, tolerance = {}) {
+    if (before.width !== after.width || before.height !== after.height) {
+        return undefined;
+    }
+    const threshold = tolerance.perChannelThreshold ?? 0;
+    const { width, height } = before;
+    const out = new Uint8Array(width * height * 4);
+    for (let pixel = 0; pixel < width * height; pixel += 1) {
+        const offset = pixel * 4;
+        const changed = channelDelta(before.data, after.data, offset) > threshold ||
+            channelDelta(before.data, after.data, offset + 1) > threshold ||
+            channelDelta(before.data, after.data, offset + 2) > threshold ||
+            channelDelta(before.data, after.data, offset + 3) > threshold;
+        if (changed) {
+            out[offset] = 255;
+            out[offset + 1] = 0;
+            out[offset + 2] = 0;
+            out[offset + 3] = 255;
+        }
+        else {
+            const gray = ((after.data[offset] ?? 0) +
+                (after.data[offset + 1] ?? 0) +
+                (after.data[offset + 2] ?? 0)) /
+                3;
+            const ghost = Math.round(gray * 0.25 + 191);
+            out[offset] = ghost;
+            out[offset + 1] = ghost;
+            out[offset + 2] = ghost;
+            out[offset + 3] = 255;
+        }
+    }
+    return encodePng({ width, height, data: out });
+}
+function channelDelta(left, right, index) {
+    return Math.abs((left[index] ?? 0) - (right[index] ?? 0));
+}

package/dist/diff/structural.d.ts

@@ -0,0 +1,11 @@
+import { type NumericTolerance } from "./numeric.js";
+export type StructuralChange = {
+    path: string;
+    before: unknown;
+    after: unknown;
+};
+export type StructuralOptions = {
+    numericTolerance?: NumericTolerance;
+};
+export declare function structuralChanges(left: unknown, right: unknown, options?: StructuralOptions): StructuralChange[];
+export declare function structuralEqual(left: unknown, right: unknown, options?: StructuralOptions): boolean;

package/dist/diff/structural.js

@@ -0,0 +1,38 @@
+import { numbersWithinTolerance } from "./numeric.js";
+import { isRecord } from "../guards.js";
+// Deep structural comparison that understands numeric tolerance: two snapshots
+// are equal when they have the same shape and every leaf matches (numbers within
+// tolerance, everything else strictly). Returns the leaf paths that differ.
+export function structuralChanges(left, right, options = {}) {
+    const changes = [];
+    walk(left, right, "$", options, changes);
+    return changes;
+}
+export function structuralEqual(left, right, options = {}) {
+    return structuralChanges(left, right, options).length === 0;
+}
+function walk(left, right, path, options, changes) {
+    if (typeof left === "number" && typeof right === "number") {
+        if (!numbersWithinTolerance(left, right, options.numericTolerance)) {
+            changes.push({ path, before: left, after: right });
+        }
+        return;
+    }
+    if (Array.isArray(left) && Array.isArray(right)) {
+        const length = Math.max(left.length, right.length);
+        for (let index = 0; index < length; index += 1) {
+            walk(left[index], right[index], `${path}[${index}]`, options, changes);
+        }
+        return;
+    }
+    if (isRecord(left) && isRecord(right)) {
+        const keys = new Set([...Object.keys(left), ...Object.keys(right)]);
+        for (const key of [...keys].sort()) {
+            walk(left[key], right[key], `${path}.${key}`, options, changes);
+        }
+        return;
+    }
+    if (!Object.is(left, right)) {
+        changes.push({ path, before: left, after: right });
+    }
+}

package/dist/diff/text.d.ts

@@ -0,0 +1,7 @@
+export type InlineOp = {
+    kind: "equal" | "insert" | "delete";
+    value: string;
+};
+export declare function diffTokens(left: string[], right: string[]): InlineOp[];
+export declare function diffWords(left: string, right: string): InlineOp[];
+export declare function renderInline(ops: InlineOp[]): string;

package/dist/diff/text.js

@@ -0,0 +1,64 @@
+import { buildLcsTable } from "./lcs.js";
+// Token-level LCS diff. Shared by the word and character diffs below — the only
+// difference is how the input strings are split into tokens.
+export function diffTokens(left, right) {
+    const table = buildLcsTable(left, right);
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < left.length && j < right.length) {
+        if (left[i] === right[j]) {
+            pushOp(ops, "equal", left[i]);
+            i += 1;
+            j += 1;
+        }
+        else if ((table[i + 1]?.[j] ?? 0) >= (table[i]?.[j + 1] ?? 0)) {
+            pushOp(ops, "delete", left[i]);
+            i += 1;
+        }
+        else {
+            pushOp(ops, "insert", right[j]);
+            j += 1;
+        }
+    }
+    while (i < left.length) {
+        pushOp(ops, "delete", left[i]);
+        i += 1;
+    }
+    while (j < right.length) {
+        pushOp(ops, "insert", right[j]);
+        j += 1;
+    }
+    return ops;
+}
+export function diffWords(left, right) {
+    return diffTokens(tokenizeWords(left), tokenizeWords(right));
+}
+// Renders inline ops with readable markers: insertions in {+ +}, deletions in
+// [- -]. Adjacent same-kind tokens are already merged by pushOp.
+export function renderInline(ops) {
+    return ops
+        .map((op) => {
+        if (op.kind === "insert") {
+            return `{+${op.value}+}`;
+        }
+        if (op.kind === "delete") {
+            return `[-${op.value}-]`;
+        }
+        return op.value;
+    })
+        .join("");
+}
+// Splits into a sequence of word and whitespace tokens, preserving whitespace so
+// the diff can be rendered back into readable text.
+function tokenizeWords(value) {
+    return value.match(/\s+|\S+/g) ?? [];
+}
+function pushOp(ops, kind, value) {
+    const last = ops[ops.length - 1];
+    if (last && last.kind === kind) {
+        last.value += value;
+        return;
+    }
+    ops.push({ kind, value });
+}

package/dist/diff/tree.d.ts

@@ -0,0 +1,46 @@
+import type { DomSnapshotNode } from "../web/domSnapshot.js";
+export type TreeChange = {
+    type: "added";
+    path: string;
+    summary: string;
+} | {
+    type: "removed";
+    path: string;
+    summary: string;
+} | {
+    type: "moved";
+    path: string;
+    summary: string;
+} | {
+    type: "text-changed";
+    path: string;
+    before: string;
+    after: string;
+} | {
+    type: "tag-changed";
+    path: string;
+    before: string;
+    after: string;
+} | {
+    type: "attribute-added";
+    path: string;
+    name: string;
+    value: string;
+} | {
+    type: "attribute-removed";
+    path: string;
+    name: string;
+    value: string;
+} | {
+    type: "attribute-changed";
+    path: string;
+    name: string;
+    before: string;
+    after: string;
+};
+export type TreeDiff = {
+    equal: boolean;
+    changes: TreeChange[];
+};
+export declare function diffDomTrees(before: DomSnapshotNode[], after: DomSnapshotNode[]): TreeDiff;
+export declare function renderTreeChanges(changes: TreeChange[]): string;

package/dist/diff/tree.js

@@ -0,0 +1,188 @@
+import { lcsPairs } from "./lcs.js";
+// Structural DOM diff: aligns children by a stable signature (tag + id, or
+// "#text") so insertions/removals don't cascade, recurses matched pairs to find
+// attribute/text/tag changes, and re-classifies a removed+added pair with an
+// identical subtree as a "moved" node.
+export function diffDomTrees(before, after) {
+    const changes = [];
+    diffChildren(before, after, "", changes);
+    return { equal: changes.length === 0, changes };
+}
+// Two-phase alignment. Phase 1 anchors byte-identical subtrees (LCS over deep
+// signatures) so a pure insertion or a reorder doesn't cascade into spurious
+// changes. Phase 2 pairs the leftover nodes in each gap by shallow signature
+// (tag + id) so a container whose descendant changed is still matched and
+// recursed, surfacing attribute/text/tag changes rather than remove + add.
+function diffChildren(before, after, basePath, changes) {
+    const anchors = lcsPairs(before.map(subtreeSignature), after.map(subtreeSignature));
+    const removed = [];
+    const added = [];
+    let beforeCursor = 0;
+    let afterCursor = 0;
+    for (const anchor of [...anchors, { i: before.length, j: after.length }]) {
+        pairGap(before, after, beforeCursor, anchor.i, afterCursor, anchor.j, basePath, changes, removed, added);
+        beforeCursor = anchor.i + 1;
+        afterCursor = anchor.j + 1;
+    }
+    reconcileMoves(removed, added, basePath, changes);
+}
+// Aligns the leftover nodes between two anchors by shallow signature, recursing
+// matched pairs and collecting the rest as candidate removals/additions.
+function pairGap(before, after, beforeStart, beforeEnd, afterStart, afterEnd, basePath, changes, removed, added) {
+    const leftKeys = [];
+    for (let k = beforeStart; k < beforeEnd; k += 1) {
+        leftKeys.push(alignKey(before[k]));
+    }
+    const rightKeys = [];
+    for (let k = afterStart; k < afterEnd; k += 1) {
+        rightKeys.push(alignKey(after[k]));
+    }
+    const pairs = lcsPairs(leftKeys, rightKeys);
+    const matchedLeft = new Set();
+    const matchedRight = new Set();
+    for (const pair of pairs) {
+        const beforeIndex = beforeStart + pair.i;
+        const afterIndex = afterStart + pair.j;
+        matchedLeft.add(beforeIndex);
+        matchedRight.add(afterIndex);
+        diffNode(before[beforeIndex], after[afterIndex], childPath(basePath, after[afterIndex], afterIndex), changes);
+    }
+    for (let k = beforeStart; k < beforeEnd; k += 1) {
+        if (!matchedLeft.has(k)) {
+            removed.push({ node: before[k], index: k });
+        }
+    }
+    for (let k = afterStart; k < afterEnd; k += 1) {
+        if (!matchedRight.has(k)) {
+            added.push({ node: after[k], index: k });
+        }
+    }
+}
+// A removed node and an added node with byte-identical subtrees are a move, not
+// an unrelated delete + insert.
+function reconcileMoves(removed, added, basePath, changes) {
+    const remaining = [...added];
+    for (const drop of removed) {
+        const signature = subtreeSignature(drop.node);
+        const moveIndex = remaining.findIndex((candidate) => subtreeSignature(candidate.node) === signature);
+        if (moveIndex >= 0) {
+            const moved = remaining.splice(moveIndex, 1)[0];
+            changes.push({
+                type: "moved",
+                path: childPath(basePath, moved.node, moved.index),
+                summary: `${describe(drop.node)} moved`
+            });
+            continue;
+        }
+        changes.push({
+            type: "removed",
+            path: childPath(basePath, drop.node, drop.index),
+            summary: describe(drop.node)
+        });
+    }
+    for (const insert of remaining) {
+        changes.push({
+            type: "added",
+            path: childPath(basePath, insert.node, insert.index),
+            summary: describe(insert.node)
+        });
+    }
+}
+function diffNode(before, after, path, changes) {
+    if (before.type === "text" && after.type === "text") {
+        if (before.value !== after.value) {
+            changes.push({
+                type: "text-changed",
+                path,
+                before: before.value,
+                after: after.value
+            });
+        }
+        return;
+    }
+    if (before.type === "element" && after.type === "element") {
+        if (before.tagName !== after.tagName) {
+            changes.push({
+                type: "tag-changed",
+                path,
+                before: before.tagName,
+                after: after.tagName
+            });
+        }
+        diffAttributes(before.attributes, after.attributes, path, changes);
+        diffChildren(before.children, after.children, path, changes);
+    }
+}
+function diffAttributes(before, after, path, changes) {
+    const names = new Set([...Object.keys(before), ...Object.keys(after)]);
+    for (const name of [...names].sort()) {
+        const beforeValue = before[name];
+        const afterValue = after[name];
+        if (beforeValue === undefined) {
+            changes.push({ type: "attribute-added", path, name, value: afterValue });
+        }
+        else if (afterValue === undefined) {
+            changes.push({ type: "attribute-removed", path, name, value: beforeValue });
+        }
+        else if (beforeValue !== afterValue) {
+            changes.push({
+                type: "attribute-changed",
+                path,
+                name,
+                before: beforeValue,
+                after: afterValue
+            });
+        }
+    }
+}
+export function renderTreeChanges(changes) {
+    return changes.map(renderTreeChange).join("\n");
+}
+function renderTreeChange(change) {
+    switch (change.type) {
+        case "added":
+            return `+ ${change.path} (${change.summary})`;
+        case "removed":
+            return `- ${change.path} (${change.summary})`;
+        case "moved":
+            return `~ ${change.path} (${change.summary})`;
+        case "text-changed":
+            return `~ ${change.path} text: "${change.before}" → "${change.after}"`;
+        case "tag-changed":
+            return `~ ${change.path} tag: <${change.before}> → <${change.after}>`;
+        case "attribute-added":
+            return `+ ${change.path} @${change.name}="${change.value}"`;
+        case "attribute-removed":
+            return `- ${change.path} @${change.name}="${change.value}"`;
+        case "attribute-changed":
+            return `~ ${change.path} @${change.name}: "${change.before}" → "${change.after}"`;
+    }
+}
+function alignKey(node) {
+    if (node.type === "text") {
+        return "#text";
+    }
+    const id = node.attributes.id ? `#${node.attributes.id}` : "";
+    return `${node.tagName}${id}`;
+}
+function childPath(basePath, node, index) {
+    const segment = node.type === "text" ? `#text[${index}]` : `${node.tagName}[${index}]`;
+    return basePath ? `${basePath} > ${segment}` : segment;
+}
+function describe(node) {
+    return node.type === "text" ? `text "${node.value}"` : `<${node.tagName}>`;
+}
+// Signature of a subtree, used both to anchor the LCS alignment and to match a
+// removed subtree to an identical added one (a move). Memoized per node so the
+// `O(removed × added)` move reconciliation doesn't re-stringify the same
+// subtrees repeatedly; keyed by node identity, so distinct nodes never collide.
+const signatureCache = new WeakMap();
+function subtreeSignature(node) {
+    const cached = signatureCache.get(node);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const signature = JSON.stringify(node);
+    signatureCache.set(node, signature);
+    return signature;
+}