@cevek/screentest 0.2.5 → 0.3.1

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 = {};
@@ -14554,7 +14554,15 @@ var groupItemSchema = external_exports.lazy(
     items: external_exports.array(external_exports.union([groupItemSchema, diffItemSchema])).min(0)
   })
 );
+var projectInfoSchema = external_exports.object({
+  /** Absolute path to the project root the doc.json was generated from. */
+  path: external_exports.string(),
+  /** Current git branch, or `null` if not a git repo (or `git` not on PATH). */
+  branch: external_exports.string().nullable()
+});
 var docSchema = external_exports.object({
+  /** Optional for backward compatibility with pre-0.3 doc.json files. */
+  project: projectInfoSchema.optional(),
   groups: external_exports.array(groupItemSchema)
 });
 var snapshotTestSchema = external_exports.object({
@@ -14573,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)
@@ -14645,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
@@ -14677,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();
@@ -14684,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;
@@ -14754,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();
@@ -14804,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);
 }
@@ -14839,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 {
@@ -14856,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 {
@@ -14927,14 +14958,14 @@ function acceptRoute(state) {
 
 // src/server.ts
 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;
@@ -15026,8 +15057,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");
@@ -15092,14 +15123,227 @@ async function runUI(opts) {
 }
 
 // src/orchestrator.ts
-import { spawn, spawnSync } from "child_process";
+import { spawn as spawn2 } from "child_process";
 import { promises as fs5 } from "fs";
-import { join as join4 } from "path";
+import { dirname as dirname6 } from "path";
+
+// src/daemon.ts
+import { spawn, spawnSync } from "child_process";
+import { existsSync as existsSync2 } from "fs";
+import { dirname as dirname5, resolve as resolve6 } from "path";
+import { fileURLToPath as fileURLToPath3 } 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 = dirname5(fileURLToPath3(import.meta.url));
+  const candidates = [
+    resolve6(here, "./templates"),
+    resolve6(here, "../templates"),
+    resolve6(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/doc-builder.ts
+import { spawnSync as spawnSync2 } 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"], {
+    stdio: "pipe",
+    encoding: "utf8"
+  });
+  if (r.status !== 0) return null;
+  const branch = r.stdout.trim();
+  return branch || null;
+}
 function isGroup(node) {
   return Array.isArray(node.items);
 }
@@ -15163,12 +15407,15 @@ function countLeaves(doc) {
   for (const g of doc.groups) walk(g.items);
   return n;
 }
-async function generateDoc(snapshotFile, actualDir, docFile, cacheDir) {
+async function generateDoc(projectRoot, 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 doc = {
+    project: { path: projectRoot, branch: detectBranch(projectRoot) },
+    groups: []
+  };
   const summary = { new: 0, change: 0, deleted: 0, unchanged: 0 };
   for (const a of actuals) {
     const buf = await fs4.readFile(a.absFile);
@@ -15219,135 +15466,42 @@ async function generateDoc(snapshotFile, actualDir, docFile, cacheDir) {
 }
 
 // src/runner/paths.ts
-import { join as join3, resolve as resolve5 } from "path";
+import { existsSync as existsSync3 } from "fs";
+import { isAbsolute as isAbsolute2, join as join3, resolve as resolve7 } from "path";
 function resolveRunnerPaths(cwd = process.cwd()) {
-  const projectRoot = resolve5(cwd);
+  const projectRoot = resolve7(cwd);
   const cacheDir = join3(projectRoot, "node_modules", ".cache", "screentest");
   return {
     projectRoot,
-    snapshotFile: join3(projectRoot, "snapshot.json"),
+    snapshotFile: resolveSnapshotFile(projectRoot),
     cacheDir,
     actualDir: join3(cacheDir, "actual"),
     docFile: join3(cacheDir, "doc.json")
   };
 }
+function resolveSnapshotFile(projectRoot) {
+  const envPath = process.env.SCREENTEST_SNAPSHOT_FILE;
+  if (envPath) {
+    return isAbsolute2(envPath) ? envPath : join3(projectRoot, envPath);
+  }
+  const legacyRoot = join3(projectRoot, "snapshot.json");
+  const insideTests = join3(projectRoot, "tests", "snapshot.json");
+  if (existsSync3(legacyRoot) && !existsSync3(insideTests)) return legacyRoot;
+  return insideTests;
+}
 
 // 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 run2(cmd, argv, env) {
+  return new Promise((resolveExit) => {
+    const p = spawn2(cmd, argv, { stdio: "inherit", env: env ?? process.env });
+    p.on("exit", (code) => resolveExit(code ?? 0));
   });
 }
-async function exists(absPath) {
-  try {
-    await fs5.access(absPath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-async function ensureDockerImageFresh(projectRoot) {
-  const dockerfile = join4(projectRoot, "Dockerfile.tests");
-  if (!await exists(dockerfile)) {
-    process.stderr.write(
-      `Dockerfile.tests not found at ${dockerfile}
-  Did you run \`screentest init\` in this project?
-`
-    );
-    return false;
-  }
-  const inspect = spawnSync(
-    "docker",
-    ["image", "inspect", "--format", "{{.Created}}", DOCKER_IMAGE],
-    { stdio: "pipe", encoding: "utf8" }
-  );
-  let reason = null;
-  if (inspect.status !== 0) {
-    reason = `Docker image "${DOCKER_IMAGE}" not found \u2014 building it (first build takes ~2 min).`;
-  } else {
-    const imageCreated = new Date(inspect.stdout.trim()).getTime();
-    const inputs = [
-      "package.json",
-      "pnpm-lock.yaml",
-      "package-lock.json",
-      "yarn.lock",
-      "Dockerfile.tests"
-    ];
-    for (const f of inputs) {
-      const abs = join4(projectRoot, f);
-      try {
-        const st = await fs5.stat(abs);
-        if (st.mtimeMs > imageCreated) {
-          reason = `${f} changed since the image was built \u2014 rebuilding.`;
-          break;
-        }
-      } catch {
-      }
-    }
-  }
-  if (!reason) return true;
-  process.stderr.write(`${reason}
-`);
-  const code = await run("docker", [
-    "build",
-    "-f",
-    "Dockerfile.tests",
-    "-t",
-    DOCKER_IMAGE,
-    projectRoot
-  ]);
-  if (code !== 0) {
-    process.stderr.write(`docker build failed (exit ${code})
-`);
-    return false;
-  }
-  return true;
-}
-async function runVitestInDocker(projectRoot, snapshotFile, cacheDir) {
-  const testsDir = join4(projectRoot, "tests");
-  const configFile = join4(projectRoot, "vitest.screentest.config.ts");
-  const tsconfigFile = join4(projectRoot, "tsconfig.json");
-  if (!await exists(testsDir)) {
-    process.stderr.write(
-      `tests/ not found at ${testsDir}
-  Did you run \`screentest init\` in this project?
-`
-    );
-    return 1;
-  }
-  if (!await exists(configFile)) {
-    process.stderr.write(
-      `vitest.screentest.config.ts not found at ${configFile}
-  Did you run \`screentest init\` in this project?
-`
-    );
-    return 1;
-  }
-  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`,
-    "-v",
-    `${testsDir}:/work/tests:ro`,
-    "-v",
-    `${configFile}:/work/vitest.screentest.config.ts:ro`
-  );
-  if (await exists(tsconfigFile)) {
-    dockerArgs.push("-v", `${tsconfigFile}:/work/tsconfig.json:ro`);
-  }
-  dockerArgs.push(DOCKER_IMAGE);
-  return run("docker", dockerArgs);
-}
 async function runOrchestrator(opts = {}) {
   const paths = resolveRunnerPaths();
   if (opts.reviewOnly) {
     const total = await generateDoc(
+      paths.projectRoot,
       paths.snapshotFile,
       paths.actualDir,
       paths.docFile,
@@ -15357,36 +15511,38 @@ async function runOrchestrator(opts = {}) {
       process.stdout.write("Nothing to review \u2014 all snapshots match.\n");
       return 0;
     }
-    return await run("node", [process.argv[1], paths.docFile]);
+    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(dirname6(paths.snapshotFile), { recursive: true });
     await fs5.writeFile(paths.snapshotFile, '{\n  "groups": []\n}\n');
   }
   await fs5.rm(paths.actualDir, { recursive: true, force: true });
-  let testCode;
-  if (opts.hostMode) {
-    testCode = await run("npx", ["vitest", "--config", "vitest.screentest.config.ts", "run"]);
-  } else {
-    if (opts.requireDockerImage !== false && !await ensureDockerImageFresh(paths.projectRoot)) {
-      return 1;
-    }
-    testCode = await runVitestInDocker(paths.projectRoot, paths.snapshotFile, paths.cacheDir);
+  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
+  );
   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 run("node", [process.argv[1], paths.docFile]);
+      const reviewCode = await run2("node", [process.argv[1], paths.docFile]);
       if (reviewCode !== 0 && reviewCode !== 130) {
         process.stderr.write(`
 (screentest exited with code ${reviewCode})
@@ -15402,52 +15558,32 @@ async function runOrchestrator(opts = {}) {
 }
 
 // src/init.ts
-import { copyFile, mkdir, readFile } from "fs/promises";
-import { existsSync as existsSync2 } from "fs";
-import { dirname as dirname4, join as join5, resolve as resolve6 } from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
-async function detectPackageManager(cwd) {
-  if (existsSync2(join5(cwd, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync2(join5(cwd, "yarn.lock"))) return "yarn";
-  if (existsSync2(join5(cwd, "package-lock.json"))) return "npm";
-  try {
-    const pkg = JSON.parse(
-      await readFile(join5(cwd, "package.json"), "utf8")
-    );
-    const pm = pkg.packageManager ?? "";
-    if (pm.startsWith("pnpm")) return "pnpm";
-    if (pm.startsWith("yarn")) return "yarn";
-  } catch {
-  }
-  return "npm";
-}
+import { copyFile, mkdir } from "fs/promises";
+import { existsSync as existsSync4 } from "fs";
+import { dirname as dirname7, join as join4, resolve as resolve8 } from "path";
+import { fileURLToPath as fileURLToPath4 } 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 here = dirname7(fileURLToPath4(import.meta.url));
+  const templatesDir = [resolve8(here, "./templates"), resolve8(here, "../templates")].find((p) => existsSync4(p)) ?? resolve8(here, "./templates");
   const cwd = process.cwd();
-  const pm = await detectPackageManager(cwd);
-  process.stdout.write(`Detected package manager: ${pm}
-
-`);
   const targets = [
-    { from: `Dockerfile.${pm}.tests`, to: "Dockerfile.tests" },
     { from: "vitest.screentest.config.ts", to: "vitest.screentest.config.ts" },
     { from: "example.test.ts", to: "tests/example.test.ts" }
   ];
   for (const { from, to } of targets) {
-    const src = join5(templatesDir, from);
-    const dst = join5(cwd, to);
-    if (existsSync2(dst)) {
+    const src = join4(templatesDir, from);
+    const dst = join4(cwd, to);
+    if (existsSync4(dst)) {
       process.stdout.write(`  exists  ${to}
 `);
       continue;
     }
-    if (!existsSync2(src)) {
+    if (!existsSync4(src)) {
       process.stdout.write(`  missing ${from} (package install incomplete?)
 `);
       continue;
     }
-    await mkdir(dirname4(dst), { recursive: true });
+    await mkdir(dirname7(dst), { recursive: true });
     await copyFile(src, dst);
     process.stdout.write(`  wrote   ${to}
 `);
@@ -15455,8 +15591,8 @@ async function runInit() {
   process.stdout.write(
     `
 Next steps:
-  1. docker build -f Dockerfile.tests -t screentest-tests .
-  2. APP_URL=http://localhost:<your-app-port> npx screentest test
+  1. screentest serve            # one-time: starts the shared Firefox daemon
+  2. APP_URL=http://localhost:<port> screentest test
 `
   );
   return 0;
@@ -15470,14 +15606,20 @@ function printHelp() {
       "  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 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",
       "",
-      "  screentest init             scaffold Dockerfile.tests, vitest.config.ts,",
-      "                              and tests/example.test.ts into the current project",
+      "  screentest serve            start the shared Firefox browser-server daemon",
+      "                              (builds the image on first run). One daemon per",
+      "                              machine \u2014 used by every project",
+      "  screentest stop             stop the daemon",
+      "  screentest status           show whether the daemon is running",
+      "",
+      "  screentest init             scaffold vitest.screentest.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",
@@ -15498,9 +15640,7 @@ async function main() {
   }
   const cmd = argv[0];
   if (cmd === "test") {
-    const rest = argv.slice(1);
-    const hostMode = rest.includes("--host");
-    const code = await runOrchestrator({ hostMode });
+    const code = await runOrchestrator();
     process.exit(code);
     return;
   }
@@ -15509,6 +15649,18 @@ async function main() {
     process.exit(code);
     return;
   }
+  if (cmd === "serve") {
+    process.exit(await startDaemon());
+    return;
+  }
+  if (cmd === "stop") {
+    process.exit(await stopDaemon());
+    return;
+  }
+  if (cmd === "status") {
+    process.exit(await printStatus());
+    return;
+  }
   if (cmd === "init") {
     const code = await runInit();
     process.exit(code);