@orkestrel/test 0.0.15 → 0.0.17

package/dist/src/core/index.d.cts

@@ -1,3 +1,24 @@
+/**
+ * Builds the error a refused fixture build raises, named for the row it was building for.
+ *
+ * @param name - The row's name, which opens the message.
+ * @param cause - The value the builder refused with, which becomes the returned error's `cause`.
+ * @returns The refusal, unthrown.
+ * @remarks {@link executeScenarios} raises this one, and `createHarness` in the browser environment
+ * announces its `message` on the row it refused, so the runner and the harness name a refused build
+ * with one sentence rather than two spellings of it. The refusal arrives as the `cause` by identity,
+ * so its own message and stack survive the naming.
+ *
+ * @example
+ * ```ts
+ * import { buildRefusal } from '@orkestrel/test'
+ *
+ * buildRefusal('closed opens through the summary', new Error('no fixture')).message
+ * // 'closed opens through the summary: build refused'
+ * ```
+ */
+export declare function buildRefusal(name: string, cause: unknown): Error;
+
 /**
  * Builds the error {@link retryUntil} raises when its elapsed-time budget runs out.
  *
@@ -281,462 +302,565 @@ export declare function executeScenario<TState extends string, TEvent extends st
  * @param scenarios - The table to drive, in the order it is written.
  * @param build - The fixture builder, called once per row and awaited when it returns a promise.
  * @returns A promise that resolves after the last row completes.
- * @throws An `Error` reading `<name>: build refused` when the row's builder throws or rejects, whose
- * `cause` is the value the builder refused with, or whatever {@link executeScenario} throws for the
- * first row whose phases fail. Either way the run stops at that row and the rows after it never
- * start.
- * @remarks The rows run one after another rather than together: a statechart's rows drive one
- * entity on one page, so a parallel run would have them arranging over each other. `build` receives
- * the row it is building for, which is what lets one table mix fixtures.
- *
- * A refusing builder is named for its row the way a failing phase is, because a table's rows build
- * under one test name too. The refusal itself arrives as the `cause`, by identity, so its own
- * message and stack survive the naming.
- *
- * @example
- * ```ts
- * await executeScenarios(SCENARIOS, () => ({ disclosure: new Disclosure() }))
- * ```
- */
-export declare function executeScenarios<TState extends string, TEvent extends string, TContext>(scenarios: ReadonlyArray<StateScenario<TState, TEvent, TContext>>, build: (scenario: StateScenario<TState, TEvent, TContext>) => TContext | Promise<TContext>): Promise<void>;
-
-/**
- * Normalizes headers into a frozen plain record.
- *
- * @param init - The platform header initializer to normalize.
- * @returns A frozen record of normalized header names and values.
- * @remarks Normalization follows the host `Headers` implementation, including lowercased names and
- * combined values.
- */
-export declare function flattenHeaders(init: HeadersSource): Readonly<Record<string, string>>;
-
-/**
- * Covers any value the host `Headers` constructor accepts.
- *
- * @remarks Derived from the host constructor rather than named from a single library, so the type
- * resolves in every project against that project's own `Headers` declaration. The record,
- * entries-array, and `Headers` forms all satisfy it.
- */
-export declare type HeadersSource = NonNullable<ConstructorParameters<typeof Headers>[0]>;
-
-/**
- * Invokes an unknown method through an explicit unchecked result contract.
- *
- * @typeParam T - The result type claimed by the caller.
- * @param target - The value used as the method's `this` argument.
- * @param method - The unknown method to invoke.
- * @param args - The arguments to pass.
- * @returns The method's result under the caller's claimed type.
- * @throws A `TypeError` when `method` is not callable.
- * @remarks The caller owns the claim that the returned value has type `T`. The contained `any`
- * bridges the unchecked runtime result to that caller-owned claim.
- */
-export declare function invokeUnchecked<T>(target: unknown, method: unknown, args: readonly unknown[]): T;
-
-/**
- * Checks whether a value contains a recorder for every listed event.
- *
- * @typeParam TMap - The source's event names and delivered argument tuples.
- * @typeParam TName - The event names represented in the map.
- * @param value - The value to inspect.
- * @param events - The events the completed map must contain.
- * @returns True if every listed event has a structurally valid recorder; false otherwise.
- * @remarks Per-key tuple precision is the predicate's claim. The factory proves that claim by
- * wiring each recorder to exactly the event where it stores that recorder. A direct caller must
- * establish the same pairing before it relies on the narrowing. This guard takes the listed events
- * through a reference parameter rather than using the canonical single-value guard form.
- *
- * @example
- * ```ts
- * import { createRecorder, isRecorderMapComplete } from '@orkestrel/test'
- *
- * type ReadyEvents = { readonly ready: readonly [name: string, step: number] }
- *
- * const value: unknown = { ready: createRecorder<readonly [name: string, step: number]>() }
- *
- * isRecorderMapComplete<ReadyEvents, 'ready'>(value, ['ready']) // true
- * isRecorderMapComplete<ReadyEvents, 'ready'>({ ready: 1 }, ['ready']) // false
- * ```
- */
-export declare function isRecorderMapComplete<TMap extends Record<string, readonly unknown[]>, TName extends keyof TMap>(value: unknown, events: readonly TName[]): value is RecorderMap<TMap, TName>;
-
-/**
- * Represents the JSON-safe projection of a type: every member JSON preserves, mapped to itself, and
- * every member it does not, mapped to `never`.
- *
- * @typeParam T - The type to project.
- * @remarks Intersect a parameter with this rather than constraining it to `JSONValue`. A `JSONValue`
- * constraint rejects every `interface`, because TypeScript grants an implicit index signature to a
- * type alias and never to an interface, and interfaces are what this project's public types are. A
- * value whose type survives the projection satisfies the intersection unchanged; one that carries a
- * method, a `Date`, a `Map`, the opaque `object` type, or a symbol-keyed member meets `never` at that
- * member and is rejected there. A member typed `undefined` is rejected the same way, because
- * serialization drops it from an object and rewrites it to `null` in an array, so the returned type
- * would claim a member the copy does not carry. An optional member survives, since its declared type
- * still narrows to what JSON keeps. A member declared `?: X | undefined` and passed an explicit
- * `undefined` is refused; declare it `?: X` and omit the member instead. `unknown` passes through
- * unvetted by the projection. For an `unknown` member, `roundTripJSON` refuses `undefined`,
- * functions, symbols, and non-finite numbers at runtime; JSON otherwise may silently reshape the
- * value, such as a `Date` to a string or a `Map` to `{}`.
- * @example
- * ```ts
- * interface Snapshot {
- * 	readonly id: string
- * 	readonly turns: number
- * }
- *
- * // { readonly id: string; readonly turns: number } — every member survives.
- * type Safe = JSONSafe<Snapshot>
- * ```
- */
-export declare type JSONSafe<T> = unknown extends T ? T : T extends string | number | boolean | null ? T : T extends ReadonlyArray<infer E> ? ReadonlyArray<JSONSafe<E>> : T extends (...args: never[]) => unknown ? never : T extends object ? object extends T ? never : {
-    readonly [K in keyof T]: K extends symbol ? never : JSONSafe<T[K]>;
-} : never;
-
-/**
- * Reads a property from an unknown object or function.
- *
- * @typeParam T - The property type claimed by the caller.
- * @param target - The unknown value to read.
- * @param key - The property key to read.
- * @returns The property value under the caller's claimed type.
- * @throws A `TypeError` when `target` is neither an object nor a function.
- * @remarks The caller owns the claim that the returned value has type `T`. The contained `any`
- * bridges the unchecked runtime result to that caller-owned claim.
- */
-export declare function readProperty<T>(target: unknown, key: PropertyKey): T;
-
-/**
- * Records every call made to its handler.
- *
- * @typeParam TArgs - The argument tuple the recorded handler accepts.
- */
-export declare interface RecorderInterface<TArgs extends readonly unknown[]> {
-    /** Lists every recorded call, oldest first, each entry the arguments of one call. */
-    readonly calls: readonly TArgs[];
-    /** Reports how many calls have been recorded. */
-    readonly count: number;
-    /** Holds the callback to hand to the code under test. */
-    readonly handler: (...args: TArgs) => void;
-    /**
-     * Discards the recorded calls and keeps the recorder usable.
-     *
-     * @remarks The list is truncated in place, so a `calls` reference taken earlier empties too.
-     */
-    clear(): void;
-}
-
-/**
- * Maps event names to recorders for their delivered argument tuples.
- *
- * @typeParam TMap - The event names and argument tuples the source delivers.
- * @typeParam TName - The event names represented in the map.
- */
-export declare type RecorderMap<TMap extends Record<string, readonly unknown[]>, TName extends keyof TMap> = {
-    readonly [K in TName]: RecorderInterface<TMap[K]>;
-};
-
-/**
- * Narrows a value away from `null` and `undefined`, throwing when it is absent.
- *
- * @typeParam T - The required value type.
- * @param value - The value to check.
- * @param message - The error message used when the value is absent. Default: `'Value is required'`.
- * @returns The present value.
- * @throws An `Error` carrying `message` when the value is `null` or `undefined`.
- */
-export declare function requireValue<T>(value: T | null | undefined, message?: string): T;
-
-/**
- * Resolves the parent directory of a calling module, which is the workspace root when called from
- * the conventional `tests/setup.ts` location.
- *
- * @param meta - The calling module metadata.
- * @returns The root URL one directory above the calling file.
- */
-export declare function resolveRoot(meta: ImportMeta): URL;
-
-/** Represents a numbered resource factory with records of every creation and destruction. */
-export declare interface ResourceFactoryInterface {
-    /** Records the ids returned by `create`, in order. */
-    readonly created: RecorderInterface<readonly [id: number]>;
-    /** Records the ids passed to `destroy`, in order. */
-    readonly destroyed: RecorderInterface<readonly [id: number]>;
-    /**
-     * Creates a numbered resource.
+ * @throws {@link buildRefusal}'s `Error` reading `<name>: build refused` when the row's builder
+     * throws or rejects, or whatever {@link executeScenario} throws for the first row whose phases
+     * fail. Either way the run stops at that row and the rows after it never start.
+     * @remarks The rows run one after another rather than together: a statechart's rows drive one
+     * entity on one page, so a parallel run would have them arranging over each other. `build` receives
+     * the row it is building for, which is what lets one table mix fixtures.
      *
-     * @returns The next monotonically increasing id.
-     * @remarks The id is the creation record's length plus one, so it counts allocations rather than
-     * live resources: a destroyed id is never reissued, and clearing `created` restarts the numbering
-     * at `1`.
-     */
-    create(): number;
-    /**
-     * Destroys a numbered resource.
+     * A refusing builder is named for its row the way a failing phase is, because a table's rows build
+     * under one test name too. `buildRefusal` owns that sentence, so the harness the browser
+     * environment publishes announces the same one rather than a second spelling of it.
      *
-     * @param id - The resource id to destroy.
-     * @remarks It records the id and nothing else: it frees nothing, refuses nothing, and accepts an
-     * id that was never created, so a suite asserts on the record rather than on a refusal.
+     * @example
+     * ```ts
+     * await executeScenarios(SCENARIOS, () => ({ disclosure: new Disclosure() }))
+     * ```
      */
-    destroy(id: number): void;
-}
-
-/** Configures a bounded retry, adding an optional producer-call limit to a bounded wait's bounds. */
-export declare interface RetryOptions extends WaitOptions {
-    /** Caps the number of producer calls. When omitted, only the time budget bounds the retry. */
-    readonly attempts?: number;
-}
-
-/**
- * Repeats a producer until one produced value satisfies a predicate.
- *
- * @typeParam T - The produced value type.
- * @param description - The operation described in an exhaustion error.
- * @param produce - The synchronous or asynchronous operation to repeat.
- * @param satisfied - The predicate that accepts a produced value.
- * @param options - The time, attempt, and abort bounds.
- * @returns The first produced value the predicate accepts.
- * @throws The predicate's thrown value, the abort reason, or an `Error` when a bound is invalid or
- * the retry exhausts its budget or attempts.
- * @remarks A producer throw counts as an unsatisfied attempt. The last producer error becomes the
- * exhaustion error's `cause`. Default budget: `1000` milliseconds. Default interval: `10`
- * milliseconds.
- */
-export declare function retryUntil<T>(description: string, produce: () => T | Promise<T>, satisfied: (value: T) => boolean, options?: RetryOptions): Promise<T>;
-
-/**
- * Copies a JSON value through serialization and parsing.
- *
- * @typeParam T - The copied value's type, which the copy keeps.
- * @param value - The value to copy, bounded by its own `JSONSafe` projection.
- * @returns The parsed JSON copy.
- * @remarks Non-finite numbers throw because JSON would replace them with `null`. Negative zero is
- * normalized to zero by JSON serialization. The bound intersects `JSONSafe<T>` rather than
- * constraining `T` to `JSONValue`, so an interface-typed value round-trips.
- */
-export declare function roundTripJSON<T>(value: T & JSONSafe<T>): T;
-
-/** Holds a real abort signal and controller instrumented with its live abort-listener tally. */
-export declare interface SignalInterface {
-    /** Holds the controller that owns the signal. */
-    readonly controller: AbortController;
-    /** Holds the signal to hand to the code under test. */
-    readonly signal: AbortSignal;
-    /** Reports the live abort-listener tally. */
-    readonly count: number;
-}
-
-/**
- * Represents one abort listener an instrumented signal installed, as its tally holds it.
- *
- * @remarks The members are the listener the caller supplied, the listener installed in its place,
- * the capture flag the pair was registered under, and the controller that removes the scope
- * subscription installed beside it, which is `undefined` where no other signal scopes the
- * registration.
- */
-export declare type SignalRegistration = readonly [
-listener: EventListener | EventListenerObject,
-installed: EventListener | EventListenerObject,
-capture: boolean,
-cleanup: AbortController | undefined
-];
-
-/**
- * Names the attributes a statechart harness publishes, keyed by the fact each one carries.
- *
- * @remarks
- * A harness renders its own table and a gate outside the page polls the rendered markup, so these
- * names are the whole contract between the two. `status`, `passed`, `failed`, and `total` belong on
- * the harness root, because a gate finds the harness by `status` and reads the tally from the same
- * element. `scenario` and `result` belong on each row, so a failing row is found by `result` and
- * named by `scenario`. `state` belongs on the element rendering the entity's current state.
- *
- * The values are the attribute names themselves, so a harness writes `setAttribute` against this map
- * and a gate writes `querySelector` against it, and neither spells a `data-statechart-*` string of
- * its own.
- *
- * @example
- * ```ts
- * harness.getAttribute(STATECHART_ATTRIBUTES.status) // 'passed'
- * ```
- */
-export declare const STATECHART_ATTRIBUTES: Readonly<{
-    status: "data-statechart-status";
-    passed: "data-statechart-passed";
-    failed: "data-statechart-failed";
-    total: "data-statechart-total";
-    scenario: "data-statechart-scenario";
-    result: "data-statechart-result";
-    state: "data-statechart-state";
-}>;
-
-/**
- * Lists every value a statechart harness reports through its `status` attribute.
- *
- * @remarks
- * `pending` is what a harness carries before a run has produced a result for every row, `idle` is a
- * harness standing ready with nothing running, and `running` is a run in flight. `passed` and
- * `failed` are the two terminal readings, so a gate waits for membership in that pair rather than
- * for a fixed duration.
- *
- * The tuple's order is the order a run passes through, and its element type is the literal union, so
- * `(typeof STATECHART_STATUSES)[number]` is the status type a harness and its gate share.
- *
- * @example
- * ```ts
- * const terminal = new Set<string>([STATECHART_STATUSES[3], STATECHART_STATUSES[4]])
- * ```
- */
-export declare const STATECHART_STATUSES: readonly ["pending", "idle", "running", "passed", "failed"];
-
-/**
- * Drives one {@link StateTransition} through the three phases that prove it.
- *
- * @typeParam TState - The states the entity moves between, as a string-literal union.
- * @typeParam TEvent - The events the entity accepts, as a string-literal union.
- * @typeParam TContext - The fixture the three phases drive.
- * @remarks Each phase receives the context and the part of the transition it is responsible for, so
- * a phase reads its subject from its own parameters rather than from the row it belongs to. A phase
- * may be synchronous or asynchronous, and `executeScenario` awaits each one before starting the
- * next.
- */
-export declare interface StateScenario<TState extends string, TEvent extends string, TContext> {
-    /** Holds the row this scenario drives. */
-    readonly transition: StateTransition<TState, TEvent>;
-    /**
-     * Puts the entity into the transition's `from` state.
-     *
-     * @param context - The fixture this row drives.
-     * @param state - The transition's `from` state.
-     */
-    arrange(context: TContext, state: TState): Promise<void> | void;
-    /**
-     * Applies the transition's event to the arranged entity.
-     *
-     * @param context - The fixture this row drives.
-     * @param event - The transition's event.
-     */
-    act(context: TContext, event: TEvent): Promise<void> | void;
-    /**
-     * Checks that the entity reached the transition's `to` state.
-     *
-     * @param context - The fixture this row drives.
-     * @param state - The transition's `to` state.
-     * @remarks Whatever it throws is renamed with the row's name and rethrown.
-     */
-    assert(context: TContext, state: TState): Promise<void> | void;
-}
-
-/**
- * Represents one row of a statechart table: the entity's state before an event, the event, and the
- * state that event must leave it in.
- *
- * @typeParam TState - The states the entity moves between, as a string-literal union.
- * @typeParam TEvent - The events the entity accepts, as a string-literal union.
- * @remarks The two unions are the entity's own vocabulary, so a table naming a state or an event the
- * entity does not have fails to typecheck rather than failing at runtime.
- */
-export declare interface StateTransition<TState extends string, TEvent extends string> {
-    /** Holds the row's name, which is prepended to the message of whatever the row throws. */
-    readonly name: string;
-    /** Holds the state the row arranges before it acts. */
-    readonly from: TState;
-    /** Holds the event the row applies to the arranged entity. */
-    readonly event: TEvent;
-    /** Holds the state the row asserts the entity reached. */
-    readonly to: TState;
-}
-
-/** Represents the work one teardown entry performs when the list is destroyed. */
-export declare type TeardownHandler = () => void | Promise<void>;
-
-/** Represents the cleanup a test adds as it goes and runs once, newest first, when it is done. */
-export declare interface TeardownInterface {
-    /** Reports how many handlers are registered. */
-    readonly count: number;
-    /**
-     * Registers a handler to run when the list is destroyed.
-     *
-     * @param handler - The work to perform.
-     * @remarks Registration order is what `destroy` reverses, so the newest registration is undone
-     * first.
-     */
-    add(handler: TeardownHandler): void;
-    /**
-     * Runs every registered handler in reverse registration order, awaiting each in turn, and empties
-     * the list.
-     *
-     * @throws The value the failed handler threw, by identity, when exactly one handler failed. An
-     * `AggregateError` carrying every thrown value in run order, when several did.
-     * @remarks Every handler runs, including after an earlier one throws or rejects. A handler
-     * registered while the run is in progress stays registered for the next call rather than joining
-     * this one. The snapshot it ran is discarded, so a repeated call runs nothing that already ran.
-     */
-    destroy(): Promise<void>;
-}
-
-/**
- * Waits until an abort signal is aborted.
- *
- * @param signal - The signal to observe.
- * @returns A promise that resolves when the signal is aborted.
- * @remarks An already-aborted signal resolves immediately. Otherwise the wait parks on a one-shot
- * abort listener without a timer or polling.
- */
-export declare function waitForAbort(signal: AbortSignal): Promise<void>;
-
-/**
- * Waits until a condition holds within an elapsed-time budget.
- *
- * @param description - The condition described in a timeout error.
- * @param condition - The synchronous or asynchronous condition to read.
- * @param options - The time bounds and abort signal.
- * @returns A promise that resolves when the condition first returns `true`.
- * @throws The condition's thrown value, the abort reason, or an `Error` when a bound is invalid or
- * the condition does not hold within the budget.
- * @remarks The first read is immediate. Default budget: `1000` milliseconds. Default interval: `10`
- * milliseconds.
- */
-export declare function waitForCondition(description: string, condition: () => boolean | Promise<boolean>, options?: WaitOptions): Promise<void>;
-
-/**
- * Waits for a host timer to elapse.
- *
- * @param ms - The delay in milliseconds. Default: `0`.
- * @returns A promise that resolves after the timer fires.
- */
-export declare function waitForDelay(ms?: number): Promise<void>;
-
-/**
- * Waits for the first delivery from an event subscription.
- *
- * @typeParam TArgs - The delivered argument tuple.
- * @param subscribe - The function that installs the event listener and may return its cleanup.
- * @param description - The event described in a timeout error.
- * @param options - The time bounds and abort signal.
- * @returns The first delivered argument tuple.
- * @throws The subscription's thrown value, the abort reason, or an `Error` when a bound is invalid
- * or the event is not delivered within the budget.
- * @remarks Default budget: `1000` milliseconds. The interval is validated for consistency with the
- * wait family but is not used because this helper parks on the event.
- */
-export declare function waitForEvent<TArgs extends readonly unknown[]>(subscribe: EventSubscriber<TArgs>, description: string, options?: WaitOptions): Promise<TArgs>;
-
-/**
- * Configures a bounded asynchronous wait with an elapsed-time limit, a delay between readings, and
- * an abort signal.
- *
- * @remarks
- * A default belongs to the function that reads these bounds rather than to the shape, because the
- * consumers do not agree on one. Each states its own numbers in its `@remarks`.
- */
-export declare interface WaitOptions {
-    /** Holds the elapsed-time limit in milliseconds. */
-    readonly budget?: number;
-    /** Holds the delay between readings in milliseconds. */
-    readonly interval?: number;
-    /** Holds the signal that aborts the wait. */
-    readonly signal?: AbortSignal;
-}
-
-export { }
+ export declare function executeScenarios<TState extends string, TEvent extends string, TContext>(scenarios: ReadonlyArray<StateScenario<TState, TEvent, TContext>>, build: (scenario: StateScenario<TState, TEvent, TContext>) => TContext | Promise<TContext>): Promise<void>;
+
+ /**
+  * Normalizes headers into a frozen plain record.
+  *
+  * @param init - The platform header initializer to normalize.
+  * @returns A frozen record of normalized header names and values.
+  * @remarks Normalization follows the host `Headers` implementation, including lowercased names and
+  * combined values.
+  */
+ export declare function flattenHeaders(init: HeadersSource): Readonly<Record<string, string>>;
+
+ /**
+  * Covers any value the host `Headers` constructor accepts.
+  *
+  * @remarks Derived from the host constructor rather than named from a single library, so the type
+  * resolves in every project against that project's own `Headers` declaration. The record,
+  * entries-array, and `Headers` forms all satisfy it.
+  */
+ export declare type HeadersSource = NonNullable<ConstructorParameters<typeof Headers>[0]>;
+
+ /**
+  * Invokes an unknown method through an explicit unchecked result contract.
+  *
+  * @typeParam T - The result type claimed by the caller.
+  * @param target - The value used as the method's `this` argument.
+  * @param method - The unknown method to invoke.
+  * @param args - The arguments to pass.
+  * @returns The method's result under the caller's claimed type.
+  * @throws A `TypeError` when `method` is not callable.
+  * @remarks The caller owns the claim that the returned value has type `T`. The contained `any`
+  * bridges the unchecked runtime result to that caller-owned claim.
+  */
+ export declare function invokeUnchecked<T>(target: unknown, method: unknown, args: readonly unknown[]): T;
+
+ /**
+  * Checks whether a value contains a recorder for every listed event.
+  *
+  * @typeParam TMap - The source's event names and delivered argument tuples.
+  * @typeParam TName - The event names represented in the map.
+  * @param value - The value to inspect.
+  * @param events - The events the completed map must contain.
+  * @returns True if every listed event has a structurally valid recorder; false otherwise.
+  * @remarks Per-key tuple precision is the predicate's claim. The factory proves that claim by
+  * wiring each recorder to exactly the event where it stores that recorder. A direct caller must
+  * establish the same pairing before it relies on the narrowing. This guard takes the listed events
+  * through a reference parameter rather than using the canonical single-value guard form.
+  *
+  * @example
+  * ```ts
+  * import { createRecorder, isRecorderMapComplete } from '@orkestrel/test'
+  *
+  * type ReadyEvents = { readonly ready: readonly [name: string, step: number] }
+  *
+  * const value: unknown = { ready: createRecorder<readonly [name: string, step: number]>() }
+  *
+  * isRecorderMapComplete<ReadyEvents, 'ready'>(value, ['ready']) // true
+  * isRecorderMapComplete<ReadyEvents, 'ready'>({ ready: 1 }, ['ready']) // false
+  * ```
+  */
+ export declare function isRecorderMapComplete<TMap extends Record<string, readonly unknown[]>, TName extends keyof TMap>(value: unknown, events: readonly TName[]): value is RecorderMap<TMap, TName>;
+
+ /**
+  * Represents one theme-and-viewport pair in the form a project configuration can serialize.
+  *
+  * @remarks
+  * A capture matrix is declared twice — once in the configuration that registers one test project
+  * per variant, and once in the suite that renders them — so this is the shape the two agree on.
+  * Every member is data a JSON file can carry, which is what keeps it reachable from a
+  * configuration; the browser environment's `CaptureVariant` extends it with the document change a
+  * capture applies, which a configuration cannot carry.
+  */
+ export declare interface JourneyVariant {
+     /** Holds the variant's name, which is the second half of every filename a capture run writes. */
+     readonly name: string;
+     /** Holds the viewport width in pixels. */
+     readonly width: number;
+     /** Holds the viewport height in pixels. */
+     readonly height: number;
+ }
+
+ /**
+  * Represents the JSON-safe projection of a type: every member JSON preserves, mapped to itself, and
+  * every member it does not, mapped to `never`.
+  *
+  * @typeParam T - The type to project.
+  * @remarks Intersect a parameter with this rather than constraining it to `JSONValue`. A `JSONValue`
+  * constraint rejects every `interface`, because TypeScript grants an implicit index signature to a
+  * type alias and never to an interface, and interfaces are what this project's public types are. A
+  * value whose type survives the projection satisfies the intersection unchanged; one that carries a
+  * method, a `Date`, a `Map`, the opaque `object` type, or a symbol-keyed member meets `never` at that
+  * member and is rejected there. A member typed `undefined` is rejected the same way, because
+  * serialization drops it from an object and rewrites it to `null` in an array, so the returned type
+  * would claim a member the copy does not carry. An optional member survives, since its declared type
+  * still narrows to what JSON keeps. A member declared `?: X | undefined` and passed an explicit
+  * `undefined` is refused; declare it `?: X` and omit the member instead. `unknown` passes through
+  * unvetted by the projection. For an `unknown` member, `roundTripJSON` refuses `undefined`,
+  * functions, symbols, and non-finite numbers at runtime; JSON otherwise may silently reshape the
+  * value, such as a `Date` to a string or a `Map` to `{}`.
+  * @example
+  * ```ts
+  * interface Snapshot {
+  * 	readonly id: string
+  * 	readonly turns: number
+  * }
+  *
+  * // { readonly id: string; readonly turns: number } — every member survives.
+  * type Safe = JSONSafe<Snapshot>
+  * ```
+  */
+ export declare type JSONSafe<T> = unknown extends T ? T : T extends string | number | boolean | null ? T : T extends ReadonlyArray<infer E> ? ReadonlyArray<JSONSafe<E>> : T extends (...args: never[]) => unknown ? never : T extends object ? object extends T ? never : {
+     readonly [K in keyof T]: K extends symbol ? never : JSONSafe<T[K]>;
+ } : never;
+
+ /**
+  * Reads a property from an unknown object or function.
+  *
+  * @typeParam T - The property type claimed by the caller.
+  * @param target - The unknown value to read.
+  * @param key - The property key to read.
+  * @returns The property value under the caller's claimed type.
+  * @throws A `TypeError` when `target` is neither an object nor a function.
+  * @remarks The caller owns the claim that the returned value has type `T`. The contained `any`
+  * bridges the unchecked runtime result to that caller-owned claim.
+  */
+ export declare function readProperty<T>(target: unknown, key: PropertyKey): T;
+
+ /**
+  * Records every call made to its handler.
+  *
+  * @typeParam TArgs - The argument tuple the recorded handler accepts.
+  */
+ export declare interface RecorderInterface<TArgs extends readonly unknown[]> {
+     /** Lists every recorded call, oldest first, each entry the arguments of one call. */
+     readonly calls: readonly TArgs[];
+     /** Reports how many calls have been recorded. */
+     readonly count: number;
+     /** Holds the callback to hand to the code under test. */
+     readonly handler: (...args: TArgs) => void;
+     /**
+      * Discards the recorded calls and keeps the recorder usable.
+      *
+      * @remarks The list is truncated in place, so a `calls` reference taken earlier empties too.
+      */
+     clear(): void;
+ }
+
+ /**
+  * Maps event names to recorders for their delivered argument tuples.
+  *
+  * @typeParam TMap - The event names and argument tuples the source delivers.
+  * @typeParam TName - The event names represented in the map.
+  */
+ export declare type RecorderMap<TMap extends Record<string, readonly unknown[]>, TName extends keyof TMap> = {
+     readonly [K in TName]: RecorderInterface<TMap[K]>;
+ };
+
+ /**
+  * Narrows a value away from `null` and `undefined`, throwing when it is absent.
+  *
+  * @typeParam T - The required value type.
+  * @param value - The value to check.
+  * @param message - The error message used when the value is absent. Default: `'Value is required'`.
+  * @returns The present value.
+  * @throws An `Error` carrying `message` when the value is `null` or `undefined`.
+  */
+ export declare function requireValue<T>(value: T | null | undefined, message?: string): T;
+
+ /**
+  * Resolves the parent directory of a calling module, which is the workspace root when called from
+  * the conventional `tests/setup.ts` location.
+  *
+  * @param meta - The calling module metadata.
+  * @returns The root URL one directory above the calling file.
+  */
+ export declare function resolveRoot(meta: ImportMeta): URL;
+
+ /** Represents a numbered resource factory with records of every creation and destruction. */
+ export declare interface ResourceFactoryInterface {
+     /** Records the ids returned by `create`, in order. */
+     readonly created: RecorderInterface<readonly [id: number]>;
+     /** Records the ids passed to `destroy`, in order. */
+     readonly destroyed: RecorderInterface<readonly [id: number]>;
+     /**
+      * Creates a numbered resource.
+      *
+      * @returns The next monotonically increasing id.
+      * @remarks The id is the creation record's length plus one, so it counts allocations rather than
+      * live resources: a destroyed id is never reissued, and clearing `created` restarts the numbering
+      * at `1`.
+      */
+     create(): number;
+     /**
+      * Destroys a numbered resource.
+      *
+      * @param id - The resource id to destroy.
+      * @remarks It records the id and nothing else: it frees nothing, refuses nothing, and accepts an
+      * id that was never created, so a suite asserts on the record rather than on a refusal.
+      */
+     destroy(id: number): void;
+ }
+
+ /** Configures a bounded retry, adding an optional producer-call limit to a bounded wait's bounds. */
+ export declare interface RetryOptions extends WaitOptions {
+     /** Caps the number of producer calls. When omitted, only the time budget bounds the retry. */
+     readonly attempts?: number;
+ }
+
+ /**
+  * Repeats a producer until one produced value satisfies a predicate.
+  *
+  * @typeParam T - The produced value type.
+  * @param description - The operation described in an exhaustion error.
+  * @param produce - The synchronous or asynchronous operation to repeat.
+  * @param satisfied - The predicate that accepts a produced value.
+  * @param options - The time, attempt, and abort bounds.
+  * @returns The first produced value the predicate accepts.
+  * @throws The predicate's thrown value, the abort reason, or an `Error` when a bound is invalid or
+  * the retry exhausts its budget or attempts.
+  * @remarks A producer throw counts as an unsatisfied attempt. The last producer error becomes the
+  * exhaustion error's `cause`. Default budget: `1000` milliseconds. Default interval: `10`
+  * milliseconds.
+  */
+ export declare function retryUntil<T>(description: string, produce: () => T | Promise<T>, satisfied: (value: T) => boolean, options?: RetryOptions): Promise<T>;
+
+ /**
+  * Copies a JSON value through serialization and parsing.
+  *
+  * @typeParam T - The copied value's type, which the copy keeps.
+  * @param value - The value to copy, bounded by its own `JSONSafe` projection.
+  * @returns The parsed JSON copy.
+  * @remarks Non-finite numbers throw because JSON would replace them with `null`. Negative zero is
+  * normalized to zero by JSON serialization. The bound intersects `JSONSafe<T>` rather than
+  * constraining `T` to `JSONValue`, so an interface-typed value round-trips.
+  */
+ export declare function roundTripJSON<T>(value: T & JSONSafe<T>): T;
+
+ /** Holds a real abort signal and controller instrumented with its live abort-listener tally. */
+ export declare interface SignalInterface {
+     /** Holds the controller that owns the signal. */
+     readonly controller: AbortController;
+     /** Holds the signal to hand to the code under test. */
+     readonly signal: AbortSignal;
+     /** Reports the live abort-listener tally. */
+     readonly count: number;
+ }
+
+ /**
+  * Represents one abort listener an instrumented signal installed, as its tally holds it.
+  *
+  * @remarks The members are the listener the caller supplied, the listener installed in its place,
+  * the capture flag the pair was registered under, and the controller that removes the scope
+  * subscription installed beside it, which is `undefined` where no other signal scopes the
+  * registration.
+  */
+ export declare type SignalRegistration = readonly [
+ listener: EventListener | EventListenerObject,
+ installed: EventListener | EventListenerObject,
+ capture: boolean,
+ cleanup: AbortController | undefined
+ ];
+
+ /**
+  * Names the attributes a statechart harness publishes, keyed by the fact each one carries.
+  *
+  * @remarks
+  * A harness renders its own table and a gate outside the page polls the rendered markup, so these
+  * names are the whole contract between the two. `status`, `passed`, `failed`, and `total` belong on
+  * the harness root, because a gate finds the harness by `status` and reads the tally from the same
+  * element. `scenario` and `result` belong on each row, so a failing row is found by `result` and
+  * named by `scenario`. `state` belongs on the element rendering the entity's current state.
+  *
+  * The values are the attribute names themselves, so a harness writes `setAttribute` against this map
+  * and a gate writes `querySelector` against it, and neither spells a `data-statechart-*` string of
+  * its own. `createHarness` in the browser environment is the harness this package publishes, and it
+  * writes every one of these names from here.
+  *
+  * @example
+  * ```ts
+  * harness.getAttribute(STATECHART_ATTRIBUTES.status) // 'passed'
+  * ```
+  */
+ export declare const STATECHART_ATTRIBUTES: Readonly<{
+     status: "data-statechart-status";
+     passed: "data-statechart-passed";
+     failed: "data-statechart-failed";
+     total: "data-statechart-total";
+     scenario: "data-statechart-scenario";
+     result: "data-statechart-result";
+     state: "data-statechart-state";
+ }>;
+
+ /**
+  * Lists every value a statechart harness reports through its `status` attribute.
+  *
+  * @remarks
+  * `pending` is what a harness carries while its inventory is incomplete: written at construction
+  * and replaced as soon as every declared row has rendered its `scenario` element and the root
+  * carries the row count. A gate that finds it has found a harness whose rows never mounted. `idle`
+  * is a mounted harness standing ready, its tally at zero and nothing running. `running` is a run in
+  * flight. `passed` and `failed` are the two terminal readings, so a gate waits for membership in
+  * that pair rather than for a fixed duration. An exceptional exit is terminal too: a harness whose
+  * `state` reader throws writes `failed` and then rejects the run, so the gate reads a terminal pair
+  * while the suite reads the throw.
+  *
+  * The tuple's order is the order a run passes through, and `StatechartStatus` is the same set as a
+  * named union, so a harness and its gate share one vocabulary whichever form each of them needs.
+  *
+  * @example
+  * ```ts
+  * const terminal = new Set<StatechartStatus>(['passed', 'failed'])
+  * terminal.has('running') // false
+  * ```
+  */
+ export declare const STATECHART_STATUSES: readonly ["pending", "idle", "running", "passed", "failed"];
+
+ /**
+  * Names the run state a statechart harness publishes through its status attribute.
+  *
+  * @remarks
+  * Each arm is observable from the harness root alone, which is what lets a gate outside the page
+  * decide from the markup rather than from anything the harness tells it. `pending` is a harness
+  * whose inventory is incomplete: it is written at construction and replaced as soon as every
+  * declared row has rendered and the root carries the row count, so a gate that reads it has found a
+  * harness whose rows never mounted. `idle` is a mounted harness standing ready with nothing
+  * running. `running` is a run in flight. `passed` and `failed` are the two terminal readings, so a
+  * gate waits for membership in that pair rather than for a fixed duration. An exceptional exit is
+  * terminal too: a harness whose `state` reader throws writes `failed` and then rejects the run, so
+  * the gate reads a terminal pair while the suite reads the throw.
+  *
+  * `STATECHART_STATUSES` lists the same arms in the order a run passes through them, so a gate that
+  * needs the values at runtime reads them from there rather than respelling the union.
+  */
+ export declare type StatechartStatus = 'pending' | 'idle' | 'running' | 'passed' | 'failed';
+
+ /**
+  * Drives one {@link StateTransition} through the three phases that prove it.
+  *
+  * @typeParam TState - The states the entity moves between, as a string-literal union.
+  * @typeParam TEvent - The events the entity accepts, as a string-literal union.
+  * @typeParam TContext - The fixture the three phases drive.
+  * @remarks Each phase receives the context and the part of the transition it is responsible for, so
+  * a phase reads its subject from its own parameters rather than from the row it belongs to. A phase
+  * may be synchronous or asynchronous, and `executeScenario` awaits each one before starting the
+  * next.
+  */
+ export declare interface StateScenario<TState extends string, TEvent extends string, TContext> {
+     /** Holds the row this scenario drives. */
+     readonly transition: StateTransition<TState, TEvent>;
+     /**
+      * Puts the entity into the transition's `from` state.
+      *
+      * @param context - The fixture this row drives.
+      * @param state - The transition's `from` state.
+      */
+     arrange(context: TContext, state: TState): Promise<void> | void;
+     /**
+      * Applies the transition's event to the arranged entity.
+      *
+      * @param context - The fixture this row drives.
+      * @param event - The transition's event.
+      */
+     act(context: TContext, event: TEvent): Promise<void> | void;
+     /**
+      * Checks that the entity reached the transition's `to` state.
+      *
+      * @param context - The fixture this row drives.
+      * @param state - The transition's `to` state.
+      * @remarks Whatever it throws is renamed with the row's name and rethrown.
+      */
+     assert(context: TContext, state: TState): Promise<void> | void;
+ }
+
+ /**
+  * Represents one row of a statechart table: the entity's state before an event, the event, and the
+  * state that event must leave it in.
+  *
+  * @typeParam TState - The states the entity moves between, as a string-literal union.
+  * @typeParam TEvent - The events the entity accepts, as a string-literal union.
+  * @remarks The two unions are the entity's own vocabulary, so a table naming a state or an event the
+  * entity does not have fails to typecheck rather than failing at runtime.
+  */
+ export declare interface StateTransition<TState extends string, TEvent extends string> {
+     /** Holds the row's name, which is prepended to the message of whatever the row throws. */
+     readonly name: string;
+     /** Holds the state the row arranges before it acts. */
+     readonly from: TState;
+     /** Holds the event the row applies to the arranged entity. */
+     readonly event: TEvent;
+     /** Holds the state the row asserts the entity reached. */
+     readonly to: TState;
+ }
+
+ /** Represents the work one teardown entry performs when the list is destroyed. */
+ export declare type TeardownHandler = () => void | Promise<void>;
+
+ /** Represents the cleanup a test adds as it goes and runs once, newest first, when it is done. */
+ export declare interface TeardownInterface {
+     /** Reports how many handlers are registered. */
+     readonly count: number;
+     /**
+      * Registers a handler to run when the list is destroyed.
+      *
+      * @param handler - The work to perform.
+      * @remarks Registration order is what `destroy` reverses, so the newest registration is undone
+      * first.
+      */
+     add(handler: TeardownHandler): void;
+     /**
+      * Runs every registered handler in reverse registration order, awaiting each in turn, and empties
+      * the list.
+      *
+      * @throws The value the failed handler threw, by identity, when exactly one handler failed. An
+      * `AggregateError` carrying every thrown value in run order, when several did.
+      * @remarks Every handler runs, including after an earlier one throws or rejects. A handler
+      * registered while the run is in progress stays registered for the next call rather than joining
+      * this one. The snapshot it ran is discarded, so a repeated call runs nothing that already ran.
+      */
+     destroy(): Promise<void>;
+ }
+
+ /**
+  * Configures a bounded wait over a reading of text.
+  *
+  * @remarks
+  * The two members are the arrival a wait is for and the departure it must see first. A screen that
+  * replaces one sentence with another passes through a moment carrying both, so a wait that names
+  * only the arrival can resolve on the frame the old sentence is still painted in. Name the
+  * replaced sentence in `absent` and the wait resolves on the reading that carries one and not the
+  * other.
+  */
+ export declare interface TextWaitOptions extends WaitOptions {
+     /** Determines whether the reading must equal the text rather than contain it. */
+     readonly exact?: boolean;
+     /** Holds a sentence the reading must no longer carry when the wait resolves. */
+     readonly absent?: string;
+ }
+
+ /**
+  * Waits until an abort signal is aborted.
+  *
+  * @param signal - The signal to observe.
+  * @returns A promise that resolves when the signal is aborted.
+  * @remarks An already-aborted signal resolves immediately. Otherwise the wait parks on a one-shot
+  * abort listener without a timer or polling.
+  */
+ export declare function waitForAbort(signal: AbortSignal): Promise<void>;
+
+ /**
+  * Waits until a condition holds within an elapsed-time budget.
+  *
+  * @param description - The condition described in a timeout error.
+  * @param condition - The synchronous or asynchronous condition to read.
+  * @param options - The time bounds and abort signal.
+  * @returns A promise that resolves when the condition first returns `true`.
+  * @throws The condition's thrown value, the abort reason, or an `Error` when a bound is invalid or
+  * the condition does not hold within the budget.
+  * @remarks The first read is immediate. Default budget: `1000` milliseconds. Default interval: `10`
+  * milliseconds.
+  */
+ export declare function waitForCondition(description: string, condition: () => boolean | Promise<boolean>, options?: WaitOptions): Promise<void>;
+
+ /**
+  * Waits for a host timer to elapse.
+  *
+  * @param ms - The delay in milliseconds. Default: `0`.
+  * @returns A promise that resolves after the timer fires.
+  */
+ export declare function waitForDelay(ms?: number): Promise<void>;
+
+ /**
+  * Waits for the first delivery from an event subscription.
+  *
+  * @typeParam TArgs - The delivered argument tuple.
+  * @param subscribe - The function that installs the event listener and may return its cleanup.
+  * @param description - The event described in a timeout error.
+  * @param options - The time bounds and abort signal.
+  * @returns The first delivered argument tuple.
+  * @throws The subscription's thrown value, the abort reason, or an `Error` when a bound is invalid
+  * or the event is not delivered within the budget.
+  * @remarks Default budget: `1000` milliseconds. The interval is validated for consistency with the
+  * wait family but is not used because this helper parks on the event.
+  */
+ export declare function waitForEvent<TArgs extends readonly unknown[]>(subscribe: EventSubscriber<TArgs>, description: string, options?: WaitOptions): Promise<TArgs>;
+
+ /**
+  * Waits until a reading of text carries an expected sentence.
+  *
+  * @param description - The wait described in a timeout error.
+  * @param read - The synchronous reading to take, such as the text of one named region.
+  * @param text - The sentence the reading must carry.
+  * @param options - The time bounds, the abort signal, the exactness switch, and the departure.
+  * @returns The first reading that satisfies the expectation.
+  * @throws The reader's thrown value, the abort reason, or an `Error` when `text` or `absent` is
+  * empty, `text` carries `absent`, a bound is invalid, or the expectation is not met within the
+  * budget.
+  * @remarks
+  * The reading is a parameter rather than a target this resolves, so the same wait serves a whole
+  * page, one named region, and a value a host-independent test computes. Scope it as narrowly as the
+  * claim: a wait over the whole page resolves on the sentence wherever it lands.
+  *
+  * {@link waitForCondition} owns the poll, so the bounds, the timeout voice, and the abort reason are
+  * that helper's, and a reader that throws stops the wait rather than counting as a reading that did
+  * not satisfy it. Default budget: `1000` milliseconds. Default interval: `10` milliseconds.
+  *
+  * An empty expectation is refused rather than satisfied by the first reading, because every string
+  * contains the empty string and every reading equals it only when the screen is blank.
+  *
+  * A departure the expectation itself carries is refused the same way, before any reading. A reading
+  * that satisfies the arrival carries the departure too — under `exact` it equals `text` and without
+  * it contains `text` — so no reading can ever satisfy the poll and the wait would spend its whole
+  * budget on a contradiction in the call.
+  *
+  * @example
+  * ```ts
+  * import { waitForText } from '@orkestrel/test'
+  *
+  * await waitForText('the ledger arrives', () => panel.innerText, 'Two entries')
+  *
+  * // Throws Error: Text expectation must not be empty
+  * await waitForText('anything', () => panel.innerText, '')
+  *
+  * // Throws Error: Text departure must not appear in the text expectation
+  * await waitForText('anything', () => panel.innerText, 'Two entries', { absent: 'entries' })
+  * ```
+  */
+ export declare function waitForText(description: string, read: () => string, text: string, options?: TextWaitOptions): Promise<string>;
+
+ /**
+  * Configures a bounded asynchronous wait with an elapsed-time limit, a delay between readings, and
+  * an abort signal.
+  *
+  * @remarks
+  * A default belongs to the function that reads these bounds rather than to the shape, because the
+  * consumers do not agree on one. Each states its own numbers in its `@remarks`.
+  */
+ export declare interface WaitOptions {
+     /** Holds the elapsed-time limit in milliseconds. */
+     readonly budget?: number;
+     /** Holds the delay between readings in milliseconds. */
+     readonly interval?: number;
+     /** Holds the signal that aborts the wait. */
+     readonly signal?: AbortSignal;
+ }
+
+ export { }