@avi2dg/checks 0.34.0 → 0.35.1

package/src/quality/browser/declaration.ts

@@ -0,0 +1,107 @@
+import { Effect, FileSystem, Path, Schema } from "effect";
+import { Usage } from "../../core/main.ts";
+
+const DECLARATION = "browser-checks.json";
+
+const CHECKS = ["layout", "keyboard", "motion", "axe", "nesting", "assets"] as const;
+
+export type CheckName = (typeof CHECKS)[number];
+
+const Name = Schema.NonEmptyString;
+const Pixels = Schema.Int.check(Schema.isGreaterThan(0));
+
+const Route = Schema.Struct({
+  path: Schema.String.check(Schema.isPattern(/^\//, { message: "is not a path from the site root, such as /ru/" })),
+  locale: Name,
+});
+
+const Viewport = Schema.Struct({ name: Name, width: Pixels, height: Pixels, touch: Schema.optionalKey(Schema.Boolean) });
+
+const State = Schema.Struct({
+  name: Name,
+  textPx: Schema.optionalKey(Pixels),
+  reducedMotion: Schema.optionalKey(Schema.Literals(["reduce", "no-preference"])),
+});
+
+const Target = Schema.Struct({
+  name: Name,
+  selector: Name,
+  routes: Schema.optionalKey(Schema.NonEmptyArray(Name)),
+  focusable: Schema.optionalKey(Schema.Boolean),
+});
+
+const Declaration = Schema.Struct({
+  site: Name,
+  routes: Schema.NonEmptyArray(Route),
+  viewports: Schema.NonEmptyArray(Viewport),
+  states: Schema.NonEmptyArray(State),
+  targets: Schema.NonEmptyArray(Target),
+  checks: Schema.NonEmptyArray(Schema.Literals(CHECKS)),
+  hooks: Schema.optionalKey(Name),
+});
+
+export type Route = typeof Route.Type;
+export type Viewport = typeof Viewport.Type;
+export type State = typeof State.Type;
+export type Target = typeof Target.Type;
+export type Declaration = typeof Declaration.Type;
+
+export type Visit = {
+  readonly route: Route;
+  readonly viewport: Viewport;
+  readonly state: State;
+};
+
+const decodeDeclaration = Schema.decodeUnknownEffect(Schema.fromJsonString(Declaration));
+
+function repeated(names: readonly string[]): readonly string[] {
+  return [...new Set(names.filter((name, index) => names.indexOf(name) !== index))];
+}
+
+export function inconsistencies(declaration: Declaration): readonly string[] {
+  const paths = declaration.routes.map(({ path }) => path);
+  const found = [
+    ...repeated(paths).map((path) => `route ${path} is declared twice`),
+    ...repeated(declaration.viewports.map(({ name }) => name)).map((name) => `viewport ${name} is declared twice`),
+    ...repeated(declaration.states.map(({ name }) => name)).map((name) => `state ${name} is declared twice`),
+    ...repeated(declaration.targets.map(({ name }) => name)).map((name) => `target ${name} is declared twice`),
+    ...repeated(declaration.checks).map((check) => `check ${check} is declared twice`),
+    ...declaration.targets.flatMap(({ name, routes = [] }) =>
+      routes.filter((path) => !paths.includes(path)).map((path) => `target ${name} names route ${path}, which no route declares`),
+    ),
+  ];
+  if (declaration.checks.includes("motion") && !declaration.states.some(({ reducedMotion }) => reducedMotion === "reduce")) {
+    found.push("check motion judges a visitor who turns motion off, and no state sets reducedMotion to reduce");
+  }
+  if (declaration.checks.includes("keyboard") && !declaration.targets.some(({ focusable }) => focusable === true)) {
+    found.push("check keyboard judges the targets Tab reaches, and no target sets focusable");
+  }
+  return found;
+}
+
+export const readDeclaration = Effect.fn("readDeclaration")(function* (root: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const file = (yield* Path.Path).join(root, DECLARATION);
+  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(
+    Effect.mapError(({ message }) => new Usage({ message: `${DECLARATION} does not decode: ${message}` })),
+  );
+  const found = inconsistencies(declaration);
+  if (found.length > 0) return yield* new Usage({ message: `${DECLARATION}: ${found.join("; ")}` });
+  return declaration;
+});
+
+export function visitsOf({ routes, viewports, states }: Declaration): readonly Visit[] {
+  return routes.flatMap((route) => viewports.flatMap((viewport) => states.map((state) => ({ route, viewport, state }))));
+}
+
+export function targetsOn(declaration: Declaration, path: string): readonly Target[] {
+  return declaration.targets.filter(({ routes }) => routes === undefined || routes.includes(path));
+}
+
+export function describeVisit({ route, viewport, state }: Visit): string {
+  const touch = viewport.touch === true ? " touch" : "";
+  return `${route.path} (${route.locale}), ${viewport.name} ${viewport.width}x${viewport.height}${touch}, ${state.name}`;
+}

package/src/quality/browser/dom.ts

@@ -0,0 +1,121 @@
+import { Effect } from "effect";
+import type { CDPSession } from "playwright-core";
+import { attempt, BrowserFailure } from "./page.ts";
+
+export type Rect = {
+  readonly left: number;
+  readonly top: number;
+  readonly right: number;
+  readonly bottom: number;
+};
+
+type TreeNode = {
+  readonly nodeId: number;
+  readonly backendNodeId: number;
+  readonly children?: readonly TreeNode[];
+  readonly pseudoElements?: readonly TreeNode[];
+  readonly shadowRoots?: readonly TreeNode[];
+  readonly contentDocument?: TreeNode;
+};
+
+export type Dom = {
+  readonly cdp: CDPSession;
+  readonly rootId: number;
+  readonly backendOf: ReadonlyMap<number, number>;
+  readonly parentOf: ReadonlyMap<number, number>;
+};
+
+export const readDom = Effect.fn("readDom")(function* (cdp: CDPSession) {
+  const { root } = yield* attempt("cannot read the DOM", () => cdp.send("DOM.getDocument", { depth: -1, pierce: true }));
+  const backendOf = new Map<number, number>();
+  const parentOf = new Map<number, number>();
+  const visit = (node: TreeNode): void => {
+    backendOf.set(node.nodeId, node.backendNodeId);
+    const { children = [], pseudoElements = [], shadowRoots = [], contentDocument } = node;
+    for (const child of [...children, ...pseudoElements, ...shadowRoots, ...(contentDocument === undefined ? [] : [contentDocument])]) {
+      parentOf.set(child.backendNodeId, node.backendNodeId);
+      visit(child);
+    }
+  };
+  visit(root);
+  return { cdp, rootId: root.nodeId, backendOf, parentOf } satisfies Dom;
+});
+
+export const querySelectorAll = Effect.fn("querySelectorAll")(function* (dom: Dom, selector: string) {
+  const { nodeIds } = yield* attempt(`cannot query ${selector}`, () => dom.cdp.send("DOM.querySelectorAll", { nodeId: dom.rootId, selector }));
+  return nodeIds.flatMap((nodeId) => {
+    const backend = dom.backendOf.get(nodeId);
+    return backend === undefined ? [] : [backend];
+  });
+});
+
+export function isWithin(dom: Dom, node: number, ancestor: number): boolean {
+  for (let at: number | undefined = node; at !== undefined; at = dom.parentOf.get(at)) {
+    if (at === ancestor) return true;
+  }
+  return false;
+}
+
+function rectOfQuad(quad: readonly number[]): Rect {
+  const xs = quad.filter((_, index) => index % 2 === 0);
+  const ys = quad.filter((_, index) => index % 2 === 1);
+  return { left: Math.min(...xs), top: Math.min(...ys), right: Math.max(...xs), bottom: Math.max(...ys) };
+}
+
+// Chromium refuses an element with no layout box rather than answering with no quads.
+const NO_LAYOUT_BOX = "Could not compute content quads";
+
+export const lineRects = Effect.fn("lineRects")(function* (dom: Dom, backendNodeId: number) {
+  const { quads } = yield* attempt("cannot read an element's boxes", () => dom.cdp.send("DOM.getContentQuads", { backendNodeId })).pipe(
+    Effect.catchTag("BrowserFailure", (failure) => (failure.message.includes(NO_LAYOUT_BOX) ? Effect.succeed({ quads: [] }) : Effect.fail(failure))),
+  );
+  return quads.map(rectOfQuad).filter((rect) => rect.right - rect.left > 0 && rect.bottom - rect.top > 0);
+});
+
+export function overlapArea(a: Rect, b: Rect): number {
+  const width = Math.min(a.right, b.right) - Math.max(a.left, b.left);
+  const height = Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top);
+  return width > 0 && height > 0 ? width * height : 0;
+}
+
+export type Viewport = {
+  readonly width: number;
+  readonly height: number;
+  readonly contentWidth: number;
+  readonly scrollX: number;
+  readonly scrollY: number;
+};
+
+export const viewportOf = Effect.fn("viewportOf")(function* (cdp: CDPSession) {
+  const { cssLayoutViewport, cssContentSize } = yield* attempt("cannot read the layout metrics", () => cdp.send("Page.getLayoutMetrics"));
+  return {
+    width: cssLayoutViewport.clientWidth,
+    height: cssLayoutViewport.clientHeight,
+    contentWidth: cssContentSize.width,
+    scrollX: cssLayoutViewport.pageX,
+    scrollY: cssLayoutViewport.pageY,
+  } satisfies Viewport;
+});
+
+// Content quads are relative to the viewport, and the hit test takes coordinates relative to the document.
+export const nodeAt = Effect.fn("nodeAt")(function* (dom: Dom, viewport: Viewport, x: number, y: number) {
+  const { backendNodeId } = yield* attempt("cannot hit-test the page", () =>
+    dom.cdp.send("DOM.getNodeForLocation", { x: Math.round(x + viewport.scrollX), y: Math.round(y + viewport.scrollY) }),
+  );
+  return backendNodeId;
+});
+
+export const callOn = Effect.fn("callOn")(function* (dom: Dom, backendNodeId: number, functionDeclaration: string) {
+  const { object } = yield* attempt("cannot resolve an element", () => dom.cdp.send("DOM.resolveNode", { backendNodeId }));
+  const { objectId } = object;
+  if (objectId === undefined) return yield* new BrowserFailure({ message: `node ${backendNodeId} resolved to no object` });
+  const { result } = yield* attempt("cannot call into the page", () =>
+    dom.cdp.send("Runtime.callFunctionOn", { objectId, functionDeclaration, returnByValue: true }),
+  );
+  const value: unknown = result.value;
+  return value;
+});
+
+export const evaluate = Effect.fn("evaluate")(function* (cdp: CDPSession, expression: string) {
+  yield* attempt("cannot evaluate in the page", () => cdp.send("Runtime.evaluate", { expression }));
+});

package/src/quality/browser/hooks.ts

@@ -0,0 +1,57 @@
+import { Effect, FileSystem, Path, Schema } from "effect";
+import type { Page } from "playwright-core";
+import { Usage } from "../../core/main.ts";
+import type { Route, State, Viewport } from "./declaration.ts";
+import { attempt } from "./page.ts";
+
+export type HookVisit = {
+  readonly route: Route;
+  readonly viewport: Viewport;
+  readonly state: State;
+  readonly url: string;
+};
+
+const HookResult = Schema.Struct({ targets: Schema.Array(Schema.String), found: Schema.Array(Schema.String) });
+
+export type HookResult = typeof HookResult.Type;
+
+type RunHook = (page: Page, visit: HookVisit) => Promise<HookResult>;
+
+const isRunHook = (value: unknown): value is RunHook => typeof value === "function";
+
+const ProductCheck = Schema.Struct({
+  name: Schema.NonEmptyString,
+  routes: Schema.optionalKey(Schema.NonEmptyArray(Schema.NonEmptyString)),
+  run: Schema.declare(isRunHook, { expected: "a function from a page and a visit to a promised result" }),
+});
+
+export type ProductCheck = typeof ProductCheck.Type;
+
+const decodeHookModule = Schema.decodeUnknownEffect(Schema.Struct({ checks: Schema.NonEmptyArray(ProductCheck) }));
+
+const decodeHookResult = Schema.decodeUnknownEffect(HookResult);
+
+export const loadHooks = Effect.fn("loadHooks")(function* (root: string, hooks: string, paths: readonly string[]) {
+  const file = (yield* Path.Path).resolve(root, hooks);
+  if (!(yield* (yield* FileSystem.FileSystem).exists(file))) return yield* new Usage({ message: `the declared hooks module ${hooks} is missing` });
+  const loaded: unknown = yield* attempt(`cannot load the hooks module ${hooks}`, () => import(file)).pipe(
+    Effect.mapError(({ message }) => new Usage({ message })),
+  );
+  const { checks } = yield* decodeHookModule(loaded).pipe(
+    Effect.mapError(({ message }) => new Usage({ message: `the hooks module ${hooks} exports no checks a runner can call: ${message}` })),
+  );
+  const names = checks.map(({ name }) => name);
+  const problems = [
+    ...names.filter((name, index) => names.indexOf(name) !== index).map((name) => `hook ${name} is exported twice`),
+    ...checks.flatMap(({ name, routes = [] }) => routes.filter((path) => !paths.includes(path)).map((path) => `hook ${name} names route ${path}, which no route declares`)),
+  ];
+  if (problems.length > 0) return yield* new Usage({ message: `${hooks}: ${problems.join("; ")}` });
+  return checks;
+});
+
+export const runHook = Effect.fn("runHook")(function* (check: ProductCheck, page: Page, visit: HookVisit) {
+  return yield* attempt(`hook ${check.name} throws`, () => check.run(page, visit)).pipe(
+    Effect.flatMap((result) => decodeHookResult(result).pipe(Effect.mapError(({ message }) => ({ message: `hook ${check.name} returns no result: ${message}` })))),
+    Effect.catch(({ message }) => Effect.succeed({ targets: [], found: [message] })),
+  );
+});

package/src/quality/browser/keyboard.ts

@@ -0,0 +1,72 @@
+import { Effect } from "effect";
+import type { Page } from "playwright-core";
+import type { Target } from "./declaration.ts";
+import { attempt } from "./page.ts";
+import { countVisible } from "./targets.ts";
+
+const FOCUS_RING_MARGIN_PX = 6;
+
+// A focus trap would hold Tab on the page forever, so the walk gives up past this many stops.
+const STOP_LIMIT = 500;
+
+type KeyboardReport = {
+  readonly found: readonly string[];
+  readonly reached: ReadonlyMap<string, number>;
+};
+
+const count = (page: Page, selector: string) => attempt(`cannot query ${selector}`, () => page.locator(selector).count());
+
+const focusedTargets = Effect.fn("focusedTargets")(function* (page: Page, targets: readonly Target[]) {
+  const focused: Target[] = [];
+  for (const target of targets) {
+    const matches = yield* attempt(`cannot query ${target.selector}`, () => page.locator(target.selector).and(page.locator(":focus")).count());
+    if (matches > 0) focused.push(target);
+  }
+  return focused;
+});
+
+const focusRingShows = Effect.fn("focusRingShows")(function* (page: Page) {
+  const focused = yield* attempt("cannot hold the focused element", () => page.locator(":focus").elementHandle());
+  const box = yield* attempt("cannot measure the focused element", () => focused.boundingBox());
+  if (box === null) return false;
+  const clip = {
+    x: Math.max(0, box.x - FOCUS_RING_MARGIN_PX),
+    y: Math.max(0, box.y - FOCUS_RING_MARGIN_PX),
+    width: box.width + 2 * FOCUS_RING_MARGIN_PX,
+    height: box.height + 2 * FOCUS_RING_MARGIN_PX,
+  };
+  const withFocus = yield* attempt("cannot capture the focused element", () => page.screenshot({ clip }));
+  yield* attempt("cannot blur the focused element", () => page.evaluate("document.activeElement.blur()"));
+  const withoutFocus = yield* attempt("cannot capture the blurred element", () => page.screenshot({ clip }));
+  yield* attempt("cannot focus the element again", () => focused.focus());
+  return !withFocus.equals(withoutFocus);
+});
+
+// Past the last stop Tab leaves the page for the browser, and the next press starts over at the first stop.
+const tabToNextStop = Effect.fn("tabToNextStop")(function* (page: Page) {
+  yield* attempt("cannot press Tab", () => page.keyboard.press("Tab"));
+  return (yield* count(page, ":focus")) > 0;
+});
+
+export const judgeKeyboard = Effect.fn("judgeKeyboard")(function* (page: Page, targets: readonly Target[]) {
+  const found: string[] = [];
+  const reached = new Map<string, number>();
+  let stops = 0;
+  while (yield* tabToNextStop(page)) {
+    stops += 1;
+    if (stops > STOP_LIMIT) {
+      found.push(`Tab never leaves the page within ${STOP_LIMIT} stops`);
+      break;
+    }
+    const focused = yield* focusedTargets(page, targets);
+    for (const target of focused) reached.set(target.name, (reached.get(target.name) ?? 0) + 1);
+    if (focused.length > 0 && !(yield* focusRingShows(page))) {
+      found.push(`${focused.map(({ name }) => name).join(" and ")} shows no visible focus when Tab reaches it`);
+    }
+  }
+  for (const target of targets) {
+    const present = yield* countVisible(page, target.selector);
+    if ((reached.get(target.name) ?? 0) !== present) found.push(`Tab reached ${target.name} ${reached.get(target.name) ?? 0} of ${present} time(s)`);
+  }
+  return { found, reached } satisfies KeyboardReport;
+});

package/src/quality/browser/layout.ts

@@ -0,0 +1,208 @@
+import { Effect } from "effect";
+import type { CDPSession } from "playwright-core";
+import type { Target } from "./declaration.ts";
+import { callOn, evaluate, isWithin, lineRects, nodeAt, overlapArea, querySelectorAll, readDom, viewportOf, type Dom, type Rect, type Viewport } from "./dom.ts";
+import { attempt } from "./page.ts";
+
+const EDGE_TOLERANCE_PX = 0.5;
+const OVERLAP_TOLERANCE_PX2 = 1;
+const LABEL_CHARS = 48;
+
+type Scanned = {
+  readonly name: string;
+  readonly text: string;
+  readonly lines: number;
+};
+
+type LayoutReport = {
+  readonly found: readonly string[];
+  readonly scanned: readonly Scanned[];
+  readonly parked: readonly string[];
+};
+
+type Resolved = {
+  readonly id: number;
+  readonly name: string;
+  readonly text: string;
+};
+
+function normaliseText(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+function label(element: Resolved): string {
+  return `${element.name} "${element.text.slice(0, LABEL_CHARS)}"`;
+}
+
+const textOf = Effect.fn("textOf")(function* (dom: Dom, id: number) {
+  const text = yield* callOn(dom, id, "function () { return this.textContent ?? ''; }");
+  return typeof text === "string" ? normaliseText(text) : "";
+});
+
+const IS_VISIBLE = `function () {
+  const box = this.getBoundingClientRect();
+  return box.width > 0 && box.height > 0 && this.checkVisibility({ visibilityProperty: true });
+}`;
+
+const IS_PARKED = `function () {
+  const box = this.getBoundingClientRect();
+  return box.right + scrollX <= 0 || box.bottom + scrollY <= 0 || box.width <= 1 || box.height <= 1;
+}`;
+
+const parkedUntilFocused = Effect.fn("parkedUntilFocused")(function* (dom: Dom, id: number) {
+  if ((yield* callOn(dom, id, IS_PARKED)) !== true) return false;
+  yield* callOn(dom, id, "function () { this.focus(); }");
+  const parkedWhenFocused = yield* callOn(dom, id, IS_PARKED);
+  yield* evaluate(dom.cdp, "document.activeElement?.blur()");
+  return parkedWhenFocused !== true;
+});
+
+const resolveTargets = Effect.fn("resolveTargets")(function* (dom: Dom, targets: readonly Target[]) {
+  const resolved = new Map<number, Resolved>();
+  const parked: string[] = [];
+  for (const target of targets) {
+    for (const id of yield* querySelectorAll(dom, target.selector)) {
+      if (resolved.has(id) || (yield* callOn(dom, id, IS_VISIBLE)) !== true) continue;
+      if (target.focusable === true && (yield* parkedUntilFocused(dom, id))) {
+        parked.push(target.name);
+        continue;
+      }
+      resolved.set(id, { id, name: target.name, text: yield* textOf(dom, id) });
+    }
+  }
+  return { elements: [...resolved.values()], parked };
+});
+
+const findOverlaps = Effect.fn("findOverlaps")(function* (dom: Dom, elements: readonly Resolved[], found: string[]) {
+  const boxes = yield* Effect.forEach(elements, (element) => lineRects(dom, element.id).pipe(Effect.map((rects) => ({ element, rects }))));
+  for (const [index, a] of boxes.entries()) {
+    for (const b of boxes.slice(index + 1)) {
+      if (isWithin(dom, a.element.id, b.element.id) || isWithin(dom, b.element.id, a.element.id)) continue;
+      const area = a.rects.reduce((sum, ra) => sum + b.rects.reduce((inner, rb) => inner + overlapArea(ra, rb), 0), 0);
+      if (area > OVERLAP_TOLERANCE_PX2) found.push(`${label(a.element)} overlaps ${label(b.element)} by ${area.toFixed(0)}px²`);
+    }
+  }
+});
+
+function probePoints(rect: Rect, viewport: Viewport): readonly (readonly [number, number])[] {
+  const y = (Math.max(rect.top, 0) + Math.min(rect.bottom, viewport.height)) / 2;
+  const inset = Math.min(2, (rect.right - rect.left) / 2);
+  return [
+    [rect.left + inset, y],
+    [(rect.left + rect.right) / 2, y],
+    [rect.right - inset, y],
+  ];
+}
+
+const judgeLine = Effect.fn("judgeLine")(function* (dom: Dom, viewport: Viewport, element: Resolved, rect: Rect) {
+  if (rect.left < -EDGE_TOLERANCE_PX || rect.right > viewport.width + EDGE_TOLERANCE_PX) {
+    return [`${label(element)} spans ${rect.left.toFixed(0)} to ${rect.right.toFixed(0)}px, past the ${viewport.width}px viewport`];
+  }
+  for (const [x, y] of probePoints(rect, viewport)) {
+    if (y < 0 || y >= viewport.height) continue;
+    const hit = yield* nodeAt(dom, viewport, x, y);
+    if (!isWithin(dom, hit, element.id)) return [`${label(element)} is covered or clipped at ${x.toFixed(0)},${y.toFixed(0)}`];
+  }
+  return [];
+});
+
+const CLIPS_ITS_OWN_TEXT = `function () {
+  if (getComputedStyle(this).display === "inline") return false;
+  return this.scrollWidth > this.clientWidth + 1 || this.scrollHeight > this.clientHeight + 1;
+}`;
+
+const FIRST_UNSHOWN_TEXT = `function () {
+  const alphaOf = (color) => {
+    const afterSlash = /\\/\\s*([^\\s)]+)\\s*\\)$/.exec(color);
+    if (afterSlash !== null) return parseFloat(afterSlash[1]);
+    const components = color.slice(color.indexOf("(") + 1, -1).split(",");
+    return components.length === 4 ? parseFloat(components[3]) : 1;
+  };
+  const unrendered = (element) =>
+    element.tagName === "TEXTAREA" ||
+    element.closest("svg title, svg desc") !== null ||
+    (!element.checkVisibility() && getComputedStyle(element).display !== "contents");
+  if (unrendered(this)) return null;
+  const walker = document.createTreeWalker(this, NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT, (node) => {
+    if (node.nodeType === Node.TEXT_NODE) return NodeFilter.FILTER_ACCEPT;
+    return unrendered(node) ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_SKIP;
+  });
+  for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
+    const text = node.textContent.trim();
+    if (text === "") continue;
+    const parent = node.parentElement;
+    const style = getComputedStyle(parent);
+    let boxed = parent;
+    while (getComputedStyle(boxed).display === "contents" && boxed.parentElement !== null) boxed = boxed.parentElement;
+    const range = document.createRange();
+    range.selectNodeContents(node);
+    const drawn = Array.from(range.getClientRects()).some((rect) => rect.width > 0 && rect.height > 0);
+    const shown =
+      drawn &&
+      parseFloat(style.fontSize) > 0 &&
+      style.visibility === "visible" &&
+      boxed.checkVisibility({ checkOpacity: true }) &&
+      alphaOf(style.color) !== 0;
+    if (!shown) return text;
+  }
+  return null;
+}`;
+
+const CUT_OFF_BY_UNSCROLLABLE = `function () {
+  const unscrollable = (overflow) => overflow === "hidden" || overflow === "clip";
+  const clippers = [];
+  for (let at = this.parentElement; at !== null; at = at.parentElement) {
+    const style = getComputedStyle(at);
+    const x = unscrollable(style.overflowX);
+    const y = unscrollable(style.overflowY);
+    if (!x && !y) continue;
+    at.scrollLeft = 0;
+    at.scrollTop = 0;
+    clippers.push({ at, x, y });
+  }
+  const lines = Array.from(this.getClientRects()).filter((rect) => rect.width > 0 && rect.height > 0);
+  return clippers.some(({ at, x, y }) => {
+    const box = at.getBoundingClientRect();
+    const left = box.left + at.clientLeft;
+    const top = box.top + at.clientTop;
+    return lines.some(
+      (rect) =>
+        (x && (rect.left < left - ${EDGE_TOLERANCE_PX} || rect.right > left + at.clientWidth + ${EDGE_TOLERANCE_PX})) ||
+        (y && (rect.top < top - ${EDGE_TOLERANCE_PX} || rect.bottom > top + at.clientHeight + ${EDGE_TOLERANCE_PX})),
+    );
+  });
+}`;
+
+const judgeReach = Effect.fn("judgeReach")(function* (dom: Dom, element: Resolved, found: string[]) {
+  const unshown = yield* callOn(dom, element.id, FIRST_UNSHOWN_TEXT);
+  if (typeof unshown === "string") {
+    found.push(`${label(element)} hides its text "${normaliseText(unshown).slice(0, LABEL_CHARS)}"`);
+    return 0;
+  }
+  yield* evaluate(dom.cdp, "window.scrollTo(0, 0)");
+  if ((yield* callOn(dom, element.id, CUT_OFF_BY_UNSCROLLABLE)) === true) found.push(`${label(element)} is cut off by a container that cannot be scrolled`);
+  yield* attempt("cannot scroll an element into view", () => dom.cdp.send("DOM.scrollIntoViewIfNeeded", { backendNodeId: element.id }));
+  const viewport = yield* viewportOf(dom.cdp);
+  if (viewport.scrollX > 0) found.push(`${label(element)} is reachable only by scrolling the page sideways`);
+  const rects = yield* lineRects(dom, element.id);
+  for (const rect of rects) found.push(...(yield* judgeLine(dom, viewport, element, rect)));
+  if ((yield* callOn(dom, element.id, CLIPS_ITS_OWN_TEXT)) === true) found.push(`${label(element)} clips its own text`);
+  return rects.length;
+});
+
+export const judgeLayout = Effect.fn("judgeLayout")(function* (cdp: CDPSession, targets: readonly Target[]) {
+  const found: string[] = [];
+  const viewport = yield* viewportOf(cdp);
+  if (viewport.contentWidth > viewport.width + EDGE_TOLERANCE_PX) {
+    found.push(`the page is ${viewport.contentWidth}px wide in a ${viewport.width}px viewport`);
+  }
+  const dom = yield* readDom(cdp);
+  const { elements, parked } = yield* resolveTargets(dom, targets);
+  yield* findOverlaps(dom, elements, found);
+  const scanned: Scanned[] = [];
+  for (const element of elements) {
+    const lines = yield* judgeReach(dom, element, found);
+    scanned.push({ name: element.name, text: element.text, lines });
+  }
+  return { found, scanned, parked } satisfies LayoutReport;
+});

package/src/quality/browser/motion.ts

@@ -0,0 +1,85 @@
+import { Effect, Schema } from "effect";
+import type { BrowserContext, Page } from "playwright-core";
+import { attempt, BrowserFailure } from "./page.ts";
+
+const CONTROLS = "a[href], button, summary, input, select, textarea";
+
+const HOVER_TIMEOUT_MS = 2_000;
+
+// 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;
+
+const MOTION_RECORDER = `(() => {
+  const seen = new WeakSet();
+  const started = [];
+  const scan = () => {
+    for (const animation of document.getAnimations()) {
+      if (seen.has(animation)) continue;
+      seen.add(animation);
+      if ((animation.effect?.getComputedTiming().activeDuration ?? 0) <= ${FRAME_MS}) continue;
+      started.push(animation.animationName ?? animation.transitionProperty ?? "a scripted animation");
+    }
+  };
+  const everyFrame = () => {
+    scan();
+    requestAnimationFrame(everyFrame);
+  };
+  requestAnimationFrame(everyFrame);
+  window.__takeStartedAnimations = () => {
+    scan();
+    return started.splice(0);
+  };
+})()`;
+
+const decodeStarted = Schema.decodeUnknownEffect(Schema.Array(Schema.String));
+
+export function recordMotion(context: BrowserContext): Promise<unknown> {
+  return context.addInitScript(MOTION_RECORDER);
+}
+
+const takeStartedAnimations = Effect.fn("takeStartedAnimations")(function* (page: Page) {
+  const started: unknown = yield* attempt("cannot read the motion recorder", () => page.evaluate("window.__takeStartedAnimations()"));
+  return yield* decodeStarted(started).pipe(
+    Effect.mapError(() => new BrowserFailure({ message: `the motion recorder gave ${String(started)}, so it did not run before the page opened` })),
+  );
+});
+
+type StillnessReport = {
+  readonly found: readonly string[];
+  readonly controls: number;
+  readonly unhovered: number;
+};
+
+export const judgeStillness = Effect.fn("judgeStillness")(function* (page: Page) {
+  const found: string[] = [];
+  const animatedDuring = Effect.fn("animatedDuring")(function* (moment: string) {
+    const started = yield* takeStartedAnimations(page);
+    if (started.length > 0) found.push(`${started.join(", ")} animated ${moment}`);
+  });
+  yield* animatedDuring("during load");
+  const scrollBehavior: unknown = yield* attempt("cannot read the scroll behaviour", () => page.evaluate("getComputedStyle(document.documentElement).scrollBehavior"));
+  if (scrollBehavior === "smooth") found.push("the page scrolls smoothly");
+  const controls = page.locator(CONTROLS);
+  const count = yield* attempt("cannot count the controls", () => controls.count());
+  let judged = 0;
+  let unhovered = 0;
+  for (let index = 0; index < count; index += 1) {
+    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)),
+    );
+    if (hovered) {
+      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}`);
+    } else {
+      unhovered += 1;
+    }
+    yield* attempt(`cannot focus control ${index + 1}`, () => control.focus());
+    yield* animatedDuring(`on focusing control ${index + 1}`);
+  }
+  return { found, controls: judged, unhovered } satisfies StillnessReport;
+});

package/src/quality/browser/nesting.ts

@@ -0,0 +1,23 @@
+import { Effect } from "effect";
+import type { Page } from "playwright-core";
+import { attempt } from "./page.ts";
+
+const CONTENT_MODEL = "element-permitted-content";
+
+type NestingReport = {
+  readonly found: readonly string[];
+  readonly elements: number;
+};
+
+// The rendered DOM rather than the served file, so markup a script builds is judged too.
+export const judgeNesting = Effect.fn("judgeNesting")(function* (page: Page) {
+  const { HtmlValidate } = yield* attempt("cannot load html-validate, which a product that runs the nesting check installs beside the kit", () =>
+    import("html-validate"),
+  );
+  const html = yield* attempt("cannot read the rendered page", () => page.content());
+  const elements = yield* attempt("cannot count the elements", () => page.locator("*").count());
+  const validator = new HtmlValidate({ rules: { [CONTENT_MODEL]: "error" } });
+  const { results } = yield* attempt("html-validate cannot judge the page", () => validator.validateString(html));
+  const found = results.flatMap(({ messages }) => messages.map(({ line, column, message }) => `${message} at ${line}:${column} of the rendered page`));
+  return { found, elements } satisfies NestingReport;
+});