@orkestrel/test 0.0.7 → 0.0.9

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

@@ -8,6 +8,89 @@
  */
 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;
+
+/**
+ * Builds one unmounted element of a known tag, wearing the classes, text, and attributes asked for.
+ *
+ * @param tag - The HTML tag name, which fixes the returned element's exact type.
+ * @param options - The class list, the text, and the attributes to apply.
+ * @returns The built element, not yet in any document.
+ *
+ * @remarks
+ * The element is unmounted on purpose, so a fixture is assembled before the page ever sees it and a
+ * test decides where it goes. Nothing here resolves against the cascade: a built element computes no
+ * style and lays out no box until {@link mount} puts it in the document.
+ *
+ * The text is set as text rather than parsed as markup, so a `<` in it stays a `<`. Use
+ * {@link render} where the fixture is markup.
+ *
+ * @example
+ * ```ts
+ * const button = build('button', { classes: 'primary', text: 'Save', attributes: { type: 'button' } })
+ * ```
+ */
+export declare function build<K extends keyof HTMLElementTagNameMap>(tag: K, options?: ElementOptions): HTMLElementTagNameMap[K];
+
+/**
+ * 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 +106,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 +174,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 +190,79 @@ 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];
+
+/**
+ * Determines whether two colors render the same, within the rounding a browser does.
+ *
+ * @param first - A CSS color expression or an already-parsed color.
+ * @param second - A CSS color expression or an already-parsed color.
+ * @returns `true` when every channel and the alpha agree within the tolerance; `false` otherwise,
+ * including when either side names no readable color.
+ *
+ * @remarks
+ * Each string side is resolved through {@link rgba}, so a keyword, a token reference, and the
+ * `rgb()` the engine computes for either of them compare equal without a test converting anything
+ * first. A side that resolves to nothing makes the answer `false` rather than a throw, because this
+ * is a predicate.
+ *
+ * The tolerance is half a channel step on the 0–255 scale, and the alpha is scaled onto that same
+ * range before it is compared, so one number covers both. Half a step is what a composite of
+ * translucent layers and a `color-mix()` round trip actually drift by; anything a reader could see
+ * is further than that and reports unequal.
+ *
+ * @example
+ * ```ts
+ * colorEqual('rebeccapurple', 'rgb(102, 51, 153)') // true
+ * colorEqual('red', [0, 0, 255, 1]) // false
+ * ```
+ */
+export declare function colorEqual(first: string | Color, second: string | Color): boolean;
+
+/**
+ * Sets one field's value and commits it, the way typing and then leaving the field does.
+ *
+ * @param element - The input or textarea to write into.
+ * @param text - The value to set.
+ *
+ * @remarks
+ * The order is the browser's: {@link typeInput} first, so `input` is dispatched with the value
+ * already set, and one bubbling `change` after it. A component that reads the value from either
+ * event therefore reads `text` from both.
+ *
+ * @example
+ * ```ts
+ * commitInput(requireValue(container.querySelector('input')), 'Ada')
+ * ```
+ */
+export declare function commitInput(element: HTMLInputElement | HTMLTextAreaElement, text: string): void;
+
+/**
+ * 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 +271,131 @@ 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 one console channel that records every call it receives and hands that call on unchanged.
+ *
+ * @param name - The channel's name, which prefixes each line it records.
+ * @param output - The list each call is recorded into, appended to in place.
+ * @param forward - The channel every call is passed on to after it is recorded.
+ * @returns A channel carrying the console's own call signature.
+ *
+ * @remarks
+ * One call becomes one line. Every argument of that call is put through `String` and joined with a
+ * space, so a call carrying several values reads as the one line the page printed rather than as
+ * several entries.
+ *
+ * Nothing is swallowed. The record happens first and `forward` receives the arguments it would have
+ * received, so a page recorded through this prints exactly what it printed without it. The list
+ * belongs to the caller, so a channel writes into whatever it was handed and holds no state of its
+ * own. {@link createJournal} builds one channel per console method over one list.
+ *
+ * @example
+ * ```ts
+ * const output: string[] = []
+ * console.log = createChannel('log', output, console.log)
+ * ```
+ */
+export declare function createChannel(name: string, output: string[], forward: (...data: unknown[]) => void): (...data: unknown[]) => void;
+
+/**
+ * Creates one real drag event carrying a live data transfer, ready to dispatch.
+ *
+ * @param name - The event type, such as `dragstart`.
+ * @param options - Any `DragEventInit` member, each one overriding the default beneath it.
+ * @returns A real `DragEvent` of that type.
+ *
+ * @remarks
+ * A drag event with no `dataTransfer` is the shape that makes a drop handler fail in a test and work
+ * in a browser, so one is allocated. Pass your own to seed it: a `dataTransfer` given in `options`
+ * replaces the allocated one, which is how a drop is driven with the payload the drag was supposed
+ * to carry.
+ *
+ * The platform declares the `dataTransfer` member on the constructed event as nullable, so calling
+ * code still narrows it even though this always supplies one.
+ *
+ * `bubbles` and `cancelable` are set, because a drop handler that never prevents the default event
+ * is a drop the browser handles itself.
+ *
+ * @example
+ * ```ts
+ * const started = createDragEvent('dragstart')
+ * started.dataTransfer?.setData('text/plain', 'row-3')
+ * element.dispatchEvent(started)
+ * ```
+ */
+export declare function createDragEvent(name: string, options?: DragEventInit): DragEvent;
+
+/**
+ * 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 one real pointer event, ready to dispatch.
+ *
+ * @param name - The event type, such as `pointerdown`.
+ * @param options - Any `PointerEventInit` member, each one overriding the default beneath it.
+ * @returns A real `PointerEvent` of that type.
+ *
+ * @remarks
+ * The defaults are what a browser's own pointer event carries and a hand-built one does not:
+ * `bubbles` and `cancelable` are set, so a delegated listener hears it and a handler can prevent it,
+ * and `pointerId`, `pointerType`, and `isPrimary` describe a single primary mouse, so a component
+ * that branches on the pointer kind takes the branch a mouse takes. Override any of them by naming
+ * it; a touch is `{ pointerType: 'touch' }` and nothing else has to be restated.
+ *
+ * The event is real rather than a shaped object, so `instanceof PointerEvent` holds and the
+ * coordinate and modifier members a handler reads are the ones the platform defines.
+ *
+ * @example
+ * ```ts
+ * element.dispatchEvent(createPointerEvent('pointerdown', { clientX: 10, clientY: 20 }))
+ * ```
+ */
+export declare function createPointerEvent(name: string, options?: PointerEventInit): PointerEvent;
 
 /**
  * Creates the capture portfolio one run places its screenshots through.
@@ -130,6 +411,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 +428,74 @@ 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;
+
+/**
+ * Options for one built element.
+ *
+ * @remarks
+ * `classes` is written the way a `class` attribute is written — one space-separated string — so a
+ * fixture reads as the markup it stands in for. `attributes` is set name by name after the class
+ * list and the text, so an `attributes` entry named `class` wins over `classes` rather than merging
+ * with it.
+ */
+export declare interface ElementOptions {
+    /** The class list, space-separated, exactly as a `class` attribute writes it. */
+    readonly classes?: string;
+    /** The text the element carries, set as text rather than parsed as markup. */
+    readonly text?: string;
+    /** Every attribute to set, keyed by attribute name. */
+    readonly attributes?: Readonly<Record<string, string>>;
+}
+
 /**
  * Expands a capture registry across every variant into the filenames a complete portfolio holds.
  *
@@ -163,6 +516,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 +570,104 @@ export declare function expandCaptures(states: readonly string[], variants: read
  */
 export declare function fillAccessible(name: string, text: string): Promise<void>;
 
+/**
+ * Finds the animation the cascade declares under one name.
+ *
+ * @param name - The exact `@keyframes` name.
+ * @returns The first matching rule in {@link readRules} order, or `undefined` when the cascade
+ * declares no animation under that name.
+ *
+ * @remarks
+ * The name is matched exactly, which is where this parts from {@link findRule}: a selector is
+ * compound and a fragment of one is a useful question, and an animation name is one atom that either
+ * is or is not the one an `animation` declaration references.
+ *
+ * @example
+ * ```ts
+ * findKeyframes('fade')?.cssRules.length
+ * ```
+ */
+export declare function findKeyframes(name: string): CSSKeyframesRule | undefined;
+
+/**
+ * Finds the first style rule in the cascade whose selector carries a fragment.
+ *
+ * @param selector - The selector fragment to look for, matched as a substring of the whole selector
+ * text.
+ * @returns The first matching rule in {@link readRules} order, or `undefined` when no rule carries
+ * the fragment.
+ *
+ * @remarks
+ * This proves a declaration exists in the cascade at all, which is a different question from what an
+ * element resolves to: {@link style} reads the winner, and a rule this finds may be overridden by
+ * another. Assert on this where the subject is the stylesheet, and on `style` where the subject is
+ * the rendered result.
+ *
+ * The match is a substring, so `findRule('.card')` finds `.card`, `.card:hover`, and
+ * `.panel > .card` alike. Pass more of the selector to narrow it.
+ *
+ * @example
+ * ```ts
+ * findRule('.card')?.style.getPropertyValue('padding')
+ * ```
+ */
+export declare function findRule(selector: string): CSSStyleRule | undefined;
+
+/**
+ * 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 +681,215 @@ 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;
+
+/**
+ * Puts one element into the document and hands it straight back.
+ *
+ * @param element - The element to attach.
+ * @returns The same element, now appended to `document.body`.
+ *
+ * @remarks
+ * What this buys is the composition, not the attachment: the `append` method returns `void`, and
+ * this hands the element back, so it fits where an expression is expected. The {@link render} helper
+ * returns its fixture through it, and the {@link rgba} helper probes through `mount(build('span'))`.
+ * A bare `append` call breaks each of those call sites.
+ *
+ * Being connected is what the attachment then buys: `getComputedStyle` resolves against the shipped
+ * cascade, custom properties inherit from `:root`, and the element lays out a real box. A detached
+ * element answers each of those questions with the initial value instead, which reads as a styling
+ * defect rather than as a detached node.
+ *
+ * Taking it back out belongs to the consumer's teardown, because this records nothing: a browser
+ * test file shares one page, so a fixture left behind is the next test's resolver ambiguity. Build a
+ * recorded container in a setup module and remove it from an `afterEach` hook.
+ *
+ * @example
+ * ```ts
+ * const panel = mount(build('div', { classes: 'surface' }))
+ * panel.remove()
+ * ```
+ */
+export declare function mount<T extends Element>(element: T): T;
+
+/**
+ * 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;
+
+/**
+ * Reads one resolved CSS length as a number of pixels.
+ *
+ * @param element - The element whose resolved style to inspect.
+ * @param property - The CSS property name, registered or custom.
+ * @returns The leading numeric part of the resolved value, and `0` when it carries none.
+ *
+ * @remarks
+ * A resolved length is text with a unit — `'12px'` — so this reads the number in front of the unit
+ * and discards the rest. The unit is not checked: the resolved value of a length is in pixels in
+ * every case a browser hands back, and a property that resolves to something else is the caller's
+ * mistake rather than this reader's.
+ *
+ * An unparsable value reads as `0` rather than as absence, because every caller of this is measuring
+ * and `'auto'`, `'none'`, and `''` each contribute no pixels to what a reader sees. Where the
+ * distinction matters, read the text with {@link style} instead.
+ *
+ * @example
+ * ```ts
+ * pixels(button, 'padding-left') // 12
+ * pixels(button, 'width') // 0 when the width resolves to `auto`
+ * ```
+ */
+export declare function pixels(element: Element, property: string): number;
+
 /** 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 +901,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,15 +946,53 @@ 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.
  *
- * @returns The set of class names reachable in the shipped cascade.
+ * @returns The set of class names reachable in the shipped cascade, in {@link readRules} order.
  *
  * @remarks
  * The set is what an authored-class conformance check measures against, so a class no loaded
  * stylesheet defines — an invented utility, a misspelled framework name — is absent from it.
  *
+ * The tokens come from the {@link readRules} walk, which decides both the membership and the
+ * insertion order this reader reports, and each answer is a deliberate difference from 0.0.8. A
+ * class declared inside a grouping rule — a media query, a supports block, a layer, a nested style
+ * rule — counts as defined, because a class the cascade defines under a condition is still one the
+ * cascade defines; 0.0.8 read the top-level rules alone. Insertion order is breadth-first, so a
+ * top-level class lands before a class declared inside an earlier grouping rule; 0.0.8 popped a
+ * stack and inserted the deepest rule first. Iterate the set where the order is the subject, and
+ * read `has` where membership is.
+ *
+ * `@keyframes` children are outside that walk, so an animation's own rules define no token here.
+ * Reach the animation itself through {@link findKeyframes}.
+ *
  * @example
  * ```ts
  * readCascade().has('card')
@@ -279,6 +1015,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 +1098,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 +1177,76 @@ export declare function readPerception(name: string): string;
  */
 export declare function readRows(root: ParentNode, selector: string): readonly string[];
 
+/**
+ * Collects every rule the stylesheets loaded into this document hold, nested grouping rules
+ * included.
+ *
+ * @returns Every rule reachable in the shipped cascade: each sheet's own rules in sheet order, then
+ * the rules nested inside them, level by level.
+ *
+ * @remarks
+ * The walk is iterative and reads the list it is still appending to, which is what expands a media
+ * query, a supports block, a layer, and a nested style rule without recursion. Expanding by level
+ * rather than by depth is why a top-level rule is always met before a rule nested inside an earlier
+ * one; {@link findRule} returns the first match in exactly this order.
+ *
+ * The descent reaches a `CSSGroupingRule` and nothing else, and a `@keyframes` rule is not one. The
+ * `@keyframes` rule itself is collected wherever it sits, and the keyframe rules inside it are not;
+ * {@link findKeyframes} is the door to those.
+ *
+ * A stylesheet the document cannot read — a cross-origin sheet with no CORS grant — throws from its
+ * own `cssRules` getter, and that sheet is skipped rather than ending the walk. What a page loaded
+ * from another origin declares is unreadable to every caller here, so the alternative is a helper
+ * that works until a test page adds a font or an analytics stylesheet.
+ *
+ * @example
+ * ```ts
+ * readRules().filter((rule) => rule instanceof CSSKeyframesRule)
+ * ```
+ */
+export declare function readRules(): readonly CSSRule[];
+
+/**
+ * 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.
  *
@@ -351,19 +1267,75 @@ export declare function readRows(root: ParentNode, selector: string): readonly s
 export declare function readValue(role: string, name: string): string;
 
 /**
- * Renders trusted fixture markup into a container attached to the document.
+ * 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;
+
+/**
+ * Deletes one IndexedDB database and reports what the request actually did.
  *
- * @param markup - The fixture markup to render.
- * @returns The attached container.
+ * @param name - The database name to delete.
+ * @returns A promise resolving after the deletion completes.
+ * @throws Thrown when the request errors, and when an open connection blocks it.
+ *
+ * @remarks
+ * Deleting a database that was never created succeeds, so this is safe to call from a teardown hook
+ * that runs whether or not the test reached the code that opens one.
+ *
+ * A block is a rejection rather than a wait. `blocked` fires when another connection is still open,
+ * and a suite that swallowed it would leave the next test reading the previous test's records
+ * through a database that reports itself deleted. The connection holding it open is the caller's to
+ * close, so the block is handed back rather than absorbed.
+ *
+ * @example
+ * ```ts
+ * afterEach(() => removeDatabase('ledger'))
+ * ```
+ */
+export declare function removeDatabase(name: string): Promise<void>;
+
+/**
+ * Renders one fixture into the document, from trusted markup or from a tag and its classes.
+ *
+ * @param first - The fixture markup, or the HTML tag name when `second` is present.
+ * @param second - The class list when `first` supplies the tag name.
+ * @returns The attached container for the markup form, and the attached element itself for the tag
+ * form.
+ *
+ * @remarks
+ * The class list is required in the tag form, which is what keeps the two forms apart: a
+ * one-argument call is always markup. A tag with no classes is `mount(build(tag))`.
+ *
+ * The markup form parses `first` into a fresh container and returns that container, so the fixture's
+ * own nodes are its children. The tag form returns the element itself, typed as exactly that tag.
+ * Both attach to `document.body` and neither records anything, so removal is the caller's, exactly
+ * as it is for {@link mount}.
  *
  * @example
  * ```ts
  * const container = render('<button type="button">Save</button>')
+ * const panel = render('section', 'surface muted')
  * container.remove()
+ * panel.remove()
  * ```
  */
 export declare function render(markup: string): HTMLDivElement;
 
+export declare function render<K extends keyof HTMLElementTagNameMap>(tag: K, classes: string): HTMLElementTagNameMap[K];
+
 /**
  * Resolves one visible, focus-reachable interactive element by its exact accessible name. A
  * wholly-off-viewport target is scrolled into view before reachability is measured.
@@ -421,12 +1393,109 @@ export declare function resolveAccessible(role: string, name: string): HTMLEleme
  */
 export declare function resolveRendered(first: string, second?: string): HTMLElement;
 
+/**
+ * Resolves any CSS color expression to straight sRGB channels, by asking the browser.
+ *
+ * @param value - Any value the `color` property accepts: a keyword, a hex triple, a `var()`
+ * reference, a `color-mix()`, or an already-computed `rgb()`.
+ * @returns The resolved color's channels, or `undefined` when the CSSOM refuses the value or the
+ * computed result names no color {@link parseColor} speaks.
+ *
+ * @remarks
+ * This is the live half of the pair {@link parseColor} opens. `parseColor` reads text and speaks
+ * only the computed syntaxes a cascade hands back; this stages a probe element, hands it to the real
+ * cascade, and reads back what the engine computed — which is the only way a keyword, a hex triple,
+ * or a `var()` reference becomes channels at all. The read itself goes through `parseColor`, so both
+ * halves agree on what a computed value means.
+ *
+ * The probe is mounted, because an unmounted element inherits nothing and a `var()` reference to a
+ * token declared on `:root` would resolve to the initial value instead. It is removed in a `finally`,
+ * so a value that throws on the way through leaves no node behind.
+ *
+ * Refusal is the CSSOM's: an expression it will not parse leaves the probe's inline `color` empty
+ * and this returns `undefined`. A `var()` naming an undeclared custom property is not refused,
+ * because the cascade accepts it and computes the inherited color, so a test that means to catch a
+ * missing token asserts on {@link token} rather than on this.
+ *
+ * @example
+ * ```ts
+ * rgba('rebeccapurple') // [102, 51, 153, 1]
+ * rgba('not-a-color') // undefined
+ * ```
+ */
+export declare function rgba(value: string): Color | undefined;
+
+/**
+ * Reads one custom property from the document element.
+ *
+ * @param name - The custom property name, with or without its leading dashes.
+ * @returns The resolved value, trimmed; an empty string when the document declares no such property.
+ *
+ * @remarks
+ * This is {@link token} against `document.documentElement`, which is where a theme declares its
+ * tokens and where a `[data-theme]` switch retunes them. It exists as its own name because that
+ * element is the one a token question is nearly always about, and naming it at every call site
+ * buries the question.
+ *
+ * @example
+ * ```ts
+ * rootToken('surface')
+ * ```
+ */
+export declare function rootToken(name: string): string;
+
+/**
+ * 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.
  *
  * @param element - The element whose resolved style to inspect.
- * @param property - The CSS property name.
- * @returns The browser's resolved property value.
+ * @param property - The CSS property name, registered or custom.
+ * @returns The browser's resolved property value, trimmed; an empty string when the element resolves
+ * none.
+ *
+ * @remarks
+ * The value is trimmed, so what comes back is the value and never the whitespace around it. Internal
+ * whitespace is kept: `--shadow: 0 0 2px` reads back with its spaces.
  *
  * @example
  * ```ts
@@ -435,6 +1504,32 @@ export declare function resolveRendered(first: string, second?: string): HTMLEle
  */
 export declare function style(element: Element, property: string): string;
 
+/**
+ * Reads one custom property from an element's resolved style.
+ *
+ * @param element - The element whose resolved style to inspect.
+ * @param name - The custom property name, with or without its leading dashes.
+ * @returns The resolved value, trimmed; an empty string when the element inherits no such property.
+ *
+ * @remarks
+ * The dashes are optional because a token is spoken about both ways — `--surface` in a stylesheet
+ * and `surface` in prose — and a reader that accepted only one spelling would turn that into a silent
+ * empty string. An absent token reads as `''`, which is what the CSSOM returns and is
+ * indistinguishable from a token declared empty; assert on the value you expect rather than on
+ * presence.
+ *
+ * Resolution is inheritance, so a token declared on `:root` reads from any mounted descendant and
+ * from an unmounted element reads as `''`. Use {@link rootToken} where the declaration is the
+ * document's.
+ *
+ * @example
+ * ```ts
+ * token(panel, 'surface') // '#ffffff'
+ * token(panel, '--surface') // '#ffffff'
+ * ```
+ */
+export declare function token(element: Element, name: string): string;
+
 /**
  * Reaches a named control only through natural forward Tab traversal from the current focus.
  *
@@ -463,6 +1558,31 @@ export declare function traverseAccessible(name: string): Promise<HTMLElement>;
  */
 export declare function typeAccessible(name: string, text: string): Promise<void>;
 
+/**
+ * Sets one field's value and announces it the way typing into the field does.
+ *
+ * @param element - The input or textarea to write into.
+ * @param text - The value to set.
+ *
+ * @remarks
+ * This is the synthetic pair of {@link typeAccessible}, for a component that listens for `input` and
+ * a test that has the element already. It sets the value in one write and dispatches one bubbling
+ * `input` event, so a delegated listener on an ancestor hears it. It sends no keystrokes, so a
+ * component reading `key`, composition, or selection sees nothing. The dispatched event is a plain
+ * `Event`, never an `InputEvent`, so a component reading `inputType` or testing
+ * `instanceof InputEvent` sees neither. Drive a component that reads any of those through
+ * `typeAccessible` instead.
+ *
+ * No `change` event follows. Use {@link commitInput} where the component waits for the field to be
+ * committed.
+ *
+ * @example
+ * ```ts
+ * typeInput(requireValue(container.querySelector('input')), 'Ada')
+ * ```
+ */
+export declare function typeInput(element: HTMLInputElement | HTMLTextAreaElement, text: string): void;
+
 /**
  * Waits for one animation frame to settle pending browser paint work.
  *