@variance-authority/core 0.14.0 → 0.17.1

package/dist/format/document.js.map

@@ -1 +1 @@
-{"version":3,"file":"document.js","sourceRoot":"","sources":["../../src/format/document.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Diagnostic, SubjectRef } from './capture.js';\nimport type { Viewport } from './environment.js';\nimport { digestValue, type Digest } from './hash.js';\nimport type { ComponentHash } from './snapshot.js';\n\n/**\n * The render document: what gets *sent* somewhere to become an image.\n *\n * This is the acquisition phase's output and the only thing the rendering side\n * ever sees. It is plain serializable data for the same reason `RawCapture` is\n * (ADR-0006): the renderer may be a page in this process, a browser on this\n * machine, or a pinned container two networks away, and no code upstream of it\n * may assume which.\n *\n * Two routes produce one of these, and the point of the type is that they are\n * interchangeable:\n *\n * 1. **jsdom → document → render elsewhere.** jsdom cannot rasterize. It can\n *    describe exactly what to rasterize, which is the sub-renderer split ADR-0002\n *    asks for: the cheap tier decides almost everything, and the residue is\n *    handed to something that owns a GPU.\n * 2. **playwright → document → render on a server.** The same payload, acquired\n *    from a real engine. Used when the *deciding* machine and the *pinned*\n *    machine are different, which is the case every CI setup actually has.\n *\n * A browser may instead capture a `Raster` in place. That is the sibling branch\n * of `CaptureMaterial`, not a third route that somehow produces this type.\n *\n * ## Why this is small\n *\n * `css` holds the *applicable* rules only — the pruning of ADR-0003, which on\n * `@variance-authority/dom`'s accretion fixture takes 1010 rules to 1. That\n * number is a cost claim as much as a\n * correctness one: shipping a document over a network hop is only sensible if the\n * document is not the entire design system plus Storybook's chrome.\n */\nexport interface RenderDocument {\n  readonly documentVersion: 1;\n  readonly subject: SubjectRef;\n\n  /**\n   * The subject subtree, serialized.\n   *\n   * Serialized rather than referenced by URL: a URL makes the renderer\n   * responsible for reproducing the application's state, which it cannot do and\n   * should not try. What is sent is the markup that existed at the moment of\n   * capture, which is the only definition of \"this render\" that survives a hop.\n   */\n  readonly html: string;\n\n  /**\n   * The ancestor context the subject was rendered inside.\n   *\n   * Not decoration. Pruning keeps rules like `html.dark .card` and\n   * `.app .list > li`, whose left-hand side lives *above* the subject — render\n   * the subtree bare and those rules match nothing, so the image is missing\n   * exactly the styling the collector went to the trouble of proving applies.\n   *\n   * Reproduced as empty open tags rather than by re-rendering the application:\n   * what a selector needs is a chain of elements with the right tags, ids,\n   * classes, and attributes, and nothing above the subject contributes anything\n   * else to it that {@link RenderDocument.inherited} does not already carry.\n   */\n  readonly frame: RenderFrame;\n\n  /**\n   * Applicable stylesheet text, in cascade order.\n   *\n   * Order is load-bearing and is the caller's to preserve — the cascade breaks\n   * specificity ties by document order, so a set that arrives shuffled paints\n   * differently while hashing the same if this were a set rather than a list.\n   */\n  readonly css: readonly string[];\n\n  readonly viewport: Viewport;\n\n  /**\n   * Inherited values in force at the subject root, applied to its wrapper.\n   *\n   * The same requirement as `RawCapture.inheritedSeed` and for the same reason:\n   * pruning drops rules on ancestors outside the subtree, and a font-size\n   * inherited from `<html>` is not optional decoration — dropping it changes\n   * every metric in the image.\n   */\n  readonly inherited: Readonly<Record<string, string>>;\n\n  /**\n   * Fonts the acquiring side observed as loaded.\n   *\n   * Carried, not resolved. A renderer that lacks one of these will substitute\n   * and produce different metrics, and that has to be *detectable* rather than\n   * silently absorbed — see {@link RenderIdentity}.\n   */\n  readonly fonts: readonly string[];\n\n  /** External references, url → content hash. Present so a swap is visible. */\n  readonly assets?: Readonly<Record<string, string>>;\n\n  /**\n   * Base against which relative resource references were resolved.\n   *\n   * Preserves relative-reference resolution for either document kind. Resource\n   * closure is denoted by `resources`, not by the presence of this field.\n   */\n  readonly baseUrl?: string;\n\n  /**\n   * Immutable responses needed to paint this document, keyed by absolute URL.\n   *\n   * Presence — including an empty object — means the document is\n   * resource-closed: a renderer must not consult the network for a missing URL.\n   * Absence preserves the older network-capable document contract and must not\n   * be described as portable to another machine.\n   */\n  readonly resources?: Readonly<Record<string, RenderResource>>;\n\n  readonly diagnostics: readonly Diagnostic[];\n}\n\nexport interface RenderResource {\n  readonly contentType: string;\n  /** Response bytes, base64. */\n  readonly bytes: string;\n  readonly digest: Digest;\n\n  /**\n   * The status a renderer answers this URL with. Absent means 200.\n   *\n   * A subject is allowed to reference something that is not there: a fallback\n   * test does it on purpose, and the browser it was acquired in painted the\n   * broken state rather than the image. Recording the failure as a failure is\n   * what lets a renderer reproduce that state without asking the network.\n   */\n  readonly status?: number;\n}\n\nexport interface RenderFrame {\n  /** Attributes on `<html>`. `class=\"dark\"` here decides half a design system. */\n  readonly html: Readonly<Record<string, string>>;\n  readonly body: Readonly<Record<string, string>>;\n  /** Elements between `<body>` and the subject root, outermost first. */\n  readonly ancestors: readonly FrameElement[];\n\n  /**\n   * Used width of the subject's parent box, in CSS pixels, when layout was\n   * observable.\n   *\n   * A subject declaring `width: 100%` is a different size in a 1024px page and\n   * inside a 600px panel, and nothing else in this document says which it was.\n   * Absent under a profile with no layout engine, in which case the render falls\n   * back to the viewport and the difference, if any, is real rather than hidden.\n   */\n  readonly containerWidth?: number;\n}\n\nexport interface FrameElement {\n  readonly tag: string;\n  readonly attributes: Readonly<Record<string, string>>;\n}\n\n/**\n * Content address of a document: *what is to be painted*.\n *\n * This is the deferral lever. Rendering is the expensive phase, and a document\n * whose digest has been rendered before under the same identity has an image\n * already — so the cheapest render is the one that is skipped. Nothing about the\n * branch, the commit, or the file path enters this (Principle 4), so moving a\n * story between files does not cost a re-render.\n *\n * Deliberately covers `viewport` in full, `deviceScaleFactor` included: unlike\n * the semantic key (ADR-0010), a raster genuinely differs at 2x and the whole\n * purpose of this digest is to address the raster.\n *\n * **Limit, stated rather than discovered.** Declaration values arrive serialized\n * by the acquiring engine's CSSOM — jsdom writes `rgb(18, 52, 86)` where the\n * author wrote `#123456` — and this phase deliberately does not canonicalize\n * them, because a collector that normalizes is a second ruleset versioned by\n * nothing (ADR-0001). So two engines can address the same page differently. That\n * makes a render cache *per acquiring engine*, which is a missed cache hit and\n * never a wrong image.\n */\nexport function documentDigest(document: RenderDocument): Digest {\n  return digestValue({\n    documentVersion: document.documentVersion,\n    html: document.html,\n    frame: {\n      html: { ...document.frame.html },\n      body: { ...document.frame.body },\n      ancestors: document.frame.ancestors.map((element) => ({\n        tag: element.tag,\n        attributes: { ...element.attributes },\n      })),\n      ...(document.frame.containerWidth !== undefined\n        ? { containerWidth: document.frame.containerWidth }\n        : {}),\n    },\n    css: [...document.css],\n    viewport: { ...document.viewport },\n    inherited: { ...document.inherited },\n    fonts: [...document.fonts],\n    ...(document.assets ? { assets: { ...document.assets } } : {}),\n    ...(document.baseUrl !== undefined ? { baseUrl: document.baseUrl } : {}),\n    ...(document.resources !== undefined\n      ? {\n          resources: Object.fromEntries(\n            Object.entries(document.resources).map(([url, resource]) => [\n              url,\n              { ...resource },\n            ]),\n          ),\n        }\n      : {}),\n  });\n}\n\n/**\n * Who painted it.\n *\n * The durable half of this system rests on one requirement — *images compared\n * against each other must come from the same machine* — and a requirement that\n * is merely stated gets violated by a CI runner upgrade nobody announced. This\n * makes it a value, so it can be compared rather than assumed.\n *\n * Every field is something that has been observed to move pixels without moving\n * markup. None of them is a guess about what *might* matter.\n */\nexport interface RenderIdentity {\n  /** `playwright-chromium@1.49.0`, `remote:render.internal`, … */\n  readonly renderer: string;\n  /** Engine build. A Chromium bump repaints text; that is not a regression. */\n  readonly engine: string;\n  /** OS and architecture. Font rasterization differs across both. */\n  readonly platform: string;\n  readonly deviceScaleFactor: number;\n  /**\n   * Fonts the *renderer* actually has.\n   *\n   * Compared against {@link RenderDocument.fonts} at render time, because a\n   * substituted font is the single most common way two machines disagree, and\n   * it is invisible in every artifact except the image itself.\n   */\n  readonly fonts: readonly string[];\n\n  /**\n   * Digest of what the renderer did *to* the page so it could be observed.\n   *\n   * Pausing animations, hiding a caret, waiting for fonts — each is necessary\n   * and each widens the gap between what was measured and what a person sees.\n   * The gap itself is acceptable; a *difference* in it between two runs is not,\n   * because the images then differ for a reason that is not the code and the\n   * report blames whichever component sits under the pixels. Folding it in here\n   * makes that comparison `incomparable` instead, by the same mechanism that\n   * refuses a cross-machine one.\n   *\n   * Optional only because a renderer may predate the field. Absent means the\n   * renderer did not record what it did, which is emphatically not the same as\n   * \"it did nothing\" — and two such renderers will compare, which is the hazard\n   * that argues for every renderer setting it.\n   */\n  readonly stabilization?: Digest;\n\n  /**\n   * Digest of pixel-affecting browser launch and raster settings.\n   *\n   * Separate from stabilization: one describes how the browser paints, the\n   * other what was done to the page before it was read.\n   */\n  readonly rasterization?: Digest;\n}\n\nexport function identityDigest(identity: RenderIdentity): Digest {\n  return digestValue({\n    renderer: identity.renderer,\n    engine: identity.engine,\n    platform: identity.platform,\n    ...(identity.stabilization !== undefined ? { stabilization: identity.stabilization } : {}),\n    ...(identity.rasterization !== undefined ? { rasterization: identity.rasterization } : {}),\n    deviceScaleFactor: identity.deviceScaleFactor,\n    fonts: [...identity.fonts],\n  });\n}\n\n/**\n * A rendered image and the conditions it was produced under.\n *\n * `bytes` is base64 rather than a `Buffer` so the whole value survives the same\n * hops the document does. A raster that could only exist in Node would make the\n * remote route a special case in every function that touches one.\n *\n * The image is optional, and the three fields that describe it move together.\n * A subject that occupies no pixels — a wrapper whose only child went to a\n * portal, a `describeConformance` mount with no children — still has a\n * document, rules, components and an accessibility tree, all of which compare.\n * Refusing to photograph it is right; refusing the subject reported a quarter\n * of Material UI's unit tier as unobserved over an axis nothing was asking\n * about. Absent here means *this subject has no pixels to observe*, which is a\n * measurement; it never means *the image was lost*.\n */\nexport interface Raster {\n  readonly documentDigest: Digest;\n  readonly identity: RenderIdentity;\n  /**\n   * Device pixels. `width / viewport.width` is the scale, and is asserted.\n   *\n   * Absent exactly when {@link bytes} is, and {@link pictured} is the one place\n   * that reads the three together.\n   */\n  readonly width?: number;\n  readonly height?: number;\n  /** PNG, base64. Absent when the subject occupies no pixels. */\n  readonly bytes?: string;\n  /** Fonts the document declared that the renderer did not have. */\n  readonly missingFonts: readonly string[];\n\n  /**\n   * The browser-computed accessibility tree from the acquisition that produced\n   * this candidate. It is independent evidence: pixel equality cannot settle it.\n   * Absent means the acquisition host did not observe this boundary.\n   */\n  readonly accessibility?: import('./accessibility.js').AccessibilitySnapshot;\n\n  /**\n   * What the document that painted this said about its own components (ADR-0018).\n   *\n   * The field that makes a baseline self-describing, and the reason it is here\n   * rather than only in a history store. Separating the component that *caused* a\n   * change from the components the change merely moved needs both revisions, and\n   * a stored baseline is an image: without this, a run has one document and ranks\n   * by area — which\n   * [journal 0013](../../../../docs/context/journal/0013-observability.md)\n   * measured as backwards.\n   *\n   * Text, and small: one line per component boundary. It rides in the sidecar\n   * beside a PNG that dominates it, so a baseline carries its own explanation\n   * wherever it is copied, and a store or a transport that drops it degrades to\n   * ranking by area rather than to a wrong answer.\n   *\n   * Optional because a baseline written before this existed does not have it, and\n   * because a profile or a collector that supplies no snapshot cannot produce it.\n   * Absent means *unknown*, never *no components*.\n   */\n  readonly components?: readonly ComponentHash[];\n\n  /**\n   * What inspection found in the document that painted this, as marks.\n   *\n   * The field that lets a later run say *this defect was already here* instead of\n   * printing every defect it finds with no indication of when it arrived. A\n   * finding is produced from one render with no baseline consulted — that is the\n   * point of having one — and the consequence is that the list is identical on\n   * the run that introduced a defect and on the two hundred runs after it. A\n   * reviewer reading `a control inside another control` has no way to tell an\n   * inherited condition from something they just wrote, and the two are different\n   * decisions.\n   *\n   * Marks rather than findings, from {@link findingMark}. The sentence, the\n   * landmark phrase and the source line are all rewritten by edits that do not\n   * touch the defect, so storing them would report a defect as new every time the\n   * copy beside it changed — and they are the bulk of the bytes, in a sidecar\n   * that is committed beside every baseline.\n   *\n   * **Absent means nothing inspected it, never that it was clean.** A baseline\n   * written before this existed, or by a collector that supplies no snapshot, has\n   * no list, and a run that read absence as `[]` would announce every standing\n   * defect in the suite as newly introduced on the first run after an upgrade.\n   */\n  readonly findingMarks?: readonly string[];\n}\n\n/**\n * A raster whose image is in hand.\n *\n * Every pixel comparison in the codebase needs all three of `bytes`, `width`\n * and `height`, and they are absent together or present together. Narrowing\n * them one at a time is how a caller ends up reading the bytes of a subject\n * that was never photographed, so the narrowing lives here and is done once.\n */\nexport type Pictured = Raster & {\n  readonly width: number;\n  readonly height: number;\n  readonly bytes: string;\n};\n\n/** Whether this record carries an image, narrowing all three fields together. */\nexport function pictured(raster: Raster): raster is Pictured {\n  return raster.bytes !== undefined && raster.width !== undefined && raster.height !== undefined;\n}\n\n/**\n * Whether the subject occupied any pixels, answered without the image.\n *\n * The question {@link pictured} cannot be asked of a sidecar. Bytes live in a\n * separate file, row or object, so a record read without them carries the width\n * and the height and nothing else — and those *are* the store's record of\n * whether there was ever anything to photograph, which is why `sidecarFrom`\n * refuses a sidecar carrying one of them.\n *\n * So: this for a record, {@link pictured} for an image in hand. A caller that\n * reached for `pictured` here would read every sidecar in the store as a subject\n * with no pixels, because none of them have bytes.\n */\nexport function occupiesPixels(raster: Omit<Raster, 'bytes'>): boolean {\n  return raster.width !== undefined && raster.height !== undefined;\n}\n\n/**\n * The image, or a refusal naming the subject that has none.\n *\n * For the paths where a missing image is a programming error rather than a\n * measurement — a diff, a PNG encode — so they read as assertions instead of\n * as a non-null assertion nobody can audit.\n */\nexport function picture(raster: Raster, subject: string): Pictured {\n  if (!pictured(raster)) {\n    throw new Error(\n      `\\`${subject}\\` occupies no pixels, and this path needs an image; ` +\n        'a subject with no raster compares on its document alone',\n    );\n  }\n  return raster;\n}\n"]}
+{"version":3,"file":"document.js","sourceRoot":"","sources":["../../src/format/document.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Diagnostic, SubjectRef } from './capture.js';\nimport type { Viewport } from './environment.js';\nimport { digestValue, type Digest } from './hash.js';\nimport { pageOrigin, withoutOrigin } from './origin.js';\nimport type { PackedSnapshot } from './packed.js';\nimport type { ComponentHash } from './snapshot.js';\n\n/**\n * The render document: what gets *sent* somewhere to become an image.\n *\n * This is the acquisition phase's output and the only thing the rendering side\n * ever sees. It is plain serializable data for the same reason `RawCapture` is\n * (ADR-0006): the renderer may be a page in this process, a browser on this\n * machine, or a pinned container two networks away, and no code upstream of it\n * may assume which.\n *\n * Two routes produce one of these, and the point of the type is that they are\n * interchangeable:\n *\n * 1. **jsdom → document → render elsewhere.** jsdom cannot rasterize. It can\n *    describe exactly what to rasterize, which is the sub-renderer split ADR-0002\n *    asks for: the cheap tier decides almost everything, and the residue is\n *    handed to something that owns a GPU.\n * 2. **playwright → document → render on a server.** The same payload, acquired\n *    from a real engine. Used when the *deciding* machine and the *pinned*\n *    machine are different, which is the case every CI setup actually has.\n *\n * A browser may instead capture a `Raster` in place. That is the sibling branch\n * of `CaptureMaterial`, not a third route that somehow produces this type.\n *\n * ## Why this is small\n *\n * `css` holds the *applicable* rules only — the pruning of ADR-0003, which on\n * `@variance-authority/dom`'s accretion fixture takes 1010 rules to 1. That\n * number is a cost claim as much as a\n * correctness one: shipping a document over a network hop is only sensible if the\n * document is not the entire design system plus Storybook's chrome.\n */\nexport interface RenderDocument {\n  readonly documentVersion: 1;\n  readonly subject: SubjectRef;\n\n  /**\n   * The subject subtree, serialized.\n   *\n   * Serialized rather than referenced by URL: a URL makes the renderer\n   * responsible for reproducing the application's state, which it cannot do and\n   * should not try. What is sent is the markup that existed at the moment of\n   * capture, which is the only definition of \"this render\" that survives a hop.\n   */\n  readonly html: string;\n\n  /**\n   * The ancestor context the subject was rendered inside.\n   *\n   * Not decoration. Pruning keeps rules like `html.dark .card` and\n   * `.app .list > li`, whose left-hand side lives *above* the subject — render\n   * the subtree bare and those rules match nothing, so the image is missing\n   * exactly the styling the collector went to the trouble of proving applies.\n   *\n   * Reproduced as empty open tags rather than by re-rendering the application:\n   * what a selector needs is a chain of elements with the right tags, ids,\n   * classes, and attributes, and nothing above the subject contributes anything\n   * else to it that {@link RenderDocument.inherited} does not already carry.\n   */\n  readonly frame: RenderFrame;\n\n  /**\n   * Applicable stylesheet text, in cascade order.\n   *\n   * Order is load-bearing and is the caller's to preserve — the cascade breaks\n   * specificity ties by document order, so a set that arrives shuffled paints\n   * differently while hashing the same if this were a set rather than a list.\n   */\n  readonly css: readonly string[];\n\n  readonly viewport: Viewport;\n\n  /**\n   * Inherited values in force at the subject root, applied to its wrapper.\n   *\n   * The same requirement as `RawCapture.inheritedSeed` and for the same reason:\n   * pruning drops rules on ancestors outside the subtree, and a font-size\n   * inherited from `<html>` is not optional decoration — dropping it changes\n   * every metric in the image.\n   */\n  readonly inherited: Readonly<Record<string, string>>;\n\n  /**\n   * Fonts the acquiring side observed as loaded.\n   *\n   * Carried, not resolved. A renderer that lacks one of these will substitute\n   * and produce different metrics, and that has to be *detectable* rather than\n   * silently absorbed — see {@link RenderIdentity}.\n   */\n  readonly fonts: readonly string[];\n\n  /** External references, url → content hash. Present so a swap is visible. */\n  readonly assets?: Readonly<Record<string, string>>;\n\n  /**\n   * Base against which relative resource references were resolved.\n   *\n   * Preserves relative-reference resolution for either document kind. Resource\n   * closure is denoted by `resources`, not by the presence of this field.\n   */\n  readonly baseUrl?: string;\n\n  /**\n   * Immutable responses needed to paint this document, keyed by absolute URL.\n   *\n   * Presence — including an empty object — means the document is\n   * resource-closed: a renderer must not consult the network for a missing URL.\n   * Absence preserves the older network-capable document contract and must not\n   * be described as portable to another machine.\n   */\n  readonly resources?: Readonly<Record<string, RenderResource>>;\n\n  readonly diagnostics: readonly Diagnostic[];\n}\n\nexport interface RenderResource {\n  readonly contentType: string;\n  /** Response bytes, base64. */\n  readonly bytes: string;\n  readonly digest: Digest;\n\n  /**\n   * The status a renderer answers this URL with. Absent means 200.\n   *\n   * A subject is allowed to reference something that is not there: a fallback\n   * test does it on purpose, and the browser it was acquired in painted the\n   * broken state rather than the image. Recording the failure as a failure is\n   * what lets a renderer reproduce that state without asking the network.\n   */\n  readonly status?: number;\n}\n\nexport interface RenderFrame {\n  /** Attributes on `<html>`. `class=\"dark\"` here decides half a design system. */\n  readonly html: Readonly<Record<string, string>>;\n  readonly body: Readonly<Record<string, string>>;\n  /** Elements between `<body>` and the subject root, outermost first. */\n  readonly ancestors: readonly FrameElement[];\n\n  /**\n   * Used `width` of the subject's parent, in CSS pixels and in the parent's own\n   * `box-sizing`, when layout was observable. Written back on the same box, it\n   * gives the content box a percentage on the subject resolves against.\n   *\n   * A subject declaring `width: 100%` is a different size in a 1024px page and\n   * inside a 600px panel, and nothing else in this document says which it was.\n   * Absent under a profile with no layout engine, in which case the render falls\n   * back to the viewport and the difference, if any, is real rather than hidden.\n   */\n  readonly containerWidth?: number;\n}\n\nexport interface FrameElement {\n  readonly tag: string;\n  readonly attributes: Readonly<Record<string, string>>;\n}\n\n/**\n * Content address of a document: *what is to be painted*.\n *\n * This is the deferral lever. Rendering is the expensive phase, and a document\n * whose digest has been rendered before under the same identity has an image\n * already — so the cheapest render is the one that is skipped. Nothing about the\n * branch, the commit, or the file path enters this (Principle 4), so moving a\n * story between files does not cost a re-render.\n *\n * Deliberately covers `viewport` in full, `deviceScaleFactor` included: unlike\n * the semantic key (ADR-0010), a raster genuinely differs at 2x and the whole\n * purpose of this digest is to address the raster.\n *\n * **Limit, stated rather than discovered.** Declaration values arrive serialized\n * by the acquiring engine's CSSOM — jsdom writes `rgb(18, 52, 86)` where the\n * author wrote `#123456` — and this phase deliberately does not canonicalize\n * them, because a collector that normalizes is a second ruleset versioned by\n * nothing (ADR-0001). So two engines can address the same page differently. That\n * makes a render cache *per acquiring engine*, which is a missed cache hit and\n * never a wrong image.\n */\nexport function documentDigest(document: RenderDocument): Digest {\n  const origin = pageOrigin(document.baseUrl);\n  return digestValue({\n    documentVersion: document.documentVersion,\n    html: document.html,\n    frame: {\n      html: { ...document.frame.html },\n      body: { ...document.frame.body },\n      ancestors: document.frame.ancestors.map((element) => ({\n        tag: element.tag,\n        attributes: { ...element.attributes },\n      })),\n      ...(document.frame.containerWidth !== undefined\n        ? { containerWidth: document.frame.containerWidth }\n        : {}),\n    },\n    css: [...document.css],\n    viewport: { ...document.viewport },\n    inherited: { ...document.inherited },\n    fonts: [...document.fonts],\n    ...(document.assets ? { assets: { ...document.assets } } : {}),\n    // The base and the page's own resources as paths: a collector serves the\n    // build on a free port, and a digest holding it would miss the render cache\n    // on every run. The document keeps both absolute, because the renderer\n    // resolves against them; a resource another origin serves stays absolute.\n    ...(document.baseUrl !== undefined ? { baseUrl: withoutOrigin(document.baseUrl, origin) } : {}),\n    ...(document.resources !== undefined\n      ? {\n          resources: Object.fromEntries(\n            Object.entries(document.resources).map(([url, resource]) => [\n              withoutOrigin(url, origin),\n              { ...resource },\n            ]),\n          ),\n        }\n      : {}),\n  });\n}\n\n/**\n * Who painted it.\n *\n * The durable half of this system rests on one requirement — *images compared\n * against each other must come from the same machine* — and a requirement that\n * is merely stated gets violated by a CI runner upgrade nobody announced. This\n * makes it a value, so it can be compared rather than assumed.\n *\n * Every field is something that has been observed to move pixels without moving\n * markup. None of them is a guess about what *might* matter.\n */\nexport interface RenderIdentity {\n  /** `playwright-chromium@1.49.0`, `remote:render.internal`, … */\n  readonly renderer: string;\n  /** Engine build. A Chromium bump repaints text; that is not a regression. */\n  readonly engine: string;\n  /** OS and architecture. Font rasterization differs across both. */\n  readonly platform: string;\n  readonly deviceScaleFactor: number;\n  /**\n   * Fonts the *renderer* actually has.\n   *\n   * Compared against {@link RenderDocument.fonts} at render time, because a\n   * substituted font is the single most common way two machines disagree, and\n   * it is invisible in every artifact except the image itself.\n   */\n  readonly fonts: readonly string[];\n\n  /**\n   * Digest of what the renderer did *to* the page so it could be observed.\n   *\n   * Pausing animations, hiding a caret, waiting for fonts — each is necessary\n   * and each widens the gap between what was measured and what a person sees.\n   * The gap itself is acceptable; a *difference* in it between two runs is not,\n   * because the images then differ for a reason that is not the code and the\n   * report blames whichever component sits under the pixels. Folding it in here\n   * names that gap as the cause of the change instead, by the same mechanism\n   * that names a moved machine.\n   *\n   * Optional only because a renderer may predate the field. Absent means the\n   * renderer did not record what it did, which is emphatically not the same as\n   * \"it did nothing\" — and two such renderers will compare, which is the hazard\n   * that argues for every renderer setting it.\n   */\n  readonly stabilization?: Digest;\n\n  /**\n   * Digest of pixel-affecting browser launch and raster settings.\n   *\n   * Separate from stabilization: one describes how the browser paints, the\n   * other what was done to the page before it was read.\n   */\n  readonly rasterization?: Digest;\n}\n\nexport function identityDigest(identity: RenderIdentity): Digest {\n  return digestValue({\n    renderer: identity.renderer,\n    engine: identity.engine,\n    platform: identity.platform,\n    ...(identity.stabilization !== undefined ? { stabilization: identity.stabilization } : {}),\n    ...(identity.rasterization !== undefined ? { rasterization: identity.rasterization } : {}),\n    deviceScaleFactor: identity.deviceScaleFactor,\n    fonts: [...identity.fonts],\n  });\n}\n\n/**\n * A rendered image and the conditions it was produced under.\n *\n * `bytes` is base64 rather than a `Buffer` so the whole value survives the same\n * hops the document does. A raster that could only exist in Node would make the\n * remote route a special case in every function that touches one.\n *\n * The image is optional, and the three fields that describe it move together.\n * A subject that occupies no pixels — a wrapper whose only child went to a\n * portal, a `describeConformance` mount with no children — still has a\n * document, rules, components and an accessibility tree, all of which compare.\n * Refusing to photograph it is right; refusing the subject reported a quarter\n * of Material UI's unit tier as unobserved over an axis nothing was asking\n * about. Absent here means *this subject has no pixels to observe*, which is a\n * measurement; it never means *the image was lost*.\n */\nexport interface Raster {\n  readonly documentDigest: Digest;\n  readonly identity: RenderIdentity;\n  /**\n   * Device pixels. `width / viewport.width` is the scale, and is asserted.\n   *\n   * Absent exactly when {@link bytes} is, and {@link pictured} is the one place\n   * that reads the three together.\n   */\n  readonly width?: number;\n  readonly height?: number;\n  /** PNG, base64. Absent when the subject occupies no pixels. */\n  readonly bytes?: string;\n  /** Fonts the document declared that the renderer did not have. */\n  readonly missingFonts: readonly string[];\n\n  /**\n   * The browser-computed accessibility tree from the acquisition that produced\n   * this candidate. It is independent evidence: pixel equality cannot settle it.\n   * Absent means the acquisition host did not observe this boundary.\n   */\n  readonly accessibility?: import('./accessibility.js').AccessibilitySnapshot;\n\n  /**\n   * What the document that painted this said about its own components (ADR-0018).\n   *\n   * The field that makes a baseline self-describing, and the reason it is here\n   * rather than only in a history store. Separating the component that *caused* a\n   * change from the components the change merely moved needs both revisions, and\n   * a stored baseline is an image: without this, a run has one document and ranks\n   * by area — which\n   * [journal 0013](https://github.com/Variance-Authority/variance-authority/blob/main/docs/context/journal/0013-observability.md)\n   * measured as backwards.\n   *\n   * Text, and small: one line per component boundary. It rides in the sidecar\n   * beside a PNG that dominates it, so a baseline carries its own explanation\n   * wherever it is copied, and a store or a transport that drops it degrades to\n   * ranking by area rather than to a wrong answer.\n   *\n   * Optional because a baseline written before this existed does not have it, and\n   * because a profile or a collector that supplies no snapshot cannot produce it.\n   * Absent means *unknown*, never *no components*.\n   */\n  readonly components?: readonly ComponentHash[];\n\n  /**\n   * What inspection found in the document that painted this, as marks.\n   *\n   * The field that lets a later run say *this defect was already here* instead of\n   * printing every defect it finds with no indication of when it arrived. A\n   * finding is produced from one render with no baseline consulted — that is the\n   * point of having one — and the consequence is that the list is identical on\n   * the run that introduced a defect and on the two hundred runs after it. A\n   * reviewer reading `a control inside another control` has no way to tell an\n   * inherited condition from something they just wrote, and the two are different\n   * decisions.\n   *\n   * Marks rather than findings, from {@link findingMark}. The sentence, the\n   * landmark phrase and the source line are all rewritten by edits that do not\n   * touch the defect, so storing them would report a defect as new every time the\n   * copy beside it changed — and they are the bulk of the bytes, in a sidecar\n   * that is committed beside every baseline.\n   *\n   * **Absent means nothing inspected it, never that it was clean.** A baseline\n   * written before this existed, or by a collector that supplies no snapshot, has\n   * no list, and a run that read absence as `[]` would announce every standing\n   * defect in the suite as newly introduced on the first run after an upgrade.\n   */\n  readonly findingMarks?: readonly string[];\n\n  /**\n   * The semantic snapshot of the document that painted this, packed.\n   *\n   * The region join needs to know where each element was in the render the\n   * pixels are compared against. A changed region is the union of what left and\n   * what arrived, and a stored baseline is an image: without its own tree, a\n   * control replaced by a larger element changes pixels outside every box this\n   * render has, and the join names the row around it. With it, the join pairs\n   * the two renders' nodes with the matcher the semantic diff reads, so a\n   * region and a delta agree about which element a node was.\n   *\n   * Packed (see {@link PackedSnapshot}) because the tree is an order of\n   * magnitude larger than the component hashes, and it rides in every sidecar.\n   * Every store and transport carries the text as it is, and only the run that\n   * decides unpacks it.\n   *\n   * **Absent means not recorded.** A baseline written before this existed, or\n   * from a collector that supplied no snapshot, has none, and a verdict whose\n   * regions were joined without it says so.\n   */\n  readonly snapshot?: PackedSnapshot;\n}\n\n/**\n * A raster whose image is in hand.\n *\n * Every pixel comparison in the codebase needs all three of `bytes`, `width`\n * and `height`, and they are absent together or present together. Narrowing\n * them one at a time is how a caller ends up reading the bytes of a subject\n * that was never photographed, so the narrowing lives here and is done once.\n */\nexport type Pictured = Raster & {\n  readonly width: number;\n  readonly height: number;\n  readonly bytes: string;\n};\n\n/** Whether this record carries an image, narrowing all three fields together. */\nexport function pictured(raster: Raster): raster is Pictured {\n  return raster.bytes !== undefined && raster.width !== undefined && raster.height !== undefined;\n}\n\n/**\n * Whether the subject occupied any pixels, answered without the image.\n *\n * The question {@link pictured} cannot be asked of a sidecar. Bytes live in a\n * separate file, row or object, so a record read without them carries the width\n * and the height and nothing else — and those *are* the store's record of\n * whether there was ever anything to photograph, which is why `sidecarFrom`\n * refuses a sidecar carrying one of them.\n *\n * So: this for a record, {@link pictured} for an image in hand. A caller that\n * reached for `pictured` here would read every sidecar in the store as a subject\n * with no pixels, because none of them have bytes.\n */\nexport function occupiesPixels(raster: Omit<Raster, 'bytes'>): boolean {\n  return raster.width !== undefined && raster.height !== undefined;\n}\n\n/**\n * The image, or a refusal naming the subject that has none.\n *\n * For the paths where a missing image is a programming error rather than a\n * measurement — a diff, a PNG encode — so they read as assertions instead of\n * as a non-null assertion nobody can audit.\n */\nexport function picture(raster: Raster, subject: string): Pictured {\n  if (!pictured(raster)) {\n    throw new Error(\n      `\\`${subject}\\` occupies no pixels, and this path needs an image; ` +\n        'a subject with no raster compares on its document alone',\n    );\n  }\n  return raster;\n}\n"]}

package/dist/format/drive.d.ts

@@ -0,0 +1,191 @@
+import type { DriverTarget, Intervention } from './intervention.js';
+/**
+ * The tricks a stylesheet cannot reach, and the one call each makes of a driver.
+ *
+ * Every other trick in [`stabilize.ts`](./stabilize.ts) is CSS, a screenshot
+ * option or a script the page runs on itself. Three causes of a page that reads
+ * two ways sit outside the document:
+ *
+ * - **the motion preference** — a page that honours `prefers-reduced-motion`
+ *   runs its script animation only when the browser says motion is welcome, and
+ *   a stylesheet cannot reach a `requestAnimationFrame` loop;
+ * - **the clock** — a page that prints `new Date()` prints a new value every
+ *   run, and the date is read by the page's first script, before any stylesheet
+ *   or settle step exists, so it is replaced by a script the browser runs before
+ *   the page's own;
+ * - **the pointer** — a hover ends when the pointer leaves, and nothing in the
+ *   page can move it.
+ *
+ * So each is declared as a {@link DriverState} and applied here, through the
+ * structural {@link DriverTarget} a Playwright `Page` already is. A host that
+ * owns the browser calls {@link driveBeforeLoad} before its first navigation
+ * and hands the page the ids it applied. A host that shares the page with
+ * somebody who moves the pointer, such as a test, also calls
+ * {@link driveBeforeRead} before each subject is read. A host that does not — a page agent, a test runner's own
+ * browser — drives nothing, and {@link forDriver} keeps those tricks out of its
+ * recorded recipe, so the absence shows in the reading's ids and digest the way
+ * a trick filtered by `needs` does.
+ */
+/**
+ * The instant a fixed clock reads unless a project names another.
+ *
+ * Noon UTC, so it is the same calendar date in every zone from UTC−11 to
+ * UTC+11: a page that prints today's date prints one date whichever zone the
+ * browser runs in. A date in the past, so a page that compares against "now"
+ * to show something as expired does so on every run or on none.
+ */
+export declare const DEFAULT_NOW = "2024-06-15T12:00:00.000Z";
+/**
+ * The milliseconds an ISO 8601 instant names, or an error that says what an
+ * instant is.
+ *
+ * The zone is required. `2024-06-15T12:00` with no zone is read in whatever
+ * zone the machine runs in, so two machines would fix two clocks — the
+ * variance this trick exists to remove.
+ */
+export declare function instantOf(now: string): number;
+/**
+ * `prefers-reduced-motion: reduce`, the switch a well-built page already reads.
+ *
+ * It reaches what `pin-animations` cannot: a script animation, which a
+ * stylesheet has no handle on. It reaches only a page that honours the
+ * preference, and that is the cost: the page is read as a user who asked for
+ * less motion sees it, which can differ from what everybody else sees.
+ */
+export declare const reducedMotion: Intervention;
+/**
+ * `Date` reads one instant; timers, animation frames and `performance` keep
+ * running.
+ *
+ * An init script, {@link freezeDate}, run in every frame before the page's own
+ * first script. It replaces `Date` and nothing else, because the thing that
+ * prints two ways is the date a page shows, and the things that make a page
+ * settle are timers and frames. Playwright's `clock.setFixedTime` was measured
+ * against it and rejected: it installs a fake for `setTimeout`,
+ * `requestAnimationFrame` and `performance.now` as well, and a frame's
+ * timestamp no longer agrees with `document.timeline`, which drives every CSS
+ * and Web Animations frame. Installing no clock also leaves `page.clock` to the
+ * test that wants one.
+ *
+ * The id carries the instant when it is not {@link DEFAULT_NOW}, as
+ * `freeze-clock@2031-01-02T03:04:05.000Z`, so the instant is in the recipe's
+ * digest and so in the environment key: a baseline read at one instant and a
+ * run read at another are compared, and the instant is named as the cause of
+ * whatever changed.
+ *
+ * The cost: code that measures elapsed time with `Date.now()`, such as a
+ * debounce, sees no time pass and never fires. `performance.now()` keeps
+ * counting.
+ */
+export declare function freezeClockAt(now: string): Intervention;
+/** {@link freezeClockAt} the default instant, {@link DEFAULT_NOW}. */
+export declare const freezeClock: Intervention;
+/**
+ * The clock trick a `freeze-clock@<instant>` id names, or undefined for any
+ * other id.
+ *
+ * The registry holds `freeze-clock` alone; an id with an instant in it is
+ * resolved here, so a recipe that crossed into a page as ids keeps its instant.
+ */
+export declare function clockById(id: string): Intervention | undefined;
+/**
+ * The init script {@link freezeClock} installs: `Date` answers `frozen`, and
+ * nothing else changes.
+ *
+ * Runs in the page, so it closes over nothing. `new Date()`, `Date()` and
+ * `Date.now()` read the instant; `new Date(value)`, `Date.UTC`, `Date.parse`
+ * and every method on a date are the browser's own. `Intl.DateTimeFormat`'s
+ * `format()` and `formatToParts()` with no date read the browser's clock rather
+ * than `Date`, so they are given the instant too.
+ */
+export declare function freezeDate(frozen: number): void;
+/**
+ * The pointer moved off the page, so nothing is hovered.
+ *
+ * To `(-1, -1)` rather than to the page's corner: content at the top left is
+ * under `(0, 0)` and stays hovered there. `pointer-events: none` is not a
+ * substitute — measured, an element already hovered keeps `:hover` under it.
+ *
+ * Once per page, before load, where nothing but the host moves the pointer. A
+ * move is acknowledged on the next frame, ~14 ms measured, so a host that alone
+ * drives its page does not move it again. A host that shares the page with a
+ * test does, before every reading: see {@link driveBeforeRead}.
+ */
+export declare const noHover: Intervention;
+/**
+ * Nothing focused, so a field a test filled or a page focused on load reads
+ * as it does untouched.
+ *
+ * A settle step rather than a stylesheet: `:focus` and `:focus-visible` follow
+ * the element that holds focus, and no rule can unmatch them. It blurs the
+ * deepest focused element, walking through shadow roots, because a shadow host
+ * is the document's `activeElement` for whatever its tree focused, and blurring
+ * the host leaves the input inside it focused and outlined.
+ *
+ * The cost: a page evaluate per subject, and an animation frame as well when
+ * the document holds an `[autofocus]`. A host that reads a page somebody goes
+ * on using — a test, an agent's browser — gives focus back once the reading
+ * is taken; a host that owns its page does not need to.
+ */
+export declare const noFocus: Intervention;
+/**
+ * The tricks that put a page into the state nobody is touching, in every
+ * default collection recipe whose tier can see them.
+ *
+ * A hover, a focus, a script animation and a printed date are each a second
+ * reading of one subject, and each comes from something other than the code
+ * under review. Three of them reach the page only through a driver, so a host
+ * that cannot drive one leaves it out of the ids it records — see {@link forDriver}.
+ */
+export declare const UNTOUCHED: readonly Intervention[];
+/**
+ * The media features a recipe's driver tricks make the browser report, merged
+ * under the ones a project declared, or undefined when there are none.
+ *
+ * Collection resolves `@media` against declared features, not against the
+ * browser, so a preference the driver emulated and nobody declared would be
+ * read as unknown: both the `reduce` and the `no-preference` block applied, a
+ * box the browser never drew. Declaring what the trick emulates gives the
+ * preference one owner. A project's own value wins, and
+ * {@link driveBeforeLoad} emulates that value, so the two still agree.
+ */
+export declare function featuresOf(recipe: readonly Intervention[], declared?: Readonly<Record<string, string>>): Readonly<Record<string, string>> | undefined;
+/**
+ * Apply what a recipe asks of the browser before the page loads.
+ *
+ * All three survive navigation, so a host calls this once per page, before its
+ * first `goto` or `setContent`. Returns the ids applied, in recipe order. The
+ * clock's instant is the trick's own, so a host that wants another instant
+ * asks `recipeToDrive` for the recipe rather than telling this.
+ *
+ * `declared` is the media features the project declared. A declared
+ * `prefers-reduced-motion` is what the motion trick emulates, so the browser
+ * reports what the record says; see {@link featuresOf}.
+ */
+export declare function driveBeforeLoad(recipe: readonly Intervention[], target: DriverTarget, declared?: Readonly<Record<string, string>>): Promise<readonly string[]>;
+/**
+ * Take the pointer off the page again before a subject is read.
+ *
+ * For a host that shares the page: a test hovers a menu to open it and then
+ * observes, so the pointer is wherever the test's last step left it. A host
+ * that alone drives its page needs only {@link driveBeforeLoad}.
+ *
+ * Every reading pays the frame, hovered or not: measured in Chromium, a
+ * Playwright hover restyles the element while `:hover` matches nothing from
+ * script, so the page cannot say whether the move is needed. The pointer is
+ * not put back afterwards, and the move fires `mouseleave`: a menu a script
+ * opened on hover is closed for the test's next step.
+ */
+export declare function driveBeforeRead(recipe: readonly Intervention[], target: Pick<DriverTarget, 'mouse'>): Promise<readonly string[]>;
+/**
+ * The recipe as it holds on a page, given the driver tricks a host applied.
+ *
+ * A trick with no `driver` is kept. A trick with one is kept only when its id
+ * is in `driven`: a host that could not drive it leaves it out of the ids and
+ * the digest it records, rather than claiming a hold the page never had. The
+ * clock is the one trick whose id the driver may change, because the instant is
+ * the host's to choose: the recipe's clock is recorded as the one the host
+ * fixed.
+ */
+export declare function forDriver(recipe: readonly Intervention[], driven: readonly string[]): readonly Intervention[];
+//# sourceMappingURL=drive.d.ts.map

package/dist/format/drive.js

@@ -0,0 +1,343 @@
+/**
+ * The tricks a stylesheet cannot reach, and the one call each makes of a driver.
+ *
+ * Every other trick in [`stabilize.ts`](./stabilize.ts) is CSS, a screenshot
+ * option or a script the page runs on itself. Three causes of a page that reads
+ * two ways sit outside the document:
+ *
+ * - **the motion preference** — a page that honours `prefers-reduced-motion`
+ *   runs its script animation only when the browser says motion is welcome, and
+ *   a stylesheet cannot reach a `requestAnimationFrame` loop;
+ * - **the clock** — a page that prints `new Date()` prints a new value every
+ *   run, and the date is read by the page's first script, before any stylesheet
+ *   or settle step exists, so it is replaced by a script the browser runs before
+ *   the page's own;
+ * - **the pointer** — a hover ends when the pointer leaves, and nothing in the
+ *   page can move it.
+ *
+ * So each is declared as a {@link DriverState} and applied here, through the
+ * structural {@link DriverTarget} a Playwright `Page` already is. A host that
+ * owns the browser calls {@link driveBeforeLoad} before its first navigation
+ * and hands the page the ids it applied. A host that shares the page with
+ * somebody who moves the pointer, such as a test, also calls
+ * {@link driveBeforeRead} before each subject is read. A host that does not — a page agent, a test runner's own
+ * browser — drives nothing, and {@link forDriver} keeps those tricks out of its
+ * recorded recipe, so the absence shows in the reading's ids and digest the way
+ * a trick filtered by `needs` does.
+ */
+/**
+ * The instant a fixed clock reads unless a project names another.
+ *
+ * Noon UTC, so it is the same calendar date in every zone from UTC−11 to
+ * UTC+11: a page that prints today's date prints one date whichever zone the
+ * browser runs in. A date in the past, so a page that compares against "now"
+ * to show something as expired does so on every run or on none.
+ */
+export const DEFAULT_NOW = '2024-06-15T12:00:00.000Z';
+const INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/;
+/**
+ * The milliseconds an ISO 8601 instant names, or an error that says what an
+ * instant is.
+ *
+ * The zone is required. `2024-06-15T12:00` with no zone is read in whatever
+ * zone the machine runs in, so two machines would fix two clocks — the
+ * variance this trick exists to remove.
+ */
+export function instantOf(now) {
+    const time = INSTANT.test(now) ? Date.parse(now) : Number.NaN;
+    if (Number.isNaN(time)) {
+        throw new Error('`now` must be an ISO 8601 instant with its zone, such as "2024-06-15T12:00:00Z" or ' +
+            `"2024-06-15T14:00:00+02:00", not ${JSON.stringify(now)}`);
+    }
+    return time;
+}
+/**
+ * `prefers-reduced-motion: reduce`, the switch a well-built page already reads.
+ *
+ * It reaches what `pin-animations` cannot: a script animation, which a
+ * stylesheet has no handle on. It reaches only a page that honours the
+ * preference, and that is the cost: the page is read as a user who asked for
+ * less motion sees it, which can differ from what everybody else sees.
+ */
+export const reducedMotion = {
+    id: 'reduced-motion',
+    trick: 'reset',
+    needs: 'layout',
+    governs: 'motion-preference',
+    because: 'the browser reports prefers-reduced-motion: reduce, so a page that honours it stops its script animations',
+    driver: { reducedMotion: 'reduce' },
+};
+const CLOCK_ID = 'freeze-clock';
+/**
+ * `Date` reads one instant; timers, animation frames and `performance` keep
+ * running.
+ *
+ * An init script, {@link freezeDate}, run in every frame before the page's own
+ * first script. It replaces `Date` and nothing else, because the thing that
+ * prints two ways is the date a page shows, and the things that make a page
+ * settle are timers and frames. Playwright's `clock.setFixedTime` was measured
+ * against it and rejected: it installs a fake for `setTimeout`,
+ * `requestAnimationFrame` and `performance.now` as well, and a frame's
+ * timestamp no longer agrees with `document.timeline`, which drives every CSS
+ * and Web Animations frame. Installing no clock also leaves `page.clock` to the
+ * test that wants one.
+ *
+ * The id carries the instant when it is not {@link DEFAULT_NOW}, as
+ * `freeze-clock@2031-01-02T03:04:05.000Z`, so the instant is in the recipe's
+ * digest and so in the environment key: a baseline read at one instant and a
+ * run read at another are compared, and the instant is named as the cause of
+ * whatever changed.
+ *
+ * The cost: code that measures elapsed time with `Date.now()`, such as a
+ * debounce, sees no time pass and never fires. `performance.now()` keeps
+ * counting.
+ */
+export function freezeClockAt(now) {
+    const at = instantOf(now);
+    return {
+        id: at === instantOf(DEFAULT_NOW) ? CLOCK_ID : `${CLOCK_ID}@${new Date(at).toISOString()}`,
+        trick: 'hold',
+        needs: 'layout',
+        governs: 'clock',
+        because: 'Date reads one fixed instant, so elapsed time measured with Date.now() reads zero',
+        driver: { clock: { at } },
+    };
+}
+/** {@link freezeClockAt} the default instant, {@link DEFAULT_NOW}. */
+export const freezeClock = freezeClockAt(DEFAULT_NOW);
+/**
+ * The clock trick a `freeze-clock@<instant>` id names, or undefined for any
+ * other id.
+ *
+ * The registry holds `freeze-clock` alone; an id with an instant in it is
+ * resolved here, so a recipe that crossed into a page as ids keeps its instant.
+ */
+export function clockById(id) {
+    return id.startsWith(`${CLOCK_ID}@`) ? freezeClockAt(id.slice(CLOCK_ID.length + 1)) : undefined;
+}
+/**
+ * The init script {@link freezeClock} installs: `Date` answers `frozen`, and
+ * nothing else changes.
+ *
+ * Runs in the page, so it closes over nothing. `new Date()`, `Date()` and
+ * `Date.now()` read the instant; `new Date(value)`, `Date.UTC`, `Date.parse`
+ * and every method on a date are the browser's own. `Intl.DateTimeFormat`'s
+ * `format()` and `formatToParts()` with no date read the browser's clock rather
+ * than `Date`, so they are given the instant too.
+ */
+export function freezeDate(frozen) {
+    // TODO: `Temporal.Now` and a worker's `Date` read the real clock. This runs
+    // in each frame's window and replaces `Date` alone, so a page that prints a
+    // date from either prints a second reading.
+    const Real = Date;
+    function Frozen(...args) {
+        if (new.target === undefined)
+            return new Real(frozen).toString();
+        return Reflect.construct(Real, args.length === 0 ? [frozen] : args, new.target);
+    }
+    Object.setPrototypeOf(Frozen, Real);
+    Object.defineProperties(Frozen, {
+        prototype: { value: Real.prototype },
+        name: { value: 'Date' },
+        length: { value: 7 },
+        now: { value: () => frozen, writable: true, configurable: true },
+    });
+    Object.defineProperty(Real.prototype, 'constructor', { value: Frozen, writable: true, configurable: true });
+    Object.defineProperty(globalThis, 'Date', { value: Frozen, writable: true, configurable: true });
+    const format = Intl.DateTimeFormat.prototype;
+    const formatting = Object.getOwnPropertyDescriptor(format, 'format')?.get;
+    if (formatting !== undefined) {
+        Object.defineProperty(format, 'format', {
+            configurable: true,
+            get() {
+                const bound = formatting.call(this);
+                return (date) => bound(date === undefined ? frozen : date);
+            },
+        });
+    }
+    const toParts = format.formatToParts;
+    Object.defineProperty(format, 'formatToParts', {
+        configurable: true,
+        writable: true,
+        value(date) {
+            return toParts.call(this, date === undefined ? frozen : date);
+        },
+    });
+}
+/**
+ * The pointer moved off the page, so nothing is hovered.
+ *
+ * To `(-1, -1)` rather than to the page's corner: content at the top left is
+ * under `(0, 0)` and stays hovered there. `pointer-events: none` is not a
+ * substitute — measured, an element already hovered keeps `:hover` under it.
+ *
+ * Once per page, before load, where nothing but the host moves the pointer. A
+ * move is acknowledged on the next frame, ~14 ms measured, so a host that alone
+ * drives its page does not move it again. A host that shares the page with a
+ * test does, before every reading: see {@link driveBeforeRead}.
+ */
+export const noHover = {
+    id: 'no-hover',
+    trick: 'reset',
+    needs: 'layout',
+    governs: 'pointer',
+    because: 'the pointer moved off the page, so a hover a test left behind is not read',
+    driver: { pointer: 'outside' },
+};
+/**
+ * Nothing focused, so a field a test filled or a page focused on load reads
+ * as it does untouched.
+ *
+ * A settle step rather than a stylesheet: `:focus` and `:focus-visible` follow
+ * the element that holds focus, and no rule can unmatch them. It blurs the
+ * deepest focused element, walking through shadow roots, because a shadow host
+ * is the document's `activeElement` for whatever its tree focused, and blurring
+ * the host leaves the input inside it focused and outlined.
+ *
+ * The cost: a page evaluate per subject, and an animation frame as well when
+ * the document holds an `[autofocus]`. A host that reads a page somebody goes
+ * on using — a test, an agent's browser — gives focus back once the reading
+ * is taken; a host that owns its page does not need to.
+ */
+export const noFocus = {
+    id: 'no-focus',
+    trick: 'reset',
+    needs: 'layout',
+    governs: 'focus',
+    because: 'focus released, so a field a test or the page focused is read unfocused',
+    // Again in a frame callback when the document holds an `autofocus`, because
+    // the browser honours one at the page's next rendering update: a blur before
+    // it is undone, and a document written by `setContent` has had no update yet.
+    // Only then, so a page without one pays no frame per subject.
+    settle: async (target) => {
+        await target.evaluate(() => new Promise((resolve) => {
+            const view = globalThis;
+            const release = () => {
+                let focused = view.document.activeElement;
+                while (focused?.shadowRoot?.activeElement != null)
+                    focused = focused.shadowRoot.activeElement;
+                focused?.blur?.();
+            };
+            release();
+            if (view.document.querySelector('[autofocus]') === null)
+                return resolve();
+            view.requestAnimationFrame(() => {
+                release();
+                resolve();
+            });
+        }));
+    },
+};
+/**
+ * The tricks that put a page into the state nobody is touching, in every
+ * default collection recipe whose tier can see them.
+ *
+ * A hover, a focus, a script animation and a printed date are each a second
+ * reading of one subject, and each comes from something other than the code
+ * under review. Three of them reach the page only through a driver, so a host
+ * that cannot drive one leaves it out of the ids it records — see {@link forDriver}.
+ */
+export const UNTOUCHED = [noHover, noFocus, reducedMotion, freezeClock];
+const MOTION = 'prefers-reduced-motion';
+/**
+ * The media features a recipe's driver tricks make the browser report, merged
+ * under the ones a project declared, or undefined when there are none.
+ *
+ * Collection resolves `@media` against declared features, not against the
+ * browser, so a preference the driver emulated and nobody declared would be
+ * read as unknown: both the `reduce` and the `no-preference` block applied, a
+ * box the browser never drew. Declaring what the trick emulates gives the
+ * preference one owner. A project's own value wins, and
+ * {@link driveBeforeLoad} emulates that value, so the two still agree.
+ */
+export function featuresOf(recipe, declared) {
+    const motion = recipe.find((intervention) => intervention.driver?.reducedMotion !== undefined);
+    const features = {
+        ...(motion === undefined ? {} : { [MOTION]: motion.driver.reducedMotion }),
+        ...declared,
+    };
+    return Object.keys(features).length === 0 ? undefined : features;
+}
+/**
+ * Apply what a recipe asks of the browser before the page loads.
+ *
+ * All three survive navigation, so a host calls this once per page, before its
+ * first `goto` or `setContent`. Returns the ids applied, in recipe order. The
+ * clock's instant is the trick's own, so a host that wants another instant
+ * asks `recipeToDrive` for the recipe rather than telling this.
+ *
+ * `declared` is the media features the project declared. A declared
+ * `prefers-reduced-motion` is what the motion trick emulates, so the browser
+ * reports what the record says; see {@link featuresOf}.
+ */
+export async function driveBeforeLoad(recipe, target, declared) {
+    const applied = [];
+    for (const intervention of recipe) {
+        const driver = intervention.driver;
+        if (driver?.pointer === 'outside') {
+            await target.mouse.move(-1, -1);
+            applied.push(intervention.id);
+        }
+        else if (driver?.reducedMotion !== undefined) {
+            const preference = motionOf(declared?.[MOTION] ?? driver.reducedMotion);
+            await target.emulateMedia({ reducedMotion: preference });
+            // A declared `no-preference` is emulated and recorded among the features;
+            // the trick's id would claim a reduced motion the page never had.
+            if (preference === driver.reducedMotion)
+                applied.push(intervention.id);
+        }
+        else if (driver?.clock !== undefined) {
+            await target.addInitScript(freezeDate, driver.clock.at);
+            applied.push(intervention.id);
+        }
+    }
+    return applied;
+}
+function motionOf(value) {
+    if (value === 'reduce' || value === 'no-preference')
+        return value;
+    throw new Error(`\`${MOTION}\` is declared as ${JSON.stringify(value)}, which no browser reports; ` +
+        'declare "reduce" or "no-preference"');
+}
+/**
+ * Take the pointer off the page again before a subject is read.
+ *
+ * For a host that shares the page: a test hovers a menu to open it and then
+ * observes, so the pointer is wherever the test's last step left it. A host
+ * that alone drives its page needs only {@link driveBeforeLoad}.
+ *
+ * Every reading pays the frame, hovered or not: measured in Chromium, a
+ * Playwright hover restyles the element while `:hover` matches nothing from
+ * script, so the page cannot say whether the move is needed. The pointer is
+ * not put back afterwards, and the move fires `mouseleave`: a menu a script
+ * opened on hover is closed for the test's next step.
+ */
+export async function driveBeforeRead(recipe, target) {
+    const applied = [];
+    for (const intervention of recipe) {
+        if (intervention.driver?.pointer === 'outside') {
+            await target.mouse.move(-1, -1);
+            applied.push(intervention.id);
+        }
+    }
+    return applied;
+}
+/**
+ * The recipe as it holds on a page, given the driver tricks a host applied.
+ *
+ * A trick with no `driver` is kept. A trick with one is kept only when its id
+ * is in `driven`: a host that could not drive it leaves it out of the ids and
+ * the digest it records, rather than claiming a hold the page never had. The
+ * clock is the one trick whose id the driver may change, because the instant is
+ * the host's to choose: the recipe's clock is recorded as the one the host
+ * fixed.
+ */
+export function forDriver(recipe, driven) {
+    const fixed = driven.map((id) => (id === freezeClock.id ? freezeClock : clockById(id))).find(Boolean);
+    return recipe.flatMap((intervention) => {
+        if (intervention.driver === undefined || driven.includes(intervention.id))
+            return [intervention];
+        return intervention.driver.clock !== undefined && fixed !== undefined ? [fixed] : [];
+    });
+}
+//# sourceMappingURL=drive.js.map