@variance-authority/core 0.1.0

package/dist/compare/value.d.ts

@@ -0,0 +1,60 @@
+import { type CapturedValue } from '../format/value.js';
+import { type Digest } from '../format/hash.js';
+/**
+ * Two values become deltas — and no verdict (spec 0031).
+ *
+ * `compare/diff` does this for two rendered documents. This is the same shape at
+ * the floor of the subject list, where there is no schema, no position and
+ * therefore nothing that can decide whether a caller survives. What is left is
+ * real and smaller: which paths appeared, which vanished, which changed type,
+ * and which changed value.
+ *
+ * ## Why no library
+ *
+ * The untyped case is usually reached for `jsondiffpatch`, whose value is a
+ * longest-common-subsequence match over arrays and an optional text diff. Neither
+ * is wanted here: `ValueShaping.arrayKey` turns an array into an object
+ * before this function ever sees it, which is a better answer than guessing at
+ * moves, and a text diff of a leaf is a picture of a difference rather than a
+ * name for it. What remains is arithmetic, and `core` carries no dependency.
+ *
+ * ## What a delta does not carry
+ *
+ * No values. The two canonical texts are the baseline and the candidate and a
+ * person reads them side by side; a delta that quoted them would put a payload
+ * into the docket, the changelog and every record that accumulates — which is a
+ * retention decision this project must not make on an adopter's behalf.
+ */
+export type ValueChange = 'added' | 'removed' | 'type-changed' | 'value-changed';
+export interface ValueDelta {
+    readonly change: ValueChange;
+    /** RFC 6901 pointer to what moved. The empty string is the whole value. */
+    readonly pointer: string;
+    /**
+     * The shape of this difference, with position and values removed.
+     *
+     * Taken over the dialect, the *wildcarded* pointer and the kind of change — so
+     * the same edit at row 4 and at row 900 is one shape happening twice, and two
+     * subjects carrying it can be settled by one decision. Deliberately not over
+     * the subject: a fingerprint that named its subject could never group two.
+     */
+    readonly fingerprint: Digest;
+}
+/**
+ * Every difference between two shaped values, one delta per site.
+ *
+ * A subtree that appeared, vanished or changed kind is **one** delta at its root
+ * and is not descended into. A removed object reported as one removal per leaf is
+ * the forty-red-rectangles failure in a medium where nobody can see it at a
+ * glance, and the root is the thing a person would fix.
+ */
+export declare function compareValues(baseline: CapturedValue, candidate: CapturedValue): readonly ValueDelta[];
+/**
+ * The fingerprint a delta would carry, without having to produce the delta.
+ *
+ * Exported so that a rule scoped to a shape is written by copying a digest out of
+ * a report rather than by deriving one — the same property region fingerprints
+ * have, for the same reason.
+ */
+export declare function fingerprintOfValueDelta(dialect: string, pointer: string, change: ValueChange, keyed?: readonly string[]): Digest;
+//# sourceMappingURL=value.d.ts.map

package/dist/compare/value.js

@@ -0,0 +1,111 @@
+import { pointerShape, pointerToken } from '../format/value.js';
+import { digestCombine, digestString } from '../format/hash.js';
+/**
+ * Every difference between two shaped values, one delta per site.
+ *
+ * A subtree that appeared, vanished or changed kind is **one** delta at its root
+ * and is not descended into. A removed object reported as one removal per leaf is
+ * the forty-red-rectangles failure in a medium where nobody can see it at a
+ * glance, and the root is the thing a person would fix.
+ */
+export function compareValues(baseline, candidate) {
+    if (baseline.dialect !== candidate.dialect) {
+        throw new Error(`cannot compare a ${baseline.dialect} value against a ${candidate.dialect} one`);
+    }
+    if (baseline.recipe !== candidate.recipe) {
+        throw new Error(`these values were shaped under different rules (${baseline.recipe} and ` +
+            `${candidate.recipe}), so a difference between them may be the rules and not the value`);
+    }
+    const keyed = (baseline.keyed ?? []).join(' ');
+    if (keyed !== (candidate.keyed ?? []).join(' ')) {
+        throw new Error('these values keyed different arrays, so a row named by its identity on one side is ' +
+            'named by its position on the other');
+    }
+    const found = [];
+    walk(parse(baseline), parse(candidate), '', baseline.dialect, baseline.keyed ?? [], found);
+    // Code-unit ordering. Never `localeCompare`: this ordering reaches a report.
+    return found.sort((left, right) => {
+        if (left.pointer !== right.pointer)
+            return left.pointer < right.pointer ? -1 : 1;
+        if (left.change === right.change)
+            return 0;
+        return left.change < right.change ? -1 : 1;
+    });
+}
+/**
+ * The fingerprint a delta would carry, without having to produce the delta.
+ *
+ * Exported so that a rule scoped to a shape is written by copying a digest out of
+ * a report rather than by deriving one — the same property region fingerprints
+ * have, for the same reason.
+ */
+export function fingerprintOfValueDelta(dialect, pointer, change, keyed = []) {
+    const site = digestCombine('value-site/v1', [
+        digestString(dialect),
+        digestString(pointerShape(pointer, keyed)),
+    ]);
+    return digestCombine('value-change/v1', [site, digestString(change)]);
+}
+function parse(value) {
+    try {
+        return JSON.parse(value.text);
+    }
+    catch (error) {
+        throw new Error(`a ${value.dialect} value at ${value.digest} is not readable`, {
+            cause: error,
+        });
+    }
+}
+function kindOf(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+function walk(before, after, pointer, dialect, keyed, found) {
+    const was = kindOf(before);
+    const now = kindOf(after);
+    const record = (change, at) => {
+        found.push({
+            change,
+            pointer: at,
+            fingerprint: fingerprintOfValueDelta(dialect, at, change, keyed),
+        });
+    };
+    if (was !== now) {
+        record('type-changed', pointer);
+        return;
+    }
+    if (was === 'array') {
+        const olds = before;
+        const news = after;
+        for (let index = 0; index < Math.max(olds.length, news.length); index += 1) {
+            const at = `${pointer}/${index}`;
+            if (index >= news.length)
+                record('removed', at);
+            else if (index >= olds.length)
+                record('added', at);
+            else
+                walk(olds[index], news[index], at, dialect, keyed, found);
+        }
+        return;
+    }
+    if (was === 'object') {
+        const olds = before;
+        const news = after;
+        for (const key of new Set([...Object.keys(olds), ...Object.keys(news)])) {
+            const at = `${pointer}/${pointerToken(key)}`;
+            if (!(key in news))
+                record('removed', at);
+            else if (!(key in olds))
+                record('added', at);
+            else
+                walk(olds[key], news[key], at, dialect, keyed, found);
+        }
+        return;
+    }
+    if (before !== after)
+        record('value-changed', pointer);
+}
+//# sourceMappingURL=value.js.map

package/dist/compare/value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"value.js","sourceRoot":"","sources":["../../src/compare/value.ts"],"names":[],"mappings":"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","sourcesContent":["import { pointerShape, pointerToken, type CapturedValue } from '../format/value.js';\nimport { digestCombine, digestString, type Digest } from '../format/hash.js';\n\n/**\n * Two values become deltas — and no verdict (spec 0031).\n *\n * `compare/diff` does this for two rendered documents. This is the same shape at\n * the floor of the subject list, where there is no schema, no position and\n * therefore nothing that can decide whether a caller survives. What is left is\n * real and smaller: which paths appeared, which vanished, which changed type,\n * and which changed value.\n *\n * ## Why no library\n *\n * The untyped case is usually reached for `jsondiffpatch`, whose value is a\n * longest-common-subsequence match over arrays and an optional text diff. Neither\n * is wanted here: `ValueShaping.arrayKey` turns an array into an object\n * before this function ever sees it, which is a better answer than guessing at\n * moves, and a text diff of a leaf is a picture of a difference rather than a\n * name for it. What remains is arithmetic, and `core` carries no dependency.\n *\n * ## What a delta does not carry\n *\n * No values. The two canonical texts are the baseline and the candidate and a\n * person reads them side by side; a delta that quoted them would put a payload\n * into the docket, the changelog and every record that accumulates — which is a\n * retention decision this project must not make on an adopter's behalf.\n */\n\nexport type ValueChange = 'added' | 'removed' | 'type-changed' | 'value-changed';\n\nexport interface ValueDelta {\n  readonly change: ValueChange;\n\n  /** RFC 6901 pointer to what moved. The empty string is the whole value. */\n  readonly pointer: string;\n\n  /**\n   * The shape of this difference, with position and values removed.\n   *\n   * Taken over the dialect, the *wildcarded* pointer and the kind of change — so\n   * the same edit at row 4 and at row 900 is one shape happening twice, and two\n   * subjects carrying it can be settled by one decision. Deliberately not over\n   * the subject: a fingerprint that named its subject could never group two.\n   */\n  readonly fingerprint: Digest;\n}\n\n/** What kind of thing a canonical value is. A change between two of these is structural. */\ntype ValueKind = 'null' | 'boolean' | 'number' | 'string' | 'array' | 'object';\n\n/**\n * Every difference between two shaped values, one delta per site.\n *\n * A subtree that appeared, vanished or changed kind is **one** delta at its root\n * and is not descended into. A removed object reported as one removal per leaf is\n * the forty-red-rectangles failure in a medium where nobody can see it at a\n * glance, and the root is the thing a person would fix.\n */\nexport function compareValues(\n  baseline: CapturedValue,\n  candidate: CapturedValue,\n): readonly ValueDelta[] {\n  if (baseline.dialect !== candidate.dialect) {\n    throw new Error(\n      `cannot compare a ${baseline.dialect} value against a ${candidate.dialect} one`,\n    );\n  }\n  if (baseline.recipe !== candidate.recipe) {\n    throw new Error(\n      `these values were shaped under different rules (${baseline.recipe} and ` +\n        `${candidate.recipe}), so a difference between them may be the rules and not the value`,\n    );\n  }\n\n  const keyed = (baseline.keyed ?? []).join(' ');\n  if (keyed !== (candidate.keyed ?? []).join(' ')) {\n    throw new Error(\n      'these values keyed different arrays, so a row named by its identity on one side is ' +\n        'named by its position on the other',\n    );\n  }\n\n  const found: ValueDelta[] = [];\n  walk(parse(baseline), parse(candidate), '', baseline.dialect, baseline.keyed ?? [], found);\n\n  // Code-unit ordering. Never `localeCompare`: this ordering reaches a report.\n  return found.sort((left, right) => {\n    if (left.pointer !== right.pointer) return left.pointer < right.pointer ? -1 : 1;\n    if (left.change === right.change) return 0;\n    return left.change < right.change ? -1 : 1;\n  });\n}\n\n/**\n * The fingerprint a delta would carry, without having to produce the delta.\n *\n * Exported so that a rule scoped to a shape is written by copying a digest out of\n * a report rather than by deriving one — the same property region fingerprints\n * have, for the same reason.\n */\nexport function fingerprintOfValueDelta(\n  dialect: string,\n  pointer: string,\n  change: ValueChange,\n  keyed: readonly string[] = [],\n): Digest {\n  const site = digestCombine('value-site/v1', [\n    digestString(dialect),\n    digestString(pointerShape(pointer, keyed)),\n  ]);\n  return digestCombine('value-change/v1', [site, digestString(change)]);\n}\n\nfunction parse(value: CapturedValue): unknown {\n  try {\n    return JSON.parse(value.text);\n  } catch (error) {\n    throw new Error(`a ${value.dialect} value at ${value.digest} is not readable`, {\n      cause: error,\n    });\n  }\n}\n\nfunction kindOf(value: unknown): ValueKind {\n  if (value === null) return 'null';\n  if (Array.isArray(value)) return 'array';\n  return typeof value as ValueKind;\n}\n\nfunction walk(\n  before: unknown,\n  after: unknown,\n  pointer: string,\n  dialect: string,\n  keyed: readonly string[],\n  found: ValueDelta[],\n): void {\n  const was = kindOf(before);\n  const now = kindOf(after);\n\n  const record = (change: ValueChange, at: string): void => {\n    found.push({\n      change,\n      pointer: at,\n      fingerprint: fingerprintOfValueDelta(dialect, at, change, keyed),\n    });\n  };\n\n  if (was !== now) {\n    record('type-changed', pointer);\n    return;\n  }\n\n  if (was === 'array') {\n    const olds = before as readonly unknown[];\n    const news = after as readonly unknown[];\n    for (let index = 0; index < Math.max(olds.length, news.length); index += 1) {\n      const at = `${pointer}/${index}`;\n      if (index >= news.length) record('removed', at);\n      else if (index >= olds.length) record('added', at);\n      else walk(olds[index], news[index], at, dialect, keyed, found);\n    }\n    return;\n  }\n\n  if (was === 'object') {\n    const olds = before as Record<string, unknown>;\n    const news = after as Record<string, unknown>;\n    for (const key of new Set([...Object.keys(olds), ...Object.keys(news)])) {\n      const at = `${pointer}/${pointerToken(key)}`;\n      if (!(key in news)) record('removed', at);\n      else if (!(key in olds)) record('added', at);\n      else walk(olds[key], news[key], at, dialect, keyed, found);\n    }\n    return;\n  }\n\n  if (before !== after) record('value-changed', pointer);\n}\n"]}

package/dist/format/accessibility.d.ts

@@ -0,0 +1,27 @@
+import { type Digest } from './hash.js';
+/**
+ * The browser accessibility trees exposed by one Playwright acquisition.
+ *
+ * `roots[0]` is the subject locator. Remaining roots are React portal contents,
+ * in component-tree order, because a portal remains part of the subject even
+ * though its DOM lives elsewhere (ADR-0007). The text is Playwright's ARIA
+ * snapshot format rather than this project's ARIA approximation: browser
+ * visibility, naming and role computation are the boundary being observed.
+ */
+export interface AccessibilitySnapshot {
+    readonly snapshotVersion: 1;
+    readonly producer: 'playwright-aria@1';
+    readonly engine: string;
+    /**
+     * One boundary-relative Playwright snapshot per requested root.
+     *
+     * An empty string is an observed root with no exposed accessibility nodes,
+     * not missing evidence. A root also need not name a parent or any children:
+     * boundary truncation is part of the reading and is hashed without repair.
+     */
+    readonly roots: readonly string[];
+    readonly digest: Digest;
+}
+/** Build the canonical, content-addressed form stored beside a raster. */
+export declare function accessibilitySnapshot(engine: string, roots: readonly string[]): AccessibilitySnapshot;
+//# sourceMappingURL=accessibility.d.ts.map

package/dist/format/accessibility.js

@@ -0,0 +1,17 @@
+import { digestValue } from './hash.js';
+/** Build the canonical, content-addressed form stored beside a raster. */
+export function accessibilitySnapshot(engine, roots) {
+    const stableRoots = [...roots];
+    return {
+        snapshotVersion: 1,
+        producer: 'playwright-aria@1',
+        engine,
+        roots: stableRoots,
+        digest: digestValue({
+            producer: 'playwright-aria@1',
+            engine,
+            roots: stableRoots,
+        }),
+    };
+}
+//# sourceMappingURL=accessibility.js.map

package/dist/format/accessibility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessibility.js","sourceRoot":"","sources":["../../src/format/accessibility.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAe,MAAM,WAAW,CAAC;AA0BrD,0EAA0E;AAC1E,MAAM,UAAU,qBAAqB,CACnC,MAAc,EACd,KAAwB;IAExB,MAAM,WAAW,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;IAC/B,OAAO;QACL,eAAe,EAAE,CAAC;QAClB,QAAQ,EAAE,mBAAmB;QAC7B,MAAM;QACN,KAAK,EAAE,WAAW;QAClB,MAAM,EAAE,WAAW,CAAC;YAClB,QAAQ,EAAE,mBAAmB;YAC7B,MAAM;YACN,KAAK,EAAE,WAAW;SACnB,CAAC;KACH,CAAC;AACJ,CAAC","sourcesContent":["import { digestValue, type Digest } from './hash.js';\n\n/**\n * The browser accessibility trees exposed by one Playwright acquisition.\n *\n * `roots[0]` is the subject locator. Remaining roots are React portal contents,\n * in component-tree order, because a portal remains part of the subject even\n * though its DOM lives elsewhere (ADR-0007). The text is Playwright's ARIA\n * snapshot format rather than this project's ARIA approximation: browser\n * visibility, naming and role computation are the boundary being observed.\n */\nexport interface AccessibilitySnapshot {\n  readonly snapshotVersion: 1;\n  readonly producer: 'playwright-aria@1';\n  readonly engine: string;\n  /**\n   * One boundary-relative Playwright snapshot per requested root.\n   *\n   * An empty string is an observed root with no exposed accessibility nodes,\n   * not missing evidence. A root also need not name a parent or any children:\n   * boundary truncation is part of the reading and is hashed without repair.\n   */\n  readonly roots: readonly string[];\n  readonly digest: Digest;\n}\n\n/** Build the canonical, content-addressed form stored beside a raster. */\nexport function accessibilitySnapshot(\n  engine: string,\n  roots: readonly string[],\n): AccessibilitySnapshot {\n  const stableRoots = [...roots];\n  return {\n    snapshotVersion: 1,\n    producer: 'playwright-aria@1',\n    engine,\n    roots: stableRoots,\n    digest: digestValue({\n      producer: 'playwright-aria@1',\n      engine,\n      roots: stableRoots,\n    }),\n  };\n}\n"]}

package/dist/format/canonical.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Canonical serialization.
+ *
+ * Determinism (Principle 2) means byte-identical output for identical inputs, on
+ * any machine. `JSON.stringify` does not provide that: key order follows
+ * insertion order, and float formatting is the one place where "obvious" and
+ * "identical everywhere" diverge.
+ *
+ * Everything hashed by this system passes through `canonicalize` first.
+ */
+export type CanonicalValue = string | number | boolean | null | readonly CanonicalValue[] | {
+    readonly [key: string]: CanonicalValue | undefined;
+};
+/**
+ * Serialize to a canonical string: object keys sorted by code unit, `undefined`
+ * members omitted (never emitted as `null`), and numbers formatted per
+ * {@link canonicalNumber}.
+ *
+ * Omitting rather than nulling `undefined` is what makes "a dimension this
+ * profile cannot observe" structurally absent from the hash input rather than
+ * present-and-empty (ADR-0002). Absence and emptiness must not collide.
+ *
+ * @throws {RangeError} on `NaN` or `Infinity` — a non-finite value in a hash
+ * input means an upstream measurement failed, and silently encoding it would
+ * produce a stable hash for a broken observation.
+ */
+export declare function canonicalize(value: CanonicalValue): string;
+/**
+ * Format a number identically across platforms.
+ *
+ * `-0` normalizes to `0`: it is a legitimate output of layout arithmetic and is
+ * indistinguishable from `0` to every consumer, but stringifies differently.
+ * Integers are emitted without a decimal point; other values keep full round-trip
+ * precision, having already been rounded to their dimension's tolerance by the
+ * ruleset (lengths to px at fixed precision) before reaching here.
+ */
+export declare function canonicalNumber(value: number): string;
+//# sourceMappingURL=canonical.d.ts.map

package/dist/format/canonical.js

@@ -0,0 +1,65 @@
+/**
+ * Canonical serialization.
+ *
+ * Determinism (Principle 2) means byte-identical output for identical inputs, on
+ * any machine. `JSON.stringify` does not provide that: key order follows
+ * insertion order, and float formatting is the one place where "obvious" and
+ * "identical everywhere" diverge.
+ *
+ * Everything hashed by this system passes through `canonicalize` first.
+ */
+/**
+ * Serialize to a canonical string: object keys sorted by code unit, `undefined`
+ * members omitted (never emitted as `null`), and numbers formatted per
+ * {@link canonicalNumber}.
+ *
+ * Omitting rather than nulling `undefined` is what makes "a dimension this
+ * profile cannot observe" structurally absent from the hash input rather than
+ * present-and-empty (ADR-0002). Absence and emptiness must not collide.
+ *
+ * @throws {RangeError} on `NaN` or `Infinity` — a non-finite value in a hash
+ * input means an upstream measurement failed, and silently encoding it would
+ * produce a stable hash for a broken observation.
+ */
+export function canonicalize(value) {
+    if (value === null)
+        return 'null';
+    switch (typeof value) {
+        case 'boolean':
+            return value ? 'true' : 'false';
+        case 'number':
+            return canonicalNumber(value);
+        case 'string':
+            return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => canonicalize(item)).join(',')}]`;
+    }
+    const record = value;
+    const parts = [];
+    for (const key of Object.keys(record).sort()) {
+        const member = record[key];
+        if (member === undefined)
+            continue;
+        parts.push(`${JSON.stringify(key)}:${canonicalize(member)}`);
+    }
+    return `{${parts.join(',')}}`;
+}
+/**
+ * Format a number identically across platforms.
+ *
+ * `-0` normalizes to `0`: it is a legitimate output of layout arithmetic and is
+ * indistinguishable from `0` to every consumer, but stringifies differently.
+ * Integers are emitted without a decimal point; other values keep full round-trip
+ * precision, having already been rounded to their dimension's tolerance by the
+ * ruleset (lengths to px at fixed precision) before reaching here.
+ */
+export function canonicalNumber(value) {
+    if (!Number.isFinite(value)) {
+        throw new RangeError(`canonical serialization requires a finite number, received ${value}`);
+    }
+    if (Object.is(value, -0))
+        return '0';
+    return String(value);
+}
+//# sourceMappingURL=canonical.js.map

package/dist/format/canonical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.js","sourceRoot":"","sources":["../../src/format/canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAUH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,KAAqB;IAChD,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAElC,QAAQ,OAAO,KAAK,EAAE,CAAC;QACrB,KAAK,SAAS;YACZ,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;QAClC,KAAK,QAAQ;YACX,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;QAChC,KAAK,QAAQ;YACX,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAClE,CAAC;IAED,MAAM,MAAM,GAAG,KAA+D,CAAC;IAC/E,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAC7C,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC3B,IAAI,MAAM,KAAK,SAAS;YAAE,SAAS;QACnC,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAChC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,UAAU,CAAC,8DAA8D,KAAK,EAAE,CAAC,CAAC;IAC9F,CAAC;IACD,IAAI,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAAE,OAAO,GAAG,CAAC;IACrC,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC","sourcesContent":["/**\n * Canonical serialization.\n *\n * Determinism (Principle 2) means byte-identical output for identical inputs, on\n * any machine. `JSON.stringify` does not provide that: key order follows\n * insertion order, and float formatting is the one place where \"obvious\" and\n * \"identical everywhere\" diverge.\n *\n * Everything hashed by this system passes through `canonicalize` first.\n */\n\nexport type CanonicalValue =\n  | string\n  | number\n  | boolean\n  | null\n  | readonly CanonicalValue[]\n  | { readonly [key: string]: CanonicalValue | undefined };\n\n/**\n * Serialize to a canonical string: object keys sorted by code unit, `undefined`\n * members omitted (never emitted as `null`), and numbers formatted per\n * {@link canonicalNumber}.\n *\n * Omitting rather than nulling `undefined` is what makes \"a dimension this\n * profile cannot observe\" structurally absent from the hash input rather than\n * present-and-empty (ADR-0002). Absence and emptiness must not collide.\n *\n * @throws {RangeError} on `NaN` or `Infinity` — a non-finite value in a hash\n * input means an upstream measurement failed, and silently encoding it would\n * produce a stable hash for a broken observation.\n */\nexport function canonicalize(value: CanonicalValue): string {\n  if (value === null) return 'null';\n\n  switch (typeof value) {\n    case 'boolean':\n      return value ? 'true' : 'false';\n    case 'number':\n      return canonicalNumber(value);\n    case 'string':\n      return JSON.stringify(value);\n  }\n\n  if (Array.isArray(value)) {\n    return `[${value.map((item) => canonicalize(item)).join(',')}]`;\n  }\n\n  const record = value as { readonly [key: string]: CanonicalValue | undefined };\n  const parts: string[] = [];\n  for (const key of Object.keys(record).sort()) {\n    const member = record[key];\n    if (member === undefined) continue;\n    parts.push(`${JSON.stringify(key)}:${canonicalize(member)}`);\n  }\n  return `{${parts.join(',')}}`;\n}\n\n/**\n * Format a number identically across platforms.\n *\n * `-0` normalizes to `0`: it is a legitimate output of layout arithmetic and is\n * indistinguishable from `0` to every consumer, but stringifies differently.\n * Integers are emitted without a decimal point; other values keep full round-trip\n * precision, having already been rounded to their dimension's tolerance by the\n * ruleset (lengths to px at fixed precision) before reaching here.\n */\nexport function canonicalNumber(value: number): string {\n  if (!Number.isFinite(value)) {\n    throw new RangeError(`canonical serialization requires a finite number, received ${value}`);\n  }\n  if (Object.is(value, -0)) return '0';\n  return String(value);\n}\n"]}

package/dist/format/capture.d.ts

@@ -0,0 +1,212 @@
+import type { EnvironmentInputs } from './environment.js';
+import type { ObservationProfile } from './profile.js';
+import type { Provenance } from './provenance.js';
+import type { Wiring } from './wiring.js';
+import type { Holding } from './holding.js';
+/**
+ * The collector/core boundary.
+ *
+ * Collectors **extract**; `core` **normalizes**. Nothing in this file is a live
+ * object — a `RawCapture` is plain data, fully serializable, produced by touching
+ * a DOM and consumed by code that has never seen one.
+ *
+ * Two properties fall out of that split, and both are the reason for it:
+ *
+ * 1. **One ruleset, by construction.** Normalization is the moat (ADR-0003) and
+ *    the thing most likely to drift between two implementations. If the JSDOM and
+ *    Chromium collectors each normalized their own captures, "the same rules ran"
+ *    would be a claim maintained by discipline. Here it is a fact of the call
+ *    graph: there is one normalizer and both profiles enter it.
+ * 2. **The sub-renderer can be anywhere.** A capture crossing a worker boundary,
+ *    a pipe, or a network hop to a device farm is the same value it was in
+ *    process. No code may assume the collector is local.
+ */
+export interface RawCapture {
+    readonly captureVersion: 1;
+    readonly subject: SubjectRef;
+    readonly profile: ObservationProfile;
+    /**
+     * Environment inputs the *collector* is positioned to know — engine version,
+     * fonts actually loaded, resolved conditions, asset hashes. The ruleset and
+     * allowlist versions are `core`'s to supply, so they are absent here and the
+     * key is completed during normalization.
+     */
+    readonly environment: Omit<EnvironmentInputs, 'ruleset' | 'allowlist'>;
+    readonly root: RawNode;
+    /**
+     * Inherited values in force at the subject root.
+     *
+     * Mandatory, not an optimization. CSS applicability pruning (ADR-0003) drops
+     * every rule that matches nothing inside the subtree — including rules on
+     * ancestors *outside* it whose inheritable properties still reach in. Without
+     * this seed the cheap tier is unsound and will report false `unchanged`.
+     */
+    readonly inheritedSeed: Readonly<Record<string, string>>;
+    /**
+     * Subtrees this subject renders through portals, in fiber traversal order.
+     *
+     * A subject's boundary is a component-tree question, not a DOM-containment
+     * one: `createPortal` renders elsewhere in the document while remaining part
+     * of the tree rooted here. Omitting these makes an opening modal report
+     * `unchanged`, because its own container is byte-identical (ADR-0007).
+     */
+    readonly portals?: readonly RawNode[];
+    /**
+     * Shared root state this subject is *latently* coupled to.
+     *
+     * Rules like `html.dark .card` contribute nothing today and everything the
+     * moment `dark` lands on `<html>`. In a session that reuses one document across
+     * subjects, that moment may arrive because a *different* subject put it there —
+     * turning this subject's baseline order-dependent with no visible cause.
+     * Recorded so the coupling can be reported before it bites.
+     */
+    readonly couplings?: readonly string[];
+    /** Anything the collector could not do. Empty is the expected case. */
+    readonly diagnostics: readonly Diagnostic[];
+}
+export interface SubjectRef {
+    /** Stable across renames of the file, e.g. `story:components-button--primary`. */
+    readonly id: string;
+    /**
+     * What kind of thing this is, which is not the same question as what produced
+     * it.
+     *
+     * `value` is the one that is not a rendering: a JSON body, a schema, a route
+     * table. It is a fourth member rather than a reuse of `route`, which already
+     * means *a page rendered at a URL* — a route table is a value about the same
+     * paths, and a subject list where one word meant both is one nobody can filter.
+     */
+    readonly kind: 'story' | 'route' | 'fixture' | 'value';
+    readonly title?: string;
+}
+/**
+ * A node exactly as observed, before any rule is applied.
+ *
+ * Raw means raw: `attributes` still holds generated ids and hashed class names,
+ * `matchedRules` still holds cascade losers. Normalization needs the unedited
+ * input — a collector that helpfully pre-cleaned would be a second, invisible
+ * ruleset, versioned by nothing.
+ */
+export interface RawNode {
+    readonly tag: string;
+    readonly attributes: Readonly<Record<string, string>>;
+    /** Resolved accessibility properties, when the profile provides them. */
+    readonly aria?: RawAria;
+    /**
+     * Rules matching this node, as authored.
+     *
+     * Losing declarations are retained: `core` resolves the cascade for profiles
+     * whose engine did not (ADR-0003 step 5), and cannot do that from winners
+     * alone. Shorthands are retained *unexpanded* — expansion is `core`'s job, so
+     * that it is versioned by the ruleset rather than by each collector.
+     *
+     * A collector MAY drop a declaration whose property is neither allowlisted nor
+     * a shorthand of an allowlisted property, and SHOULD when the capture crosses
+     * a network hop. It MUST NOT normalize values; a helpfully pre-cleaned capture
+     * is a second, invisible ruleset versioned by nothing.
+     */
+    readonly matchedRules: readonly MatchedRule[];
+    readonly inlineStyle?: Readonly<Record<string, string>>;
+    /** Engine-resolved computed style. Present only when `profile.computedStyle`. */
+    readonly computedStyle?: Readonly<Record<string, string>>;
+    /** Present only when `profile.layout`. */
+    readonly rect?: Rect;
+    /** Literal text of a text node. Digested during normalization, per policy. */
+    readonly text?: string;
+    readonly provenance?: Provenance;
+    /**
+     * How the framework holds this node's component, when an adapter supplied it.
+     *
+     * Beside `provenance` because it arrives from the same seam and under the same
+     * rule: the collector carries no framework dependency and both are injected.
+     * See {@link Wiring} for why it is a dimension rather than another attribution
+     * field.
+     */
+    readonly wiring?: Wiring;
+    /**
+     * What the component that authored this node was holding, when an adapter
+     * supplied it.
+     *
+     * A third injection at the same seam, and deliberately not folded into
+     * `wiring`: wiring is hashed into a band and this may never be, so a caller
+     * that wants the band must be able to have it without also carrying values,
+     * and a caller that wants explanations must be able to ask for them without
+     * changing a single digest. See {@link Holding}.
+     */
+    readonly holding?: Holding;
+    readonly children: readonly RawNode[];
+    /** Nodes inside a shadow root, kept distinct from light-DOM children. */
+    readonly shadowChildren?: readonly RawNode[];
+    /**
+     * Ignore rules the collector found this element under (spec 0024).
+     *
+     * A mark, not a removal. The collector is the only thing holding a live DOM, so
+     * it is the only thing that can run a selector or read a marker attribute — but
+     * it must not act on what it finds. An element deleted from the capture would
+     * be invisible to every count downstream, and the difference between "absorbed
+     * by the `carousel` rule" and "was never there" is the difference between an
+     * ignore and a blind spot.
+     *
+     * Never hashed. Normalization turns these into
+     * {@link import('./snapshot.js').SemanticSnapshot.ignoreSites}, which sits
+     * beside `styleProvenance` outside the render hash for the same reason: masking
+     * a clock changes what a run *says*, not what it *renders*, and must not
+     * re-baseline the repository.
+     */
+    readonly ignoredBy?: readonly string[];
+}
+export interface RawAria {
+    readonly role: string | null;
+    readonly name: string | null;
+    /**
+     * Accessible description — what `aria-describedby` and `title` resolve to.
+     *
+     * Captured because nothing else captures it, and its absence was a hole. The
+     * attribute allowlist drops every `aria-*` attribute on the stated grounds
+     * that they "are resolved into role/name/state" — true of `aria-label` and
+     * `aria-selected`, and false of `aria-describedby`, which resolves into a
+     * description and had nowhere to land. A field whose `aria-describedby`
+     * pointed at a deleted error message compared **equal**: the reference was
+     * dropped by the allowlist, the name was unaffected, and the regression was
+     * silent on every tier including raster.
+     */
+    readonly description?: string | null;
+    /** `checked`, `disabled`, `expanded`, `selected`, … */
+    readonly state: Readonly<Record<string, string | boolean | number>>;
+}
+export interface MatchedRule {
+    /** Identifies the origin sheet for attribution: href, or a synthetic id. */
+    readonly sheet: string;
+    readonly selector: string;
+    /** `[idCount, classCount, typeCount]` — CSS specificity, most significant first. */
+    readonly specificity: readonly [number, number, number];
+    /** Document order of the rule. Breaks specificity ties, per the cascade. */
+    readonly order: number;
+    readonly declarations: readonly Declaration[];
+    /** Source position, when the sheet exposes one. Turns a diff into a file:line. */
+    readonly source?: {
+        readonly file: string;
+        readonly line: number;
+    };
+}
+export interface Declaration {
+    readonly property: string;
+    readonly value: string;
+    readonly important: boolean;
+    /** Custom properties referenced by the value, for token-keyed attribution. */
+    readonly references?: readonly string[];
+}
+/** Browser-layout coordinates retained as evidence, without a preferred layout policy. */
+export interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+export interface Diagnostic {
+    readonly severity: 'warn' | 'error';
+    readonly code: string;
+    readonly message: string;
+    readonly nodePath?: string;
+}
+//# sourceMappingURL=capture.d.ts.map

package/dist/format/capture.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=capture.js.map

package/dist/format/capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.js","sourceRoot":"","sources":["../../src/format/capture.ts"],"names":[],"mappings":"","sourcesContent":["import type { EnvironmentInputs } from './environment.js';\nimport type { ObservationProfile } from './profile.js';\nimport type { Provenance } from './provenance.js';\nimport type { Wiring } from './wiring.js';\nimport type { Holding } from './holding.js';\n\n/**\n * The collector/core boundary.\n *\n * Collectors **extract**; `core` **normalizes**. Nothing in this file is a live\n * object — a `RawCapture` is plain data, fully serializable, produced by touching\n * a DOM and consumed by code that has never seen one.\n *\n * Two properties fall out of that split, and both are the reason for it:\n *\n * 1. **One ruleset, by construction.** Normalization is the moat (ADR-0003) and\n *    the thing most likely to drift between two implementations. If the JSDOM and\n *    Chromium collectors each normalized their own captures, \"the same rules ran\"\n *    would be a claim maintained by discipline. Here it is a fact of the call\n *    graph: there is one normalizer and both profiles enter it.\n * 2. **The sub-renderer can be anywhere.** A capture crossing a worker boundary,\n *    a pipe, or a network hop to a device farm is the same value it was in\n *    process. No code may assume the collector is local.\n */\nexport interface RawCapture {\n  readonly captureVersion: 1;\n  readonly subject: SubjectRef;\n  readonly profile: ObservationProfile;\n\n  /**\n   * Environment inputs the *collector* is positioned to know — engine version,\n   * fonts actually loaded, resolved conditions, asset hashes. The ruleset and\n   * allowlist versions are `core`'s to supply, so they are absent here and the\n   * key is completed during normalization.\n   */\n  readonly environment: Omit<EnvironmentInputs, 'ruleset' | 'allowlist'>;\n\n  readonly root: RawNode;\n\n  /**\n   * Inherited values in force at the subject root.\n   *\n   * Mandatory, not an optimization. CSS applicability pruning (ADR-0003) drops\n   * every rule that matches nothing inside the subtree — including rules on\n   * ancestors *outside* it whose inheritable properties still reach in. Without\n   * this seed the cheap tier is unsound and will report false `unchanged`.\n   */\n  readonly inheritedSeed: Readonly<Record<string, string>>;\n\n  /**\n   * Subtrees this subject renders through portals, in fiber traversal order.\n   *\n   * A subject's boundary is a component-tree question, not a DOM-containment\n   * one: `createPortal` renders elsewhere in the document while remaining part\n   * of the tree rooted here. Omitting these makes an opening modal report\n   * `unchanged`, because its own container is byte-identical (ADR-0007).\n   */\n  readonly portals?: readonly RawNode[];\n\n  /**\n   * Shared root state this subject is *latently* coupled to.\n   *\n   * Rules like `html.dark .card` contribute nothing today and everything the\n   * moment `dark` lands on `<html>`. In a session that reuses one document across\n   * subjects, that moment may arrive because a *different* subject put it there —\n   * turning this subject's baseline order-dependent with no visible cause.\n   * Recorded so the coupling can be reported before it bites.\n   */\n  readonly couplings?: readonly string[];\n\n  /** Anything the collector could not do. Empty is the expected case. */\n  readonly diagnostics: readonly Diagnostic[];\n}\n\nexport interface SubjectRef {\n  /** Stable across renames of the file, e.g. `story:components-button--primary`. */\n  readonly id: string;\n\n  /**\n   * What kind of thing this is, which is not the same question as what produced\n   * it.\n   *\n   * `value` is the one that is not a rendering: a JSON body, a schema, a route\n   * table. It is a fourth member rather than a reuse of `route`, which already\n   * means *a page rendered at a URL* — a route table is a value about the same\n   * paths, and a subject list where one word meant both is one nobody can filter.\n   */\n  readonly kind: 'story' | 'route' | 'fixture' | 'value';\n  readonly title?: string;\n}\n\n/**\n * A node exactly as observed, before any rule is applied.\n *\n * Raw means raw: `attributes` still holds generated ids and hashed class names,\n * `matchedRules` still holds cascade losers. Normalization needs the unedited\n * input — a collector that helpfully pre-cleaned would be a second, invisible\n * ruleset, versioned by nothing.\n */\nexport interface RawNode {\n  readonly tag: string;\n  readonly attributes: Readonly<Record<string, string>>;\n\n  /** Resolved accessibility properties, when the profile provides them. */\n  readonly aria?: RawAria;\n\n  /**\n   * Rules matching this node, as authored.\n   *\n   * Losing declarations are retained: `core` resolves the cascade for profiles\n   * whose engine did not (ADR-0003 step 5), and cannot do that from winners\n   * alone. Shorthands are retained *unexpanded* — expansion is `core`'s job, so\n   * that it is versioned by the ruleset rather than by each collector.\n   *\n   * A collector MAY drop a declaration whose property is neither allowlisted nor\n   * a shorthand of an allowlisted property, and SHOULD when the capture crosses\n   * a network hop. It MUST NOT normalize values; a helpfully pre-cleaned capture\n   * is a second, invisible ruleset versioned by nothing.\n   */\n  readonly matchedRules: readonly MatchedRule[];\n\n  readonly inlineStyle?: Readonly<Record<string, string>>;\n\n  /** Engine-resolved computed style. Present only when `profile.computedStyle`. */\n  readonly computedStyle?: Readonly<Record<string, string>>;\n\n  /** Present only when `profile.layout`. */\n  readonly rect?: Rect;\n\n  /** Literal text of a text node. Digested during normalization, per policy. */\n  readonly text?: string;\n\n  readonly provenance?: Provenance;\n\n  /**\n   * How the framework holds this node's component, when an adapter supplied it.\n   *\n   * Beside `provenance` because it arrives from the same seam and under the same\n   * rule: the collector carries no framework dependency and both are injected.\n   * See {@link Wiring} for why it is a dimension rather than another attribution\n   * field.\n   */\n  readonly wiring?: Wiring;\n\n  /**\n   * What the component that authored this node was holding, when an adapter\n   * supplied it.\n   *\n   * A third injection at the same seam, and deliberately not folded into\n   * `wiring`: wiring is hashed into a band and this may never be, so a caller\n   * that wants the band must be able to have it without also carrying values,\n   * and a caller that wants explanations must be able to ask for them without\n   * changing a single digest. See {@link Holding}.\n   */\n  readonly holding?: Holding;\n\n  readonly children: readonly RawNode[];\n\n  /** Nodes inside a shadow root, kept distinct from light-DOM children. */\n  readonly shadowChildren?: readonly RawNode[];\n\n  /**\n   * Ignore rules the collector found this element under (spec 0024).\n   *\n   * A mark, not a removal. The collector is the only thing holding a live DOM, so\n   * it is the only thing that can run a selector or read a marker attribute — but\n   * it must not act on what it finds. An element deleted from the capture would\n   * be invisible to every count downstream, and the difference between \"absorbed\n   * by the `carousel` rule\" and \"was never there\" is the difference between an\n   * ignore and a blind spot.\n   *\n   * Never hashed. Normalization turns these into\n   * {@link import('./snapshot.js').SemanticSnapshot.ignoreSites}, which sits\n   * beside `styleProvenance` outside the render hash for the same reason: masking\n   * a clock changes what a run *says*, not what it *renders*, and must not\n   * re-baseline the repository.\n   */\n  readonly ignoredBy?: readonly string[];\n}\n\nexport interface RawAria {\n  readonly role: string | null;\n  readonly name: string | null;\n\n  /**\n   * Accessible description — what `aria-describedby` and `title` resolve to.\n   *\n   * Captured because nothing else captures it, and its absence was a hole. The\n   * attribute allowlist drops every `aria-*` attribute on the stated grounds\n   * that they \"are resolved into role/name/state\" — true of `aria-label` and\n   * `aria-selected`, and false of `aria-describedby`, which resolves into a\n   * description and had nowhere to land. A field whose `aria-describedby`\n   * pointed at a deleted error message compared **equal**: the reference was\n   * dropped by the allowlist, the name was unaffected, and the regression was\n   * silent on every tier including raster.\n   */\n  readonly description?: string | null;\n\n  /** `checked`, `disabled`, `expanded`, `selected`, … */\n  readonly state: Readonly<Record<string, string | boolean | number>>;\n}\n\nexport interface MatchedRule {\n  /** Identifies the origin sheet for attribution: href, or a synthetic id. */\n  readonly sheet: string;\n  readonly selector: string;\n  /** `[idCount, classCount, typeCount]` — CSS specificity, most significant first. */\n  readonly specificity: readonly [number, number, number];\n  /** Document order of the rule. Breaks specificity ties, per the cascade. */\n  readonly order: number;\n  readonly declarations: readonly Declaration[];\n  /** Source position, when the sheet exposes one. Turns a diff into a file:line. */\n  readonly source?: { readonly file: string; readonly line: number };\n}\n\nexport interface Declaration {\n  readonly property: string;\n  readonly value: string;\n  readonly important: boolean;\n  /** Custom properties referenced by the value, for token-keyed attribution. */\n  readonly references?: readonly string[];\n}\n\n/** Browser-layout coordinates retained as evidence, without a preferred layout policy. */\nexport interface Rect {\n  readonly x: number;\n  readonly y: number;\n  readonly width: number;\n  readonly height: number;\n}\n\nexport interface Diagnostic {\n  readonly severity: 'warn' | 'error';\n  readonly code: string;\n  readonly message: string;\n  readonly nodePath?: string;\n}\n"]}