@orkestrel/test 0.0.28 → 0.0.30

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -23,7 +23,7 @@ npm install -D @orkestrel/test
23
23
 
24
24
  ## Requirements
25
25
 
26
- - Node.js >= 22.12.0
26
+ - Node.js >= 22.18.0
27
27
  - ESM and CommonJS
28
28
 
29
29
  ## Usage
@@ -92,7 +92,7 @@ a browser workspace renders that table in.
92
92
  The server face adds `readInventory`, which reads a checkout into a map of root-relative path to
93
93
  file text that a parity suite can assert against, and `createLoopback`, which binds a server the
94
94
  test built to an ephemeral loopback port. Behind them sit the pure leaves the server face also
95
- exports on its own: `readInventory` refuses an escape with `resolveContained` and prunes with
95
+ exports on its own: `readInventory` refuses a path outside the root with `resolveContained` and prunes with
96
96
  `isExcluded`, while `createScratch` refuses one with `requireContained`, the throwing form, and
97
97
  reads and compares its allocation with `readIdentity` and `matchesIdentity` before `destroy()`
98
98
  removes anything. `createLink` and `removeTree` do the writing under it, and both decide on the
@@ -146,7 +146,7 @@ back for every key that is not integer-like.
146
146
 
147
147
  `createScratch` and `readInventory` promise different things, and each boundary is worth stating up
148
148
  front. `createScratch` allocates its own directory at POSIX mode `0700` — under the host temporary
149
- directory, or under a `parent` you name — and refuses a path that lexically escapes it. The suite
149
+ directory, or under a `parent` you name — and refuses a path that lexically resolves outside it. The suite
150
150
  gates that assertion on `supportsMode`, the shipped probe that reads whether permission bits
151
151
  round-trip on this host, so it runs only where they do and claims nothing about a host that emulates
152
152
  them. The mode keeps another uid out, and neither a sibling test worker nor the code under test is
@@ -162,8 +162,8 @@ reports `ctime` in its place, the first write moves it, and `destroy()` then rem
162
162
  returns as if it had. `readInventory` walks a checkout you supply, usually one the test did not
163
163
  create, so it throws on a symlinked root or named target, throws on a named target whose real path
164
164
  leaves the root through a link in the middle, and skips a symlink met while walking. Neither is a
165
- sandbox against hostile filesystem content: those refusals stop accidental escape, not an adversary
166
- who can create hard links where the test process already writes.
165
+ sandbox against untrusted filesystem content: those refusals stop accidental access outside the root, not a process
166
+ that can create hard links where the test process already writes.
167
167
 
168
168
  The browser face is the journey layer: an accessible-name resolver with exact failure voices,
169
169
  region and disclosure targeting, input and traversal verbs, perception readers, a WCAG contrast
@@ -78,7 +78,7 @@ export declare function adoptSheet(text: string): SheetAdoption;
78
78
  * An animation counts as endless when its effect declares infinite iterations. A paused, an idle,
79
79
  * and a finished animation are at rest, so neither list holds one.
80
80
  */
81
- export declare interface AnimationReading {
81
+ export declare interface AnimationResult {
82
82
  /** Lists the running animations that end, the ones `waitForAnimations` waits on. */
83
83
  readonly finite: readonly Animation[];
84
84
  /** Lists the running animations whose effect declares infinite iterations. */
@@ -270,7 +270,7 @@ export declare const CAPTURE_PANE = "data-capture-pane";
270
270
  * one restaging past the cap before it comes back down to the edge. Nothing measured needs a
271
271
  * fourth, so a fourth is the headroom that keeps a settling document off the refusal.
272
272
  */
273
- export declare const CAPTURE_STAGINGS = 4;
273
+ export declare const CAPTURE_STAGE_LIMIT = 4;
274
274
 
275
275
  /**
276
276
  * Shoots one frame at one viewport size and proves the file on disk holds this run's bytes.
@@ -278,14 +278,17 @@ export declare const CAPTURE_STAGINGS = 4;
278
278
  * @param options - The path to write, the viewport to shoot at, and the element to shoot.
279
279
  * @returns The absolute path of the written frame, after it has been read back and matched.
280
280
  * @throws Thrown when the pane cannot be staged, when the document's height or an element frame's
281
- * element height never settles under {@link CAPTURE_STAGINGS} restagings, when the provider wrote
281
+ * element height never settles under {@link CAPTURE_STAGE_LIMIT} restagings, when the provider wrote
282
282
  * the frame somewhere else, and when the bytes on disk are not the ones this shot produced.
283
283
  *
284
284
  * @remarks
285
285
  * The path a screenshot call returns is the path it meant to write, so it is not evidence a file
286
- * exists. The file is read back through the runner's built-in `readFile` command and compared with
287
- * the shot itself, which is what separates a frame this run wrote from one an earlier run left
288
- * behind. The provider resolves `options.path` against the calling test file and returns an absolute
286
+ * exists. The {@link verifyFrame} helper compares the file with the shot itself. When the page
287
+ * registered a `readCapture` command, {@link readCaptureReader} returns it and the comparison uses
288
+ * SHA-256 digests computed in Node for the file and in the browser for the returned bytes. Otherwise
289
+ * the runner's built-in `readFile` command supplies the base64 comparison. A command failure
290
+ * propagates without falling back. The provider resolves `options.path`
291
+ * against the calling test file and returns an absolute
289
292
  * path, so the two are compared by the segments that survive resolving `.` and `..` lexically — the
290
293
  * refusal is what a provider resolving that path against a different base would trip.
291
294
  *
@@ -295,6 +298,8 @@ export declare const CAPTURE_STAGINGS = 4;
295
298
  * than the document — a frame that reads as the surface down to the fold and as bare canvas after
296
299
  * it. The document is therefore laid out at the declared viewport first and, where it is taller
297
300
  * than that, the pane is staged again at the height the document needs, for the shot alone.
301
+ * Where the tester already has the declared viewport, the reading precedes the initial staging,
302
+ * so fixed content stages at its final height directly. Every staged height is still read again.
298
303
  *
299
304
  * That height is {@link measureContent}, never less than `options.height`, because the declared
300
305
  * viewport is the smallest frame a variant asks for. The reading is the content's own edge rather
@@ -317,7 +322,7 @@ export declare const CAPTURE_STAGINGS = 4;
317
322
  *
318
323
  * The re-reading stops when the pane and the edge agree, which is the pane the shot is taken at. A
319
324
  * rule that adds height with every pane never reaches that point, so the re-reading is bounded by
320
- * {@link CAPTURE_STAGINGS} and the shot is refused with
325
+ * {@link CAPTURE_STAGE_LIMIT} and the shot is refused with
321
326
  * `Capture frame at <path> never settled after <n> restagings: <h> over a <h> pane` rather than
322
327
  * written at a height that is already wrong.
323
328
  *
@@ -366,6 +371,9 @@ export declare const CAPTURE_STAGINGS = 4;
366
371
  */
367
372
  export declare function captureFrame(options: FrameOptions): Promise<string>;
368
373
 
374
+ /** Reads the lowercase hexadecimal SHA-256 digest of a captured file through a browser command. */
375
+ export declare type CaptureReader = (path: string) => Promise<string>;
376
+
369
377
  /**
370
378
  * Adds to a journey variant the document change a capture run applies before resizing.
371
379
  *
@@ -409,7 +417,7 @@ export declare interface CensusFixture {
409
417
  * markup whose every class the cascade declares. Assert on `elements` as well as on `undeclared`
410
418
  * and the two cannot be confused.
411
419
  */
412
- export declare interface CensusReading {
420
+ export declare interface CensusResult {
413
421
  /** Reports how many elements the walk read, the root included when it is an element. */
414
422
  readonly elements: number;
415
423
  /** Lists every class token the markup carries, sorted. */
@@ -611,7 +619,9 @@ export declare function collectScrollRegions(root: Element, axis?: 'inline' | 'b
611
619
  * {@link containsNode}, so a control inside an open shadow root or a same-origin frame that `root`
612
620
  * holds is in the region, and `start` may sit inside one. A `start` that sits outside the region,
613
621
  * as the control immediately before it, is the walk's origin and never its end, so the first Tab into the
614
- * region reaches its first stop.
622
+ * region reaches its first stop. A native segmented input contributes one stop while consecutive
623
+ * landings pass through its segments up to {@link FOCUS_SEGMENT_LIMIT} landings. A longer run or
624
+ * any other revisit ends the walk.
615
625
  *
616
626
  * @example
617
627
  * ```ts
@@ -1344,23 +1354,29 @@ export declare function driveHold(resolve: () => HTMLElement, name: string): Pro
1344
1354
  * Reaches the control a resolver returns, only through natural forward Tab traversal from the
1345
1355
  * current focus.
1346
1356
  *
1347
- * @param resolve - The resolver that returns the target, called before the first step and again on
1348
- * every step, because a framework may replace the node between resolution and focus arrival.
1357
+ * @param resolve - The resolver called before traversal and at candidate arrivals, without retaining
1358
+ * its result between steps.
1349
1359
  * @param name - The target's name, as the refusal voices it.
1360
+ * @param candidate - The landing check; it must admit every element the resolver could return.
1361
+ * Default: the conservative exact-name check from {@link matchesTraversalName}. Supply a check
1362
+ * matching the resolver's semantics when it uses a label, region, or loose name.
1350
1363
  * @returns The target after the browser moves focus to it.
1351
1364
  * @throws When the resolver refuses, or one complete traversal cannot reach the target.
1352
1365
  *
1353
1366
  * @remarks
1354
1367
  * This is the one loop every traversal verb shares, over {@link stepFocus}. A step counts only when
1355
- * focus lands on an element, the traversal is over when focus revisits one, and the cap is counted
1356
- * off {@link FOCUSABLE_SELECTOR}.
1368
+ * focus lands on an element. Consecutive landings on the same native segmented input continue
1369
+ * through its segments up to {@link FOCUS_SEGMENT_LIMIT} landings and count that control once.
1370
+ * A longer run or any other revisit ends the traversal. Any different landing starts a separate run.
1371
+ * The press cap is {@link FOCUS_SEGMENT_LIMIT} times the {@link FOCUSABLE_SELECTOR} candidate count
1372
+ * plus ten, so a page of segmented inputs has a budget for their segments and picker indicators.
1357
1373
  *
1358
1374
  * @example
1359
1375
  * ```ts
1360
1376
  * await driveTraversal(() => resolveRendered('Evaluate'), 'Evaluate')
1361
1377
  * ```
1362
1378
  */
1363
- export declare function driveTraversal(resolve: () => HTMLElement, name: string): Promise<HTMLElement>;
1379
+ export declare function driveTraversal(resolve: () => HTMLElement, name: string, candidate?: (element: HTMLElement) => boolean): Promise<HTMLElement>;
1364
1380
 
1365
1381
  /**
1366
1382
  * Configures one built element: its class list, its text, and its attributes.
@@ -1543,6 +1559,16 @@ export declare function findKeyframes(name: string): CSSKeyframesRule | undefine
1543
1559
  */
1544
1560
  export declare function findRule(selector: string): CSSStyleRule | undefined;
1545
1561
 
1562
+ /**
1563
+ * Bounds consecutive focus landings and the Tab presses budgeted per segmented input.
1564
+ *
1565
+ * @remarks
1566
+ * Chromium measured nine landings on a datetime-local input with step="0.001": year, month,
1567
+ * day, hour, minute, second, millisecond, and meridiem segments, plus the picker indicator.
1568
+ * The budget covers those landings with one spare press per input.
1569
+ */
1570
+ export declare const FOCUS_SEGMENT_LIMIT = 10;
1571
+
1546
1572
  /**
1547
1573
  * Names what sequential keyboard navigation can reach, before disabled and unrendered elements go.
1548
1574
  *
@@ -1592,7 +1618,7 @@ export declare interface FrameOptions {
1592
1618
  * color in the `rgb(r, g, b)` form a computed style is written in, so a literal comparison,
1593
1619
  * `parseColor`, and `matchesColor` all take it.
1594
1620
  */
1595
- export declare interface FrameReading {
1621
+ export declare interface FrameResult {
1596
1622
  /** Holds the frame's width in device pixels. */
1597
1623
  readonly width: number;
1598
1624
  /** Holds the frame's height in device pixels. */
@@ -1601,6 +1627,14 @@ export declare interface FrameReading {
1601
1627
  readonly floor: string | undefined;
1602
1628
  }
1603
1629
 
1630
+ /** Represents the path and base64 bytes returned by Vitest's screenshot operation. */
1631
+ export declare interface FrameShot {
1632
+ /** Holds the absolute path the provider wrote. */
1633
+ readonly path: string;
1634
+ /** Holds the screenshot bytes encoded as base64. */
1635
+ readonly base64: string;
1636
+ }
1637
+
1604
1638
  /**
1605
1639
  * Holds a mounted statechart harness, the tally it publishes, and the run it drives.
1606
1640
  *
@@ -1970,6 +2004,30 @@ export declare interface JournalStep {
1970
2004
  */
1971
2005
  export declare function matchesColor(first: string | Color, second: string | Color): boolean;
1972
2006
 
2007
+ /**
2008
+ * Checks whether a landing can carry a requested accessible name without resolving the document.
2009
+ *
2010
+ * @param element - The element focus landed on.
2011
+ * @param name - The name the resolver matches.
2012
+ * @param exact - If `true`, compares exact names; if `false`, compares case-insensitive substrings.
2013
+ * Default: `true`.
2014
+ * @returns True if the name matches or its computation requires the resolver; false otherwise.
2015
+ *
2016
+ * @remarks
2017
+ * This is a conservative candidate check, not an accessible-name implementation. It compares a
2018
+ * nonempty `aria-label` without `aria-labelledby`, or the text of a plain native button or link.
2019
+ * Referenced labels, associated labels, descendants, shadow content, owned content, explicit roles,
2020
+ * generated content, and other naming rules fall through to the resolver. Empty requested names
2021
+ * also fall through because a role can prohibit naming. Whitespace, zero-width spaces, and soft
2022
+ * hyphens are normalized as in the provider's role query. Never use this check to accept a target.
2023
+ *
2024
+ * @example
2025
+ * ```ts
2026
+ * matchesTraversalName(document.createElement('input'), 'Attachments') // true
2027
+ * ```
2028
+ */
2029
+ export declare function matchesTraversalName(element: HTMLElement, name: string, exact?: boolean): boolean;
2030
+
1973
2031
  /**
1974
2032
  * Measures the row the document's own content ends on, in document coordinates.
1975
2033
  *
@@ -2071,7 +2129,7 @@ export declare interface MediaOptions {
2071
2129
  * Puts one element into the document and hands it straight back.
2072
2130
  *
2073
2131
  * @param element - The element to attach.
2074
- * @returns The same element, now appended to `document.body`.
2132
+ * @returns The same element, appended to `document.body`.
2075
2133
  *
2076
2134
  * @remarks
2077
2135
  * What this buys is the composition, not the attachment: the `append` method returns `void`, and
@@ -2201,7 +2259,7 @@ export declare function parseColor(value: string): Color | undefined;
2201
2259
  * property is named by letters, digits, `_`, and `-` after its `--`. A name the scope leaves
2202
2260
  * undeclared is not carried, so its `var()` fallback still applies.
2203
2261
  *
2204
- * The scope element is never written. The probe is new, so it has no earlier style to start a
2262
+ * The scope element is never written. The probe is freshly created, so it has no earlier style to start a
2205
2263
  * transition from, and a transition running on the scope keeps running: `currentColor` reads the
2206
2264
  * color the scope shows at that moment, and the scope's geometry and scroll position stay as they
2207
2265
  * were. No attribute, style, or child of the scope changes, so a `MutationObserver` on it records
@@ -2387,7 +2445,7 @@ export declare function readActiveElement(root?: Document | ShadowRoot): HTMLEle
2387
2445
  * readAnimations(document.documentElement).finite.length // 0 once every transition has settled
2388
2446
  * ```
2389
2447
  */
2390
- export declare function readAnimations(element: Element): AnimationReading;
2448
+ export declare function readAnimations(element: Element): AnimationResult;
2391
2449
 
2392
2450
  /**
2393
2451
  * Resolves the opaque color standing behind one element.
@@ -2418,6 +2476,22 @@ export declare function readAnimations(element: Element): AnimationReading;
2418
2476
  */
2419
2477
  export declare function readBackdrop(element: Element, floor: Color): Color;
2420
2478
 
2479
+ /**
2480
+ * Reads the optional disk-digest command the tester page registered.
2481
+ *
2482
+ * @returns The registered `readCapture` command, or undefined where none is registered.
2483
+ *
2484
+ * @remarks Vitest publishes only registered commands, so an unregistered `readCapture` reads as
2485
+ * undefined and a capture falls back to the base64 read-back. Outside a Vitest browser page, where
2486
+ * `commands` is no object, the command reads as undefined too, so importing this module never
2487
+ * throws there.
2488
+ * @example
2489
+ * ```ts
2490
+ * await verifyFrame(shot, '../../tmp/frame.png', readCaptureReader())
2491
+ * ```
2492
+ */
2493
+ export declare function readCaptureReader(): CaptureReader | undefined;
2494
+
2421
2495
  /**
2422
2496
  * Collects every class token the stylesheets loaded into this document actually define.
2423
2497
  *
@@ -2479,7 +2553,7 @@ export declare function readCascade(): ReadonlySet<string>;
2479
2553
  * readCensus(container).undeclared // ['lead'] — no loaded stylesheet declares it
2480
2554
  * ```
2481
2555
  */
2482
- export declare function readCensus(root: ParentNode): CensusReading;
2556
+ export declare function readCensus(root: ParentNode): CensusResult;
2483
2557
 
2484
2558
  /**
2485
2559
  * Collects every class token the markup under one root carries.
@@ -2717,10 +2791,10 @@ export declare function readFocus(): string | undefined;
2717
2791
  *
2718
2792
  * @example
2719
2793
  * ```ts
2720
- * const reading = await readFrame(written)
2794
+ * const result = await readFrame(written)
2721
2795
  * ```
2722
2796
  */
2723
- export declare function readFrame(path: string): Promise<FrameReading>;
2797
+ export declare function readFrame(path: string): Promise<FrameResult>;
2724
2798
 
2725
2799
  /**
2726
2800
  * Reads the topmost element at one element's bounding-box centre.
@@ -2968,7 +3042,7 @@ export declare function readProtocolNode(element: Element): Promise<number>;
2968
3042
  * Each frame on the way up adds its border and its padding, which is where its content starts,
2969
3043
  * scales the point by the ratio of its painted width to its layout width, and adds its own position,
2970
3044
  * so a tester iframe the runner scales or offsets is accounted for, and so is an iframe the page
2971
- * itself nests, bordered, padded, or neither. The reading is of the layout now: a box that moves
3045
+ * itself nests, bordered, padded, or neither. The reading is of the layout at the call: a box that moves
2972
3046
  * afterwards moves the point it names. An element in a document no frame holds reads its own client
2973
3047
  * point. A disconnected element has no layout, and its window still names the tester frame, so it is
2974
3048
  * refused rather than read as that frame's corner.
@@ -3010,7 +3084,7 @@ export declare function readRefusal(name: string): string | undefined;
3010
3084
  * sentence rather than a boolean. This fixes the resolver, translates the `unknown` a `catch` binds
3011
3085
  * into `string | undefined`, and rethrows anything that is not an `Error` — a value no resolver
3012
3086
  * raises, and one a caller reading a message would otherwise lose. `undefined` is rethrown with the
3013
- * rest: a resolver that returned and a hostile getter that threw `undefined` are different findings,
3087
+ * rest: a resolver that returned and an untrusted getter that threw `undefined` are different findings,
3014
3088
  * which is why the `catch` is this function's own rather than a captured thrown value.
3015
3089
  *
3016
3090
  * It resolves rather than acts, so a target it reports `undefined` for is one an acting verb
@@ -3038,7 +3112,7 @@ export declare function readRefusal(role: string, name: string): string | undefi
3038
3112
  * @remarks
3039
3113
  * This reads and never acts. Focus arrives through the published verbs — `traverseAccessible`,
3040
3114
  * `userEvent.keyboard` from `vitest/browser`, a real click — and this measures what the browser
3041
- * painted once it landed. A control that is not matching `:focus-visible` when the call is made
3115
+ * painted after it landed. A control that is not matching `:focus-visible` when the call is made
3042
3116
  * reports nothing, because no measurement taken then would be about focus.
3043
3117
  *
3044
3118
  * Some controls are two elements: one that takes the focus and one a reader can see. A hidden radio
@@ -3081,7 +3155,7 @@ export declare function readRing(control: Element, worn?: Element): number | und
3081
3155
  * A declared `role` wins outright, and its first token is the answer when several are listed.
3082
3156
  * Otherwise the element's own anatomy decides: an anchor is a link only while it holds an `href`,
3083
3157
  * an `input` takes the role {@link FIELD_ROLES} gives its type, a `select` is a combobox until it
3084
- * offers several rows at once, a `section` is a region only once something names it, and a `th`
3158
+ * offers several rows at once, a `section` is a region only after something names it, and a `th`
3085
3159
  * heads whichever axis its `scope` names. Every other tag answers from {@link IMPLICIT_ROLES},
3086
3160
  * whose membership is the contract for what this can answer at all.
3087
3161
  *
@@ -3338,7 +3412,9 @@ export declare function releaseMedia(): Promise<void>;
3338
3412
  * otherwise read the last capture's variant. The size comes off the {@link CAPTURE_PANE} value
3339
3413
  * {@link stagePane} wrote onto the rule element, which is the reading taken before the first
3340
3414
  * staging. Calling this on an unstaged pane finds no such value, so it changes nothing and resizes
3341
- * nothing.
3415
+ * nothing. A staged pane sends its saved size even when the tester already holds it, because the
3416
+ * runner refits its frame scale only on a viewport request; a release that skipped it would leave
3417
+ * the next case shooting through the staged scale.
3342
3418
  *
3343
3419
  * That hand-back is what makes {@link stagePane} and this pair a capture's staging rather than a
3344
3420
  * resize: the pair puts the tester back where it found it, so a suite that used it to reach a
@@ -3569,6 +3645,9 @@ export declare function resolveFileInput(name: string): HTMLInputElement;
3569
3645
  */
3570
3646
  export declare function resolveRendered(first: string, second?: string): HTMLElement;
3571
3647
 
3648
+ /** Names the native input types whose editable segments share one focused element. */
3649
+ export declare const SEGMENTED_INPUT_TYPES: readonly string[];
3650
+
3572
3651
  /**
3573
3652
  * Carries files from outside the page over a rendered target named by role and accessible name.
3574
3653
  *
@@ -3599,7 +3678,7 @@ export declare function sendFileDrag(type: 'dragEnter' | 'dragOver' | 'dragCance
3599
3678
  *
3600
3679
  * @param method - The protocol method name.
3601
3680
  * @param params - The protocol parameters. Omit them for a command that takes none.
3602
- * @returns A promise resolving to the browser's reply once the command completes.
3681
+ * @returns A promise resolving to the browser's reply after the command completes.
3603
3682
  * @throws Thrown when the provider exposes no DevTools session, or the command fails.
3604
3683
  *
3605
3684
  * @remarks
@@ -3646,7 +3725,7 @@ export declare function sendTouch(type: 'touchStart' | 'touchMove' | 'touchEnd'
3646
3725
  * A pointer left over a control paints that control's hover, and a transition still running paints
3647
3726
  * a fill between two states, so neither is a state the interface rests in. An endless animation, a
3648
3727
  * spinner or a placeholder shimmer, stands at a different phase in every frame unless it is held at
3649
- * the same one, so each is paused at its first frame. Call the resume once the frame is shot; a
3728
+ * the same one, so each is paused at its first frame. Call the resume after the frame is shot; a
3650
3729
  * capture that throws still owes it, so call it from a `finally` block.
3651
3730
  *
3652
3731
  * The subject is the whole document, its root element included. The pointer parks through
@@ -3753,7 +3832,7 @@ export declare function stageMedia(options: MediaOptions): Promise<void>;
3753
3832
  *
3754
3833
  * @remarks
3755
3834
  * This depends on the runner's own tester layout, and that dependency is contract rather than an
3756
- * accident: `vitest@4.1.11` lays its tester out inside a smaller page, fits it by scaling the pane
3835
+ * accident: `vitest@4.1.12` lays its tester out inside a smaller page, fits it by scaling the pane
3757
3836
  * the tester sits in, and clips whatever overflows that pane. Layout inside the tester is
3758
3837
  * unaffected — the tester reports the viewport it was given and every breakpoint answers to it —
3759
3838
  * but a screenshot is taken off the page the runner painted, so a frame shot through that scale is
@@ -3762,6 +3841,8 @@ export declare function stageMedia(options: MediaOptions): Promise<void>;
3762
3841
  * selector and the `--tester-transform`, `--tester-margin-left`, `--viewport-width`, and
3763
3842
  * `--viewport-height` custom properties are the runner's, so a Vitest release that renames any of
3764
3843
  * them reddens the size check that follows rather than writing a wrong frame.
3844
+ * The custom-property overrides serve Vitest 4; `transform: none !important` on the pane and
3845
+ * iframe also suppresses Vitest 5's direct CSS transform.
3765
3846
  *
3766
3847
  * Hand the pane straight back with {@link releasePane}. A tester pinned at a viewport taller than
3767
3848
  * the window puts its lower half beyond what a pointer can reach, so an ordinary press then fails
@@ -3779,7 +3860,8 @@ export declare function stageMedia(options: MediaOptions): Promise<void>;
3779
3860
  * the shot replaces the node and takes any attribute of ours with it.
3780
3861
  *
3781
3862
  * The wait is two frames rather than a delay: the first carries the resize into layout and the
3782
- * second is the paint a screenshot reads.
3863
+ * second is the paint a screenshot reads. An already matching viewport needs no resize command;
3864
+ * the staging rule, paint waits, and rendered-size check still run.
3783
3865
  *
3784
3866
  * The viewport the tester had before this staging is written onto that rule element as the
3785
3867
  * {@link CAPTURE_PANE} value, in `<width>x<height>` form, and {@link releasePane} hands it back.
@@ -3819,7 +3901,9 @@ export declare interface StateOptions extends WaitOptions {
3819
3901
  * through the provider, reads the landing with {@link readActiveElement}, and leaves every decision
3820
3902
  * to the caller: what counts as an end, a revisit, or a stop is the consumer's, because the two
3821
3903
  * consumers disagree. The press is the next one only after the consumer asks for the next landing, so
3822
- * a consumer that stops reading stops pressing.
3904
+ * a consumer that stops reading stops pressing. A native segmented input can yield the same element
3905
+ * for successive segment landings. This generator preserves each landing; its consumers count that
3906
+ * control once while continuing through its segments, and end a run beyond {@link FOCUS_SEGMENT_LIMIT}.
3823
3907
  *
3824
3908
  * @example
3825
3909
  * ```ts
@@ -3853,6 +3937,20 @@ export declare interface StorageOptions {
3853
3937
  readonly quota?: number;
3854
3938
  }
3855
3939
 
3940
+ /**
3941
+ * Determines whether a native input exposes separately editable segments under one focused element.
3942
+ *
3943
+ * @param element - The element whose native input type is read in its own document's realm.
3944
+ * @returns True if the element is an input with a type in {@link SEGMENTED_INPUT_TYPES}, checked
3945
+ * against its own document's `HTMLInputElement`; false otherwise, including a document with no window.
3946
+ *
3947
+ * @example
3948
+ * ```ts
3949
+ * supportsSegmentedFocus(document.createElement('button')) // false
3950
+ * ```
3951
+ */
3952
+ export declare function supportsSegmentedFocus(element: Element): boolean;
3953
+
3856
3954
  /**
3857
3955
  * Taps an element's centre with emulated touch after its box settles.
3858
3956
  *
@@ -3887,7 +3985,10 @@ export declare function tapTouch(element: Element, options?: StabilityOptions):
3887
3985
  * @throws When one complete traversal cannot reach the target.
3888
3986
  *
3889
3987
  * @remarks
3890
- * The loop is {@link driveTraversal} over {@link resolveRendered}.
3988
+ * The loop is {@link driveTraversal} over {@link resolveRendered}, with a conservative name check
3989
+ * before each arrival resolution. Consecutive landings inside a
3990
+ * native segmented input continue through its segments up to {@link FOCUS_SEGMENT_LIMIT} landings.
3991
+ * A longer run or any other revisit ends the traversal.
3891
3992
  *
3892
3993
  * @example
3893
3994
  * ```ts
@@ -3908,7 +4009,8 @@ export declare function traverseAccessible(name: string): Promise<HTMLElement>;
3908
4009
  *
3909
4010
  * @remarks
3910
4011
  * The resolution is {@link resolveAccessibleWithin} and the loop is {@link driveTraversal}, so a
3911
- * twin of the same name earlier in the tab order is passed over rather than reached.
4012
+ * twin of the same name earlier in the tab order is passed over rather than reached. Candidates
4013
+ * retain the resolver's loose name match and must belong to a freshly resolved named region.
3912
4014
  *
3913
4015
  * @example
3914
4016
  * ```ts
@@ -3960,12 +4062,28 @@ export declare function typeAccessible(name: string, text: string): Promise<void
3960
4062
  */
3961
4063
  export declare function typeInput(element: HTMLInputElement | HTMLTextAreaElement, text: string): void;
3962
4064
 
4065
+ /**
4066
+ * Verifies a screenshot's destination and compares its returned bytes with the written file.
4067
+ *
4068
+ * @param shot - The provider's absolute path and base64 screenshot bytes.
4069
+ * @param path - The requested screenshot path, relative to the test file.
4070
+ * @param reader - The optional Node disk-digest command; omission uses Vitest's base64 read-back.
4071
+ * @throws Thrown when the destination differs, the bytes differ, or either reading fails.
4072
+ * @remarks Digest reads compare SHA-256 of the decoded shot with SHA-256 of the disk bytes.
4073
+ * Command failures propagate unchanged; they never select the base64 fallback.
4074
+ * @example
4075
+ * ```ts
4076
+ * await verifyFrame(shot, '../../tmp/frame.png', readCaptureReader())
4077
+ * ```
4078
+ */
4079
+ export declare function verifyFrame(shot: FrameShot, path: string, reader?: CaptureReader): Promise<void>;
4080
+
3963
4081
  /**
3964
4082
  * Waits until every finite animation on one element and its subtree has stopped moving.
3965
4083
  *
3966
4084
  * @param element - The element whose own animations and descendants' animations to wait on.
3967
4085
  * @param options - The time bounds and the abort signal.
3968
- * @returns A promise resolving once no finite animation is still running.
4086
+ * @returns A promise resolving after every finite animation has stopped running.
3969
4087
  * @throws An `Error` when the element is not in a document, when a bound is invalid, or when an
3970
4088
  * animation is still running at the budget; or the abort reason.
3971
4089
  *
@@ -4100,8 +4218,8 @@ export declare function waitForState(role: string, name: string, state: string,
4100
4218
  *
4101
4219
  * @param stop - Accepts the destination. Omit it to census the remaining document.
4102
4220
  * @returns Every element focus reached, in order and each once, the accepted stop last.
4103
- * @throws Thrown when the walk outlasts every element the page holds, a key press rejects, or focus
4104
- * lands in a frame from another origin.
4221
+ * @throws Thrown when the walk exceeds its press cap, a key press rejects, or focus lands in a
4222
+ * frame from another origin.
4105
4223
  *
4106
4224
  * @remarks
4107
4225
  * The walk records the focused element and then presses Tab through {@link stepFocus}, so it reaches
@@ -4110,8 +4228,14 @@ export declare function waitForState(role: string, name: string, state: string,
4110
4228
  * innermost focused element {@link readActiveElement} reads, so a control inside an open shadow root
4111
4229
  * or a same-origin frame is a stop of its own, and its host or frame element is not. The walk ends
4112
4230
  * with an empty list when only the body holds focus, and where focus revisits a stop or returns to
4113
- * the body. It applies no rule about which stop counts: the predicate sees each one and decides, so
4114
- * a consumer that refuses a hidden stop throws from its own predicate.
4231
+ * the body. Consecutive landings on the same native segmented input continue through its segments
4232
+ * up to {@link FOCUS_SEGMENT_LIMIT} landings, including the initial focused element, and count that
4233
+ * control once. A longer run or any other revisit, including a repeated button in a focus trap,
4234
+ * ends the walk. Any different landing starts a separate run.
4235
+ * The press cap is {@link FOCUS_SEGMENT_LIMIT} times {@link countElements}, including
4236
+ * open shadow roots and same-origin frames. It applies no rule about which stop counts: the
4237
+ * predicate sees each one and decides, so a consumer that refuses a hidden stop throws from its own
4238
+ * predicate.
4115
4239
  *
4116
4240
  * A closed shadow root cannot be entered, so its host stands for everything inside it, and a frame
4117
4241
  * from another origin is refused because its controls cannot be named.