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

package/dist/dev/playback/engines/hls/engine.d.ts

@@ -0,0 +1,289 @@
+import { AudioTrack, CanPlayTrack, MaybeResolvedPresentation, MediaContainerData, ResolvedTrack, TextTrack, VideoTrack } from "../../../media/types/index.js";
+import { Composition, ContextSignals, StateSignals } from "../../../core/composition/create-composition.js";
+import { ShareSignalsConfig } from "../../../core/composition/share-signals.js";
+import { Reschedule } from "../../../core/tasks/task.js";
+import { BackBufferConfig } from "../../../media/buffer/back-buffer.js";
+import { ForwardBufferConfig } from "../../../media/buffer/forward-buffer.js";
+import { SourceBufferActor } from "../../actors/dom/source-buffer.js";
+import { SegmentLoaderActor } from "../../actors/dom/segment-loader.js";
+import { TextTrackSegmentResolver } from "../../primitives/text-segment-load-pipeline.js";
+import { TextTracksActor } from "../../actors/text-tracks.js";
+import { TextTrackSegmentLoaderActor } from "../../actors/text-track-segment-loader.js";
+import { SvtaError } from "../../../media/errors.js";
+import { GetCdnId } from "../../../media/utils/cdn.js";
+import { PresentationDurationResolver } from "../../behaviors/calculate-presentation-duration.js";
+import { DeriveStartMediaTime } from "../../primitives/derive-start-media-time.js";
+import "../../behaviors/establish-start-media-time.js";
+import { ParsePresentation } from "../../behaviors/resolve-presentation.js";
+import { FailoverMonitorConfig } from "../../behaviors/setup-failover-monitor.js";
+import { ReportUnsupportedTrackConditions } from "../../primitives/report-track-conditions.js";
+import { QualityConfig } from "../../../media/abr/quality-selection.js";
+import { addSubtitlesTracksToMedia, getShowingSubtitlesTrackFromMedia, removeAllSubtitlesTracksFromMedia } from "../../../media/dom/text/text-track-slots.js";
+import { BandwidthConfig, BandwidthState } from "../../../network/bandwidth-estimator.js";
+import "../../actors/dom/text-tracks.js";
+import { PlayerResolution } from "../../behaviors/dom/track-player-resolution.js";
+//#region src/playback/engines/hls/engine.d.ts
+/**
+ * State shape for the HLS playback engine.
+ *
+ * This is the union of all state required by the behaviors composed into the HLS engine. Each behavior declares its own
+ * state interface; this type satisfies all of them.
+ */
+interface HlsVideoEngineState {
+  /**
+   * The presentation being played. A caller writes `{ url }`; `resolvePresentation` parses the manifest and populates
+   * the rest.
+   */
+  presentation?: MaybeResolvedPresentation;
+  preload?: 'auto' | 'metadata' | 'none';
+  selectedVideoTrackId?: string;
+  selectedAudioTrackId?: string;
+  selectedTextTrackId?: string;
+  bandwidthState?: BandwidthState;
+  mediaContainerData?: Record<string, MediaContainerData>;
+  userVideoTrackSelection?: Partial<VideoTrack>;
+  /**
+   * Consumer-driven constraint narrowing the audio candidate set. Sibling of `userVideoTrackSelection`. Partial-track
+   * shape — `{ language: 'es' }`, `{ id: 'audio-en' }`, etc. `selectAudioTrack` reads this and re-picks when it
+   * changes. Multi-language-audio Tier 2 programmatic-write path.
+   */
+  userAudioTrackSelection?: Partial<AudioTrack>;
+  /**
+   * Consumer-driven _intent_ for text selection, resolved into `selectedTextTrackId` by `switchTextTrack`. A
+   * language-based partial (`{ language: 'es' }`) selects captions, `'off'` disables them, and absence means auto (the
+   * engine's `preferredSubtitleLanguage` / DEFAULT-track policy). Also the write path for the DOM caption UI (via
+   * `syncTextTracks`); unlike the resolved id it persists across source changes (sticky preference).
+   */
+  userTextTrackSelection?: Partial<TextTrack> | 'off';
+  /**
+   * The CDNs the source is served from (track-URL origins), in manifest priority order — most-preferred first (mirrors
+   * HLS content steering's `PATHWAY-PRIORITY`). Owned by `deriveCdnPriority`, read by `track-switching`'s
+   * `preferActiveCdn` scope, which narrows to the highest-priority CDN with surviving tracks so video / audio / text
+   * stay on one host. Only meaningful for redundant-stream sources; a single-CDN source has one entry.
+   */
+  cdnPriority?: string[];
+  /**
+   * CDN ids (origins) currently in failover cooldown — written by the CDN monitor when a host fails too often, read by
+   * `track-switching`'s `excludeFailedCdns` hard constraint, which prunes their tracks so the active-CDN scope falls to
+   * the next CDN in `cdnPriority`. Empty / absent means all CDNs are eligible.
+   */
+  failedCdns?: string[];
+  /**
+   * Conditions reported during playback, in the order encountered — appended by whichever behavior detects one
+   * (`emitError`), owned and cleared per source by `collectErrors`. Carries no severity: which of these is fatal is
+   * decided above the engine, at the adapter. See `internal/design/spf/features/errors.md`.
+   */
+  errors?: SvtaError[];
+  currentTime?: number;
+  /**
+   * The player element's rendered pixel dimensions, or `undefined` where there is nothing to measure. Written by
+   * `trackPlayerResolution`, read by the `playerResolutionCap` selection rule — which treats `undefined` as "don't
+   * cap".
+   */
+  playerResolution?: PlayerResolution;
+  loadActivated?: boolean;
+  /**
+   * One-shot command: start the current source at this position (presentation-timeline seconds). Written by consumers
+   * or by `setupAirPlay`'s session-end snapshot; consumed (cleared) by `applyStartPosition` once the element seeks. See
+   * `behaviors/dom/apply-start-position.ts`.
+   */
+  startPosition?: number;
+  /**
+   * Intent-level loading policy: initiate no new loading work while `true`. Written by `setupAirPlay` (the only
+   * behavior declaring the key) while a remote-playback session owns presentation; observed by the `loadXSegments`
+   * dispatchers (park in `'dormant'`) and by `setupMediaSource` (a pending rebuild waits). See
+   * `SegmentLoadingState['loadingSuspended']`.
+   */
+  loadingSuspended?: boolean;
+  /**
+   * Author intent for the AirPlay/remote-playback picker, written by the media adapter's `disableRemotePlayback` IDL
+   * property. `true` is an explicit opt-out: `setupAirPlay` reads it at attach and sets nothing up, leaving the
+   * element's remote playback disabled. Distinct from the underlying `<video>.disableRemotePlayback`, which stays
+   * programmatically managed (ManagedMediaSource / AirPlay).
+   */
+  disableRemotePlayback?: boolean;
+}
+/**
+ * Context shape for the HLS playback engine.
+ *
+ * Platform objects and actor references managed by HLS behaviors.
+ */
+interface HlsVideoEngineContext {
+  mediaElement?: HTMLMediaElement | undefined;
+  mediaSource?: MediaSource;
+  videoBufferActor?: SourceBufferActor;
+  audioBufferActor?: SourceBufferActor;
+  videoSegmentLoaderActor?: SegmentLoaderActor;
+  audioSegmentLoaderActor?: SegmentLoaderActor;
+  textTracksActor?: TextTracksActor;
+  textTrackSegmentLoaderActor?: TextTrackSegmentLoaderActor;
+}
+/**
+ * The composition signal refs handed to `onSignalsReady` callers — the canonical way to drive the engine externally
+ * (writes) or observe its state (reads) without touching `composition.state` / `composition.context` directly.
+ */
+type HlsVideoEngineSignals = {
+  state: StateSignals<HlsVideoEngineState>;
+  context: ContextSignals<HlsVideoEngineContext>;
+};
+/**
+ * Configuration for the HLS playback engine.
+ *
+ * Each option is consumed by the appropriate behavior — the engine itself has no config beyond what its behaviors read.
+ */
+interface HlsVideoEngineConfig extends ShareSignalsConfig<HlsVideoEngineState, HlsVideoEngineContext> {
+  /**
+   * Bandwidth estimate in bps to use before enough samples have been collected. Default: `DEFAULT_INITIAL_BANDWIDTH` (5
+   * Mbps).
+   */
+  initialBandwidth?: number;
+  /**
+   * Codec capability probe injected into `track-switching`'s `excludeUnplayableTracks` constraint — drops renditions
+   * the environment can't decode before selection. Defaults to the `MediaSource.isTypeSupported` -backed
+   * `canPlayTrack`; supply your own to override (e.g. force-exclude a codec).
+   */
+  canPlayTrack?: CanPlayTrack;
+  /**
+   * Codec families (RFC 6381 4CCs, e.g. `'avc1'` / `'hvc1'` / `'mp4a'`) the initial video/audio picks prefer on a
+   * mixed-codec source, read by the `preferCodecFamilies` selection scope. SPF implements no
+   * `SourceBuffer.changeType()`, so the initial pick's codec family is sticky for the source's lifetime
+   * (`stickToSelectedCodecs`); this decides which family that is. Soft — a source with no preferred-family rendition is
+   * unaffected. Defaults to `DEFAULT_PREFERRED_CODECS` (AVC + AAC, the broadest-decode pair); pass `[]` to disable and
+   * let ABR pick the initial family (it then still can't leave it mid-stream).
+   */
+  preferredCodecs?: string[];
+  /**
+   * Conditions reported about each rendition as it resolves — the _causes_ behind a later verdict, and the copy a
+   * verdict reuses when they agree. Defaults to {@link reportUnsupportedTrackConditions}, which reports non-fMP4
+   * containers and encryption; supply your own to report a different set (a provider that never ships MPEG-TS can drop
+   * that check) or `() => []` to report nothing.
+   */
+  reportUnsupportedTrackConditions?: ReportUnsupportedTrackConditions;
+  preferredAudioLanguage?: string;
+  preferredSubtitleLanguage?: string;
+  includeForcedTracks?: boolean;
+  enableDefaultTrack?: boolean;
+  /**
+   * Resolver that turns a text-track segment fetch into VTT cues. Defaults to the DOM-bound `resolveVttSegment`
+   * resolver, which uses an offscreen `<track>` element to parse WebVTT.
+   */
+  resolveTextTrackSegment?: TextTrackSegmentResolver<VTTCue>;
+  /**
+   * Resolver for `presentation.duration`. Defaults to picking the first resolved selected track's duration (video
+   * preferred, audio fallback) — appropriate for VoD and audio-only. Live engines should supply a resolver that returns
+   * `Number.POSITIVE_INFINITY` once the presentation is established as live; downstream `updateMediaSourceDuration`
+   * propagates that value to `mediaSource.duration` per the MSE spec.
+   */
+  resolveDuration?: PresentationDurationResolver;
+  /**
+   * Manifest parser handed to `resolvePresentation`. Defaults to the HLS multivariant-playlist parser; supply your own
+   * for alternate format support without forking the engine.
+   */
+  parsePresentation?: ParsePresentation;
+  /**
+   * Allocate SPF-owned text-track slots on the media element. Defaults to the standard `<track>`-element implementation
+   * in `media/dom/text/text-track-slots`.
+   */
+  addSubtitlesTracksToMedia?: typeof addSubtitlesTracksToMedia;
+  /**
+   * Return the SPF-owned subtitle/caption `TextTrack` currently in showing mode. Defaults to the standard
+   * selector-based implementation in `media/dom/text/text-track-slots`.
+   */
+  getShowingSubtitlesTrackFromMedia?: typeof getShowingSubtitlesTrackFromMedia;
+  /**
+   * Evict all SPF-owned text-track slots from the media element. Defaults to the standard selector-based implementation
+   * in `media/dom/text/text-track-slots`.
+   */
+  removeAllSubtitlesTracksFromMedia?: typeof removeAllSubtitlesTracksFromMedia;
+  /**
+   * Forward-buffer tuning. `bufferDuration` controls how far ahead of the playhead segments are loaded (and where
+   * forward-flush kicks in). Defaults: see `DEFAULT_FORWARD_BUFFER_CONFIG` (30 seconds). Threaded to segment-loader
+   * actors (v/a + text) at construction time and to `loadXSegments` dispatchers for the load-message range.
+   */
+  forwardBuffer?: Partial<ForwardBufferConfig>;
+  /**
+   * Back-buffer tuning. `keepSegments` controls how many segments stay behind the playhead before eviction. Defaults:
+   * see `DEFAULT_BACK_BUFFER_CONFIG` (2 segments). Threaded to the v/a segment-loader actor only (text tracks don't use
+   * back-buffer eviction).
+   */
+  backBuffer?: Partial<BackBufferConfig>;
+  /**
+   * Bandwidth-estimator tuning. Overrides any field of `BandwidthConfig` (`fastHalfLife`, `slowHalfLife`,
+   * `minTotalBytes`, `minBytes`, `minDuration`). `bandwidth.minTotalBytes` supersedes the flat `minTotalBytes` field
+   * above. Defaults: see `DEFAULT_BANDWIDTH_CONFIG`.
+   */
+  bandwidth?: Partial<BandwidthConfig>;
+  /**
+   * Quality-selection tuning. `safetyMargin` is the bandwidth-headroom multiplier used by `selectQuality`;
+   * `upgradeMargin` is the hysteresis ratio gating ABR upgrades. Defaults: `DEFAULT_QUALITY_CONFIG` (0.85 / 1.15).
+   */
+  quality?: Partial<QualityConfig>;
+  /**
+   * Whether video renditions are capped to the player element's rendered size. Read by `trackPlayerResolution`; `false`
+   * measures nothing, which leaves the `playerResolutionCap` rule inert. Defaults to `true`.
+   */
+  capRenditionToPlayerSize?: boolean;
+  /** Whether `state.playerResolution` is reported in device pixels. Read by `trackPlayerResolution`; defaults to `true`. */
+  useDevicePixelRatio?: boolean;
+  /**
+   * Multi-CDN failover monitor tuning. `cooldownMs` is how long a CDN stays excluded after a failed fetch trips it.
+   * Defaults: `DEFAULT_FAILOVER_MONITOR_CONFIG` (300s). Only meaningful for redundant-stream sources.
+   */
+  failover?: Partial<FailoverMonitorConfig>;
+  /**
+   * How to derive a CDN grouping key from a track URL — used to build `cdnPriority`, to record the failover trip in
+   * `failedCdns`, and by the track-switching CDN scope + failover constraint. One function, read by all of them, so the
+   * keys stay comparable. Defaults to the URL origin; override to key on something else (e.g. Mux's `cdn=` query
+   * param).
+   */
+  getCdnId?: GetCdnId;
+  /**
+   * Non-zero-PTS relocation (spike): the reduce seam consumed by the `establishStartMediaTime` reactor. Defaults to
+   * per-track own origin (Tier 1); a Tier-2 variant returns the shared `min` across selected A/V. Relocation is
+   * composed into the standard engine below — see the marked block — so this only needs setting to swap the tier
+   * policy. See `internal/design/spf/presentation-timeline-model.md`.
+   */
+  deriveStartMediaTime?: DeriveStartMediaTime;
+  /**
+   * Proximity window (seconds) for the `recoverEndStall` behavior — how close the playhead must be to the reachable
+   * buffered end for a `waiting` to be treated as the end-of-stream freeze and nudged to `ended`. Defaults to `0.2`.
+   * See `behaviors/dom/recover-end-stall`.
+   */
+  endStallNudgeWindow?: number;
+  /**
+   * Live media-playlist re-run policy for the resolve* loaders' `RecurringRunner`: returns a promise that resolves when
+   * the playlist should reload, or `null` to stop. Defaults to `mediaPlaylistReloadDelay` (target-duration cadence,
+   * half on an unchanged window, stop on `#EXT-X-ENDLIST`) composed with a cancellable `sleep`. Inert for VoD (a
+   * complete playlist stops it after the first resolve). Override to tune live reload timing.
+   */
+  reschedule?: Reschedule<ResolvedTrack>;
+}
+/**
+ * Create an HLS playback engine.
+ *
+ * Composes SPF behaviors into a reactive pipeline for HLS playback over MSE: manifest resolution, track selection, ABR,
+ * segment loading, and end-of-stream coordination.
+ *
+ * @example
+ *   ```ts
+ *   let signals: HlsVideoEngineSignals;
+ *   const engine = createHlsVideoEngine({
+ *     initialBandwidth: 2_000_000,
+ *     preferredAudioLanguage: 'en',
+ *     onSignalsReady: (refs) => {
+ *       signals = refs;
+ *     },
+ *   });
+ *
+ *   signals.context.mediaElement.set(videoEl);
+ *   signals.state.presentation.set({ url: 'https://example.com/stream.m3u8' });
+ *
+ *   videoEl.play();
+ *
+ *   await engine.destroy();
+ *   ```;
+ */
+declare function createHlsVideoEngine(config?: HlsVideoEngineConfig): Composition<HlsVideoEngineState, HlsVideoEngineContext>;
+//#endregion
+export { HlsVideoEngineConfig, HlsVideoEngineContext, HlsVideoEngineSignals, HlsVideoEngineState, createHlsVideoEngine };
+//# sourceMappingURL=engine.d.ts.map

package/dist/dev/playback/engines/hls/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","names":[],"sources":["../../../../../src/playback/engines/hls/engine.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA4FiB;;;;;EAKf,eAAe;EACf;EACA;EACA;EACA;EACA,iBAAiB;EAGjB,qBAAqB,eAAe;EACpC,0BAA0B,QAAQ;;;;;;EAMlC,0BAA0B,QAAQ;;;;;;;EAOlC,yBAAyB,QAAQ;;;;;;;EAOjC;;;;;;EAMA;;;;;;EAMA,SAAS;EACT;;;;;;EAMA,mBAAmB;EACnB;;;;;;EAMA;;;;;;;EAOA;;;;;;;EAOA;;;;;;;UAQe;EACf,eAAe;EACf,cAAc;EACd,mBAAmB;EACnB,mBAAmB;EACnB,0BAA0B;EAC1B,0BAA0B;EAC1B,kBAAkB;EAClB,8BAA8B;;;;;;KAOpB;EACV,OAAO,aAAa;EACpB,SAAS,eAAe;;;;;;;UAQT,6BAA6B,mBAAmB,qBAAqB;;;;;EAKpF;;;;;;EAMA,eAAe;;;;;;;;;EASf;;;;;;;EAOA,mCAAmC;EACnC;EACA;EACA;EACA;;;;;EAKA,0BAA0B,yBAAyB;;;;;;;EAOnD,kBAAkB;;;;;EAKlB,oBAAoB;;;;;EAKpB,mCAAmC;;;;;EAKnC,2CAA2C;;;;;EAK3C,2CAA2C;;;;;;EAM3C,gBAAgB,QAAQ;;;;;;EAMxB,aAAa,QAAQ;;;;;;EAMrB,YAAY,QAAQ;;;;;EAKpB,UAAU,QAAQ;;;;;EAKlB;;EAEA;;;;;EAKA,WAAW,QAAQ;;;;;;;EAOnB,WAAW;;;;;;;EAOX,uBAAuB;;;;;;EAMvB;;;;;;;EAOA,aAAa,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8CV,qBACd,SAAQ,uBACP,YAAY,qBAAqB"}

package/dist/dev/playback/engines/hls/engine.js

@@ -0,0 +1,144 @@
+import { createComposition } from "../../../core/composition/create-composition.js";
+import { makeShareSignals } from "../../../core/composition/share-signals.js";
+import { resolveVttSegment } from "../../../media/dom/text/resolve-vtt-segment.js";
+import { loadAudioSegments, loadTextTrackSegments, loadVideoSegments } from "../../behaviors/dom/load-segments.js";
+import { setupTextTrackActors } from "../../behaviors/dom/setup-text-track-actors.js";
+import { trackCurrentTime } from "../../behaviors/dom/track-current-time.js";
+import { trackLoadTriggers } from "../../behaviors/dom/track-load-triggers.js";
+import { deriveSharedMinStartMediaTime, establishStartMediaTime, gateFirstParseOnAnchor } from "../../behaviors/establish-start-media-time.js";
+import { collectErrors } from "../../behaviors/collect-errors.js";
+import { switchAudioTrack, switchTextTrack, switchVideoTrack } from "../../behaviors/track-switching.js";
+import { delayedReschedule } from "../../../core/tasks/delayed-reschedule.js";
+import { attachMediaSourceAsSourceElement } from "../../../media/dom/mse/mediasource-setup.js";
+import { canPlayTrack } from "../../../media/dom/capabilities.js";
+import { addSubtitlesTracksToMedia, getShowingSubtitlesTrackFromMedia, removeAllSubtitlesTracksFromMedia } from "../../../media/dom/text/text-track-slots.js";
+import { parseMultivariantPlaylist } from "../../../media/hls/parse-multivariant.js";
+import { mediaPlaylistReloadDelay, resolveLiveLatency } from "../../../media/hls/reload-policy.js";
+import { getResolvedSelectedTrackDuration } from "../../../media/utils/track-selection.js";
+import { calculatePresentationDuration } from "../../behaviors/calculate-presentation-duration.js";
+import { deriveCdnPriority } from "../../behaviors/derive-cdn-priority.js";
+import { setupAirPlay } from "../../behaviors/dom/airplay.js";
+import { applyStartPosition } from "../../behaviors/dom/apply-start-position.js";
+import { endOfStream } from "../../behaviors/dom/end-of-stream.js";
+import { recoverEndStall } from "../../behaviors/dom/recover-end-stall.js";
+import { seekToLiveEdge } from "../../behaviors/dom/seek-to-live-edge.js";
+import { setupAudioBufferActors, setupVideoBufferActors } from "../../behaviors/dom/setup-buffer-actors.js";
+import { setupMediaSource } from "../../behaviors/dom/setup-mediasource.js";
+import { syncLiveSeekableRange } from "../../behaviors/dom/sync-live-seekable-range.js";
+import { syncTextTracks } from "../../behaviors/dom/sync-text-tracks.js";
+import { trackPlayerResolution } from "../../behaviors/dom/track-player-resolution.js";
+import { updateMediaSourceDuration } from "../../behaviors/dom/update-mediasource-duration.js";
+import { resolvePresentation } from "../../behaviors/resolve-presentation.js";
+import { resolveAudioTrack, resolveTextTrack, resolveVideoTrack } from "../../behaviors/resolve-track.js";
+import { setupFailoverMonitor } from "../../behaviors/setup-failover-monitor.js";
+import { syncPreload } from "../../behaviors/sync-preload.js";
+import { relocatingTextPipelines, relocationPipelinesFor } from "../../primitives/relocation-pipelines.js";
+import { reportUnsupportedTrackConditions } from "../../primitives/report-track-conditions.js";
+//#region src/playback/engines/hls/engine.ts
+/**
+* Generic `shareSignals` instantiated against the HLS engine's full state and context — captures composition signal
+* refs into the consumer's `onSignalsReady` callback at setup time, and materializes input slots that no composed
+* behavior produces: `user*TrackSelection` (track-switching only reads them). `failedCdns` is owned by
+* `setupFailoverMonitor`, so it's already materialized and reachable on the `onSignalsReady` refs without being listed
+* here.
+*/
+const shareSignals = makeShareSignals([
+	"userVideoTrackSelection",
+	"userAudioTrackSelection",
+	"userTextTrackSelection",
+	"disableRemotePlayback"
+]);
+/**
+* Create an HLS playback engine.
+*
+* Composes SPF behaviors into a reactive pipeline for HLS playback over MSE: manifest resolution, track selection, ABR,
+* segment loading, and end-of-stream coordination.
+*
+* @example
+*   ```ts
+*   let signals: HlsVideoEngineSignals;
+*   const engine = createHlsVideoEngine({
+*     initialBandwidth: 2_000_000,
+*     preferredAudioLanguage: 'en',
+*     onSignalsReady: (refs) => {
+*       signals = refs;
+*     },
+*   });
+*
+*   signals.context.mediaElement.set(videoEl);
+*   signals.state.presentation.set({ url: 'https://example.com/stream.m3u8' });
+*
+*   videoEl.play();
+*
+*   await engine.destroy();
+*   ```;
+*/
+function createHlsVideoEngine(config = {}) {
+	const deriveStartMediaTime = config.deriveStartMediaTime ?? deriveSharedMinStartMediaTime;
+	const finalConfig = {
+		...config,
+		deriveStartMediaTime,
+		attachMediaSource: attachMediaSourceAsSourceElement,
+		canPlayTrack: config.canPlayTrack ?? canPlayTrack,
+		reportUnsupportedTrackConditions: config.reportUnsupportedTrackConditions ?? reportUnsupportedTrackConditions,
+		resolveTextTrackSegment: config.resolveTextTrackSegment ?? resolveVttSegment,
+		textMessagePipelines: relocatingTextPipelines,
+		resolveDuration: config.resolveDuration ?? getResolvedSelectedTrackDuration,
+		parsePresentation: config.parsePresentation ?? parseMultivariantPlaylist,
+		addSubtitlesTracksToMedia: config.addSubtitlesTracksToMedia ?? addSubtitlesTracksToMedia,
+		getShowingSubtitlesTrackFromMedia: config.getShowingSubtitlesTrackFromMedia ?? getShowingSubtitlesTrackFromMedia,
+		removeAllSubtitlesTracksFromMedia: config.removeAllSubtitlesTracksFromMedia ?? removeAllSubtitlesTracksFromMedia,
+		videoMessagePipelines: relocationPipelinesFor("video", deriveStartMediaTime),
+		audioMessagePipelines: relocationPipelinesFor("audio", deriveStartMediaTime),
+		gateFirstParse: gateFirstParseOnAnchor,
+		resolveLiveLatency,
+		reschedule: config.reschedule ?? delayedReschedule(mediaPlaylistReloadDelay)
+	};
+	return createComposition([
+		syncPreload,
+		trackLoadTriggers,
+		resolvePresentation,
+		deriveCdnPriority,
+		setupFailoverMonitor,
+		collectErrors,
+		resolveVideoTrack,
+		resolveAudioTrack,
+		resolveTextTrack,
+		calculatePresentationDuration,
+		setupMediaSource,
+		updateMediaSourceDuration,
+		establishStartMediaTime,
+		setupVideoBufferActors,
+		setupAudioBufferActors,
+		setupAirPlay,
+		trackCurrentTime,
+		applyStartPosition,
+		trackPlayerResolution,
+		switchVideoTrack,
+		switchAudioTrack,
+		switchTextTrack,
+		loadVideoSegments,
+		loadAudioSegments,
+		syncLiveSeekableRange,
+		seekToLiveEdge,
+		endOfStream,
+		recoverEndStall,
+		syncTextTracks,
+		setupTextTrackActors,
+		loadTextTrackSegments,
+		shareSignals
+	], {
+		config: finalConfig,
+		initialState: { bandwidthState: {
+			fastEstimate: 0,
+			fastTotalWeight: 0,
+			slowEstimate: 0,
+			slowTotalWeight: 0,
+			bytesSampled: 0
+		} }
+	});
+}
+//#endregion
+export { createHlsVideoEngine };
+
+//# sourceMappingURL=engine.js.map

package/dist/dev/playback/engines/hls/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","names":[],"sources":["../../../../../src/playback/engines/hls/engine.ts"],"sourcesContent":["import {\n  type Composition,\n  type ContextSignals,\n  createComposition,\n  type StateSignals,\n} from '../../../core/composition/create-composition';\nimport { makeShareSignals, type ShareSignalsConfig } from '../../../core/composition/share-signals';\nimport { delayedReschedule } from '../../../core/tasks/delayed-reschedule';\nimport type { Reschedule } from '../../../core/tasks/task';\nimport type { QualityConfig } from '../../../media/abr/quality-selection';\nimport type { BackBufferConfig } from '../../../media/buffer/back-buffer';\nimport type { ForwardBufferConfig } from '../../../media/buffer/forward-buffer';\nimport { canPlayTrack } from '../../../media/dom/capabilities';\nimport { attachMediaSourceAsSourceElement } from '../../../media/dom/mse/mediasource-setup';\nimport { resolveVttSegment } from '../../../media/dom/text/resolve-vtt-segment';\nimport {\n  addSubtitlesTracksToMedia,\n  getShowingSubtitlesTrackFromMedia,\n  removeAllSubtitlesTracksFromMedia,\n} from '../../../media/dom/text/text-track-slots';\nimport type { SvtaError } from '../../../media/errors';\nimport { parseMultivariantPlaylist } from '../../../media/hls/parse-multivariant';\nimport { mediaPlaylistReloadDelay, resolveLiveLatency } from '../../../media/hls/reload-policy';\nimport type {\n  AudioTrack,\n  CanPlayTrack,\n  MaybeResolvedPresentation,\n  MediaContainerData,\n  ResolvedTrack,\n  TextTrack,\n  VideoTrack,\n} from '../../../media/types';\nimport type { GetCdnId } from '../../../media/utils/cdn';\nimport { getResolvedSelectedTrackDuration } from '../../../media/utils/track-selection';\nimport type { BandwidthConfig, BandwidthState } from '../../../network/bandwidth-estimator';\nimport type { SegmentLoaderActor } from '../../actors/dom/segment-loader';\nimport type { SourceBufferActor } from '../../actors/dom/source-buffer';\nimport type { TextTracksActor } from '../../actors/dom/text-tracks';\nimport type { TextTrackSegmentLoaderActor } from '../../actors/text-track-segment-loader';\nimport {\n  calculatePresentationDuration,\n  type PresentationDurationResolver,\n} from '../../behaviors/calculate-presentation-duration';\nimport { collectErrors } from '../../behaviors/collect-errors';\nimport { deriveCdnPriority } from '../../behaviors/derive-cdn-priority';\nimport { setupAirPlay } from '../../behaviors/dom/airplay';\nimport { applyStartPosition } from '../../behaviors/dom/apply-start-position';\nimport { endOfStream } from '../../behaviors/dom/end-of-stream';\nimport { loadAudioSegments, loadTextTrackSegments, loadVideoSegments } from '../../behaviors/dom/load-segments';\nimport { recoverEndStall } from '../../behaviors/dom/recover-end-stall';\nimport { seekToLiveEdge } from '../../behaviors/dom/seek-to-live-edge';\nimport { setupAudioBufferActors, setupVideoBufferActors } from '../../behaviors/dom/setup-buffer-actors';\nimport { setupMediaSource } from '../../behaviors/dom/setup-mediasource';\nimport { setupTextTrackActors } from '../../behaviors/dom/setup-text-track-actors';\nimport { syncLiveSeekableRange } from '../../behaviors/dom/sync-live-seekable-range';\nimport { syncTextTracks } from '../../behaviors/dom/sync-text-tracks';\nimport { trackCurrentTime } from '../../behaviors/dom/track-current-time';\nimport { trackLoadTriggers } from '../../behaviors/dom/track-load-triggers';\nimport { type PlayerResolution, trackPlayerResolution } from '../../behaviors/dom/track-player-resolution';\nimport { updateMediaSourceDuration } from '../../behaviors/dom/update-mediasource-duration';\n// Non-zero-PTS relocation (spike): remove this import, the composed reactor, the\n// `video/audio/textMessagePipelines` finalConfig entries, the `mediaContainerData`\n// state slot, and the `deriveStartMediaTime` config field to drop relocation entirely\n// (text then falls back to the plain `resolveVttSegment` resolver).\nimport {\n  type DeriveStartMediaTime,\n  deriveSharedMinStartMediaTime,\n  establishStartMediaTime,\n  gateFirstParseOnAnchor,\n} from '../../behaviors/establish-start-media-time';\nimport { type ParsePresentation, resolvePresentation } from '../../behaviors/resolve-presentation';\nimport { resolveAudioTrack, resolveTextTrack, resolveVideoTrack } from '../../behaviors/resolve-track';\nimport { type FailoverMonitorConfig, setupFailoverMonitor } from '../../behaviors/setup-failover-monitor';\nimport { syncPreload } from '../../behaviors/sync-preload';\nimport { switchAudioTrack, switchTextTrack, switchVideoTrack } from '../../behaviors/track-switching';\nimport { relocatingTextPipelines, relocationPipelinesFor } from '../../primitives/relocation-pipelines';\nimport {\n  type ReportUnsupportedTrackConditions,\n  reportUnsupportedTrackConditions,\n} from '../../primitives/report-track-conditions';\nimport type { TextTrackSegmentResolver } from '../../primitives/text-segment-load-pipeline';\n\n// ============================================================================\n// HLS Engine State & Context\n// ============================================================================\n\n/**\n * State shape for the HLS playback engine.\n *\n * This is the union of all state required by the behaviors composed into the HLS engine. Each behavior declares its own\n * state interface; this type satisfies all of them.\n */\nexport interface HlsVideoEngineState {\n  /**\n   * The presentation being played. A caller writes `{ url }`; `resolvePresentation` parses the manifest and populates\n   * the rest.\n   */\n  presentation?: MaybeResolvedPresentation;\n  preload?: 'auto' | 'metadata' | 'none';\n  selectedVideoTrackId?: string;\n  selectedAudioTrackId?: string;\n  selectedTextTrackId?: string;\n  bandwidthState?: BandwidthState;\n  // Non-zero-PTS relocation (spike): transient per-track container data owned by\n  // `establishStartMediaTime`. Remove with the composed reactor.\n  mediaContainerData?: Record<string, MediaContainerData>;\n  userVideoTrackSelection?: Partial<VideoTrack>;\n  /**\n   * Consumer-driven constraint narrowing the audio candidate set. Sibling of `userVideoTrackSelection`. Partial-track\n   * shape — `{ language: 'es' }`, `{ id: 'audio-en' }`, etc. `selectAudioTrack` reads this and re-picks when it\n   * changes. Multi-language-audio Tier 2 programmatic-write path.\n   */\n  userAudioTrackSelection?: Partial<AudioTrack>;\n  /**\n   * Consumer-driven _intent_ for text selection, resolved into `selectedTextTrackId` by `switchTextTrack`. A\n   * language-based partial (`{ language: 'es' }`) selects captions, `'off'` disables them, and absence means auto (the\n   * engine's `preferredSubtitleLanguage` / DEFAULT-track policy). Also the write path for the DOM caption UI (via\n   * `syncTextTracks`); unlike the resolved id it persists across source changes (sticky preference).\n   */\n  userTextTrackSelection?: Partial<TextTrack> | 'off';\n  /**\n   * The CDNs the source is served from (track-URL origins), in manifest priority order — most-preferred first (mirrors\n   * HLS content steering's `PATHWAY-PRIORITY`). Owned by `deriveCdnPriority`, read by `track-switching`'s\n   * `preferActiveCdn` scope, which narrows to the highest-priority CDN with surviving tracks so video / audio / text\n   * stay on one host. Only meaningful for redundant-stream sources; a single-CDN source has one entry.\n   */\n  cdnPriority?: string[];\n  /**\n   * CDN ids (origins) currently in failover cooldown — written by the CDN monitor when a host fails too often, read by\n   * `track-switching`'s `excludeFailedCdns` hard constraint, which prunes their tracks so the active-CDN scope falls to\n   * the next CDN in `cdnPriority`. Empty / absent means all CDNs are eligible.\n   */\n  failedCdns?: string[];\n  /**\n   * Conditions reported during playback, in the order encountered — appended by whichever behavior detects one\n   * (`emitError`), owned and cleared per source by `collectErrors`. Carries no severity: which of these is fatal is\n   * decided above the engine, at the adapter. See `internal/design/spf/features/errors.md`.\n   */\n  errors?: SvtaError[];\n  currentTime?: number;\n  /**\n   * The player element's rendered pixel dimensions, or `undefined` where there is nothing to measure. Written by\n   * `trackPlayerResolution`, read by the `playerResolutionCap` selection rule — which treats `undefined` as \"don't\n   * cap\".\n   */\n  playerResolution?: PlayerResolution;\n  loadActivated?: boolean;\n  /**\n   * One-shot command: start the current source at this position (presentation-timeline seconds). Written by consumers\n   * or by `setupAirPlay`'s session-end snapshot; consumed (cleared) by `applyStartPosition` once the element seeks. See\n   * `behaviors/dom/apply-start-position.ts`.\n   */\n  startPosition?: number;\n  /**\n   * Intent-level loading policy: initiate no new loading work while `true`. Written by `setupAirPlay` (the only\n   * behavior declaring the key) while a remote-playback session owns presentation; observed by the `loadXSegments`\n   * dispatchers (park in `'dormant'`) and by `setupMediaSource` (a pending rebuild waits). See\n   * `SegmentLoadingState['loadingSuspended']`.\n   */\n  loadingSuspended?: boolean;\n  /**\n   * Author intent for the AirPlay/remote-playback picker, written by the media adapter's `disableRemotePlayback` IDL\n   * property. `true` is an explicit opt-out: `setupAirPlay` reads it at attach and sets nothing up, leaving the\n   * element's remote playback disabled. Distinct from the underlying `<video>.disableRemotePlayback`, which stays\n   * programmatically managed (ManagedMediaSource / AirPlay).\n   */\n  disableRemotePlayback?: boolean;\n}\n\n/**\n * Context shape for the HLS playback engine.\n *\n * Platform objects and actor references managed by HLS behaviors.\n */\nexport interface HlsVideoEngineContext {\n  mediaElement?: HTMLMediaElement | undefined;\n  mediaSource?: MediaSource;\n  videoBufferActor?: SourceBufferActor;\n  audioBufferActor?: SourceBufferActor;\n  videoSegmentLoaderActor?: SegmentLoaderActor;\n  audioSegmentLoaderActor?: SegmentLoaderActor;\n  textTracksActor?: TextTracksActor;\n  textTrackSegmentLoaderActor?: TextTrackSegmentLoaderActor;\n}\n\n/**\n * The composition signal refs handed to `onSignalsReady` callers — the canonical way to drive the engine externally\n * (writes) or observe its state (reads) without touching `composition.state` / `composition.context` directly.\n */\nexport type HlsVideoEngineSignals = {\n  state: StateSignals<HlsVideoEngineState>;\n  context: ContextSignals<HlsVideoEngineContext>;\n};\n\n/**\n * Configuration for the HLS playback engine.\n *\n * Each option is consumed by the appropriate behavior — the engine itself has no config beyond what its behaviors read.\n */\nexport interface HlsVideoEngineConfig extends ShareSignalsConfig<HlsVideoEngineState, HlsVideoEngineContext> {\n  /**\n   * Bandwidth estimate in bps to use before enough samples have been collected. Default: `DEFAULT_INITIAL_BANDWIDTH` (5\n   * Mbps).\n   */\n  initialBandwidth?: number;\n  /**\n   * Codec capability probe injected into `track-switching`'s `excludeUnplayableTracks` constraint — drops renditions\n   * the environment can't decode before selection. Defaults to the `MediaSource.isTypeSupported` -backed\n   * `canPlayTrack`; supply your own to override (e.g. force-exclude a codec).\n   */\n  canPlayTrack?: CanPlayTrack;\n  /**\n   * Codec families (RFC 6381 4CCs, e.g. `'avc1'` / `'hvc1'` / `'mp4a'`) the initial video/audio picks prefer on a\n   * mixed-codec source, read by the `preferCodecFamilies` selection scope. SPF implements no\n   * `SourceBuffer.changeType()`, so the initial pick's codec family is sticky for the source's lifetime\n   * (`stickToSelectedCodecs`); this decides which family that is. Soft — a source with no preferred-family rendition is\n   * unaffected. Defaults to `DEFAULT_PREFERRED_CODECS` (AVC + AAC, the broadest-decode pair); pass `[]` to disable and\n   * let ABR pick the initial family (it then still can't leave it mid-stream).\n   */\n  preferredCodecs?: string[];\n  /**\n   * Conditions reported about each rendition as it resolves — the _causes_ behind a later verdict, and the copy a\n   * verdict reuses when they agree. Defaults to {@link reportUnsupportedTrackConditions}, which reports non-fMP4\n   * containers and encryption; supply your own to report a different set (a provider that never ships MPEG-TS can drop\n   * that check) or `() => []` to report nothing.\n   */\n  reportUnsupportedTrackConditions?: ReportUnsupportedTrackConditions;\n  preferredAudioLanguage?: string;\n  preferredSubtitleLanguage?: string;\n  includeForcedTracks?: boolean;\n  enableDefaultTrack?: boolean;\n  /**\n   * Resolver that turns a text-track segment fetch into VTT cues. Defaults to the DOM-bound `resolveVttSegment`\n   * resolver, which uses an offscreen `<track>` element to parse WebVTT.\n   */\n  resolveTextTrackSegment?: TextTrackSegmentResolver<VTTCue>;\n  /**\n   * Resolver for `presentation.duration`. Defaults to picking the first resolved selected track's duration (video\n   * preferred, audio fallback) — appropriate for VoD and audio-only. Live engines should supply a resolver that returns\n   * `Number.POSITIVE_INFINITY` once the presentation is established as live; downstream `updateMediaSourceDuration`\n   * propagates that value to `mediaSource.duration` per the MSE spec.\n   */\n  resolveDuration?: PresentationDurationResolver;\n  /**\n   * Manifest parser handed to `resolvePresentation`. Defaults to the HLS multivariant-playlist parser; supply your own\n   * for alternate format support without forking the engine.\n   */\n  parsePresentation?: ParsePresentation;\n  /**\n   * Allocate SPF-owned text-track slots on the media element. Defaults to the standard `<track>`-element implementation\n   * in `media/dom/text/text-track-slots`.\n   */\n  addSubtitlesTracksToMedia?: typeof addSubtitlesTracksToMedia;\n  /**\n   * Return the SPF-owned subtitle/caption `TextTrack` currently in showing mode. Defaults to the standard\n   * selector-based implementation in `media/dom/text/text-track-slots`.\n   */\n  getShowingSubtitlesTrackFromMedia?: typeof getShowingSubtitlesTrackFromMedia;\n  /**\n   * Evict all SPF-owned text-track slots from the media element. Defaults to the standard selector-based implementation\n   * in `media/dom/text/text-track-slots`.\n   */\n  removeAllSubtitlesTracksFromMedia?: typeof removeAllSubtitlesTracksFromMedia;\n  /**\n   * Forward-buffer tuning. `bufferDuration` controls how far ahead of the playhead segments are loaded (and where\n   * forward-flush kicks in). Defaults: see `DEFAULT_FORWARD_BUFFER_CONFIG` (30 seconds). Threaded to segment-loader\n   * actors (v/a + text) at construction time and to `loadXSegments` dispatchers for the load-message range.\n   */\n  forwardBuffer?: Partial<ForwardBufferConfig>;\n  /**\n   * Back-buffer tuning. `keepSegments` controls how many segments stay behind the playhead before eviction. Defaults:\n   * see `DEFAULT_BACK_BUFFER_CONFIG` (2 segments). Threaded to the v/a segment-loader actor only (text tracks don't use\n   * back-buffer eviction).\n   */\n  backBuffer?: Partial<BackBufferConfig>;\n  /**\n   * Bandwidth-estimator tuning. Overrides any field of `BandwidthConfig` (`fastHalfLife`, `slowHalfLife`,\n   * `minTotalBytes`, `minBytes`, `minDuration`). `bandwidth.minTotalBytes` supersedes the flat `minTotalBytes` field\n   * above. Defaults: see `DEFAULT_BANDWIDTH_CONFIG`.\n   */\n  bandwidth?: Partial<BandwidthConfig>;\n  /**\n   * Quality-selection tuning. `safetyMargin` is the bandwidth-headroom multiplier used by `selectQuality`;\n   * `upgradeMargin` is the hysteresis ratio gating ABR upgrades. Defaults: `DEFAULT_QUALITY_CONFIG` (0.85 / 1.15).\n   */\n  quality?: Partial<QualityConfig>;\n  /**\n   * Whether video renditions are capped to the player element's rendered size. Read by `trackPlayerResolution`; `false`\n   * measures nothing, which leaves the `playerResolutionCap` rule inert. Defaults to `true`.\n   */\n  capRenditionToPlayerSize?: boolean;\n  /** Whether `state.playerResolution` is reported in device pixels. Read by `trackPlayerResolution`; defaults to `true`. */\n  useDevicePixelRatio?: boolean;\n  /**\n   * Multi-CDN failover monitor tuning. `cooldownMs` is how long a CDN stays excluded after a failed fetch trips it.\n   * Defaults: `DEFAULT_FAILOVER_MONITOR_CONFIG` (300s). Only meaningful for redundant-stream sources.\n   */\n  failover?: Partial<FailoverMonitorConfig>;\n  /**\n   * How to derive a CDN grouping key from a track URL — used to build `cdnPriority`, to record the failover trip in\n   * `failedCdns`, and by the track-switching CDN scope + failover constraint. One function, read by all of them, so the\n   * keys stay comparable. Defaults to the URL origin; override to key on something else (e.g. Mux's `cdn=` query\n   * param).\n   */\n  getCdnId?: GetCdnId;\n  /**\n   * Non-zero-PTS relocation (spike): the reduce seam consumed by the `establishStartMediaTime` reactor. Defaults to\n   * per-track own origin (Tier 1); a Tier-2 variant returns the shared `min` across selected A/V. Relocation is\n   * composed into the standard engine below — see the marked block — so this only needs setting to swap the tier\n   * policy. See `internal/design/spf/presentation-timeline-model.md`.\n   */\n  deriveStartMediaTime?: DeriveStartMediaTime;\n  /**\n   * Proximity window (seconds) for the `recoverEndStall` behavior — how close the playhead must be to the reachable\n   * buffered end for a `waiting` to be treated as the end-of-stream freeze and nudged to `ended`. Defaults to `0.2`.\n   * See `behaviors/dom/recover-end-stall`.\n   */\n  endStallNudgeWindow?: number;\n  /**\n   * Live media-playlist re-run policy for the resolve* loaders' `RecurringRunner`: returns a promise that resolves when\n   * the playlist should reload, or `null` to stop. Defaults to `mediaPlaylistReloadDelay` (target-duration cadence,\n   * half on an unchanged window, stop on `#EXT-X-ENDLIST`) composed with a cancellable `sleep`. Inert for VoD (a\n   * complete playlist stops it after the first resolve). Override to tune live reload timing.\n   */\n  reschedule?: Reschedule<ResolvedTrack>;\n}\n\n// ============================================================================\n// HLS Playback Engine\n// ============================================================================\n\n/**\n * Generic `shareSignals` instantiated against the HLS engine's full state and context — captures composition signal\n * refs into the consumer's `onSignalsReady` callback at setup time, and materializes input slots that no composed\n * behavior produces: `user*TrackSelection` (track-switching only reads them). `failedCdns` is owned by\n * `setupFailoverMonitor`, so it's already materialized and reachable on the `onSignalsReady` refs without being listed\n * here.\n */\nconst shareSignals = makeShareSignals<HlsVideoEngineState, HlsVideoEngineContext>([\n  'userVideoTrackSelection',\n  'userAudioTrackSelection',\n  'userTextTrackSelection',\n  'disableRemotePlayback',\n]);\n\n/**\n * Create an HLS playback engine.\n *\n * Composes SPF behaviors into a reactive pipeline for HLS playback over MSE: manifest resolution, track selection, ABR,\n * segment loading, and end-of-stream coordination.\n *\n * @example\n *   ```ts\n *   let signals: HlsVideoEngineSignals;\n *   const engine = createHlsVideoEngine({\n *     initialBandwidth: 2_000_000,\n *     preferredAudioLanguage: 'en',\n *     onSignalsReady: (refs) => {\n *       signals = refs;\n *     },\n *   });\n *\n *   signals.context.mediaElement.set(videoEl);\n *   signals.state.presentation.set({ url: 'https://example.com/stream.m3u8' });\n *\n *   videoEl.play();\n *\n *   await engine.destroy();\n *   ```;\n */\nexport function createHlsVideoEngine(\n  config: HlsVideoEngineConfig = {}\n): Composition<HlsVideoEngineState, HlsVideoEngineContext> {\n  // Non-zero-PTS relocation (spike): resolve the coordination seam once so the reactor\n  // (model `startMediaTime`) and the loader stamps (buffer `timestampOffset`) apply the\n  // SAME derive. Default is shared-`min` across selected A/V (subsumes per-type).\n  const deriveStartMediaTime = config.deriveStartMediaTime ?? deriveSharedMinStartMediaTime;\n  const finalConfig = {\n    ...config,\n    deriveStartMediaTime,\n    // Baked (not user-overridable): this engine composes `setupAirPlay`,\n    // whose native fallback `<source>` requires the MSE attachment to keep\n    // sibling source alternatives part of resource selection.\n    attachMediaSource: attachMediaSourceAsSourceElement,\n    canPlayTrack: config.canPlayTrack ?? canPlayTrack,\n    reportUnsupportedTrackConditions: config.reportUnsupportedTrackConditions ?? reportUnsupportedTrackConditions,\n    resolveTextTrackSegment: config.resolveTextTrackSegment ?? resolveVttSegment,\n    // Non-zero-PTS relocation (spike): the text pipeline rebases cues onto the\n    // relocated 0-based timeline. Remove `textMessagePipelines` to drop text relocation.\n    textMessagePipelines: relocatingTextPipelines,\n    resolveDuration: config.resolveDuration ?? getResolvedSelectedTrackDuration,\n    parsePresentation: config.parsePresentation ?? parseMultivariantPlaylist,\n    addSubtitlesTracksToMedia: config.addSubtitlesTracksToMedia ?? addSubtitlesTracksToMedia,\n    getShowingSubtitlesTrackFromMedia: config.getShowingSubtitlesTrackFromMedia ?? getShowingSubtitlesTrackFromMedia,\n    removeAllSubtitlesTracksFromMedia: config.removeAllSubtitlesTracksFromMedia ?? removeAllSubtitlesTracksFromMedia,\n    // Non-zero-PTS relocation (spike): the discover/stamp steps `establishStartMediaTime`\n    // pairs with. They apply the same `deriveStartMediaTime` seam as the reactor. Remove\n    // these two lines with the reactor.\n    videoMessagePipelines: relocationPipelinesFor('video', deriveStartMediaTime),\n    audioMessagePipelines: relocationPipelinesFor('audio', deriveStartMediaTime),\n    // Live-anchor establishment order: each non-reference track's first parse\n    // waits for the reference track to settle the wall-clock anchor question\n    // (see `gate-first-parse.ts`); pairs with the reactor's anchor stamp.\n    gateFirstParse: gateFirstParseOnAnchor,\n    // Format-neutral live-latency seam for `seekToLiveEdge` — the HLS resolver\n    // (HOLD-BACK); a DASH engine would inject `suggestedPresentationDelay`.\n    resolveLiveLatency,\n    // The resolve* loaders' RecurringRunner re-runs on this `reschedule`: the pure\n    // target-duration cadence, start-anchored + made awaitable by `delayedReschedule`.\n    // Inert for VoD (the cadence returns null once a playlist is complete), so it\n    // composes always.\n    reschedule: config.reschedule ?? delayedReschedule(mediaPlaylistReloadDelay),\n  };\n\n  return createComposition(\n    [\n      syncPreload,\n      trackLoadTriggers,\n      resolvePresentation,\n\n      // Session-level CDN priority for redundant-stream sources. Owns\n      // `cdnPriority`; `track-switching`'s preferActiveCdn scope reads it so\n      // every type stays on one CDN. No-op for single-CDN sources.\n      //\n      // Placed before switch* so `cdnPriority` is set before the first pick —\n      // but this ordering is only *mildly* load-bearing, not required for\n      // correctness. Selection is reactive: a late `cdnPriority` re-fires the\n      // pick and converges on the same result (see the late-arrival test in\n      // track-switching.test.ts). Order affects only a transient, and only for\n      // an *asymmetric* manifest (a type listing a non-primary CDN first):\n      // composing this after switch* would let that type fire one wasted\n      // media-playlist fetch to the wrong CDN before correcting. Symmetric\n      // redundant streams (the norm) never hit it — the first-listed CDN is\n      // already the primary we'd pick anyway.\n      deriveCdnPriority,\n\n      // CDN failover cooldown: owns the expiry half of failover — watches\n      // `failedCdns` (tripped directly by track resolution on a failed\n      // media-playlist fetch) and removes each CDN once its cooldown lapses.\n      setupFailoverMonitor,\n\n      // Owns `errors` and its per-source lifecycle. Composed before the\n      // behaviors that report into it so the slot exists when they first run;\n      // reporting no-ops if it isn't composed at all.\n      collectErrors,\n\n      // Resolve selected tracks (fetch media playlists). Composed before the\n      // switch* slot owners; selection is reactive, so a resolve* re-fires once\n      // its switch* sets the id (same convergence for all three types).\n      resolveVideoTrack,\n      resolveAudioTrack,\n      resolveTextTrack,\n\n      // Presentation duration\n      calculatePresentationDuration,\n\n      // MSE setup. Video cluster is registered first so that, when both\n      // per-type variants flip to `'buffer-ready'` on the shared gate's\n      // monitor evaluation, `addSourceBuffer(video)` runs before\n      // `addSourceBuffer(audio)` — see the Firefox `mozHasAudio` invariant\n      // in setup-buffer-actors.ts.\n      setupMediaSource,\n      updateMediaSourceDuration,\n\n      // ── Non-zero-PTS relocation (spike) ──────────────────────────────────\n      // Establishes per-track `startMediaTime` and publishes the relocating\n      // segment-loader pipelines to context. MUST precede `setup*BufferActors`\n      // so the pipelines are published before the loaders read them. Remove this\n      // one line (+ the import, the `mediaContainerData`/`*MessagePipelines`\n      // slots including `textMessagePipelines`, and the `deriveStartMediaTime`\n      // config) to drop relocation and test the Tier-0 baseline / bundle size.\n      establishStartMediaTime,\n      // ─────────────────────────────────────────────────────────────────────\n\n      setupVideoBufferActors,\n      setupAudioBufferActors,\n\n      // AirPlay/MSE bridge (WebKit only; no-op elsewhere).\n      setupAirPlay,\n\n      // Playback tracking\n      trackCurrentTime,\n      // After trackCurrentTime: the one-shot currentTime seed must land after\n      // the mirror's attach-time sync (see apply-start-position.ts).\n      applyStartPosition,\n\n      // Ordering isn't load-bearing — selection is reactive, so a measurement\n      // that lands after the first pick just re-fires it.\n      trackPlayerResolution,\n      switchVideoTrack,\n      switchAudioTrack,\n      // Mid-stream audio-buffer flush on language switch is handled in\n      // `segment-loader`'s `planTasks` (predicate: language differs from\n      // the previously-buffered track) — not in switchAudioTrack itself.\n\n      // Text selection: resolves `userTextTrackSelection` intent (incl. 'off',\n      // or the configured preferred-language / DEFAULT-track policy) against the\n      // failed-CDN-pruned, active-CDN-scoped text renditions. Optional selection\n      // (captions are opt-in), so it can resolve to none.\n      switchTextTrack,\n\n      // Segment loading\n      loadVideoSegments,\n      loadAudioSegments,\n\n      // Live: declare the seekable window, then command the live-edge start\n      // position + keep the playhead in-window. No-op for complete playlists\n      // (VoD / ended). `seekToLiveEdge` commands `state.startPosition`;\n      // `applyStartPosition` (composed above) performs the seek.\n      syncLiveSeekableRange,\n      seekToLiveEdge,\n\n      // End of stream coordination\n      endOfStream,\n      // Force native `ended` when Chrome freezes the playhead a few frames short of a\n      // skewed-A/V end after `endOfStream` (audio-clock stall). Inert otherwise.\n      recoverEndStall,\n\n      // Text tracks\n      syncTextTracks,\n      setupTextTrackActors,\n      loadTextTrackSegments,\n\n      // Behavior whose sole purpose is to use a callback to allow for signal writing from the outside (e.g. an adapter)\n      // NOTE: While not required, adding at the end since behaviors are setup in order, so this increases the likelihood\n      // that initial signal setup will have occurred before shareSignals' callback is invoked. (CJP)\n      shareSignals,\n    ],\n    {\n      config: finalConfig,\n      // Seed bandwidthState so switchVideoTrack fires on initial subscribe\n      // with the `initialBandwidth` fallback rather than waiting for the\n      // first chunk. The empty sample buffer means `getBandwidthEstimate`\n      // returns the configured initial bandwidth until real samples land.\n      initialState: {\n        bandwidthState: {\n          fastEstimate: 0,\n          fastTotalWeight: 0,\n          slowEstimate: 0,\n          slowTotalWeight: 0,\n          bytesSampled: 0,\n        },\n      },\n    }\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkVA,MAAM,eAAe,iBAA6D;CAChF;CACA;CACA;CACA;AACF,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BD,SAAgB,qBACd,SAA+B,CAAC,GACyB;CAIzD,MAAM,uBAAuB,OAAO,wBAAwB;CAC5D,MAAM,cAAc;EAClB,GAAG;EACH;EAIA,mBAAmB;EACnB,cAAc,OAAO,gBAAgB;EACrC,kCAAkC,OAAO,oCAAoC;EAC7E,yBAAyB,OAAO,2BAA2B;EAG3D,sBAAsB;EACtB,iBAAiB,OAAO,mBAAmB;EAC3C,mBAAmB,OAAO,qBAAqB;EAC/C,2BAA2B,OAAO,6BAA6B;EAC/D,mCAAmC,OAAO,qCAAqC;EAC/E,mCAAmC,OAAO,qCAAqC;EAI/E,uBAAuB,uBAAuB,SAAS,oBAAoB;EAC3E,uBAAuB,uBAAuB,SAAS,oBAAoB;EAI3E,gBAAgB;EAGhB;EAKA,YAAY,OAAO,cAAc,kBAAkB,wBAAwB;CAC7E;CAEA,OAAO,kBACL;EACE;EACA;EACA;EAgBA;EAKA;EAKA;EAKA;EACA;EACA;EAGA;EAOA;EACA;EASA;EAGA;EACA;EAGA;EAGA;EAGA;EAIA;EACA;EACA;EASA;EAGA;EACA;EAMA;EACA;EAGA;EAGA;EAGA;EACA;EACA;EAKA;CACF,GACA;EACE,QAAQ;EAKR,cAAc,EACZ,gBAAgB;GACd,cAAc;GACd,iBAAiB;GACjB,cAAc;GACd,iBAAiB;GACjB,cAAc;EAChB,EACF;CACF,CACF;AACF"}

package/dist/dev/playback/primitives/derive-start-media-time.d.ts

@@ -0,0 +1,16 @@
+import { MediaContainerData } from "../../media/types/index.js";
+//#region src/playback/primitives/derive-start-media-time.d.ts
+/** The selected v/a track ids a {@link DeriveStartMediaTime} may coordinate across. */
+interface DeriveStartMediaTimeContext {
+  selectedVideoTrackId?: string;
+  selectedAudioTrackId?: string;
+}
+/**
+ * Reduce the discovered {@link MediaContainerData} (keyed by track type) into each type's `startMediaTime` origin;
+ * `undefined` means "not ready yet". Pure and injected — the single coordination seam the reactor and the loader stamp
+ * share.
+ */
+type DeriveStartMediaTime = (containerData: Record<string, MediaContainerData>, ctx: DeriveStartMediaTimeContext) => Record<string, number | undefined>;
+//#endregion
+export { DeriveStartMediaTime, DeriveStartMediaTimeContext };
+//# sourceMappingURL=derive-start-media-time.d.ts.map

package/dist/dev/playback/primitives/derive-start-media-time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive-start-media-time.d.ts","names":[],"sources":["../../../../src/playback/primitives/derive-start-media-time.ts"],"mappings":";;;UAUiB;EACf;EACA;;;;;;;KAQU,wBACV,eAAe,eAAe,qBAC9B,KAAK,gCACF"}

package/dist/dev/playback/primitives/error-messages.js

@@ -0,0 +1,42 @@
+//#region src/playback/primitives/error-messages.ts
+/**
+* Developer-facing copy for what this engine reports.
+*
+* Everything here reaches a **console**, never a viewer. Viewer-facing copy for a fatal condition is the presentation
+* layer's to compose: the engine reports a code, and a consumer maps that code to localized text it owns.
+*
+* Plain string constants, one export each. Nothing is parameterized — a message that names the engine has to be built
+* at the call site from state the engine carries around solely to say it, which is a lot of plumbing for a console
+* prefix. Separate exports rather than one object so a composition that logs neither notice doesn't carry their bytes.
+*/
+/**
+* Logged when a fatal `SVTA_UNSUPPORTED_PLAYBACK_FEATURE` is surfaced.
+*
+* The developer's half of that event; the viewer gets the localized copy the code maps to. One sentence is enough
+* because the specifics — which container, which rendition, whether it was DRM — stay structured on the reported
+* conditions logged beside it.
+*/
+const UNSUPPORTED_PLAYBACK_FEATURE_MESSAGE = "Can't play this source: it requires an unsupported playback feature.";
+/**
+* Logged for **any** fatal condition, by a composition whose failures don't all reduce to a missing feature.
+*
+* The background variant is the case: it treats a per-rendition cause as fatal on its own, so what reaches its surface
+* can be an unsupported container, DRM it can't decrypt, or a source carrying no video at all. Naming one feature would
+* be wrong for the last of those, so all three are named broadly. Deferring the _why_ to the conditions instead would
+* promise prose they don't carry — an `SvtaError` is a code and its context, and nothing on this path sets `message`.
+*/
+const UNPLAYABLE_SOURCE_MESSAGE = "Can't play this source — unsupported container, encryption, or no usable video track.";
+/**
+* LL-HLS delivery, played as standard live. The parser ignores partial segments and the loader fetches whole ones, so
+* latency lands wherever `HOLD-BACK` puts it — the stream plays, just not at the latency it was published for.
+*/
+const LOW_LATENCY_UNSUPPORTED_MESSAGE = "Low-Latency HLS is unsupported; playing as standard live at higher latency.";
+/**
+* `#EXT-X-PLAYLIST-TYPE:EVENT` — a growing window, which is how DVR is delivered. It plays, but the seekable-range and
+* live-edge handling for it is newer and less exercised than sliding-window live.
+*/
+const DVR_EXPERIMENTAL_MESSAGE = "DVR support for EVENT playlists is experimental.";
+//#endregion
+export { DVR_EXPERIMENTAL_MESSAGE, LOW_LATENCY_UNSUPPORTED_MESSAGE, UNPLAYABLE_SOURCE_MESSAGE, UNSUPPORTED_PLAYBACK_FEATURE_MESSAGE };
+
+//# sourceMappingURL=error-messages.js.map

package/dist/dev/playback/primitives/error-messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-messages.js","names":[],"sources":["../../../../src/playback/primitives/error-messages.ts"],"sourcesContent":["/**\n * Developer-facing copy for what this engine reports.\n *\n * Everything here reaches a **console**, never a viewer. Viewer-facing copy for a fatal condition is the presentation\n * layer's to compose: the engine reports a code, and a consumer maps that code to localized text it owns.\n *\n * Plain string constants, one export each. Nothing is parameterized — a message that names the engine has to be built\n * at the call site from state the engine carries around solely to say it, which is a lot of plumbing for a console\n * prefix. Separate exports rather than one object so a composition that logs neither notice doesn't carry their bytes.\n */\n\n/**\n * Logged when a fatal `SVTA_UNSUPPORTED_PLAYBACK_FEATURE` is surfaced.\n *\n * The developer's half of that event; the viewer gets the localized copy the code maps to. One sentence is enough\n * because the specifics — which container, which rendition, whether it was DRM — stay structured on the reported\n * conditions logged beside it.\n */\nexport const UNSUPPORTED_PLAYBACK_FEATURE_MESSAGE =\n  \"Can't play this source: it requires an unsupported playback feature.\";\n\n/**\n * Logged for **any** fatal condition, by a composition whose failures don't all reduce to a missing feature.\n *\n * The background variant is the case: it treats a per-rendition cause as fatal on its own, so what reaches its surface\n * can be an unsupported container, DRM it can't decrypt, or a source carrying no video at all. Naming one feature would\n * be wrong for the last of those, so all three are named broadly. Deferring the _why_ to the conditions instead would\n * promise prose they don't carry — an `SvtaError` is a code and its context, and nothing on this path sets `message`.\n */\nexport const UNPLAYABLE_SOURCE_MESSAGE =\n  \"Can't play this source — unsupported container, encryption, or no usable video track.\";\n\n/**\n * LL-HLS delivery, played as standard live. The parser ignores partial segments and the loader fetches whole ones, so\n * latency lands wherever `HOLD-BACK` puts it — the stream plays, just not at the latency it was published for.\n */\nexport const LOW_LATENCY_UNSUPPORTED_MESSAGE =\n  'Low-Latency HLS is unsupported; playing as standard live at higher latency.';\n\n/**\n * `#EXT-X-PLAYLIST-TYPE:EVENT` — a growing window, which is how DVR is delivered. It plays, but the seekable-range and\n * live-edge handling for it is newer and less exercised than sliding-window live.\n */\nexport const DVR_EXPERIMENTAL_MESSAGE = 'DVR support for EVENT playlists is experimental.';\n"],"mappings":";;;;;;;;;;;;;;;;;;AAkBA,MAAa,uCACX;;;;;;;;;AAUF,MAAa,4BACX;;;;;AAMF,MAAa,kCACX;;;;;AAMF,MAAa,2BAA2B"}

package/dist/dev/playback/primitives/failover-fetch.js

@@ -0,0 +1,37 @@
+import { update } from "../../core/signals/primitives.js";
+import { findTrackById } from "../../media/utils/tracks.js";
+import { addFailedCdn, getCdnId } from "../../media/utils/cdn.js";
+//#region src/playback/primitives/failover-fetch.ts
+/**
+* Decorate a fetch so a failed request trips the **selected track's** CDN into `failedCdns`. The decorated fetch's type
+* is preserved, so this wraps both `resolve-track`'s playlist `FetchText` and the segment loaders' `FetchBytes`.
+*
+* The CDN id comes from the selected track's media-playlist URL, never the failed addressable: a segment URL resolves
+* relative to its playlist and, per RFC 3986, drops the playlist's query string (`…/r.m3u8?cdn=fastly` → `…/0.ts`), so
+* a query-keyed `getCdnId` (e.g. Mux's `cdn=`) keyed on it would derive an id that never matches the ones
+* `deriveCdnPriority` / track-switching build from `track.url`. The in-flight fetch belongs to the selected track — a
+* source or track switch aborts it, and aborts don't trip — so the selected track is the right CDN to fail over. For
+* `resolve-track` the resolving track _is_ the selected track, so this is identical to keying on its addressable.
+*
+* No-op when no failover monitor is composed (it owns the signal) or the selected track can't be located.
+*/
+function failoverFetch(baseFetch, state, config) {
+	const getCdnId$1 = config.getCdnId ?? getCdnId;
+	return (async (addressable, options) => {
+		try {
+			return await baseFetch(addressable, options);
+		} catch (error) {
+			if (!options?.signal?.aborted && state.failedCdns) {
+				const presentation = state.presentation.get();
+				const trackId = state[config.selectedKey].get();
+				const track = presentation && trackId ? findTrackById(presentation, trackId) : void 0;
+				if (track) update(state.failedCdns, (cdns) => addFailedCdn(cdns, getCdnId$1(track.url)));
+			}
+			throw error;
+		}
+	});
+}
+//#endregion
+export { failoverFetch };
+
+//# sourceMappingURL=failover-fetch.js.map

package/dist/dev/playback/primitives/failover-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failover-fetch.js","names":["getCdnId","defaultGetCdnId"],"sources":["../../../../src/playback/primitives/failover-fetch.ts"],"sourcesContent":["import { type ReadonlySignal, type Signal, update } from '../../core/signals/primitives';\nimport type { MaybeResolvedPresentation } from '../../media/types';\nimport { addFailedCdn, getCdnId as defaultGetCdnId, type GetCdnId } from '../../media/utils/cdn';\nimport { findTrackById } from '../../media/utils/tracks';\nimport type { FetchOptions, Resource } from '../../network/fetch';\n\ntype SelectedTrackKey = 'selectedVideoTrackId' | 'selectedAudioTrackId' | 'selectedTextTrackId';\n\n/**\n * State a failover-decorated fetch reads: the presentation, the per-type selected-track slot, and the failover\n * monitor's `failedCdns`.\n *\n * `failedCdns` is _optional_ — the failover monitor owns that slot, so a behavior's narrow state is assignable here\n * without the behavior declaring it (and the intersection shares keys, so it isn't a weak type). When no monitor is\n * composed the slot is absent and tracking no-ops.\n */\ntype FailoverState<K extends SelectedTrackKey> = {\n  presentation: ReadonlySignal<MaybeResolvedPresentation | undefined>;\n  failedCdns?: Signal<string[] | undefined>;\n} & { [P in K]: ReadonlySignal<string | undefined> };\n\n/** Any `Resource`-addressable fetch — both `FetchText` and `FetchBytes` qualify. */\ntype FailoverableFetch = (addressable: Resource, options?: FetchOptions) => Promise<unknown>;\n\n/**\n * Decorate a fetch so a failed request trips the **selected track's** CDN into `failedCdns`. The decorated fetch's type\n * is preserved, so this wraps both `resolve-track`'s playlist `FetchText` and the segment loaders' `FetchBytes`.\n *\n * The CDN id comes from the selected track's media-playlist URL, never the failed addressable: a segment URL resolves\n * relative to its playlist and, per RFC 3986, drops the playlist's query string (`…/r.m3u8?cdn=fastly` → `…/0.ts`), so\n * a query-keyed `getCdnId` (e.g. Mux's `cdn=`) keyed on it would derive an id that never matches the ones\n * `deriveCdnPriority` / track-switching build from `track.url`. The in-flight fetch belongs to the selected track — a\n * source or track switch aborts it, and aborts don't trip — so the selected track is the right CDN to fail over. For\n * `resolve-track` the resolving track _is_ the selected track, so this is identical to keying on its addressable.\n *\n * No-op when no failover monitor is composed (it owns the signal) or the selected track can't be located.\n */\nexport function failoverFetch<K extends SelectedTrackKey, Fetch extends FailoverableFetch>(\n  baseFetch: Fetch,\n  state: FailoverState<K>,\n  config: { selectedKey: K; getCdnId?: GetCdnId }\n): Fetch {\n  const getCdnId = config.getCdnId ?? defaultGetCdnId;\n\n  return (async (addressable: Resource, options?: FetchOptions) => {\n    try {\n      return await baseFetch(addressable, options);\n    } catch (error) {\n      if (!options?.signal?.aborted && state.failedCdns) {\n        const presentation = state.presentation.get();\n        const trackId = state[config.selectedKey].get();\n        const track = presentation && trackId ? findTrackById(presentation, trackId) : undefined;\n\n        if (track) update(state.failedCdns, (cdns) => addFailedCdn(cdns, getCdnId(track.url)));\n      }\n\n      throw error;\n    }\n  }) as Fetch;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAqCA,SAAgB,cACd,WACA,OACA,QACO;CACP,MAAMA,aAAW,OAAO,YAAYC;CAEpC,QAAQ,OAAO,aAAuB,YAA2B;EAC/D,IAAI;GACF,OAAO,MAAM,UAAU,aAAa,OAAO;EAC7C,SAAS,OAAO;GACd,IAAI,CAAC,SAAS,QAAQ,WAAW,MAAM,YAAY;IACjD,MAAM,eAAe,MAAM,aAAa,IAAI;IAC5C,MAAM,UAAU,MAAM,OAAO,YAAY,CAAC,IAAI;IAC9C,MAAM,QAAQ,gBAAgB,UAAU,cAAc,cAAc,OAAO,IAAI,KAAA;IAE/E,IAAI,OAAO,OAAO,MAAM,aAAa,SAAS,aAAa,MAAMD,WAAS,MAAM,GAAG,CAAC,CAAC;GACvF;GAEA,MAAM;EACR;CACF;AACF"}