@variance-authority/core 0.13.0 → 0.15.0

package/dist/format/stabilize.js

@@ -1,5 +1,8 @@
 import { digestValue } from './hash.js';
 import { tierReaches } from './tier.js';
+import { clockById, freezeClock, freezeClockAt, noFocus, noHover, reducedMotion, UNTOUCHED } from './drive.js';
+import { waitForFonts, waitForImages } from './waits.js';
+export { waitForFonts, waitForImages } from './waits.js';
 /**
  * Hand animations to the browser rather than emulating the hold in CSS.
  *
@@ -109,108 +112,16 @@ export const hidePresentationalImages = {
     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,
+    noHover,
+    noFocus,
+    reducedMotion,
+    freezeClock,
     waitForFonts,
     waitForImages,
 ];
@@ -223,7 +134,18 @@ export const INTERVENTIONS = [
  * rung the tier ladder exists to make cheap.
  */
 export const SEMANTIC_RECIPE = [];
-export const LAYOUT_RECIPE = [holdAnimations, hideScrollbars, waitForFonts, waitForImages];
+// TODO: a `<script>` inside a subject root runs in the render document under the
+// real clock, which no trick in this recipe holds.
+// TODO: a document is painted under this recipe whatever recipe it was read
+// under: a `RenderDocument` carries no collection recipe to follow.
+/**
+ * What a document is painted under, and of {@link UNTOUCHED} only `no-focus`: a
+ * collected `autofocus` takes focus again. The other three have nothing but a
+ * carried script to act on: the printed date and the animation's place are in
+ * the document already, its `@media` rules were resolved when it was read, and
+ * nothing moves the pointer over it.
+ */
+export const LAYOUT_RECIPE = [holdAnimations, hideScrollbars, noFocus, waitForFonts, waitForImages];
 export const RASTER_RECIPE = [...LAYOUT_RECIPE, hideCaret];
 /**
  * What is applied to a live page *before a subject is observed*, as opposed to
@@ -260,9 +182,16 @@ export const COLLECT_RECIPE = [
     // holding a focused input otherwise disagrees with itself between two
     // screenshots taken 600ms apart, and is refused for blinking.
     hideCaret,
+    ...UNTOUCHED,
     waitForFonts,
     waitForImages,
 ];
+/**
+ * The ids of {@link COLLECT_RECIPE}, as an absent `stabilize` means them. A list
+ * replaces the recipe, so one trick is turned off with this list without it:
+ * `stabilize: DEFAULT_STABILIZE.filter((id) => id !== 'freeze-clock')`.
+ */
+export const DEFAULT_STABILIZE = COLLECT_RECIPE.map((intervention) => intervention.id);
 /**
  * Resolve a trick by the name a caller wrote down.
  *
@@ -274,7 +203,7 @@ export const COLLECT_RECIPE = [
  * flake it has already paid to prevent.
  */
 export function interventionById(id) {
-    return INTERVENTIONS.find((intervention) => intervention.id === id);
+    return INTERVENTIONS.find((intervention) => intervention.id === id) ?? clockById(id);
 }
 /**
  * A recipe from the names it travels as.
@@ -290,11 +219,30 @@ export function recipeOf(ids) {
         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(', '));
+                INTERVENTIONS.map((known) => `\`${known.id}\``).join(', ') +
+                ', and `freeze-clock@<instant>`');
         }
         return intervention;
     });
 }
+/**
+ * The recipe a host that drives the browser applies, checked before it opens one:
+ * `stabilize` by id, or {@link COLLECT_RECIPE} when it is absent, with its clock
+ * fixed at `now`, which travels in the clock's id and lands in the digest. Throws
+ * on an unknown id, an instant with no zone, or a `now` with no clock to fix, so
+ * the operator hears about it before a page is loaded, not at the first subject.
+ */
+export function recipeToDrive(options) {
+    const recipe = options.stabilize === undefined ? COLLECT_RECIPE : recipeOf(options.stabilize);
+    if (options.now === undefined)
+        return recipe;
+    const clock = freezeClockAt(options.now);
+    if (!recipe.some((intervention) => intervention.driver?.clock !== undefined)) {
+        throw new Error(`\`now\` is the instant \`freeze-clock\` fixes, and this recipe has no \`freeze-clock\`: ` +
+            'add it to `stabilize`, or leave `now` out');
+    }
+    return recipe.map((intervention) => (intervention.driver?.clock === undefined ? intervention : clock));
+}
 /** Only the tricks a tier can observe the effect of. */
 export function forTier(recipe, tier) {
     return recipe.filter((intervention) => tierReaches(tier, intervention.needs));
@@ -339,7 +287,7 @@ export async function settleRecipe(recipe, target) {
  *
  * 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
+ * a cross-recipe comparison name the recipe as its cause instead of inventing a
  * component to blame.
  */
 export function recipeDigest(recipe) {

package/dist/format/stabilize.js.map

@@ -1 +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\n/**\n * A stylesheet rather than the driver's own caret switch, deliberately.\n *\n * Playwright and its peers hide a caret by writing `caret-color` onto every\n * focusable element and putting it back afterwards, and putting it back leaves\n * `style=\"\"` where there was no `style` attribute at all. Any capture that reads\n * the DOM on both sides of a screenshot — which is what the in-place path does\n * to prove the subject held still — then sees markup that moved, and reports the\n * driver's housekeeping as the page being unstable. A page with one text input\n * is enough.\n *\n * So this hold owns the caret the way {@link pinAnimations} owns animations: one\n * stylesheet, installed before the subject is read, removed with the rest of the\n * recipe.\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  css: '*{caret-color:transparent !important}',\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  // Here as well as in {@link RASTER_RECIPE}, because the in-place path\n  // photographs the live page and applies no screenshot options of its own: the\n  // only caret hold that reaches that image is one installed here. A subject\n  // holding a focused input otherwise disagrees with itself between two\n  // screenshots taken 600ms apart, and is refused for blinking.\n  hideCaret,\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"]}
+{"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 { clockById, freezeClock, freezeClockAt, noFocus, noHover, reducedMotion, UNTOUCHED } from './drive.js';\nimport type { Intervention, ScreenshotOptions, SettleTarget } from './intervention.js';\nimport { waitForFonts, waitForImages } from './waits.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 run under another recipe than its baseline names the recipe as the cause;\n * 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';\nexport { waitForFonts, waitForImages } from './waits.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\n/**\n * A stylesheet rather than the driver's own caret switch, deliberately.\n *\n * Playwright and its peers hide a caret by writing `caret-color` onto every\n * focusable element and putting it back afterwards, and putting it back leaves\n * `style=\"\"` where there was no `style` attribute at all. Any capture that reads\n * the DOM on both sides of a screenshot — which is what the in-place path does\n * to prove the subject held still — then sees markup that moved, and reports the\n * driver's housekeeping as the page being unstable. A page with one text input\n * is enough.\n *\n * So this hold owns the caret the way {@link pinAnimations} owns animations: one\n * stylesheet, installed before the subject is read, removed with the rest of the\n * recipe.\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  css: '*{caret-color:transparent !important}',\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 INTERVENTIONS: readonly Intervention[] = [\n  holdAnimations,\n  pinAnimations,\n  hideCaret,\n  hideScrollbars,\n  hidePresentationalImages,\n  noHover,\n  noFocus,\n  reducedMotion,\n  freezeClock,\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\n// TODO: a `<script>` inside a subject root runs in the render document under the\n// real clock, which no trick in this recipe holds.\n// TODO: a document is painted under this recipe whatever recipe it was read\n// under: a `RenderDocument` carries no collection recipe to follow.\n/**\n * What a document is painted under, and of {@link UNTOUCHED} only `no-focus`: a\n * collected `autofocus` takes focus again. The other three have nothing but a\n * carried script to act on: the printed date and the animation's place are in\n * the document already, its `@media` rules were resolved when it was read, and\n * nothing moves the pointer over it.\n */\nexport const LAYOUT_RECIPE: Recipe = [holdAnimations, hideScrollbars, noFocus, 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  // Here as well as in {@link RASTER_RECIPE}, because the in-place path\n  // photographs the live page and applies no screenshot options of its own: the\n  // only caret hold that reaches that image is one installed here. A subject\n  // holding a focused input otherwise disagrees with itself between two\n  // screenshots taken 600ms apart, and is refused for blinking.\n  hideCaret,\n  ...UNTOUCHED,\n  waitForFonts,\n  waitForImages,\n];\n\n/**\n * The ids of {@link COLLECT_RECIPE}, as an absent `stabilize` means them. A list\n * replaces the recipe, so one trick is turned off with this list without it:\n * `stabilize: DEFAULT_STABILIZE.filter((id) => id !== 'freeze-clock')`.\n */\nexport const DEFAULT_STABILIZE: readonly string[] = COLLECT_RECIPE.map((intervention) => intervention.id);\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) ?? clockById(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          ', and `freeze-clock@<instant>`',\n      );\n    }\n    return intervention;\n  });\n}\n\n/**\n * The recipe a host that drives the browser applies, checked before it opens one:\n * `stabilize` by id, or {@link COLLECT_RECIPE} when it is absent, with its clock\n * fixed at `now`, which travels in the clock's id and lands in the digest. Throws\n * on an unknown id, an instant with no zone, or a `now` with no clock to fix, so\n * the operator hears about it before a page is loaded, not at the first subject.\n */\nexport function recipeToDrive(options: { readonly stabilize?: readonly string[]; readonly now?: string }): Recipe {\n  const recipe = options.stabilize === undefined ? COLLECT_RECIPE : recipeOf(options.stabilize);\n  if (options.now === undefined) return recipe;\n  const clock = freezeClockAt(options.now);\n  if (!recipe.some((intervention) => intervention.driver?.clock !== undefined)) {\n    throw new Error(\n      `\\`now\\` is the instant \\`freeze-clock\\` fixes, and this recipe has no \\`freeze-clock\\`: ` +\n        'add it to `stabilize`, or leave `now` out',\n    );\n  }\n  return recipe.map((intervention) => (intervention.driver?.clock === undefined ? intervention : clock));\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 name the recipe as its cause 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/waits.d.ts

@@ -0,0 +1,12 @@
+import type { Intervention } from './intervention.js';
+/**
+ * The two tricks that block until something outside the page has landed.
+ *
+ * Apart from [`stabilize.ts`](./stabilize.ts) because they are the tricks with
+ * the most page-side code: each ships a closure into the page, bounds its wait at
+ * 15000ms and names what never answered. The rest of the vocabulary is a line of
+ * CSS or a screenshot option.
+ */
+export declare const waitForFonts: Intervention;
+export declare const waitForImages: Intervention;
+//# sourceMappingURL=waits.d.ts.map

package/dist/format/waits.js

@@ -0,0 +1,156 @@
+/**
+ * The two tricks that block until something outside the page has landed.
+ *
+ * Apart from [`stabilize.ts`](./stabilize.ts) because they are the tricks with
+ * the most page-side code: each ships a closure into the page, bounds its wait at
+ * 15000ms and names what never answered. The rest of the vocabulary is a line of
+ * CSS or a screenshot option.
+ */
+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;
+            const fonts = view.document.fonts;
+            if (fonts === undefined)
+                return;
+            // Bounded as `waitForImages` is: a font request that never answers neither
+            // loads nor fails, so `ready` never settles. Refused at the same 15000ms,
+            // naming each face still loading by family and the source its rule asked for.
+            let timer;
+            const expired = new Promise((_, reject) => {
+                timer = view.setTimeout(() => {
+                    const unquoted = (family) => family.trim().replace(/^(["'])(.*)\1$/, '$2');
+                    const sources = new Map();
+                    const visit = (rules) => {
+                        for (const rule of Array.from(rules)) {
+                            if (rule.cssRules !== undefined)
+                                visit(rule.cssRules);
+                            // An `@import` carries its sheet; a cross-origin one hides its rules.
+                            try {
+                                if (rule.styleSheet != null)
+                                    visit(rule.styleSheet.cssRules);
+                            }
+                            catch { }
+                            // Only a `@font-face` rule carries `src`; a style rule reads empty.
+                            const source = rule.style?.getPropertyValue('src') ?? '';
+                            if (source === '')
+                                continue;
+                            const family = unquoted(rule.style.getPropertyValue('font-family'));
+                            sources.set(family, [...(sources.get(family) ?? []), source]);
+                        }
+                    };
+                    for (const sheet of Array.from(view.document.styleSheets)) {
+                        try {
+                            visit(sheet.cssRules);
+                        }
+                        catch {
+                            // A cross-origin sheet hides its rules; its faces are named by family alone.
+                        }
+                    }
+                    const stuck = Array.from(fonts).filter((face) => face.status === 'loading');
+                    const named = stuck.map((face) => {
+                        const asked = sources.get(unquoted(face.family));
+                        return asked === undefined ? face.family : `${face.family} from ${asked.join(' or ')}`;
+                    });
+                    reject(new Error(`${stuck.length} web font(s) had not loaded after 15000ms, and neither answered ` +
+                        `nor failed: ${named.join('; ')}`));
+                }, 15000);
+            });
+            try {
+                await Promise.race([fonts.ready, expired]);
+            }
+            finally {
+                view.clearTimeout(timer);
+            }
+        });
+    },
+};
+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];
+                }
+            }
+        });
+    },
+};
+//# sourceMappingURL=waits.js.map

package/dist/format/waits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"waits.js","sourceRoot":"","sources":["../../src/format/waits.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Intervention, PageGlobals } from './intervention.js';\n\n/**\n * The two tricks that block until something outside the page has landed.\n *\n * Apart from [`stabilize.ts`](./stabilize.ts) because they are the tricks with\n * the most page-side code: each ships a closure into the page, bounds its wait at\n * 15000ms and names what never answered. The rest of the vocabulary is a line of\n * CSS or a screenshot option.\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      const fonts = view.document.fonts;\n      if (fonts === undefined) return;\n      // Bounded as `waitForImages` is: a font request that never answers neither\n      // loads nor fails, so `ready` never settles. Refused at the same 15000ms,\n      // naming each face still loading by family and the source its rule asked for.\n      let timer: unknown;\n      const expired = new Promise<never>((_, reject) => {\n        timer = view.setTimeout(() => {\n          const unquoted = (family: string): string => family.trim().replace(/^([\"'])(.*)\\1$/, '$2');\n          const sources = new Map<string, string[]>();\n          type Rules = PageGlobals['document']['styleSheets'][number]['cssRules'];\n          const visit = (rules: Rules): void => {\n            for (const rule of Array.from(rules)) {\n              if (rule.cssRules !== undefined) visit(rule.cssRules);\n              // An `@import` carries its sheet; a cross-origin one hides its rules.\n              try {\n                if (rule.styleSheet != null) visit(rule.styleSheet.cssRules);\n              } catch {}\n              // Only a `@font-face` rule carries `src`; a style rule reads empty.\n              const source = rule.style?.getPropertyValue('src') ?? '';\n              if (source === '') continue;\n              const family = unquoted(rule.style!.getPropertyValue('font-family'));\n              sources.set(family, [...(sources.get(family) ?? []), source]);\n            }\n          };\n          for (const sheet of Array.from(view.document.styleSheets)) {\n            try {\n              visit(sheet.cssRules);\n            } catch {\n              // A cross-origin sheet hides its rules; its faces are named by family alone.\n            }\n          }\n          const stuck = Array.from(fonts).filter((face) => face.status === 'loading');\n          const named = stuck.map((face) => {\n            const asked = sources.get(unquoted(face.family));\n            return asked === undefined ? face.family : `${face.family} from ${asked.join(' or ')}`;\n          });\n          reject(\n            new Error(\n              `${stuck.length} web font(s) had not loaded after 15000ms, and neither answered ` +\n                `nor failed: ${named.join('; ')}`,\n            ),\n          );\n        }, 15000);\n      });\n      try {\n        await Promise.race([fonts.ready, expired]);\n      } finally {\n        view.clearTimeout(timer);\n      }\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"]}

package/dist/index.d.ts

@@ -21,7 +21,8 @@
  *
  * Every name lives in exactly one of them; nothing is reachable from two paths.
  * This entrypoint holds only what belongs to no group: the artifact a capture is
- * written to.
+ * written to, and the name a refusal offers when one was mistyped.
  */
 export * from './artifact.js';
+export { didYouMean, nearest } from './nearest.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -21,7 +21,8 @@
  *
  * Every name lives in exactly one of them; nothing is reachable from two paths.
  * This entrypoint holds only what belongs to no group: the artifact a capture is
- * written to.
+ * written to, and the name a refusal offers when one was mistyped.
  */
 export * from './artifact.js';
+export { didYouMean, nearest } from './nearest.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,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 * Every name lives in exactly one of them; nothing is reachable from two paths.\n * This entrypoint holds only what belongs to no group: the artifact a capture is\n * written to.\n */\n\nexport * from './artifact.js';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,cAAc,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 * Every name lives in exactly one of them; nothing is reachable from two paths.\n * This entrypoint holds only what belongs to no group: the artifact a capture is\n * written to, and the name a refusal offers when one was mistyped.\n */\n\nexport * from './artifact.js';\nexport { didYouMean, nearest } from './nearest.js';\n"]}

package/dist/nearest.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The name somebody meant, when exactly one name is close enough.
+ *
+ * A refusal names what was typed and then the command's synopsis, which lists
+ * what it accepts. The reader is usually an agent, and an agent that mistyped
+ * `--quer` should correct it from the same message instead of spending a second
+ * turn on it. So one sentence goes in front of the synopsis. Naming a candidate
+ * is cheap and reversible: nothing is run on the guess, and a wrong guess costs
+ * one line.
+ *
+ * ## Why one, and why not always
+ *
+ * Two names equally close is not a suggestion, it is a second decision handed
+ * back — so a tie suggests nothing and the set alone answers. And the distance
+ * is bounded by the length of what was typed: without that, `--x` is one edit
+ * from nothing and three from half the table, and a suggestion that fires on
+ * anything is one nobody can read as a signal.
+ *
+ * Damerau-Levenshtein, iterative, over three rows. Transposed neighbours count
+ * as one edit rather than two, which is not a refinement: `aks` for `ask` and
+ * `--fromat` for `--format` are the typo, and under plain Levenshtein both sit
+ * at distance two and are missed by the bound below. No dependency, for the
+ * reason `parse.ts` gives — a tool whose claim is that its output can be trusted
+ * does not acquire a transitive graph to spell-check a flag.
+ */
+/**
+ * The single closest candidate, or nothing.
+ *
+ * Case-insensitive, because a name typed in the wrong case is the same mistake
+ * and the answer is the same name. Comparison only — what comes back is the
+ * candidate as it is actually spelled, since that is what has to be typed next.
+ */
+export declare function nearest(typed: string, candidates: readonly string[]): string | undefined;
+/**
+ * The line a refusal adds beside its list, or nothing.
+ *
+ * Its own function so every refusal says it the same way. An agent reading three
+ * different phrasings for one idea has three things to recognise.
+ *
+ * A line of its own, and it carries the newline itself so a refusal with nothing
+ * to suggest does not print a blank one. Beside the accepted set rather than
+ * inside that sentence: the set is the part a reader parses — a name split out
+ * of a list should not have half a second sentence attached to it.
+ */
+export declare function didYouMean(typed: string, candidates: readonly string[]): string;
+//# sourceMappingURL=nearest.d.ts.map