suaveplan/openspec/archive/2026-05-23-enterprise-react-audio-stream-hooks-components/proposal.md

@suaveplan/react-audio-stream — hooks + components (chunk C)

• Target path: packages/ui/react/react-audio-stream/
• Tier: browser/react
• Date: 2026-05-23
• Status: PROPOSED — chunk C of the 4-chunk enterprise-react-audio-stream split.

Why

Chunks A (session-core) and B (transports) deliver the headless engine — the FSM, transports, source-plugin bridge, error codes, telemetry. This chunk delivers the React surface that consumers actually touch: a Provider, 6 hooks, 4 accessible components. Transport-share concerns (the 7th hook and its component indicator) live in chunk D so this chunk stays disjoint.

What changes

1. <StreamProvider> — src/provider/stream-provider.tsx wires a StreamSession instance into React context. sessionFactory injectable (consumer creates the session with their chosen transport adapter); StrictMode-safe singleton; surfaces 'state-changed'/'interruption' events into hook subscribers via a typed event bus.
2. Hooks (each in its own feature dir with .ts + .types.ts + .test.tsx + .md + index.ts):
   • useStreamSession() — returns the session + current FSM state + lifecycle methods (connect, join, leave, disconnect)
   • useStreamRoom() — returns { roomId, isJoined, joinedAt, participants } derived from session state
   • useStreamPeers() — returns live Peer[] (id + display name + connection state + RTT)
   • useStreamMixer() — exposes per-peer setVolume, setMute, setSolo (DAW solo semantics — when any peer is soloed, every non-soloed peer's track-volume → 0); reads from each peer chain's setTrackVolume/setTrackMute/setTrackSolo
   • useStreamLevels(peerId?) — returns realtime peak/RMS for the local mic or the named peer; piggybacks on @suaveplan/audio-analysis-spectrum's level computation via the peer chain's analyzer slot
   • useStreamRecording() — start(), stop() returning a Blob; mixes the active session output (or a subset of peers) into a single audio file via audio-engine-browser's offline render
   • useStreamPermissions() — wraps navigator.mediaDevices.getUserMedia permission state with the typed MediaPermissionState enum
3. Components (each with .tsx + .types.ts + .test.tsx + .stories.tsx + .md + index.ts):
   • <StreamRoom> — controlled wrapper exposing room state + join/leave controls; render-prop pattern for layout flexibility
   • <StreamMixer> — per-peer mixer strip with level meter + mute/solo buttons + volume slider; delegates to useStreamMixer()
   • <StreamRecorder> — record/stop button with duration display; delegates to useStreamRecording()
   • <StreamPermissionsBanner> — permission state banner with explicit request button; ARIA-live for state changes
4. Subpath exports — package.json adds ./provider, ./hooks, ./hooks/use-stream-session (and 5 more), ./components, ./components/stream-room (and 3 more).

Requirements landed by this chunk

From the original spec:

• Per-peer stream mixer (full — <StreamMixer> + useStreamMixer)
• Subpath exports for ./provider, ./hooks/*, ./components/*

Impact

• ~35 files (6 hooks × 5 + 4 components × 6 + provider + barrel touches).
• Imports StreamSession, StreamSourcePlugin, ReactAudioStreamError from chunk A — local-mirror types in tests if A hasn't merged.
• Imports nothing from chunk B (consumers wire transports themselves via the session factory).
• No spec fold / no archive — chunk D performs both.