# 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

- [x] Create `browser/network/network-webrtc/` directory tree per layout in `proposal.md`.
- [x] 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
- [x] Write `tsconfig.json` and `vitest.config.ts` (pool: forks).

---

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

- [x] Define `WebRTCErrorCode`: `WEBRTC_DIAL_FAILED`, `WEBRTC_ICE_FAILED`, `WEBRTC_CHANNEL_CLOSED`, `WEBRTC_SIGNALING_TIMEOUT`, `WEBRTC_INVALID_STATE`.
- [x] Export `registerWebRTCErrorCodes()` and call eagerly.

---

## 3. Signalling (`src/signaling/`)

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

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

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

- [x] Implement `WebSocketSignalingChannel` with reconnect on error.
- [x] Write `websocket-signaling.test.ts`, `websocket-signaling.md`.

---

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

- [x] 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'`.
- [x] Write `peer-connection.test.ts`, `peer-connection.md`.

---

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

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

---

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

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

---

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

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

---

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

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

---

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

- [x] Implement `ChannelRouter` with register/unregister/route/send.
- [x] Write `channel-router.test.ts`, `channel-router.md`.

---

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

- [x] Export `STUN_SERVERS` (public Cloudflare STUN), `validateIceServers(servers)` (Zod), and builder helper.
- [x] Write `ice-servers.md`.

---

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

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

---

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

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

---

## 13. Docs

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

---

## 14. Verify and publish

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