@orkestrel/test 0.0.16 → 0.0.18

package/dist/src/browser/index.d.ts

@@ -23,6 +23,11 @@
  * @packageDocumentation
  */
 
+import type { JourneyVariant } from '@orkestrel/test';
+import type { StatechartStatus } from '@orkestrel/test';
+import type { StateScenario } from '@orkestrel/test';
+import type { WaitOptions } from '@orkestrel/test';
+
 /**
  * Names the interactive ARIA roles a bare accessible name is searched across.
  *
@@ -69,6 +74,117 @@ export declare function blendColor(front: Color, back: Color): Color;
  */
 export declare function build<K extends keyof HTMLElementTagNameMap>(tag: K, options?: ElementOptions): HTMLElementTagNameMap[K];
 
+/**
+ * Builds detached markup carrying one undeclared class token on HTML and another on SVG.
+ *
+ * @returns The detached root, the token the HTML element carries, and the one the SVG carries.
+ *
+ * @remarks
+ * The SVG element is the trap a census has to survive: `className` on an SVG element is an
+ * `SVGAnimatedString` rather than a string, so a reader splitting that value finds nothing and
+ * reports one undeclared token where two are carried. {@link readCensus} reads every element
+ * through `classList`, and this is the control that proves it.
+ *
+ * The two tokens are returned rather than written into a caller's expectation, so a cascade that
+ * later declares one of these names moves the fixture and the assertion together. Each token also
+ * carries a suffix drawn per call from `crypto.getRandomValues`, so a consumer cascade cannot
+ * declare either of them in advance and two controls in one document never share a token.
+ * `getRandomValues` rather than `randomUUID`, because that one answers outside a secure context
+ * too, and a browser project served from a remote host is not one.
+ *
+ * @example
+ * ```ts
+ * const control = buildCensus()
+ * readCensus(control.root).undeclared // [control.mark, control.token], sorted
+ * ```
+ */
+export declare function buildCensus(): CensusFixture;
+
+/**
+ * Builds a detached translucent stack whose composited and flat contrast readings straddle one bar.
+ *
+ * @param bar - The contrast ratio `refused` and `accepted` must sit on opposite sides of.
+ * @returns The opaque root carrying the tint, and the refused and accepted foregrounds under it.
+ * @throws An `Error` when no grey foreground puts the two readings on opposite sides of the bar.
+ *
+ * @remarks
+ * A contrast instrument that never composites still clears every fixture painting its own opaque
+ * background, so this is the control that makes {@link readContrast}'s ancestor walk and alpha
+ * blend the thing under test. The stack is an opaque floor, a translucent tint over it, and two
+ * grey foregrounds inside the tint. `refused` reads under the bar composited and at or over it
+ * flat, and `accepted` reads the other way about, so no single non-compositing reading satisfies
+ * both.
+ *
+ * The greys are searched rather than written down, so the control follows the bar it was asked for.
+ * A bar at or under `1` is refused because every contrast ratio reaches `1`, and a bar above what
+ * the tinted surface can reach is refused because no foreground clears it — each refusal names the
+ * bar rather than returning a stack that proves nothing.
+ *
+ * The nodes are detached, so nothing is mounted for you. Append `root` to the surface you are
+ * reading, take both readings, and remove it: a computed color needs the document, and a fixture
+ * left behind is the next test's resolver ambiguity.
+ *
+ * @example
+ * ```ts
+ * const control = buildContrast(4.5)
+ * mount(control.root)
+ * readContrast(control.refused) < 4.5 // true
+ * readContrast(control.accepted) >= 4.5 // true
+ * control.root.remove()
+ * ```
+ */
+export declare function buildContrast(bar: number): ContrastFixture;
+
+/**
+ * Builds the refusal a host withholding a storage operation raises.
+ *
+ * @param operation - The withheld operation, named as the `Storage` interface names it.
+ * @param key - The storage key the operation addressed. Omit it for an operation that takes none.
+ * @returns The refusal, unthrown.
+ *
+ * @remarks
+ * A browser with site data blocked, a sandboxed frame, and a hardened privacy mode all raise a
+ * `DOMException` named `SecurityError` from the storage object rather than answering, so this is
+ * the voice rather than a message of this package's. {@link createStorage} raises it from every
+ * operation the permission withholds; it is exported because a fixture implementing `Storage` some
+ * other way needs the same voice rather than a second spelling of it.
+ *
+ * @example
+ * ```ts
+ * buildDenial('getItem', 'theme').message // 'Access is denied for getItem "theme"'
+ * buildDenial('length').name // 'SecurityError'
+ * ```
+ */
+export declare function buildDenial(operation: string, key?: string): DOMException;
+
+/**
+ * Builds detached markup carrying one style escape of each kind, plus the sheet a project allows.
+ *
+ * @param permitted - The `id` the caller's reading exempts, placed on the third element.
+ * @returns The detached root, the inline escape, the embedded escape, and the exempt sheet.
+ *
+ * @remarks
+ * {@link extractStyles} has two branches — an inline `style` attribute and a `<style>` element —
+ * and a reading fed only the first never exercises the second. The exempt sheet is the other half
+ * of the control: a project that allows one standalone stylesheet writes an exemption for its id,
+ * and a reading that passes by refusing every `<style>` element clears the two escapes and fails
+ * that exemption.
+ *
+ * The declaration `inline`, `embedded`, and `permitted` carry is this package's, so assert on which
+ * elements are reported rather than on what they declare.
+ *
+ * The nodes are detached and stay that way: `extractStyles` takes any `ParentNode`, so the reading
+ * runs without mounting, and an embedded sheet that reached the document would join the cascade
+ * every other reading measures against.
+ *
+ * @example
+ * ```ts
+ * const control = buildEscapes('project-stylesheet')
+ * extractStyles(control.root).length // 3 — the inline escape, the embedded sheet, and the exempt one
+ * ```
+ */
+export declare function buildEscapes(permitted: string): EscapeFixture;
+
 /**
  * Names the color a browser paints an unstyled document with: opaque white.
  *
@@ -169,14 +285,16 @@ export declare const CAPTURE_STAGINGS = 4;
  */
 export declare function captureFrame(options: FrameOptions): Promise<string>;
 
-/** Represents one theme-and-viewport pair a capture run renders, and the document change it needs first. */
-export declare interface CaptureVariant {
-    /** Holds the variant's name, which is the second half of every filename the run writes. */
-    readonly name: string;
-    /** Holds the viewport width in pixels. */
-    readonly width: number;
-    /** Holds the viewport height in pixels. */
-    readonly height: number;
+/**
+ * Adds to a journey variant the document change a capture run applies before resizing.
+ *
+ * @remarks
+ * The name, the width, and the height come from {@link JourneyVariant}, which a project
+ * configuration can serialize and hand to the suite that renders it. The change this adds is a
+ * function, so it belongs to the suite rather than to that configuration: a variant a configuration
+ * declares and a variant a capture run renders are the same row read at two depths.
+ */
+export declare interface CaptureVariant extends JourneyVariant {
     /**
      * Holds the document change this variant needs before the viewport is resized — a theme
      * attribute, a density class, a language direction. Omit it when the variant is a viewport alone.
@@ -184,6 +302,41 @@ export declare interface CaptureVariant {
     readonly apply?: () => void;
 }
 
+/**
+ * Holds detached markup an authored-class census must report as undeclared.
+ *
+ * @remarks
+ * One token rides on an HTML element and the other on an SVG element, because `className` on an SVG
+ * element is an `SVGAnimatedString` rather than a string: a census splitting that value finds
+ * nothing and reports one token where two are carried.
+ */
+export declare interface CensusFixture {
+    /** Holds the detached root carrying both marked elements. */
+    readonly root: HTMLElement;
+    /** Holds the class token the HTML element carries. */
+    readonly token: string;
+    /** Holds the class token the SVG element carries. */
+    readonly mark: string;
+}
+
+/**
+ * Reports an authored-class census: the population walked, the tokens found, and the undeclared.
+ *
+ * @remarks
+ * The population is reported beside the finding because an empty walk satisfies every difference
+ * check: a census that read no element reports no undeclared token, and so does a census over
+ * markup whose every class the cascade declares. Assert on `elements` as well as on `undeclared`
+ * and the two cannot be confused.
+ */
+export declare interface CensusReading {
+    /** Reports how many elements the walk read, the root included when it is an element. */
+    readonly elements: number;
+    /** Lists every class token the markup carries, sorted. */
+    readonly tokens: readonly string[];
+    /** Lists every carried token no loaded stylesheet declares, sorted. */
+    readonly undeclared: readonly string[];
+}
+
 /**
  * Clears both browser storage surfaces.
  *
@@ -335,6 +488,24 @@ export declare function computeNamePattern(name: string): RegExp;
  */
 export declare const CONTENT_ROLES: readonly string[];
 
+/**
+ * Holds a detached translucent stack whose flat and composited readings disagree across one bar.
+ *
+ * @remarks
+ * `refused` and `accepted` are the control a composited-contrast reading owes: the composited
+ * reading refuses one and the flat reading clears it, and the other way about for the second. A reader that takes the
+ * nearest declared background at full strength answers the opposite pair, so no single
+ * non-compositing reading satisfies both.
+ */
+export declare interface ContrastFixture {
+    /** Holds the opaque floor carrying the translucent tint; append this to read either foreground. */
+    readonly root: HTMLElement;
+    /** Holds the foreground whose composited reading falls under the bar. */
+    readonly refused: HTMLElement;
+    /** Holds the foreground whose composited reading reaches the bar. */
+    readonly accepted: HTMLElement;
+}
+
 /**
  * Creates one console channel that records every call it receives and hands that call on unchanged.
  *
@@ -389,6 +560,59 @@ export declare function createChannel(name: string, output: string[], forward: (
  */
 export declare function createDragEvent(name: string, options?: DragEventInit): DragEvent;
 
+/**
+ * Creates a mounted statechart harness that renders one transition table and drives it row by row.
+ *
+ * @typeParam TState - The states the entity moves between.
+ * @typeParam TEvent - The events the entity accepts.
+ * @typeParam TContext - The fixture each row drives.
+ * @param options - The table, the fixture builder, the state reader, and the delay between rows.
+ * @returns The mounted harness, standing idle with its tally at zero.
+ * @throws An `Error` reading `Statechart harness mounted no transition` for an empty table, before
+ * anything reaches the document.
+ *
+ * @remarks
+ * A page cannot import this package, because the browser entry imports `vitest/browser` at module
+ * scope. So the harness is test-side: the suite mounts it, a gate outside the page polls the
+ * markup it renders, and `STATECHART_ATTRIBUTES` is the whole contract between the two. Nothing
+ * here spells a `data-statechart-*` string of its own, and neither does a gate. That gate has no
+ * rejection channel, so every exit writes a terminal status: a run that completes writes `passed` or
+ * `failed`, and a run that a `state` reader or a non-`Error` phase throw ends writes `failed` and
+ * then rejects with that value by identity, without counting the row as failed.
+ *
+ * The markup is framework-free. The root carries `status` and the tally; a `role="status"`
+ * announcer narrates each step in a sentence; one element carries `state` and renders what the
+ * entity's own reader reports; and an ordered list carries one row per scenario, each labelled with
+ * its `from`, its `event`, and its `to` and marked with the transition's name. The `state` element
+ * mounts empty and takes its attribute from the first row that produces a context, because a state
+ * is read from an entity and no entity exists until a row builds one.
+ *
+ * Construction writes `pending`, mounts the root, renders every row, then writes the row count and
+ * `idle` — so a gate that reads `pending` has found a harness whose rows never mounted, and the
+ * order is observable from outside through the mutations the document records.
+ *
+ * `execute` clears every rendered result and the rendered state, writes `running`, and drives each
+ * row in order through {@link executeScenario} against a context of that row's own. It continues
+ * past a failing row, so one run reports on the whole table rather than stopping at the first
+ * finding, and a builder that throws counts as its row failing under {@link buildRefusal}'s
+ * sentence, which is the one `executeScenarios` raises. What decides whether a row's phases run is
+ * whether its builder returned, not what it returned, so a table whose context is `undefined` drives
+ * every phase. A second `execute` runs the same table from a fresh tally and a cleared state.
+ *
+ * Every reading comes off the markup, so the object and the page cannot disagree, and `failures` is
+ * the `scenario` name of each row whose rendered `result` reads `failed` rather than a second list
+ * beside them.
+ *
+ * @example
+ * ```ts
+ * const harness = createHarness({ scenarios: SCENARIOS, build: buildDisclosure, state: readState })
+ * await harness.execute()
+ * harness.status // 'passed'
+ * harness.destroy()
+ * ```
+ */
+export declare function createHarness<TState extends string, TEvent extends string, TContext>(options: HarnessOptions<TState, TEvent, TContext>): HarnessInterface;
+
 /**
  * Creates the journal one scenario records its steps and the page's own output into.
  *
@@ -470,6 +694,50 @@ export declare function createPointerEvent(name: string, options?: PointerEventI
  */
 export declare function createPortfolio(options: PortfolioOptions): PortfolioInterface;
 
+/**
+ * Creates an inert `Storage` a host can withhold, grant, and run out of room in.
+ *
+ * @param options - The seed, the read and write permissions, and the quota.
+ * @returns A store carrying the Web Storage surface plus the grant.
+ * @throws An `Error` when `quota` is not a non-negative safe integer. A quota above
+ * `Number.MAX_SAFE_INTEGER` carries the same sentence, because a counter that cannot decrement past
+ * that point bounds nothing.
+ *
+ * @remarks
+ * Conditions a real origin produces are unreachable from a test otherwise: a browser with
+ * site data blocked refuses every operation the permission withholds, an origin with no room left
+ * refuses `setItem`, and a person allowing site data grants what was withheld. This makes each of
+ * them reachable against a real `Storage` surface rather than a shaped object.
+ *
+ * The store answers through its methods and intercepts no named-property access, so drive a
+ * consumer under test through `getItem` and `setItem`. `Storage` declares an index signature, so
+ * `store.theme` typechecks and reads `undefined` while `getItem('theme')` answers, and a property
+ * write lands on the object rather than in the store, consuming no quota and meeting no refusal.
+ *
+ * It is backed by a map of its own and patches nothing: `localStorage` and `sessionStorage` are
+ * untouched, no `storage` event is dispatched, and the store is reached only by the code the test
+ * hands it to. Reach for {@link clearStorage} where the real browser surfaces are the subject.
+ *
+ * `length`, `key`, and `getItem` are reads; `clear`, `removeItem`, and `setItem` are writes. A
+ * withheld operation raises {@link buildDenial}'s `SecurityError`, and `permit` lifts both
+ * permissions at once, the way a person allowing site data lifts them. Reads answer from what the
+ * store actually accepted, so a journey reads what the application kept while the host was refusing.
+ *
+ * `quota` counts accepted `setItem` calls rather than bytes, because the number of writes is what a
+ * journey scripts and a byte budget is the browser's own arithmetic. `removeItem` consumes none of
+ * it, and `permit` replenishes none of it: room and permission are different refusals, and a test
+ * that granted the permission still meets the full origin.
+ *
+ * @example
+ * ```ts
+ * const storage = createStorage({ values: { theme: 'dark' }, writes: false })
+ * storage.getItem('theme') // 'dark'
+ * storage.permit()
+ * storage.setItem('theme', 'light')
+ * ```
+ */
+export declare function createStorage(options?: StorageOptions): WebStorageInterface;
+
 /**
  * Describes the order sequential keyboard navigation visits one element's controls in.
  *
@@ -538,6 +806,25 @@ export declare interface ElementOptions {
     readonly attributes?: Readonly<Record<string, string>>;
 }
 
+/**
+ * Holds detached markup a style-escape reading must find, and the one it must leave alone.
+ *
+ * @remarks
+ * `inline`, `embedded`, and `permitted` are the branches a style-escape reading has: an inline
+ * attribute, an embedded element, and the sheet a project deliberately allows. A reading that passes
+ * by refusing every `<style>` element clears the escapes and fails the exemption.
+ */
+export declare interface EscapeFixture {
+    /** Holds the detached root carrying the inline escape, the embedded escape, and the exempt sheet. */
+    readonly root: HTMLElement;
+    /** Holds the element carrying an inline `style` attribute. */
+    readonly inline: HTMLElement;
+    /** Holds the embedded `<style>` element. */
+    readonly embedded: HTMLElement;
+    /** Holds the `<style>` element carrying the exempt id the caller named. */
+    readonly permitted: HTMLElement;
+}
+
 /**
  * Expands a capture registry across every variant into the filenames a complete portfolio holds.
  *
@@ -726,6 +1013,75 @@ export declare interface FrameReading {
     readonly floor: string | undefined;
 }
 
+/**
+ * Holds a mounted statechart harness, the tally it publishes, and the run it drives.
+ *
+ * @remarks
+ * Every reading comes off the mounted markup rather than out of a field beside it, so the object a
+ * test asserts on and the attributes a gate polls cannot disagree. `status`, `total`, `passed`, and
+ * `failed` read the root's own attributes, and `failures` reads the `scenario` name of every row
+ * whose `result` reads `failed`, so no second list can drift from the rows.
+ *
+ * `root` is the mounted element, handed out so a test can read the markup a gate would read.
+ * `failures` hands out a snapshot, so a list read mid-run stays what it was.
+ */
+export declare interface HarnessInterface {
+    /** Holds the mounted root carrying the status, the tally, and every row. */
+    readonly root: HTMLElement;
+    /** Reports the run state the root announces. */
+    readonly status: StatechartStatus;
+    /** Reports how many rows the table declares. */
+    readonly total: number;
+    /** Reports how many rows the last run finished with a passing result. */
+    readonly passed: number;
+    /** Reports how many rows the last run finished with a failing result. */
+    readonly failed: number;
+    /** Lists the name of every row whose rendered result reads failed, in table order. */
+    readonly failures: readonly string[];
+    /**
+     * Drives every row in table order, from a fresh tally and a cleared state.
+     *
+     * @returns A promise resolving after the last row settles and the terminal status is written.
+     * @throws The value a `state` reader or a non-`Error` phase threw, by identity, after the harness
+     * writes `failed`. Every exit is terminal, because the gate polling the markup has no rejection
+     * channel to read.
+     */
+    execute(): Promise<void>;
+    /** Removes the mounted root, and does nothing when it is already removed. */
+    destroy(): void;
+}
+
+/**
+ * Configures the harness that renders one transition table and drives it row by row.
+ *
+ * @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 of each row drive.
+ * @remarks
+ * `scenarios` is the table in the order it renders and the order it runs, so the rows a reader sees
+ * are the rows the run walks. `build` is called once per row, the way `executeScenarios` calls it,
+ * so one table can mix fixtures and a row never inherits the entity the row before it left behind.
+ *
+ * `state` is the reader that puts the entity's current state on the page. It is called with the
+ * row's own context after that row settles, pass or fail, so the rendered state is where the event
+ * actually left the entity rather than where the row expected it. It is a reader rather than a
+ * phase: a `state` that throws rejects the run after the harness writes `failed`, and the row it was
+ * reading is not counted as failed.
+ *
+ * `pause` holds a delay between rows, for a table whose entity is worth watching. Omit it and the
+ * rows run back to back.
+ */
+export declare interface HarnessOptions<TState extends string, TEvent extends string, TContext> {
+    /** Holds the table to render and drive, in the order it is written. */
+    readonly scenarios: ReadonlyArray<StateScenario<TState, TEvent, TContext>>;
+    /** Builds the fixture one row drives, called once per row and awaited when it returns a promise. */
+    readonly build: (scenario: StateScenario<TState, TEvent, TContext>) => TContext | Promise<TContext>;
+    /** Reads the state the entity is in, for the element the harness renders it on. */
+    readonly state: (context: TContext) => TState;
+    /** Holds the delay in milliseconds the harness waits between rows. */
+    readonly pause?: number;
+}
+
 /**
  * Names the role a `th` carries for the header axis its `scope` names.
  *
@@ -777,8 +1133,9 @@ export declare function isOutsideViewport(rectangle: DOMRectReadOnly): boolean;
  *
  * @param element - The element to judge.
  * @returns True if the element is connected, visible, laid out with a non-zero box, in the
- * sequential focus order, neither disabled nor marked `aria-disabled="true"`, and outside every
- * `[inert]` subtree; false otherwise.
+ * sequential focus order, neither disabled nor marked `aria-disabled="true"`, outside every
+ * `[inert]` subtree, and inside every shown `[aria-modal="true"]` element its document carries;
+ * false otherwise.
  *
  * @remarks
  * This is the one reachability filter the layer applies. `resolveRendered`, `clickAccessibleWithin`,
@@ -790,6 +1147,29 @@ export declare function isOutsideViewport(rectangle: DOMRectReadOnly): boolean;
  * refuses it. Nothing here asks about the viewport: `resolveAccessible` scrolls a wholly
  * off-viewport target into view and measures that separately with {@link isOutsideViewport}.
  *
+ * An open modal dialog takes the page behind it away, and the element's own facts cannot report
+ * that: the covered control stays connected, laid out, focusable, and outside every `[inert]`
+ * subtree while a pointer, a Tab, and a reader honouring `aria-modal` all stop at the dialog. So
+ * this asks the document for its `[aria-modal="true"]` elements, puts each through
+ * {@link isRendered}, and refuses the subject wherever a shown one does not contain it. A closed
+ * dialog is hidden and excludes nothing, which is why the visibility reading is the announced one
+ * rather than a bare `checkVisibility` call: a drawer parked at `visibility: hidden` is still laid
+ * out. Nesting needs no separate rule, because an element inside the innermost dialog sits inside
+ * every dialog around it.
+ *
+ * Containment follows the flat tree, so a subject inside a shadow tree is judged by its host chain
+ * as well as itself and a dialog holding the host holds its shadow content too. Two arrangements
+ * stay outside the read: a native `<dialog>` opened with `showModal` carries no `aria-modal`
+ * attribute, and a dialog declared inside a shadow tree is not in what a document query returns.
+ * Each leaves the page behind it reachable here.
+ *
+ * Inside a shadow tree it answers for the element's own facts, in an open root and a closed one
+ * alike: the box, the focus order, `:disabled`, and `aria-disabled` are all the element's. The
+ * `[inert]` ancestor is the one read that stops at the boundary, because `closest` never leaves the
+ * element's own tree, so a host marked `[inert]` is invisible here. What the flat tree decides still
+ * reaches the subject — a host the document does not lay out takes the element off the page and this
+ * refuses it. Ask the host separately where an ancestor attribute is the subject.
+ *
  * @example
  * ```ts
  * isReachable(requireValue(container.querySelector('button')))
@@ -816,6 +1196,13 @@ export declare function isReachable(element: Element): boolean;
  * for the box tree, and `visibility` inherits, so between them an ancestor cannot hide a control
  * from a reader and leave it standing in a description.
  *
+ * Inside a shadow tree it answers for the element's own facts, in an open root and a closed one
+ * alike. The `aria-hidden` ancestor is the one read that stops at the boundary, because `closest`
+ * never leaves the element's own tree, so a host marked `aria-hidden="true"` is invisible here and
+ * this reports `true` for a subject a reader is never told about. `checkVisibility` and the computed
+ * `visibility` read the flat tree, so a host the document does not lay out still takes the element
+ * off the page. Ask the host separately where an ancestor attribute is the subject.
+ *
  * @example
  * ```ts
  * isRendered(requireValue(container.querySelector('[aria-hidden="true"] button'))) // false
@@ -1094,6 +1481,32 @@ export declare interface PortfolioOptions {
     readonly enabled?: boolean;
 }
 
+/**
+ * Sends a key sequence to whatever holds focus, and refuses to send it to nothing.
+ *
+ * @param keys - The sequence in the provider's own key syntax, such as `{Enter}` or `{Escape}`.
+ * @returns A promise resolving after every keystroke completes.
+ * @throws When the document body holds focus, or nothing does.
+ *
+ * @remarks
+ * The refusal is the whole of what this adds over `userEvent.keyboard`. A key sent while focus sits
+ * on the body reaches no control, and every assertion after it reads the surface the key never
+ * touched — which is the false green a guarded keyboard step exists to catch. Bring focus about
+ * first through {@link traverseAccessible}, {@link clickAccessible}, or {@link typeAccessible}, and
+ * send the sequence here.
+ *
+ * Escaping is the caller's, because the sequence is the subject: `{` opens a key name and `[` opens
+ * a code name. Reach for {@link typeAccessible} where the text is the subject and the syntax is in
+ * the way.
+ *
+ * @example
+ * ```ts
+ * await traverseAccessible('Evaluate')
+ * await pressKeys('{Enter}')
+ * ```
+ */
+export declare function pressKeys(keys: string): Promise<void>;
+
 /**
  * Resolves the opaque color standing behind one element.
  *
@@ -1148,6 +1561,33 @@ export declare function readBackdrop(element: Element, floor: Color): Color;
  */
 export declare function readCascade(): ReadonlySet<string>;
 
+/**
+ * Takes the authored-class census of one subtree against the cascade this document loaded.
+ *
+ * @param root - The subtree to walk. A detached element and a `DocumentFragment` both work.
+ * @returns The population walked, every class token the markup carries, and every one of them no
+ * loaded stylesheet declares; both lists sorted.
+ * @throws An `Error` when the walk reads no element at all.
+ *
+ * @remarks
+ * This is {@link readClasses} differenced against {@link readCascade}, with the population reported
+ * beside the difference. The population is what makes the reading falsifiable: an empty walk
+ * reports no undeclared token, and so does a subtree whose every class the cascade declares, so a
+ * check reading `undeclared` alone passes for a census that read nothing. The empty walk is refused
+ * outright for the same reason.
+ *
+ * The root counts when it is an `Element`, so a `DocumentFragment` contributes its descendants
+ * alone. Both lists are sorted rather than left in sighting order, because a census is compared
+ * against a previous one or against an expected list, and document order is not a fact about the
+ * classes.
+ *
+ * @example
+ * ```ts
+ * readCensus(container).undeclared // ['lead'] — no loaded stylesheet declares it
+ * ```
+ */
+export declare function readCensus(root: ParentNode): CensusReading;
+
 /**
  * Collects every class token the markup under one root carries.
  *
@@ -1424,6 +1864,49 @@ export declare function readPerception(name: string): string;
  */
 export declare function readPixels(element: Element, property: string): number;
 
+/**
+ * Reads the refusal one named target answers with, or nothing when it resolves.
+ *
+ * @param name - The target's exact accessible name.
+ * @returns The refusal sentence {@link resolveRendered} raised, or `undefined` when it resolved.
+ * @throws Whatever the resolver threw that is not an `Error`.
+ *
+ * @example
+ * ```ts
+ * readRefusal('Save changes') // undefined — the control resolves
+ * readRefusal('Menu') // 'Interactive target "Menu" is not visible and focus-reachable'
+ * ```
+ */
+export declare function readRefusal(name: string): string | undefined;
+
+/**
+ * Reads the refusal one named target answers with under an exact role, or nothing when it resolves.
+ *
+ * @param role - The target's exact ARIA role.
+ * @param name - The target's exact accessible name.
+ * @returns The refusal sentence {@link resolveRendered} raised, or `undefined` when it resolved.
+ * @throws Whatever the resolver threw that is not an `Error`.
+ *
+ * @remarks
+ * Absent, present-but-gated, and ambiguous are different findings about an interface, and the
+ * layer keeps their sentences distinct, so a journey asserting on the one it means needs the
+ * sentence rather than a boolean. This fixes the resolver, translates the `unknown` a `catch` binds
+ * into `string | undefined`, and rethrows anything that is not an `Error` — a value no resolver
+ * raises, and one a caller reading a message would otherwise lose. `undefined` is rethrown with the
+ * rest: a resolver that returned and a hostile getter that threw `undefined` are different findings,
+ * which is why the `catch` is this function's own rather than a captured thrown value.
+ *
+ * It resolves rather than acts, so a target it reports `undefined` for is one an acting verb
+ * reaches. Assert on the exact sentence: a comparison against a substring passes for a refusal
+ * about a different condition.
+ *
+ * @example
+ * ```ts
+ * readRefusal('tab', 'Drafts') // undefined — the tab resolves under its role
+ * ```
+ */
+export declare function readRefusal(role: string, name: string): string | undefined;
+
 /**
  * Measures the contrast the focus chrome painted on one control reaches against its own backdrop.
  *
@@ -1868,6 +2351,42 @@ export declare function resolveRendered(first: string, second?: string): HTMLEle
  */
 export declare function stagePane(width: number, height: number): Promise<void>;
 
+/**
+ * Configures a bounded wait over the states a control announces.
+ *
+ * @remarks
+ * The direction is a boolean because a state is either announced or it is not, and both directions
+ * are the same wait over the same reading. The time bounds and the abort signal come from
+ * {@link WaitOptions} and mean there what they mean everywhere else.
+ */
+export declare interface StateOptions extends WaitOptions {
+    /** Determines the direction: `true` waits until the state is gone, `false` until it appears. */
+    readonly absent?: boolean;
+}
+
+/**
+ * Configures an inert `Storage`: its seed, which operations the host permits, and its quota.
+ *
+ * @remarks
+ * Every member describes a condition a real origin produces. A withheld read or write is what a
+ * browser with site data blocked raises from the storage object, and a quota is what an origin with
+ * no room left raises from `setItem`. Omit a member and the store behaves as an ordinary origin
+ * does: seeded with nothing, permitting everything, and bounded by nothing.
+ */
+export declare interface StorageOptions {
+    /** Holds the entries the store starts with, keyed by storage key. */
+    readonly values?: Readonly<Record<string, string>>;
+    /** Determines whether the host permits reads. Default: `true`. */
+    readonly reads?: boolean;
+    /** Determines whether the host permits writes. Default: `true`. */
+    readonly writes?: boolean;
+    /**
+     * Caps the accepted `setItem` calls, as a non-negative safe integer. When omitted, nothing bounds
+     * the store.
+     */
+    readonly quota?: number;
+}
+
 /**
  * Reaches a named control only through natural forward Tab traversal from the current focus.
  *
@@ -1925,6 +2444,43 @@ export declare function typeAccessible(name: string, text: string): Promise<void
  */
 export declare function typeInput(element: HTMLInputElement | HTMLTextAreaElement, text: string): void;
 
+/**
+ * Waits until every finite animation on one element and its subtree has stopped moving.
+ *
+ * @param element - The element whose own animations and descendants' animations to wait on.
+ * @param options - The time bounds and the abort signal.
+ * @returns A promise resolving once no finite animation is still running.
+ * @throws An `Error` when the element is not in a document, when a bound is invalid, or when an
+ * animation is still running at the budget; or the abort reason.
+ *
+ * @remarks
+ * A reading taken while paint is moving reports an interpolated frame — a `background-color` at a
+ * fraction of its alpha, a `color` part way between two values — that no state of the interface
+ * ever paints. This waits for the paint a person sees, whichever state it settles in.
+ *
+ * It parks on each animation's own `finished` promise rather than re-reading on a timer, and reads
+ * the list again after each completion or cancellation, so an animation a finishing one starts is
+ * waited on too.
+ *
+ * Some animations are left out, and each exclusion is a decision rather than an oversight. An animation
+ * whose effect declares infinite iterations never finishes, so a spinner that runs forever is a
+ * finding about the reading rather than a wait to lengthen. A finished animation filling its target
+ * stays in the list a browser reports and is already at rest. A paused animation is at rest too,
+ * and nothing here resumes it.
+ *
+ * The bounds are the wait family's, validated the same way. Default budget: `1000` milliseconds.
+ * The interval is validated for consistency with the family and is not used, because this parks on
+ * the animations. A detached element is refused rather than reported settled, because an element in
+ * no document runs no animation and would answer `true` to every wait.
+ *
+ * @example
+ * ```ts
+ * await clickAccessible('Dark')
+ * await waitForAnimations(document.body)
+ * ```
+ */
+export declare function waitForAnimations(element: Element, options?: WaitOptions): Promise<void>;
+
 /**
  * Waits for one animation frame to settle pending browser paint work.
  *
@@ -1937,4 +2493,75 @@ export declare function typeInput(element: HTMLInputElement | HTMLTextAreaElemen
  */
 export declare function waitForFrame(): Promise<void>;
 
+/**
+ * Waits until one named control announces a state, or stops announcing it.
+ *
+ * @param name - The control's exact accessible name.
+ * @param state - The state, spelled as {@link readStates} reports it.
+ * @param options - The time bounds, the abort signal, and the direction.
+ * @returns The states the control announced when the wait resolved.
+ * @throws The resolver's own refusal, the abort reason, or an `Error` when a bound is invalid or
+ * the state is not reached within the budget.
+ *
+ * @example
+ * ```ts
+ * await clickAccessible('Pin note')
+ * await waitForState('Pin note', 'pressed=true')
+ * ```
+ */
+export declare function waitForState(name: string, state: string, options?: StateOptions): Promise<readonly string[]>;
+
+/**
+ * Waits until one control of an exact role announces a state, or stops announcing it.
+ *
+ * @param role - The control's exact ARIA role.
+ * @param name - The control's exact accessible name.
+ * @param state - The state, spelled as {@link readStates} reports it.
+ * @param options - The time bounds, the abort signal, and the direction.
+ * @returns The states the control announced when the wait resolved.
+ * @throws The resolver's own refusal, the abort reason, or an `Error` when a bound is invalid or
+ * the state is not reached within the budget.
+ *
+ * @remarks
+ * The control is resolved afresh on every reading, because a framework replaces the node between
+ * one render and the next: the subject is the role and the name, never one element. That also means
+ * the resolver's own voices reach the caller unchanged — a control that leaves the document
+ * mid-wait refuses as absent rather than timing out as unannounced, which is the more useful
+ * finding.
+ *
+ * {@link waitForCondition} owns the poll, so the bounds and the abort reason are that helper's.
+ * Default budget: `1000` milliseconds. Default interval: `10` milliseconds. The exhaustion message
+ * names the control and the state, and carries the last states read, so a wait that ran out says
+ * what the control was announcing instead.
+ *
+ * This is the published replacement for a settle keyed to a framework's own class names. Where a
+ * surface announces nothing, the finding is the surface's: give the control its `aria-expanded`,
+ * `aria-pressed`, or `aria-busy` rather than reading the classes a stylesheet happens to use.
+ *
+ * @example
+ * ```ts
+ * await clickDisclosure('Advanced')
+ * await waitForState('button', 'Advanced', 'collapsed', { absent: true })
+ * ```
+ */
+export declare function waitForState(role: string, name: string, state: string, options?: StateOptions): Promise<readonly string[]>;
+
+/**
+ * Holds a store the host can withhold and later grant.
+ *
+ * @remarks
+ * The name carries `Web` because `@orkestrel/database` owns `StorageInterface` for the operations a
+ * driver's transaction scope offers, and the fleet gives one bare exported name one owning package.
+ * This one is the Web Storage surface a browser publishes on `localStorage`, plus the grant a
+ * person allowing site data performs.
+ *
+ * `Storage` declares an index signature, so `store.theme` typechecks against this type. A store
+ * `createStorage` returns answers through its methods alone and intercepts no named-property
+ * access, so drive a consumer under test through `getItem` and `setItem`.
+ */
+export declare interface WebStorageInterface extends Storage {
+    /** Grants the reads and the writes the host withheld, and replenishes no quota. */
+    permit(): void;
+}
+
 export { }