@blockcast/mmt-container 0.1.0-main.149f78a4adae

package/src/media-router.ts

@@ -0,0 +1,1185 @@
+/**
+ * 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.
+ *
+ * notifyGroupBoundary() is an observer hook: callers report the
+ * packet-stamped groupId + media time for each group, and the router
+ * cross-checks against the shared `align.ts` formula. Drift is emitted via
+ * onGroupDrift so the player can bump the CMCD `x-bc-switch-drift-us` /
+ * `x-bc-switch-miscount` counters. Observation only — does NOT alter routing.
+ */
+
+import { groupIdForTicks, driftCheck } from './align.js'
+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
+}
+export type FrameKind = 'video' | 'audio'
+export type SourceKind = 'moq' | 'multicast'
+
+/**
+ * Tick-space timing for one group boundary — the exact, authoritative form.
+ *
+ * These are the integers the catalog already carries (`groupDurationTicks`,
+ * `timescale`) plus the packet's raw timestamp in the same units. Passing
+ * them straight through keeps the whole drift check in integer math.
+ *
+ * Prefer this over the seconds overload: `groupDurationTicks / timescale`
+ * is not exactly representable for the common non-integer-second cadences
+ * (33333@90k, 1001@30k, 1024@44.1k), and the seconds path has to quantize
+ * to whole nanoseconds — which shifts `expected` by a whole group from the
+ * second boundary onward and reports drift on a perfectly aligned stream.
+ */
+export interface GroupBoundaryTicks {
+  /** Packet media timestamp in `timescale` units. Integer; negatives clamp to 0. */
+  readonly mediaTimeTicks: number
+  /** Group duration in `timescale` units. Positive integer. */
+  readonly groupDurationTicks: number
+  /**
+   * Catalog timescale in Hz. Positive integer — **validated, and a hard gate**:
+   * a non-integer or non-positive value skips the drift check entirely rather
+   * than reporting against it. It does not feed the groupId computation (that
+   * is `mediaTimeTicks / groupDurationTicks` alone), but it does derive the
+   * `mediaTimeSec` / `groupDurationSec` on every GroupDriftEvent — so letting a
+   * bad value through would push NaN/Infinity into CMCD `x-bc-switch-drift-us`,
+   * which is worse than skipping.
+   */
+  readonly timescale: number
+}
+
+/** Payload emitted by MediaRouter.onGroupDrift when a packet-stamped groupId
+ *  disagrees with the shared `align.ts` formula. */
+export interface GroupDriftEvent {
+  trackName: string
+  expectedGroupId: number
+  actualGroupId: number
+  /** `actual - expected` (positive = ahead, negative = behind). */
+  deltaGroups: number
+  /** Seconds view, kept for CMCD consumers. Derived when the caller used ticks. */
+  mediaTimeSec: number
+  groupDurationSec: number
+  /** Exact tick-space inputs. Present only when the caller used the ticks form. */
+  timing?: GroupBoundaryTicks
+}
+
+/** Normalized output of the two notifyGroupBoundary input forms. */
+type ResolvedBoundary = {
+  readonly expected: number
+  readonly mediaTimeSec: number
+  readonly groupDurationSec: number
+  readonly timing?: GroupBoundaryTicks
+}
+
+/**
+ * Distinct failure modes on the notifyGroupBoundary drift path. Each gets its
+ * own bounded warn budget (see `#skipWithWarning`), so a stream that trips one
+ * cannot permanently silence the diagnostic for a genuinely different one.
+ *
+ * Deliberately a closed union rather than `string`: the tag is the dedup key,
+ * and a typo would silently mint a second budget for an existing reason.
+ */
+type GroupAlignSkipReason =
+  | 'invalid-tick-inputs'
+  // Currently UNREACHABLE, kept as defence in depth — see the catch in
+  // #resolveTicks. Do not write a test chasing it.
+  | 'ticks-formula-threw'
+  | 'invalid-seconds-inputs'
+  | 'sub-nanosecond-duration'
+  | 'media-time-overflow'
+  | 'seconds-formula-threw'
+  | 'callback-threw'
+
+/**
+ * Warns allowed per `GroupAlignSkipReason` for the lifetime of a router.
+ *
+ * Not a single flat number (PCL-2211, #329 review). The six resolver reasons
+ * are closed, deterministic conditions: once you have seen
+ * `sub-nanosecond-duration` on this router, the second occurrence carries no
+ * new information, so one slot is the right budget and repeated malformed
+ * catalog input stays silent.
+ *
+ * `callback-threw` is the opposite. It wraps arbitrary downstream consumer
+ * code and interpolates `err.message` *because the error varies*. Under one
+ * slot, a consumer that throws at startup permanently hides an unrelated
+ * exception later — including one from a *replacement* consumer registered
+ * through `onGroupDrift()`, which is a public setter with no budget reset.
+ * That is the same argument `#skipWithWarning` makes against a single shared
+ * boolean, one level down. A small cap bounds the flood, at the cost of
+ * silencing distinct errors past the cap: three throws at startup exhaust
+ * `callback-threw`, and a replacement consumer's unrelated exception is then
+ * silenced permanently — the same failure as the one-slot budget, moved from
+ * the 1st throw to the 4th. That residual is the inherent price of a bounded
+ * budget and is accepted deliberately; the alternative is an unbounded warn.
+ *
+ * Deliberately NOT a reset on `onGroupDrift()` re-registration: that setter is
+ * public and unthrottled, so a caller re-registering per boundary would
+ * refresh the budget every time and restore the exact flood this prevents.
+ *
+ * A total `Record` rather than a lookup with a default: the union is closed, so
+ * a new reason that forgets to declare its budget is a compile error — the
+ * same typo-safety rationale that makes the union closed in the first place.
+ */
+const GROUP_ALIGN_WARN_BUDGET: Record<GroupAlignSkipReason, number> = {
+  'invalid-tick-inputs': 1,
+  'ticks-formula-threw': 1,
+  'invalid-seconds-inputs': 1,
+  'sub-nanosecond-duration': 1,
+  'media-time-overflow': 1,
+  'seconds-formula-threw': 1,
+  'callback-threw': 3,
+}
+
+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 repairs. Prevents relay SUBSCRIBE flood (T-13-01 mitigation).
+   * Default: 2.
+   */
+  maxRepairInFlight?: 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) */
+  readonly #maxRepairInFlight: number
+  /** 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
+    this.#maxRepairInFlight = options?.maxRepairInFlight ?? 2
+    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 }
+
+  // ── Group-alignment observer (align.ts formula) ──────────────────
+  // Observation only — does NOT alter routing. Producers are wired in
+  // follow-up PRs; when they land they will call
+  // CmcdProducer.incrementSwitchMiscount() + emitSwitchDrift() from the
+  // onGroupDrift callback so divergence between packet-stamped groupIds
+  // and the shared formula surfaces on `x-bc-switch-drift-us` /
+  // `x-bc-switch-miscount`. Canonical Go impl: Blockcast/multicast
+  // cmd/caddy/sender/group_align.go (commit 104eeff). Canonical Rust impl:
+  // moqtail/moqtail apps/relay/src/server/abr.rs (branch
+  // experimental/server-side-abr, commit 39accbf).
+  #onGroupDrift: ((evt: GroupDriftEvent) => void) | null = null
+  #groupAlignWarnCounts = new Map<GroupAlignSkipReason, number>()
+  onGroupDrift(cb: (evt: GroupDriftEvent) => void): void {
+    this.#onGroupDrift = cb
+  }
+
+  /**
+   * Report a group boundary observed on an incoming track. Cross-checks the
+   * packet-stamped groupId against the shared `align.ts` formula and fires
+   * the onGroupDrift callback when they disagree.
+   *
+   * Two input forms:
+   *   - **Ticks (preferred).** `notifyGroupBoundary(track, id, { mediaTimeTicks,
+   *     groupDurationTicks, timescale })` — pure integer math via
+   *     `align.groupIdForTicks`, no rounding anywhere.
+   *   - **Seconds (deprecated).** The 4-argument form. Quantizes both operands
+   *     to whole nanoseconds, which is exact only when `groupDurationSec` is a
+   *     whole number of nanoseconds. It is not for 33333@90k, 1001@30k or
+   *     1024@44.1k, and there `expected` diverges by a whole group from the
+   *     second boundary onward — a false drift event on every subsequent
+   *     group, and a systematically wrong CMCD `x-bc-switch-drift-us`.
+   *
+   * No-op when no onGroupDrift callback is registered (avoid unnecessary work
+   * on hot paths).
+   *
+   * Hot-path robustness (does NOT throw on bad inputs — the ingest stream
+   * must not be torn down by a malformed catalog or a disposed producer):
+   *   - Invalid duration (NaN / <=0) or non-finite media time → warn + early
+   *     return (same convention as audioFallbackMs).
+   *   - Any throw out of the align formula (e.g. the safe-integer overflow
+   *     guard at ~104 days of media time on the seconds path) is caught +
+   *     logged so an unusually long-running stream cannot tear down ingest.
+   *   - Callback throws are caught + logged; ingest continues.
+   *   - Skip warnings are coalesced **per failure mode** for the lifetime
+   *     of the router (never reset, including across `dispose()`), so a hot
+   *     path cannot flood the log while a genuinely new failure mode still
+   *     gets heard. Deterministic modes get one line; a throwing consumer
+   *     callback gets a small budget because its error varies. See
+   *     `#skipWithWarning` and `GROUP_ALIGN_WARN_BUDGET`.
+   *
+   * Init-track filter: media time === 0 with a non-zero stamped groupId is
+   * treated as an init/ambient track emitting pre-PTS-zero packets and is
+   * skipped (matches Go's base-clamp intent without producing spurious
+   * drift).
+   *
+   * NOTE: do NOT call from the repair path (feedRepair). Repair frames carry
+   * the groupId they are recovering for, not a freshly-stamped one.
+   */
+  notifyGroupBoundary(
+    trackName: string,
+    packetGroupId: number,
+    timing: GroupBoundaryTicks,
+  ): void
+  /**
+   * @deprecated Pass a {@link GroupBoundaryTicks} instead. The seconds form
+   *   rounds to whole nanoseconds and reports phantom drift on catalogs whose
+   *   `groupDurationTicks / timescale` is not ns-exact.
+   */
+  notifyGroupBoundary(
+    trackName: string,
+    packetGroupId: number,
+    mediaTimeSec: number,
+    groupDurationSec: number,
+  ): void
+  notifyGroupBoundary(
+    trackName: string,
+    packetGroupId: number,
+    timingOrMediaTimeSec: GroupBoundaryTicks | number,
+    groupDurationSec?: number,
+  ): void {
+    if (!this.#onGroupDrift) return
+
+    const resolved =
+      typeof timingOrMediaTimeSec === 'object' && timingOrMediaTimeSec !== null
+        ? this.#resolveTicks(trackName, timingOrMediaTimeSec)
+        : this.#resolveSeconds(
+            trackName,
+            timingOrMediaTimeSec as number,
+            groupDurationSec as number,
+          )
+    if (!resolved) return
+
+    // Init/ambient track heuristic: mediaTime=0 with stamped groupId !== 0
+    // is a signaling packet pre-PTS-zero, not a real drift. Skipping here
+    // avoids every stream opening with a false drift event.
+    if (resolved.mediaTimeSec === 0 && packetGroupId !== 0) return
+
+    const expected = resolved.expected
+    const result = driftCheck(expected, packetGroupId)
+    if (result.kind === 'aligned') return
+
+    try {
+      this.#onGroupDrift({
+        trackName,
+        expectedGroupId: expected,
+        actualGroupId: packetGroupId,
+        deltaGroups: result.deltaGroups,
+        mediaTimeSec: resolved.mediaTimeSec,
+        groupDurationSec: resolved.groupDurationSec,
+        ...(resolved.timing ? { timing: resolved.timing } : {}),
+      })
+    } catch (err) {
+      // A disposed CmcdProducer (or any downstream consumer) throwing here
+      // must NOT tear down the MoQ ingest stream. Log and continue.
+      //
+      // Routed through the same per-reason budget as the resolver skips: this
+      // fires once per DRIFT EVENT, so a consumer that throws on every
+      // boundary would otherwise flood at boundary rate — exactly the failure
+      // mode #skipWithWarning exists to prevent, and exactly the disposed-
+      // producer scenario this comment already cites (#329 review).
+      this.#skipWithWarning(
+        'callback-threw',
+        `[MediaRouter] onGroupDrift callback threw (track=${trackName} expected=${expected} actual=${packetGroupId}); continuing: ${(err as Error)?.message ?? err}`,
+      )
+    }
+  }
+
+  /**
+   * Warn at most `GROUP_ALIGN_WARN_BUDGET[reason]` times **per reason**, across
+   * every skip and post-emit failure on the drift path.
+   *
+   * Note the two call shapes: the resolvers call this *instead of* computing a
+   * groupId, and return its `null` to skip the drift check; the `onGroupDrift`
+   * catch calls it after the check already ran and the event was already
+   * emitted, so there only the warn is coalesced and the `null` is discarded.
+   *
+   * Keyed on a short stable `reason` tag, NOT on the formatted message: the
+   * messages interpolate track name and operand values, so message-keying
+   * would hand a malformed stream a fresh warn slot on every boundary — the
+   * log flood this coalescing exists to prevent.
+   *
+   * Per-reason rather than one shared boolean (PCL-2211, #329 review): the
+   * budget is never reset — not by `dispose()`, not on source switch — so a
+   * single flag means the FIRST malformed boundary of a long-running stream
+   * permanently silences every later, genuinely different failure mode. The
+   * throw/overflow diagnostics carry the operand values (`ticks=`, `durTicks=`,
+   * `err.message`) an incident responder actually needs, and under one shared
+   * flag those are precisely the ones most likely to be already spent by an
+   * unrelated NaN at catalog load.
+   *
+   * A closed, bounded set of reasons times a small per-reason budget is still
+   * bounded, so this cannot flood. See `GROUP_ALIGN_WARN_BUDGET` for why the
+   * budget is not uniform.
+   */
+  #skipWithWarning(reason: GroupAlignSkipReason, message: string): null {
+    const seen = this.#groupAlignWarnCounts.get(reason) ?? 0
+    if (seen < GROUP_ALIGN_WARN_BUDGET[reason]) {
+      this.#groupAlignWarnCounts.set(reason, seen + 1)
+      console.warn(message)
+    }
+    return null
+  }
+
+  /**
+   * Exact path: integers straight from the catalog, no rounding. `mediaTimeSec`
+   * / `groupDurationSec` are derived for reporting only and never feed the
+   * groupId computation.
+   */
+  #resolveTicks(
+    trackName: string,
+    timing: GroupBoundaryTicks,
+  ): ResolvedBoundary | null {
+    const { mediaTimeTicks, groupDurationTicks, timescale } = timing
+    if (
+      !Number.isInteger(mediaTimeTicks) ||
+      !Number.isInteger(groupDurationTicks) ||
+      groupDurationTicks <= 0 ||
+      !Number.isInteger(timescale) ||
+      timescale <= 0
+    ) {
+      return this.#skipWithWarning(
+        'invalid-tick-inputs',
+        `[MediaRouter] notifyGroupBoundary invalid tick inputs (track=${trackName} mediaTimeTicks=${mediaTimeTicks} groupDurationTicks=${groupDurationTicks} timescale=${timescale}); skipping drift check. Pre-validate at catalog load time.`,
+      )
+    }
+    try {
+      return {
+        expected: groupIdForTicks(mediaTimeTicks, groupDurationTicks),
+        mediaTimeSec: mediaTimeTicks / timescale,
+        groupDurationSec: groupDurationTicks / timescale,
+        // Snapshot, not the caller's reference: a producer that reuses one
+        // scratch object per boundary would otherwise retroactively mutate
+        // every GroupDriftEvent it has already emitted. Three integers.
+        timing: { mediaTimeTicks, groupDurationTicks, timescale },
+      }
+    } catch (err) {
+      // UNREACHABLE as of today, and deliberately kept. groupIdForTicks throws
+      // on exactly two conditions — !Number.isInteger(ticks) and
+      // !Number.isInteger(groupDurationTicks) || groupDurationTicks <= 0 — and
+      // the guard above pre-rejects both; Math.floor(a / b) does not throw.
+      //
+      // Kept because align.ts is a separate module that can grow a new
+      // precondition (a safe-integer check, say) without this file changing,
+      // and the no-throw contract must hold on that day too. Nobody should
+      // write a test chasing this branch — see BLO-21176 note.
+      //
+      // NOTE the asymmetry this implies: the seconds path is the only one that
+      // can actually reach its catch, because durTicks <= 0 cannot catch
+      // Infinity and Number.isSafeInteger guards only `ticks`. That is the real
+      // shape of the AC#5a bug, not an oversight in this resolver.
+      return this.#skipWithWarning(
+        'ticks-formula-threw',
+        `[MediaRouter] notifyGroupBoundary: groupIdForTicks threw (track=${trackName} mediaTimeTicks=${mediaTimeTicks} groupDurationTicks=${groupDurationTicks}); skipping drift check: ${(err as Error)?.message ?? err}`,
+      )
+    }
+  }
+
+  /**
+   * Legacy seconds path. Quantizes to a synthetic 1e9 Hz timescale — the exact
+   * behaviour the deprecated `align.groupIdFor` wrapper had, reproduced here so
+   * that wrapper has no non-test callers left and can be deleted (BLO-21176).
+   *
+   * Inherits that wrapper's ns-rounding error; see the `@deprecated` overload.
+   * Delete this branch once every caller passes ticks.
+   */
+  #resolveSeconds(
+    trackName: string,
+    mediaTimeSec: number,
+    groupDurationSec: number,
+  ): ResolvedBoundary | null {
+    if (
+      !Number.isFinite(groupDurationSec) ||
+      groupDurationSec <= 0 ||
+      !Number.isFinite(mediaTimeSec)
+    ) {
+      return this.#skipWithWarning(
+        'invalid-seconds-inputs',
+        `[MediaRouter] notifyGroupBoundary invalid inputs (track=${trackName} mediaTimeSec=${mediaTimeSec} groupDurationSec=${groupDurationSec}); skipping drift check. Pre-validate at catalog load time.`,
+      )
+    }
+    // 1e9 Hz keeps both operands inside MAX_SAFE_INTEGER for ~104 days of
+    // media time. Past that Math.round yields a non-safe integer that
+    // Number.isInteger still accepts, so bail explicitly rather than
+    // silently quantizing — ingest must survive either way.
+    const TS = 1_000_000_000
+    const ticks = mediaTimeSec < 0 ? 0 : Math.round(mediaTimeSec * TS)
+    const durTicks = Math.round(groupDurationSec * TS)
+    if (durTicks <= 0) {
+      return this.#skipWithWarning(
+        'sub-nanosecond-duration',
+        `[MediaRouter] notifyGroupBoundary: groupDurationSec=${groupDurationSec} rounds to <1 tick at 1e9 Hz (track=${trackName}); skipping drift check. Pass GroupBoundaryTicks for sub-nanosecond durations.`,
+      )
+    }
+    if (!Number.isSafeInteger(ticks)) {
+      return this.#skipWithWarning(
+        'media-time-overflow',
+        `[MediaRouter] notifyGroupBoundary: mediaTimeSec=${mediaTimeSec} overflows safe-integer ticks at 1e9 Hz (>~104 days, track=${trackName}); skipping drift check. Pass GroupBoundaryTicks with the catalog timescale.`,
+      )
+    }
+    // Same try as #resolveTicks: a finite groupDurationSec can still overflow
+    // the * 1e9 multiply to Infinity, which clears the durTicks <= 0 bail above
+    // but fails Number.isInteger inside groupIdForTicks. Without this catch the
+    // throw escapes notifyGroupBoundary and breaks its documented no-throw
+    // contract — the one path #resolveTicks already guards and this did not.
+    try {
+      return {
+        expected: groupIdForTicks(ticks, durTicks),
+        mediaTimeSec,
+        groupDurationSec,
+      }
+    } catch (err) {
+      return this.#skipWithWarning(
+        'seconds-formula-threw',
+        `[MediaRouter] notifyGroupBoundary: groupIdForTicks threw (track=${trackName} mediaTimeSec=${mediaTimeSec} groupDurationSec=${groupDurationSec} ticks=${ticks} durTicks=${durTicks}); skipping drift check: ${(err as Error)?.message ?? err}`,
+      )
+    }
+  }
+
+  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 {
+    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.
+   * @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.#repairInFlight.has(expectedGroupId)) return // idempotent
+    if (this.#repairInFlight.size >= this.#maxRepairInFlight) {
+      console.warn(
+        `[MediaRouter] max repair in flight (${this.#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
+    // Probe interval routes through the ONE FEC recovery-window derivation
+    // (computeFecDeliveryWindowMs). Interleave-span + jitter margin only — the
+    // K-cycle production horizon (mediaUnitsPerSecond) is deliberately omitted:
+    // this is a re-subscribe cadence, not a block-recovery deadline. With no
+    // catalog jitterBufferMs the margin defaults to one interleave window, so
+    // the value equals the retired interleaveDepthMs*2 but is now catalog-tunable.
+    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 })
+  }
+}