@cevek/screentest 0.1.0 → 0.2.0

package/README.md

@@ -1,146 +1,140 @@
-# screentest
+# @cevek/screentest
 
-Local desktop tool for visual screenshot-test review. Takes a JSON tree of
-diffs as input, serves a React UI on `127.0.0.1`, lets a human accept new /
-changed snapshots one-by-one or in bulk. Accepted screenshots are uploaded to
-your Cloudflare Worker (R2) and the diff is written back into your project's
-`snapshot.json`.
+Local desktop tool for visual screenshot-test review, **plus** the runner
+helpers and Docker-based test harness needed to actually capture the
+screenshots. Everything ships in one npm package — no copy-paste.
 
 ## Install
 
 ```bash
-npm i -D @cevek/screentest
-# or pnpm add -D @cevek/screentest / yarn add -D @cevek/screentest
+pnpm add -D @cevek/screentest playwright vitest
+pnpm exec playwright install firefox
 ```
 
-`screentest` is a CLI — no library API. The package installs a single
-`screentest` bin into `node_modules/.bin/`.
+`playwright` and `vitest` are peer-deps — keep them in your devDependencies.
 
-## Run
+## Quick start
+
+```bash
+# 1. Scaffold the test harness into your project.
+pnpm exec screentest init
+
+# 2. Build the Docker image once.
+docker build -f Dockerfile.tests -t screentest-tests .
+
+# 3. Run.
+APP_URL=http://localhost:5050 pnpm exec screentest test
+```
+
+`screentest init` creates:
+
+- `Dockerfile.tests` — playwright-noble + your project deps + vitest CMD
+- `vitest.config.ts` — pre-wired with the package's globalSetup
+- `tests/example.test.ts` — minimal Playwright test using the runner helpers
+
+Existing files are not overwritten — re-run `init` safely.
+
+## Commands
 
 ```bash
 screentest <doc-json-path> [--port 5174] [--no-open]
-                           [--worker-url <url>] [--token <token>]
+                           [--worker-url URL] [--token TOKEN]
+```
+Open the review UI on a pre-built `doc.json`. Used internally by `screentest
+test` and `screentest review`.
+
+```bash
+screentest test [--host]
+```
+Default workflow: run vitest **inside Docker** (network=host), and on failure
+auto-launch the review UI. `--host` runs vitest on the host instead (debug
+only — bytes diverge from your CI baseline). Set `CI=1` to skip the auto-UI
+launch.
+
+```bash
+screentest review
 ```
+Skip vitest, just regenerate `doc.json` from cached actuals and open the UI.
 
-`doc.json` is the input describing what to review. See the
-[input format](#input-format-docjson) below.
-
-Env vars:
-
-| Var                     | Default                                   |
-| ----------------------- | ----------------------------------------- |
-| `CLOUDFLARE_WORKER_URL` | `https://screentests.x-cevek.workers.dev` |
-| `CLOUDFLARE_TOKEN`      | `SECRET_123`                              |
-
-You almost certainly want to point these at your own R2-backed Worker. See
-the worker template at <https://github.com/x-cevek/screentest/tree/main/cloudflare-worker>.
-
-## Hotkeys
-
-| Key                            | Action                                  |
-| ------------------------------ | --------------------------------------- |
-| `↑` / `↓`                      | Previous / next pending test            |
-| `Enter`                        | Accept current (if valid)               |
-| `Cmd/Ctrl + wheel` over canvas | Move comparison slider                  |
-| Hold mouse on **Show diff**    | Purple-pixel overlay (change-type only) |
-
-## Input format: doc.json
-
-```json
-{
-  "groups": [
-    {
-      "name": "team",
-      "items": [
-        {
-          "name": "login",
-          "type": "new",
-          "actualFilename": "actual/team/login.png",
-          "patchSnapshotJsonFile": "/abs/path/to/snapshot.json"
-        },
-        {
-          "name": "page",
-          "type": "change",
-          "expectedHash": "aaa…(64 hex chars)…",
-          "actualFilename": "actual/team/page.png",
-          "patchSnapshotJsonFile": "/abs/path/to/snapshot.json"
-        },
-        {
-          "name": "deprecated-banner",
-          "type": "deleted",
-          "expectedHash": "bbb…(64 hex chars)…",
-          "patchSnapshotJsonFile": "/abs/path/to/snapshot.json"
-        }
-      ]
-    }
-  ]
-}
+```bash
+screentest init
 ```
+Scaffold Dockerfile + vitest config + example test (see above).
+
+## Writing tests
+
+```ts
+import { afterAll, beforeAll, describe, it } from 'vitest';
+import type { Page } from 'playwright';
+import { compareSnapshot, freezeDate, newPage } from '@cevek/screentest/runner';
+
+const APP_URL = (process.env.APP_URL || 'http://localhost:5050').replace(/\/+$/, '');
+
+let page: Page;
+let cleanup: () => Promise<void>;
+
+beforeAll(async () => {
+  const r = await newPage();
+  await freezeDate(r.ctx, '2024-01-15T12:00:00Z'); // optional
+  page = r.page;
+  cleanup = r.cleanup;
+});
+afterAll(() => cleanup?.());
+
+describe('team', () => {
+  it('login flow', async () => {
+    await page.goto(`${APP_URL}/team`);
+    await page.locator('input[name="username"]').waitFor({ state: 'visible' });
+    await compareSnapshot(page, 'login'); // → team / login flow / login
+  });
+});
+```
+
+Snapshot paths are auto-derived from `describe(...)` + `it(...)`. The
+hashes are stored in `snapshot.json` at your project root; actuals + the
+generated `doc.json` go to `node_modules/.cache/screentest/` (gitignored
+by convention).
+
+## Docker Desktop host networking
+
+`screentest test` uses `--network=host` so the container can reach your
+app at `localhost:*`. On macOS / Windows Docker Desktop enable it once:
+`Settings → Resources → Network → Enable host networking`. On Linux Docker
+(CI) it works out of the box.
+
+## Cloudflare Worker (blob store)
 
-Three test-item types:
-
-- **`new`** — `actualFilename` required. On accept, hashes the file (SHA-256
-  hex), uploads it to Cloudflare, inserts `{ name, hash }` into the snapshot
-  file.
-- **`change`** — both `actualFilename` and `expectedHash` required. Tool shows
-  expected vs actual with a slider + purple-pixel diff overlay. On accept, same
-  as `new` (re-hash, re-upload, update the entry).
-- **`deleted`** — `expectedHash` required, no `actualFilename`. Tool shows the
-  expected image plus a "this will be removed" plate. On accept, removes the
-  entry from the snapshot file and prunes any group that becomes empty.
-
-Paths in `actualFilename` are resolved relative to the doc.json directory.
-`patchSnapshotJsonFile` can be relative or absolute.
-
-## Snapshot file format
-
-What the tool writes into `patchSnapshotJsonFile`:
-
-```json
-{
-  "groups": [
-    {
-      "name": "team",
-      "items": [
-        { "name": "login", "hash": "aaa…(64 hex chars)…" },
-        { "name": "page", "hash": "bbb…(64 hex chars)…" }
-      ]
-    }
-  ]
-}
+Accepted screenshots are stored in your Cloudflare Worker (R2-backed). See
+the [worker template](https://github.com/x-cevek/screentest/tree/main/cloudflare-worker)
+for a 100-line implementation + `wrangler deploy` instructions.
+
+Once deployed:
+
+```bash
+export CLOUDFLARE_WORKER_URL="https://screentests.your-account.workers.dev"
+export CLOUDFLARE_TOKEN="<UPLOAD_TOKEN secret you set with wrangler>"
 ```
 
-Writes are atomic (tmp file + rename) and serialized by a per-file mutex
-inside the server, so concurrent accepts don't race.
+Or pass `--worker-url` / `--token` to `screentest` directly.
 
-## How tests produce doc.json
+## CI
 
-The tool does NOT capture screenshots — it only reviews them. Producing the
-actual screenshots and the doc.json is your test runner's job. The simplest
-pattern:
+```yaml
+- run: docker build -f Dockerfile.tests -t screentest-tests .
+- run: CI=1 pnpm exec screentest test
+```
 
-1. In each test, take a screenshot with Playwright; save to a known path; hash
-   it; compare to the entry in `snapshot.json` for that test. Fail the test
-   on mismatch.
-2. On failure (locally), run a script that walks the captured screenshots,
-   diffs them against `snapshot.json` (new / change / deleted), and writes a
-   `doc.json`.
-3. Spawn `screentest doc.json`. User reviews and accepts.
+In `CI=1` the orchestrator exits with vitest's code and never tries to open
+the UI.
 
-See the [example test-runner setup](https://github.com/x-cevek/screentest/tree/main/test-project)
-for a reference implementation (Vitest + Playwright + helpers).
+## Input format reference
+
+If you need to construct your own `doc.json` for the UI (instead of going
+through `screentest test` / `review`), see
+[the format documentation in the source repo](https://github.com/x-cevek/screentest#input-format-docjson).
 
 ## Security
 
-- Server listens only on `127.0.0.1` — never on `0.0.0.0`.
+- The UI server listens only on `127.0.0.1`. Never on `0.0.0.0`.
 - `actual` files are served strictly from a whitelist computed from
-  `doc.json` at startup. No path-traversal possible from the HTTP layer.
-- Stays in-process; no daemon, no auto-update.
-
-## Cloudflare Worker
-
-The Worker is the blob store. It stores accepted screenshots keyed by their
-SHA-256 hash and serves them back on subsequent reviews. See the
-[worker template + wrangler config](https://github.com/x-cevek/screentest/tree/main/cloudflare-worker)
-for the minimal implementation backed by R2.
+  `doc.json` at startup — no path traversal possible.

package/dist/global-setup.d.ts

@@ -0,0 +1,10 @@
+import type { TestProject } from 'vitest/node';
+
+declare const setup: (project: TestProject) => Promise<() => Promise<void>>;
+export default setup;
+
+declare module 'vitest' {
+  interface ProvidedContext {
+    wsEndpoint: string;
+  }
+}

package/dist/global-setup.js

@@ -0,0 +1,15 @@
+// src/runner/global-setup.ts
+import { firefox } from "playwright";
+var server;
+async function setup(project) {
+  server = await firefox.launchServer();
+  const wsEndpoint = server.wsEndpoint();
+  project.provide("wsEndpoint", wsEndpoint);
+  console.log(`[screentest] firefox server ready: ${wsEndpoint}`);
+  return async () => {
+    await server?.close();
+  };
+}
+export {
+  setup as default
+};

package/dist/index.js

@@ -5,7 +5,7 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
-// src/index.ts
+// src/ui.ts
 import { promises as fs3 } from "fs";
 import { dirname as dirname3, isAbsolute, resolve as resolve4 } from "path";
 
@@ -14595,7 +14595,7 @@ function buildTestId(parents, name) {
   return [...parents, name].join("/");
 }
 
-// src/index.ts
+// src/ui.ts
 import open from "open";
 
 // src/state.ts
@@ -14985,33 +14985,29 @@ function isFree(port) {
   });
 }
 
-// src/index.ts
+// src/ui.ts
 var DEFAULT_WORKER_URL = "https://screentests.x-cevek.workers.dev";
 var DEFAULT_TOKEN = "SECRET_123";
 var DEFAULT_PORT = 5174;
-function parseArgs(argv) {
-  const args = argv.slice(2);
+function parseUIArgs(rawArgs) {
   let docPath = null;
   let port = Number(process.env.PORT) || DEFAULT_PORT;
   let doOpen = true;
   let workerUrl = process.env.CLOUDFLARE_WORKER_URL || DEFAULT_WORKER_URL;
   let token = process.env.CLOUDFLARE_TOKEN || DEFAULT_TOKEN;
-  for (let i = 0; i < args.length; i++) {
-    const a = args[i];
+  for (let i = 0; i < rawArgs.length; i++) {
+    const a = rawArgs[i];
     if (a === "--port") {
-      port = Number(args[++i]);
+      port = Number(rawArgs[++i]);
       if (!Number.isFinite(port) || port <= 0) throw new Error("--port must be a number");
     } else if (a === "--no-open") {
       doOpen = false;
     } else if (a === "--worker-url") {
-      workerUrl = args[++i] ?? "";
+      workerUrl = rawArgs[++i] ?? "";
       if (!workerUrl) throw new Error("--worker-url requires a value");
     } else if (a === "--token") {
-      token = args[++i] ?? "";
+      token = rawArgs[++i] ?? "";
       if (!token) throw new Error("--token requires a value");
-    } else if (a === "--help" || a === "-h") {
-      printHelp();
-      process.exit(0);
     } else if (a.startsWith("--")) {
       throw new Error(`Unknown flag: ${a}`);
     } else if (!docPath) {
@@ -15020,10 +15016,7 @@ function parseArgs(argv) {
       throw new Error(`Unexpected positional arg: ${a}`);
     }
   }
-  if (!docPath) {
-    printHelp();
-    process.exit(1);
-  }
+  if (!docPath) throw new Error("doc-json path is required");
   return {
     docPath,
     port,
@@ -15032,15 +15025,8 @@ function parseArgs(argv) {
     token
   };
 }
-function printHelp() {
-  process.stderr.write(
-    `Usage: screentest <doc-json-path> [--port 5174] [--no-open] [--worker-url URL] [--token TOKEN]
-`
-  );
-}
-async function main() {
-  const args = parseArgs(process.argv);
-  const docAbs = isAbsolute(args.docPath) ? args.docPath : resolve4(process.cwd(), args.docPath);
+async function runUI(opts) {
+  const docAbs = isAbsolute(opts.docPath) ? opts.docPath : resolve4(process.cwd(), opts.docPath);
   const docDir = dirname3(docAbs);
   let raw;
   try {
@@ -15083,15 +15069,15 @@ async function main() {
   const state = {
     doc,
     docDir,
-    workerUrl: args.workerUrl,
-    token: args.token,
+    workerUrl: opts.workerUrl,
+    token: opts.token,
     flat: flatResult.flat,
     actualWhitelist: flatResult.whitelist
   };
-  const srv = await startServer(state, args.port);
+  const srv = await startServer(state, opts.port);
   process.stdout.write(`screentest running on ${srv.url}
 `);
-  if (args.open) {
+  if (opts.open) {
     try {
       await open(srv.url);
     } catch {
@@ -15104,6 +15090,322 @@ async function main() {
   process.on("SIGINT", shutdown);
   process.on("SIGTERM", shutdown);
 }
+
+// src/orchestrator.ts
+import { spawn, spawnSync } from "child_process";
+import { createHash as createHash2 } from "crypto";
+import { promises as fs4 } from "fs";
+import { join as join3, relative, sep } from "path";
+
+// src/runner/paths.ts
+import { join as join2, resolve as resolve5 } from "path";
+function resolveRunnerPaths(cwd = process.cwd()) {
+  const projectRoot = resolve5(cwd);
+  const cacheDir = join2(projectRoot, "node_modules", ".cache", "screentest");
+  return {
+    projectRoot,
+    snapshotFile: join2(projectRoot, "snapshot.json"),
+    cacheDir,
+    actualDir: join2(cacheDir, "actual"),
+    docFile: join2(cacheDir, "doc.json")
+  };
+}
+
+// src/orchestrator.ts
+var DOCKER_IMAGE = "screentest-tests";
+function run(cmd, argv) {
+  return new Promise((resolve7) => {
+    const p = spawn(cmd, argv, { stdio: "inherit" });
+    p.on("exit", (code) => resolve7(code ?? 0));
+  });
+}
+function isGroup(node) {
+  return Array.isArray(node.items);
+}
+async function readSnapshot(snapshotFile) {
+  try {
+    return JSON.parse(await fs4.readFile(snapshotFile, "utf8"));
+  } catch {
+    return { groups: [] };
+  }
+}
+function indexSnapshot(snap) {
+  const out = /* @__PURE__ */ new Map();
+  const walk = (items, prefix) => {
+    for (const it of items) {
+      if (isGroup(it)) walk(it.items, [...prefix, it.name]);
+      else out.set([...prefix, it.name].join("/"), it.hash);
+    }
+  };
+  for (const g of snap.groups) walk(g.items ?? [], [g.name]);
+  return out;
+}
+async function walkActual(dir, prefix = []) {
+  let entries;
+  try {
+    entries = await fs4.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      out.push(...await walkActual(join3(dir, e.name), [...prefix, e.name]));
+    } else if (e.isFile() && e.name.endsWith(".png")) {
+      const stem = e.name.slice(0, -4);
+      out.push({ path: [...prefix, stem], absFile: join3(dir, e.name) });
+    }
+  }
+  return out;
+}
+function insertLeaf(doc, path, leaf) {
+  let groups = doc.groups;
+  for (let i = 0; i < path.length - 1; i++) {
+    const name = path[i];
+    let g = groups.find((x) => "items" in x && x.name === name);
+    if (!g) {
+      g = { name, items: [] };
+      groups.push(g);
+    }
+    groups = g.items;
+  }
+  groups.push({ name: path[path.length - 1], ...leaf });
+}
+function countLeaves(doc) {
+  let n = 0;
+  const walk = (items) => {
+    for (const it of items) {
+      if ("items" in it) walk(it.items);
+      else n++;
+    }
+  };
+  for (const g of doc.groups) walk(g.items);
+  return n;
+}
+async function generateDoc(snapshotFile, actualDir, docFile, cacheDir) {
+  const snap = await readSnapshot(snapshotFile);
+  const expectedByPath = indexSnapshot(snap);
+  const actuals = await walkActual(actualDir);
+  const seen = /* @__PURE__ */ new Set();
+  const doc = { groups: [] };
+  const summary = { new: 0, change: 0, deleted: 0, unchanged: 0 };
+  for (const a of actuals) {
+    const buf = await fs4.readFile(a.absFile);
+    const hash2 = createHash2("sha256").update(buf).digest("hex");
+    const key = a.path.join("/");
+    seen.add(key);
+    const expHash = expectedByPath.get(key);
+    const relPath = relative(cacheDir, a.absFile).split(sep).join("/");
+    if (expHash === void 0 || expHash === null) {
+      insertLeaf(doc, a.path, {
+        type: "new",
+        actualFilename: relPath,
+        patchSnapshotJsonFile: snapshotFile
+      });
+      summary.new++;
+      continue;
+    }
+    if (expHash === hash2) {
+      summary.unchanged++;
+      continue;
+    }
+    insertLeaf(doc, a.path, {
+      type: "change",
+      expectedHash: expHash,
+      actualFilename: relPath,
+      patchSnapshotJsonFile: snapshotFile
+    });
+    summary.change++;
+  }
+  for (const [key, hash2] of expectedByPath) {
+    if (seen.has(key) || !hash2) continue;
+    insertLeaf(doc, key.split("/"), {
+      type: "deleted",
+      expectedHash: hash2,
+      patchSnapshotJsonFile: snapshotFile
+    });
+    summary.deleted++;
+  }
+  await fs4.mkdir(cacheDir, { recursive: true });
+  await fs4.writeFile(docFile, JSON.stringify(doc, null, 2));
+  const total = countLeaves(doc);
+  process.stdout.write(
+    `Wrote ${docFile}
+  ${total} diff${total === 1 ? "" : "s"} to review (new: ${summary.new}, change: ${summary.change}, deleted: ${summary.deleted}, unchanged: ${summary.unchanged})
+`
+  );
+  return total;
+}
+function ensureDockerImage() {
+  const r = spawnSync("docker", ["image", "inspect", DOCKER_IMAGE], { stdio: "pipe" });
+  if (r.status !== 0) {
+    process.stderr.write(
+      `Docker image "${DOCKER_IMAGE}" not found.
+  Build it first:  pnpm exec screentest init && docker build -f Dockerfile.tests -t screentest-tests .
+  Or run host-side: pnpm exec screentest test --host
+`
+    );
+    return false;
+  }
+  return true;
+}
+async function runVitestInDocker(snapshotFile, cacheDir) {
+  const dockerArgs = ["run", "--rm", "--init", "--network=host"];
+  dockerArgs.push("-e", `APP_URL=${process.env.APP_URL || "http://localhost:5050"}`);
+  if (process.env.CI) dockerArgs.push("-e", "CI=1");
+  dockerArgs.push(
+    "-v",
+    `${cacheDir}:/work/node_modules/.cache/screentest`,
+    "-v",
+    `${snapshotFile}:/work/snapshot.json`,
+    DOCKER_IMAGE
+  );
+  return run("docker", dockerArgs);
+}
+async function runOrchestrator(opts = {}) {
+  const paths = resolveRunnerPaths();
+  if (opts.reviewOnly) {
+    const total = await generateDoc(paths.snapshotFile, paths.actualDir, paths.docFile, paths.cacheDir);
+    if (total === 0) {
+      process.stdout.write("Nothing to review \u2014 all snapshots match.\n");
+      return 0;
+    }
+    return await run("node", [process.argv[1], paths.docFile]);
+  }
+  await fs4.mkdir(paths.cacheDir, { recursive: true });
+  try {
+    await fs4.access(paths.snapshotFile);
+  } catch {
+    await fs4.writeFile(paths.snapshotFile, '{\n  "groups": []\n}\n');
+  }
+  await fs4.rm(paths.actualDir, { recursive: true, force: true });
+  let testCode;
+  if (opts.hostMode) {
+    testCode = await run("pnpm", ["exec", "vitest", "run"]);
+  } else {
+    if (opts.requireDockerImage !== false && !ensureDockerImage()) {
+      return 1;
+    }
+    testCode = await runVitestInDocker(paths.snapshotFile, paths.cacheDir);
+  }
+  if (testCode !== 0 && !process.env.CI) {
+    process.stderr.write(
+      "\n\u2192 Tests failed \u2014 launching screentest for review.\n  Close the tool (Ctrl+C) when done; the original failure will still propagate.\n\n"
+    );
+    const total = await generateDoc(paths.snapshotFile, paths.actualDir, paths.docFile, paths.cacheDir);
+    if (total > 0) {
+      const reviewCode = await run("node", [process.argv[1], paths.docFile]);
+      if (reviewCode !== 0 && reviewCode !== 130) {
+        process.stderr.write(`
+(screentest exited with code ${reviewCode})
+`);
+      }
+    } else {
+      process.stderr.write(
+        "\n(no diffs to review \u2014 vitest may have failed before any screenshot)\n"
+      );
+    }
+  }
+  return testCode;
+}
+
+// src/init.ts
+import { copyFile, mkdir } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+import { dirname as dirname4, join as join4, resolve as resolve6 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+async function runInit() {
+  const here = dirname4(fileURLToPath2(import.meta.url));
+  const templatesDir = [resolve6(here, "../templates"), resolve6(here, "../../templates")].find((p) => existsSync2(p)) ?? resolve6(here, "../templates");
+  const cwd = process.cwd();
+  const targets = [
+    { from: "Dockerfile.tests", to: "Dockerfile.tests" },
+    { from: "vitest.config.ts", to: "vitest.config.ts" },
+    { from: "example.test.ts", to: "tests/example.test.ts" }
+  ];
+  for (const { from, to } of targets) {
+    const src = join4(templatesDir, from);
+    const dst = join4(cwd, to);
+    if (existsSync2(dst)) {
+      process.stdout.write(`  exists  ${to}
+`);
+      continue;
+    }
+    if (!existsSync2(src)) {
+      process.stdout.write(`  missing ${from} (package install incomplete?)
+`);
+      continue;
+    }
+    await mkdir(dirname4(dst), { recursive: true });
+    await copyFile(src, dst);
+    process.stdout.write(`  wrote   ${to}
+`);
+  }
+  process.stdout.write(
+    `
+Next steps:
+  1. docker build -f Dockerfile.tests -t screentest-tests .
+  2. APP_URL=http://localhost:<your-app-port> pnpm exec screentest test
+`
+  );
+  return 0;
+}
+
+// src/index.ts
+function printHelp() {
+  process.stderr.write(
+    [
+      "Usage:",
+      "  screentest <doc-json-path> [--port 5174] [--no-open] [--worker-url URL] [--token TOKEN]",
+      "                              open the review UI on an existing doc.json",
+      "",
+      "  screentest test [--host]    run vitest, on failure regenerate doc.json + open UI",
+      "                              default: vitest inside Docker (network=host)",
+      "                              --host:  vitest on host (debug only, bytes diverge from CI)",
+      "",
+      "  screentest review           regenerate doc.json from cached actuals + open UI",
+      "",
+      "  screentest init             scaffold Dockerfile.tests, vitest.config.ts,",
+      "                              and tests/example.test.ts into the current project",
+      "",
+      "Env vars (UI mode):",
+      "  CLOUDFLARE_WORKER_URL   default https://screentests.x-cevek.workers.dev",
+      "  CLOUDFLARE_TOKEN        default SECRET_123",
+      "",
+      "Env vars (test mode):",
+      "  APP_URL                 default http://localhost:5050",
+      "  CI                      if set, do not auto-open the review UI on failure",
+      ""
+    ].join("\n")
+  );
+}
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+    printHelp();
+    process.exit(argv.length === 0 ? 1 : 0);
+  }
+  const cmd = argv[0];
+  if (cmd === "test") {
+    const rest = argv.slice(1);
+    const hostMode = rest.includes("--host");
+    const code = await runOrchestrator({ hostMode });
+    process.exit(code);
+    return;
+  }
+  if (cmd === "review") {
+    const code = await runOrchestrator({ reviewOnly: true });
+    process.exit(code);
+    return;
+  }
+  if (cmd === "init") {
+    const code = await runInit();
+    process.exit(code);
+    return;
+  }
+  const opts = parseUIArgs(argv);
+  await runUI(opts);
+}
 main().catch((err) => {
   const e = err instanceof Error ? err : new Error(String(err));
   process.stderr.write(`Fatal: ${e.message}

package/dist/runner.d.ts

@@ -0,0 +1,41 @@
+import type { BrowserContext, BrowserContextOptions, Page } from 'playwright';
+
+/**
+ * Capture a full-page PNG, save under
+ * `<project>/node_modules/.cache/screentest/actual/<...path>.png`, and
+ * compare its SHA256 against the hash in `<project>/snapshot.json`.
+ *
+ * The snapshot path is built automatically from the surrounding
+ * `describe(...)` + `it(...)` chain, plus `name` as the leaf. Prefix `name`
+ * with `/` to opt out of auto-grouping and use an absolute path.
+ */
+export function compareSnapshot(page: Page, name: string): Promise<void>;
+
+/**
+ * Freeze `Date` inside `ctx`. `when` may be an ISO string, unix-ms number,
+ * or `Date`. Must be called BEFORE the first navigation in the context.
+ */
+export function freezeDate(
+  ctx: BrowserContext,
+  when: string | number | Date,
+): Promise<void>;
+
+/**
+ * Wait for `document.fonts.ready` and every `<img>` to reach `complete`.
+ * Called automatically inside `compareSnapshot`; exported for cases where
+ * you take screenshots through other means.
+ */
+export function waitForVisualStable(page: Page): Promise<void>;
+
+export interface NewPageResult {
+  ctx: BrowserContext;
+  page: Page;
+  cleanup(): Promise<void>;
+}
+
+/**
+ * Connect to the shared Firefox browserServer (launched once per run by
+ * `@cevek/screentest/global-setup`), create a fresh context + page, return
+ * them along with a cleanup callback. Call in `beforeAll` in each test file.
+ */
+export function newPage(opts?: BrowserContextOptions): Promise<NewPageResult>;

package/dist/runner.js

@@ -0,0 +1,164 @@
+// src/runner/snapshot.ts
+import { createHash } from "crypto";
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { dirname, join as join2 } from "path";
+import { expect } from "vitest";
+
+// src/runner/paths.ts
+import { join, resolve } from "path";
+function resolveRunnerPaths(cwd = process.cwd()) {
+  const projectRoot = resolve(cwd);
+  const cacheDir = join(projectRoot, "node_modules", ".cache", "screentest");
+  return {
+    projectRoot,
+    snapshotFile: join(projectRoot, "snapshot.json"),
+    cacheDir,
+    actualDir: join(cacheDir, "actual"),
+    docFile: join(cacheDir, "doc.json")
+  };
+}
+
+// src/runner/stabilize.ts
+async function freezeDate(ctx, when) {
+  const fixedMs = when instanceof Date ? when.getTime() : typeof when === "number" ? when : Date.parse(when);
+  if (!Number.isFinite(fixedMs)) {
+    throw new Error(`freezeDate: invalid "when" value: ${String(when)}`);
+  }
+  await ctx.addInitScript(initScript, { fixedMs });
+}
+async function waitForVisualStable(page) {
+  await page.evaluate(async () => {
+    if (document.fonts && typeof document.fonts.ready?.then === "function") {
+      await document.fonts.ready;
+    }
+    const imgs = Array.from(document.images);
+    await Promise.all(
+      imgs.map(
+        (img) => img.complete && img.naturalWidth > 0 ? Promise.resolve() : new Promise((resolve2) => {
+          const done = () => {
+            img.removeEventListener("load", done);
+            img.removeEventListener("error", done);
+            resolve2();
+          };
+          img.addEventListener("load", done);
+          img.addEventListener("error", done);
+        })
+      )
+    );
+  });
+}
+function initScript(opts) {
+  const fixed = opts.fixedMs;
+  const RealDate = Date;
+  function FakeDate(...args) {
+    if (!(this instanceof FakeDate)) {
+      return new RealDate(fixed).toString();
+    }
+    return args.length === 0 ? new RealDate(fixed) : new RealDate(...args);
+  }
+  FakeDate.prototype = RealDate.prototype;
+  FakeDate.now = () => fixed;
+  FakeDate.parse = RealDate.parse;
+  FakeDate.UTC = RealDate.UTC;
+  globalThis.Date = FakeDate;
+}
+
+// src/runner/snapshot.ts
+function isGroup(x) {
+  return Array.isArray(x.items);
+}
+var cachedSnapshot = null;
+async function loadSnapshot(snapshotFile) {
+  if (cachedSnapshot) return cachedSnapshot;
+  try {
+    const raw = await readFile(snapshotFile, "utf8");
+    cachedSnapshot = JSON.parse(raw);
+  } catch {
+    cachedSnapshot = { groups: [] };
+  }
+  return cachedSnapshot;
+}
+function findExpected(snap, path) {
+  let groups = snap.groups;
+  for (let i = 0; i < path.length - 1; i++) {
+    const segment = path[i];
+    const next = groups.find((it) => isGroup(it) && it.name === segment);
+    if (!next) return void 0;
+    groups = next.items;
+  }
+  const leaf = groups.find(
+    (it) => !isGroup(it) && it.name === path[path.length - 1]
+  );
+  return leaf ? leaf.hash : void 0;
+}
+function currentTestChain() {
+  const full = expect.getState().currentTestName ?? "";
+  if (!full) return [];
+  return full.split(" > ");
+}
+async function compareSnapshot(page, name) {
+  const explicit = name.split("/").filter(Boolean);
+  const path = name.startsWith("/") ? explicit : [...currentTestChain(), ...explicit];
+  if (path.length === 0) throw new Error("compareSnapshot: empty name");
+  const paths = resolveRunnerPaths();
+  const fileRelative = `${path.join("/")}.png`;
+  const absFile = join2(paths.actualDir, fileRelative);
+  await mkdir(dirname(absFile), { recursive: true });
+  await waitForVisualStable(page);
+  const actualBuf = await page.screenshot({
+    fullPage: true,
+    type: "png",
+    animations: "disabled",
+    caret: "hide"
+  });
+  await writeFile(absFile, actualBuf);
+  const actualHash = createHash("sha256").update(actualBuf).digest("hex");
+  const expectedHash = findExpected(await loadSnapshot(paths.snapshotFile), path);
+  if (expectedHash === void 0 || expectedHash === null) {
+    expect.soft(
+      null,
+      `Snapshot "${name}" is NEW (hash ${actualHash.slice(0, 12)}\u2026). Run \`screentest review\` to accept it.`
+    ).toBeTruthy();
+    return;
+  }
+  if (actualHash !== expectedHash) {
+    expect.soft(actualHash, `Snapshot "${name}" changed. Run \`screentest review\` to inspect.`).toBe(expectedHash);
+  }
+}
+
+// src/runner/browser.ts
+import { inject } from "vitest";
+import {
+  firefox
+} from "playwright";
+var browserPromise = null;
+async function getBrowser() {
+  if (!browserPromise) {
+    const wsEndpoint = inject("wsEndpoint");
+    browserPromise = firefox.connect(wsEndpoint);
+  }
+  return browserPromise;
+}
+async function newPage(opts = {}) {
+  const browser = await getBrowser();
+  const ctx = await browser.newContext({
+    viewport: { width: 1280, height: 800 },
+    deviceScaleFactor: 1,
+    reducedMotion: "reduce",
+    ...opts
+  });
+  const page = await ctx.newPage();
+  return {
+    ctx,
+    page,
+    cleanup: async () => {
+      await ctx.close();
+    }
+  };
+}
+export {
+  compareSnapshot,
+  freezeDate,
+  newPage,
+  waitForVisualStable
+};

package/dist/templates/Dockerfile.tests

@@ -0,0 +1,19 @@
+FROM mcr.microsoft.com/playwright:v1.60.0-noble
+
+WORKDIR /work
+
+# Install pnpm — if your project uses npm/yarn, swap the next two lines.
+RUN npm install -g pnpm@9
+
+# Install dependencies. --ignore-scripts skips your project's postinstall
+# hooks (which usually scan src/ — not needed for the test image).
+COPY package.json pnpm-lock.yaml ./
+COPY pnpm-workspace.yaml* ./
+RUN pnpm install --frozen-lockfile --ignore-scripts
+
+# Only the bits needed to run vitest.
+COPY vitest.config.ts ./
+COPY tsconfig*.json ./
+COPY tests ./tests
+
+CMD ["pnpm", "exec", "vitest", "run"]

package/dist/templates/example.test.ts

@@ -0,0 +1,27 @@
+import { afterAll, beforeAll, describe, it } from 'vitest';
+import type { Page } from 'playwright';
+import { compareSnapshot, freezeDate, newPage } from '@cevek/screentest/runner';
+
+const APP_URL = (process.env.APP_URL || 'http://localhost:5050').replace(/\/+$/, '');
+
+let page: Page;
+let cleanup: () => Promise<void>;
+
+beforeAll(async () => {
+  const r = await newPage();
+  // Optional: pin client clock so any rendered timestamp is byte-stable.
+  await freezeDate(r.ctx, '2024-01-15T12:00:00Z');
+  page = r.page;
+  cleanup = r.cleanup;
+});
+
+afterAll(async () => {
+  await cleanup?.();
+});
+
+describe('home', () => {
+  it('loads', async () => {
+    await page.goto(`${APP_URL}/`, { waitUntil: 'domcontentloaded' });
+    await compareSnapshot(page, 'home');
+  });
+});

package/dist/templates/vitest.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['tests/**/*.test.ts'],
+    globalSetup: ['@cevek/screentest/global-setup'],
+    testTimeout: 10_000,
+    hookTimeout: 10_000,
+    pool: 'forks',
+    poolOptions: { forks: { singleFork: true } },
+    fileParallelism: false,
+  },
+});

package/package.json

@@ -3,19 +3,29 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.0",
-  "description": "Local desktop tool for visual screenshot-test review — Express + React UI shipped as a single CLI.",
+  "version": "0.2.0",
+  "description": "Local desktop tool for visual screenshot-test review — CLI, runner helpers, and review UI shipped as a single package.",
   "license": "MIT",
   "type": "module",
   "bin": {
     "screentest": "dist/index.js"
   },
+  "exports": {
+    "./runner": {
+      "types": "./dist/runner.d.ts",
+      "import": "./dist/runner.js"
+    },
+    "./global-setup": {
+      "types": "./dist/global-setup.d.ts",
+      "import": "./dist/global-setup.js"
+    }
+  },
   "files": [
     "dist",
     "README.md"
   ],
   "scripts": {
-    "build": "tsup && node scripts/copy-web.mjs",
+    "build": "tsup && node scripts/postbuild.mjs",
     "start": "node dist/index.js",
     "typecheck": "tsc --noEmit"
   },
@@ -23,12 +33,18 @@
     "express": "^5.2.1",
     "open": "^11.0.0"
   },
+  "peerDependencies": {
+    "playwright": "^1.50.0",
+    "vitest": "^3.0.0 || ^4.0.0"
+  },
   "devDependencies": {
     "@screentest/shared": "workspace:*",
     "@types/express": "^5.0.6",
     "@types/node": "^25.9.1",
+    "playwright": "^1.50.0",
     "tsup": "^8.5.1",
     "tsx": "^4.22.4",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "vitest": "^4.0.0"
   }
 }