@jterrazz/test 15.1.0 → 15.2.0

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import { Scalar } from "yaml";
 import { DeepMockProxy } from "vitest-mock-extended";
+import { ReactNode as ComponentUi } from "react";
+import "vitest/browser";
 //#region src/specification/matching/match.d.ts
 /**
  * Code-side dynamic-value matchers (`match.*`) and the capture scope shared
@@ -161,6 +163,16 @@ type ContractResponse = {
   headers?: Record<string, string> | undefined;
   /** Delay in ms before responding (for timeout testing). */
   delay?: number | undefined;
+  /**
+   * A transport failure instead of a reply: the request never reached a
+   * server, so `fetch` rejects. `status`, `body` and `headers` say nothing
+   * here — there is no response to carry them.
+   *
+   * The one thing a status code cannot express. A component's "the server did
+   * not answer, check that it is running" branch is reached by a rejected
+   * `fetch`, and a 503 stand-in tests the other branch entirely.
+   */
+  transport?: 'network-error' | undefined;
 };
 /**
  * A dynamic response: computed from the observed request at the moment the
@@ -267,8 +279,15 @@ declare function defineContracts(...items: ContractInput[]): Contracts;
  * 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';
+/**
+ * The interactive/textual element kinds — what a visitor actually acts on.
+ *
+ * `dialog`, `status`, `table`, `row`, `listitem` and `option` are ARIA roles
+ * like the landmarks, but they are not CONTAINERS of a page: they are things a
+ * visitor reads and acts on, and they are the roles the estate's UI specs were
+ * already reaching for through `getByRole` or, worse, through `.first()`.
+ */
+type ElementKind = 'button' | 'dialog' | 'field' | 'heading' | 'link' | 'listitem' | 'option' | 'row' | 'status' | 'table' | 'testId' | 'text';
 /**
  * A user-facing element descriptor — pure data, built by the element
  * vocabulary (`button()`, `link()`, `field()`, …) and translated into
@@ -285,9 +304,37 @@ type ElementRef = {
    * "Read Articles".
    */
   exact?: boolean;
+  /**
+   * Assert about the element's FOCUS rather than its presence — built by
+   * `focused(element)`. The accessibility tree carries no focus state, so
+   * where the keyboard is cannot be goldened; it is asserted by a verb.
+   */
+  focused?: boolean;
+  /**
+   * Narrows to "and it is (not) accepting input" — built by `disabled(x)` /
+   * `enabled(x)`. Like `focused`, a STATE the vocabulary can already name the
+   * element of; unlike it, one the ARIA tree carries too (`[disabled]`), so
+   * this modifier is what names the ONE control a test is about, and it
+   * reaches the direction a behavioural substitute cannot — clicking a
+   * disabled control is a timeout, never an answer.
+   */
+  disabled?: boolean;
   kind: ElementKind | LandmarkKind;
   /** Landmarks may be anonymous (`main()`, `banner()`); everything else is named. */
   name?: string;
+  /**
+   * Narrows to "and it is (not) the chosen one" — built by `selected(x)`.
+   * An option of a COLLAPSED select is in the tree and in the document, and
+   * it has no box on the screen, so this facet of it is read from the node
+   * (`:checked`) rather than from what a visitor could point at.
+   */
+  selected?: boolean;
+  /**
+   * The value the field must hold — built by `valued(field('Title'), '…')`.
+   * A field's value is a PROPERTY of the node: a controlled input's `value`
+   * attribute never moves, so nothing but the live value answers for it.
+   */
+  value?: string;
   /**
    * Restrict the search to the elements of another descriptor — built by
    * `within(scope, target)`. Chains: a scope may itself carry a scope.
@@ -300,6 +347,12 @@ type ElementRef = {
  * without opening a browser.
  */
 type ElementMatch = {
+  /**
+   * The accessible name, when it differs from the text — an `aria-label` is
+   * what a role descriptor MATCHED on, and printing the text alone sends the
+   * author to disambiguate a name they cannot see.
+   */
+  accessibleName?: string | undefined;
   /** Nearest landmark ancestor (`nav`, `footer`, `main`…), when there is one. */
   context?: string | undefined;
   /** The attribute that disambiguates most — `href` for links, `name` for fields. */
@@ -340,6 +393,12 @@ type Visitor = {
   click: (element: ElementRef) => Promise<void>;
   /** Fill a form field with a value. */
   fill: (element: ElementRef, value: string) => Promise<void>;
+  /**
+   * Wait until the element is GONE — hidden, or never in the document. The
+   * absence primitive: `see()` cannot answer "the dialog closed", because an
+   * element that never appears and one that disappeared read the same to it.
+   */
+  gone: (element: ElementRef) => Promise<void>;
   /** Navigate to a path of the site under test. */
   goto: (path: string) => Promise<void>;
   /** Hover the element. */
@@ -396,6 +455,8 @@ type BrowserPage = {
   status: number;
   /** Rendered `document.body.innerText`. */
   text: string;
+  /** The ARIA snapshot of the rendered `<body>` — the outline a golden pins. */
+  tree: string;
   /** `document.title` after rendering. */
   title: string;
   /** Final URL after redirects and scenario navigation. */
@@ -813,24 +874,6 @@ declare class TextAccessor {
   toString(): string;
   valueOf(): string;
 }
-/**
- * Wrap an arbitrary string into a {@link TextAccessor} anchored on the calling
- * test's directory — the same caller-detection the builders use.
- *
- * The product surface of a test framework is its own error messages, checker
- * output, and reports; those deserve the same goldening as any other output.
- * `text()` makes an ad-hoc string a first-class snapshot subject:
- *
- * ```typescript
- * const message = await catchMessage(() => expect(result.response).toMatch('wrong-body.http'));
- * expect(text(message)).toMatch('wrong-body-error.txt'); // resolves to _expected/
- * ```
- *
- * ANSI is stripped before every comparison (the raw form stays on `.text`),
- * the `{{token}}` grammar applies to the fixture, and `.grep()` composition
- * works exactly as on any stream accessor.
- */
-declare function text(value: string): TextAccessor;
 //#endregion
 //#region src/specification/facets/cli/result.d.ts
 /**
@@ -1027,6 +1070,13 @@ declare class PageResult extends BaseResult {
   get status(): number;
   /** Rendered body text as a text accessor. */
   get content(): TextAccessor;
+  /**
+   * The ARIA snapshot of the rendered `<body>` — the page's outline, as the
+   * accessibility tree draws it, and the one golden a rendered surface pins.
+   * Deterministic where a screenshot is not, and the SAME dialect a component
+   * spec asserts, so a page and the components inside it read alike.
+   */
+  get tree(): TextAccessor;
   /** The document title as a text accessor. */
   get title(): TextAccessor;
   /** Final URL after redirects. */
@@ -1441,7 +1491,16 @@ declare class ContainerAccessor {
   private containerExec;
 }
 //#endregion
-//#region src/vitest/matchers.d.ts
+//#region src/specification/facets/_common/result/match-options.d.ts
+/**
+ * The per-call option both `toMatch` implementations honour.
+ *
+ * A golden is read from disk under node and through a server command from
+ * inside a page, and BOTH builds must answer `{ frozen: true }` the same way —
+ * so the option is declared here, where the node matchers and the page's
+ * matchers can each reach it, rather than in the runner's own folder, which a
+ * seam may not import (rule I1).
+ */
 /**
  * Per-call options for the fixture-file `toMatch` subjects. `frozen` opts a
  * single fixture OUT of update-mode rewriting: a frozen fixture is NEVER
@@ -1456,194 +1515,707 @@ type MatchFixtureOptions = {
   frozen?: boolean;
 };
 //#endregion
-//#region src/specification/facets/_common/orchestrator.d.ts
-type OrchestratorOptions = {
-  /**
-   * Named infrastructure record. Keys become the database vocabulary of the
-   * spec (`.seed()` / `.table()` `database` option) and drive the compose
-   * binding: a handle with no explicit `composeService` links to the compose
-   * service named exactly like its key, else the kebab-case conversion of the
-   * key (`analyticsDb` → `analytics-db`) — see {@link resolveComposeBinding}.
-   */
-  services: Record<string, ServiceHandle>;
-  mode: 'e2e' | 'integration';
-  /**
-   * The project root, already resolved. REQUIRED: the constructors derive it
-   * by walking up from the calling specification file (CONVENTIONS A9), and
-   * the orchestrator is handed the answer. Defaulting to `process.cwd()` here
-   * meant one silent second opinion about what the project is — the runner
-   * resolving from the caller, this from wherever the runner happened to be
-   * launched, which in a workspace is rarely the same directory.
-   */
-  root: string;
-  /** Compose project name — used for per-worker stack isolation. */
-  projectName?: string;
-};
+//#region src/integrations/vitest-browser/ui.d.ts
 /**
- * Orchestrator for test infrastructure.
- * Integration: starts services via testcontainers.
- * E2E: runs full docker compose up.
+ * A vanilla DOM subject: a function handed the container it must fill. Its
+ * optional return is the teardown, the way a DOM library states one.
  */
-declare class Orchestrator {
-  private readonly services;
-  private readonly mode;
-  private readonly root;
-  private readonly projectName;
-  private running;
-  private composeStack;
-  private composeHandles;
-  private started;
-  constructor(options: OrchestratorOptions);
-  /**
-   * Bind each declared handle to a compose service (CONVENTIONS A6): a record
-   * key resolves to the service named exactly like it, else the kebab-case
-   * conversion of the key; an explicit `composeService` wins. Throws on an
-   * ambiguous binding (both names present). Runs once compose config is known
-   * so the two-step resolution can consult the real service list.
-   */
-  private resolveBindings;
-  /**
-   * Start declared services via testcontainers (integration mode).
-   * Phase 1: start all containers in parallel (the slow part).
-   * Phase 2: wire connections, healthcheck, and init sequentially (fast).
-   */
-  start(): Promise<void>;
-  /**
-   * Stop testcontainers (integration mode).
-   */
-  stop(): Promise<void>;
-  /**
-   * Start full docker compose stack (e2e mode).
-   * Auto-detects infra services and creates handles for them.
-   */
-  startCompose(): Promise<void>;
-  /**
-   * Stop docker compose stack (e2e mode).
-   */
-  stopCompose(): Promise<void>;
-  /**
-   * Get the default database — the first declared handle that is one.
-   */
-  getDatabase(): DatabasePort | null;
-  /**
-   * Get all database services keyed by their record key (declared services)
-   * or compose service name (stack-detected services).
-   */
-  getDatabases(): Map<string, DatabasePort>;
-  private allHandles;
-  /**
-   * Get app URL from compose (e2e mode).
-   */
-  getAppUrl(): null | string;
+type DomMount = (container: HTMLElement) => (() => void) | void;
+/**
+ * The `server.commands` this seam registers, declared in the module every part
+ * of the seam already imports.
+ *
+ * A `declare module` merges only as an interface, and only from a file that is
+ * itself a module and part of the program — a lone `.d.ts` would have to be
+ * pulled in by an empty import, and its single `export {}` is exactly what a
+ * formatter is free to drop, turning the augmentation into an ambient
+ * declaration that SHADOWS the module it meant to extend.
+ */
+declare module 'vitest/browser' {
+  interface BrowserCommands {
+    ariaTree: () => Promise<string>;
+    goldenRead: (name: string) => Promise<null | string>;
+    goldenWrite: (name: string, content: string) => Promise<string>;
+  }
 }
 //#endregion
-//#region src/specification/facets/_common/services.d.ts
+//#region src/integrations/vitest-browser/vitest-browser.adapter.d.ts
+/** What a mounted subject offers the chain, React or vanilla DOM alike. */
+type MountedSurface = {
+  /** The element the subject was mounted into. */
+  container: HTMLElement;
+  /** Replace the rendered tree — a prop change, as a parent makes one. */
+  rerender: (ui: ComponentUi) => Promise<void>;
+  /** Take it off the screen, as a parent does. */
+  unmount: () => Promise<void>;
+};
+/** The verbs a rendered surface shares with a page, plus the two a parent owns. */
+declare function componentVerbs(surface: MountedSurface): {
+  check: (element: ElementRef) => Promise<void>;
+  click: (element: ElementRef) => Promise<void>;
+  fill: (element: ElementRef, value: string) => Promise<void>;
+  gone: (element: ElementRef) => Promise<void>;
+  hover: (element: ElementRef) => Promise<void>;
+  press: (key: string) => Promise<void>;
+  rerender: (ui: ComponentUi) => Promise<void>;
+  see: (element: ElementRef) => Promise<void>;
+  select: (element: ElementRef, option: string) => Promise<void>;
+  unmount: () => Promise<void>;
+};
+//#endregion
+//#region src/specification/facets/component/rendered-text.d.ts
 /**
- * Infrastructure services declared as a named record. Keys become the typed
- * vocabulary of the whole spec: the server factory receives the same record,
- * and `.seed()` / `.table()` target databases by key.
- */
-type ServiceRecord = Record<string, ServiceHandle>;
-/** Keys of a services record whose handles are databases. */
-type DatabaseKeys<Services extends ServiceRecord> = { [K in keyof Services]: Services[K] extends DatabasePort ? K & string : never; }[keyof Services];
+ * A stream captured INSIDE the page.
+ *
+ * Structurally identical to any other {@link TextAccessor} — the same
+ * `{{token}}` grammar, the same ANSI stripping, the same `.grep()` — and
+ * marked so the matcher augmentation can say the one thing that differs: its
+ * golden lives on the server, so `toMatch` is awaited here where it is
+ * synchronous everywhere else.
+ */
+declare class RenderedText extends TextAccessor {
+  /** The marker the `toMatch` overload reads. Never asserted on directly. */
+  readonly capturedInPage: true;
+}
 //#endregion
-//#region src/specification/facets/api/start-api.d.ts
-/** Any object with a request method compatible with Hono's app.request(). */
-type HonoApp = {
-  request: (path: string, init?: RequestInit) => Promise<Response> | Response;
-};
-/** Execution mode — exists ONLY on `specification.api()` (CONVENTIONS A5). */
-type SpecificationMode = 'compose' | 'node';
-/** Options for {@link startApi | specification.api}. */
-type ApiSpecificationOptions<Services extends ServiceRecord = ServiceRecord> = {
-  /**
-   * Execution mode override. Resolution: `options.mode` >
-   * `process.env.TEST_MODE` > `'node'`. Never hardcode this in a
-   * specification file when `server` is defined — set it per vitest
-   * project via `env: { TEST_MODE: 'compose' }` (CONVENTIONS A5).
-   */
-  mode?: SpecificationMode;
+//#region src/specification/facets/component/component.result.d.ts
+/**
+ * What a render resolves to — the component as the page saw it, after the
+ * scenario ran.
+ *
+ * Five accessors and no more: the ARIA outline a golden pins, the two
+ * renderings a probe reads, and the two streams a spec wants silent. Nothing
+ * here reaches back into React — a spec that needs the component's internals
+ * is asserting the implementation, not the surface a user meets.
+ */
+declare class RenderResult {
+  /** The browser console as a stream — one `[type] text` line per message. */
+  readonly console: RenderedText;
+  /** Rendered text of the whole document body (`innerText`). */
+  readonly content: RenderedText;
+  /** Console messages of type `error` only, plus any uncaught page error. */
+  readonly errors: RenderedText;
+  /** The mounted markup, serialised — the escape hatch for a class or an attribute. */
+  readonly html: RenderedText;
+  /** The ARIA snapshot of the rendered body — the outline a golden pins. */
+  readonly tree: RenderedText;
+  constructor(streams: {
+    console: string;
+    content: string;
+    errors: string;
+    html: string;
+    tree: string;
+  });
+}
+//#endregion
+//#region src/specification/facets/component/component.types.d.ts
+/**
+ * The component facet's shape, stated where BOTH runtimes can read it.
+ *
+ * The page gets the working chain; node gets a stub under the same name and
+ * the same type, so a component test that ran in the wrong project fails on
+ * the line that rendered rather than on a missing export. The published types
+ * are the node build's, so this file is the one description of the facet.
+ */
+/** The interaction vocabulary a render scenario is handed — the When. */
+type ComponentVisitor = ReturnType<typeof componentVerbs>;
+/** The behaviour of a render; assertions stay in the Then, on the result (W1). */
+type ComponentScenario = (visitor: ComponentVisitor) => Promise<void>;
+/**
+ * What `.render()` mounts. A React tree is an element (`<PostTable />`); a
+ * vanilla DOM subject is the FUNCTION that fills a container, which is how a
+ * DOM-only module is called in production too.
+ */
+type RenderSubject = ComponentUi | DomMount;
+/**
+ * The chain. Every setup returns a new one, so the handle a spec imports never
+ * carries the previous test's contracts, wrapper or clock.
+ */
+type ComponentChain = {
+  /** Pin the page's `Date` for this render — the clock the component reads. */
+  clock: (iso: string) => ComponentChain;
   /**
-   * Project root override for compose detection and init scripts. When
-   * absent, the root is auto-discovered by walking up from the calling
-   * specification file to the first directory containing
-   * `docker/compose.test.yaml`, else the first containing `package.json`
-   * (CONVENTIONS A9).
+   * Declare what the network replies — the same contracts, the same queue
+   * and the same strictness as every other facet (D7), served by msw's
+   * worker instead of its node interceptor.
    */
-  root?: string;
+  intercept: {
+    (contracts: ContractInput): ComponentChain;
+    (request: ContractRequest, response: ContractResponder | ContractResponse): ComponentChain;
+  };
+  /** Mount the subject, run the scenario, and capture what the page shows. */
+  render: (subject: RenderSubject, scenario?: ComponentScenario) => Promise<RenderResult>;
   /**
-   * The app factory — receives the started services record (fully typed)
-   * and returns the Hono app. Required in node mode, ignored in compose
-   * mode (the app runs as a compose service there).
+   * The page size THIS render gets — the Given of a component that reads
+   * `matchMedia` or a container query. The project's size is restored when
+   * the test ends, so a narrow render never leaks into the next one.
    */
-  server?: (services: Services) => HonoApp;
+  viewport: (size: {
+    height: number;
+    width: number;
+  }) => ComponentChain;
   /**
-   * Named infrastructure record. Keys become the `database` vocabulary of
-   * `.seed()` / `.table()` and drive the compose binding: a handle with no
-   * `composeService` option links to the compose service named exactly like
-   * its key, else the kebab-case conversion of the key (CONVENTIONS A6).
+   * Wrap every render of this chain — the test-local Given a router stub or
+   * a `<StrictMode>` is. The project's own `wrap` stays outermost: it is the
+   * app's frame, and one test does not get to sit outside it.
    */
-  services?: Services;
+  wrap: (wrapper: (ui: ComponentUi) => ComponentUi) => ComponentChain;
 };
+//#endregion
+//#region src/specification/facets/website/elements.d.ts
 /**
- * The record returned by {@link startApi | specification.api}. Destructure
- * with the canonical names (CONVENTIONS A3):
+ * The element vocabulary — user-facing descriptors for visit scenarios.
+ * 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.
  *
- *     const { api, cleanup, docker } = await specification.api(…);
+ * 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.
  */
-type ApiHandle<DatabaseKey extends string = string> = {
-  api: ApiSpecification<DatabaseKey>;
-  /** Stop all infrastructure started by this specification. */
-  cleanup: () => Promise<void>;
+/** Options accepted by every named descriptor. */
+type ElementOptions = {
   /**
-   * Read a running container by id — returns a {@link ContainerAccessor}
-   * usable with `await expect(...).toBeRunning()` and read accessors.
+   * Match the accessible name as a whole string. Default is substring —
+   * `link('Articles')` also matches "Read Articles".
    */
-  docker: (containerId: string) => ContainerAccessor;
-  /** The orchestrator managing the test infrastructure lifecycle. */
-  orchestrator: Orchestrator;
+  exact?: boolean;
 };
-declare function startApi<Services extends ServiceRecord>(options: ApiSpecificationOptions<Services>): Promise<ApiHandle<DatabaseKeys<Services>>>;
-//#endregion
-//#region src/specification/facets/cli/start-cli.d.ts
-/** Options for {@link startCli | specification.cli}. */
-type CliSpecificationOptions<Services extends ServiceRecord = ServiceRecord> = {
-  /**
-   * Opt-in Docker awareness. When set, every spec generates a unique
-   * test-run id, injects it into the child process env under `envVar`,
-   * and exposes `.container(name)` accessors on the result that lazily
-   * query Docker. Always declare results with `await using` so leaked
-   * containers get force-removed at scope exit (CONVENTIONS B5).
-   */
-  docker?: DockerSpecConfig;
-  /**
-   * Named environment SETS for `<case>.spec.yaml` documents. An `env:` entry
-   * `frozen` applies the whole `frozen` record; `$WORKDIR` expands and `null`
-   * unsets, exactly as in `.env()`. Declared once per app so a document
-   * states WHICH ground it stands on, not how to build it.
-   */
-  env?: Record<string, CliEnv>;
-  /**
-   * Named servers a `<case>.spec.yaml` document may start (`serve: [mcp]`, or
-   * `- mcp: { KEY: value }` to add env to that one). Each entry names the
-   * shell `command`, the `ready` regex whose capture group holds the port the
-   * server announces, the `url(port)` builder, and the `env` variable that
-   * URL is bound to in every run's child.
-   */
-  serve?: Record<string, LiterateServeRegistration>;
-  /**
-   * Project-root override (CONVENTIONS A9) — the single meaning of `root`:
-   * it anchors compose detection and local-bin resolution for the tested
-   * binary. It is NOT a fixtures root; `.fixture()` resolves feature-local
-   * or `$FIXTURES/` paths on its own.
-   */
-  root?: string;
-  /**
-   * Named infrastructure record started via testcontainers. Connection
-   * URLs are injected automatically into the child env: `<KEY>_URL` per
-   * service, plus `DATABASE_URL` / `REDIS_URL` when unambiguous
-   * (CONVENTIONS B6). `.env()` overrides.
-   */
+/** A user-facing element factory — what every name in this module is. */
+type ElementFactory = (name: string, options?: ElementOptions) => ElementRef;
+/** A button (or element with the button role), by accessible name. */
+declare const button: ElementFactory;
+/** A form field, by label. */
+declare const field: ElementFactory;
+/** A heading, by accessible name. */
+declare const heading: ElementFactory;
+/** A link, by accessible name. */
+declare const link: ElementFactory;
+/** An element containing the given text. */
+declare const content: ElementFactory;
+/** The escape hatch: an element by `data-testid`. Prefer user-facing elements. */
+declare const testId: (id: string) => ElementRef;
+/** A landmark factory — the optionally-named containers `within()` accepts. */
+type LandmarkFactory = (name?: string, options?: ElementOptions) => ElementRef;
+/** The `banner` landmark — the page header. */
+declare const banner: LandmarkFactory;
+/** The `complementary` landmark — an `<aside>`, a sidebar. */
+declare const complementary: LandmarkFactory;
+/** The `contentinfo` landmark — the page footer. */
+declare const contentinfo: LandmarkFactory;
+/** The `form` landmark — a form carrying an accessible name. */
+declare const form: LandmarkFactory;
+/** The `main` landmark — the primary content of the document. */
+declare const main: LandmarkFactory;
+/** The `navigation` landmark — a `<nav>`. Name it when a page has several. */
+declare const navigation: LandmarkFactory;
+/** The `region` landmark — a `<section>` carrying an accessible name. */
+declare const region: LandmarkFactory;
+/** The `search` landmark. */
+declare const search: LandmarkFactory;
+/**
+ * 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;
+/** A modal or non-modal `<dialog>`, by accessible name. A closed one is absent. */
+declare const dialog: LandmarkFactory;
+/** A live region announcing a result — `role="status"`, an `<output>`. */
+declare const status: LandmarkFactory;
+/** A table, by its caption or accessible name. */
+declare const table: LandmarkFactory;
+/** A row of a table or grid, by the text of its cells. */
+declare const row: LandmarkFactory;
+/** An item of a list, by its text. Retires the `.first()` of an unnamed `<li>`. */
+declare const listitem: LandmarkFactory;
+/**
+ * An option of a select or a listbox, by its label — named inside the field
+ * that holds it: `within(field('Channel'), option('LinkedIn'))`.
+ *
+ * Asserted by PRESENCE, not by visibility: the options of a collapsed
+ * `<select>` are in the document and in the accessibility tree, and none of
+ * them has a box on the screen until it is opened. `see(option('LinkedIn'))`
+ * therefore asks "is it offered", and `see(selected(option('LinkedIn')))`
+ * asks which one the field is on.
+ */
+declare const option: ElementFactory;
+/**
+ * Where the keyboard is: `see(focused(button('Open')))` asserts the element has
+ * focus, `gone(focused(x))` that it does not.
+ *
+ * A modifier rather than a descriptor of its own, because focus is a STATE of
+ * an element the vocabulary can already name. It is a verb's business and never
+ * a golden's: the accessibility tree carries no focus, so a tree snapshot of a
+ * dialog that took the keyboard and one that did not are byte-identical.
+ */
+declare const focused: (element: ElementRef) => ElementRef;
+/**
+ * Whether the element accepts input: `see(disabled(button('Delete')))` asserts
+ * it refuses, `see(enabled(button('Delete')))` that it takes it.
+ *
+ * Modifiers rather than descriptors, for the same reason as `focused`: being
+ * disabled is a state of an element the vocabulary already names. Unlike focus,
+ * the ARIA tree carries it, so a golden pins a whole outline's enablement and
+ * these name the ONE control a test is about. They also buy the direction a
+ * behavioural substitute cannot reach — clicking a disabled control is a
+ * timeout, never an assertion.
+ */
+declare const disabled: (element: ElementRef) => ElementRef;
+/** The other direction of {@link disabled} — the element takes input. */
+declare const enabled: (element: ElementRef) => ElementRef;
+/**
+ * Which option the field is on: `see(selected(option('LinkedIn')))`, and
+ * `gone(selected(option('X')))` for the one it left.
+ *
+ * A modifier for the same reason as {@link disabled}: being chosen is a state
+ * of an element the vocabulary already names. No matcher answers for it — a
+ * `<option>` is not a checkbox — so both adapters read the `:checked` the CSS
+ * spec gives a selected option.
+ */
+declare const selected: (element: ElementRef) => ElementRef;
+/**
+ * What the field holds: `see(valued(field('Title'), 'Launch teaser'))`, and
+ * `gone(valued(field('Title'), '…'))` for a value it no longer holds.
+ *
+ * A modifier for the same reason as {@link disabled}: what a field holds is a
+ * state of an element the vocabulary already names, and this is how the ONE
+ * field a test is about is waited for — a golden pins a whole outline instead.
+ * Read from the node's live value, never from the `value` ATTRIBUTE, which a
+ * controlled input never moves.
+ */
+declare const valued: (element: ElementRef, value: string) => ElementRef;
+//#endregion
+//#region src/specification/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
+type AnthropicMessagesFilter = {
+  model?: TextFilter;
+  system?: TextFilter;
+  user?: TextFilter;
+  tools?: string[];
+};
+/**
+ * Anthropic API intercept helpers.
+ */
+declare const anthropic: {
+  /**
+   * 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.
+   *
+   * @example
+   *   anthropic.messages()
+   *   anthropic.messages({ system: /classify/ })
+   *   anthropic.messages({ user: buildPrompt() })   // string = EXACT equality
+   *   anthropic.messages({ user: /classify/ }, GATEWAY)
+   */
+  messages(filter?: AnthropicMessagesFilter, url?: string): ContractRequest;
+  /** Response: wrap data in Anthropic messages format. */
+  reply(data: unknown): ContractResponse;
+  /** Response: return an Anthropic error. */
+  error(status: number, message?: string): ContractResponse;
+  /** Response: simulate a timeout. */
+  timeout(): ContractResponse;
+};
+//#endregion
+//#region src/specification/contracts/http.d.ts
+/**
+ * Request filters for the generic HTTP provider. Every field is a subset
+ * constraint — a request matches when all provided fields match.
+ */
+type HttpContractFilter = {
+  /**
+   * Body constraint. An object is a deep SUBSET match (toMatchObject-style)
+   * whose leaf values may be `match.*` matchers; a string is a containment
+   * test and a RegExp a `test()` over the raw text body.
+   */
+  body?: object | RegExp | string;
+  /** Header subset. Names are case-insensitive; string = exact value, RegExp = `test()`. */
+  headers?: Record<string, RegExp | string>;
+  /** Query-param subset. string = exact value, RegExp = `test()`. */
+  query?: Record<string, RegExp | string>;
+};
+/** Init options shared by the response builders. */
+type 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 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
+ *   defineContract({ request: http.get('/articles/{{uuid}}'), response: http.json(article) })
+ *   defineContract({ request: http.post(URL, { body: { user: 'alice' } }), response: http.empty() })
+ */
+declare const http: {
+  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: no response at all — the request fails in transport, the way a
+   * server that is not running fails it. `fetch` rejects; no status is served.
+   */
+  unreachable(): 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
+type OpenAIChatFilter = {
+  model?: TextFilter;
+  system?: TextFilter;
+  user?: TextFilter;
+  tools?: string[];
+  temperature?: number;
+};
+type OpenAIResponsesFilter = {
+  model?: TextFilter;
+  system?: TextFilter;
+  user?: TextFilter;
+  tools?: string[];
+};
+/**
+ * OpenAI API intercept helpers.
+ */
+declare const openai: {
+  /**
+   * 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' })         // exact model
+   *   openai.chat({ system: buildPrompt() })   // exact system prompt
+   *   openai.chat({ system: /classify/ })      // pattern
+   */
+  chat(filter?: OpenAIChatFilter): ContractRequest;
+  /**
+   * 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.
+   *
+   * @param filter - Optional body filters.
+   * @param url - Custom gateway URL (default: api.openai.com).
+   *
+   * @example
+   *   openai.responses({ user: /Report Ingestion/ }, GATEWAY)
+   */
+  responses(filter?: OpenAIResponsesFilter, url?: string): ContractRequest;
+  /**
+   * Response: wrap data in Chat Completions format.
+   *
+   * @example
+   *   openai.reply({ categories: ['TECH'] })
+   */
+  reply(data: unknown): ContractResponse;
+  /** Response: return an OpenAI error. */
+  error(status: number, message?: string): ContractResponse;
+  /** Response: return malformed content. */
+  malformed(content: string): ContractResponse;
+  /** Response: simulate a timeout. */
+  timeout(): ContractResponse;
+};
+//#endregion
+//#region src/vitest/mock-of.d.ts
+/** Factory signature that creates a deep mock proxy for any interface. */
+type MockPort = <T>() => DeepMockProxy<T>;
+/**
+ * Create a deep mock proxy for a given type.
+ * Wraps `vitest-mock-extended`'s `mockDeep` for convenient port mocking.
+ */
+declare const mockOf: MockPort;
+//#endregion
+//#region src/vitest/mock-of-date.d.ts
+/** Interface for freezing and resetting the global Date in tests. */
+type MockDatePort = {
+  /** Restore the real Date object. */
+  reset: () => void;
+  /** Freeze `Date.now()` and `new Date()` to the given value. */
+  set: (date: Date | number | string) => void;
+};
+/**
+ * Freeze or reset the global Date for deterministic time-dependent tests.
+ * Wraps the `mockdate` package.
+ */
+declare const mockOfDate: MockDatePort;
+//#endregion
+//#region src/surface.d.ts
+declare module 'vitest' {
+  interface Assertion<T = any> {
+    /**
+     * Assert the subject is empty — zero rows for a table (async), an
+     * empty stream for a text accessor (console, errors, stdout).
+     */
+    toBeEmpty: T extends TableAccessor ? () => Promise<void> : T extends {
+      readonly comparableText: string;
+    } ? () => Promise<void> : never;
+    /** Assert the container is running. Async — docker-backed subject. */
+    toBeRunning: T extends ContainerAccessor ? () => Promise<void> : never;
+    /**
+     * On `@jterrazz/test` accessors: assert the subject matches a fixture
+     * file under `_expected/<name>` (flat — a slash creates a subfolder;
+     * `.http` format for `result.response`). Async for filesystem/directory
+     * subjects (tree compare on disk), and for a subject captured INSIDE a
+     * page (`result.tree`, `result.html`, … — the file crosses the browser
+     * seam through a server command).
+     *
+     * Pass `{ frozen: true }` to opt a single fixture OUT of update-mode
+     * rewriting: a frozen fixture is never overwritten under `TEST_UPDATE=1`
+     * (or vitest `-u`), and a frozen mismatch/missing fixture still throws.
+     * Use it for a deliberately-wrong fixture whose diff/error rendering is
+     * the behaviour under test.
+     */
+    toMatch: T extends DirectoryAccessor | FilesystemAccessor ? (name: RegExp | string, options?: MatchFixtureOptions) => Promise<void> : T extends {
+      readonly capturedInPage: true;
+    } ? (name: RegExp | string, options?: MatchFixtureOptions) => Promise<void> : T extends JsonAccessor | ResponseAccessor | TextAccessor ? (name: RegExp | string, options?: MatchFixtureOptions) => void : (expected: RegExp | string, options?: MatchFixtureOptions) => void;
+    /**
+     * Assert the table contains exactly the given rows for the given
+     * columns. Cells accept `match.*` dynamic-value matchers. Async —
+     * queries the database.
+     */
+    toMatchRows: T extends TableAccessor ? (expected: {
+      columns: string[];
+      rows: readonly (readonly unknown[])[];
+    }) => Promise<void> : never;
+  }
+}
+//#endregion
+//#region src/specification/facets/_common/orchestrator.d.ts
+type OrchestratorOptions = {
+  /**
+   * Named infrastructure record. Keys become the database vocabulary of the
+   * spec (`.seed()` / `.table()` `database` option) and drive the compose
+   * binding: a handle with no explicit `composeService` links to the compose
+   * service named exactly like its key, else the kebab-case conversion of the
+   * key (`analyticsDb` → `analytics-db`) — see {@link resolveComposeBinding}.
+   */
+  services: Record<string, ServiceHandle>;
+  mode: 'e2e' | 'integration';
+  /**
+   * The project root, already resolved. REQUIRED: the constructors derive it
+   * by walking up from the calling specification file (CONVENTIONS A9), and
+   * the orchestrator is handed the answer. Defaulting to `process.cwd()` here
+   * meant one silent second opinion about what the project is — the runner
+   * resolving from the caller, this from wherever the runner happened to be
+   * launched, which in a workspace is rarely the same directory.
+   */
+  root: string;
+  /** Compose project name — used for per-worker stack isolation. */
+  projectName?: string;
+};
+/**
+ * Orchestrator for test infrastructure.
+ * Integration: starts services via testcontainers.
+ * E2E: runs full docker compose up.
+ */
+declare class Orchestrator {
+  private readonly services;
+  private readonly mode;
+  private readonly root;
+  private readonly projectName;
+  private running;
+  private composeStack;
+  private composeHandles;
+  private started;
+  constructor(options: OrchestratorOptions);
+  /**
+   * Bind each declared handle to a compose service (CONVENTIONS A6): a record
+   * key resolves to the service named exactly like it, else the kebab-case
+   * conversion of the key; an explicit `composeService` wins. Throws on an
+   * ambiguous binding (both names present). Runs once compose config is known
+   * so the two-step resolution can consult the real service list.
+   */
+  private resolveBindings;
+  /**
+   * Start declared services via testcontainers (integration mode).
+   * Phase 1: start all containers in parallel (the slow part).
+   * Phase 2: wire connections, healthcheck, and init sequentially (fast).
+   */
+  start(): Promise<void>;
+  /**
+   * Stop testcontainers (integration mode).
+   */
+  stop(): Promise<void>;
+  /**
+   * Start full docker compose stack (e2e mode).
+   * Auto-detects infra services and creates handles for them.
+   */
+  startCompose(): Promise<void>;
+  /**
+   * Stop docker compose stack (e2e mode).
+   */
+  stopCompose(): Promise<void>;
+  /**
+   * Get the default database — the first declared handle that is one.
+   */
+  getDatabase(): DatabasePort | null;
+  /**
+   * Get all database services keyed by their record key (declared services)
+   * or compose service name (stack-detected services).
+   */
+  getDatabases(): Map<string, DatabasePort>;
+  private allHandles;
+  /**
+   * Get app URL from compose (e2e mode).
+   */
+  getAppUrl(): null | string;
+}
+//#endregion
+//#region src/specification/facets/_common/services.d.ts
+/**
+ * Infrastructure services declared as a named record. Keys become the typed
+ * vocabulary of the whole spec: the server factory receives the same record,
+ * and `.seed()` / `.table()` target databases by key.
+ */
+type ServiceRecord = Record<string, ServiceHandle>;
+/** Keys of a services record whose handles are databases. */
+type DatabaseKeys<Services extends ServiceRecord> = { [K in keyof Services]: Services[K] extends DatabasePort ? K & string : never; }[keyof Services];
+//#endregion
+//#region src/specification/facets/api/start-api.d.ts
+/** Any object with a request method compatible with Hono's app.request(). */
+type HonoApp = {
+  request: (path: string, init?: RequestInit) => Promise<Response> | Response;
+};
+/** Execution mode — exists ONLY on `specification.api()` (CONVENTIONS A5). */
+type SpecificationMode = 'compose' | 'node';
+/** Options for {@link startApi | specification.api}. */
+type ApiSpecificationOptions<Services extends ServiceRecord = ServiceRecord> = {
+  /**
+   * Execution mode override. Resolution: `options.mode` >
+   * `process.env.TEST_MODE` > `'node'`. Never hardcode this in a
+   * specification file when `server` is defined — set it per vitest
+   * project via `env: { TEST_MODE: 'compose' }` (CONVENTIONS A5).
+   */
+  mode?: SpecificationMode;
+  /**
+   * Project root override for compose detection and init scripts. When
+   * absent, the root is auto-discovered by walking up from the calling
+   * specification file to the first directory containing
+   * `docker/compose.test.yaml`, else the first containing `package.json`
+   * (CONVENTIONS A9).
+   */
+  root?: string;
+  /**
+   * The app factory — receives the started services record (fully typed)
+   * and returns the Hono app. Required in node mode, ignored in compose
+   * mode (the app runs as a compose service there).
+   */
+  server?: (services: Services) => HonoApp;
+  /**
+   * Named infrastructure record. Keys become the `database` vocabulary of
+   * `.seed()` / `.table()` and drive the compose binding: a handle with no
+   * `composeService` option links to the compose service named exactly like
+   * its key, else the kebab-case conversion of the key (CONVENTIONS A6).
+   */
+  services?: Services;
+};
+/**
+ * The record returned by {@link startApi | specification.api}. Destructure
+ * with the canonical names (CONVENTIONS A3):
+ *
+ *     const { api, cleanup, docker } = await specification.api(…);
+ */
+type ApiHandle<DatabaseKey extends string = string> = {
+  api: ApiSpecification<DatabaseKey>;
+  /** Stop all infrastructure started by this specification. */
+  cleanup: () => Promise<void>;
+  /**
+   * Read a running container by id — returns a {@link ContainerAccessor}
+   * usable with `await expect(...).toBeRunning()` and read accessors.
+   */
+  docker: (containerId: string) => ContainerAccessor;
+  /** The orchestrator managing the test infrastructure lifecycle. */
+  orchestrator: Orchestrator;
+};
+declare function startApi<Services extends ServiceRecord>(options: ApiSpecificationOptions<Services>): Promise<ApiHandle<DatabaseKeys<Services>>>;
+//#endregion
+//#region src/specification/facets/cli/start-cli.d.ts
+/** Options for {@link startCli | specification.cli}. */
+type CliSpecificationOptions<Services extends ServiceRecord = ServiceRecord> = {
+  /**
+   * Opt-in Docker awareness. When set, every spec generates a unique
+   * test-run id, injects it into the child process env under `envVar`,
+   * and exposes `.container(name)` accessors on the result that lazily
+   * query Docker. Always declare results with `await using` so leaked
+   * containers get force-removed at scope exit (CONVENTIONS B5).
+   */
+  docker?: DockerSpecConfig;
+  /**
+   * Named environment SETS for `<case>.spec.yaml` documents. An `env:` entry
+   * `frozen` applies the whole `frozen` record; `$WORKDIR` expands and `null`
+   * unsets, exactly as in `.env()`. Declared once per app so a document
+   * states WHICH ground it stands on, not how to build it.
+   */
+  env?: Record<string, CliEnv>;
+  /**
+   * Named servers a `<case>.spec.yaml` document may start (`serve: [mcp]`, or
+   * `- mcp: { KEY: value }` to add env to that one). Each entry names the
+   * shell `command`, the `ready` regex whose capture group holds the port the
+   * server announces, the `url(port)` builder, and the `env` variable that
+   * URL is bound to in every run's child.
+   */
+  serve?: Record<string, LiterateServeRegistration>;
+  /**
+   * Project-root override (CONVENTIONS A9) — the single meaning of `root`:
+   * it anchors compose detection and local-bin resolution for the tested
+   * binary. It is NOT a fixtures root; `.fixture()` resolves feature-local
+   * or `$FIXTURES/` paths on its own.
+   */
+  root?: string;
+  /**
+   * Named infrastructure record started via testcontainers. Connection
+   * URLs are injected automatically into the child env: `<KEY>_URL` per
+   * service, plus `DATABASE_URL` / `REDIS_URL` when unambiguous
+   * (CONVENTIONS B6). `.env()` overrides.
+   */
   services?: Services;
   /**
    * Escape hatch: normaliser applied to result.stdout / result.stderr
@@ -1900,6 +2472,10 @@ type Specification = {
 };
 declare const specification: Specification;
 //#endregion
+//#region src/specification/facets/component/component.node.d.ts
+/** Present, typed, and refusing — every setup and the terminal action alike. */
+declare const component: ComponentChain;
+//#endregion
 //#region src/specification/literate/spec-document.d.ts
 /**
  * The facets a document may describe. `cli` is the only one implemented; the
@@ -1988,93 +2564,51 @@ declare function inspectContainer(id: string): unknown;
 /** Force-remove the given container IDs in a single call. Errors are swallowed. */
 declare function removeContainers(ids: string[]): void;
 //#endregion
-//#region src/specification/ports/container.port.d.ts
-/**
- * Abstract container interface.
- * Represents a running service (database, cache, etc.)
- */
-type ContainerPort = {
-  /** Start the container and wait until ready. */
-  start: () => Promise<void>;
-  /** Stop and remove the container. */
-  stop: () => Promise<void>;
-  /** Get the mapped host port for a container port. */
-  getMappedPort: (containerPort: number) => number;
-  /** Get the host to connect to. */
-  getHost: () => string;
-  /** Get a full connection string for this service. */
-  getConnectionString: () => string;
-  /** Get container logs (stdout + stderr). */
-  getLogs: () => Promise<string>;
-};
-//#endregion
-//#region src/specification/facets/website/elements.d.ts
+//#region src/specification/facets/_common/result/text-subject.d.ts
 /**
- * The element vocabulary — user-facing descriptors for visit scenarios.
- * 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:
+ * Wrap an arbitrary string into a {@link TextAccessor} anchored on the calling
+ * test's directory — the same caller-detection the builders use.
  *
- *   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. */
-type ElementOptions = {
-  /**
-   * Match the accessible name as a whole string. Default is substring —
-   * `link('Articles')` also matches "Read Articles".
-   */
-  exact?: boolean;
-};
-/** A user-facing element factory — what every name in this module is. */
-type ElementFactory = (name: string, options?: ElementOptions) => ElementRef;
-/** A button (or element with the button role), by accessible name. */
-declare const button: ElementFactory;
-/** A form field, by label. */
-declare const field: ElementFactory;
-/** A heading, by accessible name. */
-declare const heading: ElementFactory;
-/** A link, by accessible name. */
-declare const link: ElementFactory;
-/** An element containing the given text. */
-declare const content: ElementFactory;
-/** The escape hatch: an element by `data-testid`. Prefer user-facing elements. */
-declare const testId: (id: string) => ElementRef;
-/** A landmark factory — the optionally-named containers `within()` accepts. */
-type LandmarkFactory = (name?: string, options?: ElementOptions) => ElementRef;
-/** The `banner` landmark — the page header. */
-declare const banner: LandmarkFactory;
-/** The `complementary` landmark — an `<aside>`, a sidebar. */
-declare const complementary: LandmarkFactory;
-/** The `contentinfo` landmark — the page footer. */
-declare const contentinfo: LandmarkFactory;
-/** The `form` landmark — a form carrying an accessible name. */
-declare const form: LandmarkFactory;
-/** The `main` landmark — the primary content of the document. */
-declare const main: LandmarkFactory;
-/** The `navigation` landmark — a `<nav>`. Name it when a page has several. */
-declare const navigation: LandmarkFactory;
-/** The `region` landmark — a `<section>` carrying an accessible name. */
-declare const region: LandmarkFactory;
-/** The `search` landmark. */
-declare const search: LandmarkFactory;
-/**
- * Restrict a descriptor to the inside of another — the answer to ambiguity,
- * and the one the framework prefers over a test id.
+ * The product surface of a test framework is its own error messages, checker
+ * output, and reports; those deserve the same goldening as any other output.
+ * `text()` makes an ad-hoc string a first-class snapshot subject:
  *
- *     click(within(navigation(), link('Articles')))
+ * ```typescript
+ * const message = await catchMessage(() => expect(result.response).toMatch('wrong-body.http'));
+ * expect(text(message)).toMatch('wrong-body-error.txt'); // resolves to _expected/
+ * ```
  *
- * 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.
+ * ANSI is stripped before every comparison (the raw form stays on `.text`),
+ * the `{{token}}` grammar applies to the fixture, and `.grep()` composition
+ * works exactly as on any stream accessor.
+ *
+ * The ANCHOR is why this sits apart from the accessor it builds: reading the
+ * caller's frame means reading a stack and a real path, which is node's alone.
+ * {@link TextAccessor} itself is a pure projection over a captured string, so
+ * it loads in a page — and the browser entry builds its own `text()`, where
+ * the golden commands resolve `_expected/` from the test's path server-side.
  */
-declare const within: (scope: ElementRef, target: ElementRef) => ElementRef;
+declare function text(value: string): TextAccessor;
+//#endregion
+//#region src/specification/ports/container.port.d.ts
+/**
+ * Abstract container interface.
+ * Represents a running service (database, cache, etc.)
+ */
+type ContainerPort = {
+  /** Start the container and wait until ready. */
+  start: () => Promise<void>;
+  /** Stop and remove the container. */
+  stop: () => Promise<void>;
+  /** Get the mapped host port for a container port. */
+  getMappedPort: (containerPort: number) => number;
+  /** Get the host to connect to. */
+  getHost: () => string;
+  /** Get a full connection string for this service. */
+  getConnectionString: () => string;
+  /** Get container logs (stdout + stderr). */
+  getLogs: () => Promise<string>;
+};
 //#endregion
 //#region src/integrations/postgres/postgres.d.ts
 type PostgresOptions = {
@@ -2240,228 +2774,4 @@ declare class SqliteHandle implements DatabasePort, ServiceHandle {
  */
 declare function sqlite(options?: SqliteOptions): SqliteHandle;
 //#endregion
-//#region src/specification/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
-type AnthropicMessagesFilter = {
-  model?: TextFilter;
-  system?: TextFilter;
-  user?: TextFilter;
-  tools?: string[];
-};
-/**
- * Anthropic API intercept helpers.
- */
-declare const anthropic: {
-  /**
-   * 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.
-   *
-   * @example
-   *   anthropic.messages()
-   *   anthropic.messages({ system: /classify/ })
-   *   anthropic.messages({ user: buildPrompt() })   // string = EXACT equality
-   *   anthropic.messages({ user: /classify/ }, GATEWAY)
-   */
-  messages(filter?: AnthropicMessagesFilter, url?: string): ContractRequest;
-  /** Response: wrap data in Anthropic messages format. */
-  reply(data: unknown): ContractResponse;
-  /** Response: return an Anthropic error. */
-  error(status: number, message?: string): ContractResponse;
-  /** Response: simulate a timeout. */
-  timeout(): ContractResponse;
-};
-//#endregion
-//#region src/specification/contracts/http.d.ts
-/**
- * Request filters for the generic HTTP provider. Every field is a subset
- * constraint — a request matches when all provided fields match.
- */
-type HttpContractFilter = {
-  /**
-   * Body constraint. An object is a deep SUBSET match (toMatchObject-style)
-   * whose leaf values may be `match.*` matchers; a string is a containment
-   * test and a RegExp a `test()` over the raw text body.
-   */
-  body?: object | RegExp | string;
-  /** Header subset. Names are case-insensitive; string = exact value, RegExp = `test()`. */
-  headers?: Record<string, RegExp | string>;
-  /** Query-param subset. string = exact value, RegExp = `test()`. */
-  query?: Record<string, RegExp | string>;
-};
-/** Init options shared by the response builders. */
-type 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 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
- *   defineContract({ request: http.get('/articles/{{uuid}}'), response: http.json(article) })
- *   defineContract({ request: http.post(URL, { body: { user: 'alice' } }), response: http.empty() })
- */
-declare const http: {
-  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
-type OpenAIChatFilter = {
-  model?: TextFilter;
-  system?: TextFilter;
-  user?: TextFilter;
-  tools?: string[];
-  temperature?: number;
-};
-type OpenAIResponsesFilter = {
-  model?: TextFilter;
-  system?: TextFilter;
-  user?: TextFilter;
-  tools?: string[];
-};
-/**
- * OpenAI API intercept helpers.
- */
-declare const openai: {
-  /**
-   * 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' })         // exact model
-   *   openai.chat({ system: buildPrompt() })   // exact system prompt
-   *   openai.chat({ system: /classify/ })      // pattern
-   */
-  chat(filter?: OpenAIChatFilter): ContractRequest;
-  /**
-   * 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.
-   *
-   * @param filter - Optional body filters.
-   * @param url - Custom gateway URL (default: api.openai.com).
-   *
-   * @example
-   *   openai.responses({ user: /Report Ingestion/ }, GATEWAY)
-   */
-  responses(filter?: OpenAIResponsesFilter, url?: string): ContractRequest;
-  /**
-   * Response: wrap data in Chat Completions format.
-   *
-   * @example
-   *   openai.reply({ categories: ['TECH'] })
-   */
-  reply(data: unknown): ContractResponse;
-  /** Response: return an OpenAI error. */
-  error(status: number, message?: string): ContractResponse;
-  /** Response: return malformed content. */
-  malformed(content: string): ContractResponse;
-  /** Response: simulate a timeout. */
-  timeout(): ContractResponse;
-};
-//#endregion
-//#region src/vitest/mock-of.d.ts
-/** Factory signature that creates a deep mock proxy for any interface. */
-type MockPort = <T>() => DeepMockProxy<T>;
-/**
- * Create a deep mock proxy for a given type.
- * Wraps `vitest-mock-extended`'s `mockDeep` for convenient port mocking.
- */
-declare const mockOf: MockPort;
-//#endregion
-//#region src/vitest/mock-of-date.d.ts
-/** Interface for freezing and resetting the global Date in tests. */
-type MockDatePort = {
-  /** Restore the real Date object. */
-  reset: () => void;
-  /** Freeze `Date.now()` and `new Date()` to the given value. */
-  set: (date: Date | number | string) => void;
-};
-/**
- * Freeze or reset the global Date for deterministic time-dependent tests.
- * Wraps the `mockdate` package.
- */
-declare const mockOfDate: MockDatePort;
-//#endregion
-//#region src/index.d.ts
-declare module 'vitest' {
-  interface Assertion<T = any> {
-    /**
-     * Assert the subject is empty — zero rows for a table (async), an
-     * empty stream for a text accessor (console, errors, stdout).
-     */
-    toBeEmpty: T extends TableAccessor ? () => Promise<void> : T extends {
-      readonly comparableText: string;
-    } ? () => Promise<void> : never;
-    /** Assert the container is running. Async — docker-backed subject. */
-    toBeRunning: T extends ContainerAccessor ? () => Promise<void> : never;
-    /**
-     * On `@jterrazz/test` accessors: assert the subject matches a fixture
-     * file under `_expected/<name>` (flat — a slash creates a subfolder;
-     * `.http` format for `result.response`). Async for filesystem/directory
-     * subjects (tree compare on disk). Other subjects keep vitest-native
-     * `toMatch` semantics (string substring / regexp).
-     *
-     * Pass `{ frozen: true }` to opt a single fixture OUT of update-mode
-     * rewriting: a frozen fixture is never overwritten under `TEST_UPDATE=1`
-     * (or vitest `-u`), and a frozen mismatch/missing fixture still throws.
-     * Use it for a deliberately-wrong fixture whose diff/error rendering is
-     * the behaviour under test.
-     */
-    toMatch: T extends DirectoryAccessor | FilesystemAccessor ? (name: RegExp | string, options?: MatchFixtureOptions) => Promise<void> : T extends JsonAccessor | ResponseAccessor | TextAccessor ? (name: RegExp | string, options?: MatchFixtureOptions) => void : (expected: RegExp | string, options?: MatchFixtureOptions) => void;
-    /**
-     * Assert the table contains exactly the given rows for the given
-     * columns. Cells accept `match.*` dynamic-value matchers. Async —
-     * queries the database.
-     */
-    toMatchRows: T extends TableAccessor ? (expected: {
-      columns: string[];
-      rows: readonly (readonly unknown[])[];
-    }) => Promise<void> : never;
-  }
-}
-//#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 CliInput, 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, type DeviceTimeouts, 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 LiterateRunFlags, type LiterateServeRegistration, 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 SpecDocument, type SpecEnvToken, type SpecFileAssertion, type SpecFixture, type SpecKind, type SpecRun, type SpecServeEntry, type SpecStream, 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 };
+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 CliInput, type CliOutput, type CliPort, CliResult, type CliSpecification, type CliSpecificationOptions, type ComponentChain, type ComponentScenario, type ComponentUi, type ComponentVisitor, 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, type DeviceTimeouts, DirectoryAccessor, type DockerSpecConfig, type DomMount, 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 LiterateRunFlags, type LiterateServeRegistration, 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, type RenderResult, type RenderSubject, type RenderedText, ResponseAccessor, type ScreenNode, ScreenResult, type ServeOptions, type ServerPort, type ServerResponse, type ServiceHandle, type ServiceRecord, type SpecDocument, type SpecEnvToken, type SpecFileAssertion, type SpecFixture, type SpecKind, type SpecRun, type SpecServeEntry, type SpecStream, 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, component, content, contentinfo, defineContract, defineContracts, dialog, disabled, enabled, field, findContainersByLabel, focused, form, heading, http, inspectContainer, link, listitem, main, match, mockOf, mockOfDate, navigation, openai, option, postgres, redis, region, removeContainers, row, search, selected, specification, sqlite, status, table, testId, text, valued, within };