suaveplan/openspec/archive/2026-05-12-enterprise-browser-network-webrtc/tasks.md

Tasks: enterprise-browser-network-webrtc

Change ID: enterprise-browser-network-webrtc Package: @suaveplan/network-webrtc Target path: browser/network/network-webrtc Prerequisite packages on Verdaccio: @suaveplan/network, @suaveplan/serialize, @suaveplan/error, @suaveplan/types, @suaveplan/events

---

1. Scaffold

• Create browser/network/network-webrtc/ directory tree per layout in proposal.md.
• Write package.json at version 0.1.0:
  • "sideEffects": false; no react runtime dep
  • exports: ".", "./webrtc", "./dual-channel", "./channel-router", "./signaling", "./config/ice-servers"
  • dependencies: @suaveplan/network workspace:^, @suaveplan/serialize workspace:^, @suaveplan/error workspace:^, @suaveplan/types workspace:^, @suaveplan/events workspace:^, zod catalog:forms, @opentelemetry/api catalog:observability, tslib catalog:build
  • devDependencies: vitest catalog:testing, @vitest/coverage-istanbul catalog:testing, @playwright/test catalog:testing, @suaveplan/testing workspace:^
  • files: ["dist", "src", "README.md"] — examples/ intentionally excluded
• Write tsconfig.json and vitest.config.ts (pool: forks).

---

2. Error codes (src/error-codes.ts)

• Define WebRTCErrorCode: WEBRTC_DIAL_FAILED, WEBRTC_ICE_FAILED, WEBRTC_CHANNEL_CLOSED, WEBRTC_SIGNALING_TIMEOUT, WEBRTC_INVALID_STATE.
• Export registerWebRTCErrorCodes() and call eagerly.

---

3. Signalling (src/signaling/)

3a. signaling-channel/signaling-channel.ts

• Define SignalingChannel interface with offer/answer/ICE methods.
• Implement MemorySignalingChannel for in-process testing (two paired instances).
• Add Zod schemas OfferMessageSchema, AnswerMessageSchema, IceCandidateMessageSchema; validate on receive.
• Write signaling-channel.test.ts, signaling-channel.md.

3b. websocket-signaling/websocket-signaling.ts

• Implement WebSocketSignalingChannel with reconnect on error.
• Write websocket-signaling.test.ts, websocket-signaling.md.

---

4. Peer connection (src/webrtc/peer-connection/)

• Implement PeerConnection wrapping RTCPeerConnection:
  • Perfect-negotiation pattern (onnegotiationneeded with polite-peer collision handling).
  • ICE-restart policy: detect iceConnectionState === 'failed', call restartIce(), emit 'ice:restart'.
  • Typed event emitter for 'state:change', 'ice:state:change', 'ice:restart', 'error'.
• Write peer-connection.test.ts, peer-connection.md.

---

5. Data channel (src/webrtc/data-channel/)

• Implement DataChannel wrapping RTCDataChannel with onMessage, send, close, back-pressure watermark.
• Write data-channel.test.ts, data-channel.md.

---

6. Signalling handlers (src/webrtc/signaling-handlers/)

• Implement SignalingHandlers: route offer/answer/ICE-candidate events from SignalingChannel to PeerConnection.
• Write signaling-handlers.test.ts, signaling-handlers.md.

---

7. WebRTC transport (src/webrtc/webrtc-transport/)

• Implement WebRTCTransport composing PeerConnection, DataChannel, SignalingHandlers.
• Wire OTel counters + histograms from src/error-codes.ts metrics.
• Write webrtc-transport.test.ts (vitest, no describe.skip), webrtc-transport.md, webrtc-transport.types.ts.

---

8. Dual channel (src/dual-channel/dual-channel/)

• Implement DualChannel with reliable (ordered, maxRetransmits=10) and unreliable (unordered, maxRetransmits=0) channels.
• Back-pressure: track bufferedAmount; queue sends when > watermark.
• Write dual-channel.test.ts, dual-channel.md.

---

9. Channel router (src/channel-router/channel-router/)

• Implement ChannelRouter with register/unregister/route/send.
• Write channel-router.test.ts, channel-router.md.

---

10. ICE server config (src/config/ice-servers/)

• Export STUN_SERVERS (public Cloudflare STUN), validateIceServers(servers) (Zod), and builder helper.
• Write ice-servers.md.

---

11. Integration test (tests/integration.test.ts)

• Two in-process WebRTCTransport instances connected via MemorySignalingChannel: dial → send reliable + unreliable → receive → close.
• ICE-restart: simulate iceConnectionState = 'failed'; verify restart event fires and connection recovers.
• Flow-control: send above watermark; verify queuing without data loss.

---

12. Playwright E2E (e2e/webrtc.spec.ts)

• Two Chromium browser contexts; each runs a Vite-bundled test page.
• Signal via in-page BroadcastChannel acting as the MemorySignalingChannel equivalent.
• Assert: offer/answer/ICE/dial/send/close lifecycle; message received in both directions.

---

13. Docs

• Write .md per module (≥200 words, API reference, examples).
• Write README.md with subpath table, signalling matrix, ICE/TURN ops guidance, metrics table.

---

14. Verify and publish

• bunx turbo lint typecheck test --filter=@suaveplan/network-webrtc — green.
• bunx turbo test:coverage --filter=@suaveplan/network-webrtc — 100% on touched modules.
• bun run docs:check --filter=@suaveplan/network-webrtc — zero errors.
• No describe.skip, vi.mock, vi.stubGlobal, any, ts-ignore in src/.
• react not in runtime deps.
• Playwright E2E proves offer/answer/ICE/dial/send/close.
• bun scripts/publish.ts --package @suaveplan/network-webrtc.
• Archive to openspec/archive/2026-04-24-enterprise-browser-network-webrtc/.