Initial Commit

openspec/archive/2026-05-23-enterprise-react-audio-player/proposal.md

@@ -0,0 +1,112 @@
+# OpenSpec Change: enterprise-react-audio-player
+
+- **Change ID**: enterprise-react-audio-player
+- **Package**: `@suaveplan/react-audio-player`
+- **Category**: react
+- **Target path**: `packages/ui/react/react-audio-player`
+- **Status**: PROPOSED
+- **Date**: 2026-05-15
+- **Design**: `./design.md`
+- **Spec delta**: `./specs/react-audio-player/spec.md`
+
+> Replaces the prior 2026-04-24 draft flagged `NEEDS-REWRITE`. See `../REACT_AUDIO_WAVE_REWRITE_COMPLETE.md`.
+
+---
+
+## Summary
+
+Deliver `@suaveplan/react-audio-player` on genesis from scratch at enterprise quality. The package is a track-style media player UI suite built on the unified architecture: it consumes `AudioPlayerPlugin` from `@suaveplan/audio-fx-plugin-base` as its playback source, hosts an optional FX chain via the universal `PluginChain` primitive, exposes a Zustand-backed player store layered over the transport, and provides three player variants (`<BasicPlayer>`, `<AudioPlayer>`, `<PremiumPlayer>`) plus karaoke (LRC parsing + `<LyricsDisplay>`), localStorage-backed playlist, two visualisers (waveform + spectrum) sourced from `useAnalyser`, two R3F screensavers (`<GLBViewer>`, `<ShaderBackground>`), and (in the premium variant) WebRTC multi-peer playback sync via `@suaveplan/react-audio-stream`.
+
+The package owns **no DSP, no transport scheduler, no parameter automation, no audio context**. Every audio operation goes through `@suaveplan/react-audio`'s hooks; UI state goes into a per-provider Zustand store; persistence goes through an injectable store (default `localStorage`).
+
+---
+
+## Current-state audit (genesis)
+
+The package does not exist on genesis yet — fresh build replacing the obsolete pre-tier 2026-04-24 draft.
+
+---
+
+## Parity Checklist (vs upstream `../suaveplan/packages/react/media/react-audio-player/`)
+
+| Capability | Upstream | Migrated | Notes |
+|---|:---:|:---:|---|
+| Zustand `useAudioPlayerStore` | ✅ | ⬆️ | Slimmer; no playback state (lives on transport). UI + playlist + lyrics state only. |
+| `<AudioPlayerProvider>` | ✅ | ✅ | Thin wrapper that nests `<AudioProvider>` from `react-audio` and adds player-specific stores. |
+| `createPluginManager` | ✅ | ⚠️ refactored | Replaced by the generic `<PluginChainView>` from `react-audio`; consumers can drop in any `AudioFxPlugin`. |
+| `<PlayPauseButton>` | ✅ | ✅ | Uses `useTransport().play/pause`. |
+| `<VolumeControl>` | ✅ | ✅ | Drives the player's `AudioPlayerPlugin` volume parameter. |
+| `<ProgressBar>` | ✅ | ✅ | Reads `useTransportTime`. |
+| `<Queue>` (playlist) | ✅ | ✅ | Backed by `usePlaylist` from `react-audio`. |
+| 3-band EQ + presets | ✅ | ⬆️ | Built on `EQPlugin` from `audio-fx-plugin-base`. Presets via `usePreset`. |
+| LRC karaoke parser | ✅ | ✅ | Universal parser; no UI deps. |
+| `<LyricsDisplay>` | ✅ | ✅ | Reads `useTransportTime` for per-line highlight. |
+| `createNetworkSyncManager` (WebRTC/WebSocket multi-peer) | ✅ | ⬆️ | Delegated to `@suaveplan/react-audio-stream`; this package consumes its hooks. |
+| localStorage-backed track storage | ✅ | ✅ | Through injectable store (default `localStorage`). |
+| `<GLBViewer>` R3F screensaver | ✅ | ✅ | Optional subpath; r3f peer dep. |
+| `<ShaderBackground>` R3F screensaver | ✅ | ✅ | Optional subpath; r3f peer dep. |
+| `<WaveformVisualizer>` | ✅ | ⬆️ | Reads `useAnalyser` from `react-audio`. |
+| `<SpectrumAnalyzer>` | ✅ | ⬆️ | Reads `useAnalyser` from `react-audio`. |
+| Coverage | partial | ✅ | 100/100/100/100. |
+| Storybook | partial | ✅ | Every component: default + interactive + edge. |
+
+No 🚫 rows.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/react-audio` (`workspace:^`) | Provider + hooks (`useAudioFxPlugin`, `useTransport`, `useTransportTime`, `useAnalyser`, `usePlaylist`) |
+| `@suaveplan/audio-fx-plugin-base` (`workspace:^`) | `AudioPlayerPlugin`, `EQPlugin`, `PluginChain` |
+| `@suaveplan/audio-transport` (`workspace:^`) | Transport reference |
+| `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/opentelemetry`, `@suaveplan/events` | foundations |
+| `react`, optional `@react-three/fiber` + `three` for screensavers (peer deps; gated by subpath) |
+| `zustand` (`catalog:state`), `framer-motion` (`catalog:animation`), `lucide-react` (`catalog:ui`), `zod` (`catalog:forms`) |
+
+---
+
+## File layout
+
+```text
+packages/ui/react/react-audio-player/
+  src/
+    index.ts
+    error-codes.ts
+    provider/  audio-player-provider/
+    stores/    use-audio-player-store/  use-playlist-store/  use-lyrics-store/
+    hooks/     use-audio-player/  use-playlist-controls/  use-lyrics/  use-eq-band/
+    karaoke/   lrc-parser/  lyrics-display/  use-active-lyric/
+    components/
+      basic-player/  audio-player/  premium-player/
+      play-pause-button/  volume-control/  progress-bar/
+      queue/  eq-panel/  preset-selector-3band/
+      waveform-visualizer/  spectrum-analyzer/
+    screensavers/                ← optional subpaths, R3F-gated
+      glb-viewer/  shader-background/
+    sync/                        ← optional subpaths, WebRTC-gated
+      use-multi-peer-sync/
+    __benchmarks__/
+      lrc-parse.bench.ts
+      visualizer.bench.ts
+  tests/
+    integration.test.tsx
+    purity.test.ts
+    exports.test.ts
+  e2e/
+    play.spec.ts
+    karaoke.spec.ts
+```
+
+---
+
+## Impact
+
+**Breaking changes**: none — fresh build.
+
+**Prerequisites**: `react-audio`, `audio-fx-plugin-base`, `audio-transport`, foundations.
+
+### Affected dependents
+
+No dependents in this batch (verified by `bunx turbo ls --filter=...@suaveplan/react-audio-player`).