zero-query 1.0.9 → 1.2.0

package/tests/webrtc/room.test.js

@@ -0,0 +1,406 @@
+/**
+ * tests/webrtc/room.test.js
+ *
+ * Coverage for the high-level `Room` class and the `webrtc.join()`
+ * orchestrator:
+ *   - construction guards
+ *   - signaling `peer-joined` / `peer-left` mutate the `peers` Signal
+ *   - perfect-negotiation polite flag derived from lex comparison
+ *   - publish() adds tracks to every existing peer and remembers them
+ *   - publish before join: new peers receive remembered tracks
+ *   - unpublish() removes the sender on every peer
+ *   - dataChannel() opens a channel on every peer + on later joiners
+ *   - dataChannel send() broadcasts; on('message') fans-in from all peers
+ *   - peer's `track` event updates PeerInfo audio/video flags
+ *   - leave() closes every peer, sends `leave`, becomes idempotent
+ *   - event bus delivers `peer-joined`, `peer-left`, `error`
+ *   - join() handshake: connect → hello → join → joined → roster bootstrap
+ *   - join() timeout error code
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { Room, join } from '../../src/webrtc/room.js';
+import { Peer } from '../../src/webrtc/peer.js';
+import { SignalingClient } from '../../src/webrtc/signaling.js';
+import { WebRtcError } from '../../src/webrtc/errors.js';
+import {
+    FakeWebSocket, fakeSockets, resetFakeSockets,
+    FakeRTCPeerConnection, fakePeerConnections, resetFakePeerConnections,
+} from '../_helpers/webrtcFakes.js';
+
+
+/** Build a signaling client wired to a freshly opened FakeWebSocket. */
+async function openSignaling(selfId = 'self_z') {
+    const client = new SignalingClient('ws://localhost/rtc', {
+        WebSocket: FakeWebSocket,
+        reconnect: false,
+    });
+    const p = client.connect();
+    fakeSockets[0].fakeOpen();
+    fakeSockets[0].fakeMessage({ type: 'hello', peerId: selfId });
+    await p;
+    return client;
+}
+
+function makeRoom(selfId = 'self_z') {
+    return openSignaling(selfId).then((signaling) => new Room({
+        id: 'room1',
+        self: selfId,
+        signaling,
+        peerOptions: { RTCPeerConnection: FakeRTCPeerConnection },
+    }));
+}
+
+
+describe('Room (construction guards)', () => {
+    beforeEach(() => { resetFakeSockets(); resetFakePeerConnections(); });
+
+    it('throws when id is missing', async () => {
+        const sig = await openSignaling();
+        expect(() => new Room({ id: '', self: 'a', signaling: sig })).toThrow(WebRtcError);
+    });
+
+    it('throws when self is missing', async () => {
+        const sig = await openSignaling();
+        expect(() => new Room({ id: 'r', self: '', signaling: sig })).toThrow(WebRtcError);
+    });
+
+    it('throws when signaling is missing', () => {
+        expect(() => new Room({ id: 'r', self: 'a', signaling: null })).toThrow(WebRtcError);
+    });
+});
+
+
+describe('Room (mesh management)', () => {
+    beforeEach(() => { resetFakeSockets(); resetFakePeerConnections(); });
+
+    it('adds a peer when signaling emits peer-joined', async () => {
+        const room = await makeRoom('self_z');
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'peer_a' });
+        expect(room.peers.peek().size).toBe(1);
+        const info = room.peers.peek().get('peer_a');
+        expect(info).toBeDefined();
+        expect(info.id).toBe('peer_a');
+        expect(info.peer).toBeInstanceOf(Peer);
+        expect(info.connection).toBe('new');
+    });
+
+    it('ignores duplicate peer-joined frames', async () => {
+        const room = await makeRoom('self_z');
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'peer_a' });
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'peer_a' });
+        expect(room.peers.peek().size).toBe(1);
+    });
+
+    it('ignores a peer-joined frame for self', async () => {
+        const room = await makeRoom('self_z');
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'self_z' });
+        expect(room.peers.peek().size).toBe(0);
+    });
+
+    it('derives polite from lex compare (self > remote → polite)', async () => {
+        const room = await makeRoom('self_z');
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'peer_a' });
+        expect(room.peers.peek().get('peer_a').peer.polite).toBe(true);
+    });
+
+    it('derives polite from lex compare (self < remote → impolite)', async () => {
+        const room = await makeRoom('aa_self');
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'zz_peer' });
+        expect(room.peers.peek().get('zz_peer').peer.polite).toBe(false);
+    });
+
+    it('removes a peer on peer-left and closes its PC', async () => {
+        const room = await makeRoom('self_z');
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'peer_a' });
+        const info = room.peers.peek().get('peer_a');
+        fakeSockets[0].fakeMessage({ type: 'peer-left', id: 'peer_a' });
+        expect(room.peers.peek().size).toBe(0);
+        expect(info.peer.pc.closeCalls).toBe(1);
+    });
+
+    it('notifies subscribers when peers mutate', async () => {
+        const room = await makeRoom('self_z');
+        let snapshots = 0;
+        const unsub = room.peers.subscribe(() => { snapshots++; });
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'peer_a' });
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'peer_b' });
+        fakeSockets[0].fakeMessage({ type: 'peer-left',   id: 'peer_a' });
+        unsub();
+        expect(snapshots).toBe(3);
+    });
+});
+
+
+describe('Room (publish / unpublish)', () => {
+    beforeEach(() => { resetFakeSockets(); resetFakePeerConnections(); });
+
+    function fakeStream(tracks) {
+        return { id: 'stream_fake', getTracks: () => tracks.slice() };
+    }
+
+    it('publish() addTrack on every existing peer', async () => {
+        const room = await makeRoom('self_z');
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'peer_a' });
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'peer_b' });
+
+        const t1 = { kind: 'audio', id: 't1' };
+        await room.publish(fakeStream([t1]));
+
+        const a = room.peers.peek().get('peer_a').pc;
+        const b = room.peers.peek().get('peer_b').pc;
+        expect(a.addTrackCalls).toHaveLength(1);
+        expect(b.addTrackCalls).toHaveLength(1);
+        expect(a.addTrackCalls[0].track).toBe(t1);
+        expect(room.localTracks.peek()).toEqual([t1]);
+    });
+
+    it('publish() then late peer-joined → late peer also receives the track', async () => {
+        const room = await makeRoom('self_z');
+        const t1 = { kind: 'video', id: 't1' };
+        await room.publish(fakeStream([t1]));
+
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'peer_a' });
+        const a = room.peers.peek().get('peer_a').pc;
+        expect(a.addTrackCalls).toHaveLength(1);
+        expect(a.addTrackCalls[0].track).toBe(t1);
+    });
+
+    it('publish() is idempotent for the same track', async () => {
+        const room = await makeRoom('self_z');
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'peer_a' });
+        const t1 = { kind: 'audio', id: 't1' };
+        await room.publish(fakeStream([t1]));
+        await room.publish(fakeStream([t1]));
+        expect(room.peers.peek().get('peer_a').pc.addTrackCalls).toHaveLength(1);
+    });
+
+    it('unpublish() removes the sender on every peer', async () => {
+        const room = await makeRoom('self_z');
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'peer_a' });
+        const t1 = { kind: 'audio', id: 't1' };
+        const stream = fakeStream([t1]);
+        await room.publish(stream);
+        await room.unpublish(stream);
+        const a = room.peers.peek().get('peer_a').pc;
+        expect(a.removeTrackCalls).toHaveLength(1);
+        expect(room.localTracks.peek()).toEqual([]);
+    });
+
+    it('publish() rejects a non-MediaStream argument', async () => {
+        const room = await makeRoom('self_z');
+        await expect(room.publish(null)).rejects.toThrow(WebRtcError);
+    });
+});
+
+
+describe('Room (dataChannel multiplex)', () => {
+    beforeEach(() => { resetFakeSockets(); resetFakePeerConnections(); });
+
+    it('returns the same wrapper for the same label', async () => {
+        const room = await makeRoom('self_z');
+        const a = room.dataChannel('chat');
+        const b = room.dataChannel('chat');
+        expect(a).toBe(b);
+    });
+
+    it('opens the channel on every existing peer + every late joiner', async () => {
+        const room = await makeRoom('self_z');
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'peer_a' });
+        const dc = room.dataChannel('chat', { ordered: true });
+
+        const a = room.peers.peek().get('peer_a').pc;
+        expect(a.dataChannelCalls).toHaveLength(1);
+        expect(a.dataChannelCalls[0].label).toBe('chat');
+
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'peer_b' });
+        const b = room.peers.peek().get('peer_b').pc;
+        expect(b.dataChannelCalls).toHaveLength(1);
+        expect(b.dataChannelCalls[0].label).toBe('chat');
+        void dc;
+    });
+
+    it('send() broadcasts to every per-peer channel', async () => {
+        const room = await makeRoom('self_z');
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'peer_a' });
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'peer_b' });
+        const dc = room.dataChannel('chat');
+
+        const sendsA = [];
+        const sendsB = [];
+        const aPc = room.peers.peek().get('peer_a').pc;
+        const bPc = room.peers.peek().get('peer_b').pc;
+        aPc.dataChannelCalls[0].send = (d) => sendsA.push(d);
+        bPc.dataChannelCalls[0].send = (d) => sendsB.push(d);
+
+        dc.send('hello');
+        expect(sendsA).toEqual(['hello']);
+        expect(sendsB).toEqual(['hello']);
+    });
+
+    it('on("message") fans-in from every peer with (data, peerId)', async () => {
+        const room = await makeRoom('self_z');
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'peer_a' });
+        const dc = room.dataChannel('chat');
+        const received = [];
+        dc.on('message', (data, from) => received.push({ data, from }));
+
+        const aDc = room.peers.peek().get('peer_a').pc.dataChannelCalls[0];
+        // The wrapper attached an onmessage handler in tests (no addEventListener on the stub).
+        aDc.onmessage({ data: 'ping' });
+        expect(received).toEqual([{ data: 'ping', from: 'peer_a' }]);
+    });
+});
+
+
+describe('Room (peer events update PeerInfo)', () => {
+    beforeEach(() => { resetFakeSockets(); resetFakePeerConnections(); });
+
+    it('ontrack flips audio/video flags and adds the track to the stream', async () => {
+        const room = await makeRoom('self_z');
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'peer_a' });
+        const pc = room.peers.peek().get('peer_a').pc;
+        // Synthesize a remote audio track with no incoming stream to force fallback addTrack().
+        pc.fakeTrack({ track: { kind: 'audio', id: 't_audio' }, streams: [] });
+        pc.fakeTrack({ track: { kind: 'video', id: 't_video' }, streams: [] });
+        const info = room.peers.peek().get('peer_a');
+        expect(info.audio).toBe(true);
+        expect(info.video).toBe(true);
+    });
+
+    it('connectionstatechange propagates onto PeerInfo.connection', async () => {
+        const room = await makeRoom('self_z');
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'peer_a' });
+        const pc = room.peers.peek().get('peer_a').pc;
+        pc.fakeConnectionStateChange('connected');
+        expect(room.peers.peek().get('peer_a').connection).toBe('connected');
+    });
+});
+
+
+describe('Room (event bus)', () => {
+    beforeEach(() => { resetFakeSockets(); resetFakePeerConnections(); });
+
+    it('peer-joined and peer-left fire the corresponding events', async () => {
+        const room = await makeRoom('self_z');
+        const joined = [];
+        const left   = [];
+        room.on('peer-joined', (info) => joined.push(info.id));
+        room.on('peer-left',   (info) => left.push(info.id));
+
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'peer_a' });
+        fakeSockets[0].fakeMessage({ type: 'peer-left',   id: 'peer_a' });
+        expect(joined).toEqual(['peer_a']);
+        expect(left).toEqual(['peer_a']);
+    });
+
+    it('error fires when a peer\'s connection state goes "failed"', async () => {
+        const room = await makeRoom('self_z');
+        const errors = [];
+        room.on('error', (err) => errors.push(err));
+
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'peer_a' });
+        const pc = room.peers.peek().get('peer_a').pc;
+        pc.fakeConnectionStateChange('failed');
+        expect(errors.length).toBeGreaterThanOrEqual(1);
+        expect(errors[0]).toBeInstanceOf(WebRtcError);
+        expect(errors[0].code).toBe('ZQ_WEBRTC_PEER_FAILED');
+    });
+
+    it('off() removes a previously registered listener', async () => {
+        const room = await makeRoom('self_z');
+        const seen = [];
+        const cb = (info) => seen.push(info.id);
+        room.on('peer-joined', cb);
+        room.off('peer-joined', cb);
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'peer_a' });
+        expect(seen).toEqual([]);
+    });
+});
+
+
+describe('Room (leave)', () => {
+    beforeEach(() => { resetFakeSockets(); resetFakePeerConnections(); });
+
+    it('closes every peer, sends a leave frame, and clears state', async () => {
+        const room = await makeRoom('self_z');
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'peer_a' });
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'peer_b' });
+        const pcs = [
+            room.peers.peek().get('peer_a').pc,
+            room.peers.peek().get('peer_b').pc,
+        ];
+        await room.leave();
+        expect(room.closed).toBe(true);
+        expect(room.peers.peek().size).toBe(0);
+        for (const pc of pcs) expect(pc.closeCalls).toBe(1);
+        const leaves = fakeSockets[0].sentFrames.filter((f) => f.type === 'leave');
+        expect(leaves).toHaveLength(1);
+    });
+
+    it('is idempotent', async () => {
+        const room = await makeRoom('self_z');
+        await room.leave();
+        await room.leave();
+        expect(room.closed).toBe(true);
+    });
+
+    it('further peer-joined frames after leave() are ignored', async () => {
+        const room = await makeRoom('self_z');
+        await room.leave();
+        fakeSockets[0].fakeMessage({ type: 'peer-joined', id: 'peer_a' });
+        expect(room.peers.peek().size).toBe(0);
+    });
+});
+
+
+describe('webrtc.join()', () => {
+    beforeEach(() => { resetFakeSockets(); resetFakePeerConnections(); });
+
+    it('completes the handshake and seeds existing peers from joined.peers', async () => {
+        const p = join('ws://localhost/rtc', {
+            room: 'room1',
+            WebSocket: FakeWebSocket,
+            RTCPeerConnection: FakeRTCPeerConnection,
+            reconnect: false,
+        });
+        // Drive the handshake.
+        await Promise.resolve();
+        fakeSockets[0].fakeOpen();
+        fakeSockets[0].fakeMessage({ type: 'hello',  peerId: 'self_z' });
+        fakeSockets[0].fakeMessage({ type: 'joined', room: 'room1', peerId: 'self_z', peers: ['peer_a', 'peer_b'] });
+        const room = await p;
+
+        expect(room).toBeInstanceOf(Room);
+        expect(room.id).toBe('room1');
+        expect(room.self).toBe('self_z');
+        expect(room.peers.peek().size).toBe(2);
+        expect(room.peers.peek().has('peer_a')).toBe(true);
+        expect(room.peers.peek().has('peer_b')).toBe(true);
+        const joinFrames = fakeSockets[0].sentFrames.filter((f) => f.type === 'join');
+        expect(joinFrames).toHaveLength(1);
+        expect(joinFrames[0].room).toBe('room1');
+    });
+
+    it('rejects when url is missing', async () => {
+        await expect(join('', { room: 'r' })).rejects.toThrow(WebRtcError);
+    });
+
+    it('rejects when opts.room is missing', async () => {
+        await expect(join('ws://x', {})).rejects.toThrow(WebRtcError);
+    });
+
+    it('rejects with timeout when hello never arrives', async () => {
+        const p = join('ws://localhost/rtc', {
+            room: 'room1',
+            WebSocket: FakeWebSocket,
+            RTCPeerConnection: FakeRTCPeerConnection,
+            reconnect: false,
+            signalingTimeoutMs: 20,
+        });
+        await Promise.resolve();
+        fakeSockets[0].fakeOpen();
+        // Do not deliver `hello`.
+        await expect(p).rejects.toThrow(/timed out/i);
+    });
+});

package/tests/webrtc/sdp.test.js

@@ -0,0 +1,151 @@
+/**
+ * tests/webrtc/sdp.test.js
+ *
+ * Coverage for `src/webrtc/sdp.js`: parse extracts the WebRTC-relevant
+ * subset, validate enforces the same constraints the server-side hub
+ * applies, and both throw `SdpError` with stable codes on bad input.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { parseSdp, validateSdp, SDP_DIRECTIONS } from '../../src/webrtc/sdp.js';
+import { SdpError } from '../../src/webrtc/errors.js';
+import { MIN_SDP } from '../_helpers/webrtcFakes.js';
+
+
+describe('sdp.parseSdp', () => {
+    it('parses the canonical minimal SDP fixture', () => {
+        const d = parseSdp(MIN_SDP);
+        expect(d.version).toBe(0);
+        expect(d.media).toHaveLength(1);
+        const m = d.media[0];
+        expect(m.kind).toBe('audio');
+        expect(m.port).toBe(9);
+        expect(m.proto).toBe('UDP/TLS/RTP/SAVPF');
+        expect(m.fmts).toEqual(['111']);
+        expect(m.mid).toBe('0');
+        expect(m.iceUfrag).toBe('abcd');
+        expect(m.icePwd).toBeDefined();
+        expect(m.fingerprint).toBeDefined();
+        expect(m.fingerprint.algorithm).toBe('sha-256');
+        expect(m.setup).toBe('actpass');
+        expect(m.direction).toBe('sendrecv');
+        expect(m.rtpmaps).toHaveLength(1);
+        expect(m.rtpmaps[0]).toEqual({ payload: 111, codec: 'opus', clockRate: 48000, channels: 2 });
+    });
+
+    it('preserves unknown attributes on the raw attribute list', () => {
+        const sdp = MIN_SDP + 'a=custom-thing:hello\r\n';
+        const d = parseSdp(sdp);
+        const a = d.media[0].attributes.find((x) => x.key === 'custom-thing');
+        expect(a).toBeDefined();
+        expect(a.value).toBe('hello');
+    });
+
+    it('extracts a=candidate lines into media.candidates', () => {
+        const sdp = MIN_SDP + 'a=candidate:1 1 udp 1 1.2.3.4 5000 typ host\r\n';
+        const d = parseSdp(sdp);
+        expect(d.media[0].candidates).toHaveLength(1);
+        expect(d.media[0].candidates[0]).toBe('candidate:1 1 udp 1 1.2.3.4 5000 typ host');
+    });
+
+    it('throws SdpError on non-string input', () => {
+        expect(() => parseSdp(null)).toThrowError(SdpError);
+        expect(() => parseSdp(42)).toThrowError(SdpError);
+    });
+
+    it('throws SdpError on empty input', () => {
+        expect(() => parseSdp('')).toThrowError(SdpError);
+    });
+
+    it('throws SdpError when payload exceeds maxBytes', () => {
+        const huge = 'v=0\r\n' + 'a=x:'.padEnd(10_000, 'y') + '\r\n';
+        expect(() => parseSdp(huge, { maxBytes: 100 })).toThrowError(SdpError);
+    });
+
+    it('throws SdpError when SDP does not start with v=', () => {
+        expect(() => parseSdp('s=foo\r\n')).toThrowError(SdpError);
+    });
+
+    it('throws SdpError on malformed line', () => {
+        expect(() => parseSdp('v=0\r\nxxx\r\n')).toThrowError(SdpError);
+    });
+
+    it('honors LF-only line endings', () => {
+        const lf = MIN_SDP.replace(/\r\n/g, '\n');
+        const d = parseSdp(lf);
+        expect(d.media[0].iceUfrag).toBe('abcd');
+    });
+});
+
+
+describe('sdp.validateSdp', () => {
+    it('accepts a known-good SDP and returns the parsed structure', () => {
+        const d = validateSdp(MIN_SDP);
+        expect(d.media[0].iceUfrag).toBe('abcd');
+    });
+
+    it('rejects SDP with no m-lines', () => {
+        const noMedia = 'v=0\r\no=- 1 1 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\n';
+        expect(() => validateSdp(noMedia)).toThrowError(SdpError);
+    });
+
+    it('rejects SDP with wrong proto on a non-rejected m-line', () => {
+        const bad = MIN_SDP.replace('UDP/TLS/RTP/SAVPF', 'RTP/AVP');
+        expect(() => validateSdp(bad)).toThrowError(SdpError);
+    });
+
+    it('rejects SDP missing ice-ufrag', () => {
+        const bad = MIN_SDP.replace(/a=ice-ufrag:abcd\r\n/, '');
+        expect(() => validateSdp(bad)).toThrowError(SdpError);
+    });
+
+    it('rejects SDP missing ice-pwd', () => {
+        const bad = MIN_SDP.replace(/a=ice-pwd:[^\r\n]+\r\n/, '');
+        expect(() => validateSdp(bad)).toThrowError(SdpError);
+    });
+
+    it('rejects SDP missing fingerprint', () => {
+        const bad = MIN_SDP.replace(/a=fingerprint:[^\r\n]+\r\n/, '');
+        expect(() => validateSdp(bad)).toThrowError(SdpError);
+    });
+
+    it('accepts session-level ice-ufrag/ice-pwd/fingerprint as fallback', () => {
+        // Move the m-section attrs up to session level
+        const m = MIN_SDP;
+        const sessionLevel =
+            'v=0\r\n' +
+            'o=- 1 1 IN IP4 127.0.0.1\r\n' +
+            's=-\r\n' +
+            'a=ice-ufrag:abcd\r\n' +
+            'a=ice-pwd:0123456789abcdef0123456789abcd\r\n' +
+            'a=fingerprint:sha-256 AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99\r\n' +
+            't=0 0\r\n' +
+            'm=audio 9 UDP/TLS/RTP/SAVPF 111\r\n' +
+            'a=setup:actpass\r\n' +
+            'a=mid:0\r\n' +
+            'a=sendrecv\r\n' +
+            'a=rtpmap:111 opus/48000/2\r\n';
+        // Sanity: it should NOT throw, because session-level attrs are honored.
+        const d = validateSdp(sessionLevel);
+        expect(d.media[0].iceUfrag).toBeUndefined();    // raw subset: not on m-line
+        expect(d.attributes.find((a) => a.key === 'ice-ufrag').value).toBe('abcd');
+        // suppress unused-var lint
+        expect(m.length).toBeGreaterThan(0);
+    });
+
+    it('skips rejected m-lines (port=0)', () => {
+        const rejected = MIN_SDP.replace('m=audio 9 ', 'm=audio 0 ').replace(/a=ice-ufrag:[^\r\n]+\r\n/, '');
+        // port=0 means rejected and unvalidated, but no other m-line exists so should still fail "no m-lines"?
+        // It IS an m-line, just rejected; validator should not throw on it.
+        const d = validateSdp(rejected);
+        expect(d.media[0].port).toBe(0);
+    });
+});
+
+
+describe('sdp module constants', () => {
+    it('exports SDP_DIRECTIONS frozen', () => {
+        expect(SDP_DIRECTIONS).toEqual(['sendrecv', 'sendonly', 'recvonly', 'inactive']);
+        expect(Object.isFrozen(SDP_DIRECTIONS)).toBe(true);
+    });
+});

package/tests/webrtc/sfu-livekit.test.js

@@ -0,0 +1,119 @@
+/**
+ * tests/webrtc/sfu-livekit.test.js
+ */
+
+import { describe, it, expect } from 'vitest';
+import { loadSfuAdapter, createLivekitAdapter, SfuError } from '../../src/webrtc/index.js';
+
+
+function makeFakeLivekitClient({ failConnect = false } = {}) {
+    const events = { connect: [], disconnect: [] };
+    class FakeRoom {
+        constructor(opts) {
+            this.opts = opts;
+            events.connect.push([]);
+            events.disconnect.push([]);
+        }
+        async connect(url, token, connectOpts) {
+            this.lastConnect = { url, token, connectOpts };
+            if (failConnect) throw new Error('connect rejected');
+        }
+        async disconnect() {
+            this.disconnected = true;
+        }
+    }
+    return { mod: { Room: FakeRoom }, events };
+}
+
+
+describe('createLivekitAdapter (with mock)', () => {
+    it('loadSfuAdapter(\'livekit\') without livekit-client throws ZQ_WEBRTC_SFU_PEER_MISSING', async () => {
+        await expect(loadSfuAdapter('livekit')).rejects.toMatchObject({
+            code: 'ZQ_WEBRTC_SFU_PEER_MISSING',
+        });
+    });
+
+    it('throws ZQ_WEBRTC_SFU_BAD_MODULE when Room is missing', async () => {
+        await expect(createLivekitAdapter({ client: {} })).rejects.toMatchObject({
+            code: 'ZQ_WEBRTC_SFU_BAD_MODULE',
+        });
+    });
+
+    it('accepts a `default` export wrapper', async () => {
+        const { mod } = makeFakeLivekitClient();
+        const a = await createLivekitAdapter({ client: { default: mod } });
+        expect(a.name).toBe('livekit');
+    });
+
+    it('wraps Room-constructor exceptions in SfuError', async () => {
+        class BoomRoom { constructor() { throw new Error('boom'); } }
+        await expect(createLivekitAdapter({ client: { Room: BoomRoom } })).rejects.toMatchObject({
+            code: 'ZQ_WEBRTC_SFU_ROOM_FAILED',
+        });
+    });
+
+    it('builds an adapter with name=livekit, room, connected=false', async () => {
+        const { mod } = makeFakeLivekitClient();
+        const a = await loadSfuAdapter('livekit', { client: mod, roomOptions: { adaptiveStream: true } });
+        expect(a.name).toBe('livekit');
+        expect(a.room).toBeDefined();
+        expect(a.room.opts).toEqual({ adaptiveStream: true });
+        expect(a.connected).toBe(false);
+    });
+
+    it('connect() validates url and token', async () => {
+        const { mod } = makeFakeLivekitClient();
+        const a = await createLivekitAdapter({ client: mod });
+        await expect(a.connect('', 'tok')).rejects.toMatchObject({ code: 'ZQ_WEBRTC_SFU_BAD_URL' });
+        await expect(a.connect('wss://x', '')).rejects.toMatchObject({ code: 'ZQ_WEBRTC_SFU_BAD_TOKEN' });
+    });
+
+    it('connect() forwards url + token + opts and flips connected=true', async () => {
+        const { mod } = makeFakeLivekitClient();
+        const a = await createLivekitAdapter({ client: mod });
+        await a.connect('wss://lk.example', 'tok-123', { autoSubscribe: true });
+        expect(a.connected).toBe(true);
+        expect(a.room.lastConnect).toEqual({
+            url: 'wss://lk.example',
+            token: 'tok-123',
+            connectOpts: { autoSubscribe: true },
+        });
+    });
+
+    it('connect() wraps underlying failures', async () => {
+        const { mod } = makeFakeLivekitClient({ failConnect: true });
+        const a = await createLivekitAdapter({ client: mod });
+        await expect(a.connect('wss://lk.example', 'tok')).rejects.toMatchObject({
+            code: 'ZQ_WEBRTC_SFU_CONNECT_FAILED',
+        });
+        expect(a.connected).toBe(false);
+    });
+
+    it('disconnect() is a no-op when not connected', async () => {
+        const { mod } = makeFakeLivekitClient();
+        const a = await createLivekitAdapter({ client: mod });
+        await a.disconnect();
+        expect(a.room.disconnected).toBeUndefined();
+    });
+
+    it('disconnect() calls underlying disconnect and resets connected', async () => {
+        const { mod } = makeFakeLivekitClient();
+        const a = await createLivekitAdapter({ client: mod });
+        await a.connect('wss://lk.example', 'tok');
+        await a.disconnect();
+        expect(a.room.disconnected).toBe(true);
+        expect(a.connected).toBe(false);
+    });
+
+    it('join() throws ZQ_WEBRTC_SFU_JOIN_UNAVAILABLE (not yet wired)', async () => {
+        const { mod } = makeFakeLivekitClient();
+        const a = await createLivekitAdapter({ client: mod });
+        try {
+            await a.join({});
+            throw new Error('expected throw');
+        } catch (err) {
+            expect(err).toBeInstanceOf(SfuError);
+            expect(err.code).toBe('ZQ_WEBRTC_SFU_JOIN_UNAVAILABLE');
+        }
+    });
+});