@variance-authority/core 0.1.0

package/dist/rules/normalize/value.js

@@ -0,0 +1,162 @@
+import { canonicalizeColor, isColorProperty } from './color.js';
+/**
+ * Declaration-value canonicalization.
+ *
+ * Every value entering a snapshot passes through here. The job is to erase every
+ * way CSS lets an author write the same thing differently — spacing, casing,
+ * absolute unit choice, float formatting — so that reformatting a stylesheet is
+ * not a mass-invalidation event.
+ *
+ * The discipline is one-directional: collapse only differences that provably
+ * cannot reach a pixel. Anything that *might* render differently is left alone,
+ * because an over-eager equivalence here produces a false `unchanged`, and the
+ * cost of the opposite mistake is only a review that did not need to happen.
+ */
+/** Absolute lengths, in CSS px. Fixed by spec, so conversion is lossless. */
+const ABSOLUTE_LENGTHS = {
+    px: 1,
+    pt: 96 / 72,
+    pc: 16,
+    in: 96,
+    cm: 96 / 2.54,
+    mm: 96 / 25.4,
+    q: 96 / 101.6,
+};
+/** Angles, in degrees. */
+const ANGLES = {
+    deg: 1,
+    grad: 0.9,
+    rad: 180 / Math.PI,
+    turn: 360,
+};
+/**
+ * Units left symbolic because they cannot be resolved without a layout engine.
+ *
+ * This is the `declared-only` boundary made concrete (ADR-0002): under a profile
+ * without computed style, `padding: 1rem` stays `1rem`. That is honest — it is
+ * genuinely all that tier knows — and it is why JSDOM decides the token band
+ * `declared-only` rather than `full`. Resolving these by assuming a root font
+ * size would fabricate precision the tier does not have.
+ */
+export const RELATIVE_UNITS = [
+    'em', 'rem', 'ex', 'ch', 'cap', 'ic', 'lh', 'rlh',
+    'vw', 'vh', 'vmin', 'vmax', 'vi', 'vb',
+    'svw', 'svh', 'lvw', 'lvh', 'dvw', 'dvh', '%',
+];
+/** Decimal places kept for a length. Absorbs float noise, keeps sub-pixel intent. */
+const LENGTH_PRECISION = 4;
+export function canonicalizeValue(property, value) {
+    if (isColorProperty(property))
+        return canonicalizeColor(value);
+    return canonicalizeTokens(value);
+}
+/**
+ * Rewrite a value token by token.
+ *
+ * Quoted strings and `url()` payloads are passed through untouched: a font
+ * family name and a resource path are opaque data, and normalizing their case
+ * would change what they refer to.
+ */
+export function canonicalizeTokens(value) {
+    const out = [];
+    let index = 0;
+    const input = value.trim();
+    while (index < input.length) {
+        const char = input[index];
+        if (/\s/.test(char)) {
+            if (out.length > 0 && out[out.length - 1] !== ' ')
+                out.push(' ');
+            index += 1;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            const end = closingQuote(input, index);
+            out.push(input.slice(index, end + 1));
+            index = end + 1;
+            continue;
+        }
+        if (input.slice(index).toLowerCase().startsWith('url(')) {
+            const end = matchingParen(input, index + 3);
+            out.push(`url${input.slice(index + 3, end + 1)}`);
+            index = end + 1;
+            continue;
+        }
+        const numeric = /^[+-]?(\d+\.?\d*|\.\d+)(e[+-]?\d+)?([a-z%]*)/i.exec(input.slice(index));
+        if (numeric && numeric[0].length > 0) {
+            out.push(canonicalizeDimension(numeric[0]));
+            index += numeric[0].length;
+            continue;
+        }
+        const identifier = /^[a-z_-][\w-]*/i.exec(input.slice(index));
+        if (identifier) {
+            // Unquoted identifiers are CSS keywords and function names, both
+            // case-insensitive to the parser and therefore safe to fold.
+            out.push(identifier[0].toLowerCase());
+            index += identifier[0].length;
+            continue;
+        }
+        // Punctuation: `,` `(` `)` `/` `*`. Drop whitespace before a comma so
+        // `a , b` and `a, b` converge.
+        if (char === ',' && out[out.length - 1] === ' ')
+            out.pop();
+        out.push(char);
+        index += 1;
+    }
+    return out.join('').trim();
+}
+/** Canonicalize one `<number><unit>` token. */
+export function canonicalizeDimension(token) {
+    const match = /^([+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?)([a-z%]*)$/i.exec(token);
+    if (!match)
+        return token.toLowerCase();
+    const magnitude = Number.parseFloat(match[1]);
+    const unit = match[2].toLowerCase();
+    if (!Number.isFinite(magnitude))
+        return token.toLowerCase();
+    // A zero length is unitless per spec, and `0`, `0px`, `0em` are the same
+    // declaration written three ways.
+    if (magnitude === 0 && (unit === '' || unit in ABSOLUTE_LENGTHS || isRelativeUnit(unit))) {
+        return '0';
+    }
+    const lengthFactor = ABSOLUTE_LENGTHS[unit];
+    if (lengthFactor !== undefined)
+        return `${round(magnitude * lengthFactor)}px`;
+    const angleFactor = ANGLES[unit];
+    if (angleFactor !== undefined)
+        return `${round(magnitude * angleFactor)}deg`;
+    return `${round(magnitude)}${unit}`;
+}
+export function isRelativeUnit(unit) {
+    return RELATIVE_UNITS.includes(unit.toLowerCase());
+}
+function round(value) {
+    const factor = 10 ** LENGTH_PRECISION;
+    const rounded = Math.round(value * factor) / factor;
+    return Object.is(rounded, -0) ? 0 : rounded;
+}
+function closingQuote(input, start) {
+    const quote = input[start];
+    for (let i = start + 1; i < input.length; i += 1) {
+        if (input[i] === '\\') {
+            i += 1;
+            continue;
+        }
+        if (input[i] === quote)
+            return i;
+    }
+    return input.length - 1;
+}
+function matchingParen(input, openIndex) {
+    let depth = 0;
+    for (let i = openIndex; i < input.length; i += 1) {
+        if (input[i] === '(')
+            depth += 1;
+        else if (input[i] === ')') {
+            depth -= 1;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return input.length - 1;
+}
+//# sourceMappingURL=value.js.map

package/dist/rules/normalize/value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"value.js","sourceRoot":"","sources":["../../../src/rules/normalize/value.ts"],"names":[],"mappings":"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","sourcesContent":["import { canonicalizeColor, isColorProperty } from './color.js';\n\n/**\n * Declaration-value canonicalization.\n *\n * Every value entering a snapshot passes through here. The job is to erase every\n * way CSS lets an author write the same thing differently — spacing, casing,\n * absolute unit choice, float formatting — so that reformatting a stylesheet is\n * not a mass-invalidation event.\n *\n * The discipline is one-directional: collapse only differences that provably\n * cannot reach a pixel. Anything that *might* render differently is left alone,\n * because an over-eager equivalence here produces a false `unchanged`, and the\n * cost of the opposite mistake is only a review that did not need to happen.\n */\n\n/** Absolute lengths, in CSS px. Fixed by spec, so conversion is lossless. */\nconst ABSOLUTE_LENGTHS: Readonly<Record<string, number>> = {\n  px: 1,\n  pt: 96 / 72,\n  pc: 16,\n  in: 96,\n  cm: 96 / 2.54,\n  mm: 96 / 25.4,\n  q: 96 / 101.6,\n};\n\n/** Angles, in degrees. */\nconst ANGLES: Readonly<Record<string, number>> = {\n  deg: 1,\n  grad: 0.9,\n  rad: 180 / Math.PI,\n  turn: 360,\n};\n\n/**\n * Units left symbolic because they cannot be resolved without a layout engine.\n *\n * This is the `declared-only` boundary made concrete (ADR-0002): under a profile\n * without computed style, `padding: 1rem` stays `1rem`. That is honest — it is\n * genuinely all that tier knows — and it is why JSDOM decides the token band\n * `declared-only` rather than `full`. Resolving these by assuming a root font\n * size would fabricate precision the tier does not have.\n */\nexport const RELATIVE_UNITS: readonly string[] = [\n  'em', 'rem', 'ex', 'ch', 'cap', 'ic', 'lh', 'rlh',\n  'vw', 'vh', 'vmin', 'vmax', 'vi', 'vb',\n  'svw', 'svh', 'lvw', 'lvh', 'dvw', 'dvh', '%',\n];\n\n/** Decimal places kept for a length. Absorbs float noise, keeps sub-pixel intent. */\nconst LENGTH_PRECISION = 4;\n\nexport function canonicalizeValue(property: string, value: string): string {\n  if (isColorProperty(property)) return canonicalizeColor(value);\n  return canonicalizeTokens(value);\n}\n\n/**\n * Rewrite a value token by token.\n *\n * Quoted strings and `url()` payloads are passed through untouched: a font\n * family name and a resource path are opaque data, and normalizing their case\n * would change what they refer to.\n */\nexport function canonicalizeTokens(value: string): string {\n  const out: string[] = [];\n  let index = 0;\n  const input = value.trim();\n\n  while (index < input.length) {\n    const char = input[index]!;\n\n    if (/\\s/.test(char)) {\n      if (out.length > 0 && out[out.length - 1] !== ' ') out.push(' ');\n      index += 1;\n      continue;\n    }\n\n    if (char === '\"' || char === \"'\") {\n      const end = closingQuote(input, index);\n      out.push(input.slice(index, end + 1));\n      index = end + 1;\n      continue;\n    }\n\n    if (input.slice(index).toLowerCase().startsWith('url(')) {\n      const end = matchingParen(input, index + 3);\n      out.push(`url${input.slice(index + 3, end + 1)}`);\n      index = end + 1;\n      continue;\n    }\n\n    const numeric = /^[+-]?(\\d+\\.?\\d*|\\.\\d+)(e[+-]?\\d+)?([a-z%]*)/i.exec(input.slice(index));\n    if (numeric && numeric[0].length > 0) {\n      out.push(canonicalizeDimension(numeric[0]));\n      index += numeric[0].length;\n      continue;\n    }\n\n    const identifier = /^[a-z_-][\\w-]*/i.exec(input.slice(index));\n    if (identifier) {\n      // Unquoted identifiers are CSS keywords and function names, both\n      // case-insensitive to the parser and therefore safe to fold.\n      out.push(identifier[0].toLowerCase());\n      index += identifier[0].length;\n      continue;\n    }\n\n    // Punctuation: `,` `(` `)` `/` `*`. Drop whitespace before a comma so\n    // `a , b` and `a, b` converge.\n    if (char === ',' && out[out.length - 1] === ' ') out.pop();\n    out.push(char);\n    index += 1;\n  }\n\n  return out.join('').trim();\n}\n\n/** Canonicalize one `<number><unit>` token. */\nexport function canonicalizeDimension(token: string): string {\n  const match = /^([+-]?(?:\\d+\\.?\\d*|\\.\\d+)(?:e[+-]?\\d+)?)([a-z%]*)$/i.exec(token);\n  if (!match) return token.toLowerCase();\n\n  const magnitude = Number.parseFloat(match[1]!);\n  const unit = match[2]!.toLowerCase();\n\n  if (!Number.isFinite(magnitude)) return token.toLowerCase();\n\n  // A zero length is unitless per spec, and `0`, `0px`, `0em` are the same\n  // declaration written three ways.\n  if (magnitude === 0 && (unit === '' || unit in ABSOLUTE_LENGTHS || isRelativeUnit(unit))) {\n    return '0';\n  }\n\n  const lengthFactor = ABSOLUTE_LENGTHS[unit];\n  if (lengthFactor !== undefined) return `${round(magnitude * lengthFactor)}px`;\n\n  const angleFactor = ANGLES[unit];\n  if (angleFactor !== undefined) return `${round(magnitude * angleFactor)}deg`;\n\n  return `${round(magnitude)}${unit}`;\n}\n\nexport function isRelativeUnit(unit: string): boolean {\n  return RELATIVE_UNITS.includes(unit.toLowerCase());\n}\n\nfunction round(value: number): number {\n  const factor = 10 ** LENGTH_PRECISION;\n  const rounded = Math.round(value * factor) / factor;\n  return Object.is(rounded, -0) ? 0 : rounded;\n}\n\nfunction closingQuote(input: string, start: number): number {\n  const quote = input[start];\n  for (let i = start + 1; i < input.length; i += 1) {\n    if (input[i] === '\\\\') {\n      i += 1;\n      continue;\n    }\n    if (input[i] === quote) return i;\n  }\n  return input.length - 1;\n}\n\nfunction matchingParen(input: string, openIndex: number): number {\n  let depth = 0;\n  for (let i = openIndex; i < input.length; i += 1) {\n    if (input[i] === '(') depth += 1;\n    else if (input[i] === ')') {\n      depth -= 1;\n      if (depth === 0) return i;\n    }\n  }\n  return input.length - 1;\n}\n"]}

package/dist/rules/normalize/wrapper.d.ts

@@ -0,0 +1,16 @@
+import type { RawNode } from '../../format/capture.js';
+import type { SemanticNode } from '../../format/snapshot.js';
+/**
+ * Whether a node exists only to hold its children.
+ *
+ * Conservative on purpose: this is the one normalization rule that *removes* a
+ * node, so a wrong answer here deletes evidence. Anything carrying a role, a
+ * name, an id, an admitted attribute, text, or a non-inherited style declaration
+ * is kept, whatever it looks like.
+ *
+ * Inherited properties are excluded from the test because a wrapper inheriting
+ * `color` from above passes that same value to its children either way — its
+ * presence changes nothing that renders.
+ */
+export declare function isInertWrapper(raw: RawNode, node: SemanticNode, declaredBy: WeakMap<SemanticNode, ReadonlySet<string>>): boolean;
+//# sourceMappingURL=wrapper.d.ts.map

package/dist/rules/normalize/wrapper.js

@@ -0,0 +1,137 @@
+/**
+ * Whether a node exists only to hold its children.
+ *
+ * Conservative on purpose: this is the one normalization rule that *removes* a
+ * node, so a wrong answer here deletes evidence. Anything carrying a role, a
+ * name, an id, an admitted attribute, text, or a non-inherited style declaration
+ * is kept, whatever it looks like.
+ *
+ * Inherited properties are excluded from the test because a wrapper inheriting
+ * `color` from above passes that same value to its children either way — its
+ * presence changes nothing that renders.
+ */
+export function isInertWrapper(raw, node, declaredBy) {
+    if (node.tag !== 'div' && node.tag !== 'span')
+        return false;
+    if (node.role !== undefined || node.name !== undefined || node.state !== undefined)
+        return false;
+    if (node.alias !== undefined || node.text !== undefined)
+        return false;
+    if (Object.keys(node.attributes).length > 0)
+        return false;
+    if (raw.shadowChildren !== undefined && raw.shadowChildren.length > 0)
+        return false;
+    // A wrapper the operator excluded is never inert, whatever it declares.
+    //
+    // The mark is not an attribute — `data-variance-ignore` is deliberately outside
+    // the allowlist so that adding it re-baselines nothing — so the check above
+    // cannot see it, and a bare marked `<div>` is exactly the shape this function
+    // deletes. Collapsing it drops the mark with it, `sitesIn` finds no site, and
+    // the exclusion silently evaporates: the operator reads their config, sees the
+    // rule, and the run compares the region anyway. An ignore that stops working
+    // without saying so is the same failure as one that absorbs too much, pointed
+    // the other way.
+    if (node.ignoredBy !== undefined && node.ignoredBy.length > 0)
+        return false;
+    // A wrapper that roots a component boundary is never inert either, and for the
+    // same reason one sentence up: the collapse would take the holding with it, and
+    // `function Summary() { return <span>{total}</span> }` is not an exotic shape —
+    // it is most of a component library. Losing the boundary there loses the only
+    // record of what that component was handed and what it retained, which is the
+    // evidence `compare/parting.ts` traces a difference back through.
+    //
+    // The cost is stated rather than hidden: a run that reads holdings keeps
+    // wrappers a run without them collapses, so the two produce different
+    // `structureHash`es for one page. That is why holding is opted into per run
+    // rather than defaulted on, and why both sides of a comparison must be read
+    // the same way — the same bargain `ignoredBy` makes above.
+    //
+    // FIXME: `wiring` is destroyed by this collapse and is not checked here. It is
+    // hashed into a band, so adding it would move an existing baseline for anyone
+    // already reading wiring, which is a change that needs its own changeset.
+    if (node.holding !== undefined)
+        return false;
+    const declaredHere = declaredBy.get(node) ?? EMPTY_PROPERTIES;
+    for (const [property, value] of Object.entries(node.style)) {
+        // Only what the wrapper *declared* is evidence about the wrapper.
+        //
+        // An inherited value passes through unchanged — the children receive it
+        // whether or not the wrapper is there. An engine-computed value is worse
+        // than uninformative: under a profile with computed style every one of the
+        // ~200 allowlisted properties arrives with a resolved value, including used
+        // values like `width: 1264px` that describe the *parent's* layout rather
+        // than anything the wrapper did. Testing those against an initial-value
+        // table meant `isInertDeclaration` returned false on the first unrecognized
+        // one and no wrapper anywhere collapsed under `chromium` — the same rule
+        // disabled by a different accident under `jsdom` in journal 0005, and
+        // invisible until the two profiles were scored against each other (P4).
+        //
+        // Conservatism is kept where it is evidence: an unrecognized property the
+        // wrapper *declared* still blocks the collapse.
+        if (!declaredHere.has(property))
+            continue;
+        if (!isInertDeclaration(property, value))
+            return false;
+    }
+    return true;
+}
+const EMPTY_PROPERTIES = new Set();
+/**
+ * Initial values for the properties a bare `div`/`span` legitimately carries.
+ *
+ * Needed because a profile with computed style reports *every* property, initial
+ * ones included — so "declares no styling" cannot be tested by an empty map.
+ */
+const INERT_VALUES = {
+    // `contents` generates no box at all, so a wrapper carrying it is inert by
+    // definition: its children already participate in the parent's layout.
+    display: ['block', 'inline', 'contents'],
+    position: ['static'],
+    'box-sizing': ['content-box', 'border-box'],
+    'overflow-x': ['visible'],
+    'overflow-y': ['visible'],
+    opacity: ['1'],
+    visibility: ['visible'],
+    transform: ['none'],
+    filter: ['none'],
+    'backdrop-filter': ['none'],
+    'mix-blend-mode': ['normal'],
+    'background-color': ['rgb(0 0 0 / 0)'],
+    'background-image': ['none'],
+    'z-index': ['auto'],
+    float: ['none'],
+    clear: ['none'],
+    width: ['auto'],
+    height: ['auto'],
+    'min-width': ['0', 'auto'],
+    'min-height': ['0', 'auto'],
+    'max-width': ['none'],
+    'max-height': ['none'],
+    'aspect-ratio': ['auto'],
+    'content-visibility': ['visible'],
+    'object-fit': ['fill'],
+    'table-layout': ['auto'],
+};
+const ZERO_PREFIXED = ['margin-', 'padding-', 'border-', 'outline-', 'inset', 'top', 'right', 'bottom', 'left'];
+function isInertDeclaration(property, value) {
+    const allowed = INERT_VALUES[property];
+    if (allowed)
+        return allowed.includes(value);
+    if (property.startsWith('border-') && property.endsWith('-style'))
+        return value === 'none';
+    if (property.startsWith('border-') && property.endsWith('-color'))
+        return true;
+    if (property === 'outline-style')
+        return value === 'none';
+    if (property === 'outline-color')
+        return true;
+    if (property === 'box-shadow' || property === 'text-shadow')
+        return value === 'none';
+    if (ZERO_PREFIXED.some((prefix) => property.startsWith(prefix))) {
+        return value === '0' || value === 'auto';
+    }
+    // An unrecognized property on a wrapper is a reason to keep it. Silence is
+    // not evidence of inertness.
+    return false;
+}
+//# sourceMappingURL=wrapper.js.map

package/dist/rules/normalize/wrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrapper.js","sourceRoot":"","sources":["../../../src/rules/normalize/wrapper.ts"],"names":[],"mappings":"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","sourcesContent":["import type { RawNode } from '../../format/capture.js';\nimport type { SemanticNode } from '../../format/snapshot.js';\n\n/**\n * Whether a node exists only to hold its children.\n *\n * Conservative on purpose: this is the one normalization rule that *removes* a\n * node, so a wrong answer here deletes evidence. Anything carrying a role, a\n * name, an id, an admitted attribute, text, or a non-inherited style declaration\n * is kept, whatever it looks like.\n *\n * Inherited properties are excluded from the test because a wrapper inheriting\n * `color` from above passes that same value to its children either way — its\n * presence changes nothing that renders.\n */\nexport function isInertWrapper(\n  raw: RawNode,\n  node: SemanticNode,\n  declaredBy: WeakMap<SemanticNode, ReadonlySet<string>>,\n): boolean {\n  if (node.tag !== 'div' && node.tag !== 'span') return false;\n  if (node.role !== undefined || node.name !== undefined || node.state !== undefined) return false;\n  if (node.alias !== undefined || node.text !== undefined) return false;\n  if (Object.keys(node.attributes).length > 0) return false;\n  if (raw.shadowChildren !== undefined && raw.shadowChildren.length > 0) return false;\n\n  // A wrapper the operator excluded is never inert, whatever it declares.\n  //\n  // The mark is not an attribute — `data-variance-ignore` is deliberately outside\n  // the allowlist so that adding it re-baselines nothing — so the check above\n  // cannot see it, and a bare marked `<div>` is exactly the shape this function\n  // deletes. Collapsing it drops the mark with it, `sitesIn` finds no site, and\n  // the exclusion silently evaporates: the operator reads their config, sees the\n  // rule, and the run compares the region anyway. An ignore that stops working\n  // without saying so is the same failure as one that absorbs too much, pointed\n  // the other way.\n  if (node.ignoredBy !== undefined && node.ignoredBy.length > 0) return false;\n\n  // A wrapper that roots a component boundary is never inert either, and for the\n  // same reason one sentence up: the collapse would take the holding with it, and\n  // `function Summary() { return <span>{total}</span> }` is not an exotic shape —\n  // it is most of a component library. Losing the boundary there loses the only\n  // record of what that component was handed and what it retained, which is the\n  // evidence `compare/parting.ts` traces a difference back through.\n  //\n  // The cost is stated rather than hidden: a run that reads holdings keeps\n  // wrappers a run without them collapses, so the two produce different\n  // `structureHash`es for one page. That is why holding is opted into per run\n  // rather than defaulted on, and why both sides of a comparison must be read\n  // the same way — the same bargain `ignoredBy` makes above.\n  //\n  // FIXME: `wiring` is destroyed by this collapse and is not checked here. It is\n  // hashed into a band, so adding it would move an existing baseline for anyone\n  // already reading wiring, which is a change that needs its own changeset.\n  if (node.holding !== undefined) return false;\n\n  const declaredHere = declaredBy.get(node) ?? EMPTY_PROPERTIES;\n\n  for (const [property, value] of Object.entries(node.style)) {\n    // Only what the wrapper *declared* is evidence about the wrapper.\n    //\n    // An inherited value passes through unchanged — the children receive it\n    // whether or not the wrapper is there. An engine-computed value is worse\n    // than uninformative: under a profile with computed style every one of the\n    // ~200 allowlisted properties arrives with a resolved value, including used\n    // values like `width: 1264px` that describe the *parent's* layout rather\n    // than anything the wrapper did. Testing those against an initial-value\n    // table meant `isInertDeclaration` returned false on the first unrecognized\n    // one and no wrapper anywhere collapsed under `chromium` — the same rule\n    // disabled by a different accident under `jsdom` in journal 0005, and\n    // invisible until the two profiles were scored against each other (P4).\n    //\n    // Conservatism is kept where it is evidence: an unrecognized property the\n    // wrapper *declared* still blocks the collapse.\n    if (!declaredHere.has(property)) continue;\n    if (!isInertDeclaration(property, value)) return false;\n  }\n\n  return true;\n}\n\nconst EMPTY_PROPERTIES: ReadonlySet<string> = new Set();\n\n/**\n * Initial values for the properties a bare `div`/`span` legitimately carries.\n *\n * Needed because a profile with computed style reports *every* property, initial\n * ones included — so \"declares no styling\" cannot be tested by an empty map.\n */\nconst INERT_VALUES: Readonly<Record<string, readonly string[]>> = {\n  // `contents` generates no box at all, so a wrapper carrying it is inert by\n  // definition: its children already participate in the parent's layout.\n  display: ['block', 'inline', 'contents'],\n  position: ['static'],\n  'box-sizing': ['content-box', 'border-box'],\n  'overflow-x': ['visible'],\n  'overflow-y': ['visible'],\n  opacity: ['1'],\n  visibility: ['visible'],\n  transform: ['none'],\n  filter: ['none'],\n  'backdrop-filter': ['none'],\n  'mix-blend-mode': ['normal'],\n  'background-color': ['rgb(0 0 0 / 0)'],\n  'background-image': ['none'],\n  'z-index': ['auto'],\n  float: ['none'],\n  clear: ['none'],\n  width: ['auto'],\n  height: ['auto'],\n  'min-width': ['0', 'auto'],\n  'min-height': ['0', 'auto'],\n  'max-width': ['none'],\n  'max-height': ['none'],\n  'aspect-ratio': ['auto'],\n  'content-visibility': ['visible'],\n  'object-fit': ['fill'],\n  'table-layout': ['auto'],\n};\n\nconst ZERO_PREFIXED = ['margin-', 'padding-', 'border-', 'outline-', 'inset', 'top', 'right', 'bottom', 'left'];\n\nfunction isInertDeclaration(property: string, value: string): boolean {\n  const allowed = INERT_VALUES[property];\n  if (allowed) return allowed.includes(value);\n\n  if (property.startsWith('border-') && property.endsWith('-style')) return value === 'none';\n  if (property.startsWith('border-') && property.endsWith('-color')) return true;\n  if (property === 'outline-style') return value === 'none';\n  if (property === 'outline-color') return true;\n  if (property === 'box-shadow' || property === 'text-shadow') return value === 'none';\n\n  if (ZERO_PREFIXED.some((prefix) => property.startsWith(prefix))) {\n    return value === '0' || value === 'auto';\n  }\n\n  // An unrecognized property on a wrapper is a reason to keep it. Silence is\n  // not evidence of inertness.\n  return false;\n}\n"]}

package/dist/rules/ruleset.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The normalization ruleset and computed-style allowlist.
+ *
+ * Both versions are components of the environment key, so **changing anything in
+ * this file invalidates every baseline in every repository using it** (spec §7.3).
+ * That is correct and intended — a rule change is a render-input change — but it
+ * means edits here are releases, not tweaks. Bump the version in the same commit.
+ */
+/** Bump on any change to normalization behavior. */
+export declare const RULESET_VERSION = "r1";
+/**
+ * Bump on any change to {@link STYLE_ALLOWLIST}.
+ *
+ * `a2` added `accent-color` and `-webkit-text-stroke-width`, both found by
+ * probing a real Chromium against the semantic snapshot: each moves hundreds of
+ * pixels and neither moved the render hash.
+ *
+ * `-webkit-text-stroke-color` was added alongside them and immediately removed.
+ * Its initial value is `currentcolor`, so it moves whenever `color` moves — which
+ * split a colour-token root in two, since the derived property resolves through
+ * no token and looked like an independent cause. Nothing measured it as a gap;
+ * it was added on the assumption that its sibling implied it. Properties whose
+ * computed value derives from another property need the derivation modelled
+ * before they can be admitted.
+ */
+export declare const ALLOWLIST_VERSION = "a2";
+/**
+ * Properties that enter a snapshot.
+ *
+ * The allowlist is the direct lever on the product's central tradeoff (spec
+ * §11.3): too narrow and real regressions pass unseen; too wide and every
+ * snapshot churns, reintroducing the fatigue that makes teams stop reading
+ * diffs. So the admission test is deliberately strict —
+ *
+ * > Can a change to this property alone alter what a user sees or how assistive
+ * > technology reports the page?
+ *
+ * Only longhands appear. Shorthands are expanded before matching, because
+ * `margin: 4px` and `margin-top: 4px; …` must produce identical snapshots or
+ * refactoring a stylesheet becomes a mass-invalidation event.
+ *
+ * Notable exclusions, each for a reason:
+ * - `transition-*` / `animation-*` — snapshots are taken at a declared settle
+ *   point with animation disabled, so these describe a journey the snapshot does
+ *   not contain. Including them would make every easing tweak a diff.
+ * - `cursor`, `user-select`, `will-change`, `contain` — invisible in both raster
+ *   and the accessibility tree at rest.
+ * - `content` — resolved pseudo-element text is captured as text, not as a
+ *   declaration, so that it diffs like the content it is.
+ */
+export declare const STYLE_ALLOWLIST: readonly string[];
+export declare function isAllowedProperty(property: string): boolean;
+/**
+ * Custom properties are always admitted, whatever their name.
+ *
+ * They cannot be enumerated in advance — every project invents its own — and they
+ * are the mechanism design tokens travel through, which makes them the highest-
+ * value signal the system collects: a custom property resolves a *name* alongside
+ * a value, and that name is what lets one token edit collapse into one docket
+ * root with counted collateral rather than hundreds of separate colour diffs.
+ */
+export declare function isCustomProperty(property: string): boolean;
+/** Whether a property survives the allowlist projection (ADR-0003 step 4). */
+export declare function admits(property: string): boolean;
+/**
+ * Attributes kept on a semantic node.
+ *
+ * An allowlist rather than a denylist. Frameworks emit an open-ended supply of
+ * bookkeeping attributes — `data-reactroot`, `data-styled`, `data-testid`,
+ * `data-v-7f3a`, Storybook's own markers — and a denylist would need a new entry
+ * for each one, silently churning baselines until someone noticed. Anything not
+ * named here is dropped.
+ *
+ * `class` is absent by design (ADR-0003): a class name records *how* a style was
+ * applied, and the snapshot already records *what* was applied, resolved.
+ * `id` is absent because it has been replaced by a structural alias.
+ * `aria-*` is absent because those are resolved into `role`/`name`/`state`,
+ * which is what actually reaches a user.
+ */
+export declare const ATTRIBUTE_ALLOWLIST: readonly string[];
+export declare function admitsAttribute(name: string): boolean;
+/**
+ * Attributes whose values are id references, rewritten to structural aliases.
+ *
+ * Aliasing rather than masking is what preserves the *relationship* while
+ * deleting the volatile *value* (ADR-0003): a `useId` renumbering becomes a
+ * no-op, while breaking a `label ↔ input` association stays a real structural
+ * change. Masking both to a constant cannot tell those apart.
+ */
+export declare const ID_REFERENCE_ATTRIBUTES: readonly string[];
+/** Attributes holding a *space-separated list* of id references, not just one. */
+export declare const ID_REFERENCE_LIST_ATTRIBUTES: readonly string[];
+//# sourceMappingURL=ruleset.d.ts.map

package/dist/rules/ruleset.js

@@ -0,0 +1,175 @@
+/**
+ * The normalization ruleset and computed-style allowlist.
+ *
+ * Both versions are components of the environment key, so **changing anything in
+ * this file invalidates every baseline in every repository using it** (spec §7.3).
+ * That is correct and intended — a rule change is a render-input change — but it
+ * means edits here are releases, not tweaks. Bump the version in the same commit.
+ */
+/** Bump on any change to normalization behavior. */
+export const RULESET_VERSION = 'r1';
+/**
+ * Bump on any change to {@link STYLE_ALLOWLIST}.
+ *
+ * `a2` added `accent-color` and `-webkit-text-stroke-width`, both found by
+ * probing a real Chromium against the semantic snapshot: each moves hundreds of
+ * pixels and neither moved the render hash.
+ *
+ * `-webkit-text-stroke-color` was added alongside them and immediately removed.
+ * Its initial value is `currentcolor`, so it moves whenever `color` moves — which
+ * split a colour-token root in two, since the derived property resolves through
+ * no token and looked like an independent cause. Nothing measured it as a gap;
+ * it was added on the assumption that its sibling implied it. Properties whose
+ * computed value derives from another property need the derivation modelled
+ * before they can be admitted.
+ */
+export const ALLOWLIST_VERSION = 'a2';
+/**
+ * Properties that enter a snapshot.
+ *
+ * The allowlist is the direct lever on the product's central tradeoff (spec
+ * §11.3): too narrow and real regressions pass unseen; too wide and every
+ * snapshot churns, reintroducing the fatigue that makes teams stop reading
+ * diffs. So the admission test is deliberately strict —
+ *
+ * > Can a change to this property alone alter what a user sees or how assistive
+ * > technology reports the page?
+ *
+ * Only longhands appear. Shorthands are expanded before matching, because
+ * `margin: 4px` and `margin-top: 4px; …` must produce identical snapshots or
+ * refactoring a stylesheet becomes a mass-invalidation event.
+ *
+ * Notable exclusions, each for a reason:
+ * - `transition-*` / `animation-*` — snapshots are taken at a declared settle
+ *   point with animation disabled, so these describe a journey the snapshot does
+ *   not contain. Including them would make every easing tweak a diff.
+ * - `cursor`, `user-select`, `will-change`, `contain` — invisible in both raster
+ *   and the accessibility tree at rest.
+ * - `content` — resolved pseudo-element text is captured as text, not as a
+ *   declaration, so that it diffs like the content it is.
+ */
+export const STYLE_ALLOWLIST = [
+    // Box model and formatting context
+    'display', 'position', 'top', 'right', 'bottom', 'left', 'float', 'clear',
+    'width', 'height', 'min-width', 'min-height', 'max-width', 'max-height',
+    'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
+    'padding-top', 'padding-right', 'padding-bottom', 'padding-left',
+    'box-sizing', 'overflow-x', 'overflow-y', 'z-index', 'aspect-ratio',
+    // Flex and grid
+    'flex-direction', 'flex-wrap', 'flex-grow', 'flex-shrink', 'flex-basis',
+    'justify-content', 'align-items', 'align-self', 'align-content', 'order',
+    'grid-template-columns', 'grid-template-rows', 'grid-template-areas',
+    'grid-auto-columns', 'grid-auto-rows', 'grid-auto-flow',
+    'grid-column-start', 'grid-column-end', 'grid-row-start', 'grid-row-end',
+    'row-gap', 'column-gap',
+    // Typography
+    'font-family', 'font-size', 'font-weight', 'font-style', 'font-variant',
+    'font-stretch', 'line-height', 'letter-spacing', 'word-spacing',
+    'text-align', 'text-indent', 'text-transform', 'text-overflow',
+    'text-decoration-line', 'text-decoration-color', 'text-decoration-style',
+    'text-decoration-thickness', 'white-space', 'word-break', 'overflow-wrap',
+    'vertical-align', 'writing-mode', 'direction',
+    // Paint
+    'color', 'opacity', 'background-color', 'background-image',
+    // Native-control painting. `accent-color` restyles checkboxes and radios,
+    // which is exactly the kind of property the rest of this list misses: it
+    // describes what the *engine* paints rather than what the author declares
+    // about a box. See the note below.
+    'accent-color', '-webkit-text-stroke-width',
+    'background-position', 'background-size', 'background-repeat',
+    'background-clip', 'background-origin',
+    'border-top-width', 'border-right-width', 'border-bottom-width', 'border-left-width',
+    'border-top-style', 'border-right-style', 'border-bottom-style', 'border-left-style',
+    'border-top-color', 'border-right-color', 'border-bottom-color', 'border-left-color',
+    'border-top-left-radius', 'border-top-right-radius',
+    'border-bottom-right-radius', 'border-bottom-left-radius',
+    'outline-width', 'outline-style', 'outline-color', 'outline-offset',
+    'box-shadow', 'text-shadow', 'filter', 'backdrop-filter', 'mix-blend-mode',
+    // Visibility and geometry transforms
+    'visibility', 'content-visibility', 'transform', 'transform-origin',
+    'object-fit', 'object-position',
+    // Tables
+    'table-layout', 'border-collapse', 'border-spacing', 'caption-side',
+];
+/**
+ * Known weakness, recorded because two additions do not fix it.
+ *
+ * The list above was assembled by asking what an author declares about a box,
+ * and it is good at that. It is poor at properties describing what the *engine*
+ * paints — native control appearance, text decoration painted outside the glyph
+ * box, platform accent colours. `accent-color` and `-webkit-text-stroke-width`
+ * were found in an afternoon of probing a real browser, which is weak evidence
+ * that they are the only two.
+ *
+ * The right response is a systematic audit against the CSS property index rather
+ * than more ad-hoc additions, and until that happens this list should be assumed
+ * to have holes of this shape. A missing property is a false `unchanged`, so the
+ * gap is in the direction that matters.
+ */
+const ALLOWED = new Set(STYLE_ALLOWLIST);
+export function isAllowedProperty(property) {
+    return ALLOWED.has(property);
+}
+/**
+ * Custom properties are always admitted, whatever their name.
+ *
+ * They cannot be enumerated in advance — every project invents its own — and they
+ * are the mechanism design tokens travel through, which makes them the highest-
+ * value signal the system collects: a custom property resolves a *name* alongside
+ * a value, and that name is what lets one token edit collapse into one docket
+ * root with counted collateral rather than hundreds of separate colour diffs.
+ */
+export function isCustomProperty(property) {
+    return property.startsWith('--');
+}
+/** Whether a property survives the allowlist projection (ADR-0003 step 4). */
+export function admits(property) {
+    return isCustomProperty(property) || isAllowedProperty(property);
+}
+/**
+ * Attributes kept on a semantic node.
+ *
+ * An allowlist rather than a denylist. Frameworks emit an open-ended supply of
+ * bookkeeping attributes — `data-reactroot`, `data-styled`, `data-testid`,
+ * `data-v-7f3a`, Storybook's own markers — and a denylist would need a new entry
+ * for each one, silently churning baselines until someone noticed. Anything not
+ * named here is dropped.
+ *
+ * `class` is absent by design (ADR-0003): a class name records *how* a style was
+ * applied, and the snapshot already records *what* was applied, resolved.
+ * `id` is absent because it has been replaced by a structural alias.
+ * `aria-*` is absent because those are resolved into `role`/`name`/`state`,
+ * which is what actually reaches a user.
+ */
+export const ATTRIBUTE_ALLOWLIST = [
+    'type', 'value', 'checked', 'disabled', 'readonly', 'required', 'multiple',
+    'placeholder', 'name', 'href', 'target', 'rel', 'src', 'alt', 'title',
+    'for', 'form', 'list', 'headers', 'colspan', 'rowspan', 'scope',
+    'lang', 'dir', 'hidden', 'open', 'selected', 'download',
+    'min', 'max', 'step', 'pattern', 'maxlength', 'minlength', 'autocomplete',
+    'role', 'tabindex', 'draggable', 'contenteditable',
+    'width', 'height', 'loading', 'decoding', 'srcset', 'sizes', 'poster', 'controls',
+];
+const ATTRIBUTES = new Set(ATTRIBUTE_ALLOWLIST);
+export function admitsAttribute(name) {
+    return ATTRIBUTES.has(name);
+}
+/**
+ * Attributes whose values are id references, rewritten to structural aliases.
+ *
+ * Aliasing rather than masking is what preserves the *relationship* while
+ * deleting the volatile *value* (ADR-0003): a `useId` renumbering becomes a
+ * no-op, while breaking a `label ↔ input` association stays a real structural
+ * change. Masking both to a constant cannot tell those apart.
+ */
+export const ID_REFERENCE_ATTRIBUTES = [
+    'id', 'for', 'form', 'list', 'headers',
+    'aria-labelledby', 'aria-describedby', 'aria-controls', 'aria-owns',
+    'aria-activedescendant', 'aria-details', 'aria-errormessage', 'aria-flowto',
+];
+/** Attributes holding a *space-separated list* of id references, not just one. */
+export const ID_REFERENCE_LIST_ATTRIBUTES = [
+    'headers', 'aria-labelledby', 'aria-describedby', 'aria-controls',
+    'aria-owns', 'aria-flowto',
+];
+//# sourceMappingURL=ruleset.js.map