@orkestrel/test 0.0.5 → 0.0.6

package/README.md

@@ -5,10 +5,12 @@ real callback rather than a spy. A real host delay. A throw-to-value converter a
 narrower, so `!` and `as` stay banned in tests. Two async collectors and a JSON copier. A frozen
 hostile-value corpus for proving guards are total. A cleanup list that gives every owned resource
 back, newest first. A scratch directory the test owns and destroys, a loopback port for a server the
-test built, and a symlink-refusing source-file walker. A helper ships here only when enough packages
-had already written their own; the guide's
-[Limits](guides/test.md#limits) section states that rule and what it excluded. Add it as a
-devDependency; nothing here runs in production code. Part of the `@orkestrel` line.
+test built, and a symlink-refusing source-file walker. And the browser journey layer, which drives
+a real interface by role and accessible name through the installed Vitest provider. A helper ships
+here only when enough packages had already written their own; the guide's
+[Limits](guides/test.md#limits) section states that rule, what it excluded, and the one door the
+journey layer came through instead. Add it as a devDependency; nothing here runs in production
+code. Part of the `@orkestrel` line.
 
 It has **zero runtime dependencies**, and no exported signature names an `@orkestrel/*` type. Both
 rules exist for one reason: a test helper hands its types straight into the consumer's assertions,
@@ -27,8 +29,10 @@ npm install -D @orkestrel/test
 
 ## Usage
 
-`@orkestrel/test` is the host-independent core. `@orkestrel/test/server` is the Node face. Core
-touches neither `node:*` nor the DOM, so a browser test project imports it unchanged.
+`@orkestrel/test` is the host-independent core. `@orkestrel/test/server` is the Node face.
+`@orkestrel/test/browser` is the journey layer, which drives a real browser through the installed
+Vitest provider. Core touches neither `node:*` nor the DOM, so a browser test project imports it
+unchanged.
 
 ```ts
 import {
@@ -141,6 +145,14 @@ leaves the root through a link in the middle, and skips a symlink met while walk
 sandbox against hostile filesystem content: those refusals stop accidental escape, not an adversary
 who can create hard links where the test process already writes.
 
+The browser face is the journey layer: an accessible-name resolver with exact failure voices,
+region and disclosure targeting, input and traversal verbs, perception readers, a WCAG contrast
+instrument that composites translucent layers, and the capture portfolio. Every acting verb
+resolves its own target from a role and an accessible name — none takes an element, a component
+instance, or a selector — and the whole environment imports `vitest/browser` and DOM globals and
+nothing else, with `vitest` declared as a peer dependency. The guide's
+[Browser](guides/test.md#browser) section carries every export and every voice.
+
 `createLoopback` binds a server the test built. The caller constructs it and keeps every route,
 header, and status on it; this package supplies the bind and the release and nothing else.
 
@@ -179,9 +191,10 @@ rule deciding what ships and what stays in the package that owns it — see
 
 ## Package
 
-Published as two typed entry points per the `exports` field in `package.json`: `@orkestrel/test` for
-the host-independent core, `@orkestrel/test/server` for the Node helpers. Both ship ESM and
-CommonJS.
+Published as three typed entry points per the `exports` field in `package.json`: `@orkestrel/test`
+for the host-independent core, `@orkestrel/test/browser` for the journey layer, and
+`@orkestrel/test/server` for the Node helpers. Core and server ship ESM and CommonJS; the browser
+face ships ESM only, because `vitest/browser` is an ES-only module.
 
 ## License
 

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

@@ -0,0 +1,478 @@
+/**
+ * The interactive ARIA roles a bare accessible name is searched across.
+ *
+ * @remarks
+ * A person names a control, not a role, so the one-argument resolver searches every role a control
+ * can compute. The two-argument form searches exactly the role it is given, which is how a name
+ * shared by a tab and its panel is disambiguated.
+ */
+export declare const ACCESSIBLE_ROLES: readonly string[];
+
+/** One theme-and-viewport pair a capture run renders. */
+export declare interface CaptureVariant {
+    /** The variant's name, which is the second half of every filename the run writes. */
+    readonly name: string;
+    /** The viewport width in pixels. */
+    readonly width: number;
+    /** The viewport height in pixels. */
+    readonly height: number;
+    /**
+     * The document change this variant needs before the viewport is resized — a theme attribute, a
+     * density class, a language direction. Omit it when the variant is a viewport alone.
+     */
+    readonly apply?: () => void;
+}
+
+/**
+ * Clicks one visible, focus-reachable control by its accessible name through the browser provider.
+ *
+ * @param name - The target's exact accessible name.
+ * @returns A promise resolving after trusted activation completes.
+ *
+ * @example
+ * ```ts
+ * await clickAccessible('Apply')
+ * ```
+ */
+export declare function clickAccessible(name: string): Promise<void>;
+
+/**
+ * Clicks one visible, focus-reachable control by its exact ARIA role and accessible name,
+ * disambiguating a bare name that answers for more than one rendered element.
+ *
+ * @param role - The control's exact ARIA role.
+ * @param name - The target's exact accessible name.
+ * @returns A promise resolving after trusted activation completes.
+ *
+ * @example
+ * ```ts
+ * await clickAccessible('tab', 'Drafts')
+ * ```
+ */
+export declare function clickAccessible(role: string, name: string): Promise<void>;
+
+/**
+ * Clicks one human-reachable control by role and accessible-name text inside a named region.
+ *
+ * @param region - The containing region's exact accessible name.
+ * @param role - The control's exact ARIA role.
+ * @param name - The rendered accessible-name text that identifies the control in that region.
+ * @returns A promise resolving after trusted activation completes.
+ * @throws When the named control is absent, unreachable, or ambiguous inside the region.
+ *
+ * @remarks
+ * Use this form when repeated short verbs such as `Add`, or a line whose status completes its
+ * accessible name, need the same region context a person uses to disambiguate them.
+ *
+ * @example
+ * ```ts
+ * await clickAccessibleWithin('Ledger', 'button', 'Monthly income')
+ * ```
+ */
+export declare function clickAccessibleWithin(region: string, role: string, name: string): Promise<void>;
+
+/**
+ * Opens or closes one native details disclosure by its rendered summary.
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * @example
+ * ```ts
+ * await clickDisclosure('Advanced')
+ * ```
+ */
+export declare function clickDisclosure(name: string): Promise<void>;
+
+/**
+ * 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.
+ * @returns The relative-luminance contrast ratio.
+ * @throws When the browser does not expose parseable computed colors.
+ *
+ * @remarks
+ * A transparent or translucent background resolves through the element's ancestors: every painted
+ * layer from the element up to the first opaque one composites top-over-bottom onto that opaque
+ * base, so a 3% surface tint reads as a tint over what shows through it rather than as a
+ * full-strength paint. A translucent foreground then resolves against that effective background
+ * before luminance is measured.
+ *
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const container = render('<p style="background: #000; color: #fff">Ready</p>')
+ * contrast(requireValue(container.firstElementChild)) // 21
+ * ```
+ */
+export declare function contrast(element: Element): number;
+
+/**
+ * Creates the capture portfolio one run places its screenshots through.
+ *
+ * @param options - The state registry, the variant matrix, the variant this run renders, the
+ * directory it writes into, and whether it writes at all.
+ * @returns The portfolio: its registry expansion, what it has placed, and `place`.
+ * @throws When no registered variant carries the name `variant` names.
+ *
+ * @remarks
+ * A disabled portfolio is the ordinary run. `place` then resizes nothing, writes nothing, and
+ * records nothing, so a journey calls it unconditionally and a suite with the flag unset pays for
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const portfolio = createPortfolio({
+ * 	states: ['start-empty'],
+ * 	variants: [{ name: 'dark-390', width: 390, height: 844 }],
+ * 	variant: 'dark-390',
+ * 	directory: '../../tmp/capture/states',
+ * })
+ * await portfolio.place('start-empty')
+ * ```
+ */
+export declare function createPortfolio(options: PortfolioOptions): PortfolioInterface;
+
+/**
+ * Expands a capture registry across every variant into the filenames a complete portfolio holds.
+ *
+ * @param states - The registered state names.
+ * @param variants - The variants the portfolio is rendered in.
+ * @returns One `<state>--<variant>.png` name per pair, each state's variants together, in registry
+ * order.
+ *
+ * @remarks
+ * The expansion is the portfolio's own definition of complete, so a duplicate in it is a registry
+ * defect a proof reads directly rather than a collision discovered on disk.
+ *
+ * @example
+ * ```ts
+ * expandCaptures(['start'], [{ name: 'dark-390', width: 390, height: 844 }])
+ * // ['start--dark-390.png']
+ * ```
+ */
+export declare function expandCaptures(states: readonly string[], variants: readonly CaptureVariant[]): readonly string[];
+
+/**
+ * Replaces a named field's value in one operation, for text too long to type key by key.
+ *
+ * @param name - The field's exact accessible name.
+ * @param text - The text to place in the field.
+ * @returns A promise resolving after the browser commits the value.
+ *
+ * @remarks
+ * The provider drives the real element, so the field publishes the same input event a person's
+ * typing publishes. Use {@link typeAccessible} wherever the keystrokes themselves are the subject.
+ *
+ * @example
+ * ```ts
+ * await fillAccessible('Payload', '{"status":"ready"}')
+ * ```
+ */
+export declare function fillAccessible(name: string, text: string): Promise<void>;
+
+/**
+ * Determines whether a rectangle lies wholly outside the browser viewport.
+ *
+ * @param rectangle - The measured client rectangle to inspect.
+ * @returns `true` when no part of the rectangle intersects the viewport.
+ *
+ * @example
+ * ```ts
+ * isOutsideViewport(element.getBoundingClientRect())
+ * ```
+ */
+export declare function isOutsideViewport(rectangle: DOMRectReadOnly): boolean;
+
+/** The registry of capture states one run places, and the files it wrote placing them. */
+export declare interface PortfolioInterface {
+    /** The name of the variant this run renders. */
+    readonly variant: string;
+    /** Every state placed so far, in placement order. */
+    readonly states: readonly string[];
+    /** Every path written so far, in write order. */
+    readonly paths: readonly string[];
+    /** The registry expanded across every variant: the filenames a complete portfolio holds. */
+    readonly files: readonly string[];
+    /**
+     * Places one registered state: applies the variant, resizes the viewport, and writes the
+     * screenshot.
+     *
+     * @param state - The state name from the registry.
+     * @returns The written path, or `undefined` when the portfolio is not enabled.
+     * @throws When the state is not registered or has already been placed.
+     */
+    place(state: string): Promise<string | undefined>;
+}
+
+/** Options for a capture portfolio. */
+export declare interface PortfolioOptions {
+    /**
+     * Every state name the journeys place, declared once. `place` refuses a name absent from this
+     * list, so the registry and the disk cannot drift apart.
+     */
+    readonly states: readonly string[];
+    /** Every variant the portfolio can be rendered in. One run renders exactly one of them. */
+    readonly variants: readonly CaptureVariant[];
+    /** The name of the variant this run renders. Creation throws when no variant carries it. */
+    readonly variant: string;
+    /** The directory each written file is placed in, relative to the calling test file. */
+    readonly directory: string;
+    /**
+     * Whether this run writes files. An ordinary run leaves it unset, so `place` resizes nothing,
+     * writes nothing, and records nothing.
+     */
+    readonly enabled?: boolean;
+}
+
+/**
+ * Presses a browser-keyboard sequence using Vitest's installed user-event syntax.
+ *
+ * @param keys - The keys or key descriptors to press.
+ * @returns A promise resolving after the sequence completes.
+ *
+ * @example
+ * ```ts
+ * await pressKeys('{ArrowRight}{Enter}')
+ * ```
+ */
+export declare function pressKeys(keys: string): Promise<void>;
+
+/**
+ * Collects every class token the stylesheets loaded into this document actually define.
+ *
+ * @returns The set of class names reachable in the shipped cascade.
+ *
+ * @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.
+ *
+ * @example
+ * ```ts
+ * readCascade().has('card')
+ * ```
+ */
+export declare function readCascade(): ReadonlySet<string>;
+
+/**
+ * Reads the rendered text of the element that currently holds focus.
+ *
+ * @returns The focused HTML element's trimmed rendered text, including an empty string, or
+ * `undefined` when focus rests on a non-HTML element. When nothing holds focus, the browser
+ * reports the document body as active, so the whole page's rendered text returns.
+ *
+ * @example
+ * ```ts
+ * await traverseAccessible('Evaluate')
+ * readFocus() // 'Evaluate'
+ * ```
+ */
+export declare function readFocus(): string | undefined;
+
+/**
+ * Reads the normalized visible text of the whole page.
+ *
+ * @returns Every rendered word in the document body, its whitespace runs collapsed and trimmed.
+ *
+ * @remarks
+ * This is the reader for a sentence that spans two regions and for a vocabulary sweep over the
+ * words an interface uses. Reach for {@link readPerception} wherever one named region is the
+ * subject, because that one throws when the region is missing and this one returns whatever is
+ * there.
+ *
+ * @example
+ * ```ts
+ * readPage().includes('No cases yet')
+ * ```
+ */
+export declare function readPage(): string;
+
+/**
+ * Reads the normalized visible text of one named region, dialog, table, tab panel, or alert.
+ *
+ * @param name - The region's exact accessible name.
+ * @returns The text a screen reader can perceive in the visible region, including descendant
+ * visually-hidden content.
+ * @throws When the named region is absent, hidden, or ambiguous.
+ *
+ * @example
+ * ```ts
+ * readPerception('Run')
+ * ```
+ */
+export declare function readPerception(name: string): string;
+
+/**
+ * Reads the normalized visible text of every element a selector matches, in document order.
+ *
+ * @param root - The subtree to search.
+ * @param selector - The CSS selector naming the rows.
+ * @returns One line per matched element, its text runs collapsed and single-space joined.
+ *
+ * @remarks
+ * The line is built from the row's text nodes rather than from `textContent`, because adjacent
+ * inline elements carry no whitespace between them in compiled template output and would otherwise
+ * read as one run-together word.
+ *
+ * @example
+ * ```ts
+ * readRows(container, 'li')
+ * ```
+ */
+export declare function readRows(root: ParentNode, selector: string): readonly string[];
+
+/**
+ * Reads the value a resolved control renders.
+ *
+ * @param role - The control's exact ARIA role.
+ * @param name - The control's exact accessible name.
+ * @returns The control's current value.
+ * @throws When the target does not resolve, or resolves to an element that carries no value.
+ *
+ * @remarks
+ * A control's value is a rendered fact a person can read, not internal state, so it is read from
+ * the resolved element rather than from the component that produced it.
+ *
+ * @example
+ * ```ts
+ * readValue('spinbutton', 'Runs') // '3'
+ * ```
+ */
+export declare function readValue(role: string, name: string): string;
+
+/**
+ * Renders trusted fixture markup into a container attached to the document.
+ *
+ * @param markup - The fixture markup to render.
+ * @returns The attached container.
+ *
+ * @example
+ * ```ts
+ * const container = render('<button type="button">Save</button>')
+ * container.remove()
+ * ```
+ */
+export declare function render(markup: string): HTMLDivElement;
+
+/**
+ * Resolves one visible, focus-reachable interactive element by its exact accessible name. A
+ * wholly-off-viewport target is scrolled into view before reachability is measured.
+ *
+ * @param name - The accessible name rendered for the target.
+ * @returns The one reachable element carrying that name.
+ * @throws When no matching element exists; every match is disconnected, hidden, zero-sized, still
+ * outside the viewport after being scrolled into view, removed from sequential focus, disabled, or
+ * inside an inert subtree; or several reachable matches make the name ambiguous.
+ *
+ * @example
+ * ```ts
+ * resolveAccessible('Save changes')
+ * ```
+ */
+export declare function resolveAccessible(name: string): HTMLElement;
+
+/**
+ * Resolves one visible, focus-reachable interactive element by its exact ARIA role and accessible
+ * name, disambiguating a bare name that answers for more than one rendered element. A
+ * wholly-off-viewport target is scrolled into view before reachability is measured.
+ *
+ * @param role - The element's exact ARIA role.
+ * @param name - The accessible name rendered for the target.
+ * @returns The one reachable element carrying that role and name.
+ * @throws When no matching element exists; every match is disconnected, hidden, zero-sized, still
+ * outside the viewport after being scrolled into view, removed from sequential focus, disabled, or
+ * inside an inert subtree; or several reachable matches make the role/name pair ambiguous.
+ *
+ * @example
+ * ```ts
+ * resolveAccessible('tab', 'Drafts')
+ * ```
+ */
+export declare function resolveAccessible(role: string, name: string): HTMLElement;
+
+/**
+ * Resolves one rendered, focus-reachable interactive element without requiring it to intersect the
+ * viewport yet.
+ *
+ * @param first - The accessible name, or the exact ARIA role when `second` is present.
+ * @param second - The accessible name when `first` supplies the role.
+ * @returns The one rendered element carrying that name and optional role.
+ * @throws When no matching element exists, every match is hidden or unreachable, or several
+ * rendered matches make the name ambiguous.
+ *
+ * @remarks
+ * This is the resolver the acting verbs use, so a click does not fail on a target the act itself
+ * scrolls into view. Use {@link resolveAccessible} wherever the target must already be on screen.
+ *
+ * @example
+ * ```ts
+ * resolveRendered('tab', 'Drafts')
+ * ```
+ */
+export declare function resolveRendered(first: string, second?: string): HTMLElement;
+
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * style(button, 'padding-left')
+ * ```
+ */
+export declare function style(element: Element, property: string): string;
+
+/**
+ * Reaches a named control only through natural forward Tab traversal from the current focus.
+ *
+ * @param name - The target's exact accessible name.
+ * @returns The target after the browser moves focus to it.
+ * @throws When one complete traversal cannot reach the target.
+ *
+ * @example
+ * ```ts
+ * await traverseAccessible('Evaluate')
+ * ```
+ */
+export declare function traverseAccessible(name: string): Promise<HTMLElement>;
+
+/**
+ * Replaces a named field's value through focus, select-all, deletion, and real keystrokes.
+ *
+ * @param name - The field's exact accessible name.
+ * @param text - The text to type.
+ * @returns A promise resolving after every keystroke completes.
+ *
+ * @example
+ * ```ts
+ * await typeAccessible('Runs', '3')
+ * ```
+ */
+export declare function typeAccessible(name: string, text: string): Promise<void>;
+
+/**
+ * Waits for one animation frame to settle pending browser paint work.
+ *
+ * @returns A promise resolving after one `requestAnimationFrame`.
+ *
+ * @example
+ * ```ts
+ * await waitForFrame()
+ * ```
+ */
+export declare function waitForFrame(): Promise<void>;
+
+export { }

package/dist/src/browser/index.js

@@ -0,0 +1,619 @@
+import { page, userEvent } from "vitest/browser";
+//#region src/browser/constants.ts
+/**
+* The interactive ARIA roles a bare accessible name is searched across.
+*
+* @remarks
+* A person names a control, not a role, so the one-argument resolver searches every role a control
+* can compute. The two-argument form searches exactly the role it is given, which is how a name
+* shared by a tab and its panel is disambiguated.
+*/
+var ACCESSIBLE_ROLES = Object.freeze([
+	"button",
+	"checkbox",
+	"combobox",
+	"link",
+	"listbox",
+	"menuitem",
+	"option",
+	"radio",
+	"searchbox",
+	"slider",
+	"spinbutton",
+	"switch",
+	"tab",
+	"tabpanel",
+	"textbox",
+	"treeitem"
+]);
+//#endregion
+//#region src/browser/helpers.ts
+/**
+* Determines whether a rectangle lies wholly outside the browser viewport.
+*
+* @param rectangle - The measured client rectangle to inspect.
+* @returns `true` when no part of the rectangle intersects the viewport.
+*
+* @example
+* ```ts
+* isOutsideViewport(element.getBoundingClientRect())
+* ```
+*/
+function isOutsideViewport(rectangle) {
+	return rectangle.bottom <= 0 || rectangle.right <= 0 || rectangle.top >= window.innerHeight || rectangle.left >= window.innerWidth;
+}
+/**
+* Resolves one rendered, focus-reachable interactive element without requiring it to intersect the
+* viewport yet.
+*
+* @param first - The accessible name, or the exact ARIA role when `second` is present.
+* @param second - The accessible name when `first` supplies the role.
+* @returns The one rendered element carrying that name and optional role.
+* @throws When no matching element exists, every match is hidden or unreachable, or several
+* rendered matches make the name ambiguous.
+*
+* @remarks
+* This is the resolver the acting verbs use, so a click does not fail on a target the act itself
+* scrolls into view. Use {@link resolveAccessible} wherever the target must already be on screen.
+*
+* @example
+* ```ts
+* resolveRendered('tab', 'Drafts')
+* ```
+*/
+function resolveRendered(first, second) {
+	const name = second ?? first;
+	const roles = second === void 0 ? ACCESSIBLE_ROLES : [first];
+	const matches = [];
+	for (const role of roles) for (const element of page.getByRole(role, {
+		name,
+		exact: true,
+		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;
+	});
+	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;
+	if (target === void 0) throw new Error(`Interactive target "${name}" could not be resolved`);
+	return target;
+}
+function resolveAccessible(first, second) {
+	const target = resolveRendered(first, second);
+	let rectangle = target.getBoundingClientRect();
+	if (isOutsideViewport(rectangle)) {
+		target.scrollIntoView({
+			block: "nearest",
+			behavior: "instant"
+		});
+		rectangle = target.getBoundingClientRect();
+	}
+	if (isOutsideViewport(rectangle)) throw new Error(`Interactive target "${second ?? first}" is unreachable after scrolling`);
+	return target;
+}
+async function clickAccessible(first, second) {
+	const target = resolveRendered(first, second);
+	await userEvent.click(target);
+}
+/**
+* Clicks one human-reachable control by role and accessible-name text inside a named region.
+*
+* @param region - The containing region's exact accessible name.
+* @param role - The control's exact ARIA role.
+* @param name - The rendered accessible-name text that identifies the control in that region.
+* @returns A promise resolving after trusted activation completes.
+* @throws When the named control is absent, unreachable, or ambiguous inside the region.
+*
+* @remarks
+* Use this form when repeated short verbs such as `Add`, or a line whose status completes its
+* accessible name, need the same region context a person uses to disambiguate them.
+*
+* @example
+* ```ts
+* await clickAccessibleWithin('Ledger', 'button', 'Monthly income')
+* ```
+*/
+async function clickAccessibleWithin(region, role, name) {
+	const reachable = page.getByRole("region", {
+		name: region,
+		exact: true
+	}).getByRole(role, {
+		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;
+	});
+	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;
+	if (!(target instanceof HTMLElement)) throw new Error(`Interactive target "${name}" could not be resolved inside "${region}"`);
+	await userEvent.click(target);
+}
+/**
+* Opens or closes one native details disclosure by its rendered summary.
+*
+* @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.
+*
+* @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.
+*
+* @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;
+	});
+	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;
+	if (target === void 0) throw new Error(`Native disclosure "${name}" could not be resolved`);
+	await userEvent.click(target);
+}
+/**
+* Replaces a named field's value through focus, select-all, deletion, and real keystrokes.
+*
+* @param name - The field's exact accessible name.
+* @param text - The text to type.
+* @returns A promise resolving after every keystroke completes.
+*
+* @example
+* ```ts
+* await typeAccessible('Runs', '3')
+* ```
+*/
+async function typeAccessible(name, text) {
+	await userEvent.click(resolveRendered(name));
+	await userEvent.keyboard("{Control>}a{/Control}{Backspace}");
+	if (text === "") return;
+	await userEvent.keyboard(text.replaceAll("{", "{{").replaceAll("[", "[["));
+}
+/**
+* Replaces a named field's value in one operation, for text too long to type key by key.
+*
+* @param name - The field's exact accessible name.
+* @param text - The text to place in the field.
+* @returns A promise resolving after the browser commits the value.
+*
+* @remarks
+* The provider drives the real element, so the field publishes the same input event a person's
+* typing publishes. Use {@link typeAccessible} wherever the keystrokes themselves are the subject.
+*
+* @example
+* ```ts
+* await fillAccessible('Payload', '{"status":"ready"}')
+* ```
+*/
+async function fillAccessible(name, text) {
+	await userEvent.fill(resolveRendered(name), text);
+}
+/**
+* Presses a browser-keyboard sequence using Vitest's installed user-event syntax.
+*
+* @param keys - The keys or key descriptors to press.
+* @returns A promise resolving after the sequence completes.
+*
+* @example
+* ```ts
+* await pressKeys('{ArrowRight}{Enter}')
+* ```
+*/
+async function pressKeys(keys) {
+	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.
+* @returns The target after the browser moves focus to it.
+* @throws When one complete traversal cannot reach the target.
+*
+* @example
+* ```ts
+* await traverseAccessible('Evaluate')
+* ```
+*/
+async function traverseAccessible(name) {
+	resolveRendered(name);
+	const cap = document.querySelectorAll("a[href], button, input, select, textarea, [tabindex]").length * 3 + 10;
+	const visited = /* @__PURE__ */ new Set();
+	const trail = [];
+	for (let attempt = 0; attempt < cap; attempt += 1) {
+		await userEvent.tab();
+		const focused = document.activeElement;
+		if (!(focused instanceof HTMLElement) || focused === document.body) continue;
+		let current;
+		try {
+			current = resolveRendered(name);
+		} catch {
+			continue;
+		}
+		if (focused === current) return current;
+		if (visited.has(focused)) break;
+		visited.add(focused);
+		trail.push(`${focused.tagName}:${focused.innerText.slice(0, 20)}`);
+	}
+	throw new Error(`Interactive target "${name}" is not reachable through forward Tab traversal: ${trail.join(" > ")}`);
+}
+/**
+* Reads the normalized visible text of one named region, dialog, table, tab panel, or alert.
+*
+* @param name - The region's exact accessible name.
+* @returns The text a screen reader can perceive in the visible region, including descendant
+* visually-hidden content.
+* @throws When the named region is absent, hidden, or ambiguous.
+*
+* @example
+* ```ts
+* readPerception('Run')
+* ```
+*/
+function readPerception(name) {
+	const matches = [];
+	for (const role of [
+		"alert",
+		"alertdialog",
+		"dialog",
+		"region",
+		"status",
+		"table",
+		"tabpanel"
+	]) for (const element of page.getByRole(role, {
+		name,
+		exact: true,
+		includeHidden: true
+	}).elements()) if (element instanceof HTMLElement && !matches.includes(element)) matches.push(element);
+	const visible = matches.filter((element) => {
+		const rectangle = element.getBoundingClientRect();
+		return element.isConnected && element.checkVisibility({
+			checkOpacity: true,
+			checkVisibilityCSS: true
+		}) && rectangle.width > 0 && rectangle.height > 0;
+	});
+	if (visible.length === 0) throw new Error(`Named region "${name}" is not visible`);
+	if (visible.length > 1) throw new Error(`Named region "${name}" is ambiguous across ${visible.length} elements`);
+	const [region] = visible;
+	if (region === void 0) throw new Error(`Named region "${name}" could not be resolved`);
+	return region.innerText.replaceAll(/\s+/g, " ").trim();
+}
+/**
+* Reads the normalized visible text of the whole page.
+*
+* @returns Every rendered word in the document body, its whitespace runs collapsed and trimmed.
+*
+* @remarks
+* This is the reader for a sentence that spans two regions and for a vocabulary sweep over the
+* words an interface uses. Reach for {@link readPerception} wherever one named region is the
+* subject, because that one throws when the region is missing and this one returns whatever is
+* there.
+*
+* @example
+* ```ts
+* readPage().includes('No cases yet')
+* ```
+*/
+function readPage() {
+	return document.body.innerText.replaceAll(/\s+/g, " ").trim();
+}
+/**
+* Reads the rendered text of the element that currently holds focus.
+*
+* @returns The focused HTML element's trimmed rendered text, including an empty string, or
+* `undefined` when focus rests on a non-HTML element. When nothing holds focus, the browser
+* reports the document body as active, so the whole page's rendered text returns.
+*
+* @example
+* ```ts
+* await traverseAccessible('Evaluate')
+* readFocus() // 'Evaluate'
+* ```
+*/
+function readFocus() {
+	const focused = document.activeElement;
+	return focused instanceof HTMLElement ? focused.innerText.trim() : void 0;
+}
+/**
+* Reads the value a resolved control renders.
+*
+* @param role - The control's exact ARIA role.
+* @param name - The control's exact accessible name.
+* @returns The control's current value.
+* @throws When the target does not resolve, or resolves to an element that carries no value.
+*
+* @remarks
+* A control's value is a rendered fact a person can read, not internal state, so it is read from
+* the resolved element rather than from the component that produced it.
+*
+* @example
+* ```ts
+* readValue('spinbutton', 'Runs') // '3'
+* ```
+*/
+function readValue(role, name) {
+	const control = resolveAccessible(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;
+}
+/**
+* Waits for one animation frame to settle pending browser paint work.
+*
+* @returns A promise resolving after one `requestAnimationFrame`.
+*
+* @example
+* ```ts
+* await waitForFrame()
+* ```
+*/
+function waitForFrame() {
+	return new Promise((resolve) => requestAnimationFrame(() => resolve()));
+}
+/**
+* Renders trusted fixture markup into a container attached to the document.
+*
+* @param markup - The fixture markup to render.
+* @returns The attached container.
+*
+* @example
+* ```ts
+* const container = render('<button type="button">Save</button>')
+* container.remove()
+* ```
+*/
+function render(markup) {
+	const container = document.createElement("div");
+	container.innerHTML = markup;
+	document.body.append(container);
+	return container;
+}
+/**
+* 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.
+* @returns The relative-luminance contrast ratio.
+* @throws When the browser does not expose parseable computed colors.
+*
+* @remarks
+* A transparent or translucent background resolves through the element's ancestors: every painted
+* layer from the element up to the first opaque one composites top-over-bottom onto that opaque
+* base, so a 3% surface tint reads as a tint over what shows through it rather than as a
+* full-strength paint. A translucent foreground then resolves against that effective background
+* before luminance is measured.
+*
+* 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.
+*
+* @example
+* ```ts
+* const container = render('<p style="background: #000; color: #fff">Ready</p>')
+* contrast(requireValue(container.firstElementChild)) // 21
+* ```
+*/
+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);
+		});
+	}
+	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);
+}
+/**
+* Collects every class token the stylesheets loaded into this document actually define.
+*
+* @returns The set of class names reachable in the shipped cascade.
+*
+* @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.
+*
+* @example
+* ```ts
+* readCascade().has('card')
+* ```
+*/
+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);
+		if (!(rule instanceof CSSStyleRule)) continue;
+		for (const match of rule.selectorText.matchAll(/\.([a-zA-Z][\w-]*)/g)) known.add(String(match[1]));
+	}
+	return known;
+}
+/**
+* Reads the normalized visible text of every element a selector matches, in document order.
+*
+* @param root - The subtree to search.
+* @param selector - The CSS selector naming the rows.
+* @returns One line per matched element, its text runs collapsed and single-space joined.
+*
+* @remarks
+* The line is built from the row's text nodes rather than from `textContent`, because adjacent
+* inline elements carry no whitespace between them in compiled template output and would otherwise
+* read as one run-together word.
+*
+* @example
+* ```ts
+* readRows(container, 'li')
+* ```
+*/
+function readRows(root, selector) {
+	const rows = [];
+	for (const row of root.querySelectorAll(selector)) {
+		const parts = [];
+		const walker = document.createTreeWalker(row, NodeFilter.SHOW_TEXT);
+		while (walker.nextNode() !== null) {
+			const text = (walker.currentNode.textContent ?? "").replaceAll(/\s+/g, " ").trim();
+			if (text !== "") parts.push(text);
+		}
+		rows.push(parts.join(" "));
+	}
+	return rows;
+}
+/**
+* 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.
+*
+* @example
+* ```ts
+* style(button, 'padding-left')
+* ```
+*/
+function style(element, property) {
+	return getComputedStyle(element).getPropertyValue(property);
+}
+/**
+* Expands a capture registry across every variant into the filenames a complete portfolio holds.
+*
+* @param states - The registered state names.
+* @param variants - The variants the portfolio is rendered in.
+* @returns One `<state>--<variant>.png` name per pair, each state's variants together, in registry
+* order.
+*
+* @remarks
+* The expansion is the portfolio's own definition of complete, so a duplicate in it is a registry
+* defect a proof reads directly rather than a collision discovered on disk.
+*
+* @example
+* ```ts
+* expandCaptures(['start'], [{ name: 'dark-390', width: 390, height: 844 }])
+* // ['start--dark-390.png']
+* ```
+*/
+function expandCaptures(states, variants) {
+	const files = [];
+	for (const state of states) for (const variant of variants) files.push(`${state}--${variant.name}.png`);
+	return files;
+}
+//#endregion
+//#region src/browser/factories.ts
+/**
+* Creates the capture portfolio one run places its screenshots through.
+*
+* @param options - The state registry, the variant matrix, the variant this run renders, the
+* directory it writes into, and whether it writes at all.
+* @returns The portfolio: its registry expansion, what it has placed, and `place`.
+* @throws When no registered variant carries the name `variant` names.
+*
+* @remarks
+* A disabled portfolio is the ordinary run. `place` then resizes nothing, writes nothing, and
+* records nothing, so a journey calls it unconditionally and a suite with the flag unset pays for
+* 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.
+*
+* @example
+* ```ts
+* const portfolio = createPortfolio({
+* 	states: ['start-empty'],
+* 	variants: [{ name: 'dark-390', width: 390, height: 844 }],
+* 	variant: 'dark-390',
+* 	directory: '../../tmp/capture/states',
+* })
+* await portfolio.place('start-empty')
+* ```
+*/
+function createPortfolio(options) {
+	const selected = options.variants.find((candidate) => candidate.name === options.variant);
+	if (selected === void 0) throw new Error(`Capture variant "${options.variant}" is not registered`);
+	const registry = [...options.states];
+	const files = expandCaptures(registry, options.variants);
+	const enabled = options.enabled ?? false;
+	const placed = [];
+	const paths = [];
+	return {
+		variant: options.variant,
+		files,
+		get states() {
+			return [...placed];
+		},
+		get paths() {
+			return [...paths];
+		},
+		async place(state) {
+			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}` });
+			placed.push(state);
+			paths.push(written);
+			return written;
+		}
+	};
+}
+//#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 };
+
+//# sourceMappingURL=index.js.map

package/dist/src/browser/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/browser/constants.ts","../../../src/browser/helpers.ts","../../../src/browser/factories.ts"],"sourcesContent":["/**\n * The interactive ARIA roles a bare accessible name is searched across.\n *\n * @remarks\n * A person names a control, not a role, so the one-argument resolver searches every role a control\n * can compute. The two-argument form searches exactly the role it is given, which is how a name\n * shared by a tab and its panel is disambiguated.\n */\nexport const ACCESSIBLE_ROLES: readonly string[] = Object.freeze([\n\t'button',\n\t'checkbox',\n\t'combobox',\n\t'link',\n\t'listbox',\n\t'menuitem',\n\t'option',\n\t'radio',\n\t'searchbox',\n\t'slider',\n\t'spinbutton',\n\t'switch',\n\t'tab',\n\t'tabpanel',\n\t'textbox',\n\t'treeitem',\n])\n","import type { CaptureVariant } from './types.js'\nimport { page, userEvent } from 'vitest/browser'\nimport { ACCESSIBLE_ROLES } from './constants.js'\n\n/**\n * Determines whether a rectangle lies wholly outside the browser viewport.\n *\n * @param rectangle - The measured client rectangle to inspect.\n * @returns `true` when no part of the rectangle intersects the viewport.\n *\n * @example\n * ```ts\n * isOutsideViewport(element.getBoundingClientRect())\n * ```\n */\nexport function isOutsideViewport(rectangle: DOMRectReadOnly): boolean {\n\treturn (\n\t\trectangle.bottom <= 0 ||\n\t\trectangle.right <= 0 ||\n\t\trectangle.top >= window.innerHeight ||\n\t\trectangle.left >= window.innerWidth\n\t)\n}\n\n/**\n * Resolves one rendered, focus-reachable interactive element without requiring it to intersect the\n * viewport yet.\n *\n * @param first - The accessible name, or the exact ARIA role when `second` is present.\n * @param second - The accessible name when `first` supplies the role.\n * @returns The one rendered element carrying that name and optional role.\n * @throws When no matching element exists, every match is hidden or unreachable, or several\n * rendered matches make the name ambiguous.\n *\n * @remarks\n * This is the resolver the acting verbs use, so a click does not fail on a target the act itself\n * scrolls into view. Use {@link resolveAccessible} wherever the target must already be on screen.\n *\n * @example\n * ```ts\n * resolveRendered('tab', 'Drafts')\n * ```\n */\nexport function resolveRendered(first: string, second?: string): HTMLElement {\n\tconst name = second ?? first\n\tconst roles = second === undefined ? ACCESSIBLE_ROLES : [first]\n\tconst matches: HTMLElement[] = []\n\tfor (const role of roles) {\n\t\tfor (const element of page\n\t\t\t.getByRole(role, { name, exact: true, includeHidden: true })\n\t\t\t.elements()) {\n\t\t\tif (element instanceof HTMLElement && !matches.includes(element)) matches.push(element)\n\t\t}\n\t}\n\tif (matches.length === 0) {\n\t\tthrow new Error(`No interactive element has the accessible name \"${name}\"`)\n\t}\n\tconst reachable = matches.filter((element) => {\n\t\tconst rectangle = element.getBoundingClientRect()\n\t\treturn (\n\t\t\telement.isConnected &&\n\t\t\telement.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true }) &&\n\t\t\trectangle.width > 0 &&\n\t\t\trectangle.height > 0 &&\n\t\t\telement.tabIndex >= 0 &&\n\t\t\t!element.matches(':disabled, [aria-disabled=\"true\"]') &&\n\t\t\telement.closest('[inert]') === null\n\t\t)\n\t})\n\tif (reachable.length === 0) {\n\t\tthrow new Error(`Interactive target \"${name}\" is not visible and focus-reachable`)\n\t}\n\tif (reachable.length > 1) {\n\t\tthrow new Error(`Interactive target \"${name}\" is ambiguous across ${reachable.length} elements`)\n\t}\n\tconst [target] = reachable\n\tif (target === undefined) throw new Error(`Interactive target \"${name}\" could not be resolved`)\n\treturn target\n}\n\n/**\n * Resolves one visible, focus-reachable interactive element by its exact accessible name. A\n * wholly-off-viewport target is scrolled into view before reachability is measured.\n *\n * @param name - The accessible name rendered for the target.\n * @returns The one reachable element carrying that name.\n * @throws When no matching element exists; every match is disconnected, hidden, zero-sized, still\n * outside the viewport after being scrolled into view, removed from sequential focus, disabled, or\n * inside an inert subtree; or several reachable matches make the name ambiguous.\n *\n * @example\n * ```ts\n * resolveAccessible('Save changes')\n * ```\n */\nexport function resolveAccessible(name: string): HTMLElement\n/**\n * Resolves one visible, focus-reachable interactive element by its exact ARIA role and accessible\n * name, disambiguating a bare name that answers for more than one rendered element. A\n * wholly-off-viewport target is scrolled into view before reachability is measured.\n *\n * @param role - The element's exact ARIA role.\n * @param name - The accessible name rendered for the target.\n * @returns The one reachable element carrying that role and name.\n * @throws When no matching element exists; every match is disconnected, hidden, zero-sized, still\n * outside the viewport after being scrolled into view, removed from sequential focus, disabled, or\n * inside an inert subtree; or several reachable matches make the role/name pair ambiguous.\n *\n * @example\n * ```ts\n * resolveAccessible('tab', 'Drafts')\n * ```\n */\nexport function resolveAccessible(role: string, name: string): HTMLElement\nexport function resolveAccessible(first: string, second?: string): HTMLElement {\n\tconst target = resolveRendered(first, second)\n\tlet rectangle = target.getBoundingClientRect()\n\tif (isOutsideViewport(rectangle)) {\n\t\ttarget.scrollIntoView({ block: 'nearest', behavior: 'instant' })\n\t\trectangle = target.getBoundingClientRect()\n\t}\n\tif (isOutsideViewport(rectangle)) {\n\t\tthrow new Error(`Interactive target \"${second ?? first}\" is unreachable after scrolling`)\n\t}\n\treturn target\n}\n\n/**\n * Clicks one visible, focus-reachable control by its accessible name through the browser provider.\n *\n * @param name - The target's exact accessible name.\n * @returns A promise resolving after trusted activation completes.\n *\n * @example\n * ```ts\n * await clickAccessible('Apply')\n * ```\n */\nexport async function clickAccessible(name: string): Promise<void>\n/**\n * Clicks one visible, focus-reachable control by its exact ARIA role and accessible name,\n * disambiguating a bare name that answers for more than one rendered element.\n *\n * @param role - The control's exact ARIA role.\n * @param name - The target's exact accessible name.\n * @returns A promise resolving after trusted activation completes.\n *\n * @example\n * ```ts\n * await clickAccessible('tab', 'Drafts')\n * ```\n */\nexport async function clickAccessible(role: string, name: string): Promise<void>\nexport async function clickAccessible(first: string, second?: string): Promise<void> {\n\tconst target = resolveRendered(first, second)\n\tawait userEvent.click(target)\n}\n\n/**\n * Clicks one human-reachable control by role and accessible-name text inside a named region.\n *\n * @param region - The containing region's exact accessible name.\n * @param role - The control's exact ARIA role.\n * @param name - The rendered accessible-name text that identifies the control in that region.\n * @returns A promise resolving after trusted activation completes.\n * @throws When the named control is absent, unreachable, or ambiguous inside the region.\n *\n * @remarks\n * Use this form when repeated short verbs such as `Add`, or a line whose status completes its\n * accessible name, need the same region context a person uses to disambiguate them.\n *\n * @example\n * ```ts\n * await clickAccessibleWithin('Ledger', 'button', 'Monthly income')\n * ```\n */\nexport async function clickAccessibleWithin(\n\tregion: string,\n\trole: string,\n\tname: string,\n): Promise<void> {\n\tconst matches = page\n\t\t.getByRole('region', { name: region, exact: true })\n\t\t.getByRole(role, { name, exact: false, includeHidden: true })\n\t\t.elements()\n\tconst reachable = matches.filter((element) => {\n\t\tif (!(element instanceof HTMLElement)) return false\n\t\tconst rectangle = element.getBoundingClientRect()\n\t\treturn (\n\t\t\telement.isConnected &&\n\t\t\telement.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true }) &&\n\t\t\trectangle.width > 0 &&\n\t\t\trectangle.height > 0 &&\n\t\t\telement.tabIndex >= 0 &&\n\t\t\t!element.matches(':disabled, [aria-disabled=\"true\"]') &&\n\t\t\telement.closest('[inert]') === null\n\t\t)\n\t})\n\tif (reachable.length === 0) {\n\t\tthrow new Error(`Interactive target \"${name}\" is not reachable inside \"${region}\"`)\n\t}\n\tif (reachable.length > 1) {\n\t\tthrow new Error(\n\t\t\t`Interactive target \"${name}\" is ambiguous across ${reachable.length} elements inside \"${region}\"`,\n\t\t)\n\t}\n\tconst [target] = reachable\n\tif (!(target instanceof HTMLElement)) {\n\t\tthrow new Error(`Interactive target \"${name}\" could not be resolved inside \"${region}\"`)\n\t}\n\tawait userEvent.click(target)\n}\n\n/**\n * Opens or closes one native details disclosure by its rendered summary.\n *\n * @param name - The summary text a person reads.\n * @returns A promise resolving after trusted activation completes.\n * @throws When no visible, focus-reachable native summary has that rendered name, or several do.\n *\n * @remarks\n * Chromium exposes `<summary>` as a native disclosure rather than through an ARIA role accepted by\n * `getByRole`, so this resolver names the platform element and its rendered text directly.\n *\n * @example\n * ```ts\n * await clickDisclosure('Advanced')\n * ```\n */\nexport async function clickDisclosure(name: string): Promise<void> {\n\tconst matches = [...document.querySelectorAll('summary')].filter(\n\t\t(element) => element.innerText.replaceAll(/\\s+/g, ' ').trim() === name,\n\t)\n\tconst reachable = matches.filter((element) => {\n\t\tconst rectangle = element.getBoundingClientRect()\n\t\treturn (\n\t\t\telement.isConnected &&\n\t\t\telement.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true }) &&\n\t\t\trectangle.width > 0 &&\n\t\t\trectangle.height > 0 &&\n\t\t\telement.tabIndex >= 0 &&\n\t\t\telement.closest('[inert]') === null\n\t\t)\n\t})\n\tif (reachable.length === 0) {\n\t\tthrow new Error(`Native disclosure \"${name}\" is not visible and focus-reachable`)\n\t}\n\tif (reachable.length > 1) {\n\t\tthrow new Error(`Native disclosure \"${name}\" is ambiguous across ${reachable.length} elements`)\n\t}\n\tconst [target] = reachable\n\tif (target === undefined) throw new Error(`Native disclosure \"${name}\" could not be resolved`)\n\tawait userEvent.click(target)\n}\n\n/**\n * Replaces a named field's value through focus, select-all, deletion, and real keystrokes.\n *\n * @param name - The field's exact accessible name.\n * @param text - The text to type.\n * @returns A promise resolving after every keystroke completes.\n *\n * @example\n * ```ts\n * await typeAccessible('Runs', '3')\n * ```\n */\nexport async function typeAccessible(name: string, text: string): Promise<void> {\n\tawait userEvent.click(resolveRendered(name))\n\tawait userEvent.keyboard('{Control>}a{/Control}{Backspace}')\n\tif (text === '') return\n\tawait userEvent.keyboard(text.replaceAll('{', '{{').replaceAll('[', '[['))\n}\n\n/**\n * Replaces a named field's value in one operation, for text too long to type key by key.\n *\n * @param name - The field's exact accessible name.\n * @param text - The text to place in the field.\n * @returns A promise resolving after the browser commits the value.\n *\n * @remarks\n * The provider drives the real element, so the field publishes the same input event a person's\n * typing publishes. Use {@link typeAccessible} wherever the keystrokes themselves are the subject.\n *\n * @example\n * ```ts\n * await fillAccessible('Payload', '{\"status\":\"ready\"}')\n * ```\n */\nexport async function fillAccessible(name: string, text: string): Promise<void> {\n\tawait userEvent.fill(resolveRendered(name), text)\n}\n\n/**\n * Presses a browser-keyboard sequence using Vitest's installed user-event syntax.\n *\n * @param keys - The keys or key descriptors to press.\n * @returns A promise resolving after the sequence completes.\n *\n * @example\n * ```ts\n * await pressKeys('{ArrowRight}{Enter}')\n * ```\n */\nexport async function pressKeys(keys: string): Promise<void> {\n\tawait userEvent.keyboard(keys)\n}\n\n/**\n * Reaches a named control only through natural forward Tab traversal from the current focus.\n *\n * @param name - The target's exact accessible name.\n * @returns The target after the browser moves focus to it.\n * @throws When one complete traversal cannot reach the target.\n *\n * @example\n * ```ts\n * await traverseAccessible('Evaluate')\n * ```\n */\nexport async function traverseAccessible(name: string): Promise<HTMLElement> {\n\tresolveRendered(name)\n\t// Two facts shape the loop. A Tab pressed before the page has real input focus moves nothing,\n\t// so a step counts only when focus actually lands somewhere; the traversal is over when focus\n\t// revisits an element, because that is one full cycle of the tab order. And the target is\n\t// re-resolved on every step, because a framework may replace the node between resolution and\n\t// focus arrival: the person's target is the role and name, never one node.\n\tconst cap =\n\t\tdocument.querySelectorAll<HTMLElement>('a[href], button, input, select, textarea, [tabindex]')\n\t\t\t.length *\n\t\t\t3 +\n\t\t10\n\tconst visited = new Set<Element>()\n\tconst trail: string[] = []\n\tfor (let attempt = 0; attempt < cap; attempt += 1) {\n\t\tawait userEvent.tab()\n\t\tconst focused = document.activeElement\n\t\tif (!(focused instanceof HTMLElement) || focused === document.body) continue\n\t\tlet current: HTMLElement | undefined\n\t\ttry {\n\t\t\tcurrent = resolveRendered(name)\n\t\t} catch {\n\t\t\tcontinue\n\t\t}\n\t\tif (focused === current) return current\n\t\tif (visited.has(focused)) break\n\t\tvisited.add(focused)\n\t\ttrail.push(`${focused.tagName}:${focused.innerText.slice(0, 20)}`)\n\t}\n\tthrow new Error(\n\t\t`Interactive target \"${name}\" is not reachable through forward Tab traversal: ${trail.join(' > ')}`,\n\t)\n}\n\n/**\n * Reads the normalized visible text of one named region, dialog, table, tab panel, or alert.\n *\n * @param name - The region's exact accessible name.\n * @returns The text a screen reader can perceive in the visible region, including descendant\n * visually-hidden content.\n * @throws When the named region is absent, hidden, or ambiguous.\n *\n * @example\n * ```ts\n * readPerception('Run')\n * ```\n */\nexport function readPerception(name: string): string {\n\tconst matches: HTMLElement[] = []\n\tfor (const role of ['alert', 'alertdialog', 'dialog', 'region', 'status', 'table', 'tabpanel']) {\n\t\tfor (const element of page\n\t\t\t.getByRole(role, { name, exact: true, includeHidden: true })\n\t\t\t.elements()) {\n\t\t\tif (element instanceof HTMLElement && !matches.includes(element)) matches.push(element)\n\t\t}\n\t}\n\tconst visible = matches.filter((element) => {\n\t\tconst rectangle = element.getBoundingClientRect()\n\t\treturn (\n\t\t\telement.isConnected &&\n\t\t\telement.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true }) &&\n\t\t\trectangle.width > 0 &&\n\t\t\trectangle.height > 0\n\t\t)\n\t})\n\tif (visible.length === 0) throw new Error(`Named region \"${name}\" is not visible`)\n\tif (visible.length > 1) {\n\t\tthrow new Error(`Named region \"${name}\" is ambiguous across ${visible.length} elements`)\n\t}\n\tconst [region] = visible\n\tif (region === undefined) throw new Error(`Named region \"${name}\" could not be resolved`)\n\treturn region.innerText.replaceAll(/\\s+/g, ' ').trim()\n}\n\n/**\n * Reads the normalized visible text of the whole page.\n *\n * @returns Every rendered word in the document body, its whitespace runs collapsed and trimmed.\n *\n * @remarks\n * This is the reader for a sentence that spans two regions and for a vocabulary sweep over the\n * words an interface uses. Reach for {@link readPerception} wherever one named region is the\n * subject, because that one throws when the region is missing and this one returns whatever is\n * there.\n *\n * @example\n * ```ts\n * readPage().includes('No cases yet')\n * ```\n */\nexport function readPage(): string {\n\treturn document.body.innerText.replaceAll(/\\s+/g, ' ').trim()\n}\n\n/**\n * Reads the rendered text of the element that currently holds focus.\n *\n * @returns The focused HTML element's trimmed rendered text, including an empty string, or\n * `undefined` when focus rests on a non-HTML element. When nothing holds focus, the browser\n * reports the document body as active, so the whole page's rendered text returns.\n *\n * @example\n * ```ts\n * await traverseAccessible('Evaluate')\n * readFocus() // 'Evaluate'\n * ```\n */\nexport function readFocus(): string | undefined {\n\tconst focused = document.activeElement\n\treturn focused instanceof HTMLElement ? focused.innerText.trim() : undefined\n}\n\n/**\n * Reads the value a resolved control renders.\n *\n * @param role - The control's exact ARIA role.\n * @param name - The control's exact accessible name.\n * @returns The control's current value.\n * @throws When the target does not resolve, or resolves to an element that carries no value.\n *\n * @remarks\n * A control's value is a rendered fact a person can read, not internal state, so it is read from\n * the resolved element rather than from the component that produced it.\n *\n * @example\n * ```ts\n * readValue('spinbutton', 'Runs') // '3'\n * ```\n */\nexport function readValue(role: string, name: string): string {\n\tconst control = resolveAccessible(role, name)\n\tif (\n\t\t!(control instanceof HTMLInputElement) &&\n\t\t!(control instanceof HTMLTextAreaElement) &&\n\t\t!(control instanceof HTMLSelectElement)\n\t) {\n\t\tthrow new Error(`Interactive target \"${name}\" does not carry a value`)\n\t}\n\treturn control.value\n}\n\n/**\n * Waits for one animation frame to settle pending browser paint work.\n *\n * @returns A promise resolving after one `requestAnimationFrame`.\n *\n * @example\n * ```ts\n * await waitForFrame()\n * ```\n */\nexport function waitForFrame(): Promise<void> {\n\treturn new Promise<void>((resolve) => requestAnimationFrame(() => resolve()))\n}\n\n/**\n * Renders trusted fixture markup into a container attached to the document.\n *\n * @param markup - The fixture markup to render.\n * @returns The attached container.\n *\n * @example\n * ```ts\n * const container = render('<button type=\"button\">Save</button>')\n * container.remove()\n * ```\n */\nexport function render(markup: string): HTMLDivElement {\n\tconst container = document.createElement('div')\n\tcontainer.innerHTML = markup\n\tdocument.body.append(container)\n\treturn container\n}\n\n/**\n * Measures the WCAG 2.x contrast ratio between an element's computed text and background colors.\n *\n * @param element - The element whose rendered text contrast to measure.\n * @returns The relative-luminance contrast ratio.\n * @throws When the browser does not expose parseable computed colors.\n *\n * @remarks\n * A transparent or translucent background resolves through the element's ancestors: every painted\n * layer from the element up to the first opaque one composites top-over-bottom onto that opaque\n * base, so a 3% surface tint reads as a tint over what shows through it rather than as a\n * full-strength paint. A translucent foreground then resolves against that effective background\n * before luminance is measured.\n *\n * Every element from the target upwards must be reachable, and at least one of them must paint:\n * the measurement throws rather than assuming a white canvas when nothing in the chain declares a\n * background color. The element itself must expose a computed foreground color — a detached\n * element exposes none, and the measurement throws rather than guessing one.\n *\n * @example\n * ```ts\n * const container = render('<p style=\"background: #000; color: #fff\">Ready</p>')\n * contrast(requireValue(container.firstElementChild)) // 21\n * ```\n */\nexport function contrast(element: Element): number {\n\tconst foreground = getComputedStyle(element).color.match(/\\d+(?:\\.\\d+)?/g)\n\tif (foreground === null || foreground.length < 3) {\n\t\tthrow new Error('Computed foreground color is unavailable')\n\t}\n\tconst layers: number[][] = []\n\tlet current: Element | null = element\n\tlet opaque = false\n\twhile (current !== null) {\n\t\tconst channels = getComputedStyle(current).backgroundColor.match(/\\d+(?:\\.\\d+)?/g)\n\t\tif (channels !== null && channels.length >= 3) {\n\t\t\tconst layerAlpha = channels[3] === undefined ? 1 : Number(channels[3])\n\t\t\tif (layerAlpha > 0) {\n\t\t\t\tlayers.push([...channels.slice(0, 3).map(Number), layerAlpha])\n\t\t\t}\n\t\t\tif (layerAlpha >= 1) {\n\t\t\t\topaque = true\n\t\t\t\tbreak\n\t\t\t}\n\t\t}\n\t\tcurrent = current.parentElement\n\t}\n\tif (layers.length === 0) throw new Error('Computed background color is unavailable')\n\tconst base = layers[layers.length - 1]\n\tif (base === undefined) throw new Error('Computed background color is unavailable')\n\tlet composed = base.slice(0, 3).map((channel) => channel / 255)\n\tif (!opaque) composed = [1, 1, 1]\n\tconst start = opaque ? layers.length - 2 : layers.length - 1\n\tfor (let index = start; index >= 0; index -= 1) {\n\t\tconst layer = layers[index]\n\t\tif (layer === undefined) continue\n\t\tconst layerAlpha = layer[3] ?? 1\n\t\tcomposed = composed.map((channel, position) => {\n\t\t\tconst top = (layer[position] ?? 0) / 255\n\t\t\treturn top * layerAlpha + channel * (1 - layerAlpha)\n\t\t})\n\t}\n\n\tconst alpha = foreground[3] === undefined ? 1 : Number(foreground[3])\n\tconst backgroundChannels = composed\n\tconst foregroundChannels = foreground.slice(0, 3).map((channel, index) => {\n\t\tconst behind = backgroundChannels[index]\n\t\tif (behind === undefined) throw new Error('Computed background channel is unavailable')\n\t\treturn (Number(channel) / 255) * alpha + behind * (1 - alpha)\n\t})\n\tconst foregroundLinear = foregroundChannels.map((channel) =>\n\t\tchannel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4,\n\t)\n\tconst backgroundLinear = backgroundChannels.map((channel) =>\n\t\tchannel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4,\n\t)\n\tconst foregroundLuminance =\n\t\t0.2126 * (foregroundLinear[0] ?? 0) +\n\t\t0.7152 * (foregroundLinear[1] ?? 0) +\n\t\t0.0722 * (foregroundLinear[2] ?? 0)\n\tconst backgroundLuminance =\n\t\t0.2126 * (backgroundLinear[0] ?? 0) +\n\t\t0.7152 * (backgroundLinear[1] ?? 0) +\n\t\t0.0722 * (backgroundLinear[2] ?? 0)\n\tconst lighter = Math.max(foregroundLuminance, backgroundLuminance)\n\tconst darker = Math.min(foregroundLuminance, backgroundLuminance)\n\treturn (lighter + 0.05) / (darker + 0.05)\n}\n\n/**\n * Collects every class token the stylesheets loaded into this document actually define.\n *\n * @returns The set of class names reachable in the shipped cascade.\n *\n * @remarks\n * The set is what an authored-class conformance check measures against, so a class no loaded\n * stylesheet defines — an invented utility, a misspelled framework name — is absent from it.\n *\n * @example\n * ```ts\n * readCascade().has('card')\n * ```\n */\nexport function readCascade(): ReadonlySet<string> {\n\tconst known = new Set<string>()\n\tconst rules: CSSRule[] = []\n\tfor (const sheet of document.styleSheets) rules.push(...sheet.cssRules)\n\twhile (rules.length > 0) {\n\t\tconst rule = rules.pop()\n\t\tif (rule instanceof CSSGroupingRule) rules.push(...rule.cssRules)\n\t\tif (!(rule instanceof CSSStyleRule)) continue\n\t\tfor (const match of rule.selectorText.matchAll(/\\.([a-zA-Z][\\w-]*)/g)) {\n\t\t\tknown.add(String(match[1]))\n\t\t}\n\t}\n\treturn known\n}\n\n/**\n * Reads the normalized visible text of every element a selector matches, in document order.\n *\n * @param root - The subtree to search.\n * @param selector - The CSS selector naming the rows.\n * @returns One line per matched element, its text runs collapsed and single-space joined.\n *\n * @remarks\n * The line is built from the row's text nodes rather than from `textContent`, because adjacent\n * inline elements carry no whitespace between them in compiled template output and would otherwise\n * read as one run-together word.\n *\n * @example\n * ```ts\n * readRows(container, 'li')\n * ```\n */\nexport function readRows(root: ParentNode, selector: string): readonly string[] {\n\tconst rows: string[] = []\n\tfor (const row of root.querySelectorAll(selector)) {\n\t\tconst parts: string[] = []\n\t\tconst walker = document.createTreeWalker(row, NodeFilter.SHOW_TEXT)\n\t\twhile (walker.nextNode() !== null) {\n\t\t\tconst text = (walker.currentNode.textContent ?? '').replaceAll(/\\s+/g, ' ').trim()\n\t\t\tif (text !== '') parts.push(text)\n\t\t}\n\t\trows.push(parts.join(' '))\n\t}\n\treturn rows\n}\n\n/**\n * Reads one resolved CSS property from a real browser element.\n *\n * @param element - The element whose resolved style to inspect.\n * @param property - The CSS property name.\n * @returns The browser's resolved property value.\n *\n * @example\n * ```ts\n * style(button, 'padding-left')\n * ```\n */\nexport function style(element: Element, property: string): string {\n\treturn getComputedStyle(element).getPropertyValue(property)\n}\n\n/**\n * Expands a capture registry across every variant into the filenames a complete portfolio holds.\n *\n * @param states - The registered state names.\n * @param variants - The variants the portfolio is rendered in.\n * @returns One `<state>--<variant>.png` name per pair, each state's variants together, in registry\n * order.\n *\n * @remarks\n * The expansion is the portfolio's own definition of complete, so a duplicate in it is a registry\n * defect a proof reads directly rather than a collision discovered on disk.\n *\n * @example\n * ```ts\n * expandCaptures(['start'], [{ name: 'dark-390', width: 390, height: 844 }])\n * // ['start--dark-390.png']\n * ```\n */\nexport function expandCaptures(\n\tstates: readonly string[],\n\tvariants: readonly CaptureVariant[],\n): readonly string[] {\n\tconst files: string[] = []\n\tfor (const state of states) {\n\t\tfor (const variant of variants) files.push(`${state}--${variant.name}.png`)\n\t}\n\treturn files\n}\n","import type { PortfolioInterface, PortfolioOptions } from './types.js'\nimport { page } from 'vitest/browser'\nimport { expandCaptures } from './helpers.js'\n\n/**\n * Creates the capture portfolio one run places its screenshots through.\n *\n * @param options - The state registry, the variant matrix, the variant this run renders, the\n * directory it writes into, and whether it writes at all.\n * @returns The portfolio: its registry expansion, what it has placed, and `place`.\n * @throws When no registered variant carries the name `variant` names.\n *\n * @remarks\n * A disabled portfolio is the ordinary run. `place` then resizes nothing, writes nothing, and\n * records nothing, so a journey calls it unconditionally and a suite with the flag unset pays for\n * none of it. The portfolio refuses an unregistered variant at creation. An enabled run refuses an\n * unregistered state name and a second placement of one state.\n *\n * @example\n * ```ts\n * const portfolio = createPortfolio({\n * \tstates: ['start-empty'],\n * \tvariants: [{ name: 'dark-390', width: 390, height: 844 }],\n * \tvariant: 'dark-390',\n * \tdirectory: '../../tmp/capture/states',\n * })\n * await portfolio.place('start-empty')\n * ```\n */\nexport function createPortfolio(options: PortfolioOptions): PortfolioInterface {\n\tconst selected = options.variants.find((candidate) => candidate.name === options.variant)\n\tif (selected === undefined) {\n\t\tthrow new Error(`Capture variant \"${options.variant}\" is not registered`)\n\t}\n\tconst registry = [...options.states]\n\tconst files = expandCaptures(registry, options.variants)\n\tconst enabled = options.enabled ?? false\n\tconst placed: string[] = []\n\tconst paths: string[] = []\n\treturn {\n\t\tvariant: options.variant,\n\t\tfiles,\n\t\tget states() {\n\t\t\treturn [...placed]\n\t\t},\n\t\tget paths() {\n\t\t\treturn [...paths]\n\t\t},\n\t\tasync place(state) {\n\t\t\tif (!enabled) return undefined\n\t\t\tif (!registry.includes(state)) {\n\t\t\t\tthrow new Error(`Capture state \"${state}\" is not registered`)\n\t\t\t}\n\t\t\tif (placed.includes(state)) {\n\t\t\t\tthrow new Error(`Capture state \"${state}\" is already placed`)\n\t\t\t}\n\t\t\tconst file = `${state}--${options.variant}.png`\n\t\t\tselected.apply?.()\n\t\t\tif (window.innerWidth !== selected.width || window.innerHeight !== selected.height) {\n\t\t\t\tawait page.viewport(selected.width, selected.height)\n\t\t\t}\n\t\t\tconst written = await page.screenshot({ path: `${options.directory}/${file}` })\n\t\t\tplaced.push(state)\n\t\t\tpaths.push(written)\n\t\t\treturn written\n\t\t},\n\t}\n}\n"],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@orkestrel/test",
-	"version": "0.0.5",
-	"description": "The test helpers the Orkestrel fleet repeats — a call recorder, a real delay, JSON and async collectors, and an owned scratch directory with a source-file walker. Zero runtime dependencies. Part of the @orkestrel line.",
+	"version": "0.0.6",
+	"description": "The test helpers the Orkestrel fleet repeats — a call recorder, a real delay, JSON and async collectors, an owned scratch directory with a source-file walker, and a browser journey layer that drives real interfaces by role and accessible name. Zero runtime dependencies. Part of the @orkestrel line.",
 	"keywords": [],
 	"homepage": "https://github.com/orkestrel/test#readme",
 	"bugs": "https://github.com/orkestrel/test/issues",
@@ -29,6 +29,12 @@
 				"default": "./dist/src/core/index.cjs"
 			}
 		},
+		"./browser": {
+			"import": {
+				"types": "./dist/src/browser/index.d.ts",
+				"default": "./dist/src/browser/index.js"
+			}
+		},
 		"./server": {
 			"import": {
 				"types": "./dist/src/server/index.d.ts",
@@ -52,35 +58,43 @@
 		"lint": "oxlint --config .oxlintrc.json --fix .",
 		"lint:check": "oxlint --config .oxlintrc.json --deny-warnings .",
 		"check": "tsc --noEmit --project tsconfig.json && npm run check:src",
-		"check:src": "npm run check:src:core && npm run check:src:server",
+		"check:src": "npm run check:src:core && npm run check:src:browser && npm run check:src:server",
 		"check:src:core": "tsc --noEmit -p configs/src/tsconfig.core.json",
+		"check:src:browser": "tsc --noEmit -p configs/src/tsconfig.browser.json",
 		"check:src:server": "tsc --noEmit -p configs/src/tsconfig.server.json",
 		"test": "npm run test:src && npm run test:policy && npm run test:config && npm run test:guides",
-		"test:src": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:core --project src:server",
+		"test:src": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:core --project src:browser --project src:server",
 		"test:src:core": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:core",
+		"test:src:browser": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:browser",
 		"test:src:server": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:server",
 		"test:policy": "vitest run --config vite.config.ts --no-cache --reporter=dot --project policy",
 		"test:config": "vitest run --config vite.config.ts --no-cache --reporter=dot --project config",
 		"test:guides": "vitest run --config vite.config.ts --no-cache --reporter=dot --project guides",
 		"test:probe": "vitest run --config vite.config.ts --no-cache --reporter=verbose --project probe",
 		"build": "npm run clean && npm run build:src",
-		"build:src": "npm run build:src:core && npm run build:src:server",
+		"build:src": "npm run build:src:core && npm run build:src:browser && npm run build:src:server",
 		"build:src:core": "vite build --config configs/src/vite.core.config.ts && npm run copy dist/src/core/index.d.ts dist/src/core/index.d.cts",
+		"build:src:browser": "vite build --config configs/src/vite.browser.config.ts",
 		"build:src:server": "vite build --config configs/src/vite.server.config.ts && npm run copy dist/src/server/index.d.ts dist/src/server/index.d.cts",
 		"prepublishOnly": "npm run format:check && npm run lint:check && npm run check && npm run build && npm test"
 	},
 	"devDependencies": {
 		"@microsoft/api-extractor": "^7.58.12",
-		"@orkestrel/guide": "^0.0.10",
-		"@orkestrel/scaffold": "^0.0.30",
+		"@orkestrel/guide": "^0.0.11",
+		"@orkestrel/scaffold": "^0.0.38",
 		"@types/node": "^26.2.0",
+		"@vitest/browser-playwright": "^4.1.10",
 		"oxfmt": "^0.62.0",
 		"oxlint": "^1.77.0",
+		"playwright": "^1.62.1",
 		"typescript": "^6.0.3",
 		"vite": "~8.2.0",
 		"vite-plugin-dts": "^5.0.3",
 		"vitest": "^4.1.10"
 	},
+	"peerDependencies": {
+		"vitest": "^4.1.10"
+	},
 	"engines": {
 		"node": ">=22.12.0"
 	}