@variance-authority/core 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,79 @@
+# @variance-authority/core
+
+## 0.1.0
+
+### Minor Changes
+
+- 5c34e6d: Say which input moved, not just which tag did
+  
+  `partingOf(baseline, candidate)` climbs from a set of deltas to the component
+  boundary that owns them and names the input that carried the decision:
+  `Cart chose differently — useState #0 moved`, with `Summary` reported as having
+  been handed a different `expanded` and hanging under that line as a
+  manifestation rather than as a second finding. `explainParting` renders that
+  as lines. Two runs of one page that differ in a `<p>` where the other has a
+  `<span>` previously produced a structural delta and nothing to say about it;
+  the tag is now the symptom and the hook cell is the report.
+  
+  `holdingOf` from `@variance-authority/react` supplies the evidence — props,
+  context values and hook cells as digests, per boundary, including
+  `useSyncExternalStore` snapshots so a store that moved outside React is
+  distinguished from a component that decided differently on its own. Values are
+  never carried, only digests, and a holding reaches no hash: `renderHash`,
+  `structureHash`, `styleHash`, band-exact component digests and
+  `componentInstances` are all unmoved by it, the same bargain `styleProvenance`
+  makes. `collect` in `@variance-authority/dom` takes `holdingOf` as a
+  caller-supplied reader, opt in separately from `wiringOf`, and `capture` in
+  `@variance-authority/unit-test` now accepts `provenanceOf`, `wiringOf` and
+  `holdingOf` so a unit test can read one.
+  
+  A boundary whose own input could not be read is reported as `unread` and never
+  as nondeterminism: `undetermined` is reserved for a component whose every input
+  was read and agreed. A wrapper that roots a component boundary no longer
+  collapses, because collapsing it discarded the holding — the cost is that a run
+  reading holdings keeps wrappers a run without them removes, which is why both
+  sides of a comparison must be read the same way.
+  
+  A component that ran no hooks is read as having run none, rather than as
+  unreadable. React writes `_debugHookTypes = null` on every fiber and fills it on
+  the first hook call, so the property's absence is the only silence — and
+  collapsing the two reported the one shape most worth calling nondeterministic, a
+  component with no props and no hooks that renders differently twice, as
+  something nothing could be said about.
+  
+  `PartedBoundary.moved` names the properties the owned deltas named — `color`,
+  `padding-top`, `width` — and `explainParting` spends them on the delta line.
+  That is the last joint of the chain the rungs climb: a hook cell moved, a prop
+  carried it down, and this is what the prop turned into on the page. A count and
+  a band stop one link short of what somebody chasing a visual regression is
+  trying to name.
+  
+  `Parting.slice` answers the question asked before which input moved: is this
+  worth opening. Three facts are read independently — did the component tree
+  move, did any input move, did the output move — and the combinations collapse
+  to six sentences. `refactor` is the one that pays for the rest: a component
+  tree that moved while the page did not is the receipt a refactor never gets,
+  since a pixel differ can say the screenshots match and nothing about what was
+  rewritten underneath. `flake` is `settled`'s opposite number and is refused on
+  silence — a run that read no boundary reports `unread`, never `flake`.
+  
+  `explainParting` leads with that line, and stops enumerating manifestations
+  past three: one input at a fork can put a boundary on every component beneath
+  it, and nine lines carrying one decision bury the one line worth reading.
+  
+  The whole layer is documented in `docs/parting.md`: the six slices, the seven
+  rungs, what a holding carries and what it deliberately does not.
+
+### Patch Changes
+
+- e8fee66: Refuse a value whose state is not in its own enumerable keys.
+  
+  `shapeValue` documented a `Date` as refused and encoded it instead. `typeof`
+  answers `object`, `Object.entries` answers empty, and the canonical text came
+  out `{}` — so a snapshot holding a timestamp addressed to the digest of an empty
+  object, and a later run comparing a different timestamp reported unchanged. The
+  same hole swallowed `Map`, `Set`, `URL`, and `RegExp`.
+  
+  An object with no own enumerable keys and a prototype other than `Object`'s is
+  now refused by name at its pointer. A genuinely empty object is still a value,
+  and an instance carrying its own fields still serializes them.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Machine Garden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+<p align="center"><img src="./mark.svg" alt="Variance Authority mark" width="72"></p>
+
+# @variance-authority/core
+
+> The Variance Authority format, rules, comparison, attribution and verdicts. Pure data in, pure data out, no DOM and no I/O.
+
+A **subject** is whatever is under test — a component, a page, or a plain
+value. A **capture** is the raw material a collector records from it once,
+before anything is compared. Collectors extract captures; this package
+normalizes and adjudicates them, and never captures anything itself.
+
+```bash
+npm install --save-dev @variance-authority/core
+```
+## Use this package when
+
+Install `@variance-authority/core` when the input is already produced: a
+capture, a semantic snapshot, a render document (serialized subject markup,
+ready to be rasterized elsewhere), a raster mask (`ChangeMask`: a per-pixel
+changed/unchanged bitmap, not an image), or a plain value. The package does
+not collect a DOM, read PNG bytes, launch a renderer, or select a test
+runner — for that, install `@variance-authority/dom` for a live DOM,
+`@variance-authority/react` for React provenance (the chain of component
+ownership attached to each node), and `@variance-authority/png` when the
+input is a PNG.
+
+## Entrypoints
+
+Seven groups. Five of them are the order an answer travels through; `core/plan`
+and `core/relate` sit outside that line, because both are asked *before* anything
+is captured — one decides which baselines the run can reach at all, the other
+decides which subjects are worth reaching for. The default entrypoint is all
+seven and is what most callers want.
+
+| entrypoint | holds |
+|---|---|
+| `core/format` | what a subject *is*: capture, snapshot, document, identity, hashing |
+| `core/rules` | the versioned opinions: allowlist, applicability, cascade, canonicalization |
+| `core/compare` | two snapshots become deltas — and **no verdict** |
+| `core/attribute` | a position becomes a component becomes a file |
+| `core/judge` | policy: verdicts, intent claims, ignores, the docket a reader is handed |
+| `core/plan` | the whole configuration of a run — profile, ruleset version, viewport, policy, interventions — as one value, plus the identity digest derived from it |
+| `core/relate` | what rests on what: a file graph in adjacency form, the components a change reaches, and a closure digest over each one |
+
+Three terms recur across those groups. A **profile** records what a collector
+was capable of observing — jsdom sees structure and declared style, chromium
+adds layout and pixels. An **identity** is the content hash that addresses a
+result; two runs are comparable only when their identities match. A
+**verdict** is one of six words this package will commit to: `unchanged`,
+`inherited`, `authorized`, `needs-review`, `violation`, `unexplained`.
+
+The groups exist for callers who genuinely want one. Somebody implementing the
+capture format for a renderer this project has never met needs `core/format` and
+would be misled by everything else. Somebody deciding where a baseline is stored,
+or whether two runs may be compared at all, needs `core/plan` and nothing else:
+the digest it derives is the address, so changing any part of the plan changes
+which baselines the run can see.
+
+## Comparison and policy
+
+`compare` says **what moved**. `judge` says **whether anyone should mind**.
+
+Between them sits `partingOf`, which says **which input moved**. Given two
+snapshots carrying holdings it walks the component boundaries for the shallowest
+one whose inputs agreed and whose output did not, and reports that as the origin
+— a moved prop, a context, an external store, or a hook cell by call position.
+It leads with a slice (`variation`, `flake`, `refactor`, `absorbed`, `settled`,
+`unread`) so a reader knows whether to open the rest, and `explainParting` turns
+the whole thing into lines a person reads.
+
+## Smallest working path: compare a value
+
+Value comparison needs no host setup and returns paths and fingerprints, not a
+pass/fail verdict:
+
+```ts
+import { compareValues, shapeValue } from '@variance-authority/core';
+
+const before = shapeValue({ rows: [{ id: 'a', total: 10 }] }, {
+  arrayKey: { '/rows': 'id' },
+});
+const after = shapeValue({ rows: [{ id: 'a', total: 12 }] }, {
+  arrayKey: { '/rows': 'id' },
+});
+
+const deltas = compareValues(before, after);
+console.log(deltas[0]?.pointer);                     // /rows/a/total
+```
+
+For a rendered subject, the same package receives captures from a collector:
+
+```ts
+import { attributeRegions, diffSnapshots, isolateRegions, normalize } from '@variance-authority/core';
+
+const before = normalize(capture);                   // supplied by a collector
+const after = normalize(recapture);
+const diff = diffSnapshots(before, after);           // deltas, roots, no verdict
+
+// `mask` is a ChangeMask from the raster tier. Core never opens an image.
+const places = isolateRegions(mask, { cell: 8 });    // pixels → regions
+const named = attributeRegions(places.regions, after, { scale: 2 });
+```
+
+The value example prints a JSON Pointer for the changed field. The rendered path
+returns semantic roots and, when a raster mask is supplied, regions attributed to
+the candidate snapshot. A caller still chooses policy and a verdict in
+`core/judge` or in its own runner.
+
+`scale` is device pixels per CSS pixel, it is **required**, and it has no default
+on purpose: a 2x screenshot attributed at 1x lands every region in the top-left
+quadrant and names the wrong component for each — a full, plausible, entirely
+wrong report. That last step is where regions become components and files.
+
+The options that change scope are explicit at the call site:
+
+| call | useful controls |
+|---|---|
+| `normalize` | `collapseWrappers` removes layout-only wrapper boundaries, `digestText` includes text content, and `sourceRoot` relativizes source locations |
+| `isolateRegions` / `attributeRegions` | `cell` and `limit` bound mask work; `origin` and `containment` describe the coordinate origin and how much a node must contain a region |
+| `fingerprintOfMask` | `grid` controls the shape sample and `coverage` controls the minimum occupied share |
+| `compareLocales` / ignore validation | `slack` permits a declared locale distance; `sites` supplies resolved ignore locations and `now` evaluates expiry |
+| `buildDocket` / dependency reach | `sampleSize` limits review examples and `through` selects graph edge kinds |
+| report summaries | `source` maps component names to files when `summarizeAdjudication` or `summarizeFindings` needs an actionable path |
+| screenshot stabilization | `animations` and `caret` are explicit intervention settings; omitted means the caller did not assert either intervention |
+
+### A subject that was never rendered
+
+`shapeValue(value, options)` is the same treatment for a value — an API
+response, a generated schema, a route table. It canonicalizes (keys sorted,
+numbers written portably, `undefined` omitted), addresses the text by content,
+and returns a `CapturedValue`; `compareValues` turns two of them into deltas
+carrying a JSON Pointer and a fingerprint, and — like everything else here — no
+verdict.
+
+```ts
+import { shapeValue, compareValues } from '@variance-authority/core';
+
+const baseline = shapeValue(before, { arrayKey: { '/rows': 'id' } });
+const deltas = compareValues(baseline, shapeValue(after, { arrayKey: { '/rows': 'id' } }));
+```
+
+`drop` records a pointer's value as present without comparing it, `replace` puts
+a token you choose in its place, and `arrayKey` says which member identifies a
+row — the difference between *one row was added* and *two thousand rows moved*.
+Two more options describe the value rather than shape it: `dialect` is how a
+reader will interpret the text later (`'json'` by default, `'openapi'` and
+`'graphql'` being the ones with detectors), and `generator` names what emitted
+it. Neither reaches the digest, so declaring a dialect does not orphan a
+baseline.
+
+Non-data throws, naming the pointer. A function, a `Date`, a `bigint` or a
+non-finite number cannot be canonical text, and dropping one silently puts a key
+in the record that the next run reads as removed.
+
+Rendered comparisons also throw when the subjects or observation profiles differ.
+
+## What it refuses
+
+**Absent is not empty.** Not measured, measured as zero, and unobservable are
+three states, and collapsing any two produces a pass nobody earned. A **band**
+(the frequency category a change falls into — `a11y`, `geometry`, `token`,
+`content`, `texture`, rarest to noisiest) that a profile cannot see reports
+`UNOBSERVED`, which the type system will not let you spell the same way as a
+pass.
+
+**Two results whose identities differ are `incomparable`, never `different`.**
+A difference in conditions reported as a difference in the product is a
+confident wrong answer, and the confidence is what makes it expensive.
+

package/dist/artifact.d.ts

@@ -0,0 +1,47 @@
+import type { SourceIndex } from './attribute/source.js';
+import type { AccessibilitySnapshot, CapturedValue, Raster, RenderDocument, SemanticSnapshot, SubjectRef } from './format/index.js';
+/**
+ * Material already captured from a host, before retention or reporting.
+ *
+ * Three arms, and the third is the one that is not a rendering at all: a value
+ * has no viewport, no placement and nothing to paint, and it reaches the same
+ * attribution path as the other two (ADR-0044). Every existing reader narrows
+ * with `=== 'document'`, so a value arm is not a compile error anywhere — which
+ * means each of those readers owes an explicit refusal rather than a silent drop.
+ */
+export type CaptureMaterial = {
+    readonly kind: 'document';
+    readonly document: RenderDocument;
+} | {
+    readonly kind: 'raster';
+    readonly raster: Raster;
+} | {
+    readonly kind: 'value';
+    readonly value: CapturedValue;
+};
+/**
+ * The acquisition boundary shared by host adapters.
+ *
+ * The material decides whether a renderer is needed. Semantic and source
+ * evidence stay beside it so an in-place raster and a deferred document reach
+ * the same attribution path without inventing host-specific result types.
+ */
+export interface CaptureArtifact {
+    readonly artifactVersion: 1;
+    readonly subject: SubjectRef;
+    readonly material: CaptureMaterial;
+    readonly snapshot?: SemanticSnapshot;
+    /** Browser-native accessibility evidence from the same stabilized mount. */
+    readonly accessibility?: AccessibilitySnapshot;
+    readonly source?: SourceIndex;
+    readonly stabilization?: readonly string[];
+    readonly attempt?: {
+        readonly retry: number;
+        readonly repeat: number;
+        readonly shard?: {
+            readonly index: number;
+            readonly total: number;
+        };
+    };
+}
+//# sourceMappingURL=artifact.d.ts.map

package/dist/artifact.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=artifact.js.map

package/dist/artifact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact.js","sourceRoot":"","sources":["../src/artifact.ts"],"names":[],"mappings":"","sourcesContent":["import type { SourceIndex } from './attribute/source.js';\nimport type {\n  AccessibilitySnapshot,\n  CapturedValue,\n  Raster,\n  RenderDocument,\n  SemanticSnapshot,\n  SubjectRef,\n} from './format/index.js';\n\n/**\n * Material already captured from a host, before retention or reporting.\n *\n * Three arms, and the third is the one that is not a rendering at all: a value\n * has no viewport, no placement and nothing to paint, and it reaches the same\n * attribution path as the other two (ADR-0044). Every existing reader narrows\n * with `=== 'document'`, so a value arm is not a compile error anywhere — which\n * means each of those readers owes an explicit refusal rather than a silent drop.\n */\nexport type CaptureMaterial =\n  | { readonly kind: 'document'; readonly document: RenderDocument }\n  | { readonly kind: 'raster'; readonly raster: Raster }\n  | { readonly kind: 'value'; readonly value: CapturedValue };\n\n/**\n * The acquisition boundary shared by host adapters.\n *\n * The material decides whether a renderer is needed. Semantic and source\n * evidence stay beside it so an in-place raster and a deferred document reach\n * the same attribution path without inventing host-specific result types.\n */\nexport interface CaptureArtifact {\n  readonly artifactVersion: 1;\n  readonly subject: SubjectRef;\n  readonly material: CaptureMaterial;\n  readonly snapshot?: SemanticSnapshot;\n  /** Browser-native accessibility evidence from the same stabilized mount. */\n  readonly accessibility?: AccessibilitySnapshot;\n  readonly source?: SourceIndex;\n  readonly stabilization?: readonly string[];\n  readonly attempt?: {\n    readonly retry: number;\n    readonly repeat: number;\n    readonly shard?: { readonly index: number; readonly total: number };\n  };\n}\n"]}

package/dist/attribute/because.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The one sentence a movement carries, written once for both readers.
+ *
+ * Every rung ends in prose because the category is not the answer — *upstream*
+ * tells a reviewer nothing, `ProductCard` was edited and reaches it through
+ * `Card` sends them to a file. The sentence is written here, shipped to the
+ * terminal and to the review page, and rendered rather than rewritten at the far
+ * end: a second sentence composed for the web is a second thing that can
+ * disagree with the first, and the disagreement would be between a reviewer's
+ * screen and their CI log.
+ *
+ * Names the sentence claims things about are wrapped in backticks. That is for
+ * the terminal, and the page turns each pair into `code` rather than reprinting
+ * the punctuation.
+ */
+import type { Site } from './composition.js';
+import type { Ancestor, Evidence } from './movement.js';
+/**
+ * The upstream sentence, which is the one a reviewer acts on.
+ *
+ * It says three things and the third is the reason the first two are worth
+ * printing: an edited component reaches this one, this one's own file is not in
+ * the change set, and therefore what moved here is what it was handed. Every
+ * rung above this has already been tried, so *its own code* and *a token it
+ * reads* are both ruled out by the time this speaks.
+ */
+export declare function becauseUpstream(ancestor: Ancestor): string;
+/**
+ * Why nothing explains it, and how much the suite could say about that.
+ *
+ * The three endings are three different findings and were one sentence. An empty
+ * control group has two causes — the component renders nowhere else with these
+ * inputs, or it renders elsewhere and moved in every one of them — and they point
+ * opposite ways. The first is a suite with nothing to compare against. The second
+ * *is* the comparison, and a component that moved in all six of its renders with
+ * no file, token or ancestor behind it is the strongest unexplained this ladder
+ * can produce.
+ */
+export declare function unexplainedBecause(movement: {
+    readonly component: string;
+    readonly held: readonly Site[];
+}, considered: number, evidence: Evidence): string;
+//# sourceMappingURL=because.d.ts.map

package/dist/attribute/because.js

@@ -0,0 +1,64 @@
+/**
+ * The one sentence a movement carries, written once for both readers.
+ *
+ * Every rung ends in prose because the category is not the answer — *upstream*
+ * tells a reviewer nothing, `ProductCard` was edited and reaches it through
+ * `Card` sends them to a file. The sentence is written here, shipped to the
+ * terminal and to the review page, and rendered rather than rewritten at the far
+ * end: a second sentence composed for the web is a second thing that can
+ * disagree with the first, and the disagreement would be between a reviewer's
+ * screen and their CI log.
+ *
+ * Names the sentence claims things about are wrapped in backticks. That is for
+ * the terminal, and the page turns each pair into `code` rather than reprinting
+ * the punctuation.
+ */
+/**
+ * The upstream sentence, which is the one a reviewer acts on.
+ *
+ * It says three things and the third is the reason the first two are worth
+ * printing: an edited component reaches this one, this one's own file is not in
+ * the change set, and therefore what moved here is what it was handed. Every
+ * rung above this has already been tried, so *its own code* and *a token it
+ * reads* are both ruled out by the time this speaks.
+ */
+export function becauseUpstream(ancestor) {
+    const reaches = ancestor.through.length === 0 ? 'mounts it' : `reaches it through ${chain(ancestor.through)}`;
+    return (`\`${ancestor.name}\` was edited and ${reaches}; nothing edited its own file, ` +
+        `so it moved on what it was given`);
+}
+/** The components in between, named while there are few enough to be worth naming. */
+function chain(through) {
+    const named = through.map((name) => `\`${name}\``);
+    if (named.length === 1)
+        return named[0] ?? '';
+    if (named.length > 3)
+        return `${named.slice(0, 3).join(', ')} and ${String(named.length - 3)} more`;
+    return `${named.slice(0, -1).join(', ')} and ${named[named.length - 1] ?? ''}`;
+}
+/**
+ * Why nothing explains it, and how much the suite could say about that.
+ *
+ * The three endings are three different findings and were one sentence. An empty
+ * control group has two causes — the component renders nowhere else with these
+ * inputs, or it renders elsewhere and moved in every one of them — and they point
+ * opposite ways. The first is a suite with nothing to compare against. The second
+ * *is* the comparison, and a component that moved in all six of its renders with
+ * no file, token or ancestor behind it is the strongest unexplained this ladder
+ * can produce.
+ */
+export function unexplainedBecause(movement, considered, evidence) {
+    if (evidence.changed === undefined) {
+        return 'nothing was asked about what changed, so nothing here explains it — run with `--against` to reach the first rung';
+    }
+    const unexplained = 'no file, token or ancestor explains it, and';
+    if (considered === 0) {
+        return `${unexplained} it renders nowhere else in this run with these props to compare against`;
+    }
+    if (movement.held.length === 0) {
+        return `${unexplained} every other render of it with these props moved here too`;
+    }
+    return (`${unexplained} the same component with the same props held in ` +
+        `${movement.held.length} of ${considered} other place(s) in this run`);
+}
+//# sourceMappingURL=because.js.map

package/dist/attribute/because.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"because.js","sourceRoot":"","sources":["../../src/attribute/because.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,QAAkB;IAChD,MAAM,OAAO,GACX,QAAQ,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,sBAAsB,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;IAEhG,OAAO,CACL,KAAK,QAAQ,CAAC,IAAI,qBAAqB,OAAO,iCAAiC;QAC/E,kCAAkC,CACnC,CAAC;AACJ,CAAC;AAED,sFAAsF;AACtF,SAAS,KAAK,CAAC,OAA0B;IACvC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC;IACnD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9C,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,OAAO,CAAC;IACpG,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;AACjF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAwE,EACxE,UAAkB,EAClB,QAAkB;IAElB,IAAI,QAAQ,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACnC,OAAO,kHAAkH,CAAC;IAC5H,CAAC;IAED,MAAM,WAAW,GAAG,6CAA6C,CAAC;IAElE,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,GAAG,WAAW,0EAA0E,CAAC;IAClG,CAAC;IAED,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO,GAAG,WAAW,2DAA2D,CAAC;IACnF,CAAC;IAED,OAAO,CACL,GAAG,WAAW,kDAAkD;QAChE,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,OAAO,UAAU,6BAA6B,CACtE,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The one sentence a movement carries, written once for both readers.\n *\n * Every rung ends in prose because the category is not the answer — *upstream*\n * tells a reviewer nothing, `ProductCard` was edited and reaches it through\n * `Card` sends them to a file. The sentence is written here, shipped to the\n * terminal and to the review page, and rendered rather than rewritten at the far\n * end: a second sentence composed for the web is a second thing that can\n * disagree with the first, and the disagreement would be between a reviewer's\n * screen and their CI log.\n *\n * Names the sentence claims things about are wrapped in backticks. That is for\n * the terminal, and the page turns each pair into `code` rather than reprinting\n * the punctuation.\n */\n\nimport type { Site } from './composition.js';\nimport type { Ancestor, Evidence } from './movement.js';\n\n/**\n * The upstream sentence, which is the one a reviewer acts on.\n *\n * It says three things and the third is the reason the first two are worth\n * printing: an edited component reaches this one, this one's own file is not in\n * the change set, and therefore what moved here is what it was handed. Every\n * rung above this has already been tried, so *its own code* and *a token it\n * reads* are both ruled out by the time this speaks.\n */\nexport function becauseUpstream(ancestor: Ancestor): string {\n  const reaches =\n    ancestor.through.length === 0 ? 'mounts it' : `reaches it through ${chain(ancestor.through)}`;\n\n  return (\n    `\\`${ancestor.name}\\` was edited and ${reaches}; nothing edited its own file, ` +\n    `so it moved on what it was given`\n  );\n}\n\n/** The components in between, named while there are few enough to be worth naming. */\nfunction chain(through: readonly string[]): string {\n  const named = through.map((name) => `\\`${name}\\``);\n  if (named.length === 1) return named[0] ?? '';\n  if (named.length > 3) return `${named.slice(0, 3).join(', ')} and ${String(named.length - 3)} more`;\n  return `${named.slice(0, -1).join(', ')} and ${named[named.length - 1] ?? ''}`;\n}\n\n/**\n * Why nothing explains it, and how much the suite could say about that.\n *\n * The three endings are three different findings and were one sentence. An empty\n * control group has two causes — the component renders nowhere else with these\n * inputs, or it renders elsewhere and moved in every one of them — and they point\n * opposite ways. The first is a suite with nothing to compare against. The second\n * *is* the comparison, and a component that moved in all six of its renders with\n * no file, token or ancestor behind it is the strongest unexplained this ladder\n * can produce.\n */\nexport function unexplainedBecause(\n  movement: { readonly component: string; readonly held: readonly Site[] },\n  considered: number,\n  evidence: Evidence,\n): string {\n  if (evidence.changed === undefined) {\n    return 'nothing was asked about what changed, so nothing here explains it — run with `--against` to reach the first rung';\n  }\n\n  const unexplained = 'no file, token or ancestor explains it, and';\n\n  if (considered === 0) {\n    return `${unexplained} it renders nowhere else in this run with these props to compare against`;\n  }\n\n  if (movement.held.length === 0) {\n    return `${unexplained} every other render of it with these props moved here too`;\n  }\n\n  return (\n    `${unexplained} the same component with the same props held in ` +\n    `${movement.held.length} of ${considered} other place(s) in this run`\n  );\n}\n"]}

package/dist/attribute/boundary.d.ts

@@ -0,0 +1,191 @@
+import type { CanonicalValue } from '../format/canonical.js';
+import type { Rect } from '../format/capture.js';
+import type { Digest } from '../format/hash.js';
+import type { SemanticNode } from '../format/snapshot.js';
+/**
+ * Where one component's nodes stop and the next component's begin.
+ *
+ * Two relations run upward out of a rendered node and they are not the same
+ * relation. **Parent** is what is above it — React's `return` chain, the boxes
+ * it ended up inside. **Owner** is what rendered it — React's `_debugOwner`, the
+ * code that wrote the element. A layout wrapper is the parent of everything
+ * handed to it and the owner of none of it.
+ *
+ * Both are needed here, for different halves of the same answer:
+ *
+ * - **Parent decides nesting.** A boundary owns a contiguous region of the
+ *   document, and what encloses that region is a fact about the tree. Reading
+ *   the owner for this would produce a boundary set that is not a partition.
+ * - **Owner decides membership and naming.** A component's own content is what
+ *   *it* wrote. Content it was handed is a hole in its output — present, sized,
+ *   positioned by it, and authored somewhere else.
+ *
+ * Reading the parent for both — which is what a walk over `owners[0]` does — has
+ * two consequences, and they are the two shapes a design system is made of:
+ *
+ * - **A component that renders only components disappears.** It authors no host
+ *   node, so it is never any node's nearest enclosing composite, so it is a
+ *   boundary nowhere. That is every variant wrapper (`DangerButton` returning a
+ *   `Button`) and every page-level assembly. The information is not missing —
+ *   the composite is in the chain, one rung up — it is discarded by reading only
+ *   the head of it. {@link boundaries} enters every rung the chain crosses.
+ * - **A container absorbs its caller's content.** `Card` renders one `div` and
+ *   whatever it was given; hashed by enclosure, its digest moves whenever a
+ *   caller passes something else, while its props digest — which excludes
+ *   `children` — says its inputs held. {@link shapeOf} names a child boundary
+ *   only when this component placed it, and leaves an anonymous hole otherwise.
+ *
+ * The owner half is a development-build artefact: React populates `_debugOwner`
+ * from `element._owner`, and a production bundle does not. Absent, both rules
+ * degrade to naming everything, which is the enclosure answer — coarser, never
+ * wrong in a new direction.
+ *
+ * Nothing here is exported from the package. The callers are siblings.
+ */
+/** A node whose provenance chain broke. Not a filler category; see `RootKind`. */
+export declare const UNATTRIBUTED = "(unattributed)";
+/**
+ * Properties whose *computed* value is layout output rather than authored input.
+ *
+ * The distinction this list exists for is not stylistic. Under a profile with a
+ * layout engine the snapshot carries the engine's resolved values, so a block
+ * element's computed `height` is whatever its contents made it — and a button
+ * two levels down growing by six pixels moves the computed height of every
+ * ancestor. Hashed as *style*, that reports every enclosing component as having
+ * changed, which is precisely the "area ranks the displaced above the displacer"
+ * failure the cause hashes exist to fix, arriving through a different door.
+ *
+ * Measured on `cases/storybook-case`: one padding edit inside `Button` made
+ * `Tokens`, `Stack`, `Card` and the unattributed root all report a moved style
+ * hash, so *every* component in every affected story was named a cause.
+ *
+ * They are folded into `geometry` instead, where "this component's box is a
+ * different size" already belongs and where it correctly does not make a cause.
+ * Under a profile *without* layout there are no computed values, so these are
+ * authored declarations like any other and stay in `style` — that tier has no
+ * `geometry` digest to move them to, and a declared `width: 100px` really is the
+ * component's own content.
+ */
+export declare const LAYOUT_OUTPUT: ReadonlySet<string>;
+export interface Boundary {
+    readonly node: SemanticNode;
+    readonly component: string;
+    /** The enclosing boundary's component, absent on the subject root. */
+    readonly within?: string;
+    /** Boundaries between this one and the subject root. The root is `0`. */
+    readonly depth: number;
+    /**
+     * This component's rung in the node's ownership stack.
+     *
+     * Distinct from `depth`, which counts enclosing boundaries. They diverge
+     * wherever a subject root has no provenance: the `(unattributed)` container is
+     * a boundary at depth 0 holding a stack of one, and the application inside it
+     * starts again at rung 0 while sitting at depth 1.
+     */
+    readonly rung: number;
+    /**
+     * Digest of the props this boundary received, from its own `OwnerFrame`.
+     *
+     * Read at this rung rather than from `owners[0]`, which is the innermost
+     * component and belongs to whichever boundary is deepest at this node — the
+     * distinction only exists because several boundaries can share a root.
+     */
+    readonly props?: Digest;
+    /** The component whose JSX placed this one. Absent on a production build. */
+    readonly placedBy?: string;
+}
+/** Whether a node's own content belongs to this boundary rather than one below. */
+export declare function holds(boundary: Boundary, node: SemanticNode): boolean;
+/**
+ * Every boundary root in the subject, in document order.
+ *
+ * A boundary opens at each rung a node's ownership stack adds to its parent's,
+ * plus the subject root. Several can open at one node — a page assembly, the
+ * card it returns and the stack inside that card all begin at the same element —
+ * which is what makes a component that renders only components visible.
+ *
+ * Collected in a separate pre-order pass rather than discovered during hashing,
+ * so that instance order is document order exactly. Discovering them while
+ * walking would order them by boundary depth instead, and "the second instance"
+ * would mean something different in a nested tree.
+ */
+export declare function boundaries(root: SemanticNode): readonly Boundary[];
+export interface Shape {
+    readonly structure: CanonicalValue;
+    readonly semantics: CanonicalValue;
+    readonly text: CanonicalValue;
+    readonly style: CanonicalValue;
+    readonly geometry: CanonicalValue;
+    /**
+     * How the framework holds this boundary, per node that reports it.
+     *
+     * Its own band because it answers its own question. `structure` through
+     * `geometry` all read what the renderer produced; this reads what the
+     * component *is* — its hook shape, its wrappers, the contexts it subscribes
+     * to, the keys it is reconciled under. Two components can agree on all five
+     * content bands and disagree here, and when they do, they behave differently
+     * under every change that follows.
+     */
+    readonly wiring: CanonicalValue;
+    /**
+     * The box this boundary's root node occupies. Not part of any digest.
+     *
+     * Beside the digests rather than inside `geometry`, which is the whole subtree:
+     * this is the only thing on the record that can say a control grew eight pixels
+     * rather than merely stopped being what it was. `null` where nothing was laid out.
+     */
+    readonly box: Rect | null;
+    /** Child boundaries encountered, in document order. Not part of any digest. */
+    readonly renders: readonly string[];
+    /** Nodes this boundary owns, counting its own root. Not part of any digest. */
+    readonly nodes: number;
+    /**
+     * Custom properties this boundary's own nodes resolved through, sorted.
+     *
+     * Not part of any digest — the *values* are already inside `style`, and the
+     * names are carried beside it so a token that moved can be joined to the
+     * components that read it. Off the boundary rather than off the subject on
+     * purpose: every subject on a themed page resolves through every token in the
+     * theme, so a subject-level list names them all and explains nothing.
+     */
+    readonly tokens: readonly string[];
+}
+/**
+ * How a value that may carry a structural alias is rewritten before hashing.
+ *
+ * `undefined` for the per-name hashes, which have always hashed the alias the
+ * normalizer assigned and must keep doing so byte for byte. Supplied by the
+ * per-instance hashes, which need a boundary-local alias space — see
+ * {@link ./instances.js}, where the argument for it lives.
+ */
+export interface Rename {
+    readonly attribute: (name: string, value: string) => string;
+    readonly style: (value: string) => string;
+    readonly alias: (alias: string) => string;
+}
+/**
+ * One boundary's content, stopping at nested boundaries.
+ *
+ * Where a child belongs to another component, this records a placeholder rather
+ * than descending. That is the whole design: a component's hash moves when *its
+ * own* code changes, and what a child renders internally is not that. Hashing
+ * whole subtrees instead would move every ancestor on any leaf edit, and the
+ * page root would change on every commit.
+ *
+ * **The placeholder names the child only when this component placed it.** A
+ * component that wrote `<Stack>` owns that choice, and swapping it for a `<Card>`
+ * is its own change; a container that was handed a `<Stack>` chose nothing, and
+ * naming it would make the container's digest a function of its callers. So a
+ * slot is anonymous, and `Card` renders the same bytes on every page that uses
+ * it, whatever it was given. The cost is stated in ADR-0035: the *number* of
+ * slotted children still reaches the digest, so a caller passing three where it
+ * passed two moves the container.
+ *
+ * Falls back to naming every child where `_debugOwner` is absent, which is the
+ * enclosure answer this replaced.
+ *
+ * Paths are not hashed. A path is an address that shifts when an unrelated
+ * sibling is inserted, so hashing one reports a change nobody made.
+ */
+export declare function shapeOf(boundary: Boundary, layout: boolean, rename?: Rename): Shape;
+//# sourceMappingURL=boundary.d.ts.map