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

package/dist/default/playback/behaviors/track-types.js

@@ -0,0 +1,61 @@
+//#region src/playback/behaviors/track-types.ts
+/**
+* **Per-type config bundles for per-type behavior variants.**
+*
+* Each `*_TYPE_CONFIG` constant names the per-type slot keys that
+* per-type-variant setup-shape helpers consume. Variants reference the
+* shared constant at their `defineBehavior` setup body rather than
+* constructing the config inline, so the per-type identity (which state
+* slot, which context slot, which discriminant) lives in one place per
+* type.
+*
+* Variants spread their composition-time `config` over the defaults so
+* engines can layer composition-supplied additions on top (e.g. a
+* custom fetch closure, a non-default segment resolver). Defaults
+* first, engine config second.
+*
+* Helpers continue to consume their slice via the existing typed-key
+* generics (`<K extends SelectedTrackKey>` etc.); the extra fields on
+* the config object (carrying facets other helpers care about) are fine
+* under structural typing.
+*/
+/**
+* Type-identity bundle for video-track-typed behaviors.
+*
+* @see setupVideoBufferActors, loadVideoSegments
+*/
+const VIDEO_TYPE_CONFIG = {
+	type: "video",
+	selectedKey: "selectedVideoTrackId",
+	actorKey: "videoBufferActor",
+	loaderKey: "videoSegmentLoaderActor"
+};
+/**
+* Type-identity bundle for audio-track-typed behaviors.
+*
+* @see setupAudioBufferActors, loadAudioSegments
+*/
+const AUDIO_TYPE_CONFIG = {
+	type: "audio",
+	selectedKey: "selectedAudioTrackId",
+	actorKey: "audioBufferActor",
+	loaderKey: "audioSegmentLoaderActor"
+};
+/**
+* Type-identity bundle for text-track-typed behaviors. Text tracks have
+* no `SourceBufferActor` (MSE doesn't apply), so this bundle omits
+* `actorKey`. The `loaderKey` points at the text-track-segment-loader
+* actor (a `MessageActor` with continue-vs-preempt semantics, parallel
+* to v/a's `SegmentLoaderActor`).
+*
+* @see loadTextTrackSegments, setupTextTrackActors
+*/
+const TEXT_TYPE_CONFIG = {
+	type: "text",
+	selectedKey: "selectedTextTrackId",
+	loaderKey: "textTrackSegmentLoaderActor"
+};
+//#endregion
+export { AUDIO_TYPE_CONFIG, TEXT_TYPE_CONFIG, VIDEO_TYPE_CONFIG };
+
+//# sourceMappingURL=track-types.js.map

package/dist/default/playback/behaviors/track-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"track-types.js","names":[],"sources":["../../../../src/playback/behaviors/track-types.ts"],"sourcesContent":["/**\n * **Per-type config bundles for per-type behavior variants.**\n *\n * Each `*_TYPE_CONFIG` constant names the per-type slot keys that\n * per-type-variant setup-shape helpers consume. Variants reference the\n * shared constant at their `defineBehavior` setup body rather than\n * constructing the config inline, so the per-type identity (which state\n * slot, which context slot, which discriminant) lives in one place per\n * type.\n *\n * Variants spread their composition-time `config` over the defaults so\n * engines can layer composition-supplied additions on top (e.g. a\n * custom fetch closure, a non-default segment resolver). Defaults\n * first, engine config second.\n *\n * Helpers continue to consume their slice via the existing typed-key\n * generics (`<K extends SelectedTrackKey>` etc.); the extra fields on\n * the config object (carrying facets other helpers care about) are fine\n * under structural typing.\n */\n\n/**\n * Type-identity bundle for video-track-typed behaviors.\n *\n * @see setupVideoBufferActors, loadVideoSegments\n */\nexport const VIDEO_TYPE_CONFIG = {\n  type: 'video',\n  selectedKey: 'selectedVideoTrackId',\n  actorKey: 'videoBufferActor',\n  loaderKey: 'videoSegmentLoaderActor',\n} as const;\n\n/**\n * Type-identity bundle for audio-track-typed behaviors.\n *\n * @see setupAudioBufferActors, loadAudioSegments\n */\nexport const AUDIO_TYPE_CONFIG = {\n  type: 'audio',\n  selectedKey: 'selectedAudioTrackId',\n  actorKey: 'audioBufferActor',\n  loaderKey: 'audioSegmentLoaderActor',\n} as const;\n\n/**\n * Type-identity bundle for text-track-typed behaviors. Text tracks have\n * no `SourceBufferActor` (MSE doesn't apply), so this bundle omits\n * `actorKey`. The `loaderKey` points at the text-track-segment-loader\n * actor (a `MessageActor` with continue-vs-preempt semantics, parallel\n * to v/a's `SegmentLoaderActor`).\n *\n * @see loadTextTrackSegments, setupTextTrackActors\n */\nexport const TEXT_TYPE_CONFIG = {\n  type: 'text',\n  selectedKey: 'selectedTextTrackId',\n  loaderKey: 'textTrackSegmentLoaderActor',\n} as const;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,MAAa,oBAAoB;CAC/B,MAAM;CACN,aAAa;CACb,UAAU;CACV,WAAW;CACZ;;;;;;AAOD,MAAa,oBAAoB;CAC/B,MAAM;CACN,aAAa;CACb,UAAU;CACV,WAAW;CACZ;;;;;;;;;;AAWD,MAAa,mBAAmB;CAC9B,MAAM;CACN,aAAa;CACb,WAAW;CACZ"}

package/dist/default/{dom/playback-engine → playback/engines/hls}/adapter.js

@@ -1,6 +1,9 @@
-import { update } from "../../core/signals/primitives.js";
-import { createPlaybackEngine } from "./engine.js";
-//#region src/dom/playback-engine/adapter.ts
+import { createSimpleHlsEngine } from "./engine.js";
+//#region src/playback/engines/hls/adapter.ts
+const simpleHlsMediaDefaultProps = {
+	src: "",
+	preload: ""
+};
 /**
 * Mixin that adds SPF playback engine behavior to any base class.
 *
@@ -13,35 +16,36 @@ import { createPlaybackEngine } from "./engine.js";
 * changes and re-applied to the new engine automatically.
 *
 * @example
-* class SimpleHlsMedia extends SpfMediaMixin(HTMLVideoElementHost) {}
+* class SimpleHlsMedia extends SimpleHlsMediaMixin(HTMLVideoElementHost) {}
 *
 * const media = new SimpleHlsMedia();
 * media.attach(document.querySelector('video'));
 * media.src = 'https://stream.mux.com/abc123.m3u8';
 */
-function SpfMediaMixin(BaseClass) {
-	class SpfMediaImpl extends BaseClass {
+function SimpleHlsMediaMixin(BaseClass) {
+	class SimpleHlsMediaImpl extends BaseClass {
 		#engine;
 		#config;
-		#preload = "";
+		#signals;
+		#preload = simpleHlsMediaDefaultProps.preload;
 		/** Pending loadstart listener from a deferred play() retry, if any. */
 		#loadstartListener = null;
 		constructor(...args) {
 			super(...args);
 			const { config } = args?.[0] ?? {};
 			this.#config = config;
-			this.#engine = createPlaybackEngine(config);
+			this.#engine = this.#createEngine();
 		}
 		get engine() {
 			return this.#engine;
 		}
 		attach(mediaElement) {
 			super.attach?.(mediaElement);
-			update(this.#engine.owners, { mediaElement });
+			this.#signals.context.mediaElement.set(mediaElement);
 		}
 		detach() {
 			this.#cancelPendingPlay();
-			update(this.#engine.owners, { mediaElement: void 0 });
+			this.#signals.context.mediaElement.set(void 0);
 			super.detach?.();
 		}
 		destroy() {
@@ -53,24 +57,24 @@ function SpfMediaMixin(BaseClass) {
 		}
 		set preload(value) {
 			this.#preload = value;
-			if (value) update(this.#engine.state, { preload: value });
+			if (value) this.#signals.state.preload.set(value);
 		}
 		get src() {
-			return this.#engine.state.get().presentation?.url ?? "";
+			return this.#signals.state.presentation.get()?.url ?? "";
 		}
 		set src(value) {
-			const prevMediaElement = this.#engine.owners.get().mediaElement;
+			const prevMediaElement = this.#signals.context.mediaElement.get();
 			this.#cancelPendingPlay();
 			this.#engine.destroy();
-			this.#engine = createPlaybackEngine(this.#config);
-			if (this.#preload) update(this.#engine.state, { preload: this.#preload });
-			if (prevMediaElement) update(this.#engine.owners, { mediaElement: prevMediaElement });
-			if (value) update(this.#engine.state, { presentation: { url: value } });
+			this.#engine = this.#createEngine();
+			if (this.#preload) this.#signals.state.preload.set(this.#preload);
+			if (prevMediaElement) this.#signals.context.mediaElement.set(prevMediaElement);
+			if (value) this.#signals.state.presentation.set({ url: value });
 		}
 		play() {
-			const { mediaElement } = this.#engine.owners.get();
-			if (!mediaElement) return Promise.reject(/* @__PURE__ */ new Error("SpfMedia: no media element attached"));
-			update(this.#engine.state, { playbackInitiated: true });
+			const mediaElement = this.#signals.context.mediaElement.get();
+			if (!mediaElement) return Promise.reject(/* @__PURE__ */ new Error("SimpleHlsMediaElement: no media element attached"));
+			this.#signals.state.loadActivated.set(true);
 			return mediaElement.play().catch((err) => {
 				if (this.src) return new Promise((resolve, reject) => {
 					const listener = () => {
@@ -83,18 +87,25 @@ function SpfMediaMixin(BaseClass) {
 				throw err;
 			});
 		}
+		#createEngine() {
+			return createSimpleHlsEngine({
+				...this.#config,
+				onSignalsReady: (signals) => {
+					this.#signals = signals;
+				}
+			});
+		}
 		#cancelPendingPlay() {
 			if (!this.#loadstartListener) return;
-			const { mediaElement } = this.#engine.owners.get();
-			mediaElement?.removeEventListener("loadstart", this.#loadstartListener);
+			this.#signals.context.mediaElement.get()?.removeEventListener("loadstart", this.#loadstartListener);
 			this.#loadstartListener = null;
 		}
 	}
-	return SpfMediaImpl;
+	return SimpleHlsMediaImpl;
 }
 /** Standalone SPF media adapter with no base class. */
-var SpfMedia = class extends SpfMediaMixin(class {}) {};
+var SimpleHlsMediaElement = class extends SimpleHlsMediaMixin(class {}) {};
 //#endregion
-export { SpfMedia, SpfMediaMixin };
+export { SimpleHlsMediaElement, SimpleHlsMediaMixin, simpleHlsMediaDefaultProps };
 
 //# sourceMappingURL=adapter.js.map

package/dist/default/playback/engines/hls/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","names":["#config","#engine","#createEngine","#signals","#cancelPendingPlay","#preload","#loadstartListener"],"sources":["../../../../../src/playback/engines/hls/adapter.ts"],"sourcesContent":["import type { Constructor, MixinReturn } from '@videojs/utils/types';\nimport type { Composition } from '../../../core/composition/create-composition';\nimport {\n  createSimpleHlsEngine,\n  type SimpleHlsEngineConfig,\n  type SimpleHlsEngineContext,\n  type SimpleHlsEngineSignals,\n  type SimpleHlsEngineState,\n} from './engine';\n\nexport interface SimpleHlsMediaProps {\n  src: string;\n  preload: '' | 'none' | 'metadata' | 'auto';\n}\n\nexport const simpleHlsMediaDefaultProps: SimpleHlsMediaProps = {\n  src: '',\n  preload: '',\n};\n\nexport interface SimpleHlsMediaAPI extends SimpleHlsMediaProps {\n  readonly engine: Composition<SimpleHlsEngineState, SimpleHlsEngineContext>;\n  attach(mediaElement: HTMLMediaElement): void;\n  detach(): void;\n  destroy(): void;\n  play(): Promise<void>;\n}\n\n/**\n * Mixin that adds SPF playback engine behavior to any base class.\n *\n * Implements the src/play() contract per the WHATWG HTML spec so that SPF can\n * be used anywhere a media element API is expected.\n *\n * A new engine is created on every src assignment — this fully tears down all\n * state, SourceBuffers, and in-flight requests from the previous source before\n * the next one begins. The media element reference is preserved across src\n * changes and re-applied to the new engine automatically.\n *\n * @example\n * class SimpleHlsMedia extends SimpleHlsMediaMixin(HTMLVideoElementHost) {}\n *\n * const media = new SimpleHlsMedia();\n * media.attach(document.querySelector('video'));\n * media.src = 'https://stream.mux.com/abc123.m3u8';\n */\nexport function SimpleHlsMediaMixin<Base extends Constructor<any>>(BaseClass: Base) {\n  class SimpleHlsMediaImpl extends BaseClass {\n    #engine: Composition<SimpleHlsEngineState, SimpleHlsEngineContext>;\n    #config: SimpleHlsEngineConfig;\n    #signals!: SimpleHlsEngineSignals;\n    #preload: '' | 'none' | 'metadata' | 'auto' = simpleHlsMediaDefaultProps.preload;\n\n    /** Pending loadstart listener from a deferred play() retry, if any. */\n    #loadstartListener: (() => void) | null = null;\n\n    constructor(...args: any[]) {\n      super(...args);\n\n      const { config } = args?.[0] ?? {};\n      this.#config = config;\n      this.#engine = this.#createEngine();\n    }\n\n    get engine(): Composition<SimpleHlsEngineState, SimpleHlsEngineContext> {\n      return this.#engine;\n    }\n\n    // -------------------------------------------------------------------------\n    // Media element lifecycle\n    // -------------------------------------------------------------------------\n\n    attach(mediaElement: HTMLMediaElement): void {\n      super.attach?.(mediaElement);\n      this.#signals.context.mediaElement.set(mediaElement);\n    }\n\n    detach(): void {\n      this.#cancelPendingPlay();\n      this.#signals.context.mediaElement.set(undefined);\n      super.detach?.();\n    }\n\n    destroy(): void {\n      this.#cancelPendingPlay();\n      this.#engine.destroy();\n    }\n\n    // -------------------------------------------------------------------------\n    // preload — synchronous IDL attribute (WHATWG §4.8.11.2)\n    // -------------------------------------------------------------------------\n\n    get preload(): '' | 'none' | 'metadata' | 'auto' {\n      return this.#preload;\n    }\n\n    set preload(value: '' | 'none' | 'metadata' | 'auto') {\n      this.#preload = value;\n      if (value) {\n        this.#signals.state.preload.set(value);\n      }\n      // value = '' clears #preload (so the next engine recreation won't re-apply\n      // an explicit value) but does not patch current state — the existing preload\n      // stays in effect until the next src change creates a fresh engine.\n    }\n\n    // -------------------------------------------------------------------------\n    // src — synchronous IDL attribute (WHATWG §4.8.11.2)\n    // Each assignment destroys the current engine and starts a fresh one, exactly\n    // as the browser's load algorithm resets all media element state on src change.\n    // -------------------------------------------------------------------------\n\n    get src(): string {\n      return this.#signals.state.presentation.get()?.url ?? '';\n    }\n\n    set src(value: string) {\n      const prevMediaElement = this.#signals.context.mediaElement.get();\n\n      this.#cancelPendingPlay();\n      this.#engine.destroy();\n      this.#engine = this.#createEngine();\n\n      // Apply explicit preload before setting context so it's already in\n      // state.preload when syncPreload's read effect runs on the attach —\n      // the read effect only overwrites when the element's `preload` is a\n      // W3C value (which a freshly-created <video> with no attribute is not).\n      if (this.#preload) {\n        this.#signals.state.preload.set(this.#preload);\n      }\n\n      if (prevMediaElement) {\n        this.#signals.context.mediaElement.set(prevMediaElement);\n      }\n\n      if (value) {\n        this.#signals.state.presentation.set({ url: value });\n      }\n    }\n\n    // -------------------------------------------------------------------------\n    // play() — WHATWG §4.8.11.8\n    // Delegates to the attached media element's native play().\n    // -------------------------------------------------------------------------\n\n    play(): Promise<void> {\n      const mediaElement = this.#signals.context.mediaElement.get();\n      if (!mediaElement) {\n        return Promise.reject(new Error('SimpleHlsMediaElement: no media element attached'));\n      }\n\n      // Signal play intent — enables loading even with preload=\"none\"\n      this.#signals.state.loadActivated.set(true);\n\n      return mediaElement.play().catch((err: unknown) => {\n        // If we have a pending HLS source, the rejection may be because MSE\n        // hasn't attached a blob URL yet. Wait for loadstart (src assigned\n        // by MSE setup) and retry once.\n        if (this.src) {\n          return new Promise<void>((resolve, reject) => {\n            const listener = () => {\n              this.#loadstartListener = null;\n              mediaElement.play().then(resolve, reject);\n            };\n            this.#loadstartListener = listener;\n            mediaElement.addEventListener('loadstart', listener, { once: true });\n          });\n        }\n        throw err;\n      });\n    }\n\n    // -------------------------------------------------------------------------\n    // Private\n    // -------------------------------------------------------------------------\n\n    #createEngine(): Composition<SimpleHlsEngineState, SimpleHlsEngineContext> {\n      return createSimpleHlsEngine({\n        ...this.#config,\n        onSignalsReady: (signals) => {\n          this.#signals = signals;\n        },\n      });\n    }\n\n    #cancelPendingPlay(): void {\n      if (!this.#loadstartListener) return;\n      const mediaElement = this.#signals.context.mediaElement.get();\n      mediaElement?.removeEventListener('loadstart', this.#loadstartListener);\n      this.#loadstartListener = null;\n    }\n  }\n\n  return SimpleHlsMediaImpl as unknown as MixinReturn<Base, SimpleHlsMediaAPI>;\n}\n\n/** Standalone SPF media adapter with no base class. */\nexport class SimpleHlsMediaElement extends SimpleHlsMediaMixin(class {}) {}\n"],"mappings":";;AAeA,MAAa,6BAAkD;CAC7D,KAAK;CACL,SAAS;CACV;;;;;;;;;;;;;;;;;;;AA4BD,SAAgB,oBAAmD,WAAiB;CAClF,MAAM,2BAA2B,UAAU;EACzC;EACA;EACA;EACA,WAA8C,2BAA2B;;EAGzE,qBAA0C;EAE1C,YAAY,GAAG,MAAa;AAC1B,SAAM,GAAG,KAAK;GAEd,MAAM,EAAE,WAAW,OAAO,MAAM,EAAE;AAClC,SAAA,SAAe;AACf,SAAA,SAAe,MAAA,cAAoB;;EAGrC,IAAI,SAAoE;AACtE,UAAO,MAAA;;EAOT,OAAO,cAAsC;AAC3C,SAAM,SAAS,aAAa;AAC5B,SAAA,QAAc,QAAQ,aAAa,IAAI,aAAa;;EAGtD,SAAe;AACb,SAAA,mBAAyB;AACzB,SAAA,QAAc,QAAQ,aAAa,IAAI,KAAA,EAAU;AACjD,SAAM,UAAU;;EAGlB,UAAgB;AACd,SAAA,mBAAyB;AACzB,SAAA,OAAa,SAAS;;EAOxB,IAAI,UAA6C;AAC/C,UAAO,MAAA;;EAGT,IAAI,QAAQ,OAA0C;AACpD,SAAA,UAAgB;AAChB,OAAI,MACF,OAAA,QAAc,MAAM,QAAQ,IAAI,MAAM;;EAa1C,IAAI,MAAc;AAChB,UAAO,MAAA,QAAc,MAAM,aAAa,KAAK,EAAE,OAAO;;EAGxD,IAAI,IAAI,OAAe;GACrB,MAAM,mBAAmB,MAAA,QAAc,QAAQ,aAAa,KAAK;AAEjE,SAAA,mBAAyB;AACzB,SAAA,OAAa,SAAS;AACtB,SAAA,SAAe,MAAA,cAAoB;AAMnC,OAAI,MAAA,QACF,OAAA,QAAc,MAAM,QAAQ,IAAI,MAAA,QAAc;AAGhD,OAAI,iBACF,OAAA,QAAc,QAAQ,aAAa,IAAI,iBAAiB;AAG1D,OAAI,MACF,OAAA,QAAc,MAAM,aAAa,IAAI,EAAE,KAAK,OAAO,CAAC;;EASxD,OAAsB;GACpB,MAAM,eAAe,MAAA,QAAc,QAAQ,aAAa,KAAK;AAC7D,OAAI,CAAC,aACH,QAAO,QAAQ,uBAAO,IAAI,MAAM,mDAAmD,CAAC;AAItF,SAAA,QAAc,MAAM,cAAc,IAAI,KAAK;AAE3C,UAAO,aAAa,MAAM,CAAC,OAAO,QAAiB;AAIjD,QAAI,KAAK,IACP,QAAO,IAAI,SAAe,SAAS,WAAW;KAC5C,MAAM,iBAAiB;AACrB,YAAA,oBAA0B;AAC1B,mBAAa,MAAM,CAAC,KAAK,SAAS,OAAO;;AAE3C,WAAA,oBAA0B;AAC1B,kBAAa,iBAAiB,aAAa,UAAU,EAAE,MAAM,MAAM,CAAC;MACpE;AAEJ,UAAM;KACN;;EAOJ,gBAA2E;AACzE,UAAO,sBAAsB;IAC3B,GAAG,MAAA;IACH,iBAAiB,YAAY;AAC3B,WAAA,UAAgB;;IAEnB,CAAC;;EAGJ,qBAA2B;AACzB,OAAI,CAAC,MAAA,kBAAyB;AACT,SAAA,QAAc,QAAQ,aAAa,KAAK,EAC/C,oBAAoB,aAAa,MAAA,kBAAwB;AACvE,SAAA,oBAA0B;;;AAI9B,QAAO;;;AAIT,IAAa,wBAAb,cAA2C,oBAAoB,MAAM,GAAG,CAAC"}

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

@@ -0,0 +1,102 @@
+import { createComposition } from "../../../core/composition/create-composition.js";
+import { makeShareSignals } from "../../../core/composition/share-signals.js";
+import { resolveVttSegment } from "../../../media/dom/text/resolve-vtt-segment.js";
+import { loadAudioSegments, loadTextTrackSegments, loadVideoSegments } from "../../behaviors/dom/load-segments.js";
+import { setupTextTrackActors } from "../../behaviors/dom/setup-text-track-actors.js";
+import { trackCurrentTime } from "../../behaviors/dom/track-current-time.js";
+import { trackLoadTriggers } from "../../behaviors/dom/track-load-triggers.js";
+import { addSubtitlesTracksToMedia, getShowingSubtitlesTrackFromMedia, removeAllSubtitlesTracksFromMedia } from "../../../media/dom/text/text-track-slots.js";
+import { parseMultivariantPlaylist } from "../../../media/hls/parse-multivariant.js";
+import { getResolvedSelectedTrackDuration } from "../../../media/utils/track-selection.js";
+import { calculatePresentationDuration } from "../../behaviors/calculate-presentation-duration.js";
+import { endOfStream } from "../../behaviors/dom/end-of-stream.js";
+import { setupAudioBufferActors, setupVideoBufferActors } from "../../behaviors/dom/setup-buffer-actors.js";
+import { setupMediaSource } from "../../behaviors/dom/setup-mediasource.js";
+import { syncTextTracks } from "../../behaviors/dom/sync-text-tracks.js";
+import { updateMediaSourceDuration } from "../../behaviors/dom/update-mediasource-duration.js";
+import { switchVideoQuality } from "../../behaviors/quality-switching.js";
+import { resolvePresentation } from "../../behaviors/resolve-presentation.js";
+import { resolveAudioTrack, resolveTextTrack, resolveVideoTrack } from "../../behaviors/resolve-track.js";
+import { selectAudioTrack, selectTextTrack } from "../../behaviors/select-tracks.js";
+import { syncPreload } from "../../behaviors/sync-preload.js";
+//#region src/playback/engines/hls/engine.ts
+/**
+* Generic `shareSignals` instantiated against the HLS engine's full state
+* and context — captures composition signal refs into the consumer's
+* `onSignalsReady` callback at setup time.
+*/
+const shareSignals = makeShareSignals();
+/**
+* Create an HLS playback engine.
+*
+* Composes SPF behaviors into a reactive pipeline for HLS playback over MSE:
+* manifest resolution, track selection, ABR, segment loading, and
+* end-of-stream coordination.
+*
+* @example
+* ```ts
+* let signals: SimpleHlsEngineSignals;
+* const engine = createSimpleHlsEngine({
+*   initialBandwidth: 2_000_000,
+*   preferredAudioLanguage: 'en',
+*   onSignalsReady: (refs) => {
+*     signals = refs;
+*   },
+* });
+*
+* signals.context.mediaElement.set(videoEl);
+* signals.state.presentation.set({ url: 'https://example.com/stream.m3u8' });
+*
+* videoEl.play();
+*
+* await engine.destroy();
+* ```
+*/
+function createSimpleHlsEngine(config = {}) {
+	const finalConfig = {
+		...config,
+		resolveTextTrackSegment: config.resolveTextTrackSegment ?? resolveVttSegment,
+		resolveDuration: config.resolveDuration ?? getResolvedSelectedTrackDuration,
+		parsePresentation: config.parsePresentation ?? parseMultivariantPlaylist,
+		addSubtitlesTracksToMedia: config.addSubtitlesTracksToMedia ?? addSubtitlesTracksToMedia,
+		getShowingSubtitlesTrackFromMedia: config.getShowingSubtitlesTrackFromMedia ?? getShowingSubtitlesTrackFromMedia,
+		removeAllSubtitlesTracksFromMedia: config.removeAllSubtitlesTracksFromMedia ?? removeAllSubtitlesTracksFromMedia
+	};
+	return createComposition([
+		syncPreload,
+		trackLoadTriggers,
+		resolvePresentation,
+		selectAudioTrack,
+		selectTextTrack,
+		resolveVideoTrack,
+		resolveAudioTrack,
+		resolveTextTrack,
+		calculatePresentationDuration,
+		setupMediaSource,
+		updateMediaSourceDuration,
+		setupVideoBufferActors,
+		setupAudioBufferActors,
+		trackCurrentTime,
+		switchVideoQuality,
+		loadVideoSegments,
+		loadAudioSegments,
+		endOfStream,
+		syncTextTracks,
+		setupTextTrackActors,
+		loadTextTrackSegments,
+		shareSignals
+	], {
+		config: finalConfig,
+		initialState: { bandwidthState: {
+			fastEstimate: 0,
+			fastTotalWeight: 0,
+			slowEstimate: 0,
+			slowTotalWeight: 0,
+			bytesSampled: 0
+		} }
+	});
+}
+//#endregion
+export { createSimpleHlsEngine };
+
+//# sourceMappingURL=engine.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","names":[],"sources":["../../../../../src/playback/engines/hls/engine.ts"],"sourcesContent":["import {\n  type Composition,\n  type ContextSignals,\n  createComposition,\n  type StateSignals,\n} from '../../../core/composition/create-composition';\nimport { makeShareSignals, type ShareSignalsConfig } from '../../../core/composition/share-signals';\nimport type { QualityConfig } from '../../../media/abr/quality-selection';\nimport type { BackBufferConfig } from '../../../media/buffer/back-buffer';\nimport type { ForwardBufferConfig } from '../../../media/buffer/forward-buffer';\nimport { resolveVttSegment } from '../../../media/dom/text/resolve-vtt-segment';\nimport {\n  addSubtitlesTracksToMedia,\n  getShowingSubtitlesTrackFromMedia,\n  removeAllSubtitlesTracksFromMedia,\n} from '../../../media/dom/text/text-track-slots';\nimport { parseMultivariantPlaylist } from '../../../media/hls/parse-multivariant';\nimport type { MaybeResolvedPresentation, VideoTrack } from '../../../media/types';\nimport { getResolvedSelectedTrackDuration } from '../../../media/utils/track-selection';\nimport type { BandwidthConfig, BandwidthState } from '../../../network/bandwidth-estimator';\nimport type { SegmentLoaderActor } from '../../actors/dom/segment-loader';\nimport type { SourceBufferActor } from '../../actors/dom/source-buffer';\nimport type { TextTracksActor } from '../../actors/dom/text-tracks';\nimport type { TextTrackSegmentLoaderActor, TextTrackSegmentResolver } from '../../actors/text-track-segment-loader';\nimport {\n  calculatePresentationDuration,\n  type PresentationDurationResolver,\n} from '../../behaviors/calculate-presentation-duration';\nimport { endOfStream } from '../../behaviors/dom/end-of-stream';\nimport { loadAudioSegments, loadTextTrackSegments, loadVideoSegments } from '../../behaviors/dom/load-segments';\nimport { setupAudioBufferActors, setupVideoBufferActors } from '../../behaviors/dom/setup-buffer-actors';\nimport { setupMediaSource } from '../../behaviors/dom/setup-mediasource';\nimport { setupTextTrackActors } from '../../behaviors/dom/setup-text-track-actors';\nimport { syncTextTracks } from '../../behaviors/dom/sync-text-tracks';\nimport { trackCurrentTime } from '../../behaviors/dom/track-current-time';\nimport { trackLoadTriggers } from '../../behaviors/dom/track-load-triggers';\nimport { updateMediaSourceDuration } from '../../behaviors/dom/update-mediasource-duration';\nimport { switchVideoQuality } from '../../behaviors/quality-switching';\nimport { type ParsePresentation, resolvePresentation } from '../../behaviors/resolve-presentation';\nimport { resolveAudioTrack, resolveTextTrack, resolveVideoTrack } from '../../behaviors/resolve-track';\nimport { selectAudioTrack, selectTextTrack } from '../../behaviors/select-tracks';\nimport { syncPreload } from '../../behaviors/sync-preload';\n\n// ============================================================================\n// HLS Engine State & Context\n// ============================================================================\n\n/**\n * State shape for the HLS playback engine.\n *\n * This is the union of all state required by the behaviors composed into\n * the HLS engine. Each behavior declares its own state interface; this\n * type satisfies all of them.\n */\nexport interface SimpleHlsEngineState {\n  /**\n   * The presentation being played. A caller writes `{ url }`;\n   * `resolvePresentation` parses the manifest and populates the rest.\n   */\n  presentation?: MaybeResolvedPresentation;\n  preload?: 'auto' | 'metadata' | 'none';\n  selectedVideoTrackId?: string;\n  selectedAudioTrackId?: string;\n  selectedTextTrackId?: string;\n  bandwidthState?: BandwidthState;\n  userVideoTrackSelection?: Partial<VideoTrack>;\n  currentTime?: number;\n  loadActivated?: boolean;\n}\n\n/**\n * Context shape for the HLS playback engine.\n *\n * Platform objects and actor references managed by HLS behaviors.\n */\nexport interface SimpleHlsEngineContext {\n  mediaElement?: HTMLMediaElement | undefined;\n  mediaSource?: MediaSource;\n  videoBufferActor?: SourceBufferActor;\n  audioBufferActor?: SourceBufferActor;\n  videoSegmentLoaderActor?: SegmentLoaderActor;\n  audioSegmentLoaderActor?: SegmentLoaderActor;\n  textTracksActor?: TextTracksActor;\n  textTrackSegmentLoaderActor?: TextTrackSegmentLoaderActor;\n}\n\n/**\n * The composition signal refs handed to `onSignalsReady` callers — the\n * canonical way to drive the engine externally (writes) or observe its\n * state (reads) without touching `composition.state` / `composition.context`\n * directly.\n */\nexport type SimpleHlsEngineSignals = {\n  state: StateSignals<SimpleHlsEngineState>;\n  context: ContextSignals<SimpleHlsEngineContext>;\n};\n\n/**\n * Configuration for the HLS playback engine.\n *\n * Each option is consumed by the appropriate behavior — the engine itself\n * has no config beyond what its behaviors read.\n */\nexport interface SimpleHlsEngineConfig extends ShareSignalsConfig<SimpleHlsEngineState, SimpleHlsEngineContext> {\n  /**\n   * Bandwidth estimate in bps to use before enough samples have been\n   * collected. Default: `DEFAULT_INITIAL_BANDWIDTH` (5 Mbps).\n   */\n  initialBandwidth?: number;\n  preferredAudioLanguage?: string;\n  preferredSubtitleLanguage?: string;\n  includeForcedTracks?: boolean;\n  enableDefaultTrack?: boolean;\n  /**\n   * Resolver that turns a text-track segment fetch into VTT cues.\n   * Defaults to the DOM-bound `resolveVttSegment` resolver, which uses an\n   * offscreen `<track>` element to parse WebVTT.\n   */\n  resolveTextTrackSegment?: TextTrackSegmentResolver<VTTCue>;\n  /**\n   * Resolver for `presentation.duration`. Defaults to picking the first\n   * resolved selected track's duration (video preferred, audio fallback) —\n   * appropriate for VoD and audio-only. Live engines should supply a\n   * resolver that returns `Number.POSITIVE_INFINITY` once the presentation\n   * is established as live; downstream `updateMediaSourceDuration` propagates\n   * that value to `mediaSource.duration` per the MSE spec.\n   */\n  resolveDuration?: PresentationDurationResolver;\n  /**\n   * Manifest parser handed to `resolvePresentation`. Defaults to the HLS\n   * multivariant-playlist parser; supply your own for alternate format\n   * support without forking the engine.\n   */\n  parsePresentation?: ParsePresentation;\n  /**\n   * Allocate SPF-owned text-track slots on the media element. Defaults to\n   * the standard `<track>`-element implementation in\n   * `media/dom/text/text-track-slots`.\n   */\n  addSubtitlesTracksToMedia?: typeof addSubtitlesTracksToMedia;\n  /**\n   * Return the SPF-owned subtitle/caption `TextTrack` currently in showing\n   * mode. Defaults to the standard selector-based implementation in\n   * `media/dom/text/text-track-slots`.\n   */\n  getShowingSubtitlesTrackFromMedia?: typeof getShowingSubtitlesTrackFromMedia;\n  /**\n   * Evict all SPF-owned text-track slots from the media element. Defaults to\n   * the standard selector-based implementation in\n   * `media/dom/text/text-track-slots`.\n   */\n  removeAllSubtitlesTracksFromMedia?: typeof removeAllSubtitlesTracksFromMedia;\n  /**\n   * Forward-buffer tuning. `bufferDuration` controls how far ahead of the\n   * playhead segments are loaded (and where forward-flush kicks in).\n   * Defaults: see `DEFAULT_FORWARD_BUFFER_CONFIG` (30 seconds). Threaded to\n   * segment-loader actors (v/a + text) at construction time and to\n   * `loadXSegments` dispatchers for the load-message range.\n   */\n  forwardBuffer?: Partial<ForwardBufferConfig>;\n  /**\n   * Back-buffer tuning. `keepSegments` controls how many segments stay\n   * behind the playhead before eviction. Defaults: see\n   * `DEFAULT_BACK_BUFFER_CONFIG` (2 segments). Threaded to the v/a\n   * segment-loader actor only (text tracks don't use back-buffer eviction).\n   */\n  backBuffer?: Partial<BackBufferConfig>;\n  /**\n   * Bandwidth-estimator tuning. Overrides any field of `BandwidthConfig`\n   * (`fastHalfLife`, `slowHalfLife`, `minTotalBytes`, `minBytes`,\n   * `minDuration`). `bandwidth.minTotalBytes` supersedes the flat\n   * `minTotalBytes` field above. Defaults: see `DEFAULT_BANDWIDTH_CONFIG`.\n   */\n  bandwidth?: Partial<BandwidthConfig>;\n  /**\n   * Quality-selection tuning. `safetyMargin` is the bandwidth-headroom\n   * multiplier used by `selectQuality`; `upgradeMargin` is the hysteresis\n   * ratio gating ABR upgrades. Defaults: `DEFAULT_QUALITY_CONFIG` (0.85 / 1.15).\n   */\n  quality?: Partial<QualityConfig>;\n}\n\n// ============================================================================\n// HLS Playback Engine\n// ============================================================================\n\n/**\n * Generic `shareSignals` instantiated against the HLS engine's full state\n * and context — captures composition signal refs into the consumer's\n * `onSignalsReady` callback at setup time.\n */\nconst shareSignals = makeShareSignals<SimpleHlsEngineState, SimpleHlsEngineContext>();\n\n/**\n * Create an HLS playback engine.\n *\n * Composes SPF behaviors into a reactive pipeline for HLS playback over MSE:\n * manifest resolution, track selection, ABR, segment loading, and\n * end-of-stream coordination.\n *\n * @example\n * ```ts\n * let signals: SimpleHlsEngineSignals;\n * const engine = createSimpleHlsEngine({\n *   initialBandwidth: 2_000_000,\n *   preferredAudioLanguage: 'en',\n *   onSignalsReady: (refs) => {\n *     signals = refs;\n *   },\n * });\n *\n * signals.context.mediaElement.set(videoEl);\n * signals.state.presentation.set({ url: 'https://example.com/stream.m3u8' });\n *\n * videoEl.play();\n *\n * await engine.destroy();\n * ```\n */\nexport function createSimpleHlsEngine(\n  config: SimpleHlsEngineConfig = {}\n): Composition<SimpleHlsEngineState, SimpleHlsEngineContext> {\n  const finalConfig = {\n    ...config,\n    resolveTextTrackSegment: config.resolveTextTrackSegment ?? resolveVttSegment,\n    resolveDuration: config.resolveDuration ?? getResolvedSelectedTrackDuration,\n    parsePresentation: config.parsePresentation ?? parseMultivariantPlaylist,\n    addSubtitlesTracksToMedia: config.addSubtitlesTracksToMedia ?? addSubtitlesTracksToMedia,\n    getShowingSubtitlesTrackFromMedia: config.getShowingSubtitlesTrackFromMedia ?? getShowingSubtitlesTrackFromMedia,\n    removeAllSubtitlesTracksFromMedia: config.removeAllSubtitlesTracksFromMedia ?? removeAllSubtitlesTracksFromMedia,\n  };\n\n  return createComposition(\n    [\n      syncPreload,\n      trackLoadTriggers,\n      resolvePresentation,\n\n      // Track selection (reads config for initial preferences).\n      // Video selection lives in switchVideoQuality, which owns the\n      // default-pick + ABR-driven adjustment for selectedVideoTrackId.\n      selectAudioTrack,\n      selectTextTrack,\n\n      // Resolve selected tracks (fetch media playlists)\n      resolveVideoTrack,\n      resolveAudioTrack,\n      resolveTextTrack,\n\n      // Presentation duration\n      calculatePresentationDuration,\n\n      // MSE setup. Video cluster is registered first so that, when both\n      // per-type variants flip to `'buffer-ready'` on the shared gate's\n      // monitor evaluation, `addSourceBuffer(video)` runs before\n      // `addSourceBuffer(audio)` — see the Firefox `mozHasAudio` invariant\n      // in setup-buffer-actors.ts.\n      setupMediaSource,\n      updateMediaSourceDuration,\n      setupVideoBufferActors,\n      setupAudioBufferActors,\n\n      // Playback tracking\n      trackCurrentTime,\n      switchVideoQuality,\n\n      // Segment loading\n      loadVideoSegments,\n      loadAudioSegments,\n\n      // End of stream coordination\n      endOfStream,\n\n      // Text tracks\n      syncTextTracks,\n      setupTextTrackActors,\n      loadTextTrackSegments,\n\n      // Behavior whose sole purpose is to use a callback to allow for signal writing from the outside (e.g. an adapter)\n      // NOTE: While not required, adding at the end since behaviors are setup in order, so this increases the likelihood\n      // that initial signal setup will have occurred before shareSignals' callback is invoked. (CJP)\n      shareSignals,\n    ],\n    {\n      config: finalConfig,\n      // Seed bandwidthState so switchVideoQuality fires on initial subscribe\n      // with the `initialBandwidth` fallback rather than waiting for the\n      // first chunk. The empty sample buffer means `getBandwidthEstimate`\n      // returns the configured initial bandwidth until real samples land.\n      initialState: {\n        bandwidthState: {\n          fastEstimate: 0,\n          fastTotalWeight: 0,\n          slowEstimate: 0,\n          slowTotalWeight: 0,\n          bytesSampled: 0,\n        },\n      },\n    }\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA+LA,MAAM,eAAe,kBAAgE;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BrF,SAAgB,sBACd,SAAgC,EAAE,EACyB;CAC3D,MAAM,cAAc;EAClB,GAAG;EACH,yBAAyB,OAAO,2BAA2B;EAC3D,iBAAiB,OAAO,mBAAmB;EAC3C,mBAAmB,OAAO,qBAAqB;EAC/C,2BAA2B,OAAO,6BAA6B;EAC/D,mCAAmC,OAAO,qCAAqC;EAC/E,mCAAmC,OAAO,qCAAqC;EAChF;AAED,QAAO,kBACL;EACE;EACA;EACA;EAKA;EACA;EAGA;EACA;EACA;EAGA;EAOA;EACA;EACA;EACA;EAGA;EACA;EAGA;EACA;EAGA;EAGA;EACA;EACA;EAKA;EACD,EACD;EACE,QAAQ;EAKR,cAAc,EACZ,gBAAgB;GACd,cAAc;GACd,iBAAiB;GACjB,cAAc;GACd,iBAAiB;GACjB,cAAc;GACf,EACF;EACF,CACF"}

package/dist/dev/core/{actor.d.ts → actors/actor.d.ts}

@@ -1,6 +1,6 @@
-import { Machine, MachineSnapshot } from "./machine.js";
+import { Machine, MachineSnapshot } from "../machine.js";
 
-//#region src/core/actor.d.ts
+//#region src/core/actors/actor.d.ts
 /**
  * Complete actor snapshot: finite state + non-finite context.
  * Extends `MachineSnapshot` with context — the non-finite data managed by the actor.

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

@@ -0,0 +1 @@
+{"version":3,"file":"actor.d.ts","names":[],"sources":["../../../../src/core/actors/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/actors/create-machine-actor.d.ts

@@ -0,0 +1,125 @@
+import { TaskLike } from "../tasks/task.js";
+import { SignalActor } from "./actor.js";
+
+//#region src/core/actors/create-machine-actor.d.ts
+/**
+ * Minimal interface for any runner that can be used with createMachineActor.
+ */
+interface RunnerLike {
+  schedule<Value = void, Err = unknown>(task: TaskLike<Value, Err>): Promise<Value>;
+  abortAll(): void;
+  destroy(): void;
+  whenSettled(callback: () => void): void;
+}
+/**
+ * Context passed to message handlers.
+ * `runner` is present and typed as the exact runner instance only when the
+ * definition includes a runner factory.
+ */
+type HandlerContext<UserState extends string, Context extends object, RunnerFactory extends (() => RunnerLike) | undefined> = {
+  transition: (to: UserState) => void; /** Context snapshot captured at dispatch time. Stale after any `setContext` call. */
+  context: Context;
+  /**
+   * Live untracked read of the current context. Use in async task closures that
+   * execute after the handler returns — e.g. `getCtx: getContext` passed to tasks
+   * scheduled on the runner, so each task reads the context committed by the
+   * previous task rather than the stale snapshot from dispatch time.
+   */
+  getContext: () => Context;
+  setContext: (next: Context) => void;
+} & (RunnerFactory extends (() => infer R) ? {
+  runner: R;
+} : object);
+/**
+ * Definition for a single user-defined state.
+ */
+type ActorStateDefinition<UserState extends string, Context extends object, Message extends {
+  type: string;
+}, RunnerFactory extends (() => RunnerLike) | undefined> = {
+  /**
+   * When the actor's runner settles while in this state, automatically
+   * transition to this state. The framework owns the generation-token logic —
+   * re-registering after each `runner.schedule()` call so that
+   * `abortAll()` + reschedule correctly supersedes stale callbacks.
+   */
+  onSettled?: UserState; /** Message handlers active in this state. Messages with no handler are silently dropped. */
+  on?: { [M in Message as M['type']]?: (message: Extract<Message, {
+    type: M['type'];
+  }>, ctx: HandlerContext<UserState, Context, RunnerFactory>) => void };
+};
+/**
+ * Full actor definition passed to `createMachineActor`.
+ *
+ * `UserState` is the set of domain-meaningful states. `'destroyed'` is always
+ * added by the framework as the implicit terminal state — do not include it here.
+ */
+type ActorDefinition<UserState extends string, Context extends object, Message extends {
+  type: string;
+}, RunnerFactory extends (() => RunnerLike) | undefined = undefined> = {
+  /**
+   * Runner factory — called once at `createMachineActor()` time.
+   * The runner lives for the full actor lifetime and is destroyed with it.
+   *
+   * @example
+   * runner: () => new SerialRunner()
+   */
+  runner?: RunnerFactory; /** Initial state. */
+  initial: UserState; /** Initial context. */
+  context: Context;
+  /**
+   * Per-state definitions. States with no definition silently drop all messages.
+   * All user-defined states must appear as keys in the `UserState` union.
+   */
+  states: Partial<Record<UserState, ActorStateDefinition<UserState, Context, Message, RunnerFactory>>>;
+};
+/** 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;
+}
+/**
+ * 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(...)));
+ *         }
+ *       }
+ *     }
+ *   }
+ * });
+ */
+declare function createMachineActor<UserState extends string, Context extends object, Message extends {
+  type: string;
+}, RunnerFactory extends (() => RunnerLike) | undefined = undefined>(def: ActorDefinition<UserState, Context, Message, RunnerFactory>): MessageActor<UserState | 'destroyed', Context, Message>;
+//#endregion
+export { ActorDefinition, ActorStateDefinition, HandlerContext, MessageActor, RunnerLike, createMachineActor };
+//# sourceMappingURL=create-machine-actor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-machine-actor.d.ts","names":[],"sources":["../../../../src/core/actors/create-machine-actor.ts"],"mappings":";;;;;;AAYA;UAAiB,UAAA;EACf,QAAA,8BAAsC,IAAA,EAAM,QAAA,CAAS,KAAA,EAAO,GAAA,IAAO,OAAA,CAAQ,KAAA;EAC3E,QAAA;EACA,OAAA;EACA,WAAA,CAAY,QAAA;AAAA;;;;;;KAYF,cAAA,gFAGmB,UAAA;EAE7B,UAAA,GAAa,EAAA,EAAI,SAAA,WApBoC;EAsBrD,OAAA,EAAS,OAAA;EAtB6B;;;;;;EA6BtC,UAAA,QAAkB,OAAA;EAClB,UAAA,GAAa,IAAA,EAAM,OAAA;AAAA,KAChB,aAAA;EAAwC,MAAA,EAAQ,CAAA;AAAA;;;;KAKzC,oBAAA;EAGQ,IAAA;AAAA,gCACW,UAAA;EAT1B;;;;;;EAiBH,SAAA,GAAY,SAAA,EA9BiB;EAgC7B,EAAA,WACQ,OAAA,IAAW,CAAA,aACf,OAAA,EAAS,OAAA,CAAQ,OAAA;IAAW,IAAA,EAAM,CAAA;EAAA,IAClC,GAAA,EAAK,cAAA,CAAe,SAAA,EAAW,OAAA,EAAS,aAAA;AAAA;;;;;;;KAWlC,eAAA;EAGQ,IAAA;AAAA,gCACW,UAAA;EArCuB;AAKtD;;;;;;EAyCE,MAAA,GAAS,aAAA,EAzBY;EA2BrB,OAAA,EAAS,SAAA,EA3BI;EA6Bb,OAAA,EAAS,OAAA;EA5B0B;;;;EAiCnC,MAAA,EAAQ,OAAA,CAAQ,MAAA,CAAO,SAAA,EAAW,oBAAA,CAAqB,SAAA,EAAW,OAAA,EAAS,OAAA,EAAS,aAAA;AAAA;;UAQrE,YAAA;EAA6E,IAAA;AAAA,WACpF,WAAA,CAAY,KAAA,EAAO,OAAA;EAC3B,IAAA,CAAK,OAAA,EAAS,OAAA;AAAA;;;;;;;;;;;;;;;;;;AAhChB;;;;;;;;;;;;;;;;;;;;;;iBA8EgB,kBAAA;EAGI,IAAA;AAAA,gCACW,UAAA,0BAAA,CAE7B,GAAA,EAAK,eAAA,CAAgB,SAAA,EAAW,OAAA,EAAS,OAAA,EAAS,aAAA,IACjD,YAAA,CAAa,SAAA,gBAAyB,OAAA,EAAS,OAAA"}

package/dist/{default/core → dev/core/actors}/create-machine-actor.js

@@ -1,6 +1,6 @@
-import { untrack, update } from "./signals/primitives.js";
-import { createMachineCore } from "./machine.js";
-//#region src/core/create-machine-actor.ts
+import { untrack, update } from "../signals/primitives.js";
+import { createMachineCore } from "../machine.js";
+//#region src/core/actors/create-machine-actor.ts
 /**
 * Creates a message-driven actor from a declarative definition.
 *

package/dist/dev/core/actors/create-machine-actor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-machine-actor.js","names":[],"sources":["../../../../src/core/actors/create-machine-actor.ts"],"sourcesContent":["import { createMachineCore } from '../machine';\nimport { untrack, update } from '../signals/primitives';\nimport type { TaskLike } from '../tasks/task';\nimport type { ActorSnapshot, SignalActor } from './actor';\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/actors/create-transition-actor.d.ts

@@ -0,0 +1,42 @@
+import { ActorSnapshot } from "./actor.js";
+import { Machine } from "../machine.js";
+
+//#region src/core/actors/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;
+}
+/**
+ * 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 })
+ * );
+ */
+declare function createTransitionActor<Context extends object, Message extends {
+  type: string;
+}>(initialContext: Context, reducer: (context: Context, message: Message) => Context): TransitionActor<Context, Message>;
+//#endregion
+export { TransitionActor, createTransitionActor };
+//# sourceMappingURL=create-transition-actor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-transition-actor.d.ts","names":[],"sources":["../../../../src/core/actors/create-transition-actor.ts"],"mappings":";;;;;;AAoBA;;;;;;;;;UAAiB,eAAA;EAA0D,IAAA;AAAA,WACjE,OAAA,CAAQ,aAAA,yBAAsC,OAAA;EACtD,IAAA,CAAK,OAAA,EAAS,OAAA;AAAA;;;;;;;AAuBhB;;;;;;;;;;iBAAgB,qBAAA;EAAgE,IAAA;AAAA,EAAA,CAC9E,cAAA,EAAgB,OAAA,EAChB,OAAA,GAAU,OAAA,EAAS,OAAA,EAAS,OAAA,EAAS,OAAA,KAAY,OAAA,GAChD,eAAA,CAAgB,OAAA,EAAS,OAAA"}

package/dist/dev/core/{create-transition-actor.js → actors/create-transition-actor.js}

@@ -1,6 +1,6 @@
-import { untrack, update } from "./signals/primitives.js";
-import { createMachineCore } from "./machine.js";
-//#region src/core/create-transition-actor.ts
+import { untrack, update } from "../signals/primitives.js";
+import { createMachineCore } from "../machine.js";
+//#region src/core/actors/create-transition-actor.ts
 /**
 * Creates a reducer-shaped actor from an initial context and a reducer function.
 *

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-transition-actor.js","names":[],"sources":["../../../../src/core/actors/create-transition-actor.ts"],"sourcesContent":["import type { Machine } from '../machine';\nimport { createMachineCore } from '../machine';\nimport { untrack, update } from '../signals/primitives';\nimport type { ActorSnapshot } from './actor';\n\n// =============================================================================\n// Definition types\n// =============================================================================\n\n/**\n * A reducer-shaped actor: `(context, message) => context`.\n *\n * No finite states — the snapshot carries `value: 'active' | 'destroyed'`\n * as a universal lifecycle marker rather than domain state. The interesting\n * state is entirely in the context, which is reactive via `snapshot`.\n *\n * Use this when the actor has context that needs to be reactive but no\n * meaningful state machine (e.g., a message-driven model with DOM side\n * effects). For actors that need per-state behavior, use `createMachineActor`.\n */\nexport interface TransitionActor<Context extends object, Message extends { type: string }>\n  extends Machine<ActorSnapshot<'active' | 'destroyed', Context>> {\n  send(message: Message): void;\n}\n\n// =============================================================================\n// Implementation\n// =============================================================================\n\n/**\n * Creates a reducer-shaped actor from an initial context and a reducer function.\n *\n * The reducer receives the current context and a message and returns the next\n * context. Returning the same reference (by identity) skips the signal update —\n * so early-returning `context` unchanged is both the no-op and the optimization.\n *\n * Side effects (e.g. DOM mutations) may be performed inside the reducer.\n * They run synchronously before the signal is updated.\n *\n * @example\n * const actor = createTransitionActor(\n *   { count: 0 },\n *   (context, message: { type: 'increment' }) => ({ count: context.count + 1 })\n * );\n */\nexport function createTransitionActor<Context extends object, Message extends { type: string }>(\n  initialContext: Context,\n  reducer: (context: Context, message: Message) => Context\n): TransitionActor<Context, Message> {\n  const { snapshotSignal, getState, transition } = createMachineCore<\n    'active' | 'destroyed',\n    ActorSnapshot<'active' | 'destroyed', Context>\n  >({ value: 'active', context: initialContext });\n\n  const getContext = (): Context => untrack(() => snapshotSignal.get().context);\n  const setContext = (context: Context): void => update(snapshotSignal, { context });\n\n  return {\n    get snapshot() {\n      return snapshotSignal;\n    },\n\n    send(message: Message): void {\n      if (getState() === 'destroyed') return;\n      const context = getContext();\n      const newContext = reducer(context, message);\n      if (newContext !== context) setContext(newContext);\n    },\n\n    destroy(): void {\n      if (getState() === 'destroyed') return;\n      transition('destroyed');\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA6CA,SAAgB,sBACd,gBACA,SACmC;CACnC,MAAM,EAAE,gBAAgB,UAAU,eAAe,kBAG/C;EAAE,OAAO;EAAU,SAAS;EAAgB,CAAC;CAE/C,MAAM,mBAA4B,cAAc,eAAe,KAAK,CAAC,QAAQ;CAC7E,MAAM,cAAc,YAA2B,OAAO,gBAAgB,EAAE,SAAS,CAAC;AAElF,QAAO;EACL,IAAI,WAAW;AACb,UAAO;;EAGT,KAAK,SAAwB;AAC3B,OAAI,UAAU,KAAK,YAAa;GAChC,MAAM,UAAU,YAAY;GAC5B,MAAM,aAAa,QAAQ,SAAS,QAAQ;AAC5C,OAAI,eAAe,QAAS,YAAW,WAAW;;EAGpD,UAAgB;AACd,OAAI,UAAU,KAAK,YAAa;AAChC,cAAW,YAAY;;EAE1B"}