Visual regression capture, comparison, and review for Ariakit.
Visonaut captures prepared Playwright pages. Trusted CLI Submit verifies the capture evidence and compares PNG images in CI. The service validates the signed receipt and lets maintainers review changes in a private web app. The GitHub App check reports the result. Uploading a capture does not approve it. The CLI in the Submit job checks each image: it decodes each capture when it compares. The service checks only the size and the SHA-256 digest of each uploaded image, and it does not decode the bytes.
The current implementation contract is the current guide. It owns the requirements, exact supersession map, source behavior, selected targets, and evidence limits. PR #205 completed the authority handoff on 2026-10-02. The pinned issue #1 notice preserves the earlier issue. Every unaffected requirement remains binding. The guide also records the selected changes from issue #204.
Use the release and deployment guide for execution and the dated cutover record for dated completion receipts. A passing local test suite does not prove live state.
Open the review link from the GitHub check and sign in with GitHub. Access requires current write permission to the configured repository. Check the commit and attempt, select a screenshot and a variant, then inspect its images before you approve or reject it.
A pull request author with no write permission cannot open the review link, and does not need it. The title of the Visonaut check names the state of the run, and its summary says who acts next. For example, 79 changes need review waits for a maintainer, and 3 changes rejected waits for a commit of the author that corrects the rejected changes. The review guide lists the title of each run state.
Only a pull request whose branch is in this repository gets a Visonaut check. A pull request from a fork gets none, so its author has no title to read.
Validated image URLs need no session. Anyone with a URL can view and copy those pixels. Run metadata, labels, decisions, export files, and quarantine remain private. The public route serves only validated image records, not arbitrary bucket paths. Preview uses isolated fixture runs without GitHub login or production data. It does not certify deployed authentication.
The Status page shows unresolved service alerts. It refreshes them while it is open and its tab is visible. No external notifications are sent.
Use the review guide for image modes, keyboard controls, commands for a whole screenshot, Undo, and recovery from a failed save.
The Playwright adapter captures one prepared variant per call. The caller controls navigation, media settings, viewport, and variant order. Item and variant keys define identity.
import { visual } from "@visonaut/playwright";
await visual(page, {
item: "dialog/success/open",
name: "Success dialog",
variant: { key: "react-chromium-light", browser: "chromium" },
});Ariakit configures its reporter explicitly and uploads ordinary one-day capture artifacts. Native Plan runs visonaut submit --no-visual only after successful Plan CI computes app=false. For app=true, App / Visual Capture (linux) and App / Visual Capture (safari) feed App / Visual Submit. Trusted Submit verifies successful native Plan and the complete capture set. The adapter guide explains capture profiles, comparison settings, stability, and retries. The CLI guide explains submission. The versions are in the CLI manifest and the adapter manifest. The implementation checkpoint records publication, consumer adoption, required checks, and deployment. PR #205 completed the readiness marker and authority handoff; #207 records completed transfer-key cleanup. These dated receipts do not prove the later #204 removal gates.
# In the trusted signed Submit job, after every capture job succeeds:
pnpm exec visonaut submit --shard linux --shard safariThe service accepts a run from the signed GitHub Actions identity alone. It verifies the exact tested commit and attempt, and the complete source-attempt capture set, and it compares no workflow Git blob. The visual path has no separate signed Plan report. The Visonaut check from App 5028451 is required beside Gate. Gate polling is removed. Native Gate still verifies the other selected CI jobs. The service accepts validated PNG and lossless WebP originals; local Submit requires PNG captures and references. Human decisions bind to the exact comparison and revision. A full main run promotes a baseline only when all acceptance conditions pass.
The root manifest selects Node.js in devEngines.runtime and pnpm in packageManager. pnpm install downloads the selected Node.js runtime. CI reads the same runtime version. The review browser tests run on the Chromium build of the locked Playwright version: run pnpm exec playwright install chromium once.
pnpm install --frozen-lockfile
pnpm checkUse the development and verification guide for command scopes and the on-demand built-app check. For a focused check, run pnpm test or pnpm test:browser. The browser suite starts its own review fixture with controlled data and fails if the selected port is busy. Set VISONAUT_TEST_PORT=4392 pnpm test:browser to use a separate port for another checkout. The default port is 4179. The fixture needs no GitHub session or deployed Worker.
pnpm dev starts the public fixture demo. Preview uses synthetic review data and inline SVG images without backend bindings or credentials. Local tests create separate ephemeral storage when they need the live API. pnpm --filter @visonaut/web db:local applies the production schema to local D1 only. See the security configuration, Worker configuration, and deployment guide.
| Path | Purpose |
|---|---|
apps/web |
TanStack Start app, private API, review UI, and operations |
packages/playwright |
Public Playwright adapter and reporter |
packages/cli |
Public visonaut begin, submit, and status commands |
packages/protocol |
Capture and service contracts |
packages/compare |
Image validation, codecs, and legacy comparison engine |
packages/service |
Run, review, acceptance, and baseline transitions |
packages/security |
Authentication, authorization, OIDC, and GitHub checks |
- Current implementation contract
- Development and verification
- Implementation record
- Review guide
- Operations and recovery
- CI, deployment, and publication
- Review evidence capture plan
- Revision 9 design, decision data, and design verification
D10 and D17 keep the copied UI components, current packages, and TanStack Start framework. The CLI remains independent of the Playwright peer runtime. The revision 9 design is a historical record. The current contract preserves its 61 decisions and states each selected supersession. Prototype checks remain separate from implementation and deployment evidence. The copied Ariakit UI components retain their MIT license and source notice.