@orkestrel/test 0.0.10 → 0.0.12

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

@@ -1,5 +1,5 @@
 /**
- * The interactive ARIA roles a bare accessible name is searched across.
+ * Names the interactive ARIA roles a bare accessible name is searched across.
  *
  * @remarks
  * A person names a control, not a role, so the one-argument resolver searches every role a control
@@ -45,7 +45,7 @@ export declare function blendColor(front: Color, back: Color): Color;
 export declare function build<K extends keyof HTMLElementTagNameMap>(tag: K, options?: ElementOptions): HTMLElementTagNameMap[K];
 
 /**
- * The page a browser paints an unstyled document onto.
+ * Names the color a browser paints an unstyled document with.
  *
  * @remarks
  * This is the floor a backdrop walk ends on wherever the caller wants the browser's own canvas
@@ -55,23 +55,43 @@ export declare function build<K extends keyof HTMLElementTagNameMap>(tag: K, opt
 export declare const CANVAS_COLOR: Color;
 
 /**
- * The attribute marking the runner's tester pane, and the rule that sizes it, while a frame is
- * staged.
+ * Names the attribute marking the runner's tester pane, and the rule that sizes it, while a frame
+ * is staged.
  *
  * @remarks
  * `stagePane` writes it onto the pane and onto the stylesheet it appends, and `releasePane` finds
- * both by it. Nothing else reads it, so a document carrying it after a capture returned is a pane
- * that was never released.
+ * both by it. The stylesheet's value is the viewport the tester had before the first staging, in
+ * `<width>x<height>` form, which is what `releasePane` hands back. Nothing else reads it, so a
+ * document carrying it after a capture returned is a pane that was never released.
  */
 export declare const CAPTURE_PANE = "data-capture-pane";
 
+/**
+ * Bounds the restagings one capture takes before it refuses a document whose height never settles.
+ *
+ * @remarks
+ * `captureFrame` stages the pane at the content edge `measureContent` reads, and a rule bound to
+ * the viewport height lays that document out taller against the taller pane, so the edge has to be
+ * read again after every staging. The re-reading stops when the pane and the edge agree, and a rule
+ * that adds height with every pane never reaches that point, so the re-reading is bounded here and
+ * the shot is refused rather than taken at a height that is already stale.
+ *
+ * The bound is the measured need plus one. A document holding half the pane plus a fixed block
+ * settles in two restagings, because the second carries the growth the first produced and lands on
+ * the fixed point; a document whose growth is capped part way settles in three, because it takes
+ * one restaging past the cap before it comes back down to the edge. Nothing measured needs a
+ * fourth, so a fourth is the headroom that keeps a settling document off the refusal.
+ */
+export declare const CAPTURE_STAGINGS = 4;
+
 /**
  * Shoots one frame at one viewport size and proves the file on disk holds this run's bytes.
  *
  * @param options - The path to write, the viewport to shoot at, and the element to shoot.
  * @returns The absolute path of the written frame, after it has been read back and matched.
- * @throws Thrown when the pane cannot be staged, when the provider wrote the frame somewhere else,
- * and when the bytes on disk are not the ones this shot produced.
+ * @throws Thrown when the pane cannot be staged, when the document's height never settles under
+ * {@link CAPTURE_STAGINGS} restagings, when the provider wrote the frame somewhere else, and when
+ * the bytes on disk are not the ones this shot produced.
  *
  * @remarks
  * The path a screenshot call returns is the path it meant to write, so it is not evidence a file
@@ -81,8 +101,41 @@ export declare const CAPTURE_PANE = "data-capture-pane";
  * path, so the two are compared by the segments that survive resolving `.` and `..` lexically — the
  * refusal is what a provider resolving that path against a different base would trip.
  *
+ * The frame covers the whole document at `options.width`, whatever `options.height` is. The
+ * provider shoots the tester's body in the top-level page's own coordinates, so a document taller
+ * than the pane is painted for the pane's height and the rows below it are the runner's page rather
+ * than the document — a frame that reads as the surface down to the fold and as bare canvas after
+ * it. The document is therefore laid out at the declared viewport first and, where it is taller
+ * than that, the pane is staged again at the height the document needs, for the shot alone.
+ *
+ * That height is {@link measureContent}, never less than `options.height`, because the declared
+ * viewport is the smallest frame a variant asks for. The reading is the content's own edge rather
+ * than the body's box: the box is the larger of the content and the pane, so it stretches with
+ * every pane staged over it and a capture that staged too tall a pane could not read its way back
+ * down. Rounding up is what covers a body ending part way through a row, which the box does and an
+ * integer scroll height does not.
+ *
+ * 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, so a surface built out of those photographs as its scrolled-open self rather than as one
+ * screen, and the reading taken before that staging is stale by exactly what the reflow added.
+ * Restaging at the edge alone converges on such a document without arriving: each staging closes
+ * the same fraction of what is left, so a rule keeping half the pane reads 1322, 1561, 1681, and
+ * 1741 against a fixed point of 1800. Each staging therefore carries the growth the one before it
+ * produced — the pane is the edge plus that growth — which lands on the fixed point rather than
+ * creeping up to it. The first staging carries no growth, because nothing has grown yet, so a
+ * document of fixed content is staged at its own edge and shot there rather than at a pane the
+ * overshoot stretched.
+ *
+ * The re-reading stops when the pane and the edge agree, which is the pane the shot is taken at. A
+ * rule that adds height with every pane never reaches that point, so the re-reading is bounded by
+ * {@link CAPTURE_STAGINGS} and the shot is refused with
+ * `Capture frame at <path> never settled after <n> restagings: <h> over a <h> pane` rather than
+ * written at a height that is already wrong.
+ *
  * Omit `options.element` to shoot the whole page. The pane is staged for the frame and released
- * before this returns, on the failing path as well as the passing one.
+ * before this returns, on the failing path as well as the passing one, which hands the tester back
+ * the viewport it had before the first staging.
  *
  * @example
  * ```ts
@@ -91,17 +144,17 @@ export declare const CAPTURE_PANE = "data-capture-pane";
  */
 export declare function captureFrame(options: FrameOptions): Promise<string>;
 
-/** One theme-and-viewport pair a capture run renders. */
+/** Represents one theme-and-viewport pair a capture run renders. */
 export declare interface CaptureVariant {
-    /** The variant's name, which is the second half of every filename the run writes. */
+    /** Holds the variant's name, which is the second half of every filename the run writes. */
     readonly name: string;
-    /** The viewport width in pixels. */
+    /** Holds the viewport width in pixels. */
     readonly width: number;
-    /** The viewport height in pixels. */
+    /** Holds the viewport height in pixels. */
     readonly height: number;
     /**
-     * The document change this variant needs before the viewport is resized — a theme attribute, a
-     * density class, a language direction. Omit it when the variant is a viewport alone.
+     * Holds the document change this variant needs before the viewport is resized — a theme
+     * attribute, a density class, a language direction. Omit it when the variant is a viewport alone.
      */
     readonly apply?: () => void;
 }
@@ -191,7 +244,7 @@ export declare function clickAccessibleWithin(region: string, role: string, name
 export declare function clickDisclosure(name: string): Promise<void>;
 
 /**
- * One rendered color as straight sRGB channels and its alpha.
+ * Represents one rendered color as straight sRGB channels and its alpha.
  *
  * @remarks
  * The channels run 0–255 and the alpha runs 0–1, which is the shape a computed `rgb()` value already
@@ -200,33 +253,6 @@ export declare function clickDisclosure(name: string): Promise<void>;
  */
 export declare type Color = readonly [red: number, green: number, blue: number, alpha: number];
 
-/**
- * Determines whether two colors render the same, within the rounding a browser does.
- *
- * @param first - A CSS color expression or an already-parsed color.
- * @param second - A CSS color expression or an already-parsed color.
- * @returns `true` when every channel and the alpha agree within the tolerance; `false` otherwise,
- * including when either side names no readable color.
- *
- * @remarks
- * Each string side is resolved through {@link rgba}, so a keyword, a token reference, and the
- * `rgb()` the engine computes for either of them compare equal without a test converting anything
- * first. A side that resolves to nothing makes the answer `false` rather than a throw, because this
- * is a predicate.
- *
- * The tolerance is half a channel step on the 0–255 scale, and the alpha is scaled onto that same
- * range before it is compared, so one number covers both. Half a step is what a composite of
- * translucent layers and a `color-mix()` round trip actually drift by; anything a reader could see
- * is further than that and reports unequal.
- *
- * @example
- * ```ts
- * colorEqual('rebeccapurple', 'rgb(102, 51, 153)') // true
- * colorEqual('red', [0, 0, 255, 1]) // false
- * ```
- */
-export declare function colorEqual(first: string | Color, second: string | Color): boolean;
-
 /**
  * Sets one field's value and commits it, the way typing and then leaving the field does.
  *
@@ -246,52 +272,43 @@ export declare function colorEqual(first: string | Color, second: string | Color
 export declare function commitInput(element: HTMLInputElement | HTMLTextAreaElement, text: string): void;
 
 /**
- * The roles whose accessible name is the text a reader can see inside them.
+ * Computes the pattern that matches one accessible name a decorative glyph may sit beside.
  *
- * @remarks
- * `readName` reads an element in this list from its own rendered text, after every `aria-hidden`
- * descendant is dropped, and falls through to `title` for every other role.
- */
-export declare const CONTENT_ROLES: readonly string[];
-
-/**
- * Measures the WCAG 2.x contrast ratio between an element's computed text and background colors.
- *
- * @param element - The element whose rendered text contrast to measure.
- * @param floor - The opaque color the backdrop walk ends on. Omit it to refuse a stack the floor
- * would show through instead of assuming one.
- * @returns The relative-luminance contrast ratio.
- * @throws Thrown when the element exposes no computed foreground color, and — with `floor` omitted
- * — when the walk from the element upwards reaches no opaque layer.
+ * @param name - The exact accessible name a person reads, whitespace runs collapsed on the way in.
+ * @returns A pattern anchored at both ends, admitting a run of characters that are neither letters
+ * nor digits before the name and after it.
  *
  * @remarks
- * A transparent or translucent background resolves through the element's ancestors: every painted
- * layer from the element up to the first opaque one composites top-over-bottom onto that opaque
- * base, so a 3% surface tint reads as a tint over what shows through it rather than as a
- * full-strength paint. A translucent foreground then resolves against that effective background
- * before luminance is measured.
+ * A role query that includes hidden elements computes a name from the `aria-hidden` subtrees too,
+ * so an icon font's `::before` glyph joins the name a person never hears and an exact string never
+ * matches again. This pattern is what {@link resolveRendered} asks the hidden pass with, and its
+ * tolerance is bounded to what a glyph can be: a leading or trailing run carrying no letter and no
+ * digit. A hidden icon whose own content is a word still defeats it, and a name differing from the
+ * requested one by punctuation alone still satisfies it.
  *
- * With `floor` omitted, the walk from the target upwards must reach a fully opaque layer: the
- * measurement throws rather than assuming a white canvas wherever that canvas would still be part
- * of the answer. The refusal reads the alpha of the deepest layer {@link readLayers} collected, so
- * a chain that declares no background color at all, a chain painting only translucent layers, and a
- * chain deep enough for its composite to round to the canvas's own channels are refused alike,
- * because the number any of them produces is as much a report of the assumption as of the page.
- * Supply a floor wherever the caller knows what the stack sits on — a fragment mounted into a
- * painted host, or a document whose canvas is {@link CANVAS_COLOR} — and the composite is taken
- * over it rather than refused.
+ * That bound is affordable because the hidden pass chooses between two refusal voices and returns
+ * nothing. The visible pass decides which element a resolver returns, and it matches the exact
+ * string against the name the accessibility tree actually publishes.
  *
- * The element itself must expose a computed foreground color either way. A detached element exposes
- * none, and the measurement throws rather than guessing one.
+ * Pass this to a role query with `exact: true`. That flag is the engine's case-sensitivity switch
+ * as well as its exactness one, so a query carrying `exact: false` uppercases the computed name
+ * before testing a pattern against it and a lowercase letter in the requested name never matches.
  *
  * @example
  * ```ts
- * const container = render('<p style="background: #000; color: #fff">Ready</p>')
- * contrast(requireValue(container.firstElementChild)) // 21
- * contrast(requireValue(container.firstElementChild), CANVAS_COLOR) // 21, and never refuses
+ * computeNamePattern('Add building').test('\uF4FE Add building') // true
  * ```
  */
-export declare function contrast(element: Element, floor?: Color): number;
+export declare function computeNamePattern(name: string): RegExp;
+
+/**
+ * Names the roles whose accessible name is the text a reader can see inside them.
+ *
+ * @remarks
+ * `readName` reads an element in this list from its own rendered text, after every `aria-hidden`
+ * descendant is dropped, and falls through to `title` for every other role.
+ */
+export declare const CONTENT_ROLES: readonly string[];
 
 /**
  * Creates one console channel that records every call it receives and hands that call on unchanged.
@@ -479,7 +496,7 @@ export declare function describeFocus(element: Element): string;
 export declare function describeTree(element: Element): string;
 
 /**
- * Options for one built element.
+ * Configures one built element.
  *
  * @remarks
  * `classes` is written the way a `class` attribute is written — one space-separated string — so a
@@ -488,11 +505,11 @@ export declare function describeTree(element: Element): string;
  * with it.
  */
 export declare interface ElementOptions {
-    /** The class list, space-separated, exactly as a `class` attribute writes it. */
+    /** Holds the class list, space-separated, exactly as a `class` attribute writes it. */
     readonly classes?: string;
-    /** The text the element carries, set as text rather than parsed as markup. */
+    /** Holds the text the element carries, set as text rather than parsed as markup. */
     readonly text?: string;
-    /** Every attribute to set, keyed by attribute name. */
+    /** Holds every attribute to set, keyed by attribute name. */
     readonly attributes?: Readonly<Record<string, string>>;
 }
 
@@ -542,7 +559,34 @@ export declare function expandCaptures(states: readonly string[], variants: read
 export declare function extractOrphans(root: ParentNode, child: string, parent: string): readonly string[];
 
 /**
- * The role each `input` type carries.
+ * 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`.
+ *
+ * @param root - The subtree to sweep. A detached element and a `DocumentFragment` both work.
+ * @returns The `outerHTML` of each such element, in document order; an empty list when the markup
+ * declares no style of its own.
+ *
+ * @remarks
+ * These are the declarations the stylesheet never sees: an inline `style` attribute, wherever it
+ * sits, and a `<style>` element, whatever it holds. Nothing else counts. A class and a `data-*`
+ * attribute name something the cascade resolves, so neither is reported however unusual it looks;
+ * an inline `style` on a `<path>` inside an SVG is reported, because a namespace changes nothing
+ * about what an inline declaration is.
+ *
+ * A `style` attribute holding nothing but whitespace declares nothing, so it is not reported. A
+ * `DocumentFragment` root contributes its descendants alone, because it is not an `Element`; a
+ * `<style>` root and a root carrying an inline attribute are each reported, and an element that is a
+ * `<style>` element and carries an inline attribute too is reported once.
+ *
+ * @example
+ * ```ts
+ * extractStyles(container) // []
+ * ```
+ */
+export declare function extractStyles(root: ParentNode): readonly string[];
+
+/**
+ * Names the role each `input` type carries.
  *
  * @remarks
  * Membership is the contract. The map answers for `button`, `checkbox`, `email`, `number`,
@@ -599,8 +643,8 @@ export declare function findKeyframes(name: string): CSSKeyframesRule | undefine
  *
  * @remarks
  * This proves a declaration exists in the cascade at all, which is a different question from what an
- * element resolves to: {@link style} reads the winner, and a rule this finds may be overridden by
- * another. Assert on this where the subject is the stylesheet, and on `style` where the subject is
+ * element resolves to: {@link readStyle} reads the winner, and a rule this finds may be overridden by
+ * another. Assert on this where the subject is the stylesheet, and on `readStyle` where the subject is
  * the rendered result.
  *
  * The match is a substring, so `findRule('.card')` finds `.card`, `.card:hover`, and
@@ -614,7 +658,7 @@ export declare function findKeyframes(name: string): CSSKeyframesRule | undefine
 export declare function findRule(selector: string): CSSStyleRule | undefined;
 
 /**
- * What sequential keyboard navigation can reach, before disabled and unrendered elements go.
+ * Names what sequential keyboard navigation can reach, before disabled and unrendered elements go.
  *
  * @remarks
  * `describeFocus` queries this selector and then drops what a browser drops: an element the
@@ -624,20 +668,40 @@ export declare function findRule(selector: string): CSSStyleRule | undefined;
  */
 export declare const FOCUSABLE_SELECTOR = "a[href], area[href], button, input, select, summary, textarea, [tabindex]";
 
-/** Options for one captured frame. */
+/** Configures one captured frame. */
 export declare interface FrameOptions {
-    /** The frame's path, relative to the calling test file. */
+    /** Holds the frame's path, relative to the calling test file. */
     readonly path: string;
-    /** The viewport width in CSS pixels the frame is shot at. */
+    /** Holds the viewport width in CSS pixels the frame is shot at. */
     readonly width: number;
-    /** The viewport height in CSS pixels the frame is shot at. */
+    /** Holds the viewport height in CSS pixels the frame is shot at. */
     readonly height: number;
-    /** The element to shoot. Omit it to shoot the whole page. */
+    /** Holds the element to shoot. Omit it to shoot the whole page. */
     readonly element?: Element | undefined;
 }
 
 /**
- * The role a `th` carries for the header axis its `scope` names.
+ * Represents one written frame, read back from the file a capture produced.
+ *
+ * @remarks
+ * The floor is the frame's bottom row, because that row is where coverage shows: a frame shot at a
+ * pane shorter than the document ends on the runner's own canvas rather than on the document's
+ * background, and the two read as different colors. A row counts as one color only when every
+ * channel matches across it, alpha included, and `floor` names the three color channels of that one
+ * color in the `rgb(r, g, b)` form a computed style is written in, so a literal comparison,
+ * `parseColor`, and `matchesColor` all take it.
+ */
+export declare interface FrameReading {
+    /** Holds the frame's width in device pixels. */
+    readonly width: number;
+    /** Holds the frame's height in device pixels. */
+    readonly height: number;
+    /** Holds the single color the frame's bottom row paints; `undefined` where that row paints several. */
+    readonly floor: string | undefined;
+}
+
+/**
+ * Names the role a `th` carries for the header axis its `scope` names.
  *
  * @remarks
  * A header cell heads a column or a row, and this map answers for the `col` and `row` scopes that
@@ -647,7 +711,8 @@ export declare interface FrameOptions {
 export declare const HEADER_ROLES: Readonly<Record<string, string>>;
 
 /**
- * The role each listed tag carries in the accessibility tree when it declares none of its own.
+ * Names the role each listed tag carries in the accessibility tree when it declares none of its
+ * own.
  *
  * @remarks
  * Membership is the contract. The map answers for the sectioning elements `ARTICLE`, `ASIDE`,
@@ -672,7 +737,7 @@ export declare const IMPLICIT_ROLES: Readonly<Record<string, string>>;
  * Determines whether a rectangle lies wholly outside the browser viewport.
  *
  * @param rectangle - The measured client rectangle to inspect.
- * @returns `true` when no part of the rectangle intersects the viewport.
+ * @returns True if no part of the rectangle intersects the viewport; false otherwise.
  *
  * @example
  * ```ts
@@ -685,9 +750,9 @@ export declare function isOutsideViewport(rectangle: DOMRectReadOnly): boolean;
  * Determines whether a person can click one element where it currently sits.
  *
  * @param element - The element to judge.
- * @returns `true` when the element is connected, visible, laid out with a non-zero box, in the
+ * @returns True if the element is connected, visible, laid out with a non-zero box, in the
  * sequential focus order, neither disabled nor marked `aria-disabled="true"`, and outside every
- * `[inert]` subtree; `false` otherwise.
+ * `[inert]` subtree; false otherwise.
  *
  * @remarks
  * This is the one reachability filter the layer applies. `resolveRendered`, `clickAccessibleWithin`,
@@ -710,8 +775,7 @@ export declare function isReachable(element: Element): boolean;
  * Determines whether the accessibility tree presents one element at all.
  *
  * @param element - The element to judge.
- * @returns `false` when the element is hidden from assistive technology, from sight, or from both;
- * `true` otherwise.
+ * @returns True if the element is presented to assistive technology and to sight; false otherwise.
  *
  * @remarks
  * A control clipped to a zero-size rectangle is still announced, which is the whole point of that
@@ -734,7 +798,7 @@ export declare function isReachable(element: Element): boolean;
 export declare function isRendered(element: Element): boolean;
 
 /**
- * The record of one scenario: every step it took and everything the page said while it ran.
+ * Records one scenario: every step it took and everything the page said while it ran.
  *
  * @remarks
  * Recording is off until {@link JournalInterface.start} arms it, so a suite that never starts a
@@ -743,9 +807,9 @@ export declare function isRendered(element: Element): boolean;
  * journal that swallowed what it read would hide exactly the diagnostics it exists to keep.
  */
 export declare interface JournalInterface {
-    /** Every step recorded since the journal started, in the order it was taken; a snapshot. */
+    /** Lists every step recorded since the journal started, in the order it was taken; a snapshot. */
     readonly steps: readonly JournalStep[];
-    /** Every console line and uncaught failure the page emitted since it started; a snapshot. */
+    /** Lists every console line and uncaught failure the page emitted since it started; a snapshot. */
     readonly output: readonly string[];
     /**
      * Starts a fresh recording, dropping whatever the previous scenario left.
@@ -773,16 +837,75 @@ export declare interface JournalInterface {
     record(action: string, trigger: string, result: string): void;
 }
 
-/** One scripted step a journal recorded, and what the surface did about it. */
+/** Represents one scripted step a journal recorded, and what the surface did about it. */
 export declare interface JournalStep {
-    /** What the run did, as one verb. */
+    /** Names what the run did, as one verb. */
     readonly action: string;
-    /** The exact thing it did it to. */
+    /** Names the exact thing it did it to. */
     readonly trigger: string;
-    /** What was observed on the surface after the step landed. */
+    /** Holds what was observed on the surface after the step landed. */
     readonly result: string;
 }
 
+/**
+ * Determines whether two colors render the same, within the rounding a browser does.
+ *
+ * @param first - A CSS color expression or an already-parsed color.
+ * @param second - A CSS color expression or an already-parsed color.
+ * @returns True if every channel and the alpha agree within the tolerance; false otherwise,
+ * including when either side names no readable color.
+ *
+ * @remarks
+ * Each string side is resolved through {@link parseCSSColor}, so a keyword, a token reference, and the
+ * `rgb()` the engine computes for either of them compare equal without a test converting anything
+ * first. A side that resolves to nothing makes the answer `false` rather than a throw, because this
+ * is a predicate.
+ *
+ * The tolerance is half a channel step on the 0–255 scale, and the alpha is scaled onto that same
+ * range before it is compared, so one number covers both. Half a step is what a composite of
+ * translucent layers and a `color-mix()` round trip actually drift by; anything a reader could see
+ * is further than that and reports unequal.
+ *
+ * @example
+ * ```ts
+ * matchesColor('rebeccapurple', 'rgb(102, 51, 153)') // true
+ * matchesColor('red', [0, 0, 255, 1]) // false
+ * ```
+ */
+export declare function matchesColor(first: string | Color, second: string | Color): boolean;
+
+/**
+ * Measures the row the document's own content ends on, in document coordinates.
+ *
+ * @returns The content edge, rounded up to a whole row.
+ *
+ * @remarks
+ * The body's box is not the document's height: it is the larger of the content and the pane. A pane
+ * taller than the document stretches it, and `document.body.getBoundingClientRect()`,
+ * `body.scrollHeight`, `body.offsetHeight`, and `documentElement.scrollHeight` all read that pane
+ * back rather than the content under it. So a caller that has staged a pane taller than the
+ * document cannot find its way down again from any of them. This reading can, because it is taken
+ * over the elements inside the body rather than over the box around them: a document of fixed
+ * content answers the same number under a short pane and a tall one, and a document laid out
+ * against the viewport answers what that viewport actually laid out.
+ *
+ * Each element contributes its client rectangle's bottom edge in document coordinates plus its own
+ * bottom margin, which sits outside that rectangle, and the largest contribution wins. Taking the
+ * largest is what handles a collapsed margin without asking whether it collapsed: a child margin
+ * that collapses out through its parent is counted once, at the child, and one the parent's padding
+ * holds in is counted once, at the parent. The body's and the root's own bottom padding and margin
+ * sit under every child rather than beside them, so they are added after the walk.
+ *
+ * The sum is rounded up because a box can end part way through a row and a frame cannot hold part
+ * of one.
+ *
+ * @example
+ * ```ts
+ * const covered = measureContent()
+ * ```
+ */
+export declare function measureContent(): number;
+
 /**
  * Measures the WCAG 2.x contrast ratio between two opaque colors.
  *
@@ -823,8 +946,8 @@ export declare function measureLuminance(color: Color): number;
  * @remarks
  * What this buys is the composition, not the attachment: the `append` method returns `void`, and
  * this hands the element back, so it fits where an expression is expected. The {@link render} helper
- * returns its fixture through it, and the {@link rgba} helper probes through `mount(build('span'))`.
- * A bare `append` call breaks each of those call sites.
+ * returns its fixture through it, and the {@link parseCSSColor} helper probes through
+ * `mount(build('span'))`. A bare `append` call breaks each of those call sites.
  *
  * Being connected is what the attachment then buys: `getComputedStyle` resolves against the shipped
  * cascade, custom properties inherit from `:root`, and the element lays out a real box. A detached
@@ -866,39 +989,46 @@ export declare function mount<T extends Element>(element: T): T;
 export declare function parseColor(value: string): Color | undefined;
 
 /**
- * Reads one resolved CSS length as a number of pixels.
+ * Resolves any CSS color expression to straight sRGB channels, by asking the browser.
  *
- * @param element - The element whose resolved style to inspect.
- * @param property - The CSS property name, registered or custom.
- * @returns The leading numeric part of the resolved value, and `0` when it carries none.
+ * @param value - Any value the `color` property accepts: a keyword, a hex triple, a `var()`
+ * reference, a `color-mix()`, or an already-computed `rgb()`.
+ * @returns The resolved color's channels, or `undefined` when the CSSOM refuses the value or the
+ * computed result names no color {@link parseColor} speaks.
  *
  * @remarks
- * A resolved length is text with a unit — `'12px'` — so this reads the number in front of the unit
- * and discards the rest. The unit is not checked: the resolved value of a length is in pixels in
- * every case a browser hands back, and a property that resolves to something else is the caller's
- * mistake rather than this reader's.
+ * This is the live half of the pair {@link parseColor} opens. `parseColor` reads text and speaks
+ * only the computed syntaxes a cascade hands back; this stages a probe element, hands it to the real
+ * cascade, and reads back what the engine computed — which is the only way a keyword, a hex triple,
+ * or a `var()` reference becomes channels at all. The read itself goes through `parseColor`, so both
+ * halves agree on what a computed value means.
  *
- * An unparsable value reads as `0` rather than as absence, because every caller of this is measuring
- * and `'auto'`, `'none'`, and `''` each contribute no pixels to what a reader sees. Where the
- * distinction matters, read the text with {@link style} instead.
+ * The probe is mounted, because an unmounted element inherits nothing and a `var()` reference to a
+ * token declared on `:root` would resolve to the initial value instead. It is removed in a `finally`,
+ * so a value that throws on the way through leaves no node behind.
+ *
+ * Refusal is the CSSOM's: an expression it will not parse leaves the probe's inline `color` empty
+ * and this returns `undefined`. A `var()` naming an undeclared custom property is not refused,
+ * because the cascade accepts it and computes the inherited color, so a test that means to catch a
+ * missing token asserts on {@link readToken} rather than on this.
  *
  * @example
  * ```ts
- * pixels(button, 'padding-left') // 12
- * pixels(button, 'width') // 0 when the width resolves to `auto`
+ * parseCSSColor('rebeccapurple') // [102, 51, 153, 1]
+ * parseCSSColor('not-a-color') // undefined
  * ```
  */
-export declare function pixels(element: Element, property: string): number;
+export declare function parseCSSColor(value: string): Color | undefined;
 
-/** The registry of capture states one run places, and the files it wrote placing them. */
+/** Holds the registry of capture states one run places, and the files it wrote placing them. */
 export declare interface PortfolioInterface {
-    /** The name of the variant this run renders. */
+    /** Holds the name of the variant this run renders. */
     readonly variant: string;
-    /** Every state placed so far, in placement order. */
-    readonly states: readonly string[];
-    /** Every path written so far, in write order. */
+    /** Lists every state placed so far, in placement order. */
+    readonly placements: readonly string[];
+    /** Lists every path written so far, in write order. */
     readonly paths: readonly string[];
-    /** The registry expanded across every variant: the filenames a complete portfolio holds. */
+    /** Lists the filenames a complete portfolio holds: the registry expanded across every variant. */
     readonly files: readonly string[];
     /**
      * Places one registered state: applies the variant, stages the pane, and writes the verified
@@ -913,22 +1043,22 @@ export declare interface PortfolioInterface {
     place(state: string, element?: Element): Promise<string | undefined>;
 }
 
-/** Options for a capture portfolio. */
+/** Configures a capture portfolio. */
 export declare interface PortfolioOptions {
     /**
-     * Every state name the journeys place, declared once. `place` refuses a name absent from this
-     * list, so the registry and the disk cannot drift apart.
+     * Lists every state name the journeys place, declared once. `place` refuses a name absent from
+     * this list, so the registry and the disk cannot drift apart.
      */
     readonly states: readonly string[];
-    /** Every variant the portfolio can be rendered in. One run renders exactly one of them. */
+    /** Lists every variant the portfolio can be rendered in. One run renders exactly one of them. */
     readonly variants: readonly CaptureVariant[];
-    /** The name of the variant this run renders. Creation throws when no variant carries it. */
+    /** Holds the name of the variant this run renders. Creation throws when no variant carries it. */
     readonly variant: string;
-    /** The directory each written file is placed in, relative to the calling test file. */
+    /** Holds the directory each written file is placed in, relative to the calling test file. */
     readonly directory: string;
     /**
-     * Whether this run writes files. An ordinary run leaves it unset, so `place` resizes nothing,
-     * writes nothing, and records nothing.
+     * Determines whether this run writes files. An ordinary run leaves it unset, so `place` resizes
+     * nothing, writes nothing, and records nothing.
      */
     readonly enabled?: boolean;
 }
@@ -1000,6 +1130,69 @@ export declare function readBackdrop(element: Element, floor: Color): Color;
  */
 export declare function readCascade(): ReadonlySet<string>;
 
+/**
+ * Collects every class token the markup under one root carries.
+ *
+ * @param root - The subtree to sweep. A detached element and a `DocumentFragment` both work.
+ * @returns The class tokens in document order of first sighting; an empty set for markup carrying no
+ * class at all.
+ *
+ * @remarks
+ * The root's own classes count when the root is an `Element`, so a `DocumentFragment` contributes
+ * its descendants alone. Every element is read through `classList`, which is what makes an SVG
+ * element count the same as an HTML one: `className` on an SVG element is an `SVGAnimatedString`
+ * rather than a string, and a reader splitting that value finds nothing.
+ *
+ * This is the authored half of a class conformance check and {@link readCascade} is the defined
+ * half, so the difference between them is the set of classes the markup uses and no loaded
+ * stylesheet declares.
+ *
+ * @example
+ * ```ts
+ * [...readClasses(container)].filter((name) => !readCascade().has(name))
+ * ```
+ */
+export declare function readClasses(root: ParentNode): ReadonlySet<string>;
+
+/**
+ * Measures the WCAG 2.x contrast ratio between an element's computed text and background colors.
+ *
+ * @param element - The element whose rendered text contrast to measure.
+ * @param floor - The opaque color the backdrop walk ends on. Omit it to refuse a stack the floor
+ * would show through instead of assuming one.
+ * @returns The relative-luminance contrast ratio.
+ * @throws Thrown when the element exposes no computed foreground color, and — with `floor` omitted
+ * — when the walk from the element upwards reaches no opaque layer.
+ *
+ * @remarks
+ * A transparent or translucent background resolves through the element's ancestors: every painted
+ * layer from the element up to the first opaque one composites top-over-bottom onto that opaque
+ * base, so a 3% surface tint reads as a tint over what shows through it rather than as a
+ * full-strength paint. A translucent foreground then resolves against that effective background
+ * before luminance is measured.
+ *
+ * With `floor` omitted, the walk from the target upwards must reach a fully opaque layer: the
+ * measurement throws rather than assuming a white canvas wherever that canvas would still be part
+ * of the answer. The refusal reads the alpha of the deepest layer {@link readLayers} collected, so
+ * a chain that declares no background color at all, a chain painting only translucent layers, and a
+ * chain deep enough for its composite to round to the canvas's own channels are refused alike,
+ * because the number any of them produces is as much a report of the assumption as of the page.
+ * Supply a floor wherever the caller knows what the stack sits on — a fragment mounted into a
+ * painted host, or a document whose canvas is {@link CANVAS_COLOR} — and the composite is taken
+ * over it rather than refused.
+ *
+ * The element itself must expose a computed foreground color either way. A detached element exposes
+ * none, and the measurement throws rather than guessing one.
+ *
+ * @example
+ * ```ts
+ * const container = render('<p style="background: #000; color: #fff">Ready</p>')
+ * readContrast(requireValue(container.firstElementChild)) // 21
+ * readContrast(requireValue(container.firstElementChild), CANVAS_COLOR) // 21, and never refuses
+ * ```
+ */
+export declare function readContrast(element: Element, floor?: Color): number;
+
 /**
  * Reads the rendered text of the element that currently holds focus.
  *
@@ -1015,6 +1208,30 @@ export declare function readCascade(): ReadonlySet<string>;
  */
 export declare function readFocus(): string | undefined;
 
+/**
+ * Reads one written frame back and reports its size and the color its bottom row paints.
+ *
+ * @param path - The frame's absolute path, as `captureFrame` returns it.
+ * @returns The frame's size in device pixels and its floor.
+ * @throws Thrown when the runner cannot read the path, when the bytes there are not an image this
+ * browser decodes, and when the browser hands out no 2D canvas to measure them on.
+ *
+ * @remarks
+ * The reading comes off the written file rather than off the document that produced it, which is
+ * what makes it evidence about a capture: the browser's own image decoding and an
+ * `OffscreenCanvas` answer for the pixels a viewer would see, so a frame that ends on the runner's
+ * canvas reports that canvas whatever the document's style resolves to. Pass the path the provider
+ * resolved and `captureFrame` returned; the runner's `readFile` command resolves a relative path
+ * against its own root rather than against the calling test file, so a relative path names a file
+ * somewhere else.
+ *
+ * @example
+ * ```ts
+ * const reading = await readFrame(written)
+ * ```
+ */
+export declare function readFrame(path: string): Promise<FrameReading>;
+
 /**
  * Collects the painted layers standing between one element and the surface it sits on.
  *
@@ -1028,7 +1245,7 @@ export declare function readFocus(): string | undefined;
  * the walk stops at the first fully opaque layer, because nothing above that layer is visible.
  *
  * The stack is what tells a resolved backdrop from an assumed one: the walk reached an opaque
- * surface exactly when its last layer's alpha is `1`. {@link contrast} refuses on that reading,
+ * surface exactly when its last layer's alpha is `1`. {@link readContrast} refuses on that reading,
  * which no comparison of composited colors can replace — 64 half-transparent layers composite to
  * the same channels over opposite floors, because the floor's remaining share falls below the last
  * bit a channel carries.
@@ -1091,6 +1308,13 @@ export declare function readPage(): string;
  * visually-hidden content.
  * @throws When the named region is absent, hidden, or ambiguous.
  *
+ * @remarks
+ * One pass answers this, because absence and concealment share the refusal. The pass asks the role
+ * engine over the elements the accessibility tree presents, so the name matched is the one a screen
+ * reader announces and an `aria-hidden` glyph in a heading a region points at contributes nothing
+ * to it. A region the tree does not present is refused as not visible, which is what a reader
+ * perceiving nothing there means.
+ *
  * @example
  * ```ts
  * readPerception('Run')
@@ -1098,6 +1322,31 @@ export declare function readPage(): string;
  */
 export declare function readPerception(name: string): string;
 
+/**
+ * Reads one resolved CSS length as a number of pixels.
+ *
+ * @param element - The element whose resolved style to inspect.
+ * @param property - The CSS property name, registered or custom.
+ * @returns The leading numeric part of the resolved value, and `0` when it carries none.
+ *
+ * @remarks
+ * A resolved length is text with a unit — `'12px'` — so this reads the number in front of the unit
+ * and discards the rest. The unit is not checked: the resolved value of a length is in pixels in
+ * every case a browser hands back, and a property that resolves to something else is the caller's
+ * mistake rather than this reader's.
+ *
+ * An unparsable value reads as `0` rather than as absence, because every caller of this is measuring
+ * and `'auto'`, `'none'`, and `''` each contribute no pixels to what a reader sees. Where the
+ * distinction matters, read the text with {@link readStyle} instead.
+ *
+ * @example
+ * ```ts
+ * readPixels(button, 'padding-left') // 12
+ * readPixels(button, 'width') // 0 when the width resolves to `auto`
+ * ```
+ */
+export declare function readPixels(element: Element, property: string): number;
+
 /**
  * Measures the contrast the focus chrome painted on one control reaches against its own backdrop.
  *
@@ -1158,6 +1407,25 @@ export declare function readRing(control: Element, worn?: Element): number | und
  */
 export declare function readRole(element: Element): string | undefined;
 
+/**
+ * Reads one custom property from the document element.
+ *
+ * @param name - The custom property name, with or without its leading dashes.
+ * @returns The resolved value, trimmed; an empty string when the document declares no such property.
+ *
+ * @remarks
+ * This is {@link readToken} against `document.documentElement`, which is where a theme declares its
+ * tokens and where a `[data-theme]` switch retunes them. It exists as its own name because that
+ * element is the one a token question is nearly always about, and naming it at every call site
+ * buries the question.
+ *
+ * @example
+ * ```ts
+ * readRootToken('surface')
+ * ```
+ */
+export declare function readRootToken(name: string): string;
+
 /**
  * Reads the normalized visible text of every element a selector matches, in document order.
  *
@@ -1228,6 +1496,25 @@ export declare function readRules(): readonly CSSRule[];
  */
 export declare function readStates(element: Element): readonly string[];
 
+/**
+ * Reads one resolved CSS property from a real browser element.
+ *
+ * @param element - The element whose resolved style to inspect.
+ * @param property - The CSS property name, registered or custom.
+ * @returns The browser's resolved property value, trimmed; an empty string when the element resolves
+ * none.
+ *
+ * @remarks
+ * The value is trimmed, so what comes back is the value and never the whitespace around it. Internal
+ * whitespace is kept: `--shadow: 0 0 2px` reads back with its spaces.
+ *
+ * @example
+ * ```ts
+ * readStyle(button, 'padding-left')
+ * ```
+ */
+export declare function readStyle(element: Element, property: string): string;
+
 /**
  * Reads one element's rendered text the way a name computation reads it.
  *
@@ -1247,6 +1534,32 @@ export declare function readStates(element: Element): readonly string[];
  */
 export declare function readText(element: Element): string;
 
+/**
+ * Reads one custom property from an element's resolved style.
+ *
+ * @param element - The element whose resolved style to inspect.
+ * @param name - The custom property name, with or without its leading dashes.
+ * @returns The resolved value, trimmed; an empty string when the element inherits no such property.
+ *
+ * @remarks
+ * The dashes are optional because a token is spoken about both ways — `--surface` in a stylesheet
+ * and `surface` in prose — and a reader that accepted only one spelling would turn that into a silent
+ * empty string. An absent token reads as `''`, which is what the CSSOM returns and is
+ * indistinguishable from a token declared empty; assert on the value you expect rather than on
+ * presence.
+ *
+ * Resolution is inheritance, so a token declared on `:root` reads from any mounted descendant and
+ * from an unmounted element reads as `''`. Use {@link readRootToken} where the declaration is the
+ * document's.
+ *
+ * @example
+ * ```ts
+ * readToken(panel, 'surface') // '#ffffff'
+ * readToken(panel, '--surface') // '#ffffff'
+ * ```
+ */
+export declare function readToken(element: Element, name: string): string;
+
 /**
  * Reads the value a resolved control renders.
  *
@@ -1267,22 +1580,33 @@ export declare function readText(element: Element): string;
 export declare function readValue(role: string, name: string): string;
 
 /**
- * Hands the tester pane back to the runner's own layout.
+ * Hands the tester pane back to the runner's own layout, at the viewport it had before staging.
  *
  * @remarks
  * A staged pane is the runner's fitting scale suppressed, so a pane left staged outlives the capture
  * that needed it and every later act in the file happens on a surface the runner is no longer
  * fitting to its window. What that costs is not a wrong picture: it is a control whose page
  * coordinates fall outside the pane, which the runner's own layout then intercepts, so an ordinary
- * press fails with the voice of a control that is covered. Calling this on an unstaged pane does
+ * press fails with the voice of a control that is covered.
+ *
+ * The viewport goes back too, because a capture resizes the tester and the size it chose belongs to
+ * the frame rather than to the file: a test that runs after one and reads a breakpoint would
+ * otherwise read the last capture's variant. The size comes off the {@link CAPTURE_PANE} value
+ * {@link stagePane} wrote onto the rule element, which is the reading taken before the first
+ * staging. Calling this on an unstaged pane finds no such value, so it changes nothing and resizes
  * nothing.
  *
+ * That hand-back is what makes {@link stagePane} and this pair a capture's staging rather than a
+ * resize: the pair puts the tester back where it found it, so a suite that used it to reach a
+ * breakpoint runs its next step at the old size. Call `page.viewport` from `vitest/browser` for a
+ * journey's own size, and leave this pair to the capture.
+ *
  * @example
  * ```ts
- * releasePane()
+ * await releasePane()
  * ```
  */
-export declare function releasePane(): void;
+export declare function releasePane(): Promise<void>;
 
 /**
  * Deletes one IndexedDB database and reports what the request actually did.
@@ -1386,6 +1710,14 @@ export declare function resolveAccessible(role: string, name: string): HTMLEleme
  * This is the resolver the acting verbs use, so a click does not fail on a target the act itself
  * scrolls into view. Use {@link resolveAccessible} wherever the target must already be on screen.
  *
+ * It runs two passes, and only the first one can return an element. The visible pass asks the role
+ * engine for the exact name over the elements the accessibility tree presents, which is the name a
+ * screen reader announces: an `aria-hidden` icon beside the text contributes nothing to it. The
+ * hidden pass runs only when the visible pass found nothing at all, and it decides which refusal
+ * the caller hears — a name the page carries nowhere, or a target that is there and out of reach.
+ * That pass must include hidden elements to see a folded control, which is what puts a glyph back
+ * into the computed name, so it asks with {@link computeNamePattern} rather than the exact string.
+ *
  * @example
  * ```ts
  * resolveRendered('tab', 'Drafts')
@@ -1393,57 +1725,6 @@ export declare function resolveAccessible(role: string, name: string): HTMLEleme
  */
 export declare function resolveRendered(first: string, second?: string): HTMLElement;
 
-/**
- * Resolves any CSS color expression to straight sRGB channels, by asking the browser.
- *
- * @param value - Any value the `color` property accepts: a keyword, a hex triple, a `var()`
- * reference, a `color-mix()`, or an already-computed `rgb()`.
- * @returns The resolved color's channels, or `undefined` when the CSSOM refuses the value or the
- * computed result names no color {@link parseColor} speaks.
- *
- * @remarks
- * This is the live half of the pair {@link parseColor} opens. `parseColor` reads text and speaks
- * only the computed syntaxes a cascade hands back; this stages a probe element, hands it to the real
- * cascade, and reads back what the engine computed — which is the only way a keyword, a hex triple,
- * or a `var()` reference becomes channels at all. The read itself goes through `parseColor`, so both
- * halves agree on what a computed value means.
- *
- * The probe is mounted, because an unmounted element inherits nothing and a `var()` reference to a
- * token declared on `:root` would resolve to the initial value instead. It is removed in a `finally`,
- * so a value that throws on the way through leaves no node behind.
- *
- * Refusal is the CSSOM's: an expression it will not parse leaves the probe's inline `color` empty
- * and this returns `undefined`. A `var()` naming an undeclared custom property is not refused,
- * because the cascade accepts it and computes the inherited color, so a test that means to catch a
- * missing token asserts on {@link token} rather than on this.
- *
- * @example
- * ```ts
- * rgba('rebeccapurple') // [102, 51, 153, 1]
- * rgba('not-a-color') // undefined
- * ```
- */
-export declare function rgba(value: string): Color | undefined;
-
-/**
- * Reads one custom property from the document element.
- *
- * @param name - The custom property name, with or without its leading dashes.
- * @returns The resolved value, trimmed; an empty string when the document declares no such property.
- *
- * @remarks
- * This is {@link token} against `document.documentElement`, which is where a theme declares its
- * tokens and where a `[data-theme]` switch retunes them. It exists as its own name because that
- * element is the one a token question is nearly always about, and naming it at every call site
- * buries the question.
- *
- * @example
- * ```ts
- * rootToken('surface')
- * ```
- */
-export declare function rootToken(name: string): string;
-
 /**
  * Sets the tester's viewport and renders the runner's pane at the size that viewport claims.
  *
@@ -1469,6 +1750,11 @@ export declare function rootToken(name: string): string;
  * the window puts its lower half beyond what a pointer can reach, so an ordinary press then fails
  * as a control outside the viewport, in a test that took no picture at all.
  *
+ * This is a capture's staging alone. A suite that resizes the tester for a journey — a breakpoint
+ * to drive, a variant to act at — calls `page.viewport` from `vitest/browser` and leaves the tester
+ * there. Staging and releasing as a pair resizes and then undoes the resize, so the journey step
+ * after it runs at the size the file started at.
+ *
  * The rule is declared rather than written inline, because the runner writes its own scale onto the
  * pane as inline custom properties and rewrites them whenever the tester resizes. A declared rule
  * marked important outranks an inline value and survives every rewrite. It finds the pane by the
@@ -1478,6 +1764,11 @@ export declare function rootToken(name: string): string;
  * The wait is two frames rather than a delay: the first carries the resize into layout and the
  * second is the paint a screenshot reads.
  *
+ * The viewport the tester had before this staging is written onto that rule element as the
+ * {@link CAPTURE_PANE} value, in `<width>x<height>` form, and {@link releasePane} hands it back.
+ * Staging an already-staged pane leaves that value alone, so a capture that stages a second time to
+ * cover a taller document still releases to the viewport the tester started with.
+ *
  * @example
  * ```ts
  * await stagePane(390, 844)
@@ -1485,51 +1776,6 @@ export declare function rootToken(name: string): string;
  */
 export declare function stagePane(width: number, height: number): Promise<void>;
 
-/**
- * Reads one resolved CSS property from a real browser element.
- *
- * @param element - The element whose resolved style to inspect.
- * @param property - The CSS property name, registered or custom.
- * @returns The browser's resolved property value, trimmed; an empty string when the element resolves
- * none.
- *
- * @remarks
- * The value is trimmed, so what comes back is the value and never the whitespace around it. Internal
- * whitespace is kept: `--shadow: 0 0 2px` reads back with its spaces.
- *
- * @example
- * ```ts
- * style(button, 'padding-left')
- * ```
- */
-export declare function style(element: Element, property: string): string;
-
-/**
- * Reads one custom property from an element's resolved style.
- *
- * @param element - The element whose resolved style to inspect.
- * @param name - The custom property name, with or without its leading dashes.
- * @returns The resolved value, trimmed; an empty string when the element inherits no such property.
- *
- * @remarks
- * The dashes are optional because a token is spoken about both ways — `--surface` in a stylesheet
- * and `surface` in prose — and a reader that accepted only one spelling would turn that into a silent
- * empty string. An absent token reads as `''`, which is what the CSSOM returns and is
- * indistinguishable from a token declared empty; assert on the value you expect rather than on
- * presence.
- *
- * Resolution is inheritance, so a token declared on `:root` reads from any mounted descendant and
- * from an unmounted element reads as `''`. Use {@link rootToken} where the declaration is the
- * document's.
- *
- * @example
- * ```ts
- * token(panel, 'surface') // '#ffffff'
- * token(panel, '--surface') // '#ffffff'
- * ```
- */
-export declare function token(element: Element, name: string): string;
-
 /**
  * Reaches a named control only through natural forward Tab traversal from the current focus.
  *