Initial Commit

openspec/archive/2026-05-19-enterprise-react-audio-components/proposal.md

@@ -0,0 +1,54 @@
+# OpenSpec Change: enterprise-react-audio-components
+
+- **Change ID**: enterprise-react-audio-components
+- **Package**: `@suaveplan/react-audio`
+- **Category**: react
+- **Target path**: `packages/react/react-audio`
+- **Status**: PROPOSED — Phase 2 of 3
+- **Date**: 2026-05-19
+- **Spec delta**: `./specs/react-audio/spec.md`
+
+> Phase 2 of the decomposed `enterprise-react-audio` rollout. Phase 1 (`enterprise-react-audio-foundation`) shipped at commit `c3460248`. Ships ONLY the components the spec hard-mandates; the composed-plugin UIs ship in a sibling change `enterprise-react-audio-components-extras`.
+
+## Summary
+
+Add the four spec-mandated components plus their primitives to `@suaveplan/react-audio`:
+
+1. `<PluginSlot>` — generic renderer for any `AudioFxPlugin`, parameterised by `slotRenderers` for specialised overrides (spec req 1).
+2. `<PluginChainView>` — drag/drop + keyboard reorder + IO-validation toast (spec req 2).
+3. `<PluginParameterKnob>` + `<PluginParameterSlider>` — keyboard + ARIA per the accessibility requirement (spec req 3).
+4. `<PresetManager>` — `ChainSnapshot` save/restore via the provider's preset store (spec req 4).
+
+Plus the cross-cutting infrastructure:
+- Storybook coverage CI gate enforcing default + interactive + edge-case stories per component (spec req 5).
+- `./components` + `./components/<name>` subpath exports (spec req 6).
+
+These six requirements are the package's external contract for Phase 2. Every requirement has explicit `**Verified by:**` test names in the spec delta.
+
+## Deferred to `enterprise-react-audio-components-extras`
+
+The following components were listed in the original umbrella proposal but are NOT load-bearing for Phase 2's spec contract — they ship in a sibling change after Phase 2 archives:
+
+- `<TransportControls>`, `<TrackList>` + `<TrackRow>`, `<MasterMeter>`
+- `<Mixer>` (over `@suaveplan/audio-fx-plugin-mixer`)
+- `<AudioVisualizer>` (waveform / spectrum / level modes)
+- `<AudioPlayer>` + `<BasicPlayer>` + `<PremiumPlayer>` (over `@suaveplan/audio-fx-plugin-audio-player`)
+- `<MicrophoneControls>` (over `@suaveplan/audio-fx-plugin-microphone`)
+- `<GLaDOSControls>` (over `@suaveplan/audio-fx-plugin-glados`)
+- `<PluginLoader>` — dynamic registration UI over `PluginRegistry.list()`
+
+These are composed-plugin UIs whose value depends on the four core primitives shipping first. Splitting them out keeps Phase 2 to a scope a single agent dispatch has consistently shipped successfully across this migration (audio-controllers, audio-engine-browser, audio-fx-plugin-base — each in the 17–40 src-file range).
+
+## Out of scope
+
+- Provider/hook/store surface (Phase 1, shipped at `c3460248`).
+- `<MidiControllerSetup>` learn-mode panel + `useMidiController` hook (Phase 3, `enterprise-react-audio-midi`).
+- The deferred composed-plugin UIs above (`enterprise-react-audio-components-extras`).
+
+## Impact
+
+### Affected dependents
+
+- `@suaveplan/react-audio-fingerprint`, `@suaveplan/react-audio-player`, `@suaveplan/react-audio-stream`, `@suaveplan/r3f-audio` — all currently `–` in STATUS.md; each composes against the core primitives once Phase 2 lands; full migration also requires the extras + Phase 3.
+
+After Phase 2 archives, STATUS row `@suaveplan/react-audio` description updates to "Phase 2 of 3 shipped: foundation + 4 spec-mandated components; remaining UIs in `enterprise-react-audio-components-extras`; MIDI Phase 3".