add headless playwright runner for AI agents

CLAUDE.md

@@ -15,14 +15,17 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - `npm run preview` - Preview production build
 
 **Testing:**
-- `npm run test:unit` - Run unit tests with Vitest
-- `npm run test:e2e` - Run end-to-end tests with Playwright
-- `npm run test` - Run both unit and e2e tests
-
-**Testing Guidelines:**
-- DO NOT run tests automatically (test:unit, test:e2e, test, etc.)
-- The user prefers to run all tests manually
-- Focus on implementing code changes and let the user handle testing
+- `npm run test:unit` - Run unit tests with Vitest (preview provider, opens in user's real browser)
+- `npm run test:headless` - Run unit tests with Vitest (playwright provider, headless background browser)
+- `npm run test` - Run unit tests once (preview provider)
+
+First time setup for `test:headless`: run `npx playwright install chromium` once after `npm install` to download the playwright chromium binary (~90 MB).
+
+**Testing guidelines for AI agents:**
+- ALWAYS use `npm run test:headless` when running tests. It runs in a background browser — no tabs in the user's real browser, no focus stealing, safe to invoke repeatedly.
+- Do NOT use `npm test` or `npm run test:unit`. Both use the preview provider, which opens a new tab in the user's real browser on every invocation and does not close it. Multiple runs accumulate tabs and steal focus.
+- Do not run tests in tight loops to "characterize flakiness." If a test fails once and passes when re-run alone, that's the test harness, not the code.
+- The user generally prefers to run tests themselves. Default to making code changes and letting them verify.
 
 **Implementation Guidelines:**
 - Do exactly what the user asks for - one step at a time

package.json

@@ -13,7 +13,8 @@
 		"format": "prettier --write .",
 		"lint": "prettier --check . && eslint .",
 		"test:unit": "vitest",
-		"test": "npm run test:unit -- --run"
+		"test": "npm run test:unit -- --run",
+		"test:headless": "vitest --config vitest.headless.config.js --run"
 	},
 	"files": [
 		"dist",
@@ -49,20 +50,22 @@
 		"@typescript-eslint/eslint-plugin": "^8.57.0",
 		"@typescript-eslint/parser": "^8.57.0",
 		"@vitest/browser": "^4.1.0",
+		"@vitest/browser-playwright": "4.1.5",
 		"@vitest/browser-preview": "^4.1.0",
 		"eslint": "^10.0.3",
 		"eslint-config-prettier": "^10.1.8",
 		"eslint-plugin-svelte": "^3.15.1",
 		"globals": "^17.4.0",
 		"nanoid": "^5.1.6",
+		"playwright": "^1.60.0",
 		"prettier": "^3.8.1",
 		"prettier-plugin-svelte": "^3.5.1",
 		"publint": "^0.3.18",
 		"svelte": "^5.53.12",
 		"svelte-check": "^4.4.5",
 		"typescript": "^5.9.3",
 		"vite": "^8.0.0",
-		"vitest": "^4.1.0",
+		"vitest": "4.1.5",
 		"vitest-browser-svelte": "^2.1.0"
 	}
 }

vitest.headless.config.js

@@ -0,0 +1,23 @@
+import { defineConfig } from 'vitest/config';
+import { playwright } from '@vitest/browser-playwright';
+import { sveltekit } from '@sveltejs/kit/vite';
+
+// Headless playwright config. Used by `npm run test:headless`, which is
+// what AI agents should call when running the test suite — runs in a
+// background browser, no tabs in the user's real browser, no focus
+// stealing. Humans keep using `npm test` (preview provider in their
+// real browser).
+export default defineConfig({
+	plugins: [sveltekit()],
+	test: {
+		browser: {
+			provider: playwright(),
+			enabled: true,
+			headless: true,
+			instances: [{ browser: 'chromium' }]
+		}
+	},
+	clearMocks: true,
+	include: ['src/**/*.svelte.{test,spec}.{js,ts}'],
+	exclude: ['src/lib/server/**']
+});