@blockcast/mmt-container 0.1.0 → 0.3.0-main.ef68de90edb3

package/dist/media-router.js

@@ -0,0 +1,584 @@
+// src/track-session.ts
+import { fecBlockBudgetMs } from "@blockcast/mmt-fec";
+function computeFecDeliveryWindowMs(config) {
+  const fecInterleaveMs = config.interleaveDepthMs;
+  const fecK = config.sourceSymbols;
+  if (!Number.isFinite(fecInterleaveMs) || fecInterleaveMs <= 0) {
+    throw new Error(
+      `[TrackSession] fecInterleaveMs=${fecInterleaveMs}. Derive a positive FEC interleave window from the stream catalog.`
+    );
+  }
+  if (!Number.isFinite(fecK) || fecK <= 0) {
+    throw new Error(
+      `[TrackSession] fecK=${fecK}. Derive a positive FEC source-symbol count from the stream catalog.`
+    );
+  }
+  if (config.jitterBufferMs === void 0) return Math.ceil(fecInterleaveMs);
+  return fecBlockBudgetMs(fecInterleaveMs, config.jitterBufferMs);
+}
+
+// src/media-router.ts
+var TrackSourceConflictError = class extends Error {
+  constructor(trackName) {
+    super(`Track source already assigned for '${trackName}'; call clearTrackSource first`);
+    this.trackName = trackName;
+    this.name = "TrackSourceConflictError";
+  }
+};
+var DEFAULT_CROSSFADE_FRAMES = 10;
+var DEFAULT_MAX_OVERLAY_BUFFER = 128;
+var MediaRouter = class {
+  #active = "moq";
+  #multicastVideoKeyed = false;
+  #multicastAudioReceived = false;
+  #moqVideoKeyframeEmitted = false;
+  #requireAudio;
+  #suppressed = false;
+  // true after multicast confirmed — suppresses MoQ
+  #audioFallbackTimer = null;
+  // Configurable constants (from catalog/FEC config, not magic numbers)
+  #audioFallbackMs;
+  #crossfadeFrames;
+  #maxOverlayBuffer;
+  #allowDeltaMulticastTakeoverAfterMoqKeyframe;
+  // ── Keyframe repair state ────────────────────────────────────────
+  /** Groups currently being repaired — idempotent guard per Pitfall 2 (T-13-01 mitigation) */
+  #repairInFlight = /* @__PURE__ */ new Set();
+  /** Max concurrent repairs — prevents relay SUBSCRIBE flood (T-13-01 mitigation). A reader is evaluated per decision. */
+  #maxRepairInFlight;
+  /** Callback to request MoQ subscribe for a specific group (wired by player) */
+  #onRepairRequest = null;
+  #onVideoFrame = null;
+  #onAudioFrame = null;
+  #onOverlayFrame = null;
+  #onSourceSwitch = null;
+  #sourceSwitchReady = null;
+  #sourceSwitchToken = 0;
+  #pendingMulticastToken = null;
+  #pendingMulticastVideo = null;
+  #pendingMulticastAudio = null;
+  // Per-track source state
+  #trackSources = /* @__PURE__ */ new Map();
+  // Track type registry: trackName → { type, source }.
+  // Init data / inline signaling is authoritative until catalog updates.
+  // Priority: 'init' > 'catalog' > 'name' (backward compat fallback).
+  #trackTypes = /* @__PURE__ */ new Map();
+  // Crossfade state: maps trackName → remaining binary-path frames allowed during window
+  #crossfadeCounters = /* @__PURE__ */ new Map();
+  // Overlay alignment state
+  #overlayBoundaryReached = false;
+  #overlayBuffer = [];
+  // ── Phase 14: deltaActive state machine (D-11..D-14) ─────────────
+  // No timers — state transitions driven entirely by notifyDeltaBlock() callbacks.
+  // All thresholds derived from catalog fields or throw at configureDelta() time.
+  #deltaConfigured = false;
+  #deltaActive = true;
+  #deltaWindow = [];
+  // ring buffer: true = block failed
+  #deltaWindowSize = 0;
+  #deltaFailThresholdRatio = 0;
+  // P/K
+  #deltaRecoverThresholdRatio = 0;
+  // (P/K)/2 — hysteresis (D-13)
+  #deltaProbeIntervalMs = 0;
+  #lastProbeAt = 0;
+  #onDeltaFallbackCb = null;
+  #onDeltaRecoverCb = null;
+  constructor(options) {
+    this.#requireAudio = options?.requireAudio ?? true;
+    this.#audioFallbackMs = options?.audioFallbackMs ?? 0;
+    this.#crossfadeFrames = options?.crossfadeFrames ?? DEFAULT_CROSSFADE_FRAMES;
+    this.#maxOverlayBuffer = options?.maxOverlayBuffer ?? DEFAULT_MAX_OVERLAY_BUFFER;
+    const maxRepairInFlight = options?.maxRepairInFlight;
+    if (maxRepairInFlight !== void 0 && typeof maxRepairInFlight !== "function" && (!Number.isSafeInteger(maxRepairInFlight) || maxRepairInFlight < 1)) {
+      throw new Error(
+        `[MediaRouter] maxRepairInFlight=${maxRepairInFlight} must be a positive integer`
+      );
+    }
+    this.#maxRepairInFlight = maxRepairInFlight ?? null;
+    this.#allowDeltaMulticastTakeoverAfterMoqKeyframe = options?.allowDeltaMulticastTakeoverAfterMoqKeyframe ?? false;
+  }
+  onVideoFrame(cb) {
+    this.#onVideoFrame = cb;
+  }
+  onAudioFrame(cb) {
+    this.#onAudioFrame = cb;
+  }
+  onOverlayFrame(cb) {
+    this.#onOverlayFrame = cb;
+  }
+  onSourceSwitch(cb) {
+    this.#onSourceSwitch = cb;
+  }
+  get activeSource() {
+    return this.#active;
+  }
+  // ── Keyframe repair API ──────────────────────────────────────────
+  /** Register callback for keyframe repair requests. Player wires this to issue MoQ SUBSCRIBE. */
+  onRepairRequest(cb) {
+    if (this.#maxRepairInFlight === null) {
+      throw new Error(
+        "[MediaRouter] onRepairRequest requires an explicit maxRepairInFlight option"
+      );
+    }
+    this.#onRepairRequest = cb;
+  }
+  /**
+   * Request repair for a lost keyframe group. Only fires when activeSource is 'multicast'.
+   * Idempotent per groupId — duplicate calls for the same group are suppressed.
+   * A reader `maxRepairInFlight` is evaluated here; without a valid value the
+   * group is skipped and a later call reads it again.
+   * @param expectedGroupId - The group ID expected but not received
+   * @param trackName - Track name for the SUBSCRIBE (e.g. 'video'). Default: 'video'.
+   */
+  repairLostGroup(expectedGroupId, trackName = "video") {
+    if (this.#active !== "multicast") return;
+    if (this.#maxRepairInFlight === null) return;
+    if (this.#repairInFlight.has(expectedGroupId)) return;
+    let maxRepairInFlight;
+    try {
+      maxRepairInFlight = typeof this.#maxRepairInFlight === "function" ? this.#maxRepairInFlight() : this.#maxRepairInFlight;
+    } catch (error) {
+      console.warn(
+        `[MediaRouter] maxRepairInFlight unmeasured, skipping repair for group ${expectedGroupId}:`,
+        error
+      );
+      return;
+    }
+    if (!Number.isSafeInteger(maxRepairInFlight) || maxRepairInFlight < 1) {
+      console.warn(
+        `[MediaRouter] maxRepairInFlight=${maxRepairInFlight} is not a positive integer, skipping repair for group ${expectedGroupId}`
+      );
+      return;
+    }
+    if (this.#repairInFlight.size >= maxRepairInFlight) {
+      console.warn(
+        `[MediaRouter] max repair in flight (${maxRepairInFlight}), dropping repair for group ${expectedGroupId}`
+      );
+      return;
+    }
+    this.#repairInFlight.add(expectedGroupId);
+    this.#onRepairRequest?.(expectedGroupId, trackName);
+  }
+  /**
+   * Feed a recovered keyframe frame from the repair path.
+   * Bypasses source arbitration entirely — goes directly to decoder callbacks.
+   * Does NOT change activeSource. Does NOT trigger failbackToMoq.
+   */
+  feedRepair(data, meta, kind) {
+    if (this.#active !== "multicast") return;
+    const routedMeta = { ...meta, source: "repair", recovered: true };
+    if (kind === "video") this.#onVideoFrame?.(data, routedMeta);
+    else this.#onAudioFrame?.(data, routedMeta);
+  }
+  /**
+   * Clear repair-in-flight state for a group (called after repair completes or times out).
+   */
+  clearRepairInFlight(groupId) {
+    this.#repairInFlight.delete(groupId);
+  }
+  // ── Phase 14: deltaActive state machine API ──────────────────────
+  /**
+   * Configure the delta-track fallback state machine from catalog parameters.
+   *
+   * D-11: Thresholds derive from fec.sourceSymbols, fec.repairSymbols, framerate.
+   * D-13: Probe interval derives from deltaProbeIntervalMs or interleaveDepthMs*2.
+   * CLAUDE.md: error on bad init — throws if required inputs are absent.
+   *
+   * Calling again resets deltaActive=true and clears the window buffer (stream restart).
+   */
+  configureDelta(cfg) {
+    if (typeof cfg.framerate !== "number" || !Number.isFinite(cfg.framerate) || cfg.framerate <= 0) {
+      throw new Error("[MediaRouter] configureDelta: framerate required and must be > 0");
+    }
+    if (typeof cfg.sourceSymbols !== "number" || cfg.sourceSymbols <= 0) {
+      throw new Error("[MediaRouter] configureDelta: sourceSymbols (K_delta) required and must be > 0");
+    }
+    if (typeof cfg.repairSymbols !== "number" || cfg.repairSymbols <= 0) {
+      throw new Error("[MediaRouter] configureDelta: repairSymbols (P_delta) required and must be > 0");
+    }
+    if (cfg.deltaProbeIntervalMs === void 0 && cfg.interleaveDepthMs === void 0) {
+      throw new Error(
+        "[MediaRouter] configureDelta: either deltaProbeIntervalMs or interleaveDepthMs required for probe interval derivation"
+      );
+    }
+    this.#deltaWindowSize = cfg.deltaFailWindowBlocks ?? Math.ceil(cfg.framerate);
+    this.#deltaFailThresholdRatio = cfg.repairSymbols / cfg.sourceSymbols;
+    this.#deltaRecoverThresholdRatio = this.#deltaFailThresholdRatio / 2;
+    this.#deltaProbeIntervalMs = cfg.deltaProbeIntervalMs ?? computeFecDeliveryWindowMs({
+      interleaveDepthMs: cfg.interleaveDepthMs,
+      sourceSymbols: cfg.sourceSymbols
+    });
+    this.#deltaActive = true;
+    this.#deltaWindow = [];
+    this.#lastProbeAt = 0;
+    this.#deltaConfigured = true;
+  }
+  /**
+   * Notify the state machine of a completed FEC block for the delta track.
+   *
+   * @param failed - true if the block was unrecoverable (FEC failure)
+   * @param nowMs  - caller-injected monotonic ms (no internal timer — D-13, CLAUDE.md)
+   *
+   * If configureDelta() has not been called, this is a silent no-op (pre-catalog state).
+   */
+  notifyDeltaBlock(failed, nowMs) {
+    if (!this.#deltaConfigured) return;
+    this.#deltaWindow.push(failed);
+    if (this.#deltaWindow.length > this.#deltaWindowSize) {
+      this.#deltaWindow.shift();
+    }
+    if (this.#deltaWindow.length < this.#deltaWindowSize) return;
+    const failedCount = this.#deltaWindow.filter((x) => x).length;
+    const ratio = failedCount / this.#deltaWindowSize;
+    if (this.#deltaActive) {
+      if (ratio > this.#deltaFailThresholdRatio) {
+        this.#deltaActive = false;
+        this.#lastProbeAt = nowMs;
+        this.#onDeltaFallbackCb?.();
+      }
+    } else {
+      if (nowMs - this.#lastProbeAt >= this.#deltaProbeIntervalMs && ratio < this.#deltaRecoverThresholdRatio) {
+        this.#deltaActive = true;
+        this.#lastProbeAt = nowMs;
+        this.#onDeltaRecoverCb?.();
+      }
+    }
+  }
+  /** Register callback fired when delta track degrades past threshold (D-12). */
+  onDeltaFallback(cb) {
+    this.#onDeltaFallbackCb = cb;
+  }
+  /** Register callback fired when delta track recovers below recovery threshold (D-13). */
+  onDeltaRecover(cb) {
+    this.#onDeltaRecoverCb = cb;
+  }
+  /** Whether the delta track is currently considered healthy (true = active). */
+  get deltaActive() {
+    return this.#deltaActive;
+  }
+  // ── Test-visible accessors for threshold verification ────────────
+  // These expose internal derived values for test assertions (Tests 3,4,5,6,7).
+  // Prefixed with 'delta' to namespace clearly within the public API surface.
+  /** Derived window size — exposed for test assertions (Test 3, 4). */
+  get deltaWindowSize() {
+    return this.#deltaWindowSize;
+  }
+  /** Derived fail threshold ratio (P/K) — exposed for test assertions (Test 6). */
+  get deltaFailThresholdRatio() {
+    return this.#deltaFailThresholdRatio;
+  }
+  /** Derived recovery threshold ratio ((P/K)/2) — exposed for test assertions (Test 7). */
+  get deltaRecoverThresholdRatio() {
+    return this.#deltaRecoverThresholdRatio;
+  }
+  /** Derived probe interval ms — exposed for test assertions (Test 5a). */
+  get deltaProbeIntervalMs() {
+    return this.#deltaProbeIntervalMs;
+  }
+  /**
+   * Register a track name → type mapping from catalog.
+   * Catalog is the default authority. Init data / inline signaling
+   * takes precedence until the next catalog update.
+   */
+  registerTrackType(trackName, type) {
+    this.#trackTypes.set(trackName, { type, source: "catalog" });
+  }
+  /**
+   * Register a track name → type from init data / inline signaling (MMTP FT=0).
+   * Authoritative until the next catalog update per §5.3.
+   * Does NOT overwrite an existing catalog registration.
+   */
+  registerTrackTypeFromInit(trackName, type) {
+    const existing = this.#trackTypes.get(trackName);
+    if (existing?.source === "catalog") return;
+    this.#trackTypes.set(trackName, { type, source: "init" });
+  }
+  /**
+   * Assign a per-track source. Frames from this source bypass the binary
+   * MoQ↔multicast switching for this track only.
+   *
+   * Throws TrackSourceConflictError if a source is already assigned for this
+   * track without a clearTrackSource() in between.
+   */
+  setTrackSource(trackName, source, opts) {
+    if (this.#trackSources.has(trackName)) {
+      throw new TrackSourceConflictError(trackName);
+    }
+    const effectivePolicy = opts?.policy ?? (opts?.overlay ? "wait" : void 0);
+    if (effectivePolicy === "crossfade") {
+      this.#crossfadeCounters.set(trackName, this.#crossfadeFrames);
+    }
+    const record = {
+      source,
+      unsubscribeFrame: () => {
+      },
+      emitCount: 0
+    };
+    record.unsubscribeFrame = source.onFrame((data, meta) => {
+      record.emitCount++;
+      if (effectivePolicy === "wait") {
+        this.#handleOverlayFrame(data, meta);
+      } else {
+        this.#emitForTrack(trackName, data, meta);
+      }
+    });
+    if (source.onError) {
+      record.unsubscribeError = source.onError(() => {
+        this.clearTrackSource(trackName);
+      });
+    }
+    this.#trackSources.set(trackName, record);
+  }
+  /**
+   * Remove the per-track source for the given track.
+   * Binary switching resumes for this track after this call.
+   */
+  clearTrackSource(trackName) {
+    const record = this.#trackSources.get(trackName);
+    if (!record) return;
+    record.unsubscribeFrame();
+    record.unsubscribeError?.();
+    record.source.dispose?.();
+    this.#trackSources.delete(trackName);
+    this.#crossfadeCounters.delete(trackName);
+    const reg = this.#trackTypes.get(trackName);
+    const isMedia = reg?.type === "video" || reg?.type === "audio" || reg === void 0 && (trackName === "video" || trackName === "audio");
+    if (!isMedia) {
+      this.#overlayBoundaryReached = false;
+      this.#overlayBuffer = [];
+    }
+  }
+  /**
+   * Signal that a FEC block boundary has been reached on the base track.
+   * Overlay tracks waiting for alignment flush their buffered frames now.
+   */
+  notifyFecBlockBoundary() {
+    if (this.#overlayBoundaryReached) return;
+    this.#overlayBoundaryReached = true;
+    const buffered = this.#overlayBuffer.splice(0);
+    for (const { data, meta } of buffered) {
+      this.#onOverlayFrame?.(data, meta);
+    }
+  }
+  /**
+   * Return the number of frames emitted from the per-track source for a given
+   * track. Used in test-mode to verify per-track routing histogram.
+   * Returns 0 if no per-track source is active for the track.
+   */
+  trackSourceEmitCount(trackName) {
+    return this.#trackSources.get(trackName)?.emitCount ?? 0;
+  }
+  /** Feed a frame from the MoQ path. Suppressed when multicast is active OR a per-track source owns this track. */
+  feedMoq(data, meta, kind) {
+    if (this.#trackSources.has(kind)) {
+      const remaining = this.#crossfadeCounters.get(kind);
+      if (remaining && remaining > 0) {
+        const next = remaining - 1;
+        if (next === 0) {
+          this.#crossfadeCounters.delete(kind);
+        } else {
+          this.#crossfadeCounters.set(kind, next);
+        }
+      } else {
+        return;
+      }
+    }
+    if (this.#suppressed) return;
+    const routedMeta = { ...meta, source: "moq" };
+    if (kind === "video") this.#onVideoFrame?.(data, routedMeta);
+    else this.#onAudioFrame?.(data, routedMeta);
+  }
+  /** Feed a frame from the multicast path. Video waits for keyframe before activating. */
+  feedMulticast(data, meta, kind) {
+    if (this.#trackSources.has(kind)) {
+      const remaining = this.#crossfadeCounters.get(kind);
+      if (remaining && remaining > 0) {
+        const next = remaining - 1;
+        if (next === 0) {
+          this.#crossfadeCounters.delete(kind);
+        } else {
+          this.#crossfadeCounters.set(kind, next);
+        }
+      } else {
+        return;
+      }
+    }
+    if (kind === "video") {
+      if (!this.#multicastVideoKeyed) {
+        const moqSeededDelta = !meta.keyframe && this.#allowDeltaMulticastTakeoverAfterMoqKeyframe && this.#moqVideoKeyframeEmitted;
+        if (!meta.keyframe && !moqSeededDelta) return;
+        this.#multicastVideoKeyed = true;
+        const pendingMeta = { ...meta, source: "multicast" };
+        if (!moqSeededDelta) pendingMeta.sourceDiscontinuity = true;
+        this.#pendingMulticastVideo = {
+          data: data.slice(),
+          meta: pendingMeta
+        };
+        if (this.#requireAudio && this.#audioFallbackMs > 0 && !this.#multicastAudioReceived && !this.#audioFallbackTimer) {
+          this.#audioFallbackTimer = setTimeout(() => {
+            if (!this.#multicastAudioReceived && this.#active !== "multicast") {
+              this.#multicastAudioReceived = true;
+              this.#moqAudioWarmed = true;
+              this.#tryActivateMulticast();
+            }
+          }, this.#audioFallbackMs);
+        }
+      } else if (this.#active !== "multicast") {
+        if (meta.keyframe) {
+          this.#pendingMulticastVideo = {
+            data: data.slice(),
+            meta: { ...meta, source: "multicast", sourceDiscontinuity: true }
+          };
+        }
+        this.#tryActivateMulticast();
+        return;
+      }
+      if (this.#active === "multicast") this.#onVideoFrame?.(data, { ...meta, source: "multicast" });
+      this.#tryActivateMulticast();
+    } else {
+      this.#multicastAudioReceived = true;
+      if (this.#audioFallbackTimer) {
+        clearTimeout(this.#audioFallbackTimer);
+        this.#audioFallbackTimer = null;
+      }
+      if (!this.#moqAudioWarmed) this.#moqAudioWarmed = true;
+      this.#tryActivateMulticast();
+      if (this.#active === "multicast") {
+        this.#onAudioFrame?.(data, { ...meta, source: "multicast" });
+      } else if (this.#pendingMulticastToken !== null) {
+        this.#pendingMulticastAudio = { data: data.slice(), meta: { ...meta, source: "multicast" } };
+      }
+    }
+  }
+  /**
+   * MoQ unicast audio warmup gate. When audio is required, multicast takeover
+   * waits until the MoQ unicast audio decoder has emitted at least one frame
+   * (so downstream samples-before-takeover counters observe nonzero) or until
+   * the existing audio-fallback timer forces the flag true.
+   */
+  #moqAudioWarmed = false;
+  /** Called by the player when the MoQ unicast audio decoder emits first frame. */
+  notifyMoqAudioEmit() {
+    if (this.#moqAudioWarmed) return;
+    this.#moqAudioWarmed = true;
+    this.#tryActivateMulticast();
+  }
+  /**
+   * Called by the player after a MoQ video keyframe has reached the active
+   * decoder path. Used only by MSE/MMTP continuity switching; decoder-reset
+   * paths leave allowDeltaMulticastTakeoverAfterMoqKeyframe disabled.
+   */
+  notifyMoqVideoKeyframeEmit() {
+    this.#moqVideoKeyframeEmitted = true;
+    this.#tryActivateMulticast();
+  }
+  #tryActivateMulticast() {
+    if (this.#active === "multicast") return;
+    if (this.#pendingMulticastToken !== null) return;
+    if (!this.#multicastVideoKeyed) return;
+    if (this.#requireAudio && !this.#multicastAudioReceived) return;
+    if (this.#requireAudio && !this.#moqAudioWarmed) return;
+    const token = ++this.#sourceSwitchToken;
+    const maybeReady = this.#onSourceSwitch?.("multicast");
+    if (!maybeReady || typeof maybeReady.then !== "function") {
+      this.#commitMulticastActivation(token);
+      return;
+    }
+    const ready = Promise.resolve(maybeReady);
+    this.#pendingMulticastToken = token;
+    this.#sourceSwitchReady = ready;
+    void ready.then(
+      () => this.#commitMulticastActivation(token),
+      (err) => this.#rejectMulticastActivation(token, err)
+    ).finally(() => {
+      if (this.#sourceSwitchReady === ready) this.#sourceSwitchReady = null;
+    });
+  }
+  #commitMulticastActivation(token) {
+    if (token !== this.#sourceSwitchToken) return;
+    this.#active = "multicast";
+    this.#suppressed = true;
+    this.#pendingMulticastToken = null;
+    const video = this.#pendingMulticastVideo;
+    this.#pendingMulticastVideo = null;
+    const audio = this.#pendingMulticastAudio;
+    this.#pendingMulticastAudio = null;
+    if (video) this.#onVideoFrame?.(video.data, video.meta);
+    if (audio) this.#onAudioFrame?.(audio.data, audio.meta);
+  }
+  #rejectMulticastActivation(token, err) {
+    if (token !== this.#sourceSwitchToken) return;
+    if (this.#pendingMulticastToken === token) this.#pendingMulticastToken = null;
+    this.#pendingMulticastVideo = null;
+    this.#pendingMulticastAudio = null;
+    console.warn("[MediaRouter] onSourceSwitch(multicast) failed", err);
+  }
+  /** Switch back to MoQ immediately (called on multicast failback). */
+  failbackToMoq() {
+    const hadPendingMulticast = this.#pendingMulticastToken !== null;
+    if (this.#active === "moq" && !hadPendingMulticast) return;
+    ++this.#sourceSwitchToken;
+    this.#active = "moq";
+    this.#suppressed = false;
+    this.#pendingMulticastToken = null;
+    this.#pendingMulticastVideo = null;
+    this.#pendingMulticastAudio = null;
+    this.#sourceSwitchReady = null;
+    this.#multicastVideoKeyed = false;
+    this.#multicastAudioReceived = false;
+    this.#moqVideoKeyframeEmitted = false;
+    if (this.#audioFallbackTimer) {
+      clearTimeout(this.#audioFallbackTimer);
+      this.#audioFallbackTimer = null;
+    }
+    this.#onSourceSwitch?.("moq");
+  }
+  /** Dispose timers and per-track sources. Call on teardown to prevent
+   *  stale timer callbacks firing into garbage-collected closures (WR-03). */
+  dispose() {
+    if (this.#audioFallbackTimer) {
+      clearTimeout(this.#audioFallbackTimer);
+      this.#audioFallbackTimer = null;
+    }
+    for (const [name] of this.#trackSources) {
+      this.clearTrackSource(name);
+    }
+  }
+  // ── Private helpers ──────────────────────────────────────────────────────
+  /** Emit a frame on the correct per-track callback using the type registry.
+   *  Falls back to name match if no type registered (backward compat). */
+  #emitForTrack(trackName, data, meta) {
+    const reg = this.#trackTypes.get(trackName);
+    if (reg?.type === "video") {
+      this.#onVideoFrame?.(data, meta);
+    } else if (reg?.type === "audio") {
+      this.#onAudioFrame?.(data, meta);
+    } else if (reg !== void 0) {
+      this.#onOverlayFrame?.(data, meta);
+    } else {
+      if (trackName === "video") this.#onVideoFrame?.(data, meta);
+      else if (trackName === "audio") this.#onAudioFrame?.(data, meta);
+      else this.#onOverlayFrame?.(data, meta);
+    }
+  }
+  /** Handle an overlay frame: buffer until first FEC block boundary, then pass through. */
+  #handleOverlayFrame(data, meta) {
+    if (this.#overlayBoundaryReached) {
+      this.#onOverlayFrame?.(data, meta);
+      return;
+    }
+    if (this.#overlayBuffer.length >= this.#maxOverlayBuffer) {
+      console.warn(
+        `[MediaRouter] overlay buffer full (${this.#maxOverlayBuffer} frames); dropping frame ts=${meta.timestamp}`
+      );
+      return;
+    }
+    this.#overlayBuffer.push({ data, meta });
+  }
+};
+export {
+  MediaRouter,
+  TrackSourceConflictError
+};
+//# sourceMappingURL=media-router.js.map