@jterrazz/test 15.2.0 → 15.3.0

package/dist/browser/index.js

@@ -1,29 +1,146 @@
 import { TestRunner, expect, inject, onTestFinished, vi } from "vitest";
 import { commands, page, userEvent } from "vitest/browser";
-import { mockDeep } from "vitest-mock-extended";
+import { mock, mockDeep } from "vitest-mock-extended";
 import MockDatePackage from "mockdate";
-//#region src/specification/facets/_common/ground.ts
+//#region src/specification/contracts/contract.ts
 /**
-* The GROUND a row of specs stands on — the naming law of a spec tree.
+* Declare one contract. Identity function — its value is the enforced shape
+* and the naming convention:
 *
-* 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.
+* @example
+*   // specs/api/reports/contracts/openai/classify-article.ts
+*   import { defineContract, openai } from '@jterrazz/test';
 *
-* 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.
+*   export default defineContract({
+*       request: openai.responses({ user: PROMPT, tools: ['classify'] }),
+*       response: openai.reply({ categories: ['TECH'] }),
+*   });
 *
-* 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.
+*   // 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 }),
+*   });
 */
-/** Goldens: every expected fixture, flat, extension included. */
-const GROUND_EXPECTED = "_expected";
+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). */
@@ -411,1152 +528,1156 @@ function textEquals(expected, actual, scope) {
 	return placeholderStringMatches(expected, actual, scope);
 }
 //#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
-	};
-}
+//#region src/specification/contracts/queue.ts
 /**
-* Render an expected/received diff over two texts.
+* 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.
 *
-* `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.
+* 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]`.
 *
-* 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.
+* 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).
 */
-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
+/** 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 {
-		message: () => formatStdoutDiff(name, expected, actual, { equals: (expectedLine, actualLine) => textEquals(expectedLine, actualLine, new CaptureScope(accessor.captures.workdir)) }),
-		pass: false
+		base: url.slice(0, separator),
+		query: new URLSearchParams(url.slice(separator + 1))
 	};
 }
-/** `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
-	};
+/** Decode percent-escapes, falling back to the raw text on malformed input. */
+function safeDecode(text) {
+	try {
+		return decodeURIComponent(text);
+	} catch {
+		return text;
+	}
 }
-/** `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
-	};
+/** Token-aware comparison of one declared value against an observed one. */
+function valueMatches(declared, observed) {
+	return textEquals(declared, observed, new CaptureScope());
 }
 /**
-* `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.
+* 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.
 */
-/** 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
-		};
+function urlMatches(declared, observed) {
+	if (declared instanceof RegExp) return declared.test(observed);
+	let url;
+	try {
+		url = new URL(observed, RELATIVE_BASE);
+	} catch {
+		return false;
 	}
-	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";
+	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;
 }
-//#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")
+* Does an observed request satisfy a contract? Method (`*` matches any), URL,
+* then the contract's own `match` predicate (headers/query/body filters).
 */
-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, "");
+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;
 }
 /**
-* 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).
+* 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.
 */
-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();
+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
+		}));
 	}
-	/** @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;
+	/** How many contracts the chain declared. */
+	get size() {
+		return this.entries.length;
 	}
 	/**
-	* 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.
+	* Routes to register with an out-of-process router, deduped by pattern —
+	* two contracts on the same URL share one handler and one queue.
 	*/
-	grep(pattern) {
-		return new TextAccessor(grep(this.text, pattern), this.streamName, this.testDir, {
-			captures: this.captures,
-			transform: this.transform
-		});
+	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()];
 	}
-	toString() {
-		return this.text;
+	/** The declared routes, in order — the enumeration a 501 body carries. */
+	declaredRoutes() {
+		return this.entries.map(({ contract }) => describeRoute(contract));
 	}
-	valueOf() {
-		return this.text;
+	/**
+	* 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/facets/website/ambiguity.ts
+//#region src/specification/timing/pause.ts
 /**
-* The ambiguity refusal — CONVENTIONS W3.
+* One answer to "wait" — the only `setTimeout` the model owns.
 *
-* 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.
+* 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.
 *
-* 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()"
-};
+* 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
 /**
-* 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.
+* 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`.
 */
-function formatElement(element) {
-	const bare = formatBare(element);
-	return element.scope ? `within(${formatElement(element.scope)}, ${bare})` : bare;
+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";
 }
-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}`;
+//#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
+	});
 }
-function quoteDetail(match) {
-	return `${match.tag === "a" ? "href" : "name"}=${JSON.stringify(match.detail)}`;
+/**
+* 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()
+	};
 }
-/** 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);
+/** 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;
 	}
-	return [...counts].toSorted(([, a], [, b]) => a - b);
+	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
 /**
-* 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.
+* What the runner itself fetches. Everything else a page asks for is the
+* subject's own traffic and answers to its contracts (D7).
 */
-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;
+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));
 }
 /**
-* 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.
+* 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`.
 */
-var AmbiguousElementError = class extends Error {
-	name = "AmbiguousElementError";
-};
+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" }
+	});
+}
 /**
-* Build the refusal thrown when a descriptor matches more than one element.
+* Register one render's contracts on the page's worker.
 *
-* @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.
+* 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.
 */
-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");
+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/integrations/vitest-browser/vitest-browser.adapter.ts
+//#region src/specification/facets/_common/ground.ts
 /**
-* The browser-mode adapter — the component facet's half of the one element
-* vocabulary.
+* The GROUND a row of specs stands on — the naming law of a spec tree.
 *
-* 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.
+* 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.
 *
-* 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).
+* 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.
 */
-/** 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]";
+/** 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
+	};
+}
 /**
-* 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.
+* 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 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
-		};
-	});
+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");
 }
-/** 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;
+//#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").`);
 }
 /**
-* 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.
+* 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.
 */
-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
-		}));
-	}
+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
+	};
 }
 /**
-* Is this descriptor answered by PRESENCE rather than by visibility?
+* `toMatch` and `toContain` on a subject that is NOT an accessor.
 *
-* 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.
+* 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.
 */
-function byPresence(element) {
-	return element.kind === "option";
+/** 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
+	};
 }
-/** 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;
+/** 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
 /**
-* 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.
+* 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 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());
+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, "");
 }
 /**
-* How long `gone()` waits — what is LEFT of the running test's budget.
+* Read-only accessor for a captured text handle — THE universal one: stdout,
+* stderr, container logs, and file text all surface as a `TextAccessor`.
 *
-* 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".
+* 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.
 *
-* 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.
+* 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).
 */
-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 });
+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();
 	}
-	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
-		};
+	/** @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;
 	}
-	const comparison = compareStreamText(accessor, name, stored);
-	if (!comparison.pass && updating() && !frozen) {
-		await writeGolden(name, actual);
-		return {
-			message: () => `updated ${GROUND_EXPECTED}/${name}`,
-			pass: true
-		};
+	/**
+	* 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
+		});
 	}
-	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);
+	toString() {
+		return this.text;
+	}
+	valueOf() {
+		return this.text;
 	}
-	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/specification/contracts/contract.ts
+//#region src/specification/facets/website/ambiguity.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';
+* The ambiguity refusal — CONVENTIONS W3.
 *
-*   export default defineContract({
-*       request: openai.responses({ user: PROMPT, tools: ['classify'] }),
-*       response: openai.reply({ categories: ['TECH'] }),
-*   });
+* 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.
 *
-*   // 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 }),
-*   });
+* 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.
 */
-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;
-}
+/** `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()"
+};
 /**
-* 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).
+* 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 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;
+function formatElement(element) {
+	const bare = formatBare(element);
+	return element.scope ? `within(${formatElement(element.scope)}, ${bare})` : bare;
 }
-/**
-* 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]);
-		}
-	};
+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(", ")})`;
 }
-/** Normalize any accepted input into a flat contract list. */
-function contractsOf(input) {
-	return flatten([input]);
+/** `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}`;
 }
-//#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))
-	};
+function quoteDetail(match) {
+	return `${match.tag === "a" ? "href" : "name"}=${JSON.stringify(match.detail)}`;
 }
-/** Decode percent-escapes, falling back to the raw text on malformed input. */
-function safeDecode(text) {
-	try {
-		return decodeURIComponent(text);
-	} catch {
-		return text;
+/** 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);
 	}
-}
-/** Token-aware comparison of one declared value against an observed one. */
-function valueMatches(declared, observed) {
-	return textEquals(declared, observed, new CaptureScope());
+	return [...counts].toSorted(([, a], [, b]) => a - b);
 }
 /**
-* 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.
+* 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 urlMatches(declared, observed) {
-	if (declared instanceof RegExp) return declared.test(observed);
-	let url;
-	try {
-		url = new URL(observed, RELATIVE_BASE);
-	} catch {
-		return false;
+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}`);
 	}
-	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;
+	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}]`);
 	}
-	return true;
+	fixes.push("other element  a heading(), button() or field() may name one thing where this does not");
+	return fixes;
 }
 /**
-* Does an observed request satisfy a contract? Method (`*` matches any), URL,
-* then the contract's own `match` predicate (headers/query/body filters).
+* 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.
 */
-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;
-}
+var AmbiguousElementError = class extends Error {
+	name = "AmbiguousElementError";
+};
 /**
-* 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.
+* 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 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))`;
+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");
 }
-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/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
+		}));
 	}
-};
-//#endregion
-//#region src/integrations/msw/handlers.ts
+}
 /**
-* A contract answers the request that was made, never a copy of an earlier one.
+* Is this descriptor answered by PRESENCE rather than by visibility?
 *
-* 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.
+* 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.
 */
-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 (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
-	});
+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;
 }
 /**
-* 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".
+* 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.
 *
-* `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.
+* 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 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
-		});
+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
 	};
-	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);
-		}));
+}
+/** 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 });
 	}
-	handlers.push(msw.http.all("*", ({ request }) => bypass?.(request.url) === true ? msw.passthrough() : recordViolation(request.method, request.url)));
+	const rendered = await render(ui);
 	return {
-		handlers,
-		violation: () => violation ?? queue.requiredError()
+		container: rendered.container,
+		rerender: rendered.rerender,
+		unmount: rendered.unmount
 	};
 }
-/** 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;
-	});
+/**
+* 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 {
-		body,
-		headers,
-		method: request.method.toUpperCase(),
-		url: request.url
+		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/msw/worker.ts
+//#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;
 /**
-* What the runner itself fetches. Everything else a page asks for is the
-* subject's own traffic and answers to its contracts (D7).
+* 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.
 */
-const RUNNER_PREFIXES = [
-	"/.artifacts/",
-	"/@fs/",
-	"/@id/",
-	"/@vite",
-	"/node_modules/",
-	"/__vitest"
-];
-let workerInstance = null;
+function registerBrowserMatchers() {
+	if (registered) return;
+	registered = true;
+	expect.extend({
+		toBeEmpty,
+		toContain,
+		toMatch
+	});
+}
+//#endregion
+//#region src/browser/node-only.ts
 /**
-* Is this the runner's own traffic rather than the subject's?
+* The refusals the browser build ships in place of what only node can do.
 *
-* 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.
+* `@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`.
 */
-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`.
+* 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.
 */
-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" }
-	});
+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.`);
 }
 /**
-* Register one render's contracts on the page's worker.
+* 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 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.
+* 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.
 */
-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();
-}
+const nodeOnlyClass = (name) => function NodeOnly() {
+	return refuse(name);
+};
 //#endregion
 //#region src/integrations/vitest-browser/page-runtime.ts
 /**
@@ -1846,7 +1967,13 @@ var JsonAccessor = class {
 		this.transform = transform;
 		this.captures = captures ?? new CaptureScope();
 	}
-	/** The parsed JSON value. Throws if the text is not valid JSON. */
+	/**
+	* 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;
@@ -2139,6 +2266,18 @@ function wrapJson(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) {
@@ -2248,6 +2387,52 @@ const http = {
 			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 {
@@ -2420,11 +2605,9 @@ const openai = {
 };
 //#endregion
 //#region src/vitest/mock-of.ts
-/**
-* Create a deep mock proxy for a given type.
-* Wraps `vitest-mock-extended`'s `mockDeep` for convenient port mocking.
-*/
-const mockOf = mockDeep;
+function mockOf(options) {
+	return options?.deep === false ? mock() : mockDeep();
+}
 //#endregion
 //#region src/vitest/mock-of-date.ts
 /**
@@ -2433,20 +2616,155 @@ const mockOf = mockDeep;
 */
 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 five constructors, present and refusing. A component test never reaches
+* 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()");
@@ -2456,6 +2774,7 @@ 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");
@@ -2474,4 +2793,4 @@ function text(value) {
 	return new TextAccessor(value, "text", "");
 }
 //#endregion
-export { BaseResult, CliResult, ContainerAccessor, DirectoryAccessor, FetchResult, FilesystemAccessor, HttpResult, JsonAccessor, Matcher, Orchestrator, PageResult, ResponseAccessor, ScreenResult, TableAccessor, TextAccessor, anthropic, banner, button, complementary, component, content, contentinfo, defineContract, defineContracts, dialog, disabled, enabled, field, findContainersByLabel, focused, form, heading, http, inspectContainer, link, listitem, main, match, mockOf, mockOfDate, navigation, openai, option, postgres, redis, region, removeContainers, row, search, selected, specification, sqlite, status, table, testId, text, valued, within };
+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 };