@variance-authority/core 0.1.0

package/dist/attribute/component-hash.js

@@ -0,0 +1,312 @@
+import { BANDS } from '../compare/band.js';
+import { digestValue } from '../format/hash.js';
+import { boundaries, shapeOf, UNATTRIBUTED } from './boundary.js';
+export { UNATTRIBUTED } from './boundary.js';
+/**
+ * Per-component content hashes, one per band.
+ *
+ * `SemanticSnapshot` hashes a whole subject. That answers "did anything change"
+ * and nothing else: it moves whenever anything inside it moves, so it cannot say
+ * *which area*, and a record built on it says "the page changed" on every commit.
+ *
+ * These hashes are the unit a history is kept in. Text, and small — a component
+ * that did not change contributes the same digest it did last time, so the only
+ * thing worth recording is the difference.
+ */
+/**
+ * Hash every component boundary in a subject.
+ *
+ * Ordered by component name so an unchanged subject produces byte-identical
+ * output across runs.
+ *
+ * The walk and the per-boundary shape live in {@link ./boundary.js}, which
+ * {@link ./instances.js} shares — one definition of what a component's own
+ * content is, read by the aggregate and by the per-instance form.
+ */
+export function hashComponents(snapshot) {
+    const layout = snapshot.profile.layout;
+    const accumulated = new Map();
+    for (const boundary of boundaries(snapshot.root)) {
+        const shape = shapeOf(boundary, layout);
+        const entry = accumulated.get(boundary.component) ?? {
+            structure: [],
+            semantics: [],
+            text: [],
+            style: [],
+            geometry: [],
+            boxes: [],
+        };
+        entry.structure.push(shape.structure);
+        entry.semantics.push(shape.semantics);
+        entry.text.push(shape.text);
+        entry.style.push(shape.style);
+        entry.geometry.push(shape.geometry);
+        entry.boxes.push(shape.box);
+        accumulated.set(boundary.component, entry);
+    }
+    return [...accumulated.entries()]
+        .map(([component, entry]) => ({
+        component,
+        instances: entry.structure.length,
+        structure: digestValue(entry.structure),
+        semantics: digestValue(entry.semantics),
+        text: digestValue(entry.text),
+        style: digestValue(entry.style),
+        ...(layout ? { geometry: digestValue(entry.geometry) } : {}),
+        // Under a profile with no layout every entry is `null`, and a list of
+        // nulls is a measurement nobody took written as one they did. Absent
+        // instead, which is the same rule `geometry` above obeys.
+        ...(layout ? { boxes: entry.boxes } : {}),
+    }))
+        // Code-unit order, not `localeCompare`. The doc above promises byte-identical
+        // output for an unchanged subject, and a locale-aware comparison makes that a
+        // promise about the machine's `LANG` — which was tolerable while these were
+        // internal and is not now that they are written into a sidecar, committed
+        // beside a baseline, and read back on someone else's runner.
+        .sort((a, b) => (a.component < b.component ? -1 : a.component > b.component ? 1 : 0));
+}
+/**
+ * Which components *caused* a change, given both revisions' hashes.
+ *
+ * The arithmetic behind cause-first ranking, and the reason a baseline carries
+ * its component hashes at all. `rankRegions` takes a list of cause names and,
+ * given none, falls back to area — which
+ * [journal 0013](../../../../docs/context/journal/0013-observability.md)
+ * measured as backwards by 6×, because area measures displacement rather than
+ * cause. This is where that list comes from on a path with no second document.
+ *
+ * The distinction is the split ADR-0018 built the bands for:
+ *
+ * - **`structure` or `style` moved** — the component's own content is different.
+ *   It is a cause.
+ * - **only `geometry` moved** — the component is byte-identical and its box is
+ *   somewhere else. Something *else* moved it, so it is collateral, and naming
+ *   it would send a reviewer to a file nobody edited.
+ * - **appeared or disappeared** — a component present on one side only is a
+ *   cause. Something decided to render it or to stop.
+ *
+ * `instances` is deliberately not consulted. A component rendered five times
+ * instead of four has a different `structure` digest for the subject, and the
+ * count moving on its own — the same component, the same content, one more of
+ * them — is a change in whatever decided how many, not in this component.
+ *
+ * A profile with no layout supplies no `geometry`, so on that tier every
+ * difference is `structure` or `style` and every changed component is a cause.
+ * That is correct rather than degraded: with no boxes, nothing was displaced.
+ */
+export function causesBetween(before, after) {
+    const previous = new Map(before.map((entry) => [entry.component, entry]));
+    const causes = [];
+    for (const entry of after) {
+        // `(unattributed)` is not a component and can never be a cause. It is the
+        // bucket for nodes whose provenance chain broke, so it collects unrelated
+        // parts of a page under one name — and nothing downstream could act on it
+        // anyway: a region with no owner reports no component, so it would never
+        // match. A broken chain is a defect in this tool and is reported as
+        // `unattributed` where that means something, not smuggled in here as a
+        // culprit.
+        if (entry.component === UNATTRIBUTED)
+            continue;
+        const was = previous.get(entry.component);
+        if (was === undefined) {
+            causes.push(entry.component);
+            continue;
+        }
+        if (ownContentMoved(was, entry))
+            causes.push(entry.component);
+    }
+    // Removals too, and they are the case a candidate-only walk cannot see: a
+    // component that stopped rendering leaves regions behind it, and the component
+    // that used to be there is exactly the name a reviewer needs.
+    const present = new Set(after.map((entry) => entry.component));
+    for (const entry of before) {
+        if (entry.component === UNATTRIBUTED)
+            continue;
+        if (!present.has(entry.component))
+            causes.push(entry.component);
+    }
+    return causes.sort();
+}
+/**
+ * Whether a component's *own content* differs, ignoring where its box ended up.
+ *
+ * Deliberately not phrased in bands, because it is not a band question. Both
+ * `structure` and `geometry` map to the `geometry` band, and this has to keep
+ * them apart: a component whose tree changed edited itself, and a component
+ * whose rect moved was pushed. That distinction is the entire cause/collateral
+ * result, and asking it through the band mapping would need the digests back
+ * again to answer it.
+ *
+ * The list is every digest a component owns except `geometry`. It grew by two on
+ * 2026-08-06 without changing meaning: `semantics` and `text` used to be inside
+ * `structure`.
+ */
+function ownContentMoved(before, after) {
+    return (before.structure !== after.structure ||
+        before.semantics !== after.semantics ||
+        before.text !== after.text ||
+        before.style !== after.style);
+}
+/**
+ * Which frequency bands moved between one component's two hashes.
+ *
+ * The reason the digests were split. A baseline carries hashes and not
+ * documents, so "what changed here" used to be answerable only as a boolean —
+ * and a boolean cannot serve a route-level test, whose entire request is *tell
+ * me when the page stops assembling and never when it is repainted*.
+ *
+ * The mapping is exact and it is the same one `bandOf` applies to a delta, which
+ * is the property that matters: a subject relaxed to `layout` must absorb the
+ * same things whether the run held two documents or two sidecars. Two mappings
+ * would be one drift away from a config key meaning different things on the two
+ * paths, discovered as a regression somebody let through.
+ *
+ * | digest | band | what it covers |
+ * |---|---|---|
+ * | `semantics` | `a11y` | role, accessible name, ARIA state |
+ * | `text` | `content` | text runs |
+ * | `structure` | `geometry` | tags, aliases, attributes, child boundaries |
+ * | `geometry` | `geometry` | rects and computed layout output |
+ * | `style` | `token` | declared values and custom properties |
+ *
+ * `texture` never appears. It is raster residue by definition, and a component
+ * hash is built from a document — so the band a comparison of hashes cannot
+ * decide is *absent* from the answer rather than reported as unmoved, which is
+ * ADR-0002's rule applied to a narrower question.
+ *
+ * A missing `geometry` on either side is the profile saying it has no layout
+ * engine, and is not a difference. Treating absent as a change would report
+ * every component as having moved the moment a jsdom baseline met a Chromium
+ * run — which the environment key already refuses as `incomparable`, so this
+ * would be a second, wronger answer to a question already settled.
+ */
+export function movedBands(before, after) {
+    const moved = new Set();
+    if (before.semantics !== after.semantics)
+        moved.add('a11y');
+    if (before.text !== after.text)
+        moved.add('content');
+    if (before.structure !== after.structure)
+        moved.add('geometry');
+    if (before.style !== after.style)
+        moved.add('token');
+    if (before.geometry !== undefined &&
+        after.geometry !== undefined &&
+        before.geometry !== after.geometry) {
+        moved.add('geometry');
+    }
+    return BANDS.filter((band) => moved.has(band));
+}
+/**
+ * Every band that moved anywhere in the subject, given both revisions' hashes.
+ *
+ * A component present on one side only contributes `geometry`: something was
+ * added or removed, which is the structural half of that band however the rest
+ * of it compares. It deliberately does not contribute `a11y` or `content` as
+ * well — a component that is simply not there did not *rename* anything, and
+ * inflating the answer would make a level that absorbs nothing look like the
+ * only safe choice.
+ */
+export function bandsBetween(before, after) {
+    const previous = new Map(before.map((entry) => [entry.component, entry]));
+    const present = new Set(after.map((entry) => entry.component));
+    const moved = new Set();
+    for (const entry of after) {
+        const was = previous.get(entry.component);
+        if (was === undefined)
+            moved.add('geometry');
+        else
+            for (const band of movedBands(was, entry))
+                moved.add(band);
+    }
+    for (const entry of before) {
+        if (!present.has(entry.component))
+            moved.add('geometry');
+    }
+    return BANDS.filter((band) => moved.has(band));
+}
+/**
+ * Every component whose hashes differ, with the bands it differs in.
+ *
+ * One-sided components contribute `geometry` and nothing else, which is
+ * {@link bandsBetween}'s rule and must stay identical to it: a component that is
+ * simply not there did not rename anything, and inflating the answer would put
+ * an `a11y` claim on a page for a component nobody can look at. `presence` is
+ * what carries the rest of that meaning, so no reader has to infer *appeared*
+ * from a lone `geometry`.
+ *
+ * `(unattributed)` is excluded for the reason {@link causesBetween} excludes it:
+ * it is a bucket for nodes whose provenance chain broke, so it collects
+ * unrelated parts of a page under one name and nothing downstream could act on
+ * it. The broken chain is reported where it means something, not here as a
+ * component that moved.
+ */
+export function movedBandsBetween(before, after) {
+    const previous = new Map(before.map((entry) => [entry.component, entry]));
+    const present = new Set(after.map((entry) => entry.component));
+    const moved = [];
+    for (const entry of after) {
+        if (entry.component === UNATTRIBUTED)
+            continue;
+        const was = previous.get(entry.component);
+        if (was === undefined) {
+            moved.push({ component: entry.component, bands: ['geometry'], cause: true, presence: 'added' });
+            continue;
+        }
+        const bands = movedBands(was, entry);
+        if (bands.length === 0)
+            continue;
+        const grew = grewBetween(was.boxes, entry.boxes);
+        moved.push({
+            component: entry.component,
+            bands,
+            cause: ownContentMoved(was, entry),
+            ...(grew === undefined ? {} : { grew }),
+        });
+    }
+    for (const entry of before) {
+        if (entry.component === UNATTRIBUTED)
+            continue;
+        if (present.has(entry.component))
+            continue;
+        moved.push({ component: entry.component, bands: ['geometry'], cause: true, presence: 'removed' });
+    }
+    return moved.sort((left, right) => left.component.localeCompare(right.component));
+}
+/**
+ * One size delta both sides agree on, or nothing.
+ *
+ * Instances are paired by document order, which is the only order either side
+ * has. That pairing is sound exactly while the counts match: a component that
+ * gained an instance shifted every index after the insertion, and the deltas
+ * that fell out would be measurements of one instance against a different one.
+ * So a changed count answers nothing rather than answering wrongly — the count
+ * itself already moved `structure`, and the reviewer is told that instead.
+ *
+ * Instances that disagree also answer nothing. Three buttons where one grew and
+ * two did not is a real finding and it is not *this* one, and printing the first
+ * or the largest would be the page picking a representative and not saying so.
+ *
+ * Position is deliberately not read. Everything below a control that got taller
+ * moved down, and a delta drawn from `x`/`y` would name every one of them.
+ */
+function grewBetween(before, after) {
+    if (before === undefined || after === undefined)
+        return undefined;
+    if (before.length === 0 || before.length !== after.length)
+        return undefined;
+    let agreed;
+    for (const [index, was] of before.entries()) {
+        const now = after[index];
+        if (was === null || was === undefined || now === null || now === undefined)
+            return undefined;
+        const width = now.width - was.width;
+        const height = now.height - was.height;
+        if (agreed === undefined)
+            agreed = { width, height };
+        else if (agreed.width !== width || agreed.height !== height)
+            return undefined;
+    }
+    return agreed === undefined || (agreed.width === 0 && agreed.height === 0) ? undefined : agreed;
+}
+//# sourceMappingURL=component-hash.js.map

package/dist/attribute/component-hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-hash.js","sourceRoot":"","sources":["../../src/attribute/component-hash.ts"],"names":[],"mappings":"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","sourcesContent":["import { BANDS, type Band } from '../compare/band.js';\nimport type { CanonicalValue } from '../format/canonical.js';\nimport type { Rect } from '../format/capture.js';\nimport type { Digest } from '../format/hash.js';\nimport { digestValue } from '../format/hash.js';\nimport type { ComponentHash, SemanticSnapshot } from '../format/snapshot.js';\nimport { boundaries, shapeOf, UNATTRIBUTED } from './boundary.js';\n\nexport type { ComponentHash } from '../format/snapshot.js';\nexport { UNATTRIBUTED } from './boundary.js';\n\n/**\n * The digests a comparison of two component states actually reads.\n *\n * `movedBands` used to take two `ComponentHash`es, which carry a name and an\n * instance count neither side of the comparison consults. Narrowing it to the\n * digests is what lets a per-instance record (`ComponentInstance`, which has no\n * `instances` count because it *is* one) be compared by the same function —\n * rather than by a second copy of the band mapping, which is the one thing in\n * this file that must not exist twice: a subject relaxed to `layout` has to\n * absorb the same bands whichever shape the caller happened to be holding.\n */\nexport interface BandDigests {\n  readonly structure: Digest;\n  readonly semantics: Digest;\n  readonly text: Digest;\n  readonly style: Digest;\n  readonly geometry?: Digest;\n}\n\n/**\n * Per-component content hashes, one per band.\n *\n * `SemanticSnapshot` hashes a whole subject. That answers \"did anything change\"\n * and nothing else: it moves whenever anything inside it moves, so it cannot say\n * *which area*, and a record built on it says \"the page changed\" on every commit.\n *\n * These hashes are the unit a history is kept in. Text, and small — a component\n * that did not change contributes the same digest it did last time, so the only\n * thing worth recording is the difference.\n */\n\n/**\n * Hash every component boundary in a subject.\n *\n * Ordered by component name so an unchanged subject produces byte-identical\n * output across runs.\n *\n * The walk and the per-boundary shape live in {@link ./boundary.js}, which\n * {@link ./instances.js} shares — one definition of what a component's own\n * content is, read by the aggregate and by the per-instance form.\n */\nexport function hashComponents(snapshot: SemanticSnapshot): readonly ComponentHash[] {\n  const layout = snapshot.profile.layout;\n\n  const accumulated = new Map<\n    string,\n    {\n      structure: CanonicalValue[];\n      semantics: CanonicalValue[];\n      text: CanonicalValue[];\n      style: CanonicalValue[];\n      geometry: CanonicalValue[];\n      boxes: (Rect | null)[];\n    }\n  >();\n\n  for (const boundary of boundaries(snapshot.root)) {\n    const shape = shapeOf(boundary, layout);\n\n    const entry = accumulated.get(boundary.component) ?? {\n      structure: [],\n      semantics: [],\n      text: [],\n      style: [],\n      geometry: [],\n      boxes: [],\n    };\n    entry.structure.push(shape.structure);\n    entry.semantics.push(shape.semantics);\n    entry.text.push(shape.text);\n    entry.style.push(shape.style);\n    entry.geometry.push(shape.geometry);\n    entry.boxes.push(shape.box);\n    accumulated.set(boundary.component, entry);\n  }\n\n  return [...accumulated.entries()]\n    .map(([component, entry]) => ({\n      component,\n      instances: entry.structure.length,\n      structure: digestValue(entry.structure),\n      semantics: digestValue(entry.semantics),\n      text: digestValue(entry.text),\n      style: digestValue(entry.style),\n      ...(layout ? { geometry: digestValue(entry.geometry) } : {}),\n      // Under a profile with no layout every entry is `null`, and a list of\n      // nulls is a measurement nobody took written as one they did. Absent\n      // instead, which is the same rule `geometry` above obeys.\n      ...(layout ? { boxes: entry.boxes } : {}),\n    }))\n    // Code-unit order, not `localeCompare`. The doc above promises byte-identical\n    // output for an unchanged subject, and a locale-aware comparison makes that a\n    // promise about the machine's `LANG` — which was tolerable while these were\n    // internal and is not now that they are written into a sidecar, committed\n    // beside a baseline, and read back on someone else's runner.\n    .sort((a, b) => (a.component < b.component ? -1 : a.component > b.component ? 1 : 0));\n}\n\n/**\n * Which components *caused* a change, given both revisions' hashes.\n *\n * The arithmetic behind cause-first ranking, and the reason a baseline carries\n * its component hashes at all. `rankRegions` takes a list of cause names and,\n * given none, falls back to area — which\n * [journal 0013](../../../../docs/context/journal/0013-observability.md)\n * measured as backwards by 6×, because area measures displacement rather than\n * cause. This is where that list comes from on a path with no second document.\n *\n * The distinction is the split ADR-0018 built the bands for:\n *\n * - **`structure` or `style` moved** — the component's own content is different.\n *   It is a cause.\n * - **only `geometry` moved** — the component is byte-identical and its box is\n *   somewhere else. Something *else* moved it, so it is collateral, and naming\n *   it would send a reviewer to a file nobody edited.\n * - **appeared or disappeared** — a component present on one side only is a\n *   cause. Something decided to render it or to stop.\n *\n * `instances` is deliberately not consulted. A component rendered five times\n * instead of four has a different `structure` digest for the subject, and the\n * count moving on its own — the same component, the same content, one more of\n * them — is a change in whatever decided how many, not in this component.\n *\n * A profile with no layout supplies no `geometry`, so on that tier every\n * difference is `structure` or `style` and every changed component is a cause.\n * That is correct rather than degraded: with no boxes, nothing was displaced.\n */\nexport function causesBetween(\n  before: readonly ComponentHash[],\n  after: readonly ComponentHash[],\n): readonly string[] {\n  const previous = new Map(before.map((entry) => [entry.component, entry]));\n  const causes: string[] = [];\n\n  for (const entry of after) {\n    // `(unattributed)` is not a component and can never be a cause. It is the\n    // bucket for nodes whose provenance chain broke, so it collects unrelated\n    // parts of a page under one name — and nothing downstream could act on it\n    // anyway: a region with no owner reports no component, so it would never\n    // match. A broken chain is a defect in this tool and is reported as\n    // `unattributed` where that means something, not smuggled in here as a\n    // culprit.\n    if (entry.component === UNATTRIBUTED) continue;\n\n    const was = previous.get(entry.component);\n    if (was === undefined) {\n      causes.push(entry.component);\n      continue;\n    }\n    if (ownContentMoved(was, entry)) causes.push(entry.component);\n  }\n\n  // Removals too, and they are the case a candidate-only walk cannot see: a\n  // component that stopped rendering leaves regions behind it, and the component\n  // that used to be there is exactly the name a reviewer needs.\n  const present = new Set(after.map((entry) => entry.component));\n  for (const entry of before) {\n    if (entry.component === UNATTRIBUTED) continue;\n    if (!present.has(entry.component)) causes.push(entry.component);\n  }\n\n  return causes.sort();\n}\n\n/**\n * Whether a component's *own content* differs, ignoring where its box ended up.\n *\n * Deliberately not phrased in bands, because it is not a band question. Both\n * `structure` and `geometry` map to the `geometry` band, and this has to keep\n * them apart: a component whose tree changed edited itself, and a component\n * whose rect moved was pushed. That distinction is the entire cause/collateral\n * result, and asking it through the band mapping would need the digests back\n * again to answer it.\n *\n * The list is every digest a component owns except `geometry`. It grew by two on\n * 2026-08-06 without changing meaning: `semantics` and `text` used to be inside\n * `structure`.\n */\nfunction ownContentMoved(before: BandDigests, after: BandDigests): boolean {\n  return (\n    before.structure !== after.structure ||\n    before.semantics !== after.semantics ||\n    before.text !== after.text ||\n    before.style !== after.style\n  );\n}\n\n/**\n * Which frequency bands moved between one component's two hashes.\n *\n * The reason the digests were split. A baseline carries hashes and not\n * documents, so \"what changed here\" used to be answerable only as a boolean —\n * and a boolean cannot serve a route-level test, whose entire request is *tell\n * me when the page stops assembling and never when it is repainted*.\n *\n * The mapping is exact and it is the same one `bandOf` applies to a delta, which\n * is the property that matters: a subject relaxed to `layout` must absorb the\n * same things whether the run held two documents or two sidecars. Two mappings\n * would be one drift away from a config key meaning different things on the two\n * paths, discovered as a regression somebody let through.\n *\n * | digest | band | what it covers |\n * |---|---|---|\n * | `semantics` | `a11y` | role, accessible name, ARIA state |\n * | `text` | `content` | text runs |\n * | `structure` | `geometry` | tags, aliases, attributes, child boundaries |\n * | `geometry` | `geometry` | rects and computed layout output |\n * | `style` | `token` | declared values and custom properties |\n *\n * `texture` never appears. It is raster residue by definition, and a component\n * hash is built from a document — so the band a comparison of hashes cannot\n * decide is *absent* from the answer rather than reported as unmoved, which is\n * ADR-0002's rule applied to a narrower question.\n *\n * A missing `geometry` on either side is the profile saying it has no layout\n * engine, and is not a difference. Treating absent as a change would report\n * every component as having moved the moment a jsdom baseline met a Chromium\n * run — which the environment key already refuses as `incomparable`, so this\n * would be a second, wronger answer to a question already settled.\n */\nexport function movedBands(before: BandDigests, after: BandDigests): readonly Band[] {\n  const moved = new Set<Band>();\n\n  if (before.semantics !== after.semantics) moved.add('a11y');\n  if (before.text !== after.text) moved.add('content');\n  if (before.structure !== after.structure) moved.add('geometry');\n  if (before.style !== after.style) moved.add('token');\n  if (\n    before.geometry !== undefined &&\n    after.geometry !== undefined &&\n    before.geometry !== after.geometry\n  ) {\n    moved.add('geometry');\n  }\n\n  return BANDS.filter((band) => moved.has(band));\n}\n\n/**\n * Every band that moved anywhere in the subject, given both revisions' hashes.\n *\n * A component present on one side only contributes `geometry`: something was\n * added or removed, which is the structural half of that band however the rest\n * of it compares. It deliberately does not contribute `a11y` or `content` as\n * well — a component that is simply not there did not *rename* anything, and\n * inflating the answer would make a level that absorbs nothing look like the\n * only safe choice.\n */\nexport function bandsBetween(\n  before: readonly ComponentHash[],\n  after: readonly ComponentHash[],\n): readonly Band[] {\n  const previous = new Map(before.map((entry) => [entry.component, entry]));\n  const present = new Set(after.map((entry) => entry.component));\n  const moved = new Set<Band>();\n\n  for (const entry of after) {\n    const was = previous.get(entry.component);\n    if (was === undefined) moved.add('geometry');\n    else for (const band of movedBands(was, entry)) moved.add(band);\n  }\n\n  for (const entry of before) {\n    if (!present.has(entry.component)) moved.add('geometry');\n  }\n\n  return BANDS.filter((band) => moved.has(band));\n}\n\n/**\n * Which bands moved, kept per component instead of folded into one list.\n *\n * {@link bandsBetween} answers *what kind of change is in this subject*, which is\n * the question a sensitivity level asks. It cannot answer the one a reviewer\n * asks — *what changed, and where* — because the fold is lossy in exactly the\n * place attribution lives: a subject reporting `content, geometry, token` has\n * told you a colour and a string and a size all moved somewhere in it, and left\n * you to guess which of the forty components on the page owns which.\n *\n * Unfolded, the same two sidecars say `Button — geometry, token` and\n * `CardFooter — a11y, content`, and that is a sentence a page can print beside a\n * picture. It is also the record that survives when the raster tier loses the\n * name: a difference that reflowed its neighbours merges into one blob whose box\n * fits no component, so the region resolves to the document root and the edit\n * arrives unattributed — while the hashes, which never looked at a pixel, still\n * hold the component that moved and the sense in which it moved.\n *\n * `cause` repeats the {@link causesBetween} predicate rather than being derived\n * from `bands`, and the repetition is the point: `structure` and `geometry` both\n * map to the `geometry` band, so a component that edited its own tree and one\n * that was merely pushed by a neighbour are indistinguishable *after* the band\n * mapping. Losing that here would make every reflowed container a culprit.\n */\nexport interface ComponentBands {\n  readonly component: string;\n  /** Non-empty: a component whose digests all matched has no entry at all. */\n  readonly bands: readonly Band[];\n  /** Its own content moved, as opposed to only its rect. `causesBetween`'s test. */\n  readonly cause: boolean;\n  /** Set only when the component is on one side alone, which `bands` cannot say. */\n  readonly presence?: 'added' | 'removed';\n\n  /**\n   * How much bigger its own box got, when every instance agrees on the answer.\n   *\n   * The band a reviewer actually wanted. `geometry` says a rect under here is\n   * not the rect it was; this says the control is eight pixels taller and\n   * thirty-six wider, which is the padding somebody edited, arriving as a\n   * measurement rather than as a guess about which property produced it.\n   *\n   * Absent for four different reasons and they are one reason: nobody can say.\n   * No boxes on one side, a different number of instances, instances that\n   * disagree about the delta, or a box that did not change size. Present is\n   * always non-zero on at least one axis.\n   */\n  readonly grew?: { readonly width: number; readonly height: number };\n}\n\n/**\n * Every component whose hashes differ, with the bands it differs in.\n *\n * One-sided components contribute `geometry` and nothing else, which is\n * {@link bandsBetween}'s rule and must stay identical to it: a component that is\n * simply not there did not rename anything, and inflating the answer would put\n * an `a11y` claim on a page for a component nobody can look at. `presence` is\n * what carries the rest of that meaning, so no reader has to infer *appeared*\n * from a lone `geometry`.\n *\n * `(unattributed)` is excluded for the reason {@link causesBetween} excludes it:\n * it is a bucket for nodes whose provenance chain broke, so it collects\n * unrelated parts of a page under one name and nothing downstream could act on\n * it. The broken chain is reported where it means something, not here as a\n * component that moved.\n */\nexport function movedBandsBetween(\n  before: readonly ComponentHash[],\n  after: readonly ComponentHash[],\n): readonly ComponentBands[] {\n  const previous = new Map(before.map((entry) => [entry.component, entry]));\n  const present = new Set(after.map((entry) => entry.component));\n  const moved: ComponentBands[] = [];\n\n  for (const entry of after) {\n    if (entry.component === UNATTRIBUTED) continue;\n    const was = previous.get(entry.component);\n    if (was === undefined) {\n      moved.push({ component: entry.component, bands: ['geometry'], cause: true, presence: 'added' });\n      continue;\n    }\n    const bands = movedBands(was, entry);\n    if (bands.length === 0) continue;\n    const grew = grewBetween(was.boxes, entry.boxes);\n    moved.push({\n      component: entry.component,\n      bands,\n      cause: ownContentMoved(was, entry),\n      ...(grew === undefined ? {} : { grew }),\n    });\n  }\n\n  for (const entry of before) {\n    if (entry.component === UNATTRIBUTED) continue;\n    if (present.has(entry.component)) continue;\n    moved.push({ component: entry.component, bands: ['geometry'], cause: true, presence: 'removed' });\n  }\n\n  return moved.sort((left, right) => left.component.localeCompare(right.component));\n}\n\n/**\n * One size delta both sides agree on, or nothing.\n *\n * Instances are paired by document order, which is the only order either side\n * has. That pairing is sound exactly while the counts match: a component that\n * gained an instance shifted every index after the insertion, and the deltas\n * that fell out would be measurements of one instance against a different one.\n * So a changed count answers nothing rather than answering wrongly — the count\n * itself already moved `structure`, and the reviewer is told that instead.\n *\n * Instances that disagree also answer nothing. Three buttons where one grew and\n * two did not is a real finding and it is not *this* one, and printing the first\n * or the largest would be the page picking a representative and not saying so.\n *\n * Position is deliberately not read. Everything below a control that got taller\n * moved down, and a delta drawn from `x`/`y` would name every one of them.\n */\nfunction grewBetween(\n  before: readonly (Rect | null)[] | undefined,\n  after: readonly (Rect | null)[] | undefined,\n): { readonly width: number; readonly height: number } | undefined {\n  if (before === undefined || after === undefined) return undefined;\n  if (before.length === 0 || before.length !== after.length) return undefined;\n\n  let agreed: { width: number; height: number } | undefined;\n  for (const [index, was] of before.entries()) {\n    const now = after[index];\n    if (was === null || was === undefined || now === null || now === undefined) return undefined;\n\n    const width = now.width - was.width;\n    const height = now.height - was.height;\n    if (agreed === undefined) agreed = { width, height };\n    else if (agreed.width !== width || agreed.height !== height) return undefined;\n  }\n\n  return agreed === undefined || (agreed.width === 0 && agreed.height === 0) ? undefined : agreed;\n}\n"]}

package/dist/attribute/composition-fixture.d.ts

@@ -0,0 +1,18 @@
+/**
+ * One small suite, built twice over: as a graph, and as something that moved.
+ *
+ * `composition.test.ts` proves the fold and `movement.test.ts` proves the ladder
+ * that reads it, and they need the same three subjects to do it. A chip in its
+ * own story and the same chip in a page is the smallest arrangement in which an
+ * echo, a divergence and a control group are all available at once, so it is
+ * described once here rather than diverging in two files.
+ */
+import type { ComponentInstance } from './instances.js';
+import type { SubjectComposition } from './composition.js';
+export declare function instance(over: Partial<ComponentInstance> & {
+    component: string;
+}): ComponentInstance;
+/** A chip, rendered the same way, with the same inputs. */
+export declare const chip: (path: string, within: string, over?: Partial<ComponentInstance>) => ComponentInstance;
+export declare const SUITE: readonly SubjectComposition[];
+//# sourceMappingURL=composition-fixture.d.ts.map

package/dist/attribute/composition-fixture.js

@@ -0,0 +1,53 @@
+/**
+ * One small suite, built twice over: as a graph, and as something that moved.
+ *
+ * `composition.test.ts` proves the fold and `movement.test.ts` proves the ladder
+ * that reads it, and they need the same three subjects to do it. A chip in its
+ * own story and the same chip in a page is the smallest arrangement in which an
+ * echo, a divergence and a control group are all available at once, so it is
+ * described once here rather than diverging in two files.
+ */
+export function instance(over) {
+    return {
+        path: '0',
+        depth: 1,
+        rendering: 'v1:r',
+        structure: 'v1:s',
+        semantics: 'v1:a',
+        text: 'v1:t',
+        style: 'v1:y',
+        renders: [],
+        nodes: 1,
+        tokens: [],
+        ...over,
+    };
+}
+/** A chip, rendered the same way, with the same inputs. */
+export const chip = (path, within, over = {}) => instance({
+    component: 'Chip',
+    path,
+    within,
+    depth: 2,
+    props: 'v1:chip',
+    rendering: 'v1:chip-done',
+    ...over,
+});
+export const SUITE = [
+    {
+        subject: 'story:ds-chip--done',
+        instances: [
+            instance({ component: 'Story', path: '0', depth: 0, renders: ['Chip'] }),
+            chip('0/0', 'Story'),
+        ],
+    },
+    {
+        subject: 'story:page--default',
+        instances: [
+            instance({ component: 'App', path: '0', depth: 0, renders: ['Footer'] }),
+            instance({ component: 'Footer', path: '0/1', depth: 1, renders: ['Chip', 'Chip'] }),
+            chip('0/1/0', 'Footer', { props: 'v1:chip-all', rendering: 'v1:chip-all' }),
+            chip('0/1/1', 'Footer'),
+        ],
+    },
+];
+//# sourceMappingURL=composition-fixture.js.map

package/dist/attribute/composition-fixture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition-fixture.js","sourceRoot":"","sources":["../../src/attribute/composition-fixture.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,UAAU,QAAQ,CAAC,IAAwD;IAC/E,OAAO;QACL,IAAI,EAAE,GAAG;QACT,KAAK,EAAE,CAAC;QACR,SAAS,EAAE,MAAM;QACjB,SAAS,EAAE,MAAM;QACjB,SAAS,EAAE,MAAM;QACjB,IAAI,EAAE,MAAM;QACZ,KAAK,EAAE,MAAM;QACb,OAAO,EAAE,EAAE;QACX,KAAK,EAAE,CAAC;QACR,MAAM,EAAE,EAAE;QACV,GAAG,IAAI;KACR,CAAC;AACJ,CAAC;AAED,2DAA2D;AAC3D,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,MAAc,EAAE,IAAI,GAA+B,EAAE,EAAE,EAAE,CAC1F,QAAQ,CAAC;IACP,SAAS,EAAE,MAAM;IACjB,IAAI;IACJ,MAAM;IACN,KAAK,EAAE,CAAC;IACR,KAAK,EAAE,SAAS;IAChB,SAAS,EAAE,cAAc;IACzB,GAAG,IAAI;CACR,CAAC,CAAC;AAEL,MAAM,CAAC,MAAM,KAAK,GAAkC;IAClD;QACE,OAAO,EAAE,qBAAqB;QAC9B,SAAS,EAAE;YACT,QAAQ,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;YACxE,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC;SACrB;KACF;IACD;QACE,OAAO,EAAE,qBAAqB;QAC9B,SAAS,EAAE;YACT,QAAQ,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC;YACxE,QAAQ,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;YACnF,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,aAAa,EAAE,CAAC;YAC3E,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC;SACxB;KACF;CACF,CAAC","sourcesContent":["/**\n * One small suite, built twice over: as a graph, and as something that moved.\n *\n * `composition.test.ts` proves the fold and `movement.test.ts` proves the ladder\n * that reads it, and they need the same three subjects to do it. A chip in its\n * own story and the same chip in a page is the smallest arrangement in which an\n * echo, a divergence and a control group are all available at once, so it is\n * described once here rather than diverging in two files.\n */\n\nimport type { ComponentInstance } from './instances.js';\nimport type { SubjectComposition } from './composition.js';\n\nexport function instance(over: Partial<ComponentInstance> & { component: string }): ComponentInstance {\n  return {\n    path: '0',\n    depth: 1,\n    rendering: 'v1:r',\n    structure: 'v1:s',\n    semantics: 'v1:a',\n    text: 'v1:t',\n    style: 'v1:y',\n    renders: [],\n    nodes: 1,\n    tokens: [],\n    ...over,\n  };\n}\n\n/** A chip, rendered the same way, with the same inputs. */\nexport const chip = (path: string, within: string, over: Partial<ComponentInstance> = {}) =>\n  instance({\n    component: 'Chip',\n    path,\n    within,\n    depth: 2,\n    props: 'v1:chip',\n    rendering: 'v1:chip-done',\n    ...over,\n  });\n\nexport const SUITE: readonly SubjectComposition[] = [\n  {\n    subject: 'story:ds-chip--done',\n    instances: [\n      instance({ component: 'Story', path: '0', depth: 0, renders: ['Chip'] }),\n      chip('0/0', 'Story'),\n    ],\n  },\n  {\n    subject: 'story:page--default',\n    instances: [\n      instance({ component: 'App', path: '0', depth: 0, renders: ['Footer'] }),\n      instance({ component: 'Footer', path: '0/1', depth: 1, renders: ['Chip', 'Chip'] }),\n      chip('0/1/0', 'Footer', { props: 'v1:chip-all', rendering: 'v1:chip-all' }),\n      chip('0/1/1', 'Footer'),\n    ],\n  },\n];\n"]}

package/dist/attribute/composition.d.ts

@@ -0,0 +1,182 @@
+import type { Digest } from '../format/hash.js';
+import type { NodePath, SemanticSnapshot } from '../format/snapshot.js';
+import { type Divergence } from './divergence.js';
+import { type ComponentInstance } from './instances.js';
+/**
+ * The suite read as one graph, at one commit.
+ *
+ * Every other comparison in this system is between two revisions of one subject.
+ * This is the other axis: **many subjects, one revision**, joined on the
+ * components they share. It answers the question a per-subject tool cannot even
+ * phrase — *this component, here, is the same component you already have an
+ * example of over there* — and it answers it from digests a run already
+ * computed, with no second render, no image and no store.
+ *
+ * ## What the join is worth
+ *
+ * A suite of examples is a suite of *compositions*. The narrow example is a
+ * component at a boundary; the page examples contain that same boundary again,
+ * sometimes with the same props and sometimes not. Once the instances are
+ * addressable, three facts fall out that nobody had:
+ *
+ * - **An echo.** One rendering, several subjects. The narrow example and the
+ *   page are watching literally the same bytes, so a change in one is a change
+ *   in all of them, and a reviewer looking at eleven diffs is looking at one.
+ * - **A divergence.** Same component, same props, *different* rendering, at one
+ *   commit. Nothing about the component's own inputs can explain that. Either
+ *   something outside it decides its output — an ancestor's cascade, a token, its
+ *   own state — or the reading is not repeatable. Both are findings and neither
+ *   is a regression.
+ * - **A control group.** For any instance that moved, the same rendering
+ *   somewhere else that did *not* is a stable state to refer to. That is the
+ *   referent flake attribution has always needed and never had, and the suite
+ *   supplies it for free: one commit already holds N renderings of every shared
+ *   component.
+ *
+ * ## What it deliberately does not do
+ *
+ * It never decides anything. Two subjects sharing a rendering is not a reason to
+ * delete either — that is the argument `coverage.ts` makes at the level of names
+ * and it holds harder here, because a component can be correct in one context
+ * and broken in the next, which is why the contexts are separate subjects.
+ */
+/** One instance, located. */
+export interface Site {
+    readonly subject: string;
+    readonly path: NodePath;
+    readonly depth: number;
+    readonly within?: string;
+    /**
+     * The component whose JSX wrote this element, here.
+     *
+     * On the entry beside it, `createdBy` is a set folded over the whole suite —
+     * every component that ever wrote one of these, anywhere. That is the right
+     * shape for *who mounts this* and the wrong one for *who mounted this here*,
+     * and the ladder asks the second: an edit to a component that writes a `Chip`
+     * on the footer explains nothing about a `Chip` the sidebar wrote. Kept per
+     * site so the question can be asked where it was answered.
+     */
+    readonly createdBy?: string;
+}
+/** One rendering of one component, and everywhere it occurred. */
+export interface Rendering {
+    readonly rendering: Digest;
+    readonly structure: Digest;
+    readonly semantics: Digest;
+    readonly text: Digest;
+    readonly style: Digest;
+    /**
+     * Child components this rendering mounted, in document order.
+     *
+     * Carried on the rendering rather than only on the entry because it is the
+     * only evidence available about what was passed *in*: `propsDigest` excludes
+     * `children` by design, so two renderings that mount different children are
+     * two different inputs wearing one props digest. `divergencesOf` refuses to
+     * call that a contradiction, and this is the field it reads.
+     */
+    readonly renders: readonly string[];
+    /** In subject order, then document order. */
+    readonly sites: readonly Site[];
+}
+/** One props digest of one component, and every way it rendered under it. */
+export interface PropsClass {
+    /** Absent when the collector supplied no provenance — unknown, not "none". */
+    readonly props?: Digest;
+    readonly renderings: readonly Rendering[];
+}
+export interface ComponentEntry {
+    readonly component: string;
+    /** Subjects containing at least one boundary of it, in the order supplied. */
+    readonly subjects: readonly string[];
+    /** Boundaries summed across every subject. Distinct from `subjects.length`. */
+    readonly instances: number;
+    /**
+     * Subjects whose shallowest attributed boundary is this component.
+     *
+     * The narrow example — the subject that exists to show this thing, rather than
+     * a page that happens to contain it. Defined by depth rather than by a naming
+     * convention because a naming convention is a different tool's `story:` prefix,
+     * and this has to hold for a route suite too. Ties resolve to nothing: a
+     * subject whose two shallowest boundaries are siblings has no single subject.
+     */
+    readonly examples: readonly string[];
+    /** Components that enclose it somewhere, sorted. The graph, upwards. */
+    readonly within: readonly string[];
+    /**
+     * Components that *mounted* it somewhere, sorted. The graph, upwards, again —
+     * and usually the more useful of the two.
+     *
+     * `within` is where the boundary sits in the DOM and this is who wrote the
+     * element. They are the same thing only for a component that authors a node of
+     * its own, and a real application is full of components that do not: measured
+     * on `examples/todomvc`, every `Chip` reports `within: ['Stack']` and
+     * `createdBy: ['TodoFooter']`. `TodoFooter` renders nothing but other
+     * components, so it owns no node, is a boundary nowhere, and appears in this
+     * graph *only* here — while being the file a reviewer has to open.
+     *
+     * Empty on a production build, where `_debugOwner` is absent (ADR-0007). Empty
+     * is *not* "nothing mounted it": a component with no caller is the subject root
+     * and every other case is missing data, which is why the `upstream` rung in
+     * `movement.ts` reads this and never concludes from its silence.
+     */
+    readonly createdBy: readonly string[];
+    /** Components it encloses somewhere, sorted. The graph, downwards. */
+    readonly renders: readonly string[];
+    /**
+     * Custom properties its own nodes resolve through, anywhere in the suite.
+     *
+     * The set a token movement is intersected against, which is how "`--va-space-3`
+     * moved" becomes "`--va-space-3` moved and these four components read it".
+     */
+    readonly tokens: readonly string[];
+    /** Sorted by props digest; the class with unknown props sorts last. */
+    readonly classes: readonly PropsClass[];
+}
+/**
+ * The same component, the same props, the same bytes, in more than one subject.
+ *
+ * The connected dots. `example` names the narrow subject among the sites when
+ * there is one, because that is the artefact a reviewer already has an opinion
+ * about — "this is the Chip from the Chip story" is a sentence, and "these four
+ * paths share a digest" is not.
+ */
+export interface Echo {
+    readonly component: string;
+    readonly props?: Digest;
+    readonly rendering: Digest;
+    /** At least two, spanning at least two subjects. */
+    readonly sites: readonly Site[];
+    readonly example?: string;
+}
+export interface SubjectComposition {
+    readonly subject: string;
+    readonly instances: readonly ComponentInstance[];
+    /**
+     * The subject as read, kept so a divergence can say *which input* moved.
+     *
+     * Optional because `composeSubjects` is a fold over instance lists and stays
+     * one — a caller holding only a report's sidecars still gets the graph, the
+     * echoes and the divergences, and gets them without a `partings` field it
+     * would have to explain away as empty.
+     */
+    readonly snapshot?: SemanticSnapshot;
+}
+export interface Composition {
+    /** In the order supplied, which the run guarantees is plan order. */
+    readonly subjects: readonly string[];
+    /** Sorted by name, code-unit order. */
+    readonly components: readonly ComponentEntry[];
+    /** Sorted by how many sites each has, widest first, then by component. */
+    readonly echoes: readonly Echo[];
+    /** Sorted by component name. */
+    readonly divergences: readonly Divergence[];
+}
+/**
+ * Fold a run's per-subject instance lists into the graph.
+ *
+ * Pure, ordered, and a function of its input alone — the run's report has to be
+ * a function of the plan, and a phase that accumulated as a worker pool finished
+ * would produce a different artefact from the same suite on a slower machine.
+ */
+export declare function composeSubjects(subjects: readonly SubjectComposition[]): Composition;
+//# sourceMappingURL=composition.d.ts.map