@zero-server/sdk 0.9.9 → 1.0.0

package/lib/webrtc/sfu/memory.js

@@ -42,9 +42,14 @@ class MemorySfuAdapter extends SfuAdapter
         this._opts = opts || {};
         this._counter = 0;
         this._routers    = new Map(); // routerId    -> { id, opts, transports:Set, closed }
-        this._transports = new Map(); // transportId -> { id, routerId, peer, producers:Set, consumers:Set, closed }
+        this._transports = new Map(); // transportId -> { id, routerId, peer, producers:Set, consumers:Set, closed, bitrates }
         this._producers  = new Map(); // producerId  -> { id, transportId, kind, rtpParams, paused, closed }
-        this._consumers  = new Map(); // consumerId  -> { id, transportId, producerId, rtpCaps, closed }
+        this._consumers  = new Map(); // consumerId  -> { id, transportId, producerId, rtpCaps, closed, paused, priority, preferredLayers, keyFrameRequests }
+        this._dataProducers = new Map(); // dataProducerId -> { id, transportId, label, ordered, closed }
+        this._dataConsumers = new Map(); // dataConsumerId -> { id, transportId, dataProducerId, closed }
+        this._observers     = new Map(); // observerId -> { id, kind, routerId, closed }
+        this._pipes         = new Map(); // pipeId     -> { id, producerId, localRouterId, remoteRouterId, pipeProducerId, pipeConsumerId }
+        this._traceTypes    = new Map(); // routerId -> Set<string>
     }
 
     _nextId(prefix)
@@ -129,6 +134,10 @@ class MemorySfuAdapter extends SfuAdapter
             rtpParams:   prod.rtpParams,
             rtpCaps:     rtpCaps || {},
             closed:      false,
+            paused:      false,
+            priority:    1,
+            preferredLayers: null,
+            keyFrameRequests: 0,
         };
         this._consumers.set(id, c);
         t.consumers.add(id);
@@ -198,7 +207,13 @@ class MemorySfuAdapter extends SfuAdapter
         if (scope && this._routers.has(scope))
         {
             const r = this._routers.get(scope);
-            return { kind: 'router', routerId: scope, transports: r.transports.size };
+            const trace = this._traceTypes.get(scope);
+            return {
+                kind:       'router',
+                routerId:   scope,
+                transports: r.transports.size,
+                traceTypes: trace ? [...trace] : [],
+            };
         }
         if (scope && this._transports.has(scope))
         {
@@ -206,6 +221,7 @@ class MemorySfuAdapter extends SfuAdapter
             return {
                 kind: 'transport', transportId: scope, routerId: t.routerId,
                 producers: t.producers.size, consumers: t.consumers.size,
+                bitrates:  t.bitrates || null,
             };
         }
         return {
@@ -216,6 +232,303 @@ class MemorySfuAdapter extends SfuAdapter
             consumers:  this._consumers.size,
         };
     }
+
+    // -- Consumer-side BWE / quality knobs --
+
+    async setConsumerPreferredLayers(consumerId, layers)
+    {
+        const c = this._consumers.get(consumerId);
+        if (!c || c.closed)
+        {
+            throw new WebRTCError('setConsumerPreferredLayers: unknown consumer', { code: 'WEBRTC_SFU_NO_CONSUMER' });
+        }
+        if (!layers || typeof layers.spatialLayer !== 'number')
+        {
+            throw new WebRTCError('setConsumerPreferredLayers: layers.spatialLayer must be a number', { code: 'WEBRTC_SFU_INVALID_LAYERS' });
+        }
+        c.preferredLayers = {
+            spatialLayer:  layers.spatialLayer,
+            temporalLayer: typeof layers.temporalLayer === 'number' ? layers.temporalLayer : null,
+        };
+        this._emit('consumer-layers-change', { consumerId, layers: c.preferredLayers });
+    }
+
+    async setConsumerPriority(consumerId, priority)
+    {
+        const c = this._consumers.get(consumerId);
+        if (!c || c.closed)
+        {
+            throw new WebRTCError('setConsumerPriority: unknown consumer', { code: 'WEBRTC_SFU_NO_CONSUMER' });
+        }
+        const p = Number(priority);
+        if (!Number.isFinite(p) || p < 1 || p > 255)
+        {
+            throw new WebRTCError('setConsumerPriority: priority must be 1..255', { code: 'WEBRTC_SFU_INVALID_PRIORITY' });
+        }
+        c.priority = p;
+        this._emit('consumer-priority-change', { consumerId, priority: p });
+    }
+
+    async requestKeyFrame(consumerId)
+    {
+        const c = this._consumers.get(consumerId);
+        if (!c || c.closed)
+        {
+            throw new WebRTCError('requestKeyFrame: unknown consumer', { code: 'WEBRTC_SFU_NO_CONSUMER' });
+        }
+        c.keyFrameRequests += 1;
+        this._emit('consumer-keyframe', { consumerId, producerId: c.producerId, count: c.keyFrameRequests });
+    }
+
+    async pauseConsumer(consumerId)
+    {
+        const c = this._consumers.get(consumerId);
+        if (!c || c.closed)
+        {
+            throw new WebRTCError('pauseConsumer: unknown consumer', { code: 'WEBRTC_SFU_NO_CONSUMER' });
+        }
+        if (!c.paused)
+        {
+            c.paused = true;
+            this._emit('consumer-pause', { consumerId });
+        }
+    }
+
+    async resumeConsumer(consumerId)
+    {
+        const c = this._consumers.get(consumerId);
+        if (!c || c.closed)
+        {
+            throw new WebRTCError('resumeConsumer: unknown consumer', { code: 'WEBRTC_SFU_NO_CONSUMER' });
+        }
+        if (c.paused)
+        {
+            c.paused = false;
+            this._emit('consumer-resume', { consumerId });
+        }
+    }
+
+    // -- Transport bitrates --
+
+    async setTransportBitrates(transportId, opts)
+    {
+        const t = this._transports.get(transportId);
+        if (!t || t.closed)
+        {
+            throw new WebRTCError('setTransportBitrates: unknown transport', { code: 'WEBRTC_SFU_NO_TRANSPORT' });
+        }
+        t.bitrates = { ...(t.bitrates || {}), ...(opts || {}) };
+        this._emit('transport-bitrates', { transportId, bitrates: t.bitrates });
+    }
+
+    // -- Data channels --
+
+    async produceData(transport, opts)
+    {
+        const t = transport && this._transports.get(transport.id);
+        if (!t || t.closed)
+        {
+            throw new WebRTCError('produceData: unknown transport', { code: 'WEBRTC_SFU_NO_TRANSPORT' });
+        }
+        const id = this._nextId('dataProducer');
+        const dp = {
+            id,
+            dataProducerId: id,
+            transportId:    t.id,
+            label:          (opts && opts.label) || '',
+            protocol:       (opts && opts.protocol) || '',
+            ordered:        opts && opts.ordered !== undefined ? !!opts.ordered : true,
+            closed:         false,
+        };
+        this._dataProducers.set(id, dp);
+        this._emit('data-producer-new', { dataProducerId: id, transportId: t.id, label: dp.label });
+        return dp;
+    }
+
+    async consumeData(transport, dataProducerId, opts)
+    {
+        const t = transport && this._transports.get(transport.id);
+        if (!t || t.closed)
+        {
+            throw new WebRTCError('consumeData: unknown transport', { code: 'WEBRTC_SFU_NO_TRANSPORT' });
+        }
+        const dp = this._dataProducers.get(dataProducerId);
+        if (!dp || dp.closed)
+        {
+            throw new WebRTCError('consumeData: unknown data producer', { code: 'WEBRTC_SFU_NO_DATA_PRODUCER' });
+        }
+        const id = this._nextId('dataConsumer');
+        const dc = {
+            id,
+            dataConsumerId: id,
+            transportId:    t.id,
+            dataProducerId,
+            label:          dp.label,
+            protocol:       dp.protocol,
+            ordered:        opts && opts.ordered !== undefined ? !!opts.ordered : dp.ordered,
+            closed:         false,
+        };
+        this._dataConsumers.set(id, dc);
+        this._emit('data-consumer-new', { dataConsumerId: id, transportId: t.id, dataProducerId });
+        return dc;
+    }
+
+    // -- Observers --
+
+    async observeAudioLevels(routerId, opts)
+    {
+        const r = this._routers.get(routerId);
+        if (!r || r.closed)
+        {
+            throw new WebRTCError('observeAudioLevels: unknown router', { code: 'WEBRTC_SFU_NO_ROUTER' });
+        }
+        const id = this._nextId('audioObserver');
+        const handle = {
+            id,
+            kind:    'audio-level',
+            routerId,
+            opts:    opts || {},
+            closed:  false,
+            close: async () =>
+            {
+                if (handle.closed) return;
+                handle.closed = true;
+                this._observers.delete(id);
+                this._emit('observer-close', { observerId: id, kind: 'audio-level' });
+            },
+            // Test seam: feed synthetic samples through the adapter's event bus.
+            emit: (levels) =>
+            {
+                if (handle.closed) return;
+                this._emit('audio-level', { observerId: id, routerId, levels });
+            },
+        };
+        this._observers.set(id, handle);
+        this._emit('observer-new', { observerId: id, kind: 'audio-level', routerId });
+        return handle;
+    }
+
+    async observeActiveSpeaker(routerId, opts)
+    {
+        const r = this._routers.get(routerId);
+        if (!r || r.closed)
+        {
+            throw new WebRTCError('observeActiveSpeaker: unknown router', { code: 'WEBRTC_SFU_NO_ROUTER' });
+        }
+        const id = this._nextId('speakerObserver');
+        const handle = {
+            id,
+            kind:    'active-speaker',
+            routerId,
+            opts:    opts || {},
+            closed:  false,
+            close: async () =>
+            {
+                if (handle.closed) return;
+                handle.closed = true;
+                this._observers.delete(id);
+                this._emit('observer-close', { observerId: id, kind: 'active-speaker' });
+            },
+            // Test seam: announce a synthetic dominant speaker.
+            emit: (producerId) =>
+            {
+                if (handle.closed) return;
+                this._emit('active-speaker', { observerId: id, routerId, producerId });
+            },
+        };
+        this._observers.set(id, handle);
+        this._emit('observer-new', { observerId: id, kind: 'active-speaker', routerId });
+        return handle;
+    }
+
+    // -- Cascade --
+
+    async pipeToRouter(opts)
+    {
+        const o = opts || {};
+        const prod = o.producerId && this._producers.get(o.producerId);
+        if (!prod || prod.closed)
+        {
+            throw new WebRTCError('pipeToRouter: unknown producer', { code: 'WEBRTC_SFU_NO_PRODUCER' });
+        }
+        const local = o.localRouterId && this._routers.get(o.localRouterId);
+        if (!local)
+        {
+            throw new WebRTCError('pipeToRouter: unknown local router', { code: 'WEBRTC_SFU_NO_ROUTER' });
+        }
+        if (!o.remoteRouter || (!o.remoteRouter.id && !o.remoteRouter.routerId))
+        {
+            throw new WebRTCError('pipeToRouter: opts.remoteRouter is required', { code: 'WEBRTC_SFU_INVALID_PIPE' });
+        }
+        const remoteRouterId = o.remoteRouter.id || o.remoteRouter.routerId;
+        const id = this._nextId('pipe');
+        const pipeProducerId = this._nextId('pipeProducer');
+        const pipeConsumerId = this._nextId('pipeConsumer');
+        const handle = {
+            id,
+            pipeId:           id,
+            producerId:       o.producerId,
+            localRouterId:    o.localRouterId,
+            remoteRouterId,
+            pipeProducerId,
+            pipeConsumerId,
+        };
+        this._pipes.set(id, handle);
+        this._emit('pipe-open', handle);
+        return handle;
+    }
+
+    // -- Targeted stats --
+
+    async getProducerStats(producerId)
+    {
+        const p = this._producers.get(producerId);
+        if (!p)
+        {
+            throw new WebRTCError('getProducerStats: unknown producer', { code: 'WEBRTC_SFU_NO_PRODUCER' });
+        }
+        return [{ type: 'inbound-rtp', producerId, kind: p.kind, paused: p.paused, timestamp: Date.now() }];
+    }
+
+    async getConsumerStats(consumerId)
+    {
+        const c = this._consumers.get(consumerId);
+        if (!c)
+        {
+            throw new WebRTCError('getConsumerStats: unknown consumer', { code: 'WEBRTC_SFU_NO_CONSUMER' });
+        }
+        return [{
+            type: 'outbound-rtp', consumerId, producerId: c.producerId,
+            kind: c.kind, paused: c.paused, priority: c.priority,
+            preferredLayers: c.preferredLayers, timestamp: Date.now(),
+        }];
+    }
+
+    async getTransportStats(transportId)
+    {
+        const t = this._transports.get(transportId);
+        if (!t)
+        {
+            throw new WebRTCError('getTransportStats: unknown transport', { code: 'WEBRTC_SFU_NO_TRANSPORT' });
+        }
+        return [{
+            type: 'transport', transportId, routerId: t.routerId,
+            producers: t.producers.size, consumers: t.consumers.size,
+            bitrates: t.bitrates || null, timestamp: Date.now(),
+        }];
+    }
+
+    async enableTraceEvent(routerId, types)
+    {
+        const r = this._routers.get(routerId);
+        if (!r || r.closed)
+        {
+            throw new WebRTCError('enableTraceEvent: unknown router', { code: 'WEBRTC_SFU_NO_ROUTER' });
+        }
+        const set = new Set(Array.isArray(types) ? types : []);
+        this._traceTypes.set(routerId, set);
+        this._emit('trace-enabled', { routerId, types: [...set] });
+    }
 }
 
 module.exports = { MemorySfuAdapter };

package/lib/webrtc/signaling.js

@@ -5,6 +5,12 @@
  *   offer / answer / ICE traffic. Transport-agnostic — bind to `app.ws()`
  *   in production, an `EventEmitter` shim in tests.
  *
+ *   SDP validation is cross-browser by design: session-level
+ *   `a=fingerprint` / `a=ice-ufrag` / `a=ice-pwd` lines are accepted as a
+ *   fallback for media sections that omit their own copy (RFC 8839 §5.4,
+ *   RFC 8122 §5). This is required for Firefox interop — Firefox emits
+ *   `a=fingerprint` only at session level.
+ *
  * @example | Bind a hub to an `app.ws()` route with all production knobs
  *   const app = createApp();
  *   const hub = new SignalingHub({
@@ -44,6 +50,7 @@ const { parseCandidate } = require('./ice');
 const { Peer, PEER_STATE } = require('./peer');
 const { Room } = require('./room');
 const { verifyJoinToken } = require('./joinToken');
+const { loadSfuAdapter } = require('./sfu');
 
 // --- Constants ---
 
@@ -62,6 +69,17 @@ const DEFAULT_MAX_PROTOCOL_ERRORS = 5;
 /** Default rolling window (sec) for the per-IP attach rate limit. */
 const IP_ATTACH_WINDOW_SEC = 60;
 
+/** Allowed values for the room topology hint. */
+const VALID_TOPOLOGIES = new Set(['mesh', 'sfu', 'mcu', 'auto']);
+
+/**
+ * Default peer count at which an `auto` room is promoted from full mesh
+ * to SFU. Past this count an N-peer mesh costs O(N²) uplink and quickly
+ * saturates mobile radios; standard guidance (bloggeek.me, Jitsi, Daily)
+ * is to break the mesh between 4 and 6 participants.
+ */
+const DEFAULT_MAX_MESH_PEERS = 4;
+
 /** Set of message `type`s the hub will dispatch. */
 const VALID_TYPES = new Set([
     'join', 'leave', 'offer', 'answer', 'ice',
@@ -88,6 +106,11 @@ function _countCandidatesInSdp(sdp)
  * sections (RFC 8841 m=application ... UDP/DTLS/SCTP). When BUNDLE is in use
  * (every browser since ~2018), only the first m-section is required to carry
  * iceUfrag/icePwd; other bundled sections inherit them via a=group:BUNDLE.
+ *
+ * Session-level `a=fingerprint`, `a=ice-ufrag`, and `a=ice-pwd` lines are
+ * honoured: per RFC 8839 §5.4 and RFC 8122 §5 they apply to every media
+ * section that omits its own copy.  Firefox emits `a=fingerprint` only at
+ * session level, so this fallback is required for cross-browser interop.
  */
 function _validateSdpStructure(sdp)
 {
@@ -102,13 +125,22 @@ function _validateSdpStructure(sdp)
 
     // BUNDLE: collect bundled mids so per-section ice credentials are optional
     // on every section except the first (the BUNDLE owner).
+    // Also collect session-level fingerprint / ice-ufrag / ice-pwd, which per
+    // RFC 8839 §5.4 and RFC 8122 §5 apply to every media section that omits
+    // its own copy (Firefox emits fingerprint only at session level).
     const bundleMids = new Set();
+    let sessFingerprint = null, sessIceUfrag = null, sessIcePwd = null;
     for (const a of desc.attributes || [])
     {
-        if (a.key !== 'group') continue;
-        const parts = String(a.value || '').split(/\s+/);
-        if (parts[0] !== 'BUNDLE') continue;
-        for (let i = 1; i < parts.length; i++) bundleMids.add(parts[i]);
+        if (a.key === 'group')
+        {
+            const parts = String(a.value || '').split(/\s+/);
+            if (parts[0] === 'BUNDLE')
+                for (let i = 1; i < parts.length; i++) bundleMids.add(parts[i]);
+        }
+        else if (a.key === 'fingerprint' && a.value) sessFingerprint = a.value;
+        else if (a.key === 'ice-ufrag'   && a.value) sessIceUfrag   = a.value;
+        else if (a.key === 'ice-pwd'     && a.value) sessIcePwd     = a.value;
     }
 
     let firstBundleMid = null;
@@ -121,14 +153,18 @@ function _validateSdpStructure(sdp)
         const isSctp = /^(UDP|TCP)\/DTLS\/SCTP$/i.test(m.proto);
         if (!isRtp && !isSctp) return 'INVALID_SDP';
 
-        if (!m.fingerprint) return 'INVALID_SDP';
+        const fp    = m.fingerprint || sessFingerprint;
+        const ufrag = m.iceUfrag    || sessIceUfrag;
+        const pwd   = m.icePwd      || sessIcePwd;
+
+        if (!fp) return 'INVALID_SDP';
 
         // ice-ufrag / ice-pwd: required on the BUNDLE owner; optional on
         // every other bundled section (inherited per RFC 8843 §9.2).
         const bundled = m.mid && bundleMids.has(m.mid);
         if (bundled && firstBundleMid === null) firstBundleMid = m.mid;
         const isBundleOwner = !bundled || m.mid === firstBundleMid;
-        if (isBundleOwner && (!m.iceUfrag || !m.icePwd)) return 'INVALID_SDP';
+        if (isBundleOwner && (!ufrag || !pwd)) return 'INVALID_SDP';
     }
     return null;
 }
@@ -139,6 +175,10 @@ function _validateSdpStructure(sdp)
  * Central WebRTC signaling broker.  Owns rooms, attaches peers, validates
  * JSEP traffic, and emits `join` / `leave` / `error` lifecycle events.
  *
+ * Interop: SDP validation accepts session-level `a=fingerprint`,
+ * `a=ice-ufrag`, and `a=ice-pwd` as a fallback when a media section omits
+ * them (RFC 8839 §5.4 / RFC 8122 §5). Required for Firefox.
+ *
  * @class
  * @section Signaling
  *
@@ -168,6 +208,19 @@ class SignalingHub extends EventEmitter
      * @param {string|Buffer} [opts.joinTokenSecret]    - If set, every `join` must include a valid
      *                                                    JWT signed with this secret and audience `room:<name>`.
      * @param {boolean} [opts.autoCreateRooms=true]     - If false, joins targeting an unknown room are rejected.
+     * @param {'mesh'|'sfu'|'mcu'|'auto'} [opts.topology='auto'] - Default room topology. `auto` starts every room
+     *                                                    as full mesh and promotes to `sfu` once the peer count
+     *                                                    exceeds `maxMeshPeers`. Pure signaling is unchanged;
+     *                                                    the hint is broadcast to peers and surfaced via
+     *                                                    `hub.stats()` so clients can switch transports.
+     * @param {number} [opts.maxMeshPeers=4]            - Peer count at which an `auto` room is promoted from
+     *                                                    mesh to SFU (and at which a `mesh` room emits
+     *                                                    `peer:limit:reached` for capacity alarms).
+     * @param {SfuAdapter|string} [opts.sfu]            - Optional SFU adapter or spec string (memory|mediasoup|livekit|<pkg>).
+     *                                                    Mounts a `hub.media` facade backed by this adapter so
+     *                                                    application code can drive routers/transports/producers
+     *                                                    through the hub without importing the adapter directly.
+     * @param {object} [opts.sfuOpts]                   - Adapter constructor options, forwarded when `opts.sfu` is a string.
      */
     constructor(opts = {})
     {
@@ -199,6 +252,21 @@ class SignalingHub extends EventEmitter
         /** @type {boolean} */
         this.autoCreateRooms = opts.autoCreateRooms !== false;
 
+        /** @type {'mesh'|'sfu'|'mcu'|'auto'} */
+        if (opts.topology != null && !VALID_TOPOLOGIES.has(opts.topology))
+        {
+            throw new SignalingError(
+                `invalid topology "${opts.topology}" (expected mesh|sfu|mcu|auto)`,
+                { code: 'WEBRTC_INVALID_TOPOLOGY' },
+            );
+        }
+        this.defaultTopology = opts.topology || 'auto';
+
+        /** @type {number} */
+        this.maxMeshPeers = Number.isFinite(opts.maxMeshPeers) && opts.maxMeshPeers > 0
+            ? Math.floor(opts.maxMeshPeers)
+            : DEFAULT_MAX_MESH_PEERS;
+
         /** @type {Map<string, Room>} */
         this._rooms = new Map();
 
@@ -210,6 +278,23 @@ class SignalingHub extends EventEmitter
 
         /** @type {Map<string, number[]>} ip -> attach timestamps in the rolling window. */
         this._ipAttachLog = new Map();
+
+        // -- Optional media plane (SFU adapter facade) --
+        /** @type {import('./sfu').SfuAdapter|null} */
+        this.sfu = null;
+        if (opts.sfu)
+        {
+            this.sfu = (typeof opts.sfu === 'string' || (opts.sfu && typeof opts.sfu === 'object' && typeof opts.sfu.createRouter !== 'function'))
+                ? loadSfuAdapter(opts.sfu, opts.sfuOpts)
+                : loadSfuAdapter(opts.sfu);
+        }
+
+        /**
+         * Media-plane facade. Always present so application code can write
+         * `hub.media.createRouter(...)` regardless of whether an adapter is
+         * mounted; calls without an adapter throw `WEBRTC_SFU_NOT_CONFIGURED`.
+         */
+        this.media = _buildMediaFacade(this);
     }
 
     // -- Public surface --
@@ -230,6 +315,10 @@ class SignalingHub extends EventEmitter
         if (!r)
         {
             r = new Room(name, { hub: this });
+            // Apply the hub's default topology preference; `auto` rooms start
+            // as mesh and are promoted in _onRoomMembershipChange().
+            r.topologyMode = this.defaultTopology;
+            r.topology     = this.defaultTopology === 'auto' ? 'mesh' : this.defaultTopology;
             this._rooms.set(name, r);
         }
         return r;
@@ -458,7 +547,12 @@ class SignalingHub extends EventEmitter
         }
 
         room._add(peer);
-        peer.send('joined', { room: room.name, peerId: peer.id, peers: room.peers().map(p => p.id) });
+        peer.send('joined', {
+            room:     room.name,
+            peerId:   peer.id,
+            peers:    room.peers().map(p => p.id),
+            topology: room.topology,
+        });
         room.broadcast('peer-joined', { id: peer.id }, peer.id);
         this.emit('join', { peer, room });
     }
@@ -614,6 +708,114 @@ class SignalingHub extends EventEmitter
             peer.close(1008, 'too-many-errors');
         }
     }
+
+    // -- Topology / capacity --
+
+    /**
+     * Internal callback fired by `Room#_add` / `Room#_remove`.  Drives
+     * auto-promotion (`mesh` → `sfu`) and capacity alarms for fixed-mesh
+     * rooms.  Pure signaling: media transports do not move; the hub only
+     * advertises the new topology to peers so client SDKs can switch.
+     * @private
+     */
+    _onRoomMembershipChange(room, action, peer)
+    {
+        const size = room.size;
+        if (action === 'add' && size === this.maxMeshPeers + 1)
+        {
+            // Crossed the mesh limit.
+            this.emit('peer:limit:reached', { room, size, limit: this.maxMeshPeers });
+            if (room.topologyMode === 'auto' && room.topology === 'mesh')
+            {
+                room.setTopology('sfu');
+                this.emit('topology:promoted', { room, from: 'mesh', to: 'sfu', size });
+            }
+        }
+        else if (action === 'remove' && size === this.maxMeshPeers
+            && room.topologyMode === 'auto' && room.topology === 'sfu')
+        {
+            // Demote back to mesh if the room drops to / below the limit.
+            room.setTopology('mesh');
+            this.emit('topology:demoted', { room, from: 'sfu', to: 'mesh', size });
+        }
+    }
+
+    /**
+     * Snapshot of hub state for dashboards and health checks. Includes
+     * the configured topology defaults, current peer/room counts, and a
+     * coarse media-plane summary when an SFU adapter is mounted.
+     * @returns {Promise<{topology:string, maxMeshPeers:number, peers:number, rooms:object[], mediaPlane:object|null}>}
+     */
+    async stats()
+    {
+        const rooms = [];
+        for (const r of this._rooms.values())
+        {
+            rooms.push({
+                name:         r.name,
+                size:         r.size,
+                topology:     r.topology,
+                topologyMode: r.topologyMode,
+            });
+        }
+        let mediaPlane = null;
+        if (this.sfu)
+        {
+            try { mediaPlane = await this.sfu.stats(); }
+            catch (err) { mediaPlane = { error: err && err.message }; }
+        }
+        return {
+            topology:     this.defaultTopology,
+            maxMeshPeers: this.maxMeshPeers,
+            peers:        this._peers.size,
+            rooms,
+            mediaPlane,
+        };
+    }
+}
+
+// -- Media-plane facade --
+
+/**
+ * @private
+ * Build the `hub.media` proxy. Every adapter method on `SfuAdapter` is
+ * exposed; calls without a mounted adapter throw
+ * `WEBRTC_SFU_NOT_CONFIGURED` so misconfiguration is loud.
+ */
+function _buildMediaFacade(hub)
+{
+    const proxiedMethods = [
+        'createRouter', 'createTransport', 'produce', 'consume',
+        'pauseProducer', 'resumeProducer', 'closeRouter', 'stats',
+        'setConsumerPreferredLayers', 'setConsumerPriority', 'requestKeyFrame',
+        'pauseConsumer', 'resumeConsumer', 'setTransportBitrates',
+        'produceData', 'consumeData',
+        'observeAudioLevels', 'observeActiveSpeaker', 'pipeToRouter',
+        'getProducerStats', 'getConsumerStats', 'getTransportStats',
+        'enableTraceEvent',
+    ];
+    const facade = {
+        get adapter() { return hub.sfu; },
+        get configured() { return !!hub.sfu; },
+        onEvent(fn)
+        {
+            if (!hub.sfu)
+                throw new SignalingError('hub.media is not configured; pass `sfu` to SignalingHub or call useSfu()',
+                    { code: 'WEBRTC_SFU_NOT_CONFIGURED' });
+            return hub.sfu.onEvent(fn);
+        },
+    };
+    for (const name of proxiedMethods)
+    {
+        facade[name] = async (...args) =>
+        {
+            if (!hub.sfu)
+                throw new SignalingError('hub.media is not configured; pass `sfu` to SignalingHub or call useSfu()',
+                    { code: 'WEBRTC_SFU_NOT_CONFIGURED' });
+            return hub.sfu[name](...args);
+        };
+    }
+    return facade;
 }
 
 module.exports = { SignalingHub, Room, Peer, PEER_STATE };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zero-server/sdk",
-  "version": "0.9.9",
+  "version": "1.0.0",
   "description": "Zero-dependency backend framework for Node.js - routing, ORM, auth, WebSocket, SSE, gRPC, observability, and 20+ middleware. Distributed as a single SDK and as scoped @zero-server/* packages.",
   "main": "index.js",
   "bin": {