@orkestrel/scaffold 0.0.77 → 0.0.79

package/dist/host/guides/test.md

@@ -254,6 +254,7 @@ a union's arms escaped as `\|`.
 | `Color`               | type      | `readonly [red, green, blue, alpha]`                                           | Represents one rendered color as straight sRGB channels and its alpha.                                                                          |
 | `ElementOptions`      | interface | `{ classes?, text?, attributes? }`                                             | Configures one built element: its class list, its text, and its attributes.                                                                     |
 | `FrameOptions`        | interface | `{ path, width, height, element? }`                                            | Configures one captured frame: where it is written, the viewport it is shot at, and what it shoots.                                             |
+| `FrameOffset`         | interface | `{ top, left }`                                                                | Represents how far an element frame moves the tester frame from the runner window's origin for the shot, in CSS pixels.                         |
 | `FrameReading`        | interface | `{ width, height, floor }`                                                     | Represents one written frame read back from the file a capture produced: its size in device pixels, and the single color its bottom row paints. |
 | `CaptureVariant`      | interface | `JourneyVariant` plus `{ apply? }`                                             | Adds to a journey variant the document change a capture run applies before resizing.                                                            |
 | `PortfolioOptions`    | interface | `{ states, variants, variant, directory, enabled? }`                           | Configures a capture portfolio: the state registry, the variant matrix, this run's variant, where it writes, and whether it writes at all.      |
@@ -261,6 +262,7 @@ a union's arms escaped as `\|`.
 | `JournalStep`         | interface | `{ action, trigger, result }`                                                  | Represents one scripted step a journal recorded, and what the surface did about it.                                                             |
 | `JournalInterface`    | interface | `{ steps, output }` plus `start` / `stop` / `record`                           | Records one scenario: every step it took and everything the page said while it ran.                                                             |
 | `StateOptions`        | interface | `WaitOptions` plus `{ absent? }`                                               | Configures a bounded wait over the states a control announces.                                                                                  |
+| `MediaOptions`        | interface | `{ print?, motion?, forced? }`                                                 | Configures the tester's print medium, motion preference, and forced colours.                                                                    |
 | `StorageOptions`      | interface | `{ values?, reads?, writes?, quota? }`                                         | Configures an inert `Storage`: its seed, which operations the host permits, and its quota.                                                      |
 | `WebStorageInterface` | interface | `Storage` plus `{}` plus `permit`                                              | Holds a store the host can withhold and later grant.                                                                                            |
 | `CensusReading`       | interface | `{ elements, tokens, undeclared }`                                             | Reports an authored-class census: the population walked, the tokens found, and the undeclared.                                                  |
@@ -285,79 +287,106 @@ A `Shape` cell holds the constant's declared type.
 | `FOCUSABLE_SELECTOR` | const | `string`                           | Names what sequential keyboard navigation can reach, before disabled and unrendered elements go.           |
 | `HEADER_ROLES`       | const | `Readonly<Record<string, string>>` | Names the role a `th` carries for the header axis its `scope` names.                                       |
 | `IMPLICIT_ROLES`     | const | `Readonly<Record<string, string>>` | Names the role each listed tag carries in the accessibility tree when it declares none of its own.         |
+| `MEDIA_STAGE`        | const | `string`                           | Names the tester root's attribute holding the media readings observed before the first stage.              |
+| `POINTER_HOLD`       | const | `string`                           | Names the tester root's attribute holding the pressed pointer's page coordinates.                          |
 
 #### Helpers
 
-| API                     | Kind     | Signature                                                                                                               | Summary                                                                                                                                                                                     |
-| ----------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `resolveAccessible`     | function | `(name: string) => HTMLElement` / `(role: string, name: string) => HTMLElement`                                         | 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.                 |
-| `resolveRendered`       | function | `(first: string, second?: string) => HTMLElement`                                                                       | Resolves one rendered, focus-reachable interactive element without requiring it to intersect the viewport yet.                                                                              |
-| `computeNamePattern`    | function | `(name: string) => RegExp`                                                                                              | Computes the pattern that matches one accessible name a decorative glyph may sit beside.                                                                                                    |
-| `isOutsideViewport`     | function | `(rectangle: DOMRectReadOnly) => boolean`                                                                               | Determines whether a rectangle lies wholly outside the browser viewport.                                                                                                                    |
-| `isRendered`            | function | `(element: Element) => boolean`                                                                                         | Determines whether the accessibility tree presents one element at all.                                                                                                                      |
-| `isReachable`           | function | `(element: Element) => boolean`                                                                                         | Determines whether a person can click one element where it sits.                                                                                                                            |
-| `readHit`               | function | `(element: Element) => Element \| undefined`                                                                            | Reads the topmost element at one element's bounding-box centre.                                                                                                                             |
-| `clickAccessible`       | function | `(name: string) => Promise<void>` / `(role: string, name: string) => Promise<void>`                                     | Clicks one visible, focus-reachable control by its accessible name through the browser provider.                                                                                            |
-| `clickAccessibleWithin` | function | `(region: string, role: string, name: string) => Promise<void>`                                                         | Clicks one human-reachable control by role and accessible-name text inside a named region.                                                                                                  |
-| `clickDisclosure`       | function | `(name: string) => Promise<void>`                                                                                       | Opens or closes one native details disclosure by its rendered summary.                                                                                                                      |
-| `typeAccessible`        | function | `(name: string, text: string) => Promise<void>`                                                                         | Replaces a named field's value through focus, select-all, deletion, and real keystrokes.                                                                                                    |
-| `fillAccessible`        | function | `(name: string, text: string) => Promise<void>`                                                                         | Replaces a named field's value in one operation, for text too long to type key by key.                                                                                                      |
-| `traverseAccessible`    | function | `(name: string) => Promise<HTMLElement>`                                                                                | Reaches a named control only through natural forward Tab traversal from the current focus.                                                                                                  |
-| `pressKeys`             | function | `(keys: string) => Promise<void>`                                                                                       | Sends a key sequence to whatever holds focus, and refuses to send it to nothing.                                                                                                            |
-| `readPerception`        | function | `(name: string) => string`                                                                                              | Reads the normalized visible text of one named region, dialog, table, tab panel, or alert.                                                                                                  |
-| `readPage`              | function | `() => string`                                                                                                          | Reads the normalized visible text of the whole page.                                                                                                                                        |
-| `readFocus`             | function | `() => string \| undefined`                                                                                             | Reads the rendered text of the element that holds focus.                                                                                                                                    |
-| `readValue`             | function | `(role: string, name: string) => string`                                                                                | Reads the value a resolved control renders.                                                                                                                                                 |
-| `readRefusal`           | function | `(name: string) => string \| undefined` / `(role: string, name: string) => string \| undefined`                         | Reads the refusal one named target answers with, or nothing when it resolves.                                                                                                               |
-| `readText`              | function | `(element: Element) => string`                                                                                          | Reads one element's rendered text the way a name computation reads it.                                                                                                                      |
-| `readRole`              | function | `(element: Element) => string \| undefined`                                                                             | Reads the role one element carries in the accessibility tree.                                                                                                                               |
-| `readName`              | function | `(element: Element) => string`                                                                                          | Reads the accessible name one element is announced under.                                                                                                                                   |
-| `readStates`            | function | `(element: Element) => readonly string[]`                                                                               | Reads the states one element is announced in.                                                                                                                                               |
-| `describeTree`          | function | `(element: Element) => string`                                                                                          | Describes the accessible tree one rendered element presents.                                                                                                                                |
-| `describeFocus`         | function | `(element: Element) => string`                                                                                          | Describes the order sequential keyboard navigation visits one element's controls in.                                                                                                        |
-| `waitForFrame`          | function | `() => Promise<void>`                                                                                                   | Waits for one animation frame to settle pending browser paint work.                                                                                                                         |
-| `waitForState`          | function | `(name, state, options?) => Promise<readonly string[]>` / `(role, name, state, options?) => Promise<readonly string[]>` | Waits until one named control announces a state, or stops announcing it.                                                                                                                    |
-| `waitForAnimations`     | function | `(element: Element, options?: WaitOptions) => Promise<void>`                                                            | Waits until every finite animation on one element and its subtree has stopped moving.                                                                                                       |
-| `build`                 | function | `<K extends keyof HTMLElementTagNameMap>(tag: K, options?: ElementOptions) => HTMLElementTagNameMap[K]`                 | Builds one unmounted element of a known tag, wearing the classes, text, and attributes asked for.                                                                                           |
-| `mount`                 | function | `<T extends Element>(element: T) => T`                                                                                  | Puts one element into the document and hands it straight back.                                                                                                                              |
-| `render`                | function | `(markup: string) => HTMLDivElement` / `(tag: K, classes: string) => HTMLElementTagNameMap[K]`                          | Renders one fixture into the document from trusted markup.                                                                                                                                  |
-| `typeInput`             | function | `(element: HTMLInputElement \| HTMLTextAreaElement, text: string) => void`                                              | Sets one field's value and announces it the way typing into the field does.                                                                                                                 |
-| `commitInput`           | function | `(element: HTMLInputElement \| HTMLTextAreaElement, text: string) => void`                                              | Sets one field's value and commits it, the way typing and then leaving the field does.                                                                                                      |
-| `clearStorage`          | function | `() => void`                                                                                                            | Clears both browser storage surfaces.                                                                                                                                                       |
-| `removeDatabase`        | function | `(name: string) => Promise<void>`                                                                                       | Deletes one IndexedDB database and reports what the request actually did.                                                                                                                   |
-| `parseColor`            | function | `(value: string) => Color \| undefined`                                                                                 | Parses one computed CSS color value into straight sRGB channels.                                                                                                                            |
-| `parseCSSColor`         | function | `(value: string) => Color \| undefined`                                                                                 | Resolves any CSS color expression to straight sRGB channels, by asking the browser.                                                                                                         |
-| `matchesColor`          | function | `(first: string \| Color, second: string \| Color) => boolean`                                                          | Determines whether two colors render the same, within the rounding a browser does.                                                                                                          |
-| `blendColor`            | function | `(front: Color, back: Color) => Color`                                                                                  | Composites one color over another.                                                                                                                                                          |
-| `measureLuminance`      | function | `(color: Color) => number`                                                                                              | Measures one opaque color's WCAG relative luminance.                                                                                                                                        |
-| `measureContrast`       | function | `(front: Color, back: Color) => number`                                                                                 | Measures the WCAG 2.x contrast ratio between two opaque colors.                                                                                                                             |
-| `readLayers`            | function | `(element: Element) => readonly Color[]`                                                                                | Collects the painted layers standing between one element and the surface it sits on.                                                                                                        |
-| `readBackdrop`          | function | `(element: Element, floor: Color) => Color`                                                                             | Resolves the opaque color standing behind one element.                                                                                                                                      |
-| `readContrast`          | function | `(element: Element, floor?: Color) => number`                                                                           | Measures the WCAG 2.x contrast ratio between an element's computed text and background colors.                                                                                              |
-| `readRing`              | function | `(control: Element, worn?: Element) => number \| undefined`                                                             | Measures the contrast the focus chrome painted on one control reaches against its own backdrop.                                                                                             |
-| `measureContent`        | function | `() => number`                                                                                                          | Measures the row the document's own content ends on, in document coordinates.                                                                                                               |
-| `stagePane`             | function | `(width: number, height: number) => Promise<void>`                                                                      | Sets the tester's viewport and renders the runner's pane at the size that viewport claims.                                                                                                  |
-| `releasePane`           | function | `() => Promise<void>`                                                                                                   | Hands the tester pane back to the runner's own layout, at the viewport it had before staging.                                                                                               |
-| `captureFrame`          | function | `(options: FrameOptions) => Promise<string>`                                                                            | Shoots one frame at one viewport size and proves the file on disk holds this run's bytes.                                                                                                   |
-| `readFrame`             | function | `(path: string) => Promise<FrameReading>`                                                                               | Reads one written frame back and reports its size and the color its bottom row paints.                                                                                                      |
-| `readCascade`           | function | `() => ReadonlySet<string>`                                                                                             | Collects every class token the stylesheets loaded into this document actually define.                                                                                                       |
-| `readClasses`           | function | `(root: ParentNode) => ReadonlySet<string>`                                                                             | Collects every class token the markup under one root carries.                                                                                                                               |
-| `readCensus`            | function | `(root: ParentNode) => CensusReading`                                                                                   | Takes the authored-class census of one subtree against the cascade this document loaded.                                                                                                    |
-| `readRules`             | function | `() => readonly CSSRule[]`                                                                                              | Collects every rule the stylesheets loaded into this document hold, nested grouping rules included.                                                                                         |
-| `findRule`              | function | `(selector: string) => CSSStyleRule \| undefined`                                                                       | Finds the first style rule in the cascade whose selector carries a fragment.                                                                                                                |
-| `findKeyframes`         | function | `(name: string) => CSSKeyframesRule \| undefined`                                                                       | Finds the animation the cascade declares under one name.                                                                                                                                    |
-| `readRows`              | function | `(root: ParentNode, selector: string) => readonly string[]`                                                             | Reads the normalized visible text of every element a selector matches, in document order.                                                                                                   |
-| `extractOrphans`        | function | `(root: ParentNode, child: string, parent: string) => readonly string[]`                                                | Collects every element carrying a component class rendered outside the container it belongs to.                                                                                             |
-| `extractStyles`         | function | `(root: ParentNode) => readonly string[]`                                                                               | Collects the markup of every element carrying a non-empty `style` attribute and of every `<style>` element, in document order, `root` included in both populations when it is an `Element`. |
-| `readStyle`             | function | `(element: Element, property: string) => string`                                                                        | Reads one resolved CSS property from a real browser element.                                                                                                                                |
-| `readToken`             | function | `(element: Element, name: string) => string`                                                                            | Reads one custom property from an element's resolved style.                                                                                                                                 |
-| `readRootToken`         | function | `(name: string) => string`                                                                                              | Reads one custom property from the document element.                                                                                                                                        |
-| `readPixels`            | function | `(element: Element, property: string) => number`                                                                        | Reads one resolved CSS length as a number of pixels.                                                                                                                                        |
-| `expandCaptures`        | function | `(states: readonly string[], variants: readonly CaptureVariant[]) => readonly string[]`                                 | Expands a capture registry across every variant into the filenames a complete portfolio holds.                                                                                              |
-| `buildDenial`           | function | `(operation: string, key?: string) => DOMException`                                                                     | Builds the refusal a host withholding a storage operation raises.                                                                                                                           |
-| `buildContrast`         | function | `(bar: number) => ContrastFixture`                                                                                      | Builds a detached translucent stack whose composited and flat contrast readings straddle one bar.                                                                                           |
-| `buildEscapes`          | function | `(permitted: string) => EscapeFixture`                                                                                  | Builds detached markup carrying one style escape of each kind, plus the sheet a project allows.                                                                                             |
-| `buildCensus`           | function | `() => CensusFixture`                                                                                                   | Builds detached markup carrying one undeclared class token on HTML and another on SVG.                                                                                                      |
+| API                        | Kind     | Signature                                                                                                               | Summary                                                                                                                                                                                                                                                                         |
+| -------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `resolveAccessible`        | function | `(name: string) => HTMLElement` / `(role: string, name: string) => HTMLElement`                                         | 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.                                                                                                     |
+| `resolveAccessibleWithin`  | function | `(region: string, role: string, name: string) => HTMLElement`                                                           | Resolves one human-reachable control by role and accessible-name text inside a named region.                                                                                                                                                                                    |
+| `resolveRendered`          | function | `(first: string, second?: string) => HTMLElement`                                                                       | Resolves one rendered, focus-reachable interactive element without requiring it to intersect the viewport yet.                                                                                                                                                                  |
+| `computeNamePattern`       | function | `(name: string) => RegExp`                                                                                              | Computes the pattern that matches one accessible name a decorative glyph may sit beside.                                                                                                                                                                                        |
+| `isOutsideViewport`        | function | `(rectangle: DOMRectReadOnly) => boolean`                                                                               | Determines whether a rectangle lies wholly outside the browser viewport.                                                                                                                                                                                                        |
+| `isRendered`               | function | `(element: Element) => boolean`                                                                                         | Determines whether the accessibility tree presents one element at all.                                                                                                                                                                                                          |
+| `isReachable`              | function | `(element: Element) => boolean`                                                                                         | Determines whether a person can click one element where it sits.                                                                                                                                                                                                                |
+| `readHit`                  | function | `(element: Element) => Element \| undefined`                                                                            | Reads the topmost element at one element's bounding-box centre.                                                                                                                                                                                                                 |
+| `clickAccessible`          | function | `(name: string) => Promise<void>` / `(role: string, name: string) => Promise<void>`                                     | Clicks one visible, focus-reachable control by its accessible name through the browser provider.                                                                                                                                                                                |
+| `clickAccessibleWithin`    | function | `(region: string, role: string, name: string) => Promise<void>`                                                         | Clicks one human-reachable control by role and accessible-name text inside a named region.                                                                                                                                                                                      |
+| `clickDisclosure`          | function | `(name: string) => Promise<void>`                                                                                       | Opens or closes one native details disclosure by its rendered summary.                                                                                                                                                                                                          |
+| `sendProtocol`             | function | `(method: string, params: Readonly<Record<string, unknown>>) => Promise<void>`                                          | Sends one DevTools protocol command through the browser provider.                                                                                                                                                                                                               |
+| `hoverAccessible`          | function | `(name: string) => Promise<void>` / `(role: string, name: string) => Promise<void>`                                     | Hovers one visible, focus-reachable control by its accessible name through the browser provider.                                                                                                                                                                                |
+| `holdAccessible`           | function | `(name: string) => Promise<void>` / `(role: string, name: string) => Promise<void>`                                     | Holds the primary pointer button on one visible, focus-reachable control by its accessible name.                                                                                                                                                                                |
+| `holdAccessibleWithin`     | function | `(region: string, role: string, name: string) => Promise<void>`                                                         | Holds the primary pointer button on one control by role and accessible-name text inside a named region.                                                                                                                                                                         |
+| `driveHold`                | function | `(resolve: () => HTMLElement, name: string) => Promise<void>`                                                           | Holds the primary pointer button on the control a resolver returns, through the browser provider.                                                                                                                                                                               |
+| `releasePointer`           | function | `() => Promise<void>`                                                                                                   | Releases a held pointer and parks it outside the page, clearing hover.                                                                                                                                                                                                          |
+| `typeAccessible`           | function | `(name: string, text: string) => Promise<void>`                                                                         | Replaces a named field's value through focus, select-all, deletion, and real keystrokes.                                                                                                                                                                                        |
+| `fillAccessible`           | function | `(name: string, text: string) => Promise<void>`                                                                         | Replaces a named field's value in one operation, for text too long to type key by key.                                                                                                                                                                                          |
+| `traverseAccessible`       | function | `(name: string) => Promise<HTMLElement>`                                                                                | Reaches a named control only through natural forward Tab traversal from the current focus.                                                                                                                                                                                      |
+| `traverseAccessibleWithin` | function | `(region: string, role: string, name: string) => Promise<HTMLElement>`                                                  | Reaches a control by role and accessible-name text inside a named region, only through natural forward Tab traversal from the current focus.                                                                                                                                    |
+| `driveTraversal`           | function | `(resolve: () => HTMLElement, name: string) => Promise<HTMLElement>`                                                    | Reaches the control a resolver returns, only through natural forward Tab traversal from the current focus.                                                                                                                                                                      |
+| `pressKeys`                | function | `(keys: string) => Promise<void>`                                                                                       | Sends a key sequence to whatever holds focus, and refuses to send it to nothing.                                                                                                                                                                                                |
+| `readPerception`           | function | `(name: string) => string`                                                                                              | Reads the normalized visible text of one named region, dialog, table, tab panel, or alert.                                                                                                                                                                                      |
+| `readPage`                 | function | `() => string`                                                                                                          | Reads the normalized visible text of the whole page.                                                                                                                                                                                                                            |
+| `readFocus`                | function | `() => string \| undefined`                                                                                             | Reads the rendered text of the element that holds focus.                                                                                                                                                                                                                        |
+| `readValue`                | function | `(role: string, name: string) => string`                                                                                | Reads the value a resolved control renders.                                                                                                                                                                                                                                     |
+| `readRefusal`              | function | `(name: string) => string \| undefined` / `(role: string, name: string) => string \| undefined`                         | Reads the refusal one named target answers with, or nothing when it resolves.                                                                                                                                                                                                   |
+| `readText`                 | function | `(element: Element) => string`                                                                                          | Reads one element's rendered text the way a name computation reads it.                                                                                                                                                                                                          |
+| `readRole`                 | function | `(element: Element) => string \| undefined`                                                                             | Reads the role one element carries in the accessibility tree.                                                                                                                                                                                                                   |
+| `readName`                 | function | `(element: Element) => string`                                                                                          | Reads the accessible name one element is announced under.                                                                                                                                                                                                                       |
+| `readStates`               | function | `(element: Element) => readonly string[]`                                                                               | Reads the states one element is announced in.                                                                                                                                                                                                                                   |
+| `describeTree`             | function | `(element: Element) => string`                                                                                          | Describes the accessible tree one rendered element presents.                                                                                                                                                                                                                    |
+| `describeFocus`            | function | `(element: Element) => string`                                                                                          | Describes the order sequential keyboard navigation visits one element's controls in.                                                                                                                                                                                            |
+| `waitForFrame`             | function | `() => Promise<void>`                                                                                                   | Waits for one animation frame to settle pending browser paint work.                                                                                                                                                                                                             |
+| `waitForState`             | function | `(name, state, options?) => Promise<readonly string[]>` / `(role, name, state, options?) => Promise<readonly string[]>` | Waits until one named control announces a state, or stops announcing it.                                                                                                                                                                                                        |
+| `waitForAnimations`        | function | `(element: Element, options?: WaitOptions) => Promise<void>`                                                            | Waits until every finite animation on one element and its subtree has stopped moving.                                                                                                                                                                                           |
+| `build`                    | function | `<K extends keyof HTMLElementTagNameMap>(tag: K, options?: ElementOptions) => HTMLElementTagNameMap[K]`                 | Builds one unmounted element of a known tag, wearing the classes, text, and attributes asked for.                                                                                                                                                                               |
+| `mount`                    | function | `<T extends Element>(element: T) => T`                                                                                  | Puts one element into the document and hands it straight back.                                                                                                                                                                                                                  |
+| `render`                   | function | `(markup: string) => HTMLDivElement` / `(tag: K, classes: string) => HTMLElementTagNameMap[K]`                          | Renders one fixture into the document from trusted markup.                                                                                                                                                                                                                      |
+| `typeInput`                | function | `(element: HTMLInputElement \| HTMLTextAreaElement, text: string) => void`                                              | Sets one field's value and announces it the way typing into the field does.                                                                                                                                                                                                     |
+| `commitInput`              | function | `(element: HTMLInputElement \| HTMLTextAreaElement, text: string) => void`                                              | Sets one field's value and commits it, the way typing and then leaving the field does.                                                                                                                                                                                          |
+| `clearStorage`             | function | `() => void`                                                                                                            | Clears both browser storage surfaces.                                                                                                                                                                                                                                           |
+| `removeDatabase`           | function | `(name: string) => Promise<void>`                                                                                       | Deletes one IndexedDB database and reports what the request actually did.                                                                                                                                                                                                       |
+| `convertSRGB`              | function | `(red: number, green: number, blue: number, alpha?: number) => Color`                                                   | Converts normalized encoded sRGB channels to the clipped paint scale.                                                                                                                                                                                                           |
+| `convertLinearSRGB`        | function | `(red: number, green: number, blue: number, alpha?: number) => Color`                                                   | Converts linear sRGB channels to encoded, clipped paint channels.                                                                                                                                                                                                               |
+| `convertXYZD65`            | function | `(x: number, y: number, z: number, alpha?: number) => Color`                                                            | Converts D65 XYZ coordinates to clipped sRGB paint channels.                                                                                                                                                                                                                    |
+| `convertXYZD50`            | function | `(x: number, y: number, z: number, alpha?: number) => Color`                                                            | Converts D50 XYZ coordinates to clipped sRGB paint channels.                                                                                                                                                                                                                    |
+| `convertOKLab`             | function | `(lightness: number, a: number, b: number, alpha?: number) => Color`                                                    | Converts OKLab coordinates to clipped sRGB paint channels.                                                                                                                                                                                                                      |
+| `convertLab`               | function | `(lightness: number, a: number, b: number, alpha?: number) => Color`                                                    | Converts CIE Lab coordinates relative to D50 to clipped sRGB paint channels.                                                                                                                                                                                                    |
+| `convertDisplayP3`         | function | `(red: number, green: number, blue: number, alpha?: number) => Color`                                                   | Converts encoded Display P3 channels to clipped sRGB paint channels.                                                                                                                                                                                                            |
+| `convertA98RGB`            | function | `(red: number, green: number, blue: number, alpha?: number) => Color`                                                   | Converts encoded A98 RGB channels to clipped sRGB paint channels.                                                                                                                                                                                                               |
+| `convertProPhotoRGB`       | function | `(red: number, green: number, blue: number, alpha?: number) => Color`                                                   | Converts encoded ProPhoto RGB channels to clipped sRGB paint channels.                                                                                                                                                                                                          |
+| `convertRec2020`           | function | `(red: number, green: number, blue: number, alpha?: number) => Color`                                                   | Converts encoded Rec. 2020 channels to clipped sRGB paint channels.                                                                                                                                                                                                             |
+| `parseColor`               | function | `(value: string) => Color \| undefined`                                                                                 | Parses computed CSS Color 4 values into clipped straight sRGB channels.                                                                                                                                                                                                         |
+| `parseCSSColor`            | function | `(value: string) => Color \| undefined`                                                                                 | Resolves any CSS color expression to straight sRGB channels, by asking the browser.                                                                                                                                                                                             |
+| `matchesColor`             | function | `(first: string \| Color, second: string \| Color) => boolean`                                                          | Determines whether two colors render the same, within the rounding a browser does.                                                                                                                                                                                              |
+| `blendColor`               | function | `(front: Color, back: Color) => Color`                                                                                  | Composites one color over another.                                                                                                                                                                                                                                              |
+| `measureLuminance`         | function | `(color: Color) => number`                                                                                              | Measures one opaque color's WCAG relative luminance.                                                                                                                                                                                                                            |
+| `measureContrast`          | function | `(front: Color, back: Color) => number`                                                                                 | Measures the WCAG 2.x contrast ratio between two opaque colors.                                                                                                                                                                                                                 |
+| `readLayers`               | function | `(element: Element) => readonly Color[]`                                                                                | Collects readable background color layers and refuses an unreadable painted layer.                                                                                                                                                                                              |
+| `readBackdrop`             | function | `(element: Element, floor: Color) => Color`                                                                             | Resolves the opaque color standing behind one element.                                                                                                                                                                                                                          |
+| `readContrast`             | function | `(element: Element, floor?: Color) => number`                                                                           | Measures the WCAG 2.x contrast ratio between an element's computed text and background colors.                                                                                                                                                                                  |
+| `readRing`                 | function | `(control: Element, worn?: Element) => number \| undefined`                                                             | Measures the contrast the focus chrome painted on one control reaches against its own backdrop.                                                                                                                                                                                 |
+| `readClipEdge`             | function | `(element: Element) => number \| undefined`                                                                             | Measures the row a clipping element cuts its content off at, in document coordinates.                                                                                                                                                                                           |
+| `readClipMargin`           | function | `(element: Element) => number`                                                                                          | Measures how far past its own box a clipping element lets its content show.                                                                                                                                                                                                     |
+| `clipsOverflow`            | function | `(element: Element) => boolean`                                                                                         | Reports whether an element clips its descendants' overflow.                                                                                                                                                                                                                     |
+| `measureContent`           | function | `() => number`                                                                                                          | Measures the row the document's own content ends on, in document coordinates.                                                                                                                                                                                                   |
+| `stagePane`                | function | `(width: number, height: number) => Promise<void>`                                                                      | Sets the tester's viewport and renders the runner's pane at the size that viewport claims.                                                                                                                                                                                      |
+| `releasePane`              | function | `() => Promise<void>`                                                                                                   | Hands the tester pane back to the runner's own layout, at the viewport it had before staging.                                                                                                                                                                                   |
+| `computeOffset`            | function | `(box: DOMRectReadOnly, width: number, height: number) => FrameOffset`                                                  | Computes how far an element frame moves the tester frame so the element is shot inside the runner's window.                                                                                                                                                                     |
+| `stageMedia`               | function | `(options: MediaOptions) => Promise<void>`                                                                              | Stages the tester's print medium, motion preference, and forced colours through the browser provider.                                                                                                                                                                           |
+| `releaseMedia`             | function | `() => Promise<void>`                                                                                                   | Restores the media readings observed before the first stage as explicit emulation. With nothing staged, clears every override and waits for a stable reading, not a proved engine baseline. Checks the budget between polls, so a frame that never paints is not bounded by it. |
+| `captureFrame`             | function | `(options: FrameOptions) => Promise<string>`                                                                            | Shoots one frame at one viewport size and proves the file on disk holds this run's bytes.                                                                                                                                                                                       |
+| `readFrame`                | function | `(path: string) => Promise<FrameReading>`                                                                               | Reads one written frame back and reports its size and the color its bottom row paints.                                                                                                                                                                                          |
+| `readCascade`              | function | `() => ReadonlySet<string>`                                                                                             | Collects every class token the stylesheets loaded into this document actually define.                                                                                                                                                                                           |
+| `readClasses`              | function | `(root: ParentNode) => ReadonlySet<string>`                                                                             | Collects every class token the markup under one root carries.                                                                                                                                                                                                                   |
+| `readCensus`               | function | `(root: ParentNode) => CensusReading`                                                                                   | Takes the authored-class census of one subtree against the cascade this document loaded.                                                                                                                                                                                        |
+| `readRules`                | function | `() => readonly CSSRule[]`                                                                                              | Collects every rule the stylesheets loaded into this document hold, nested grouping rules included.                                                                                                                                                                             |
+| `findRule`                 | function | `(selector: string) => CSSStyleRule \| undefined`                                                                       | Finds the first style rule in the cascade whose selector carries a fragment.                                                                                                                                                                                                    |
+| `findKeyframes`            | function | `(name: string) => CSSKeyframesRule \| undefined`                                                                       | Finds the animation the cascade declares under one name.                                                                                                                                                                                                                        |
+| `readRows`                 | function | `(root: ParentNode, selector: string) => readonly string[]`                                                             | Reads the normalized visible text of every element a selector matches, in document order.                                                                                                                                                                                       |
+| `extractOrphans`           | function | `(root: ParentNode, child: string, parent: string) => readonly string[]`                                                | Collects every element carrying a component class rendered outside the container it belongs to.                                                                                                                                                                                 |
+| `extractStyles`            | function | `(root: ParentNode) => readonly string[]`                                                                               | Collects the markup of every element carrying a non-empty `style` attribute and of every `<style>` element, in document order, `root` included in both populations when it is an `Element`.                                                                                     |
+| `readStyle`                | function | `(element: Element, property: string, pseudo?: string) => string`                                                       | Reads one resolved CSS property from a real browser element or a named pseudo-element.                                                                                                                                                                                          |
+| `readToken`                | function | `(element: Element, name: string) => string`                                                                            | Reads one custom property from an element's resolved style.                                                                                                                                                                                                                     |
+| `readRootToken`            | function | `(name: string) => string`                                                                                              | Reads one custom property from the document element.                                                                                                                                                                                                                            |
+| `readPixels`               | function | `(element: Element, property: string, pseudo?: string) => number`                                                       | Reads one resolved CSS length as a number of pixels.                                                                                                                                                                                                                            |
+| `expandCaptures`           | function | `(states: readonly string[], variants: readonly CaptureVariant[]) => readonly string[]`                                 | Expands a capture registry across every variant into the filenames a complete portfolio holds.                                                                                                                                                                                  |
+| `buildDenial`              | function | `(operation: string, key?: string) => DOMException`                                                                     | Builds the refusal a host withholding a storage operation raises.                                                                                                                                                                                                               |
+| `buildContrast`            | function | `(bar: number) => ContrastFixture`                                                                                      | Builds a detached translucent stack whose composited and flat contrast readings straddle one bar.                                                                                                                                                                               |
+| `buildEscapes`             | function | `(permitted: string) => EscapeFixture`                                                                                  | Builds detached markup carrying one style escape of each kind, plus the sheet a project allows.                                                                                                                                                                                 |
+| `buildCensus`              | function | `() => CensusFixture`                                                                                                   | Builds detached markup carrying one undeclared class token on HTML and another on SVG.                                                                                                                                                                                          |
 
 #### Factories
 
@@ -412,13 +441,20 @@ rendered status completes its accessible name: the region supplies the context,
 has to be recognisable inside it. The loose match reads a computed name that includes the hidden
 subtrees, so a glyph joins the text rather than displacing it and the control is still recognisable
 under the words beside it. That verb owns one refusal for a control it cannot reach, absent or
-hidden, so it needs no second pass to tell the two apart.
+hidden, so it needs no second pass to tell the two apart. `resolveAccessibleWithin` is that
+resolution on its own, and `holdAccessibleWithin` and `traverseAccessibleWithin` drive the control it
+resolves the way `holdAccessible` and `traverseAccessible` drive a document-wide one, so a twin of
+the same name in another region is left alone.
 
 `traverseAccessible` charges a step only when focus actually lands on an element, ends when focus
 revisits one — that is a complete cycle of the tab order — and re-resolves the target by name on
 every step, because a framework may replace the node between resolution and focus arrival. Its hard
 cap is three times the page's candidate count plus ten, including disabled controls and elements
 with `tabindex="-1"`, so a page whose focus never settles fails instead of hanging.
+`driveTraversal` is that loop over any resolver, and `driveHold` is the one pointer drive every hold
+verb shares, releasing the pointer before refusing when the frame wait or the pressed-state read
+fails, as well as when the press misses; each verb supplies its resolver and the name its refusals
+voice.
 
 `build` and `mount` are the halves of a fixture, and `render` is the pair spelled as one call.
 `build` creates the element and applies its class list, its text, and its attributes, and leaves it
@@ -451,6 +487,16 @@ another connection is still open, and a suite that swallowed it would leave the
 the previous test's records through a database that reports itself deleted. The connection holding
 it open is the caller's to close, and [Voices](#voices) carries the message each refusal spells.
 
+The paint parser reads computed `rgb()`, `rgba()`, `oklab()`, `oklch()`, `lab()`,
+`lch()`, and `color()` values. Its predefined spaces are `srgb`, `srgb-linear`,
+`display-p3`, `a98-rgb`, `prophoto-rgb`, `rec2020`, `xyz`, `xyz-d50`, and
+`xyz-d65`. Signed channels, percentage lightness, degree hues, scientific notation, and
+`none` components resolve to straight sRGB. The exported conversion helpers apply the
+[CSS Color 4 matrices and white-point adaptation](https://www.w3.org/TR/css-color-4/#color-conversion-code).
+The Rec. 2020 decoder follows Chromium's piecewise transfer curve. Encoded sRGB channels are
+clipped to 0–255 after conversion; this reader does not perform perceptual gamut mapping.
+Alpha is clipped to 0–1.
+
 `parseCSSColor` is the live half of the pair `parseColor` opens. `parseColor` reads text and speaks
 only the computed syntaxes a cascade hands back; `parseCSSColor` stages a probe element, hands the
 expression to the real cascade, and reads back what the engine computed — which is the only way a
@@ -483,6 +529,12 @@ layers blend to identical channels over black and over white alike, because the
 share falls below the last bit a channel carries, so comparing two composited readings admits the
 stack the refusal exists for.
 
+An unreadable painted background layer throws an error naming its element and computed value.
+Non-finite calculations such as `color(srgb calc(infinity) 0 0)` are deliberately unreadable.
+A layer with an explicit zero alpha paints nothing and is skipped, including an unreadable one.
+Background images remain outside this color reader. The refusal propagates through `readBackdrop`,
+`readContrast`, and the focused-control reading in `readRing`, even with a supplied floor.
+
 `readBackdrop` composites that stack and takes its floor as an argument rather than reaching for
 `CANVAS_COLOR` itself, so a measurement over a surface the canvas never shows through names the
 color it actually sits on. When no layer paints it hands that floor straight back.
@@ -493,7 +545,8 @@ the browser painted once it landed: the `outline` the cascade declares, and the
 `outline-style: auto` ring, and a focus style that only changes the control's own fill all report
 `undefined` — in each case no measurement taken here would be about focus. `worn` names the element
 the chrome is painted onto when that is not the element holding focus, which is the hidden-input
-control whose visible label wears every pixel of its chrome.
+control whose visible label wears every pixel of its chrome. Modern colors, including an
+`oklch()` box-shadow, return the ring’s contrast ratio against its backdrop.
 
 `readRules` is the one walk over the shipped cascade, and `readCascade`, `findRule`, and
 `findKeyframes` all read through it. It collects each sheet's own rules in sheet order and then
@@ -556,7 +609,7 @@ command and compares it with the shot itself, which is what separates this run's
 earlier run left behind. It releases the pane in a `finally`, so a refusal at any stage hands the
 tester back before it propagates.
 
-The frame covers the whole document at the width it was given, whatever height it was given. The
+A page frame covers the whole document at the width it was given, whatever height it was given. The
 provider shoots the tester's body in the top-level page's own coordinates, so a document taller than
 the pane paints for the pane's height and the rows under it are the runner's page: the frame reads
 as the surface down to the fold and as bare canvas after it. `captureFrame` therefore lays the
@@ -570,9 +623,18 @@ reads back as the document's own height. A capture that staged a pane taller tha
 not descend from a reading like that — the box, `body.scrollHeight`, `body.offsetHeight`, and
 `documentElement.scrollHeight` each answer with the pane. `measureContent` walks the elements inside
 the body instead, taking the largest bottom edge in document coordinates plus that element's own
-bottom margin, and adds the body's and the root's bottom padding and margin under them. It rounds
-up, which is what covers a body ending part way through a row: a box ending on a fraction under a
-half is a row the integer scroll height drops, and that row comes out as the runner's page.
+bottom margin, and adds the body's and the root's bottom padding and margin under them. An
+ancestor that clips its overflow (the `clipsOverflow` helper: an `overflow-y` value other than the
+`visible` keyword, or a paint containment) caps a descendant's edge at that ancestor's clip edge,
+which the `readClipEdge` helper reads. An `overflow-y` value of the `hidden` keyword, the `auto`
+keyword, or the `scroll` keyword clips at the padding box, whatever the ancestor's
+`overflow-clip-margin` value selects. The `clip` keyword and a paint containment over a `visible`
+overflow clip at the box that value selects, the padding box by default, expanded by the length the
+`readClipMargin` helper reads. So a viewport-height specimen
+inside a bounded frame ends, for the reading, where the frame ends rather than stretching the
+document with every pane. It rounds up, which is what covers a body ending part way through a row: a
+box ending on a fraction under a half is a row the integer scroll height drops, and that row comes
+out as the runner's page.
 
 The edge is read again after every staging, because a rule bound to the viewport height — a `vh`
 length, a fixed footer, a full-height panel — lays the document out taller against the taller pane,
@@ -595,13 +657,40 @@ written at a height that is already wrong. That bound is 4: a document holding h
 fixed block settles in two restagings, one whose growth is capped part way settles in three, and
 the fourth is headroom.
 
+An element frame no taller than the declared height is shot in the declared pane, so its viewport
+lengths resolve against the declared viewport whether the element sits above the fold, below it, or
+fixed: a `50vh` element under a 900-row block reads back 422 rows in an 844-row pane. The re-reading
+takes the element's own height, so the pane grows only for an element taller than the declared
+height, and then to that element's height, which is what its viewport lengths resolve against.
+Where the element's box lies outside the pane, the document is scrolled by the nearest distance that
+would bring it inside, and the box is read again. A fixed element past the pane can take a scroll
+that does not move it, and that scroll is handed back with the rest. The document is not scrolled for
+an element already inside the pane.
+
+The provider paints an element that fits the runner's window only where that window shows it. Where
+such an element lies past the window, the `captureFrame` function offsets the calling tester frame up
+or left only as far as brings the element inside, and composites the frame so a fixed element that
+starts past the window's height is not culled. The `computeOffset` function computes that move. The
+offset is written on that frame's own `style` attribute, outranks the placement the `stagePane`
+function makes, and is removed as soon as the screenshot settles. An element inside the window, or
+too large for it, is not offset.
+
+The capture sends no pointer input. The staging lifts the tester to the window's origin, a scroll
+brings an element outside the pane into it, and an offset brings an element past the window inside;
+each moves content under a pointer resting on the page. A pointer the case placed on the element,
+with the pane already staged at the frame's size, keeps its hover in the frame where the element lies
+inside both the pane and the runner window, because the capture then moves nothing. No hover is
+promised after the pane is released.
+
 `readFrame` reads a written frame back: its size in device pixels, and the single color its bottom
 row paints. The reading comes off the file through the browser's own image decoding rather than off
 the document that produced it, which is what makes it evidence about the capture rather than a
 second look at the style that fed it — a clipped frame reports the runner's white canvas as its
 floor while every style in the document still resolves to the document's own background. Pass the
 absolute path `captureFrame` returned: the runner's `readFile` command resolves a relative path
-against its own root rather than against the calling test file.
+against its own root rather than against the calling test file. A file that opens with a PNG header
+and still does not decode is refused with the width and height that header declares, in device
+pixels; a file with no PNG header is refused without a size.
 
 `createPortfolio` refuses an unregistered variant name at creation, so a run cannot write a filename
 naming a combination it did not render. A portfolio left un-`enabled` is the ordinary run: `place`
@@ -991,50 +1080,51 @@ what the link reaches, not on what it stores.
 Every message `src/browser` throws. Keep them distinct: a journey asserts the one it means, and
 absent, present-but-gated, and ambiguous are different findings about an interface.
 
-| Voice                                                                                    | Thrown by               |
-| ---------------------------------------------------------------------------------------- | ----------------------- |
-| `No interactive element has the accessible name "<name>"`                                | `resolveRendered`       |
-| `Interactive target "<name>" is not visible and focus-reachable`                         | `resolveRendered`       |
-| `Interactive target "<name>" is ambiguous across <n> elements`                           | `resolveRendered`       |
-| `Interactive target "<name>" could not be resolved`                                      | `resolveRendered`       |
-| `Interactive target "<name>" is unreachable after scrolling`                             | `resolveAccessible`     |
-| `Interactive target "<name>" is not reachable inside "<region>"`                         | `clickAccessibleWithin` |
-| `Interactive target "<name>" is ambiguous across <n> elements inside "<region>"`         | `clickAccessibleWithin` |
-| `Interactive target "<name>" could not be resolved inside "<region>"`                    | `clickAccessibleWithin` |
-| `Native disclosure "<name>" is not visible and focus-reachable`                          | `clickDisclosure`       |
-| `Native disclosure "<name>" is ambiguous across <n> elements`                            | `clickDisclosure`       |
-| `Native disclosure "<name>" could not be resolved`                                       | `clickDisclosure`       |
-| `Interactive target "<name>" is not reachable through forward Tab traversal: <trail>`    | `traverseAccessible`    |
-| `Named region "<name>" is not visible`                                                   | `readPerception`        |
-| `Named region "<name>" is ambiguous across <n> elements`                                 | `readPerception`        |
-| `Named region "<name>" could not be resolved`                                            | `readPerception`        |
-| `Interactive target "<name>" does not carry a value`                                     | `readValue`             |
-| `Computed foreground color is unavailable`                                               | `readContrast`          |
-| `Computed background color is unavailable`                                               | `readContrast`          |
-| `Tester pane is unavailable for a capture`                                               | `stagePane`             |
-| `Tester pane rendered <w>x<h> for a <w>x<h> viewport`                                    | `stagePane`             |
-| `Capture frame at <path> never settled after <n> restagings: <h> over a <h> pane`        | `captureFrame`          |
-| `Capture frame was written to <path> where <path> was asked for`                         | `captureFrame`          |
-| `Capture frame at <path> is not the one this run shot`                                   | `captureFrame`          |
-| `Capture frame at <path> could not be read`                                              | `readFrame`             |
-| `Capture frame at <path> is not an image this browser decodes`                           | `readFrame`             |
-| `Capture frame at <path> cannot be measured without a 2D canvas`                         | `readFrame`             |
-| `Capture variant "<name>" is not registered`                                             | `createPortfolio`       |
-| `Capture state "<state>" is not registered`                                              | `place`                 |
-| `Capture state "<state>" is already placed`                                              | `place`                 |
-| `IndexedDB database "<name>" could not be deleted`                                       | `removeDatabase`        |
-| `IndexedDB database "<name>" is blocked by an open connection`                           | `removeDatabase`        |
-| `Key sequence "<keys>" was sent with nothing focused`                                    | `pressKeys`             |
-| `Condition "<subject>" did not hold within <n>ms (waited <n>ms) (last states: <states>)` | `waitForState`          |
-| `Animation subject is not connected`                                                     | `waitForAnimations`     |
-| `Animation "<subject>" did not settle within <n>ms (waited <n>ms): <animations>`         | `waitForAnimations`     |
-| `Class census walked no element`                                                         | `readCensus`            |
-| `Contrast control cannot straddle the bar <bar>`                                         | `buildContrast`         |
-| `Access is denied for <operation> "<key>"`                                               | `buildDenial`           |
-| `No room is left for <key>`                                                              | `createStorage`         |
-| `Storage quota must be a non-negative integer`                                           | `createStorage`         |
-| `Statechart harness mounted no transition`                                               | `createHarness`         |
-| `Statechart harness carries no status`                                                   | `status`                |
+| Voice                                                                                    | Thrown by                 |
+| ---------------------------------------------------------------------------------------- | ------------------------- |
+| `No interactive element has the accessible name "<name>"`                                | `resolveRendered`         |
+| `Interactive target "<name>" is not visible and focus-reachable`                         | `resolveRendered`         |
+| `Interactive target "<name>" is ambiguous across <n> elements`                           | `resolveRendered`         |
+| `Interactive target "<name>" could not be resolved`                                      | `resolveRendered`         |
+| `Interactive target "<name>" is unreachable after scrolling`                             | `resolveAccessible`       |
+| `Interactive target "<name>" is not reachable inside "<region>"`                         | `resolveAccessibleWithin` |
+| `Interactive target "<name>" is ambiguous across <n> elements inside "<region>"`         | `resolveAccessibleWithin` |
+| `Interactive target "<name>" could not be resolved inside "<region>"`                    | `resolveAccessibleWithin` |
+| `Native disclosure "<name>" is not visible and focus-reachable`                          | `clickDisclosure`         |
+| `Native disclosure "<name>" is ambiguous across <n> elements`                            | `clickDisclosure`         |
+| `Native disclosure "<name>" could not be resolved`                                       | `clickDisclosure`         |
+| `Interactive target "<name>" is not reachable through forward Tab traversal: <trail>`    | `driveTraversal`          |
+| `Named region "<name>" is not visible`                                                   | `readPerception`          |
+| `Named region "<name>" is ambiguous across <n> elements`                                 | `readPerception`          |
+| `Named region "<name>" could not be resolved`                                            | `readPerception`          |
+| `Interactive target "<name>" does not carry a value`                                     | `readValue`               |
+| `Computed foreground color is unavailable`                                               | `readContrast`            |
+| `Computed background color is unavailable`                                               | `readContrast`            |
+| `Tester pane is unavailable for a capture`                                               | `stagePane`               |
+| `Tester pane rendered <w>x<h> for a <w>x<h> viewport`                                    | `stagePane`               |
+| `Capture frame at <path> never settled after <n> restagings: <h> over a <h> pane`        | `captureFrame`            |
+| `Capture frame was written to <path> where <path> was asked for`                         | `captureFrame`            |
+| `Capture frame at <path> is not the one this run shot`                                   | `captureFrame`            |
+| `Capture frame at <path> could not be read`                                              | `readFrame`               |
+| `Capture frame at <path> is not an image this browser decodes`                           | `readFrame`               |
+| `Capture frame at <path> is not an image this browser decodes: <w>x<h> device pixels`    | `readFrame`               |
+| `Capture frame at <path> cannot be measured without a 2D canvas`                         | `readFrame`               |
+| `Capture variant "<name>" is not registered`                                             | `createPortfolio`         |
+| `Capture state "<state>" is not registered`                                              | `place`                   |
+| `Capture state "<state>" is already placed`                                              | `place`                   |
+| `IndexedDB database "<name>" could not be deleted`                                       | `removeDatabase`          |
+| `IndexedDB database "<name>" is blocked by an open connection`                           | `removeDatabase`          |
+| `Key sequence "<keys>" was sent with nothing focused`                                    | `pressKeys`               |
+| `Condition "<subject>" did not hold within <n>ms (waited <n>ms) (last states: <states>)` | `waitForState`            |
+| `Animation subject is not connected`                                                     | `waitForAnimations`       |
+| `Animation "<subject>" did not settle within <n>ms (waited <n>ms): <animations>`         | `waitForAnimations`       |
+| `Class census walked no element`                                                         | `readCensus`              |
+| `Contrast control cannot straddle the bar <bar>`                                         | `buildContrast`           |
+| `Access is denied for <operation> "<key>"`                                               | `buildDenial`             |
+| `No room is left for <key>`                                                              | `createStorage`           |
+| `Storage quota must be a non-negative integer`                                           | `createStorage`           |
+| `Statechart harness mounted no transition`                                               | `createHarness`           |
+| `Statechart harness carries no status`                                                   | `status`                  |
 
 Some of those rows are not plain `Error` messages. `buildDenial` returns a `DOMException` named
 `SecurityError`, `createStorage` raises that one from every operation the permission withholds and a
@@ -1066,9 +1156,27 @@ disk disagrees with the bytes the provider handed back — which a provider that
 never produces, so the suite proves that comparison discriminates with a planted file rather than by
 reaching the refusal. `Capture frame at <path> cannot be measured without a 2D canvas` is narrowing
 of the same kind: a canvas allocated for this reading and asked for no other context type hands one
-back. `readFrame`'s other two refusals are driven, by a path holding no file and by a file holding
-no image, and so is `Capture frame at <path> never settled after <n> restagings`, by a fixture whose
-full-height panel grows with every pane the capture stages.
+back. The remaining refusals of the `readFrame` function are driven, by a path holding no file, by a
+file holding no image, and by a PNG header over no image data, and so is
+`Capture frame at <path> never settled after <n> restagings`, by a fixture whose full-height panel
+grows with every pane the capture stages.
+
+The pointer, pseudo-element, and media helpers add the following voices.
+
+| Voice                                                         | Thrown by      |
+| ------------------------------------------------------------- | -------------- |
+| `Browser provider exposes no DevTools session`                | `sendProtocol` |
+| `Pointer is already held at <x>x<y>`                          | `driveHold`    |
+| `Interactive target "<name>" did not enter the pressed state` | `driveHold`    |
+| `Pseudo-element "<pseudo>" must start with "::"`              | `readStyle`    |
+| `Pseudo-element "<pseudo>" is not one this engine exposes`    | `readStyle`    |
+| `Media emulation was staged with nothing to emulate`          | `stageMedia`   |
+| `Media emulation did not reach the tester: <query>`           | `stageMedia`   |
+| `Media emulation did not clear from the tester`               | `releaseMedia` |
+
+The resolver's absent, gated, ambiguous, and unreachable voices stay unchanged. The DevTools-session
+and media-delivery refusals guard provider failures the managed Chromium suite doesn't induce.
+The suite exercises real delivery rather than substituting a provider that manufactures a failure.
 
 ### Refusals outside the journey layer
 
@@ -1356,13 +1464,22 @@ These hold across `src/core`, `src/browser`, `src/server`, and this guide.
     element, the `hidden` attribute, a hidden input, and a `display` or `visibility` that takes it
     off the page. `isReachable` reads geometry, and adds connectedness, a visibility check that
     honours opacity, a non-zero box, the sequential focus order, `:disabled` and `aria-disabled`, and
-    the `[inert]` ancestor. A control clipped to a
-    zero-size rectangle is the case that separates them: the accessibility tree still announces it,
-    so `isRendered` accepts it and `isReachable` refuses it. `isReachable` is the one reachability
-    filter the layer applies — `resolveRendered`, `clickAccessibleWithin`, and `clickDisclosure` each
-    narrow their own candidates and then keep the ones it accepts — so a journey meets one rule
-    rather than near-copies of it. Neither asks about the viewport; `resolveAccessible` scrolls a
-    wholly off-viewport target into view and measures that separately with `isOutsideViewport`.
+    the `[inert]` ancestor. It adds one reading the element's own facts cannot carry: an open modal
+    dialog. A shown `[aria-modal="true"]` element that does not contain the subject refuses it,
+    because a pointer, a Tab, and a reader honouring that attribute all stop at the dialog while the
+    covered control stays connected, laid out, and focusable. The dialog is put through `isRendered`,
+    so a drawer parked at `visibility: hidden` excludes nothing, and containment follows the flat
+    tree, so the innermost dialog rules and a host it holds carries its shadow content with it.
+    Applying that inside the predicate is what keeps the resolver, the ambiguity count, the Tab
+    trail, and every acting verb agreeing with the person in front of the dialog, and it is what
+    takes away the name splitting a consumer writes to keep a covered control out of the count. A
+    control clipped to a zero-size rectangle is the case that separates them: the accessibility tree
+    still announces it, so `isRendered` accepts it and `isReachable` refuses it. `isReachable` is the
+    one reachability filter the layer applies — `resolveRendered`, `clickAccessibleWithin`, and
+    `clickDisclosure` each narrow their own candidates and then keep the ones it accepts — so a
+    journey meets one rule rather than near-copies of it. Neither asks about the viewport;
+    `resolveAccessible` scrolls a wholly off-viewport target into view and measures that separately
+    with `isOutsideViewport`.
     `readHit` reads beside that pair rather than filtering with it. It hit-tests one point — the
     element's own bounding-box centre — which is how it sees what neither predicate can: a cover
     over a control they both accept, and a wrapped inline target whose centre falls between its line
@@ -1392,19 +1509,25 @@ These hold across `src/core`, `src/browser`, `src/server`, and this guide.
     `Tester pane rendered <w>x<h> for a <w>x<h> viewport` rather than writing a wrong frame. The
     coupling therefore fails loudly, and the version this rule names moves with the fix instead of a
     suite shipping thumbnails nobody inspects. The same layout decides what a frame covers: the
-    provider shoots the tester's body in the top-level page's coordinates, so `captureFrame` stages
-    the pane again at the document's own height wherever the document outruns the declared one, and
-    a frame is neither shorter nor taller than the document it photographs. That height is
+    provider shoots the tester's body in the top-level page's coordinates, so the `captureFrame`
+    function stages the pane again at the document's own height wherever the document outruns the
+    declared one, and a page frame is neither shorter nor taller than the document it photographs.
+    That height is
     `measureContent`, the content's own edge rounded up, rather than the body's box: the box is the
     larger of the content and the pane, so a taller pane stretches it and a capture cannot read its
     way back down. The edge is read again after every staging, because a rule bound to the viewport
     height lays the document out taller against the taller pane, and each staging carries the growth
     the one before it produced so a converging document lands on its fixed point rather than
     creeping toward it. The re-reading is bounded by `CAPTURE_STAGINGS`, and a document still
-    growing at that bound is refused rather than photographed at a stale height. What the capture borrows it gives back —
-    `releasePane` returns the tester to the viewport it held before the staging, so the variant a
-    frame was shot at belongs to that frame alone, and a suite that wants a size of its own calls
-    `page.viewport` rather than this pair.
+    growing at that bound is refused rather than photographed at a stale height. An element frame
+    keeps the declared pane unless its element is taller, and offsets the calling tester frame only
+    as far as brings the element inside the runner's window. What
+    the capture borrows it gives back: the `releasePane` function returns the tester to the viewport
+    it held before the staging, the capture then restores the tester's scroll position, even where
+    the release rejects, and it restores the offset frame's
+    `style` attribute as soon as the screenshot settles. So the variant a frame was shot at belongs
+    to that frame alone, and a suite that wants a size of its own calls the `page.viewport` method
+    rather than this pair.
 19. **The statechart harness is test-side, and the markup is its whole contract.** A page cannot
     import this package. `@orkestrel/test` is a development dependency, its browser entry imports
     `vitest/browser` at module scope, and that import throws outside Browser Mode — so an
@@ -1536,6 +1659,18 @@ or when a consumer appears the ruling did not consider.
 | A generated or published harness page                                                            | Refused | Which transitions a surface owes, where that page is deep-linked, and whether it ships to anyone are product decisions, and framework code stops before them. A page hosting a harness would also have to import this package, which rule 19 rules out: the browser entry imports `vitest/browser` at module scope. The mechanism ships and the page does not.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | A framework-class disclosure settle                                                              | Refused | A helper that waits for a named element to carry one class and not two others encodes one framework's transition vocabulary, which is that framework's policy rather than a mechanism. `waitForState` waits on what the control announces and `waitForAnimations` waits on the paint itself, and between them they answer the question the class poll was asked. A surface announcing nothing is the finding.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 
+The journey additions have these candidate rulings.
+
+| Candidate                       | Ruling  | Why                                                                                                                                                                                                                                                                                                           |
+| ------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A hover verb                    | Ships   | `hoverAccessible` adds exact role/name resolution and the journey's reachability boundary to the provider's hover primitive.                                                                                                                                                                                  |
+| A pointer hold                  | Ships   | `holdAccessible` composes resolution, tester-scale mapping, a trusted press, and a pressed-state read-back through `driveHold`; `holdAccessibleWithin` resolves inside a named region and drives the same hold. `releasePointer` releases the hold and clears hover. Veneer's Button consumes the held paint. |
+| A pseudo-element style read     | Ships   | The third argument of `readStyle` and `readPixels` selects another subject of the same CSSOM reading. A separate reader would duplicate that operation.                                                                                                                                                       |
+| A medium emulation              | Ships   | `stageMedia` bounds the axes through `MediaOptions`, reads back `print: true`, either `motion` value, and either `forced` value, and pairs with `releaseMedia` for teardown. A `print: false` stage is sent and followed by a frame wait without a read-back.                                                 |
+| A DevTools command door         | Ships   | `sendProtocol` centralizes the unchecked provider boundary shared by pointer and media operations. The scale control consumes it directly.                                                                                                                                                                    |
+| A general media-feature map     | Refused | The consumer needs print, motion, and forced colours. A free-form map adds an unbounded contract without a consumer.                                                                                                                                                                                          |
+| A scoped hold taking a callback | Refused | The layer already uses stage-and-release pairs. An `afterEach` hook owns release after a failed test without a second lifecycle form.                                                                                                                                                                         |
+
 `ScratchInterface`'s own members were ruled the same way, and coherence rather than demand decided
 them. `ensure` ships because it is the one member that produces an empty directory — `write` always
 creates a file. `names` and `link` ship because a fixture that seeds a tree has to list it and to
@@ -1558,6 +1693,50 @@ peer, protocol fixture, and domain builder stays in the package that owns it.
 A shipped helper can still decline the question it looks like it answers. Each bound here belongs to
 the helper rather than to the host, and each names what to reach for instead.
 
+- **`holdAccessible` maps through the tester iframe's painted scale and reads `:active` back.** It
+  presses the control's centre and releases before refusing a missed press. If that release also
+  rejects, the missed-press refusal carries it as its cause. That path can't be driven from inert
+  input against a conforming engine, because the marker is built from the coordinates the press
+  used; it is covered by review. The measured layout is a single accessible, uniformly scaled tester
+  iframe. A covered centre or unsupported geometry can refuse even when the resolver accepts the
+  target. The verb inherits the resolver's focus reachability conditions.
+- **`releasePointer` parks the pointer outside the page.** It releases at the recorded point first,
+  which can produce a click. It then clears hover by moving to (-1, -1) in the runner page's
+  coordinates, one pixel above and to the left of that page's viewport. The browser hit-tests
+  nothing outside the viewport, so no element takes a `mouseover` event or hover paint from the
+  parked pointer until the next pointer verb. This holds even where a staging, scroll, or offset
+  lays content over the park point. Register it with `afterEach` before a hover
+  or hold. A second release sends no button-up event. Holds must not overlap. A rejected press
+  leaves no marker. A rejected release keeps the marker for a retry and still attempts the park. If
+  that park also rejects, the park's error surfaces with the release rejection attached in the
+  aggregate's errors; the park rejection is its cause.
+- **`stageMedia` overrides the provider page, and `releaseMedia` restores the first stage's
+  readings.** Pin a base with `{ motion: true }` rather than assuming the host prefers motion.
+  `motion: false` stages reduced motion; `print: true` stages print, and `print: false` stages
+  screen; `forced: true` stages active forced colours, and `forced: false` stages none. An omitted
+  print, motion, or forced axis keeps its effective reading, as does `prefers-color-scheme`. Any
+  other emulated feature the provider configured is cleared. An empty `{}`
+  refuses. Each staged query has a 1000 ms read-back budget with a 10 ms poll interval; refusal
+  restores the carried pre-call readings before throwing and can take two budgets. A restoration
+  failure is attached as the refusal's cause. The read-back exhaustion path can't be driven from
+  inert input against a conforming engine; its restoration is covered by review and by the shared
+  payload code, not by a case. The first stage records print, reduced motion, dark colour scheme,
+  and forced colours on the tester root under `MEDIA_STAGE`, as a bit string in that order (`1` for
+  a match, `0` otherwise). Later stages keep that marker. Release restores those readings as
+  explicit emulation rather than removing every override, waits per axis for its recorded value, and
+  removes the marker. A release whose wait exhausts keeps `MEDIA_STAGE` on the tester root, so the
+  next `releaseMedia` retries from the same recorded readings. A release with nothing staged clears
+  every override and compares readings taken strictly after the reset until they are stable.
+  Stability doesn't prove the engine's own baseline. Each release read-back has a 1000 ms budget and
+  waits for a frame per poll, with 10 ms between polls. The budget is checked between polls, so a
+  frame that never paints is not bounded by it. Media scopes must not overlap. The browser project
+  runs files serially.
+- **`readStyle` refuses a pseudo argument rather than ignoring it.** The argument must start with
+  `::` before the engine's selector-support check runs. A supported pseudo-element with no value for
+  the requested property still reads as an empty string. `readPixels` uses the same guard.
+- **`sendProtocol` reaches a Chromium-family provider alone.** It needs the provider's DevTools
+  session, passes the named command and parameters through, and discards the response. Browser
+  termination cannot promise cleanup. Edge observations belong to a separate run.
 - **`parseCSSColor` resolves an undeclared token to the inherited color.** A `var()` naming a custom
   property nothing declares is not a parse failure: the cascade accepts it and computes the
   inherited color, so `parseCSSColor('var(--absent)')` hands back channels rather than `undefined`.
@@ -1597,6 +1776,13 @@ the helper rather than to the host, and each names what to reach for instead.
   subject: a host the document does not lay out takes the element off the page, and both predicates
   refuse it. Read a `true` for a shadow subject as the element's own answer, and ask the host
   separately where an ancestor attribute is the subject.
+- **`isReachable` finds an open modal through the `aria-modal` attribute in the element's own
+  document.** Two arrangements carry no such attribute there, and each leaves the page behind it
+  reachable: a native `<dialog>` opened with `showModal`, which a browser makes modal without
+  marking it, and a dialog declared inside a shadow tree, which a document query does not return.
+  Containment itself does cross a boundary, because the subject's host chain is judged beside the
+  subject, so a dialog holding a host holds that host's shadow content too. Read `:modal` or the
+  dialog's own root where a native or shadow-declared dialog is the subject.
 - **`waitForAnimations` waits on the animations a browser reports as running.** A finished animation
   filling its target stays in the list and is already at rest, a paused one is at rest too and
   nothing here resumes it, and an animation declaring infinite iterations never finishes. Each is
@@ -2715,6 +2901,81 @@ await traverseAccessible('Evaluate')
 readPerception('Run') // one visible named region, whitespace collapsed, hidden-but-read text kept
 ```
 
+### Hold a control and read the pressed paint
+
+Register pointer cleanup before a test can fail. This fixture declares `padding-top: 16px` on its
+`Apply` button and `32px` under `:active`. Read the paint while the button is held, then release it.
+
+```ts
+import {
+	holdAccessible,
+	readPixels,
+	releasePointer,
+	resolveAccessible,
+} from '@orkestrel/test/browser'
+import { afterEach } from 'vitest'
+
+afterEach(releasePointer)
+const button = resolveAccessible('button', 'Apply')
+readPixels(button, 'padding-top') // 16
+await holdAccessible('button', 'Apply')
+readPixels(button, 'padding-top') // 32
+await releasePointer()
+readPixels(button, 'padding-top') // 16
+```
+
+Where a twin elsewhere on the page carries the same name, hold the one inside a named region with
+`holdAccessibleWithin('Ledger', 'button', 'Apply')`, which composes `resolveAccessibleWithin` with
+`driveHold`; `traverseAccessibleWithin` composes the same resolver with `driveTraversal`, and each
+refuses before it sends any input.
+
+### Read a pseudo-element's paint
+
+This fixture declares `padding-top: 0` on its `Marked` button and `7px` on its generated `::after`
+pseudo-element. Keep the element reading beside the pseudo reading so dropping the argument fails.
+
+```ts
+import { readPixels, readStyle, resolveAccessible } from '@orkestrel/test/browser'
+
+const button = resolveAccessible('Marked')
+readStyle(button, 'padding-top', '::after') // '7px'
+readPixels(button, 'padding-top', '::after') // 7
+readStyle(button, 'padding-top') // '0px'
+```
+
+### Emulate reduced motion and print
+
+This fixture's `Media` button declares `padding-top: 1px`, `2px` under reduced motion, and `3px`
+under print. Pin the base preference, then read each staged axis. Stage the inverse of the observed
+motion reading before release so the restore comparison can fail. The initial unstaged release
+clears overrides and waits for stable readings. The final release returns the readings observed
+before the first stage, kept as explicit emulation. A further unstaged release clears that emulation.
+
+```ts
+import { readPixels, releaseMedia, resolveAccessible, stageMedia } from '@orkestrel/test/browser'
+import { afterEach } from 'vitest'
+
+afterEach(releaseMedia)
+await releaseMedia()
+const reduced = matchMedia('(prefers-reduced-motion: reduce)').matches
+const button = resolveAccessible('Media')
+await stageMedia({ motion: true })
+readPixels(button, 'padding-top') // 1
+await stageMedia({ motion: false })
+readPixels(button, 'padding-top') // 2
+matchMedia('(prefers-reduced-motion: reduce)').matches // true
+await stageMedia({ motion: reduced })
+matchMedia('(prefers-reduced-motion: reduce)').matches === !reduced // true
+readPixels(button, 'padding-top') === (reduced ? 1 : 2) // true
+await stageMedia({ print: true })
+readPixels(button, 'padding-top') // 3
+matchMedia('print').matches // true
+await releaseMedia()
+matchMedia('print').matches // false
+matchMedia('(prefers-reduced-motion: reduce)').matches === reduced // true
+readPixels(button, 'padding-top') === (reduced ? 2 : 1) // true
+```
+
 ### Send a key to what holds focus
 
 Bring focus about through a verb, then send the sequence. A key sent while the document body holds
@@ -3210,7 +3471,13 @@ The second pair is what the reading exists for. Every box a document exposes —
 content and the pane, so a caller that has staged too tall a pane reads that pane back and cannot
 descend from it. `measureContent` walks the elements inside the body instead, so it descends. Where
 the document is laid out against the viewport, it moves with the viewport and reports what the
-reflow produced rather than what the pane claimed.
+reflow produced rather than what the pane claimed, except inside a frame that clips its overflow,
+where a viewport-bound child ends at the frame's clip edge. The `clipsOverflow` helper names the
+frames that count, and the `readClipEdge` helper reads each frame's clip edge. An `overflow-y`
+value of the `hidden` keyword, the `auto` keyword, or the `scroll` keyword ends at the padding box.
+The `clip` keyword and a paint containment over a
+`visible` overflow end at the box the frame's `overflow-clip-margin` value selects, the padding box
+by default, expanded by the margin the `readClipMargin` helper reads.
 
 ### Read a written frame back
 
@@ -3332,11 +3599,16 @@ Each entry names the contracts its file proves. The test names carry the cases.
   that stays there, and `isOutsideViewport` takes a rectangle wholly beyond each edge and one
   straddling an edge. `isReachable` takes a plain control and each condition it drops, a control the
   document no longer holds, a focusable SVG against an element from a foreign namespace, and the
-  refused summary that proves it is the one filter the acting verbs apply; `isRendered` takes each
-  removal a browser honours and, as the split from `isReachable`, a zero-size announced control. Each
-  predicate also takes a subject inside an open and a closed shadow root beside a host that carries
-  its own ancestor attribute — `[inert]` for one and `aria-hidden` for the other — and a host the flat
-  tree does not lay out, which pins where the boundary falls for each.
+  refused summary that proves it is the one filter the acting verbs apply. It takes the open modal
+  dialog through the readings that fix it: the masthead control the dialog leaves behind against the
+  same name inside it, which resolves and traverses unambiguously; the control a plain dialog, a
+  folded modal, and a blanked modal each leave standing, as the control; the nested dialog and the
+  shadow subject that pin containment on the flat tree; and the native `showModal` dialog and the
+  shadow-declared modal it reports nothing about, which is the bound the guide states. `isRendered`
+  takes each removal a browser honours and, as the split from `isReachable`, a zero-size announced
+  control. Each predicate also takes a subject inside an open and a closed shadow root beside a host
+  that carries its own ancestor attribute — `[inert]` for one and `aria-hidden` for the other — and a
+  host the flat tree does not lay out, which pins where the boundary falls for each.
   `pressKeys` takes a sequence reaching the control a traversal focused and, as the control, the same
   sequence refused while the document body holds focus with no keystroke recorded. `waitForState`
   takes a state a timer flips after the act, a node replaced mid-wait and still resolved by role and
@@ -3434,10 +3706,32 @@ Each entry names the contracts its file proves. The test names carry the cases.
   read — 1322, then 1561 — and its frame lands on 1800, which is the fixed point written out rather
   than read back from the capture that staged it. The same panel uncapped grows with every pane and
   reaches the refusal, whose written-out restaging bound reddens when the source's bound moves and
-  whose pane and viewport are handed back anyway. `readFrame` takes a written frame's size and
-  floor, read a second way through the cascade's own answer for the same canvas, a bottom row split
-  between two colors reported as no floor at all, a path holding no file, and a file holding no
-  image. `readCascade` takes class tokens collected from plain and grouped rules and only real ones;
+  whose pane and viewport are handed back anyway. An element frame takes a fixed `30vh` panel whose
+  top lies past the runner's window, shot from a scrolled tester, whose frame is 30% of the declared
+  height on the panel's own color with the scroll handed back; an element below both the pane and
+  the window, whole on the document's floor with the scroll handed back; a `50vh` element and a
+  `30vh` element below the fold, at the declared pane rather than a grown one; an element taller
+  than the pane, in a pane of its own height; an element that outgrows every pane, refused with the
+  pane and the scroll handed back; a second tester frame the offset leaves in place; and a frame
+  carrying no `style` attribute, handed back without one. After the `releasePointer` function, an
+  element frame takes no `mouseover` event for an element inside the window, which also takes no `scroll` event;
+  for a flush-left element the scroll brings to the top, one the offset brings to the left edge, and
+  one too large for the window; for an element past both window edges, whose frame has the
+  element's size; for an element touching the origin and one filling the window; across a scroll
+  the staging clamps, with the scroll handed back; and for an `svg` element in the shadow tree of a
+  fixed host and a fixed `svg` element under a containing-block ancestor. A hover placed after
+  staging on an element at the tester's top-left corner stays in the frame. The `computeOffset`
+  function takes an element inside the window, one touching the origin or starting above it, one
+  filling the window, an element past the bottom edge, a fractional bottom edge rounded up, a
+  fractional top and a fractional left each moved only as far as the window start, a box already
+  ending inside a fractional window left where it is, an element past the right edge,
+  one past both edges, and an element too large for the window.
+  The `readFrame` function takes a written
+  frame's size and floor, read a second way through the cascade's own answer for the same canvas, a
+  bottom row split between two colors reported as no floor at all, a path holding no file,
+  a file holding no image and refused without a size, and a PNG header over no image data, refused
+  with the size the header declares. The `readCascade` function takes class tokens collected from
+  plain and grouped rules and only real ones;
   `readRows` takes a row joined from its own text nodes rather than from run-together content, and
   an empty list; `extractOrphans` takes a child class rendered outside its container with a nested
   one left alone, nothing reported when every child sits inside one, and, as the control, an element