@orkestrel/test 0.0.7 → 0.0.9

package/dist/src/browser/index.js

@@ -1,4 +1,4 @@
-import { page, userEvent } from "vitest/browser";
+import { commands, page, userEvent } from "vitest/browser";
 //#region src/browser/constants.ts
 /**
 * The interactive ARIA roles a bare accessible name is searched across.
@@ -26,6 +26,151 @@ var ACCESSIBLE_ROLES = Object.freeze([
 	"textbox",
 	"treeitem"
 ]);
+/**
+* The page a browser paints an unstyled document onto.
+*
+* @remarks
+* This is the floor a backdrop walk ends on wherever the caller wants the browser's own canvas
+* assumed. `readBackdrop` takes its floor as an argument rather than reaching for this one, so a
+* measurement over a surface the canvas never shows through names the color it actually sits on.
+*/
+var CANVAS_COLOR = Object.freeze([
+	255,
+	255,
+	255,
+	1
+]);
+/**
+* The attribute marking the runner's tester pane, and the rule that sizes it, while a frame is
+* staged.
+*
+* @remarks
+* `stagePane` writes it onto the pane and onto the stylesheet it appends, and `releasePane` finds
+* both by it. Nothing else reads it, so a document carrying it after a capture returned is a pane
+* that was never released.
+*/
+var CAPTURE_PANE = "data-capture-pane";
+/**
+* The roles whose accessible name is the text a reader can see inside them.
+*
+* @remarks
+* `readName` reads an element in this list from its own rendered text, after every `aria-hidden`
+* descendant is dropped, and falls through to `title` for every other role.
+*/
+var CONTENT_ROLES = Object.freeze([
+	"button",
+	"cell",
+	"columnheader",
+	"heading",
+	"link",
+	"listitem",
+	"option",
+	"row",
+	"rowheader",
+	"tab"
+]);
+/**
+* The role each `input` type carries.
+*
+* @remarks
+* Membership is the contract. The map answers for `button`, `checkbox`, `email`, `number`,
+* `password`, `radio`, `range`, `reset`, `search`, `submit`, `tel`, `text`, and `url`. A type the
+* map omits — `color`, `date`, `file`, `hidden`, and the rest — exposes no role of its own, so
+* `readRole` returns `undefined` for it and `describeTree` writes no line for it.
+*/
+var FIELD_ROLES = Object.freeze({
+	button: "button",
+	checkbox: "checkbox",
+	email: "textbox",
+	number: "spinbutton",
+	password: "textbox",
+	radio: "radio",
+	range: "slider",
+	reset: "button",
+	search: "searchbox",
+	submit: "button",
+	tel: "textbox",
+	text: "textbox",
+	url: "textbox"
+});
+/**
+* What sequential keyboard navigation can reach, before disabled and unrendered elements go.
+*
+* @remarks
+* `describeFocus` queries this selector and then drops what a browser drops: an element the
+* accessibility tree does not present, a disabled control, and one removed from the sequence by
+* `tabindex="-1"`. `traverseAccessible` counts the same population to bound its walk, so this is
+* the one list either one reads.
+*/
+var FOCUSABLE_SELECTOR = "a[href], area[href], button, input, select, summary, textarea, [tabindex]";
+/**
+* The role a `th` carries for the header axis its `scope` names.
+*
+* @remarks
+* A header cell heads a column or a row, and this map answers for the `col` and `row` scopes that
+* say which. A `th` declaring no scope keeps {@link IMPLICIT_ROLES}' `columnheader` rather than the
+* ARIA computation that infers the axis from the table's shape.
+*/
+var HEADER_ROLES = Object.freeze({
+	col: "columnheader",
+	row: "rowheader"
+});
+/**
+* The role each listed tag carries in the accessibility tree when it declares none of its own.
+*
+* @remarks
+* Membership is the contract. The map answers for the sectioning elements `ARTICLE`, `ASIDE`,
+* `FOOTER`, `HEADER`, `MAIN`, `NAV`, `SEARCH`, and `SECTION`; the headings `H1` through `H6`; the
+* grouping and list elements `FIELDSET`, `FORM`, `HR`, `LI`, `OL`, and `UL`; the table elements
+* `TABLE`, `TBODY`, `THEAD`, `TR`, `TD`, and `TH`; and the widgets `BUTTON`, `DIALOG`, `IMG`,
+* `OPTION`, `OUTPUT`, `PROGRESS`, `SUMMARY`, and `TEXTAREA`.
+*
+* A tag the map omits carries no implicit role, so `readRole` returns `undefined` for it,
+* `describeTree` writes no line for it, and the walk continues straight into its children at the
+* depth the omitted element sat at. `A`, `INPUT`, and `SELECT` are absent deliberately: each takes
+* its role from an attribute rather than from its tag, and `readRole` answers for them from their
+* own anatomy.
+*
+* `SECTION` maps to `region`, which `readRole` withholds from an unnamed one, because an unnamed
+* section is not a landmark. `TH` maps to `columnheader`, which {@link HEADER_ROLES} replaces when
+* the cell declares a `scope`.
+*/
+var IMPLICIT_ROLES = Object.freeze({
+	ARTICLE: "article",
+	ASIDE: "complementary",
+	BUTTON: "button",
+	DIALOG: "dialog",
+	FIELDSET: "group",
+	FOOTER: "contentinfo",
+	FORM: "form",
+	H1: "heading",
+	H2: "heading",
+	H3: "heading",
+	H4: "heading",
+	H5: "heading",
+	H6: "heading",
+	HEADER: "banner",
+	HR: "separator",
+	IMG: "img",
+	LI: "listitem",
+	MAIN: "main",
+	NAV: "navigation",
+	OL: "list",
+	OPTION: "option",
+	OUTPUT: "status",
+	PROGRESS: "progressbar",
+	SEARCH: "search",
+	SECTION: "region",
+	SUMMARY: "button",
+	TABLE: "table",
+	TBODY: "rowgroup",
+	TD: "cell",
+	TEXTAREA: "textbox",
+	TH: "columnheader",
+	THEAD: "rowgroup",
+	TR: "row",
+	UL: "list"
+});
 //#endregion
 //#region src/browser/helpers.ts
 /**
@@ -43,6 +188,69 @@ function isOutsideViewport(rectangle) {
 	return rectangle.bottom <= 0 || rectangle.right <= 0 || rectangle.top >= window.innerHeight || rectangle.left >= window.innerWidth;
 }
 /**
+* Determines whether a person can click one element where it currently sits.
+*
+* @param element - The element to judge.
+* @returns `true` when 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.
+*
+* @remarks
+* This is the one reachability filter the layer applies. `resolveRendered`, `clickAccessibleWithin`,
+* and `clickDisclosure` each narrow their own candidates and then keep the ones this accepts, so a
+* journey meets one rule rather than three near-copies of it.
+*
+* It measures geometry, which is what separates it from {@link isRendered}. A control clipped to a
+* zero-size rectangle is announced and is not clickable, so `isRendered` accepts it and this
+* refuses it. Nothing here asks about the viewport: `resolveAccessible` scrolls a wholly
+* off-viewport target into view and measures that separately with {@link isOutsideViewport}.
+*
+* @example
+* ```ts
+* isReachable(requireValue(container.querySelector('button')))
+* ```
+*/
+function isReachable(element) {
+	if (!(element instanceof HTMLElement) && !(element instanceof SVGElement)) return false;
+	const rectangle = element.getBoundingClientRect();
+	return element.isConnected && element.checkVisibility({
+		checkOpacity: true,
+		checkVisibilityCSS: true
+	}) && rectangle.width > 0 && rectangle.height > 0 && element.tabIndex >= 0 && !element.matches(":disabled, [aria-disabled=\"true\"]") && element.closest("[inert]") === null;
+}
+/**
+* Determines whether the accessibility tree presents one element at all.
+*
+* @param element - The element to judge.
+* @returns `false` when the element is hidden from assistive technology, from sight, or from both;
+* `true` otherwise.
+*
+* @remarks
+* A control clipped to a zero-size rectangle is still announced, which is the whole point of that
+* idiom, so nothing here reads geometry: only the removals a browser honours — `aria-hidden`
+* anywhere above it, the `hidden` attribute, a hidden input, and a `display` or `visibility` that
+* takes it off the page. {@link isReachable} is the clickable half of the pair and does read
+* geometry.
+*
+* The last two are asked about the element's ancestors as well as itself, which reading a computed
+* `display` cannot do: the computed value of a child of a `display: none` container is the child's
+* own, so a control inside a closed drawer reports itself as laid out. `checkVisibility` answers
+* for the box tree, and `visibility` inherits, so between them an ancestor cannot hide a control
+* from a reader and leave it standing in a description.
+*
+* @example
+* ```ts
+* isRendered(requireValue(container.querySelector('[aria-hidden="true"] button'))) // false
+* ```
+*/
+function isRendered(element) {
+	if (element.closest("[aria-hidden=\"true\"]") !== null) return false;
+	if (element instanceof HTMLElement && element.hidden) return false;
+	if (element instanceof HTMLInputElement && element.type === "hidden") return false;
+	if (!element.checkVisibility()) return false;
+	return getComputedStyle(element).visibility !== "hidden";
+}
+/**
 * Resolves one rendered, focus-reachable interactive element without requiring it to intersect the
 * viewport yet.
 *
@@ -71,13 +279,7 @@ function resolveRendered(first, second) {
 		includeHidden: true
 	}).elements()) if (element instanceof HTMLElement && !matches.includes(element)) matches.push(element);
 	if (matches.length === 0) throw new Error(`No interactive element has the accessible name "${name}"`);
-	const reachable = matches.filter((element) => {
-		const rectangle = element.getBoundingClientRect();
-		return element.isConnected && element.checkVisibility({
-			checkOpacity: true,
-			checkVisibilityCSS: true
-		}) && rectangle.width > 0 && rectangle.height > 0 && element.tabIndex >= 0 && !element.matches(":disabled, [aria-disabled=\"true\"]") && element.closest("[inert]") === null;
-	});
+	const reachable = matches.filter((element) => isReachable(element));
 	if (reachable.length === 0) throw new Error(`Interactive target "${name}" is not visible and focus-reachable`);
 	if (reachable.length > 1) throw new Error(`Interactive target "${name}" is ambiguous across ${reachable.length} elements`);
 	const [target] = reachable;
@@ -127,14 +329,7 @@ async function clickAccessibleWithin(region, role, name) {
 		name,
 		exact: false,
 		includeHidden: true
-	}).elements().filter((element) => {
-		if (!(element instanceof HTMLElement)) return false;
-		const rectangle = element.getBoundingClientRect();
-		return element.isConnected && element.checkVisibility({
-			checkOpacity: true,
-			checkVisibilityCSS: true
-		}) && rectangle.width > 0 && rectangle.height > 0 && element.tabIndex >= 0 && !element.matches(":disabled, [aria-disabled=\"true\"]") && element.closest("[inert]") === null;
-	});
+	}).elements().filter((element) => element instanceof HTMLElement && isReachable(element));
 	if (reachable.length === 0) throw new Error(`Interactive target "${name}" is not reachable inside "${region}"`);
 	if (reachable.length > 1) throw new Error(`Interactive target "${name}" is ambiguous across ${reachable.length} elements inside "${region}"`);
 	const [target] = reachable;
@@ -146,25 +341,22 @@ async function clickAccessibleWithin(region, role, name) {
 *
 * @param name - The summary text a person reads.
 * @returns A promise resolving after trusted activation completes.
-* @throws When no visible, focus-reachable native summary has that rendered name, or several do.
+* @throws When no native summary with that rendered name passes {@link isReachable}, or several do.
 *
 * @remarks
 * Chromium exposes `<summary>` as a native disclosure rather than through an ARIA role accepted by
 * `getByRole`, so this resolver names the platform element and its rendered text directly.
 *
+* It applies the same {@link isReachable} filter the other acting verbs apply, so a summary marked
+* `aria-disabled="true"` is refused here exactly as a button marked that way is refused there.
+*
 * @example
 * ```ts
 * await clickDisclosure('Advanced')
 * ```
 */
 async function clickDisclosure(name) {
-	const reachable = [...document.querySelectorAll("summary")].filter((element) => element.innerText.replaceAll(/\s+/g, " ").trim() === name).filter((element) => {
-		const rectangle = element.getBoundingClientRect();
-		return element.isConnected && element.checkVisibility({
-			checkOpacity: true,
-			checkVisibilityCSS: true
-		}) && rectangle.width > 0 && rectangle.height > 0 && element.tabIndex >= 0 && element.closest("[inert]") === null;
-	});
+	const reachable = [...document.querySelectorAll("summary")].filter((element) => element.innerText.replaceAll(/\s+/g, " ").trim() === name).filter((element) => isReachable(element));
 	if (reachable.length === 0) throw new Error(`Native disclosure "${name}" is not visible and focus-reachable`);
 	if (reachable.length > 1) throw new Error(`Native disclosure "${name}" is ambiguous across ${reachable.length} elements`);
 	const [target] = reachable;
@@ -236,7 +428,7 @@ async function pressKeys(keys) {
 */
 async function traverseAccessible(name) {
 	resolveRendered(name);
-	const cap = document.querySelectorAll("a[href], button, input, select, textarea, [tabindex]").length * 3 + 10;
+	const cap = document.querySelectorAll(FOCUSABLE_SELECTOR).length * 3 + 10;
 	const visited = /* @__PURE__ */ new Set();
 	const trail = [];
 	for (let attempt = 0; attempt < cap; attempt += 1) {
@@ -356,6 +548,244 @@ function readValue(role, name) {
 	return control.value;
 }
 /**
+* Reads one element's rendered text the way a name computation reads it.
+*
+* @param element - The element whose announced words are wanted.
+* @returns The text with every `aria-hidden` descendant dropped and whitespace runs collapsed.
+*
+* @remarks
+* A glyph marked `aria-hidden` contributes nothing to a name, so a control captioned by an icon
+* plus a word reads as the word alone — which is what a reader hears, and what a verdict citing a
+* description has to compare against the copy a template writes. Reach for `readRows` wherever the
+* subject is what the page paints rather than what it announces: that one keeps the glyph.
+*
+* @example
+* ```ts
+* readText(requireValue(container.querySelector('button'))) // 'Save'
+* ```
+*/
+function readText(element) {
+	const parts = [];
+	const walker = element.ownerDocument.createTreeWalker(element, NodeFilter.SHOW_TEXT);
+	for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
+		const owner = node.parentElement;
+		if (owner === null || owner.closest("[aria-hidden=\"true\"]") !== null) continue;
+		parts.push(node.textContent ?? "");
+	}
+	return parts.join(" ").replaceAll(/\s+/g, " ").trim();
+}
+/**
+* Reads the role one element carries in the accessibility tree.
+*
+* @param element - The element to classify.
+* @returns The declared role, the implicit one, or `undefined` when the element carries none.
+*
+* @remarks
+* A declared `role` wins outright, and its first token is the answer when several are listed.
+* Otherwise the element's own anatomy decides: an anchor is a link only while it holds an `href`,
+* an `input` takes the role {@link FIELD_ROLES} gives its type, a `select` is a combobox until it
+* offers several rows at once, a `section` is a region only once something names it, and a `th`
+* heads whichever axis its `scope` names. Every other tag answers from {@link IMPLICIT_ROLES},
+* whose membership is the contract for what this can answer at all.
+*
+* @example
+* ```ts
+* readRole(requireValue(container.querySelector('a[href]'))) // 'link'
+* ```
+*/
+function readRole(element) {
+	const declared = element.getAttribute("role")?.trim();
+	if (declared !== void 0 && declared.length > 0) return declared.split(/\s+/)[0];
+	if (element instanceof HTMLAnchorElement) return element.href.length > 0 ? "link" : void 0;
+	if (element instanceof HTMLInputElement) return FIELD_ROLES[element.type];
+	if (element instanceof HTMLSelectElement) return element.multiple || element.size > 1 ? "listbox" : "combobox";
+	const implicit = IMPLICIT_ROLES[element.tagName];
+	const scope = element.tagName === "TH" ? element.getAttribute("scope")?.trim() : void 0;
+	if (scope !== void 0) return HEADER_ROLES[scope] ?? implicit;
+	if (implicit === "region" && !element.hasAttribute("aria-label") && !element.hasAttribute("aria-labelledby")) return;
+	return implicit;
+}
+/**
+* Reads the accessible name one element is announced under.
+*
+* @param element - The element to name.
+* @returns The computed name, or an empty string when the element carries none.
+*
+* @remarks
+* The order is the one a browser follows: `aria-labelledby`, then `aria-label`, then a form
+* control's own labels, then an image's `alt`, then the text inside a role {@link CONTENT_ROLES}
+* names, then `title`. A submit, reset, or button input is named by its value, because it renders
+* no text to read. An `aria-labelledby` naming several ids joins their texts in the order the
+* attribute lists them, and an id nothing answers for is skipped rather than fatal.
+*
+* Each step answers only when it has something to say, so a step that carries nothing hands the
+* element to the next one. An image whose `alt` is absent or blank is the case that shows it:
+* `<img title="Chart">` is named `Chart` rather than the empty string its own `alt` step would
+* have returned, and an image carrying both keeps answering `alt`.
+*
+* @example
+* ```ts
+* readName(requireValue(container.querySelector('button'))) // 'Save changes'
+* ```
+*/
+function readName(element) {
+	const referenced = element.getAttribute("aria-labelledby");
+	if (referenced !== null) {
+		const named = referenced.split(/\s+/).map((id) => element.ownerDocument.getElementById(id)).filter((node) => node !== null).map((node) => readText(node)).filter((text) => text.length > 0);
+		if (named.length > 0) return named.join(" ");
+	}
+	const labelled = element.getAttribute("aria-label")?.trim();
+	if (labelled !== void 0 && labelled.length > 0) return labelled;
+	if (element instanceof HTMLInputElement || element instanceof HTMLSelectElement || element instanceof HTMLTextAreaElement) {
+		const labels = [...element.labels ?? []].map((label) => readText(label)).filter((text) => text.length > 0);
+		if (labels.length > 0) return labels.join(" ");
+		if (element instanceof HTMLInputElement && element.value.length > 0) {
+			if (FIELD_ROLES[element.type] === "button") return element.value;
+		}
+	}
+	if (element instanceof HTMLImageElement) {
+		const alternative = element.alt.trim();
+		if (alternative.length > 0) return alternative;
+	}
+	const role = readRole(element);
+	if (role !== void 0 && CONTENT_ROLES.includes(role)) {
+		const text = readText(element);
+		if (text.length > 0) return text;
+	}
+	return element.getAttribute("title")?.trim() ?? "";
+}
+/**
+* Reads the states one element is announced in.
+*
+* @param element - The element to read.
+* @returns Every state the element declares, in one fixed order.
+*
+* @remarks
+* A state a reader is told about is one this records: what is unavailable, disclosed, pressed,
+* current, refused, chosen, announcing itself, demanded, uneditable, described, or busy. The order
+* is fixed, so two descriptions of the same surface are comparable line for line.
+*
+* A native disclosure states its expansion on the parent `details` element's own `open` rather than
+* on an ARIA attribute, so a summary that declares no `aria-expanded` is read from the platform's
+* one copy of that fact.
+*
+* @example
+* ```ts
+* readStates(requireValue(container.querySelector('summary'))) // ['collapsed']
+* ```
+*/
+function readStates(element) {
+	const states = [];
+	if (element.matches(":disabled") || element.getAttribute("aria-disabled") === "true") states.push("disabled");
+	const expanded = element.getAttribute("aria-expanded");
+	if (expanded === "true") states.push("expanded");
+	if (expanded === "false") states.push("collapsed");
+	if (expanded === null && element.tagName === "SUMMARY" && element.parentElement instanceof HTMLDetailsElement) states.push(element.parentElement.open ? "expanded" : "collapsed");
+	const pressed = element.getAttribute("aria-pressed");
+	if (pressed !== null) states.push(`pressed=${pressed}`);
+	const current = element.getAttribute("aria-current");
+	if (current !== null && current !== "false") states.push("current");
+	if (element.getAttribute("aria-invalid") === "true") states.push("invalid");
+	if (element instanceof HTMLInputElement ? element.checked : element.getAttribute("aria-checked") === "true") states.push("checked");
+	const selected = element.getAttribute("aria-selected");
+	if (selected !== null) states.push(`selected=${selected}`);
+	const live = element.getAttribute("aria-live");
+	if (live !== null) states.push(`live=${live}`);
+	if (element.matches(":required")) states.push("required");
+	if (element instanceof HTMLInputElement && element.readOnly) states.push("readonly");
+	if (element.hasAttribute("aria-describedby")) states.push("described");
+	if (element.getAttribute("aria-busy") === "true") states.push("busy");
+	return Object.freeze(states);
+}
+/**
+* Describes the accessible tree one rendered element presents.
+*
+* @param element - The host to walk, which is described first when it carries a role of its own.
+* @returns One indented line per element carrying a role, naming its role, its name, and its
+* states, in document order; an empty string when nothing in the subtree carries one.
+*
+* @remarks
+* The walk is over the real rendered DOM, so what it reports is the tree the shipped markup and the
+* shipped cascade produce together — a landmark lost to a hidden ancestor is missing here exactly as
+* it is missing for a reader. An element {@link isRendered} refuses is dropped with its whole
+* subtree.
+*
+* Depth follows the roles rather than the elements, so the indentation reads as the structure a
+* screen reader announces instead of as the markup's nesting. An element {@link readRole} answers
+* `undefined` for writes no line and adds no depth, so its children sit where it sat. That is how
+* a wrapper `div` disappears, and it is also how an element {@link IMPLICIT_ROLES} does not answer
+* for disappears — visibly, because its roled children stay at the depth it occupied.
+*
+* @example
+* ```ts
+* describeTree(container)
+* // main "Board"
+* //   heading "Totals"
+* ```
+*/
+function describeTree(element) {
+	const lines = [];
+	const pending = [{
+		node: element,
+		depth: 0
+	}];
+	while (pending.length > 0) {
+		const entry = pending.pop();
+		if (entry === void 0) break;
+		if (!isRendered(entry.node)) continue;
+		const role = readRole(entry.node);
+		let depth = entry.depth;
+		if (role !== void 0) {
+			const name = readName(entry.node);
+			const states = readStates(entry.node);
+			lines.push(`${"  ".repeat(depth)}${role}${name.length > 0 ? ` "${name}"` : ""}${states.length > 0 ? ` [${states.join(", ")}]` : ""}`);
+			depth += 1;
+		}
+		for (let index = entry.node.children.length - 1; index >= 0; index -= 1) {
+			const child = entry.node.children[index];
+			if (child !== void 0) pending.push({
+				node: child,
+				depth
+			});
+		}
+	}
+	return lines.join("\n");
+}
+/**
+* Describes the order sequential keyboard navigation visits one element's controls in.
+*
+* @param element - The host to walk; its own controls are described, and it is not itself one.
+* @returns One numbered line per reachable control, naming its role and its name.
+*
+* @remarks
+* A positive `tabindex` is honoured, because a browser honours it: those controls come first in
+* ascending order and everything else follows in document order. A control removed from the
+* sequence by `tabindex="-1"`, by being disabled, or by not being rendered at all is absent here,
+* which is the fact a focus-order verdict is about. A control {@link readRole} answers `undefined`
+* for is named by its lowercased tag, so it is still counted rather than silently dropped.
+*
+* @example
+* ```ts
+* describeFocus(container)
+* // 1. button "Save"
+* // 2. link "Cancel"
+* ```
+*/
+function describeFocus(element) {
+	return [...element.querySelectorAll(FOCUSABLE_SELECTOR)].filter((node) => isRendered(node) && !node.matches(":disabled") && node.getAttribute("tabindex") !== "-1").sort((first, second) => {
+		const left = Number.parseInt(first.getAttribute("tabindex") ?? "0", 10);
+		const right = Number.parseInt(second.getAttribute("tabindex") ?? "0", 10);
+		if (left > 0 && right > 0) return left - right;
+		if (left > 0) return -1;
+		if (right > 0) return 1;
+		return 0;
+	}).map((node, index) => {
+		const role = readRole(node) ?? node.tagName.toLowerCase();
+		const name = readName(node);
+		return `${String(index + 1)}. ${role}${name.length > 0 ? ` "${name}"` : ""}`;
+	}).join("\n");
+}
+/**
 * Waits for one animation frame to settle pending browser paint work.
 *
 * @returns A promise resolving after one `requestAnimationFrame`.
@@ -369,29 +799,418 @@ function waitForFrame() {
 	return new Promise((resolve) => requestAnimationFrame(() => resolve()));
 }
 /**
-* Renders trusted fixture markup into a container attached to the document.
+* Builds one unmounted element of a known tag, wearing the classes, text, and attributes asked for.
+*
+* @param tag - The HTML tag name, which fixes the returned element's exact type.
+* @param options - The class list, the text, and the attributes to apply.
+* @returns The built element, not yet in any document.
+*
+* @remarks
+* The element is unmounted on purpose, so a fixture is assembled before the page ever sees it and a
+* test decides where it goes. Nothing here resolves against the cascade: a built element computes no
+* style and lays out no box until {@link mount} puts it in the document.
+*
+* The text is set as text rather than parsed as markup, so a `<` in it stays a `<`. Use
+* {@link render} where the fixture is markup.
+*
+* @example
+* ```ts
+* const button = build('button', { classes: 'primary', text: 'Save', attributes: { type: 'button' } })
+* ```
+*/
+function build(tag, options) {
+	const element = document.createElement(tag);
+	if (options?.classes !== void 0) element.className = options.classes;
+	if (options?.text !== void 0) element.textContent = options.text;
+	for (const [name, value] of Object.entries(options?.attributes ?? {})) element.setAttribute(name, value);
+	return element;
+}
+/**
+* Puts one element into the document and hands it straight back.
+*
+* @param element - The element to attach.
+* @returns The same element, now appended to `document.body`.
+*
+* @remarks
+* What this buys is the composition, not the attachment: the `append` method returns `void`, and
+* this hands the element back, so it fits where an expression is expected. The {@link render} helper
+* returns its fixture through it, and the {@link rgba} helper probes through `mount(build('span'))`.
+* A bare `append` call breaks each of those call sites.
+*
+* Being connected is what the attachment then buys: `getComputedStyle` resolves against the shipped
+* cascade, custom properties inherit from `:root`, and the element lays out a real box. A detached
+* element answers each of those questions with the initial value instead, which reads as a styling
+* defect rather than as a detached node.
+*
+* Taking it back out belongs to the consumer's teardown, because this records nothing: a browser
+* test file shares one page, so a fixture left behind is the next test's resolver ambiguity. Build a
+* recorded container in a setup module and remove it from an `afterEach` hook.
+*
+* @example
+* ```ts
+* const panel = mount(build('div', { classes: 'surface' }))
+* panel.remove()
+* ```
+*/
+function mount(element) {
+	document.body.append(element);
+	return element;
+}
+function render(first, second) {
+	if (second === void 0) {
+		const container = build("div");
+		container.innerHTML = first;
+		return mount(container);
+	}
+	const element = document.createElement(first);
+	element.className = second;
+	return mount(element);
+}
+/**
+* Sets one field's value and announces it the way typing into the field does.
+*
+* @param element - The input or textarea to write into.
+* @param text - The value to set.
+*
+* @remarks
+* This is the synthetic pair of {@link typeAccessible}, for a component that listens for `input` and
+* a test that has the element already. It sets the value in one write and dispatches one bubbling
+* `input` event, so a delegated listener on an ancestor hears it. It sends no keystrokes, so a
+* component reading `key`, composition, or selection sees nothing. The dispatched event is a plain
+* `Event`, never an `InputEvent`, so a component reading `inputType` or testing
+* `instanceof InputEvent` sees neither. Drive a component that reads any of those through
+* `typeAccessible` instead.
+*
+* No `change` event follows. Use {@link commitInput} where the component waits for the field to be
+* committed.
+*
+* @example
+* ```ts
+* typeInput(requireValue(container.querySelector('input')), 'Ada')
+* ```
+*/
+function typeInput(element, text) {
+	element.value = text;
+	element.dispatchEvent(new Event("input", { bubbles: true }));
+}
+/**
+* Sets one field's value and commits it, the way typing and then leaving the field does.
+*
+* @param element - The input or textarea to write into.
+* @param text - The value to set.
+*
+* @remarks
+* The order is the browser's: {@link typeInput} first, so `input` is dispatched with the value
+* already set, and one bubbling `change` after it. A component that reads the value from either
+* event therefore reads `text` from both.
+*
+* @example
+* ```ts
+* commitInput(requireValue(container.querySelector('input')), 'Ada')
+* ```
+*/
+function commitInput(element, text) {
+	typeInput(element, text);
+	element.dispatchEvent(new Event("change", { bubbles: true }));
+}
+/**
+* Clears both browser storage surfaces.
+*
+* @remarks
+* A browser test file shares one page, so a key written by one test is read by the next one that
+* looks for it. Call this from an `afterEach` hook, which runs after a failed test as well as a
+* passing one, rather than at the end of each test that happens to write a key.
+*
+* @example
+* ```ts
+* afterEach(clearStorage)
+* ```
+*/
+function clearStorage() {
+	localStorage.clear();
+	sessionStorage.clear();
+}
+/**
+* Deletes one IndexedDB database and reports what the request actually did.
+*
+* @param name - The database name to delete.
+* @returns A promise resolving after the deletion completes.
+* @throws Thrown when the request errors, and when an open connection blocks it.
+*
+* @remarks
+* Deleting a database that was never created succeeds, so this is safe to call from a teardown hook
+* that runs whether or not the test reached the code that opens one.
+*
+* A block is a rejection rather than a wait. `blocked` fires when another connection is still open,
+* and a suite that swallowed it would leave the next test reading the previous test's records
+* through a database that reports itself deleted. The connection holding it open is the caller's to
+* close, so the block is handed back rather than absorbed.
+*
+* @example
+* ```ts
+* afterEach(() => removeDatabase('ledger'))
+* ```
+*/
+function removeDatabase(name) {
+	return new Promise((resolve, reject) => {
+		const request = globalThis.indexedDB.deleteDatabase(name);
+		request.addEventListener("success", () => resolve());
+		request.addEventListener("error", () => reject(/* @__PURE__ */ new Error(`IndexedDB database "${name}" could not be deleted`)));
+		request.addEventListener("blocked", () => reject(/* @__PURE__ */ new Error(`IndexedDB database "${name}" is blocked by an open connection`)));
+	});
+}
+/**
+* Parses one computed CSS color value into 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.
+*
+* @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.
+*
+* @example
+* ```ts
+* parseColor('rgba(255, 255, 255, 0.5)') // [255, 255, 255, 0.5]
+* parseColor('rebeccapurple') // undefined
+* ```
+*/
+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 (![
+		red,
+		green,
+		blue,
+		alpha
+	].every((channel) => Number.isFinite(channel))) return void 0;
+	return Object.freeze([
+		red,
+		green,
+		blue,
+		alpha
+	]);
+}
+/**
+* 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()`.
+* @returns The resolved color's channels, or `undefined` when the CSSOM refuses the value or the
+* computed result names no color {@link parseColor} speaks.
+*
+* @remarks
+* This is the live half of the pair {@link parseColor} opens. `parseColor` reads text and speaks
+* only the computed syntaxes a cascade hands back; this stages a probe element, hands it to the real
+* 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.
+*
+* 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`,
+* so a value that throws on the way through leaves no node behind.
+*
+* Refusal is the CSSOM's: an expression it will not parse leaves the probe's inline `color` empty
+* and this returns `undefined`. A `var()` naming an undeclared custom property is not refused,
+* because the cascade accepts it and computes the inherited color, so a test that means to catch a
+* missing token asserts on {@link token} rather than on this.
+*
+* @example
+* ```ts
+* rgba('rebeccapurple') // [102, 51, 153, 1]
+* rgba('not-a-color') // undefined
+* ```
+*/
+function rgba(value) {
+	const probe = mount(build("span"));
+	try {
+		probe.style.color = value;
+		if (probe.style.color === "") return void 0;
+		return parseColor(style(probe, "color"));
+	} finally {
+		probe.remove();
+	}
+}
+/**
+* Determines whether two colors render the same, within the rounding a browser does.
+*
+* @param first - A CSS color expression or an already-parsed color.
+* @param second - A CSS color expression or an already-parsed color.
+* @returns `true` when every channel and the alpha agree within the tolerance; `false` otherwise,
+* including when either side names no readable color.
+*
+* @remarks
+* Each string side is resolved through {@link rgba}, so a keyword, a token reference, and the
+* `rgb()` the engine computes for either of them compare equal without a test converting anything
+* first. A side that resolves to nothing makes the answer `false` rather than a throw, because this
+* is a predicate.
+*
+* The tolerance is half a channel step on the 0–255 scale, and the alpha is scaled onto that same
+* range before it is compared, so one number covers both. Half a step is what a composite of
+* translucent layers and a `color-mix()` round trip actually drift by; anything a reader could see
+* is further than that and reports unequal.
+*
+* @example
+* ```ts
+* colorEqual('rebeccapurple', 'rgb(102, 51, 153)') // true
+* colorEqual('red', [0, 0, 255, 1]) // false
+* ```
+*/
+function colorEqual(first, second) {
+	const left = typeof first === "string" ? rgba(first) : first;
+	const right = typeof second === "string" ? rgba(second) : second;
+	if (left === void 0 || right === void 0) return false;
+	const tolerance = .5;
+	const [leftRed, leftGreen, leftBlue, leftAlpha] = left;
+	const [rightRed, rightGreen, rightBlue, rightAlpha] = right;
+	return Math.abs(leftRed - rightRed) <= tolerance && Math.abs(leftGreen - rightGreen) <= tolerance && Math.abs(leftBlue - rightBlue) <= tolerance && Math.abs(leftAlpha - rightAlpha) * 255 <= tolerance;
+}
+/**
+* Composites one color over another.
 *
-* @param markup - The fixture markup to render.
-* @returns The attached container.
+* @param front - The color painted on top.
+* @param back - The color already on the surface.
+* @returns The opaque result a reader sees, its alpha always `1`.
 *
 * @example
 * ```ts
-* const container = render('<button type="button">Save</button>')
-* container.remove()
+* blendColor([255, 255, 255, 0.5], [0, 0, 0, 1]) // [127.5, 127.5, 127.5, 1]
 * ```
 */
-function render(markup) {
-	const container = document.createElement("div");
-	container.innerHTML = markup;
-	document.body.append(container);
-	return container;
+function blendColor(front, back) {
+	const [red, green, blue, alpha] = front;
+	const [under, over, beneath] = back;
+	return Object.freeze([
+		red * alpha + under * (1 - alpha),
+		green * alpha + over * (1 - alpha),
+		blue * alpha + beneath * (1 - alpha),
+		1
+	]);
+}
+/**
+* Measures one opaque color's WCAG relative luminance.
+*
+* @param color - The color to weigh. Its alpha is ignored, so composite before calling.
+* @returns The relative luminance, from `0` for black to `1` for white.
+*
+* @example
+* ```ts
+* measureLuminance([255, 255, 255, 1]) // 1
+* ```
+*/
+function measureLuminance(color) {
+	const [red, green, blue] = color;
+	const [first = 0, second = 0, third = 0] = [
+		red,
+		green,
+		blue
+	].map((channel) => {
+		const part = channel / 255;
+		return part <= .04045 ? part / 12.92 : ((part + .055) / 1.055) ** 2.4;
+	});
+	return .2126 * first + .7152 * second + .0722 * third;
+}
+/**
+* Measures the WCAG 2.x contrast ratio between two opaque colors.
+*
+* @param front - The foreground color, already composited.
+* @param back - The opaque backdrop.
+* @returns The ratio, from `1` for two identical colors to `21` for black against white.
+*
+* @remarks
+* The ratio is symmetric: the brighter of the two luminances is always the numerator, so swapping
+* the arguments returns the same number.
+*
+* @example
+* ```ts
+* measureContrast([0, 0, 0, 1], [255, 255, 255, 1]) // 21
+* ```
+*/
+function measureContrast(front, back) {
+	const bright = Math.max(measureLuminance(front), measureLuminance(back));
+	const dark = Math.min(measureLuminance(front), measureLuminance(back));
+	return (bright + .05) / (dark + .05);
+}
+/**
+* Collects the painted layers standing between one element and the surface it sits on.
+*
+* @param element - The element to walk up from.
+* @returns Every layer the walk paints, the element's own first and the deepest last.
+*
+* @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.
+*
+* 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 contrast} refuses on that reading,
+* which no comparison of composited colors can replace — 64 half-transparent layers composite to
+* the same channels over opposite floors, because the floor's remaining share falls below the last
+* bit a channel carries.
+*
+* @example
+* ```ts
+* readLayers(requireValue(container.querySelector('p')))
+* ```
+*/
+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;
+		layers.push(layer);
+		if (layer[3] >= 1) break;
+	}
+	return Object.freeze(layers);
+}
+/**
+* Resolves the opaque color standing behind one 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.
+*
+* @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.
+*
+* 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
+* the surface a fragment is really rendered into. When no layer paints, the floor is returned by
+* identity.
+*
+* The composite alone never says whether the floor is part of the answer. A caller that must know
+* reads the stack instead.
+*
+* @example
+* ```ts
+* readBackdrop(requireValue(container.querySelector('p')), CANVAS_COLOR)
+* ```
+*/
+function readBackdrop(element, floor) {
+	return readLayers(element).reduceRight((back, front) => blendColor(front, back), floor);
 }
 /**
 * Measures the WCAG 2.x contrast ratio between an element's computed text and background colors.
 *
 * @param element - The element whose rendered text contrast to measure.
+* @param floor - The opaque color the backdrop walk ends on. Omit it to refuse a stack the floor
+* would show through instead of assuming one.
 * @returns The relative-luminance contrast ratio.
-* @throws When the browser does not expose parseable computed colors.
+* @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.
 *
 * @remarks
 * A transparent or translucent background resolves through the element's ancestors: every painted
@@ -400,76 +1219,107 @@ function render(markup) {
 * full-strength paint. A translucent foreground then resolves against that effective background
 * before luminance is measured.
 *
-* Every element from the target upwards must be reachable, and at least one of them must paint:
-* the measurement throws rather than assuming a white canvas when nothing in the chain declares a
-* background color. The element itself must expose a computed foreground color — a detached
-* element exposes none, and the measurement throws rather than guessing one.
+* 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
+* of the answer. The refusal reads the alpha of the deepest layer {@link readLayers} collected, so
+* a chain that declares no background color at all, a chain painting only translucent layers, and a
+* chain deep enough for its composite to round to the canvas's own channels are refused alike,
+* because the number any of them produces is as much a report of the assumption as of the page.
+* Supply a floor wherever the caller knows what the stack sits on — a fragment mounted into a
+* painted host, or a document whose canvas is {@link CANVAS_COLOR} — and the composite is taken
+* over it rather than refused.
+*
+* The element itself must expose a computed foreground color either way. A detached element exposes
+* none, and the measurement throws rather than guessing one.
 *
 * @example
 * ```ts
 * const container = render('<p style="background: #000; color: #fff">Ready</p>')
 * contrast(requireValue(container.firstElementChild)) // 21
+* contrast(requireValue(container.firstElementChild), CANVAS_COLOR) // 21, and never refuses
 * ```
 */
-function contrast(element) {
-	const foreground = getComputedStyle(element).color.match(/\d+(?:\.\d+)?/g);
-	if (foreground === null || foreground.length < 3) throw new Error("Computed foreground color is unavailable");
-	const layers = [];
-	let current = element;
-	let opaque = false;
-	while (current !== null) {
-		const channels = getComputedStyle(current).backgroundColor.match(/\d+(?:\.\d+)?/g);
-		if (channels !== null && channels.length >= 3) {
-			const layerAlpha = channels[3] === void 0 ? 1 : Number(channels[3]);
-			if (layerAlpha > 0) layers.push([...channels.slice(0, 3).map(Number), layerAlpha]);
-			if (layerAlpha >= 1) {
-				opaque = true;
-				break;
-			}
-		}
-		current = current.parentElement;
-	}
-	if (layers.length === 0) throw new Error("Computed background color is unavailable");
-	const base = layers[layers.length - 1];
-	if (base === void 0) throw new Error("Computed background color is unavailable");
-	let composed = base.slice(0, 3).map((channel) => channel / 255);
-	if (!opaque) composed = [
-		1,
-		1,
-		1
-	];
-	const start = opaque ? layers.length - 2 : layers.length - 1;
-	for (let index = start; index >= 0; index -= 1) {
-		const layer = layers[index];
-		if (layer === void 0) continue;
-		const layerAlpha = layer[3] ?? 1;
-		composed = composed.map((channel, position) => {
-			return (layer[position] ?? 0) / 255 * layerAlpha + channel * (1 - layerAlpha);
-		});
+function contrast(element, floor) {
+	const foreground = parseColor(getComputedStyle(element).color);
+	if (foreground === void 0) throw new Error("Computed foreground color is unavailable");
+	const layers = readLayers(element);
+	const deepest = layers.at(-1);
+	if (floor === void 0 && (deepest === void 0 || deepest[3] < 1)) throw new Error("Computed background color is unavailable");
+	const backdrop = layers.reduceRight((back, front) => blendColor(front, back), floor ?? CANVAS_COLOR);
+	return measureContrast(blendColor(foreground, backdrop), backdrop);
+}
+/**
+* Measures the contrast the focus chrome painted on one control reaches against its own backdrop.
+*
+* @param control - The control that holds the focus.
+* @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.
+*
+* @remarks
+* This reads and never acts. Focus arrives through the published verbs — `traverseAccessible`,
+* `pressKeys`, a real click — and this measures what the browser painted once it landed. A control
+* that is not matching `:focus-visible` when the call is made reports nothing, because no
+* measurement taken then would be about focus.
+*
+* Some controls are two elements: one that takes the focus and one a reader can see. A hidden radio
+* beside the label that carries every pixel of its chrome is the case `worn` exists for, so a
+* measurement is not taken on a rectangle nobody is looking at. The focus state is still read off
+* `control`, because that is what holds it.
+*
+* The backdrop is the surface behind the element the chrome is worn on, resolved from that element's
+* parent through {@link readBackdrop} onto {@link CANVAS_COLOR}. A control whose ancestry paints
+* nothing is therefore measured against the browser's own canvas, which is what a reader looking at
+* an unstyled document sees.
+*
+* Only chrome the cascade paints is measured — an `outline` with a real style and width, and the
+* first color in a `box-shadow`. A control left the browser's own `outline-style: auto` ring reports
+* `undefined`, because that ring's two tones are guaranteed against any backdrop and its computed
+* 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.
+*
+* @example
+* ```ts
+* await traverseAccessible('Evaluate')
+* readRing(resolveRendered('Evaluate')) // the ratio the painted ring reaches
+* ```
+*/
+function readRing(control, worn) {
+	if (!control.matches(":focus-visible")) return void 0;
+	const target = worn ?? control;
+	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 ratios = [];
+	for (const painted of [outline, shadow]) {
+		if (painted === void 0) continue;
+		ratios.push(measureContrast(blendColor(painted, backdrop), backdrop));
 	}
-	const alpha = foreground[3] === void 0 ? 1 : Number(foreground[3]);
-	const backgroundChannels = composed;
-	const foregroundLinear = foreground.slice(0, 3).map((channel, index) => {
-		const behind = backgroundChannels[index];
-		if (behind === void 0) throw new Error("Computed background channel is unavailable");
-		return Number(channel) / 255 * alpha + behind * (1 - alpha);
-	}).map((channel) => channel <= .04045 ? channel / 12.92 : ((channel + .055) / 1.055) ** 2.4);
-	const backgroundLinear = backgroundChannels.map((channel) => channel <= .04045 ? channel / 12.92 : ((channel + .055) / 1.055) ** 2.4);
-	const foregroundLuminance = .2126 * (foregroundLinear[0] ?? 0) + .7152 * (foregroundLinear[1] ?? 0) + .0722 * (foregroundLinear[2] ?? 0);
-	const backgroundLuminance = .2126 * (backgroundLinear[0] ?? 0) + .7152 * (backgroundLinear[1] ?? 0) + .0722 * (backgroundLinear[2] ?? 0);
-	const lighter = Math.max(foregroundLuminance, backgroundLuminance);
-	const darker = Math.min(foregroundLuminance, backgroundLuminance);
-	return (lighter + .05) / (darker + .05);
+	return ratios.length === 0 ? void 0 : Math.max(...ratios);
 }
 /**
 * Collects every class token the stylesheets loaded into this document actually define.
 *
-* @returns The set of class names reachable in the shipped cascade.
+* @returns The set of class names reachable in the shipped cascade, in {@link readRules} order.
 *
 * @remarks
 * The set is what an authored-class conformance check measures against, so a class no loaded
 * stylesheet defines — an invented utility, a misspelled framework name — is absent from it.
 *
+* The tokens come from the {@link readRules} walk, which decides both the membership and the
+* insertion order this reader reports, and each answer is a deliberate difference from 0.0.8. A
+* class declared inside a grouping rule — a media query, a supports block, a layer, a nested style
+* rule — counts as defined, because a class the cascade defines under a condition is still one the
+* cascade defines; 0.0.8 read the top-level rules alone. Insertion order is breadth-first, so a
+* top-level class lands before a class declared inside an earlier grouping rule; 0.0.8 popped a
+* stack and inserted the deepest rule first. Iterate the set where the order is the subject, and
+* read `has` where membership is.
+*
+* `@keyframes` children are outside that walk, so an animation's own rules define no token here.
+* Reach the animation itself through {@link findKeyframes}.
+*
 * @example
 * ```ts
 * readCascade().has('card')
@@ -477,17 +1327,98 @@ function contrast(element) {
 */
 function readCascade() {
 	const known = /* @__PURE__ */ new Set();
-	const rules = [];
-	for (const sheet of document.styleSheets) rules.push(...sheet.cssRules);
-	while (rules.length > 0) {
-		const rule = rules.pop();
-		if (rule instanceof CSSGroupingRule) rules.push(...rule.cssRules);
+	for (const rule of readRules()) {
 		if (!(rule instanceof CSSStyleRule)) continue;
 		for (const match of rule.selectorText.matchAll(/\.([a-zA-Z][\w-]*)/g)) known.add(String(match[1]));
 	}
 	return known;
 }
 /**
+* Collects every rule the stylesheets loaded into this document hold, nested grouping rules
+* included.
+*
+* @returns Every rule reachable in the shipped cascade: each sheet's own rules in sheet order, then
+* the rules nested inside them, level by level.
+*
+* @remarks
+* The walk is iterative and reads the list it is still appending to, which is what expands a media
+* query, a supports block, a layer, and a nested style rule without recursion. Expanding by level
+* rather than by depth is why a top-level rule is always met before a rule nested inside an earlier
+* one; {@link findRule} returns the first match in exactly this order.
+*
+* The descent reaches a `CSSGroupingRule` and nothing else, and a `@keyframes` rule is not one. The
+* `@keyframes` rule itself is collected wherever it sits, and the keyframe rules inside it are not;
+* {@link findKeyframes} is the door to those.
+*
+* A stylesheet the document cannot read — a cross-origin sheet with no CORS grant — throws from its
+* own `cssRules` getter, and that sheet is skipped rather than ending the walk. What a page loaded
+* from another origin declares is unreadable to every caller here, so the alternative is a helper
+* that works until a test page adds a font or an analytics stylesheet.
+*
+* @example
+* ```ts
+* readRules().filter((rule) => rule instanceof CSSKeyframesRule)
+* ```
+*/
+function readRules() {
+	const rules = [];
+	for (const sheet of document.styleSheets) try {
+		rules.push(...sheet.cssRules);
+	} catch {
+		continue;
+	}
+	for (let index = 0; index < rules.length; index += 1) {
+		const rule = rules[index];
+		if (rule instanceof CSSGroupingRule) rules.push(...rule.cssRules);
+	}
+	return rules;
+}
+/**
+* Finds the first style rule in the cascade whose selector carries a fragment.
+*
+* @param selector - The selector fragment to look for, matched as a substring of the whole selector
+* text.
+* @returns The first matching rule in {@link readRules} order, or `undefined` when no rule carries
+* the fragment.
+*
+* @remarks
+* This proves a declaration exists in the cascade at all, which is a different question from what an
+* element resolves to: {@link style} reads the winner, and a rule this finds may be overridden by
+* another. Assert on this where the subject is the stylesheet, and on `style` where the subject is
+* the rendered result.
+*
+* The match is a substring, so `findRule('.card')` finds `.card`, `.card:hover`, and
+* `.panel > .card` alike. Pass more of the selector to narrow it.
+*
+* @example
+* ```ts
+* findRule('.card')?.style.getPropertyValue('padding')
+* ```
+*/
+function findRule(selector) {
+	for (const rule of readRules()) if (rule instanceof CSSStyleRule && rule.selectorText.includes(selector)) return rule;
+}
+/**
+* Finds the animation the cascade declares under one name.
+*
+* @param name - The exact `@keyframes` name.
+* @returns The first matching rule in {@link readRules} order, or `undefined` when the cascade
+* declares no animation under that name.
+*
+* @remarks
+* The name is matched exactly, which is where this parts from {@link findRule}: a selector is
+* compound and a fragment of one is a useful question, and an animation name is one atom that either
+* is or is not the one an `animation` declaration references.
+*
+* @example
+* ```ts
+* findKeyframes('fade')?.cssRules.length
+* ```
+*/
+function findKeyframes(name) {
+	for (const rule of readRules()) if (rule instanceof CSSKeyframesRule && rule.name === name) return rule;
+}
+/**
 * Reads the normalized visible text of every element a selector matches, in document order.
 *
 * @param root - The subtree to search.
@@ -518,11 +1449,42 @@ function readRows(root, selector) {
 	return rows;
 }
 /**
+* Collects every element carrying a component class rendered outside the container it belongs to.
+*
+* @param root - The subtree to sweep.
+* @param child - The component class whose anatomy requires a container, such as `list-group-item`.
+* @param parent - The container class that child class must render inside, such as `list-group`.
+* @returns The markup of every element carrying `child` with no `parent` above it, in document
+* order; an empty list when every one of them is nested correctly.
+*
+* @remarks
+* A component keeps its padding, borders, and radii on the container, so a child class rendered
+* outside one is an unstyled box wearing a component's name, and the interface has to hand-roll the
+* chrome back. The search for the container starts at the element's parent, so an element can never
+* answer the invariant by carrying both classes itself.
+*
+* The class names are arguments, so the check belongs to no framework: name the pair your own
+* cascade defines.
+*
+* @example
+* ```ts
+* extractOrphans(container, 'list-group-item', 'list-group') // []
+* ```
+*/
+function extractOrphans(root, child, parent) {
+	return [...root.querySelectorAll(`.${child}`)].filter((node) => (node.parentElement?.closest(`.${parent}`) ?? null) === null).map((node) => node.outerHTML);
+}
+/**
 * Reads one resolved CSS property from a real browser element.
 *
 * @param element - The element whose resolved style to inspect.
-* @param property - The CSS property name.
-* @returns The browser's resolved property value.
+* @param property - The CSS property name, registered or custom.
+* @returns The browser's resolved property value, trimmed; an empty string when the element resolves
+* none.
+*
+* @remarks
+* The value is trimmed, so what comes back is the value and never the whitespace around it. Internal
+* whitespace is kept: `--shadow: 0 0 2px` reads back with its spaces.
 *
 * @example
 * ```ts
@@ -530,7 +1492,214 @@ function readRows(root, selector) {
 * ```
 */
 function style(element, property) {
-	return getComputedStyle(element).getPropertyValue(property);
+	return getComputedStyle(element).getPropertyValue(property).trim();
+}
+/**
+* Reads one custom property from an element's resolved style.
+*
+* @param element - The element whose resolved style to inspect.
+* @param name - The custom property name, with or without its leading dashes.
+* @returns The resolved value, trimmed; an empty string when the element inherits no such property.
+*
+* @remarks
+* The dashes are optional because a token is spoken about both ways — `--surface` in a stylesheet
+* and `surface` in prose — and a reader that accepted only one spelling would turn that into a silent
+* empty string. An absent token reads as `''`, which is what the CSSOM returns and is
+* indistinguishable from a token declared empty; assert on the value you expect rather than on
+* presence.
+*
+* Resolution is inheritance, so a token declared on `:root` reads from any mounted descendant and
+* from an unmounted element reads as `''`. Use {@link rootToken} where the declaration is the
+* document's.
+*
+* @example
+* ```ts
+* token(panel, 'surface') // '#ffffff'
+* token(panel, '--surface') // '#ffffff'
+* ```
+*/
+function token(element, name) {
+	return style(element, name.startsWith("--") ? name : `--${name}`);
+}
+/**
+* Reads one custom property from the document element.
+*
+* @param name - The custom property name, with or without its leading dashes.
+* @returns The resolved value, trimmed; an empty string when the document declares no such property.
+*
+* @remarks
+* This is {@link token} against `document.documentElement`, which is where a theme declares its
+* tokens and where a `[data-theme]` switch retunes them. It exists as its own name because that
+* element is the one a token question is nearly always about, and naming it at every call site
+* buries the question.
+*
+* @example
+* ```ts
+* rootToken('surface')
+* ```
+*/
+function rootToken(name) {
+	return token(document.documentElement, name);
+}
+/**
+* Reads one resolved CSS length as a number of pixels.
+*
+* @param element - The element whose resolved style to inspect.
+* @param property - The CSS property name, registered or custom.
+* @returns The leading numeric part of the resolved value, and `0` when it carries none.
+*
+* @remarks
+* A resolved length is text with a unit — `'12px'` — so this reads the number in front of the unit
+* and discards the rest. The unit is not checked: the resolved value of a length is in pixels in
+* every case a browser hands back, and a property that resolves to something else is the caller's
+* mistake rather than this reader's.
+*
+* An unparsable value reads as `0` rather than as absence, because every caller of this is measuring
+* and `'auto'`, `'none'`, and `''` each contribute no pixels to what a reader sees. Where the
+* distinction matters, read the text with {@link style} instead.
+*
+* @example
+* ```ts
+* pixels(button, 'padding-left') // 12
+* pixels(button, 'width') // 0 when the width resolves to `auto`
+* ```
+*/
+function pixels(element, property) {
+	const measured = Number.parseFloat(style(element, property));
+	return Number.isFinite(measured) ? measured : 0;
+}
+/**
+* Sets the tester's viewport and renders the runner's pane at the size that viewport claims.
+*
+* @param width - The viewport width in CSS pixels.
+* @param height - The viewport height in CSS pixels.
+* @returns A promise resolving after the resized pane has been painted.
+* @throws Thrown when the tester sits inside no pane a capture can size, and when the staged pane
+* does not render at the viewport it was given.
+*
+* @remarks
+* This depends on the runner's own tester layout, and that dependency is contract rather than an
+* accident: `vitest@4.1.11` lays its tester out inside a smaller page, fits it by scaling the pane
+* the tester sits in, and clips whatever overflows that pane. Layout inside the tester is
+* unaffected — the tester reports the viewport it was given and every breakpoint answers to it —
+* but a screenshot is taken off the page the runner painted, so a frame shot through that scale is
+* a thumbnail of the surface and a frame shot after only unscaling it is a sliver. The tester is
+* therefore unscaled and lifted to the window's own origin for the shot. The `iframe[data-vitest]`
+* selector and the `--tester-transform`, `--tester-margin-left`, `--viewport-width`, and
+* `--viewport-height` custom properties are the runner's, so a Vitest release that renames any of
+* them reddens the size check below rather than writing a wrong frame.
+*
+* Hand the pane straight back with {@link releasePane}. A tester pinned at a viewport taller than
+* the window puts its lower half beyond what a pointer can reach, so an ordinary press then fails
+* as a control outside the viewport, in a test that took no picture at all.
+*
+* The rule is declared rather than written inline, because the runner writes its own scale onto the
+* pane as inline custom properties and rewrites them whenever the tester resizes. A declared rule
+* marked important outranks an inline value and survives every rewrite. It finds the pane by the
+* tester it contains as well as by {@link CAPTURE_PANE}, because a re-render between the staging and
+* the shot replaces the node and takes any attribute of ours with it.
+*
+* The wait is two frames rather than a delay: the first carries the resize into layout and the
+* second is the paint a screenshot reads.
+*
+* @example
+* ```ts
+* await stagePane(390, 844)
+* ```
+*/
+async function stagePane(width, height) {
+	await page.viewport(width, height);
+	const frame = window.frameElement;
+	const pane = frame?.parentElement;
+	const owner = pane?.ownerDocument;
+	if (frame === null || pane === null || pane === void 0 || owner === void 0) throw new Error("Tester pane is unavailable for a capture");
+	pane.setAttribute(CAPTURE_PANE, "");
+	if (owner.querySelector(`style[data-capture-pane]`) === null) {
+		const rule = owner.createElement("style");
+		rule.setAttribute(CAPTURE_PANE, "");
+		rule.textContent = [
+			`[${CAPTURE_PANE}],:has(>iframe[data-vitest])`,
+			"{--tester-transform:none !important;--tester-margin-left:0px !important}",
+			"iframe[data-vitest]",
+			"{position:fixed !important;left:0 !important;top:0 !important;right:auto !important;",
+			"bottom:auto !important;width:var(--viewport-width) !important;",
+			"height:var(--viewport-height) !important;z-index:2147483647 !important}"
+		].join("");
+		owner.head.append(rule);
+	}
+	await waitForFrame();
+	await waitForFrame();
+	const box = frame.getBoundingClientRect();
+	if (Math.round(box.width) !== width || Math.round(box.height) !== height) throw new Error(`Tester pane rendered ${String(Math.round(box.width))}x${String(Math.round(box.height))} for a ${String(width)}x${String(height)} viewport`);
+}
+/**
+* Hands the tester pane back to the runner's own layout.
+*
+* @remarks
+* A staged pane is the runner's fitting scale suppressed, so a pane left staged outlives the capture
+* that needed it and every later act in the file happens on a surface the runner is no longer
+* fitting to its window. What that costs is not a wrong picture: it is a control whose page
+* coordinates fall outside the pane, which the runner's own layout then intercepts, so an ordinary
+* press fails with the voice of a control that is covered. Calling this on an unstaged pane does
+* nothing.
+*
+* @example
+* ```ts
+* releasePane()
+* ```
+*/
+function releasePane() {
+	const pane = window.frameElement?.parentElement;
+	pane?.removeAttribute(CAPTURE_PANE);
+	pane?.ownerDocument.querySelector(`style[${CAPTURE_PANE}]`)?.remove();
+}
+/**
+* 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.
+* @returns The absolute path of the written frame, after it has been read back and matched.
+* @throws Thrown when the pane cannot be staged, when the provider wrote the frame somewhere else,
+* and when the bytes on disk are not the ones this shot produced.
+*
+* @remarks
+* The path a screenshot call returns is the path it meant to write, so it is not evidence a file
+* exists. The file is read back through the runner's built-in `readFile` command and compared with
+* the shot itself, which is what separates a frame this run wrote from one an earlier run left
+* behind. The provider resolves `options.path` against the calling test file and returns an absolute
+* path, so the two are compared by the segments that survive resolving `.` and `..` lexically — the
+* refusal is what a provider resolving that path against a different base would trip.
+*
+* Omit `options.element` to shoot the whole page. The pane is staged for the frame and released
+* before this returns, on the failing path as well as the passing one.
+*
+* @example
+* ```ts
+* await captureFrame({ path: '../../tmp/capture/start.png', width: 390, height: 844 })
+* ```
+*/
+async function captureFrame(options) {
+	try {
+		await stagePane(options.width, options.height);
+		const shot = options.element === void 0 ? await page.screenshot({
+			path: options.path,
+			base64: true
+		}) : await page.screenshot({
+			element: options.element,
+			path: options.path,
+			base64: true
+		});
+		const segments = [];
+		for (const segment of options.path.replaceAll("\\", "/").split("/")) {
+			if (segment === "" || segment === ".") continue;
+			if (segment === "..") segments.pop();
+			else segments.push(segment);
+		}
+		if (!shot.path.replaceAll("\\", "/").endsWith(segments.join("/"))) throw new Error(`Capture frame was written to ${shot.path} where ${options.path} was asked for`);
+		if (await commands.readFile(shot.path, "base64") !== shot.base64) throw new Error(`Capture frame at ${options.path} is not the one this run shot`);
+		return shot.path;
+	} finally {
+		releasePane();
+	}
 }
 /**
 * Expands a capture registry across every variant into the filenames a complete portfolio holds.
@@ -558,6 +1727,72 @@ function expandCaptures(states, variants) {
 //#endregion
 //#region src/browser/factories.ts
 /**
+* Creates one real pointer event, ready to dispatch.
+*
+* @param name - The event type, such as `pointerdown`.
+* @param options - Any `PointerEventInit` member, each one overriding the default beneath it.
+* @returns A real `PointerEvent` of that type.
+*
+* @remarks
+* The defaults are what a browser's own pointer event carries and a hand-built one does not:
+* `bubbles` and `cancelable` are set, so a delegated listener hears it and a handler can prevent it,
+* and `pointerId`, `pointerType`, and `isPrimary` describe a single primary mouse, so a component
+* that branches on the pointer kind takes the branch a mouse takes. Override any of them by naming
+* it; a touch is `{ pointerType: 'touch' }` and nothing else has to be restated.
+*
+* The event is real rather than a shaped object, so `instanceof PointerEvent` holds and the
+* coordinate and modifier members a handler reads are the ones the platform defines.
+*
+* @example
+* ```ts
+* element.dispatchEvent(createPointerEvent('pointerdown', { clientX: 10, clientY: 20 }))
+* ```
+*/
+function createPointerEvent(name, options) {
+	return new PointerEvent(name, {
+		bubbles: true,
+		cancelable: true,
+		pointerId: 1,
+		pointerType: "mouse",
+		isPrimary: true,
+		...options
+	});
+}
+/**
+* Creates one real drag event carrying a live data transfer, ready to dispatch.
+*
+* @param name - The event type, such as `dragstart`.
+* @param options - Any `DragEventInit` member, each one overriding the default beneath it.
+* @returns A real `DragEvent` of that type.
+*
+* @remarks
+* A drag event with no `dataTransfer` is the shape that makes a drop handler fail in a test and work
+* in a browser, so one is allocated. Pass your own to seed it: a `dataTransfer` given in `options`
+* replaces the allocated one, which is how a drop is driven with the payload the drag was supposed
+* to carry.
+*
+* The platform declares the `dataTransfer` member on the constructed event as nullable, so calling
+* code still narrows it even though this always supplies one.
+*
+* `bubbles` and `cancelable` are set, because a drop handler that never prevents the default event
+* is a drop the browser handles itself.
+*
+* @example
+* ```ts
+* const started = createDragEvent('dragstart')
+* started.dataTransfer?.setData('text/plain', 'row-3')
+* element.dispatchEvent(started)
+* ```
+*/
+function createDragEvent(name, options) {
+	return new DragEvent(name, {
+		bubbles: true,
+		cancelable: true,
+		dataTransfer: new DataTransfer(),
+		...options
+	});
+}
+/**
 * Creates the capture portfolio one run places its screenshots through.
 *
 * @param options - The state registry, the variant matrix, the variant this run renders, the
@@ -571,6 +1806,10 @@ function expandCaptures(states, variants) {
 * none of it. The portfolio refuses an unregistered variant at creation. An enabled run refuses an
 * unregistered state name and a second placement of one state.
 *
+* An enabled `place` writes through `captureFrame`, so a placed state carries that helper's staged
+* pane and its byte readback: a path is recorded only after the file on disk has been proved to hold
+* this run's own frame.
+*
 * @example
 * ```ts
 * const portfolio = createPortfolio({
@@ -599,21 +1838,136 @@ function createPortfolio(options) {
 		get paths() {
 			return [...paths];
 		},
-		async place(state) {
+		async place(state, element) {
 			if (!enabled) return void 0;
 			if (!registry.includes(state)) throw new Error(`Capture state "${state}" is not registered`);
 			if (placed.includes(state)) throw new Error(`Capture state "${state}" is already placed`);
 			const file = `${state}--${options.variant}.png`;
 			selected.apply?.();
-			if (window.innerWidth !== selected.width || window.innerHeight !== selected.height) await page.viewport(selected.width, selected.height);
-			const written = await page.screenshot({ path: `${options.directory}/${file}` });
+			const written = await captureFrame({
+				path: `${options.directory}/${file}`,
+				width: selected.width,
+				height: selected.height,
+				element
+			});
 			placed.push(state);
 			paths.push(written);
 			return written;
 		}
 	};
 }
+/**
+* Creates one console channel that records every call it receives and hands that call on unchanged.
+*
+* @param name - The channel's name, which prefixes each line it records.
+* @param output - The list each call is recorded into, appended to in place.
+* @param forward - The channel every call is passed on to after it is recorded.
+* @returns A channel carrying the console's own call signature.
+*
+* @remarks
+* One call becomes one line. Every argument of that call is put through `String` and joined with a
+* space, so a call carrying several values reads as the one line the page printed rather than as
+* several entries.
+*
+* Nothing is swallowed. The record happens first and `forward` receives the arguments it would have
+* received, so a page recorded through this prints exactly what it printed without it. The list
+* belongs to the caller, so a channel writes into whatever it was handed and holds no state of its
+* own. {@link createJournal} builds one channel per console method over one list.
+*
+* @example
+* ```ts
+* const output: string[] = []
+* console.log = createChannel('log', output, console.log)
+* ```
+*/
+function createChannel(name, output, forward) {
+	return (...data) => {
+		output.push(`${name}: ${data.map((value) => String(value)).join(" ")}`);
+		forward(...data);
+	};
+}
+/**
+* Creates the journal one scenario records its steps and the page's own output into.
+*
+* @returns A journal that records nothing until it is started.
+*
+* @remarks
+* The console is recorded rather than replaced: every intercepted call is forwarded to the channel
+* that was there when the journal started, so a run under a journal prints exactly what it printed
+* without one. `stop` puts those same function references back by identity.
+*
+* Uncaught errors and unhandled rejections are recorded too, through listeners the journal drops
+* when it stops. `steps` and `output` hand out snapshots, so a list read mid-scenario stays what it
+* was. Each journal owns its own recording, so a file that needs one per scenario creates one per
+* scenario.
+*
+* @example
+* ```ts
+* const journal = createJournal()
+* journal.start()
+* journal.record('click', 'Evaluate', 'alerts=0')
+* journal.stop()
+* journal.steps // [{ action: 'click', trigger: 'Evaluate', result: 'alerts=0' }]
+* ```
+*/
+function createJournal() {
+	const steps = [];
+	const output = [];
+	let intercepted;
+	let listeners;
+	return {
+		get steps() {
+			return [...steps];
+		},
+		get output() {
+			return [...output];
+		},
+		start() {
+			steps.length = 0;
+			output.length = 0;
+			if (intercepted !== void 0) return;
+			const forwarded = {
+				debug: console.debug,
+				error: console.error,
+				info: console.info,
+				log: console.log,
+				warn: console.warn
+			};
+			intercepted = forwarded;
+			for (const channel of [
+				"debug",
+				"error",
+				"info",
+				"log",
+				"warn"
+			]) console[channel] = createChannel(channel, output, forwarded[channel]);
+			const dropped = new AbortController();
+			listeners = dropped;
+			window.addEventListener("error", (event) => {
+				output.push(`error: ${event.message}`);
+			}, { signal: dropped.signal });
+			window.addEventListener("unhandledrejection", (event) => {
+				output.push(`rejection: ${String(event.reason)}`);
+			}, { signal: dropped.signal });
+		},
+		stop() {
+			if (intercepted === void 0) return;
+			Object.assign(console, intercepted);
+			intercepted = void 0;
+			listeners?.abort();
+			listeners = void 0;
+		},
+		record(action, trigger, result) {
+			if (intercepted === void 0) return;
+			steps.push(Object.freeze({
+				action,
+				trigger,
+				result
+			}));
+		}
+	};
+}
 //#endregion
-export { ACCESSIBLE_ROLES, clickAccessible, clickAccessibleWithin, clickDisclosure, contrast, createPortfolio, expandCaptures, fillAccessible, isOutsideViewport, pressKeys, readCascade, readFocus, readPage, readPerception, readRows, readValue, render, resolveAccessible, resolveRendered, style, traverseAccessible, typeAccessible, waitForFrame };
+export { ACCESSIBLE_ROLES, CANVAS_COLOR, CAPTURE_PANE, CONTENT_ROLES, FIELD_ROLES, FOCUSABLE_SELECTOR, HEADER_ROLES, IMPLICIT_ROLES, blendColor, build, captureFrame, clearStorage, clickAccessible, clickAccessibleWithin, clickDisclosure, colorEqual, commitInput, contrast, createChannel, createDragEvent, createJournal, createPointerEvent, createPortfolio, describeFocus, describeTree, expandCaptures, extractOrphans, fillAccessible, findKeyframes, findRule, isOutsideViewport, isReachable, isRendered, measureContrast, measureLuminance, mount, parseColor, pixels, pressKeys, readBackdrop, readCascade, readFocus, readLayers, readName, readPage, readPerception, readRing, readRole, readRows, readRules, readStates, readText, readValue, releasePane, removeDatabase, render, resolveAccessible, resolveRendered, rgba, rootToken, stagePane, style, token, traverseAccessible, typeAccessible, typeInput, waitForFrame };
 
 //# sourceMappingURL=index.js.map