@videojs/spf 10.0.0-beta.2 → 10.0.0-beta.22

package/README.md

@@ -1,51 +1,27 @@
 # @videojs/spf
 
-Stream Processing Framework for Video.js 10
+[![package-badge]][package]
 
-## Overview
-
-SPF is a lightweight, bundle-size-optimized HLS playback engine for Video.js 10.
-
-**Target:** < 20KB (minified + gzipped)  
-**Target Date:** February 27, 2026  
-**Status:** Active development
-
-## V1 Feature Set
-
-- CMAF HLS VOD playback
-- Basic ABR (EWMA throughput)
-- WebVTT captions
-- MSE + MMS support
-- Chrome, Safari, Firefox, Edge (latest)
+> **⚠️ Beta** Experimental adoption in real projects.
 
-## Development
-
-```bash
-# Install dependencies
-pnpm install
-
-# Run tests
-pnpm test
-
-# Build
-pnpm build
+## Overview
 
-# Typecheck
-pnpm typecheck
-```
+`@videojs/spf` is a lightweight, bundle-size-optimized streaming engine for Video.js 10. It provides
+HLS playback with adaptive bitrate switching, WebVTT captions, and MSE support.
 
-## Documentation
+## Community
 
-See `.claude/spf-breakdown/` for:
-- Complete work breakdown (58 issues)
-- Architecture decisions
-- Implementation timeline
+If you need help with anything related to Video.js 10, or if you'd like to casually chat with other
+members:
 
-## Reference
+- [Join Discord Server][discord]
+- [See GitHub Discussions][gh-discussions]
 
-Spike code available in `.archive/spf-xstate-poc/` for pattern reference.
+## License
 
-## GitHub Issues
+[Apache-2.0](./LICENSE)
 
-- Epics: #384, #385, #386, #387
-- All issues: https://github.com/videojs/v10/issues?q=is:issue+label:spf
+[package]: https://www.npmjs.com/package/@videojs/spf
+[package-badge]: https://img.shields.io/npm/v/@videojs/spf?label=@videojs/spf
+[discord]: https://discord.gg/JBqHh485uF
+[gh-discussions]: https://github.com/videojs/v10/discussions

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

@@ -0,0 +1,95 @@
+import { applyZeroFactor, calculateEwma } from "./ewma.js";
+//#region src/core/abr/bandwidth-estimator.ts
+/**
+* Dual EWMA Bandwidth Estimator
+*
+* Estimates available bandwidth using two EWMA calculations with different
+* half-lives, taking the minimum of both. This approach (from Shaka Player):
+*
+* - **Fast EWMA** (2s half-life): Reacts quickly to bandwidth drops
+* - **Slow EWMA** (5s half-life): Provides stability during fluctuations
+* - **min(fast, slow)**: Adapts down quickly, up slowly
+*
+* This naturally provides asymmetric behavior needed for good QoE:
+* avoiding stalls (quick downgrade) while preventing oscillation (slow upgrade).
+*/
+/**
+* Default bandwidth estimator configuration.
+*
+* Values match Shaka Player defaults based on experimentation.
+*/
+const DEFAULT_BANDWIDTH_CONFIG = {
+	fastHalfLife: 2,
+	slowHalfLife: 5,
+	minTotalBytes: 128e3,
+	minBytes: 16e3,
+	minDuration: 5
+};
+/**
+* Add a bandwidth sample from a segment download.
+*
+* Samples are filtered based on:
+* - Minimum bytes (filters TTFB-dominated small segments)
+* - Minimum duration (filters cached responses)
+*
+* Valid samples update both fast and slow EWMA estimates.
+*
+* @param state - Current estimator state
+* @param durationMs - Download duration in milliseconds
+* @param numBytes - Number of bytes downloaded
+* @param config - Optional estimator configuration (uses defaults if not provided)
+* @returns New estimator state with sample incorporated (or unchanged if filtered)
+*
+* @example
+* let state = { fastEstimate: 0, fastTotalWeight: 0, ... };
+* // Sample: 1MB in 1 second
+* state = sampleBandwidth(state, 1000, 1_000_000);
+*/
+function sampleBandwidth(state, durationMs, numBytes, config = DEFAULT_BANDWIDTH_CONFIG) {
+	const updatedBytesSampled = state.bytesSampled + numBytes;
+	if (numBytes < config.minBytes) return {
+		...state,
+		bytesSampled: updatedBytesSampled
+	};
+	if (durationMs < config.minDuration) return {
+		...state,
+		bytesSampled: updatedBytesSampled
+	};
+	const bandwidth = 8e3 * numBytes / durationMs;
+	const weight = durationMs / 1e3;
+	return {
+		fastEstimate: calculateEwma(state.fastEstimate, bandwidth, weight, config.fastHalfLife),
+		fastTotalWeight: state.fastTotalWeight + weight,
+		slowEstimate: calculateEwma(state.slowEstimate, bandwidth, weight, config.slowHalfLife),
+		slowTotalWeight: state.slowTotalWeight + weight,
+		bytesSampled: updatedBytesSampled
+	};
+}
+/**
+* Get the current bandwidth estimate.
+*
+* Returns the **minimum** of the fast and slow EWMA estimates.
+* This provides the key asymmetric behavior:
+* - When bandwidth drops, fast EWMA reacts first and dominates (quick adaptation)
+* - When bandwidth rises, slow EWMA lags behind and dominates (slow adaptation)
+*
+* Uses default estimate until enough data has been sampled.
+*
+* @param state - Current estimator state
+* @param defaultEstimate - Fallback estimate before sufficient samples (bps)
+* @param config - Optional estimator configuration (uses defaults if not provided)
+* @returns Bandwidth estimate in bits per second
+*
+* @example
+* const estimate = getBandwidthEstimate(state, 5_000_000); // 5 Mbps default
+*/
+function getBandwidthEstimate(state, defaultEstimate, config = DEFAULT_BANDWIDTH_CONFIG) {
+	if (state.bytesSampled < config.minTotalBytes) return defaultEstimate;
+	const fastEstimate = applyZeroFactor(state.fastEstimate, state.fastTotalWeight, config.fastHalfLife);
+	const slowEstimate = applyZeroFactor(state.slowEstimate, state.slowTotalWeight, config.slowHalfLife);
+	return Math.min(fastEstimate, slowEstimate);
+}
+//#endregion
+export { getBandwidthEstimate, sampleBandwidth };
+
+//# sourceMappingURL=bandwidth-estimator.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,71 @@
+//#region src/core/abr/ewma.ts
+/**
+* Exponentially Weighted Moving Average (EWMA)
+*
+* Pure functional implementation of EWMA calculations.
+* Based on Shaka Player's EWMA algorithm.
+*/
+/**
+* Calculate alpha (decay factor) from half-life.
+*
+* Alpha determines how quickly old data "expires":
+* - alpha close to 1 = slow decay (long memory)
+* - alpha close to 0 = fast decay (short memory)
+*
+* @param halfLife - The quantity of prior samples (by weight) that make up
+*   half of the new estimate. Must be positive.
+* @returns Alpha value between 0 and 1
+*
+* @example
+* const alpha = calculateAlpha(2); // ≈ 0.7071 for 2-second half-life
+*/
+function calculateAlpha(halfLife) {
+	return Math.exp(Math.log(.5) / halfLife);
+}
+/**
+* Calculate exponentially weighted moving average.
+*
+* Updates an estimate by blending a new value with the previous estimate,
+* weighted by the sample duration. Longer samples have more influence.
+*
+* @param prevEstimate - Previous EWMA estimate
+* @param value - New sample value to incorporate
+* @param weight - Sample weight (typically duration in seconds)
+* @param halfLife - Half-life for decay (typically 2-5 seconds)
+* @returns Updated EWMA estimate
+*
+* @example
+* let estimate = 0;
+* estimate = calculateEwma(estimate, 1_000_000, 1, 2); // First sample
+* estimate = calculateEwma(estimate, 2_000_000, 1, 2); // Second sample
+*/
+function calculateEwma(prevEstimate, value, weight, halfLife) {
+	const adjAlpha = calculateAlpha(halfLife) ** weight;
+	return value * (1 - adjAlpha) + adjAlpha * prevEstimate;
+}
+/**
+* Apply zero-factor correction to EWMA estimate.
+*
+* The zero-factor correction compensates for bias when starting from zero.
+* Without this correction, early estimates would be artificially low.
+*
+* As totalWeight increases, the correction factor approaches 1, meaning
+* the estimate becomes more reliable and needs less correction.
+*
+* @param estimate - Raw EWMA estimate (uncorrected)
+* @param totalWeight - Accumulated weight from all samples
+* @param halfLife - Half-life used in EWMA calculation
+* @returns Corrected estimate, or 0 if totalWeight is 0
+*
+* @example
+* const raw = calculateEwma(0, 1_000_000, 1, 2);
+* const corrected = applyZeroFactor(raw, 1, 2); // ≈ 1_000_000
+*/
+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/ewma.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ewma.js","names":[],"sources":["../../../../src/core/abr/ewma.ts"],"sourcesContent":["/**\n * Exponentially Weighted Moving Average (EWMA)\n *\n * Pure functional implementation of EWMA calculations.\n * Based on Shaka Player's EWMA algorithm.\n */\n\n/**\n * Calculate alpha (decay factor) from half-life.\n *\n * Alpha determines how quickly old data \"expires\":\n * - alpha close to 1 = slow decay (long memory)\n * - alpha close to 0 = fast decay (short memory)\n *\n * @param halfLife - The quantity of prior samples (by weight) that make up\n *   half of the new estimate. Must be positive.\n * @returns Alpha value between 0 and 1\n *\n * @example\n * const alpha = calculateAlpha(2); // ≈ 0.7071 for 2-second half-life\n */\nexport function calculateAlpha(halfLife: number): number {\n  return Math.exp(Math.log(0.5) / halfLife);\n}\n\n/**\n * Calculate exponentially weighted moving average.\n *\n * Updates an estimate by blending a new value with the previous estimate,\n * weighted by the sample duration. Longer samples have more influence.\n *\n * @param prevEstimate - Previous EWMA estimate\n * @param value - New sample value to incorporate\n * @param weight - Sample weight (typically duration in seconds)\n * @param halfLife - Half-life for decay (typically 2-5 seconds)\n * @returns Updated EWMA estimate\n *\n * @example\n * let estimate = 0;\n * estimate = calculateEwma(estimate, 1_000_000, 1, 2); // First sample\n * estimate = calculateEwma(estimate, 2_000_000, 1, 2); // Second sample\n */\nexport function calculateEwma(prevEstimate: number, value: number, weight: number, halfLife: number): number {\n  const alpha = calculateAlpha(halfLife);\n  const adjAlpha = alpha ** weight;\n  return value * (1 - adjAlpha) + adjAlpha * prevEstimate;\n}\n\n/**\n * Apply zero-factor correction to EWMA estimate.\n *\n * The zero-factor correction compensates for bias when starting from zero.\n * Without this correction, early estimates would be artificially low.\n *\n * As totalWeight increases, the correction factor approaches 1, meaning\n * the estimate becomes more reliable and needs less correction.\n *\n * @param estimate - Raw EWMA estimate (uncorrected)\n * @param totalWeight - Accumulated weight from all samples\n * @param halfLife - Half-life used in EWMA calculation\n * @returns Corrected estimate, or 0 if totalWeight is 0\n *\n * @example\n * const raw = calculateEwma(0, 1_000_000, 1, 2);\n * const corrected = applyZeroFactor(raw, 1, 2); // ≈ 1_000_000\n */\nexport function applyZeroFactor(estimate: number, totalWeight: number, halfLife: number): number {\n  if (totalWeight === 0) {\n    return 0;\n  }\n\n  const alpha = calculateAlpha(halfLife);\n  const zeroFactor = 1 - alpha ** totalWeight;\n  return estimate / zeroFactor;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,eAAe,UAA0B;AACvD,QAAO,KAAK,IAAI,KAAK,IAAI,GAAI,GAAG,SAAS;;;;;;;;;;;;;;;;;;;AAoB3C,SAAgB,cAAc,cAAsB,OAAe,QAAgB,UAA0B;CAE3G,MAAM,WADQ,eAAe,SAAS,IACZ;AAC1B,QAAO,SAAS,IAAI,YAAY,WAAW;;;;;;;;;;;;;;;;;;;;AAqB7C,SAAgB,gBAAgB,UAAkB,aAAqB,UAA0B;AAC/F,KAAI,gBAAgB,EAClB,QAAO;AAKT,QAAO,YADY,IADL,eAAe,SAAS,IACN"}

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

@@ -0,0 +1,53 @@
+//#region src/core/abr/quality-selection.ts
+/**
+* Default quality selection configuration.
+* Values match Shaka Player upgrade threshold (0.85 = 15% headroom).
+*/
+const DEFAULT_QUALITY_CONFIG = { safetyMargin: .85 };
+/**
+* Select the best video track based on current bandwidth estimate.
+*
+* Selects the highest quality track where bandwidth is sufficient with safety margin:
+* - currentBandwidth >= track.bandwidth / safetyMargin
+* - Default safetyMargin 0.85 means track uses ≤85% of bandwidth (15% headroom)
+* - At same bandwidth, prefers higher resolution
+*
+* @param tracks - Available video tracks (can be unsorted)
+* @param currentBandwidth - Current bandwidth estimate in bits per second
+* @param config - Optional quality selection configuration
+* @returns Selected track, or undefined if no tracks available
+*
+* @example
+* const tracks = [
+*   { id: '360p', bandwidth: 500_000, ... },
+*   { id: '720p', bandwidth: 2_000_000, ... },
+*   { id: '1080p', bandwidth: 4_000_000, ... },
+* ];
+*
+* // With 2.5 Mbps, selects 720p (1080p needs 4M/0.85 = 4.7 Mbps)
+* const selected = selectQuality(tracks, 2_500_000);
+*/
+function selectQuality(tracks, currentBandwidth, config = DEFAULT_QUALITY_CONFIG) {
+	if (tracks.length === 0) return;
+	const sortedTracks = tracks.slice().sort((a, b) => a.bandwidth - b.bandwidth);
+	let chosen;
+	for (const track of sortedTracks) if (currentBandwidth >= track.bandwidth / config.safetyMargin) {
+		if (!chosen || track.bandwidth > chosen.bandwidth || track.bandwidth === chosen.bandwidth && hasHigherResolution(track, chosen)) chosen = track;
+	}
+	return chosen ?? sortedTracks[0];
+}
+/**
+* Check if track A has higher resolution than track B.
+* Compares by total pixel count (width × height).
+*
+* @param trackA - First track to compare
+* @param trackB - Second track to compare
+* @returns True if trackA has more pixels than trackB
+*/
+function hasHigherResolution(trackA, trackB) {
+	return (trackA.width ?? 0) * (trackA.height ?? 0) > (trackB.width ?? 0) * (trackB.height ?? 0);
+}
+//#endregion
+export { selectQuality };
+
+//# sourceMappingURL=quality-selection.js.map

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

@@ -0,0 +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;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

@@ -0,0 +1,46 @@
+//#region src/core/buffer/back-buffer.ts
+/**
+* Default back buffer configuration.
+*/
+const DEFAULT_BACK_BUFFER_CONFIG = { keepSegments: 2 };
+/**
+* Calculate back buffer flush point.
+*
+* Determines where to flush old segments from the back buffer.
+* Keeps a fixed number of segments behind the current playback position.
+*
+* Algorithm:
+* 1. Find segments before currentTime
+* 2. Count back N segments (keepSegments)
+* 3. Return startTime of segment N+1 back (flush everything before this)
+*
+* @param segments - Available segments (should be sorted by startTime)
+* @param currentTime - Current playback position in seconds
+* @param config - Optional back buffer configuration
+* @returns Time in seconds to flush up to (flush range: [0, flushEnd))
+*
+* @example
+* const segments = [
+*   { startTime: 0, duration: 6, ... },
+*   { startTime: 6, duration: 6, ... },
+*   { startTime: 12, duration: 6, ... },
+*   { startTime: 18, duration: 6, ... },
+* ];
+*
+* // Playing at 18s, keep 2 segments
+* const flushEnd = calculateBackBufferFlushPoint(segments, 18);
+* // Returns 6 (flush [0, 6), keep [6-18))
+*/
+function calculateBackBufferFlushPoint(segments, currentTime, config = DEFAULT_BACK_BUFFER_CONFIG) {
+	if (segments.length === 0) return 0;
+	const segmentsBefore = segments.filter((seg) => seg.startTime < currentTime);
+	if (segmentsBefore.length === 0) return 0;
+	const segmentsToFlush = segmentsBefore.length - config.keepSegments;
+	if (segmentsToFlush <= 0) return 0;
+	if (segmentsToFlush >= segmentsBefore.length) return currentTime;
+	return segmentsBefore[segmentsToFlush].startTime;
+}
+//#endregion
+export { calculateBackBufferFlushPoint };
+
+//# sourceMappingURL=back-buffer.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"back-buffer.js","names":[],"sources":["../../../../src/core/buffer/back-buffer.ts"],"sourcesContent":["/**\n * Back Buffer Strategy (Simple)\n *\n * Calculates flush points for back buffer management.\n * V1 uses simple \"keep N segments\" strategy.\n */\n\nimport type { Segment } from '../types';\n\n/**\n * Back buffer configuration.\n */\nexport interface BackBufferConfig {\n  /**\n   * Number of segments to keep behind current playback position.\n   * Default: 2 segments.\n   */\n  keepSegments: number;\n}\n\n/**\n * Default back buffer configuration.\n */\nexport const DEFAULT_BACK_BUFFER_CONFIG: BackBufferConfig = {\n  keepSegments: 2,\n};\n\n/**\n * Calculate back buffer flush point.\n *\n * Determines where to flush old segments from the back buffer.\n * Keeps a fixed number of segments behind the current playback position.\n *\n * Algorithm:\n * 1. Find segments before currentTime\n * 2. Count back N segments (keepSegments)\n * 3. Return startTime of segment N+1 back (flush everything before this)\n *\n * @param segments - Available segments (should be sorted by startTime)\n * @param currentTime - Current playback position in seconds\n * @param config - Optional back buffer configuration\n * @returns Time in seconds to flush up to (flush range: [0, flushEnd))\n *\n * @example\n * const segments = [\n *   { startTime: 0, duration: 6, ... },\n *   { startTime: 6, duration: 6, ... },\n *   { startTime: 12, duration: 6, ... },\n *   { startTime: 18, duration: 6, ... },\n * ];\n *\n * // Playing at 18s, keep 2 segments\n * const flushEnd = calculateBackBufferFlushPoint(segments, 18);\n * // Returns 6 (flush [0, 6), keep [6-18))\n */\nexport function calculateBackBufferFlushPoint(\n  segments: Segment[],\n  currentTime: number,\n  config: BackBufferConfig = DEFAULT_BACK_BUFFER_CONFIG\n): number {\n  if (segments.length === 0) {\n    return 0;\n  }\n\n  // Find all segments before current time (not including current segment)\n  const segmentsBefore = segments.filter((seg) => seg.startTime < currentTime);\n\n  // If no segments before current time, nothing to flush\n  if (segmentsBefore.length === 0) {\n    return 0;\n  }\n\n  // Calculate how many segments to flush\n  // Keep last N segments, flush the rest\n  const segmentsToFlush = segmentsBefore.length - config.keepSegments;\n\n  // If we don't have enough segments to flush, keep everything\n  if (segmentsToFlush <= 0) {\n    return 0;\n  }\n\n  // If we want to flush all segments, return currentTime\n  // (flush everything before current playback position)\n  if (segmentsToFlush >= segmentsBefore.length) {\n    return currentTime;\n  }\n\n  // Return the startTime of the first segment we want to keep\n  // Everything before this will be flushed\n  return segmentsBefore[segmentsToFlush]!.startTime;\n}\n"],"mappings":";;;;AAuBA,MAAa,6BAA+C,EAC1D,cAAc,GACf;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BD,SAAgB,8BACd,UACA,aACA,SAA2B,4BACnB;AACR,KAAI,SAAS,WAAW,EACtB,QAAO;CAIT,MAAM,iBAAiB,SAAS,QAAQ,QAAQ,IAAI,YAAY,YAAY;AAG5E,KAAI,eAAe,WAAW,EAC5B,QAAO;CAKT,MAAM,kBAAkB,eAAe,SAAS,OAAO;AAGvD,KAAI,mBAAmB,EACrB,QAAO;AAKT,KAAI,mBAAmB,eAAe,OACpC,QAAO;AAKT,QAAO,eAAe,iBAAkB"}

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

@@ -0,0 +1,73 @@
+//#region src/core/buffer/forward-buffer.ts
+/**
+* Default forward buffer configuration.
+*/
+const DEFAULT_FORWARD_BUFFER_CONFIG = { bufferDuration: 30 };
+/**
+* Get segments that need to be loaded for forward buffer.
+*
+* Determines which segments to load to maintain target buffer duration.
+* Handles discontiguous buffering (gaps after seeks).
+*
+* Algorithm:
+* 1. Calculate target time: currentTime + bufferDuration
+* 2. Find all segments in range [currentTime, targetTime)
+* 3. Filter out segments already buffered at that time position
+* 4. Return segments to load (fills gaps + extends to target)
+*
+* @param segments - All available segments from playlist
+* @param bufferedSegments - Segments already buffered (ordered by startTime)
+* @param currentTime - Current playback position in seconds
+* @param config - Optional forward buffer configuration
+* @returns Array of segments to load (empty if buffer is sufficient)
+*
+* @example
+* // After seek: buffered [0-12, 18-30], playing at 7s
+* const toLoad = getSegmentsToLoad(segments, buffered, 7, { bufferDuration: 24 });
+* // Returns [seg-12, seg-30] (fills gap, extends to target 31s)
+*/
+/**
+* Calculate the start time from which to flush forward buffer content.
+*
+* Content that starts at or beyond `currentTime + bufferDuration` is no
+* longer needed for the current playback position and should be removed
+* from the SourceBuffer. This prevents unbounded accumulation of scattered
+* SourceBuffer content after seeks, which can cause QuotaExceededError on
+* long-form content.
+*
+* Returns `Infinity` when nothing needs flushing (no buffered segments
+* exist beyond the threshold).
+*
+* @param bufferedSegments - Segments currently tracked in the buffer model
+* @param currentTime - Current playback position in seconds
+* @param config - Optional forward buffer configuration
+* @returns Start time to flush from (flush range: [flushStart, Infinity)),
+*          or Infinity if no flush is needed
+*
+* @example
+* // Playing at 0s, buffered [0,6,12,18,24,30,36], bufferDuration=30
+* const flushStart = calculateForwardFlushPoint(segments, 0);
+* // Returns 30 — flush [30, Infinity), keep [0, 30)
+*/
+function calculateForwardFlushPoint(bufferedSegments, currentTime, config = DEFAULT_FORWARD_BUFFER_CONFIG) {
+	if (bufferedSegments.length === 0) return Infinity;
+	const threshold = currentTime + config.bufferDuration;
+	const beyond = bufferedSegments.filter((seg) => seg.startTime >= threshold);
+	if (beyond.length === 0) return Infinity;
+	return Math.min(...beyond.map((seg) => seg.startTime));
+}
+function getSegmentsToLoad(segments, bufferedSegments, currentTime, config = DEFAULT_FORWARD_BUFFER_CONFIG) {
+	if (segments.length === 0) return [];
+	const targetTime = currentTime + config.bufferDuration;
+	const bufferedStartTimes = new Set(bufferedSegments.map((seg) => seg.startTime));
+	return segments.filter((seg) => {
+		const segmentEnd = seg.startTime + seg.duration;
+		const isInRange = seg.startTime < targetTime && segmentEnd > currentTime;
+		const isNotBuffered = !bufferedStartTimes.has(seg.startTime);
+		return isInRange && isNotBuffered;
+	});
+}
+//#endregion
+export { DEFAULT_FORWARD_BUFFER_CONFIG, calculateForwardFlushPoint, getSegmentsToLoad };
+
+//# sourceMappingURL=forward-buffer.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"forward-buffer.js","names":[],"sources":["../../../../src/core/buffer/forward-buffer.ts"],"sourcesContent":["/**\n * Forward Buffer Strategy (Simple)\n *\n * Determines which segments to load for forward buffer management.\n * V1 uses simple fixed-duration strategy (buffer N seconds ahead).\n */\n\nimport type { Segment } from '../types';\n\n/**\n * Forward buffer configuration.\n */\nexport interface ForwardBufferConfig {\n  /**\n   * Duration in seconds to buffer ahead of current playback position.\n   * Default: 30 seconds.\n   */\n  bufferDuration: number;\n}\n\n/**\n * Default forward buffer configuration.\n */\nexport const DEFAULT_FORWARD_BUFFER_CONFIG: ForwardBufferConfig = {\n  bufferDuration: 30,\n};\n\n/**\n * Get segments that need to be loaded for forward buffer.\n *\n * Determines which segments to load to maintain target buffer duration.\n * Handles discontiguous buffering (gaps after seeks).\n *\n * Algorithm:\n * 1. Calculate target time: currentTime + bufferDuration\n * 2. Find all segments in range [currentTime, targetTime)\n * 3. Filter out segments already buffered at that time position\n * 4. Return segments to load (fills gaps + extends to target)\n *\n * @param segments - All available segments from playlist\n * @param bufferedSegments - Segments already buffered (ordered by startTime)\n * @param currentTime - Current playback position in seconds\n * @param config - Optional forward buffer configuration\n * @returns Array of segments to load (empty if buffer is sufficient)\n *\n * @example\n * // After seek: buffered [0-12, 18-30], playing at 7s\n * const toLoad = getSegmentsToLoad(segments, buffered, 7, { bufferDuration: 24 });\n * // Returns [seg-12, seg-30] (fills gap, extends to target 31s)\n */\n/**\n * Calculate the start time from which to flush forward buffer content.\n *\n * Content that starts at or beyond `currentTime + bufferDuration` is no\n * longer needed for the current playback position and should be removed\n * from the SourceBuffer. This prevents unbounded accumulation of scattered\n * SourceBuffer content after seeks, which can cause QuotaExceededError on\n * long-form content.\n *\n * Returns `Infinity` when nothing needs flushing (no buffered segments\n * exist beyond the threshold).\n *\n * @param bufferedSegments - Segments currently tracked in the buffer model\n * @param currentTime - Current playback position in seconds\n * @param config - Optional forward buffer configuration\n * @returns Start time to flush from (flush range: [flushStart, Infinity)),\n *          or Infinity if no flush is needed\n *\n * @example\n * // Playing at 0s, buffered [0,6,12,18,24,30,36], bufferDuration=30\n * const flushStart = calculateForwardFlushPoint(segments, 0);\n * // Returns 30 — flush [30, Infinity), keep [0, 30)\n */\nexport function calculateForwardFlushPoint(\n  bufferedSegments: readonly Segment[],\n  currentTime: number,\n  config: ForwardBufferConfig = DEFAULT_FORWARD_BUFFER_CONFIG\n): number {\n  if (bufferedSegments.length === 0) return Infinity;\n\n  const threshold = currentTime + config.bufferDuration;\n\n  // Find segments that start at or beyond the threshold\n  const beyond = bufferedSegments.filter((seg) => seg.startTime >= threshold);\n\n  if (beyond.length === 0) return Infinity;\n\n  // Flush from the earliest such segment onward\n  return Math.min(...beyond.map((seg) => seg.startTime));\n}\n\nexport function getSegmentsToLoad(\n  segments: readonly Segment[],\n  bufferedSegments: readonly Pick<Segment, 'startTime' | 'duration'>[],\n  currentTime: number,\n  config: ForwardBufferConfig = DEFAULT_FORWARD_BUFFER_CONFIG\n): Segment[] {\n  if (segments.length === 0) {\n    return [];\n  }\n\n  // Calculate target buffer end time\n  const targetTime = currentTime + config.bufferDuration;\n\n  // Create set of buffered segment start times for fast lookup\n  // V1 simple: if ANY segment is buffered at a given time, don't load for that time\n  // V2 (future): would compare by startTime + bitrate/track for quality switching\n  const bufferedStartTimes = new Set(bufferedSegments.map((seg) => seg.startTime));\n\n  // Find segments to load:\n  // - Overlaps buffer window [currentTime, targetTime)\n  // - Not already buffered at that time position\n  const toLoad = segments.filter((seg) => {\n    // Segment must overlap the buffer window\n    const segmentEnd = seg.startTime + seg.duration;\n    const isInRange = seg.startTime < targetTime && segmentEnd > currentTime;\n\n    // Must not have a segment buffered at this time position\n    const isNotBuffered = !bufferedStartTimes.has(seg.startTime);\n\n    return isInRange && isNotBuffered;\n  });\n\n  return toLoad;\n}\n"],"mappings":";;;;AAuBA,MAAa,gCAAqD,EAChE,gBAAgB,IACjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgDD,SAAgB,2BACd,kBACA,aACA,SAA8B,+BACtB;AACR,KAAI,iBAAiB,WAAW,EAAG,QAAO;CAE1C,MAAM,YAAY,cAAc,OAAO;CAGvC,MAAM,SAAS,iBAAiB,QAAQ,QAAQ,IAAI,aAAa,UAAU;AAE3E,KAAI,OAAO,WAAW,EAAG,QAAO;AAGhC,QAAO,KAAK,IAAI,GAAG,OAAO,KAAK,QAAQ,IAAI,UAAU,CAAC;;AAGxD,SAAgB,kBACd,UACA,kBACA,aACA,SAA8B,+BACnB;AACX,KAAI,SAAS,WAAW,EACtB,QAAO,EAAE;CAIX,MAAM,aAAa,cAAc,OAAO;CAKxC,MAAM,qBAAqB,IAAI,IAAI,iBAAiB,KAAK,QAAQ,IAAI,UAAU,CAAC;AAgBhF,QAXe,SAAS,QAAQ,QAAQ;EAEtC,MAAM,aAAa,IAAI,YAAY,IAAI;EACvC,MAAM,YAAY,IAAI,YAAY,cAAc,aAAa;EAG7D,MAAM,gBAAgB,CAAC,mBAAmB,IAAI,IAAI,UAAU;AAE5D,SAAO,aAAa;GACpB"}

package/dist/default/core/create-machine-actor.js

@@ -0,0 +1,91 @@
+import { untrack, update } from "./signals/primitives.js";
+import { createMachineCore } from "./machine.js";
+//#region src/core/create-machine-actor.ts
+/**
+* Creates a message-driven actor from a declarative definition.
+*
+* The actor owns a reactive snapshot signal (state + context), an optional
+* runner, and dispatches incoming messages to per-state handlers. `'destroyed'`
+* is always the implicit terminal state — `destroy()` transitions there
+* unconditionally and all subsequent `send()` calls are no-ops.
+*
+* When a state declares `onSettled`, the framework calls `runner.whenSettled()`
+* after the handler returns. The runner owns the generation-token logic — if
+* new tasks are scheduled before the current batch settles, the callback is
+* automatically superseded.
+*
+* @example
+* const actor = createMachineActor({
+*   runner: () => new SerialRunner(),
+*   initial: 'idle',
+*   context: {},
+*   states: {
+*     idle: {
+*       on: {
+*         load: (msg, { transition, runner }) => {
+*           segments.forEach(s => runner.schedule(new Task(...)));
+*           transition('loading');
+*         }
+*       }
+*     },
+*     loading: {
+*       onSettled: 'idle',
+*       on: {
+*         load: (msg, { runner }) => {
+*           runner.abortAll();
+*           segments.forEach(s => runner.schedule(new Task(...)));
+*         }
+*       }
+*     }
+*   }
+* });
+*/
+function createMachineActor(def) {
+	const runner = def.runner?.();
+	const { snapshotSignal, getState, transition } = createMachineCore({
+		value: def.initial,
+		context: def.context
+	});
+	const getContext = () => untrack(() => snapshotSignal.get().context);
+	const setContext = (context) => {
+		update(snapshotSignal, { context });
+	};
+	return {
+		get snapshot() {
+			return snapshotSignal;
+		},
+		send(message) {
+			const state = getState();
+			if (state === "destroyed") return;
+			const handler = def.states[state]?.on?.[message.type];
+			if (!handler) return;
+			handler(message, {
+				context: getContext(),
+				getContext,
+				transition: (to) => transition(to),
+				setContext,
+				...runner ? { runner } : {}
+			});
+			const newState = getState();
+			if (newState !== "destroyed") {
+				const newStateDef = def.states[newState];
+				if (newStateDef?.onSettled && runner) {
+					const targetState = newStateDef.onSettled;
+					runner.whenSettled(() => {
+						if (getState() !== newState) return;
+						transition(targetState);
+					});
+				}
+			}
+		},
+		destroy() {
+			if (getState() === "destroyed") return;
+			runner?.destroy();
+			transition("destroyed");
+		}
+	};
+}
+//#endregion
+export { createMachineActor };
+
+//# sourceMappingURL=create-machine-actor.js.map

package/dist/default/core/create-machine-actor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-machine-actor.js","names":[],"sources":["../../../src/core/create-machine-actor.ts"],"sourcesContent":["import type { ActorSnapshot, SignalActor } from './actor';\nimport { createMachineCore } from './machine';\nimport { untrack, update } from './signals/primitives';\nimport type { TaskLike } from './task';\n\n// =============================================================================\n// Runner interfaces\n// =============================================================================\n\n/**\n * Minimal interface for any runner that can be used with createMachineActor.\n */\nexport interface RunnerLike {\n  schedule<Value = void, Err = unknown>(task: TaskLike<Value, Err>): Promise<Value>;\n  abortAll(): void;\n  destroy(): void;\n  whenSettled(callback: () => void): void;\n}\n\n// =============================================================================\n// Definition types\n// =============================================================================\n\n/**\n * Context passed to message handlers.\n * `runner` is present and typed as the exact runner instance only when the\n * definition includes a runner factory.\n */\nexport type HandlerContext<\n  UserState extends string,\n  Context extends object,\n  RunnerFactory extends (() => RunnerLike) | undefined,\n> = {\n  transition: (to: UserState) => void;\n  /** Context snapshot captured at dispatch time. Stale after any `setContext` call. */\n  context: Context;\n  /**\n   * Live untracked read of the current context. Use in async task closures that\n   * execute after the handler returns — e.g. `getCtx: getContext` passed to tasks\n   * scheduled on the runner, so each task reads the context committed by the\n   * previous task rather than the stale snapshot from dispatch time.\n   */\n  getContext: () => Context;\n  setContext: (next: Context) => void;\n} & (RunnerFactory extends () => infer R ? { runner: R } : object);\n\n/**\n * Definition for a single user-defined state.\n */\nexport type ActorStateDefinition<\n  UserState extends string,\n  Context extends object,\n  Message extends { type: string },\n  RunnerFactory extends (() => RunnerLike) | undefined,\n> = {\n  /**\n   * When the actor's runner settles while in this state, automatically\n   * transition to this state. The framework owns the generation-token logic —\n   * re-registering after each `runner.schedule()` call so that\n   * `abortAll()` + reschedule correctly supersedes stale callbacks.\n   */\n  onSettled?: UserState;\n  /** Message handlers active in this state. Messages with no handler are silently dropped. */\n  on?: {\n    [M in Message as M['type']]?: (\n      message: Extract<Message, { type: M['type'] }>,\n      ctx: HandlerContext<UserState, Context, RunnerFactory>\n    ) => void;\n  };\n};\n\n/**\n * Full actor definition passed to `createMachineActor`.\n *\n * `UserState` is the set of domain-meaningful states. `'destroyed'` is always\n * added by the framework as the implicit terminal state — do not include it here.\n */\nexport type ActorDefinition<\n  UserState extends string,\n  Context extends object,\n  Message extends { type: string },\n  RunnerFactory extends (() => RunnerLike) | undefined = undefined,\n> = {\n  /**\n   * Runner factory — called once at `createMachineActor()` time.\n   * The runner lives for the full actor lifetime and is destroyed with it.\n   *\n   * @example\n   * runner: () => new SerialRunner()\n   */\n  runner?: RunnerFactory;\n  /** Initial state. */\n  initial: UserState;\n  /** Initial context. */\n  context: Context;\n  /**\n   * Per-state definitions. States with no definition silently drop all messages.\n   * All user-defined states must appear as keys in the `UserState` union.\n   */\n  states: Partial<Record<UserState, ActorStateDefinition<UserState, Context, Message, RunnerFactory>>>;\n};\n\n// =============================================================================\n// Live actor interface\n// =============================================================================\n\n/** Live actor instance returned by `createMachineActor`. */\nexport interface MessageActor<State extends string, Context extends object, Message extends { type: string }>\n  extends SignalActor<State, Context> {\n  send(message: Message): void;\n}\n\n// =============================================================================\n// Implementation\n// =============================================================================\n\n/**\n * Creates a message-driven actor from a declarative definition.\n *\n * The actor owns a reactive snapshot signal (state + context), an optional\n * runner, and dispatches incoming messages to per-state handlers. `'destroyed'`\n * is always the implicit terminal state — `destroy()` transitions there\n * unconditionally and all subsequent `send()` calls are no-ops.\n *\n * When a state declares `onSettled`, the framework calls `runner.whenSettled()`\n * after the handler returns. The runner owns the generation-token logic — if\n * new tasks are scheduled before the current batch settles, the callback is\n * automatically superseded.\n *\n * @example\n * const actor = createMachineActor({\n *   runner: () => new SerialRunner(),\n *   initial: 'idle',\n *   context: {},\n *   states: {\n *     idle: {\n *       on: {\n *         load: (msg, { transition, runner }) => {\n *           segments.forEach(s => runner.schedule(new Task(...)));\n *           transition('loading');\n *         }\n *       }\n *     },\n *     loading: {\n *       onSettled: 'idle',\n *       on: {\n *         load: (msg, { runner }) => {\n *           runner.abortAll();\n *           segments.forEach(s => runner.schedule(new Task(...)));\n *         }\n *       }\n *     }\n *   }\n * });\n */\nexport function createMachineActor<\n  UserState extends string,\n  Context extends object,\n  Message extends { type: string },\n  RunnerFactory extends (() => RunnerLike) | undefined = undefined,\n>(\n  def: ActorDefinition<UserState, Context, Message, RunnerFactory>\n): MessageActor<UserState | 'destroyed', Context, Message> {\n  type FullState = UserState | 'destroyed';\n\n  const runner = def.runner?.() as RunnerLike | undefined;\n  const { snapshotSignal, getState, transition } = createMachineCore<FullState, ActorSnapshot<FullState, Context>>({\n    value: def.initial as FullState,\n    context: def.context,\n  });\n\n  const getContext = (): Context => untrack(() => snapshotSignal.get().context);\n\n  const setContext = (context: Context): void => {\n    update(snapshotSignal, { context });\n  };\n\n  return {\n    get snapshot() {\n      return snapshotSignal;\n    },\n\n    send(message: Message): void {\n      const state = getState();\n      if (state === 'destroyed') return;\n      const stateDef = def.states[state as UserState];\n      const handler = stateDef?.on?.[message.type as keyof typeof stateDef.on] as\n        | ((msg: Message, ctx: HandlerContext<UserState, Context, RunnerFactory>) => void)\n        | undefined;\n      if (!handler) return;\n      handler(message, {\n        context: getContext(),\n        getContext,\n        transition: (to: UserState) => transition(to as FullState),\n        setContext,\n        ...(runner ? { runner } : {}),\n      } as HandlerContext<UserState, Context, RunnerFactory>);\n      // Register onSettled after the handler so we read the post-transition state.\n      const newState = getState();\n      if (newState !== 'destroyed') {\n        const newStateDef = def.states[newState as UserState];\n        if (newStateDef?.onSettled && runner) {\n          const targetState = newStateDef.onSettled as FullState;\n          runner.whenSettled(() => {\n            if (getState() !== newState) return;\n            transition(targetState);\n          });\n        }\n      }\n    },\n\n    destroy(): void {\n      if (getState() === 'destroyed') return;\n      runner?.destroy();\n      transition('destroyed');\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2JA,SAAgB,mBAMd,KACyD;CAGzD,MAAM,SAAS,IAAI,UAAU;CAC7B,MAAM,EAAE,gBAAgB,UAAU,eAAe,kBAAgE;EAC/G,OAAO,IAAI;EACX,SAAS,IAAI;EACd,CAAC;CAEF,MAAM,mBAA4B,cAAc,eAAe,KAAK,CAAC,QAAQ;CAE7E,MAAM,cAAc,YAA2B;AAC7C,SAAO,gBAAgB,EAAE,SAAS,CAAC;;AAGrC,QAAO;EACL,IAAI,WAAW;AACb,UAAO;;EAGT,KAAK,SAAwB;GAC3B,MAAM,QAAQ,UAAU;AACxB,OAAI,UAAU,YAAa;GAE3B,MAAM,UADW,IAAI,OAAO,QACF,KAAK,QAAQ;AAGvC,OAAI,CAAC,QAAS;AACd,WAAQ,SAAS;IACf,SAAS,YAAY;IACrB;IACA,aAAa,OAAkB,WAAW,GAAgB;IAC1D;IACA,GAAI,SAAS,EAAE,QAAQ,GAAG,EAAE;IAC7B,CAAsD;GAEvD,MAAM,WAAW,UAAU;AAC3B,OAAI,aAAa,aAAa;IAC5B,MAAM,cAAc,IAAI,OAAO;AAC/B,QAAI,aAAa,aAAa,QAAQ;KACpC,MAAM,cAAc,YAAY;AAChC,YAAO,kBAAkB;AACvB,UAAI,UAAU,KAAK,SAAU;AAC7B,iBAAW,YAAY;OACvB;;;;EAKR,UAAgB;AACd,OAAI,UAAU,KAAK,YAAa;AAChC,WAAQ,SAAS;AACjB,cAAW,YAAY;;EAE1B"}