@fusion.dev/helix-cli 0.223.0 → 0.224.0

package/README.md

@@ -31,7 +31,7 @@ helix mcp init --client claude
 | `scan` | Reads your project's stylesheets, templates, and modules, and prints each finding with its file and line. `--build <dir>` weighs each Helix family in your bundle, `--out <path>` writes the run to the CI file, `--config <path>` names the settings, `--file <path>` reports one file's findings, and `--stdin <language>` checks a snippet |
 | `api` | Looks up the installed Helix packages: `find` a family, a `family`'s API, an `example` with its imports, the `imports` for a list of tags, and `tokens` |
 | `manifest` | `diff` compares two custom elements manifests and prints each difference. Exits 1 on any difference |
-| `visual` | Pictures each page in a real browser and compares it with a baseline kept in git: `test`, `update` the baselines, open the `report`, and `compare` two PNG files. Reads `visual.config.ts`, and needs Playwright installed. [The guide](https://github.com/project-fusion/fusion/blob/main/helix/cli/npm/visual/README.md) has the config and the GitHub Action |
+| `visual` | Pictures each page in a real browser and compares it with a baseline kept in git: `test`, `update` the baselines, open the `report`, and `compare` two PNG files. Reads `visual.config.ts`, and needs Playwright installed. [The guide](https://github.com/project-fusion/fusion/blob/main/helix/cli/npm/visual/README.md), also in this package at `visual/README.md`, has the config and the GitHub Action |
 | `mcp` | Serves the same lookups, the scan, and the theme derivation to an agent over stdio, as an MCP server. `mcp init --client <client>` writes the configuration for Claude Code, Cursor, VS Code, Gemini CLI, opencode, Roo Code, or Junie |
 
 `--json` is on every verb, in a shape a script can read without parsing

package/bin.mjs

@@ -231,12 +231,11 @@ const run = (binary) => {
 }
 
 /**
- * What a build here asks cargo for: the selection `rs:build` and CI build,
- * the workspace without the desktop app's shell. The shell links the system's
- * webview, which a machine building only the command lines may not have: on
- * CI's runner its `glib-sys` found no `glib-2.0` and every rule check failed.
+ * What a build here asks cargo for: the selection `rs:build` and CI build, the
+ * whole workspace. Kept in one place, so the build this runs and the build
+ * `rs:build` runs unify the same features and neither undoes the other's work.
  */
-const SELECTION = ['--workspace', '--exclude', 'fusion-hartley-desktop']
+const SELECTION = ['--workspace']
 
 /* **In this repository, cargo is asked first, and asking is cheap.** A binary
    under `target/` is whatever the last build left, so after an edit to a rule,

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@fusion.dev/helix-cli",
   "description": "The Helix command line, for a workspace that reaches it through npm, and the visual tests it runs.",
-  "version": "0.223.0",
+  "version": "0.224.0",
   "license": "MIT",
-  "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
+  "author": "Fusion Development Group",
   "repository": {
     "directory": "helix/cli/npm",
     "type": "git",
@@ -30,7 +30,7 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-templates": "0.223.0"
+    "@fusion.dev/helix-templates": "0.224.0"
   },
   "homepage": "https://fusion.dev",
   "keywords": [
@@ -44,11 +44,11 @@
     "visual-regression"
   ],
   "optionalDependencies": {
-    "@fusion.dev/helix-cli-darwin-arm64": "0.223.0",
-    "@fusion.dev/helix-cli-darwin-x64": "0.223.0",
-    "@fusion.dev/helix-cli-linux-arm64": "0.223.0",
-    "@fusion.dev/helix-cli-linux-x64": "0.223.0",
-    "@fusion.dev/helix-cli-win32-x64": "0.223.0"
+    "@fusion.dev/helix-cli-darwin-arm64": "0.224.0",
+    "@fusion.dev/helix-cli-darwin-x64": "0.224.0",
+    "@fusion.dev/helix-cli-linux-arm64": "0.224.0",
+    "@fusion.dev/helix-cli-linux-x64": "0.224.0",
+    "@fusion.dev/helix-cli-win32-x64": "0.224.0"
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": ">=0.132",
@@ -63,6 +63,6 @@
     }
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   }
 }

package/visual/README.md

@@ -16,7 +16,14 @@ npx playwright install --with-deps chromium
 
 Capture runs in Playwright, which you install beside the command line. The
 rest of `helix` needs no browser, so Playwright is an optional peer, and
-`helix visual test` names it when it is missing.
+`helix visual test` names it when it is missing. A config in TypeScript needs
+Node 22.18 or later. On an older Node, write it as `visual.config.mjs`.
+
+**On macOS and Windows, a run skips until you choose where baselines are taken.**
+`test` and `update` say so, compare nothing, and exit 0, because text draws
+differently on each platform. Take baselines on Linux, as
+[Baselines on Linux](#baselines-on-linux) shows, or set `platform: 'any'` to
+compare on the machine in front of you.
 
 ## Commands
 
@@ -81,6 +88,85 @@ the report's `run.json`, `report` prints the last one, `accept` prints what it
 wrote and what it left, and `compare` prints whether the two pictures match and
 how many pixels differ.
 
+## Picture a site
+
+Picture a production build, because a dev server draws its own overlays, and they
+differ from run to run. `visual.config.ts`, for a Next.js site:
+
+```ts
+import { defineConfig } from '@fusion.dev/helix-cli/visual'
+
+export default defineConfig({
+  sources: [
+    {
+      baselines: 'visual/baselines',
+      kind: 'server',
+      name: 'site',
+      routes: ['/', '/pricing', { name: 'not-found', path: '/nope', status: 404 }],
+      start: 'npm run start -- --port 3100',
+      url: 'http://localhost:3100',
+    },
+  ],
+})
+```
+
+```sh
+npm run build
+npx helix visual update
+```
+
+`update` writes the baselines and the fingerprint, and its report shows each
+picture it wrote. Look at them, commit them, and run `helix visual test` from then
+on. Build before each run, since `start` serves the last build. Any page that
+answers 400 or above fails the entry, unless its route names that `status`.
+
+## Pages that draw late
+
+A page can look finished before it is: a map's tiles arrive after the page loads.
+Name a selector that matches once it has drawn, and the run waits for it after each
+load. The entry fails when nothing matches within `settle.timeout`, 30 seconds
+unless you set it.
+
+```ts
+settle: { selector: '[data-map-ready]', timeout: 60 },
+```
+
+A route can name its own `selector`, for a page the others do not resemble:
+`{ path: '/map', selector: '[data-map-ready]' }`.
+
+**Requests to other hosts are refused**, and the run names each host in its log and
+in `run.json`, under `refused`. A page that draws from another host needs one of
+these:
+
+- **`network: { allow: ['tiles.example.com', '*.example.org'] }`** lets those hosts
+  through. A baseline then records what they returned, and a host that changes its
+  pictures fails the run.
+- **`network: 'open'`** lets every host through, with the same result.
+- **`mask`** paints over the content and needs no network. It paints over the
+  element's whole box and anything drawn on top of it, so name the smallest element
+  that holds the content. The run names a mask that matches nothing on a page, or
+  only elements with no box, such as an element with `display: contents`.
+- **`style`** applies a stylesheet while each picture is taken, to hide an element
+  that a mask would paint too much around.
+
+A clock on the page, such as "4 minutes ago", changes on its own. Mask that element.
+
+## Baselines on Linux
+
+Linux is the default, so a Mac can take baselines in Playwright's image. Install
+inside the container, which fetches the command's Linux binary, use the image that
+matches your Playwright version, and add `--platform linux/amd64` when your CI runs
+on x86-64:
+
+```sh
+docker run --rm -v "$PWD":/work -v /work/node_modules -w /work \
+  mcr.microsoft.com/playwright:v1.64.1-noble \
+  sh -c 'npm ci && npm run build && npx helix visual update'
+```
+
+The fingerprint records the image's browser and fonts, so CI has to run in the same
+image.
+
 ## The config
 
 `visual.config.ts`, in the directory you run `helix visual` from:
@@ -118,8 +204,9 @@ export default defineConfig({
   - `pairs` compares two renders of each entry with each other, described below.
 
   The three on a server take its `url`, a `start` command that runs only when
-  nothing answers there and is stopped when the run ends, and `baselines`, the
-  directory their baselines are written in. An `html` source reads every file
+  nothing answers there and is stopped when the run ends, `timeout`, the seconds
+  to wait for it to answer, 120 unless you set it, and `baselines`, the directory
+  their baselines are written in. An `html` source reads every file
   its `glob` matches under `root`. `{name}` is the path segment that names the
   entry, `*` matches within a segment, and `**` matches any number of
   directories. Each file is pictured inside a document that links `styles`,
@@ -133,9 +220,14 @@ export default defineConfig({
 - **`serve`**: URL paths served from disk, relative to the config. A path that
   ends in `/` serves a directory.
 - **`settle.readyProperty`**: a property your elements carry holding a promise
-  that resolves once they have rendered. `helix visual` awaits it before each shot.
-  `settle.elements` limits the custom elements a run waits for to one tag
-  prefix, for a framework that writes hyphenated tags it never defines.
+  that resolves once they have rendered. `helix visual` awaits it before each shot,
+  for 5 seconds, and then names the tags still waiting and takes the picture.
+- **`settle.selector`** and **`settle.timeout`**: what a page matches once it has
+  drawn, and how long to wait for it. See [Pages that draw late](#pages-that-draw-late).
+- **`settle.elements`**: limits the custom elements a run waits for to one tag
+  prefix, for a framework that writes hyphenated tags it never defines, such as
+  Angular's component tags. A tag a script gives a shadow root while nothing defines
+  it is a plain host, and is never waited for.
 - **`aria`**: keeps each entry's accessibility snapshot, Playwright's
   `ariaSnapshot()` of its page, beside its baselines as `<stem>.aria.yml`, and
   compares it as text, so a lost label fails even when no pixel moved. A
@@ -220,6 +312,8 @@ export default defineConfig({
 - **`retake`**: a sentence telling your team how to retake baselines, printed
   when a run fails.
 - **`fingerprint`**, **`network`**, and **`platform`** are described below.
+- **`baselines`**: on a server source, the directory its baselines are written
+  in, relative to the config.
 
 ## Pairs
 
@@ -259,7 +353,8 @@ picture is committed.
   element to be defined, the fonts to load, each element's ready promise, and
   the page's boxes and scroll offsets to stay the same for three frames. It
   emulates reduced motion and takes the shot with animations disabled. A font
-  that fails to load fails the entry.
+  file that fails to load fails the entry. A face with only `local()` sources has
+  no file to load, and the page draws the next family in its stack.
 - **One page load for each width an entry is pictured at.** Shots at the same
   width change the color scheme and the harness style on the same page, in the
   order the config lists them. A shot at a new width loads the page again, so
@@ -275,11 +370,17 @@ picture is committed.
   read the same, apart from where they are and each element's `id`, are one
   group: a token change that moved one kind of element across 300 pictures is
   one group of 300. No model is involved.
+- **A page that answers an error is not pictured.** A status of 400 or above, or a
+  page that does not load, fails the entry, in `test` and in `update`. No baseline
+  is written.
 - **Requests stay on the harness origin.** Every request to another host is
-  refused, so a baseline never records what another server returned.
-  `network: 'open'` turns that off.
+  refused, so a baseline never records what another server returned, and the run
+  names each refused host. `network: { allow: [...] }` lets some hosts through, and
+  `network: 'open'` lets every host through.
 - **Baselines are taken and compared on Linux.** On another platform `helix
-  visual test` says so and exits 0. `platform: 'any'` compares wherever it runs.
+  visual test` and `helix visual update` say so, compare nothing, and exit 0.
+  `platform: 'any'` compares wherever it runs, and baselines taken that way hold
+  only on that platform.
 - **The environment is recorded.** `helix visual update` of every entry
   writes `visual.fingerprint.json`: the platform, the operating system release, the
   browser version, and a hash of the installed fonts. A run on an environment
@@ -321,7 +422,7 @@ Every `helix visual test` and `helix visual update` writes a report into the con
 `report` directory: `index.html` to look at, and `run.json` for a program to
 read. The page shows each shot that failed with its baseline, its capture, and
 its difference side by side, and a swipe between the baseline and the capture.
-It lists the shots that needed a second take, the exceptions with their
+After an `update`, it shows each picture the run wrote. It lists the shots that needed a second take, the exceptions with their
 measurements, and what was skipped. The directory is emptied at the start of
 each run.
 

package/visual/driver.mjs

@@ -48,6 +48,7 @@ import { extname, resolve, sep } from 'node:path'
 import { StringDecoder } from 'node:string_decoder'
 import { pathToFileURL } from 'node:url'
 import { boxesOf, readPage } from './checks.mjs'
+import { allowed, unanswered, unloadable } from './words.mjs'
 
 /** The `id` of the harness `<style>` the binary writes into every page. */
 const STYLE_ID = 'helix-visual-harness'
@@ -110,6 +111,8 @@ const TYPES = {
 
 /** The run's state, filled in by the requests in the order they come. */
 const state = {
+  /** Hosts requests may reach besides the origins, with `network: { allow }`. */
+  allow: [],
   browser: undefined,
   config: undefined,
   /**
@@ -236,19 +239,47 @@ const respond = (request, response) => {
  */
 const upgrades = (page, prefix) =>
   page.evaluate(
-    async ({ prefix, seconds }) => {
+    async ({ PLAIN_HOSTS, prefix, seconds }) => {
+      const hosts = globalThis[Symbol.for(PLAIN_HOSTS)]
       const pending = [
         ...new Set([...document.querySelectorAll(':not(:defined)')].map((one) => one.localName)),
-      ].filter((tag) => tag.startsWith(prefix))
+      ].filter((tag) => tag.startsWith(prefix) && !hosts?.has(tag))
       await Promise.race([
         Promise.all(pending.map((tag) => customElements.whenDefined(tag))),
         new Promise((done) => setTimeout(done, seconds * 1000)),
       ])
       return pending.filter((tag) => customElements.get(tag) === undefined)
     },
-    { prefix: prefix ?? '', seconds: UPGRADES },
+    { PLAIN_HOSTS, prefix: prefix ?? '', seconds: UPGRADES },
   )
 
+/** Where a page keeps the tags {@link notePlainHosts} saw. */
+const PLAIN_HOSTS = 'fusion.dev/helix/visual/plain-hosts'
+
+/**
+ * Notes each tag a script gives a shadow root while nothing defines it.
+ *
+ * **A plain host is waiting for no definition.** Next.js puts its route
+ * announcer in `<next-route-announcer>` and its dev overlay in
+ * `<nextjs-portal>` this way, and no framework that does this ever registers
+ * the tag. An element waiting for a definition has no shadow root yet, or has
+ * one its HTML declared, which calls nothing, so a page whose bundle failed to
+ * load still fails. A definition's own constructor runs with the tag already
+ * registered, so it is never noted.
+ */
+const notePlainHosts = (context) =>
+  context.addInitScript((key) => {
+    const hosts = new Set()
+    globalThis[Symbol.for(key)] = hosts
+    const attach = Element.prototype.attachShadow
+    Element.prototype.attachShadow = function (...options) {
+      if (customElements.get(this.localName) === undefined) {
+        hosts.add(this.localName)
+      }
+      return attach.apply(this, options)
+    }
+  }, PLAIN_HOSTS)
+
 /**
  * **How long a page has to define its elements after it loads: twenty
  * seconds**, a third of what one shot may take. The bound only stops a run
@@ -261,8 +292,9 @@ const upgrades = (page, prefix) =>
 const UPGRADES = 20
 
 /**
- * Waits for the page to hold still: three frames, the fonts, each element's
- * own ready signal, then boxes and scroll offsets unchanged for three frames.
+ * Waits for the page to hold still: three frames, the fonts, every image,
+ * each element's own ready signal, then boxes and scroll offsets unchanged for
+ * three frames.
  *
  * **Three frames, because a framework may render in a task of its own** and
  * an example that sets state in an effect needs the render after it.
@@ -271,7 +303,15 @@ const UPGRADES = 20
  * library that publishes a promise for "rendered and styled" knows better
  * than any frame count. Without it, Fusion's `pagination/footer` differed by
  * 419 pixels on one run and 842 on the next from the same two files.
- * Bounded, so an element that never resolves cannot hang the run.
+ * Bounded, so an element that never resolves cannot hang the run, and the tags
+ * still waiting at the bound come back, for the run to name.
+ *
+ * **Every picture loaded, lazy ones included.** A whole-page picture is taken
+ * without scrolling, so an image marked `loading="lazy"` below the first
+ * screen was never asked for, and the site's home page was baselined with an
+ * empty app window for as long as it had one. Each is switched to eager, and
+ * the wait is for every image to load and decode, or fail, bounded at ten
+ * seconds so an image that never answers cannot hang the run.
  *
  * **Then geometry and scroll held for three frames**, which `animations:
  * 'disabled'` does not cover. A programmatic smooth scroll is no animation:
@@ -286,12 +326,26 @@ const still = (page, readyProperty) =>
       requestAnimationFrame(() => requestAnimationFrame(() => requestAnimationFrame(done))),
     )
     await Promise.race([document.fonts.ready, new Promise((done) => setTimeout(done, 10000))])
+    const images = [...document.images]
+    for (const image of images) {
+      if (image.loading === 'lazy') {
+        image.loading = 'eager'
+      }
+    }
+    await Promise.race([
+      Promise.all(images.map((image) => image.decode().catch(() => {}))),
+      new Promise((done) => setTimeout(done, 10000)),
+    ])
+    const late = new Set()
     if (readyProperty) {
       await Promise.race([
         Promise.all(
           [...document.querySelectorAll('*')]
-            .map((one) => one[readyProperty])
-            .filter((one) => one instanceof Promise),
+            .filter((one) => one[readyProperty] instanceof Promise)
+            .map((one) => {
+              late.add(one.localName)
+              return one[readyProperty].then(() => late.delete(one.localName))
+            }),
         ),
         new Promise((done) => setTimeout(done, 5000)),
       ])
@@ -310,8 +364,62 @@ const still = (page, readyProperty) =>
       held = now === last ? held + 1 : 0
       last = now
     }
+    return [...late]
   }, readyProperty ?? null)
 
+/**
+ * Waits for what `settle.selector` or a route's `selector` names, which is how a
+ * page says it has drawn what no frame count can see, such as a map's tiles.
+ * It waits for the element to be in the document, since a host with
+ * `display: contents` is never visible. Giving up fails the entry, because a
+ * picture taken anyway is a baseline of the page before it was ready.
+ */
+const awaited = async (page, selector, seconds) => {
+  try {
+    await page
+      .locator(selector)
+      .first()
+      .waitFor({ state: 'attached', timeout: seconds * 1000 })
+  } catch (caught) {
+    if (caught?.name !== 'TimeoutError') {
+      throw caught
+    }
+    /* A page drawing WebGL in software can hold its main thread for minutes, and
+       the wait polls there: BlocNav's map marked itself ready at 4.8 seconds and
+       answered at 142. So the page is asked once more, and this waits for its
+       answer, within what `bounded` allows the entry. */
+    if ((await page.locator(selector).count()) > 0) {
+      return
+    }
+    throw new Error(
+      `the selector \`${selector}\` matched nothing after ${seconds} seconds, so nothing was pictured`,
+    )
+  }
+}
+
+/**
+ * What each mask painted on this page: `painted`, `no box` when it matches only
+ * elements with no area, such as a host with `display: contents`, or `nothing`.
+ * Playwright paints over a box, so the last two leave the picture as it was.
+ */
+const maskStates = (page) =>
+  Promise.all(
+    state.mask.map(async (selector) => [
+      selector,
+      await page.locator(selector).evaluateAll((elements) => {
+        if (elements.length === 0) {
+          return 'nothing'
+        }
+        return elements.some((one) => {
+          const box = one.getBoundingClientRect()
+          return box.width > 0 && box.height > 0
+        })
+          ? 'painted'
+          : 'no box'
+      }),
+    ]),
+  )
+
 /**
  * `promise`, or a refusal after `seconds`.
  *
@@ -443,6 +551,46 @@ const restore = async (page, state) => {
   }
 }
 
+/**
+ * The families of the faces a page failed to load, in the page.
+ *
+ * **A face with only `local()` sources has nothing to download.** `next/font`
+ * writes a fallback as `src: local("Arial")`, and Linux has no Arial, so its
+ * status is `error` on the platform baselines are taken on, and the page draws
+ * the next family in its stack, as it is written to. A sheet the page cannot
+ * read leaves a face judged by its status alone. A family with a file among its
+ * faces has something to download, so its failure stands.
+ */
+const unloadedFaces = () => {
+  const localOnly = new Set()
+  const downloaded = new Set()
+  const rulesOf = (sheet) => {
+    try {
+      return [...sheet.cssRules]
+    } catch {
+      return []
+    }
+  }
+  const walk = (rules) => {
+    for (const rule of rules) {
+      if (rule instanceof CSSFontFaceRule) {
+        const family = rule.style.getPropertyValue('font-family').replace(/["']/g, '')
+        const faces = rule.style.getPropertyValue('src').includes('url(') ? downloaded : localOnly
+        faces.add(family)
+      } else if (rule.cssRules) {
+        walk([...rule.cssRules])
+      }
+    }
+  }
+  for (const sheet of document.styleSheets) {
+    walk(rulesOf(sheet))
+  }
+  return [...document.fonts]
+    .filter((face) => face.status === 'error')
+    .map((face) => face.family.replace(/["']/g, ''))
+    .filter((family) => !localOnly.has(family) || downloaded.has(family))
+}
+
 /** One entry, every shot of it from one navigation. */
 const take = async (lane, item, { elements, readyProperty }, progress) => {
   const { page } = lane
@@ -455,8 +603,14 @@ const take = async (lane, item, { elements, readyProperty }, progress) => {
   let aria = null
   /* The color schemes contrast has been read in. */
   const read = new Set()
+  /* What each mask painted, the best of the shots, since one element may hide
+     at one width. */
+  const masks = new Map()
+  /* The tags still holding an unresolved ready promise at the bound. */
+  const unready = new Set()
   lane.errors.length = 0
   lane.messages.length = 0
+  lane.refused.clear()
   /* The width the page was last loaded at. */
   let loaded
   try {
@@ -472,17 +626,25 @@ const take = async (lane, item, { elements, readyProperty }, progress) => {
         const address =
           item.url ??
           `${state.origin}${item.path}?visual=${encodeURIComponent(item.key)}${index > 0 ? `&shot=${index}` : ''}`
-        await page.goto(address, { waitUntil: 'load' })
+        const answered = await page.goto(address, { waitUntil: 'load' })
+        const refused = unanswered(answered?.status(), item.status, address)
+        if (refused !== undefined) {
+          throw new Error(refused)
+        }
         loaded = shot.width
         const missing = await upgrades(page, elements)
         if (missing.length > 0) {
           throw new Error(
-            `nothing defines ${missing.map((tag) => `<${tag}>`).join(', ')}, after ${UPGRADES} seconds of waiting`,
+            `nothing defines ${missing.map((tag) => `<${tag}>`).join(', ')}, after ${UPGRADES} seconds of waiting. If a framework writes that tag and never defines it, set \`settle.elements\` to the prefix of the custom elements you do define`,
           )
         }
         if (item.state) {
           await restore(page, item.state)
         }
+        if (item.selector) {
+          progress.stage = `waiting for ${item.selector}`
+          await awaited(page, item.selector, item.wait)
+        }
       } else if (shot.harness !== null) {
         await page.evaluate(
           ([id, rules]) => {
@@ -495,12 +657,12 @@ const take = async (lane, item, { elements, readyProperty }, progress) => {
         )
       }
       progress.stage = `settling for ${shot.name}`
-      await still(page, readyProperty)
+      for (const tag of await still(page, readyProperty)) {
+        unready.add(tag)
+      }
       /* A face the page asked for and could not load draws in the platform's
          fallback, and a baseline taken that way defends the wrong face. */
-      const broken = await page.evaluate(() =>
-        [...document.fonts].filter((face) => face.status === 'error').map((face) => face.family),
-      )
+      const broken = await page.evaluate(unloadedFaces)
       if (broken.length > 0) {
         throw new Error(`the font ${[...new Set(broken)].join(', ')} did not load`)
       }
@@ -508,6 +670,12 @@ const take = async (lane, item, { elements, readyProperty }, progress) => {
          frame and finishes finite ones, so a picture is of one definite moment:
          Fusion's spinner moved 17 pixels between two takes without it. */
       progress.stage = `capturing ${shot.name}`
+      for (const [selector, drew] of await maskStates(page)) {
+        const before = masks.get(selector)
+        if (before !== 'painted' && !(before === 'no box' && drew === 'nothing')) {
+          masks.set(selector, drew)
+        }
+      }
       /* A masked element is painted over in one fixed color, so what changes
          on its own, a version number, moves no pixel. */
       const png = await page.screenshot({
@@ -583,10 +751,13 @@ const take = async (lane, item, { elements, readyProperty }, progress) => {
     errors: item.errors ? [...lane.errors] : [],
     findings,
     key: item.key,
+    masks: [...masks].filter(([, drew]) => drew !== 'painted'),
     op: 'item',
     painted,
     problems,
+    refused: [...lane.refused],
     seconds,
+    unready: [...unready],
   })
 }
 
@@ -607,7 +778,7 @@ const PER_SHOT = 60
  */
 const bounded = async (lane, item, settle) => {
   const progress = { abandoned: false, stage: 'starting' }
-  const limit = PER_SHOT * item.shots.length
+  const limit = PER_SHOT * item.shots.length + (item.wait ?? 0)
   let timer
   const expired = new Promise((done) => {
     timer = setTimeout(() => done(true), limit * 1000)
@@ -640,6 +811,13 @@ const listened = (lane, page) => {
     }
   })
   page.on('pageerror', (caught) => lane.errors.push(caught.message))
+  /* What the browser itself blocked, a policy of the page's among it, beside
+     what the run refused. */
+  page.on('requestfailed', (request) => {
+    if (request.failure()?.errorText.includes('BLOCKED')) {
+      lane.refused.add(request.url())
+    }
+  })
   return page
 }
 
@@ -664,18 +842,27 @@ const lanes = async (count) => {
       viewport: { height: 800, width: 1280 },
     })
     await askForState(context)
+    await notePlainHosts(context)
+    const lane = { errors: [], messages: [], refused: new Set() }
     if (state.network === 'origin') {
       await context.route('**/*', (route) => {
-        let origin
+        const asked = route.request().url()
+        let url
         try {
-          origin = new URL(route.request().url()).origin
+          url = new URL(asked)
         } catch {
-          origin = undefined
+          url = undefined
+        }
+        if (
+          url !== undefined &&
+          (state.origins.has(url.origin) || allowed(url.hostname, state.allow))
+        ) {
+          return route.continue()
         }
-        return state.origins.has(origin) ? route.continue() : route.abort()
+        lane.refused.add(asked)
+        return route.abort()
       })
     }
-    const lane = { errors: [], messages: [] }
     lane.page = listened(lane, await context.newPage())
     state.lanes.push(lane)
   }
@@ -714,7 +901,12 @@ const handlers = {
   },
 
   async config({ path }) {
-    const loaded = await import(pathToFileURL(path).href)
+    let loaded
+    try {
+      loaded = await import(pathToFileURL(path).href)
+    } catch (caught) {
+      throw new Error(unloadable(path, caught, process.version))
+    }
     const config = loaded.default ?? loaded.config
     if (config === null || typeof config !== 'object') {
       throw new Error(`${path} exports no config: export one as the default`)
@@ -835,7 +1027,17 @@ const handlers = {
     })
   },
 
-  async start({ hide = [], mask = [], network, origins = [], serve, style = null, workers }) {
+  async start({
+    allow = [],
+    hide = [],
+    mask = [],
+    network,
+    origins = [],
+    serve,
+    style = null,
+    workers,
+  }) {
+    state.allow = allow
     state.hide = hide
     state.mask = mask
     state.style = style ?? undefined

package/visual/index.d.ts

@@ -101,12 +101,27 @@ interface Served {
   url: string
 }
 
+/** A route with something to say about itself. */
+export interface Route {
+  /** The name its baselines take. Taken from `path` when not given. */
+  name?: string
+  /** The route's path on the server. */
+  path: string
+  /** Waited for on this route, in place of `settle.selector`. */
+  selector?: string
+  /**
+   * The status the route answers on purpose, such as 404 for a not-found page. Any other answer
+   * fails it. When not given, any status of 400 or above fails it.
+   */
+  status?: number
+}
+
 /** Pages of any server, by route or from its sitemap. */
 export interface ServerSource extends Served {
   /** Picks this source out of the others. */
   kind: 'server'
-  /** Routes to picture, each a path or a path and the name its baselines take. `/` is named `index`. */
-  routes?: (string | { name: string; path: string })[]
+  /** Routes to picture, each a path or a {@link Route}. `/` is named `index`. */
+  routes?: (string | Route)[]
   /** A sitemap's path on the server, `/sitemap.xml`, whose every route is pictured too. */
   sitemap?: string
 }
@@ -350,11 +365,16 @@ export interface Config {
   /**
    * Selectors whose elements are painted over in one fixed color in every picture and left out of every
    * accessibility snapshot, for what changes on its own and says nothing about the page, such as a version
-   * number or a date.
+   * number or a date. A mask paints over its elements' boxes and whatever is drawn over them, and a run
+   * names a mask that matches nothing on a page or only elements with no box.
    */
   mask?: string[]
-  /** `origin` refuses every request off the harness origin, and is the default. `open` lets them through. */
-  network?: 'open' | 'origin'
+  /**
+   * `origin` refuses every request off the harness origin, and is the default. `open` lets them
+   * through. `{ allow }` refuses them but those to the hosts it lists, each a host or `*.` and a
+   * domain. A run names every request it refused, in its log and in `run.json`.
+   */
+  network?: 'open' | 'origin' | { allow: string[] }
   /** `linux` takes and compares baselines on Linux alone, and is the default. `any` compares wherever it runs. */
   platform?: 'any' | 'linux'
   /** Where each run writes its report and `run.json`, relative to the config. `.helix/visual` when not given. */
@@ -367,12 +387,25 @@ export interface Config {
   settle?: {
     /**
      * Only custom elements whose tag starts with this are awaited, and one left undefined fails the
-     * entry. Set it for a framework that writes hyphenated tags of its own, such as Next.js's
-     * `next-route-announcer`. Every custom element when not given.
+     * entry. Set it for a framework that writes hyphenated tags and never defines them, such as
+     * Angular's component tags. Every custom element when not given, except a tag a script gave a
+     * shadow root while nothing defined it, which is a plain host, as Next.js's
+     * `next-route-announcer` is.
      */
     elements?: string
-    /** A property each element may carry holding a promise that resolves when it has rendered. */
+    /**
+     * A property each element may carry holding a promise that resolves when it has rendered. A run
+     * waits 5 seconds, then names the tags still waiting and takes the picture.
+     */
     readyProperty?: string
+    /**
+     * A selector that matches once a page has drawn what it draws late, such as a map's tiles, for a
+     * page that sets an attribute or adds an element when it is done. Each entry waits for it after
+     * it loads, and fails when nothing matches in time.
+     */
+    selector?: string
+    /** Seconds to wait for `selector`. 30 when not given. */
+    timeout?: number
   }
   /** How `--shard` packs entries into shards. */
   shard?: {

package/visual/words.mjs

@@ -0,0 +1,41 @@
+/**
+ * The driver's sentences that depend only on what they are given, apart from
+ * the driver, which starts reading its standard input as soon as it is imported.
+ */
+
+/**
+ * Why a config could not be imported, with what to do when the reason is that
+ * the runtime reads no TypeScript. Node strips types by default from 22.18 and
+ * 23.6, and an older one answers only with the file's extension.
+ */
+export const unloadable = (path, caught, runtime) => {
+  const said = caught instanceof Error ? caught.message : String(caught)
+  if (caught?.code !== 'ERR_UNKNOWN_FILE_EXTENSION' || !/\.[cm]?ts$/.test(path)) {
+    return said
+  }
+  return `${said}. Node ${runtime} reads no TypeScript. Use Node 22.18 or later, or write the config as visual.config.mjs.`
+}
+
+/** Why a page's answer is no page to picture, or undefined when it is one. */
+export const unanswered = (status, expected, address) => {
+  if (status === undefined) {
+    return undefined
+  }
+  if (expected !== undefined && expected !== null) {
+    return status === expected
+      ? undefined
+      : `the page answered ${status} at ${address}, and its route names ${expected}, so nothing was pictured`
+  }
+  return status >= 400
+    ? `the page answered ${status} at ${address}, so nothing was pictured. A route that answers ${status} on purpose names it, as \`{ path, status: ${status} }\``
+    : undefined
+}
+
+/**
+ * Whether the network setting lets a request to `hostname` through: an entry
+ * is a host, or `*.` and a domain, which matches the hosts under the domain.
+ */
+export const allowed = (hostname, allow) =>
+  allow.some((entry) =>
+    entry.startsWith('*.') ? hostname.endsWith(entry.slice(1)) : hostname === entry,
+  )