@jterrazz/test 10.0.0 → 11.0.0

package/dist/index.js

@@ -1,13 +1,16 @@
-import { i as match, n as Matcher, r as TOKEN_KINDS, t as CaptureScope } from "./match.js";
-import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { i as match, n as Matcher, t as CaptureScope } from "./match.js";
+import { a as isContract, c as mergeTextPreservingPlaceholders, d as structuralSubset, f as textEquals, i as defineContracts, l as renderExpected, n as contractsOf, o as isContracts, r as defineContract, s as mergePreservingPlaceholders, t as ContractQueue, u as structuralEquals } from "./queue.js";
+import { closeSync, copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, realpathSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { parse } from "yaml";
-import { execSync, spawn, spawnSync } from "node:child_process";
+import { execFile, execSync, spawn, spawnSync } from "node:child_process";
 import { Client } from "pg";
 import { readdir } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { tmpdir } from "node:os";
-import { createServer } from "node:net";
+import { createServer } from "node:http";
+import { createServer as createServer$1 } from "node:net";
+import { promisify } from "node:util";
 import Database from "better-sqlite3";
 import { mockDeep } from "vitest-mock-extended";
 import MockDatePackage from "mockdate";
@@ -518,289 +521,6 @@ function isJsonLike(text) {
 	}
 }
 //#endregion
-//#region src/core/matching/structural.ts
-/**
-* Structural comparison engine shared by every fixture matcher.
-*
-* Handles three kinds of "expected" values:
-* - plain JSON values → strict deep equality
-* - {@link Matcher} instances (code-side `match.*`)
-* - strings containing `{{placeholder}}` forms (file-side fixtures)
-*
-* One unified `{{token}}` grammar (CONVENTIONS D4) — the same vocabulary
-* works in `expected/*.http` (body and headers), `expected/*.json`, and
-* text snapshots (`expected/*.txt`).
-*
-* Ref captures (`match.ref(name)` / `{{type#name}}`) are recorded in the
-* {@link CaptureScope} supplied by the caller.
-*/
-const UUID_SOURCE = "[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}";
-const ULID_SOURCE = "[0-9A-HJKMNP-TV-Z]{26}";
-const ISO8601_SOURCE = String.raw`\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})`;
-const DATE_SOURCE = String.raw`\d{4}-\d{2}-\d{2}`;
-const TIME_SOURCE = String.raw`\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?`;
-const DURATION_SOURCE = String.raw`\d+(?:\.\d+)?(?:ms|s|m|h)`;
-const NUMBER_SOURCE = String.raw`-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?`;
-const INT_SOURCE = String.raw`-?\d+`;
-const FLOAT_SOURCE = String.raw`-?\d+\.\d+`;
-const SEMVER_SOURCE = String.raw`\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?`;
-const SHA_SOURCE = "[0-9a-f]{7,64}";
-const HEX_SOURCE = "[0-9a-fA-F]+";
-const BASE64_SOURCE = "[A-Za-z0-9+/]+={0,2}";
-const PORT_SOURCE = String.raw`(?:6553[0-5]|655[0-2]\d|65[0-4]\d{2}|6[0-4]\d{3}|[1-5]\d{4}|\d{1,4})`;
-const IP_OCTET = String.raw`(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)`;
-const IP_SOURCE = String.raw`(?:${IP_OCTET}\.){3}${IP_OCTET}`;
-const URL_SOURCE = String.raw`https?:\/\/[^\s"'<>]+`;
-const EMBEDDED_SOURCES = {
-	base64: BASE64_SOURCE,
-	date: DATE_SOURCE,
-	duration: DURATION_SOURCE,
-	email: String.raw`[^\s@"'<>]+@[^\s@"'<>]+\.[^\s@"'<>]+`,
-	float: FLOAT_SOURCE,
-	hex: HEX_SOURCE,
-	int: INT_SOURCE,
-	ip: IP_SOURCE,
-	iso8601: ISO8601_SOURCE,
-	number: NUMBER_SOURCE,
-	path: String.raw`\.{0,2}\/[^\s"'<>]*`,
-	port: PORT_SOURCE,
-	semver: SEMVER_SOURCE,
-	sha: SHA_SOURCE,
-	time: TIME_SOURCE,
-	ulid: ULID_SOURCE,
-	url: URL_SOURCE,
-	uuid: UUID_SOURCE
-};
-const wholeRe = (source) => new RegExp(`^(?:${source})$`);
-const WHOLE_RES = Object.fromEntries(Object.entries(EMBEDDED_SOURCES).map(([kind, source]) => [kind, wholeRe(source)]));
-const PLACEHOLDER_RE = new RegExp(String.raw`\{\{(?<kind>${[...TOKEN_KINDS].sort((a, b) => b.length - a.length).join("|")})(?:#(?<ref>[\w.-]+))?\}\}`, "g");
-/** Whether a fixture string contains at least one `{{placeholder}}`. */
-function hasPlaceholders(value) {
-	PLACEHOLDER_RE.lastIndex = 0;
-	return PLACEHOLDER_RE.test(value);
-}
-/** Key-order-independent stringification for captured-object comparison. */
-function stableStringify(value) {
-	if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(",")}]`;
-	if (value !== null && typeof value === "object") return `{${Object.entries(value).sort(([a], [b]) => a < b ? -1 : 1).map(([key, item]) => `${JSON.stringify(key)}:${stableStringify(item)}`).join(",")}}`;
-	return JSON.stringify(value) ?? "undefined";
-}
-function capturedEquals(a, b) {
-	if (Object.is(a, b)) return true;
-	if (typeof a === "number" && typeof b === "string" || typeof a === "string" && typeof b === "number") return String(a) === String(b);
-	if (a !== null && b !== null && typeof a === "object" && typeof b === "object") return stableStringify(a) === stableStringify(b);
-	return false;
-}
-function recordRef(name, actual, scope) {
-	if (scope.has(name)) return capturedEquals(scope.get(name), actual);
-	scope.set(name, actual);
-	return true;
-}
-function isPortValue(value) {
-	return Number.isInteger(value) && value >= 0 && value <= 65535;
-}
-function kindMatches(kind, actual, scope) {
-	switch (kind) {
-		case "any": return true;
-		case "float":
-			if (typeof actual === "number") return Number.isFinite(actual);
-			return typeof actual === "string" && WHOLE_RES.float.test(actual);
-		case "int":
-			if (typeof actual === "number") return Number.isInteger(actual);
-			return typeof actual === "string" && WHOLE_RES.int.test(actual);
-		case "number":
-			if (typeof actual === "number") return Number.isFinite(actual);
-			return typeof actual === "string" && WHOLE_RES.number.test(actual);
-		case "port":
-			if (typeof actual === "number") return isPortValue(actual);
-			return typeof actual === "string" && WHOLE_RES.port.test(actual) && isPortValue(Number(actual));
-		case "string": return typeof actual === "string";
-		case "workdir": return typeof actual === "string" && scope.workdir !== void 0 ? actual === scope.workdir : false;
-		default: {
-			const re = WHOLE_RES[kind];
-			return re !== void 0 && typeof actual === "string" && re.test(actual);
-		}
-	}
-}
-function matcherMatches(matcher, actual, scope) {
-	if (matcher.kind === "regex") return typeof actual === "string" && matcher.regex.test(actual);
-	if (matcher.kind === "ref") {
-		if (matcher.notRef && scope.has(matcher.notRef) && capturedEquals(scope.get(matcher.notRef), actual)) return false;
-		return recordRef(matcher.refName, actual, scope);
-	}
-	return kindMatches(matcher.kind, actual, scope);
-}
-function placeholderSource(kind, scope) {
-	if (kind === "workdir") return scope.workdir === void 0 ? "(?!)" : escapeRegExp(scope.workdir);
-	const source = EMBEDDED_SOURCES[kind];
-	if (source) return source;
-	return kind === "any" ? String.raw`[\s\S]*?` : String.raw`[^\n]*?`;
-}
-function escapeRegExp(text) {
-	return text.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
-}
-function parsePlaceholderString(expected, scope) {
-	PLACEHOLDER_RE.lastIndex = 0;
-	const refs = [];
-	let pattern = "^";
-	let lastIndex = 0;
-	let single = null;
-	let count = 0;
-	for (const found of expected.matchAll(PLACEHOLDER_RE)) {
-		const kind = found.groups.kind;
-		const ref = found.groups.ref;
-		pattern += escapeRegExp(expected.slice(lastIndex, found.index));
-		pattern += `(${placeholderSource(kind, scope)})`;
-		refs.push({
-			index: count,
-			kind,
-			ref
-		});
-		count++;
-		lastIndex = found.index + found[0].length;
-		if (found.index === 0 && found[0].length === expected.length) single = {
-			kind,
-			ref
-		};
-	}
-	pattern += `${escapeRegExp(expected.slice(lastIndex))}$`;
-	return {
-		pattern: new RegExp(pattern),
-		refs,
-		single
-	};
-}
-function placeholderStringMatches(expected, actual, scope) {
-	const parsed = parsePlaceholderString(expected, scope);
-	if (parsed.single) {
-		if (!kindMatches(parsed.single.kind, actual, scope)) return false;
-		if (parsed.single.ref) return recordRef(parsed.single.ref, actual, scope);
-		return true;
-	}
-	if (typeof actual !== "string" && typeof actual !== "number") return false;
-	const text = String(actual);
-	const found = parsed.pattern.exec(text);
-	if (!found) return false;
-	for (const entry of parsed.refs) {
-		if (!entry.ref) continue;
-		if (!recordRef(entry.ref, found[entry.index + 1], scope)) return false;
-	}
-	return true;
-}
-function isPlainObject(value) {
-	return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-/**
-* Deep structural equality with matcher / placeholder support. Ref captures
-* are recorded in `scope` in traversal order (arrays left-to-right, object
-* keys in expected-key order).
-*/
-function structuralEquals(expected, actual, scope) {
-	if (expected instanceof Matcher) return matcherMatches(expected, actual, scope);
-	if (typeof expected === "string" && hasPlaceholders(expected)) return placeholderStringMatches(expected, actual, scope);
-	if (Array.isArray(expected)) {
-		if (!Array.isArray(actual) || actual.length !== expected.length) return false;
-		return expected.every((item, i) => structuralEquals(item, actual[i], scope));
-	}
-	if (isPlainObject(expected)) {
-		if (!isPlainObject(actual)) return false;
-		const expectedKeys = Object.keys(expected);
-		const actualKeys = Object.keys(actual);
-		if (expectedKeys.length !== actualKeys.length) return false;
-		return expectedKeys.every((key) => key in actual && structuralEquals(expected[key], actual[key], scope));
-	}
-	return Object.is(expected, actual);
-}
-/**
-* Deep structural SUBSET match (toMatchObject-style) with matcher /
-* placeholder support. Plain objects match when every expected key is present
-* and recursively subset-matches — the actual value may carry extra keys.
-* Arrays require equal length with each element subset-matched. Leaves fall
-* back to {@link structuralEquals} semantics (matchers, placeholders, strict
-* equality). Used by request-body filters on intercept triggers.
-*/
-function structuralSubset(expected, actual, scope) {
-	if (expected instanceof Matcher) return matcherMatches(expected, actual, scope);
-	if (typeof expected === "string" && hasPlaceholders(expected)) return placeholderStringMatches(expected, actual, scope);
-	if (Array.isArray(expected)) {
-		if (!Array.isArray(actual) || actual.length !== expected.length) return false;
-		return expected.every((item, i) => structuralSubset(item, actual[i], scope));
-	}
-	if (isPlainObject(expected)) {
-		if (!isPlainObject(actual)) return false;
-		return Object.keys(expected).every((key) => key in actual && structuralSubset(expected[key], actual[key], scope));
-	}
-	return Object.is(expected, actual);
-}
-/**
-* Multi-line text comparison with `{{token}}` support — used by text
-* snapshots (`expected/*.txt`). Without placeholders this is strict equality.
-*/
-function textEquals(expected, actual, scope) {
-	if (!hasPlaceholders(expected)) return expected === actual;
-	return placeholderStringMatches(expected, actual, scope);
-}
-/**
-* Render an expected value for failure diffs and serialization: Matcher
-* instances become their placeholder text, everything else is untouched.
-*/
-function renderExpected(value) {
-	if (value instanceof Matcher) return value.toString();
-	if (Array.isArray(value)) return value.map((item) => renderExpected(item));
-	if (isPlainObject(value)) return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, renderExpected(item)]));
-	return value;
-}
-/**
-* Substitute the framework-known cwd (`workdir`) for its `{{workdir}}` token in
-* every string leaf of a structured value. The structural mirror of the text
-* path's `actual.replaceAll(workdir, '{{workdir}}')` — so a golden written under
-* `TEST_UPDATE=1` stores the token, not a run-specific temp path (CONVENTIONS
-* D5). A no-op when `workdir` is undefined (no cwd, e.g. api/jobs mode).
-*/
-function substituteWorkdirDeep(value, workdir) {
-	if (typeof value === "string") return value.replaceAll(workdir, "{{workdir}}");
-	if (Array.isArray(value)) return value.map((item) => substituteWorkdirDeep(item, workdir));
-	if (isPlainObject(value)) return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, substituteWorkdirDeep(item, workdir)]));
-	return value;
-}
-/**
-* Update-mode merge: rewrite a fixture from the actual output while
-* preserving every segment of the previous fixture that was covered by a
-* placeholder (and still matches the actual value).
-*
-* Token preservation is symmetric with the text path (CONVENTIONS D5): a
-* previous `{{placeholder}}` (including `{{workdir}}`) that still matches the
-* RAW actual value is kept; every other leaf is taken from the actual output
-* with the framework-known cwd substituted back to `{{workdir}}`.
-*/
-function mergePreservingPlaceholders(previous, actual, workdir) {
-	const scope = new CaptureScope(workdir);
-	const subst = (value) => workdir === void 0 ? value : substituteWorkdirDeep(value, workdir);
-	function merge(prev, act) {
-		if (typeof prev === "string" && hasPlaceholders(prev)) return placeholderStringMatches(prev, act, scope) ? prev : subst(act);
-		if (Array.isArray(prev) && Array.isArray(act)) return act.map((item, i) => i < prev.length ? merge(prev[i], item) : subst(item));
-		if (isPlainObject(prev) && isPlainObject(act)) return Object.fromEntries(Object.entries(act).map(([key, item]) => [key, key in prev ? merge(prev[key], item) : subst(item)]));
-		return subst(act);
-	}
-	return merge(previous, actual);
-}
-/**
-* Update-mode merge for text snapshots: line-by-line, a previous line whose
-* placeholders still match the actual line is preserved; every other line is
-* taken from the actual output. Values the framework knows to be dynamic
-* (`{{workdir}}`) are substituted automatically (CONVENTIONS D5).
-*/
-function mergeTextPreservingPlaceholders(previous, actual, scope) {
-	const substituted = scope.workdir === void 0 ? actual : actual.replaceAll(scope.workdir, "{{workdir}}");
-	if (previous === null) return substituted;
-	const prevLines = previous.split("\n");
-	return substituted.split("\n").map((line, i) => {
-		const prev = prevLines[i];
-		if (prev === void 0 || !hasPlaceholders(prev)) return line;
-		return textEquals(prev, line, new CaptureScope(scope.workdir)) || textEquals(prev, actual.split("\n")[i] ?? line, new CaptureScope(scope.workdir)) ? prev : line;
-	}).join("\n");
-}
-//#endregion
 //#region src/core/specification/shared/reporter.ts
 const GREEN = "\x1B[32m";
 const RED = "\x1B[31m";
@@ -1997,6 +1717,30 @@ var HttpResult = class extends BaseResult {
 	}
 };
 //#endregion
+//#region src/core/specification/mobile/result.ts
+/** Result from a `.open()` action — the screen as the device saw it, final state. */
+var ScreenResult = class extends BaseResult {
+	capturedScreen;
+	constructor(options) {
+		super(options);
+		this.capturedScreen = options.screen;
+	}
+	/**
+	* The visible screen texts as one stream, in reading order — the scalpel
+	* for a targeted probe: `expect(result.content).toContain('Bookmarked')`.
+	*/
+	get content() {
+		return new TextAccessor(this.capturedScreen.texts.join("\n"), "content", this.testDir, { captures: this.captures });
+	}
+	/**
+	* The projected accessibility tree as a JSON accessor — the one golden
+	* per screen: `expect(result.screen).toMatch('events.screen.json')`.
+	*/
+	get screen() {
+		return new JsonAccessor(JSON.stringify(this.capturedScreen.tree), this.testDir, void 0, this.captures);
+	}
+};
+//#endregion
 //#region src/core/specification/website/result.ts
 /** Result from a raw `.fetch()` action (robots.txt, sitemaps, redirects). */
 var FetchResult = class extends BaseResult {
@@ -2255,8 +1999,8 @@ function copyPlan(path, testDir, workDir) {
 var SpecificationBuilder = class {
 	commandEnv = {};
 	config;
+	contracts = [];
 	fixtures = [];
-	intercepts = [];
 	requestHeaders = {};
 	seeds = [];
 	testDir;
@@ -2330,36 +2074,22 @@ var SpecificationBuilder = class {
 		};
 		return this;
 	}
-	intercept(triggerOrContracts, maybeResponse) {
+	intercept(requestOrContracts, maybeResponse) {
 		if (this.config.interceptDisabledReason) throw new Error(`.intercept(): ${this.config.interceptDisabledReason}`);
-		if (Array.isArray(triggerOrContracts)) {
-			for (const contract of triggerOrContracts) this.registerIntercept(contract);
+		if ((this.config.baseUrl !== void 0 || this.config.device !== void 0) && !this.config.backend) {
+			const facet = this.config.device === void 0 ? "website" : "mobile";
+			throw new Error(`.intercept(): this runner has no declared backend — add \`backend\` to the specification options (specification.${facet}({ …, backend: { … } })) so the chain's contracts have a stub to serve them.`);
+		}
+		if (Array.isArray(requestOrContracts) || isContracts(requestOrContracts) || isContract(requestOrContracts)) {
+			this.contracts.push(...contractsOf(requestOrContracts));
 			return this;
 		}
-		this.registerIntercept(triggerOrContracts, maybeResponse);
-		return this;
-	}
-	/** Register a single intercept — a contract, or a trigger + response pair. */
-	registerIntercept(triggerOrContract, maybeResponse) {
-		const isContract = "trigger" in triggerOrContract && "response" in triggerOrContract;
-		const trigger = isContract ? triggerOrContract.trigger : triggerOrContract;
-		const response = isContract ? triggerOrContract.response : maybeResponse;
-		if (typeof response === "string") {
-			const slashIndex = response.indexOf("/");
-			if (slashIndex === -1) throw new Error(`.intercept(): file path must be 'adapter/filename.json' (e.g. 'openai/ingest-tech.json'), got '${response}'`);
-			const adapterName = response.slice(0, slashIndex);
-			if (adapterName !== trigger.adapter) throw new Error(`.intercept(): adapter mismatch - trigger uses '${trigger.adapter}' but file path starts with '${adapterName}/'`);
-			const filePath = resolve(this.testDir, "intercepts", response);
-			const data = JSON.parse(readFileSync(filePath, "utf8"));
-			const resolved = trigger.wrap(data);
-			this.intercepts.push({
-				trigger,
-				response: resolved
-			});
-		} else this.intercepts.push({
-			trigger,
-			response
+		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).");
+		this.contracts.push({
+			request: requestOrContracts,
+			response: maybeResponse
 		});
+		return this;
 	}
 	/**
 	* Send the complete request described by `requests/<file>` — first line
@@ -2479,6 +2209,24 @@ var SpecificationBuilder = class {
 		return this.executeSetup(null, () => this.runVisitAction(path, scenario));
 	}
 	/**
+	* Terminate and relaunch the app on the simulator, apply the deep link,
+	* run the scenario, and resolve with the captured final screen — the
+	* projected accessibility tree and the visible texts. One driver session
+	* per runner; every open starts from a deterministic fresh app state.
+	*
+	* @example
+	*   const result = await mobile.open('news://events');
+	*   expect(result.screen).toMatch('events.screen.json');
+	*
+	*   const result = await mobile.open('news://events', async (visitor) => {
+	*       await visitor.tap(button('Enquête Fauci COVID-19'));
+	*       await visitor.see(content('rapports'));
+	*   });
+	*/
+	open(deepLink, scenario) {
+		return this.executeSetup(null, () => this.runOpenAction(deepLink, scenario));
+	}
+	/**
 	* Execute the named job registered via the `jobs` option of
 	* `specification.jobs()` and resolve with the result.
 	*
@@ -2517,17 +2265,18 @@ var SpecificationBuilder = class {
 			cpSync(src, dest, { recursive: true });
 		}
 		let registration = null;
-		if (this.intercepts.length > 0) {
-			const { registerIntercepts } = await import("./intercept.js");
-			registration = await registerIntercepts(this.intercepts);
+		if (this.config.backend) this.config.backend.beginChain(this.contracts);
+		else if (this.contracts.length > 0) {
+			const { registerContracts } = await import("./intercept.js");
+			registration = await registerContracts(this.contracts);
 		}
 		try {
 			const value = await action();
-			const violation = registration?.violation();
+			const violation = registration?.violation() ?? this.config.backend?.violation();
 			if (violation) throw violation;
 			return value;
 		} catch (error) {
-			throw registration?.violation() ?? error;
+			throw registration?.violation() ?? this.config.backend?.violation() ?? error;
 		} finally {
 			registration?.cleanup();
 		}
@@ -2595,6 +2344,7 @@ var SpecificationBuilder = class {
 		const browser = await this.config.browser();
 		const headers = Object.keys(this.requestHeaders).length > 0 ? this.requestHeaders : void 0;
 		const page = await browser.open(`${baseUrl}${path}`, {
+			allowedOrigins: this.config.backendUrl ? [new URL(this.config.backendUrl).origin] : void 0,
 			baseUrl,
 			external: this.config.external ?? "allow",
 			headers,
@@ -2606,6 +2356,19 @@ var SpecificationBuilder = class {
 			testDir: this.testDir
 		});
 	}
+	async runOpenAction(deepLink, scenario) {
+		if (!this.config.device || this.config.bundleId === void 0) throw new Error(".open() requires a device adapter (use specification.mobile())");
+		const screen = await (await this.config.device()).open({
+			bundleId: this.config.bundleId,
+			deepLink,
+			scenario
+		});
+		return new ScreenResult({
+			config: this.config,
+			screen,
+			testDir: this.testDir
+		});
+	}
 	requireBaseUrl(method) {
 		if (!this.config.baseUrl) throw new Error(`.${method}() requires a website under test (use specification.website())`);
 		return this.config.baseUrl;
@@ -2682,6 +2445,14 @@ var SpecificationBuilder = class {
 		});
 	}
 };
+/**
+* The facet-level `.intercept()`: both overloads forwarded to a fresh chain.
+* The pair form is recognised by its second argument — a bare
+* {@link ContractRequest} never arrives alone.
+*/
+function interceptOn(start) {
+	return (contractsOrRequest, response) => response === void 0 ? start().intercept(contractsOrRequest) : start().intercept(contractsOrRequest, response);
+}
 function withDockerTestRunId(config) {
 	if (config.dockerConfig && !config.dockerTestRunId) return {
 		...config,
@@ -2699,7 +2470,7 @@ function createApiFacet(config) {
 		delete: (path) => start().delete(path),
 		get: (path) => start().get(path),
 		headers: (headers) => start().headers(headers),
-		intercept: (triggerOrContracts, response) => Array.isArray(triggerOrContracts) ? start().intercept(triggerOrContracts) : start().intercept(triggerOrContracts, response),
+		intercept: interceptOn(start),
 		post: (path, body) => start().post(path, body),
 		put: (path, body) => start().put(path, body),
 		request: (file) => start().request(file),
@@ -2712,7 +2483,7 @@ function createApiFacet(config) {
 function createJobsFacet(config) {
 	const start = () => new SpecificationBuilder(config, getCallerDir());
 	return {
-		intercept: (triggerOrContracts, response) => Array.isArray(triggerOrContracts) ? start().intercept(triggerOrContracts) : start().intercept(triggerOrContracts, response),
+		intercept: interceptOn(start),
 		seed: (file, options) => start().seed(file, options),
 		trigger: (name) => start().trigger(name)
 	};
@@ -2725,10 +2496,21 @@ function createWebsiteFacet(config) {
 	return {
 		fetch: (path) => start().fetch(path),
 		headers: (headers) => start().headers(headers),
+		intercept: interceptOn(start),
 		visit: (path, scenario) => start().visit(path, scenario)
 	};
 }
 /**
+* Create the `mobile` facet bound to the given adapter configuration.
+*/
+function createMobileFacet(config) {
+	const start = () => new SpecificationBuilder(config, getCallerDir());
+	return {
+		intercept: interceptOn(start),
+		open: (deepLink, scenario) => start().open(deepLink, scenario)
+	};
+}
+/**
 * Create the `cli` facet bound to the given adapter configuration.
 */
 function createCliFacet(config) {
@@ -3423,6 +3205,178 @@ async function startJobs(options) {
 	};
 }
 //#endregion
+//#region src/core/specification/shared/stub-backend.ts
+/**
+* The declared stub backend — a small `node:http` server the website and
+* mobile runners start when their `backend` option is present. It serves the
+* contracts the CURRENT chain declared via `.intercept(...)`: one chain = one
+* terminal action, and the stub resets between chains the way databases do.
+*
+* Selection is the shared {@link ContractQueue} — the same first-matching,
+* `times`-aware queue the MSW engine runs on api/jobs chains. A contract
+* without `times` keeps replying (re-render, retry); `times: n` is spent after
+* n serves.
+*
+* Strictness is the `external: 'block'` analog (CONVENTIONS D7 in spirit): a
+* request matching no contract is answered 501 and RECORDED; once the chain
+* declared at least one contract, the terminal action throws an error
+* enumerating every unmatched request — and every `required` contract that was
+* never requested. Chains with zero contracts leave the stub unguarded —
+* mirroring how MSW stays off without them.
+*
+* Every response (including the 501 and the OPTIONS preflight) carries
+* permissive CORS headers — a website's client-side fetches are cross-origin
+* to the stub by construction.
+*/
+const CORS_METHODS = "GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS";
+const PREFLIGHT_MAX_AGE = "600";
+var StubBackend = class {
+	/** Guarded once the current chain declared at least one contract. */
+	guarded = false;
+	options;
+	queue = new ContractQueue([]);
+	server = null;
+	unmatchedRequests = /* @__PURE__ */ new Map();
+	url = "";
+	constructor(options = {}) {
+		this.options = options;
+	}
+	/** Start the server and resolve with its base URL. */
+	async start() {
+		const server = createServer((request, response) => {
+			this.handle(request, response);
+		});
+		this.server = server;
+		await new Promise((resolve, reject) => {
+			server.once("error", reject);
+			server.listen(this.options.port ?? 0, "127.0.0.1", () => resolve());
+		});
+		const address = server.address();
+		if (address === null || typeof address === "string") throw new Error("stub backend: could not determine the listening port");
+		this.url = `http://127.0.0.1:${address.port}`;
+		return this.url;
+	}
+	/** Stop the server (idempotent). */
+	async stop() {
+		const server = this.server;
+		if (!server) return;
+		this.server = null;
+		server.closeAllConnections();
+		await new Promise((resolve) => {
+			server.close(() => resolve());
+		});
+	}
+	/**
+	* Arm the stub for one chain: the declared contracts replace the previous
+	* chain's wholesale, the queue restarts, and the unmatched log clears —
+	* the reset-between-chains databases already follow.
+	*/
+	beginChain(contracts) {
+		this.guarded = contracts.length > 0;
+		this.queue = new ContractQueue(contracts);
+		this.unmatchedRequests.clear();
+	}
+	/**
+	* The strict failure for the chain, or null. Non-null when the chain
+	* declared at least one contract AND either an unmatched request was
+	* recorded, or a `required` contract was never satisfied. Enumerates every
+	* unmatched request (method, path, count) plus the declared routes, so the
+	* missing contract writes itself.
+	*/
+	violation() {
+		if (!this.guarded) return null;
+		if (this.unmatchedRequests.size === 0) return this.queue.requiredError();
+		const unmatched = [...this.unmatchedRequests.values()].map((entry) => `  - ${entry.method} ${entry.path}${entry.count > 1 ? ` (${entry.count} times)` : ""}`).join("\n");
+		return /* @__PURE__ */ new Error(`Unmatched request(s) hit the declared backend during the chain:\n${unmatched}\nDeclared contracts:\n${this.describeRoutes()}\nEvery backend request of a chain that declares contracts must match one — add a contract for it to the chain's composite.`);
+	}
+	corsHeaders(request) {
+		return {
+			"access-control-allow-headers": request.headers["access-control-request-headers"] ?? "*",
+			"access-control-allow-methods": CORS_METHODS,
+			"access-control-allow-origin": "*",
+			"access-control-max-age": PREFLIGHT_MAX_AGE
+		};
+	}
+	describeRoutes() {
+		const routes = this.queue.declaredRoutes();
+		if (routes.length === 0) return "  (no contracts declared)";
+		return routes.map((route) => `  - ${route}`).join("\n");
+	}
+	async handle(request, response) {
+		const method = (request.method ?? "GET").toUpperCase();
+		const cors = this.corsHeaders(request);
+		if (method === "OPTIONS") {
+			response.writeHead(204, cors);
+			response.end();
+			return;
+		}
+		const headers = {};
+		for (const [name, value] of Object.entries(request.headers)) if (typeof value === "string") headers[name.toLowerCase()] = value;
+		const url = request.url ?? "/";
+		const observed = {
+			body: await readBody(request),
+			headers,
+			method,
+			url
+		};
+		const contract = this.queue.take(observed);
+		if (!contract) {
+			this.record(method, url);
+			response.writeHead(501, {
+				...cors,
+				"content-type": "application/json"
+			});
+			response.end(JSON.stringify({
+				declared: this.queue.declaredRoutes(),
+				error: `@jterrazz/test declared backend: no contract matches ${method} ${url}`
+			}));
+			return;
+		}
+		const reply = typeof contract.response === "function" ? contract.response(observed) : contract.response;
+		if (reply.delay) await new Promise((resolve) => setTimeout(resolve, reply.delay));
+		const status = reply.status ?? 200;
+		const { body } = reply;
+		if (body === null || body === void 0) {
+			response.writeHead(status, {
+				...cors,
+				...reply.headers
+			});
+			response.end();
+			return;
+		}
+		const payload = typeof body === "string" ? body : JSON.stringify(body);
+		const contentType = typeof body === "string" ? "text/plain; charset=utf-8" : "application/json";
+		response.writeHead(status, {
+			...cors,
+			"content-type": contentType,
+			...reply.headers
+		});
+		response.end(payload);
+	}
+	record(method, path) {
+		const key = `${method} ${path}`;
+		const existing = this.unmatchedRequests.get(key);
+		if (existing) existing.count += 1;
+		else this.unmatchedRequests.set(key, {
+			count: 1,
+			method,
+			path
+		});
+	}
+};
+/** Read the request body — parsed JSON when it is JSON, raw text otherwise. */
+async function readBody(request) {
+	const chunks = [];
+	for await (const chunk of request) chunks.push(chunk);
+	const raw = Buffer.concat(chunks).toString("utf8");
+	if (raw.length === 0) return null;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return raw;
+	}
+}
+//#endregion
 //#region src/core/specification/website/serve.adapter.ts
 /** Grace period between SIGTERM and the SIGKILL escalation. */
 const KILL_GRACE_MS = 2e3;
@@ -3432,7 +3386,7 @@ const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /** Ask the OS for a free TCP port. */
 function findFreePort() {
 	return new Promise((resolve, reject) => {
-		const server = createServer();
+		const server = createServer$1();
 		server.listen(0, () => {
 			const address = server.address();
 			if (address === null || typeof address === "string") {
@@ -3458,10 +3412,16 @@ function findFreePort() {
 */
 var ServeAdapter = class {
 	child = null;
+	/** Extra environment injected into the child (e.g. the stub backend URL). */
+	extraEnv;
+	/** The constructor named in error messages — `website`, or `mobile` (appium server). */
+	facet;
 	options;
 	output = "";
 	root;
-	constructor(options, root) {
+	constructor(options, root, facet = "website", extraEnv = {}) {
+		this.extraEnv = extraEnv;
+		this.facet = facet;
 		this.options = options;
 		this.root = root;
 	}
@@ -3476,6 +3436,7 @@ var ServeAdapter = class {
 			detached: process.platform !== "win32",
 			env: {
 				...process.env,
+				...this.extraEnv,
 				PORT: String(port)
 			},
 			shell: true,
@@ -3497,14 +3458,14 @@ var ServeAdapter = class {
 		});
 		const deadline = Date.now() + timeout;
 		for (;;) {
-			if (exited) throw new Error(`specification.website(): server command exited before answering HTTP.\nCommand: ${this.options.command}\nOutput:\n${this.output}`);
+			if (exited) throw new Error(`specification.${this.facet}(): server command exited before answering HTTP.\nCommand: ${this.options.command}\nOutput:\n${this.output}`);
 			try {
 				await fetch(readyUrl, { redirect: "manual" });
 				return baseUrl;
 			} catch {
 				if (Date.now() >= deadline) {
 					await this.stop();
-					throw new Error(`specification.website(): server did not answer on ${readyUrl} within ${timeout}ms.\nCommand: ${this.options.command}\nOutput:\n${this.output}`);
+					throw new Error(`specification.${this.facet}(): server did not answer on ${readyUrl} within ${timeout}ms.\nCommand: ${this.options.command}\nOutput:\n${this.output}`);
 				}
 				await delay(READY_POLL_INTERVAL_MS);
 			}
@@ -3544,16 +3505,184 @@ var ServeAdapter = class {
 	}
 };
 //#endregion
+//#region src/core/specification/mobile/appium-server.ts
+const APPIUM_READY_TIMEOUT_MS = 6e4;
+/**
+* The guidance thrown when the optional peers are missing — the exact fix,
+* mirroring the playwright message on `.visit()`.
+*/
+const APPIUM_INSTALL_HINT = "specification.mobile() requires appium and webdriverio (optional peer dependencies): npm install -D appium webdriverio && npx appium driver install xcuitest";
+/**
+* Start the caller project's appium server as a child process on a free port
+* and wait until `/status` answers. The binary is resolved from the project
+* root's `node_modules/.bin` — appium is an optional peer, so its absence
+* refuses with the exact install command. Process lifecycle (free port via
+* `PORT`, readiness poll, SIGTERM→SIGKILL group escalation on stop) is the
+* serve adapter's — one implementation for every child the framework spawns.
+*/
+async function startAppiumServer(root) {
+	const bin = resolve(root, "node_modules", ".bin", "appium");
+	if (!existsSync(bin)) throw new Error(APPIUM_INSTALL_HINT);
+	const serve = new ServeAdapter({
+		command: `"${bin}" --port "$PORT"`,
+		ready: "/status",
+		timeout: APPIUM_READY_TIMEOUT_MS
+	}, root, "mobile");
+	return {
+		stop: () => serve.stop(),
+		url: await serve.start()
+	};
+}
+//#endregion
+//#region src/core/specification/mobile/simulator.ts
+/**
+* Simulator resolution — `device: { name, os? }` → one booted UDID.
+*
+* The selection logic is pure (`simctl list` JSON in, one device out) so the
+* refusals are unit-testable; only the thin wrappers below shell out to
+* `xcrun`. Zero matches and several matches both refuse with the full device
+* listing — the framework never guesses which simulator a spec meant.
+*/
+const run = promisify(execFile);
+const BOOT_TIMEOUT_MS = 12e4;
+/** `com.apple.CoreSimulator.SimRuntime.iOS-26-5` → `iOS 26.5`. */
+function runtimeLabel(runtime) {
+	const match = /SimRuntime\.(?<platform>[A-Za-z]+)-(?<version>[\d-]+)$/.exec(runtime);
+	return match?.groups ? `${match.groups["platform"]} ${match.groups["version"].replaceAll("-", ".")}` : runtime;
+}
+/** Flatten the per-runtime record into one available-device list. */
+function listSimulators(listJson) {
+	const parsed = JSON.parse(listJson);
+	return Object.entries(parsed.devices).flatMap(([runtime, devices]) => devices.filter((device) => device.isAvailable !== false).map((device) => ({
+		name: device.name,
+		os: runtimeLabel(runtime),
+		state: device.state,
+		udid: device.udid
+	})));
+}
+/** `iOS 26.5` matches `os: 'iOS 26.5'` and the bare version `'26.5'`, case-insensitive. */
+function osMatches(deviceOs, wanted) {
+	const normalized = wanted.toLowerCase();
+	return deviceOs.toLowerCase() === normalized || deviceOs.split(" ")[1] === wanted;
+}
+function formatListing(devices) {
+	return devices.map((device) => `  ${device.name} — ${device.os} (${device.state}) ${device.udid}`).join("\n");
+}
+/**
+* Pick exactly one simulator by name (and OS when given). Zero or several
+* matches refuse with the listing needed to fix the options without opening
+* Xcode.
+*/
+function selectSimulator(listJson, criteria) {
+	const available = listSimulators(listJson);
+	const matches = available.filter((device) => device.name === criteria.name && (criteria.os === void 0 || osMatches(device.os, criteria.os)));
+	const wanted = criteria.os === void 0 ? `"${criteria.name}"` : `"${criteria.name}" on ${criteria.os}`;
+	if (matches.length === 0) throw new Error(`specification.mobile(): no simulator matches ${wanted}.\nAvailable devices:\n${formatListing(available)}`);
+	if (matches.length > 1) throw new Error(`specification.mobile(): ${matches.length} simulators match ${wanted} — add \`os:\` or \`udid:\` to pick one.\nMatched:\n${formatListing(matches)}`);
+	return matches[0];
+}
+/** Resolve `device: { name, os? }` to a UDID via `xcrun simctl`. */
+async function resolveSimulatorUdid(criteria) {
+	const { stdout } = await run("xcrun", [
+		"simctl",
+		"list",
+		"devices",
+		"--json"
+	], { maxBuffer: 16 * 1024 * 1024 });
+	return selectSimulator(stdout, criteria).udid;
+}
+/**
+* Boot the simulator when it is shut down and wait until it reports Booted.
+* Idempotent: booting an already-booted device is tolerated, and
+* `bootstatus -b` returns immediately when the device is up.
+*/
+async function ensureBooted(udid) {
+	try {
+		await run("xcrun", [
+			"simctl",
+			"boot",
+			udid
+		]);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		if (!message.includes("current state: Booted")) throw new Error(`specification.mobile(): could not boot simulator ${udid}.\n${message}`, { cause: error });
+	}
+	await run("xcrun", [
+		"simctl",
+		"bootstatus",
+		udid,
+		"-b"
+	], { timeout: BOOT_TIMEOUT_MS });
+}
+//#endregion
+//#region src/core/specification/mobile/start-mobile.ts
+async function startMobile(options) {
+	const callerDir = getCallerDir();
+	await registerMatchers();
+	const root = resolveRoot(options.root, callerDir);
+	const udid = options.device.udid ?? await resolveSimulatorUdid(options.device);
+	await ensureBooted(udid);
+	const appium = await startAppiumServer(root);
+	let backend = null;
+	let backendUrl;
+	if (options.backend) {
+		backend = new StubBackend({ port: options.backend.port });
+		backendUrl = await backend.start();
+	}
+	let device = null;
+	const getDevice = async () => {
+		if (!device) {
+			const { AppiumAdapter } = await import("./appium.adapter.js");
+			device = new AppiumAdapter({
+				serverUrl: appium.url,
+				udid
+			});
+		}
+		return device;
+	};
+	const config = {
+		backend: backend ?? void 0,
+		backendUrl,
+		bundleId: options.app.bundleId,
+		device: getDevice
+	};
+	return {
+		backendUrl,
+		cleanup: async () => {
+			if (device) {
+				await device.close();
+				device = null;
+			}
+			await appium.stop();
+			if (backend) await backend.stop();
+		},
+		mobile: createMobileFacet(config),
+		udid
+	};
+}
+//#endregion
 //#region src/core/specification/website/start-website.ts
 async function startWebsite(options) {
 	const callerDir = getCallerDir();
 	await registerMatchers();
+	if (options.backend && !options.server) throw new Error("specification.website(): `backend` requires `server` mode — a deployed `url` cannot be pointed at a local stub.");
+	let backend = null;
+	let backendUrl;
+	if (options.backend) {
+		backend = new StubBackend({ port: options.backend.port });
+		backendUrl = await backend.start();
+	}
 	let serve = null;
 	let baseUrl;
 	if (options.server) {
 		const root = resolveRoot(options.root, callerDir);
-		serve = new ServeAdapter(options.server, root);
-		baseUrl = await serve.start();
+		serve = new ServeAdapter(options.server, root, "website", options.backend && backendUrl !== void 0 ? { [options.backend.env]: backendUrl } : {});
+		try {
+			baseUrl = await serve.start();
+		} catch (error) {
+			await backend?.stop();
+			throw error;
+		}
 	} else baseUrl = options.url.replace(/\/$/, "");
 	let browser = null;
 	const getBrowser = async () => {
@@ -3564,6 +3693,8 @@ async function startWebsite(options) {
 		return browser;
 	};
 	const config = {
+		backend: backend ?? void 0,
+		backendUrl,
 		baseUrl,
 		browser: getBrowser,
 		external: options.external ?? (options.server ? "block" : "allow")
@@ -3575,6 +3706,7 @@ async function startWebsite(options) {
 				browser = null;
 			}
 			if (serve) await serve.stop();
+			if (backend) await backend.stop();
 		},
 		url: baseUrl,
 		website: createWebsiteFacet(config)
@@ -3583,7 +3715,7 @@ async function startWebsite(options) {
 //#endregion
 //#region src/core/specification/shared/specification.ts
 /**
-* The three specification constructors (CONVENTIONS A2) — created in a
+* The five specification constructors (CONVENTIONS A2) — created in a
 * `*.specification.ts` file under `specs/`, destructured with canonical
 * names, and cleaned up via `afterAll(cleanup)` (A1/A3/A4).
 *
@@ -3627,6 +3759,13 @@ const specification = {
 	*/
 	jobs: startJobs,
 	/**
+	* Test a native app on the iOS simulator. `device` names the simulator
+	* (resolved and booted via `simctl`); `app` names the bundle under
+	* test. `.open(deepLink?, scenario?)` relaunches the app fresh, runs
+	* the scenario, and captures the final screen.
+	*/
+	mobile: startMobile,
+	/**
 	* Test a deployed or locally-served website. `server` starts the site
 	* (a shell command receiving `PORT`); `url` targets a running one.
 	* `.visit(path)` renders the page in a single shared browser instance;
@@ -3698,6 +3837,30 @@ const within = (scope, target) => ({
 });
 //#endregion
 //#region src/integrations/sqlite/sqlite.ts
+const SQLITE_FILE_HEADER = Buffer.from("SQLite format 3\0");
+/**
+* Whether `path` looks like a usable SQLite database file: it exists, is at
+* least as long as the format header, and begins with the SQLite magic
+* bytes. Does not validate anything beyond the header — good enough to
+* reject a 0-byte or truncated leftover without opening the file.
+*/
+function isValidSqliteTemplate(path) {
+	if (!existsSync(path)) return false;
+	let fd;
+	try {
+		fd = openSync(path, "r");
+	} catch {
+		return false;
+	}
+	try {
+		const header = Buffer.alloc(SQLITE_FILE_HEADER.length);
+		return readSync(fd, header, 0, header.length, 0) === SQLITE_FILE_HEADER.length && header.equals(SQLITE_FILE_HEADER);
+	} catch {
+		return false;
+	} finally {
+		closeSync(fd);
+	}
+}
 var SqliteHandle = class {
 	type = "sqlite";
 	composeName = null;
@@ -3730,9 +3893,14 @@ var SqliteHandle = class {
 			while (existsSync(lockPath) && Date.now() - start < 3e4) await new Promise((r) => setTimeout(r, 100));
 		}
 		if (existsSync(this.templatePath)) {
-			this.connectionString = `file:${this.templatePath}`;
-			this.started = true;
-			return;
+			if (isValidSqliteTemplate(this.templatePath)) {
+				this.connectionString = `file:${this.templatePath}`;
+				this.started = true;
+				return;
+			}
+			try {
+				unlinkSync(this.templatePath);
+			} catch {}
 		}
 		const { writeFileSync } = await import("node:fs");
 		writeFileSync(lockPath, process.pid.toString());
@@ -3824,25 +3992,22 @@ function sqlite(options = {}) {
 	return new SqliteHandle(options);
 }
 //#endregion
+//#region src/core/contracts/filters.ts
+/** Does an observed text satisfy a declared {@link TextFilter}? */
+function matchesText(filter, actual) {
+	if (filter === void 0) return true;
+	if (typeof filter === "string") return actual === filter;
+	if (filter instanceof RegExp) return filter.test(actual);
+	return structuralEquals(filter, actual, new CaptureScope());
+}
+//#endregion
 //#region src/integrations/anthropic/anthropic.ts
 const ANTHROPIC_MESSAGES_URL = "https://api.anthropic.com/v1/messages";
 function matchesFilter(body, filter) {
-	if (filter.model) {
-		const model = body?.model;
-		if (typeof filter.model === "string" && model !== filter.model) return false;
-		if (filter.model instanceof RegExp && !filter.model.test(model ?? "")) return false;
-	}
-	if (filter.system) {
-		const system = typeof body?.system === "string" ? body.system : "";
-		if (typeof filter.system === "string" && !system.includes(filter.system)) return false;
-		if (filter.system instanceof RegExp && !filter.system.test(system)) return false;
-	}
-	if (filter.user) {
-		const userMsg = body?.messages?.find((m) => m.role === "user")?.content ?? "";
-		const text = typeof userMsg === "string" ? userMsg : JSON.stringify(userMsg);
-		if (typeof filter.user === "string" && !text.includes(filter.user)) return false;
-		if (filter.user instanceof RegExp && !filter.user.test(text)) return false;
-	}
+	if (!matchesText(filter.model, body?.model ?? "")) return false;
+	if (!matchesText(filter.system, typeof body?.system === "string" ? body.system : "")) return false;
+	const userMsg = body?.messages?.find((m) => m.role === "user")?.content ?? "";
+	if (!matchesText(filter.user, typeof userMsg === "string" ? userMsg : JSON.stringify(userMsg))) return false;
 	if (filter.tools) {
 		const names = body?.tools?.map((t) => t.name).filter(Boolean) ?? [];
 		if (!filter.tools.every((t) => names.includes(t))) return false;
@@ -3874,7 +4039,7 @@ function buildReply(data) {
 */
 const anthropic = {
 	/**
-	* Trigger: match Messages API requests, optionally routed through a
+	* Request: match Messages API calls, optionally routed through a
 	* custom gateway URL. When used with a JSON fixture file, the data is
 	* returned as-is (no wrapping) because Anthropic fixtures are typically
 	* already in the Messages API response shape.
@@ -3882,6 +4047,7 @@ const anthropic = {
 	* @example
 	*   anthropic.messages()
 	*   anthropic.messages({ system: /classify/ })
+	*   anthropic.messages({ user: buildPrompt() })   // string = EXACT equality
 	*   anthropic.messages({ user: /classify/ }, GATEWAY)
 	*/
 	messages(filter, url) {
@@ -3931,6 +4097,7 @@ function wrapJson(data) {
 		body: data
 	};
 }
+const TEXT_CONTENT_TYPE = "text/plain; charset=utf-8";
 function matchesBody(body, expected) {
 	if (typeof expected === "string") return (typeof body === "string" ? body : JSON.stringify(body ?? "")).includes(expected);
 	if (expected instanceof RegExp) {
@@ -3947,7 +4114,7 @@ function matchesEntries(expected, lookup) {
 	});
 }
 /**
-* Build the `match` predicate for an HTTP trigger filter, or `undefined` when
+* Build the `match` predicate for an HTTP request filter, or `undefined` when
 * no filter is supplied (fires on any URL/method match).
 */
 function buildMatch(filter) {
@@ -3958,7 +4125,7 @@ function buildMatch(filter) {
 		if (filter.query) {
 			let params;
 			try {
-				params = new URL(request.url).searchParams;
+				params = new URL(request.url, "http://contract.invalid").searchParams;
 			} catch {
 				return false;
 			}
@@ -3967,74 +4134,79 @@ function buildMatch(filter) {
 		return true;
 	};
 }
+function declare(method, url, filter) {
+	return {
+		adapter: "http",
+		match: buildMatch(filter),
+		method,
+		url,
+		wrap: wrapJson
+	};
+}
 /**
-* Generic HTTP intercept helpers for any URL. An optional {@link
-* HttpInterceptFilter} narrows matching by request body, headers, or query —
-* a request that hits the URL/method but fails the filter counts as unmatched
-* (strict intercepts, CONVENTIONS D7).
+* Generic HTTP contract helpers for any URL. The url is absolute (string or
+* RegExp), or a PATH FORM starting with `/` — `http.get('/articles/{{uuid}}')`
+* matches that path on ANY origin, which is what an app calling its own
+* backend needs. An optional {@link HttpContractFilter} narrows matching by
+* body, headers, or query — a request that hits the URL/method but fails the
+* filter counts as unmatched (strict contracts, CONVENTIONS D7).
 *
 * @example
-*   .intercept(http.get('https://api.example.com/data'), 'http/response.json')
-*   .intercept(http.post(URL, { body: { user: 'alice' } }), http.json({ ok: true }))
+*   defineContract({ request: http.get('/articles/{{uuid}}'), response: http.json(article) })
+*   defineContract({ request: http.post(URL, { body: { user: 'alice' } }), response: http.empty() })
 */
 const http = {
+	any(url, filter) {
+		return declare("*", url, filter);
+	},
+	delete(url, filter) {
+		return declare("DELETE", url, filter);
+	},
 	get(url, filter) {
-		return {
-			adapter: "http",
-			match: buildMatch(filter),
-			method: "GET",
-			url,
-			wrap: wrapJson
-		};
+		return declare("GET", url, filter);
+	},
+	patch(url, filter) {
+		return declare("PATCH", url, filter);
 	},
 	post(url, filter) {
-		return {
-			adapter: "http",
-			match: buildMatch(filter),
-			method: "POST",
-			url,
-			wrap: wrapJson
-		};
+		return declare("POST", url, filter);
 	},
 	put(url, filter) {
-		return {
-			adapter: "http",
-			match: buildMatch(filter),
-			method: "PUT",
-			url,
-			wrap: wrapJson
-		};
+		return declare("PUT", url, filter);
 	},
-	delete(url, filter) {
+	/** Response: a body-less reply (204 by default). */
+	empty(status = 204) {
 		return {
-			adapter: "http",
-			match: buildMatch(filter),
-			method: "DELETE",
-			url,
-			wrap: wrapJson
+			status,
+			body: null
 		};
 	},
-	any(url, filter) {
+	/** Response: an error status. Without a body, `{ error: 'HTTP <status>' }`. */
+	error(status, body) {
 		return {
-			adapter: "http",
-			match: buildMatch(filter),
-			method: "*",
-			url,
-			wrap: wrapJson
+			status,
+			body: body === void 0 ? { error: `HTTP ${status}` } : body
 		};
 	},
-	/** Response: simple JSON success. */
-	json(data, status = 200) {
+	/** Response: a JSON body (200 by default). */
+	json(body, init) {
 		return {
-			status,
-			body: data
+			status: init?.status ?? 200,
+			body,
+			delay: init?.delay,
+			headers: init?.headers
 		};
 	},
-	/** Response: error with message. */
-	error(status, message) {
+	/** Response: a text body, served as `text/plain` (200 by default). */
+	text(body, init) {
 		return {
-			status,
-			body: { error: message ?? `HTTP ${status}` }
+			status: init?.status ?? 200,
+			body,
+			delay: init?.delay,
+			headers: {
+				"content-type": TEXT_CONTENT_TYPE,
+				...init?.headers
+			}
 		};
 	}
 };
@@ -4043,21 +4215,9 @@ const http = {
 const OPENAI_CHAT_URL = "https://api.openai.com/v1/chat/completions";
 const OPENAI_RESPONSES_URL = "https://api.openai.com/v1/responses";
 function matchesChatFilter(body, filter) {
-	if (filter.model) {
-		const model = body?.model;
-		if (typeof filter.model === "string" && model !== filter.model) return false;
-		if (filter.model instanceof RegExp && !filter.model.test(model ?? "")) return false;
-	}
-	if (filter.system) {
-		const msg = body?.messages?.find((m) => m.role === "system")?.content ?? "";
-		if (typeof filter.system === "string" && !msg.includes(filter.system)) return false;
-		if (filter.system instanceof RegExp && !filter.system.test(msg)) return false;
-	}
-	if (filter.user) {
-		const msg = body?.messages?.find((m) => m.role === "user")?.content ?? "";
-		if (typeof filter.user === "string" && !msg.includes(filter.user)) return false;
-		if (filter.user instanceof RegExp && !filter.user.test(msg)) return false;
-	}
+	if (!matchesText(filter.model, body?.model ?? "")) return false;
+	if (!matchesText(filter.system, body?.messages?.find((m) => m.role === "system")?.content ?? "")) return false;
+	if (!matchesText(filter.user, body?.messages?.find((m) => m.role === "user")?.content ?? "")) return false;
 	if (filter.tools) {
 		const names = body?.tools?.map((t) => t.function?.name).filter(Boolean) ?? [];
 		if (!filter.tools.every((t) => names.includes(t))) return false;
@@ -4066,23 +4226,11 @@ function matchesChatFilter(body, filter) {
 	return true;
 }
 function matchesResponsesFilter(body, filter) {
-	if (filter.model) {
-		const model = body?.model;
-		if (typeof filter.model === "string" && model !== filter.model) return false;
-		if (filter.model instanceof RegExp && !filter.model.test(model ?? "")) return false;
-	}
-	if (filter.system) {
-		const instructions = body?.instructions ?? "";
-		const systemInput = body?.input?.find?.((m) => m.role === "system")?.content ?? "";
-		const text = instructions || systemInput;
-		if (typeof filter.system === "string" && !text.includes(filter.system)) return false;
-		if (filter.system instanceof RegExp && !filter.system.test(text)) return false;
-	}
-	if (filter.user) {
-		const msgs = (body?.input ?? []).filter((m) => m.role === "user").map((m) => typeof m.content === "string" ? m.content : JSON.stringify(m.content)).join(" ");
-		if (typeof filter.user === "string" && !msgs.includes(filter.user)) return false;
-		if (filter.user instanceof RegExp && !filter.user.test(msgs)) return false;
-	}
+	if (!matchesText(filter.model, body?.model ?? "")) return false;
+	const systemInput = body?.input?.find?.((m) => m.role === "system")?.content ?? "";
+	if (!matchesText(filter.system, body?.instructions || systemInput)) return false;
+	const userText = (body?.input ?? []).filter((m) => m.role === "user").map((m) => typeof m.content === "string" ? m.content : JSON.stringify(m.content)).join(" ");
+	if (!matchesText(filter.user, userText)) return false;
 	if (filter.tools) {
 		const names = body?.tools?.map((t) => t.name ?? t.function?.name).filter(Boolean) ?? [];
 		if (!filter.tools.every((t) => names.includes(t))) return false;
@@ -4146,12 +4294,15 @@ function buildResponsesReply(data) {
 */
 const openai = {
 	/**
-	* Trigger: match Chat Completions API requests.
+	* Request: match Chat Completions API calls. STRING filters mean EXACT
+	* equality (pass the app's own prompt builder); loosen deliberately with a
+	* RegExp or `match.includes(...)`.
 	*
 	* @example
-	*   openai.chat()                         // any chat call
-	*   openai.chat({ model: 'gpt-4o' })      // specific model
-	*   openai.chat({ system: /classify/ })    // system prompt match
+	*   openai.chat()                            // any chat call
+	*   openai.chat({ model: 'gpt-4o' })         // exact model
+	*   openai.chat({ system: buildPrompt() })   // exact system prompt
+	*   openai.chat({ system: /classify/ })      // pattern
 	*/
 	chat(filter) {
 		return {
@@ -4163,7 +4314,8 @@ const openai = {
 		};
 	},
 	/**
-	* Trigger: match Responses API requests (AI SDK v5+) with auto-wrapping.
+	* Request: match Responses API calls (AI SDK v5+) with auto-wrapping.
+	* String filters mean EXACT equality (see {@link openai.chat}).
 	* When used with a JSON file, the data is automatically wrapped in the
 	* Responses API envelope.
 	*
@@ -4214,35 +4366,6 @@ const openai = {
 	}
 };
 //#endregion
-//#region src/core/contracts/contract.ts
-/**
-* Declare an intercept contract. Identity function — its value is the
-* enforced shape and the naming convention:
-*
-* @example
-*   // specs/api/reports/contracts/classify-article.openai.ts
-*   import { defineContract, openai } from '@jterrazz/test';
-*
-*   export default defineContract({
-*       trigger: openai.responses({ user: /Report Ingestion/, tools: ['classify'] }),
-*       response: openai.reply({ categories: ['TECH'] }),
-*   });
-*
-*   // Dynamic — the response is computed from the observed request:
-*   export default defineContract({
-*       trigger: http.post('https://api.example.com/echo'),
-*       response: (request) => http.json({ received: request.body }),
-*   });
-*
-*   // specs/api/reports/reports.test.ts
-*   import classifyArticle from '../../spec/intercept/contracts/classify-article.openai.js';
-*
-*   const result = await jobs.intercept(classifyArticle).trigger('report-ingestion');
-*/
-function defineContract(contract) {
-	return contract;
-}
-//#endregion
 //#region src/vitest/mock-of.ts
 /**
 * Create a deep mock proxy for a given type.
@@ -4269,4 +4392,4 @@ registerComposeServiceFactory("postgres", (service) => postgres({
 }));
 registerComposeServiceFactory("redis", (service) => redis({ composeService: service.name }));
 //#endregion
-export { BaseResult, CliResult, ContainerAccessor, DirectoryAccessor, FetchResult, FilesystemAccessor, HttpResult, JsonAccessor, Matcher, Orchestrator, PageResult, ResponseAccessor, TableAccessor, TextAccessor, anthropic, banner, button, complementary, content, contentinfo, defineContract, field, findContainersByLabel, form, heading, http, inspectContainer, link, main, match, mockOf, mockOfDate, navigation, openai, postgres, redis, region, removeContainers, search, specification, sqlite, testId, text, within };
+export { BaseResult, CliResult, ContainerAccessor, DirectoryAccessor, FetchResult, FilesystemAccessor, HttpResult, JsonAccessor, Matcher, Orchestrator, PageResult, ResponseAccessor, ScreenResult, TableAccessor, TextAccessor, anthropic, banner, button, complementary, content, contentinfo, defineContract, defineContracts, field, findContainersByLabel, form, heading, http, inspectContainer, link, main, match, mockOf, mockOfDate, navigation, openai, postgres, redis, region, removeContainers, search, specification, sqlite, testId, text, within };