@fusion.dev/helix-cli 0.187.0 → 0.189.0

package/README.md

@@ -1,8 +1,8 @@
 # @fusion.dev/helix-cli
 
 The Helix command line. Derives themes, scaffolds a project, checks a project's
-code against the Helix it installed, looks up the installed packages, and serves
-all of it to an agent.
+code against the Helix it installed, pictures its pages against baselines kept
+in git, looks up the installed packages, and serves all of it to an agent.
 
 ```sh
 npm install --save-dev @fusion.dev/helix-cli
@@ -22,11 +22,13 @@ helix mcp init --client claude
 
 | Verb | What it does |
 |---|---|
+| `component` | Checks the components you build on Helix's base classes: registration under your prefix, imports, slots, parts, states, hooks, words, reflection, attribute names, lifecycle, and listeners. Reads the folders named by `tiers` in `helix.json`. `--only <rule>` runs some of them |
 | `theme` | `init` a starter intent, `build` it to CSS, `audit` every contrast pair, `check` in CI |
 | `new` | Scaffolds a project from a Helix template |
-| `diagnostics` | Receives the runs `initDiagnostics()` sends from your app and prints each new finding. `--out <path>` writes the CI file, `--port` picks the port, 7417 by default, and `--config <path>` names the settings served to the page |
+| `diagnostics` | Receives the runs `initDiagnostics()` sends from your app and prints each new finding. `--once <url>` opens a page headless instead, diagnoses it, and exits. `--out <path>` writes the CI file, `--port` picks the port, 7417 by default, and `--config <path>` names the settings served to the page |
 | `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` |
+| `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 |
 | `mcp` | Serves the same lookups, the scan, and the theme derivation to an agent over stdio, as an MCP server. `mcp init --client claude\|cursor\|vscode` writes the client's configuration |
 
 `--json` is on every verb, in a shape a script can read without parsing

package/bin.mjs

@@ -145,8 +145,23 @@ const onPath = () => {
   return undefined
 }
 
+/**
+ * What `helix visual` needs to start its capture driver: the runtime that ran
+ * this shim, and the driver beside it. Set only where the caller has not set
+ * them, so `HELIX_VISUAL_RUNTIME=node bun run helix visual test` still means
+ * node.
+ */
+const DRIVER_ENV = {
+  ...process.env,
+  HELIX_VISUAL_DRIVER: process.env.HELIX_VISUAL_DRIVER ?? join(HERE, 'visual', 'driver.mjs'),
+  HELIX_VISUAL_RUNTIME: process.env.HELIX_VISUAL_RUNTIME ?? process.execPath,
+}
+
 const run = (binary) => {
-  const { status, error } = spawnSync(binary, process.argv.slice(2), { stdio: 'inherit' })
+  const { status, error } = spawnSync(binary, process.argv.slice(2), {
+    env: DRIVER_ENV,
+    stdio: 'inherit',
+  })
   /* A status means it ran. Bun sets `error` on any exit but zero, to a
      `SystemError` reading "null", so asking `error` alone reported every failed
      check as a binary that would not start, and exited 70 for its 1. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-cli",
-  "description": "The Helix command line, for a workspace that reaches it through npm.",
-  "version": "0.187.0",
+  "description": "The Helix command line, for a workspace that reaches it through npm, and the visual tests it runs.",
+  "version": "0.189.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -10,8 +10,17 @@
     "url": "git+https://github.com/project-fusion/fusion.git"
   },
   "type": "module",
+  "exports": {
+    "./bin.mjs": "./bin.mjs",
+    "./package.json": "./package.json",
+    "./visual": {
+      "types": "./visual/index.d.ts",
+      "default": "./visual/index.mjs"
+    }
+  },
   "files": [
-    "bin.mjs"
+    "bin.mjs",
+    "visual"
   ],
   "bin": {
     "helix": "./bin.mjs"
@@ -26,14 +35,25 @@
     "cli",
     "design-system",
     "scaffold",
-    "theme"
+    "theme",
+    "playwright",
+    "screenshot",
+    "visual-regression"
   ],
   "optionalDependencies": {
-    "@fusion.dev/helix-cli-darwin-arm64": "0.187.0",
-    "@fusion.dev/helix-cli-darwin-x64": "0.187.0",
-    "@fusion.dev/helix-cli-linux-arm64": "0.187.0",
-    "@fusion.dev/helix-cli-linux-x64": "0.187.0",
-    "@fusion.dev/helix-cli-win32-x64": "0.187.0"
+    "@fusion.dev/helix-cli-darwin-arm64": "0.189.0",
+    "@fusion.dev/helix-cli-darwin-x64": "0.189.0",
+    "@fusion.dev/helix-cli-linux-arm64": "0.189.0",
+    "@fusion.dev/helix-cli-linux-x64": "0.189.0",
+    "@fusion.dev/helix-cli-win32-x64": "0.189.0"
+  },
+  "peerDependencies": {
+    "playwright": ">=1.50"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
   },
   "publishConfig": {
     "access": "restricted"

package/visual/README.md

@@ -0,0 +1,211 @@
+# Visual tests
+
+`helix visual` takes pictures of your pages and components in a real browser,
+compares each one to a baseline kept in your git repository, and fails the run
+when a picture changes. It ships in `@fusion.dev/helix-cli`, and it pictures
+any web project, with Helix or without it.
+
+It pictures HTML files, any server's pages, Storybook stories, and entries from
+a JSON catalog, and it has a GitHub Action. What comes next is in the roadmap
+below.
+
+```sh
+npm install --save-dev @fusion.dev/helix-cli playwright
+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.
+
+## Commands
+
+```sh
+helix visual test                    compare every shot, and fail on a difference
+helix visual test button             only the entries named button
+helix visual update                  write only the baselines the comparison rejects
+helix visual test --shard 0 --of 4   the first of four shards, for CI
+helix visual report                  open the report of the last run
+helix visual compare a.png b.png     compare two PNG files, with no browser
+```
+
+- **`helix visual test`** pictures every entry and compares each shot with its
+  baseline. It exits 1 when a shot differs, changes size, has no baseline, or
+  cannot be taken, and writes an image of each difference beside its baseline,
+  named `<stem><suffix>.diff.png`. Add `*.diff.png` to your `.gitignore`.
+- **`helix visual update`** pictures every entry and writes a baseline only where the
+  comparison would fail. Review the files it writes before you commit them.
+- **`helix visual report`** opens the report the last run wrote. `--markdown` prints
+  its summary as Markdown instead, for a CI job's summary page.
+- **`helix visual compare`** compares two PNG files. `--diff` writes the image of the
+  difference, and `--threshold` sets how far apart two colors may be and still
+  count as the same pixel, from 0 to 1.
+
+Each run ends with one line that says what it compared and what it skipped.
+`--config` names the config file, `--workers` sets how many pages capture at
+once, and `--shard` with `--of` takes one shard of a run split across jobs.
+
+`helix --json visual …` prints one JSON document on stdout and moves the
+sentences to stderr: `test` and `update` print the run's record, the same as
+the report's `run.json`, `report` prints the last one, and `compare` prints
+whether the two pictures match and how many pixels differ.
+
+## The config
+
+`visual.config.ts`, in the directory you run `helix visual` from:
+
+```ts
+import { defineConfig } from '@fusion.dev/helix-cli/visual'
+
+export default defineConfig({
+  serve: { '/theme.css': 'dist/theme.css' },
+  shots: [
+    { name: 'wide', scheme: 'light', width: 1280 },
+    { name: 'phone', scheme: 'light', width: 390 },
+    { name: 'dark', scheme: 'dark', width: 1280 },
+  ],
+  sources: [
+    {
+      glob: '{name}/example.html',
+      kind: 'html',
+      name: 'components',
+      root: 'src',
+      styles: ['/theme.css'],
+    },
+  ],
+})
+```
+
+- **`sources`**: where the entries come from, four kinds:
+  - `html` reads every file its `glob` matches under `root`, described next.
+  - `server` pictures a server's `routes`, and every route its `sitemap` lists.
+    `/` is named `index`, and a route given as `{ name, path }` takes its name.
+  - `storybook` pictures every story in a running Storybook's `index.json`.
+    `include` and `exclude` filter them by tag.
+  - `catalog` pictures every `{ id, url }` in a JSON file, each `url` relative to
+    the server.
+
+  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
+  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`,
+  loads `scripts` with `defer`, and sets the color scheme, the background, the
+  text color, the width, and a 24-pixel inset on `body`. `harness: false`
+  pictures the file as it is. `files` answers a relative request from a page
+  with another file beside it, such as `{ 'styles.css': '{stem}.css' }`.
+- **`shots`**: the pictures taken of each entry. A wide width, a phone width,
+  and dark when you give none. Each baseline is written beside its entry as
+  `<stem>.<name>.png`, and `suffix` changes `.<name>`.
+- **`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.
+- **`diff`**: how a shot is compared, for the whole config or for one source.
+  `mode: 'pixel'` counts the pixels past `threshold`, 0.1 unless you set it,
+  and fails above `pixels`, 0 unless you set it. `mode: 'perceptual'` scores
+  structural similarity and fails below `ssim`, 0.99 unless you set it, for
+  photographs and gradients whose pixels move a shade on every render.
+- **`exceptions`**: each names an `entry`, optionally a `shot`, and a `reason`.
+  `unstable: true` skips the shot and names it in every run. `pixels` lets the
+  shot differ by that many, and the run fails once the shot stops differing, so
+  an exception that is no longer needed is removed.
+- **`inspect`**: `run` is called with the Playwright page after each entry's
+  first shot, and `report` once at the end with everything `run` returned.
+  `report` returns `{ failed: true }` to fail the run.
+- **`shard`**: `cost` maps entry names to measured seconds, so shards are packed
+  by time. Entries with no measurement weigh `perShot` seconds a shot.
+- **`timings`**: a file to write each entry name's seconds to, which is how you
+  measure `shard.cost`.
+- **`mask`**: selectors whose elements are painted over in one fixed color in
+  every picture, for what changes on its own, such as a version number.
+- **`style`**: a stylesheet applied while each picture is taken, to hold still
+  what `mask` cannot, such as a masked element whose width follows its text.
+- **`report`**: where each run writes its report, `.helix/visual` unless you
+  set it. Add `.helix/visual/` to your `.gitignore`.
+- **`retake`**: a sentence telling your team how to retake baselines, printed
+  when a run fails.
+- **`fingerprint`**, **`network`**, and **`platform`** are described below.
+
+## What every run does
+
+- **Capture holds still.** Before each shot `helix visual` waits for every custom
+  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.
+- **One page load for all the shots of an entry.** The viewport, the color
+  scheme, and the harness style change between shots on the same page.
+- **A difference is taken again from a fresh page load.** A shot that matches
+  on the second take passes, and the run names it.
+- **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.
+- **Baselines are taken and compared on Linux.** On another platform `helix
+  visual test` says so and exits 0. `platform: 'any'` compares wherever it runs.
+- **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
+  that differs stops and names what differs, because every picture would
+  differ for that reason alone.
+
+## The report
+
+Every `helix visual test` and `helix visual update` writes a report into the config's
+`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
+measurements, and what was skipped. The directory is emptied at the start of
+each run.
+
+## The GitHub Action
+
+The Action lives in the Fusion repository, in `helix/visual/action`.
+
+```yaml
+- uses: project-fusion/fusion/helix/visual/action@main
+  with:
+    mode: check
+```
+
+- **`mode: check`** installs Chromium and its system packages from the cache,
+  runs `helix visual test`, writes the summary to the job's summary page, and
+  on a failure uploads the report and the diff images.
+- **`mode: retake`** runs `helix visual update` and opens a pull request with
+  what it wrote, on a branch named for the ref. Give it `token` from a GitHub
+  App or a person: a pull request opened with `GITHUB_TOKEN` starts no checks.
+  Run it on `workflow_dispatch` only, with `concurrency` set to queue and never
+  cancel, so a retake is asked for and never cut in half.
+
+`args` passes arguments to `helix visual`, such as `--config` or `--shard`.
+`helix` and `playwright` name the commands that run each,
+`npx --no-install helix` and `npx --no-install playwright` unless you set them.
+
+## How it works
+
+- **Local-first.** `helix visual` runs on your machine and in your CI. It needs no
+  hosted service, and no picture leaves your machine unless you turn that on.
+- **Baselines in git.** Each baseline is a file in your repository. A retake
+  writes only the pictures the comparison rejects, and the pull request that
+  carries them is where you review the change.
+- **Three shots by default.** A wide width, a phone width, and the dark color
+  scheme, each compared to its own baseline.
+- **The environment is part of the baseline.** The browser version, the
+  operating system image, and the installed fonts are recorded beside the
+  baselines, and a run on a different environment stops and names what differs.
+- **A Rust core and a Playwright driver.** The `helix` binary reads the config,
+  finds what to picture, shards the work, decodes and compares the images, and
+  writes the report. Capture runs in a small Node driver that runs Playwright,
+  and the driver ships in `@fusion.dev/helix-cli`.
+
+## Roadmap
+
+| Phase | What it adds |
+|---|---|
+| 1. Core | `helix visual test` and `helix visual update` on plain HTML sources. The config file, the environment fingerprint, the pixel diff, exceptions with their measurements, deterministic shards, and capture that waits for the page to hold still, refuses requests to other origins, and takes all three shots from one page load |
+| 2. Ship | Server and Storybook sources, a perceptual diff, the HTML report behind `helix visual report`, the GitHub Action with its `check` and `retake` modes, documentation, and the first public `0.x` |
+| 3. Checks | Differential checks with no baseline, such as server rendering against client rendering. Page checks on the render that was pictured: unhighlighted code blocks, clipped text, overlapping elements, and contrast. Accessibility snapshots stored beside each picture, and each changed region traced to the elements under it |
+| 4. Triage | A model that groups and explains changes, only on a failed comparison and only when you configure one. Off by default, text-only first, local or hosted models, and a cost cap per run |
+| GitHub App | Opens the baselines pull request for a retake so your required checks run on it, without a token you create and store. Planned after phase 2 |

package/visual/driver.mjs

@@ -0,0 +1,660 @@
+/**
+ * The capture driver: the Node half of `helix visual`, which runs Playwright.
+ *
+ * **The binary starts this once per run and sends it one request per line**
+ * on standard input; every answer is one line of JSON on standard output.
+ * Standard error is the run's own. `console.log` is sent there, and the binary
+ * passes any other line on standard output that is not an answer through to
+ * standard error, so a config's `inspect` cannot corrupt the protocol.
+ *
+ * - `config` imports the config file and answers with its values. Functions
+ *   stay here, where they run.
+ * - `fetch` and `wait` ask a server for a page, or wait for it to answer, so
+ *   the binary needs no HTTP of its own.
+ * - `start` serves the harness origin and launches Chromium.
+ * - `capture` pictures entries, answering `shot` for each picture as it is
+ *   taken, `item` when an entry is done, and `captured` at the end.
+ * - `finish` hands the config's `inspect.report` every run it collected.
+ * - `diagnose` opens pages and runs the installed diagnostics in each, for
+ *   `helix diagnostics --once`.
+ * - `close` closes the browser and the server and exits.
+ *
+ * Any request that fails answers `error`, with the reason.
+ *
+ * **One navigation per entry for every shot.** The first shot loads the page;
+ * each later one resizes the viewport, switches the emulated scheme, rewrites
+ * the harness style and settles again. Measured on October 8, 2026 over 153
+ * pictures of 51 examples, that took 242.6 ms a picture against 287.3 ms for a
+ * navigation each, and every picture was pixel for pixel the same.
+ *
+ * **Node and Playwright, decided on October 8, 2026.** Chromium's work is about
+ * 94% of the time of a picture, so a capture written in Rust over the browser
+ * protocol is the same speed. It would also lose what Playwright already
+ * tests: auto-waiting, disabled animations, request routing, media emulation,
+ * `ariaSnapshot()`, Firefox and WebKit, and `playwright install --with-deps`.
+ */
+import { existsSync, readFileSync, readSync, statSync, writeSync } from 'node:fs'
+import { createServer } from 'node:http'
+import { extname, resolve, sep } from 'node:path'
+import { StringDecoder } from 'node:string_decoder'
+import { pathToFileURL } from 'node:url'
+
+/** The `id` of the harness `<style>` the binary writes into every page. */
+const STYLE_ID = 'helix-visual-harness'
+
+/** Where `diagnose` serves the diagnostics on a page's own origin. */
+const DIAGNOSTICS = '__helix-diagnostics'
+
+/* **Read and written synchronously, on the descriptors themselves.** Bun
+   1.1.43, the runtime Fusion's CI pins, hands a script nothing from a piped
+   standard input until the pipe closes, so a stream reader would wait for a
+   request the binary is waiting to have answered. `readSync` on descriptor 0
+   returns each line as it arrives, in Bun and in Node. A request is read only
+   when the last one is answered, which is the one time this has nothing else
+   to do. Answers are written with `writeSync` for the same reason: the next
+   thing after an answer is that blocking read, and an answer still queued
+   behind it would never reach the binary. */
+for (const name of ['debug', 'info', 'log']) {
+  console[name] = console.error
+}
+
+/** Blocks for `milliseconds`, for a descriptor that asked to be retried. */
+const pause = (milliseconds) =>
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds)
+
+/** One answer, written whole. */
+const say = (message) => {
+  const bytes = Buffer.from(`${JSON.stringify(message)}\n`)
+  for (let at = 0; at < bytes.length; ) {
+    try {
+      at += writeSync(1, bytes, at)
+    } catch (caught) {
+      if (caught?.code !== 'EAGAIN') {
+        throw caught
+      }
+      pause(2)
+    }
+  }
+}
+
+const TYPES = {
+  '.css': 'text/css',
+  '.gif': 'image/gif',
+  '.html': 'text/html',
+  '.jpeg': 'image/jpeg',
+  '.jpg': 'image/jpeg',
+  '.js': 'text/javascript',
+  '.json': 'application/json',
+  '.mjs': 'text/javascript',
+  '.mp4': 'video/mp4',
+  '.otf': 'font/otf',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.ttf': 'font/ttf',
+  '.webm': 'video/webm',
+  '.webp': 'image/webp',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+}
+
+/** The run's state, filled in by the requests in the order they come. */
+const state = {
+  browser: undefined,
+  config: undefined,
+  /**
+   * Each document by the key of the request that asked for it. Two takes of
+   * one entry can load at once on two pages, each styled for its own shot, so
+   * the document is named in the query and the path is the entry's.
+   */
+  documents: new Map(),
+  lanes: [],
+  /** Selectors painted over in every picture. */
+  mask: [],
+  network: 'origin',
+  origin: undefined,
+  /** The origins requests may reach: the harness's and each source's server. */
+  origins: new Set(),
+  /** `/source/name/` to the directory relative requests resolve in, and its renames. */
+  pages: new Map(),
+  /** What `inspect.run` returned for each entry, for `inspect.report`. */
+  runs: [],
+  serve: [],
+  server: undefined,
+  /** A stylesheet applied while each picture is taken. */
+  style: undefined,
+  workers: 1,
+}
+
+/**
+ * `relative` resolved inside `directory`, or undefined when it escapes it.
+ *
+ * The directory is resolved too, because a mount named with a trailing slash
+ * arrives as `fonts/`, and `fonts/` plus a separator is a prefix no file has.
+ */
+const inside = (directory, relative) => {
+  const root = resolve(directory)
+  const file = resolve(root, relative)
+  return file === root || file.startsWith(root + sep) ? file : undefined
+}
+
+/** What the server answers for `path`: a file, a document, or nothing. */
+const lookup = (path, document) => {
+  for (const { directory, file, url } of state.serve) {
+    if (directory && path.startsWith(url)) {
+      return { file: inside(file, path.slice(url.length)) }
+    }
+    if (!directory && path === url) {
+      return { file }
+    }
+  }
+  /* The page whose path is the longest prefix of this one, so a relative
+     request from a page resolves inside that page's directory. */
+  for (let at = path.lastIndexOf('/'); at >= 0; at = path.lastIndexOf('/', at - 1)) {
+    const page = state.pages.get(path.slice(0, at + 1))
+    if (page !== undefined) {
+      const rest = path.slice(at + 1)
+      if (rest === '') {
+        return { html: state.documents.get(document) }
+      }
+      return { file: inside(page.dir, page.files[rest] ?? rest) }
+    }
+    if (at === 0) {
+      break
+    }
+  }
+  return {}
+}
+
+const respond = (request, response) => {
+  let path
+  let document
+  try {
+    const url = new URL(request.url ?? '/', 'http://visual')
+    path = decodeURIComponent(url.pathname)
+    document = url.searchParams.get('visual')
+  } catch {
+    response.writeHead(400).end()
+    return
+  }
+  const found = lookup(path, document)
+  if (found.html !== undefined) {
+    response.writeHead(200, { 'content-type': 'text/html' })
+    response.end(found.html)
+    return
+  }
+  let body
+  try {
+    if (found.file === undefined || !statSync(found.file).isFile()) {
+      throw new Error('not a file')
+    }
+    body = readFileSync(found.file)
+  } catch {
+    response.writeHead(404).end()
+    return
+  }
+  response.writeHead(200, {
+    'content-type': TYPES[extname(found.file).toLowerCase()] ?? 'application/octet-stream',
+  })
+  response.end(body)
+}
+
+/**
+ * Waits for every custom element on the page to be defined, and names the
+ * tags nothing defines.
+ *
+ * **Bounded, because `whenDefined` on a tag nothing registers never settles.**
+ * Unbounded, a page naming an element the bundle does not define hangs the
+ * run with no output. This gives up after five seconds and names the tags.
+ */
+const upgrades = (page, prefix) =>
+  page.evaluate(async (prefix) => {
+    const pending = [
+      ...new Set([...document.querySelectorAll(':not(:defined)')].map((one) => one.localName)),
+    ].filter((tag) => tag.startsWith(prefix))
+    await Promise.race([
+      Promise.all(pending.map((tag) => customElements.whenDefined(tag))),
+      new Promise((done) => setTimeout(done, 5000)),
+    ])
+    return pending.filter((tag) => customElements.get(tag) === undefined)
+  }, prefix ?? '')
+
+/**
+ * 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.
+ *
+ * **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.
+ *
+ * **Each element's ready signal, when the config names one.** A component
+ * 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.
+ *
+ * **Then geometry and scroll held for three frames**, which `animations:
+ * 'disabled'` does not cover. A programmatic smooth scroll is no animation:
+ * `carousel/controlled` reported `scrollLeft` of 135, 184 and 239 on three
+ * loads. A control that measures itself settles a frame or two late, and
+ * `pagination/footer` measured 272, 273 and 275 wide. Bounded at 120 frames,
+ * so a page that never stops moving reports a difference and does not hang.
+ */
+const still = (page, readyProperty) =>
+  page.evaluate(async (readyProperty) => {
+    await new Promise((done) =>
+      requestAnimationFrame(() => requestAnimationFrame(() => requestAnimationFrame(done))),
+    )
+    await Promise.race([document.fonts.ready, new Promise((done) => setTimeout(done, 10000))])
+    if (readyProperty) {
+      await Promise.race([
+        Promise.all(
+          [...document.querySelectorAll('*')]
+            .map((one) => one[readyProperty])
+            .filter((one) => one instanceof Promise),
+        ),
+        new Promise((done) => setTimeout(done, 5000)),
+      ])
+    }
+    const shape = () =>
+      [...document.querySelectorAll('*')]
+        .map((one) => {
+          const box = one.getBoundingClientRect()
+          return `${Math.round(box.x)},${Math.round(box.y)},${Math.round(box.width)},${Math.round(box.height)},${one.scrollLeft},${one.scrollTop}`
+        })
+        .join('|')
+    let last = shape()
+    for (let held = 0, spent = 0; held < 3 && spent < 120; spent += 1) {
+      await new Promise((done) => requestAnimationFrame(done))
+      const now = shape()
+      held = now === last ? held + 1 : 0
+      last = now
+    }
+  }, readyProperty ?? null)
+
+/**
+ * `promise`, or a refusal after `seconds`.
+ *
+ * **A timer of its own, because an abort signal is not one everywhere.** A
+ * server that accepts a connection and never answers leaves a fetch waiting,
+ * and a runtime that does not honor `AbortSignal.timeout` on it waits with it.
+ */
+const within = (seconds, promise, what) => {
+  let timer
+  const expired = new Promise((_, refuse) => {
+    timer = setTimeout(
+      () => refuse(new Error(`${what} did not answer within ${seconds} seconds`)),
+      seconds * 1000,
+    )
+  })
+  return Promise.race([promise, expired]).finally(() => clearTimeout(timer))
+}
+
+/** One entry, every shot of it from one navigation. */
+const take = async (page, item, { elements, readyProperty }, progress) => {
+  const started = performance.now()
+  let error = null
+  try {
+    for (const [index, shot] of item.shots.entries()) {
+      progress.stage = index === 0 ? 'loading the page' : `settling for ${shot.name}`
+      await page.setViewportSize({ height: shot.height, width: shot.width })
+      await page.emulateMedia({ colorScheme: shot.scheme })
+      if (index === 0) {
+        /* An entry on a server has its own address. An HTML entry is served
+           here, its document named in the query. */
+        const address =
+          item.url ?? `${state.origin}${item.path}?visual=${encodeURIComponent(item.key)}`
+        await page.goto(address, { waitUntil: 'load' })
+        const missing = await upgrades(page, elements)
+        if (missing.length > 0) {
+          throw new Error(
+            `nothing defines ${missing.map((tag) => `<${tag}>`).join(', ')}, after five seconds of waiting`,
+          )
+        }
+      } else if (shot.harness !== null) {
+        await page.evaluate(
+          ([id, rules]) => {
+            const style = document.getElementById(id)
+            if (style !== null) {
+              style.textContent = rules
+            }
+          },
+          [STYLE_ID, shot.harness],
+        )
+      }
+      progress.stage = `settling for ${shot.name}`
+      await still(page, readyProperty)
+      /* 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),
+      )
+      if (broken.length > 0) {
+        throw new Error(`the font ${[...new Set(broken)].join(', ')} did not load`)
+      }
+      /* `animations: 'disabled'` cancels infinite animations to their first
+         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}`
+      /* 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({
+        animations: 'disabled',
+        fullPage: true,
+        mask: state.mask.map((selector) => page.locator(selector)),
+        maskColor: '#ff00ff',
+        style: state.style,
+      })
+      if (progress.abandoned) {
+        return
+      }
+      say({ key: item.key, op: 'shot', png: png.toString('base64'), shot: shot.name })
+      /* After the first picture, on the page that was pictured, so what the
+         inspection reads cannot move a pixel of that picture. */
+      if (index === 0 && item.inspect) {
+        progress.stage = 'inspecting the page'
+        state.runs.push({
+          entry: item.entry,
+          result: await state.config.inspect.run({ entry: item.entry, page }),
+        })
+      }
+    }
+  } catch (caught) {
+    error = caught instanceof Error ? caught.message.split('\n')[0] : String(caught)
+  }
+  if (progress.abandoned) {
+    return
+  }
+  const seconds = (performance.now() - started) / 1000
+  console.error(
+    `helix: ${item.key}: ${error === null ? `${item.shots.length} ${item.shots.length === 1 ? 'shot' : 'shots'}` : 'failed'} in ${seconds.toFixed(1)} s`,
+  )
+  say({ error, key: item.key, op: 'item', seconds })
+}
+
+/**
+ * Seconds an entry may take for each of its shots before it is given up on.
+ *
+ * **Every wait in a picture is bounded, and so is the whole of one.** A page
+ * that stops drawing frames leaves an `evaluate` waiting on a frame that
+ * never comes, and an unbounded run is a job that hangs until CI kills it and
+ * says nothing about which page did it.
+ */
+const PER_SHOT = 60
+
+/**
+ * One entry on the lane's page, given up on after its time with the stage it
+ * reached named. The page it was stuck on is closed and the lane gets a new
+ * one in the same context, so the entries after it start clean.
+ */
+const bounded = async (lane, item, settle) => {
+  const progress = { abandoned: false, stage: 'starting' }
+  const limit = PER_SHOT * item.shots.length
+  let timer
+  const expired = new Promise((done) => {
+    timer = setTimeout(() => done(true), limit * 1000)
+  })
+  const finished = await Promise.race([take(lane.page, item, settle, progress), expired])
+  clearTimeout(timer)
+  if (finished !== true) {
+    return
+  }
+  progress.abandoned = true
+  const message = `did not finish in ${limit} seconds, stuck ${progress.stage}`
+  console.error(`helix: ${item.key}: ${message}`)
+  say({ error: message, key: item.key, op: 'item', seconds: limit })
+  const context = lane.page.context()
+  await lane.page.close().catch(() => {})
+  lane.page = await context.newPage()
+}
+
+/**
+ * A page per worker, each in a context of its own, made when first needed and
+ * kept for every capture after.
+ *
+ * **Reduced motion on the context**, because `animations: 'disabled'` reaches
+ * only what the browser animates: a WebGL field driven by its own
+ * `requestAnimationFrame` differed by 26,883 pixels between two loads.
+ * Measured across 181 of Fusion's families, no other picture changed under it.
+ *
+ * **Every request off the harness origin is refused**, unless the config opens
+ * the network. A baseline that loaded media from another host recorded
+ * whatever that host returned, and a refusal by the resolver arrives in
+ * whatever time the resolver takes.
+ */
+const lanes = async (count) => {
+  while (state.lanes.length < count) {
+    const context = await state.browser.newContext({
+      reducedMotion: 'reduce',
+      viewport: { height: 800, width: 1280 },
+    })
+    if (state.network === 'origin') {
+      await context.route('**/*', (route) => {
+        let origin
+        try {
+          origin = new URL(route.request().url()).origin
+        } catch {
+          origin = undefined
+        }
+        return state.origins.has(origin) ? route.continue() : route.abort()
+      })
+    }
+    state.lanes.push({ page: await context.newPage() })
+  }
+  return state.lanes.slice(0, count)
+}
+
+const handlers = {
+  async capture({ elements, items, readyProperty }) {
+    for (const item of items.filter((one) => one.path !== undefined)) {
+      state.documents.set(item.key, item.html)
+      state.pages.set(item.path, { dir: item.dir, files: item.files ?? {} })
+    }
+    /* **Worker `k` takes items `k`, `k + n`, and so on**, rather than the next
+       free one off a queue, so which entries shared a page is a function of
+       the worker count and a finding can be reproduced by running again. */
+    const taken = await lanes(Math.min(state.workers, items.length))
+    await Promise.all(
+      taken.map(async (lane, k) => {
+        for (let at = k; at < items.length; at += taken.length) {
+          console.error(`helix: ${items[at].key}: picturing`)
+          await bounded(lane, items[at], { elements, readyProperty })
+        }
+      }),
+    )
+    say({ op: 'captured' })
+  },
+
+  async close() {
+    await state.browser?.close().catch(() => {})
+    state.server?.close()
+    process.exit(0)
+  },
+
+  async config({ path }) {
+    const loaded = await import(pathToFileURL(path).href)
+    const config = loaded.default ?? loaded.config
+    if (config === null || typeof config !== 'object') {
+      throw new Error(`${path} exports no config: export one as the default`)
+    }
+    if (config.inspect !== undefined && typeof config.inspect.run !== 'function') {
+      throw new Error(
+        '`inspect.run` is a function, called with the page after each entry is pictured',
+      )
+    }
+    state.config = config
+    const { inspect, ...values } = config
+    say({
+      config: { ...JSON.parse(JSON.stringify(values)), inspect: inspect !== undefined },
+      op: 'config',
+    })
+  },
+
+  /* **Each page's own diagnostics, with nothing added to the app.** The
+     installed `@fusion.dev/helix-diagnostics` is served on each page's own
+     origin, under a path no app uses, so a policy that allows only `'self'`
+     scripts allows it, and the page imports it once it holds still and runs
+     one `diagnose()` against the installed manifests. The runtime events the
+     library logged as the page loaded are in the run, which is the half a
+     read of the code cannot see. */
+  async diagnose({ dist, file, readyProperty, tiers, urls }) {
+    const { chromium } = await playwright()
+    state.browser ??= await chromium.launch()
+    const context = await state.browser.newContext({ reducedMotion: 'reduce' })
+    await context.route(`**/${DIAGNOSTICS}/**`, async (route) => {
+      const name = new URL(route.request().url()).pathname.split(`/${DIAGNOSTICS}/`)[1] ?? ''
+      const path = inside(dist, name)
+      if (path === undefined || !existsSync(path) || !statSync(path).isFile()) {
+        await route.fulfill({ status: 404 })
+        return
+      }
+      await route.fulfill({ body: readFileSync(path), contentType: 'text/javascript' })
+    })
+    const runs = []
+    for (const url of urls) {
+      const page = await context.newPage()
+      try {
+        const answered = await page.goto(url, { waitUntil: 'load' })
+        /* A page that is not there is no clean page. */
+        if (answered !== null && !answered.ok()) {
+          throw new Error(`answered ${answered.status()}`)
+        }
+        await still(page, readyProperty)
+        runs.push(
+          await page.evaluate(
+            async ({ entry, file, tiers }) => {
+              const { diagnose } = await import(entry)
+              return diagnose({ environment: 'development', file: file ?? undefined, tiers })
+            },
+            { entry: `/${DIAGNOSTICS}/index.js`, file, tiers },
+          ),
+        )
+      } catch (caught) {
+        runs.push({ error: caught instanceof Error ? caught.message : String(caught), url })
+      } finally {
+        await page.close().catch(() => {})
+      }
+    }
+    await context.close().catch(() => {})
+    say({ op: 'diagnosed', runs })
+  },
+
+  async fetch({ url }) {
+    const answer = await within(30, fetch(url, { redirect: 'follow' }), url)
+    say({
+      ok: answer.ok,
+      op: 'fetched',
+      status: answer.status,
+      text: await within(30, answer.text(), url),
+    })
+  },
+
+  async finish({ update }) {
+    const reported = await state.config.inspect?.report?.(state.runs, { update })
+    say({ failed: Boolean(reported?.failed), op: 'finished' })
+  },
+
+  async start({ mask = [], network, origins = [], serve, style = null, workers }) {
+    state.mask = mask
+    state.style = style ?? undefined
+    state.network = network
+    state.workers = workers
+    state.serve = Object.entries(serve)
+      .map(([url, file]) => ({ directory: url.endsWith('/'), file, url }))
+      .sort((a, b) => b.url.length - a.url.length)
+    state.server = createServer(respond)
+    await new Promise((done) => state.server.listen(0, '127.0.0.1', done))
+    state.origin = `http://127.0.0.1:${state.server.address().port}`
+    state.origins = new Set([state.origin, ...origins])
+    const { chromium } = await playwright()
+    state.browser = await chromium.launch()
+    say({ browser: `chromium ${state.browser.version()}`, op: 'started' })
+  },
+
+  /* Polls until anything answers, a refusal of the connection being the one
+     thing that means nothing is listening yet. */
+  async wait({ seconds, url }) {
+    const deadline = Date.now() + seconds * 1000
+    for (;;) {
+      try {
+        await within(5, fetch(url, { redirect: 'manual' }), url)
+        say({ op: 'waited', up: true })
+        return
+      } catch {
+        if (Date.now() > deadline) {
+          say({ op: 'waited', up: false })
+          return
+        }
+        await new Promise((done) => setTimeout(done, 500))
+      }
+    }
+  },
+}
+
+/**
+ * Playwright, or a failure that says how to install it.
+ *
+ * **An optional peer of `@fusion.dev/helix-cli`**, because a project that only
+ * scans or derives a theme never pictures a page and should not install a
+ * browser to do it. The first `helix visual test` is where it is needed, so
+ * that is where the instruction is.
+ */
+const playwright = async () => {
+  try {
+    return await import('playwright')
+  } catch (error) {
+    if (error?.code !== 'ERR_MODULE_NOT_FOUND' || !String(error.message).includes("'playwright'")) {
+      throw error
+    }
+    throw new Error(
+      '`helix visual` pictures pages with Playwright, which is not installed. Install it with `npm install --save-dev playwright`, then its browser with `npx playwright install chromium`.',
+    )
+  }
+}
+
+const input = Buffer.alloc(1 << 16)
+const decoder = new StringDecoder('utf8')
+let pending = ''
+
+/** The next request line, or undefined once the binary has closed the pipe. */
+const request = () => {
+  for (;;) {
+    const at = pending.indexOf('\n')
+    if (at >= 0) {
+      const line = pending.slice(0, at)
+      pending = pending.slice(at + 1)
+      return line
+    }
+    let read
+    try {
+      read = readSync(0, input, 0, input.length, null)
+    } catch (caught) {
+      if (caught?.code === 'EAGAIN') {
+        pause(5)
+        continue
+      }
+      if (caught?.code === 'EOF') {
+        return undefined
+      }
+      throw caught
+    }
+    if (read === 0) {
+      return undefined
+    }
+    pending += decoder.write(input.subarray(0, read))
+  }
+}
+
+/* One request at a time, each answered before the next is read. */
+for (let line = request(); line !== undefined; line = request()) {
+  try {
+    const asked = JSON.parse(line)
+    const handler = handlers[asked.op]
+    if (handler === undefined) {
+      throw new Error(`no request is called \`${asked.op}\``)
+    }
+    await handler(asked)
+  } catch (caught) {
+    say({ message: caught instanceof Error ? caught.message : String(caught), op: 'error' })
+  }
+}
+/* The binary went away, so nothing is waiting for the browser. */
+await handlers.close()

package/visual/index.d.ts

@@ -0,0 +1,251 @@
+import type { Page } from 'playwright'
+
+/** A color scheme a shot is taken in, declared on the page and emulated both. */
+export type Scheme = 'dark' | 'light'
+
+/** One picture of every entry. */
+export interface Shot {
+  /** The viewport's height in pixels. The picture is the full page either way. 800 when not given. */
+  height?: number
+  /** Names the shot in the report, in exceptions and, unless `suffix` is given, in the baseline's file name. */
+  name: string
+  /** The color scheme the page is told it has. */
+  scheme: Scheme
+  /** What the baseline's file name carries after its stem. `.<name>` when not given, so `preview.phone.png`. */
+  suffix?: string
+  /** The viewport's width in pixels, set on `body` by the harness too. */
+  width: number
+}
+
+/** One color for each scheme. */
+export interface Pair {
+  /** The color in the dark scheme. */
+  dark: string
+  /** The color in the light scheme. */
+  light: string
+}
+
+/** The ground, the ink and the inset the harness sets on `body`. */
+export interface Harness {
+  /** The page's background. `#fff` and `#000` when not given. */
+  ground?: Pair
+  /** The page's text color. `#000` and `#fff` when not given. */
+  ink?: Pair
+  /** Pixels between the page's edge and its content. 24 when not given. */
+  padding?: number
+}
+
+/** How a shot is compared with its baseline. */
+export interface Diff {
+  /**
+   * `pixel` counts the pixels past `threshold`, and is the default. `perceptual` scores structural
+   * similarity, for photographs and gradients whose pixels move a shade on every render.
+   */
+  mode?: 'perceptual' | 'pixel'
+  /** Pixels a shot may differ by and still pass, in the pixel mode. 0 when not given. */
+  pixels?: number
+  /** The lowest structural similarity a shot may score and pass, in the perceptual mode, from 0 to 1. 0.99 when not given. */
+  ssim?: number
+  /** How far apart two colors may be and still be one pixel, from 0 to 1. 0.1 when not given. */
+  threshold?: number
+}
+
+/** HTML files from a glob, each pictured inside a document the harness writes. */
+export interface HtmlSource {
+  /** The diff for this source's shots, in place of the config's. */
+  diff?: Diff
+  /**
+   * Relative requests from a page answered by another file in its directory,
+   * with `{stem}` for the page's own file name without its extension:
+   * `{ 'styles.css': '{stem}.css' }`.
+   */
+  files?: Record<string, string>
+  /**
+   * Which files under `root` are entries. `*` matches within a path segment,
+   * `**` matches any number of directories, and `{name}` is the one segment
+   * that names the entry: `{name}/.examples/preview.html`.
+   */
+  glob: string
+  /** The harness's colors and inset, or `false` to picture the file as it is. */
+  harness?: boolean | Harness
+  /** Picks this source out of the others. */
+  kind: 'html'
+  /** The first half of each entry's id, `<name>/<entry>`. One word. */
+  name: string
+  /** Where the glob starts, relative to the config. */
+  root: string
+  /** URLs of scripts the page loads, each with `defer`, after the harness style. */
+  scripts?: string[]
+  /** URLs of stylesheets the page links, before the harness style. */
+  styles?: string[]
+}
+
+/** What every source on a server shares. */
+interface Served {
+  /** The directory each entry's baselines are written in, relative to the config. */
+  baselines: string
+  /** The directory `start` runs in, relative to the config. */
+  cwd?: string
+  /** The diff for this source's shots, in place of the config's. */
+  diff?: Diff
+  /** The first half of each entry's id, `<name>/<entry>`. One word. */
+  name: string
+  /**
+   * A shell command that starts the server, run only when nothing answers at `url`, and stopped
+   * when the run ends. Left out, the server has to be running already.
+   */
+  start?: string
+  /** Seconds to wait for the server to answer after `start`. 120 when not given. */
+  timeout?: number
+  /** The server's address, `http://localhost:3000`. */
+  url: string
+}
+
+/** 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 })[]
+  /** A sitemap's path on the server, `/sitemap.xml`, whose every route is pictured too. */
+  sitemap?: string
+}
+
+/** Stories from a running Storybook, read from its `index.json`. */
+export interface StorybookSource extends Served {
+  /** Stories carrying one of these tags are left out. */
+  exclude?: string[]
+  /** Only stories carrying one of these tags, when any are given. */
+  include?: string[]
+  /** Picks this source out of the others. */
+  kind: 'storybook'
+}
+
+/** Entries listed in a JSON file: an array of `{ id, url }`, each `url` relative to the server. */
+export interface CatalogSource extends Served {
+  /** The catalog file, relative to the config. */
+  catalog: string
+  /** Picks this source out of the others. */
+  kind: 'catalog'
+}
+
+/** Any source of entries. */
+export type Source = CatalogSource | HtmlSource | ServerSource | StorybookSource
+
+/** An entry as `inspect` sees it. */
+export interface Entry {
+  /** The HTML file, absolute, for an entry from an HTML source. */
+  file?: string
+  /** `<source>/<name>`, unique across the run. */
+  id: string
+  /** What the glob named it. */
+  name: string
+  /** The name of the source it came from. */
+  source: string
+  /** The page's address, for an entry on a server. */
+  url?: string
+}
+
+/** A run of `inspect.run`, collected for `inspect.report`. */
+export interface Inspected<Result = unknown> {
+  /** The entry that was inspected. */
+  entry: Entry
+  /** What `run` returned. */
+  result: Result
+}
+
+/** Checks of your own on each page, after its first picture. */
+export interface Inspect<Result = unknown> {
+  /**
+   * Called once at the end of the run with every result. Return `{ failed: true }` to fail the run.
+   */
+  report?: (
+    runs: Inspected<Result>[],
+    context: {
+      /** Whether the run is `helix visual update`. */
+      update: boolean
+    },
+  ) => Promise<{ failed?: boolean } | undefined> | { failed?: boolean } | undefined
+  /** Called on the page that was pictured, after its first shot. What it returns is kept for `report`. */
+  run: (context: {
+    /** The entry on the page. */
+    entry: Entry
+    /** The Playwright page. */
+    page: Page
+  }) => Promise<Result> | Result
+}
+
+/** One exception to the comparison, with the reason it exists. */
+export interface Exception {
+  /** An entry's id, `styled/aura`, or its name in every source, `aura`. */
+  entry: string
+  /** What was measured to justify it, said beside it in every run. */
+  measured?: string
+  /** How many pixels the shot may differ by. An exception whose shot stops differing fails the run. */
+  pixels?: number
+  /** Why the exception exists. */
+  reason: string
+  /** One shot by name, or every shot of the entry when not given. */
+  shot?: string
+  /** A surface that cannot hold still: never pictured, and named in every run as skipped. */
+  unstable?: boolean
+}
+
+/** A `visual.config.ts`. */
+export interface Config {
+  /** How a shot is compared with its baseline, unless its source sets its own. */
+  diff?: Diff
+  /** Exceptions to the comparison, each with its reason. */
+  exceptions?: Exception[]
+  /** Where the environment fingerprint is kept, relative to the config. `visual.fingerprint.json` when not given. */
+  fingerprint?: string
+  /** Checks of your own on each page, after its first picture. */
+  inspect?: Inspect
+  /**
+   * Selectors whose elements are painted over in one fixed color in every picture, for what changes on its
+   * own and says nothing about the page, such as a version number or a date.
+   */
+  mask?: string[]
+  /** `origin` refuses every request off the harness origin, and is the default. `open` lets them through. */
+  network?: 'open' | 'origin'
+  /** `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. */
+  report?: string
+  /** How your project retakes its baselines, said when a run fails. */
+  retake?: string
+  /** URL paths the harness serves from disk, relative to the config. A path ending in `/` serves a directory. */
+  serve?: Record<string, string>
+  /** What the harness waits for before each picture. */
+  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.
+     */
+    elements?: string
+    /** A property each element may carry holding a promise that resolves when it has rendered. */
+    readyProperty?: string
+  }
+  /** How `--shard` packs entries into shards. */
+  shard?: {
+    /** Measured seconds by entry name. */
+    cost?: Record<string, number>
+    /** Seconds a shot is taken to cost where `cost` names nothing. 1 when not given. */
+    perShot?: number
+  }
+  /** The pictures taken of every entry. A wide width, a phone width and dark when not given. */
+  shots?: Shot[]
+  /** Where entries come from. */
+  sources: Source[]
+  /**
+   * A stylesheet applied while each picture is taken and removed after, to hold still what `mask` alone
+   * cannot, such as a masked element whose width follows its text.
+   */
+  style?: string
+  /** A file to write the seconds each entry name took, relative to the config. */
+  timings?: string
+}
+
+/** Returns the config unchanged, typed. */
+export declare const defineConfig: (config: Config) => Config

package/visual/index.mjs

@@ -0,0 +1,10 @@
+/**
+ * `@fusion.dev/helix-cli/visual`: what a `visual.config.ts` imports.
+ *
+ * The config is plain data and two optional functions, so this returns what it
+ * is given. It exists for the types: `defineConfig` checks a config against
+ * `index.d.ts` beside it where it is written.
+ */
+
+/** The config, unchanged, typed. */
+export const defineConfig = (config) => config