@typeonce/ritmo-devtools 0.24.0 → 0.26.0

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.
Files changed (53) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/README.md +197 -1
  3. package/dist/Fuzz.d.ts +38 -6
  4. package/dist/Fuzz.d.ts.map +1 -1
  5. package/dist/Fuzz.js +37 -11
  6. package/dist/Fuzz.js.map +1 -1
  7. package/dist/Replay.d.ts +1 -1
  8. package/dist/cli.js +171 -3
  9. package/dist/cli.js.map +1 -1
  10. package/dist/internal/dependencyScan.js +1 -1
  11. package/dist/internal/dependencyScan.js.map +1 -1
  12. package/dist/internal/fuzzNetwork.d.ts +15 -2
  13. package/dist/internal/fuzzNetwork.d.ts.map +1 -1
  14. package/dist/internal/fuzzNetwork.js +30 -7
  15. package/dist/internal/fuzzNetwork.js.map +1 -1
  16. package/dist/internal/keyboardPage.d.ts +29 -0
  17. package/dist/internal/keyboardPage.d.ts.map +1 -0
  18. package/dist/internal/keyboardPage.js +199 -0
  19. package/dist/internal/keyboardPage.js.map +1 -0
  20. package/dist/internal/keyboardWalk.d.ts +91 -0
  21. package/dist/internal/keyboardWalk.d.ts.map +1 -0
  22. package/dist/internal/keyboardWalk.js +373 -0
  23. package/dist/internal/keyboardWalk.js.map +1 -0
  24. package/dist/internal/layoutPage.d.ts +35 -0
  25. package/dist/internal/layoutPage.d.ts.map +1 -0
  26. package/dist/internal/layoutPage.js +535 -0
  27. package/dist/internal/layoutPage.js.map +1 -0
  28. package/dist/internal/layoutWalk.d.ts +84 -0
  29. package/dist/internal/layoutWalk.d.ts.map +1 -0
  30. package/dist/internal/layoutWalk.js +252 -0
  31. package/dist/internal/layoutWalk.js.map +1 -0
  32. package/dist/internal/pageOpen.d.ts +86 -0
  33. package/dist/internal/pageOpen.d.ts.map +1 -0
  34. package/dist/internal/pageOpen.js +166 -0
  35. package/dist/internal/pageOpen.js.map +1 -0
  36. package/dist/internal/route.d.ts +94 -0
  37. package/dist/internal/route.d.ts.map +1 -0
  38. package/dist/internal/route.js +230 -0
  39. package/dist/internal/route.js.map +1 -0
  40. package/dist/internal/version.d.ts +1 -1
  41. package/dist/internal/version.js +1 -1
  42. package/package.json +3 -3
  43. package/src/Fuzz.ts +62 -11
  44. package/src/cli.ts +165 -3
  45. package/src/internal/dependencyScan.ts +1 -1
  46. package/src/internal/fuzzNetwork.ts +33 -7
  47. package/src/internal/keyboardPage.ts +198 -0
  48. package/src/internal/keyboardWalk.ts +474 -0
  49. package/src/internal/layoutPage.ts +534 -0
  50. package/src/internal/layoutWalk.ts +365 -0
  51. package/src/internal/pageOpen.ts +225 -0
  52. package/src/internal/route.ts +276 -0
  53. package/src/internal/version.ts +1 -1
package/src/cli.ts CHANGED
@@ -5,6 +5,8 @@
5
5
  * ritmo-devtools lint <entry>
6
6
  * ritmo-devtools verify <entry> <replay> [--engines node,chromium,webkit,firefox] [--json]
7
7
  * ritmo-devtools scan <entry> [--json]
8
+ * ritmo-devtools keyboard [--url <url>] [--route <file>] [--json]
9
+ * ritmo-devtools layout [--url <url>] [--route <file>] [--screenshots <dir>] [--json]
8
10
  *
9
11
  * `lint` imports `<entry>` (a module exporting `lintTarget`, see the `Lint` module),
10
12
  * prints every lint of its schedules with its fix, and exits with 1 when one
@@ -54,9 +56,33 @@
54
56
  * and the game's `oxlint` with `@typeonce/oxlint-plugin-ritmo`; a missing one
55
57
  * is printed with its install command and exits with 2.
56
58
  *
59
+ * `keyboard` plays the game's page by keyboard in Chromium and checks, on
60
+ * each screen of a route, what a keyboard player relies on: focus moves into
61
+ * an open menu and Tab stays there, every control has a name, Enter and
62
+ * Space press the focused control, a press keeps focus off `<body>`, and
63
+ * every visible control is reached by Tab or by its group's arrow keys.
64
+ * Without `--url` it serves the working directory with the game's own Vite
65
+ * config. `--route <file>` names the screens to visit (JSON, see the README);
66
+ * without it the start page is one screen. It needs `playwright` and its
67
+ * Chromium, and `vite` when there is no `--url`; a missing one is printed
68
+ * with its install command.
69
+ *
70
+ * `layout` opens each screen of the same route in Chromium at each of the
71
+ * route's viewports (phones held both ways and a desktop by default) and
72
+ * reports what is broken in the layout: things drawn over each other, text
73
+ * cut by a box, anything past the screen's edge or in the device's own
74
+ * space, taps that land on too small an area, and layout that moves while
75
+ * nothing happens. Those fail. Text shortened with an ellipsis, controls half
76
+ * hidden at a scroll edge, and what breaks with every text 40% longer are
77
+ * warnings, which never fail. `--screenshots <dir>` saves each screen with
78
+ * its findings boxed and numbered. It needs what `keyboard` needs.
79
+ *
57
80
  * Exit codes: 0 ok (and every `scan` that ran), 1 lint warning, uncovered
58
- * module, mismatched versions, or an engine that differs or did not run, 2 usage error (for `scan`
59
- * also an unreadable entry, an import that does not resolve, or a missing tool).
81
+ * module, mismatched versions, an engine that differs or did not run, or a
82
+ * keyboard failure, or a layout error, 2 usage error (for `scan` also an
83
+ * unreadable entry, an import that does not resolve, or a missing tool; for
84
+ * `keyboard` and `layout` an invalid route, a missing tool, or a dev server
85
+ * that did not start).
60
86
  * Requires Node 22.15 or later for `module.registerHooks`; on older Node it
61
87
  * prints that coverage was not checked.
62
88
  *
@@ -64,11 +90,15 @@
64
90
  * @docGroup devtools
65
91
  */
66
92
  import { readFileSync } from "node:fs"
93
+ import { availableParallelism } from "node:os"
67
94
  import { resolve } from "node:path"
68
95
  import { pathToFileURL } from "node:url"
69
96
 
70
97
  import * as DependencyScan from "./internal/dependencyScan.ts"
98
+ import * as KeyboardWalk from "./internal/keyboardWalk.ts"
99
+ import * as LayoutWalk from "./internal/layoutWalk.ts"
71
100
  import * as PackageVersions from "./internal/packageVersions.ts"
101
+ import * as Route from "./internal/route.ts"
72
102
  import * as SimulationCoverage from "./internal/simulationCoverage.ts"
73
103
  import * as SkillLink from "./internal/skillLink.ts"
74
104
  import * as Lint from "./Lint.ts"
@@ -79,9 +109,13 @@ const usage = [
79
109
  "usage: ritmo-devtools lint <entry>",
80
110
  " ritmo-devtools verify <entry> <replay> [--engines node,chromium,webkit,firefox] [--json]",
81
111
  " ritmo-devtools scan <entry> [--json]",
112
+ " ritmo-devtools keyboard [--url <url>] [--route <file>] [--json]",
113
+ " ritmo-devtools layout [--url <url>] [--route <file>] [--screenshots <dir>] [--json]",
82
114
  " lint: <entry> exports lintTarget: () => { runtime, schedules, describe?, hostEvents? } (see the Lint module)",
83
115
  " verify: <entry> exports replayTarget: (playback) => { runtime, schedules, hostClock } (see the Verify module)",
84
- " scan: <entry> is the simulation's entry module; every file it imports, node_modules included, is checked for Math, clock, and randomness calls"
116
+ " scan: <entry> is the simulation's entry module; every file it imports, node_modules included, is checked for Math, clock, and randomness calls",
117
+ " keyboard: plays the page at --url (or the working directory served with its Vite config) by keyboard in Chromium; --route is a JSON file of screens",
118
+ " layout: measures each screen of the route at each of its viewports in Chromium; --screenshots writes each screen with its findings boxed"
85
119
  ].join("\n")
86
120
 
87
121
  const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null
@@ -101,6 +135,8 @@ const main = async (args: ReadonlyArray<string>): Promise<number> => {
101
135
  if (command === "lint" && rest.length === 1) return lint(rest[0]!)
102
136
  if (command === "verify") return verify(rest)
103
137
  if (command === "scan") return scan(rest)
138
+ if (command === "keyboard") return keyboard(rest)
139
+ if (command === "layout") return layout(rest)
104
140
  console.error(usage)
105
141
  return 2
106
142
  }
@@ -223,6 +259,132 @@ const scan = async (args: ReadonlyArray<string>): Promise<number> => {
223
259
  return 0
224
260
  }
225
261
 
262
+ /** The value of `--name value` or `--name=value` at `index`, and how many arguments it took; undefined when `args[index]` is not that flag. */
263
+ const flag = (args: ReadonlyArray<string>, index: number, name: string): { readonly value: string | undefined; readonly taken: number } | undefined => {
264
+ const arg = args[index]!
265
+ if (arg === name) return { value: args[index + 1], taken: 2 }
266
+ if (arg.startsWith(`${name}=`)) return { value: arg.slice(name.length + 1), taken: 1 }
267
+ return undefined
268
+ }
269
+
270
+ /** The walks over a game's page: which one, and the flags only it takes. */
271
+ type PageCommand = "keyboard" | "layout"
272
+
273
+ const keyboard = (args: ReadonlyArray<string>): Promise<number> => pageWalk("keyboard", args)
274
+
275
+ const layout = (args: ReadonlyArray<string>): Promise<number> => pageWalk("layout", args)
276
+
277
+ /**
278
+ * Reads `--url`, `--route`, `--json` (and `layout`'s `--screenshots`),
279
+ * launches Chromium, serves the working directory with the game's Vite
280
+ * config when there is no `--url`, and runs the walk.
281
+ */
282
+ const pageWalk = async (command: PageCommand, args: ReadonlyArray<string>): Promise<number> => {
283
+ let url: string | undefined
284
+ let routeFile: string | undefined
285
+ let screenshots: string | undefined
286
+ let json = false
287
+ for (let index = 0; index < args.length;) {
288
+ if (args[index] === "--json") {
289
+ json = true
290
+ index++
291
+ continue
292
+ }
293
+ const named = ["--url", "--route", ...(command === "layout" ? ["--screenshots"] : [])]
294
+ const name = named.find((candidate) => flag(args, index, candidate) !== undefined)
295
+ const given = name === undefined ? undefined : flag(args, index, name)
296
+ if (name === undefined || given === undefined || given.value === undefined || given.value === "") {
297
+ console.error(usage)
298
+ return 2
299
+ }
300
+ if (name === "--url") url = given.value
301
+ else if (name === "--route") routeFile = given.value
302
+ else screenshots = resolve(given.value)
303
+ index += given.taken
304
+ }
305
+ if (url !== undefined && !/^https?:\/\//.test(url)) {
306
+ console.error(`--url must be an http(s) URL of the game's page, such as http://localhost:5173/; got ${url}`)
307
+ return 2
308
+ }
309
+ let route = Route.startRoute
310
+ if (routeFile !== undefined) {
311
+ let data: unknown
312
+ try {
313
+ data = JSON.parse(readFileSync(resolve(routeFile), "utf8"))
314
+ } catch (error) {
315
+ console.error(`${routeFile} could not be read as JSON: ${error instanceof Error ? error.message : String(error)}`)
316
+ return 2
317
+ }
318
+ const parsed = Route.parseRoute(data)
319
+ if (!parsed.ok) {
320
+ console.error(`${routeFile} is not a ${command} route: ${parsed.error}`)
321
+ return 2
322
+ }
323
+ route = parsed.value
324
+ }
325
+ let playwright: typeof import("playwright")
326
+ try {
327
+ playwright = await import("playwright")
328
+ } catch {
329
+ console.error(`${command} needs playwright, which is not installed: npm install --save-dev playwright && npx playwright install chromium`)
330
+ return 2
331
+ }
332
+ let browser: Awaited<ReturnType<typeof playwright.chromium.launch>>
333
+ try {
334
+ browser = await playwright.chromium.launch()
335
+ } catch (error) {
336
+ const message = error instanceof Error ? error.message : String(error)
337
+ console.error(/Executable doesn't exist|playwright install/i.test(message)
338
+ ? `${command} needs Chromium, which is not downloaded: npx playwright install chromium`
339
+ : `Chromium did not launch: ${message.split("\n")[0]}`)
340
+ return 2
341
+ }
342
+ let server: { readonly close: () => Promise<void> } | undefined
343
+ try {
344
+ if (url === undefined) {
345
+ let vite: typeof import("vite")
346
+ try {
347
+ vite = await import("vite")
348
+ } catch {
349
+ console.error(`${command} serves the game with its own Vite config and needs vite, which is not installed: npm install --save-dev vite (or pass --url of a running dev server)`)
350
+ return 2
351
+ }
352
+ try {
353
+ const dev = await vite.createServer({
354
+ root: process.cwd(),
355
+ logLevel: "silent",
356
+ clearScreen: false,
357
+ server: { host: "127.0.0.1", port: 0, strictPort: false, hmr: false, watch: null }
358
+ })
359
+ server = dev
360
+ await dev.listen()
361
+ const address = dev.httpServer?.address()
362
+ if (address === null || address === undefined || typeof address === "string") {
363
+ console.error("the Vite dev server did not report its port")
364
+ return 2
365
+ }
366
+ url = `http://127.0.0.1:${address.port}/`
367
+ } catch (error) {
368
+ console.error(`the game's Vite dev server did not start: ${error instanceof Error ? error.message : String(error)}`)
369
+ return 2
370
+ }
371
+ }
372
+ if (command === "keyboard") {
373
+ // Half the cores, four pages at most: each page runs the whole game.
374
+ const pages = Math.max(1, Math.min(4, Math.floor(availableParallelism() / 2)))
375
+ const report = await KeyboardWalk.walk(browser, { url, route, pages })
376
+ console.log(json ? JSON.stringify(report, null, 2) : KeyboardWalk.format(report))
377
+ return report.ok ? 0 : 1
378
+ }
379
+ const report = await LayoutWalk.walk(browser, screenshots === undefined ? { url, route } : { url, route, screenshots })
380
+ console.log(json ? JSON.stringify(report, null, 2) : LayoutWalk.format(report))
381
+ return report.ok ? 0 : 1
382
+ } finally {
383
+ await browser.close().catch(() => undefined)
384
+ await server?.close().catch(() => undefined)
385
+ }
386
+ }
387
+
226
388
  const withoutText = ({ text: _text, ...error }: Verify.VerifyError) => error
227
389
 
228
390
  process.exitCode = await main(process.argv.slice(2))
@@ -329,7 +329,7 @@ export const run = async (entry: string, cwd: string): Promise<Result.Result<Rep
329
329
  groups.set(name, group)
330
330
  }
331
331
  const packages = [...groups]
332
- .sort(([a], [b]) => a === own ? -1 : b === own ? 1 : a.localeCompare(b))
332
+ .sort(([a], [b]) => a === own ? -1 : b === own ? 1 : a < b ? -1 : a > b ? 1 : 0)
333
333
  .map(([name, group]) => ({ name, files: group.files, findings: group.findings }))
334
334
  return Result.success({ entry: relative(base, realpathSync(absolute)), files: files.length, packages })
335
335
  }
@@ -2,8 +2,8 @@
2
2
  * The network half of `Fuzz.run`: one simulation of every seat as its own
3
3
  * peer, each a fresh runtime from the game's factory, joined by a seeded
4
4
  * `MemoryNetworkLink` on one test clock and driven by `Netcode.rollback`
5
- * sessions. Deterministic for a timeline and a network seed, so shrinking
6
- * can run it again.
5
+ * sessions. Deterministic for a timeline, a network seed, and the frames
6
+ * seats leave on, so shrinking can run it again.
7
7
  */
8
8
  import { HostClock } from "@typeonce/ritmo"
9
9
  import type * as Clock from "@typeonce/ritmo/Clock"
@@ -26,6 +26,8 @@ export interface NetworkPlan {
26
26
  readonly codec: Descriptor.Codec<any, any>
27
27
  readonly count: number
28
28
  readonly idle: unknown
29
+ /** What the simulation reads for a seat that left (`Netcode.seats`' `left`). */
30
+ readonly left: unknown
29
31
  /** The game's factory, and the schedules it is fuzzed with. */
30
32
  readonly make: (playback: Replay.Playback) => { readonly runtime: unknown; readonly schedules: Readonly<Record<string, unknown>> }
31
33
  readonly schedule: string
@@ -53,15 +55,27 @@ export type NetworkViolation =
53
55
  | { readonly _tag: "InvariantViolated"; readonly invariant: string; readonly message: string }
54
56
  | { readonly _tag: "Defect"; readonly invariant: string | undefined; readonly error: unknown }
55
57
 
56
- /** Plays `timeline` (per frame, the seats input's value: every seat's local input) on one peer per seat, then `settle` idle frames. */
57
- export const play = (plan: NetworkPlan, timeline: ReadonlyArray<ReadonlyArray<unknown>>): NetworkOutcome<NetworkViolation> => {
58
+ /** A seat whose page is gone from `frame` on (0: before the first one). */
59
+ export interface Leave {
60
+ readonly seat: number
61
+ readonly frame: number
62
+ }
63
+
64
+ /**
65
+ * Plays `timeline` (per frame, the seats input's value: every seat's local
66
+ * input) on one peer per seat, then `settle` idle frames. A seat of `leaves`
67
+ * closes its link and runs no more from its frame on; every peer still there
68
+ * is told (`session.drop`) once the link's latency passed, as a relay that
69
+ * saw the socket close tells them.
70
+ */
71
+ export const play = (plan: NetworkPlan, timeline: ReadonlyArray<ReadonlyArray<unknown>>, leaves: ReadonlyArray<Leave> = []): NetworkOutcome<NetworkViolation> => {
58
72
  const hostClock = HostClock.test()
59
73
  const links = MemoryNetworkLink.make({ peers: plan.count, hostClock, seed: plan.seed, latencyMS: plan.latencyMS, jitterMS: plan.jitterMS, loss: plan.loss })
60
74
  if (!links.ok) return { kind: "invalid", message: `network.${links.error.field} is out of range: ${links.error.value}` }
61
75
  const peers: Array<{ readonly runtime: Peer; readonly session: Netcode.Session<unknown, unknown> }> = []
62
76
  for (let seat = 0; seat < plan.count; seat++) {
63
- const seats = Netcode.seats(plan.codec, { count: plan.count, idle: plan.idle })
64
- if (!seats.ok) return { kind: "invalid", message: `the seats' idle input: ${seats.error.reason}` }
77
+ const seats = Netcode.seats(plan.codec, { count: plan.count, idle: plan.idle, left: plan.left })
78
+ if (!seats.ok) return { kind: "invalid", message: `the seats' ${seats.error.field} input: ${seats.error.reason}` }
65
79
  const unknown: Array<string> = []
66
80
  const playback: Replay.Playback = {
67
81
  source: <const SourceName extends string, Value extends Source<unknown>>(descriptor: Descriptor.Descriptor<"service", SourceName, Value>): Source<Replay.SourceData<Value>> => {
@@ -102,9 +116,19 @@ export const play = (plan: NetworkPlan, timeline: ReadonlyArray<ReadonlyArray<un
102
116
 
103
117
  const stepMS = plan.step.dt * 1000
104
118
  const frames = timeline.length + plan.settle
119
+ const tellAfter = Math.ceil(plan.latencyMS / stepMS)
120
+ const gone = new Set<number>()
105
121
  for (let frame = 0; frame < frames; frame++) {
122
+ for (const leave of leaves) {
123
+ if (leave.frame === frame) {
124
+ links.value[leave.seat]!.close("the seat left")
125
+ gone.add(leave.seat)
126
+ }
127
+ if (leave.frame + tellAfter === frame) for (const [seat, { session }] of peers.entries()) if (!gone.has(seat)) session.drop(leave.seat)
128
+ }
106
129
  const values = timeline[frame]?.[0] as ReadonlyArray<unknown> | undefined
107
130
  for (const [seat, { session }] of peers.entries()) {
131
+ if (gone.has(seat)) continue
108
132
  let advanced: ReturnType<typeof session.advance>
109
133
  try {
110
134
  advanced = session.advance(values === undefined ? plan.idle : values[seat])
@@ -113,7 +137,9 @@ export const play = (plan: NetworkPlan, timeline: ReadonlyArray<ReadonlyArray<un
113
137
  }
114
138
  if (!advanced.ok) return { kind: "violated", violation: { _tag: "SessionFailed", seat, error: advanced.error }, frame: frame + 1 }
115
139
  }
116
- for (const { runtime } of peers) {
140
+ for (const [seat, { runtime }] of peers.entries()) {
141
+ // A page that is gone holds a world nobody plays.
142
+ if (gone.has(seat)) continue
117
143
  for (const invariant of plan.invariants) {
118
144
  let message: unknown
119
145
  try {
@@ -0,0 +1,198 @@
1
+ /**
2
+ * The page side of `ritmo-devtools keyboard`: a script installed before the
3
+ * game's own scripts on every page the walk opens. It runs in the browser,
4
+ * so it is plain JavaScript in a string: Node never runs it, and the package
5
+ * config has no DOM types.
6
+ *
7
+ * It installs `__ritmoKeyboardWalk` with:
8
+ *
9
+ * - `state()`: the focused element and the open menu, each described;
10
+ * - `signature()`: the page's clock and one string naming the open menu, the
11
+ * focused element, and every visible control, to tell when a screen has
12
+ * stopped changing;
13
+ * - `controls(scope)`: the visible, enabled controls inside the menu (or the
14
+ * page), described;
15
+ * - `groupStops(control, stops)`: the Tab stops in the smallest element that
16
+ * holds the control and at least one stop, for the arrow-key probe;
17
+ * - `arm(stop)` and `result()`: around one key press, whether the focused
18
+ * control was pressed (a `click` reached it, or its `aria-checked`,
19
+ * `aria-pressed`, `aria-expanded`, or `aria-selected` changed) and whether
20
+ * a listener prevented the key; with `stop`, the click is stopped at
21
+ * `window` before any game listener runs, so a press through `click`
22
+ * changes nothing (a control that acts on keydown still acts);
23
+ * - `element(id)`, `focus(id)`: an element by the id the walk gave it.
24
+ *
25
+ * Elements are identified through a `WeakMap`, so the game's DOM is never
26
+ * changed.
27
+ */
28
+ export const pageScript = String.raw`(() => {
29
+ if (globalThis.__ritmoKeyboardWalk) return
30
+ const ids = new WeakMap()
31
+ const byId = new Map()
32
+ let next = 1
33
+ const idOf = (element) => {
34
+ let id = ids.get(element)
35
+ if (id === undefined) {
36
+ id = next++
37
+ ids.set(element, id)
38
+ byId.set(id, new WeakRef(element))
39
+ }
40
+ return id
41
+ }
42
+ const element = (id) => byId.get(id)?.deref() ?? null
43
+ const shown = (element) => typeof element.checkVisibility === "function" && element.checkVisibility({ visibilityProperty: true, opacityProperty: true }) === true
44
+ const visible = (element) => {
45
+ if (!shown(element)) return false
46
+ const box = element.getBoundingClientRect()
47
+ return box.width > 0 && box.height > 0
48
+ }
49
+ const last = (list) => list.length === 0 ? null : list[list.length - 1]
50
+ const openMenu = () =>
51
+ last([...document.querySelectorAll("dialog:modal")])
52
+ ?? last([...document.querySelectorAll('[aria-modal="true"]')].filter(shown))
53
+ ?? last([...document.querySelectorAll('dialog[open], [role="dialog"], [role="alertdialog"]')].filter(shown))
54
+ const selector = (element) => {
55
+ const parts = []
56
+ let at = element
57
+ while (at !== null && at.nodeType === 1 && at !== document.documentElement) {
58
+ if (at.id !== "" && document.querySelectorAll("#" + CSS.escape(at.id)).length === 1) {
59
+ parts.unshift("#" + CSS.escape(at.id))
60
+ break
61
+ }
62
+ let part = at.localName
63
+ const parent = at.parentElement
64
+ if (parent !== null) {
65
+ const same = [...parent.children].filter((child) => child.localName === at.localName)
66
+ if (same.length > 1) part += ":nth-of-type(" + (same.indexOf(at) + 1) + ")"
67
+ }
68
+ parts.unshift(part)
69
+ at = parent
70
+ }
71
+ return parts.join(" > ")
72
+ }
73
+ const nativeKeys = (element) => {
74
+ const tag = element.localName
75
+ const type = (element.getAttribute("type") ?? "").toLowerCase()
76
+ if (tag === "button") return ["Enter", " "]
77
+ if (tag === "input" && ["button", "submit", "reset", "image"].includes(type)) return ["Enter", " "]
78
+ if (tag === "input" && ["checkbox", "radio"].includes(type)) return [" "]
79
+ if (tag === "a" && element.hasAttribute("href")) return ["Enter"]
80
+ if (tag === "summary") return ["Enter", " "]
81
+ return []
82
+ }
83
+ const customRoles = ["button", "link", "checkbox", "switch", "radio", "tab", "menuitem", "menuitemcheckbox", "menuitemradio", "option"]
84
+ const describe = (element) => {
85
+ const tag = element.localName
86
+ const native = nativeKeys(element)
87
+ const role = element.getAttribute("role") ?? ""
88
+ const custom = native.length === 0 && customRoles.includes(role)
89
+ return {
90
+ id: idOf(element),
91
+ tag: element.localName,
92
+ selector: selector(element),
93
+ keys: native.length > 0 ? native : custom ? (role === "link" ? ["Enter"] : ["Enter", " "]) : [],
94
+ native: native.length > 0,
95
+ external: tag === "a" && element.hasAttribute("href") && (() => {
96
+ try {
97
+ return new URL(element.href, location.href).origin !== location.origin
98
+ } catch {
99
+ return false
100
+ }
101
+ })(),
102
+ canvas: element.localName === "canvas"
103
+ }
104
+ }
105
+ const focused = () => {
106
+ const active = document.activeElement
107
+ return active === null || active === document.body || active === document.documentElement ? null : active
108
+ }
109
+ const controlSelector = [
110
+ "button", "a[href]", "input:not([type=hidden])", "select", "textarea", "summary",
111
+ ...customRoles.map((role) => '[role="' + role + '"]'),
112
+ '[role="slider"]', '[role="spinbutton"]', '[role="combobox"]', '[role="textbox"]'
113
+ ].join(", ")
114
+ const visibleControls = (root) => [...root.querySelectorAll(controlSelector)]
115
+ .filter((control) => !control.disabled && control.closest("[inert]") === null && visible(control))
116
+ // A custom control (a switch, a toggle) may act on keydown with no click: a change of its state attributes is a press too.
117
+ const stateOf = (element) => element === null ? "" : ["aria-checked", "aria-pressed", "aria-expanded", "aria-selected"].map((name) => element.getAttribute(name) ?? "").join("|")
118
+ let armed = null
119
+ window.addEventListener("click", (event) => {
120
+ if (armed === null) return
121
+ armed.clicks.push(event.target)
122
+ if (armed.stop) {
123
+ event.stopImmediatePropagation()
124
+ event.preventDefault()
125
+ }
126
+ }, true)
127
+ globalThis.__ritmoKeyboardWalk = {
128
+ element: (id) => element(id),
129
+ focus: (id) => {
130
+ const found = element(id)
131
+ if (found !== null) found.focus()
132
+ return found !== null && document.activeElement === found
133
+ },
134
+ state: () => {
135
+ const menu = openMenu()
136
+ const active = focused()
137
+ return {
138
+ active: active === null ? null : describe(active),
139
+ menu: menu === null ? null : describe(menu),
140
+ inMenu: menu !== null && active !== null && menu.contains(active),
141
+ url: location.href
142
+ }
143
+ },
144
+ controls: (scope) => {
145
+ const root = scope === null ? document.body : element(scope)
146
+ if (root === null) return []
147
+ return visibleControls(root).map(describe)
148
+ },
149
+ signature: () => {
150
+ const menu = openMenu()
151
+ const active = focused()
152
+ return {
153
+ now: performance.now(),
154
+ key: [menu, active, ...(document.body === null ? [] : visibleControls(document.body))].map((element) => element === null ? "-" : idOf(element)).join(" ")
155
+ }
156
+ },
157
+ groupStops: (control, stops) => {
158
+ const target = element(control)
159
+ if (target === null) return []
160
+ const inside = (group) => stops.filter((stop) => {
161
+ const found = element(stop)
162
+ return found !== null && group.contains(found)
163
+ })
164
+ for (let group = target.parentElement; group !== null && group !== document.body && group !== document.documentElement; group = group.parentElement) {
165
+ const found = inside(group)
166
+ if (found.length > 0) return found
167
+ }
168
+ return []
169
+ },
170
+ arm: (stop) => {
171
+ const target = document.activeElement
172
+ const press = { stop, clicks: [], target, before: stateOf(target), keydown: null, keyup: null }
173
+ armed = press
174
+ const down = (event) => {
175
+ press.keydown = event.defaultPrevented
176
+ window.removeEventListener("keydown", down)
177
+ }
178
+ const up = (event) => {
179
+ press.keyup = event.defaultPrevented
180
+ window.removeEventListener("keyup", up)
181
+ }
182
+ window.addEventListener("keydown", down)
183
+ window.addEventListener("keyup", up)
184
+ },
185
+ result: () => {
186
+ const press = armed
187
+ armed = null
188
+ if (press === null) return { pressed: false, keydownPrevented: null, keyupPrevented: null }
189
+ const target = press.target
190
+ const clicked = target !== null && press.clicks.some((clicked) => clicked === target || (clicked instanceof Node && target.contains(clicked)))
191
+ return {
192
+ pressed: clicked || (target !== null && stateOf(target) !== press.before),
193
+ keydownPrevented: press.keydown,
194
+ keyupPrevented: press.keyup
195
+ }
196
+ }
197
+ }
198
+ })()`