@ultimat3/testing 12.0.0 → 14.0.0

package/CLAUDE.md

@@ -22,12 +22,20 @@ is its own entry point and not part of the barrel.
 | One way offline | the `network` fixture. `setNetworkState` is the gate's only writer and is not exported — setting it from a test body skips the fixture's disposal and leaves every later file offline |
 | No retries | a flake is fixed or deleted the day it flakes; there is no `retry: 3` |
 | `toBeUltimateError` reads THREE fields | an `X_` code plus a `cause` plus a `fix`, all through core's `stringField`. `typeof value.code === 'string'` alone passed a Node `ENOENT` — so a suite pinning "never throw a bare `Error`" stayed green through exactly the regression it guards (`matchers.test.ts`). Same discriminator `packages/cli/src/output.ts` uses to decide what the terminal shows, and a hostile getter answers `undefined` instead of raising inside the assertion |
+| One matcher WAITS, and it is `toBeVisible` | `await expect(locator).toBeVisible()` retries `isVisible()` to a budget — 5000ms every 100ms, Playwright's own default, narrowable per call. **`.not` waits for the element to GO**: it reads bun's `isNot` (measured — the flag is real but is not in bun's published types) and inverts what it waits FOR, never just the answer. Inverting a single look is a no-op that passes on a page which has not painted yet, which is the failure a retrying assertion exists to remove. `expect(await locator.isVisible()).toBe(true)` is the point-in-time spelling and stays a different assertion |
+| The budget is counted in LOOKS, not milliseconds | this package freezes `Date.now()`, so a deadline computed from the clock never expires and the loop spins forever. `attemptsFor(budget)` is `1 + floor(timeout / interval)` — one free look plus one per whole interval — and it is what a test asserts, because elapsed time is the one thing a frozen clock cannot give it. `retryUntil`'s `sleep` is a DEFAULT PARAMETER for the same reason a `random = Math.random` default is: a test injects a counting stub and measures how many times it looked and slept |
+| A FIXED interval, and never a curve | doubling the gap makes the last look land long after the state changed, and the caller's deadline is the contract. There is exactly one backoff curve in the framework (`@ultimat3/core`'s `backoff.ts`) and this is deliberately not a second one. A zero or negative interval is REFUSED: the failure mode is a test that never fails — it hangs, and CI reports a runner timeout with no assertion in it |
+| A matcher that may throw a coded error MUST NOT be `async` | measured against Bun 1.4.0: an `async` matcher has any error it throws REPLACED by bun's own `Matcher \`x\` returned a promise that rejected`, so the code, the cause and the fix are gone before a reader sees them. `X_TEST_SCHEMA_EXPECTED` and `X_TEST_JOB_EXPECTED` were declared, registered, titled — and unreachable by any caller for their whole life, because nothing asserted them. The shape is a SYNCHRONOUS prologue that validates the receiver (`assertStandardSchema`, `assertJobDeclaration`, `assertVisibilityProbe`) and a promise returned after it. `matcher-receiver.test.ts` pins all four |
+| Wrong receiver throws, wrong value returns | a matcher handed a page where a locator belongs is not FALSE, it is unanswerable — `pass: false` would read as "the element was hidden". A wrong-shaped receiver is a coded throw; a wrong value is `result(false, …)` |
 | Test names | the filename picks the step; `testName(type, name)` on the outer `describe` puts that type on every failure line under it. Never on the inner `test` too — the prefix would print twice |
 | `test` here is `fixtureTest`, and it takes no timeout | `(name, body)`, nothing else (`fixtures.ts:248`, exported as `test` by `index.ts:107`) — `bunTest` is called with two arguments, so bun's own third one is unreachable and no case can ask for more than the default 5s. Slow work goes in `beforeAll(fn, 60_000)`, which is `bun:test`'s own re-export and does take one; that is where both generated island tests and `examples/dummy/apps/web/app/settings/settings.island.test.ts` build their chunk, once, for every case to share — a Babel pass plus a browser bundle is seconds. A case that needs 60s of its own is work sitting in the wrong place |
 | Injection | `SqlRunner` and `connect` are parameters, so unit tests need no server |
 | Fixtures | the preload registers the whole framework bag — an app registers only what the framework cannot know (`seed`, `actorFor`) |
-| e2e without a driver | `e2eTest` becomes `test.skip`, and the gate reports the step GREEN over it — `bun test` exits 0 on a skip and the exit code is the only channel between the step and the child that registers the driver. `hasE2eDriver()` is what a harness asks instead of reading an all-skipped run as a pass. Zero drivers are registered `As of 2026-08` |
+| e2e without a driver | `e2eTest` becomes `test.skip`, and the gate reports the step GREEN over it — `bun test` exits 0 on a skip and the exit code is the only channel between the step and the child that registers the driver. `hasE2eDriver()` is what a harness asks instead of reading an all-skipped run as a pass. Zero drivers are registered BY DEFAULT and that is the design, not a gap: `@ultimat3/cli`'s `installE2eDriver()` is the one that exists (`packages/cli/src/e2e-driver.ts`), an app's test preload is what calls it, and CI has no browser |
+| The seam has an inverse, `As of 2026-08-25` | `resetE2eDriver()`. `useE2eDriver` writes MODULE scope and `bun test` is one process, so a file that installed a browser handed every later file in the run an `e2eTest` that opened a page nobody asked for — `test-types.test.ts` was itself doing it, at module scope, with nothing to undo it. Same shape and same reason as `@ultimat3/scraping`'s `resetScrapeDriver()` |
 | Built vs declared | `clock` `mail` `network` `runJobs` `statements` `subscribe` are built in-process; `page` `budget` `signIn` `deploy` are declared and wait for a driver (`X_TEST_FIXTURE_UNAVAILABLE`). The four left all need a browser or a second build — things the framework genuinely cannot bundle |
+| `page` HAS a driver now, and the other three still do not, `As of 2026-08-25` | `installE2eDriver({ page, baseUrl })` registers `page` over its declaration and leaves `budget`, `signIn` and `deploy` refusing, on purpose: byte counts come off a built `dist/`, a sign-in route is the APP's, and a new build id is a fact about the SERVER — a page port can answer for none of the three, and a fixture that silently no-opped would make the assertion after it read as proof |
+| `network` is THIS process's fetch, and an e2e page is not in this process | `sealed-network.ts` patches `globalThis.fetch` here; a browser's requests never pass through it. So `network.offline()` in a test that also destructures `page` is a **no-op on the browser** — the app's online page passing an offline test. `E2eFixtures.offline()` is the browser-side spelling and the CDP driver REFUSES it (`X_TEST_FIXTURE_UNAVAILABLE`), because `CdpPageLike` declares no `setOfflineMode`. Two words, two mechanisms, and only one of them can put a browser offline |
 | `subscribe` is a whole `sync` node | `live-node.ts` assembles what `x dev --role sync` assembles minus the listener — real `LiveQueryRegistry`, real `liveQueryDefinition` bridge, real per-subscriber gate, real cursor — over a socket that is two objects handing each other the JSON a WebSocket would. `live-replicator.ts` feeds it from `@ultimat3/entity`'s `setRowObserver`, which is the change SOURCE a test process never had: PGlite has no walsender and the memory driver no log, so `InMemoryChangeFeed` had nothing upstream of it. The WAL decoder is the only thing substituted; everything downstream of it is production code |
 | What `subscribe` does NOT hold | a client store, an offline queue or a rebase log — so `feed.local()` answers `undefined` rather than the server row. A twin reported as applied whether or not a mutator ran is coverage that reads as proof, which is worse than none. That half is `useMutation` / `useMutationQueue` and an e2e |
 | Draining is a macrotask yield | the node dispatches `message` into a floating async task, so `settled()` yields with `setImmediate` until the frame count stops moving. Counting microtask turns is a number that is right until someone adds an `await` — the first version drained 32 and read `examples/dummy`'s deeper feed read as "the node answered nothing" |
@@ -60,6 +68,7 @@ is its own entry point and not part of the barrel.
 | Factory seeds | derived from the table name unless given, so two entities never draw the same uuid stream. `reset()` cascades into associated parents — a half-reset row is worse than none |
 | Shared examples | `behavesLike` calls `describe`, so it goes at declaration scope; bun rejects a `describe` inside a test body |
 | An island needs a BUILDER, not an import | `buildIslands` is `@ultimat3/cli`'s and both packages are tier 5; the one declared edge is `cli → testing`, so the reverse is a `bun run boundaries` failure. `mountIsland({ build, root, file })` takes the function as a parameter and declares only the two fields it reads — `IslandChunkLike` is `{ file, code }`, so a CSS artifact, a source map or a dev/production flag the bundler grows is invisible here. Moving the bundler down a tier was the alternative and it drags `@babel/core` and `babel-preset-solid` with it, into a package whose whole point is being importable from tier 0 |
+| `mountIsland` AWAITS `mount` | `IslandEntry['mount']` returns `unknown`, not `void`, and the call is awaited — the shipped runtime chains `import(e).then((m) => m.mount(el, props))` (`packages/render/src/hydrate.ts`) and only marks the element mounted when that settles, so an `async` mount is an ordinary island and `like.island.tsx` already is one. Typed `=> void` and called bare, the fixture returned before an island that opens a queue or a socket had rendered anything, so every assertion after it read an empty wrapper — and worse, the mount RESUMED after `restore()` had taken the fake `document` back out, failing with `document is not defined` inside whichever later test happened to be running. Not a breaking change: `IslandEntry` is module-private and an island module is matched structurally off an `unknown` import, so nothing implements it. |
 | The micro-DOM is the fixture's, once **for islands** | `island-dom.ts`. **"Once" is scoped to this job, and said so only from 2026-08-23**: `packages/ui/src/fake-dom.ts` is a second micro-DOM (201 lines, test-only, off that package's barrel) for a different one — focus, `activeElement`, `contains` and a `:not()` selector grammar for keyboard code, none of which parses a `<template>`. It is not a copy to collapse: `ui` is tier 4 and this package is tier 5, so `ui -> testing` is an upward import the boundary check refuses, and the merge would need the shared half moved down to a tier neither grammar belongs in. `bun test` has no DOM and no DOM library may be added; `generate: 'dom'` builds every element from `_$template("<label …>")`, so a stub without a parsed `<template>` cannot run one line of a compiled island. It lived twice, ~200 lines each, in `packages/cli/src/island-bundle.test.ts` and the reference app's island test |
 | `style` and `classList` RECORD, `As of 2026-08` | `FakeStyle` is one declaration map behind all four spellings compiled Solid uses on one element: a STATIC entry baked into the template's `style=` attribute, a dynamic one through `setStyleProperty` → `style.setProperty`, a whole-object or string prop through `style()` → `cssText`, and a cleared one through `removeAttribute`. It was `style = {}` until 2026-08-21 — `<Form>`, `<Stack>`, `<Grid>` and `<Container>` each set a CSS custom property, so every one of them died inside `mount` with `e.style.setProperty is not a function`, and `x g resource` emitted a plain `<form>` rather than the design system's. A design-system component kept out of generated code by the limits of a TEST DOUBLE. A no-op `setProperty` would have stopped the crash and left "the component set `--form-gap`" unassertable, which is the same hole one layer down |
 | `classList` is the class attribute | not a list of its own, so `classList.toggle` — what the compiler emits INLINE for `classList={{ … }}`, with no runtime helper in front of it — and `className` can never answer one element two ways. `add` was the only method the stand-in had and is the one Solid never calls |

package/README.md

@@ -16,7 +16,8 @@ frozen clock. Never let a test reach the network unmocked — it fails by design
 | `factory-persist.ts` | `usePersister` — the one seam `create()` writes through |
 | `shared-examples.ts` | `sharedExamples` / `behavesLike` — one rule, many subjects |
 | `test-types.ts` | the six test types and their helpers |
-| `matchers.ts` | `toBeUltimateError` `toDenyPolicy` `toEmitSteps` `toMatchOpenApi` `toBeWithinBudget` `toRejectInput` |
+| `matchers.ts` | `toBeUltimateError` `toDenyPolicy` `toEmitSteps` `toMatchOpenApi` `toBeWithinBudget` `toRejectInput` `toAcceptInput` `toBeVisible` |
+| `retry.ts` | the one retry loop every waiting assertion is built from — a budget, a fixed interval, and an injectable sleep |
 | `fixtures.ts` | the registry + `test('…', ({ clock }) => …)` injection |
 | `fixture-{clock,mail,jobs,network,statements}.ts` | the five fixtures the framework builds in-process |
 | `fixture-drivers.ts` | the five it declares but a driver must build — `page` `budget` `signIn` `deploy` `subscribe` |
@@ -135,9 +136,19 @@ there is no flag on the fixture and no code to silence.
 | `contractTest` | OpenAPI diff vs the committed spec, MCP exposure | `contract` |
 | `liveTest` | exactly what each subscriber receives | `live` |
 | `jobTest` | step sequence, retries, idempotency | `job` |
-| `e2eTest` | a browser driver incl. offline mode + SW update; with none registered it SKIPS, and the gate's `e2e` step passes over the skip — ask `hasE2eDriver()` rather than reading that as a pass | `e2e` |
+| `e2eTest` | a browser driver; with none registered it SKIPS, and the gate's `e2e` step passes over the skip — ask `hasE2eDriver()` rather than reading that as a pass | `e2e` |
 | `evalTest` | LLM output scoring against a threshold | `eval` |
 
+**Registering one, `As of 2026-08-25`.** `@ultimat3/cli`'s `installE2eDriver({ page, baseUrl })` is
+the driver that exists — a `PageLike` over `@ultimat3/scraping`'s browser — and an app's test preload
+is what calls it. It returns the undo, and `resetE2eDriver()` is the seam's inverse for anything that
+installs one by hand: `bun test` is one process, so a driver left registered reaches every later file.
+
+It registers `page` and nothing else. `budget`, `signIn` and `deploy` keep refusing with
+`X_TEST_FIXTURE_UNAVAILABLE`, and so do `E2eFixtures`' `offline()` / `online()` / `update()` — the
+browser's own network state and a second build id are not things a page port can answer for, and a
+fixture that silently no-opped would make the assertion after it read as proof.
+
 Each helper prefixes the test name with its type (`job · onboards an org`), which is what
 `bun test --test-name-pattern "job · "` selects — the six lines of `x verify` come from the tests
 themselves, not from a directory convention.
@@ -280,6 +291,12 @@ line and makes the direction visible instead of hidden.
 **`fire` answers whether a handler RAN.** A selector that matches nothing and an island that
 attached no handler are the same silence; the second is a bug and the first is a typo in the test.
 
+**An `async` mount is awaited**, as the shipped hydration runtime awaits it — an island that opens
+a queue or a socket before its first render (`like.island.tsx` does) needs no `settle()` helper in
+the test. Until `As of 2026-08-25` the call was bare, so the fixture answered before such an island
+had rendered anything and the mount later resumed against a `document` the teardown had already
+removed.
+
 **A mount installs process-global state**, so `MountedIsland` is `Disposable` — `using`, or
 `island[Symbol.dispose]()` in an `afterAll`. Left installed it hands a fake `document` to every
 later FILE in the run.
@@ -356,6 +373,32 @@ changed when only the reviewer moved.
 **The command that takes the pictures is not here yet.** `As of 2026-08-23` this package ships the
 vocabulary, the expansion and the refusals; the browser half is `x shot`'s.
 
+## The one assertion that waits
+
+```ts
+import { e2eTest, expect } from '@ultimat3/testing';
+
+e2eTest('the feed paints, and says so when the socket drops', async ({ page }) => {
+  // Retries isVisible() to a budget — 5000ms every 100ms unless you narrow it.
+  await expect(page.getByRole('heading', { name: 'Feed' })).toBeVisible();
+  await expect(page.getByText('Reconnecting')).toBeVisible({ timeout: 10_000 });
+
+  // `.not` waits for it to GO, not for one look to come back false.
+  await expect(page.getByText('Offline')).not.toBeVisible();
+});
+```
+
+| Fact | Why |
+|---|---|
+| the budget is counted in **looks**, not elapsed ms | this package freezes `Date.now()`, so a deadline read off the clock never expires. `1 + floor(timeout / interval)` |
+| a fixed interval, never a curve | the caller's deadline is the contract; a curve spends most of it waiting. The framework's one backoff curve is `@ultimat3/core`'s |
+| `interval: 0` is refused | an unbounded spin is a test that never fails — it hangs, and CI reports a runner timeout with no assertion in it |
+| a receiver with no `isVisible()` is `X_TEST_LOCATOR_EXPECTED` | the assertion is unanswerable, not false; `pass: false` would read as "the element was hidden" |
+| `timeout: 0` is the non-retrying spelling | one look, no wait — and you have to ask for it |
+
+`expect(await locator.isVisible()).toBe(true)` still works and is a **different** assertion: it
+fails on a page that simply has not painted yet.
+
 ## Errors
 
 `X_TEST_NETWORK_SEALED` `X_TEST_DB_UNAVAILABLE` `X_TEST_NONDETERMINISTIC` `X_TEST_FIXTURE_UNKNOWN`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/testing",
-  "version": "12.0.0",
+  "version": "14.0.0",
   "description": "Test harness: cloned template DBs per worker, frozen clock, sealed network, 6 test types",
   "license": "MIT",
   "type": "module",
@@ -33,16 +33,16 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "12.0.0",
-    "@ultimat3/core": "12.0.0",
-    "@ultimat3/db": "12.0.0",
-    "@ultimat3/entity": "12.0.0",
-    "@ultimat3/i18n": "12.0.0",
-    "@ultimat3/jobs": "12.0.0",
-    "@ultimat3/mail": "12.0.0",
-    "@ultimat3/policy": "12.0.0",
-    "@ultimat3/query": "12.0.0",
-    "@ultimat3/realtime": "12.0.0",
-    "@ultimat3/time": "12.0.0"
+    "@ultimat3/cache": "14.0.0",
+    "@ultimat3/core": "14.0.0",
+    "@ultimat3/db": "14.0.0",
+    "@ultimat3/entity": "14.0.0",
+    "@ultimat3/i18n": "14.0.0",
+    "@ultimat3/jobs": "14.0.0",
+    "@ultimat3/mail": "14.0.0",
+    "@ultimat3/policy": "14.0.0",
+    "@ultimat3/query": "14.0.0",
+    "@ultimat3/realtime": "14.0.0",
+    "@ultimat3/time": "14.0.0"
   }
 }

package/src/errors.ts

@@ -21,6 +21,7 @@ export const TESTING_ERROR_CODES = [
   'X_TEST_EVAL_THRESHOLD',
   'X_TEST_SCHEMA_EXPECTED',
   'X_TEST_JOB_EXPECTED',
+  'X_TEST_LOCATOR_EXPECTED',
   'X_TEST_NETWORK_RACE',
   'X_TEST_FACTORY_TRAIT_UNKNOWN',
   'X_TEST_FACTORY_NOT_PERSISTED',
@@ -55,6 +56,7 @@ export const TESTING_ERROR_TITLES: Readonly<Record<TestingErrorCode, string>> =
   X_TEST_EVAL_THRESHOLD: 'an evalTest() score fell below its threshold',
   X_TEST_SCHEMA_EXPECTED: 'a matcher expected a Standard Schema and got something else',
   X_TEST_JOB_EXPECTED: 'a matcher expected a job declaration and got something else',
+  X_TEST_LOCATOR_EXPECTED: 'a matcher expected a locator and got something else',
   X_TEST_NETWORK_RACE: 'a request raced unsealNetwork() and lost the patched fetch',
   X_TEST_FACTORY_TRAIT_UNKNOWN: 'a factory was asked for a trait it does not declare',
   X_TEST_FACTORY_NOT_PERSISTED: 'a factory create() had nowhere to write the row',
@@ -257,6 +259,22 @@ export class TestSchemaExpectedError extends UltimateError {
   }
 }
 
+/**
+ * `toBeVisible` was handed something with no `isVisible()` — a page, a selector string, or the
+ * result of awaiting the locator. Thrown rather than returned as a failing result, exactly as
+ * `TestSchemaExpectedError` is: the assertion is not false, it is unanswerable, and a `pass: false`
+ * would read as "the element was hidden".
+ */
+export class TestLocatorExpectedError extends UltimateError {
+  constructor() {
+    super({
+      code: 'X_TEST_LOCATOR_EXPECTED',
+      cause: 'toBeVisible expects a locator — an object with isVisible() — not a page or a string',
+      fix: 'expect(page.getByRole("heading", { name: "Feed" })).toBeVisible()   # the locator itself, unawaited',
+    });
+  }
+}
+
 /** `toEmitSteps`/`recordSteps` were handed something other than a job declaration. */
 export class TestJobExpectedError extends UltimateError {
   constructor() {

package/src/fixture-island.ts

@@ -62,8 +62,16 @@ export interface MountedIsland extends Disposable {
   ): boolean;
 }
 
+/**
+ * Module-private, and its `mount` returns `unknown` rather than `void` — the shipped hydration
+ * runtime chains `import(e).then((m) => m.mount(el, props))` (`packages/render/src/hydrate.ts`),
+ * so a browser AWAITS whatever `mount` answers before it marks the element mounted. An island that
+ * opens a queue or a socket first is therefore an ordinary island (`like.island.tsx` is `async`),
+ * and a fixture typed `=> void` could only ever call it and walk away. Widening, not narrowing: an
+ * island module is matched structurally off an `unknown` import, so nothing implements this type.
+ */
 interface IslandEntry {
-  readonly mount: (el: unknown, props: unknown) => void;
+  readonly mount: (el: unknown, props: unknown) => unknown;
 }
 
 /** `unknown` + a check, not a cast: a chunk whose `mount` was renamed is a real authoring mistake
@@ -180,7 +188,11 @@ export async function mountIsland(options: MountIslandOptions): Promise<MountedI
     if (options.shell !== undefined) {
       for (const child of [...parseHtml(options.shell).children]) el.appendChild(child);
     }
-    entry.mount(el, options.props);
+    // AWAITED, because the runtime this fixture stands in for awaits it. Left unawaited, an async
+    // island's `mount` resumed AFTER the `restore()` below had taken the fake `document` back out
+    // — so it failed with `document is not defined` inside whichever later test happened to be
+    // running, with no thread back here.
+    await entry.mount(el, options.props);
     return {
       code: chunk.code,
       el,

package/src/index.ts

@@ -185,6 +185,12 @@ export type { LiveConnection, LiveNodeHandle, LiveNodeOptions } from './live-nod
 export { createLiveNode } from './live-node';
 export type { LiveReplicator, LiveReplicatorOptions } from './live-replicator';
 export { startLiveReplicator } from './live-replicator';
+/**
+ * The budget `toBeVisible(options?)` takes. Exported because it is in a public matcher's signature;
+ * `retryUntil` and `RetryBudget` deliberately are NOT — nothing outside this package calls them,
+ * and an export nothing calls is the unwired declaration this matcher exists to have closed.
+ */
+export type { VisibleOptions } from './matcher-visible';
 export type { MatcherResult } from './matchers';
 export { matchersInstalled, recordSteps } from './matchers';
 // `isolateEntityRegistry` is deliberately NOT here — it is `@ultimat3/testing/registry-isolation`.
@@ -246,6 +252,7 @@ export {
   hasE2eDriver,
   jobTest,
   liveTest,
+  resetE2eDriver,
   SEPARATOR,
   TEST_TYPES,
   testName,

package/src/matcher-result.ts

@@ -0,0 +1,7 @@
+// What every matcher in this package hands back. Its own module so `matcher-visible.ts` can carry
+// the shape without importing `matchers.ts`, which imports it.
+
+export interface MatcherResult {
+  readonly pass: boolean;
+  message(): string;
+}

package/src/matcher-surface.ts

@@ -3,6 +3,7 @@
 // program in the repo has to READ this declaration — `tsconfig.tests.json` names this file — and a
 // tier-0 test cannot reach it by importing tier-5 `@ultimat3/testing`.
 
+import type { VisibleOptions } from './matcher-visible';
 import type { OpenApiLike } from './test-types';
 
 /**
@@ -23,6 +24,13 @@ export interface UltimateMatchers<T> {
   toBeWithinBudget(limit: number): T;
   toRejectInput(input: unknown): Promise<T>;
   toAcceptInput(input: unknown): Promise<T>;
+  /**
+   * The one matcher that WAITS. Retries `isVisible()` to a budget — 5000ms every 100ms unless
+   * narrowed — and `.not.toBeVisible()` waits for the element to GO rather than inverting one look.
+   * Point-in-time is `expect(await locator.isVisible()).toBe(true)`, and it is a different
+   * assertion: it fails on a page that simply has not painted yet.
+   */
+  toBeVisible(options?: VisibleOptions): Promise<T>;
 }
 
 declare module 'bun:test' {

package/src/matcher-visible.ts

@@ -0,0 +1,68 @@
+// The one assertion in this package that WAITS. Split from `matchers.ts` because everything about
+// it is different from the others: it has a budget, it has a direction (`.not` waits for the
+// element to go), and its message has to say what it waited for and what it saw instead.
+
+import { TestLocatorExpectedError } from './errors';
+import type { MatcherResult } from './matcher-result';
+import { DEFAULT_RETRY_BUDGET, type RetryBudget, retryUntil } from './retry';
+
+/** What a caller may narrow. Both halves default to `DEFAULT_RETRY_BUDGET`. */
+export type VisibleOptions = Partial<RetryBudget>;
+
+/**
+ * Structural, and the ONE member it insists on is the one it calls. `LocatorLike` declares four,
+ * but a matcher demanding all four would refuse a driver's element handle over members this
+ * assertion never touches — and the receiver here is whatever a test passed to `expect()`.
+ */
+export interface VisibilityProbe {
+  isVisible(): Promise<boolean>;
+}
+
+/**
+ * SYNCHRONOUS, and that is the whole reason it is a function of its own.
+ *
+ * Measured against Bun 1.4.0: a matcher declared `async` that throws has its error replaced by
+ * bun's own `Matcher \`x\` returned a promise that rejected` — the code, the cause and the fix are
+ * all gone, and the reader is told nothing. A matcher that is NOT async and throws before it
+ * returns a promise keeps the error intact. So the receiver check runs here, in the synchronous
+ * prologue, and the waiting happens in the promise that follows it.
+ */
+export const assertVisibilityProbe = (received: unknown): VisibilityProbe => {
+  const probe = received as { isVisible?: unknown };
+  if (typeof received !== 'object' || received === null || typeof probe.isVisible !== 'function') {
+    throw new TestLocatorExpectedError();
+  }
+  return received as VisibilityProbe;
+};
+
+/**
+ * `pass` is the RAW fact — whether the element was visible on the last look — because `.not`
+ * inverts it and a matcher that pre-inverted would report the wrong direction. What `isNot` decides
+ * is what this WAITS FOR: `.not.toBeVisible()` must wait for the element to disappear, not check
+ * once and invert. Inverting a single look is a no-op that passes on a page which has not painted
+ * yet, which is the exact failure a retrying assertion exists to remove.
+ */
+export const visibilityResult = async (
+  probe: VisibilityProbe,
+  isNot: boolean,
+  options: VisibleOptions = {},
+): Promise<MatcherResult> => {
+  const budget: RetryBudget = {
+    timeout: options.timeout ?? DEFAULT_RETRY_BUDGET.timeout,
+    interval: options.interval ?? DEFAULT_RETRY_BUDGET.interval,
+  };
+  const wanted = !isNot;
+  const outcome = await retryUntil(
+    () => probe.isVisible(),
+    (visible) => visible === wanted,
+    budget,
+  );
+  const looks = `${outcome.attempts} look${outcome.attempts === 1 ? '' : 's'}, ${budget.interval}ms apart`;
+  // The BUDGET is reported, never an elapsed measurement: this package freezes `Date.now()`, so an
+  // "after 4993ms" would be a number nothing in the process could have produced.
+  const waited = `within ${budget.timeout}ms (${looks})`;
+  const message = isNot
+    ? `expected the locator to stop being visible ${waited}, and it was visible every time`
+    : `expected the locator to be visible ${waited}, and it was hidden every time`;
+  return { pass: outcome.last, message: () => message };
+};

package/src/matchers.ts

@@ -6,20 +6,19 @@ import type { ExpectExtendMatchers } from 'bun:test';
 import { expect } from 'bun:test';
 import { describeValue, isUltimateError, stringField } from '@ultimat3/core';
 import { TestJobExpectedError, TestSchemaExpectedError } from './errors';
+import type { MatcherResult } from './matcher-result';
 import type { UltimateMatchers } from './matcher-surface';
+import type { VisibleOptions } from './matcher-visible';
+import { assertVisibilityProbe, visibilityResult } from './matcher-visible';
 import type { OpenApiLike } from './test-types';
 
+export type { MatcherResult } from './matcher-result';
 // Re-exported so the EMITTED `matchers.d.ts` still names `./matcher-surface`. A type-only import
 // used by a non-exported const is elided from the declaration output, and with it goes the
 // `bun:test` augmentation for anyone consuming this package through `dist/` — which is every
 // package that reaches it across a project reference.
 export type { UltimateMatchers } from './matcher-surface';
 
-export interface MatcherResult {
-  readonly pass: boolean;
-  message(): string;
-}
-
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null;
 
@@ -56,6 +55,25 @@ interface StandardSchema {
 const isStandardSchema = (value: unknown): value is StandardSchema =>
   isRecord(value) && isRecord(value['~standard']);
 
+/**
+ * The receiver check, SYNCHRONOUS and separate from the work — measured against Bun 1.4.0: a
+ * matcher declared `async` has any error it throws replaced by bun's own `Matcher \`x\` returned a
+ * promise that rejected`, so the code, the cause and the fix are all gone by the time a reader sees
+ * it. `X_TEST_SCHEMA_EXPECTED` and `X_TEST_JOB_EXPECTED` were declared, registered and titled, and
+ * no caller could ever observe either (`matcher-receiver.test.ts`). The guard runs before the
+ * matcher returns a promise; the work happens inside it.
+ */
+function assertStandardSchema(schema: unknown): StandardSchema {
+  if (!isStandardSchema(schema)) throw new TestSchemaExpectedError();
+  return schema;
+}
+
+/** The same rule for a job declaration. `recordSteps` is public, so it keeps its own check too. */
+function assertJobDeclaration(job: unknown): JobLike {
+  if (!isJob(job)) throw new TestJobExpectedError();
+  return job;
+}
+
 async function hasIssues(schema: unknown, input: unknown): Promise<boolean> {
   if (!isStandardSchema(schema)) {
     throw new TestSchemaExpectedError();
@@ -176,7 +194,28 @@ function breakingChanges(before: OpenApiLike, after: OpenApiLike): readonly stri
  * of the three is visible, and a declared-but-unimplemented matcher fails at runtime in whichever
  * test calls it first.
  */
+/**
+ * What `expect.extend` binds `this` to. Bun supplies `isNot`, and it is the only member any matcher
+ * here reads — measured, because the shape is not in bun's published types and a matcher that
+ * guessed would silently wait for the wrong thing under `.not`.
+ */
+interface MatcherContext {
+  readonly isNot: boolean;
+}
+
 const implementations: ExpectExtendMatchers<UltimateMatchers<unknown>> = {
+  // NOT `async`, deliberately — see `assertVisibilityProbe`. A matcher declared `async` has any
+  // error it throws replaced by bun's own "returned a promise that rejected", which is how the
+  // three matchers below it lost their codes. The guard runs synchronously; the wait is the
+  // promise this returns.
+  toBeVisible(received: unknown, options?: VisibleOptions) {
+    const probe = assertVisibilityProbe(received);
+    // `this` and not a parameter: the direction is bun's to tell us, and `.not` has to change what
+    // this WAITS for, not just how the answer is read.
+    const context = this as unknown as MatcherContext;
+    return visibilityResult(probe, context.isNot === true, options);
+  },
+
   toBeUltimateError(received: unknown, code?: string) {
     const actual = codeOf(received);
     if (actual === undefined) {
@@ -200,11 +239,15 @@ const implementations: ExpectExtendMatchers<UltimateMatchers<unknown>> = {
     return result(!allowed, `expected the policy to deny ${JSON.stringify(context)}`);
   },
 
-  async toEmitSteps(received: unknown, expected: readonly string[]) {
-    const names = await recordSteps(received);
-    return result(
-      JSON.stringify(names) === JSON.stringify(expected),
-      `expected steps ${expected.join(' -> ')}, ran ${names.join(' -> ')}`,
+  // Not `async` — see `assertStandardSchema`. The guard is the synchronous prologue; the wait is
+  // the promise this returns.
+  toEmitSteps(received: unknown, expected: readonly string[]) {
+    const job = assertJobDeclaration(received);
+    return recordSteps(job).then((names) =>
+      result(
+        JSON.stringify(names) === JSON.stringify(expected),
+        `expected steps ${expected.join(' -> ')}, ran ${names.join(' -> ')}`,
+      ),
     );
   },
 
@@ -232,14 +275,18 @@ const implementations: ExpectExtendMatchers<UltimateMatchers<unknown>> = {
     return result(received <= limit, `expected ${received} to be within the budget of ${limit}`);
   },
 
-  async toRejectInput(received: unknown, input: unknown) {
-    const rejected = await hasIssues(received, input);
-    return result(rejected, `expected the schema to reject ${JSON.stringify(input)}`);
+  toRejectInput(received: unknown, input: unknown) {
+    const schema = assertStandardSchema(received);
+    return hasIssues(schema, input).then((rejected) =>
+      result(rejected, `expected the schema to reject ${JSON.stringify(input)}`),
+    );
   },
 
-  async toAcceptInput(received: unknown, input: unknown) {
-    const rejected = await hasIssues(received, input);
-    return result(!rejected, `expected the schema to accept ${JSON.stringify(input)}`);
+  toAcceptInput(received: unknown, input: unknown) {
+    const schema = assertStandardSchema(received);
+    return hasIssues(schema, input).then((rejected) =>
+      result(!rejected, `expected the schema to accept ${JSON.stringify(input)}`),
+    );
   },
 };
 

package/src/retry.ts

@@ -0,0 +1,89 @@
+// Poll an observation until it matches, or until a declared budget runs out. The MECHANISM behind
+// every retrying assertion in this package, owned here so a second one cannot arrive with its own
+// deadline, its own interval and its own idea of what to report — the rule `backoff.ts` already
+// holds for retries that back off.
+
+import { assert } from '@ultimat3/core';
+
+/**
+ * What a retrying assertion is allowed to spend. A FIXED interval and not a curve: an assertion
+ * about a page is asked "is it there yet", and doubling the gap makes the last look land long
+ * after the state changed — the caller's deadline is the contract, and a curve would quietly
+ * spend most of it waiting. There is exactly one backoff curve in this framework
+ * (`@ultimat3/core`'s `backoff.ts`) and this is deliberately not a second one.
+ */
+export interface RetryBudget {
+  /** Total time the assertion may wait, in milliseconds. `0` is one look and no wait. */
+  readonly timeout: number;
+  /** Gap between looks, in milliseconds. */
+  readonly interval: number;
+}
+
+export interface RetryOutcome<T> {
+  readonly matched: boolean;
+  /** How many times the observation ran. `attemptsFor(budget)` when it never matched. */
+  readonly attempts: number;
+  /** What the last look answered — what a failure message reports as "saw" instead. */
+  readonly last: T;
+}
+
+/** Playwright's own default, which is what a reader of `toBeVisible()` already expects. */
+export const DEFAULT_RETRY_BUDGET: RetryBudget = { timeout: 5_000, interval: 100 };
+
+/**
+ * How many times the observation will run at most: one free look, plus one per whole interval in
+ * the budget. Exported because it is what makes a retry TESTABLE — a test asserts this number
+ * rather than measuring elapsed time, which is the one thing a frozen clock cannot give it.
+ */
+export const attemptsFor = (budget: RetryBudget): number =>
+  1 + Math.floor(budget.timeout / budget.interval);
+
+/** Real time passes here and nowhere else in this module, which is what makes `sleep` injectable. */
+const wait = (ms: number): Promise<void> =>
+  new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+
+/**
+ * Look, test, sleep, repeat — stopping on the look that matches or on the last one the budget buys.
+ *
+ * `sleep` is a DEFAULT PARAMETER and not a module-level call, the same seam a `random = Math.random`
+ * default is: a test injects a counting stub and asserts how many times this slept and how many
+ * times it looked, so "it retried, and it stopped when it said it would" is a measurement rather
+ * than a wall-clock hope. This package freezes `Date.now()`, so a deadline computed from the clock
+ * would never expire and the loop would spin forever — the budget is counted in LOOKS for that
+ * reason, not in elapsed milliseconds.
+ *
+ * Never sleeps after the look that answered: a passing assertion costs one observation and no time
+ * at all, which is what keeps a retrying matcher usable in a suite of hundreds.
+ */
+export const retryUntil = async <T>(
+  observe: () => Promise<T>,
+  matches: (value: T) => boolean,
+  budget: RetryBudget = DEFAULT_RETRY_BUDGET,
+  sleep: (ms: number) => Promise<void> = wait,
+): Promise<RetryOutcome<T>> => {
+  // Refused rather than attempted: a zero or negative interval is an unbounded spin, and the
+  // failure mode is a test that never fails — it hangs, and CI reports a runner timeout with no
+  // assertion anywhere in it.
+  assert(
+    Number.isFinite(budget.interval) && budget.interval > 0,
+    `a retry interval must be a positive number of milliseconds, got ${String(budget.interval)}`,
+    'toBeVisible({ interval: 100 })   # the gap between looks; the default budget is 5000ms every 100ms',
+  );
+  assert(
+    Number.isFinite(budget.timeout) && budget.timeout >= 0,
+    `a retry timeout must be zero or more milliseconds, got ${String(budget.timeout)}`,
+    'toBeVisible({ timeout: 5000 })   # the whole wait; 0 is one look and no wait',
+  );
+  const limit = attemptsFor(budget);
+  let attempts = 0;
+  let last = await observe();
+  attempts += 1;
+  while (!matches(last) && attempts < limit) {
+    await sleep(budget.interval);
+    last = await observe();
+    attempts += 1;
+  }
+  return { matched: matches(last), attempts, last };
+};

package/src/test-types.ts

@@ -44,19 +44,31 @@ export interface LocatorLike {
 }
 
 /**
- * The browser surface an e2e test drives. Every member is one the reference app's e2e suite
- * already calls — this is the observed contract, not a wish list, and the driver that implements
- * it (a browser, at milestone 11) is the only thing that may add to it.
+ * The browser surface an e2e test drives. Intended as the OBSERVED contract rather than a wish
+ * list, and the driver that implements it (a browser, at milestone 11) is the only thing that may
+ * add to it.
+ *
+ * This comment claimed every member was one the reference app's e2e suite already calls, and an
+ * audit on 2026-08-24 found that false for three of eleven: `content()` had ZERO call sites
+ * anywhere in the repository, and `title()` / `reload()` are named only by `x g route`'s generated
+ * template — a string the CLI writes, which nothing executes. `content()` is deleted; the other
+ * two keep their line WITH the caveat, because a generated template is a real contract the moment
+ * a driver lands and a scaffolded app runs it.
+ *
+ * The claim was checkable and nobody checked it, which is the class this tree keeps re-shipping.
+ * Nothing enforces this one either: `PageLike` has no driver, so an unwired member cannot fail —
+ * see `hasE2eDriver()`. Do not restore the absolute wording without a rule that reads it.
  */
 export interface PageLike {
   goto(url: string): Promise<unknown>;
   /** The first flush of a streamed response — the shell, before the holes resolve. */
   gotoStreamed(url: string): Promise<{ readonly html: string }>;
+  /** Called only by `x g route`'s generated e2e template — no driver runs it yet. */
   reload(): Promise<unknown>;
   /** Resolves once the service worker controls the page, so the offline assertions are not racy. */
   waitForServiceWorker(): Promise<void>;
+  /** Called only by `x g route`'s generated e2e template — no driver runs it yet. */
   title(): Promise<string>;
-  content(): Promise<string>;
   url(): string;
   evaluate<T>(fn: () => T): Promise<T>;
   locator(selector: string): LocatorLike;
@@ -100,6 +112,16 @@ export function useE2eDriver(driver: (name: string, body: E2eBody) => void): voi
  * instead of reading an all-skipped run as a green one. */
 export const hasE2eDriver = (): boolean => e2eDriver !== undefined;
 
+/**
+ * Put the seam back. The counterpart `useE2eDriver` shipped without, and the module scope it
+ * writes to is process-global: `bun test` shares one process across files, so a file that installs
+ * a browser and does not undo it hands every later file an `e2eTest` that opens a page nobody
+ * asked for. Same shape and same reason as `@ultimat3/scraping`'s `resetScrapeDriver()`.
+ */
+export const resetE2eDriver = (): void => {
+  e2eDriver = undefined;
+};
+
 export const e2eTest = (name: string, body: E2eBody): void => {
   if (e2eDriver === undefined) {
     test.skip(