@blockcast/mmt-container 0.1.0 → 0.3.0-main.0bde85f7082f

package/src/media-router.ts

@@ -0,0 +1,841 @@
+/**
+ * MediaRouter — source arbitration for MoQ ↔ multicast switching.
+ *
+ * Both moq-lib and moqtail wire their MoQ and multicast frame outputs
+ * through this router. The router decides which source reaches the decoder:
+ *
+ *   - MoQ frames pass through while multicast is inactive.
+ *   - Multicast video frames are suppressed until the first keyframe.
+ *   - Once multicast has both a video keyframe and audio, takeover is requested.
+ *   - MoQ is suppressed only after the source-switch callback completes.
+ *   - failbackToMoq() reverses the switch immediately.
+ *
+ * Per-track setTrackSource() allows individual tracks to be wired to a
+ * specific transport source (video=multicast, audio=moq, overlay=amt) without
+ * changing the binary MoQ↔multicast switching for other tracks.
+ */
+
+import { computeFecDeliveryWindowMs } from './track-session.js'
+
+export type FrameMeta = {
+  timestamp: number
+  keyframe: boolean
+  packetId?: number
+  packetSequenceNumber?: number
+  source?: 'moq' | 'multicast' | 'repair'
+  recovered?: boolean
+  sourceDiscontinuity?: boolean
+  /**
+   * Raw MMTP header timestamp (RFC 5905 short NTP, 32 bits): the publisher's
+   * send-wall clock for the packet that carried this frame. On timed media it
+   * is distinct from `timestamp`, the authored media presentation time. On a
+   * non-timed MFU there is no authored presentation time, so `MmtpRouter`
+   * derives `timestamp` from this same clock and the two carry no latency
+   * between them. Populated from `RoutedFrameMeta.mmtpTimestamp` and
+   * preserved by every re-emit on this router (multicast, MoQ, and repair) so
+   * players can measure network ingress on the multicast legs; absent when
+   * the packet header could not be read.
+   */
+  mmtpTimestamp?: bigint
+}
+export type FrameKind = 'video' | 'audio'
+export type SourceKind = 'moq' | 'multicast'
+
+type FrameCb = (data: Uint8Array, meta: FrameMeta) => void
+type SwitchCb = (source: SourceKind) => void | Promise<void>
+
+export interface MediaRouterOptions {
+  /** Set false for video-only streams. Default: true. */
+  requireAudio?: boolean
+  /**
+   * Audio fallback timeout (ms): force multicast activation if video keyframe
+   * arrived but audio hasn't within this window. Catalog-derived via
+   * computeFecDeliveryWindowMs (the single FEC recovery-window source of truth).
+   * Omit to disable the independent audio-fallback timer (no magic default).
+   */
+  audioFallbackMs?: number
+  /**
+   * Number of binary-path frames to allow through during a crossfade transition.
+   * Derive from FEC block size (e.g., ceil(K / groupsPerBlock)). Default: 10.
+   */
+  crossfadeFrames?: number
+  /**
+   * Max pre-boundary overlay frames to buffer before dropping.
+   * Derive from FEC config (e.g., ceil(K * 1.5)). Default: 128.
+   */
+  maxOverlayBuffer?: number
+  /**
+   * Max concurrent in-flight Phase-13 keyframe-group repairs (relay SUBSCRIBE
+   * flood mitigation, T-13-01). Required once repair is wired: registering
+   * `onRepairRequest` without it throws — there is no default. A number is
+   * validated at construction. A bound derived from live measurements that
+   * arrive after construction (e.g. ceil(reliableRtt / keyframeCadence)) is
+   * passed as a reader, evaluated at each repair decision: a throw or a value
+   * that is not a positive safe integer skips that group's repair (fail closed
+   * per decision, not per session) and the next decision reads it again.
+   * Unused for FEC tracks, which never arm the keyframe-lost path; their QUIC
+   * repair is the D-28 scheduler (`wireRepairFetch`), prioritised by block
+   * class.
+   */
+  maxRepairInFlight?: number | (() => number)
+  /**
+   * Allow multicast takeover from a delta frame after the player has confirmed
+   * that MoQ already seeded the same decoder timeline with a video keyframe.
+   * Default false: decoder-reset paths still need multicast to provide a RAP.
+   */
+  allowDeltaMulticastTakeoverAfterMoqKeyframe?: boolean
+}
+
+/**
+ * A per-track source that emits frames independently of the binary MoQ/multicast path.
+ * Used by setTrackSource() to wire specific tracks to specific transport sources.
+ */
+export interface TrackSource {
+  name: string
+  /**
+   * Register a frame callback. Returns an unsubscribe function.
+   * MediaRouter calls unsubscribe() when clearTrackSource() is called.
+   */
+  onFrame(cb: (data: Uint8Array, meta: FrameMeta) => void): () => void
+  /**
+   * Optional error callback for when the source fails.
+   * MediaRouter uses this to trigger failback to binary switching for this track.
+   */
+  onError?(cb: () => void): () => void
+  /** Optional dispose hook called when clearTrackSource() is called. */
+  dispose?(): void
+}
+
+/**
+ * Thrown when setTrackSource() is called for a track that already has a source
+ * without an intervening clearTrackSource(). Prevents silent concurrent-assignment
+ * races (T-02-16 mitigation).
+ */
+export class TrackSourceConflictError extends Error {
+  constructor(public readonly trackName: string) {
+    super(`Track source already assigned for '${trackName}'; call clearTrackSource first`)
+    this.name = 'TrackSourceConflictError'
+  }
+}
+
+/**
+ * Migration policy for setTrackSource() transport switching.
+ *
+ * - 'crossfade': Overlap old (binary) and new source briefly (CROSSFADE_WINDOW_FRAMES),
+ *   then suppress the binary path. Default for audio.
+ * - 'drop':      Cut to new source immediately. Binary path suppressed at once.
+ *                Suitable for latency-critical tracks.
+ * - 'wait':      Defer migration until first FEC block boundary (same as overlay=true).
+ *                Default for video — avoids decoder reset mid-block.
+ */
+export type MigrationPolicy = 'crossfade' | 'drop' | 'wait'
+
+/** Default crossfade window — override via MediaRouterOptions.crossfadeFrames. */
+const DEFAULT_CROSSFADE_FRAMES = 10
+
+/** Options passed to setTrackSource(). */
+export interface SetTrackSourceOptions {
+  /**
+   * If true, this source is an overlay track that must wait for the first FEC
+   * block boundary signal (via notifyFecBlockBoundary()) before emitting frames.
+   * Frames arriving before the first boundary are buffered up to MAX_OVERLAY_BUFFER.
+   *
+   * Backwards compat: equivalent to policy: 'wait'.
+   */
+  overlay?: boolean
+  /**
+   * Migration policy for the transport switch. Overrides `overlay` when provided.
+   * See MigrationPolicy for semantics.
+   */
+  policy?: MigrationPolicy
+}
+
+/** Default overlay buffer cap — override via MediaRouterOptions.maxOverlayBuffer. */
+const DEFAULT_MAX_OVERLAY_BUFFER = 128
+
+/** Internal per-track source record. */
+interface TrackSourceRecord {
+  source: TrackSource
+  unsubscribeFrame: () => void
+  unsubscribeError?: () => void
+  emitCount: number
+}
+
+export class MediaRouter {
+  #active: SourceKind = 'moq'
+  #multicastVideoKeyed = false
+  #multicastAudioReceived = false
+  #moqVideoKeyframeEmitted = false
+  #requireAudio: boolean
+  #suppressed = false // true after multicast confirmed — suppresses MoQ
+  #audioFallbackTimer: ReturnType<typeof setTimeout> | null = null
+
+  // Configurable constants (from catalog/FEC config, not magic numbers)
+  readonly #audioFallbackMs: number
+  readonly #crossfadeFrames: number
+  readonly #maxOverlayBuffer: number
+  readonly #allowDeltaMulticastTakeoverAfterMoqKeyframe: boolean
+
+  // ── Keyframe repair state ────────────────────────────────────────
+  /** Groups currently being repaired — idempotent guard per Pitfall 2 (T-13-01 mitigation) */
+  #repairInFlight = new Set<number>()
+  /** Max concurrent repairs — prevents relay SUBSCRIBE flood (T-13-01 mitigation). A reader is evaluated per decision. */
+  readonly #maxRepairInFlight: number | (() => number) | null
+  /** Callback to request MoQ subscribe for a specific group (wired by player) */
+  #onRepairRequest: ((expectedGroupId: number, trackName: string) => void) | null = null
+
+  #onVideoFrame: FrameCb | null = null
+  #onAudioFrame: FrameCb | null = null
+  #onOverlayFrame: FrameCb | null = null
+  #onSourceSwitch: SwitchCb | null = null
+  #sourceSwitchReady: Promise<void> | null = null
+  #sourceSwitchToken = 0
+  #pendingMulticastToken: number | null = null
+  #pendingMulticastVideo: { data: Uint8Array; meta: FrameMeta } | null = null
+  #pendingMulticastAudio: { data: Uint8Array; meta: FrameMeta } | null = null
+
+  // Per-track source state
+  #trackSources = new Map<string, TrackSourceRecord>()
+
+  // Track type registry: trackName → { type, source }.
+  // Init data / inline signaling is authoritative until catalog updates.
+  // Priority: 'init' > 'catalog' > 'name' (backward compat fallback).
+  #trackTypes = new Map<string, { type: FrameKind; source: 'catalog' | 'init' }>()
+
+  // Crossfade state: maps trackName → remaining binary-path frames allowed during window
+  #crossfadeCounters = new Map<string, number>()
+
+  // Overlay alignment state
+  #overlayBoundaryReached = false
+  #overlayBuffer: Array<{ data: Uint8Array; meta: FrameMeta }> = []
+
+  // ── 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: boolean = true
+  #deltaWindow: boolean[] = []         // ring buffer: true = block failed
+  #deltaWindowSize: number = 0
+  #deltaFailThresholdRatio: number = 0  // P/K
+  #deltaRecoverThresholdRatio: number = 0  // (P/K)/2 — hysteresis (D-13)
+  #deltaProbeIntervalMs: number = 0
+  #lastProbeAt: number = 0
+  #onDeltaFallbackCb: (() => void) | null = null
+  #onDeltaRecoverCb: (() => void) | null = null
+
+  constructor(options?: MediaRouterOptions) {
+    this.#requireAudio = options?.requireAudio ?? true
+    // Catalog-derived — the caller passes an audioFallbackMs computed from the
+    // FEC recovery window (computeFecDeliveryWindowMs). No magic default: when
+    // absent, the independent audio-fallback timer is disabled (0) and
+    // activation waits for real audio arrival.
+    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 !== undefined &&
+      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: FrameCb) { this.#onVideoFrame = cb }
+  onAudioFrame(cb: FrameCb) { this.#onAudioFrame = cb }
+  onOverlayFrame(cb: FrameCb) { this.#onOverlayFrame = cb }
+  onSourceSwitch(cb: SwitchCb) { this.#onSourceSwitch = cb }
+
+  get activeSource(): SourceKind { return this.#active }
+
+  // ── Keyframe repair API ──────────────────────────────────────────
+
+  /** Register callback for keyframe repair requests. Player wires this to issue MoQ SUBSCRIBE. */
+  onRepairRequest(cb: (expectedGroupId: number, trackName: string) => void): void {
+    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: number, trackName = 'video'): void {
+    if (this.#active !== 'multicast') return // only repair on multicast path
+    if (this.#maxRepairInFlight === null) return // repair is not wired
+    if (this.#repairInFlight.has(expectedGroupId)) return // idempotent
+    let maxRepairInFlight: number
+    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: Uint8Array, meta: FrameMeta, kind: FrameKind): void {
+    // Repair only makes sense when multicast is active.
+    // Silently drop if MoQ became active (race with failbackToMoq) to avoid
+    // injecting stale-timestamp frames into the MoQ decoder path (WR-02).
+    if (this.#active !== 'multicast') return
+    const routedMeta = { ...meta, source: 'repair' as const, 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: number): void {
+    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: {
+    framerate: number
+    sourceSymbols: number
+    repairSymbols: number
+    deltaFailWindowBlocks?: number
+    deltaProbeIntervalMs?: number
+    interleaveDepthMs?: number
+  }): void {
+    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 === undefined && cfg.interleaveDepthMs === undefined) {
+      throw new Error(
+        '[MediaRouter] configureDelta: either deltaProbeIntervalMs or interleaveDepthMs required for probe interval derivation'
+      )
+    }
+
+    // Derivations — no magic floors, no hardcoded defaults (CLAUDE.md).
+    this.#deltaWindowSize = cfg.deltaFailWindowBlocks ?? Math.ceil(cfg.framerate)
+    this.#deltaFailThresholdRatio = cfg.repairSymbols / cfg.sourceSymbols
+    this.#deltaRecoverThresholdRatio = this.#deltaFailThresholdRatio / 2
+    // Without an explicit probe interval, use one complete signaled block span.
+    this.#deltaProbeIntervalMs = cfg.deltaProbeIntervalMs ?? computeFecDeliveryWindowMs({
+      interleaveDepthMs: cfg.interleaveDepthMs!,
+      sourceSymbols: cfg.sourceSymbols,
+    })
+
+    // Reset state — useful for stream restart.
+    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: boolean, nowMs: number): void {
+    if (!this.#deltaConfigured) return
+
+    // Maintain sliding window — ring buffer semantics.
+    this.#deltaWindow.push(failed)
+    if (this.#deltaWindow.length > this.#deltaWindowSize) {
+      this.#deltaWindow.shift()
+    }
+
+    // Window not yet full — insufficient data for decision.
+    if (this.#deltaWindow.length < this.#deltaWindowSize) return
+
+    const failedCount = this.#deltaWindow.filter(x => x).length
+    const ratio = failedCount / this.#deltaWindowSize
+
+    if (this.#deltaActive) {
+      // Fallback transition: active → inactive (T-14-03: fires exactly once)
+      if (ratio > this.#deltaFailThresholdRatio) {
+        this.#deltaActive = false
+        this.#lastProbeAt = nowMs
+        this.#onDeltaFallbackCb?.()
+      }
+    } else {
+      // Recovery transition: inactive → active (after probe interval + low ratio)
+      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: () => void): void {
+    this.#onDeltaFallbackCb = cb
+  }
+
+  /** Register callback fired when delta track recovers below recovery threshold (D-13). */
+  onDeltaRecover(cb: () => void): void {
+    this.#onDeltaRecoverCb = cb
+  }
+
+  /** Whether the delta track is currently considered healthy (true = active). */
+  get deltaActive(): boolean {
+    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(): number { return this.#deltaWindowSize }
+  /** Derived fail threshold ratio (P/K) — exposed for test assertions (Test 6). */
+  get deltaFailThresholdRatio(): number { return this.#deltaFailThresholdRatio }
+  /** Derived recovery threshold ratio ((P/K)/2) — exposed for test assertions (Test 7). */
+  get deltaRecoverThresholdRatio(): number { return this.#deltaRecoverThresholdRatio }
+  /** Derived probe interval ms — exposed for test assertions (Test 5a). */
+  get deltaProbeIntervalMs(): number { 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: string, type: FrameKind): void {
+    // Catalog overwrites any previous registration (including init).
+    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: string, type: FrameKind): void {
+    const existing = this.#trackTypes.get(trackName)
+    if (existing?.source === 'catalog') return // catalog already set — don't downgrade
+    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: string, source: TrackSource, opts?: SetTrackSourceOptions): void {
+    if (this.#trackSources.has(trackName)) {
+      throw new TrackSourceConflictError(trackName)
+    }
+
+    // Resolve effective policy. opts.policy takes precedence; overlay=true is legacy 'wait'.
+    const effectivePolicy: MigrationPolicy | undefined =
+      opts?.policy ?? (opts?.overlay ? 'wait' : undefined)
+
+    // For crossfade: open the binary-path window immediately so the first per-track frame
+    // triggers the window (counter starts before the frame callback is wired).
+    if (effectivePolicy === 'crossfade') {
+      this.#crossfadeCounters.set(trackName, this.#crossfadeFrames)
+    }
+
+    const record: TrackSourceRecord = {
+      source,
+      unsubscribeFrame: () => {},
+      emitCount: 0,
+    }
+
+    // Wire the frame callback
+    record.unsubscribeFrame = source.onFrame((data, meta) => {
+      record.emitCount++
+      if (effectivePolicy === 'wait') {
+        this.#handleOverlayFrame(data, meta)
+      } else {
+        // 'drop', 'crossfade', or undefined: emit immediately
+        this.#emitForTrack(trackName, data, meta)
+      }
+    })
+
+    // Wire the optional error callback — failback to binary switching
+    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: string): void {
+    const record = this.#trackSources.get(trackName)
+    if (!record) return
+
+    record.unsubscribeFrame()
+    record.unsubscribeError?.()
+    record.source.dispose?.()
+    this.#trackSources.delete(trackName)
+
+    // Clean up crossfade window if one was active for this track
+    this.#crossfadeCounters.delete(trackName)
+
+    // Reset overlay buffer if removing a non-media track (overlay/unknown)
+    const reg = this.#trackTypes.get(trackName)
+    const isMedia = reg?.type === 'video' || reg?.type === 'audio' ||
+      (reg === undefined && (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(): void {
+    if (this.#overlayBoundaryReached) return
+    this.#overlayBoundaryReached = true
+
+    // Flush buffered overlay frames
+    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: string): number {
+    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: Uint8Array, meta: FrameMeta, kind: FrameKind) {
+    // Per-track source takes precedence; allow through during crossfade window
+    if (this.#trackSources.has(kind)) {
+      const remaining = this.#crossfadeCounters.get(kind)
+      if (remaining && remaining > 0) {
+        // Decrement crossfade counter and allow this frame through
+        const next = remaining - 1
+        if (next === 0) {
+          this.#crossfadeCounters.delete(kind)
+        } else {
+          this.#crossfadeCounters.set(kind, next)
+        }
+        // Fall through to emit below (no return)
+      } else {
+        return // suppressed — no crossfade window active
+      }
+    }
+    if (this.#suppressed) return
+    // Audio suppression is handled by SessionManager onSuppress callback —
+    // do NOT independently suppress based on multicastAudioReceived.
+    // The state machine decides when to switch; the router just routes.
+    const routedMeta = { ...meta, source: 'moq' as const }
+    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: Uint8Array, meta: FrameMeta, kind: FrameKind) {
+    // Per-track source takes precedence; allow through during crossfade window
+    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)
+        }
+        // Fall through to emit below (no return)
+      } else {
+        return // suppressed
+      }
+    }
+
+    if (kind === 'video') {
+      if (!this.#multicastVideoKeyed) {
+        const moqSeededDelta =
+          !meta.keyframe &&
+          this.#allowDeltaMulticastTakeoverAfterMoqKeyframe &&
+          this.#moqVideoKeyframeEmitted
+        if (!meta.keyframe && !moqSeededDelta) return // drop until first safe decode point
+        this.#multicastVideoKeyed = true
+        const pendingMeta: FrameMeta = { ...meta, source: 'multicast' }
+        if (!moqSeededDelta) pendingMeta.sourceDiscontinuity = true
+        this.#pendingMulticastVideo = {
+          data: data.slice(),
+          meta: pendingMeta,
+        }
+        // If audio is required but hasn't arrived yet, start a fallback timer.
+        // Audio FEC blocks may recover after video — don't block activation forever.
+        // Only arms when a catalog-derived audioFallbackMs was supplied (>0).
+        if (this.#requireAudio && this.#audioFallbackMs > 0 && !this.#multicastAudioReceived && !this.#audioFallbackTimer) {
+          this.#audioFallbackTimer = setTimeout(() => {
+            if (!this.#multicastAudioReceived && this.#active !== 'multicast') {
+              this.#multicastAudioReceived = true // force
+              // Also release the MoQ-audio-warmup gate so the fallback actually
+              // activates — otherwise #tryActivateMulticast would still bail.
+              this.#moqAudioWarmed = true
+              this.#tryActivateMulticast()
+            }
+          }, this.#audioFallbackMs)
+        }
+      } else if (this.#active !== 'multicast') {
+        // Do not feed video into the multicast decoder while the source switch
+        // is still pending. Keep the newest keyframe as the post-activation
+        // decoder opener and drop deltas until takeover commits.
+        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
+      }
+      // BLO-3035 layer 5: in a multicast-first scenario (no MoQ unicast audio
+      // source) `notifyMoqAudioEmit()` is never called and the audio-fallback
+      // timer's force-set is bypassed (the timer's inner `!multicastAudioReceived`
+      // check returns early because audio already arrived). Without this gate
+      // `#moqAudioWarmed` stays false forever and `#tryActivateMulticast` never
+      // fires `onSourceSwitch('multicast')` — the player can't know to emit
+      // `__MULTICAST_TAKEOVER_TIME`. Treat the arrival of multicast audio as
+      // sufficient evidence to release the warmup gate. For the MoQ→multicast
+      // handoff case `notifyMoqAudioEmit()` will already have set this flag, so
+      // the assignment is idempotent.
+      if (!this.#moqAudioWarmed) this.#moqAudioWarmed = true
+      // Activate BEFORE delivering the frame — the source switch callback
+      // (e.g. ring buffer reset) must fire before the first multicast audio
+      // frame reaches the backend. Otherwise the NTP timestamp hits the
+      // MoQ-era ring buffer base → overflow → silence gap.
+      this.#tryActivateMulticast()
+      // Only emit multicast audio AFTER takeover succeeds. Before takeover,
+      // MoQ audio is still flowing through feedMoq → #onAudioFrame; emitting
+      // multicast audio too would double-feed the backend (2x audio frames,
+      // pitch wobble and distortion). Post-takeover, feedMoq is suppressed
+      // (#suppressed=true) so only multicast audio reaches the backend.
+      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. */
+  public notifyMoqAudioEmit(): void {
+    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.
+   */
+  public notifyMoqVideoKeyframeEmit(): void {
+    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 as Promise<void>).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: number) {
+    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: number, err: unknown) {
+    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 // already on MoQ, no-op
+    ++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
+    // A pending audio-fallback timer belongs to the abandoned takeover attempt.
+    // Left running it would force-set the audio flags against the next attempt's
+    // fresh state (BLO-9413 failback coherence — every takeover-era flag/timer
+    // unwinds on this edge).
+    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(): void {
+    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: string, data: Uint8Array, meta: FrameMeta): void {
+    // Prefer explicit type registry (catalog or init data)
+    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 !== undefined) {
+      // Registered but unknown type — overlay
+      this.#onOverlayFrame?.(data, meta)
+    } else {
+      // Not registered — fall back to name match (backward compat for tests/legacy)
+      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: Uint8Array, meta: FrameMeta): void {
+    if (this.#overlayBoundaryReached) {
+      this.#onOverlayFrame?.(data, meta)
+      return
+    }
+
+    // Buffer until boundary — enforcing cap for T-02-17 DoS mitigation
+    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 })
+  }
+}