@blockcast/mmt-transport 0.2.2 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockcast/mmt-transport",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Unified transport manager for MoQ with WebTransport, SSM multicast, AMT, DRIAD, and FEC support",
   "type": "module",
   "main": "dist/index.js",
@@ -10,10 +10,6 @@
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
     },
-    "./fec": {
-      "import": "./dist/fec-client.js",
-      "types": "./dist/fec-client.d.ts"
-    },
     "./clock": {
       "import": "./dist/clock.js",
       "types": "./dist/clock.d.ts"
@@ -24,7 +20,12 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts",
+    "!src/**/__tests__",
+    "!dist/**/*.test.*",
+    "!dist/**/*.spec.*"
   ],
   "scripts": {
     "build": "tsc && node build.mjs",
@@ -34,6 +35,12 @@
     "test": "vitest run",
     "test:watch": "vitest"
   },
+  "dependencies": {
+    "@blockcast/mmt-base": "^0.3.0"
+  },
+  "bundledDependencies": [
+    "@blockcast/mmt-base"
+  ],
   "devDependencies": {
     "esbuild": "^0.21.5",
     "typescript": "^5.9.3",

package/src/abr-controller.ts

@@ -27,9 +27,15 @@ export interface FecStatsForAbr {
 }
 
 /**
- * Standard quality levels for progressive ABR
+ * A generic 240p..4K ladder, kept as public API only.
+ *
+ * @deprecated Not a stream's ladder and never a default: the controller
+ * adapts over the ladder its caller supplies (`AdaptiveBitrateControllerOptions.ladder`,
+ * e.g. the catalog's video renditions). Walking this list is how a player on a
+ * 360p/480p/720p catalog logged upgrades to 1080p and 1440p it could never
+ * switch to (BLO-35597).
  */
-export const QUALITY_LEVELS: QualityLevel[] = [
+export const QUALITY_LEVELS: readonly QualityLevel[] = Object.freeze([
 	{ name: "240p", bitrate: 300_000, width: 426, height: 240, fps: 15 },
 	{ name: "360p", bitrate: 500_000, width: 640, height: 360, fps: 24 },
 	{ name: "480p", bitrate: 1_000_000, width: 854, height: 480, fps: 30 },
@@ -37,7 +43,57 @@ export const QUALITY_LEVELS: QualityLevel[] = [
 	{ name: "1080p", bitrate: 5_000_000, width: 1920, height: 1080, fps: 30 },
 	{ name: "1440p", bitrate: 8_000_000, width: 2560, height: 1440, fps: 30 },
 	{ name: "4K", bitrate: 15_000_000, width: 3840, height: 2160, fps: 30 },
-];
+].map((level) => Object.freeze(level)));
+
+/** What the controller adapts over and where it starts; both from the caller. */
+export interface AdaptiveBitrateControllerOptions {
+	/**
+	 * The renditions this stream carries (e.g. the catalog's video tracks), in
+	 * any order: a unique name and a bitrate (bps) each, plus dimensions and
+	 * fps when the catalog states them. Renditions may share a bitrate.
+	 */
+	ladder: readonly QualityLevel[];
+	/** Name of the ladder rendition presented at construction; the lowest
+	 *  rung when omitted. A name that matches no rung is refused. */
+	initialQuality?: string;
+}
+
+function positiveFinite(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+
+/**
+ * Validate a caller ladder and return it frozen, ascending by bitrate. Throws
+ * on an empty ladder, a rung without a name or a positive finite bitrate, a
+ * width, height or fps that is present but not positive finite, or a name that
+ * appears twice: a name is how `setQuality` and the initial rendition find a
+ * rung. A shared bitrate is legal (e.g. 720p30 and 720p60, or two codecs);
+ * `Array.prototype.sort` is stable, so equal bitrates keep the caller's order.
+ */
+export function validateQualityLadder(ladder: readonly QualityLevel[]): readonly QualityLevel[] {
+	if (!Array.isArray(ladder) || ladder.length === 0) {
+		throw new TypeError("[ABR] ladder must list at least one rendition (e.g. the catalog's video tracks)");
+	}
+	const names = new Set<string>();
+	for (const level of ladder) {
+		if (typeof level?.name !== "string" || level.name.length === 0) {
+			throw new TypeError("[ABR] every ladder rendition needs a name");
+		}
+		if (!positiveFinite(level.bitrate)) {
+			throw new RangeError(`[ABR] rendition ${level.name}: bitrate must be a positive finite number, got ${String(level.bitrate)}`);
+		}
+		for (const field of ["width", "height", "fps"] as const) {
+			if (level[field] !== undefined && !positiveFinite(level[field])) {
+				throw new RangeError(`[ABR] rendition ${level.name}: ${field} must be a positive finite number when stated, got ${String(level[field])}`);
+			}
+		}
+		if (names.has(level.name)) throw new RangeError(`[ABR] rendition ${level.name} appears twice in the ladder`);
+		names.add(level.name);
+	}
+	return Object.freeze(
+		[...ladder].sort((a, b) => a.bitrate - b.bitrate).map((level) => Object.freeze({ ...level })),
+	);
+}
 
 /**
  * Progressive Adaptive Bitrate Controller
@@ -50,6 +106,8 @@ export const QUALITY_LEVELS: QualityLevel[] = [
  * - Fast quality downgrades on congestion
  */
 export class AdaptiveBitrateController {
+	/** The caller's renditions, ascending by bitrate (`validateQualityLadder`). */
+	readonly ladder: readonly QualityLevel[];
 	private currentQualityIndex: number;
 	private history: { timestamp: number; bytesReceived: number; packetsLost: number }[] = [];
 	private readonly historyWindow = 10_000; // 10 second window
@@ -68,10 +126,16 @@ export class AdaptiveBitrateController {
 		fecEnabled: false,
 	};
 
-	constructor(initialQuality?: QualityLevel) {
-		this.currentQualityIndex = initialQuality ? QUALITY_LEVELS.findIndex((q) => q.name === initialQuality.name) : 0;
-
-		if (this.currentQualityIndex < 0) this.currentQualityIndex = 0;
+	constructor(options: AdaptiveBitrateControllerOptions) {
+		if (!options || typeof options !== "object") {
+			throw new TypeError("[ABR] AdaptiveBitrateController needs { ladder, initialQuality }");
+		}
+		this.ladder = validateQualityLadder(options.ladder);
+		this.currentQualityIndex =
+			options.initialQuality === undefined ? 0 : this.ladder.findIndex((q) => q.name === options.initialQuality);
+		if (this.currentQualityIndex < 0) {
+			throw new RangeError(`[ABR] initial rendition ${String(options.initialQuality)} is not in the ladder`);
+		}
 	}
 
 	setCallback(callback: (quality: QualityLevel) => void) {
@@ -79,7 +143,7 @@ export class AdaptiveBitrateController {
 	}
 
 	getCurrentQuality(): QualityLevel {
-		return QUALITY_LEVELS[this.currentQualityIndex];
+		return this.ladder[this.currentQualityIndex];
 	}
 
 	/** Selects the multicast (S,G) tier without replacing a player's unicast ABR manager. */
@@ -130,7 +194,7 @@ export class AdaptiveBitrateController {
 		if (
 			measuredBitrate > currentQuality.bitrate * this.upgradeThreshold &&
 			effectiveLossRate < 0.01 &&
-			this.currentQualityIndex < QUALITY_LEVELS.length - 1
+			this.currentQualityIndex < this.ladder.length - 1
 		) {
 			this.upgrade();
 		}
@@ -171,7 +235,7 @@ export class AdaptiveBitrateController {
 	}
 
 	private upgrade() {
-		if (this.currentQualityIndex >= QUALITY_LEVELS.length - 1) return;
+		if (this.currentQualityIndex >= this.ladder.length - 1) return;
 
 		this.currentQualityIndex++;
 		this.lastQualityChange = Date.now();
@@ -195,15 +259,15 @@ export class AdaptiveBitrateController {
 	}
 
 	/**
-	 * Force quality level (for testing)
+	 * Select a ladder rendition: the caller switched to it (a manual override,
+	 * or a switch the caller made). Throws for a name the ladder does not carry.
 	 */
 	setQuality(name: string) {
-		const index = QUALITY_LEVELS.findIndex((q) => q.name === name);
-		if (index >= 0) {
-			this.currentQualityIndex = index;
-			this.lastQualityChange = Date.now();
-			this.onQualityChange?.(this.getCurrentQuality());
-		}
+		const index = this.ladder.findIndex((q) => q.name === name);
+		if (index < 0) throw new RangeError(`[ABR] rendition ${name} is not in the ladder`);
+		this.currentQualityIndex = index;
+		this.lastQualityChange = Date.now();
+		this.onQualityChange?.(this.getCurrentQuality());
 	}
 
 	/**

package/src/amt-gateway.ts

@@ -9,9 +9,7 @@
 
 import type { GroupKey, PacketMetadata, AmtRelayInfo } from "./types.js";
 import { DRIADDiscovery } from "./driad-discovery.js";
-
-/** Default AMT port (RFC 7450) */
-const DEFAULT_AMT_PORT = 2268;
+import { DEFAULT_AMT_RELAY_PORT } from "@blockcast/mmt-base";
 
 /** AMT message types */
 const AMT_MESSAGE_TYPES = {
@@ -133,7 +131,7 @@ export class AMTGatewayManager {
 		try {
 			let relayAddress: string;
 			let discoveryMethod: "driad" | "manual";
-			const relayPort = config.relayPort || DEFAULT_AMT_PORT;
+			const relayPort = config.relayPort || DEFAULT_AMT_RELAY_PORT;
 
 			if (config.relayAddress) {
 				relayAddress = config.relayAddress;
@@ -352,7 +350,7 @@ export class AMTGateway {
 
 	constructor(options: AMTGatewayOptions) {
 		this.relayAddress = options.relayAddress;
-		this.relayPort = options.relayPort || DEFAULT_AMT_PORT;
+		this.relayPort = options.relayPort || DEFAULT_AMT_RELAY_PORT;
 
 		this.onPacket = options.onPacket || (() => {});
 		this.onStateChange = options.onStateChange || (() => {});

package/src/driad-discovery.ts

@@ -10,6 +10,7 @@
  *   Query: 10.95.25.69.amt.in-addr.arpa (source-based, NOT group-based)
  */
 
+import { DEFAULT_AMT_RELAY_PORT } from "@blockcast/mmt-base";
 import type { DRIADRelay } from "./types.js";
 
 /**
@@ -89,11 +90,7 @@ export class DRIADDiscovery {
 			return [dohRelay];
 		}
 
-		// Final fallback to well-known AMT relays
-		return [
-			{ host: "amt-relay.m2icast.net", port: 2268, priority: 10, weight: 100, asn: 0 },
-			{ host: "amt.akamaistream.net", port: 2268, priority: 20, weight: 50, asn: 0 },
-		];
+		return [];
 	}
 
 	/**
@@ -121,7 +118,7 @@ export class DRIADDiscovery {
 			if (result.Answer && result.Answer.length > 0) {
 				return {
 					host: result.Answer[0].data,
-					port: 2268,
+					port: DEFAULT_AMT_RELAY_PORT,
 					priority: 10,
 					weight: 100,
 					asn: 0,

package/src/endpoint-config.ts

@@ -1,5 +1,13 @@
+import { MMTP_PACKET_ID_MAX, MMTP_SIGNALING_PACKET_ID } from "@blockcast/mmt-base";
+import type {
+	WindowMulticastSubscribeConfig,
+	WindowMulticastSubscribeConfigBytes,
+} from "./types.js";
+
 export type MulticastTransportPreference = "auto" | "native" | "tunnel";
 
+export { DEFAULT_AMT_RELAY_PORT } from "@blockcast/mmt-base";
+
 export interface MulticastEndpointConfig {
 	groupAddress: string;
 	sourceAddress?: string;
@@ -9,6 +17,94 @@ export interface MulticastEndpointConfig {
 	amtRelayPort?: number;
 }
 
+/**
+ * Input accepted by the canonical window.multicast request converter.
+ *
+ * `mode` and the `amtRelay*` fields are internal endpoint-selection state;
+ * they are deliberately not emitted on the page-facing request.  The
+ * resulting `origin` is the only acquisition selector understood by the
+ * gateway.
+ */
+export interface WindowMulticastEndpointInput {
+	group: string;
+	port: number;
+	source?: string;
+	mode?: MulticastTransportPreference;
+	amtRelay?: string;
+	amtRelayPort?: number;
+	packetIds?: readonly number[];
+	tracks?: ReadonlyArray<{ name: string; packetId: number }>;
+}
+
+/**
+ * Convert internal endpoint-selection state to the canonical page contract.
+ *
+ * Native is the default and an explicit `native` selection always wins over
+ * stale relay metadata.  Tunnel/AMT requests must carry the resolved relay
+ * and port; there is no implicit relay-port default at this boundary.
+ *
+ * That rule is deliberate and is NOT the place to fix a relay that names no
+ * port: this is the last hop before the page-facing request, so a default
+ * applied here would be invisible to every caller and to the join it produces.
+ * A catalog relay with no port gets `DEFAULT_AMT_RELAY_PORT` upstream, in the
+ * readers that resolve it, and arrives here explicit like any other
+ * (BLO-38176).
+ */
+export function toWindowMulticastSubscribeConfig(
+	input: WindowMulticastEndpointInput,
+): WindowMulticastSubscribeConfig {
+	if (input.mode !== undefined && !["auto", "native", "tunnel"].includes(input.mode)) {
+		throw new TypeError(`Unsupported multicast mode: ${String(input.mode)}`);
+	}
+	// An explicit non-array (the null "endpoint unusable" sentinel from
+	// selectEndpointPacketIdsForTracks) must not degrade into "no filter".
+	if (input.packetIds !== undefined && !Array.isArray(input.packetIds)) {
+		throw new TypeError(
+			`multicast packetIds must be an array, got ${input.packetIds === null ? "null" : typeof input.packetIds}`,
+		);
+	}
+	// Every join request passes through here, so the track packet_id range is
+	// enforced here rather than trusted from each caller.
+	if (input.packetIds?.some(id => !isMulticastTrackPacketId(id)) ||
+		input.tracks?.some(track => !isMulticastTrackPacketId(track.packetId))) {
+		throw new RangeError(
+			`multicast packetId must be an integer from 1 to ${MMTP_PACKET_ID_MAX}; ` +
+			"packetId 0 is the MMTP signaling flow and is never a track's",
+		);
+	}
+
+	const base = {
+		group: input.group,
+		port: input.port,
+		...(input.source?.trim() ? { source: input.source.trim() } : {}),
+		consume: "bytes" as const,
+		...(input.packetIds?.length ? { packetIds: [...input.packetIds] } : {}),
+	};
+
+	const relay = input.amtRelay?.trim();
+	const wantsAmt = input.mode === "tunnel" ||
+		(input.mode !== "native" && relay !== undefined && relay !== "");
+	if (!wantsAmt) {
+		const native: WindowMulticastSubscribeConfigBytes = {
+			...base,
+			origin: "ip-multicast",
+			...(input.tracks?.length ? { tracks: input.tracks.map(({ name, packetId }) => ({ name, packetId })) } : {}),
+		};
+		return native;
+	}
+
+	const relayPort = input.amtRelayPort;
+	if (!relay || relayPort === undefined || !isPositivePort(relayPort)) {
+		throw new TypeError("AMT requires a resolved relay and a valid relay port");
+	}
+	return {
+		...base,
+		origin: "amt",
+		relay,
+		relayPort,
+	};
+}
+
 export function isValidMulticastGroupAddress(address: string | undefined): boolean {
 	const value = address?.trim().toLowerCase();
 	if (!value) return false;
@@ -58,6 +154,19 @@ export function multicastEndpointKey(endpoint: MulticastEndpointConfig): string
 	]);
 }
 
+/**
+ * True when `value` may be advertised as a multicast track's MMTP `packet_id`:
+ * an integer in 1..MMTP_PACKET_ID_MAX. packet_id 0 (MMTP_SIGNALING_PACKET_ID)
+ * is the MMTP signaling flow -- the FFmpeg `moq_mmt` muxer sends the AL-FEC
+ * message (0x0203) on it into the same group as the media -- so it is never a
+ * track's. Only a number qualifies: a string, boolean or null is not coerced.
+ */
+export function isMulticastTrackPacketId(value: unknown): value is number {
+	return Number.isInteger(value) &&
+		(value as number) > MMTP_SIGNALING_PACKET_ID &&
+		(value as number) <= MMTP_PACKET_ID_MAX;
+}
+
 export function isUsableMulticastEndpoint(
 	endpoint: { groupAddress?: string; port?: unknown } | undefined,
 ): boolean {
@@ -65,6 +174,46 @@ export function isUsableMulticastEndpoint(
 	return isValidMulticastGroupAddress(endpoint?.groupAddress) && isPositivePort(port);
 }
 
+/**
+ * Unprefixed aliases of the `mc_` URL override keys, retired in BLO-37507, each
+ * paired with the key that replaces it.
+ */
+const RETIRED_MULTICAST_URL_PARAMS = [
+	["amt_relay", "mc_amt_relay"],
+	["amt_relay_port", "mc_amt_relay_port"],
+] as const;
+
+/**
+ * Reject a URL multicast override that still carries a retired unprefixed alias.
+ *
+ * Both URL readers call this only once a valid override is established (a valid
+ * multicast `mc_group` and a valid `mc_port`; `readUrlMulticastConfig` also
+ * requires the whole endpoint to normalize), which is where they used to read
+ * the aliases: a link that
+ * relied on one fails here with its replacement named, instead of silently
+ * losing its AMT relay (and, in `readUrlMulticastConfig`, its tunnel mode).
+ * Presence is the error, whatever the value and whether or not the `mc_` form
+ * is also present: quietly preferring one of two keys is the tolerant read being
+ * retired. Outside an override the readers read no override key at all, the
+ * `mc_` forms included, so the bare names are left to the page; they are live
+ * page parameters elsewhere, and keeping clear of those is what the `mc_`
+ * namespace is for.
+ */
+export function assertNoRetiredMulticastUrlParams(params: URLSearchParams): void {
+	for (const [retired, replacement] of RETIRED_MULTICAST_URL_PARAMS) {
+		if (params.has(retired)) {
+			throw new Error(
+				`multicast URL override: query parameter "${retired}" is retired; use "${replacement}"`,
+			);
+		}
+	}
+}
+
+/**
+ * Read an explicit multicast endpoint override from `mc_*` URL parameters.
+ * Throws when an override carries a retired unprefixed alias
+ * (`assertNoRetiredMulticastUrlParams`).
+ */
 export function readUrlMulticastConfig(
 	search: string | URLSearchParams = typeof location === "undefined" ? "" : location.search,
 ): MulticastEndpointConfig | undefined {
@@ -73,12 +222,12 @@ export function readUrlMulticastConfig(
 	const port = positivePort(params.get("mc_port"));
 	if (!groupAddress || !port) return undefined;
 
-	const amtRelay = params.get("mc_amt_relay") || params.get("amt_relay") || undefined;
-	const amtRelayPort = positivePort(params.get("mc_amt_relay_port") || params.get("amt_relay_port"));
+	const amtRelay = params.get("mc_amt_relay") || undefined;
+	const amtRelayPort = positivePort(params.get("mc_amt_relay_port"));
 	const requestedMode = params.get("mc_mode");
 	const mode = amtRelay ? "tunnel" : multicastMode(requestedMode);
 
-	return normalizeMulticastEndpoint({
+	const endpoint = normalizeMulticastEndpoint({
 		groupAddress,
 		sourceAddress: params.get("mc_source") || undefined,
 		port,
@@ -86,6 +235,11 @@ export function readUrlMulticastConfig(
 		...(amtRelay ? { amtRelay } : {}),
 		...(amtRelayPort ? { amtRelayPort } : {}),
 	});
+	// An endpoint that does not normalize (e.g. a non-multicast mc_group) is no
+	// override, so the page keeps its own bare names; the same scope
+	// readPlayerMulticastConfig applies by validating the group first.
+	if (endpoint) assertNoRetiredMulticastUrlParams(params);
+	return endpoint;
 }
 
 export function isMulticastExplicitlyDisabled(

package/src/index.ts

@@ -26,6 +26,7 @@
 // Types (new generic names)
 export type {
 	TransportConfig,
+	TransportConnectConfig,
 	TransportSubscription,
 	QualityLevel,
 	TransportCapabilities,
@@ -35,16 +36,15 @@ export type {
 	AmtRelayInfo,
 	GroupKey,
 	PacketMetadata,
-	MfuFragment,
-	ReassembledMfu,
-	ProcessingStats,
-	MmtFecClientOptions,
 	Micro,
 	SyncDecision,
 	WindowMulticastSubscribeConfig,
+	WindowMulticastSubscribeConfigBytes,
+	WindowMulticastSubscribeConfigAmt,
 	WindowMulticastSubscriptionState,
 	WindowMulticastSubscriptionEventMap,
 	WindowMulticastSubscription,
+	WindowMulticastDelivery,
 	WindowMulticastCapabilities,
 	WindowMulticastGateway,
 	// Consolidated from @blockcast/multicast
@@ -54,40 +54,28 @@ export type {
 	SubscriptionState,
 	SubscriptionStats,
 	MulticastSubscriptionHandle,
-	FecConfig,
-	FecStats,
-	MulticastConfigWithFec,
 	MulticastBridge,
 	// FEC types per draft-ramadan-moq-fec-00
 	MoqFecConfig,
 	RepairObjectHeader,
-	// @deprecated - use TransportConfig and TransportSubscription instead
-	SSMConfig,
-	SSMSubscription,
 } from "./types.js";
 
 // FEC constants and utilities per draft-ramadan-moq-fec-00
 export {
-	FEC_CONFIG_MESSAGE_TYPE,
-	REPAIR_TRACK_SUFFIX,
 	repairTrackPath,
-	isRepairTrack,
-	sourceTrackFromRepair,
 	MoqFecAlgorithm,
 } from "./types.js";
 
-// Transport Manager (renamed from SSMTransportManager)
 export { TransportManager, transportManager } from "./transport-manager.js";
 
-// @deprecated - Use TransportManager and transportManager instead
-export { SSMTransportManager, ssmTransport } from "./transport-manager.js";
-
 // DRIAD Discovery
 export { DRIADDiscovery, driadDiscovery } from "./driad-discovery.js";
 
 // Adaptive Bitrate Controller
 export {
 	AdaptiveBitrateController,
+	validateQualityLadder,
+	type AdaptiveBitrateControllerOptions,
 	QUALITY_LEVELS,
 	type FecStatsForAbr,
 } from "./abr-controller.js";
@@ -104,23 +92,59 @@ export {
 	DEFAULT_JOIN_DEADLINE_MS,
 	goodputFromStats,
 	type GoodputSample,
+	type HeadroomSample,
 	type MulticastTierPacket,
 	type OrchestratorCommand,
 	type OrchestratorOptions,
 	type OrchestratorState,
 } from "./multicast-orchestrator.js";
 
+export {
+	createMulticastSignalingReconciler,
+	normalizeCatalogEndpoints,
+	type MulticastSignalingEndpoint,
+} from "./multicast-signaling-reconciler.js";
+
+export {
+	catalogTierEndpoints,
+	endpointCarriesMedia,
+	endpointToMulticastConfig,
+	hasMulticastCatalogBaseline,
+	hasUnicastMediaRenditions,
+	isMulticastOnlyCatalog,
+	isRecoverableMulticastSignalReadError,
+	mergeUrlMulticastPolicy,
+	normalizeMulticastConfig,
+	readPlayerMulticastConfig,
+	requiresMulticastCapability,
+	sameMulticastConfig,
+	selectEndpointPacketIds,
+	selectEndpointPacketIdsForTracks,
+	selectMulticastCandidate,
+	selectMulticastCandidateForTracks,
+	urlOverrideBlocksMulticastCandidate,
+	withMulticastEndpoints,
+	catalogQualityLadder,
+	type PlayerMulticastConfig,
+	type MulticastTrackSelection,
+} from "./multicast-catalog-policy.js";
+
 export {
 	isMulticastExplicitlyDisabled,
+	isMulticastTrackPacketId,
 	isUsableMulticastEndpoint,
 	isValidMulticastGroupAddress,
 	multicastEndpointKey,
 	normalizeMulticastEndpoint,
 	readUrlMulticastConfig,
+	toWindowMulticastSubscribeConfig,
 	type MulticastEndpointConfig,
 	type MulticastTransportPreference,
+	type WindowMulticastEndpointInput,
 } from "./endpoint-config.js";
 
+export { subscriptionDeliversPacketBatches } from "./packet-batch.js";
+
 export {
 	MulticastSubscriptionPool,
 	multicastSubscriptionPool,
@@ -129,8 +153,11 @@ export {
 } from "./multicast-subscription-pool.js";
 
 export {
+	classifyStall,
 	TransportStallDetector,
 	type FecProgressSnapshot,
+	type PlayerStallClassification,
+	type PlayerStallSnapshot,
 	type StallDetectorConfig,
 } from "./stall-detector.js";
 
@@ -158,6 +185,15 @@ export {
 	type FallbackTrack,
 } from "./unicast-fallback.js";
 
+export {
+	MOQT_PUBLISHER_PRIORITY,
+	MOQT_SUBSCRIBER_PRIORITY,
+	moqtPublisherPriority,
+	type MoqtPublisherPriority,
+	moqtSubscriberPriority,
+	type MoqtSubscriberPriority,
+} from "./moqt-priority.js";
+
 // AMT Gateway
 export {
 	AMTGatewayManager,
@@ -167,21 +203,6 @@ export {
 	type AMTGatewayOptions,
 } from "./amt-gateway.js";
 
-// FEC Client
-export {
-	MmtFecClient,
-	createMulticastFecHandler,
-	setupMmtFec,
-	// MoQ FEC Client (for WebTransport)
-	MoqFecClient,
-	createMoqFecClient,
-	loadMmtWasm,
-	type MoqFecClientConfig,
-	type MoqFecClientStats,
-	// FEC decoder configuration (RFC 6330 OTI parameters)
-	type FecDecoderConfig,
-} from "./fec-client.js";
-
 // A/V Sync Clock
 export {
 	SharedClock,

package/src/moqt-priority.ts

@@ -0,0 +1,51 @@
+const MAX_MOQT_PRIORITY = 0xff;
+
+declare const subscriberPriorityBrand: unique symbol;
+declare const publisherPriorityBrand: unique symbol;
+
+export type MoqtSubscriberPriority = number & { readonly [subscriberPriorityBrand]: true };
+export type MoqtPublisherPriority = number & { readonly [publisherPriorityBrand]: true };
+
+function moqtPriority(value: number, field: string): number {
+	if (!Number.isInteger(value) || value < 0 || value > MAX_MOQT_PRIORITY) {
+		throw new RangeError(`${field} must be an integer in [0, ${MAX_MOQT_PRIORITY}], got ${value}`);
+	}
+	return value;
+}
+
+/** Validate a protocol-native MOQT subscriber priority without transforming it. */
+export function moqtSubscriberPriority(value: number): MoqtSubscriberPriority {
+	return moqtPriority(value, "MOQT subscriber priority") as MoqtSubscriberPriority;
+}
+
+/** Validate a protocol-native MOQT publisher priority without transforming it. */
+export function moqtPublisherPriority(value: number): MoqtPublisherPriority {
+	return moqtPriority(value, "MOQT publisher priority") as MoqtPublisherPriority;
+}
+
+/** Shared media subscription policy on MOQT's native lower-number-wins scale. */
+export const MOQT_SUBSCRIBER_PRIORITY = Object.freeze({
+	catalog: moqtSubscriberPriority(0),
+	/**
+	 * @deprecated A repair FETCH's SUBSCRIBER_PRIORITY is derived per request
+	 * from the catalog source and repair priorities (draft-ramadan-moq-fec
+	 * §11.4.5), not a player constant. Use the `subscriberPriority` that
+	 * `@blockcast/mmt-container`'s `wireRepairFetch` puts on each
+	 * `RepairFetchRequest` (`repairFetchSubscriberPriority`).
+	 */
+	deadlineRepair: moqtSubscriberPriority(0),
+	audio: moqtSubscriberPriority(1),
+	video: moqtSubscriberPriority(2),
+	/**
+	 * @deprecated See `deadlineRepair`: use the request's catalog-derived
+	 * `RepairFetchRequest.subscriberPriority` (draft-ramadan-moq-fec §11.4.5).
+	 */
+	backgroundRepair: moqtSubscriberPriority(3),
+});
+
+/** Publisher priority bands from draft-ramadan-moq-fec section 10. */
+export const MOQT_PUBLISHER_PRIORITY = Object.freeze({
+	catalog: moqtPublisherPriority(32),
+	source: moqtPublisherPriority(128),
+	repair: moqtPublisherPriority(240),
+});