@variance-authority/core 0.1.0

package/dist/compare/parting.d.ts

@@ -0,0 +1,179 @@
+import type { Digest } from '../format/hash.js';
+import type { NodePath, SemanticSnapshot } from '../format/snapshot.js';
+import { type Band } from './band.js';
+import { type Delta } from './diff/index.js';
+import { type PartingSlice } from './slice.js';
+/**
+ * Where two readings of one page parted.
+ *
+ * A diff says a `<div>` rendered a `<p>` on one side and a `<span>` on the
+ * other. That is a symptom, and acting on it means reading the component,
+ * guessing which branch ran, and guessing why. This says: `Cart`'s `useState` at
+ * call 2 held different values, so `Summary` was handed a different `total`, so
+ * the tag moved. Same evidence, three rungs up.
+ *
+ * The rung it can reach is decided by how much of the boundary was readable, and
+ * the difference between the top two rungs is the whole point:
+ *
+ * - **collateral** — a prop or a context this boundary *received* moved, so the
+ *   difference arrived from outside and something above it is the cause.
+ * - **origin** — every input this boundary received held, and its own retained
+ *   state moved. Nothing above it explains this; it is the answer.
+ *
+ * The mechanism is one rule applied at every boundary: *a component whose
+ * inputs agreed and whose output moved decided differently.* Walking the tree
+ * for the shallowest boundary where that holds is what turns a page of deltas
+ * into one sentence — and the same rule, run over two readings of one page
+ * rather than two arms of an experiment, is what separates a flake from a
+ * change. A flake is the case where nothing readable moved at all
+ * ({@link PartingRung} `undetermined`), and it is only nameable because
+ * `unread` is a rung of its own: an accusation of nondeterminism may only be
+ * made about inputs somebody actually read (ADR-0002).
+ *
+ * Not `attribute/composition.ts`'s `Divergence`, which is the same suspicion
+ * arrived at from the other side: one component rendering two ways from one
+ * props digest *within* a run, found by counting sites. That one can say a
+ * component's inputs do not determine its output; this one can say which input.
+ *
+ * Nothing here reaches a hash. {@link Holding} is evidence carried beside the
+ * snapshot, exactly as `styleProvenance` is, and for the reason `wiring.ts`
+ * gives: a hook's value is the thing that legitimately differs between two
+ * readings of one page, so a band carrying it would be a flake generator wearing
+ * a band's name. This module is the reader that value was kept for.
+ */
+export interface Parting {
+    /**
+     * What kind of parting this is, decided before which input moved.
+     *
+     * The triage line. `refactor` and `settled` are pages nobody needs to open,
+     * `flake` is a page whose baseline is the problem, and `variation` is the
+     * only one where the rungs below are worth reading.
+     */
+    readonly slice: PartingSlice;
+    /** `true` when both render hashes agree. Inputs may still have moved. */
+    readonly identical: boolean;
+    /** Every delta, unchanged, so a caller need not run the comparison twice. */
+    readonly deltas: readonly Delta[];
+    /**
+     * Boundaries where something moved — an input, an output, or both — in
+     * document order.
+     *
+     * Absent, never `[]`, when no node on either side started a component: a page
+     * read with no framework adapter has not been found to agree, it has not been
+     * asked (ADR-0002). Present with every boundary at rung `unread` is the next
+     * reading up — the components were found and their inputs were not.
+     */
+    readonly boundaries?: readonly PartedBoundary[];
+    /**
+     * The boundaries the difference started at, shallowest first.
+     *
+     * A subset of {@link boundaries}: those whose output moved without an
+     * incoming input to explain it. Usually one. More than one means the two
+     * renders differ in more than one place, which is a real answer rather than a
+     * failure to narrow.
+     */
+    readonly origins?: readonly PartedBoundary[];
+}
+/**
+ * One component boundary, and what moved at it.
+ *
+ * A boundary is a component's root host node — `componentFiberOf`'s definition,
+ * shared with the wiring band so the two can never disagree about where a
+ * component starts. A component that vanished entirely has no boundary here: its
+ * nodes leave `node-removed` deltas that attribute to the *parent* boundary,
+ * which is the correct answer, because deciding not to render a child is
+ * something the parent did.
+ */
+export interface PartedBoundary {
+    /** `displayName`, or `(anonymous)` when provenance did not name it. */
+    readonly component: string;
+    /** Path in the candidate tree. */
+    readonly path: NodePath;
+    /** Depth of {@link path}, so callers can order without re-parsing it. */
+    readonly depth: number;
+    readonly rung: PartingRung;
+    /**
+     * Inputs that differ: props, then contexts, then hook calls in order, then
+     * the inherited properties no declaration at this boundary accounts for.
+     */
+    readonly inputs: readonly MovedInput[];
+    /**
+     * Deltas at or under this boundary that no nested boundary owns.
+     *
+     * Zero is meaningful and is not a filtered-out row: a boundary with moved
+     * inputs and no deltas of its own is the negative result an experiment
+     * usually wants — this arm was assigned differently and rendered the same.
+     */
+    readonly deltas: number;
+    /** Bands those deltas fall in, in band order. */
+    readonly bands: readonly Band[];
+    /**
+     * The properties the owned deltas named, deduplicated and in code-unit order.
+     *
+     * The last joint of the chain the rungs above climb: a hook cell moved, a prop
+     * carried it down, and *this* is what the prop turned into on the page —
+     * `color`, `padding-top`, `width`. A reader chasing a visual regression is
+     * looking for this list, and `deltas: 7` alone sends them back to the delta
+     * array to assemble it.
+     *
+     * Absent when no owned delta named a property, which is a reading rather than
+     * a gap: a removed node and a changed accessible name are whole-node facts and
+     * have no property to name. `deltas` and `bands` still say what happened
+     * there.
+     */
+    readonly moved?: readonly string[];
+}
+/**
+ * How far up the difference could be traced at one boundary.
+ *
+ * Ordered by precedence, and the ordering is the reasoning. Any input that
+ * arrived from outside settles the question — this boundary is downstream of
+ * the cause, whatever else it may also be holding — so `handed` and `provided`
+ * outrank the state rungs. `unread` outranks `undetermined` for the same reason
+ * pointed the other way: silence is not agreement.
+ */
+export type PartingRung = 
+/** A named prop differs. The parent decided this; look up. */
+'handed'
+/** A context value differs. A provider above decided this; look up. */
+ | 'provided'
+/**
+ * An inherited style value differs, and this boundary declares none of it.
+ * An ancestor's cascade decided this; look up.
+ */
+ | 'inherited'
+/** A `useSyncExternalStore` snapshot differs — the store moved, outside React. */
+ | 'external'
+/** An own hook cell differs. **This is the cause.** */
+ | 'stateful'
+/** The output moved and something this boundary depends on could not be read. */
+ | 'unread'
+/** Every input was read, every input agreed, and the output moved anyway. */
+ | 'undetermined'
+/** The boundary exists on one side only. */
+ | 'unpaired';
+export interface MovedInput {
+    readonly kind: 'prop' | 'context' | 'hook' | 'inherited';
+    /**
+     * Prop name, context display name, hook name (`useState`), or — for
+     * `inherited` — the CSS property an ancestor decided.
+     */
+    readonly name: string;
+    /** Hook call position — the index a reader gets counting down the component. */
+    readonly index?: number;
+    /**
+     * Explicitly `| undefined`, on {@link Delta}'s rule: an input present on one
+     * side only is the reading, not a field somebody forgot.
+     */
+    readonly from?: Digest | undefined;
+    readonly to?: Digest | undefined;
+}
+/**
+ * Two snapshots of the same page, read for where they parted.
+ *
+ * Takes snapshots rather than trees, and takes them without refusing a subject
+ * mismatch, for `compareTrees`' stated reason: this produces an *explanation*,
+ * not a verdict, and two arms of an experiment are two subjects on purpose.
+ */
+export declare function partingOf(baseline: SemanticSnapshot, candidate: SemanticSnapshot): Parting;
+//# sourceMappingURL=parting.d.ts.map

package/dist/compare/parting.js

@@ -0,0 +1,244 @@
+import { boundaries as componentBoundaries, UNATTRIBUTED } from '../attribute/boundary.js';
+import { BANDS, bandOf } from './band.js';
+import { compareTrees, matchTrees } from './diff/index.js';
+import { cascadeInputs, declaredIn } from './cascade.js';
+import { compareHoldings } from './holding-diff.js';
+import { sameTree, sliceOf } from './slice.js';
+/**
+ * Two snapshots of the same page, read for where they parted.
+ *
+ * Takes snapshots rather than trees, and takes them without refusing a subject
+ * mismatch, for `compareTrees`' stated reason: this produces an *explanation*,
+ * not a verdict, and two arms of an experiment are two subjects on purpose.
+ */
+export function partingOf(baseline, candidate) {
+    const comparison = compareTrees(baseline, candidate);
+    const matching = matchTrees(baseline.root, candidate.root);
+    const partner = new Map();
+    for (const [left, right] of matching.pairs)
+        partner.set(right, left);
+    const tree = sameTree(baseline.root, candidate.root);
+    const moved = comparison.deltas.length > 0;
+    const found = boundariesOf(baseline.root, candidate.root, partner, {
+        there: declaredIn(baseline),
+        here: declaredIn(candidate),
+    });
+    if (found === undefined) {
+        return {
+            slice: sliceOf(tree, undefined, moved),
+            identical: comparison.identical,
+            deltas: comparison.deltas,
+        };
+    }
+    attribute(found, comparison.deltas);
+    const boundaries = found
+        .filter((entry) => entry.inputs.length > 0 || entry.owned.length > 0)
+        .map(settle);
+    const origins = boundaries.filter((entry) => entry.rung === 'stateful' || entry.rung === 'external' || entry.rung === 'undetermined');
+    return {
+        slice: sliceOf(tree, boundaries, moved),
+        identical: comparison.identical,
+        deltas: comparison.deltas,
+        boundaries,
+        ...(origins.length > 0 ? { origins: [...origins].sort((a, b) => a.depth - b.depth) } : {}),
+    };
+}
+/**
+ * Every boundary in the candidate tree, in document order, paired with its
+ * baseline counterpart.
+ *
+ * Undefined when neither tree carried a holding at all, which is the ADR-0002
+ * distinction this whole module rests on: nothing to read is not nothing to
+ * report.
+ */
+function boundariesOf(baselineRoot, candidateRoot, partner, declared) {
+    const mine = boundaryNodes(candidateRoot);
+    const theirs = boundaryNodes(baselineRoot);
+    if (mine.length === 0 && theirs.length === 0)
+        return undefined;
+    const paired = pairBoundaries(mine, theirs, partner);
+    return mine.map((node) => {
+        const other = paired.get(node);
+        const moved = compareHoldings(other?.holding, node.holding);
+        const inputs = [
+            ...moved.inputs,
+            ...cascadeInputs(other, node, declared.there, declared.here),
+        ];
+        return {
+            component: node.provenance?.owners[0]?.name ?? '(anonymous)',
+            path: node.path,
+            ...(other === undefined ? {} : { basePath: other.path }),
+            depth: depthOf(node.path),
+            inputs,
+            unread: moved.unread,
+            paired: other !== undefined,
+            owned: [],
+        };
+    });
+}
+/**
+ * Every node where a component starts, in document order.
+ *
+ * Read from provenance and not from `holding`, which is the difference between
+ * this module working on one collector and working on all of them. A holding is
+ * what a *framework adapter* managed to read at a boundary — props values, hook
+ * cells — and only `@variance-authority/unit-test` supplies one today. Keying the
+ * boundary set on it made every rung unreachable from a browser run, including
+ * the two that need no adapter at all: the ancestor cascade, which is read from
+ * `styleProvenance`, and the tree comparison, which is read from the owner
+ * chains. Those runs got `unread` — "nothing can be said about why" — while
+ * holding the evidence to say it.
+ *
+ * {@link componentBoundaries} is the shared definition, so a boundary here is
+ * the same node the component hashes and the wiring band call one. It reports a
+ * node once per component that opens there; the nodes are what this needs, and
+ * `boundariesOf` names each by its innermost owner exactly as before.
+ *
+ * A node with a holding and no provenance is still kept. That is an adapter that
+ * read the fiber's values but not its owner chain, and dropping its evidence
+ * because of a second failure would lose the one rung it can still reach.
+ */
+function boundaryNodes(root) {
+    const found = new Set();
+    for (const boundary of componentBoundaries(root)) {
+        // `(unattributed)` is the bucket for nodes whose owner chain broke, not a
+        // component, and `causesBetween` refuses it for the same reason: a boundary
+        // reported there would name a component nobody wrote and pool unrelated
+        // parts of the page under one name.
+        if (boundary.component === UNATTRIBUTED)
+            continue;
+        found.add(boundary.node);
+    }
+    const holders = (node) => {
+        if (node.holding !== undefined)
+            found.add(node);
+        for (const child of node.children)
+            holders(child);
+    };
+    holders(root);
+    return [...found].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+/**
+ * Pair boundaries, preferring the tree matcher and falling back to the owner
+ * chain.
+ *
+ * The fallback is not a nicety, it is the case the whole module exists for. A
+ * component that took the other branch returns a `<span>` where it returned a
+ * `<p>`, and no host-level matcher pairs those: the tag is the thing that
+ * changed, and every identity key ends in it. Reporting the boundary as present
+ * on one side only would throw away the props and the hook cells at exactly the
+ * moment they are the answer — `Summary` did not appear, it *chose differently*,
+ * and the evidence for that is sitting in a holding nobody joined.
+ *
+ * The chain — the boundary's owner names, outermost component included — is
+ * stable under precisely that change, since neither the branch nor the tag
+ * appears in it. Ties inside one chain are broken by document order, which is
+ * positional and therefore shifts when a sibling is inserted; that is the same
+ * cost `match.ts` pays for the same reason, and it is bounded here to
+ * components sharing one chain that the matcher already failed to pair.
+ */
+function pairBoundaries(mine, theirs, partner) {
+    const paired = new Map();
+    const taken = new Set();
+    for (const node of mine) {
+        const other = partner.get(node);
+        if (other?.holding === undefined || taken.has(other))
+            continue;
+        paired.set(node, other);
+        taken.add(other);
+    }
+    const spare = new Map();
+    for (const node of theirs) {
+        if (taken.has(node))
+            continue;
+        const key = chainOf(node);
+        const bucket = spare.get(key);
+        if (bucket === undefined)
+            spare.set(key, [node]);
+        else
+            bucket.push(node);
+    }
+    for (const node of mine) {
+        if (paired.has(node))
+            continue;
+        const bucket = spare.get(chainOf(node));
+        const other = bucket?.shift();
+        if (other !== undefined)
+            paired.set(node, other);
+    }
+    return paired;
+}
+function chainOf(node) {
+    return (node.provenance?.owners ?? []).map((owner) => owner.name).join('>');
+}
+/**
+ * Give each delta to the deepest boundary that encloses it.
+ *
+ * By prefix rather than by scanning every boundary: a node's path *is* its
+ * ancestry, so walking it up one segment at a time reaches the owning boundary
+ * in as many steps as the node is deep. A `node-removed` delta carries a
+ * baseline path, so it is resolved in baseline space — mixing the two spaces
+ * would silently hand a removal to whichever candidate node now sits at that
+ * address, which is the exact misattribution positional diffing is famous for.
+ */
+function attribute(drafts, deltas) {
+    const here = new Map();
+    const there = new Map();
+    for (const draft of drafts) {
+        here.set(draft.path, draft);
+        if (draft.basePath !== undefined)
+            there.set(draft.basePath, draft);
+    }
+    for (const delta of deltas) {
+        const index = delta.kind === 'node-removed' ? there : here;
+        for (let path = delta.path; path !== undefined; path = parentOf(path)) {
+            const owner = index.get(path);
+            if (owner !== undefined) {
+                owner.owned.push(delta);
+                break;
+            }
+        }
+    }
+}
+/** Apply the precedence in {@link PartingRung} and freeze the row. */
+function settle(draft) {
+    const bands = BANDS.filter((band) => draft.owned.some((delta) => bandOf(delta.kind) === band));
+    const moved = [
+        ...new Set(draft.owned.map((delta) => delta.property).filter((name) => name !== undefined)),
+    ].sort();
+    return {
+        component: draft.component,
+        path: draft.path,
+        depth: draft.depth,
+        rung: rungOf(draft),
+        inputs: draft.inputs,
+        deltas: draft.owned.length,
+        bands,
+        ...(moved.length > 0 ? { moved } : {}),
+    };
+}
+function rungOf(draft) {
+    if (!draft.paired)
+        return 'unpaired';
+    if (draft.inputs.some((input) => input.kind === 'prop'))
+        return 'handed';
+    if (draft.inputs.some((input) => input.kind === 'context'))
+        return 'provided';
+    if (draft.inputs.some((input) => input.kind === 'inherited'))
+        return 'inherited';
+    if (draft.inputs.some((input) => input.name === 'useSyncExternalStore'))
+        return 'external';
+    if (draft.inputs.length > 0)
+        return 'stateful';
+    return draft.unread ? 'unread' : 'undetermined';
+}
+function depthOf(path) {
+    return path === '' ? 0 : path.split('/').length;
+}
+function parentOf(path) {
+    if (path === '')
+        return undefined;
+    const cut = path.lastIndexOf('/');
+    return cut === -1 ? '' : path.slice(0, cut);
+}
+//# sourceMappingURL=parting.js.map

package/dist/compare/parting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parting.js","sourceRoot":"","sources":["../../src/compare/parting.ts"],"names":[],"mappings":"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","sourcesContent":["import { boundaries as componentBoundaries, UNATTRIBUTED } from '../attribute/boundary.js';\nimport type { Digest } from '../format/hash.js';\nimport type { NodePath, SemanticNode, SemanticSnapshot } from '../format/snapshot.js';\nimport { BANDS, bandOf, type Band } from './band.js';\nimport { compareTrees, matchTrees, type Delta } from './diff/index.js';\nimport { cascadeInputs, declaredIn } from './cascade.js';\nimport { compareHoldings } from './holding-diff.js';\nimport { sameTree, sliceOf, type PartingSlice } from './slice.js';\n\n/**\n * Where two readings of one page parted.\n *\n * A diff says a `<div>` rendered a `<p>` on one side and a `<span>` on the\n * other. That is a symptom, and acting on it means reading the component,\n * guessing which branch ran, and guessing why. This says: `Cart`'s `useState` at\n * call 2 held different values, so `Summary` was handed a different `total`, so\n * the tag moved. Same evidence, three rungs up.\n *\n * The rung it can reach is decided by how much of the boundary was readable, and\n * the difference between the top two rungs is the whole point:\n *\n * - **collateral** — a prop or a context this boundary *received* moved, so the\n *   difference arrived from outside and something above it is the cause.\n * - **origin** — every input this boundary received held, and its own retained\n *   state moved. Nothing above it explains this; it is the answer.\n *\n * The mechanism is one rule applied at every boundary: *a component whose\n * inputs agreed and whose output moved decided differently.* Walking the tree\n * for the shallowest boundary where that holds is what turns a page of deltas\n * into one sentence — and the same rule, run over two readings of one page\n * rather than two arms of an experiment, is what separates a flake from a\n * change. A flake is the case where nothing readable moved at all\n * ({@link PartingRung} `undetermined`), and it is only nameable because\n * `unread` is a rung of its own: an accusation of nondeterminism may only be\n * made about inputs somebody actually read (ADR-0002).\n *\n * Not `attribute/composition.ts`'s `Divergence`, which is the same suspicion\n * arrived at from the other side: one component rendering two ways from one\n * props digest *within* a run, found by counting sites. That one can say a\n * component's inputs do not determine its output; this one can say which input.\n *\n * Nothing here reaches a hash. {@link Holding} is evidence carried beside the\n * snapshot, exactly as `styleProvenance` is, and for the reason `wiring.ts`\n * gives: a hook's value is the thing that legitimately differs between two\n * readings of one page, so a band carrying it would be a flake generator wearing\n * a band's name. This module is the reader that value was kept for.\n */\nexport interface Parting {\n  /**\n   * What kind of parting this is, decided before which input moved.\n   *\n   * The triage line. `refactor` and `settled` are pages nobody needs to open,\n   * `flake` is a page whose baseline is the problem, and `variation` is the\n   * only one where the rungs below are worth reading.\n   */\n  readonly slice: PartingSlice;\n\n  /** `true` when both render hashes agree. Inputs may still have moved. */\n  readonly identical: boolean;\n\n  /** Every delta, unchanged, so a caller need not run the comparison twice. */\n  readonly deltas: readonly Delta[];\n\n  /**\n   * Boundaries where something moved — an input, an output, or both — in\n   * document order.\n   *\n   * Absent, never `[]`, when no node on either side started a component: a page\n   * read with no framework adapter has not been found to agree, it has not been\n   * asked (ADR-0002). Present with every boundary at rung `unread` is the next\n   * reading up — the components were found and their inputs were not.\n   */\n  readonly boundaries?: readonly PartedBoundary[];\n\n  /**\n   * The boundaries the difference started at, shallowest first.\n   *\n   * A subset of {@link boundaries}: those whose output moved without an\n   * incoming input to explain it. Usually one. More than one means the two\n   * renders differ in more than one place, which is a real answer rather than a\n   * failure to narrow.\n   */\n  readonly origins?: readonly PartedBoundary[];\n}\n\n/**\n * One component boundary, and what moved at it.\n *\n * A boundary is a component's root host node — `componentFiberOf`'s definition,\n * shared with the wiring band so the two can never disagree about where a\n * component starts. A component that vanished entirely has no boundary here: its\n * nodes leave `node-removed` deltas that attribute to the *parent* boundary,\n * which is the correct answer, because deciding not to render a child is\n * something the parent did.\n */\nexport interface PartedBoundary {\n  /** `displayName`, or `(anonymous)` when provenance did not name it. */\n  readonly component: string;\n\n  /** Path in the candidate tree. */\n  readonly path: NodePath;\n\n  /** Depth of {@link path}, so callers can order without re-parsing it. */\n  readonly depth: number;\n\n  readonly rung: PartingRung;\n\n  /**\n   * Inputs that differ: props, then contexts, then hook calls in order, then\n   * the inherited properties no declaration at this boundary accounts for.\n   */\n  readonly inputs: readonly MovedInput[];\n\n  /**\n   * Deltas at or under this boundary that no nested boundary owns.\n   *\n   * Zero is meaningful and is not a filtered-out row: a boundary with moved\n   * inputs and no deltas of its own is the negative result an experiment\n   * usually wants — this arm was assigned differently and rendered the same.\n   */\n  readonly deltas: number;\n\n  /** Bands those deltas fall in, in band order. */\n  readonly bands: readonly Band[];\n\n  /**\n   * The properties the owned deltas named, deduplicated and in code-unit order.\n   *\n   * The last joint of the chain the rungs above climb: a hook cell moved, a prop\n   * carried it down, and *this* is what the prop turned into on the page —\n   * `color`, `padding-top`, `width`. A reader chasing a visual regression is\n   * looking for this list, and `deltas: 7` alone sends them back to the delta\n   * array to assemble it.\n   *\n   * Absent when no owned delta named a property, which is a reading rather than\n   * a gap: a removed node and a changed accessible name are whole-node facts and\n   * have no property to name. `deltas` and `bands` still say what happened\n   * there.\n   */\n  readonly moved?: readonly string[];\n}\n\n/**\n * How far up the difference could be traced at one boundary.\n *\n * Ordered by precedence, and the ordering is the reasoning. Any input that\n * arrived from outside settles the question — this boundary is downstream of\n * the cause, whatever else it may also be holding — so `handed` and `provided`\n * outrank the state rungs. `unread` outranks `undetermined` for the same reason\n * pointed the other way: silence is not agreement.\n */\nexport type PartingRung =\n  /** A named prop differs. The parent decided this; look up. */\n  | 'handed'\n  /** A context value differs. A provider above decided this; look up. */\n  | 'provided'\n  /**\n   * An inherited style value differs, and this boundary declares none of it.\n   * An ancestor's cascade decided this; look up.\n   */\n  | 'inherited'\n  /** A `useSyncExternalStore` snapshot differs — the store moved, outside React. */\n  | 'external'\n  /** An own hook cell differs. **This is the cause.** */\n  | 'stateful'\n  /** The output moved and something this boundary depends on could not be read. */\n  | 'unread'\n  /** Every input was read, every input agreed, and the output moved anyway. */\n  | 'undetermined'\n  /** The boundary exists on one side only. */\n  | 'unpaired';\n\nexport interface MovedInput {\n  readonly kind: 'prop' | 'context' | 'hook' | 'inherited';\n\n  /**\n   * Prop name, context display name, hook name (`useState`), or — for\n   * `inherited` — the CSS property an ancestor decided.\n   */\n  readonly name: string;\n\n  /** Hook call position — the index a reader gets counting down the component. */\n  readonly index?: number;\n\n  /**\n   * Explicitly `| undefined`, on {@link Delta}'s rule: an input present on one\n   * side only is the reading, not a field somebody forgot.\n   */\n  readonly from?: Digest | undefined;\n  readonly to?: Digest | undefined;\n}\n\n/**\n * Two snapshots of the same page, read for where they parted.\n *\n * Takes snapshots rather than trees, and takes them without refusing a subject\n * mismatch, for `compareTrees`' stated reason: this produces an *explanation*,\n * not a verdict, and two arms of an experiment are two subjects on purpose.\n */\nexport function partingOf(baseline: SemanticSnapshot, candidate: SemanticSnapshot): Parting {\n  const comparison = compareTrees(baseline, candidate);\n  const matching = matchTrees(baseline.root, candidate.root);\n\n  const partner = new Map<SemanticNode, SemanticNode>();\n  for (const [left, right] of matching.pairs) partner.set(right, left);\n\n  const tree = sameTree(baseline.root, candidate.root);\n  const moved = comparison.deltas.length > 0;\n\n  const found = boundariesOf(baseline.root, candidate.root, partner, {\n    there: declaredIn(baseline),\n    here: declaredIn(candidate),\n  });\n  if (found === undefined) {\n    return {\n      slice: sliceOf(tree, undefined, moved),\n      identical: comparison.identical,\n      deltas: comparison.deltas,\n    };\n  }\n\n  attribute(found, comparison.deltas);\n\n  const boundaries = found\n    .filter((entry) => entry.inputs.length > 0 || entry.owned.length > 0)\n    .map(settle);\n\n  const origins = boundaries.filter(\n    (entry) => entry.rung === 'stateful' || entry.rung === 'external' || entry.rung === 'undetermined',\n  );\n\n  return {\n    slice: sliceOf(tree, boundaries, moved),\n    identical: comparison.identical,\n    deltas: comparison.deltas,\n    boundaries,\n    ...(origins.length > 0 ? { origins: [...origins].sort((a, b) => a.depth - b.depth) } : {}),\n  };\n}\n\n/** A boundary mid-construction, before its deltas are counted. */\ninterface Draft {\n  readonly component: string;\n  readonly path: NodePath;\n  readonly basePath?: NodePath;\n  readonly depth: number;\n  readonly inputs: readonly MovedInput[];\n  readonly unread: boolean;\n  readonly paired: boolean;\n  readonly owned: Delta[];\n}\n\n/**\n * Every boundary in the candidate tree, in document order, paired with its\n * baseline counterpart.\n *\n * Undefined when neither tree carried a holding at all, which is the ADR-0002\n * distinction this whole module rests on: nothing to read is not nothing to\n * report.\n */\nfunction boundariesOf(\n  baselineRoot: SemanticNode,\n  candidateRoot: SemanticNode,\n  partner: ReadonlyMap<SemanticNode, SemanticNode>,\n  declared: { readonly there: ReadonlySet<string>; readonly here: ReadonlySet<string> },\n): Draft[] | undefined {\n  const mine = boundaryNodes(candidateRoot);\n  const theirs = boundaryNodes(baselineRoot);\n  if (mine.length === 0 && theirs.length === 0) return undefined;\n\n  const paired = pairBoundaries(mine, theirs, partner);\n\n  return mine.map((node) => {\n    const other = paired.get(node);\n    const moved = compareHoldings(other?.holding, node.holding);\n    const inputs = [\n      ...moved.inputs,\n      ...cascadeInputs(other, node, declared.there, declared.here),\n    ];\n    return {\n      component: node.provenance?.owners[0]?.name ?? '(anonymous)',\n      path: node.path,\n      ...(other === undefined ? {} : { basePath: other.path }),\n      depth: depthOf(node.path),\n      inputs,\n      unread: moved.unread,\n      paired: other !== undefined,\n      owned: [],\n    };\n  });\n}\n\n/**\n * Every node where a component starts, in document order.\n *\n * Read from provenance and not from `holding`, which is the difference between\n * this module working on one collector and working on all of them. A holding is\n * what a *framework adapter* managed to read at a boundary — props values, hook\n * cells — and only `@variance-authority/unit-test` supplies one today. Keying the\n * boundary set on it made every rung unreachable from a browser run, including\n * the two that need no adapter at all: the ancestor cascade, which is read from\n * `styleProvenance`, and the tree comparison, which is read from the owner\n * chains. Those runs got `unread` — \"nothing can be said about why\" — while\n * holding the evidence to say it.\n *\n * {@link componentBoundaries} is the shared definition, so a boundary here is\n * the same node the component hashes and the wiring band call one. It reports a\n * node once per component that opens there; the nodes are what this needs, and\n * `boundariesOf` names each by its innermost owner exactly as before.\n *\n * A node with a holding and no provenance is still kept. That is an adapter that\n * read the fiber's values but not its owner chain, and dropping its evidence\n * because of a second failure would lose the one rung it can still reach.\n */\nfunction boundaryNodes(root: SemanticNode): readonly SemanticNode[] {\n  const found = new Set<SemanticNode>();\n  for (const boundary of componentBoundaries(root)) {\n    // `(unattributed)` is the bucket for nodes whose owner chain broke, not a\n    // component, and `causesBetween` refuses it for the same reason: a boundary\n    // reported there would name a component nobody wrote and pool unrelated\n    // parts of the page under one name.\n    if (boundary.component === UNATTRIBUTED) continue;\n    found.add(boundary.node);\n  }\n\n  const holders = (node: SemanticNode): void => {\n    if (node.holding !== undefined) found.add(node);\n    for (const child of node.children) holders(child);\n  };\n  holders(root);\n\n  return [...found].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));\n}\n\n/**\n * Pair boundaries, preferring the tree matcher and falling back to the owner\n * chain.\n *\n * The fallback is not a nicety, it is the case the whole module exists for. A\n * component that took the other branch returns a `<span>` where it returned a\n * `<p>`, and no host-level matcher pairs those: the tag is the thing that\n * changed, and every identity key ends in it. Reporting the boundary as present\n * on one side only would throw away the props and the hook cells at exactly the\n * moment they are the answer — `Summary` did not appear, it *chose differently*,\n * and the evidence for that is sitting in a holding nobody joined.\n *\n * The chain — the boundary's owner names, outermost component included — is\n * stable under precisely that change, since neither the branch nor the tag\n * appears in it. Ties inside one chain are broken by document order, which is\n * positional and therefore shifts when a sibling is inserted; that is the same\n * cost `match.ts` pays for the same reason, and it is bounded here to\n * components sharing one chain that the matcher already failed to pair.\n */\nfunction pairBoundaries(\n  mine: readonly SemanticNode[],\n  theirs: readonly SemanticNode[],\n  partner: ReadonlyMap<SemanticNode, SemanticNode>,\n): ReadonlyMap<SemanticNode, SemanticNode> {\n  const paired = new Map<SemanticNode, SemanticNode>();\n  const taken = new Set<SemanticNode>();\n\n  for (const node of mine) {\n    const other = partner.get(node);\n    if (other?.holding === undefined || taken.has(other)) continue;\n    paired.set(node, other);\n    taken.add(other);\n  }\n\n  const spare = new Map<string, SemanticNode[]>();\n  for (const node of theirs) {\n    if (taken.has(node)) continue;\n    const key = chainOf(node);\n    const bucket = spare.get(key);\n    if (bucket === undefined) spare.set(key, [node]);\n    else bucket.push(node);\n  }\n\n  for (const node of mine) {\n    if (paired.has(node)) continue;\n    const bucket = spare.get(chainOf(node));\n    const other = bucket?.shift();\n    if (other !== undefined) paired.set(node, other);\n  }\n\n  return paired;\n}\n\nfunction chainOf(node: SemanticNode): string {\n  return (node.provenance?.owners ?? []).map((owner) => owner.name).join('>');\n}\n\n/**\n * Give each delta to the deepest boundary that encloses it.\n *\n * By prefix rather than by scanning every boundary: a node's path *is* its\n * ancestry, so walking it up one segment at a time reaches the owning boundary\n * in as many steps as the node is deep. A `node-removed` delta carries a\n * baseline path, so it is resolved in baseline space — mixing the two spaces\n * would silently hand a removal to whichever candidate node now sits at that\n * address, which is the exact misattribution positional diffing is famous for.\n */\nfunction attribute(drafts: readonly Draft[], deltas: readonly Delta[]): void {\n  const here = new Map<NodePath, Draft>();\n  const there = new Map<NodePath, Draft>();\n  for (const draft of drafts) {\n    here.set(draft.path, draft);\n    if (draft.basePath !== undefined) there.set(draft.basePath, draft);\n  }\n\n  for (const delta of deltas) {\n    const index = delta.kind === 'node-removed' ? there : here;\n    for (let path: NodePath | undefined = delta.path; path !== undefined; path = parentOf(path)) {\n      const owner = index.get(path);\n      if (owner !== undefined) {\n        owner.owned.push(delta);\n        break;\n      }\n    }\n  }\n}\n\n/** Apply the precedence in {@link PartingRung} and freeze the row. */\nfunction settle(draft: Draft): PartedBoundary {\n  const bands = BANDS.filter((band) => draft.owned.some((delta) => bandOf(delta.kind) === band));\n\n  const moved = [\n    ...new Set(draft.owned.map((delta) => delta.property).filter((name) => name !== undefined)),\n  ].sort();\n\n  return {\n    component: draft.component,\n    path: draft.path,\n    depth: draft.depth,\n    rung: rungOf(draft),\n    inputs: draft.inputs,\n    deltas: draft.owned.length,\n    bands,\n    ...(moved.length > 0 ? { moved } : {}),\n  };\n}\n\nfunction rungOf(draft: Draft): PartingRung {\n  if (!draft.paired) return 'unpaired';\n  if (draft.inputs.some((input) => input.kind === 'prop')) return 'handed';\n  if (draft.inputs.some((input) => input.kind === 'context')) return 'provided';\n  if (draft.inputs.some((input) => input.kind === 'inherited')) return 'inherited';\n  if (draft.inputs.some((input) => input.name === 'useSyncExternalStore')) return 'external';\n  if (draft.inputs.length > 0) return 'stateful';\n  return draft.unread ? 'unread' : 'undetermined';\n}\n\n\nfunction depthOf(path: NodePath): number {\n  return path === '' ? 0 : path.split('/').length;\n}\n\nfunction parentOf(path: NodePath): NodePath | undefined {\n  if (path === '') return undefined;\n  const cut = path.lastIndexOf('/');\n  return cut === -1 ? '' : path.slice(0, cut);\n}\n"]}

package/dist/compare/slice.d.ts

@@ -0,0 +1,74 @@
+import type { SemanticNode } from '../format/snapshot.js';
+import type { PartedBoundary } from './parting.js';
+/**
+ * What kind of parting this is, before anything about which one.
+ *
+ * The rungs in `parting.ts` answer *which input moved*. This answers the
+ * question asked first and answered least: **is this worth looking at at all.**
+ * Three facts are read independently — did the component tree move, did any
+ * input move, did the output move — and the eight combinations collapse to
+ * seven sentences, five of which are a triage decision on their own:
+ *
+ * | component tree | inputs | output | slice |
+ * |---|---|---|---|
+ * | same | same | **moved** | `flake` |
+ * | any | **moved** | **moved** | `variation` |
+ * | **moved** | same | **moved** | `reshaped` |
+ * | **moved** | any | same | `refactor` |
+ * | same | **moved** | same | `absorbed` |
+ * | same | same | same | `settled` |
+ * | unread | — | **moved** | `unread` |
+ *
+ * `reshaped` is the row that used to be missing. It was answered `variation`,
+ * whose sentence says an input moved — and the whole point of this table is
+ * that in that row no input did. Two readings whose component trees are not the
+ * same tree, reached from inputs that all agreed, is a component that chose a
+ * different shape: a branch taken differently between two arms, or a rewrite
+ * between two revisions. Either way the tree is the finding and the rungs below
+ * have nothing to add, because there is no moved input for them to name.
+ *
+ * `refactor` is the one that pays for the other six. A component tree that
+ * moved while the page did not is the receipt a refactor never gets: the
+ * screenshots match, which is what a pixel differ says and all it says, and
+ * *the components underneath were rewritten*, which is the fact somebody wanted
+ * confirmed before merging.
+ */
+export type PartingSlice = 
+/** Nothing moved: not the tree, not an input, not the output. */
+'settled'
+/** An input moved and the output followed. The ordinary parting. */
+ | 'variation'
+/** Every input agreed, the tree held, and the output moved anyway. */
+ | 'flake'
+/** The component tree is a different tree, no input moved, and the output followed. */
+ | 'reshaped'
+/** The component tree moved and the output did not. */
+ | 'refactor'
+/** An input moved and the output did not: the component ignored it. */
+ | 'absorbed'
+/** The output moved and what would explain it was not read. */
+ | 'unread';
+/**
+ * Decide the slice from three independent readings.
+ *
+ * `tree` is `undefined` when neither side carried provenance — not `false`.
+ * A run that never asked what components were there has not found them equal,
+ * and both `refactor` and `flake` are claims about the component tree that such
+ * a run is not entitled to make (ADR-0002).
+ */
+export declare function sliceOf(tree: boolean | undefined, boundaries: readonly PartedBoundary[] | undefined, moved: boolean): PartingSlice;
+/**
+ * Whether the two component trees are the same tree.
+ *
+ * The signature is the owner chain plus the wiring at each node that carries
+ * one, in document order — the shape `wiringOf` already records, which is what
+ * makes this a reading of the fiber rather than of the markup it produced. A
+ * renamed component, an added `memo`, a hook inserted, a `key` changed and a
+ * subtree moved all land here; a repainted pixel does not.
+ *
+ * `undefined` when neither side carried provenance at any node. A page read
+ * without a framework adapter has no component tree to compare, which is a
+ * different answer from two trees that matched.
+ */
+export declare function sameTree(baseline: SemanticNode, candidate: SemanticNode): boolean | undefined;
+//# sourceMappingURL=slice.d.ts.map

package/dist/compare/slice.js

@@ -0,0 +1,79 @@
+/**
+ * Decide the slice from three independent readings.
+ *
+ * `tree` is `undefined` when neither side carried provenance — not `false`.
+ * A run that never asked what components were there has not found them equal,
+ * and both `refactor` and `flake` are claims about the component tree that such
+ * a run is not entitled to make (ADR-0002).
+ */
+export function sliceOf(tree, boundaries, moved) {
+    // Nothing was read, so nothing may be alleged. `flake` in particular is an
+    // accusation, and it is the one this project must never make on silence.
+    if (boundaries === undefined)
+        return moved ? 'unread' : 'settled';
+    const inputs = boundaries.some((boundary) => boundary.inputs.length > 0);
+    if (!moved) {
+        if (tree === false)
+            return 'refactor';
+        return inputs ? 'absorbed' : 'settled';
+    }
+    if (inputs)
+        return 'variation';
+    if (tree === false)
+        return 'reshaped';
+    // `flake` is the accusation, and it rests on the component tree having held.
+    // A run that read holdings but no provenance never established that, so it
+    // gets the rung that says so rather than the one that blames the page.
+    if (tree === undefined)
+        return 'unread';
+    return 'flake';
+}
+/**
+ * Whether the two component trees are the same tree.
+ *
+ * The signature is the owner chain plus the wiring at each node that carries
+ * one, in document order — the shape `wiringOf` already records, which is what
+ * makes this a reading of the fiber rather than of the markup it produced. A
+ * renamed component, an added `memo`, a hook inserted, a `key` changed and a
+ * subtree moved all land here; a repainted pixel does not.
+ *
+ * `undefined` when neither side carried provenance at any node. A page read
+ * without a framework adapter has no component tree to compare, which is a
+ * different answer from two trees that matched.
+ */
+export function sameTree(baseline, candidate) {
+    const left = signature(baseline, []);
+    const right = signature(candidate, []);
+    if (left.length === 0 && right.length === 0)
+        return undefined;
+    if (left.length !== right.length)
+        return false;
+    return left.every((entry, index) => entry === right[index]);
+}
+function signature(node, out) {
+    const owners = node.provenance?.owners;
+    if (owners !== undefined && owners.length > 0) {
+        out.push(`${owners.map((owner) => owner.name).join('>')}|${wiringKey(node.wiring)}`);
+    }
+    for (const child of node.children)
+        signature(child, out);
+    return out;
+}
+/**
+ * Wiring as one comparable string.
+ *
+ * Field order is fixed here rather than taken from `Object.keys`, so that a
+ * wiring gaining a field it did not have changes the key for a reason a reader
+ * can name, and never because the two objects were built in a different order.
+ */
+function wiringKey(wiring) {
+    if (wiring === undefined)
+        return '';
+    return [
+        wiring.hooks?.join(',') ?? '',
+        wiring.wrappers?.join(',') ?? '',
+        wiring.contexts?.join(',') ?? '',
+        wiring.key ?? '',
+    ].join(';');
+}
+//# sourceMappingURL=slice.js.map

package/dist/compare/slice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slice.js","sourceRoot":"","sources":["../../src/compare/slice.ts"],"names":[],"mappings":"AAqDA;;;;;;;GAOG;AACH,MAAM,UAAU,OAAO,CACrB,IAAyB,EACzB,UAAiD,EACjD,KAAc;IAEd,2EAA2E;IAC3E,yEAAyE;IACzE,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;IAElE,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAEzE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,IAAI,IAAI,KAAK,KAAK;YAAE,OAAO,UAAU,CAAC;QACtC,OAAO,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;IACzC,CAAC;IAED,IAAI,MAAM;QAAE,OAAO,WAAW,CAAC;IAC/B,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,UAAU,CAAC;IACtC,6EAA6E;IAC7E,2EAA2E;IAC3E,uEAAuE;IACvE,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IACxC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,QAAQ,CAAC,QAAsB,EAAE,SAAuB;IACtE,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACrC,MAAM,KAAK,GAAG,SAAS,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IACvC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC9D,IAAI,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC/C,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,SAAS,CAAC,IAAkB,EAAE,GAAa;IAClD,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC;IACvC,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9C,GAAG,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACvF,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ;QAAE,SAAS,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACzD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;GAMG;AACH,SAAS,SAAS,CAAC,MAA0B;IAC3C,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACpC,OAAO;QACL,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE;QAC7B,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE;QAChC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE;QAChC,MAAM,CAAC,GAAG,IAAI,EAAE;KACjB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC","sourcesContent":["import type { SemanticNode } from '../format/snapshot.js';\nimport type { Wiring } from '../format/wiring.js';\nimport type { PartedBoundary } from './parting.js';\n\n/**\n * What kind of parting this is, before anything about which one.\n *\n * The rungs in `parting.ts` answer *which input moved*. This answers the\n * question asked first and answered least: **is this worth looking at at all.**\n * Three facts are read independently — did the component tree move, did any\n * input move, did the output move — and the eight combinations collapse to\n * seven sentences, five of which are a triage decision on their own:\n *\n * | component tree | inputs | output | slice |\n * |---|---|---|---|\n * | same | same | **moved** | `flake` |\n * | any | **moved** | **moved** | `variation` |\n * | **moved** | same | **moved** | `reshaped` |\n * | **moved** | any | same | `refactor` |\n * | same | **moved** | same | `absorbed` |\n * | same | same | same | `settled` |\n * | unread | — | **moved** | `unread` |\n *\n * `reshaped` is the row that used to be missing. It was answered `variation`,\n * whose sentence says an input moved — and the whole point of this table is\n * that in that row no input did. Two readings whose component trees are not the\n * same tree, reached from inputs that all agreed, is a component that chose a\n * different shape: a branch taken differently between two arms, or a rewrite\n * between two revisions. Either way the tree is the finding and the rungs below\n * have nothing to add, because there is no moved input for them to name.\n *\n * `refactor` is the one that pays for the other six. A component tree that\n * moved while the page did not is the receipt a refactor never gets: the\n * screenshots match, which is what a pixel differ says and all it says, and\n * *the components underneath were rewritten*, which is the fact somebody wanted\n * confirmed before merging.\n */\nexport type PartingSlice =\n  /** Nothing moved: not the tree, not an input, not the output. */\n  | 'settled'\n  /** An input moved and the output followed. The ordinary parting. */\n  | 'variation'\n  /** Every input agreed, the tree held, and the output moved anyway. */\n  | 'flake'\n  /** The component tree is a different tree, no input moved, and the output followed. */\n  | 'reshaped'\n  /** The component tree moved and the output did not. */\n  | 'refactor'\n  /** An input moved and the output did not: the component ignored it. */\n  | 'absorbed'\n  /** The output moved and what would explain it was not read. */\n  | 'unread';\n\n/**\n * Decide the slice from three independent readings.\n *\n * `tree` is `undefined` when neither side carried provenance — not `false`.\n * A run that never asked what components were there has not found them equal,\n * and both `refactor` and `flake` are claims about the component tree that such\n * a run is not entitled to make (ADR-0002).\n */\nexport function sliceOf(\n  tree: boolean | undefined,\n  boundaries: readonly PartedBoundary[] | undefined,\n  moved: boolean,\n): PartingSlice {\n  // Nothing was read, so nothing may be alleged. `flake` in particular is an\n  // accusation, and it is the one this project must never make on silence.\n  if (boundaries === undefined) return moved ? 'unread' : 'settled';\n\n  const inputs = boundaries.some((boundary) => boundary.inputs.length > 0);\n\n  if (!moved) {\n    if (tree === false) return 'refactor';\n    return inputs ? 'absorbed' : 'settled';\n  }\n\n  if (inputs) return 'variation';\n  if (tree === false) return 'reshaped';\n  // `flake` is the accusation, and it rests on the component tree having held.\n  // A run that read holdings but no provenance never established that, so it\n  // gets the rung that says so rather than the one that blames the page.\n  if (tree === undefined) return 'unread';\n  return 'flake';\n}\n\n/**\n * Whether the two component trees are the same tree.\n *\n * The signature is the owner chain plus the wiring at each node that carries\n * one, in document order — the shape `wiringOf` already records, which is what\n * makes this a reading of the fiber rather than of the markup it produced. A\n * renamed component, an added `memo`, a hook inserted, a `key` changed and a\n * subtree moved all land here; a repainted pixel does not.\n *\n * `undefined` when neither side carried provenance at any node. A page read\n * without a framework adapter has no component tree to compare, which is a\n * different answer from two trees that matched.\n */\nexport function sameTree(baseline: SemanticNode, candidate: SemanticNode): boolean | undefined {\n  const left = signature(baseline, []);\n  const right = signature(candidate, []);\n  if (left.length === 0 && right.length === 0) return undefined;\n  if (left.length !== right.length) return false;\n  return left.every((entry, index) => entry === right[index]);\n}\n\nfunction signature(node: SemanticNode, out: string[]): string[] {\n  const owners = node.provenance?.owners;\n  if (owners !== undefined && owners.length > 0) {\n    out.push(`${owners.map((owner) => owner.name).join('>')}|${wiringKey(node.wiring)}`);\n  }\n  for (const child of node.children) signature(child, out);\n  return out;\n}\n\n/**\n * Wiring as one comparable string.\n *\n * Field order is fixed here rather than taken from `Object.keys`, so that a\n * wiring gaining a field it did not have changes the key for a reason a reader\n * can name, and never because the two objects were built in a different order.\n */\nfunction wiringKey(wiring: Wiring | undefined): string {\n  if (wiring === undefined) return '';\n  return [\n    wiring.hooks?.join(',') ?? '',\n    wiring.wrappers?.join(',') ?? '',\n    wiring.contexts?.join(',') ?? '',\n    wiring.key ?? '',\n  ].join(';');\n}\n"]}