@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
@@ -0,0 +1,199 @@
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
+ })()`;
199
+ //# sourceMappingURL=keyboardPage.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"keyboardPage.js","sourceRoot":"","sources":["../../src/internal/keyboardPage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA0K/B,CAAA"}
@@ -0,0 +1,91 @@
1
+ /**
2
+ * `ritmo-devtools keyboard`: plays a game's page by keyboard in Chromium and
3
+ * checks what a keyboard player relies on, on each screen of a route.
4
+ *
5
+ * Six checks, each decided per screen as passed, failed, or not checked
6
+ * (with the reason), never passed by default:
7
+ *
8
+ * - `focus-outside-menu`: a menu is open and focus is outside it;
9
+ * - `tab-leaves-menu`: Tab moves focus out of the open menu;
10
+ * - `unnamed-control`: a control the keyboard reaches (by Tab, or by the
11
+ * arrows of its group) has no accessible name;
12
+ * - `key-not-pressed`: Enter or Space on the focused control did not press
13
+ * it (the click is stopped, so this changes nothing);
14
+ * - `focus-dropped`: pressing a control dropped focus to `<body>` (the
15
+ * control is pressed for real, after a reload of the screen);
16
+ * - `unreachable-control`: a visible control neither Tab nor the arrows of
17
+ * its group reach.
18
+ *
19
+ * A loaded screen is walked once it has stopped changing: no request in
20
+ * flight, and the same menu, focus, and visible controls for 400 ms, or
21
+ * `settle` at the latest. `focus-dropped` presses on several pages at once
22
+ * (`pages`); a press that did not keep focus is run again with no other page
23
+ * open, and that second result is the one reported, so a failure never comes
24
+ * from a busy machine.
25
+ *
26
+ * A page that stops answering for `stall` milliseconds (its main thread is
27
+ * busy, or its renderer hung) is closed and reported as a `page-error`, so
28
+ * the walk fails instead of waiting for ever.
29
+ *
30
+ * A screen on which no check could be decided is a failure too
31
+ * (`nothing-checked`): nothing checked is never an exit code of 0.
32
+ *
33
+ * A menu is a `dialog:modal`, a shown `aria-modal="true"` element (the
34
+ * `checkVisibility` test `Keyboard.actions` uses), or a shown dialog
35
+ * (`<dialog open>`, `role="dialog"`, `role="alertdialog"`). Accessible names
36
+ * come from Chromium's own accessibility tree.
37
+ *
38
+ * @internal
39
+ */
40
+ import type * as PlaywrightTypes from "playwright";
41
+ import type { Control } from "./pageOpen.ts";
42
+ import type { Route } from "./route.ts";
43
+ /** The six checks. */
44
+ export type CheckId = "focus-outside-menu" | "tab-leaves-menu" | "unnamed-control" | "key-not-pressed" | "focus-dropped" | "unreachable-control";
45
+ export declare const checks: ReadonlyArray<CheckId>;
46
+ /** One failure: which check, on which screen, which control, what the walk saw, and what to change. */
47
+ export interface Failure {
48
+ readonly check: CheckId | "route-step" | "page-error" | "nothing-checked";
49
+ readonly screen: string;
50
+ readonly control?: Control;
51
+ readonly saw: string;
52
+ readonly fix: string;
53
+ }
54
+ /** A control a check could not decide, and why. */
55
+ export interface Undecided {
56
+ readonly control?: Control;
57
+ readonly reason: string;
58
+ }
59
+ /** One check on one screen. `passed` counts only what was decided; `undecided` lists the rest. */
60
+ export interface Outcome {
61
+ readonly check: CheckId;
62
+ readonly screen: string;
63
+ readonly status: "passed" | "failed" | "not-checked";
64
+ /** How many controls (or menus) the check decided. */
65
+ readonly decided: number;
66
+ readonly undecided: ReadonlyArray<Undecided>;
67
+ }
68
+ export interface Report {
69
+ readonly ok: boolean;
70
+ readonly url: string;
71
+ readonly screens: ReadonlyArray<string>;
72
+ readonly failures: ReadonlyArray<Failure>;
73
+ readonly outcomes: ReadonlyArray<Outcome>;
74
+ }
75
+ export declare const fixes: Record<Failure["check"], string>;
76
+ /** What the walk needs from outside: the page's URL, the route, and how long to let a screen settle. */
77
+ export interface Options {
78
+ readonly url: string;
79
+ readonly route: Route;
80
+ /** The most milliseconds a loaded page gets to stop changing before the route's steps run (default 1500). */
81
+ readonly settle?: number;
82
+ /** How many pages press controls at once for `focus-dropped` (default 1). */
83
+ readonly pages?: number;
84
+ /** How many milliseconds a page may go without answering before it is closed and reported (default 20000). */
85
+ readonly stall?: number;
86
+ }
87
+ /** Runs the walk in an open Chromium; the caller launches and closes it. */
88
+ export declare const walk: (browser: PlaywrightTypes.Browser, options: Options) => Promise<Report>;
89
+ /** The report as text: one line per failure, then what passed and what was not checked, per screen. */
90
+ export declare const format: (report: Report) => string;
91
+ //# sourceMappingURL=keyboardWalk.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"keyboardWalk.d.ts","sourceRoot":"","sources":["../../src/internal/keyboardWalk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,KAAK,KAAK,eAAe,MAAM,YAAY,CAAA;AAElD,OAAO,KAAK,EAAE,OAAO,EAAgC,MAAM,eAAe,CAAA;AAE1E,OAAO,KAAK,EAAe,KAAK,EAAU,MAAM,YAAY,CAAA;AAE5D,sBAAsB;AACtB,MAAM,MAAM,OAAO,GAAG,oBAAoB,GAAG,iBAAiB,GAAG,iBAAiB,GAAG,iBAAiB,GAAG,eAAe,GAAG,qBAAqB,CAAA;AAEhJ,eAAO,MAAM,MAAM,EAAE,aAAa,CAAC,OAAO,CAA2H,CAAA;AAErK,uGAAuG;AACvG,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,GAAG,YAAY,GAAG,iBAAiB,CAAA;IACzE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED,mDAAmD;AACnD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,kGAAkG;AAClG,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,aAAa,CAAA;IACpD,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,SAAS,CAAC,CAAA;CAC7C;AAED,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACvC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;IACzC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;CAC1C;AAED,eAAO,MAAM,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,CAUlD,CAAA;AAED,wGAAwG;AACxG,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,6GAA6G;IAC7G,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,8GAA8G;IAC9G,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAaD,4EAA4E;AAC5E,eAAO,MAAM,IAAI,YAAmB,eAAe,CAAC,OAAO,WAAW,OAAO,KAAG,OAAO,CAAC,MAAM,CAU7F,CAAA;AAiUD,uGAAuG;AACvG,eAAO,MAAM,MAAM,WAAY,MAAM,KAAG,MAsBvC,CAAA"}