@juxtapose/core 0.4.0 → 0.6.0

package/dist/diff/structural/deltas.js

@@ -0,0 +1,218 @@
+// One typed fact per changed thing between two matched snapshots.
+//
+// Style deltas are reported where they originate. Compact storage (see
+// capture/structure.ts) stores an inherited property only where it differs
+// from the parent, but a change on `main` still changes every descendant's
+// effective colour — reporting it 40 times would bury the one fact that
+// matters. So an inherited delta is emitted only where the element's own
+// stored value changed, or where the parents' effective values already agree.
+import { INHERITED_PROPS, STRUCTURE_PROPS, effectiveStyle, round, } from '../../capture/structure.js';
+import { abstractLabel, clip, label } from './label.js';
+/** Within one position, which fact reads first. */
+export const KIND_RANK = {
+    removed: 0,
+    added: 1,
+    text: 2,
+    attr: 3,
+    style: 4,
+    resized: 5,
+    moved: 6,
+    shift: 7,
+};
+const ATTRS = ['src', 'role', 'name'];
+/** Longest `from`/`to` in a delta. A paragraph of copy or a data-URI src
+ *  would otherwise make one delta larger than the whole tier-0 budget; 200
+ *  keeps any realistic value (a font stack, a shadow, a URL) whole. With
+ *  labels capped at MAX_LABEL, every delta has a fixed worst-case size. */
+const MAX_VALUE = 200;
+const BORDER_COLOR = /^border-(top|right|bottom|left)-color$/;
+export function computeFacts(a, b, match) {
+    const facts = [];
+    const aToB = new Map(match.pairs);
+    /** Baseline index → its facts; and children whose only change was
+     *  following, so their rects can ride on an ancestor's fact. */
+    const byElement = new Map();
+    const followers = [];
+    for (const [i, j] of match.pairs) {
+        const ea = a.elements[i];
+        const eb = b.elements[j];
+        const fact = (delta) => {
+            const f = {
+                delta,
+                rects: [ea.rect, eb.rect],
+                abstract: abstractLabel(eb),
+                order: j,
+                source: { side: 'baseline', index: i },
+            };
+            byElement.set(i, [...(byElement.get(i) ?? []), f]);
+            return f;
+        };
+        // Every fact about a matched element carries ONE label, the baseline
+        // side's. A button's label is its name, and its name is usually its text,
+        // so the current side would read `button[name="Save changes"] text
+        // "Save"→"Save changes"`, and a text delta labelled from one side beside
+        // a resize labelled from the other reads as two buttons.
+        const el = label(ea);
+        // Masked stand-ins carry no content by construction; anything that leaks
+        // onto one must not surface as a delta either.
+        if (ea.tag !== 'masked' && eb.tag !== 'masked') {
+            const ta = ea.text ?? '';
+            const tb = eb.text ?? '';
+            if (ta !== tb)
+                facts.push(fact({ kind: 'text', el, from: clip(ta, MAX_VALUE), to: clip(tb, MAX_VALUE) }));
+            for (const attr of ATTRS) {
+                const from = ea[attr] ?? '';
+                const to = eb[attr] ?? '';
+                if (from === to)
+                    continue;
+                // A name that is just the text restates the text delta.
+                if (attr === 'name' && from === ta && to === tb)
+                    continue;
+                facts.push(fact({
+                    kind: 'attr',
+                    el,
+                    attr,
+                    from: clip(from, MAX_VALUE),
+                    to: clip(to, MAX_VALUE),
+                }));
+            }
+            for (const prop of STRUCTURE_PROPS) {
+                // An unstored border colour resolves to currentColor, so a plain
+                // `color` change would also report four phantom border-colour deltas
+                // on every borderless element. No border, no border-colour fact.
+                if (BORDER_COLOR.test(prop) && borderless(a, i, prop) && borderless(b, j, prop))
+                    continue;
+                const from = effectiveStyle(a, i, prop);
+                const to = effectiveStyle(b, j, prop);
+                if (from === to)
+                    continue;
+                if (INHERITED_PROPS.has(prop) && !originatesHere(a, b, i, j, aToB, prop))
+                    continue;
+                facts.push(fact({
+                    kind: 'style',
+                    el,
+                    prop,
+                    from: clip(from, MAX_VALUE),
+                    to: clip(to, MAX_VALUE),
+                }));
+            }
+        }
+        const dw = round(eb.rect.w - ea.rect.w);
+        const dh = round(eb.rect.h - ea.rect.h);
+        const dx = round(eb.rect.x - ea.rect.x);
+        const dy = round(eb.rect.y - ea.rect.y);
+        // A child whose box changed exactly as its parent's did only followed it.
+        // On the 12-item reorder probe the item's `span.meta moved down 222px`
+        // read as a second change beside the item's own move, and in the corpus
+        // `nested-reorder` case the five spans doubled the shift count (6 for 3).
+        // The ancestor that actually moved keeps its fact. Its rect usually
+        // contains the child's, but an overflowing child's does not, so the
+        // child's rects are handed to that fact below and coverage loses nothing.
+        const p = parentChange(a, b, i, j, aToB);
+        const resized = dw !== 0 || dh !== 0;
+        const moved = dx !== 0 || dy !== 0;
+        const followedSize = resized && p !== undefined && p.dw === dw && p.dh === dh;
+        const followedPos = moved && p !== undefined && p.dx === dx && p.dy === dy;
+        if (resized && !followedSize)
+            facts.push(fact({ kind: 'resized', el, dw, dh }));
+        if (moved && !followedPos)
+            facts.push(fact({ kind: 'moved', el, dx, dy }));
+        if ((followedSize || followedPos) && !byElement.has(i))
+            followers.push({ i, rects: [ea.rect, eb.rect] });
+    }
+    // Nearest baseline ancestor with a geometry fact: the move or resize the
+    // child followed. Walked on the baseline tree, the side `source` indexes.
+    for (const { i, rects } of followers) {
+        for (let k = a.elements[i].parent; k !== null; k = a.elements[k].parent) {
+            const own = byElement
+                .get(k)
+                ?.find((f) => f.delta.kind === 'moved' || f.delta.kind === 'resized');
+            if (own) {
+                own.rects.push(...rects);
+                break;
+            }
+        }
+    }
+    for (const j of match.added) {
+        const e = b.elements[j];
+        facts.push({
+            delta: { kind: 'added', el: label(e), rect: e.rect },
+            rects: [e.rect],
+            abstract: abstractLabel(e),
+            order: j,
+            source: { side: 'current', index: j },
+        });
+    }
+    // A removed element has no current position; order it after the last
+    // matched element that precedes it on the baseline side.
+    const lastMatchedBefore = (i) => {
+        for (let k = i - 1; k >= 0; k--) {
+            const j = aToB.get(k);
+            if (j !== undefined)
+                return j + 0.5;
+        }
+        return -0.5;
+    };
+    for (const i of match.removed) {
+        const e = a.elements[i];
+        facts.push({
+            delta: { kind: 'removed', el: label(e), rect: e.rect },
+            rects: [e.rect],
+            abstract: abstractLabel(e),
+            order: lastMatchedBefore(i),
+            source: { side: 'baseline', index: i },
+        });
+    }
+    return sortFacts(facts);
+}
+/** That side of `border-<side>-color` has zero width on this element. */
+function borderless(s, i, colorProp) {
+    return effectiveStyle(s, i, colorProp.replace(/-color$/, '-width')) === '0px';
+}
+/** An inherited property changed on this element, not merely on an ancestor:
+ *  either it stores its own value on a side, or its parents' effective values
+ *  agree (so the difference starts here). */
+function originatesHere(a, b, i, j, aToB, prop) {
+    const ea = a.elements[i];
+    const eb = b.elements[j];
+    if (ea.styles[prop] !== undefined || eb.styles[prop] !== undefined)
+        return true;
+    const pa = ea.parent;
+    const pb = eb.parent;
+    if (pa === null || pb === null)
+        return true;
+    // Parents unmatched: nothing above to blame, so report here.
+    if (aToB.get(pa) !== pb)
+        return true;
+    return effectiveStyle(a, pa, prop) === effectiveStyle(b, pb, prop);
+}
+/** How the matched parent's box changed; undefined when the parent is the
+ *  root or unmatched. Read off the rects, not off the facts, so a grandchild
+ *  still reads as following when its parent's own move was itself
+ *  suppressed. */
+function parentChange(a, b, i, j, aToB) {
+    const pa = a.elements[i].parent;
+    const pb = b.elements[j].parent;
+    if (pa === null || pb === null || aToB.get(pa) !== pb)
+        return undefined;
+    const ra = a.elements[pa].rect;
+    const rb = b.elements[pb].rect;
+    return {
+        dx: round(rb.x - ra.x),
+        dy: round(rb.y - ra.y),
+        dw: round(rb.w - ra.w),
+        dh: round(rb.h - ra.h),
+    };
+}
+export function sortFacts(facts) {
+    return facts.sort((x, y) => x.order - y.order ||
+        KIND_RANK[x.delta.kind] - KIND_RANK[y.delta.kind] ||
+        compareCodeUnits(factKey(x.delta), factKey(y.delta)));
+}
+function factKey(d) {
+    return d.kind === 'style' ? d.prop : d.kind === 'attr' ? d.attr : '';
+}
+/** Byte-identical output across machines needs a locale-free order;
+ *  `localeCompare` is not one. */
+export const compareCodeUnits = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+//# sourceMappingURL=deltas.js.map

package/dist/diff/structural/deltas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deltas.js","sourceRoot":"","sources":["../../../src/diff/structural/deltas.ts"],"names":[],"mappings":"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"}

package/dist/diff/structural/disambiguate.d.ts

@@ -0,0 +1,3 @@
+import type { StructureSnapshot } from '../../types.js';
+import type { Fact } from './deltas.js';
+export declare function disambiguate(facts: Fact[], baseline: StructureSnapshot, current: StructureSnapshot): Fact[];

package/dist/diff/structural/disambiguate.js

@@ -0,0 +1,89 @@
+// A label is a description, not an identity: a page with two cards has two
+// `div.card`s, and when both change, every reader of the verdict — the JSON,
+// the summary, `describeDeltas` — sees one element. Measured on a dark-mode
+// probe: the two cards' facts merged into one clause that stated
+// `background-color` twice; on a 12-item reorder, seven `span.meta` moves
+// read as one line and six deltas vanished from the human output.
+//
+// So within one verdict, distinct elements get distinct labels. Only labels
+// that actually collide change, and they take the shortest stable
+// distinguisher: the nearest ancestor with a name, id or test id
+// (`span.meta in listitem[name="Item 4"]`), or, when that does not separate
+// them, the element's ordinal among same-labelled elements on its side of the
+// diff (`div.card (2nd)`). Both are properties of the page, not of the diff,
+// so the same change labels the same way on every run.
+import { MAX_LABEL, clip, label } from './label.js';
+export function disambiguate(facts, baseline, current) {
+    const snap = (s) => (s.side === 'baseline' ? baseline : current);
+    const nth = {
+        baseline: undefined,
+        current: undefined,
+    };
+    const nthOf = (s) => (nth[s.side] ??= ordinals(snap(s)))[s.index];
+    const key = (s) => `${s.side}:${s.index}`;
+    const labelOf = (f) => ('el' in f.delta ? f.delta.el : f.delta.after);
+    // label → the distinct elements wearing it, in first-seen (fact) order
+    const byLabel = new Map();
+    for (const f of facts) {
+        const l = labelOf(f);
+        let ids = byLabel.get(l);
+        if (!ids)
+            byLabel.set(l, (ids = new Map()));
+        ids.set(key(f.source), f.source);
+    }
+    const rename = new Map();
+    for (const [l, ids] of byLabel) {
+        if (ids.size < 2)
+            continue;
+        const sources = [...ids.values()];
+        const scoped = sources.map((s) => {
+            const a = labelledAncestor(snap(s), s.index);
+            return a === undefined ? undefined : clip(`${l} in ${a}`, MAX_LABEL);
+        });
+        const distinct = scoped.every((x) => x !== undefined) && new Set(scoped).size === scoped.length;
+        for (const [k, s] of sources.entries()) {
+            const suffix = ` (${ordinal(nthOf(s))})`;
+            rename.set(key(s), distinct ? scoped[k] : clip(l, MAX_LABEL - suffix.length) + suffix);
+        }
+    }
+    if (rename.size === 0)
+        return facts;
+    return facts.map((f) => {
+        const to = rename.get(key(f.source));
+        if (to === undefined)
+            return f;
+        const d = f.delta;
+        return { ...f, delta: 'el' in d ? { ...d, el: to } : { ...d, after: to } };
+    });
+}
+/** Label of the nearest ancestor that names itself (role+name, id, test id);
+ *  a class or a path does not tell two siblings' parents apart. */
+function labelledAncestor(s, index) {
+    for (let p = s.elements[index].parent; p !== null; p = s.elements[p].parent) {
+        const e = s.elements[p];
+        if (e.tag === 'masked')
+            continue;
+        if ((e.role && e.name) || e.id !== undefined || e.testId !== undefined)
+            return label(e);
+    }
+    return undefined;
+}
+/** Each element's 1-based position among its side's elements that carry the
+ *  same label, in document order. One pass per side, not one per element: a
+ *  list of 5,000 identical rows that all changed would otherwise be 25M
+ *  label calls. */
+function ordinals(s) {
+    const seen = new Map();
+    return s.elements.map((e) => {
+        const l = label(e);
+        const n = (seen.get(l) ?? 0) + 1;
+        seen.set(l, n);
+        return n;
+    });
+}
+function ordinal(n) {
+    const teen = n % 100 >= 11 && n % 100 <= 13;
+    const suffix = teen ? 'th' : (['th', 'st', 'nd', 'rd'][n % 10] ?? 'th');
+    return `${n}${suffix}`;
+}
+//# sourceMappingURL=disambiguate.js.map

package/dist/diff/structural/disambiguate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"disambiguate.js","sourceRoot":"","sources":["../../../src/diff/structural/disambiguate.ts"],"names":[],"mappings":"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"}

package/dist/diff/structural/label.d.ts

@@ -0,0 +1,15 @@
+import type { StructureElement } from '../../types.js';
+/** Elements that paint their own pixels: a change inside them leaves the DOM
+ *  and computed styles untouched, so unexplained pixels on one of these mean
+ *  "content", not "drift". */
+export declare const SELF_PAINTING: ReadonlySet<string>;
+/** Longest label in a delta or summary. A deep path or a generated id or
+ *  class must not be able to spend the verdict's 1,500-char budget. */
+export declare const MAX_LABEL = 60;
+export declare function label(el: StructureElement): string;
+/** At most `max` UTF-16 units, ending in `…` when cut, never splitting a
+ *  surrogate pair (half an emoji is invalid UTF-16 in the JSON). */
+export declare function clip(s: string, max: number): string;
+/** Identity with the page-specific part removed, so the same change on two
+ *  pages hashes to the same signature. */
+export declare function abstractLabel(el: StructureElement): string;

package/dist/diff/structural/label.js

@@ -0,0 +1,64 @@
+// Short human labels for elements in deltas and summaries. The budget is
+// ~1,500 chars for a whole verdict, so a label is the shortest thing that
+// still tells an agent which element to look at.
+/** Elements that paint their own pixels: a change inside them leaves the DOM
+ *  and computed styles untouched, so unexplained pixels on one of these mean
+ *  "content", not "drift". */
+export const SELF_PAINTING = new Set([
+    'canvas',
+    'video',
+    'img',
+    'iframe',
+    'object',
+    'embed',
+]);
+/** Longest label in a delta or summary. A deep path or a generated id or
+ *  class must not be able to spend the verdict's 1,500-char budget. */
+export const MAX_LABEL = 60;
+export function label(el) {
+    if (el.tag === 'masked')
+        return 'masked';
+    if (el.role && el.name)
+        return clip(`${el.role}[name="${clip(el.name, 40)}"]`, MAX_LABEL);
+    if (el.id !== undefined)
+        return clip(`${el.tag}#${el.id}`, MAX_LABEL);
+    if (el.testId !== undefined)
+        return clip(`${el.tag}[data-testid="${el.testId}"]`, MAX_LABEL);
+    if (el.classes?.length)
+        return clip(`${el.tag}.${el.classes[0]}`, MAX_LABEL);
+    return clipPath(el.path
+        .replace(/^html:nth-of-type\(1\)>body:nth-of-type\(1\)>/, '')
+        .replace(/:nth-of-type\(1\)/g, ''));
+}
+/** A path keeps its tail — the element itself and its nearest ancestors —
+ *  cut at a `>` boundary, so what remains is still a valid selector suffix. */
+function clipPath(path) {
+    if (path.length <= MAX_LABEL)
+        return path;
+    const parts = path.split('>');
+    let out = parts[parts.length - 1];
+    for (let k = parts.length - 2; k >= 0; k--) {
+        const next = `${parts[k]}>${out}`;
+        if (next.length + 2 > MAX_LABEL)
+            break;
+        out = next;
+    }
+    return `…>${clip(out, MAX_LABEL - 2)}`;
+}
+/** At most `max` UTF-16 units, ending in `…` when cut, never splitting a
+ *  surrogate pair (half an emoji is invalid UTF-16 in the JSON). */
+export function clip(s, max) {
+    if (s.length <= max)
+        return s;
+    let end = max - 1;
+    const c = s.charCodeAt(end - 1);
+    if (c >= 0xd800 && c <= 0xdbff)
+        end--;
+    return s.slice(0, end) + '…';
+}
+/** Identity with the page-specific part removed, so the same change on two
+ *  pages hashes to the same signature. */
+export function abstractLabel(el) {
+    return el.role ?? el.tag;
+}
+//# sourceMappingURL=label.js.map

package/dist/diff/structural/label.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"label.js","sourceRoot":"","sources":["../../../src/diff/structural/label.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,0EAA0E;AAC1E,iDAAiD;AAIjD;;8BAE8B;AAC9B,MAAM,CAAC,MAAM,aAAa,GAAwB,IAAI,GAAG,CAAC;IACxD,QAAQ;IACR,OAAO;IACP,KAAK;IACL,QAAQ;IACR,QAAQ;IACR,OAAO;CACR,CAAC,CAAC;AAEH;uEACuE;AACvE,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,CAAC;AAE5B,MAAM,UAAU,KAAK,CAAC,EAAoB;IACxC,IAAI,EAAE,CAAC,GAAG,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IACzC,IAAI,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,IAAI;QACpB,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,UAAU,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACpE,IAAI,EAAE,CAAC,EAAE,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,SAAS,CAAC,CAAC;IACtE,IAAI,EAAE,CAAC,MAAM,KAAK,SAAS;QACzB,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,iBAAiB,EAAE,CAAC,MAAM,IAAI,EAAE,SAAS,CAAC,CAAC;IAClE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM;QAAE,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;IAC7E,OAAO,QAAQ,CACb,EAAE,CAAC,IAAI;SACJ,OAAO,CAAC,+CAA+C,EAAE,EAAE,CAAC;SAC5D,OAAO,CAAC,oBAAoB,EAAE,EAAE,CAAC,CACrC,CAAC;AACJ,CAAC;AAED;+EAC+E;AAC/E,SAAS,QAAQ,CAAC,IAAY;IAC5B,IAAI,IAAI,CAAC,MAAM,IAAI,SAAS;QAAE,OAAO,IAAI,CAAC;IAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAClC,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3C,MAAM,IAAI,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,GAAG,SAAS;YAAE,MAAM;QACvC,GAAG,GAAG,IAAI,CAAC;IACb,CAAC;IACD,OAAO,KAAK,IAAI,CAAC,GAAG,EAAE,SAAS,GAAG,CAAC,CAAC,EAAE,CAAC;AACzC,CAAC;AAED;oEACoE;AACpE,MAAM,UAAU,IAAI,CAAC,CAAS,EAAE,GAAW;IACzC,IAAI,CAAC,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,CAAC,CAAC;IAC9B,IAAI,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC;IAClB,MAAM,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IAChC,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,IAAI,MAAM;QAAE,GAAG,EAAE,CAAC;IACtC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,GAAG,CAAC;AAC/B,CAAC;AAED;0CAC0C;AAC1C,MAAM,UAAU,aAAa,CAAC,EAAoB;IAChD,OAAO,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,GAAG,CAAC;AAC3B,CAAC"}

package/dist/diff/structural/match.d.ts

@@ -0,0 +1,13 @@
+import type { StructureElement, StructureSnapshot } from '../../types.js';
+export interface ElementMatch {
+    /** [baseline index, current index], sorted by current index. */
+    pairs: Array<[number, number]>;
+    /** Current indices of unmatched subtree roots, ascending. */
+    added: number[];
+    /** Baseline indices of unmatched subtree roots, ascending. */
+    removed: number[];
+}
+/** What makes an element "the same one" across captures: tag plus the most
+ *  stable identity it carries. Masked stand-ins have only their tag. */
+export declare function identityKey(el: StructureElement): string;
+export declare function matchElements(a: StructureSnapshot, b: StructureSnapshot): ElementMatch;

package/dist/diff/structural/match.js

@@ -0,0 +1,135 @@
+// Which element on the baseline side is which element on the current side.
+//
+// Positional paths alone would report every sibling after an insertion as
+// changed. Instead children are aligned per parent with an LCS over an
+// identity key, recursing into matches, so an insertion is one `added` and the
+// rest stay matched. LCS is per parent, so cost is Σ(children²) — small for
+// real DOMs; a pathological flat parent falls back to in-order key pairing.
+/** Above this many DP cells for one parent, pair greedily instead. */
+const LCS_CELL_CAP = 250_000;
+/** What makes an element "the same one" across captures: tag plus the most
+ *  stable identity it carries. Masked stand-ins have only their tag. */
+export function identityKey(el) {
+    if (el.id !== undefined)
+        return `${el.tag}#${el.id}`;
+    if (el.testId !== undefined)
+        return `${el.tag}[${el.testId}]`;
+    if (el.role && el.name)
+        return `${el.tag}|${el.role}=${el.name}`;
+    if (el.classes?.length)
+        return `${el.tag}.${el.classes.join('.')}`;
+    return el.tag;
+}
+export function matchElements(a, b) {
+    const childrenA = childLists(a.elements);
+    const childrenB = childLists(b.elements);
+    const keyA = a.elements.map(identityKey);
+    const keyB = b.elements.map(identityKey);
+    const pairs = [];
+    const added = [];
+    const removed = [];
+    const walk = (pa, pb) => {
+        const ca = childrenA.get(pa) ?? [];
+        const cb = childrenB.get(pb) ?? [];
+        const first = align(ca, cb, (i, j) => keyA[i] === keyB[j]);
+        // A text edit changes a name-derived key, a toggled class changes a
+        // class-derived one. Pair what is left by tag, in order, so those read as
+        // `text`/`attr` deltas rather than removed + added.
+        // Never across conflicting explicit identities: `div#row-1` removed and
+        // `div#banner` added are two different elements, not one edited one.
+        const second = align(first.leftA, first.leftB, (i, j) => sameKind(a.elements[i], b.elements[j]));
+        for (const [i, j] of [...first.matched, ...second.matched]) {
+            pairs.push([i, j]);
+            walk(i, j);
+        }
+        removed.push(...second.leftA);
+        added.push(...second.leftB);
+    };
+    walk(-1, -1);
+    pairs.sort((p, q) => p[1] - q[1]);
+    added.sort((x, y) => x - y);
+    removed.sort((x, y) => x - y);
+    return { pairs, added, removed };
+}
+/** Tag equal, and no explicit id or testId present on both sides and unequal. */
+function sameKind(x, y) {
+    if (x.tag !== y.tag)
+        return false;
+    if (x.id !== undefined && y.id !== undefined && x.id !== y.id)
+        return false;
+    if (x.testId !== undefined && y.testId !== undefined && x.testId !== y.testId)
+        return false;
+    return true;
+}
+/** Children in document order, keyed by parent index; -1 is the root. */
+function childLists(elements) {
+    const m = new Map();
+    elements.forEach((e, i) => {
+        const p = e.parent ?? -1;
+        const list = m.get(p);
+        if (list)
+            list.push(i);
+        else
+            m.set(p, [i]);
+    });
+    return m;
+}
+/** Order-preserving alignment of two sibling lists under `same`. */
+function align(ca, cb, same) {
+    const matched = ca.length * cb.length > LCS_CELL_CAP ? greedy(ca, cb, same) : lcs(ca, cb, same);
+    const usedA = new Set(matched.map(([i]) => i));
+    const usedB = new Set(matched.map(([, j]) => j));
+    return {
+        matched,
+        leftA: ca.filter((i) => !usedA.has(i)),
+        leftB: cb.filter((j) => !usedB.has(j)),
+    };
+}
+function lcs(ca, cb, same) {
+    const n = ca.length;
+    const m = cb.length;
+    // L[i][j] = LCS length of ca[i..] and cb[j..]
+    const L = Array.from({ length: n + 1 }, () => new Uint32Array(m + 1));
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            L[i][j] = same(ca[i], cb[j])
+                ? L[i + 1][j + 1] + 1
+                : Math.max(L[i + 1][j], L[i][j + 1]);
+        }
+    }
+    const out = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (same(ca[i], cb[j])) {
+            out.push([ca[i], cb[j]]);
+            i++;
+            j++;
+        }
+        else if (L[i + 1][j] >= L[i][j + 1])
+            i++;
+        else
+            j++;
+    }
+    return out;
+}
+/** In-order pairing: each a takes the first unused b after the last pairing
+ *  that is `same`. Linear-ish, order-preserving, and good enough for a parent
+ *  with thousands of children where an exact LCS would cost seconds.
+ *  Failure mode: it never looks backwards, so a reordered list degrades to
+ *  many removed/added pairs instead of a minimal edit. */
+function greedy(ca, cb, same) {
+    const out = [];
+    let j = 0;
+    for (const i of ca) {
+        let k = j;
+        while (k < cb.length && !same(i, cb[k]))
+            k++;
+        if (k < cb.length) {
+            out.push([i, cb[k]]);
+            j = k + 1;
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=match.js.map

package/dist/diff/structural/match.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.js","sourceRoot":"","sources":["../../../src/diff/structural/match.ts"],"names":[],"mappings":"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"}

package/dist/diff/structural/shift.d.ts

@@ -0,0 +1,2 @@
+import { type Fact } from './deltas.js';
+export declare function synthesizeShifts(facts: Fact[]): Fact[];