@orkestrel/test 0.0.27 → 0.0.29

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
@@ -33,6 +33,10 @@ npm install -D @orkestrel/test
33
33
  Vitest provider. Core touches neither `node:*` nor the DOM, so a browser test project imports it
34
34
  unchanged.
35
35
 
36
+ The browser face also supplies `sendTouch`, `tapTouch`, and `releaseTouch`, external file drags
37
+ through `sendFileDrag`, a `pointer` axis on `stageMedia`, and the stylesheet instruments
38
+ `adoptSheet`, `SheetAdoption`, and `readLayerNames`.
39
+
36
40
  ```ts
37
41
  import {
38
42
  captureError,
@@ -88,7 +92,7 @@ a browser workspace renders that table in.
88
92
  The server face adds `readInventory`, which reads a checkout into a map of root-relative path to
89
93
  file text that a parity suite can assert against, and `createLoopback`, which binds a server the
90
94
  test built to an ephemeral loopback port. Behind them sit the pure leaves the server face also
91
- 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
92
96
  `isExcluded`, while `createScratch` refuses one with `requireContained`, the throwing form, and
93
97
  reads and compares its allocation with `readIdentity` and `matchesIdentity` before `destroy()`
94
98
  removes anything. `createLink` and `removeTree` do the writing under it, and both decide on the
@@ -142,7 +146,7 @@ back for every key that is not integer-like.
142
146
 
143
147
  `createScratch` and `readInventory` promise different things, and each boundary is worth stating up
144
148
  front. `createScratch` allocates its own directory at POSIX mode `0700` — under the host temporary
145
- 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
146
150
  gates that assertion on `supportsMode`, the shipped probe that reads whether permission bits
147
151
  round-trip on this host, so it runs only where they do and claims nothing about a host that emulates
148
152
  them. The mode keeps another uid out, and neither a sibling test worker nor the code under test is
@@ -158,8 +162,8 @@ reports `ctime` in its place, the first write moves it, and `destroy()` then rem
158
162
  returns as if it had. `readInventory` walks a checkout you supply, usually one the test did not
159
163
  create, so it throws on a symlinked root or named target, throws on a named target whose real path
160
164
  leaves the root through a link in the middle, and skips a symlink met while walking. Neither is a
161
- sandbox against hostile filesystem content: those refusals stop accidental escape, not an adversary
162
- 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.
163
167
 
164
168
  The browser face is the journey layer: an accessible-name resolver with exact failure voices,
165
169
  region and disclosure targeting, input and traversal verbs, perception readers, a WCAG contrast
@@ -57,6 +57,20 @@ export declare interface AccessibilityNode {
57
57
  */
58
58
  export declare const ACCESSIBLE_ROLES: readonly string[];
59
59
 
60
+ /**
61
+ * Adopts CSS text into the document with an idempotent release operation.
62
+ *
63
+ * @param text - The compiled sheet text.
64
+ * @returns The adopted sheet and its release operation.
65
+ *
66
+ * @example
67
+ * ```ts
68
+ * const adopted = adoptSheet('.sample { display: block }')
69
+ * adopted.release()
70
+ * ```
71
+ */
72
+ export declare function adoptSheet(text: string): SheetAdoption;
73
+
60
74
  /**
61
75
  * Represents the animations running on one element and its subtree, split by whether each one ends.
62
76
  *
@@ -597,7 +611,9 @@ export declare function collectScrollRegions(root: Element, axis?: 'inline' | 'b
597
611
  * {@link containsNode}, so a control inside an open shadow root or a same-origin frame that `root`
598
612
  * holds is in the region, and `start` may sit inside one. A `start` that sits outside the region,
599
613
  * 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.
614
+ * region reaches its first stop. A native segmented input contributes one stop while consecutive
615
+ * landings pass through its segments up to {@link FOCUS_SEGMENT_LIMIT} landings. A longer run or
616
+ * any other revisit ends the walk.
601
617
  *
602
618
  * @example
603
619
  * ```ts
@@ -1338,8 +1354,11 @@ export declare function driveHold(resolve: () => HTMLElement, name: string): Pro
1338
1354
  *
1339
1355
  * @remarks
1340
1356
  * 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}.
1357
+ * focus lands on an element. Consecutive landings on the same native segmented input continue
1358
+ * through its segments up to {@link FOCUS_SEGMENT_LIMIT} landings and count that control once.
1359
+ * A longer run or any other revisit ends the traversal. Any different landing starts a separate run.
1360
+ * The press cap is {@link FOCUS_SEGMENT_LIMIT} times the {@link FOCUSABLE_SELECTOR} candidate count
1361
+ * plus ten, so a page of segmented inputs has a budget for their segments and picker indicators.
1343
1362
  *
1344
1363
  * @example
1345
1364
  * ```ts
@@ -1529,6 +1548,16 @@ export declare function findKeyframes(name: string): CSSKeyframesRule | undefine
1529
1548
  */
1530
1549
  export declare function findRule(selector: string): CSSStyleRule | undefined;
1531
1550
 
1551
+ /**
1552
+ * Bounds consecutive focus landings and the Tab presses budgeted per segmented input.
1553
+ *
1554
+ * @remarks
1555
+ * Chromium measured nine landings on a datetime-local input with step="0.001": year, month,
1556
+ * day, hour, minute, second, millisecond, and meridiem segments, plus the picker indicator.
1557
+ * The budget covers those landings with one spare press per input.
1558
+ */
1559
+ export declare const FOCUS_SEGMENT_LIMIT = 10;
1560
+
1532
1561
  /**
1533
1562
  * Names what sequential keyboard navigation can reach, before disabled and unrendered elements go.
1534
1563
  *
@@ -2035,11 +2064,13 @@ export declare function measureLuminance(color: Color): number;
2035
2064
  *
2036
2065
  * @remarks
2037
2066
  * The value is a bit string in print, reduced motion, dark colour scheme, and forced colours order.
2038
- * Each bit is `1` for a matching query and `0` otherwise, for example `0100`.
2067
+ * Each bit is `1` for a matching query and `0` otherwise, for example `0100`. The first pointer
2068
+ * stage appends a fifth bit for the pre-call `(pointer: coarse)` reading. Without a pointer stage,
2069
+ * the marker stays four bits and release leaves touch emulation alone.
2039
2070
  */
2040
2071
  export declare const MEDIA_STAGE = "data-media-stage";
2041
2072
 
2042
- /** Configures the tester's print medium, motion preference, and forced colours. */
2073
+ /** Configures the tester's print medium, motion preference, forced colours, and pointer precision. */
2043
2074
  export declare interface MediaOptions {
2044
2075
  /** Determines whether the tester lays out for print. Omit it to leave the medium alone. */
2045
2076
  readonly print?: boolean;
@@ -2047,13 +2078,15 @@ export declare interface MediaOptions {
2047
2078
  readonly motion?: boolean;
2048
2079
  /** Determines whether the tester runs under forced colours. Omit it to leave the colours alone. */
2049
2080
  readonly forced?: boolean;
2081
+ /** Selects touch emulation for coarse input or mouse input for fine precision. Omit it to leave touch emulation alone. */
2082
+ readonly pointer?: 'coarse' | 'fine';
2050
2083
  }
2051
2084
 
2052
2085
  /**
2053
2086
  * Puts one element into the document and hands it straight back.
2054
2087
  *
2055
2088
  * @param element - The element to attach.
2056
- * @returns The same element, now appended to `document.body`.
2089
+ * @returns The same element, appended to `document.body`.
2057
2090
  *
2058
2091
  * @remarks
2059
2092
  * What this buys is the composition, not the attachment: the `append` method returns `void`, and
@@ -2183,7 +2216,7 @@ export declare function parseColor(value: string): Color | undefined;
2183
2216
  * property is named by letters, digits, `_`, and `-` after its `--`. A name the scope leaves
2184
2217
  * undeclared is not carried, so its `var()` fallback still applies.
2185
2218
  *
2186
- * The scope element is never written. The probe is new, so it has no earlier style to start a
2219
+ * The scope element is never written. The probe is freshly created, so it has no earlier style to start a
2187
2220
  * transition from, and a transition running on the scope keeps running: `currentColor` reads the
2188
2221
  * color the scope shows at that moment, and the scope's geometry and scroll position stay as they
2189
2222
  * were. No attribute, style, or child of the scope changes, so a `MutationObserver` on it records
@@ -2763,6 +2796,28 @@ export declare function readFrame(path: string): Promise<FrameReading>;
2763
2796
  */
2764
2797
  export declare function readHit(element: Element): Element | undefined;
2765
2798
 
2799
+ /**
2800
+ * Reads layer statements and blocks in declaration order, including repeated names.
2801
+ *
2802
+ * @param source - The parsed sheet, or a grouping or style rule inside it.
2803
+ * @param layer - The qualified name of the layer enclosing the source, when one does.
2804
+ * @returns Qualified layer names, with an empty name for an anonymous top-level layer.
2805
+ *
2806
+ * @remarks
2807
+ * Descends through grouping and style rules at any depth, qualifying each name by its enclosing layer.
2808
+ * An anonymous layer inside a named layer contributes a trailing dot to that qualified name.
2809
+ * Conditions are read whether or not they match the document.
2810
+ * An `@import ... layer()` rule contributes nothing, and neither do its imported sheet's rules.
2811
+ * A dotted declaration such as `@layer a.b` contributes `a.b` as declared, without an implicit `a`.
2812
+ * Distinct anonymous layers produce the same names; the result does not distinguish their identities.
2813
+ *
2814
+ * @example
2815
+ * ```ts
2816
+ * readLayerNames(new CSSStyleSheet()) // []
2817
+ * ```
2818
+ */
2819
+ export declare function readLayerNames(source: CSSStyleSheet | CSSGroupingRule | CSSStyleRule, layer?: string): readonly string[];
2820
+
2766
2821
  /**
2767
2822
  * Collects readable background color layers and refuses an unreadable painted layer.
2768
2823
  *
@@ -2928,7 +2983,7 @@ export declare function readProtocolNode(element: Element): Promise<number>;
2928
2983
  * Each frame on the way up adds its border and its padding, which is where its content starts,
2929
2984
  * scales the point by the ratio of its painted width to its layout width, and adds its own position,
2930
2985
  * 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
2986
+ * itself nests, bordered, padded, or neither. The reading is of the layout at the call: a box that moves
2932
2987
  * afterwards moves the point it names. An element in a document no frame holds reads its own client
2933
2988
  * point. A disconnected element has no layout, and its window still names the tester frame, so it is
2934
2989
  * refused rather than read as that frame's corner.
@@ -2970,7 +3025,7 @@ export declare function readRefusal(name: string): string | undefined;
2970
3025
  * sentence rather than a boolean. This fixes the resolver, translates the `unknown` a `catch` binds
2971
3026
  * into `string | undefined`, and rethrows anything that is not an `Error` — a value no resolver
2972
3027
  * raises, and one a caller reading a message would otherwise lose. `undefined` is rethrown with the
2973
- * rest: a resolver that returned and a hostile getter that threw `undefined` are different findings,
3028
+ * rest: a resolver that returned and an untrusted getter that threw `undefined` are different findings,
2974
3029
  * which is why the `catch` is this function's own rather than a captured thrown value.
2975
3030
  *
2976
3031
  * It resolves rather than acts, so a target it reports `undefined` for is one an acting verb
@@ -2998,7 +3053,7 @@ export declare function readRefusal(role: string, name: string): string | undefi
2998
3053
  * @remarks
2999
3054
  * This reads and never acts. Focus arrives through the published verbs — `traverseAccessible`,
3000
3055
  * `userEvent.keyboard` from `vitest/browser`, a real click — and this measures what the browser
3001
- * painted once it landed. A control that is not matching `:focus-visible` when the call is made
3056
+ * painted after it landed. A control that is not matching `:focus-visible` when the call is made
3002
3057
  * reports nothing, because no measurement taken then would be about focus.
3003
3058
  *
3004
3059
  * Some controls are two elements: one that takes the focus and one a reader can see. A hidden radio
@@ -3041,7 +3096,7 @@ export declare function readRing(control: Element, worn?: Element): number | und
3041
3096
  * A declared `role` wins outright, and its first token is the answer when several are listed.
3042
3097
  * Otherwise the element's own anatomy decides: an anchor is a link only while it holds an `href`,
3043
3098
  * an `input` takes the role {@link FIELD_ROLES} gives its type, a `select` is a combobox until it
3044
- * offers several rows at once, a `section` is a region only once something names it, and a `th`
3099
+ * offers several rows at once, a `section` is a region only after something names it, and a `th`
3045
3100
  * heads whichever axis its `scope` names. Every other tag answers from {@link IMPLICIT_ROLES},
3046
3101
  * whose membership is the contract for what this can answer at all.
3047
3102
  *
@@ -3267,6 +3322,14 @@ export declare function readValue(role: string, name: string): string;
3267
3322
  * waits per axis for the recorded value, and removes the marker after every axis agrees. With no
3268
3323
  * marker, sends the empty reset and compares readings taken strictly after that send. Each poll
3269
3324
  * waits for a frame; the interval is 10 milliseconds. The provider must expose a DevTools session.
3325
+ * A fifth marker bit restores pointer precision through touch emulation. A four-bit marker or an
3326
+ * unstaged release leaves touch emulation alone. Restoring coarse precision uses one touch point;
3327
+ * the marker does not preserve a provider's earlier maximum touch-point count.
3328
+ * {@link releaseTouch} leaves this marker intact even when it disables a staged coarse pointer,
3329
+ * so media release still restores the reading recorded before the first pointer stage.
3330
+ * A first pointer stage while {@link tapTouch} emulation is live records coarse. In teardown,
3331
+ * call this release before {@link releaseTouch}; reversing the order restores coarse emulation
3332
+ * after touch cleanup.
3270
3333
  *
3271
3334
  * @example
3272
3335
  * ```ts
@@ -3330,6 +3393,30 @@ export declare function releasePane(): Promise<void>;
3330
3393
  */
3331
3394
  export declare function releasePointer(): Promise<void>;
3332
3395
 
3396
+ /**
3397
+ * Cancels emulated touch input, disables touch emulation, and parks the pointer.
3398
+ *
3399
+ * @returns A promise resolving after touch cleanup and the parked pointer's frame.
3400
+ * @throws Thrown when a protocol command fails, apart from Chromium's idle touch cancellation refusal.
3401
+ *
3402
+ * @remarks
3403
+ * Safe after a completed tap, a held touch, or an idle release. This sends no mouse button release.
3404
+ * A native drag that also holds the mouse requires its own `mouseReleased` protocol command before
3405
+ * parking. {@link releasePointer} releases only a press recorded by the package's hold verbs.
3406
+ * Parking after touch input does not prove that Chromium cleared sticky touch hover.
3407
+ * Disables even a coarse pointer staged by {@link stageMedia}, leaving its restoration marker
3408
+ * unchanged. Stage the coarse pointer again when later steps need it; {@link releaseMedia} still
3409
+ * restores the pointer reading recorded before the first pointer stage.
3410
+ * If that stage ran while {@link tapTouch} emulation was live, it recorded coarse. In teardown,
3411
+ * call {@link releaseMedia} before this cleanup; reversing the order ends with coarse emulation.
3412
+ *
3413
+ * @example
3414
+ * ```ts
3415
+ * await releaseTouch()
3416
+ * ```
3417
+ */
3418
+ export declare function releaseTouch(): Promise<void>;
3419
+
3333
3420
  /**
3334
3421
  * Deletes one IndexedDB database and reports what the request actually did.
3335
3422
  *
@@ -3497,12 +3584,40 @@ export declare function resolveFileInput(name: string): HTMLInputElement;
3497
3584
  */
3498
3585
  export declare function resolveRendered(first: string, second?: string): HTMLElement;
3499
3586
 
3587
+ /** Names the native input types whose editable segments share one focused element. */
3588
+ export declare const SEGMENTED_INPUT_TYPES: readonly string[];
3589
+
3590
+ /**
3591
+ * Carries files from outside the page over a rendered target named by role and accessible name.
3592
+ *
3593
+ * @param type - The protocol drag event; cancellation leaves the target before ending the drag.
3594
+ * @param role - The target's accessible role.
3595
+ * @param name - The target's exact accessible name.
3596
+ * @param names - The file names to write under the provider root's `tmp/drag` directory.
3597
+ * @returns A promise resolving after the browser accepts the event.
3598
+ * @throws Thrown when the target is absent, ambiguous, or outside the viewport after scrolling,
3599
+ * a file name contains a path, or the provider refuses a file write or protocol command.
3600
+ *
3601
+ * @remarks
3602
+ * Resolves rendered elements through {@link isRendered}, without focus reachability. A status or
3603
+ * region can receive a drag without being a Tab stop. Events are trusted and carry the `Files`
3604
+ * type. No drop is sent. Chromium raises no `dragleave` for protocol cancellation alone, so
3605
+ * cancellation first moves the drag outside the page.
3606
+ *
3607
+ * @example
3608
+ * ```ts
3609
+ * await sendFileDrag('dragEnter', 'status', 'Drop status', ['note.txt'])
3610
+ * await sendFileDrag('dragCancel', 'status', 'Drop status', ['note.txt'])
3611
+ * ```
3612
+ */
3613
+ export declare function sendFileDrag(type: 'dragEnter' | 'dragOver' | 'dragCancel', role: string, name: string, names: readonly string[]): Promise<void>;
3614
+
3500
3615
  /**
3501
3616
  * Sends one DevTools protocol command through the browser provider.
3502
3617
  *
3503
3618
  * @param method - The protocol method name.
3504
3619
  * @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.
3620
+ * @returns A promise resolving to the browser's reply after the command completes.
3506
3621
  * @throws Thrown when the provider exposes no DevTools session, or the command fails.
3507
3622
  *
3508
3623
  * @remarks
@@ -3516,6 +3631,24 @@ export declare function resolveRendered(first: string, second?: string): HTMLEle
3516
3631
  */
3517
3632
  export declare function sendProtocol(method: string, params?: Readonly<Record<string, unknown>>): Promise<unknown>;
3518
3633
 
3634
+ /**
3635
+ * Sends one emulated touch event through the browser protocol.
3636
+ *
3637
+ * @param type - The Chrome DevTools Protocol touch event type.
3638
+ * @param element - The connected element locating the touch; omit it to end or cancel every point.
3639
+ * @param point - The offset from the element's top-left corner. Default: `{ x: 20, y: 20 }`.
3640
+ * @returns A promise resolving after the browser accepts the event.
3641
+ * @throws Thrown when the element is disconnected, the provider exposes no DevTools session, or the
3642
+ * browser refuses the touch sequence.
3643
+ *
3644
+ * @example
3645
+ * ```ts
3646
+ * await sendTouch('touchStart', target)
3647
+ * await sendTouch('touchEnd')
3648
+ * ```
3649
+ */
3650
+ export declare function sendTouch(type: 'touchStart' | 'touchMove' | 'touchEnd' | 'touchCancel', element?: Element, point?: ProtocolPoint): Promise<void>;
3651
+
3519
3652
  /**
3520
3653
  * Settles the page for one capture: parks the pointer, waits out every finite animation, and holds
3521
3654
  * each endless animation at its first frame.
@@ -3531,7 +3664,7 @@ export declare function sendProtocol(method: string, params?: Readonly<Record<st
3531
3664
  * A pointer left over a control paints that control's hover, and a transition still running paints
3532
3665
  * a fill between two states, so neither is a state the interface rests in. An endless animation, a
3533
3666
  * 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
3667
+ * the same one, so each is paused at its first frame. Call the resume after the frame is shot; a
3535
3668
  * capture that throws still owes it, so call it from a `finally` block.
3536
3669
  *
3537
3670
  * The subject is the whole document, its root element included. The pointer parks through
@@ -3565,6 +3698,20 @@ export declare interface SettleOptions extends WaitOptions {
3565
3698
  readonly pointer?: boolean;
3566
3699
  }
3567
3700
 
3701
+ /**
3702
+ * Describes an adopted stylesheet and its idempotent release operation.
3703
+ */
3704
+ export declare interface SheetAdoption {
3705
+ /** Holds the stylesheet adopted into the document. */
3706
+ readonly sheet: CSSStyleSheet;
3707
+ /**
3708
+ * Removes this sheet from the document without removing another adoption.
3709
+ *
3710
+ * @returns Nothing.
3711
+ */
3712
+ release(): void;
3713
+ }
3714
+
3568
3715
  /**
3569
3716
  * Configures how long a reading must hold still: the time bounds of {@link WaitOptions} and the
3570
3717
  * count of reads it must agree across.
@@ -3578,13 +3725,13 @@ export declare interface StabilityOptions extends WaitOptions {
3578
3725
  }
3579
3726
 
3580
3727
  /**
3581
- * Stages the tester's print medium, motion preference, and forced colours through the browser
3582
- * provider.
3728
+ * Stages the tester's print medium, motion preference, forced colours, and pointer precision through
3729
+ * the browser provider.
3583
3730
  *
3584
3731
  * @param options - The media axes to override.
3585
3732
  * @returns A promise resolving after a bounded read-back for `print: true`, either `motion` value,
3586
- * and either `forced` value. A `print: false` stage is sent and followed by a frame wait without a
3587
- * read-back.
3733
+ * either `forced` value, and either `pointer` value. A `print: false` stage is sent and followed by
3734
+ * a frame wait without a read-back.
3588
3735
  * @throws Thrown when no axis is supplied or a staged query does not reach the tester.
3589
3736
  *
3590
3737
  * @remarks
@@ -3597,6 +3744,14 @@ export declare interface StabilityOptions extends WaitOptions {
3597
3744
  * budgets. A restoration failure is attached as the refusal's cause. Register
3598
3745
  * {@link releaseMedia} in teardown; it restores the readings observed before the first stage.
3599
3746
  *
3747
+ * A coarse pointer enables single-point touch emulation; a fine pointer disables it. Chromium also
3748
+ * changes `any-pointer` and the hover queries. An omitted pointer never sends a touch-emulation
3749
+ * command. The first pointer stage appends its pre-call coarse reading to the media marker.
3750
+ * {@link releaseTouch} disables a staged coarse pointer without changing that marker. Stage the
3751
+ * pointer again after touch cleanup when later steps need coarse precision.
3752
+ * A first pointer stage while {@link tapTouch} emulation is live records coarse. In teardown,
3753
+ * call {@link releaseMedia} before {@link releaseTouch}; reversing the order ends coarse.
3754
+ *
3600
3755
  * @example
3601
3756
  * ```ts
3602
3757
  * await stageMedia({ motion: false, print: true })
@@ -3616,7 +3771,7 @@ export declare function stageMedia(options: MediaOptions): Promise<void>;
3616
3771
  *
3617
3772
  * @remarks
3618
3773
  * This depends on the runner's own tester layout, and that dependency is contract rather than an
3619
- * accident: `vitest@4.1.11` lays its tester out inside a smaller page, fits it by scaling the pane
3774
+ * accident: `vitest@4.1.12` lays its tester out inside a smaller page, fits it by scaling the pane
3620
3775
  * the tester sits in, and clips whatever overflows that pane. Layout inside the tester is
3621
3776
  * unaffected — the tester reports the viewport it was given and every breakpoint answers to it —
3622
3777
  * but a screenshot is taken off the page the runner painted, so a frame shot through that scale is
@@ -3682,7 +3837,9 @@ export declare interface StateOptions extends WaitOptions {
3682
3837
  * through the provider, reads the landing with {@link readActiveElement}, and leaves every decision
3683
3838
  * to the caller: what counts as an end, a revisit, or a stop is the consumer's, because the two
3684
3839
  * 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.
3840
+ * a consumer that stops reading stops pressing. A native segmented input can yield the same element
3841
+ * for successive segment landings. This generator preserves each landing; its consumers count that
3842
+ * control once while continuing through its segments, and end a run beyond {@link FOCUS_SEGMENT_LIMIT}.
3686
3843
  *
3687
3844
  * @example
3688
3845
  * ```ts
@@ -3716,6 +3873,46 @@ export declare interface StorageOptions {
3716
3873
  readonly quota?: number;
3717
3874
  }
3718
3875
 
3876
+ /**
3877
+ * Determines whether a native input exposes separately editable segments under one focused element.
3878
+ *
3879
+ * @param element - The element whose native input type is read in its own document's realm.
3880
+ * @returns True if the element is an input with a type in {@link SEGMENTED_INPUT_TYPES}, checked
3881
+ * against its own document's `HTMLInputElement`; false otherwise, including a document with no window.
3882
+ *
3883
+ * @example
3884
+ * ```ts
3885
+ * supportsSegmentedFocus(document.createElement('button')) // false
3886
+ * ```
3887
+ */
3888
+ export declare function supportsSegmentedFocus(element: Element): boolean;
3889
+
3890
+ /**
3891
+ * Taps an element's centre with emulated touch after its box settles.
3892
+ *
3893
+ * @param element - The connected element locating the tap.
3894
+ * @param options - The stability frame count, time bounds, and abort signal.
3895
+ * @returns A promise resolving after the browser accepts the touch end.
3896
+ * @throws Thrown when stability fails, the element is disconnected, or a protocol command fails.
3897
+ *
3898
+ * @remarks
3899
+ * Uses one touch point and leaves touch emulation enabled until {@link releaseTouch}.
3900
+ * That cleanup disables even a coarse pointer staged by {@link stageMedia}; stage it again after
3901
+ * cleanup when later steps need coarse precision.
3902
+ * A first pointer stage while tap emulation is live records coarse as its pre-call reading.
3903
+ * In teardown, call {@link releaseMedia} before {@link releaseTouch}; reversing that order restores
3904
+ * coarse emulation after touch cleanup.
3905
+ * The wait uses {@link waitForStability}; an unsettled scroller can consume a tap to stop momentum
3906
+ * without producing a click. No scrolling or focus-reachability check is performed.
3907
+ *
3908
+ * @example
3909
+ * ```ts
3910
+ * await tapTouch(target, { budget: 2000 })
3911
+ * await releaseTouch()
3912
+ * ```
3913
+ */
3914
+ export declare function tapTouch(element: Element, options?: StabilityOptions): Promise<void>;
3915
+
3719
3916
  /**
3720
3917
  * Reaches a named control only through natural forward Tab traversal from the current focus.
3721
3918
  *
@@ -3724,7 +3921,9 @@ export declare interface StorageOptions {
3724
3921
  * @throws When one complete traversal cannot reach the target.
3725
3922
  *
3726
3923
  * @remarks
3727
- * The loop is {@link driveTraversal} over {@link resolveRendered}.
3924
+ * The loop is {@link driveTraversal} over {@link resolveRendered}. Consecutive landings inside a
3925
+ * native segmented input continue through its segments up to {@link FOCUS_SEGMENT_LIMIT} landings.
3926
+ * A longer run or any other revisit ends the traversal.
3728
3927
  *
3729
3928
  * @example
3730
3929
  * ```ts
@@ -3802,7 +4001,7 @@ export declare function typeInput(element: HTMLInputElement | HTMLTextAreaElemen
3802
4001
  *
3803
4002
  * @param element - The element whose own animations and descendants' animations to wait on.
3804
4003
  * @param options - The time bounds and the abort signal.
3805
- * @returns A promise resolving once no finite animation is still running.
4004
+ * @returns A promise resolving after every finite animation has stopped running.
3806
4005
  * @throws An `Error` when the element is not in a document, when a bound is invalid, or when an
3807
4006
  * animation is still running at the budget; or the abort reason.
3808
4007
  *
@@ -3937,8 +4136,8 @@ export declare function waitForState(role: string, name: string, state: string,
3937
4136
  *
3938
4137
  * @param stop - Accepts the destination. Omit it to census the remaining document.
3939
4138
  * @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.
4139
+ * @throws Thrown when the walk exceeds its press cap, a key press rejects, or focus lands in a
4140
+ * frame from another origin.
3942
4141
  *
3943
4142
  * @remarks
3944
4143
  * The walk records the focused element and then presses Tab through {@link stepFocus}, so it reaches
@@ -3947,8 +4146,14 @@ export declare function waitForState(role: string, name: string, state: string,
3947
4146
  * innermost focused element {@link readActiveElement} reads, so a control inside an open shadow root
3948
4147
  * or a same-origin frame is a stop of its own, and its host or frame element is not. The walk ends
3949
4148
  * 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.
4149
+ * the body. Consecutive landings on the same native segmented input continue through its segments
4150
+ * up to {@link FOCUS_SEGMENT_LIMIT} landings, including the initial focused element, and count that
4151
+ * control once. A longer run or any other revisit, including a repeated button in a focus trap,
4152
+ * ends the walk. Any different landing starts a separate run.
4153
+ * The press cap is {@link FOCUS_SEGMENT_LIMIT} times {@link countElements}, including
4154
+ * open shadow roots and same-origin frames. It applies no rule about which stop counts: the
4155
+ * predicate sees each one and decides, so a consumer that refuses a hidden stop throws from its own
4156
+ * predicate.
3952
4157
  *
3953
4158
  * A closed shadow root cannot be entered, so its host stands for everything inside it, and a frame
3954
4159
  * from another origin is refused because its controls cannot be named.