@variance-authority/core 0.1.0

package/dist/compare/impact.js

@@ -0,0 +1,124 @@
+/**
+ * Render impact: what a changed property can actually disturb.
+ *
+ * This is a **second axis**, orthogonal to the frequency bands of §5, and adding
+ * it rather than folding it into them is deliberate. A band answers *what kind of
+ * thing changed* — structure, a value, sub-pixel noise. Impact answers *how far
+ * the change can reach*.
+ *
+ * The two genuinely differ. A spacing token and a colour token are both `token`
+ * band: a value moved, structure held. But changing spacing reflows the document,
+ * so it can move a node on the other side of the page; changing colour repaints
+ * one box and can move nothing at all. Reporting both as "a token changed" hides
+ * the only thing a reviewer wants to know first.
+ *
+ * The useful consequence is a **bound on collateral**:
+ *
+ * > A paint-only change has no geometric collateral. Ever.
+ *
+ * That is not a heuristic — it follows from how rendering works. So a subject
+ * whose every delta is paint-impact needs no layout comparison to rule out
+ * geometry regressions, which is exactly the kind of question a profile without a
+ * layout engine can otherwise never settle. It is how the cheap tier answers
+ * *"could this have moved anything?"* without measuring anything.
+ */
+/**
+ * Properties that change the box tree.
+ *
+ * Includes the typography metrics, which is easy to get wrong: `font-size`,
+ * `line-height`, `letter-spacing`, and `text-transform` all change glyph
+ * advances, so they resize the boxes containing them and reflow everything after.
+ * A "typography token" change is a layout change, not a styling one.
+ */
+const LAYOUT = [
+    'display', 'position', 'top', 'right', 'bottom', 'left', 'float', 'clear',
+    'width', 'height', 'min-width', 'min-height', 'max-width', 'max-height',
+    'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
+    'padding-top', 'padding-right', 'padding-bottom', 'padding-left',
+    'box-sizing', 'overflow-x', 'overflow-y', 'aspect-ratio',
+    'flex-direction', 'flex-wrap', 'flex-grow', 'flex-shrink', 'flex-basis',
+    'justify-content', 'align-items', 'align-self', 'align-content', 'order',
+    'grid-template-columns', 'grid-template-rows', 'grid-template-areas',
+    'grid-auto-columns', 'grid-auto-rows', 'grid-auto-flow',
+    'grid-column-start', 'grid-column-end', 'grid-row-start', 'grid-row-end',
+    'row-gap', 'column-gap',
+    'font-family', 'font-size', 'font-weight', 'font-style', 'font-stretch',
+    'font-variant', 'line-height', 'letter-spacing', 'word-spacing',
+    'text-align', 'text-indent', 'text-transform', 'white-space', 'word-break',
+    'overflow-wrap', 'text-overflow', 'vertical-align', 'writing-mode', 'direction',
+    // Border *width* occupies space; border colour does not. The style longhand
+    // belongs here too, because `none` collapses the border to zero width whatever
+    // the declared width says.
+    'border-top-width', 'border-right-width', 'border-bottom-width', 'border-left-width',
+    'border-top-style', 'border-right-style', 'border-bottom-style', 'border-left-style',
+    'table-layout', 'border-collapse', 'border-spacing', 'caption-side',
+    'content-visibility',
+];
+/** Properties that repaint a box without resizing or moving it. */
+const PAINT = [
+    'color', 'background-color', 'background-image', 'background-position',
+    'background-size', 'background-repeat', 'background-clip', 'background-origin',
+    'border-top-color', 'border-right-color', 'border-bottom-color', 'border-left-color',
+    'border-top-left-radius', 'border-top-right-radius',
+    'border-bottom-right-radius', 'border-bottom-left-radius',
+    'box-shadow', 'text-shadow',
+    'text-decoration-line', 'text-decoration-color', 'text-decoration-style',
+    'text-decoration-thickness',
+    'object-fit', 'object-position',
+    // `outline` is painted outside the box and never affects layout — that is the
+    // whole reason it exists as a separate property from `border`.
+    'outline-width', 'outline-style', 'outline-color', 'outline-offset',
+    // `visibility: hidden` still occupies its space, unlike `display: none`.
+    'visibility',
+];
+/** Properties handled by the compositor. */
+const COMPOSITE = [
+    'transform', 'transform-origin', 'opacity', 'filter', 'backdrop-filter',
+    'mix-blend-mode', 'z-index',
+];
+const IMPACTS = new Map([
+    ...LAYOUT.map((property) => [property, 'layout']),
+    ...PAINT.map((property) => [property, 'paint']),
+    ...COMPOSITE.map((property) => [property, 'composite']),
+]);
+/**
+ * Impact of a property change.
+ *
+ * An unrecognized property is reported as `layout`, the widest answer. Impact is
+ * used to *rule out* collateral, so an unknown treated as paint-only would let a
+ * real reflow pass unexamined — the over-reporting direction, as everywhere else.
+ */
+export function impactOf(property) {
+    // A custom property is only ever a carrier; what it costs depends entirely on
+    // where it was consumed, which the caller knows and this function does not.
+    if (property.startsWith('--'))
+        return 'layout';
+    return IMPACTS.get(property) ?? 'layout';
+}
+/**
+ * Whether a change to this property can move anything.
+ *
+ * The question the cheap tier can answer without a layout engine, and the reason
+ * this axis exists.
+ */
+export function canReflow(property) {
+    return impactOf(property) === 'layout';
+}
+/**
+ * Combine impacts for a group of changes.
+ *
+ * `structural` wins over everything: a node appearing or disappearing is not a
+ * property change at all, and describing it in terms of repaint versus reflow
+ * would understate it.
+ */
+export function aggregateImpact(impacts) {
+    if (impacts.length === 0)
+        return 'paint';
+    if (impacts.includes('structural'))
+        return 'structural';
+    const distinct = new Set(impacts);
+    if (distinct.size === 1)
+        return [...distinct][0];
+    return 'mixed';
+}
+//# sourceMappingURL=impact.js.map

package/dist/compare/impact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"impact.js","sourceRoot":"","sources":["../../src/compare/impact.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Render impact: what a changed property can actually disturb.\n *\n * This is a **second axis**, orthogonal to the frequency bands of §5, and adding\n * it rather than folding it into them is deliberate. A band answers *what kind of\n * thing changed* — structure, a value, sub-pixel noise. Impact answers *how far\n * the change can reach*.\n *\n * The two genuinely differ. A spacing token and a colour token are both `token`\n * band: a value moved, structure held. But changing spacing reflows the document,\n * so it can move a node on the other side of the page; changing colour repaints\n * one box and can move nothing at all. Reporting both as \"a token changed\" hides\n * the only thing a reviewer wants to know first.\n *\n * The useful consequence is a **bound on collateral**:\n *\n * > A paint-only change has no geometric collateral. Ever.\n *\n * That is not a heuristic — it follows from how rendering works. So a subject\n * whose every delta is paint-impact needs no layout comparison to rule out\n * geometry regressions, which is exactly the kind of question a profile without a\n * layout engine can otherwise never settle. It is how the cheap tier answers\n * *\"could this have moved anything?\"* without measuring anything.\n */\n\nexport type PropertyImpact =\n  /** Reflows: box sizes and positions may change, here and elsewhere. */\n  | 'layout'\n  /** Repaints in place. The box tree is untouched, so nothing moves. */\n  | 'paint'\n  /** Compositing only: transform, opacity, stacking. No reflow, no repaint. */\n  | 'composite';\n\n/**\n * Properties that change the box tree.\n *\n * Includes the typography metrics, which is easy to get wrong: `font-size`,\n * `line-height`, `letter-spacing`, and `text-transform` all change glyph\n * advances, so they resize the boxes containing them and reflow everything after.\n * A \"typography token\" change is a layout change, not a styling one.\n */\nconst LAYOUT: readonly string[] = [\n  'display', 'position', 'top', 'right', 'bottom', 'left', 'float', 'clear',\n  'width', 'height', 'min-width', 'min-height', 'max-width', 'max-height',\n  'margin-top', 'margin-right', 'margin-bottom', 'margin-left',\n  'padding-top', 'padding-right', 'padding-bottom', 'padding-left',\n  'box-sizing', 'overflow-x', 'overflow-y', 'aspect-ratio',\n\n  'flex-direction', 'flex-wrap', 'flex-grow', 'flex-shrink', 'flex-basis',\n  'justify-content', 'align-items', 'align-self', 'align-content', 'order',\n  'grid-template-columns', 'grid-template-rows', 'grid-template-areas',\n  'grid-auto-columns', 'grid-auto-rows', 'grid-auto-flow',\n  'grid-column-start', 'grid-column-end', 'grid-row-start', 'grid-row-end',\n  'row-gap', 'column-gap',\n\n  'font-family', 'font-size', 'font-weight', 'font-style', 'font-stretch',\n  'font-variant', 'line-height', 'letter-spacing', 'word-spacing',\n  'text-align', 'text-indent', 'text-transform', 'white-space', 'word-break',\n  'overflow-wrap', 'text-overflow', 'vertical-align', 'writing-mode', 'direction',\n\n  // Border *width* occupies space; border colour does not. The style longhand\n  // belongs here too, because `none` collapses the border to zero width whatever\n  // the declared width says.\n  'border-top-width', 'border-right-width', 'border-bottom-width', 'border-left-width',\n  'border-top-style', 'border-right-style', 'border-bottom-style', 'border-left-style',\n\n  'table-layout', 'border-collapse', 'border-spacing', 'caption-side',\n  'content-visibility',\n];\n\n/** Properties that repaint a box without resizing or moving it. */\nconst PAINT: readonly string[] = [\n  'color', 'background-color', 'background-image', 'background-position',\n  'background-size', 'background-repeat', 'background-clip', 'background-origin',\n  'border-top-color', 'border-right-color', 'border-bottom-color', 'border-left-color',\n  'border-top-left-radius', 'border-top-right-radius',\n  'border-bottom-right-radius', 'border-bottom-left-radius',\n  'box-shadow', 'text-shadow',\n  'text-decoration-line', 'text-decoration-color', 'text-decoration-style',\n  'text-decoration-thickness',\n  'object-fit', 'object-position',\n\n  // `outline` is painted outside the box and never affects layout — that is the\n  // whole reason it exists as a separate property from `border`.\n  'outline-width', 'outline-style', 'outline-color', 'outline-offset',\n\n  // `visibility: hidden` still occupies its space, unlike `display: none`.\n  'visibility',\n];\n\n/** Properties handled by the compositor. */\nconst COMPOSITE: readonly string[] = [\n  'transform', 'transform-origin', 'opacity', 'filter', 'backdrop-filter',\n  'mix-blend-mode', 'z-index',\n];\n\nconst IMPACTS = new Map<string, PropertyImpact>([\n  ...LAYOUT.map((property) => [property, 'layout'] as const),\n  ...PAINT.map((property) => [property, 'paint'] as const),\n  ...COMPOSITE.map((property) => [property, 'composite'] as const),\n]);\n\n/**\n * Impact of a property change.\n *\n * An unrecognized property is reported as `layout`, the widest answer. Impact is\n * used to *rule out* collateral, so an unknown treated as paint-only would let a\n * real reflow pass unexamined — the over-reporting direction, as everywhere else.\n */\nexport function impactOf(property: string): PropertyImpact {\n  // A custom property is only ever a carrier; what it costs depends entirely on\n  // where it was consumed, which the caller knows and this function does not.\n  if (property.startsWith('--')) return 'layout';\n  return IMPACTS.get(property) ?? 'layout';\n}\n\n/**\n * Whether a change to this property can move anything.\n *\n * The question the cheap tier can answer without a layout engine, and the reason\n * this axis exists.\n */\nexport function canReflow(property: string): boolean {\n  return impactOf(property) === 'layout';\n}\n\nexport type AggregateImpact = PropertyImpact | 'mixed' | 'structural';\n\n/**\n * Combine impacts for a group of changes.\n *\n * `structural` wins over everything: a node appearing or disappearing is not a\n * property change at all, and describing it in terms of repaint versus reflow\n * would understate it.\n */\nexport function aggregateImpact(\n  impacts: readonly (PropertyImpact | 'structural')[],\n): AggregateImpact {\n  if (impacts.length === 0) return 'paint';\n  if (impacts.includes('structural')) return 'structural';\n\n  const distinct = new Set(impacts);\n  if (distinct.size === 1) return [...distinct][0] as PropertyImpact;\n  return 'mixed';\n}\n"]}

package/dist/compare/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `@variance-authority/core/compare` — two snapshots become a list of deltas.
+ *
+ * Tree matching, the delta vocabulary, the bands a delta falls into, and what a
+ * changed property is capable of doing to a layout. No verdict: this group says
+ * *what moved*, and refuses to say whether anyone should mind.
+ *
+ * The split from `judge` is the load-bearing one. A comparison that also decided
+ * severity could not be reused by a caller with a different policy, and every
+ * team has a different policy.
+ */
+export { diffSnapshots, matchTrees } from './diff/index.js';
+export type { SemanticDiff, Delta, Root, RootKind, ChangedComponent, Matching, } from './diff/index.js';
+export { impactOf, canReflow, aggregateImpact } from './impact.js';
+export type { PropertyImpact, AggregateImpact } from './impact.js';
+export type { Band, DeltaKind } from './band.js';
+export { BANDS, bandOf, loudestBand } from './band.js';
+export { observableBands, decidesBand } from './observability.js';
+export type { Observability } from './observability.js';
+export { deriveVariation } from './derive.js';
+export type { Variation } from './derive.js';
+export { partingOf } from './parting.js';
+export { boundarySnapshot } from './instance.js';
+export { sliceOf, sameTree } from './slice.js';
+export type { PartingSlice } from './slice.js';
+export type { Parting, PartedBoundary, PartingRung, MovedInput, } from './parting.js';
+export { explainParting } from './explain.js';
+export { compareValues, fingerprintOfValueDelta } from './value.js';
+export type { ValueChange, ValueDelta } from './value.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/compare/index.js

@@ -0,0 +1,22 @@
+/**
+ * `@variance-authority/core/compare` — two snapshots become a list of deltas.
+ *
+ * Tree matching, the delta vocabulary, the bands a delta falls into, and what a
+ * changed property is capable of doing to a layout. No verdict: this group says
+ * *what moved*, and refuses to say whether anyone should mind.
+ *
+ * The split from `judge` is the load-bearing one. A comparison that also decided
+ * severity could not be reused by a caller with a different policy, and every
+ * team has a different policy.
+ */
+export { diffSnapshots, matchTrees } from './diff/index.js';
+export { impactOf, canReflow, aggregateImpact } from './impact.js';
+export { BANDS, bandOf, loudestBand } from './band.js';
+export { observableBands, decidesBand } from './observability.js';
+export { deriveVariation } from './derive.js';
+export { partingOf } from './parting.js';
+export { boundarySnapshot } from './instance.js';
+export { sliceOf, sameTree } from './slice.js';
+export { explainParting } from './explain.js';
+export { compareValues, fingerprintOfValueDelta } from './value.js';
+//# sourceMappingURL=index.js.map

package/dist/compare/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/compare/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAU5D,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAInE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAEvD,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGlE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9C,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAS/C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC","sourcesContent":["/**\n * `@variance-authority/core/compare` — two snapshots become a list of deltas.\n *\n * Tree matching, the delta vocabulary, the bands a delta falls into, and what a\n * changed property is capable of doing to a layout. No verdict: this group says\n * *what moved*, and refuses to say whether anyone should mind.\n *\n * The split from `judge` is the load-bearing one. A comparison that also decided\n * severity could not be reused by a caller with a different policy, and every\n * team has a different policy.\n */\n\nexport { diffSnapshots, matchTrees } from './diff/index.js';\nexport type {\n  SemanticDiff,\n  Delta,\n  Root,\n  RootKind,\n  ChangedComponent,\n  Matching,\n} from './diff/index.js';\n\nexport { impactOf, canReflow, aggregateImpact } from './impact.js';\nexport type { PropertyImpact, AggregateImpact } from './impact.js';\n\nexport type { Band, DeltaKind } from './band.js';\nexport { BANDS, bandOf, loudestBand } from './band.js';\n\nexport { observableBands, decidesBand } from './observability.js';\nexport type { Observability } from './observability.js';\n\nexport { deriveVariation } from './derive.js';\nexport type { Variation } from './derive.js';\n\nexport { partingOf } from './parting.js';\nexport { boundarySnapshot } from './instance.js';\nexport { sliceOf, sameTree } from './slice.js';\nexport type { PartingSlice } from './slice.js';\nexport type {\n  Parting,\n  PartedBoundary,\n  PartingRung,\n  MovedInput,\n} from './parting.js';\n\nexport { explainParting } from './explain.js';\n\nexport { compareValues, fingerprintOfValueDelta } from './value.js';\nexport type { ValueChange, ValueDelta } from './value.js';\n"]}

package/dist/compare/instance.d.ts

@@ -0,0 +1,30 @@
+import type { NodePath, SemanticSnapshot } from '../format/snapshot.js';
+/**
+ * One component instance, read as though it were the whole subject.
+ *
+ * `partingOf` compares two readings of one tree. A divergence is not that: it is
+ * one component reached at two *sites*, in two different subjects, and handing
+ * the two subjects straight to a parting produces a confident wrong answer.
+ * Measured on the divergence example, `Price` — the component the finding is
+ * about, present on both sides — came back `unpaired`, while `Receipt` and
+ * `PromoCard`, which are genuinely different components, paired positionally at
+ * the root and were reported nondeterministic for holding no state.
+ *
+ * The cause is that a boundary's identity is its owner chain, and the chain
+ * carries the container: the same `<Price>` is `Price>Receipt` at one site and
+ * `Price>PromoCard` at the other, so neither `pairBoundaries` nor `sameTree`
+ * can see them as one component. That is correct for the question those
+ * functions were built for — two arms of an experiment share a root, and a
+ * container that differs there really is a difference — and wrong for this one.
+ *
+ * So the instance is lifted out before it is compared. Everything outside it
+ * goes, including the part of every owner chain that named it: what is left is
+ * the subtree that component rendered, addressed from its own root, which is
+ * the thing two sites actually have in common.
+ *
+ * Returns `undefined` when the path names no node, rather than an empty
+ * snapshot, so a caller cannot mistake "that site is not in this tree" for
+ * "that site rendered nothing".
+ */
+export declare function boundarySnapshot(snapshot: SemanticSnapshot, path: NodePath): SemanticSnapshot | undefined;
+//# sourceMappingURL=instance.d.ts.map

package/dist/compare/instance.js

@@ -0,0 +1,145 @@
+import { digestCombine, digestValue } from '../format/hash.js';
+import { structureOf, styleOf } from '../rules/normalize/project.js';
+/**
+ * One component instance, read as though it were the whole subject.
+ *
+ * `partingOf` compares two readings of one tree. A divergence is not that: it is
+ * one component reached at two *sites*, in two different subjects, and handing
+ * the two subjects straight to a parting produces a confident wrong answer.
+ * Measured on the divergence example, `Price` — the component the finding is
+ * about, present on both sides — came back `unpaired`, while `Receipt` and
+ * `PromoCard`, which are genuinely different components, paired positionally at
+ * the root and were reported nondeterministic for holding no state.
+ *
+ * The cause is that a boundary's identity is its owner chain, and the chain
+ * carries the container: the same `<Price>` is `Price>Receipt` at one site and
+ * `Price>PromoCard` at the other, so neither `pairBoundaries` nor `sameTree`
+ * can see them as one component. That is correct for the question those
+ * functions were built for — two arms of an experiment share a root, and a
+ * container that differs there really is a difference — and wrong for this one.
+ *
+ * So the instance is lifted out before it is compared. Everything outside it
+ * goes, including the part of every owner chain that named it: what is left is
+ * the subtree that component rendered, addressed from its own root, which is
+ * the thing two sites actually have in common.
+ *
+ * Returns `undefined` when the path names no node, rather than an empty
+ * snapshot, so a caller cannot mistake "that site is not in this tree" for
+ * "that site rendered nothing".
+ */
+export function boundarySnapshot(snapshot, path) {
+    const node = nodeAt(snapshot.root, path);
+    if (node === undefined)
+        return undefined;
+    /**
+     * How many owners to drop, decided once at the boundary and applied to every
+     * node under it.
+     *
+     * Owners run innermost-first, so the containers outside this instance are the
+     * *tail* of the list — and they are the same tail at every depth, because
+     * every node in the subtree is inside the same containers. `Price>PromoCard`
+     * loses one and becomes `Price`; a `Label` nested inside it reads
+     * `Label>Price>PromoCard` and loses exactly the same one.
+     */
+    const outer = Math.max(0, (node.provenance?.owners.length ?? 1) - 1);
+    const root = lift(node, path, outer);
+    const structureHash = digestValue(structureOf(root));
+    const styleHash = digestValue(styleOf(root, snapshot.profile.layout));
+    const ignoreSites = rebasedSites(snapshot.ignoreSites, path);
+    return {
+        formatVersion: snapshot.formatVersion,
+        subject: snapshot.subject,
+        profile: snapshot.profile,
+        environment: snapshot.environment,
+        /**
+         * Recomputed, and it is not bookkeeping.
+         *
+         * `compareTrees` returns `identical` the moment two `renderHash`es match, so
+         * a lifted snapshot carrying the digest of the subject it came out of would
+         * make every comparison between two instances answer a question about their
+         * containers. Two identical renderings of one component in two different
+         * pages would compare as different, which is precisely the echo this half of
+         * the report exists to recognise.
+         */
+        renderHash: digestCombine('render', [
+            snapshot.environment.semanticDigest,
+            structureHash,
+            styleHash,
+        ]),
+        structureHash,
+        styleHash,
+        root,
+        styleProvenance: rebasedProvenance(snapshot.styleProvenance, path),
+        ...(ignoreSites.length > 0 ? { ignoreSites } : {}),
+        diagnostics: snapshot.diagnostics,
+    };
+}
+/**
+ * The subtree, re-addressed and with the containers stripped from its chains.
+ *
+ * Paths are rewritten rather than kept, because a delta carries a path and a
+ * reader of one instance has no way to resolve `0/3/1/0` against a tree whose
+ * root is `0/3/1`. The rewrite is a prefix swap, so sibling order and depth
+ * survive it exactly.
+ */
+function lift(node, prefix, outer) {
+    const owners = node.provenance?.owners;
+    return {
+        ...node,
+        path: rebase(node.path, prefix),
+        ...(node.provenance !== undefined && owners !== undefined
+            ? {
+                provenance: {
+                    ...node.provenance,
+                    owners: owners.slice(0, Math.max(1, owners.length - outer)),
+                },
+            }
+            : {}),
+        children: node.children.map((child) => lift(child, prefix, outer)),
+    };
+}
+/**
+ * A path in the lifted tree's own space.
+ *
+ * The boundary itself becomes `ROOT`; everything under it keeps its tail. A path
+ * that is not under the prefix never reaches here — both callers filter first —
+ * and returning it unchanged would be a silent mis-address.
+ */
+function rebase(path, prefix) {
+    return path === prefix ? ROOT : `${ROOT}${path.slice(prefix.length)}`;
+}
+function under(path, prefix) {
+    return path === prefix || path.startsWith(`${prefix}/`);
+}
+function rebasedProvenance(entries, prefix) {
+    return entries
+        .filter((entry) => under(entry.path, prefix))
+        .map((entry) => ({ ...entry, path: rebase(entry.path, prefix) }));
+}
+/**
+ * Ignores kept rather than dropped.
+ *
+ * An ignore that fell inside this instance still applies to it: dropping it here
+ * would let a masked clock back into a comparison by the side door, which is the
+ * one direction this system is not allowed to be wrong in.
+ */
+function rebasedSites(sites, prefix) {
+    return (sites ?? [])
+        .filter((site) => under(site.path, prefix))
+        .map((site) => ({ ...site, path: rebase(site.path, prefix) }));
+}
+function nodeAt(root, path) {
+    if (root.path === path)
+        return root;
+    if (!under(path, root.path))
+        return undefined;
+    for (const child of root.children) {
+        const found = nodeAt(child, path);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+/** The path a normalized tree's root carries, and therefore a lifted one's. */
+const ROOT = '0';
+//# sourceMappingURL=instance.js.map

package/dist/compare/instance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance.js","sourceRoot":"","sources":["../../src/compare/instance.ts"],"names":[],"mappings":"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","sourcesContent":["import { digestCombine, digestValue } from '../format/hash.js';\nimport type {\n  IgnoreSite,\n  NodePath,\n  SemanticNode,\n  SemanticSnapshot,\n  StyleProvenanceEntry,\n} from '../format/snapshot.js';\nimport { structureOf, styleOf } from '../rules/normalize/project.js';\n\n/**\n * One component instance, read as though it were the whole subject.\n *\n * `partingOf` compares two readings of one tree. A divergence is not that: it is\n * one component reached at two *sites*, in two different subjects, and handing\n * the two subjects straight to a parting produces a confident wrong answer.\n * Measured on the divergence example, `Price` — the component the finding is\n * about, present on both sides — came back `unpaired`, while `Receipt` and\n * `PromoCard`, which are genuinely different components, paired positionally at\n * the root and were reported nondeterministic for holding no state.\n *\n * The cause is that a boundary's identity is its owner chain, and the chain\n * carries the container: the same `<Price>` is `Price>Receipt` at one site and\n * `Price>PromoCard` at the other, so neither `pairBoundaries` nor `sameTree`\n * can see them as one component. That is correct for the question those\n * functions were built for — two arms of an experiment share a root, and a\n * container that differs there really is a difference — and wrong for this one.\n *\n * So the instance is lifted out before it is compared. Everything outside it\n * goes, including the part of every owner chain that named it: what is left is\n * the subtree that component rendered, addressed from its own root, which is\n * the thing two sites actually have in common.\n *\n * Returns `undefined` when the path names no node, rather than an empty\n * snapshot, so a caller cannot mistake \"that site is not in this tree\" for\n * \"that site rendered nothing\".\n */\nexport function boundarySnapshot(\n  snapshot: SemanticSnapshot,\n  path: NodePath,\n): SemanticSnapshot | undefined {\n  const node = nodeAt(snapshot.root, path);\n  if (node === undefined) return undefined;\n\n  /**\n   * How many owners to drop, decided once at the boundary and applied to every\n   * node under it.\n   *\n   * Owners run innermost-first, so the containers outside this instance are the\n   * *tail* of the list — and they are the same tail at every depth, because\n   * every node in the subtree is inside the same containers. `Price>PromoCard`\n   * loses one and becomes `Price`; a `Label` nested inside it reads\n   * `Label>Price>PromoCard` and loses exactly the same one.\n   */\n  const outer = Math.max(0, (node.provenance?.owners.length ?? 1) - 1);\n\n  const root = lift(node, path, outer);\n  const structureHash = digestValue(structureOf(root));\n  const styleHash = digestValue(styleOf(root, snapshot.profile.layout));\n  const ignoreSites = rebasedSites(snapshot.ignoreSites, path);\n\n  return {\n    formatVersion: snapshot.formatVersion,\n    subject: snapshot.subject,\n    profile: snapshot.profile,\n    environment: snapshot.environment,\n\n    /**\n     * Recomputed, and it is not bookkeeping.\n     *\n     * `compareTrees` returns `identical` the moment two `renderHash`es match, so\n     * a lifted snapshot carrying the digest of the subject it came out of would\n     * make every comparison between two instances answer a question about their\n     * containers. Two identical renderings of one component in two different\n     * pages would compare as different, which is precisely the echo this half of\n     * the report exists to recognise.\n     */\n    renderHash: digestCombine('render', [\n      snapshot.environment.semanticDigest,\n      structureHash,\n      styleHash,\n    ]),\n    structureHash,\n    styleHash,\n    root,\n    styleProvenance: rebasedProvenance(snapshot.styleProvenance, path),\n    ...(ignoreSites.length > 0 ? { ignoreSites } : {}),\n    diagnostics: snapshot.diagnostics,\n  };\n}\n\n/**\n * The subtree, re-addressed and with the containers stripped from its chains.\n *\n * Paths are rewritten rather than kept, because a delta carries a path and a\n * reader of one instance has no way to resolve `0/3/1/0` against a tree whose\n * root is `0/3/1`. The rewrite is a prefix swap, so sibling order and depth\n * survive it exactly.\n */\nfunction lift(node: SemanticNode, prefix: NodePath, outer: number): SemanticNode {\n  const owners = node.provenance?.owners;\n\n  return {\n    ...node,\n    path: rebase(node.path, prefix),\n    ...(node.provenance !== undefined && owners !== undefined\n      ? {\n          provenance: {\n            ...node.provenance,\n            owners: owners.slice(0, Math.max(1, owners.length - outer)),\n          },\n        }\n      : {}),\n    children: node.children.map((child) => lift(child, prefix, outer)),\n  };\n}\n\n/**\n * A path in the lifted tree's own space.\n *\n * The boundary itself becomes `ROOT`; everything under it keeps its tail. A path\n * that is not under the prefix never reaches here — both callers filter first —\n * and returning it unchanged would be a silent mis-address.\n */\nfunction rebase(path: NodePath, prefix: NodePath): NodePath {\n  return path === prefix ? ROOT : `${ROOT}${path.slice(prefix.length)}`;\n}\n\nfunction under(path: NodePath, prefix: NodePath): boolean {\n  return path === prefix || path.startsWith(`${prefix}/`);\n}\n\nfunction rebasedProvenance(\n  entries: readonly StyleProvenanceEntry[],\n  prefix: NodePath,\n): readonly StyleProvenanceEntry[] {\n  return entries\n    .filter((entry) => under(entry.path, prefix))\n    .map((entry) => ({ ...entry, path: rebase(entry.path, prefix) }));\n}\n\n/**\n * Ignores kept rather than dropped.\n *\n * An ignore that fell inside this instance still applies to it: dropping it here\n * would let a masked clock back into a comparison by the side door, which is the\n * one direction this system is not allowed to be wrong in.\n */\nfunction rebasedSites(\n  sites: readonly IgnoreSite[] | undefined,\n  prefix: NodePath,\n): readonly IgnoreSite[] {\n  return (sites ?? [])\n    .filter((site) => under(site.path, prefix))\n    .map((site) => ({ ...site, path: rebase(site.path, prefix) }));\n}\n\nfunction nodeAt(root: SemanticNode, path: NodePath): SemanticNode | undefined {\n  if (root.path === path) return root;\n  if (!under(path, root.path)) return undefined;\n  for (const child of root.children) {\n    const found = nodeAt(child, path);\n    if (found !== undefined) return found;\n  }\n  return undefined;\n}\n\n/** The path a normalized tree's root carries, and therefore a lifted one's. */\nconst ROOT = '0';\n"]}

package/dist/compare/observability.d.ts

@@ -0,0 +1,49 @@
+/**
+ * What a profile can decide, band by band.
+ *
+ * This lives in `compare` rather than beside `ObservationProfile` in `format`
+ * because it is a statement about *bands*, and a band classifies a delta. Core's
+ * entrypoints run format → rules → compare → attribute → judge → plan, and a
+ * `format` module importing `Band` would point that arrow backwards. The profile
+ * describes a collector's capability; mapping that capability onto what can be
+ * settled is the comparison layer's question.
+ */
+import type { ObservationProfile } from '../format/profile.js';
+import type { Band } from './band.js';
+/** How completely a profile can decide one band. */
+export type Observability = 'full' | 'structural-only' | 'declared-only' | 'none';
+/**
+ * Bands a profile is able to decide. A band this returns `none` for can never
+ * resolve to `unchanged` under that profile — it resolves to `unobserved`.
+ *
+ * JSDOM sees structural geometry (nodes appearing, disappearing, reordering)
+ * because that is tree shape, but not metric geometry (moves, resizes) because
+ * that requires an engine. `geometry` is therefore only partially observable,
+ * and partial observation of a blocking band is reported, never assumed away.
+ *
+ * The two bands that need no engine are worth stating rather than leaving to be
+ * inferred: **`a11y` and `content` are fully decidable in the unit-test
+ * process.** A role, an accessible name, an ARIA state and a text node are facts
+ * about a document, so a dropped `aria-label` and a changed string are settled at
+ * the cheapest tier this project has — no browser, no screenshot, no baseline
+ * image. That is the concrete form of `docs/comparison.md` §3.3: the category no
+ * raster comparison can reach is also the category that costs least to reach.
+ *
+ * The return type is `Record<Band, …>` on purpose. Declaring a new band and
+ * forgetting to say whether a profile can observe it is a compile error, not a
+ * silent `undefined` that a truthiness check reads as "no".
+ */
+export declare function observableBands(profile: ObservationProfile): Record<Band, Observability>;
+/**
+ * Whether a level is enough to settle its band, or whether the band must be
+ * reported `unobserved`.
+ *
+ * The asymmetry between `geometry` and everything else is ADR-0002 and is
+ * deliberate. `structural-only` geometry is *not* enough: a profile that sees
+ * tree shape but not metrics would report a box that moved as `unchanged`, which
+ * is the one failure this product must never produce. `declared-only` style *is*
+ * enough — an author's declaration is a real answer about the token band, just a
+ * narrower one than a resolved cascade.
+ */
+export declare function decidesBand(band: Band, level: Observability): boolean;
+//# sourceMappingURL=observability.d.ts.map

package/dist/compare/observability.js

@@ -0,0 +1,57 @@
+/**
+ * What a profile can decide, band by band.
+ *
+ * This lives in `compare` rather than beside `ObservationProfile` in `format`
+ * because it is a statement about *bands*, and a band classifies a delta. Core's
+ * entrypoints run format → rules → compare → attribute → judge → plan, and a
+ * `format` module importing `Band` would point that arrow backwards. The profile
+ * describes a collector's capability; mapping that capability onto what can be
+ * settled is the comparison layer's question.
+ */
+/**
+ * Bands a profile is able to decide. A band this returns `none` for can never
+ * resolve to `unchanged` under that profile — it resolves to `unobserved`.
+ *
+ * JSDOM sees structural geometry (nodes appearing, disappearing, reordering)
+ * because that is tree shape, but not metric geometry (moves, resizes) because
+ * that requires an engine. `geometry` is therefore only partially observable,
+ * and partial observation of a blocking band is reported, never assumed away.
+ *
+ * The two bands that need no engine are worth stating rather than leaving to be
+ * inferred: **`a11y` and `content` are fully decidable in the unit-test
+ * process.** A role, an accessible name, an ARIA state and a text node are facts
+ * about a document, so a dropped `aria-label` and a changed string are settled at
+ * the cheapest tier this project has — no browser, no screenshot, no baseline
+ * image. That is the concrete form of `docs/comparison.md` §3.3: the category no
+ * raster comparison can reach is also the category that costs least to reach.
+ *
+ * The return type is `Record<Band, …>` on purpose. Declaring a new band and
+ * forgetting to say whether a profile can observe it is a compile error, not a
+ * silent `undefined` that a truthiness check reads as "no".
+ */
+export function observableBands(profile) {
+    return {
+        a11y: profile.ariaTree ? 'full' : 'none',
+        geometry: profile.layout ? 'full' : profile.ariaTree ? 'structural-only' : 'none',
+        token: profile.computedStyle ? 'full' : profile.declaredStyle ? 'declared-only' : 'none',
+        // Text is the one band no collector can fail at: having a document is the
+        // precondition for producing a snapshot at all.
+        content: 'full',
+        texture: profile.raster ? 'full' : 'none',
+    };
+}
+/**
+ * Whether a level is enough to settle its band, or whether the band must be
+ * reported `unobserved`.
+ *
+ * The asymmetry between `geometry` and everything else is ADR-0002 and is
+ * deliberate. `structural-only` geometry is *not* enough: a profile that sees
+ * tree shape but not metrics would report a box that moved as `unchanged`, which
+ * is the one failure this product must never produce. `declared-only` style *is*
+ * enough — an author's declaration is a real answer about the token band, just a
+ * narrower one than a resolved cascade.
+ */
+export function decidesBand(band, level) {
+    return band === 'geometry' ? level === 'full' : level !== 'none';
+}
+//# sourceMappingURL=observability.js.map

package/dist/compare/observability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.js","sourceRoot":"","sources":["../../src/compare/observability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,eAAe,CAAC,OAA2B;IACzD,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;QACxC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,MAAM;QACjF,KAAK,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,MAAM;QACxF,0EAA0E;QAC1E,gDAAgD;QAChD,OAAO,EAAE,MAAM;QACf,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;KAC1C,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,IAAU,EAAE,KAAoB;IAC1D,OAAO,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,KAAK,KAAK,MAAM,CAAC;AACnE,CAAC","sourcesContent":["/**\n * What a profile can decide, band by band.\n *\n * This lives in `compare` rather than beside `ObservationProfile` in `format`\n * because it is a statement about *bands*, and a band classifies a delta. Core's\n * entrypoints run format → rules → compare → attribute → judge → plan, and a\n * `format` module importing `Band` would point that arrow backwards. The profile\n * describes a collector's capability; mapping that capability onto what can be\n * settled is the comparison layer's question.\n */\n\nimport type { ObservationProfile } from '../format/profile.js';\nimport type { Band } from './band.js';\n\n/** How completely a profile can decide one band. */\nexport type Observability = 'full' | 'structural-only' | 'declared-only' | 'none';\n\n/**\n * Bands a profile is able to decide. A band this returns `none` for can never\n * resolve to `unchanged` under that profile — it resolves to `unobserved`.\n *\n * JSDOM sees structural geometry (nodes appearing, disappearing, reordering)\n * because that is tree shape, but not metric geometry (moves, resizes) because\n * that requires an engine. `geometry` is therefore only partially observable,\n * and partial observation of a blocking band is reported, never assumed away.\n *\n * The two bands that need no engine are worth stating rather than leaving to be\n * inferred: **`a11y` and `content` are fully decidable in the unit-test\n * process.** A role, an accessible name, an ARIA state and a text node are facts\n * about a document, so a dropped `aria-label` and a changed string are settled at\n * the cheapest tier this project has — no browser, no screenshot, no baseline\n * image. That is the concrete form of `docs/comparison.md` §3.3: the category no\n * raster comparison can reach is also the category that costs least to reach.\n *\n * The return type is `Record<Band, …>` on purpose. Declaring a new band and\n * forgetting to say whether a profile can observe it is a compile error, not a\n * silent `undefined` that a truthiness check reads as \"no\".\n */\nexport function observableBands(profile: ObservationProfile): Record<Band, Observability> {\n  return {\n    a11y: profile.ariaTree ? 'full' : 'none',\n    geometry: profile.layout ? 'full' : profile.ariaTree ? 'structural-only' : 'none',\n    token: profile.computedStyle ? 'full' : profile.declaredStyle ? 'declared-only' : 'none',\n    // Text is the one band no collector can fail at: having a document is the\n    // precondition for producing a snapshot at all.\n    content: 'full',\n    texture: profile.raster ? 'full' : 'none',\n  };\n}\n\n/**\n * Whether a level is enough to settle its band, or whether the band must be\n * reported `unobserved`.\n *\n * The asymmetry between `geometry` and everything else is ADR-0002 and is\n * deliberate. `structural-only` geometry is *not* enough: a profile that sees\n * tree shape but not metrics would report a box that moved as `unchanged`, which\n * is the one failure this product must never produce. `declared-only` style *is*\n * enough — an author's declaration is a real answer about the token band, just a\n * narrower one than a resolved cascade.\n */\nexport function decidesBand(band: Band, level: Observability): boolean {\n  return band === 'geometry' ? level === 'full' : level !== 'none';\n}\n"]}