@variance-authority/core 0.1.0

package/dist/attribute/stack.js

@@ -0,0 +1,108 @@
+/**
+ * V8: `    at App (http://host/src/probe.jsx:23:26)` — and the same without a
+ * name for top-level code, which is why the parenthesised half is optional.
+ *
+ * `async`, `new` and `Object.<anonymous>` all land in the name, which is fine:
+ * nothing here reads the name, and a name that is slightly wrong costs nothing
+ * where a *position* that is slightly wrong costs a reviewer an open file.
+ */
+const V8_FRAME = /^\s*at\s+(?:(.+?)\s+\()?(.+?):(\d+):(\d+)\)?$/;
+/** SpiderMonkey and JavaScriptCore: `App@http://host/src/probe.jsx:23:26`. */
+const AT_FRAME = /^\s*(?:(.*?)@)(.+?):(\d+):(\d+)$/;
+/**
+ * The frames of a stack, in order, outermost call last.
+ *
+ * The message line is dropped, and so is any line neither engine format
+ * recognises — a stack is diagnostic output rather than a data format, and a
+ * frame that cannot be read is one fewer candidate rather than a failure.
+ *
+ * `eval` frames are deliberately not unwrapped. V8 writes them as
+ * `at eval (eval at fn (http://host/a.js:1:1), <anonymous>:2:3)`, where two
+ * positions are present and the inner one is meaningless outside the eval.
+ * Taking the outer one would name the line that *called* `eval` as the line that
+ * wrote the element, which is a confident wrong answer.
+ */
+export function parseStackFrames(stack) {
+    const frames = [];
+    for (const raw of stack.split('\n')) {
+        const line = raw.trimEnd();
+        if (line === '' || line.includes('(eval at '))
+            continue;
+        const match = V8_FRAME.exec(line) ?? AT_FRAME.exec(line);
+        if (match === null)
+            continue;
+        const [, name, url = '', lineDigits = '', columnDigits = ''] = match;
+        if (url === '' || url.startsWith('data:'))
+            continue;
+        const at = Number(lineDigits);
+        const column = Number(columnDigits);
+        if (!Number.isFinite(at) || !Number.isFinite(column) || at < 1)
+            continue;
+        frames.push({
+            url,
+            line: at,
+            column,
+            ...(name !== undefined && name !== '' ? { function: name } : {}),
+        });
+    }
+    return frames;
+}
+/**
+ * Whether a path belongs to a dependency rather than to the project.
+ *
+ * Three spellings of the same fact, because three build tools spell it
+ * differently: the directory itself, Vite's prebundled dependency cache, and the
+ * `webpack-internal:` scheme wrapping the same directory. The test runs against
+ * both the served URL — which saves fetching a map for a megabyte of vendor
+ * code — and against the path the map resolves to, which is what actually
+ * decides it.
+ *
+ * A dependency that *is* the subject cannot be attributed by this, and that is
+ * the intended reading: a project reviewing its own components wants the line in
+ * its own repository, and the line inside `react-dom` that rendered it is never
+ * the answer to "what changed".
+ */
+export function isVendorPath(path) {
+    return (path.includes('node_modules') ||
+        path.includes('/.vite/deps/') ||
+        path.includes('/.yarn/') ||
+        path.startsWith('webpack-internal:'));
+}
+/**
+ * The location that wrote this element, chosen from its stack.
+ *
+ * The rule is one sentence: **the first frame that resolves to a file the
+ * project wrote.** Frame zero is always React's own runtime, because React is
+ * what constructed the error. Frame one is the author in an ordinary build and
+ * is a custom JSX runtime in a build that has one — and this does not need to
+ * know which, because Emotion resolves into `node_modules` and the component
+ * does not.
+ *
+ * That is the same answer the recorded-symbol path gives, arrived at from the
+ * other side. Where `jsx-source` is installed it wins, because it is exact
+ * without a map; this is what a project that installed nothing still gets.
+ *
+ * `originalFor` is supplied rather than performed because resolving a frame
+ * means fetching the module the browser was served, and this package may not
+ * assume a network (ADR-0013). The caller owns the fetch, the cache, and the
+ * decision about how long to wait; this owns which frame to ask about and when
+ * to stop asking.
+ */
+export function writerLocationOf(frames, originalFor) {
+    for (const frame of frames) {
+        if (isVendorPath(frame.url))
+            continue;
+        const original = originalFor(frame);
+        // No map is not the same as a vendor frame. An unmapped application module
+        // is one a build served as written — which a dev server does for plain `.js`
+        // — and its own coordinates are already the answer.
+        if (original === null) {
+            return { file: frame.url, line: frame.line, column: frame.column };
+        }
+        if (isVendorPath(original.source))
+            continue;
+        return { file: original.source, line: original.line, column: original.column };
+    }
+    return null;
+}
+//# sourceMappingURL=stack.js.map

package/dist/attribute/stack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack.js","sourceRoot":"","sources":["../../src/attribute/stack.ts"],"names":[],"mappings":"AA+BA;;;;;;;GAOG;AACH,MAAM,QAAQ,GAAG,+CAA+C,CAAC;AAEjE,8EAA8E;AAC9E,MAAM,QAAQ,GAAG,kCAAkC,CAAC;AAEpD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,MAAM,MAAM,GAAiB,EAAE,CAAC;IAEhC,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC;QAC3B,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC;YAAE,SAAS;QAExD,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzD,IAAI,KAAK,KAAK,IAAI;YAAE,SAAS;QAE7B,MAAM,CAAC,EAAE,IAAI,EAAE,GAAG,GAAG,EAAE,EAAE,UAAU,GAAG,EAAE,EAAE,YAAY,GAAG,EAAE,CAAC,GAAG,KAAK,CAAC;QACrE,IAAI,GAAG,KAAK,EAAE,IAAI,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC;YAAE,SAAS;QAEpD,MAAM,EAAE,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;QAC9B,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;QACpC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC;YAAE,SAAS;QAEzE,MAAM,CAAC,IAAI,CAAC;YACV,GAAG;YACH,IAAI,EAAE,EAAE;YACR,MAAM;YACN,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACjE,CAAC,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,CACL,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC;QAC7B,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC;QAC7B,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;QACxB,IAAI,CAAC,UAAU,CAAC,mBAAmB,CAAC,CACrC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAA6B,EAC7B,WAA2D;IAE3D,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC;YAAE,SAAS;QAEtC,MAAM,QAAQ,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;QAEpC,2EAA2E;QAC3E,6EAA6E;QAC7E,oDAAoD;QACpD,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;QACrE,CAAC;QAED,IAAI,YAAY,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,SAAS;QAE5C,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;IACjF,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["import type { SourceLocation, StackFrame } from '../format/provenance.js';\nimport type { OriginalPosition } from './source-map.js';\n\n/**\n * Reading a call site out of a stack, and deciding which frame is the author.\n *\n * React 19 constructs an `Error` inside its own `jsx`/`jsxDEV` and keeps it on\n * every fiber. That error is a complete answer to \"which line wrote this\n * element\" that no build has to opt into: the runtime that captured it is frame\n * zero, and whoever called it is frame one. Nothing is configured, nothing is\n * installed, and the location is present in any build where React is the\n * development build — which is every dev server, every Vitest run and every Jest\n * run, because all three are what \"not production\" means.\n *\n * Two jobs live here and they are separable on purpose. Parsing a stack is a\n * fact about a JavaScript engine. Choosing *which* frame is the author is a\n * policy, and it is the part with a defensible rule rather than a heuristic:\n * the author is the first frame that maps back to code the project wrote. A\n * custom JSX runtime — Emotion, theme-ui — sits between React and the author and\n * is skipped not because it is on a list but because it resolves into\n * `node_modules`.\n */\n\n/**\n * A frame is a wire value, not a local one: the page reads it, the collector\n * resolves it, and it travels between them on `Provenance`. It is declared where\n * the rest of provenance is declared, and re-exported here because this is the\n * group that does something with it.\n */\nexport type { StackFrame };\n\n/**\n * V8: `    at App (http://host/src/probe.jsx:23:26)` — and the same without a\n * name for top-level code, which is why the parenthesised half is optional.\n *\n * `async`, `new` and `Object.<anonymous>` all land in the name, which is fine:\n * nothing here reads the name, and a name that is slightly wrong costs nothing\n * where a *position* that is slightly wrong costs a reviewer an open file.\n */\nconst V8_FRAME = /^\\s*at\\s+(?:(.+?)\\s+\\()?(.+?):(\\d+):(\\d+)\\)?$/;\n\n/** SpiderMonkey and JavaScriptCore: `App@http://host/src/probe.jsx:23:26`. */\nconst AT_FRAME = /^\\s*(?:(.*?)@)(.+?):(\\d+):(\\d+)$/;\n\n/**\n * The frames of a stack, in order, outermost call last.\n *\n * The message line is dropped, and so is any line neither engine format\n * recognises — a stack is diagnostic output rather than a data format, and a\n * frame that cannot be read is one fewer candidate rather than a failure.\n *\n * `eval` frames are deliberately not unwrapped. V8 writes them as\n * `at eval (eval at fn (http://host/a.js:1:1), <anonymous>:2:3)`, where two\n * positions are present and the inner one is meaningless outside the eval.\n * Taking the outer one would name the line that *called* `eval` as the line that\n * wrote the element, which is a confident wrong answer.\n */\nexport function parseStackFrames(stack: string): StackFrame[] {\n  const frames: StackFrame[] = [];\n\n  for (const raw of stack.split('\\n')) {\n    const line = raw.trimEnd();\n    if (line === '' || line.includes('(eval at ')) continue;\n\n    const match = V8_FRAME.exec(line) ?? AT_FRAME.exec(line);\n    if (match === null) continue;\n\n    const [, name, url = '', lineDigits = '', columnDigits = ''] = match;\n    if (url === '' || url.startsWith('data:')) continue;\n\n    const at = Number(lineDigits);\n    const column = Number(columnDigits);\n    if (!Number.isFinite(at) || !Number.isFinite(column) || at < 1) continue;\n\n    frames.push({\n      url,\n      line: at,\n      column,\n      ...(name !== undefined && name !== '' ? { function: name } : {}),\n    });\n  }\n\n  return frames;\n}\n\n/**\n * Whether a path belongs to a dependency rather than to the project.\n *\n * Three spellings of the same fact, because three build tools spell it\n * differently: the directory itself, Vite's prebundled dependency cache, and the\n * `webpack-internal:` scheme wrapping the same directory. The test runs against\n * both the served URL — which saves fetching a map for a megabyte of vendor\n * code — and against the path the map resolves to, which is what actually\n * decides it.\n *\n * A dependency that *is* the subject cannot be attributed by this, and that is\n * the intended reading: a project reviewing its own components wants the line in\n * its own repository, and the line inside `react-dom` that rendered it is never\n * the answer to \"what changed\".\n */\nexport function isVendorPath(path: string): boolean {\n  return (\n    path.includes('node_modules') ||\n    path.includes('/.vite/deps/') ||\n    path.includes('/.yarn/') ||\n    path.startsWith('webpack-internal:')\n  );\n}\n\n/**\n * The location that wrote this element, chosen from its stack.\n *\n * The rule is one sentence: **the first frame that resolves to a file the\n * project wrote.** Frame zero is always React's own runtime, because React is\n * what constructed the error. Frame one is the author in an ordinary build and\n * is a custom JSX runtime in a build that has one — and this does not need to\n * know which, because Emotion resolves into `node_modules` and the component\n * does not.\n *\n * That is the same answer the recorded-symbol path gives, arrived at from the\n * other side. Where `jsx-source` is installed it wins, because it is exact\n * without a map; this is what a project that installed nothing still gets.\n *\n * `originalFor` is supplied rather than performed because resolving a frame\n * means fetching the module the browser was served, and this package may not\n * assume a network (ADR-0013). The caller owns the fetch, the cache, and the\n * decision about how long to wait; this owns which frame to ask about and when\n * to stop asking.\n */\nexport function writerLocationOf(\n  frames: readonly StackFrame[],\n  originalFor: (frame: StackFrame) => OriginalPosition | null,\n): SourceLocation | null {\n  for (const frame of frames) {\n    if (isVendorPath(frame.url)) continue;\n\n    const original = originalFor(frame);\n\n    // No map is not the same as a vendor frame. An unmapped application module\n    // is one a build served as written — which a dev server does for plain `.js`\n    // — and its own coordinates are already the answer.\n    if (original === null) {\n      return { file: frame.url, line: frame.line, column: frame.column };\n    }\n\n    if (isVendorPath(original.source)) continue;\n\n    return { file: original.source, line: original.line, column: original.column };\n  }\n\n  return null;\n}\n"]}

package/dist/compare/band.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Frequency bands (spec §5).
+ *
+ * Every semantic delta lands in exactly one band, and the band decides how loudly
+ * it is reported. The insight the bands encode: change frequency and change
+ * importance are inversely correlated. An accessible name almost never moves and
+ * is a defect when it does; anti-aliasing moves constantly and never matters.
+ *
+ * The list is ordered, loudest first, and `loudestBand` is the only thing allowed
+ * to collapse a set of them. Three call sites used to hard-code their own
+ * `if (bands.includes('geometry'))` ladder, which meant adding a band silently
+ * demoted it below everything in every one of them.
+ */
+export type Band = 
+/**
+ * Rarest, and the one a picture cannot hold. A role, an accessible name, or an
+ * ARIA state changed — what a screen reader announces moved, whether or not
+ * anything was repainted.
+ *
+ * Split out of `geometry` deliberately. Both are low-frequency, but a box that
+ * moved and a control that lost its name are different findings for different
+ * readers, and folding the second into the first means the evidence this
+ * project collects and no image-comparison tool has is reported under a label
+ * that sounds like layout. A project can now write `blocking: ['a11y']` and
+ * have an accessibility regression stop a merge on its own terms.
+ */
+'a11y'
+/** Low frequency. Boxes appear, vanish, move, or resize; content reflows. */
+ | 'geometry'
+/** Mid frequency. Style *values* moved while structure held. */
+ | 'token'
+/**
+ * Text moved and nothing else did.
+ *
+ * The highest-frequency band that is still a real change: copy edits, counts,
+ * dates, translations. Quieter than `geometry` because a reviewer who is told
+ * a string changed does not also need to be told a box moved — the reflow is
+ * the consequence, and `geometry` outranks it exactly when the tree moved for
+ * some other reason too.
+ *
+ * It is separated from `geometry` because it is the band a message catalogue
+ * joins against. A locale run compares the same subject's `content` across two
+ * languages, which is a question no baseline image can be asked.
+ */
+ | 'content'
+/**
+ * High frequency. Sub-semantic rendering variance — anti-aliasing, sub-pixel
+ * shifts, compression artifacts. Auto-passes; counted, never reviewed.
+ */
+ | 'texture';
+/** Loudest first. `loudestBand` reads this order; nothing else may assume one. */
+export declare const BANDS: readonly Band[];
+/**
+ * The loudest band present, or `null` for an empty set.
+ *
+ * `null` rather than a default, because "nothing changed" and "something changed
+ * at the quietest band" are different states and a caller that wants to conflate
+ * them should have to say so.
+ */
+export declare function loudestBand(bands: Iterable<Band>): Band | null;
+/** What kind of thing changed, before policy has an opinion about it. */
+export type DeltaKind = 'node-added' | 'node-removed' | 'node-moved' | 'role-changed' | 'name-changed' | 'description-changed' | 'state-changed' | 'text-changed' | 'attribute-changed' | 'rect-changed' | 'style-changed' | 'token-changed' | 'raster-residue';
+/**
+ * The band a delta falls in, before policy.
+ *
+ * `attribute-changed` is `geometry` rather than `a11y` for a reason that is
+ * easy to get backwards: **no `aria-*` attribute ever reaches it.**
+ * `ATTRIBUTE_ALLOWLIST` drops them all, because each one resolves into a field
+ * of its own — `role`, `name`, `description`, `state` — and those are the four
+ * kinds banded `a11y`. An `aria-*` delta arriving as `attribute-changed` would
+ * mean normalization had stopped resolving it, which is a defect rather than a
+ * banding question.
+ *
+ * Note that `rect-changed` is `geometry` while `style-changed` is `token`, even
+ * though a padding change produces both. That is intended: the two are reported
+ * at different bands from different evidence, and the attributor folds the rect
+ * movement into the style change as collateral. Under a profile without layout
+ * there is no rect evidence at all, and the style change stands alone — which is
+ * why JSDOM can decide the token band but only part of geometry.
+ *
+ * Policy may promote or demote from here per project, subject, region, or
+ * component (spec §5). This function is the default, not the answer.
+ */
+export declare function bandOf(kind: DeltaKind): Band;
+//# sourceMappingURL=band.d.ts.map

package/dist/compare/band.js

@@ -0,0 +1,70 @@
+/**
+ * Frequency bands (spec §5).
+ *
+ * Every semantic delta lands in exactly one band, and the band decides how loudly
+ * it is reported. The insight the bands encode: change frequency and change
+ * importance are inversely correlated. An accessible name almost never moves and
+ * is a defect when it does; anti-aliasing moves constantly and never matters.
+ *
+ * The list is ordered, loudest first, and `loudestBand` is the only thing allowed
+ * to collapse a set of them. Three call sites used to hard-code their own
+ * `if (bands.includes('geometry'))` ladder, which meant adding a band silently
+ * demoted it below everything in every one of them.
+ */
+/** Loudest first. `loudestBand` reads this order; nothing else may assume one. */
+export const BANDS = ['a11y', 'geometry', 'token', 'content', 'texture'];
+/**
+ * The loudest band present, or `null` for an empty set.
+ *
+ * `null` rather than a default, because "nothing changed" and "something changed
+ * at the quietest band" are different states and a caller that wants to conflate
+ * them should have to say so.
+ */
+export function loudestBand(bands) {
+    const present = new Set(bands);
+    return BANDS.find((band) => present.has(band)) ?? null;
+}
+/**
+ * The band a delta falls in, before policy.
+ *
+ * `attribute-changed` is `geometry` rather than `a11y` for a reason that is
+ * easy to get backwards: **no `aria-*` attribute ever reaches it.**
+ * `ATTRIBUTE_ALLOWLIST` drops them all, because each one resolves into a field
+ * of its own — `role`, `name`, `description`, `state` — and those are the four
+ * kinds banded `a11y`. An `aria-*` delta arriving as `attribute-changed` would
+ * mean normalization had stopped resolving it, which is a defect rather than a
+ * banding question.
+ *
+ * Note that `rect-changed` is `geometry` while `style-changed` is `token`, even
+ * though a padding change produces both. That is intended: the two are reported
+ * at different bands from different evidence, and the attributor folds the rect
+ * movement into the style change as collateral. Under a profile without layout
+ * there is no rect evidence at all, and the style change stands alone — which is
+ * why JSDOM can decide the token band but only part of geometry.
+ *
+ * Policy may promote or demote from here per project, subject, region, or
+ * component (spec §5). This function is the default, not the answer.
+ */
+export function bandOf(kind) {
+    switch (kind) {
+        case 'role-changed':
+        case 'name-changed':
+        case 'description-changed':
+        case 'state-changed':
+            return 'a11y';
+        case 'text-changed':
+            return 'content';
+        case 'node-added':
+        case 'node-removed':
+        case 'node-moved':
+        case 'attribute-changed':
+        case 'rect-changed':
+            return 'geometry';
+        case 'style-changed':
+        case 'token-changed':
+            return 'token';
+        case 'raster-residue':
+            return 'texture';
+    }
+}
+//# sourceMappingURL=band.js.map

package/dist/compare/band.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"band.js","sourceRoot":"","sources":["../../src/compare/band.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAwCH,kFAAkF;AAClF,MAAM,CAAC,MAAM,KAAK,GAAoB,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;AAE1F;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAqB;IAC/C,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IAC/B,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC;AACzD,CAAC;AAkBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,MAAM,CAAC,IAAe;IACpC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,cAAc,CAAC;QACpB,KAAK,cAAc,CAAC;QACpB,KAAK,qBAAqB,CAAC;QAC3B,KAAK,eAAe;YAClB,OAAO,MAAM,CAAC;QAChB,KAAK,cAAc;YACjB,OAAO,SAAS,CAAC;QACnB,KAAK,YAAY,CAAC;QAClB,KAAK,cAAc,CAAC;QACpB,KAAK,YAAY,CAAC;QAClB,KAAK,mBAAmB,CAAC;QACzB,KAAK,cAAc;YACjB,OAAO,UAAU,CAAC;QACpB,KAAK,eAAe,CAAC;QACrB,KAAK,eAAe;YAClB,OAAO,OAAO,CAAC;QACjB,KAAK,gBAAgB;YACnB,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC","sourcesContent":["/**\n * Frequency bands (spec §5).\n *\n * Every semantic delta lands in exactly one band, and the band decides how loudly\n * it is reported. The insight the bands encode: change frequency and change\n * importance are inversely correlated. An accessible name almost never moves and\n * is a defect when it does; anti-aliasing moves constantly and never matters.\n *\n * The list is ordered, loudest first, and `loudestBand` is the only thing allowed\n * to collapse a set of them. Three call sites used to hard-code their own\n * `if (bands.includes('geometry'))` ladder, which meant adding a band silently\n * demoted it below everything in every one of them.\n */\n\nexport type Band =\n  /**\n   * Rarest, and the one a picture cannot hold. A role, an accessible name, or an\n   * ARIA state changed — what a screen reader announces moved, whether or not\n   * anything was repainted.\n   *\n   * Split out of `geometry` deliberately. Both are low-frequency, but a box that\n   * moved and a control that lost its name are different findings for different\n   * readers, and folding the second into the first means the evidence this\n   * project collects and no image-comparison tool has is reported under a label\n   * that sounds like layout. A project can now write `blocking: ['a11y']` and\n   * have an accessibility regression stop a merge on its own terms.\n   */\n  | 'a11y'\n  /** Low frequency. Boxes appear, vanish, move, or resize; content reflows. */\n  | 'geometry'\n  /** Mid frequency. Style *values* moved while structure held. */\n  | 'token'\n  /**\n   * Text moved and nothing else did.\n   *\n   * The highest-frequency band that is still a real change: copy edits, counts,\n   * dates, translations. Quieter than `geometry` because a reviewer who is told\n   * a string changed does not also need to be told a box moved — the reflow is\n   * the consequence, and `geometry` outranks it exactly when the tree moved for\n   * some other reason too.\n   *\n   * It is separated from `geometry` because it is the band a message catalogue\n   * joins against. A locale run compares the same subject's `content` across two\n   * languages, which is a question no baseline image can be asked.\n   */\n  | 'content'\n  /**\n   * High frequency. Sub-semantic rendering variance — anti-aliasing, sub-pixel\n   * shifts, compression artifacts. Auto-passes; counted, never reviewed.\n   */\n  | 'texture';\n\n/** Loudest first. `loudestBand` reads this order; nothing else may assume one. */\nexport const BANDS: readonly Band[] = ['a11y', 'geometry', 'token', 'content', 'texture'];\n\n/**\n * The loudest band present, or `null` for an empty set.\n *\n * `null` rather than a default, because \"nothing changed\" and \"something changed\n * at the quietest band\" are different states and a caller that wants to conflate\n * them should have to say so.\n */\nexport function loudestBand(bands: Iterable<Band>): Band | null {\n  const present = new Set(bands);\n  return BANDS.find((band) => present.has(band)) ?? null;\n}\n\n/** What kind of thing changed, before policy has an opinion about it. */\nexport type DeltaKind =\n  | 'node-added'\n  | 'node-removed'\n  | 'node-moved'\n  | 'role-changed'\n  | 'name-changed'\n  | 'description-changed'\n  | 'state-changed'\n  | 'text-changed'\n  | 'attribute-changed'\n  | 'rect-changed'\n  | 'style-changed'\n  | 'token-changed'\n  | 'raster-residue';\n\n/**\n * The band a delta falls in, before policy.\n *\n * `attribute-changed` is `geometry` rather than `a11y` for a reason that is\n * easy to get backwards: **no `aria-*` attribute ever reaches it.**\n * `ATTRIBUTE_ALLOWLIST` drops them all, because each one resolves into a field\n * of its own — `role`, `name`, `description`, `state` — and those are the four\n * kinds banded `a11y`. An `aria-*` delta arriving as `attribute-changed` would\n * mean normalization had stopped resolving it, which is a defect rather than a\n * banding question.\n *\n * Note that `rect-changed` is `geometry` while `style-changed` is `token`, even\n * though a padding change produces both. That is intended: the two are reported\n * at different bands from different evidence, and the attributor folds the rect\n * movement into the style change as collateral. Under a profile without layout\n * there is no rect evidence at all, and the style change stands alone — which is\n * why JSDOM can decide the token band but only part of geometry.\n *\n * Policy may promote or demote from here per project, subject, region, or\n * component (spec §5). This function is the default, not the answer.\n */\nexport function bandOf(kind: DeltaKind): Band {\n  switch (kind) {\n    case 'role-changed':\n    case 'name-changed':\n    case 'description-changed':\n    case 'state-changed':\n      return 'a11y';\n    case 'text-changed':\n      return 'content';\n    case 'node-added':\n    case 'node-removed':\n    case 'node-moved':\n    case 'attribute-changed':\n    case 'rect-changed':\n      return 'geometry';\n    case 'style-changed':\n    case 'token-changed':\n      return 'token';\n    case 'raster-residue':\n      return 'texture';\n  }\n}\n"]}

package/dist/compare/cascade.d.ts

@@ -0,0 +1,45 @@
+import type { SemanticNode, SemanticSnapshot } from '../format/snapshot.js';
+import type { MovedInput } from './parting.js';
+/**
+ * The input nobody passes.
+ *
+ * Every rung in `parting.ts` above this one reads something a boundary
+ * *received* — a prop, a context, a hook cell — and all three arrive through a
+ * framework adapter. This one reads what the boundary did not receive and did
+ * not declare, out of the snapshot itself, which is why it is the only rung a
+ * run with no adapter attached can reach.
+ */
+/**
+ * Every property some declaration set *at* a node, keyed by node and name.
+ *
+ * `styleProvenance` records where each winning declaration came from, so the
+ * properties it does not mention at a node are exactly the ones that arrived
+ * from somewhere else — which is the whole reading below.
+ */
+export declare function declaredIn(snapshot: SemanticSnapshot): ReadonlySet<string>;
+/**
+ * What an ancestor decided, and the rung that stops this being called a flake.
+ *
+ * A component that sets its own font and no colour paints white on a dark panel
+ * and near-black on a light card from one set of props. Every input the holding
+ * carries — props, contexts, hook cells — is byte-identical across the two, so
+ * before this existed the boundary settled at `undetermined` and `explainParting`
+ * called a perfectly deterministic component *nondeterministic*. That is the
+ * accusation ADR-0002 forbids making about an input nobody read, and the input
+ * was there to be read: the resolved value is on the node and `styleProvenance`
+ * says no declaration here produced it.
+ *
+ * So the reading is the difference between those two facts — **in the style,
+ * not in the provenance** — and a property that differs on that test came from
+ * an ancestor's cascade. It ranks with `handed` and `provided` because it says
+ * the same thing they do: the cause is above this boundary, not in it.
+ *
+ * Values are digested rather than carried, so that every `MovedInput` means one
+ * thing regardless of kind. The property name is the part a reader acts on, and
+ * the deltas already name what it turned into on the page.
+ *
+ * Unpaired boundaries contribute nothing: a component present on one side only
+ * has not inherited differently, it has not been compared.
+ */
+export declare function cascadeInputs(left: SemanticNode | undefined, right: SemanticNode, there: ReadonlySet<string>, here: ReadonlySet<string>): readonly MovedInput[];
+//# sourceMappingURL=cascade.d.ts.map

package/dist/compare/cascade.js

@@ -0,0 +1,71 @@
+import { digestValue } from '../format/hash.js';
+/**
+ * The input nobody passes.
+ *
+ * Every rung in `parting.ts` above this one reads something a boundary
+ * *received* — a prop, a context, a hook cell — and all three arrive through a
+ * framework adapter. This one reads what the boundary did not receive and did
+ * not declare, out of the snapshot itself, which is why it is the only rung a
+ * run with no adapter attached can reach.
+ */
+/**
+ * Every property some declaration set *at* a node, keyed by node and name.
+ *
+ * `styleProvenance` records where each winning declaration came from, so the
+ * properties it does not mention at a node are exactly the ones that arrived
+ * from somewhere else — which is the whole reading below.
+ */
+export function declaredIn(snapshot) {
+    return new Set(snapshot.styleProvenance.map(keyOf));
+}
+function keyOf(entry) {
+    return `${entry.path}\u0000${entry.property}`;
+}
+/**
+ * What an ancestor decided, and the rung that stops this being called a flake.
+ *
+ * A component that sets its own font and no colour paints white on a dark panel
+ * and near-black on a light card from one set of props. Every input the holding
+ * carries — props, contexts, hook cells — is byte-identical across the two, so
+ * before this existed the boundary settled at `undetermined` and `explainParting`
+ * called a perfectly deterministic component *nondeterministic*. That is the
+ * accusation ADR-0002 forbids making about an input nobody read, and the input
+ * was there to be read: the resolved value is on the node and `styleProvenance`
+ * says no declaration here produced it.
+ *
+ * So the reading is the difference between those two facts — **in the style,
+ * not in the provenance** — and a property that differs on that test came from
+ * an ancestor's cascade. It ranks with `handed` and `provided` because it says
+ * the same thing they do: the cause is above this boundary, not in it.
+ *
+ * Values are digested rather than carried, so that every `MovedInput` means one
+ * thing regardless of kind. The property name is the part a reader acts on, and
+ * the deltas already name what it turned into on the page.
+ *
+ * Unpaired boundaries contribute nothing: a component present on one side only
+ * has not inherited differently, it has not been compared.
+ */
+export function cascadeInputs(left, right, there, here) {
+    if (left === undefined)
+        return [];
+    const before = inheritedAt(left, there);
+    const after = inheritedAt(right, here);
+    const moved = [];
+    for (const name of [...new Set([...before.keys(), ...after.keys()])].sort()) {
+        const from = before.get(name);
+        const to = after.get(name);
+        if (from !== to)
+            moved.push({ kind: 'inherited', name, from, to });
+    }
+    return moved;
+}
+function inheritedAt(node, declared) {
+    const found = new Map();
+    for (const [property, value] of Object.entries(node.style)) {
+        if (declared.has(`${node.path}\u0000${property}`))
+            continue;
+        found.set(property, digestValue(value));
+    }
+    return found;
+}
+//# sourceMappingURL=cascade.js.map

package/dist/compare/cascade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cascade.js","sourceRoot":"","sources":["../../src/compare/cascade.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAe,MAAM,mBAAmB,CAAC;AAI7D;;;;;;;;GAQG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,QAA0B;IACnD,OAAO,IAAI,GAAG,CAAC,QAAQ,CAAC,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;AACtD,CAAC;AAED,SAAS,KAAK,CAAC,KAA2B;IACxC,OAAO,GAAG,KAAK,CAAC,IAAI,SAAS,KAAK,CAAC,QAAQ,EAAE,CAAC;AAChD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,aAAa,CAC3B,IAA8B,EAC9B,KAAmB,EACnB,KAA0B,EAC1B,IAAyB;IAEzB,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IAElC,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACxC,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACvC,MAAM,KAAK,GAAiB,EAAE,CAAC;IAE/B,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,EAAE,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAC5E,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,IAAI,KAAK,EAAE;YAAE,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,WAAW,CAAC,IAAkB,EAAE,QAA6B;IACpE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,KAAK,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3D,IAAI,QAAQ,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,IAAI,SAAS,QAAQ,EAAE,CAAC;YAAE,SAAS;QAC5D,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC","sourcesContent":["import { digestValue, type Digest } from '../format/hash.js';\nimport type { SemanticNode, SemanticSnapshot, StyleProvenanceEntry } from '../format/snapshot.js';\nimport type { MovedInput } from './parting.js';\n\n/**\n * The input nobody passes.\n *\n * Every rung in `parting.ts` above this one reads something a boundary\n * *received* — a prop, a context, a hook cell — and all three arrive through a\n * framework adapter. This one reads what the boundary did not receive and did\n * not declare, out of the snapshot itself, which is why it is the only rung a\n * run with no adapter attached can reach.\n */\n\n/**\n * Every property some declaration set *at* a node, keyed by node and name.\n *\n * `styleProvenance` records where each winning declaration came from, so the\n * properties it does not mention at a node are exactly the ones that arrived\n * from somewhere else — which is the whole reading below.\n */\nexport function declaredIn(snapshot: SemanticSnapshot): ReadonlySet<string> {\n  return new Set(snapshot.styleProvenance.map(keyOf));\n}\n\nfunction keyOf(entry: StyleProvenanceEntry): string {\n  return `${entry.path}\\u0000${entry.property}`;\n}\n\n/**\n * What an ancestor decided, and the rung that stops this being called a flake.\n *\n * A component that sets its own font and no colour paints white on a dark panel\n * and near-black on a light card from one set of props. Every input the holding\n * carries — props, contexts, hook cells — is byte-identical across the two, so\n * before this existed the boundary settled at `undetermined` and `explainParting`\n * called a perfectly deterministic component *nondeterministic*. That is the\n * accusation ADR-0002 forbids making about an input nobody read, and the input\n * was there to be read: the resolved value is on the node and `styleProvenance`\n * says no declaration here produced it.\n *\n * So the reading is the difference between those two facts — **in the style,\n * not in the provenance** — and a property that differs on that test came from\n * an ancestor's cascade. It ranks with `handed` and `provided` because it says\n * the same thing they do: the cause is above this boundary, not in it.\n *\n * Values are digested rather than carried, so that every `MovedInput` means one\n * thing regardless of kind. The property name is the part a reader acts on, and\n * the deltas already name what it turned into on the page.\n *\n * Unpaired boundaries contribute nothing: a component present on one side only\n * has not inherited differently, it has not been compared.\n */\nexport function cascadeInputs(\n  left: SemanticNode | undefined,\n  right: SemanticNode,\n  there: ReadonlySet<string>,\n  here: ReadonlySet<string>,\n): readonly MovedInput[] {\n  if (left === undefined) return [];\n\n  const before = inheritedAt(left, there);\n  const after = inheritedAt(right, here);\n  const moved: MovedInput[] = [];\n\n  for (const name of [...new Set([...before.keys(), ...after.keys()])].sort()) {\n    const from = before.get(name);\n    const to = after.get(name);\n    if (from !== to) moved.push({ kind: 'inherited', name, from, to });\n  }\n\n  return moved;\n}\n\nfunction inheritedAt(node: SemanticNode, declared: ReadonlySet<string>): Map<string, Digest> {\n  const found = new Map<string, Digest>();\n  for (const [property, value] of Object.entries(node.style)) {\n    if (declared.has(`${node.path}\\u0000${property}`)) continue;\n    found.set(property, digestValue(value));\n  }\n  return found;\n}\n"]}

package/dist/compare/derive.d.ts

@@ -0,0 +1,78 @@
+import { type Digest } from '../format/hash.js';
+import type { SemanticSnapshot } from '../format/snapshot.js';
+import type { EnvironmentDelta } from '../format/environment.js';
+import { type Band } from './band.js';
+import type { AggregateImpact } from './impact.js';
+import { type ChangedComponent, type Delta, type Root } from './diff/index.js';
+/**
+ * One subject read as a variation of another.
+ *
+ * The same arithmetic a verdict is made of, pointed at a pair of subjects
+ * somebody linked on purpose: a dark story against its light parent, a mobile
+ * viewport against the desktop one, a story behind a feature flag against the
+ * story it was copied from. Nothing here is compared against a baseline and
+ * nothing here is a verdict — a variation *is* a difference, so reporting it as a
+ * regression would be reporting the subject for existing.
+ *
+ * What it answers is the question a second case cannot: **a new story under a
+ * flag is a new baseline and an empty diff, and everybody has to open two
+ * pictures to see what the flag does.** Linked, the difference is a value with an
+ * identity, and the identity is the useful part — see {@link Variation.digest}.
+ */
+export interface Variation {
+    /** The variation's own subject id. */
+    readonly subject: string;
+    /** The subject it declares itself a variation of. */
+    readonly parent: string;
+    /** `true` when the two renders hash identically — the flag changed nothing. */
+    readonly identical: boolean;
+    readonly deltas: readonly Delta[];
+    readonly roots: readonly Root[];
+    readonly components: readonly ChangedComponent[];
+    readonly impact: AggregateImpact;
+    /** Bands the difference falls in, in band order. Empty when identical. */
+    readonly bands: readonly Band[];
+    /**
+     * Bands **either** side's profile could not decide.
+     *
+     * Union rather than intersection, and never dropped: a jsdom side has no
+     * geometry, and a variation that reported no geometry difference because
+     * nothing could measure one would be the false `unchanged` this project exists
+     * to refuse (ADR-0002).
+     */
+    readonly unobserved: readonly Band[];
+    /**
+     * Render inputs that differ between the two sides.
+     *
+     * Reported, never a refusal. A variation is frequently a *deliberate*
+     * environment difference — a viewport, a colour scheme — and the field that
+     * would make `diffSnapshots` refuse the pair is here the thing being examined.
+     */
+    readonly environmentDeltas: readonly EnvironmentDelta[];
+    /**
+     * The identity of the difference itself: `variation/v1` over the deltas.
+     *
+     * The field that makes a linked pair worth more than two pictures. A parent and
+     * its variation both move by the same edit — a token changed, both re-render,
+     * both go red — and this digest does not move, because what the variation *adds*
+     * to its parent is unchanged. So the reviewer's question stops being "did these
+     * two subjects change" and becomes "did what this flag does change", which is
+     * the question they were trying to ask.
+     *
+     * Positions and values are in it and owner chains are not. An owner frame
+     * carries a props digest per frame, so hashing it would make the identity move
+     * whenever any component above the change was handed a different object —
+     * which is a fact about the render, not about the difference.
+     */
+    readonly digest: Digest;
+}
+/**
+ * Compare a variation against the subject it derives from.
+ *
+ * Refuses nothing. Two subject ids are the input this function exists for, and
+ * two profiles or two environments are reported as part of the answer — see
+ * `compareTrees` for why the refusals live with the caller that owes them rather
+ * than with the arithmetic.
+ */
+export declare function deriveVariation(parent: SemanticSnapshot, variant: SemanticSnapshot): Variation;
+//# sourceMappingURL=derive.d.ts.map

package/dist/compare/derive.js

@@ -0,0 +1,39 @@
+import { digestCombine, digestValue } from '../format/hash.js';
+import { BANDS } from './band.js';
+import { compareTrees } from './diff/index.js';
+/**
+ * Compare a variation against the subject it derives from.
+ *
+ * Refuses nothing. Two subject ids are the input this function exists for, and
+ * two profiles or two environments are reported as part of the answer — see
+ * `compareTrees` for why the refusals live with the caller that owes them rather
+ * than with the arithmetic.
+ */
+export function deriveVariation(parent, variant) {
+    const compared = compareTrees(parent, variant);
+    const moved = new Set(compared.deltas.map((delta) => delta.band));
+    return {
+        subject: variant.subject.id,
+        parent: parent.subject.id,
+        ...compared,
+        bands: BANDS.filter((band) => moved.has(band)),
+        digest: digestOfDifference(compared.deltas),
+    };
+}
+/**
+ * `variation/v1` over what each delta *is*, in the order the comparison produced.
+ *
+ * Order is the comparison's, which is a function of the two trees and of nothing
+ * else — sorting here would cost a walk to buy stability the input already has.
+ */
+function digestOfDifference(deltas) {
+    return digestCombine('variation/v1', deltas.map((delta) => digestValue({
+        kind: delta.kind,
+        band: delta.band,
+        path: delta.path,
+        property: delta.property,
+        from: delta.from,
+        to: delta.to,
+    })));
+}
+//# sourceMappingURL=derive.js.map

package/dist/compare/derive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.js","sourceRoot":"","sources":["../../src/compare/derive.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,WAAW,EAAe,MAAM,mBAAmB,CAAC;AAG5E,OAAO,EAAE,KAAK,EAAa,MAAM,WAAW,CAAC;AAE7C,OAAO,EAAE,YAAY,EAAgD,MAAM,iBAAiB,CAAC;AAuE7F;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,MAAwB,EAAE,OAAyB;IACjF,MAAM,QAAQ,GAAG,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/C,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IAElE,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE;QAC3B,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE;QACzB,GAAG,QAAQ;QACX,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC9C,MAAM,EAAE,kBAAkB,CAAC,QAAQ,CAAC,MAAM,CAAC;KAC5C,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,kBAAkB,CAAC,MAAwB;IAClD,OAAO,aAAa,CAClB,cAAc,EACd,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CACnB,WAAW,CAAC;QACV,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,EAAE,EAAE,KAAK,CAAC,EAAE;KACb,CAAC,CACH,CACF,CAAC;AACJ,CAAC","sourcesContent":["import { digestCombine, digestValue, type Digest } from '../format/hash.js';\nimport type { SemanticSnapshot } from '../format/snapshot.js';\nimport type { EnvironmentDelta } from '../format/environment.js';\nimport { BANDS, type Band } from './band.js';\nimport type { AggregateImpact } from './impact.js';\nimport { compareTrees, type ChangedComponent, type Delta, type Root } from './diff/index.js';\n\n/**\n * One subject read as a variation of another.\n *\n * The same arithmetic a verdict is made of, pointed at a pair of subjects\n * somebody linked on purpose: a dark story against its light parent, a mobile\n * viewport against the desktop one, a story behind a feature flag against the\n * story it was copied from. Nothing here is compared against a baseline and\n * nothing here is a verdict — a variation *is* a difference, so reporting it as a\n * regression would be reporting the subject for existing.\n *\n * What it answers is the question a second case cannot: **a new story under a\n * flag is a new baseline and an empty diff, and everybody has to open two\n * pictures to see what the flag does.** Linked, the difference is a value with an\n * identity, and the identity is the useful part — see {@link Variation.digest}.\n */\nexport interface Variation {\n  /** The variation's own subject id. */\n  readonly subject: string;\n  /** The subject it declares itself a variation of. */\n  readonly parent: string;\n\n  /** `true` when the two renders hash identically — the flag changed nothing. */\n  readonly identical: boolean;\n\n  readonly deltas: readonly Delta[];\n  readonly roots: readonly Root[];\n  readonly components: readonly ChangedComponent[];\n  readonly impact: AggregateImpact;\n\n  /** Bands the difference falls in, in band order. Empty when identical. */\n  readonly bands: readonly Band[];\n\n  /**\n   * Bands **either** side's profile could not decide.\n   *\n   * Union rather than intersection, and never dropped: a jsdom side has no\n   * geometry, and a variation that reported no geometry difference because\n   * nothing could measure one would be the false `unchanged` this project exists\n   * to refuse (ADR-0002).\n   */\n  readonly unobserved: readonly Band[];\n\n  /**\n   * Render inputs that differ between the two sides.\n   *\n   * Reported, never a refusal. A variation is frequently a *deliberate*\n   * environment difference — a viewport, a colour scheme — and the field that\n   * would make `diffSnapshots` refuse the pair is here the thing being examined.\n   */\n  readonly environmentDeltas: readonly EnvironmentDelta[];\n\n  /**\n   * The identity of the difference itself: `variation/v1` over the deltas.\n   *\n   * The field that makes a linked pair worth more than two pictures. A parent and\n   * its variation both move by the same edit — a token changed, both re-render,\n   * both go red — and this digest does not move, because what the variation *adds*\n   * to its parent is unchanged. So the reviewer's question stops being \"did these\n   * two subjects change\" and becomes \"did what this flag does change\", which is\n   * the question they were trying to ask.\n   *\n   * Positions and values are in it and owner chains are not. An owner frame\n   * carries a props digest per frame, so hashing it would make the identity move\n   * whenever any component above the change was handed a different object —\n   * which is a fact about the render, not about the difference.\n   */\n  readonly digest: Digest;\n}\n\n/**\n * Compare a variation against the subject it derives from.\n *\n * Refuses nothing. Two subject ids are the input this function exists for, and\n * two profiles or two environments are reported as part of the answer — see\n * `compareTrees` for why the refusals live with the caller that owes them rather\n * than with the arithmetic.\n */\nexport function deriveVariation(parent: SemanticSnapshot, variant: SemanticSnapshot): Variation {\n  const compared = compareTrees(parent, variant);\n  const moved = new Set(compared.deltas.map((delta) => delta.band));\n\n  return {\n    subject: variant.subject.id,\n    parent: parent.subject.id,\n    ...compared,\n    bands: BANDS.filter((band) => moved.has(band)),\n    digest: digestOfDifference(compared.deltas),\n  };\n}\n\n/**\n * `variation/v1` over what each delta *is*, in the order the comparison produced.\n *\n * Order is the comparison's, which is a function of the two trees and of nothing\n * else — sorting here would cost a walk to buy stability the input already has.\n */\nfunction digestOfDifference(deltas: readonly Delta[]): Digest {\n  return digestCombine(\n    'variation/v1',\n    deltas.map((delta) =>\n      digestValue({\n        kind: delta.kind,\n        band: delta.band,\n        path: delta.path,\n        property: delta.property,\n        from: delta.from,\n        to: delta.to,\n      }),\n    ),\n  );\n}\n"]}

package/dist/compare/diff/attribution.d.ts

@@ -0,0 +1,23 @@
+import type { EnvironmentDelta } from '../../format/environment.js';
+import { type Delta, type Root } from './delta.js';
+import type { Matching } from './match.js';
+/**
+ * Grouping deltas into explanations — the docket's entire value proposition.
+ *
+ * Separated from `index.ts` because it is the half of diffing that has nothing
+ * to do with observation: it takes deltas that already exist and decides which
+ * *one* sentence covers them. The precedence rules, the metric-delta folding and
+ * the boundary walk are all in service of the same claim — report the largest
+ * explanation once rather than the smallest one many times — and they only make
+ * sense read together.
+ */
+/**
+ * Group deltas into explanations (spec §6.2).
+ *
+ * Precedence is fixed and deliberate: environment, then token, then props, then
+ * component. Each level explains more subjects than the one below it, and the
+ * docket's value is entirely in reporting the *largest* explanation once rather
+ * than the smallest one many times.
+ */
+export declare function attribute(deltas: readonly Delta[], matching: Matching, environmentDeltas: readonly EnvironmentDelta[]): readonly Root[];
+//# sourceMappingURL=attribution.d.ts.map