@orkestrel/test 0.0.18 → 0.0.19

package/dist/src/browser/index.js

@@ -1,6 +1,6 @@
 import { isError, isString } from "@orkestrel/contract";
-import { STATECHART_ATTRIBUTES, STATECHART_STATUSES, buildRefusal, checkBounds, executeScenario, requireValue, waitForAbort, waitForCondition, waitForDelay } from "../core/index.js";
-import { commands, page, userEvent } from "vitest/browser";
+import { STATECHART_ATTRIBUTES, STATECHART_STATUSES, buildRefusal, checkBounds, executeScenario, invokeUnchecked, readProperty, requireValue, waitForAbort, waitForCondition, waitForDelay } from "../core/index.js";
+import { cdp, commands, page, userEvent } from "vitest/browser";
 //#region src/browser/constants.ts
 /**
 * Names the interactive ARIA roles a bare accessible name is searched across.
@@ -192,6 +192,22 @@ var IMPLICIT_ROLES = Object.freeze({
 	TR: "row",
 	UL: "list"
 });
+/**
+* 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`.
+*/
+var MEDIA_STAGE = "data-media-stage";
+/**
+* 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.
+*/
+var POINTER_HOLD = "data-pointer-hold";
 //#endregion
 //#region src/browser/helpers.ts
 /**
@@ -529,6 +545,119 @@ async function clickDisclosure(name) {
 	await userEvent.click(target);
 }
 /**
+* 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: [] })
+* ```
+*/
+async function sendProtocol(method, params) {
+	let session;
+	let send;
+	try {
+		session = cdp();
+		send = readProperty(session, "send");
+	} catch (cause) {
+		throw new Error("Browser provider exposes no DevTools session", { cause });
+	}
+	if (typeof send !== "function") throw new Error("Browser provider exposes no DevTools session");
+	await invokeUnchecked(session, send, [method, params]);
+}
+async function hoverAccessible(first, second) {
+	await userEvent.hover(resolveRendered(first, second));
+}
+async function holdAccessible(first, second) {
+	const held = document.documentElement.getAttribute(POINTER_HOLD);
+	if (held !== null) throw new Error(`Pointer is already held at ${held}`);
+	const target = second === void 0 ? resolveAccessible(first) : resolveAccessible(first, second);
+	const box = target.getBoundingClientRect();
+	const frame = window.frameElement?.getBoundingClientRect();
+	const scale = frame === void 0 ? 1 : frame.width / window.innerWidth;
+	const x = (frame?.left ?? 0) + (box.left + box.width / 2) * scale;
+	const y = (frame?.top ?? 0) + (box.top + box.height / 2) * scale;
+	await sendProtocol("Input.dispatchMouseEvent", {
+		type: "mouseMoved",
+		x,
+		y
+	});
+	await sendProtocol("Input.dispatchMouseEvent", {
+		type: "mousePressed",
+		x,
+		y,
+		button: "left",
+		buttons: 1,
+		clickCount: 1
+	});
+	document.documentElement.setAttribute(POINTER_HOLD, `${String(x)}x${String(y)}`);
+	await waitForFrame();
+	if (!target.matches(":active")) {
+		try {
+			await releasePointer();
+		} catch (cause) {
+			throw new Error(`Interactive target "${second ?? first}" did not enter the pressed state`, { cause });
+		}
+		throw new Error(`Interactive target "${second ?? first}" did not enter the pressed state`);
+	}
+}
+/**
+* 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()
+* ```
+*/
+async function releasePointer() {
+	const held = document.documentElement.getAttribute(POINTER_HOLD);
+	let released = held === null;
+	let rejection;
+	try {
+		if (held !== null) {
+			const [x, y] = held.split("x").map(Number);
+			await sendProtocol("Input.dispatchMouseEvent", {
+				type: "mouseReleased",
+				x,
+				y,
+				button: "left",
+				buttons: 0,
+				clickCount: 1
+			});
+			released = true;
+		}
+	} catch (cause) {
+		rejection = cause;
+	}
+	if (released) document.documentElement.removeAttribute(POINTER_HOLD);
+	try {
+		await sendProtocol("Input.dispatchMouseEvent", {
+			type: "mouseMoved",
+			x: 0,
+			y: 0
+		});
+		await waitForFrame();
+	} catch (cause) {
+		if (!released) throw new AggregateError([rejection], isError(cause) ? cause.message : String(cause), { cause });
+		throw cause;
+	}
+	if (!released) throw rejection;
+}
+/**
 * Replaces a named field's value through focus, select-all, deletion, and real keystrokes.
 *
 * @param name - The field's exact accessible name.
@@ -1271,53 +1400,317 @@ function removeDatabase(name) {
 	});
 }
 /**
-* Parses one computed CSS color value into straight sRGB channels.
+* 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]
+* ```
+*/
+function convertSRGB(red, green, blue, alpha = 1) {
+	return Object.freeze([
+		Math.min(255, Math.max(0, red * 255)),
+		Math.min(255, Math.max(0, green * 255)),
+		Math.min(255, Math.max(0, blue * 255)),
+		Math.min(1, Math.max(0, alpha))
+	]);
+}
+/**
+* Converts linear sRGB channels to encoded, clipped paint 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 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
-* 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.
+* Applies the CSS Color 4 extended sRGB transfer function before clipping.
 *
 * @example
 * ```ts
-* parseColor('rgba(255, 255, 255, 0.5)') // [255, 255, 255, 0.5]
-* parseColor('rebeccapurple') // undefined
+* convertLinearSRGB(0, 0, 0) // [0, 0, 0, 1]
 * ```
 */
-function parseColor(value) {
-	const modern = /^color\(srgb\s+(?<red>[\d.]+)\s+(?<green>[\d.]+)\s+(?<blue>[\d.]+)(?:\s*\/\s*(?<alpha>[\d.]+))?\)$/u.exec(value);
-	const legacy = /^rgba?\((?<channels>[^)]*)\)$/u.exec(value);
-	const [red, green, blue, alpha = 1] = modern?.groups === void 0 ? (legacy?.groups?.channels ?? "").split(/[\s,/]+/u).filter((part) => part.length > 0).map((part) => Number.parseFloat(part)) : [
-		Number.parseFloat(modern.groups.red ?? "") * 255,
-		Number.parseFloat(modern.groups.green ?? "") * 255,
-		Number.parseFloat(modern.groups.blue ?? "") * 255,
-		modern.groups.alpha === void 0 ? 1 : Number.parseFloat(modern.groups.alpha)
-	];
-	if (red === void 0 || green === void 0 || blue === void 0) return void 0;
-	if (![
+function convertLinearSRGB(red, green, blue, alpha = 1) {
+	const [encodedRed = 0, encodedGreen = 0, encodedBlue = 0] = [
 		red,
 		green,
-		blue,
-		alpha
-	].every((channel) => Number.isFinite(channel))) return void 0;
-	return Object.freeze([
+		blue
+	].map((channel) => Math.abs(channel) <= .0031308 ? 12.92 * channel : Math.sign(channel) * (1.055 * Math.abs(channel) ** (1 / 2.4) - .055));
+	return convertSRGB(encodedRed, encodedGreen, encodedBlue, alpha);
+}
+/**
+* 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]
+* ```
+*/
+function convertXYZD65(x, y, z, alpha = 1) {
+	return convertLinearSRGB(12831 / 3959 * x - 329 / 214 * y - 1974 / 3959 * z, -851781 / 878810 * x + 1648619 / 878810 * y + 36519 / 878810 * z, 705 / 12673 * x - 2585 / 12673 * y + 705 / 667 * z, alpha);
+}
+/**
+* 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]
+* ```
+*/
+function convertXYZD50(x, y, z, alpha = 1) {
+	return convertXYZD65(.955473421488075 * x - .02309845494876471 * y + .06325924320057072 * z, -.0283697093338637 * x + 1.0099953980813041 * y + .021041441191917323 * z, .012314014864481998 * x - .020507649298898964 * y + 1.330365926242124 * z, alpha);
+}
+/**
+* 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]
+* ```
+*/
+function convertOKLab(lightness, a, b, alpha = 1) {
+	const long = (lightness + .3963377773761749 * a + .2158037573099136 * b) ** 3;
+	const medium = (lightness - .1055613458156586 * a - .0638541728258133 * b) ** 3;
+	const short = (lightness - .0894841775298119 * a - 1.2914855480194092 * b) ** 3;
+	return convertLinearSRGB(4.076741661347994 * long - 3.307711590408193 * medium + .230969929060199 * short, -1.2684380040921763 * long + 2.6097574006633715 * medium - .3413193965711952 * short, -.0041960865418371 * long - .7034186144594493 * medium + 1.7076147010012863 * short, alpha);
+}
+/**
+* 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]
+* ```
+*/
+function convertLab(lightness, a, b, alpha = 1) {
+	const luminance = (lightness + 16) / 116;
+	const [x = 0, y = 0, z = 0] = [
+		luminance + a / 500,
+		luminance,
+		luminance - b / 200
+	].map((channel) => channel ** 3 > 216 / 24389 ? channel ** 3 : (116 * channel - 16) / (24389 / 27));
+	return convertXYZD50(x * (.3457 / .3585), y, z * (.2958 / .3585), alpha);
+}
+/**
+* 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]
+* ```
+*/
+function convertDisplayP3(red, green, blue, alpha = 1) {
+	const [r = 0, g = 0, b = 0] = [
 		red,
 		green,
-		blue,
-		alpha
-	]);
+		blue
+	].map((channel) => Math.abs(channel) <= .04045 ? channel / 12.92 : Math.sign(channel) * ((Math.abs(channel) + .055) / 1.055) ** 2.4);
+	return convertXYZD65(608311 / 1250200 * r + 189793 / 714400 * g + 198249 / 1000160 * b, 35783 / 156275 * r + 247089 / 357200 * g + 198249 / 2500400 * b, 32229 / 714400 * g + 5220557 / 5000800 * b, alpha);
+}
+/**
+* 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]
+* ```
+*/
+function convertA98RGB(red, green, blue, alpha = 1) {
+	const [r = 0, g = 0, b = 0] = [
+		red,
+		green,
+		blue
+	].map((channel) => Math.sign(channel) * Math.abs(channel) ** (563 / 256));
+	return convertXYZD65(573536 / 994567 * r + 263643 / 1420810 * g + 187206 / 994567 * b, 591459 / 1989134 * r + 6239551 / 9945670 * g + 374412 / 4972835 * b, 53769 / 1989134 * r + 351524 / 4972835 * g + 4929758 / 4972835 * b, alpha);
+}
+/**
+* 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]
+* ```
+*/
+function convertProPhotoRGB(red, green, blue, alpha = 1) {
+	const [r = 0, g = 0, b = 0] = [
+		red,
+		green,
+		blue
+	].map((channel) => Math.abs(channel) <= 16 / 512 ? channel / 16 : Math.sign(channel) * Math.abs(channel) ** 1.8);
+	return convertXYZD50(.7977666449006423 * r + .13518129740053308 * g + .0313477341283922 * b, .2880748288194013 * r + .711835234241873 * g + 8993693872564e-17 * b, .8251046025104602 * b, alpha);
+}
+/**
+* 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]
+* ```
+*/
+function convertRec2020(red, green, blue, alpha = 1) {
+	const [r = 0, g = 0, b = 0] = [
+		red,
+		green,
+		blue
+	].map((channel) => Math.abs(channel) < .08124285829863151 ? channel / 4.5 : Math.sign(channel) * ((Math.abs(channel) + 1.09929682680944 - 1) / 1.09929682680944) ** (1 / .45));
+	return convertXYZD65(63426534 / 99577255 * r + 20160776 / 139408157 * g + 47086771 / 278816314 * b, 26158966 / 99577255 * r + 472592308 / 697040785 * g + 8267143 / 139408157 * b, 19567812 / 697040785 * g + 295819943 / 278816314 * b, alpha);
+}
+/**
+* Parses computed CSS Color 4 values into clipped straight sRGB channels.
+*
+* @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
+* 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
+* parseColor('rgba(255, 255, 255, 0.5)') // [255, 255, 255, 0.5]
+* parseColor('rebeccapurple') // undefined
+* ```
+*/
+function parseColor(value) {
+	const match = /^(?<syntax>rgba?|oklab|oklch|lab|lch|color)\((?<body>[^()]*)\)$/u.exec(value);
+	if (match?.groups === void 0) return void 0;
+	const { syntax, body = "" } = match.groups;
+	const legacy = syntax === "rgb" || syntax === "rgba";
+	const polar = syntax === "oklch" || syntax === "lch";
+	const perceptual = syntax === "oklab" || syntax === "oklch" || syntax === "lab" || syntax === "lch";
+	const tokens = body.trim().split(legacy && body.includes(",") ? /\s*,\s*/u : /\s*\/\s*|\s+/u);
+	const space = syntax === "color" ? tokens.shift() : syntax;
+	if (tokens.length !== 3 && tokens.length !== 4) return void 0;
+	if (!legacy && body.includes(",")) return void 0;
+	if (body.split("/").length > 2) return void 0;
+	if (body.includes("/") && (tokens.length !== 4 || !/\/\s*[^\s/]+\s*$/u.test(body))) return void 0;
+	if (!(legacy && body.includes(",")) && tokens.length === 4 && !body.includes("/")) return void 0;
+	const parts = tokens.map((token, index) => {
+		if (token === "none") return 0;
+		const part = /^(?<number>[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?)(?<unit>%|deg)?$/u.exec(token);
+		if (part?.groups === void 0) return NaN;
+		const number = Number(part.groups.number);
+		const unit = part.groups.unit;
+		if (unit === "deg") return polar && index === 2 ? number : NaN;
+		if (unit !== "%") return number;
+		if (index === 3 || syntax === "color") return number / 100;
+		if (legacy) return number * 255 / 100;
+		if (index === 0) return syntax === "oklab" || syntax === "oklch" ? number / 100 : number;
+		return NaN;
+	});
+	const [first, second, third, alpha = 1] = parts;
+	if (first === void 0 || second === void 0 || third === void 0) return void 0;
+	if (!parts.every((part) => Number.isFinite(part))) return void 0;
+	if (legacy) return convertSRGB(first / 255, second / 255, third / 255, alpha);
+	if (perceptual) {
+		const lightness = Math.max(0, Math.min(syntax === "oklab" || syntax === "oklch" ? 1 : 100, first));
+		const a = polar ? Math.max(0, second) * Math.cos(third * Math.PI / 180) : second;
+		const b = polar ? Math.max(0, second) * Math.sin(third * Math.PI / 180) : third;
+		return syntax === "oklab" || syntax === "oklch" ? convertOKLab(lightness, a, b, alpha) : convertLab(lightness, a, b, alpha);
+	}
+	switch (space) {
+		case "srgb": return convertSRGB(first, second, third, alpha);
+		case "srgb-linear": return convertLinearSRGB(first, second, third, alpha);
+		case "display-p3": return convertDisplayP3(first, second, third, alpha);
+		case "a98-rgb": return convertA98RGB(first, second, third, alpha);
+		case "prophoto-rgb": return convertProPhotoRGB(first, second, third, alpha);
+		case "rec2020": return convertRec2020(first, second, third, alpha);
+		case "xyz":
+		case "xyz-d65": return convertXYZD65(first, second, third, alpha);
+		case "xyz-d50": return convertXYZD50(first, second, third, alpha);
+		default: return;
+	}
 }
 /**
 * 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.
 *
@@ -1327,6 +1720,8 @@ function parseColor(value) {
 * 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`,
@@ -1454,16 +1849,23 @@ function measureContrast(front, back) {
 	return (bright + .05) / (dark + .05);
 }
 /**
-* 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,
@@ -1479,8 +1881,14 @@ function measureContrast(front, back) {
 function readLayers(element) {
 	const layers = [];
 	for (let node = element; node !== null; node = node.parentElement) {
-		const layer = parseColor(getComputedStyle(node).backgroundColor);
-		if (layer === void 0 || layer[3] === 0) continue;
+		const computed = getComputedStyle(node).backgroundColor;
+		if (computed === "") continue;
+		const layer = parseColor(computed);
+		if (layer === void 0) {
+			if (/\/\s*(?:0(?:\.0*)?|none)\s*\)$/u.test(computed)) continue;
+			throw new Error(`Computed background color is unreadable on ${node.localName}${node.id === "" ? "" : `#${node.id}`}: ${computed}`);
+		}
+		if (layer[3] === 0) continue;
 		layers.push(layer);
 		if (layer[3] >= 1) break;
 	}
@@ -1492,10 +1900,13 @@ function readLayers(element) {
 * @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
@@ -1521,7 +1932,8 @@ function readBackdrop(element, floor) {
 * 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
@@ -1529,6 +1941,8 @@ function readBackdrop(element, floor) {
 * 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
@@ -1547,7 +1961,7 @@ function readBackdrop(element, floor) {
 * ```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
 * ```
 */
 function readContrast(element, floor) {
@@ -1566,6 +1980,7 @@ function readContrast(element, floor) {
 * @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`,
@@ -1589,6 +2004,9 @@ function readContrast(element, floor) {
 * 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
@@ -1602,7 +2020,7 @@ function readRing(control, worn) {
 	const declared = getComputedStyle(target);
 	const backdrop = readBackdrop(target.parentElement ?? target, CANVAS_COLOR);
 	const outline = declared.outlineStyle === "none" || declared.outlineStyle === "auto" || Number.parseFloat(declared.outlineWidth) === 0 ? void 0 : parseColor(declared.outlineColor);
-	const shadow = parseColor(/(?:rgba?|color)\([^)]*\)/u.exec(declared.boxShadow)?.[0] ?? "");
+	const shadow = parseColor(/(?:rgba?|color|oklab|oklch|lab|lch)\([^)]*\)/u.exec(declared.boxShadow)?.[0] ?? "");
 	const ratios = [];
 	for (const painted of [outline, shadow]) {
 		if (painted === void 0) continue;
@@ -1882,12 +2300,14 @@ function extractStyles(root) {
 	return styled;
 }
 /**
-* 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
@@ -1898,8 +2318,12 @@ function extractStyles(root) {
 * readStyle(button, 'padding-left')
 * ```
 */
-function readStyle(element, property) {
-	return getComputedStyle(element).getPropertyValue(property).trim();
+function readStyle(element, property, pseudo) {
+	if (pseudo !== void 0) {
+		if (!pseudo.startsWith("::")) throw new Error(`Pseudo-element "${pseudo}" must start with "::"`);
+		if (!CSS.supports(`selector(${pseudo})`)) throw new Error(`Pseudo-element "${pseudo}" is not one this engine exposes`);
+	}
+	return getComputedStyle(element, pseudo).getPropertyValue(property).trim();
 }
 /**
 * Reads one custom property from an element's resolved style.
@@ -1953,7 +2377,9 @@ function readRootToken(name) {
 *
 * @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
@@ -1971,8 +2397,8 @@ function readRootToken(name) {
 * readPixels(button, 'width') // 0 when the width resolves to `auto`
 * ```
 */
-function readPixels(element, property) {
-	const measured = Number.parseFloat(readStyle(element, property));
+function readPixels(element, property, pseudo) {
+	const measured = Number.parseFloat(readStyle(element, property, pseudo));
 	return Number.isFinite(measured) ? measured : 0;
 }
 /**
@@ -2126,6 +2552,157 @@ async function releasePane() {
 	if (Number.isFinite(width) && Number.isFinite(height)) await page.viewport(width, height);
 }
 /**
+* 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()
+* ```
+*/
+async function stageMedia(options) {
+	const print = options.print;
+	const motion = options.motion;
+	if (print === void 0 && motion === void 0) throw new Error("Media emulation was staged with nothing to emulate");
+	const media = matchMedia("print").matches ? "print" : "screen";
+	const reduced = matchMedia("(prefers-reduced-motion: reduce)").matches;
+	const dark = matchMedia("(prefers-color-scheme: dark)").matches;
+	const forced = matchMedia("(forced-colors: active)").matches;
+	if (!document.documentElement.hasAttribute("data-media-stage")) document.documentElement.setAttribute(MEDIA_STAGE, [
+		media === "print",
+		reduced,
+		dark,
+		forced
+	].map(Number).join(""));
+	const features = [
+		{
+			name: "prefers-color-scheme",
+			value: dark ? "dark" : "light"
+		},
+		{
+			name: "forced-colors",
+			value: forced ? "active" : "none"
+		},
+		{
+			name: "prefers-reduced-motion",
+			value: reduced ? "reduce" : "no-preference"
+		}
+	];
+	const queries = [];
+	if (print === true) queries.push("print");
+	if (motion !== void 0) queries.push(`(prefers-reduced-motion: ${motion ? "no-preference" : "reduce"})`);
+	await sendProtocol("Emulation.setEmulatedMedia", {
+		media: print === void 0 ? media : print ? "print" : "screen",
+		features: features.map((feature) => feature.name === "prefers-reduced-motion" && motion !== void 0 ? {
+			name: feature.name,
+			value: motion ? "no-preference" : "reduce"
+		} : feature)
+	});
+	await waitForFrame();
+	for (const query of queries) try {
+		await waitForCondition(query, () => matchMedia(query).matches);
+	} catch (cause) {
+		try {
+			await sendProtocol("Emulation.setEmulatedMedia", {
+				media,
+				features
+			});
+			await waitForCondition("pre-call media readings restored", () => matchMedia(media).matches && features.every((feature) => matchMedia(`(${feature.name}: ${feature.value})`).matches));
+		} catch (restoration) {
+			throw new Error(`Media emulation did not reach the tester: ${query}`, { cause: restoration });
+		}
+		throw new Error(`Media emulation did not reach the tester: ${query}`, { cause });
+	}
+}
+/**
+* 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()
+* ```
+*/
+async function releaseMedia() {
+	const queries = [
+		"print",
+		"(prefers-reduced-motion: reduce)",
+		"(prefers-color-scheme: dark)",
+		"(forced-colors: active)"
+	];
+	const staged = document.documentElement.getAttribute(MEDIA_STAGE);
+	if (staged !== null) {
+		const readings = staged.split("").map((value) => value === "1");
+		await sendProtocol("Emulation.setEmulatedMedia", {
+			media: readings[0] ? "print" : "screen",
+			features: [
+				{
+					name: "prefers-reduced-motion",
+					value: readings[1] ? "reduce" : "no-preference"
+				},
+				{
+					name: "prefers-color-scheme",
+					value: readings[2] ? "dark" : "light"
+				},
+				{
+					name: "forced-colors",
+					value: readings[3] ? "active" : "none"
+				}
+			]
+		});
+		try {
+			await Promise.all(queries.map((query, index) => waitForCondition(query, async () => {
+				await waitForFrame();
+				return matchMedia(query).matches === readings[index];
+			})));
+		} catch (cause) {
+			throw new Error("Media emulation did not clear from the tester", { cause });
+		}
+		document.documentElement.removeAttribute(MEDIA_STAGE);
+		return;
+	}
+	await sendProtocol("Emulation.setEmulatedMedia", {
+		media: "",
+		features: []
+	});
+	let previous = queries.map((query) => matchMedia(query).matches);
+	try {
+		await waitForCondition("media emulation cleared", async () => {
+			await waitForFrame();
+			const readings = queries.map((query) => matchMedia(query).matches);
+			const stable = readings.every((reading, index) => reading === previous[index]);
+			previous = readings;
+			return stable;
+		});
+	} catch (cause) {
+		throw new Error("Media emulation did not clear from the tester", { cause });
+	}
+}
+/**
 * Shoots one frame at one viewport size and proves the file on disk holds this run's bytes.
 *
 * @param options - The path to write, the viewport to shoot at, and the element to shoot.
@@ -2954,6 +3531,6 @@ function createHarness(options) {
 	};
 }
 //#endregion
-export { ACCESSIBLE_ROLES, CANVAS_COLOR, CAPTURE_PANE, CAPTURE_STAGINGS, CONTENT_ROLES, FIELD_ROLES, FOCUSABLE_SELECTOR, HEADER_ROLES, IMPLICIT_ROLES, blendColor, build, buildCensus, buildContrast, buildDenial, buildEscapes, captureFrame, clearStorage, clickAccessible, clickAccessibleWithin, clickDisclosure, commitInput, computeNamePattern, createChannel, createDragEvent, createHarness, createJournal, createPointerEvent, createPortfolio, createStorage, describeFocus, describeTree, expandCaptures, extractOrphans, extractStyles, fillAccessible, findKeyframes, findRule, isOutsideViewport, isReachable, isRendered, matchesColor, measureContent, measureContrast, measureLuminance, mount, parseCSSColor, parseColor, pressKeys, readBackdrop, readCascade, readCensus, readClasses, readContrast, readFocus, readFrame, readHit, readLayers, readName, readPage, readPerception, readPixels, readRefusal, readRing, readRole, readRootToken, readRows, readRules, readStates, readStyle, readText, readToken, readValue, releasePane, removeDatabase, render, resolveAccessible, resolveRendered, stagePane, traverseAccessible, typeAccessible, typeInput, waitForAnimations, waitForFrame, waitForState };
+export { ACCESSIBLE_ROLES, CANVAS_COLOR, CAPTURE_PANE, CAPTURE_STAGINGS, CONTENT_ROLES, FIELD_ROLES, FOCUSABLE_SELECTOR, HEADER_ROLES, IMPLICIT_ROLES, MEDIA_STAGE, POINTER_HOLD, blendColor, build, buildCensus, buildContrast, buildDenial, buildEscapes, captureFrame, clearStorage, clickAccessible, clickAccessibleWithin, clickDisclosure, commitInput, computeNamePattern, convertA98RGB, convertDisplayP3, convertLab, convertLinearSRGB, convertOKLab, convertProPhotoRGB, convertRec2020, convertSRGB, convertXYZD50, convertXYZD65, createChannel, createDragEvent, createHarness, createJournal, createPointerEvent, createPortfolio, createStorage, describeFocus, describeTree, expandCaptures, extractOrphans, extractStyles, fillAccessible, findKeyframes, findRule, holdAccessible, hoverAccessible, isOutsideViewport, isReachable, isRendered, matchesColor, measureContent, measureContrast, measureLuminance, mount, parseCSSColor, parseColor, pressKeys, readBackdrop, readCascade, readCensus, readClasses, readContrast, readFocus, readFrame, readHit, readLayers, readName, readPage, readPerception, readPixels, readRefusal, readRing, readRole, readRootToken, readRows, readRules, readStates, readStyle, readText, readToken, readValue, releaseMedia, releasePane, releasePointer, removeDatabase, render, resolveAccessible, resolveRendered, sendProtocol, stageMedia, stagePane, traverseAccessible, typeAccessible, typeInput, waitForAnimations, waitForFrame, waitForState };
 
 //# sourceMappingURL=index.js.map