@orkestrel/test 0.0.25 → 0.0.27

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.
@@ -23,11 +23,30 @@
23
23
  * @packageDocumentation
24
24
  */
25
25
 
26
+ import type { ChoiceOptions } from '@orkestrel/test';
27
+ import type { FixtureFile } from '@orkestrel/test';
26
28
  import type { JourneyVariant } from '@orkestrel/test';
27
29
  import type { StatechartStatus } from '@orkestrel/test';
28
30
  import type { StateScenario } from '@orkestrel/test';
29
31
  import type { WaitOptions } from '@orkestrel/test';
30
32
 
33
+ /**
34
+ * Represents the accessibility node the browser computed for one element.
35
+ *
36
+ * @remarks
37
+ * The values are the browser's own computation, which is what separates this from the DOM-based
38
+ * `readRole`, `readName`, and `readStates` readings: the browser applies every naming and role rule
39
+ * itself, so the node is what an assistive technology is handed.
40
+ */
41
+ export declare interface AccessibilityNode {
42
+ /** Holds the computed role, or `undefined` when the node states none. */
43
+ readonly role: string | undefined;
44
+ /** Holds the computed accessible name, or `undefined` when the node states none. */
45
+ readonly name: string | undefined;
46
+ /** Maps each property name to its value; an ID reference reads as the list of referenced IDs. */
47
+ readonly properties: Readonly<Record<string, unknown>>;
48
+ }
49
+
31
50
  /**
32
51
  * Names the interactive ARIA roles a bare accessible name is searched across.
33
52
  *
@@ -38,6 +57,20 @@ import type { WaitOptions } from '@orkestrel/test';
38
57
  */
39
58
  export declare const ACCESSIBLE_ROLES: readonly string[];
40
59
 
60
+ /**
61
+ * Represents the animations running on one element and its subtree, split by whether each one ends.
62
+ *
63
+ * @remarks
64
+ * An animation counts as endless when its effect declares infinite iterations. A paused, an idle,
65
+ * and a finished animation are at rest, so neither list holds one.
66
+ */
67
+ export declare interface AnimationReading {
68
+ /** Lists the running animations that end, the ones `waitForAnimations` waits on. */
69
+ readonly finite: readonly Animation[];
70
+ /** Lists the running animations whose effect declares infinite iterations. */
71
+ readonly endless: readonly Animation[];
72
+ }
73
+
41
74
  /**
42
75
  * Composites one color over another.
43
76
  *
@@ -274,18 +307,22 @@ export declare const CAPTURE_STAGINGS = 4;
274
307
  * `Capture frame at <path> never settled after <n> restagings: <h> over a <h> pane` rather than
275
308
  * written at a height that is already wrong.
276
309
  *
277
- * Omit the `element` option to shoot the whole page. An element frame no taller than the declared
278
- * height is shot with the pane at the declared size, so every viewport length resolves against the
279
- * declared viewport, whether the element sits in flow above the fold, in flow below it,
280
- * or fixed. The re-reading takes the element's own height in place of the content edge, so the pane
281
- * grows only for an element taller than the declared height, and then to that element's height,
282
- * which is the geometry its viewport lengths resolve against. An element that outgrows every pane
283
- * is refused with the same text.
310
+ * Omit the `element` option to shoot the whole page. An element that fits with its native scroll
311
+ * clearance is shot in the declared pane, as is a short fixed panel that native alignment cannot
312
+ * move. A sticky subject with a vertical start inset also keeps that pane when native end alignment
313
+ * fits its box inside it; adding the start clearance would instead grow its viewport constraint.
314
+ * These subjects' viewport lengths resolve against the declared viewport. Otherwise native start
315
+ * alignment resolves the document's scroll clearance before the re-reading takes the element's
316
+ * height plus the space above its aligned top. This includes an element shorter than the declared
317
+ * pane whose height plus clearance exceeds it. The pane reserves room below authored scroll
318
+ * padding and target scroll margins without interpreting CSS lengths or hiding overlays.
319
+ * Clearance that changes with the viewport participates in the same bounded settling loop; a
320
+ * frame that has not settled within that bound is refused with the same text.
284
321
  *
285
322
  * Where the element's box lies outside the pane, the tester's document is scrolled by the nearest
286
323
  * distance that would bring it inside, and the box is read again. A fixed element past the pane can
287
- * take a scroll that does not move it, and that scroll is handed back with the rest. The document is
288
- * not scrolled for an element already inside the pane.
324
+ * take a scroll that does not move it, and that scroll is handed back with the rest. Other short
325
+ * elements keep their nearest native alignment when they need no additional room.
289
326
  *
290
327
  * The provider paints an element that fits the runner's window only where that window shows it.
291
328
  * Where such an element lies past the window, the calling tester frame is offset up or left only as
@@ -367,6 +404,23 @@ export declare interface CensusReading {
367
404
  readonly undeclared: readonly string[];
368
405
  }
369
406
 
407
+ /**
408
+ * Activates a labeled native file input and fulfills its observed chooser with fixture bytes.
409
+ *
410
+ * @param name - The input's exact accessible label.
411
+ * @param files - The fixture selection; an empty collection clears the selection, not an OS Cancel gesture.
412
+ * @param options - The activation method and provider wait budget.
413
+ * @returns A promise resolving after the correct native chooser receives the fixture selection.
414
+ * @throws When the input is refused, the provider command is unregistered, or the expected chooser does not open.
415
+ * @remarks Register the server entry's `chooseFiles` function as the `chooseFiles` command in the workspace's
416
+ * `configs/commands.ts`, which the root configuration passes to every browser project.
417
+ * @example
418
+ * ```ts
419
+ * await chooseAccessible('Attachments', [{ name: 'note.txt', mime: 'text/plain', bytes: [72, 105] }])
420
+ * ```
421
+ */
422
+ export declare function chooseAccessible(name: string, files: readonly FixtureFile[], options?: ChoiceOptions): Promise<void>;
423
+
370
424
  /**
371
425
  * Clears both browser storage surfaces.
372
426
  *
@@ -476,6 +530,82 @@ export declare function clickDisclosure(name: string): Promise<void>;
476
530
  */
477
531
  export declare function clipsOverflow(element: Element): boolean;
478
532
 
533
+ /**
534
+ * Collects the ancestors of an element that clip their descendants' overflow.
535
+ *
536
+ * @param element - The element whose ancestors to read.
537
+ * @returns Every ancestor element for which the {@link clipsOverflow} helper reports true, nearest
538
+ * first, and an empty list where the element has none.
539
+ * @throws Thrown when the element is not connected to a document, because a disconnected element
540
+ * resolves no style and its ancestors would all read as clipping.
541
+ *
542
+ * @remarks
543
+ * The walk climbs the flat tree, the tree a browser paints. A step goes to the slot an element is
544
+ * assigned to, else to its parent element, else to the host of the shadow root it stands in. So the
545
+ * wrapper around a slot clips the child assigned to that slot, a shadow tree's wrappers clip what
546
+ * stands in it and then what its host stands in, and the walk ends at the root element, which has
547
+ * none of the three. The `assignedSlot` property reports no slot of a closed shadow root, so a
548
+ * child assigned into one climbs through its light parent instead. The element itself is not one of
549
+ * its own ancestors. Each step returns its own parent's frame, if it is one, ahead of the frames
550
+ * above it, so the depth of the flat tree bounds the recursion.
551
+ *
552
+ * @example
553
+ * ```ts
554
+ * collectClippingAncestors(bar) // [frame] where a hidden-overflow frame wraps the bar
555
+ * ```
556
+ */
557
+ export declare function collectClippingAncestors(element: Element): readonly Element[];
558
+
559
+ /**
560
+ * Collects the rendered boxes a person can scroll.
561
+ *
562
+ * @param root - The element whose subtree is searched, the root included.
563
+ * @param axis - The scroll axis to keep: `'inline'` for boxes that scroll across, `'block'` for
564
+ * boxes that scroll down. Omit it to keep both.
565
+ * @returns Each rendered element, in document order, whose resolved overflow scrolls on a searched
566
+ * axis where its content is larger than its box.
567
+ *
568
+ * @remarks
569
+ * A screenshot shows no scrollbar where the browser overlays them, so a frame alone never tells
570
+ * that a pane scrolls or how far. A box counts when its `overflow-x` or `overflow-y` value is the
571
+ * `auto` keyword or the `scroll` keyword and its content overflows on that axis; a `hidden` or
572
+ * `clip` box cuts its content without letting anyone scroll it, and a box whose content fits has
573
+ * nowhere to go. An element that {@link isRendered} reports false for is left out, because a person
574
+ * cannot scroll a box the page does not show.
575
+ *
576
+ * @example
577
+ * ```ts
578
+ * collectScrollRegions(document.documentElement).map((region) => region.id)
579
+ * collectScrollRegions(document.documentElement, 'inline').map((region) => region.id)
580
+ * ```
581
+ */
582
+ export declare function collectScrollRegions(root: Element, axis?: 'inline' | 'block'): readonly HTMLElement[];
583
+
584
+ /**
585
+ * Collects the elements of a region that a forward Tab walk reaches from a starting element.
586
+ *
587
+ * @param root - The region whose stops are collected; the walk ends where focus leaves it.
588
+ * @param start - The element that takes focus first. It is not a stop, and it need not sit in
589
+ * the region.
590
+ * @returns The region's Tab stops in order, including a scroll container Chromium focuses
591
+ * automatically.
592
+ * @throws Thrown when `start` cannot take focus, and whatever {@link walkFocus} throws.
593
+ *
594
+ * @remarks
595
+ * The walk is {@link walkFocus} from `start` with the region's edge as its stop, so a stop outside
596
+ * `root` ends the walk and is left out of the result. A stop belongs to the region by
597
+ * {@link containsNode}, so a control inside an open shadow root or a same-origin frame that `root`
598
+ * holds is in the region, and `start` may sit inside one. A `start` that sits outside the region,
599
+ * as the control immediately before it, is the walk's origin and never its end, so the first Tab into the
600
+ * region reaches its first stop.
601
+ *
602
+ * @example
603
+ * ```ts
604
+ * const stops = await collectTabStops(screen, heading)
605
+ * ```
606
+ */
607
+ export declare function collectTabStops(root: Element, start: HTMLElement): Promise<readonly HTMLElement[]>;
608
+
479
609
  /**
480
610
  * Represents one rendered color as straight sRGB channels and its alpha.
481
611
  *
@@ -562,6 +692,26 @@ export declare function computeNamePattern(name: string): RegExp;
562
692
  */
563
693
  export declare function computeOffset(box: DOMRectReadOnly, width: number, height: number): FrameOffset;
564
694
 
695
+ /**
696
+ * Determines whether a node sits inside a root, through open shadow roots and frames.
697
+ *
698
+ * @param root - The node that bounds the region.
699
+ * @param node - The node to place.
700
+ * @returns `true` when `node` is `root` or a descendant of it, counting a shadow root's content as
701
+ * its host's and a frame's content as its frame element's.
702
+ *
703
+ * @remarks
704
+ * `contains` stops at a shadow root and at a frame, so a control inside a component reads as outside
705
+ * the region that holds the component. This climbs from the node to its host or its frame element
706
+ * until `contains` answers or the page's top is reached.
707
+ *
708
+ * @example
709
+ * ```ts
710
+ * containsNode(region, readActiveElement() ?? region)
711
+ * ```
712
+ */
713
+ export declare function containsNode(root: Node, node: Node): boolean;
714
+
565
715
  /**
566
716
  * Names the roles whose accessible name is the text a reader can see inside them.
567
717
  *
@@ -589,6 +739,22 @@ export declare interface ContrastFixture {
589
739
  readonly accepted: HTMLElement;
590
740
  }
591
741
 
742
+ /**
743
+ * Configures one color contrast reading: the surface the backdrop walk ends on, and the opacity the
744
+ * painted color is shown at.
745
+ *
746
+ * @remarks
747
+ * Omit `floor` to refuse a stack whose walk reaches no opaque layer, exactly as `readContrast` does.
748
+ * `opacity` multiplies the color's own alpha before it is composited, so a mark painted in a
749
+ * translucent element reads at the strength a reader sees.
750
+ */
751
+ export declare interface ContrastOptions {
752
+ /** Holds the opaque color the backdrop walk ends on when nothing above it paints. */
753
+ readonly floor?: Color;
754
+ /** Holds the factor, from `0` to `1`, the color's alpha is multiplied by. Default: `1`. */
755
+ readonly opacity?: number;
756
+ }
757
+
592
758
  /**
593
759
  * Converts encoded A98 RGB channels to clipped sRGB paint channels.
594
760
  *
@@ -776,6 +942,25 @@ export declare function convertXYZD50(x: number, y: number, z: number, alpha?: n
776
942
  */
777
943
  export declare function convertXYZD65(x: number, y: number, z: number, alpha?: number): Color;
778
944
 
945
+ /**
946
+ * Counts the elements a tree holds, descending into open shadow roots and same-origin frames.
947
+ *
948
+ * @param root - The document or open shadow root to count. Default: the page's document.
949
+ * @returns How many elements the tree holds, each host and frame element included.
950
+ *
951
+ * @remarks
952
+ * `querySelectorAll('*')` stops at the first boundary, so it undercounts a page built from shadow
953
+ * roots. A frame from another origin and a closed shadow root hold nothing the page can count, so
954
+ * each counts as its own element only. The number bounds a walk that visits each element once, which
955
+ * is how {@link walkFocus} knows a Tab order that never ends.
956
+ *
957
+ * @example
958
+ * ```ts
959
+ * countElements(host.shadowRoot)
960
+ * ```
961
+ */
962
+ export declare function countElements(root?: Document | ShadowRoot): number;
963
+
779
964
  /**
780
965
  * Creates one console channel that records every call it receives and hands that call on unchanged.
781
966
  *
@@ -818,8 +1003,11 @@ export declare function createChannel(name: string, output: string[], forward: (
818
1003
  * The platform declares the `dataTransfer` member on the constructed event as nullable, so calling
819
1004
  * code still narrows it even though this always supplies one.
820
1005
  *
821
- * `bubbles` and `cancelable` are set, because a drop handler that never prevents the default event
822
- * is a drop the browser handles itself.
1006
+ * `bubbles`, `cancelable`, and `composed` are set, because a drop handler that never prevents the
1007
+ * default event is a drop the browser handles itself, and a drag a browser raises inside an open
1008
+ * shadow root is heard outside it. `composed` defaults to `true` from 0.0.27; 0.0.26 left it
1009
+ * `false`, so an event dispatched inside an open shadow root stayed there. A listener outside that
1010
+ * root hears the event, and `{ composed: false }` restores the 0.0.26 boundary behavior.
823
1011
  *
824
1012
  * @example
825
1013
  * ```ts
@@ -909,6 +1097,31 @@ export declare function createHarness<TState extends string, TEvent extends stri
909
1097
  */
910
1098
  export declare function createJournal(): JournalInterface;
911
1099
 
1100
+ /**
1101
+ * Creates one real keyboard event, ready to dispatch.
1102
+ *
1103
+ * @param name - The event type, such as `keydown`.
1104
+ * @param options - Any `KeyboardEventInit` member, each one overriding the default beneath it.
1105
+ * @returns A real `KeyboardEvent` of that type.
1106
+ *
1107
+ * @remarks
1108
+ * A bare `new KeyboardEvent('keydown')` neither bubbles nor can be cancelled, and it stops at the
1109
+ * first shadow root it meets, so a delegated listener never hears it and `preventDefault` does
1110
+ * nothing, which is the shape that passes in a test and fails in a browser. `bubbles`, `cancelable`,
1111
+ * and `composed` are set, as a browser's own key event carries them. Override any of them by naming
1112
+ * it; every other member, such as `key`, `code`, and the modifiers, is the platform's own and is
1113
+ * named in `options`.
1114
+ *
1115
+ * The event is real rather than a shaped object, so `instanceof KeyboardEvent` holds and the members
1116
+ * a handler reads are the ones the platform defines.
1117
+ *
1118
+ * @example
1119
+ * ```ts
1120
+ * element.dispatchEvent(createKeyboardEvent('keydown', { key: 'Escape' }))
1121
+ * ```
1122
+ */
1123
+ export declare function createKeyboardEvent(name: string, options?: KeyboardEventInit): KeyboardEvent;
1124
+
912
1125
  /**
913
1126
  * Creates one real pointer event, ready to dispatch.
914
1127
  *
@@ -918,10 +1131,15 @@ export declare function createJournal(): JournalInterface;
918
1131
  *
919
1132
  * @remarks
920
1133
  * The defaults are what a browser's own pointer event carries and a hand-built one does not:
921
- * `bubbles` and `cancelable` are set, so a delegated listener hears it and a handler can prevent it,
922
- * and `pointerId`, `pointerType`, and `isPrimary` describe a single primary mouse, so a component
923
- * that branches on the pointer kind takes the branch a mouse takes. Override any of them by naming
924
- * it; a touch is `{ pointerType: 'touch' }` and nothing else has to be restated.
1134
+ * `bubbles`, `cancelable`, and `composed` are set, so a delegated listener hears it, a handler can
1135
+ * prevent it, and a listener outside an open shadow root hears one dispatched inside it, and
1136
+ * `pointerId`, `pointerType`, and `isPrimary` describe a single primary mouse, so a component that
1137
+ * branches on the pointer kind takes the branch a mouse takes. Override any of them by naming it; a
1138
+ * touch is `{ pointerType: 'touch' }` and nothing else has to be restated.
1139
+ *
1140
+ * `composed` defaults to `true` from 0.0.27; 0.0.26 left it `false`, so an event dispatched inside an
1141
+ * open shadow root stayed there. A listener outside that root hears the event, and
1142
+ * `{ composed: false }` restores the 0.0.26 boundary behavior.
925
1143
  *
926
1144
  * The event is real rather than a shaped object, so `instanceof PointerEvent` holds and the
927
1145
  * coordinate and modifier members a handler reads are the ones the platform defines.
@@ -934,7 +1152,7 @@ export declare function createJournal(): JournalInterface;
934
1152
  export declare function createPointerEvent(name: string, options?: PointerEventInit): PointerEvent;
935
1153
 
936
1154
  /**
937
- * Creates the capture portfolio one run places its screenshots through.
1155
+ * Creates the capture portfolio one run places its screenshots through; a disabled run still refuses.
938
1156
  *
939
1157
  * @param options - The state registry, the variant matrix, the variant this run renders, the
940
1158
  * directory it writes into, and whether it writes at all.
@@ -943,9 +1161,11 @@ export declare function createPointerEvent(name: string, options?: PointerEventI
943
1161
  *
944
1162
  * @remarks
945
1163
  * A disabled portfolio is the ordinary run. `place` then resizes nothing, writes nothing, and
946
- * records nothing, so a journey calls it unconditionally and a suite with the flag unset pays for
947
- * none of it. The portfolio refuses an unregistered variant at creation. An enabled run refuses an
948
- * unregistered state name and a second placement of one state.
1164
+ * records no placement, so a journey calls it unconditionally and a suite with the flag unset pays
1165
+ * for none of it. The portfolio refuses an unregistered variant at creation. Every run, enabled or not,
1166
+ * refuses an unregistered state name and a second placement of one state, so a wrong name fails the
1167
+ * ordinary run. A disabled run keeps the names it has seen apart from `placements`, which stays
1168
+ * empty.
949
1169
  *
950
1170
  * An enabled `place` writes through `captureFrame`, so a placed state carries that helper's staged
951
1171
  * pane and its byte readback: a path is recorded only after the file on disk has been proved to hold
@@ -1030,6 +1250,27 @@ export declare function createStorage(options?: StorageOptions): WebStorageInter
1030
1250
  */
1031
1251
  export declare function describeFocus(element: Element): string;
1032
1252
 
1253
+ /**
1254
+ * Describes the window's scroll position and each scroll region's offsets and extents.
1255
+ *
1256
+ * @param regions - The regions to describe, as {@link collectScrollRegions} returns them.
1257
+ * @returns One line for the window, then one line per region with each offset beside the largest
1258
+ * offset that region reaches, or a line saying no region overflows.
1259
+ *
1260
+ * @remarks
1261
+ * The window line reads `window <w>x<h> scroll <x>,<y> of <x>,<y>`. Each region line reads
1262
+ * `scroll <tag>#<id> "<name>": left <x>/<x> top <y>/<y> box <w>x<h> content <w>x<h>`, where the id
1263
+ * and the accessible name appear only when the region carries them and the name is cut to 40
1264
+ * characters. Record it beside a frame, so the journey's output says which panes scroll and where
1265
+ * each one stood when the picture was taken.
1266
+ *
1267
+ * @example
1268
+ * ```ts
1269
+ * describeScrollRegions(collectScrollRegions(document.documentElement))
1270
+ * ```
1271
+ */
1272
+ export declare function describeScrollRegions(regions: readonly HTMLElement[]): string;
1273
+
1033
1274
  /**
1034
1275
  * Describes the accessible tree one rendered element presents.
1035
1276
  *
@@ -1072,9 +1313,10 @@ export declare function describeTree(element: Element): string;
1072
1313
  * @remarks
1073
1314
  * This is the one pointer drive every hold verb shares: the held-marker refusal, a scroll that
1074
1315
  * brings a wholly off-viewport target into view and a refusal for one that stays outside, the
1075
- * centre mapped through the tester iframe's painted scale into page coordinates, the trusted move
1076
- * and press, the marker, and the frame wait and the `:active` read-back that both release before
1077
- * refusing. The refusal precedes resolution, so a double hold is refused before an absent name is.
1316
+ * centre projected through every frame into page coordinates by {@link readProtocolPoint}, the
1317
+ * trusted move and press, the marker, and the frame wait and the `:active` read-back that both
1318
+ * release before refusing. The refusal precedes resolution, so a double hold is refused before an
1319
+ * absent name is.
1078
1320
  *
1079
1321
  * @example
1080
1322
  * ```ts
@@ -1095,9 +1337,9 @@ export declare function driveHold(resolve: () => HTMLElement, name: string): Pro
1095
1337
  * @throws When the resolver refuses, or one complete traversal cannot reach the target.
1096
1338
  *
1097
1339
  * @remarks
1098
- * This is the one loop every traversal verb shares. A step counts only when focus lands on an
1099
- * element, the traversal is over when focus revisits one, and the cap is counted off
1100
- * {@link FOCUSABLE_SELECTOR}.
1340
+ * This is the one loop every traversal verb shares, over {@link stepFocus}. A step counts only when
1341
+ * focus lands on an element, the traversal is over when focus revisits one, and the cap is counted
1342
+ * off {@link FOCUSABLE_SELECTOR}.
1101
1343
  *
1102
1344
  * @example
1103
1345
  * ```ts
@@ -1731,8 +1973,9 @@ export declare function matchesColor(first: string | Color, second: string | Col
1731
1973
  *
1732
1974
  * Each element contributes its client rectangle's bottom edge in document coordinates plus its own
1733
1975
  * bottom margin, which sits outside that rectangle, and the largest contribution wins. An ancestor
1734
- * that clips its overflow caps the contribution at that ancestor's clip edge, which the
1735
- * {@link readClipEdge} helper measures, because the rows a descendant lays out past a clipping
1976
+ * that clips its overflow, which the {@link collectClippingAncestors} helper finds through the flat
1977
+ * tree and so reaches a shadow wrapper around a slot, caps the contribution at that ancestor's clip
1978
+ * edge, which the {@link readClipEdge} helper measures, because the rows a descendant lays out past a clipping
1736
1979
  * frame are cut, scrolled, or discarded rather than added to the document: a viewport-height
1737
1980
  * specimen inside a bounded frame ends, for this reading, where the frame ends, so a taller pane
1738
1981
  * does not read back as a taller document. The clip edge of a `clip` overflow, and of a paint
@@ -1835,6 +2078,53 @@ export declare interface MediaOptions {
1835
2078
  */
1836
2079
  export declare function mount<T extends Element>(element: T): T;
1837
2080
 
2081
+ /**
2082
+ * Decodes a base64 PNG and paints it, unscaled, onto a fresh offscreen 2D canvas.
2083
+ *
2084
+ * @param encoded - The image's bytes as base64 text, without a data-URL prefix.
2085
+ * @returns The canvas's 2D context, whose `canvas` holds the image's size in device pixels, or
2086
+ * `undefined` when the browser hands out no 2D context.
2087
+ * @throws The decode failure, as the rejection of the image's own `decode` call, when the bytes are
2088
+ * not an image this browser decodes.
2089
+ *
2090
+ * @remarks
2091
+ * This is the decode and the draw that {@link readFrame} and {@link readShotPixel} share, which
2092
+ * leaves each of them its own words for a refusal: a frame names the path it was read from and the
2093
+ * size its header declares, and a shot names neither. The decode failure is handed on unchanged so
2094
+ * the caller can read the bytes it rejected, and the missing context is a value rather than a throw
2095
+ * for the same reason. The image is drawn at its natural size, so the canvas holds one canvas pixel
2096
+ * for each device pixel of the image.
2097
+ *
2098
+ * @example
2099
+ * ```ts
2100
+ * const context = await paintImage(encoded)
2101
+ * const [red, green, blue] = context?.getImageData(0, 0, 1, 1).data ?? []
2102
+ * ```
2103
+ */
2104
+ export declare function paintImage(encoded: string): Promise<OffscreenCanvasRenderingContext2D | undefined>;
2105
+
2106
+ /**
2107
+ * Parks the pointer outside the page and waits for the parked pointer's frame to paint.
2108
+ *
2109
+ * @returns A promise resolving after the pointer has moved to its park point and one frame has painted.
2110
+ * @throws Thrown when the provider exposes no DevTools session, or the move rejects.
2111
+ *
2112
+ * @remarks
2113
+ * The park point is (-1, -1) in the runner page's coordinates, one pixel above and to the left of
2114
+ * that page's viewport. The browser hit-tests nothing outside the viewport, so no element keeps its
2115
+ * hover paint from the parked pointer. This sends no button release: a press that the
2116
+ * `holdAccessible` verb holds stays recorded as held and its button-up is still owed, so a later
2117
+ * `releasePointer` call sends it. The control a held press was on loses its `:active` paint when the
2118
+ * pointer leaves it. Use this verb to clear hover without ending a held press, and
2119
+ * `releasePointer` for teardown.
2120
+ *
2121
+ * @example
2122
+ * ```ts
2123
+ * await parkPointer()
2124
+ * ```
2125
+ */
2126
+ export declare function parkPointer(): Promise<void>;
2127
+
1838
2128
  /**
1839
2129
  * Parses computed CSS Color 4 values into clipped straight sRGB channels.
1840
2130
  *
@@ -1863,34 +2153,55 @@ export declare function parseColor(value: string): Color | undefined;
1863
2153
  *
1864
2154
  * @param value - Any value the `color` property accepts: a keyword, a hex triple, a `var()`
1865
2155
  * reference, a `color-mix()`, or a computed CSS Color 4 value.
1866
- * @returns The resolved color's channels, or `undefined` when the CSSOM refuses the value or the
1867
- * computed result names no color {@link parseColor} speaks.
2156
+ * @param scope - The element whose cascade the expression resolves in. Omit it to resolve at the
2157
+ * document's body.
2158
+ * @returns The resolved color's channels, or `undefined` when the CSSOM refuses the value, the
2159
+ * computed result names no color {@link parseColor} speaks, or the scope is disconnected and
2160
+ * computes no style.
1868
2161
  *
1869
2162
  * @remarks
1870
2163
  * This is the live half of the pair {@link parseColor} opens. `parseColor` reads text and speaks
1871
- * only the computed syntaxes a cascade hands back; this stages a probe element, hands it to the real
1872
- * cascade, and reads back what the engine computed — which is the only way a keyword, a hex triple,
1873
- * or a `var()` reference becomes channels at all. The read itself goes through `parseColor`, so both
2164
+ * only the computed syntaxes a cascade hands back; this hands the expression to the real cascade
2165
+ * and reads back what the engine computed — which is the only way a keyword, a hex triple, or a
2166
+ * `var()` reference becomes channels at all. The read itself goes through `parseColor`, so both
1874
2167
  * halves agree on what a computed value means.
1875
2168
  * Modern perceptual and predefined RGB/XYZ spaces resolve through that parser's conversions;
1876
2169
  * out-of-gamut sRGB channels are clipped to 0–255 after conversion.
1877
2170
  *
1878
- * The probe is mounted, because an unmounted element inherits nothing and a `var()` reference to a
1879
- * token declared on `:root` would resolve to the initial value instead. It is removed in a `finally`,
1880
- * so a value that throws on the way through leaves no node behind.
2171
+ * With no scope the expression resolves on a probe that is a child of `document.body`, mounted
2172
+ * because an unmounted element inherits nothing, so a `var()` reference or `currentColor` resolves
2173
+ * against what the body declares and paints. The probe is removed in a `finally`, so a value that
2174
+ * throws on the way through leaves no node behind.
2175
+ *
2176
+ * With a scope the expression resolves on that same body-mounted probe, which carries the scope's
2177
+ * computed context onto its own inline style: the computed value of every custom property the
2178
+ * expression names, a fallback's included, the scope's computed `color`, and its computed
2179
+ * `color-scheme`. The expression is written into `background-color`, so `currentColor` is the
2180
+ * carried `color`, and a system color or `light-dark()` answers as the scope's scheme. The element's
2181
+ * own and inherited custom properties therefore apply, a registered property that does not inherit
2182
+ * included, and an `input`, an SVG element, or any other element resolves like any other. A custom
2183
+ * property is named by letters, digits, `_`, and `-` after its `--`. A name the scope leaves
2184
+ * undeclared is not carried, so its `var()` fallback still applies.
2185
+ *
2186
+ * The scope element is never written. The probe is new, so it has no earlier style to start a
2187
+ * transition from, and a transition running on the scope keeps running: `currentColor` reads the
2188
+ * color the scope shows at that moment, and the scope's geometry and scroll position stay as they
2189
+ * were. No attribute, style, or child of the scope changes, so a `MutationObserver` on it records
2190
+ * nothing.
1881
2191
  *
1882
- * Refusal is the CSSOM's: an expression it will not parse leaves the probe's inline `color` empty
1883
- * and this returns `undefined`. A `var()` naming an undeclared custom property is not refused,
1884
- * because the cascade accepts it and computes the inherited color, so a test that means to catch a
2192
+ * Refusal is the CSSOM's: an expression it will not parse leaves the probe's declaration empty and
2193
+ * this returns `undefined`. A `var()` naming an undeclared custom property is not refused, because
2194
+ * the cascade accepts it and computes the inherited color, so a test that means to catch a
1885
2195
  * missing token asserts on {@link readToken} rather than on this.
1886
2196
  *
1887
2197
  * @example
1888
2198
  * ```ts
1889
2199
  * parseCSSColor('rebeccapurple') // [102, 51, 153, 1]
1890
2200
  * parseCSSColor('not-a-color') // undefined
2201
+ * parseCSSColor('var(--ink)', panel) // the token as the panel declares it
1891
2202
  * ```
1892
2203
  */
1893
- export declare function parseCSSColor(value: string): Color | undefined;
2204
+ export declare function parseCSSColor(value: string, scope?: Element): Color | undefined;
1894
2205
 
1895
2206
  /**
1896
2207
  * Names the tester root's attribute holding the pressed pointer's page coordinates.
@@ -1973,6 +2284,93 @@ export declare interface PortfolioOptions {
1973
2284
  */
1974
2285
  export declare function pressKeys(keys: string): Promise<void>;
1975
2286
 
2287
+ /**
2288
+ * Represents one point in the coordinates of the browser's top-level viewport, the space a DevTools
2289
+ * input command addresses.
2290
+ *
2291
+ * @remarks
2292
+ * As an input to {@link readProtocolPoint}, the same shape names an offset from the element's
2293
+ * top-left corner, in the element's own pixels.
2294
+ */
2295
+ export declare interface ProtocolPoint {
2296
+ /** Holds the distance from the left edge, in CSS pixels. */
2297
+ readonly x: number;
2298
+ /** Holds the distance from the top edge, in CSS pixels. */
2299
+ readonly y: number;
2300
+ }
2301
+
2302
+ /**
2303
+ * Reads the accessibility node the browser computed for one element.
2304
+ *
2305
+ * @param element - The connected element to read.
2306
+ * @returns A promise resolving to the node's role, name, and properties.
2307
+ * @throws Thrown when the provider exposes no DevTools session, a command fails, or the element is
2308
+ * not the one connected element {@link readProtocolNode} finds.
2309
+ *
2310
+ * @remarks
2311
+ * This is the browser's own computation, which complements the DOM-based `readRole`, `readName`, and
2312
+ * `readStates`: those apply this package's mapping to the markup, and this asks the browser what it
2313
+ * published. A property whose value names other nodes reads as the list of their ids, and a value the
2314
+ * browser states plainly reads as that value.
2315
+ *
2316
+ * @example
2317
+ * ```ts
2318
+ * const node = await readAccessibilityNode(input)
2319
+ * node.name // 'Port'
2320
+ * ```
2321
+ */
2322
+ export declare function readAccessibilityNode(element: Element): Promise<AccessibilityNode>;
2323
+
2324
+ /**
2325
+ * Reads the HTML element that holds focus, following it into open shadow roots and same-origin
2326
+ * frames.
2327
+ *
2328
+ * @param root - The document or open shadow root to read from. Default: the page's document.
2329
+ * @returns The innermost focused element when it is an HTML element of its own window, or
2330
+ * `undefined` when only a body, a non-HTML element, or nothing holds focus.
2331
+ * @throws Thrown when focus sits in a frame from another origin, whose document the page cannot
2332
+ * reach.
2333
+ *
2334
+ * @remarks
2335
+ * `document.activeElement` stops at the first boundary: it names the host of a shadow root or the
2336
+ * element of a frame, never the control focused inside. This follows `shadowRoot.activeElement` and
2337
+ * a frame's `contentDocument.activeElement` until neither names a deeper element, so a host or a
2338
+ * frame holding focus with nothing focused inside is itself the answer. A closed shadow root cannot
2339
+ * be followed, so its host is the answer there. When the innermost focused element is not HTML, as
2340
+ * an SVG element focused inside an open shadow root, the answer is `undefined`: the host that holds
2341
+ * it is not where focus is.
2342
+ *
2343
+ * A frame from another origin is refused rather than answered with its element, because the answer
2344
+ * would name a frame while focus sat on a control the page cannot see. The element comes back typed
2345
+ * for its own window, so a control inside a frame passes the frame's `HTMLElement` check and not
2346
+ * this window's.
2347
+ *
2348
+ * @example
2349
+ * ```ts
2350
+ * readActiveElement()?.textContent
2351
+ * ```
2352
+ */
2353
+ export declare function readActiveElement(root?: Document | ShadowRoot): HTMLElement | undefined;
2354
+
2355
+ /**
2356
+ * Reads the animations running on one element and its subtree, split by whether each one ends.
2357
+ *
2358
+ * @param element - The element whose own animations and descendants' animations to read.
2359
+ * @returns The running animations that end, and the running animations whose effect declares
2360
+ * infinite iterations.
2361
+ *
2362
+ * @remarks
2363
+ * The split is the one {@link waitForAnimations} waits by: it waits on `finite` and leaves
2364
+ * `endless` running. A paused, an idle, and a finished animation are at rest, so neither
2365
+ * list holds one. A detached element runs no animation and reads as two empty lists.
2366
+ *
2367
+ * @example
2368
+ * ```ts
2369
+ * readAnimations(document.documentElement).finite.length // 0 once every transition has settled
2370
+ * ```
2371
+ */
2372
+ export declare function readAnimations(element: Element): AnimationReading;
2373
+
1976
2374
  /**
1977
2375
  * Resolves the opaque color standing behind one element.
1978
2376
  *
@@ -2020,6 +2418,14 @@ export declare function readBackdrop(element: Element, floor: Color): Color;
2020
2418
  * stack and inserted the deepest rule first. Iterate the set where the order is the subject, and
2021
2419
  * read `has` where membership is.
2022
2420
  *
2421
+ * Each rule's selector text is read by {@link collectSelectorClasses}, so the tokens are the class
2422
+ * names a selector means rather than what a pattern over its text finds: an escaped name decodes,
2423
+ * so `.sm\:flex` defines `sm:flex` rather than `sm`; text inside an attribute value, a string, or
2424
+ * a comment defines nothing, so `[title=".card"]` defines no `card`; and a name opening with an
2425
+ * underscore, a hyphen, or a non-ASCII letter counts, and a non-ASCII letter inside a name stays in
2426
+ * it, so `.café` defines `café` where 0.0.26 ended the class at the first code point outside ASCII
2427
+ * letters, digits, `_`, and `-` and defined `caf`. One rule's own tokens enter in code-unit order.
2428
+ *
2023
2429
  * `@keyframes` children are outside that walk, so an animation's own rules define no token here.
2024
2430
  * Reach the animation itself through {@link findKeyframes}.
2025
2431
  *
@@ -2133,6 +2539,77 @@ export declare function readClipEdge(element: Element): number | undefined;
2133
2539
  */
2134
2540
  export declare function readClipMargin(element: Element): number;
2135
2541
 
2542
+ /**
2543
+ * Measures the block size an element shows after every clipping ancestor cuts it.
2544
+ *
2545
+ * @param element - The element to read.
2546
+ * @returns The height in CSS pixels of the part of the element's box that lies inside the clip of
2547
+ * every ancestor that clips its overflow, and `0` where none of it does.
2548
+ * @throws Thrown when the element is not connected to a document.
2549
+ *
2550
+ * @remarks
2551
+ * The `getBoundingClientRect` method reports the whole box of a clipped element, so a bar taller
2552
+ * than its frame still reads its own height there; this reading is the height a person sees. An
2553
+ * ancestor clips where the {@link clipsOverflow} helper says so, and the {@link collectClippingAncestors}
2554
+ * helper finds it through the flat tree, so a wrapper in a shadow tree around the element or around
2555
+ * its slot counts. Its top edge is the top of its
2556
+ * padding box, and its bottom edge is the one the {@link readClipEdge} helper measures, so a paint
2557
+ * containment and an `overflow-clip-margin` length count. That edge comes in document coordinates
2558
+ * and is converted into the viewport coordinates the box is read in, so a scrolled page reads the
2559
+ * same height as an unscrolled one.
2560
+ *
2561
+ * @example
2562
+ * ```ts
2563
+ * readClippedBlock(bar) // the frame's height where the frame clips a taller bar
2564
+ * ```
2565
+ */
2566
+ export declare function readClippedBlock(element: Element): number;
2567
+
2568
+ /**
2569
+ * Measures the WCAG 2.x contrast ratio one color reaches when painted over an element's backdrop.
2570
+ *
2571
+ * @param element - The element whose own and ancestor backgrounds paint the surface.
2572
+ * @param color - Any CSS color expression, such as the resolved `border-left-color` of a
2573
+ * pseudo-element, resolved at the element's own scope.
2574
+ * @param options - The floor the backdrop walk ends on and the opacity the color is shown at.
2575
+ * @returns The ratio of the color composited over the backdrop, against that backdrop.
2576
+ * @throws Thrown when `color` names no readable color, as under a disconnected element that computes
2577
+ * no style, when `opacity` lies outside `0` to `1`, when a painted background layer is unreadable,
2578
+ * and — with `floor` omitted — when the walk from the element upwards reaches no opaque layer.
2579
+ *
2580
+ * @remarks
2581
+ * This is the reading {@link readContrast} and {@link readRing} take for their own colors, with the
2582
+ * color handed in: a separator grip, a placeholder, a checkbox mark, or any other paint that is not
2583
+ * the element's text. The backdrop composites the {@link readLayers} stack top-over-bottom, the
2584
+ * color composites over that backdrop, and the ratio is measured between the two, so a translucent
2585
+ * color reads at the strength a reader sees.
2586
+ *
2587
+ * A computed color value parses directly through {@link parseColor}; any other expression, such as
2588
+ * a keyword or a `var()` reference, resolves through {@link parseCSSColor} at the element's own
2589
+ * scope. A `var()` reference therefore reads the token as the element and its ancestors declare it,
2590
+ * and `currentColor` reads the element's own text color, not the body's. The read carries the
2591
+ * element's computed custom properties, `color`, and `color-scheme` onto a probe, so an `input` and
2592
+ * a non-inheriting registered token resolve as they do on any other element, and the element itself
2593
+ * is never written. A disconnected element computes no style, so it reads no expression; hand it a
2594
+ * computed color such as `rgb(255, 255, 255)`.
2595
+ *
2596
+ * With `options.floor` omitted, the walk must reach a fully opaque layer, and the refusal shares
2597
+ * `readContrast`'s voice, because the number a stack the canvas shows through produces is as much a
2598
+ * report of the assumption as of the page. Name the floor wherever the caller knows what the stack
2599
+ * sits on: {@link CANVAS_COLOR} for a document, or the color a fragment is really mounted onto.
2600
+ * `options.opacity` multiplies the color's alpha before compositing, for a mark painted inside an
2601
+ * element whose own `opacity` is below `1`. Default: `1`.
2602
+ *
2603
+ * @example
2604
+ * ```ts
2605
+ * const container = render('<div style="background: #fff"><span>Mark</span></div>')
2606
+ * const mark = requireValue(container.querySelector('span'))
2607
+ * readColorContrast(mark, 'rgb(0, 0, 0)') // 21
2608
+ * readColorContrast(mark, 'rgb(0, 0, 0)', { opacity: 0.5 }) // the rgba(0, 0, 0, 0.5) reading
2609
+ * ```
2610
+ */
2611
+ export declare function readColorContrast(element: Element, color: string, options?: ContrastOptions): number;
2612
+
2136
2613
  /**
2137
2614
  * Measures the WCAG 2.x contrast ratio between an element's computed text and background colors.
2138
2615
  *
@@ -2164,7 +2641,8 @@ export declare function readClipMargin(element: Element): number;
2164
2641
  * over it rather than refused.
2165
2642
  *
2166
2643
  * The element itself must expose a computed foreground color either way. A detached element exposes
2167
- * none, and the measurement throws rather than guessing one.
2644
+ * none, and the measurement throws rather than guessing one. The computed foreground is then
2645
+ * measured by {@link readColorContrast}, which owns the walk, the refusal, and the composite.
2168
2646
  *
2169
2647
  * @example
2170
2648
  * ```ts
@@ -2179,8 +2657,15 @@ export declare function readContrast(element: Element, floor?: Color): number;
2179
2657
  * Reads the rendered text of the element that holds focus.
2180
2658
  *
2181
2659
  * @returns The focused HTML element's trimmed rendered text, including an empty string, or
2182
- * `undefined` when focus rests on a non-HTML element. When nothing holds focus, the browser
2183
- * reports the document body as active, so the whole page's rendered text returns.
2660
+ * `undefined` when focus rests on a non-HTML element, inside a shadow root or not. When nothing holds
2661
+ * focus, the browser reports the document body as active, so the whole page's rendered text returns.
2662
+ * @throws Thrown when focus sits in a frame from another origin, as {@link readActiveElement} refuses.
2663
+ *
2664
+ * @remarks
2665
+ * The focused element is read through {@link readActiveElement}, so a control focused inside an open
2666
+ * shadow root or a same-origin frame answers, not its host or its frame. The page text returns only
2667
+ * when the document's active element is its body, and never as a fallback for a focused element
2668
+ * that {@link readActiveElement} declines.
2184
2669
  *
2185
2670
  * @example
2186
2671
  * ```ts
@@ -2402,6 +2887,60 @@ export declare function readPerception(name: string): string;
2402
2887
  */
2403
2888
  export declare function readPixels(element: Element, property: string, pseudo?: string): number;
2404
2889
 
2890
+ /**
2891
+ * Resolves one element to the node the browser's DOM tree holds for it.
2892
+ *
2893
+ * @param element - The element to find.
2894
+ * @returns A promise resolving to the DevTools node id of the element.
2895
+ * @throws Thrown when the provider exposes no DevTools session, a command fails, or the element is
2896
+ * not the one connected element its marker finds.
2897
+ *
2898
+ * @remarks
2899
+ * The browser's DOM domain cannot be handed an element, so the element wears a marker attribute while
2900
+ * the browser searches the document, shadow roots included, for it. The search is discarded and the
2901
+ * marker is put back before this resolves: an attribute the element already carried under that name
2902
+ * keeps its value, and an absent one is removed again, on a refusal as much as on success.
2903
+ *
2904
+ * Use the id before calling again, because each call asks the browser for the document afresh. A
2905
+ * twin of the element, left unmarked, is never the node returned.
2906
+ *
2907
+ * @example
2908
+ * ```ts
2909
+ * const nodeId = await readProtocolNode(button)
2910
+ * const described = await sendProtocol('DOM.describeNode', { nodeId })
2911
+ * ```
2912
+ */
2913
+ export declare function readProtocolNode(element: Element): Promise<number>;
2914
+
2915
+ /**
2916
+ * Projects a point of one element through every frame that holds it into the browser's top-level
2917
+ * viewport.
2918
+ *
2919
+ * @param element - The connected element the point is relative to.
2920
+ * @param offset - The offset from the element's top-left corner, in the element's own pixels.
2921
+ * Default: the centre of its box.
2922
+ * @returns The point in the top-level viewport's coordinates, which is where a DevTools input
2923
+ * command addresses.
2924
+ * @throws Thrown when the element is not connected to a document, or a frame on the way up is not an
2925
+ * HTML element of a document a window holds.
2926
+ *
2927
+ * @remarks
2928
+ * Each frame on the way up adds its border and its padding, which is where its content starts,
2929
+ * scales the point by the ratio of its painted width to its layout width, and adds its own position,
2930
+ * so a tester iframe the runner scales or offsets is accounted for, and so is an iframe the page
2931
+ * itself nests, bordered, padded, or neither. The reading is of the layout now: a box that moves
2932
+ * afterwards moves the point it names. An element in a document no frame holds reads its own client
2933
+ * point. A disconnected element has no layout, and its window still names the tester frame, so it is
2934
+ * refused rather than read as that frame's corner.
2935
+ *
2936
+ * @example
2937
+ * ```ts
2938
+ * const point = readProtocolPoint(button)
2939
+ * await sendProtocol('Input.dispatchMouseEvent', { type: 'mouseMoved', ...point })
2940
+ * ```
2941
+ */
2942
+ export declare function readProtocolPoint(element: Element, offset?: ProtocolPoint): ProtocolPoint;
2943
+
2405
2944
  /**
2406
2945
  * Reads the refusal one named target answers with, or nothing when it resolves.
2407
2946
  *
@@ -2452,7 +2991,9 @@ export declare function readRefusal(role: string, name: string): string | undefi
2452
2991
  * @param worn - The element the control's focus chrome is painted onto. Default: `control`.
2453
2992
  * @returns The strongest ratio the painted focus chrome reaches, or `undefined` when the control is
2454
2993
  * not showing `:focus-visible` or the cascade paints no chrome of its own.
2455
- * @throws Thrown when the focused control's backdrop contains an unreadable painted color layer.
2994
+ * @throws Thrown when the control is showing `:focus-visible` and the backdrop behind the element
2995
+ * the chrome is worn on contains an unreadable painted color layer, whether or not the cascade
2996
+ * paints chrome.
2456
2997
  *
2457
2998
  * @remarks
2458
2999
  * This reads and never acts. Focus arrives through the published verbs — `traverseAccessible`,
@@ -2465,10 +3006,12 @@ export declare function readRefusal(role: string, name: string): string | undefi
2465
3006
  * measurement is not taken on a rectangle nobody is looking at. The focus state is still read off
2466
3007
  * `control`, because that is what holds it.
2467
3008
  *
2468
- * The backdrop is the surface behind the element the chrome is worn on, resolved from that element's
2469
- * parent through {@link readBackdrop} onto {@link CANVAS_COLOR}. A control whose ancestry paints
2470
- * nothing is therefore measured against the browser's own canvas, which is what a reader looking at
2471
- * an unstyled document sees.
3009
+ * The backdrop is the surface behind the element the chrome is worn on: each painted color is
3010
+ * measured by {@link readColorContrast} from that element's parent, with {@link CANVAS_COLOR} as the
3011
+ * floor. A control whose ancestry paints nothing is therefore measured against the browser's own
3012
+ * canvas, which is what a reader looking at an unstyled document sees. The backdrop is read for
3013
+ * every control showing `:focus-visible` before the chrome is looked for, so an unreadable surface
3014
+ * refuses the reading even where the cascade paints no chrome.
2472
3015
  *
2473
3016
  * Only chrome the cascade paints is measured — an `outline` with a real style and width, and the
2474
3017
  * first color in a `box-shadow`. A control left the browser's own `outline-style: auto` ring reports
@@ -2576,6 +3119,34 @@ export declare function readRows(root: ParentNode, selector: string): readonly s
2576
3119
  */
2577
3120
  export declare function readRules(): readonly CSSRule[];
2578
3121
 
3122
+ /**
3123
+ * Reads one painted pixel of an element's screenshot.
3124
+ *
3125
+ * @param element - The rendered element to shoot.
3126
+ * @param x - The pixel's horizontal position as a fraction of the shot's width, from `0` to `1`.
3127
+ * @param y - The pixel's vertical position as a fraction of the shot's height, from `0` to `1`.
3128
+ * @returns The pixel's frozen color: its channels from 0 to 255 and its alpha from 0 to 1.
3129
+ * @throws Thrown when either position is not a finite fraction from `0` to `1`, when the provider
3130
+ * cannot shoot the element, when the shot is not an image this browser decodes, and when the browser
3131
+ * hands out no 2D canvas to measure it on.
3132
+ *
3133
+ * @remarks
3134
+ * The runner scales the tester to fit its window, so a shot's size in device pixels is not the
3135
+ * element's size in CSS pixels. The position is therefore a fraction of the shot rather than an
3136
+ * offset, and a fraction of `1` reads the last row or column rather than one past it. A position
3137
+ * that is `NaN`, infinite, or outside `0` to `1` is refused before the shot is taken, because it
3138
+ * would read outside the shot as a transparent black nothing painted, or coerce to an edge. The
3139
+ * decode and the canvas come from {@link paintImage}, which {@link readFrame} reads through as well.
3140
+ * The shot is not saved. The reading is what the provider painted, so it answers for compositing, stacking, and
3141
+ * clipping that a computed style cannot see; it composes with `matchesColor` and `measureContrast`.
3142
+ *
3143
+ * @example
3144
+ * ```ts
3145
+ * const [red, green, blue] = await readShotPixel(figure, 0.5, 0.5)
3146
+ * ```
3147
+ */
3148
+ export declare function readShotPixel(element: Element, x: number, y: number): Promise<Color>;
3149
+
2579
3150
  /**
2580
3151
  * Reads the states one element is announced in.
2581
3152
  *
@@ -2746,8 +3317,9 @@ export declare function releasePane(): Promise<void>;
2746
3317
  * to its park point in cleanup, and a rejection there joins the aggregate described under `@throws`.
2747
3318
  * The provider must expose a DevTools session.
2748
3319
  *
2749
- * The park point is (-1, -1) in the runner page's coordinates, one pixel above and to the left of
2750
- * that page's viewport. The browser hit-tests nothing outside the viewport, so no element takes a
3320
+ * The pointer parks through the `parkPointer` verb, which sends no release of its own. The park
3321
+ * point is (-1, -1) in the runner page's coordinates, one pixel above and to the left of that
3322
+ * page's viewport. The browser hit-tests nothing outside the viewport, so no element takes a
2751
3323
  * `mouseover` event or hover paint from the parked pointer until the next pointer verb. This holds
2752
3324
  * even where a staging, scroll, or offset lays content over the park point.
2753
3325
  *
@@ -2883,6 +3455,19 @@ export declare function resolveAccessible(role: string, name: string): HTMLEleme
2883
3455
  */
2884
3456
  export declare function resolveAccessibleWithin(region: string, role: string, name: string): HTMLElement;
2885
3457
 
3458
+ /**
3459
+ * Resolves one visible, enabled, focus-reachable native file input by its exact label.
3460
+ *
3461
+ * @param name - The input's accessible label.
3462
+ * @returns The unique reachable native file input.
3463
+ * @throws When the label is absent, ambiguous, hidden, disabled, or outside the active modal.
3464
+ * @example
3465
+ * ```ts
3466
+ * resolveFileInput('Attachments')
3467
+ * ```
3468
+ */
3469
+ export declare function resolveFileInput(name: string): HTMLInputElement;
3470
+
2886
3471
  /**
2887
3472
  * Resolves one rendered, focus-reachable interactive element without requiring it to intersect the
2888
3473
  * viewport yet.
@@ -2916,16 +3501,81 @@ export declare function resolveRendered(first: string, second?: string): HTMLEle
2916
3501
  * Sends one DevTools protocol command through the browser provider.
2917
3502
  *
2918
3503
  * @param method - The protocol method name.
2919
- * @param params - The protocol parameters.
2920
- * @returns A promise resolving after the command completes, discarding its response.
3504
+ * @param params - The protocol parameters. Omit them for a command that takes none.
3505
+ * @returns A promise resolving to the browser's reply once the command completes.
2921
3506
  * @throws Thrown when the provider exposes no DevTools session, or the command fails.
2922
3507
  *
3508
+ * @remarks
3509
+ * The reply is typed `unknown`, because its shape is the command's and the provider's types stay out
3510
+ * of a browser file. Narrow it with guards before reading a field.
3511
+ *
2923
3512
  * @example
2924
3513
  * ```ts
2925
3514
  * await sendProtocol('Emulation.setEmulatedMedia', { media: '', features: [] })
2926
3515
  * ```
2927
3516
  */
2928
- export declare function sendProtocol(method: string, params: Readonly<Record<string, unknown>>): Promise<void>;
3517
+ export declare function sendProtocol(method: string, params?: Readonly<Record<string, unknown>>): Promise<unknown>;
3518
+
3519
+ /**
3520
+ * Settles the page for one capture: parks the pointer, waits out every finite animation, and holds
3521
+ * each endless animation at its first frame.
3522
+ *
3523
+ * @param options - The time bounds of the wait, its abort signal, and whether the pointer parks.
3524
+ * @returns A promise resolving, after one more frame has painted, to the resume: a function that
3525
+ * sets every held animation running again.
3526
+ * @throws Thrown when the pointer cannot park, as {@link parkPointer} raises it, and when a finite
3527
+ * animation is still running at the budget, as {@link waitForAnimations} raises it. An aborted wait
3528
+ * rejects with the signal's reason.
3529
+ *
3530
+ * @remarks
3531
+ * A pointer left over a control paints that control's hover, and a transition still running paints
3532
+ * a fill between two states, so neither is a state the interface rests in. An endless animation, a
3533
+ * spinner or a placeholder shimmer, stands at a different phase in every frame unless it is held at
3534
+ * the same one, so each is paused at its first frame. Call the resume once the frame is shot; a
3535
+ * capture that throws still owes it, so call it from a `finally` block.
3536
+ *
3537
+ * The subject is the whole document, its root element included. The pointer parks through
3538
+ * {@link parkPointer}, which sends no button release, so a held press stays held either way. Pass
3539
+ * `pointer: false` only where the pointer is part of the state, such as a drag in flight: the
3540
+ * control under it then keeps its hover and its pressed paint. Default budget: `1000` milliseconds.
3541
+ *
3542
+ * @example
3543
+ * ```ts
3544
+ * const resume = await settleCapture()
3545
+ * try {
3546
+ * await portfolio.place('start-empty')
3547
+ * } finally {
3548
+ * resume()
3549
+ * }
3550
+ * ```
3551
+ */
3552
+ export declare function settleCapture(options?: SettleOptions): Promise<() => void>;
3553
+
3554
+ /**
3555
+ * Configures one capture settle: the time bounds of {@link WaitOptions} and whether the pointer
3556
+ * parks first.
3557
+ *
3558
+ * @remarks
3559
+ * The bounds go to the wait on finite animations and mean there what they mean everywhere else.
3560
+ * Leave the pointer where it is only where the pointer is part of the state being shot, such as a
3561
+ * drag in flight.
3562
+ */
3563
+ export declare interface SettleOptions extends WaitOptions {
3564
+ /** Determines whether the pointer parks outside the page before the wait. Default: `true`. */
3565
+ readonly pointer?: boolean;
3566
+ }
3567
+
3568
+ /**
3569
+ * Configures how long a reading must hold still: the time bounds of {@link WaitOptions} and the
3570
+ * count of reads it must agree across.
3571
+ */
3572
+ export declare interface StabilityOptions extends WaitOptions {
3573
+ /**
3574
+ * Holds the count of reads, each taken after a painted frame, that must repeat the settled
3575
+ * reading, so the last `frames + 1` reads agree. Default: `4`.
3576
+ */
3577
+ readonly frames?: number;
3578
+ }
2929
3579
 
2930
3580
  /**
2931
3581
  * Stages the tester's print medium, motion preference, and forced colours through the browser
@@ -3019,6 +3669,30 @@ export declare interface StateOptions extends WaitOptions {
3019
3669
  readonly absent?: boolean;
3020
3670
  }
3021
3671
 
3672
+ /**
3673
+ * Presses Tab and yields the element focus lands on, once per press, up to a limit.
3674
+ *
3675
+ * @param limit - The most presses to make.
3676
+ * @returns An async generator of the element each press landed on, `undefined` where only a body, a
3677
+ * non-HTML element, or nothing took focus.
3678
+ * @throws Thrown when a press rejects, or focus lands in a frame from another origin.
3679
+ *
3680
+ * @remarks
3681
+ * This is the one Tab loop {@link driveTraversal} and {@link walkFocus} share. It makes a real press
3682
+ * through the provider, reads the landing with {@link readActiveElement}, and leaves every decision
3683
+ * to the caller: what counts as an end, a revisit, or a stop is the consumer's, because the two
3684
+ * consumers disagree. The press is the next one only after the consumer asks for the next landing, so
3685
+ * a consumer that stops reading stops pressing.
3686
+ *
3687
+ * @example
3688
+ * ```ts
3689
+ * for await (const focused of stepFocus(10)) {
3690
+ * if (focused?.id === 'save') break
3691
+ * }
3692
+ * ```
3693
+ */
3694
+ export declare function stepFocus(limit: number): AsyncGenerator<HTMLElement | undefined, void, undefined>;
3695
+
3022
3696
  /**
3023
3697
  * Configures an inert `Storage`: its seed, which operations the host permits, and its quota.
3024
3698
  *
@@ -3172,6 +3846,38 @@ export declare function waitForAnimations(element: Element, options?: WaitOption
3172
3846
  */
3173
3847
  export declare function waitForFrame(): Promise<void>;
3174
3848
 
3849
+ /**
3850
+ * Waits for a reading to hold across its last `frames + 1` reads, each later read taken after a
3851
+ * painted frame, with the interval slept between polls. Checks the budget between reads, so a frame
3852
+ * that never paints is not bounded by it.
3853
+ *
3854
+ * @param description - The wait described in a timeout error.
3855
+ * @param read - The reading to compare from read to read, such as a scroll position or a box.
3856
+ * @param options - The frame count, the time bounds, and the abort signal.
3857
+ * @returns A promise resolving after the last `frames + 1` reads agree.
3858
+ * @throws Thrown when the frame count is not a positive integer, when `read` throws, or when the
3859
+ * reading keeps changing until the budget runs out. The timeout error names the description.
3860
+ *
3861
+ * @remarks
3862
+ * The first read is immediate. Each later read follows one painted frame, and every later read but
3863
+ * the first also follows the interval, which `waitForCondition` sleeps between polls. The reads are
3864
+ * therefore not on consecutive frames: an interval longer than a frame skips the frames in between.
3865
+ * The wait ends when the last `frames + 1` reads agree, so a reading that settles on read `n`
3866
+ * resolves on read `n + frames`.
3867
+ *
3868
+ * The abort signal is checked between reads too, so neither the budget nor the signal ends a wait
3869
+ * parked on a frame that never paints. Default frames: `4`. Default budget: `1000` milliseconds.
3870
+ * Default interval: `10` milliseconds.
3871
+ *
3872
+ * @example
3873
+ * ```ts
3874
+ * await waitForStability('the panel holds its box', () =>
3875
+ * JSON.stringify(panel.getBoundingClientRect().toJSON()),
3876
+ * )
3877
+ * ```
3878
+ */
3879
+ export declare function waitForStability(description: string, read: () => string, options?: StabilityOptions): Promise<void>;
3880
+
3175
3881
  /**
3176
3882
  * Waits until one named control announces a state, or stops announcing it.
3177
3883
  *
@@ -3225,6 +3931,35 @@ export declare function waitForState(name: string, state: string, options?: Stat
3225
3931
  */
3226
3932
  export declare function waitForState(role: string, name: string, state: string, options?: StateOptions): Promise<readonly string[]>;
3227
3933
 
3934
+ /**
3935
+ * Walks forward by real Tab presses from the focused element until a predicate accepts a stop or
3936
+ * the Tab order ends.
3937
+ *
3938
+ * @param stop - Accepts the destination. Omit it to census the remaining document.
3939
+ * @returns Every element focus reached, in order and each once, the accepted stop last.
3940
+ * @throws Thrown when the walk outlasts every element the page holds, a key press rejects, or focus
3941
+ * lands in a frame from another origin.
3942
+ *
3943
+ * @remarks
3944
+ * The walk records the focused element and then presses Tab through {@link stepFocus}, so it reaches
3945
+ * what the browser's own sequential navigation reaches, including a scroll container Chromium
3946
+ * focuses without a `tabindex`. The static {@link describeFocus} sort does not. Each stop is the
3947
+ * innermost focused element {@link readActiveElement} reads, so a control inside an open shadow root
3948
+ * or a same-origin frame is a stop of its own, and its host or frame element is not. The walk ends
3949
+ * with an empty list when only the body holds focus, and where focus revisits a stop or returns to
3950
+ * the body. It applies no rule about which stop counts: the predicate sees each one and decides, so
3951
+ * a consumer that refuses a hidden stop throws from its own predicate.
3952
+ *
3953
+ * A closed shadow root cannot be entered, so its host stands for everything inside it, and a frame
3954
+ * from another origin is refused because its controls cannot be named.
3955
+ *
3956
+ * @example
3957
+ * ```ts
3958
+ * const stops = await walkFocus((focused) => focused.id === 'save')
3959
+ * ```
3960
+ */
3961
+ export declare function walkFocus(stop?: (element: HTMLElement) => boolean): Promise<readonly HTMLElement[]>;
3962
+
3228
3963
  /**
3229
3964
  * Holds a store the host can withhold and later grant.
3230
3965
  *