@orkestrel/test 0.0.17 → 0.0.19

package/dist/src/browser/index.d.ts

@@ -506,6 +506,193 @@ export declare interface ContrastFixture {
     readonly accepted: HTMLElement;
 }
 
+/**
+ * Converts encoded A98 RGB channels to clipped sRGB paint channels.
+ *
+ * @param red - The normalized encoded red channel.
+ * @param green - The normalized encoded green channel.
+ * @param blue - The normalized encoded blue channel.
+ * @param alpha - The opacity. Default: `1`.
+ * @returns Frozen straight sRGB channels clipped to 0–255, with alpha clipped to 0–1.
+ *
+ * @remarks
+ * Decodes the signed 563/256 power curve and uses the CSS Color 4 A98 RGB to XYZ D65 matrix.
+ *
+ * @example
+ * ```ts
+ * convertA98RGB(0, 0, 0) // [0, 0, 0, 1]
+ * ```
+ */
+export declare function convertA98RGB(red: number, green: number, blue: number, alpha?: number): Color;
+
+/**
+ * Converts encoded Display P3 channels to clipped sRGB paint channels.
+ *
+ * @param red - The normalized encoded red channel.
+ * @param green - The normalized encoded green channel.
+ * @param blue - The normalized encoded blue channel.
+ * @param alpha - The opacity. Default: `1`.
+ * @returns Frozen straight sRGB channels clipped to 0–255, with alpha clipped to 0–1.
+ *
+ * @remarks
+ * Decodes the extended sRGB transfer curve and uses the CSS Color 4 P3 to XYZ D65 matrix.
+ *
+ * @example
+ * ```ts
+ * convertDisplayP3(0, 0, 0) // [0, 0, 0, 1]
+ * ```
+ */
+export declare function convertDisplayP3(red: number, green: number, blue: number, alpha?: number): Color;
+
+/**
+ * Converts CIE Lab coordinates relative to D50 to clipped sRGB paint channels.
+ *
+ * @param lightness - The CIE lightness on the 0–100 scale.
+ * @param a - The signed green-to-red axis.
+ * @param b - The signed blue-to-yellow axis.
+ * @param alpha - The opacity. Default: `1`.
+ * @returns Frozen straight sRGB channels clipped to 0–255, with alpha clipped to 0–1.
+ *
+ * @remarks
+ * Resolves the CSS Color 4 Lab curve against the D50 white point before adapting to D65.
+ *
+ * @example
+ * ```ts
+ * convertLab(0, 0, 0) // [0, 0, 0, 1]
+ * ```
+ */
+export declare function convertLab(lightness: number, a: number, b: number, alpha?: number): Color;
+
+/**
+ * Converts linear sRGB channels to encoded, clipped paint channels.
+ *
+ * @param red - The linear red channel on the normalized scale.
+ * @param green - The linear green channel.
+ * @param blue - The linear blue channel.
+ * @param alpha - The opacity. Default: `1`.
+ * @returns Frozen straight sRGB channels clipped to 0–255, with alpha clipped to 0–1.
+ *
+ * @remarks
+ * Applies the CSS Color 4 extended sRGB transfer function before clipping.
+ *
+ * @example
+ * ```ts
+ * convertLinearSRGB(0, 0, 0) // [0, 0, 0, 1]
+ * ```
+ */
+export declare function convertLinearSRGB(red: number, green: number, blue: number, alpha?: number): Color;
+
+/**
+ * Converts OKLab coordinates to clipped sRGB paint channels.
+ *
+ * @param lightness - The OKLab lightness on the 0–1 scale.
+ * @param a - The signed green-to-red axis.
+ * @param b - The signed blue-to-yellow axis.
+ * @param alpha - The opacity. Default: `1`.
+ * @returns Frozen straight sRGB channels clipped to 0–255, with alpha clipped to 0–1.
+ *
+ * @remarks
+ * Cubes the transformed cone responses before applying the linear sRGB matrix.
+ *
+ * @example
+ * ```ts
+ * convertOKLab(0, 0, 0) // [0, 0, 0, 1]
+ * ```
+ */
+export declare function convertOKLab(lightness: number, a: number, b: number, alpha?: number): Color;
+
+/**
+ * Converts encoded ProPhoto RGB channels to clipped sRGB paint channels.
+ *
+ * @param red - The normalized encoded red channel.
+ * @param green - The normalized encoded green channel.
+ * @param blue - The normalized encoded blue channel.
+ * @param alpha - The opacity. Default: `1`.
+ * @returns Frozen straight sRGB channels clipped to 0–255, with alpha clipped to 0–1.
+ *
+ * @remarks
+ * Decodes the signed ProPhoto curve, converts to XYZ D50, and adapts to D65 before clipping.
+ *
+ * @example
+ * ```ts
+ * convertProPhotoRGB(0, 0, 0) // [0, 0, 0, 1]
+ * ```
+ */
+export declare function convertProPhotoRGB(red: number, green: number, blue: number, alpha?: number): Color;
+
+/**
+ * Converts encoded Rec. 2020 channels to clipped sRGB paint channels.
+ *
+ * @param red - The normalized encoded red channel.
+ * @param green - The normalized encoded green channel.
+ * @param blue - The normalized encoded blue channel.
+ * @param alpha - The opacity. Default: `1`.
+ * @returns Frozen straight sRGB channels clipped to 0–255, with alpha clipped to 0–1.
+ *
+ * @remarks
+ * Uses the piecewise Rec. 2020 transfer curve Chromium computes and the CSS Color 4 XYZ matrix.
+ *
+ * @example
+ * ```ts
+ * convertRec2020(0, 0, 0) // [0, 0, 0, 1]
+ * ```
+ */
+export declare function convertRec2020(red: number, green: number, blue: number, alpha?: number): Color;
+
+/**
+ * Converts normalized encoded sRGB channels to the clipped paint scale.
+ *
+ * @param red - The encoded red channel, with `1` representing full intensity.
+ * @param green - The encoded green channel.
+ * @param blue - The encoded blue channel.
+ * @param alpha - The opacity. Default: `1`.
+ * @returns Frozen straight sRGB channels clipped to 0–255, with alpha clipped to 0–1.
+ *
+ * @example
+ * ```ts
+ * convertSRGB(1.2, -0.1, 0.5) // [255, 0, 127.5, 1]
+ * ```
+ */
+export declare function convertSRGB(red: number, green: number, blue: number, alpha?: number): Color;
+
+/**
+ * Converts D50 XYZ coordinates to clipped sRGB paint channels.
+ *
+ * @param x - The normalized X coordinate relative to D50.
+ * @param y - The normalized Y coordinate relative to D50.
+ * @param z - The normalized Z coordinate relative to D50.
+ * @param alpha - The opacity. Default: `1`.
+ * @returns Frozen straight sRGB channels clipped to 0–255, with alpha clipped to 0–1.
+ *
+ * @remarks
+ * Applies the CSS Color 4 Bradford adaptation from D50 to D65 before converting to sRGB.
+ *
+ * @example
+ * ```ts
+ * convertXYZD50(0, 0, 0) // [0, 0, 0, 1]
+ * ```
+ */
+export declare function convertXYZD50(x: number, y: number, z: number, alpha?: number): Color;
+
+/**
+ * Converts D65 XYZ coordinates to clipped sRGB paint channels.
+ *
+ * @param x - The normalized X coordinate.
+ * @param y - The normalized Y coordinate.
+ * @param z - The normalized Z coordinate.
+ * @param alpha - The opacity. Default: `1`.
+ * @returns Frozen straight sRGB channels clipped to 0–255, with alpha clipped to 0–1.
+ *
+ * @remarks
+ * Uses the CSS Color 4 XYZ D65 to linear sRGB matrix, then the sRGB transfer function.
+ *
+ * @example
+ * ```ts
+ * convertXYZD65(0, 0, 0) // [0, 0, 0, 1]
+ * ```
+ */
+export declare function convertXYZD65(x: number, y: number, z: number, alpha?: number): Color;
+
 /**
  * Creates one console channel that records every call it receives and hands that call on unchanged.
  *
@@ -1092,6 +1279,75 @@ export declare interface HarnessOptions<TState extends string, TEvent extends st
  */
 export declare const HEADER_ROLES: Readonly<Record<string, string>>;
 
+/**
+ * Holds the primary pointer button on one visible, focus-reachable control by its accessible name.
+ *
+ * @param name - The target's exact accessible name.
+ * @returns A promise resolving after the control enters its pressed state.
+ * @throws Thrown when the resolver refuses the target, a pointer is already held, or the press
+ * misses. A missed press that also fails to release carries the release rejection as its cause.
+ *
+ * @remarks
+ * The centre maps through the tester iframe's painted scale into page coordinates. The `:active`
+ * reading verifies delivery. A missed press releases before refusing; if that release also
+ * rejects, the refusal carries it as its cause. Register {@link releasePointer} in teardown
+ * before holding; release can produce a click on the pressed control. A rejected button-down send
+ * leaves no hold marker.
+ *
+ * @example
+ * ```ts
+ * await holdAccessible('Apply')
+ * await releasePointer()
+ * ```
+ */
+export declare function holdAccessible(name: string): Promise<void>;
+
+/**
+ * Holds the primary pointer button on one control by its exact ARIA role and accessible name.
+ *
+ * @param role - The control's exact ARIA role.
+ * @param name - The target's exact accessible name.
+ * @returns A promise resolving after the control enters its pressed state.
+ * @throws Thrown when the resolver refuses the target, a pointer is already held, or the press
+ * misses. A missed press that also fails to release carries the release rejection as its cause.
+ *
+ * @example
+ * ```ts
+ * await holdAccessible('tab', 'Drafts')
+ * await releasePointer()
+ * ```
+ */
+export declare function holdAccessible(role: string, name: string): Promise<void>;
+
+/**
+ * Hovers one visible, focus-reachable control by its accessible name through the browser provider.
+ *
+ * @param name - The target's exact accessible name.
+ * @returns A promise resolving after the pointer reaches the control.
+ * @throws Thrown when the resolver refuses the target.
+ *
+ * @example
+ * ```ts
+ * await hoverAccessible('Apply')
+ * ```
+ */
+export declare function hoverAccessible(name: string): Promise<void>;
+
+/**
+ * Hovers one visible, focus-reachable control by its exact ARIA role and accessible name.
+ *
+ * @param role - The control's exact ARIA role.
+ * @param name - The target's exact accessible name.
+ * @returns A promise resolving after the pointer reaches the control.
+ * @throws Thrown when the resolver refuses the target.
+ *
+ * @example
+ * ```ts
+ * await hoverAccessible('tab', 'Drafts')
+ * ```
+ */
+export declare function hoverAccessible(role: string, name: string): Promise<void>;
+
 /**
  * Names the role each listed tag carries in the accessibility tree when it declares none of its
  * own.
@@ -1133,8 +1389,9 @@ export declare function isOutsideViewport(rectangle: DOMRectReadOnly): boolean;
  *
  * @param element - The element to judge.
  * @returns True if the element is connected, visible, laid out with a non-zero box, in the
- * sequential focus order, neither disabled nor marked `aria-disabled="true"`, and outside every
- * `[inert]` subtree; false otherwise.
+ * sequential focus order, neither disabled nor marked `aria-disabled="true"`, outside every
+ * `[inert]` subtree, and inside every shown `[aria-modal="true"]` element its document carries;
+ * false otherwise.
  *
  * @remarks
  * This is the one reachability filter the layer applies. `resolveRendered`, `clickAccessibleWithin`,
@@ -1146,6 +1403,22 @@ export declare function isOutsideViewport(rectangle: DOMRectReadOnly): boolean;
  * refuses it. Nothing here asks about the viewport: `resolveAccessible` scrolls a wholly
  * off-viewport target into view and measures that separately with {@link isOutsideViewport}.
  *
+ * An open modal dialog takes the page behind it away, and the element's own facts cannot report
+ * that: the covered control stays connected, laid out, focusable, and outside every `[inert]`
+ * subtree while a pointer, a Tab, and a reader honouring `aria-modal` all stop at the dialog. So
+ * this asks the document for its `[aria-modal="true"]` elements, puts each through
+ * {@link isRendered}, and refuses the subject wherever a shown one does not contain it. A closed
+ * dialog is hidden and excludes nothing, which is why the visibility reading is the announced one
+ * rather than a bare `checkVisibility` call: a drawer parked at `visibility: hidden` is still laid
+ * out. Nesting needs no separate rule, because an element inside the innermost dialog sits inside
+ * every dialog around it.
+ *
+ * Containment follows the flat tree, so a subject inside a shadow tree is judged by its host chain
+ * as well as itself and a dialog holding the host holds its shadow content too. Two arrangements
+ * stay outside the read: a native `<dialog>` opened with `showModal` carries no `aria-modal`
+ * attribute, and a dialog declared inside a shadow tree is not in what a document query returns.
+ * Each leaves the page behind it reachable here.
+ *
  * Inside a shadow tree it answers for the element's own facts, in an open root and a closed one
  * alike: the box, the focus order, `:disabled`, and `aria-disabled` are all the element's. The
  * `[inert]` ancestor is the one read that stops at the boundary, because `closest` never leaves the
@@ -1335,6 +1608,23 @@ export declare function measureContrast(front: Color, back: Color): number;
  */
 export declare function measureLuminance(color: Color): number;
 
+/**
+ * Names the tester root's attribute holding the media readings observed before the first stage.
+ *
+ * @remarks
+ * The value is a bit string in print, reduced motion, dark colour scheme, and forced colours order.
+ * Each bit is `1` for a matching query and `0` otherwise, for example `0100`.
+ */
+export declare const MEDIA_STAGE = "data-media-stage";
+
+/** Configures the tester's print medium and motion preference. */
+export declare interface MediaOptions {
+    /** Determines whether the tester lays out for print. Omit it to leave the medium alone. */
+    readonly print?: boolean;
+    /** Determines whether the tester prefers motion. Omit it to leave the preference alone. */
+    readonly motion?: boolean;
+}
+
 /**
  * Puts one element into the document and hands it straight back.
  *
@@ -1365,18 +1655,19 @@ export declare function measureLuminance(color: Color): number;
 export declare function mount<T extends Element>(element: T): T;
 
 /**
- * Parses one computed CSS color value into straight sRGB channels.
+ * Parses computed CSS Color 4 values into clipped straight sRGB channels.
  *
- * @param value - A computed `rgb()`, `rgba()`, or `color(srgb …)` value.
- * @returns The color's channels, or `undefined` when the value names no color this reader speaks.
+ * @param value - A computed `rgb()`, `rgba()`, `oklab()`, `oklch()`, `lab()`, `lch()`, or `color()` value.
+ * @returns Frozen channels, or `undefined` for an unsupported syntax or non-finite channel.
  *
  * @remarks
- * A computed color resolves to `rgb()` or `rgba()` for every legacy source, and a `color-mix()`
- * declaration resolves to `color(srgb r g b [/ a])` with channels on the 0–1 scale. Both forms are
- * read here and nothing else is: a keyword, a hex triple, an empty string from a detached element,
- * and a color space the cascade never hands back all return `undefined`. Absence is the answer
- * rather than a transparent color, so a caller decides what an unreadable value means instead of
- * measuring a black it never saw.
+ * Reads signed channels, scientific notation, percentage lightness, degree hues, and `none` as
+ * zero. The `color()` spaces are `srgb`, `srgb-linear`, `display-p3`, `a98-rgb`, `prophoto-rgb`,
+ * `rec2020`, `xyz`, `xyz-d50`, and `xyz-d65`. Conversion uses the CSS Color 4 matrices and white
+ * point adaptation, then clips each encoded sRGB channel to 0–255 rather than gamut-mapping it.
+ * Alpha is clipped to 0–1. Keywords, hex colors, unresolved expressions, and non-finite calculations
+ * such as `color(srgb calc(infinity) 0 0)` remain unreadable; use {@link parseCSSColor} to resolve
+ * ordinary authored expressions through the cascade.
  *
  * @example
  * ```ts
@@ -1390,7 +1681,7 @@ export declare function parseColor(value: string): Color | undefined;
  * Resolves any CSS color expression to straight sRGB channels, by asking the browser.
  *
  * @param value - Any value the `color` property accepts: a keyword, a hex triple, a `var()`
- * reference, a `color-mix()`, or an already-computed `rgb()`.
+ * reference, a `color-mix()`, or a computed CSS Color 4 value.
  * @returns The resolved color's channels, or `undefined` when the CSSOM refuses the value or the
  * computed result names no color {@link parseColor} speaks.
  *
@@ -1400,6 +1691,8 @@ export declare function parseColor(value: string): Color | undefined;
  * cascade, and reads back what the engine computed — which is the only way a keyword, a hex triple,
  * or a `var()` reference becomes channels at all. The read itself goes through `parseColor`, so both
  * halves agree on what a computed value means.
+ * Modern perceptual and predefined RGB/XYZ spaces resolve through that parser's conversions;
+ * out-of-gamut sRGB channels are clipped to 0–255 after conversion.
  *
  * The probe is mounted, because an unmounted element inherits nothing and a `var()` reference to a
  * token declared on `:root` would resolve to the initial value instead. It is removed in a `finally`,
@@ -1418,6 +1711,15 @@ export declare function parseColor(value: string): Color | undefined;
  */
 export declare function parseCSSColor(value: string): Color | undefined;
 
+/**
+ * Names the tester root's attribute holding the pressed pointer's page coordinates.
+ *
+ * @remarks
+ * The value has the form `<x>x<y>`. The release removes it only after the button-up send resolves,
+ * so a rejected send keeps the marker for a retry.
+ */
+export declare const POINTER_HOLD = "data-pointer-hold";
+
 /** Holds the registry of capture states one run places, and the files it wrote placing them. */
 export declare interface PortfolioInterface {
     /** Holds the name of the variant this run renders. */
@@ -1496,10 +1798,13 @@ export declare function pressKeys(keys: string): Promise<void>;
  * @param element - The element whose backdrop to resolve.
  * @param floor - The opaque color the walk ends on when nothing above it paints.
  * @returns The composited color a reader sees behind the element.
+ * @throws Thrown when the backdrop contains an unreadable painted color layer.
  *
  * @remarks
  * The layers {@link readLayers} collects composite top-over-bottom onto the floor, so a 3% surface
  * tint reads as a tint over what shows through it rather than as a full-strength paint.
+ * Those layers include the modern CSS Color 4 spaces, converted and clipped to sRGB by
+ * {@link parseColor}; an unreadable painted layer refuses the entire reading.
  *
  * The floor is required, because this leaf never guesses what a document sits on. Pass
  * {@link CANVAS_COLOR} for the page a browser paints behind an unstyled document, or the color of
@@ -1603,7 +1908,8 @@ export declare function readClasses(root: ParentNode): ReadonlySet<string>;
  * would show through instead of assuming one.
  * @returns The relative-luminance contrast ratio.
  * @throws Thrown when the element exposes no computed foreground color, and — with `floor` omitted
- * — when the walk from the element upwards reaches no opaque layer.
+ * — when the walk from the element upwards reaches no opaque layer. An unreadable painted
+ * background layer throws even when a floor is supplied.
  *
  * @remarks
  * A transparent or translucent background resolves through the element's ancestors: every painted
@@ -1611,6 +1917,8 @@ export declare function readClasses(root: ParentNode): ReadonlySet<string>;
  * base, so a 3% surface tint reads as a tint over what shows through it rather than as a
  * full-strength paint. A translucent foreground then resolves against that effective background
  * before luminance is measured.
+ * Text and background colors can use the modern CSS Color 4 spaces {@link parseColor} reads;
+ * each is converted to sRGB and clipped before composition and luminance measurement.
  *
  * With `floor` omitted, the walk from the target upwards must reach a fully opaque layer: the
  * measurement throws rather than assuming a white canvas wherever that canvas would still be part
@@ -1629,7 +1937,7 @@ export declare function readClasses(root: ParentNode): ReadonlySet<string>;
  * ```ts
  * const container = render('<p style="background: #000; color: #fff">Ready</p>')
  * readContrast(requireValue(container.firstElementChild)) // 21
- * readContrast(requireValue(container.firstElementChild), CANVAS_COLOR) // 21, and never refuses
+ * readContrast(requireValue(container.firstElementChild), CANVAS_COLOR) // 21
  * ```
  */
 export declare function readContrast(element: Element, floor?: Color): number;
@@ -1733,16 +2041,23 @@ export declare function readFrame(path: string): Promise<FrameReading>;
 export declare function readHit(element: Element): Element | undefined;
 
 /**
- * Collects the painted layers standing between one element and the surface it sits on.
+ * Collects readable background color layers and refuses an unreadable painted layer.
  *
  * @param element - The element to walk up from.
  * @returns Every layer the walk paints, the element's own first and the deepest last.
+ * @throws Thrown when a painted background color is unreadable; the error names the element and
+ * its computed value.
  *
  * @remarks
  * A surface token paints one ancestor while every element between it and the text paints nothing,
  * so a backdrop is found by walking up rather than by reading the element's own `background-color`,
  * which is almost always transparent. A fully transparent layer paints nothing and is left out, and
  * the walk stops at the first fully opaque layer, because nothing above that layer is visible.
+ * Legacy and modern CSS Color 4 values resolve through {@link parseColor}, with sRGB channels
+ * clipped after conversion. Non-finite calculations such as `color(srgb calc(infinity) 0 0)` are
+ * deliberately unreadable. An unreadable value with an explicit zero alpha paints nothing and is
+ * skipped. An empty detached-element reading paints nothing too. Background images remain outside
+ * this color reader.
  *
  * The stack is what tells a resolved backdrop from an assumed one: the walk reached an opaque
  * surface exactly when its last layer's alpha is `1`. {@link readContrast} refuses on that reading,
@@ -1827,7 +2142,9 @@ export declare function readPerception(name: string): string;
  *
  * @param element - The element whose resolved style to inspect.
  * @param property - The CSS property name, registered or custom.
+ * @param pseudo - The pseudo-element selector. Omit it to read the element itself.
  * @returns The leading numeric part of the resolved value, and `0` when it carries none.
+ * @throws Thrown when the pseudo argument lacks the `::` prefix or the engine does not support it.
  *
  * @remarks
  * A resolved length is text with a unit — `'12px'` — so this reads the number in front of the unit
@@ -1845,7 +2162,7 @@ export declare function readPerception(name: string): string;
  * readPixels(button, 'width') // 0 when the width resolves to `auto`
  * ```
  */
-export declare function readPixels(element: Element, property: string): number;
+export declare function readPixels(element: Element, property: string, pseudo?: string): number;
 
 /**
  * Reads the refusal one named target answers with, or nothing when it resolves.
@@ -1897,6 +2214,7 @@ export declare function readRefusal(role: string, name: string): string | undefi
  * @param worn - The element the control's focus chrome is painted onto. Default: `control`.
  * @returns The strongest ratio the painted focus chrome reaches, or `undefined` when the control is
  * not showing `:focus-visible` or the cascade paints no chrome of its own.
+ * @throws Thrown when the focused control's backdrop contains an unreadable painted color layer.
  *
  * @remarks
  * This reads and never acts. Focus arrives through the published verbs — `traverseAccessible`,
@@ -1920,6 +2238,9 @@ export declare function readRefusal(role: string, name: string): string | undefi
  * color names neither. A focus style that only changes the control's own fill reports `undefined`
  * too: the resting fill is gone by the time focus is on the control, and this never moves focus to
  * go and read it.
+ * Outline and shadow colors include `oklch()`, `oklab()`, `lab()`, `lch()`, and predefined
+ * `color()` spaces. Each readable color converts to clipped sRGB through {@link parseColor}, and
+ * the result remains a contrast ratio rather than a ring width.
  *
  * @example
  * ```ts
@@ -2040,12 +2361,14 @@ export declare function readRules(): readonly CSSRule[];
 export declare function readStates(element: Element): readonly string[];
 
 /**
- * Reads one resolved CSS property from a real browser element.
+ * Reads one resolved CSS property from a real browser element or a named pseudo-element.
  *
  * @param element - The element whose resolved style to inspect.
  * @param property - The CSS property name, registered or custom.
+ * @param pseudo - The pseudo-element selector. Omit it to read the element itself.
  * @returns The browser's resolved property value, trimmed; an empty string when the element resolves
  * none.
+ * @throws Thrown when the pseudo argument lacks the `::` prefix or the engine does not support it.
  *
  * @remarks
  * The value is trimmed, so what comes back is the value and never the whitespace around it. Internal
@@ -2056,7 +2379,7 @@ export declare function readStates(element: Element): readonly string[];
  * readStyle(button, 'padding-left')
  * ```
  */
-export declare function readStyle(element: Element, property: string): string;
+export declare function readStyle(element: Element, property: string, pseudo?: string): string;
 
 /**
  * Reads one element's rendered text the way a name computation reads it.
@@ -2122,6 +2445,27 @@ export declare function readToken(element: Element, name: string): string;
  */
 export declare function readValue(role: string, name: string): string;
 
+/**
+ * Restores the media readings observed before the first stage as explicit emulation. With nothing
+ * staged, clears every override and waits for a stable reading, not a proved engine baseline. Checks
+ * the budget between polls, so a frame that never paints is not bounded by it.
+ *
+ * @returns A promise resolving after the media readings settle.
+ * @throws Thrown when a media read-back exhausts its 1000 millisecond budget between polls.
+ *
+ * @remarks
+ * Restores print, reduced motion, colour scheme, and forced colours from {@link MEDIA_STAGE},
+ * waits per axis for the recorded value, and removes the marker after every axis agrees. With no
+ * marker, sends the empty reset and compares readings taken strictly after that send. Each poll
+ * waits for a frame; the interval is 10 milliseconds. The provider must expose a DevTools session.
+ *
+ * @example
+ * ```ts
+ * await releaseMedia()
+ * ```
+ */
+export declare function releaseMedia(): Promise<void>;
+
 /**
  * Hands the tester pane back to the runner's own layout, at the viewport it had before staging.
  *
@@ -2151,6 +2495,26 @@ export declare function readValue(role: string, name: string): string;
  */
 export declare function releasePane(): Promise<void>;
 
+/**
+ * Releases a held pointer and parks it at the page origin, clearing hover.
+ *
+ * @returns A promise resolving after the released pointer's frame paints.
+ * @throws Thrown when the release or the park rejects. If both reject, the aggregate carries the
+ * park rejection as its cause and the release rejection in its errors.
+ *
+ * @remarks
+ * An idle pointer sends no button release. Calling this after an explicit release is safe in an
+ * `afterEach` hook. A rejected release keeps the marker for a later retry. The pointer still moves
+ * to the origin in cleanup, and a rejection there joins the aggregate described under `@throws`.
+ * The provider must expose a DevTools session.
+ *
+ * @example
+ * ```ts
+ * await releasePointer()
+ * ```
+ */
+export declare function releasePointer(): Promise<void>;
+
 /**
  * Deletes one IndexedDB database and reports what the request actually did.
  *
@@ -2283,6 +2647,46 @@ export declare function resolveAccessible(role: string, name: string): HTMLEleme
  */
 export declare function resolveRendered(first: string, second?: string): HTMLElement;
 
+/**
+ * Sends one DevTools protocol command through the browser provider.
+ *
+ * @param method - The protocol method name.
+ * @param params - The protocol parameters.
+ * @returns A promise resolving after the command completes, discarding its response.
+ * @throws Thrown when the provider exposes no DevTools session, or the command fails.
+ *
+ * @example
+ * ```ts
+ * await sendProtocol('Emulation.setEmulatedMedia', { media: '', features: [] })
+ * ```
+ */
+export declare function sendProtocol(method: string, params: Readonly<Record<string, unknown>>): Promise<void>;
+
+/**
+ * Stages the tester's print medium and motion preference through the browser provider.
+ *
+ * @param options - The media axes to override.
+ * @returns A promise resolving after a bounded read-back for `print: true` and either
+ * `motion` value. A `print: false` stage is sent and followed by a frame wait without a read-back.
+ * @throws Thrown when no axis is supplied or a staged query does not reach the tester.
+ *
+ * @remarks
+ * If `print` is true, uses print; if false, uses screen. If `motion` is true, uses no preference;
+ * if false, uses reduced motion. The print medium, reduced motion, colour scheme, and forced colours
+ * keep their effective readings when omitted. Any other emulated feature the provider configured
+ * is cleared. Each staged query waits up to 1000 milliseconds, polling every 10 milliseconds.
+ * A refused read-back restores the carried pre-call readings before throwing and can take two
+ * budgets. A restoration failure is attached as the refusal's cause. Register
+ * {@link releaseMedia} in teardown; it restores the readings observed before the first stage.
+ *
+ * @example
+ * ```ts
+ * await stageMedia({ motion: false, print: true })
+ * await releaseMedia()
+ * ```
+ */
+export declare function stageMedia(options: MediaOptions): Promise<void>;
+
 /**
  * Sets the tester's viewport and renders the runner's pane at the size that viewport claims.
  *