@jterrazz/test 9.2.1 → 10.1.0

package/dist/index.d.ts

@@ -497,15 +497,53 @@ interface InterceptContract {
 declare function defineContract(contract: InterceptContract): InterceptContract;
 //#endregion
 //#region src/core/ports/browser.port.d.ts
+/**
+ * The landmark roles — the standard set of page regions, and the only
+ * containers a scope can name. Closed on purpose: ARIA defines exactly these,
+ * so `within()` never becomes a second selector language.
+ */
+type LandmarkKind = 'banner' | 'complementary' | 'contentinfo' | 'form' | 'main' | 'navigation' | 'region' | 'search';
+/** The interactive//textual element kinds — what a visitor actually acts on. */
+type ElementKind = 'button' | 'field' | 'heading' | 'link' | 'testId' | 'text';
 /**
  * A user-facing element descriptor — pure data, built by the element
  * vocabulary (`button()`, `link()`, `field()`, …) and translated into
  * concrete locators by the browser integration. CSS/XPath selectors are
  * deliberately not expressible: user-facing elements are the only surface.
+ *
+ * A descriptor must designate exactly ONE element at action time; see
+ * {@link ElementMatch} and CONVENTIONS W3.
  */
 interface ElementRef {
-  kind: 'button' | 'field' | 'heading' | 'link' | 'testId' | 'text';
-  name: string;
+  /**
+   * Match the accessible name as a whole string rather than a substring.
+   * Default (`false`) mirrors playwright: `link('Articles')` also matches
+   * "Read Articles".
+   */
+  exact?: boolean;
+  kind: ElementKind | LandmarkKind;
+  /** Landmarks may be anonymous (`main()`, `banner()`); everything else is named. */
+  name?: string;
+  /**
+   * Restrict the search to the elements of another descriptor — built by
+   * `within(scope, target)`. Chains: a scope may itself carry a scope.
+   */
+  scope?: 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 a browser.
+ */
+interface ElementMatch {
+  /** Nearest landmark ancestor (`nav`, `footer`, `main`…), when there is one. */
+  context?: string;
+  /** The attribute that disambiguates most — `href` for links, `name` for fields. */
+  detail?: string;
+  /** Tag name, lower-cased. */
+  tag: string;
+  /** Text content, whitespace-collapsed and truncated. */
+  text: string;
 }
 /** A `<link>` element captured from the rendered document's head. */
 interface BrowserLinkElement {
@@ -553,6 +591,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.
@@ -606,6 +649,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.
@@ -733,6 +877,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 {
@@ -810,6 +975,78 @@ declare class PageResult extends BaseResult {
   get url(): string;
 }
 //#endregion
+//#region src/core/http-files/intercept-file.d.ts
+/** The declared request half of an exchange — the matching trigger. */
+interface ExchangeRequest {
+  /** Declared header subset — names case-insensitive, values may carry `{{token}}`s. */
+  headers: Record<string, string>;
+  method: string;
+  /** Path as written, query string included (`/articles?event_id=…`). */
+  path: string;
+}
+/** The declared response half of an exchange — the stubbed reply. */
+interface ExchangeResponse {
+  /** Parsed JSON body — or the raw text when the body is not valid JSON. */
+  body: unknown;
+  /** True when a body section is present. */
+  hasBody: boolean;
+  headers: Record<string, string>;
+  status: number;
+}
+/** One declared request/response pair of an `intercepts/*.http` file. */
+interface InterceptExchange {
+  request: ExchangeRequest;
+  response: ExchangeResponse;
+}
+//#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 {
+  private consumed;
+  private entries;
+  /** Guarded once the current chain declared at least one intercept. */
+  private guarded;
+  private readonly options;
+  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 exchanges replace the previous
+   * chain's wholesale, consumption restarts, and the unmatched log clears —
+   * the reset-between-chains databases already follow.
+   */
+  beginChain(exchanges: InterceptExchange[]): void;
+  /**
+   * The strict failure for the chain, or null — non-null when the chain
+   * declared at least one intercept AND an unmatched request was recorded.
+   * Enumerates every unmatched request (method, path, count) plus the
+   * declared routes, so the missing exchange writes itself.
+   */
+  violation(): Error | null;
+  private corsHeaders;
+  private describeRoutes;
+  private handle;
+  private record;
+  /**
+   * FIFO with a sticky tail: the first unconsumed matching exchange is
+   * consumed; when every matching exchange is spent, the LAST one keeps
+   * replying.
+   */
+  private take;
+}
+//#endregion
 //#region src/core/specification/shared/builder.d.ts
 /** A named job that can be triggered via jobs.trigger(). */
 interface JobHandle {
@@ -829,6 +1066,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 `.http` intercept exchanges 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;
   /**
@@ -843,6 +1090,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;
   /**
@@ -852,6 +1101,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.
@@ -891,8 +1147,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>);
+  /** Intercept an outgoing HTTP call — a contract, an array of contracts, an `intercepts/*.http` file, or a trigger + response pair. */
+  intercept: ((contractOrContracts: InterceptContract | InterceptContract[] | string) => ApiSpecification<DatabaseKey>) & ((trigger: InterceptTrigger, response: InterceptResponder | InterceptResponse | string) => ApiSpecification<DatabaseKey>);
   /** Queue a SQL seed file from `seeds/` to run before the action. */
   seed: (file: string, options?: {
     database?: DatabaseKey;
@@ -913,8 +1169,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>);
+  /** Intercept an outgoing HTTP call — a contract, an array of contracts, an `intercepts/*.http` file, or a trigger + response pair. */
+  intercept: ((contractOrContracts: InterceptContract | InterceptContract[] | string) => JobsSpecification<DatabaseKey>) & ((trigger: InterceptTrigger, response: InterceptResponder | InterceptResponse | string) => JobsSpecification<DatabaseKey>);
   /** Queue a SQL seed file from `seeds/` to run before the action. */
   seed: (file: string, options?: {
     database?: DatabaseKey;
@@ -960,6 +1216,12 @@ 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 exchanges from an `intercepts/<name>.http`
+   * file — served by the declared stub backend (requires the runner's
+   * `backend` option). Multiple calls layer in order.
+   */
+  intercept: (file: string) => WebsiteSpecification;
   /** Perform one raw HTTP GET — redirects surface as 3xx results, never followed. */
   fetch: (path: string) => Promise<FetchResult>;
   /**
@@ -969,6 +1231,26 @@ 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 exchanges from an `intercepts/<name>.http`
+   * file — served by the declared stub backend (requires the runner's
+   * `backend` option). Multiple calls layer in order.
+   */
+  intercept: (file: string) => 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
 /**
@@ -1320,6 +1602,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 exchanges
+   * each chain declares via `.intercept('<name>.http')`. 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 {
@@ -1334,11 +1682,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 chain's
+ * `.intercept('<name>.http')` exchanges 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 = {
   /**
@@ -1353,6 +1715,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
+   * exchanges each chain declares via `.intercept('<name>.http')`.
+   */
+  backend?: WebsiteBackendOptions;
   /**
    * Start the site locally: a shell command receiving a free port
    * as `PORT`, polled on `ready` (default `/`) until it answers.
@@ -1360,6 +1728,7 @@ type WebsiteSpecificationOptions = {
   server: ServeOptions;
   url?: never;
 } | {
+  backend?: never;
   server?: never;
   /** Target an already-running site (a deployed or preview URL). */
   url: string;
@@ -1381,7 +1750,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).
  *
@@ -1424,6 +1793,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.
@@ -1468,19 +1844,63 @@ interface ContainerPort {
  * Reads like English (`click(link('Articles'))`), translates to
  * accessibility-first locators in the browser integration. CSS/XPath is
  * deliberately not expressible; `testId()` is the single escape hatch.
+ *
+ * A descriptor must designate exactly ONE element (CONVENTIONS W3). Two knobs
+ * narrow it, in this order of preference:
+ *
+ *   1. `within(scope, target)` — search inside a landmark, the way a person
+ *      would say "the Articles link *in the nav*";
+ *   2. `{ exact: true }` — match the accessible name whole rather than as a
+ *      substring, when two names genuinely overlap.
  */
+/** Options accepted by every named descriptor. */
+interface ElementOptions {
+  /**
+   * Match the accessible name as a whole string. Default is substring —
+   * `link('Articles')` also matches "Read Articles".
+   */
+  exact?: boolean;
+}
 /** A button (or element with the button role), by accessible name. */
-declare const button: (name: string) => ElementRef;
+declare const button: (name: string, options?: ElementOptions) => ElementRef;
 /** A form field, by label. */
-declare const field: (label: string) => ElementRef;
+declare const field: (name: string, options?: ElementOptions) => ElementRef;
 /** A heading, by accessible name. */
-declare const heading: (name: string) => ElementRef;
+declare const heading: (name: string, options?: ElementOptions) => ElementRef;
 /** A link, by accessible name. */
-declare const link: (name: string) => ElementRef;
+declare const link: (name: string, options?: ElementOptions) => ElementRef;
 /** An element containing the given text. */
-declare const content: (value: string) => ElementRef;
+declare const content: (name: string, options?: ElementOptions) => ElementRef;
 /** The escape hatch: an element by `data-testid`. Prefer user-facing elements. */
 declare const testId: (id: string) => ElementRef;
+/** The `banner` landmark — the page header. */
+declare const banner: (name?: string, options?: ElementOptions) => ElementRef;
+/** The `complementary` landmark — an `<aside>`, a sidebar. */
+declare const complementary: (name?: string, options?: ElementOptions) => ElementRef;
+/** The `contentinfo` landmark — the page footer. */
+declare const contentinfo: (name?: string, options?: ElementOptions) => ElementRef;
+/** The `form` landmark — a form carrying an accessible name. */
+declare const form: (name?: string, options?: ElementOptions) => ElementRef;
+/** The `main` landmark — the primary content of the document. */
+declare const main: (name?: string, options?: ElementOptions) => ElementRef;
+/** The `navigation` landmark — a `<nav>`. Name it when a page has several. */
+declare const navigation: (name?: string, options?: ElementOptions) => ElementRef;
+/** The `region` landmark — a `<section>` carrying an accessible name. */
+declare const region: (name?: string, options?: ElementOptions) => ElementRef;
+/** The `search` landmark. */
+declare const search: (name?: string, options?: ElementOptions) => ElementRef;
+/**
+ * Restrict a descriptor to the inside of another — the answer to ambiguity,
+ * and the one the framework prefers over a test id.
+ *
+ *     click(within(navigation(), link('Articles')))
+ *
+ * Composes outside-in: the scope may itself be scoped, so a deeply nested
+ * target reads `within(main(), within(region('Series'), link('Part 2')))`.
+ * Any descriptor works as a scope, including `testId()` when a container has
+ * no landmark role to stand on.
+ */
+declare const within: (scope: ElementRef, target: ElementRef) => ElementRef;
 //#endregion
 //#region src/integrations/postgres/postgres.d.ts
 interface PostgresOptions {
@@ -1809,4 +2229,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 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 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, button, content, defineContract, field, findContainersByLabel, heading, http, inspectContainer, link, match, mockOf, mockOfDate, openai, postgres, redis, removeContainers, specification, sqlite, testId, text };
+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, 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, 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 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 VisitScenario, type Visitor, type WebsiteBackendOptions, 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 };