@videojs/spf 10.0.0-beta.11 → 10.0.0-beta.12

package/dist/default/core/abr/bandwidth-estimator.js

@@ -1,5 +1,4 @@
 import { applyZeroFactor, calculateEwma } from "./ewma.js";
-
 //#region src/core/abr/bandwidth-estimator.ts
 /**
 * Dual EWMA Bandwidth Estimator
@@ -90,7 +89,7 @@ function getBandwidthEstimate(state, defaultEstimate, config = DEFAULT_BANDWIDTH
 	const slowEstimate = applyZeroFactor(state.slowEstimate, state.slowTotalWeight, config.slowHalfLife);
 	return Math.min(fastEstimate, slowEstimate);
 }
-
 //#endregion
-export { DEFAULT_BANDWIDTH_CONFIG, getBandwidthEstimate, sampleBandwidth };
+export { getBandwidthEstimate, sampleBandwidth };
+
 //# sourceMappingURL=bandwidth-estimator.js.map

package/dist/default/core/abr/bandwidth-estimator.js.map

@@ -1 +1 @@
-{"version":3,"file":"bandwidth-estimator.js","names":[],"sources":["../../../../src/core/abr/bandwidth-estimator.ts"],"sourcesContent":["/**\n * Dual EWMA Bandwidth Estimator\n *\n * Estimates available bandwidth using two EWMA calculations with different\n * half-lives, taking the minimum of both. This approach (from Shaka Player):\n *\n * - **Fast EWMA** (2s half-life): Reacts quickly to bandwidth drops\n * - **Slow EWMA** (5s half-life): Provides stability during fluctuations\n * - **min(fast, slow)**: Adapts down quickly, up slowly\n *\n * This naturally provides asymmetric behavior needed for good QoE:\n * avoiding stalls (quick downgrade) while preventing oscillation (slow upgrade).\n */\n\nimport { applyZeroFactor, calculateEwma } from './ewma';\n\n/**\n * Bandwidth estimator state.\n *\n * This state structure will be managed by O1 (State Container).\n * Functions in this module operate on this state immutably.\n */\nexport interface BandwidthState {\n  /** Fast-moving EWMA estimate (raw, uncorrected). */\n  fastEstimate: number;\n  /** Total weight accumulated in fast EWMA. */\n  fastTotalWeight: number;\n  /** Slow-moving EWMA estimate (raw, uncorrected). */\n  slowEstimate: number;\n  /** Total weight accumulated in slow EWMA. */\n  slowTotalWeight: number;\n  /** Total bytes sampled across all valid samples. */\n  bytesSampled: number;\n}\n\n/**\n * Configuration for bandwidth estimation.\n */\nexport interface BandwidthConfig {\n  /** Half-life for fast EWMA in seconds. */\n  fastHalfLife: number;\n  /** Half-life for slow EWMA in seconds. */\n  slowHalfLife: number;\n  /** Minimum total bytes before trusting the estimate. */\n  minTotalBytes: number;\n  /** Minimum bytes per sample to count (filters TTFB-dominated samples). */\n  minBytes: number;\n  /** Minimum sample duration in ms (filters cached responses). */\n  minDuration: number;\n}\n\n/**\n * Default bandwidth estimator configuration.\n *\n * Values match Shaka Player defaults based on experimentation.\n */\nexport const DEFAULT_BANDWIDTH_CONFIG: BandwidthConfig = {\n  fastHalfLife: 2, // 2 seconds\n  slowHalfLife: 5, // 5 seconds\n  minTotalBytes: 128_000, // 128 KB\n  minBytes: 16_000, // 16 KB\n  minDuration: 5, // 5 ms\n};\n\n/**\n * Add a bandwidth sample from a segment download.\n *\n * Samples are filtered based on:\n * - Minimum bytes (filters TTFB-dominated small segments)\n * - Minimum duration (filters cached responses)\n *\n * Valid samples update both fast and slow EWMA estimates.\n *\n * @param state - Current estimator state\n * @param durationMs - Download duration in milliseconds\n * @param numBytes - Number of bytes downloaded\n * @param config - Optional estimator configuration (uses defaults if not provided)\n * @returns New estimator state with sample incorporated (or unchanged if filtered)\n *\n * @example\n * let state = { fastEstimate: 0, fastTotalWeight: 0, ... };\n * // Sample: 1MB in 1 second\n * state = sampleBandwidth(state, 1000, 1_000_000);\n */\nexport function sampleBandwidth(\n  state: BandwidthState,\n  durationMs: number,\n  numBytes: number,\n  config: BandwidthConfig = DEFAULT_BANDWIDTH_CONFIG\n): BandwidthState {\n  // Always track bytes for startup phase calculation\n  const updatedBytesSampled = state.bytesSampled + numBytes;\n\n  // Filter: Ignore samples below minimum bytes (TTFB-dominated)\n  // Small segments' download time is mostly connection setup latency,\n  // which would artificially lower our bandwidth estimate\n  if (numBytes < config.minBytes) {\n    return { ...state, bytesSampled: updatedBytesSampled };\n  }\n\n  // Filter: Ignore samples faster than minimum duration (cached responses)\n  // Cached responses load nearly instantly and would artificially inflate\n  // our bandwidth estimate\n  if (durationMs < config.minDuration) {\n    return { ...state, bytesSampled: updatedBytesSampled };\n  }\n\n  // Calculate bandwidth in bits per second\n  // Formula: (bytes * 8 bits/byte * 1000 ms/s) / ms = bits/s\n  const bandwidth = (8000 * numBytes) / durationMs;\n\n  // Weight by duration in seconds\n  // Longer downloads are more reliable indicators of true bandwidth\n  const weight = durationMs / 1000;\n\n  return {\n    fastEstimate: calculateEwma(state.fastEstimate, bandwidth, weight, config.fastHalfLife),\n    fastTotalWeight: state.fastTotalWeight + weight,\n    slowEstimate: calculateEwma(state.slowEstimate, bandwidth, weight, config.slowHalfLife),\n    slowTotalWeight: state.slowTotalWeight + weight,\n    bytesSampled: updatedBytesSampled,\n  };\n}\n\n/**\n * Get the current bandwidth estimate.\n *\n * Returns the **minimum** of the fast and slow EWMA estimates.\n * This provides the key asymmetric behavior:\n * - When bandwidth drops, fast EWMA reacts first and dominates (quick adaptation)\n * - When bandwidth rises, slow EWMA lags behind and dominates (slow adaptation)\n *\n * Uses default estimate until enough data has been sampled.\n *\n * @param state - Current estimator state\n * @param defaultEstimate - Fallback estimate before sufficient samples (bps)\n * @param config - Optional estimator configuration (uses defaults if not provided)\n * @returns Bandwidth estimate in bits per second\n *\n * @example\n * const estimate = getBandwidthEstimate(state, 5_000_000); // 5 Mbps default\n */\nexport function getBandwidthEstimate(\n  state: BandwidthState,\n  defaultEstimate: number,\n  config: BandwidthConfig = DEFAULT_BANDWIDTH_CONFIG\n): number {\n  // Use default until we have enough samples to trust our estimate\n  if (state.bytesSampled < config.minTotalBytes) {\n    return defaultEstimate;\n  }\n\n  // Apply zero-factor correction to both estimates\n  const fastEstimate = applyZeroFactor(state.fastEstimate, state.fastTotalWeight, config.fastHalfLife);\n\n  const slowEstimate = applyZeroFactor(state.slowEstimate, state.slowTotalWeight, config.slowHalfLife);\n\n  // Take the minimum - this is the key insight from Shaka Player\n  // It naturally provides \"down quickly, up slowly\" behavior\n  return Math.min(fastEstimate, slowEstimate);\n}\n\n/**\n * Check if the estimator has enough data to provide a reliable estimate.\n *\n * Requires both:\n * - Enough total bytes sampled (minTotalBytes threshold)\n * - At least one valid EWMA sample (totalWeight > 0)\n *\n * @param state - Current estimator state\n * @param config - Optional estimator configuration (uses defaults if not provided)\n * @returns True if we've sampled enough bytes to trust the estimate\n *\n * @example\n * if (hasGoodEstimate(state)) {\n *   const estimate = getBandwidthEstimate(state, 5_000_000);\n * }\n */\nexport function hasGoodEstimate(state: BandwidthState, config: BandwidthConfig = DEFAULT_BANDWIDTH_CONFIG): boolean {\n  // Need enough total bytes AND at least one valid EWMA sample\n  return state.bytesSampled >= config.minTotalBytes && state.fastTotalWeight > 0 && state.slowTotalWeight > 0;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAwDA,MAAa,2BAA4C;CACvD,cAAc;CACd,cAAc;CACd,eAAe;CACf,UAAU;CACV,aAAa;CACd;;;;;;;;;;;;;;;;;;;;;AAsBD,SAAgB,gBACd,OACA,YACA,UACA,SAA0B,0BACV;CAEhB,MAAM,sBAAsB,MAAM,eAAe;AAKjD,KAAI,WAAW,OAAO,SACpB,QAAO;EAAE,GAAG;EAAO,cAAc;EAAqB;AAMxD,KAAI,aAAa,OAAO,YACtB,QAAO;EAAE,GAAG;EAAO,cAAc;EAAqB;CAKxD,MAAM,YAAa,MAAO,WAAY;CAItC,MAAM,SAAS,aAAa;AAE5B,QAAO;EACL,cAAc,cAAc,MAAM,cAAc,WAAW,QAAQ,OAAO,aAAa;EACvF,iBAAiB,MAAM,kBAAkB;EACzC,cAAc,cAAc,MAAM,cAAc,WAAW,QAAQ,OAAO,aAAa;EACvF,iBAAiB,MAAM,kBAAkB;EACzC,cAAc;EACf;;;;;;;;;;;;;;;;;;;;AAqBH,SAAgB,qBACd,OACA,iBACA,SAA0B,0BAClB;AAER,KAAI,MAAM,eAAe,OAAO,cAC9B,QAAO;CAIT,MAAM,eAAe,gBAAgB,MAAM,cAAc,MAAM,iBAAiB,OAAO,aAAa;CAEpG,MAAM,eAAe,gBAAgB,MAAM,cAAc,MAAM,iBAAiB,OAAO,aAAa;AAIpG,QAAO,KAAK,IAAI,cAAc,aAAa"}
+{"version":3,"file":"bandwidth-estimator.js","names":[],"sources":["../../../../src/core/abr/bandwidth-estimator.ts"],"sourcesContent":["/**\n * Dual EWMA Bandwidth Estimator\n *\n * Estimates available bandwidth using two EWMA calculations with different\n * half-lives, taking the minimum of both. This approach (from Shaka Player):\n *\n * - **Fast EWMA** (2s half-life): Reacts quickly to bandwidth drops\n * - **Slow EWMA** (5s half-life): Provides stability during fluctuations\n * - **min(fast, slow)**: Adapts down quickly, up slowly\n *\n * This naturally provides asymmetric behavior needed for good QoE:\n * avoiding stalls (quick downgrade) while preventing oscillation (slow upgrade).\n */\n\nimport { applyZeroFactor, calculateEwma } from './ewma';\n\n/**\n * Bandwidth estimator state.\n *\n * This state structure will be managed by O1 (State Container).\n * Functions in this module operate on this state immutably.\n */\nexport interface BandwidthState {\n  /** Fast-moving EWMA estimate (raw, uncorrected). */\n  fastEstimate: number;\n  /** Total weight accumulated in fast EWMA. */\n  fastTotalWeight: number;\n  /** Slow-moving EWMA estimate (raw, uncorrected). */\n  slowEstimate: number;\n  /** Total weight accumulated in slow EWMA. */\n  slowTotalWeight: number;\n  /** Total bytes sampled across all valid samples. */\n  bytesSampled: number;\n}\n\n/**\n * Configuration for bandwidth estimation.\n */\nexport interface BandwidthConfig {\n  /** Half-life for fast EWMA in seconds. */\n  fastHalfLife: number;\n  /** Half-life for slow EWMA in seconds. */\n  slowHalfLife: number;\n  /** Minimum total bytes before trusting the estimate. */\n  minTotalBytes: number;\n  /** Minimum bytes per sample to count (filters TTFB-dominated samples). */\n  minBytes: number;\n  /** Minimum sample duration in ms (filters cached responses). */\n  minDuration: number;\n}\n\n/**\n * Default bandwidth estimator configuration.\n *\n * Values match Shaka Player defaults based on experimentation.\n */\nexport const DEFAULT_BANDWIDTH_CONFIG: BandwidthConfig = {\n  fastHalfLife: 2, // 2 seconds\n  slowHalfLife: 5, // 5 seconds\n  minTotalBytes: 128_000, // 128 KB\n  minBytes: 16_000, // 16 KB\n  minDuration: 5, // 5 ms\n};\n\n/**\n * Add a bandwidth sample from a segment download.\n *\n * Samples are filtered based on:\n * - Minimum bytes (filters TTFB-dominated small segments)\n * - Minimum duration (filters cached responses)\n *\n * Valid samples update both fast and slow EWMA estimates.\n *\n * @param state - Current estimator state\n * @param durationMs - Download duration in milliseconds\n * @param numBytes - Number of bytes downloaded\n * @param config - Optional estimator configuration (uses defaults if not provided)\n * @returns New estimator state with sample incorporated (or unchanged if filtered)\n *\n * @example\n * let state = { fastEstimate: 0, fastTotalWeight: 0, ... };\n * // Sample: 1MB in 1 second\n * state = sampleBandwidth(state, 1000, 1_000_000);\n */\nexport function sampleBandwidth(\n  state: BandwidthState,\n  durationMs: number,\n  numBytes: number,\n  config: BandwidthConfig = DEFAULT_BANDWIDTH_CONFIG\n): BandwidthState {\n  // Always track bytes for startup phase calculation\n  const updatedBytesSampled = state.bytesSampled + numBytes;\n\n  // Filter: Ignore samples below minimum bytes (TTFB-dominated)\n  // Small segments' download time is mostly connection setup latency,\n  // which would artificially lower our bandwidth estimate\n  if (numBytes < config.minBytes) {\n    return { ...state, bytesSampled: updatedBytesSampled };\n  }\n\n  // Filter: Ignore samples faster than minimum duration (cached responses)\n  // Cached responses load nearly instantly and would artificially inflate\n  // our bandwidth estimate\n  if (durationMs < config.minDuration) {\n    return { ...state, bytesSampled: updatedBytesSampled };\n  }\n\n  // Calculate bandwidth in bits per second\n  // Formula: (bytes * 8 bits/byte * 1000 ms/s) / ms = bits/s\n  const bandwidth = (8000 * numBytes) / durationMs;\n\n  // Weight by duration in seconds\n  // Longer downloads are more reliable indicators of true bandwidth\n  const weight = durationMs / 1000;\n\n  return {\n    fastEstimate: calculateEwma(state.fastEstimate, bandwidth, weight, config.fastHalfLife),\n    fastTotalWeight: state.fastTotalWeight + weight,\n    slowEstimate: calculateEwma(state.slowEstimate, bandwidth, weight, config.slowHalfLife),\n    slowTotalWeight: state.slowTotalWeight + weight,\n    bytesSampled: updatedBytesSampled,\n  };\n}\n\n/**\n * Get the current bandwidth estimate.\n *\n * Returns the **minimum** of the fast and slow EWMA estimates.\n * This provides the key asymmetric behavior:\n * - When bandwidth drops, fast EWMA reacts first and dominates (quick adaptation)\n * - When bandwidth rises, slow EWMA lags behind and dominates (slow adaptation)\n *\n * Uses default estimate until enough data has been sampled.\n *\n * @param state - Current estimator state\n * @param defaultEstimate - Fallback estimate before sufficient samples (bps)\n * @param config - Optional estimator configuration (uses defaults if not provided)\n * @returns Bandwidth estimate in bits per second\n *\n * @example\n * const estimate = getBandwidthEstimate(state, 5_000_000); // 5 Mbps default\n */\nexport function getBandwidthEstimate(\n  state: BandwidthState,\n  defaultEstimate: number,\n  config: BandwidthConfig = DEFAULT_BANDWIDTH_CONFIG\n): number {\n  // Use default until we have enough samples to trust our estimate\n  if (state.bytesSampled < config.minTotalBytes) {\n    return defaultEstimate;\n  }\n\n  // Apply zero-factor correction to both estimates\n  const fastEstimate = applyZeroFactor(state.fastEstimate, state.fastTotalWeight, config.fastHalfLife);\n\n  const slowEstimate = applyZeroFactor(state.slowEstimate, state.slowTotalWeight, config.slowHalfLife);\n\n  // Take the minimum - this is the key insight from Shaka Player\n  // It naturally provides \"down quickly, up slowly\" behavior\n  return Math.min(fastEstimate, slowEstimate);\n}\n\n/**\n * Check if the estimator has enough data to provide a reliable estimate.\n *\n * Requires both:\n * - Enough total bytes sampled (minTotalBytes threshold)\n * - At least one valid EWMA sample (totalWeight > 0)\n *\n * @param state - Current estimator state\n * @param config - Optional estimator configuration (uses defaults if not provided)\n * @returns True if we've sampled enough bytes to trust the estimate\n *\n * @example\n * if (hasGoodEstimate(state)) {\n *   const estimate = getBandwidthEstimate(state, 5_000_000);\n * }\n */\nexport function hasGoodEstimate(state: BandwidthState, config: BandwidthConfig = DEFAULT_BANDWIDTH_CONFIG): boolean {\n  // Need enough total bytes AND at least one valid EWMA sample\n  return state.bytesSampled >= config.minTotalBytes && state.fastTotalWeight > 0 && state.slowTotalWeight > 0;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAwDA,MAAa,2BAA4C;CACvD,cAAc;CACd,cAAc;CACd,eAAe;CACf,UAAU;CACV,aAAa;CACd;;;;;;;;;;;;;;;;;;;;;AAsBD,SAAgB,gBACd,OACA,YACA,UACA,SAA0B,0BACV;CAEhB,MAAM,sBAAsB,MAAM,eAAe;AAKjD,KAAI,WAAW,OAAO,SACpB,QAAO;EAAE,GAAG;EAAO,cAAc;EAAqB;AAMxD,KAAI,aAAa,OAAO,YACtB,QAAO;EAAE,GAAG;EAAO,cAAc;EAAqB;CAKxD,MAAM,YAAa,MAAO,WAAY;CAItC,MAAM,SAAS,aAAa;AAE5B,QAAO;EACL,cAAc,cAAc,MAAM,cAAc,WAAW,QAAQ,OAAO,aAAa;EACvF,iBAAiB,MAAM,kBAAkB;EACzC,cAAc,cAAc,MAAM,cAAc,WAAW,QAAQ,OAAO,aAAa;EACvF,iBAAiB,MAAM,kBAAkB;EACzC,cAAc;EACf;;;;;;;;;;;;;;;;;;;;AAqBH,SAAgB,qBACd,OACA,iBACA,SAA0B,0BAClB;AAER,KAAI,MAAM,eAAe,OAAO,cAC9B,QAAO;CAIT,MAAM,eAAe,gBAAgB,MAAM,cAAc,MAAM,iBAAiB,OAAO,aAAa;CAEpG,MAAM,eAAe,gBAAgB,MAAM,cAAc,MAAM,iBAAiB,OAAO,aAAa;AAIpG,QAAO,KAAK,IAAI,cAAc,aAAa"}

package/dist/default/core/abr/ewma.js

@@ -65,7 +65,7 @@ function applyZeroFactor(estimate, totalWeight, halfLife) {
 	if (totalWeight === 0) return 0;
 	return estimate / (1 - calculateAlpha(halfLife) ** totalWeight);
 }
-
 //#endregion
 export { applyZeroFactor, calculateEwma };
+
 //# sourceMappingURL=ewma.js.map

package/dist/default/core/abr/quality-selection.js

@@ -47,7 +47,7 @@ function selectQuality(tracks, currentBandwidth, config = DEFAULT_QUALITY_CONFIG
 function hasHigherResolution(trackA, trackB) {
 	return (trackA.width ?? 0) * (trackA.height ?? 0) > (trackB.width ?? 0) * (trackB.height ?? 0);
 }
-
 //#endregion
-export { DEFAULT_QUALITY_CONFIG, selectQuality };
+export { selectQuality };
+
 //# sourceMappingURL=quality-selection.js.map

package/dist/default/core/abr/quality-selection.js.map

@@ -1 +1 @@
-{"version":3,"file":"quality-selection.js","names":[],"sources":["../../../../src/core/abr/quality-selection.ts"],"sourcesContent":["/**\n * Quality Selection Algorithm\n *\n * Selects optimal video track based on bandwidth estimate with safety margin.\n * Stateless selection - picks highest quality that fits bandwidth.\n *\n * Key concepts:\n * - **Safety margin** (0.85): Pick track where bandwidth >= track.bandwidth / 0.85\n * - This ensures 15% headroom to avoid buffering\n * - At same bandwidth, prefer higher resolution\n */\n\nimport type { PartiallyResolvedVideoTrack } from '../types';\n\n/**\n * Quality selection configuration.\n */\nexport interface QualityConfig {\n  /**\n   * Safety margin (0-1).\n   * To select a track, need: currentBandwidth >= track.bandwidth / safetyMargin.\n   * Default 0.85 means track must use ≤85% of available bandwidth (15% headroom).\n   */\n  safetyMargin: number;\n}\n\n/**\n * Default quality selection configuration.\n * Values match Shaka Player upgrade threshold (0.85 = 15% headroom).\n */\nexport const DEFAULT_QUALITY_CONFIG: QualityConfig = {\n  safetyMargin: 0.85,\n};\n\n/**\n * Select the best video track based on current bandwidth estimate.\n *\n * Selects the highest quality track where bandwidth is sufficient with safety margin:\n * - currentBandwidth >= track.bandwidth / safetyMargin\n * - Default safetyMargin 0.85 means track uses ≤85% of bandwidth (15% headroom)\n * - At same bandwidth, prefers higher resolution\n *\n * @param tracks - Available video tracks (can be unsorted)\n * @param currentBandwidth - Current bandwidth estimate in bits per second\n * @param config - Optional quality selection configuration\n * @returns Selected track, or undefined if no tracks available\n *\n * @example\n * const tracks = [\n *   { id: '360p', bandwidth: 500_000, ... },\n *   { id: '720p', bandwidth: 2_000_000, ... },\n *   { id: '1080p', bandwidth: 4_000_000, ... },\n * ];\n *\n * // With 2.5 Mbps, selects 720p (1080p needs 4M/0.85 = 4.7 Mbps)\n * const selected = selectQuality(tracks, 2_500_000);\n */\nexport function selectQuality(\n  tracks: PartiallyResolvedVideoTrack[],\n  currentBandwidth: number,\n  config: QualityConfig = DEFAULT_QUALITY_CONFIG\n): PartiallyResolvedVideoTrack | undefined {\n  if (tracks.length === 0) {\n    return undefined;\n  }\n\n  // Sort tracks by bandwidth (lowest first)\n  const sortedTracks = tracks.slice().sort((a, b) => a.bandwidth - b.bandwidth);\n\n  // Start with no selection\n  let chosen: PartiallyResolvedVideoTrack | undefined;\n\n  for (const track of sortedTracks) {\n    // Check if we have enough bandwidth for this track with safety margin\n    // Required bandwidth = track.bandwidth / safetyMargin\n    const requiredBandwidth = track.bandwidth / config.safetyMargin;\n\n    if (currentBandwidth >= requiredBandwidth) {\n      // We can support this track - prefer it if better than current choice\n      if (\n        !chosen ||\n        track.bandwidth > chosen.bandwidth ||\n        (track.bandwidth === chosen.bandwidth && hasHigherResolution(track, chosen))\n      ) {\n        chosen = track;\n      }\n    }\n  }\n\n  // If no track fits with safety margin, fall back to lowest quality\n  return chosen ?? sortedTracks[0];\n}\n\n/**\n * Check if track A has higher resolution than track B.\n * Compares by total pixel count (width × height).\n *\n * @param trackA - First track to compare\n * @param trackB - Second track to compare\n * @returns True if trackA has more pixels than trackB\n */\nfunction hasHigherResolution(trackA: PartiallyResolvedVideoTrack, trackB: PartiallyResolvedVideoTrack): boolean {\n  const pixelsA = (trackA.width ?? 0) * (trackA.height ?? 0);\n  const pixelsB = (trackB.width ?? 0) * (trackB.height ?? 0);\n  return pixelsA > pixelsB;\n}\n"],"mappings":";;;;;AA8BA,MAAa,yBAAwC,EACnD,cAAc,KACf;;;;;;;;;;;;;;;;;;;;;;;;AAyBD,SAAgB,cACd,QACA,kBACA,SAAwB,wBACiB;AACzC,KAAI,OAAO,WAAW,EACpB;CAIF,MAAM,eAAe,OAAO,OAAO,CAAC,MAAM,GAAG,MAAM,EAAE,YAAY,EAAE,UAAU;CAG7E,IAAI;AAEJ,MAAK,MAAM,SAAS,aAKlB,KAAI,oBAFsB,MAAM,YAAY,OAAO,cAIjD;MACE,CAAC,UACD,MAAM,YAAY,OAAO,aACxB,MAAM,cAAc,OAAO,aAAa,oBAAoB,OAAO,OAAO,CAE3E,UAAS;;AAMf,QAAO,UAAU,aAAa;;;;;;;;;;AAWhC,SAAS,oBAAoB,QAAqC,QAA8C;AAG9G,SAFiB,OAAO,SAAS,MAAM,OAAO,UAAU,MACvC,OAAO,SAAS,MAAM,OAAO,UAAU"}
+{"version":3,"file":"quality-selection.js","names":[],"sources":["../../../../src/core/abr/quality-selection.ts"],"sourcesContent":["/**\n * Quality Selection Algorithm\n *\n * Selects optimal video track based on bandwidth estimate with safety margin.\n * Stateless selection - picks highest quality that fits bandwidth.\n *\n * Key concepts:\n * - **Safety margin** (0.85): Pick track where bandwidth >= track.bandwidth / 0.85\n * - This ensures 15% headroom to avoid buffering\n * - At same bandwidth, prefer higher resolution\n */\n\nimport type { PartiallyResolvedVideoTrack } from '../types';\n\n/**\n * Quality selection configuration.\n */\nexport interface QualityConfig {\n  /**\n   * Safety margin (0-1).\n   * To select a track, need: currentBandwidth >= track.bandwidth / safetyMargin.\n   * Default 0.85 means track must use ≤85% of available bandwidth (15% headroom).\n   */\n  safetyMargin: number;\n}\n\n/**\n * Default quality selection configuration.\n * Values match Shaka Player upgrade threshold (0.85 = 15% headroom).\n */\nexport const DEFAULT_QUALITY_CONFIG: QualityConfig = {\n  safetyMargin: 0.85,\n};\n\n/**\n * Select the best video track based on current bandwidth estimate.\n *\n * Selects the highest quality track where bandwidth is sufficient with safety margin:\n * - currentBandwidth >= track.bandwidth / safetyMargin\n * - Default safetyMargin 0.85 means track uses ≤85% of bandwidth (15% headroom)\n * - At same bandwidth, prefers higher resolution\n *\n * @param tracks - Available video tracks (can be unsorted)\n * @param currentBandwidth - Current bandwidth estimate in bits per second\n * @param config - Optional quality selection configuration\n * @returns Selected track, or undefined if no tracks available\n *\n * @example\n * const tracks = [\n *   { id: '360p', bandwidth: 500_000, ... },\n *   { id: '720p', bandwidth: 2_000_000, ... },\n *   { id: '1080p', bandwidth: 4_000_000, ... },\n * ];\n *\n * // With 2.5 Mbps, selects 720p (1080p needs 4M/0.85 = 4.7 Mbps)\n * const selected = selectQuality(tracks, 2_500_000);\n */\nexport function selectQuality(\n  tracks: PartiallyResolvedVideoTrack[],\n  currentBandwidth: number,\n  config: QualityConfig = DEFAULT_QUALITY_CONFIG\n): PartiallyResolvedVideoTrack | undefined {\n  if (tracks.length === 0) {\n    return undefined;\n  }\n\n  // Sort tracks by bandwidth (lowest first)\n  const sortedTracks = tracks.slice().sort((a, b) => a.bandwidth - b.bandwidth);\n\n  // Start with no selection\n  let chosen: PartiallyResolvedVideoTrack | undefined;\n\n  for (const track of sortedTracks) {\n    // Check if we have enough bandwidth for this track with safety margin\n    // Required bandwidth = track.bandwidth / safetyMargin\n    const requiredBandwidth = track.bandwidth / config.safetyMargin;\n\n    if (currentBandwidth >= requiredBandwidth) {\n      // We can support this track - prefer it if better than current choice\n      if (\n        !chosen ||\n        track.bandwidth > chosen.bandwidth ||\n        (track.bandwidth === chosen.bandwidth && hasHigherResolution(track, chosen))\n      ) {\n        chosen = track;\n      }\n    }\n  }\n\n  // If no track fits with safety margin, fall back to lowest quality\n  return chosen ?? sortedTracks[0];\n}\n\n/**\n * Check if track A has higher resolution than track B.\n * Compares by total pixel count (width × height).\n *\n * @param trackA - First track to compare\n * @param trackB - Second track to compare\n * @returns True if trackA has more pixels than trackB\n */\nfunction hasHigherResolution(trackA: PartiallyResolvedVideoTrack, trackB: PartiallyResolvedVideoTrack): boolean {\n  const pixelsA = (trackA.width ?? 0) * (trackA.height ?? 0);\n  const pixelsB = (trackB.width ?? 0) * (trackB.height ?? 0);\n  return pixelsA > pixelsB;\n}\n"],"mappings":";;;;;AA8BA,MAAa,yBAAwC,EACnD,cAAc,KACf;;;;;;;;;;;;;;;;;;;;;;;;AAyBD,SAAgB,cACd,QACA,kBACA,SAAwB,wBACiB;AACzC,KAAI,OAAO,WAAW,EACpB;CAIF,MAAM,eAAe,OAAO,OAAO,CAAC,MAAM,GAAG,MAAM,EAAE,YAAY,EAAE,UAAU;CAG7E,IAAI;AAEJ,MAAK,MAAM,SAAS,aAKlB,KAAI,oBAFsB,MAAM,YAAY,OAAO;MAK/C,CAAC,UACD,MAAM,YAAY,OAAO,aACxB,MAAM,cAAc,OAAO,aAAa,oBAAoB,OAAO,OAAO,CAE3E,UAAS;;AAMf,QAAO,UAAU,aAAa;;;;;;;;;;AAWhC,SAAS,oBAAoB,QAAqC,QAA8C;AAG9G,SAFiB,OAAO,SAAS,MAAM,OAAO,UAAU,MACvC,OAAO,SAAS,MAAM,OAAO,UAAU"}

package/dist/default/core/buffer/back-buffer.js

@@ -40,7 +40,7 @@ function calculateBackBufferFlushPoint(segments, currentTime, config = DEFAULT_B
 	if (segmentsToFlush >= segmentsBefore.length) return currentTime;
 	return segmentsBefore[segmentsToFlush].startTime;
 }
-
 //#endregion
-export { DEFAULT_BACK_BUFFER_CONFIG, calculateBackBufferFlushPoint };
+export { calculateBackBufferFlushPoint };
+
 //# sourceMappingURL=back-buffer.js.map

package/dist/default/core/buffer/forward-buffer.js

@@ -67,7 +67,7 @@ function getSegmentsToLoad(segments, bufferedSegments, currentTime, config = DEF
 		return isInRange && isNotBuffered;
 	});
 }
-
 //#endregion
 export { DEFAULT_FORWARD_BUFFER_CONFIG, calculateForwardFlushPoint, getSegmentsToLoad };
+
 //# sourceMappingURL=forward-buffer.js.map

package/dist/default/core/features/calculate-presentation-duration.js

@@ -1,7 +1,6 @@
+import { effect } from "../signals/effect.js";
 import { isResolvedTrack } from "../types/index.js";
-import { combineLatest } from "../reactive/combine-latest.js";
 import { getSelectedTrack } from "../utils/track-selection.js";
-
 //#region src/core/features/calculate-presentation-duration.ts
 /**
 * Check if we can calculate presentation duration (have required data).
@@ -34,18 +33,21 @@ function getDurationFromResolvedTracks(state) {
 * Calculate and set presentation duration from resolved tracks.
 */
 function calculatePresentationDuration({ state }) {
-	return combineLatest([state]).subscribe(([currentState]) => {
+	return effect(() => {
+		const currentState = state.get();
 		if (!shouldCalculateDuration(currentState)) return;
 		const duration = getDurationFromResolvedTracks(currentState);
 		if (duration === void 0 || !Number.isFinite(duration)) return;
-		const { presentation } = currentState;
-		state.patch({ presentation: {
-			...presentation,
-			duration
-		} });
+		state.set({
+			...currentState,
+			presentation: {
+				...currentState.presentation,
+				duration
+			}
+		});
 	});
 }
-
 //#endregion
 export { calculatePresentationDuration };
+
 //# sourceMappingURL=calculate-presentation-duration.js.map

package/dist/default/core/features/calculate-presentation-duration.js.map

@@ -1 +1 @@
-{"version":3,"file":"calculate-presentation-duration.js","names":[],"sources":["../../../../src/core/features/calculate-presentation-duration.ts"],"sourcesContent":["import { combineLatest } from '../reactive/combine-latest';\nimport type { WritableState } from '../state/create-state';\nimport type { AudioTrack, Presentation, VideoTrack } from '../types';\nimport { isResolvedTrack } from '../types';\nimport { getSelectedTrack } from '../utils/track-selection';\n\nexport interface PresentationDurationState {\n  presentation?: Presentation;\n  selectedVideoTrackId?: string;\n  selectedAudioTrackId?: string;\n}\n\n/**\n * Check if we can calculate presentation duration (have required data).\n */\nexport function canCalculateDuration(state: PresentationDurationState): boolean {\n  if (!state.presentation) return false;\n  // Need at least one selected track\n  return !!(state.selectedVideoTrackId || state.selectedAudioTrackId);\n}\n\n/**\n * Check if we should calculate presentation duration (conditions met).\n */\nexport function shouldCalculateDuration(state: PresentationDurationState): boolean {\n  if (!canCalculateDuration(state)) return false;\n\n  const { presentation } = state;\n\n  // Don't recalculate if already set\n  if (presentation!.duration !== undefined) return false;\n\n  // Check if any selected track is resolved\n  const videoTrack = state.selectedVideoTrackId ? getSelectedTrack(state, 'video') : undefined;\n  const audioTrack = state.selectedAudioTrackId ? getSelectedTrack(state, 'audio') : undefined;\n\n  // At least one track must be resolved (has segments and duration)\n  return !!((videoTrack && isResolvedTrack(videoTrack)) || (audioTrack && isResolvedTrack(audioTrack)));\n}\n\n/**\n * Get duration from the first resolved track (prefer video, fallback to audio).\n */\nexport function getDurationFromResolvedTracks(state: PresentationDurationState): number | undefined {\n  // Try video track first\n  const videoTrack = state.selectedVideoTrackId\n    ? (getSelectedTrack(state, 'video') as VideoTrack | undefined)\n    : undefined;\n  if (videoTrack && isResolvedTrack(videoTrack)) {\n    return videoTrack.duration;\n  }\n\n  // Fallback to audio track\n  const audioTrack = state.selectedAudioTrackId\n    ? (getSelectedTrack(state, 'audio') as AudioTrack | undefined)\n    : undefined;\n  if (audioTrack && isResolvedTrack(audioTrack)) {\n    return audioTrack.duration;\n  }\n\n  return undefined;\n}\n\n/**\n * Calculate and set presentation duration from resolved tracks.\n */\nexport function calculatePresentationDuration({\n  state,\n}: {\n  state: WritableState<PresentationDurationState>;\n}): () => void {\n  return combineLatest([state]).subscribe(([currentState]: [PresentationDurationState]) => {\n    if (!shouldCalculateDuration(currentState)) return;\n\n    const duration = getDurationFromResolvedTracks(currentState);\n    if (duration === undefined || !Number.isFinite(duration)) return;\n\n    const { presentation } = currentState;\n\n    // Patch presentation with duration\n    state.patch({\n      presentation: {\n        ...presentation!,\n        duration,\n      },\n    });\n  });\n}\n"],"mappings":";;;;;;;;AAeA,SAAgB,qBAAqB,OAA2C;AAC9E,KAAI,CAAC,MAAM,aAAc,QAAO;AAEhC,QAAO,CAAC,EAAE,MAAM,wBAAwB,MAAM;;;;;AAMhD,SAAgB,wBAAwB,OAA2C;AACjF,KAAI,CAAC,qBAAqB,MAAM,CAAE,QAAO;CAEzC,MAAM,EAAE,iBAAiB;AAGzB,KAAI,aAAc,aAAa,OAAW,QAAO;CAGjD,MAAM,aAAa,MAAM,uBAAuB,iBAAiB,OAAO,QAAQ,GAAG;CACnF,MAAM,aAAa,MAAM,uBAAuB,iBAAiB,OAAO,QAAQ,GAAG;AAGnF,QAAO,CAAC,EAAG,cAAc,gBAAgB,WAAW,IAAM,cAAc,gBAAgB,WAAW;;;;;AAMrG,SAAgB,8BAA8B,OAAsD;CAElG,MAAM,aAAa,MAAM,uBACpB,iBAAiB,OAAO,QAAQ,GACjC;AACJ,KAAI,cAAc,gBAAgB,WAAW,CAC3C,QAAO,WAAW;CAIpB,MAAM,aAAa,MAAM,uBACpB,iBAAiB,OAAO,QAAQ,GACjC;AACJ,KAAI,cAAc,gBAAgB,WAAW,CAC3C,QAAO,WAAW;;;;;AAStB,SAAgB,8BAA8B,EAC5C,SAGa;AACb,QAAO,cAAc,CAAC,MAAM,CAAC,CAAC,WAAW,CAAC,kBAA+C;AACvF,MAAI,CAAC,wBAAwB,aAAa,CAAE;EAE5C,MAAM,WAAW,8BAA8B,aAAa;AAC5D,MAAI,aAAa,UAAa,CAAC,OAAO,SAAS,SAAS,CAAE;EAE1D,MAAM,EAAE,iBAAiB;AAGzB,QAAM,MAAM,EACV,cAAc;GACZ,GAAG;GACH;GACD,EACF,CAAC;GACF"}
+{"version":3,"file":"calculate-presentation-duration.js","names":[],"sources":["../../../../src/core/features/calculate-presentation-duration.ts"],"sourcesContent":["import { effect } from '../signals/effect';\nimport type { Signal } from '../signals/primitives';\nimport type { AudioTrack, Presentation, VideoTrack } from '../types';\nimport { isResolvedTrack } from '../types';\nimport { getSelectedTrack } from '../utils/track-selection';\n\nexport interface PresentationDurationState {\n  presentation?: Presentation;\n  selectedVideoTrackId?: string;\n  selectedAudioTrackId?: string;\n}\n\n/**\n * Check if we can calculate presentation duration (have required data).\n */\nexport function canCalculateDuration(state: PresentationDurationState): boolean {\n  if (!state.presentation) return false;\n  // Need at least one selected track\n  return !!(state.selectedVideoTrackId || state.selectedAudioTrackId);\n}\n\n/**\n * Check if we should calculate presentation duration (conditions met).\n */\nexport function shouldCalculateDuration(state: PresentationDurationState): boolean {\n  if (!canCalculateDuration(state)) return false;\n\n  const { presentation } = state;\n\n  // Don't recalculate if already set\n  if (presentation!.duration !== undefined) return false;\n\n  // Check if any selected track is resolved\n  const videoTrack = state.selectedVideoTrackId ? getSelectedTrack(state, 'video') : undefined;\n  const audioTrack = state.selectedAudioTrackId ? getSelectedTrack(state, 'audio') : undefined;\n\n  // At least one track must be resolved (has segments and duration)\n  return !!((videoTrack && isResolvedTrack(videoTrack)) || (audioTrack && isResolvedTrack(audioTrack)));\n}\n\n/**\n * Get duration from the first resolved track (prefer video, fallback to audio).\n */\nexport function getDurationFromResolvedTracks(state: PresentationDurationState): number | undefined {\n  // Try video track first\n  const videoTrack = state.selectedVideoTrackId\n    ? (getSelectedTrack(state, 'video') as VideoTrack | undefined)\n    : undefined;\n  if (videoTrack && isResolvedTrack(videoTrack)) {\n    return videoTrack.duration;\n  }\n\n  // Fallback to audio track\n  const audioTrack = state.selectedAudioTrackId\n    ? (getSelectedTrack(state, 'audio') as AudioTrack | undefined)\n    : undefined;\n  if (audioTrack && isResolvedTrack(audioTrack)) {\n    return audioTrack.duration;\n  }\n\n  return undefined;\n}\n\n/**\n * Calculate and set presentation duration from resolved tracks.\n */\nexport function calculatePresentationDuration<S extends PresentationDurationState>({\n  state,\n}: {\n  state: Signal<S>;\n}): () => void {\n  return effect(() => {\n    const currentState = state.get();\n    if (!shouldCalculateDuration(currentState)) return;\n\n    const duration = getDurationFromResolvedTracks(currentState);\n    if (duration === undefined || !Number.isFinite(duration)) return;\n\n    state.set({\n      ...currentState,\n      presentation: {\n        ...currentState.presentation!,\n        duration,\n      },\n    } as S);\n  });\n}\n"],"mappings":";;;;;;;AAeA,SAAgB,qBAAqB,OAA2C;AAC9E,KAAI,CAAC,MAAM,aAAc,QAAO;AAEhC,QAAO,CAAC,EAAE,MAAM,wBAAwB,MAAM;;;;;AAMhD,SAAgB,wBAAwB,OAA2C;AACjF,KAAI,CAAC,qBAAqB,MAAM,CAAE,QAAO;CAEzC,MAAM,EAAE,iBAAiB;AAGzB,KAAI,aAAc,aAAa,KAAA,EAAW,QAAO;CAGjD,MAAM,aAAa,MAAM,uBAAuB,iBAAiB,OAAO,QAAQ,GAAG,KAAA;CACnF,MAAM,aAAa,MAAM,uBAAuB,iBAAiB,OAAO,QAAQ,GAAG,KAAA;AAGnF,QAAO,CAAC,EAAG,cAAc,gBAAgB,WAAW,IAAM,cAAc,gBAAgB,WAAW;;;;;AAMrG,SAAgB,8BAA8B,OAAsD;CAElG,MAAM,aAAa,MAAM,uBACpB,iBAAiB,OAAO,QAAQ,GACjC,KAAA;AACJ,KAAI,cAAc,gBAAgB,WAAW,CAC3C,QAAO,WAAW;CAIpB,MAAM,aAAa,MAAM,uBACpB,iBAAiB,OAAO,QAAQ,GACjC,KAAA;AACJ,KAAI,cAAc,gBAAgB,WAAW,CAC3C,QAAO,WAAW;;;;;AAStB,SAAgB,8BAAmE,EACjF,SAGa;AACb,QAAO,aAAa;EAClB,MAAM,eAAe,MAAM,KAAK;AAChC,MAAI,CAAC,wBAAwB,aAAa,CAAE;EAE5C,MAAM,WAAW,8BAA8B,aAAa;AAC5D,MAAI,aAAa,KAAA,KAAa,CAAC,OAAO,SAAS,SAAS,CAAE;AAE1D,QAAM,IAAI;GACR,GAAG;GACH,cAAc;IACZ,GAAG,aAAa;IAChB;IACD;GACF,CAAM;GACP"}

package/dist/default/core/features/quality-switching.js

@@ -1,6 +1,7 @@
 import { getBandwidthEstimate } from "../abr/bandwidth-estimator.js";
+import { effect } from "../signals/effect.js";
+import { update } from "../signals/primitives.js";
 import { selectQuality } from "../abr/quality-selection.js";
-
 //#region src/core/features/quality-switching.ts
 /**
 * Default quality switching configuration.
@@ -43,8 +44,8 @@ function switchQuality({ state }, config = {}) {
 	const defaultBandwidth = config.defaultBandwidth ?? DEFAULT_SWITCHING_CONFIG.defaultBandwidth;
 	let lastUpgradeTime = Date.now();
 	let firstMeaningfulFire = true;
-	return state.subscribe((currentState) => {
-		const { presentation, bandwidthState, selectedVideoTrackId, abrDisabled } = currentState;
+	return effect(() => {
+		const { presentation, bandwidthState, selectedVideoTrackId, abrDisabled } = state.get();
 		if (abrDisabled === true) return;
 		if (!presentation || !bandwidthState) return;
 		const videoTracks = getVideoTracks(presentation);
@@ -59,10 +60,10 @@ function switchQuality({ state }, config = {}) {
 			if (!isFirst && now - lastUpgradeTime < minUpgradeInterval) return;
 			lastUpgradeTime = now;
 		}
-		state.patch({ selectedVideoTrackId: optimal.id });
+		update(state, { selectedVideoTrackId: optimal.id });
 	});
 }
-
 //#endregion
-export { DEFAULT_SWITCHING_CONFIG, switchQuality };
+export { switchQuality };
+
 //# sourceMappingURL=quality-switching.js.map

package/dist/default/core/features/quality-switching.js.map

@@ -1 +1 @@
-{"version":3,"file":"quality-switching.js","names":[],"sources":["../../../../src/core/features/quality-switching.ts"],"sourcesContent":["import type { BandwidthState } from '../abr/bandwidth-estimator';\nimport { getBandwidthEstimate } from '../abr/bandwidth-estimator';\nimport { selectQuality } from '../abr/quality-selection';\nimport type { WritableState } from '../state/create-state';\nimport type { Presentation, VideoSelectionSet } from '../types';\n\n/**\n * State shape for quality switching.\n */\nexport interface QualitySwitchingState {\n  presentation?: Presentation;\n  bandwidthState?: BandwidthState;\n  selectedVideoTrackId?: string;\n  // TODO: abrDisabled is a blunt instrument — it requires callers to know they're\n  // competing with ABR and explicitly opt out. A better long-term design would\n  // separate ABR selection (abrVideoTrackId) from manual selection (manualVideoTrackId)\n  // and derive the effective selectedVideoTrackId as manualVideoTrackId ?? abrVideoTrackId.\n  // That way the two concerns never write to the same field and consumers are unchanged.\n  /** When true, ABR quality switching is suppressed. Use for manual quality selection. */\n  abrDisabled?: boolean;\n}\n\n/**\n * Configuration for quality switching behavior.\n */\nexport interface QualitySwitchingConfig {\n  /**\n   * Safety margin for quality selection (0–1).\n   * Track is selected only when bandwidth >= track.bandwidth / safetyMargin.\n   * Default: 0.85 (15% headroom).\n   */\n  safetyMargin?: number;\n\n  /**\n   * Minimum milliseconds between upgrades.\n   * Prevents oscillation when bandwidth fluctuates around a quality threshold.\n   * Downgrades are always immediate regardless of this setting.\n   * Default: 8000 (8 seconds).\n   */\n  minUpgradeInterval?: number;\n\n  /**\n   * Bandwidth estimate in bps to use before enough samples have been collected.\n   * Default: 5_000_000 (5 Mbps).\n   */\n  defaultBandwidth?: number;\n}\n\n/**\n * Default quality switching configuration.\n */\nexport const DEFAULT_SWITCHING_CONFIG: Required<QualitySwitchingConfig> = {\n  safetyMargin: 0.85,\n  minUpgradeInterval: 8000,\n  defaultBandwidth: 5_000_000,\n};\n\n/**\n * Get all video tracks from a presentation's first switching set.\n * Returns [] when the presentation is still unresolved (no selectionSets yet).\n */\nfunction getVideoTracks(presentation: Presentation) {\n  const videoSet = presentation.selectionSets?.find((s) => s.type === 'video') as VideoSelectionSet | undefined;\n  return videoSet?.switchingSets[0]?.tracks ?? [];\n}\n\n/**\n * Quality switching orchestration (F9).\n *\n * Reacts to bandwidth estimate changes and updates `selectedVideoTrackId`\n * when a different quality is optimal:\n *\n * - **Downgrades** happen immediately to avoid buffering stalls.\n * - **Upgrades** are gated by `minUpgradeInterval` to prevent oscillation.\n * - The first switch (from any track, or no track) is always immediate.\n *\n * Smooth switching is handled downstream: when `selectedVideoTrackId` changes,\n * `resolveTrack` fetches the new playlist and `loadSegments` reloads the init\n * segment, then appends media segments from the current position in the new\n * quality. The browser's SourceBuffer replaces the overlapping buffered range.\n *\n * @example\n * const cleanup = switchQuality({ state });\n * // Later, when done:\n * cleanup();\n */\nexport function switchQuality(\n  { state }: { state: WritableState<QualitySwitchingState> },\n  config: QualitySwitchingConfig = {}\n): () => void {\n  const safetyMargin = config.safetyMargin ?? DEFAULT_SWITCHING_CONFIG.safetyMargin;\n  const minUpgradeInterval = config.minUpgradeInterval ?? DEFAULT_SWITCHING_CONFIG.minUpgradeInterval;\n  const defaultBandwidth = config.defaultBandwidth ?? DEFAULT_SWITCHING_CONFIG.defaultBandwidth;\n\n  // Initialize to creation time so the interval starts counting immediately.\n  // The first time we have enough data to make a meaningful quality decision\n  // (presentation resolved + bandwidth available), the upgrade gate is skipped\n  // so the initial ABR correction does not wait for minUpgradeInterval.\n  let lastUpgradeTime = Date.now();\n  let firstMeaningfulFire = true;\n\n  return state.subscribe((currentState: QualitySwitchingState) => {\n    const { presentation, bandwidthState, selectedVideoTrackId, abrDisabled } = currentState;\n\n    if (abrDisabled === true) return;\n    if (!presentation || !bandwidthState) return;\n\n    const videoTracks = getVideoTracks(presentation);\n    if (videoTracks.length === 0) return;\n\n    // Consume the first-meaningful-fire flag now that we have all required data.\n    const isFirst = firstMeaningfulFire;\n    firstMeaningfulFire = false;\n\n    const bandwidth = getBandwidthEstimate(bandwidthState, defaultBandwidth);\n    const optimal = selectQuality(videoTracks as any, bandwidth, { safetyMargin });\n    if (!optimal || optimal.id === selectedVideoTrackId) return;\n\n    // Determine whether this is an upgrade or downgrade.\n    const currentTrack = videoTracks.find((t) => t.id === selectedVideoTrackId);\n    const isUpgrade = !currentTrack || optimal.bandwidth > currentTrack.bandwidth;\n\n    if (isUpgrade) {\n      const now = Date.now();\n      // Gate upgrades with minUpgradeInterval to prevent oscillation.\n      // Downgrades are always immediate; the first meaningful evaluation is always allowed.\n      if (!isFirst && now - lastUpgradeTime < minUpgradeInterval) return;\n      lastUpgradeTime = now;\n    }\n\n    state.patch({ selectedVideoTrackId: optimal.id });\n  });\n}\n"],"mappings":";;;;;;;AAmDA,MAAa,2BAA6D;CACxE,cAAc;CACd,oBAAoB;CACpB,kBAAkB;CACnB;;;;;AAMD,SAAS,eAAe,cAA4B;AAElD,SADiB,aAAa,eAAe,MAAM,MAAM,EAAE,SAAS,QAAQ,GAC3D,cAAc,IAAI,UAAU,EAAE;;;;;;;;;;;;;;;;;;;;;;AAuBjD,SAAgB,cACd,EAAE,SACF,SAAiC,EAAE,EACvB;CACZ,MAAM,eAAe,OAAO,gBAAgB,yBAAyB;CACrE,MAAM,qBAAqB,OAAO,sBAAsB,yBAAyB;CACjF,MAAM,mBAAmB,OAAO,oBAAoB,yBAAyB;CAM7E,IAAI,kBAAkB,KAAK,KAAK;CAChC,IAAI,sBAAsB;AAE1B,QAAO,MAAM,WAAW,iBAAwC;EAC9D,MAAM,EAAE,cAAc,gBAAgB,sBAAsB,gBAAgB;AAE5E,MAAI,gBAAgB,KAAM;AAC1B,MAAI,CAAC,gBAAgB,CAAC,eAAgB;EAEtC,MAAM,cAAc,eAAe,aAAa;AAChD,MAAI,YAAY,WAAW,EAAG;EAG9B,MAAM,UAAU;AAChB,wBAAsB;EAGtB,MAAM,UAAU,cAAc,aADZ,qBAAqB,gBAAgB,iBAAiB,EACX,EAAE,cAAc,CAAC;AAC9E,MAAI,CAAC,WAAW,QAAQ,OAAO,qBAAsB;EAGrD,MAAM,eAAe,YAAY,MAAM,MAAM,EAAE,OAAO,qBAAqB;AAG3E,MAFkB,CAAC,gBAAgB,QAAQ,YAAY,aAAa,WAErD;GACb,MAAM,MAAM,KAAK,KAAK;AAGtB,OAAI,CAAC,WAAW,MAAM,kBAAkB,mBAAoB;AAC5D,qBAAkB;;AAGpB,QAAM,MAAM,EAAE,sBAAsB,QAAQ,IAAI,CAAC;GACjD"}
+{"version":3,"file":"quality-switching.js","names":[],"sources":["../../../../src/core/features/quality-switching.ts"],"sourcesContent":["import type { BandwidthState } from '../abr/bandwidth-estimator';\nimport { getBandwidthEstimate } from '../abr/bandwidth-estimator';\nimport { selectQuality } from '../abr/quality-selection';\nimport { effect } from '../signals/effect';\nimport { type Signal, update } from '../signals/primitives';\nimport type { Presentation, VideoSelectionSet } from '../types';\n\n/**\n * State shape for quality switching.\n */\nexport interface QualitySwitchingState {\n  presentation?: Presentation;\n  bandwidthState?: BandwidthState;\n  selectedVideoTrackId?: string;\n  // TODO: abrDisabled is a blunt instrument — it requires callers to know they're\n  // competing with ABR and explicitly opt out. A better long-term design would\n  // separate ABR selection (abrVideoTrackId) from manual selection (manualVideoTrackId)\n  // and derive the effective selectedVideoTrackId as manualVideoTrackId ?? abrVideoTrackId.\n  // That way the two concerns never write to the same field and consumers are unchanged.\n  /** When true, ABR quality switching is suppressed. Use for manual quality selection. */\n  abrDisabled?: boolean;\n}\n\n/**\n * Configuration for quality switching behavior.\n */\nexport interface QualitySwitchingConfig {\n  /**\n   * Safety margin for quality selection (0–1).\n   * Track is selected only when bandwidth >= track.bandwidth / safetyMargin.\n   * Default: 0.85 (15% headroom).\n   */\n  safetyMargin?: number;\n\n  /**\n   * Minimum milliseconds between upgrades.\n   * Prevents oscillation when bandwidth fluctuates around a quality threshold.\n   * Downgrades are always immediate regardless of this setting.\n   * Default: 8000 (8 seconds).\n   */\n  minUpgradeInterval?: number;\n\n  /**\n   * Bandwidth estimate in bps to use before enough samples have been collected.\n   * Default: 5_000_000 (5 Mbps).\n   */\n  defaultBandwidth?: number;\n}\n\n/**\n * Default quality switching configuration.\n */\nexport const DEFAULT_SWITCHING_CONFIG: Required<QualitySwitchingConfig> = {\n  safetyMargin: 0.85,\n  minUpgradeInterval: 8000,\n  defaultBandwidth: 5_000_000,\n};\n\n/**\n * Get all video tracks from a presentation's first switching set.\n * Returns [] when the presentation is still unresolved (no selectionSets yet).\n */\nfunction getVideoTracks(presentation: Presentation) {\n  const videoSet = presentation.selectionSets?.find((s) => s.type === 'video') as VideoSelectionSet | undefined;\n  return videoSet?.switchingSets[0]?.tracks ?? [];\n}\n\n/**\n * Quality switching orchestration (F9).\n *\n * Reacts to bandwidth estimate changes and updates `selectedVideoTrackId`\n * when a different quality is optimal:\n *\n * - **Downgrades** happen immediately to avoid buffering stalls.\n * - **Upgrades** are gated by `minUpgradeInterval` to prevent oscillation.\n * - The first switch (from any track, or no track) is always immediate.\n *\n * Smooth switching is handled downstream: when `selectedVideoTrackId` changes,\n * `resolveTrack` fetches the new playlist and `loadSegments` reloads the init\n * segment, then appends media segments from the current position in the new\n * quality. The browser's SourceBuffer replaces the overlapping buffered range.\n *\n * @example\n * const cleanup = switchQuality({ state });\n * // Later, when done:\n * cleanup();\n */\nexport function switchQuality<S extends QualitySwitchingState>(\n  { state }: { state: Signal<S> },\n  config: QualitySwitchingConfig = {}\n): () => void {\n  const safetyMargin = config.safetyMargin ?? DEFAULT_SWITCHING_CONFIG.safetyMargin;\n  const minUpgradeInterval = config.minUpgradeInterval ?? DEFAULT_SWITCHING_CONFIG.minUpgradeInterval;\n  const defaultBandwidth = config.defaultBandwidth ?? DEFAULT_SWITCHING_CONFIG.defaultBandwidth;\n\n  // Initialize to creation time so the interval starts counting immediately.\n  // The first time we have enough data to make a meaningful quality decision\n  // (presentation resolved + bandwidth available), the upgrade gate is skipped\n  // so the initial ABR correction does not wait for minUpgradeInterval.\n  let lastUpgradeTime = Date.now();\n  let firstMeaningfulFire = true;\n\n  return effect(() => {\n    const currentState = state.get();\n    const { presentation, bandwidthState, selectedVideoTrackId, abrDisabled } = currentState;\n\n    if (abrDisabled === true) return;\n    if (!presentation || !bandwidthState) return;\n\n    const videoTracks = getVideoTracks(presentation);\n    if (videoTracks.length === 0) return;\n\n    // Consume the first-meaningful-fire flag now that we have all required data.\n    const isFirst = firstMeaningfulFire;\n    firstMeaningfulFire = false;\n\n    const bandwidth = getBandwidthEstimate(bandwidthState, defaultBandwidth);\n    const optimal = selectQuality(videoTracks as any, bandwidth, { safetyMargin });\n    if (!optimal || optimal.id === selectedVideoTrackId) return;\n\n    // Determine whether this is an upgrade or downgrade.\n    const currentTrack = videoTracks.find((t) => t.id === selectedVideoTrackId);\n    const isUpgrade = !currentTrack || optimal.bandwidth > currentTrack.bandwidth;\n\n    if (isUpgrade) {\n      const now = Date.now();\n      // Gate upgrades with minUpgradeInterval to prevent oscillation.\n      // Downgrades are always immediate; the first meaningful evaluation is always allowed.\n      if (!isFirst && now - lastUpgradeTime < minUpgradeInterval) return;\n      lastUpgradeTime = now;\n    }\n\n    const patch: Partial<QualitySwitchingState> = { selectedVideoTrackId: optimal.id };\n    update(state, patch);\n  });\n}\n"],"mappings":";;;;;;;;AAoDA,MAAa,2BAA6D;CACxE,cAAc;CACd,oBAAoB;CACpB,kBAAkB;CACnB;;;;;AAMD,SAAS,eAAe,cAA4B;AAElD,SADiB,aAAa,eAAe,MAAM,MAAM,EAAE,SAAS,QAAQ,GAC3D,cAAc,IAAI,UAAU,EAAE;;;;;;;;;;;;;;;;;;;;;;AAuBjD,SAAgB,cACd,EAAE,SACF,SAAiC,EAAE,EACvB;CACZ,MAAM,eAAe,OAAO,gBAAgB,yBAAyB;CACrE,MAAM,qBAAqB,OAAO,sBAAsB,yBAAyB;CACjF,MAAM,mBAAmB,OAAO,oBAAoB,yBAAyB;CAM7E,IAAI,kBAAkB,KAAK,KAAK;CAChC,IAAI,sBAAsB;AAE1B,QAAO,aAAa;EAElB,MAAM,EAAE,cAAc,gBAAgB,sBAAsB,gBADvC,MAAM,KAAK;AAGhC,MAAI,gBAAgB,KAAM;AAC1B,MAAI,CAAC,gBAAgB,CAAC,eAAgB;EAEtC,MAAM,cAAc,eAAe,aAAa;AAChD,MAAI,YAAY,WAAW,EAAG;EAG9B,MAAM,UAAU;AAChB,wBAAsB;EAGtB,MAAM,UAAU,cAAc,aADZ,qBAAqB,gBAAgB,iBAAiB,EACX,EAAE,cAAc,CAAC;AAC9E,MAAI,CAAC,WAAW,QAAQ,OAAO,qBAAsB;EAGrD,MAAM,eAAe,YAAY,MAAM,MAAM,EAAE,OAAO,qBAAqB;AAG3E,MAFkB,CAAC,gBAAgB,QAAQ,YAAY,aAAa,WAErD;GACb,MAAM,MAAM,KAAK,KAAK;AAGtB,OAAI,CAAC,WAAW,MAAM,kBAAkB,mBAAoB;AAC5D,qBAAkB;;AAIpB,SAAO,OADuC,EAAE,sBAAsB,QAAQ,IAAI,CAC9D;GACpB"}

package/dist/default/core/features/resolve-presentation.js

@@ -1,7 +1,7 @@
-import { parseMultivariantPlaylist } from "../hls/parse-multivariant.js";
+import { effect } from "../signals/effect.js";
+import { computed, update } from "../signals/primitives.js";
 import { fetchResolvable, getResponseText } from "../../dom/network/fetch.js";
-import { combineLatest } from "../reactive/combine-latest.js";
-
+import { parseMultivariantPlaylist } from "../hls/parse-multivariant.js";
 //#region src/core/features/resolve-presentation.ts
 /**
 * Type guard to check if presentation is unresolved.
@@ -13,87 +13,65 @@ function canResolve(state) {
 	return isUnresolved(state.presentation);
 }
 /**
-* Determines if resolution conditions are met based on preload policy and event.
+* Determines if resolution conditions are met based on preload policy and playback state.
 *
 * Resolution conditions:
 * - State-driven: preload is 'auto' or 'metadata'
-* - Event-driven: play event
+* - Playback-driven: playbackInitiated is true
 *
 * @param state - Current presentation state
-* @param event - Current action/event
 * @returns true if resolution conditions are met
 */
-function shouldResolve(state, event) {
-	const { preload } = state;
-	return ["auto", "metadata"].includes(preload) || event.type === "play";
-}
-/**
-* Syncs preload attribute from mediaElement to state.
-*
-* Watches the owners state for mediaElement changes and copies the
-* preload attribute to the immutable state.
-*
-* @param state - Immutable state container
-* @param owners - Mutable platform objects container
-* @returns Cleanup function to stop syncing
-*/
-function syncPreloadAttribute(state, owners) {
-	return owners.subscribe((current) => {
-		if (state.current.preload !== void 0) return;
-		const preload = current.mediaElement?.preload || void 0;
-		state.patch({ preload });
-	});
+function shouldResolve(state) {
+	const { preload, playbackInitiated } = state;
+	return ["auto", "metadata"].includes(preload) || !!playbackInitiated;
 }
 /**
 * Resolves unresolved presentations using reactive composition.
 *
-* Uses combineLatest to compose state + events, enabling both state-driven
-* and event-driven resolution triggers.
-*
 * Triggers resolution when:
 * - State-driven: Unresolved presentation + preload allows (auto/metadata)
-* - Event-driven: PLAY event when preload="none"
+* - Playback-driven: playbackInitiated is true
 *
 * @example
 * ```ts
-* const state = createState({ presentation: undefined, preload: 'auto' });
-* const events = createEventStream<PresentationAction>();
+* const state = signal({ presentation: undefined, preload: 'auto', playbackInitiated: false });
 *
-* const cleanup = resolvePresentation({ state, events });
+* const cleanup = resolvePresentation({ state });
 *
 * // State-driven: resolves immediately when preload allows
-* state.patch({ presentation: { url: 'http://example.com/playlist.m3u8' } });
+* state.set({ ...state.get(), presentation: { url: 'http://example.com/playlist.m3u8' } });
 *
-* // Event-driven: resolves on PLAY when preload="none"
-* state.patch({ preload: 'none', presentation: { url: '...' } });
-* events.dispatch({ type: 'PLAY' });
+* // Playback-driven: resolves when playbackInitiated is set
+* state.set({ ...state.get(), preload: 'none', presentation: { url: '...' }, playbackInitiated: true });
 * ```
 */
-function resolvePresentation({ state, events }) {
+function resolvePresentation({ state }) {
+	const canResolveSignal = computed(() => canResolve(state.get()));
+	const shouldResolveSignal = computed(() => shouldResolve(state.get()));
 	let resolving = false;
 	let abortController = null;
-	const cleanup = combineLatest([state, events]).subscribe(async ([currentState, event]) => {
-		if (!canResolve(currentState) || !shouldResolve(currentState, event) || resolving) return;
-		try {
-			resolving = true;
-			abortController = new AbortController();
-			const { presentation } = currentState;
-			const parsed = parseMultivariantPlaylist(await getResponseText(await fetchResolvable(presentation, { signal: abortController.signal })), presentation);
-			state.patch({ presentation: parsed });
-		} catch (error) {
+	const cleanupEffect = effect(() => {
+		if (!canResolveSignal.get() || !shouldResolveSignal.get() || resolving) return;
+		const presentation = state.get().presentation;
+		resolving = true;
+		abortController = new AbortController();
+		fetchResolvable(presentation, { signal: abortController.signal }).then((response) => getResponseText(response)).then((text) => {
+			update(state, { presentation: parseMultivariantPlaylist(text, presentation) });
+		}).catch((error) => {
 			if (error instanceof Error && error.name === "AbortError") return;
 			throw error;
-		} finally {
+		}).finally(() => {
 			resolving = false;
 			abortController = null;
-		}
+		});
 	});
 	return () => {
 		abortController?.abort();
-		cleanup();
+		cleanupEffect();
 	};
 }
-
 //#endregion
-export { canResolve, isUnresolved, resolvePresentation, shouldResolve, syncPreloadAttribute };
+export { resolvePresentation };
+
 //# sourceMappingURL=resolve-presentation.js.map

package/dist/default/core/features/resolve-presentation.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-presentation.js","names":[],"sources":["../../../../src/core/features/resolve-presentation.ts"],"sourcesContent":["import { fetchResolvable, getResponseText } from '../../dom/network/fetch';\nimport type { EventStream } from '../events/create-event-stream';\nimport { parseMultivariantPlaylist } from '../hls/parse-multivariant';\nimport { combineLatest } from '../reactive/combine-latest';\nimport type { WritableState } from '../state/create-state';\nimport type { AddressableObject, MediaElementLike, Presentation } from '../types';\n\n/**\n * Unresolved presentation - has a URL but no data yet.\n * Identical to AddressableObject per user requirement.\n */\nexport type UnresolvedPresentation = AddressableObject;\n\n/**\n * State shape for presentation resolution.\n */\nexport interface PresentationState {\n  presentation?: UnresolvedPresentation | Presentation | undefined;\n  preload?: 'auto' | 'metadata' | 'none' | undefined;\n}\n\n/**\n * Mutable platform objects.\n */\nexport interface PlatformOwners {\n  mediaElement?: MediaElementLike | undefined;\n}\n\n/**\n * Type guard to check if presentation is unresolved.\n */\nexport function isUnresolved(\n  presentation: UnresolvedPresentation | Presentation | undefined\n): presentation is UnresolvedPresentation {\n  return presentation !== undefined && 'url' in presentation && !('id' in presentation);\n}\n\nexport function canResolve(\n  state: PresentationState\n): state is PresentationState & { presentation: UnresolvedPresentation } {\n  return isUnresolved(state.presentation);\n}\n\n/**\n * Determines if resolution conditions are met based on preload policy and event.\n *\n * Resolution conditions:\n * - State-driven: preload is 'auto' or 'metadata'\n * - Event-driven: play event\n *\n * @param state - Current presentation state\n * @param event - Current action/event\n * @returns true if resolution conditions are met\n */\nexport function shouldResolve(state: PresentationState, event: PresentationAction): boolean {\n  const { preload } = state;\n  return (\n    // State-driven: preload allows (auto/metadata)\n    ['auto', 'metadata'].includes(preload as any) ||\n    // Event-driven: play event\n    event.type === 'play'\n  );\n}\n\n/**\n * Syncs preload attribute from mediaElement to state.\n *\n * Watches the owners state for mediaElement changes and copies the\n * preload attribute to the immutable state.\n *\n * @param state - Immutable state container\n * @param owners - Mutable platform objects container\n * @returns Cleanup function to stop syncing\n */\nexport function syncPreloadAttribute(\n  state: WritableState<PresentationState>,\n  owners: WritableState<PlatformOwners>\n): () => void {\n  return owners.subscribe((current) => {\n    // Only infer preload from the element when no explicit value has been set.\n    // An explicit value (set via SpfMedia.preload) always wins.\n    if (state.current.preload !== undefined) return;\n    const preload = current.mediaElement?.preload || undefined;\n    state.patch({ preload: preload as 'auto' | 'metadata' | 'none' | undefined });\n  });\n}\n\n/**\n * Action types for presentation resolution.\n * Event names match HTMLMediaElement events (lowercase).\n */\nexport type PresentationAction = { type: 'play' } | { type: 'pause' } | { type: 'load'; url: string };\n\n/**\n * Resolves unresolved presentations using reactive composition.\n *\n * Uses combineLatest to compose state + events, enabling both state-driven\n * and event-driven resolution triggers.\n *\n * Triggers resolution when:\n * - State-driven: Unresolved presentation + preload allows (auto/metadata)\n * - Event-driven: PLAY event when preload=\"none\"\n *\n * @example\n * ```ts\n * const state = createState({ presentation: undefined, preload: 'auto' });\n * const events = createEventStream<PresentationAction>();\n *\n * const cleanup = resolvePresentation({ state, events });\n *\n * // State-driven: resolves immediately when preload allows\n * state.patch({ presentation: { url: 'http://example.com/playlist.m3u8' } });\n *\n * // Event-driven: resolves on PLAY when preload=\"none\"\n * state.patch({ preload: 'none', presentation: { url: '...' } });\n * events.dispatch({ type: 'PLAY' });\n * ```\n */\nexport function resolvePresentation({\n  state,\n  events,\n}: {\n  state: WritableState<PresentationState>;\n  events: EventStream<PresentationAction>;\n}): () => void {\n  // This is effectively a very simple finite state model. We can formalize this if needed.\n  let resolving = false;\n  let abortController: AbortController | null = null;\n\n  const cleanup = combineLatest([state, events]).subscribe(async ([currentState, event]) => {\n    if (!canResolve(currentState) || !shouldResolve(currentState, event) || resolving) return;\n\n    try {\n      // This along with the resolving finite state (or more complex) could be pulled into its own abstraction.\n      // Set flag before async work\n      resolving = true;\n      abortController = new AbortController();\n\n      const { presentation } = currentState;\n      // Fetch and parse playlist\n      const response = await fetchResolvable(presentation, { signal: abortController.signal });\n      const text = await getResponseText(response);\n      const parsed = parseMultivariantPlaylist(text, presentation);\n\n      // Update state with resolved presentation\n      state.patch({\n        presentation: parsed,\n      });\n    } catch (error) {\n      // Ignore AbortError - this is expected when cleanup happens\n      if (error instanceof Error && error.name === 'AbortError') {\n        return;\n      }\n      throw error;\n    } finally {\n      // Always clear flag\n      resolving = false;\n      abortController = null;\n    }\n  });\n\n  // Return cleanup function that aborts pending fetches\n  return () => {\n    abortController?.abort();\n    cleanup();\n  };\n}\n"],"mappings":";;;;;;;;AA+BA,SAAgB,aACd,cACwC;AACxC,QAAO,iBAAiB,UAAa,SAAS,gBAAgB,EAAE,QAAQ;;AAG1E,SAAgB,WACd,OACuE;AACvE,QAAO,aAAa,MAAM,aAAa;;;;;;;;;;;;;AAczC,SAAgB,cAAc,OAA0B,OAAoC;CAC1F,MAAM,EAAE,YAAY;AACpB,QAEE,CAAC,QAAQ,WAAW,CAAC,SAAS,QAAe,IAE7C,MAAM,SAAS;;;;;;;;;;;;AAcnB,SAAgB,qBACd,OACA,QACY;AACZ,QAAO,OAAO,WAAW,YAAY;AAGnC,MAAI,MAAM,QAAQ,YAAY,OAAW;EACzC,MAAM,UAAU,QAAQ,cAAc,WAAW;AACjD,QAAM,MAAM,EAAW,SAAqD,CAAC;GAC7E;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCJ,SAAgB,oBAAoB,EAClC,OACA,UAIa;CAEb,IAAI,YAAY;CAChB,IAAI,kBAA0C;CAE9C,MAAM,UAAU,cAAc,CAAC,OAAO,OAAO,CAAC,CAAC,UAAU,OAAO,CAAC,cAAc,WAAW;AACxF,MAAI,CAAC,WAAW,aAAa,IAAI,CAAC,cAAc,cAAc,MAAM,IAAI,UAAW;AAEnF,MAAI;AAGF,eAAY;AACZ,qBAAkB,IAAI,iBAAiB;GAEvC,MAAM,EAAE,iBAAiB;GAIzB,MAAM,SAAS,0BADF,MAAM,gBADF,MAAM,gBAAgB,cAAc,EAAE,QAAQ,gBAAgB,QAAQ,CAAC,CAC5C,EACG,aAAa;AAG5D,SAAM,MAAM,EACV,cAAc,QACf,CAAC;WACK,OAAO;AAEd,OAAI,iBAAiB,SAAS,MAAM,SAAS,aAC3C;AAEF,SAAM;YACE;AAER,eAAY;AACZ,qBAAkB;;GAEpB;AAGF,cAAa;AACX,mBAAiB,OAAO;AACxB,WAAS"}
+{"version":3,"file":"resolve-presentation.js","names":[],"sources":["../../../../src/core/features/resolve-presentation.ts"],"sourcesContent":["import { fetchResolvable, getResponseText } from '../../dom/network/fetch';\nimport { parseMultivariantPlaylist } from '../hls/parse-multivariant';\nimport { effect } from '../signals/effect';\nimport { computed, type Signal, update } from '../signals/primitives';\nimport type { AddressableObject, Presentation } from '../types';\n\n/**\n * Unresolved presentation - has a URL but no data yet.\n * Identical to AddressableObject per user requirement.\n */\nexport type UnresolvedPresentation = AddressableObject;\n\n/**\n * State shape for presentation resolution.\n */\nexport interface PresentationState {\n  presentation?: UnresolvedPresentation | Presentation | undefined;\n  preload?: 'auto' | 'metadata' | 'none' | undefined;\n  /** True once the user has initiated playback — enables resolution regardless of preload. */\n  playbackInitiated?: boolean;\n}\n\n/**\n * Type guard to check if presentation is unresolved.\n */\nexport function isUnresolved(\n  presentation: UnresolvedPresentation | Presentation | undefined\n): presentation is UnresolvedPresentation {\n  return presentation !== undefined && 'url' in presentation && !('id' in presentation);\n}\n\nexport function canResolve(\n  state: PresentationState\n): state is PresentationState & { presentation: UnresolvedPresentation } {\n  return isUnresolved(state.presentation);\n}\n\n/**\n * Determines if resolution conditions are met based on preload policy and playback state.\n *\n * Resolution conditions:\n * - State-driven: preload is 'auto' or 'metadata'\n * - Playback-driven: playbackInitiated is true\n *\n * @param state - Current presentation state\n * @returns true if resolution conditions are met\n */\nexport function shouldResolve(state: PresentationState): boolean {\n  const { preload, playbackInitiated } = state;\n  return (\n    // State-driven: preload allows (auto/metadata)\n    ['auto', 'metadata'].includes(preload as any) ||\n    // Playback-driven: user has initiated playback\n    !!playbackInitiated\n  );\n}\n\n/**\n * Resolves unresolved presentations using reactive composition.\n *\n * Triggers resolution when:\n * - State-driven: Unresolved presentation + preload allows (auto/metadata)\n * - Playback-driven: playbackInitiated is true\n *\n * @example\n * ```ts\n * const state = signal({ presentation: undefined, preload: 'auto', playbackInitiated: false });\n *\n * const cleanup = resolvePresentation({ state });\n *\n * // State-driven: resolves immediately when preload allows\n * state.set({ ...state.get(), presentation: { url: 'http://example.com/playlist.m3u8' } });\n *\n * // Playback-driven: resolves when playbackInitiated is set\n * state.set({ ...state.get(), preload: 'none', presentation: { url: '...' }, playbackInitiated: true });\n * ```\n */\nexport function resolvePresentation<S extends PresentationState>({ state }: { state: Signal<S> }): () => void {\n  const canResolveSignal = computed(() => canResolve(state.get()));\n  const shouldResolveSignal = computed(() => shouldResolve(state.get()));\n\n  let resolving = false;\n  let abortController: AbortController | null = null;\n\n  const cleanupEffect = effect(() => {\n    if (!canResolveSignal.get() || !shouldResolveSignal.get() || resolving) return;\n\n    const presentation = state.get().presentation as UnresolvedPresentation;\n    resolving = true;\n    abortController = new AbortController();\n\n    fetchResolvable(presentation, { signal: abortController.signal })\n      .then((response) => getResponseText(response))\n      .then((text) => {\n        const parsed = parseMultivariantPlaylist(text, presentation);\n        const patch: Partial<PresentationState> = { presentation: parsed };\n        update(state, patch);\n      })\n      .catch((error) => {\n        if (error instanceof Error && error.name === 'AbortError') return;\n        throw error;\n      })\n      .finally(() => {\n        resolving = false;\n        abortController = null;\n      });\n  });\n\n  return () => {\n    abortController?.abort();\n    cleanupEffect();\n  };\n}\n"],"mappings":";;;;;;;;AAyBA,SAAgB,aACd,cACwC;AACxC,QAAO,iBAAiB,KAAA,KAAa,SAAS,gBAAgB,EAAE,QAAQ;;AAG1E,SAAgB,WACd,OACuE;AACvE,QAAO,aAAa,MAAM,aAAa;;;;;;;;;;;;AAazC,SAAgB,cAAc,OAAmC;CAC/D,MAAM,EAAE,SAAS,sBAAsB;AACvC,QAEE,CAAC,QAAQ,WAAW,CAAC,SAAS,QAAe,IAE7C,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;AAwBN,SAAgB,oBAAiD,EAAE,SAA2C;CAC5G,MAAM,mBAAmB,eAAe,WAAW,MAAM,KAAK,CAAC,CAAC;CAChE,MAAM,sBAAsB,eAAe,cAAc,MAAM,KAAK,CAAC,CAAC;CAEtE,IAAI,YAAY;CAChB,IAAI,kBAA0C;CAE9C,MAAM,gBAAgB,aAAa;AACjC,MAAI,CAAC,iBAAiB,KAAK,IAAI,CAAC,oBAAoB,KAAK,IAAI,UAAW;EAExE,MAAM,eAAe,MAAM,KAAK,CAAC;AACjC,cAAY;AACZ,oBAAkB,IAAI,iBAAiB;AAEvC,kBAAgB,cAAc,EAAE,QAAQ,gBAAgB,QAAQ,CAAC,CAC9D,MAAM,aAAa,gBAAgB,SAAS,CAAC,CAC7C,MAAM,SAAS;AAGd,UAAO,OADmC,EAAE,cAD7B,0BAA0B,MAAM,aAAa,EACM,CAC9C;IACpB,CACD,OAAO,UAAU;AAChB,OAAI,iBAAiB,SAAS,MAAM,SAAS,aAAc;AAC3D,SAAM;IACN,CACD,cAAc;AACb,eAAY;AACZ,qBAAkB;IAClB;GACJ;AAEF,cAAa;AACX,mBAAiB,OAAO;AACxB,iBAAe"}

package/dist/default/core/features/resolve-track.js

@@ -1,10 +1,9 @@
-import { parseMediaPlaylist } from "../hls/parse-media-playlist.js";
+import { effect } from "../signals/effect.js";
 import { isResolvedTrack } from "../types/index.js";
-import { fetchResolvable, getResponseText } from "../../dom/network/fetch.js";
-import { combineLatest } from "../reactive/combine-latest.js";
 import { getSelectedTrack } from "../utils/track-selection.js";
+import { fetchResolvable, getResponseText } from "../../dom/network/fetch.js";
+import { parseMediaPlaylist } from "../hls/parse-media-playlist.js";
 import { ConcurrentRunner, Task } from "../task.js";
-
 //#region src/core/features/resolve-track.ts
 function canResolve(state, config) {
 	const track = getSelectedTrack(state, config.type);
@@ -12,19 +11,6 @@ function canResolve(state, config) {
 	return !isResolvedTrack(track);
 }
 /**
-* Determines if track resolution conditions are met.
-*
-* Currently always returns true - conditions are checked by canResolveTrack()
-* and resolving flag. Kept as placeholder for future conditional logic.
-*
-* @param state - Current track resolution state
-* @param event - Current action/event
-* @returns true (conditions checked elsewhere)
-*/
-function shouldResolve(_state, _event) {
-	return true;
-}
-/**
 * Updates a track within a presentation (immutably).
 * Generic - works for video, audio, or text tracks.
 */
@@ -44,26 +30,29 @@ function updateTrackInPresentation(presentation, resolvedTrack) {
 /**
 * Resolves unresolved tracks using reactive composition.
 *
-* The subscribe closure is pure scheduling logic: it checks conditions and
-* creates a Task for the selected track when appropriate. The ConcurrentRunner
-* handles all concurrency concerns — deduplication, parallel execution, and
-* cleanup.
+* Reacts to state changes and schedules fetch tasks via ConcurrentRunner when
+* a selected track is unresolved. The ConcurrentRunner handles deduplication,
+* parallel execution, and cleanup.
 *
 * Generic version that works for video, audio, or text tracks based on config.
 * Type parameter T is inferred from config.type (use 'as const' for inference).
 */
-function resolveTrack({ state, events }, config) {
+function resolveTrack({ state }, config) {
 	const runner = new ConcurrentRunner();
-	const cleanup = combineLatest([state, events]).subscribe(([currentState, event]) => {
-		if (!canResolve(currentState, config) || !shouldResolve(currentState, event)) return;
+	const cleanup = effect(() => {
+		const currentState = state.get();
+		if (!canResolve(currentState, config)) return;
 		const track = getSelectedTrack(currentState, config.type);
 		if (!track) return;
 		const resolvedTrack = track;
 		runner.schedule(new Task(async (signal) => {
 			const mediaTrack = parseMediaPlaylist(await getResponseText(await fetchResolvable(resolvedTrack, { signal })), resolvedTrack);
-			const latestPresentation = state.current.presentation;
-			const updatedPresentation = updateTrackInPresentation(latestPresentation, mediaTrack);
-			state.patch({ presentation: updatedPresentation });
+			const latest = state.get();
+			const updatedPresentation = updateTrackInPresentation(latest.presentation, mediaTrack);
+			state.set({
+				...latest,
+				presentation: updatedPresentation
+			});
 		}, { id: track.id }));
 	});
 	return () => {
@@ -71,7 +60,7 @@ function resolveTrack({ state, events }, config) {
 		cleanup();
 	};
 }
-
 //#endregion
 export { resolveTrack };
+
 //# sourceMappingURL=resolve-track.js.map

package/dist/default/core/features/resolve-track.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-track.js","names":[],"sources":["../../../../src/core/features/resolve-track.ts"],"sourcesContent":["import { fetchResolvable, getResponseText } from '../../dom/network/fetch';\nimport type { EventStream } from '../events/create-event-stream';\nimport { parseMediaPlaylist } from '../hls/parse-media-playlist';\nimport { combineLatest } from '../reactive/combine-latest';\nimport type { WritableState } from '../state/create-state';\nimport { ConcurrentRunner, Task } from '../task';\nimport type { Presentation, ResolvedTrack, TrackType } from '../types';\nimport { isResolvedTrack } from '../types';\nimport { getSelectedTrack, type TrackSelectionState } from '../utils/track-selection';\n\n/**\n * State shape for track resolution.\n */\nexport interface TrackResolutionState extends TrackSelectionState {\n  presentation?: Presentation | undefined;\n  selectedVideoTrackId?: string | undefined;\n  selectedAudioTrackId?: string | undefined;\n  selectedTextTrackId?: string | undefined;\n}\n\nexport function canResolve<T extends TrackType>(\n  state: TrackResolutionState,\n  config: TrackResolutionConfig<T>\n): boolean {\n  const track = getSelectedTrack(state, config.type);\n  if (!track) return false;\n\n  return !isResolvedTrack(track);\n}\n\n/**\n * Determines if track resolution conditions are met.\n *\n * Currently always returns true - conditions are checked by canResolveTrack()\n * and resolving flag. Kept as placeholder for future conditional logic.\n *\n * @param state - Current track resolution state\n * @param event - Current action/event\n * @returns true (conditions checked elsewhere)\n */\nexport function shouldResolve(_state: TrackResolutionState, _event: TrackResolutionAction): boolean {\n  return true;\n}\n\n// ============================================================================\n// Public API\n// ============================================================================\n\n/**\n * Updates a track within a presentation (immutably).\n * Generic - works for video, audio, or text tracks.\n */\nexport function updateTrackInPresentation<T extends ResolvedTrack>(\n  presentation: Presentation,\n  resolvedTrack: T\n): Presentation {\n  const trackId = resolvedTrack.id;\n  return {\n    ...presentation,\n    selectionSets: presentation.selectionSets.map((selectionSet) => ({\n      ...selectionSet,\n      switchingSets: selectionSet.switchingSets.map((switchingSet) => ({\n        ...switchingSet,\n        tracks: switchingSet.tracks.map((track) => (track.id === trackId ? resolvedTrack : track)),\n      })),\n    })),\n  } as Presentation;\n}\n\n/**\n * Action types for track resolution.\n * Event names match HTMLMediaElement events (lowercase).\n */\nexport type TrackResolutionAction = { type: 'play' } | { type: 'pause' };\n\n/**\n * Configuration for track resolution.\n */\nexport interface TrackResolutionConfig<T extends TrackType = TrackType> {\n  type: T;\n}\n\n/**\n * Resolves unresolved tracks using reactive composition.\n *\n * The subscribe closure is pure scheduling logic: it checks conditions and\n * creates a Task for the selected track when appropriate. The ConcurrentRunner\n * handles all concurrency concerns — deduplication, parallel execution, and\n * cleanup.\n *\n * Generic version that works for video, audio, or text tracks based on config.\n * Type parameter T is inferred from config.type (use 'as const' for inference).\n */\nexport function resolveTrack<T extends TrackType>(\n  {\n    state,\n    events,\n  }: {\n    state: WritableState<TrackResolutionState>;\n    events: EventStream<TrackResolutionAction>;\n  },\n  config: TrackResolutionConfig<T>\n): () => void {\n  // NOTE: This can/maybe will be pulled into a per-use case factory (e.g. something like createTaskRunner() with args TBD),\n  // likely eventually passed down via config or a new \"definitions\" argument. This will allow us to decide if we want our task runner/scheduler\n  // to e.g. run concurrently (like we currently are), serially with a queue, or abort the previous task and replace it with the newly scheduled one. (CJP).\n  const runner = new ConcurrentRunner();\n\n  const cleanup = combineLatest([state, events]).subscribe(([currentState, event]) => {\n    if (!canResolve(currentState, config) || !shouldResolve(currentState, event)) return;\n\n    const track = getSelectedTrack(currentState, config.type);\n    if (!track) return;\n\n    const resolvedTrack = track;\n\n    runner.schedule(\n      // NOTE: This can/maybe will be pulled into a per-use case factory (e.g. something like createResolveTrackTask(track, context, config)),\n      // likely eventually passed down via config or a new \"definitions\" argument (CJP).\n      new Task(\n        async (signal) => {\n          const response = await fetchResolvable(resolvedTrack, { signal });\n          const text = await getResponseText(response);\n          const mediaTrack = parseMediaPlaylist(text, resolvedTrack);\n\n          // IMPORTANT: Read state.current.presentation at patch time, not from the\n          // captured currentState snapshot. Multiple Tasks may be running concurrently\n          // (one per track being resolved), so the snapshot is likely already stale by\n          // the time a task completes — a sibling task may have already patched the\n          // presentation with its own resolved track. Using the snapshot would overwrite\n          // that update and lose the other track's resolution. Reading live state ensures\n          // each task builds on top of whatever has been committed so far.\n          //\n          // This is a limitation of the current architecture: tasks receive a snapshot\n          // at scheduling time but need live state at write time. A future improvement\n          // could dispatch resolved tracks through a single serialised writer (e.g. a\n          // reducer pattern) to eliminate this hazard entirely.\n          const latestPresentation = state.current.presentation!;\n          const updatedPresentation = updateTrackInPresentation(latestPresentation, mediaTrack);\n          state.patch({ presentation: updatedPresentation });\n        },\n        { id: track.id }\n      )\n    );\n  });\n\n  return () => {\n    runner.abortAll();\n    cleanup();\n  };\n}\n"],"mappings":";;;;;;;;AAoBA,SAAgB,WACd,OACA,QACS;CACT,MAAM,QAAQ,iBAAiB,OAAO,OAAO,KAAK;AAClD,KAAI,CAAC,MAAO,QAAO;AAEnB,QAAO,CAAC,gBAAgB,MAAM;;;;;;;;;;;;AAahC,SAAgB,cAAc,QAA8B,QAAwC;AAClG,QAAO;;;;;;AAWT,SAAgB,0BACd,cACA,eACc;CACd,MAAM,UAAU,cAAc;AAC9B,QAAO;EACL,GAAG;EACH,eAAe,aAAa,cAAc,KAAK,kBAAkB;GAC/D,GAAG;GACH,eAAe,aAAa,cAAc,KAAK,kBAAkB;IAC/D,GAAG;IACH,QAAQ,aAAa,OAAO,KAAK,UAAW,MAAM,OAAO,UAAU,gBAAgB,MAAO;IAC3F,EAAE;GACJ,EAAE;EACJ;;;;;;;;;;;;;AA2BH,SAAgB,aACd,EACE,OACA,UAKF,QACY;CAIZ,MAAM,SAAS,IAAI,kBAAkB;CAErC,MAAM,UAAU,cAAc,CAAC,OAAO,OAAO,CAAC,CAAC,WAAW,CAAC,cAAc,WAAW;AAClF,MAAI,CAAC,WAAW,cAAc,OAAO,IAAI,CAAC,cAAc,cAAc,MAAM,CAAE;EAE9E,MAAM,QAAQ,iBAAiB,cAAc,OAAO,KAAK;AACzD,MAAI,CAAC,MAAO;EAEZ,MAAM,gBAAgB;AAEtB,SAAO,SAGL,IAAI,KACF,OAAO,WAAW;GAGhB,MAAM,aAAa,mBADN,MAAM,gBADF,MAAM,gBAAgB,eAAe,EAAE,QAAQ,CAAC,CACrB,EACA,cAAc;GAc1D,MAAM,qBAAqB,MAAM,QAAQ;GACzC,MAAM,sBAAsB,0BAA0B,oBAAoB,WAAW;AACrF,SAAM,MAAM,EAAE,cAAc,qBAAqB,CAAC;KAEpD,EAAE,IAAI,MAAM,IAAI,CACjB,CACF;GACD;AAEF,cAAa;AACX,SAAO,UAAU;AACjB,WAAS"}
+{"version":3,"file":"resolve-track.js","names":[],"sources":["../../../../src/core/features/resolve-track.ts"],"sourcesContent":["import { fetchResolvable, getResponseText } from '../../dom/network/fetch';\nimport { parseMediaPlaylist } from '../hls/parse-media-playlist';\nimport { effect } from '../signals/effect';\nimport type { Signal } from '../signals/primitives';\nimport { ConcurrentRunner, Task } from '../task';\nimport type { Presentation, ResolvedTrack, TrackType } from '../types';\nimport { isResolvedTrack } from '../types';\nimport { getSelectedTrack, type TrackSelectionState } from '../utils/track-selection';\n\n/**\n * State shape for track resolution.\n */\nexport interface TrackResolutionState extends TrackSelectionState {\n  presentation?: Presentation | undefined;\n  selectedVideoTrackId?: string | undefined;\n  selectedAudioTrackId?: string | undefined;\n  selectedTextTrackId?: string | undefined;\n}\n\nexport function canResolve<T extends TrackType>(\n  state: TrackResolutionState,\n  config: TrackResolutionConfig<T>\n): boolean {\n  const track = getSelectedTrack(state, config.type);\n  if (!track) return false;\n\n  return !isResolvedTrack(track);\n}\n\n// ============================================================================\n// Public API\n// ============================================================================\n\n/**\n * Updates a track within a presentation (immutably).\n * Generic - works for video, audio, or text tracks.\n */\nexport function updateTrackInPresentation<T extends ResolvedTrack>(\n  presentation: Presentation,\n  resolvedTrack: T\n): Presentation {\n  const trackId = resolvedTrack.id;\n  return {\n    ...presentation,\n    selectionSets: presentation.selectionSets.map((selectionSet) => ({\n      ...selectionSet,\n      switchingSets: selectionSet.switchingSets.map((switchingSet) => ({\n        ...switchingSet,\n        tracks: switchingSet.tracks.map((track) => (track.id === trackId ? resolvedTrack : track)),\n      })),\n    })),\n  } as Presentation;\n}\n\n/**\n * Configuration for track resolution.\n */\nexport interface TrackResolutionConfig<T extends TrackType = TrackType> {\n  type: T;\n}\n\n/**\n * Resolves unresolved tracks using reactive composition.\n *\n * Reacts to state changes and schedules fetch tasks via ConcurrentRunner when\n * a selected track is unresolved. The ConcurrentRunner handles deduplication,\n * parallel execution, and cleanup.\n *\n * Generic version that works for video, audio, or text tracks based on config.\n * Type parameter T is inferred from config.type (use 'as const' for inference).\n */\nexport function resolveTrack<S extends TrackResolutionState, T extends TrackType>(\n  { state }: { state: Signal<S> },\n  config: TrackResolutionConfig<T>\n): () => void {\n  // NOTE: This can/maybe will be pulled into a per-use case factory (e.g. something like createTaskRunner() with args TBD),\n  // likely eventually passed down via config or a new \"definitions\" argument. This will allow us to decide if we want our task runner/scheduler\n  // to e.g. run concurrently (like we currently are), serially with a queue, or abort the previous task and replace it with the newly scheduled one. (CJP).\n  const runner = new ConcurrentRunner();\n\n  const cleanup = effect(() => {\n    const currentState = state.get();\n    if (!canResolve(currentState, config)) return;\n\n    const track = getSelectedTrack(currentState, config.type);\n    if (!track) return;\n\n    const resolvedTrack = track;\n\n    runner.schedule(\n      // NOTE: This can/maybe will be pulled into a per-use case factory (e.g. something like createResolveTrackTask(track, context, config)),\n      // likely eventually passed down via config or a new \"definitions\" argument (CJP).\n      new Task(\n        async (signal) => {\n          const response = await fetchResolvable(resolvedTrack, { signal });\n          const text = await getResponseText(response);\n          const mediaTrack = parseMediaPlaylist(text, resolvedTrack);\n\n          // IMPORTANT: Read state.get().presentation at write time, not from the\n          // captured currentState snapshot. Multiple Tasks may be running concurrently\n          // (one per track being resolved), so the snapshot is likely already stale by\n          // the time a task completes — a sibling task may have already written the\n          // presentation with its own resolved track. Reading live state ensures each\n          // task builds on top of whatever has been committed so far.\n          const latest = state.get();\n          const updatedPresentation = updateTrackInPresentation(latest.presentation!, mediaTrack);\n          state.set({ ...latest, presentation: updatedPresentation } as S);\n        },\n        { id: track.id }\n      )\n    );\n  });\n\n  return () => {\n    runner.abortAll();\n    cleanup();\n  };\n}\n"],"mappings":";;;;;;;AAmBA,SAAgB,WACd,OACA,QACS;CACT,MAAM,QAAQ,iBAAiB,OAAO,OAAO,KAAK;AAClD,KAAI,CAAC,MAAO,QAAO;AAEnB,QAAO,CAAC,gBAAgB,MAAM;;;;;;AAWhC,SAAgB,0BACd,cACA,eACc;CACd,MAAM,UAAU,cAAc;AAC9B,QAAO;EACL,GAAG;EACH,eAAe,aAAa,cAAc,KAAK,kBAAkB;GAC/D,GAAG;GACH,eAAe,aAAa,cAAc,KAAK,kBAAkB;IAC/D,GAAG;IACH,QAAQ,aAAa,OAAO,KAAK,UAAW,MAAM,OAAO,UAAU,gBAAgB,MAAO;IAC3F,EAAE;GACJ,EAAE;EACJ;;;;;;;;;;;;AAoBH,SAAgB,aACd,EAAE,SACF,QACY;CAIZ,MAAM,SAAS,IAAI,kBAAkB;CAErC,MAAM,UAAU,aAAa;EAC3B,MAAM,eAAe,MAAM,KAAK;AAChC,MAAI,CAAC,WAAW,cAAc,OAAO,CAAE;EAEvC,MAAM,QAAQ,iBAAiB,cAAc,OAAO,KAAK;AACzD,MAAI,CAAC,MAAO;EAEZ,MAAM,gBAAgB;AAEtB,SAAO,SAGL,IAAI,KACF,OAAO,WAAW;GAGhB,MAAM,aAAa,mBADN,MAAM,gBADF,MAAM,gBAAgB,eAAe,EAAE,QAAQ,CAAC,CACrB,EACA,cAAc;GAQ1D,MAAM,SAAS,MAAM,KAAK;GAC1B,MAAM,sBAAsB,0BAA0B,OAAO,cAAe,WAAW;AACvF,SAAM,IAAI;IAAE,GAAG;IAAQ,cAAc;IAAqB,CAAM;KAElE,EAAE,IAAI,MAAM,IAAI,CACjB,CACF;GACD;AAEF,cAAa;AACX,SAAO,UAAU;AACjB,WAAS"}