@variance-authority/core 0.1.0

package/dist/format/hash.js

@@ -0,0 +1,41 @@
+import { canonicalize } from './canonical.js';
+import { sha256Hex, sha256HexBytes } from './sha256.js';
+const PREFIX = 'v1';
+const HEX_LENGTH = 32;
+/**
+ * Hash an already-canonical string.
+ *
+ * Synchronous, and must stay so. `propsDigest` runs inside the rendering page,
+ * where a prop may be a function or an element that cannot be serialized out —
+ * so the digest is taken where the value still exists. `crypto.subtle` is async
+ * and would colour the whole normalizer; see `sha256.ts`.
+ */
+export function digestString(input) {
+    return `${PREFIX}:${sha256Hex(input).slice(0, HEX_LENGTH)}`;
+}
+/**
+ * Hash raw bytes — an image, a font file, anything whose identity is its octets.
+ *
+ * Same prefix and same truncation as every other digest here, so an asset hash
+ * and a render hash are the same kind of value and neither can be mistaken for
+ * the other's domain. What it is for is `EnvironmentInputs.assets`: a URL is not
+ * an identity, and the same `url(...)` can resolve to different bytes tomorrow.
+ */
+export function digestBytes(bytes) {
+    return `${PREFIX}:${sha256HexBytes(bytes).slice(0, HEX_LENGTH)}`;
+}
+/** Canonicalize then hash. The only correct way to hash a structure. */
+export function digestValue(value) {
+    return digestString(canonicalize(value));
+}
+/**
+ * Combine digests under a domain label.
+ *
+ * The label prevents cross-domain collision: an environment key and a render hash
+ * built from identical component digests must not be equal, or an environment
+ * change could masquerade as a content match.
+ */
+export function digestCombine(domain, parts) {
+    return digestString(`${domain}\u0000${parts.join('\u0000')}`);
+}
+//# sourceMappingURL=hash.js.map

package/dist/format/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../src/format/hash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAuB,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAkBxD,MAAM,MAAM,GAAG,IAAI,CAAC;AACpB,MAAM,UAAU,GAAG,EAAE,CAAC;AAEtB;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,GAAG,MAAM,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,CAAC;AAC9D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,KAAiB;IAC3C,OAAO,GAAG,MAAM,IAAI,cAAc,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,CAAC;AACnE,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,WAAW,CAAC,KAAqB;IAC/C,OAAO,YAAY,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,KAAwB;IACpE,OAAO,YAAY,CAAC,GAAG,MAAM,SAAS,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAChE,CAAC","sourcesContent":["import { canonicalize, type CanonicalValue } from './canonical.js';\nimport { sha256Hex, sha256HexBytes } from './sha256.js';\n\n/**\n * Content addressing (Principle 4).\n *\n * Hashes are the system's only identity. A baseline is addressed by what it *is*,\n * never by the branch or commit it arrived on, which is why a rebase cannot\n * invalidate one.\n *\n * Digests are prefixed with their algorithm and truncated to 128 bits. The prefix\n * makes a future algorithm change a visible, greppable migration rather than a\n * silent collision domain; 128 bits is far beyond collision risk for a corpus\n * bounded by the number of subjects a repository has, and keeps `variance.lock`\n * readable as a diff — a manifest a human refuses to read is a manifest nobody\n * reviews.\n */\nexport type Digest = string;\n\nconst PREFIX = 'v1';\nconst HEX_LENGTH = 32;\n\n/**\n * Hash an already-canonical string.\n *\n * Synchronous, and must stay so. `propsDigest` runs inside the rendering page,\n * where a prop may be a function or an element that cannot be serialized out —\n * so the digest is taken where the value still exists. `crypto.subtle` is async\n * and would colour the whole normalizer; see `sha256.ts`.\n */\nexport function digestString(input: string): Digest {\n  return `${PREFIX}:${sha256Hex(input).slice(0, HEX_LENGTH)}`;\n}\n\n/**\n * Hash raw bytes — an image, a font file, anything whose identity is its octets.\n *\n * Same prefix and same truncation as every other digest here, so an asset hash\n * and a render hash are the same kind of value and neither can be mistaken for\n * the other's domain. What it is for is `EnvironmentInputs.assets`: a URL is not\n * an identity, and the same `url(...)` can resolve to different bytes tomorrow.\n */\nexport function digestBytes(bytes: Uint8Array): Digest {\n  return `${PREFIX}:${sha256HexBytes(bytes).slice(0, HEX_LENGTH)}`;\n}\n\n/** Canonicalize then hash. The only correct way to hash a structure. */\nexport function digestValue(value: CanonicalValue): Digest {\n  return digestString(canonicalize(value));\n}\n\n/**\n * Combine digests under a domain label.\n *\n * The label prevents cross-domain collision: an environment key and a render hash\n * built from identical component digests must not be equal, or an environment\n * change could masquerade as a content match.\n */\nexport function digestCombine(domain: string, parts: readonly Digest[]): Digest {\n  return digestString(`${domain}\\u0000${parts.join('\\u0000')}`);\n}\n"]}

package/dist/format/holding.d.ts

@@ -0,0 +1,134 @@
+import type { Digest } from './hash.js';
+/**
+ * Holding: what a component was holding, as distinct from how it is attached.
+ *
+ * {@link Wiring} ends on the sentence that defines this type by exclusion —
+ * *wiring carries the shape of the component's attachment and nothing that
+ * attachment happened to be holding*. This is the nothing. A `useState` cell's
+ * value, a `useSyncExternalStore` snapshot, a context's current value, and the
+ * per-key breakdown of the props object a boundary was handed.
+ *
+ * ## Why the refusal in `Wiring` is not reversed here
+ *
+ * `Wiring` states, correctly, that state values must never be a band: a hook's
+ * value is the thing that *legitimately* differs between two readings of one
+ * page — the ticker, the timestamp, the animation frame — so a band carrying one
+ * would be a flake generator wearing a band's name. That argument is about
+ * **identity**, and it is accepted here without qualification.
+ *
+ * This type is not identity. It is **evidence**, and it enters no hash: not the
+ * render hash, not the structure or style hash, not a component hash, not an
+ * environment key. Its precedent is `styleProvenance`, which exists for the same
+ * reason and takes the same exemption — normalization discards exactly what
+ * attribution needs, so the discarded thing is preserved beside the snapshot
+ * rather than inside it. Keeping it outside is the point, twice over: a baseline
+ * cannot be invalidated by a value that was always allowed to move, and a
+ * differ that could not read *why* a component chose differently is left
+ * reporting the choice.
+ *
+ * The two types therefore answer different questions about one boundary, and the
+ * pair is what makes the interesting sentence sayable:
+ *
+ * | question | answered by |
+ * |---|---|
+ * | is this the same component? | `Wiring` — hook shape, wrappers, contexts, key |
+ * | did it decide the same way? | `Holding` — the values those hooks were holding |
+ *
+ * ## Digests, never values
+ *
+ * Every field is a {@link Digest}, on spec 0024's rule and for its reason: a
+ * prop value can be a customer record, and a `useState` cell can hold the same
+ * record with a session token beside it. The digest is what makes an equality
+ * comparison possible without the value leaving the page. Nothing here can be
+ * reversed into what a user was looking at, which is the property that lets this
+ * travel over the same wire the rest of the document does.
+ *
+ * The cost is the one `propsDigest` already documents and accepts: shape rather
+ * than identity, so a re-created closure does not register and a genuinely
+ * rebound anonymous one does not either. That is tolerable for the same reason —
+ * this decides *who is responsible* for a difference the semantic diff already
+ * found, never *whether* there is one.
+ */
+export interface Holding {
+    /**
+     * One digest per hook that retains something, in authored call order.
+     *
+     * Sparse by construction. A hook that retains nothing a later reading could
+     * disagree about contributes no cell, so `useContext` (which has no cell at
+     * all) and the dispatch half of `useActionState` (a function React rebuilds)
+     * are absent rather than present-and-meaningless. {@link HeldCell.index}
+     * carries the authored position, so a gap is legible instead of silently
+     * renumbering everything after it.
+     */
+    readonly cells?: readonly HeldCell[];
+    /**
+     * Context values this boundary read, by the context's display name, sorted.
+     *
+     * Separate from `cells` because a context subscription leaves no hook cell —
+     * it is recorded on the fiber's dependency list and nowhere else — and because
+     * the two fail differently. A changed cell is this component's own decision; a
+     * changed context is a decision taken above it by a provider that may not even
+     * be in the subject, which is a different sentence and a different fix.
+     */
+    readonly contexts?: readonly HeldValue[];
+    /**
+     * The props object, one digest per key, sorted — spec 0024's map.
+     *
+     * `OwnerFrame.propsDigest` says *this component was handed something
+     * different* and cannot say which thing. This says which thing, under the same
+     * projection and with `children` excluded for the same reason: `children` *is*
+     * the subtree, and digesting it would make every ancestor's inputs a function
+     * of every descendant's edit, which is the condition that makes root
+     * attribution work at all.
+     */
+    readonly props?: readonly HeldValue[];
+    /**
+     * The hook whose name this reader does not know, when one was met.
+     *
+     * Present only on a truncated read, and its presence means `cells` is a
+     * *prefix* rather than the whole list. Alignment between React's recorded hook
+     * names and its hook cells depends on knowing how many cells each hook builds
+     * (see the reader's table), so one unrecognised name makes every cell after it
+     * unattributable — not wrong by a little, but attached to the wrong hook.
+     *
+     * Reported rather than guessed through, on ADR-0002: a prefix that says where
+     * it stopped is usable, and a full list silently mislabelled from the fourth
+     * entry on is the failure this project exists to refuse. The reader stops, and
+     * a React release that adds a hook makes this field appear instead of making
+     * an attribution quietly point at the wrong `useState`.
+     */
+    readonly unread?: string;
+}
+/** One hook cell's retained value, addressed by the position a person can count to. */
+export interface HeldCell {
+    /**
+     * Position in the component's own hook call order, zero-based.
+     *
+     * The number a reader arrives at by counting hook calls down the component,
+     * which is the only index anybody can act on — it indexes
+     * {@link Wiring.hooks} exactly, and it is *not* an index into React's cell
+     * chain, because `useContext` builds no cell and `useTransition` builds two.
+     * Converting between the two is the reader's job and the reason it needs a
+     * measured table rather than a zip.
+     */
+    readonly index: number;
+    /** `useState`, `useReducer`, `useSyncExternalStore`, … as React recorded it. */
+    readonly hook: string;
+    /**
+     * Digest of what the cell held, under a projection chosen per hook.
+     *
+     * Per hook because the cells are not alike and a single rule over them is
+     * either useless or fatal. A `useState` cell holds the state; a `useMemo` cell
+     * holds `[value, deps]` and the deps are the input the value is derived from;
+     * an effect cell holds an object whose `next` pointer closes a ring, and
+     * walking one is an out-of-memory kill rather than a bad digest. The reader
+     * names the projection it used for each.
+     */
+    readonly digest: Digest;
+}
+/** A named value a boundary read: a context, or one prop. */
+export interface HeldValue {
+    readonly name: string;
+    readonly digest: Digest;
+}
+//# sourceMappingURL=holding.d.ts.map

package/dist/format/holding.js

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

package/dist/format/holding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"holding.js","sourceRoot":"","sources":["../../src/format/holding.ts"],"names":[],"mappings":"","sourcesContent":["import type { Digest } from './hash.js';\n\n/**\n * Holding: what a component was holding, as distinct from how it is attached.\n *\n * {@link Wiring} ends on the sentence that defines this type by exclusion —\n * *wiring carries the shape of the component's attachment and nothing that\n * attachment happened to be holding*. This is the nothing. A `useState` cell's\n * value, a `useSyncExternalStore` snapshot, a context's current value, and the\n * per-key breakdown of the props object a boundary was handed.\n *\n * ## Why the refusal in `Wiring` is not reversed here\n *\n * `Wiring` states, correctly, that state values must never be a band: a hook's\n * value is the thing that *legitimately* differs between two readings of one\n * page — the ticker, the timestamp, the animation frame — so a band carrying one\n * would be a flake generator wearing a band's name. That argument is about\n * **identity**, and it is accepted here without qualification.\n *\n * This type is not identity. It is **evidence**, and it enters no hash: not the\n * render hash, not the structure or style hash, not a component hash, not an\n * environment key. Its precedent is `styleProvenance`, which exists for the same\n * reason and takes the same exemption — normalization discards exactly what\n * attribution needs, so the discarded thing is preserved beside the snapshot\n * rather than inside it. Keeping it outside is the point, twice over: a baseline\n * cannot be invalidated by a value that was always allowed to move, and a\n * differ that could not read *why* a component chose differently is left\n * reporting the choice.\n *\n * The two types therefore answer different questions about one boundary, and the\n * pair is what makes the interesting sentence sayable:\n *\n * | question | answered by |\n * |---|---|\n * | is this the same component? | `Wiring` — hook shape, wrappers, contexts, key |\n * | did it decide the same way? | `Holding` — the values those hooks were holding |\n *\n * ## Digests, never values\n *\n * Every field is a {@link Digest}, on spec 0024's rule and for its reason: a\n * prop value can be a customer record, and a `useState` cell can hold the same\n * record with a session token beside it. The digest is what makes an equality\n * comparison possible without the value leaving the page. Nothing here can be\n * reversed into what a user was looking at, which is the property that lets this\n * travel over the same wire the rest of the document does.\n *\n * The cost is the one `propsDigest` already documents and accepts: shape rather\n * than identity, so a re-created closure does not register and a genuinely\n * rebound anonymous one does not either. That is tolerable for the same reason —\n * this decides *who is responsible* for a difference the semantic diff already\n * found, never *whether* there is one.\n */\nexport interface Holding {\n  /**\n   * One digest per hook that retains something, in authored call order.\n   *\n   * Sparse by construction. A hook that retains nothing a later reading could\n   * disagree about contributes no cell, so `useContext` (which has no cell at\n   * all) and the dispatch half of `useActionState` (a function React rebuilds)\n   * are absent rather than present-and-meaningless. {@link HeldCell.index}\n   * carries the authored position, so a gap is legible instead of silently\n   * renumbering everything after it.\n   */\n  readonly cells?: readonly HeldCell[];\n\n  /**\n   * Context values this boundary read, by the context's display name, sorted.\n   *\n   * Separate from `cells` because a context subscription leaves no hook cell —\n   * it is recorded on the fiber's dependency list and nowhere else — and because\n   * the two fail differently. A changed cell is this component's own decision; a\n   * changed context is a decision taken above it by a provider that may not even\n   * be in the subject, which is a different sentence and a different fix.\n   */\n  readonly contexts?: readonly HeldValue[];\n\n  /**\n   * The props object, one digest per key, sorted — spec 0024's map.\n   *\n   * `OwnerFrame.propsDigest` says *this component was handed something\n   * different* and cannot say which thing. This says which thing, under the same\n   * projection and with `children` excluded for the same reason: `children` *is*\n   * the subtree, and digesting it would make every ancestor's inputs a function\n   * of every descendant's edit, which is the condition that makes root\n   * attribution work at all.\n   */\n  readonly props?: readonly HeldValue[];\n\n  /**\n   * The hook whose name this reader does not know, when one was met.\n   *\n   * Present only on a truncated read, and its presence means `cells` is a\n   * *prefix* rather than the whole list. Alignment between React's recorded hook\n   * names and its hook cells depends on knowing how many cells each hook builds\n   * (see the reader's table), so one unrecognised name makes every cell after it\n   * unattributable — not wrong by a little, but attached to the wrong hook.\n   *\n   * Reported rather than guessed through, on ADR-0002: a prefix that says where\n   * it stopped is usable, and a full list silently mislabelled from the fourth\n   * entry on is the failure this project exists to refuse. The reader stops, and\n   * a React release that adds a hook makes this field appear instead of making\n   * an attribution quietly point at the wrong `useState`.\n   */\n  readonly unread?: string;\n}\n\n/** One hook cell's retained value, addressed by the position a person can count to. */\nexport interface HeldCell {\n  /**\n   * Position in the component's own hook call order, zero-based.\n   *\n   * The number a reader arrives at by counting hook calls down the component,\n   * which is the only index anybody can act on — it indexes\n   * {@link Wiring.hooks} exactly, and it is *not* an index into React's cell\n   * chain, because `useContext` builds no cell and `useTransition` builds two.\n   * Converting between the two is the reader's job and the reason it needs a\n   * measured table rather than a zip.\n   */\n  readonly index: number;\n\n  /** `useState`, `useReducer`, `useSyncExternalStore`, … as React recorded it. */\n  readonly hook: string;\n\n  /**\n   * Digest of what the cell held, under a projection chosen per hook.\n   *\n   * Per hook because the cells are not alike and a single rule over them is\n   * either useless or fatal. A `useState` cell holds the state; a `useMemo` cell\n   * holds `[value, deps]` and the deps are the input the value is derived from;\n   * an effect cell holds an object whose `next` pointer closes a ring, and\n   * walking one is an out-of-memory kill rather than a bad digest. The reader\n   * names the projection it used for each.\n   */\n  readonly digest: Digest;\n}\n\n/** A named value a boundary read: a context, or one prop. */\nexport interface HeldValue {\n  readonly name: string;\n  readonly digest: Digest;\n}\n"]}

package/dist/format/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `@variance-authority/core/format` — what a subject *is*, as a value.
+ *
+ * The shapes every other group reads and none of them may redefine: a raw
+ * capture as a collector hands it over, the normalized snapshot it becomes, the
+ * document a renderer paints, the identity that addresses the result, and the
+ * hashing that makes any of it comparable.
+ *
+ * A consumer writing their own collector needs exactly this and nothing else.
+ * That is the entrypoint's reason to exist: the format is a contract other people
+ * implement, and implementing it should not require reading the rules that
+ * interpret it or the verdicts drawn from it.
+ */
+export type { CanonicalValue } from './canonical.js';
+export { canonicalize, canonicalNumber } from './canonical.js';
+export type { CapturedValue, ShapeValueOptions, ValueShaping } from './value.js';
+export { shapeValue, pointerShape, pointerToken, DROPPED, VALUE_RECIPE } from './value.js';
+export type { Digest } from './hash.js';
+export { digestString, digestBytes, digestValue, digestCombine } from './hash.js';
+export type { AccessibilitySnapshot } from './accessibility.js';
+export { accessibilitySnapshot } from './accessibility.js';
+export type { ObservationProfile, ProfileId } from './profile.js';
+export { JSDOM_PROFILE, CHROMIUM_PROFILE, profileById, tierOfProfile } from './profile.js';
+export type { Tier } from './tier.js';
+export { tierReaches } from './tier.js';
+export type { EnvironmentInputs, EnvironmentKey, EnvironmentDelta, EnvironmentField, Viewport, } from './environment.js';
+export { environmentKey, diffEnvironments } from './environment.js';
+export { INTERVENTIONS, SEMANTIC_RECIPE, COLLECT_RECIPE, LAYOUT_RECIPE, RASTER_RECIPE, holdAnimations, pinAnimations, hideCaret, hideScrollbars, hidePresentationalImages, waitForFonts, waitForImages, forTier, conflicts, interventionById, recipeOf, recipeCss, recipeScreenshot, recipeDigest, settleRecipe, describeRecipe, } from './stabilize.js';
+export type { Intervention, Recipe, Trick, ScreenshotOptions, SettleTarget, } from './stabilize.js';
+export type { Provenance, OwnerFrame, SourceLocation, StackFrame } from './provenance.js';
+export { propsDigest, heldDigest, jsxSourceOf, relativizeSource, JSX_SOURCE } from './provenance.js';
+export type { Holding, HeldCell, HeldValue } from './holding.js';
+export type { Wiring } from './wiring.js';
+export { keyedByPosition } from './wiring.js';
+export type { RawCapture, RawNode, RawAria, MatchedRule, Declaration, Rect, SubjectRef, Diagnostic, } from './capture.js';
+export type { SemanticSnapshot, SemanticNode, NodePath, StyleProvenanceEntry, IgnoreSite, ComponentHash, } from './snapshot.js';
+export { documentDigest, identityDigest } from './document.js';
+export type { RenderDocument, RenderFrame, FrameElement, RenderResource, RenderIdentity, Raster, } from './document.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/format/index.js

@@ -0,0 +1,25 @@
+/**
+ * `@variance-authority/core/format` — what a subject *is*, as a value.
+ *
+ * The shapes every other group reads and none of them may redefine: a raw
+ * capture as a collector hands it over, the normalized snapshot it becomes, the
+ * document a renderer paints, the identity that addresses the result, and the
+ * hashing that makes any of it comparable.
+ *
+ * A consumer writing their own collector needs exactly this and nothing else.
+ * That is the entrypoint's reason to exist: the format is a contract other people
+ * implement, and implementing it should not require reading the rules that
+ * interpret it or the verdicts drawn from it.
+ */
+export { canonicalize, canonicalNumber } from './canonical.js';
+export { shapeValue, pointerShape, pointerToken, DROPPED, VALUE_RECIPE } from './value.js';
+export { digestString, digestBytes, digestValue, digestCombine } from './hash.js';
+export { accessibilitySnapshot } from './accessibility.js';
+export { JSDOM_PROFILE, CHROMIUM_PROFILE, profileById, tierOfProfile } from './profile.js';
+export { tierReaches } from './tier.js';
+export { environmentKey, diffEnvironments } from './environment.js';
+export { INTERVENTIONS, SEMANTIC_RECIPE, COLLECT_RECIPE, LAYOUT_RECIPE, RASTER_RECIPE, holdAnimations, pinAnimations, hideCaret, hideScrollbars, hidePresentationalImages, waitForFonts, waitForImages, forTier, conflicts, interventionById, recipeOf, recipeCss, recipeScreenshot, recipeDigest, settleRecipe, describeRecipe, } from './stabilize.js';
+export { propsDigest, heldDigest, jsxSourceOf, relativizeSource, JSX_SOURCE } from './provenance.js';
+export { keyedByPosition } from './wiring.js';
+export { documentDigest, identityDigest } from './document.js';
+//# sourceMappingURL=index.js.map

package/dist/format/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/format/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAG/D,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG3F,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAGlF,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAG3D,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG3F,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AASxC,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpE,OAAO,EACL,aAAa,EACb,eAAe,EACf,cAAc,EACd,aAAa,EACb,aAAa,EACb,cAAc,EACd,aAAa,EACb,SAAS,EACT,cAAc,EACd,wBAAwB,EACxB,YAAY,EACZ,aAAa,EACb,OAAO,EACP,SAAS,EACT,gBAAgB,EAChB,QAAQ,EACR,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,cAAc,GACf,MAAM,gBAAgB,CAAC;AAUxB,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGrG,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAsB9C,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC","sourcesContent":["/**\n * `@variance-authority/core/format` — what a subject *is*, as a value.\n *\n * The shapes every other group reads and none of them may redefine: a raw\n * capture as a collector hands it over, the normalized snapshot it becomes, the\n * document a renderer paints, the identity that addresses the result, and the\n * hashing that makes any of it comparable.\n *\n * A consumer writing their own collector needs exactly this and nothing else.\n * That is the entrypoint's reason to exist: the format is a contract other people\n * implement, and implementing it should not require reading the rules that\n * interpret it or the verdicts drawn from it.\n */\n\nexport type { CanonicalValue } from './canonical.js';\nexport { canonicalize, canonicalNumber } from './canonical.js';\n\nexport type { CapturedValue, ShapeValueOptions, ValueShaping } from './value.js';\nexport { shapeValue, pointerShape, pointerToken, DROPPED, VALUE_RECIPE } from './value.js';\n\nexport type { Digest } from './hash.js';\nexport { digestString, digestBytes, digestValue, digestCombine } from './hash.js';\n\nexport type { AccessibilitySnapshot } from './accessibility.js';\nexport { accessibilitySnapshot } from './accessibility.js';\n\nexport type { ObservationProfile, ProfileId } from './profile.js';\nexport { JSDOM_PROFILE, CHROMIUM_PROFILE, profileById, tierOfProfile } from './profile.js';\n\nexport type { Tier } from './tier.js';\nexport { tierReaches } from './tier.js';\n\nexport type {\n  EnvironmentInputs,\n  EnvironmentKey,\n  EnvironmentDelta,\n  EnvironmentField,\n  Viewport,\n} from './environment.js';\nexport { environmentKey, diffEnvironments } from './environment.js';\n\nexport {\n  INTERVENTIONS,\n  SEMANTIC_RECIPE,\n  COLLECT_RECIPE,\n  LAYOUT_RECIPE,\n  RASTER_RECIPE,\n  holdAnimations,\n  pinAnimations,\n  hideCaret,\n  hideScrollbars,\n  hidePresentationalImages,\n  waitForFonts,\n  waitForImages,\n  forTier,\n  conflicts,\n  interventionById,\n  recipeOf,\n  recipeCss,\n  recipeScreenshot,\n  recipeDigest,\n  settleRecipe,\n  describeRecipe,\n} from './stabilize.js';\nexport type {\n  Intervention,\n  Recipe,\n  Trick,\n  ScreenshotOptions,\n  SettleTarget,\n} from './stabilize.js';\n\nexport type { Provenance, OwnerFrame, SourceLocation, StackFrame } from './provenance.js';\nexport { propsDigest, heldDigest, jsxSourceOf, relativizeSource, JSX_SOURCE } from './provenance.js';\nexport type { Holding, HeldCell, HeldValue } from './holding.js';\nexport type { Wiring } from './wiring.js';\nexport { keyedByPosition } from './wiring.js';\n\nexport type {\n  RawCapture,\n  RawNode,\n  RawAria,\n  MatchedRule,\n  Declaration,\n  Rect,\n  SubjectRef,\n  Diagnostic,\n} from './capture.js';\n\nexport type {\n  SemanticSnapshot,\n  SemanticNode,\n  NodePath,\n  StyleProvenanceEntry,\n  IgnoreSite,\n  ComponentHash,\n} from './snapshot.js';\n\nexport { documentDigest, identityDigest } from './document.js';\nexport type {\n  RenderDocument,\n  RenderFrame,\n  FrameElement,\n  RenderResource,\n  RenderIdentity,\n  Raster,\n} from './document.js';\n"]}

package/dist/format/intervention.d.ts

@@ -0,0 +1,87 @@
+/**
+ * What an intervention is, as a shape.
+ *
+ * Beside [`stabilize.ts`](./stabilize.ts), which argues why the set is open and
+ * then fills it. This file is the declaration that argument depends on: an id, a
+ * tier, a property it claims, and the three ways it can reach a page. A trick
+ * from another project is one of these and nothing more, so the shape is worth
+ * reading without reading the tricks.
+ */
+import type { Tier } from './tier.js';
+/** What kind of move it is, for reading a recipe at a glance. */
+export type Trick = 
+/** Puts the page into a known state. */
+'reset'
+/** Stops something that would otherwise keep moving. */
+ | 'hold'
+/** Blocks until something outside the page's control has landed. */
+ | 'wait'
+/** Removes something that is present but must not be measured. */
+ | 'support';
+/** Screenshot options a trick contributes. Narrow on purpose. */
+export interface ScreenshotOptions {
+    readonly animations?: 'disabled';
+    readonly caret?: 'hide';
+}
+/** The page surface a `settle` step may use. Structural, so no driver leaks in. */
+export interface SettleTarget {
+    evaluate<T>(fn: () => T | Promise<T>): Promise<T>;
+}
+/**
+ * The page's globals, as the little of them a settle step needs.
+ *
+ * A settle closure is the one place in `core` that reads a live document, and it
+ * gets away with it because it never runs here: it is handed to
+ * {@link SettleTarget.evaluate}, which ships it into a page. ADR-0001's
+ * enforcement is `core`'s `tsconfig`, which has no `lib.dom` — so writing
+ * `window.document.fonts` is a compile error and this shape is what remains.
+ *
+ * That is a stricter arrangement than the convention it replaced, not a
+ * loophole. Everything a settle step may touch is enumerated here, in one
+ * declaration a reader can check, and a trick that wants more of the DOM has to
+ * widen it in public rather than reach for an ambient global.
+ */
+export interface PageGlobals {
+    readonly document: {
+        readonly fonts?: {
+            readonly ready: Promise<unknown>;
+        };
+        readonly images: ArrayLike<{
+            readonly complete: boolean;
+            readonly currentSrc: string;
+            readonly src: string;
+            loading: string;
+            addEventListener(type: string, listener: () => void, options?: {
+                once?: boolean;
+            }): void;
+        }>;
+    };
+    setTimeout(handler: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+export interface Intervention {
+    /**
+     * Stable identifier, and part of the recipe's digest.
+     *
+     * Renaming one is therefore a new identity, which is correct: a reader
+     * comparing two runs has no way to know that `hold-animations` and
+     * `pause-animations` were the same trick.
+     */
+    readonly id: string;
+    readonly trick: Trick;
+    readonly needs: Tier;
+    /** What it does and what it costs, in one sentence a report can print. */
+    readonly because: string;
+    /**
+     * The property this trick governs.
+     *
+     * Two tricks claiming one subject are in conflict — pinning animations in CSS
+     * while asking the compositor to fast-forward them applies both, and the CSS
+     * wins silently. See {@link conflicts}.
+     */
+    readonly governs: string;
+    readonly css?: string;
+    readonly screenshot?: ScreenshotOptions;
+    readonly settle?: (target: SettleTarget) => Promise<void>;
+}
+//# sourceMappingURL=intervention.d.ts.map

package/dist/format/intervention.js

@@ -0,0 +1,11 @@
+/**
+ * What an intervention is, as a shape.
+ *
+ * Beside [`stabilize.ts`](./stabilize.ts), which argues why the set is open and
+ * then fills it. This file is the declaration that argument depends on: an id, a
+ * tier, a property it claims, and the three ways it can reach a page. A trick
+ * from another project is one of these and nothing more, so the shape is worth
+ * reading without reading the tricks.
+ */
+export {};
+//# sourceMappingURL=intervention.js.map

package/dist/format/intervention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"intervention.js","sourceRoot":"","sources":["../../src/format/intervention.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG","sourcesContent":["/**\n * What an intervention is, as a shape.\n *\n * Beside [`stabilize.ts`](./stabilize.ts), which argues why the set is open and\n * then fills it. This file is the declaration that argument depends on: an id, a\n * tier, a property it claims, and the three ways it can reach a page. A trick\n * from another project is one of these and nothing more, so the shape is worth\n * reading without reading the tricks.\n */\n\nimport type { Tier } from './tier.js';\n\n/** What kind of move it is, for reading a recipe at a glance. */\nexport type Trick =\n  /** Puts the page into a known state. */\n  | 'reset'\n  /** Stops something that would otherwise keep moving. */\n  | 'hold'\n  /** Blocks until something outside the page's control has landed. */\n  | 'wait'\n  /** Removes something that is present but must not be measured. */\n  | 'support';\n\n/** Screenshot options a trick contributes. Narrow on purpose. */\nexport interface ScreenshotOptions {\n  readonly animations?: 'disabled';\n  readonly caret?: 'hide';\n}\n\n/** The page surface a `settle` step may use. Structural, so no driver leaks in. */\nexport interface SettleTarget {\n  evaluate<T>(fn: () => T | Promise<T>): Promise<T>;\n}\n\n/**\n * The page's globals, as the little of them a settle step needs.\n *\n * A settle closure is the one place in `core` that reads a live document, and it\n * gets away with it because it never runs here: it is handed to\n * {@link SettleTarget.evaluate}, which ships it into a page. ADR-0001's\n * enforcement is `core`'s `tsconfig`, which has no `lib.dom` — so writing\n * `window.document.fonts` is a compile error and this shape is what remains.\n *\n * That is a stricter arrangement than the convention it replaced, not a\n * loophole. Everything a settle step may touch is enumerated here, in one\n * declaration a reader can check, and a trick that wants more of the DOM has to\n * widen it in public rather than reach for an ambient global.\n */\nexport interface PageGlobals {\n  readonly document: {\n    readonly fonts?: { readonly ready: Promise<unknown> };\n    readonly images: ArrayLike<{\n      readonly complete: boolean;\n      readonly currentSrc: string;\n      readonly src: string;\n      loading: string;\n      addEventListener(type: string, listener: () => void, options?: { once?: boolean }): void;\n    }>;\n  };\n  setTimeout(handler: () => void, ms: number): unknown;\n  clearTimeout(handle: unknown): void;\n}\n\nexport interface Intervention {\n  /**\n   * Stable identifier, and part of the recipe's digest.\n   *\n   * Renaming one is therefore a new identity, which is correct: a reader\n   * comparing two runs has no way to know that `hold-animations` and\n   * `pause-animations` were the same trick.\n   */\n  readonly id: string;\n  readonly trick: Trick;\n  readonly needs: Tier;\n  /** What it does and what it costs, in one sentence a report can print. */\n  readonly because: string;\n\n  /**\n   * The property this trick governs.\n   *\n   * Two tricks claiming one subject are in conflict — pinning animations in CSS\n   * while asking the compositor to fast-forward them applies both, and the CSS\n   * wins silently. See {@link conflicts}.\n   */\n  readonly governs: string;\n\n  readonly css?: string;\n  readonly screenshot?: ScreenshotOptions;\n  readonly settle?: (target: SettleTarget) => Promise<void>;\n}\n"]}

package/dist/format/profile.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Observation profiles.
+ *
+ * A profile declares what a collector was *capable* of observing, independent of
+ * what it found. This distinction is load-bearing: see ADR-0002. Without it, a
+ * JSDOM snapshot (no layout engine) compared against a Chromium baseline reports
+ * either every rect as "moved to 0x0" or — far worse — reports a real geometry
+ * regression as `unchanged`, because both sides omitted geometry.
+ *
+ * A false `unchanged` is the one failure mode this product must never produce.
+ */
+import type { Tier } from './tier.js';
+/** Dimensions a collector may or may not be able to observe. */
+export interface ObservationProfile {
+    readonly id: ProfileId;
+    /** Roles, accessible names, and ARIA states are resolvable. */
+    readonly ariaTree: boolean;
+    /** Author-declared style is readable (stylesheet rules, inline style). */
+    readonly declaredStyle: boolean;
+    /**
+     * The cascade is fully resolved by a real engine, including relative units,
+     * percentages, and inherited values that depend on layout.
+     */
+    readonly computedStyle: boolean;
+    /** Real box geometry: positions and sizes from a layout engine. */
+    readonly layout: boolean;
+    /** Pixels can be produced. */
+    readonly raster: boolean;
+}
+export type ProfileId = 'jsdom' | 'chromium';
+/**
+ * jest / vitest. Structure, ARIA, and declared style only.
+ *
+ * JSDOM has no layout engine: `getBoundingClientRect()` returns zeros and
+ * `getComputedStyle()` resolves only what was declared. It is not a cheap
+ * approximation of a browser — it is an earlier, different gate that decides
+ * structural and token-band questions in milliseconds, in the unit-test process.
+ */
+export declare const JSDOM_PROFILE: ObservationProfile;
+/** playwright / agent-browser. Everything. */
+export declare const CHROMIUM_PROFILE: ObservationProfile;
+export declare function profileById(id: ProfileId): ObservationProfile;
+/**
+ * The rung a collector with this profile actually stands on.
+ *
+ * Derived rather than declared, because a profile already says what it can
+ * observe and a second field naming a tier is one more thing that can disagree
+ * with the first. Used to charge a collection only for the stabilization tricks
+ * it could see the effect of: jsdom has no layout engine and no animation clock,
+ * so pinning animations and waiting for fonts there is a per-subject cost that
+ * buys a rung that exists to be cheap exactly nothing.
+ *
+ * `raster` is never returned. Whether pixels *can* be produced is a property of
+ * the machine, not of the reading being taken — and a collection is a reading,
+ * so charging it for a caret it will never photograph would be the same mistake
+ * in the other direction.
+ */
+export declare function tierOfProfile(profile: ObservationProfile): Tier;
+//# sourceMappingURL=profile.d.ts.map

package/dist/format/profile.js

@@ -0,0 +1,66 @@
+/**
+ * Observation profiles.
+ *
+ * A profile declares what a collector was *capable* of observing, independent of
+ * what it found. This distinction is load-bearing: see ADR-0002. Without it, a
+ * JSDOM snapshot (no layout engine) compared against a Chromium baseline reports
+ * either every rect as "moved to 0x0" or — far worse — reports a real geometry
+ * regression as `unchanged`, because both sides omitted geometry.
+ *
+ * A false `unchanged` is the one failure mode this product must never produce.
+ */
+/**
+ * jest / vitest. Structure, ARIA, and declared style only.
+ *
+ * JSDOM has no layout engine: `getBoundingClientRect()` returns zeros and
+ * `getComputedStyle()` resolves only what was declared. It is not a cheap
+ * approximation of a browser — it is an earlier, different gate that decides
+ * structural and token-band questions in milliseconds, in the unit-test process.
+ */
+export const JSDOM_PROFILE = {
+    id: 'jsdom',
+    ariaTree: true,
+    declaredStyle: true,
+    computedStyle: false,
+    layout: false,
+    raster: false,
+};
+/** playwright / agent-browser. Everything. */
+export const CHROMIUM_PROFILE = {
+    id: 'chromium',
+    ariaTree: true,
+    declaredStyle: true,
+    computedStyle: true,
+    layout: true,
+    raster: true,
+};
+const PROFILES = {
+    jsdom: JSDOM_PROFILE,
+    chromium: CHROMIUM_PROFILE,
+};
+export function profileById(id) {
+    return PROFILES[id];
+}
+/**
+ * The rung a collector with this profile actually stands on.
+ *
+ * Derived rather than declared, because a profile already says what it can
+ * observe and a second field naming a tier is one more thing that can disagree
+ * with the first. Used to charge a collection only for the stabilization tricks
+ * it could see the effect of: jsdom has no layout engine and no animation clock,
+ * so pinning animations and waiting for fonts there is a per-subject cost that
+ * buys a rung that exists to be cheap exactly nothing.
+ *
+ * `raster` is never returned. Whether pixels *can* be produced is a property of
+ * the machine, not of the reading being taken — and a collection is a reading,
+ * so charging it for a caret it will never photograph would be the same mistake
+ * in the other direction.
+ */
+export function tierOfProfile(profile) {
+    if (profile.layout || profile.computedStyle)
+        return 'layout';
+    if (profile.declaredStyle || profile.ariaTree)
+        return 'semantic';
+    return 'reachability';
+}
+//# sourceMappingURL=profile.js.map

package/dist/format/profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile.js","sourceRoot":"","sources":["../../src/format/profile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA8BH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GAAuB;IAC/C,EAAE,EAAE,OAAO;IACX,QAAQ,EAAE,IAAI;IACd,aAAa,EAAE,IAAI;IACnB,aAAa,EAAE,KAAK;IACpB,MAAM,EAAE,KAAK;IACb,MAAM,EAAE,KAAK;CACd,CAAC;AAEF,8CAA8C;AAC9C,MAAM,CAAC,MAAM,gBAAgB,GAAuB;IAClD,EAAE,EAAE,UAAU;IACd,QAAQ,EAAE,IAAI;IACd,aAAa,EAAE,IAAI;IACnB,aAAa,EAAE,IAAI;IACnB,MAAM,EAAE,IAAI;IACZ,MAAM,EAAE,IAAI;CACb,CAAC;AAEF,MAAM,QAAQ,GAA0C;IACtD,KAAK,EAAE,aAAa;IACpB,QAAQ,EAAE,gBAAgB;CAC3B,CAAC;AAEF,MAAM,UAAU,WAAW,CAAC,EAAa;IACvC,OAAO,QAAQ,CAAC,EAAE,CAAC,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,aAAa,CAAC,OAA2B;IACvD,IAAI,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,aAAa;QAAE,OAAO,QAAQ,CAAC;IAC7D,IAAI,OAAO,CAAC,aAAa,IAAI,OAAO,CAAC,QAAQ;QAAE,OAAO,UAAU,CAAC;IACjE,OAAO,cAAc,CAAC;AACxB,CAAC","sourcesContent":["/**\n * Observation profiles.\n *\n * A profile declares what a collector was *capable* of observing, independent of\n * what it found. This distinction is load-bearing: see ADR-0002. Without it, a\n * JSDOM snapshot (no layout engine) compared against a Chromium baseline reports\n * either every rect as \"moved to 0x0\" or — far worse — reports a real geometry\n * regression as `unchanged`, because both sides omitted geometry.\n *\n * A false `unchanged` is the one failure mode this product must never produce.\n */\n\n\nimport type { Tier } from './tier.js';\n\n/** Dimensions a collector may or may not be able to observe. */\nexport interface ObservationProfile {\n  readonly id: ProfileId;\n\n  /** Roles, accessible names, and ARIA states are resolvable. */\n  readonly ariaTree: boolean;\n\n  /** Author-declared style is readable (stylesheet rules, inline style). */\n  readonly declaredStyle: boolean;\n\n  /**\n   * The cascade is fully resolved by a real engine, including relative units,\n   * percentages, and inherited values that depend on layout.\n   */\n  readonly computedStyle: boolean;\n\n  /** Real box geometry: positions and sizes from a layout engine. */\n  readonly layout: boolean;\n\n  /** Pixels can be produced. */\n  readonly raster: boolean;\n}\n\nexport type ProfileId = 'jsdom' | 'chromium';\n\n/**\n * jest / vitest. Structure, ARIA, and declared style only.\n *\n * JSDOM has no layout engine: `getBoundingClientRect()` returns zeros and\n * `getComputedStyle()` resolves only what was declared. It is not a cheap\n * approximation of a browser — it is an earlier, different gate that decides\n * structural and token-band questions in milliseconds, in the unit-test process.\n */\nexport const JSDOM_PROFILE: ObservationProfile = {\n  id: 'jsdom',\n  ariaTree: true,\n  declaredStyle: true,\n  computedStyle: false,\n  layout: false,\n  raster: false,\n};\n\n/** playwright / agent-browser. Everything. */\nexport const CHROMIUM_PROFILE: ObservationProfile = {\n  id: 'chromium',\n  ariaTree: true,\n  declaredStyle: true,\n  computedStyle: true,\n  layout: true,\n  raster: true,\n};\n\nconst PROFILES: Record<ProfileId, ObservationProfile> = {\n  jsdom: JSDOM_PROFILE,\n  chromium: CHROMIUM_PROFILE,\n};\n\nexport function profileById(id: ProfileId): ObservationProfile {\n  return PROFILES[id];\n}\n\n/**\n * The rung a collector with this profile actually stands on.\n *\n * Derived rather than declared, because a profile already says what it can\n * observe and a second field naming a tier is one more thing that can disagree\n * with the first. Used to charge a collection only for the stabilization tricks\n * it could see the effect of: jsdom has no layout engine and no animation clock,\n * so pinning animations and waiting for fonts there is a per-subject cost that\n * buys a rung that exists to be cheap exactly nothing.\n *\n * `raster` is never returned. Whether pixels *can* be produced is a property of\n * the machine, not of the reading being taken — and a collection is a reading,\n * so charging it for a caret it will never photograph would be the same mistake\n * in the other direction.\n */\nexport function tierOfProfile(profile: ObservationProfile): Tier {\n  if (profile.layout || profile.computedStyle) return 'layout';\n  if (profile.declaredStyle || profile.ariaTree) return 'semantic';\n  return 'reachability';\n}\n"]}