# 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.