first commit

docs/testkit/testing/testing-dom/src/setup/polyfills.md

@@ -0,0 +1,61 @@
+# setup/polyfills
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+The `setup/polyfills` module is a side-effect import that installs the globals test code expects to be present — `crypto`, `TextEncoder`, `TextDecoder` — when the host runtime (bare Node, happy-dom, jsdom, or Bun) doesn't already provide them. It's idempotent and safe to import multiple times.
+
+## Features
+
+- Installs `globalThis.crypto` from Node's `webcrypto` when missing
+- Installs `TextEncoder` / `TextDecoder` from `node:util` when missing
+- Guards every assignment with an existence check — never overwrites a populated global
+- Exports nothing — side effects only
+
+## Usage: Basic Example
+
+```ts
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+import { createVitestConfig } from "@suaveplan/testing-dom/config";
+
+export default defineConfig(
+    createVitestConfig(__dirname, {
+        setupFiles: ["@suaveplan/testing-dom/polyfills"],
+    })
+);
+```
+
+## Usage: Advanced Example
+
+```ts
+// bunfig.toml (bun-test)
+// [test]
+// preload = ["@suaveplan/testing-dom/polyfills", "./tests/install-matchers.ts"]
+
+// Or programmatically via createBunTestConfig:
+import { createBunTestConfig } from "@suaveplan/testing-dom/config";
+
+const cfg = createBunTestConfig(__dirname, {
+    preload: ["./tests/install-matchers.ts"],
+    // createBunTestConfig adds the polyfills entry automatically.
+});
+```
+
+## API Reference
+
+No exports. Side effects:
+
+- `globalThis.crypto ??= webcrypto` _(from `node:crypto`)_
+- `globalThis.TextEncoder ??= NodeTextEncoder`
+- `globalThis.TextDecoder ??= NodeTextDecoder`
+
+## Implementation Notes
+
+Modern Node (≥19) and Bun both ship `crypto` globally, so the `??=` short-circuits on those hosts. The module remains in the package for older Node versions and for happy-dom sandboxes that don't initialise `crypto`. Imports use `node:` specifiers so the code remains bundler-safe — Rollup/esbuild skip it when externalising node built-ins. Because the module exports nothing, consumers who mistakenly try `import { x } from "@suaveplan/testing-dom/polyfills"` get a useful TypeScript error rather than silent misbehaviour.
+
+### Coverage
+
+The polyfill bundle installs happy-dom's `DOMParser`, `XMLSerializer`, `fetch`, `Request`, `Response`, `Headers`, `URL`, `URLSearchParams`, and `crypto.getRandomValues` into the Node / Bun global scope when they are missing. Double-install is idempotent — the module tracks a `Symbol.for("suaveplan.testing-dom.polyfilled")` marker on `globalThis` so repeated imports are cheap.