@jterrazz/test 10.0.0 → 11.0.0

package/dist/index.d.ts

@@ -10,12 +10,14 @@ import { DeepMockProxy } from "vitest-mock-extended";
  * (`expected/*.txt`). One grammar, one vocabulary (CONVENTIONS D4).
  */
 /** The frozen token vocabulary (CONVENTIONS D4) plus the code-only kinds. */
-type MatcherKind = 'any' | 'base64' | 'date' | 'duration' | 'email' | 'float' | 'hex' | 'int' | 'ip' | 'iso8601' | 'number' | 'path' | 'port' | 'ref' | 'regex' | 'semver' | 'sha' | 'string' | 'time' | 'ulid' | 'url' | 'uuid' | 'workdir';
+type MatcherKind = 'any' | 'base64' | 'date' | 'duration' | 'email' | 'float' | 'hex' | 'includes' | 'int' | 'ip' | 'iso8601' | 'number' | 'path' | 'port' | 'ref' | 'regex' | 'semver' | 'sha' | 'string' | 'time' | 'ulid' | 'url' | 'uuid' | 'workdir';
 /**
  * A dynamic-value matcher. Created via the {@link match} factories — never
  * constructed directly by user code.
  */
 declare class Matcher {
+  /** For kind 'includes': the substring the actual value must contain. */
+  readonly includes?: string;
   readonly kind: MatcherKind;
   /** For kind 'ref': the capture to assert inequality against. */
   readonly notRef?: string;
@@ -24,6 +26,7 @@ declare class Matcher {
   /** For kind 'regex': the pattern the actual value must match. */
   readonly regex?: RegExp;
   constructor(kind: MatcherKind, options?: {
+    includes?: string;
     notRef?: string;
     refName?: string;
     regex?: RegExp;
@@ -61,6 +64,13 @@ declare const match: {
   float: () => Matcher;
   /** Matches a hexadecimal string. */
   hex: () => Matcher;
+  /**
+   * Matches a string CONTAINING the given substring. Code-only, like
+   * {@link match.regex} — the `{{token}}` fixture vocabulary does not grow.
+   * The explicit escape hatch now that contract string filters
+   * (`openai.chat({ user })`) mean exact equality.
+   */
+  includes: (substring: string) => Matcher;
   /** Matches an integer (or an integer string in text contexts). */
   int: () => Matcher;
   /** Matches an IPv4 address. */
@@ -389,43 +399,48 @@ interface CliPort {
 //#endregion
 //#region src/core/contracts/types.d.ts
 /**
- * The observed outgoing request, reduced to what trigger matchers inspect.
- * Built once per request by the MSW integration and handed to
- * {@link InterceptTrigger.match}.
+ * The observed outgoing request, reduced to what contract matchers inspect.
+ * Built once per request by the engine (MSW on api/jobs, the stub backend on
+ * website/mobile) and handed to {@link ContractRequest.match} and to a
+ * {@link ContractResponder}.
  */
 interface MatchableRequest {
   /** Parsed JSON body when the payload is JSON, the raw text otherwise, or `null` when absent. */
   body: unknown;
   /** Request headers, keyed by lowercased header name. */
   headers: Record<string, string>;
-  /** The fully-qualified request URL (including any query string). */
+  /** Uppercased HTTP method of the observed request. */
+  method: string;
+  /** The request URL — fully-qualified, or origin-relative for the stub backend. */
   url: string;
 }
 /**
- * An intercept trigger describes which HTTP request to match.
+ * The request half of a contract: which outgoing call it speaks for.
+ *
+ * `url` is either an absolute URL (string or RegExp), or a PATH FORM starting
+ * with `/` (`/articles/{{uuid}}`) which matches any origin — the shape a
+ * website/mobile app's own backend calls take. `{{token}}` segments compare
+ * structurally, declared query params are a subset of the observed ones.
  */
-interface InterceptTrigger {
-  /** Adapter name - must match the folder prefix in file-based intercepts. */
+interface ContractRequest {
+  /** Adapter name — `http` | `openai` | `anthropic`. */
   adapter: string;
-  /** HTTP method to match. */
+  /** HTTP method to match. `*` matches any method. */
   method: string;
-  /** URL pattern to match (string for exact prefix, RegExp for pattern). */
+  /** Absolute URL (string | RegExp) or an any-origin path form (`/articles/{{uuid}}`). */
   url: RegExp | string;
-  /** Optional request matcher - the handler only fires if this returns true. */
+  /** Optional request matcher — the contract only fires if this returns true. */
   match?: (request: MatchableRequest) => boolean;
-  /**
-   * Transform raw JSON data into a provider-specific response envelope.
-   * Called when .intercept(trigger, 'adapter/file.json') loads a file.
-   */
-  wrap: (data: unknown) => InterceptResponse;
+  /** Transform raw data into a provider-specific response envelope. */
+  wrap: (data: unknown) => ContractResponse;
 }
 /**
- * An intercept response describes what to return when the trigger matches.
+ * The response half of a contract: what to reply when the request matches.
  */
-interface InterceptResponse {
+interface ContractResponse {
   /** HTTP status code (default: 200). */
   status?: number;
-  /** Response body (will be JSON.stringified). */
+  /** Response body — an object is JSON, a string is text, `null`/`undefined` is empty. */
   body: unknown;
   /** Response headers. */
   headers?: Record<string, string>;
@@ -434,67 +449,101 @@ interface InterceptResponse {
 }
 /**
  * A dynamic response: computed from the observed request at the moment the
- * intercept is consumed, rather than fixed ahead of time. Handed the same
- * {@link MatchableRequest} the trigger matched on, so the reply can echo or
- * derive from the request body/headers/url.
- */
-type InterceptResponder = (request: MatchableRequest) => InterceptResponse;
-/**
- * What an intercept replies with: either a fixed {@link InterceptResponse} or
- * an {@link InterceptResponder} evaluated per consumed request.
+ * contract is served, rather than fixed ahead of time. Handed the same
+ * {@link MatchableRequest} the request half matched on, so the reply can echo
+ * or derive from the body/headers/url.
  */
-type InterceptResponseValue = InterceptResponder | InterceptResponse;
+type ContractResponder = (request: MatchableRequest) => ContractResponse;
 /**
- * A fully resolved intercept entry ready to be registered with MSW.
+ * What a contract replies with: either a fixed {@link ContractResponse} or a
+ * {@link ContractResponder} evaluated per served request.
  */
-interface InterceptEntry {
-  trigger: InterceptTrigger;
-  response: InterceptResponseValue;
-}
+type ContractResponseValue = ContractResponder | ContractResponse;
 //#endregion
 //#region src/core/contracts/contract.d.ts
 /**
- * A declared external interaction: what to match and what to reply, together
- * in one named artifact. Contracts live in flat TypeScript files under
- * `contracts/` next to the tests that use them — `<name>.<provider>.ts` with
- * `provider ∈ { openai, anthropic, http }` (CONVENTIONS C4) — so the business
- * payload (prompts, JSON responses) is visible at a glance while the real
- * HTTP call stays mocked underneath (MSW).
+ * A declared external interaction: what to match (`request`) and what to reply
+ * (`response`), together in one named artifact. Contracts live in TypeScript
+ * files under `contracts/` next to the tests that use them, so the business
+ * payload (prompts, JSON responses) is visible at a glance while the real HTTP
+ * call stays mocked underneath.
  */
-interface InterceptContract {
-  trigger: InterceptTrigger;
+interface Contract {
+  /** Which outgoing call this contract speaks for. */
+  request: ContractRequest;
   /**
-   * The reply — a fixed {@link InterceptResponse}, or a function
-   * `(request) => InterceptResponse` evaluated per consumed request when the
+   * The reply — a fixed {@link ContractResponse}, or a function
+   * `(request) => ContractResponse` evaluated per served request when the
    * response must derive from the incoming payload.
    */
-  response: InterceptResponseValue;
+  response: ContractResponseValue;
+  /**
+   * How many times this contract may serve. Omitted = unlimited (a
+   * re-render or a retry replays it). `n` = exhausted after n serves, so an
+   * ordered sequence is a finite contract followed by an unlimited tail.
+   */
+  times?: number;
+  /**
+   * When true, the chain FAILS unless the contract was actually requested:
+   * at least once, or exactly `times` times when `times` is set. Turns a
+   * silently-unused declaration into a spec failure.
+   */
+  required?: boolean;
+}
+/**
+ * A composite of contracts — the unit tests import. Flat, ordered, immutable;
+ * `.with()` derives a variant without touching the original.
+ */
+interface Contracts {
+  /** The flattened contracts, in selection order. */
+  readonly contracts: readonly Contract[];
+  /**
+   * Derive a new composite: every base contract sharing a route with an
+   * override is REPLACED, and the overrides are PREPENDED — so a
+   * more-specific override wins first-match selection over a generic base
+   * route it does not replace.
+   */
+  with: (...overrides: (Contract | Contract[] | Contracts)[]) => Contracts;
 }
+/** Any accepted contract input: one, a list, or a composite. */
+type ContractInput = Contract | Contract[] | Contracts;
 /**
- * Declare an intercept contract. Identity function — its value is the
- * enforced shape and the naming convention:
+ * Declare one contract. Identity function — its value is the enforced shape
+ * and the naming convention:
  *
  * @example
- *   // specs/api/reports/contracts/classify-article.openai.ts
+ *   // specs/api/reports/contracts/openai/classify-article.ts
  *   import { defineContract, openai } from '@jterrazz/test';
  *
  *   export default defineContract({
- *       trigger: openai.responses({ user: /Report Ingestion/, tools: ['classify'] }),
+ *       request: openai.responses({ user: PROMPT, 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'),
+ *       request: http.post('https://api.example.com/echo'),
  *       response: (request) => http.json({ received: request.body }),
  *   });
+ */
+declare function defineContract(contract: Contract): Contract;
+/**
+ * Compose contracts into the artifact a test imports — it's contracts all the
+ * way down: a composite may extend contracts, lists, and other composites,
+ * recursively, order preserved.
  *
- *   // specs/api/reports/reports.test.ts
- *   import classifyArticle from '../../spec/intercept/contracts/classify-article.openai.js';
+ * `.with(...)` derives a scenario: contracts whose route the overrides claim
+ * are removed from the base, and the overrides are prepended. Under
+ * first-match selection a more specific override (`/articles/gone-1`) also
+ * wins over a generic base route (`/articles/{{uuid}}`) it does not replace.
  *
- *   const result = await jobs.intercept(classifyArticle).trigger('report-ingestion');
+ * @example
+ *   // contracts/newsroom.contracts.ts
+ *   export default defineContracts(events, articleById);
+ *   export const withArticleGone = (id: string) =>
+ *       newsroom.with(articleGone(id));
  */
-declare function defineContract(contract: InterceptContract): InterceptContract;
+declare function defineContracts(...items: ContractInput[]): Contracts;
 //#endregion
 //#region src/core/ports/browser.port.d.ts
 /**
@@ -591,6 +640,11 @@ interface Visitor {
 type VisitScenario = (visitor: Visitor) => Promise<void>;
 /** Per-visit options forwarded to the browser context. */
 interface BrowserOpenOptions {
+  /**
+   * Extra origins the `external: 'block'` policy lets through — the
+   * declared stub backend the page legitimately fetches from.
+   */
+  allowedOrigins?: string[];
   /**
    * Base URL of the site under test — the origin `goto()` resolves against
    * and the boundary of the `external` policy.
@@ -644,6 +698,107 @@ interface BrowserPort {
   open: (url: string, options: BrowserOpenOptions) => Promise<BrowserPage>;
 }
 //#endregion
+//#region src/core/ports/device.port.d.ts
+/**
+ * The element kinds a mobile screen can designate — the structural subset of
+ * {@link ElementRef} kinds that map onto the XCUITest accessibility tree.
+ * There is ONE element vocabulary across facets: `button('Bookmark')` works
+ * in a visit scenario and a mobile scenario alike. Landmarks have no iOS
+ * analog — passing one to a mobile verb refuses at runtime.
+ */
+type MobileElementKind = 'button' | 'field' | 'testId' | 'text';
+/**
+ * A user-facing element descriptor for mobile scenarios — pure data, built by
+ * the shared element vocabulary (`button()`, `field()`, `content()`,
+ * `testId()`, `within()`) and translated into iOS predicate strings by the
+ * device integration. Structurally the same ref type as the browser's, so the
+ * vocabulary stays single; kinds outside {@link MobileElementKind} (the ARIA
+ * landmarks) are refused at runtime with a message naming the boundary.
+ *
+ * A descriptor must designate exactly ONE element when a verb ACTS on it
+ * (`tap`, `fill`) — see {@link MobileElementMatch} and CONVENTIONS W3.
+ * `see()` acts on nothing, so any visible match satisfies it: XCUITest trees
+ * legitimately duplicate a label across container and child.
+ */
+type MobileElementRef = ElementRef;
+/**
+ * One candidate captured when a descriptor matched more than one element —
+ * the evidence the ambiguity error enumerates so the author can disambiguate
+ * without opening the simulator.
+ */
+interface MobileElementMatch {
+  /** The accessibility identifier (`testId()` target), when one is set. */
+  identifier?: string;
+  /** The accessible label, whitespace-collapsed and truncated. */
+  label?: string;
+  /** Element type without the `XCUIElementType` prefix — `Button`, `StaticText`. */
+  type: string;
+  /** The element value (text-field content, adjustable value), when present. */
+  value?: string;
+}
+/**
+ * The visitor — the interaction vocabulary handed to a mobile scenario.
+ * Every verb auto-waits by polling until a visible match exists; acting
+ * verbs then enforce exactly-one (W3), while `see()` — the single
+ * synchronization primitive — is satisfied by any visible match. There is
+ * no sleep and no conditional helper.
+ */
+interface MobileVisitor {
+  /** Fill a text field with a value. */
+  fill: (element: MobileElementRef, value: string) => Promise<void>;
+  /** Wait until the element is visible — the only synchronization primitive. */
+  see: (element: MobileElementRef) => Promise<void>;
+  /** Tap the element. */
+  tap: (element: MobileElementRef) => Promise<void>;
+}
+/** The behavior of an open — the When of the spec; assertions stay in the Then. */
+type MobileScenario = (visitor: MobileVisitor) => Promise<void>;
+/**
+ * One node of the projected accessibility tree — the XCUITest page source
+ * with its noise collapsed: unlabeled, identifier-less, valueless wrapper
+ * nodes are dropped and their children hoisted, so the projection stays
+ * stable and golden-friendly. Type names lose the `XCUIElementType` prefix.
+ */
+interface ScreenNode {
+  children?: ScreenNode[];
+  /** The accessibility identifier, only when it differs from the label. */
+  identifier?: string;
+  label?: string;
+  /** Element type without the `XCUIElementType` prefix — `Button`, `StaticText`. */
+  type: string;
+  value?: string;
+}
+/**
+ * The screen captured by a device open — the FINAL state when a scenario
+ * ran. The tree is the projected page source; `texts` are the visible
+ * labels/values in document order, consecutive duplicates collapsed.
+ */
+interface DeviceScreen {
+  texts: string[];
+  tree: ScreenNode;
+}
+/** Per-open options forwarded to the device session. */
+interface DeviceOpenOptions {
+  /** The app under test — terminated and relaunched for a fresh, deterministic state. */
+  bundleId: string;
+  /** Deep link applied after the relaunch (`news://events`); absent opens the app plainly. */
+  deepLink?: string;
+  /** The interaction scenario to run after launch; the capture reflects the final state. */
+  scenario?: MobileScenario;
+}
+/**
+ * Abstract device interface for the mobile specification runner.
+ * One implementation lives in `integrations/appium/` — a single driver
+ * session per runner, created on the first `open()` and reused; each open
+ * terminates and relaunches the app for a deterministic fresh state.
+ */
+interface DevicePort {
+  /** End the driver session (idempotent). */
+  close: () => Promise<void>;
+  /** Relaunch the app, apply the deep link, run the scenario, capture the final screen. */
+  open: (options: DeviceOpenOptions) => Promise<DeviceScreen>;
+}
+//#endregion
 //#region src/core/ports/isolation.port.d.ts
 /**
  * Strategy for isolating service state across parallel test workers.
@@ -771,6 +926,27 @@ declare class HttpResult extends BaseResult {
   get status(): number;
 }
 //#endregion
+//#region src/core/specification/mobile/result.d.ts
+/** Result from a `.open()` action — the screen as the device saw it, final state. */
+declare class ScreenResult extends BaseResult {
+  private readonly capturedScreen;
+  constructor(options: {
+    config: SpecificationConfig;
+    screen: DeviceScreen;
+    testDir: string;
+  });
+  /**
+   * The visible screen texts as one stream, in reading order — the scalpel
+   * for a targeted probe: `expect(result.content).toContain('Bookmarked')`.
+   */
+  get content(): TextAccessor;
+  /**
+   * The projected accessibility tree as a JSON accessor — the one golden
+   * per screen: `expect(result.screen).toMatch('events.screen.json')`.
+   */
+  get screen(): JsonAccessor;
+}
+//#endregion
 //#region src/core/specification/website/result.d.ts
 /** A raw HTTP exchange captured by `.fetch()` — redirects are NOT followed. */
 interface FetchExchange {
@@ -848,6 +1024,48 @@ declare class PageResult extends BaseResult {
   get url(): string;
 }
 //#endregion
+//#region src/core/specification/shared/stub-backend.d.ts
+/** Options for the stub backend server. */
+interface StubBackendOptions {
+  /**
+   * Fixed port — pins a stable stub URL across runs (a bundler that inlines
+   * the URL at serve time survives warm). Default: a free OS-assigned port.
+   */
+  port?: number;
+}
+declare class StubBackend {
+  /** Guarded once the current chain declared at least one contract. */
+  private guarded;
+  private readonly options;
+  private queue;
+  private server;
+  private readonly unmatchedRequests;
+  private url;
+  constructor(options?: StubBackendOptions);
+  /** Start the server and resolve with its base URL. */
+  start(): Promise<string>;
+  /** Stop the server (idempotent). */
+  stop(): Promise<void>;
+  /**
+   * 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: readonly Contract[]): void;
+  /**
+   * 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(): Error | null;
+  private corsHeaders;
+  private describeRoutes;
+  private handle;
+  private record;
+}
+//#endregion
 //#region src/core/specification/shared/builder.d.ts
 /** A named job that can be triggered via jobs.trigger(). */
 interface JobHandle {
@@ -867,6 +1085,16 @@ interface DockerSpecConfig {
 }
 /** Adapter configuration passed to the specification facets at setup time. */
 interface SpecificationConfig {
+  /**
+   * The declared stub backend (website/mobile facets) — armed with the
+   * chain's contracts before every terminal action.
+   */
+  backend?: StubBackend;
+  /**
+   * Base URL of the running stub backend — allow-listed through the
+   * browser's `external: 'block'` policy so client-side fetches reach it.
+   */
+  backendUrl?: string;
   /** Base URL of the website under test (website facet only). */
   baseUrl?: string;
   /**
@@ -881,6 +1109,8 @@ interface SpecificationConfig {
    * of strict intercepts.
    */
   external?: 'allow' | 'block';
+  /** Bundle id of the app under test (mobile facet only) — the app `.open()` relaunches. */
+  bundleId?: string;
   command?: CliPort;
   database?: DatabasePort;
   /**
@@ -890,6 +1120,13 @@ interface SpecificationConfig {
    */
   databaseKeys?: string[];
   databases?: Map<string, DatabasePort>;
+  /**
+   * Lazy device accessor (mobile facet only). The first `.open()` creates
+   * the shared driver session; the appium/webdriverio integration stays a
+   * lazy import so the optional peer is only loaded when a spec opens the
+   * app.
+   */
+  device?: () => Promise<DevicePort>;
   dockerConfig?: DockerSpecConfig;
   /**
    * Unique id shared by every spec from this runner instance.
@@ -918,6 +1155,11 @@ interface SpecificationConfig {
    */
   transform?: (text: string) => string;
 }
+/**
+ * The `.intercept()` overload set, identical on every facet: one contract, a
+ * list, a composite — or the inline `(request, response)` pair for a one-off.
+ */
+type InterceptMethod<T> = ((contracts: ContractInput) => T) & ((request: ContractRequest, response: ContractResponder | ContractResponse) => T);
 /**
  * The `api` facet — HTTP chain entry handed out by `specification.api()`.
  * Setup methods chain; action methods are terminal: they execute the spec
@@ -929,8 +1171,8 @@ interface SpecificationConfig {
 interface ApiSpecification<DatabaseKey extends string = string> {
   /** Set HTTP headers for the request. Multiple calls merge. */
   headers: (headers: Record<string, string>) => ApiSpecification<DatabaseKey>;
-  /** Intercept an outgoing HTTP call — a contract, an array of contracts, or a trigger + response pair. */
-  intercept: ((contractOrContracts: InterceptContract | InterceptContract[]) => ApiSpecification<DatabaseKey>) & ((trigger: InterceptTrigger, response: InterceptResponder | InterceptResponse | string) => ApiSpecification<DatabaseKey>);
+  /** Declare outgoing calls — a contract, a list, a composite, or an inline request + response pair. */
+  intercept: InterceptMethod<ApiSpecification<DatabaseKey>>;
   /** Queue a SQL seed file from `seeds/` to run before the action. */
   seed: (file: string, options?: {
     database?: DatabaseKey;
@@ -951,8 +1193,8 @@ interface ApiSpecification<DatabaseKey extends string = string> {
  * Jobs run in-process by definition (CONVENTIONS A5/A8).
  */
 interface JobsSpecification<DatabaseKey extends string = string> {
-  /** Intercept an outgoing HTTP call — a contract, an array of contracts, or a trigger + response pair. */
-  intercept: ((contractOrContracts: InterceptContract | InterceptContract[]) => JobsSpecification<DatabaseKey>) & ((trigger: InterceptTrigger, response: InterceptResponder | InterceptResponse | string) => JobsSpecification<DatabaseKey>);
+  /** Declare outgoing calls — a contract, a list, a composite, or an inline request + response pair. */
+  intercept: InterceptMethod<JobsSpecification<DatabaseKey>>;
   /** Queue a SQL seed file from `seeds/` to run before the action. */
   seed: (file: string, options?: {
     database?: DatabaseKey;
@@ -998,6 +1240,11 @@ interface CliSpecification<DatabaseKey extends string = string> {
 interface WebsiteSpecification {
   /** Set HTTP headers for the exchange (incl. User-Agent overrides). Multiple calls merge. */
   headers: (headers: Record<string, string>) => WebsiteSpecification;
+  /**
+   * Declare the chain's backend contracts — served by the declared stub
+   * backend (requires the runner's `backend` option). Multiple calls append.
+   */
+  intercept: InterceptMethod<WebsiteSpecification>;
   /** Perform one raw HTTP GET — redirects surface as 3xx results, never followed. */
   fetch: (path: string) => Promise<FetchResult>;
   /**
@@ -1007,6 +1254,25 @@ interface WebsiteSpecification {
    */
   visit: (path: string, scenario?: VisitScenario) => Promise<PageResult>;
 }
+/**
+ * The `mobile` facet — screen chain entry handed out by
+ * `specification.mobile()`. `.open()` is the single, terminal action: it
+ * terminates and relaunches the app (deterministic fresh state), applies the
+ * deep link, runs the scenario, and captures the final screen.
+ */
+interface MobileSpecification {
+  /**
+   * Declare the chain's backend contracts — served by the declared stub
+   * backend (requires the runner's `backend` option). Multiple calls append.
+   */
+  intercept: InterceptMethod<MobileSpecification>;
+  /**
+   * Relaunch the app and resolve with the captured screen. With a deep
+   * link, the app opens on it; with a scenario, the visitor interacts
+   * first (the When) and the capture reflects the FINAL screen state.
+   */
+  open: (deepLink?: string, scenario?: MobileScenario) => Promise<ScreenResult>;
+}
 //#endregion
 //#region src/core/specification/cli/result.d.ts
 /**
@@ -1358,6 +1624,72 @@ interface JobsHandle<DatabaseKey extends string = string> {
 }
 declare function startJobs<Services extends ServiceRecord>(options: JobsSpecificationOptions<Services>): Promise<JobsHandle<DatabaseKeys<Services>>>;
 //#endregion
+//#region src/core/specification/mobile/start-mobile.d.ts
+/**
+ * The declared stub backend behind the app under test. The framework owns
+ * the simulator and appium but NOT the JS bundler (Metro belongs to the
+ * caller's repo, like `next build` belongs to a website's) — so nothing is
+ * injected: the handle exposes `backendUrl` and the CALLER wires it into its
+ * own bundler env.
+ */
+interface MobileBackendOptions {
+  /**
+   * Fixed port — pins a stable stub URL across runs. Metro inlines
+   * `EXPO_PUBLIC_*` values at bundle-serve time; a stable port lets a warm
+   * Metro survive between runs. Default: a free OS-assigned port.
+   */
+  port?: number;
+}
+/** Options for {@link startMobile | specification.mobile}. */
+interface MobileSpecificationOptions {
+  /** The app under test — terminated and relaunched by every `.open()`. */
+  app: {
+    /** Bundle id of the installed app (`com.example.app`). */
+    bundleId: string;
+  };
+  /**
+   * Declared stub backend: started with the runner, serving the contracts
+   * each chain declares via `.intercept(...)`. The handle gains
+   * `backendUrl` — inject it into your bundler env yourself.
+   */
+  backend?: MobileBackendOptions;
+  /** The simulator to run on — resolved through `xcrun simctl`. */
+  device: {
+    /** Simulator name, matched exactly (`iPhone 17`). */
+    name: string;
+    /** OS narrowing when the name exists on several runtimes — `'26.5'` or `'iOS 26.5'`. */
+    os?: string;
+    /** Explicit UDID — skips name/os resolution entirely. */
+    udid?: string;
+  };
+  /**
+   * Project-root override (CONVENTIONS A9): where the appium binary is
+   * resolved from (`node_modules/.bin`). Auto-discovered from the calling
+   * file when absent.
+   */
+  root?: string;
+}
+/**
+ * The record returned by {@link startMobile | specification.mobile}.
+ * Destructure with the canonical names (CONVENTIONS A3):
+ *
+ *     const { mobile, cleanup, udid } = await specification.mobile(…);
+ */
+interface MobileHandle {
+  /**
+   * Base URL of the declared stub backend — present only with the
+   * `backend` option. The caller injects it into its own bundler env
+   * (e.g. `EXPO_PUBLIC_API_URL`); the framework never touches the bundler.
+   */
+  backendUrl?: string;
+  /** End the driver session, stop the appium server and the stub backend. */
+  cleanup: () => Promise<void>;
+  mobile: MobileSpecification;
+  /** The resolved simulator UDID the specs run against. */
+  udid: string;
+}
+declare function startMobile(options: MobileSpecificationOptions): Promise<MobileHandle>;
+//#endregion
 //#region src/core/specification/website/serve.adapter.d.ts
 /** Options for the local server started by `specification.website()`. */
 interface ServeOptions {
@@ -1372,11 +1704,25 @@ interface ServeOptions {
 }
 //#endregion
 //#region src/core/specification/website/start-website.d.ts
+/**
+ * The declared stub backend behind the site under test — started before the
+ * server command, torn down with the runner. Its URL is injected into the
+ * server child's environment under `env`; the contracts each chain declares
+ * via `.intercept(...)` are what it serves.
+ */
+interface WebsiteBackendOptions {
+  /** Env var receiving the stub's URL in the server child (e.g. `'API_URL'`). */
+  env: string;
+  /** Fixed port — pins a stable stub URL across runs. Default: a free OS-assigned port. */
+  port?: number;
+}
 /**
  * Options for {@link startWebsite | specification.website}. `server` (start
  * the site locally) and `url` (target a running site) are mutually
  * exclusive BY TYPE — the union makes the invalid combinations
- * inexpressible rather than runtime-checked.
+ * inexpressible rather than runtime-checked. `backend` requires `server`
+ * mode for the same reason: a deployed site cannot be pointed at a local
+ * stub.
  */
 type WebsiteSpecificationOptions = {
   /**
@@ -1391,6 +1737,12 @@ type WebsiteSpecificationOptions = {
    */
   root?: string;
 } & ({
+  /**
+   * Declared stub backend: started BEFORE the server command, its
+   * URL injected into the child env under `backend.env`. Serves the
+   * contracts each chain declares via `.intercept(...)`.
+   */
+  backend?: WebsiteBackendOptions;
   /**
    * Start the site locally: a shell command receiving a free port
    * as `PORT`, polled on `ready` (default `/`) until it answers.
@@ -1398,6 +1750,7 @@ type WebsiteSpecificationOptions = {
   server: ServeOptions;
   url?: never;
 } | {
+  backend?: never;
   server?: never;
   /** Target an already-running site (a deployed or preview URL). */
   url: string;
@@ -1419,7 +1772,7 @@ declare function startWebsite(options: WebsiteSpecificationOptions): Promise<Web
 //#endregion
 //#region src/core/specification/shared/specification.d.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).
  *
@@ -1462,6 +1815,13 @@ declare const specification: {
    * server, no mode. `.trigger(name)` is the terminal action.
    */
   jobs: typeof 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: typeof startMobile;
   /**
    * Test a deployed or locally-served website. `server` starts the site
    * (a shell command receiving `PORT`); `url` targets a running one.
@@ -1702,20 +2062,38 @@ declare class SqliteHandle implements DatabasePort, ServiceHandle {
  */
 declare function sqlite(options?: SqliteOptions): SqliteHandle;
 //#endregion
+//#region src/core/contracts/filters.d.ts
+/**
+ * A text filter on a provider request builder (`openai.chat({ user })`,
+ * `anthropic.messages({ system })`, …).
+ *
+ * A **string is EXACT**. That is deliberate: a substring filter silently
+ * cross-matches — two prompts sharing a preamble both satisfy the first
+ * contract, and the spec goes green on the wrong reply. Looser matching is
+ * explicit, and says which looseness it means:
+ *
+ * - a `RegExp` — pattern matching;
+ * - `match.includes('…')` — containment, the code-only matcher (it never joins
+ *   the `{{token}}` file vocabulary, CONVENTIONS D4);
+ * - any other `match.*` matcher, evaluated by the same structural engine the
+ *   assertions use.
+ */
+type TextFilter = Matcher | RegExp | string;
+//#endregion
 //#region src/integrations/anthropic/anthropic.d.ts
 interface AnthropicMessagesFilter {
-  model?: RegExp | string;
-  system?: RegExp | string;
-  user?: RegExp | string;
+  model?: TextFilter;
+  system?: TextFilter;
+  user?: TextFilter;
   tools?: string[];
 }
-declare function buildReply(data: unknown): InterceptResponse;
+declare function buildReply(data: unknown): ContractResponse;
 /**
  * Anthropic API intercept helpers.
  */
 declare 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.
@@ -1723,15 +2101,16 @@ declare const anthropic: {
    * @example
    *   anthropic.messages()
    *   anthropic.messages({ system: /classify/ })
+   *   anthropic.messages({ user: buildPrompt() })   // string = EXACT equality
    *   anthropic.messages({ user: /classify/ }, GATEWAY)
    */
-  messages(filter?: AnthropicMessagesFilter, url?: string): InterceptTrigger;
+  messages(filter?: AnthropicMessagesFilter, url?: string): ContractRequest;
   /** Response: wrap data in Anthropic messages format. */
   reply: typeof buildReply;
   /** Response: return an Anthropic error. */
-  error(status: number, message?: string): InterceptResponse;
+  error(status: number, message?: string): ContractResponse;
   /** Response: simulate a timeout. */
-  timeout(): InterceptResponse;
+  timeout(): ContractResponse;
 };
 //#endregion
 //#region src/core/contracts/http.d.ts
@@ -1739,7 +2118,7 @@ declare const anthropic: {
  * Request filters for the generic HTTP provider. Every field is a subset
  * constraint — a request matches when all provided fields match.
  */
-interface HttpInterceptFilter {
+interface HttpContractFilter {
   /**
    * Body constraint. An object is a deep SUBSET match (toMatchObject-style)
    * whose leaf values may be `match.*` matchers; a string is a containment
@@ -1751,58 +2130,78 @@ interface HttpInterceptFilter {
   /** Query-param subset. string = exact value, RegExp = `test()`. */
   query?: Record<string, RegExp | string>;
 }
+/** Init options shared by the response builders. */
+interface HttpResponseInit {
+  /** Delay in ms before responding (for timeout testing). */
+  delay?: number;
+  /** Response headers, merged over the builder's own. */
+  headers?: Record<string, string>;
+  /** HTTP status code. */
+  status?: number;
+}
 /**
- * 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() })
  */
 declare const http: {
-  get(url: RegExp | string, filter?: HttpInterceptFilter): InterceptTrigger;
-  post(url: RegExp | string, filter?: HttpInterceptFilter): InterceptTrigger;
-  put(url: RegExp | string, filter?: HttpInterceptFilter): InterceptTrigger;
-  delete(url: RegExp | string, filter?: HttpInterceptFilter): InterceptTrigger;
-  any(url: RegExp | string, filter?: HttpInterceptFilter): InterceptTrigger;
-  /** Response: simple JSON success. */
-  json(data: unknown, status?: number): InterceptResponse;
-  /** Response: error with message. */
-  error(status: number, message?: string): InterceptResponse;
+  any(url: RegExp | string, filter?: HttpContractFilter): ContractRequest;
+  delete(url: RegExp | string, filter?: HttpContractFilter): ContractRequest;
+  get(url: RegExp | string, filter?: HttpContractFilter): ContractRequest;
+  patch(url: RegExp | string, filter?: HttpContractFilter): ContractRequest;
+  post(url: RegExp | string, filter?: HttpContractFilter): ContractRequest;
+  put(url: RegExp | string, filter?: HttpContractFilter): ContractRequest;
+  /** Response: a body-less reply (204 by default). */
+  empty(status?: number): ContractResponse;
+  /** Response: an error status. Without a body, `{ error: 'HTTP <status>' }`. */
+  error(status: number, body?: unknown): ContractResponse;
+  /** Response: a JSON body (200 by default). */
+  json(body: unknown, init?: HttpResponseInit): ContractResponse;
+  /** Response: a text body, served as `text/plain` (200 by default). */
+  text(body: string, init?: HttpResponseInit): ContractResponse;
 };
 //#endregion
 //#region src/integrations/openai/openai.d.ts
 interface OpenAIChatFilter {
-  model?: RegExp | string;
-  system?: RegExp | string;
-  user?: RegExp | string;
+  model?: TextFilter;
+  system?: TextFilter;
+  user?: TextFilter;
   tools?: string[];
   temperature?: number;
 }
 interface OpenAIResponsesFilter {
-  model?: RegExp | string;
-  system?: RegExp | string;
-  user?: RegExp | string;
+  model?: TextFilter;
+  system?: TextFilter;
+  user?: TextFilter;
   tools?: string[];
 }
-declare function buildChatReply(data: unknown): InterceptResponse;
+declare function buildChatReply(data: unknown): ContractResponse;
 /**
  * OpenAI API intercept helpers.
  */
 declare 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?: OpenAIChatFilter): InterceptTrigger;
+  chat(filter?: OpenAIChatFilter): ContractRequest;
   /**
-   * 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.
    *
@@ -1812,7 +2211,7 @@ declare const openai: {
    * @example
    *   openai.responses({ user: /Report Ingestion/ }, GATEWAY)
    */
-  responses(filter?: OpenAIResponsesFilter, url?: string): InterceptTrigger;
+  responses(filter?: OpenAIResponsesFilter, url?: string): ContractRequest;
   /**
    * Response: wrap data in Chat Completions format.
    *
@@ -1821,11 +2220,11 @@ declare const openai: {
    */
   reply: typeof buildChatReply;
   /** Response: return an OpenAI error. */
-  error(status: number, message?: string): InterceptResponse;
+  error(status: number, message?: string): ContractResponse;
   /** Response: return malformed content. */
-  malformed(content: string): InterceptResponse;
+  malformed(content: string): ContractResponse;
   /** Response: simulate a timeout. */
-  timeout(): InterceptResponse;
+  timeout(): ContractResponse;
 };
 //#endregion
 //#region src/vitest/mock-of.d.ts
@@ -1891,4 +2290,4 @@ declare module 'vitest' {
   }
 }
 //#endregion
-export { type ApiHandle, type ApiSpecification, type ApiSpecificationOptions, BaseResult, type BrowserConsoleMessage, type BrowserLinkElement, type BrowserMetaElement, type BrowserOpenOptions, type BrowserPage, type BrowserPort, type CaptureScope, type CliEnv, type CliHandle, type CliOutput, type CliPort, CliResult, type CliSpecification, type CliSpecificationOptions, ContainerAccessor, type ContainerPort, type DatabaseKeys, type DatabasePort, DirectoryAccessor, type DockerSpecConfig, type ElementKind, type ElementMatch, type ElementOptions, type ElementRef, type ExecOptions, FetchResult, type FileAccessor, FilesystemAccessor, type HonoApp, HttpResult, type InterceptContract, type InterceptEntry, type InterceptResponder, type InterceptResponse, type InterceptResponseValue, type InterceptTrigger, type IsolationStrategy, type JobHandle, type JobsHandle, type JobsSpecification, type JobsSpecificationOptions, JsonAccessor, type LandmarkKind, type MatchFixtureOptions, type MatchableRequest, Matcher, type MatcherKind, type MockDatePort, type MockPort, Orchestrator, PageResult, type PostgresOptions, type RedisOptions, ResponseAccessor, type ServeOptions, type ServerPort, type ServerResponse, type ServiceHandle, type ServiceRecord, type SpecificationConfig, type SpecificationMode, type SqliteOptions, TableAccessor, TextAccessor, type VisitScenario, type Visitor, type WebsiteHandle, type WebsiteSpecification, type WebsiteSpecificationOptions, 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 { type ApiHandle, type ApiSpecification, type ApiSpecificationOptions, BaseResult, type BrowserConsoleMessage, type BrowserLinkElement, type BrowserMetaElement, type BrowserOpenOptions, type BrowserPage, type BrowserPort, type CaptureScope, type CliEnv, type CliHandle, type CliOutput, type CliPort, CliResult, type CliSpecification, type CliSpecificationOptions, ContainerAccessor, type ContainerPort, type Contract, type ContractInput, type ContractRequest, type ContractResponder, type ContractResponse, type ContractResponseValue, type Contracts, type DatabaseKeys, type DatabasePort, type DeviceOpenOptions, type DevicePort, type DeviceScreen, DirectoryAccessor, type DockerSpecConfig, type ElementKind, type ElementMatch, type ElementOptions, type ElementRef, type ExecOptions, FetchResult, type FileAccessor, FilesystemAccessor, type HonoApp, type HttpContractFilter, type HttpResponseInit, HttpResult, type IsolationStrategy, type JobHandle, type JobsHandle, type JobsSpecification, type JobsSpecificationOptions, JsonAccessor, type LandmarkKind, type MatchFixtureOptions, type MatchableRequest, Matcher, type MatcherKind, type MobileBackendOptions, type MobileElementKind, type MobileElementMatch, type MobileElementRef, type MobileHandle, type MobileScenario, type MobileSpecification, type MobileSpecificationOptions, type MobileVisitor, type MockDatePort, type MockPort, Orchestrator, PageResult, type PostgresOptions, type RedisOptions, ResponseAccessor, type ScreenNode, ScreenResult, type ServeOptions, type ServerPort, type ServerResponse, type ServiceHandle, type ServiceRecord, type SpecificationConfig, type SpecificationMode, type SqliteOptions, TableAccessor, TextAccessor, type TextFilter, type VisitScenario, type Visitor, type WebsiteBackendOptions, type WebsiteHandle, type WebsiteSpecification, type WebsiteSpecificationOptions, 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 };