@orkestrel/test 0.0.28 → 0.0.30

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -7,7 +7,7 @@ import { isArray, isError, isNumber, isRecord, isString, resolveField } from "@o
7
7
  *
8
8
  * @param method - The protocol method name.
9
9
  * @param params - The protocol parameters. Omit them for a command that takes none.
10
- * @returns A promise resolving to the browser's reply once the command completes.
10
+ * @returns A promise resolving to the browser's reply after the command completes.
11
11
  * @throws Thrown when the provider exposes no DevTools session, or the command fails.
12
12
  *
13
13
  * @remarks
@@ -75,7 +75,7 @@ function build(tag, options) {
75
75
  * Puts one element into the document and hands it straight back.
76
76
  *
77
77
  * @param element - The element to attach.
78
- * @returns The same element, now appended to `document.body`.
78
+ * @returns The same element, appended to `document.body`.
79
79
  *
80
80
  * @remarks
81
81
  * What this buys is the composition, not the attachment: the `append` method returns `void`, and
@@ -209,6 +209,23 @@ var FIELD_ROLES = Object.freeze({
209
209
  * the one list either one reads.
210
210
  */
211
211
  var FOCUSABLE_SELECTOR = "a[href], area[href], button, input, select, summary, textarea, [tabindex]";
212
+ /** Names the native input types whose editable segments share one focused element. */
213
+ var SEGMENTED_INPUT_TYPES = Object.freeze([
214
+ "date",
215
+ "time",
216
+ "datetime-local",
217
+ "month",
218
+ "week"
219
+ ]);
220
+ /**
221
+ * Bounds consecutive focus landings and the Tab presses budgeted per segmented input.
222
+ *
223
+ * @remarks
224
+ * Chromium measured nine landings on a datetime-local input with step="0.001": year, month,
225
+ * day, hour, minute, second, millisecond, and meridiem segments, plus the picker indicator.
226
+ * The budget covers those landings with one spare press per input.
227
+ */
228
+ var FOCUS_SEGMENT_LIMIT = 10;
212
229
  /**
213
230
  * Names the role a `th` carries for the header axis its `scope` names.
214
231
  *
@@ -315,7 +332,7 @@ var CAPTURE_PANE = "data-capture-pane";
315
332
  * one restaging past the cap before it comes back down to the edge. Nothing measured needs a
316
333
  * fourth, so a fourth is the headroom that keeps a settling document off the refusal.
317
334
  */
318
- var CAPTURE_STAGINGS = 4;
335
+ var CAPTURE_STAGE_LIMIT = 4;
319
336
  /**
320
337
  * Names the tester root's attribute holding the media readings observed before the first stage.
321
338
  *
@@ -578,7 +595,7 @@ function measureContent() {
578
595
  *
579
596
  * @remarks
580
597
  * This depends on the runner's own tester layout, and that dependency is contract rather than an
581
- * accident: `vitest@4.1.11` lays its tester out inside a smaller page, fits it by scaling the pane
598
+ * accident: `vitest@4.1.12` lays its tester out inside a smaller page, fits it by scaling the pane
582
599
  * the tester sits in, and clips whatever overflows that pane. Layout inside the tester is
583
600
  * unaffected — the tester reports the viewport it was given and every breakpoint answers to it —
584
601
  * but a screenshot is taken off the page the runner painted, so a frame shot through that scale is
@@ -587,6 +604,8 @@ function measureContent() {
587
604
  * selector and the `--tester-transform`, `--tester-margin-left`, `--viewport-width`, and
588
605
  * `--viewport-height` custom properties are the runner's, so a Vitest release that renames any of
589
606
  * them reddens the size check that follows rather than writing a wrong frame.
607
+ * The custom-property overrides serve Vitest 4; `transform: none !important` on the pane and
608
+ * iframe also suppresses Vitest 5's direct CSS transform.
590
609
  *
591
610
  * Hand the pane straight back with {@link releasePane}. A tester pinned at a viewport taller than
592
611
  * the window puts its lower half beyond what a pointer can reach, so an ordinary press then fails
@@ -604,7 +623,8 @@ function measureContent() {
604
623
  * the shot replaces the node and takes any attribute of ours with it.
605
624
  *
606
625
  * The wait is two frames rather than a delay: the first carries the resize into layout and the
607
- * second is the paint a screenshot reads.
626
+ * second is the paint a screenshot reads. An already matching viewport needs no resize command;
627
+ * the staging rule, paint waits, and rendered-size check still run.
608
628
  *
609
629
  * The viewport the tester had before this staging is written onto that rule element as the
610
630
  * {@link CAPTURE_PANE} value, in `<width>x<height>` form, and {@link releasePane} hands it back.
@@ -618,7 +638,7 @@ function measureContent() {
618
638
  */
619
639
  async function stagePane(width, height) {
620
640
  const viewport = `${String(window.innerWidth)}x${String(window.innerHeight)}`;
621
- await page.viewport(width, height);
641
+ if (window.innerWidth !== width || window.innerHeight !== height) await page.viewport(width, height);
622
642
  const frame = window.frameElement;
623
643
  const pane = frame?.parentElement;
624
644
  const owner = pane?.ownerDocument;
@@ -629,9 +649,9 @@ async function stagePane(width, height) {
629
649
  rule.setAttribute(CAPTURE_PANE, viewport);
630
650
  rule.textContent = [
631
651
  `[${CAPTURE_PANE}],:has(>iframe[data-vitest])`,
632
- "{--tester-transform:none !important;--tester-margin-left:0px !important}",
652
+ "{--tester-transform:none !important;--tester-margin-left:0px !important;transform:none !important}",
633
653
  "iframe[data-vitest]",
634
- "{position:fixed !important;left:0 !important;top:0 !important;right:auto !important;",
654
+ "{transform:none !important;position:fixed !important;left:0 !important;top:0 !important;right:auto !important;",
635
655
  "bottom:auto !important;width:var(--viewport-width) !important;",
636
656
  "height:var(--viewport-height) !important;z-index:2147483647 !important}"
637
657
  ].join("");
@@ -657,7 +677,9 @@ async function stagePane(width, height) {
657
677
  * otherwise read the last capture's variant. The size comes off the {@link CAPTURE_PANE} value
658
678
  * {@link stagePane} wrote onto the rule element, which is the reading taken before the first
659
679
  * staging. Calling this on an unstaged pane finds no such value, so it changes nothing and resizes
660
- * nothing.
680
+ * nothing. A staged pane sends its saved size even when the tester already holds it, because the
681
+ * runner refits its frame scale only on a viewport request; a release that skipped it would leave
682
+ * the next case shooting through the staged scale.
661
683
  *
662
684
  * That hand-back is what makes {@link stagePane} and this pair a capture's staging rather than a
663
685
  * resize: the pair puts the tester back where it found it, so a suite that used it to reach a
@@ -851,12 +873,12 @@ async function stageMedia(options) {
851
873
  async function waitForStability(description, read, options) {
852
874
  const frames = options?.frames ?? 4;
853
875
  if (!Number.isInteger(frames) || frames < 1) throw new Error("Stability frames must be a positive integer");
854
- const readings = [read()];
876
+ const samples = [read()];
855
877
  await waitForCondition(description, async () => {
856
878
  await waitForFrame();
857
- readings.push(read());
858
- const tail = readings.slice(-(frames + 1));
859
- return tail.length > frames && tail.every((reading) => reading === tail[0]);
879
+ samples.push(read());
880
+ const tail = samples.slice(-(frames + 1));
881
+ return tail.length > frames && tail.every((sample) => sample === tail[0]);
860
882
  }, options);
861
883
  }
862
884
  /**
@@ -895,33 +917,33 @@ async function releaseMedia() {
895
917
  ];
896
918
  const staged = document.documentElement.getAttribute(MEDIA_STAGE);
897
919
  if (staged !== null) {
898
- const readings = staged.split("").map((value) => value === "1");
920
+ const matches = staged.split("").map((value) => value === "1");
899
921
  if (staged.length === 5) queries.push("(pointer: coarse)");
900
922
  await sendProtocol("Emulation.setEmulatedMedia", {
901
- media: readings[0] ? "print" : "screen",
923
+ media: matches[0] ? "print" : "screen",
902
924
  features: [
903
925
  {
904
926
  name: "prefers-reduced-motion",
905
- value: readings[1] ? "reduce" : "no-preference"
927
+ value: matches[1] ? "reduce" : "no-preference"
906
928
  },
907
929
  {
908
930
  name: "prefers-color-scheme",
909
- value: readings[2] ? "dark" : "light"
931
+ value: matches[2] ? "dark" : "light"
910
932
  },
911
933
  {
912
934
  name: "forced-colors",
913
- value: readings[3] ? "active" : "none"
935
+ value: matches[3] ? "active" : "none"
914
936
  }
915
937
  ]
916
938
  });
917
939
  if (staged.length === 5) await sendProtocol("Emulation.setTouchEmulationEnabled", {
918
- enabled: readings[4],
940
+ enabled: matches[4],
919
941
  maxTouchPoints: 1
920
942
  });
921
943
  try {
922
944
  await Promise.all(queries.map((query, index) => waitForCondition(query, async () => {
923
945
  await waitForFrame();
924
- return matchMedia(query).matches === readings[index];
946
+ return matchMedia(query).matches === matches[index];
925
947
  })));
926
948
  } catch (cause) {
927
949
  throw new Error("Media emulation did not clear from the tester", { cause });
@@ -945,14 +967,17 @@ async function releaseMedia() {
945
967
  * @param options - The path to write, the viewport to shoot at, and the element to shoot.
946
968
  * @returns The absolute path of the written frame, after it has been read back and matched.
947
969
  * @throws Thrown when the pane cannot be staged, when the document's height or an element frame's
948
- * element height never settles under {@link CAPTURE_STAGINGS} restagings, when the provider wrote
970
+ * element height never settles under {@link CAPTURE_STAGE_LIMIT} restagings, when the provider wrote
949
971
  * the frame somewhere else, and when the bytes on disk are not the ones this shot produced.
950
972
  *
951
973
  * @remarks
952
974
  * The path a screenshot call returns is the path it meant to write, so it is not evidence a file
953
- * exists. The file is read back through the runner's built-in `readFile` command and compared with
954
- * the shot itself, which is what separates a frame this run wrote from one an earlier run left
955
- * behind. The provider resolves `options.path` against the calling test file and returns an absolute
975
+ * exists. The {@link verifyFrame} helper compares the file with the shot itself. When the page
976
+ * registered a `readCapture` command, {@link readCaptureReader} returns it and the comparison uses
977
+ * SHA-256 digests computed in Node for the file and in the browser for the returned bytes. Otherwise
978
+ * the runner's built-in `readFile` command supplies the base64 comparison. A command failure
979
+ * propagates without falling back. The provider resolves `options.path`
980
+ * against the calling test file and returns an absolute
956
981
  * path, so the two are compared by the segments that survive resolving `.` and `..` lexically — the
957
982
  * refusal is what a provider resolving that path against a different base would trip.
958
983
  *
@@ -962,6 +987,8 @@ async function releaseMedia() {
962
987
  * than the document — a frame that reads as the surface down to the fold and as bare canvas after
963
988
  * it. The document is therefore laid out at the declared viewport first and, where it is taller
964
989
  * than that, the pane is staged again at the height the document needs, for the shot alone.
990
+ * Where the tester already has the declared viewport, the reading precedes the initial staging,
991
+ * so fixed content stages at its final height directly. Every staged height is still read again.
965
992
  *
966
993
  * That height is {@link measureContent}, never less than `options.height`, because the declared
967
994
  * viewport is the smallest frame a variant asks for. The reading is the content's own edge rather
@@ -984,7 +1011,7 @@ async function releaseMedia() {
984
1011
  *
985
1012
  * The re-reading stops when the pane and the edge agree, which is the pane the shot is taken at. A
986
1013
  * rule that adds height with every pane never reaches that point, so the re-reading is bounded by
987
- * {@link CAPTURE_STAGINGS} and the shot is refused with
1014
+ * {@link CAPTURE_STAGE_LIMIT} and the shot is refused with
988
1015
  * `Capture frame at <path> never settled after <n> restagings: <h> over a <h> pane` rather than
989
1016
  * written at a height that is already wrong.
990
1017
  *
@@ -1037,12 +1064,13 @@ async function captureFrame(options) {
1037
1064
  left: window.scrollX,
1038
1065
  top: window.scrollY
1039
1066
  };
1067
+ const prepared = window.innerWidth === options.width && window.innerHeight === options.height;
1040
1068
  try {
1041
- await stagePane(options.width, options.height);
1069
+ if (!prepared) await stagePane(options.width, options.height);
1042
1070
  let pane = options.height;
1043
1071
  let covered;
1044
1072
  let growth = 0;
1045
- for (let staging = 0;; staging += 1) {
1073
+ for (let stage = 0;; stage += 1) {
1046
1074
  let height = element?.getBoundingClientRect().height;
1047
1075
  if (element !== void 0 && height !== void 0 && height > options.height) {
1048
1076
  element.scrollIntoView({
@@ -1100,11 +1128,17 @@ async function captureFrame(options) {
1100
1128
  }
1101
1129
  }
1102
1130
  }
1103
- const reading = Math.max(height === void 0 ? measureContent() : Math.ceil(height), options.height);
1104
- if (covered !== void 0) growth = Math.max(0, reading - covered);
1105
- covered = reading;
1106
- if (pane === covered) break;
1107
- if (staging === 4) throw new Error(`Capture frame at ${options.path} never settled after ${String(4)} restagings: ${String(covered)} over a ${String(pane)} pane`);
1131
+ const extent = Math.max(height === void 0 ? measureContent() : Math.ceil(height), options.height);
1132
+ if (covered !== void 0) growth = Math.max(0, extent - covered);
1133
+ covered = extent;
1134
+ if (pane === covered) {
1135
+ if (prepared && stage === 0) {
1136
+ await stagePane(options.width, pane);
1137
+ continue;
1138
+ }
1139
+ break;
1140
+ }
1141
+ if (stage === 4) throw new Error(`Capture frame at ${options.path} never settled after ${String(4)} restagings: ${String(covered)} over a ${String(pane)} pane`);
1108
1142
  pane = covered + growth;
1109
1143
  await stagePane(options.width, pane);
1110
1144
  }
@@ -1147,14 +1181,7 @@ async function captureFrame(options) {
1147
1181
  else if (offset && style !== null) frame.setAttribute("style", style);
1148
1182
  }
1149
1183
  }
1150
- const segments = [];
1151
- for (const segment of options.path.replaceAll("\\", "/").split("/")) {
1152
- if (segment === "" || segment === ".") continue;
1153
- if (segment === "..") segments.pop();
1154
- else segments.push(segment);
1155
- }
1156
- if (!shot.path.replaceAll("\\", "/").endsWith(segments.join("/"))) throw new Error(`Capture frame was written to ${shot.path} where ${options.path} was asked for`);
1157
- if (await commands.readFile(shot.path, "base64") !== shot.base64) throw new Error(`Capture frame at ${options.path} is not the one this run shot`);
1184
+ await verifyFrame(shot, options.path, readCaptureReader());
1158
1185
  return shot.path;
1159
1186
  } finally {
1160
1187
  try {
@@ -1169,6 +1196,49 @@ async function captureFrame(options) {
1169
1196
  }
1170
1197
  }
1171
1198
  /**
1199
+ * Reads the optional disk-digest command the tester page registered.
1200
+ *
1201
+ * @returns The registered `readCapture` command, or undefined where none is registered.
1202
+ *
1203
+ * @remarks Vitest publishes only registered commands, so an unregistered `readCapture` reads as
1204
+ * undefined and a capture falls back to the base64 read-back. Outside a Vitest browser page, where
1205
+ * `commands` is no object, the command reads as undefined too, so importing this module never
1206
+ * throws there.
1207
+ * @example
1208
+ * ```ts
1209
+ * await verifyFrame(shot, '../../tmp/frame.png', readCaptureReader())
1210
+ * ```
1211
+ */
1212
+ function readCaptureReader() {
1213
+ if (typeof commands !== "object" || commands === null) return void 0;
1214
+ return readProperty(commands, "readCapture");
1215
+ }
1216
+ /**
1217
+ * Verifies a screenshot's destination and compares its returned bytes with the written file.
1218
+ *
1219
+ * @param shot - The provider's absolute path and base64 screenshot bytes.
1220
+ * @param path - The requested screenshot path, relative to the test file.
1221
+ * @param reader - The optional Node disk-digest command; omission uses Vitest's base64 read-back.
1222
+ * @throws Thrown when the destination differs, the bytes differ, or either reading fails.
1223
+ * @remarks Digest reads compare SHA-256 of the decoded shot with SHA-256 of the disk bytes.
1224
+ * Command failures propagate unchanged; they never select the base64 fallback.
1225
+ * @example
1226
+ * ```ts
1227
+ * await verifyFrame(shot, '../../tmp/frame.png', readCaptureReader())
1228
+ * ```
1229
+ */
1230
+ async function verifyFrame(shot, path, reader) {
1231
+ const segments = [];
1232
+ for (const segment of path.replaceAll("\\", "/").split("/")) {
1233
+ if (segment === "" || segment === ".") continue;
1234
+ if (segment === "..") segments.pop();
1235
+ else segments.push(segment);
1236
+ }
1237
+ if (!shot.path.replaceAll("\\", "/").endsWith(segments.join("/"))) throw new Error(`Capture frame was written to ${shot.path} where ${path} was asked for`);
1238
+ const expected = reader === void 0 ? shot.base64 : [...new Uint8Array(await crypto.subtle.digest("SHA-256", Uint8Array.from(atob(shot.base64), (character) => character.charCodeAt(0))))].map((byte) => byte.toString(16).padStart(2, "0")).join("");
1239
+ if ((reader === void 0 ? await commands.readFile(shot.path, "base64") : await reader(shot.path)) !== expected) throw new Error(`Capture frame at ${path} is not the one this run shot`);
1240
+ }
1241
+ /**
1172
1242
  * Decodes a base64 PNG and paints it, unscaled, onto a fresh offscreen 2D canvas.
1173
1243
  *
1174
1244
  * @param encoded - The image's bytes as base64 text, without a data-URL prefix.
@@ -1223,7 +1293,7 @@ async function paintImage(encoded) {
1223
1293
  *
1224
1294
  * @example
1225
1295
  * ```ts
1226
- * const reading = await readFrame(written)
1296
+ * const result = await readFrame(written)
1227
1297
  * ```
1228
1298
  */
1229
1299
  async function readFrame(path) {
@@ -1796,7 +1866,7 @@ function resolveFileInput(name) {
1796
1866
  * ```
1797
1867
  */
1798
1868
  async function chooseAccessible(name, files, options) {
1799
- if (options?.keyboard) await driveTraversal(() => resolveFileInput(name), name);
1869
+ if (options?.keyboard) await driveTraversal(() => resolveFileInput(name), name, (focused) => focused instanceof HTMLInputElement && focused.type === "file");
1800
1870
  const target = resolveFileInput(name);
1801
1871
  const command = readProperty(commands, "chooseFiles");
1802
1872
  if (typeof command !== "function") throw new Error("Register the chooseFiles browser command before choosing files");
@@ -2079,7 +2149,7 @@ async function releasePointer() {
2079
2149
  * Each frame on the way up adds its border and its padding, which is where its content starts,
2080
2150
  * scales the point by the ratio of its painted width to its layout width, and adds its own position,
2081
2151
  * so a tester iframe the runner scales or offsets is accounted for, and so is an iframe the page
2082
- * itself nests, bordered, padded, or neither. The reading is of the layout now: a box that moves
2152
+ * itself nests, bordered, padded, or neither. The reading is of the layout at the call: a box that moves
2083
2153
  * afterwards moves the point it names. An element in a document no frame holds reads its own client
2084
2154
  * point. A disconnected element has no layout, and its window still names the tester frame, so it is
2085
2155
  * refused rather than read as that frame's corner.
@@ -2286,7 +2356,10 @@ async function pressKeys(keys) {
2286
2356
  * @throws When one complete traversal cannot reach the target.
2287
2357
  *
2288
2358
  * @remarks
2289
- * The loop is {@link driveTraversal} over {@link resolveRendered}.
2359
+ * The loop is {@link driveTraversal} over {@link resolveRendered}, with a conservative name check
2360
+ * before each arrival resolution. Consecutive landings inside a
2361
+ * native segmented input continue through its segments up to {@link FOCUS_SEGMENT_LIMIT} landings.
2362
+ * A longer run or any other revisit ends the traversal.
2290
2363
  *
2291
2364
  * @example
2292
2365
  * ```ts
@@ -2308,7 +2381,8 @@ async function traverseAccessible(name) {
2308
2381
  *
2309
2382
  * @remarks
2310
2383
  * The resolution is {@link resolveAccessibleWithin} and the loop is {@link driveTraversal}, so a
2311
- * twin of the same name earlier in the tab order is passed over rather than reached.
2384
+ * twin of the same name earlier in the tab order is passed over rather than reached. Candidates
2385
+ * retain the resolver's loose name match and must belong to a freshly resolved named region.
2312
2386
  *
2313
2387
  * @example
2314
2388
  * ```ts
@@ -2316,7 +2390,10 @@ async function traverseAccessible(name) {
2316
2390
  * ```
2317
2391
  */
2318
2392
  async function traverseAccessibleWithin(region, role, name) {
2319
- return driveTraversal(() => resolveAccessibleWithin(region, role, name), name);
2393
+ return driveTraversal(() => resolveAccessibleWithin(region, role, name), name, (focused) => matchesTraversalName(focused, name, false) && page.getByRole("region", {
2394
+ name: region,
2395
+ exact: true
2396
+ }).elements().some((container) => containsNode(container, focused)));
2320
2397
  }
2321
2398
  /**
2322
2399
  * Reads the HTML element that holds focus, following it into open shadow roots and same-origin
@@ -2424,7 +2501,9 @@ function containsNode(root, node) {
2424
2501
  * through the provider, reads the landing with {@link readActiveElement}, and leaves every decision
2425
2502
  * to the caller: what counts as an end, a revisit, or a stop is the consumer's, because the two
2426
2503
  * consumers disagree. The press is the next one only after the consumer asks for the next landing, so
2427
- * a consumer that stops reading stops pressing.
2504
+ * a consumer that stops reading stops pressing. A native segmented input can yield the same element
2505
+ * for successive segment landings. This generator preserves each landing; its consumers count that
2506
+ * control once while continuing through its segments, and end a run beyond {@link FOCUS_SEGMENT_LIMIT}.
2428
2507
  *
2429
2508
  * @example
2430
2509
  * ```ts
@@ -2440,42 +2519,104 @@ async function* stepFocus(limit) {
2440
2519
  }
2441
2520
  }
2442
2521
  /**
2522
+ * Determines whether a native input exposes separately editable segments under one focused element.
2523
+ *
2524
+ * @param element - The element whose native input type is read in its own document's realm.
2525
+ * @returns True if the element is an input with a type in {@link SEGMENTED_INPUT_TYPES}, checked
2526
+ * against its own document's `HTMLInputElement`; false otherwise, including a document with no window.
2527
+ *
2528
+ * @example
2529
+ * ```ts
2530
+ * supportsSegmentedFocus(document.createElement('button')) // false
2531
+ * ```
2532
+ */
2533
+ function supportsSegmentedFocus(element) {
2534
+ const realm = element.ownerDocument.defaultView;
2535
+ return realm !== null && element instanceof realm.HTMLInputElement && SEGMENTED_INPUT_TYPES.includes(element.type);
2536
+ }
2537
+ /**
2538
+ * Checks whether a landing can carry a requested accessible name without resolving the document.
2539
+ *
2540
+ * @param element - The element focus landed on.
2541
+ * @param name - The name the resolver matches.
2542
+ * @param exact - If `true`, compares exact names; if `false`, compares case-insensitive substrings.
2543
+ * Default: `true`.
2544
+ * @returns True if the name matches or its computation requires the resolver; false otherwise.
2545
+ *
2546
+ * @remarks
2547
+ * This is a conservative candidate check, not an accessible-name implementation. It compares a
2548
+ * nonempty `aria-label` without `aria-labelledby`, or the text of a plain native button or link.
2549
+ * Referenced labels, associated labels, descendants, shadow content, owned content, explicit roles,
2550
+ * generated content, and other naming rules fall through to the resolver. Empty requested names
2551
+ * also fall through because a role can prohibit naming. Whitespace, zero-width spaces, and soft
2552
+ * hyphens are normalized as in the provider's role query. Never use this check to accept a target.
2553
+ *
2554
+ * @example
2555
+ * ```ts
2556
+ * matchesTraversalName(document.createElement('input'), 'Attachments') // true
2557
+ * ```
2558
+ */
2559
+ function matchesTraversalName(element, name, exact = true) {
2560
+ const wanted = name.replaceAll(/[\u200b\u00ad]/g, "").trim().replaceAll(/\s+/g, " ");
2561
+ if (wanted.length === 0 || element.hasAttribute("aria-labelledby")) return true;
2562
+ const label = element.getAttribute("aria-label") ?? "";
2563
+ const realm = element.ownerDocument.defaultView;
2564
+ if (label.trim().length === 0) {
2565
+ if (realm === null || !(element instanceof realm.HTMLButtonElement || element instanceof realm.HTMLAnchorElement) || element.hasAttribute("role") || element.hasAttribute("aria-owns") || element.childElementCount > 0 || element.shadowRoot !== null || element instanceof realm.HTMLButtonElement && (element.labels?.length ?? 0) > 0 || element instanceof realm.HTMLAnchorElement && !element.hasAttribute("href")) return true;
2566
+ if (![realm.getComputedStyle(element, "::before"), realm.getComputedStyle(element, "::after")].every((style) => style.content === "none" || style.content === "normal")) return true;
2567
+ if ((element.textContent ?? "").trim().length === 0) return true;
2568
+ }
2569
+ const actual = (label.trim().length > 0 ? label : element.textContent ?? "").replaceAll(/[\u200b\u00ad]/g, "").trim().replaceAll(/\s+/g, " ");
2570
+ return exact ? actual === wanted : actual.toUpperCase().includes(wanted.toUpperCase());
2571
+ }
2572
+ /**
2443
2573
  * Reaches the control a resolver returns, only through natural forward Tab traversal from the
2444
2574
  * current focus.
2445
2575
  *
2446
- * @param resolve - The resolver that returns the target, called before the first step and again on
2447
- * every step, because a framework may replace the node between resolution and focus arrival.
2576
+ * @param resolve - The resolver called before traversal and at candidate arrivals, without retaining
2577
+ * its result between steps.
2448
2578
  * @param name - The target's name, as the refusal voices it.
2579
+ * @param candidate - The landing check; it must admit every element the resolver could return.
2580
+ * Default: the conservative exact-name check from {@link matchesTraversalName}. Supply a check
2581
+ * matching the resolver's semantics when it uses a label, region, or loose name.
2449
2582
  * @returns The target after the browser moves focus to it.
2450
2583
  * @throws When the resolver refuses, or one complete traversal cannot reach the target.
2451
2584
  *
2452
2585
  * @remarks
2453
2586
  * This is the one loop every traversal verb shares, over {@link stepFocus}. A step counts only when
2454
- * focus lands on an element, the traversal is over when focus revisits one, and the cap is counted
2455
- * off {@link FOCUSABLE_SELECTOR}.
2587
+ * focus lands on an element. Consecutive landings on the same native segmented input continue
2588
+ * through its segments up to {@link FOCUS_SEGMENT_LIMIT} landings and count that control once.
2589
+ * A longer run or any other revisit ends the traversal. Any different landing starts a separate run.
2590
+ * The press cap is {@link FOCUS_SEGMENT_LIMIT} times the {@link FOCUSABLE_SELECTOR} candidate count
2591
+ * plus ten, so a page of segmented inputs has a budget for their segments and picker indicators.
2456
2592
  *
2457
2593
  * @example
2458
2594
  * ```ts
2459
2595
  * await driveTraversal(() => resolveRendered('Evaluate'), 'Evaluate')
2460
2596
  * ```
2461
2597
  */
2462
- async function driveTraversal(resolve, name) {
2598
+ async function driveTraversal(resolve, name, candidate) {
2463
2599
  resolve();
2464
- const cap = document.querySelectorAll(FOCUSABLE_SELECTOR).length * 3 + 10;
2600
+ const cap = document.querySelectorAll(FOCUSABLE_SELECTOR).length * 10 + 10;
2465
2601
  const visited = /* @__PURE__ */ new Set();
2466
- const trail = [];
2602
+ const stops = [];
2467
2603
  for await (const focused of stepFocus(cap)) {
2604
+ const previous = stops.at(-1);
2605
+ stops.push(focused);
2468
2606
  if (focused === void 0) continue;
2469
2607
  try {
2470
- const current = resolve();
2471
- if (focused === current) return current;
2608
+ if (candidate === void 0 ? matchesTraversalName(focused, name) : candidate(focused)) {
2609
+ const current = resolve();
2610
+ if (focused === current) return current;
2611
+ }
2472
2612
  } catch {
2473
2613
  continue;
2474
2614
  }
2615
+ if (focused === previous && supportsSegmentedFocus(focused) && stops.length - stops.findLastIndex((entry) => entry !== focused) - 1 <= 10) continue;
2475
2616
  if (visited.has(focused)) break;
2476
2617
  visited.add(focused);
2477
- trail.push(`${focused.tagName}:${focused.innerText.slice(0, 20)}`);
2478
2618
  }
2619
+ const trail = [...new Set(stops)].filter((focused) => focused !== void 0).filter((focused) => visited.has(focused)).map((focused) => `${focused.tagName}:${focused.innerText.slice(0, 20)}`);
2479
2620
  throw new Error(`Interactive target "${name}" is not reachable through forward Tab traversal: ${trail.join(" > ")}`);
2480
2621
  }
2481
2622
  /**
@@ -2484,8 +2625,8 @@ async function driveTraversal(resolve, name) {
2484
2625
  *
2485
2626
  * @param stop - Accepts the destination. Omit it to census the remaining document.
2486
2627
  * @returns Every element focus reached, in order and each once, the accepted stop last.
2487
- * @throws Thrown when the walk outlasts every element the page holds, a key press rejects, or focus
2488
- * lands in a frame from another origin.
2628
+ * @throws Thrown when the walk exceeds its press cap, a key press rejects, or focus lands in a
2629
+ * frame from another origin.
2489
2630
  *
2490
2631
  * @remarks
2491
2632
  * The walk records the focused element and then presses Tab through {@link stepFocus}, so it reaches
@@ -2494,8 +2635,14 @@ async function driveTraversal(resolve, name) {
2494
2635
  * innermost focused element {@link readActiveElement} reads, so a control inside an open shadow root
2495
2636
  * or a same-origin frame is a stop of its own, and its host or frame element is not. The walk ends
2496
2637
  * with an empty list when only the body holds focus, and where focus revisits a stop or returns to
2497
- * the body. It applies no rule about which stop counts: the predicate sees each one and decides, so
2498
- * a consumer that refuses a hidden stop throws from its own predicate.
2638
+ * the body. Consecutive landings on the same native segmented input continue through its segments
2639
+ * up to {@link FOCUS_SEGMENT_LIMIT} landings, including the initial focused element, and count that
2640
+ * control once. A longer run or any other revisit, including a repeated button in a focus trap,
2641
+ * ends the walk. Any different landing starts a separate run.
2642
+ * The press cap is {@link FOCUS_SEGMENT_LIMIT} times {@link countElements}, including
2643
+ * open shadow roots and same-origin frames. It applies no rule about which stop counts: the
2644
+ * predicate sees each one and decides, so a consumer that refuses a hidden stop throws from its own
2645
+ * predicate.
2499
2646
  *
2500
2647
  * A closed shadow root cannot be entered, so its host stands for everything inside it, and a frame
2501
2648
  * from another origin is refused because its controls cannot be named.
@@ -2509,9 +2656,14 @@ async function walkFocus(stop) {
2509
2656
  const first = readActiveElement();
2510
2657
  if (first === void 0) return [];
2511
2658
  const reached = [first];
2659
+ const stops = [first];
2512
2660
  if (stop?.(first) === true) return reached;
2513
- for await (const focused of stepFocus(countElements())) {
2514
- if (focused === void 0 || reached.includes(focused)) return reached;
2661
+ for await (const focused of stepFocus(countElements() * 10)) {
2662
+ if (focused === void 0) return reached;
2663
+ const previous = stops.at(-1);
2664
+ stops.push(focused);
2665
+ if (focused === previous && supportsSegmentedFocus(focused) && stops.length - stops.findLastIndex((entry) => entry !== focused) - 1 <= 10) continue;
2666
+ if (reached.includes(focused)) return reached;
2515
2667
  reached.push(focused);
2516
2668
  if (stop?.(focused) === true) return reached;
2517
2669
  }
@@ -2533,7 +2685,9 @@ async function walkFocus(stop) {
2533
2685
  * {@link containsNode}, so a control inside an open shadow root or a same-origin frame that `root`
2534
2686
  * holds is in the region, and `start` may sit inside one. A `start` that sits outside the region,
2535
2687
  * as the control immediately before it, is the walk's origin and never its end, so the first Tab into the
2536
- * region reaches its first stop.
2688
+ * region reaches its first stop. A native segmented input contributes one stop while consecutive
2689
+ * landings pass through its segments up to {@link FOCUS_SEGMENT_LIMIT} landings. A longer run or
2690
+ * any other revisit ends the walk.
2537
2691
  *
2538
2692
  * @example
2539
2693
  * ```ts
@@ -2703,7 +2857,7 @@ function readText(element) {
2703
2857
  * A declared `role` wins outright, and its first token is the answer when several are listed.
2704
2858
  * Otherwise the element's own anatomy decides: an anchor is a link only while it holds an `href`,
2705
2859
  * an `input` takes the role {@link FIELD_ROLES} gives its type, a `select` is a combobox until it
2706
- * offers several rows at once, a `section` is a region only once something names it, and a `th`
2860
+ * offers several rows at once, a `section` is a region only after something names it, and a `th`
2707
2861
  * heads whichever axis its `scope` names. Every other tag answers from {@link IMPLICIT_ROLES},
2708
2862
  * whose membership is the contract for what this can answer at all.
2709
2863
  *
@@ -2913,11 +3067,11 @@ async function waitForState(first, second, third, fourth) {
2913
3067
  const absent = options?.absent ?? false;
2914
3068
  const description = `"${name}" to ${absent ? "stop announcing" : "announce"} "${state}"`;
2915
3069
  let observed = [];
2916
- let readings = 0;
3070
+ let count = 0;
2917
3071
  let refused;
2918
3072
  try {
2919
3073
  await waitForCondition(description, () => {
2920
- readings += 1;
3074
+ count += 1;
2921
3075
  try {
2922
3076
  observed = readStates(role === void 0 ? resolveRendered(name) : resolveRendered(role, name));
2923
3077
  } catch (thrown) {
@@ -2929,7 +3083,7 @@ async function waitForState(first, second, third, fourth) {
2929
3083
  } catch (cause) {
2930
3084
  if (refused !== void 0 && cause === refused.thrown) throw cause;
2931
3085
  if (cause === options?.signal?.reason) throw cause;
2932
- if (readings === 0) throw cause;
3086
+ if (count === 0) throw cause;
2933
3087
  if (!isError(cause)) throw cause;
2934
3088
  throw new Error(`${cause.message} (last states: ${JSON.stringify(observed)})`, { cause });
2935
3089
  }
@@ -2940,7 +3094,7 @@ async function waitForState(first, second, third, fourth) {
2940
3094
  *
2941
3095
  * @param element - The element whose own animations and descendants' animations to wait on.
2942
3096
  * @param options - The time bounds and the abort signal.
2943
- * @returns A promise resolving once no finite animation is still running.
3097
+ * @returns A promise resolving after every finite animation has stopped running.
2944
3098
  * @throws An `Error` when the element is not in a document, when a bound is invalid, or when an
2945
3099
  * animation is still running at the budget; or the abort reason.
2946
3100
  *
@@ -3053,7 +3207,7 @@ function readAnimations(element) {
3053
3207
  * A pointer left over a control paints that control's hover, and a transition still running paints
3054
3208
  * a fill between two states, so neither is a state the interface rests in. An endless animation, a
3055
3209
  * spinner or a placeholder shimmer, stands at a different phase in every frame unless it is held at
3056
- * the same one, so each is paused at its first frame. Call the resume once the frame is shot; a
3210
+ * the same one, so each is paused at its first frame. Call the resume after the frame is shot; a
3057
3211
  * capture that throws still owes it, so call it from a `finally` block.
3058
3212
  *
3059
3213
  * The subject is the whole document, its root element included. The pointer parks through
@@ -4183,7 +4337,7 @@ function parseColor(value) {
4183
4337
  * property is named by letters, digits, `_`, and `-` after its `--`. A name the scope leaves
4184
4338
  * undeclared is not carried, so its `var()` fallback still applies.
4185
4339
  *
4186
- * The scope element is never written. The probe is new, so it has no earlier style to start a
4340
+ * The scope element is never written. The probe is freshly created, so it has no earlier style to start a
4187
4341
  * transition from, and a transition running on the scope keeps running: `currentColor` reads the
4188
4342
  * color the scope shows at that moment, and the scope's geometry and scroll position stay as they
4189
4343
  * were. No attribute, style, or child of the scope changes, so a `MutationObserver` on it records
@@ -4519,7 +4673,7 @@ function readContrast(element, floor) {
4519
4673
  * @remarks
4520
4674
  * This reads and never acts. Focus arrives through the published verbs — `traverseAccessible`,
4521
4675
  * `userEvent.keyboard` from `vitest/browser`, a real click — and this measures what the browser
4522
- * painted once it landed. A control that is not matching `:focus-visible` when the call is made
4676
+ * painted after it landed. A control that is not matching `:focus-visible` when the call is made
4523
4677
  * reports nothing, because no measurement taken then would be about focus.
4524
4678
  *
4525
4679
  * Some controls are two elements: one that takes the focus and one a reader can see. A hidden radio
@@ -5066,6 +5220,6 @@ function buildCensus() {
5066
5220
  });
5067
5221
  }
5068
5222
  //#endregion
5069
- export { ACCESSIBLE_ROLES, CANVAS_COLOR, CAPTURE_PANE, CAPTURE_STAGINGS, CONTENT_ROLES, FIELD_ROLES, FOCUSABLE_SELECTOR, HEADER_ROLES, IMPLICIT_ROLES, MEDIA_STAGE, POINTER_HOLD, adoptSheet, blendColor, build, buildCensus, buildContrast, buildDenial, buildEscapes, captureFrame, chooseAccessible, clearStorage, clickAccessible, clickAccessibleWithin, clickDisclosure, clipsOverflow, collectClippingAncestors, collectScrollRegions, collectTabStops, commitInput, computeNamePattern, computeOffset, containsNode, convertA98RGB, convertDisplayP3, convertLab, convertLinearSRGB, convertOKLab, convertProPhotoRGB, convertRec2020, convertSRGB, convertXYZD50, convertXYZD65, countElements, createChannel, createDragEvent, createHarness, createJournal, createKeyboardEvent, createPointerEvent, createPortfolio, createStorage, describeFocus, describeScrollRegions, describeTree, driveHold, driveTraversal, expandCaptures, extractOrphans, extractStyles, fillAccessible, findKeyframes, findRule, holdAccessible, holdAccessibleWithin, hoverAccessible, isOutsideViewport, isReachable, isRendered, matchesColor, measureContent, measureContrast, measureLuminance, mount, paintImage, parkPointer, parseCSSColor, parseColor, pressKeys, readAccessibilityNode, readActiveElement, readAnimations, readBackdrop, readCascade, readCensus, readClasses, readClipEdge, readClipMargin, readClippedBlock, readColorContrast, readContrast, readFocus, readFrame, readHit, readLayerNames, readLayers, readName, readPage, readPerception, readPixels, readProtocolNode, readProtocolPoint, readRefusal, readRing, readRole, readRootToken, readRows, readRules, readShotPixel, readStates, readStyle, readText, readToken, readValue, releaseMedia, releasePane, releasePointer, releaseTouch, removeDatabase, render, resolveAccessible, resolveAccessibleWithin, resolveFileInput, resolveRendered, sendFileDrag, sendProtocol, sendTouch, settleCapture, stageMedia, stagePane, stepFocus, tapTouch, traverseAccessible, traverseAccessibleWithin, typeAccessible, typeInput, waitForAnimations, waitForFrame, waitForStability, waitForState, walkFocus };
5223
+ export { ACCESSIBLE_ROLES, CANVAS_COLOR, CAPTURE_PANE, CAPTURE_STAGE_LIMIT, CONTENT_ROLES, FIELD_ROLES, FOCUSABLE_SELECTOR, FOCUS_SEGMENT_LIMIT, HEADER_ROLES, IMPLICIT_ROLES, MEDIA_STAGE, POINTER_HOLD, SEGMENTED_INPUT_TYPES, adoptSheet, blendColor, build, buildCensus, buildContrast, buildDenial, buildEscapes, captureFrame, chooseAccessible, clearStorage, clickAccessible, clickAccessibleWithin, clickDisclosure, clipsOverflow, collectClippingAncestors, collectScrollRegions, collectTabStops, commitInput, computeNamePattern, computeOffset, containsNode, convertA98RGB, convertDisplayP3, convertLab, convertLinearSRGB, convertOKLab, convertProPhotoRGB, convertRec2020, convertSRGB, convertXYZD50, convertXYZD65, countElements, createChannel, createDragEvent, createHarness, createJournal, createKeyboardEvent, createPointerEvent, createPortfolio, createStorage, describeFocus, describeScrollRegions, describeTree, driveHold, driveTraversal, expandCaptures, extractOrphans, extractStyles, fillAccessible, findKeyframes, findRule, holdAccessible, holdAccessibleWithin, hoverAccessible, isOutsideViewport, isReachable, isRendered, matchesColor, matchesTraversalName, measureContent, measureContrast, measureLuminance, mount, paintImage, parkPointer, parseCSSColor, parseColor, pressKeys, readAccessibilityNode, readActiveElement, readAnimations, readBackdrop, readCaptureReader, readCascade, readCensus, readClasses, readClipEdge, readClipMargin, readClippedBlock, readColorContrast, readContrast, readFocus, readFrame, readHit, readLayerNames, readLayers, readName, readPage, readPerception, readPixels, readProtocolNode, readProtocolPoint, readRefusal, readRing, readRole, readRootToken, readRows, readRules, readShotPixel, readStates, readStyle, readText, readToken, readValue, releaseMedia, releasePane, releasePointer, releaseTouch, removeDatabase, render, resolveAccessible, resolveAccessibleWithin, resolveFileInput, resolveRendered, sendFileDrag, sendProtocol, sendTouch, settleCapture, stageMedia, stagePane, stepFocus, supportsSegmentedFocus, tapTouch, traverseAccessible, traverseAccessibleWithin, typeAccessible, typeInput, verifyFrame, waitForAnimations, waitForFrame, waitForStability, waitForState, walkFocus };
5070
5224
 
5071
5225
  //# sourceMappingURL=index.js.map