@cevek/screentest 0.3.0 → 0.3.2

package/dist/index.js

@@ -7,7 +7,7 @@ var __export = (target, all) => {
 
 // src/ui.ts
 import { promises as fs3 } from "fs";
-import { dirname as dirname3, isAbsolute, resolve as resolve4 } from "path";
+import { dirname as dirname4, isAbsolute, resolve as resolve5 } from "path";
 
 // ../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/external.js
 var external_exports = {};
@@ -14581,7 +14581,9 @@ var snapshotDocSchema = external_exports.object({
 var apiDocResponseSchema = external_exports.object({
   doc: docSchema,
   expectedUrlPattern: external_exports.string(),
-  workerUrl: external_exports.string()
+  workerUrl: external_exports.string(),
+  /** `@cevek/screentest` package version that served this doc.json. */
+  serverVersion: external_exports.string()
 });
 var apiAcceptRequestSchema = external_exports.object({
   testId: external_exports.string().min(1)
@@ -14653,8 +14655,8 @@ function flatten(doc, docDir) {
 // src/server.ts
 import express from "express";
 import { existsSync } from "fs";
-import { dirname as dirname2, join, resolve as resolve3 } from "path";
-import { fileURLToPath } from "url";
+import { dirname as dirname3, join, resolve as resolve4 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
 import { createServer } from "http";
 
 // src/routes/doc.ts
@@ -14685,6 +14687,26 @@ function expectedUrlPattern(workerUrl) {
   return `${workerUrl}/{hash}.png`;
 }
 
+// src/version.ts
+import { readFileSync } from "fs";
+import { dirname, resolve as resolve2 } from "path";
+import { fileURLToPath } from "url";
+function readVersion() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const candidates = [resolve2(here, "../package.json"), resolve2(here, "../../package.json")];
+  for (const p of candidates) {
+    try {
+      const pkg = JSON.parse(readFileSync(p, "utf8"));
+      if (pkg.name === "@cevek/screentest" && typeof pkg.version === "string") {
+        return pkg.version;
+      }
+    } catch {
+    }
+  }
+  return "unknown";
+}
+var SCREENTEST_VERSION = readVersion();
+
 // src/routes/doc.ts
 function docRoute(state) {
   const r = Router();
@@ -14692,7 +14714,8 @@ function docRoute(state) {
     res.json({
       doc: state.doc,
       expectedUrlPattern: expectedUrlPattern(state.workerUrl),
-      workerUrl: state.workerUrl
+      workerUrl: state.workerUrl,
+      serverVersion: SCREENTEST_VERSION
     });
   });
   return r;
@@ -14762,7 +14785,7 @@ function sha256Hex(buf) {
 
 // src/patcher.ts
 import { promises as fs } from "fs";
-import { dirname, resolve as resolve2 } from "path";
+import { dirname as dirname2, resolve as resolve3 } from "path";
 var fileLocks = /* @__PURE__ */ new Map();
 async function withFileLock(absPath, fn) {
   const prev = fileLocks.get(absPath) ?? Promise.resolve();
@@ -14812,7 +14835,7 @@ function upsertHash(doc, path, hash2) {
 async function atomicWriteJson(absPath, data) {
   const json2 = JSON.stringify(data, null, 2);
   const tmp = `${absPath}.tmp-${process.pid}-${Date.now()}`;
-  await fs.mkdir(dirname(absPath), { recursive: true });
+  await fs.mkdir(dirname2(absPath), { recursive: true });
   await fs.writeFile(tmp, json2, "utf8");
   await fs.rename(tmp, absPath);
 }
@@ -14847,7 +14870,7 @@ function removeAtPath(doc, path) {
   return true;
 }
 async function removeFromSnapshot(args) {
-  const abs = resolve2(args.docDir, args.patchSnapshotJsonFile);
+  const abs = resolve3(args.docDir, args.patchSnapshotJsonFile);
   await withFileLock(abs, async () => {
     let doc;
     try {
@@ -14864,7 +14887,7 @@ async function removeFromSnapshot(args) {
   });
 }
 async function patchSnapshot(args) {
-  const abs = resolve2(args.docDir, args.patchSnapshotJsonFile);
+  const abs = resolve3(args.docDir, args.patchSnapshotJsonFile);
   await withFileLock(abs, async () => {
     let doc;
     try {
@@ -14933,28 +14956,60 @@ function acceptRoute(state) {
   return r;
 }
 
+// src/routes/shutdown.ts
+import { Router as Router4 } from "express";
+var EXIT_DELAY_MS = 2e3;
+var exitTimer = null;
+function scheduleExit() {
+  if (exitTimer) clearTimeout(exitTimer);
+  exitTimer = setTimeout(() => process.exit(0), EXIT_DELAY_MS);
+}
+function cancelPendingExit() {
+  if (exitTimer) {
+    clearTimeout(exitTimer);
+    exitTimer = null;
+  }
+}
+var cancelPendingShutdownMiddleware = (req, _res, next) => {
+  if (req.path !== "/shutdown") cancelPendingExit();
+  next();
+};
+function shutdownRoute() {
+  const r = Router4();
+  r.post("/shutdown", (_req, res) => {
+    res.status(204).end();
+    scheduleExit();
+  });
+  return r;
+}
+
 // src/server.ts
+var RANDOM_PORT_MIN = 4e4;
+var RANDOM_PORT_MAX = 5e4;
+var RANDOM_PICK_ATTEMPTS = 50;
 function resolveWebDist() {
-  const here = dirname2(fileURLToPath(import.meta.url));
+  const here = dirname3(fileURLToPath2(import.meta.url));
   const candidates = [
     // Published npm package: dist/index.js → ./web
-    resolve3(here, "./web"),
+    resolve4(here, "./web"),
     // Local monorepo build: apps/server/dist/index.js → ../../web/dist
-    resolve3(here, "../../web/dist"),
+    resolve4(here, "../../web/dist"),
     // Dev via tsx: apps/server/src/server.ts → ../../../apps/web/dist
-    resolve3(here, "../../../apps/web/dist")
+    resolve4(here, "../../../apps/web/dist")
   ];
   for (const c of candidates) {
     if (existsSync(join(c, "index.html"))) return c;
   }
   return null;
 }
-async function startServer(state, startPort) {
+async function startServer(state, requestedPort) {
   const app = express();
   app.use(express.json({ limit: "1mb" }));
+  app.use("/api", cancelPendingShutdownMiddleware);
   app.use("/api", docRoute(state));
   app.use("/api", actualRoute(state));
   app.use("/api", acceptRoute(state));
+  app.use("/api", shutdownRoute());
   const webDist = resolveWebDist();
   if (webDist) {
     app.use(express.static(webDist));
@@ -14962,7 +15017,7 @@ async function startServer(state, startPort) {
       res.sendFile(join(webDist, "index.html"));
     });
   }
-  const port = await findFreePort(startPort);
+  const port = requestedPort === 0 ? await pickRandomFreePort() : await findFreePort(requestedPort);
   const httpServer = createServer(app);
   await new Promise((resolveListen, rejectListen) => {
     httpServer.once("error", rejectListen);
@@ -14977,6 +15032,16 @@ async function startServer(state, startPort) {
     close: () => new Promise((r) => httpServer.close(() => r()))
   };
 }
+async function pickRandomFreePort() {
+  const span = RANDOM_PORT_MAX - RANDOM_PORT_MIN;
+  for (let attempt = 0; attempt < RANDOM_PICK_ATTEMPTS; attempt++) {
+    const p = RANDOM_PORT_MIN + Math.floor(Math.random() * span);
+    if (await isFree(p)) return p;
+  }
+  throw new Error(
+    `No free port in [${RANDOM_PORT_MIN}, ${RANDOM_PORT_MAX}) after ${RANDOM_PICK_ATTEMPTS} attempts`
+  );
+}
 async function findFreePort(start) {
   for (let p = start; p < start + 100; p++) {
     if (await isFree(p)) return p;
@@ -14996,10 +15061,9 @@ function isFree(port) {
 // src/ui.ts
 var DEFAULT_WORKER_URL = "https://screentests.x-cevek.workers.dev";
 var DEFAULT_TOKEN = "SECRET_123";
-var DEFAULT_PORT = 5174;
 function parseUIArgs(rawArgs) {
   let docPath = null;
-  let port = Number(process.env.PORT) || DEFAULT_PORT;
+  let port = Number(process.env.PORT) || 0;
   let doOpen = true;
   let workerUrl = process.env.CLOUDFLARE_WORKER_URL || DEFAULT_WORKER_URL;
   let token = process.env.CLOUDFLARE_TOKEN || DEFAULT_TOKEN;
@@ -15034,8 +15098,8 @@ function parseUIArgs(rawArgs) {
   };
 }
 async function runUI(opts) {
-  const docAbs = isAbsolute(opts.docPath) ? opts.docPath : resolve4(process.cwd(), opts.docPath);
-  const docDir = dirname3(docAbs);
+  const docAbs = isAbsolute(opts.docPath) ? opts.docPath : resolve5(process.cwd(), opts.docPath);
+  const docDir = dirname4(docAbs);
   let raw;
   try {
     raw = await fs3.readFile(docAbs, "utf8");
@@ -15099,221 +15163,16 @@ async function runUI(opts) {
   process.on("SIGTERM", shutdown);
 }
 
-// src/orchestrator.ts
-import { spawn as spawn2 } from "child_process";
-import { promises as fs5 } from "fs";
-import { dirname as dirname5 } from "path";
-
-// src/daemon.ts
-import { spawn, spawnSync } from "child_process";
-import { existsSync as existsSync2 } from "fs";
-import { dirname as dirname4, resolve as resolve5 } from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
-import { createConnection } from "net";
-var IMAGE_NAME = "cevek/screentest-firefox";
-var IMAGE_TAG = "pw-1.60.0";
-var FULL_IMAGE = `${IMAGE_NAME}:${IMAGE_TAG}`;
-var CONTAINER_NAME = "screentest-firefox";
-var PORT = 5180;
-var WS_PATH = "screentest-firefox";
-var WS_ENDPOINT = `ws://localhost:${PORT}/${WS_PATH}`;
-function run(cmd, argv) {
-  return new Promise((resolveExit) => {
-    const p = spawn(cmd, argv, { stdio: "inherit" });
-    p.on("exit", (code) => resolveExit(code ?? 0));
-  });
-}
-function daemonState() {
-  const ps = spawnSync(
-    "docker",
-    ["ps", "-a", "-f", `name=^${CONTAINER_NAME}$`, "--format", "{{.Status}}	{{.Image}}"],
-    { stdio: "pipe", encoding: "utf8" }
-  );
-  const line = ps.stdout.trim();
-  if (line.startsWith("Up")) {
-    const tab = line.indexOf("	");
-    const image = tab === -1 ? "" : line.slice(tab + 1).trim();
-    return { state: "running", image };
-  }
-  const img = spawnSync("docker", ["image", "inspect", FULL_IMAGE], { stdio: "pipe" });
-  if (img.status !== 0) return { state: "missing-image" };
-  return { state: "stopped" };
-}
-function resolveTemplatesDir() {
-  const here = dirname4(fileURLToPath2(import.meta.url));
-  const candidates = [
-    resolve5(here, "./templates"),
-    resolve5(here, "../templates"),
-    resolve5(here, "../../server/templates")
-  ];
-  for (const c of candidates) {
-    if (existsSync2(c)) return c;
-  }
-  throw new Error("templates/ directory not found relative to daemon.ts");
-}
-async function buildImage() {
-  const templates = resolveTemplatesDir();
-  process.stderr.write(`Building Docker image ${FULL_IMAGE} (~2 min first time, cached after).
-`);
-  const code = await run("docker", [
-    "build",
-    "-f",
-    `${templates}/Dockerfile.firefox-server`,
-    "-t",
-    FULL_IMAGE,
-    templates
-  ]);
-  if (code !== 0) {
-    process.stderr.write(`docker build failed (exit ${code})
-`);
-    return false;
-  }
-  return true;
-}
-function probePort() {
-  return new Promise((resolveProbe) => {
-    const s = createConnection({ host: "127.0.0.1", port: PORT });
-    s.once("connect", () => {
-      s.end();
-      resolveProbe(true);
-    });
-    s.once("error", () => resolveProbe(false));
-  });
-}
-async function waitForReady(timeoutMs = 1e4) {
-  const start = Date.now();
-  while (Date.now() - start < timeoutMs) {
-    if (await probePort()) return true;
-    await new Promise((r) => setTimeout(r, 150));
-  }
-  return false;
-}
-async function startDaemon() {
-  const s = daemonState();
-  if (s.state === "running") {
-    if (s.image !== FULL_IMAGE) {
-      process.stderr.write(
-        `screentest-firefox daemon is running, but on a different image:
-  running: ${s.image}
-  this @cevek/screentest wants: ${FULL_IMAGE}
-  \u2192 stop it first:  screentest stop
-  \u2192 then re-run:    screentest serve
-`
-      );
-      return 1;
-    }
-    process.stdout.write(`screentest-firefox daemon already running at ${WS_ENDPOINT}
-`);
-    return 0;
-  }
-  if (s.state === "missing-image") {
-    if (!await buildImage()) return 1;
-  }
-  spawnSync("docker", ["rm", "-f", CONTAINER_NAME], { stdio: "pipe" });
-  process.stderr.write(`Starting screentest-firefox daemon (port ${PORT})\u2026
-`);
-  const code = await run("docker", [
-    "run",
-    "-d",
-    "--rm",
-    "--name",
-    CONTAINER_NAME,
-    "--network=host",
-    FULL_IMAGE
-  ]);
-  if (code !== 0) {
-    process.stderr.write(`docker run failed (exit ${code})
-`);
-    return code;
-  }
-  if (!await waitForReady()) {
-    process.stderr.write(`Daemon container started but port ${PORT} never opened. Logs:
-`);
-    spawnSync("docker", ["logs", CONTAINER_NAME], { stdio: "inherit" });
-    return 1;
-  }
-  process.stdout.write(`screentest-firefox daemon ready at ${WS_ENDPOINT}
-`);
-  return 0;
-}
-async function stopDaemon() {
-  const s = daemonState();
-  if (s.state !== "running") {
-    process.stdout.write("screentest-firefox daemon is not running\n");
-    return 0;
-  }
-  const code = await run("docker", ["stop", CONTAINER_NAME]);
-  if (code === 0) process.stdout.write("screentest-firefox daemon stopped\n");
-  return code;
-}
-async function printStatus() {
-  const s = daemonState();
-  if (s.state === "running") {
-    const match = s.image === FULL_IMAGE ? "(matches this @cevek/screentest)" : "(MISMATCH!)";
-    process.stdout.write(
-      `screentest-firefox daemon: running
-  ws endpoint: ${WS_ENDPOINT}
-  image:       ${s.image} ${match}
-  expected:    ${FULL_IMAGE}
-`
-    );
-    if (s.image !== FULL_IMAGE) {
-      process.stdout.write(
-        `  \u2192 daemon is running an image pinned by a different version of this
-    package. Stop it (screentest stop) and re-serve from the project
-    whose Playwright version you want to use.
-`
-      );
-    }
-    return 0;
-  }
-  if (s.state === "stopped") {
-    process.stdout.write(
-      `screentest-firefox daemon: stopped (image ${FULL_IMAGE} exists)
-  start it with: screentest serve
-`
-    );
-    return 0;
-  }
-  process.stdout.write(
-    `screentest-firefox daemon: not installed (image ${FULL_IMAGE} missing)
-  build + start with: screentest serve
-`
-  );
-  return 0;
-}
-async function requireRunningDaemon() {
-  const s = daemonState();
-  if (s.state !== "running") {
-    process.stderr.write(
-      `screentest-firefox daemon is not running.
-  Start it once with:  screentest serve
-  It then stays alive across projects until you stop it.
-`
-    );
-    return false;
-  }
-  if (s.image !== FULL_IMAGE) {
-    process.stderr.write(
-      `screentest-firefox daemon is running with a different Playwright version:
-  running: ${s.image}
-  this @cevek/screentest expects: ${FULL_IMAGE}
-  \u2192 screentest stop && screentest serve
-    (or align package versions across projects sharing the daemon)
-`
-    );
-    return false;
-  }
-  return true;
-}
+// src/review.ts
+import { spawn } from "child_process";
 
 // src/doc-builder.ts
-import { spawnSync as spawnSync2 } from "child_process";
+import { spawnSync } from "child_process";
 import { createHash as createHash2 } from "crypto";
 import { promises as fs4 } from "fs";
 import { join as join2, relative, sep } from "path";
 function detectBranch(projectRoot) {
-  const r = spawnSync2("git", ["-C", projectRoot, "rev-parse", "--abbrev-ref", "HEAD"], {
+  const r = spawnSync("git", ["-C", projectRoot, "rev-parse", "--abbrev-ref", "HEAD"], {
     stdio: "pipe",
     encoding: "utf8"
   });
@@ -15443,7 +15302,7 @@ async function generateDoc(projectRoot, snapshotFile, actualDir, docFile, cacheD
 }
 
 // src/runner/paths.ts
-import { existsSync as existsSync3 } from "fs";
+import { existsSync as existsSync2 } from "fs";
 import { isAbsolute as isAbsolute2, join as join3, resolve as resolve6 } from "path";
 function resolveRunnerPaths(cwd = process.cwd()) {
   const projectRoot = resolve6(cwd);
@@ -15463,85 +15322,41 @@ function resolveSnapshotFile(projectRoot) {
   }
   const legacyRoot = join3(projectRoot, "snapshot.json");
   const insideTests = join3(projectRoot, "tests", "snapshot.json");
-  if (existsSync3(legacyRoot) && !existsSync3(insideTests)) return legacyRoot;
+  if (existsSync2(legacyRoot) && !existsSync2(insideTests)) return legacyRoot;
   return insideTests;
 }
 
-// src/orchestrator.ts
-function run2(cmd, argv, env) {
+// src/review.ts
+function run(cmd, argv) {
   return new Promise((resolveExit) => {
-    const p = spawn2(cmd, argv, { stdio: "inherit", env: env ?? process.env });
+    const p = spawn(cmd, argv, { stdio: "inherit" });
     p.on("exit", (code) => resolveExit(code ?? 0));
   });
 }
-async function runOrchestrator(opts = {}) {
+async function runReview() {
   const paths = resolveRunnerPaths();
-  if (opts.reviewOnly) {
-    const total = await generateDoc(
-      paths.projectRoot,
-      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 run2("node", [process.argv[1], paths.docFile]);
-  }
-  await fs5.mkdir(paths.cacheDir, { recursive: true });
-  try {
-    await fs5.access(paths.snapshotFile);
-  } catch {
-    await fs5.mkdir(dirname5(paths.snapshotFile), { recursive: true });
-    await fs5.writeFile(paths.snapshotFile, '{\n  "groups": []\n}\n');
-  }
-  await fs5.rm(paths.actualDir, { recursive: true, force: true });
-  if (!await requireRunningDaemon()) {
-    return 1;
-  }
-  const env = { ...process.env, SCREENTEST_FIREFOX_WS: WS_ENDPOINT };
-  const testCode = await run2(
-    "npx",
-    ["vitest", "--config", "vitest.screentest.config.ts", "run"],
-    env
+  const total = await generateDoc(
+    paths.projectRoot,
+    paths.snapshotFile,
+    paths.actualDir,
+    paths.docFile,
+    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.projectRoot,
-      paths.snapshotFile,
-      paths.actualDir,
-      paths.docFile,
-      paths.cacheDir
-    );
-    if (total > 0) {
-      const reviewCode = await run2("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"
-      );
-    }
+  if (total === 0) {
+    process.stdout.write("Nothing to review \u2014 all snapshots match.\n");
+    return 0;
   }
-  return testCode;
+  return await run("node", [process.argv[1], paths.docFile]);
 }
 
 // src/init.ts
 import { copyFile, mkdir } from "fs/promises";
-import { existsSync as existsSync4 } from "fs";
-import { dirname as dirname6, join as join4, resolve as resolve7 } from "path";
+import { existsSync as existsSync3 } from "fs";
+import { dirname as dirname5, join as join4, resolve as resolve7 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 async function runInit() {
-  const here = dirname6(fileURLToPath3(import.meta.url));
-  const templatesDir = [resolve7(here, "./templates"), resolve7(here, "../templates")].find((p) => existsSync4(p)) ?? resolve7(here, "./templates");
+  const here = dirname5(fileURLToPath3(import.meta.url));
+  const templatesDir = [resolve7(here, "./templates"), resolve7(here, "../templates")].find((p) => existsSync3(p)) ?? resolve7(here, "./templates");
   const cwd = process.cwd();
   const targets = [
     { from: "vitest.screentest.config.ts", to: "vitest.screentest.config.ts" },
@@ -15550,17 +15365,17 @@ async function runInit() {
   for (const { from, to } of targets) {
     const src = join4(templatesDir, from);
     const dst = join4(cwd, to);
-    if (existsSync4(dst)) {
+    if (existsSync3(dst)) {
       process.stdout.write(`  exists  ${to}
 `);
       continue;
     }
-    if (!existsSync4(src)) {
+    if (!existsSync3(src)) {
       process.stdout.write(`  missing ${from} (package install incomplete?)
 `);
       continue;
     }
-    await mkdir(dirname6(dst), { recursive: true });
+    await mkdir(dirname5(dst), { recursive: true });
     await copyFile(src, dst);
     process.stdout.write(`  wrote   ${to}
 `);
@@ -15569,7 +15384,190 @@ async function runInit() {
     `
 Next steps:
   1. screentest serve            # one-time: starts the shared Firefox daemon
-  2. APP_URL=http://localhost:<port> screentest test
+  2. APP_URL=http://localhost:<port> \\
+       npx vitest run --config vitest.screentest.config.ts
+
+Tip: add a script to package.json so you can just \`npm run screentest\`:
+  "screentest": "vitest run --config vitest.screentest.config.ts"
+`
+  );
+  return 0;
+}
+
+// src/daemon.ts
+import { spawn as spawn2, spawnSync as spawnSync2 } from "child_process";
+import { existsSync as existsSync4 } from "fs";
+import { dirname as dirname6, resolve as resolve8 } from "path";
+import { fileURLToPath as fileURLToPath4 } from "url";
+import { createConnection } from "net";
+var IMAGE_NAME = "cevek/screentest-firefox";
+var IMAGE_TAG = "pw-1.60.0";
+var FULL_IMAGE = `${IMAGE_NAME}:${IMAGE_TAG}`;
+var CONTAINER_NAME = "screentest-firefox";
+var PORT = 5180;
+var WS_PATH = "screentest-firefox";
+var WS_ENDPOINT = `ws://localhost:${PORT}/${WS_PATH}`;
+function run2(cmd, argv) {
+  return new Promise((resolveExit) => {
+    const p = spawn2(cmd, argv, { stdio: "inherit" });
+    p.on("exit", (code) => resolveExit(code ?? 0));
+  });
+}
+function daemonState() {
+  const ps = spawnSync2(
+    "docker",
+    ["ps", "-a", "-f", `name=^${CONTAINER_NAME}$`, "--format", "{{.Status}}	{{.Image}}"],
+    { stdio: "pipe", encoding: "utf8" }
+  );
+  const line = ps.stdout.trim();
+  if (line.startsWith("Up")) {
+    const tab = line.indexOf("	");
+    const image = tab === -1 ? "" : line.slice(tab + 1).trim();
+    return { state: "running", image };
+  }
+  const img = spawnSync2("docker", ["image", "inspect", FULL_IMAGE], { stdio: "pipe" });
+  if (img.status !== 0) return { state: "missing-image" };
+  return { state: "stopped" };
+}
+function resolveTemplatesDir() {
+  const here = dirname6(fileURLToPath4(import.meta.url));
+  const candidates = [
+    resolve8(here, "./templates"),
+    resolve8(here, "../templates"),
+    resolve8(here, "../../server/templates")
+  ];
+  for (const c of candidates) {
+    if (existsSync4(c)) return c;
+  }
+  throw new Error("templates/ directory not found relative to daemon.ts");
+}
+async function buildImage() {
+  const templates = resolveTemplatesDir();
+  process.stderr.write(`Building Docker image ${FULL_IMAGE} (~2 min first time, cached after).
+`);
+  const code = await run2("docker", [
+    "build",
+    "-f",
+    `${templates}/Dockerfile.firefox-server`,
+    "-t",
+    FULL_IMAGE,
+    templates
+  ]);
+  if (code !== 0) {
+    process.stderr.write(`docker build failed (exit ${code})
+`);
+    return false;
+  }
+  return true;
+}
+function probePort() {
+  return new Promise((resolveProbe) => {
+    const s = createConnection({ host: "127.0.0.1", port: PORT });
+    s.once("connect", () => {
+      s.end();
+      resolveProbe(true);
+    });
+    s.once("error", () => resolveProbe(false));
+  });
+}
+async function waitForReady(timeoutMs = 1e4) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (await probePort()) return true;
+    await new Promise((r) => setTimeout(r, 150));
+  }
+  return false;
+}
+async function startDaemon() {
+  const s = daemonState();
+  if (s.state === "running") {
+    if (s.image !== FULL_IMAGE) {
+      process.stderr.write(
+        `screentest-firefox daemon is running, but on a different image:
+  running: ${s.image}
+  this @cevek/screentest wants: ${FULL_IMAGE}
+  \u2192 stop it first:  screentest stop
+  \u2192 then re-run:    screentest serve
+`
+      );
+      return 1;
+    }
+    process.stdout.write(`screentest-firefox daemon already running at ${WS_ENDPOINT}
+`);
+    return 0;
+  }
+  if (s.state === "missing-image") {
+    if (!await buildImage()) return 1;
+  }
+  spawnSync2("docker", ["rm", "-f", CONTAINER_NAME], { stdio: "pipe" });
+  process.stderr.write(`Starting screentest-firefox daemon (port ${PORT})\u2026
+`);
+  const code = await run2("docker", [
+    "run",
+    "-d",
+    "--rm",
+    "--name",
+    CONTAINER_NAME,
+    "--network=host",
+    FULL_IMAGE
+  ]);
+  if (code !== 0) {
+    process.stderr.write(`docker run failed (exit ${code})
+`);
+    return code;
+  }
+  if (!await waitForReady()) {
+    process.stderr.write(`Daemon container started but port ${PORT} never opened. Logs:
+`);
+    spawnSync2("docker", ["logs", CONTAINER_NAME], { stdio: "inherit" });
+    return 1;
+  }
+  process.stdout.write(`screentest-firefox daemon ready at ${WS_ENDPOINT}
+`);
+  return 0;
+}
+async function stopDaemon() {
+  const s = daemonState();
+  if (s.state !== "running") {
+    process.stdout.write("screentest-firefox daemon is not running\n");
+    return 0;
+  }
+  const code = await run2("docker", ["stop", CONTAINER_NAME]);
+  if (code === 0) process.stdout.write("screentest-firefox daemon stopped\n");
+  return code;
+}
+async function printStatus() {
+  const s = daemonState();
+  if (s.state === "running") {
+    const match = s.image === FULL_IMAGE ? "(matches this @cevek/screentest)" : "(MISMATCH!)";
+    process.stdout.write(
+      `screentest-firefox daemon: running
+  ws endpoint: ${WS_ENDPOINT}
+  image:       ${s.image} ${match}
+  expected:    ${FULL_IMAGE}
+`
+    );
+    if (s.image !== FULL_IMAGE) {
+      process.stdout.write(
+        `  \u2192 daemon is running an image pinned by a different version of this
+    package. Stop it (screentest stop) and re-serve from the project
+    whose Playwright version you want to use.
+`
+      );
+    }
+    return 0;
+  }
+  if (s.state === "stopped") {
+    process.stdout.write(
+      `screentest-firefox daemon: stopped (image ${FULL_IMAGE} exists)
+  start it with: screentest serve
+`
+    );
+    return 0;
+  }
+  process.stdout.write(
+    `screentest-firefox daemon: not installed (image ${FULL_IMAGE} missing)
+  build + start with: screentest serve
 `
   );
   return 0;
@@ -15580,14 +15578,9 @@ function printHelp() {
   process.stderr.write(
     [
       "Usage:",
-      "  screentest <doc-json-path> [--port 5174] [--no-open] [--worker-url URL] [--token TOKEN]",
+      "  screentest <doc-json-path> [--port N] [--no-open] [--worker-url URL] [--token TOKEN]",
       "                              open the review UI on an existing doc.json",
-      "",
-      "  screentest test             run vitest on the host, connect to the shared",
-      "                              Firefox daemon, on failure regenerate doc.json",
-      "                              and open the review UI",
-      "",
-      "  screentest review           regenerate doc.json from cached actuals + open UI",
+      "                              (this is what `vitest run` auto-launches on failure)",
       "",
       "  screentest serve            start the shared Firefox browser-server daemon",
       "                              (builds the image on first run). One daemon per",
@@ -15595,16 +15588,29 @@ function printHelp() {
       "  screentest stop             stop the daemon",
       "  screentest status           show whether the daemon is running",
       "",
+      "  screentest review           regenerate doc.json from cached actuals + open UI",
+      "                              (useful when you closed the UI without accepting)",
+      "",
       "  screentest init             scaffold vitest.screentest.config.ts and",
       "                              tests/example.test.ts into the current project",
       "",
+      "Running screenshot tests:",
+      "  Add to your package.json scripts (or run directly):",
+      '    "screentest": "vitest run --config vitest.screentest.config.ts"',
+      "  The vitest globalSetup we ship handles pre-flight (wipe actualDir, locate",
+      "  the daemon) and post-flight (build doc.json, auto-launch the review UI",
+      "  if there are diffs).",
+      "",
       "Env vars (UI mode):",
       "  CLOUDFLARE_WORKER_URL   default https://screentests.x-cevek.workers.dev",
       "  CLOUDFLARE_TOKEN        default SECRET_123",
       "",
-      "Env vars (test mode):",
+      "Env vars (test runs):",
       "  APP_URL                 default http://localhost:5050",
       "  CI                      if set, do not auto-open the review UI on failure",
+      "  SCREENTEST_NO_UI        if set, never auto-open the review UI",
+      "  SCREENTEST_FIREFOX_WS   override the daemon WS endpoint",
+      "  SCREENTEST_SNAPSHOT_FILE override snapshot.json path (default tests/snapshot.json)",
       ""
     ].join("\n")
   );
@@ -15617,12 +15623,21 @@ async function main() {
   }
   const cmd = argv[0];
   if (cmd === "test") {
-    const code = await runOrchestrator();
-    process.exit(code);
+    process.stderr.write(
+      `\`screentest test\` was removed in 0.3.2 \u2014 the globalSetup hook now does
+everything it used to do. Run vitest directly instead:
+
+  npx vitest run --config vitest.screentest.config.ts
+
+Or add it as a script in package.json:
+  "screentest": "vitest run --config vitest.screentest.config.ts"
+`
+    );
+    process.exit(2);
     return;
   }
   if (cmd === "review") {
-    const code = await runOrchestrator({ reviewOnly: true });
+    const code = await runReview();
     process.exit(code);
     return;
   }