# `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.