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

package/dist/dev/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/dev/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/dev/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/dev/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/dev/core/actor.d.ts

@@ -0,0 +1,27 @@
+import { Machine, MachineSnapshot } from "./machine.js";
+
+//#region src/core/actor.d.ts
+/**
+ * Complete actor snapshot: finite state + non-finite context.
+ * Extends `MachineSnapshot` with context — the non-finite data managed by the actor.
+ */
+interface ActorSnapshot<State extends string, Context extends object> extends MachineSnapshot<State> {
+  context: Context;
+}
+/** Generic actor interface: owns its snapshot as a reactive signal. */
+interface SignalActor<State extends string, Context extends object> extends Machine<ActorSnapshot<State, Context>> {}
+/**
+ * A message-driven actor with no reactive snapshot.
+ *
+ * Use for actors that coordinate async work but have no state that external
+ * consumers need to observe. Analogous to XState's `fromCallback`.
+ */
+interface CallbackActor<Message extends {
+  type: string;
+}> {
+  send(message: Message): void;
+  destroy(): void;
+}
+//#endregion
+export { ActorSnapshot, CallbackActor, SignalActor };
+//# sourceMappingURL=actor.d.ts.map

package/dist/dev/core/actor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor.d.ts","names":[],"sources":["../../../src/core/actor.ts"],"mappings":";;;;;;;UAeiB,aAAA,uDAAoE,eAAA,CAAgB,KAAA;EACnG,OAAA,EAAS,OAAA;AAAA;;UAIM,WAAA,uDACP,OAAA,CAAQ,aAAA,CAAc,KAAA,EAAO,OAAA;AADvC;;;;;;AAAA,UASiB,aAAA;EAAgC,IAAA;AAAA;EAC/C,IAAA,CAAK,OAAA,EAAS,OAAA;EACd,OAAA;AAAA"}

package/dist/dev/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/dev/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/dev/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/dev/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/dev/core/create-machine-actor.d.ts

@@ -0,0 +1,12 @@
+import { SignalActor } from "./actor.js";
+
+//#region src/core/create-machine-actor.d.ts
+/** Live actor instance returned by `createMachineActor`. */
+interface MessageActor<State extends string, Context extends object, Message extends {
+  type: string;
+}> extends SignalActor<State, Context> {
+  send(message: Message): void;
+}
+//#endregion
+export { MessageActor };
+//# sourceMappingURL=create-machine-actor.d.ts.map

package/dist/dev/core/create-machine-actor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-machine-actor.d.ts","names":[],"sources":["../../../src/core/create-machine-actor.ts"],"mappings":";;;;UA2GiB,YAAA;EAA6E,IAAA;AAAA,WACpF,WAAA,CAAY,KAAA,EAAO,OAAA;EAC3B,IAAA,CAAK,OAAA,EAAS,OAAA;AAAA"}

package/dist/dev/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/dev/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"}

package/dist/dev/core/create-machine-reactor.d.ts

@@ -0,0 +1,8 @@
+import { Machine, MachineSnapshot } from "./machine.js";
+
+//#region src/core/create-machine-reactor.d.ts
+/** Live reactor instance returned by `createMachineReactor`. */
+type Reactor<State extends string> = Machine<MachineSnapshot<State>>;
+//#endregion
+export { Reactor };
+//# sourceMappingURL=create-machine-reactor.d.ts.map

package/dist/dev/core/create-machine-reactor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-machine-reactor.d.ts","names":[],"sources":["../../../src/core/create-machine-reactor.ts"],"mappings":";;;;KAyEY,OAAA,yBAAgC,OAAA,CAAQ,eAAA,CAAgB,KAAA"}

package/dist/dev/core/create-machine-reactor.js

@@ -0,0 +1,83 @@
+import { effect } from "./signals/effect.js";
+import { untrack } from "./signals/primitives.js";
+import { createMachineCore } from "./machine.js";
+//#region src/core/create-machine-reactor.ts
+const toArray = (x) => x === void 0 ? [] : Array.isArray(x) ? x : [x];
+/**
+* Creates a reactive Reactor from a declarative definition.
+*
+* A Reactor is driven by subscriptions to external signals rather than
+* imperative messages. Each state holds an array of effect functions —
+* every element becomes one independent `effect()` call gated on that state,
+* with its own dependency tracking and cleanup lifecycle.
+*
+* `'destroying'` and `'destroyed'` are always implicit terminal states.
+* `destroy()` transitions through both in sequence: `'destroying'` first (for
+* potential async teardown in a future extension), then immediately `'destroyed'`
+* for the synchronous base case. Active effect cleanups fire via disposal.
+*
+* @example
+* const reactor = createMachineReactor({
+*   initial: 'waiting',
+*   monitor: () => srcSignal.get() ? 'active' : 'waiting',
+*   states: {
+*     active: {
+*       // entry: runs once on state entry; fn body is automatically untracked.
+*       entry: () => listen(el, 'play', handler),
+*       // effects: re-runs whenever tracked signals change.
+*       effects: () => { currentTimeSignal.get(); return cleanup; },
+*     },
+*     waiting: {},
+*   }
+* });
+*/
+function createMachineReactor(def) {
+	const { snapshotSignal, getState, transition } = createMachineCore({ value: def.initial });
+	const effectDisposals = [];
+	const wrapResult = (result) => {
+		if (!result) return void 0;
+		if (typeof result === "function") return result;
+		return () => result.abort();
+	};
+	const untracked = (baseCall) => () => untrack(baseCall);
+	const isTerminal = (snapshot) => snapshot.value === "destroying" || snapshot.value === "destroyed";
+	const descriptors = [...toArray(def.monitor).map((fn) => ({
+		fn: () => {
+			const target = fn();
+			if (target !== getState()) transition(target);
+		},
+		shouldSkip: isTerminal
+	})), ...Object.entries(def.states).flatMap(([state, stateDef]) => {
+		const isNotState = (snapshot) => snapshot.value !== state;
+		return [...toArray(stateDef.entry).map((fn) => ({
+			fn,
+			shouldSkip: isNotState,
+			toFnCall: untracked
+		})), ...toArray(stateDef.effects).map((fn) => ({
+			fn,
+			shouldSkip: isNotState
+		}))];
+	})];
+	const toEffect = ({ fn, shouldSkip, toFnCall = (baseCall) => baseCall }) => effect(() => {
+		if (shouldSkip(snapshotSignal.get())) return;
+		const baseCall = () => fn();
+		return wrapResult(toFnCall(baseCall)());
+	});
+	effectDisposals.push(...descriptors.map(toEffect));
+	return {
+		get snapshot() {
+			return snapshotSignal;
+		},
+		destroy() {
+			const state = getState();
+			if (state === "destroying" || state === "destroyed") return;
+			transition("destroying");
+			transition("destroyed");
+			for (const dispose of effectDisposals) dispose();
+		}
+	};
+}
+//#endregion
+export { createMachineReactor };
+
+//# sourceMappingURL=create-machine-reactor.js.map

package/dist/dev/core/create-machine-reactor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-machine-reactor.js","names":[],"sources":["../../../src/core/create-machine-reactor.ts"],"sourcesContent":["import type { Machine, MachineSnapshot } from './machine';\nimport { createMachineCore } from './machine';\nimport { effect } from './signals/effect';\nimport { untrack } from './signals/primitives';\n\n// =============================================================================\n// Definition types\n// =============================================================================\n\n/**\n * A reactive state-deriving function used in the `monitor` field.\n *\n * Returns the target state the reactor should be in. Any signals read inside\n * the fn body create reactive dependencies — the framework re-evaluates it when\n * those signals change and automatically calls `transition()` when the returned\n * state differs from the current one.\n */\nexport type ReactorDeriveFn<State extends string> = () => State;\n\n/**\n * An effect function used in reactor `entry` and `effects` blocks.\n *\n * May return a cleanup function that runs before each re-evaluation and on\n * state exit (including destroy).\n */\nexport type ReactorEffectFn = () => (() => void) | { abort(): void } | void;\n\n/**\n * Per-state effect grouping for a single reactor state.\n *\n * - `entry` effects run once on state entry. The fn body is automatically\n *   untracked — no `untrack()` calls are needed inside. Use this for\n *   one-time setup: reading current values, attaching event listeners, etc.\n * - `effects` run on state entry and re-run whenever a signal read inside\n *   the fn body changes. Use `untrack()` for reads you do not want to track.\n *   Use this for work that must stay in sync with reactive state.\n *\n * Both are optional; pass `{}` for states with no effects.\n */\nexport type ReactorStateDefinition = {\n  entry?: ReactorEffectFn | ReactorEffectFn[];\n  effects?: ReactorEffectFn | ReactorEffectFn[];\n};\n\n/**\n * Full reactor definition passed to `createMachineReactor`.\n *\n * `State` is the set of domain-meaningful states. `'destroying'` and\n * `'destroyed'` are always added by the framework as implicit terminal states —\n * do not include them here.\n */\nexport type ReactorDefinition<State extends string> = {\n  /** Initial state. */\n  initial: State;\n  /**\n   * Reactive state derivation. Registered before per-state effects — the\n   * ordering guarantee ensures transitions fired here take effect before\n   * per-state effects re-evaluate in the same flush.\n   */\n  monitor?: ReactorDeriveFn<State> | ReactorDeriveFn<State>[];\n  /**\n   * Per-state effect groupings. Every valid state must be declared — pass `{}`\n   * for states with no effects. `entry` and `effects` each become independent\n   * `effect()` calls gated on that state, with their own cleanup lifecycles.\n   */\n  states: Record<State, ReactorStateDefinition>;\n};\n\n// =============================================================================\n// Live reactor interface\n// =============================================================================\n\n/** Live reactor instance returned by `createMachineReactor`. */\nexport type Reactor<State extends string> = Machine<MachineSnapshot<State>>;\n\n// =============================================================================\n// Implementation helpers\n// =============================================================================\n\nconst toArray = <T>(x: T | T[] | undefined): T[] => (x === undefined ? [] : Array.isArray(x) ? x : [x]);\n\n// =============================================================================\n// Implementation\n// =============================================================================\n\n/**\n * Creates a reactive Reactor from a declarative definition.\n *\n * A Reactor is driven by subscriptions to external signals rather than\n * imperative messages. Each state holds an array of effect functions —\n * every element becomes one independent `effect()` call gated on that state,\n * with its own dependency tracking and cleanup lifecycle.\n *\n * `'destroying'` and `'destroyed'` are always implicit terminal states.\n * `destroy()` transitions through both in sequence: `'destroying'` first (for\n * potential async teardown in a future extension), then immediately `'destroyed'`\n * for the synchronous base case. Active effect cleanups fire via disposal.\n *\n * @example\n * const reactor = createMachineReactor({\n *   initial: 'waiting',\n *   monitor: () => srcSignal.get() ? 'active' : 'waiting',\n *   states: {\n *     active: {\n *       // entry: runs once on state entry; fn body is automatically untracked.\n *       entry: () => listen(el, 'play', handler),\n *       // effects: re-runs whenever tracked signals change.\n *       effects: () => { currentTimeSignal.get(); return cleanup; },\n *     },\n *     waiting: {},\n *   }\n * });\n */\nexport function createMachineReactor<State extends string>(\n  def: ReactorDefinition<State>\n): Reactor<State | 'destroying' | 'destroyed'> {\n  type FullState = State | 'destroying' | 'destroyed';\n\n  const { snapshotSignal, getState, transition } = createMachineCore<FullState, MachineSnapshot<FullState>>({\n    value: def.initial as FullState,\n  });\n\n  const effectDisposals: Array<() => void> = [];\n\n  const wrapResult = (result: ReturnType<ReactorEffectFn>) => {\n    if (!result) return undefined;\n    if (typeof result === 'function') return result;\n    return () => result.abort();\n  };\n\n  type EffectCall = () => ReturnType<ReactorEffectFn>;\n\n  type EffectDescriptor = {\n    fn: ReactorEffectFn;\n    shouldSkip: (snapshot: { value: FullState }) => boolean;\n    toFnCall?: (baseCall: EffectCall) => EffectCall;\n  };\n\n  const untracked: EffectDescriptor['toFnCall'] = (baseCall) => () => untrack(baseCall);\n\n  const isTerminal = (snapshot: { value: FullState }) =>\n    snapshot.value === 'destroying' || snapshot.value === 'destroyed';\n\n  // `monitor` descriptors are built first — the ordering guarantee ensures\n  // transitions they trigger take effect before per-state effects re-evaluate\n  // in the same flush. See the comment on effect registration order in the\n  // previous implementation for full details.\n  const descriptors: EffectDescriptor[] = [\n    ...toArray(def.monitor).map((fn) => ({\n      fn: () => {\n        const target = fn();\n        if (target !== (getState() as State)) transition(target as FullState);\n      },\n      shouldSkip: isTerminal,\n    })),\n    ...(Object.entries(def.states) as Array<[State, ReactorStateDefinition]>).flatMap(([state, stateDef]) => {\n      const isNotState = (snapshot: { value: FullState }) => snapshot.value !== state;\n      return [\n        ...toArray(stateDef.entry).map((fn) => ({ fn, shouldSkip: isNotState, toFnCall: untracked })),\n        ...toArray(stateDef.effects).map((fn) => ({ fn, shouldSkip: isNotState })),\n      ];\n    }),\n  ];\n\n  const toEffect = ({ fn, shouldSkip, toFnCall = (baseCall) => baseCall }: EffectDescriptor) =>\n    effect(() => {\n      const snapshot = snapshotSignal.get();\n      if (shouldSkip(snapshot)) return;\n      const baseCall = () => fn();\n      return wrapResult(toFnCall(baseCall)());\n    });\n\n  effectDisposals.push(...descriptors.map(toEffect));\n\n  return {\n    get snapshot() {\n      return snapshotSignal;\n    },\n\n    destroy(): void {\n      const state = getState();\n      if (state === 'destroying' || state === 'destroyed') return;\n      // Two-step teardown: transition through 'destroying' first to leave room\n      // for async teardown in a future extension, then immediately 'destroyed'\n      // for the synchronous base case. Active effect cleanups fire via disposal.\n      transition('destroying');\n      transition('destroyed');\n      for (const dispose of effectDisposals) dispose();\n    },\n  };\n}\n"],"mappings":";;;;AA+EA,MAAM,WAAc,MAAiC,MAAM,KAAA,IAAY,EAAE,GAAG,MAAM,QAAQ,EAAE,GAAG,IAAI,CAAC,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCtG,SAAgB,qBACd,KAC6C;CAG7C,MAAM,EAAE,gBAAgB,UAAU,eAAe,kBAAyD,EACxG,OAAO,IAAI,SACZ,CAAC;CAEF,MAAM,kBAAqC,EAAE;CAE7C,MAAM,cAAc,WAAwC;AAC1D,MAAI,CAAC,OAAQ,QAAO,KAAA;AACpB,MAAI,OAAO,WAAW,WAAY,QAAO;AACzC,eAAa,OAAO,OAAO;;CAW7B,MAAM,aAA2C,mBAAmB,QAAQ,SAAS;CAErF,MAAM,cAAc,aAClB,SAAS,UAAU,gBAAgB,SAAS,UAAU;CAMxD,MAAM,cAAkC,CACtC,GAAG,QAAQ,IAAI,QAAQ,CAAC,KAAK,QAAQ;EACnC,UAAU;GACR,MAAM,SAAS,IAAI;AACnB,OAAI,WAAY,UAAU,CAAY,YAAW,OAAoB;;EAEvE,YAAY;EACb,EAAE,EACH,GAAI,OAAO,QAAQ,IAAI,OAAO,CAA4C,SAAS,CAAC,OAAO,cAAc;EACvG,MAAM,cAAc,aAAmC,SAAS,UAAU;AAC1E,SAAO,CACL,GAAG,QAAQ,SAAS,MAAM,CAAC,KAAK,QAAQ;GAAE;GAAI,YAAY;GAAY,UAAU;GAAW,EAAE,EAC7F,GAAG,QAAQ,SAAS,QAAQ,CAAC,KAAK,QAAQ;GAAE;GAAI,YAAY;GAAY,EAAE,CAC3E;GACD,CACH;CAED,MAAM,YAAY,EAAE,IAAI,YAAY,YAAY,aAAa,eAC3D,aAAa;AAEX,MAAI,WADa,eAAe,KAAK,CACb,CAAE;EAC1B,MAAM,iBAAiB,IAAI;AAC3B,SAAO,WAAW,SAAS,SAAS,EAAE,CAAC;GACvC;AAEJ,iBAAgB,KAAK,GAAG,YAAY,IAAI,SAAS,CAAC;AAElD,QAAO;EACL,IAAI,WAAW;AACb,UAAO;;EAGT,UAAgB;GACd,MAAM,QAAQ,UAAU;AACxB,OAAI,UAAU,gBAAgB,UAAU,YAAa;AAIrD,cAAW,aAAa;AACxB,cAAW,YAAY;AACvB,QAAK,MAAM,WAAW,gBAAiB,UAAS;;EAEnD"}

package/dist/dev/core/create-transition-actor.d.ts

@@ -0,0 +1,23 @@
+import { Machine } from "./machine.js";
+import { ActorSnapshot } from "./actor.js";
+
+//#region src/core/create-transition-actor.d.ts
+/**
+ * A reducer-shaped actor: `(context, message) => context`.
+ *
+ * No finite states — the snapshot carries `value: 'active' | 'destroyed'`
+ * as a universal lifecycle marker rather than domain state. The interesting
+ * state is entirely in the context, which is reactive via `snapshot`.
+ *
+ * Use this when the actor has context that needs to be reactive but no
+ * meaningful state machine (e.g., a message-driven model with DOM side
+ * effects). For actors that need per-state behavior, use `createMachineActor`.
+ */
+interface TransitionActor<Context extends object, Message extends {
+  type: string;
+}> extends Machine<ActorSnapshot<'active' | 'destroyed', Context>> {
+  send(message: Message): void;
+}
+//#endregion
+export { TransitionActor };
+//# sourceMappingURL=create-transition-actor.d.ts.map

package/dist/dev/core/create-transition-actor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-transition-actor.d.ts","names":[],"sources":["../../../src/core/create-transition-actor.ts"],"mappings":";;;;;;AAoBA;;;;;;;;;UAAiB,eAAA;EAA0D,IAAA;AAAA,WACjE,OAAA,CAAQ,aAAA,yBAAsC,OAAA;EACtD,IAAA,CAAK,OAAA,EAAS,OAAA;AAAA"}

package/dist/dev/core/create-transition-actor.js

@@ -0,0 +1,46 @@
+import { untrack, update } from "./signals/primitives.js";
+import { createMachineCore } from "./machine.js";
+//#region src/core/create-transition-actor.ts
+/**
+* Creates a reducer-shaped actor from an initial context and a reducer function.
+*
+* The reducer receives the current context and a message and returns the next
+* context. Returning the same reference (by identity) skips the signal update —
+* so early-returning `context` unchanged is both the no-op and the optimization.
+*
+* Side effects (e.g. DOM mutations) may be performed inside the reducer.
+* They run synchronously before the signal is updated.
+*
+* @example
+* const actor = createTransitionActor(
+*   { count: 0 },
+*   (context, message: { type: 'increment' }) => ({ count: context.count + 1 })
+* );
+*/
+function createTransitionActor(initialContext, reducer) {
+	const { snapshotSignal, getState, transition } = createMachineCore({
+		value: "active",
+		context: initialContext
+	});
+	const getContext = () => untrack(() => snapshotSignal.get().context);
+	const setContext = (context) => update(snapshotSignal, { context });
+	return {
+		get snapshot() {
+			return snapshotSignal;
+		},
+		send(message) {
+			if (getState() === "destroyed") return;
+			const context = getContext();
+			const newContext = reducer(context, message);
+			if (newContext !== context) setContext(newContext);
+		},
+		destroy() {
+			if (getState() === "destroyed") return;
+			transition("destroyed");
+		}
+	};
+}
+//#endregion
+export { createTransitionActor };
+
+//# sourceMappingURL=create-transition-actor.js.map