@avi2dg/checks 0.61.0 → 0.62.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.62.0
+
+Released 2026-11-02.
+
+### Features
+
+- **testing:** picture one block at each screen size in chromium and webkit [#24](https://github.com/avi2d/checks/pull/24)
+
+## 0.61.1
+
+Released 2026-11-02.
+
+### Fixes
+
+- **changelog:** keep a release's section when its commit gets its tag [#23](https://github.com/avi2d/checks/pull/23)
+
 ## 0.61.0
 
 Released 2026-11-01.

package/README.md

@@ -41,6 +41,7 @@ A repository the kit holds ends with `checks-lint: <count> gate(s) pass`.
 | write every file the gates ask for | [Set up a repository](docs/how-to/set-up-a-repository.md) |
 | move to a newer release | [Upgrade the kit](docs/how-to/upgrade-the-kit.md) |
 | turn on the CSS checks | [Turn on the CSS families](docs/how-to/turn-on-the-css-families.md) |
+| picture one block at each screen size and approve its pictures | [Test the screens of one block](docs/how-to/test-a-blocks-screens.md) |
 | look up a gate or a bin | [The bins](docs/bins.md) |
 | look up a shared config | [Native settings](docs/configs/native-settings.md) |
 | find a file the package ships | [The shipped files](docs/shipped-files.md) |

package/docs/design.md

@@ -84,11 +84,12 @@ 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.
 
-Seven `exports` keys name a path the file does not sit at, because consumers resolve them by that name.
+Eight `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/screen-sizes.ts` points at `src/quality/browser/screen-sizes.ts`, whose sizes a product imports.
+`@avi2dg/checks/block-screens.ts` points at `src/testing/block-screens.ts`, whose screenshot suite a product's pixel tests call.
 `@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.
 
@@ -114,7 +115,7 @@ A shell reaches it through `bun run`, which never falls back to the registry the
 The `.ts` bins keep a `bun` shebang and need no build step, unlike the oxlint plugins that Node loads.
 
 The bins are written in Effect.
-So `effect` is a peer dependency, and `@effect/platform-bun`, which only the bins use, is a dependency.
+So `effect` is a peer dependency, and `@effect/platform-bun`, which the bins and the block screenshot helper use, is a dependency.
 The Stryker test order helper runs under Node, so it takes its services from `@effect/platform-node-shared`, which is a direct dependency.
 That dependency also pins its version.
 `@effect/platform-bun` asks for it with a `^` range, so a newer minor of it could resolve and peer on a newer `effect` than the exact version consumers install.

package/docs/gates/checks-browser.md

@@ -162,6 +162,7 @@ Each size in a set is a viewport named for its device and its size, with `device
 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.
 A product's own code takes the sizes by importing `SCREEN_SIZES`, `screenSizeName` and `ENLARGED_TEXT_PX` from `@avi2dg/checks/screen-sizes.ts`.
+A block's screenshot suite runs at the same sizes, as [Test the screens of one block](../how-to/test-a-blocks-screens.md) says.
 
 <!-- generated screen-sizes: bun run build writes it from SCREEN_SIZES in src/quality/browser/screen-sizes.ts and scripts/doc-blocks.ts -->
 

package/docs/gates/checks-changelog.md

@@ -27,6 +27,8 @@ It finds releases in the version bumps of `package.json` across all of `HEAD` an
 It reads a commit whose `package.json` is missing or has no version as unversioned, so the commit that adds the version is the first release and a repository that adopts a version late still writes its changelog.
 A bump to a version no newer than the release before it is a revert.
 A revert cancels every release above the version it returns to, except a release a `v` tag marks as published.
+A `v` tag publishes only the newest bump of its version that the tagged commit reaches.
+So a version bumped again after a cancel keeps its cancelled bump cancelled, and the tag leaves the changelog unchanged.
 A version older than the newest in the committed `CHANGELOG.md` and absent from it was never published, so its commits go into the next release.
 It refuses a shallow checkout, since the releases reach back past its history.
 It refuses a `package.json` with no repository address, since each entry links its pull request under it.

package/docs/how-to/test-a-blocks-screens.md

@@ -0,0 +1,81 @@
+---
+kind: how-to
+audience: consumers
+---
+# Test the screens of one block
+
+A repository owner follows these steps to picture one block at the kit's screen sizes in Chromium and WebKit, and to approve its pictures.
+
+## Before you begin
+
+- `playwright-core` installed at the version the kit's `package.json` lists among its `peerDependencies`.
+- Playwright's Chromium headless shell and WebKit, installed with `bunx playwright-core install --with-deps chromium-headless-shell webkit`.
+- A `test:pixel` script set to `checks-test --tier=pixel`, as [checks-test-layout](../gates/checks-test-layout.md) says.
+
+## Add a suite
+
+To add a suite for one block:
+
+1. Write a test file for Chromium under `tests/pixel/`, named for the block and the engine:
+
+   ```ts
+   import { join } from "node:path";
+   import { blockScreens } from "@avi2dg/checks/block-screens.ts";
+
+   blockScreens("chromium", {
+     block: "footer",
+     fixtures: join(import.meta.dir, "..", "fixtures", "footer-screens"),
+     url: "http://localhost:4321/",
+     selector: ".footer",
+   });
+   ```
+
+1. Write the same file for `"webkit"` beside it.
+1. Add `*.new.png` to `.gitignore`.
+1. Run `bun run test:pixel`, which fails at each size until its first pictures are approved.
+1. Approve them as [Approve new pictures](#approve-new-pictures) says.
+
+`blockScreens` registers one test for each size, and each test opens the page in a fresh browser context for its device.
+It waits for the fonts and every running animation that ends, runs `setup` and takes the picture with animations stopped.
+
+| Key | What it takes |
+| --- | --- |
+| `block` | the name each test opens with |
+| `fixtures` | the folder of approved pictures, which holds one folder for each engine |
+| `url` | the page that shows the block, or a function that returns a promise of it |
+| `selector` | the element in the picture, which is the whole window when the key is left out |
+| `setup` | a function that gets the page after it settles and before its picture, such as one that opens a menu |
+| `sizes` | `anchor`, the default, or `full`, the sets [Screen sizes](../gates/checks-browser.md#screen-sizes) lists |
+| `devices` | more devices of the repository's own, each made with `emulatedDevice` or `windowDevice` |
+| `tolerance` | `channel`, how far a color channel may move before its pixel counts as changed, and `share`, the share of pixels that may change, both 0 when the key is left out |
+| `timeoutMs` | how long each size may take, 60 seconds when the key is left out |
+
+Each picture is compared with `<fixtures>/<engine>/<device>.png`, where the device name is lowercased and each run of other characters becomes one hyphen, as in `iphone-se-375x667.png`.
+A phone picture comes from a phone the kit emulates, such as an iPhone SE at 375 by 667.
+A picture that differs from its approved picture, or that has none, fails its test.
+The failure names the device, its size and the engine, and the new picture is written beside the approved one as `<device>.new.png`.
+A picture that matches removes any `.new.png` beside it.
+
+## Approve new pictures
+
+To approve the pictures of a block that changed on purpose:
+
+1. Run `bun run test:pixel` and look at each `.new.png` it writes.
+1. Run `APPROVE_SCREENS=1 bun run test:pixel`, which replaces each approved picture with the new one and removes its `.new.png`.
+1. Look at every changed file in the fixtures folder before you commit it.
+
+Approve mode passes every size, so it runs only once each new picture looks right.
+
+## Build a suite from the parts
+
+A repository whose test already opens the page uses the parts `blockScreens` is built from:
+
+1. Take the devices from `screenDevices("anchor")`, and add the repository's own with `emulatedDevice` or `windowDevice`.
+1. Open each page in a browser context with the device's `options`.
+1. Wait with `settled(page)`, and take the picture with `pictureOf(page, selector)`.
+1. Pass the picture to `matchesApproved(picture, { fixtures, engine, device, tolerance })`, which resolves to `AS_APPROVED` or to the failure, and expect `AS_APPROVED`.
+
+## Related topics
+
+- [checks-browser](../gates/checks-browser.md)
+- [checks-test-layout](../gates/checks-test-layout.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.61.0",
+  "version": "0.62.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "author": {
     "name": "avi2d",
@@ -50,6 +50,7 @@
     "src/delivery/release-tagging.ts",
     "src/delivery/github.ts",
     "src/testing/test-layout.ts",
+    "src/testing/block-screens.ts",
     "src/testing/test.ts",
     "src/testing/test-skips.ts",
     "src/core/swc.ts",
@@ -144,6 +145,7 @@
     "./browser-hooks.ts": "./src/quality/browser/hooks.ts",
     "./browser-checks.json": "./src/quality/browser/browser-checks.json",
     "./screen-sizes.ts": "./src/quality/browser/screen-sizes.ts",
+    "./block-screens.ts": "./src/testing/block-screens.ts",
     "./oxlint": {
       "types": "./dist/presets/oxlint.d.ts",
       "default": "./dist/presets/oxlint.js"

package/src/delivery/changelog-write.ts

@@ -64,9 +64,26 @@ const readBumps = Effect.fn("readBumps")(function* (root: string) {
   return bumps;
 });
 
-const readPublished = Effect.fn("readPublished")(function* (root: string) {
+const reaches = (root: string, ancestor: string, descendant: string) =>
+  git(["merge-base", "--is-ancestor", ancestor, descendant], root).pipe(
+    Effect.as(true),
+    Effect.catchTag("GitFailure", () => Effect.succeed(false)),
+  );
+
+// A tag publishes the newest bump of its version that it reaches, so a cancelled older bump of that version stays cancelled.
+const readPublishedShas = Effect.fn("readPublishedShas")(function* (root: string, bumps: readonly Bump[]) {
   const tags = yield* git(["for-each-ref", "--format=%(refname:strip=2)", `refs/tags/${TAG_PREFIX}*`], root);
-  return new Set(tags.split("\n").flatMap((tag) => (tag.startsWith(TAG_PREFIX) ? [tag.slice(TAG_PREFIX.length)] : [])));
+  const published = new Set<string>();
+  for (const tag of tags.split("\n").filter((line) => line.startsWith(TAG_PREFIX))) {
+    const version = tag.slice(TAG_PREFIX.length);
+    for (const bump of bumps.filter((one) => one.version === version).toReversed()) {
+      if (yield* reaches(root, bump.sha, `refs/tags/${tag}`)) {
+        published.add(bump.sha);
+        break;
+      }
+    }
+  }
+  return published;
 });
 
 const mergedTips = Effect.fn("mergedTips")(function* (root: string, through: string) {
@@ -78,11 +95,7 @@ const mergedTips = Effect.fn("mergedTips")(function* (root: string, through: str
   for (const [, ...parents] of merges.split("\n").filter((line) => line !== "").map((line) => line.split(" "))) {
     for (const parent of parents) {
       // A parent past the bump belongs to a later release, so only a parent beside it joins this one.
-      const past = yield* git(["merge-base", "--is-ancestor", through, parent], root).pipe(
-        Effect.as(true),
-        Effect.catchTag("GitFailure", () => Effect.succeed(false)),
-      );
-      if (!past) tips.push(parent);
+      if (!(yield* reaches(root, through, parent))) tips.push(parent);
     }
   }
   return tips;
@@ -113,7 +126,8 @@ const write = Effect.gen(function* () {
   }
   const recorded = (yield* fs.exists(target)) ? releaseDates(yield* fs.readFileString(target)) : new Map<string, string>();
   const pending = version === (yield* versionAt(root, "HEAD")) ? undefined : { sha: "HEAD", version, date: yield* today };
-  const released = cuts(yield* readBumps(root), recorded, yield* readPublished(root), pending);
+  const bumps = yield* readBumps(root);
+  const released = cuts(bumps, recorded, yield* readPublishedShas(root, bumps), pending);
   const tip = released.at(-1);
   const extra = tip === undefined || tip.through === "HEAD" ? [] : yield* mergedTips(root, tip.through);
   const found = (yield* Effect.forEach(released, (cut, index) => subjectsOf(root, cut, index === released.length - 1 ? extra : [])))

package/src/delivery/changelog.ts

@@ -57,12 +57,13 @@ function entryOf(subject: string, repositoryUrl: string): Entry | undefined {
 }
 
 // A bump not newer than the release before it is a revert: it cancels every release above the version it
-// returns to, except a published one.
-function standing(bumps: readonly Bump[], published: ReadonlySet<string>): readonly Bump[] {
+// returns to, except a published one. A version cancelled and bumped again holds two bumps, so a bump is
+// published by its sha and never by its version.
+function standing(bumps: readonly Bump[], publishedShas: ReadonlySet<string>): readonly Bump[] {
   return bumps.reduce<readonly Bump[]>((kept, bump) => {
     const before = kept.at(-1);
     if (before === undefined || Bun.semver.order(bump.version, before.version) === 1) return [...kept, bump];
-    return kept.filter(({ version }) => published.has(version) || Bun.semver.order(version, bump.version) !== 1);
+    return kept.filter(({ sha, version }) => publishedShas.has(sha) || Bun.semver.order(version, bump.version) !== 1);
   }, []);
 }
 
@@ -71,11 +72,11 @@ function standing(bumps: readonly Bump[], published: ReadonlySet<string>): reado
 export function cuts(
   bumps: readonly Bump[],
   recorded: ReadonlyMap<string, string>,
-  published: ReadonlySet<string>,
+  publishedShas: ReadonlySet<string>,
   pending: Bump | undefined,
 ): readonly Cut[] {
   const newest = [...recorded.keys()].toSorted(Bun.semver.order).at(-1);
-  const candidates = standing(pending === undefined ? bumps : [...bumps, pending], published);
+  const candidates = standing(pending === undefined ? bumps : [...bumps, pending], publishedShas);
   const released = candidates.filter(
     ({ version }, index) =>
       index === candidates.length - 1 || newest === undefined || recorded.has(version) || Bun.semver.order(version, newest) !== -1,

package/src/testing/block-screens.ts

@@ -0,0 +1,286 @@
+import { BunServices } from "@effect/platform-bun";
+import { afterAll, expect, test } from "bun:test";
+import { Config, Effect, FileSystem, Path, Schema } from "effect";
+import { chromium, devices, webkit, type Browser, type Page } from "playwright-core";
+import { SCREEN_SIZES, screenSizeName, type ScreenSize, type ScreenSizeSet } from "../quality/browser/screen-sizes.ts";
+
+export const SCREEN_ENGINES = ["chromium", "webkit"] as const;
+
+export type ScreenEngine = (typeof SCREEN_ENGINES)[number];
+
+export type Viewport = { readonly width: number; readonly height: number };
+
+export type DeviceOptions = {
+  readonly userAgent?: string;
+  readonly deviceScaleFactor: number;
+  readonly isMobile: boolean;
+  readonly hasTouch: boolean;
+  readonly viewport: Viewport;
+  readonly screen: Viewport;
+};
+
+export type ScreenDevice = { readonly name: string; readonly options: DeviceOptions };
+
+type Devices = typeof devices;
+
+export type DeviceDescriptor = keyof { [Name in keyof Devices as string extends Name ? never : Name]: Devices[Name] };
+
+const sized = (label: string, { width, height }: Viewport): string => `${label} ${String(width)}x${String(height)}`;
+
+export function emulatedDevice(label: string, descriptor: DeviceDescriptor, viewport: Viewport, deviceScaleFactor?: number): ScreenDevice {
+  const { userAgent, isMobile, hasTouch, ...described } = devices[descriptor];
+  return {
+    name: sized(label, viewport),
+    options: { userAgent, deviceScaleFactor: deviceScaleFactor ?? described.deviceScaleFactor, isMobile, hasTouch, viewport, screen: viewport },
+  };
+}
+
+export const windowDevice = (viewport: Viewport): ScreenDevice => emulatedDevice("desktop", "Desktop Chrome", viewport);
+
+const IPHONES: Readonly<Partial<Record<string, { readonly label: string; readonly descriptor: DeviceDescriptor }>>> = {
+  "phone-375x667": { label: "iPhone SE", descriptor: "iPhone SE (3rd gen)" },
+  "phone-393x852": { label: "iPhone 15 and 16", descriptor: "iPhone 16" },
+};
+
+function sizeDevice(size: ScreenSize): ScreenDevice {
+  const viewport = { width: size.width, height: size.height };
+  const iphone = IPHONES[screenSizeName(size)];
+  if (iphone !== undefined) return emulatedDevice(iphone.label, iphone.descriptor, viewport);
+  switch (size.device) {
+    case "phone":
+      return emulatedDevice("Android", "Pixel 7", viewport);
+    case "tablet":
+      return { name: sized("iPad", viewport), options: { viewport, screen: viewport, deviceScaleFactor: 2, isMobile: true, hasTouch: true } };
+    case "desktop":
+      return windowDevice(viewport);
+  }
+}
+
+export const screenDevices = (set: ScreenSizeSet): readonly ScreenDevice[] => SCREEN_SIZES[set].map(sizeDevice);
+
+export const pictureFile = (engine: ScreenEngine, device: ScreenDevice): string =>
+  `${engine}/${device.name.toLowerCase().replaceAll(/[^a-z0-9]+/g, "-")}.png`;
+
+class PictureFailure extends Schema.TaggedError<PictureFailure>()("PictureFailure", {
+  message: Schema.String,
+}) {}
+
+type Picture = { readonly width: number; readonly height: number; readonly rgb: Uint8Array };
+
+const PNG_SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10];
+const CHANNELS_OF_COLOR_TYPE: Readonly<Partial<Record<number, number>>> = { 0: 1, 2: 3, 4: 2, 6: 4 };
+
+type Header = { readonly width: number; readonly height: number; readonly channels: number };
+
+type Chunks = { readonly header: Header; readonly deflated: Uint8Array<ArrayBuffer> };
+
+const chunksOf = (png: Uint8Array): Chunks | string => {
+  if (!PNG_SIGNATURE.every((byte, at) => png[at] === byte)) return "it is not a PNG";
+  const view = new DataView(png.buffer, png.byteOffset, png.byteLength);
+  const data: Uint8Array[] = [];
+  let header: Header | string = "it has no IHDR chunk";
+  for (let at = PNG_SIGNATURE.length; at + 8 <= png.length; ) {
+    const length = view.getUint32(at);
+    const type = String.fromCharCode(...png.subarray(at + 4, at + 8));
+    const body = png.subarray(at + 8, at + 8 + length);
+    if (type === "IHDR") header = headerOf(new DataView(body.buffer, body.byteOffset, body.byteLength));
+    if (type === "IDAT") data.push(body);
+    at += 12 + length;
+  }
+  return typeof header === "string" ? header : { header, deflated: joined(data) };
+};
+
+const headerOf = (view: DataView): Header | string => {
+  const [depth, colorType, interlace] = [view.getUint8(8), view.getUint8(9), view.getUint8(12)];
+  const channels = CHANNELS_OF_COLOR_TYPE[colorType];
+  if (depth !== 8 || channels === undefined || interlace !== 0) return `it is a ${String(depth)}-bit PNG of color type ${String(colorType)} with interlace ${String(interlace)}, and only 8-bit gray, RGB and RGBA without interlace decode`;
+  return { width: view.getUint32(0), height: view.getUint32(4), channels };
+};
+
+const joined = (parts: readonly Uint8Array[]): Uint8Array<ArrayBuffer> => {
+  const whole = new Uint8Array(parts.reduce((length, part) => length + part.length, 0));
+  parts.reduce((at, part) => (whole.set(part, at), at + part.length), 0);
+  return whole;
+};
+
+const paeth = (left: number, up: number, upLeft: number): number => {
+  const [leftDistance, upDistance, upLeftDistance] = [Math.abs(up - upLeft), Math.abs(left - upLeft), Math.abs(left + up - 2 * upLeft)];
+  if (leftDistance <= upDistance && leftDistance <= upLeftDistance) return left;
+  return upDistance <= upLeftDistance ? up : upLeft;
+};
+
+const PREDICTORS: readonly ((left: number, up: number, upLeft: number) => number)[] = [
+  () => 0,
+  (left) => left,
+  (_left, up) => up,
+  (left, up) => Math.floor((left + up) / 2),
+  paeth,
+];
+
+type Row = { readonly filtered: Uint8Array; readonly raw: Uint8Array; readonly row: number; readonly stride: number; readonly channels: number };
+
+const unfilterRow = ({ filtered, raw, row, stride, channels }: Row): string | undefined => {
+  const predict = PREDICTORS[filtered[row * (stride + 1)] ?? 0];
+  if (predict === undefined) return `row ${String(row)} names an unknown filter`;
+  for (let at = 0; at < stride; at += 1) {
+    const here = row * stride + at;
+    const left = at < channels ? 0 : (raw[here - channels] ?? 0);
+    const up = row === 0 ? 0 : (raw[here - stride] ?? 0);
+    const upLeft = row === 0 || at < channels ? 0 : (raw[here - stride - channels] ?? 0);
+    raw[here] = ((filtered[row * (stride + 1) + 1 + at] ?? 0) + predict(left, up, upLeft)) & 0xff;
+  }
+  return undefined;
+};
+
+const unfiltered = (filtered: Uint8Array, { width, height, channels }: Header): Uint8Array | string => {
+  const stride = width * channels;
+  if (filtered.length < height * (stride + 1)) return "its image data ends early";
+  const raw = new Uint8Array(stride * height);
+  for (let row = 0; row < height; row += 1) {
+    const failed = unfilterRow({ filtered, raw, row, stride, channels });
+    if (failed !== undefined) return failed;
+  }
+  return raw;
+};
+
+const rgbOf = (raw: Uint8Array, { width, height, channels }: Header): Uint8Array => {
+  const rgb = new Uint8Array(width * height * 3);
+  for (let pixel = 0; pixel < width * height; pixel += 1) {
+    for (let channel = 0; channel < 3; channel += 1) rgb[pixel * 3 + channel] = raw[pixel * channels + (channels < 3 ? 0 : channel)] ?? 0;
+  }
+  return rgb;
+};
+
+const inflated = (deflated: Uint8Array<ArrayBuffer>) =>
+  Effect.tryPromise({
+    try: () => new Response(new Blob([deflated]).stream().pipeThrough(new DecompressionStream("deflate"))).bytes(),
+    catch: (cause) => new PictureFailure({ message: `its image data does not inflate: ${String(cause)}` }),
+  });
+
+export const decodePng = Effect.fn("decodePng")(function* (png: Uint8Array) {
+  const chunks = chunksOf(png);
+  if (typeof chunks === "string") return yield* new PictureFailure({ message: chunks });
+  const raw = unfiltered(yield* inflated(chunks.deflated), chunks.header);
+  if (typeof raw === "string") return yield* new PictureFailure({ message: raw });
+  return { width: chunks.header.width, height: chunks.header.height, rgb: rgbOf(raw, chunks.header) } satisfies Picture;
+});
+
+export type Tolerance = {
+  readonly channel: number;
+  readonly share: number;
+};
+
+export const EXACT: Tolerance = { channel: 0, share: 0 };
+
+const differingPixels = (now: Picture, then: Picture, channel: number): number => {
+  let differing = 0;
+  for (let at = 0; at < now.rgb.length; at += 3) {
+    const moved = [0, 1, 2].some((offset) => Math.abs((now.rgb[at + offset] ?? 0) - (then.rgb[at + offset] ?? 0)) > channel);
+    if (moved) differing += 1;
+  }
+  return differing;
+};
+
+const mismatch = (now: Picture, then: Picture, { channel, share }: Tolerance): string | undefined => {
+  if (now.width !== then.width || now.height !== then.height)
+    return `is ${String(now.width)}x${String(now.height)} and the approved picture is ${String(then.width)}x${String(then.height)}`;
+  const differing = differingPixels(now, then, channel);
+  return differing <= Math.floor(now.width * now.height * share) ? undefined : `has ${String(differing)} pixel(s) that differ from the approved picture`;
+};
+
+export type ApprovalMode = "compare" | "approve";
+
+export const APPROVE_VARIABLE = "APPROVE_SCREENS";
+
+const modeFromEnvironment = Config.Boolean(APPROVE_VARIABLE).pipe(
+  Config.withDefault(false),
+  Config.map((approving): ApprovalMode => (approving ? "approve" : "compare")),
+);
+
+export type PictureAt = {
+  readonly fixtures: string;
+  readonly engine: ScreenEngine;
+  readonly device: ScreenDevice;
+  readonly tolerance?: Tolerance;
+};
+
+export const AS_APPROVED = "the picture is as approved";
+
+const judged = Effect.fn("judged")(function* (picture: Uint8Array, at: PictureAt, given: ApprovalMode | undefined) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const approved = path.join(at.fixtures, pictureFile(at.engine, at.device));
+  const fresh = approved.replace(/\.png$/, ".new.png");
+  const shown = (file: string): string => path.relative(process.cwd(), file);
+  const forget = fs.remove(fresh, { force: true });
+  const keep = (why: string) =>
+    fs.writeFile(fresh, picture).pipe(Effect.as(`${at.device.name} in ${at.engine}: ${why}, so the new picture is at ${shown(fresh)}`));
+  yield* fs.makeDirectory(path.dirname(approved), { recursive: true });
+  if ((given ?? (yield* modeFromEnvironment)) === "approve") return yield* fs.writeFile(approved, picture).pipe(Effect.andThen(forget), Effect.as(AS_APPROVED));
+  if (!(yield* fs.exists(approved))) return yield* keep(`no approved picture is at ${shown(approved)}`);
+  const [now, then] = yield* Effect.all([decodePng(picture), Effect.flatMap(fs.readFile(approved), decodePng)]);
+  const found = mismatch(now, then, at.tolerance ?? EXACT);
+  return yield* found === undefined ? forget.pipe(Effect.as(AS_APPROVED)) : keep(`the picture ${found} at ${shown(approved)}`);
+});
+
+export const matchesApproved = (picture: Uint8Array, at: PictureAt, mode?: ApprovalMode): Promise<string> =>
+  Effect.runPromise(judged(picture, at, mode).pipe(Effect.provide(BunServices.layer)));
+
+const PICTURE_OPTIONS = { scale: "css", animations: "disabled", caret: "hide" } as const;
+
+export const pictureOf = (page: Page, selector?: string): Promise<Uint8Array> =>
+  selector === undefined ? page.screenshot(PICTURE_OPTIONS) : page.locator(selector).screenshot(PICTURE_OPTIONS);
+
+const SETTLED = `document.fonts.ready.then(() => Promise.all(document.getAnimations().filter((animation) => animation.playState !== "paused" && animation.timeline === document.timeline && animation.effect?.getTiming().iterations !== Infinity).map((animation) => animation.finished))).then(() => undefined)`;
+
+export const settled = (page: Page): Promise<unknown> => page.evaluate(SETTLED);
+
+const LAUNCHERS = {
+  // Headless shell snaps glyph advances to whole pixels, so a picture would not match one from a full Chromium.
+  chromium: () => chromium.launch({ args: ["--font-render-hinting=none"] }),
+  webkit: () => webkit.launch(),
+} as const satisfies Record<ScreenEngine, () => Promise<Browser>>;
+
+export type BlockSuite = {
+  readonly block: string;
+  readonly fixtures: string;
+  readonly url: string | (() => Promise<string>);
+  readonly selector?: string;
+  readonly setup?: (page: Page) => Promise<unknown>;
+  readonly sizes?: ScreenSizeSet;
+  readonly devices?: readonly ScreenDevice[];
+  readonly tolerance?: Tolerance;
+  readonly timeoutMs?: number;
+};
+
+const blockPicture = (browser: Browser, suite: BlockSuite, device: ScreenDevice): Promise<Uint8Array> =>
+  browser.newContext(device.options).then((context) =>
+    context
+      .newPage()
+      .then((page) =>
+        (typeof suite.url === "string" ? Promise.resolve(suite.url) : suite.url())
+          .then((url) => page.goto(url, { waitUntil: "networkidle" }))
+          .then(() => settled(page))
+          .then(() => suite.setup?.(page))
+          .then(() => pictureOf(page, suite.selector)),
+      )
+      .finally(() => context.close()),
+  );
+
+export function blockScreens(engine: ScreenEngine, suite: BlockSuite): void {
+  let launched: Promise<Browser> | undefined;
+  afterAll(() => launched?.then((browser) => browser.close()));
+  for (const device of [...screenDevices(suite.sizes ?? "anchor"), ...(suite.devices ?? [])]) {
+    test(
+      `${suite.block} at ${device.name} in ${engine} looks as approved, instead of changing its look with no picture approving it`,
+      () => {
+        launched ??= LAUNCHERS[engine]();
+        return launched
+          .then((browser) => blockPicture(browser, suite, device))
+          .then((picture) => matchesApproved(picture, { fixtures: suite.fixtures, engine, device, ...(suite.tolerance === undefined ? {} : { tolerance: suite.tolerance }) }))
+          .then((verdict) => expect(verdict).toBe(AS_APPROVED));
+      },
+      suite.timeoutMs ?? 60_000,
+    );
+  }
+}