@avi2dg/checks 0.58.0 → 0.59.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.59.0
+
+Released 2026-10-31.
+
+### Features
+
+- **browser:** add shared screen size presets and starter declaration [#20](https://github.com/avi2d/checks/pull/20)
+
+## 0.58.1
+
+Released 2026-10-29.
+
+### Fixes
+
+- **browser:** judge where the pointer lands instead of timing the hover [#19](https://github.com/avi2d/checks/pull/19)
+
 ## 0.58.0
 
 Released 2026-10-29.

package/docs/design.md

@@ -84,9 +84,10 @@ Nothing would then say which gate a helper serves.
 A mutation runner's default scope covers `src/`, so the kit's own Stryker run mutates its source with no `mutate` list.
 The testing directory is named `testing` rather than `tests`, because a `src/tests/` beside the root `tests/` would read as a second suite.
 
-Five `exports` keys name a path the file does not sit at, because consumers resolve them by that name.
+Six `exports` keys name a path the file does not sit at, because consumers resolve them by that name.
 `@avi2dg/checks/scripts/test-skips.ts`, `@avi2dg/checks/scripts/comment-matchers.ts` and `@avi2dg/checks/scripts/prose-matchers.ts` point at their files under `src/`.
 `@avi2dg/checks/browser-hooks.ts` points at `src/quality/browser/hooks.ts`, whose types a product's browser hooks import.
+`@avi2dg/checks/browser-checks.json` points at `src/quality/browser/browser-checks.json`, the starter a product copies.
 `@avi2dg/checks/templates/*` points at `dist/templates/`.
 A path read without the resolver, such as `node_modules/@avi2dg/checks/scripts/test-skips.ts`, does not exist.
 

package/docs/gates/checks-browser.md

@@ -121,12 +121,12 @@ It reads `browser-checks.json` in the directory it runs in:
     { "path": "/ru/", "locale": "ru" }
   ],
   "viewports": [
-    { "name": "phone", "width": 375, "height": 812, "touch": true },
-    { "name": "desktop", "width": 1280, "height": 800 }
+    { "preset": "anchor" },
+    { "name": "small laptop", "width": 1280, "height": 720, "device": "desktop" }
   ],
   "states": [
     { "name": "default" },
-    { "name": "enlarged text", "textPx": 32 },
+    { "preset": "enlarged-text" },
     { "name": "reduced motion", "reducedMotion": "reduce" }
   ],
   "targets": [
@@ -143,8 +143,8 @@ It reads `browser-checks.json` in the directory it runs in:
 | --- | --- |
 | `site` | the directory of the built site, which the runner serves on a local port, an `index.html` answering for its directory |
 | `routes` | each page to visit, as a `path` from the site root and the `locale` it renders |
-| `viewports` | each window to visit in, with a `name`, a `width` and a `height` in pixels, and `touch` for a phone that has touch and a mobile viewport |
-| `states` | each condition to visit in, with a `name`, `textPx` for the browser's default text size, and `reducedMotion` as `reduce` or `no-preference` |
+| `viewports` | each window to visit in, with a `name`, a `width` and a `height` in pixels, `touch` for a phone that has touch and a mobile viewport, and `device` as `phone`, `tablet` or `desktop`, or a `preset` that stands for a set of screen sizes |
+| `states` | each condition to visit in, with a `name`, `textPx` for the browser's default text size, and `reducedMotion` as `reduce` or `no-preference`, or the `enlarged-text` preset |
 | `targets` | each named control or text the checks judge, with a CSS `selector`, the `routes` it is on when not every route, and `focusable` when Tab must reach it |
 | `checks` | the built-in checks to run, from `layout`, `keyboard`, `motion`, `axe`, `nesting` and `assets` |
 | `hooks` | the module of product hooks, as a path from the directory the runner runs in |
@@ -153,6 +153,88 @@ It reads `browser-checks.json` in the directory it runs in:
 A declaration that names a route, viewport, state, target or check twice is refused.
 So are a `motion` check with no state whose `reducedMotion` is `reduce`, a `keyboard` check with no `focusable` target, and a target or a hook that names an undeclared route.
 
+### Screen sizes
+
+A viewport `{ "preset": "anchor" }` stands for the anchor set of screen sizes, and `{ "preset": "full" }` for the full set.
+The full set holds the anchors and eleven more sizes.
+A product runs the anchor set on every pull request and the full set at night.
+Each size in a set is a viewport named for its device and its size, with `device` set, and each phone also sets `touch`.
+A preset sits beside a product's own viewports.
+A name both declare is refused as declared twice, and so is a size that two listed presets both hold.
+
+<!-- generated screen-sizes: bun run build writes it from SCREEN_SIZES in src/quality/browser/screen-sizes.ts and scripts/doc-blocks.ts -->
+
+| Device | Width | Height | Name | Sets |
+| --- | --- | --- | --- | --- |
+| phone | 360 | 640 | `phone-360x640` | `anchor` and `full` |
+| phone | 375 | 667 | `phone-375x667` | `anchor` and `full` |
+| phone | 393 | 852 | `phone-393x852` | `anchor` and `full` |
+| phone | 412 | 915 | `phone-412x915` | `anchor` and `full` |
+| tablet | 820 | 1180 | `tablet-820x1180` | `anchor` and `full` |
+| desktop | 1366 | 768 | `desktop-1366x768` | `anchor` and `full` |
+| desktop | 1440 | 900 | `desktop-1440x900` | `anchor` and `full` |
+| desktop | 1920 | 1080 | `desktop-1920x1080` | `anchor` and `full` |
+| phone | 320 | 568 | `phone-320x568` | `full` |
+| phone | 360 | 540 | `phone-360x540` | `full` |
+| phone | 375 | 567 | `phone-375x567` | `full` |
+| phone | 375 | 812 | `phone-375x812` | `full` |
+| phone | 390 | 844 | `phone-390x844` | `full` |
+| phone | 430 | 932 | `phone-430x932` | `full` |
+| tablet | 768 | 1024 | `tablet-768x1024` | `full` |
+| tablet | 1024 | 1366 | `tablet-1024x1366` | `full` |
+| desktop | 1280 | 800 | `desktop-1280x800` | `full` |
+| desktop | 1536 | 864 | `desktop-1536x864` | `full` |
+| desktop | 2560 | 1440 | `desktop-2560x1440` | `full` |
+
+<!-- end generated screen-sizes -->
+
+The state `{ "preset": "enlarged-text" }` stands for a state named `enlarged text` whose `textPx` is 32.
+The sizes were checked on 2026-10-31 against four sources.
+They are StatCounter's screen resolution statistics, the point sizes in Apple's Human Interface Guidelines, Material Design's device metrics and the Chrome UX Report.
+They are due for a recheck against those sources once a year.
+
+### Start from the shipped declaration
+
+The kit ships a starter declaration, which a product copies and then edits to its own routes and targets:
+
+```sh
+cp node_modules/@avi2dg/checks/src/quality/browser/browser-checks.json browser-checks.json
+```
+
+A host resolves it as `@avi2dg/checks/browser-checks.json`.
+
+<!-- generated starter: bun run build writes it from src/quality/browser/browser-checks.json and scripts/doc-blocks.ts -->
+
+```json
+{
+  "site": "dist",
+  "routes": [
+    { "path": "/", "locale": "en" }
+  ],
+  "viewports": [
+    { "preset": "anchor" }
+  ],
+  "states": [
+    { "name": "default" },
+    { "preset": "enlarged-text" },
+    { "name": "reduced motion", "reducedMotion": "reduce" }
+  ],
+  "targets": [
+    { "name": "headline", "selector": "main h1" },
+    { "name": "link", "selector": "a[href]", "focusable": true }
+  ],
+  "checks": ["layout", "keyboard", "motion", "axe", "nesting", "assets"]
+}
+```
+
+<!-- end generated starter -->
+
+For the night run, a product keeps a second declaration in a directory of its own.
+Its `site` is a path from that directory, such as `../dist`, and its viewports are `{ "preset": "full" }`.
+It runs `checks-browser <directory>` on that directory.
+
+### Chrome and the peers
+
 It drives the Chrome the machine has, which `CHROME_PATH` names, or Chrome's standard install when it is unset.
 The product installs the optional peers the runner loads, at the versions the kit pins:
 
@@ -183,15 +265,15 @@ It reads the declaration in the directory it runs in, or in the directory it is
 ## Sample output
 
 ```
-browser: targets at /ru/ (ru), phone 375x812 touch, enlarged text scanned language switch 1, email contact 1, headline 1
-browser: layout at /ru/ (ru), phone 375x812 touch, enlarged text scanned language switch 1, email contact 1, headline 1
-browser: keyboard at /ru/ (ru), phone 375x812 touch, enlarged text scanned language switch 1, email contact 1
-browser: axe at /ru/ (ru), phone 375x812 touch, enlarged text scanned 11 rule(s)
+browser: targets at /ru/ (ru), phone-375x667 375x667 touch, enlarged text scanned language switch 1, email contact 1, headline 1
+browser: layout at /ru/ (ru), phone-375x667 375x667 touch, enlarged text scanned language switch 1, email contact 1, headline 1
+browser: keyboard at /ru/ (ru), phone-375x667 375x667 touch, enlarged text scanned language switch 1, email contact 1
+browser: axe at /ru/ (ru), phone-375x667 375x667 touch, enlarged text scanned 11 rule(s)
 browser: 1 contrast check(s) axe cannot measure, reported as unverified:
-  axe at /ru/ (ru), phone 375x812 touch, enlarged text: color-contrast unverified: header > p: Element's background color could not be determined due to a background image
+  axe at /ru/ (ru), phone-375x667 375x667 touch, enlarged text: color-contrast unverified: header > p: Element's background color could not be determined due to a background image
 browser: 2 failure(s) in 4 check run(s) over 1 route(s), 1 viewport(s), 1 state(s) and 3 target(s):
-  layout at /ru/ (ru), phone 375x812 touch, enlarged text: email contact "Написать письмо владельцу" clips its own text
-  axe at /ru/ (ru), phone 375x812 touch, enlarged text: nested-interactive (serious): button: Interactive controls must not be nested
+  layout at /ru/ (ru), phone-375x667 375x667 touch, enlarged text: email contact "Написать письмо владельцу" clips its own text
+  axe at /ru/ (ru), phone-375x667 375x667 touch, enlarged text: nested-interactive (serious): button: Interactive controls must not be nested
 ```
 
 ## When it runs

package/docs/shipped-files.md

@@ -21,7 +21,7 @@ Every path is relative to the installed package, `node_modules/@avi2dg/checks/`.
 | `commitlint.config.ts` | the shared commitlint config |
 | `dependency-cruiser.config.js` | the kit's dependency-cruiser rules as a base a `.dependency-cruiser.cjs` extends by path, which the build writes |
 | `knip-base.json` | the Knip `include` setting, for a configuration that spreads it |
-| `src/` | every bin, which a package script calls by its `checks-` name, the modules the bins import, and the Effect language service severities under `src/quality/presets/` |
+| `src/` | every bin, which a package script calls by its `checks-` name, the modules the bins import, the Effect language service severities under `src/quality/presets/`, and the starter `browser-checks.json` under `src/quality/browser/` |
 | `dist/` | the compiled oxlint plugins, the config builders `@avi2dg/checks/oxlint`, `@avi2dg/checks/knip`, `@avi2dg/checks/dependency-cruiser` and `@avi2dg/checks/stylelint` resolve to, and the doc templates, one template per kind of doc file |
 | `oxlintrc.json` | the oxlint `base` as a config a `.oxlintrc.json` extends by path, which the build writes |
 | `stryker.preset.js` | the Stryker mutation-testing preset, which refuses a full run outside CI |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "author": {
     "name": "avi2d",
@@ -141,6 +141,7 @@
     "./templates/*": "./dist/templates/*",
     "./tsconfig.effect.json": "./tsconfig.effect.json",
     "./browser-hooks.ts": "./src/quality/browser/hooks.ts",
+    "./browser-checks.json": "./src/quality/browser/browser-checks.json",
     "./oxlint": {
       "types": "./dist/presets/oxlint.d.ts",
       "default": "./dist/presets/oxlint.js"

package/src/quality/browser/browser-checks.json

@@ -0,0 +1,19 @@
+{
+  "site": "dist",
+  "routes": [
+    { "path": "/", "locale": "en" }
+  ],
+  "viewports": [
+    { "preset": "anchor" }
+  ],
+  "states": [
+    { "name": "default" },
+    { "preset": "enlarged-text" },
+    { "name": "reduced motion", "reducedMotion": "reduce" }
+  ],
+  "targets": [
+    { "name": "headline", "selector": "main h1" },
+    { "name": "link", "selector": "a[href]", "focusable": true }
+  ],
+  "checks": ["layout", "keyboard", "motion", "axe", "nesting", "assets"]
+}

package/src/quality/browser/declaration.ts

@@ -1,5 +1,6 @@
-import { Effect, FileSystem, Path, Schema } from "effect";
+import { Array as Arr, Effect, FileSystem, Path, Schema } from "effect";
 import { Usage } from "../../core/main.ts";
+import { DEVICES, ENLARGED_TEXT_PX, SCREEN_SIZE_SETS, SCREEN_SIZES, screenSizeName, type ScreenSize } from "./screen-sizes.ts";
 
 const DECLARATION = "browser-checks.json";
 
@@ -15,7 +16,15 @@ const Route = Schema.Struct({
   locale: Name,
 });
 
-const Viewport = Schema.Struct({ name: Name, width: Pixels, height: Pixels, touch: Schema.optionalKey(Schema.Boolean) });
+const Viewport = Schema.Struct({
+  name: Name,
+  width: Pixels,
+  height: Pixels,
+  touch: Schema.optionalKey(Schema.Boolean),
+  device: Schema.optionalKey(Schema.Literals(DEVICES)),
+});
+
+const ScreenSizeSet = Schema.Struct({ preset: Schema.Literals(SCREEN_SIZE_SETS) });
 
 const State = Schema.Struct({
   name: Name,
@@ -23,6 +32,10 @@ const State = Schema.Struct({
   reducedMotion: Schema.optionalKey(Schema.Literals(["reduce", "no-preference"])),
 });
 
+const STATE_PRESETS = ["enlarged-text"] as const;
+
+const StatePreset = Schema.Struct({ preset: Schema.Literals(STATE_PRESETS) });
+
 const Target = Schema.Struct({
   name: Name,
   selector: Name,
@@ -40,6 +53,12 @@ const Declaration = Schema.Struct({
   hooks: Schema.optionalKey(Name),
 });
 
+const Listed = Schema.Struct({
+  ...Declaration.fields,
+  viewports: Schema.NonEmptyArray(Schema.Union([Viewport, ScreenSizeSet])),
+  states: Schema.NonEmptyArray(Schema.Union([State, StatePreset])),
+});
+
 export type Route = typeof Route.Type;
 export type Viewport = typeof Viewport.Type;
 export type State = typeof State.Type;
@@ -52,7 +71,26 @@ export type Visit = {
   readonly state: State;
 };
 
-const decodeDeclaration = Schema.decodeUnknownEffect(Schema.fromJsonString(Declaration));
+export type Listed = typeof Listed.Type;
+
+const decodeListed = Schema.decodeUnknownEffect(Schema.fromJsonString(Listed));
+
+function viewportOf(size: ScreenSize): Viewport {
+  const { device, width, height } = size;
+  return { name: screenSizeName(size), width, height, device, ...(device === "phone" ? { touch: true } : {}) };
+}
+
+const STATES: Readonly<Record<(typeof STATE_PRESETS)[number], State>> = {
+  "enlarged-text": { name: "enlarged text", textPx: ENLARGED_TEXT_PX },
+};
+
+export function expanded(listed: Listed): Declaration {
+  return {
+    ...listed,
+    viewports: Arr.flatMap(listed.viewports, (entry) => ("preset" in entry ? Arr.map(SCREEN_SIZES[entry.preset], viewportOf) : [entry])),
+    states: Arr.map(listed.states, (entry) => ("preset" in entry ? STATES[entry.preset] : entry)),
+  };
+}
 
 function repeated(names: readonly string[]): readonly string[] {
   return [...new Set(names.filter((name, index) => names.indexOf(name) !== index))];
@@ -85,9 +123,10 @@ export const readDeclaration = Effect.fn("readDeclaration")(function* (root: str
   if (!(yield* fs.exists(file))) {
     return yield* new Usage({ message: `${DECLARATION} is missing, and a product opts in to the browser checks by declaring its pages there` });
   }
-  const declaration = yield* decodeDeclaration(yield* fs.readFileString(file)).pipe(
+  const listed = yield* decodeListed(yield* fs.readFileString(file)).pipe(
     Effect.mapError(({ message }) => new Usage({ message: `${DECLARATION} does not decode: ${message}` })),
   );
+  const declaration = expanded(listed);
   const found = inconsistencies(declaration);
   if (found.length > 0) return yield* new Usage({ message: `${DECLARATION}: ${found.join("; ")}` });
   return declaration;

package/src/quality/browser/motion.ts

@@ -1,10 +1,63 @@
 import { Effect, Schema } from "effect";
 import type { BrowserContext, Page } from "playwright-core";
+import type { Rect } from "./dom.ts";
 import { attempt, BrowserFailure } from "./page.ts";
 
 const CONTROLS = "a[href], button, summary, input, select, textarea";
 
-const HOVER_TIMEOUT_MS = 2_000;
+const Landing = Schema.NullOr(Schema.Struct({ x: Schema.Finite, y: Schema.Finite }));
+
+type ScrollAlignment = "nearest" | "center" | "start" | "end";
+
+type PointerTarget = {
+  readonly ownerDocument: { readonly documentElement: { readonly clientWidth: number; readonly clientHeight: number } };
+  readonly scrollIntoView: (options: { readonly behavior: "instant"; readonly block: ScrollAlignment; readonly inline: ScrollAlignment }) => void;
+  readonly getClientRects: () => Iterable<Rect>;
+  readonly getRootNode: () => { readonly elementFromPoint: (x: number, y: number) => unknown };
+};
+
+// Playwright's hover retries until a timeout to give up on a control the pointer cannot reach, and a busy host outlasts any timeout on a control it can reach.
+// The page runs this from its source text, so it must not reach anything outside its own body.
+function pointerLanding(control: PointerTarget): typeof Landing.Type {
+  const reachesControl = (hit: unknown): boolean => {
+    let node: unknown = hit;
+    while (node !== null && node !== undefined) {
+      if (node === control) return true;
+      const candidate = node as { readonly assignedSlot?: unknown; readonly parentNode?: unknown; readonly host?: unknown };
+      if (candidate.assignedSlot !== undefined && candidate.assignedSlot !== null) {
+        node = candidate.assignedSlot;
+        continue;
+      }
+      if (candidate.parentNode !== undefined && candidate.parentNode !== null) {
+        node = candidate.parentNode;
+        continue;
+      }
+      if (candidate.host !== undefined && candidate.host !== null) {
+        node = candidate.host;
+        continue;
+      }
+      return false;
+    }
+    return false;
+  };
+  const alignments: readonly ScrollAlignment[] = ["nearest", "center", "start", "end"];
+  for (const alignment of alignments) {
+    control.scrollIntoView({ behavior: "instant", block: alignment, inline: alignment });
+    const { clientWidth, clientHeight } = control.ownerDocument.documentElement;
+    for (const rect of control.getClientRects()) {
+      const left = Math.max(rect.left, 0);
+      const right = Math.min(rect.right, clientWidth);
+      const top = Math.max(rect.top, 0);
+      const bottom = Math.min(rect.bottom, clientHeight);
+      if (right - left < 1 || bottom - top < 1) continue;
+      const x = (left + right) / 2;
+      const y = (top + bottom) / 2;
+      const hit = control.getRootNode().elementFromPoint(x, y);
+      if (hit !== null && reachesControl(hit)) return { x, y };
+    }
+  }
+  return null;
+}
 
 // A motion reset for reduced motion shortens animations to near zero rather than removing them, so one that ends within a frame never moves.
 const FRAME_MS = 1000 / 60;
@@ -33,6 +86,8 @@ const MOTION_RECORDER = `(() => {
 
 const decodeStarted = Schema.decodeUnknownEffect(Schema.Array(Schema.String));
 
+const decodeLanding = Schema.decodeUnknownEffect(Landing);
+
 export function recordMotion(context: BrowserContext): Promise<unknown> {
   return context.addInitScript(MOTION_RECORDER);
 }
@@ -67,11 +122,12 @@ export const judgeStillness = Effect.fn("judgeStillness")(function* (page: Page)
     const control = controls.nth(index);
     if (!(yield* attempt(`cannot see control ${index + 1}`, () => control.isVisible()))) continue;
     judged += 1;
-    const hovered = yield* attempt(`cannot hover control ${index + 1}`, () => control.hover({ timeout: HOVER_TIMEOUT_MS })).pipe(
-      Effect.as(true),
-      Effect.catchTag("BrowserFailure", () => Effect.succeed(false)),
+    const landing: unknown = yield* attempt(`cannot find where the pointer lands on control ${index + 1}`, () => control.evaluate(pointerLanding));
+    const point = yield* decodeLanding(landing).pipe(
+      Effect.mapError(() => new BrowserFailure({ message: `the pointer landing on control ${index + 1} gave ${JSON.stringify(landing)}` })),
     );
-    if (hovered) {
+    if (point !== null) {
+      yield* attempt(`cannot hover control ${index + 1}`, () => page.mouse.move(point.x, point.y));
       yield* animatedDuring(`on hovering control ${index + 1}`);
       yield* attempt("cannot move the pointer away", () => page.mouse.move(0, 0));
       yield* animatedDuring(`on leaving control ${index + 1}`);

package/src/quality/browser/screen-sizes.ts

@@ -0,0 +1,48 @@
+import type { NonEmptyReadonlyArray } from "effect/Array";
+
+export const DEVICES = ["phone", "tablet", "desktop"] as const;
+
+type Device = (typeof DEVICES)[number];
+
+export type ScreenSize = { readonly device: Device; readonly width: number; readonly height: number };
+
+const phone = (width: number, height: number): ScreenSize => ({ device: "phone", width, height });
+const tablet = (width: number, height: number): ScreenSize => ({ device: "tablet", width, height });
+const desktop = (width: number, height: number): ScreenSize => ({ device: "desktop", width, height });
+
+const ANCHOR = [
+  phone(360, 640),
+  phone(375, 667),
+  phone(393, 852),
+  phone(412, 915),
+  tablet(820, 1180),
+  desktop(1366, 768),
+  desktop(1440, 900),
+  desktop(1920, 1080),
+] as const;
+
+const NIGHTLY = [
+  phone(320, 568),
+  phone(360, 540),
+  phone(375, 567),
+  phone(375, 812),
+  phone(390, 844),
+  phone(430, 932),
+  tablet(768, 1024),
+  tablet(1024, 1366),
+  desktop(1280, 800),
+  desktop(1536, 864),
+  desktop(2560, 1440),
+] as const;
+
+export const SCREEN_SIZE_SETS = ["anchor", "full"] as const;
+
+export type ScreenSizeSet = (typeof SCREEN_SIZE_SETS)[number];
+
+export const SCREEN_SIZES: Readonly<Record<ScreenSizeSet, NonEmptyReadonlyArray<ScreenSize>>> = { anchor: ANCHOR, full: [...ANCHOR, ...NIGHTLY] };
+
+export function screenSizeName({ device, width, height }: ScreenSize): string {
+  return `${device}-${width}x${height}`;
+}
+
+export const ENLARGED_TEXT_PX = 32;