@orkestrel/test 0.0.15 → 0.0.17

package/dist/src/browser/index.js

@@ -1,3 +1,5 @@
+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";
 //#region src/browser/constants.ts
 /**
@@ -224,6 +226,13 @@ function isOutsideViewport(rectangle) {
 * refuses it. Nothing here asks about the viewport: `resolveAccessible` scrolls a wholly
 * off-viewport target into view and measures that separately with {@link isOutsideViewport}.
 *
+* Inside a shadow tree it answers for the element's own facts, in an open root and a closed one
+* alike: the box, the focus order, `:disabled`, and `aria-disabled` are all the element's. The
+* `[inert]` ancestor is the one read that stops at the boundary, because `closest` never leaves the
+* element's own tree, so a host marked `[inert]` is invisible here. What the flat tree decides still
+* reaches the subject — a host the document does not lay out takes the element off the page and this
+* refuses it. Ask the host separately where an ancestor attribute is the subject.
+*
 * @example
 * ```ts
 * isReachable(requireValue(container.querySelector('button')))
@@ -256,6 +265,13 @@ function isReachable(element) {
 * 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.
 *
+* Inside a shadow tree it answers for the element's own facts, in an open root and a closed one
+* alike. The `aria-hidden` ancestor is the one read that stops at the boundary, because `closest`
+* never leaves the element's own tree, so a host marked `aria-hidden="true"` is invisible here and
+* this reports `true` for a subject a reader is never told about. `checkVisibility` and the computed
+* `visibility` read the flat tree, so a host the document does not lay out still takes the element
+* off the page. Ask the host separately where an ancestor attribute is the subject.
+*
 * @example
 * ```ts
 * isRendered(requireValue(container.querySelector('[aria-hidden="true"] button'))) // false
@@ -269,6 +285,67 @@ function isRendered(element) {
 	return getComputedStyle(element).visibility !== "hidden";
 }
 /**
+* Reads the topmost element at one element's bounding-box centre.
+*
+* @param element - The element whose bounding-box centre is the point to read.
+* @returns The element the owner document's hit test names at that point, or `undefined` where the
+* point lies outside that viewport or reaches nothing.
+*
+* @remarks
+* This reads one point and nothing else: the centre of the element's own bounding box, hit-tested
+* against `element.ownerDocument`. That point is where a thumb aimed at the middle of what it sees
+* lands, and the arrangements that take it away are the ones {@link isReachable} cannot see: a
+* sticky masthead covering a control that was scrolled to, and a wrapped inline target, whose
+* per-line rectangles leave a gap the single bounding box spans and whose centre falls in that gap
+* on the ancestor. `isReachable` reads `checkVisibility`, geometry, and the focus order, and each
+* arrangement passes all three while a click at that point misses.
+*
+* It does not predict where the installed driver clicks. `playwright-core@1.63.0` clips each
+* content quad to the viewport, drops every quad left without area, and takes the midpoint of the
+* first quad that survives — `_clickablePoint` at `playwright-core/lib/coreBundle.js:20084`,
+* reached from the locator `click` the Vitest provider delegates to. For the wrapped target the
+* first surviving quad is the first line box, so the driver aims inside the link while this centre
+* sits in the gap. Read a result as the answer for the point this names, and for no other.
+*
+* It returns the node rather than a verdict, because the node is the diagnosis: a caller narrows
+* the result, rules on `link.contains(hit)`, and names what came back — the list item rather than
+* the link, the masthead rather than the control.
+*
+* Pass {@link isRendered} and {@link isReachable} before reading, because neither answer means
+* anything on an element that failed them. An element the document does not render measures a zero
+* rectangle at the origin, and a zero-area element measures a point on its own edge; each is
+* hit-tested like any other point and names whatever paints there — the surrounding container for
+* a control clipped inside one, and the document body for a rectangle collapsed at the origin.
+* `contains` is then false, and a caller that skipped the gates reports a cover that is not there.
+*
+* A returned node carries silences of its own. A cover painted with `pointer-events: none` is
+* absent from the hit test, so the reading names the element underneath it and the caller reads
+* reachable for a cover a person can see. An element inside a shadow tree retargets, in an open
+* root and a closed one alike: the document-level hit test names the host, the inner element does
+* not contain the host, and the caller reads the element's own host as a cover. Ask
+* `element.getRootNode()` for its own `elementFromPoint` where the subject sits in a shadow tree.
+*
+* `undefined` carries one silence: a centre outside the viewport reads the same as a centre that
+* reaches nothing. {@link isOutsideViewport} does not separate them, because it asks whether the
+* whole rectangle misses the viewport while this asks where one point lands — a rectangle at
+* `left: -80` with `width: 100` has its right edge at 20, so that predicate reports false while the
+* centre at -30 reads `undefined` here. The two also measure different windows: the predicate reads
+* the global `window`, and this reads `element.ownerDocument`. Compare the centre against that
+* document's own viewport where the distinction is the subject.
+*
+* @example
+* ```ts
+* const link = requireValue(container.querySelector('a'))
+* const hit = readHit(link)
+* // False for a wrapped link whose centre sits between its line boxes.
+* hit !== undefined && link.contains(hit)
+* ```
+*/
+function readHit(element) {
+	const rectangle = element.getBoundingClientRect();
+	return element.ownerDocument.elementFromPoint(rectangle.left + rectangle.width / 2, rectangle.top + rectangle.height / 2) ?? void 0;
+}
+/**
 * Computes the pattern that matches one accessible name a decorative glyph may sit beside.
 *
 * @param name - The exact accessible name a person reads, whitespace runs collapsed on the way in.
@@ -470,6 +547,35 @@ async function fillAccessible(name, text) {
 	await userEvent.fill(resolveRendered(name), text);
 }
 /**
+* Sends a key sequence to whatever holds focus, and refuses to send it to nothing.
+*
+* @param keys - The sequence in the provider's own key syntax, such as `{Enter}` or `{Escape}`.
+* @returns A promise resolving after every keystroke completes.
+* @throws When the document body holds focus, or nothing does.
+*
+* @remarks
+* The refusal is the whole of what this adds over `userEvent.keyboard`. A key sent while focus sits
+* on the body reaches no control, and every assertion after it reads the surface the key never
+* touched — which is the false green a guarded keyboard step exists to catch. Bring focus about
+* first through {@link traverseAccessible}, {@link clickAccessible}, or {@link typeAccessible}, and
+* send the sequence here.
+*
+* Escaping is the caller's, because the sequence is the subject: `{` opens a key name and `[` opens
+* a code name. Reach for {@link typeAccessible} where the text is the subject and the syntax is in
+* the way.
+*
+* @example
+* ```ts
+* await traverseAccessible('Evaluate')
+* await pressKeys('{Enter}')
+* ```
+*/
+async function pressKeys(keys) {
+	const focused = document.activeElement;
+	if (focused === null || focused === document.body) throw new Error(`Key sequence "${keys}" was sent with nothing focused`);
+	await userEvent.keyboard(keys);
+}
+/**
 * Reaches a named control only through natural forward Tab traversal from the current focus.
 *
 * @param name - The target's exact accessible name.
@@ -608,6 +714,14 @@ function readValue(role, name) {
 	if (!(control instanceof HTMLInputElement) && !(control instanceof HTMLTextAreaElement) && !(control instanceof HTMLSelectElement)) throw new Error(`Interactive target "${name}" does not carry a value`);
 	return control.value;
 }
+function readRefusal(first, second) {
+	try {
+		resolveRendered(first, second);
+	} catch (thrown) {
+		if (isError(thrown)) return thrown.message;
+		throw thrown;
+	}
+}
 /**
 * Reads one element's rendered text the way a name computation reads it.
 *
@@ -859,6 +973,119 @@ function describeFocus(element) {
 function waitForFrame() {
 	return new Promise((resolve) => requestAnimationFrame(() => resolve()));
 }
+async function waitForState(first, second, third, fourth) {
+	const keyed = isString(third);
+	const role = keyed ? first : void 0;
+	const name = keyed ? second : first;
+	const state = keyed ? third : second;
+	const options = keyed ? fourth : third;
+	const absent = options?.absent ?? false;
+	const description = `"${name}" to ${absent ? "stop announcing" : "announce"} "${state}"`;
+	let observed = [];
+	let readings = 0;
+	let refused;
+	try {
+		await waitForCondition(description, () => {
+			readings += 1;
+			try {
+				observed = readStates(role === void 0 ? resolveRendered(name) : resolveRendered(role, name));
+			} catch (thrown) {
+				refused = { thrown };
+				throw thrown;
+			}
+			return observed.includes(state) !== absent;
+		}, options);
+	} catch (cause) {
+		if (refused !== void 0 && cause === refused.thrown) throw cause;
+		if (cause === options?.signal?.reason) throw cause;
+		if (readings === 0) throw cause;
+		if (!isError(cause)) throw cause;
+		throw new Error(`${cause.message} (last states: ${JSON.stringify(observed)})`, { cause });
+	}
+	return observed;
+}
+/**
+* Waits until every finite animation on one element and its subtree has stopped moving.
+*
+* @param element - The element whose own animations and descendants' animations to wait on.
+* @param options - The time bounds and the abort signal.
+* @returns A promise resolving once no finite animation is still running.
+* @throws An `Error` when the element is not in a document, when a bound is invalid, or when an
+* animation is still running at the budget; or the abort reason.
+*
+* @remarks
+* A reading taken while paint is moving reports an interpolated frame — a `background-color` at a
+* fraction of its alpha, a `color` part way between two values — that no state of the interface
+* ever paints. This waits for the paint a person sees, whichever state it settles in.
+*
+* It parks on each animation's own `finished` promise rather than re-reading on a timer, and reads
+* the list again after each completion or cancellation, so an animation a finishing one starts is
+* waited on too.
+*
+* Some animations are left out, and each exclusion is a decision rather than an oversight. An animation
+* whose effect declares infinite iterations never finishes, so a spinner that runs forever is a
+* finding about the reading rather than a wait to lengthen. A finished animation filling its target
+* stays in the list a browser reports and is already at rest. A paused animation is at rest too,
+* and nothing here resumes it.
+*
+* The bounds are the wait family's, validated the same way. Default budget: `1000` milliseconds.
+* The interval is validated for consistency with the family and is not used, because this parks on
+* the animations. A detached element is refused rather than reported settled, because an element in
+* no document runs no animation and would answer `true` to every wait.
+*
+* @example
+* ```ts
+* await clickAccessible('Dark')
+* await waitForAnimations(document.body)
+* ```
+*/
+async function waitForAnimations(element, options) {
+	const budget = options?.budget ?? 1e3;
+	const interval = options?.interval ?? 10;
+	checkBounds("Animation", budget, interval);
+	if (!element.isConnected) throw new Error("Animation subject is not connected");
+	const signal = options?.signal;
+	const label = readName(element);
+	const subject = `${readRole(element) ?? element.localName}${label.length > 0 ? ` "${label}"` : ""}`;
+	const start = performance.now();
+	let expired = false;
+	let aborted;
+	let timer;
+	const expiry = new Promise((resolve) => {
+		timer = setTimeout(() => {
+			expired = true;
+			resolve();
+		}, budget);
+	});
+	try {
+		while (true) {
+			signal?.throwIfAborted();
+			const running = element.getAnimations({ subtree: true }).filter((animation) => {
+				const iterations = animation.effect?.getTiming().iterations ?? 1;
+				return animation.playState === "running" && Number.isFinite(iterations);
+			});
+			if (running.length === 0) return;
+			const elapsed = performance.now() - start;
+			if (expired || elapsed >= budget) {
+				const names = running.map((animation) => {
+					if (animation instanceof CSSAnimation) return animation.animationName;
+					if (animation instanceof CSSTransition) return animation.transitionProperty;
+					return animation.id;
+				});
+				throw new Error(`Animation "${subject}" did not settle within ${budget}ms (waited ${elapsed}ms): ${names.join(", ")}`);
+			}
+			const pending = running.map((animation) => animation.finished.catch(() => void 0));
+			pending.push(expiry);
+			if (signal !== void 0) {
+				aborted ??= waitForAbort(signal);
+				pending.push(aborted);
+			}
+			await Promise.race(pending);
+		}
+	} finally {
+		if (timer !== void 0) clearTimeout(timer);
+	}
+}
 /**
 * Builds one unmounted element of a known tag, wearing the classes, text, and attributes asked for.
 *
@@ -1423,6 +1650,42 @@ function readClasses(root) {
 	return authored;
 }
 /**
+* Takes the authored-class census of one subtree against the cascade this document loaded.
+*
+* @param root - The subtree to walk. A detached element and a `DocumentFragment` both work.
+* @returns The population walked, every class token the markup carries, and every one of them no
+* loaded stylesheet declares; both lists sorted.
+* @throws An `Error` when the walk reads no element at all.
+*
+* @remarks
+* This is {@link readClasses} differenced against {@link readCascade}, with the population reported
+* beside the difference. The population is what makes the reading falsifiable: an empty walk
+* reports no undeclared token, and so does a subtree whose every class the cascade declares, so a
+* check reading `undeclared` alone passes for a census that read nothing. The empty walk is refused
+* outright for the same reason.
+*
+* The root counts when it is an `Element`, so a `DocumentFragment` contributes its descendants
+* alone. Both lists are sorted rather than left in sighting order, because a census is compared
+* against a previous one or against an expected list, and document order is not a fact about the
+* classes.
+*
+* @example
+* ```ts
+* readCensus(container).undeclared // ['lead'] — no loaded stylesheet declares it
+* ```
+*/
+function readCensus(root) {
+	const elements = (root instanceof Element ? 1 : 0) + root.querySelectorAll("*").length;
+	if (elements === 0) throw new Error("Class census walked no element");
+	const declared = readCascade();
+	const tokens = [...readClasses(root)].sort();
+	return Object.freeze({
+		elements,
+		tokens: Object.freeze(tokens),
+		undeclared: Object.freeze(tokens.filter((token) => !declared.has(token)))
+	});
+}
+/**
 * Collects every rule the stylesheets loaded into this document hold, nested grouping rules
 * included.
 *
@@ -2002,6 +2265,196 @@ function expandCaptures(states, variants) {
 	for (const state of states) for (const variant of variants) files.push(`${state}--${variant.name}.png`);
 	return files;
 }
+/**
+* Builds the refusal a host withholding a storage operation raises.
+*
+* @param operation - The withheld operation, named as the `Storage` interface names it.
+* @param key - The storage key the operation addressed. Omit it for an operation that takes none.
+* @returns The refusal, unthrown.
+*
+* @remarks
+* A browser with site data blocked, a sandboxed frame, and a hardened privacy mode all raise a
+* `DOMException` named `SecurityError` from the storage object rather than answering, so this is
+* the voice rather than a message of this package's. {@link createStorage} raises it from every
+* operation the permission withholds; it is exported because a fixture implementing `Storage` some
+* other way needs the same voice rather than a second spelling of it.
+*
+* @example
+* ```ts
+* buildDenial('getItem', 'theme').message // 'Access is denied for getItem "theme"'
+* buildDenial('length').name // 'SecurityError'
+* ```
+*/
+function buildDenial(operation, key) {
+	return new DOMException(`Access is denied for ${operation}${key === void 0 ? "" : ` "${key}"`}`, "SecurityError");
+}
+/**
+* Builds a detached translucent stack whose composited and flat contrast readings straddle one bar.
+*
+* @param bar - The contrast ratio `refused` and `accepted` must sit on opposite sides of.
+* @returns The opaque root carrying the tint, and the refused and accepted foregrounds under it.
+* @throws An `Error` when no grey foreground puts the two readings on opposite sides of the bar.
+*
+* @remarks
+* A contrast instrument that never composites still clears every fixture painting its own opaque
+* background, so this is the control that makes {@link readContrast}'s ancestor walk and alpha
+* blend the thing under test. The stack is an opaque floor, a translucent tint over it, and two
+* grey foregrounds inside the tint. `refused` reads under the bar composited and at or over it
+* flat, and `accepted` reads the other way about, so no single non-compositing reading satisfies
+* both.
+*
+* The greys are searched rather than written down, so the control follows the bar it was asked for.
+* A bar at or under `1` is refused because every contrast ratio reaches `1`, and a bar above what
+* the tinted surface can reach is refused because no foreground clears it — each refusal names the
+* bar rather than returning a stack that proves nothing.
+*
+* The nodes are detached, so nothing is mounted for you. Append `root` to the surface you are
+* reading, take both readings, and remove it: a computed color needs the document, and a fixture
+* left behind is the next test's resolver ambiguity.
+*
+* @example
+* ```ts
+* const control = buildContrast(4.5)
+* mount(control.root)
+* readContrast(control.refused) < 4.5 // true
+* readContrast(control.accepted) >= 4.5 // true
+* control.root.remove()
+* ```
+*/
+function buildContrast(bar) {
+	const tint = [
+		0,
+		0,
+		0,
+		.06
+	];
+	const backdrop = blendColor(tint, CANVAS_COLOR);
+	const flattened = [
+		tint[0],
+		tint[1],
+		tint[2],
+		1
+	];
+	let refusedChannel;
+	let acceptedChannel;
+	for (let channel = 0; channel <= 255; channel += 1) {
+		const front = [
+			channel,
+			channel,
+			channel,
+			1
+		];
+		const composited = measureContrast(front, backdrop);
+		const flat = measureContrast(front, flattened);
+		if (refusedChannel === void 0 && composited < bar && flat >= bar) refusedChannel = channel;
+		if (acceptedChannel === void 0 && composited >= bar && flat < bar) acceptedChannel = channel;
+	}
+	if (refusedChannel === void 0 || acceptedChannel === void 0) throw new Error(`Contrast control cannot straddle the bar ${bar}`);
+	const root = build("div", { attributes: { style: `background-color: rgb(${CANVAS_COLOR[0]}, ${CANVAS_COLOR[1]}, ${CANVAS_COLOR[2]})` } });
+	const tinted = build("div", { attributes: { style: `background-color: rgba(${tint[0]}, ${tint[1]}, ${tint[2]}, ${tint[3]})` } });
+	const refused = build("p", {
+		text: "Composited contrast control",
+		attributes: { style: `color: rgb(${refusedChannel}, ${refusedChannel}, ${refusedChannel})` }
+	});
+	const accepted = build("p", {
+		text: "Composited contrast survivor",
+		attributes: { style: `color: rgb(${acceptedChannel}, ${acceptedChannel}, ${acceptedChannel})` }
+	});
+	tinted.append(refused, accepted);
+	root.append(tinted);
+	return Object.freeze({
+		root,
+		refused,
+		accepted
+	});
+}
+/**
+* Builds detached markup carrying one style escape of each kind, plus the sheet a project allows.
+*
+* @param permitted - The `id` the caller's reading exempts, placed on the third element.
+* @returns The detached root, the inline escape, the embedded escape, and the exempt sheet.
+*
+* @remarks
+* {@link extractStyles} has two branches — an inline `style` attribute and a `<style>` element —
+* and a reading fed only the first never exercises the second. The exempt sheet is the other half
+* of the control: a project that allows one standalone stylesheet writes an exemption for its id,
+* and a reading that passes by refusing every `<style>` element clears the two escapes and fails
+* that exemption.
+*
+* The declaration `inline`, `embedded`, and `permitted` carry is this package's, so assert on which
+* elements are reported rather than on what they declare.
+*
+* The nodes are detached and stay that way: `extractStyles` takes any `ParentNode`, so the reading
+* runs without mounting, and an embedded sheet that reached the document would join the cascade
+* every other reading measures against.
+*
+* @example
+* ```ts
+* const control = buildEscapes('project-stylesheet')
+* extractStyles(control.root).length // 3 — the inline escape, the embedded sheet, and the exempt one
+* ```
+*/
+function buildEscapes(permitted) {
+	const declaration = "color: rgb(1, 2, 3)";
+	const root = build("div");
+	const inline = build("p", {
+		text: "Inline escape control",
+		attributes: { style: declaration }
+	});
+	const embedded = build("style");
+	embedded.textContent = `.escape-embedded { ${declaration} }`;
+	const exempt = build("style", { attributes: { id: permitted } });
+	exempt.textContent = `#escape-permitted { ${declaration} }`;
+	root.append(inline, embedded, exempt);
+	return Object.freeze({
+		root,
+		inline,
+		embedded,
+		permitted: exempt
+	});
+}
+/**
+* Builds detached markup carrying one undeclared class token on HTML and another on SVG.
+*
+* @returns The detached root, the token the HTML element carries, and the one the SVG carries.
+*
+* @remarks
+* The SVG element is the trap a census has to survive: `className` on an SVG element is an
+* `SVGAnimatedString` rather than a string, so a reader splitting that value finds nothing and
+* reports one undeclared token where two are carried. {@link readCensus} reads every element
+* through `classList`, and this is the control that proves it.
+*
+* The two tokens are returned rather than written into a caller's expectation, so a cascade that
+* later declares one of these names moves the fixture and the assertion together. Each token also
+* carries a suffix drawn per call from `crypto.getRandomValues`, so a consumer cascade cannot
+* declare either of them in advance and two controls in one document never share a token.
+* `getRandomValues` rather than `randomUUID`, because that one answers outside a secure context
+* too, and a browser project served from a remote host is not one.
+*
+* @example
+* ```ts
+* const control = buildCensus()
+* readCensus(control.root).undeclared // [control.mark, control.token], sorted
+* ```
+*/
+function buildCensus() {
+	const suffix = crypto.getRandomValues(/* @__PURE__ */ new Uint32Array(1)).join("");
+	const token = `census-authored-token-${suffix}`;
+	const mark = `census-authored-mark-${suffix}`;
+	const root = build("div");
+	root.append(build("p", {
+		classes: token,
+		text: "Authored class control"
+	}));
+	const glyph = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+	glyph.setAttribute("class", mark);
+	root.append(glyph);
+	return Object.freeze({
+		root,
+		token,
+		mark
+	});
+}
 //#endregion
 //#region src/browser/factories.ts
 /**
@@ -2245,7 +2698,239 @@ function createJournal() {
 		}
 	};
 }
+/**
+* Creates an inert `Storage` a host can withhold, grant, and run out of room in.
+*
+* @param options - The seed, the read and write permissions, and the quota.
+* @returns A store carrying the Web Storage surface plus the grant.
+* @throws An `Error` when `quota` is not a non-negative safe integer. A quota above
+* `Number.MAX_SAFE_INTEGER` carries the same sentence, because a counter that cannot decrement past
+* that point bounds nothing.
+*
+* @remarks
+* Conditions a real origin produces are unreachable from a test otherwise: a browser with
+* site data blocked refuses every operation the permission withholds, an origin with no room left
+* refuses `setItem`, and a person allowing site data grants what was withheld. This makes each of
+* them reachable against a real `Storage` surface rather than a shaped object.
+*
+* The store answers through its methods and intercepts no named-property access, so drive a
+* consumer under test through `getItem` and `setItem`. `Storage` declares an index signature, so
+* `store.theme` typechecks and reads `undefined` while `getItem('theme')` answers, and a property
+* write lands on the object rather than in the store, consuming no quota and meeting no refusal.
+*
+* It is backed by a map of its own and patches nothing: `localStorage` and `sessionStorage` are
+* untouched, no `storage` event is dispatched, and the store is reached only by the code the test
+* hands it to. Reach for {@link clearStorage} where the real browser surfaces are the subject.
+*
+* `length`, `key`, and `getItem` are reads; `clear`, `removeItem`, and `setItem` are writes. A
+* withheld operation raises {@link buildDenial}'s `SecurityError`, and `permit` lifts both
+* permissions at once, the way a person allowing site data lifts them. Reads answer from what the
+* store actually accepted, so a journey reads what the application kept while the host was refusing.
+*
+* `quota` counts accepted `setItem` calls rather than bytes, because the number of writes is what a
+* journey scripts and a byte budget is the browser's own arithmetic. `removeItem` consumes none of
+* it, and `permit` replenishes none of it: room and permission are different refusals, and a test
+* that granted the permission still meets the full origin.
+*
+* @example
+* ```ts
+* const storage = createStorage({ values: { theme: 'dark' }, writes: false })
+* storage.getItem('theme') // 'dark'
+* storage.permit()
+* storage.setItem('theme', 'light')
+* ```
+*/
+function createStorage(options) {
+	const quota = options?.quota;
+	if (quota !== void 0 && (!Number.isSafeInteger(quota) || quota < 0)) throw new Error("Storage quota must be a non-negative integer");
+	const values = new Map(Object.entries(options?.values ?? {}));
+	let reads = options?.reads ?? true;
+	let writes = options?.writes ?? true;
+	let room = quota;
+	return {
+		get length() {
+			if (!reads) throw buildDenial("length");
+			return values.size;
+		},
+		permit() {
+			reads = true;
+			writes = true;
+		},
+		clear() {
+			if (!writes) throw buildDenial("clear");
+			values.clear();
+		},
+		getItem(key) {
+			if (!reads) throw buildDenial("getItem", key);
+			return values.get(key) ?? null;
+		},
+		key(index) {
+			if (!reads) throw buildDenial("key");
+			return [...values.keys()][index] ?? null;
+		},
+		removeItem(key) {
+			if (!writes) throw buildDenial("removeItem", key);
+			values.delete(key);
+		},
+		setItem(key, value) {
+			if (!writes) throw buildDenial("setItem", key);
+			if (room !== void 0) {
+				if (room === 0) throw new DOMException(`No room is left for ${key}`, "QuotaExceededError");
+				room -= 1;
+			}
+			values.set(key, value);
+		}
+	};
+}
+/**
+* Creates a mounted statechart harness that renders one transition table and drives it row by row.
+*
+* @typeParam TState - The states the entity moves between.
+* @typeParam TEvent - The events the entity accepts.
+* @typeParam TContext - The fixture each row drives.
+* @param options - The table, the fixture builder, the state reader, and the delay between rows.
+* @returns The mounted harness, standing idle with its tally at zero.
+* @throws An `Error` reading `Statechart harness mounted no transition` for an empty table, before
+* anything reaches the document.
+*
+* @remarks
+* A page cannot import this package, because the browser entry imports `vitest/browser` at module
+* scope. So the harness is test-side: the suite mounts it, a gate outside the page polls the
+* markup it renders, and `STATECHART_ATTRIBUTES` is the whole contract between the two. Nothing
+* here spells a `data-statechart-*` string of its own, and neither does a gate. That gate has no
+* rejection channel, so every exit writes a terminal status: a run that completes writes `passed` or
+* `failed`, and a run that a `state` reader or a non-`Error` phase throw ends writes `failed` and
+* then rejects with that value by identity, without counting the row as failed.
+*
+* The markup is framework-free. The root carries `status` and the tally; a `role="status"`
+* announcer narrates each step in a sentence; one element carries `state` and renders what the
+* entity's own reader reports; and an ordered list carries one row per scenario, each labelled with
+* its `from`, its `event`, and its `to` and marked with the transition's name. The `state` element
+* mounts empty and takes its attribute from the first row that produces a context, because a state
+* is read from an entity and no entity exists until a row builds one.
+*
+* Construction writes `pending`, mounts the root, renders every row, then writes the row count and
+* `idle` — so a gate that reads `pending` has found a harness whose rows never mounted, and the
+* order is observable from outside through the mutations the document records.
+*
+* `execute` clears every rendered result and the rendered state, writes `running`, and drives each
+* row in order through {@link executeScenario} against a context of that row's own. It continues
+* past a failing row, so one run reports on the whole table rather than stopping at the first
+* finding, and a builder that throws counts as its row failing under {@link buildRefusal}'s
+* sentence, which is the one `executeScenarios` raises. What decides whether a row's phases run is
+* whether its builder returned, not what it returned, so a table whose context is `undefined` drives
+* every phase. A second `execute` runs the same table from a fresh tally and a cleared state.
+*
+* Every reading comes off the markup, so the object and the page cannot disagree, and `failures` is
+* the `scenario` name of each row whose rendered `result` reads `failed` rather than a second list
+* beside them.
+*
+* @example
+* ```ts
+* const harness = createHarness({ scenarios: SCENARIOS, build: buildDisclosure, state: readState })
+* await harness.execute()
+* harness.status // 'passed'
+* harness.destroy()
+* ```
+*/
+function createHarness(options) {
+	const scenarios = options.scenarios;
+	if (scenarios.length === 0) throw new Error("Statechart harness mounted no transition");
+	const root = mount(build("div", { attributes: { [STATECHART_ATTRIBUTES.status]: "pending" } }));
+	const announcer = build("p", { attributes: { role: "status" } });
+	const state = build("p");
+	const rows = build("ol");
+	root.append(announcer, state, rows);
+	const table = scenarios.map((scenario) => ({
+		scenario,
+		element: build("li", {
+			text: `${scenario.transition.name}: ${scenario.transition.from} on ${scenario.transition.event} becomes ${scenario.transition.to}`,
+			attributes: { [STATECHART_ATTRIBUTES.scenario]: scenario.transition.name }
+		})
+	}));
+	for (const row of table) rows.append(row.element);
+	root.setAttribute(STATECHART_ATTRIBUTES.total, String(table.length));
+	root.setAttribute(STATECHART_ATTRIBUTES.passed, "0");
+	root.setAttribute(STATECHART_ATTRIBUTES.failed, "0");
+	root.setAttribute(STATECHART_ATTRIBUTES.status, "idle");
+	announcer.textContent = `Statechart harness is idle, 0 passed and 0 failed of ${table.length}.`;
+	return {
+		root,
+		get status() {
+			const written = root.getAttribute(STATECHART_ATTRIBUTES.status);
+			return requireValue(STATECHART_STATUSES.find((member) => member === written), "Statechart harness carries no status");
+		},
+		get total() {
+			return Number(root.getAttribute(STATECHART_ATTRIBUTES.total));
+		},
+		get passed() {
+			return Number(root.getAttribute(STATECHART_ATTRIBUTES.passed));
+		},
+		get failed() {
+			return Number(root.getAttribute(STATECHART_ATTRIBUTES.failed));
+		},
+		get failures() {
+			const names = [];
+			for (const row of table) {
+				if (row.element.getAttribute(STATECHART_ATTRIBUTES.result) !== "failed") continue;
+				const name = row.element.getAttribute(STATECHART_ATTRIBUTES.scenario);
+				if (name !== null) names.push(name);
+			}
+			return names;
+		},
+		async execute() {
+			for (const row of table) row.element.removeAttribute(STATECHART_ATTRIBUTES.result);
+			state.removeAttribute(STATECHART_ATTRIBUTES.state);
+			state.textContent = "";
+			let passed = 0;
+			let failed = 0;
+			root.setAttribute(STATECHART_ATTRIBUTES.passed, "0");
+			root.setAttribute(STATECHART_ATTRIBUTES.failed, "0");
+			root.setAttribute(STATECHART_ATTRIBUTES.status, "running");
+			announcer.textContent = `Statechart harness is running, 0 passed and 0 failed of ${table.length}.`;
+			try {
+				for (const [index, row] of table.entries()) {
+					let built;
+					let refusal;
+					try {
+						built = { context: await options.build(row.scenario) };
+					} catch (cause) {
+						refusal = buildRefusal(row.scenario.transition.name, cause).message;
+					}
+					if (built !== void 0) {
+						try {
+							await executeScenario(row.scenario, built.context);
+						} catch (cause) {
+							if (!isError(cause)) throw cause;
+							refusal = cause.message;
+						}
+						const current = options.state(built.context);
+						state.setAttribute(STATECHART_ATTRIBUTES.state, current);
+						state.textContent = current;
+					}
+					if (refusal === void 0) passed += 1;
+					else failed += 1;
+					row.element.setAttribute(STATECHART_ATTRIBUTES.result, refusal === void 0 ? "passed" : "failed");
+					root.setAttribute(STATECHART_ATTRIBUTES.passed, String(passed));
+					root.setAttribute(STATECHART_ATTRIBUTES.failed, String(failed));
+					announcer.textContent = refusal ?? `${row.scenario.transition.name} passed.`;
+					if (options.pause !== void 0 && index < table.length - 1) await waitForDelay(options.pause);
+				}
+			} catch (cause) {
+				root.setAttribute(STATECHART_ATTRIBUTES.status, "failed");
+				announcer.textContent = `Statechart harness failed, ${passed} passed and ${failed} failed of ${table.length}.`;
+				throw cause;
+			}
+			const outcome = failed === 0 ? "passed" : "failed";
+			root.setAttribute(STATECHART_ATTRIBUTES.status, outcome);
+			announcer.textContent = `Statechart harness ${outcome}, ${passed} passed and ${failed} failed of ${table.length}.`;
+		},
+		destroy() {
+			root.remove();
+		}
+	};
+}
 //#endregion
-export { ACCESSIBLE_ROLES, CANVAS_COLOR, CAPTURE_PANE, CAPTURE_STAGINGS, CONTENT_ROLES, FIELD_ROLES, FOCUSABLE_SELECTOR, HEADER_ROLES, IMPLICIT_ROLES, blendColor, build, captureFrame, clearStorage, clickAccessible, clickAccessibleWithin, clickDisclosure, commitInput, computeNamePattern, createChannel, createDragEvent, createJournal, createPointerEvent, createPortfolio, describeFocus, describeTree, expandCaptures, extractOrphans, extractStyles, fillAccessible, findKeyframes, findRule, isOutsideViewport, isReachable, isRendered, matchesColor, measureContent, measureContrast, measureLuminance, mount, parseCSSColor, parseColor, readBackdrop, readCascade, readClasses, readContrast, readFocus, readFrame, readLayers, readName, readPage, readPerception, readPixels, readRing, readRole, readRootToken, readRows, readRules, readStates, readStyle, readText, readToken, readValue, releasePane, removeDatabase, render, resolveAccessible, resolveRendered, stagePane, traverseAccessible, typeAccessible, typeInput, waitForFrame };
+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 };
 
 //# sourceMappingURL=index.js.map