@dloizides/game-e2e 0.0.0-stage → 1.1.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.
package/CHANGELOG.md ADDED
@@ -0,0 +1,33 @@
1
+ # Changelog
2
+
3
+ All notable changes to `@dloizides/game-e2e` are documented here.
4
+
5
+ ## 1.1.0
6
+
7
+ NAV-1 "Every game menu works with arrow keys and controller", phase 1:
8
+
9
+ - `walkMenus()` / `expectMenuWalkable()`: open each screen, walk every focusable control by arrow keys and
10
+ by a stubbed gamepad (breadth-first from the focused control), report unreached controls, a dialog that
11
+ opens without focus inside it, sliders that ignore Left/Right, and Escape / B that does not close a dialog.
12
+ Exemptions take a selector and a printed reason.
13
+ - `stubGamepad()`: a `navigator.getGamepads()` stand-in driven from the test (`PadDriver.press`).
14
+ - `renderWalk()`, `walkFailed()`, `WALK_INPUTS`.
15
+ - Depends on `@dloizides/game-input` ^1.5.1 for the shared focusable and dialog selectors.
16
+
17
+ ## 1.0.0
18
+
19
+ First release. Playwright helpers that Aurora, Surge and Morphe each carried a copy of, unified on the
20
+ strictest behaviour of the three:
21
+
22
+ - `phone()` / `desktop()` / `gameProjects()`: Galaxy S5 and Desktop Chrome device descriptors (touch,
23
+ mobile UA, isMobile on the phone), resized; never a bare viewport.
24
+ - `armVisibleHeight()` / `shrinkVisibleHeight()`: a simulated browser toolbar. `relayoutGlobal` waits for
25
+ every active Phaser scene to re-create and throws when the global is missing.
26
+ - `expectFitTo()`, `expectCanvasHeight()`, `expectCanvasInside()`: game-shell fit assertions with a
27
+ configurable canvas selector.
28
+ - `domControls()`, `overlaps()`, `findOverlaps()`, `findOverlapsWithin()`, `canvasBoxToPage()`.
29
+ - `diffPngs()` / `regionDiff()` / `countDiff()`: exact by default (tolerance 0, sizes must match);
30
+ `ANTI_ALIAS_TOLERANCE` (48) and `width`/`height` opt into Surge's tolerant, scaled comparison.
31
+ - `auditTouchTargets()` + `expectTouchTargets(AcrossRoutes)()`: the 44x44 hit-box gate.
32
+ - `readHorizontalOverflow()` + `expectNoHorizontalOverflow(AcrossRoutes)()`: the no-horizontal-scroll
33
+ gate, measured against the narrower of visualViewport width and clientWidth.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 dloizides
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,116 @@
1
- # Temporary Holding Version
1
+ # @dloizides/game-e2e
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Playwright helpers for the EisaiPollis browser games. Aurora, Surge and Morphe each held a copy of the
4
+ same fixtures; this package is the one copy. Where the three differed, the default is the strictest
5
+ behaviour and the looser one is an option.
6
+
7
+ ```bash
8
+ npm install -D @dloizides/game-e2e
9
+ ```
10
+
11
+ `@playwright/test` (>= 1.57) is a peer dependency.
12
+
13
+ ## Projects: device descriptors, never a bare viewport
14
+
15
+ ```ts
16
+ import { defineConfig } from '@playwright/test';
17
+ import { gameProjects } from '@dloizides/game-e2e';
18
+
19
+ export default defineConfig({ projects: gameProjects() });
20
+ ```
21
+
22
+ `gameProjects()` returns `phone` (Galaxy S5 descriptor: mobile UA, touch, `isMobile`, at 360x640) and
23
+ `desktop` (Desktop Chrome at 1280x720, scale factor 1). A bare `viewport` has no touch flag, no scale
24
+ factor and no mobile UA, so it is not offered. `phone(w, h, dsf?)` and `desktop(w, h, dsf?)` build a
25
+ single context, e.g. `test.use(phone(390, 844))`.
26
+
27
+ ## Visible height and fit
28
+
29
+ ```ts
30
+ await armVisibleHeight(page);
31
+ await page.goto('/');
32
+ await shrinkVisibleHeight(page, 560, { relayoutGlobal: '__auroraGame' });
33
+ await expectFitTo(page, 560);
34
+ await expectCanvasHeight(page, 560, { canvasSelector: '#game-container canvas' });
35
+ ```
36
+
37
+ | Option | Default | Why |
38
+ |---|---|---|
39
+ | `shrinkVisibleHeight` `relayoutGlobal` | none | Aurora's behaviour: wait until every active Phaser scene on `window[relayoutGlobal]` re-creates. Throws when the global is missing (Aurora's copy passed silently). Without it, the call only fires the resize (Surge, Morphe). |
40
+ | `expectCanvasHeight` / `expectCanvasInside` `canvasSelector` | `canvas` | Aurora `#game-container canvas`, Surge `#app canvas`, Morphe `#game-root canvas`. |
41
+ | `expectCanvasHeight` `timeout` | 15 s | Aurora's value; Surge used 10 s. |
42
+
43
+ ## Boxes and overlaps
44
+
45
+ `domControls(page, selector?)` names each control `tag#id:text` or `tag.class:text` (Surge's form; Aurora and
46
+ Morphe dropped the text, which made two unnamed buttons indistinguishable). `findOverlaps(a, b)` and
47
+ `findOverlapsWithin(boxes)` return the overlapping pairs; `canvasBoxToPage(frame, bounds, name, band?)`
48
+ is the game-space to CSS-px transform the scene-target probes use.
49
+
50
+ ## Pixel and region diff
51
+
52
+ ```ts
53
+ const r = await diffPngs(browser, before, after);
54
+ const s = await regionDiff(page.context(), { png: a, region: { x: 0, y: 0, w: 200, h: 80 } }, { png: b, region: null }, { tolerance: ANTI_ALIAS_TOLERANCE });
55
+ ```
56
+
57
+ Returns `{ differing, total, ratio, bbox }`. Default is exact (any RGB change counts) and the two PNGs must
58
+ be the same size, as in Aurora. `tolerance: ANTI_ALIAS_TOLERANCE` (48) and `width`/`height` give Surge's
59
+ tolerant comparison of both images scaled to one size. Alpha is ignored in both.
60
+
61
+ ## Mobile gates
62
+
63
+ - `expectTouchTargets(page, where)` / `auditRoute` + `expectTouchTargetsAcrossRoutes(readings, portal)`:
64
+ every reachable pressable is at least 44x44 (`MIN_TARGET_PX`) and has a role or an accessible name. One
65
+ assertion per portal; a route that reads zero targets fails as a broken probe.
66
+ - `expectNoHorizontalOverflow(page, where)` / `measureHorizontalOverflow` +
67
+ `expectNoHorizontalOverflowAcrossRoutes`: overflow is `scrollWidth` minus the narrower of
68
+ `visualViewport.width` and `clientWidth`. Morphe compared against `clientWidth`, Aurora against the visual
69
+ viewport; the gate fails if either says the page scrolls sideways.
70
+
71
+ ## Migration
72
+
73
+ ### Aurora (`tests/design-ac/fixtures/`)
74
+
75
+ | Local | Export |
76
+ |---|---|
77
+ | `game-fit.ts` `phone`, `desktop` | `phone`, `desktop` (same signature) |
78
+ | `game-fit.ts` `armVisibleHeight` | `armVisibleHeight` |
79
+ | `game-fit.ts` `shrinkVisibleHeight(page, h)` | `shrinkVisibleHeight(page, h, { relayoutGlobal: '__auroraGame' })` |
80
+ | `game-fit.ts` `Box`, `overlaps`, `domControls` | `Box`, `overlaps`, `domControls` (names gain `:text`) |
81
+ | `game-fit.ts` `expectFitTo` | `expectFitTo` |
82
+ | `game-fit.ts` `expectCanvasHeight` | `expectCanvasHeight(page, h, { canvasSelector: '#game-container canvas' })` |
83
+ | `game-fit.ts` `sceneTargets`, `titleTexts` | stay local; may use `canvasBoxToPage` |
84
+ | `pixel-diff.ts` `countDiffPixels(browser, a, b)` | `diffPngs(browser, a, b)` (`differing`, `total`, `bbox` unchanged, plus `ratio`) |
85
+ | `mobile-gates.ts` (all) | same names: `MIN_TARGET_PX`, `auditTouchTargets`, `auditRoute`, `expectTouchTargets`, `expectTouchTargetsAcrossRoutes` |
86
+ | `mobile-overflow.ts` (all) | same names: `readHorizontalOverflow`, `measureHorizontalOverflow`, `expectNoHorizontalOverflow`, `expectNoHorizontalOverflowAcrossRoutes` |
87
+
88
+ ### Surge (`e2e/fixtures/`)
89
+
90
+ | Local | Export |
91
+ |---|---|
92
+ | `game-fit.ts` `phone`, `desktop` | `phone`, `desktop` |
93
+ | `game-fit.ts` `armVisibleHeight`, `shrinkVisibleHeight` | same names |
94
+ | `game-fit.ts` `Box`, `overlaps`, `domControls`, `expectFitTo` | same names |
95
+ | `game-fit.ts` `expectCanvasHeight` | `expectCanvasHeight(page, h, { canvasSelector: '#app canvas', timeout: 10_000 })` |
96
+ | `game-fit.ts` `horizontalOverflow` | `horizontalOverflowPx` |
97
+ | `game-fit.ts` `openTitle` | stays local |
98
+ | `pixelDiff.ts` `CHANNEL_TOLERANCE` | `ANTI_ALIAS_TOLERANCE` |
99
+ | `pixelDiff.ts` `diffPngs(page, a, b, w, h)` | `(await diffPngs(page.context(), a, b, { width: w, height: h, tolerance: ANTI_ALIAS_TOLERANCE })).ratio` |
100
+ | `regionDiff.ts` `regionDiff(page, a, ra, b, rb, w, h)` | `(await regionDiff(page.context(), { png: a, region: ra }, { png: b, region: rb }, { width: w, height: h, tolerance: ANTI_ALIAS_TOLERANCE })).ratio` |
101
+ | `regionDiff.ts` `Region` | `Region` |
102
+
103
+ ### Morphe (`e2e/fixtures/`)
104
+
105
+ | Local | Export |
106
+ |---|---|
107
+ | `game-fit.ts` `phone`, `desktop` | `phone`, `desktop` |
108
+ | `game-fit.ts` `armVisibleHeight`, `shrinkVisibleHeight` | same names |
109
+ | `game-fit.ts` `Box`, `overlaps`, `domControls`, `expectFitTo` | same names |
110
+ | `game-fit.ts` `expectCanvasInside` | `expectCanvasInside(page, h, { canvasSelector: '#game-root canvas' })` |
111
+ | `game-fit.ts` `expectNoHorizontalScroll(page, label)` | `expectNoHorizontalOverflow(page, label)` (stricter denominator) |
112
+ | `game-fit.ts` `openGame`, `gameTargets` | stay local; `gameTargets` may use `canvasBoxToPage` |
113
+
114
+ ## Publish
115
+
116
+ `./publish.ps1 -Bump patch|minor|major` (guarded by `publish-guard.ps1`).
@@ -0,0 +1,258 @@
1
+ import { Page, BrowserContextOptions } from '@playwright/test';
2
+
3
+ interface Box {
4
+ name: string;
5
+ left: number;
6
+ top: number;
7
+ right: number;
8
+ bottom: number;
9
+ }
10
+ interface Region {
11
+ readonly x: number;
12
+ readonly y: number;
13
+ readonly w: number;
14
+ readonly h: number;
15
+ }
16
+ interface Rect {
17
+ x: number;
18
+ y: number;
19
+ width: number;
20
+ height: number;
21
+ }
22
+ /** Anything that opens a scratch page: a `Browser` or a `BrowserContext` (e.g. `page.context()`). */
23
+ interface PageFactory {
24
+ newPage(): Promise<Page>;
25
+ }
26
+ /** The outcome of a whole-portal gate: zero problems passes, the message carries the per-route breakdown. */
27
+ interface GateSummary {
28
+ problems: number;
29
+ message: string;
30
+ }
31
+
32
+ interface CanvasFrame {
33
+ left: number;
34
+ top: number;
35
+ width: number;
36
+ logicalWidth: number;
37
+ }
38
+ interface ControlIdentity {
39
+ tag: string;
40
+ id: string;
41
+ className: string;
42
+ text: string;
43
+ }
44
+ type Band = readonly [number, number];
45
+ declare function overlaps(a: Box, b: Box): boolean;
46
+ /** Every overlapping (a, b) pair across two lists; an element never overlaps itself. */
47
+ declare function findOverlaps(a: readonly Box[], b: readonly Box[]): Array<[Box, Box]>;
48
+ /** Every overlapping pair inside one list, each pair reported once. */
49
+ declare function findOverlapsWithin(boxes: readonly Box[]): Array<[Box, Box]>;
50
+ /** Maps a game-space rect onto the page in CSS px, clipped to a scroll band; null when nothing is left. */
51
+ declare function canvasBoxToPage(frame: CanvasFrame, bounds: Rect, name: string, band?: Band): Box | null;
52
+ declare function controlName(c: ControlIdentity): string;
53
+
54
+ interface Size {
55
+ width: number;
56
+ height: number;
57
+ }
58
+ interface GameProject {
59
+ name: string;
60
+ use: BrowserContextOptions;
61
+ }
62
+ interface GameProjectsOptions {
63
+ phone?: Size;
64
+ desktop?: Size;
65
+ phoneName?: string;
66
+ desktopName?: string;
67
+ }
68
+ declare const PHONE_DEVICE = "Galaxy S5";
69
+ declare const DESKTOP_DEVICE = "Desktop Chrome";
70
+ declare const PHONE_SIZE: Size;
71
+ declare const DESKTOP_SIZE: Size;
72
+ /** A Playwright device descriptor without `defaultBrowserType`, so it can sit inside any project's `use`. */
73
+ declare function deviceDescriptor(name: string): BrowserContextOptions;
74
+ /** A touch phone (Galaxy S5 descriptor: mobile UA, touch, isMobile) resized to width x height. */
75
+ declare function phone(width?: number, height?: number, deviceScaleFactor?: number): BrowserContextOptions;
76
+ /** A Desktop Chrome descriptor resized to width x height, scale factor 1 unless given. */
77
+ declare function desktop(width?: number, height?: number, deviceScaleFactor?: number): BrowserContextOptions;
78
+ /** The phone + desktop Playwright projects every game runs its specs under. */
79
+ declare function gameProjects(options?: GameProjectsOptions): GameProject[];
80
+
81
+ interface ShrinkOptions {
82
+ relayoutGlobal?: string;
83
+ timeout?: number;
84
+ }
85
+ declare const RELAYOUT_TIMEOUT_MS = 15000;
86
+ /** Replaces visualViewport.height before page scripts run: reads window.__gfVisibleHeight, else innerHeight. */
87
+ declare function armVisibleHeight(page: Page): Promise<void>;
88
+ /** Drops the visible height and fires visualViewport resize; with `relayoutGlobal`, waits for every active Phaser scene to re-create. */
89
+ declare function shrinkVisibleHeight(page: Page, height: number, options?: ShrinkOptions): Promise<void>;
90
+
91
+ interface FitOptions {
92
+ cssVar?: string;
93
+ timeout?: number;
94
+ }
95
+ interface CanvasOptions {
96
+ canvasSelector?: string;
97
+ timeout?: number;
98
+ }
99
+ declare const GAME_SHELL_HEIGHT_VAR = "--gs-vh";
100
+ declare const DEFAULT_CANVAS_SELECTOR = "canvas";
101
+ declare const FIT_TIMEOUT_MS = 10000;
102
+ declare const CANVAS_TIMEOUT_MS = 15000;
103
+ /** Waits until the game-shell height variable on :root equals `height` px. */
104
+ declare function expectFitTo(page: Page, height: number, options?: FitOptions): Promise<void>;
105
+ /** Waits for the canvas to follow its container to exactly `height` CSS px. */
106
+ declare function expectCanvasHeight(page: Page, height: number, options?: CanvasOptions): Promise<void>;
107
+ /** Waits until the canvas bottom sits inside the visible `height` (a FIT-scaled canvas may be shorter). */
108
+ declare function expectCanvasInside(page: Page, height: number, options?: CanvasOptions): Promise<void>;
109
+
110
+ declare const CONTROL_SELECTOR = "button, a[href], [role=\"button\"]";
111
+ /** Visible, interactive DOM controls as CSS-px boxes, named tag#id or tag.class plus their text. */
112
+ declare function domControls(page: Page, selector?: string): Promise<Box[]>;
113
+
114
+ declare const EXACT = 0;
115
+ declare const ANTI_ALIAS_TOLERANCE = 48;
116
+ interface DiffResult {
117
+ differing: number;
118
+ total: number;
119
+ ratio: number;
120
+ bbox: string;
121
+ }
122
+ /** Counts RGBA pixels whose largest RGB channel delta exceeds `tolerance` (0 = any change), with their bounding box. */
123
+ declare function countDiff(a: ArrayLike<number>, b: ArrayLike<number>, width: number, tolerance?: number): DiffResult;
124
+
125
+ interface DiffOptions {
126
+ tolerance?: number;
127
+ width?: number;
128
+ height?: number;
129
+ regionA?: Region | null;
130
+ regionB?: Region | null;
131
+ }
132
+ interface RegionInput {
133
+ png: Buffer;
134
+ region: Region | null;
135
+ }
136
+ /** Decodes two PNGs in a scratch page and counts differing pixels; exact and same-size unless options say otherwise. */
137
+ declare function diffPngs(factory: PageFactory, a: Buffer, b: Buffer, options?: DiffOptions): Promise<DiffResult>;
138
+ /** Diffs a region of PNG a against a region of PNG b (null = whole image), both drawn at the same size. */
139
+ declare function regionDiff(factory: PageFactory, a: RegionInput, b: RegionInput, options?: Omit<DiffOptions, 'regionA' | 'regionB'>): Promise<DiffResult>;
140
+
141
+ declare const MIN_TARGET_PX = 44;
142
+ declare const MAX_REPORTED = 12;
143
+ interface TargetFinding {
144
+ idx: number;
145
+ selector: string;
146
+ width: number;
147
+ height: number;
148
+ reason: string;
149
+ name: string;
150
+ }
151
+ interface TargetProbeFunnel {
152
+ raw: number;
153
+ afterWrapper: number;
154
+ kept: number;
155
+ }
156
+ /** One route's touch-target reading; `probe` makes a zero attributable (raw -> afterWrapper -> kept -> total). */
157
+ interface TargetAudit {
158
+ total: number;
159
+ undersized: TargetFinding[];
160
+ unlabelled: TargetFinding[];
161
+ probe: TargetProbeFunnel;
162
+ }
163
+ /** One route's reading. `total === 0` is a broken probe for that route, never a clean route. */
164
+ interface RouteAudit {
165
+ route: string;
166
+ audit: TargetAudit;
167
+ }
168
+ declare function renderFindings(findings: readonly TargetFinding[], alsoIn: ReadonlySet<number>, alsoLabel: string): string;
169
+ declare function renderRouteAudit({ route, audit }: RouteAudit, minPx: number): string;
170
+ declare function routeProblems({ audit }: RouteAudit): number;
171
+ /** Folds every route and both claims (size, label) into one tally; no routes at all is itself a problem. */
172
+ declare function summariseTouchTargets(readings: readonly RouteAudit[], portal: string, minPx?: number): GateSummary;
173
+
174
+ /** Measures every reachable pressable on the page (role OR handler OR own-origin pointer cursor, outermost wins) against `minPx`. */
175
+ declare function auditTouchTargets(page: Page, minPx?: number): Promise<TargetAudit>;
176
+ /** Measures one route and asserts nothing, so a route with findings cannot hide the routes after it. */
177
+ declare function auditRoute(page: Page, route: string, minPx?: number): Promise<RouteAudit>;
178
+ /** ONE assertion per portal over every route and both claims (undersized, unlabelled); a zero-target route fails. */
179
+ declare function expectTouchTargetsAcrossRoutes(readings: readonly RouteAudit[], portal: string, minPx?: number): void;
180
+ /** Single-route convenience over `expectTouchTargetsAcrossRoutes`. */
181
+ declare function expectTouchTargets(page: Page, where: string, minPx?: number): Promise<TargetAudit>;
182
+
183
+ interface OverflowMetrics {
184
+ scrollWidth: number;
185
+ visualViewportWidth: number;
186
+ innerWidth: number;
187
+ clientWidth: number;
188
+ }
189
+ /** `layoutViewportDrift` (innerWidth above visualViewport) is the signature of a widened layout viewport. */
190
+ interface OverflowReading extends OverflowMetrics {
191
+ overflowPx: number;
192
+ layoutViewportDrift: number;
193
+ }
194
+ interface RouteOverflow {
195
+ route: string;
196
+ reading: OverflowReading;
197
+ }
198
+ /** Overflow against the NARROWER of visualViewport width and clientWidth, never innerWidth (which widens with the defect). */
199
+ declare function toOverflowReading(m: OverflowMetrics): OverflowReading;
200
+ declare function renderOverflow({ route, reading: r }: RouteOverflow): string;
201
+ /** Folds every route into one tally of routes that scroll sideways; no routes at all is itself a problem. */
202
+ declare function summariseOverflow(readings: readonly RouteOverflow[], portal: string): GateSummary;
203
+
204
+ declare function readHorizontalOverflow(page: Page): Promise<OverflowReading>;
205
+ /** Measures one route and asserts nothing. */
206
+ declare function measureHorizontalOverflow(page: Page, route: string): Promise<RouteOverflow>;
207
+ /** Pixels the document scrolls sideways past the visible width (<= 0 means no horizontal scroll). */
208
+ declare function horizontalOverflowPx(page: Page): Promise<number>;
209
+ /** ONE assertion per portal over every route, so the first overflowing route cannot hide the rest. */
210
+ declare function expectNoHorizontalOverflowAcrossRoutes(readings: readonly RouteOverflow[], portal: string): void;
211
+ /** Single-route convenience over `expectNoHorizontalOverflowAcrossRoutes`. */
212
+ declare function expectNoHorizontalOverflow(page: Page, where: string): Promise<OverflowReading>;
213
+
214
+ declare const WALK_INPUTS: {
215
+ readonly keys: "keys";
216
+ readonly pad: "pad";
217
+ };
218
+ type WalkInput = (typeof WALK_INPUTS)[keyof typeof WALK_INPUTS];
219
+ interface WalkResult {
220
+ screen: string;
221
+ via: WalkInput;
222
+ reached: number;
223
+ total: number;
224
+ unreached: string[];
225
+ problems: string[];
226
+ exempt: string[];
227
+ }
228
+ declare const walkFailed: (r: WalkResult) => boolean;
229
+ /** One block per screen and input: reached/total, then every unreached control, problem and exemption. */
230
+ declare function renderWalk(results: readonly WalkResult[]): string;
231
+
232
+ interface WalkScreen {
233
+ name: string;
234
+ /** Opens the screen from a fresh page (clicks, a URL, a test hook). */
235
+ open: (page: Page) => Promise<void>;
236
+ /** Controls deliberately not walkable, each with a reason (printed in the report). */
237
+ exempt?: ReadonlyArray<{
238
+ selector: string;
239
+ reason: string;
240
+ }>;
241
+ }
242
+ interface WalkOptions {
243
+ via?: readonly WalkInput[];
244
+ }
245
+ /** Walks every screen by arrow keys and by a stubbed pad (default both) and returns one result per screen and input. */
246
+ declare function walkMenus(page: Page, screens: readonly WalkScreen[], options?: WalkOptions): Promise<WalkResult[]>;
247
+ /** NAV-1 gate: throws, listing every unreached control and problem, unless every screen walks by keys and pad. */
248
+ declare function expectMenuWalkable(page: Page, screens: readonly WalkScreen[], options?: WalkOptions): Promise<void>;
249
+
250
+ interface PadDriver {
251
+ press(button: number): Promise<void>;
252
+ hold(axis: number, value: number): Promise<void>;
253
+ }
254
+ declare const STUB_FRAMES = 3;
255
+ /** Replaces navigator.getGamepads with one standard pad (call before the page loads); returns its driver. */
256
+ declare function stubGamepad(page: Page): Promise<PadDriver>;
257
+
258
+ export { ANTI_ALIAS_TOLERANCE, type Band, type Box, CANVAS_TIMEOUT_MS, CONTROL_SELECTOR, type CanvasFrame, type CanvasOptions, type ControlIdentity, DEFAULT_CANVAS_SELECTOR, DESKTOP_DEVICE, DESKTOP_SIZE, type DiffOptions, type DiffResult, EXACT, FIT_TIMEOUT_MS, type FitOptions, GAME_SHELL_HEIGHT_VAR, type GameProject, type GameProjectsOptions, type GateSummary, MAX_REPORTED, MIN_TARGET_PX, type OverflowMetrics, type OverflowReading, PHONE_DEVICE, PHONE_SIZE, type PadDriver, type PageFactory, RELAYOUT_TIMEOUT_MS, type Rect, type Region, type RegionInput, type RouteAudit, type RouteOverflow, STUB_FRAMES, type ShrinkOptions, type Size, type TargetAudit, type TargetFinding, type TargetProbeFunnel, WALK_INPUTS, type WalkInput, type WalkOptions, type WalkResult, type WalkScreen, armVisibleHeight, auditRoute, auditTouchTargets, canvasBoxToPage, controlName, countDiff, desktop, deviceDescriptor, diffPngs, domControls, expectCanvasHeight, expectCanvasInside, expectFitTo, expectMenuWalkable, expectNoHorizontalOverflow, expectNoHorizontalOverflowAcrossRoutes, expectTouchTargets, expectTouchTargetsAcrossRoutes, findOverlaps, findOverlapsWithin, gameProjects, horizontalOverflowPx, measureHorizontalOverflow, overlaps, phone, readHorizontalOverflow, regionDiff, renderFindings, renderOverflow, renderRouteAudit, renderWalk, routeProblems, shrinkVisibleHeight, stubGamepad, summariseOverflow, summariseTouchTargets, toOverflowReading, walkFailed, walkMenus };