@pjts/webrtc-client 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# Domain-Driven Design TypeScript Utilities / WebRTC Client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Framework-free browser building blocks for two-party WebRTC calls, pairing with `@pjts/webrtc-signalling`:
+
+- `createSignalling` — room inbox over `@pjts/websocket-client` with replay cursor, exactly-once delivery and an injected poll fallback
+- `createPeer` — `RTCPeerConnection` with perfect negotiation (polite/impolite, optional non-initiator), ICE trickle, ICE restart, stats sampler
+- `createChannels` — negotiated JSON data channels with fixed ids and an open-queue
+- `createAudioMeter`, `createSpeakingDetector`, `mixTracks`, `composeVideos` — media utilities
+- `createRecorder` — `MediaRecorder` wrapper with pause/resume and pause-free duration

package/dist/channels.d.ts

@@ -0,0 +1,20 @@
+export interface ChannelSpec {
+    /** Negotiated id — both peers must use the same id for the same name. */
+    id: number;
+    ordered?: boolean;
+    /** Messages buffered while the channel is not open; oldest dropped beyond this. Default 50. */
+    maxQueued?: number;
+}
+export interface TypedChannel<T> {
+    send(message: T): void;
+    onMessage(listener: (message: T) => void): () => void;
+    /** Called on every `open` — including after an ICE restart re-opened the channel. */
+    onOpen(listener: () => void): () => void;
+    isOpen(): boolean;
+    close(): void;
+}
+/**
+ * JSON data channels created with `negotiated: true` and fixed ids, so both peers create them
+ * independently — no in-band announcement, no ordering dependency on who connects first.
+ */
+export declare const createChannels: <M extends Record<string, unknown>>(pc: Pick<RTCPeerConnection, 'createDataChannel'>, spec: { [K in keyof M]: ChannelSpec; }) => { [K_1 in keyof M]: TypedChannel<M[K_1]>; };

package/dist/channels.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createChannels = void 0;
+/**
+ * JSON data channels created with `negotiated: true` and fixed ids, so both peers create them
+ * independently — no in-band announcement, no ordering dependency on who connects first.
+ */
+const createChannels = (pc, spec) => {
+    const result = {};
+    Object.keys(spec).forEach(name => {
+        const { id, ordered = true, maxQueued = 50 } = spec[name];
+        const dc = pc.createDataChannel(String(name), { negotiated: true, id, ordered });
+        const queue = [];
+        const messageListeners = new Set();
+        const openListeners = new Set();
+        dc.onopen = () => {
+            queue.splice(0).forEach(raw => dc.send(raw));
+            openListeners.forEach(l => l());
+        };
+        dc.onmessage = event => {
+            let parsed;
+            try {
+                parsed = JSON.parse(String(event.data));
+            }
+            catch {
+                return;
+            }
+            messageListeners.forEach(l => l(parsed));
+        };
+        result[name] = {
+            send(message) {
+                const raw = JSON.stringify(message);
+                if (dc.readyState === 'open') {
+                    dc.send(raw);
+                    return;
+                }
+                queue.push(raw);
+                if (queue.length > maxQueued)
+                    queue.shift();
+            },
+            onMessage(listener) {
+                messageListeners.add(listener);
+                return () => messageListeners.delete(listener);
+            },
+            onOpen(listener) {
+                openListeners.add(listener);
+                return () => openListeners.delete(listener);
+            },
+            isOpen: () => dc.readyState === 'open',
+            close: () => dc.close(),
+        };
+    });
+    return result;
+};
+exports.createChannels = createChannels;
+//# sourceMappingURL=channels.js.map

package/dist/channels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channels.js","sourceRoot":"","sources":["../src/channels.ts"],"names":[],"mappings":";;;AAiBA;;;GAGG;AACI,MAAM,cAAc,GAAG,CAC5B,EAAgD,EAChD,IAAqC,EACG,EAAE;IAC1C,MAAM,MAAM,GAAG,EAA4C,CAC1D;IAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAoB,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE;QACpD,MAAM,EAAE,EAAE,EAAE,OAAO,GAAG,IAAI,EAAE,SAAS,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;QACzD,MAAM,EAAE,GAAG,EAAE,CAAC,iBAAiB,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAA;QAChF,MAAM,KAAK,GAAa,EAAE,CAAA;QAC1B,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAA+B,CAAA;QAC/D,MAAM,aAAa,GAAG,IAAI,GAAG,EAAc,CAAA;QAE3C,EAAE,CAAC,MAAM,GAAG,GAAG,EAAE;YACf,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;YAC5C,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAA;QACjC,CAAC,CAAA;QACD,EAAE,CAAC,SAAS,GAAG,KAAK,CAAC,EAAE;YACrB,IAAI,MAAsB,CAAA;YAC1B,IAAI;gBACF,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;aACxC;YAAC,MAAM;gBACN,OAAM;aACP;YACD,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAA;QAC1C,CAAC,CAAA;QAED,MAAM,CAAC,IAAI,CAAC,GAAG;YACb,IAAI,CAAC,OAAO;gBACV,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;gBACnC,IAAI,EAAE,CAAC,UAAU,KAAK,MAAM,EAAE;oBAC5B,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;oBACZ,OAAM;iBACP;gBACD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;gBACf,IAAI,KAAK,CAAC,MAAM,GAAG,SAAS;oBAAE,KAAK,CAAC,KAAK,EAAE,CAAA;YAC7C,CAAC;YACD,SAAS,CAAC,QAAQ;gBAChB,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;gBAC9B,OAAO,GAAG,EAAE,CAAC,gBAAgB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;YAChD,CAAC;YACD,MAAM,CAAC,QAAQ;gBACb,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;gBAC3B,OAAO,GAAG,EAAE,CAAC,aAAa,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;YAC7C,CAAC;YACD,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,UAAU,KAAK,MAAM;YACtC,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE;SACxB,CAAA;IACH,CAAC,CAAC,CAAA;IACF,OAAO,MAAM,CAAA;AACf,CAAC,CAAA;AAjDY,QAAA,cAAc,kBAiD1B"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from './sequencer';
+export * from './signalling';
+export * from './peer';
+export * from './channels';
+export * from './media/speaking';
+export * from './media/audio';
+export * from './media/compose';
+export * from './media/recorder';
+export * from './media/quality';

package/dist/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./sequencer"), exports);
+tslib_1.__exportStar(require("./signalling"), exports);
+tslib_1.__exportStar(require("./peer"), exports);
+tslib_1.__exportStar(require("./channels"), exports);
+tslib_1.__exportStar(require("./media/speaking"), exports);
+tslib_1.__exportStar(require("./media/audio"), exports);
+tslib_1.__exportStar(require("./media/compose"), exports);
+tslib_1.__exportStar(require("./media/recorder"), exports);
+tslib_1.__exportStar(require("./media/quality"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,sDAA2B;AAC3B,uDAA4B;AAC5B,iDAAsB;AACtB,qDAA0B;AAC1B,2DAAgC;AAChC,wDAA6B;AAC7B,0DAA+B;AAC/B,2DAAgC;AAChC,0DAA+B"}

package/dist/media/audio.d.ts

@@ -0,0 +1,25 @@
+import { LevelSample, SpeakingDetectorOptions } from './speaking';
+export interface AudioMeterOptions extends SpeakingDetectorOptions {
+    audioContext: AudioContext;
+    /** Sampling interval. Default 50 ms. */
+    intervalMs?: number;
+    onLevel?: (sample: LevelSample & {
+        speaking: boolean;
+    }) => void;
+    now?: () => number;
+}
+/** RMS level + speaking flag of one audio track, sampled from an `AnalyserNode`. */
+export declare const createAudioMeter: (track: MediaStreamTrack, options: AudioMeterOptions) => {
+    detector: {
+        push(sample: LevelSample): boolean;
+        isSpeaking: () => boolean;
+        floorDb: () => number;
+        samplesBetween: (from: number, to: number) => LevelSample[];
+    };
+    stop(): void;
+};
+/** Sums audio tracks into one stream (for recording or a mixed speech-recognition input). */
+export declare const mixTracks: (tracks: MediaStreamTrack[], audioContext: AudioContext) => {
+    stream: MediaStream;
+    stop: () => void;
+};

package/dist/media/audio.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mixTracks = exports.createAudioMeter = void 0;
+const speaking_1 = require("./speaking");
+/** RMS level + speaking flag of one audio track, sampled from an `AnalyserNode`. */
+const createAudioMeter = (track, options) => {
+    const ctx = options.audioContext;
+    const now = options.now ?? (() => performance.now());
+    const source = ctx.createMediaStreamSource(new MediaStream([track]));
+    const analyser = ctx.createAnalyser();
+    analyser.fftSize = 1024;
+    source.connect(analyser);
+    const buffer = new Float32Array(analyser.fftSize);
+    const detector = (0, speaking_1.createSpeakingDetector)(options);
+    const timer = setInterval(() => {
+        analyser.getFloatTimeDomainData(buffer);
+        let sum = 0;
+        for (let i = 0; i < buffer.length; i++)
+            sum += buffer[i] * buffer[i];
+        const sample = { t: now(), rms: Math.sqrt(sum / buffer.length) };
+        const speaking = detector.push(sample);
+        options.onLevel?.({ ...sample, speaking });
+    }, options.intervalMs ?? 50);
+    return {
+        detector,
+        stop() {
+            clearInterval(timer);
+            source.disconnect();
+            analyser.disconnect();
+        },
+    };
+};
+exports.createAudioMeter = createAudioMeter;
+/** Sums audio tracks into one stream (for recording or a mixed speech-recognition input). */
+const mixTracks = (tracks, audioContext) => {
+    const destination = audioContext.createMediaStreamDestination();
+    const sources = tracks
+        .filter(t => t.kind === 'audio')
+        .map(track => {
+        const source = audioContext.createMediaStreamSource(new MediaStream([track]));
+        source.connect(destination);
+        return source;
+    });
+    return {
+        stream: destination.stream,
+        stop: () => sources.forEach(s => s.disconnect()),
+    };
+};
+exports.mixTracks = mixTracks;
+//# sourceMappingURL=audio.js.map

package/dist/media/audio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio.js","sourceRoot":"","sources":["../../src/media/audio.ts"],"names":[],"mappings":";;;AAAA,yCAAyF;AAUzF,oFAAoF;AAC7E,MAAM,gBAAgB,GAAG,CAAC,KAAuB,EAAE,OAA0B,EAAE,EAAE;IACtF,MAAM,GAAG,GAAG,OAAO,CAAC,YAAY,CAAA;IAChC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAA;IACpD,MAAM,MAAM,GAAG,GAAG,CAAC,uBAAuB,CAAC,IAAI,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IACpE,MAAM,QAAQ,GAAG,GAAG,CAAC,cAAc,EAAE,CAAA;IACrC,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAA;IACvB,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;IACxB,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;IACjD,MAAM,QAAQ,GAAG,IAAA,iCAAsB,EAAC,OAAO,CAAC,CAAA;IAEhD,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;QAC7B,QAAQ,CAAC,sBAAsB,CAAC,MAAM,CAAC,CAAA;QACvC,IAAI,GAAG,GAAG,CAAC,CAAA;QACX,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE;YAAE,GAAG,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAA;QACpE,MAAM,MAAM,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,CAAA;QAChE,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACtC,OAAO,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAA;IAC5C,CAAC,EAAE,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC,CAAA;IAE5B,OAAO;QACL,QAAQ;QACR,IAAI;YACF,aAAa,CAAC,KAAK,CAAC,CAAA;YACpB,MAAM,CAAC,UAAU,EAAE,CAAA;YACnB,QAAQ,CAAC,UAAU,EAAE,CAAA;QACvB,CAAC;KACF,CAAA;AACH,CAAC,CAAA;AA3BY,QAAA,gBAAgB,oBA2B5B;AAED,6FAA6F;AACtF,MAAM,SAAS,GAAG,CAAC,MAA0B,EAAE,YAA0B,EAAE,EAAE;IAClF,MAAM,WAAW,GAAG,YAAY,CAAC,4BAA4B,EAAE,CAAA;IAC/D,MAAM,OAAO,GAAG,MAAM;SACnB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC;SAC/B,GAAG,CAAC,KAAK,CAAC,EAAE;QACX,MAAM,MAAM,GAAG,YAAY,CAAC,uBAAuB,CAAC,IAAI,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;QAC7E,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;QAC3B,OAAO,MAAM,CAAA;IACf,CAAC,CAAC,CAAA;IACJ,OAAO;QACL,MAAM,EAAE,WAAW,CAAC,MAAM;QAC1B,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;KACjD,CAAA;AACH,CAAC,CAAA;AAbY,QAAA,SAAS,aAarB"}

package/dist/media/compose.d.ts

@@ -0,0 +1,25 @@
+export interface ComposeOptions {
+    width?: number;
+    height?: number;
+    fps?: number;
+    /** Canvas background (letterboxing). Default near-black. */
+    background?: string;
+}
+export interface Tile {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** Fit a source of `sw×sh` into a box, preserving aspect ratio (contain). */
+export declare const fitContain: (sw: number, sh: number, box: Tile) => Tile;
+/** Equal side-by-side boxes for `count` sources on a `width×height` canvas. */
+export declare const sideBySide: (count: number, width: number, height: number) => Tile[];
+/**
+ * Draws the given `<video>` elements side by side on a canvas and returns its captured stream — a single
+ * video track for `MediaRecorder`. Sources whose video is missing are left as background.
+ */
+export declare const composeVideos: (videos: HTMLVideoElement[], options?: ComposeOptions) => {
+    stream: MediaStream;
+    stop(): void;
+};

package/dist/media/compose.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.composeVideos = exports.sideBySide = exports.fitContain = void 0;
+/** Fit a source of `sw×sh` into a box, preserving aspect ratio (contain). */
+const fitContain = (sw, sh, box) => {
+    if (!sw || !sh)
+        return box;
+    const scale = Math.min(box.w / sw, box.h / sh);
+    const w = sw * scale;
+    const h = sh * scale;
+    return { x: box.x + (box.w - w) / 2, y: box.y + (box.h - h) / 2, w, h };
+};
+exports.fitContain = fitContain;
+/** Equal side-by-side boxes for `count` sources on a `width×height` canvas. */
+const sideBySide = (count, width, height) => Array.from({ length: count }, (_, i) => ({ x: (width / count) * i, y: 0, w: width / count, h: height }));
+exports.sideBySide = sideBySide;
+/**
+ * Draws the given `<video>` elements side by side on a canvas and returns its captured stream — a single
+ * video track for `MediaRecorder`. Sources whose video is missing are left as background.
+ */
+const composeVideos = (videos, options = {}) => {
+    const width = options.width ?? 1280;
+    const height = options.height ?? 360;
+    const fps = options.fps ?? 15;
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    const ctx = canvas.getContext('2d');
+    const boxes = (0, exports.sideBySide)(videos.length, width, height);
+    const draw = () => {
+        ctx.fillStyle = options.background ?? '#1C1917';
+        ctx.fillRect(0, 0, width, height);
+        videos.forEach((video, i) => {
+            if (video.readyState < 2 || !video.videoWidth)
+                return;
+            const tile = (0, exports.fitContain)(video.videoWidth, video.videoHeight, boxes[i]);
+            ctx.drawImage(video, tile.x, tile.y, tile.w, tile.h);
+        });
+    };
+    draw();
+    const timer = setInterval(draw, 1000 / fps);
+    const stream = canvas.captureStream(fps);
+    return {
+        stream,
+        stop() {
+            clearInterval(timer);
+            stream.getTracks().forEach(t => t.stop());
+        },
+    };
+};
+exports.composeVideos = composeVideos;
+//# sourceMappingURL=compose.js.map

package/dist/media/compose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.js","sourceRoot":"","sources":["../../src/media/compose.ts"],"names":[],"mappings":"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"}

package/dist/media/quality.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Outgoing media quality: send profiles, sender parameters and an adaptive governor.
+ *
+ * Everything here works through `RTCRtpSender.setParameters()` — live, without renegotiation. The
+ * camera is captured once at the best profile and scaled down per sender, so switching levels never
+ * touches getUserMedia. Audio is always protected: it gets high priority and the video gives way first.
+ */
+/** 0 = best. */
+export type QualityLevel = 0 | 1 | 2 | 3;
+export interface VideoProfile {
+    label: 'full' | 'high' | 'medium' | 'low';
+    height: number;
+    frameRate: number;
+    /** bits per second */
+    maxBitrate: number;
+}
+export declare const VIDEO_PROFILES: readonly VideoProfile[];
+export declare const LOWEST_LEVEL: QualityLevel;
+/** 720p — where adaptive mode starts; 1080p is earned with measured headroom. */
+export declare const DEFAULT_LEVEL: QualityLevel;
+/** Best level a camera track can feed without upscaling: 1080p only from a real 1080p capture. */
+export declare const bestLevelFor: (trackHeight: number | undefined) => QualityLevel;
+/** Screen share keeps full resolution (text stays readable) and gives up frame rate instead. */
+export declare const SCREEN_PROFILE: {
+    readonly frameRate: 5;
+    readonly maxBitrate: 1200000;
+};
+/** Opus at 48 kbps is transparent for speech; the browser lowers it under congestion. */
+export declare const AUDIO_MAX_BITRATE = 48000;
+/**
+ * Camera capture constraints for the best profile — scaled down per sender afterwards. `ideal`, so a
+ * 720p webcam simply delivers 720p (and `bestLevelFor` then never offers 1080p).
+ */
+export declare const cameraConstraints: (deviceId?: string) => MediaTrackConstraints;
+/** Voice processing on — the call is speech, not music. */
+export declare const microphoneConstraints: (deviceId?: string) => MediaTrackConstraints;
+/** How much to shrink a track of `trackHeight` to reach `targetHeight` (never upscales). */
+export declare const scaleFor: (trackHeight: number | undefined, targetHeight: number) => number;
+/**
+ * Apply a video level (or the screen profile) to a sender. Resolves `false` when the sender is not
+ * negotiated yet or the browser rejected the parameters — callers simply re-apply later.
+ */
+export declare function applyVideoQuality(sender: RTCRtpSender, opts: {
+    level: QualityLevel;
+    screen?: boolean; /** false = audio-only: the encoder stops, the track stays. */
+    active?: boolean;
+}): Promise<boolean>;
+/** Speech first: the audio sender is prioritised over video on the wire and in the browser's pacer. */
+export declare function applyAudioPriority(sender: RTCRtpSender): Promise<boolean>;
+export interface QualitySample {
+    /** epoch ms */
+    t: number;
+    /** seconds */
+    roundTripTime: number | null;
+    /** 0..1 — loss of what WE send, as reported back by the remote side (preferred). */
+    outboundLoss: number | null;
+    /** 0..1 — loss of what we receive; used when the outbound figure is unknown. */
+    packetLoss: number | null;
+    /** bits per second — the congestion controller's estimate for the selected pair. */
+    availableOutgoingBitrate: number | null;
+}
+export interface QualityGovernorOptions {
+    /** Best level the governor may reach (camera capability, user or remote cap). Default 0. */
+    ceiling?: QualityLevel;
+    /** Where to start (and restart after `setCeiling`). Default `DEFAULT_LEVEL` (720p), clamped to the ceiling. */
+    start?: QualityLevel;
+    /** Sustained trouble before stepping down. Default 9 s. */
+    downAfterMs?: number;
+    /** Sustained health before stepping back up. Default 30 s. */
+    upAfterMs?: number;
+}
+export interface QualityGovernor {
+    level(): QualityLevel;
+    /** Feed one stats sample; returns the step taken, if any. */
+    push(sample: QualitySample): 'down' | 'up' | null;
+    setCeiling(ceiling: QualityLevel, start?: QualityLevel): void;
+}
+/**
+ * Step video down after `downAfterMs` of trouble (loss, latency, or the bandwidth estimate below what
+ * the current level needs) and back up after `upAfterMs` of headroom. Pure — the caller samples stats
+ * and applies the level, so this is unit-testable without a browser.
+ */
+export declare function createQualityGovernor(options?: QualityGovernorOptions): QualityGovernor;

package/dist/media/quality.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * Outgoing media quality: send profiles, sender parameters and an adaptive governor.
+ *
+ * Everything here works through `RTCRtpSender.setParameters()` — live, without renegotiation. The
+ * camera is captured once at the best profile and scaled down per sender, so switching levels never
+ * touches getUserMedia. Audio is always protected: it gets high priority and the video gives way first.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createQualityGovernor = exports.applyAudioPriority = exports.applyVideoQuality = exports.scaleFor = exports.microphoneConstraints = exports.cameraConstraints = exports.AUDIO_MAX_BITRATE = exports.SCREEN_PROFILE = exports.bestLevelFor = exports.DEFAULT_LEVEL = exports.LOWEST_LEVEL = exports.VIDEO_PROFILES = void 0;
+exports.VIDEO_PROFILES = [
+    { label: 'full', height: 1080, frameRate: 30, maxBitrate: 3_500_000 },
+    { label: 'high', height: 720, frameRate: 30, maxBitrate: 1_500_000 },
+    { label: 'medium', height: 480, frameRate: 24, maxBitrate: 750_000 },
+    { label: 'low', height: 240, frameRate: 15, maxBitrate: 250_000 },
+];
+exports.LOWEST_LEVEL = 3;
+/** 720p — where adaptive mode starts; 1080p is earned with measured headroom. */
+exports.DEFAULT_LEVEL = 1;
+/** Best level a camera track can feed without upscaling: 1080p only from a real 1080p capture. */
+const bestLevelFor = (trackHeight) => ((trackHeight ?? 0) >= 1080 ? 0 : exports.DEFAULT_LEVEL);
+exports.bestLevelFor = bestLevelFor;
+/** Screen share keeps full resolution (text stays readable) and gives up frame rate instead. */
+exports.SCREEN_PROFILE = { frameRate: 5, maxBitrate: 1_200_000 };
+/** Opus at 48 kbps is transparent for speech; the browser lowers it under congestion. */
+exports.AUDIO_MAX_BITRATE = 48_000;
+/**
+ * Camera capture constraints for the best profile — scaled down per sender afterwards. `ideal`, so a
+ * 720p webcam simply delivers 720p (and `bestLevelFor` then never offers 1080p).
+ */
+const cameraConstraints = (deviceId) => ({
+    ...(deviceId ? { deviceId: { exact: deviceId } } : {}),
+    width: { ideal: 1920 },
+    height: { ideal: 1080 },
+    frameRate: { ideal: 30, max: 30 },
+});
+exports.cameraConstraints = cameraConstraints;
+/** Voice processing on — the call is speech, not music. */
+const microphoneConstraints = (deviceId) => ({
+    ...(deviceId ? { deviceId: { exact: deviceId } } : {}),
+    echoCancellation: true,
+    noiseSuppression: true,
+    autoGainControl: true,
+});
+exports.microphoneConstraints = microphoneConstraints;
+/** How much to shrink a track of `trackHeight` to reach `targetHeight` (never upscales). */
+const scaleFor = (trackHeight, targetHeight) => trackHeight && trackHeight > targetHeight ? trackHeight / targetHeight : 1;
+exports.scaleFor = scaleFor;
+const withEncoding = (sender, patch) => {
+    const params = sender.getParameters();
+    // Chrome returns an empty list before negotiation completes; setParameters would then throw.
+    if (!params.encodings?.length)
+        return Promise.resolve(false);
+    patch(params.encodings[0], params);
+    return sender.setParameters(params).then(() => true, () => false);
+};
+/**
+ * Apply a video level (or the screen profile) to a sender. Resolves `false` when the sender is not
+ * negotiated yet or the browser rejected the parameters — callers simply re-apply later.
+ */
+function applyVideoQuality(sender, opts) {
+    const track = sender.track;
+    return withEncoding(sender, (enc, params) => {
+        enc.active = opts.active ?? true;
+        enc.priority = 'low';
+        enc.networkPriority = 'low';
+        if (opts.screen) {
+            enc.maxBitrate = exports.SCREEN_PROFILE.maxBitrate;
+            enc.maxFramerate = exports.SCREEN_PROFILE.frameRate;
+            enc.scaleResolutionDownBy = 1;
+            params.degradationPreference = 'maintain-resolution';
+        }
+        else {
+            const profile = exports.VIDEO_PROFILES[opts.level];
+            enc.maxBitrate = profile.maxBitrate;
+            enc.maxFramerate = profile.frameRate;
+            enc.scaleResolutionDownBy = (0, exports.scaleFor)(track?.getSettings().height, profile.height);
+            params.degradationPreference = 'balanced';
+        }
+    });
+}
+exports.applyVideoQuality = applyVideoQuality;
+/** Speech first: the audio sender is prioritised over video on the wire and in the browser's pacer. */
+function applyAudioPriority(sender) {
+    return withEncoding(sender, (enc) => {
+        enc.priority = 'high';
+        enc.networkPriority = 'high';
+        enc.maxBitrate = exports.AUDIO_MAX_BITRATE;
+    });
+}
+exports.applyAudioPriority = applyAudioPriority;
+const BAD_RTT = 0.4;
+const BAD_LOSS = 0.05;
+const GOOD_RTT = 0.25;
+const GOOD_LOSS = 0.02;
+/**
+ * Step video down after `downAfterMs` of trouble (loss, latency, or the bandwidth estimate below what
+ * the current level needs) and back up after `upAfterMs` of headroom. Pure — the caller samples stats
+ * and applies the level, so this is unit-testable without a browser.
+ */
+function createQualityGovernor(options = {}) {
+    const downAfter = options.downAfterMs ?? 9_000;
+    const upAfter = options.upAfterMs ?? 30_000;
+    let ceiling = options.ceiling ?? 0;
+    const clampStart = (start) => Math.max(ceiling, start ?? exports.DEFAULT_LEVEL);
+    let level = clampStart(options.start);
+    let badSince = null;
+    let goodSince = null;
+    const loss = (s) => s.outboundLoss ?? s.packetLoss;
+    const bad = (s) => (s.roundTripTime ?? 0) > BAD_RTT ||
+        (loss(s) ?? 0) > BAD_LOSS ||
+        (s.availableOutgoingBitrate !== null && s.availableOutgoingBitrate < exports.VIDEO_PROFILES[level].maxBitrate * 0.7);
+    const good = (s) => {
+        if (level <= ceiling)
+            return false;
+        const up = exports.VIDEO_PROFILES[level - 1];
+        // 1080p is only earned with a MEASURED estimate; lower levels may also return on loss/RTT alone.
+        const bitrateOk = s.availableOutgoingBitrate === null ? level - 1 > 0 : s.availableOutgoingBitrate > up.maxBitrate * 1.2;
+        return (s.roundTripTime ?? 0) < GOOD_RTT && (loss(s) ?? 0) < GOOD_LOSS && bitrateOk;
+    };
+    return {
+        level: () => level,
+        setCeiling(next, start) {
+            ceiling = next;
+            level = clampStart(start);
+            badSince = goodSince = null;
+        },
+        push(s) {
+            if (bad(s)) {
+                goodSince = null;
+                badSince = badSince ?? s.t;
+                if (level < exports.LOWEST_LEVEL && s.t - badSince >= downAfter) {
+                    level = (level + 1);
+                    badSince = null;
+                    return 'down';
+                }
+                return null;
+            }
+            badSince = null;
+            if (good(s)) {
+                goodSince = goodSince ?? s.t;
+                if (s.t - goodSince >= upAfter) {
+                    level = (level - 1);
+                    goodSince = null;
+                    return 'up';
+                }
+            }
+            else {
+                goodSince = null;
+            }
+            return null;
+        },
+    };
+}
+exports.createQualityGovernor = createQualityGovernor;
+//# sourceMappingURL=quality.js.map

package/dist/media/quality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality.js","sourceRoot":"","sources":["../../src/media/quality.ts"],"names":[],"mappings":"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"}

package/dist/media/recorder.d.ts

@@ -0,0 +1,38 @@
+export type RecorderState = 'inactive' | 'recording' | 'paused';
+export interface RecorderOptions {
+    stream: MediaStream;
+    /** Candidates in order of preference; the first supported one is used. */
+    mimeTypes: string[];
+    /** Chunk interval. Default 10 000 ms. */
+    timesliceMs?: number;
+    onChunk?: (chunk: Blob) => void;
+    /** Test seams. */
+    MediaRecorderImpl?: typeof MediaRecorder;
+    now?: () => number;
+}
+export interface RecordingResult {
+    blob: Blob;
+    mimeType: string;
+    /** Recorded time excluding pauses. */
+    durationMs: number;
+    sizeBytes: number;
+}
+export declare const pickMimeType: (candidates: string[], isSupported: (type: string) => boolean) => string;
+/** Duration bookkeeping that excludes paused spans. */
+export declare const createClock: (now: () => number) => {
+    start: () => number;
+    pause: () => void;
+    elapsed: () => number;
+};
+/** `MediaRecorder` wrapper: pause/resume, chunked capture, and a single Blob on stop. */
+export declare const createRecorder: (options: RecorderOptions) => {
+    mimeType: () => string;
+    state: () => RecorderState;
+    durationMs: () => number;
+    sizeBytes: () => number;
+    start(): void;
+    pause(): void;
+    resume(): void;
+    stop(): Promise<RecordingResult>;
+};
+export type SessionRecorder = ReturnType<typeof createRecorder>;

package/dist/media/recorder.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRecorder = exports.createClock = exports.pickMimeType = void 0;
+const pickMimeType = (candidates, isSupported) => candidates.find(type => isSupported(type)) ?? '';
+exports.pickMimeType = pickMimeType;
+/** Duration bookkeeping that excludes paused spans. */
+const createClock = (now) => {
+    let accumulated = 0;
+    let since = null;
+    return {
+        start: () => (since = now()),
+        pause: () => {
+            if (since !== null)
+                accumulated += now() - since;
+            since = null;
+        },
+        elapsed: () => accumulated + (since !== null ? now() - since : 0),
+    };
+};
+exports.createClock = createClock;
+/** `MediaRecorder` wrapper: pause/resume, chunked capture, and a single Blob on stop. */
+const createRecorder = (options) => {
+    const Impl = options.MediaRecorderImpl ?? MediaRecorder;
+    const mimeType = (0, exports.pickMimeType)(options.mimeTypes, t => Impl.isTypeSupported(t));
+    const recorder = new Impl(options.stream, mimeType ? { mimeType } : undefined);
+    const chunks = [];
+    const clock = (0, exports.createClock)(options.now ?? (() => performance.now()));
+    let sizeBytes = 0;
+    recorder.ondataavailable = event => {
+        if (!event.data || event.data.size === 0)
+            return;
+        chunks.push(event.data);
+        sizeBytes += event.data.size;
+        options.onChunk?.(event.data);
+    };
+    return {
+        mimeType: () => recorder.mimeType || mimeType,
+        state: () => recorder.state,
+        durationMs: () => clock.elapsed(),
+        sizeBytes: () => sizeBytes,
+        start() {
+            recorder.start(options.timesliceMs ?? 10_000);
+            clock.start();
+        },
+        pause() {
+            if (recorder.state !== 'recording')
+                return;
+            recorder.pause();
+            clock.pause();
+        },
+        resume() {
+            if (recorder.state !== 'paused')
+                return;
+            recorder.resume();
+            clock.start();
+        },
+        stop() {
+            return new Promise(resolve => {
+                const finish = () => {
+                    const type = recorder.mimeType || mimeType || 'application/octet-stream';
+                    const blob = new Blob(chunks, { type });
+                    resolve({ blob, mimeType: type, durationMs: clock.elapsed(), sizeBytes: blob.size });
+                };
+                if (recorder.state === 'inactive')
+                    return finish();
+                clock.pause();
+                recorder.onstop = finish;
+                recorder.stop();
+            });
+        },
+    };
+};
+exports.createRecorder = createRecorder;
+//# sourceMappingURL=recorder.js.map

package/dist/media/recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.js","sourceRoot":"","sources":["../../src/media/recorder.ts"],"names":[],"mappings":"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"}

package/dist/media/speaking.d.ts

@@ -0,0 +1,29 @@
+export interface LevelSample {
+    /** Milliseconds (same clock as the caller's `now`). */
+    t: number;
+    /** RMS of the window, 0..1. */
+    rms: number;
+}
+export interface SpeakingDetectorOptions {
+    /** Speaking when the level exceeds the noise floor by this many dB… Default 12. */
+    marginDb?: number;
+    /** …for at least this long. Default 150 ms. */
+    minSpeakingMs?: number;
+    /** Stay "speaking" this long after the level drops (avoids flicker between words). Default 300 ms. */
+    holdMs?: number;
+    /** Samples kept for `samplesBetween` (attribution). Default 1200 (~60 s at 50 ms). */
+    historySize?: number;
+}
+export declare const toDb: (rms: number) => number;
+/**
+ * Pure speaking detector over RMS samples with an adaptive noise floor: the floor follows quiet passages
+ * quickly and loud ones slowly, so background noise is learnt while speech is not.
+ */
+export declare const createSpeakingDetector: (options?: SpeakingDetectorOptions) => {
+    push(sample: LevelSample): boolean;
+    isSpeaking: () => boolean;
+    floorDb: () => number;
+    /** Samples with `from <= t <= to` — e.g. the window of a speech-recognition result. */
+    samplesBetween: (from: number, to: number) => LevelSample[];
+};
+export type SpeakingDetector = ReturnType<typeof createSpeakingDetector>;

package/dist/media/speaking.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSpeakingDetector = exports.toDb = void 0;
+const toDb = (rms) => (rms > 0 ? 20 * Math.log10(rms) : -100);
+exports.toDb = toDb;
+/**
+ * Pure speaking detector over RMS samples with an adaptive noise floor: the floor follows quiet passages
+ * quickly and loud ones slowly, so background noise is learnt while speech is not.
+ */
+const createSpeakingDetector = (options = {}) => {
+    const marginDb = options.marginDb ?? 12;
+    const minSpeakingMs = options.minSpeakingMs ?? 150;
+    const holdMs = options.holdMs ?? 300;
+    const historySize = options.historySize ?? 1200;
+    let floorDb = -60;
+    let aboveSince = null;
+    let lastAbove = -Infinity;
+    let speaking = false;
+    const history = [];
+    return {
+        push(sample) {
+            history.push(sample);
+            if (history.length > historySize)
+                history.shift();
+            const db = (0, exports.toDb)(sample.rms);
+            floorDb = db < floorDb ? floorDb + (db - floorDb) * 0.3 : floorDb + (db - floorDb) * 0.002;
+            floorDb = Math.max(floorDb, -90);
+            const above = db > floorDb + marginDb;
+            if (above) {
+                aboveSince = aboveSince ?? sample.t;
+                lastAbove = sample.t;
+                if (sample.t - aboveSince >= minSpeakingMs)
+                    speaking = true;
+            }
+            else {
+                aboveSince = null;
+                if (sample.t - lastAbove > holdMs)
+                    speaking = false;
+            }
+            return speaking;
+        },
+        isSpeaking: () => speaking,
+        floorDb: () => floorDb,
+        /** Samples with `from <= t <= to` — e.g. the window of a speech-recognition result. */
+        samplesBetween: (from, to) => history.filter(s => s.t >= from && s.t <= to),
+    };
+};
+exports.createSpeakingDetector = createSpeakingDetector;
+//# sourceMappingURL=speaking.js.map

package/dist/media/speaking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"speaking.js","sourceRoot":"","sources":["../../src/media/speaking.ts"],"names":[],"mappings":";;;AAkBO,MAAM,IAAI,GAAG,CAAC,GAAW,EAAE,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;AAA/D,QAAA,IAAI,QAA2D;AAE5E;;;GAGG;AACI,MAAM,sBAAsB,GAAG,CAAC,UAAmC,EAAE,EAAE,EAAE;IAC9E,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAA;IACvC,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,GAAG,CAAA;IAClD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,GAAG,CAAA;IACpC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,IAAI,CAAA;IAE/C,IAAI,OAAO,GAAG,CAAC,EAAE,CAAA;IACjB,IAAI,UAAU,GAAkB,IAAI,CAAA;IACpC,IAAI,SAAS,GAAG,CAAC,QAAQ,CAAA;IACzB,IAAI,QAAQ,GAAG,KAAK,CAAA;IACpB,MAAM,OAAO,GAAkB,EAAE,CAAA;IAEjC,OAAO;QACL,IAAI,CAAC,MAAmB;YACtB,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;YACpB,IAAI,OAAO,CAAC,MAAM,GAAG,WAAW;gBAAE,OAAO,CAAC,KAAK,EAAE,CAAA;YACjD,MAAM,EAAE,GAAG,IAAA,YAAI,EAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YAC3B,OAAO,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC,GAAG,KAAK,CAAA;YAC1F,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAA;YAChC,MAAM,KAAK,GAAG,EAAE,GAAG,OAAO,GAAG,QAAQ,CAAA;YACrC,IAAI,KAAK,EAAE;gBACT,UAAU,GAAG,UAAU,IAAI,MAAM,CAAC,CAAC,CAAA;gBACnC,SAAS,GAAG,MAAM,CAAC,CAAC,CAAA;gBACpB,IAAI,MAAM,CAAC,CAAC,GAAG,UAAU,IAAI,aAAa;oBAAE,QAAQ,GAAG,IAAI,CAAA;aAC5D;iBAAM;gBACL,UAAU,GAAG,IAAI,CAAA;gBACjB,IAAI,MAAM,CAAC,CAAC,GAAG,SAAS,GAAG,MAAM;oBAAE,QAAQ,GAAG,KAAK,CAAA;aACpD;YACD,OAAO,QAAQ,CAAA;QACjB,CAAC;QACD,UAAU,EAAE,GAAG,EAAE,CAAC,QAAQ;QAC1B,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO;QACtB,uFAAuF;QACvF,cAAc,EAAE,CAAC,IAAY,EAAE,EAAU,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;KAC5F,CAAA;AACH,CAAC,CAAA;AAnCY,QAAA,sBAAsB,0BAmClC"}

package/dist/peer.d.ts

@@ -0,0 +1,52 @@
+export type CandidateType = 'host' | 'srflx' | 'prflx' | 'relay' | 'unknown';
+export interface PeerStats {
+    /** Seconds, from the selected candidate pair. */
+    roundTripTime: number | null;
+    /** Fraction of inbound RTP packets lost since the previous sample (0..1). */
+    packetLoss: number | null;
+    /** Local candidate type of the selected pair — `relay` means TURN. */
+    candidateType: CandidateType | null;
+    /** Fraction (0..1) of OUR packets the remote side reports lost (`remote-inbound-rtp`), worst stream. */
+    outboundLoss: number | null;
+    /** Bits per second — the congestion controller's send estimate for the selected pair. */
+    availableOutgoingBitrate: number | null;
+}
+export interface PeerSignalSender {
+    send(type: 'offer' | 'answer' | 'ice', payload: unknown): Promise<string | null> | void;
+}
+export interface PeerConfig {
+    /**
+     * Perfect negotiation role: the polite peer yields on offer collisions (rolls back and answers),
+     * the impolite peer ignores the colliding offer.
+     */
+    polite: boolean;
+    /**
+     * When false, this peer does not send offers until it has completed one negotiation started by the
+     * other side — e.g. a guest who must wait for the host's offer. Default true.
+     */
+    initiator?: boolean;
+    iceServers?: RTCIceServer[];
+    signalling: PeerSignalSender;
+    onTrack?: (event: RTCTrackEvent) => void;
+    onConnectionState?: (state: RTCPeerConnectionState, ice: RTCIceConnectionState) => void;
+    onStats?: (stats: PeerStats) => void;
+    /** Restart ICE after this long in `disconnected` (immediately on `failed`). Default 3000 ms; 0 disables. */
+    restartAfterMs?: number;
+    /** Stats sampling interval. Default 3000 ms; 0 disables. */
+    statsIntervalMs?: number;
+    /** Test seam. */
+    createPeerConnection?: (config: RTCConfiguration) => RTCPeerConnection;
+}
+export interface Peer {
+    pc: RTCPeerConnection;
+    /** Feed a remote `offer` / `answer` / `ice` signal. Other types are ignored. */
+    handleSignal(type: string, payload: unknown): Promise<void>;
+    restartIce(): void;
+    close(): void;
+}
+/**
+ * RTCPeerConnection with the "perfect negotiation" pattern (W3C WebRTC spec §10.7): either side may add
+ * or remove tracks at any time, glare is resolved by the polite/impolite roles, ICE candidates trickle,
+ * and a dropped connection is restarted with `restartIce()`.
+ */
+export declare const createPeer: (config: PeerConfig) => Peer;

package/dist/peer.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPeer = void 0;
+/**
+ * RTCPeerConnection with the "perfect negotiation" pattern (W3C WebRTC spec §10.7): either side may add
+ * or remove tracks at any time, glare is resolved by the polite/impolite roles, ICE candidates trickle,
+ * and a dropped connection is restarted with `restartIce()`.
+ */
+const createPeer = (config) => {
+    const pc = (config.createPeerConnection ?? (c => new RTCPeerConnection(c)))({
+        iceServers: config.iceServers ?? [],
+    });
+    const restartAfterMs = config.restartAfterMs ?? 3000;
+    const statsIntervalMs = config.statsIntervalMs ?? 3000;
+    let makingOffer = false;
+    let ignoreOffer = false;
+    let settingRemoteAnswer = false;
+    let mayOffer = config.initiator ?? true;
+    let closed = false;
+    let restartTimer = null;
+    let statsTimer = null;
+    let lastInbound = { lost: 0, received: 0 };
+    const send = (type, payload) => {
+        void config.signalling.send(type, payload);
+    };
+    pc.onnegotiationneeded = async () => {
+        if (!mayOffer || closed)
+            return;
+        try {
+            makingOffer = true;
+            await pc.setLocalDescription();
+            send('offer', pc.localDescription?.toJSON?.() ?? pc.localDescription);
+        }
+        finally {
+            makingOffer = false;
+        }
+    };
+    pc.onicecandidate = ({ candidate }) => {
+        if (candidate)
+            send('ice', candidate.toJSON?.() ?? candidate);
+    };
+    pc.ontrack = event => config.onTrack?.(event);
+    const clearRestart = () => {
+        if (restartTimer)
+            clearTimeout(restartTimer);
+        restartTimer = null;
+    };
+    const report = () => config.onConnectionState?.(pc.connectionState, pc.iceConnectionState);
+    pc.onconnectionstatechange = report;
+    pc.oniceconnectionstatechange = () => {
+        report();
+        if (restartAfterMs <= 0 || closed)
+            return;
+        const state = pc.iceConnectionState;
+        if (state === 'failed') {
+            clearRestart();
+            pc.restartIce();
+        }
+        else if (state === 'disconnected') {
+            clearRestart();
+            restartTimer = setTimeout(() => {
+                if (pc.iceConnectionState === 'disconnected' || pc.iceConnectionState === 'failed')
+                    pc.restartIce();
+            }, restartAfterMs);
+        }
+        else {
+            clearRestart();
+        }
+    };
+    const handleDescription = async (description) => {
+        const readyForOffer = !makingOffer && (pc.signalingState === 'stable' || settingRemoteAnswer);
+        const offerCollision = description.type === 'offer' && !readyForOffer;
+        ignoreOffer = !config.polite && offerCollision;
+        if (ignoreOffer)
+            return;
+        settingRemoteAnswer = description.type === 'answer';
+        try {
+            await pc.setRemoteDescription(description); // rolls back a pending local offer when polite
+        }
+        finally {
+            settingRemoteAnswer = false;
+        }
+        if (description.type === 'offer') {
+            await pc.setLocalDescription();
+            send('answer', pc.localDescription?.toJSON?.() ?? pc.localDescription);
+        }
+        if (!mayOffer && pc.signalingState === 'stable') {
+            mayOffer = true;
+        }
+    };
+    const handleSignal = async (type, payload) => {
+        if (closed)
+            return;
+        if (type === 'offer' || type === 'answer') {
+            await handleDescription(payload);
+        }
+        else if (type === 'ice') {
+            try {
+                await pc.addIceCandidate(payload);
+            }
+            catch (err) {
+                if (!ignoreOffer)
+                    throw err;
+            }
+        }
+    };
+    const sampleStats = async () => {
+        if (closed || !config.onStats)
+            return;
+        const report = await pc.getStats();
+        let pair = null;
+        let transportPairId = null;
+        const byId = new Map();
+        let lost = 0;
+        let received = 0;
+        let outboundLoss = null;
+        report.forEach((entry) => {
+            if (entry.type === 'remote-inbound-rtp' && typeof entry.fractionLost === 'number') {
+                outboundLoss = Math.max(outboundLoss ?? 0, entry.fractionLost);
+            }
+            byId.set(entry.id, entry);
+            if (entry.type === 'transport' && entry.selectedCandidatePairId)
+                transportPairId = entry.selectedCandidatePairId;
+            if (entry.type === 'candidate-pair' && (entry.selected || (entry.nominated && entry.state === 'succeeded'))) {
+                pair = pair ?? entry;
+            }
+            if (entry.type === 'inbound-rtp') {
+                lost += entry.packetsLost ?? 0;
+                received += entry.packetsReceived ?? 0;
+            }
+        });
+        if (transportPairId && byId.has(transportPairId))
+            pair = byId.get(transportPairId);
+        const local = pair ? byId.get(pair.localCandidateId) : null;
+        const dLost = lost - lastInbound.lost;
+        const dReceived = received - lastInbound.received;
+        lastInbound = { lost, received };
+        config.onStats({
+            roundTripTime: pair?.currentRoundTripTime ?? null,
+            packetLoss: dLost + dReceived > 0 ? Math.max(0, dLost) / (dLost + dReceived) : null,
+            candidateType: local ? (local.candidateType ?? 'unknown') : null,
+            outboundLoss,
+            availableOutgoingBitrate: pair?.availableOutgoingBitrate ?? null,
+        });
+    };
+    if (statsIntervalMs > 0 && config.onStats) {
+        statsTimer = setInterval(() => void sampleStats().catch(() => undefined), statsIntervalMs);
+    }
+    return {
+        pc,
+        handleSignal,
+        restartIce: () => pc.restartIce(),
+        close() {
+            closed = true;
+            clearRestart();
+            if (statsTimer)
+                clearInterval(statsTimer);
+            pc.close();
+        },
+    };
+};
+exports.createPeer = createPeer;
+//# sourceMappingURL=peer.js.map

package/dist/peer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer.js","sourceRoot":"","sources":["../src/peer.ts"],"names":[],"mappings":"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"}

package/dist/sequencer.d.ts

@@ -0,0 +1,18 @@
+export interface Sequenced {
+    seq: number;
+}
+/**
+ * Exactly-once delivery of room signals arriving from several sources (subscribe replay, live push, poll).
+ *
+ * `seq` is monotonic per *room*, so one party's inbox has gaps (the other party's signals) — gaps are
+ * normal and cannot be detected from the stream. What can go wrong is a live frame overtaking the replay
+ * on (re)subscribe; `hold()` buffers everything until `release()`, which delivers the buffer sorted by seq.
+ * Outside a hold window items are delivered in arrival order, deduplicated by seq. `cursor()` is the
+ * highest seq delivered — the replay cursor for the next (re)subscribe or poll.
+ */
+export declare const createSequencer: <T extends Sequenced>(afterSeq: number, deliver: (item: T) => void) => {
+    push(item: T): void;
+    hold(): void;
+    release(): void;
+    cursor: () => number;
+};

package/dist/sequencer.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSequencer = void 0;
+const SEEN_LIMIT = 2000;
+/**
+ * Exactly-once delivery of room signals arriving from several sources (subscribe replay, live push, poll).
+ *
+ * `seq` is monotonic per *room*, so one party's inbox has gaps (the other party's signals) — gaps are
+ * normal and cannot be detected from the stream. What can go wrong is a live frame overtaking the replay
+ * on (re)subscribe; `hold()` buffers everything until `release()`, which delivers the buffer sorted by seq.
+ * Outside a hold window items are delivered in arrival order, deduplicated by seq. `cursor()` is the
+ * highest seq delivered — the replay cursor for the next (re)subscribe or poll.
+ */
+const createSequencer = (afterSeq, deliver) => {
+    let cursor = afterSeq;
+    let holding = false;
+    const held = [];
+    const seen = new Set();
+    const order = [];
+    const remember = (seq) => {
+        seen.add(seq);
+        order.push(seq);
+        if (order.length > SEEN_LIMIT)
+            seen.delete(order.shift());
+    };
+    const emit = (item) => {
+        if (seen.has(item.seq) || item.seq <= afterSeq)
+            return;
+        remember(item.seq);
+        cursor = Math.max(cursor, item.seq);
+        deliver(item);
+    };
+    return {
+        push(item) {
+            if (!Number.isInteger(item?.seq))
+                return;
+            if (holding)
+                held.push(item);
+            else
+                emit(item);
+        },
+        hold() {
+            holding = true;
+        },
+        release() {
+            holding = false;
+            held.splice(0).sort((a, b) => a.seq - b.seq).forEach(emit);
+        },
+        cursor: () => cursor,
+    };
+};
+exports.createSequencer = createSequencer;
+//# sourceMappingURL=sequencer.js.map

package/dist/sequencer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequencer.js","sourceRoot":"","sources":["../src/sequencer.ts"],"names":[],"mappings":";;;AAIA,MAAM,UAAU,GAAG,IAAI,CAAA;AAEvB;;;;;;;;GAQG;AACI,MAAM,eAAe,GAAG,CAAsB,QAAgB,EAAE,OAA0B,EAAE,EAAE;IACnG,IAAI,MAAM,GAAG,QAAQ,CAAA;IACrB,IAAI,OAAO,GAAG,KAAK,CAAA;IACnB,MAAM,IAAI,GAAQ,EAAE,CAAA;IACpB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,MAAM,KAAK,GAAa,EAAE,CAAA;IAE1B,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAE,EAAE;QAC/B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACb,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QACf,IAAI,KAAK,CAAC,MAAM,GAAG,UAAU;YAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAG,CAAC,CAAA;IAC5D,CAAC,CAAA;IAED,MAAM,IAAI,GAAG,CAAC,IAAO,EAAE,EAAE;QACvB,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,IAAI,QAAQ;YAAE,OAAM;QACtD,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QAClB,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;QACnC,OAAO,CAAC,IAAI,CAAC,CAAA;IACf,CAAC,CAAA;IAED,OAAO;QACL,IAAI,CAAC,IAAO;YACV,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC;gBAAE,OAAM;YACxC,IAAI,OAAO;gBAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;;gBACvB,IAAI,CAAC,IAAI,CAAC,CAAA;QACjB,CAAC;QACD,IAAI;YACF,OAAO,GAAG,IAAI,CAAA;QAChB,CAAC;QACD,OAAO;YACL,OAAO,GAAG,KAAK,CAAA;YACf,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;QAC5D,CAAC;QACD,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM;KACrB,CAAA;AACH,CAAC,CAAA;AAnCY,QAAA,eAAe,mBAmC3B"}

package/dist/signalling.d.ts

@@ -0,0 +1,46 @@
+import { buildClient } from '@pjts/websocket-client';
+/** Mirror of `@pjts/webrtc-signalling`'s `Signal` (kept local so the browser package has no server dependency). */
+export interface RoomSignal<P = unknown> {
+    seq: number;
+    roomId: string;
+    from: string;
+    to: string;
+    type: string;
+    payload: P;
+    at: string;
+}
+export type SignallingState = 'connecting' | 'open' | 'polling' | 'closed';
+export interface SignallingFallback {
+    /** Authoritative fetch of signals addressed to this party with `seq > afterSeq` (e.g. a REST endpoint). */
+    fetch(afterSeq: number): Promise<RoomSignal[]>;
+}
+export interface SignallingConfig {
+    /** WebSocket URL of the hub, e.g. `wss://api.example.com/api/v1/rtc/ws`. */
+    url: string;
+    roomId: string;
+    party: string;
+    /** Sent as the `bearer_<token>` subprotocol — never in the URL. */
+    token: string;
+    channelPrefix?: string;
+    /** Replay cursor — signals with `seq <= afterSeq` are never delivered. */
+    afterSeq?: number;
+    onSignal: (signal: RoomSignal) => void;
+    onState?: (state: SignallingState) => void;
+    fallback?: SignallingFallback;
+    /** How often connectivity is checked (and the fallback polled while the socket is down). Default 1000 ms. */
+    pollIntervalMs?: number;
+    /** Consecutive failed connectivity checks before polling starts. Default 2. */
+    pollAfterMisses?: number;
+    /** Test seam. */
+    clientFactory?: typeof buildClient;
+}
+export interface Signalling {
+    /** Subscribes (replaying after the cursor) — resolves once the replay is delivered. Rejects on nack. */
+    start(): Promise<void>;
+    /** Resolves `null` when the hub accepted the signal, otherwise the reason. */
+    send(type: string, payload?: unknown): Promise<string | null>;
+    cursor(): number;
+    state(): SignallingState;
+    close(): void;
+}
+export declare const createSignalling: (config: SignallingConfig) => Signalling;

package/dist/signalling.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSignalling = void 0;
+const websocket_client_1 = require("@pjts/websocket-client");
+const sequencer_1 = require("./sequencer");
+const createSignalling = (config) => {
+    const channel = `${config.channelPrefix ?? 'rtc'}.${config.roomId}.${config.party}`;
+    const pollIntervalMs = config.pollIntervalMs ?? 1000;
+    const pollAfterMisses = config.pollAfterMisses ?? 2;
+    const sequencer = (0, sequencer_1.createSequencer)(config.afterSeq ?? 0, config.onSignal);
+    const client = (config.clientFactory ?? websocket_client_1.buildClient)({ url: config.url, token: config.token });
+    let current = 'connecting';
+    let misses = 0;
+    let polling = false;
+    let timer = null;
+    const setState = (next) => {
+        if (next === current)
+            return;
+        current = next;
+        config.onState?.(next);
+    };
+    const poll = async () => {
+        if (!config.fallback || polling)
+            return;
+        polling = true;
+        try {
+            const signals = await config.fallback.fetch(sequencer.cursor());
+            signals.slice().sort((a, b) => a.seq - b.seq).forEach(s => sequencer.push(s));
+        }
+        catch {
+            // keep trying on the next tick
+        }
+        finally {
+            polling = false;
+        }
+    };
+    const tick = () => {
+        if (client.isConnected()) {
+            misses = 0;
+            setState('open');
+            return;
+        }
+        misses += 1;
+        if (misses >= pollAfterMisses && config.fallback) {
+            setState('polling');
+            void poll();
+        }
+        else if (current !== 'polling') {
+            setState('connecting');
+        }
+    };
+    return {
+        async start() {
+            timer = setInterval(tick, pollIntervalMs);
+            sequencer.hold();
+            try {
+                await client.subscribe(channel, frame => sequencer.push(frame), () => ({ afterSeq: sequencer.cursor() }));
+                setState('open');
+            }
+            catch (err) {
+                // A nack (unauthorized, replay failed) is final. A timeout means the socket is not reachable: the
+                // websocket client keeps the subscription and resubscribes on reconnect, and polling covers the gap.
+                const isTimeout = err instanceof Error && err.message.includes('timeout');
+                if (!isTimeout || !config.fallback) {
+                    if (timer)
+                        clearInterval(timer);
+                    timer = null;
+                    throw err;
+                }
+                setState('polling');
+                await poll();
+            }
+            finally {
+                sequencer.release();
+            }
+        },
+        send: (type, payload = null) => client.send(channel, { type, payload: payload }),
+        cursor: () => sequencer.cursor(),
+        state: () => current,
+        close() {
+            if (timer)
+                clearInterval(timer);
+            timer = null;
+            client.disconnect();
+            setState('closed');
+        },
+    };
+};
+exports.createSignalling = createSignalling;
+//# sourceMappingURL=signalling.js.map

package/dist/signalling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signalling.js","sourceRoot":"","sources":["../src/signalling.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@pjts/webrtc-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "description": "Piotr Józefów DDD utility package — browser WebRTC client: signalling, perfect negotiation, data channels, media utilities",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "author": "Piotr Józefów",
+  "license": "MIT",
+  "engines": {
+    "node": "^18.14.0"
+  },
+  "engineStrict": true,
+  "scripts": {
+    "lint": "eslint src/ --ext .js,.jsx,.ts,.tsx",
+    "test": "NODE_ENV=test jest --coverage=false --verbose",
+    "test:watch": "NODE_ENV=test jest --coverage=false --watchAll --testNamePattern=",
+    "build": "rm -rf ./dist && tsc",
+    "package": "npm run build && npm publish --access=public",
+    "prepare": "npm install @pjts/websocket-client@latest & npm install @pjts/core@latest @pjts/websocket-server@latest --save-dev & npm version patch"
+  },
+  "dependencies": {
+    "@pjts/websocket-client": "^0.0.59"
+  },
+  "devDependencies": {
+    "@pjts/core": "^0.0.90",
+    "@pjts/webrtc-signalling": "file:../webrtc-signalling",
+    "@pjts/websocket-server": "^0.0.60",
+    "@types/jest": "29.4.0",
+    "@types/node": "18.13.0",
+    "jest": "29.4.2",
+    "ts-jest": "29.0.5",
+    "typescript": "4.9.5"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  }
+}