first commit

docs/devtools/tooling/test-vite/src/vitest-browser-config/vitest-browser-config.md

@@ -0,0 +1,52 @@
+# vitest-browser-config
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`createVitestBrowserConfig` builds a Vitest configuration that drives tests through Playwright in real browsers. The factory encodes the suaveplan rules for browser-mode tests: `pool: 'forks'`, `fileParallelism: false` (required so Playwright workers do not contend), `provider: 'playwright'`, and headless-by-default. Packages opting into the browser runner inherit a known-good baseline and only have to declare the browser matrix they need.
+
+## Features
+
+- Playwright provider with caller-supplied browser matrix (`chromium`, `firefox`, `webkit`).
+- Headless-by-default with explicit opt-out.
+- `fileParallelism: false` pinned by the spec.
+- Setup files accepted for environment bootstrap.
+- Zod-validated boundary; bad input throws `TestViteError(TEST_VITE.INVALID_OPTIONS)`.
+- OTel counter `test_vite_config_built_total{kind="vitest_browser"}` incremented per invocation.
+
+## Usage: Basic
+
+```ts
+// vitest.browser.config.ts
+import { createVitestBrowserConfig } from "@suaveplan/test-vite/vitest-browser-config";
+
+export default createVitestBrowserConfig({});
+```
+
+## Usage: Advanced
+
+Multi-browser matrix with custom include + setup:
+
+```ts
+import { createVitestBrowserConfig } from "@suaveplan/test-vite/vitest-browser-config";
+
+export default createVitestBrowserConfig({
+  browsers: ["chromium", "firefox", "webkit"],
+  headless: false,
+  setupFiles: ["./tests/setup/browser.ts"],
+  include: ["src/**/*.browser.test.ts"],
+});
+```
+
+## API Reference
+
+- `createVitestBrowserConfig(opts?: VitestBrowserConfigOptions): UserConfig`.
+- `VitestBrowserConfigOptions` — `{ browsers?, headless?, setupFiles?, include? }`.
+- Throws `TestViteError` with code `TEST_VITE.INVALID_OPTIONS` on Zod failure (including empty browser list).
+
+## Implementation Notes
+
+The `browser.instances` array is built by mapping each requested browser into a `{ browser }` object so Vitest's browser runner can attach per-browser overrides if a caller spreads the result. The factory deliberately does not expose every Playwright option — packages with bespoke needs should spread the returned config and override the `browser` block. Vitest 4 requires `browser.provider` to be a provider factory imported from `@vitest/browser/providers/playwright`; to avoid a hard subpath dependency we accept that factory through `opts.provider`. When omitted we emit a tagged sentinel object that consumers can replace with a one-line spread before exporting their config.