@videojs/spf 10.0.0-beta.9 → 10.0.0-rc.2

package/dist/default/media/mp4/timestamp-origin.js

@@ -0,0 +1,95 @@
+import { findBox, iterateBoxesOfType, readFourCC, readFullBoxVersion, toDataView } from "./box.js";
+//#region src/media/mp4/timestamp-origin.ts
+/**
+* Decode-time origin extraction from fMP4/CMAF segments.
+*
+* Non-zero-PTS sources encode media at a non-zero start time (an instant clip starting at asset second 60, an Apple
+* bipbop asset starting at 10s, …). To relocate such a source onto a 0-based presentation timeline via
+* `SourceBuffer.timestampOffset`, the engine needs that start time — the **decode-time origin** — read straight from
+* the container:
+*
+* - `tfdt.baseMediaDecodeTime` (from a media segment's `moof`) — the decode time of the segment's first sample, in the
+*   track's media timescale. This is a DTS: relocating by `−(baseMediaDecodeTime / timescale)` lands the earliest DTS
+*   at exactly 0, so a negative-DTS append failure on Chromium is impossible by construction.
+* - `mdhd.timescale` (from the init segment's `moov`) — ticks per second for that track, needed to convert the raw tick
+*   count to seconds.
+*
+* ## Presumptive vs. track-selected reads
+*
+* The two variants share only the leaf field-readers (`mdhd` timescale, `tfdt` baseMediaDecodeTime) and the box walker.
+* Everything else differs, and the split is deliberate so the presumptive pair is _proportionally_ smaller under
+* tree-shaking:
+*
+* - **Presumptive** — {@link readFirstMediaTimescale} / {@link readFirstBaseMediaDecodeTime} read the first `mdhd`
+*   timescale and first `tfdt` baseMediaDecodeTime. There's no `track_id` (nothing to match against) and no
+*   `trak`/`traf` iteration — a direct `findBox` to the first leaf. Correct when the init/segment holds a single media
+*   track (the common CMAF case). A caption-free platform imports only this pair and tree-shakes away all the matching
+*   machinery below.
+* - **Track-selected** — {@link findMediaTrack} / {@link readBaseMediaDecodeTime}. `findMediaTrack` returns `{ trackId,
+*   timescale }` for the `trak` whose `hdlr` handler matches; `readBaseMediaDecodeTime` takes that `trackId` and reads
+*   the `traf` whose `tfhd.track_id` matches. The `track_id` is the join that ties one track's timescale to the _same_
+*   track's baseMediaDecodeTime — required when a source muxes CEA-608/708 captions (a `clcp` track shares the same
+*   `moov` and `moof`, each track with its own timescale + baseMediaDecodeTime, so a presumptive read there risks
+*   `300000 / 6000 = 50s` instead of `60000 / 6000 = 10s`). This pair adds `trak`/`traf` iteration plus the handler and
+*   `track_id` reads. We only ever ask for buffered media handlers (`vide` / `soun`); the caption track is never
+*   selected — we read the origin, not the captions (caption _rendering_ is out of scope).
+*
+* Both raw values are returned un-divided to leave room for an edit-list (`elst`) presentation-time correction term if
+* a source ever carries one — the validated streams do not.
+*/
+/**
+* The `track_ID` + timescale of the `trak` whose `mdhd` handler matches `handlerType`, skipping a muxed `clcp` caption
+* track. `undefined` if no matching track exists.
+*/
+function findMediaTrack(initSegment, handlerType) {
+	const view = toDataView(initSegment);
+	const moov = findBox(view, ["moov"]);
+	if (!moov) return void 0;
+	for (const trak of iterateBoxesOfType(view, "trak", moov.dataStart, moov.end)) {
+		if (readTrakHandler(view, trak) !== handlerType) continue;
+		const tkhd = findBox(view, ["tkhd"], trak.dataStart, trak.end);
+		const mdhd = findBox(view, ["mdia", "mdhd"], trak.dataStart, trak.end);
+		if (!tkhd || !mdhd) return void 0;
+		return {
+			trackId: view.getUint32(tkhd.dataStart + 4 + (readFullBoxVersion(view, tkhd.dataStart) === 1 ? 16 : 8)),
+			timescale: readMdhdTimescale(view, mdhd)
+		};
+	}
+}
+/**
+* `baseMediaDecodeTime` (in the track's media timescale) from the `traf` matching `trackId` (via `tfhd.track_id`) —
+* required for muxed multi-`traf` segments. `undefined` if no matching `tfdt` exists.
+*/
+function readBaseMediaDecodeTime(mediaSegment, trackId) {
+	const view = toDataView(mediaSegment);
+	const moof = findBox(view, ["moof"]);
+	if (!moof) return void 0;
+	for (const traf of iterateBoxesOfType(view, "traf", moof.dataStart, moof.end)) {
+		if (readTrafTrackId(view, traf) !== trackId) continue;
+		const tfdt = findBox(view, ["tfdt"], traf.dataStart, traf.end);
+		return tfdt ? readTfdtBaseMediaDecodeTime(view, tfdt) : void 0;
+	}
+}
+/** `mdhd.timescale`: FullBox version(1)+flags(3) + dates (v0: 4+4, v1: 8+8) + timescale. */
+function readMdhdTimescale(view, mdhd) {
+	return view.getUint32(mdhd.dataStart + 4 + (readFullBoxVersion(view, mdhd.dataStart) === 1 ? 16 : 8));
+}
+/** `tfdt.baseMediaDecodeTime`: FullBox, then the value — v0: (4), v1: (8). */
+function readTfdtBaseMediaDecodeTime(view, tfdt) {
+	const at = tfdt.dataStart + 4;
+	return readFullBoxVersion(view, tfdt.dataStart) === 1 ? Number(view.getBigUint64(at)) : view.getUint32(at);
+}
+/** `hdlr.handler_type` for a `trak`: FullBox version(1)+flags(3) + pre_defined(4) + handler_type(4). */
+function readTrakHandler(view, trak) {
+	const hdlr = findBox(view, ["mdia", "hdlr"], trak.dataStart, trak.end);
+	return hdlr ? readFourCC(view, hdlr.dataStart + 8) : void 0;
+}
+/** `tfhd.track_id` for a `traf`: FullBox version(1)+flags(3) + track_id(4). */
+function readTrafTrackId(view, traf) {
+	const tfhd = findBox(view, ["tfhd"], traf.dataStart, traf.end);
+	return tfhd ? view.getUint32(tfhd.dataStart + 4) : void 0;
+}
+//#endregion
+export { findMediaTrack, readBaseMediaDecodeTime };
+
+//# sourceMappingURL=timestamp-origin.js.map

package/dist/default/media/mp4/timestamp-origin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp-origin.js","names":[],"sources":["../../../../src/media/mp4/timestamp-origin.ts"],"sourcesContent":["/**\n * Decode-time origin extraction from fMP4/CMAF segments.\n *\n * Non-zero-PTS sources encode media at a non-zero start time (an instant clip starting at asset second 60, an Apple\n * bipbop asset starting at 10s, …). To relocate such a source onto a 0-based presentation timeline via\n * `SourceBuffer.timestampOffset`, the engine needs that start time — the **decode-time origin** — read straight from\n * the container:\n *\n * - `tfdt.baseMediaDecodeTime` (from a media segment's `moof`) — the decode time of the segment's first sample, in the\n *   track's media timescale. This is a DTS: relocating by `−(baseMediaDecodeTime / timescale)` lands the earliest DTS\n *   at exactly 0, so a negative-DTS append failure on Chromium is impossible by construction.\n * - `mdhd.timescale` (from the init segment's `moov`) — ticks per second for that track, needed to convert the raw tick\n *   count to seconds.\n *\n * ## Presumptive vs. track-selected reads\n *\n * The two variants share only the leaf field-readers (`mdhd` timescale, `tfdt` baseMediaDecodeTime) and the box walker.\n * Everything else differs, and the split is deliberate so the presumptive pair is _proportionally_ smaller under\n * tree-shaking:\n *\n * - **Presumptive** — {@link readFirstMediaTimescale} / {@link readFirstBaseMediaDecodeTime} read the first `mdhd`\n *   timescale and first `tfdt` baseMediaDecodeTime. There's no `track_id` (nothing to match against) and no\n *   `trak`/`traf` iteration — a direct `findBox` to the first leaf. Correct when the init/segment holds a single media\n *   track (the common CMAF case). A caption-free platform imports only this pair and tree-shakes away all the matching\n *   machinery below.\n * - **Track-selected** — {@link findMediaTrack} / {@link readBaseMediaDecodeTime}. `findMediaTrack` returns `{ trackId,\n *   timescale }` for the `trak` whose `hdlr` handler matches; `readBaseMediaDecodeTime` takes that `trackId` and reads\n *   the `traf` whose `tfhd.track_id` matches. The `track_id` is the join that ties one track's timescale to the _same_\n *   track's baseMediaDecodeTime — required when a source muxes CEA-608/708 captions (a `clcp` track shares the same\n *   `moov` and `moof`, each track with its own timescale + baseMediaDecodeTime, so a presumptive read there risks\n *   `300000 / 6000 = 50s` instead of `60000 / 6000 = 10s`). This pair adds `trak`/`traf` iteration plus the handler and\n *   `track_id` reads. We only ever ask for buffered media handlers (`vide` / `soun`); the caption track is never\n *   selected — we read the origin, not the captions (caption _rendering_ is out of scope).\n *\n * Both raw values are returned un-divided to leave room for an edit-list (`elst`) presentation-time correction term if\n * a source ever carries one — the validated streams do not.\n */\nimport { type Box, findBox, iterateBoxesOfType, readFourCC, readFullBoxVersion, toDataView } from './box';\n\n/** MSE-buffered media handler types (`mdhd`/`hdlr`). Captions/subtitles excluded. */\nexport type MediaHandlerType = 'vide' | 'soun';\n\nexport interface MediaTrackInfo {\n  /** `tkhd.track_id` — used to match the corresponding `traf` in media segments. */\n  trackId: number;\n  /** `mdhd.timescale` — ticks per second for this track. */\n  timescale: number;\n}\n\n// --- presumptive: first leaf, no track_id, no iteration -----------------------\n\n/**\n * Presumptive: the `timescale` of the **first** `mdhd` in an init segment. Correct only for single-media-track inits —\n * for muxed captions use {@link findMediaTrack}. `undefined` if no `mdhd` exists.\n */\nexport function readFirstMediaTimescale(initSegment: ArrayBuffer | Uint8Array): number | undefined {\n  const view = toDataView(initSegment);\n  const mdhd = findBox(view, ['moov', 'trak', 'mdia', 'mdhd']);\n\n  return mdhd ? readMdhdTimescale(view, mdhd) : undefined;\n}\n\n/**\n * Presumptive: `baseMediaDecodeTime` from the **first** `tfdt` of a media segment. Correct only for single-`traf`\n * segments — for muxed captions use {@link readBaseMediaDecodeTime}. `undefined` if no `tfdt` exists.\n */\nexport function readFirstBaseMediaDecodeTime(mediaSegment: ArrayBuffer | Uint8Array): number | undefined {\n  const view = toDataView(mediaSegment);\n  const tfdt = findBox(view, ['moof', 'traf', 'tfdt']);\n\n  return tfdt ? readTfdtBaseMediaDecodeTime(view, tfdt) : undefined;\n}\n\n// --- track-selected: iterate + match by handler / track_id --------------------\n\n/**\n * The `track_ID` + timescale of the `trak` whose `mdhd` handler matches `handlerType`, skipping a muxed `clcp` caption\n * track. `undefined` if no matching track exists.\n */\nexport function findMediaTrack(\n  initSegment: ArrayBuffer | Uint8Array,\n  handlerType: MediaHandlerType\n): MediaTrackInfo | undefined {\n  const view = toDataView(initSegment);\n  const moov = findBox(view, ['moov']);\n  if (!moov) return undefined;\n\n  for (const trak of iterateBoxesOfType(view, 'trak', moov.dataStart, moov.end)) {\n    if (readTrakHandler(view, trak) !== handlerType) continue;\n\n    const tkhd = findBox(view, ['tkhd'], trak.dataStart, trak.end);\n    const mdhd = findBox(view, ['mdia', 'mdhd'], trak.dataStart, trak.end);\n    if (!tkhd || !mdhd) return undefined;\n\n    // tkhd FullBox: version(1)+flags(3), creation/modification dates (v0: 4+4, v1:\n    // 8+8), then track_id.\n    const trackId = view.getUint32(tkhd.dataStart + 4 + (readFullBoxVersion(view, tkhd.dataStart) === 1 ? 16 : 8));\n\n    return { trackId, timescale: readMdhdTimescale(view, mdhd) };\n  }\n\n  return undefined;\n}\n\n/**\n * `baseMediaDecodeTime` (in the track's media timescale) from the `traf` matching `trackId` (via `tfhd.track_id`) —\n * required for muxed multi-`traf` segments. `undefined` if no matching `tfdt` exists.\n */\nexport function readBaseMediaDecodeTime(mediaSegment: ArrayBuffer | Uint8Array, trackId: number): number | undefined {\n  const view = toDataView(mediaSegment);\n  const moof = findBox(view, ['moof']);\n  if (!moof) return undefined;\n\n  for (const traf of iterateBoxesOfType(view, 'traf', moof.dataStart, moof.end)) {\n    if (readTrafTrackId(view, traf) !== trackId) continue;\n\n    const tfdt = findBox(view, ['tfdt'], traf.dataStart, traf.end);\n\n    return tfdt ? readTfdtBaseMediaDecodeTime(view, tfdt) : undefined;\n  }\n\n  return undefined;\n}\n\n// --- shared leaf field-readers ------------------------------------------------\n\n/** `mdhd.timescale`: FullBox version(1)+flags(3) + dates (v0: 4+4, v1: 8+8) + timescale. */\nfunction readMdhdTimescale(view: DataView, mdhd: Box): number {\n  return view.getUint32(mdhd.dataStart + 4 + (readFullBoxVersion(view, mdhd.dataStart) === 1 ? 16 : 8));\n}\n\n/** `tfdt.baseMediaDecodeTime`: FullBox, then the value — v0: (4), v1: (8). */\nfunction readTfdtBaseMediaDecodeTime(view: DataView, tfdt: Box): number {\n  const at = tfdt.dataStart + 4;\n\n  return readFullBoxVersion(view, tfdt.dataStart) === 1 ? Number(view.getBigUint64(at)) : view.getUint32(at);\n}\n\n// --- track-selection readers (referenced only by the track-selected variants) -\n\n/** `hdlr.handler_type` for a `trak`: FullBox version(1)+flags(3) + pre_defined(4) + handler_type(4). */\nfunction readTrakHandler(view: DataView, trak: Box): string | undefined {\n  const hdlr = findBox(view, ['mdia', 'hdlr'], trak.dataStart, trak.end);\n\n  return hdlr ? readFourCC(view, hdlr.dataStart + 8) : undefined;\n}\n\n/** `tfhd.track_id` for a `traf`: FullBox version(1)+flags(3) + track_id(4). */\nfunction readTrafTrackId(view: DataView, traf: Box): number | undefined {\n  const tfhd = findBox(view, ['tfhd'], traf.dataStart, traf.end);\n\n  return tfhd ? view.getUint32(tfhd.dataStart + 4) : undefined;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+EA,SAAgB,eACd,aACA,aAC4B;CAC5B,MAAM,OAAO,WAAW,WAAW;CACnC,MAAM,OAAO,QAAQ,MAAM,CAAC,MAAM,CAAC;CACnC,IAAI,CAAC,MAAM,OAAO,KAAA;CAElB,KAAK,MAAM,QAAQ,mBAAmB,MAAM,QAAQ,KAAK,WAAW,KAAK,GAAG,GAAG;EAC7E,IAAI,gBAAgB,MAAM,IAAI,MAAM,aAAa;EAEjD,MAAM,OAAO,QAAQ,MAAM,CAAC,MAAM,GAAG,KAAK,WAAW,KAAK,GAAG;EAC7D,MAAM,OAAO,QAAQ,MAAM,CAAC,QAAQ,MAAM,GAAG,KAAK,WAAW,KAAK,GAAG;EACrE,IAAI,CAAC,QAAQ,CAAC,MAAM,OAAO,KAAA;EAM3B,OAAO;GAAE,SAFO,KAAK,UAAU,KAAK,YAAY,KAAK,mBAAmB,MAAM,KAAK,SAAS,MAAM,IAAI,KAAK,EAE5F;GAAG,WAAW,kBAAkB,MAAM,IAAI;EAAE;CAC7D;AAGF;;;;;AAMA,SAAgB,wBAAwB,cAAwC,SAAqC;CACnH,MAAM,OAAO,WAAW,YAAY;CACpC,MAAM,OAAO,QAAQ,MAAM,CAAC,MAAM,CAAC;CACnC,IAAI,CAAC,MAAM,OAAO,KAAA;CAElB,KAAK,MAAM,QAAQ,mBAAmB,MAAM,QAAQ,KAAK,WAAW,KAAK,GAAG,GAAG;EAC7E,IAAI,gBAAgB,MAAM,IAAI,MAAM,SAAS;EAE7C,MAAM,OAAO,QAAQ,MAAM,CAAC,MAAM,GAAG,KAAK,WAAW,KAAK,GAAG;EAE7D,OAAO,OAAO,4BAA4B,MAAM,IAAI,IAAI,KAAA;CAC1D;AAGF;;AAKA,SAAS,kBAAkB,MAAgB,MAAmB;CAC5D,OAAO,KAAK,UAAU,KAAK,YAAY,KAAK,mBAAmB,MAAM,KAAK,SAAS,MAAM,IAAI,KAAK,EAAE;AACtG;;AAGA,SAAS,4BAA4B,MAAgB,MAAmB;CACtE,MAAM,KAAK,KAAK,YAAY;CAE5B,OAAO,mBAAmB,MAAM,KAAK,SAAS,MAAM,IAAI,OAAO,KAAK,aAAa,EAAE,CAAC,IAAI,KAAK,UAAU,EAAE;AAC3G;;AAKA,SAAS,gBAAgB,MAAgB,MAA+B;CACtE,MAAM,OAAO,QAAQ,MAAM,CAAC,QAAQ,MAAM,GAAG,KAAK,WAAW,KAAK,GAAG;CAErE,OAAO,OAAO,WAAW,MAAM,KAAK,YAAY,CAAC,IAAI,KAAA;AACvD;;AAGA,SAAS,gBAAgB,MAAgB,MAA+B;CACtE,MAAM,OAAO,QAAQ,MAAM,CAAC,MAAM,GAAG,KAAK,WAAW,KAAK,GAAG;CAE7D,OAAO,OAAO,KAAK,UAAU,KAAK,YAAY,CAAC,IAAI,KAAA;AACrD"}

package/dist/default/media/primitives/resolution.js

@@ -0,0 +1,26 @@
+//#region src/media/primitives/resolution.ts
+/**
+* Apply `scale` to a size and normalize it to whole pixels, or `undefined` where that leaves nothing to describe.
+*
+* Rounded because pixels are whole and a fractional scale doesn't divide a surface evenly. A non-positive or non-finite
+* axis yields `undefined` rather than a zero-area reading: an element that isn't being rendered reports `0 × 0` and a
+* nonsense dimension reports `NaN`, and the caps consuming this read absence as "unknown, don't cap" while an area of
+* zero would read as a cap of zero — pinning every source to its smallest rendition.
+*
+* @param size - Dimensions to project, in the units `scale` converts from
+* @param scale - Multiplier for both axes, e.g. `devicePixelRatio`; defaults to 1
+* @returns The scaled, whole-pixel resolution, or `undefined` when either axis
+* doesn't survive it
+*/
+function scaleResolution(size, scale = 1) {
+	const width = Math.round(size.width * scale);
+	const height = Math.round(size.height * scale);
+	return width > 0 && height > 0 ? {
+		width,
+		height
+	} : void 0;
+}
+//#endregion
+export { scaleResolution };
+
+//# sourceMappingURL=resolution.js.map

package/dist/default/media/primitives/resolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolution.js","names":[],"sources":["../../../../src/media/primitives/resolution.ts"],"sourcesContent":["/**\n * Pixel dimensions, and the one projection every reader of them needs.\n *\n * Shared by the surfaces a rendition cap measures — a screen (`media/dom/screen`), a player element\n * (`behaviors/dom/track-player-resolution`) — and by the caps that compare renditions against them. Lives outside the\n * DOM layer because scaling and rounding two numbers needs no DOM, which is also what lets the DOM-free selection rules\n * name the type they read instead of restating its shape.\n */\n\n/**\n * A surface's pixel dimensions.\n *\n * A width and a height rather than a `\"720p\"`-style tier, because a tier only describes a surface once you assume its\n * aspect ratio — the assumption that mis-measures an anamorphic or otherwise non-16:9 rendition.\n */\nexport interface Resolution {\n  readonly width: number;\n  readonly height: number;\n}\n\n/**\n * Apply `scale` to a size and normalize it to whole pixels, or `undefined` where that leaves nothing to describe.\n *\n * Rounded because pixels are whole and a fractional scale doesn't divide a surface evenly. A non-positive or non-finite\n * axis yields `undefined` rather than a zero-area reading: an element that isn't being rendered reports `0 × 0` and a\n * nonsense dimension reports `NaN`, and the caps consuming this read absence as \"unknown, don't cap\" while an area of\n * zero would read as a cap of zero — pinning every source to its smallest rendition.\n *\n * @param size - Dimensions to project, in the units `scale` converts from\n * @param scale - Multiplier for both axes, e.g. `devicePixelRatio`; defaults to 1\n * @returns The scaled, whole-pixel resolution, or `undefined` when either axis\n * doesn't survive it\n */\nexport function scaleResolution(size: Resolution, scale = 1): Resolution | undefined {\n  const width = Math.round(size.width * scale);\n  const height = Math.round(size.height * scale);\n\n  return width > 0 && height > 0 ? { width, height } : undefined;\n}\n"],"mappings":";;;;;;;;;;;;;;AAiCA,SAAgB,gBAAgB,MAAkB,QAAQ,GAA2B;CACnF,MAAM,QAAQ,KAAK,MAAM,KAAK,QAAQ,KAAK;CAC3C,MAAM,SAAS,KAAK,MAAM,KAAK,SAAS,KAAK;CAE7C,OAAO,QAAQ,KAAK,SAAS,IAAI;EAAE;EAAO;CAAO,IAAI,KAAA;AACvD"}

package/dist/default/media/primitives/select-tracks.js

@@ -0,0 +1,97 @@
+//#region src/media/primitives/select-tracks.ts
+/**
+* Test whether a track matches a partial-track description: every present, defined field of `filter` equals the
+* track's. Absent or `undefined` filter fields don't constrain. Used to narrow candidates by a user selection (`{ id
+* }`, `{ language }`, `{ height }`, …).
+*
+* @param track - The track to test
+* @param filter - Partial-track description; only present, defined fields constrain
+* @returns `true` when the track matches every constraining field
+*/
+function matchesPartialTrack(track, filter) {
+	for (const key in filter) {
+		const filterValue = filter[key];
+		if (filterValue !== void 0 && track[key] !== filterValue) return false;
+	}
+	return true;
+}
+/** Missing dimensions are treated as area `0`, so a track without them ranks last. */
+function pixelArea(track) {
+	return (track.width ?? 0) * (track.height ?? 0);
+}
+/**
+* Narrow to the tracks at or below `maxPixelArea`, and nothing else: no ordering, no fallback. Survivors keep their
+* incoming order, and an empty result is a real answer — "none of these fit".
+*
+* Deliberately only the filter, because as a selection rule this composes under `applyRules`, which already owns both
+* halves a caller might expect here: an empty result is skipped, so a preference can never narrow the candidate set to
+* nothing; and ordering the survivors is a separate rule's job ({@link byDescendingResolution}, bandwidth ABR). Doing
+* either here would duplicate the composer and give one rule two responsibilities.
+*/
+function tracksUnderPixelArea(tracks, maxPixelArea = Number.POSITIVE_INFINITY) {
+	return tracks.filter((track) => pixelArea(track) <= maxPixelArea);
+}
+/**
+* The smallest track area that still covers `minPixelArea`, or `undefined` when no track reaches it.
+*
+* The cap a surface-size rule wants when it should round _up_ to the ladder: a surface between two tiers is covered by
+* the upper one, and capping at the surface's own area instead would serve a picture smaller than the surface and
+* upscale it.
+*
+* Tracks declaring no dimensions compare as area `0` and so never cover anything, which keeps them out of the cap
+* rather than pinning it to zero.
+*/
+function smallestCoveringPixelArea(tracks, minPixelArea) {
+	const covering = tracks.map(pixelArea).filter((area) => area >= minPixelArea);
+	return covering.length ? Math.min(...covering) : void 0;
+}
+/**
+* Compare two tracks by resolution, largest first, with bandwidth as the tiebreak for renditions of identical
+* dimensions. Missing dimensions are treated as area `0`, so a track without them sorts last.
+*
+* A comparator rather than a "highest track" function: the selection-rule chain takes the head of the list it produces,
+* so ranking never has to collapse to a single track. `preferHighestResolution` is `sort` over this and nothing more.
+*/
+function byDescendingResolution(a, b) {
+	return pixelArea(b) - pixelArea(a) || (b.bandwidth ?? 0) - (a.bandwidth ?? 0);
+}
+/**
+* Default audio policy over a candidate list: the three-tier pick a selection-rule chain applies once it has narrowed
+* the candidates.
+*
+* Priority: `preferredAudioLanguage` match → `DEFAULT=YES` → first track.
+*/
+function pickAudioTrackFromTracks(tracks, config) {
+	if (config?.preferredAudioLanguage) {
+		const languageMatch = tracks.find((track) => track.language === config.preferredAudioLanguage);
+		if (languageMatch) return languageMatch.id;
+	}
+	const defaultTrack = tracks.find((track) => track.default === true);
+	if (defaultTrack) return defaultTrack.id;
+	return tracks[0]?.id;
+}
+/**
+* Default text-track policy over a candidate list: the opt-in three-tier pick `switchTextTrack`'s terminal applies once
+* it has narrowed the renditions to the constrained, CDN-scoped set.
+*
+* Priority: `preferredSubtitleLanguage` match → `DEFAULT=YES + AUTOSELECT=YES` (only when `enableDefaultTrack`) →
+* `undefined` (opt-in). FORCED tracks are excluded unless `includeForcedTracks` (Apple-spec: a regular track must carry
+* forced content when both exist, so a forced-only track is redundant).
+*/
+function pickTextTrackFromTracks(tracks, config) {
+	const availableTracks = config?.includeForcedTracks ? tracks : tracks.filter((track) => !track.forced);
+	if (availableTracks.length === 0) return void 0;
+	const { preferredSubtitleLanguage, enableDefaultTrack = false } = config ?? {};
+	if (preferredSubtitleLanguage) {
+		const languageMatch = availableTracks.find((track) => track.language === preferredSubtitleLanguage);
+		if (languageMatch) return languageMatch.id;
+	}
+	if (enableDefaultTrack) {
+		const defaultTrack = availableTracks.find((track) => track.default === true);
+		if (defaultTrack) return defaultTrack.id;
+	}
+}
+//#endregion
+export { byDescendingResolution, matchesPartialTrack, pickAudioTrackFromTracks, pickTextTrackFromTracks, smallestCoveringPixelArea, tracksUnderPixelArea };
+
+//# sourceMappingURL=select-tracks.js.map

package/dist/default/media/primitives/select-tracks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-tracks.js","names":[],"sources":["../../../../src/media/primitives/select-tracks.ts"],"sourcesContent":["import type { MaybeResolvedPresentation, PartiallyResolvedTextTrack, TextTrack } from '../types';\n\n/** State shape for track selection. */\nexport interface TrackSelectionState {\n  presentation?: MaybeResolvedPresentation;\n  selectedVideoTrackId?: string;\n  selectedAudioTrackId?: string;\n  selectedTextTrackId?: string;\n}\n\n/** Configuration for audio track selection. */\nexport interface AudioSelectionConfig {\n  /** Preferred audio language (ISO 639 code, e.g., \"en\", \"es\"). If not specified, selects first audio track. */\n  preferredAudioLanguage?: string;\n}\n\n/** Configuration for text track selection. */\nexport interface TextSelectionConfig {\n  /** Preferred subtitle language (ISO 639 code, e.g., \"en\", \"es\"). If specified, selects matching track if available. */\n  preferredSubtitleLanguage?: string;\n\n  /**\n   * Include FORCED subtitle tracks in selection. Default: false (follows hls.js/http-streaming pattern)\n   *\n   * Note: Per Apple's HLS spec, if content has forced and regular subtitles in the same language, the regular track\n   * MUST contain both forced and regular content. Therefore, forced-only tracks are redundant and excluded by default.\n   */\n  includeForcedTracks?: boolean;\n\n  /**\n   * Auto-select DEFAULT track (requires DEFAULT=YES + AUTOSELECT=YES in HLS). Default: false (user opt-in, matches\n   * hls.js/http-streaming)\n   *\n   * When enabled, tracks marked with both DEFAULT=YES and AUTOSELECT=YES will be automatically selected if no user\n   * preference matches.\n   */\n  enableDefaultTrack?: boolean;\n}\n\n// =============================================================================\n// Helper Functions (Pure Selection Logic)\n//\n// Candidate-list policies and track geometry, for the selection rules in\n// `playback/behaviors/select-tracks.ts` and `playback/behaviors/track-switching.ts`\n// to compose. Nothing here consults a whole presentation or returns a single id:\n// narrowing a list and ordering a list are the two shapes a rule can take, and the\n// rule chain takes the head of what they leave.\n// =============================================================================\n\n/**\n * Test whether a track matches a partial-track description: every present, defined field of `filter` equals the\n * track's. Absent or `undefined` filter fields don't constrain. Used to narrow candidates by a user selection (`{ id\n * }`, `{ language }`, `{ height }`, …).\n *\n * @param track - The track to test\n * @param filter - Partial-track description; only present, defined fields constrain\n * @returns `true` when the track matches every constraining field\n */\nexport function matchesPartialTrack<T>(track: T, filter: Partial<T>): boolean {\n  for (const key in filter) {\n    const filterValue = filter[key as keyof T];\n    if (filterValue !== undefined && track[key as keyof T] !== filterValue) return false;\n  }\n\n  return true;\n}\n\ntype RankableTrack = { id: string; width?: number; height?: number; bandwidth?: number };\n\n/** Missing dimensions are treated as area `0`, so a track without them ranks last. */\nfunction pixelArea(track: RankableTrack): number {\n  return (track.width ?? 0) * (track.height ?? 0);\n}\n\n/**\n * Narrow to the tracks at or below `maxPixelArea`, and nothing else: no ordering, no fallback. Survivors keep their\n * incoming order, and an empty result is a real answer — \"none of these fit\".\n *\n * Deliberately only the filter, because as a selection rule this composes under `applyRules`, which already owns both\n * halves a caller might expect here: an empty result is skipped, so a preference can never narrow the candidate set to\n * nothing; and ordering the survivors is a separate rule's job ({@link byDescendingResolution}, bandwidth ABR). Doing\n * either here would duplicate the composer and give one rule two responsibilities.\n */\nexport function tracksUnderPixelArea<T extends RankableTrack>(\n  tracks: readonly T[],\n  maxPixelArea: number = Number.POSITIVE_INFINITY\n): readonly T[] {\n  return tracks.filter((track) => pixelArea(track) <= maxPixelArea);\n}\n\n/**\n * The smallest track area that still covers `minPixelArea`, or `undefined` when no track reaches it.\n *\n * The cap a surface-size rule wants when it should round _up_ to the ladder: a surface between two tiers is covered by\n * the upper one, and capping at the surface's own area instead would serve a picture smaller than the surface and\n * upscale it.\n *\n * Tracks declaring no dimensions compare as area `0` and so never cover anything, which keeps them out of the cap\n * rather than pinning it to zero.\n */\nexport function smallestCoveringPixelArea(tracks: readonly RankableTrack[], minPixelArea: number): number | undefined {\n  const covering = tracks.map(pixelArea).filter((area) => area >= minPixelArea);\n\n  return covering.length ? Math.min(...covering) : undefined;\n}\n\n/**\n * Compare two tracks by resolution, largest first, with bandwidth as the tiebreak for renditions of identical\n * dimensions. Missing dimensions are treated as area `0`, so a track without them sorts last.\n *\n * A comparator rather than a \"highest track\" function: the selection-rule chain takes the head of the list it produces,\n * so ranking never has to collapse to a single track. `preferHighestResolution` is `sort` over this and nothing more.\n */\nexport function byDescendingResolution(a: RankableTrack, b: RankableTrack): number {\n  return pixelArea(b) - pixelArea(a) || (b.bandwidth ?? 0) - (a.bandwidth ?? 0);\n}\n\n/**\n * Default audio policy over a candidate list: the three-tier pick a selection-rule chain applies once it has narrowed\n * the candidates.\n *\n * Priority: `preferredAudioLanguage` match → `DEFAULT=YES` → first track.\n */\nexport function pickAudioTrackFromTracks(\n  tracks: readonly { id: string; language?: string | undefined; default?: boolean | undefined }[],\n  config?: AudioSelectionConfig\n): string | undefined {\n  // Try preferred language first\n  if (config?.preferredAudioLanguage) {\n    const languageMatch = tracks.find((track) => track.language === config.preferredAudioLanguage);\n    if (languageMatch) return languageMatch.id;\n  }\n\n  // Try default track\n  const defaultTrack = tracks.find((track) => track.default === true);\n  if (defaultTrack) return defaultTrack.id;\n\n  // Fall back to first track\n  return tracks[0]?.id;\n}\n\n/**\n * Default text-track policy over a candidate list: the opt-in three-tier pick `switchTextTrack`'s terminal applies once\n * it has narrowed the renditions to the constrained, CDN-scoped set.\n *\n * Priority: `preferredSubtitleLanguage` match → `DEFAULT=YES + AUTOSELECT=YES` (only when `enableDefaultTrack`) →\n * `undefined` (opt-in). FORCED tracks are excluded unless `includeForcedTracks` (Apple-spec: a regular track must carry\n * forced content when both exist, so a forced-only track is redundant).\n */\nexport function pickTextTrackFromTracks(\n  tracks: readonly (PartiallyResolvedTextTrack | TextTrack)[],\n  config?: TextSelectionConfig\n): string | undefined {\n  const availableTracks = config?.includeForcedTracks ? tracks : tracks.filter((track) => !track.forced);\n  if (availableTracks.length === 0) return undefined;\n\n  const { preferredSubtitleLanguage, enableDefaultTrack = false } = config ?? {};\n\n  if (preferredSubtitleLanguage) {\n    const languageMatch = availableTracks.find((track) => track.language === preferredSubtitleLanguage);\n    if (languageMatch) return languageMatch.id;\n  }\n\n  if (enableDefaultTrack) {\n    const defaultTrack = availableTracks.find((track) => track.default === true);\n    if (defaultTrack) return defaultTrack.id;\n  }\n\n  return undefined;\n}\n"],"mappings":";;;;;;;;;;AA0DA,SAAgB,oBAAuB,OAAU,QAA6B;CAC5E,KAAK,MAAM,OAAO,QAAQ;EACxB,MAAM,cAAc,OAAO;EAC3B,IAAI,gBAAgB,KAAA,KAAa,MAAM,SAAoB,aAAa,OAAO;CACjF;CAEA,OAAO;AACT;;AAKA,SAAS,UAAU,OAA8B;CAC/C,QAAQ,MAAM,SAAS,MAAM,MAAM,UAAU;AAC/C;;;;;;;;;;AAWA,SAAgB,qBACd,QACA,eAAuB,OAAO,mBAChB;CACd,OAAO,OAAO,QAAQ,UAAU,UAAU,KAAK,KAAK,YAAY;AAClE;;;;;;;;;;;AAYA,SAAgB,0BAA0B,QAAkC,cAA0C;CACpH,MAAM,WAAW,OAAO,IAAI,SAAS,CAAC,CAAC,QAAQ,SAAS,QAAQ,YAAY;CAE5E,OAAO,SAAS,SAAS,KAAK,IAAI,GAAG,QAAQ,IAAI,KAAA;AACnD;;;;;;;;AASA,SAAgB,uBAAuB,GAAkB,GAA0B;CACjF,OAAO,UAAU,CAAC,IAAI,UAAU,CAAC,MAAM,EAAE,aAAa,MAAM,EAAE,aAAa;AAC7E;;;;;;;AAQA,SAAgB,yBACd,QACA,QACoB;CAEpB,IAAI,QAAQ,wBAAwB;EAClC,MAAM,gBAAgB,OAAO,MAAM,UAAU,MAAM,aAAa,OAAO,sBAAsB;EAC7F,IAAI,eAAe,OAAO,cAAc;CAC1C;CAGA,MAAM,eAAe,OAAO,MAAM,UAAU,MAAM,YAAY,IAAI;CAClE,IAAI,cAAc,OAAO,aAAa;CAGtC,OAAO,OAAO,EAAE,EAAE;AACpB;;;;;;;;;AAUA,SAAgB,wBACd,QACA,QACoB;CACpB,MAAM,kBAAkB,QAAQ,sBAAsB,SAAS,OAAO,QAAQ,UAAU,CAAC,MAAM,MAAM;CACrG,IAAI,gBAAgB,WAAW,GAAG,OAAO,KAAA;CAEzC,MAAM,EAAE,2BAA2B,qBAAqB,UAAU,UAAU,CAAC;CAE7E,IAAI,2BAA2B;EAC7B,MAAM,gBAAgB,gBAAgB,MAAM,UAAU,MAAM,aAAa,yBAAyB;EAClG,IAAI,eAAe,OAAO,cAAc;CAC1C;CAEA,IAAI,oBAAoB;EACtB,MAAM,eAAe,gBAAgB,MAAM,UAAU,MAAM,YAAY,IAAI;EAC3E,IAAI,cAAc,OAAO,aAAa;CACxC;AAGF"}

package/dist/default/media/text/parse-vtt-timestamp-map.js

@@ -0,0 +1,40 @@
+//#region src/media/text/parse-vtt-timestamp-map.ts
+const TIMESTAMP_MAP_PREFIX = "X-TIMESTAMP-MAP=";
+/**
+* Scrape a WebVTT segment's `X-TIMESTAMP-MAP` header into a {@link TimestampMap} — the only header line we need to
+* correlate LOCAL cue times with the media presentation timeline. Deliberately _not_ a WebVTT parser: cue parsing stays
+* with the browser's native `<track>` parser (which drops this line); this reads just the one header field the native
+* path discards.
+*
+* Returns `undefined` when the segment carries no map (e.g. cues already in absolute presentation time) — per the HLS
+* spec that means LOCAL 0 maps to MPEGTS 0. Tolerant of attribute order and `[HH:]MM:SS.mmm` LOCAL forms.
+*/
+function parseVttTimestampMap(text) {
+	const timestampMapLine = text.split(/\r\n|\r|\n/).find((line) => line.startsWith(TIMESTAMP_MAP_PREFIX));
+	return timestampMapLine ? parseTimestampMapBody(timestampMapLine.slice(16)) : void 0;
+}
+const TimeStampMapParserMap = {
+	LOCAL: parseWebVttTimestamp,
+	MPEGTS: (v) => +v
+};
+function parseTimestampMapBody(body) {
+	return Object.fromEntries(body.split(",").map((kvStr) => {
+		const [k, v] = kvStr.split(/:(.*)/).map((kOrV) => kOrV.trim());
+		return [k?.toLowerCase(), TimeStampMapParserMap[k](v)];
+	}));
+}
+/** Seconds-per-unit for the `[HH:]MM:SS.mmm` parts, right-aligned so a missing HH just drops the leading weight. */
+const VTT_TIMESTAMP_WEIGHTS = [
+	3600,
+	60,
+	1,
+	.001
+];
+function parseWebVttTimestamp(value) {
+	const parts = value.split(/[:.]/);
+	return parts.reduce((acc, val, i) => acc + +val * (VTT_TIMESTAMP_WEIGHTS[i + 4 - parts.length] ?? 0), 0);
+}
+//#endregion
+export { parseVttTimestampMap };
+
+//# sourceMappingURL=parse-vtt-timestamp-map.js.map

package/dist/default/media/text/parse-vtt-timestamp-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-vtt-timestamp-map.js","names":[],"sources":["../../../../src/media/text/parse-vtt-timestamp-map.ts"],"sourcesContent":["/**\n * WebVTT-in-HLS `X-TIMESTAMP-MAP`: correlates a cue's LOCAL (in-file) time with an MPEG-2 presentation timestamp, so\n * LOCAL-authored cues can be placed on the media presentation timeline. Stored raw — the LOCAL→native correction is\n * `mpegts / 90000 - local` — so it stays independent of how (or whether) the presentation is later re-origined. See the\n * HLS spec, RFC 8216bis §3.5.\n */\nexport interface TimestampMap {\n  /** The MPEG-2 presentation timestamp, in 90 kHz ticks, as authored. */\n  mpegts: number;\n  /** The LOCAL cue time the `mpegts` value maps to, in seconds. */\n  local: number;\n}\n\nconst TIMESTAMP_MAP_PREFIX = 'X-TIMESTAMP-MAP=';\n\n/**\n * Scrape a WebVTT segment's `X-TIMESTAMP-MAP` header into a {@link TimestampMap} — the only header line we need to\n * correlate LOCAL cue times with the media presentation timeline. Deliberately _not_ a WebVTT parser: cue parsing stays\n * with the browser's native `<track>` parser (which drops this line); this reads just the one header field the native\n * path discards.\n *\n * Returns `undefined` when the segment carries no map (e.g. cues already in absolute presentation time) — per the HLS\n * spec that means LOCAL 0 maps to MPEGTS 0. Tolerant of attribute order and `[HH:]MM:SS.mmm` LOCAL forms.\n */\nexport function parseVttTimestampMap(text: string): TimestampMap | undefined {\n  const timestampMapLine = text.split(/\\r\\n|\\r|\\n/).find((line) => line.startsWith(TIMESTAMP_MAP_PREFIX));\n\n  return timestampMapLine ? parseTimestampMapBody(timestampMapLine.slice(TIMESTAMP_MAP_PREFIX.length)) : undefined;\n}\n\nconst TimeStampMapParserMap = {\n  LOCAL: parseWebVttTimestamp,\n  MPEGTS: (v: string) => +v,\n} as const;\n\ntype TimeStampMapParserMap = typeof TimeStampMapParserMap;\n\nfunction parseTimestampMapBody(body: string): TimestampMap | undefined {\n  return Object.fromEntries(\n    body.split(',').map((kvStr) => {\n      const [k, v] = kvStr.split(/:(.*)/).map((kOrV) => kOrV.trim());\n\n      return [k?.toLowerCase(), TimeStampMapParserMap[k as keyof TimeStampMapParserMap](v as string)];\n    })\n  ) as TimestampMap;\n}\n\n/** Seconds-per-unit for the `[HH:]MM:SS.mmm` parts, right-aligned so a missing HH just drops the leading weight. */\nconst VTT_TIMESTAMP_WEIGHTS = [3600, 60, 1, 0.001];\n\nfunction parseWebVttTimestamp(value: string): number {\n  const parts = value.split(/[:.]/);\n\n  return parts.reduce((acc, val, i) => acc + +val * (VTT_TIMESTAMP_WEIGHTS[i + 4 - parts.length] ?? 0), 0);\n}\n"],"mappings":";AAaA,MAAM,uBAAuB;;;;;;;;;;AAW7B,SAAgB,qBAAqB,MAAwC;CAC3E,MAAM,mBAAmB,KAAK,MAAM,YAAY,CAAC,CAAC,MAAM,SAAS,KAAK,WAAW,oBAAoB,CAAC;CAEtG,OAAO,mBAAmB,sBAAsB,iBAAiB,MAAM,EAA2B,CAAC,IAAI,KAAA;AACzG;AAEA,MAAM,wBAAwB;CAC5B,OAAO;CACP,SAAS,MAAc,CAAC;AAC1B;AAIA,SAAS,sBAAsB,MAAwC;CACrE,OAAO,OAAO,YACZ,KAAK,MAAM,GAAG,CAAC,CAAC,KAAK,UAAU;EAC7B,MAAM,CAAC,GAAG,KAAK,MAAM,MAAM,OAAO,CAAC,CAAC,KAAK,SAAS,KAAK,KAAK,CAAC;EAE7D,OAAO,CAAC,GAAG,YAAY,GAAG,sBAAsB,EAAiC,CAAC,CAAW,CAAC;CAChG,CAAC,CACH;AACF;;AAGA,MAAM,wBAAwB;CAAC;CAAM;CAAI;CAAG;AAAK;AAEjD,SAAS,qBAAqB,OAAuB;CACnD,MAAM,QAAQ,MAAM,MAAM,MAAM;CAEhC,OAAO,MAAM,QAAQ,KAAK,KAAK,MAAM,MAAM,CAAC,OAAO,sBAAsB,IAAI,IAAI,MAAM,WAAW,IAAI,CAAC;AACzG"}

package/dist/default/media/text/resolve-vtt-metadata.js

@@ -0,0 +1,22 @@
+import { parseVttTimestampMap } from "./parse-vtt-timestamp-map.js";
+//#region src/media/text/resolve-vtt-metadata.ts
+/**
+* Header-level text-segment metadata — the `X-TIMESTAMP-MAP` correlation scraped from a VTT segment's raw bytes.
+* DOM-free (a plain fetch + regex parse): the native `<track>` parser in `media/dom/text` (`resolveVttSegment`)
+* discards this header, so a caller that needs it (e.g. non-zero-PTS relocation) fetches the bytes itself.
+*/
+/**
+* Fetch a VTT segment and scrape only its header metadata (no cue parsing).
+*
+* The native `<track>` parser (`media/dom/text`'s `resolveVttSegment`) discards `X-TIMESTAMP-MAP`, so reading it
+* requires the raw bytes. This is a separate, caller-controlled fetch — the caller decides _when_ metadata is needed
+* (e.g. once per source) rather than paying for it on every segment.
+*/
+async function resolveVttSegmentMetadata(url) {
+	const text = await fetch(url).then((response) => response.text());
+	return { timestampMap: parseVttTimestampMap(text) };
+}
+//#endregion
+export { resolveVttSegmentMetadata };
+
+//# sourceMappingURL=resolve-vtt-metadata.js.map

package/dist/default/media/text/resolve-vtt-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-vtt-metadata.js","names":[],"sources":["../../../../src/media/text/resolve-vtt-metadata.ts"],"sourcesContent":["/**\n * Header-level text-segment metadata — the `X-TIMESTAMP-MAP` correlation scraped from a VTT segment's raw bytes.\n * DOM-free (a plain fetch + regex parse): the native `<track>` parser in `media/dom/text` (`resolveVttSegment`)\n * discards this header, so a caller that needs it (e.g. non-zero-PTS relocation) fetches the bytes itself.\n */\nimport { parseVttTimestampMap, type TimestampMap } from './parse-vtt-timestamp-map';\n\n/**\n * Header-level metadata for a text segment, surfaced alongside its cues. Each field is present only when the segment\n * declared it.\n */\nexport interface TextSegmentMetadata {\n  timestampMap?: TimestampMap;\n}\n\n/**\n * Fetch a VTT segment and scrape only its header metadata (no cue parsing).\n *\n * The native `<track>` parser (`media/dom/text`'s `resolveVttSegment`) discards `X-TIMESTAMP-MAP`, so reading it\n * requires the raw bytes. This is a separate, caller-controlled fetch — the caller decides _when_ metadata is needed\n * (e.g. once per source) rather than paying for it on every segment.\n */\nexport async function resolveVttSegmentMetadata(url: string): Promise<TextSegmentMetadata> {\n  const text = await fetch(url).then((response) => response.text());\n\n  return { timestampMap: parseVttTimestampMap(text) };\n}\n"],"mappings":";;;;;;;;;;;;;;AAsBA,eAAsB,0BAA0B,KAA2C;CACzF,MAAM,OAAO,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,aAAa,SAAS,KAAK,CAAC;CAEhE,OAAO,EAAE,cAAc,qBAAqB,IAAI,EAAE;AACpD"}

package/dist/default/media/types/index.js

@@ -0,0 +1,42 @@
+//#region src/media/types/index.ts
+/**
+* Floating-point tolerance for matching segments by `startTime`. Two segments are considered the same position when
+* `Math.abs(a.startTime - b.startTime) < SEGMENT_TIME_EPSILON`. Used by the source-buffer dedup and segment-loader
+* quality-aware filter to tolerate sub-millisecond drift in segment timestamps across multiple playlists / quality
+* levels.
+*/
+const SEGMENT_TIME_EPSILON = 1e-4;
+/** Key under `Ham.metadata` where {@link MediaPlaylistMetadata} is stored. */
+const MEDIA_PLAYLIST_METADATA_KEY = "mediaPlaylist";
+/** Typed read of the media-playlist metadata stashed in `ham.metadata`. */
+function getMediaPlaylistMetadata(ham) {
+	return ham.metadata?.[MEDIA_PLAYLIST_METADATA_KEY];
+}
+/**
+* Derive {@link StreamType} from a media playlist's metadata. Per the model, only `#EXT-X-PLAYLIST-TYPE:VOD` marks
+* on-demand; everything else (EVENT, or the tag absent) is live — completeness (`endList`) never factors in.
+*/
+function deriveStreamType(metadata) {
+	return metadata?.playlistType === "VOD" ? "on-demand" : "live";
+}
+function isResolvedTrack(track) {
+	return "segments" in track;
+}
+/** Check if a presentation has duration (at least one track resolved). Narrows type to include required duration. */
+function hasPresentationDuration(presentation) {
+	return presentation.duration !== void 0;
+}
+/**
+* Narrows a `MaybeResolvedPresentation` to a fully resolved `Presentation`.
+*
+* A presentation is resolved once `resolvePresentation` has parsed the manifest and populated both `id` and
+* `selectionSets`. Both must be present — a partial value with only one of them isn't usable, and letting it through
+* would have downstream behaviors crash when they access `selectionSets`.
+*/
+function isResolvedPresentation(presentation) {
+	return presentation !== void 0 && presentation.id !== void 0 && presentation.selectionSets !== void 0;
+}
+//#endregion
+export { MEDIA_PLAYLIST_METADATA_KEY, SEGMENT_TIME_EPSILON, deriveStreamType, getMediaPlaylistMetadata, hasPresentationDuration, isResolvedPresentation, isResolvedTrack };
+
+//# sourceMappingURL=index.js.map

package/dist/default/media/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../../src/media/types/index.ts"],"sourcesContent":["/**\n * Core SPF Types\n *\n * Based on CMAF-HAM (Common Media Application Format - Hypothetical Application Model) Protocol-agnostic representation\n * of streaming media content.\n *\n * @see https://github.com/streaming-video-technology-alliance/common-media-library\n */\n\n// =============================================================================\n// Base Types\n// =============================================================================\n\n/** Base identifier type for all HAM objects. */\nexport interface Ham {\n  id: string;\n  /**\n   * Format-/protocol-specific values that aren't part of the generic CMAF-HAM model — kept in an open bag so the model\n   * stays format-neutral (mirrors how CMAF-HAM itself stashes protocol extras rather than growing the model). Typed\n   * reads go through dedicated accessors (e.g. `getMediaPlaylistMetadata`).\n   */\n  metadata?: Record<string, unknown>;\n}\n\n/** Addressable resource with optional byte range. */\nexport interface AddressableObject {\n  url: string;\n  byteRange?: {\n    start: number;\n    end: number;\n  };\n}\n\n// =============================================================================\n// Platform-agnostic Media Element\n// =============================================================================\n\n/**\n * Platform-agnostic media element interface. Captures minimal shape needed for orchestration without DOM dependencies.\n * HTMLMediaElement satisfies this interface.\n */\nexport interface MediaElementLike {\n  preload: string;\n  /**\n   * DOM attribute-reflection surface, present on real elements. Where it exists, reflected IDL properties like\n   * `preload` report a browser-dependent UA default even when no attribute was authored — so consumers that need author\n   * intent must gate property reads on attribute presence. A non-DOM implementation may omit it; its properties carry\n   * no UA defaults and are authored by construction.\n   */\n  hasAttribute?(qualifiedName: string): boolean;\n}\n\n// =============================================================================\n// Time and Duration\n// =============================================================================\n\n/** Time span with start time and duration. Used for segments and other timed ranges. */\nexport interface TimeSpan {\n  startTime: number;\n  duration: number;\n}\n\n// =============================================================================\n// Enums\n// =============================================================================\n\n/** Track content type. */\nexport type TrackType = 'video' | 'audio' | 'text';\n\n// =============================================================================\n// Frame Rate\n// =============================================================================\n\n/**\n * Video frame rate expressed as numerator/denominator.\n *\n * Examples: - 30 fps: { frameRateNumerator: 30 } - 29.97 fps: { frameRateNumerator: 30000, frameRateDenominator: 1001 }\n */\nexport interface FrameRate {\n  frameRateNumerator: number;\n  frameRateDenominator?: number;\n}\n\n// =============================================================================\n// Partially Resolved Tracks (before media playlist is fetched)\n// =============================================================================\n\n/**\n * Generic type for partially resolved tracks. Removes fields that come from media playlist parsing.\n *\n * @param T - Track type to make partially resolved (must extend Track)\n */\nexport type PartiallyResolved<T extends Track = Track> = Omit<T, 'segments' | 'initialization' | keyof TimeSpan> & {\n  segments?: never;\n  duration?: never;\n  startTime?: never;\n  initialization?: never;\n};\n\n/**\n * Partially resolved video track from multivariant playlist. Has metadata but no segments or initialization yet (media\n * playlist not fetched).\n */\nexport type PartiallyResolvedVideoTrack = PartiallyResolved<VideoTrack>;\n\n/**\n * Partially resolved audio track from multivariant playlist. Has metadata but no segments or initialization yet (media\n * playlist not fetched).\n */\nexport type PartiallyResolvedAudioTrack = PartiallyResolved<AudioTrack>;\n\n// =============================================================================\n// Resolved Track Types (with segments from media playlist)\n// =============================================================================\n\n/**\n * Base track type containing common properties for all resolved tracks. A resolved track has segments, duration, and\n * initialization data. All URLs are fully qualified (parsers resolve relative URLs).\n */\n/**\n * Track startTime is always 0 — the presentation-timeline origin (and future multi-period base). The live\n * sliding-window edge is `segments[0].startTime`, derived — never stored here.\n */\nexport type Track = Ham &\n  AddressableObject &\n  TimeSpan & {\n    type: TrackType;\n    codecs?: string[]; // Optional per HLS spec\n    mimeType: string;\n    language?: string | undefined;\n    bandwidth: number;\n    initialization?: AddressableObject;\n    segments: Segment[];\n    /**\n     * Media-timeline (decode/encode) coordinate of the track's timeline origin (presentation-0) — the media-time base\n     * value of the coordinate model, peer to `startTime` (presentation). Derived from the container\n     * (`tfdt.baseMediaDecodeTime ÷ mdhd.timescale`); the relocation offset is `−startMediaTime` (targets presentation-0\n     * — `Track.startTime` plays no part), never stored.\n     *\n     * Optional: `undefined` means not yet established, or never establishable (e.g. text tracks carry no container\n     * origin); a near-zero/native origin is established as `0` (no relocation). Established once per source by the\n     * `establishStartMediaTime` reactor. See `internal/design/spf/presentation-timeline-model.md`.\n     */\n    startMediaTime?: number;\n    /**\n     * Wall-clock time (epoch seconds) at the track's timeline origin (presentation-0) — pure playlist arithmetic over\n     * any PDT-bearing segment: `segment.startDate − segment.startTime`, invariant along a linear timeline. Optional:\n     * absent when no segment carries `startDate`.\n     *\n     * The wall-clock member of the coordinate triple (peer to `startTime` and `startMediaTime`). For live it is the\n     * anchor segments are PDT-placed against on every parse; equal `startDate` across tracks marks the same\n     * presentation instant. See `internal/design/spf/live-presentation-timeline-model.md`.\n     */\n    startDate?: number;\n  };\n\n/**\n * Per-track-type origin-establishment data, accumulated across appends (the media track's `track_id` + `mdhd` timescale\n * from the init, `tfdt` baseMediaDecodeTime of that same track from the first media segment) — hence optional. The\n * transient input the `establishStartMediaTime` reactor reduces into `Track.startMediaTime`.\n *\n * `trackId` is the ISO-BMFF `track_ID` of the buffered media track (`vide`/`soun`), read from the init's `tkhd`; it\n * ties the timescale to the _same_ track's `baseMediaDecodeTime` (matched via `tfhd.track_id`) so a muxed segment\n * carrying a second track (e.g. `clcp` captions) reads the right `tfdt` rather than the first one.\n *\n * `segmentStartTime` is the 0-based presentation start of the segment `baseMediaDecodeTime` was read from — _not_ a\n * container value (it's the playlist position), but co-located because the origin is `baseMediaDecodeTime/timescale −\n * segmentStartTime`: the first _loaded_ segment isn't necessarily the 0th (a non-zero initial `currentTime`, or\n * live/DVR), so the decode time alone isn't the stream origin.\n */\nexport interface MediaContainerData {\n  trackId?: number;\n  timescale?: number;\n  baseMediaDecodeTime?: number;\n  segmentStartTime?: number;\n}\n\n/**\n * Raw media-segment bytes — a complete buffer or a byte stream. The transport-neutral payload the loader pipeline\n * carries; `AppendData` (the MSE `SourceBuffer` append input in `media/dom/mse`) is an alias of this at the DOM\n * boundary.\n */\nexport type SegmentData = ArrayBuffer | AsyncIterable<Uint8Array>;\n\n/** Resolved video track with segments. */\nexport type VideoTrack = Track &\n  Required<Pick<Track, 'initialization' | 'codecs'>> & {\n    type: 'video';\n\n    // Optional metadata from multivariant (per HLS spec)\n    width?: number;\n    height?: number;\n    frameRate?: FrameRate;\n    /**\n     * Audio groups (`EXT-X-STREAM-INF:AUDIO`) this video rendition can pair with. A list because one rendition is\n     * typically listed across multiple `EXT-X-STREAM-INF` entries — one per audio group (the HLS cross-product) — which\n     * the parser collapses into a single track carrying every group it advertised.\n     */\n    audioGroupIds?: string[];\n  };\n\n/** Resolved audio track with segments. */\nexport type AudioTrack = Track &\n  Required<Pick<Track, 'initialization' | 'codecs'>> & {\n    type: 'audio';\n    groupId: string;\n    name: string;\n    sampleRate: number;\n    channels: number;\n    default?: boolean;\n    autoselect?: boolean;\n  };\n\n/** Resolved text track with segments. */\nexport type TextTrack = Track & {\n  type: 'text';\n  groupId: string;\n  label: string;\n  kind: 'subtitles' | 'captions';\n  default?: boolean;\n  autoselect?: boolean;\n  forced?: boolean;\n};\n\n/**\n * Predicate that answers \"can this environment decode this track?\" — the capability-probing surface, read by the\n * track-switching hard-constraint pre-pass (`excludeUnplayableTracks`) to drop undecodable renditions before selection.\n * Kept DOM-free here (a plain function type over a minimal track shape) so DOM-free behaviors can consume it; the DOM\n * implementation (`canPlayTrack` in `media/dom/capabilities.ts`) wraps `MediaSource.isTypeSupported`.\n *\n * Takes the minimal codec-bearing shape both video and audio candidates carry. `mimeType` is optional so unprobeable\n * candidates (no MIME) can be passed straight through as playable rather than dropped.\n */\nexport type CanPlayTrack = (track: {\n  mimeType?: string;\n  codecs?: string[];\n  metadata?: Record<string, unknown>;\n}) => boolean;\n\n/**\n * Minimal text-track cue shape — start time, end time, and display text.\n *\n * Host-agnostic representation. `VTTCue` structurally satisfies this interface, so DOM consumers pass `VTTCue` values\n * directly. Non-DOM hosts (workers, test fakes, non-browser engines) can satisfy the same shape without pulling in DOM\n * types.\n */\nexport interface Cue {\n  startTime: number;\n  endTime: number;\n  text: string;\n}\n\n/**\n * Media element with an iterable text-track list, host-agnostic.\n *\n * Extends `MediaElementLike` with the minimum surface needed to observe which text tracks are currently mounted on the\n * media. `HTMLMediaElement` structurally satisfies this (its `textTracks` is a `TextTrackList`, which is iterable with\n * `{ id }` items).\n */\nexport interface MediaElementWithTextTracks extends MediaElementLike {\n  readonly textTracks: Iterable<{ readonly id: string }>;\n}\n\n/**\n * Partially resolved text track from multivariant playlist. Has metadata but no segments or initialization yet (media\n * playlist not fetched).\n */\nexport type PartiallyResolvedTextTrack = PartiallyResolved<TextTrack>;\n\n/** Union of all resolved track types. */\nexport type ResolvedTrack = VideoTrack | AudioTrack | TextTrack;\n\n/** Union of all partially resolved track types. */\nexport type PartiallyResolvedTrack =\n  | PartiallyResolvedVideoTrack\n  | PartiallyResolvedAudioTrack\n  | PartiallyResolvedTextTrack;\n\n// =============================================================================\n// Switching and Selection Sets\n// =============================================================================\n\n/**\n * Generic switching set type. A group of tracks that can be switched between seamlessly.\n *\n * @param T - Track type (VideoTrack, AudioTrack, or TextTrack)\n */\nexport type SwitchingSetOf<T extends Track = Track> = Ham & {\n  type: T['type'];\n  tracks: (PartiallyResolved<T> | T)[];\n};\n\n/** Video switching set - contains only video tracks (partially resolved or fully resolved). */\nexport type VideoSwitchingSet = SwitchingSetOf<VideoTrack>;\n\n/** Audio switching set - contains only audio tracks (partially resolved or fully resolved). */\nexport type AudioSwitchingSet = SwitchingSetOf<AudioTrack>;\n\n/** Text switching set - contains only text tracks (partially resolved or fully resolved). */\nexport type TextSwitchingSet = SwitchingSetOf<TextTrack>;\n\n/** Switching set - a group of tracks that can be switched between seamlessly. Discriminated by track type. */\nexport type SwitchingSet = VideoSwitchingSet | AudioSwitchingSet | TextSwitchingSet;\n\n/**\n * Generic selection set type. Groups switching sets by track type.\n *\n * @param T - Track type (VideoTrack, AudioTrack, or TextTrack)\n */\nexport type SelectionSetOf<T extends Track = Track> = Ham & {\n  type: T['type'];\n  switchingSets: SwitchingSetOf<T>[];\n};\n\n/** Video selection set - contains only video switching sets. */\nexport type VideoSelectionSet = SelectionSetOf<VideoTrack>;\n\n/** Audio selection set - contains only audio switching sets. */\nexport type AudioSelectionSet = SelectionSetOf<AudioTrack>;\n\n/** Text selection set - contains only text switching sets. */\nexport type TextSelectionSet = SelectionSetOf<TextTrack>;\n\n/** Selection set - groups switching sets by track type. Discriminated union ensures type-safe track access. */\nexport type SelectionSet = VideoSelectionSet | AudioSelectionSet | TextSelectionSet;\n\n// =============================================================================\n// Segment\n// =============================================================================\n\n/**\n * Media segment with timing information. Follows CMAF-HAM composition pattern.\n *\n * `startDate` is the absolute wall-clock time of the segment's first sample, in **epoch seconds** (unit-consistent with\n * `startTime`/`duration`), derived from `#EXT-X-PROGRAM-DATE-TIME` (explicit or interpolated forward via `EXTINF`).\n * Unlike the per-track-relative `startTime`, it is comparable across tracks, so it is the cross-track sync anchor for\n * demuxed audio/video and the exact recovery value on a full live-window turnover. Optional: absent when the source\n * carries no PDT (allowed by RFC 8216, required by Apple's HLS authoring spec — so present on conformant content).\n */\nexport type Segment = Ham & AddressableObject & TimeSpan & { startDate?: number };\n\n/**\n * Floating-point tolerance for matching segments by `startTime`. Two segments are considered the same position when\n * `Math.abs(a.startTime - b.startTime) < SEGMENT_TIME_EPSILON`. Used by the source-buffer dedup and segment-loader\n * quality-aware filter to tolerate sub-millisecond drift in segment timestamps across multiple playlists / quality\n * levels.\n */\nexport const SEGMENT_TIME_EPSILON = 0.0001;\n\n// =============================================================================\n// Media Playlist Metadata\n// =============================================================================\n\n/**\n * Playlist-level metadata surfaced from a parsed media playlist. HLS delivery specifics — not part of the generic\n * CMAF-HAM model — so they live under `Ham.metadata` (read via `getMediaPlaylistMetadata`) rather than as first-class\n * `Track` fields:\n *\n * - `targetDuration` (`#EXT-X-TARGETDURATION`) — reload-cadence basis.\n * - `mediaSequence` (`#EXT-X-MEDIA-SEQUENCE`, default 0) — sequence number of `segments[0]`; the join key for merging\n *   successive reload snapshots.\n * - `playlistType` (`#EXT-X-PLAYLIST-TYPE`) — `VOD` / `EVENT` / undefined.\n * - `endList` (`#EXT-X-ENDLIST`) — playlist is complete; stop reloading.\n */\nexport interface MediaPlaylistMetadata {\n  targetDuration: number;\n  mediaSequence: number;\n  playlistType?: 'VOD' | 'EVENT';\n  endList: boolean;\n  /**\n   * Whether this rendition carries encrypted segments — any `#EXT-X-KEY` whose `METHOD` isn't `NONE`. Detection only:\n   * enough to tell that playback needs decryption support, not enough to perform it.\n   *\n   * Deliberately _not_ a model-level `protection` shape. CMAF-HAM puts `protection` on `SwitchingSet`, but that can't\n   * express two real cases: a clear lead (`METHOD=NONE` segments followed by encrypted ones — protection varies along\n   * the timeline within one rendition) or key rotation (its single `defaultKid` can't represent a key changing over\n   * time). Modeling it properly belongs to DRM support; until then this records the one fact a playlist reliably gives\n   * us. Per-rendition because that's HLS's granularity — `EXT-X-KEY` is a media-playlist tag.\n   *\n   * Conservative for a clear lead: a rendition whose opening segments are clear still reads as encrypted, so it's\n   * judged unplayable rather than played until it breaks.\n   */\n  encrypted?: boolean;\n  /**\n   * `EXT-X-SERVER-CONTROL` `HOLD-BACK` (seconds) — the server's declared distance from the live edge for clients\n   * playing _complete_ segments. Absent when the server doesn't advertise it, in which case the spec default (3 ×\n   * target duration) applies. Deliberately HLS vocabulary living in the playlist metadata rather than on `Track`:\n   * whether a wall-clock holdback generalizes across delivery formats is unresolved.\n   *\n   * `PART-HOLD-BACK` is **not** captured — it only applies to clients playing partial segments, and using it while\n   * fetching whole segments would put the playhead ahead of the last complete segment. Add it with LL-HLS support.\n   */\n  holdBack?: number;\n  /**\n   * Whether the server is delivering this rendition as Low-Latency HLS — any of `#EXT-X-PART`, `#EXT-X-PART-INF`, or\n   * `EXT-X-SERVER-CONTROL`'s `PART-HOLD-BACK`.\n   *\n   * Detection only, and deliberately so: partial segments are ignored by the parser and the loader fetches whole\n   * segments, so an LL-HLS playlist plays as standard live at standard latency. Recording the fact is what lets a\n   * composition _say_ that rather than silently under-delivering the latency the publisher configured.\n   */\n  lowLatency?: boolean;\n}\n\n/** Key under `Ham.metadata` where {@link MediaPlaylistMetadata} is stored. */\nexport const MEDIA_PLAYLIST_METADATA_KEY = 'mediaPlaylist';\n\n/** Typed read of the media-playlist metadata stashed in `ham.metadata`. */\nexport function getMediaPlaylistMetadata(ham: Pick<Ham, 'metadata'>): MediaPlaylistMetadata | undefined {\n  return ham.metadata?.[MEDIA_PLAYLIST_METADATA_KEY] as MediaPlaylistMetadata | undefined;\n}\n\n// =============================================================================\n// Stream Type\n// =============================================================================\n\n/**\n * The source's semantic nature — live vs on-demand. A model concept (consumer-facing), distinct from completeness /\n * duration: a live stream that has _ended_ is still `'live'`.\n */\nexport type StreamType = 'live' | 'on-demand';\n\n/**\n * Derive {@link StreamType} from a media playlist's metadata. Per the model, only `#EXT-X-PLAYLIST-TYPE:VOD` marks\n * on-demand; everything else (EVENT, or the tag absent) is live — completeness (`endList`) never factors in.\n */\nexport function deriveStreamType(metadata: MediaPlaylistMetadata | undefined): StreamType {\n  return metadata?.playlistType === 'VOD' ? 'on-demand' : 'live';\n}\n\n// =============================================================================\n// Media Playlist Info\n// =============================================================================\n\n/** Intermediate representation of a parsed media playlist. Used internally before assembling into full Track structure. */\nexport interface MediaPlaylistInfo {\n  version: number;\n  targetDuration: number;\n  playlistType: 'VOD' | 'EVENT' | undefined;\n  initSegment: AddressableObject | null;\n  segments: Segment[];\n  duration: number;\n  endList: boolean;\n}\n\n// =============================================================================\n// Presentation\n// =============================================================================\n\n/**\n * Presentation - a single playable period of content. Uses TimeSpan fields (startTime always 0, duration optional until\n * track resolved).\n *\n * Extends AddressableObject so `url` contains the original manifest URL. All URLs are fully qualified (parsers resolve\n * relative URLs).\n */\nexport type Presentation = Ham &\n  AddressableObject &\n  Partial<TimeSpan> & {\n    selectionSets: SelectionSet[];\n    /**\n     * Live vs on-demand — the source's semantic nature. Populated once a media playlist is parsed (derived from\n     * `#EXT-X-PLAYLIST-TYPE` via `deriveStreamType`); orthogonal to duration / completeness.\n     */\n    streamType?: StreamType;\n  };\n\n/**\n * State-shaped presentation that may or may not be resolved yet.\n *\n * The lifecycle is a single value: a caller writes `{ url }`, and the resolver populates the rest in place. `url` is\n * always present; resolved fields (`id`, `selectionSets`, duration) appear once parsing succeeds.\n *\n * Use `isResolvedPresentation` to narrow to `Presentation`.\n */\nexport type MaybeResolvedPresentation = AddressableObject & Partial<Omit<Presentation, keyof AddressableObject>>;\n\n// =============================================================================\n// Type Guards\n// =============================================================================\n\n/** Check if a track is resolved (has segments). Works for all track types with overloaded signatures for type narrowing. */\nexport function isResolvedTrack(track: PartiallyResolvedVideoTrack | VideoTrack): track is VideoTrack;\nexport function isResolvedTrack(track: PartiallyResolvedAudioTrack | AudioTrack): track is AudioTrack;\nexport function isResolvedTrack(track: PartiallyResolvedTextTrack | TextTrack): track is TextTrack;\nexport function isResolvedTrack(track: PartiallyResolvedTrack | ResolvedTrack): track is ResolvedTrack;\nexport function isResolvedTrack(track: PartiallyResolvedTrack | ResolvedTrack): track is ResolvedTrack {\n  return 'segments' in track;\n}\n\n/** Check if a presentation has duration (at least one track resolved). Narrows type to include required duration. */\nexport function hasPresentationDuration(\n  presentation: MaybeResolvedPresentation\n): presentation is MaybeResolvedPresentation & { duration: number } {\n  return presentation.duration !== undefined;\n}\n\n/**\n * Narrows a `MaybeResolvedPresentation` to a fully resolved `Presentation`.\n *\n * A presentation is resolved once `resolvePresentation` has parsed the manifest and populated both `id` and\n * `selectionSets`. Both must be present — a partial value with only one of them isn't usable, and letting it through\n * would have downstream behaviors crash when they access `selectionSets`.\n */\nexport function isResolvedPresentation(\n  presentation: MaybeResolvedPresentation | undefined\n): presentation is Presentation {\n  return presentation !== undefined && presentation.id !== undefined && presentation.selectionSets !== undefined;\n}\n"],"mappings":";;;;;;;AA2VA,MAAa,uBAAuB;;AA0DpC,MAAa,8BAA8B;;AAG3C,SAAgB,yBAAyB,KAA+D;CACtG,OAAO,IAAI,WAAW;AACxB;;;;;AAgBA,SAAgB,iBAAiB,UAAyD;CACxF,OAAO,UAAU,iBAAiB,QAAQ,cAAc;AAC1D;AA0DA,SAAgB,gBAAgB,OAAuE;CACrG,OAAO,cAAc;AACvB;;AAGA,SAAgB,wBACd,cACkE;CAClE,OAAO,aAAa,aAAa,KAAA;AACnC;;;;;;;;AASA,SAAgB,uBACd,cAC8B;CAC9B,OAAO,iBAAiB,KAAA,KAAa,aAAa,OAAO,KAAA,KAAa,aAAa,kBAAkB,KAAA;AACvG"}

package/dist/default/media/utils/cdn.js

@@ -0,0 +1,50 @@
+//#region src/media/utils/cdn.ts
+/**
+* Default {@link GetCdnId}: the URL's origin (scheme + host + port); falls back to the raw string when the URL can't be
+* parsed, so the return value is always a stable grouping key.
+*/
+function getCdnId(url) {
+	try {
+		return new URL(url).origin;
+	} catch {
+		return url;
+	}
+}
+const CDN_TYPE_PRIORITY = {
+	video: 0,
+	audio: 1,
+	text: 2
+};
+/**
+* The distinct CDNs a presentation's tracks are served from, ordered video CDNs first, then audio, then text (manifest
+* order within a type). The head is the primary CDN — the one a sticky pick defaults to — and is always video-derived
+* when the source has video. Returns `[]` for an unresolved presentation with no tracks.
+*
+* Redundant-stream sources list the same content on multiple hosts (e.g. Mux's `?redundant_streams=true`), so each host
+* contributes its own candidate tracks; this collapses them to the set of CDNs across every track type. The CDN-id
+* derivation defaults to {@link getCdnId}; pass a consumer-configured `getId` to key on something other than origin.
+*/
+function getOrderedCdnIds(presentation, getId = getCdnId) {
+	const seen = /* @__PURE__ */ new Set();
+	const ids = [];
+	const selectionSets = [...presentation.selectionSets ?? []].sort((a, b) => CDN_TYPE_PRIORITY[a.type] - CDN_TYPE_PRIORITY[b.type]);
+	for (const selectionSet of selectionSets) for (const switchingSet of selectionSet.switchingSets) for (const track of switchingSet.tracks) {
+		const id = getId(track.url);
+		if (seen.has(id)) continue;
+		seen.add(id);
+		ids.push(id);
+	}
+	return ids;
+}
+/**
+* Add a CDN id to a failed-CDN list, preserving order and ignoring duplicates. Idempotent: re-adding an already-present
+* id returns the same array reference (so a no-op trip doesn't churn the `failedCdns` signal). The failover trip in
+* `resolve-track` and the segment loaders feed this into `failedCdns` via `update`.
+*/
+function addFailedCdn(failed, cdn) {
+	return failed?.includes(cdn) ? failed : [...failed ?? [], cdn];
+}
+//#endregion
+export { addFailedCdn, getCdnId, getOrderedCdnIds };
+
+//# sourceMappingURL=cdn.js.map

package/dist/default/media/utils/cdn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdn.js","names":[],"sources":["../../../../src/media/utils/cdn.ts"],"sourcesContent":["import type { MaybeResolvedPresentation, TrackType } from '../types';\n\n/**\n * Derive a stable grouping key for the CDN a URL is served from. Synchronous and pure (deliberately not a `resolve*` —\n * no fetch). Consumers override the default via the engine's `getCdnId` config (e.g. to key on Mux's `cdn=` query param\n * instead of the host); every CDN-identity site reads that same function so keys stay comparable across `cdnPriority`,\n * `failedCdns`, and the track-switching constraint + scope.\n */\nexport type GetCdnId = (url: string) => string;\n\n/**\n * Default {@link GetCdnId}: the URL's origin (scheme + host + port); falls back to the raw string when the URL can't be\n * parsed, so the return value is always a stable grouping key.\n */\nexport function getCdnId(url: string): string {\n  try {\n    return new URL(url).origin;\n  } catch {\n    return url;\n  }\n}\n\n// Track-type priority for CDN ordering: video first, then audio, then text.\n// Selection sets are visited in this order so the head of the returned list is\n// always video-derived. `preferActiveCdn` anchors every track type to the\n// first CDN with surviving tracks (the head), so this makes \"the primary CDN\n// is the video CDN\" a guarantee of `getOrderedCdnIds` rather than a side effect\n// of the order tracks happen to be parsed in.\nconst CDN_TYPE_PRIORITY: Record<TrackType, number> = { video: 0, audio: 1, text: 2 };\n\n/**\n * The distinct CDNs a presentation's tracks are served from, ordered video CDNs first, then audio, then text (manifest\n * order within a type). The head is the primary CDN — the one a sticky pick defaults to — and is always video-derived\n * when the source has video. Returns `[]` for an unresolved presentation with no tracks.\n *\n * Redundant-stream sources list the same content on multiple hosts (e.g. Mux's `?redundant_streams=true`), so each host\n * contributes its own candidate tracks; this collapses them to the set of CDNs across every track type. The CDN-id\n * derivation defaults to {@link getCdnId}; pass a consumer-configured `getId` to key on something other than origin.\n */\nexport function getOrderedCdnIds(presentation: MaybeResolvedPresentation, getId: GetCdnId = getCdnId): string[] {\n  const seen = new Set<string>();\n  const ids: string[] = [];\n  // Stable sort keeps manifest order among same-type selection sets.\n  const selectionSets = [...(presentation.selectionSets ?? [])].sort(\n    (a, b) => CDN_TYPE_PRIORITY[a.type] - CDN_TYPE_PRIORITY[b.type]\n  );\n\n  for (const selectionSet of selectionSets) {\n    for (const switchingSet of selectionSet.switchingSets) {\n      for (const track of switchingSet.tracks) {\n        const id = getId(track.url);\n        if (seen.has(id)) continue;\n\n        seen.add(id);\n        ids.push(id);\n      }\n    }\n  }\n\n  return ids;\n}\n\n/**\n * Add a CDN id to a failed-CDN list, preserving order and ignoring duplicates. Idempotent: re-adding an already-present\n * id returns the same array reference (so a no-op trip doesn't churn the `failedCdns` signal). The failover trip in\n * `resolve-track` and the segment loaders feed this into `failedCdns` via `update`.\n */\nexport function addFailedCdn(failed: string[] | undefined, cdn: string): string[] {\n  return failed?.includes(cdn) ? failed : [...(failed ?? []), cdn];\n}\n"],"mappings":";;;;;AAcA,SAAgB,SAAS,KAAqB;CAC5C,IAAI;EACF,OAAO,IAAI,IAAI,GAAG,CAAC,CAAC;CACtB,QAAQ;EACN,OAAO;CACT;AACF;AAQA,MAAM,oBAA+C;CAAE,OAAO;CAAG,OAAO;CAAG,MAAM;AAAE;;;;;;;;;;AAWnF,SAAgB,iBAAiB,cAAyC,QAAkB,UAAoB;CAC9G,MAAM,uBAAO,IAAI,IAAY;CAC7B,MAAM,MAAgB,CAAC;CAEvB,MAAM,gBAAgB,CAAC,GAAI,aAAa,iBAAiB,CAAC,CAAE,CAAC,CAAC,MAC3D,GAAG,MAAM,kBAAkB,EAAE,QAAQ,kBAAkB,EAAE,KAC5D;CAEA,KAAK,MAAM,gBAAgB,eACzB,KAAK,MAAM,gBAAgB,aAAa,eACtC,KAAK,MAAM,SAAS,aAAa,QAAQ;EACvC,MAAM,KAAK,MAAM,MAAM,GAAG;EAC1B,IAAI,KAAK,IAAI,EAAE,GAAG;EAElB,KAAK,IAAI,EAAE;EACX,IAAI,KAAK,EAAE;CACb;CAIJ,OAAO;AACT;;;;;;AAOA,SAAgB,aAAa,QAA8B,KAAuB;CAChF,OAAO,QAAQ,SAAS,GAAG,IAAI,SAAS,CAAC,GAAI,UAAU,CAAC,GAAI,GAAG;AACjE"}

package/dist/default/media/utils/preload.js

@@ -0,0 +1,21 @@
+//#region src/media/utils/preload.ts
+function isStandardPreload(value) {
+	return value === "auto" || value === "metadata" || value === "none";
+}
+/**
+* Default `preload` value used as the fallback across behaviors (`syncPreload`, `resolvePresentation`,
+* `isBlockingPreload`). SPF's own default, deliberately independent of the `<video>`/`<audio>` element's implicit
+* default — that one is UA policy and browser-dependent (`'metadata'` Chromium, `'auto'` WebKit), never a source.
+*/
+const DEFAULT_PRELOAD = "metadata";
+/**
+* True when the preload value blocks initial resolution / loading. Falsy values (undefined, empty) fall back to
+* `defaultPreload` (default `DEFAULT_PRELOAD`); the resolved value blocks iff it is `'none'`.
+*/
+function isBlockingPreload(preload, defaultPreload = DEFAULT_PRELOAD) {
+	return (preload || defaultPreload) === "none";
+}
+//#endregion
+export { DEFAULT_PRELOAD, isBlockingPreload, isStandardPreload };
+
+//# sourceMappingURL=preload.js.map

package/dist/default/media/utils/preload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preload.js","names":[],"sources":["../../../../src/media/utils/preload.ts"],"sourcesContent":["/**\n * The W3C-standard set of `<video>`/`<audio>` `preload` attribute values. SPF allows extended values (e.g. `'canplay'`)\n * on `state.preload`, which are _not_ reflected to the DOM — predicate below is the discriminator.\n */\nexport type StandardPreload = 'auto' | 'metadata' | 'none';\n\nexport function isStandardPreload(value: unknown): value is StandardPreload {\n  return value === 'auto' || value === 'metadata' || value === 'none';\n}\n\n/**\n * Default `preload` value used as the fallback across behaviors (`syncPreload`, `resolvePresentation`,\n * `isBlockingPreload`). SPF's own default, deliberately independent of the `<video>`/`<audio>` element's implicit\n * default — that one is UA policy and browser-dependent (`'metadata'` Chromium, `'auto'` WebKit), never a source.\n */\nexport const DEFAULT_PRELOAD = 'metadata';\n\n/**\n * True when the preload value blocks initial resolution / loading. Falsy values (undefined, empty) fall back to\n * `defaultPreload` (default `DEFAULT_PRELOAD`); the resolved value blocks iff it is `'none'`.\n */\nexport function isBlockingPreload(\n  preload: string | undefined,\n  defaultPreload: StandardPreload = DEFAULT_PRELOAD\n): boolean {\n  return (preload || defaultPreload) === 'none';\n}\n"],"mappings":";AAMA,SAAgB,kBAAkB,OAA0C;CAC1E,OAAO,UAAU,UAAU,UAAU,cAAc,UAAU;AAC/D;;;;;;AAOA,MAAa,kBAAkB;;;;;AAM/B,SAAgB,kBACd,SACA,iBAAkC,iBACzB;CACT,QAAQ,WAAW,oBAAoB;AACzC"}

package/dist/default/media/utils/track-selection.js

@@ -0,0 +1,43 @@
+import { isResolvedTrack } from "../types/index.js";
+//#region src/media/utils/track-selection.ts
+/** Map track type to selected track ID property key in state. */
+const SelectedTrackIdKeyByType = {
+	video: "selectedVideoTrackId",
+	audio: "selectedAudioTrackId",
+	text: "selectedTextTrackId"
+};
+/**
+* Get selected track from state by type. Returns properly typed track (partially or fully resolved) or undefined. Type
+* parameter T is inferred from the type argument.
+*
+* @example
+*   const videoTrack = getSelectedTrack(state, 'video');
+*   if (videoTrack && isResolvedTrack(videoTrack)) {
+*     // videoTrack is VideoTrack
+*   }
+*/
+function getSelectedTrack(state, type) {
+	const { presentation } = state;
+	if (!presentation?.selectionSets) return void 0;
+	const trackId = state[SelectedTrackIdKeyByType[type]];
+	return presentation.selectionSets.find(({ type: selectionSetType }) => selectionSetType === type)?.switchingSets[0]?.tracks.find(({ id }) => id === trackId);
+}
+/**
+* Returns the duration of the first resolved selected track, preferring video over audio. A track is "resolved" once
+* its media playlist has been parsed (per {@link isResolvedTrack}). Returns `undefined` if neither selected track is
+* resolved.
+*/
+function getResolvedSelectedTrackDuration(state) {
+	if (state.selectedVideoTrackId) {
+		const video = getSelectedTrack(state, "video");
+		if (video && isResolvedTrack(video)) return video.duration;
+	}
+	if (state.selectedAudioTrackId) {
+		const audio = getSelectedTrack(state, "audio");
+		if (audio && isResolvedTrack(audio)) return audio.duration;
+	}
+}
+//#endregion
+export { SelectedTrackIdKeyByType, getResolvedSelectedTrackDuration, getSelectedTrack };
+
+//# sourceMappingURL=track-selection.js.map

package/dist/default/media/utils/track-selection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"track-selection.js","names":[],"sources":["../../../../src/media/utils/track-selection.ts"],"sourcesContent":["import type {\n  AudioTrack,\n  MaybeResolvedPresentation,\n  PartiallyResolvedAudioTrack,\n  PartiallyResolvedTextTrack,\n  PartiallyResolvedVideoTrack,\n  TextTrack,\n  TrackType,\n  VideoTrack,\n} from '../types';\nimport { isResolvedTrack } from '../types';\n\n/** State shape for track selection. Minimal shape containing presentation and selected track IDs. */\nexport interface TrackSelectionState {\n  presentation?: MaybeResolvedPresentation;\n  selectedVideoTrackId?: string | undefined;\n  selectedAudioTrackId?: string | undefined;\n  selectedTextTrackId?: string | undefined;\n}\n\n/** Map track type to selected track ID property key in state. */\nexport const SelectedTrackIdKeyByType = {\n  video: 'selectedVideoTrackId',\n  audio: 'selectedAudioTrackId',\n  text: 'selectedTextTrackId',\n} as const;\n\n/**\n * Get selected track from state by type. Returns properly typed track (partially or fully resolved) or undefined. Type\n * parameter T is inferred from the type argument.\n *\n * @example\n *   const videoTrack = getSelectedTrack(state, 'video');\n *   if (videoTrack && isResolvedTrack(videoTrack)) {\n *     // videoTrack is VideoTrack\n *   }\n */\nexport function getSelectedTrack<T extends TrackType>(\n  state: TrackSelectionState,\n  type: T\n): T extends 'video'\n  ? PartiallyResolvedVideoTrack | VideoTrack | undefined\n  : T extends 'audio'\n    ? PartiallyResolvedAudioTrack | AudioTrack | undefined\n    : T extends 'text'\n      ? PartiallyResolvedTextTrack | TextTrack | undefined\n      : never {\n  const { presentation } = state;\n  if (!presentation?.selectionSets) return undefined as any;\n\n  // Get track ID based on type\n  const trackIdKey = SelectedTrackIdKeyByType[type];\n  const trackId = state[trackIdKey];\n\n  return presentation.selectionSets\n    .find(({ type: selectionSetType }) => selectionSetType === type)\n    ?.switchingSets[0]?.tracks.find(({ id }) => id === trackId) as any;\n}\n\n/**\n * Returns the duration of the first resolved selected track, preferring video over audio. A track is \"resolved\" once\n * its media playlist has been parsed (per {@link isResolvedTrack}). Returns `undefined` if neither selected track is\n * resolved.\n */\nexport function getResolvedSelectedTrackDuration(state: TrackSelectionState): number | undefined {\n  if (state.selectedVideoTrackId) {\n    const video = getSelectedTrack(state, 'video');\n    if (video && isResolvedTrack(video)) return video.duration;\n  }\n\n  if (state.selectedAudioTrackId) {\n    const audio = getSelectedTrack(state, 'audio');\n    if (audio && isResolvedTrack(audio)) return audio.duration;\n  }\n\n  return undefined;\n}\n"],"mappings":";;;AAqBA,MAAa,2BAA2B;CACtC,OAAO;CACP,OAAO;CACP,MAAM;AACR;;;;;;;;;;;AAYA,SAAgB,iBACd,OACA,MAOY;CACZ,MAAM,EAAE,iBAAiB;CACzB,IAAI,CAAC,cAAc,eAAe,OAAO,KAAA;CAIzC,MAAM,UAAU,MADG,yBAAyB;CAG5C,OAAO,aAAa,cACjB,MAAM,EAAE,MAAM,uBAAuB,qBAAqB,IAAI,CAAC,EAC9D,cAAc,EAAE,EAAE,OAAO,MAAM,EAAE,SAAS,OAAO,OAAO;AAC9D;;;;;;AAOA,SAAgB,iCAAiC,OAAgD;CAC/F,IAAI,MAAM,sBAAsB;EAC9B,MAAM,QAAQ,iBAAiB,OAAO,OAAO;EAC7C,IAAI,SAAS,gBAAgB,KAAK,GAAG,OAAO,MAAM;CACpD;CAEA,IAAI,MAAM,sBAAsB;EAC9B,MAAM,QAAQ,iBAAiB,OAAO,OAAO;EAC7C,IAAI,SAAS,gBAAgB,KAAK,GAAG,OAAO,MAAM;CACpD;AAGF"}