@orkestrel/test 0.0.18 → 0.0.20

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.
  *
@@ -788,6 +975,54 @@ export declare function describeFocus(element: Element): string;
  */
 export declare function describeTree(element: Element): string;
 
+/**
+ * Holds the primary pointer button on the control a resolver returns, through the browser provider.
+ *
+ * @param resolve - The resolver that returns the target, called after the held-pointer refusal.
+ * @param name - The target's name, as the refusals voice it.
+ * @returns A promise resolving after the control enters its pressed state.
+ * @throws Thrown when a pointer is already held, the resolver refuses, the target stays outside
+ * the viewport after scrolling, or the press misses. A missed press that also fails to release
+ * carries the release rejection as its cause.
+ *
+ * @remarks
+ * This is the one pointer drive every hold verb shares: the held-marker refusal, a scroll that
+ * brings a wholly off-viewport target into view and a refusal for one that stays outside, the
+ * centre mapped through the tester iframe's painted scale into page coordinates, the trusted move
+ * and press, the marker, a frame wait, and the `:active` read-back that releases before refusing a
+ * missed press. The refusal precedes resolution, so a double hold is refused before an absent
+ * name is.
+ *
+ * @example
+ * ```ts
+ * await driveHold(() => resolveAccessible('Apply'), 'Apply')
+ * await releasePointer()
+ * ```
+ */
+export declare function driveHold(resolve: () => HTMLElement, name: string): Promise<void>;
+
+/**
+ * Reaches the control a resolver returns, only through natural forward Tab traversal from the
+ * current focus.
+ *
+ * @param resolve - The resolver that returns the target, called before the first step and again on
+ * every step, because a framework may replace the node between resolution and focus arrival.
+ * @param name - The target's name, as the refusal voices it.
+ * @returns The target after the browser moves focus to it.
+ * @throws When the resolver refuses, or one complete traversal cannot reach the target.
+ *
+ * @remarks
+ * This is the one loop every traversal verb shares. A step counts only when focus lands on an
+ * element, the traversal is over when focus revisits one, and the cap is counted off
+ * {@link FOCUSABLE_SELECTOR}.
+ *
+ * @example
+ * ```ts
+ * await driveTraversal(() => resolveRendered('Evaluate'), 'Evaluate')
+ * ```
+ */
+export declare function driveTraversal(resolve: () => HTMLElement, name: string): Promise<HTMLElement>;
+
 /**
  * Configures one built element: its class list, its text, and its attributes.
  *
@@ -1092,6 +1327,99 @@ 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. The hold itself is {@link driveHold}.
+ *
+ * @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>;
+
+/**
+ * Holds the primary pointer button on one control by role and accessible-name text inside a named
+ * region.
+ *
+ * @param region - The containing region's exact accessible name.
+ * @param role - The control's exact ARIA role.
+ * @param name - The rendered accessible-name text that identifies the control in that region.
+ * @returns A promise resolving after the control enters its pressed state.
+ * @throws Thrown when a pointer is already held, the region refuses the target, or the press
+ * misses. A missed press that also fails to release carries the release rejection as its cause.
+ *
+ * @remarks
+ * The resolution is {@link resolveAccessibleWithin} and the hold is {@link driveHold}, so a twin
+ * of the same name in another region is left alone. Register {@link releasePointer} in teardown
+ * before holding.
+ *
+ * @example
+ * ```ts
+ * await holdAccessibleWithin('Ledger', 'button', 'Apply')
+ * await releasePointer()
+ * ```
+ */
+export declare function holdAccessibleWithin(region: string, 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.
@@ -1352,6 +1680,25 @@ 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, motion preference, and forced colours. */
+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;
+    /** Determines whether the tester runs under forced colours. Omit it to leave the colours alone. */
+    readonly forced?: boolean;
+}
+
 /**
  * Puts one element into the document and hands it straight back.
  *
@@ -1382,18 +1729,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
@@ -1407,7 +1755,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.
  *
@@ -1417,6 +1765,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`,
@@ -1435,6 +1785,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. */
@@ -1513,10 +1872,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
@@ -1620,7 +1982,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
@@ -1628,6 +1991,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
@@ -1646,7 +2011,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;
@@ -1750,16 +2115,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,
@@ -1844,7 +2216,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
@@ -1862,7 +2236,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.
@@ -1914,6 +2288,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`,
@@ -1937,6 +2312,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
@@ -2057,12 +2435,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
@@ -2073,7 +2453,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.
@@ -2139,6 +2519,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.
  *
@@ -2168,6 +2569,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.
  *
@@ -2271,6 +2692,28 @@ export declare function resolveAccessible(name: string): HTMLElement;
  */
 export declare function resolveAccessible(role: string, name: string): HTMLElement;
 
+/**
+ * Resolves one human-reachable control by role and accessible-name text inside a named region.
+ *
+ * @param region - The containing region's exact accessible name.
+ * @param role - The control's exact ARIA role.
+ * @param name - The rendered accessible-name text that identifies the control in that region.
+ * @returns The one reachable element carrying that role and name inside the region.
+ * @throws When the named control is absent, unreachable, or ambiguous inside the region.
+ *
+ * @remarks
+ * The region's name is matched exactly and the control's name loosely, over a computed name that
+ * includes hidden subtrees, so a glyph joins the text rather than displacing it. One pass answers
+ * this: a control the region cannot reach is refused whether it is absent or hidden. This is the
+ * resolver the region-scoped verbs share.
+ *
+ * @example
+ * ```ts
+ * resolveAccessibleWithin('Ledger', 'button', 'Monthly income')
+ * ```
+ */
+export declare function resolveAccessibleWithin(region: string, role: string, name: string): HTMLElement;
+
 /**
  * Resolves one rendered, focus-reachable interactive element without requiring it to intersect the
  * viewport yet.
@@ -2300,6 +2743,49 @@ 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, motion preference, and forced colours through the browser
+ * provider.
+ *
+ * @param options - The media axes to override.
+ * @returns A promise resolving after a bounded read-back for `print: true`, either `motion` value,
+ * and either `forced` 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. If `forced` is true, uses active forced colours; if false, uses
+ * none. 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.
  *
@@ -2394,6 +2880,9 @@ export declare interface StorageOptions {
  * @returns The target after the browser moves focus to it.
  * @throws When one complete traversal cannot reach the target.
  *
+ * @remarks
+ * The loop is {@link driveTraversal} over {@link resolveRendered}.
+ *
  * @example
  * ```ts
  * await traverseAccessible('Evaluate')
@@ -2401,6 +2890,27 @@ export declare interface StorageOptions {
  */
 export declare function traverseAccessible(name: string): Promise<HTMLElement>;
 
+/**
+ * Reaches a control by role and accessible-name text inside a named region, only through natural
+ * forward Tab traversal from the current focus.
+ *
+ * @param region - The containing region's exact accessible name.
+ * @param role - The control's exact ARIA role.
+ * @param name - The rendered accessible-name text that identifies the control in that region.
+ * @returns The target after the browser moves focus to it.
+ * @throws When the region refuses the target, or one complete traversal cannot reach it.
+ *
+ * @remarks
+ * The resolution is {@link resolveAccessibleWithin} and the loop is {@link driveTraversal}, so a
+ * twin of the same name earlier in the tab order is passed over rather than reached.
+ *
+ * @example
+ * ```ts
+ * await traverseAccessibleWithin('Ledger', 'button', 'Evaluate')
+ * ```
+ */
+export declare function traverseAccessibleWithin(region: string, role: string, name: string): Promise<HTMLElement>;
+
 /**
  * Replaces a named field's value through focus, select-all, deletion, and real keystrokes.
  *