chore(e2e): auto-run under xvfb-run when available

Add scripts/run-e2e.mjs which detects xvfb-run on PATH and wraps
playwright under it automatically so E2E tests don't steal focus from
the user's display. Falls back to direct invocation if xvfb-run is
absent (with an install hint). Set E2E_NO_XVFB=1 to force direct mode.

- package.json: test:e2e → node scripts/run-e2e.mjs
- ci.yml: drop explicit xvfb-run wrapper (script handles it)
- AGENTS.md: document xvfb-run behaviour in Dev loop table

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: JohnMcLear

.github/workflows/ci.yml

@@ -32,7 +32,7 @@ jobs:
       - run: pnpm install --frozen-lockfile
       - run: pnpm exec playwright install --with-deps chromium
       - run: pnpm build
-      - run: xvfb-run --auto-servernum pnpm test:e2e
+      - run: pnpm test:e2e
         env:
           CI: 'true'
       - uses: actions/upload-artifact@v4

AGENTS.md

@@ -22,7 +22,7 @@ Guidance for AI agents (Claude, Copilot, Cursor, etc.) working in this repo.
 | `pnpm format` | Prettier write. |
 | `pnpm test` | Vitest unit + component tests (single run). |
 | `pnpm test:watch` | Vitest watch mode. |
-| `pnpm test:e2e` | Playwright Electron E2E. Requires Etherpad on `:9003` (auto-spun by global setup). |
+| `pnpm test:e2e` | Playwright Electron E2E. Requires Etherpad on `:9003` (auto-spun by global setup). Auto-runs under `xvfb-run` when available so no windows steal focus. Set `E2E_NO_XVFB=1` to disable. |
 | `pnpm build` | Production build → `out/main`, `out/preload`, `out/renderer`. |
 | `pnpm package` | Build + electron-builder → AppImage + .deb under `release/`. |
 

package.json

@@ -21,7 +21,7 @@
     "format": "prettier --write src tests",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:e2e": "playwright test",
+    "test:e2e": "node scripts/run-e2e.mjs",
     "package": "electron-vite build && electron-builder --linux --config build/electron-builder.yml",
     "start": "electron-vite preview"
   },

scripts/run-e2e.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// Run Playwright E2E either under xvfb-run (if available) so the tests don't
+// steal focus from the user, or directly otherwise. Pass-through args.
+import { spawnSync } from 'node:child_process';
+
+const args = process.argv.slice(2);
+
+function which(bin) {
+  const r = spawnSync('which', [bin], { stdio: ['ignore', 'pipe', 'ignore'] });
+  return r.status === 0 ? r.stdout.toString().trim() : null;
+}
+
+const xvfb = which('xvfb-run');
+const playwrightArgs = ['exec', 'playwright', 'test', ...args];
+
+let cmd;
+let argv;
+if (xvfb && !process.env.E2E_NO_XVFB) {
+  cmd = xvfb;
+  argv = ['--auto-servernum', '--server-args=-screen 0 1280x800x24', 'pnpm', ...playwrightArgs];
+  console.error('[e2e] running under xvfb-run (set E2E_NO_XVFB=1 to disable)');
+} else {
+  cmd = 'pnpm';
+  argv = playwrightArgs;
+  if (!xvfb) {
+    console.error('[e2e] xvfb-run not found on PATH; tests will run on the visible display.');
+    console.error('[e2e] install with: sudo apt install xvfb');
+  }
+}
+
+const r = spawnSync(cmd, argv, { stdio: 'inherit' });
+process.exit(r.status ?? 1);