first commit

docs/ui/react/react-audio/src/provider/provider-options.md

@@ -0,0 +1,79 @@
+# `provider/provider-options`
+
+## Purpose
+
+Defines the `AudioProviderOptions` shape consumed by
+`<AudioProvider>`, the Zod schema that validates it, and the
+`parseAudioProviderOptions` helper that converts a Zod failure into a
+`ReactAudioError` whose code is `REACT_AUDIO.INVALID_OPTIONS`. The
+schema is intentionally permissive about deep adapter/transport
+internals — those are validated again by their owning packages
+(`@suaveplan/audio-engine-browser` revalidates `BrowserAdapterOptions`,
+`@suaveplan/audio-transport` revalidates transport options) — but
+strict about the provider-level shape so a typo such as `adaptor`
+fails at the React boundary instead of mid-way through async init.
+
+## Features
+
+- `AudioProviderOptionsSchema` — strict-object Zod schema rejecting
+  unknown top-level keys.
+- `AudioProviderOptions` TypeScript interface mirroring the schema.
+- `parseAudioProviderOptions(input)` — single-call validator that
+  throws `ReactAudioError(REACT_AUDIO.INVALID_OPTIONS)` on failure.
+- `PluginFactoryEntry` shape for the optional auto-registration list.
+- `PresetStore` shape for the pluggable preset persistence layer.
+
+## Usage: Basic
+
+```ts
+import { parseAudioProviderOptions } from "@suaveplan/react-audio/provider";
+
+const options = parseAudioProviderOptions({
+    adapter: { sampleRate: 48000 },
+    transport: { bpm: 120 },
+    sampleRateHz: 60,
+});
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    parseAudioProviderOptions,
+    type AudioProviderOptions,
+    type PluginFactoryEntry,
+} from "@suaveplan/react-audio/provider";
+
+const factories: ReadonlyArray<PluginFactoryEntry> = [
+    { pluginType: "delay", factory: () => makeDelay() },
+    { pluginType: "reverb", factory: () => makeReverb() },
+];
+
+const opts: AudioProviderOptions = {
+    plugins: factories,
+    sampleRateHz: 30, // half-rate sampling for low-power devices
+};
+
+parseAudioProviderOptions(opts);
+```
+
+## API Reference
+
+- `AudioProviderOptions` — `{ adapter?, transport?, plugins?,
+  presetStore?, sampleRateHz?, slotRenderers? }`.
+- `PluginFactoryEntry` — `{ pluginType, factory }`.
+- `PresetStore` — `{ save(kind, id, payload), load(kind, id) }`.
+- `parseAudioProviderOptions(input)` — returns a frozen-shape value
+  on success, throws `ReactAudioError` otherwise.
+
+## Implementation Notes
+
+The schema is `.strict()` on the top-level object so unknown keys
+fail validation rather than being silently dropped — this catches
+shape regressions early. Deeper objects (`transport`, `presetStore`)
+use `.passthrough()` because their authoritative schemas live in the
+owning packages; revalidating their full shape here would couple this
+package to internal layouts that already validate at construction.
+`sampleRateHz` is clamped to `[1, 240]` to keep `requestAnimationFrame`
+sampling in a sensible band: below 1 the UI feels frozen, above 240
+the work done per frame outpaces typical display refresh.