@variance-authority/core 0.1.0

package/dist/format/stabilize.js

@@ -0,0 +1,333 @@
+import { digestValue } from './hash.js';
+import { tierReaches } from './tier.js';
+/**
+ * Hand animations to the browser rather than emulating the hold in CSS.
+ *
+ * A browser disabling animations for a screenshot fast-forwards a finite
+ * animation to completion — the state a user comes to rest on — and cancels an
+ * infinite one to its initial frame, replaying it afterwards. That is the
+ * behaviour worth having, and CSS cannot express it.
+ */
+export const holdAnimations = {
+    id: 'hold-animations',
+    trick: 'hold',
+    needs: 'layout',
+    governs: 'animations',
+    because: 'animations settled by the browser: finite fast-forwarded, infinite reset',
+    screenshot: { animations: 'disabled' },
+};
+/**
+ * The same intent without a browser that can do it, and it is not equivalent.
+ *
+ * Pins every animation at its first frame, so a fade-in is captured at the
+ * moment it is invisible. `animation: none` is avoided deliberately — removing
+ * an animation drops whatever layout its keyframes contribute, which changes the
+ * page rather than stopping it.
+ */
+export const pinAnimations = {
+    id: 'pin-animations',
+    trick: 'hold',
+    needs: 'layout',
+    governs: 'animations',
+    because: 'animations pinned at their first frame, which is not where a user sees them',
+    css: '*,*::before,*::after{' +
+        'animation-play-state:paused !important;' +
+        'animation-delay:-0.0001s !important;' +
+        'transition-duration:0s !important;' +
+        'transition-delay:0s !important;' +
+        'scroll-behavior:auto !important}',
+};
+export const hideCaret = {
+    id: 'hide-caret',
+    trick: 'support',
+    // A caret paints and does not lay out, so a tier that never rasterizes cannot
+    // see it and must not pay to hide it.
+    needs: 'raster',
+    governs: 'caret',
+    because: 'text caret hidden, because it blinks on its own schedule',
+    screenshot: { caret: 'hide' },
+};
+export const hideScrollbars = {
+    id: 'hide-scrollbars',
+    trick: 'support',
+    needs: 'layout',
+    governs: 'scrollbars',
+    because: 'scrollbars hidden, removing a platform and preference difference — and their width',
+    css: '*{scrollbar-width:none !important}\n*::-webkit-scrollbar{display:none !important}',
+};
+/**
+ * Drop the pixels of images the page itself called decorative, keeping their boxes.
+ *
+ * The other half of blanking, and it lives here because of what it needs to
+ * know. A driver rewriting responses (`@variance-authority/playwright`'s
+ * `blank` rules) can decide by URL and by intrinsic size, which answers "every
+ * illustration over 40,000 pixels" and answers it before the bytes are even
+ * fetched. It cannot answer `role="presentation"`, because a request carries no
+ * idea which element wanted it — that fact exists only in the document, so the
+ * trick that uses it is a stylesheet.
+ *
+ * `visibility:hidden` rather than `display:none`, and the distinction is the
+ * entire design: a hidden element still occupies exactly the box it would have,
+ * so a page whose column height comes from an image's intrinsic size is
+ * unchanged. `display:none` would collapse it and report a layout regression
+ * this tool caused.
+ *
+ * **Opt-in, and it belongs in no default recipe.** Every other trick here
+ * removes something that is not part of the assertion — a caret, a scrollbar, an
+ * animation mid-flight. This one removes page content, which is a judgement
+ * about what a suite is for, and a default that quietly stopped watching every
+ * `alt=""` image would hide real regressions under a green run.
+ */
+export const hidePresentationalImages = {
+    id: 'hide-presentational-images',
+    trick: 'support',
+    // `layout` rather than `raster`, and the difference is whether it runs at all.
+    // A raster-tier trick is filtered out of every *collection* — `tierOfProfile`
+    // never returns `raster` — so it would only reach a page through a renderer
+    // option, which is not where an operator configures their suite. A collection
+    // sheet is in force when the document is serialized, so hiding it here is what
+    // makes the pixels absent from the render.
+    needs: 'layout',
+    governs: 'presentational-images',
+    because: 'images the page marked decorative hidden, keeping their boxes — real changes inside them ' +
+        'are not reported',
+    css: 'img[role="presentation"],img[alt=""],[role="presentation"] img,[role="none"] img' +
+        '{visibility:hidden !important}',
+};
+export const waitForFonts = {
+    id: 'wait-for-fonts',
+    trick: 'wait',
+    needs: 'layout',
+    governs: 'fonts',
+    because: 'waited for web fonts, whose advances change every metric on the page',
+    // Written without a module-scope helper on purpose: a settle closure is
+    // shipped to a page as source text, so anything it names by identifier is a
+    // `ReferenceError` on the far side. Types are erased and therefore free.
+    settle: async (target) => {
+        await target.evaluate(async () => {
+            const view = globalThis;
+            await view.document.fonts?.ready;
+        });
+    },
+};
+export const waitForImages = {
+    id: 'wait-for-images',
+    trick: 'wait',
+    needs: 'layout',
+    governs: 'images',
+    because: 'waited for images to decode, since their intrinsic size participates in layout, and asked ' +
+        'for the ones the browser had deferred',
+    settle: async (target) => {
+        await target.evaluate(async () => {
+            const view = globalThis;
+            const pending = Array.from(view.document.images).filter((image) => !image.complete);
+            const arrived = Promise.all(pending.map((image) => new Promise((resolve) => {
+                image.addEventListener('load', () => resolve(), { once: true });
+                image.addEventListener('error', () => resolve(), { once: true });
+            })));
+            // Asked for, after the listeners are attached and before anything is
+            // awaited. A `loading="lazy"` image outside the viewport has not been
+            // requested and will not be until something scrolls, so waiting on it is
+            // waiting for a decision the browser has already taken the other way.
+            //
+            // This is the same act as pinning an animation, not a different kind of
+            // thing: what the page shows stops depending on where the viewport
+            // happens to be. It matters most for the readings that need it most — a
+            // full-page capture of a long page is exactly the case where most of the
+            // images are deferred, and photographing it without them yields a picture
+            // full of empty boxes whose contents change with the browser's loading
+            // heuristics rather than with the product.
+            const asServed = pending.map((image) => image.loading);
+            for (const image of pending)
+                image.loading = 'eager';
+            // Bounded, and it throws when the bound is reached.
+            //
+            // A response can stall: a CDN that never answers, an image endpoint that
+            // deadlocks under its own concurrency, an image the browser deferred and
+            // will not request from where the page is scrolled. None of those fire
+            // `load` and none fire `error`, so an unbounded wait turns one stuck
+            // request into a run that never ends and never says why — not a wrong
+            // answer, no answer.
+            //
+            // Giving up quietly would be worse than the hang in a subtler way: it
+            // photographs a page with holes in it and reports the holes as a change,
+            // inventing a regression out of the network this trick exists to hold
+            // still. Refused instead, naming what it was still waiting for, because
+            // "these two never answered" is a finding about the application.
+            //
+            // The bound is written twice — once as the delay, once in the sentence —
+            // because a settle closure is shipped to the page as source text and a
+            // constant it named would be a `ReferenceError` on the far side.
+            // Held so the loser can be cancelled. A timer left to fire after the
+            // images arrived rejects a promise nothing is waiting on any more, which
+            // the page reports as an unhandled rejection — this trick's own noise,
+            // arriving in the console of every subject it succeeded on.
+            let timer;
+            const expired = new Promise((_, reject) => {
+                timer = view.setTimeout(() => {
+                    const stuck = pending.filter((image) => !image.complete);
+                    reject(new Error(`${stuck.length} image(s) had not loaded after 15000ms, and neither answered ` +
+                        `nor failed: ${stuck.map((image) => image.currentSrc || image.src).join(', ')}`));
+                }, 15000);
+            });
+            try {
+                await Promise.race([arrived, expired]);
+            }
+            finally {
+                view.clearTimeout(timer);
+                // Put back, because the trick has to be invisible to the tier that
+                // reads the page after it. `loading` is a reflected attribute, so a
+                // document whose deferred images were switched to `eager` and left that
+                // way is a document that no longer matches the one the product served —
+                // and which images were still undecoded when this ran is a question
+                // about the network, so the edit lands in some readings and not others.
+                // Left in, it makes the same page at two widths disagree about its own
+                // markup: this trick filed as a finding against the application.
+                for (let index = 0; index < pending.length; index += 1) {
+                    pending[index].loading = asServed[index];
+                }
+            }
+        });
+    },
+};
+export const INTERVENTIONS = [
+    holdAnimations,
+    pinAnimations,
+    hideCaret,
+    hideScrollbars,
+    hidePresentationalImages,
+    waitForFonts,
+    waitForImages,
+];
+/**
+ * Nothing at all, and correct for the tier that reads structure and declared style.
+ *
+ * A font that has not loaded cannot change which rules match or what they
+ * declare; an image that has not decoded cannot either. Waiting for both before
+ * a structure-and-style hash buys nothing and costs the wait per subject, on the
+ * rung the tier ladder exists to make cheap.
+ */
+export const SEMANTIC_RECIPE = [];
+export const LAYOUT_RECIPE = [holdAnimations, hideScrollbars, waitForFonts, waitForImages];
+export const RASTER_RECIPE = [...LAYOUT_RECIPE, hideCaret];
+/**
+ * What is applied to a live page *before a subject is observed*, as opposed to
+ * before it is painted.
+ *
+ * The two are different recipes and it is not a preference. {@link
+ * holdAnimations} is a *screenshot option* — it asks the browser to settle
+ * animations for the image it is about to take — and there is no screenshot at
+ * collection time, so it would be a trick that silently does nothing. The CSS
+ * variant is the one that works where nobody is holding a camera, which is the
+ * whole reason both exist as separate values rather than as one switch.
+ *
+ * ## Why the cheap tier needs this at all
+ *
+ * The claim in [`ruleset.ts`](../rules/ruleset.ts) that `transition-*` and
+ * `animation-*` "describe a journey the snapshot does not contain" is only true
+ * if the snapshot is taken with the journey stopped. `transform`, `opacity`,
+ * `filter`, `color` and every geometric longhand *are* admitted, and an
+ * animation in flight moves all of them — so an unstabilized collection turns a
+ * 300ms fade into a component-attributed regression with a real file name on it,
+ * which is worse than an unexplained pixel diff because it is credible.
+ *
+ * Filtered by {@link forTier}, so jsdom applies none of it: with no layout
+ * engine and no animation clock there is nothing to hold still, and paying a
+ * `fonts.ready` wait per subject on the rung that exists to be cheap is exactly
+ * the trade {@link SEMANTIC_RECIPE} refuses.
+ */
+export const COLLECT_RECIPE = [
+    pinAnimations,
+    hideScrollbars,
+    waitForFonts,
+    waitForImages,
+];
+/**
+ * Resolve a trick by the name a caller wrote down.
+ *
+ * The boundary a collection recipe crosses is a `page.evaluate`, and an
+ * `Intervention` does not survive it — `settle` is a function. Ids do survive,
+ * and the page holds this same registry, so a recipe travels as the list of
+ * names it is. A name nothing answers to is a caller error worth failing on
+ * rather than a trick to skip quietly: under-stabilizing is how a suite gets a
+ * flake it has already paid to prevent.
+ */
+export function interventionById(id) {
+    return INTERVENTIONS.find((intervention) => intervention.id === id);
+}
+/**
+ * A recipe from the names it travels as.
+ *
+ * Throws on a name nothing answers to, and names it. The quiet alternative —
+ * skip what cannot be resolved — turns a typo in a config into a suite that is
+ * one trick less stable than its operator believes, discovered later as a flake
+ * they have already paid to prevent. Failing here costs one run and one reading
+ * of the message.
+ */
+export function recipeOf(ids) {
+    return ids.map((id) => {
+        const intervention = interventionById(id);
+        if (intervention === undefined) {
+            throw new Error(`no stabilization trick is called \`${id}\`; this build knows ` +
+                INTERVENTIONS.map((known) => `\`${known.id}\``).join(', '));
+        }
+        return intervention;
+    });
+}
+/** Only the tricks a tier can observe the effect of. */
+export function forTier(recipe, tier) {
+    return recipe.filter((intervention) => tierReaches(tier, intervention.needs));
+}
+/**
+ * Tricks in a recipe that claim the same property.
+ *
+ * Returned rather than thrown, so a caller can decide — an override is a
+ * legitimate composition, and silently applying both is not. Two tricks over one
+ * property means one of them wins by accident of ordering, and which one is
+ * invisible in the result.
+ */
+export function conflicts(recipe) {
+    const byProperty = new Map();
+    for (const intervention of recipe) {
+        byProperty.set(intervention.governs, [
+            ...(byProperty.get(intervention.governs) ?? []),
+            intervention.id,
+        ]);
+    }
+    return [...byProperty.entries()]
+        .filter(([, ids]) => ids.length > 1)
+        .map(([governs, ids]) => ({ governs, ids }));
+}
+export function recipeCss(recipe) {
+    return recipe
+        .map((intervention) => intervention.css)
+        .filter((css) => css !== undefined)
+        .join('\n');
+}
+export function recipeScreenshot(recipe) {
+    return recipe.reduce((options, intervention) => ({ ...options, ...intervention.screenshot }), {});
+}
+export async function settleRecipe(recipe, target) {
+    for (const intervention of recipe) {
+        if (intervention.settle !== undefined)
+            await intervention.settle(target);
+    }
+}
+/**
+ * The identity of a recipe.
+ *
+ * Sorted, so the order tricks were composed in does not change the identity —
+ * only which ones are present. Folded into `RenderIdentity`, which is what makes
+ * a cross-recipe comparison report `incomparable` instead of inventing a
+ * component to blame.
+ */
+export function recipeDigest(recipe) {
+    return digestValue(recipe.map((intervention) => intervention.id).sort());
+}
+/** The recipe as a sentence, so the gap between image and product stays visible. */
+export function describeRecipe(recipe) {
+    return recipe.length === 0
+        ? 'the subject was observed untouched'
+        : `the subject was altered to be observable: ${recipe.map((i) => i.because).join('; ')}`;
+}
+//# sourceMappingURL=stabilize.js.map

package/dist/format/stabilize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stabilize.js","sourceRoot":"","sources":["../../src/format/stabilize.ts"],"names":[],"mappings":"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","sourcesContent":["import { digestValue, type Digest } from './hash.js';\nimport { tierReaches, type Tier } from './tier.js';\nimport type { Intervention, PageGlobals, ScreenshotOptions, SettleTarget } from './intervention.js';\n\n/**\n * Interventions as separate, nameable tricks — not a fixed set of switches.\n *\n * A subject that is still changing cannot be compared, so every system of this\n * kind reaches into the page: it holds animations, waits for fonts, hides a\n * caret, suppresses scrollbars. Written as one struct of booleans that becomes a\n * closed vocabulary: adding a trick edits a type every caller depends on, and a\n * project with a need nobody anticipated has to fork.\n *\n * So each is a value. It carries an id, the tier that can actually observe what\n * it fixes, what it costs, and how it is applied — and a *recipe* is any list of\n * them. Two tricks may express the same intent through different mechanisms and\n * remain separate values, because they produce different images and choosing\n * between them is the caller's business.\n *\n * ## What this buys\n *\n * A recipe can be filtered by tier, so the structure-and-style rung waits for\n * nothing; composed from another project's tricks alongside these; digested, so\n * a baseline made under one recipe is `incomparable` with a run made under\n * another rather than `changed`; and checked for tricks that fight each other.\n *\n * ## Where the damage lands\n *\n * Ordered by increasing cost, earliest sufficient option first:\n *\n * - **Outside the subject** — injected CSS, browser screenshot options. Nothing\n *   in the product imports it and deleting the tool deletes the intervention.\n * - **Runtime substitution** — wrapping `Promise`, replacing a suspense\n *   boundary. Buys the same knowledge without touching a component and is\n *   deliberately not shipped here: it moves the damage from design into\n *   semantics, where a difference caused by the patch cannot be told apart from\n *   a difference caused by the code. Expressible as a trick if a project decides\n *   the trade is worth it — that is the point of an open set.\n * - **A contract the subject implements** — a readiness marker. Real design\n *   damage, and reserved for what the outside genuinely cannot know.\n *\n * ## Why this is in `format` and not in the raster package\n *\n * It was in `@variance-authority/raster` until 2026-08-06, on the reading that\n * holding a page still is something you do before you photograph it. That\n * reading was wrong in a way that cost correctness: an animation in flight is a\n * *computed style value*, so it reaches the cheap representation too — and the\n * allowlist excludes `animation-*` and `transition-*` precisely because it\n * assumed a snapshot is taken with animation already disabled. Nothing disabled\n * it. See {@link COLLECT_RECIPE} and ADR-0028.\n *\n * So a recipe is a render input on every tier, `EnvironmentInputs` carries its\n * digest, and the vocabulary belongs beside the key it is part of.\n */\n\n// Re-exported from here because this is where a reader arrives looking for the\n// vocabulary; [`intervention.ts`](./intervention.js) holds the declaration.\nexport type { Intervention, ScreenshotOptions, SettleTarget, Trick } from './intervention.js';\n\n/**\n * Hand animations to the browser rather than emulating the hold in CSS.\n *\n * A browser disabling animations for a screenshot fast-forwards a finite\n * animation to completion — the state a user comes to rest on — and cancels an\n * infinite one to its initial frame, replaying it afterwards. That is the\n * behaviour worth having, and CSS cannot express it.\n */\nexport const holdAnimations: Intervention = {\n  id: 'hold-animations',\n  trick: 'hold',\n  needs: 'layout',\n  governs: 'animations',\n  because: 'animations settled by the browser: finite fast-forwarded, infinite reset',\n  screenshot: { animations: 'disabled' },\n};\n\n/**\n * The same intent without a browser that can do it, and it is not equivalent.\n *\n * Pins every animation at its first frame, so a fade-in is captured at the\n * moment it is invisible. `animation: none` is avoided deliberately — removing\n * an animation drops whatever layout its keyframes contribute, which changes the\n * page rather than stopping it.\n */\nexport const pinAnimations: Intervention = {\n  id: 'pin-animations',\n  trick: 'hold',\n  needs: 'layout',\n  governs: 'animations',\n  because: 'animations pinned at their first frame, which is not where a user sees them',\n  css:\n    '*,*::before,*::after{' +\n    'animation-play-state:paused !important;' +\n    'animation-delay:-0.0001s !important;' +\n    'transition-duration:0s !important;' +\n    'transition-delay:0s !important;' +\n    'scroll-behavior:auto !important}',\n};\n\nexport const hideCaret: Intervention = {\n  id: 'hide-caret',\n  trick: 'support',\n  // A caret paints and does not lay out, so a tier that never rasterizes cannot\n  // see it and must not pay to hide it.\n  needs: 'raster',\n  governs: 'caret',\n  because: 'text caret hidden, because it blinks on its own schedule',\n  screenshot: { caret: 'hide' },\n};\n\nexport const hideScrollbars: Intervention = {\n  id: 'hide-scrollbars',\n  trick: 'support',\n  needs: 'layout',\n  governs: 'scrollbars',\n  because: 'scrollbars hidden, removing a platform and preference difference — and their width',\n  css: '*{scrollbar-width:none !important}\\n*::-webkit-scrollbar{display:none !important}',\n};\n\n/**\n * Drop the pixels of images the page itself called decorative, keeping their boxes.\n *\n * The other half of blanking, and it lives here because of what it needs to\n * know. A driver rewriting responses (`@variance-authority/playwright`'s\n * `blank` rules) can decide by URL and by intrinsic size, which answers \"every\n * illustration over 40,000 pixels\" and answers it before the bytes are even\n * fetched. It cannot answer `role=\"presentation\"`, because a request carries no\n * idea which element wanted it — that fact exists only in the document, so the\n * trick that uses it is a stylesheet.\n *\n * `visibility:hidden` rather than `display:none`, and the distinction is the\n * entire design: a hidden element still occupies exactly the box it would have,\n * so a page whose column height comes from an image's intrinsic size is\n * unchanged. `display:none` would collapse it and report a layout regression\n * this tool caused.\n *\n * **Opt-in, and it belongs in no default recipe.** Every other trick here\n * removes something that is not part of the assertion — a caret, a scrollbar, an\n * animation mid-flight. This one removes page content, which is a judgement\n * about what a suite is for, and a default that quietly stopped watching every\n * `alt=\"\"` image would hide real regressions under a green run.\n */\nexport const hidePresentationalImages: Intervention = {\n  id: 'hide-presentational-images',\n  trick: 'support',\n  // `layout` rather than `raster`, and the difference is whether it runs at all.\n  // A raster-tier trick is filtered out of every *collection* — `tierOfProfile`\n  // never returns `raster` — so it would only reach a page through a renderer\n  // option, which is not where an operator configures their suite. A collection\n  // sheet is in force when the document is serialized, so hiding it here is what\n  // makes the pixels absent from the render.\n  needs: 'layout',\n  governs: 'presentational-images',\n  because:\n    'images the page marked decorative hidden, keeping their boxes — real changes inside them ' +\n    'are not reported',\n  css:\n    'img[role=\"presentation\"],img[alt=\"\"],[role=\"presentation\"] img,[role=\"none\"] img' +\n    '{visibility:hidden !important}',\n};\n\nexport const waitForFonts: Intervention = {\n  id: 'wait-for-fonts',\n  trick: 'wait',\n  needs: 'layout',\n  governs: 'fonts',\n  because: 'waited for web fonts, whose advances change every metric on the page',\n  // Written without a module-scope helper on purpose: a settle closure is\n  // shipped to a page as source text, so anything it names by identifier is a\n  // `ReferenceError` on the far side. Types are erased and therefore free.\n  settle: async (target) => {\n    await target.evaluate(async () => {\n      const view = globalThis as unknown as PageGlobals;\n      await view.document.fonts?.ready;\n    });\n  },\n};\n\nexport const waitForImages: Intervention = {\n  id: 'wait-for-images',\n  trick: 'wait',\n  needs: 'layout',\n  governs: 'images',\n  because:\n    'waited for images to decode, since their intrinsic size participates in layout, and asked ' +\n    'for the ones the browser had deferred',\n  settle: async (target) => {\n    await target.evaluate(async () => {\n      const view = globalThis as unknown as PageGlobals;\n      const pending = Array.from(view.document.images).filter((image) => !image.complete);\n\n      const arrived = Promise.all(\n        pending.map(\n          (image) =>\n            new Promise<void>((resolve) => {\n              image.addEventListener('load', () => resolve(), { once: true });\n              image.addEventListener('error', () => resolve(), { once: true });\n            }),\n        ),\n      );\n\n      // Asked for, after the listeners are attached and before anything is\n      // awaited. A `loading=\"lazy\"` image outside the viewport has not been\n      // requested and will not be until something scrolls, so waiting on it is\n      // waiting for a decision the browser has already taken the other way.\n      //\n      // This is the same act as pinning an animation, not a different kind of\n      // thing: what the page shows stops depending on where the viewport\n      // happens to be. It matters most for the readings that need it most — a\n      // full-page capture of a long page is exactly the case where most of the\n      // images are deferred, and photographing it without them yields a picture\n      // full of empty boxes whose contents change with the browser's loading\n      // heuristics rather than with the product.\n      const asServed = pending.map((image) => image.loading);\n      for (const image of pending) image.loading = 'eager';\n\n      // Bounded, and it throws when the bound is reached.\n      //\n      // A response can stall: a CDN that never answers, an image endpoint that\n      // deadlocks under its own concurrency, an image the browser deferred and\n      // will not request from where the page is scrolled. None of those fire\n      // `load` and none fire `error`, so an unbounded wait turns one stuck\n      // request into a run that never ends and never says why — not a wrong\n      // answer, no answer.\n      //\n      // Giving up quietly would be worse than the hang in a subtler way: it\n      // photographs a page with holes in it and reports the holes as a change,\n      // inventing a regression out of the network this trick exists to hold\n      // still. Refused instead, naming what it was still waiting for, because\n      // \"these two never answered\" is a finding about the application.\n      //\n      // The bound is written twice — once as the delay, once in the sentence —\n      // because a settle closure is shipped to the page as source text and a\n      // constant it named would be a `ReferenceError` on the far side.\n      // Held so the loser can be cancelled. A timer left to fire after the\n      // images arrived rejects a promise nothing is waiting on any more, which\n      // the page reports as an unhandled rejection — this trick's own noise,\n      // arriving in the console of every subject it succeeded on.\n      let timer: unknown;\n\n      const expired = new Promise<never>((_, reject) => {\n        timer = view.setTimeout(() => {\n          const stuck = pending.filter((image) => !image.complete);\n          reject(\n            new Error(\n              `${stuck.length} image(s) had not loaded after 15000ms, and neither answered ` +\n                `nor failed: ${stuck.map((image) => image.currentSrc || image.src).join(', ')}`,\n            ),\n          );\n        }, 15000);\n      });\n\n      try {\n        await Promise.race([arrived, expired]);\n      } finally {\n        view.clearTimeout(timer);\n\n        // Put back, because the trick has to be invisible to the tier that\n        // reads the page after it. `loading` is a reflected attribute, so a\n        // document whose deferred images were switched to `eager` and left that\n        // way is a document that no longer matches the one the product served —\n        // and which images were still undecoded when this ran is a question\n        // about the network, so the edit lands in some readings and not others.\n        // Left in, it makes the same page at two widths disagree about its own\n        // markup: this trick filed as a finding against the application.\n        for (let index = 0; index < pending.length; index += 1) {\n          pending[index]!.loading = asServed[index]!;\n        }\n      }\n    });\n  },\n};\n\nexport const INTERVENTIONS: readonly Intervention[] = [\n  holdAnimations,\n  pinAnimations,\n  hideCaret,\n  hideScrollbars,\n  hidePresentationalImages,\n  waitForFonts,\n  waitForImages,\n];\n\nexport type Recipe = readonly Intervention[];\n\n/**\n * Nothing at all, and correct for the tier that reads structure and declared style.\n *\n * A font that has not loaded cannot change which rules match or what they\n * declare; an image that has not decoded cannot either. Waiting for both before\n * a structure-and-style hash buys nothing and costs the wait per subject, on the\n * rung the tier ladder exists to make cheap.\n */\nexport const SEMANTIC_RECIPE: Recipe = [];\n\nexport const LAYOUT_RECIPE: Recipe = [holdAnimations, hideScrollbars, waitForFonts, waitForImages];\n\nexport const RASTER_RECIPE: Recipe = [...LAYOUT_RECIPE, hideCaret];\n\n/**\n * What is applied to a live page *before a subject is observed*, as opposed to\n * before it is painted.\n *\n * The two are different recipes and it is not a preference. {@link\n * holdAnimations} is a *screenshot option* — it asks the browser to settle\n * animations for the image it is about to take — and there is no screenshot at\n * collection time, so it would be a trick that silently does nothing. The CSS\n * variant is the one that works where nobody is holding a camera, which is the\n * whole reason both exist as separate values rather than as one switch.\n *\n * ## Why the cheap tier needs this at all\n *\n * The claim in [`ruleset.ts`](../rules/ruleset.ts) that `transition-*` and\n * `animation-*` \"describe a journey the snapshot does not contain\" is only true\n * if the snapshot is taken with the journey stopped. `transform`, `opacity`,\n * `filter`, `color` and every geometric longhand *are* admitted, and an\n * animation in flight moves all of them — so an unstabilized collection turns a\n * 300ms fade into a component-attributed regression with a real file name on it,\n * which is worse than an unexplained pixel diff because it is credible.\n *\n * Filtered by {@link forTier}, so jsdom applies none of it: with no layout\n * engine and no animation clock there is nothing to hold still, and paying a\n * `fonts.ready` wait per subject on the rung that exists to be cheap is exactly\n * the trade {@link SEMANTIC_RECIPE} refuses.\n */\nexport const COLLECT_RECIPE: Recipe = [\n  pinAnimations,\n  hideScrollbars,\n  waitForFonts,\n  waitForImages,\n];\n\n/**\n * Resolve a trick by the name a caller wrote down.\n *\n * The boundary a collection recipe crosses is a `page.evaluate`, and an\n * `Intervention` does not survive it — `settle` is a function. Ids do survive,\n * and the page holds this same registry, so a recipe travels as the list of\n * names it is. A name nothing answers to is a caller error worth failing on\n * rather than a trick to skip quietly: under-stabilizing is how a suite gets a\n * flake it has already paid to prevent.\n */\nexport function interventionById(id: string): Intervention | undefined {\n  return INTERVENTIONS.find((intervention) => intervention.id === id);\n}\n\n/**\n * A recipe from the names it travels as.\n *\n * Throws on a name nothing answers to, and names it. The quiet alternative —\n * skip what cannot be resolved — turns a typo in a config into a suite that is\n * one trick less stable than its operator believes, discovered later as a flake\n * they have already paid to prevent. Failing here costs one run and one reading\n * of the message.\n */\nexport function recipeOf(ids: readonly string[]): Recipe {\n  return ids.map((id) => {\n    const intervention = interventionById(id);\n    if (intervention === undefined) {\n      throw new Error(\n        `no stabilization trick is called \\`${id}\\`; this build knows ` +\n          INTERVENTIONS.map((known) => `\\`${known.id}\\``).join(', '),\n      );\n    }\n    return intervention;\n  });\n}\n\n/** Only the tricks a tier can observe the effect of. */\nexport function forTier(recipe: Recipe, tier: Tier): Recipe {\n  return recipe.filter((intervention) => tierReaches(tier, intervention.needs));\n}\n\n/**\n * Tricks in a recipe that claim the same property.\n *\n * Returned rather than thrown, so a caller can decide — an override is a\n * legitimate composition, and silently applying both is not. Two tricks over one\n * property means one of them wins by accident of ordering, and which one is\n * invisible in the result.\n */\nexport function conflicts(recipe: Recipe): readonly { governs: string; ids: readonly string[] }[] {\n  const byProperty = new Map<string, string[]>();\n\n  for (const intervention of recipe) {\n    byProperty.set(intervention.governs, [\n      ...(byProperty.get(intervention.governs) ?? []),\n      intervention.id,\n    ]);\n  }\n\n  return [...byProperty.entries()]\n    .filter(([, ids]) => ids.length > 1)\n    .map(([governs, ids]) => ({ governs, ids }));\n}\n\nexport function recipeCss(recipe: Recipe): string {\n  return recipe\n    .map((intervention) => intervention.css)\n    .filter((css): css is string => css !== undefined)\n    .join('\\n');\n}\n\nexport function recipeScreenshot(recipe: Recipe): ScreenshotOptions {\n  return recipe.reduce<ScreenshotOptions>(\n    (options, intervention) => ({ ...options, ...intervention.screenshot }),\n    {},\n  );\n}\n\nexport async function settleRecipe(recipe: Recipe, target: SettleTarget): Promise<void> {\n  for (const intervention of recipe) {\n    if (intervention.settle !== undefined) await intervention.settle(target);\n  }\n}\n\n/**\n * The identity of a recipe.\n *\n * Sorted, so the order tricks were composed in does not change the identity —\n * only which ones are present. Folded into `RenderIdentity`, which is what makes\n * a cross-recipe comparison report `incomparable` instead of inventing a\n * component to blame.\n */\nexport function recipeDigest(recipe: Recipe): Digest {\n  return digestValue(recipe.map((intervention) => intervention.id).sort());\n}\n\n/** The recipe as a sentence, so the gap between image and product stays visible. */\nexport function describeRecipe(recipe: Recipe): string {\n  return recipe.length === 0\n    ? 'the subject was observed untouched'\n    : `the subject was altered to be observable: ${recipe.map((i) => i.because).join('; ')}`;\n}\n"]}

package/dist/format/tier.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The cheapest representation that can answer a question.
+ *
+ * Ordered, and the order is the cost. Everything in this project that says "do
+ * not pay for what this rung cannot observe" says it with this type: a tool
+ * declares the rung it needs and a plan running lower is told which of its tools
+ * cannot do their job; a stabilization trick declares the rung that can observe
+ * what it fixes, so the structure-and-style rung waits for no fonts.
+ *
+ * It lives in `format` rather than in `plan` because two different groups need
+ * it and `format` is the one both may depend on. It was in `plan` until
+ * 2026-08-06, when the stabilization vocabulary moved into `format` and brought
+ * a second, separately-declared four-value union with it — two copies of a
+ * ladder that must not drift.
+ */
+export type Tier = 'reachability' | 'semantic' | 'layout' | 'raster';
+/** Whether a rung can observe what something declaring `needs` requires. */
+export declare function tierReaches(available: Tier, needs: Tier): boolean;
+//# sourceMappingURL=tier.d.ts.map

package/dist/format/tier.js

@@ -0,0 +1,11 @@
+const TIER_ORDER = {
+    reachability: 0,
+    semantic: 1,
+    layout: 2,
+    raster: 3,
+};
+/** Whether a rung can observe what something declaring `needs` requires. */
+export function tierReaches(available, needs) {
+    return TIER_ORDER[needs] <= TIER_ORDER[available];
+}
+//# sourceMappingURL=tier.js.map

package/dist/format/tier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tier.js","sourceRoot":"","sources":["../../src/format/tier.ts"],"names":[],"mappings":"AAiBA,MAAM,UAAU,GAAyB;IACvC,YAAY,EAAE,CAAC;IACf,QAAQ,EAAE,CAAC;IACX,MAAM,EAAE,CAAC;IACT,MAAM,EAAE,CAAC;CACV,CAAC;AAEF,4EAA4E;AAC5E,MAAM,UAAU,WAAW,CAAC,SAAe,EAAE,KAAW;IACtD,OAAO,UAAU,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,SAAS,CAAC,CAAC;AACpD,CAAC","sourcesContent":["/**\n * The cheapest representation that can answer a question.\n *\n * Ordered, and the order is the cost. Everything in this project that says \"do\n * not pay for what this rung cannot observe\" says it with this type: a tool\n * declares the rung it needs and a plan running lower is told which of its tools\n * cannot do their job; a stabilization trick declares the rung that can observe\n * what it fixes, so the structure-and-style rung waits for no fonts.\n *\n * It lives in `format` rather than in `plan` because two different groups need\n * it and `format` is the one both may depend on. It was in `plan` until\n * 2026-08-06, when the stabilization vocabulary moved into `format` and brought\n * a second, separately-declared four-value union with it — two copies of a\n * ladder that must not drift.\n */\nexport type Tier = 'reachability' | 'semantic' | 'layout' | 'raster';\n\nconst TIER_ORDER: Record<Tier, number> = {\n  reachability: 0,\n  semantic: 1,\n  layout: 2,\n  raster: 3,\n};\n\n/** Whether a rung can observe what something declaring `needs` requires. */\nexport function tierReaches(available: Tier, needs: Tier): boolean {\n  return TIER_ORDER[needs] <= TIER_ORDER[available];\n}\n"]}

package/dist/format/value.d.ts

@@ -0,0 +1,115 @@
+import { type Digest } 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 declare const VALUE_RECIPE = "value/1";
+/** What a dropped value becomes. Present in the text, never compared. */
+export declare const DROPPED = "[dropped]";
+/** What a value capture looks like once it has been shaped. */
+export interface CapturedValue {
+    /** How to read the text: `json`, `openapi`, `graphql`, `route-table`. */
+    readonly dialect: string;
+    /** The canonical serialization — byte for byte what the digest was taken over. */
+    readonly text: string;
+    readonly digest: Digest;
+    /** The shaping rules this text was produced under. {@link VALUE_RECIPE}. */
+    readonly recipe: string;
+    /**
+     * The arrays this text was keyed by, as wildcarded pointers.
+     *
+     * A keyed array is an object whose members are named by a row's identity, so
+     * `/rows/checkout` is a *row* and `/rows/total` might not be. Carried because
+     * nothing downstream can tell those apart by looking, and a comparison that
+     * guessed would either group two unrelated members or fail to group the same
+     * edit made to two rows.
+     */
+    readonly keyed?: readonly string[];
+    /** What emitted it. The environment key for this material, when there is one. */
+    readonly generator?: {
+        readonly name: string;
+        readonly version: string;
+    };
+}
+/**
+ * What to do to a value before it is canonicalized.
+ *
+ * Every key is a JSON Pointer (RFC 6901) into the value. A `-` token matches any
+ * array index, so `/items/-/updatedAt` names that member of every item — the
+ * concrete pointer and the wildcarded one are both offered to the rules, so a
+ * literal `/items/0/updatedAt` still names exactly one.
+ */
+export interface ValueShaping {
+    /**
+     * Paths whose values are volatile.
+     *
+     * Recorded as {@link DROPPED} rather than removed, because *this key is here
+     * and I chose not to look at it* and *this key is gone* are different facts and
+     * a comparison must not collapse them.
+     */
+    readonly drop?: readonly string[];
+    /** Paths whose values become a stable token of the adopter's choosing. */
+    readonly replace?: Readonly<Record<string, string>>;
+    /**
+     * For an array of records, the member that identifies a row.
+     *
+     * Load-bearing, and not a convenience. An array compared by index reports a row
+     * inserted at the top of a two-thousand-row list as two thousand rows having
+     * changed — the same failure as forty red screenshots for one edit, in a medium
+     * where nobody can see it at a glance. Keyed, the array becomes an object, so
+     * order stops being a fact about it and an insertion is one addition.
+     */
+    readonly arrayKey?: Readonly<Record<string, string>>;
+}
+export interface ShapeValueOptions extends ValueShaping {
+    /** Defaults to `json`. */
+    readonly dialect?: string;
+    readonly generator?: {
+        readonly name: string;
+        readonly version: string;
+    };
+}
+/**
+ * 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 declare function shapeValue(value: unknown, options?: ShapeValueOptions): CapturedValue;
+/** RFC 6901: `~` becomes `~0` and `/` becomes `~1`, in that order. */
+export declare function pointerToken(token: string): string;
+/**
+ * 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 declare function pointerShape(pointer: string, keyed?: readonly string[]): string;
+//# sourceMappingURL=value.d.ts.map