@variance-authority/core 0.1.0

package/dist/attribute/call-site.js

@@ -0,0 +1,183 @@
+import { inlineSourceMapOf, originalPositionFor, parseSourceMap, sourceMappingUrlOf, } from './source-map.js';
+import { isVendorPath, writerLocationOf } from './stack.js';
+export function createCallSiteResolver(fetchModule) {
+    /** Module URL → its map, `null` once we know it has none. Also the in-flight guard. */
+    const maps = new Map();
+    /** `url:line:column` → the answer, so a page's 4211 nodes cost 14 resolutions. */
+    const sites = new Map();
+    const stats = { modules: 0, sites: 0, located: 0 };
+    async function mapsFor(url) {
+        const cached = maps.get(url);
+        if (cached !== undefined)
+            return cached;
+        const pending = (async () => {
+            stats.modules += 1;
+            const code = await fetchModule(url);
+            if (code === null)
+                return null;
+            const annotation = sourceMappingUrlOf(code);
+            if (annotation === null)
+                return null;
+            const inline = inlineSourceMapOf(annotation);
+            if (inline !== null)
+                return parseSourceMap(inline);
+            // A sibling file, which is what a production bundler writes. Resolved
+            // against the module rather than the page: `//# sourceMappingURL=out.js.map`
+            // means "beside this module", and a page several directories deep would
+            // otherwise ask for it in the wrong place.
+            const sibling = absolute(annotation, url);
+            const text = sibling === null ? null : await fetchModule(sibling);
+            return text === null ? null : parseSourceMap(text);
+        })();
+        maps.set(url, pending);
+        return pending;
+    }
+    async function locateFrame(frame) {
+        const parsed = await mapsFor(frame.url);
+        // No map is not failure. A dev server serving a plain `.js` as written, and a
+        // Node test runner — which applies source maps to `Error.stack` itself, so
+        // the frame arrives already original — both land here with the answer in
+        // hand. `writerLocationOf` keeps the frame's own coordinates in that case.
+        if (parsed === null || parsed.length === 0)
+            return null;
+        const original = originalPositionFor(parsed, frame.line, frame.column);
+        if (original === null)
+            return null;
+        return {
+            file: sourcePath(original.source, frame.url),
+            line: original.line,
+            column: original.column,
+        };
+    }
+    async function locate(frames) {
+        for (const frame of frames) {
+            if (isVendorPath(frame.url))
+                continue;
+            const key = `${frame.url}:${frame.line}:${frame.column}`;
+            let answer = sites.get(key);
+            if (answer === undefined) {
+                stats.sites += 1;
+                answer = locateFrame(frame);
+                sites.set(key, answer);
+            }
+            const located = await answer;
+            // The frame's own coordinates, for a module served as written. Delegated so
+            // there is one statement of the choosing rule rather than two.
+            const chosen = located === null
+                ? writerLocationOf([frame], () => null)
+                : isVendorPath(located.file)
+                    ? null
+                    : located;
+            if (chosen !== null) {
+                stats.located += 1;
+                return chosen;
+            }
+        }
+        return null;
+    }
+    return { locate, stats: stats };
+}
+/**
+ * Provenance with its frames spent: `source` filled in, `stack` gone.
+ *
+ * Returned unchanged when there is nothing to do — which is the common case once
+ * a project installs `jsx-source`, and the case a production build is always in.
+ * Never throws: a report that names a location for most of its nodes is the
+ * normal outcome, and one node's unreachable module must not take the run down.
+ */
+export async function locateProvenance(provenance, resolver) {
+    const { stack, ...carried } = provenance;
+    if (stack === undefined || stack.length === 0)
+        return provenance;
+    let source = null;
+    try {
+        source = await resolver.locate(stack);
+    }
+    catch {
+        source = null;
+    }
+    return source === null ? carried : { ...carried, source };
+}
+/**
+ * The line for each site a report is about to name, and for nothing else.
+ *
+ * This is the demand side of the zero-install path. The page reads frames off
+ * every fiber because reading them is nearly free; turning one into a file is
+ * not, and this is the only place that spends it.
+ *
+ * Three ways a site costs nothing, all of them the common case:
+ *
+ * - **It has no `path`.** A region no box contains names no node.
+ * - **It already has a `source`.** React ≤18 and `@variance-authority/jsx-source`
+ *   both record the location outright, so there is nothing to resolve. Only
+ *   React 19, which throws its location away and captures an `Error` instead,
+ *   reaches the map.
+ * - **Its node carried no frames.** A production build captures nothing.
+ *
+ * And a subject that settled on its document digest never calls this at all,
+ * which is the point: no region, no finding, no fetch.
+ *
+ * Sites are resolved concurrently. The resolver's own cache collapses them onto
+ * the modules they share, so two regions in one component cost one fetch.
+ */
+export async function locateSites(sites, snapshot, resolver) {
+    const wanted = sites.some((site) => site.source === undefined && site.path !== undefined);
+    if (!wanted)
+        return sites;
+    // Built once and only when something asked. A path lookup on a tree is a walk,
+    // and doing it per site would make a fifty-region page walk it fifty times.
+    const nodes = index(snapshot.root);
+    const located = await Promise.all(sites.map(async (site) => {
+        if (site.source !== undefined || site.path === undefined)
+            return site;
+        const provenance = nodes.get(site.path)?.provenance;
+        if (provenance?.stack === undefined)
+            return site;
+        const spent = await locateProvenance(provenance, resolver);
+        return spent.source === undefined ? site : { ...site, source: spent.source };
+    }));
+    return located.every((site, at) => site === sites[at]) ? sites : located;
+}
+function index(root) {
+    const nodes = new Map();
+    const walk = (node) => {
+        nodes.set(node.path, node);
+        for (const child of node.children)
+            walk(child);
+    };
+    walk(root);
+    return nodes;
+}
+/**
+ * A map's `sources` entry as a path, resolved against the module it describes.
+ *
+ * Maps state sources relatively — Vite writes `probe.jsx` for `/src/probe.jsx` —
+ * so the entry alone is ambiguous between two directories. Resolved and then
+ * stripped to a path, because the origin is a fact about the machine that ran
+ * the capture: a baseline holding `http://localhost:5199/src/probe.jsx` would
+ * disagree with the next run on a different port. What is left is what the
+ * source index and `relativizeSource` already speak.
+ */
+function sourcePath(source, moduleUrl) {
+    const resolved = absolute(source, moduleUrl) ?? source;
+    const parsed = parseUrl(resolved);
+    // Not a URL: a bundler that wrote an absolute filesystem path, or a
+    // `webpack://` specifier. Left as it is — `relativizeSource` handles the
+    // first, and inventing a shape for the second would be a guess.
+    return parsed === null ? resolved : parsed.pathname.replace(/^\/+/, '');
+}
+function absolute(url, base) {
+    return parseUrl(url, base)?.href ?? null;
+}
+const URL_OF = globalThis.URL;
+function parseUrl(url, base) {
+    if (URL_OF === undefined)
+        return null;
+    try {
+        return new URL_OF(url, base);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=call-site.js.map

package/dist/attribute/call-site.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-site.js","sourceRoot":"","sources":["../../src/attribute/call-site.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Provenance, SourceLocation, StackFrame } from '../format/provenance.js';\nimport type { NodePath, SemanticNode, SemanticSnapshot } from '../format/snapshot.js';\nimport {\n  inlineSourceMapOf,\n  originalPositionFor,\n  parseSourceMap,\n  sourceMappingUrlOf,\n  type SourceMap,\n} from './source-map.js';\nimport { isVendorPath, writerLocationOf } from './stack.js';\n\n/**\n * Spending the frames a page read, to get the file a reviewer opens.\n *\n * This is the half of the zero-install path that cannot happen in the page. A\n * frame names the module the browser was *served*, and turning that into a line\n * in the repository means fetching that module and reading the source map the\n * build already emitted beside it. Fetching is not something a page agent should\n * do — it runs inside somebody else's application, on a budget measured against\n * their render loop — and it is exactly what the collector is for.\n *\n * **The economics are what make this worth doing rather than clever.** Measured\n * on a 4211-node document: every fiber carried a stack, and between them they\n * held **14 distinct call sites**. A hundred-row table writes two thousand cells\n * from one line of JSX. So the work is per *call site*, not per node, and the\n * cache below is not an optimization but the thing that makes the cost bounded —\n * a handful of module fetches for a whole page.\n *\n * **And it is asked on a signal rather than on every capture.** Fourteen sites is\n * a bounded cost, not a free one, and a run that settles every subject on its\n * document digest has nobody to hand a location to: no region was drawn, no\n * finding was raised, and the fetches would answer a question nothing asked. So\n * frames ride the snapshot — they are provenance, and no hash projects\n * provenance — and {@link locateSites} spends them for the handful of nodes a\n * report is about to name. A page whose only change is one button resolves one\n * call site, not fourteen; a page that did not change resolves none.\n *\n * `fetchModule` is injected because `core` may not assume a network (ADR-0013),\n * and because the right way to fetch differs by caller: a browser-driving\n * collector should fetch from the page's own context, where the origin, the\n * cookies and the dev server's module graph are already correct.\n */\n\n/** Fetch a module's text, or answer that it cannot be had. Never throws. */\nexport type FetchModule = (url: string) => Promise<string | null>;\n\nexport interface CallSiteResolver {\n  /** The location that wrote an element, from the frames its fiber carried. */\n  locate(frames: readonly StackFrame[]): Promise<SourceLocation | null>;\n  /** How many modules were fetched, and how many call sites they answered. */\n  readonly stats: CallSiteStats;\n}\n\nexport interface CallSiteStats {\n  /** Distinct modules fetched. The number that costs anything. */\n  readonly modules: number;\n  /** Distinct call sites asked about — the ratio to `modules` is the point. */\n  readonly sites: number;\n  /** Call sites that resolved to a file. */\n  readonly located: number;\n}\n\nexport function createCallSiteResolver(fetchModule: FetchModule): CallSiteResolver {\n  /** Module URL → its map, `null` once we know it has none. Also the in-flight guard. */\n  const maps = new Map<string, Promise<readonly SourceMap[] | null>>();\n  /** `url:line:column` → the answer, so a page's 4211 nodes cost 14 resolutions. */\n  const sites = new Map<string, Promise<SourceLocation | null>>();\n\n  const stats = { modules: 0, sites: 0, located: 0 };\n\n  async function mapsFor(url: string): Promise<readonly SourceMap[] | null> {\n    const cached = maps.get(url);\n    if (cached !== undefined) return cached;\n\n    const pending = (async () => {\n      stats.modules += 1;\n\n      const code = await fetchModule(url);\n      if (code === null) return null;\n\n      const annotation = sourceMappingUrlOf(code);\n      if (annotation === null) return null;\n\n      const inline = inlineSourceMapOf(annotation);\n      if (inline !== null) return parseSourceMap(inline);\n\n      // A sibling file, which is what a production bundler writes. Resolved\n      // against the module rather than the page: `//# sourceMappingURL=out.js.map`\n      // means \"beside this module\", and a page several directories deep would\n      // otherwise ask for it in the wrong place.\n      const sibling = absolute(annotation, url);\n      const text = sibling === null ? null : await fetchModule(sibling);\n      return text === null ? null : parseSourceMap(text);\n    })();\n\n    maps.set(url, pending);\n    return pending;\n  }\n\n  async function locateFrame(frame: StackFrame): Promise<SourceLocation | null> {\n    const parsed = await mapsFor(frame.url);\n\n    // No map is not failure. A dev server serving a plain `.js` as written, and a\n    // Node test runner — which applies source maps to `Error.stack` itself, so\n    // the frame arrives already original — both land here with the answer in\n    // hand. `writerLocationOf` keeps the frame's own coordinates in that case.\n    if (parsed === null || parsed.length === 0) return null;\n\n    const original = originalPositionFor(parsed, frame.line, frame.column);\n    if (original === null) return null;\n\n    return {\n      file: sourcePath(original.source, frame.url),\n      line: original.line,\n      column: original.column,\n    };\n  }\n\n  async function locate(frames: readonly StackFrame[]): Promise<SourceLocation | null> {\n    for (const frame of frames) {\n      if (isVendorPath(frame.url)) continue;\n\n      const key = `${frame.url}:${frame.line}:${frame.column}`;\n      let answer = sites.get(key);\n\n      if (answer === undefined) {\n        stats.sites += 1;\n        answer = locateFrame(frame);\n        sites.set(key, answer);\n      }\n\n      const located = await answer;\n\n      // The frame's own coordinates, for a module served as written. Delegated so\n      // there is one statement of the choosing rule rather than two.\n      const chosen =\n        located === null\n          ? writerLocationOf([frame], () => null)\n          : isVendorPath(located.file)\n            ? null\n            : located;\n\n      if (chosen !== null) {\n        stats.located += 1;\n        return chosen;\n      }\n    }\n\n    return null;\n  }\n\n  return { locate, stats: stats as CallSiteStats };\n}\n\n/**\n * Provenance with its frames spent: `source` filled in, `stack` gone.\n *\n * Returned unchanged when there is nothing to do — which is the common case once\n * a project installs `jsx-source`, and the case a production build is always in.\n * Never throws: a report that names a location for most of its nodes is the\n * normal outcome, and one node's unreachable module must not take the run down.\n */\nexport async function locateProvenance(\n  provenance: Provenance,\n  resolver: CallSiteResolver,\n): Promise<Provenance> {\n  const { stack, ...carried } = provenance;\n  if (stack === undefined || stack.length === 0) return provenance;\n\n  let source: SourceLocation | null = null;\n  try {\n    source = await resolver.locate(stack);\n  } catch {\n    source = null;\n  }\n\n  return source === null ? carried : { ...carried, source };\n}\n\n/**\n * Anything a report points at: it names a node, and may already know its line.\n *\n * An `AttributedRegion` and a `Finding` are both this, arrived at from opposite\n * directions — one from a mask, one from an inspection — and both are the *few*.\n * That is the whole reason this shape is worth having rather than two functions:\n * what makes resolution affordable is being asked about a handful of nodes, and\n * a handful is what a region list and a finding list are.\n */\nexport interface LocatableSite {\n  readonly path?: NodePath;\n  readonly source?: SourceLocation;\n}\n\n/**\n * The line for each site a report is about to name, and for nothing else.\n *\n * This is the demand side of the zero-install path. The page reads frames off\n * every fiber because reading them is nearly free; turning one into a file is\n * not, and this is the only place that spends it.\n *\n * Three ways a site costs nothing, all of them the common case:\n *\n * - **It has no `path`.** A region no box contains names no node.\n * - **It already has a `source`.** React ≤18 and `@variance-authority/jsx-source`\n *   both record the location outright, so there is nothing to resolve. Only\n *   React 19, which throws its location away and captures an `Error` instead,\n *   reaches the map.\n * - **Its node carried no frames.** A production build captures nothing.\n *\n * And a subject that settled on its document digest never calls this at all,\n * which is the point: no region, no finding, no fetch.\n *\n * Sites are resolved concurrently. The resolver's own cache collapses them onto\n * the modules they share, so two regions in one component cost one fetch.\n */\nexport async function locateSites<T extends LocatableSite>(\n  sites: readonly T[],\n  snapshot: SemanticSnapshot,\n  resolver: CallSiteResolver,\n): Promise<readonly T[]> {\n  const wanted = sites.some((site) => site.source === undefined && site.path !== undefined);\n  if (!wanted) return sites;\n\n  // Built once and only when something asked. A path lookup on a tree is a walk,\n  // and doing it per site would make a fifty-region page walk it fifty times.\n  const nodes = index(snapshot.root);\n\n  const located = await Promise.all(\n    sites.map(async (site) => {\n      if (site.source !== undefined || site.path === undefined) return site;\n\n      const provenance = nodes.get(site.path)?.provenance;\n      if (provenance?.stack === undefined) return site;\n\n      const spent = await locateProvenance(provenance, resolver);\n      return spent.source === undefined ? site : { ...site, source: spent.source };\n    }),\n  );\n\n  return located.every((site, at) => site === sites[at]) ? sites : located;\n}\n\nfunction index(root: SemanticNode): ReadonlyMap<NodePath, SemanticNode> {\n  const nodes = new Map<NodePath, SemanticNode>();\n\n  const walk = (node: SemanticNode): void => {\n    nodes.set(node.path, node);\n    for (const child of node.children) walk(child);\n  };\n  walk(root);\n\n  return nodes;\n}\n\n/**\n * A map's `sources` entry as a path, resolved against the module it describes.\n *\n * Maps state sources relatively — Vite writes `probe.jsx` for `/src/probe.jsx` —\n * so the entry alone is ambiguous between two directories. Resolved and then\n * stripped to a path, because the origin is a fact about the machine that ran\n * the capture: a baseline holding `http://localhost:5199/src/probe.jsx` would\n * disagree with the next run on a different port. What is left is what the\n * source index and `relativizeSource` already speak.\n */\nfunction sourcePath(source: string, moduleUrl: string): string {\n  const resolved = absolute(source, moduleUrl) ?? source;\n  const parsed = parseUrl(resolved);\n\n  // Not a URL: a bundler that wrote an absolute filesystem path, or a\n  // `webpack://` specifier. Left as it is — `relativizeSource` handles the\n  // first, and inventing a shape for the second would be a guess.\n  return parsed === null ? resolved : parsed.pathname.replace(/^\\/+/, '');\n}\n\nfunction absolute(url: string, base: string): string | null {\n  return parseUrl(url, base)?.href ?? null;\n}\n\n/**\n * The one host global this file needs, asked for rather than assumed.\n *\n * `core` types no host library (ADR-0001) and joining URLs by hand is a bug farm\n * — `..` past the root, a query string on the base, a protocol-relative\n * specifier. `URL` is present in every Node release this project supports and in\n * every browser, so the honest thing is to use it and to degrade if it is not\n * there, exactly as `inlineSourceMapOf` does for `atob`.\n */\ninterface ParsedUrl {\n  readonly href: string;\n  readonly pathname: string;\n}\n\nconst URL_OF = (globalThis as { URL?: new (url: string, base?: string) => ParsedUrl }).URL;\n\nfunction parseUrl(url: string, base?: string): ParsedUrl | null {\n  if (URL_OF === undefined) return null;\n\n  try {\n    return new URL_OF(url, base);\n  } catch {\n    return null;\n  }\n}\n"]}

package/dist/attribute/component-hash.d.ts

@@ -0,0 +1,188 @@
+import { type Band } from '../compare/band.js';
+import type { Digest } from '../format/hash.js';
+import type { ComponentHash, SemanticSnapshot } from '../format/snapshot.js';
+export type { ComponentHash } from '../format/snapshot.js';
+export { UNATTRIBUTED } from './boundary.js';
+/**
+ * The digests a comparison of two component states actually reads.
+ *
+ * `movedBands` used to take two `ComponentHash`es, which carry a name and an
+ * instance count neither side of the comparison consults. Narrowing it to the
+ * digests is what lets a per-instance record (`ComponentInstance`, which has no
+ * `instances` count because it *is* one) be compared by the same function —
+ * rather than by a second copy of the band mapping, which is the one thing in
+ * this file that must not exist twice: a subject relaxed to `layout` has to
+ * absorb the same bands whichever shape the caller happened to be holding.
+ */
+export interface BandDigests {
+    readonly structure: Digest;
+    readonly semantics: Digest;
+    readonly text: Digest;
+    readonly style: Digest;
+    readonly geometry?: Digest;
+}
+/**
+ * Per-component content hashes, one per band.
+ *
+ * `SemanticSnapshot` hashes a whole subject. That answers "did anything change"
+ * and nothing else: it moves whenever anything inside it moves, so it cannot say
+ * *which area*, and a record built on it says "the page changed" on every commit.
+ *
+ * These hashes are the unit a history is kept in. Text, and small — a component
+ * that did not change contributes the same digest it did last time, so the only
+ * thing worth recording is the difference.
+ */
+/**
+ * Hash every component boundary in a subject.
+ *
+ * Ordered by component name so an unchanged subject produces byte-identical
+ * output across runs.
+ *
+ * The walk and the per-boundary shape live in {@link ./boundary.js}, which
+ * {@link ./instances.js} shares — one definition of what a component's own
+ * content is, read by the aggregate and by the per-instance form.
+ */
+export declare function hashComponents(snapshot: SemanticSnapshot): readonly ComponentHash[];
+/**
+ * Which components *caused* a change, given both revisions' hashes.
+ *
+ * The arithmetic behind cause-first ranking, and the reason a baseline carries
+ * its component hashes at all. `rankRegions` takes a list of cause names and,
+ * given none, falls back to area — which
+ * [journal 0013](../../../../docs/context/journal/0013-observability.md)
+ * measured as backwards by 6×, because area measures displacement rather than
+ * cause. This is where that list comes from on a path with no second document.
+ *
+ * The distinction is the split ADR-0018 built the bands for:
+ *
+ * - **`structure` or `style` moved** — the component's own content is different.
+ *   It is a cause.
+ * - **only `geometry` moved** — the component is byte-identical and its box is
+ *   somewhere else. Something *else* moved it, so it is collateral, and naming
+ *   it would send a reviewer to a file nobody edited.
+ * - **appeared or disappeared** — a component present on one side only is a
+ *   cause. Something decided to render it or to stop.
+ *
+ * `instances` is deliberately not consulted. A component rendered five times
+ * instead of four has a different `structure` digest for the subject, and the
+ * count moving on its own — the same component, the same content, one more of
+ * them — is a change in whatever decided how many, not in this component.
+ *
+ * A profile with no layout supplies no `geometry`, so on that tier every
+ * difference is `structure` or `style` and every changed component is a cause.
+ * That is correct rather than degraded: with no boxes, nothing was displaced.
+ */
+export declare function causesBetween(before: readonly ComponentHash[], after: readonly ComponentHash[]): readonly string[];
+/**
+ * Which frequency bands moved between one component's two hashes.
+ *
+ * The reason the digests were split. A baseline carries hashes and not
+ * documents, so "what changed here" used to be answerable only as a boolean —
+ * and a boolean cannot serve a route-level test, whose entire request is *tell
+ * me when the page stops assembling and never when it is repainted*.
+ *
+ * The mapping is exact and it is the same one `bandOf` applies to a delta, which
+ * is the property that matters: a subject relaxed to `layout` must absorb the
+ * same things whether the run held two documents or two sidecars. Two mappings
+ * would be one drift away from a config key meaning different things on the two
+ * paths, discovered as a regression somebody let through.
+ *
+ * | digest | band | what it covers |
+ * |---|---|---|
+ * | `semantics` | `a11y` | role, accessible name, ARIA state |
+ * | `text` | `content` | text runs |
+ * | `structure` | `geometry` | tags, aliases, attributes, child boundaries |
+ * | `geometry` | `geometry` | rects and computed layout output |
+ * | `style` | `token` | declared values and custom properties |
+ *
+ * `texture` never appears. It is raster residue by definition, and a component
+ * hash is built from a document — so the band a comparison of hashes cannot
+ * decide is *absent* from the answer rather than reported as unmoved, which is
+ * ADR-0002's rule applied to a narrower question.
+ *
+ * A missing `geometry` on either side is the profile saying it has no layout
+ * engine, and is not a difference. Treating absent as a change would report
+ * every component as having moved the moment a jsdom baseline met a Chromium
+ * run — which the environment key already refuses as `incomparable`, so this
+ * would be a second, wronger answer to a question already settled.
+ */
+export declare function movedBands(before: BandDigests, after: BandDigests): readonly Band[];
+/**
+ * Every band that moved anywhere in the subject, given both revisions' hashes.
+ *
+ * A component present on one side only contributes `geometry`: something was
+ * added or removed, which is the structural half of that band however the rest
+ * of it compares. It deliberately does not contribute `a11y` or `content` as
+ * well — a component that is simply not there did not *rename* anything, and
+ * inflating the answer would make a level that absorbs nothing look like the
+ * only safe choice.
+ */
+export declare function bandsBetween(before: readonly ComponentHash[], after: readonly ComponentHash[]): readonly Band[];
+/**
+ * Which bands moved, kept per component instead of folded into one list.
+ *
+ * {@link bandsBetween} answers *what kind of change is in this subject*, which is
+ * the question a sensitivity level asks. It cannot answer the one a reviewer
+ * asks — *what changed, and where* — because the fold is lossy in exactly the
+ * place attribution lives: a subject reporting `content, geometry, token` has
+ * told you a colour and a string and a size all moved somewhere in it, and left
+ * you to guess which of the forty components on the page owns which.
+ *
+ * Unfolded, the same two sidecars say `Button — geometry, token` and
+ * `CardFooter — a11y, content`, and that is a sentence a page can print beside a
+ * picture. It is also the record that survives when the raster tier loses the
+ * name: a difference that reflowed its neighbours merges into one blob whose box
+ * fits no component, so the region resolves to the document root and the edit
+ * arrives unattributed — while the hashes, which never looked at a pixel, still
+ * hold the component that moved and the sense in which it moved.
+ *
+ * `cause` repeats the {@link causesBetween} predicate rather than being derived
+ * from `bands`, and the repetition is the point: `structure` and `geometry` both
+ * map to the `geometry` band, so a component that edited its own tree and one
+ * that was merely pushed by a neighbour are indistinguishable *after* the band
+ * mapping. Losing that here would make every reflowed container a culprit.
+ */
+export interface ComponentBands {
+    readonly component: string;
+    /** Non-empty: a component whose digests all matched has no entry at all. */
+    readonly bands: readonly Band[];
+    /** Its own content moved, as opposed to only its rect. `causesBetween`'s test. */
+    readonly cause: boolean;
+    /** Set only when the component is on one side alone, which `bands` cannot say. */
+    readonly presence?: 'added' | 'removed';
+    /**
+     * How much bigger its own box got, when every instance agrees on the answer.
+     *
+     * The band a reviewer actually wanted. `geometry` says a rect under here is
+     * not the rect it was; this says the control is eight pixels taller and
+     * thirty-six wider, which is the padding somebody edited, arriving as a
+     * measurement rather than as a guess about which property produced it.
+     *
+     * Absent for four different reasons and they are one reason: nobody can say.
+     * No boxes on one side, a different number of instances, instances that
+     * disagree about the delta, or a box that did not change size. Present is
+     * always non-zero on at least one axis.
+     */
+    readonly grew?: {
+        readonly width: number;
+        readonly height: number;
+    };
+}
+/**
+ * Every component whose hashes differ, with the bands it differs in.
+ *
+ * One-sided components contribute `geometry` and nothing else, which is
+ * {@link bandsBetween}'s rule and must stay identical to it: a component that is
+ * simply not there did not rename anything, and inflating the answer would put
+ * an `a11y` claim on a page for a component nobody can look at. `presence` is
+ * what carries the rest of that meaning, so no reader has to infer *appeared*
+ * from a lone `geometry`.
+ *
+ * `(unattributed)` is excluded for the reason {@link causesBetween} excludes it:
+ * it is a bucket for nodes whose provenance chain broke, so it collects
+ * unrelated parts of a page under one name and nothing downstream could act on
+ * it. The broken chain is reported where it means something, not here as a
+ * component that moved.
+ */
+export declare function movedBandsBetween(before: readonly ComponentHash[], after: readonly ComponentHash[]): readonly ComponentBands[];
+//# sourceMappingURL=component-hash.d.ts.map