@orkestrel/test 0.0.11 → 0.0.13

package/dist/src/browser/index.js

@@ -1,7 +1,7 @@
 import { commands, page, userEvent } from "vitest/browser";
 //#region src/browser/constants.ts
 /**
-* 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
@@ -27,7 +27,7 @@ var ACCESSIBLE_ROLES = Object.freeze([
 	"treeitem"
 ]);
 /**
-* 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
@@ -41,17 +41,35 @@ var CANVAS_COLOR = Object.freeze([
 	1
 ]);
 /**
-* 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.
 */
 var CAPTURE_PANE = "data-capture-pane";
 /**
-* The roles whose accessible name is the text a reader can see inside them.
+* 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.
+*/
+var CAPTURE_STAGINGS = 4;
+/**
+* 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`
@@ -70,7 +88,7 @@ var CONTENT_ROLES = Object.freeze([
 	"tab"
 ]);
 /**
-* The role each `input` type carries.
+* Names the role each `input` type carries.
 *
 * @remarks
 * Membership is the contract. The map answers for `button`, `checkbox`, `email`, `number`,
@@ -94,7 +112,7 @@ var FIELD_ROLES = Object.freeze({
 	url: "textbox"
 });
 /**
-* 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
@@ -104,7 +122,7 @@ var FIELD_ROLES = Object.freeze({
 */
 var FOCUSABLE_SELECTOR = "a[href], area[href], button, input, select, summary, textarea, [tabindex]";
 /**
-* The role a `th` carries for the header axis its `scope` names.
+* 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
@@ -116,7 +134,8 @@ var HEADER_ROLES = Object.freeze({
 	row: "rowheader"
 });
 /**
-* 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`,
@@ -177,7 +196,7 @@ var IMPLICIT_ROLES = Object.freeze({
 * 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
@@ -188,12 +207,12 @@ function isOutsideViewport(rectangle) {
 	return rectangle.bottom <= 0 || rectangle.right <= 0 || rectangle.top >= window.innerHeight || rectangle.left >= window.innerWidth;
 }
 /**
-* Determines whether a person can click one element where it currently sits.
+* Determines whether a person can click one element where it 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`,
@@ -222,8 +241,7 @@ function isReachable(element) {
 * 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
@@ -251,6 +269,38 @@ function isRendered(element) {
 	return getComputedStyle(element).visibility !== "hidden";
 }
 /**
+* Computes the pattern that matches one accessible name a decorative glyph may sit beside.
+*
+* @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 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.
+*
+* 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.
+*
+* 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
+* computeNamePattern('Add building').test('\uF4FE Add building') // true
+* ```
+*/
+function computeNamePattern(name) {
+	const wanted = name.replaceAll(/\s+/g, " ").trim().replaceAll(/[$()*+.?[\\\]^{|}]/g, "\\$&");
+	return new RegExp(`^[^\\p{L}\\p{N}]*${wanted}[^\\p{L}\\p{N}]*$`, "u");
+}
+/**
 * Resolves one rendered, focus-reachable interactive element without requiring it to intersect the
 * viewport yet.
 *
@@ -264,6 +314,14 @@ function isRendered(element) {
 * 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')
@@ -275,10 +333,17 @@ function resolveRendered(first, second) {
 	const matches = [];
 	for (const role of roles) for (const element of page.getByRole(role, {
 		name,
-		exact: true,
-		includeHidden: true
+		exact: true
 	}).elements()) if (element instanceof HTMLElement && !matches.includes(element)) matches.push(element);
-	if (matches.length === 0) throw new Error(`No interactive element has the accessible name "${name}"`);
+	if (matches.length === 0) {
+		const pattern = computeNamePattern(name);
+		if (!roles.some((role) => page.getByRole(role, {
+			name: pattern,
+			exact: true,
+			includeHidden: true
+		}).elements().length > 0)) throw new Error(`No interactive element has the accessible name "${name}"`);
+		throw new Error(`Interactive target "${name}" is not visible and focus-reachable`);
+	}
 	const reachable = matches.filter((element) => isReachable(element));
 	if (reachable.length === 0) throw new Error(`Interactive target "${name}" is not visible and focus-reachable`);
 	if (reachable.length > 1) throw new Error(`Interactive target "${name}" is ambiguous across ${reachable.length} elements`);
@@ -401,20 +466,6 @@ async function fillAccessible(name, text) {
 	await userEvent.fill(resolveRendered(name), text);
 }
 /**
-* Presses a browser-keyboard sequence using Vitest's installed user-event syntax.
-*
-* @param keys - The keys or key descriptors to press.
-* @returns A promise resolving after the sequence completes.
-*
-* @example
-* ```ts
-* await pressKeys('{ArrowRight}{Enter}')
-* ```
-*/
-async function pressKeys(keys) {
-	await userEvent.keyboard(keys);
-}
-/**
 * Reaches a named control only through natural forward Tab traversal from the current focus.
 *
 * @param name - The target's exact accessible name.
@@ -456,6 +507,13 @@ async function traverseAccessible(name) {
 * 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')
@@ -473,8 +531,7 @@ function readPerception(name) {
 		"tabpanel"
 	]) for (const element of page.getByRole(role, {
 		name,
-		exact: true,
-		includeHidden: true
+		exact: true
 	}).elements()) if (element instanceof HTMLElement && !matches.includes(element)) matches.push(element);
 	const visible = matches.filter((element) => {
 		const rectangle = element.getBoundingClientRect();
@@ -509,7 +566,7 @@ function readPage() {
 	return document.body.innerText.replaceAll(/\s+/g, " ").trim();
 }
 /**
-* Reads the rendered text of the element that currently holds focus.
+* Reads the rendered text of the element that holds focus.
 *
 * @returns The focused HTML element's trimmed rendered text, including an empty string, or
 * `undefined` when focus rests on a non-HTML element. When nothing holds focus, the browser
@@ -834,8 +891,8 @@ function build(tag, options) {
 * @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
@@ -1024,20 +1081,20 @@ function parseColor(value) {
 * 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.
+* missing token asserts on {@link readToken} rather than on this.
 *
 * @example
 * ```ts
-* rgba('rebeccapurple') // [102, 51, 153, 1]
-* rgba('not-a-color') // undefined
+* parseCSSColor('rebeccapurple') // [102, 51, 153, 1]
+* parseCSSColor('not-a-color') // undefined
 * ```
 */
-function rgba(value) {
+function parseCSSColor(value) {
 	const probe = mount(build("span"));
 	try {
 		probe.style.color = value;
 		if (probe.style.color === "") return void 0;
-		return parseColor(style(probe, "color"));
+		return parseColor(readStyle(probe, "color"));
 	} finally {
 		probe.remove();
 	}
@@ -1047,11 +1104,11 @@ function rgba(value) {
 *
 * @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,
+* @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 rgba}, so a keyword, a token reference, and the
+* 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.
@@ -1063,13 +1120,13 @@ function rgba(value) {
 *
 * @example
 * ```ts
-* colorEqual('rebeccapurple', 'rgb(102, 51, 153)') // true
-* colorEqual('red', [0, 0, 255, 1]) // false
+* matchesColor('rebeccapurple', 'rgb(102, 51, 153)') // true
+* matchesColor('red', [0, 0, 255, 1]) // false
 * ```
 */
-function colorEqual(first, second) {
-	const left = typeof first === "string" ? rgba(first) : first;
-	const right = typeof second === "string" ? rgba(second) : second;
+function matchesColor(first, second) {
+	const left = typeof first === "string" ? parseCSSColor(first) : first;
+	const right = typeof second === "string" ? parseCSSColor(second) : second;
 	if (left === void 0 || right === void 0) return false;
 	const tolerance = .5;
 	const [leftRed, leftGreen, leftBlue, leftAlpha] = left;
@@ -1155,7 +1212,7 @@ function measureContrast(front, back) {
 * 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.
@@ -1235,11 +1292,11 @@ function readBackdrop(element, floor) {
 * @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
+* readContrast(requireValue(container.firstElementChild)) // 21
+* readContrast(requireValue(container.firstElementChild), CANVAS_COLOR) // 21, and never refuses
 * ```
 */
-function contrast(element, floor) {
+function readContrast(element, floor) {
 	const foreground = parseColor(getComputedStyle(element).color);
 	if (foreground === void 0) throw new Error("Computed foreground color is unavailable");
 	const layers = readLayers(element);
@@ -1258,9 +1315,9 @@ function contrast(element, floor) {
 *
 * @remarks
 * This reads and never acts. Focus arrives through the published verbs — `traverseAccessible`,
-* `pressKeys`, a real click — and this measures what the browser painted once it landed. A control
-* that is not matching `:focus-visible` when the call is made reports nothing, because no
-* measurement taken then would be about focus.
+* `userEvent.keyboard` from `vitest/browser`, a real click — and this measures what the browser
+* painted once it landed. A control that is not matching `:focus-visible` when the call is made
+* reports nothing, because no measurement taken then would be about focus.
 *
 * Some controls are two elements: one that takes the focus and one a reader can see. A hidden radio
 * beside the label that carries every pixel of its chrome is the case `worn` exists for, so a
@@ -1334,6 +1391,34 @@ function readCascade() {
 	return known;
 }
 /**
+* 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))
+* ```
+*/
+function readClasses(root) {
+	const authored = /* @__PURE__ */ new Set();
+	if (root instanceof Element) for (const name of root.classList) authored.add(name);
+	for (const element of root.querySelectorAll("*")) for (const name of element.classList) authored.add(name);
+	return authored;
+}
+/**
 * Collects every rule the stylesheets loaded into this document hold, nested grouping rules
 * included.
 *
@@ -1383,8 +1468,8 @@ function readRules() {
 *
 * @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
@@ -1475,6 +1560,38 @@ function extractOrphans(root, child, parent) {
 	return [...root.querySelectorAll(`.${child}`)].filter((node) => (node.parentElement?.closest(`.${parent}`) ?? null) === null).map((node) => node.outerHTML);
 }
 /**
+* 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) // []
+* ```
+*/
+function extractStyles(root) {
+	const elements = root instanceof Element ? [root] : [];
+	elements.push(...root.querySelectorAll("*"));
+	const styled = [];
+	for (const element of elements) if ((element.getAttribute("style") ?? "").trim() !== "" || element.localName === "style") styled.push(element.outerHTML);
+	return styled;
+}
+/**
 * Reads one resolved CSS property from a real browser element.
 *
 * @param element - The element whose resolved style to inspect.
@@ -1488,10 +1605,10 @@ function extractOrphans(root, child, parent) {
 *
 * @example
 * ```ts
-* style(button, 'padding-left')
+* readStyle(button, 'padding-left')
 * ```
 */
-function style(element, property) {
+function readStyle(element, property) {
 	return getComputedStyle(element).getPropertyValue(property).trim();
 }
 /**
@@ -1509,17 +1626,17 @@ function style(element, property) {
 * 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
+* from an unmounted element reads as `''`. Use {@link readRootToken} where the declaration is the
 * document's.
 *
 * @example
 * ```ts
-* token(panel, 'surface') // '#ffffff'
-* token(panel, '--surface') // '#ffffff'
+* readToken(panel, 'surface') // '#ffffff'
+* readToken(panel, '--surface') // '#ffffff'
 * ```
 */
-function token(element, name) {
-	return style(element, name.startsWith("--") ? name : `--${name}`);
+function readToken(element, name) {
+	return readStyle(element, name.startsWith("--") ? name : `--${name}`);
 }
 /**
 * Reads one custom property from the document element.
@@ -1528,18 +1645,18 @@ function token(element, name) {
 * @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
+* 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
-* rootToken('surface')
+* readRootToken('surface')
 * ```
 */
-function rootToken(name) {
-	return token(document.documentElement, name);
+function readRootToken(name) {
+	return readToken(document.documentElement, name);
 }
 /**
 * Reads one resolved CSS length as a number of pixels.
@@ -1556,19 +1673,57 @@ function rootToken(name) {
 *
 * 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.
+* distinction matters, read the text with {@link readStyle} instead.
 *
 * @example
 * ```ts
-* pixels(button, 'padding-left') // 12
-* pixels(button, 'width') // 0 when the width resolves to `auto`
+* readPixels(button, 'padding-left') // 12
+* readPixels(button, 'width') // 0 when the width resolves to `auto`
 * ```
 */
-function pixels(element, property) {
-	const measured = Number.parseFloat(style(element, property));
+function readPixels(element, property) {
+	const measured = Number.parseFloat(readStyle(element, property));
 	return Number.isFinite(measured) ? measured : 0;
 }
 /**
+* 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()
+* ```
+*/
+function measureContent() {
+	let edge = 0;
+	for (const element of document.body.querySelectorAll("*")) {
+		const bottom = element.getBoundingClientRect().bottom + window.scrollY + readPixels(element, "margin-bottom");
+		if (bottom > edge) edge = bottom;
+	}
+	return Math.ceil(edge + readPixels(document.body, "padding-bottom") + readPixels(document.body, "margin-bottom") + readPixels(document.documentElement, "padding-bottom") + readPixels(document.documentElement, "margin-bottom"));
+}
+/**
 * Sets the tester's viewport and renders the runner's pane at the size that viewport claims.
 *
 * @param width - The viewport width in CSS pixels.
@@ -1587,12 +1742,17 @@ function pixels(element, property) {
 * therefore unscaled and lifted to the window's own origin for the shot. The `iframe[data-vitest]`
 * selector and the `--tester-transform`, `--tester-margin-left`, `--viewport-width`, and
 * `--viewport-height` custom properties are the runner's, so a Vitest release that renames any of
-* them reddens the size check below rather than writing a wrong frame.
+* them reddens the size check that follows rather than writing a wrong frame.
 *
 * Hand the pane straight back with {@link releasePane}. A tester pinned at a viewport taller than
 * the window puts its lower half beyond what a pointer can reach, so an ordinary press then fails
 * as a control outside the viewport, in a test that took no picture at all.
 *
+* 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
@@ -1602,12 +1762,18 @@ function pixels(element, property) {
 * 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)
 * ```
 */
 async function stagePane(width, height) {
+	const viewport = `${String(window.innerWidth)}x${String(window.innerHeight)}`;
 	await page.viewport(width, height);
 	const frame = window.frameElement;
 	const pane = frame?.parentElement;
@@ -1616,7 +1782,7 @@ async function stagePane(width, height) {
 	pane.setAttribute(CAPTURE_PANE, "");
 	if (owner.querySelector(`style[data-capture-pane]`) === null) {
 		const rule = owner.createElement("style");
-		rule.setAttribute(CAPTURE_PANE, "");
+		rule.setAttribute(CAPTURE_PANE, viewport);
 		rule.textContent = [
 			`[${CAPTURE_PANE}],:has(>iframe[data-vitest])`,
 			"{--tester-transform:none !important;--tester-margin-left:0px !important}",
@@ -1633,33 +1799,50 @@ async function stagePane(width, height) {
 	if (Math.round(box.width) !== width || Math.round(box.height) !== height) throw new Error(`Tester pane rendered ${String(Math.round(box.width))}x${String(Math.round(box.height))} for a ${String(width)}x${String(height)} viewport`);
 }
 /**
-* 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()
 * ```
 */
-function releasePane() {
+async function releasePane() {
 	const pane = window.frameElement?.parentElement;
+	const rule = pane?.ownerDocument.querySelector(`style[${CAPTURE_PANE}]`);
+	const viewport = rule?.getAttribute("data-capture-pane")?.split("x") ?? [];
 	pane?.removeAttribute(CAPTURE_PANE);
-	pane?.ownerDocument.querySelector(`style[${CAPTURE_PANE}]`)?.remove();
+	rule?.remove();
+	const width = Number(viewport[0]);
+	const height = Number(viewport[1]);
+	if (Number.isFinite(width) && Number.isFinite(height)) await page.viewport(width, height);
 }
 /**
 * 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
@@ -1669,8 +1852,41 @@ function releasePane() {
 * 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
@@ -1680,6 +1896,17 @@ function releasePane() {
 async function captureFrame(options) {
 	try {
 		await stagePane(options.width, options.height);
+		let pane = options.height;
+		let covered = Math.max(measureContent(), options.height);
+		let growth = 0;
+		for (let staging = 0; pane !== covered; staging += 1) {
+			if (staging === 4) throw new Error(`Capture frame at ${options.path} never settled after ${String(4)} restagings: ${String(covered)} over a ${String(pane)} pane`);
+			pane = covered + growth;
+			await stagePane(options.width, pane);
+			const reading = Math.max(measureContent(), options.height);
+			growth = Math.max(0, reading - covered);
+			covered = reading;
+		}
 		const shot = options.element === void 0 ? await page.screenshot({
 			path: options.path,
 			base64: true
@@ -1698,10 +1925,57 @@ async function captureFrame(options) {
 		if (await commands.readFile(shot.path, "base64") !== shot.base64) throw new Error(`Capture frame at ${options.path} is not the one this run shot`);
 		return shot.path;
 	} finally {
-		releasePane();
+		await releasePane();
 	}
 }
 /**
+* 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)
+* ```
+*/
+async function readFrame(path) {
+	const encoded = await commands.readFile(path, "base64").catch((cause) => {
+		throw new Error(`Capture frame at ${path} could not be read`, { cause });
+	});
+	const image = new Image();
+	image.src = `data:image/png;base64,${encoded}`;
+	await image.decode().catch((cause) => {
+		throw new Error(`Capture frame at ${path} is not an image this browser decodes`, { cause });
+	});
+	const context = new OffscreenCanvas(image.width, image.height).getContext("2d");
+	if (context === null) throw new Error(`Capture frame at ${path} cannot be measured without a 2D canvas`);
+	context.drawImage(image, 0, 0);
+	const row = context.getImageData(0, image.height - 1, image.width, 1).data;
+	const red = row[0];
+	const green = row[1];
+	const blue = row[2];
+	const alpha = row[3];
+	let single = red !== void 0 && green !== void 0 && blue !== void 0;
+	for (let pixel = 4; single && pixel < row.length; pixel += 4) single = row[pixel] === red && row[pixel + 1] === green && row[pixel + 2] === blue && row[pixel + 3] === alpha;
+	return {
+		width: image.width,
+		height: image.height,
+		floor: single ? `rgb(${String(red)}, ${String(green)}, ${String(blue)})` : void 0
+	};
+}
+/**
 * Expands a capture registry across every variant into the filenames a complete portfolio holds.
 *
 * @param states - The registered state names.
@@ -1832,7 +2106,7 @@ function createPortfolio(options) {
 	return {
 		variant: options.variant,
 		files,
-		get states() {
+		get placements() {
 			return [...placed];
 		},
 		get paths() {
@@ -1968,6 +2242,6 @@ function createJournal() {
 	};
 }
 //#endregion
-export { ACCESSIBLE_ROLES, CANVAS_COLOR, CAPTURE_PANE, CONTENT_ROLES, FIELD_ROLES, FOCUSABLE_SELECTOR, HEADER_ROLES, IMPLICIT_ROLES, blendColor, build, captureFrame, clearStorage, clickAccessible, clickAccessibleWithin, clickDisclosure, colorEqual, commitInput, contrast, createChannel, createDragEvent, createJournal, createPointerEvent, createPortfolio, describeFocus, describeTree, expandCaptures, extractOrphans, fillAccessible, findKeyframes, findRule, isOutsideViewport, isReachable, isRendered, measureContrast, measureLuminance, mount, parseColor, pixels, pressKeys, readBackdrop, readCascade, readFocus, readLayers, readName, readPage, readPerception, readRing, readRole, readRows, readRules, readStates, readText, readValue, releasePane, removeDatabase, render, resolveAccessible, resolveRendered, rgba, rootToken, stagePane, style, token, traverseAccessible, typeAccessible, typeInput, waitForFrame };
+export { ACCESSIBLE_ROLES, CANVAS_COLOR, CAPTURE_PANE, CAPTURE_STAGINGS, CONTENT_ROLES, FIELD_ROLES, FOCUSABLE_SELECTOR, HEADER_ROLES, IMPLICIT_ROLES, blendColor, build, captureFrame, clearStorage, clickAccessible, clickAccessibleWithin, clickDisclosure, commitInput, computeNamePattern, createChannel, createDragEvent, createJournal, createPointerEvent, createPortfolio, describeFocus, describeTree, expandCaptures, extractOrphans, extractStyles, fillAccessible, findKeyframes, findRule, isOutsideViewport, isReachable, isRendered, matchesColor, measureContent, measureContrast, measureLuminance, mount, parseCSSColor, parseColor, readBackdrop, readCascade, readClasses, readContrast, readFocus, readFrame, readLayers, readName, readPage, readPerception, readPixels, readRing, readRole, readRootToken, readRows, readRules, readStates, readStyle, readText, readToken, readValue, releasePane, removeDatabase, render, resolveAccessible, resolveRendered, stagePane, traverseAccessible, typeAccessible, typeInput, waitForFrame };
 
 //# sourceMappingURL=index.js.map