@blockcast/mmt-container 2.0.1 → 2.1.0-main.36792a9d6614

package/dist/browser-runtime.js

@@ -7457,11 +7457,33 @@ var AdaptiveBitrateController = class {
 };
 
 // node_modules/@blockcast/mmt-base/dist/mmtp.js
+var MMTP_HEADER_SIZE2 = 12;
 var MPU_HEADER_SIZE2 = 8;
 var MPU_LENGTH_FIELD_SIZE2 = 2;
 var MPU_HEADER_REMAINDER_SIZE2 = MPU_HEADER_SIZE2 - MPU_LENGTH_FIELD_SIZE2;
 var MMTP_SIGNALING_PACKET_ID2 = 0;
 var MMTP_PACKET_ID_MAX2 = 65535;
+function readMMTPPacketId2(buffer) {
+  if (buffer.length < MMTP_HEADER_SIZE2)
+    return null;
+  const flags = buffer[0];
+  if ((flags >> 6 & 3) !== 0)
+    return null;
+  let offset = MMTP_HEADER_SIZE2;
+  if ((flags & 32) !== 0) {
+    if (offset + 4 > buffer.length)
+      return null;
+    offset += 4;
+  }
+  if ((flags & 2) !== 0) {
+    if (offset + 4 > buffer.length)
+      return null;
+    const length = buffer[offset + 2] << 8 | buffer[offset + 3];
+    if (offset + 4 + length > buffer.length)
+      return null;
+  }
+  return buffer[2] << 8 | buffer[3];
+}
 
 // node_modules/@blockcast/mmt-base/dist/net-constants.js
 var DEFAULT_AMT_RELAY_PORT2 = 2268;
@@ -8447,6 +8469,205 @@ var TransportManager = class {
 };
 var transportManager = new TransportManager();
 
+// node_modules/@blockcast/mmt-transport/dist/multicast-receiver-gateway.js
+var REGISTRY = /* @__PURE__ */ Symbol.for("@blockcast/mmt-transport/native-provider-registry/v1");
+var USER_AGENT_VERIFIED = /* @__PURE__ */ Symbol.for("@blockcast/mmt-transport/user-agent-verified/v1");
+var INTEGRITY_SCHEME = "manifest-ed25519-2";
+var MulticastError = class extends Error {
+  code;
+  constructor(code, message, cause) {
+    super(message, cause === void 0 ? void 0 : { cause });
+    this.name = "MulticastError";
+    this.code = code;
+  }
+};
+function datagramsOf(chunk) {
+  const list = Array.isArray(chunk) ? chunk : chunk?.datagrams ?? [];
+  const out = [];
+  for (const d of list) {
+    const data = d instanceof Uint8Array || d instanceof ArrayBuffer ? d : d?.data;
+    if (data instanceof Uint8Array)
+      out.push(data);
+    else if (data instanceof ArrayBuffer)
+      out.push(new Uint8Array(data));
+  }
+  return out;
+}
+function reasonOf(value) {
+  return typeof value === "object" && value !== null && "reason" in value ? value.reason : value;
+}
+function registry() {
+  const g = globalThis;
+  if (g[REGISTRY] === void 0) {
+    const providers = /* @__PURE__ */ new WeakSet();
+    const byScope = /* @__PURE__ */ new WeakMap();
+    Object.defineProperty(g, REGISTRY, {
+      value: Object.freeze({
+        isProvider: (x) => typeof x === "object" && x !== null && providers.has(x),
+        providerFor: (scope) => {
+          let provider = byScope.get(scope);
+          if (provider === void 0) {
+            provider = createProvider(scope);
+            providers.add(provider);
+            byScope.set(scope, provider);
+          }
+          return provider;
+        }
+      }),
+      writable: false,
+      configurable: false,
+      enumerable: false
+    });
+  }
+  return g[REGISTRY];
+}
+function resolveMulticastGateway(scope = globalThis) {
+  const s = scope;
+  if (typeof s.MulticastReceiver === "function")
+    return registry().providerFor(scope);
+  if (typeof s.multicast?.subscribe === "function")
+    return s.multicast;
+  return void 0;
+}
+function isUserAgentVerifiedGateway(gateway) {
+  return registry().isProvider(gateway);
+}
+function userAgentVerifiedIngress(ingress, gateway) {
+  if (isUserAgentVerifiedGateway(gateway))
+    return { ...ingress, admittedBy: USER_AGENT_VERIFIED };
+  if (!("admittedBy" in ingress))
+    return ingress;
+  const { admittedBy: _, ...rest } = ingress;
+  return rest;
+}
+function unsupported(message, cause) {
+  return new MulticastError("capability-unsupported", message, cause);
+}
+function createProvider(scope) {
+  const Receiver = scope.MulticastReceiver;
+  let gate = null;
+  return {
+    capabilities: () => Promise.resolve({ consumeModes: ["bytes"] }),
+    subscribe: async (config) => {
+      const c = config;
+      if (c.consume !== "bytes")
+        throw unsupported(`consume mode ${String(c.consume)} is not supported`);
+      const origin = c.origin ?? "ip-multicast";
+      if (origin !== "ip-multicast" && !(origin === "amt" && c.discovery === "driad")) {
+        throw unsupported(`origin ${String(origin)} is not supported by MulticastReceiver`);
+      }
+      if (c.relay !== void 0)
+        throw unsupported("MulticastReceiver picks its own AMT relay");
+      if (!c.source)
+        throw unsupported("MulticastReceiver needs an SSM source");
+      if (c.senderAddress !== void 0 && c.senderAddress !== c.source) {
+        throw unsupported("MulticastReceiver filters by source only");
+      }
+      const options = { sourceAddress: c.source, groupAddress: c.group, localPort: c.port };
+      if (gate !== null)
+        await gate;
+      let rx;
+      try {
+        rx = new Receiver(options);
+      } catch (error) {
+        throw unsupported("MulticastReceiver refused the request", error);
+      }
+      const opened = rx.opened;
+      if (gate === null)
+        gate = opened.then(() => void 0, () => void 0);
+      return openSubscription(rx, opened, options, c.packetIds);
+    }
+  };
+}
+async function openSubscription(rx, openedPromise, options, packetIds) {
+  let opened;
+  try {
+    opened = await openedPromise;
+  } catch (error) {
+    throw new MulticastError("subscription-failed", "MulticastReceiver did not open", error);
+  }
+  if (rx.integrityScheme !== INTEGRITY_SCHEME) {
+    await rx.close();
+    throw unsupported(`integrity scheme ${String(rx.integrityScheme)} is not ${INTEGRITY_SCHEME}`);
+  }
+  const events = new EventTarget();
+  let state = "connected";
+  let filter = packetIds?.length ? new Set(packetIds) : null;
+  let closing = false;
+  const setState = (next) => {
+    if (state === next)
+      return;
+    state = next;
+    events.dispatchEvent(new CustomEvent("state", { detail: next }));
+  };
+  const sourceAddress = options.sourceAddress;
+  const subscription = {
+    id: `${options.sourceAddress}|${options.groupAddress}|${options.localPort}`,
+    get state() {
+      return state;
+    },
+    delivery: "datagram",
+    eventTypes: Object.freeze(["bytes", "packets", "state", "error"]),
+    setPacketIds(ids) {
+      filter = ids.length ? new Set(ids) : null;
+    },
+    addEventListener: events.addEventListener.bind(events),
+    removeEventListener: events.removeEventListener.bind(events),
+    async unsubscribe() {
+      closing = true;
+      await rx.close();
+      setState("closed");
+    }
+  };
+  void (async () => {
+    const reader = opened.readable.getReader();
+    try {
+      for (; ; ) {
+        const { value, done } = await reader.read();
+        if (done)
+          break;
+        const packets = [];
+        for (const data of datagramsOf(value)) {
+          if (filter !== null) {
+            const id = readMMTPPacketId2(data);
+            if (id === null || !filter.has(id))
+              continue;
+          }
+          const copy = data.slice().buffer;
+          packets.push(copy);
+          events.dispatchEvent(Object.assign(new CustomEvent("bytes", { detail: copy }), { sourceAddress }));
+        }
+        if (packets.length > 0)
+          events.dispatchEvent(new CustomEvent("packets", { detail: packets }));
+      }
+    } catch {
+    }
+  })();
+  void rx.closed.then((value) => {
+    const reason = reasonOf(value);
+    if (!closing) {
+      if (reason === "consent-withdrawn") {
+        events.dispatchEvent(new CustomEvent("error", {
+          detail: new MulticastError("origin-not-trusted", "multicast consent withdrawn")
+        }));
+      } else if (reason === "oversubscribed" || reason === "network") {
+        events.dispatchEvent(new CustomEvent("error", {
+          detail: new MulticastError("subscription-failed", `MulticastReceiver closed: ${reason}`)
+        }));
+      }
+    }
+    setState("closed");
+  }, (error) => {
+    if (!closing) {
+      events.dispatchEvent(new CustomEvent("error", {
+        detail: new MulticastError("subscription-failed", "MulticastReceiver failed", error)
+      }));
+    }
+    setState("closed");
+  });
+  return subscription;
+}
+
 // node_modules/@blockcast/mmt-transport/dist/moqt-priority.js
 var MAX_MOQT_PRIORITY = 255;
 function moqtPriority(value, field) {
@@ -8733,9 +8954,9 @@ function validateTemplatePair(mediaUriTemplate, mediaObjectTemplate, path) {
 }
 function validateMmtpDashTemplate(template, path) {
   const variables = [...template.matchAll(TEMPLATE_VARIABLE)].map((match) => match[1]);
-  const unsupported = variables.find((variable) => variable !== "Number" && variable !== "RepresentationID");
-  if (unsupported !== void 0) {
-    throw new Error(`${path} contains unsupported MMTP-backed DASH template variable $${unsupported}$`);
+  const unsupported2 = variables.find((variable) => variable !== "Number" && variable !== "RepresentationID");
+  if (unsupported2 !== void 0) {
+    throw new Error(`${path} contains unsupported MMTP-backed DASH template variable $${unsupported2}$`);
   }
   if (variables.filter((variable) => variable === "Number").length !== 1) {
     throw new Error(`${path} must contain exactly one $Number$ for MMTP-backed DASH`);
@@ -17098,17 +17319,17 @@ var FECManager = class _FECManager {
 
 // src/mfu-reassembly-policy.ts
 function validateReliableMoqOptionShape(value) {
-  const unsupported = Object.keys(value).filter(
+  const unsupported2 = Object.keys(value).filter(
     (key) => key !== "transport" && key !== "startsAtRandomAccessGroup"
   );
-  if (unsupported.length > 0) {
-    if (unsupported.includes("maxRacingGroups")) {
+  if (unsupported2.length > 0) {
+    if (unsupported2.includes("maxRacingGroups")) {
       throw new Error(
         "[MFU reassembly] maxRacingGroups was removed; reliable MoQ completion is transport-owned"
       );
     }
     throw new Error(
-      `[MFU reassembly] unsupported reliable MoQ option(s): ${unsupported.join(", ")}`
+      `[MFU reassembly] unsupported reliable MoQ option(s): ${unsupported2.join(", ")}`
     );
   }
   const startsAtRandomAccessGroup = value["startsAtRandomAccessGroup"];
@@ -17152,12 +17373,12 @@ function assertValidMfuReassemblyPolicy(policy) {
     return;
   }
   if (value["transport"] === "datagram") {
-    const unsupported = Object.keys(value).filter(
+    const unsupported2 = Object.keys(value).filter(
       (key) => key !== "transport" && key !== "deadlineMs"
     );
-    if (unsupported.length > 0) {
+    if (unsupported2.length > 0) {
       throw new Error(
-        `[MFU reassembly] unsupported datagram option(s): ${unsupported.join(", ")}`
+        `[MFU reassembly] unsupported datagram option(s): ${unsupported2.join(", ")}`
       );
     }
     assertValidDatagramDeadline(value["deadlineMs"]);
@@ -22431,6 +22652,14 @@ function isRouterDebugEnabled() {
 function debugRouter(message) {
   if (isRouterDebugEnabled()) console.debug(message);
 }
+var KEYFRAME_OVERLAY_EXTENSION_TYPE = 35585;
+function keyframeOverlaySsId(header) {
+  const ext = header.extension;
+  if (ext?.type !== KEYFRAME_OVERLAY_EXTENSION_TYPE || ext.data.length !== 4) return void 0;
+  return new DataView(ext.data.buffer, ext.data.byteOffset, 4).getUint32(0);
+}
+var OVERLAY_OFFSET_MPUS = 16;
+var OVERLAY_MOQ_HORIZON_BLOCKS = 64;
 function assertStreamIdentity(role, stream) {
   if (stream === void 0 || !Number.isInteger(stream.packetId) || stream.packetId <= MMTP_SIGNALING_PACKET_ID || typeof stream.catalogTrackName !== "string" || stream.catalogTrackName.length === 0) {
     throw new Error(
@@ -22647,6 +22876,26 @@ var MmtpRouter = class {
   #packetIdRoles = /* @__PURE__ */ new Map();
   /** Explicit catalog ownership for dedicated repair-track packet IDs. */
   #repairOwnersByPacketId = /* @__PURE__ */ new Map();
+  /** Keyframe-overlay repair PID → the source its FEC instance protects
+   *  (draft-ramadan-mmt-fec-02 7.4.1). Never an owner in
+   *  #repairOwnersByPacketId: the overlay is decoded as its own instance. */
+  #overlayLegs = /* @__PURE__ */ new Map();
+  /** Keyframe-overlay repair track names, which name a leg too: a catalog
+   *  may state no PID for it (learned at subscribe time). */
+  #overlayRepairNames = /* @__PURE__ */ new Map();
+  /** Installed overlay instances, by overlay repair PID (opt-in only). */
+  #overlays = /* @__PURE__ */ new Map();
+  #overlayRecoveredObservers = /* @__PURE__ */ new Set();
+  /** Streams whose recovered sequence the base path ever re-stamped. */
+  #restampedStreams = /* @__PURE__ */ new Set();
+  #overlayStats = {
+    repairDropped: 0,
+    ownerRefused: 0,
+    recovered: 0,
+    restarts: 0,
+    unsequencedDropped: 0,
+    protectedDropped: 0
+  };
   /** Callback fired when a delta-track FEC block completes or fails. */
   #onDeltaBlockCompleteCb = null;
   // Debug counters
@@ -22843,6 +23092,7 @@ var MmtpRouter = class {
       this.#fecManager.onSourceDiscontinuity = (packetId, catalogTrackName) => {
         this.#parser.markFecDiscontinuity(packetId, catalogTrackName);
         this.#requestFecPoke(packetId, catalogTrackName);
+        this.resetKeyframeOverlays(packetId, catalogTrackName);
       };
       this.#fecManager.onBlockComplete = (sbn, packetId, catalogTrackName) => {
         this.#mseAssemblerFor(packetId, catalogTrackName)?.completeBlock(sbn);
@@ -23165,13 +23415,287 @@ var MmtpRouter = class {
   /** Replace catalog-derived repair ownership before a catalog reconfiguration. */
   clearRepairPacketIdOwners() {
     this.#repairOwnersByPacketId.clear();
+    this.#overlayLegs.clear();
+    this.#overlayRepairNames.clear();
   }
-  /** Bind one dedicated repair-track PID to its authoritative media PID. */
+  /** Bind one dedicated repair-track PID to its authoritative media PID. A
+   *  known keyframe-overlay PID is refused, and counted: its symbols belong to
+   *  the overlay instance, never to the source's base decoder (mmt-02 7.4.4). */
   setRepairPacketIdOwner(repairPacketId, ownerPacketId) {
+    if (this.#overlayLegs.has(repairPacketId)) {
+      this.#overlayStats.ownerRefused++;
+      return;
+    }
     const owners = this.#repairOwnersByPacketId.get(repairPacketId) ?? /* @__PURE__ */ new Set();
     owners.add(ownerPacketId);
     this.#repairOwnersByPacketId.set(repairPacketId, owners);
   }
+  /**
+   * Record a keyframe-overlay repair leg (draft-ramadan-mmt-fec-02 7.4): its
+   * PID, the source it protects, and its repair track name. Either one names
+   * the leg, so a catalog that states no PID (learned at subscribe time) is
+   * covered by the name. Overlay repair is then never resolved to a base
+   * owner, on multicast or MoQ. Cleared with the catalog owners
+   * (`clearRepairPacketIdOwners`).
+   */
+  setKeyframeOverlayLeg(repairPacketId, leg) {
+    if (leg.repairTrackName !== void 0) this.#overlayRepairNames.set(leg.repairTrackName, { ...leg });
+    if (repairPacketId === void 0) return;
+    this.#repairOwnersByPacketId.delete(repairPacketId);
+    this.#overlayLegs.set(repairPacketId, { ...leg });
+  }
+  /** The keyframe-overlay leg registered on `repairPacketId`, if any. */
+  keyframeOverlayLeg(repairPacketId) {
+    return this.#overlayLegs.get(repairPacketId);
+  }
+  /**
+   * Overlay counters: repair dropped for want of an installed instance, base
+   * owners refused on an overlay PID, overlay blocks recovered, overlay
+   * restarts, and recovered packets dropped for want of a wire sequence or
+   * for a MoQ symbol on a protected flow (multicast-02 7.2.7).
+   */
+  get keyframeOverlayStats() {
+    return { ...this.#overlayStats };
+  }
+  #isOverlayRepair(repairPacketId, repairTrackName) {
+    return this.#overlayLegs.has(repairPacketId) || repairTrackName !== void 0 && this.#overlayRepairNames.has(repairTrackName);
+  }
+  /**
+   * Install the keyframe overlay decoded on `fec` for a known overlay leg
+   * (draft-ramadan-mmt-fec-02 7.4.4: decoded independently of the base). `fec`
+   * holds the overlay stream under `repairPacketId` and `streamName`. Replaces
+   * an earlier install on the same leg; the returned disposer removes only
+   * this one.
+   */
+  installKeyframeOverlay(repairPacketId, fec, k, streamName) {
+    const leg = this.#overlayLegs.get(repairPacketId);
+    if (!leg) throw new Error(`[MmtpRouter] packetId=${repairPacketId} is no known keyframe-overlay leg`);
+    const inst = {
+      repairPacketId,
+      streamName,
+      leg: { ...leg },
+      fec,
+      k,
+      offsets: /* @__PURE__ */ new Map(),
+      moqBlocks: /* @__PURE__ */ new Set()
+    };
+    this.#overlays.set(repairPacketId, inst);
+    return () => {
+      if (this.#overlays.get(repairPacketId) === inst) this.#overlays.delete(repairPacketId);
+    };
+  }
+  /**
+   * Observe each base block whose RAP MFU fragments a keyframe-overlay
+   * recovery supplied, with the keyframe's FT=0 and FT=1 held
+   * (fec-multicast-00 §6.6). The block is named by the recovered packets'
+   * restored wire sequence through the base SS_ID offset, never by an overlay
+   * coordinate. Called synchronously from the recovered-block route.
+   */
+  addKeyframeOverlayRecoveredObserver(observer) {
+    this.#overlayRecoveredObservers.add(observer);
+    return () => {
+      this.#overlayRecoveredObservers.delete(observer);
+    };
+  }
+  /** Whether an overlay is installed on `repairPacketId`. */
+  hasKeyframeOverlay(repairPacketId) {
+    return this.#overlays.has(repairPacketId);
+  }
+  /**
+   * Start a new epoch of every overlay protecting `sourcePacketId` (its
+   * source restarted): empty overlay stream, no coverage, no offsets.
+   */
+  resetKeyframeOverlays(sourcePacketId, catalogTrackName) {
+    for (const inst of this.#overlaysForSource(sourcePacketId, catalogTrackName)) this.#resetOverlay(inst);
+  }
+  #resetOverlay(inst) {
+    inst.fec.resetTrack(inst.repairPacketId, inst.streamName);
+    inst.last = void 0;
+    inst.offsets.clear();
+    inst.moqBlocks.clear();
+  }
+  #overlaysForSource(sourcePacketId, catalogTrackName) {
+    return [...this.#overlays.values()].filter(({ leg }) => leg.sourcePacketId === sourcePacketId && (catalogTrackName === void 0 || leg.sourceCatalogTrackName === void 0 || leg.sourceCatalogTrackName === catalogTrackName));
+  }
+  /**
+   * The overlay instance a repair packet belongs to, by the track it arrived
+   * on (7.4.2: its PID or its repair track name); null for overlay repair
+   * with no instance installed; undefined for repair of no overlay.
+   */
+  #overlayRepairTarget(repairPacketId, repairTrackName) {
+    const inst = this.#overlays.get(repairPacketId) ?? (repairTrackName === void 0 ? void 0 : [...this.#overlays.values()].find(({ leg }) => leg.repairTrackName === repairTrackName));
+    if (inst) return inst;
+    return this.#isOverlayRepair(repairPacketId, repairTrackName) ? null : void 0;
+  }
+  /** Overlay repair goes to its own instance, never to a base owner, locator
+   *  or decoder; with none installed it is dropped and counted. */
+  #routeOverlayRepair(inst, repairPacketId, packet, header, source) {
+    const repair = inst ? parseMoqRepairFrameWithHeader(packet, header) : null;
+    if (!inst || !repair) {
+      this.#overlayStats.repairDropped++;
+      debugRouter(`[MmtpRouter] Dropping keyframe-overlay repair pid=${repairPacketId}: no overlay instance`);
+      return;
+    }
+    const { fec, repairPacketId: pid, streamName: name } = inst;
+    if (!fec.admitRepairBlockLength(pid, repair.ssbLength, repair.rsbLength, repair.rsId)) return;
+    if (!fec.admitRepairSymbolSize(pid, repair.ssStart, repair.ssbLength, repair.rsId, repair.symbolData.byteLength)) return;
+    const placement = fec.placeIsoRepair(pid, name, repair.ssStart, repair.ssbLength);
+    if (placement.status !== "placed") return;
+    const blockStart = placement.block.start;
+    if (placement.span !== void 0) this.#replayOverlaySources(inst, placement.span.block.start, placement.span.placed);
+    this.#replayOverlaySources(inst, blockStart, placement.placed);
+    if (source === "moq") this.#noteOverlayMoqBlock(inst, blockStart);
+    const alreadyCompleted = fec.isBlockCompleted(blockStart, pid, name);
+    const recovered = fec.feedRepairSymbol(pid, repair.ssStart, repair.ssbLength, repair.rsId, repair.symbolData, name);
+    if (recovered && !alreadyCompleted) this.#routeOverlayRecovered(inst, blockStart, recovered);
+  }
+  #replayOverlaySources(inst, blockStart, placed) {
+    const { fec, repairPacketId: pid, streamName: name } = inst;
+    for (const { ssId, payload } of placed) {
+      if (payload.source === "moq") this.#noteOverlayMoqBlock(inst, blockStart);
+      if (payload.oversized) continue;
+      const alreadyCompleted = fec.isBlockCompleted(blockStart, pid, name);
+      const recovered = fec.feedSourceSymbol(pid, ssId, payload.symbolData, name);
+      if (recovered && !alreadyCompleted) this.#routeOverlayRecovered(inst, blockStart, recovered);
+    }
+  }
+  /**
+   * A source packet that carries a 0x8B01 overlay SS_ID is also a symbol of
+   * every overlay installed for its source, at that SS_ID, with the bytes the
+   * base protects: the packet minus its 4-byte SS_ID trailer, extension
+   * included (7.1, 7.4.3).
+   */
+  #feedOverlaySource(packetId, catalogTrackName, packet, header, sequenceNumber, rapFlag, source) {
+    if (this.#overlays.size === 0) return;
+    const ssId = keyframeOverlaySsId(header);
+    if (ssId === void 0) return;
+    for (const inst of this.#overlaysForSource(packetId, catalogTrackName)) {
+      this.#noteOverlaySsId(inst, ssId, sequenceNumber);
+      const identity = MmtpContainerParser.sourcePacketIdentity(packet, header);
+      if (identity !== null) {
+        inst.offsets.delete(identity.mpuSequenceNumber);
+        inst.offsets.set(identity.mpuSequenceNumber, ssId - sequenceNumber >>> 0);
+        if (inst.offsets.size > OVERLAY_OFFSET_MPUS) inst.offsets.delete(inst.offsets.keys().next().value);
+      }
+      const { fec, repairPacketId: pid, streamName: name } = inst;
+      const symbolData = packet.subarray(0, packet.length - 4);
+      const oversized = !fec.isoSourceFits(pid, symbolData.length);
+      const coords = fec.locateIsoSource(pid, name, ssId);
+      if (coords === null) {
+        fec.holdIsoSource(pid, name, ssId, {
+          symbolData,
+          source,
+          oversized,
+          evidence: sourceSymbolEvidence(packet, header, rapFlag, sequenceNumber)
+        });
+        continue;
+      }
+      if (source === "moq") this.#noteOverlayMoqBlock(inst, coords.sbn);
+      if (oversized) continue;
+      const alreadyCompleted = fec.isBlockCompleted(coords.sbn, pid, name);
+      const recovered = fec.feedSourceSymbol(pid, ssId, symbolData, name);
+      if (recovered && !alreadyCompleted) this.#routeOverlayRecovered(inst, coords.sbn, recovered);
+    }
+  }
+  #noteOverlayMoqBlock(inst, blockStart) {
+    inst.moqBlocks.add(blockStart);
+    const newest = inst.last?.ssId;
+    if (newest === void 0) return;
+    for (const start of inst.moqBlocks) {
+      if ((newest - start | 0) > OVERLAY_MOQ_HORIZON_BLOCKS * inst.k) inst.moqBlocks.delete(start);
+    }
+  }
+  /**
+   * An overlay SS_ID inconsistent with the source's packet_sequence_number
+   * advance since the last one is an overlay restart (an FFmpeg muxer start,
+   * a bridge swap that keeps psn continuous): it moved the other way, or
+   * further than the psn advance plus K_overlay. Reordering keeps the two
+   * consistent and is no restart.
+   */
+  #noteOverlaySsId(inst, ssId, psn) {
+    const last = inst.last;
+    if (last !== void 0) {
+      const dSs = ssId - last.ssId | 0;
+      const dPsn = psn - last.psn | 0;
+      const consistent = dSs === 0 ? dPsn === 0 : Math.sign(dSs) === Math.sign(dPsn) && Math.abs(dSs) <= Math.abs(dPsn) + inst.k;
+      if (!consistent) {
+        this.#overlayStats.restarts++;
+        this.#resetOverlay(inst);
+      } else if (dPsn < 0) {
+        return;
+      }
+    }
+    inst.last = { ssId, psn };
+  }
+  /**
+   * Route an overlay-recovered block's packets as source media of the
+   * overlay's source (7.2: an overlay coordinate yields no base SS_ID). No
+   * base-SS_ID derivation runs: no release-gate anchor, no parse ledger, no
+   * base re-stamp, no block advance. Each packet's wire sequence is restored
+   * from its keyframe's own offset; without one, a stream the base never
+   * re-stamped keeps the header's sequence and any other drops the packet.
+   */
+  #routeOverlayRecovered(inst, blockStart, recovered) {
+    const { fec, repairPacketId: pid, streamName: name } = inst;
+    fec.markBlockCompleted(blockStart, pid, name);
+    const sourcePacketId = inst.leg.sourcePacketId;
+    const sourceName = inst.leg.sourceCatalogTrackName;
+    if (this.#classifyPacketId(sourcePacketId) === null) return;
+    const receiver = this.#provenanceFor(sourcePacketId, sourceName);
+    if (receiver !== void 0 && inst.moqBlocks.has(blockStart)) {
+      this.#overlayStats.protectedDropped++;
+      return;
+    }
+    const blockProfile = fec.blockProfileForPacket(pid);
+    const symbolSize = fec.symbolSizeForPacket(pid);
+    if (blockProfile === void 0 || symbolSize === void 0 || !(symbolSize > 0)) return;
+    const result = processFecBlock(recovered, { symbolSize, ownerPacketId: sourcePacketId, blockProfile });
+    const streamKey = this.#mediaStreamKey(sourcePacketId, sourceName);
+    const restamped = this.#restampedStreams.has(streamKey);
+    const restored = /* @__PURE__ */ new Set();
+    const symbols = result.symbols.flatMap((sym) => {
+      const offset = inst.offsets.get(sym.fragment.mpuSequenceNumber);
+      if (offset !== void 0) {
+        const packetSequenceNumber = serial32Add(blockStart, sym.index) - offset >>> 0;
+        restored.add(packetSequenceNumber);
+        return [{ ...sym, packetSequenceNumber }];
+      }
+      if (!restamped) return [sym];
+      this.#overlayStats.unsequencedDropped++;
+      return [];
+    });
+    this.#overlayStats.recovered++;
+    this.#routeProcessedFecSymbols(blockStart, { ...result, symbols }, sourcePacketId, sourceName, {
+      deliveryProvenance: inst.moqBlocks.has(blockStart) ? "mixed" : "multicast"
+    });
+    this.#noteOverlayRecoveredRaps(sourcePacketId, sourceName, streamKey, symbols.filter((sym) => restored.has(sym.packetSequenceNumber)));
+  }
+  /** fec-multicast-00 §6.6: report each base block whose RAP MFU fragments
+   *  the overlay restored, when the keyframe's FT=0 and FT=1 are held too. A
+   *  packet whose wire sequence was not restored names no base block. */
+  #noteOverlayRecoveredRaps(packetId, catalogTrackName, streamKey, symbols) {
+    const ssIdSeqOffset = this.#ssIdSeqOffsetByStream.get(streamKey);
+    if (ssIdSeqOffset === void 0 || this.#overlayRecoveredObservers.size === 0) return;
+    const withMeta = (type) => new Set(symbols.filter((sym) => sym.fragmentType === type).map((sym) => sym.fragment.mpuSequenceNumber));
+    const ft0 = withMeta(0);
+    const ft1 = withMeta(1);
+    const rapMfu = (fi) => new Set(symbols.filter((sym) => sym.fragmentType === 2 && sym.fragment.rapFlag && sym.fragment.fragmentationIndicator === fi).map((sym) => sym.fragment.mpuSequenceNumber));
+    const single = rapMfu(0);
+    const first = rapMfu(1);
+    const last = rapMfu(3);
+    const blocks = /* @__PURE__ */ new Set();
+    for (const sym of symbols) {
+      const mpu = sym.fragment.mpuSequenceNumber;
+      if (sym.fragmentType !== 2 || !sym.fragment.rapFlag || !ft0.has(mpu) || !ft1.has(mpu)) continue;
+      if (!single.has(mpu) && !(first.has(mpu) && last.has(mpu))) continue;
+      const ssId = sym.packetSequenceNumber + ssIdSeqOffset >>> 0;
+      const sbn = this.#fecManager?.locateIsoSource?.(packetId, catalogTrackName, ssId)?.sbn;
+      if (sbn !== void 0) blocks.add(sbn);
+    }
+    for (const sbn of blocks) {
+      for (const observer of this.#overlayRecoveredObservers) observer(packetId, catalogTrackName, sbn);
+    }
+  }
   /**
    * Register callback fired when a delta-track FEC block completes or fails.
    *
@@ -23276,10 +23800,11 @@ var MmtpRouter = class {
     if (!entry) return;
     entry.receiver.release();
     entry.protected = false;
+    entry.userAgent = false;
     this.#assistBlocks.clear();
     this.#assistFailures.clear();
   }
-  /** MoQ packets of a track a protected flow lists, dropped on its unicast path: duplicate, overflow, or listed by more than one flow. */
+  /** Packets of a track a protected flow lists, dropped unread: a MoQ copy (duplicate, overflow, or listed by more than one flow) or a multicast source datagram that names no flow, of a track a user-agent-admitted flow lists. */
   get unadmittedListedDropCount() {
     return this.#unadmittedListedDrops;
   }
@@ -23320,6 +23845,13 @@ var MmtpRouter = class {
     }
     return false;
   }
+  /** Whether a protected flow the user agent admitted lists `packetId`. */
+  #userAgentGoverns(packetId) {
+    for (const entry of this.#provenance.values()) {
+      if (entry.protected && entry.userAgent && ingressHasPacketId(entry.ingress, packetId)) return true;
+    }
+    return false;
+  }
   /**
    * A MoQ repair symbol no protected flow lists, owned by a source track one
    * does: its FEC instance is governed (7.2.7 step 2) and takes only admitted
@@ -23410,7 +23942,7 @@ var MmtpRouter = class {
       fec.cancelBlockTimeout(blockStart, ownerPacketId, catalogTrackName);
       fec.countRecovery(ownerPacketId, blockStart, catalogTrackName);
       fec.markBlockCompleted(blockStart, ownerPacketId, catalogTrackName);
-    })) {
+    }, true)) {
       this.#unlistedAssistedRecoveries++;
       this.#assistBlocks.delete(key);
       return;
@@ -23595,6 +24127,11 @@ var MmtpRouter = class {
       return;
     }
     const repairPacketId = header.packetId;
+    const overlay = this.#overlayRepairTarget(repairPacketId, repairTrackName);
+    if (overlay !== void 0) {
+      this.#routeOverlayRepair(overlay, repairPacketId, packet, header, "moq");
+      return;
+    }
     const hintedOwner = ownerPacketIdHint != null && this.#classifyPacketId(ownerPacketIdHint) !== null ? ownerPacketIdHint : null;
     const ownerPacketId = hintedOwner ?? (this.#classifyPacketId(repairPacketId) !== null ? repairPacketId : null);
     if (ownerPacketId === null) {
@@ -23884,6 +24421,8 @@ var MmtpRouter = class {
       }
     }
     this.#parser.resetTrack(packetId, catalogTrackName);
+    this.resetKeyframeOverlays(packetId, catalogTrackName);
+    this.#restampedStreams.delete(this.#mediaStreamKey(packetId, catalogTrackName));
     const assistPrefix = assistKey(packetId, catalogTrackName, 0).slice(0, -1);
     for (const key of this.#assistBlocks.keys()) if (key.startsWith(assistPrefix)) this.#assistBlocks.delete(key);
     for (const key of this.#assistFailures.keys()) if (key.startsWith(assistPrefix)) this.#assistFailures.delete(key);
@@ -23970,6 +24509,17 @@ var MmtpRouter = class {
     this.#packetIdRoles.delete(packetId);
     this.#catalogTrackNamesByPacketId.delete(packetId);
     this.#repairOwnersByPacketId.delete(packetId);
+    this.#overlayLegs.delete(packetId);
+    for (const [repairPacketId, leg] of [...this.#overlayLegs]) {
+      if (leg.sourcePacketId === packetId) this.#overlayLegs.delete(repairPacketId);
+    }
+    for (const [name, leg] of [...this.#overlayRepairNames]) {
+      if (leg.sourcePacketId === packetId) this.#overlayRepairNames.delete(name);
+    }
+    this.#overlays.delete(packetId);
+    for (const [repairPacketId, inst] of [...this.#overlays]) {
+      if (inst.leg.sourcePacketId === packetId) this.#overlays.delete(repairPacketId);
+    }
     delete this.#pidCounts[packetId];
     delete this.#repairPidCounts[packetId];
     delete this.#moqRepairPidCounts[packetId];
@@ -24208,6 +24758,9 @@ var MmtpRouter = class {
     this.#parserDiagnostics.clear();
     this.#catalogTrackNamesByPacketId.clear();
     this.#repairOwnersByPacketId.clear();
+    this.#overlayLegs.clear();
+    this.#overlayRepairNames.clear();
+    this.#overlays.clear();
     for (const { receiver } of this.#provenance.values()) receiver.release();
     this.#provenance.clear();
     this.#provenanceStreamFlow.clear();
@@ -24545,6 +25098,12 @@ var MmtpRouter = class {
         debugRouter(`[MmtpRouter] Dropping multicast packet pid=${info.packetId}: flow ${ingress.flow} has no receiver`);
         return;
       }
+      if (ingress.admittedBy === USER_AGENT_VERIFIED) {
+        this.#noteFlowAdmitted(ingress.flow);
+        protectedFlow.userAgent = true;
+        this.#processMMTP(packet, source, true, ingress, overlapCopy);
+        return;
+      }
       const { verdict } = protectedFlow.receiver.onDatagram(packet, "multicast");
       if (verdict === "admitted") {
         this.#noteFlowAdmitted(ingress.flow);
@@ -24562,7 +25121,17 @@ var MmtpRouter = class {
         return;
       }
     }
+    const flowless = source === "multicast" && !manifestAdmitted && ingress?.flow === void 0;
+    if (flowless && !info.isRepair && this.#userAgentGoverns(info.packetId)) {
+      this.#unadmittedListedDrops++;
+      return;
+    }
     if (info.isRepair) {
+      const overlay = this.#overlayRepairTarget(info.packetId, catalogTrackNameForPacket(ingress, info.packetId));
+      if (overlay !== void 0) {
+        this.#routeOverlayRepair(overlay, info.packetId, packet, parsed.header, source);
+        return;
+      }
       const ownerPacketId = this.#resolveRepairOwnerPacketId(info.packetId, ingress);
       if (ownerPacketId != null && this.#fecManager && hasAmbiguousCatalogTrackName(ingress, ownerPacketId)) return;
       const repair = this.#readRepairObject(
@@ -24574,7 +25143,7 @@ var MmtpRouter = class {
       );
       if (!repair) return;
       if (ownerPacketId != null && this.#fecManager) {
-        if (source === "moq" && !manifestAdmitted && this.#setAsideUnlistedRepair(ownerPacketId, catalogTrackNameForPacket(ingress, ownerPacketId), repair)) return;
+        if ((flowless && this.#userAgentGoverns(ownerPacketId) || source === "moq" && !manifestAdmitted) && this.#setAsideUnlistedRepair(ownerPacketId, catalogTrackNameForPacket(ingress, ownerPacketId), repair)) return;
         this.#repairPidCounts[info.packetId] = (this.#repairPidCounts[info.packetId] || 0) + 1;
         const count = this.#repairPidCounts[info.packetId];
         if (count <= 2 || count % 500 === 0) {
@@ -24769,6 +25338,17 @@ var MmtpRouter = class {
           });
         }
       }
+      if (!overlapCopy && this.#classifyPacketId(info.packetId) !== null) {
+        this.#feedOverlaySource(
+          info.packetId,
+          catalogTrackName,
+          packet,
+          parsed.header,
+          info.sequenceNumber,
+          info.rapFlag,
+          source
+        );
+      }
     }
   }
   /**
@@ -25142,7 +25722,7 @@ var MmtpRouter = class {
   }
   // ── Private: FEC recovery routing ───────────────────────────────
   /** Route WASM-recovered block through appropriate path based on container kind. */
-  #routeRecoveredBlock(blockId, recovered, ownerPacketId, catalogTrackName, complete) {
+  #routeRecoveredBlock(blockId, recovered, ownerPacketId, catalogTrackName, complete, assisted = false) {
     const packetSymbolSize = this.#symbolSizeForPacket(ownerPacketId);
     if (ownerPacketId === void 0) {
       throw new Error("[MmtpRouter] a recovered FEC block needs its owner packetId to read its fec.blockProfile");
@@ -25159,7 +25739,7 @@ var MmtpRouter = class {
       ownerPacketId,
       blockProfile
     });
-    return this.#routeVerifiedFecSymbols(blockId, result, ownerPacketId, catalogTrackName, complete);
+    return this.#routeVerifiedFecSymbols(blockId, result, ownerPacketId, catalogTrackName, complete, assisted);
   }
   /**
    * A recovered source packet of a protected flow is admitted on its own
@@ -25171,9 +25751,24 @@ var MmtpRouter = class {
    * recovered packets is refused is unrecovered (7.2.7): its caller leaves it
    * open, so it reaches its FEC deadline and fails by class. Always true
    * outside a protected flow.
-   */
-  #routeVerifiedFecSymbols(blockId, result, ownerPacketId, catalogTrackName, complete) {
-    const receiver = ownerPacketId == null ? void 0 : this.#provenanceFor(ownerPacketId, catalogTrackName);
+   *
+   * On a flow the user agent admitted, the live decoder's recoveries are kept
+   * without a record: while the flow is protected that decoder takes only
+   * symbols the user agent or a record verified (a flow-less multicast
+   * datagram of a listed track is dropped or set aside in #processMMTP), so
+   * what it recovers is as verified as they are. An `assisted` (scratch-decoder) recovery mixes in
+   * unlisted MoQ repair and still needs a record.
+   * ponytail: per-flow flag; per-block provenance only if a protected flow
+   * ever mixes verified and unverified live inputs.
+   * ponytail: a worker frame computed before the protection reset can still
+   * arrive after it (frames carry no epoch); its inputs are MoQ copies read
+   * and played before protection, so it admits nothing new. Drop pre-reset
+   * frames by epoch only if pre-protection input ever matters.
+   */
+  #routeVerifiedFecSymbols(blockId, result, ownerPacketId, catalogTrackName, complete, assisted = false) {
+    const entry = ownerPacketId == null ? void 0 : this.#provenanceFor(ownerPacketId, catalogTrackName);
+    const receiver = entry === void 0 || entry === "ambiguous" ? entry : entry.receiver;
+    const userAgent = !assisted && entry !== void 0 && entry !== "ambiguous" && entry.protected === true && entry.userAgent === true;
     let recovered = true;
     if (receiver) {
       const parsed = this.#stream(ownerPacketId, catalogTrackName).duplicates.parsedSymbols;
@@ -25185,6 +25780,8 @@ var MmtpRouter = class {
           let admitted = false;
           if (receiver === "ambiguous") {
             this.#ambiguousRecoveredDrops++;
+          } else if (userAgent) {
+            admitted = true;
           } else {
             const wire = new Uint8Array(sym.rawSymbol.byteLength + 4);
             wire.set(sym.rawSymbol);
@@ -25212,22 +25809,22 @@ var MmtpRouter = class {
       catalogTrackName === void 0 || !byName ? byName?.values() : byName.has(catalogTrackName) ? [byName.get(catalogTrackName)] : []
     );
     if (flows.size > 1) return "ambiguous";
-    for (const bound of flows) return this.#provenance.get(bound)?.receiver ?? "ambiguous";
+    for (const bound of flows) return this.#provenance.get(bound) ?? "ambiguous";
     let match;
-    for (const { receiver, ingress } of this.#provenance.values()) {
-      if (ingress.tracks.some((t) => t.packetId === packetId && (catalogTrackName === void 0 || t.name === catalogTrackName))) {
+    for (const entry of this.#provenance.values()) {
+      if (entry.ingress.tracks.some((t) => t.packetId === packetId && (catalogTrackName === void 0 || t.name === catalogTrackName))) {
         if (match) return "ambiguous";
-        match = receiver;
+        match = entry;
       }
     }
     return match;
   }
-  #routeProcessedFecSymbols(blockId, result, ownerPacketId, catalogTrackName) {
+  #routeProcessedFecSymbols(blockId, result, ownerPacketId, catalogTrackName, overlay) {
     if (ownerPacketId == null) return;
     if (this.#classifyPacketId(ownerPacketId) === null) return;
-    const ssIdSeqOffset = this.#ssIdSeqOffsetByStream.get(
-      this.#mediaStreamKey(ownerPacketId, catalogTrackName)
-    );
+    const fecSbnOf = (index) => overlay ? {} : { fecSbn: this.#fecAnchorForRecovered(blockId, index) };
+    const streamKey = this.#mediaStreamKey(ownerPacketId, catalogTrackName);
+    const ssIdSeqOffset = overlay ? void 0 : this.#ssIdSeqOffsetByStream.get(streamKey);
     if (ssIdSeqOffset !== void 0) {
       result = {
         ...result,
@@ -25235,12 +25832,13 @@ var MmtpRouter = class {
           const wire = this.#fecAnchorForRecovered(blockId, sym.index) - ssIdSeqOffset >>> 0;
           if (wire === sym.packetSequenceNumber) return sym;
           this.#restampedRecoveredSeqs++;
+          this.#restampedStreams.add(streamKey);
           return { ...sym, packetSequenceNumber: wire };
         })
       };
     }
-    this.#stream(ownerPacketId, catalogTrackName).duplicates.advance(blockId);
-    const deliveryProvenance = this.#fecManager?.blockDeliveryProvenance?.(
+    if (!overlay) this.#stream(ownerPacketId, catalogTrackName).duplicates.advance(blockId);
+    const deliveryProvenance = overlay?.deliveryProvenance ?? this.#fecManager?.blockDeliveryProvenance?.(
       blockId,
       ownerPacketId,
       catalogTrackName
@@ -25318,7 +25916,7 @@ var MmtpRouter = class {
               rapFlag: sym.fragment.rapFlag,
               recovered: true,
               deliveryProvenance,
-              fecSbn: this.#fecAnchorForRecovered(blockId, sym.index),
+              ...fecSbnOf(sym.index),
               ...catalogTrackName === void 0 ? {} : { catalogTrackName }
             });
             continue;
@@ -25430,7 +26028,7 @@ var MmtpRouter = class {
                 rapFlag: assembled.rapFlag,
                 recovered: true,
                 ...assembled.deliveryProvenance === void 0 ? {} : { deliveryProvenance: assembled.deliveryProvenance },
-                fecSbn: this.#fecAnchorForRecovered(blockId, sym.index),
+                ...fecSbnOf(sym.index),
                 ...recoveredCatalogTrackName === void 0 ? {} : { catalogTrackName: recoveredCatalogTrackName }
               });
               continue;
@@ -25567,7 +26165,7 @@ var MmtpRouter = class {
             rapFlag: sym.fragment.rapFlag,
             recovered: true,
             deliveryProvenance,
-            fecSbn: this.#fecAnchorForRecovered(blockId, sym.index),
+            ...fecSbnOf(sym.index),
             ...catalogTrackName === void 0 ? {} : { catalogTrackName }
           });
         } else {
@@ -25646,7 +26244,7 @@ var MmtpRouter = class {
               rapFlag: assembled.rapFlag,
               recovered: true,
               deliveryProvenance,
-              fecSbn: this.#fecAnchorForRecovered(blockId, sym.index),
+              ...fecSbnOf(sym.index),
               ...assembled.catalogTrackName === void 0 ? {} : { catalogTrackName: assembled.catalogTrackName }
             });
           }
@@ -25681,7 +26279,7 @@ var MmtpRouter = class {
             ...sym.fragment.sampleNumber === void 0 ? {} : { sampleNumber: sym.fragment.sampleNumber },
             recovered: true,
             deliveryProvenance,
-            fecSbn: this.#fecAnchorForRecovered(blockId, sym.index),
+            ...fecSbnOf(sym.index),
             ...catalogTrackName === void 0 ? {} : { catalogTrackName }
           });
           continue;
@@ -25998,11 +26596,8 @@ function providerErrorOf(error) {
   return Object.freeze(typeof code === "string" ? { name, message, code } : { name, message });
 }
 var MAX_TRACKED_DROPPED_PIDS = 16;
-function getMulticastGlobals() {
-  return globalThis;
-}
 function hasMulticastGateway() {
-  return typeof getMulticastGlobals().multicast?.subscribe === "function";
+  return typeof resolveMulticastGateway()?.subscribe === "function";
 }
 function senderOf(event) {
   const sourceAddress = event.sourceAddress;
@@ -26094,6 +26689,9 @@ var MulticastTransport = class {
   // listener closure, so an in-place admission change (setContext) applies
   // from the next packet on without rejoining.
   #context = void 0;
+  #deliveredContext = void 0;
+  /** The live join's gateway, when it is the user agent's MulticastReceiver provider. */
+  #userAgentGateway = void 0;
   // The live join's provider-side filter. An in-place widening must reach it,
   // or the provider never delivers the new ID; null without a live join.
   #providerFilter = null;
@@ -26130,7 +26728,7 @@ var MulticastTransport = class {
     this.#dataPlaneLive = false;
     this.#sender = void 0;
     if (this.#disposed) return this.#declined(generation, "disposed");
-    const gateway = this.#gateway ?? getMulticastGlobals().multicast;
+    const gateway = this.#gateway ?? resolveMulticastGateway();
     if (typeof gateway?.subscribe !== "function") {
       console.warn("[MulticastTransport] Multicast API not available");
       return this.#declined(generation, "unavailable");
@@ -26146,15 +26744,16 @@ var MulticastTransport = class {
       console.log(
         `[MulticastTransport] window.multicast.subscribe(${config.sourceAddress ?? config.senderAddress ?? "*"}, ${config.groupAddress}, ${config.port})`
       );
+      const userAgent = isUserAgentVerifiedGateway(gateway);
       const subscribeConfig = toWindowMulticastSubscribeConfig({
         source: config.sourceAddress,
         senderAddress: config.senderAddress,
         group: config.groupAddress,
         port: config.port,
-        mode: config.mode,
-        amtRelay: config.amtRelay,
-        amtRelayPort: config.amtRelayPort,
-        amtDiscovery: config.amtDiscovery,
+        mode: userAgent ? "native" : config.mode,
+        amtRelay: userAgent ? void 0 : config.amtRelay,
+        amtRelayPort: userAgent ? void 0 : config.amtRelayPort,
+        amtDiscovery: userAgent ? void 0 : config.amtDiscovery,
         packetIds: config.packetIds,
         tracks: config.tracks,
         atsc3: config.atsc3
@@ -26200,7 +26799,8 @@ var MulticastTransport = class {
         acknowledgedUpdate: 0,
         inFlight: 0
       };
-      this.#context = context;
+      this.#userAgentGateway = userAgent ? gateway : void 0;
+      this.#setContext(context);
       if (packetIds) {
         for (const packetId of packetIds) {
           if (!this.#acceptedBytesByPacketId.has(packetId)) {
@@ -26208,7 +26808,7 @@ var MulticastTransport = class {
           }
         }
       }
-      this.#resolvedTransport = subscribeConfig.origin === "amt" ? "amt" : "native";
+      this.#resolvedTransport = userAgent ? "user-agent" : subscribeConfig.origin === "amt" ? "amt" : "native";
       const delivery = subscription.delivery ?? "datagram";
       if (delivery !== "datagram" && delivery !== "ordered-relay") {
         throw new Error(
@@ -26289,7 +26889,7 @@ var MulticastTransport = class {
     }
     if (!this.#acceptPacket(packet, sourceAddress)) return false;
     const liveness = !this.#isRecordCandidate(packet);
-    this.#onPacket(packet, this.#context);
+    this.#onPacket(packet, this.#deliveredContext);
     return liveness;
   }
   #isRecordCandidate(packet) {
@@ -26500,8 +27100,10 @@ var MulticastTransport = class {
     return this.#subscription !== null;
   }
   /**
-   * What the live join delivers with every accepted packet (the join's
-   * `context`, or the last setContext), or undefined without a live join.
+   * The live join's context as the caller gave it (the join's `context`, or
+   * the last setContext), or undefined without a live join. On a native
+   * provider each accepted packet is delivered with a marked copy of it
+   * (`userAgentVerifiedIngress`); this getter never carries the mark.
    */
   get context() {
     return this.#context;
@@ -26525,7 +27127,16 @@ var MulticastTransport = class {
         "[MulticastTransport] setContext needs a live join; join() carries the first context"
       );
     }
+    this.#setContext(context);
+  }
+  /**
+   * The join's context, and what the subscription delivers with each packet:
+   * marked admitted by the user agent when the gateway is its native
+   * MulticastReceiver provider. feedPacket never marks.
+   */
+  #setContext(context) {
     this.#context = context;
+    this.#deliveredContext = this.#userAgentGateway !== void 0 && typeof context === "object" && context !== null ? userAgentVerifiedIngress(context, this.#userAgentGateway) : context;
   }
   /**
    * Replace the live join's packet-ID allow-list in place, without rejoining.
@@ -26657,6 +27268,8 @@ var MulticastTransport = class {
     this.#matchedSource = void 0;
     this.#providerFilter = null;
     this.#context = void 0;
+    this.#deliveredContext = void 0;
+    this.#userAgentGateway = void 0;
     this.#withdrawnPacketIds.clear();
   }
   /** The ingress filter; an accepted packet is counted here, once. */
@@ -26860,7 +27473,7 @@ function newBlockPolicyStats(packetId, catalogTrackName, epoch) {
     repairsSkippedRangeNoAnchor: 0,
     repairsSkippedGroupCannotComplete: 0,
     repairsSkippedMootRap: 0,
-    repairStops: { preempted: 0, reprioritized: 0, expired: 0, resolved: 0, reset: 0, disposed: 0, moot: 0 },
+    repairStops: { preempted: 0, reprioritized: 0, expired: 0, resolved: 0, reset: 0, disposed: 0, moot: 0, "overlay-recovered": 0 },
     lastRepairSkip: null,
     keyframeRepairFetchesSent: 0,
     rangeRepairFetchesSent: 0,
@@ -27193,9 +27806,7 @@ function repairTrackNamesBySource(tracks) {
 }
 function boundRepairNames(binding) {
   if (binding?.status !== "ok") return [];
-  const names = binding.layers.map((layer) => layer.repairTrackName);
-  if (binding.overlay) names.push(binding.overlay.repairTrackName);
-  return names;
+  return binding.layers.map((layer) => layer.repairTrackName);
 }
 var MulticastManager = class {
   #fec;
@@ -27209,6 +27820,10 @@ var MulticastManager = class {
   /** Live joinRepairEndpoints() releases → the repair owners they registered,
    *  re-applied after configureMultiTrack() clears catalog-derived owners. */
   #repairReleases = /* @__PURE__ */ new Map();
+  /** Each source's catalog keyframe overlay, from its `ok` binding. */
+  #overlayBindings = /* @__PURE__ */ new Map();
+  /** Installed overlay decoders (`setKeyframeOverlayDecoder`), by source. */
+  #overlayInstalls = /* @__PURE__ */ new Map();
   #reportedFecDiagnosticsFailure = false;
   // ── Stream-global FEC timing reduction ──
   //
@@ -27449,6 +28064,63 @@ var MulticastManager = class {
     this.#configureTrackMapper(packetId, fecConfig);
     this.#router.setPacketIdType(packetId, trackType);
   }
+  /**
+   * Decode the keyframe overlay of `sourcePacketId` (draft-ramadan-mmt-fec-02
+   * 7.4) with `decoder`, a decoder of the same kind `setFecDecoder` takes.
+   * Opt-in: nothing else installs one, so a receiver that never calls this
+   * holds no overlay state and drops overlay repair. K_overlay, T, scheme
+   * and block profile come from the source's `ok` catalog binding, which
+   * must declare an overlay (`configureMultiTrack` first). The overlay is
+   * decoded on its own FEC state, apart from the base: no repair FETCH, no
+   * repair lifecycle event and no base statistic for its blocks. A second
+   * install on the same source replaces the first; the returned disposer
+   * removes only the install it created. Call it on releasing the overlay
+   * join.
+   */
+  setKeyframeOverlayDecoder(sourcePacketId, decoder, catalogTrackName) {
+    const binding = this.#overlayBindings.get(sourcePacketId);
+    if (!binding || catalogTrackName !== void 0 && binding.sourceCatalogTrackName !== catalogTrackName) {
+      throw new Error(
+        `[MulticastManager] packetId=${sourcePacketId} has no catalog keyframe overlay to decode`
+      );
+    }
+    this.#overlayInstalls.get(sourcePacketId)?.dispose();
+    let fec;
+    let uninstall;
+    const attach = () => {
+      fec = new FECManager();
+      fec.setFecDecoder(binding.repairPacketId, decoder, binding.k, {
+        blockProfile: binding.blockProfile,
+        k: binding.k,
+        symbolSize: binding.symbolSize,
+        trackKind: "video"
+      }, binding.repairTrackName);
+      uninstall = this.#router.installKeyframeOverlay(
+        binding.repairPacketId,
+        fec,
+        binding.k,
+        binding.repairTrackName
+      );
+    };
+    const detach = () => {
+      uninstall();
+      fec.releasePacket(binding.repairPacketId);
+    };
+    attach();
+    const install = {
+      reattach: () => {
+        detach();
+        attach();
+      },
+      dispose: () => {
+        if (this.#overlayInstalls.get(sourcePacketId) !== install) return;
+        this.#overlayInstalls.delete(sourcePacketId);
+        detach();
+      }
+    };
+    this.#overlayInstalls.set(sourcePacketId, install);
+    return install.dispose;
+  }
   /**
    * Register a Worker-backed FEC decoder for a specific packetId (track).
    * Worker-backed tracks decode asynchronously — recovered frames arrive via
@@ -27950,8 +28622,17 @@ var MulticastManager = class {
    * repair roles and owners are registered here; in-band owners stay the
    * caller's. Joining is best effort: a group that fails to join is logged
    * and leaves the media join as it was.
-   */
-  joinRepairEndpoints(endpoints, provider) {
+   *
+   * `options.gateway` names the gateway a subscribe callback reads through.
+   * When it is the browser's own MulticastReceiver provider, the callback's
+   * packets are fed as admitted by the user agent
+   * (`userAgentVerifiedIngress`); nothing the callback passes can mark them.
+   * The mark rests on this statement, not on the data path: every packet the
+   * callback delivers must come from a subscription opened on
+   * `options.gateway`. A callback that also merges another source (a MoQ or
+   * WebSocket repair feed) must not name a native provider here.
+   */
+  joinRepairEndpoints(endpoints, provider, options) {
     const releases = [];
     let released = false;
     const safely = (each) => {
@@ -27961,7 +28642,11 @@ var MulticastManager = class {
         console.warn("[MulticastManager] repair group release failed", error);
       }
     };
-    const repairOwners = endpoints.flatMap((endpoint) => endpoint.repairOwners);
+    const repairOwners = endpoints.flatMap((endpoint) => endpoint.repairOwners.map((owner) => owner.instance !== "keyframe" ? owner : {
+      ...owner,
+      ownerTrackName: endpoint.tracks.find((t) => t.packetId === owner.ownerPacketId)?.name,
+      repairTrackName: endpoint.tracks.find((t) => t.packetId === owner.packetId)?.name
+    }));
     this.#applyRepairOwners(repairOwners);
     for (const endpoint of endpoints) {
       const ingress = {
@@ -27969,17 +28654,19 @@ var MulticastManager = class {
         ...endpoint.flow === void 0 ? {} : { flow: endpoint.flow }
       };
       let sender;
-      const onPacket = (packet, sourceAddress) => {
+      const feed = (packet, sourceAddress, ingressToFeed) => {
         if (released) return;
         if (sourceAddress !== void 0 && !sameDatagramSource(sourceAddress, this.#transport.sender ?? (sender ??= sourceAddress))) return;
-        this.#router.feedPacket(packet, "multicast", ingress);
+        this.#router.feedPacket(packet, "multicast", ingressToFeed);
       };
       const fail = (error) => console.warn(`[MulticastManager] repair group ${endpoint.group}:${endpoint.port} not joined`, error);
       if (typeof provider === "function") {
+        const marked = userAgentVerifiedIngress(ingress, options?.gateway);
+        const onPacket = (packet, sourceAddress) => feed(packet, sourceAddress, marked);
         Promise.resolve().then(() => provider(endpoint, onPacket)).then((release2) => released ? safely(release2) : releases.push(release2), fail);
         continue;
       }
-      const transport = new MulticastTransport((packet) => onPacket(packet), {
+      const transport = new MulticastTransport((packet, delivered) => feed(packet, void 0, delivered ?? ingress), {
         gateway: provider,
         lockedTo: () => this.#transport.sender
       });
@@ -27995,7 +28682,7 @@ var MulticastManager = class {
         tracks: endpoint.tracks.map(({ name, packetId }) => ({ name, packetId })),
         // A protected repair group's records ride in band on its port (7.2.3).
         ...endpoint.flow === void 0 ? {} : { protected: true }
-      }).then((joined) => {
+      }, ingress).then((joined) => {
         if (!joined && !released) fail(transport.lastJoinOutcome);
       });
     }
@@ -28009,9 +28696,17 @@ var MulticastManager = class {
     return release;
   }
   #applyRepairOwners(owners) {
-    for (const { packetId, ownerPacketId } of owners) {
+    for (const { packetId, ownerPacketId, instance, ownerTrackName, repairTrackName } of owners) {
       this.#router.setPacketIdRole(packetId, "repair");
-      this.#router.setRepairPacketIdOwner(packetId, ownerPacketId);
+      if (instance === "keyframe") {
+        this.#router.setKeyframeOverlayLeg(packetId, {
+          sourcePacketId: ownerPacketId,
+          ...ownerTrackName === void 0 ? {} : { sourceCatalogTrackName: ownerTrackName },
+          ...repairTrackName === void 0 ? {} : { repairTrackName }
+        });
+      } else {
+        this.#router.setRepairPacketIdOwner(packetId, ownerPacketId);
+      }
     }
   }
   // ---------------------------------------------------------------------------
@@ -28275,8 +28970,8 @@ var MulticastManager = class {
     this.#fec.setMulticastSymbolDelivery(delivery);
   }
   /** Process a repair packet from MoQ (reliable QUIC). */
-  processRepairFromMoQ(packet, ownerPacketId, catalogTrackName) {
-    this.#router.feedRepairPacket(packet, ownerPacketId, catalogTrackName);
+  processRepairFromMoQ(packet, ownerPacketId, catalogTrackName, repairTrackName) {
+    this.#router.feedRepairPacket(packet, ownerPacketId, catalogTrackName, repairTrackName);
   }
   /** Route a Worker-recovered FEC block through the MMTP parser + dedup pipeline. */
   routeRecoveredBlock(blockId, data, packetId, catalogTrackName) {
@@ -28328,7 +29023,10 @@ var MulticastManager = class {
     const ownedRepairNames = /* @__PURE__ */ new Set();
     const claimed = /* @__PURE__ */ new Map();
     for (const binding of bindings.values()) {
-      for (const name of boundRepairNames(binding)) claimed.set(name, (claimed.get(name) ?? 0) + 1);
+      const overlay = binding.status === "ok" ? binding.overlay?.repairTrackName : void 0;
+      for (const name of [...boundRepairNames(binding), ...overlay === void 0 ? [] : [overlay]]) {
+        claimed.set(name, (claimed.get(name) ?? 0) + 1);
+      }
     }
     for (const [name, count] of claimed) if (count === 1) ownedRepairNames.add(name);
     const repairOwnerGroup = /* @__PURE__ */ new Map();
@@ -28431,6 +29129,7 @@ var MulticastManager = class {
     const catalogTracksByName = new Map(
       catalog.tracks.map((track) => [track.name, track])
     );
+    const overlayBindings = /* @__PURE__ */ new Map();
     for (let i = 0; i < catalog.tracks.length; i++) {
       const track = catalog.tracks[i];
       const role = resolvedRoles[i];
@@ -28459,6 +29158,29 @@ var MulticastManager = class {
               this.#router.setRepairPacketIdOwner(repairTrack.packetId, track.packetId);
             }
           }
+          const overlayName = binding.overlay?.repairTrackName;
+          const overlayPacketId = overlayName === void 0 ? void 0 : catalogTracksByName.get(overlayName)?.packetId;
+          if (overlayName !== void 0 && ownedRepairNames.has(overlayName)) {
+            this.#router.setKeyframeOverlayLeg(overlayPacketId, {
+              sourcePacketId: track.packetId,
+              sourceCatalogTrackName: track.name,
+              repairTrackName: overlayName
+            });
+          }
+          if (overlayName !== void 0 && overlayPacketId !== void 0 && ownedRepairNames.has(overlayName)) {
+            const geometry2 = binding.overlay.geometry;
+            overlayBindings.set(track.packetId, {
+              repairPacketId: overlayPacketId,
+              repairTrackName: overlayName,
+              sourceCatalogTrackName: track.name,
+              k: binding.overlay.sourceSymbols,
+              symbolSize: fecCfg.symbolSize,
+              blockProfile: parseFecBlockProfile(
+                geometry2.blockProfile,
+                `tracks[${JSON.stringify(track.name)}].fec keyframe overlay blockProfile`
+              )
+            });
+          }
         }
         const wasmDecoder = fecDecoders.get(i);
         if (track.packetId !== void 0 && wasmDecoder !== void 0) {
@@ -28492,6 +29214,16 @@ var MulticastManager = class {
         }
       }
     }
+    for (const [sourcePacketId, install] of [...this.#overlayInstalls]) {
+      const before = this.#overlayBindings.get(sourcePacketId);
+      const after = overlayBindings.get(sourcePacketId);
+      const same = before !== void 0 && after !== void 0 && Object.keys(after).every((key) => after[key] === before[key]);
+      if (!same) install.dispose();
+      else if (this.#router.hasKeyframeOverlay(after.repairPacketId)) this.#router.resetKeyframeOverlays(sourcePacketId);
+      else install.reattach();
+    }
+    this.#overlayBindings.clear();
+    for (const [sourcePacketId, binding] of overlayBindings) this.#overlayBindings.set(sourcePacketId, binding);
   }
   /**
    * Why `configureMultiTrack` consumes the named catalog track without FEC
@@ -28663,6 +29395,10 @@ var MulticastManager = class {
   addRapCompleteObserver(observer) {
     return this.#router.addFecRapObserver(observer);
   }
+  /** Observe each base block whose RAP the keyframe overlay recovered (fec-multicast-00 §6.6). */
+  addKeyframeOverlayRecoveredObserver(observer) {
+    return this.#router.addKeyframeOverlayRecoveredObserver(observer);
+  }
   /** Catalog/reset epoch of a packet's streams; gap decisions carry it. */
   epochFor(packetId) {
     return this.#fec.epochFor(packetId);
@@ -31754,12 +32490,27 @@ function wireRepairFetch(mc, opts) {
       dispatch();
     });
   });
+  const removeOverlayObserver = mc.addKeyframeOverlayRecoveredObserver?.((packetId, catalogTrackName, sbn) => {
+    queueMicrotask(() => {
+      if (disposed) return;
+      for (const entry of [...entries.values()]) {
+        if (entry.range || entry.priority !== 0 || entry.packetId !== packetId || entry.sbn !== sbn) continue;
+        if (catalogTrackName !== void 0 && entry.catalogTrackName !== catalogTrackName) continue;
+        stop(entry, "overlay-recovered");
+        retire(entry);
+        releaseHold(entry);
+        clearEntry(entry);
+      }
+      dispatch();
+    });
+  });
   return () => {
     disposed = true;
     mc.setUnicastRepair?.(false);
     removeResetObserver();
     removeLifecycleObserver();
     removeRapObserver?.();
+    removeOverlayObserver?.();
     for (const entry of [...entries.values()]) {
       clearEntry(entry);
       if (entry.running) releaseHold(entry);
@@ -31793,6 +32544,7 @@ export {
   HoldLastTimeline,
   JOIN_DEFER_WARN_MS,
   KEYFRAME_LOST_TIMEOUT_SLACK,
+  KEYFRAME_OVERLAY_EXTENSION_TYPE,
   LOCHeaderExtensionId,
   MAX_ENCODING_SYMBOL_ID,
   MAX_RAPTORQ_SOURCE_SYMBOLS,
@@ -31902,6 +32654,7 @@ export {
   isTrackTimingConfig,
   joinedRepairSymbolCount,
   keyframeIntervalMediaTicks,
+  keyframeOverlaySsId,
   mergeOverrideIntoCmsfTracks,
   mergeOverrideIntoHangRenditions,
   mfuReassemblyTimeoutMs,