@blockcast/mmt-container 0.1.0 → 0.3.0

package/dist/track-session.js

@@ -0,0 +1,754 @@
+// src/transport-pool.ts
+var TransportPool = class {
+  #subs = /* @__PURE__ */ new Map();
+  #options;
+  #failedCb = null;
+  #stats = { activeSubscriptions: 0, totalAcquires: 0, totalReleases: 0 };
+  constructor(options) {
+    this.#options = options ?? {};
+  }
+  /** Register callback for subscription failures. */
+  onSubscriptionFailed(cb) {
+    this.#failedCb = cb;
+  }
+  acquireSubscription(keyOrOpts, consumer) {
+    const key = typeof keyOrOpts === "string" ? keyOrOpts : keyOrOpts.key;
+    const cons = typeof keyOrOpts === "string" ? consumer : keyOrOpts.consumer;
+    const mode = typeof keyOrOpts === "object" ? keyOrOpts.mode : "moq";
+    let sub = this.#subs.get(key);
+    if (!sub) {
+      sub = { key, mode, consumers: /* @__PURE__ */ new Set() };
+      this.#subs.set(key, sub);
+      this.#stats.activeSubscriptions++;
+    }
+    ;
+    sub.consumers.add(cons);
+    this.#stats.totalAcquires++;
+    return sub;
+  }
+  /** Release a subscription for a consumer. Closes if last consumer. */
+  releaseSubscription(key, consumer) {
+    const sub = this.#subs.get(key);
+    if (!sub) return;
+    sub.consumers.delete(consumer);
+    this.#stats.totalReleases++;
+    if (sub.consumers.size === 0) {
+      this.#subs.delete(key);
+      this.#stats.activeSubscriptions--;
+    }
+  }
+  /** Release all subscriptions held by a consumer. */
+  releaseAllForConsumer(consumer) {
+    for (const [key, sub] of this.#subs) {
+      ;
+      sub.consumers.delete(consumer);
+      if (sub.consumers.size === 0) {
+        this.#subs.delete(key);
+        this.#stats.activeSubscriptions--;
+      }
+    }
+  }
+  /** Report a subscription failure. */
+  reportFailure(key, error) {
+    const sub = this.#subs.get(key);
+    if (sub) this.#failedCb?.({ key, consumers: sub.consumers, error });
+  }
+  /** Get stats. */
+  get stats() {
+    return this.#stats;
+  }
+  /** Clean up all subscriptions. */
+  dispose() {
+    this.#subs.clear();
+    this.#failedCb = null;
+    this.#stats.activeSubscriptions = 0;
+  }
+  /** Number of active subscriptions. */
+  get size() {
+    return this.#subs.size;
+  }
+};
+
+// src/track-session.ts
+import { fecBlockBudgetMs } from "@blockcast/mmt-fec";
+function computeFecLossWindowMs(fecInterleaveMs, fecK, jitterBufferMs) {
+  return computeFecDeliveryWindowMs({
+    interleaveDepthMs: fecInterleaveMs,
+    sourceSymbols: fecK,
+    jitterBufferMs
+  });
+}
+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);
+}
+function computeFecDeliveryWindowMediaUnits(config, timestampTimescale) {
+  if (!Number.isFinite(timestampTimescale) || timestampTimescale <= 0) {
+    throw new Error(
+      `[TrackSession] timestampTimescale=${timestampTimescale}. Derive a positive media timescale from the container.`
+    );
+  }
+  const deliveryWindow = Math.ceil(
+    computeFecDeliveryWindowMs(config) * timestampTimescale / 1e3
+  );
+  if (!Number.isSafeInteger(deliveryWindow)) {
+    throw new Error("[TrackSession] FEC delivery window exceeds the media timestamp range.");
+  }
+  return deliveryWindow;
+}
+var TrackSession = class {
+  #state = "idle";
+  #subscription = null;
+  #hysteresisTimer = null;
+  #joinDeadlineTimer = null;
+  #previousPrimary = null;
+  #manager;
+  // Single suppression authority flag (BLO-9413 failback coherence): every
+  // suppress this session fires is recorded here, and every path that leaves
+  // a suppressed state unwinds through #unsuppress(). Before this flag,
+  // unsubscribe() only un-suppressed from multicast/amt — a session torn down
+  // from `failing` (exactly where a starving track sits) was re-subscribed to
+  // unicast with the host's media still muted: MoQ playing into a dead sink.
+  #suppressFired = false;
+  // Single FEC authority flag: set by the fec-setup edges (joinStarted,
+  // enterUnicastFallback), cleared by the fec-teardown edge in #transition.
+  // Setup and teardown are paired by construction, so a takeover timeout that
+  // parks the session in `unicast` keeps the decoder the still-joined
+  // transport is feeding, and the later unsubscribe still tears it down.
+  #fecArmed = false;
+  constructor(config, manager) {
+    this.config = config;
+    this.#manager = manager;
+  }
+  // -----------------------------------------------------------------------
+  // State
+  // -----------------------------------------------------------------------
+  get state() {
+    return this.#state;
+  }
+  get subscription() {
+    return this.#subscription;
+  }
+  /** True while this session's onSuppress(true) is outstanding (no matching
+   *  onSuppress(false) yet). Test/assertion surface for failback coherence. */
+  get isSuppressed() {
+    return this.#suppressFired;
+  }
+  /** Current active transport mode, or null if idle. */
+  get transport() {
+    switch (this.#state) {
+      case "multicast":
+        return "multicast";
+      case "amt":
+        return "amt";
+      case "unicast":
+        return "moq";
+      case "unicast-fallback":
+        return "moq";
+      // SSM bridge absent — MoQ unicast is the only source
+      case "joining":
+        return "moq";
+      // MoQ still primary during join
+      case "failing":
+        return this.#previousPrimary;
+      default:
+        return null;
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Computed (no magic numbers)
+  // -----------------------------------------------------------------------
+  /** Audio worklet latency: max(fecInterleaveMs, frameDurationMs * fecK).
+   *  Returns undefined if frame duration unknown (no initData). */
+  get audioLatencyMs() {
+    const fd = this.frameDurationMs;
+    if (fd === void 0) {
+      return this.config.fecInterleaveMs > 0 ? this.config.fecInterleaveMs : void 0;
+    }
+    return Math.max(this.config.fecInterleaveMs, fd * this.config.fecK);
+  }
+  /** Frame duration in ms, derived from frameSamples + sampleRate. */
+  get frameDurationMs() {
+    const { frameSamples, sampleRate } = this.config;
+    if (!frameSamples || !sampleRate || sampleRate <= 0) return void 0;
+    return frameSamples / sampleRate * 1e3;
+  }
+  // -----------------------------------------------------------------------
+  // Transitions (Patent Claim 9)
+  // -----------------------------------------------------------------------
+  /** idle → unicast: player subscribes to this track. */
+  subscribe() {
+    if (this.#state !== "idle") return;
+    this.#transition("unicast");
+    if (this.config.trackType === "audio") {
+      const latency = this.audioLatencyMs;
+      if (latency !== void 0) {
+        this.#manager.mmtp?.onTrackEvent?.(this.config.trackName, { type: "latency", latencyMs: latency }, this.config);
+      }
+    }
+  }
+  /** unicast → joining: multicast/AMT capability detected, join in progress. */
+  joinStarted() {
+    if (this.#state !== "unicast") return;
+    this.#transition("joining");
+    this.#armFec();
+  }
+  /**
+   * any non-fallback state → unicast-fallback. Used when the SSM bridge is
+   * absent (vanilla Chromium / no extension) and the host falls back to a
+   * MoQ unicast subscription per track. Terminal-ish: activateMulticast,
+   * failbackAll, and transportFailed are no-ops while in this state.
+   *
+   * Fires fec-setup so the per-track repair worker spins up — repair packets
+   * still flow over the MoQ repair-track subscription, so FEC source+repair
+   * can converge as in the multicast path.
+   *
+   * Audio latency is NOT re-emitted here: subscribe() already fires latency
+   * once on the idle → unicast edge, and enterUnicastFallback is only ever
+   * reached from a non-idle state (SessionManager skips idle sessions).
+   */
+  enterUnicastFallback() {
+    if (this.#state === "unicast-fallback") return;
+    this.#clearHysteresis();
+    this.#transition("unicast-fallback");
+    this.#suppress();
+    this.#armFec();
+  }
+  /**
+   * unicast-fallback → unicast. Called when the SSM bridge appears mid-session
+   * (extension installed after fallback engaged). Host first aborts the fallback
+   * drainers, then transitions sessions back to unicast so the regular
+   * multicast/AMT preference chain can take over via joinStarted().
+   */
+  exitUnicastFallback() {
+    if (this.#state !== "unicast-fallback") return;
+    this.#transition("unicast");
+    this.#unsuppress();
+  }
+  /**
+   * joining → multicast or amt: RAP received on the joined transport (Claim 9d).
+   * Resets audio worklet, then suppresses MoQ.
+   */
+  rapReceived(mode) {
+    if (this.#state !== "joining") return;
+    this.#previousPrimary = mode;
+    this.#transition(mode);
+    if (this.config.trackType === "audio") {
+      this.#manager.mmtp?.onTrackEvent?.(this.config.trackName, { type: "reset" }, this.config);
+    }
+    this.#suppress();
+  }
+  /** multicast/amt → failing: loss detected, start hysteresis timer (Claim 9f). */
+  lossDetected() {
+    if (this.#state !== "multicast" && this.#state !== "amt") return;
+    this.#previousPrimary = this.#state;
+    this.#transition("failing");
+    const hysteresisMs = computeFecLossWindowMs(
+      this.config.fecInterleaveMs,
+      this.config.fecK,
+      this.config.fecReorderToleranceMs
+    );
+    this.#hysteresisTimer = setTimeout(() => {
+      this.hysteresisExpired();
+    }, hysteresisMs);
+  }
+  /** failing → previous primary: loss recovered within hysteresis window. */
+  lossRecovered() {
+    if (this.#state !== "failing") return;
+    this.#clearHysteresis();
+    if (this.#previousPrimary) {
+      this.#transition(this.#previousPrimary);
+    }
+  }
+  /**
+   * Transport failed (AMT relay down, multicast interface gone).
+   * Try next transport in preference chain.
+   */
+  transportFailed() {
+    this.#clearHysteresis();
+    if (this.#state === "unicast-fallback") return;
+    const current = this.#previousPrimary ?? this.transport;
+    const prefs = this.config.preferredTransports;
+    const currentIdx = current ? prefs.indexOf(current) : -1;
+    const nextMode = prefs[currentIdx + 1];
+    if (nextMode !== void 0 && nextMode !== "moq") {
+      this.#previousPrimary = nextMode;
+      this.#transition("joining");
+      this.#unsuppress();
+      return;
+    }
+    const from = this.#state;
+    this.#previousPrimary = null;
+    this.#transition("unicast");
+    this.#disarmFec();
+    this.#unsuppress();
+    if (from !== "unicast" && this.config.trackType === "audio") {
+      this.#manager.mmtp?.onTrackEvent?.(this.config.trackName, { type: "reset" }, this.config);
+    }
+  }
+  /** Hysteresis expired → failback to next transport (Claim 9g). */
+  hysteresisExpired() {
+    if (this.#state !== "failing") return;
+    this.#clearHysteresis();
+    this.transportFailed();
+  }
+  /** → idle: player unsubscribes / tab close / cleanup. */
+  unsubscribe() {
+    this.#clearHysteresis();
+    if (this.#state !== "idle") {
+      this.#transition("idle");
+      this.#unsuppress();
+    }
+  }
+  /** True when SessionManager.enterUnicastFallback put this track into the
+   *  host-driven unicast subscription mode. Host can iterate sessions to
+   *  decide whether to keep its fallback drainer alive across MediaRouter
+   *  arbitration events. */
+  get isUnicastFallback() {
+    return this.#state === "unicast-fallback";
+  }
+  /**
+   * True while this track owns a FEC decoder (fec-setup fired, fec-teardown
+   * not yet). Stays true across a takeover timeout that parked the session in
+   * `unicast`; SessionManager.failbackAll uses it to release such sessions.
+   */
+  get isFecArmed() {
+    return this.#fecArmed;
+  }
+  /**
+   * Start the deadline a `joining` entry deferred while the join was inactive
+   * (SessionManager.joinActive). The track gets the FULL deadline from here,
+   * because that is when media can first arrive. No-op outside `joining` and
+   * when a deadline is already running, so it never shortens or restarts one.
+   *
+   * The `joinActive` guard is what makes this safe to call from anywhere: a
+   * track parked in `joining` with a deferred (null) timer satisfies the other
+   * two, so without it a host calling this while the join is still inactive
+   * would arm the exact deadline the gate exists to defer -- silently
+   * reinstating BLO-34289. It is a no-op for the internal caller, which writes
+   * `#joinActive = true` before iterating the sessions.
+   */
+  armDeferredJoinDeadline() {
+    if (this.#state !== "joining" || this.#joinDeadlineTimer !== null) return;
+    if (!this.#manager.joinActive) return;
+    this.#armJoinDeadline(this.#manager.takeoverDeadlineMs);
+  }
+  dispose() {
+    this.#clearHysteresis();
+    this.#clearJoinDeadline();
+    this.#state = "idle";
+    this.#subscription = null;
+    this.#disarmFec();
+  }
+  // -----------------------------------------------------------------------
+  // Internal
+  // -----------------------------------------------------------------------
+  #transition(to, opts) {
+    const from = this.#state;
+    if (from === to) return;
+    const joinDeadlineMs = to === "joining" ? this.#manager.takeoverDeadlineMs : void 0;
+    this.#state = to;
+    if (from === "joining") this.#clearJoinDeadline();
+    if (joinDeadlineMs !== void 0 && this.#manager.joinActive) {
+      this.#armJoinDeadline(joinDeadlineMs);
+    }
+    const fecActive = (s) => s === "joining" || s === "multicast" || s === "amt" || s === "failing" || s === "unicast-fallback";
+    if (!fecActive(to) && !opts?.retainFec) this.#disarmFec();
+    this.#manager.callbacks?.onStateChange?.(this.config.trackName, from, to);
+  }
+  #clearHysteresis() {
+    if (this.#hysteresisTimer !== null) {
+      clearTimeout(this.#hysteresisTimer);
+      this.#hysteresisTimer = null;
+    }
+  }
+  #armJoinDeadline(deadlineMs) {
+    this.#clearJoinDeadline();
+    if (deadlineMs === 0) return;
+    this.#joinDeadlineTimer = setTimeout(() => {
+      this.#joinDeadlineTimer = null;
+      if (this.#state !== "joining") return;
+      this.#transition("unicast", { retainFec: true });
+      this.#manager.callbacks?.onTakeoverTimeout?.(this.config.trackName);
+    }, deadlineMs);
+  }
+  #clearJoinDeadline() {
+    if (this.#joinDeadlineTimer !== null) {
+      clearTimeout(this.#joinDeadlineTimer);
+      this.#joinDeadlineTimer = null;
+    }
+  }
+  /** Fire fec-setup exactly once per FEC epoch. */
+  #armFec() {
+    if (this.#fecArmed) return;
+    this.#fecArmed = true;
+    this.#manager.mmtp?.onTrackEvent?.(this.config.trackName, { type: "fec-setup" }, this.config);
+  }
+  /** Fire fec-teardown for an armed decoder; no-op when none is armed. */
+  #disarmFec() {
+    if (!this.#fecArmed) return;
+    this.#fecArmed = false;
+    this.#manager.mmtp?.onTrackEvent?.(this.config.trackName, { type: "fec-teardown" }, this.config);
+  }
+  /** Fire onSuppress(true) exactly once per suppression epoch. */
+  #suppress() {
+    if (this.#suppressFired) return;
+    this.#suppressFired = true;
+    this.#manager.callbacks?.onSuppress?.(this.config.trackName, true);
+  }
+  /** Unwind an outstanding suppression; no-op when none is outstanding. */
+  #unsuppress() {
+    if (!this.#suppressFired) return;
+    this.#suppressFired = false;
+    this.#manager.callbacks?.onSuppress?.(this.config.trackName, false);
+  }
+};
+var MAX_TAKEOVER_DEADLINE_MS = 2147483647;
+var JOIN_DEFER_WARN_MS = 3e4;
+var SessionManager = class {
+  constructor(poolOptions) {
+    this.sessions = /* @__PURE__ */ new Map();
+    this.callbacks = null;
+    this.#takeoverDeadlineMs = void 0;
+    this.#joinActive = true;
+    this.#joinDeferWarnTimer = null;
+    this.pool = new TransportPool(poolOptions);
+    this.pool.onSubscriptionFailed((sub) => {
+      for (const trackName of sub.consumers) {
+        const session = this.sessions.get(trackName);
+        if (session) session.transportFailed();
+      }
+    });
+  }
+  #takeoverDeadlineMs;
+  #joinActive;
+  #joinDeferWarnTimer;
+  /**
+   * Takeover deadline (BLO-9413/D9): the time a session may sit in `joining`
+   * without a RAP before returning to `unicast` and firing onTakeoverTimeout.
+   * MoQ is never suppressed during `joining`, so expiry abandons the takeover
+   * without a playback glitch. The host derives it from the catalog (RAP
+   * cadence from groupDurationTicks/timescale plus the signaled FEC delivery
+   * window or reorder tolerance) and sets it before addTrack(). There is no
+   * default: an unset value fails addTrack() closed, and reading the getter
+   * before assignment throws the same way, so no host ever holds a
+   * `number | undefined` it could coalesce back into a default.
+   * `hasTakeoverDeadline` answers whether one was admitted. A declared 0
+   * disables the deadline. The value is an integer number of milliseconds:
+   * setTimeout truncates fractions, so a host that divides ticks by a
+   * timescale must round before assigning.
+   *
+   * Assignment validates, so the diagnostic lands at the host's own call site.
+   * That is what bounds the blast radius: `joining` is entered from
+   * joinStarted(), from the transportFailed() failover branch -- itself
+   * reachable from a setTimeout via hysteresisExpired(), where no caller could
+   * catch a throw -- and from the activateMulticast()/activateAmt()/pool-failure
+   * loops, where a throw on one session would abandon its siblings mid-loop
+   * (the split-brain those loops exist to prevent). Refusing a bad value at
+   * assignment means no host mutation can make an already-admitted session
+   * throw out of a transport edge.
+   */
+  get takeoverDeadlineMs() {
+    return this.#requireTakeoverDeadlineMs();
+  }
+  set takeoverDeadlineMs(value) {
+    if (!Number.isInteger(value) || value < 0 || value > MAX_TAKEOVER_DEADLINE_MS) {
+      throw new Error(
+        `[SessionManager] takeoverDeadlineMs must be an integer from 0 to ${MAX_TAKEOVER_DEADLINE_MS} (0 disables it, larger values overflow setTimeout); got ${String(value)}`
+      );
+    }
+    this.#takeoverDeadlineMs = value;
+  }
+  /** True once the host has admitted a deadline; a declared 0 counts. */
+  get hasTakeoverDeadline() {
+    return this.#takeoverDeadlineMs !== void 0;
+  }
+  /**
+   * Whether the transport the joining tracks are waiting on is actually
+   * subscribed. The takeover deadline is a media-arrival budget and media
+   * cannot arrive before the join exists, so while this is false, entering
+   * `joining` arms no deadline; flipping it true starts the FULL deadline for
+   * every track already parked there.
+   *
+   * Default true, which is the arm-on-`joining` behaviour every host had
+   * before: a host that only calls joinStarted() after its own join resolves
+   * (moqtail-private's player, post-BLO-33339) is already at the right edge and
+   * needs no gate. A host that arms joinStarted() up front — to have FEC
+   * decoders ready before the first datagram — sets this false before addTrack()
+   * and true when its subscribe settles. Charging a slow subscribe (bridge
+   * reconnect, AMT relay handshake) against the media budget expired the
+   * deadline before the subscription existed and abandoned the join on the
+   * happy path. BLO-34289.
+   *
+   * The deadline is a media budget (group cadence plus FEC delivery window) and
+   * budgets nothing for reaching the stream, so ideally it starts at
+   * MulticastTransport.onDataPlaneLive, the join's first accepted packet. Over
+   * AMT that is measurably later than a settled subscribe: the subscribe
+   * settles once the gateway has sent its Membership Update, and the relay's
+   * upstream join plus a path RTT (0.4-0.8 s measured to the prod relay) still
+   * precede the first packet. But RFC 7450 gives a gateway no signal that the
+   * relay has traffic for its (S,G), so a join whose source never sends never
+   * reaches that edge. Starting the deadline there is therefore sound only when
+   * the provider bounds the join phase itself, with a typed subscription error
+   * for a join that delivers nothing (MulticastTransport forwards it to
+   * onFailback). A host whose provider makes no such guarantee flips this true
+   * when the subscribe settles and accepts that join latency is charged to the
+   * media budget; holding it until the first packet would park a silent join
+   * in `joining` forever.
+   *
+   * The flag tracks the host's primary join, not per-track transport state. A
+   * track that fails over to the next transport in its own chain while this is
+   * false (transportFailed's failover branch also enters `joining`) has that
+   * deadline gated on the primary join activating, not on its own transport.
+   * Under the documented usage -- false once at setup, true once the subscribe
+   * settles -- the two coincide.
+   *
+   * The gate is on the ENTRY into `joining`, and false cannot take back a
+   * deadline already running: the `true -> false` edge arms the warn below and
+   * clears nothing. So set it false BEFORE the `joining` entry it is meant to
+   * gate. A host that instead flipped it false after a `transportFailed()`
+   * failover had already entered `joining` would leave the full deadline
+   * counting against a subscribe that had not begun -- BLO-34289 again, on the
+   * failover edge. Clearing running deadlines on that edge is deliberately NOT
+   * done: this flag is manager-wide, so one transport's brief false would
+   * cancel an unrelated track's live deadline and then re-arm it at FULL length
+   * on the next activation (armDeferredJoinDeadline sees `joining` + a null
+   * timer and cannot tell a cleared deadline from a deferred one). Every
+   * unrelated transport blip would restart the whole budget, so under repeated
+   * failover a track that should have timed out is extended indefinitely and
+   * never advances. Only a false that never returns true loses the timer
+   * outright, and JOIN_DEFER_WARN_MS already covers that.
+   *
+   * Leaving this false is not free: see JOIN_DEFER_WARN_MS.
+   */
+  get joinActive() {
+    return this.#joinActive;
+  }
+  set joinActive(active) {
+    const wasActive = this.#joinActive;
+    this.#joinActive = active;
+    if (!active) {
+      if (wasActive) this.#armJoinDeferWarn();
+      return;
+    }
+    this.#clearJoinDeferWarn();
+    if (wasActive) return;
+    for (const [, session] of this.sessions) session.armDeferredJoinDeadline();
+  }
+  #armJoinDeferWarn() {
+    this.#joinDeferWarnTimer = setTimeout(() => {
+      this.#joinDeferWarnTimer = null;
+      const deferred = [...this.sessions.values()].filter((s) => s.state === "joining").length;
+      console.warn(
+        `[SessionManager] joinActive has been false for ${JOIN_DEFER_WARN_MS} ms and ${deferred} track(s) sit in 'joining' with no takeover deadline. Set joinActive = true when the subscribe settles, on every exit path including failures, or these tracks never time out, never release their FEC decoders, and never advance to the next transport.`
+      );
+    }, JOIN_DEFER_WARN_MS);
+  }
+  #clearJoinDeferWarn() {
+    if (this.#joinDeferWarnTimer === null) return;
+    clearTimeout(this.#joinDeferWarnTimer);
+    this.#joinDeferWarnTimer = null;
+  }
+  /** Narrow to MMTP callbacks (onTrackEvent). Safe — optional chaining handles PIM-only consumers. */
+  get mmtp() {
+    return this.callbacks;
+  }
+  // -----------------------------------------------------------------------
+  // Track management
+  // -----------------------------------------------------------------------
+  /**
+   * The admitted takeover deadline. Throws only when the host never set one,
+   * every other invalid value being refused by the setter, and returns a
+   * declared 0 as 0. The getter and addTrack() both route through it, so a
+   * session cannot exist without an admitted deadline, which is what makes
+   * the #transition() read unable to throw on an already-admitted session.
+   */
+  #requireTakeoverDeadlineMs() {
+    const value = this.#takeoverDeadlineMs;
+    if (value === void 0) {
+      throw new Error(
+        "[SessionManager] takeoverDeadlineMs is unset; set a catalog-derived takeover deadline (0 disables it) before adding tracks"
+      );
+    }
+    return value;
+  }
+  /** Add a track session from catalog config. */
+  addTrack(config) {
+    if (this.sessions.has(config.trackName)) {
+      throw new Error(`[SessionManager] Track "${config.trackName}" already exists`);
+    }
+    this.#requireTakeoverDeadlineMs();
+    const session = new TrackSession(config, this);
+    this.sessions.set(config.trackName, session);
+    return session;
+  }
+  /** Remove a track session. Releases subscription with grace period. */
+  removeTrack(trackName) {
+    const session = this.sessions.get(trackName);
+    if (!session) return;
+    session.unsubscribe();
+    const subKey = session.config.multicastKey ?? session.config.moqTrackName;
+    if (subKey) this.pool.releaseSubscription(subKey, trackName);
+    session.dispose();
+    this.sessions.delete(trackName);
+  }
+  // -----------------------------------------------------------------------
+  // Atomic multi-track operations
+  // -----------------------------------------------------------------------
+  /**
+   * All tracks with multicast RAP → multicast state (atomic).
+   * Called when MediaRouter fires onSourceSwitch('multicast').
+   * Prevents split-brain between video and audio.
+   *
+   * A takeover deadline can return a track from `joining` to `unicast` while
+   * the multicast socket keeps delivering packets and the track keeps its FEC
+   * decoder armed. If a valid RAP arrives later, that late-RAP edge suppresses
+   * unicast and promotes multicast without a second fec-setup.
+   */
+  activateMulticast() {
+    for (const [, session] of this.sessions) {
+      if (session.state === "unicast") {
+        session.joinStarted();
+      }
+      if (session.state === "joining") {
+        session.rapReceived("multicast");
+      }
+    }
+  }
+  /**
+   * All tracks with AMT RAP → amt state (atomic).
+   */
+  activateAmt() {
+    for (const [, session] of this.sessions) {
+      if (session.state === "unicast") {
+        session.joinStarted();
+      }
+      if (session.state === "joining") {
+        session.rapReceived("amt");
+      }
+    }
+  }
+  /**
+   * All tracks → unicast (failback, atomic).
+   * Called when MulticastManager fires onFailback().
+   * unicast-fallback sessions are skipped — the host owns those subscriptions
+   * and they must drain uninterrupted across transport-state events.
+   *
+   * Coherence invariant (BLO-9413): after this returns, every non-fallback
+   * session is `unicast` (or `idle`), unsuppressed, and without a FEC decoder.
+   * unsubscribe() unwinds any outstanding suppression regardless of the state
+   * it tears down from (`failing` included; see TrackSession.#suppressFired),
+   * and a session that a takeover timeout parked in `unicast` with its decoder
+   * still armed is cycled too, because this transport edge is what releases
+   * that decoder (unsubscribe fires fec-teardown).
+   */
+  failbackAll() {
+    for (const [, session] of this.sessions) {
+      const parkedWithFec = session.state === "unicast" && session.isFecArmed;
+      if (parkedWithFec || session.state !== "idle" && session.state !== "unicast" && session.state !== "unicast-fallback") {
+        session.unsubscribe();
+        session.subscribe();
+      }
+    }
+  }
+  /**
+   * All tracks → unicast-fallback (atomic).
+   * Called by the host when the multicast gateway is absent and
+   * the player will subscribe to source tracks over MoQ unicast and feed
+   * packets via MulticastManager.feedUnicastSource() (or manager.router
+   * directly). Sessions in this state stay terminal until the host calls
+   * unsubscribe() / disposes the SessionManager.
+   */
+  enterUnicastFallback() {
+    for (const [, session] of this.sessions) {
+      if (session.state === "idle") continue;
+      session.enterUnicastFallback();
+    }
+  }
+  /**
+   * True if any session is currently in unicast-fallback. Hosts use this to
+   * gate `multicastTrack.close()` on failback events — closing the shared
+   * broadcast would kill the host's fallback drainers.
+   */
+  hasActiveFallback() {
+    for (const [, session] of this.sessions) {
+      if (session.isUnicastFallback) return true;
+    }
+    return false;
+  }
+  /**
+   * All fallback tracks → unicast (atomic).
+   * Called when the SSM bridge appears mid-session and the host has aborted
+   * the fallback drainers. The session re-enters the regular preference chain
+   * via joinStarted() (issued by the host immediately after).
+   */
+  exitUnicastFallback() {
+    for (const [, session] of this.sessions) {
+      if (session.isUnicastFallback) session.exitUnicastFallback();
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Cleanup lifecycle
+  // -----------------------------------------------------------------------
+  /** Tab closed — release all subscriptions for this tab (grace period). */
+  tabClosed(tabId) {
+    for (const [trackName, session] of this.sessions) {
+      session.unsubscribe();
+      this.pool.releaseAllForConsumer(trackName);
+    }
+  }
+  /** Bridge WebTransport connection dropped — same as tab close. */
+  bridgeDisconnected() {
+    this.tabClosed("bridge");
+  }
+  /**
+   * Track selection changed (user or ABR).
+   * Old track released (grace period), new track subscribed.
+   */
+  trackSelectionChanged(oldTrackName, newConfig) {
+    this.removeTrack(oldTrackName);
+    const session = this.addTrack(newConfig);
+    session.subscribe();
+  }
+  // -----------------------------------------------------------------------
+  // Query
+  // -----------------------------------------------------------------------
+  /** Get a track session by name. */
+  getTrack(trackName) {
+    return this.sessions.get(trackName);
+  }
+  // -----------------------------------------------------------------------
+  // Cleanup
+  // -----------------------------------------------------------------------
+  dispose() {
+    this.#clearJoinDeferWarn();
+    for (const [, session] of this.sessions) {
+      session.dispose();
+    }
+    this.sessions.clear();
+    this.pool.dispose();
+    this.callbacks = null;
+  }
+};
+export {
+  JOIN_DEFER_WARN_MS,
+  MAX_TAKEOVER_DEADLINE_MS,
+  SessionManager,
+  TrackSession,
+  computeFecDeliveryWindowMediaUnits,
+  computeFecDeliveryWindowMs,
+  computeFecLossWindowMs
+};
+//# sourceMappingURL=track-session.js.map