@jterrazz/test 15.3.0 → 16.1.0

package/dist/browser/index.js

@@ -1,8 +1,7 @@
 import { TestRunner, expect, inject, onTestFinished, vi } from "vitest";
 import { commands, page, userEvent } from "vitest/browser";
 import { mock, mockDeep } from "vitest-mock-extended";
-import MockDatePackage from "mockdate";
-//#region src/specification/contracts/contract.ts
+//#region src/model/contracts/contract.ts
 /**
 * Declare one contract. Identity function — its value is the enforced shape
 * and the naming convention:
@@ -88,7 +87,7 @@ function contractsOf(input) {
 	return flatten([input]);
 }
 //#endregion
-//#region src/integrations/msw/scope.ts
+//#region src/model/contracts/intercept.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
@@ -120,6 +119,38 @@ function declared(requestOrContracts, maybeResponse) {
 		response: maybeResponse
 	}];
 }
+/** Is this argument the options object rather than a response? */
+function isOptions(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) && "origin" in value;
+}
+/**
+* Resolve every relative request against `origin` for the life of the scope.
+*
+* The framework owns the seam so a test never has to: this is the one place
+* `fetch` is wrapped, it is put back when the scope ends, and what it does is
+* the one thing a page would have done for free — turn `/api/posts` into a URL.
+*
+* Validating the origin and INSTALLING the wrapper are two steps because they
+* happen at two moments: the refusal of a bad origin belongs before anything
+* starts, while the wrapper may only go on once the engine is listening — it
+* has to sit ON TOP of whatever `fetch` the engine installed, and be taken off
+* before the engine takes its own back.
+*/
+function resolveRelativeAgainst(origin) {
+	let base;
+	try {
+		base = new URL(origin);
+	} catch {
+		throw new Error(`intercept(): \`origin\` states where a relative request resolves — \`${origin}\` is not an absolute URL (e.g. 'http://console.test').`);
+	}
+	return () => {
+		const engine = globalThis.fetch;
+		globalThis.fetch = async (input, init) => typeof input === "string" && input.startsWith("/") ? await engine(new URL(input, base).toString(), init) : await engine(input, init);
+		return () => {
+			globalThis.fetch = engine;
+		};
+	};
+}
 /**
 * 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,
@@ -128,11 +159,15 @@ function declared(requestOrContracts, maybeResponse) {
 * @internal
 */
 function interceptThrough(register) {
-	async function intercept(requestOrContracts, maybeResponse) {
-		const contracts = declared(requestOrContracts, maybeResponse);
+	async function intercept(requestOrContracts, maybeResponseOrOptions, maybeOptions) {
+		const options = isOptions(maybeOptions) ? maybeOptions : isOptions(maybeResponseOrOptions) ? maybeResponseOrOptions : void 0;
+		const contracts = declared(requestOrContracts, options === maybeResponseOrOptions ? void 0 : maybeResponseOrOptions);
 		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 installOrigin = options?.origin === void 0 ? void 0 : resolveRelativeAgainst(options.origin);
 		const registration = await register(contracts);
+		const restoreOrigin = installOrigin?.();
 		return { [Symbol.asyncDispose]: async () => {
+			restoreOrigin?.();
 			const violation = registration.violation();
 			registration.cleanup();
 			await Promise.resolve();
@@ -142,7 +177,7 @@ function interceptThrough(register) {
 	return intercept;
 }
 //#endregion
-//#region src/specification/matching/match.ts
+//#region src/model/matching/match.ts
 /** Every kind usable as a `{{token}}` in fixture files (all but ref/regex/includes). */
 const TOKEN_KINDS = [
 	"any",
@@ -295,7 +330,94 @@ var CaptureScope = class {
 	}
 };
 //#endregion
-//#region src/specification/matching/structural.ts
+//#region src/model/result/grep.ts
+/**
+* Extract text blocks from output that contain a pattern.
+* Splits by blank lines (how linter/compiler output is structured),
+* returns only blocks matching the pattern.
+*
+* @example
+* expect(grep(result.stdout, "unused-var.ts")).toContain("no-unused-vars")
+* expect(grep(result.stdout, "valid/sorted.ts")).not.toContain("sort-imports")
+*/
+function grep(output, pattern) {
+	return output.replaceAll(/\u001B\[[0-9;]*m/gu, "").split(/\n\s*\n/u).filter((block) => block.includes(pattern)).join("\n\n");
+}
+//#endregion
+//#region src/model/result/text.ts
+const ANSI_RE = /\u001B\[[0-9;]*m/gu;
+/** Strip ANSI escape sequences from a string. */
+function stripAnsiCodes(value) {
+	return value.replace(ANSI_RE, "");
+}
+/**
+* Read-only accessor for a captured text handle — THE universal one: stdout,
+* stderr, container logs, and file text all surface as a `TextAccessor`.
+*
+* Backed by a primitive string, exposed via {@link text}, but also provides
+* `toString()` / `valueOf()` for string coercion, so common patterns like
+* `String(result.stdout)` and template-literal interpolation still work.
+*
+* ANSI escape sequences are stripped by default before every comparison
+* (CONVENTIONS D6) — `.text` stays raw. The runner `transform` option remains
+* an escape hatch for application noise not covered by the `{{token}}`
+* grammar.
+*
+* Text operations are **closed** over the type: `.grep(pattern)` returns a
+* `TextAccessor` (not a bare string), preserving the `_expected/`-resolution
+* context and the `transform`, so results are chainable
+* (`result.stdout.grep(a).grep(b)`) and snapshot-able
+* (`expect(result.stdout.grep('users.ts')).toMatch('block.txt')`).
+*
+* Assertions go through `expect()` matchers: `expect(result.stdout).toContain(...)`
+* and `expect(result.stdout).toMatch('name.txt')` (resolved against
+* `_expected/<name>`, flat — with `{{token}}` support, CONVENTIONS D4).
+*/
+var TextAccessor = class TextAccessor {
+	/** @internal Ref-capture scope shared by the current spec execution. */
+	captures;
+	/** @internal Stream label used in failure messages ("stdout" / "stderr"). */
+	streamName;
+	/** @internal Test-file directory — fixture resolution root for matchers. */
+	testDir;
+	/** The raw captured text (never transformed, ANSI preserved). */
+	text;
+	/** @internal Normaliser applied before comparisons, never to fixtures. */
+	transform;
+	constructor(value, streamName, testDir, options = {}) {
+		this.text = value;
+		this.streamName = streamName;
+		this.testDir = testDir;
+		this.transform = options.transform;
+		this.captures = options.captures ?? new CaptureScope();
+	}
+	/** @internal The text as compared by matchers — ANSI stripped, transform applied. */
+	get comparableText() {
+		const stripped = stripAnsiCodes(this.text);
+		return this.transform ? this.transform(stripped) : stripped;
+	}
+	/**
+	* Keep only the blank-line-separated blocks of the text that contain
+	* `pattern` (how linter/compiler output is structured), returned as a new
+	* `TextAccessor` — the same subject type, so the result is chainable and
+	* snapshot-able. The scalpel for probing large tool outputs; snapshot the
+	* whole surface by default, reach for `.grep()` for targeted checks.
+	*/
+	grep(pattern) {
+		return new TextAccessor(grep(this.text, pattern), this.streamName, this.testDir, {
+			captures: this.captures,
+			transform: this.transform
+		});
+	}
+	toString() {
+		return this.text;
+	}
+	valueOf() {
+		return this.text;
+	}
+};
+//#endregion
+//#region src/model/matching/structural.ts
 /**
 * Structural comparison engine shared by every fixture matcher.
 *
@@ -528,7 +650,7 @@ function textEquals(expected, actual, scope) {
 	return placeholderStringMatches(expected, actual, scope);
 }
 //#endregion
-//#region src/specification/contracts/queue.ts
+//#region src/model/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
@@ -701,7 +823,7 @@ var ContractQueue = class {
 	}
 };
 //#endregion
-//#region src/specification/timing/pause.ts
+//#region src/model/timing/pause.ts
 /**
 * One answer to "wait" — the only `setTimeout` the model owns.
 *
@@ -716,7 +838,7 @@ async function pause(ms) {
 	});
 }
 //#endregion
-//#region src/specification/contracts/stream.ts
+//#region src/model/contracts/stream.ts
 /**
 * A declared stream, made real — ONE serialisation for all three engines.
 *
@@ -746,7 +868,7 @@ function toReadableStream(body) {
 	} });
 }
 //#endregion
-//#region src/specification/contracts/types.ts
+//#region src/model/contracts/types.ts
 /**
 * The marker that tells a STREAMED body from a value that happens to be an
 * object. A body reaches three different engines (msw's server, msw's worker,
@@ -760,7 +882,7 @@ function isStreamBody(body) {
 	return typeof body === "object" && body !== null && "kind" in body && body.kind === "@jterrazz/test:stream";
 }
 //#endregion
-//#region src/integrations/msw/handlers.ts
+//#region src/seams/msw/handlers.ts
 /**
 * A contract answers the request that was made, never a copy of an earlier one.
 *
@@ -866,7 +988,7 @@ async function observe(request) {
 	};
 }
 //#endregion
-//#region src/integrations/msw/worker.ts
+//#region src/seams/msw/worker.ts
 /**
 * What the runner itself fetches. Everything else a page asks for is the
 * subject's own traffic and answers to its contracts (D7).
@@ -935,7 +1057,7 @@ function resetWorkerContracts() {
 	if (workerInstance !== null) workerInstance.resetHandlers();
 }
 //#endregion
-//#region src/specification/facets/_common/ground.ts
+//#region src/model/chain/ground.ts
 /**
 * The GROUND a row of specs stands on — the naming law of a spec tree.
 *
@@ -958,7 +1080,7 @@ function resetWorkerContracts() {
 /** Goldens: every expected fixture, flat, extension included. */
 const GROUND_EXPECTED = "_expected";
 //#endregion
-//#region src/specification/facets/_common/reporter.ts
+//#region src/model/chain/reporter.ts
 const GREEN = "\x1B[32m";
 const RED = "\x1B[31m";
 const RESET = "\x1B[0m";
@@ -1009,7 +1131,7 @@ function formatStdoutDiff(file, expected, actual, options) {
 	return [...lines, ...rendered].join("\n");
 }
 //#endregion
-//#region src/specification/facets/_common/result/text-assertions.ts
+//#region src/model/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").`);
@@ -1091,94 +1213,7 @@ function isIterable(value) {
 	return value !== null && value !== void 0 && typeof value[Symbol.iterator] === "function";
 }
 //#endregion
-//#region src/specification/facets/_common/result/grep.ts
-/**
-* Extract text blocks from output that contain a pattern.
-* Splits by blank lines (how linter/compiler output is structured),
-* returns only blocks matching the pattern.
-*
-* @example
-* expect(grep(result.stdout, "unused-var.ts")).toContain("no-unused-vars")
-* expect(grep(result.stdout, "valid/sorted.ts")).not.toContain("sort-imports")
-*/
-function grep(output, pattern) {
-	return output.replaceAll(/\u001B\[[0-9;]*m/gu, "").split(/\n\s*\n/u).filter((block) => block.includes(pattern)).join("\n\n");
-}
-//#endregion
-//#region src/specification/facets/_common/result/text.ts
-const ANSI_RE = /\u001B\[[0-9;]*m/gu;
-/** Strip ANSI escape sequences from a string. */
-function stripAnsiCodes(value) {
-	return value.replace(ANSI_RE, "");
-}
-/**
-* Read-only accessor for a captured text handle — THE universal one: stdout,
-* stderr, container logs, and file text all surface as a `TextAccessor`.
-*
-* Backed by a primitive string, exposed via {@link text}, but also provides
-* `toString()` / `valueOf()` for string coercion, so common patterns like
-* `String(result.stdout)` and template-literal interpolation still work.
-*
-* ANSI escape sequences are stripped by default before every comparison
-* (CONVENTIONS D6) — `.text` stays raw. The runner `transform` option remains
-* an escape hatch for application noise not covered by the `{{token}}`
-* grammar.
-*
-* Text operations are **closed** over the type: `.grep(pattern)` returns a
-* `TextAccessor` (not a bare string), preserving the `_expected/`-resolution
-* context and the `transform`, so results are chainable
-* (`result.stdout.grep(a).grep(b)`) and snapshot-able
-* (`expect(result.stdout.grep('users.ts')).toMatch('block.txt')`).
-*
-* Assertions go through `expect()` matchers: `expect(result.stdout).toContain(...)`
-* and `expect(result.stdout).toMatch('name.txt')` (resolved against
-* `_expected/<name>`, flat — with `{{token}}` support, CONVENTIONS D4).
-*/
-var TextAccessor = class TextAccessor {
-	/** @internal Ref-capture scope shared by the current spec execution. */
-	captures;
-	/** @internal Stream label used in failure messages ("stdout" / "stderr"). */
-	streamName;
-	/** @internal Test-file directory — fixture resolution root for matchers. */
-	testDir;
-	/** The raw captured text (never transformed, ANSI preserved). */
-	text;
-	/** @internal Normaliser applied before comparisons, never to fixtures. */
-	transform;
-	constructor(value, streamName, testDir, options = {}) {
-		this.text = value;
-		this.streamName = streamName;
-		this.testDir = testDir;
-		this.transform = options.transform;
-		this.captures = options.captures ?? new CaptureScope();
-	}
-	/** @internal The text as compared by matchers — ANSI stripped, transform applied. */
-	get comparableText() {
-		const stripped = stripAnsiCodes(this.text);
-		return this.transform ? this.transform(stripped) : stripped;
-	}
-	/**
-	* Keep only the blank-line-separated blocks of the text that contain
-	* `pattern` (how linter/compiler output is structured), returned as a new
-	* `TextAccessor` — the same subject type, so the result is chainable and
-	* snapshot-able. The scalpel for probing large tool outputs; snapshot the
-	* whole surface by default, reach for `.grep()` for targeted checks.
-	*/
-	grep(pattern) {
-		return new TextAccessor(grep(this.text, pattern), this.streamName, this.testDir, {
-			captures: this.captures,
-			transform: this.transform
-		});
-	}
-	toString() {
-		return this.text;
-	}
-	valueOf() {
-		return this.text;
-	}
-};
-//#endregion
-//#region src/specification/facets/website/ambiguity.ts
+//#region src/model/elements/ambiguity.ts
 /**
 * The ambiguity refusal — CONVENTIONS W3.
 *
@@ -1232,8 +1267,9 @@ const CONTEXT_LANDMARKS = {
 };
 /**
 * 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.
+* `within(navigation(), link('Articles', { exact: false }))`. The error speaks
+* the vocabulary the author wrote, never playwright's — so the option appears
+* only when the AUTHOR stated one, whichever way.
 */
 function formatElement(element) {
 	const bare = formatBare(element);
@@ -1242,7 +1278,7 @@ function formatElement(element) {
 function formatBare(element) {
 	const args = [];
 	if (element.name !== void 0) args.push(JSON.stringify(element.name));
-	if (element.exact) args.push("{ exact: true }");
+	if (element.exact !== void 0) args.push(`{ exact: ${String(element.exact)} }`);
 	return `${CONSTRUCTORS[element.kind]}(${args.join(", ")})`;
 }
 /** `1. <a href="/articles">Articles</a>  in <nav>` — one evidence line per candidate. */
@@ -1278,7 +1314,7 @@ function formatFixes(element, matches) {
 		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) {
+	if (element.exact === false && 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,
@@ -1318,11 +1354,109 @@ function describeAmbiguity(options) {
 		"Disambiguate with one of:",
 		...fixes,
 		"",
-		"Docs: docs/14-website.md#designating-exactly-one-element (CONVENTIONS W3)"
+		"Docs: docs/13-elements.md#designating-exactly-one-element (CONVENTIONS W3)"
 	].join("\n");
 }
 //#endregion
-//#region src/integrations/vitest-browser/vitest-browser.adapter.ts
+//#region src/model/elements/substring-warning.ts
+/**
+* The transitional warning for a name that matches only as a SUBSTRING.
+*
+* Until 16.0 a descriptor's name matched any element whose accessible name
+* CONTAINED it, so `link('Articles')` also designated "Read Articles" — and a
+* test could pass for years against the wrong element without anyone noticing,
+* because the wrong element was usually next to the right one. Exact is the
+* default now.
+*
+* A lint rule cannot carry this: whether a name matched whole or in part is a
+* fact about a RUN, and a verdict fed by a previous run's artefact is not
+* deterministic. So it is a runtime warning, printed by the adapter that did
+* the looking, at the moment it has both answers in hand — nothing found under
+* exact, something found under substring.
+*
+* It is printed ONCE per descriptor per process: a scenario that clicks the
+* same link in ten tests has one thing to fix, not ten lines to read.
+*/
+/** How long the window lasts, stated in the message itself. */
+const WINDOW = "through 16.x";
+/** Descriptors already reported in this process. */
+const reported = /* @__PURE__ */ new Set();
+/** The identity a descriptor is deduplicated by — kind, name, and its scope chain. */
+function identityOf(element) {
+	const own = `${element.kind}:${element.name ?? ""}`;
+	return element.scope === void 0 ? own : `${identityOf(element.scope)}>${own}`;
+}
+/**
+* Report that `element` designated nothing as a whole name, but would have
+* designated something as a substring. Returns whether a line was printed,
+* which is what the adapters' own tests assert on.
+*/
+function warnSubstringOnly(element, where, found) {
+	const identity = identityOf(element);
+	if (reported.has(identity)) return false;
+	reported.add(identity);
+	const spelling = found === void 0 ? "" : ` The name to write is '${found.replaceAll(/\s+/gu, " ").trim()}'.`;
+	console.warn(`@jterrazz/test: ${element.kind}('${element.name ?? ""}') matched nothing as a whole accessible name, and matched only as a SUBSTRING of a longer one (${where}).${spelling} Names are exact from 16.0: write the name in full, scope it with \`within(…)\`, or state \`{ exact: false }\` to keep the old behaviour. The substring is still resolved, with this warning, ${WINDOW}; gone in 17.0, where the same descriptor is simply not found.`);
+	return true;
+}
+/**
+* The descriptor to retry with, LEVEL by level, or `undefined` when nothing
+* would change.
+*
+* Every level of the chain is asked the same question the target is asked —
+* `within(button('Proof of authorship'), content('Verified'))` against a
+* button named "Proof of authorship Verified" failed on the SCOPE, and a
+* warning that only ever widened the target printed nothing at all. The chain
+* is walked outside-in and rebuilt as it goes, since an inner level's answer
+* is meaningless under a scope that designates nothing.
+*
+* A level that states an `exact` of its own is left alone: an author who wrote
+* `{ exact: false }` chose the substring, and one who wrote `{ exact: true }`
+* was already exact.
+*
+* Asked BEFORE the action, not after it fails: a verb waits its whole
+* actionability budget, which is the test's own budget, so a retry afterwards
+* never runs — the test is already over. The probes are counts, which wait for
+* nothing, and the common case (the name matches whole) costs one per level.
+*/
+async function widenedForWindow(element, where, probe) {
+	const chain = [];
+	for (let level = element; level; level = level.scope) chain.unshift(level);
+	let rebuilt;
+	let widened = false;
+	for (const level of chain) {
+		const candidate = {
+			...level,
+			...rebuilt === void 0 ? {} : { scope: rebuilt }
+		};
+		const loose = await widenedLevel(candidate, where, probe);
+		widened ||= loose !== void 0;
+		rebuilt = loose ?? candidate;
+	}
+	return widened ? rebuilt : void 0;
+}
+/**
+* The one level, widened and warned about, or `undefined` when it designates
+* something already, states its own `exact`, carries no name, or would
+* designate nothing either way.
+*/
+async function widenedLevel(candidate, where, probe) {
+	if (candidate.exact !== void 0 || candidate.name === void 0) return;
+	try {
+		if (await probe.count(candidate) > 0) return;
+		const loose = {
+			...candidate,
+			exact: false
+		};
+		if (await probe.count(loose) !== 1) return;
+		warnSubstringOnly(candidate, where, await probe.nameOf(loose));
+		return loose;
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/seams/vitest-browser/vitest-browser.adapter.ts
 /**
 * The browser-mode adapter — the component facet's half of the one element
 * vocabulary.
@@ -1343,6 +1477,29 @@ const MAX_REPORTED_MATCHES = 10;
 /** The landmark ancestors the ambiguity evidence names. */
 const LANDMARKS = "nav, header, footer, main, aside, section, form, [role]";
 /**
+* The roles a FIELD can carry — what `field('Name')` designates.
+*
+* A field is named by its ACCESSIBLE name, not by the text of the label
+* element that happens to wrap it: `<label><span>Channel</span><select>…` has
+* a label whose text carries every option of the select, while the control's
+* accessible name is `Channel` — which is what the ARIA tree shows and what a
+* screen reader reads. Resolving by label text alone made the ordinary
+* wrapping-label form unreachable under the 16.0 whole-name default.
+*
+* The label-text locator stays in the union for the controls ARIA gives no
+* role at all (a date or colour input), which nothing else would find.
+*/
+const FIELD_ROLES = [
+	"checkbox",
+	"combobox",
+	"radio",
+	"searchbox",
+	"slider",
+	"spinbutton",
+	"switch",
+	"textbox"
+];
+/**
 * 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
@@ -1351,9 +1508,16 @@ const LANDMARKS = "nav, header, footer, main, aside, section, form, [role]";
 */
 function locate(root, element) {
 	const scope = element.scope ? locate(root, element.scope) : root;
-	const exact = element.exact ?? false;
+	const exact = element.exact ?? true;
 	const name = element.name ?? "";
-	if (element.kind === "field") return scope.getByLabelText(name, { exact });
+	if (element.kind === "field") {
+		let field = scope.getByLabelText(name, { exact });
+		for (const role of FIELD_ROLES) field = field.or(scope.getByRole(role, {
+			exact,
+			name
+		}));
+		return field;
+	}
 	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 } : {
@@ -1385,6 +1549,14 @@ function ambiguousLevel(element) {
 	for (const level of chain.slice(0, -1)) if (locate(page, level).elements().length > 1) return level;
 	return element;
 }
+/** What the transitional window may ask of the mounted page. */
+const PROBE = {
+	count: async (element) => await Promise.resolve(locate(page, element).elements().length),
+	nameOf: async (element) => {
+		const [match] = candidates(locate(page, element));
+		return await Promise.resolve(match?.accessibleName ?? match?.text);
+	}
+};
 /**
 * Run one visitor action, turning "more than one match" into the W3 refusal.
 * The ambiguous LEVEL is identified first: a scope matching several landmarks
@@ -1392,12 +1564,13 @@ function ambiguousLevel(element) {
 * wrong descriptor.
 */
 async function act(element, action) {
-	const locator = locate(page, element);
+	const target = await widenedForWindow(element, globalThis.location.href, PROBE) ?? element;
+	const locator = locate(page, target);
 	try {
 		return await action(locator);
 	} catch (error) {
 		if (locator.elements().length <= 1) throw error;
-		const culprit = ambiguousLevel(element);
+		const culprit = ambiguousLevel(target);
 		const matches = candidates(locate(page, culprit));
 		const url = globalThis.location.href;
 		throw new AmbiguousElementError(describeAmbiguity({
@@ -1584,7 +1757,7 @@ function mountDom(mount) {
 	};
 }
 //#endregion
-//#region src/integrations/vitest-browser/golden.ts
+//#region src/seams/vitest-browser/golden.ts
 /** Update mode crosses the seam as a provided value, never as an env read. */
 function updating() {
 	return inject("update") === true;
@@ -1679,7 +1852,7 @@ const nodeOnlyClass = (name) => function NodeOnly() {
 	return refuse(name);
 };
 //#endregion
-//#region src/integrations/vitest-browser/page-runtime.ts
+//#region src/seams/vitest-browser/page-runtime.ts
 /**
 * The runner, as the page reaches it.
 *
@@ -1728,7 +1901,7 @@ function projectWrapper() {
 	return typeof wrap === "function" ? wrap : void 0;
 }
 //#endregion
-//#region src/specification/facets/component/rendered-text.ts
+//#region src/facets/component/rendered-text.ts
 /**
 * A stream captured INSIDE the page.
 *
@@ -1743,7 +1916,7 @@ var RenderedText = class extends TextAccessor {
 	capturedInPage = true;
 };
 //#endregion
-//#region src/specification/facets/component/component.result.ts
+//#region src/facets/component/component.result.ts
 /**
 * What a render resolves to — the component as the page saw it, after the
 * scenario ran.
@@ -1773,7 +1946,7 @@ var RenderResult = class {
 	}
 };
 //#endregion
-//#region src/specification/facets/component/component.chain.ts
+//#region src/facets/component/component.chain.ts
 /** The console methods a render records; everything else is left alone. */
 const CONSOLE_METHODS = [
 	"debug",
@@ -1936,91 +2109,11 @@ function chainOf(state) {
 /** The handle a component test imports. */
 const component = chainOf(EMPTY);
 //#endregion
-//#region src/specification/facets/_common/result/json.ts
-/**
-* Read-only accessor for a JSON payload parsed from a text stream (stdout).
-*
-* Lazily parses the JSON on first use; parse errors are deferred until the
-* value is read so that callers can still read the raw stream text without
-* triggering a throw.
-*
-* ANSI escape sequences are stripped by default before `JSON.parse`
-* (CONVENTIONS D6). When a `transform` is configured on the spec runner, it
-* runs on the stripped text — an escape hatch for application noise not
-* covered by the `{{token}}` grammar.
-*
-* Assertions go through `expect()`: `expect(result.json).toMatch('name.json')`
-* (deep-equal against `_expected/<name>`, with `{{placeholder}}` support).
-*/
-var JsonAccessor = class {
-	/** @internal Ref-capture scope shared by the current spec execution. */
-	captures;
-	/** @internal */
-	rawText;
-	/** @internal Test-file directory — fixture resolution root for matchers. */
-	testDir;
-	/** @internal */
-	transform;
-	constructor(rawText, testDir, transform, captures) {
-		this.rawText = rawText;
-		this.testDir = testDir;
-		this.transform = transform;
-		this.captures = captures ?? new CaptureScope();
-	}
-	/**
-	* The parsed JSON value. Throws if the text is not valid JSON.
-	*
-	* `Value` is `unknown` unless the subject that produced this accessor
-	* knows better — `.call<T>()` does, and hands its T straight through so a
-	* one-field reading needs no cast in the test.
-	*/
-	get value() {
-		const stripped = stripAnsiCodes(this.rawText);
-		const source = this.transform ? this.transform(stripped) : stripped;
-		try {
-			return JSON.parse(source);
-		} catch {
-			const preview = source.slice(0, 200);
-			throw new Error(`stdout is not valid JSON: ${preview}`);
-		}
-	}
-};
-//#endregion
-//#region src/specification/facets/_common/result/table.ts
-/**
-* Read-only accessor for a database table after a specification run.
-*
-* Assertions go through `expect()` (async — they query the database):
-*
-*     await expect(result.table('users', { database: 'db' })).toMatchRows({
-*         columns: ['name'],
-*         rows: [['Alice']],
-*     });
-*     await expect(result.table('users', { database: 'db' })).toBeEmpty();
-*/
-var TableAccessor = class {
-	/** @internal Ref-capture scope shared by the current spec execution. */
-	captures;
-	/** @internal */
-	db;
-	/** The table name this accessor reads. */
-	name;
-	constructor(name, db, captures) {
-		this.name = name;
-		this.db = db;
-		this.captures = captures ?? new CaptureScope();
-	}
-	/** @internal Query the table — used by the toMatchRows / toBeEmpty matchers. */
-	async query(columns) {
-		return await this.db.query(this.name, columns);
-	}
-};
-//#endregion
-//#region src/specification/facets/website/elements.ts
+//#region src/model/elements/elements.ts
 const named = (kind) => (name, options) => ({
 	kind,
 	name,
-	...options?.exact ? { exact: true } : {}
+	...options?.exact === void 0 ? {} : { exact: options.exact }
 });
 /** A button (or element with the button role), by accessible name. */
 const button = named("button");
@@ -2040,7 +2133,7 @@ const testId = (id) => ({
 const landmark = (kind) => (name, options) => ({
 	kind,
 	...name === void 0 ? {} : { name },
-	...options?.exact ? { exact: true } : {}
+	...options?.exact === void 0 ? {} : { exact: options.exact }
 });
 /** The `banner` landmark — the page header. */
 const banner = landmark("banner");
@@ -2158,7 +2251,7 @@ const valued = (element, value) => ({
 	value
 });
 //#endregion
-//#region src/specification/contracts/filters.ts
+//#region src/model/contracts/filters.ts
 /** Does an observed text satisfy a declared {@link TextFilter}? */
 function matchesText(filter, actual) {
 	if (filter === void 0) return true;
@@ -2167,7 +2260,7 @@ function matchesText(filter, actual) {
 	return structuralEquals(filter, actual, new CaptureScope());
 }
 //#endregion
-//#region src/integrations/anthropic/anthropic.ts
+//#region src/seams/anthropic/anthropic.ts
 const ANTHROPIC_MESSAGES_URL = "https://api.anthropic.com/v1/messages";
 function matchesFilter(body, filter) {
 	if (!matchesText(filter.model, body?.model ?? "")) return false;
@@ -2258,7 +2351,7 @@ const anthropic = {
 	}
 };
 //#endregion
-//#region src/specification/contracts/http.ts
+//#region src/model/contracts/http.ts
 function wrapJson(data) {
 	return {
 		status: 200,
@@ -2447,7 +2540,7 @@ const http = {
 	}
 };
 //#endregion
-//#region src/integrations/openai/openai.ts
+//#region src/seams/openai/openai.ts
 const OPENAI_CHAT_URL = "https://api.openai.com/v1/chat/completions";
 const OPENAI_RESPONSES_URL = "https://api.openai.com/v1/responses";
 function matchesChatFilter(body, filter) {
@@ -2604,19 +2697,12 @@ const openai = {
 	}
 };
 //#endregion
-//#region src/vitest/mock-of.ts
+//#region src/model/doubles/mock-of.ts
 function mockOf(options) {
 	return options?.deep === false ? mock() : mockDeep();
 }
 //#endregion
-//#region src/vitest/mock-of-date.ts
-/**
-* Freeze or reset the global Date for deterministic time-dependent tests.
-* Wraps the `mockdate` package.
-*/
-const mockOfDate = MockDatePackage;
-//#endregion
-//#region src/vitest/clock.ts
+//#region src/model/clock/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);
@@ -2683,7 +2769,7 @@ const clock = {
 	}
 };
 //#endregion
-//#region src/specification/assertions/required.ts
+//#region src/model/assertions/required.ts
 /**
 * The value, or a failure that says what was missing and why it mattered.
 *
@@ -2703,7 +2789,7 @@ function required(value, why) {
 	return value;
 }
 //#endregion
-//#region src/specification/assertions/wait-until.ts
+//#region src/model/assertions/wait-until.ts
 const DEFAULT_TIMEOUT_MS = 5e3;
 const DEFAULT_INTERVAL_MS = 50;
 /**
@@ -2768,21 +2854,6 @@ const ProcessHandle = nodeOnlyClass("ProcessHandle");
 const postgres = () => refuse("postgres()");
 const redis = () => refuse("redis()");
 const sqlite = () => refuse("sqlite()");
-const ContainerAccessor = nodeOnlyClass("ContainerAccessor");
-const findContainersByLabel = () => refuse("findContainersByLabel()");
-const inspectContainer = () => refuse("inspectContainer()");
-const removeContainers = () => refuse("removeContainers()");
-const Orchestrator = nodeOnlyClass("Orchestrator");
-const BaseResult = nodeOnlyClass("BaseResult");
-const CallResult = nodeOnlyClass("CallResult");
-const CliResult = nodeOnlyClass("CliResult");
-const DirectoryAccessor = nodeOnlyClass("DirectoryAccessor");
-const FetchResult = nodeOnlyClass("FetchResult");
-const FilesystemAccessor = nodeOnlyClass("FilesystemAccessor");
-const HttpResult = nodeOnlyClass("HttpResult");
-const PageResult = nodeOnlyClass("PageResult");
-const ResponseAccessor = nodeOnlyClass("ResponseAccessor");
-const ScreenResult = nodeOnlyClass("ScreenResult");
 /**
 * `text()` is real here: only its anchor differs. Under node the accessor
 * remembers the caller's directory so a golden resolves against it; in a page
@@ -2793,4 +2864,4 @@ function text(value) {
 	return new TextAccessor(value, "text", "");
 }
 //#endregion
-export { BaseResult, CallResult, CliResult, ContainerAccessor, DirectoryAccessor, FetchResult, FilesystemAccessor, HttpResult, JsonAccessor, Matcher, Orchestrator, PageResult, ProcessHandle, ResponseAccessor, ScreenResult, TableAccessor, TextAccessor, anthropic, banner, button, clock, complementary, component, content, contentinfo, defineContract, defineContracts, dialog, disabled, enabled, field, findContainersByLabel, focused, form, heading, http, inspectContainer, intercept, link, listitem, main, match, mockOf, mockOfDate, navigation, openai, option, postgres, process, redis, region, removeContainers, required, row, search, selected, specification, sqlite, status, table, testId, text, valued, waitUntil, within };
+export { Matcher, ProcessHandle, anthropic, banner, button, clock, complementary, component, content, contentinfo, defineContract, defineContracts, dialog, disabled, enabled, field, focused, form, heading, http, intercept, link, listitem, main, match, mockOf, navigation, openai, option, postgres, process, redis, region, required, row, search, selected, specification, sqlite, status, table, testId, text, valued, waitUntil, within };