Initial Commit

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

@@ -0,0 +1,32 @@
+# @suaveplan/react-audio-stream — transports (chunk B)
+
+- **Target path**: `packages/ui/react/react-audio-stream/`
+- **Tier**: browser/react
+- **Date**: 2026-05-23
+- **Status**: PROPOSED — chunk B of the 4-chunk `enterprise-react-audio-stream` split.
+
+## Why
+
+The session-core chunk (A) declares a structural `StreamTransportAdapter` contract that `StreamSession` accepts via constructor injection. This chunk lands three concrete adapters that implement that contract: WebRTC (default, low-latency), WebSocket (fallback for corporate NATs), and Trystero (serverless WebRTC over BitTorrent/Nostr/MQTT/IPFS). Each lives behind its own subpath so consumers only bundle what they import.
+
+## What changes
+
+1. **WebRTC adapter** — `src/transports/webrtc/webrtc-transport.ts`. Uses `RTCPeerConnection`, ICE configuration via supplied STUN/TURN list (no embedded defaults — caller MUST provide for security), `MediaStream` send/receive, signalling driven through an injected `SignallingChannel` shape (this chunk does NOT implement a signalling server, only the adapter side that an external signalling channel feeds).
+2. **WebSocket adapter** — `src/transports/websocket/websocket-transport.ts`. Wraps `@suaveplan/network-transport-websockets`; frames PCM (raw or Opus-encoded when `@suaveplan/audio-codec-ffmpeg-wasm` is available); fallback path for NAT'd peers.
+3. **Trystero adapter** — `src/transports/trystero/trystero-transport.ts`. Optional peer dep on `@suaveplan/network-discovery-trystero`. Only this subpath imports trystero — the other transports do not transitively pull it.
+4. **Shared transport types** — `src/transports/transport.types.ts` defines `StreamTransportAdapter` (the contract chunk A's session accepts), `SignallingChannel`, `IceConfig`, `TransportEvent` union.
+5. **RTT probes** — every adapter implements `getRtt(): Promise<number>` for the telemetry histogram registered in chunk A.
+6. **Subpath gating** — `package.json` adds `./transports/webrtc`, `./transports/websocket`, `./transports/trystero` exports. Trystero is optional via `optionalDependencies` + lazy `import()`.
+7. **Bundle-size test** — `tests/bundle-size/webrtc-only.size.test.ts` asserts a WebRTC-only consumer's tree-shaken bundle has zero bytes from `@suaveplan/network-discovery-trystero`.
+
+## Requirements landed by this chunk
+
+From the original spec:
+- Subpath exports per surface — completes the `./transports/*` subpaths
+- Bundle-size purity for trystero gating
+
+## Impact
+
+- ~20 files (3 adapters × 5 sibling files + shared types + bundle-size test + config touches).
+- Imports `StreamTransportAdapter`, `ReactAudioStreamError`, `InterruptionClassifier` from chunk A — declare those as local-mirror types in this chunk's `tests/fixtures/` if chunk A hasn't merged yet.
+- No spec fold or archive — that happens after chunk D.

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

@@ -0,0 +1,58 @@
+# Tasks — enterprise-react-audio-stream-transports (chunk B)
+
+## 0. Pre-flight (non-negotiable)
+
+- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
+- [ ] 0.2 Account for every `.claude/worktrees/*` entry; prune stale ones via `bun scripts/worktree-prune.ts --remove`.
+- [ ] 0.3 Confirm `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json | wc -l`.
+
+## 1. Shared transport types
+
+- [ ] 1.1 `src/transports/transport.types.ts` — `StreamTransportAdapter`, `SignallingChannel`, `IceConfig`, `TransportEvent` union
+- [ ] 1.2 `src/transports/transport.md`, `src/transports/index.ts`
+
+## 2. WebRTC adapter
+
+- [ ] 2.1 `src/transports/webrtc/webrtc-transport.ts`
+- [ ] 2.2 `src/transports/webrtc/webrtc-transport.types.ts`, `.test.ts`, `.md`, `index.ts`
+- [ ] 2.3 Tests via a fake `RTCPeerConnection` shim (deterministic, no real network)
+
+## 3. WebSocket adapter
+
+- [ ] 3.1 `src/transports/websocket/websocket-transport.ts`
+- [ ] 3.2 `src/transports/websocket/websocket-transport.types.ts`, `.test.ts`, `.md`, `index.ts`
+- [ ] 3.3 Opus-encoded path gated by lazy import of `@suaveplan/audio-codec-ffmpeg-wasm` (graceful fallback to raw PCM when absent)
+
+## 4. Trystero adapter
+
+- [ ] 4.1 `src/transports/trystero/trystero-transport.ts` — lazy `import("@suaveplan/network-discovery-trystero")`
+- [ ] 4.2 `src/transports/trystero/trystero-transport.types.ts`, `.test.ts`, `.md`, `index.ts`
+- [ ] 4.3 Tests with an injectable trystero room factory (DI seam — not a mock; deterministic in-memory implementation of the room shape)
+
+## 5. RTT probe + telemetry hook
+
+- [ ] 5.1 Each adapter exposes `getRtt(): Promise<number>`
+- [ ] 5.2 Wire-through into the histogram registered by chunk A
+
+## 6. Subpath gating
+
+- [ ] 6.1 `package.json` `exports`: add `./transports/webrtc`, `./transports/websocket`, `./transports/trystero`
+- [ ] 6.2 `optionalDependencies`: `@suaveplan/network-discovery-trystero`
+
+## 7. Bundle-size test
+
+- [ ] 7.1 `tests/bundle-size/webrtc-only.size.test.ts` — asserts a WebRTC-only build excludes trystero
+
+## 8. Tests + docs
+
+- [ ] 8.1 Every `it(...)` carries `{ timeout: 5000 }`
+- [ ] 8.2 Sibling `.md` per `.ts` (≥200 words, basic + advanced examples)
+
+## 9. Pre-archive verification
+
+- [ ] 9.1 `bunx turbo lint typecheck test --filter=@suaveplan/react-audio-stream` — green on chunk-B files
+- [ ] 9.2 `bunx turbo test:coverage --filter=@suaveplan/react-audio-stream` — 100/100/100/100 on touched modules
+
+## 10. Hand-off (no archive yet)
+
+- [ ] 10.1 Commit on `feat/react-audio-stream-transports`. No spec fold / no archive.