@zero-server/webrtc 0.9.7 → 0.9.8

package/lib/webrtc/bot.js

@@ -1,18 +1,10 @@
 /**
  * @module webrtc/bot
  * @description Server-side WebRTC peer ("bot") built on the `wrtc`
- *   peerDependency.
- *
- *   `spawnBotPeer({hub, room, ...})` attaches an in-process peer to a
- *   {@link SignalingHub}, joins a room, and drives a real
- *   {@link RTCPeerConnection} per remote peer (using the Node.js `wrtc`
- *   binding).  It implements the standard JSEP perfect-negotiation
- *   pattern and is designed for headless workloads such as recording,
- *   transcription, AI agents, and SFU verification harnesses.
- *
- *   The `wrtc` peerDependency is loaded lazily; in production any of
- *   `wrtc` or `@roamhq/wrtc` is acceptable.  Tests inject a fake via
- *   `opts.wrtc`.
+ *   peerDependency. `spawnBotPeer({ hub, room, ... })` attaches an
+ *   in-process peer that joins a room and drives a real
+ *   `RTCPeerConnection` per remote peer. Bidirectional — use for
+ *   recording, transcription, AI participants, or SFU verification.
  */
 'use strict';
 
@@ -43,6 +35,58 @@ const { WebRTCError }  = require('../errors');
  *   ready:              Promise<{ peerId: string }>,
  *   close:              () => void,
  * }}
+ *
+ * @example | Recording bot: dump every inbound audio track to a file
+ *   const { spawnBotPeer } = require('@zero-server/webrtc');
+ *   const { RTCAudioSink } = require('@roamhq/wrtc').nonstandard;
+ *   const fs = require('node:fs');
+ *
+ *   const bot = spawnBotPeer({
+ *       hub,
+ *       room: 'standup',
+ *       user: { id: 'recorder' },
+ *       iceServers: [{ urls: 'stun:stun.l.google.com:19302' }],
+ *       onTrack: (track, _streams, fromPeerId) => {
+ *           if (track.kind !== 'audio') return;
+ *           const sink = new RTCAudioSink(track);
+ *           const out  = fs.createWriteStream(`./recordings/${fromPeerId}.pcm`);
+ *           sink.ondata = ({ samples }) => out.write(Buffer.from(samples.buffer));
+ *           track.onended = () => { sink.stop(); out.end(); };
+ *       },
+ *   });
+ *
+ *   await bot.ready;          // resolves with { peerId } once the hub welcomes us
+ *   process.on('SIGTERM', () => bot.close());
+ *
+ * @example | AI participant: push synthesized audio back to the room
+ *   const { spawnBotPeer } = require('@zero-server/webrtc');
+ *   const { RTCAudioSource } = require('@roamhq/wrtc').nonstandard;
+ *
+ *   const source = new RTCAudioSource();
+ *   const track  = source.createTrack();
+ *
+ *   const bot = spawnBotPeer({
+ *       hub, room: 'lounge', user: { id: 'ai-host' },
+ *       onPeerJoin: (remoteId) => {
+ *           const pc = bot.getPeerConnection(remoteId);
+ *           if (pc) pc.addTrack(track); // perfect-negotiation will renegotiate
+ *       },
+ *   });
+ *
+ *   // Feed synthesized PCM frames every 10ms.
+ *   setInterval(() => source.onData({
+ *       samples:     ttsNextFrame(),     // Int16Array(160)
+ *       sampleRate:  16000,
+ *       bitsPerSample: 16,
+ *       channelCount:  1,
+ *       numberOfFrames: 160,
+ *   }), 10);
+ *
+ * @example | Inject a fake `wrtc` for unit tests
+ *   const bot = spawnBotPeer({ hub, room: 'test', wrtc: fakeWrtc });
+ *   await bot.ready;
+ *   expect(hub.room('test').size).toBe(1);
+ *   bot.close();
  */
 function spawnBotPeer(opts)
 {

package/lib/webrtc/cli.js

@@ -1,6 +1,6 @@
 /**
  * @module webrtc/cli
- * @description CLI subcommands for the `zh webrtc:*` namespace.
+ * @description CLI subcommands for the `zs webrtc:*` namespace.
  *
  *   Pure-function entry point `runWebRTCCommand(subcmd, flags, deps)` so
  *   the dispatch can be exercised in tests without spawning a child
@@ -10,11 +10,11 @@
  *
  * @example
  *   // From the shell, via the top-level CLI:
- *   //   npx zh webrtc:stun --host stun.l.google.com --port 19302
- *   //   npx zh webrtc:turn-creds --secret $SECRET --user alice \
+ *   //   npx zs webrtc:stun --host stun.l.google.com --port 19302
+ *   //   npx zs webrtc:turn-creds --secret $SECRET --user alice \
  *   //                           --servers turn:turn.example.com:3478
- *   //   npx zh webrtc:join-token --secret $JT_SECRET --room lobby --sub u1
- *   //   npx zh webrtc:verify-token --secret $JT_SECRET --token $TOKEN
+ *   //   npx zs webrtc:join-token --secret $JT_SECRET --room lobby --sub u1
+ *   //   npx zs webrtc:verify-token --secret $JT_SECRET --token $TOKEN
  *
  *   // Programmatically:
  *   const { runWebRTCCommand } = require('@zero-server/webrtc/cli');
@@ -168,7 +168,7 @@ function runVerifyToken(flags, { out })
 function helpText()
 {
     return [
-        'zh webrtc:* - WebRTC tooling',
+        'zs webrtc:* - WebRTC tooling',
         '',
         'Subcommands:',
         '  webrtc:stun         --host H [--port 3478] [--timeout 1000] [--retries 1]',

package/lib/webrtc/cluster.js

@@ -1,22 +1,10 @@
 /**
  * @module webrtc/cluster
- * @description Cluster adapter for the WebRTC signaling hub.
- *
- *   `useCluster(hub, adapter)` glues a `SignalingHub` to any pub/sub
- *   adapter that implements `{ publish(channel, message), subscribe(
- *   channel, cb) -> unsubscribe }`.  Once attached:
- *
- *   - Every local `join` / `leave` is announced cluster-wide so other
- *     nodes can resolve a `peer.id` to its owning node.
- *   - Every `room.broadcast(...)` is mirrored to peers in the same room
- *     on other nodes.
- *   - Direct frames (`offer`, `answer`, `ice`) addressed to a peer that
- *     lives on a different node are forwarded to that node's inbox.
- *
- *   The adapter itself is intentionally tiny so production deployments
- *   can wire it up to Redis, NATS, Kafka, or any in-house bus.  A
- *   `MemoryClusterAdapter` is provided for tests and single-process
- *   simulations.
+ * @description Cluster adapter for the signaling hub. `useCluster(hub,
+ *   adapter)` glues a `SignalingHub` to any `{ publish, subscribe }`
+ *   pub/sub bus so joins, leaves, broadcasts, and direct frames flow
+ *   across nodes. Ships with `MemoryClusterAdapter`; wire to Redis, NATS,
+ *   Kafka, or any in-house bus in production.
  *
  * @section Cluster
  */

package/lib/webrtc/e2ee.js

@@ -1,18 +1,10 @@
 /**
  * @module webrtc/e2ee
- * @description End-to-end-encrypted key relay channel for WebRTC.
- *
- *   The hub never sees plaintext SFrame / Insertable-Streams keys.
- *   Publishers wrap each rotation in a sealed envelope (X25519 ECDH +
- *   HKDF-SHA-256 + AES-256-GCM) and broadcast it via the `e2ee-key`
- *   wire message; subscribers in the same room receive the sealed
- *   payload and decrypt locally with their private key.
- *
- *   For deployments that use a different sealing primitive (NaCl
- *   `crypto_box_seal`, libsignal, etc.) the {@link E2eeChannel} works
- *   with any opaque `Buffer` - the {@link sealKey} / {@link openSealedKey}
- *   helpers are provided as a zero-dependency default that satisfies the
- *   HIPAA / FINRA "server is opaque" requirement.
+ * @description End-to-end-encrypted key relay for WebRTC. Publishers wrap
+ *   SFrame/Insertable-Streams keys in sealed envelopes (X25519 + HKDF-SHA-256
+ *   + AES-256-GCM) and broadcast via `e2ee-key`; the hub stays opaque.
+ *   `E2eeChannel` accepts any opaque `Buffer`, so libsignal or NaCl-sealed
+ *   payloads work out of the box.
  *
  * @section E2EE
  */

package/lib/webrtc/ice.js

@@ -1,16 +1,9 @@
 /**
  * @module webrtc/ice
  * @description Zero-dependency ICE candidate parser, serializer, and address
- *              classifiers (private / loopback / link-local / mDNS), plus a
- *              `filterCandidates` helper used by `SignalingHub` to enforce
- *              privacy-preserving policies on relayed offers/answers.
- *
- *              Candidate grammar follows RFC 8839 §5.1 / RFC 5245 §15.1:
- *
- *                candidate-attribute = "candidate" ":" foundation SP component-id
- *                                      SP transport SP priority SP connection-address
- *                                      SP port SP cand-type [SP rel-addr] [SP rel-port]
- *                                      *(SP extension-att-name SP extension-att-value)
+ *   classifiers (private / loopback / link-local / mDNS) per RFC 8839,
+ *   plus a `filterCandidates` helper used by `SignalingHub` to enforce
+ *   privacy-preserving policies on relayed offers/answers.
  *
  * @see https://datatracker.ietf.org/doc/html/rfc8839
  * @see https://datatracker.ietf.org/doc/html/rfc5245

package/lib/webrtc/index.js

@@ -1,14 +1,91 @@
 /**
  * @module @zero-server/webrtc
- * @description First-class WebRTC support for Zero Server.
+ * @description First-class, batteries-included WebRTC support for Zero Server.
  *
- *   Signaling hub, room / peer orchestration, RFC 8489 STUN client,
- *   RFC 7635 TURN credential issuance, optional embedded TURN server,
- *   SFrame E2EE key relay, and a pluggable SFU adapter interface.
+ *   `@zero-server/webrtc` is a complete signaling + NAT-traversal toolkit you
+ *   can drop into any Zero Server app.  Everything is pure JavaScript with
+ *   zero hard dependencies — bring your own media engine (`wrtc`, browsers,
+ *   `mediasoup`, LiveKit, ...) and the library handles the rest.
  *
- *   Implementation is landing PR-by-PR per `.myshit/WEBRTC-ROADMAP.md`.
- *   Real exports already live in this barrel; the rest throw
- *   `WEBRTC_NOT_IMPLEMENTED` so accidental production use fails loud.
+ *   Surface area:
+ *
+ *   - **Signaling** — {@link SignalingHub}, {@link Room}, {@link Peer}.  A
+ *     transport-agnostic WS broker that owns the room registry, validates
+ *     JSEP traffic (offer / answer / ICE / `e2ee-key`), enforces per-peer
+ *     and per-IP rate limits, supports policy gates (`require()`,
+ *     `canPublish()`), and emits lifecycle events.
+ *   - **JSEP parsing** — {@link parseSdp}, {@link stringifySdp},
+ *     {@link parseCandidate}, {@link stringifyCandidate},
+ *     {@link filterCandidates}.  RFC 8866 / 8839 compliant pure-JS codecs.
+ *   - **STUN client** — {@link stunBinding} (RFC 5389 / 8489) for public-IP
+ *     discovery, plus low-level attribute encoders.
+ *   - **TURN** — {@link issueTurnCredentials} (RFC 7635 ephemeral creds) and
+ *     a full embedded {@link TurnServer} that speaks STUN/TURN over UDP.
+ *   - **Join tokens** — {@link signJoinToken} / {@link verifyJoinToken}: HS256
+ *     JWTs scoped to `room:<name>` with publish / subscribe claims.
+ *   - **End-to-end encryption** — {@link E2eeChannel}, {@link attachE2ee},
+ *     {@link generateE2eeKeyPair}, {@link sealKey}, {@link openSealedKey}.
+ *     SFrame-compatible key-relay primitives; the hub never sees media.
+ *   - **SFU adapters** — {@link SfuAdapter} interface plus first-party
+ *     {@link MemorySfuAdapter} (tests), {@link MediasoupSfuAdapter},
+ *     {@link LiveKitSfuAdapter}.  Pluggable via {@link loadSfuAdapter}.
+ *   - **Cluster** — {@link useCluster}, {@link ClusterCoordinator}, and the
+ *     {@link MemoryClusterAdapter} so multiple hub instances can share a
+ *     room registry behind a load balancer.
+ *   - **Server-side peer** — {@link spawnBotPeer} for headless recorders,
+ *     transcribers, or AI participants using `node-wrtc`.
+ *   - **Observability** — {@link bindObservability} wires Prometheus
+ *     counters / histograms and structured logs into a hub.
+ *   - **CLI** — {@link runWebRTCCommand} powers `zs webrtc:*` for STUN
+ *     probes, TURN credential issuance, and join-token sign / verify.
+ *
+ * @example | Bind a signaling hub to a Zero Server `app.ws()` route
+ *   const { createApp } = require('@zero-server/sdk');
+ *   const { SignalingHub, bindObservability } = require('@zero-server/webrtc');
+ *
+ *   const app = createApp();
+ *   const hub = new SignalingHub({
+ *       joinTokenSecret: process.env.WEBRTC_JWT_SECRET,
+ *       ipAttachRate: 60,          // max 60 attaches / IP / min
+ *       maxSdpSize: 64 * 1024,
+ *   });
+ *
+ *   bindObservability(hub, { app }); // exposes /metrics for Prometheus
+ *
+ *   app.ws('/rtc', (ws, req) =>
+ *   {
+ *       const peer = hub.attach(ws, {
+ *           user: req.user,
+ *           ip: req.ip,
+ *           origin: req.headers.origin,
+ *       });
+ *       ws.on('close', () => peer.close());
+ *   });
+ *
+ *   app.listen(3000);
+ *
+ * @example | Issue a join token and a TURN credential to a browser
+ *   const {
+ *       signJoinToken, issueTurnCredentials,
+ *   } = require('@zero-server/webrtc');
+ *
+ *   app.get('/rtc/session/:room', (req, res) =>
+ *   {
+ *       const token = signJoinToken({
+ *           secret: process.env.WEBRTC_JWT_SECRET,
+ *           room: req.params.room,
+ *           userId: req.user.id,
+ *           publish: req.user.isHost,
+ *           ttlSec: 60 * 30,
+ *       });
+ *       const turn = issueTurnCredentials({
+ *           secret: process.env.TURN_SHARED_SECRET,
+ *           userId: req.user.id,
+ *           ttlSec: 60 * 60,
+ *           uris: ['turn:turn.example.com:3478?transport=udp'],
+ *       });
+ *       res.json({ token, iceServers: turn.iceServers });
+ *   });
  */
 
 'use strict';
@@ -49,30 +126,31 @@ const { spawnBotPeer }        = require('./bot');
 
 /**
  * @private
- * Sentinel for surfaces that have not yet been implemented.  Each PR in the
- * roadmap replaces one of these with a real function/class export.
+ * Sentinel for surfaces that are intentionally not exported yet.  Reserved
+ * for future top-level shortcuts; current consumers should construct a
+ * `SignalingHub` directly and use `bindObservability(hub, { app })`.
  */
 const notImplemented = (name) =>
 {
     throw new WebRTCError(
-        `${name} is not implemented yet - see .myshit/WEBRTC-ROADMAP.md for the implementation plan.`,
+        `${name} is not implemented yet - construct \`new SignalingHub(opts)\` directly and wire it via \`app.ws()\`.`,
         { code: 'WEBRTC_NOT_IMPLEMENTED' },
     );
 };
 
 module.exports = {
-    // Signaling - landing in a later PR
+    // Signaling
     createWebRTC:          () => notImplemented('createWebRTC'),
     SignalingHub,
     Room,
     Peer,
     PEER_STATE,
 
-    // SDP - PR 1
+    // SDP / JSEP
     parseSdp,
     stringifySdp,
 
-    // ICE - PR 1
+    // ICE candidate utilities
     parseCandidate,
     stringifyCandidate,
     filterCandidates,
@@ -83,7 +161,7 @@ module.exports = {
     CANDIDATE_TYPES,
     TCP_TYPES,
 
-    // NAT traversal - later PRs
+    // STUN client + low-level codecs
     stunBinding,
     encodeBindingRequest,
     decodeMessage,
@@ -93,10 +171,12 @@ module.exports = {
     STUN_METHOD,
     STUN_CLASS,
     STUN_ATTR,
+
+    // TURN
     issueTurnCredentials,
     TurnServer,
 
-    // SFU + tokens - later PRs
+    // SFU adapters + tokens
     SfuAdapter,
     MemorySfuAdapter,
     MediasoupSfuAdapter,
@@ -105,20 +185,20 @@ module.exports = {
     signJoinToken,
     verifyJoinToken,
 
-    // Server-side WebRTC peer (wrtc bot)
+    // Server-side WebRTC peer (node-wrtc bot)
     spawnBotPeer,
 
-    // Observability - PR 6
+    // Observability
     bindObservability,
 
-    // E2EE key relay - PR 7
+    // SFrame E2EE key relay
     E2eeChannel,
     attachE2ee,
     generateE2eeKeyPair,
     sealKey,
     openSealedKey,
 
-    // Cluster - PR 8
+    // Cluster coordination
     useCluster,
     ClusterCoordinator,
     MemoryClusterAdapter,

package/lib/webrtc/joinToken.js

@@ -1,11 +1,28 @@
 /**
  * @module webrtc/joinToken
- * @description Signed, short-TTL join tokens that authenticate a peer's
- *              right to join a specific room.  JWT-shaped (HS256 by default)
- *              and audience-scoped to `room:<name>` so a token leaked from
- *              one channel cannot be replayed against another.
+ * @description Signed, short-TTL JWT join tokens scoped to `room:<name>`.
+ *   HS256 by default, RS256 supported. Verification is constant-time and
+ *   surfaces every failure mode as `WebRTCError({ code: 'INVALID_TOKEN' })`.
+ *   The hub auto-enforces tokens when constructed with `joinTokenSecret`.
  *
- *   Reuses the canonical sign/verify primitives from `lib/auth/jwt.js`.
+ * @example | Browser receives a token from a regular HTTP route
+ *   // server.js
+ *   const { signJoinToken } = require('@zero-server/webrtc');
+ *   app.get('/rtc/token/:room', (req, res) => {
+ *       const token = signJoinToken({
+ *           secret: process.env.WEBRTC_JWT_SECRET,
+ *           user:   req.user,          // { id, name, role }
+ *           room:   req.params.room,
+ *           ttl:    300,               // 5 minute window
+ *           claims: { publish: req.user.isHost === true },
+ *       });
+ *       res.json({ wsUrl: '/rtc', token });
+ *   });
+ *
+ *   // client.js (pseudo)
+ *   const { wsUrl, token } = await fetch(`/rtc/token/${room}`).then(r => r.json());
+ *   ws = new WebSocket(wsUrl);
+ *   ws.onopen = () => ws.send(JSON.stringify({ type: 'join', room, token }));
  */
 
 'use strict';
@@ -27,15 +44,34 @@ const { SignalingError, WebRTCError } = require('../errors');
  * @param {object}        [opts.claims]    - Additional claims merged into the payload.
  * @returns {string} Compact JWT.
  *
- * @example
+ * @example | Simple HS256 token with a user object
  *   const token = signJoinToken({
  *       secret: process.env.JOIN_SECRET,
- *       user:   req.user,
+ *       user:   req.user,           // { id: 'u_42', name: 'Ada', role: 'host' }
  *       room:   'boardroom',
  *       ttl:    300,
  *   });
  *   res.json({ wsUrl: '/rtc', token });
  *
+ * @example | Embed publish / subscribe permissions as custom claims
+ *   const token = signJoinToken({
+ *       secret: process.env.JOIN_SECRET,
+ *       user:   { id: 'guest_' + crypto.randomUUID() },
+ *       room:   'webinar-42',
+ *       ttl:    60 * 30,            // 30 minute viewer session
+ *       claims: { publish: false, subscribe: true, tier: 'free' },
+ *   });
+ *
+ * @example | RS256 with a per-tenant key id
+ *   const token = signJoinToken({
+ *       secret:    fs.readFileSync('./keys/tenant-A.private.pem'),
+ *       algorithm: 'RS256',
+ *       user:      req.user,
+ *       room:      'tenantA:lobby',
+ *       ttl:       300,
+ *       claims:    { kid: 'tenantA-2025-01' },
+ *   });
+ *
  * @section Signaling
  */
 function signJoinToken(opts = {})
@@ -80,6 +116,25 @@ function signJoinToken(opts = {})
  * @param {number} [opts.clockTolerance=0]
  * @returns {object} Verified payload.
  *
+ * @example | Manually verify a token (most apps never need this — the hub does it)
+ *   try {
+ *       const payload = verifyJoinToken(req.body.token, {
+ *           secret: process.env.WEBRTC_JWT_SECRET,
+ *           room:   'boardroom',
+ *       });
+ *       console.log('peer is', payload.user.id, 'publish =', payload.publish);
+ *   } catch (err) {
+ *       // err.code === 'INVALID_TOKEN'
+ *       res.status(401).json({ error: err.message });
+ *   }
+ *
+ * @example | Allow a 30-second clock skew between issuer and verifier
+ *   const payload = verifyJoinToken(token, {
+ *       secret:         sharedSecret,
+ *       room:           'lobby',
+ *       clockTolerance: 30,
+ *   });
+ *
  * @section Signaling
  */
 function verifyJoinToken(token, opts = {})

package/lib/webrtc/observe.js

@@ -1,10 +1,9 @@
 /**
  * @module webrtc/observe
- * @description Optional metrics + tracing wiring for a {@link SignalingHub}.
- *              Pass a `MetricsRegistry`, a `Tracer`, or both; the binder
- *              subscribes to the hub's lifecycle events and exports the six
- *              standard `zs_webrtc_*` Prometheus series plus per-operation
- *              OpenTelemetry-compatible spans.
+ * @description Optional metrics + tracing wiring for a `SignalingHub`.
+ *   `bindObservability(hub, { metrics, tracer })` exports the standard
+ *   `zs_webrtc_*` Prometheus series plus OTel-compatible spans. Both
+ *   adapters are duck-typed and opt-in.
  */
 
 'use strict';
@@ -215,9 +214,41 @@ function _bindTracing(hub, tracer)
  * @param {Tracer}          [opts.tracer]  - Tracer for span emission.
  * @returns {SignalingHub} The same hub, for chaining.
  *
- * @example | Plug into an existing app
+ * @example | Wire metrics + tracing from Zero Server's observe scope
+ *   const { createApp } = require('@zero-server/sdk');
+ *   const { Tracer } = require('@zero-server/sdk/observe');
+ *   const { SignalingHub, bindObservability } = require('@zero-server/webrtc');
+ *
+ *   const app = createApp();
+ *   const hub = new SignalingHub({ joinTokenSecret: process.env.JWT });
+ *
+ *   bindObservability(hub, {
+ *       metrics: app.metrics,        // exposes /metrics for Prometheus scraping
+ *       tracer:  new Tracer(),       // OTel-shaped tracer
+ *   });
+ *
+ *   app.ws('/rtc', (ws, req) => hub.attach(ws, { user: req.user, ip: req.ip }));
+ *
+ * @example | Metrics only (no tracer)
  *   const hub = new SignalingHub();
- *   bindObservability(hub, { metrics: app.metrics() });
+ *   bindObservability(hub, { metrics: app.metrics });
+ *   // Scrape /metrics:
+ *   //   zs_webrtc_peers_active{room="lobby"}              3
+ *   //   zs_webrtc_rooms_active                            1
+ *   //   zs_webrtc_signaling_messages_total{type="offer",direction="in",result="ok"} 17
+ *   //   zs_webrtc_offer_duration_ms_bucket{room="lobby",le="250"} 5
+ *
+ * @example | Custom prom-client registry adapter
+ *   const client = require('prom-client');
+ *   const reg = new client.Registry();
+ *   const adapter = {
+ *       counter:   ({ name, help, labels }) => new client.Counter({ name, help, labelNames: labels, registers: [reg] }),
+ *       gauge:     ({ name, help, labels }) => new client.Gauge  ({ name, help, labelNames: labels, registers: [reg] }),
+ *       histogram: ({ name, help, labels, buckets }) =>
+ *                  new client.Histogram({ name, help, labelNames: labels, buckets, registers: [reg] }),
+ *   };
+ *   bindObservability(hub, { metrics: adapter });
+ *   app.get('/metrics', async (_req, res) => res.type(reg.contentType).send(await reg.metrics()));
  */
 function bindObservability(hub, opts = {})
 {

package/lib/webrtc/peer.js

@@ -1,11 +1,20 @@
 /**
  * @module webrtc/peer
- * @description Per-connection state machine for a WebRTC signaling peer.
+ * @description Per-connection state machine for a signaling peer. Wraps a
+ *   `{ send, on, close }` transport (typically `app.ws()`'s
+ *   `WebSocketConnection`) and exposes JSEP message types as events.
+ *   Constructed by `hub.attach(transport, info)` — not directly.
  *
- *   A `Peer` wraps a transport object (typically a `WebSocketConnection`
- *   but any duck-typed `{ send, on, close }` works - see the unit tests
- *   for a minimal in-memory transport) and exposes the JSEP message
- *   types as ordinary events.  The hub is responsible for routing.
+ * @example | Inspect every newly-attached peer
+ *   hub.on('join', ({ peer, room }) => {
+ *       console.log(
+ *           'peer', peer.id,
+ *           'user=', peer.user && peer.user.id,
+ *           'ip=', peer.ip,
+ *           'joined', room.name,
+ *           'roster size=', room.size,
+ *       );
+ *   });
  */
 
 'use strict';
@@ -25,14 +34,32 @@ const PEER_STATE = Object.freeze({
 /**
  * One signaling peer attached to a `SignalingHub` via some transport.
  *
+ * `Peer` is created by `hub.attach(transport, info)` and lives until the
+ * underlying transport closes (or the hub kicks the peer for protocol
+ * abuse).  All event listeners are owned by the hub; application code
+ * subscribes to hub-level events such as `join`, `leave`, and the
+ * room-level `peer-joined` / `peer-left`.
+ *
  * @class
  * @section Peers
  *
- * @example
+ * @example | Push a per-peer welcome and tap mute events
  *   hub.on('join', ({ peer, room }) => {
- *       peer.send('welcome', { roomSize: room.size });
- *       peer.on('mute', ev => audit('mute', peer.id, ev.kind));
+ *       peer.send('welcome', { roomSize: room.size, you: peer.id });
+ *       peer.on?.('mute', ev => audit('mute', peer.id, ev.kind));
  *   });
+ *
+ * @example | Forcefully disconnect a peer that fails an auth refresh
+ *   async function rotateAuth(peer) {
+ *       const ok = await refreshSession(peer.user);
+ *       if (!ok) peer.close(4401, 'auth-expired');
+ *   }
+ *
+ * @example | Send a typed error frame instead of throwing inside a handler
+ *   if (msg.bytes.length > MAX_BYTES) {
+ *       peer.sendError('PAYLOAD_TOO_LARGE', 'frame > 64 KiB');
+ *       return;
+ *   }
  */
 class Peer
 {

package/lib/webrtc/room.js

@@ -1,10 +1,9 @@
 /**
  * @module webrtc/room
- * @description Room / channel abstraction for the WebRTC signaling hub.
- *
- *   A `Room` holds a set of `Peer`s plus a list of `require()` policy gates
- *   that decide whether a given peer may join.  Membership is in-process;
- *   the cluster adapter (PR 8) will fan room state out via pub/sub.
+ * @description Room / channel abstraction for the signaling hub. Holds a
+ *   set of peers plus a fluent chain of policy gates (`require()`,
+ *   `canPublish()`, `canSubscribe()`). Constructed lazily via
+ *   `hub.room(name)`; pair with `useCluster()` for multi-node membership.
  */
 
 'use strict';
@@ -20,11 +19,25 @@ const { SignalingError } = require('../errors');
  * @class
  * @section Rooms
  *
- * @example
+ * @example | Open a public lobby that anyone with a token may join
  *   hub.room('lobby').open();
+ *
+ * @example | Gate a room with role + per-publisher policies
  *   hub.room('boardroom')
  *       .require(peer => peer.user && peer.user.role === 'exec')
- *       .canPublish(peer => peer.user.isHost);
+ *       .canPublish(peer => peer.user.isHost)
+ *       .canSubscribe(peer => peer.user.verified === true)
+ *       .open();
+ *
+ * @example | Programmatic room metrics
+ *   const r = hub.room('webinar-42');
+ *   setInterval(() => log.info({ room: r.name, size: r.size }), 10_000);
+ *
+ * @example | Broadcast a system announcement from outside the message handler
+ *   hub.room('lobby').broadcast('notice', { text: 'Server restart in 60s' });
+ *
+ * @example | Boot the room and disconnect everyone gracefully
+ *   hub.room('lobby').close('shutdown');
  */
 class Room
 {

package/lib/webrtc/sdp.js

@@ -1,14 +1,9 @@
 /**
  * @module webrtc/sdp
- * @description Zero-dependency RFC 8866 Session Description Protocol parser and
- *              serializer, with WebRTC-specific attribute extraction (JSEP per
- *              RFC 8829: ice-ufrag, ice-pwd, fingerprint, setup, mid, rtcp-mux,
- *              direction, rtpmap, fmtp, rid, simulcast, ssrc, extmap, candidate).
- *
- *              The parser deliberately does NOT validate semantics that belong
- *              to a SignalingHub policy layer (codec allowlists, mDNS blocking,
- *              etc.) - it only structures the document.  Policy lives in
- *              `lib/webrtc/signaling.js`.
+ * @description Zero-dependency RFC 8866 SDP parser and serializer with
+ *   WebRTC-specific attribute extraction per RFC 8829 (ice-ufrag, ice-pwd,
+ *   fingerprint, setup, mid, rtcp-mux, rtpmap, fmtp, ssrc, etc.). Pure
+ *   structure — policy lives in the signaling layer.
  *
  * @see https://datatracker.ietf.org/doc/html/rfc8866
  * @see https://datatracker.ietf.org/doc/html/rfc8829