@orkestrel/test 0.0.7 → 0.0.8

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

@@ -8,6 +8,67 @@
  */
 export declare const ACCESSIBLE_ROLES: readonly string[];
 
+/**
+ * Composites one color over another.
+ *
+ * @param front - The color painted on top.
+ * @param back - The color already on the surface.
+ * @returns The opaque result a reader sees, its alpha always `1`.
+ *
+ * @example
+ * ```ts
+ * blendColor([255, 255, 255, 0.5], [0, 0, 0, 1]) // [127.5, 127.5, 127.5, 1]
+ * ```
+ */
+export declare function blendColor(front: Color, back: Color): Color;
+
+/**
+ * The page a browser paints an unstyled document onto.
+ *
+ * @remarks
+ * This is the floor a backdrop walk ends on wherever the caller wants the browser's own canvas
+ * assumed. `readBackdrop` takes its floor as an argument rather than reaching for this one, so a
+ * measurement over a surface the canvas never shows through names the color it actually sits on.
+ */
+export declare const CANVAS_COLOR: Color;
+
+/**
+ * The attribute marking the runner's tester pane, and the rule that sizes it, while a frame is
+ * staged.
+ *
+ * @remarks
+ * `stagePane` writes it onto the pane and onto the stylesheet it appends, and `releasePane` finds
+ * both by it. Nothing else reads it, so a document carrying it after a capture returned is a pane
+ * that was never released.
+ */
+export declare const CAPTURE_PANE = "data-capture-pane";
+
+/**
+ * Shoots one frame at one viewport size and proves the file on disk holds this run's bytes.
+ *
+ * @param options - The path to write, the viewport to shoot at, and the element to shoot.
+ * @returns The absolute path of the written frame, after it has been read back and matched.
+ * @throws Thrown when the pane cannot be staged, when the provider wrote the frame somewhere else,
+ * and when the bytes on disk are not the ones this shot produced.
+ *
+ * @remarks
+ * The path a screenshot call returns is the path it meant to write, so it is not evidence a file
+ * exists. The file is read back through the runner's built-in `readFile` command and compared with
+ * the shot itself, which is what separates a frame this run wrote from one an earlier run left
+ * behind. The provider resolves `options.path` against the calling test file and returns an absolute
+ * path, so the two are compared by the segments that survive resolving `.` and `..` lexically — the
+ * refusal is what a provider resolving that path against a different base would trip.
+ *
+ * Omit `options.element` to shoot the whole page. The pane is staged for the frame and released
+ * before this returns, on the failing path as well as the passing one.
+ *
+ * @example
+ * ```ts
+ * await captureFrame({ path: '../../tmp/capture/start.png', width: 390, height: 844 })
+ * ```
+ */
+export declare function captureFrame(options: FrameOptions): Promise<string>;
+
 /** One theme-and-viewport pair a capture run renders. */
 export declare interface CaptureVariant {
     /** The variant's name, which is the second half of every filename the run writes. */
@@ -23,6 +84,21 @@ export declare interface CaptureVariant {
     readonly apply?: () => void;
 }
 
+/**
+ * Clears both browser storage surfaces.
+ *
+ * @remarks
+ * A browser test file shares one page, so a key written by one test is read by the next one that
+ * looks for it. Call this from an `afterEach` hook, which runs after a failed test as well as a
+ * passing one, rather than at the end of each test that happens to write a key.
+ *
+ * @example
+ * ```ts
+ * afterEach(clearStorage)
+ * ```
+ */
+export declare function clearStorage(): void;
+
 /**
  * Clicks one visible, focus-reachable control by its accessible name through the browser provider.
  *
@@ -76,12 +152,15 @@ export declare function clickAccessibleWithin(region: string, role: string, name
  *
  * @param name - The summary text a person reads.
  * @returns A promise resolving after trusted activation completes.
- * @throws When no visible, focus-reachable native summary has that rendered name, or several do.
+ * @throws When no native summary with that rendered name passes {@link isReachable}, or several do.
  *
  * @remarks
  * Chromium exposes `<summary>` as a native disclosure rather than through an ARIA role accepted by
  * `getByRole`, so this resolver names the platform element and its rendered text directly.
  *
+ * It applies the same {@link isReachable} filter the other acting verbs apply, so a summary marked
+ * `aria-disabled="true"` is refused here exactly as a button marked that way is refused there.
+ *
  * @example
  * ```ts
  * await clickDisclosure('Advanced')
@@ -89,12 +168,34 @@ export declare function clickAccessibleWithin(region: string, role: string, name
  */
 export declare function clickDisclosure(name: string): Promise<void>;
 
+/**
+ * One rendered color as straight sRGB channels and its alpha.
+ *
+ * @remarks
+ * The channels run 0–255 and the alpha runs 0–1, which is the shape a computed `rgb()` value already
+ * carries. `parseColor` converts the 0–1 channels of `color(srgb …)` onto the same scale, so every
+ * color the measurement family passes around is comparable without asking where it came from.
+ */
+export declare type Color = readonly [red: number, green: number, blue: number, alpha: number];
+
+/**
+ * The roles whose accessible name is the text a reader can see inside them.
+ *
+ * @remarks
+ * `readName` reads an element in this list from its own rendered text, after every `aria-hidden`
+ * descendant is dropped, and falls through to `title` for every other role.
+ */
+export declare const CONTENT_ROLES: readonly string[];
+
 /**
  * Measures the WCAG 2.x contrast ratio between an element's computed text and background colors.
  *
  * @param element - The element whose rendered text contrast to measure.
+ * @param floor - The opaque color the backdrop walk ends on. Omit it to refuse a stack the floor
+ * would show through instead of assuming one.
  * @returns The relative-luminance contrast ratio.
- * @throws When the browser does not expose parseable computed colors.
+ * @throws Thrown when the element exposes no computed foreground color, and — with `floor` omitted
+ * — when the walk from the element upwards reaches no opaque layer.
  *
  * @remarks
  * A transparent or translucent background resolves through the element's ancestors: every painted
@@ -103,18 +204,53 @@ export declare function clickDisclosure(name: string): Promise<void>;
  * full-strength paint. A translucent foreground then resolves against that effective background
  * before luminance is measured.
  *
- * Every element from the target upwards must be reachable, and at least one of them must paint:
- * the measurement throws rather than assuming a white canvas when nothing in the chain declares a
- * background color. The element itself must expose a computed foreground color — a detached
- * element exposes none, and the measurement throws rather than guessing one.
+ * With `floor` omitted, the walk from the target upwards must reach a fully opaque layer: the
+ * measurement throws rather than assuming a white canvas wherever that canvas would still be part
+ * of the answer. The refusal reads the alpha of the deepest layer {@link readLayers} collected, so
+ * a chain that declares no background color at all, a chain painting only translucent layers, and a
+ * chain deep enough for its composite to round to the canvas's own channels are refused alike,
+ * because the number any of them produces is as much a report of the assumption as of the page.
+ * Supply a floor wherever the caller knows what the stack sits on — a fragment mounted into a
+ * painted host, or a document whose canvas is {@link CANVAS_COLOR} — and the composite is taken
+ * over it rather than refused.
+ *
+ * The element itself must expose a computed foreground color either way. A detached element exposes
+ * none, and the measurement throws rather than guessing one.
  *
  * @example
  * ```ts
  * const container = render('<p style="background: #000; color: #fff">Ready</p>')
  * contrast(requireValue(container.firstElementChild)) // 21
+ * contrast(requireValue(container.firstElementChild), CANVAS_COLOR) // 21, and never refuses
+ * ```
+ */
+export declare function contrast(element: Element, floor?: Color): number;
+
+/**
+ * Creates the journal one scenario records its steps and the page's own output into.
+ *
+ * @returns A journal that records nothing until it is started.
+ *
+ * @remarks
+ * The console is recorded rather than replaced: every intercepted call is forwarded to the channel
+ * that was there when the journal started, so a run under a journal prints exactly what it printed
+ * without one. `stop` puts those same function references back by identity.
+ *
+ * Uncaught errors and unhandled rejections are recorded too, through listeners the journal drops
+ * when it stops. `steps` and `output` hand out snapshots, so a list read mid-scenario stays what it
+ * was. Each journal owns its own recording, so a file that needs one per scenario creates one per
+ * scenario.
+ *
+ * @example
+ * ```ts
+ * const journal = createJournal()
+ * journal.start()
+ * journal.record('click', 'Evaluate', 'alerts=0')
+ * journal.stop()
+ * journal.steps // [{ action: 'click', trigger: 'Evaluate', result: 'alerts=0' }]
  * ```
  */
-export declare function contrast(element: Element): number;
+export declare function createJournal(): JournalInterface;
 
 /**
  * Creates the capture portfolio one run places its screenshots through.
@@ -130,6 +266,10 @@ export declare function contrast(element: Element): number;
  * none of it. The portfolio refuses an unregistered variant at creation. An enabled run refuses an
  * unregistered state name and a second placement of one state.
  *
+ * An enabled `place` writes through `captureFrame`, so a placed state carries that helper's staged
+ * pane and its byte readback: a path is recorded only after the file on disk has been proved to hold
+ * this run's own frame.
+ *
  * @example
  * ```ts
  * const portfolio = createPortfolio({
@@ -143,6 +283,56 @@ export declare function contrast(element: Element): number;
  */
 export declare function createPortfolio(options: PortfolioOptions): PortfolioInterface;
 
+/**
+ * Describes the order sequential keyboard navigation visits one element's controls in.
+ *
+ * @param element - The host to walk; its own controls are described, and it is not itself one.
+ * @returns One numbered line per reachable control, naming its role and its name.
+ *
+ * @remarks
+ * A positive `tabindex` is honoured, because a browser honours it: those controls come first in
+ * ascending order and everything else follows in document order. A control removed from the
+ * sequence by `tabindex="-1"`, by being disabled, or by not being rendered at all is absent here,
+ * which is the fact a focus-order verdict is about. A control {@link readRole} answers `undefined`
+ * for is named by its lowercased tag, so it is still counted rather than silently dropped.
+ *
+ * @example
+ * ```ts
+ * describeFocus(container)
+ * // 1. button "Save"
+ * // 2. link "Cancel"
+ * ```
+ */
+export declare function describeFocus(element: Element): string;
+
+/**
+ * Describes the accessible tree one rendered element presents.
+ *
+ * @param element - The host to walk, which is described first when it carries a role of its own.
+ * @returns One indented line per element carrying a role, naming its role, its name, and its
+ * states, in document order; an empty string when nothing in the subtree carries one.
+ *
+ * @remarks
+ * The walk is over the real rendered DOM, so what it reports is the tree the shipped markup and the
+ * shipped cascade produce together — a landmark lost to a hidden ancestor is missing here exactly as
+ * it is missing for a reader. An element {@link isRendered} refuses is dropped with its whole
+ * subtree.
+ *
+ * Depth follows the roles rather than the elements, so the indentation reads as the structure a
+ * screen reader announces instead of as the markup's nesting. An element {@link readRole} answers
+ * `undefined` for writes no line and adds no depth, so its children sit where it sat. That is how
+ * a wrapper `div` disappears, and it is also how an element {@link IMPLICIT_ROLES} does not answer
+ * for disappears — visibly, because its roled children stay at the depth it occupied.
+ *
+ * @example
+ * ```ts
+ * describeTree(container)
+ * // main "Board"
+ * //   heading "Totals"
+ * ```
+ */
+export declare function describeTree(element: Element): string;
+
 /**
  * Expands a capture registry across every variant into the filenames a complete portfolio holds.
  *
@@ -163,6 +353,42 @@ export declare function createPortfolio(options: PortfolioOptions): PortfolioInt
  */
 export declare function expandCaptures(states: readonly string[], variants: readonly CaptureVariant[]): readonly string[];
 
+/**
+ * Collects every element carrying a component class rendered outside the container it belongs to.
+ *
+ * @param root - The subtree to sweep.
+ * @param child - The component class whose anatomy requires a container, such as `list-group-item`.
+ * @param parent - The container class that child class must render inside, such as `list-group`.
+ * @returns The markup of every element carrying `child` with no `parent` above it, in document
+ * order; an empty list when every one of them is nested correctly.
+ *
+ * @remarks
+ * A component keeps its padding, borders, and radii on the container, so a child class rendered
+ * outside one is an unstyled box wearing a component's name, and the interface has to hand-roll the
+ * chrome back. The search for the container starts at the element's parent, so an element can never
+ * answer the invariant by carrying both classes itself.
+ *
+ * The class names are arguments, so the check belongs to no framework: name the pair your own
+ * cascade defines.
+ *
+ * @example
+ * ```ts
+ * extractOrphans(container, 'list-group-item', 'list-group') // []
+ * ```
+ */
+export declare function extractOrphans(root: ParentNode, child: string, parent: string): readonly string[];
+
+/**
+ * The role each `input` type carries.
+ *
+ * @remarks
+ * Membership is the contract. The map answers for `button`, `checkbox`, `email`, `number`,
+ * `password`, `radio`, `range`, `reset`, `search`, `submit`, `tel`, `text`, and `url`. A type the
+ * map omits — `color`, `date`, `file`, `hidden`, and the rest — exposes no role of its own, so
+ * `readRole` returns `undefined` for it and `describeTree` writes no line for it.
+ */
+export declare const FIELD_ROLES: Readonly<Record<string, string>>;
+
 /**
  * Replaces a named field's value in one operation, for text too long to type key by key.
  *
@@ -181,6 +407,61 @@ export declare function expandCaptures(states: readonly string[], variants: read
  */
 export declare function fillAccessible(name: string, text: string): Promise<void>;
 
+/**
+ * What sequential keyboard navigation can reach, before disabled and unrendered elements go.
+ *
+ * @remarks
+ * `describeFocus` queries this selector and then drops what a browser drops: an element the
+ * accessibility tree does not present, a disabled control, and one removed from the sequence by
+ * `tabindex="-1"`. `traverseAccessible` counts the same population to bound its walk, so this is
+ * the one list either one reads.
+ */
+export declare const FOCUSABLE_SELECTOR = "a[href], area[href], button, input, select, summary, textarea, [tabindex]";
+
+/** Options for one captured frame. */
+export declare interface FrameOptions {
+    /** The frame's path, relative to the calling test file. */
+    readonly path: string;
+    /** The viewport width in CSS pixels the frame is shot at. */
+    readonly width: number;
+    /** The viewport height in CSS pixels the frame is shot at. */
+    readonly height: number;
+    /** The element to shoot. Omit it to shoot the whole page. */
+    readonly element?: Element | undefined;
+}
+
+/**
+ * The role a `th` carries for the header axis its `scope` names.
+ *
+ * @remarks
+ * A header cell heads a column or a row, and this map answers for the `col` and `row` scopes that
+ * say which. A `th` declaring no scope keeps {@link IMPLICIT_ROLES}' `columnheader` rather than the
+ * ARIA computation that infers the axis from the table's shape.
+ */
+export declare const HEADER_ROLES: Readonly<Record<string, string>>;
+
+/**
+ * The role each listed tag carries in the accessibility tree when it declares none of its own.
+ *
+ * @remarks
+ * Membership is the contract. The map answers for the sectioning elements `ARTICLE`, `ASIDE`,
+ * `FOOTER`, `HEADER`, `MAIN`, `NAV`, `SEARCH`, and `SECTION`; the headings `H1` through `H6`; the
+ * grouping and list elements `FIELDSET`, `FORM`, `HR`, `LI`, `OL`, and `UL`; the table elements
+ * `TABLE`, `TBODY`, `THEAD`, `TR`, `TD`, and `TH`; and the widgets `BUTTON`, `DIALOG`, `IMG`,
+ * `OPTION`, `OUTPUT`, `PROGRESS`, `SUMMARY`, and `TEXTAREA`.
+ *
+ * A tag the map omits carries no implicit role, so `readRole` returns `undefined` for it,
+ * `describeTree` writes no line for it, and the walk continues straight into its children at the
+ * depth the omitted element sat at. `A`, `INPUT`, and `SELECT` are absent deliberately: each takes
+ * its role from an attribute rather than from its tag, and `readRole` answers for them from their
+ * own anatomy.
+ *
+ * `SECTION` maps to `region`, which `readRole` withholds from an unnamed one, because an unnamed
+ * section is not a landmark. `TH` maps to `columnheader`, which {@link HEADER_ROLES} replaces when
+ * the cell declares a `scope`.
+ */
+export declare const IMPLICIT_ROLES: Readonly<Record<string, string>>;
+
 /**
  * Determines whether a rectangle lies wholly outside the browser viewport.
  *
@@ -194,6 +475,161 @@ export declare function fillAccessible(name: string, text: string): Promise<void
  */
 export declare function isOutsideViewport(rectangle: DOMRectReadOnly): boolean;
 
+/**
+ * Determines whether a person can click one element where it currently sits.
+ *
+ * @param element - The element to judge.
+ * @returns `true` when 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.
+ *
+ * @remarks
+ * This is the one reachability filter the layer applies. `resolveRendered`, `clickAccessibleWithin`,
+ * and `clickDisclosure` each narrow their own candidates and then keep the ones this accepts, so a
+ * journey meets one rule rather than three near-copies of it.
+ *
+ * It measures geometry, which is what separates it from {@link isRendered}. A control clipped to a
+ * zero-size rectangle is announced and is not clickable, so `isRendered` accepts it and this
+ * refuses it. Nothing here asks about the viewport: `resolveAccessible` scrolls a wholly
+ * off-viewport target into view and measures that separately with {@link isOutsideViewport}.
+ *
+ * @example
+ * ```ts
+ * isReachable(requireValue(container.querySelector('button')))
+ * ```
+ */
+export declare function isReachable(element: Element): boolean;
+
+/**
+ * Determines whether the accessibility tree presents one element at all.
+ *
+ * @param element - The element to judge.
+ * @returns `false` when the element is hidden from assistive technology, from sight, or from both;
+ * `true` otherwise.
+ *
+ * @remarks
+ * A control clipped to a zero-size rectangle is still announced, which is the whole point of that
+ * idiom, so nothing here reads geometry: only the removals a browser honours — `aria-hidden`
+ * anywhere above it, the `hidden` attribute, a hidden input, and a `display` or `visibility` that
+ * takes it off the page. {@link isReachable} is the clickable half of the pair and does read
+ * geometry.
+ *
+ * The last two are asked about the element's ancestors as well as itself, which reading a computed
+ * `display` cannot do: the computed value of a child of a `display: none` container is the child's
+ * own, so a control inside a closed drawer reports itself as laid out. `checkVisibility` answers
+ * 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.
+ *
+ * @example
+ * ```ts
+ * isRendered(requireValue(container.querySelector('[aria-hidden="true"] button'))) // false
+ * ```
+ */
+export declare function isRendered(element: Element): boolean;
+
+/**
+ * The record of one scenario: every step it took and everything the page said while it ran.
+ *
+ * @remarks
+ * Recording is off until {@link JournalInterface.start} arms it, so a suite that never starts a
+ * journal pays for none of it. The console is observed by standing in front of it and forwarding
+ * every call to the channel that was there: a browser offers no listener for its own output, and a
+ * journal that swallowed what it read would hide exactly the diagnostics it exists to keep.
+ */
+export declare interface JournalInterface {
+    /** Every step recorded since the journal started, in the order it was taken; a snapshot. */
+    readonly steps: readonly JournalStep[];
+    /** Every console line and uncaught failure the page emitted since it started; a snapshot. */
+    readonly output: readonly string[];
+    /**
+     * Starts a fresh recording, dropping whatever the previous scenario left.
+     *
+     * @remarks
+     * Calling this on a started journal clears both lists and leaves the console interception
+     * standing, so a restart never wraps its own wrappers.
+     */
+    start(): void;
+    /**
+     * Stops recording and hands every intercepted console channel back by identity.
+     *
+     * @remarks
+     * Calling this on a stopped journal does nothing. The recorded lists survive, so a scenario is
+     * read after its recording ends.
+     */
+    stop(): void;
+    /**
+     * Records one step, when the journal is started.
+     *
+     * @param action - What the run did, as one verb.
+     * @param trigger - The exact thing it did it to.
+     * @param result - What was observed on the surface after the step landed.
+     */
+    record(action: string, trigger: string, result: string): void;
+}
+
+/** One scripted step a journal recorded, and what the surface did about it. */
+export declare interface JournalStep {
+    /** What the run did, as one verb. */
+    readonly action: string;
+    /** The exact thing it did it to. */
+    readonly trigger: string;
+    /** What was observed on the surface after the step landed. */
+    readonly result: string;
+}
+
+/**
+ * Measures the WCAG 2.x contrast ratio between two opaque colors.
+ *
+ * @param front - The foreground color, already composited.
+ * @param back - The opaque backdrop.
+ * @returns The ratio, from `1` for two identical colors to `21` for black against white.
+ *
+ * @remarks
+ * The ratio is symmetric: the brighter of the two luminances is always the numerator, so swapping
+ * the arguments returns the same number.
+ *
+ * @example
+ * ```ts
+ * measureContrast([0, 0, 0, 1], [255, 255, 255, 1]) // 21
+ * ```
+ */
+export declare function measureContrast(front: Color, back: Color): number;
+
+/**
+ * Measures one opaque color's WCAG relative luminance.
+ *
+ * @param color - The color to weigh. Its alpha is ignored, so composite before calling.
+ * @returns The relative luminance, from `0` for black to `1` for white.
+ *
+ * @example
+ * ```ts
+ * measureLuminance([255, 255, 255, 1]) // 1
+ * ```
+ */
+export declare function measureLuminance(color: Color): number;
+
+/**
+ * Parses one computed CSS color value into straight sRGB channels.
+ *
+ * @param value - A computed `rgb()`, `rgba()`, or `color(srgb …)` value.
+ * @returns The color's channels, or `undefined` when the value names no color this reader speaks.
+ *
+ * @remarks
+ * A computed color resolves to `rgb()` or `rgba()` for every legacy source, and a `color-mix()`
+ * declaration resolves to `color(srgb r g b [/ a])` with channels on the 0–1 scale. Both forms are
+ * read here and nothing else is: a keyword, a hex triple, an empty string from a detached element,
+ * and a color space the cascade never hands back all return `undefined`. Absence is the answer
+ * rather than a transparent color, so a caller decides what an unreadable value means instead of
+ * measuring a black it never saw.
+ *
+ * @example
+ * ```ts
+ * parseColor('rgba(255, 255, 255, 0.5)') // [255, 255, 255, 0.5]
+ * parseColor('rebeccapurple') // undefined
+ * ```
+ */
+export declare function parseColor(value: string): Color | undefined;
+
 /** The registry of capture states one run places, and the files it wrote placing them. */
 export declare interface PortfolioInterface {
     /** The name of the variant this run renders. */
@@ -205,14 +641,16 @@ export declare interface PortfolioInterface {
     /** The registry expanded across every variant: the filenames a complete portfolio holds. */
     readonly files: readonly string[];
     /**
-     * Places one registered state: applies the variant, resizes the viewport, and writes the
+     * Places one registered state: applies the variant, stages the pane, and writes the verified
      * screenshot.
      *
      * @param state - The state name from the registry.
+     * @param element - The element to shoot. Omit it to shoot the whole page.
      * @returns The written path, or `undefined` when the portfolio is not enabled.
-     * @throws When the state is not registered or has already been placed.
+     * @throws When the state is not registered, has already been placed, or the written frame does
+     * not read back as the bytes this shot produced.
      */
-    place(state: string): Promise<string | undefined>;
+    place(state: string, element?: Element): Promise<string | undefined>;
 }
 
 /** Options for a capture portfolio. */
@@ -248,6 +686,32 @@ export declare interface PortfolioOptions {
  */
 export declare function pressKeys(keys: string): Promise<void>;
 
+/**
+ * Resolves the opaque color standing behind one element.
+ *
+ * @param element - The element whose backdrop to resolve.
+ * @param floor - The opaque color the walk ends on when nothing above it paints.
+ * @returns The composited color a reader sees behind the element.
+ *
+ * @remarks
+ * The layers {@link readLayers} collects composite top-over-bottom onto the floor, so a 3% surface
+ * tint reads as a tint over what shows through it rather than as a full-strength paint.
+ *
+ * The floor is required, because this leaf never guesses what a document sits on. Pass
+ * {@link CANVAS_COLOR} for the page a browser paints behind an unstyled document, or the color of
+ * the surface a fragment is really rendered into. When no layer paints, the floor is returned by
+ * identity.
+ *
+ * The composite alone never says whether the floor is part of the answer. A caller that must know
+ * reads the stack instead.
+ *
+ * @example
+ * ```ts
+ * readBackdrop(requireValue(container.querySelector('p')), CANVAS_COLOR)
+ * ```
+ */
+export declare function readBackdrop(element: Element, floor: Color): Color;
+
 /**
  * Collects every class token the stylesheets loaded into this document actually define.
  *
@@ -279,6 +743,56 @@ export declare function readCascade(): ReadonlySet<string>;
  */
 export declare function readFocus(): string | undefined;
 
+/**
+ * Collects the painted layers standing between one element and the surface it sits on.
+ *
+ * @param element - The element to walk up from.
+ * @returns Every layer the walk paints, the element's own first and the deepest last.
+ *
+ * @remarks
+ * A surface token paints one ancestor while every element between it and the text paints nothing,
+ * so a backdrop is found by walking up rather than by reading the element's own `background-color`,
+ * which is almost always transparent. A fully transparent layer paints nothing and is left out, and
+ * the walk stops at the first fully opaque layer, because nothing above that layer is visible.
+ *
+ * The stack is what tells a resolved backdrop from an assumed one: the walk reached an opaque
+ * surface exactly when its last layer's alpha is `1`. {@link contrast} refuses on that reading,
+ * which no comparison of composited colors can replace — 64 half-transparent layers composite to
+ * the same channels over opposite floors, because the floor's remaining share falls below the last
+ * bit a channel carries.
+ *
+ * @example
+ * ```ts
+ * readLayers(requireValue(container.querySelector('p')))
+ * ```
+ */
+export declare function readLayers(element: Element): readonly Color[];
+
+/**
+ * Reads the accessible name one element is announced under.
+ *
+ * @param element - The element to name.
+ * @returns The computed name, or an empty string when the element carries none.
+ *
+ * @remarks
+ * The order is the one a browser follows: `aria-labelledby`, then `aria-label`, then a form
+ * control's own labels, then an image's `alt`, then the text inside a role {@link CONTENT_ROLES}
+ * names, then `title`. A submit, reset, or button input is named by its value, because it renders
+ * no text to read. An `aria-labelledby` naming several ids joins their texts in the order the
+ * attribute lists them, and an id nothing answers for is skipped rather than fatal.
+ *
+ * Each step answers only when it has something to say, so a step that carries nothing hands the
+ * element to the next one. An image whose `alt` is absent or blank is the case that shows it:
+ * `<img title="Chart">` is named `Chart` rather than the empty string its own `alt` step would
+ * have returned, and an image carrying both keeps answering `alt`.
+ *
+ * @example
+ * ```ts
+ * readName(requireValue(container.querySelector('button'))) // 'Save changes'
+ * ```
+ */
+export declare function readName(element: Element): string;
+
 /**
  * Reads the normalized visible text of the whole page.
  *
@@ -312,6 +826,66 @@ export declare function readPage(): string;
  */
 export declare function readPerception(name: string): string;
 
+/**
+ * Measures the contrast the focus chrome painted on one control reaches against its own backdrop.
+ *
+ * @param control - The control that holds the focus.
+ * @param worn - The element the control's focus chrome is painted onto. Default: `control`.
+ * @returns The strongest ratio the painted focus chrome reaches, or `undefined` when the control is
+ * not showing `:focus-visible` or the cascade paints no chrome of its own.
+ *
+ * @remarks
+ * This reads and never acts. Focus arrives through the published verbs — `traverseAccessible`,
+ * `pressKeys`, a real click — and this measures what the browser painted once it landed. A control
+ * that is not matching `:focus-visible` when the call is made reports nothing, because no
+ * measurement taken then would be about focus.
+ *
+ * Some controls are two elements: one that takes the focus and one a reader can see. A hidden radio
+ * beside the label that carries every pixel of its chrome is the case `worn` exists for, so a
+ * measurement is not taken on a rectangle nobody is looking at. The focus state is still read off
+ * `control`, because that is what holds it.
+ *
+ * The backdrop is the surface behind the element the chrome is worn on, resolved from that element's
+ * parent through {@link readBackdrop} onto {@link CANVAS_COLOR}. A control whose ancestry paints
+ * nothing is therefore measured against the browser's own canvas, which is what a reader looking at
+ * an unstyled document sees.
+ *
+ * Only chrome the cascade paints is measured — an `outline` with a real style and width, and the
+ * first color in a `box-shadow`. A control left the browser's own `outline-style: auto` ring reports
+ * `undefined`, because that ring's two tones are guaranteed against any backdrop and its computed
+ * color names neither. A focus style that only changes the control's own fill reports `undefined`
+ * too: the resting fill is gone by the time focus is on the control, and this never moves focus to
+ * go and read it.
+ *
+ * @example
+ * ```ts
+ * await traverseAccessible('Evaluate')
+ * readRing(resolveRendered('Evaluate')) // the ratio the painted ring reaches
+ * ```
+ */
+export declare function readRing(control: Element, worn?: Element): number | undefined;
+
+/**
+ * Reads the role one element carries in the accessibility tree.
+ *
+ * @param element - The element to classify.
+ * @returns The declared role, the implicit one, or `undefined` when the element carries none.
+ *
+ * @remarks
+ * A declared `role` wins outright, and its first token is the answer when several are listed.
+ * Otherwise the element's own anatomy decides: an anchor is a link only while it holds an `href`,
+ * an `input` takes the role {@link FIELD_ROLES} gives its type, a `select` is a combobox until it
+ * offers several rows at once, a `section` is a region only once something names it, and a `th`
+ * heads whichever axis its `scope` names. Every other tag answers from {@link IMPLICIT_ROLES},
+ * whose membership is the contract for what this can answer at all.
+ *
+ * @example
+ * ```ts
+ * readRole(requireValue(container.querySelector('a[href]'))) // 'link'
+ * ```
+ */
+export declare function readRole(element: Element): string | undefined;
+
 /**
  * Reads the normalized visible text of every element a selector matches, in document order.
  *
@@ -331,6 +905,47 @@ export declare function readPerception(name: string): string;
  */
 export declare function readRows(root: ParentNode, selector: string): readonly string[];
 
+/**
+ * Reads the states one element is announced in.
+ *
+ * @param element - The element to read.
+ * @returns Every state the element declares, in one fixed order.
+ *
+ * @remarks
+ * A state a reader is told about is one this records: what is unavailable, disclosed, pressed,
+ * current, refused, chosen, announcing itself, demanded, uneditable, described, or busy. The order
+ * is fixed, so two descriptions of the same surface are comparable line for line.
+ *
+ * A native disclosure states its expansion on the parent `details` element's own `open` rather than
+ * on an ARIA attribute, so a summary that declares no `aria-expanded` is read from the platform's
+ * one copy of that fact.
+ *
+ * @example
+ * ```ts
+ * readStates(requireValue(container.querySelector('summary'))) // ['collapsed']
+ * ```
+ */
+export declare function readStates(element: Element): readonly string[];
+
+/**
+ * Reads one element's rendered text the way a name computation reads it.
+ *
+ * @param element - The element whose announced words are wanted.
+ * @returns The text with every `aria-hidden` descendant dropped and whitespace runs collapsed.
+ *
+ * @remarks
+ * A glyph marked `aria-hidden` contributes nothing to a name, so a control captioned by an icon
+ * plus a word reads as the word alone — which is what a reader hears, and what a verdict citing a
+ * description has to compare against the copy a template writes. Reach for `readRows` wherever the
+ * subject is what the page paints rather than what it announces: that one keeps the glyph.
+ *
+ * @example
+ * ```ts
+ * readText(requireValue(container.querySelector('button'))) // 'Save'
+ * ```
+ */
+export declare function readText(element: Element): string;
+
 /**
  * Reads the value a resolved control renders.
  *
@@ -350,6 +965,24 @@ export declare function readRows(root: ParentNode, selector: string): readonly s
  */
 export declare function readValue(role: string, name: string): string;
 
+/**
+ * Hands the tester pane back to the runner's own layout.
+ *
+ * @remarks
+ * A staged pane is the runner's fitting scale suppressed, so a pane left staged outlives the capture
+ * that needed it and every later act in the file happens on a surface the runner is no longer
+ * fitting to its window. What that costs is not a wrong picture: it is a control whose page
+ * coordinates fall outside the pane, which the runner's own layout then intercepts, so an ordinary
+ * press fails with the voice of a control that is covered. Calling this on an unstaged pane does
+ * nothing.
+ *
+ * @example
+ * ```ts
+ * releasePane()
+ * ```
+ */
+export declare function releasePane(): void;
+
 /**
  * Renders trusted fixture markup into a container attached to the document.
  *
@@ -421,6 +1054,47 @@ export declare function resolveAccessible(role: string, name: string): HTMLEleme
  */
 export declare function resolveRendered(first: string, second?: string): HTMLElement;
 
+/**
+ * Sets the tester's viewport and renders the runner's pane at the size that viewport claims.
+ *
+ * @param width - The viewport width in CSS pixels.
+ * @param height - The viewport height in CSS pixels.
+ * @returns A promise resolving after the resized pane has been painted.
+ * @throws Thrown when the tester sits inside no pane a capture can size, and when the staged pane
+ * does not render at the viewport it was given.
+ *
+ * @remarks
+ * This depends on the runner's own tester layout, and that dependency is contract rather than an
+ * accident: `vitest@4.1.11` lays its tester out inside a smaller page, fits it by scaling the pane
+ * the tester sits in, and clips whatever overflows that pane. Layout inside the tester is
+ * unaffected — the tester reports the viewport it was given and every breakpoint answers to it —
+ * but a screenshot is taken off the page the runner painted, so a frame shot through that scale is
+ * a thumbnail of the surface and a frame shot after only unscaling it is a sliver. The tester is
+ * therefore unscaled and lifted to the window's own origin for the shot. The `iframe[data-vitest]`
+ * selector and the `--tester-transform`, `--tester-margin-left`, `--viewport-width`, and
+ * `--viewport-height` custom properties are the runner's, so a Vitest release that renames any of
+ * them reddens the size check below rather than writing a wrong frame.
+ *
+ * Hand the pane straight back with {@link releasePane}. A tester pinned at a viewport taller than
+ * the window puts its lower half beyond what a pointer can reach, so an ordinary press then fails
+ * as a control outside the viewport, in a test that took no picture at all.
+ *
+ * The rule is declared rather than written inline, because the runner writes its own scale onto the
+ * pane as inline custom properties and rewrites them whenever the tester resizes. A declared rule
+ * marked important outranks an inline value and survives every rewrite. It finds the pane by the
+ * tester it contains as well as by {@link CAPTURE_PANE}, because a re-render between the staging and
+ * the shot replaces the node and takes any attribute of ours with it.
+ *
+ * The wait is two frames rather than a delay: the first carries the resize into layout and the
+ * second is the paint a screenshot reads.
+ *
+ * @example
+ * ```ts
+ * await stagePane(390, 844)
+ * ```
+ */
+export declare function stagePane(width: number, height: number): Promise<void>;
+
 /**
  * Reads one resolved CSS property from a real browser element.
  *