@cevek/screentest 0.2.4 → 0.3.0

package/README.md

@@ -1,13 +1,12 @@
 # @cevek/screentest
 
-Local desktop tool for visual screenshot-test review, **plus** the runner
-helpers and Docker-based test harness needed to actually capture the
+Local desktop tool for visual screenshot-test review **plus** the runner
+helpers and Docker-based browser harness needed to capture the
 screenshots. Everything ships in one npm package — no copy-paste.
 
 ## Install
 
 ```bash
-# pick your package manager — all three are supported:
 npm  i -D @cevek/screentest playwright vitest && npx  playwright install firefox
 # pnpm add -D @cevek/screentest playwright vitest && pnpm exec playwright install firefox
 # yarn add -D @cevek/screentest playwright vitest && yarn playwright install firefox
@@ -15,26 +14,31 @@ npm  i -D @cevek/screentest playwright vitest && npx  playwright install firefox
 
 `playwright` and `vitest` are peer-deps — keep them in your devDependencies.
 
-`screentest init` detects your package manager (from your lockfile or
-`packageManager` field) and writes a matching `Dockerfile.tests`.
-
 ## Quick start
 
 ```bash
-# 1. Scaffold the test harness into your project.
+# 1. Scaffold vitest.screentest.config.ts + tests/example.test.ts
 npx screentest init
 
-# 2. Build the Docker image once.
-docker build -f Dockerfile.tests -t screentest-tests .
+# 2. Start the shared Firefox daemon (one-time per machine — image builds
+#    on first run, ~2 min; cached forever after).
+npx screentest serve
 
 # 3. Run.
 APP_URL=http://localhost:5050 npx screentest test
 ```
 
+The daemon lives outside your project — one container serves every
+project on your machine. It listens on `ws://localhost:5180`, holds
+~300MB RAM at idle, and stays up across reboots-of-your-app until you
+`screentest stop` it.
+
+Your **tests run natively on the host** (your normal vitest + TS + path
+aliases + watch mode); only the Firefox rendering happens in the
+container, over a WebSocket. Editing tests never needs an image rebuild.
+
 `screentest init` creates:
 
-- `Dockerfile.tests` — playwright-noble + your project deps + vitest CMD
-  (auto-picked for pnpm / npm / yarn based on your lockfile)
 - `vitest.screentest.config.ts` — separate vitest config wired with the
   package's globalSetup. Kept under its own name so your normal
   `vitest.config.ts` (unit tests) is untouched.
@@ -49,33 +53,38 @@ and screenshot tests via `screentest test` stay completely separate.
 ## Commands
 
 ```bash
-screentest <doc-json-path> [--port 5174] [--no-open]
-                           [--worker-url URL] [--token TOKEN]
+screentest serve    # start the shared Firefox browser-server daemon
+screentest stop     # stop it
+screentest status   # is it running?
 ```
 
-Open the review UI on a pre-built `doc.json`. Used internally by `screentest
-test` and `screentest review`.
-
 ```bash
-screentest test [--host]
+screentest test
 ```
 
-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.
+Run vitest on the host, connect to the daemon for browser rendering.
+On failure (or new snapshots) auto-launch the review UI. Set `CI=1` to
+skip the auto-UI and just propagate the exit code.
 
 ```bash
 screentest review
 ```
 
-Skip vitest, just regenerate `doc.json` from cached actuals and open the UI.
+Skip vitest, regenerate `doc.json` from cached actuals, open the UI.
 
 ```bash
 screentest init
 ```
 
-Scaffold Dockerfile + vitest config + example test (see above).
+Scaffold vitest config + example test (see above).
+
+```bash
+screentest <doc-json-path> [--port 5174] [--no-open]
+                           [--worker-url URL] [--token TOKEN]
+```
+
+Open the review UI on a pre-built `doc.json`. Used internally by
+`screentest test` and `screentest review`.
 
 ## Writing tests
 
@@ -102,26 +111,33 @@ describe('team', () => {
     await page.goto(`${APP_URL}/team`);
     await page.locator('input[name="username"]').waitFor({ state: 'visible' });
     await compareSnapshot(page, 'login'); // → team / login flow / login
+
+    // Snapshot just one element instead of the whole page:
+    await compareSnapshot(page.locator('header'), 'header');
   });
 });
 ```
 
-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).
+Snapshot paths are auto-derived from `describe(...)` + `it(...)` plus the
+`compareSnapshot` leaf name. Hashes go into `tests/snapshot.json` by
+default; override with `SCREENTEST_SNAPSHOT_FILE=path/to/snapshot.json`.
+Actuals + the generated `doc.json` go to
+`node_modules/.cache/screentest/` (gitignored by convention).
+
+> **Upgrading from < 0.3:** an existing `<projectRoot>/snapshot.json` keeps
+> working — the runner picks it up if `tests/snapshot.json` isn't there yet.
 
 ## 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.
+The daemon container uses `--network=host` so its Firefox 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)
 
-Accepted screenshots are stored in your Cloudflare Worker (R2-backed). See
-the [worker template](https://github.com/x-cevek/screentest/tree/main/cloudflare-worker)
+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:
@@ -136,12 +152,12 @@ Or pass `--worker-url` / `--token` to `screentest` directly.
 ## CI
 
 ```yaml
-- run: docker build -f Dockerfile.tests -t screentest-tests .
+- run: npx screentest serve # builds image + starts daemon
 - run: CI=1 npx screentest test
 ```
 
-In `CI=1` the orchestrator exits with vitest's code and never tries to open
-the UI.
+In `CI=1` the orchestrator exits with vitest's code and never tries to
+open the UI.
 
 ## Input format reference
 

package/dist/global-setup.js

@@ -2,6 +2,13 @@
 import { firefox } from "playwright";
 var server;
 async function setup(project) {
+  const externalWs = process.env.SCREENTEST_FIREFOX_WS;
+  if (externalWs) {
+    project.provide("wsEndpoint", externalWs);
+    console.log(`[screentest] using external firefox daemon: ${externalWs}`);
+    return async () => {
+    };
+  }
   server = await firefox.launchServer();
   const wsEndpoint = server.wsEndpoint();
   project.provide("wsEndpoint", wsEndpoint);

package/dist/index.js

@@ -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({
@@ -15092,32 +15100,226 @@ async function runUI(opts) {
 }
 
 // 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";
+import { spawn as spawn2 } from "child_process";
+import { promises as fs5 } from "fs";
+import { dirname as dirname5 } 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";
+// 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((resolve7) => {
+  return new Promise((resolveExit) => {
     const p = spawn(cmd, argv, { stdio: "inherit" });
-    p.on("exit", (code) => resolve7(code ?? 0));
+    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/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);
@@ -15150,10 +15352,10 @@ async function walkActual(dir, prefix = []) {
   const out = [];
   for (const e of entries) {
     if (e.isDirectory()) {
-      out.push(...await walkActual(join3(dir, e.name), [...prefix, e.name]));
+      out.push(...await walkActual(join2(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) });
+      out.push({ path: [...prefix, stem], absFile: join2(dir, e.name) });
     }
   }
   return out;
@@ -15182,12 +15384,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);
@@ -15236,36 +15441,44 @@ async function generateDoc(snapshotFile, actualDir, docFile, cacheDir) {
   );
   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;
+
+// src/runner/paths.ts
+import { existsSync as existsSync3 } from "fs";
+import { isAbsolute as isAbsolute2, join as join3, resolve as resolve6 } from "path";
+function resolveRunnerPaths(cwd = process.cwd()) {
+  const projectRoot = resolve6(cwd);
+  const cacheDir = join3(projectRoot, "node_modules", ".cache", "screentest");
+  return {
+    projectRoot,
+    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);
   }
-  return true;
+  const legacyRoot = join3(projectRoot, "snapshot.json");
+  const insideTests = join3(projectRoot, "tests", "snapshot.json");
+  if (existsSync3(legacyRoot) && !existsSync3(insideTests)) return legacyRoot;
+  return insideTests;
 }
-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);
+
+// src/orchestrator.ts
+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 runOrchestrator(opts = {}) {
   const paths = resolveRunnerPaths();
   if (opts.reviewOnly) {
     const total = await generateDoc(
+      paths.projectRoot,
       paths.snapshotFile,
       paths.actualDir,
       paths.docFile,
@@ -15275,36 +15488,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 fs4.mkdir(paths.cacheDir, { recursive: true });
+  await fs5.mkdir(paths.cacheDir, { recursive: true });
   try {
-    await fs4.access(paths.snapshotFile);
+    await fs5.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("npx", ["vitest", "--config", "vitest.screentest.config.ts", "run"]);
-  } else {
-    if (opts.requireDockerImage !== false && !ensureDockerImage()) {
-      return 1;
-    }
-    testCode = await runVitestInDocker(paths.snapshotFile, paths.cacheDir);
-  }
+    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
+  );
   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})
@@ -15320,52 +15535,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 join4, resolve as resolve6 } from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
-async function detectPackageManager(cwd) {
-  if (existsSync2(join4(cwd, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync2(join4(cwd, "yarn.lock"))) return "yarn";
-  if (existsSync2(join4(cwd, "package-lock.json"))) return "npm";
-  try {
-    const pkg = JSON.parse(
-      await readFile(join4(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 dirname6, join as join4, resolve as resolve7 } from "path";
+import { fileURLToPath as fileURLToPath3 } 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 = dirname6(fileURLToPath3(import.meta.url));
+  const templatesDir = [resolve7(here, "./templates"), resolve7(here, "../templates")].find((p) => existsSync4(p)) ?? resolve7(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 = join4(templatesDir, from);
     const dst = join4(cwd, to);
-    if (existsSync2(dst)) {
+    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(dirname6(dst), { recursive: true });
     await copyFile(src, dst);
     process.stdout.write(`  wrote   ${to}
 `);
@@ -15373,8 +15568,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;
@@ -15388,14 +15583,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",
@@ -15416,9 +15617,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;
   }
@@ -15427,6 +15626,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);

package/dist/runner.js

@@ -5,18 +5,29 @@ import { dirname, join as join2 } from "path";
 import { expect } from "vitest";
 
 // src/runner/paths.ts
-import { join, resolve } from "path";
+import { existsSync } from "fs";
+import { isAbsolute, 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"),
+    snapshotFile: resolveSnapshotFile(projectRoot),
     cacheDir,
     actualDir: join(cacheDir, "actual"),
     docFile: join(cacheDir, "doc.json")
   };
 }
+function resolveSnapshotFile(projectRoot) {
+  const envPath = process.env.SCREENTEST_SNAPSHOT_FILE;
+  if (envPath) {
+    return isAbsolute(envPath) ? envPath : join(projectRoot, envPath);
+  }
+  const legacyRoot = join(projectRoot, "snapshot.json");
+  const insideTests = join(projectRoot, "tests", "snapshot.json");
+  if (existsSync(legacyRoot) && !existsSync(insideTests)) return legacyRoot;
+  return insideTests;
+}
 
 // src/runner/stabilize.ts
 async function freezeDate(ctx, when) {

package/dist/templates/Dockerfile.firefox-server

@@ -0,0 +1,25 @@
+# Universal screentest Firefox browser-server image.
+#
+# Used by `screentest serve` to run a long-lived headless Firefox in a Linux
+# container. Your tests run on the host (native vitest) and connect via
+# WebSocket — so PNG bytes are baked by Linux Firefox (CI-parity) while the
+# rest of your toolchain (TypeScript, deps, watch mode) stays on the host.
+#
+# The image is project-agnostic: it ONLY contains Playwright + Firefox + a
+# 10-line launch script. Rebuild only when the Playwright version pinned
+# below moves.
+
+FROM mcr.microsoft.com/playwright:v1.60.0-noble
+
+WORKDIR /work
+
+# Browsers are pre-installed at /ms-playwright in the base image; we only
+# need the JS package to use `firefox.launchServer(...)`.
+RUN npm init -y >/dev/null \
+ && npm install --no-audit --no-fund --no-progress playwright@1.60.0
+
+COPY launch-server.mjs ./
+
+EXPOSE 5180
+
+CMD ["node", "launch-server.mjs"]

package/dist/templates/launch-server.mjs

@@ -0,0 +1,22 @@
+// Long-lived headless Firefox browser-server. Tests on the host connect via
+// WS, see playwright.dev/docs/api/class-browsertype#browser-type-launch-server
+import { firefox } from 'playwright';
+
+const port = Number.parseInt(process.env.SCREENTEST_PORT ?? '5180', 10);
+const wsPath = process.env.SCREENTEST_WS_PATH ?? 'screentest-firefox';
+
+const server = await firefox.launchServer({
+  port,
+  host: '0.0.0.0',
+  wsPath,
+});
+
+console.log(`[screentest] firefox browser-server ready: ${server.wsEndpoint()}`);
+
+const shutdown = async (signal) => {
+  console.log(`[screentest] received ${signal}, closing browser-server`);
+  await server.close();
+  process.exit(0);
+};
+process.on('SIGTERM', () => void shutdown('SIGTERM'));
+process.on('SIGINT', () => void shutdown('SIGINT'));

package/dist/templates/vitest.screentest.config.ts

@@ -6,8 +6,11 @@ export default defineConfig({
     globalSetup: ['@cevek/screentest/global-setup'],
     testTimeout: 10_000,
     hookTimeout: 10_000,
+    // One file at a time: screenshot tests share a Firefox browserServer
+    // (launched in global-setup) and would collide if files ran in parallel.
+    // In vitest 4 `poolOptions` was removed; `fileParallelism: false` forces
+    // maxWorkers=1, which is the equivalent of the old `singleFork: true`.
     pool: 'forks',
-    poolOptions: { forks: { singleFork: true } },
     fileParallelism: false,
   },
 });

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.4",
+  "version": "0.3.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",

package/dist/templates/Dockerfile.npm.tests

@@ -1,17 +0,0 @@
-FROM mcr.microsoft.com/playwright:v1.60.0-noble
-
-WORKDIR /work
-
-# Install dependencies. --ignore-scripts skips your project's postinstall
-# hooks (which usually scan src/ — not needed for the test image).
-COPY package.json package-lock.json ./
-RUN npm ci --ignore-scripts
-
-# Only the bits needed to run vitest.
-COPY vitest.screentest.config.ts ./
-COPY tsconfig*.json ./
-COPY tests ./tests
-
-# Run vitest directly (skipping `npm exec`) — keeps the test image simple
-# and matches how the host orchestrator invokes it.
-CMD ["./node_modules/.bin/vitest", "--config", "vitest.screentest.config.ts", "run"]

package/dist/templates/Dockerfile.pnpm.tests

@@ -1,28 +0,0 @@
-FROM mcr.microsoft.com/playwright:v1.60.0-noble
-
-WORKDIR /work
-
-# corepack lets us use whatever pnpm version your project's `packageManager`
-# field pins (pnpm 11 by default in modern projects). If your project uses
-# npm or yarn instead, swap the install commands accordingly.
-RUN corepack enable
-
-# Install dependencies. Flags:
-#   --ignore-scripts        skips your project's postinstall hooks (which
-#                            usually scan src/ — not needed for the test image).
-#   --config.minimumReleaseAge=0  bypass pnpm 11's supply-chain policy for
-#                            freshly-published packages (the test image is
-#                            ephemeral, runs only what's already in lockfile).
-COPY package.json pnpm-lock.yaml ./
-COPY pnpm-workspace.yaml* ./
-RUN pnpm install --frozen-lockfile --ignore-scripts --config.minimumReleaseAge=0
-
-# Only the bits needed to run vitest.
-COPY vitest.screentest.config.ts ./
-COPY tsconfig*.json ./
-COPY tests ./tests
-
-# Run vitest directly (not via pnpm exec) — pnpm 11 re-runs its supply-chain
-# policy on every exec, which would re-fail freshly-published packages
-# even after install succeeded.
-CMD ["./node_modules/.bin/vitest", "--config", "vitest.screentest.config.ts", "run"]

package/dist/templates/Dockerfile.yarn.tests

@@ -1,21 +0,0 @@
-FROM mcr.microsoft.com/playwright:v1.60.0-noble
-
-WORKDIR /work
-
-# corepack lets yarn 2+/berry self-install from your project's
-# `packageManager` field. For yarn 1 it's a no-op (yarn is bundled in newer
-# Node images anyway).
-RUN corepack enable
-
-# Install dependencies. --ignore-scripts skips your project's postinstall
-# hooks (which usually scan src/ — not needed for the test image).
-COPY package.json yarn.lock ./
-COPY .yarnrc.yml* ./
-RUN yarn install --frozen-lockfile --ignore-scripts
-
-# Only the bits needed to run vitest.
-COPY vitest.screentest.config.ts ./
-COPY tsconfig*.json ./
-COPY tests ./tests
-
-CMD ["./node_modules/.bin/vitest", "--config", "vitest.screentest.config.ts", "run"]