@variance-authority/core 0.1.0

package/dist/format/value.js

@@ -0,0 +1,182 @@
+import { canonicalize } from './canonical.js';
+import { digestCombine, digestString } from './hash.js';
+/**
+ * A value that was never rendered, as something a run can compare (spec 0031).
+ *
+ * The third material. It carries **text**, not a parse tree, for the reason the
+ * raster arm carries bytes: every reader that understands a dialect is somebody
+ * else's dependency, `core` carries none, and a stored parse is a parse that
+ * reader's next version disagrees with. The text is what the digest was taken
+ * over, what a baseline holds, and what a person reads in a pull request.
+ *
+ * The canonical form is `canonicalize`, unchanged and unwrapped — sorted keys,
+ * portable number formatting, `undefined` omitted rather than nulled, and a
+ * refusal on a non-finite number. What this module adds is the *shaping* that
+ * has to happen before it, because two of the three rules below decide whether
+ * the comparison downstream is readable or useless.
+ */
+/**
+ * The version of the shaping rules, and part of every value digest.
+ *
+ * Bumping it invalidates stored value baselines deliberately: a text produced
+ * under different rules is not the same reading of the same subject, and a
+ * digest that could not tell the difference would report a rule change as a
+ * subject that did not move.
+ */
+export const VALUE_RECIPE = 'value/1';
+/** What a dropped value becomes. Present in the text, never compared. */
+export const DROPPED = '[dropped]';
+/**
+ * Shape a value, canonicalize it, and address it by content.
+ *
+ * Throws on anything that cannot be a value rather than encoding it: a function,
+ * a `Date`, a `bigint`, a non-finite number. Each refusal names the JSON Pointer
+ * where it was found, because the alternative — `JSON.stringify`'s — is to drop
+ * a function silently, which reads downstream as a key that was removed.
+ */
+export function shapeValue(value, options = {}) {
+    const shaped = shapeNode(value, '', options);
+    const text = canonicalize(shaped);
+    const keyed = Object.keys(options.arrayKey ?? {})
+        .map((pointer) => pointerShape(pointer))
+        .sort();
+    return {
+        dialect: options.dialect ?? 'json',
+        text,
+        digest: digestCombine('value/v1', [digestString(text), digestString(VALUE_RECIPE)]),
+        recipe: VALUE_RECIPE,
+        ...(keyed.length === 0 ? {} : { keyed }),
+        ...(options.generator === undefined ? {} : { generator: options.generator }),
+    };
+}
+/** RFC 6901: `~` becomes `~0` and `/` becomes `~1`, in that order. */
+export function pointerToken(token) {
+    return token.replace(/~/g, '~0').replace(/\//g, '~1');
+}
+/**
+ * The pointer with every row identity replaced by `-`.
+ *
+ * Two things: it is what a wildcard rule is matched against, and it is what a
+ * change's fingerprint is taken over — so the same kind of edit at row 4 and at
+ * row 900 is one shape happening twice rather than two findings.
+ *
+ * An index is a row identity by spelling. A **keyed** array's members are named
+ * instead, and no spelling can distinguish those from an ordinary object's keys —
+ * so `keyed` is passed in from the capture that declared it, and only the segment
+ * immediately below a keyed array is wildcarded.
+ */
+export function pointerShape(pointer, keyed = []) {
+    const shaped = pointer.replace(/\/\d+(?=\/|$)/g, '/-');
+    return keyed.reduce((current, array) => {
+        if (!current.startsWith(`${array}/`))
+            return current;
+        const rest = current.slice(array.length + 1);
+        const cut = rest.indexOf('/');
+        return cut === -1 ? `${array}/-` : `${array}/-${rest.slice(cut)}`;
+    }, shaped);
+}
+function matches(rules, pointer) {
+    return rules.includes(pointer) || rules.includes(pointerShape(pointer));
+}
+function ruleFor(rules, pointer) {
+    if (rules === undefined)
+        return undefined;
+    return rules[pointer] ?? rules[pointerShape(pointer)];
+}
+function shapeNode(value, pointer, options) {
+    if (matches(options.drop ?? [], pointer))
+        return DROPPED;
+    const replaced = ruleFor(options.replace, pointer);
+    if (replaced !== undefined)
+        return replaced;
+    if (value === null)
+        return null;
+    switch (typeof value) {
+        case 'string':
+        case 'boolean':
+            return value;
+        case 'number':
+            if (!Number.isFinite(value)) {
+                throw new RangeError(`${describe(pointer)} is ${String(value)}, which no digest may encode: a non-finite ` +
+                    'number means the thing that produced it failed, and hashing it would give a broken ' +
+                    'reading a stable identity');
+            }
+            return value;
+        case 'object':
+            break;
+        default:
+            throw new TypeError(`${describe(pointer)} is a ${typeof value}, which is not a value. ` +
+                'Serializing it would drop it silently, and a key that vanished from the text is ' +
+                'read downstream as a key that was removed.');
+    }
+    if (Array.isArray(value))
+        return shapeArray(value, pointer, options);
+    if (opaque(value)) {
+        throw new TypeError(`${describe(pointer)} is a ${nameOf(value)}, which is not a value. Its state is not in ` +
+            'its own enumerable keys, so it would serialize to `{}` and two different ones would ' +
+            'compare as unchanged. Convert it where it is produced — an ISO string, a number, a ' +
+            'plain object — so the text says what was compared.');
+    }
+    const shaped = {};
+    for (const [key, member] of Object.entries(value)) {
+        if (member === undefined)
+            continue;
+        shaped[key] = shapeNode(member, `${pointer}/${pointerToken(key)}`, options);
+    }
+    return shaped;
+}
+/**
+ * Whether an object keeps its state somewhere `Object.entries` cannot reach.
+ *
+ * A `Date`, a `Map`, a `Set`, a `URL`, a `RegExp` — each has no own enumerable
+ * key, so the object branch below produces `{}` for every one of them. That is
+ * the exact harm the function and bigint refusals exist to prevent, arriving
+ * through the one `typeof` that does not name it: a timestamp that moved a year
+ * and a timestamp that did not both address to the digest of `{}`, and the run
+ * that compares them reports unchanged.
+ *
+ * Emptiness alone is not the test — `{}` is a value, and an adopter may legitimately
+ * snapshot one. The test is emptiness in something that is not a plain object,
+ * which is what says the state went somewhere else. An instance carrying its own
+ * fields serializes those fields and is left alone, exactly as `JSON.stringify`
+ * would leave it.
+ */
+function opaque(value) {
+    if (Object.keys(value).length > 0)
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype !== Object.prototype && prototype !== null;
+}
+/** What to call the thing in the refusal, so the message names the type at hand. */
+function nameOf(value) {
+    const named = value.constructor?.name;
+    return typeof named === 'string' && named.length > 0 ? named : 'object';
+}
+function shapeArray(items, pointer, options) {
+    const key = ruleFor(options.arrayKey, pointer);
+    if (key === undefined) {
+        return items.map((item, index) => shapeNode(item, `${pointer}/${index}`, options));
+    }
+    const keyed = {};
+    items.forEach((item, index) => {
+        const at = `${pointer}/${index}`;
+        if (typeof item !== 'object' || item === null || Array.isArray(item)) {
+            throw new TypeError(`${describe(at)} is keyed by \`${key}\` and is not a record`);
+        }
+        const member = item[key];
+        if (typeof member !== 'string' && typeof member !== 'number') {
+            throw new TypeError(`${describe(at)} has no \`${key}\` to be identified by`);
+        }
+        const identity = String(member);
+        if (identity in keyed) {
+            throw new Error(`${describe(pointer)} has two rows with \`${key}\` of ${identity}. A key that does not ` +
+                'identify a row would silently take the later one, making the earlier row invisible.');
+        }
+        keyed[identity] = shapeNode(item, `${pointer}/${pointerToken(identity)}`, options);
+    });
+    return keyed;
+}
+function describe(pointer) {
+    return pointer === '' ? 'the value' : `the value at ${pointer}`;
+}
+//# sourceMappingURL=value.js.map

package/dist/format/value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"value.js","sourceRoot":"","sources":["../../src/format/value.ts"],"names":[],"mappings":"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","sourcesContent":["import { canonicalize, type CanonicalValue } from './canonical.js';\nimport { digestCombine, digestString, type Digest } from './hash.js';\n\n/**\n * A value that was never rendered, as something a run can compare (spec 0031).\n *\n * The third material. It carries **text**, not a parse tree, for the reason the\n * raster arm carries bytes: every reader that understands a dialect is somebody\n * else's dependency, `core` carries none, and a stored parse is a parse that\n * reader's next version disagrees with. The text is what the digest was taken\n * over, what a baseline holds, and what a person reads in a pull request.\n *\n * The canonical form is `canonicalize`, unchanged and unwrapped — sorted keys,\n * portable number formatting, `undefined` omitted rather than nulled, and a\n * refusal on a non-finite number. What this module adds is the *shaping* that\n * has to happen before it, because two of the three rules below decide whether\n * the comparison downstream is readable or useless.\n */\n\n/**\n * The version of the shaping rules, and part of every value digest.\n *\n * Bumping it invalidates stored value baselines deliberately: a text produced\n * under different rules is not the same reading of the same subject, and a\n * digest that could not tell the difference would report a rule change as a\n * subject that did not move.\n */\nexport const VALUE_RECIPE = 'value/1';\n\n/** What a dropped value becomes. Present in the text, never compared. */\nexport const DROPPED = '[dropped]';\n\n/** What a value capture looks like once it has been shaped. */\nexport interface CapturedValue {\n  /** How to read the text: `json`, `openapi`, `graphql`, `route-table`. */\n  readonly dialect: string;\n\n  /** The canonical serialization — byte for byte what the digest was taken over. */\n  readonly text: string;\n\n  readonly digest: Digest;\n\n  /** The shaping rules this text was produced under. {@link VALUE_RECIPE}. */\n  readonly recipe: string;\n\n  /**\n   * The arrays this text was keyed by, as wildcarded pointers.\n   *\n   * A keyed array is an object whose members are named by a row's identity, so\n   * `/rows/checkout` is a *row* and `/rows/total` might not be. Carried because\n   * nothing downstream can tell those apart by looking, and a comparison that\n   * guessed would either group two unrelated members or fail to group the same\n   * edit made to two rows.\n   */\n  readonly keyed?: readonly string[];\n\n  /** What emitted it. The environment key for this material, when there is one. */\n  readonly generator?: { readonly name: string; readonly version: string };\n}\n\n/**\n * What to do to a value before it is canonicalized.\n *\n * Every key is a JSON Pointer (RFC 6901) into the value. A `-` token matches any\n * array index, so `/items/-/updatedAt` names that member of every item — the\n * concrete pointer and the wildcarded one are both offered to the rules, so a\n * literal `/items/0/updatedAt` still names exactly one.\n */\nexport interface ValueShaping {\n  /**\n   * Paths whose values are volatile.\n   *\n   * Recorded as {@link DROPPED} rather than removed, because *this key is here\n   * and I chose not to look at it* and *this key is gone* are different facts and\n   * a comparison must not collapse them.\n   */\n  readonly drop?: readonly string[];\n\n  /** Paths whose values become a stable token of the adopter's choosing. */\n  readonly replace?: Readonly<Record<string, string>>;\n\n  /**\n   * For an array of records, the member that identifies a row.\n   *\n   * Load-bearing, and not a convenience. An array compared by index reports a row\n   * inserted at the top of a two-thousand-row list as two thousand rows having\n   * changed — the same failure as forty red screenshots for one edit, in a medium\n   * where nobody can see it at a glance. Keyed, the array becomes an object, so\n   * order stops being a fact about it and an insertion is one addition.\n   */\n  readonly arrayKey?: Readonly<Record<string, string>>;\n}\n\nexport interface ShapeValueOptions extends ValueShaping {\n  /** Defaults to `json`. */\n  readonly dialect?: string;\n  readonly generator?: { readonly name: string; readonly version: string };\n}\n\n/**\n * Shape a value, canonicalize it, and address it by content.\n *\n * Throws on anything that cannot be a value rather than encoding it: a function,\n * a `Date`, a `bigint`, a non-finite number. Each refusal names the JSON Pointer\n * where it was found, because the alternative — `JSON.stringify`'s — is to drop\n * a function silently, which reads downstream as a key that was removed.\n */\nexport function shapeValue(value: unknown, options: ShapeValueOptions = {}): CapturedValue {\n  const shaped = shapeNode(value, '', options);\n  const text = canonicalize(shaped);\n\n  const keyed = Object.keys(options.arrayKey ?? {})\n    .map((pointer) => pointerShape(pointer))\n    .sort();\n\n  return {\n    dialect: options.dialect ?? 'json',\n    text,\n    digest: digestCombine('value/v1', [digestString(text), digestString(VALUE_RECIPE)]),\n    recipe: VALUE_RECIPE,\n    ...(keyed.length === 0 ? {} : { keyed }),\n    ...(options.generator === undefined ? {} : { generator: options.generator }),\n  };\n}\n\n/** RFC 6901: `~` becomes `~0` and `/` becomes `~1`, in that order. */\nexport function pointerToken(token: string): string {\n  return token.replace(/~/g, '~0').replace(/\\//g, '~1');\n}\n\n/**\n * The pointer with every row identity replaced by `-`.\n *\n * Two things: it is what a wildcard rule is matched against, and it is what a\n * change's fingerprint is taken over — so the same kind of edit at row 4 and at\n * row 900 is one shape happening twice rather than two findings.\n *\n * An index is a row identity by spelling. A **keyed** array's members are named\n * instead, and no spelling can distinguish those from an ordinary object's keys —\n * so `keyed` is passed in from the capture that declared it, and only the segment\n * immediately below a keyed array is wildcarded.\n */\nexport function pointerShape(pointer: string, keyed: readonly string[] = []): string {\n  const shaped = pointer.replace(/\\/\\d+(?=\\/|$)/g, '/-');\n\n  return keyed.reduce((current, array) => {\n    if (!current.startsWith(`${array}/`)) return current;\n    const rest = current.slice(array.length + 1);\n    const cut = rest.indexOf('/');\n    return cut === -1 ? `${array}/-` : `${array}/-${rest.slice(cut)}`;\n  }, shaped);\n}\n\nfunction matches(rules: readonly string[], pointer: string): boolean {\n  return rules.includes(pointer) || rules.includes(pointerShape(pointer));\n}\n\nfunction ruleFor<T>(rules: Readonly<Record<string, T>> | undefined, pointer: string): T | undefined {\n  if (rules === undefined) return undefined;\n  return rules[pointer] ?? rules[pointerShape(pointer)];\n}\n\nfunction shapeNode(value: unknown, pointer: string, options: ValueShaping): CanonicalValue {\n  if (matches(options.drop ?? [], pointer)) return DROPPED;\n\n  const replaced = ruleFor(options.replace, pointer);\n  if (replaced !== undefined) return replaced;\n\n  if (value === null) return null;\n\n  switch (typeof value) {\n    case 'string':\n    case 'boolean':\n      return value;\n    case 'number':\n      if (!Number.isFinite(value)) {\n        throw new RangeError(\n          `${describe(pointer)} is ${String(value)}, which no digest may encode: a non-finite ` +\n            'number means the thing that produced it failed, and hashing it would give a broken ' +\n            'reading a stable identity',\n        );\n      }\n      return value;\n    case 'object':\n      break;\n    default:\n      throw new TypeError(\n        `${describe(pointer)} is a ${typeof value}, which is not a value. ` +\n          'Serializing it would drop it silently, and a key that vanished from the text is ' +\n          'read downstream as a key that was removed.',\n      );\n  }\n\n  if (Array.isArray(value)) return shapeArray(value, pointer, options);\n\n  if (opaque(value)) {\n    throw new TypeError(\n      `${describe(pointer)} is a ${nameOf(value)}, which is not a value. Its state is not in ` +\n        'its own enumerable keys, so it would serialize to `{}` and two different ones would ' +\n        'compare as unchanged. Convert it where it is produced — an ISO string, a number, a ' +\n        'plain object — so the text says what was compared.',\n    );\n  }\n\n  const shaped: Record<string, CanonicalValue> = {};\n  for (const [key, member] of Object.entries(value as Record<string, unknown>)) {\n    if (member === undefined) continue;\n    shaped[key] = shapeNode(member, `${pointer}/${pointerToken(key)}`, options);\n  }\n  return shaped;\n}\n\n/**\n * Whether an object keeps its state somewhere `Object.entries` cannot reach.\n *\n * A `Date`, a `Map`, a `Set`, a `URL`, a `RegExp` — each has no own enumerable\n * key, so the object branch below produces `{}` for every one of them. That is\n * the exact harm the function and bigint refusals exist to prevent, arriving\n * through the one `typeof` that does not name it: a timestamp that moved a year\n * and a timestamp that did not both address to the digest of `{}`, and the run\n * that compares them reports unchanged.\n *\n * Emptiness alone is not the test — `{}` is a value, and an adopter may legitimately\n * snapshot one. The test is emptiness in something that is not a plain object,\n * which is what says the state went somewhere else. An instance carrying its own\n * fields serializes those fields and is left alone, exactly as `JSON.stringify`\n * would leave it.\n */\nfunction opaque(value: object): boolean {\n  if (Object.keys(value).length > 0) return false;\n  const prototype = Object.getPrototypeOf(value);\n  return prototype !== Object.prototype && prototype !== null;\n}\n\n/** What to call the thing in the refusal, so the message names the type at hand. */\nfunction nameOf(value: object): string {\n  const named = value.constructor?.name;\n  return typeof named === 'string' && named.length > 0 ? named : 'object';\n}\n\nfunction shapeArray(\n  items: readonly unknown[],\n  pointer: string,\n  options: ValueShaping,\n): CanonicalValue {\n  const key = ruleFor(options.arrayKey, pointer);\n  if (key === undefined) {\n    return items.map((item, index) => shapeNode(item, `${pointer}/${index}`, options));\n  }\n\n  const keyed: Record<string, CanonicalValue> = {};\n  items.forEach((item, index) => {\n    const at = `${pointer}/${index}`;\n    if (typeof item !== 'object' || item === null || Array.isArray(item)) {\n      throw new TypeError(`${describe(at)} is keyed by \\`${key}\\` and is not a record`);\n    }\n    const member = (item as Record<string, unknown>)[key];\n    if (typeof member !== 'string' && typeof member !== 'number') {\n      throw new TypeError(`${describe(at)} has no \\`${key}\\` to be identified by`);\n    }\n    const identity = String(member);\n    if (identity in keyed) {\n      throw new Error(\n        `${describe(pointer)} has two rows with \\`${key}\\` of ${identity}. A key that does not ` +\n          'identify a row would silently take the later one, making the earlier row invisible.',\n      );\n    }\n    keyed[identity] = shapeNode(item, `${pointer}/${pointerToken(identity)}`, options);\n  });\n  return keyed;\n}\n\nfunction describe(pointer: string): string {\n  return pointer === '' ? 'the value' : `the value at ${pointer}`;\n}\n"]}

package/dist/format/wiring.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Wiring: how a component is attached to its framework, as a dimension of its own.
+ *
+ * The other bands read the artefact. `structure` reads the tree the renderer
+ * produced, `style` reads the declarations that matched it, `geometry` reads the
+ * boxes those declarations made. All three are downstream of a decision that has
+ * already been taken, and none of them can reach back past the render to say what
+ * the component *is*.
+ *
+ * Wiring is that reach. Two components can produce byte-identical structure,
+ * semantics, text, style and geometry while one of them subscribes to a theme
+ * context and the other does not; while one is memoised and the other re-renders
+ * on every parent tick; while one keys a list by identity and the other by index,
+ * so that the first survives a reorder and the second corrupts. Those are
+ * differences in the component, they are the ones that decide how it behaves
+ * under change, and no amount of HTML and CSS contains them. They are in the
+ * fiber, so the fiber is where they are read from.
+ *
+ * ## Why this is a wire type in `core` and a reader in `react`
+ *
+ * Exactly like {@link Provenance}: the collector produces it, it travels with the
+ * document over every wire this project has, and a differ on the other end reads
+ * it without ever having seen a fiber. A type the snapshot format needs cannot
+ * live in the framework adapter, and the adapter is the only thing that should
+ * know what a `_debugHookTypes` is.
+ *
+ * ## What is deliberately not here
+ *
+ * **State values.** `useState(0)` records `useState`, never `0`. A hook's *value*
+ * is the thing that legitimately differs between two readings of one page — it is
+ * the ticker, the timestamp, the animation frame — so a band carrying it would be
+ * a flake generator wearing a band's name. Wiring carries the shape of the
+ * component's attachment and nothing that attachment happened to be holding.
+ *
+ * **Anything temporal.** Whether an instance *remounted* is the single most useful
+ * thing the fiber knows, and it is not in here, because it is not a property of a
+ * revision — it is a property of a reading, and by construction it differs between
+ * two readings of one unchanged page. It lives in `@variance-authority/react`'s
+ * `remounted()` as a finding, next to `pendingSuspense`. The rule that separates
+ * them is stated once, in `wiring.test.ts`, and it is checkable: read the same
+ * page twice without changing anything, and if the value moved it is not a band.
+ */
+/** How the framework holds a component, at one boundary. */
+export interface Wiring {
+    /**
+     * Hook names in call order: `['useState', 'useRef', 'useEffect']`.
+     *
+     * Exact rather than inferred. React records the list itself during a
+     * development render, so this is the compiler's own account of the component
+     * and not a reconstruction from the hook chain's shape — which cannot in
+     * principle separate `useMemo` from `useCallback`, or `useEffect` from
+     * `useLayoutEffect`, because those pairs build identical memo cells.
+     *
+     * Absent when the adapter could not see them, and that covers more than a
+     * production build: React only populates its record once a hook actually runs,
+     * so a component that declares none is indistinguishable from one nobody could
+     * read. Absent for both, never `[]` — "declares no hooks" is a positive claim
+     * and this observation does not support it (ADR-0002).
+     */
+    readonly hooks?: readonly string[];
+    /**
+     * The wrappers the author put around the component, outermost first.
+     *
+     * `memo` is a claim about when the component may be skipped, and `forwardRef`
+     * is a claim about who owns its host node. Both are load-bearing, both are
+     * invisible in the output, and both are ordinary things to lose in a refactor:
+     * dropping a `memo` changes no pixel and no digest in any other band, and turns
+     * a component that rendered once into one that renders on every parent tick.
+     *
+     * A list rather than one value because `memo(forwardRef(f))` is both, and
+     * reporting either alone would say a component lost a wrapper it still has.
+     */
+    readonly wrappers?: readonly ('memo' | 'forwardRef')[];
+    /**
+     * Contexts this boundary subscribes to, by display name, sorted.
+     *
+     * The dependency edge that decides re-renders and that nothing in the document
+     * shows. A component under a theme switch that changed without appearing here
+     * got its change through the CSS cascade rather than through React, and those
+     * are different explanations for the same visual difference.
+     *
+     * Anonymous contexts are named `(anonymous)` rather than dropped — a
+     * subscription nobody named is still a subscription, and dropping it would let
+     * a component that gained one compare equal to one that has none.
+     */
+    readonly contexts?: readonly string[];
+    /**
+     * The reconciliation key React holds this boundary under, when it has one.
+     *
+     * Two lists that serialize to the same `<li>a</li><li>b</li>` reconcile
+     * differently depending on whether their keys are `'a', 'b'` or `'0', '1'`, and
+     * the difference only becomes visible when the list reorders — at which point
+     * the index-keyed one has moved every child's state onto the wrong row. The
+     * fiber holds the answer before the reorder, so this is a defect readable in a
+     * single still reading of a page that currently looks perfect.
+     *
+     * Absent when React assigned none, which is the ordinary case for a component
+     * that is not one of several siblings.
+     */
+    readonly key?: string;
+}
+/**
+ * Whether a key looks positional.
+ *
+ * A heuristic, and named as one. `key: '0'` on the first child, `'1'` on the
+ * second, is what `items.map((item, index) => ...)` produces and is the defect;
+ * `key: '0'` on a list of numeric ids is the same string arrived at honestly. The
+ * two are indistinguishable at one node and separable across siblings, which is
+ * why this takes the whole run of keys rather than one of them.
+ *
+ * Returns `false` for anything shorter than two siblings: a one-element list
+ * keyed `'0'` reorders into nothing and there is no defect to report.
+ */
+export declare function keyedByPosition(keys: readonly (string | undefined)[]): boolean;
+//# sourceMappingURL=wiring.d.ts.map

package/dist/format/wiring.js

@@ -0,0 +1,60 @@
+/**
+ * Wiring: how a component is attached to its framework, as a dimension of its own.
+ *
+ * The other bands read the artefact. `structure` reads the tree the renderer
+ * produced, `style` reads the declarations that matched it, `geometry` reads the
+ * boxes those declarations made. All three are downstream of a decision that has
+ * already been taken, and none of them can reach back past the render to say what
+ * the component *is*.
+ *
+ * Wiring is that reach. Two components can produce byte-identical structure,
+ * semantics, text, style and geometry while one of them subscribes to a theme
+ * context and the other does not; while one is memoised and the other re-renders
+ * on every parent tick; while one keys a list by identity and the other by index,
+ * so that the first survives a reorder and the second corrupts. Those are
+ * differences in the component, they are the ones that decide how it behaves
+ * under change, and no amount of HTML and CSS contains them. They are in the
+ * fiber, so the fiber is where they are read from.
+ *
+ * ## Why this is a wire type in `core` and a reader in `react`
+ *
+ * Exactly like {@link Provenance}: the collector produces it, it travels with the
+ * document over every wire this project has, and a differ on the other end reads
+ * it without ever having seen a fiber. A type the snapshot format needs cannot
+ * live in the framework adapter, and the adapter is the only thing that should
+ * know what a `_debugHookTypes` is.
+ *
+ * ## What is deliberately not here
+ *
+ * **State values.** `useState(0)` records `useState`, never `0`. A hook's *value*
+ * is the thing that legitimately differs between two readings of one page — it is
+ * the ticker, the timestamp, the animation frame — so a band carrying it would be
+ * a flake generator wearing a band's name. Wiring carries the shape of the
+ * component's attachment and nothing that attachment happened to be holding.
+ *
+ * **Anything temporal.** Whether an instance *remounted* is the single most useful
+ * thing the fiber knows, and it is not in here, because it is not a property of a
+ * revision — it is a property of a reading, and by construction it differs between
+ * two readings of one unchanged page. It lives in `@variance-authority/react`'s
+ * `remounted()` as a finding, next to `pendingSuspense`. The rule that separates
+ * them is stated once, in `wiring.test.ts`, and it is checkable: read the same
+ * page twice without changing anything, and if the value moved it is not a band.
+ */
+/**
+ * Whether a key looks positional.
+ *
+ * A heuristic, and named as one. `key: '0'` on the first child, `'1'` on the
+ * second, is what `items.map((item, index) => ...)` produces and is the defect;
+ * `key: '0'` on a list of numeric ids is the same string arrived at honestly. The
+ * two are indistinguishable at one node and separable across siblings, which is
+ * why this takes the whole run of keys rather than one of them.
+ *
+ * Returns `false` for anything shorter than two siblings: a one-element list
+ * keyed `'0'` reorders into nothing and there is no defect to report.
+ */
+export function keyedByPosition(keys) {
+    if (keys.length < 2)
+        return false;
+    return keys.every((key, index) => key === String(index));
+}
+//# sourceMappingURL=wiring.js.map

package/dist/format/wiring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiring.js","sourceRoot":"","sources":["../../src/format/wiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAiEH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,IAAqC;IACnE,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAClC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AAC3D,CAAC","sourcesContent":["/**\n * Wiring: how a component is attached to its framework, as a dimension of its own.\n *\n * The other bands read the artefact. `structure` reads the tree the renderer\n * produced, `style` reads the declarations that matched it, `geometry` reads the\n * boxes those declarations made. All three are downstream of a decision that has\n * already been taken, and none of them can reach back past the render to say what\n * the component *is*.\n *\n * Wiring is that reach. Two components can produce byte-identical structure,\n * semantics, text, style and geometry while one of them subscribes to a theme\n * context and the other does not; while one is memoised and the other re-renders\n * on every parent tick; while one keys a list by identity and the other by index,\n * so that the first survives a reorder and the second corrupts. Those are\n * differences in the component, they are the ones that decide how it behaves\n * under change, and no amount of HTML and CSS contains them. They are in the\n * fiber, so the fiber is where they are read from.\n *\n * ## Why this is a wire type in `core` and a reader in `react`\n *\n * Exactly like {@link Provenance}: the collector produces it, it travels with the\n * document over every wire this project has, and a differ on the other end reads\n * it without ever having seen a fiber. A type the snapshot format needs cannot\n * live in the framework adapter, and the adapter is the only thing that should\n * know what a `_debugHookTypes` is.\n *\n * ## What is deliberately not here\n *\n * **State values.** `useState(0)` records `useState`, never `0`. A hook's *value*\n * is the thing that legitimately differs between two readings of one page — it is\n * the ticker, the timestamp, the animation frame — so a band carrying it would be\n * a flake generator wearing a band's name. Wiring carries the shape of the\n * component's attachment and nothing that attachment happened to be holding.\n *\n * **Anything temporal.** Whether an instance *remounted* is the single most useful\n * thing the fiber knows, and it is not in here, because it is not a property of a\n * revision — it is a property of a reading, and by construction it differs between\n * two readings of one unchanged page. It lives in `@variance-authority/react`'s\n * `remounted()` as a finding, next to `pendingSuspense`. The rule that separates\n * them is stated once, in `wiring.test.ts`, and it is checkable: read the same\n * page twice without changing anything, and if the value moved it is not a band.\n */\n\n/** How the framework holds a component, at one boundary. */\nexport interface Wiring {\n  /**\n   * Hook names in call order: `['useState', 'useRef', 'useEffect']`.\n   *\n   * Exact rather than inferred. React records the list itself during a\n   * development render, so this is the compiler's own account of the component\n   * and not a reconstruction from the hook chain's shape — which cannot in\n   * principle separate `useMemo` from `useCallback`, or `useEffect` from\n   * `useLayoutEffect`, because those pairs build identical memo cells.\n   *\n   * Absent when the adapter could not see them, and that covers more than a\n   * production build: React only populates its record once a hook actually runs,\n   * so a component that declares none is indistinguishable from one nobody could\n   * read. Absent for both, never `[]` — \"declares no hooks\" is a positive claim\n   * and this observation does not support it (ADR-0002).\n   */\n  readonly hooks?: readonly string[];\n\n  /**\n   * The wrappers the author put around the component, outermost first.\n   *\n   * `memo` is a claim about when the component may be skipped, and `forwardRef`\n   * is a claim about who owns its host node. Both are load-bearing, both are\n   * invisible in the output, and both are ordinary things to lose in a refactor:\n   * dropping a `memo` changes no pixel and no digest in any other band, and turns\n   * a component that rendered once into one that renders on every parent tick.\n   *\n   * A list rather than one value because `memo(forwardRef(f))` is both, and\n   * reporting either alone would say a component lost a wrapper it still has.\n   */\n  readonly wrappers?: readonly ('memo' | 'forwardRef')[];\n\n  /**\n   * Contexts this boundary subscribes to, by display name, sorted.\n   *\n   * The dependency edge that decides re-renders and that nothing in the document\n   * shows. A component under a theme switch that changed without appearing here\n   * got its change through the CSS cascade rather than through React, and those\n   * are different explanations for the same visual difference.\n   *\n   * Anonymous contexts are named `(anonymous)` rather than dropped — a\n   * subscription nobody named is still a subscription, and dropping it would let\n   * a component that gained one compare equal to one that has none.\n   */\n  readonly contexts?: readonly string[];\n\n  /**\n   * The reconciliation key React holds this boundary under, when it has one.\n   *\n   * Two lists that serialize to the same `<li>a</li><li>b</li>` reconcile\n   * differently depending on whether their keys are `'a', 'b'` or `'0', '1'`, and\n   * the difference only becomes visible when the list reorders — at which point\n   * the index-keyed one has moved every child's state onto the wrong row. The\n   * fiber holds the answer before the reorder, so this is a defect readable in a\n   * single still reading of a page that currently looks perfect.\n   *\n   * Absent when React assigned none, which is the ordinary case for a component\n   * that is not one of several siblings.\n   */\n  readonly key?: string;\n}\n\n/**\n * Whether a key looks positional.\n *\n * A heuristic, and named as one. `key: '0'` on the first child, `'1'` on the\n * second, is what `items.map((item, index) => ...)` produces and is the defect;\n * `key: '0'` on a list of numeric ids is the same string arrived at honestly. The\n * two are indistinguishable at one node and separable across siblings, which is\n * why this takes the whole run of keys rather than one of them.\n *\n * Returns `false` for anything shorter than two siblings: a one-element list\n * keyed `'0'` reorders into nothing and there is no defect to report.\n */\nexport function keyedByPosition(keys: readonly (string | undefined)[]): boolean {\n  if (keys.length < 2) return false;\n  return keys.every((key, index) => key === String(index));\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `@variance-authority/core` — the format, the rules, and the verdict model.
+ *
+ * This package is pure data in, pure data out: no DOM, no React, no I/O, no
+ * async. That is enforced by its `tsconfig` (`lib: ES2022` only), so "the core
+ * cannot peek at a live document" is a compile error rather than a convention
+ * (ADR-0001). Collectors extract; core normalizes and adjudicates.
+ *
+ * Seven groups, each its own entrypoint, in the order an answer travels through
+ * them:
+ *
+ * | entrypoint | what it holds |
+ * |---|---|
+ * | `core/format` | what a subject *is*: capture, snapshot, document, identity |
+ * | `core/rules` | the versioned opinions: allowlist, cascade, canonicalization |
+ * | `core/compare` | two snapshots become deltas — and no verdict |
+ * | `core/attribute` | a position becomes a component becomes a file |
+ * | `core/relate` | what reaches what: the graph a change is traversed over |
+ * | `core/judge` | policy: verdicts, intent, the docket a reader is handed |
+ * | `core/plan` | a composition as a value, and the identity derived from it |
+ *
+ * This entrypoint is all seven, and is what most callers want. The groups exist for
+ * the callers who genuinely want one: somebody implementing the format for a
+ * renderer this project has never met needs `core/format` and would be misled by
+ * everything else.
+ */
+export * from './format/index.js';
+export * from './rules/index.js';
+export * from './compare/index.js';
+export * from './attribute/index.js';
+export * from './relate/index.js';
+export * from './judge/index.js';
+export * from './plan/index.js';
+export * from './artifact.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,35 @@
+/**
+ * `@variance-authority/core` — the format, the rules, and the verdict model.
+ *
+ * This package is pure data in, pure data out: no DOM, no React, no I/O, no
+ * async. That is enforced by its `tsconfig` (`lib: ES2022` only), so "the core
+ * cannot peek at a live document" is a compile error rather than a convention
+ * (ADR-0001). Collectors extract; core normalizes and adjudicates.
+ *
+ * Seven groups, each its own entrypoint, in the order an answer travels through
+ * them:
+ *
+ * | entrypoint | what it holds |
+ * |---|---|
+ * | `core/format` | what a subject *is*: capture, snapshot, document, identity |
+ * | `core/rules` | the versioned opinions: allowlist, cascade, canonicalization |
+ * | `core/compare` | two snapshots become deltas — and no verdict |
+ * | `core/attribute` | a position becomes a component becomes a file |
+ * | `core/relate` | what reaches what: the graph a change is traversed over |
+ * | `core/judge` | policy: verdicts, intent, the docket a reader is handed |
+ * | `core/plan` | a composition as a value, and the identity derived from it |
+ *
+ * This entrypoint is all seven, and is what most callers want. The groups exist for
+ * the callers who genuinely want one: somebody implementing the format for a
+ * renderer this project has never met needs `core/format` and would be misled by
+ * everything else.
+ */
+export * from './format/index.js';
+export * from './rules/index.js';
+export * from './compare/index.js';
+export * from './attribute/index.js';
+export * from './relate/index.js';
+export * from './judge/index.js';
+export * from './plan/index.js';
+export * from './artifact.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC","sourcesContent":["/**\n * `@variance-authority/core` — the format, the rules, and the verdict model.\n *\n * This package is pure data in, pure data out: no DOM, no React, no I/O, no\n * async. That is enforced by its `tsconfig` (`lib: ES2022` only), so \"the core\n * cannot peek at a live document\" is a compile error rather than a convention\n * (ADR-0001). Collectors extract; core normalizes and adjudicates.\n *\n * Seven groups, each its own entrypoint, in the order an answer travels through\n * them:\n *\n * | entrypoint | what it holds |\n * |---|---|\n * | `core/format` | what a subject *is*: capture, snapshot, document, identity |\n * | `core/rules` | the versioned opinions: allowlist, cascade, canonicalization |\n * | `core/compare` | two snapshots become deltas — and no verdict |\n * | `core/attribute` | a position becomes a component becomes a file |\n * | `core/relate` | what reaches what: the graph a change is traversed over |\n * | `core/judge` | policy: verdicts, intent, the docket a reader is handed |\n * | `core/plan` | a composition as a value, and the identity derived from it |\n *\n * This entrypoint is all seven, and is what most callers want. The groups exist for\n * the callers who genuinely want one: somebody implementing the format for a\n * renderer this project has never met needs `core/format` and would be misled by\n * everything else.\n */\n\nexport * from './format/index.js';\nexport * from './rules/index.js';\nexport * from './compare/index.js';\nexport * from './attribute/index.js';\nexport * from './relate/index.js';\nexport * from './judge/index.js';\nexport * from './plan/index.js';\nexport * from './artifact.js';\n"]}

package/dist/judge/docket.d.ts

@@ -0,0 +1,85 @@
+import { type Band } from '../compare/band.js';
+import type { ChangedComponent, RootKind, SemanticDiff } from '../compare/diff/index.js';
+import { type AggregateImpact } from '../compare/impact.js';
+/**
+ * The docket: one entry per root cause, across every subject in a change set.
+ *
+ * A `SemanticDiff` answers "what changed in this subject". That is the wrong unit
+ * for review, and reviewing at that unit is what makes visual regression
+ * unbearable — one design-token edit arrives as three hundred separate subjects
+ * to click through, and the three-hundred-and-first gets approved without being
+ * read.
+ *
+ * The docket inverts it. One token edit is **one entry**, carrying the count of
+ * what it reached. Spec §6.2 requires that approving it be a single action, which
+ * is only possible if the thing being approved is the cause rather than each of
+ * its effects.
+ *
+ * Aggregation is by root **id**, which is why root ids are constructed to be
+ * stable across subjects: `token:--color-primary` is the same root wherever it
+ * lands, so the grouping needs no similarity heuristic.
+ */
+export interface DocketEntry {
+    readonly rootId: string;
+    readonly kind: RootKind;
+    readonly label: string;
+    readonly band: Band;
+    readonly impact: AggregateImpact;
+    /** Subjects this root reached, in first-seen order. */
+    readonly subjects: readonly string[];
+    readonly subjectCount: number;
+    /** Individual deltas across all subjects — the collateral count. */
+    readonly deltaCount: number;
+    readonly components: readonly ChangedComponent[];
+    /**
+     * A few subjects to actually look at.
+     *
+     * Mass re-baselining is only survivable if approval is *informed*, and nobody
+     * informs themselves by reviewing three hundred identical diffs. Spec §7.3 asks
+     * for a sampled spot-check list, and this is it.
+     */
+    readonly sample: readonly string[];
+    /**
+     * Distinct places this root's changes were observed, most common first.
+     *
+     * Carried on the entry rather than derived from deltas at report time, because
+     * an entry spans subjects and the deltas behind it are not kept. Three is
+     * enough to orient without turning a collapsed root back into a list — the
+     * thing collapsing it was for.
+     */
+    readonly places: readonly string[];
+    /**
+     * `true` when nothing under this root added, removed, moved, or renamed a node.
+     *
+     * The other half of the sentence the product promises. "One token change, 300
+     * collateral" is only reassuring alongside "structure intact" — that is what
+     * makes it a one-action approval rather than three hundred things to check.
+     */
+    readonly structureIntact: boolean;
+}
+export interface Docket {
+    readonly entries: readonly DocketEntry[];
+    readonly subjectsCompared: number;
+    readonly subjectsUnchanged: number;
+    readonly subjectsChanged: number;
+    /**
+     * `true` when every change in the set has one explanation.
+     *
+     * The condition under which the whole review collapses to a single action.
+     */
+    readonly singleRoot: boolean;
+}
+export interface DocketOptions {
+    /** Subjects listed per entry for spot-checking. Policy, not a constant. */
+    readonly sampleSize?: number;
+}
+export declare function buildDocket(diffs: readonly SemanticDiff[], options?: DocketOptions): Docket;
+/**
+ * The docket as one sentence per entry.
+ *
+ * Deliberately terse. The audience is a reviewer deciding whether to look
+ * further and an agent deciding whether to act, and both are worse served by a
+ * paragraph than by a line they can scan.
+ */
+export declare function summarize(docket: Docket): string;
+//# sourceMappingURL=docket.d.ts.map