@variance-authority/core 0.1.0

package/dist/attribute/divergence.js

@@ -0,0 +1,152 @@
+import { explainParting } from '../compare/explain.js';
+import { boundarySnapshot } from '../compare/instance.js';
+import { partingOf } from '../compare/parting.js';
+import { movedBands } from './component-hash.js';
+/**
+ * Every props class that produced more than one rendering *from one input*.
+ *
+ * Three refusals, and all three are the same refusal: a props digest is not a
+ * complete statement of a component's inputs, so most pairs of renderings that
+ * share one are not a contradiction. Measured on `examples/todomvc` before the
+ * checks below existed, **eleven divergences were reported and all eleven were
+ * false** — which is what a finding built on an incomplete key looks like.
+ *
+ * **Unknown props are not shared props.** Instances whose provenance did not
+ * survive are not known to have received the same thing. Grouping them and
+ * reporting that they render differently manufactures a finding out of missing
+ * data, in a system where absent must never read as equal.
+ *
+ * **Renderings that co-occur in one subject are not alternatives.** A component
+ * whose nodes are interrupted by a nested boundary is walked as two boundaries
+ * with one owner frame, so one `TextField` becomes a label-shaped rendering and
+ * an input-shaped one under a single props digest. That is one instance in two
+ * pieces, and it is indistinguishable from two instances that genuinely disagree
+ * — so it is not reported. A contradiction is a component that renders as A
+ * *here* and as B *there*, never both at once.
+ *
+ * **Different children are different inputs.** `propsDigest` excludes `children`
+ * deliberately (see `digestableProps` in `@variance-authority/react`: folding the
+ * subtree in would make every ancestor's props move on any descendant edit, and
+ * §6.2's root/collateral rule could never fire). The consequence is that
+ * `<Card><Stack/></Card>` and `<Card><Text/></Card>` share a props digest, and
+ * calling their different output a contradiction blames the component for its
+ * caller. Two proxies for "the children differed" are available and both are
+ * required to be quiet: the child components mounted, and the boundary's own
+ * text — which is where a string child lands.
+ *
+ * What survives is narrow on purpose. A movement wrongly dismissed as
+ * `contradicted` is an explanation nobody can act on; the same movement left
+ * unexplained lands on the suspect shortlist, where a second reading settles it.
+ * The asymmetry is the whole reason these checks are here rather than in prose.
+ */
+export function divergencesOf(components, snapshots) {
+    const divergences = [];
+    for (const entry of components) {
+        for (const group of entry.classes) {
+            if (group.props === undefined || group.renderings.length < 2)
+                continue;
+            if (!fromOneInput(group.renderings))
+                continue;
+            // Union against the first rather than over every pair. A band moves here
+            // when the renderings do not all agree on its digest, and a field that
+            // disagrees anywhere disagrees with the first somewhere — so the two are
+            // the same set, and the mapping stays in `movedBands` where the sensitivity
+            // tier reads it.
+            const [first, ...rest] = group.renderings;
+            const bands = new Set();
+            for (const other of rest)
+                for (const band of movedBands(first, other))
+                    bands.add(band);
+            const partings = partingsOf(group.renderings, snapshots);
+            divergences.push({
+                component: entry.component,
+                props: group.props,
+                bands: [...bands],
+                renderings: group.renderings,
+                ...(partings === undefined ? {} : { partings }),
+            });
+        }
+    }
+    return divergences.sort((a, b) => byCodeUnit(a.component, b.component));
+}
+/**
+ * Read every rendering after the first against the first, for the moved input.
+ *
+ * Each site is lifted out of its subject and re-rooted at the component before
+ * the comparison — {@link boundarySnapshot}'s reason for existing. Comparing the
+ * two *subjects* instead would compare a receipt against a promo card, which is
+ * the difference the reader already knows about and not the one being asked.
+ *
+ * `undefined`, never `[]`, when no snapshot for the first rendering's subject was
+ * supplied: a run that was never handed the documents has not found the parting
+ * unexplainable, it has not looked.
+ */
+function partingsOf(renderings, snapshots) {
+    const first = liftFirstSite(renderings[0], snapshots);
+    if (first === undefined)
+        return undefined;
+    const found = [];
+    for (const [index, rendering] of renderings.entries()) {
+        if (index === 0)
+            continue;
+        const other = liftFirstSite(rendering, snapshots);
+        if (other === undefined)
+            continue;
+        found.push({ rendering: index, lines: explainParting(partingOf(first, other)) });
+    }
+    return found;
+}
+/**
+ * One rendering's first site, as a snapshot rooted at the component.
+ *
+ * The first site and not a chosen one: `sites` is ordered by subject then
+ * document position, so this is the same instance on every machine — which the
+ * report being a function of the plan requires.
+ */
+function liftFirstSite(rendering, snapshots) {
+    const site = rendering?.sites[0];
+    if (site === undefined)
+        return undefined;
+    const snapshot = snapshots.get(site.subject);
+    if (snapshot === undefined)
+        return undefined;
+    return boundarySnapshot(snapshot, site.path);
+}
+/**
+ * Whether a props class' renderings can be said to have had the same inputs.
+ *
+ * The two checks the props digest cannot make for itself — see `divergencesOf`
+ * above for why each exists. Both are conservative in the same direction: they
+ * answer *no* whenever the run cannot tell, so what remains is a set of
+ * renderings that mounted the same children, said the same words, and still came
+ * out different, with no two of them observed in one subject.
+ */
+function fromOneInput(renderings) {
+    const [first, ...rest] = renderings;
+    if (first === undefined)
+        return false;
+    if (rest.some((other) => other.text !== first.text))
+        return false;
+    if (rest.some((other) => !sameOrder(other.renders, first.renders)))
+        return false;
+    const seen = new Set();
+    for (const rendering of renderings) {
+        for (const subject of new Set(rendering.sites.map((site) => site.subject))) {
+            if (seen.has(subject))
+                return false;
+            seen.add(subject);
+        }
+    }
+    return true;
+}
+function sameOrder(a, b) {
+    return a.length === b.length && a.every((value, index) => value === b[index]);
+}
+/**
+ * Code-unit order, never `localeCompare`, for `composition.ts`' reason: this
+ * output reaches a report that is committed and read back on another runner.
+ */
+function byCodeUnit(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+//# sourceMappingURL=divergence.js.map

package/dist/attribute/divergence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"divergence.js","sourceRoot":"","sources":["../../src/attribute/divergence.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Band } from '../compare/band.js';\nimport { explainParting } from '../compare/explain.js';\nimport { boundarySnapshot } from '../compare/instance.js';\nimport { partingOf } from '../compare/parting.js';\nimport type { Digest } from '../format/hash.js';\nimport type { SemanticSnapshot } from '../format/snapshot.js';\nimport { movedBands } from './component-hash.js';\nimport type { ComponentEntry, Rendering } from './composition.js';\n\n/**\n * The finding with no baseline in it, and the sentence that makes it actionable.\n *\n * Split out of `composition.ts` because it is the only part of the graph that\n * reads *documents*. Everything else there folds digests a run already computed;\n * this lifts two instances out of the pages they were found in and compares them\n * — which is the only way to say `color`, and the difference between a reader\n * knowing which subject to open and knowing what is waiting there.\n */\n\n/**\n * The same component, the same inputs, and more than one rendering. At one commit.\n *\n * Not a regression and not a comparison — there is no baseline anywhere in it.\n * It is a statement that the component's own inputs do not determine its output,\n * which is either a fact about the design (a token, a theme, an ancestor) or the\n * reading not being repeatable. `bands` says which kind of difference it is, in\n * the same vocabulary a sensitivity absorbs, so a divergence entirely inside a\n * band the subject relaxes is one a reader can dismiss without opening it.\n *\n * *Inputs*, not *props*, and the difference is the whole finding: a props digest\n * excludes `children` and the checks in `divergencesOf` are what close the gap.\n * A suite can legitimately produce none of these — `examples/todomvc` produces\n * exactly zero — and that is the correct answer for a suite in which nothing\n * renders two ways from one input, not a section to be filled.\n */\nexport interface Divergence {\n  readonly component: string;\n  readonly props?: Digest;\n  readonly bands: readonly Band[];\n  /** At least two, sorted by how many sites each has, widest first. */\n  readonly renderings: readonly Rendering[];\n\n  /**\n   * Why each rendering after the first parted from it.\n   *\n   * The half of this finding that used to be missing. \"`Price` rendered two ways\n   * from one props digest\" states the contradiction and stops there, leaving the\n   * reader to open two subjects and diff them by eye — which is the work the\n   * component graph was built to remove. These lines name the input: an\n   * ancestor's `color`, a context, a hook cell, or nothing readable at all.\n   *\n   * It is reachable here and nowhere else in the system, because a parting needs\n   * both sides read the same way and this is the only comparison where that is\n   * true by construction: both renderings come out of one run, off one collector,\n   * at one commit. A parting across two revisions has to reconcile two configs\n   * and two baselines first.\n   *\n   * Absent when the run supplied no snapshots to read — unknown, not \"nothing to\n   * say\" (ADR-0002). Shorter than `renderings.length - 1` when some rendering's\n   * site could not be lifted.\n   */\n  readonly partings?: readonly DivergenceParting[];\n}\n\n/** One rendering of a divergence, and why it parted from the first. */\nexport interface DivergenceParting {\n  /** Index into {@link Divergence.renderings}, always at least 1. */\n  readonly rendering: number;\n  /** `explainParting` output, comparing that rendering against the first. */\n  readonly lines: readonly string[];\n}\n\n/**\n * Every props class that produced more than one rendering *from one input*.\n *\n * Three refusals, and all three are the same refusal: a props digest is not a\n * complete statement of a component's inputs, so most pairs of renderings that\n * share one are not a contradiction. Measured on `examples/todomvc` before the\n * checks below existed, **eleven divergences were reported and all eleven were\n * false** — which is what a finding built on an incomplete key looks like.\n *\n * **Unknown props are not shared props.** Instances whose provenance did not\n * survive are not known to have received the same thing. Grouping them and\n * reporting that they render differently manufactures a finding out of missing\n * data, in a system where absent must never read as equal.\n *\n * **Renderings that co-occur in one subject are not alternatives.** A component\n * whose nodes are interrupted by a nested boundary is walked as two boundaries\n * with one owner frame, so one `TextField` becomes a label-shaped rendering and\n * an input-shaped one under a single props digest. That is one instance in two\n * pieces, and it is indistinguishable from two instances that genuinely disagree\n * — so it is not reported. A contradiction is a component that renders as A\n * *here* and as B *there*, never both at once.\n *\n * **Different children are different inputs.** `propsDigest` excludes `children`\n * deliberately (see `digestableProps` in `@variance-authority/react`: folding the\n * subtree in would make every ancestor's props move on any descendant edit, and\n * §6.2's root/collateral rule could never fire). The consequence is that\n * `<Card><Stack/></Card>` and `<Card><Text/></Card>` share a props digest, and\n * calling their different output a contradiction blames the component for its\n * caller. Two proxies for \"the children differed\" are available and both are\n * required to be quiet: the child components mounted, and the boundary's own\n * text — which is where a string child lands.\n *\n * What survives is narrow on purpose. A movement wrongly dismissed as\n * `contradicted` is an explanation nobody can act on; the same movement left\n * unexplained lands on the suspect shortlist, where a second reading settles it.\n * The asymmetry is the whole reason these checks are here rather than in prose.\n */\nexport function divergencesOf(\n  components: readonly ComponentEntry[],\n  snapshots: ReadonlyMap<string, SemanticSnapshot>,\n): readonly Divergence[] {\n  const divergences: Divergence[] = [];\n\n  for (const entry of components) {\n    for (const group of entry.classes) {\n      if (group.props === undefined || group.renderings.length < 2) continue;\n      if (!fromOneInput(group.renderings)) continue;\n\n      // Union against the first rather than over every pair. A band moves here\n      // when the renderings do not all agree on its digest, and a field that\n      // disagrees anywhere disagrees with the first somewhere — so the two are\n      // the same set, and the mapping stays in `movedBands` where the sensitivity\n      // tier reads it.\n      const [first, ...rest] = group.renderings;\n      const bands = new Set<Band>();\n      for (const other of rest) for (const band of movedBands(first!, other)) bands.add(band);\n\n      const partings = partingsOf(group.renderings, snapshots);\n\n      divergences.push({\n        component: entry.component,\n        props: group.props,\n        bands: [...bands],\n        renderings: group.renderings,\n        ...(partings === undefined ? {} : { partings }),\n      });\n    }\n  }\n\n  return divergences.sort((a, b) => byCodeUnit(a.component, b.component));\n}\n\n/**\n * Read every rendering after the first against the first, for the moved input.\n *\n * Each site is lifted out of its subject and re-rooted at the component before\n * the comparison — {@link boundarySnapshot}'s reason for existing. Comparing the\n * two *subjects* instead would compare a receipt against a promo card, which is\n * the difference the reader already knows about and not the one being asked.\n *\n * `undefined`, never `[]`, when no snapshot for the first rendering's subject was\n * supplied: a run that was never handed the documents has not found the parting\n * unexplainable, it has not looked.\n */\nfunction partingsOf(\n  renderings: readonly Rendering[],\n  snapshots: ReadonlyMap<string, SemanticSnapshot>,\n): readonly DivergenceParting[] | undefined {\n  const first = liftFirstSite(renderings[0], snapshots);\n  if (first === undefined) return undefined;\n\n  const found: DivergenceParting[] = [];\n  for (const [index, rendering] of renderings.entries()) {\n    if (index === 0) continue;\n    const other = liftFirstSite(rendering, snapshots);\n    if (other === undefined) continue;\n    found.push({ rendering: index, lines: explainParting(partingOf(first, other)) });\n  }\n  return found;\n}\n\n/**\n * One rendering's first site, as a snapshot rooted at the component.\n *\n * The first site and not a chosen one: `sites` is ordered by subject then\n * document position, so this is the same instance on every machine — which the\n * report being a function of the plan requires.\n */\nfunction liftFirstSite(\n  rendering: Rendering | undefined,\n  snapshots: ReadonlyMap<string, SemanticSnapshot>,\n): SemanticSnapshot | undefined {\n  const site = rendering?.sites[0];\n  if (site === undefined) return undefined;\n  const snapshot = snapshots.get(site.subject);\n  if (snapshot === undefined) return undefined;\n  return boundarySnapshot(snapshot, site.path);\n}\n\n/**\n * Whether a props class' renderings can be said to have had the same inputs.\n *\n * The two checks the props digest cannot make for itself — see `divergencesOf`\n * above for why each exists. Both are conservative in the same direction: they\n * answer *no* whenever the run cannot tell, so what remains is a set of\n * renderings that mounted the same children, said the same words, and still came\n * out different, with no two of them observed in one subject.\n */\nfunction fromOneInput(renderings: readonly Rendering[]): boolean {\n  const [first, ...rest] = renderings;\n  if (first === undefined) return false;\n\n  if (rest.some((other) => other.text !== first.text)) return false;\n  if (rest.some((other) => !sameOrder(other.renders, first.renders))) return false;\n\n  const seen = new Set<string>();\n  for (const rendering of renderings) {\n    for (const subject of new Set(rendering.sites.map((site) => site.subject))) {\n      if (seen.has(subject)) return false;\n      seen.add(subject);\n    }\n  }\n\n  return true;\n}\n\nfunction sameOrder(a: readonly string[], b: readonly string[]): boolean {\n  return a.length === b.length && a.every((value, index) => value === b[index]);\n}\n\n/**\n * Code-unit order, never `localeCompare`, for `composition.ts`' reason: this\n * output reaches a report that is committed and read back on another runner.\n */\nfunction byCodeUnit(a: string, b: string): number {\n  return a < b ? -1 : a > b ? 1 : 0;\n}\n"]}

package/dist/attribute/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `@variance-authority/core/attribute` — from a position to a name to a file.
+ *
+ * The group that makes a difference actionable. Pixels cluster into regions,
+ * regions join the box tree, the tree knows which component produced each node,
+ * and the component resolves to a source location. The same machinery answers
+ * "which component is not holding still" and "which subjects cover this
+ * component".
+ *
+ * This is the answer to *"a pixel differ reports 1530 pixels changed"* — and the
+ * reason it is a group rather than a function is that every step of the journey
+ * is separately useful, and separately capable of refusing. `locateInstability`
+ * will not name a component for a difference that is beneath the semantic tier;
+ * `coverage` will not recommend deleting anything.
+ */
+export { locate } from './locate.js';
+export type { Location, LocationStep } from './locate.js';
+export { isolateRegions, subtractRegions, excludedBoxes } from './mask.js';
+export type { ChangeMask, DiffRegion, ExcludedBox, Isolation, IsolationOptions, Subtraction, } from './mask.js';
+export { attributeRegions, rankRegions } from './region.js';
+export type { AttributedRegion, AttributionOptions, RankedRegion } from './region.js';
+export { resolveSource, formatSource, indexSource, mergeSourceIndexes } from './source.js';
+export type { SourceIndex, SourceRef, Resolution } from './source.js';
+export { parseStackFrames, isVendorPath, writerLocationOf } from './stack.js';
+export type { StackFrame } from './stack.js';
+export { parseSourceMap, originalPositionFor, sourceMappingUrlOf, inlineSourceMapOf, } from './source-map.js';
+export type { SourceMap, OriginalPosition } from './source-map.js';
+export { createCallSiteResolver, locateProvenance, locateSites } from './call-site.js';
+export type { CallSiteResolver, CallSiteStats, FetchModule, LocatableSite } from './call-site.js';
+export { hashComponents, causesBetween, movedBands, movedBandsBetween, bandsBetween, UNATTRIBUTED, } from './component-hash.js';
+export type { BandDigests, ComponentBands, ComponentHash } from './component-hash.js';
+export { componentInstances, attributed } from './instances.js';
+export type { ComponentInstance } from './instances.js';
+export { composeSubjects } from './composition.js';
+export type { Composition, ComponentEntry, Echo, PropsClass, Rendering, Site, SubjectComposition, } from './composition.js';
+export type { Divergence, DivergenceParting } from './divergence.js';
+export { attributeMovement } from './movement.js';
+export type { Attribution, Cause, Evidence, Moved, Movement } from './movement.js';
+export { coverageOf, alsoCovering, summarizeCoverage } from './coverage.js';
+export type { Coverage, ComponentCoverage, SubjectCoverage, SubjectValue } from './coverage.js';
+export { locateInstability, summarizeInstability } from './instability.js';
+export type { Instability, InstabilityBand, UnstableLocation, UnstableProperty, } from './instability.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/attribute/index.js

@@ -0,0 +1,29 @@
+/**
+ * `@variance-authority/core/attribute` — from a position to a name to a file.
+ *
+ * The group that makes a difference actionable. Pixels cluster into regions,
+ * regions join the box tree, the tree knows which component produced each node,
+ * and the component resolves to a source location. The same machinery answers
+ * "which component is not holding still" and "which subjects cover this
+ * component".
+ *
+ * This is the answer to *"a pixel differ reports 1530 pixels changed"* — and the
+ * reason it is a group rather than a function is that every step of the journey
+ * is separately useful, and separately capable of refusing. `locateInstability`
+ * will not name a component for a difference that is beneath the semantic tier;
+ * `coverage` will not recommend deleting anything.
+ */
+export { locate } from './locate.js';
+export { isolateRegions, subtractRegions, excludedBoxes } from './mask.js';
+export { attributeRegions, rankRegions } from './region.js';
+export { resolveSource, formatSource, indexSource, mergeSourceIndexes } from './source.js';
+export { parseStackFrames, isVendorPath, writerLocationOf } from './stack.js';
+export { parseSourceMap, originalPositionFor, sourceMappingUrlOf, inlineSourceMapOf, } from './source-map.js';
+export { createCallSiteResolver, locateProvenance, locateSites } from './call-site.js';
+export { hashComponents, causesBetween, movedBands, movedBandsBetween, bandsBetween, UNATTRIBUTED, } from './component-hash.js';
+export { componentInstances, attributed } from './instances.js';
+export { composeSubjects } from './composition.js';
+export { attributeMovement } from './movement.js';
+export { coverageOf, alsoCovering, summarizeCoverage } from './coverage.js';
+export { locateInstability, summarizeInstability } from './instability.js';
+//# sourceMappingURL=index.js.map

package/dist/attribute/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/attribute/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAU3E,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG5D,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAG3F,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG9E,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGvF,OAAO,EACL,cAAc,EACd,aAAa,EACb,UAAU,EACV,iBAAiB,EACjB,YAAY,EACZ,YAAY,GACb,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGhE,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAanD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAGlD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAG5E,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC","sourcesContent":["/**\n * `@variance-authority/core/attribute` — from a position to a name to a file.\n *\n * The group that makes a difference actionable. Pixels cluster into regions,\n * regions join the box tree, the tree knows which component produced each node,\n * and the component resolves to a source location. The same machinery answers\n * \"which component is not holding still\" and \"which subjects cover this\n * component\".\n *\n * This is the answer to *\"a pixel differ reports 1530 pixels changed\"* — and the\n * reason it is a group rather than a function is that every step of the journey\n * is separately useful, and separately capable of refusing. `locateInstability`\n * will not name a component for a difference that is beneath the semantic tier;\n * `coverage` will not recommend deleting anything.\n */\n\nexport { locate } from './locate.js';\nexport type { Location, LocationStep } from './locate.js';\n\nexport { isolateRegions, subtractRegions, excludedBoxes } from './mask.js';\nexport type {\n  ChangeMask,\n  DiffRegion,\n  ExcludedBox,\n  Isolation,\n  IsolationOptions,\n  Subtraction,\n} from './mask.js';\n\nexport { attributeRegions, rankRegions } from './region.js';\nexport type { AttributedRegion, AttributionOptions, RankedRegion } from './region.js';\n\nexport { resolveSource, formatSource, indexSource, mergeSourceIndexes } from './source.js';\nexport type { SourceIndex, SourceRef, Resolution } from './source.js';\n\nexport { parseStackFrames, isVendorPath, writerLocationOf } from './stack.js';\nexport type { StackFrame } from './stack.js';\n\nexport {\n  parseSourceMap,\n  originalPositionFor,\n  sourceMappingUrlOf,\n  inlineSourceMapOf,\n} from './source-map.js';\nexport type { SourceMap, OriginalPosition } from './source-map.js';\n\nexport { createCallSiteResolver, locateProvenance, locateSites } from './call-site.js';\nexport type { CallSiteResolver, CallSiteStats, FetchModule, LocatableSite } from './call-site.js';\n\nexport {\n  hashComponents,\n  causesBetween,\n  movedBands,\n  movedBandsBetween,\n  bandsBetween,\n  UNATTRIBUTED,\n} from './component-hash.js';\nexport type { BandDigests, ComponentBands, ComponentHash } from './component-hash.js';\n\nexport { componentInstances, attributed } from './instances.js';\nexport type { ComponentInstance } from './instances.js';\n\nexport { composeSubjects } from './composition.js';\nexport type {\n  Composition,\n  ComponentEntry,\n  Echo,\n  PropsClass,\n  Rendering,\n  Site,\n  SubjectComposition,\n} from './composition.js';\n\nexport type { Divergence, DivergenceParting } from './divergence.js';\n\nexport { attributeMovement } from './movement.js';\nexport type { Attribution, Cause, Evidence, Moved, Movement } from './movement.js';\n\nexport { coverageOf, alsoCovering, summarizeCoverage } from './coverage.js';\nexport type { Coverage, ComponentCoverage, SubjectCoverage, SubjectValue } from './coverage.js';\n\nexport { locateInstability, summarizeInstability } from './instability.js';\nexport type {\n  Instability,\n  InstabilityBand,\n  UnstableLocation,\n  UnstableProperty,\n} from './instability.js';\n"]}

package/dist/attribute/instability.d.ts

@@ -0,0 +1,89 @@
+import { type Band } from '../compare/band.js';
+import { type SourceIndex } from './source.js';
+import type { NodePath, SemanticSnapshot } from '../format/snapshot.js';
+/**
+ * Where an instability lives, and what kind it is.
+ *
+ * Two captures of the *same* subject at the *same* commit are supposed to agree.
+ * When they do not, the usual response is to capture again until two agree and
+ * proceed — which works, and destroys the only evidence that existed. The
+ * disagreement was the finding. A run that resolves it by repetition has paid
+ * for the extra captures and learned nothing, and will pay again tomorrow.
+ *
+ * There is always a cause and always a place. A pixel comparison cannot supply
+ * either: it reports that some pixels moved, which is true of every cause
+ * equally. The semantic representation can, because the same two captures also
+ * carry structure, resolved declarations and geometry — so the question "what
+ * moved between two observations of one commit" has an answer in terms of a
+ * component, a declaration, and a file.
+ *
+ * That answer is what makes prevention possible instead of suppression. An
+ * animation caught mid-flight is fixed by pausing it, not by masking the region
+ * it happens to occupy this week; a clock is fixed at the fixture. Both fixes are
+ * at a source location, and both make every later run cheaper — the stabilisation
+ * captures stop being needed at all.
+ *
+ * The honest boundary: when nothing moved semantically and pixels still differ,
+ * the cause is below the box tree and **no component is responsible**. Naming one
+ * would be inventing a location. That case is reported as its own kind, because
+ * "we cannot see it from here" and "nothing is wrong" are different sentences.
+ */
+export type InstabilityBand = Band
+/** Pixels moved and the box tree did not. Rasterization, compositing, fonts. */
+ | 'sub-semantic' | 'none';
+export interface UnstableProperty {
+    readonly property: string;
+    readonly from?: string | undefined;
+    readonly to?: string | undefined;
+}
+export interface UnstableLocation {
+    readonly component: string;
+    readonly bands: readonly Band[];
+    readonly properties: readonly UnstableProperty[];
+    /** Landmark phrase, e.g. `main → list item 2 of 3`. */
+    readonly where?: string;
+    readonly path?: NodePath;
+    /** Custom property the moving value resolved through, when there is one. */
+    readonly token?: string;
+    readonly deltas: number;
+    /**
+     * A conservative reading of the *shape* of the evidence, not a conclusion.
+     *
+     * Present only where one shape fits and the others do not. Absent is the
+     * common case and is not a failure — the location and the moved declarations
+     * are the deliverable; this is a hint about where to look first.
+     */
+    readonly likely?: 'animation' | 'dynamic-content' | 'displacement';
+}
+export interface Instability {
+    readonly stable: boolean;
+    readonly band: InstabilityBand;
+    /** Ordered by how many deltas landed in each, widest first. */
+    readonly locations: readonly UnstableLocation[];
+    /** One sentence stating what moved and what that implies. */
+    readonly because: string;
+}
+/**
+ * Compare two observations of one subject that ought to be identical.
+ *
+ * `pixelsDiffer` is supplied by the caller when an image comparison was also
+ * taken. It is what separates "stable" from "unstable in a way this tier cannot
+ * see", and omitting it means the second answer is unavailable rather than
+ * assumed — a subject reported stable on the strength of a comparison nobody
+ * made would be the same false negative this system exists to refuse.
+ */
+export declare function locateInstability(before: SemanticSnapshot, after: SemanticSnapshot, options?: {
+    readonly pixelsDiffer?: boolean;
+}): Instability;
+/**
+ * The instability as the thing a person reads, with a file on the end.
+ *
+ * Same shape as every other report here: a cause per line, and a path an editor
+ * opens, because `Spinner` is an identifier and `src/ds/components.tsx:88` is an
+ * edit.
+ */
+export declare function summarizeInstability(instability: Instability, options?: {
+    readonly source?: SourceIndex;
+    readonly limit?: number;
+}): string;
+//# sourceMappingURL=instability.d.ts.map

package/dist/attribute/instability.js

@@ -0,0 +1,183 @@
+import { loudestBand } from '../compare/band.js';
+import { diffSnapshots } from '../compare/diff/index.js';
+import { formatSource, resolveSource } from './source.js';
+/** Properties whose movement is characteristic of something still animating. */
+const ANIMATED = new Set(['transform', 'opacity', 'filter', 'offset-distance', 'rotate', 'scale', 'translate']);
+/**
+ * Compare two observations of one subject that ought to be identical.
+ *
+ * `pixelsDiffer` is supplied by the caller when an image comparison was also
+ * taken. It is what separates "stable" from "unstable in a way this tier cannot
+ * see", and omitting it means the second answer is unavailable rather than
+ * assumed — a subject reported stable on the strength of a comparison nobody
+ * made would be the same false negative this system exists to refuse.
+ */
+export function locateInstability(before, after, options = {}) {
+    // `diffSnapshots` refuses a cross-subject or cross-profile comparison, which
+    // is the right failure here: two captures that are not of the same thing
+    // cannot be evidence about stability.
+    const diff = diffSnapshots(before, after);
+    if (diff.deltas.length === 0) {
+        if (options.pixelsDiffer === true) {
+            return {
+                stable: false,
+                band: 'sub-semantic',
+                locations: [],
+                because: 'two captures of the same subject are identical in structure, resolved style and ' +
+                    'geometry, and their images are not. The cause is below the box tree — glyph ' +
+                    'rasterization, compositing, or a font resolving differently — so no component is ' +
+                    'responsible and there is no source location to fix. This belongs to the ' +
+                    'environment key, not to the code',
+            };
+        }
+        return {
+            stable: true,
+            band: 'none',
+            locations: [],
+            because: options.pixelsDiffer === false
+                ? 'two captures of the same subject agree in structure, style, geometry and pixels'
+                : 'two captures of the same subject agree in structure, style and geometry; no image ' +
+                    'comparison was supplied, so sub-semantic movement is unobserved rather than absent',
+        };
+    }
+    const locations = group(diff.deltas);
+    return {
+        stable: false,
+        band: worst(diff.deltas.map((delta) => delta.band)),
+        locations,
+        because: sentence(locations, diff.deltas.length),
+    };
+}
+/**
+ * The instability as the thing a person reads, with a file on the end.
+ *
+ * Same shape as every other report here: a cause per line, and a path an editor
+ * opens, because `Spinner` is an identifier and `src/ds/components.tsx:88` is an
+ * edit.
+ */
+export function summarizeInstability(instability, options = {}) {
+    if (instability.stable)
+        return instability.because;
+    const limit = options.limit ?? 5;
+    const shown = instability.locations.slice(0, limit);
+    const lines = shown.map((location) => {
+        const file = options.source === undefined ? null : resolveSource(location.component, options.source);
+        const moved = location.properties
+            .slice(0, 3)
+            .map((property) => property.from === undefined && property.to === undefined
+            ? property.property
+            : `${property.property} ${property.from ?? '(absent)'} → ${property.to ?? '(absent)'}`);
+        return [
+            `  ${location.component} — ${location.deltas} delta(s) in ${location.bands.join(', ')}` +
+                (location.likely !== undefined ? ` [likely ${location.likely}]` : ''),
+            ...moved.map((line) => `      ${line}`),
+            location.properties.length > 3
+                ? `      +${location.properties.length - 3} more propert(y|ies) not listed`
+                : null,
+            location.where !== undefined ? `      in ${location.where}` : null,
+            location.token !== undefined ? `      through ${location.token}` : null,
+            file !== null ? `      ${formatSource(file)}` : null,
+        ]
+            .filter((line) => line !== null)
+            .join('\n');
+    });
+    return [
+        `[unstable] ${instability.because}`,
+        '',
+        ...lines,
+        ...(instability.locations.length > shown.length
+            ? [`  +${instability.locations.length - shown.length} more location(s) not listed`]
+            : []),
+    ].join('\n');
+}
+function group(deltas) {
+    const byComponent = new Map();
+    for (const delta of deltas) {
+        // `createdBy` names the component whose JSX produced the node; `owners[0]`
+        // names the nearest enclosing one. Prefer the author, because a fix is made
+        // where the markup is written, not where it ends up.
+        const component = delta.createdBy ?? delta.owners?.[0]?.name ?? '(unattributed)';
+        const entry = byComponent.get(component) ?? {
+            bands: new Set(),
+            properties: new Map(),
+            kinds: new Set(),
+            count: 0,
+        };
+        entry.bands.add(delta.band);
+        entry.kinds.add(delta.kind);
+        entry.count += 1;
+        // A whole-node delta — text, a role, a node appearing — carries no
+        // `property`. Reading its absence as "only geometry moved" would file a
+        // changing clock under displacement, so the kind is what is consulted and
+        // the property list is only ever additive.
+        if (delta.property !== undefined && !entry.properties.has(delta.property)) {
+            entry.properties.set(delta.property, {
+                property: delta.property,
+                from: delta.from,
+                to: delta.to,
+            });
+        }
+        if (entry.where === undefined && delta.where !== undefined)
+            entry.where = delta.where;
+        if (entry.path === undefined)
+            entry.path = delta.path;
+        if (entry.token === undefined && delta.token !== undefined)
+            entry.token = delta.token;
+        byComponent.set(component, entry);
+    }
+    return [...byComponent.entries()]
+        .map(([component, entry]) => {
+        const properties = [...entry.properties.values()];
+        return {
+            component,
+            bands: [...entry.bands],
+            properties,
+            ...(entry.where !== undefined ? { where: entry.where } : {}),
+            ...(entry.path !== undefined ? { path: entry.path } : {}),
+            ...(entry.token !== undefined ? { token: entry.token } : {}),
+            deltas: entry.count,
+            ...(guess(properties, entry.kinds) !== undefined
+                ? { likely: guess(properties, entry.kinds) }
+                : {}),
+        };
+    })
+        .sort((a, b) => b.deltas - a.deltas ||
+        (a.component < b.component ? -1 : a.component > b.component ? 1 : 0));
+}
+/**
+ * Read the shape of the evidence, and only where one reading fits.
+ *
+ * Deliberately narrow. A guess that fires on ambiguous evidence is worse than no
+ * guess: it sends someone to the wrong file with confidence, and the location
+ * and the moved declarations — which are facts — get read as if they carried the
+ * same certainty as the label.
+ */
+function guess(properties, kinds) {
+    // Content that rewrote itself between two captures of one commit. Checked
+    // before the others because a changing string also moves the box around it,
+    // and the text is the cause while the movement is its consequence.
+    if (kinds.has('text-changed'))
+        return 'dynamic-content';
+    if (properties.length === 0) {
+        // Geometry moved and this component declared nothing at all. Something
+        // upstream reflowed it, so the cause is elsewhere and this is only where it
+        // landed — which is worth saying, because it is the one reading that points
+        // away from the component being named.
+        const onlyGeometry = [...kinds].every((kind) => kind === 'rect-changed' || kind === 'node-moved');
+        return onlyGeometry ? 'displacement' : undefined;
+    }
+    if (properties.every((property) => ANIMATED.has(property.property)))
+        return 'animation';
+    return undefined;
+}
+function worst(bands) {
+    return loudestBand(bands) ?? 'none';
+}
+function sentence(locations, deltas) {
+    const named = locations.slice(0, 3).map((location) => location.component);
+    const rest = locations.length > named.length ? ` (+${locations.length - named.length} more)` : '';
+    return (`two captures of the same subject at the same commit disagree: ${deltas} delta(s) ` +
+        `across ${locations.length} component(s) — ${named.join(', ')}${rest}. ` +
+        'This is not noise to retry away; the location below is where it is caused');
+}
+//# sourceMappingURL=instability.js.map

package/dist/attribute/instability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instability.js","sourceRoot":"","sources":["../../src/attribute/instability.ts"],"names":[],"mappings":"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","sourcesContent":["import { loudestBand, type Band, type DeltaKind } from '../compare/band.js';\nimport type { Delta } from '../compare/diff/delta.js';\nimport { diffSnapshots } from '../compare/diff/index.js';\nimport { formatSource, resolveSource, type SourceIndex } from './source.js';\nimport type { NodePath, SemanticSnapshot } from '../format/snapshot.js';\n\n/**\n * Where an instability lives, and what kind it is.\n *\n * Two captures of the *same* subject at the *same* commit are supposed to agree.\n * When they do not, the usual response is to capture again until two agree and\n * proceed — which works, and destroys the only evidence that existed. The\n * disagreement was the finding. A run that resolves it by repetition has paid\n * for the extra captures and learned nothing, and will pay again tomorrow.\n *\n * There is always a cause and always a place. A pixel comparison cannot supply\n * either: it reports that some pixels moved, which is true of every cause\n * equally. The semantic representation can, because the same two captures also\n * carry structure, resolved declarations and geometry — so the question \"what\n * moved between two observations of one commit\" has an answer in terms of a\n * component, a declaration, and a file.\n *\n * That answer is what makes prevention possible instead of suppression. An\n * animation caught mid-flight is fixed by pausing it, not by masking the region\n * it happens to occupy this week; a clock is fixed at the fixture. Both fixes are\n * at a source location, and both make every later run cheaper — the stabilisation\n * captures stop being needed at all.\n *\n * The honest boundary: when nothing moved semantically and pixels still differ,\n * the cause is below the box tree and **no component is responsible**. Naming one\n * would be inventing a location. That case is reported as its own kind, because\n * \"we cannot see it from here\" and \"nothing is wrong\" are different sentences.\n */\n\nexport type InstabilityBand =\n  | Band\n  /** Pixels moved and the box tree did not. Rasterization, compositing, fonts. */\n  | 'sub-semantic'\n  | 'none';\n\nexport interface UnstableProperty {\n  readonly property: string;\n  readonly from?: string | undefined;\n  readonly to?: string | undefined;\n}\n\nexport interface UnstableLocation {\n  readonly component: string;\n  readonly bands: readonly Band[];\n  readonly properties: readonly UnstableProperty[];\n\n  /** Landmark phrase, e.g. `main → list item 2 of 3`. */\n  readonly where?: string;\n  readonly path?: NodePath;\n  /** Custom property the moving value resolved through, when there is one. */\n  readonly token?: string;\n\n  readonly deltas: number;\n\n  /**\n   * A conservative reading of the *shape* of the evidence, not a conclusion.\n   *\n   * Present only where one shape fits and the others do not. Absent is the\n   * common case and is not a failure — the location and the moved declarations\n   * are the deliverable; this is a hint about where to look first.\n   */\n  readonly likely?: 'animation' | 'dynamic-content' | 'displacement';\n}\n\nexport interface Instability {\n  readonly stable: boolean;\n  readonly band: InstabilityBand;\n  /** Ordered by how many deltas landed in each, widest first. */\n  readonly locations: readonly UnstableLocation[];\n  /** One sentence stating what moved and what that implies. */\n  readonly because: string;\n}\n\n/** Properties whose movement is characteristic of something still animating. */\nconst ANIMATED = new Set(['transform', 'opacity', 'filter', 'offset-distance', 'rotate', 'scale', 'translate']);\n\n/**\n * Compare two observations of one subject that ought to be identical.\n *\n * `pixelsDiffer` is supplied by the caller when an image comparison was also\n * taken. It is what separates \"stable\" from \"unstable in a way this tier cannot\n * see\", and omitting it means the second answer is unavailable rather than\n * assumed — a subject reported stable on the strength of a comparison nobody\n * made would be the same false negative this system exists to refuse.\n */\nexport function locateInstability(\n  before: SemanticSnapshot,\n  after: SemanticSnapshot,\n  options: { readonly pixelsDiffer?: boolean } = {},\n): Instability {\n  // `diffSnapshots` refuses a cross-subject or cross-profile comparison, which\n  // is the right failure here: two captures that are not of the same thing\n  // cannot be evidence about stability.\n  const diff = diffSnapshots(before, after);\n\n  if (diff.deltas.length === 0) {\n    if (options.pixelsDiffer === true) {\n      return {\n        stable: false,\n        band: 'sub-semantic',\n        locations: [],\n        because:\n          'two captures of the same subject are identical in structure, resolved style and ' +\n          'geometry, and their images are not. The cause is below the box tree — glyph ' +\n          'rasterization, compositing, or a font resolving differently — so no component is ' +\n          'responsible and there is no source location to fix. This belongs to the ' +\n          'environment key, not to the code',\n      };\n    }\n\n    return {\n      stable: true,\n      band: 'none',\n      locations: [],\n      because:\n        options.pixelsDiffer === false\n          ? 'two captures of the same subject agree in structure, style, geometry and pixels'\n          : 'two captures of the same subject agree in structure, style and geometry; no image ' +\n            'comparison was supplied, so sub-semantic movement is unobserved rather than absent',\n    };\n  }\n\n  const locations = group(diff.deltas);\n\n  return {\n    stable: false,\n    band: worst(diff.deltas.map((delta) => delta.band)),\n    locations,\n    because: sentence(locations, diff.deltas.length),\n  };\n}\n\n/**\n * The instability as the thing a person reads, with a file on the end.\n *\n * Same shape as every other report here: a cause per line, and a path an editor\n * opens, because `Spinner` is an identifier and `src/ds/components.tsx:88` is an\n * edit.\n */\nexport function summarizeInstability(\n  instability: Instability,\n  options: { readonly source?: SourceIndex; readonly limit?: number } = {},\n): string {\n  if (instability.stable) return instability.because;\n\n  const limit = options.limit ?? 5;\n  const shown = instability.locations.slice(0, limit);\n\n  const lines = shown.map((location) => {\n    const file =\n      options.source === undefined ? null : resolveSource(location.component, options.source);\n\n    const moved = location.properties\n      .slice(0, 3)\n      .map((property) =>\n        property.from === undefined && property.to === undefined\n          ? property.property\n          : `${property.property} ${property.from ?? '(absent)'} → ${property.to ?? '(absent)'}`,\n      );\n\n    return [\n      `  ${location.component} — ${location.deltas} delta(s) in ${location.bands.join(', ')}` +\n        (location.likely !== undefined ? ` [likely ${location.likely}]` : ''),\n      ...moved.map((line) => `      ${line}`),\n      location.properties.length > 3\n        ? `      +${location.properties.length - 3} more propert(y|ies) not listed`\n        : null,\n      location.where !== undefined ? `      in ${location.where}` : null,\n      location.token !== undefined ? `      through ${location.token}` : null,\n      file !== null ? `      ${formatSource(file)}` : null,\n    ]\n      .filter((line): line is string => line !== null)\n      .join('\\n');\n  });\n\n  return [\n    `[unstable] ${instability.because}`,\n    '',\n    ...lines,\n    ...(instability.locations.length > shown.length\n      ? [`  +${instability.locations.length - shown.length} more location(s) not listed`]\n      : []),\n  ].join('\\n');\n}\n\nfunction group(deltas: readonly Delta[]): readonly UnstableLocation[] {\n  const byComponent = new Map<\n    string,\n    {\n      bands: Set<Band>;\n      properties: Map<string, UnstableProperty>;\n      kinds: Set<DeltaKind>;\n      where?: string;\n      path?: NodePath;\n      token?: string;\n      count: number;\n    }\n  >();\n\n  for (const delta of deltas) {\n    // `createdBy` names the component whose JSX produced the node; `owners[0]`\n    // names the nearest enclosing one. Prefer the author, because a fix is made\n    // where the markup is written, not where it ends up.\n    const component = delta.createdBy ?? delta.owners?.[0]?.name ?? '(unattributed)';\n\n    const entry = byComponent.get(component) ?? {\n      bands: new Set<Band>(),\n      properties: new Map<string, UnstableProperty>(),\n      kinds: new Set<DeltaKind>(),\n      count: 0,\n    };\n\n    entry.bands.add(delta.band);\n    entry.kinds.add(delta.kind);\n    entry.count += 1;\n\n    // A whole-node delta — text, a role, a node appearing — carries no\n    // `property`. Reading its absence as \"only geometry moved\" would file a\n    // changing clock under displacement, so the kind is what is consulted and\n    // the property list is only ever additive.\n    if (delta.property !== undefined && !entry.properties.has(delta.property)) {\n      entry.properties.set(delta.property, {\n        property: delta.property,\n        from: delta.from,\n        to: delta.to,\n      });\n    }\n\n    if (entry.where === undefined && delta.where !== undefined) entry.where = delta.where;\n    if (entry.path === undefined) entry.path = delta.path;\n    if (entry.token === undefined && delta.token !== undefined) entry.token = delta.token;\n\n    byComponent.set(component, entry);\n  }\n\n  return [...byComponent.entries()]\n    .map(([component, entry]) => {\n      const properties = [...entry.properties.values()];\n      return {\n        component,\n        bands: [...entry.bands],\n        properties,\n        ...(entry.where !== undefined ? { where: entry.where } : {}),\n        ...(entry.path !== undefined ? { path: entry.path } : {}),\n        ...(entry.token !== undefined ? { token: entry.token } : {}),\n        deltas: entry.count,\n        ...(guess(properties, entry.kinds) !== undefined\n          ? { likely: guess(properties, entry.kinds)! }\n          : {}),\n      };\n    })\n    .sort(\n      (a, b) =>\n        b.deltas - a.deltas ||\n        (a.component < b.component ? -1 : a.component > b.component ? 1 : 0),\n    );\n}\n\n/**\n * Read the shape of the evidence, and only where one reading fits.\n *\n * Deliberately narrow. A guess that fires on ambiguous evidence is worse than no\n * guess: it sends someone to the wrong file with confidence, and the location\n * and the moved declarations — which are facts — get read as if they carried the\n * same certainty as the label.\n */\nfunction guess(\n  properties: readonly UnstableProperty[],\n  kinds: ReadonlySet<DeltaKind>,\n): UnstableLocation['likely'] | undefined {\n  // Content that rewrote itself between two captures of one commit. Checked\n  // before the others because a changing string also moves the box around it,\n  // and the text is the cause while the movement is its consequence.\n  if (kinds.has('text-changed')) return 'dynamic-content';\n\n  if (properties.length === 0) {\n    // Geometry moved and this component declared nothing at all. Something\n    // upstream reflowed it, so the cause is elsewhere and this is only where it\n    // landed — which is worth saying, because it is the one reading that points\n    // away from the component being named.\n    const onlyGeometry = [...kinds].every((kind) => kind === 'rect-changed' || kind === 'node-moved');\n    return onlyGeometry ? 'displacement' : undefined;\n  }\n\n  if (properties.every((property) => ANIMATED.has(property.property))) return 'animation';\n\n  return undefined;\n}\n\nfunction worst(bands: readonly Band[]): InstabilityBand {\n  return loudestBand(bands) ?? 'none';\n}\n\nfunction sentence(locations: readonly UnstableLocation[], deltas: number): string {\n  const named = locations.slice(0, 3).map((location) => location.component);\n  const rest = locations.length > named.length ? ` (+${locations.length - named.length} more)` : '';\n\n  return (\n    `two captures of the same subject at the same commit disagree: ${deltas} delta(s) ` +\n    `across ${locations.length} component(s) — ${named.join(', ')}${rest}. ` +\n    'This is not noise to retry away; the location below is where it is caused'\n  );\n}\n"]}