@videojs/spf 10.0.0-beta.31 → 10.0.0-beta.32

package/dist/dev/playback/primitives/relocation-pipelines.js.map

@@ -1 +1 @@
-{"version":3,"file":"relocation-pipelines.js","names":[],"sources":["../../../../src/playback/primitives/relocation-pipelines.ts"],"sourcesContent":["/**\n * Non-zero-PTS relocation pipelines — the config-supplied, loader-facing half of the\n * `establishStartMediaTime` behavior (`../behaviors/establish-start-media-time`). The\n * reactor there owns the lifecycle and the `derive` coordination seam; this file supplies\n * the `messagePipelines` the segment/text loaders run to *fill and act on* that behavior's\n * state. It's the relocation analog of `track-switching`'s config-supplied constraint/rule\n * chain — a pluggable strategy handed to the machinery via config, not applied inline —\n * supplied to the loaders rather than applied by the behavior, so the two coordinate\n * through the shared `mediaContainerData` / `startMediaTime` slots alone, never by import.\n *\n * DOM-free: it composes the loader vocabularies (`segment-load-pipeline`,\n * `text-segment-load-pipeline`) through their structural sink seams and shifts cues via\n * the structural `Cue` type, so it names no `SourceBuffer`, `TextTracksActor`, or\n * `VTTCue`. The A/V pipeline is a plain `messagePipelines` array:\n *   - `discover` — init `track_id` + `mdhd` timescale for the buffered media track, then\n *     that same track's `tfdt` baseMediaDecodeTime, matched by `track_id` so a muxed\n *     segment reads the media track's origin, not the first `traf` — writes\n *     `state.mediaContainerData`.\n *   - `stamp` — reads that track's derived origin back and relocates via\n *     `timestampOffset = −startMediaTime`.\n * Steps read composition `state` from their call-time `deps` (no closures, no context).\n *\n * The text half (`relocatingTextPipelines`) is the same idea for the text-segment loader:\n * a `resolveWithMetadata → relocateCues → dispatchCues` pipeline that shifts cues onto the\n * same 0-based timeline, reading the primary A/V track's `startMediaTime` (the reactor's\n * consumed value) via `deps`.\n */\nimport type { StateSignals } from '../../core/composition/create-composition';\nimport { effect } from '../../core/signals/effect';\nimport { peek, type Signal, update } from '../../core/signals/primitives';\nimport { findMediaTrack, type MediaHandlerType, readBaseMediaDecodeTime } from '../../media/mp4/timestamp-origin';\nimport { resolveVttSegmentMetadata, type TextSegmentMetadata } from '../../media/text/resolve-vtt-metadata';\nimport type { Cue, MaybeResolvedPresentation, MediaContainerData } from '../../media/types';\nimport { findTrackById, getTracksByType } from '../../media/utils/tracks';\nimport type { DeriveStartMediaTime } from './derive-start-media-time';\nimport { peekHead } from './head-peek';\nimport { dispatchStep, fetchStep, type LoadStep, type MessagePipelines, type StepDeps } from './segment-load-pipeline';\nimport {\n  dispatchCuesStep,\n  type TextFrame,\n  type TextLoadStep,\n  type TextStepDeps,\n  textStepWiring,\n} from './text-segment-load-pipeline';\n\n/** The composition slots these steps read — the view asserted from the opaque `deps.state`. */\ninterface RelocationSlots {\n  presentation?: MaybeResolvedPresentation;\n  mediaContainerData?: Record<string, MediaContainerData>;\n  selectedVideoTrackId?: string;\n  selectedAudioTrackId?: string;\n}\n\ntype ContainerSlot = Signal<Record<string, MediaContainerData> | undefined>;\n\n/** Assert the relocation state view from the opaque step deps — this module knows the slots the composition provides. */\nfunction relocationState(deps: StepDeps): StateSignals<RelocationSlots> {\n  return deps.state as unknown as StateSignals<RelocationSlots>;\n}\n\nfunction containerSlot(deps: StepDeps): ContainerSlot {\n  return relocationState(deps).mediaContainerData;\n}\n\n/** Synchronous RMW of the per-type entry — disjoint keys across producers, so no lost update. */\nfunction writeContainer(slot: ContainerSlot, trackType: string, patch: Partial<MediaContainerData>): void {\n  update(slot, (current) => ({ ...current, [trackType]: { ...current?.[trackType], ...patch } }));\n}\n\n/**\n * Resolve once `read()` returns a number. Shared by the A/V stamp (waits for the\n * `derive`d origin — immediate for per-type, the shared-`min` barrier for coordinated)\n * and the text step (waits for the primary A/V origin). No bound: for fMP4 the origin\n * always establishes.\n */\nfunction awaitDefined(read: () => number | undefined): Promise<number> {\n  return new Promise((resolve) => {\n    let stop: (() => void) | undefined;\n    stop = effect(() => {\n      const value = read();\n      if (value !== undefined) {\n        stop?.();\n        resolve(value);\n      }\n    });\n  });\n}\n\n/**\n * Relocation pipelines for one track type — a plain config `messagePipelines`.\n * Keyed by **track type** (`'video'` / `'audio'`), so ABR rungs of a type share the\n * origin (discover skips once the type's value is present). The steps read/write\n * `state.mediaContainerData[trackType]` via their call-time `deps`; the stamp applies\n * the same `derive` seam the reactor uses (pass the composition's resolved\n * `deriveStartMediaTime` so the buffer offset and the model's `startMediaTime` agree).\n */\nexport function relocationPipelinesFor(trackType: 'video' | 'audio', derive: DeriveStartMediaTime): MessagePipelines {\n  const handlerType: MediaHandlerType = trackType === 'video' ? 'vide' : 'soun';\n\n  /**\n   * Init step: head-peek the buffered media track's `track_id` + `mdhd` timescale into\n   * `mediaContainerData[trackType]`. Matching by handler (`vide`/`soun`) skips a muxed\n   * `clcp` caption track, and the `track_id` lets `readSegmentOrigin` read *this*\n   * track's `tfdt` rather than the first `traf` in the segment.\n   */\n  const readInitTrackInfo: LoadStep = async (frame, _signal, deps) => {\n    const { op } = frame;\n    if (op.type !== 'append-init' || !frame.data) return;\n    const slot = containerSlot(deps);\n    if (peek(slot)?.[trackType]?.timescale !== undefined) return; // already have it (any rung of this type)\n    frame.data = await peekHead(frame.data, (bytes) => {\n      const track = findMediaTrack(bytes, handlerType);\n      if (track === undefined) return false;\n      writeContainer(slot, trackType, { trackId: track.trackId, timescale: track.timescale });\n      return true;\n    });\n  };\n\n  /**\n   * Media-segment step: head-peek the `tfdt` baseMediaDecodeTime of the media track's\n   * `traf` (matched by the `track_id` discovered from the init), recording the\n   * segment's 0-based `startTime` with it — the origin is `bmdt/ts − segmentStartTime`,\n   * so the first *loaded* segment need not be the 0th. Without a discovered `track_id`\n   * (non-fMP4 / mock init) there's no media track to relocate, so the step no-ops and\n   * the append stays native.\n   */\n  const readSegmentOrigin: LoadStep = async (frame, _signal, deps) => {\n    const { op } = frame;\n    if (op.type !== 'append-segment' || !frame.data) return;\n    const slot = containerSlot(deps);\n    const container = peek(slot)?.[trackType];\n    if (container?.baseMediaDecodeTime !== undefined) return; // established\n    const { trackId } = container ?? {};\n    if (trackId === undefined) return; // init didn't identify a media track — nothing to match\n    const segmentStartTime = op.meta.startTime;\n    frame.data = await peekHead(frame.data, (bytes) => {\n      const baseMediaDecodeTime = readBaseMediaDecodeTime(bytes, trackId);\n      if (baseMediaDecodeTime === undefined) return false;\n      writeContainer(slot, trackType, { baseMediaDecodeTime, segmentStartTime });\n      return true;\n    });\n  };\n\n  /**\n   * Stamp step — tier-agnostic apply. Relocate by the `derive`d `startMediaTime` for\n   * this type (`offset = −startMediaTime`). Applies the **same** `derive` the reactor\n   * uses, over the shared `mediaContainerData` slot — so the buffer offset matches the\n   * model's stamped `startMediaTime`, and it's robust to `established` + late tracks\n   * (the slot persists; the model value may not be re-stamped after the reactor goes\n   * sticky). Awaited: per-type resolves at once (own origin discovered earlier in this\n   * pipeline); shared-`min` waits until every selected A/V origin is in — the barrier,\n   * filled by the other type's discover step. A derived `0` (0-PTS / below threshold)\n   * leaves the append native — setting `timestampOffset` at all can ripple.\n   */\n  const stampStartMediaTime: LoadStep = async (frame, signal, deps) => {\n    if (frame.op.type !== 'append-segment') return;\n    const state = relocationState(deps);\n    // Liveness guard: if THIS type's own origin wasn't discovered — `readSegmentOrigin`\n    // ran earlier in this pipeline and found no `tfdt` (mock / TS / containerless) — the\n    // source isn't relocatable, so leave the append native and DON'T wait. Only a\n    // discoverable type awaits the derived origin (which for shared-`min` legitimately\n    // blocks on the other selected type — the barrier).\n    const own = peek(state.mediaContainerData)?.[trackType];\n    if (own?.timescale === undefined || own.baseMediaDecodeTime === undefined || own.segmentStartTime === undefined) {\n      return;\n    }\n    const startMediaTime = await awaitDefined(() => {\n      const containerData = state.mediaContainerData.get();\n      if (!containerData) return undefined;\n      return derive(containerData, {\n        selectedVideoTrackId: state.selectedVideoTrackId?.get(),\n        selectedAudioTrackId: state.selectedAudioTrackId?.get(),\n      })[trackType];\n    });\n    if (signal.aborted || startMediaTime === 0) return;\n    frame.meta = { ...(frame.meta ?? frame.op.meta), timestampOffset: -startMediaTime };\n  };\n\n  return () => ({\n    remove: [dispatchStep],\n    'append-init': [fetchStep, readInitTrackInfo, dispatchStep],\n    'append-segment': [fetchStep, readSegmentOrigin, stampStartMediaTime, dispatchStep],\n  });\n}\n\n// ============================================================================\n// TEXT (cue relocation)\n// ============================================================================\n\n/**\n * Resolve step for the relocation text pipeline. Reuses the injected host resolver\n * (the loader's folded `resolveSegment`, via `textStepWiring`) for cues and fetches\n * the `X-TIMESTAMP-MAP` header in parallel, stashing it on `frame.metadata` for\n * `relocateCuesStep`. Replaces the\n * base `resolveCuesStep` (which fetches cues only) — text's native `<track>` parser\n * discards the header, so the map needs its own raw-bytes fetch.\n */\nconst resolveWithMetadataStep = async <C extends Cue>(\n  frame: TextFrame<C>,\n  signal: AbortSignal,\n  deps: TextStepDeps\n): Promise<void> => {\n  const [cues, metadata] = await Promise.all([\n    textStepWiring<C>(deps).resolveSegment(frame.op.segment.url),\n    resolveVttSegmentMetadata(frame.op.segment.url),\n  ]);\n  if (signal.aborted) return;\n  frame.cues = cues;\n  frame.metadata = metadata;\n};\n\n/**\n * Relocate step — shifts each cue onto the 0-based presentation timeline:\n * `cueFinal = cueNative − startMediaTime`, where `startMediaTime` is the primary\n * A/V track's origin (selected **video**, else **audio** — the single-anchor rule,\n * and defensive like the reactor's optional selection) and `cueNative` folds in the\n * `X-TIMESTAMP-MAP` correction (`mpegts/90000 − local`) for map-bearing VTT (Apple)\n * or is the absolute cue time (no map, e.g. Mux). Text can resolve before A/V\n * establishes, so the origin is awaited; fMP4 always establishes it (0-PTS → 0),\n * and a text-only source (no A/V selected) simply gets offset 0.\n */\nconst relocateCuesStep = async <C extends Cue>(\n  frame: TextFrame<C>,\n  signal: AbortSignal,\n  deps: TextStepDeps\n): Promise<void> => {\n  if (!frame.cues?.length) return;\n  const state = deps.state as unknown as StateSignals<RelocationSlots>;\n  const startMediaTime = await awaitDefined(() => {\n    const presentation = state.presentation.get();\n    if (!presentation) return undefined;\n    const primaryId = state.selectedVideoTrackId.get() ?? state.selectedAudioTrackId.get();\n    if (primaryId !== undefined) {\n      // A/V selected: use its origin once stamped (undefined until then → keep waiting).\n      return findTrackById(presentation, primaryId)?.startMediaTime;\n    }\n    // No A/V selected. Distinguish \"not selected YET\" from \"text-only source\". If the\n    // presentation has A/V tracks, one WILL be selected and stamped — wait for it, or the\n    // cues get shifted by the full `mapCorrection` (e.g. +10s on Apple X-TIMESTAMP-MAP\n    // sources) when text relocation wins the race against A/V selection. Only a genuinely\n    // text-only source (no A/V origin ever coming) legitimately relocates by offset 0.\n    const hasAv =\n      getTracksByType(presentation, 'video').length > 0 || getTracksByType(presentation, 'audio').length > 0;\n    return hasAv ? undefined : 0;\n  });\n  if (signal.aborted) return;\n  const { timestampMap } = (frame.metadata as TextSegmentMetadata | undefined) ?? {};\n  const mapCorrection = timestampMap ? timestampMap.mpegts / 90000 - timestampMap.local : 0;\n  const delta = mapCorrection - startMediaTime;\n  if (delta !== 0) {\n    for (const cue of frame.cues) {\n      cue.startTime += delta;\n      cue.endTime += delta;\n    }\n  }\n};\n\n/**\n * Relocation text pipeline — the text analog of `relocationPipelinesFor(type)`.\n * `resolveWithMetadata` (cues + `X-TIMESTAMP-MAP`) → `relocateCues` (shift by the\n * primary A/V origin) → `dispatchCues`.\n */\nexport const relocatingTextPipelines = <C extends Cue>(): TextLoadStep<C>[] => [\n  resolveWithMetadataStep,\n  relocateCuesStep,\n  dispatchCuesStep,\n];\n"],"mappings":"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"}
+{"version":3,"file":"relocation-pipelines.js","names":[],"sources":["../../../../src/playback/primitives/relocation-pipelines.ts"],"sourcesContent":["/**\n * Non-zero-PTS relocation pipelines — the config-supplied, loader-facing half of the `establishStartMediaTime` behavior\n * (`../behaviors/establish-start-media-time`). The reactor there owns the lifecycle and the `derive` coordination seam;\n * this file supplies the `messagePipelines` the segment/text loaders run to _fill and act on_ that behavior's state.\n * It's the relocation analog of `track-switching`'s config-supplied constraint/rule chain — a pluggable strategy handed\n * to the machinery via config, not applied inline — supplied to the loaders rather than applied by the behavior, so the\n * two coordinate through the shared `mediaContainerData` / `startMediaTime` slots alone, never by import.\n *\n * DOM-free: it composes the loader vocabularies (`segment-load-pipeline`, `text-segment-load-pipeline`) through their\n * structural sink seams and shifts cues via the structural `Cue` type, so it names no `SourceBuffer`,\n * `TextTracksActor`, or `VTTCue`. The A/V pipeline is a plain `messagePipelines` array:\n *\n * - `discover` — init `track_id` + `mdhd` timescale for the buffered media track, then that same track's `tfdt`\n *   baseMediaDecodeTime, matched by `track_id` so a muxed segment reads the media track's origin, not the first `traf`\n *   — writes `state.mediaContainerData`.\n * - `stamp` — reads that track's derived origin back and relocates via `timestampOffset = −startMediaTime`. Steps read\n *   composition `state` from their call-time `deps` (no closures, no context).\n *\n * The text half (`relocatingTextPipelines`) is the same idea for the text-segment loader: a `resolveWithMetadata →\n * relocateCues → dispatchCues` pipeline that shifts cues onto the same 0-based timeline, reading the primary A/V\n * track's `startMediaTime` (the reactor's consumed value) via `deps`.\n */\nimport type { StateSignals } from '../../core/composition/create-composition';\nimport { effect } from '../../core/signals/effect';\nimport { peek, type Signal, update } from '../../core/signals/primitives';\nimport { findMediaTrack, type MediaHandlerType, readBaseMediaDecodeTime } from '../../media/mp4/timestamp-origin';\nimport { resolveVttSegmentMetadata, type TextSegmentMetadata } from '../../media/text/resolve-vtt-metadata';\nimport type { Cue, MaybeResolvedPresentation, MediaContainerData } from '../../media/types';\nimport { findTrackById, getTracksByType } from '../../media/utils/tracks';\nimport type { DeriveStartMediaTime } from './derive-start-media-time';\nimport { peekHead } from './head-peek';\nimport { dispatchStep, fetchStep, type LoadStep, type MessagePipelines, type StepDeps } from './segment-load-pipeline';\nimport {\n  dispatchCuesStep,\n  type TextFrame,\n  type TextLoadStep,\n  type TextStepDeps,\n  textStepWiring,\n} from './text-segment-load-pipeline';\n\n/** The composition slots these steps read — the view asserted from the opaque `deps.state`. */\ninterface RelocationSlots {\n  presentation?: MaybeResolvedPresentation;\n  mediaContainerData?: Record<string, MediaContainerData>;\n  selectedVideoTrackId?: string;\n  selectedAudioTrackId?: string;\n}\n\ntype ContainerSlot = Signal<Record<string, MediaContainerData> | undefined>;\n\n/** Assert the relocation state view from the opaque step deps — this module knows the slots the composition provides. */\nfunction relocationState(deps: StepDeps): StateSignals<RelocationSlots> {\n  return deps.state as unknown as StateSignals<RelocationSlots>;\n}\n\nfunction containerSlot(deps: StepDeps): ContainerSlot {\n  return relocationState(deps).mediaContainerData;\n}\n\n/** Synchronous RMW of the per-type entry — disjoint keys across producers, so no lost update. */\nfunction writeContainer(slot: ContainerSlot, trackType: string, patch: Partial<MediaContainerData>): void {\n  update(slot, (current) => ({ ...current, [trackType]: { ...current?.[trackType], ...patch } }));\n}\n\n/**\n * Resolve once `read()` returns a number. Shared by the A/V stamp (waits for the `derive`d origin — immediate for\n * per-type, the shared-`min` barrier for coordinated) and the text step (waits for the primary A/V origin). No bound:\n * for fMP4 the origin always establishes.\n */\nfunction awaitDefined(read: () => number | undefined): Promise<number> {\n  return new Promise((resolve) => {\n    let stop: (() => void) | undefined;\n\n    stop = effect(() => {\n      const value = read();\n\n      if (value !== undefined) {\n        stop?.();\n        resolve(value);\n      }\n    });\n  });\n}\n\n/**\n * Relocation pipelines for one track type — a plain config `messagePipelines`. Keyed by **track type** (`'video'` /\n * `'audio'`), so ABR rungs of a type share the origin (discover skips once the type's value is present). The steps\n * read/write `state.mediaContainerData[trackType]` via their call-time `deps`; the stamp applies the same `derive` seam\n * the reactor uses (pass the composition's resolved `deriveStartMediaTime` so the buffer offset and the model's\n * `startMediaTime` agree).\n */\nexport function relocationPipelinesFor(trackType: 'video' | 'audio', derive: DeriveStartMediaTime): MessagePipelines {\n  const handlerType: MediaHandlerType = trackType === 'video' ? 'vide' : 'soun';\n\n  /**\n   * Init step: head-peek the buffered media track's `track_id` + `mdhd` timescale into `mediaContainerData[trackType]`.\n   * Matching by handler (`vide`/`soun`) skips a muxed `clcp` caption track, and the `track_id` lets `readSegmentOrigin`\n   * read _this_ track's `tfdt` rather than the first `traf` in the segment.\n   */\n  const readInitTrackInfo: LoadStep = async (frame, _signal, deps) => {\n    const { op } = frame;\n    if (op.type !== 'append-init' || !frame.data) return;\n\n    const slot = containerSlot(deps);\n    if (peek(slot)?.[trackType]?.timescale !== undefined) return; // already have it (any rung of this type)\n\n    frame.data = await peekHead(frame.data, (bytes) => {\n      const track = findMediaTrack(bytes, handlerType);\n      if (track === undefined) return false;\n\n      writeContainer(slot, trackType, { trackId: track.trackId, timescale: track.timescale });\n      return true;\n    });\n  };\n\n  /**\n   * Media-segment step: head-peek the `tfdt` baseMediaDecodeTime of the media track's `traf` (matched by the `track_id`\n   * discovered from the init), recording the segment's 0-based `startTime` with it — the origin is `bmdt/ts −\n   * segmentStartTime`, so the first _loaded_ segment need not be the 0th. Without a discovered `track_id` (non-fMP4 /\n   * mock init) there's no media track to relocate, so the step no-ops and the append stays native.\n   */\n  const readSegmentOrigin: LoadStep = async (frame, _signal, deps) => {\n    const { op } = frame;\n    if (op.type !== 'append-segment' || !frame.data) return;\n\n    const slot = containerSlot(deps);\n    const container = peek(slot)?.[trackType];\n    if (container?.baseMediaDecodeTime !== undefined) return; // established\n\n    const { trackId } = container ?? {};\n    if (trackId === undefined) return; // init didn't identify a media track — nothing to match\n\n    const segmentStartTime = op.meta.startTime;\n\n    frame.data = await peekHead(frame.data, (bytes) => {\n      const baseMediaDecodeTime = readBaseMediaDecodeTime(bytes, trackId);\n      if (baseMediaDecodeTime === undefined) return false;\n\n      writeContainer(slot, trackType, { baseMediaDecodeTime, segmentStartTime });\n      return true;\n    });\n  };\n\n  /**\n   * Stamp step — tier-agnostic apply. Relocate by the `derive`d `startMediaTime` for this type (`offset =\n   * −startMediaTime`). Applies the **same** `derive` the reactor uses, over the shared `mediaContainerData` slot — so\n   * the buffer offset matches the model's stamped `startMediaTime`, and it's robust to `established` + late tracks (the\n   * slot persists; the model value may not be re-stamped after the reactor goes sticky). Awaited: per-type resolves at\n   * once (own origin discovered earlier in this pipeline); shared-`min` waits until every selected A/V origin is in —\n   * the barrier, filled by the other type's discover step. A derived `0` (0-PTS / below threshold) leaves the append\n   * native — setting `timestampOffset` at all can ripple.\n   */\n  const stampStartMediaTime: LoadStep = async (frame, signal, deps) => {\n    if (frame.op.type !== 'append-segment') return;\n\n    const state = relocationState(deps);\n    // Liveness guard: if THIS type's own origin wasn't discovered — `readSegmentOrigin`\n    // ran earlier in this pipeline and found no `tfdt` (mock / TS / containerless) — the\n    // source isn't relocatable, so leave the append native and DON'T wait. Only a\n    // discoverable type awaits the derived origin (which for shared-`min` legitimately\n    // blocks on the other selected type — the barrier).\n    const own = peek(state.mediaContainerData)?.[trackType];\n\n    if (own?.timescale === undefined || own.baseMediaDecodeTime === undefined || own.segmentStartTime === undefined) {\n      return;\n    }\n\n    const startMediaTime = await awaitDefined(() => {\n      const containerData = state.mediaContainerData.get();\n      if (!containerData) return undefined;\n\n      return derive(containerData, {\n        selectedVideoTrackId: state.selectedVideoTrackId?.get(),\n        selectedAudioTrackId: state.selectedAudioTrackId?.get(),\n      })[trackType];\n    });\n    if (signal.aborted || startMediaTime === 0) return;\n\n    frame.meta = { ...(frame.meta ?? frame.op.meta), timestampOffset: -startMediaTime };\n  };\n\n  return () => ({\n    remove: [dispatchStep],\n    'append-init': [fetchStep, readInitTrackInfo, dispatchStep],\n    'append-segment': [fetchStep, readSegmentOrigin, stampStartMediaTime, dispatchStep],\n  });\n}\n\n// ============================================================================\n// TEXT (cue relocation)\n// ============================================================================\n\n/**\n * Resolve step for the relocation text pipeline. Reuses the injected host resolver (the loader's folded\n * `resolveSegment`, via `textStepWiring`) for cues and fetches the `X-TIMESTAMP-MAP` header in parallel, stashing it on\n * `frame.metadata` for `relocateCuesStep`. Replaces the base `resolveCuesStep` (which fetches cues only) — text's\n * native `<track>` parser discards the header, so the map needs its own raw-bytes fetch.\n */\nconst resolveWithMetadataStep = async <C extends Cue>(\n  frame: TextFrame<C>,\n  signal: AbortSignal,\n  deps: TextStepDeps\n): Promise<void> => {\n  const [cues, metadata] = await Promise.all([\n    textStepWiring<C>(deps).resolveSegment(frame.op.segment.url),\n    resolveVttSegmentMetadata(frame.op.segment.url),\n  ]);\n\n  if (signal.aborted) return;\n\n  frame.cues = cues;\n  frame.metadata = metadata;\n};\n\n/**\n * Relocate step — shifts each cue onto the 0-based presentation timeline: `cueFinal = cueNative − startMediaTime`,\n * where `startMediaTime` is the primary A/V track's origin (selected **video**, else **audio** — the single-anchor\n * rule, and defensive like the reactor's optional selection) and `cueNative` folds in the `X-TIMESTAMP-MAP` correction\n * (`mpegts/90000 − local`) for map-bearing VTT (Apple) or is the absolute cue time (no map, e.g. Mux). Text can resolve\n * before A/V establishes, so the origin is awaited; fMP4 always establishes it (0-PTS → 0), and a text-only source (no\n * A/V selected) simply gets offset 0.\n */\nconst relocateCuesStep = async <C extends Cue>(\n  frame: TextFrame<C>,\n  signal: AbortSignal,\n  deps: TextStepDeps\n): Promise<void> => {\n  if (!frame.cues?.length) return;\n\n  const state = deps.state as unknown as StateSignals<RelocationSlots>;\n  const startMediaTime = await awaitDefined(() => {\n    const presentation = state.presentation.get();\n    if (!presentation) return undefined;\n\n    const primaryId = state.selectedVideoTrackId.get() ?? state.selectedAudioTrackId.get();\n\n    if (primaryId !== undefined) {\n      // A/V selected: use its origin once stamped (undefined until then → keep waiting).\n      return findTrackById(presentation, primaryId)?.startMediaTime;\n    }\n\n    // No A/V selected. Distinguish \"not selected YET\" from \"text-only source\". If the\n    // presentation has A/V tracks, one WILL be selected and stamped — wait for it, or the\n    // cues get shifted by the full `mapCorrection` (e.g. +10s on Apple X-TIMESTAMP-MAP\n    // sources) when text relocation wins the race against A/V selection. Only a genuinely\n    // text-only source (no A/V origin ever coming) legitimately relocates by offset 0.\n    const hasAv =\n      getTracksByType(presentation, 'video').length > 0 || getTracksByType(presentation, 'audio').length > 0;\n\n    return hasAv ? undefined : 0;\n  });\n\n  if (signal.aborted) return;\n\n  const { timestampMap } = (frame.metadata as TextSegmentMetadata | undefined) ?? {};\n  const mapCorrection = timestampMap ? timestampMap.mpegts / 90000 - timestampMap.local : 0;\n  const delta = mapCorrection - startMediaTime;\n\n  if (delta !== 0) {\n    for (const cue of frame.cues) {\n      cue.startTime += delta;\n      cue.endTime += delta;\n    }\n  }\n};\n\n/**\n * Relocation text pipeline — the text analog of `relocationPipelinesFor(type)`. `resolveWithMetadata` (cues +\n * `X-TIMESTAMP-MAP`) → `relocateCues` (shift by the primary A/V origin) → `dispatchCues`.\n */\nexport const relocatingTextPipelines = <C extends Cue>(): TextLoadStep<C>[] => [\n  resolveWithMetadataStep,\n  relocateCuesStep,\n  dispatchCuesStep,\n];\n"],"mappings":"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"}

package/dist/dev/playback/primitives/report-track-conditions.d.ts

@@ -1,10 +1,7 @@
 import { ResolvedTrack } from "../../media/types/index.js";
 import { SvtaError } from "../../media/errors.js";
 //#region src/playback/primitives/report-track-conditions.d.ts
-/**
- * Conditions worth reporting about a just-resolved track. Return an empty array
- * (or omit the seam) to report nothing.
- */
+/** Conditions worth reporting about a just-resolved track. Return an empty array (or omit the seam) to report nothing. */
 type ReportUnsupportedTrackConditions = (track: ResolvedTrack) => readonly SvtaError[];
 //#endregion
 export { ReportUnsupportedTrackConditions };

package/dist/dev/playback/primitives/report-track-conditions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"report-track-conditions.d.ts","names":[],"sources":["../../../../src/playback/primitives/report-track-conditions.ts"],"mappings":";;;;;;;KAgCY,oCAAoC,OAAO,2BAA2B"}
+{"version":3,"file":"report-track-conditions.d.ts","names":[],"sources":["../../../../src/playback/primitives/report-track-conditions.ts"],"mappings":";;;;KAwBY,oCAAoC,OAAO,2BAA2B"}

package/dist/dev/playback/primitives/report-track-conditions.js

@@ -3,23 +3,18 @@ import { SVTA_UNSUPPORTED_AUDIO_FORMAT, SVTA_UNSUPPORTED_DRM_SYSTEM, SVTA_UNSUPP
 import { NON_FMP4_CONTAINER_MIMES } from "../../media/hls/parse-media-playlist.js";
 //#region src/playback/primitives/report-track-conditions.ts
 /**
-* The seam `resolve-track` uses to report conditions discovered in a freshly
-* parsed media playlist.
+* The seam `resolve-track` uses to report conditions discovered in a freshly parsed media playlist.
 *
-* Injected rather than baked in so `resolve-track` stays free of format and
-* policy knowledge: it parses and commits, and whatever the composition wants
-* noticed about the result is this function's business. Which conditions matter,
-* and which codes they carry, therefore vary per composition — a provider that
-* never ships MPEG-TS can drop that check, and future playlist-derived notices
-* (LL-HLS or DVR support that's partial rather than absent) attach here without
+* Injected rather than baked in so `resolve-track` stays free of format and policy knowledge: it parses and commits,
+* and whatever the composition wants noticed about the result is this function's business. Which conditions matter, and
+* which codes they carry, therefore vary per composition — a provider that never ships MPEG-TS can drop that check, and
+* future playlist-derived notices (LL-HLS or DVR support that's partial rather than absent) attach here without
 * touching the resolver.
 *
-* Reported **per rendition, as it resolves**, which is why these are causes and
-* not verdicts: one rendition being unplayable doesn't make the source
-* unplayable. The verdict is `track-switching`'s, which reports
-* `SVTA_NO_SUPPORTED_{VIDEO,AUDIO}_TRACK` when a type's candidates actually
-* empty. Keeping the two apart is what lets a mixed source — some renditions
-* encrypted or MPEG-TS, others playable — log its causes and still play.
+* Reported **per rendition, as it resolves**, which is why these are causes and not verdicts: one rendition being
+* unplayable doesn't make the source unplayable. The verdict is `track-switching`'s, which reports
+* `SVTA_NO_SUPPORTED_{VIDEO,AUDIO}_TRACK` when a type's candidates actually empty. Keeping the two apart is what lets a
+* mixed source — some renditions encrypted or MPEG-TS, others playable — log its causes and still play.
 */
 /** Unsupported-format code per type; text has none — absent captions aren't a failure. */
 const UNSUPPORTED_FORMAT_CODE = {
@@ -27,37 +22,30 @@ const UNSUPPORTED_FORMAT_CODE = {
 	audio: SVTA_UNSUPPORTED_AUDIO_FORMAT
 };
 /**
-* The types a reported cause can legitimately describe: the ones whose candidates
-* `canPlayTrack` actually prunes, via `track-switching`'s `excludeUnplayableTracks`
-* pre-pass.
+* The types a reported cause can legitimately describe: the ones whose candidates `canPlayTrack` actually prunes, via
+* `track-switching`'s `excludeUnplayableTracks` pre-pass.
 *
-* Text is outside it by design — its switching chain runs failed-CDN constraints
-* alone, because an MSE codec probe is the wrong question for a WebVTT rendition
-* (see `track-switching.ts`). So nothing prunes a text rendition, no verdict can
-* follow from one, and a cause reported against it would be an orphan: the
-* adapter's unsupported-feature substitution scans the sequence as a whole, so a
-* lone encrypted subtitle would otherwise recode an unrelated verdict — an
-* all-CDN cooldown among them — as "this engine can't play the source".
+* Text is outside it by design — its switching chain runs failed-CDN constraints alone, because an MSE codec probe is
+* the wrong question for a WebVTT rendition (see `track-switching.ts`). So nothing prunes a text rendition, no verdict
+* can follow from one, and a cause reported against it would be an orphan: the adapter's unsupported-feature
+* substitution scans the sequence as a whole, so a lone encrypted subtitle would otherwise recode an unrelated verdict
+* — an all-CDN cooldown among them — as "this engine can't play the source".
 */
 const CAPABILITY_PRUNED_TYPES = /* @__PURE__ */ new Set(["video", "audio"]);
 /**
-* The default: report what makes a rendition unplayable *to this engine* — a
-* container MSE can't accept, or encryption with no decryption pipeline. Both
-* mirror what `canPlayTrack` prunes on, so a reported cause always has a
+* The default: report what makes a rendition unplayable _to this engine_ — a container MSE can't accept, or encryption
+* with no decryption pipeline. Both mirror what `canPlayTrack` prunes on, so a reported cause always has a
 * corresponding exclusion.
 *
-* A condition carries its code and its context, not copy. `data.mimeType` is
-* what preserves the specificity — the format codes cover every non-fMP4
-* container, so "which one" lives there for a consumer that wants to say, rather
-* than being flattened into an English sentence here.
+* A condition carries its code and its context, not copy. `data.mimeType` is what preserves the specificity — the
+* format codes cover every non-fMP4 container, so "which one" lives there for a consumer that wants to say, rather than
+* being flattened into an English sentence here.
 *
-* Both carry `trackType`, redundantly for the format codes (1004/1005 are
-* already per type) but not for 4008, which isn't per type — SVTA has one
-* content-protection code for both. Nothing branches on the tag: it's diagnostic
-* context, reaching a developer through the logged sequence and `error.data`,
-* which is why it goes on every condition rather than only where the code can't
-* carry it. `trackId` alongside it is what distinguishes two renditions of the
-* same type.
+* Both carry `trackType`, redundantly for the format codes (1004/1005 are already per type) but not for 4008, which
+* isn't per type — SVTA has one content-protection code for both. Nothing branches on the tag: it's diagnostic context,
+* reaching a developer through the logged sequence and `error.data`, which is why it goes on every condition rather
+* than only where the code can't carry it. `trackId` alongside it is what distinguishes two renditions of the same
+* type.
 */
 function reportUnsupportedTrackConditions(track) {
 	if (!CAPABILITY_PRUNED_TYPES.has(track.type)) return [];

package/dist/dev/playback/primitives/report-track-conditions.js.map

@@ -1 +1 @@
-{"version":3,"file":"report-track-conditions.js","names":[],"sources":["../../../../src/playback/primitives/report-track-conditions.ts"],"sourcesContent":["/**\n * The seam `resolve-track` uses to report conditions discovered in a freshly\n * parsed media playlist.\n *\n * Injected rather than baked in so `resolve-track` stays free of format and\n * policy knowledge: it parses and commits, and whatever the composition wants\n * noticed about the result is this function's business. Which conditions matter,\n * and which codes they carry, therefore vary per composition — a provider that\n * never ships MPEG-TS can drop that check, and future playlist-derived notices\n * (LL-HLS or DVR support that's partial rather than absent) attach here without\n * touching the resolver.\n *\n * Reported **per rendition, as it resolves**, which is why these are causes and\n * not verdicts: one rendition being unplayable doesn't make the source\n * unplayable. The verdict is `track-switching`'s, which reports\n * `SVTA_NO_SUPPORTED_{VIDEO,AUDIO}_TRACK` when a type's candidates actually\n * empty. Keeping the two apart is what lets a mixed source — some renditions\n * encrypted or MPEG-TS, others playable — log its causes and still play.\n */\nimport {\n  SVTA_UNSUPPORTED_AUDIO_FORMAT,\n  SVTA_UNSUPPORTED_DRM_SYSTEM,\n  SVTA_UNSUPPORTED_VIDEO_FORMAT,\n  type SvtaError,\n} from '../../media/errors';\nimport { NON_FMP4_CONTAINER_MIMES } from '../../media/hls/parse-media-playlist';\nimport { getMediaPlaylistMetadata, type ResolvedTrack, type TrackType } from '../../media/types';\n\n/**\n * Conditions worth reporting about a just-resolved track. Return an empty array\n * (or omit the seam) to report nothing.\n */\nexport type ReportUnsupportedTrackConditions = (track: ResolvedTrack) => readonly SvtaError[];\n\n/** Unsupported-format code per type; text has none — absent captions aren't a failure. */\nconst UNSUPPORTED_FORMAT_CODE: Partial<Record<TrackType, number>> = {\n  video: SVTA_UNSUPPORTED_VIDEO_FORMAT,\n  audio: SVTA_UNSUPPORTED_AUDIO_FORMAT,\n};\n\n/**\n * The types a reported cause can legitimately describe: the ones whose candidates\n * `canPlayTrack` actually prunes, via `track-switching`'s `excludeUnplayableTracks`\n * pre-pass.\n *\n * Text is outside it by design — its switching chain runs failed-CDN constraints\n * alone, because an MSE codec probe is the wrong question for a WebVTT rendition\n * (see `track-switching.ts`). So nothing prunes a text rendition, no verdict can\n * follow from one, and a cause reported against it would be an orphan: the\n * adapter's unsupported-feature substitution scans the sequence as a whole, so a\n * lone encrypted subtitle would otherwise recode an unrelated verdict — an\n * all-CDN cooldown among them — as \"this engine can't play the source\".\n */\nconst CAPABILITY_PRUNED_TYPES: ReadonlySet<TrackType> = new Set<TrackType>(['video', 'audio']);\n\n/**\n * The default: report what makes a rendition unplayable *to this engine* — a\n * container MSE can't accept, or encryption with no decryption pipeline. Both\n * mirror what `canPlayTrack` prunes on, so a reported cause always has a\n * corresponding exclusion.\n *\n * A condition carries its code and its context, not copy. `data.mimeType` is\n * what preserves the specificity — the format codes cover every non-fMP4\n * container, so \"which one\" lives there for a consumer that wants to say, rather\n * than being flattened into an English sentence here.\n *\n * Both carry `trackType`, redundantly for the format codes (1004/1005 are\n * already per type) but not for 4008, which isn't per type — SVTA has one\n * content-protection code for both. Nothing branches on the tag: it's diagnostic\n * context, reaching a developer through the logged sequence and `error.data`,\n * which is why it goes on every condition rather than only where the code can't\n * carry it. `trackId` alongside it is what distinguishes two renditions of the\n * same type.\n */\nexport function reportUnsupportedTrackConditions(track: ResolvedTrack): readonly SvtaError[] {\n  if (!CAPABILITY_PRUNED_TYPES.has(track.type)) return [];\n\n  const conditions: SvtaError[] = [];\n  const data = { trackType: track.type, trackId: track.id };\n\n  const formatCode = UNSUPPORTED_FORMAT_CODE[track.type];\n  if (formatCode !== undefined && NON_FMP4_CONTAINER_MIMES.has(track.mimeType)) {\n    conditions.push({ code: formatCode, data: { ...data, mimeType: track.mimeType } });\n  }\n  if (getMediaPlaylistMetadata(track)?.encrypted) {\n    conditions.push({ code: SVTA_UNSUPPORTED_DRM_SYSTEM, data });\n  }\n  return conditions;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAmCA,MAAM,0BAA8D;CAClE,OAAO;CACP,OAAO;AACT;;;;;;;;;;;;;;AAeA,MAAM,0CAAkD,IAAI,IAAe,CAAC,SAAS,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;AAqB7F,SAAgB,iCAAiC,OAA4C;CAC3F,IAAI,CAAC,wBAAwB,IAAI,MAAM,IAAI,GAAG,OAAO,CAAC;CAEtD,MAAM,aAA0B,CAAC;CACjC,MAAM,OAAO;EAAE,WAAW,MAAM;EAAM,SAAS,MAAM;CAAG;CAExD,MAAM,aAAa,wBAAwB,MAAM;CACjD,IAAI,eAAe,KAAA,KAAa,yBAAyB,IAAI,MAAM,QAAQ,GACzE,WAAW,KAAK;EAAE,MAAM;EAAY,MAAM;GAAE,GAAG;GAAM,UAAU,MAAM;EAAS;CAAE,CAAC;CAEnF,IAAI,yBAAyB,KAAK,CAAC,EAAE,WACnC,WAAW,KAAK;EAAE,MAAM;EAA6B;CAAK,CAAC;CAE7D,OAAO;AACT"}
+{"version":3,"file":"report-track-conditions.js","names":[],"sources":["../../../../src/playback/primitives/report-track-conditions.ts"],"sourcesContent":["/**\n * The seam `resolve-track` uses to report conditions discovered in a freshly parsed media playlist.\n *\n * Injected rather than baked in so `resolve-track` stays free of format and policy knowledge: it parses and commits,\n * and whatever the composition wants noticed about the result is this function's business. Which conditions matter, and\n * which codes they carry, therefore vary per composition — a provider that never ships MPEG-TS can drop that check, and\n * future playlist-derived notices (LL-HLS or DVR support that's partial rather than absent) attach here without\n * touching the resolver.\n *\n * Reported **per rendition, as it resolves**, which is why these are causes and not verdicts: one rendition being\n * unplayable doesn't make the source unplayable. The verdict is `track-switching`'s, which reports\n * `SVTA_NO_SUPPORTED_{VIDEO,AUDIO}_TRACK` when a type's candidates actually empty. Keeping the two apart is what lets a\n * mixed source — some renditions encrypted or MPEG-TS, others playable — log its causes and still play.\n */\nimport {\n  SVTA_UNSUPPORTED_AUDIO_FORMAT,\n  SVTA_UNSUPPORTED_DRM_SYSTEM,\n  SVTA_UNSUPPORTED_VIDEO_FORMAT,\n  type SvtaError,\n} from '../../media/errors';\nimport { NON_FMP4_CONTAINER_MIMES } from '../../media/hls/parse-media-playlist';\nimport { getMediaPlaylistMetadata, type ResolvedTrack, type TrackType } from '../../media/types';\n\n/** Conditions worth reporting about a just-resolved track. Return an empty array (or omit the seam) to report nothing. */\nexport type ReportUnsupportedTrackConditions = (track: ResolvedTrack) => readonly SvtaError[];\n\n/** Unsupported-format code per type; text has none — absent captions aren't a failure. */\nconst UNSUPPORTED_FORMAT_CODE: Partial<Record<TrackType, number>> = {\n  video: SVTA_UNSUPPORTED_VIDEO_FORMAT,\n  audio: SVTA_UNSUPPORTED_AUDIO_FORMAT,\n};\n\n/**\n * The types a reported cause can legitimately describe: the ones whose candidates `canPlayTrack` actually prunes, via\n * `track-switching`'s `excludeUnplayableTracks` pre-pass.\n *\n * Text is outside it by design — its switching chain runs failed-CDN constraints alone, because an MSE codec probe is\n * the wrong question for a WebVTT rendition (see `track-switching.ts`). So nothing prunes a text rendition, no verdict\n * can follow from one, and a cause reported against it would be an orphan: the adapter's unsupported-feature\n * substitution scans the sequence as a whole, so a lone encrypted subtitle would otherwise recode an unrelated verdict\n * — an all-CDN cooldown among them — as \"this engine can't play the source\".\n */\nconst CAPABILITY_PRUNED_TYPES: ReadonlySet<TrackType> = new Set<TrackType>(['video', 'audio']);\n\n/**\n * The default: report what makes a rendition unplayable _to this engine_ — a container MSE can't accept, or encryption\n * with no decryption pipeline. Both mirror what `canPlayTrack` prunes on, so a reported cause always has a\n * corresponding exclusion.\n *\n * A condition carries its code and its context, not copy. `data.mimeType` is what preserves the specificity — the\n * format codes cover every non-fMP4 container, so \"which one\" lives there for a consumer that wants to say, rather than\n * being flattened into an English sentence here.\n *\n * Both carry `trackType`, redundantly for the format codes (1004/1005 are already per type) but not for 4008, which\n * isn't per type — SVTA has one content-protection code for both. Nothing branches on the tag: it's diagnostic context,\n * reaching a developer through the logged sequence and `error.data`, which is why it goes on every condition rather\n * than only where the code can't carry it. `trackId` alongside it is what distinguishes two renditions of the same\n * type.\n */\nexport function reportUnsupportedTrackConditions(track: ResolvedTrack): readonly SvtaError[] {\n  if (!CAPABILITY_PRUNED_TYPES.has(track.type)) return [];\n\n  const conditions: SvtaError[] = [];\n  const data = { trackType: track.type, trackId: track.id };\n\n  const formatCode = UNSUPPORTED_FORMAT_CODE[track.type];\n\n  if (formatCode !== undefined && NON_FMP4_CONTAINER_MIMES.has(track.mimeType)) {\n    conditions.push({ code: formatCode, data: { ...data, mimeType: track.mimeType } });\n  }\n\n  if (getMediaPlaylistMetadata(track)?.encrypted) {\n    conditions.push({ code: SVTA_UNSUPPORTED_DRM_SYSTEM, data });\n  }\n\n  return conditions;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA2BA,MAAM,0BAA8D;CAClE,OAAO;CACP,OAAO;AACT;;;;;;;;;;;AAYA,MAAM,0CAAkD,IAAI,IAAe,CAAC,SAAS,OAAO,CAAC;;;;;;;;;;;;;;;;AAiB7F,SAAgB,iCAAiC,OAA4C;CAC3F,IAAI,CAAC,wBAAwB,IAAI,MAAM,IAAI,GAAG,OAAO,CAAC;CAEtD,MAAM,aAA0B,CAAC;CACjC,MAAM,OAAO;EAAE,WAAW,MAAM;EAAM,SAAS,MAAM;CAAG;CAExD,MAAM,aAAa,wBAAwB,MAAM;CAEjD,IAAI,eAAe,KAAA,KAAa,yBAAyB,IAAI,MAAM,QAAQ,GACzE,WAAW,KAAK;EAAE,MAAM;EAAY,MAAM;GAAE,GAAG;GAAM,UAAU,MAAM;EAAS;CAAE,CAAC;CAGnF,IAAI,yBAAyB,KAAK,CAAC,EAAE,WACnC,WAAW,KAAK;EAAE,MAAM;EAA6B;CAAK,CAAC;CAG7D,OAAO;AACT"}

package/dist/dev/playback/primitives/segment-load-pipeline.js

@@ -1,22 +1,20 @@
 import { effect } from "../../core/signals/effect.js";
 //#region src/playback/primitives/segment-load-pipeline.ts
 /**
-* Base-step view of the loader's own wiring. `createSegmentLoaderActor` folds its
-* `sourceBufferActor` + `fetch` into the threaded `config` so base steps read them
-* from the uniform passthrough — present whether the loader runs inside a composition
-* or standalone. `config` is loose (`object`), so assert the shape here (one cast, like
-* relocation's `containerSlot`).
+* Base-step view of the loader's own wiring. `createSegmentLoaderActor` folds its `sourceBufferActor` + `fetch` into
+* the threaded `config` so base steps read them from the uniform passthrough — present whether the loader runs inside a
+* composition or standalone. `config` is loose (`object`), so assert the shape here (one cast, like relocation's
+* `containerSlot`).
 */
 function stepWiring(deps) {
 	return deps.config;
 }
 /**
-* Resolves when the SourceBufferActor snapshot reaches 'idle'.
-* Rejects if the signal is aborted or the actor is destroyed.
+* Resolves when the SourceBufferActor snapshot reaches 'idle'. Rejects if the signal is aborted or the actor is
+* destroyed.
 *
-* Used to sequence SourceBufferActor operations without awaiting send()
-* directly — send() is fire-and-forget; callers observe completion via
-* state transition.
+* Used to sequence SourceBufferActor operations without awaiting send() directly — send() is fire-and-forget; callers
+* observe completion via state transition.
 */
 function waitForIdle(snapshot, signal) {
 	return new Promise((resolve, reject) => {
@@ -47,7 +45,10 @@ function waitForIdle(snapshot, signal) {
 		signal.addEventListener("abort", onAbort, { once: true });
 	});
 }
-/** Build the SourceBuffer message a completed frame dispatches. `fetchStep` always precedes `dispatchStep` in append pipelines, so `data` is set by now. */
+/**
+* Build the SourceBuffer message a completed frame dispatches. `fetchStep` always precedes `dispatchStep` in append
+* pipelines, so `data` is set by now.
+*/
 function toMessage({ op, data, meta }) {
 	switch (op.type) {
 		case "remove": return op;
@@ -64,10 +65,9 @@ function toMessage({ op, data, meta }) {
 	}
 }
 /**
-* Fetch this op's bytes into the frame. Init segments need the full body
-* (`minChunkSize: Infinity`) before appending; media segments stream so chunks
-* append as they arrive. Awaiting headers eagerly also starts the HTTP
-* connection (and records the fetch in observers like tests).
+* Fetch this op's bytes into the frame. Init segments need the full body (`minChunkSize: Infinity`) before appending;
+* media segments stream so chunks append as they arrive. Awaiting headers eagerly also starts the HTTP connection (and
+* records the fetch in observers like tests).
 */
 const fetchStep = async (frame, signal, deps) => {
 	const { op } = frame;

package/dist/dev/playback/primitives/segment-load-pipeline.js.map

@@ -1 +1 @@
-{"version":3,"file":"segment-load-pipeline.js","names":[],"sources":["../../../../src/playback/primitives/segment-load-pipeline.ts"],"sourcesContent":["/**\n * The v/a segment **load pipeline** — the step vocabulary and base steps a segment\n * loader runs, extracted from the loader actor so the \"what\" (the composable steps)\n * is separable from the \"how\" (the actor's scheduling). A pipeline is a per-op list\n * of {@link LoadStep}s the loader drains in order; the default is `fetch → dispatch`,\n * and a composition can insert its own steps between them (e.g. non-zero-PTS\n * relocation) without the loader knowing.\n *\n * The base steps reach their SourceBuffer sink through the structural {@link AppendSink}\n * seam rather than the concrete actor type — the loader folds the real actor into\n * `config` at construction, and it satisfies the seam by structure — so this module\n * carries no dependency on the actor implementation, and no dependency on the DOM.\n */\nimport type { AnySlotMap } from '../../core/composition/create-composition';\nimport { effect } from '../../core/signals/effect';\nimport type { ReadonlySignal } from '../../core/signals/primitives';\nimport type { AddressableObject } from '../../media/types';\nimport type {\n  AppendInitMessage,\n  AppendSegmentMessage,\n  IndividualSourceBufferMessage,\n  RemoveMessage,\n} from './source-buffer-messages';\n\n// ============================================================================\n// SINK SEAM\n// ============================================================================\n\n/**\n * The structural view of a SourceBuffer sink the base steps use — just the ops\n * {@link dispatchStep} needs (`send` + a `snapshot` to await idle). The concrete\n * `SourceBufferActor` satisfies it by structure, so the pipeline names no actor.\n */\nexport interface AppendSink {\n  send(message: IndividualSourceBufferMessage): void;\n  snapshot: ReadonlySignal<{ value: string }>;\n}\n\n// ============================================================================\n// STEP MODEL\n// ============================================================================\n\n/**\n * A LoadTask is the intent to perform one unit of SegmentLoader work.\n * Unlike SourceBufferMessage, fetch-based tasks carry a URL rather than\n * pre-fetched data — the runner fetches and appends them in sequence.\n *\n * Derived from SourceBufferMessage types by removing `data` and adding\n * a fetch URL via AddressableObject.\n *\n * @todo Rename — \"LoadTask\" risks confusion with the `Task` class used for\n * SourceBufferActor scheduling. These are closer to operation descriptors or\n * messages than tasks in that sense.\n */\nexport type LoadTask =\n  | (Omit<AppendInitMessage, 'data'> & AddressableObject)\n  | (Omit<AppendSegmentMessage, 'data'> & AddressableObject)\n  | RemoveMessage;\n\n/**\n * A {@link LoadTask} mid-reassembly into its append message. `LoadTask` is a\n * message with `data` omitted and a URL added; the pipeline reverses that —\n * `fetchStep` produces `data`, `dispatchStep` reassembles the message. `data` is\n * the omitted payload (kept as the fetched stream — the loader never produces the\n * `ArrayBuffer` arm of `SegmentData` — widened back at dispatch). `meta` overrides\n * `op.meta` for `append-segment` (e.g. a stamped `timestampOffset`); an\n * `append-init` dispatches `op.meta` directly.\n */\nexport interface Frame {\n  readonly op: LoadTask;\n  data?: AsyncIterable<Uint8Array>;\n  meta?: AppendSegmentMessage['meta'];\n}\n\n/**\n * One stage of a message pipeline. Mutates the {@link Frame} in place and may be\n * async; the runner checks `signal.aborted` before each step and passes the\n * actor's {@link StepDeps} on every call, so a stateless step (e.g.\n * {@link fetchStep}) is a plain value, and a step that needs composition signals\n * (relocation's discover/stamp) reads them from `deps` at call time.\n */\nexport type LoadStep = (frame: Frame, signal: AbortSignal, deps: StepDeps) => void | Promise<void>;\n\n/**\n * The uniform passthrough handed to every {@link LoadStep} on every call — the\n * composition triple, nothing more. `state`/`context` are the full composition signal\n * maps; `config` is the threaded config with the loader's own wiring folded in (see\n * {@link stepWiring} + `createSegmentLoaderActor`). All three are typed loose: the\n * loader is a conduit and never reads them; a step asserts the slots it knows are\n * present (composition steps read `state`; base steps read the folded wiring off\n * `config`).\n */\nexport interface StepDeps {\n  state: AnySlotMap;\n  context: AnySlotMap;\n  config: object;\n}\n\n/**\n * Base-step view of the loader's own wiring. `createSegmentLoaderActor` folds its\n * `sourceBufferActor` + `fetch` into the threaded `config` so base steps read them\n * from the uniform passthrough — present whether the loader runs inside a composition\n * or standalone. `config` is loose (`object`), so assert the shape here (one cast, like\n * relocation's `containerSlot`).\n */\nfunction stepWiring(deps: StepDeps): { sourceBufferActor: AppendSink; fetch: FetchBytes } {\n  return deps.config as { sourceBufferActor: AppendSink; fetch: FetchBytes };\n}\n\n/**\n * Builds the ordered step list for each message type. Called **once per actor**\n * — its role is per-actor instantiation, so stateful steps (relocation's origin\n * discoverer) get fresh state per source reset; deps arrive at step-call time,\n * not here. The default ({@link DEFAULT_MESSAGE_PIPELINES}) is `fetch → dispatch`;\n * a non-zero-PTS composition returns a map that inserts its own discover/stamp\n * steps between them (see `establishStartMediaTime`), so the loader stays oblivious\n * to relocation and the Tier 0 pipeline carries no relocation vocabulary at all.\n */\nexport type MessagePipelines = () => Record<LoadTask['type'], LoadStep[]>;\n\n// ============================================================================\n// BASE STEPS\n// ============================================================================\n\nexport type FetchBytes = (\n  addressable: AddressableObject,\n  options?: RequestInit & { minChunkSize?: number }\n) => Promise<AsyncIterable<Uint8Array>>;\n\n/**\n * Resolves when the SourceBufferActor snapshot reaches 'idle'.\n * Rejects if the signal is aborted or the actor is destroyed.\n *\n * Used to sequence SourceBufferActor operations without awaiting send()\n * directly — send() is fire-and-forget; callers observe completion via\n * state transition.\n */\nfunction waitForIdle(snapshot: AppendSink['snapshot'], signal: AbortSignal): Promise<void> {\n  return new Promise((resolve, reject) => {\n    if (snapshot.get().value === 'idle') {\n      resolve();\n      return;\n    }\n    if (snapshot.get().value === 'destroyed') {\n      reject(new DOMException('Aborted', 'AbortError'));\n      return;\n    }\n    if (signal.aborted) {\n      reject(signal.reason);\n      return;\n    }\n\n    let stop: (() => void) | undefined;\n\n    const cleanup = (fn: () => void) => {\n      stop?.();\n      signal.removeEventListener('abort', onAbort);\n      fn();\n    };\n\n    const onAbort = () => cleanup(() => reject(signal.reason));\n\n    stop = effect(() => {\n      const value = snapshot.get().value;\n      if (value === 'idle') cleanup(resolve);\n      else if (value === 'destroyed') cleanup(() => reject(new DOMException('Aborted', 'AbortError')));\n    });\n\n    signal.addEventListener('abort', onAbort, { once: true });\n  });\n}\n\n/** Build the SourceBuffer message a completed frame dispatches. `fetchStep` always precedes `dispatchStep` in append pipelines, so `data` is set by now. */\nfunction toMessage({ op, data, meta }: Frame): IndividualSourceBufferMessage {\n  switch (op.type) {\n    case 'remove':\n      return op;\n    case 'append-init':\n      return { type: 'append-init', data: data!, meta: op.meta };\n    case 'append-segment':\n      return { type: 'append-segment', data: data!, meta: meta ?? op.meta };\n  }\n}\n\n/**\n * Fetch this op's bytes into the frame. Init segments need the full body\n * (`minChunkSize: Infinity`) before appending; media segments stream so chunks\n * append as they arrive. Awaiting headers eagerly also starts the HTTP\n * connection (and records the fetch in observers like tests).\n */\nexport const fetchStep: LoadStep = async (frame, signal, deps) => {\n  const { op } = frame;\n  if (op.type === 'remove') return; // fetchStep only appears in append pipelines\n  const { fetch } = stepWiring(deps);\n  frame.data = await fetch(op, op.type === 'append-init' ? { signal, minChunkSize: Infinity } : { signal });\n};\n\n/** Dispatch the frame's message to the SourceBufferActor and await its return to idle. */\nexport const dispatchStep: LoadStep = async (frame, signal, deps) => {\n  const { sourceBufferActor } = stepWiring(deps);\n  sourceBufferActor.send(toMessage(frame));\n  await waitForIdle(sourceBufferActor.snapshot, signal);\n};\n\n/** Tier 0 default: fetch (for ops that carry bytes) then dispatch. No relocation vocabulary. */\nexport const DEFAULT_MESSAGE_PIPELINES: MessagePipelines = () => ({\n  remove: [dispatchStep],\n  'append-init': [fetchStep, dispatchStep],\n  'append-segment': [fetchStep, dispatchStep],\n});\n"],"mappings":";;;;;;;;;AAyGA,SAAS,WAAW,MAAsE;CACxF,OAAO,KAAK;AACd;;;;;;;;;AA8BA,SAAS,YAAY,UAAkC,QAAoC;CACzF,OAAO,IAAI,SAAS,SAAS,WAAW;EACtC,IAAI,SAAS,IAAI,CAAC,CAAC,UAAU,QAAQ;GACnC,QAAQ;GACR;EACF;EACA,IAAI,SAAS,IAAI,CAAC,CAAC,UAAU,aAAa;GACxC,OAAO,IAAI,aAAa,WAAW,YAAY,CAAC;GAChD;EACF;EACA,IAAI,OAAO,SAAS;GAClB,OAAO,OAAO,MAAM;GACpB;EACF;EAEA,IAAI;EAEJ,MAAM,WAAW,OAAmB;GAClC,OAAO;GACP,OAAO,oBAAoB,SAAS,OAAO;GAC3C,GAAG;EACL;EAEA,MAAM,gBAAgB,cAAc,OAAO,OAAO,MAAM,CAAC;EAEzD,OAAO,aAAa;GAClB,MAAM,QAAQ,SAAS,IAAI,CAAC,CAAC;GAC7B,IAAI,UAAU,QAAQ,QAAQ,OAAO;QAChC,IAAI,UAAU,aAAa,cAAc,OAAO,IAAI,aAAa,WAAW,YAAY,CAAC,CAAC;EACjG,CAAC;EAED,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;CAC1D,CAAC;AACH;;AAGA,SAAS,UAAU,EAAE,IAAI,MAAM,QAA8C;CAC3E,QAAQ,GAAG,MAAX;EACE,KAAK,UACH,OAAO;EACT,KAAK,eACH,OAAO;GAAE,MAAM;GAAqB;GAAO,MAAM,GAAG;EAAK;EAC3D,KAAK,kBACH,OAAO;GAAE,MAAM;GAAwB;GAAO,MAAM,QAAQ,GAAG;EAAK;CACxE;AACF;;;;;;;AAQA,MAAa,YAAsB,OAAO,OAAO,QAAQ,SAAS;CAChE,MAAM,EAAE,OAAO;CACf,IAAI,GAAG,SAAS,UAAU;CAC1B,MAAM,EAAE,UAAU,WAAW,IAAI;CACjC,MAAM,OAAO,MAAM,MAAM,IAAI,GAAG,SAAS,gBAAgB;EAAE;EAAQ,cAAc;CAAS,IAAI,EAAE,OAAO,CAAC;AAC1G;;AAGA,MAAa,eAAyB,OAAO,OAAO,QAAQ,SAAS;CACnE,MAAM,EAAE,sBAAsB,WAAW,IAAI;CAC7C,kBAAkB,KAAK,UAAU,KAAK,CAAC;CACvC,MAAM,YAAY,kBAAkB,UAAU,MAAM;AACtD;;AAGA,MAAa,mCAAqD;CAChE,QAAQ,CAAC,YAAY;CACrB,eAAe,CAAC,WAAW,YAAY;CACvC,kBAAkB,CAAC,WAAW,YAAY;AAC5C"}
+{"version":3,"file":"segment-load-pipeline.js","names":[],"sources":["../../../../src/playback/primitives/segment-load-pipeline.ts"],"sourcesContent":["/**\n * The v/a segment **load pipeline** — the step vocabulary and base steps a segment loader runs, extracted from the\n * loader actor so the \"what\" (the composable steps) is separable from the \"how\" (the actor's scheduling). A pipeline is\n * a per-op list of {@link LoadStep}s the loader drains in order; the default is `fetch → dispatch`, and a composition\n * can insert its own steps between them (e.g. non-zero-PTS relocation) without the loader knowing.\n *\n * The base steps reach their SourceBuffer sink through the structural {@link AppendSink} seam rather than the concrete\n * actor type — the loader folds the real actor into `config` at construction, and it satisfies the seam by structure —\n * so this module carries no dependency on the actor implementation, and no dependency on the DOM.\n */\nimport type { AnySlotMap } from '../../core/composition/create-composition';\nimport { effect } from '../../core/signals/effect';\nimport type { ReadonlySignal } from '../../core/signals/primitives';\nimport type { AddressableObject } from '../../media/types';\nimport type {\n  AppendInitMessage,\n  AppendSegmentMessage,\n  IndividualSourceBufferMessage,\n  RemoveMessage,\n} from './source-buffer-messages';\n\n// ============================================================================\n// SINK SEAM\n// ============================================================================\n\n/**\n * The structural view of a SourceBuffer sink the base steps use — just the ops {@link dispatchStep} needs (`send` + a\n * `snapshot` to await idle). The concrete `SourceBufferActor` satisfies it by structure, so the pipeline names no\n * actor.\n */\nexport interface AppendSink {\n  send(message: IndividualSourceBufferMessage): void;\n  snapshot: ReadonlySignal<{ value: string }>;\n}\n\n// ============================================================================\n// STEP MODEL\n// ============================================================================\n\n/**\n * A LoadTask is the intent to perform one unit of SegmentLoader work. Unlike SourceBufferMessage, fetch-based tasks\n * carry a URL rather than pre-fetched data — the runner fetches and appends them in sequence.\n *\n * Derived from SourceBufferMessage types by removing `data` and adding a fetch URL via AddressableObject.\n *\n * @todo Rename — \"LoadTask\" risks confusion with the `Task` class used for SourceBufferActor scheduling. These are\n *   closer to operation descriptors or messages than tasks in that sense.\n */\nexport type LoadTask =\n  | (Omit<AppendInitMessage, 'data'> & AddressableObject)\n  | (Omit<AppendSegmentMessage, 'data'> & AddressableObject)\n  | RemoveMessage;\n\n/**\n * A {@link LoadTask} mid-reassembly into its append message. `LoadTask` is a message with `data` omitted and a URL\n * added; the pipeline reverses that — `fetchStep` produces `data`, `dispatchStep` reassembles the message. `data` is\n * the omitted payload (kept as the fetched stream — the loader never produces the `ArrayBuffer` arm of `SegmentData` —\n * widened back at dispatch). `meta` overrides `op.meta` for `append-segment` (e.g. a stamped `timestampOffset`); an\n * `append-init` dispatches `op.meta` directly.\n */\nexport interface Frame {\n  readonly op: LoadTask;\n  data?: AsyncIterable<Uint8Array>;\n  meta?: AppendSegmentMessage['meta'];\n}\n\n/**\n * One stage of a message pipeline. Mutates the {@link Frame} in place and may be async; the runner checks\n * `signal.aborted` before each step and passes the actor's {@link StepDeps} on every call, so a stateless step (e.g.\n * {@link fetchStep}) is a plain value, and a step that needs composition signals (relocation's discover/stamp) reads\n * them from `deps` at call time.\n */\nexport type LoadStep = (frame: Frame, signal: AbortSignal, deps: StepDeps) => void | Promise<void>;\n\n/**\n * The uniform passthrough handed to every {@link LoadStep} on every call — the composition triple, nothing more.\n * `state`/`context` are the full composition signal maps; `config` is the threaded config with the loader's own wiring\n * folded in (see {@link stepWiring} + `createSegmentLoaderActor`). All three are typed loose: the loader is a conduit\n * and never reads them; a step asserts the slots it knows are present (composition steps read `state`; base steps read\n * the folded wiring off `config`).\n */\nexport interface StepDeps {\n  state: AnySlotMap;\n  context: AnySlotMap;\n  config: object;\n}\n\n/**\n * Base-step view of the loader's own wiring. `createSegmentLoaderActor` folds its `sourceBufferActor` + `fetch` into\n * the threaded `config` so base steps read them from the uniform passthrough — present whether the loader runs inside a\n * composition or standalone. `config` is loose (`object`), so assert the shape here (one cast, like relocation's\n * `containerSlot`).\n */\nfunction stepWiring(deps: StepDeps): { sourceBufferActor: AppendSink; fetch: FetchBytes } {\n  return deps.config as { sourceBufferActor: AppendSink; fetch: FetchBytes };\n}\n\n/**\n * Builds the ordered step list for each message type. Called **once per actor** — its role is per-actor instantiation,\n * so stateful steps (relocation's origin discoverer) get fresh state per source reset; deps arrive at step-call time,\n * not here. The default ({@link DEFAULT_MESSAGE_PIPELINES}) is `fetch → dispatch`; a non-zero-PTS composition returns a\n * map that inserts its own discover/stamp steps between them (see `establishStartMediaTime`), so the loader stays\n * oblivious to relocation and the Tier 0 pipeline carries no relocation vocabulary at all.\n */\nexport type MessagePipelines = () => Record<LoadTask['type'], LoadStep[]>;\n\n// ============================================================================\n// BASE STEPS\n// ============================================================================\n\nexport type FetchBytes = (\n  addressable: AddressableObject,\n  options?: RequestInit & { minChunkSize?: number }\n) => Promise<AsyncIterable<Uint8Array>>;\n\n/**\n * Resolves when the SourceBufferActor snapshot reaches 'idle'. Rejects if the signal is aborted or the actor is\n * destroyed.\n *\n * Used to sequence SourceBufferActor operations without awaiting send() directly — send() is fire-and-forget; callers\n * observe completion via state transition.\n */\nfunction waitForIdle(snapshot: AppendSink['snapshot'], signal: AbortSignal): Promise<void> {\n  return new Promise((resolve, reject) => {\n    if (snapshot.get().value === 'idle') {\n      resolve();\n      return;\n    }\n\n    if (snapshot.get().value === 'destroyed') {\n      reject(new DOMException('Aborted', 'AbortError'));\n      return;\n    }\n\n    if (signal.aborted) {\n      reject(signal.reason);\n      return;\n    }\n\n    let stop: (() => void) | undefined;\n\n    const cleanup = (fn: () => void) => {\n      stop?.();\n      signal.removeEventListener('abort', onAbort);\n      fn();\n    };\n\n    const onAbort = () => cleanup(() => reject(signal.reason));\n\n    stop = effect(() => {\n      const value = snapshot.get().value;\n\n      if (value === 'idle') cleanup(resolve);\n      else if (value === 'destroyed') cleanup(() => reject(new DOMException('Aborted', 'AbortError')));\n    });\n\n    signal.addEventListener('abort', onAbort, { once: true });\n  });\n}\n\n/**\n * Build the SourceBuffer message a completed frame dispatches. `fetchStep` always precedes `dispatchStep` in append\n * pipelines, so `data` is set by now.\n */\nfunction toMessage({ op, data, meta }: Frame): IndividualSourceBufferMessage {\n  switch (op.type) {\n    case 'remove':\n      return op;\n    case 'append-init':\n      return { type: 'append-init', data: data!, meta: op.meta };\n    case 'append-segment':\n      return { type: 'append-segment', data: data!, meta: meta ?? op.meta };\n  }\n}\n\n/**\n * Fetch this op's bytes into the frame. Init segments need the full body (`minChunkSize: Infinity`) before appending;\n * media segments stream so chunks append as they arrive. Awaiting headers eagerly also starts the HTTP connection (and\n * records the fetch in observers like tests).\n */\nexport const fetchStep: LoadStep = async (frame, signal, deps) => {\n  const { op } = frame;\n  if (op.type === 'remove') return; // fetchStep only appears in append pipelines\n\n  const { fetch } = stepWiring(deps);\n\n  frame.data = await fetch(op, op.type === 'append-init' ? { signal, minChunkSize: Infinity } : { signal });\n};\n\n/** Dispatch the frame's message to the SourceBufferActor and await its return to idle. */\nexport const dispatchStep: LoadStep = async (frame, signal, deps) => {\n  const { sourceBufferActor } = stepWiring(deps);\n\n  sourceBufferActor.send(toMessage(frame));\n  await waitForIdle(sourceBufferActor.snapshot, signal);\n};\n\n/** Tier 0 default: fetch (for ops that carry bytes) then dispatch. No relocation vocabulary. */\nexport const DEFAULT_MESSAGE_PIPELINES: MessagePipelines = () => ({\n  remove: [dispatchStep],\n  'append-init': [fetchStep, dispatchStep],\n  'append-segment': [fetchStep, dispatchStep],\n});\n"],"mappings":";;;;;;;;AA6FA,SAAS,WAAW,MAAsE;CACxF,OAAO,KAAK;AACd;;;;;;;;AA2BA,SAAS,YAAY,UAAkC,QAAoC;CACzF,OAAO,IAAI,SAAS,SAAS,WAAW;EACtC,IAAI,SAAS,IAAI,CAAC,CAAC,UAAU,QAAQ;GACnC,QAAQ;GACR;EACF;EAEA,IAAI,SAAS,IAAI,CAAC,CAAC,UAAU,aAAa;GACxC,OAAO,IAAI,aAAa,WAAW,YAAY,CAAC;GAChD;EACF;EAEA,IAAI,OAAO,SAAS;GAClB,OAAO,OAAO,MAAM;GACpB;EACF;EAEA,IAAI;EAEJ,MAAM,WAAW,OAAmB;GAClC,OAAO;GACP,OAAO,oBAAoB,SAAS,OAAO;GAC3C,GAAG;EACL;EAEA,MAAM,gBAAgB,cAAc,OAAO,OAAO,MAAM,CAAC;EAEzD,OAAO,aAAa;GAClB,MAAM,QAAQ,SAAS,IAAI,CAAC,CAAC;GAE7B,IAAI,UAAU,QAAQ,QAAQ,OAAO;QAChC,IAAI,UAAU,aAAa,cAAc,OAAO,IAAI,aAAa,WAAW,YAAY,CAAC,CAAC;EACjG,CAAC;EAED,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;CAC1D,CAAC;AACH;;;;;AAMA,SAAS,UAAU,EAAE,IAAI,MAAM,QAA8C;CAC3E,QAAQ,GAAG,MAAX;EACE,KAAK,UACH,OAAO;EACT,KAAK,eACH,OAAO;GAAE,MAAM;GAAqB;GAAO,MAAM,GAAG;EAAK;EAC3D,KAAK,kBACH,OAAO;GAAE,MAAM;GAAwB;GAAO,MAAM,QAAQ,GAAG;EAAK;CACxE;AACF;;;;;;AAOA,MAAa,YAAsB,OAAO,OAAO,QAAQ,SAAS;CAChE,MAAM,EAAE,OAAO;CACf,IAAI,GAAG,SAAS,UAAU;CAE1B,MAAM,EAAE,UAAU,WAAW,IAAI;CAEjC,MAAM,OAAO,MAAM,MAAM,IAAI,GAAG,SAAS,gBAAgB;EAAE;EAAQ,cAAc;CAAS,IAAI,EAAE,OAAO,CAAC;AAC1G;;AAGA,MAAa,eAAyB,OAAO,OAAO,QAAQ,SAAS;CACnE,MAAM,EAAE,sBAAsB,WAAW,IAAI;CAE7C,kBAAkB,KAAK,UAAU,KAAK,CAAC;CACvC,MAAM,YAAY,kBAAkB,UAAU,MAAM;AACtD;;AAGA,MAAa,mCAAqD;CAChE,QAAQ,CAAC,YAAY;CACrB,eAAe,CAAC,WAAW,YAAY;CACvC,kBAAkB,CAAC,WAAW,YAAY;AAC5C"}

package/dist/dev/playback/primitives/selection-rules.d.ts

@@ -1,10 +1,9 @@
 import { CanPlayTrack } from "../../media/types/index.js";
 //#region src/playback/primitives/selection-rules.d.ts
 /**
- * Deps handed to each rule and to `applyRules`, mirroring a behavior's setup
- * deps so a rule reads from the same surfaces a behavior does. `context` is
- * optional — it's threaded through but absent on direct setup calls (and
- * unread by today's rules), so the whole deps object can pass straight through.
+ * Deps handed to each rule and to `applyRules`, mirroring a behavior's setup deps so a rule reads from the same
+ * surfaces a behavior does. `context` is optional — it's threaded through but absent on direct setup calls (and unread
+ * by today's rules), so the whole deps object can pass straight through.
  */
 interface SelectionRuleDeps<State = unknown, Context = unknown, Config = unknown> {
   state: State;
@@ -12,27 +11,56 @@ interface SelectionRuleDeps<State = unknown, Context = unknown, Config = unknown
   config: Config;
 }
 /**
- * A selection rule narrows or reorders the candidate list. It reads the state,
- * context, and config it needs at apply time (tightly-coupled reads), so a
- * rule's `.get()`s subscribe the running effect to exactly what it consulted.
- * Returning an empty list means "no match" — the composer skips it, so a soft
- * filter never narrows the set to nothing. A ranker returns the list with its
- * pick at the head.
+ * A selection rule narrows or reorders the candidate list. It reads the state, context, and config it needs at apply
+ * time (tightly-coupled reads), so a rule's `.get()`s subscribe the running effect to exactly what it consulted.
+ * Returning an empty list means "no match" — the composer skips it, so a soft filter never narrows the set to nothing.
+ * A ranker returns the list with its pick at the head.
  */
 type SelectionRule<T, State = unknown, Context = unknown, Config = unknown> = (tracks: readonly T[], deps: SelectionRuleDeps<State, Context, Config>) => readonly T[];
 /**
  * What {@link excludeUnplayableTracks} reads off the config it is handed.
  *
- * Read through a cast rather than constraining the rule's `Config` generic, the
- * same way `screenResolutionCap` reads `screenResolution` off its state: a rule
- * composes into chains whose config types have nothing else in common, and
- * constraining the generic would make every one of those a weak-type mismatch.
- * Each engine defaults `canPlayTrack` to the DOM-bound probe; unwired means "no
- * capability filtering" and the constraint passes everything through.
+ * Read through a cast rather than constraining the rule's `Config` generic, the same way `screenResolutionCap` reads
+ * `screenResolution` off its state: a rule composes into chains whose config types have nothing else in common, and
+ * constraining the generic would make every one of those a weak-type mismatch. Each engine defaults `canPlayTrack` to
+ * the DOM-bound probe; unwired means "no capability filtering" and the constraint passes everything through.
  */
 interface CapabilityConstraintConfig {
   canPlayTrack?: CanPlayTrack;
 }
+/**
+ * What {@link preferCodecFamilies} reads off the config it is handed — a cast view, for the same reason as
+ * {@link CapabilityConstraintConfig}.
+ */
+interface CodecPreferenceConfig {
+  preferredCodecs?: string[];
+}
+/**
+ * The codec families {@link preferCodecFamilies} narrows to when the config carries no `preferredCodecs`: AVC (both its
+ * 4CCs) and AAC. The default is deliberate rather than neutral — SPF implements no `SourceBuffer.changeType()`, so on a
+ * mixed-codec source the _initial_ family choice is the one ABR lives inside for the whole source (see
+ * `stickToSelectedCodecs` in `behaviors/track-switching.ts`), and AVC/AAC is the family pair with the broadest decode
+ * support. The cost, equally deliberate: on a ladder whose higher rungs are HEVC-only (a common 4K shape), the default
+ * caps quality at the top AVC rung — configure `preferredCodecs` (or pass `[]`) to trade the other way.
+ */
+declare const DEFAULT_PREFERRED_CODECS: readonly string[];
+/**
+ * Codec-family preference — a _soft_ filter (scope) for a selection-rule chain; the `hevc-variant-selection` concern
+ * from `internal/design/spf/track-switching-model.md`. Narrows to the tracks whose codec families are all in
+ * `preferredCodecs` (family-compared, so entries may be 4CCs or full codec strings). Soft-filter semantics: a source
+ * with no preferred-family rendition (an HEVC-only ladder under the AVC default) is left unnarrowed, and a track
+ * without codecs never matches — on a ladder with no codecs anywhere (DOM-free tests) the rule is inert.
+ *
+ * `preferredCodecs` defaults to {@link DEFAULT_PREFERRED_CODECS}; explicitly pass `[]` to disable the preference while
+ * keeping the rule composed.
+ *
+ * "All families" rather than "any" so a muxed rendition is judged as the unit it is: `hvc1,mp4a` must not count as
+ * preferred just because its audio half matches.
+ *
+ * Lives here rather than beside `switchVideoTrack` for the module's usual reason: the pinned `selectVideoTrack` variant
+ * can compose it without dragging the ABR path in.
+ */
+declare function preferCodecFamilies<T, State, Context, Config>(tracks: readonly T[], { config }: SelectionRuleDeps<State, Context, Config>): readonly T[];
 //#endregion
-export { CapabilityConstraintConfig, SelectionRule, SelectionRuleDeps };
+export { CapabilityConstraintConfig, CodecPreferenceConfig, DEFAULT_PREFERRED_CODECS, SelectionRule, SelectionRuleDeps, preferCodecFamilies };
 //# sourceMappingURL=selection-rules.d.ts.map

package/dist/dev/playback/primitives/selection-rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"selection-rules.d.ts","names":[],"sources":["../../../../src/playback/primitives/selection-rules.ts"],"mappings":";;;;;;;;UAwBiB,kBAAkB,iBAAiB,mBAAmB;EACrE,OAAO;EACP,UAAU;EACV,QAAQ;;;;;;;;;;KAWE,cAAc,GAAG,iBAAiB,mBAAmB,qBAC/D,iBAAiB,KACjB,MAAM,kBAAkB,OAAO,SAAS,qBAC5B;;;;;;;;;;;UA+EG;EACf,eAAe"}
+{"version":3,"file":"selection-rules.d.ts","names":[],"sources":["../../../../src/playback/primitives/selection-rules.ts"],"mappings":";;;;;;;UAqBiB,kBAAkB,iBAAiB,mBAAmB;EACrE,OAAO;EACP,UAAU;EACV,QAAQ;;;;;;;;KASE,cAAc,GAAG,iBAAiB,mBAAmB,qBAC/D,iBAAiB,KACjB,MAAM,kBAAkB,OAAO,SAAS,qBAC5B;;;;;;;;;UA6EG;EACf,eAAe;;;;;;UAiCA;EACf;;;;;;;;;;cAWW;;;;;;;;;;;;;;;;;iBAkBG,oBAAoB,GAAG,OAAO,SAAS,QACrD,iBAAiB,OACf,UAAU,kBAAkB,OAAO,SAAS,mBACpC"}

package/dist/dev/playback/primitives/selection-rules.js

@@ -1,11 +1,10 @@
+import { getCodecFamilies, getCodecFamily } from "../../media/utils/tracks.js";
 //#region src/playback/primitives/selection-rules.ts
 /**
-* Apply rules to a candidate list in order; the pick is the first survivor.
-* Two responsibilities the rules don't carry: a rule that returns nothing is
-* skipped (fall-through — a preference never empties the set), and once one
-* survivor remains the chain stops (early-bail — later rules, including the
-* bandwidth ranker, never run, so the effect doesn't subscribe to their
-* signals while the choice is fixed).
+* Apply rules to a candidate list in order; the pick is the first survivor. Two responsibilities the rules don't carry:
+* a rule that returns nothing is skipped (fall-through — a preference never empties the set), and once one survivor
+* remains the chain stops (early-bail — later rules, including the bandwidth ranker, never run, so the effect doesn't
+* subscribe to their signals while the choice is fixed).
 *
 * @param rules - Rules to apply, most authoritative first
 * @param tracks - Candidate tracks
@@ -23,15 +22,12 @@ function applyRules(rules, tracks, deps) {
 	return current;
 }
 /**
-* Apply hard constraints to a candidate list — the pre-pass that runs before the
-* rule chain. A constraint shares a rule's signature but its exclusion is
-* *hard*: it removes the unplayable (a codec the environment can't decode, a CDN
-* in failover cooldown) and a removed track is never attempted. Unlike
-* `applyRules`, this never skips an empty result and never early-bails — every
-* constraint always applies, and an empty survivor set is a real outcome
-* ("nothing playable here"), not a fall-through. Because each constraint only
-* removes, the order they run in can't change which tracks survive — though one
-* that also *reports* reads the list at its own position, so placement matters.
+* Apply hard constraints to a candidate list — the pre-pass that runs before the rule chain. A constraint shares a
+* rule's signature but its exclusion is _hard_: it removes the unplayable (a codec the environment can't decode, a CDN
+* in failover cooldown) and a removed track is never attempted. Unlike `applyRules`, this never skips an empty result
+* and never early-bails — every constraint always applies, and an empty survivor set is a real outcome ("nothing
+* playable here"), not a fall-through. Because each constraint only removes, the order they run in can't change which
+* tracks survive — though one that also _reports_ reads the list at its own position, so placement matters.
 *
 * @param constraints - Constraints to apply, in order
 * @param tracks - Candidate tracks
@@ -46,41 +42,74 @@ function applyConstraints(constraints, tracks, deps) {
 /**
 * Whether two candidate sets hold the same tracks, by id.
 *
-* The `equals` both selection behaviors give their candidate-set `computed`. A
-* live playlist refresh swaps in a new presentation object carrying the same
-* variants, and a constraint's own inputs can churn without changing which
-* tracks survive; in both cases the set is unchanged and the reaction must not
-* re-fire. Compares by id rather than array identity for exactly that.
+* The `equals` both selection behaviors give their candidate-set `computed`. A live playlist refresh swaps in a new
+* presentation object carrying the same variants, and a constraint's own inputs can churn without changing which tracks
+* survive; in both cases the set is unchanged and the reaction must not re-fire. Compares by id rather than array
+* identity for exactly that.
 */
 function sameCandidateSet(a, b) {
 	return a.length === b.length && a.every((track) => b.some((other) => other.id === track.id));
 }
 /**
-* Capability constraint — a *hard* filter for the {@link applyConstraints}
-* pre-pass. Removes renditions this environment can't decode, probed via the
-* injected `canPlayTrack` (codec → `MediaSource.isTypeSupported`, plus the
-* container and encryption assertions that probe can't make). Constraining here
-* — before selection — means an unplayable variant is pruned upstream and never
-* picked, instead of surviving into the pipeline to fail late at
-* `createSourceBuffer`. That late throw stays as a defensive structural
-* guarantee; with this constraint it should rarely fire.
+* Capability constraint — a _hard_ filter for the {@link applyConstraints} pre-pass. Removes renditions this
+* environment can't decode, probed via the injected `canPlayTrack` (codec → `MediaSource.isTypeSupported`, plus the
+* container and encryption assertions that probe can't make). Constraining here — before selection — means an
+* unplayable variant is pruned upstream and never picked, instead of surviving into the pipeline to fail late at
+* `createSourceBuffer`. That late throw stays as a defensive structural guarantee; with this constraint it should
+* rarely fire.
 *
-* Lives here rather than beside `switchVideoTrack` for the reason this module
-* exists: both the re-evaluating variant and the pinned `selectVideoTrack` apply
-* it, and reaching it through `behaviors/track-switching.ts` would drag the ABR
+* Lives here rather than beside `switchVideoTrack` for the reason this module exists: both the re-evaluating variant
+* and the pinned `selectVideoTrack` apply it, and reaching it through `behaviors/track-switching.ts` would drag the ABR
 * path into a composition that deliberately omits it.
 *
-* Passes everything through when there's no probe (a composition that didn't
-* wire one, or DOM-free tests). When it prunes *every* track, the empty result is
-* preserved (per `applyConstraints`) — "nothing playable" — which each consuming
-* behavior answers by clearing its selection; reporting the verdict is separate.
+* Passes everything through when there's no probe (a composition that didn't wire one, or DOM-free tests). When it
+* prunes _every_ track, the empty result is preserved (per `applyConstraints`) — "nothing playable" — which each
+* consuming behavior answers by clearing its selection; reporting the verdict is separate.
 */
 function excludeUnplayableTracks(tracks, { config }) {
 	const canPlay = config?.canPlayTrack;
 	if (!canPlay) return tracks;
 	return tracks.filter((track) => canPlay(track));
 }
+/**
+* The codec families {@link preferCodecFamilies} narrows to when the config carries no `preferredCodecs`: AVC (both its
+* 4CCs) and AAC. The default is deliberate rather than neutral — SPF implements no `SourceBuffer.changeType()`, so on a
+* mixed-codec source the _initial_ family choice is the one ABR lives inside for the whole source (see
+* `stickToSelectedCodecs` in `behaviors/track-switching.ts`), and AVC/AAC is the family pair with the broadest decode
+* support. The cost, equally deliberate: on a ladder whose higher rungs are HEVC-only (a common 4K shape), the default
+* caps quality at the top AVC rung — configure `preferredCodecs` (or pass `[]`) to trade the other way.
+*/
+const DEFAULT_PREFERRED_CODECS = [
+	"avc1",
+	"avc3",
+	"mp4a"
+];
+/**
+* Codec-family preference — a _soft_ filter (scope) for a selection-rule chain; the `hevc-variant-selection` concern
+* from `internal/design/spf/track-switching-model.md`. Narrows to the tracks whose codec families are all in
+* `preferredCodecs` (family-compared, so entries may be 4CCs or full codec strings). Soft-filter semantics: a source
+* with no preferred-family rendition (an HEVC-only ladder under the AVC default) is left unnarrowed, and a track
+* without codecs never matches — on a ladder with no codecs anywhere (DOM-free tests) the rule is inert.
+*
+* `preferredCodecs` defaults to {@link DEFAULT_PREFERRED_CODECS}; explicitly pass `[]` to disable the preference while
+* keeping the rule composed.
+*
+* "All families" rather than "any" so a muxed rendition is judged as the unit it is: `hvc1,mp4a` must not count as
+* preferred just because its audio half matches.
+*
+* Lives here rather than beside `switchVideoTrack` for the module's usual reason: the pinned `selectVideoTrack` variant
+* can compose it without dragging the ABR path in.
+*/
+function preferCodecFamilies(tracks, { config }) {
+	const preferred = config?.preferredCodecs ?? DEFAULT_PREFERRED_CODECS;
+	if (!preferred.length) return tracks;
+	const preferredFamilies = new Set(preferred.map(getCodecFamily));
+	return tracks.filter((track) => {
+		const families = getCodecFamilies(track);
+		return !!families && families.every((family) => preferredFamilies.has(family));
+	});
+}
 //#endregion
-export { applyConstraints, applyRules, excludeUnplayableTracks, sameCandidateSet };
+export { DEFAULT_PREFERRED_CODECS, applyConstraints, applyRules, excludeUnplayableTracks, preferCodecFamilies, sameCandidateSet };
 
 //# sourceMappingURL=selection-rules.js.map