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:
@@ -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.
|
||||
Reference in New Issue
Block a user