@dloizides/game-e2e 1.4.1 → 1.6.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 CHANGED
@@ -2,6 +2,23 @@
2
2
 
3
3
  All notable changes to `@dloizides/game-e2e` are documented here.
4
4
 
5
+ ## 1.6.0
6
+
7
+ GAME-INPUT-PROMPTS-1 "Every action bound, with device labels":
8
+
9
+ - `expectActionsBound(page, bindings, options?)`, `measureActionBinding`, `readActionElements`, `toActionReading`,
10
+ `summariseActionBinding`, `actionBindingFindings`: fails when a visible clickable has no `data-gi-action`, a tagged
11
+ action has no key or pad binding, a visible `data-gi-prompt` shows a label other than the current binding, or zero
12
+ elements were read. Bindings are an input (`ActionBindings`), so the gate does not depend on a game-input release.
13
+
14
+ ## 1.5.0
15
+
16
+ TEXT-FIT-1 "UI text never overflows its box at 360x640 or desktop, in every state":
17
+
18
+ - `expectTextFits(page, selector?, options?)`, `measureTextFit`, `readTextBoxes`, `summariseTextFit`, `textFitFindings`:
19
+ fails when visible text is wider/taller than its box or spills its parent, across named UI states. Trigger: Surge's
20
+ "Daily run" button with the "Completed today" badge ran past the button edge at 360x640 and 1280.
21
+
5
22
  ## 1.4.0
6
23
 
7
24
  GAME-E2E-PRESS-1 "Faster pad presses in game-e2e walks":
package/README.md CHANGED
@@ -1,116 +1,122 @@
1
- # @dloizides/game-e2e
2
-
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`).
1
+ # @dloizides/game-e2e
2
+
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
+ - `expectTextFits(page, selector?, { states?, where?, tolerancePx? })` / `measureTextFit` / `readTextBoxes`:
72
+ TEXT-FIT-1 "UI text never overflows its box". Every visible element under `selector` (default `body *`)
73
+ that holds its own text fails when its `scrollWidth`/`scrollHeight` exceeds its box, or when its box
74
+ spills the block it sits in (scroll containers excepted). `states` walks named UI states (`enter(page)`)
75
+ and reports all of them in one assertion; a state that matched no text is a BLIND failure.
76
+
77
+ ## Migration
78
+
79
+ ### Aurora (`tests/design-ac/fixtures/`)
80
+
81
+ | Local | Export |
82
+ |---|---|
83
+ | `game-fit.ts` `phone`, `desktop` | `phone`, `desktop` (same signature) |
84
+ | `game-fit.ts` `armVisibleHeight` | `armVisibleHeight` |
85
+ | `game-fit.ts` `shrinkVisibleHeight(page, h)` | `shrinkVisibleHeight(page, h, { relayoutGlobal: '__auroraGame' })` |
86
+ | `game-fit.ts` `Box`, `overlaps`, `domControls` | `Box`, `overlaps`, `domControls` (names gain `:text`) |
87
+ | `game-fit.ts` `expectFitTo` | `expectFitTo` |
88
+ | `game-fit.ts` `expectCanvasHeight` | `expectCanvasHeight(page, h, { canvasSelector: '#game-container canvas' })` |
89
+ | `game-fit.ts` `sceneTargets`, `titleTexts` | stay local; may use `canvasBoxToPage` |
90
+ | `pixel-diff.ts` `countDiffPixels(browser, a, b)` | `diffPngs(browser, a, b)` (`differing`, `total`, `bbox` unchanged, plus `ratio`) |
91
+ | `mobile-gates.ts` (all) | same names: `MIN_TARGET_PX`, `auditTouchTargets`, `auditRoute`, `expectTouchTargets`, `expectTouchTargetsAcrossRoutes` |
92
+ | `mobile-overflow.ts` (all) | same names: `readHorizontalOverflow`, `measureHorizontalOverflow`, `expectNoHorizontalOverflow`, `expectNoHorizontalOverflowAcrossRoutes` |
93
+
94
+ ### Surge (`e2e/fixtures/`)
95
+
96
+ | Local | Export |
97
+ |---|---|
98
+ | `game-fit.ts` `phone`, `desktop` | `phone`, `desktop` |
99
+ | `game-fit.ts` `armVisibleHeight`, `shrinkVisibleHeight` | same names |
100
+ | `game-fit.ts` `Box`, `overlaps`, `domControls`, `expectFitTo` | same names |
101
+ | `game-fit.ts` `expectCanvasHeight` | `expectCanvasHeight(page, h, { canvasSelector: '#app canvas', timeout: 10_000 })` |
102
+ | `game-fit.ts` `horizontalOverflow` | `horizontalOverflowPx` |
103
+ | `game-fit.ts` `openTitle` | stays local |
104
+ | `pixelDiff.ts` `CHANNEL_TOLERANCE` | `ANTI_ALIAS_TOLERANCE` |
105
+ | `pixelDiff.ts` `diffPngs(page, a, b, w, h)` | `(await diffPngs(page.context(), a, b, { width: w, height: h, tolerance: ANTI_ALIAS_TOLERANCE })).ratio` |
106
+ | `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` |
107
+ | `regionDiff.ts` `Region` | `Region` |
108
+
109
+ ### Morphe (`e2e/fixtures/`)
110
+
111
+ | Local | Export |
112
+ |---|---|
113
+ | `game-fit.ts` `phone`, `desktop` | `phone`, `desktop` |
114
+ | `game-fit.ts` `armVisibleHeight`, `shrinkVisibleHeight` | same names |
115
+ | `game-fit.ts` `Box`, `overlaps`, `domControls`, `expectFitTo` | same names |
116
+ | `game-fit.ts` `expectCanvasInside` | `expectCanvasInside(page, h, { canvasSelector: '#game-root canvas' })` |
117
+ | `game-fit.ts` `expectNoHorizontalScroll(page, label)` | `expectNoHorizontalOverflow(page, label)` (stricter denominator) |
118
+ | `game-fit.ts` `openGame`, `gameTargets` | stay local; `gameTargets` may use `canvasBoxToPage` |
119
+
120
+ ## Publish
121
+
122
+ `./publish.ps1 -Bump patch|minor|major` (guarded by `publish-guard.ps1`).
package/dist/index.d.mts CHANGED
@@ -284,4 +284,107 @@ declare function walkHookMenus(page: Page, opts: HookWalkOptions): Promise<WalkR
284
284
  /** NAV-1 gate for canvas menus: throws, naming every unreached item and problem, unless all screens walk. */
285
285
  declare function expectHookMenuWalkable(page: Page, opts: HookWalkOptions): Promise<void>;
286
286
 
287
- 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, HOOK_WALK_SIZES, type HookScreen, type HookWalkOptions, 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, expectHookMenuWalkable, 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, walkHookMenus, walkMenus };
287
+ declare const TEXT_FIT_TOLERANCE_PX = 1;
288
+ /** One visible text element: its own box and content size, and the box of the block it sits in. */
289
+ interface TextBoxReading {
290
+ name: string;
291
+ text: string;
292
+ inline: boolean;
293
+ clientWidth: number;
294
+ clientHeight: number;
295
+ scrollWidth: number;
296
+ scrollHeight: number;
297
+ left: number;
298
+ top: number;
299
+ right: number;
300
+ bottom: number;
301
+ parentLeft: number;
302
+ parentTop: number;
303
+ parentRight: number;
304
+ parentBottom: number;
305
+ }
306
+ interface TextFitFinding {
307
+ name: string;
308
+ text: string;
309
+ why: string;
310
+ px: number;
311
+ }
312
+ interface StateTextFit {
313
+ state: string;
314
+ readings: readonly TextBoxReading[];
315
+ }
316
+ /** Every way one reading breaks the rule: content larger than its own box, or the box outside its parent's. */
317
+ declare function textFitFindings(r: TextBoxReading, tol?: number): TextFitFinding[];
318
+ /** Folds every UI state into one tally; a state that measured no text at all is a blind probe and counts as a problem. */
319
+ declare function summariseTextFit(states: readonly StateTextFit[], where: string, tol?: number): GateSummary;
320
+
321
+ declare const TEXT_FIT_SELECTOR = "body *";
322
+ /** A UI state to measure: `enter` puts the page into it (seed a save, open a screen, swap a label). */
323
+ interface TextFitState {
324
+ name: string;
325
+ enter: (page: Page) => Promise<void>;
326
+ }
327
+ interface TextFitOptions {
328
+ states?: readonly TextFitState[];
329
+ where?: string;
330
+ tolerancePx?: number;
331
+ }
332
+ /** Reads every visible element under `selector` that holds its own text, with the box of the block it sits in. */
333
+ declare function readTextBoxes(page: Page, selector?: string): Promise<TextBoxReading[]>;
334
+ /** Measures every given state (or the current page) and returns the per-state readings; asserts nothing. */
335
+ declare function measureTextFit(page: Page, selector?: string, states?: readonly TextFitState[]): Promise<StateTextFit[]>;
336
+ /** Fails when any visible text under `selector` is larger than its box or spills its parent, in any given UI state. */
337
+ declare function expectTextFits(page: Page, selector?: string, options?: TextFitOptions): Promise<StateTextFit[]>;
338
+
339
+ /** One clickable in-play element: its tagged action, its bindings, and the prompt it shows. */
340
+ interface ActionReading {
341
+ name: string;
342
+ action: string | null;
343
+ hasPointerHandler: boolean;
344
+ key: string | null;
345
+ pad: number | null;
346
+ promptText: string | null;
347
+ expectedPromptText: string | null;
348
+ }
349
+ interface ActionBindingFinding {
350
+ name: string;
351
+ why: string;
352
+ }
353
+ /** Every way one element breaks "every action bound": untagged, no key, no pad button, stale prompt. */
354
+ declare function actionBindingFindings(r: ActionReading): ActionBindingFinding[];
355
+ /** Folds every reading into one tally; zero readings is a blind probe and counts as a problem. */
356
+ declare function summariseActionBinding(readings: readonly ActionReading[], where: string): GateSummary;
357
+
358
+ declare const ACTION_ATTR = "data-gi-action";
359
+ declare const PROMPT_ATTR = "data-gi-prompt";
360
+ declare const POINTER_SELECTOR = "button, a[href], [role=\"button\"], [onclick]";
361
+ declare const ACTION_ROOT_SELECTOR = "body";
362
+ /** One action's current key, pad button and the prompt label the active device should show. */
363
+ interface ActionBinding {
364
+ key: string | null;
365
+ pad: number | null;
366
+ prompt?: string | null;
367
+ }
368
+ type ActionBindings = Readonly<Record<string, ActionBinding | undefined>>;
369
+ /** What the page shows for one element, before it is joined with the bindings. */
370
+ interface ActionElement {
371
+ name: string;
372
+ action: string | null;
373
+ hasPointerHandler: boolean;
374
+ promptText: string | null;
375
+ }
376
+ interface ActionBindingOptions {
377
+ root?: string;
378
+ pointerSelector?: string;
379
+ where?: string;
380
+ }
381
+ /** Joins one element with its action's binding; an action missing from `bindings` reads as unbound. */
382
+ declare function toActionReading(el: ActionElement, bindings: ActionBindings): ActionReading;
383
+ /** Reads every visible clickable or `data-gi-action` element under `root`, with its visible prompt text. */
384
+ declare function readActionElements(page: Page, root?: string, pointerSelector?: string): Promise<ActionElement[]>;
385
+ /** Reads the page and joins each element with `bindings`; asserts nothing. */
386
+ declare function measureActionBinding(page: Page, bindings: ActionBindings, options?: ActionBindingOptions): Promise<ActionReading[]>;
387
+ /** Fails on an untagged clickable, an action without key or pad, a stale prompt, or zero elements read. */
388
+ declare function expectActionsBound(page: Page, bindings: ActionBindings, options?: ActionBindingOptions): Promise<ActionReading[]>;
389
+
390
+ export { ACTION_ATTR, ACTION_ROOT_SELECTOR, ANTI_ALIAS_TOLERANCE, type ActionBinding, type ActionBindingFinding, type ActionBindingOptions, type ActionBindings, type ActionElement, type ActionReading, 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, HOOK_WALK_SIZES, type HookScreen, type HookWalkOptions, MAX_REPORTED, MIN_TARGET_PX, type OverflowMetrics, type OverflowReading, PHONE_DEVICE, PHONE_SIZE, POINTER_SELECTOR, PROMPT_ATTR, type PadDriver, type PageFactory, RELAYOUT_TIMEOUT_MS, type Rect, type Region, type RegionInput, type RouteAudit, type RouteOverflow, STUB_FRAMES, type ShrinkOptions, type Size, type StateTextFit, TEXT_FIT_SELECTOR, TEXT_FIT_TOLERANCE_PX, type TargetAudit, type TargetFinding, type TargetProbeFunnel, type TextBoxReading, type TextFitFinding, type TextFitOptions, type TextFitState, WALK_INPUTS, type WalkInput, type WalkOptions, type WalkResult, type WalkScreen, actionBindingFindings, armVisibleHeight, auditRoute, auditTouchTargets, canvasBoxToPage, controlName, countDiff, desktop, deviceDescriptor, diffPngs, domControls, expectActionsBound, expectCanvasHeight, expectCanvasInside, expectFitTo, expectHookMenuWalkable, expectMenuWalkable, expectNoHorizontalOverflow, expectNoHorizontalOverflowAcrossRoutes, expectTextFits, expectTouchTargets, expectTouchTargetsAcrossRoutes, findOverlaps, findOverlapsWithin, gameProjects, horizontalOverflowPx, measureActionBinding, measureHorizontalOverflow, measureTextFit, overlaps, phone, readActionElements, readHorizontalOverflow, readTextBoxes, regionDiff, renderFindings, renderOverflow, renderRouteAudit, renderWalk, routeProblems, shrinkVisibleHeight, stubGamepad, summariseActionBinding, summariseOverflow, summariseTextFit, summariseTouchTargets, textFitFindings, toActionReading, toOverflowReading, walkFailed, walkHookMenus, walkMenus };
package/dist/index.d.ts CHANGED
@@ -284,4 +284,107 @@ declare function walkHookMenus(page: Page, opts: HookWalkOptions): Promise<WalkR
284
284
  /** NAV-1 gate for canvas menus: throws, naming every unreached item and problem, unless all screens walk. */
285
285
  declare function expectHookMenuWalkable(page: Page, opts: HookWalkOptions): Promise<void>;
286
286
 
287
- 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, HOOK_WALK_SIZES, type HookScreen, type HookWalkOptions, 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, expectHookMenuWalkable, 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, walkHookMenus, walkMenus };
287
+ declare const TEXT_FIT_TOLERANCE_PX = 1;
288
+ /** One visible text element: its own box and content size, and the box of the block it sits in. */
289
+ interface TextBoxReading {
290
+ name: string;
291
+ text: string;
292
+ inline: boolean;
293
+ clientWidth: number;
294
+ clientHeight: number;
295
+ scrollWidth: number;
296
+ scrollHeight: number;
297
+ left: number;
298
+ top: number;
299
+ right: number;
300
+ bottom: number;
301
+ parentLeft: number;
302
+ parentTop: number;
303
+ parentRight: number;
304
+ parentBottom: number;
305
+ }
306
+ interface TextFitFinding {
307
+ name: string;
308
+ text: string;
309
+ why: string;
310
+ px: number;
311
+ }
312
+ interface StateTextFit {
313
+ state: string;
314
+ readings: readonly TextBoxReading[];
315
+ }
316
+ /** Every way one reading breaks the rule: content larger than its own box, or the box outside its parent's. */
317
+ declare function textFitFindings(r: TextBoxReading, tol?: number): TextFitFinding[];
318
+ /** Folds every UI state into one tally; a state that measured no text at all is a blind probe and counts as a problem. */
319
+ declare function summariseTextFit(states: readonly StateTextFit[], where: string, tol?: number): GateSummary;
320
+
321
+ declare const TEXT_FIT_SELECTOR = "body *";
322
+ /** A UI state to measure: `enter` puts the page into it (seed a save, open a screen, swap a label). */
323
+ interface TextFitState {
324
+ name: string;
325
+ enter: (page: Page) => Promise<void>;
326
+ }
327
+ interface TextFitOptions {
328
+ states?: readonly TextFitState[];
329
+ where?: string;
330
+ tolerancePx?: number;
331
+ }
332
+ /** Reads every visible element under `selector` that holds its own text, with the box of the block it sits in. */
333
+ declare function readTextBoxes(page: Page, selector?: string): Promise<TextBoxReading[]>;
334
+ /** Measures every given state (or the current page) and returns the per-state readings; asserts nothing. */
335
+ declare function measureTextFit(page: Page, selector?: string, states?: readonly TextFitState[]): Promise<StateTextFit[]>;
336
+ /** Fails when any visible text under `selector` is larger than its box or spills its parent, in any given UI state. */
337
+ declare function expectTextFits(page: Page, selector?: string, options?: TextFitOptions): Promise<StateTextFit[]>;
338
+
339
+ /** One clickable in-play element: its tagged action, its bindings, and the prompt it shows. */
340
+ interface ActionReading {
341
+ name: string;
342
+ action: string | null;
343
+ hasPointerHandler: boolean;
344
+ key: string | null;
345
+ pad: number | null;
346
+ promptText: string | null;
347
+ expectedPromptText: string | null;
348
+ }
349
+ interface ActionBindingFinding {
350
+ name: string;
351
+ why: string;
352
+ }
353
+ /** Every way one element breaks "every action bound": untagged, no key, no pad button, stale prompt. */
354
+ declare function actionBindingFindings(r: ActionReading): ActionBindingFinding[];
355
+ /** Folds every reading into one tally; zero readings is a blind probe and counts as a problem. */
356
+ declare function summariseActionBinding(readings: readonly ActionReading[], where: string): GateSummary;
357
+
358
+ declare const ACTION_ATTR = "data-gi-action";
359
+ declare const PROMPT_ATTR = "data-gi-prompt";
360
+ declare const POINTER_SELECTOR = "button, a[href], [role=\"button\"], [onclick]";
361
+ declare const ACTION_ROOT_SELECTOR = "body";
362
+ /** One action's current key, pad button and the prompt label the active device should show. */
363
+ interface ActionBinding {
364
+ key: string | null;
365
+ pad: number | null;
366
+ prompt?: string | null;
367
+ }
368
+ type ActionBindings = Readonly<Record<string, ActionBinding | undefined>>;
369
+ /** What the page shows for one element, before it is joined with the bindings. */
370
+ interface ActionElement {
371
+ name: string;
372
+ action: string | null;
373
+ hasPointerHandler: boolean;
374
+ promptText: string | null;
375
+ }
376
+ interface ActionBindingOptions {
377
+ root?: string;
378
+ pointerSelector?: string;
379
+ where?: string;
380
+ }
381
+ /** Joins one element with its action's binding; an action missing from `bindings` reads as unbound. */
382
+ declare function toActionReading(el: ActionElement, bindings: ActionBindings): ActionReading;
383
+ /** Reads every visible clickable or `data-gi-action` element under `root`, with its visible prompt text. */
384
+ declare function readActionElements(page: Page, root?: string, pointerSelector?: string): Promise<ActionElement[]>;
385
+ /** Reads the page and joins each element with `bindings`; asserts nothing. */
386
+ declare function measureActionBinding(page: Page, bindings: ActionBindings, options?: ActionBindingOptions): Promise<ActionReading[]>;
387
+ /** Fails on an untagged clickable, an action without key or pad, a stale prompt, or zero elements read. */
388
+ declare function expectActionsBound(page: Page, bindings: ActionBindings, options?: ActionBindingOptions): Promise<ActionReading[]>;
389
+
390
+ export { ACTION_ATTR, ACTION_ROOT_SELECTOR, ANTI_ALIAS_TOLERANCE, type ActionBinding, type ActionBindingFinding, type ActionBindingOptions, type ActionBindings, type ActionElement, type ActionReading, 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, HOOK_WALK_SIZES, type HookScreen, type HookWalkOptions, MAX_REPORTED, MIN_TARGET_PX, type OverflowMetrics, type OverflowReading, PHONE_DEVICE, PHONE_SIZE, POINTER_SELECTOR, PROMPT_ATTR, type PadDriver, type PageFactory, RELAYOUT_TIMEOUT_MS, type Rect, type Region, type RegionInput, type RouteAudit, type RouteOverflow, STUB_FRAMES, type ShrinkOptions, type Size, type StateTextFit, TEXT_FIT_SELECTOR, TEXT_FIT_TOLERANCE_PX, type TargetAudit, type TargetFinding, type TargetProbeFunnel, type TextBoxReading, type TextFitFinding, type TextFitOptions, type TextFitState, WALK_INPUTS, type WalkInput, type WalkOptions, type WalkResult, type WalkScreen, actionBindingFindings, armVisibleHeight, auditRoute, auditTouchTargets, canvasBoxToPage, controlName, countDiff, desktop, deviceDescriptor, diffPngs, domControls, expectActionsBound, expectCanvasHeight, expectCanvasInside, expectFitTo, expectHookMenuWalkable, expectMenuWalkable, expectNoHorizontalOverflow, expectNoHorizontalOverflowAcrossRoutes, expectTextFits, expectTouchTargets, expectTouchTargetsAcrossRoutes, findOverlaps, findOverlapsWithin, gameProjects, horizontalOverflowPx, measureActionBinding, measureHorizontalOverflow, measureTextFit, overlaps, phone, readActionElements, readHorizontalOverflow, readTextBoxes, regionDiff, renderFindings, renderOverflow, renderRouteAudit, renderWalk, routeProblems, shrinkVisibleHeight, stubGamepad, summariseActionBinding, summariseOverflow, summariseTextFit, summariseTouchTargets, textFitFindings, toActionReading, toOverflowReading, walkFailed, walkHookMenus, walkMenus };