Initial Commit

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

@@ -0,0 +1,43 @@
+# OpenSpec Change: enterprise-react-audio-components-extras
+
+- **Change ID**: enterprise-react-audio-components-extras
+- **Package**: `@suaveplan/react-audio`
+- **Category**: react
+- **Target path**: `packages/react/react-audio`
+- **Status**: PROPOSED — supplementary to Phase 2 (`enterprise-react-audio-components`)
+- **Date**: 2026-05-19
+- **Spec delta**: `./specs/react-audio/spec.md`
+
+> Supplementary phase. **Blocked** on `enterprise-react-audio-components` shipping first. Adds the composed-plugin UIs that the original umbrella `enterprise-react-audio` proposal listed but the Phase 2 spec did not hard-mandate.
+
+## Summary
+
+Add the composed-plugin UI components to `@suaveplan/react-audio`:
+
+- `<TransportControls>` (play/pause/stop/seek/loop/tempo with keyboard).
+- `<TrackList>` + `<TrackRow>` (track enumeration + per-row controls).
+- `<MasterMeter>` (overall output peak/RMS meter).
+- `<Mixer>` (track strips with gain/pan/mute/solo/sends — composed against `@suaveplan/audio-fx-plugin-mixer`).
+- `<AudioVisualizer>` (waveform / spectrum / level meter modes).
+- `<AudioPlayer>`, `<BasicPlayer>`, `<PremiumPlayer>` (composed against `@suaveplan/audio-fx-plugin-audio-player`).
+- `<MicrophoneControls>` (composed against `@suaveplan/audio-fx-plugin-microphone`).
+- `<GLaDOSControls>` (composed against `@suaveplan/audio-fx-plugin-glados`).
+- `<PluginLoader>` — dynamic registration UI over `PluginRegistry.list()`.
+
+Each ships with `.md`, `.test.tsx`, and three Storybook stories per the gate already enforced in Phase 2. Subpath exports `./components/<name>` extend the Phase 2 surface.
+
+## Spec delta scope
+
+The Phase 2 spec stays valid; this change adds one new requirement per component family asserting the surface, plus a parity invariant that no main-branch component is omitted at the conclusion of this change.
+
+## Out of scope
+
+- Foundation hooks/provider (Phase 1).
+- Spec-mandated core primitives `<PluginSlot>` / `<PluginChainView>` / `<PresetManager>` (Phase 2).
+- `<MidiControllerSetup>` (Phase 3).
+
+## Impact
+
+### Affected dependents
+
+After this change archives, the parity invariant against main is restored: every component on `/mnt/s/web/suaveplan/packages/react/react-audio/src/components/` has a genesis equivalent. `react-audio-fingerprint`, `react-audio-player`, `react-audio-stream`, and `r3f-audio` migrations can compose freely against the full UI surface.

openspec/archive/2026-05-19-enterprise-react-audio-components-extras/specs/react-audio/spec.md

@@ -0,0 +1,42 @@
+<!-- markdownlint-disable MD024 -->
+
+# Capability Spec Delta: react-audio (enterprise-react-audio-components-extras)
+
+**Package**: `@suaveplan/react-audio`
+**Status**: PROPOSED — supplementary to Phase 2
+**Blocked on**: `enterprise-react-audio-components` shipping first.
+
+> Every requirement carries `**Verified by:**`.
+
+## ADDED Requirements
+
+### Requirement: Composed-plugin UI components
+
+The package SHALL export `<TransportControls>`, `<TrackList>`, `<TrackRow>`, `<MasterMeter>`, `<Mixer>`, `<AudioVisualizer>`, `<AudioPlayer>`, `<BasicPlayer>`, `<PremiumPlayer>`, `<MicrophoneControls>`, `<GLaDOSControls>`, and `<PluginLoader>`. Each component SHALL compose against the foundation hooks (Phase 1) and the appropriate concrete plugin package: `<Mixer>` against `@suaveplan/audio-fx-plugin-mixer`, `<AudioPlayer>` family against `@suaveplan/audio-fx-plugin-audio-player`, `<MicrophoneControls>` against `@suaveplan/audio-fx-plugin-microphone`, `<GLaDOSControls>` against `@suaveplan/audio-fx-plugin-glados`. Each component SHALL satisfy the Storybook coverage gate (default + interactive + edge-case stories) and the accessibility requirement from Phase 2. Each SHALL have a `./components/<name>` subpath export.
+
+#### Scenario: every composed-plugin component renders against a real instance
+
+- **WHEN** a test renders `<Mixer>` with a real `MixerPlugin` from `@suaveplan/audio-fx-plugin-mixer` registered on the provider
+- **THEN** the component renders strip controls bound to the real plugin's parameters; setting a strip's gain calls `mixerPlugin.setParameter` and the new value is reflected on the next sample tick
+
+#### Scenario: subpath export per component
+
+- **WHEN** a consumer imports `@suaveplan/react-audio/components/transport-controls`
+- **THEN** the import resolves and pulls in only that component's bundle (verified by `tests/exports.test.ts`)
+
+**Verified by:** `src/components/transport-controls/transport-controls.test.tsx::"renders against a real transport"` AND `src/components/track-list/track-list.test.tsx::"renders against a real TimelineEngine"` AND `src/components/mixer/mixer.test.tsx::"renders against a real MixerPlugin"` AND `src/components/audio-player/audio-player.test.tsx::"renders against a real AudioPlayerPlugin"` AND `src/components/microphone-controls/microphone-controls.test.tsx::"renders against a real MicrophonePlugin"` AND `src/components/glados-controls/glados-controls.test.tsx::"renders against a real GLaDOSPlugin"` AND `src/components/audio-visualizer/audio-visualizer.test.tsx::"renders a canvas bound to useAnalyser"` AND `src/components/master-meter/master-meter.test.tsx::"renders against a master analyser"` AND `src/components/plugin-loader/plugin-loader.test.tsx::"lists every registered plugin from PluginRegistry"` AND `tests/exports.test.ts::"every extras component has a subpath export entry"`
+
+---
+
+### Requirement: Main-branch parity restored
+
+After this change archives, every component on `/mnt/s/web/suaveplan/packages/react/react-audio/src/components/` SHALL have a genesis equivalent exported from `@suaveplan/react-audio`. The parity test SHALL fail if any main-branch component family is missing on genesis.
+
+#### Scenario: parity test enumerates every main-branch component family
+
+- **WHEN** `tests/parity.test.ts::"every main-branch component family has a genesis equivalent"` runs
+- **THEN** for every top-level directory under `/mnt/s/web/suaveplan/packages/react/react-audio/src/components/` (the test reads this list from a checked-in fixture so it stays runnable offline) there is a corresponding genesis component reachable via `@suaveplan/react-audio/components/<name>`
+
+**Verified by:** `tests/parity.test.ts::"every main-branch component family has a genesis equivalent"`
+
+<!-- markdownlint-enable MD024 -->

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

@@ -0,0 +1,13 @@
+# Tasks: enterprise-react-audio-components-extras
+
+**Phase**: Supplementary to Phase 2
+**Blocked on**: `enterprise-react-audio-components` shipping green.
+
+Outline (to flesh out at execution time):
+
+1. Author every component listed in the proposal Summary (`<TransportControls>`, `<TrackList>`, `<TrackRow>`, `<MasterMeter>`, `<Mixer>`, `<AudioVisualizer>`, `<AudioPlayer>`/`<BasicPlayer>`/`<PremiumPlayer>`, `<MicrophoneControls>`, `<GLaDOSControls>`, `<PluginLoader>`).
+2. Each component family ships with `.tsx` + `.md` + `.test.tsx` + 3 `.stories.tsx` stories matching the Phase 2 Storybook gate.
+3. Compose against real concrete plugin packages (mixer, audio-player, microphone, glados) — no mocks.
+4. Author `tests/parity.test.ts` with a checked-in fixture enumerating main-branch component families.
+5. Extend `package.json` `exports` with `./components/<name>` for every new component.
+6. 5-gate triple + archive + STATUS row description updates to reflect parity restored.