@variance-authority/core 0.1.0

package/dist/attribute/instances.d.ts

@@ -0,0 +1,145 @@
+import type { Digest } from '../format/hash.js';
+import type { NodePath, SemanticSnapshot } from '../format/snapshot.js';
+/**
+ * One digest per component *boundary*, comparable across subjects.
+ *
+ * `hashComponents` folds every boundary with the same name into one row, which
+ * is the right unit for a history — it is the unit an edit moves — and the wrong
+ * unit for the question a suite of examples actually poses:
+ *
+ * > A visual-regression example is a component built from components. The
+ * > example *is* a component, at a boundary; the same component appears again,
+ * > with the same or different props, inside larger examples. Connecting those
+ * > is connecting the dots.
+ *
+ * Under the aggregate that connection is unmakeable. `Button` in a one-button
+ * story digests a list of one shape; `Button` in a page holding three digests a
+ * list of three; the two can never be equal, and the fact that one of the three
+ * is byte-identical to the story is not recoverable from either digest.
+ *
+ * So this is the same walk and the same shapes, digested per boundary instead of
+ * per name. It is additive: `hashComponents` is untouched and still produces the
+ * bytes a sidecar already holds.
+ *
+ * ## Two things had to change for a digest to cross a subject boundary
+ *
+ * **Aliases are subject-ordinal.** The normalizer replaces every id with `#a0`,
+ * `#a1`, … in document order *across the whole subject* (ADR-0003). That is
+ * exactly right for a subject and fatal across two: the same field rendered in a
+ * story and on a page gets `#a0` in one and `#a7` in the other, so its structure
+ * digests differ and the dots stay unconnected — for a reason that is an
+ * artefact of where else the component happened to be mounted. This re-aliases
+ * to `#b0`, `#b1`, … in the boundary's own document order, which is the same
+ * argument `shapeOf` already makes about paths: an address that shifts when
+ * something unrelated moves must not reach a hash.
+ *
+ * The association survives, which is the property that made aliasing worth doing
+ * in the first place. A `for` that points at an input inside the boundary keeps
+ * pointing at it. A reference that escapes the boundary keeps its own slot and
+ * points at nothing in particular — from inside, one foreign target is
+ * indistinguishable from another, and pretending otherwise would report a
+ * difference the component cannot see.
+ *
+ * **Geometry is left out of the joining digest.** A rect is absolute page
+ * coordinates, so two identical renderings in two subjects disagree on it
+ * always. `rendering` is the four content digests; the geometry digest is
+ * carried beside it, where a caller comparing two instances *within* one subject
+ * can still read it.
+ */
+/** One component boundary, hashed. */
+export interface ComponentInstance {
+    readonly component: string;
+    /**
+     * Where it sits in this subject. Never hashed — see `shapeOf`.
+     *
+     * Carried so a finding can be pointed at, which is the whole reason a
+     * per-instance record is worth having: "the third `Chip`" is a sentence a
+     * reviewer can act on and `instances: 3` is not.
+     */
+    readonly path: NodePath;
+    /** Boundaries between this one and the subject root. The root is `0`. */
+    readonly depth: number;
+    /** The enclosing boundary's component. Absent on the subject root. */
+    readonly within?: string;
+    /**
+     * Who placed this boundary's element, when it differs from `within`.
+     *
+     * `within` says which component this one *sits inside* and `createdBy` says
+     * which component *wrote the element*, and the two diverge wherever a
+     * component is passed as a prop and rendered somewhere else (ADR-0007). That
+     * divergence is a fact about composition, so it is kept rather than resolved.
+     */
+    readonly createdBy?: string;
+    /**
+     * Digest of the props this boundary received, from `OwnerFrame.propsDigest`.
+     *
+     * Absent when the collector supplied no provenance for the boundary root —
+     * absent, never a digest of nothing, because "rendered with unknown inputs"
+     * and "rendered with no inputs" are different claims and only one of them
+     * licenses a join.
+     *
+     * It is one-way. Two instances can be shown to have received different props;
+     * *which* prop differed is not recoverable, and nothing here pretends it is.
+     */
+    readonly props?: Digest;
+    /**
+     * The four content digests, together. The join key.
+     *
+     * Two instances with the same `rendering` rendered the same thing, wherever
+     * they were and whatever else was on the page with them.
+     */
+    readonly rendering: Digest;
+    readonly structure: Digest;
+    readonly semantics: Digest;
+    readonly text: Digest;
+    readonly style: Digest;
+    /** Absent under a profile without layout — absent, never empty (ADR-0002). */
+    readonly geometry?: Digest;
+    /**
+     * How the framework holds this boundary: hook shape, wrappers, context
+     * subscriptions, reconciliation keys. See `Wiring`.
+     *
+     * Deliberately **not** folded into `rendering`, for the same reason `geometry`
+     * is not: `rendering` is the four content digests and its contract is that two
+     * instances sharing it rendered the same thing. A component that gained a
+     * `memo()` renders the same thing. Folding wiring in would make a performance
+     * annotation read as a visual regression and would re-baseline every subject
+     * on the first run after a framework adapter was wired up — which is the
+     * surest way to make a new dimension the thing people turn off.
+     *
+     * Absent when no adapter supplied wiring for any node in this boundary.
+     * Absent, never a digest of nulls, because "no framework here" and "a framework
+     * nobody could read" must not compare equal (ADR-0002).
+     */
+    readonly wiring?: Digest;
+    /** Child boundaries, in document order. The edges of the component graph. */
+    readonly renders: readonly string[];
+    /** Nodes this boundary owns, counting its own root. */
+    readonly nodes: number;
+    /**
+     * Custom properties this boundary's own nodes resolved through, sorted.
+     *
+     * The join between the token axis and the component axis. A run that reports
+     * `--va-space-3` moved can now say which components read it, rather than
+     * leaving a reader to guess from a colour.
+     */
+    readonly tokens: readonly string[];
+}
+/**
+ * Every component boundary in a subject, in document order.
+ *
+ * Document order, not name order, because unlike `hashComponents` this list is
+ * not a set of rows keyed by name — it is a walk, and its order is the only
+ * thing that makes "the third `Chip`" mean anything.
+ */
+export declare function componentInstances(snapshot: SemanticSnapshot): readonly ComponentInstance[];
+/**
+ * Whether an instance is worth joining on at all.
+ *
+ * `(unattributed)` is one bucket per subject collecting every node whose
+ * provenance chain broke, anywhere. Two subjects' buckets hold unrelated parts
+ * of two pages, so an equality between them means nothing and an inequality
+ * means less — it is the only name in the vocabulary that is not a component.
+ */
+export declare function attributed(instance: ComponentInstance): boolean;
+//# sourceMappingURL=instances.d.ts.map

package/dist/attribute/instances.js

@@ -0,0 +1,140 @@
+import { digestValue } from '../format/hash.js';
+import { ID_REFERENCE_ATTRIBUTES, ID_REFERENCE_LIST_ATTRIBUTES } from '../rules/ruleset.js';
+import { boundaries, holds, shapeOf, UNATTRIBUTED, } from './boundary.js';
+/**
+ * Every component boundary in a subject, in document order.
+ *
+ * Document order, not name order, because unlike `hashComponents` this list is
+ * not a set of rows keyed by name — it is a walk, and its order is the only
+ * thing that makes "the third `Chip`" mean anything.
+ */
+export function componentInstances(snapshot) {
+    const layout = snapshot.profile.layout;
+    return boundaries(snapshot.root).map((boundary) => {
+        const shape = shapeOf(boundary, layout, localAliases(boundary));
+        const structure = digestValue(shape.structure);
+        const semantics = digestValue(shape.semantics);
+        const text = digestValue(shape.text);
+        const style = digestValue(shape.style);
+        return {
+            component: boundary.component,
+            path: boundary.node.path,
+            depth: boundary.depth,
+            ...(boundary.within === undefined ? {} : { within: boundary.within }),
+            ...(boundary.placedBy === undefined ? {} : { createdBy: boundary.placedBy }),
+            ...(boundary.props === undefined ? {} : { props: boundary.props }),
+            rendering: digestValue([structure, semantics, text, style]),
+            structure,
+            semantics,
+            text,
+            style,
+            ...(layout ? { geometry: digestValue(shape.geometry) } : {}),
+            // Only when something reported wiring. A boundary of pure nulls is a
+            // boundary nobody read, and hashing it would give a plain-DOM page a
+            // `wiring` digest to be compared against a React page's.
+            ...(observed(shape.wiring) ? { wiring: digestValue(shape.wiring) } : {}),
+            renders: shape.renders,
+            nodes: shape.nodes,
+            tokens: shape.tokens,
+        };
+    });
+}
+/**
+ * Whether a per-node band list holds anything at all.
+ *
+ * The band pushes one entry per node so that position stays meaningful, which
+ * means a boundary under no framework adapter produces a full-length list of
+ * `null`. That is a well-formed value and it hashes to something, and something
+ * is exactly what it must not produce — the digest would then say "this boundary
+ * has known wiring, and it is nothing", which joins against every other
+ * unread boundary in the corpus.
+ */
+function observed(band) {
+    return Array.isArray(band) && band.some((entry) => entry !== null);
+}
+/**
+ * Whether an instance is worth joining on at all.
+ *
+ * `(unattributed)` is one bucket per subject collecting every node whose
+ * provenance chain broke, anywhere. Two subjects' buckets hold unrelated parts
+ * of two pages, so an equality between them means nothing and an inequality
+ * means less — it is the only name in the vocabulary that is not a component.
+ */
+export function attributed(instance) {
+    return instance.component !== UNATTRIBUTED;
+}
+const REFERENCE = new Set(ID_REFERENCE_ATTRIBUTES);
+const REFERENCE_LIST = new Set(ID_REFERENCE_LIST_ATTRIBUTES);
+const ALIAS = /^#(?:a\d+|extern:.*)$/;
+/**
+ * A boundary-local alias space, assigned in the boundary's own document order.
+ *
+ * Built in a pass of its own, ahead of hashing, for the reason `buildAliasMap`
+ * takes two: a reference may precede its definition, and an alias whose slot
+ * depended on which side was seen first would differ between two identical
+ * renderings that happened to be reached in a different order. Here the walk
+ * order is fixed, so one pass over the boundary's own nodes in document order —
+ * definition or reference, whichever is met first — is deterministic and enough.
+ *
+ * Stops at nested boundaries, exactly as `shapeOf` does. A child component's
+ * internal ids are its own; folding them into the parent's alias space would
+ * make the parent's structure digest move when the child renumbered internally,
+ * which is the ancestor-moves-on-every-leaf-edit failure the boundary rule
+ * exists to prevent.
+ */
+function localAliases(boundary) {
+    const local = new Map();
+    const take = (value) => {
+        if (!ALIAS.test(value) || local.has(value))
+            return;
+        local.set(value, `#b${local.size}`);
+    };
+    const walk = (node) => {
+        if (node.alias !== undefined)
+            take(node.alias);
+        for (const [name, value] of Object.entries(node.attributes)) {
+            if (REFERENCE_LIST.has(name))
+                for (const part of value.split(/\s+/))
+                    take(part);
+            else if (REFERENCE.has(name) || name === 'href' || name === 'xlink:href')
+                take(value);
+        }
+        for (const value of Object.values(node.style))
+            for (const found of urlAliases(value))
+                take(found);
+        for (const value of Object.values(node.tokens ?? {}))
+            for (const found of urlAliases(value))
+                take(found);
+        for (const child of node.children)
+            if (holds(boundary, child))
+                walk(child);
+    };
+    walk(boundary.node);
+    // Unmapped values pass through unchanged. A reference this walk never reached
+    // — one inside a nested boundary, reaching back out — is left as the subject
+    // alias it already was, which is visible and wrong in the same direction as
+    // doing nothing, rather than silently colliding with a local slot.
+    const rewrite = (value) => local.get(value) ?? value;
+    return {
+        alias: rewrite,
+        style: (value) => value.replace(/url\(\s*(['"]?)#([^'")]+)\1\s*\)/g, (match, quote, id) => {
+            const mapped = local.get(`#${id}`);
+            return mapped === undefined ? match : `url(${quote}${mapped}${quote})`;
+        }),
+        attribute: (name, value) => {
+            if (REFERENCE_LIST.has(name)) {
+                return value
+                    .split(/\s+/)
+                    .map((part) => rewrite(part))
+                    .join(' ');
+            }
+            if (REFERENCE.has(name) || name === 'href' || name === 'xlink:href')
+                return rewrite(value);
+            return value;
+        },
+    };
+}
+function urlAliases(value) {
+    return [...value.matchAll(/url\(\s*['"]?#([^'")]+)['"]?\s*\)/g)].map((match) => `#${match[1]}`);
+}
+//# sourceMappingURL=instances.js.map

package/dist/attribute/instances.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instances.js","sourceRoot":"","sources":["../../src/attribute/instances.ts"],"names":[],"mappings":"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","sourcesContent":["import type { CanonicalValue } from '../format/canonical.js';\nimport { digestValue } from '../format/hash.js';\nimport type { Digest } from '../format/hash.js';\nimport type { NodePath, SemanticNode, SemanticSnapshot } from '../format/snapshot.js';\nimport { ID_REFERENCE_ATTRIBUTES, ID_REFERENCE_LIST_ATTRIBUTES } from '../rules/ruleset.js';\nimport {\n  boundaries,\n  holds,\n  shapeOf,\n  UNATTRIBUTED,\n  type Boundary,\n  type Rename,\n} from './boundary.js';\n\n/**\n * One digest per component *boundary*, comparable across subjects.\n *\n * `hashComponents` folds every boundary with the same name into one row, which\n * is the right unit for a history — it is the unit an edit moves — and the wrong\n * unit for the question a suite of examples actually poses:\n *\n * > A visual-regression example is a component built from components. The\n * > example *is* a component, at a boundary; the same component appears again,\n * > with the same or different props, inside larger examples. Connecting those\n * > is connecting the dots.\n *\n * Under the aggregate that connection is unmakeable. `Button` in a one-button\n * story digests a list of one shape; `Button` in a page holding three digests a\n * list of three; the two can never be equal, and the fact that one of the three\n * is byte-identical to the story is not recoverable from either digest.\n *\n * So this is the same walk and the same shapes, digested per boundary instead of\n * per name. It is additive: `hashComponents` is untouched and still produces the\n * bytes a sidecar already holds.\n *\n * ## Two things had to change for a digest to cross a subject boundary\n *\n * **Aliases are subject-ordinal.** The normalizer replaces every id with `#a0`,\n * `#a1`, … in document order *across the whole subject* (ADR-0003). That is\n * exactly right for a subject and fatal across two: the same field rendered in a\n * story and on a page gets `#a0` in one and `#a7` in the other, so its structure\n * digests differ and the dots stay unconnected — for a reason that is an\n * artefact of where else the component happened to be mounted. This re-aliases\n * to `#b0`, `#b1`, … in the boundary's own document order, which is the same\n * argument `shapeOf` already makes about paths: an address that shifts when\n * something unrelated moves must not reach a hash.\n *\n * The association survives, which is the property that made aliasing worth doing\n * in the first place. A `for` that points at an input inside the boundary keeps\n * pointing at it. A reference that escapes the boundary keeps its own slot and\n * points at nothing in particular — from inside, one foreign target is\n * indistinguishable from another, and pretending otherwise would report a\n * difference the component cannot see.\n *\n * **Geometry is left out of the joining digest.** A rect is absolute page\n * coordinates, so two identical renderings in two subjects disagree on it\n * always. `rendering` is the four content digests; the geometry digest is\n * carried beside it, where a caller comparing two instances *within* one subject\n * can still read it.\n */\n\n/** One component boundary, hashed. */\nexport interface ComponentInstance {\n  readonly component: string;\n\n  /**\n   * Where it sits in this subject. Never hashed — see `shapeOf`.\n   *\n   * Carried so a finding can be pointed at, which is the whole reason a\n   * per-instance record is worth having: \"the third `Chip`\" is a sentence a\n   * reviewer can act on and `instances: 3` is not.\n   */\n  readonly path: NodePath;\n\n  /** Boundaries between this one and the subject root. The root is `0`. */\n  readonly depth: number;\n\n  /** The enclosing boundary's component. Absent on the subject root. */\n  readonly within?: string;\n\n  /**\n   * Who placed this boundary's element, when it differs from `within`.\n   *\n   * `within` says which component this one *sits inside* and `createdBy` says\n   * which component *wrote the element*, and the two diverge wherever a\n   * component is passed as a prop and rendered somewhere else (ADR-0007). That\n   * divergence is a fact about composition, so it is kept rather than resolved.\n   */\n  readonly createdBy?: string;\n\n  /**\n   * Digest of the props this boundary received, from `OwnerFrame.propsDigest`.\n   *\n   * Absent when the collector supplied no provenance for the boundary root —\n   * absent, never a digest of nothing, because \"rendered with unknown inputs\"\n   * and \"rendered with no inputs\" are different claims and only one of them\n   * licenses a join.\n   *\n   * It is one-way. Two instances can be shown to have received different props;\n   * *which* prop differed is not recoverable, and nothing here pretends it is.\n   */\n  readonly props?: Digest;\n\n  /**\n   * The four content digests, together. The join key.\n   *\n   * Two instances with the same `rendering` rendered the same thing, wherever\n   * they were and whatever else was on the page with them.\n   */\n  readonly rendering: Digest;\n\n  readonly structure: Digest;\n  readonly semantics: Digest;\n  readonly text: Digest;\n  readonly style: Digest;\n  /** Absent under a profile without layout — absent, never empty (ADR-0002). */\n  readonly geometry?: Digest;\n\n  /**\n   * How the framework holds this boundary: hook shape, wrappers, context\n   * subscriptions, reconciliation keys. See `Wiring`.\n   *\n   * Deliberately **not** folded into `rendering`, for the same reason `geometry`\n   * is not: `rendering` is the four content digests and its contract is that two\n   * instances sharing it rendered the same thing. A component that gained a\n   * `memo()` renders the same thing. Folding wiring in would make a performance\n   * annotation read as a visual regression and would re-baseline every subject\n   * on the first run after a framework adapter was wired up — which is the\n   * surest way to make a new dimension the thing people turn off.\n   *\n   * Absent when no adapter supplied wiring for any node in this boundary.\n   * Absent, never a digest of nulls, because \"no framework here\" and \"a framework\n   * nobody could read\" must not compare equal (ADR-0002).\n   */\n  readonly wiring?: Digest;\n\n  /** Child boundaries, in document order. The edges of the component graph. */\n  readonly renders: readonly string[];\n\n  /** Nodes this boundary owns, counting its own root. */\n  readonly nodes: number;\n\n  /**\n   * Custom properties this boundary's own nodes resolved through, sorted.\n   *\n   * The join between the token axis and the component axis. A run that reports\n   * `--va-space-3` moved can now say which components read it, rather than\n   * leaving a reader to guess from a colour.\n   */\n  readonly tokens: readonly string[];\n}\n\n/**\n * Every component boundary in a subject, in document order.\n *\n * Document order, not name order, because unlike `hashComponents` this list is\n * not a set of rows keyed by name — it is a walk, and its order is the only\n * thing that makes \"the third `Chip`\" mean anything.\n */\nexport function componentInstances(snapshot: SemanticSnapshot): readonly ComponentInstance[] {\n  const layout = snapshot.profile.layout;\n\n  return boundaries(snapshot.root).map((boundary) => {\n    const shape = shapeOf(boundary, layout, localAliases(boundary));\n\n    const structure = digestValue(shape.structure);\n    const semantics = digestValue(shape.semantics);\n    const text = digestValue(shape.text);\n    const style = digestValue(shape.style);\n\n    return {\n      component: boundary.component,\n      path: boundary.node.path,\n      depth: boundary.depth,\n      ...(boundary.within === undefined ? {} : { within: boundary.within }),\n      ...(boundary.placedBy === undefined ? {} : { createdBy: boundary.placedBy }),\n      ...(boundary.props === undefined ? {} : { props: boundary.props }),\n      rendering: digestValue([structure, semantics, text, style]),\n      structure,\n      semantics,\n      text,\n      style,\n      ...(layout ? { geometry: digestValue(shape.geometry) } : {}),\n      // Only when something reported wiring. A boundary of pure nulls is a\n      // boundary nobody read, and hashing it would give a plain-DOM page a\n      // `wiring` digest to be compared against a React page's.\n      ...(observed(shape.wiring) ? { wiring: digestValue(shape.wiring) } : {}),\n      renders: shape.renders,\n      nodes: shape.nodes,\n      tokens: shape.tokens,\n    };\n  });\n}\n\n/**\n * Whether a per-node band list holds anything at all.\n *\n * The band pushes one entry per node so that position stays meaningful, which\n * means a boundary under no framework adapter produces a full-length list of\n * `null`. That is a well-formed value and it hashes to something, and something\n * is exactly what it must not produce — the digest would then say \"this boundary\n * has known wiring, and it is nothing\", which joins against every other\n * unread boundary in the corpus.\n */\nfunction observed(band: CanonicalValue): boolean {\n  return Array.isArray(band) && band.some((entry) => entry !== null);\n}\n\n/**\n * Whether an instance is worth joining on at all.\n *\n * `(unattributed)` is one bucket per subject collecting every node whose\n * provenance chain broke, anywhere. Two subjects' buckets hold unrelated parts\n * of two pages, so an equality between them means nothing and an inequality\n * means less — it is the only name in the vocabulary that is not a component.\n */\nexport function attributed(instance: ComponentInstance): boolean {\n  return instance.component !== UNATTRIBUTED;\n}\n\nconst REFERENCE = new Set(ID_REFERENCE_ATTRIBUTES);\nconst REFERENCE_LIST = new Set(ID_REFERENCE_LIST_ATTRIBUTES);\nconst ALIAS = /^#(?:a\\d+|extern:.*)$/;\n\n/**\n * A boundary-local alias space, assigned in the boundary's own document order.\n *\n * Built in a pass of its own, ahead of hashing, for the reason `buildAliasMap`\n * takes two: a reference may precede its definition, and an alias whose slot\n * depended on which side was seen first would differ between two identical\n * renderings that happened to be reached in a different order. Here the walk\n * order is fixed, so one pass over the boundary's own nodes in document order —\n * definition or reference, whichever is met first — is deterministic and enough.\n *\n * Stops at nested boundaries, exactly as `shapeOf` does. A child component's\n * internal ids are its own; folding them into the parent's alias space would\n * make the parent's structure digest move when the child renumbered internally,\n * which is the ancestor-moves-on-every-leaf-edit failure the boundary rule\n * exists to prevent.\n */\nfunction localAliases(boundary: Boundary): Rename {\n  const local = new Map<string, string>();\n\n  const take = (value: string): void => {\n    if (!ALIAS.test(value) || local.has(value)) return;\n    local.set(value, `#b${local.size}`);\n  };\n\n  const walk = (node: SemanticNode): void => {\n    if (node.alias !== undefined) take(node.alias);\n    for (const [name, value] of Object.entries(node.attributes)) {\n      if (REFERENCE_LIST.has(name)) for (const part of value.split(/\\s+/)) take(part);\n      else if (REFERENCE.has(name) || name === 'href' || name === 'xlink:href') take(value);\n    }\n    for (const value of Object.values(node.style)) for (const found of urlAliases(value)) take(found);\n    for (const value of Object.values(node.tokens ?? {})) for (const found of urlAliases(value)) take(found);\n    for (const child of node.children) if (holds(boundary, child)) walk(child);\n  };\n\n  walk(boundary.node);\n\n  // Unmapped values pass through unchanged. A reference this walk never reached\n  // — one inside a nested boundary, reaching back out — is left as the subject\n  // alias it already was, which is visible and wrong in the same direction as\n  // doing nothing, rather than silently colliding with a local slot.\n  const rewrite = (value: string): string => local.get(value) ?? value;\n\n  return {\n    alias: rewrite,\n    style: (value) =>\n      value.replace(/url\\(\\s*(['\"]?)#([^'\")]+)\\1\\s*\\)/g, (match, quote: string, id: string) => {\n        const mapped = local.get(`#${id}`);\n        return mapped === undefined ? match : `url(${quote}${mapped}${quote})`;\n      }),\n    attribute: (name, value) => {\n      if (REFERENCE_LIST.has(name)) {\n        return value\n          .split(/\\s+/)\n          .map((part) => rewrite(part))\n          .join(' ');\n      }\n      if (REFERENCE.has(name) || name === 'href' || name === 'xlink:href') return rewrite(value);\n      return value;\n    },\n  };\n}\n\nfunction urlAliases(value: string): readonly string[] {\n  return [...value.matchAll(/url\\(\\s*['\"]?#([^'\")]+)['\"]?\\s*\\)/g)].map((match) => `#${match[1]}`);\n}\n"]}

package/dist/attribute/locate.d.ts

@@ -0,0 +1,22 @@
+import type { NodePath, SemanticNode } from '../format/snapshot.js';
+export interface LocationStep {
+    /** `landmark`, `named`, or `ordinal` — why this step is worth mentioning. */
+    readonly kind: 'landmark' | 'named' | 'ordinal';
+    readonly text: string;
+}
+export interface Location {
+    readonly steps: readonly LocationStep[];
+    /** The nearest landmark, for grouping. Spec §6.3's "right panel". */
+    readonly region?: string;
+    /** One phrase: `main → region "Todos" → item 2 of 3`. */
+    readonly where: string;
+}
+/**
+ * Describe where `path` sits, from the landmarks and names above it.
+ *
+ * Returns an empty location rather than throwing when the path does not resolve.
+ * A stale or unresolvable path is a defect somewhere upstream, and losing the
+ * whole report over it would hide the finding that actually matters.
+ */
+export declare function locate(root: SemanticNode, path: NodePath): Location;
+//# sourceMappingURL=locate.d.ts.map

package/dist/attribute/locate.js

@@ -0,0 +1,100 @@
+/**
+ * Orientation: *where* a change is, in words a person can act on.
+ *
+ * A path like `0/0/0/2/1/0` is an address, not a location. It tells a reviewer
+ * nothing, and it tells an agent nothing either — which is how a report ends up
+ * being read as "looks right, merge".
+ *
+ * Coordinates are no better. Spec §6.3 is explicit that spatial location is
+ * expressed through landmarks rather than pixels, and the reason is that
+ * coordinates are the least stable thing about a page: a rect moves whenever
+ * anything above it reflows, so "at (412, 880)" describes this build and no
+ * other. A landmark path describes the *page*, and stays true while the layout
+ * moves under it.
+ *
+ * So a location is built from the things a user would use to describe where they
+ * are: the landmark they are in, the named region or dialog, and their position
+ * in a list. `main → region "Todos" → list → item 2 of 3` is a sentence someone
+ * can follow without opening a screenshot.
+ */
+/** Roles that orient: a user could say "in the navigation" and be understood. */
+const LANDMARKS = new Set([
+    'banner', 'navigation', 'main', 'complementary', 'contentinfo',
+    'region', 'form', 'search', 'dialog', 'alertdialog',
+]);
+/** Roles whose children are positional, so an ordinal is worth reporting. */
+const ORDINAL_CONTAINERS = new Set(['list', 'table', 'rowgroup', 'row', 'tablist', 'menu', 'grid']);
+/**
+ * Describe where `path` sits, from the landmarks and names above it.
+ *
+ * Returns an empty location rather than throwing when the path does not resolve.
+ * A stale or unresolvable path is a defect somewhere upstream, and losing the
+ * whole report over it would hide the finding that actually matters.
+ */
+export function locate(root, path) {
+    const chain = walkTo(root, path);
+    if (chain.length === 0)
+        return { steps: [], where: '' };
+    const steps = [];
+    let region;
+    for (const [index, node] of chain.entries()) {
+        const child = chain[index + 1];
+        if (node.role !== undefined && LANDMARKS.has(node.role)) {
+            const text = node.name !== undefined ? `${node.role} "${node.name}"` : node.role;
+            steps.push({ kind: 'landmark', text });
+            // Nearest wins: the innermost landmark is the one a person would name.
+            region = text;
+            continue;
+        }
+        // A named non-landmark still orients — `tabpanel "Active"`, `group "Filters"`.
+        if (node.role !== undefined && node.name !== undefined && index > 0) {
+            steps.push({ kind: 'named', text: `${node.role} "${node.name}"` });
+            continue;
+        }
+        if (child !== undefined && node.role !== undefined && ORDINAL_CONTAINERS.has(node.role)) {
+            const position = node.children.indexOf(child);
+            if (position >= 0) {
+                steps.push({
+                    kind: 'ordinal',
+                    text: `${node.role} item ${position + 1} of ${node.children.length}`,
+                });
+            }
+        }
+    }
+    return {
+        steps,
+        ...(region !== undefined ? { region } : {}),
+        // Deepest first would read backwards; a location is spoken outside-in, the
+        // way someone points at a screen.
+        where: steps.map((step) => step.text).join(' → '),
+    };
+}
+/**
+ * Nodes from the root down to `path`, inclusive.
+ *
+ * Paths are child indices, so this is index navigation rather than a search —
+ * except for portal segments, which are keyed rather than positional because a
+ * portalled subtree is appended outside the DOM child order (ADR-0007).
+ */
+function walkTo(root, path) {
+    const segments = path.split('/');
+    if (segments.length === 0)
+        return [];
+    const chain = [root];
+    let current = root;
+    for (const segment of segments.slice(1)) {
+        // `portal:N` names the *N-th* portal, not "a portal". Taking the first meant
+        // every node in a second or later portalled subtree was located through the
+        // wrong one, and produced a confident landmark phrase about somewhere else —
+        // a subject with two dialogs open is the ordinary case.
+        const next = segment.startsWith('portal:')
+            ? current.children.filter((child) => child.portalled === true)[Number.parseInt(segment.slice('portal:'.length), 10)]
+            : current.children[Number.parseInt(segment, 10)];
+        if (next === undefined)
+            return chain;
+        chain.push(next);
+        current = next;
+    }
+    return chain;
+}
+//# sourceMappingURL=locate.js.map

package/dist/attribute/locate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locate.js","sourceRoot":"","sources":["../../src/attribute/locate.ts"],"names":[],"mappings":"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","sourcesContent":["import type { NodePath, SemanticNode } from '../format/snapshot.js';\n\n/**\n * Orientation: *where* a change is, in words a person can act on.\n *\n * A path like `0/0/0/2/1/0` is an address, not a location. It tells a reviewer\n * nothing, and it tells an agent nothing either — which is how a report ends up\n * being read as \"looks right, merge\".\n *\n * Coordinates are no better. Spec §6.3 is explicit that spatial location is\n * expressed through landmarks rather than pixels, and the reason is that\n * coordinates are the least stable thing about a page: a rect moves whenever\n * anything above it reflows, so \"at (412, 880)\" describes this build and no\n * other. A landmark path describes the *page*, and stays true while the layout\n * moves under it.\n *\n * So a location is built from the things a user would use to describe where they\n * are: the landmark they are in, the named region or dialog, and their position\n * in a list. `main → region \"Todos\" → list → item 2 of 3` is a sentence someone\n * can follow without opening a screenshot.\n */\n\n/** Roles that orient: a user could say \"in the navigation\" and be understood. */\nconst LANDMARKS = new Set([\n  'banner', 'navigation', 'main', 'complementary', 'contentinfo',\n  'region', 'form', 'search', 'dialog', 'alertdialog',\n]);\n\n/** Roles whose children are positional, so an ordinal is worth reporting. */\nconst ORDINAL_CONTAINERS = new Set(['list', 'table', 'rowgroup', 'row', 'tablist', 'menu', 'grid']);\n\nexport interface LocationStep {\n  /** `landmark`, `named`, or `ordinal` — why this step is worth mentioning. */\n  readonly kind: 'landmark' | 'named' | 'ordinal';\n  readonly text: string;\n}\n\nexport interface Location {\n  readonly steps: readonly LocationStep[];\n  /** The nearest landmark, for grouping. Spec §6.3's \"right panel\". */\n  readonly region?: string;\n  /** One phrase: `main → region \"Todos\" → item 2 of 3`. */\n  readonly where: string;\n}\n\n/**\n * Describe where `path` sits, from the landmarks and names above it.\n *\n * Returns an empty location rather than throwing when the path does not resolve.\n * A stale or unresolvable path is a defect somewhere upstream, and losing the\n * whole report over it would hide the finding that actually matters.\n */\nexport function locate(root: SemanticNode, path: NodePath): Location {\n  const chain = walkTo(root, path);\n  if (chain.length === 0) return { steps: [], where: '' };\n\n  const steps: LocationStep[] = [];\n  let region: string | undefined;\n\n  for (const [index, node] of chain.entries()) {\n    const child = chain[index + 1];\n\n    if (node.role !== undefined && LANDMARKS.has(node.role)) {\n      const text = node.name !== undefined ? `${node.role} \"${node.name}\"` : node.role;\n      steps.push({ kind: 'landmark', text });\n      // Nearest wins: the innermost landmark is the one a person would name.\n      region = text;\n      continue;\n    }\n\n    // A named non-landmark still orients — `tabpanel \"Active\"`, `group \"Filters\"`.\n    if (node.role !== undefined && node.name !== undefined && index > 0) {\n      steps.push({ kind: 'named', text: `${node.role} \"${node.name}\"` });\n      continue;\n    }\n\n    if (child !== undefined && node.role !== undefined && ORDINAL_CONTAINERS.has(node.role)) {\n      const position = node.children.indexOf(child);\n      if (position >= 0) {\n        steps.push({\n          kind: 'ordinal',\n          text: `${node.role} item ${position + 1} of ${node.children.length}`,\n        });\n      }\n    }\n  }\n\n  return {\n    steps,\n    ...(region !== undefined ? { region } : {}),\n    // Deepest first would read backwards; a location is spoken outside-in, the\n    // way someone points at a screen.\n    where: steps.map((step) => step.text).join(' → '),\n  };\n}\n\n/**\n * Nodes from the root down to `path`, inclusive.\n *\n * Paths are child indices, so this is index navigation rather than a search —\n * except for portal segments, which are keyed rather than positional because a\n * portalled subtree is appended outside the DOM child order (ADR-0007).\n */\nfunction walkTo(root: SemanticNode, path: NodePath): readonly SemanticNode[] {\n  const segments = path.split('/');\n  if (segments.length === 0) return [];\n\n  const chain: SemanticNode[] = [root];\n  let current = root;\n\n  for (const segment of segments.slice(1)) {\n    // `portal:N` names the *N-th* portal, not \"a portal\". Taking the first meant\n    // every node in a second or later portalled subtree was located through the\n    // wrong one, and produced a confident landmark phrase about somewhere else —\n    // a subject with two dialogs open is the ordinary case.\n    const next = segment.startsWith('portal:')\n      ? current.children.filter((child) => child.portalled === true)[\n          Number.parseInt(segment.slice('portal:'.length), 10)\n        ]\n      : current.children[Number.parseInt(segment, 10)];\n\n    if (next === undefined) return chain;\n    chain.push(next);\n    current = next;\n  }\n\n  return chain;\n}\n"]}

package/dist/attribute/mask.d.ts

@@ -0,0 +1,156 @@
+import type { Rect } from '../format/capture.js';
+import type { SemanticSnapshot } from '../format/snapshot.js';
+/**
+ * A change as a bitmask: where on the canvas, and what was excluded from it.
+ *
+ * Arithmetic, and nothing else. No DOM, no snapshot, no notion of what a
+ * component is — which is why it is the half of attribution that can be tested
+ * with a hand-written mask and why it is a file of its own. Everything here
+ * answers *where on the canvas*; `region.ts` joins those coordinates to a tree
+ * and answers *what is there*, and the two fail differently enough that reading
+ * one to understand the other was how they came to share 500 lines.
+ *
+ * The pixel count is what this exists to defeat. "5482 pixels changed" cannot be
+ * read, cannot be assigned, and leaves opening the image as the only available
+ * response — the expensive act the tool was supposed to replace.
+ */
+/**
+ * Per-pixel changed/unchanged, row-major, one byte per pixel.
+ *
+ * A mask rather than a diff image: an image is for looking at, and everything
+ * downstream of here wants to compute. Producing one is the comparison phase's
+ * job and involves PNG decoding; consuming one is pure.
+ */
+export interface ChangeMask {
+    readonly width: number;
+    readonly height: number;
+    /** `1` where the pixel differs. Length is `width * height`. */
+    readonly data: Uint8Array;
+    /** Count of set bytes, carried so callers need not rescan. */
+    readonly changed: number;
+}
+export interface DiffRegion extends Rect {
+    /** Changed pixels inside the box. Always ≤ `width * height`. */
+    readonly pixels: number;
+    /** `pixels / (width * height)`. Low means scattered; high means a solid block. */
+    readonly density: number;
+}
+export interface IsolationOptions {
+    /**
+     * Grid size, in pixels, at which neighbouring changes are considered one place.
+     *
+     * Not a tuning knob so much as a statement about what a region *is*. At cell 1
+     * every antialiased glyph edge is its own region and a paragraph of restyled
+     * text produces four hundred of them, which is the same unreadable output as a
+     * single number, only longer. At cell 8 a word is one region and a button is
+     * one region, which is the granularity a person names when they point at a
+     * screen.
+     */
+    readonly cell?: number;
+    /**
+     * Cap on regions returned, largest first.
+     *
+     * Truncation is reported in {@link Isolation.truncated} rather than applied
+     * silently. A capped list that does not say it was capped reads as complete
+     * coverage, and the reader has no way to know the difference.
+     */
+    readonly limit?: number;
+}
+export interface Isolation {
+    readonly regions: readonly DiffRegion[];
+    /** Regions found but not returned, because of `limit`. `0` in the normal case. */
+    readonly truncated: number;
+    /** Changed pixels in the truncated tail. Nothing is lost silently. */
+    readonly truncatedPixels: number;
+}
+/**
+ * Cluster a change mask into regions.
+ *
+ * Connected components are computed on a coarse grid rather than on the pixels
+ * themselves. That is a performance decision and a semantic one at once: the
+ * coarse pass is one linear sweep instead of a merge over thousands of glyph-edge
+ * fragments, and it produces the grouping a reader would have produced by eye.
+ * Bounding boxes are then tightened back onto the actual changed pixels, so a
+ * region's coordinates are exact even though its *membership* was decided coarsely.
+ */
+export declare function isolateRegions(mask: ChangeMask, options?: IsolationOptions): Isolation;
+export interface Subtraction {
+    /** The mask with the excluded boxes cleared. Never the same object. */
+    readonly mask: ChangeMask;
+    /** Changed pixels that fell inside an excluded box. */
+    readonly ignored: number;
+    /**
+     * Pixels each input box cleared, in the order the boxes were given.
+     *
+     * Positional rather than keyed, because this file knows nothing about ignore
+     * rules and should not start: a box is geometry. The caller that supplied the
+     * boxes knows which rule each came from and can attribute the counts, which is
+     * what a per-rule register is assembled from.
+     *
+     * Two boxes overlapping share their pixels on a first-come basis, so these sum
+     * to {@link Subtraction.ignored} exactly and never double-count.
+     */
+    readonly cleared: readonly number[];
+    /**
+     * Boxes that covered no changed pixel at all.
+     *
+     * The raster half of the dead-ignore register. A mask drawn around a carousel
+     * that has since been removed covers nothing, and an operator who cannot see
+     * that keeps a hole in the suite because deleting it feels risky.
+     *
+     * Judged against the *original* mask, not against what earlier boxes left. Two
+     * rules covering one element is ordinary — a selector and a marker attribute
+     * reaching the same node — and clearing is first-come, so the second box would
+     * otherwise clear zero and be reported as covering nothing at all. That reads
+     * as "delete this rule" about a rule that is working.
+     */
+    readonly inert: readonly Rect[];
+}
+/**
+ * Clear excluded boxes out of a change mask, and say what that cost.
+ *
+ * The raster half of an ignore (spec 0024). The semantic half drops deltas under
+ * a subtree; this drops the pixels the same subtree occupied, so the two tiers
+ * cannot disagree about what the subject is — a region excluded semantically and
+ * still compared on pixels arrives as `unexplained`, the highest severity in the
+ * system, for something the operator already said was not the subject.
+ *
+ * Subtracting *before* isolation rather than filtering regions afterwards, which
+ * looks equivalent and is not: a region that straddles the boundary would
+ * otherwise be dropped whole or kept whole, and both answers are wrong. Clearing
+ * pixels lets the part outside the box cluster on its own and be reported.
+ *
+ * The count is returned rather than folded away. `changed` on the result is what
+ * the run compares against zero; `ignored` is what it owes the reader, because a
+ * comparison that discarded four thousand pixels and reported "no difference" is
+ * the failure this whole mechanism is written around.
+ */
+export declare function subtractRegions(mask: ChangeMask, boxes: readonly Rect[]): Subtraction;
+/**
+ * Excluded subtrees as device-pixel boxes on the raster's own canvas.
+ *
+ * The conversion that lets one declaration serve both tiers (spec 0024). A site
+ * is recorded in CSS pixels in page space, because that is what a document knows;
+ * a mask is device pixels in raster space, because that is what a screenshot is.
+ * Getting the transform wrong is not a small error — at the wrong scale every box
+ * lands in the top-left quadrant and silences whatever happens to be there — so
+ * it is inverted from exactly the expression `attributeRegions` uses in the other
+ * direction, in one place, rather than re-derived per caller.
+ *
+ * Sites with no `rect` are dropped: a profile with no layout engine observed no
+ * box, and a box that was never observed must never be inferred. The semantic
+ * half of the same rule still applies on that profile, which is the correct
+ * asymmetry — that profile decides no pixels either.
+ */
+export declare function excludedBoxes(snapshot: SemanticSnapshot, options: {
+    readonly scale: number;
+    readonly origin?: {
+        readonly x: number;
+        readonly y: number;
+    };
+}): readonly ExcludedBox[];
+/** A box, carrying the rule that excluded it so absorption can be attributed. */
+export interface ExcludedBox extends Rect {
+    readonly rule: string;
+}
+//# sourceMappingURL=mask.d.ts.map