@variance-authority/core 0.14.0 → 0.17.1

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));
@@ -328,10 +276,17 @@ export function recipeCss(recipe) {
 export function recipeScreenshot(recipe) {
     return recipe.reduce((options, intervention) => ({ ...options, ...intervention.screenshot }), {});
 }
-export async function settleRecipe(recipe, target) {
+/**
+ * Every wait the recipe holds, in order. Each is one step on `steps`, named by
+ * the intervention's id, so a run can say which wait a slow subject spent its
+ * time in.
+ */
+export async function settleRecipe(recipe, target, steps) {
     for (const intervention of recipe) {
-        if (intervention.settle !== undefined)
-            await intervention.settle(target);
+        const settle = intervention.settle;
+        if (settle === undefined)
+            continue;
+        await (steps === undefined ? settle(target) : steps.time(intervention.id, async () => settle(target)));
     }
 }
 /**
@@ -339,7 +294,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 type { StepClock } from './steps.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\n/**\n * Every wait the recipe holds, in order. Each is one step on `steps`, named by\n * the intervention's id, so a run can say which wait a slow subject spent its\n * time in.\n */\nexport async function settleRecipe(recipe: Recipe, target: SettleTarget, steps?: StepClock): Promise<void> {\n  for (const intervention of recipe) {\n    const settle = intervention.settle;\n    if (settle === undefined) continue;\n    await (steps === undefined ? settle(target) : steps.time(intervention.id, async () => 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/steps.d.ts

@@ -0,0 +1,44 @@
+/**
+ * How long each step of reading one subject took.
+ *
+ * A step is a span of work the code already brackets as one phase — a
+ * navigation, one stabilization wait, the screenshot, the decode — named by the
+ * phase's own name. Each owner times only its own steps and hands the rest on
+ * as data, so a subject's steps never overlap and never sum to more than what
+ * the subject cost. A step that did not run is absent, never a zero: zero means
+ * it ran and finished under the clock's resolution.
+ *
+ * Durations only, on a monotonic clock, and the wall time of the span: with
+ * several worlds collecting side by side a step includes what the others cost
+ * it, which is what it cost this run. Steps describe a reading and are part of
+ * no digest, so a timing can never move an image, a key or a verdict.
+ */
+/** One step of one subject: the phase's own name and how long its span took. */
+export interface Step {
+    readonly step: string;
+    /** Wall time of the span, in milliseconds, to a tenth. */
+    readonly ms: number;
+}
+/** One step over a run: summed over the subjects that ran it, and how many did. */
+export interface StepTotal {
+    readonly step: string;
+    readonly ms: number;
+    readonly subjects: number;
+}
+/** Where one subject's steps are taken, in the order they ran; each owner times its own and passes the clock on. */
+export interface StepClock {
+    /** Run `job` as `step`. Taken whether it resolves or throws. */
+    time<T>(step: string, job: () => Promise<T> | T): Promise<T>;
+    /** Steps another owner timed, appended as they arrive, each name behind `prefix`. */
+    add(steps: readonly Step[] | undefined, prefix?: string): void;
+    /** The same list, with every name this view takes behind `prefix`. */
+    within(prefix: string): StepClock;
+    readonly taken: readonly Step[];
+}
+/** `now` is the owner's monotonic clock, in milliseconds: `performance.now` wherever it runs. */
+export declare function stepClock(now: () => number): StepClock;
+/** `job` as `step` on `steps`, or just `job` when nothing is timing it. */
+export declare function timeOn<T>(steps: StepClock | undefined, step: string, job: () => Promise<T> | T): Promise<T>;
+/** Each step's total over every subject that ran it, by name in code-unit order. */
+export declare function totalsOf(subjects: readonly (readonly Step[] | undefined)[]): readonly StepTotal[];
+//# sourceMappingURL=steps.d.ts.map

package/dist/format/steps.js

@@ -0,0 +1,67 @@
+/**
+ * How long each step of reading one subject took.
+ *
+ * A step is a span of work the code already brackets as one phase — a
+ * navigation, one stabilization wait, the screenshot, the decode — named by the
+ * phase's own name. Each owner times only its own steps and hands the rest on
+ * as data, so a subject's steps never overlap and never sum to more than what
+ * the subject cost. A step that did not run is absent, never a zero: zero means
+ * it ran and finished under the clock's resolution.
+ *
+ * Durations only, on a monotonic clock, and the wall time of the span: with
+ * several worlds collecting side by side a step includes what the others cost
+ * it, which is what it cost this run. Steps describe a reading and are part of
+ * no digest, so a timing can never move an image, a key or a verdict.
+ */
+import { codeUnitOrder } from '../segment/index.js';
+/** `now` is the owner's monotonic clock, in milliseconds: `performance.now` wherever it runs. */
+export function stepClock(now) {
+    return viewOf([], now, '');
+}
+function viewOf(taken, now, prefix) {
+    return {
+        async time(step, job) {
+            const started = now();
+            try {
+                return await job();
+            }
+            finally {
+                taken.push({ step: prefix + step, ms: tenths(now() - started) });
+            }
+        },
+        add(steps, more = '') {
+            for (const { step, ms } of steps ?? [])
+                taken.push({ step: prefix + more + step, ms });
+        },
+        within(more) {
+            return viewOf(taken, now, prefix + more);
+        },
+        taken,
+    };
+}
+/** `job` as `step` on `steps`, or just `job` when nothing is timing it. */
+export async function timeOn(steps, step, job) {
+    return steps === undefined ? job() : steps.time(step, job);
+}
+/** Each step's total over every subject that ran it, by name in code-unit order. */
+export function totalsOf(subjects) {
+    const totals = new Map();
+    for (const steps of subjects) {
+        const seen = new Set();
+        for (const { step, ms } of steps ?? []) {
+            const total = totals.get(step) ?? { ms: 0, subjects: 0 };
+            total.ms += ms;
+            if (!seen.has(step))
+                total.subjects += 1;
+            seen.add(step);
+            totals.set(step, total);
+        }
+    }
+    return [...totals]
+        .sort(([left], [right]) => codeUnitOrder(left, right))
+        .map(([step, total]) => ({ step, ms: tenths(total.ms), subjects: total.subjects }));
+}
+function tenths(ms) {
+    return Math.round(ms * 10) / 10;
+}
+//# sourceMappingURL=steps.js.map

package/dist/format/steps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"steps.js","sourceRoot":"","sources":["../../src/format/steps.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * How long each step of reading one subject took.\n *\n * A step is a span of work the code already brackets as one phase — a\n * navigation, one stabilization wait, the screenshot, the decode — named by the\n * phase's own name. Each owner times only its own steps and hands the rest on\n * as data, so a subject's steps never overlap and never sum to more than what\n * the subject cost. A step that did not run is absent, never a zero: zero means\n * it ran and finished under the clock's resolution.\n *\n * Durations only, on a monotonic clock, and the wall time of the span: with\n * several worlds collecting side by side a step includes what the others cost\n * it, which is what it cost this run. Steps describe a reading and are part of\n * no digest, so a timing can never move an image, a key or a verdict.\n */\n\nimport { codeUnitOrder } from '../segment/index.js';\n\n/** One step of one subject: the phase's own name and how long its span took. */\nexport interface Step {\n  readonly step: string;\n  /** Wall time of the span, in milliseconds, to a tenth. */\n  readonly ms: number;\n}\n\n/** One step over a run: summed over the subjects that ran it, and how many did. */\nexport interface StepTotal {\n  readonly step: string;\n  readonly ms: number;\n  readonly subjects: number;\n}\n\n/** Where one subject's steps are taken, in the order they ran; each owner times its own and passes the clock on. */\nexport interface StepClock {\n  /** Run `job` as `step`. Taken whether it resolves or throws. */\n  time<T>(step: string, job: () => Promise<T> | T): Promise<T>;\n  /** Steps another owner timed, appended as they arrive, each name behind `prefix`. */\n  add(steps: readonly Step[] | undefined, prefix?: string): void;\n  /** The same list, with every name this view takes behind `prefix`. */\n  within(prefix: string): StepClock;\n  readonly taken: readonly Step[];\n}\n\n/** `now` is the owner's monotonic clock, in milliseconds: `performance.now` wherever it runs. */\nexport function stepClock(now: () => number): StepClock {\n  return viewOf([], now, '');\n}\n\nfunction viewOf(taken: Step[], now: () => number, prefix: string): StepClock {\n  return {\n    async time(step, job) {\n      const started = now();\n      try {\n        return await job();\n      } finally {\n        taken.push({ step: prefix + step, ms: tenths(now() - started) });\n      }\n    },\n    add(steps, more = '') {\n      for (const { step, ms } of steps ?? []) taken.push({ step: prefix + more + step, ms });\n    },\n    within(more) {\n      return viewOf(taken, now, prefix + more);\n    },\n    taken,\n  };\n}\n\n/** `job` as `step` on `steps`, or just `job` when nothing is timing it. */\nexport async function timeOn<T>(\n  steps: StepClock | undefined,\n  step: string,\n  job: () => Promise<T> | T,\n): Promise<T> {\n  return steps === undefined ? job() : steps.time(step, job);\n}\n\n/** Each step's total over every subject that ran it, by name in code-unit order. */\nexport function totalsOf(subjects: readonly (readonly Step[] | undefined)[]): readonly StepTotal[] {\n  const totals = new Map<string, { ms: number; subjects: number }>();\n  for (const steps of subjects) {\n    const seen = new Set<string>();\n    for (const { step, ms } of steps ?? []) {\n      const total = totals.get(step) ?? { ms: 0, subjects: 0 };\n      total.ms += ms;\n      if (!seen.has(step)) total.subjects += 1;\n      seen.add(step);\n      totals.set(step, total);\n    }\n  }\n  return [...totals]\n    .sort(([left], [right]) => codeUnitOrder(left, right))\n    .map(([step, total]) => ({ step, ms: tenths(total.ms), subjects: total.subjects }));\n}\n\nfunction tenths(ms: number): number {\n  return Math.round(ms * 10) / 10;\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