Move docs/ package mirror into document-navigator plugin

Relocate the ~6k-file docs tree from the repo root into
plugins/document-navigator/docs/ so the plugin is self-contained and
portable. docs/superpowers/ (specs and plans) stays at the repo root.

Moved via cp+rm rather than git mv because directory rename() fails with
EPERM on this WSL /mnt DrvFs mount; git rename-detection pairs the
identical-content files at commit time.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-05-30 01:10:00 +01:00
parent fe3fedf42e
commit 9bf56a806b
6022 changed files with 12437 additions and 0 deletions

View File

@@ -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.