first commit

docs/devtools/tooling/test-vite/src/browser-environment/browser-environment.md

@@ -0,0 +1,54 @@
+# browser-environment
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`setupBrowserEnvironment` installs the DOM and Web-platform shims that suaveplan browser packages depend on when running under happy-dom, jsdom, or bare Node. The function is idempotent — re-running it on a target that already has real implementations is a no-op — so it is safe to call from package setup files without worrying about clobbering whatever the test runner has already installed.
+
+## Features
+
+- Idempotent installer: real implementations are preserved.
+- Per-shim opt-out via `mock*` flags.
+- Injectable `target` parameter for unit testing.
+- Backed by Node's `webcrypto` for the `crypto` shim — no third-party dependency.
+- Memory-backed `localStorage` implementing the standard `Storage` shape.
+
+## Usage: Basic
+
+```ts
+import { setupBrowserEnvironment } from "@suaveplan/test-vite/browser-environment";
+
+setupBrowserEnvironment();
+```
+
+## Usage: Advanced
+
+Install only the shims your tests need, against a synthetic target:
+
+```ts
+import { setupBrowserEnvironment } from "@suaveplan/test-vite/browser-environment";
+
+const target = {} as Record<string, unknown>;
+
+setupBrowserEnvironment({
+  target,
+  mockLocalStorage: true,
+  mockMatchMedia: true,
+  mockResizeObserver: true,
+  mockIntersectionObserver: false,
+  mockCrypto: true,
+});
+```
+
+## API Reference
+
+- `setupBrowserEnvironment(opts?: BrowserEnvironmentOptions): void`.
+- `BrowserEnvironmentOptions` — `{ target?, mockLocalStorage?, mockMatchMedia?, mockResizeObserver?, mockIntersectionObserver?, mockCrypto? }`. All booleans default to `true`.
+- Throws `TestViteError` with code `TEST_VITE.INVALID_OPTIONS` on unknown options.
+
+## Implementation Notes
+
+`MemoryStorage` keeps a `Map<string, string>` rather than a plain object so insertion order is preserved across `key(index)` calls. The `matchMedia` stub returns `matches: false` for every query so tests do not accidentally trigger media-query-conditional behaviour without explicit opt-in. Observer stubs implement no-op `observe` / `unobserve` / `disconnect` methods so client code that wires them up does not crash. The crypto shim delegates to Node's standard `webcrypto` import to avoid bundling extra runtime weight.