@variance-authority/core 0.15.0 → 0.18.0

package/dist/format/shape.js

@@ -0,0 +1,269 @@
+import { FORMAT_VERSION } from './packed.js';
+/**
+ * Whether a value read back from a file or a store is the format it claims.
+ *
+ * Read, not believed: a value parsed from JSON is `unknown` until one of these
+ * says otherwise, and each checks every field its type declares, so that there
+ * is one answer to what a snapshot, a document or a subject is. What a reader
+ * can re-derive, a digest against the bytes it names, is the reader's to check.
+ */
+/**
+ * Whether a value is a `SemanticSnapshot`, every node down to the leaves.
+ *
+ * The readers walk all of it: the matcher pairs every child, and a node that is
+ * not one throws there instead of reading as a snapshot that is not recorded.
+ * A capture file and a packed snapshot are the two places one is read back.
+ * Whose snapshot it is, against the subject it was filed under, is the
+ * reader's question.
+ */
+export function isSemanticSnapshot(value) {
+    const snapshot = record(value);
+    const profile = snapshot === null ? null : record(snapshot.profile);
+    const environment = snapshot === null ? null : record(snapshot.environment);
+    const root = snapshot === null ? null : record(snapshot.root);
+    return (snapshot !== null &&
+        snapshot.formatVersion === FORMAT_VERSION &&
+        isSubjectRef(snapshot.subject) &&
+        profile !== null &&
+        (profile.id === 'jsdom' || profile.id === 'chromium') &&
+        ['ariaTree', 'declaredStyle', 'computedStyle', 'layout', 'raster'].every((field) => typeof profile[field] === 'boolean') &&
+        environment !== null &&
+        typeof environment.digest === 'string' &&
+        typeof environment.semanticDigest === 'string' &&
+        environmentInputsShape(environment.inputs) &&
+        typeof snapshot.renderHash === 'string' &&
+        typeof snapshot.structureHash === 'string' &&
+        typeof snapshot.styleHash === 'string' &&
+        root !== null &&
+        semanticNodeShape(root) &&
+        Array.isArray(snapshot.styleProvenance) &&
+        snapshot.styleProvenance.every(styleProvenanceShape) &&
+        (snapshot.ignoreSites === undefined ||
+            (Array.isArray(snapshot.ignoreSites) && snapshot.ignoreSites.every(ignoreSiteShape))) &&
+        diagnosticArray(snapshot.diagnostics));
+}
+/**
+ * Whether a value is a `RenderDocument`, its resources' shape included.
+ *
+ * Shape only: that a resource's bytes are base64 and hash to its digest, and
+ * that a document is resource-closed, are what a reader that needs them checks.
+ */
+export function isRenderDocument(value) {
+    const document = record(value);
+    const frame = document === null ? null : record(document.frame);
+    const viewport = document === null ? null : record(document.viewport);
+    return (document !== null &&
+        document.documentVersion === 1 &&
+        isSubjectRef(document.subject) &&
+        typeof document.html === 'string' &&
+        frame !== null &&
+        stringRecord(frame.html) &&
+        stringRecord(frame.body) &&
+        Array.isArray(frame.ancestors) &&
+        frame.ancestors.every(frameElementShape) &&
+        (frame.containerWidth === undefined || finiteNumber(frame.containerWidth)) &&
+        stringArray(document.css) &&
+        viewport !== null &&
+        finiteNumber(viewport.width) &&
+        finiteNumber(viewport.height) &&
+        finiteNumber(viewport.deviceScaleFactor) &&
+        (viewport.colorScheme === 'light' || viewport.colorScheme === 'dark') &&
+        stringRecord(document.inherited) &&
+        stringArray(document.fonts) &&
+        (document.assets === undefined || stringRecord(document.assets)) &&
+        optionalString(document.baseUrl) &&
+        (document.resources === undefined ||
+            (record(document.resources) !== null && Object.values(document.resources).every(resourceShape))) &&
+        diagnosticArray(document.diagnostics));
+}
+/** Whether a value is a `SubjectRef`: an id, one of the four kinds, and an optional title. */
+export function isSubjectRef(value) {
+    const subject = record(value);
+    return subject !== null &&
+        typeof subject.id === 'string' &&
+        ['story', 'route', 'fixture', 'value'].includes(String(subject.kind)) &&
+        optionalString(subject.title);
+}
+function frameElementShape(value) {
+    const element = record(value);
+    return element !== null && typeof element.tag === 'string' && stringRecord(element.attributes);
+}
+function resourceShape(value) {
+    const resource = record(value);
+    return resource !== null &&
+        typeof resource.contentType === 'string' &&
+        typeof resource.bytes === 'string' &&
+        typeof resource.digest === 'string' &&
+        (resource.status === undefined || finiteNumber(resource.status));
+}
+function environmentInputsShape(value) {
+    const inputs = record(value);
+    const viewport = inputs === null ? null : record(inputs.viewport);
+    return inputs !== null &&
+        (inputs.profile === 'jsdom' || inputs.profile === 'chromium') &&
+        typeof inputs.engine === 'string' &&
+        typeof inputs.ruleset === 'string' &&
+        typeof inputs.allowlist === 'string' &&
+        viewport !== null &&
+        finiteNumber(viewport.width) &&
+        finiteNumber(viewport.height) &&
+        finiteNumber(viewport.deviceScaleFactor) &&
+        (viewport.colorScheme === 'light' || viewport.colorScheme === 'dark') &&
+        stringArray(inputs.fonts) &&
+        scalarRecord(inputs.conditions) &&
+        stringRecord(inputs.assets) &&
+        optionalString(inputs.stabilization) &&
+        optionalString(inputs.timezoneId) &&
+        optionalString(inputs.locale);
+}
+function styleProvenanceShape(value) {
+    const entry = record(value);
+    if (entry === null ||
+        typeof entry.path !== 'string' ||
+        typeof entry.property !== 'string' ||
+        typeof entry.sheet !== 'string' ||
+        typeof entry.selector !== 'string' ||
+        !optionalString(entry.tokenName))
+        return false;
+    if (entry.source === undefined)
+        return true;
+    const source = record(entry.source);
+    return source !== null && typeof source.file === 'string' && finiteNumber(source.line);
+}
+function semanticNodeShape(node) {
+    return (typeof node.path === 'string' &&
+        typeof node.tag === 'string' &&
+        optionalString(node.alias) &&
+        optionalString(node.role) &&
+        optionalString(node.name) &&
+        optionalString(node.description) &&
+        (node.state === undefined || scalarRecord(node.state)) &&
+        stringRecord(node.attributes) &&
+        stringRecord(node.style) &&
+        (node.tokens === undefined || stringRecord(node.tokens)) &&
+        (node.styleTokens === undefined || stringRecord(node.styleTokens)) &&
+        (node.rect === undefined || rectShape(node.rect)) &&
+        optionalString(node.text) &&
+        (node.provenance === undefined || provenanceShape(node.provenance)) &&
+        (node.wiring === undefined || wiringShape(node.wiring)) &&
+        (node.holding === undefined || holdingShape(node.holding)) &&
+        (node.portalled === undefined || typeof node.portalled === 'boolean') &&
+        (node.ignoredBy === undefined || stringArray(node.ignoredBy)) &&
+        optionalString(node.unread) &&
+        Array.isArray(node.children) &&
+        node.children.every((child) => {
+            const parsed = record(child);
+            return parsed !== null && semanticNodeShape(parsed);
+        }));
+}
+function ignoreSiteShape(value) {
+    const site = record(value);
+    return site !== null &&
+        typeof site.path === 'string' &&
+        typeof site.rule === 'string' &&
+        (site.rect === undefined || rectShape(site.rect));
+}
+function rectShape(value) {
+    const rect = record(value);
+    return rect !== null &&
+        finiteNumber(rect.x) &&
+        finiteNumber(rect.y) &&
+        finiteNumber(rect.width) &&
+        finiteNumber(rect.height);
+}
+function provenanceShape(value) {
+    const provenance = record(value);
+    return provenance !== null &&
+        Array.isArray(provenance.owners) &&
+        provenance.owners.every(ownerShape) &&
+        optionalString(provenance.createdBy) &&
+        (provenance.source === undefined || sourceLocationShape(provenance.source)) &&
+        (provenance.stack === undefined ||
+            (Array.isArray(provenance.stack) && provenance.stack.every(stackFrameShape)));
+}
+function ownerShape(value) {
+    const owner = record(value);
+    return owner !== null &&
+        typeof owner.name === 'string' &&
+        typeof owner.propsDigest === 'string' &&
+        optionalString(owner.createdBy);
+}
+function sourceLocationShape(value) {
+    const source = record(value);
+    return source !== null &&
+        typeof source.file === 'string' &&
+        finiteNumber(source.line) &&
+        finiteNumber(source.column);
+}
+function stackFrameShape(value) {
+    const frame = record(value);
+    return frame !== null &&
+        typeof frame.url === 'string' &&
+        finiteNumber(frame.line) &&
+        finiteNumber(frame.column) &&
+        optionalString(frame.function);
+}
+function wiringShape(value) {
+    const wiring = record(value);
+    return wiring !== null &&
+        (wiring.hooks === undefined || stringArray(wiring.hooks)) &&
+        (wiring.wrappers === undefined ||
+            (Array.isArray(wiring.wrappers) &&
+                wiring.wrappers.every((entry) => entry === 'memo' || entry === 'forwardRef'))) &&
+        (wiring.contexts === undefined || stringArray(wiring.contexts)) &&
+        optionalString(wiring.key);
+}
+function holdingShape(value) {
+    const holding = record(value);
+    return holding !== null &&
+        (holding.cells === undefined || (Array.isArray(holding.cells) && holding.cells.every((value) => {
+            const cell = record(value);
+            return cell !== null && finiteNumber(cell.index) && typeof cell.hook === 'string' && typeof cell.digest === 'string';
+        }))) &&
+        (holding.contexts === undefined || heldValues(holding.contexts)) &&
+        (holding.props === undefined || heldValues(holding.props)) &&
+        optionalString(holding.unread);
+}
+function heldValues(value) {
+    return Array.isArray(value) && value.every((entry) => {
+        const held = record(entry);
+        return held !== null && typeof held.name === 'string' && typeof held.digest === 'string';
+    });
+}
+function diagnosticArray(value) {
+    return Array.isArray(value) && value.every((entry) => {
+        const diagnostic = record(entry);
+        return diagnostic !== null &&
+            (diagnostic.severity === 'warn' || diagnostic.severity === 'error') &&
+            typeof diagnostic.code === 'string' &&
+            typeof diagnostic.message === 'string' &&
+            optionalString(diagnostic.nodePath);
+    });
+}
+// A plain object. `@variance-authority/unit-test`'s capture-file reader keeps
+// the same guard privately: it is re-typed in several packages and has no
+// exported owner, and exporting it from here would make it part of the format.
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+function stringRecord(value) {
+    const parsed = record(value);
+    return parsed !== null && Object.values(parsed).every((entry) => typeof entry === 'string');
+}
+function scalarRecord(value) {
+    const parsed = record(value);
+    return parsed !== null && Object.values(parsed).every((entry) => ['string', 'boolean', 'number'].includes(typeof entry) &&
+        (typeof entry !== 'number' || Number.isFinite(entry)));
+}
+function stringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
+}
+function optionalString(value) {
+    return value === undefined || typeof value === 'string';
+}
+function finiteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+//# sourceMappingURL=shape.js.map

package/dist/format/shape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape.js","sourceRoot":"","sources":["../../src/format/shape.ts"],"names":[],"mappings":"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","sourcesContent":["import type { SubjectRef } from './capture.js';\nimport type { RenderDocument } from './document.js';\nimport { FORMAT_VERSION } from './packed.js';\nimport type { SemanticSnapshot } from './snapshot.js';\n\n/**\n * Whether a value read back from a file or a store is the format it claims.\n *\n * Read, not believed: a value parsed from JSON is `unknown` until one of these\n * says otherwise, and each checks every field its type declares, so that there\n * is one answer to what a snapshot, a document or a subject is. What a reader\n * can re-derive, a digest against the bytes it names, is the reader's to check.\n */\n\n/**\n * Whether a value is a `SemanticSnapshot`, every node down to the leaves.\n *\n * The readers walk all of it: the matcher pairs every child, and a node that is\n * not one throws there instead of reading as a snapshot that is not recorded.\n * A capture file and a packed snapshot are the two places one is read back.\n * Whose snapshot it is, against the subject it was filed under, is the\n * reader's question.\n */\nexport function isSemanticSnapshot(value: unknown): value is SemanticSnapshot {\n  const snapshot = record(value);\n  const profile = snapshot === null ? null : record(snapshot.profile);\n  const environment = snapshot === null ? null : record(snapshot.environment);\n  const root = snapshot === null ? null : record(snapshot.root);\n  return (\n    snapshot !== null &&\n    snapshot.formatVersion === FORMAT_VERSION &&\n    isSubjectRef(snapshot.subject) &&\n    profile !== null &&\n    (profile.id === 'jsdom' || profile.id === 'chromium') &&\n    ['ariaTree', 'declaredStyle', 'computedStyle', 'layout', 'raster'].every(\n      (field) => typeof profile[field] === 'boolean',\n    ) &&\n    environment !== null &&\n    typeof environment.digest === 'string' &&\n    typeof environment.semanticDigest === 'string' &&\n    environmentInputsShape(environment.inputs) &&\n    typeof snapshot.renderHash === 'string' &&\n    typeof snapshot.structureHash === 'string' &&\n    typeof snapshot.styleHash === 'string' &&\n    root !== null &&\n    semanticNodeShape(root) &&\n    Array.isArray(snapshot.styleProvenance) &&\n    snapshot.styleProvenance.every(styleProvenanceShape) &&\n    (snapshot.ignoreSites === undefined ||\n      (Array.isArray(snapshot.ignoreSites) && snapshot.ignoreSites.every(ignoreSiteShape))) &&\n    diagnosticArray(snapshot.diagnostics)\n  );\n}\n\n/**\n * Whether a value is a `RenderDocument`, its resources' shape included.\n *\n * Shape only: that a resource's bytes are base64 and hash to its digest, and\n * that a document is resource-closed, are what a reader that needs them checks.\n */\nexport function isRenderDocument(value: unknown): value is RenderDocument {\n  const document = record(value);\n  const frame = document === null ? null : record(document.frame);\n  const viewport = document === null ? null : record(document.viewport);\n  return (\n    document !== null &&\n    document.documentVersion === 1 &&\n    isSubjectRef(document.subject) &&\n    typeof document.html === 'string' &&\n    frame !== null &&\n    stringRecord(frame.html) &&\n    stringRecord(frame.body) &&\n    Array.isArray(frame.ancestors) &&\n    frame.ancestors.every(frameElementShape) &&\n    (frame.containerWidth === undefined || finiteNumber(frame.containerWidth)) &&\n    stringArray(document.css) &&\n    viewport !== null &&\n    finiteNumber(viewport.width) &&\n    finiteNumber(viewport.height) &&\n    finiteNumber(viewport.deviceScaleFactor) &&\n    (viewport.colorScheme === 'light' || viewport.colorScheme === 'dark') &&\n    stringRecord(document.inherited) &&\n    stringArray(document.fonts) &&\n    (document.assets === undefined || stringRecord(document.assets)) &&\n    optionalString(document.baseUrl) &&\n    (document.resources === undefined ||\n      (record(document.resources) !== null && Object.values(document.resources as object).every(resourceShape))) &&\n    diagnosticArray(document.diagnostics)\n  );\n}\n\n/** Whether a value is a `SubjectRef`: an id, one of the four kinds, and an optional title. */\nexport function isSubjectRef(value: unknown): value is SubjectRef {\n  const subject = record(value);\n  return subject !== null &&\n    typeof subject.id === 'string' &&\n    ['story', 'route', 'fixture', 'value'].includes(String(subject.kind)) &&\n    optionalString(subject.title);\n}\n\nfunction frameElementShape(value: unknown): boolean {\n  const element = record(value);\n  return element !== null && typeof element.tag === 'string' && stringRecord(element.attributes);\n}\n\nfunction resourceShape(value: unknown): boolean {\n  const resource = record(value);\n  return resource !== null &&\n    typeof resource.contentType === 'string' &&\n    typeof resource.bytes === 'string' &&\n    typeof resource.digest === 'string' &&\n    (resource.status === undefined || finiteNumber(resource.status));\n}\n\nfunction environmentInputsShape(value: unknown): boolean {\n  const inputs = record(value);\n  const viewport = inputs === null ? null : record(inputs.viewport);\n  return inputs !== null &&\n    (inputs.profile === 'jsdom' || inputs.profile === 'chromium') &&\n    typeof inputs.engine === 'string' &&\n    typeof inputs.ruleset === 'string' &&\n    typeof inputs.allowlist === 'string' &&\n    viewport !== null &&\n    finiteNumber(viewport.width) &&\n    finiteNumber(viewport.height) &&\n    finiteNumber(viewport.deviceScaleFactor) &&\n    (viewport.colorScheme === 'light' || viewport.colorScheme === 'dark') &&\n    stringArray(inputs.fonts) &&\n    scalarRecord(inputs.conditions) &&\n    stringRecord(inputs.assets) &&\n    optionalString(inputs.stabilization) &&\n    optionalString(inputs.timezoneId) &&\n    optionalString(inputs.locale);\n}\n\nfunction styleProvenanceShape(value: unknown): boolean {\n  const entry = record(value);\n  if (entry === null ||\n    typeof entry.path !== 'string' ||\n    typeof entry.property !== 'string' ||\n    typeof entry.sheet !== 'string' ||\n    typeof entry.selector !== 'string' ||\n    !optionalString(entry.tokenName)) return false;\n  if (entry.source === undefined) return true;\n  const source = record(entry.source);\n  return source !== null && typeof source.file === 'string' && finiteNumber(source.line);\n}\n\nfunction semanticNodeShape(node: Record<string, unknown>): boolean {\n  return (\n    typeof node.path === 'string' &&\n    typeof node.tag === 'string' &&\n    optionalString(node.alias) &&\n    optionalString(node.role) &&\n    optionalString(node.name) &&\n    optionalString(node.description) &&\n    (node.state === undefined || scalarRecord(node.state)) &&\n    stringRecord(node.attributes) &&\n    stringRecord(node.style) &&\n    (node.tokens === undefined || stringRecord(node.tokens)) &&\n    (node.styleTokens === undefined || stringRecord(node.styleTokens)) &&\n    (node.rect === undefined || rectShape(node.rect)) &&\n    optionalString(node.text) &&\n    (node.provenance === undefined || provenanceShape(node.provenance)) &&\n    (node.wiring === undefined || wiringShape(node.wiring)) &&\n    (node.holding === undefined || holdingShape(node.holding)) &&\n    (node.portalled === undefined || typeof node.portalled === 'boolean') &&\n    (node.ignoredBy === undefined || stringArray(node.ignoredBy)) &&\n    optionalString(node.unread) &&\n    Array.isArray(node.children) &&\n    node.children.every((child) => {\n      const parsed = record(child);\n      return parsed !== null && semanticNodeShape(parsed);\n    })\n  );\n}\n\nfunction ignoreSiteShape(value: unknown): boolean {\n  const site = record(value);\n  return site !== null &&\n    typeof site.path === 'string' &&\n    typeof site.rule === 'string' &&\n    (site.rect === undefined || rectShape(site.rect));\n}\n\nfunction rectShape(value: unknown): boolean {\n  const rect = record(value);\n  return rect !== null &&\n    finiteNumber(rect.x) &&\n    finiteNumber(rect.y) &&\n    finiteNumber(rect.width) &&\n    finiteNumber(rect.height);\n}\n\nfunction provenanceShape(value: unknown): boolean {\n  const provenance = record(value);\n  return provenance !== null &&\n    Array.isArray(provenance.owners) &&\n    provenance.owners.every(ownerShape) &&\n    optionalString(provenance.createdBy) &&\n    (provenance.source === undefined || sourceLocationShape(provenance.source)) &&\n    (provenance.stack === undefined ||\n      (Array.isArray(provenance.stack) && provenance.stack.every(stackFrameShape)));\n}\n\nfunction ownerShape(value: unknown): boolean {\n  const owner = record(value);\n  return owner !== null &&\n    typeof owner.name === 'string' &&\n    typeof owner.propsDigest === 'string' &&\n    optionalString(owner.createdBy);\n}\n\nfunction sourceLocationShape(value: unknown): boolean {\n  const source = record(value);\n  return source !== null &&\n    typeof source.file === 'string' &&\n    finiteNumber(source.line) &&\n    finiteNumber(source.column);\n}\n\nfunction stackFrameShape(value: unknown): boolean {\n  const frame = record(value);\n  return frame !== null &&\n    typeof frame.url === 'string' &&\n    finiteNumber(frame.line) &&\n    finiteNumber(frame.column) &&\n    optionalString(frame.function);\n}\n\nfunction wiringShape(value: unknown): boolean {\n  const wiring = record(value);\n  return wiring !== null &&\n    (wiring.hooks === undefined || stringArray(wiring.hooks)) &&\n    (wiring.wrappers === undefined ||\n      (Array.isArray(wiring.wrappers) &&\n        wiring.wrappers.every((entry) => entry === 'memo' || entry === 'forwardRef'))) &&\n    (wiring.contexts === undefined || stringArray(wiring.contexts)) &&\n    optionalString(wiring.key);\n}\n\nfunction holdingShape(value: unknown): boolean {\n  const holding = record(value);\n  return holding !== null &&\n    (holding.cells === undefined || (Array.isArray(holding.cells) && holding.cells.every((value) => {\n      const cell = record(value);\n      return cell !== null && finiteNumber(cell.index) && typeof cell.hook === 'string' && typeof cell.digest === 'string';\n    }))) &&\n    (holding.contexts === undefined || heldValues(holding.contexts)) &&\n    (holding.props === undefined || heldValues(holding.props)) &&\n    optionalString(holding.unread);\n}\n\nfunction heldValues(value: unknown): boolean {\n  return Array.isArray(value) && value.every((entry) => {\n    const held = record(entry);\n    return held !== null && typeof held.name === 'string' && typeof held.digest === 'string';\n  });\n}\n\nfunction diagnosticArray(value: unknown): boolean {\n  return Array.isArray(value) && value.every((entry) => {\n    const diagnostic = record(entry);\n    return diagnostic !== null &&\n      (diagnostic.severity === 'warn' || diagnostic.severity === 'error') &&\n      typeof diagnostic.code === 'string' &&\n      typeof diagnostic.message === 'string' &&\n      optionalString(diagnostic.nodePath);\n  });\n}\n\n// A plain object. `@variance-authority/unit-test`'s capture-file reader keeps\n// the same guard privately: it is re-typed in several packages and has no\n// exported owner, and exporting it from here would make it part of the format.\nfunction record(value: unknown): Record<string, unknown> | null {\n  return typeof value === 'object' && value !== null && !Array.isArray(value)\n    ? (value as Record<string, unknown>)\n    : null;\n}\n\nfunction stringRecord(value: unknown): boolean {\n  const parsed = record(value);\n  return parsed !== null && Object.values(parsed).every((entry) => typeof entry === 'string');\n}\n\nfunction scalarRecord(value: unknown): boolean {\n  const parsed = record(value);\n  return parsed !== null && Object.values(parsed).every(\n    (entry) => ['string', 'boolean', 'number'].includes(typeof entry) &&\n      (typeof entry !== 'number' || Number.isFinite(entry)),\n  );\n}\n\nfunction stringArray(value: unknown): boolean {\n  return Array.isArray(value) && value.every((entry) => typeof entry === 'string');\n}\n\nfunction optionalString(value: unknown): boolean {\n  return value === undefined || typeof value === 'string';\n}\n\nfunction finiteNumber(value: unknown): boolean {\n  return typeof value === 'number' && Number.isFinite(value);\n}\n"]}

package/dist/format/stabilize.d.ts

@@ -1,6 +1,7 @@
 import { type Digest } from './hash.js';
 import { type Tier } from './tier.js';
 import type { Intervention, ScreenshotOptions, SettleTarget } from './intervention.js';
+import type { StepClock } from './steps.js';
 /**
  * Interventions as separate, nameable tricks — not a fixed set of switches.
  *
@@ -213,7 +214,12 @@ export declare function conflicts(recipe: Recipe): readonly {
 }[];
 export declare function recipeCss(recipe: Recipe): string;
 export declare function recipeScreenshot(recipe: Recipe): ScreenshotOptions;
-export declare function settleRecipe(recipe: Recipe, target: SettleTarget): Promise<void>;
+/**
+ * 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 declare function settleRecipe(recipe: Recipe, target: SettleTarget, steps?: StepClock): Promise<void>;
 /**
  * The identity of a recipe.
  *

package/dist/format/stabilize.js

@@ -276,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)));
     }
 }
 /**

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 { 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"]}
+{"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"]}