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

Tasks: enterprise-react-audio-stream

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

---

1. Scaffold

• 1.1 Directory tree per proposal.
• 1.2 package.json at 0.1.0, "sideEffects": false, full subpath exports. React 19 peer; @suaveplan/network-discovery-trystero optional peer gated by ./transports/trystero.
• 1.3 tsconfig.json, vitest.config.ts (happy-dom).

2. Error codes

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

3. Session core

• 3.1 src/session/session-fsm/ — @suaveplan/fsm-driven FSM with the 7-state lifecycle.
• 3.2 src/session/stream-session/ — StreamSession class wrapping FSM + transport adapter + peer registry + control channel.
• 3.3 src/session/peer-channel/ — per-peer state and control-message wiring.
• 3.4 src/session/stream-source-plugin/ — AudioFxPlugin implementation that wraps a MediaStream as a source plugin (io.inputs[0].count === 0).
• 3.5 src/session/interruption-classifier/ — deterministic mapping from underlying cause to one of 5 classes.
• 3.6 session.test.ts covering the entire FSM, peer add / remove, interruption classification, reconnect.

4. Transports

• 4.1 src/transports/webrtc/ — WebRTCTransport using browser RTCPeerConnection + RTCDataChannel (for control + transport-share).
• 4.2 src/transports/websocket/ — WebSocketTransport using @suaveplan/network-transport-websockets; PCM or opus frames per option.
• 4.3 src/transports/trystero/ — optional subpath wrapping @suaveplan/network-discovery-trystero.

5. Provider + hooks

• 5.1 src/provider/audio-stream-provider.tsx — owns one StreamSession per provider, injects transport adapter, strict-mode safe lifecycle, dispose on unmount.
• 5.2 use-audio-stream(participantId).
• 5.3 use-peer-streams().
• 5.4 use-stream-controls().
• 5.5 use-stream-reconnect() — exposes reconnect attempts + last error.
• 5.6 use-stream-mixer() — per-peer level/mute/solo + share toggle, delegating to the peer chain.
• 5.7 use-stream-interruption() — last interruption + class.
• 5.8 use-transport-share() — request/grant/revoke + share status.

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

• 6.1 remote-peer-strip/.
• 6.2 stream-mixer/ — DAW solo semantics across peers.
• 6.3 stream-health-indicator/ — latency, packet loss, codec.
• 6.4 stream-reconnect-toast/.

7. OTel

• 7.1 Register all counters / gauge / histogram; wire instrumentation throughout lifecycle.

8. Benchmarks

• 8.1 src/__benchmarks__/session-fanout.bench.ts — 32 peers connected simultaneously.

9. Tests

• 9.1 tests/integration.test.tsx — two peers, one becomes driver, transport share works, network failure auto-reconnects.
• 9.2 tests/purity.test.ts — built dist/ references no audio context.
• 9.3 tests/exports.test.ts — every surface subpath; trystero gated correctly.
• 9.4 tests/bundle-size/{root-only,webrtc-only,trystero-only}.size.test.ts.
• 9.5 e2e/two-peer-sync.spec.ts — Playwright two-browser test with a real signalling server.

10. Docs + verify

• 10.1 All co-located .md (≥200 words).
• 10.2 README.md at package root with quick-start, transport-share example, FX-on-peer example.
• 10.3 bunx turbo lint typecheck test --filter=@suaveplan/react-audio-stream green; coverage 100/100/100/100.

11. Spec reconciliation + archive

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