@jterrazz/test 15.1.1 → 15.3.0

package/dist/browser/index.js

@@ -0,0 +1,2796 @@
+import { TestRunner, expect, inject, onTestFinished, vi } from "vitest";
+import { commands, page, userEvent } from "vitest/browser";
+import { mock, mockDeep } from "vitest-mock-extended";
+import MockDatePackage from "mockdate";
+//#region src/specification/contracts/contract.ts
+/**
+* Declare one contract. Identity function — its value is the enforced shape
+* and the naming convention:
+*
+* @example
+*   // specs/api/reports/contracts/openai/classify-article.ts
+*   import { defineContract, openai } from '@jterrazz/test';
+*
+*   export default defineContract({
+*       request: openai.responses({ user: PROMPT, tools: ['classify'] }),
+*       response: openai.reply({ categories: ['TECH'] }),
+*   });
+*
+*   // Dynamic — the response is computed from the observed request:
+*   export default defineContract({
+*       request: http.post('https://api.example.com/echo'),
+*       response: (request) => http.json({ received: request.body }),
+*   });
+*/
+function defineContract(contract) {
+	return contract;
+}
+/** Is this a {@link Contracts} composite (rather than a contract or a list)? */
+function isContracts(value) {
+	return typeof value === "object" && value !== null && Array.isArray(value.contracts) && typeof value.with === "function";
+}
+/** Is this a single {@link Contract} (rather than a bare request half)? */
+function isContract(value) {
+	return typeof value === "object" && value !== null && "request" in value && "response" in value;
+}
+/**
+* The route a contract claims — method + the DECLARED url source. Two
+* contracts share a route when they would be written on the same line of a
+* declaration: same method, same url pattern (`.source` for a RegExp).
+*/
+function routeKeyOf(contract) {
+	const { method, url } = contract.request;
+	return url instanceof RegExp ? `${method} re:${url.source}` : `${method} str:${url}`;
+}
+/** Human-readable route of a contract — used in every failure message. */
+function describeRoute(contract) {
+	const { method, url } = contract.request;
+	return `${method === "*" ? "ANY" : method} ${url instanceof RegExp ? String(url) : url}`;
+}
+/** Flatten contracts, lists, and composites into one ordered list. */
+function flatten(items) {
+	const flat = [];
+	for (const item of items) if (Array.isArray(item)) flat.push(...flatten(item));
+	else if (isContracts(item)) flat.push(...item.contracts);
+	else flat.push(item);
+	return flat;
+}
+/**
+* Compose contracts into the artifact a test imports — it's contracts all the
+* way down: a composite may extend contracts, lists, and other composites,
+* recursively, order preserved.
+*
+* `.with(...)` derives a scenario: contracts whose route the overrides claim
+* are removed from the base, and the overrides are prepended. Under
+* first-match selection a more specific override (`/articles/gone-1`) also
+* wins over a generic base route (`/articles/{{uuid}}`) it does not replace.
+*
+* @example
+*   // contracts/newsroom.contracts.ts
+*   export default defineContracts(events, articleById);
+*   export const withArticleGone = (id: string) =>
+*       newsroom.with(articleGone(id));
+*/
+function defineContracts(...items) {
+	const contracts = Object.freeze(flatten(items));
+	return {
+		contracts,
+		with(...overrides) {
+			const added = flatten(overrides);
+			const claimed = new Set(added.map(routeKeyOf));
+			const kept = contracts.filter((contract) => !claimed.has(routeKeyOf(contract)));
+			return defineContracts([...added, ...kept]);
+		}
+	};
+}
+/** Normalize any accepted input into a flat contract list. */
+function contractsOf(input) {
+	return flatten([input]);
+}
+//#endregion
+//#region src/integrations/msw/scope.ts
+/**
+* The network double in MODULE scope — the same contracts, the same queue and
+* the same strictness as a chain's `.intercept()`, for the one kind of test
+* that has no chain to hang them on.
+*
+* A module test whose subject reaches the network had exactly two ways out
+* before this: `vi.stubGlobal('fetch')`, which replaces the platform with a
+* hand-written stand-in, or `msw/node` imported directly, which F6 refuses a
+* test and F8 refuses a consumer to declare. Both answer "what did the outside
+* world reply" in a dialect nothing else in the repository speaks.
+*
+* The scope is an `AsyncDisposable`, so the handlers come off at the end of
+* the block however the block ends — and the strict violation (an outgoing
+* request no contract accepted) is raised THERE, which is what makes the
+* double a guard rather than a convenience.
+*/
+/**
+* The contracts a call declared, whichever of the two forms it used. Exported
+* for its own module test: the bare-request refusal is a runtime guard the
+* compiler already states, so no typed call site can reach it.
+*
+* @internal
+*/
+function declared(requestOrContracts, maybeResponse) {
+	if (Array.isArray(requestOrContracts) || isContracts(requestOrContracts) || isContract(requestOrContracts)) return contractsOf(requestOrContracts);
+	if (maybeResponse === void 0) throw new Error("intercept(): a bare request needs its response — pass a contract (defineContract({ request, response })) or the inline pair intercept(request, response).");
+	return [{
+		request: requestOrContracts,
+		response: maybeResponse
+	}];
+}
+/**
+* Build the module-scope double on one engine. The node entry hands it msw's
+* server, the page's entry hands it msw's worker: one shape, two transports,
+* exactly as a chain's `.intercept()` already has it.
+*
+* @internal
+*/
+function interceptThrough(register) {
+	async function intercept(requestOrContracts, maybeResponse) {
+		const contracts = declared(requestOrContracts, maybeResponse);
+		if (contracts.length === 0) throw new Error("intercept(): declare at least one contract — an empty list guards nothing, and a subject with no network needs no intercept at all.");
+		const registration = await register(contracts);
+		return { [Symbol.asyncDispose]: async () => {
+			const violation = registration.violation();
+			registration.cleanup();
+			await Promise.resolve();
+			if (violation) throw violation;
+		} };
+	}
+	return intercept;
+}
+//#endregion
+//#region src/specification/matching/match.ts
+/** Every kind usable as a `{{token}}` in fixture files (all but ref/regex/includes). */
+const TOKEN_KINDS = [
+	"any",
+	"base64",
+	"date",
+	"duration",
+	"email",
+	"float",
+	"hex",
+	"int",
+	"ip",
+	"iso8601",
+	"number",
+	"path",
+	"port",
+	"semver",
+	"sha",
+	"string",
+	"time",
+	"ulid",
+	"url",
+	"uuid",
+	"workdir"
+];
+/**
+* A dynamic-value matcher. Created via the {@link match} factories — never
+* constructed directly by user code.
+*/
+var Matcher = class {
+	/** For kind 'includes': the substring the actual value must contain. */
+	includes;
+	kind;
+	/** For kind 'ref': the capture to assert inequality against. */
+	notRef;
+	/** For kind 'ref': the capture name. */
+	refName;
+	/** For kind 'regex': the pattern the actual value must match. */
+	regex;
+	constructor(kind, options = {}) {
+		this.includes = options.includes;
+		this.kind = kind;
+		this.notRef = options.notRef;
+		this.refName = options.refName;
+		this.regex = options.regex;
+	}
+	/** Placeholder-style rendering used in failure diffs and serialization. */
+	toString() {
+		switch (this.kind) {
+			case "includes": return `{{includes:${this.includes}}}`;
+			case "ref": return this.notRef ? `{{ref#${this.refName}!${this.notRef}}}` : `{{ref#${this.refName}}}`;
+			case "regex": return `{{regex:${this.regex?.source}}}`;
+			default: return this.refName ? `{{${this.kind}#${this.refName}}}` : `{{${this.kind}}}`;
+		}
+	}
+	toJSON() {
+		return this.toString();
+	}
+};
+const typed = (kind) => () => new Matcher(kind);
+const match = {
+	/** Matches anything. */
+	any: typed("any"),
+	/** Matches a base64 string. */
+	base64: typed("base64"),
+	/** Matches a calendar date (`YYYY-MM-DD`). */
+	date: typed("date"),
+	/** Matches a human duration (`12ms`, `1.5s`, `2m`, `3h`). */
+	duration: typed("duration"),
+	/** Matches an email address. */
+	email: typed("email"),
+	/**
+	* Matches a float. In JSON contexts any finite number passes (JSON does
+	* not distinguish `42` from `42.0`); in text contexts the decimal part
+	* is required (`4.2`, never `42`).
+	*/
+	float: typed("float"),
+	/** Matches a hexadecimal string. */
+	hex: typed("hex"),
+	/**
+	* Matches a string CONTAINING the given substring. Code-only, like
+	* {@link match.regex} — the `{{token}}` fixture vocabulary does not grow.
+	* The explicit escape hatch now that contract string filters
+	* (`openai.chat({ user })`) mean exact equality.
+	*/
+	includes: (substring) => new Matcher("includes", { includes: substring }),
+	/** Matches an integer (or an integer string in text contexts). */
+	int: typed("int"),
+	/** Matches an IPv4 address. */
+	ip: typed("ip"),
+	/** Matches an ISO-8601 timestamp string. */
+	iso8601: typed("iso8601"),
+	/** Matches a number (or a numeric string in text contexts). */
+	number: typed("number"),
+	/** Matches a filesystem path (`/...` or `./...`). */
+	path: typed("path"),
+	/** Matches a TCP/UDP port number (0-65535). */
+	port: typed("port"),
+	/**
+	* Capture-and-compare. The first occurrence of `ref(name)` captures the
+	* actual value; every later occurrence must strictly equal the capture.
+	* `{ not: other }` additionally asserts inequality with the capture named
+	* `other`. Scope: the current spec execution (reset per chain).
+	*/
+	ref: (name, options) => new Matcher("ref", {
+		notRef: options?.not,
+		refName: name
+	}),
+	/** Matches a string against the given regular expression. */
+	regex: (regex) => new Matcher("regex", { regex }),
+	/** Matches a semantic version (`1.2.3`, `2.0.0-rc.1`). */
+	semver: typed("semver"),
+	/** Matches a git SHA (7-64 hex chars). */
+	sha: typed("sha"),
+	/** Matches any string. */
+	string: typed("string"),
+	/** Matches a wall-clock time (`HH:MM` or `HH:MM:SS`). */
+	time: typed("time"),
+	/** Matches a ULID. */
+	ulid: typed("ulid"),
+	/** Matches an http(s) URL. */
+	url: typed("url"),
+	/** Matches a UUID string. */
+	uuid: typed("uuid"),
+	/** Matches the exact working directory of the current spec. */
+	workdir: typed("workdir")
+};
+/**
+* Named captures recorded by `match.ref()` / `{{type#ref}}` placeholders.
+* One scope lives on each spec result — every assertion chained off the same
+* result shares it, and a new chain starts fresh.
+*/
+var CaptureScope = class {
+	values = /* @__PURE__ */ new Map();
+	/**
+	* The exact working directory of the current spec, when the framework
+	* knows it (cli mode). Drives the `{{workdir}}` token / `match.workdir()`.
+	*/
+	workdir;
+	constructor(workdir) {
+		this.workdir = workdir;
+	}
+	get(name) {
+		return this.values.get(name);
+	}
+	has(name) {
+		return this.values.has(name);
+	}
+	set(name, value) {
+		this.values.set(name, value);
+	}
+};
+//#endregion
+//#region src/specification/matching/structural.ts
+/**
+* Structural comparison engine shared by every fixture matcher.
+*
+* Handles three kinds of "expected" values:
+* - plain JSON values → strict deep equality
+* - {@link Matcher} instances (code-side `match.*`)
+* - strings containing `{{placeholder}}` forms (file-side fixtures)
+*
+* One unified `{{token}}` grammar (CONVENTIONS D4) — the same vocabulary
+* works in `_expected/*.http` (body and headers), `_expected/*.json`, and
+* text snapshots (`_expected/*.txt`).
+*
+* Ref captures (`match.ref(name)` / `{{type#name}}`) are recorded in the
+* {@link CaptureScope} supplied by the caller.
+*/
+const UUID_SOURCE = "[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}";
+const ULID_SOURCE = "[0-9A-HJKMNP-TV-Z]{26}";
+const ISO8601_SOURCE = String.raw`\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})`;
+const DATE_SOURCE = String.raw`\d{4}-\d{2}-\d{2}`;
+const TIME_SOURCE = String.raw`\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?`;
+const DURATION_SOURCE = String.raw`\d+(?:\.\d+)?(?:ms|s|m|h)`;
+const NUMBER_SOURCE = String.raw`-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?`;
+const INT_SOURCE = String.raw`-?\d+`;
+const FLOAT_SOURCE = String.raw`-?\d+\.\d+`;
+const SEMVER_SOURCE = String.raw`\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?`;
+const SHA_SOURCE = "[0-9a-f]{7,64}";
+const HEX_SOURCE = "[0-9a-fA-F]+";
+const BASE64_SOURCE = "[A-Za-z0-9+/]+={0,2}";
+const PORT_SOURCE = String.raw`(?:6553[0-5]|655[0-2]\d|65[0-4]\d{2}|6[0-4]\d{3}|[1-5]\d{4}|\d{1,4})`;
+const IP_OCTET = String.raw`(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)`;
+const IP_SOURCE = String.raw`(?:${IP_OCTET}\.){3}${IP_OCTET}`;
+const URL_SOURCE = String.raw`https?:\/\/[^\s"'<>]+`;
+const EMBEDDED_SOURCES = {
+	base64: BASE64_SOURCE,
+	date: DATE_SOURCE,
+	duration: DURATION_SOURCE,
+	email: String.raw`[^\s@"'<>]+@[^\s@"'<>]+\.[^\s@"'<>]+`,
+	float: FLOAT_SOURCE,
+	hex: HEX_SOURCE,
+	int: INT_SOURCE,
+	ip: IP_SOURCE,
+	iso8601: ISO8601_SOURCE,
+	number: NUMBER_SOURCE,
+	path: String.raw`\.{0,2}\/[^\s"'<>]*`,
+	port: PORT_SOURCE,
+	semver: SEMVER_SOURCE,
+	sha: SHA_SOURCE,
+	time: TIME_SOURCE,
+	ulid: ULID_SOURCE,
+	url: URL_SOURCE,
+	uuid: UUID_SOURCE
+};
+const wholeRe = (source) => new RegExp(`^(?:${source})$`, "u");
+const WHOLE_RES = Object.fromEntries(Object.entries(EMBEDDED_SOURCES).map(([kind, source]) => [kind, wholeRe(source)]));
+const PLACEHOLDER_RE = new RegExp(String.raw`\{\{(?<kind>${[...TOKEN_KINDS].sort((a, b) => b.length - a.length).join("|")})(?:#(?<ref>[\w.-]+))?\}\}`, "gu");
+/** Whether a fixture string contains at least one `{{placeholder}}`. */
+function hasPlaceholders(value) {
+	PLACEHOLDER_RE.lastIndex = 0;
+	return PLACEHOLDER_RE.test(value);
+}
+/** Key-order-independent stringification for captured-object comparison. */
+function stableStringify(value) {
+	if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+	if (value !== null && typeof value === "object") return `{${Object.entries(value).sort(([a], [b]) => a < b ? -1 : 1).map(([key, item]) => `${JSON.stringify(key)}:${stableStringify(item)}`).join(",")}}`;
+	return JSON.stringify(value) ?? "undefined";
+}
+function capturedEquals(a, b) {
+	if (Object.is(a, b)) return true;
+	if (typeof a === "number" && typeof b === "string" || typeof a === "string" && typeof b === "number") return String(a) === String(b);
+	if (a !== null && b !== null && typeof a === "object" && typeof b === "object") return stableStringify(a) === stableStringify(b);
+	return false;
+}
+function recordRef(name, actual, scope) {
+	if (scope.has(name)) return capturedEquals(scope.get(name), actual);
+	scope.set(name, actual);
+	return true;
+}
+function isPortValue(value) {
+	return Number.isInteger(value) && value >= 0 && value <= 65535;
+}
+function kindMatches(kind, actual, scope) {
+	switch (kind) {
+		case "any": return true;
+		case "float":
+			if (typeof actual === "number") return Number.isFinite(actual);
+			return typeof actual === "string" && WHOLE_RES.float.test(actual);
+		case "int":
+			if (typeof actual === "number") return Number.isInteger(actual);
+			return typeof actual === "string" && WHOLE_RES.int.test(actual);
+		case "number":
+			if (typeof actual === "number") return Number.isFinite(actual);
+			return typeof actual === "string" && WHOLE_RES.number.test(actual);
+		case "port":
+			if (typeof actual === "number") return isPortValue(actual);
+			return typeof actual === "string" && WHOLE_RES.port.test(actual) && isPortValue(Number(actual));
+		case "string": return typeof actual === "string";
+		case "workdir": return typeof actual === "string" && scope.workdir !== void 0 ? actual === scope.workdir : false;
+		default: {
+			const re = WHOLE_RES[kind];
+			return re !== void 0 && typeof actual === "string" && re.test(actual);
+		}
+	}
+}
+function matcherMatches(matcher, actual, scope) {
+	if (matcher.kind === "includes") return typeof actual === "string" && actual.includes(matcher.includes);
+	if (matcher.kind === "regex") return typeof actual === "string" && matcher.regex.test(actual);
+	if (matcher.kind === "ref") {
+		if (matcher.notRef && scope.has(matcher.notRef) && capturedEquals(scope.get(matcher.notRef), actual)) return false;
+		return recordRef(matcher.refName, actual, scope);
+	}
+	return kindMatches(matcher.kind, actual, scope);
+}
+function placeholderSource(kind, scope) {
+	if (kind === "workdir") return scope.workdir === void 0 ? "(?!)" : escapeRegExp(scope.workdir);
+	const source = EMBEDDED_SOURCES[kind];
+	if (source) return source;
+	return kind === "any" ? String.raw`[\s\S]*?` : String.raw`[^\n]*?`;
+}
+function escapeRegExp(text) {
+	return text.replaceAll(/[.*+?^${}()|[\]\\]/gu, String.raw`\$&`);
+}
+function parsePlaceholderString(expected, scope) {
+	PLACEHOLDER_RE.lastIndex = 0;
+	const refs = [];
+	let source = "";
+	let lastIndex = 0;
+	let single = null;
+	let count = 0;
+	for (const found of expected.matchAll(PLACEHOLDER_RE)) {
+		const kind = found.groups.kind;
+		const { ref } = found.groups;
+		source += escapeRegExp(expected.slice(lastIndex, found.index));
+		source += `(${placeholderSource(kind, scope)})`;
+		refs.push({
+			index: count,
+			kind,
+			ref
+		});
+		count++;
+		lastIndex = found.index + found[0].length;
+		if (found.index === 0 && found[0].length === expected.length) single = {
+			kind,
+			ref
+		};
+	}
+	source += escapeRegExp(expected.slice(lastIndex));
+	return {
+		pattern: new RegExp(`^${source}$`, "u"),
+		refs,
+		single,
+		source
+	};
+}
+/**
+* Unanchored regex source matching a fixture string — plain text escaped
+* verbatim, each `{{token}}` expanded to its embedded grammar. Used to route
+* declared `.http` intercept paths (`/articles/{{uuid}}`) as URL patterns.
+*/
+function placeholderPatternSource(expected) {
+	return parsePlaceholderString(expected, new CaptureScope()).source;
+}
+function placeholderStringMatches(expected, actual, scope) {
+	const parsed = parsePlaceholderString(expected, scope);
+	if (parsed.single) {
+		if (!kindMatches(parsed.single.kind, actual, scope)) return false;
+		if (parsed.single.ref) return recordRef(parsed.single.ref, actual, scope);
+		return true;
+	}
+	if (typeof actual !== "string" && typeof actual !== "number") return false;
+	const text = String(actual);
+	const found = parsed.pattern.exec(text);
+	if (!found) return false;
+	for (const entry of parsed.refs) {
+		if (!entry.ref) continue;
+		if (!recordRef(entry.ref, found[entry.index + 1], scope)) return false;
+	}
+	return true;
+}
+function isPlainObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+* Deep structural equality with matcher / placeholder support. Ref captures
+* are recorded in `scope` in traversal order (arrays left-to-right, object
+* keys in expected-key order).
+*/
+function structuralEquals(expected, actual, scope) {
+	if (expected instanceof Matcher) return matcherMatches(expected, actual, scope);
+	if (typeof expected === "string" && hasPlaceholders(expected)) return placeholderStringMatches(expected, actual, scope);
+	if (Array.isArray(expected)) {
+		if (!Array.isArray(actual) || actual.length !== expected.length) return false;
+		return expected.every((item, i) => structuralEquals(item, actual[i], scope));
+	}
+	if (isPlainObject(expected)) {
+		if (!isPlainObject(actual)) return false;
+		const expectedKeys = Object.keys(expected);
+		const actualKeys = Object.keys(actual);
+		if (expectedKeys.length !== actualKeys.length) return false;
+		return expectedKeys.every((key) => key in actual && structuralEquals(expected[key], actual[key], scope));
+	}
+	return Object.is(expected, actual);
+}
+/**
+* Deep structural SUBSET match (toMatchObject-style) with matcher /
+* placeholder support. Plain objects match when every expected key is present
+* and recursively subset-matches — the actual value may carry extra keys.
+* Arrays require equal length with each element subset-matched. Leaves fall
+* back to {@link structuralEquals} semantics (matchers, placeholders, strict
+* equality). Used by request-body filters on intercept triggers.
+*/
+function structuralSubset(expected, actual, scope) {
+	if (expected instanceof Matcher) return matcherMatches(expected, actual, scope);
+	if (typeof expected === "string" && hasPlaceholders(expected)) return placeholderStringMatches(expected, actual, scope);
+	if (Array.isArray(expected)) {
+		if (!Array.isArray(actual) || actual.length !== expected.length) return false;
+		return expected.every((item, i) => structuralSubset(item, actual[i], scope));
+	}
+	if (isPlainObject(expected)) {
+		if (!isPlainObject(actual)) return false;
+		return Object.keys(expected).every((key) => key in actual && structuralSubset(expected[key], actual[key], scope));
+	}
+	return Object.is(expected, actual);
+}
+/**
+* Multi-line text comparison with `{{token}}` support — used by text
+* snapshots (`_expected/*.txt`). Without placeholders this is strict equality.
+*/
+function textEquals(expected, actual, scope) {
+	if (!hasPlaceholders(expected)) return expected === actual;
+	return placeholderStringMatches(expected, actual, scope);
+}
+//#endregion
+//#region src/specification/contracts/queue.ts
+/**
+* The ONE contract queue — pure, engine-agnostic (no MSW, no node:http).
+* Both engines consume it: the MSW integration on api/jobs chains, and the
+* declared stub backend on website/mobile chains.
+*
+* Selection: the FIRST contract in declaration order that matches the observed
+* request and is not exhausted. A contract with no `times` is unlimited (a
+* re-render or a retry replays it); `times: n` is spent after n serves, so an
+* ordered sequence is written as finite contracts before an unlimited tail:
+* `[error500 ×3, ok]`.
+*
+* Strictness (CONVENTIONS D7): when nothing matches — including "everything
+* that matches is exhausted" — the engine answers 501, records the request,
+* and the chain fails with {@link ContractQueue.unmatchedError}. A chain that
+* declared zero contracts is not guarded at all (unchanged boundary).
+*/
+/** Base used to parse origin-relative observed URLs (`/events?x=1`). */
+const RELATIVE_BASE = "http://contract.invalid";
+/** Split a declared url into its base (origin+path, or path) and query halves.
+* Never through `new URL()`, which would percent-encode `{{token}}` braces. */
+function splitDeclared(url) {
+	const separator = url.indexOf("?");
+	if (separator === -1) return {
+		base: url,
+		query: new URLSearchParams()
+	};
+	return {
+		base: url.slice(0, separator),
+		query: new URLSearchParams(url.slice(separator + 1))
+	};
+}
+/** Decode percent-escapes, falling back to the raw text on malformed input. */
+function safeDecode(text) {
+	try {
+		return decodeURIComponent(text);
+	} catch {
+		return text;
+	}
+}
+/** Token-aware comparison of one declared value against an observed one. */
+function valueMatches(declared, observed) {
+	return textEquals(declared, observed, new CaptureScope());
+}
+/**
+* Does an observed URL satisfy a declared one? A RegExp tests the full URL; a
+* PATH FORM (`/articles/{{uuid}}`) ignores the origin; an absolute string
+* compares origin+pathname. In both string forms `{{token}}` segments compare
+* structurally and declared query params are a SUBSET of the observed ones.
+*/
+function urlMatches(declared, observed) {
+	if (declared instanceof RegExp) return declared.test(observed);
+	let url;
+	try {
+		url = new URL(observed, RELATIVE_BASE);
+	} catch {
+		return false;
+	}
+	const { base, query } = splitDeclared(declared);
+	const observedBase = base.startsWith("/") ? url.pathname : `${url.origin}${url.pathname}`;
+	const decodedBase = base.startsWith("/") ? safeDecode(url.pathname) : `${url.origin}${safeDecode(url.pathname)}`;
+	if (!valueMatches(base, observedBase) && !valueMatches(base, decodedBase)) return false;
+	for (const key of new Set(query.keys())) {
+		const observedValues = url.searchParams.getAll(key);
+		if (!query.getAll(key).every((value) => observedValues.some((actual) => valueMatches(value, actual)))) return false;
+	}
+	return true;
+}
+/**
+* Does an observed request satisfy a contract? Method (`*` matches any), URL,
+* then the contract's own `match` predicate (headers/query/body filters).
+*/
+function contractMatches(contract, request) {
+	const { match, method, url } = contract.request;
+	if (method !== "*" && method.toUpperCase() !== request.method.toUpperCase()) return false;
+	if (!urlMatches(url, request.url)) return false;
+	return match ? match(request) : true;
+}
+/**
+* The URL pattern an out-of-process router (MSW) must register so the request
+* REACHES the queue. Deliberately no narrower than {@link contractMatches} —
+* the predicate above stays the authority on what actually matches.
+*/
+function routePatternOf(declared) {
+	if (declared instanceof RegExp) return declared;
+	const { base } = splitDeclared(declared);
+	if (base.startsWith("/")) return new RegExp(String.raw`^https?:\/\/[^/?#]+${placeholderPatternSource(base)}(?:\?[^#]*)?(?:#.*)?$`, "u");
+	if (hasPlaceholders(base)) return new RegExp(String.raw`^${placeholderPatternSource(base)}(?:\?[^#]*)?(?:#.*)?$`, "u");
+	return base;
+}
+/** How a declared contract reads in a failure message: spent, served, or silent. */
+function stateOf({ contract, served }) {
+	const { times } = contract;
+	if (times !== void 0 && served >= times) return ` (exhausted after ${times})`;
+	return served === 0 ? "" : ` (served ${served} time(s))`;
+}
+var ContractQueue = class {
+	entries;
+	constructor(contracts) {
+		this.entries = contracts.map((contract) => ({
+			contract,
+			served: 0
+		}));
+	}
+	/** How many contracts the chain declared. */
+	get size() {
+		return this.entries.length;
+	}
+	/**
+	* Routes to register with an out-of-process router, deduped by pattern —
+	* two contracts on the same URL share one handler and one queue.
+	*/
+	get routes() {
+		const routes = /* @__PURE__ */ new Map();
+		for (const { contract } of this.entries) {
+			const url = routePatternOf(contract.request.url);
+			const key = String(url);
+			const route = routes.get(key) ?? {
+				methods: [],
+				url
+			};
+			if (!route.methods.includes(contract.request.method)) route.methods.push(contract.request.method);
+			routes.set(key, route);
+		}
+		return [...routes.values()];
+	}
+	/** The declared routes, in order — the enumeration a 501 body carries. */
+	declaredRoutes() {
+		return this.entries.map(({ contract }) => describeRoute(contract));
+	}
+	/**
+	* Serve the first contract in declaration order that matches and is not
+	* exhausted, or null when nothing matches (including "everything that
+	* matches is spent") — the strict-violation signal.
+	*/
+	take(request) {
+		for (const entry of this.entries) {
+			const { times } = entry.contract;
+			if (times !== void 0 && entry.served >= times) continue;
+			if (!contractMatches(entry.contract, request)) continue;
+			entry.served += 1;
+			return entry.contract;
+		}
+		return null;
+	}
+	/**
+	* The chain-end failure for contracts declared `required: true` that were
+	* never requested (or not exactly `times` times), or null when every
+	* requirement held.
+	*/
+	requiredError() {
+		const unmet = [];
+		for (const { contract, served } of this.entries) {
+			if (!contract.required) continue;
+			const { times } = contract;
+			if (times === void 0) {
+				if (served === 0) unmet.push(`  - ${describeRoute(contract)} — declared and required but never requested`);
+			} else if (served !== times) unmet.push(`  - ${describeRoute(contract)} — declared required with times: ${times} but was requested ${served} time(s)`);
+		}
+		if (unmet.length === 0) return null;
+		return /* @__PURE__ */ new Error(`Required contract(s) never satisfied during the chain:\n${unmet.join("\n")}\nA required contract states the call MUST happen — either the code no longer makes it, or the contract no longer describes it.`);
+	}
+	/**
+	* The strict failure for a request that matched no contract (CONVENTIONS
+	* D7): method + URL of the offending request, plus every declared contract
+	* and how often it was served.
+	*/
+	unmatchedError(method, url) {
+		const declared = this.entries.length === 0 ? "  (no contracts declared)" : this.entries.map((entry) => `  - ${describeRoute(entry.contract)}${stateOf(entry)}`).join("\n");
+		return /* @__PURE__ */ new Error(`Unmatched outgoing HTTP request during spec: ${method} ${url}\nDeclared contracts:\n${declared}\nEvery outgoing request of a chain that declares contracts must match one — add a contract for it (or raise its \`times\` when it is exhausted).`);
+	}
+};
+//#endregion
+//#region src/specification/timing/pause.ts
+/**
+* One answer to "wait" — the only `setTimeout` the model owns.
+*
+* Two things in the framework genuinely have to wait: the spacing between the
+* pieces of a declared stream, and the poll behind `waitUntil`. Everything
+* else that waits is a spec doing it by hand, which is what J2 refuses. Stated
+* once so there is one place to look when time stops behaving.
+*/
+async function pause(ms) {
+	await new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
+//#endregion
+//#region src/specification/contracts/stream.ts
+/**
+* A declared stream, made real — ONE serialisation for all three engines.
+*
+* msw's server and msw's worker take a `ReadableStream` body verbatim
+* (https://mswjs.io/docs/http/mocking-responses/streaming) and the `node:http`
+* stub pipes one into its response, so what "arriving in pieces" MEANS —
+* the order, the spacing, the close after the last chunk — is stated here and
+* nowhere else. A second copy of it would be a second answer to "what does the
+* subject read", and the facets would drift.
+*/
+/**
+* The pieces of `body`, in order, `delayBetweenChunks` milliseconds apart,
+* closing after the last one.
+*/
+function toReadableStream(body) {
+	const encoder = new TextEncoder();
+	let index = 0;
+	return new ReadableStream({ async pull(controller) {
+		const chunk = body.chunks[index];
+		if (chunk === void 0) {
+			controller.close();
+			return;
+		}
+		if (body.delayBetweenChunks > 0 && index > 0) await pause(body.delayBetweenChunks);
+		index += 1;
+		controller.enqueue(encoder.encode(chunk));
+	} });
+}
+//#endregion
+//#region src/specification/contracts/types.ts
+/**
+* The marker that tells a STREAMED body from a value that happens to be an
+* object. A body reaches three different engines (msw's server, msw's worker,
+* the `node:http` stub) and each of them serialises "an object" as JSON, so a
+* stream declared as a plain value arrives as `{}`. The tag is what each
+* engine recognises before it reaches for `JSON.stringify`.
+*/
+const STREAM_BODY = "@jterrazz/test:stream";
+/** Is this body a declared stream rather than a value to serialise? */
+function isStreamBody(body) {
+	return typeof body === "object" && body !== null && "kind" in body && body.kind === "@jterrazz/test:stream";
+}
+//#endregion
+//#region src/integrations/msw/handlers.ts
+/**
+* A contract answers the request that was made, never a copy of an earlier one.
+*
+* In a page the reply travels through a real service worker and a real HTTP
+* cache, so a second render of the same component can be served the FIRST
+* test's answer and never reach the queue at all — a contract that was
+* exhausted, or replaced, silently keeps answering. Stated as a default, so a
+* spec whose subject IS caching can still say otherwise.
+*/
+const NEVER_CACHED = { "cache-control": "no-store" };
+/** Turn a contract response into the msw reply, body kind by body kind. */
+function toMswResponse(msw, response) {
+	const { body, headers, status = 200 } = response;
+	if (response.transport === "network-error") return msw.HttpResponse.error();
+	if (body === null || body === void 0) return new msw.HttpResponse(null, {
+		headers: {
+			...NEVER_CACHED,
+			...headers
+		},
+		status
+	});
+	if (isStreamBody(body)) return new msw.HttpResponse(toReadableStream(body), {
+		headers: {
+			...NEVER_CACHED,
+			"content-type": body.contentType,
+			...headers
+		},
+		status
+	});
+	if (typeof body === "string") return new msw.HttpResponse(body, {
+		headers: {
+			...NEVER_CACHED,
+			"content-type": "text/plain; charset=utf-8",
+			...headers
+		},
+		status
+	});
+	return msw.HttpResponse.json(body, {
+		headers: {
+			...NEVER_CACHED,
+			...headers
+		},
+		status
+	});
+}
+/**
+* The handlers one chain's contracts become, plus the trailing catch-all that
+* records any request no contract accepted (CONVENTIONS D7). The caller decides
+* what to do with the recorded violation — the api chain rethrows it, the
+* component chain fails the render. An EMPTY contract list is still a guard:
+* the catch-all alone says "this subject has no network".
+*
+* `bypass` names the traffic that is not the subject's: under node there is
+* none, in a page it is everything the runner fetches to BE a page.
+*/
+function buildContractHandlers(msw, contracts, bypass) {
+	const queue = new ContractQueue(contracts);
+	let violation = null;
+	const recordViolation = (method, url) => {
+		violation ??= queue.unmatchedError(method, url);
+		return msw.HttpResponse.json({ error: `@jterrazz/test strict contracts: unmatched request ${method} ${url}` }, {
+			headers: NEVER_CACHED,
+			status: 501
+		});
+	};
+	const handlers = [];
+	for (const route of queue.routes) for (const method of route.methods) {
+		const handlerFn = method === "*" ? msw.http.all : msw.http[method.toLowerCase()];
+		if (!handlerFn) continue;
+		handlers.push(handlerFn(route.url, async ({ request }) => {
+			const observed = await observe(request);
+			const contract = queue.take(observed);
+			if (!contract) return recordViolation(request.method, request.url);
+			const response = typeof contract.response === "function" ? contract.response(observed) : contract.response;
+			if (response.delay) await new Promise((resolve) => setTimeout(resolve, response.delay));
+			return toMswResponse(msw, response);
+		}));
+	}
+	handlers.push(msw.http.all("*", ({ request }) => bypass?.(request.url) === true ? msw.passthrough() : recordViolation(request.method, request.url)));
+	return {
+		handlers,
+		violation: () => violation ?? queue.requiredError()
+	};
+}
+/** The request as the queue matches it — body parsed when it is JSON. */
+async function observe(request) {
+	let body = null;
+	const rawText = await request.clone().text();
+	if (rawText) try {
+		body = JSON.parse(rawText);
+	} catch {
+		body = rawText;
+	}
+	const headers = {};
+	request.headers.forEach((value, key) => {
+		headers[key.toLowerCase()] = value;
+	});
+	return {
+		body,
+		headers,
+		method: request.method.toUpperCase(),
+		url: request.url
+	};
+}
+//#endregion
+//#region src/integrations/msw/worker.ts
+/**
+* What the runner itself fetches. Everything else a page asks for is the
+* subject's own traffic and answers to its contracts (D7).
+*/
+const RUNNER_PREFIXES = [
+	"/.artifacts/",
+	"/@fs/",
+	"/@id/",
+	"/@vite",
+	"/node_modules/",
+	"/__vitest"
+];
+let workerInstance = null;
+/**
+* Is this the runner's own traffic rather than the subject's?
+*
+* In a page EVERY module is an HTTP request: the test file, the seam, the
+* dependency cache Vite optimised, the runner's own channel. None of them is
+* the component's network, and none of them can be declared by a contract, so
+* they are recognised by PREFIX — never by extension, because msw bypasses a
+* "common asset" path before `onUnhandledRequest` ever runs and an extension
+* test would let a real `/api/posts.json` through on the same ground.
+*/
+function isRunnerRequest(url) {
+	const { pathname } = new URL(url);
+	return RUNNER_PREFIXES.some((prefix) => pathname.startsWith(prefix));
+}
+/**
+* Start the worker once per page. The script is served at `/mockServiceWorker.js`
+* by the plugin `component()` registers, out of the package's OWN `msw`
+* install — so no consumer ever runs `msw init` and no consumer declares `msw`.
+*/
+async function ensureContractWorker() {
+	if (workerInstance !== null) return;
+	const { setupWorker } = await import("msw/browser");
+	workerInstance = setupWorker();
+	await workerInstance.start({
+		onUnhandledRequest: (request, print) => {
+			if (!isRunnerRequest(request.url)) print.error();
+		},
+		quiet: true,
+		serviceWorker: { url: "/mockServiceWorker.js" }
+	});
+}
+/**
+* Register one render's contracts on the page's worker.
+*
+* The worker starts even when the list is empty: on this facet D7 is TOTAL —
+* a component that was given no contract has no network, and a fetch it makes
+* anyway is named by {@link ContractRegistration.violation} rather than
+* answered by whatever the dev server happens to have at that path.
+*/
+async function registerWorkerContracts(contracts) {
+	await ensureContractWorker();
+	const { handlers, violation } = buildContractHandlers(await import("msw"), contracts, isRunnerRequest);
+	workerInstance.use(...handlers);
+	return {
+		cleanup: () => {
+			workerInstance.resetHandlers();
+		},
+		violation
+	};
+}
+/** Drop every handler the page still carries — the per-test reset. */
+function resetWorkerContracts() {
+	if (workerInstance !== null) workerInstance.resetHandlers();
+}
+//#endregion
+//#region src/specification/facets/_common/ground.ts
+/**
+* The GROUND a row of specs stands on — the naming law of a spec tree.
+*
+* In a row of specs, a MEMBER is a spec: `<aspect>.test.ts`, `<case>.spec.yaml`,
+* `<name>.specification.ts`, and the facet/domain folders that hold them.
+* Everything else in that row is what the members STAND ON — inert material the
+* framework resolves BY PATH, never imported, never executed — and it carries a
+* LEADING UNDERSCORE. A spec's own folder never does.
+*
+* Four names, and only four: `_fixtures/` (file state), `_expected/` (goldens),
+* `_requests/` (inputs), `_seeds/` (database state). `contracts/` is NOT ground —
+* a contract is TypeScript a spec imports, behaviour composed with the spec's own,
+* so it stays a member. `docker/` is not ground either: it sits at the PROJECT
+* root beside `package.json`, outside any row of specs.
+*
+* This module is the single home of those names. Every resolver, matcher, lint
+* rule and checker pass reads them from here, so the runtime and the static
+* channels cannot disagree about where a spec's ground lives.
+*/
+/** Goldens: every expected fixture, flat, extension included. */
+const GROUND_EXPECTED = "_expected";
+//#endregion
+//#region src/specification/facets/_common/reporter.ts
+const GREEN = "\x1B[32m";
+const RED = "\x1B[31m";
+const RESET = "\x1B[0m";
+const strictEquals = (expected, actual) => expected === actual;
+function renderLines(expectedLines, actualLines, equals) {
+	const rendered = [];
+	let marked = 0;
+	const maxLines = Math.max(expectedLines.length, actualLines.length);
+	for (let i = 0; i < maxLines; i++) {
+		const exp = expectedLines[i];
+		const act = actualLines[i];
+		if (exp !== void 0 && act !== void 0 && equals(exp, act)) {
+			rendered.push(`  ${exp}`);
+			continue;
+		}
+		marked++;
+		if (exp !== void 0) rendered.push(`${GREEN}- ${exp}${RESET}`);
+		if (act !== void 0) rendered.push(`${RED}+ ${act}${RESET}`);
+	}
+	return {
+		marked,
+		rendered
+	};
+}
+/**
+* Render an expected/received diff over two texts.
+*
+* `equals` is how a line is judged EQUAL. Callers that compare through the
+* `{{token}}` grammar pass a token-aware predicate, so a `{{url}}` line that
+* matched is shown as equal — with its token, not as a `-`/`+` pair against
+* the concrete URL. Marking a line the comparison ACCEPTED buries the one it
+* rejected: the reader then has to work out which of the differences is the
+* actual cause.
+*
+* Safety net: if the token-aware pass marks nothing at all, the whole diff
+* would render as a clean block against a failure that really happened (a
+* `#ref` captured inconsistently across lines, say). The strict rendering is
+* used instead, so a diff always shows the reader something.
+*/
+function formatStdoutDiff(file, expected, actual, options) {
+	const lines = [];
+	lines.push(`Output mismatch (${file})`, "", `${GREEN}- Expected${RESET}`, `${RED}+ Received${RESET}`, "");
+	const expectedLines = expected.split("\n");
+	const actualLines = actual.split("\n");
+	const equals = options?.equals ?? strictEquals;
+	const first = renderLines(expectedLines, actualLines, equals);
+	const rendered = first.marked === 0 && equals !== strictEquals ? renderLines(expectedLines, actualLines, strictEquals).rendered : first.rendered;
+	return [...lines, ...rendered].join("\n");
+}
+//#endregion
+//#region src/specification/facets/_common/result/text-assertions.ts
+/** The fixture name carries its extension — the name IS the file. */
+function requireExtension(name, subject) {
+	if (!/\.[A-Za-z0-9]+$/u.test(name)) throw new Error(`toMatch("${name}"): the extension is part of the name and is required for ${subject} subjects (e.g. "help.txt").`);
+}
+/**
+* Compare a captured stream against the CONTENT of its golden. Text snapshots
+* share the unified `{{token}}` grammar (CONVENTIONS D4), and the diff judges
+* each line through the SAME grammar the comparison used — so a token line
+* that matched is shown as equal instead of competing with the real mismatch
+* for the reader's attention.
+*/
+function compareStreamText(accessor, name, expected) {
+	const actual = accessor.comparableText;
+	if (textEquals(expected, actual, accessor.captures)) return {
+		message: () => `expected ${accessor.streamName} not to match _expected/${name}`,
+		pass: true
+	};
+	return {
+		message: () => formatStdoutDiff(name, expected, actual, { equals: (expectedLine, actualLine) => textEquals(expectedLine, actualLine, new CaptureScope(accessor.captures.workdir)) }),
+		pass: false
+	};
+}
+/** `expect(stream).toBeEmpty()` — the stream you usually want silent. */
+function textIsEmpty(accessor) {
+	const content = accessor.comparableText;
+	const pass = content === "";
+	return {
+		message: () => pass ? `expected ${accessor.streamName} not to be empty` : `Expected ${accessor.streamName} to be empty, but it contains:\n${content}`,
+		pass
+	};
+}
+/** `expect(stream).toContain('…')` — the scalpel, never the default (D11). */
+function textContains(accessor, expected) {
+	const actual = accessor.comparableText;
+	const pass = actual.includes(expected);
+	return {
+		message: () => pass ? `expected ${accessor.streamName} not to contain ${JSON.stringify(expected)}` : `${accessor.streamName} does not contain expected substring.\n  expected to contain: ${JSON.stringify(expected)}\n  actual: ${JSON.stringify(actual.length > 500 ? `${actual.slice(0, 500)}…` : actual)}`,
+		pass
+	};
+}
+/**
+* `toMatch` and `toContain` on a subject that is NOT an accessor.
+*
+* Both matchers are overridden globally, for every subject in the project, so
+* whatever the framework does not own has to keep meaning what vitest's own
+* matcher meant. Stated once here because the two builds register two different
+* `expect.extend` calls: a copy in the page is how `expect(['ab']).toContain('b')`
+* ends up passing on one side of the seam and failing on the other.
+*/
+/** vitest's `toMatch` for a plain string: a substring, or a regular expression. */
+function nativeMatch(received, expected) {
+	if (typeof received !== "string") throw new TypeError("toMatch: unsupported subject — expected a stream, json, response, filesystem, or directory accessor, or a string.");
+	const pass = expected instanceof RegExp ? expected.test(received) : received.includes(String(expected));
+	return {
+		message: () => `expected ${JSON.stringify(received)} ${pass ? "not " : ""}to match ${String(expected)}`,
+		pass
+	};
+}
+/** vitest's `toContain` for a plain string (substring) or an iterable (membership). */
+function nativeContain(received, expected) {
+	if (typeof received === "string") {
+		const pass = received.includes(String(expected));
+		return {
+			message: () => `expected ${JSON.stringify(received)} ${pass ? "not " : ""}to contain ${JSON.stringify(expected)}`,
+			pass
+		};
+	}
+	if (isIterable(received)) {
+		const pass = [...received].includes(expected);
+		return {
+			message: () => `expected iterable ${pass ? "not " : ""}to contain ${JSON.stringify(expected)}`,
+			pass
+		};
+	}
+	throw new TypeError(`toContain: unsupported subject of type ${typeof received} — expected a stream accessor, string, or iterable.`);
+}
+/** Does this value hand out its members? A Set and an array both do; a DOM node does not. */
+function isIterable(value) {
+	return value !== null && value !== void 0 && typeof value[Symbol.iterator] === "function";
+}
+//#endregion
+//#region src/specification/facets/_common/result/grep.ts
+/**
+* Extract text blocks from output that contain a pattern.
+* Splits by blank lines (how linter/compiler output is structured),
+* returns only blocks matching the pattern.
+*
+* @example
+* expect(grep(result.stdout, "unused-var.ts")).toContain("no-unused-vars")
+* expect(grep(result.stdout, "valid/sorted.ts")).not.toContain("sort-imports")
+*/
+function grep(output, pattern) {
+	return output.replaceAll(/\u001B\[[0-9;]*m/gu, "").split(/\n\s*\n/u).filter((block) => block.includes(pattern)).join("\n\n");
+}
+//#endregion
+//#region src/specification/facets/_common/result/text.ts
+const ANSI_RE = /\u001B\[[0-9;]*m/gu;
+/** Strip ANSI escape sequences from a string. */
+function stripAnsiCodes(value) {
+	return value.replace(ANSI_RE, "");
+}
+/**
+* Read-only accessor for a captured text handle — THE universal one: stdout,
+* stderr, container logs, and file text all surface as a `TextAccessor`.
+*
+* Backed by a primitive string, exposed via {@link text}, but also provides
+* `toString()` / `valueOf()` for string coercion, so common patterns like
+* `String(result.stdout)` and template-literal interpolation still work.
+*
+* ANSI escape sequences are stripped by default before every comparison
+* (CONVENTIONS D6) — `.text` stays raw. The runner `transform` option remains
+* an escape hatch for application noise not covered by the `{{token}}`
+* grammar.
+*
+* Text operations are **closed** over the type: `.grep(pattern)` returns a
+* `TextAccessor` (not a bare string), preserving the `_expected/`-resolution
+* context and the `transform`, so results are chainable
+* (`result.stdout.grep(a).grep(b)`) and snapshot-able
+* (`expect(result.stdout.grep('users.ts')).toMatch('block.txt')`).
+*
+* Assertions go through `expect()` matchers: `expect(result.stdout).toContain(...)`
+* and `expect(result.stdout).toMatch('name.txt')` (resolved against
+* `_expected/<name>`, flat — with `{{token}}` support, CONVENTIONS D4).
+*/
+var TextAccessor = class TextAccessor {
+	/** @internal Ref-capture scope shared by the current spec execution. */
+	captures;
+	/** @internal Stream label used in failure messages ("stdout" / "stderr"). */
+	streamName;
+	/** @internal Test-file directory — fixture resolution root for matchers. */
+	testDir;
+	/** The raw captured text (never transformed, ANSI preserved). */
+	text;
+	/** @internal Normaliser applied before comparisons, never to fixtures. */
+	transform;
+	constructor(value, streamName, testDir, options = {}) {
+		this.text = value;
+		this.streamName = streamName;
+		this.testDir = testDir;
+		this.transform = options.transform;
+		this.captures = options.captures ?? new CaptureScope();
+	}
+	/** @internal The text as compared by matchers — ANSI stripped, transform applied. */
+	get comparableText() {
+		const stripped = stripAnsiCodes(this.text);
+		return this.transform ? this.transform(stripped) : stripped;
+	}
+	/**
+	* Keep only the blank-line-separated blocks of the text that contain
+	* `pattern` (how linter/compiler output is structured), returned as a new
+	* `TextAccessor` — the same subject type, so the result is chainable and
+	* snapshot-able. The scalpel for probing large tool outputs; snapshot the
+	* whole surface by default, reach for `.grep()` for targeted checks.
+	*/
+	grep(pattern) {
+		return new TextAccessor(grep(this.text, pattern), this.streamName, this.testDir, {
+			captures: this.captures,
+			transform: this.transform
+		});
+	}
+	toString() {
+		return this.text;
+	}
+	valueOf() {
+		return this.text;
+	}
+};
+//#endregion
+//#region src/specification/facets/website/ambiguity.ts
+/**
+* The ambiguity refusal — CONVENTIONS W3.
+*
+* A visit descriptor must designate exactly one element. Acting on "the
+* first match" is the failure mode this module exists to prevent: the spec
+* keeps passing while the visitor clicks something else, and nothing ever
+* reports it. So when a descriptor matches several elements the framework
+* refuses, and the refusal has to carry everything needed to fix it without
+* opening a browser — the descriptor in the caller's own vocabulary, every
+* candidate, and the concrete rewrites that would resolve it.
+*
+* Pure string building: it takes captured data and returns a message, so the
+* wording is unit-testable and the browser integration stays a thin adapter.
+*/
+/** `kind` → the constructor that builds it, so errors echo the caller's source. */
+const CONSTRUCTORS = {
+	banner: "banner",
+	button: "button",
+	complementary: "complementary",
+	contentinfo: "contentinfo",
+	dialog: "dialog",
+	field: "field",
+	form: "form",
+	heading: "heading",
+	link: "link",
+	listitem: "listitem",
+	main: "main",
+	navigation: "navigation",
+	option: "option",
+	region: "region",
+	row: "row",
+	search: "search",
+	status: "status",
+	table: "table",
+	testId: "testId",
+	text: "content"
+};
+/** The landmark a context string maps back to, for a copy-pasteable suggestion. */
+const CONTEXT_LANDMARKS = {
+	aside: "complementary()",
+	banner: "banner()",
+	complementary: "complementary()",
+	contentinfo: "contentinfo()",
+	footer: "contentinfo()",
+	form: "form()",
+	header: "banner()",
+	main: "main()",
+	nav: "navigation()",
+	navigation: "navigation()",
+	search: "search()"
+};
+/**
+* Render a descriptor as the source that would build it — `link('Articles')`,
+* `within(navigation(), link('Articles', { exact: true }))`. The error speaks
+* the vocabulary the author wrote, never playwright's.
+*/
+function formatElement(element) {
+	const bare = formatBare(element);
+	return element.scope ? `within(${formatElement(element.scope)}, ${bare})` : bare;
+}
+function formatBare(element) {
+	const args = [];
+	if (element.name !== void 0) args.push(JSON.stringify(element.name));
+	if (element.exact) args.push("{ exact: true }");
+	return `${CONSTRUCTORS[element.kind]}(${args.join(", ")})`;
+}
+/** `1. <a href="/articles">Articles</a>  in <nav>` — one evidence line per candidate. */
+function formatMatch(match, index) {
+	const attribute = match.detail ? ` ${quoteDetail(match)}` : "";
+	const named = match.accessibleName ? `  named ${JSON.stringify(match.accessibleName)}` : "";
+	const context = match.context ? `  in <${match.context}>` : "";
+	return `  ${index + 1}. <${match.tag}${attribute}>${match.text}</${match.tag}>${named}${context}`;
+}
+function quoteDetail(match) {
+	return `${match.tag === "a" ? "href" : "name"}=${JSON.stringify(match.detail)}`;
+}
+/** Each landmark the candidates sit in, and how many of them it holds. */
+function landmarkCounts(matches) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const match of matches) {
+		const landmark = match.context === void 0 ? void 0 : CONTEXT_LANDMARKS[match.context];
+		if (landmark !== void 0) counts.set(landmark, (counts.get(landmark) ?? 0) + 1);
+	}
+	return [...counts].toSorted(([, a], [, b]) => a - b);
+}
+/**
+* The rewrites worth offering, in the order they should be tried. Scoping is
+* always available; `exact` only when it would actually narrow the set, and
+* the count it would leave is stated so a still-ambiguous suggestion never
+* reads as a fix.
+*/
+function formatFixes(element, matches) {
+	const fixes = [];
+	const narrowing = landmarkCounts(matches).filter(([, count]) => count < matches.length);
+	if (!element.scope) {
+		const [first, ...rest] = narrowing;
+		const alsoHere = rest.length > 0 ? `   [also here: ${rest.map(([name]) => name).join(", ")}]` : "";
+		fixes.push(first === void 0 ? `scope it       within(<a container holding only this one>, ${formatBare(element)})` : `scope it       within(${first[0]}, ${formatBare(element)})   [leaves ${first[1]} of ${matches.length}]${alsoHere}`);
+	}
+	if (!element.exact && element.name !== void 0) {
+		const remaining = matches.filter((match) => match.text === element.name).length;
+		if (remaining > 0 && remaining < matches.length) fixes.push(`exact name     ${formatBare({
+			...element,
+			exact: true
+		})}   [leaves ${remaining} of ${matches.length}]`);
+	}
+	fixes.push("other element  a heading(), button() or field() may name one thing where this does not");
+	return fixes;
+}
+/**
+* The W3 refusal. A distinct class so the visit wrapper can recognize an
+* already-complete message and let it through instead of nesting it inside
+* `visit scenario failed: …`, which would print the whole thing twice.
+*/
+var AmbiguousElementError = class extends Error {
+	name = "AmbiguousElementError";
+};
+/**
+* Build the refusal thrown when a descriptor matches more than one element.
+*
+* @param options.element The descriptor as the caller wrote it.
+* @param options.matches Every candidate, in DOM order (already truncated).
+* @param options.url The page the visitor was on when it happened.
+*/
+function describeAmbiguity(options) {
+	const { element, matches, url } = options;
+	const fixes = formatFixes(element, matches).map((fix) => `  • ${fix}`);
+	return [
+		`Ambiguous element: ${formatElement(element)} matched ${matches.length} elements on ${url}.`,
+		"",
+		"A spec must designate exactly one element. Acting on the first match would let",
+		"this test keep passing while the visitor interacts with something else.",
+		"",
+		"Matched:",
+		...matches.map((match, index) => formatMatch(match, index)),
+		"",
+		"Disambiguate with one of:",
+		...fixes,
+		"",
+		"Docs: docs/14-website.md#designating-exactly-one-element (CONVENTIONS W3)"
+	].join("\n");
+}
+//#endregion
+//#region src/integrations/vitest-browser/vitest-browser.adapter.ts
+/**
+* The browser-mode adapter — the component facet's half of the one element
+* vocabulary.
+*
+* Its translation table is the playwright adapter's, descriptor for
+* descriptor: a `button('Save')` means `getByRole('button', { name })` whether
+* the surface is a served page or a mounted component, and the W3 refusal
+* enumerates candidates in the same words. Two adapters, one dialect — which
+* is the whole reason a page spec and a component spec read alike.
+*
+* What differs is where the code runs. Playwright drives a page from the
+* outside and reads it through `evaluate`; here the test IS in the page, so a
+* candidate is described from the live element and the ARIA tree is the one
+* thing that has to go back out (`server.commands`, the provider's own frame).
+*/
+/** How many candidates the ambiguity error enumerates before truncating. */
+const MAX_REPORTED_MATCHES = 10;
+/** The landmark ancestors the ambiguity evidence names. */
+const LANDMARKS = "nav, header, footer, main, aside, section, form, [role]";
+/**
+* Translate a user-facing descriptor into a Browser Mode locator, resolving
+* `scope` outside-in so `within(navigation(), link('X'))` searches the nav
+* subtree. No `.first()` anywhere: designating exactly one element is
+* CONVENTIONS W3, and taking the first match is the silent wrong-element bug
+* the rule exists to prevent.
+*/
+function locate(root, element) {
+	const scope = element.scope ? locate(root, element.scope) : root;
+	const exact = element.exact ?? false;
+	const name = element.name ?? "";
+	if (element.kind === "field") return scope.getByLabelText(name, { exact });
+	if (element.kind === "testId") return scope.getByTestId(name);
+	if (element.kind === "text") return scope.getByText(name, { exact });
+	return scope.getByRole(element.kind, element.name === void 0 ? { exact } : {
+		exact,
+		name: element.name
+	});
+}
+/** Describe the live candidates — the evidence the W3 refusal enumerates. */
+function candidates(locator) {
+	return locator.elements().slice(0, MAX_REPORTED_MATCHES).map((node) => {
+		const landmark = node.parentElement?.closest(LANDMARKS);
+		const context = landmark?.getAttribute("role") ?? landmark?.tagName.toLowerCase();
+		const detail = node.getAttribute("href") ?? node.getAttribute("name");
+		const text = (node.textContent ?? "").replaceAll(/\s+/gu, " ").trim().slice(0, 80);
+		const label = node.getAttribute("aria-label")?.trim();
+		return {
+			accessibleName: label !== void 0 && label !== text ? label : void 0,
+			context: context ?? void 0,
+			detail: detail ?? void 0,
+			tag: node.tagName.toLowerCase(),
+			text
+		};
+	});
+}
+/** Walk the scope chain outside-in; the outermost ambiguous level is the fault. */
+function ambiguousLevel(element) {
+	const chain = [];
+	for (let current = element; current; current = current.scope) chain.unshift(current);
+	for (const level of chain.slice(0, -1)) if (locate(page, level).elements().length > 1) return level;
+	return element;
+}
+/**
+* Run one visitor action, turning "more than one match" into the W3 refusal.
+* The ambiguous LEVEL is identified first: a scope matching several landmarks
+* is the real fault, and naming the target would send the author to fix the
+* wrong descriptor.
+*/
+async function act(element, action) {
+	const locator = locate(page, element);
+	try {
+		return await action(locator);
+	} catch (error) {
+		if (locator.elements().length <= 1) throw error;
+		const culprit = ambiguousLevel(element);
+		const matches = candidates(locate(page, culprit));
+		const url = globalThis.location.href;
+		throw new AmbiguousElementError(describeAmbiguity({
+			element: culprit,
+			matches,
+			url
+		}));
+	}
+}
+/**
+* Is this descriptor answered by PRESENCE rather than by visibility?
+*
+* The options of a collapsed `<select>` are in the document and in the
+* accessibility tree, and not one of them has a box on the screen — asking
+* whether an option is visible would answer "no" for every select a visitor
+* never opened.
+*/
+function byPresence(element) {
+	return element.kind === "option";
+}
+/** A control's live value — the property, never the attribute. */
+function valueOf(node) {
+	return node instanceof HTMLInputElement || node instanceof HTMLSelectElement || node instanceof HTMLTextAreaElement ? node.value : void 0;
+}
+/**
+* Is the element gone — or, with a state modifier, no longer in that state? A
+* node that left the document and one that is still there but not rendered are
+* the same answer to a spec.
+*/
+function isGone(locator, element) {
+	const node = locator.query();
+	if (element.focused === true) return node !== document.activeElement;
+	if (element.disabled !== void 0) return node === null || node.matches(":disabled") !== element.disabled;
+	if (element.selected !== void 0) return node === null || node.matches(":checked") !== element.selected;
+	if (element.value !== void 0) return node === null || valueOf(node) !== element.value;
+	return node === null || (byPresence(element) ? false : !node.checkVisibility());
+}
+/**
+* How long `gone()` waits — what is LEFT of the running test's budget.
+*
+* Every other verb already gets it: a locator action and `expect.element`
+* default their timeout to the remaining budget, and only a bare
+* `expect.poll` falls back to vitest's one second. That second made `gone()`
+* the one verb that could not outlast a slow answer — a button taken off the
+* screen when a two-second request returns was "still on the screen".
+*
+* The 100ms margin is vitest's own: the poll has to give up just BEFORE the
+* test does, or the failure is a bare timeout naming no element.
+*/
+function remainingBudget() {
+	const current = TestRunner.getCurrentTest();
+	const started = current?.result?.startTime;
+	if (current === void 0 || started === void 0) return;
+	return Math.max(current.timeout - (Date.now() - started) - 100, 0);
+}
+/** `expect.poll` over that budget — the retry the matchers get for free. */
+function polling(probe, message) {
+	const timeout = remainingBudget();
+	return expect.poll(probe, {
+		message,
+		...timeout === void 0 ? {} : { timeout }
+	});
+}
+/** A key name is a key; a single character is typed as itself. */
+function keystroke(key) {
+	return key.length > 1 ? `{${key}}` : key;
+}
+/** The verbs a rendered surface shares with a page, plus the two a parent owns. */
+function componentVerbs(surface) {
+	return {
+		check: async (element) => {
+			await act(element, async (locator) => {
+				const node = locator.element();
+				if (!(node instanceof HTMLInputElement) || !node.checked) await locator.click();
+			});
+		},
+		click: async (element) => {
+			await act(element, async (locator) => {
+				await locator.click();
+			});
+		},
+		fill: async (element, value) => {
+			await act(element, async (locator) => {
+				await locator.fill(value);
+			});
+		},
+		gone: async (element) => {
+			await act(element, async (locator) => {
+				await polling(() => isGone(locator, element), `${formatElement(element)} is still on the screen`).toBeTruthy();
+			});
+		},
+		hover: async (element) => {
+			await act(element, async (locator) => {
+				await locator.hover();
+			});
+		},
+		press: async (key) => {
+			await userEvent.keyboard(keystroke(key));
+		},
+		rerender: surface.rerender,
+		see: async (element) => {
+			await act(element, async (locator) => {
+				if (element.focused === true) {
+					await expect.element(locator).toHaveFocus();
+					return;
+				}
+				if (element.disabled === true) {
+					await expect.element(locator).toBeDisabled();
+					return;
+				}
+				if (element.disabled === false) {
+					await expect.element(locator).toBeEnabled();
+					return;
+				}
+				if (element.selected !== void 0) {
+					await polling(() => locator.query()?.matches(":checked") === true, `${formatElement(element)} is not the selected one`).toBe(element.selected);
+					return;
+				}
+				if (element.value !== void 0) {
+					await expect.element(locator).toHaveValue(element.value);
+					return;
+				}
+				if (byPresence(element)) {
+					await expect.element(locator).toBeInTheDocument();
+					return;
+				}
+				await expect.element(locator).toBeVisible();
+			});
+		},
+		select: async (element, option) => {
+			await act(element, async (locator) => {
+				await locator.selectOptions(option);
+			});
+		},
+		unmount: surface.unmount
+	};
+}
+/** The ARIA snapshot of the rendered `<body>` — the golden a tree is asserted as. */
+async function ariaTree() {
+	return await commands.ariaTree();
+}
+/** A golden's content, read server-side from `_expected/` beside the test. */
+async function readGolden(name) {
+	return await commands.goldenRead(name);
+}
+/** Write a golden server-side, and say where — update mode's half. */
+async function writeGolden(name, content) {
+	return await commands.goldenWrite(name, content);
+}
+/** Mount a React subject through the optional `vitest-browser-react` adapter. */
+async function mountReact(ui) {
+	let render;
+	try {
+		({render} = await import("vitest-browser-react"));
+	} catch (error) {
+		throw new Error(`component.render(<X />) needs vitest-browser-react and react (optional peers): npm install -D vitest-browser-react react react-dom (${String(error)})`, { cause: error });
+	}
+	const rendered = await render(ui);
+	return {
+		container: rendered.container,
+		rerender: rendered.rerender,
+		unmount: rendered.unmount
+	};
+}
+/**
+* Mount a vanilla DOM subject: the function is handed a fresh container and
+* may return its own teardown — the shape a DOM library states one in. There
+* is no react here, and no react is loaded.
+*/
+function mountDom(mount) {
+	const container = document.createElement("div");
+	document.body.append(container);
+	const teardown = mount(container);
+	return {
+		container,
+		rerender: () => {
+			throw new Error("rerender() replaces a React tree; a DOM function is re-rendered by calling it again in a new render().");
+		},
+		unmount: async () => {
+			teardown?.();
+			container.remove();
+			await Promise.resolve();
+		}
+	};
+}
+//#endregion
+//#region src/integrations/vitest-browser/golden.ts
+/** Update mode crosses the seam as a provided value, never as an env read. */
+function updating() {
+	return inject("update") === true;
+}
+async function matchGolden(accessor, name, frozen) {
+	requireExtension(name, "stream");
+	const actual = accessor.comparableText;
+	const stored = await readGolden(name);
+	if (stored === null) {
+		if (updating() && !frozen) {
+			const path = await writeGolden(name, actual);
+			return {
+				message: () => `wrote ${path}`,
+				pass: true
+			};
+		}
+		return {
+			message: () => `${accessor.streamName} fixture "${name}" does not exist under ${GROUND_EXPECTED}/ beside this test.\nRun with TEST_UPDATE=1 (or vitest -u) to create it.`,
+			pass: false
+		};
+	}
+	const comparison = compareStreamText(accessor, name, stored);
+	if (!comparison.pass && updating() && !frozen) {
+		await writeGolden(name, actual);
+		return {
+			message: () => `updated ${GROUND_EXPECTED}/${name}`,
+			pass: true
+		};
+	}
+	return comparison;
+}
+async function toMatch(received, expected, options) {
+	if (received instanceof TextAccessor) {
+		if (typeof expected !== "string") throw new TypeError("toMatch on accessors takes a fixture name (extension included) — for a regex, assert on the raw text instead: expect(x.text).toMatch(/re/).");
+		return await matchGolden(received, expected, options?.frozen === true);
+	}
+	return nativeMatch(received, expected);
+}
+function toContain(received, expected) {
+	if (received instanceof TextAccessor) return textContains(received, String(expected));
+	return nativeContain(received, expected);
+}
+function toBeEmpty(received) {
+	if (!(received instanceof TextAccessor)) throw new TypeError("toBeEmpty: unsupported subject — expected a text accessor.");
+	return textIsEmpty(received);
+}
+let registered = false;
+/**
+* Register the page's matchers with vitest's `expect`. Idempotent, and called
+* from the browser entry itself: a component test imports `@jterrazz/test` to
+* get `component`, and that import IS the registration.
+*/
+function registerBrowserMatchers() {
+	if (registered) return;
+	registered = true;
+	expect.extend({
+		toBeEmpty,
+		toContain,
+		toMatch
+	});
+}
+//#endregion
+//#region src/browser/node-only.ts
+/**
+* The refusals the browser build ships in place of what only node can do.
+*
+* `@jterrazz/test` has ONE specifier and two runtimes, so the page gets the
+* same NAMES as the server: a component test that reaches for
+* `specification.api()` or `postgres()` fails on the line that reached, saying
+* where that name runs — not on an unresolved import three layers down, and
+* not silently on `undefined`.
+*/
+/**
+* The refusal, in one line, whatever the name. Returns `never`, so a stub is
+* an ordinary arrow function the page's entry annotates with the node
+* signature — no cast, and no way for the two surfaces to disagree.
+*/
+function refuse(name) {
+	throw new Error(`${name} runs under node: a page has no filesystem, no child process and no socket. Specify it from a test collected by a node project (unit/api/jobs/cli/website/mobile); a rendered thing is a \`.test.tsx\` beside its component.`);
+}
+/**
+* A node-only CLASS, present under the same name. A class has a shape a stub
+* cannot honour — every instance member of the real one — so this is the one
+* place the page's entry states a type it does not structurally satisfy; what
+* the value can actually do is throw, which is the whole of the contract.
+*
+* The stub is a constructible FUNCTION, never an arrow: `new` on an arrow
+* throws "is not a constructor" before the refusal can run, so the page would
+* lose the one thing the stub exists to say — which name it reached for.
+*/
+const nodeOnlyClass = (name) => function NodeOnly() {
+	return refuse(name);
+};
+//#endregion
+//#region src/integrations/vitest-browser/page-runtime.ts
+/**
+* The runner, as the page reaches it.
+*
+* `vitest` is the framework's one sanctioned coupling and it lives in the
+* layers that own a runner — `src/vitest/` for the config side, this seam for
+* the page's. The component model asks for "after this test", "pin the clock"
+* and "what did the project provide" and never learns which runner answers.
+*/
+/** Run `teardown` when the current test ends, however it ends. No hook in the spec. */
+function afterThisTest(teardown) {
+	onTestFinished(teardown);
+}
+/**
+* Freeze the page's `Date` at `iso`. `Date` ONLY: faking the page's timers
+* would stop React's scheduler and nothing would ever render.
+*/
+function pinClock(iso) {
+	vi.useFakeTimers({
+		now: new Date(iso),
+		toFake: ["Date"]
+	});
+}
+/** Give the page its real clock back. */
+function releaseClock() {
+	vi.useRealTimers();
+}
+/** The instant `component({ clock })` pinned for every render, if it did. */
+function providedClock() {
+	return inject("componentClock");
+}
+/** The page size the project states — what a per-test `.viewport()` is restored to. */
+function providedViewport() {
+	return inject("componentViewport");
+}
+/** Resize the page the test renders into. */
+async function setViewport(size) {
+	await page.viewport(size.width, size.height);
+}
+/**
+* The project's `wrap`, left on `globalThis` by the setup module the project
+* loads. A shared symbol rather than an import: the setup module and this
+* bundle are two graphs in one page and share no module instance.
+*/
+function projectWrapper() {
+	const wrap = globalThis[Symbol.for("@jterrazz/test:component-wrap")];
+	return typeof wrap === "function" ? wrap : void 0;
+}
+//#endregion
+//#region src/specification/facets/component/rendered-text.ts
+/**
+* A stream captured INSIDE the page.
+*
+* Structurally identical to any other {@link TextAccessor} — the same
+* `{{token}}` grammar, the same ANSI stripping, the same `.grep()` — and
+* marked so the matcher augmentation can say the one thing that differs: its
+* golden lives on the server, so `toMatch` is awaited here where it is
+* synchronous everywhere else.
+*/
+var RenderedText = class extends TextAccessor {
+	/** The marker the `toMatch` overload reads. Never asserted on directly. */
+	capturedInPage = true;
+};
+//#endregion
+//#region src/specification/facets/component/component.result.ts
+/**
+* What a render resolves to — the component as the page saw it, after the
+* scenario ran.
+*
+* Five accessors and no more: the ARIA outline a golden pins, the two
+* renderings a probe reads, and the two streams a spec wants silent. Nothing
+* here reaches back into React — a spec that needs the component's internals
+* is asserting the implementation, not the surface a user meets.
+*/
+var RenderResult = class {
+	/** The browser console as a stream — one `[type] text` line per message. */
+	console;
+	/** Rendered text of the whole document body (`innerText`). */
+	content;
+	/** Console messages of type `error` only, plus any uncaught page error. */
+	errors;
+	/** The mounted markup, serialised — the escape hatch for a class or an attribute. */
+	html;
+	/** The ARIA snapshot of the rendered body — the outline a golden pins. */
+	tree;
+	constructor(streams) {
+		this.console = new RenderedText(streams.console, "console", "");
+		this.content = new RenderedText(streams.content, "content", "");
+		this.errors = new RenderedText(streams.errors, "errors", "");
+		this.html = new RenderedText(streams.html, "html", "");
+		this.tree = new RenderedText(streams.tree, "tree", "");
+	}
+};
+//#endregion
+//#region src/specification/facets/component/component.chain.ts
+/** The console methods a render records; everything else is left alone. */
+const CONSOLE_METHODS = [
+	"debug",
+	"error",
+	"info",
+	"log",
+	"warn"
+];
+const EMPTY = {
+	clock: null,
+	contracts: [],
+	viewport: null,
+	wrap: null
+};
+/** Record what the page writes to the console for the length of the render. */
+function recordConsole() {
+	const entries = [];
+	const originals = /* @__PURE__ */ new Map();
+	for (const method of CONSOLE_METHODS) {
+		const original = console[method];
+		originals.set(method, original);
+		console[method] = (...args) => {
+			entries.push({
+				text: args.map(String).join(" "),
+				type: method
+			});
+			original(...args);
+		};
+	}
+	const onError = (event) => {
+		entries.push({
+			text: event.message,
+			type: "error"
+		});
+	};
+	globalThis.addEventListener("error", onError);
+	let stopped = false;
+	return {
+		entries,
+		stop: () => {
+			if (stopped) return;
+			stopped = true;
+			for (const method of CONSOLE_METHODS) {
+				const original = originals.get(method);
+				if (original !== void 0) console[method] = original;
+			}
+			globalThis.removeEventListener("error", onError);
+		}
+	};
+}
+/** Is the subject a function that fills a container, rather than a React tree? */
+function isDomMount(subject) {
+	return typeof subject === "function";
+}
+/** A bare request needs its response — the same refusal every facet gives. */
+function inlinePair(request, response) {
+	if (response === void 0) throw new Error(".intercept(): a bare request needs its response — pass a contract (defineContract({ request, response })) or the inline pair .intercept(request, response).");
+	return {
+		request,
+		response
+	};
+}
+/**
+* What the page is still holding, and the teardown that lets it go.
+*
+* The React adapter's own auto-cleanup is a `beforeEach` registered when its
+* module loads — and this package loads it lazily, INSIDE the first render, so
+* that hook never covers the test that triggered it. The seam does the unmount
+* itself, on the test that rendered: two renders' markup sharing one document
+* is how a second `button('Open')` appears and a descriptor that named exactly
+* one element starts refusing.
+*/
+let mounted = null;
+/** Everything one test may have left behind, undone — no hook in any spec. */
+async function resetComponentScope(resized) {
+	await unmountHeld();
+	if (resized) await setViewport(providedViewport());
+	resetWorkerContracts();
+	releaseClock();
+}
+/** Take down whatever is still mounted, and hold nothing afterwards. */
+async function unmountHeld() {
+	const surface = mounted;
+	mounted = null;
+	if (surface !== null) try {
+		await surface.unmount();
+	} catch {}
+}
+/** Mount the subject, dressing a React tree in the chain's wrapper and the project's. */
+async function mount(state, subject) {
+	if (isDomMount(subject)) return mountDom(subject);
+	const outer = projectWrapper();
+	const dress = (ui) => {
+		const inner = state.wrap ? state.wrap(ui) : ui;
+		return outer ? outer(inner) : inner;
+	};
+	const surface = await mountReact(dress(subject));
+	return {
+		...surface,
+		rerender: async (ui) => {
+			await surface.rerender(dress(ui));
+		}
+	};
+}
+/** The terminal action: mount, run the scenario, capture what the page shows. */
+async function render(state, subject, scenario) {
+	await unmountHeld();
+	const recorder = recordConsole();
+	afterThisTest(async () => {
+		recorder.stop();
+		await resetComponentScope(state.viewport !== null);
+	});
+	if (state.viewport !== null) await setViewport(state.viewport);
+	const instant = state.clock ?? providedClock();
+	if (instant !== void 0) pinClock(instant);
+	const registration = await registerWorkerContracts(state.contracts);
+	const surface = await mount(state, subject);
+	mounted = surface;
+	try {
+		if (scenario) await scenario(componentVerbs(surface));
+	} finally {
+		recorder.stop();
+	}
+	const violation = registration.violation();
+	if (violation !== null) throw violation;
+	const { entries } = recorder;
+	return new RenderResult({
+		console: entries.map((entry) => `[${entry.type}] ${entry.text}`).join("\n"),
+		content: document.body.innerText,
+		errors: entries.filter((entry) => entry.type === "error").map((entry) => entry.text).join("\n"),
+		html: surface.container.innerHTML,
+		tree: await ariaTree()
+	});
+}
+/** Every setup forks a chain, so the exported handle never carries a test's state. */
+function chainOf(state) {
+	return {
+		clock: (iso) => chainOf({
+			...state,
+			clock: iso
+		}),
+		intercept: (requestOrContracts, maybeResponse) => {
+			const added = Array.isArray(requestOrContracts) || isContracts(requestOrContracts) || isContract(requestOrContracts) ? contractsOf(requestOrContracts) : [inlinePair(requestOrContracts, maybeResponse)];
+			return chainOf({
+				...state,
+				contracts: [...state.contracts, ...added]
+			});
+		},
+		render: async (subject, scenario) => await render(state, subject, scenario),
+		viewport: (size) => chainOf({
+			...state,
+			viewport: size
+		}),
+		wrap: (wrapper) => chainOf({
+			...state,
+			wrap: wrapper
+		})
+	};
+}
+/** The handle a component test imports. */
+const component = chainOf(EMPTY);
+//#endregion
+//#region src/specification/facets/_common/result/json.ts
+/**
+* Read-only accessor for a JSON payload parsed from a text stream (stdout).
+*
+* Lazily parses the JSON on first use; parse errors are deferred until the
+* value is read so that callers can still read the raw stream text without
+* triggering a throw.
+*
+* ANSI escape sequences are stripped by default before `JSON.parse`
+* (CONVENTIONS D6). When a `transform` is configured on the spec runner, it
+* runs on the stripped text — an escape hatch for application noise not
+* covered by the `{{token}}` grammar.
+*
+* Assertions go through `expect()`: `expect(result.json).toMatch('name.json')`
+* (deep-equal against `_expected/<name>`, with `{{placeholder}}` support).
+*/
+var JsonAccessor = class {
+	/** @internal Ref-capture scope shared by the current spec execution. */
+	captures;
+	/** @internal */
+	rawText;
+	/** @internal Test-file directory — fixture resolution root for matchers. */
+	testDir;
+	/** @internal */
+	transform;
+	constructor(rawText, testDir, transform, captures) {
+		this.rawText = rawText;
+		this.testDir = testDir;
+		this.transform = transform;
+		this.captures = captures ?? new CaptureScope();
+	}
+	/**
+	* The parsed JSON value. Throws if the text is not valid JSON.
+	*
+	* `Value` is `unknown` unless the subject that produced this accessor
+	* knows better — `.call<T>()` does, and hands its T straight through so a
+	* one-field reading needs no cast in the test.
+	*/
+	get value() {
+		const stripped = stripAnsiCodes(this.rawText);
+		const source = this.transform ? this.transform(stripped) : stripped;
+		try {
+			return JSON.parse(source);
+		} catch {
+			const preview = source.slice(0, 200);
+			throw new Error(`stdout is not valid JSON: ${preview}`);
+		}
+	}
+};
+//#endregion
+//#region src/specification/facets/_common/result/table.ts
+/**
+* Read-only accessor for a database table after a specification run.
+*
+* Assertions go through `expect()` (async — they query the database):
+*
+*     await expect(result.table('users', { database: 'db' })).toMatchRows({
+*         columns: ['name'],
+*         rows: [['Alice']],
+*     });
+*     await expect(result.table('users', { database: 'db' })).toBeEmpty();
+*/
+var TableAccessor = class {
+	/** @internal Ref-capture scope shared by the current spec execution. */
+	captures;
+	/** @internal */
+	db;
+	/** The table name this accessor reads. */
+	name;
+	constructor(name, db, captures) {
+		this.name = name;
+		this.db = db;
+		this.captures = captures ?? new CaptureScope();
+	}
+	/** @internal Query the table — used by the toMatchRows / toBeEmpty matchers. */
+	async query(columns) {
+		return await this.db.query(this.name, columns);
+	}
+};
+//#endregion
+//#region src/specification/facets/website/elements.ts
+const named = (kind) => (name, options) => ({
+	kind,
+	name,
+	...options?.exact ? { exact: true } : {}
+});
+/** A button (or element with the button role), by accessible name. */
+const button = named("button");
+/** A form field, by label. */
+const field = named("field");
+/** A heading, by accessible name. */
+const heading = named("heading");
+/** A link, by accessible name. */
+const link = named("link");
+/** An element containing the given text. */
+const content = named("text");
+/** The escape hatch: an element by `data-testid`. Prefer user-facing elements. */
+const testId = (id) => ({
+	kind: "testId",
+	name: id
+});
+const landmark = (kind) => (name, options) => ({
+	kind,
+	...name === void 0 ? {} : { name },
+	...options?.exact ? { exact: true } : {}
+});
+/** The `banner` landmark — the page header. */
+const banner = landmark("banner");
+/** The `complementary` landmark — an `<aside>`, a sidebar. */
+const complementary = landmark("complementary");
+/** The `contentinfo` landmark — the page footer. */
+const contentinfo = landmark("contentinfo");
+/** The `form` landmark — a form carrying an accessible name. */
+const form = landmark("form");
+/** The `main` landmark — the primary content of the document. */
+const main = landmark("main");
+/** The `navigation` landmark — a `<nav>`. Name it when a page has several. */
+const navigation = landmark("navigation");
+/** The `region` landmark — a `<section>` carrying an accessible name. */
+const region = landmark("region");
+/** The `search` landmark. */
+const search = landmark("search");
+/**
+* Restrict a descriptor to the inside of another — the answer to ambiguity,
+* and the one the framework prefers over a test id.
+*
+*     click(within(navigation(), link('Articles')))
+*
+* Composes outside-in: the scope may itself be scoped, so a deeply nested
+* target reads `within(main(), within(region('Series'), link('Part 2')))`.
+* Any descriptor works as a scope, including `testId()` when a container has
+* no landmark role to stand on.
+*/
+const within = (scope, target) => ({
+	...target,
+	scope: target.scope ? {
+		...target.scope,
+		scope
+	} : scope
+});
+/** A modal or non-modal `<dialog>`, by accessible name. A closed one is absent. */
+const dialog = landmark("dialog");
+/** A live region announcing a result — `role="status"`, an `<output>`. */
+const status = landmark("status");
+/** A table, by its caption or accessible name. */
+const table = landmark("table");
+/** A row of a table or grid, by the text of its cells. */
+const row = landmark("row");
+/** An item of a list, by its text. Retires the `.first()` of an unnamed `<li>`. */
+const listitem = landmark("listitem");
+/**
+* An option of a select or a listbox, by its label — named inside the field
+* that holds it: `within(field('Channel'), option('LinkedIn'))`.
+*
+* Asserted by PRESENCE, not by visibility: the options of a collapsed
+* `<select>` are in the document and in the accessibility tree, and none of
+* them has a box on the screen until it is opened. `see(option('LinkedIn'))`
+* therefore asks "is it offered", and `see(selected(option('LinkedIn')))`
+* asks which one the field is on.
+*/
+const option = named("option");
+/**
+* Where the keyboard is: `see(focused(button('Open')))` asserts the element has
+* focus, `gone(focused(x))` that it does not.
+*
+* A modifier rather than a descriptor of its own, because focus is a STATE of
+* an element the vocabulary can already name. It is a verb's business and never
+* a golden's: the accessibility tree carries no focus, so a tree snapshot of a
+* dialog that took the keyboard and one that did not are byte-identical.
+*/
+const focused = (element) => ({
+	...element,
+	focused: true
+});
+/**
+* Whether the element accepts input: `see(disabled(button('Delete')))` asserts
+* it refuses, `see(enabled(button('Delete')))` that it takes it.
+*
+* Modifiers rather than descriptors, for the same reason as `focused`: being
+* disabled is a state of an element the vocabulary already names. Unlike focus,
+* the ARIA tree carries it, so a golden pins a whole outline's enablement and
+* these name the ONE control a test is about. They also buy the direction a
+* behavioural substitute cannot reach — clicking a disabled control is a
+* timeout, never an assertion.
+*/
+const disabled = (element) => ({
+	...element,
+	disabled: true
+});
+/** The other direction of {@link disabled} — the element takes input. */
+const enabled = (element) => ({
+	...element,
+	disabled: false
+});
+/**
+* Which option the field is on: `see(selected(option('LinkedIn')))`, and
+* `gone(selected(option('X')))` for the one it left.
+*
+* A modifier for the same reason as {@link disabled}: being chosen is a state
+* of an element the vocabulary already names. No matcher answers for it — a
+* `<option>` is not a checkbox — so both adapters read the `:checked` the CSS
+* spec gives a selected option.
+*/
+const selected = (element) => ({
+	...element,
+	selected: true
+});
+/**
+* What the field holds: `see(valued(field('Title'), 'Launch teaser'))`, and
+* `gone(valued(field('Title'), '…'))` for a value it no longer holds.
+*
+* A modifier for the same reason as {@link disabled}: what a field holds is a
+* state of an element the vocabulary already names, and this is how the ONE
+* field a test is about is waited for — a golden pins a whole outline instead.
+* Read from the node's live value, never from the `value` ATTRIBUTE, which a
+* controlled input never moves.
+*/
+const valued = (element, value) => ({
+	...element,
+	value
+});
+//#endregion
+//#region src/specification/contracts/filters.ts
+/** Does an observed text satisfy a declared {@link TextFilter}? */
+function matchesText(filter, actual) {
+	if (filter === void 0) return true;
+	if (typeof filter === "string") return actual === filter;
+	if (filter instanceof RegExp) return filter.test(actual);
+	return structuralEquals(filter, actual, new CaptureScope());
+}
+//#endregion
+//#region src/integrations/anthropic/anthropic.ts
+const ANTHROPIC_MESSAGES_URL = "https://api.anthropic.com/v1/messages";
+function matchesFilter(body, filter) {
+	if (!matchesText(filter.model, body?.model ?? "")) return false;
+	if (!matchesText(filter.system, typeof body?.system === "string" ? body.system : "")) return false;
+	const userMsg = body?.messages?.find((m) => m.role === "user")?.content ?? "";
+	if (!matchesText(filter.user, typeof userMsg === "string" ? userMsg : JSON.stringify(userMsg))) return false;
+	if (filter.tools) {
+		const names = body?.tools?.map((t) => t.name).filter(Boolean) ?? [];
+		if (!filter.tools.every((t) => names.includes(t))) return false;
+	}
+	return true;
+}
+function buildReply(data) {
+	return {
+		status: 200,
+		body: {
+			id: "msg-test",
+			type: "message",
+			role: "assistant",
+			content: [{
+				type: "text",
+				text: typeof data === "string" ? data : JSON.stringify(data)
+			}],
+			model: "claude-sonnet-4-20250514",
+			stop_reason: "end_turn",
+			usage: {
+				input_tokens: 10,
+				output_tokens: 10
+			}
+		}
+	};
+}
+/**
+* Anthropic API intercept helpers.
+*/
+const anthropic = {
+	/**
+	* Request: match Messages API calls, optionally routed through a
+	* custom gateway URL. When used with a JSON fixture file, the data is
+	* returned as-is (no wrapping) because Anthropic fixtures are typically
+	* already in the Messages API response shape.
+	*
+	* @example
+	*   anthropic.messages()
+	*   anthropic.messages({ system: /classify/ })
+	*   anthropic.messages({ user: buildPrompt() })   // string = EXACT equality
+	*   anthropic.messages({ user: /classify/ }, GATEWAY)
+	*/
+	messages(filter, url) {
+		return {
+			adapter: "anthropic",
+			method: "POST",
+			url: url ?? ANTHROPIC_MESSAGES_URL,
+			match: filter ? ({ body }) => matchesFilter(body, filter) : void 0,
+			wrap(data) {
+				if (data && typeof data === "object" && !Array.isArray(data)) return {
+					status: 200,
+					body: data
+				};
+				return buildReply(data);
+			}
+		};
+	},
+	/** Response: wrap data in Anthropic messages format. */
+	reply(data) {
+		return buildReply(data);
+	},
+	/** Response: return an Anthropic error. */
+	error(status, message) {
+		return {
+			status,
+			body: {
+				type: "error",
+				error: {
+					type: status === 429 ? "rate_limit_error" : "api_error",
+					message: message ?? `Anthropic error (${status})`
+				}
+			}
+		};
+	},
+	/** Response: simulate a timeout. */
+	timeout() {
+		return {
+			status: 200,
+			body: {},
+			delay: 3e4
+		};
+	}
+};
+//#endregion
+//#region src/specification/contracts/http.ts
+function wrapJson(data) {
+	return {
+		status: 200,
+		body: data
+	};
+}
+const TEXT_CONTENT_TYPE = "text/plain; charset=utf-8";
+const STREAM_CONTENT_TYPE = "application/octet-stream";
+const SSE_CONTENT_TYPE = "text/event-stream";
+/** The wire form of one event — the frame an `EventSource` parses. */
+function frameEvent(event) {
+	const lines = [];
+	if (event.event !== void 0) lines.push(`event: ${event.event}`);
+	if (event.id !== void 0) lines.push(`id: ${event.id}`);
+	if (event.retry !== void 0) lines.push(`retry: ${event.retry}`);
+	const payload = typeof event.data === "string" ? event.data : JSON.stringify(event.data);
+	for (const line of payload.split("\n")) lines.push(`data: ${line}`);
+	return `${lines.join("\n")}\n\n`;
+}
+function matchesBody(body, expected) {
+	if (typeof expected === "string") return (typeof body === "string" ? body : JSON.stringify(body ?? "")).includes(expected);
+	if (expected instanceof RegExp) {
+		const text = typeof body === "string" ? body : JSON.stringify(body ?? "");
+		return expected.test(text);
+	}
+	return structuralSubset(expected, body, new CaptureScope());
+}
+function matchesEntries(expected, lookup) {
+	return Object.entries(expected).every(([key, value]) => {
+		const actual = lookup(key);
+		if (actual === void 0) return false;
+		return value instanceof RegExp ? value.test(actual) : actual === value;
+	});
+}
+/**
+* Build the `match` predicate for an HTTP request filter, or `undefined` when
+* no filter is supplied (fires on any URL/method match).
+*/
+function buildMatch(filter) {
+	if (!filter) return;
+	return (request) => {
+		if (filter.body !== void 0 && !matchesBody(request.body, filter.body)) return false;
+		if (filter.headers && !matchesEntries(filter.headers, (key) => request.headers[key.toLowerCase()])) return false;
+		if (filter.query) {
+			let params;
+			try {
+				params = new URL(request.url, "http://contract.invalid").searchParams;
+			} catch {
+				return false;
+			}
+			if (!matchesEntries(filter.query, (key) => params.get(key) ?? void 0)) return false;
+		}
+		return true;
+	};
+}
+function declare(method, url, filter) {
+	return {
+		adapter: "http",
+		match: buildMatch(filter),
+		method,
+		url,
+		wrap: wrapJson
+	};
+}
+/**
+* Generic HTTP contract helpers for any URL. The url is absolute (string or
+* RegExp), or a PATH FORM starting with `/` — `http.get('/articles/{{uuid}}')`
+* matches that path on ANY origin, which is what an app calling its own
+* backend needs. An optional {@link HttpContractFilter} narrows matching by
+* body, headers, or query — a request that hits the URL/method but fails the
+* filter counts as unmatched (strict contracts, CONVENTIONS D7).
+*
+* @example
+*   defineContract({ request: http.get('/articles/{{uuid}}'), response: http.json(article) })
+*   defineContract({ request: http.post(URL, { body: { user: 'alice' } }), response: http.empty() })
+*/
+const http = {
+	any(url, filter) {
+		return declare("*", url, filter);
+	},
+	delete(url, filter) {
+		return declare("DELETE", url, filter);
+	},
+	get(url, filter) {
+		return declare("GET", url, filter);
+	},
+	patch(url, filter) {
+		return declare("PATCH", url, filter);
+	},
+	post(url, filter) {
+		return declare("POST", url, filter);
+	},
+	put(url, filter) {
+		return declare("PUT", url, filter);
+	},
+	/** Response: a body-less reply (204 by default). */
+	empty(status = 204) {
+		return {
+			status,
+			body: null
+		};
+	},
+	/** Response: an error status. Without a body, `{ error: 'HTTP <status>' }`. */
+	error(status, body) {
+		return {
+			status,
+			body: body === void 0 ? { error: `HTTP ${status}` } : body
+		};
+	},
+	/** Response: a JSON body (200 by default). */
+	json(body, init) {
+		return {
+			status: init?.status ?? 200,
+			body,
+			delay: init?.delay,
+			headers: init?.headers
+		};
+	},
+	/**
+	* Response: no response at all — the request fails in transport, the way a
+	* server that is not running fails it. `fetch` rejects; no status is served.
+	*/
+	unreachable() {
+		return {
+			body: null,
+			transport: "network-error"
+		};
+	},
+	/**
+	* Response: a body that arrives in PIECES, written in order.
+	*
+	* A subject that reads a response as it lands — a token-by-token render, a
+	* progress bar, a reconnect on a half-read body — is specified by the
+	* chunks and their order, which a single serialised body cannot state.
+	* Honoured by all three engines: msw's server, msw's worker, and the
+	* `node:http` stub the website and mobile facets serve from.
+	*
+	* @example
+	*   http.stream(['Hel', 'lo, ', 'world'], { contentType: 'text/plain', delay: 10 })
+	*/
+	stream(chunks, init) {
+		return {
+			status: init?.status ?? 200,
+			body: {
+				chunks: [...chunks],
+				contentType: init?.contentType ?? STREAM_CONTENT_TYPE,
+				delayBetweenChunks: init?.delay ?? 0,
+				kind: STREAM_BODY
+			},
+			headers: init?.headers
+		};
+	},
+	/**
+	* Response: a server-sent event stream — one chunk per event, framed the
+	* way an `EventSource` reads them, served as `text/event-stream`.
+	*
+	* @example
+	*   http.sse([{ data: { token: 'Hel' } }, { data: { token: 'lo' } }, { event: 'done', data: '' }])
+	*/
+	sse(events, init) {
+		return {
+			status: init?.status ?? 200,
+			body: {
+				chunks: events.map(frameEvent),
+				contentType: SSE_CONTENT_TYPE,
+				delayBetweenChunks: init?.delay ?? 0,
+				kind: STREAM_BODY
+			},
+			headers: {
+				"cache-control": "no-cache",
+				...init?.headers
+			}
+		};
+	},
+	/** Response: a text body, served as `text/plain` (200 by default). */
+	text(body, init) {
+		return {
+			status: init?.status ?? 200,
+			body,
+			delay: init?.delay,
+			headers: {
+				"content-type": TEXT_CONTENT_TYPE,
+				...init?.headers
+			}
+		};
+	}
+};
+//#endregion
+//#region src/integrations/openai/openai.ts
+const OPENAI_CHAT_URL = "https://api.openai.com/v1/chat/completions";
+const OPENAI_RESPONSES_URL = "https://api.openai.com/v1/responses";
+function matchesChatFilter(body, filter) {
+	if (!matchesText(filter.model, body?.model ?? "")) return false;
+	if (!matchesText(filter.system, body?.messages?.find((m) => m.role === "system")?.content ?? "")) return false;
+	if (!matchesText(filter.user, body?.messages?.find((m) => m.role === "user")?.content ?? "")) return false;
+	if (filter.tools) {
+		const names = body?.tools?.map((t) => t.function?.name).filter(Boolean) ?? [];
+		if (!filter.tools.every((t) => names.includes(t))) return false;
+	}
+	if (filter.temperature !== void 0 && body?.temperature !== filter.temperature) return false;
+	return true;
+}
+function matchesResponsesFilter(body, filter) {
+	if (!matchesText(filter.model, body?.model ?? "")) return false;
+	const systemInput = body?.input?.find?.((m) => m.role === "system")?.content ?? "";
+	if (!matchesText(filter.system, body?.instructions || systemInput)) return false;
+	const userText = (body?.input ?? []).filter((m) => m.role === "user").map((m) => typeof m.content === "string" ? m.content : JSON.stringify(m.content)).join(" ");
+	if (!matchesText(filter.user, userText)) return false;
+	if (filter.tools) {
+		const names = body?.tools?.map((t) => t.name ?? t.function?.name).filter(Boolean) ?? [];
+		if (!filter.tools.every((t) => names.includes(t))) return false;
+	}
+	return true;
+}
+function buildChatReply(data) {
+	const content = typeof data === "string" ? data : JSON.stringify(data);
+	return {
+		status: 200,
+		body: {
+			id: "chatcmpl-test",
+			object: "chat.completion",
+			created: Math.floor(Date.now() / 1e3),
+			model: "gpt-4o-test",
+			choices: [{
+				index: 0,
+				message: {
+					role: "assistant",
+					content
+				},
+				finish_reason: "stop"
+			}],
+			usage: {
+				prompt_tokens: 10,
+				completion_tokens: 10,
+				total_tokens: 20
+			}
+		}
+	};
+}
+function buildResponsesReply(data) {
+	const text = typeof data === "string" ? data : JSON.stringify(data);
+	return {
+		status: 200,
+		body: {
+			id: "resp-test",
+			object: "response",
+			created_at: Math.floor(Date.now() / 1e3),
+			model: "gpt-4o-test",
+			output: [{
+				type: "message",
+				id: "msg-test",
+				role: "assistant",
+				content: [{
+					type: "output_text",
+					text,
+					annotations: []
+				}]
+			}],
+			usage: {
+				input_tokens: 10,
+				output_tokens: 10,
+				total_tokens: 20
+			}
+		}
+	};
+}
+/**
+* OpenAI API intercept helpers.
+*/
+const openai = {
+	/**
+	* Request: match Chat Completions API calls. STRING filters mean EXACT
+	* equality (pass the app's own prompt builder); loosen deliberately with a
+	* RegExp or `match.includes(...)`.
+	*
+	* @example
+	*   openai.chat()                            // any chat call
+	*   openai.chat({ model: 'gpt-4o' })         // exact model
+	*   openai.chat({ system: buildPrompt() })   // exact system prompt
+	*   openai.chat({ system: /classify/ })      // pattern
+	*/
+	chat(filter) {
+		return {
+			adapter: "openai",
+			method: "POST",
+			url: OPENAI_CHAT_URL,
+			match: filter ? ({ body }) => matchesChatFilter(body, filter) : void 0,
+			wrap: buildChatReply
+		};
+	},
+	/**
+	* Request: match Responses API calls (AI SDK v5+) with auto-wrapping.
+	* String filters mean EXACT equality (see {@link openai.chat}).
+	* When used with a JSON file, the data is automatically wrapped in the
+	* Responses API envelope.
+	*
+	* @param filter - Optional body filters.
+	* @param url - Custom gateway URL (default: api.openai.com).
+	*
+	* @example
+	*   openai.responses({ user: /Report Ingestion/ }, GATEWAY)
+	*/
+	responses(filter, url) {
+		return {
+			adapter: "openai",
+			method: "POST",
+			url: url ?? OPENAI_RESPONSES_URL,
+			match: filter ? ({ body }) => matchesResponsesFilter(body, filter) : void 0,
+			wrap: buildResponsesReply
+		};
+	},
+	/**
+	* Response: wrap data in Chat Completions format.
+	*
+	* @example
+	*   openai.reply({ categories: ['TECH'] })
+	*/
+	reply(data) {
+		return buildChatReply(data);
+	},
+	/** Response: return an OpenAI error. */
+	error(status, message) {
+		return {
+			status,
+			body: { error: {
+				message: message ?? `OpenAI error (${status})`,
+				type: status === 429 ? "rate_limit_error" : "api_error",
+				code: status === 429 ? "rate_limit_exceeded" : null
+			} }
+		};
+	},
+	/** Response: return malformed content. */
+	malformed(content) {
+		return buildChatReply(content);
+	},
+	/** Response: simulate a timeout. */
+	timeout() {
+		return {
+			status: 200,
+			body: {},
+			delay: 3e4
+		};
+	}
+};
+//#endregion
+//#region src/vitest/mock-of.ts
+function mockOf(options) {
+	return options?.deep === false ? mock() : mockDeep();
+}
+//#endregion
+//#region src/vitest/mock-of-date.ts
+/**
+* Freeze or reset the global Date for deterministic time-dependent tests.
+* Wraps the `mockdate` package.
+*/
+const mockOfDate = MockDatePackage;
+//#endregion
+//#region src/vitest/clock.ts
+/** The instant `iso` names, or a refusal that says what an instant looks like. */
+function instantOf(method, iso) {
+	const at = new Date(iso);
+	if (Number.isNaN(at.getTime())) throw new TypeError(`clock.${method}(): "${iso}" is not an instant — pass an ISO-8601 string (e.g. '2026-03-04T09:30:00Z').`);
+	return at;
+}
+/**
+* One clock per test — a second one taken inside the first is refused rather
+* than nested.
+*
+* Disposing gives the REAL clock back, which is the only thing vitest's fake
+* timers can restore: the instant, the `toFake` set and the queue a previous
+* scope held are not readable, so an inner scope that ended would silently end
+* the outer one too. A refusal says which of the two the test meant.
+*/
+function take(method, options) {
+	if (vi.isFakeTimers()) throw new Error(`clock.${method}(): a clock is already pinned — one scope per test. End the first scope before taking another, or state the instant on the chain (\`.clock(iso)\`) rather than around it.`);
+	vi.useFakeTimers(options);
+	return { [Symbol.dispose]: () => {
+		vi.useRealTimers();
+	} };
+}
+const clock = {
+	/**
+	* Move the pinned clock forward by `ms` — and, under {@link clock.run},
+	* fire every callback that came due, awaiting what each of them started.
+	*
+	* Only a pinned clock moves: called with no clock taken, it says so rather
+	* than silently doing nothing to the real one.
+	*/
+	async advance(ms) {
+		if (!vi.isFakeTimers()) throw new Error("clock.advance(): no clock is pinned — take one first with `using _ = clock.at('<iso>')` (the calendar) or `using _ = clock.run()` (the scheduler).");
+		await vi.advanceTimersByTimeAsync(ms);
+	},
+	/**
+	* Pin `Date` at `iso` for the current scope. `Date` ONLY: the scheduler
+	* stays real, so a subject that awaits, renders or polls keeps running.
+	*
+	* @example
+	*   using _ = clock.at('2026-03-04T09:30:00Z');
+	*   expect(stampedAt()).toBe('2026-03-04T09:30:00.000Z');
+	*/
+	at(iso) {
+		return take("at", {
+			now: instantOf("at", iso),
+			toFake: ["Date"]
+		});
+	},
+	/**
+	* Take the scheduler as well as the calendar: `setTimeout`, `setInterval`
+	* and their friends queue instead of firing, and {@link clock.advance} is
+	* what makes them due. For a subject whose behaviour IS elapsed time — a
+	* debounce, a retry backoff, a poll — where waiting for real would be the
+	* arbitrary sleep J2 forbids.
+	*
+	* @example
+	*   using _ = clock.run('2026-03-04T09:30:00Z');
+	*   const pending = retrying(failsTwice);
+	*   await clock.advance(5_000);
+	*   await expect(pending).resolves.toBe('ok');
+	*/
+	run(iso) {
+		return take("run", iso === void 0 ? {} : { now: instantOf("run", iso) });
+	}
+};
+//#endregion
+//#region src/specification/assertions/required.ts
+/**
+* The value, or a failure that says what was missing and why it mattered.
+*
+* A test reaching into a captured structure — a row, a header, the third
+* element of a list — meets `T | undefined` and has to do something about it.
+* The two things it usually does are both wrong: `!` erases the question, and
+* an `if (!x) throw new Error('missing')` re-states the same three lines in
+* every repository (the estate had two hand-written copies of exactly this).
+* `required` is that gesture with the reason attached, so the failure reads as
+* a sentence rather than as a `TypeError` two frames further down.
+*
+* @example
+*   const id = required(result.response.body.id, 'the creation reply carries the new id');
+*/
+function required(value, why) {
+	if (value === null || value === void 0) throw new Error(`required(): ${why} — got ${value === null ? "null" : "undefined"}. State it in the Given, or assert on what the subject actually produced.`);
+	return value;
+}
+//#endregion
+//#region src/specification/assertions/wait-until.ts
+const DEFAULT_TIMEOUT_MS = 5e3;
+const DEFAULT_INTERVAL_MS = 50;
+/**
+* Wait until a condition holds — the sanctioned answer to "the thing I am
+* specifying is not ready yet".
+*
+* A spec that sleeps for a guessed duration is a spec that is slow on a fast
+* machine and flaky on a slow one, which is why J2 refuses `setTimeout` under
+* `specs/`. Every facet that drives something already waits on a CONDITION —
+* a served page, a banner on stdout, an element the visitor can see — and this
+* is that primitive where no facet owns the waiting: a background write to
+* land, a queue to drain, a file to appear.
+*
+* The failure names the condition and how long it was given, so a timeout is a
+* sentence rather than "expected true, got false".
+*
+* The budget is measured on `performance.now()`, not on `Date` — `clock.at()`
+* freezes the calendar, and a deadline read off a frozen calendar never
+* arrives: the poll would run until vitest killed the test with a sentence
+* about the file rather than about the condition.
+*
+* Not for a subject under `clock.run()`: there the scheduler is the test's, and
+* `clock.advance(ms)` is what makes time pass.
+*
+* @example
+*   await waitUntil(() => outbox.length === 1, { why: 'the job wrote its one message' });
+*/
+async function waitUntil(predicate, options = {}) {
+	const timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+	const interval = options.interval ?? DEFAULT_INTERVAL_MS;
+	const deadline = performance.now() + timeout;
+	for (;;) {
+		if (await predicate()) return;
+		if (performance.now() >= deadline) throw new Error(`waitUntil(): ${options.why ?? "the condition"} did not hold within ${timeout}ms. Raise the budget if the wait is legitimate, or wait on what actually changes.`);
+		await pause(interval);
+	}
+}
+//#endregion
+//#region src/browser/index.ts
+registerBrowserMatchers();
+/**
+* The module-scope network double, on msw's WORKER — the same contracts and
+* the same strictness the node entry publishes, served by the one engine a
+* page has. Everything new in this release that a page can use is real here.
+*/
+const intercept = interceptThrough(registerWorkerContracts);
+/**
+* The six constructors, present and refusing. A component test never reaches
+* one: what it renders is a unit, and the assembled product behind an entry is
+* specified from a node project.
+*/
+const specification = {
+	api: () => refuse("specification.api()"),
+	cli: () => refuse("specification.cli()"),
+	integration: () => refuse("specification.integration()"),
+	jobs: () => refuse("specification.jobs()"),
+	mobile: () => refuse("specification.mobile()"),
+	website: () => refuse("specification.website()")
+};
+const process = () => refuse("process()");
+const ProcessHandle = nodeOnlyClass("ProcessHandle");
+const postgres = () => refuse("postgres()");
+const redis = () => refuse("redis()");
+const sqlite = () => refuse("sqlite()");
+const ContainerAccessor = nodeOnlyClass("ContainerAccessor");
+const findContainersByLabel = () => refuse("findContainersByLabel()");
+const inspectContainer = () => refuse("inspectContainer()");
+const removeContainers = () => refuse("removeContainers()");
+const Orchestrator = nodeOnlyClass("Orchestrator");
+const BaseResult = nodeOnlyClass("BaseResult");
+const CallResult = nodeOnlyClass("CallResult");
+const CliResult = nodeOnlyClass("CliResult");
+const DirectoryAccessor = nodeOnlyClass("DirectoryAccessor");
+const FetchResult = nodeOnlyClass("FetchResult");
+const FilesystemAccessor = nodeOnlyClass("FilesystemAccessor");
+const HttpResult = nodeOnlyClass("HttpResult");
+const PageResult = nodeOnlyClass("PageResult");
+const ResponseAccessor = nodeOnlyClass("ResponseAccessor");
+const ScreenResult = nodeOnlyClass("ScreenResult");
+/**
+* `text()` is real here: only its anchor differs. Under node the accessor
+* remembers the caller's directory so a golden resolves against it; in a page
+* the golden commands read the test's own path server-side, so there is
+* nothing for the accessor to carry.
+*/
+function text(value) {
+	return new TextAccessor(value, "text", "");
+}
+//#endregion
+export { BaseResult, CallResult, CliResult, ContainerAccessor, DirectoryAccessor, FetchResult, FilesystemAccessor, HttpResult, JsonAccessor, Matcher, Orchestrator, PageResult, ProcessHandle, ResponseAccessor, ScreenResult, TableAccessor, TextAccessor, anthropic, banner, button, clock, complementary, component, content, contentinfo, defineContract, defineContracts, dialog, disabled, enabled, field, findContainersByLabel, focused, form, heading, http, inspectContainer, intercept, link, listitem, main, match, mockOf, mockOfDate, navigation, openai, option, postgres, process, redis, region, removeContainers, required, row, search, selected, specification, sqlite, status, table, testId, text, valued, waitUntil, within };