@michaelmagan/dnumb 0.1.0

package/dist/diff/changes.js

@@ -0,0 +1,653 @@
+const GEOMETRIC_STYLES = [
+    'display',
+    'position',
+    'fontSize',
+    'fontWeight',
+    'flexDirection',
+    'gridTemplateColumns',
+    'textAlign',
+];
+const BOX_SIDE_STYLES = ['padding', 'margin', 'border'];
+const PAINT_STYLES = ['color', 'backgroundColor'];
+const INHERITED_PAINT = new Set(['color']);
+const isInheritedPaint = (prop) => prop !== undefined && INHERITED_PAINT.has(prop);
+/** Layout arithmetic produces sub-pixel differences constantly. */
+const BOX_TOLERANCE = 0.5;
+/**
+ * browser-use's `DYNAMIC_CLASS_PATTERNS`, put to the job step 1 assigned them.
+ * They are useless for matching — dnumb drops `class` from identity entirely —
+ * but a class list that only gained or lost these tokens is reporting the state
+ * the element is in, not a change to the page, and printing it beside a
+ * structural change costs one of fifteen lines to say `.is-hover` appeared.
+ */
+const DYNAMIC_CLASS_TOKENS = [
+    'focus',
+    'hover',
+    'active',
+    'selected',
+    'disabled',
+    'animation',
+    'transition',
+    'loading',
+    'open',
+    'closed',
+    'expanded',
+    'collapsed',
+    'visible',
+    'hidden',
+    'pressed',
+    'checked',
+    'highlighted',
+    'current',
+    'entering',
+    'leaving',
+];
+const sides = (s) => `${s.top},${s.right},${s.bottom},${s.left}`;
+const clipKey = (c) => (c ? `${c.by}|${sides(c.hidden)}` : '');
+const boxDelta = (b, a) => ({
+    dx: a.rect.x - b.rect.x,
+    dy: a.rect.y - b.rect.y,
+    dw: a.rect.width - b.rect.width,
+    dh: a.rect.height - b.rect.height,
+});
+const moved = (d) => Math.abs(d.dx) > BOX_TOLERANCE || Math.abs(d.dy) > BOX_TOLERANCE;
+const resized = (d) => Math.abs(d.dw) > BOX_TOLERANCE || Math.abs(d.dh) > BOX_TOLERANCE;
+const near = (x, y) => Math.abs(x - y) <= BOX_TOLERANCE;
+/** The class tokens present on one side and not the other, in both directions. */
+function classDelta(beforeClass, afterClass) {
+    const b = new Set(beforeClass.split(/\s+/).filter((t) => t !== ''));
+    const a = new Set(afterClass.split(/\s+/).filter((t) => t !== ''));
+    const out = [];
+    for (const token of b)
+        if (!a.has(token))
+            out.push(token);
+    for (const token of a)
+        if (!b.has(token))
+            out.push(token);
+    return out;
+}
+const isDynamicClass = (token) => {
+    const lower = token.toLowerCase();
+    return DYNAMIC_CLASS_TOKENS.some((pattern) => lower.includes(pattern));
+};
+export function computeChanges(before, after, matched) {
+    const changes = [];
+    const byAfterId = new Map();
+    const record = (c) => {
+        changes.push(c);
+        if (c.afterId) {
+            const list = byAfterId.get(c.afterId);
+            if (list)
+                list.push(c);
+            else
+                byAfterId.set(c.afterId, [c]);
+        }
+        return c;
+    };
+    for (const el of before.elements) {
+        if (!matched.pairs.has(el.id))
+            record({ kind: 'removed', beforeId: el.id, before: el });
+    }
+    for (const el of after.elements) {
+        if (!matched.reverse.has(el.id))
+            record({ kind: 'added', afterId: el.id, after: el });
+    }
+    for (const [bid, aid] of matched.pairs) {
+        const b = before.byId.get(bid);
+        const a = after.byId.get(aid);
+        if (!b || !a)
+            continue;
+        const pair = { afterId: aid, beforeId: bid, before: b, after: a };
+        if (b.visible !== a.visible) {
+            record({
+                kind: a.visible ? 'appeared' : 'disappeared',
+                ...pair,
+                reason: (a.visible ? b : a).display === 'none' ? 'display:none' : 'hidden',
+            });
+        }
+        if (b.text !== a.text)
+            record({ kind: 'text', ...pair });
+        for (const prop of GEOMETRIC_STYLES) {
+            if (b[prop] !== a[prop])
+                record({ kind: 'style', geometric: true, prop, ...pair });
+        }
+        for (const prop of PAINT_STYLES) {
+            if (b[prop] !== a[prop])
+                record({ kind: 'style', geometric: false, prop, ...pair });
+        }
+        for (const prop of BOX_SIDE_STYLES) {
+            if (sides(b[prop]) !== sides(a[prop])) {
+                record({ kind: 'style', geometric: true, prop, ...pair });
+            }
+        }
+        if (b.gap.row !== a.gap.row || b.gap.column !== a.gap.column) {
+            record({ kind: 'style', geometric: true, prop: 'gap', ...pair });
+        }
+        if (b.className !== a.className) {
+            const toggled = classDelta(b.className, a.className);
+            // A reordered or re-spaced class list is the same class list, and a style
+            // line for it would describe nothing the page can show.
+            if (toggled.length > 0) {
+                // Geometric in both cases, because a class swap can restyle anything.
+                // Calling a state toggle non-geometric would send rule 4 hunting for an
+                // ancestor to blame for a box this element moved by itself, which
+                // invents a causal claim the measurements do not support.
+                const c = record({ kind: 'style', geometric: true, prop: 'className', ...pair });
+                // Demoted, not attributed: there is no other measurement to point at,
+                // so this carries no `via` — the element is its own cause.
+                if (toggled.every(isDynamicClass))
+                    c.cause = 'derived';
+            }
+        }
+        if (b.ariaExpanded !== a.ariaExpanded) {
+            record({ kind: 'attr', prop: 'aria-expanded', ...pair });
+        }
+        const bOver = b.scrollWidth - b.clientWidth > 1;
+        const aOver = a.scrollWidth - a.clientWidth > 1;
+        if (bOver !== aOver)
+            record({ kind: 'overflow', ...pair, now: aOver });
+        if (clipKey(b.clip) !== clipKey(a.clip))
+            record({ kind: 'clip', ...pair });
+        const d = boxDelta(b, a);
+        if (moved(d) || resized(d))
+            record({ kind: 'box', ...pair, delta: d });
+    }
+    // Newly added or newly visible elements have no before-clip to compare to, so
+    // their clip is reported on its own. Such a change carries no `before`, which
+    // is how a renderer tells it from a clip that changed.
+    for (const c of [...changes]) {
+        if (c.kind !== 'added' && c.kind !== 'appeared')
+            continue;
+        if (!c.afterId || !c.after?.clip)
+            continue;
+        // An element that was matched *and* became visible already produced a clip
+        // change above, because its before-clip differed. Don't say it twice.
+        if ((byAfterId.get(c.afterId) ?? []).some((o) => o.kind === 'clip'))
+            continue;
+        record({ kind: 'clip', afterId: c.afterId, after: c.after });
+    }
+    markBoundaryAmbiguous(before, after, matched, changes);
+    subsume(before, after, matched, changes, byAfterId);
+    return changes;
+}
+/**
+ * Tell a genuine removal/addition apart from an artefact of the element cap.
+ *
+ * The precondition is per-kind, not "both captures truncated" — that was the
+ * bug (F1 in the fabrication review). A `removed` change is a before-element
+ * with no after-counterpart; the only way that counterpart could exist but be
+ * unreachable is if the *after* capture is a window, because a complete after
+ * capture would have found it wherever it moved. Whether the *before* capture
+ * is also a window is irrelevant to that question — it already produced the
+ * element in hand. Requiring both sides truncated silently dropped the
+ * ambiguity flag (and printed a bare fabricated `-`) whenever the complete
+ * side happened to be the before side: a complete 4,900-element before and a
+ * truncated 5,000-element after, with 200 elements inserted at the top,
+ * pushes the last 100 before-elements out of the after window while nothing
+ * was actually removed — and the old "both truncated" gate never even looked,
+ * because `before.truncated` was `false`. The `added` case mirrors this in
+ * the other direction and needs `before.truncated`, not `after.truncated`.
+ *
+ * Within that regime, "near the boundary" is not a fixed margin. It is
+ * measured: for an unmatched before-element, the matcher already recorded how
+ * far document order shifted for every pair it *did* match. The nearest
+ * matched neighbour's shift is the best available estimate of how far this
+ * element's live counterpart also moved — add that shift to its own
+ * before-index, and if the result falls at or past where the after capture's
+ * window ends, the two explanations ("removed" and "pushed past the cap")
+ * are indistinguishable from the evidence in hand. A genuine removal in the
+ * middle of an otherwise-stable page has a local shift of zero and is never
+ * flagged; only a removal whose neighbourhood demonstrably moved enough to
+ * explain it away is. The mirror case (`added`) runs the same arithmetic in
+ * the other direction: a "new" element near the after-capture's tail may have
+ * existed all along, just past where the before capture's window ended.
+ *
+ * The shift itself has to have a sign consistent with the story being told
+ * (F3 in the review): "pushed past the cap by insertions" requires a
+ * *positive* local shift — elements measurably moving later — and "pulled
+ * into the window by removals" requires a *negative* one. A shift of exactly
+ * zero is evidence that nothing moved nearby at all, so it cannot be blamed
+ * for either; before this guard, two captures whose element counts merely
+ * differed (for a reason having nothing to do with a nearby insertion) could
+ * satisfy `bi + 0 >= after.elements.length` and fabricate an "insertions
+ * earlier in the document" explanation with zero supporting evidence.
+ */
+function markBoundaryAmbiguous(before, after, matched, changes) {
+    // Neither branch below can ever fire unless at least one side is a window,
+    // so this is a fast path, not a correctness gate — each branch re-checks
+    // the specific side it actually depends on.
+    if (!before.truncated && !after.truncated)
+        return;
+    // One shift sample per matched pair, indexed by each side's own document
+    // order so the nearest-neighbour lookup works in either direction.
+    const byBeforeIndex = [];
+    const byAfterIndex = [];
+    for (const [bid, aid] of matched.pairs) {
+        const bi = before.docIndex.get(bid);
+        const ai = after.docIndex.get(aid);
+        if (bi === undefined || ai === undefined)
+            continue;
+        const shift = ai - bi;
+        byBeforeIndex.push({ index: bi, shift });
+        byAfterIndex.push({ index: ai, shift });
+    }
+    byBeforeIndex.sort((x, y) => x.index - y.index);
+    byAfterIndex.sort((x, y) => x.index - y.index);
+    /** The shift of the nearest sample strictly before `index`, via binary
+     * search over the sorted array; `null` when nothing matched before it. */
+    const shiftBefore = (samples, index) => {
+        let lo = 0;
+        let hi = samples.length - 1;
+        let found = null;
+        while (lo <= hi) {
+            const mid = (lo + hi) >> 1;
+            const sample = samples[mid];
+            if (sample && sample.index < index) {
+                found = sample.shift;
+                lo = mid + 1;
+            }
+            else {
+                hi = mid - 1;
+            }
+        }
+        return found;
+    };
+    for (const c of changes) {
+        if (c.kind === 'removed' && c.beforeId) {
+            // Only the after capture's window can explain a removed element being
+            // unreachable — see the doc comment above.
+            if (!after.truncated)
+                continue;
+            const bi = before.docIndex.get(c.beforeId);
+            if (bi === undefined)
+                continue;
+            const shift = shiftBefore(byBeforeIndex, bi);
+            // `shift > 0`: only a measured positive shift nearby is evidence of the
+            // "pushed past the cap by insertions" story this line tells (F3).
+            if (shift !== null && shift > 0 && bi + shift >= after.elements.length) {
+                c.boundaryAmbiguous = true;
+                c.capSize = after.elements.length;
+            }
+        }
+        else if (c.kind === 'added' && c.afterId) {
+            // Only the before capture's window can explain an added element having
+            // been there all along — see the doc comment above.
+            if (!before.truncated)
+                continue;
+            const ai = after.docIndex.get(c.afterId);
+            if (ai === undefined)
+                continue;
+            const shift = shiftBefore(byAfterIndex, ai);
+            // `shift < 0`: only a measured negative shift nearby is evidence of the
+            // "pulled into the window by removals" story this line tells (F3).
+            if (shift !== null && shift < 0 && ai - shift >= before.elements.length) {
+                c.boundaryAmbiguous = true;
+                c.capSize = before.elements.length;
+            }
+        }
+    }
+}
+/**
+ * Mark every change `primary`, `derived` (printed, folded, cause named) or
+ * `subsumed` (not printed — fully restated by another line).
+ */
+function subsume(before, after, matched, changes, byAfterId) {
+    const of = (id) => (id ? byAfterId.get(id) : undefined) ?? [];
+    // Excludes a boundary-ambiguous match: "a sibling was inserted" is not
+    // evidence this box was pushed when the insertion itself is only maybe.
+    const kindOn = (id, kind) => of(id).some((c) => c.kind === kind && !c.boundaryAmbiguous);
+    // Memoised because rule 4 asks for the same chains once per candidate pair,
+    // which is quadratic in the number of moved boxes on a reflow.
+    const ancestorCache = new Map();
+    const ancestors = (id) => {
+        if (!id)
+            return [];
+        const hit = ancestorCache.get(id);
+        if (hit)
+            return hit;
+        const out = [];
+        const seen = new Set([id]);
+        let cursor = after.byId.get(id)?.parentId ?? null;
+        while (cursor && !seen.has(cursor)) {
+            seen.add(cursor);
+            out.push(cursor);
+            cursor = after.byId.get(cursor)?.parentId ?? null;
+        }
+        ancestorCache.set(id, out);
+        return out;
+    };
+    // --- 1. Visibility restates its own box and its own styles ----------------
+    // A display:none element has a 0x0 box at the origin. "Moved from @0,0" is an
+    // artefact of that, not an observation, and `display: none → block` is the
+    // same sentence as "appeared" in CSS.
+    //
+    // Every *other* style goes with them, and that is not an aesthetic call. An
+    // element outside the layout has no resolved style to compare against: the
+    // CDP path returns no layout row for it at all, so `font-size`, `color`,
+    // `border` and the rest read as `'' → 14px`. Those are first observations of
+    // a thing that was never rendered, not changes to it, and printing them
+    // states as fact that a colour changed when nothing of the sort happened.
+    //
+    // Left in, a menu opening produced twelve lines where the cold-read version
+    // produced three, and eleven of the twelve were this.
+    for (const c of changes) {
+        if (c.kind !== 'appeared' && c.kind !== 'disappeared')
+            continue;
+        for (const other of of(c.afterId)) {
+            if (other === c)
+                continue;
+            if (other.kind === 'box' || other.kind === 'style')
+                other.subsumed = 'visibility';
+        }
+    }
+    // --- 2. A whole subtree arriving or leaving is one event ------------------
+    // A boundary-ambiguous arrival is never confirmed enough to be the *top* of
+    // an entering subtree — folding a real, matched descendant under a maybe
+    // would hide it behind uncertainty it does not share. It is equally never
+    // confirmed enough to be silently folded *as* someone else's descendant
+    // (B3): a boundary-ambiguous element's own presence is only maybe, and its
+    // `?` line (`render.ts`'s `boundaryLine`) is the one place that says so.
+    // Subsuming it — `c.subsumed = 'subtree'` drops it from `live` in
+    // `render.ts` before that line is ever built — erases the ambiguity from
+    // the text output entirely (it survives only in `--json`) while the header
+    // still tallies it as a confirmed arrival or departure. Both fold loops
+    // below skip a boundary-ambiguous `c` for this reason, not just a
+    // boundary-ambiguous *top*.
+    const entering = new Set();
+    for (const c of changes) {
+        if ((c.kind === 'added' || c.kind === 'appeared') && c.afterId && !c.boundaryAmbiguous) {
+            entering.add(c.afterId);
+        }
+    }
+    for (const c of changes) {
+        if (c.kind !== 'added' && c.kind !== 'appeared')
+            continue;
+        if (c.boundaryAmbiguous)
+            continue;
+        const top = ancestors(c.afterId).find((a) => entering.has(a));
+        if (!top)
+            continue;
+        c.subsumed = 'subtree';
+        c.subsumedBy = top;
+        for (const other of of(c.afterId))
+            other.subsumed ??= 'subtree';
+    }
+    // `disappeared` belongs beside `removed` here (B11), not just `appeared`
+    // beside `added` above. A subtree that leaves via `display:none` never
+    // produces `removed` changes for its descendants — every element under it
+    // is still in the DOM, still matched, and each one's own `visible` flips
+    // to `false` right along with its ancestor's, so each gets its own
+    // `disappeared` change. Omitting that kind here meant a departing
+    // display:none subtree folded its top element but never its children:
+    // one dropdown toggle produced an asymmetric "1 added / 10 folded" opening
+    // (fine — `appeared` was already included) against "5 removed / 6 folded"
+    // closing, for what is the same act run in reverse, and a large dropdown
+    // closing could consume the entire line budget with descendant lines the
+    // opening never had to pay for.
+    const departing = new Set();
+    for (const c of changes) {
+        if ((c.kind === 'removed' || c.kind === 'disappeared') && c.beforeId && !c.boundaryAmbiguous) {
+            departing.add(c.beforeId);
+        }
+    }
+    for (const c of changes) {
+        if (c.kind !== 'removed' && c.kind !== 'disappeared')
+            continue;
+        if (c.boundaryAmbiguous)
+            continue;
+        let cursor = c.before?.parentId ?? null;
+        while (cursor) {
+            if (departing.has(cursor)) {
+                c.subsumed = 'subtree';
+                c.subsumedBy = cursor;
+                break;
+            }
+            cursor = before.byId.get(cursor)?.parentId ?? null;
+        }
+    }
+    // Two maps, not one. Element ids are unique within a capture and meaningless
+    // across captures, so counting arrivals and departures together lets `e5` in
+    // the before-tree hand its tally to an unrelated `e5` in the after-tree — the
+    // spike printed "+3 inside" on the wrong element for exactly that reason.
+    // `disappeared` folds under a before-tree id exactly like `removed` does
+    // (both loops above walk `c.before?.parentId` and key `departing` by
+    // `beforeId`), so it routes into the same `foldedByBeforeId` map — routing
+    // it into `foldedByAfterId` instead would key the count by a before-id
+    // under a map every lookup below indexes by after-id, silently losing it.
+    const foldedByAfterId = new Map();
+    const foldedByBeforeId = new Map();
+    for (const c of changes) {
+        if (c.subsumed !== 'subtree' || !c.subsumedBy)
+            continue;
+        const into = c.kind === 'removed' || c.kind === 'disappeared' ? foldedByBeforeId : foldedByAfterId;
+        into.set(c.subsumedBy, (into.get(c.subsumedBy) ?? 0) + 1);
+    }
+    for (const c of changes) {
+        if (c.subsumed)
+            continue;
+        const n = (c.afterId ? foldedByAfterId.get(c.afterId) : undefined) ??
+            (c.beforeId ? foldedByBeforeId.get(c.beforeId) : undefined);
+        if (n)
+            c.descendants = n;
+    }
+    // --- 3. Inherited paint --------------------------------------------------
+    // `color` cascades. One theme swap restates itself on every descendant that
+    // did not author its own value. Same from *and* same to, or it stays primary:
+    // an independently-authored colour that happens to have moved is its own fact.
+    for (const c of changes) {
+        const prop = c.prop;
+        if (c.kind !== 'style' || c.geometric || c.subsumed)
+            continue;
+        if (!isInheritedPaint(prop) || !c.before || !c.after)
+            continue;
+        const from = c.before[prop];
+        const to = c.after[prop];
+        const source = ancestors(c.afterId).find((a) => of(a).some((o) => o.kind === 'style' &&
+            o.prop === prop &&
+            !o.subsumed &&
+            o.before?.[prop] === from &&
+            o.after?.[prop] === to));
+        if (source) {
+            c.cause = 'derived';
+            c.via = source;
+            c.how = 'inherited';
+        }
+    }
+    // --- 4. Geometry causality ----------------------------------------------
+    const boxChanges = changes.filter((c) => c.kind === 'box' && !c.subsumed && c.afterId);
+    const boxByAfterId = new Map();
+    for (const c of boxChanges)
+        if (c.afterId)
+            boxByAfterId.set(c.afterId, c);
+    // A parent whose children changed structurally has a reason of its own.
+    const structural = new Set();
+    for (const c of changes) {
+        if (c.subsumed)
+            continue;
+        // A boundary-ambiguous element cannot license "this box's parent has a
+        // structural reason of its own" — that reason is itself only maybe.
+        if (c.boundaryAmbiguous)
+            continue;
+        if (c.kind === 'added' || c.kind === 'appeared' || c.kind === 'disappeared') {
+            const parentId = c.afterId ? after.byId.get(c.afterId)?.parentId : null;
+            if (parentId)
+                structural.add(parentId);
+        }
+        if (c.kind === 'removed') {
+            const beforeParent = c.before?.parentId;
+            const afterParent = beforeParent ? matched.pairs.get(beforeParent) : undefined;
+            if (afterParent)
+                structural.add(afterParent);
+        }
+    }
+    const hasSelfCause = (id) => structural.has(id) ||
+        of(id).some((c) => !c.subsumed && (c.kind === 'text' || (c.kind === 'style' && c.geometric === true)));
+    for (const c of boxChanges) {
+        const id = c.afterId;
+        const delta = c.delta;
+        if (!id || !delta)
+            continue;
+        if (hasSelfCause(id)) {
+            c.cause = 'primary';
+            continue;
+        }
+        // Carried: an ancestor moved by the same vector and this one only followed.
+        if (!resized(delta)) {
+            const carrier = ancestors(id).find((a) => {
+                const up = boxByAfterId.get(a)?.delta;
+                return up !== undefined && near(up.dx, delta.dx) && near(up.dy, delta.dy);
+            });
+            if (carrier) {
+                c.cause = 'derived';
+                c.via = carrier;
+                c.how = 'carried';
+                continue;
+            }
+        }
+        // Reflowed: an ancestor moved *and* resized, and this box did exactly the
+        // same thing. A viewport change makes almost every box move and shrink; the
+        // ones that did precisely what their container did are restating it. All
+        // four components must match — a box whose height changed differently from
+        // its parent's did something of its own and keeps its line.
+        const reflowSource = ancestors(id).find((a) => {
+            const up = boxByAfterId.get(a)?.delta;
+            return (up !== undefined &&
+                near(up.dx, delta.dx) &&
+                near(up.dy, delta.dy) &&
+                near(up.dw, delta.dw) &&
+                near(up.dh, delta.dh));
+        });
+        if (reflowSource) {
+            c.cause = 'derived';
+            c.via = reflowSource;
+            c.how = 'reflowed';
+            continue;
+        }
+        // Absorbed: this box only grew because something inside it grew.
+        if (resized(delta) && !moved(delta)) {
+            const inner = boxChanges.find((o) => {
+                const innerDelta = o.delta;
+                return (o !== c &&
+                    o.afterId !== undefined &&
+                    innerDelta !== undefined &&
+                    ancestors(o.afterId).includes(id) &&
+                    near(innerDelta.dh, delta.dh) &&
+                    near(innerDelta.dw, delta.dw) &&
+                    hasSelfCause(o.afterId));
+            });
+            if (inner?.afterId) {
+                c.cause = 'derived';
+                c.via = inner.afterId;
+                c.how = 'absorbed';
+                continue;
+            }
+        }
+        // Pushed: an earlier sibling grew or was inserted, by exactly this
+        // distance. "By exactly this distance" is load-bearing, not decorative
+        // (B2): the first preceding sibling that changed shape at all used to be
+        // named the cause regardless of whether its growth could account for
+        // this box's own delta, so a sibling that gained 3px of *width* could be
+        // blamed for a 40px vertical push while the sibling that actually grew
+        // 40px taller sat one slot further back, never even checked. Every
+        // candidate's growth on the relevant axis (height, since this branch
+        // only fires when the box itself did not resize) must match `delta.dy`
+        // within tolerance before it is accepted; a candidate that merely
+        // resized on some other axis, or by some other amount, is skipped in
+        // favour of the next one further back, not accepted as a fallback.
+        const el = after.byId.get(id);
+        const parent = el?.parentId ? after.byId.get(el.parentId) : undefined;
+        if (parent && !resized(delta) && Math.abs(delta.dx) <= BOX_TOLERANCE) {
+            const index = parent.childIds.indexOf(id);
+            for (let i = index - 1; i >= 0; i--) {
+                const sibling = parent.childIds[i];
+                if (!sibling)
+                    continue;
+                const grew = boxByAfterId.get(sibling)?.delta;
+                // A resized sibling explains this push only if its own height
+                // growth matches the distance this box moved by.
+                const growExplains = grew !== undefined && resized(grew) && near(grew.dh, delta.dy);
+                // An inserted sibling has no `delta` (there is no before-state to
+                // diff against) — the space it claims is its own rendered height.
+                const insertedHeight = kindOn(sibling, 'added') || kindOn(sibling, 'appeared')
+                    ? after.byId.get(sibling)?.rect.height
+                    : undefined;
+                const insertExplains = insertedHeight !== undefined && near(insertedHeight, delta.dy);
+                if (growExplains || insertExplains) {
+                    c.cause = 'derived';
+                    c.via = sibling;
+                    c.how = 'pushed';
+                    break;
+                }
+            }
+            if (c.cause)
+                continue;
+        }
+        // No candidate's growth explained the distance moved: leaving this
+        // primary is the honest outcome. An unattributed move is a fact; naming
+        // the nearest sibling that merely happened to resize would be a guess
+        // wearing the same "by e3" sentence as a confirmed one.
+        c.cause = 'primary';
+    }
+    // --- 5. Roll derived-of-derived up to the act that started it ------------
+    // Without this, a pushed row and the four words inside it become five groups
+    // that all mean "because e6 was inserted".
+    //
+    // Two maps, not one (B1). An element can carry *both* a geometry-derived
+    // `box` change (via a sibling or ancestor that moved it) and a
+    // paint-derived `style` change (via an ancestor's colour cascade) at once —
+    // the same element is simultaneously a link in a "carried" chain and a
+    // link in an "inherited" chain, for entirely unrelated reasons. A single
+    // `Map<afterId, …>` has room for only one entry per id, so whichever of the
+    // two changes was recorded later in `changes` silently overwrote the
+    // other's roll-up target: a descendant's colour, correctly traced back to
+    // an ancestor's real colour change, could have its `rootVia` hijacked
+    // mid-walk by that same ancestor's *unrelated* box-carry entry — producing
+    // `~ e4 color inherited from e2` when `e2` never had a colour change at
+    // all, with the underlying `rootHow` left as `carried` beneath a line that
+    // reads "inherited" (`foldDerived` in `render.ts` decides the wording from
+    // `kind`, not from `rootHow`, so the mismatch is invisible until the JSON
+    // is inspected). Keeping geometry and paint in separate maps means a walk
+    // started by a `box` change can only ever continue through other `box`
+    // changes, and a walk started by a `style` change only through other
+    // `style` changes — the two causal chains can share an element without
+    // being able to overwrite each other's link at it.
+    const geometryViaOf = new Map();
+    const paintViaOf = new Map();
+    for (const c of changes) {
+        if (c.cause !== 'derived' || !c.via || !c.afterId)
+            continue;
+        if (c.kind === 'box')
+            geometryViaOf.set(c.afterId, { via: c.via, how: c.how });
+        else if (c.kind === 'style')
+            paintViaOf.set(c.afterId, { via: c.via, how: c.how });
+    }
+    for (const c of changes) {
+        if (c.cause !== 'derived' || !c.via)
+            continue;
+        const viaOf = c.kind === 'box' ? geometryViaOf : c.kind === 'style' ? paintViaOf : undefined;
+        if (!viaOf) {
+            c.rootVia = c.via;
+            if (c.how)
+                c.rootHow = c.how;
+            continue;
+        }
+        const seen = new Set();
+        if (c.afterId)
+            seen.add(c.afterId);
+        let cursor = c.via;
+        let how = c.how;
+        while (!seen.has(cursor)) {
+            const up = viaOf.get(cursor);
+            if (!up)
+                break;
+            seen.add(cursor);
+            // A paint change does not move anything, so passing through one must not
+            // rewrite a geometric consequence as `inherited`.
+            how = up.how === 'inherited' ? how : up.how;
+            cursor = up.via;
+        }
+        c.rootVia = cursor;
+        if (how)
+            c.rootHow = how;
+    }
+}