@dloizides/game-e2e 1.4.1 → 1.5.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,14 @@
2
2
 
3
3
  All notable changes to `@dloizides/game-e2e` are documented here.
4
4
 
5
+ ## 1.5.0
6
+
7
+ TEXT-FIT-1 "UI text never overflows its box at 360x640 or desktop, in every state":
8
+
9
+ - `expectTextFits(page, selector?, options?)`, `measureTextFit`, `readTextBoxes`, `summariseTextFit`, `textFitFindings`:
10
+ fails when visible text is wider/taller than its box or spills its parent, across named UI states. Trigger: Surge's
11
+ "Daily run" button with the "Completed today" badge ran past the button edge at 360x640 and 1280.
12
+
5
13
  ## 1.4.0
6
14
 
7
15
  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,56 @@ 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
+ 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 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, armVisibleHeight, auditRoute, auditTouchTargets, canvasBoxToPage, controlName, countDiff, desktop, deviceDescriptor, diffPngs, domControls, expectCanvasHeight, expectCanvasInside, expectFitTo, expectHookMenuWalkable, expectMenuWalkable, expectNoHorizontalOverflow, expectNoHorizontalOverflowAcrossRoutes, expectTextFits, expectTouchTargets, expectTouchTargetsAcrossRoutes, findOverlaps, findOverlapsWithin, gameProjects, horizontalOverflowPx, measureHorizontalOverflow, measureTextFit, overlaps, phone, readHorizontalOverflow, readTextBoxes, regionDiff, renderFindings, renderOverflow, renderRouteAudit, renderWalk, routeProblems, shrinkVisibleHeight, stubGamepad, summariseOverflow, summariseTextFit, summariseTouchTargets, textFitFindings, toOverflowReading, walkFailed, walkHookMenus, walkMenus };
package/dist/index.d.ts CHANGED
@@ -284,4 +284,56 @@ 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
+ 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 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, armVisibleHeight, auditRoute, auditTouchTargets, canvasBoxToPage, controlName, countDiff, desktop, deviceDescriptor, diffPngs, domControls, expectCanvasHeight, expectCanvasInside, expectFitTo, expectHookMenuWalkable, expectMenuWalkable, expectNoHorizontalOverflow, expectNoHorizontalOverflowAcrossRoutes, expectTextFits, expectTouchTargets, expectTouchTargetsAcrossRoutes, findOverlaps, findOverlapsWithin, gameProjects, horizontalOverflowPx, measureHorizontalOverflow, measureTextFit, overlaps, phone, readHorizontalOverflow, readTextBoxes, regionDiff, renderFindings, renderOverflow, renderRouteAudit, renderWalk, routeProblems, shrinkVisibleHeight, stubGamepad, summariseOverflow, summariseTextFit, summariseTouchTargets, textFitFindings, toOverflowReading, walkFailed, walkHookMenus, walkMenus };
package/dist/index.js CHANGED
@@ -903,6 +903,118 @@ ${renderWalk(results)}`);
903
903
  }
904
904
  }
905
905
 
906
+ // src/text-fit-report.ts
907
+ var TEXT_FIT_TOLERANCE_PX = 1;
908
+ function ownOverflow(r, tol) {
909
+ if (r.inline) {
910
+ return null;
911
+ }
912
+ const wide = r.scrollWidth - r.clientWidth;
913
+ const tall = r.scrollHeight - r.clientHeight;
914
+ if (wide > tol) {
915
+ return { name: r.name, text: r.text, why: "text wider than its box", px: wide };
916
+ }
917
+ if (tall > tol) {
918
+ return { name: r.name, text: r.text, why: "text taller than its box", px: tall };
919
+ }
920
+ return null;
921
+ }
922
+ function spill(r, tol) {
923
+ const px = Math.max(r.parentLeft - r.left, r.parentTop - r.top, r.right - r.parentRight, r.bottom - r.parentBottom);
924
+ return px > tol ? { name: r.name, text: r.text, why: "spills out of its parent", px: Math.round(px) } : null;
925
+ }
926
+ function textFitFindings(r, tol = TEXT_FIT_TOLERANCE_PX) {
927
+ return [ownOverflow(r, tol), spill(r, tol)].filter((f) => f !== null);
928
+ }
929
+ var renderFinding = (f) => `
930
+ ${f.name} "${f.text}": ${f.why} by ${String(f.px)}px`;
931
+ function summariseTextFit(states, where, tol = TEXT_FIT_TOLERANCE_PX) {
932
+ if (states.length === 0) {
933
+ return { problems: 1, message: `${where}: no UI state was measured at all` };
934
+ }
935
+ let problems = 0;
936
+ const lines = states.map((s) => {
937
+ if (s.readings.length === 0) {
938
+ problems += 1;
939
+ return `
940
+ ${s.state}: BLIND - no visible text element matched`;
941
+ }
942
+ const found = s.readings.flatMap((r) => textFitFindings(r, tol));
943
+ problems += found.length;
944
+ const head = found.length > 0 ? `${String(found.length)} overflow(s)` : "ok";
945
+ return `
946
+ ${s.state}: ${head} over ${String(s.readings.length)} text element(s)${found.map(renderFinding).join("")}`;
947
+ });
948
+ return { problems, message: `${where}: ${String(states.length)} state(s), ${String(problems)} problem(s)${lines.join("")}` };
949
+ }
950
+ var TEXT_FIT_SELECTOR = "body *";
951
+ async function readTextBoxes(page, selector = TEXT_FIT_SELECTOR) {
952
+ return page.evaluate((sel) => {
953
+ const display = (el) => getComputedStyle(el).display;
954
+ const ownText = (el) => [...el.childNodes].filter((n) => n.nodeType === Node.TEXT_NODE).map((n) => n.textContent ?? "").join("").trim();
955
+ const shown = (el) => {
956
+ const r = el.getBoundingClientRect();
957
+ return r.width > 0 && r.height > 0 && getComputedStyle(el).visibility !== "hidden" && el.closest('[aria-hidden="true"]') === null;
958
+ };
959
+ const scrolls = (el) => /auto|scroll/.test(getComputedStyle(el).overflowX + getComputedStyle(el).overflowY);
960
+ const container = (el) => {
961
+ let p = el.parentElement;
962
+ while (p && (display(p) === "inline" || display(p) === "contents")) {
963
+ p = p.parentElement;
964
+ }
965
+ return p;
966
+ };
967
+ const label = (el) => {
968
+ const id = el.id !== "" ? `#${el.id}` : "";
969
+ const cls = typeof el.className === "string" && el.className.trim() !== "" ? `.${el.className.trim().split(/\s+/).join(".")}` : "";
970
+ return `${el.tagName.toLowerCase()}${id}${cls}`;
971
+ };
972
+ const els = [...document.querySelectorAll(sel)].filter((el) => !(el instanceof SVGElement) && ownText(el) !== "" && shown(el));
973
+ return els.flatMap((el) => {
974
+ const parent = container(el);
975
+ if (!parent || parent === document.body || parent === document.documentElement || scrolls(parent)) {
976
+ return [];
977
+ }
978
+ const r = el.getBoundingClientRect();
979
+ const p = parent.getBoundingClientRect();
980
+ return [{
981
+ name: label(el),
982
+ text: ownText(el).slice(0, 40),
983
+ inline: display(el) === "inline",
984
+ clientWidth: el.clientWidth,
985
+ clientHeight: el.clientHeight,
986
+ scrollWidth: el.scrollWidth,
987
+ scrollHeight: el.scrollHeight,
988
+ left: r.left,
989
+ top: r.top,
990
+ right: r.right,
991
+ bottom: r.bottom,
992
+ parentLeft: p.left,
993
+ parentTop: p.top,
994
+ parentRight: p.right,
995
+ parentBottom: p.bottom
996
+ }];
997
+ });
998
+ }, selector);
999
+ }
1000
+ async function measureTextFit(page, selector = TEXT_FIT_SELECTOR, states) {
1001
+ if (!states || states.length === 0) {
1002
+ return [{ state: "current", readings: await readTextBoxes(page, selector) }];
1003
+ }
1004
+ const out = [];
1005
+ for (const s of states) {
1006
+ await s.enter(page);
1007
+ out.push({ state: s.name, readings: await readTextBoxes(page, selector) });
1008
+ }
1009
+ return out;
1010
+ }
1011
+ async function expectTextFits(page, selector = TEXT_FIT_SELECTOR, options = {}) {
1012
+ const measured = await measureTextFit(page, selector, options.states);
1013
+ const summary = summariseTextFit(measured, options.where ?? selector, options.tolerancePx ?? TEXT_FIT_TOLERANCE_PX);
1014
+ test.expect(summary.problems, summary.message).toBe(0);
1015
+ return measured;
1016
+ }
1017
+
906
1018
  exports.ANTI_ALIAS_TOLERANCE = ANTI_ALIAS_TOLERANCE;
907
1019
  exports.CANVAS_TIMEOUT_MS = CANVAS_TIMEOUT_MS;
908
1020
  exports.CONTROL_SELECTOR = CONTROL_SELECTOR;
@@ -919,6 +1031,8 @@ exports.PHONE_DEVICE = PHONE_DEVICE;
919
1031
  exports.PHONE_SIZE = PHONE_SIZE;
920
1032
  exports.RELAYOUT_TIMEOUT_MS = RELAYOUT_TIMEOUT_MS;
921
1033
  exports.STUB_FRAMES = STUB_FRAMES;
1034
+ exports.TEXT_FIT_SELECTOR = TEXT_FIT_SELECTOR;
1035
+ exports.TEXT_FIT_TOLERANCE_PX = TEXT_FIT_TOLERANCE_PX;
922
1036
  exports.WALK_INPUTS = WALK_INPUTS;
923
1037
  exports.armVisibleHeight = armVisibleHeight;
924
1038
  exports.auditRoute = auditRoute;
@@ -937,6 +1051,7 @@ exports.expectHookMenuWalkable = expectHookMenuWalkable;
937
1051
  exports.expectMenuWalkable = expectMenuWalkable;
938
1052
  exports.expectNoHorizontalOverflow = expectNoHorizontalOverflow;
939
1053
  exports.expectNoHorizontalOverflowAcrossRoutes = expectNoHorizontalOverflowAcrossRoutes;
1054
+ exports.expectTextFits = expectTextFits;
940
1055
  exports.expectTouchTargets = expectTouchTargets;
941
1056
  exports.expectTouchTargetsAcrossRoutes = expectTouchTargetsAcrossRoutes;
942
1057
  exports.findOverlaps = findOverlaps;
@@ -944,9 +1059,11 @@ exports.findOverlapsWithin = findOverlapsWithin;
944
1059
  exports.gameProjects = gameProjects;
945
1060
  exports.horizontalOverflowPx = horizontalOverflowPx;
946
1061
  exports.measureHorizontalOverflow = measureHorizontalOverflow;
1062
+ exports.measureTextFit = measureTextFit;
947
1063
  exports.overlaps = overlaps;
948
1064
  exports.phone = phone;
949
1065
  exports.readHorizontalOverflow = readHorizontalOverflow;
1066
+ exports.readTextBoxes = readTextBoxes;
950
1067
  exports.regionDiff = regionDiff;
951
1068
  exports.renderFindings = renderFindings;
952
1069
  exports.renderOverflow = renderOverflow;
@@ -956,7 +1073,9 @@ exports.routeProblems = routeProblems;
956
1073
  exports.shrinkVisibleHeight = shrinkVisibleHeight;
957
1074
  exports.stubGamepad = stubGamepad;
958
1075
  exports.summariseOverflow = summariseOverflow;
1076
+ exports.summariseTextFit = summariseTextFit;
959
1077
  exports.summariseTouchTargets = summariseTouchTargets;
1078
+ exports.textFitFindings = textFitFindings;
960
1079
  exports.toOverflowReading = toOverflowReading;
961
1080
  exports.walkFailed = walkFailed;
962
1081
  exports.walkHookMenus = walkHookMenus;