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

Tasks: enterprise-react-audio-player

Change ID: enterprise-react-audio-player Package: @suaveplan/react-audio-player Target path: packages/ui/react/react-audio-player Prerequisite packages on Verdaccio: @suaveplan/react-audio, @suaveplan/audio-fx-plugin-base, @suaveplan/audio-transport, @suaveplan/error, @suaveplan/types, @suaveplan/opentelemetry, @suaveplan/events

---

1. Scaffold

• 1.1 Directory tree per proposal.
• 1.2 package.json at 0.1.0, "sideEffects": false, full subpath exports map (root + provider + components + hooks + stores + karaoke + optional screensavers + optional sync). React 19 peer. @react-three/fiber, three, react-audio-stream as optional peers gated by subpath.
• 1.3 tsconfig.json, vitest.config.ts (happy-dom).

2. Error codes

• 2.1 src/error-codes.ts — defineCodes("REACT_AUDIO_PLAYER", [...]), ReactAudioPlayerError extends AudioError.
• 2.2 error-codes.test.ts — every code reachable.

3. Provider + stores

• 3.1 src/provider/audio-player-provider.tsx — nests <AudioProvider>, owns three Zustand stores, constructs source plugin in player-track chain, wires 'ended' to playlist advance, disposal on unmount.
• 3.2 src/stores/use-audio-player-store.ts — volume / mute / loading-state / chain-visibility.
• 3.3 src/stores/use-playlist-store.ts — tracks / position / repeat / shuffle.
• 3.4 src/stores/use-lyrics-store.ts — parsed lyrics + active index cache.
• 3.5 audio-player-provider.test.tsx covering: per-id source plugin uniqueness, ended → playlist advance, persistence restore, injected store supersedes default, strict-mode safe.

4. Hooks

• 4.1 use-audio-player — combined controls (play/pause/seek/setVolume/load).
• 4.2 use-playlist-controls — next/previous/select/add/remove/clear, repeat/shuffle toggles.
• 4.3 use-lyrics — exposes parsed lyrics and active index sampled at 100 ms.
• 4.4 use-eq-band — bind a single band (low/mid/high) to the chain's EQ plugin parameters.

5. Karaoke

• 5.1 src/karaoke/lrc-parser/lrc-parser.ts — sorted, validated parse; ignores metadata tags; skips malformed lines.
• 5.2 lrc-parser.test.ts — sort, skip, malformed, large file (10 k lines) under 50 ms.
• 5.3 src/karaoke/lyrics-display/lyrics-display.tsx — 100 ms re-bind binary-search active line; aria-live toggle.

6. Components (each: .tsx, .md, .test.tsx, .stories.tsx)

• 6.1 play-pause-button/.
• 6.2 volume-control/.
• 6.3 progress-bar/ — keyboard seek, ARIA per spec.
• 6.4 queue/ — listbox semantics, keyboard CRUD per spec.
• 6.5 eq-panel/ — 3-band specialised renderer over EQPlugin.
• 6.6 preset-selector-3band/.
• 6.7 waveform-visualizer/ — <canvas> over useAnalyser.
• 6.8 spectrum-analyzer/.
• 6.9 basic-player/.
• 6.10 audio-player/.
• 6.11 premium-player/ — composes everything, optional chain UI, optional lyrics, optional multi-peer.

7. Optional subpaths

• 7.1 screensavers/glb-viewer/ — R3F-gated component.
• 7.2 screensavers/shader-background/ — R3F-gated component.
• 7.3 sync/use-multi-peer-sync/ — WebRTC-gated hook over react-audio-stream.

8. Benchmarks

• 8.1 src/__benchmarks__/lrc-parse.bench.ts — parse a 10 k-line LRC.
• 8.2 src/__benchmarks__/visualizer.bench.ts — <SpectrumAnalyzer> frame render.

9. Tests

• 9.1 tests/integration.test.tsx — load playlist, play, advance on ended, EQ change persists across remount.
• 9.2 tests/purity.test.ts — built dist/ references no audio context.
• 9.3 tests/exports.test.ts — every surface has subpath; every component has 3 story types.
• 9.4 tests/bundle-size/{root-only,basic-only,premium-only}.size.test.ts — gating proof.
• 9.5 e2e/play.spec.ts — Playwright play/pause/seek under a real browser.
• 9.6 e2e/karaoke.spec.ts — Playwright lyric advancement.

10. Docs + verify

• 10.1 All co-located .md (≥200 words).
• 10.2 README.md at package root with quick-start for each variant + karaoke example + screensaver example.
• 10.3 bunx turbo lint typecheck test --filter=@suaveplan/react-audio-player green; coverage 100/100/100/100; banned-pattern sweeps empty.

11. Spec reconciliation + archive

• 11.1 Walk every ### Requirement and **Verified by:**.
• 11.2 Fold spec delta into openspec/specs/react-audio-player/spec.md.
• 11.3 Move change folder to archive.