@variance-authority/core 0.1.0

package/dist/compare/diff/match.js

@@ -0,0 +1,167 @@
+/**
+ * Identity key, most specific first.
+ *
+ * Ordering matters: a structural alias is the strongest signal available because
+ * it survives reordering and is stable across renders (that being the point of
+ * ADR-0003's aliasing). Role plus accessible name is next, since it is what a
+ * user of assistive technology would call the node. Owner chain plus tag comes
+ * third — two `<span>`s rendered by the same component are interchangeable in a
+ * way two spans from different components are not. Bare tag is the last resort.
+ */
+function matchKey(node) {
+    if (node.alias !== undefined)
+        return `alias:${node.alias}`;
+    if (node.role !== undefined && node.name !== undefined) {
+        return `aria:${node.role}|${node.name}`;
+    }
+    if (node.provenance && node.provenance.owners.length > 0) {
+        const chain = node.provenance.owners.map((owner) => owner.name).join('>');
+        return `own:${chain}:${node.tag}`;
+    }
+    return `tag:${node.tag}`;
+}
+const SIGNATURES = new WeakMap();
+/**
+ * What this subtree *says*, ignoring where it sits.
+ *
+ * Deliberately narrow: tag, the three ARIA fields, text, and the same of every
+ * descendant. Style is excluded, because a node that was restyled and a node
+ * that was replaced must not be confused — pairing by appearance would let a
+ * recolour look like a substitution. Position is excluded because that is the
+ * whole point.
+ *
+ * Cached per node: the recursion is O(subtree) and a parent computing it for
+ * every child at every level would be quadratic in depth.
+ */
+function contentSignature(node) {
+    const cached = SIGNATURES.get(node);
+    if (cached !== undefined)
+        return cached;
+    const own = [node.tag, node.role ?? '', node.name ?? '', node.description ?? '', node.text ?? ''];
+    const signature = `${own.join('
')}(${node.children.map(contentSignature).join('')})`;
+    SIGNATURES.set(node, signature);
+    return signature;
+}
+/**
+ * Content pass key. Scoped by identity so the refinement never crosses a
+ * boundary the identity key drew — two components rendering the same string are
+ * not the same node however identical their subtrees.
+ */
+function contentKey(node) {
+    return `${matchKey(node)}\u0000${contentSignature(node)}`;
+}
+export function matchTrees(baseline, candidate) {
+    const pairs = new Map();
+    const added = [];
+    const removed = [];
+    const moved = new Set();
+    pairs.set(baseline, candidate);
+    matchChildren(baseline, candidate);
+    return { pairs, added, removed, moved };
+    function matchChildren(before, after) {
+        const byContent = index(before.children, contentKey);
+        const byIdentity = index(before.children, matchKey);
+        const taken = new Set();
+        /** Baseline index each candidate paired with, indexed by candidate position. */
+        const partner = Array.from({ length: after.children.length }, () => undefined);
+        // Pass 1 — identical content. A node that says the same thing is the same
+        // node, wherever it moved to.
+        after.children.forEach((child, afterIndex) => {
+            const claimed = claim(byContent.get(contentKey(child)), taken);
+            if (claimed !== undefined)
+                partner[afterIndex] = claimed;
+        });
+        // Pass 2 — whatever is left, by identity and then by order of appearance.
+        // This is what turns `[a, b, c]` → `[a, x, c]` into one changed string
+        // rather than one removal and one addition: `b` and `x` are the only two
+        // nodes their bucket has left, so they are each other's counterpart.
+        after.children.forEach((child, afterIndex) => {
+            if (partner[afterIndex] !== undefined)
+                return;
+            const claimed = claim(byIdentity.get(matchKey(child)), taken);
+            if (claimed !== undefined)
+                partner[afterIndex] = claimed;
+        });
+        const sequence = [];
+        after.children.forEach((child, afterIndex) => {
+            const beforeIndex = partner[afterIndex];
+            if (beforeIndex === undefined) {
+                // Unmatched candidates are recorded whole. Their descendants are not
+                // walked: a new subtree is one change to review, not one per node in it.
+                added.push(child);
+                return;
+            }
+            sequence.push(beforeIndex);
+            const counterpart = before.children[beforeIndex];
+            pairs.set(counterpart, child);
+            matchChildren(counterpart, child);
+        });
+        for (const beforeIndex of outOfOrder(sequence)) {
+            moved.add(before.children[beforeIndex]);
+        }
+        before.children.forEach((child, index) => {
+            if (!taken.has(index))
+                removed.push(child);
+        });
+    }
+}
+function index(children, key) {
+    const buckets = new Map();
+    children.forEach((child, position) => {
+        const bucket = buckets.get(key(child));
+        if (bucket)
+            bucket.push(position);
+        else
+            buckets.set(key(child), [position]);
+    });
+    return buckets;
+}
+/** Lowest unclaimed index in a bucket, marking it claimed. */
+function claim(bucket, taken) {
+    const free = bucket?.find((position) => !taken.has(position));
+    if (free !== undefined)
+        taken.add(free);
+    return free;
+}
+/**
+ * Indices that must have moved for `sequence` to be in this order.
+ *
+ * The complement of a longest increasing subsequence: everything in that
+ * subsequence kept its relative order and needs no explanation, and what is left
+ * is the smallest set of movements that produces the observed sequence. A
+ * prepend leaves the sequence increasing and therefore reports nothing moved,
+ * which is the answer `prepend/list` asks for — one added node, and not three
+ * displaced siblings alongside it.
+ */
+function outOfOrder(sequence) {
+    if (sequence.length < 2)
+        return [];
+    // Patience sorting. `tails[k]` is the smallest tail of an increasing run of
+    // length k+1; `previous` reconstructs which elements formed the longest one.
+    const tails = [];
+    const tailIndex = [];
+    const previous = Array.from({ length: sequence.length }, () => undefined);
+    for (let position = 0; position < sequence.length; position += 1) {
+        const value = sequence[position];
+        let low = 0;
+        let high = tails.length;
+        while (low < high) {
+            const mid = (low + high) >> 1;
+            if (tails[mid] < value)
+                low = mid + 1;
+            else
+                high = mid;
+        }
+        tails[low] = value;
+        tailIndex[low] = position;
+        previous[position] = low > 0 ? tailIndex[low - 1] : undefined;
+    }
+    const kept = new Set();
+    let cursor = tailIndex[tails.length - 1];
+    while (cursor !== undefined) {
+        kept.add(cursor);
+        cursor = previous[cursor];
+    }
+    return sequence.filter((_, position) => !kept.has(position));
+}
+//# sourceMappingURL=match.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"match.js","sourceRoot":"","sources":["../../../src/compare/diff/match.ts"],"names":[],"mappings":"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","sourcesContent":["import type { SemanticNode } from '../../format/snapshot.js';\n\n/**\n * Node correspondence.\n *\n * Paths are positional, so inserting one sibling renumbers everything after it.\n * Diffing by path alone would report a single insertion as \"every following node\n * changed\" — the classic snapshot-test failure that trains people to stop\n * reading diffs. Matching therefore happens by identity first, content second,\n * and position last.\n *\n * The middle pass is the one that took three attempts to find. Identity keys\n * collapse whenever a node has no alias, no accessible name and no provenance —\n * five bare `<li>`s bucket together as `tag:li` — and pairing inside that bucket\n * by position turns a rotation into \"every item's text changed\". The corpus case\n * `reorder/list` was written to catch exactly that and could not: its assertions\n * were the verdict and the root count, and both are correct while the report is\n * useless. Scoring the *band* is what exposed it — five `text-changed` deltas\n * band as `content` where a rotation bands as `geometry`.\n */\n\nexport interface Matching {\n  /** Baseline node → candidate node. */\n  readonly pairs: ReadonlyMap<SemanticNode, SemanticNode>;\n  readonly added: readonly SemanticNode[];\n  readonly removed: readonly SemanticNode[];\n  /**\n   * Pairs whose position among their siblings changed *relative to each other*.\n   *\n   * Not \"whose index differs\". Prepending one item shifts every index after it\n   * without reordering anything, and reporting three moves for one insertion is\n   * the same fatigue that positional diffing produces. The moved set is the\n   * complement of the longest run that stayed in order, which is the smallest\n   * set of nodes whose movement explains the new sequence.\n   */\n  readonly moved: ReadonlySet<SemanticNode>;\n}\n\n/**\n * Identity key, most specific first.\n *\n * Ordering matters: a structural alias is the strongest signal available because\n * it survives reordering and is stable across renders (that being the point of\n * ADR-0003's aliasing). Role plus accessible name is next, since it is what a\n * user of assistive technology would call the node. Owner chain plus tag comes\n * third — two `<span>`s rendered by the same component are interchangeable in a\n * way two spans from different components are not. Bare tag is the last resort.\n */\nfunction matchKey(node: SemanticNode): string {\n  if (node.alias !== undefined) return `alias:${node.alias}`;\n  if (node.role !== undefined && node.name !== undefined) {\n    return `aria:${node.role}|${node.name}`;\n  }\n  if (node.provenance && node.provenance.owners.length > 0) {\n    const chain = node.provenance.owners.map((owner) => owner.name).join('>');\n    return `own:${chain}:${node.tag}`;\n  }\n  return `tag:${node.tag}`;\n}\n\nconst SIGNATURES = new WeakMap<SemanticNode, string>();\n\n/**\n * What this subtree *says*, ignoring where it sits.\n *\n * Deliberately narrow: tag, the three ARIA fields, text, and the same of every\n * descendant. Style is excluded, because a node that was restyled and a node\n * that was replaced must not be confused — pairing by appearance would let a\n * recolour look like a substitution. Position is excluded because that is the\n * whole point.\n *\n * Cached per node: the recursion is O(subtree) and a parent computing it for\n * every child at every level would be quadratic in depth.\n */\nfunction contentSignature(node: SemanticNode): string {\n  const cached = SIGNATURES.get(node);\n  if (cached !== undefined) return cached;\n\n  const own = [node.tag, node.role ?? '', node.name ?? '', node.description ?? '', node.text ?? ''];\n  const signature = `${own.join('\u0001')}(${node.children.map(contentSignature).join('\u0002')})`;\n\n  SIGNATURES.set(node, signature);\n  return signature;\n}\n\n/**\n * Content pass key. Scoped by identity so the refinement never crosses a\n * boundary the identity key drew — two components rendering the same string are\n * not the same node however identical their subtrees.\n */\nfunction contentKey(node: SemanticNode): string {\n  return `${matchKey(node)}\\u0000${contentSignature(node)}`;\n}\n\nexport function matchTrees(baseline: SemanticNode, candidate: SemanticNode): Matching {\n  const pairs = new Map<SemanticNode, SemanticNode>();\n  const added: SemanticNode[] = [];\n  const removed: SemanticNode[] = [];\n  const moved = new Set<SemanticNode>();\n\n  pairs.set(baseline, candidate);\n  matchChildren(baseline, candidate);\n\n  return { pairs, added, removed, moved };\n\n  function matchChildren(before: SemanticNode, after: SemanticNode): void {\n    const byContent = index(before.children, contentKey);\n    const byIdentity = index(before.children, matchKey);\n    const taken = new Set<number>();\n\n    /** Baseline index each candidate paired with, indexed by candidate position. */\n    const partner: (number | undefined)[] = Array.from(\n      { length: after.children.length },\n      () => undefined,\n    );\n\n    // Pass 1 — identical content. A node that says the same thing is the same\n    // node, wherever it moved to.\n    after.children.forEach((child, afterIndex) => {\n      const claimed = claim(byContent.get(contentKey(child)), taken);\n      if (claimed !== undefined) partner[afterIndex] = claimed;\n    });\n\n    // Pass 2 — whatever is left, by identity and then by order of appearance.\n    // This is what turns `[a, b, c]` → `[a, x, c]` into one changed string\n    // rather than one removal and one addition: `b` and `x` are the only two\n    // nodes their bucket has left, so they are each other's counterpart.\n    after.children.forEach((child, afterIndex) => {\n      if (partner[afterIndex] !== undefined) return;\n      const claimed = claim(byIdentity.get(matchKey(child)), taken);\n      if (claimed !== undefined) partner[afterIndex] = claimed;\n    });\n\n    const sequence: number[] = [];\n    after.children.forEach((child, afterIndex) => {\n      const beforeIndex = partner[afterIndex];\n      if (beforeIndex === undefined) {\n        // Unmatched candidates are recorded whole. Their descendants are not\n        // walked: a new subtree is one change to review, not one per node in it.\n        added.push(child);\n        return;\n      }\n\n      sequence.push(beforeIndex);\n      const counterpart = before.children[beforeIndex]!;\n      pairs.set(counterpart, child);\n      matchChildren(counterpart, child);\n    });\n\n    for (const beforeIndex of outOfOrder(sequence)) {\n      moved.add(before.children[beforeIndex]!);\n    }\n\n    before.children.forEach((child, index) => {\n      if (!taken.has(index)) removed.push(child);\n    });\n  }\n}\n\nfunction index(\n  children: readonly SemanticNode[],\n  key: (node: SemanticNode) => string,\n): Map<string, number[]> {\n  const buckets = new Map<string, number[]>();\n\n  children.forEach((child, position) => {\n    const bucket = buckets.get(key(child));\n    if (bucket) bucket.push(position);\n    else buckets.set(key(child), [position]);\n  });\n\n  return buckets;\n}\n\n/** Lowest unclaimed index in a bucket, marking it claimed. */\nfunction claim(bucket: number[] | undefined, taken: Set<number>): number | undefined {\n  const free = bucket?.find((position) => !taken.has(position));\n  if (free !== undefined) taken.add(free);\n  return free;\n}\n\n/**\n * Indices that must have moved for `sequence` to be in this order.\n *\n * The complement of a longest increasing subsequence: everything in that\n * subsequence kept its relative order and needs no explanation, and what is left\n * is the smallest set of movements that produces the observed sequence. A\n * prepend leaves the sequence increasing and therefore reports nothing moved,\n * which is the answer `prepend/list` asks for — one added node, and not three\n * displaced siblings alongside it.\n */\nfunction outOfOrder(sequence: readonly number[]): readonly number[] {\n  if (sequence.length < 2) return [];\n\n  // Patience sorting. `tails[k]` is the smallest tail of an increasing run of\n  // length k+1; `previous` reconstructs which elements formed the longest one.\n  const tails: number[] = [];\n  const tailIndex: number[] = [];\n  const previous: (number | undefined)[] = Array.from(\n    { length: sequence.length },\n    () => undefined,\n  );\n\n  for (let position = 0; position < sequence.length; position += 1) {\n    const value = sequence[position]!;\n\n    let low = 0;\n    let high = tails.length;\n    while (low < high) {\n      const mid = (low + high) >> 1;\n      if (tails[mid]! < value) low = mid + 1;\n      else high = mid;\n    }\n\n    tails[low] = value;\n    tailIndex[low] = position;\n    previous[position] = low > 0 ? tailIndex[low - 1] : undefined;\n  }\n\n  const kept = new Set<number>();\n  let cursor: number | undefined = tailIndex[tails.length - 1];\n  while (cursor !== undefined) {\n    kept.add(cursor);\n    cursor = previous[cursor];\n  }\n\n  return sequence.filter((_, position) => !kept.has(position));\n}\n"]}

package/dist/compare/explain.d.ts

@@ -0,0 +1,23 @@
+import type { Parting } from './parting.js';
+/**
+ * A parting, spoken.
+ *
+ * The rung a run reached is only worth what a reader takes from it, and the
+ * three sentences below are three different products:
+ *
+ * ```text
+ * a <div> rendered <p> on one side and <span> on the other
+ * Summary was handed a different `total`
+ * Cart chose differently — useState #2 moved, and Summary's `total` follows
+ * ```
+ *
+ * The first is a diff. The second localises. Only the third names a cause, and
+ * it is the only one somebody can act on without opening the component and
+ * guessing. So the shape here is an **origin and its manifestations**, not a
+ * flat list: an origin line, then the boundaries and deltas downstream of it,
+ * indented. A collateral boundary with no origin above it gets a line of its own
+ * — that is a parting this run could not trace further, and hiding it under
+ * something else would overstate what was found.
+ */
+export declare function explainParting(parting: Parting): readonly string[];
+//# sourceMappingURL=explain.d.ts.map

package/dist/compare/explain.js

@@ -0,0 +1,190 @@
+/**
+ * A parting, spoken.
+ *
+ * The rung a run reached is only worth what a reader takes from it, and the
+ * three sentences below are three different products:
+ *
+ * ```text
+ * a <div> rendered <p> on one side and <span> on the other
+ * Summary was handed a different `total`
+ * Cart chose differently — useState #2 moved, and Summary's `total` follows
+ * ```
+ *
+ * The first is a diff. The second localises. Only the third names a cause, and
+ * it is the only one somebody can act on without opening the component and
+ * guessing. So the shape here is an **origin and its manifestations**, not a
+ * flat list: an origin line, then the boundaries and deltas downstream of it,
+ * indented. A collateral boundary with no origin above it gets a line of its own
+ * — that is a parting this run could not trace further, and hiding it under
+ * something else would overstate what was found.
+ */
+export function explainParting(parting) {
+    const boundaries = parting.boundaries;
+    const headline = slice(parting.slice);
+    if (boundaries === undefined) {
+        return [headline, '  no framework boundary was read, so nothing can be said about why'];
+    }
+    if (boundaries.length === 0) {
+        return [headline, '  every boundary read held its inputs and its output'];
+    }
+    const origins = parting.origins ?? [];
+    const claimed = new Set();
+    const lines = [headline];
+    for (const origin of origins) {
+        if (claimed.has(origin))
+            continue;
+        claimed.add(origin);
+        const downstream = boundaries.filter((other) => !claimed.has(other) && under(origin.path, other.path));
+        for (const other of downstream)
+            claimed.add(other);
+        lines.push(sentence(origin));
+        lines.push(...deltaLines(origin, boundaries));
+        // The avalanche. One input at a fork can put a boundary on every component
+        // beneath it, and enumerating them buries the one line worth reading under
+        // its own consequences. Past the cap the fan-out is stated as a size —
+        // pointing at the fork is the finding, and the boundary list is still there
+        // for a caller that wants to walk it.
+        if (downstream.length > FANOUT) {
+            const deltas = downstream.reduce((total, other) => total + other.deltas, 0);
+            lines.push(`  manifests across ${downstream.length} boundaries below it` +
+                (deltas > 0 ? `, ${deltas} delta${deltas === 1 ? '' : 's'} in all` : ''));
+        }
+        else {
+            for (const other of downstream) {
+                lines.push(`  manifests as ${sentence(other)}`);
+                lines.push(...deltaLines(other, boundaries).map((line) => `  ${line}`));
+            }
+        }
+    }
+    for (const rest of boundaries) {
+        if (claimed.has(rest))
+            continue;
+        lines.push(sentence(rest));
+        lines.push(...deltaLines(rest, boundaries));
+    }
+    return lines;
+}
+function sentence(boundary) {
+    const { component, inputs } = boundary;
+    switch (boundary.rung) {
+        case 'stateful':
+            return `${component} chose differently — ${list(inputs.filter(isHook))} moved`;
+        case 'external':
+            return `${component} read a different external store — ${list(inputs.filter(isHook))} moved`;
+        case 'provided':
+            return `${component} was given a different ${list(inputs.filter((i) => i.kind === 'context'))}`;
+        case 'handed':
+            return `${component} was handed a different ${list(inputs.filter((i) => i.kind === 'prop'))}`;
+        // Phrased at the ancestor rather than at the component, because that is
+        // where the reader has to go. `Price` did nothing; something it is standing
+        // inside declared a value it never declares for itself.
+        case 'inherited':
+            return (`${component} inherited a different ` +
+                `${list(inputs.filter((i) => i.kind === 'inherited'))} — an ancestor declared it`);
+        case 'undetermined':
+            return `${component} rendered differently from inputs that all agreed — nondeterministic`;
+        case 'unread':
+            return `${component} rendered differently, and what it holds could not be read`;
+        case 'unpaired':
+            return `${component} is present on one side only`;
+    }
+}
+/** What `holdingOf` writes for a context React could not name. */
+const ANONYMOUS = '(anonymous)';
+function isHook(input) {
+    return input.kind === 'hook';
+}
+/**
+ * Name the moved inputs, hooks by call position.
+ *
+ * `useState #2` rather than `useState` because a component with four `useState`
+ * calls is the ordinary case, and a sentence naming the hook without saying
+ * which one sends the reader back to counting — the work this module exists to
+ * have already done.
+ */
+function list(inputs) {
+    const named = inputs.map((input) => {
+        if (input.index !== undefined)
+            return `${input.name} #${input.index}`;
+        // A `createContext` call with no `displayName` is the common case, and
+        // "a different `(anonymous)`" names the gap in React's metadata rather than
+        // the thing that moved.
+        return input.name === ANONYMOUS ? 'context value' : `\`${input.name}\``;
+    });
+    if (named.length === 0)
+        return 'input';
+    if (named.length === 1)
+        return named[0];
+    return `${named.slice(0, -1).join(', ')} and ${named[named.length - 1]}`;
+}
+/**
+ * The deltas at a boundary, and the one case worth saying nothing about.
+ *
+ * A boundary owning no delta is only *quiet* if nothing under it owns one
+ * either. Otherwise the deltas are real and belong to a nested boundary, whose
+ * own line already reports them — and "and rendered the same anyway" directly
+ * beneath "chose differently" reads as a contradiction rather than as the
+ * ownership statement it is.
+ */
+function deltaLines(boundary, all) {
+    if (boundary.deltas === 0) {
+        const moved = all.some((other) => under(boundary.path, other.path) && other.deltas > 0);
+        return moved ? [] : ['  and rendered the same anyway'];
+    }
+    const bands = boundary.bands.join(', ');
+    const count = `${boundary.deltas} delta${boundary.deltas === 1 ? '' : 's'} here (${bands})`;
+    return [`  ${count}${named(boundary.moved)}`];
+}
+const SHOWN = 4;
+/** Above this many boundaries under one origin, the fan-out is the finding. */
+const FANOUT = 3;
+/**
+ * The triage line, first, before anything about which input moved.
+ *
+ * Deliberately a whole sentence rather than the bare word: `refactor` alone
+ * reads as a label somebody applied, and the clause is the evidence for it.
+ */
+function slice(kind) {
+    switch (kind) {
+        case 'settled':
+            return 'settled — the component tree, its inputs and its output all held';
+        case 'variation':
+            return 'variation — an input moved and the page followed';
+        case 'flake':
+            return 'flake — every input agreed, the component tree held, and the page moved anyway';
+        case 'reshaped':
+            return 'reshaped — the component tree is a different tree and the page followed';
+        case 'refactor':
+            return 'refactor — the component tree moved and the page did not';
+        case 'absorbed':
+            return 'absorbed — an input moved and the page did not';
+        case 'unread':
+            return 'unread — the page moved and what would explain it was not read';
+    }
+}
+/**
+ * The properties that moved, truncated where a list stops being a sentence.
+ *
+ * Four because `padding` expands to four longhands and a reader who has seen
+ * the first learns nothing from the rest. What was dropped is counted rather
+ * than elided — a list that quietly ends reads as the whole list.
+ */
+function named(moved) {
+    if (moved === undefined || moved.length === 0)
+        return '';
+    if (moved.length <= SHOWN)
+        return ` — ${moved.join(', ')}`;
+    return ` — ${moved.slice(0, SHOWN).join(', ')} and ${moved.length - SHOWN} more`;
+}
+/**
+ * Whether one path encloses another, strictly.
+ *
+ * Segment-aware: `0/1` must not swallow `0/10`, and a plain `startsWith` would
+ * make every tenth sibling collateral of its second.
+ */
+function under(ancestor, path) {
+    if (ancestor === path)
+        return false;
+    return ancestor === '' || path.startsWith(`${ancestor}/`);
+}
+//# sourceMappingURL=explain.js.map

package/dist/compare/explain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.js","sourceRoot":"","sources":["../../src/compare/explain.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Parting, PartedBoundary, MovedInput } from './parting.js';\nimport type { PartingSlice } from './slice.js';\n\n/**\n * A parting, spoken.\n *\n * The rung a run reached is only worth what a reader takes from it, and the\n * three sentences below are three different products:\n *\n * ```text\n * a <div> rendered <p> on one side and <span> on the other\n * Summary was handed a different `total`\n * Cart chose differently — useState #2 moved, and Summary's `total` follows\n * ```\n *\n * The first is a diff. The second localises. Only the third names a cause, and\n * it is the only one somebody can act on without opening the component and\n * guessing. So the shape here is an **origin and its manifestations**, not a\n * flat list: an origin line, then the boundaries and deltas downstream of it,\n * indented. A collateral boundary with no origin above it gets a line of its own\n * — that is a parting this run could not trace further, and hiding it under\n * something else would overstate what was found.\n */\nexport function explainParting(parting: Parting): readonly string[] {\n  const boundaries = parting.boundaries;\n  const headline = slice(parting.slice);\n\n  if (boundaries === undefined) {\n    return [headline, '  no framework boundary was read, so nothing can be said about why'];\n  }\n  if (boundaries.length === 0) {\n    return [headline, '  every boundary read held its inputs and its output'];\n  }\n\n  const origins = parting.origins ?? [];\n  const claimed = new Set<PartedBoundary>();\n  const lines: string[] = [headline];\n\n  for (const origin of origins) {\n    if (claimed.has(origin)) continue;\n    claimed.add(origin);\n    const downstream = boundaries.filter(\n      (other) => !claimed.has(other) && under(origin.path, other.path),\n    );\n    for (const other of downstream) claimed.add(other);\n\n    lines.push(sentence(origin));\n    lines.push(...deltaLines(origin, boundaries));\n\n    // The avalanche. One input at a fork can put a boundary on every component\n    // beneath it, and enumerating them buries the one line worth reading under\n    // its own consequences. Past the cap the fan-out is stated as a size —\n    // pointing at the fork is the finding, and the boundary list is still there\n    // for a caller that wants to walk it.\n    if (downstream.length > FANOUT) {\n      const deltas = downstream.reduce((total, other) => total + other.deltas, 0);\n      lines.push(\n        `  manifests across ${downstream.length} boundaries below it` +\n          (deltas > 0 ? `, ${deltas} delta${deltas === 1 ? '' : 's'} in all` : ''),\n      );\n    } else {\n      for (const other of downstream) {\n        lines.push(`  manifests as ${sentence(other)}`);\n        lines.push(...deltaLines(other, boundaries).map((line) => `  ${line}`));\n      }\n    }\n  }\n\n  for (const rest of boundaries) {\n    if (claimed.has(rest)) continue;\n    lines.push(sentence(rest));\n    lines.push(...deltaLines(rest, boundaries));\n  }\n\n  return lines;\n}\n\nfunction sentence(boundary: PartedBoundary): string {\n  const { component, inputs } = boundary;\n\n  switch (boundary.rung) {\n    case 'stateful':\n      return `${component} chose differently — ${list(inputs.filter(isHook))} moved`;\n    case 'external':\n      return `${component} read a different external store — ${list(inputs.filter(isHook))} moved`;\n    case 'provided':\n      return `${component} was given a different ${list(inputs.filter((i) => i.kind === 'context'))}`;\n    case 'handed':\n      return `${component} was handed a different ${list(inputs.filter((i) => i.kind === 'prop'))}`;\n    // Phrased at the ancestor rather than at the component, because that is\n    // where the reader has to go. `Price` did nothing; something it is standing\n    // inside declared a value it never declares for itself.\n    case 'inherited':\n      return (\n        `${component} inherited a different ` +\n        `${list(inputs.filter((i) => i.kind === 'inherited'))} — an ancestor declared it`\n      );\n    case 'undetermined':\n      return `${component} rendered differently from inputs that all agreed — nondeterministic`;\n    case 'unread':\n      return `${component} rendered differently, and what it holds could not be read`;\n    case 'unpaired':\n      return `${component} is present on one side only`;\n  }\n}\n\n/** What `holdingOf` writes for a context React could not name. */\nconst ANONYMOUS = '(anonymous)';\n\nfunction isHook(input: MovedInput): boolean {\n  return input.kind === 'hook';\n}\n\n/**\n * Name the moved inputs, hooks by call position.\n *\n * `useState #2` rather than `useState` because a component with four `useState`\n * calls is the ordinary case, and a sentence naming the hook without saying\n * which one sends the reader back to counting — the work this module exists to\n * have already done.\n */\nfunction list(inputs: readonly MovedInput[]): string {\n  const named = inputs.map((input) => {\n    if (input.index !== undefined) return `${input.name} #${input.index}`;\n    // A `createContext` call with no `displayName` is the common case, and\n    // \"a different `(anonymous)`\" names the gap in React's metadata rather than\n    // the thing that moved.\n    return input.name === ANONYMOUS ? 'context value' : `\\`${input.name}\\``;\n  });\n  if (named.length === 0) return 'input';\n  if (named.length === 1) return named[0] as string;\n  return `${named.slice(0, -1).join(', ')} and ${named[named.length - 1] as string}`;\n}\n\n/**\n * The deltas at a boundary, and the one case worth saying nothing about.\n *\n * A boundary owning no delta is only *quiet* if nothing under it owns one\n * either. Otherwise the deltas are real and belong to a nested boundary, whose\n * own line already reports them — and \"and rendered the same anyway\" directly\n * beneath \"chose differently\" reads as a contradiction rather than as the\n * ownership statement it is.\n */\nfunction deltaLines(\n  boundary: PartedBoundary,\n  all: readonly PartedBoundary[],\n): readonly string[] {\n  if (boundary.deltas === 0) {\n    const moved = all.some((other) => under(boundary.path, other.path) && other.deltas > 0);\n    return moved ? [] : ['  and rendered the same anyway'];\n  }\n  const bands = boundary.bands.join(', ');\n  const count = `${boundary.deltas} delta${boundary.deltas === 1 ? '' : 's'} here (${bands})`;\n  return [`  ${count}${named(boundary.moved)}`];\n}\n\nconst SHOWN = 4;\n\n/** Above this many boundaries under one origin, the fan-out is the finding. */\nconst FANOUT = 3;\n\n/**\n * The triage line, first, before anything about which input moved.\n *\n * Deliberately a whole sentence rather than the bare word: `refactor` alone\n * reads as a label somebody applied, and the clause is the evidence for it.\n */\nfunction slice(kind: PartingSlice): string {\n  switch (kind) {\n    case 'settled':\n      return 'settled — the component tree, its inputs and its output all held';\n    case 'variation':\n      return 'variation — an input moved and the page followed';\n    case 'flake':\n      return 'flake — every input agreed, the component tree held, and the page moved anyway';\n    case 'reshaped':\n      return 'reshaped — the component tree is a different tree and the page followed';\n    case 'refactor':\n      return 'refactor — the component tree moved and the page did not';\n    case 'absorbed':\n      return 'absorbed — an input moved and the page did not';\n    case 'unread':\n      return 'unread — the page moved and what would explain it was not read';\n  }\n}\n\n/**\n * The properties that moved, truncated where a list stops being a sentence.\n *\n * Four because `padding` expands to four longhands and a reader who has seen\n * the first learns nothing from the rest. What was dropped is counted rather\n * than elided — a list that quietly ends reads as the whole list.\n */\nfunction named(moved: readonly string[] | undefined): string {\n  if (moved === undefined || moved.length === 0) return '';\n  if (moved.length <= SHOWN) return ` — ${moved.join(', ')}`;\n  return ` — ${moved.slice(0, SHOWN).join(', ')} and ${moved.length - SHOWN} more`;\n}\n\n/**\n * Whether one path encloses another, strictly.\n *\n * Segment-aware: `0/1` must not swallow `0/10`, and a plain `startsWith` would\n * make every tenth sibling collateral of its second.\n */\nfunction under(ancestor: string, path: string): boolean {\n  if (ancestor === path) return false;\n  return ancestor === '' || path.startsWith(`${ancestor}/`);\n}\n"]}

package/dist/compare/holding-diff.d.ts

@@ -0,0 +1,25 @@
+import type { Holding } from '../format/holding.js';
+import type { MovedInput } from './parting.js';
+/**
+ * What a boundary received, as a framework adapter read it.
+ *
+ * The counterpart to `cascade.ts`: that one reads the input nobody passed, and
+ * this one reads the three that were — props, contexts and hook cells. Split out
+ * because they fail in opposite directions and the difference is the whole
+ * safety property. A cascade reading is either present or the property was
+ * declared; a holding reading can be *absent*, and absent must never settle as
+ * agreement. Everything here that returns `unread` is doing that work.
+ */
+/**
+ * What differs between two readings of one boundary.
+ *
+ * `unread` is returned beside the inputs rather than folded into them because
+ * the two answer different questions. The inputs say what moved; `unread` says
+ * whether "nothing moved" is a reading or a shrug, and only the second caller —
+ * the one about to call a render nondeterministic — needs it.
+ */
+export declare function compareHoldings(left: Holding | undefined, right: Holding | undefined): {
+    inputs: readonly MovedInput[];
+    unread: boolean;
+};
+//# sourceMappingURL=holding-diff.d.ts.map

package/dist/compare/holding-diff.js

@@ -0,0 +1,74 @@
+/**
+ * What a boundary received, as a framework adapter read it.
+ *
+ * The counterpart to `cascade.ts`: that one reads the input nobody passed, and
+ * this one reads the three that were — props, contexts and hook cells. Split out
+ * because they fail in opposite directions and the difference is the whole
+ * safety property. A cascade reading is either present or the property was
+ * declared; a holding reading can be *absent*, and absent must never settle as
+ * agreement. Everything here that returns `unread` is doing that work.
+ */
+/**
+ * What differs between two readings of one boundary.
+ *
+ * `unread` is returned beside the inputs rather than folded into them because
+ * the two answer different questions. The inputs say what moved; `unread` says
+ * whether "nothing moved" is a reading or a shrug, and only the second caller —
+ * the one about to call a render nondeterministic — needs it.
+ */
+export function compareHoldings(left, right) {
+    const inputs = [];
+    let unread = left?.unread !== undefined || right?.unread !== undefined;
+    // Absent props mean `memoizedProps` was not an object, which is a failure to
+    // read rather than a component with no props. Symmetric absence is left alone:
+    // two readings that failed the same way have not disagreed.
+    if ((left?.props === undefined) !== (right?.props === undefined))
+        unread = true;
+    else
+        compareNamed('prop', left?.props, right?.props, inputs);
+    // Contexts are different: absent means `dependencies` was null, and that is a
+    // positive reading — this component subscribes to no context.
+    compareNamed('context', left?.contexts, right?.contexts, inputs);
+    if (left?.cells === undefined || right?.cells === undefined)
+        unread = true;
+    else
+        compareCells(left.cells, right.cells, inputs);
+    return { inputs, unread };
+}
+function compareNamed(kind, left, right, into) {
+    const before = new Map((left ?? []).map((value) => [value.name, value.digest]));
+    const after = new Map((right ?? []).map((value) => [value.name, value.digest]));
+    for (const name of [...new Set([...before.keys(), ...after.keys()])].sort()) {
+        const from = before.get(name);
+        const to = after.get(name);
+        if (from !== to)
+            into.push({ kind, name, from, to });
+    }
+}
+/**
+ * Hook cells, joined on call position.
+ *
+ * On position rather than on name because position is what a hook *is* to React
+ * — the rule the linter enforces — and because a component that ran a different
+ * number of hooks took a different branch before it rendered anything. That case
+ * arrives here as cells present on one side only, which is a reading rather than
+ * a join failure, and one of the loudest available.
+ */
+function compareCells(left, right, into) {
+    const before = new Map(left.map((cell) => [cell.index, cell]));
+    const after = new Map(right.map((cell) => [cell.index, cell]));
+    for (const index of [...new Set([...before.keys(), ...after.keys()])].sort((a, b) => a - b)) {
+        const from = before.get(index);
+        const to = after.get(index);
+        if (from?.digest === to?.digest && from?.hook === to?.hook)
+            continue;
+        into.push({
+            kind: 'hook',
+            name: to?.hook ?? from?.hook ?? '(unknown)',
+            index,
+            from: from?.digest,
+            to: to?.digest,
+        });
+    }
+}
+//# sourceMappingURL=holding-diff.js.map

package/dist/compare/holding-diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"holding-diff.js","sourceRoot":"","sources":["../../src/compare/holding-diff.ts"],"names":[],"mappings":"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","sourcesContent":["import type { HeldCell, HeldValue, Holding } from '../format/holding.js';\nimport type { MovedInput } from './parting.js';\n\n/**\n * What a boundary received, as a framework adapter read it.\n *\n * The counterpart to `cascade.ts`: that one reads the input nobody passed, and\n * this one reads the three that were — props, contexts and hook cells. Split out\n * because they fail in opposite directions and the difference is the whole\n * safety property. A cascade reading is either present or the property was\n * declared; a holding reading can be *absent*, and absent must never settle as\n * agreement. Everything here that returns `unread` is doing that work.\n */\n\n/**\n * What differs between two readings of one boundary.\n *\n * `unread` is returned beside the inputs rather than folded into them because\n * the two answer different questions. The inputs say what moved; `unread` says\n * whether \"nothing moved\" is a reading or a shrug, and only the second caller —\n * the one about to call a render nondeterministic — needs it.\n */\nexport function compareHoldings(\n  left: Holding | undefined,\n  right: Holding | undefined,\n): { inputs: readonly MovedInput[]; unread: boolean } {\n  const inputs: MovedInput[] = [];\n  let unread = left?.unread !== undefined || right?.unread !== undefined;\n\n  // Absent props mean `memoizedProps` was not an object, which is a failure to\n  // read rather than a component with no props. Symmetric absence is left alone:\n  // two readings that failed the same way have not disagreed.\n  if ((left?.props === undefined) !== (right?.props === undefined)) unread = true;\n  else compareNamed('prop', left?.props, right?.props, inputs);\n\n  // Contexts are different: absent means `dependencies` was null, and that is a\n  // positive reading — this component subscribes to no context.\n  compareNamed('context', left?.contexts, right?.contexts, inputs);\n\n  if (left?.cells === undefined || right?.cells === undefined) unread = true;\n  else compareCells(left.cells, right.cells, inputs);\n\n  return { inputs, unread };\n}\n\nfunction compareNamed(\n  kind: 'prop' | 'context',\n  left: readonly HeldValue[] | undefined,\n  right: readonly HeldValue[] | undefined,\n  into: MovedInput[],\n): void {\n  const before = new Map((left ?? []).map((value) => [value.name, value.digest]));\n  const after = new Map((right ?? []).map((value) => [value.name, value.digest]));\n\n  for (const name of [...new Set([...before.keys(), ...after.keys()])].sort()) {\n    const from = before.get(name);\n    const to = after.get(name);\n    if (from !== to) into.push({ kind, name, from, to });\n  }\n}\n\n/**\n * Hook cells, joined on call position.\n *\n * On position rather than on name because position is what a hook *is* to React\n * — the rule the linter enforces — and because a component that ran a different\n * number of hooks took a different branch before it rendered anything. That case\n * arrives here as cells present on one side only, which is a reading rather than\n * a join failure, and one of the loudest available.\n */\nfunction compareCells(\n  left: readonly HeldCell[],\n  right: readonly HeldCell[],\n  into: MovedInput[],\n): void {\n  const before = new Map(left.map((cell) => [cell.index, cell]));\n  const after = new Map(right.map((cell) => [cell.index, cell]));\n\n  for (const index of [...new Set([...before.keys(), ...after.keys()])].sort((a, b) => a - b)) {\n    const from = before.get(index);\n    const to = after.get(index);\n    if (from?.digest === to?.digest && from?.hook === to?.hook) continue;\n    into.push({\n      kind: 'hook',\n      name: to?.hook ?? from?.hook ?? '(unknown)',\n      index,\n      from: from?.digest,\n      to: to?.digest,\n    });\n  }\n}\n"]}

package/dist/compare/impact.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Render impact: what a changed property can actually disturb.
+ *
+ * This is a **second axis**, orthogonal to the frequency bands of §5, and adding
+ * it rather than folding it into them is deliberate. A band answers *what kind of
+ * thing changed* — structure, a value, sub-pixel noise. Impact answers *how far
+ * the change can reach*.
+ *
+ * The two genuinely differ. A spacing token and a colour token are both `token`
+ * band: a value moved, structure held. But changing spacing reflows the document,
+ * so it can move a node on the other side of the page; changing colour repaints
+ * one box and can move nothing at all. Reporting both as "a token changed" hides
+ * the only thing a reviewer wants to know first.
+ *
+ * The useful consequence is a **bound on collateral**:
+ *
+ * > A paint-only change has no geometric collateral. Ever.
+ *
+ * That is not a heuristic — it follows from how rendering works. So a subject
+ * whose every delta is paint-impact needs no layout comparison to rule out
+ * geometry regressions, which is exactly the kind of question a profile without a
+ * layout engine can otherwise never settle. It is how the cheap tier answers
+ * *"could this have moved anything?"* without measuring anything.
+ */
+export type PropertyImpact = 
+/** Reflows: box sizes and positions may change, here and elsewhere. */
+'layout'
+/** Repaints in place. The box tree is untouched, so nothing moves. */
+ | 'paint'
+/** Compositing only: transform, opacity, stacking. No reflow, no repaint. */
+ | 'composite';
+/**
+ * Impact of a property change.
+ *
+ * An unrecognized property is reported as `layout`, the widest answer. Impact is
+ * used to *rule out* collateral, so an unknown treated as paint-only would let a
+ * real reflow pass unexamined — the over-reporting direction, as everywhere else.
+ */
+export declare function impactOf(property: string): PropertyImpact;
+/**
+ * Whether a change to this property can move anything.
+ *
+ * The question the cheap tier can answer without a layout engine, and the reason
+ * this axis exists.
+ */
+export declare function canReflow(property: string): boolean;
+export type AggregateImpact = PropertyImpact | 'mixed' | 'structural';
+/**
+ * Combine impacts for a group of changes.
+ *
+ * `structural` wins over everything: a node appearing or disappearing is not a
+ * property change at all, and describing it in terms of repaint versus reflow
+ * would understate it.
+ */
+export declare function aggregateImpact(impacts: readonly (PropertyImpact | 'structural')[]): AggregateImpact;
+//# sourceMappingURL=impact.d.ts.map