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

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

@@ -0,0 +1 @@
+{"version":3,"file":"text-segment-load-pipeline.js","names":[],"sources":["../../../../src/playback/primitives/text-segment-load-pipeline.ts"],"sourcesContent":["/**\n * The text-track **load pipeline** — the step vocabulary and base steps a text-segment\n * loader runs, the text mirror of `segment-load-pipeline`. Extracted from the loader\n * actor so the \"what\" (the composable steps) is separable from the \"how\" (scheduling).\n * A pipeline is a flat, ordered list of {@link TextLoadStep}s (text has a single op\n * type, so no per-type `Record`); the default is `resolveCues → dispatchCues`, and a\n * composition can insert its own steps (e.g. non-zero-PTS cue rebase) without the\n * loader knowing.\n *\n * The dispatch step reaches its cue sink through the structural {@link CueSink} seam\n * rather than the concrete `TextTracksActor` type — the loader folds the real actor\n * into `config`, and it satisfies the seam by structure — so this module names no\n * actor and stays DOM-free (generic over the cue type `C`).\n */\nimport type { AnySlotMap } from '../../core/composition/create-composition';\nimport type { Cue, Segment } from '../../media/types';\nimport type { AddCuesMessage } from './text-track-messages';\n\n// ============================================================================\n// SINK SEAM\n// ============================================================================\n\n/**\n * The structural view of a cue sink the base steps use — just the `send`\n * {@link dispatchCuesStep} needs. The concrete `TextTracksActor` satisfies it by\n * structure, so the pipeline names no actor.\n */\nexport interface CueSink<C extends Cue = Cue> {\n  send(message: AddCuesMessage<C>): void;\n}\n\n// ============================================================================\n// STEP MODEL\n// ============================================================================\n\n/**\n * Resolves a text-track segment URL into the array of cues it contains.\n *\n * \"Resolve\" because the fn covers both network fetch and parse into the\n * domain model. Host-agnostic — the concrete resolver (e.g. the\n * browser's native VTT resolver) is supplied at engine-assembly time,\n * so this stays DOM-free. A pure `url → cues` primitive (the text\n * analog of the v/a loader's `fetchBytes`); composition-awareness lives in\n * the injected {@link TextLoadStep}s, not here.\n */\nexport type TextTrackSegmentResolver<C extends Cue = Cue> = (url: string) => Promise<C[]>;\n\n/** Internal load-task descriptor — one segment fetch + dispatch unit. */\nexport interface TextLoadTask {\n  segment: Segment;\n  trackId: string;\n}\n\n/**\n * A text load in mid-pipeline — the text analog of the v/a loader's `Frame`.\n * `resolveCuesStep` fills `cues`; `dispatchCuesStep` sends them. `metadata` is\n * opaque header metadata a resolve step may attach for a later step to read\n * (e.g. relocation stashes the `X-TIMESTAMP-MAP` correlation here for its rebase\n * step). Typed `unknown` so the generic loader stays host-agnostic — the step\n * that reads it knows its concrete shape (mirrors `StepDeps.state`).\n */\nexport interface TextFrame<C extends Cue = Cue> {\n  readonly op: TextLoadTask;\n  cues?: C[];\n  metadata?: unknown;\n}\n\n/**\n * One stage of a text message pipeline — the text analog of the v/a loader's\n * `LoadStep`. Mutates the {@link TextFrame} in place and may be async; the runner\n * checks `signal.aborted` before each step and passes the actor's\n * {@link TextStepDeps} on every call, so a stateless step (`resolveCuesStep`) is a\n * plain value and a step that needs composition signals (relocation's cue rebase)\n * reads them from `deps` at call time.\n */\nexport type TextLoadStep<C extends Cue = Cue> = (\n  frame: TextFrame<C>,\n  signal: AbortSignal,\n  deps: TextStepDeps\n) => void | Promise<void>;\n\n/**\n * The uniform passthrough handed to each {@link TextLoadStep} — the composition triple,\n * the text analog of `StepDeps`. `state`/`context` are the composition signal maps;\n * `config` is the threaded config with the loader's wiring folded in (see\n * {@link textStepWiring} + `createTextTrackSegmentLoaderActor`). Typed loose: composition\n * steps read `state`; base steps read the folded wiring off `config`.\n */\nexport interface TextStepDeps {\n  state: AnySlotMap;\n  context: AnySlotMap;\n  config: object;\n}\n\n/**\n * Base-step view of the loader's wiring, folded into `config` by\n * `createTextTrackSegmentLoaderActor` so base steps read it from the uniform passthrough\n * — present in both composition and standalone use. `config` is loose (`object`), so\n * assert the shape here (mirrors the v/a loader's `stepWiring`). The sink is the\n * structural {@link CueSink}, not the concrete actor.\n */\nexport function textStepWiring<C extends Cue>(\n  deps: TextStepDeps\n): { textTracksActor: CueSink<C>; resolveSegment: TextTrackSegmentResolver<C> } {\n  return deps.config as { textTracksActor: CueSink<C>; resolveSegment: TextTrackSegmentResolver<C> };\n}\n\n/**\n * Builds the ordered step list, called **once per actor** (mirrors the v/a loader's\n * `MessagePipelines`, but text has a single op type so it's a flat array, not a\n * `Record`). The default ({@link DEFAULT_TEXT_MESSAGE_PIPELINES}) is\n * `resolveCues → dispatchCues`; a non-zero-PTS composition returns a list that\n * inserts a cue-rebase step (see `relocatingTextPipelines`), so the loader stays\n * oblivious to relocation.\n */\nexport type TextMessagePipelines<C extends Cue = Cue> = () => TextLoadStep<C>[];\n\n// ============================================================================\n// BASE STEPS\n// ============================================================================\n\n// Base steps are generic over the cue type `C` (generic arrow consts, not\n// `TextLoadStep<Cue>` values): each touches `C` — `frame.cues: C[]` and the\n// `C`-typed `textStepWiring<C>` — so a `Cue`-typed const wouldn't slot into a\n// `VTTCue` pipeline. A generic function assigns to any `TextLoadStep<C>`.\n\n/** Resolve the op's cues (via the injected host primitive) into the frame. The text analog of `fetchStep`. */\nexport const resolveCuesStep = async <C extends Cue>(\n  frame: TextFrame<C>,\n  signal: AbortSignal,\n  deps: TextStepDeps\n): Promise<void> => {\n  const cues = await textStepWiring<C>(deps).resolveSegment(frame.op.segment.url);\n  if (signal.aborted) return;\n  frame.cues = cues;\n};\n\n/** Dispatch the frame's cues to the TextTracksActor as `add-cues`. The text analog of `dispatchStep`. */\nexport const dispatchCuesStep = <C extends Cue>(\n  frame: TextFrame<C>,\n  _signal: AbortSignal,\n  deps: TextStepDeps\n): void => {\n  const { op } = frame;\n  textStepWiring<C>(deps).textTracksActor.send({\n    type: 'add-cues',\n    meta: {\n      trackId: op.trackId,\n      id: op.segment.id,\n      startTime: op.segment.startTime,\n      duration: op.segment.duration,\n    },\n    cues: frame.cues ?? [],\n  });\n};\n\n/** Tier 0 default: resolve then dispatch. No relocation vocabulary. */\nexport const DEFAULT_TEXT_MESSAGE_PIPELINES = <C extends Cue>(): TextLoadStep<C>[] => [\n  resolveCuesStep,\n  dispatchCuesStep,\n];\n"],"mappings":";;;;;;;;AAqGA,SAAgB,eACd,MAC8E;CAC9E,OAAO,KAAK;AACd;;AAsBA,MAAa,kBAAkB,OAC7B,OACA,QACA,SACkB;CAClB,MAAM,OAAO,MAAM,eAAkB,IAAI,CAAC,CAAC,eAAe,MAAM,GAAG,QAAQ,GAAG;CAC9E,IAAI,OAAO,SAAS;CACpB,MAAM,OAAO;AACf;;AAGA,MAAa,oBACX,OACA,SACA,SACS;CACT,MAAM,EAAE,OAAO;CACf,eAAkB,IAAI,CAAC,CAAC,gBAAgB,KAAK;EAC3C,MAAM;EACN,MAAM;GACJ,SAAS,GAAG;GACZ,IAAI,GAAG,QAAQ;GACf,WAAW,GAAG,QAAQ;GACtB,UAAU,GAAG,QAAQ;EACvB;EACA,MAAM,MAAM,QAAQ,CAAC;CACvB,CAAC;AACH;;AAGA,MAAa,uCAAyE,CACpF,iBACA,gBACF"}

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

@@ -0,0 +1,61 @@
+//#region src/playback/primitives/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/primitives/track-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"track-types.js","names":[],"sources":["../../../../src/playback/primitives/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;AACb;;;;;;AAOA,MAAa,oBAAoB;CAC/B,MAAM;CACN,aAAa;CACb,UAAU;CACV,WAAW;AACb;;;;;;;;;;AAWA,MAAa,mBAAmB;CAC9B,MAAM;CACN,aAAa;CACb,WAAW;AACb"}

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

@@ -0,0 +1,26 @@
+import { Machine, MachineSnapshot } from "../machine.js";
+//#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.
+ */
+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/actors/actor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor.d.ts","names":[],"sources":["../../../../src/core/actors/actor.ts"],"mappings":";;;;;;UAeiB,cAAc,sBAAsB,gCAAgC,gBAAgB;EACnG,SAAS;;;UAIM,YAAY,sBAAsB,gCACzC,QAAQ,cAAc,OAAO;;;;;;;UAQtB,cAAc;EAAkB;;EAC/C,KAAK,SAAS;EACd"}

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

@@ -0,0 +1,128 @@
+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":";;;;;;UAYiB;EACf,SAAS,cAAc,eAAe,MAAM,SAAS,OAAO,OAAO,QAAQ;EAC3E;EACA;EACA,YAAY;;;;;;;KAYF,eACV,0BACA,wBACA,6BAA6B;EAE7B,aAAa,IAAI;;EAEjB,SAAS;;;;;;;EAOT,kBAAkB;EAClB,aAAa,MAAM;KAChB,mCAAkC;EAAM,QAAQ;;;;;KAKzC,qBACV,0BACA,wBACA;EAAkB;GAClB,6BAA6B;;;;;;;EAQ7B,YAAY;;EAEZ,QACG,KAAK,WAAW,cACf,SAAS,QAAQ;IAAW,MAAM;MAClC,KAAK,eAAe,WAAW,SAAS;;;;;;;;KAWlC,gBACV,0BACA,wBACA;EAAkB;GAClB,6BAA6B;;;;;;;;EAS7B,SAAS;;EAET,SAAS;;EAET,SAAS;;;;;EAKT,QAAQ,QAAQ,OAAO,WAAW,qBAAqB,WAAW,SAAS,SAAS;;;UAQrE,aAAa,sBAAsB,wBAAwB;EAAkB;WACpF,YAAY,OAAO;EAC3B,KAAK,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8CA,mBACd,0BACA,wBACA;EAAkB;GAClB,6BAA6B,qCAE7B,KAAK,gBAAgB,WAAW,SAAS,SAAS,iBACjD,aAAa,yBAAyB,SAAS"}

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

@@ -0,0 +1,91 @@
+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.
+*
+* 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/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,SAAS;CAC5B,MAAM,EAAE,gBAAgB,UAAU,eAAe,kBAAgE;EAC/G,OAAO,IAAI;EACX,SAAS,IAAI;CACf,CAAC;CAED,MAAM,mBAA4B,cAAc,eAAe,IAAI,CAAC,CAAC,OAAO;CAE5E,MAAM,cAAc,YAA2B;EAC7C,OAAO,gBAAgB,EAAE,QAAQ,CAAC;CACpC;CAEA,OAAO;EACL,IAAI,WAAW;GACb,OAAO;EACT;EAEA,KAAK,SAAwB;GAC3B,MAAM,QAAQ,SAAS;GACvB,IAAI,UAAU,aAAa;GAE3B,MAAM,UADW,IAAI,OAAO,MACJ,EAAE,KAAK,QAAQ;GAGvC,IAAI,CAAC,SAAS;GACd,QAAQ,SAAS;IACf,SAAS,WAAW;IACpB;IACA,aAAa,OAAkB,WAAW,EAAe;IACzD;IACA,GAAI,SAAS,EAAE,OAAO,IAAI,CAAC;GAC7B,CAAsD;GAEtD,MAAM,WAAW,SAAS;GAC1B,IAAI,aAAa,aAAa;IAC5B,MAAM,cAAc,IAAI,OAAO;IAC/B,IAAI,aAAa,aAAa,QAAQ;KACpC,MAAM,cAAc,YAAY;KAChC,OAAO,kBAAkB;MACvB,IAAI,SAAS,MAAM,UAAU;MAC7B,WAAW,WAAW;KACxB,CAAC;IACH;GACF;EACF;EAEA,UAAgB;GACd,IAAI,SAAS,MAAM,aAAa;GAChC,QAAQ,QAAQ;GAChB,WAAW,WAAW;EACxB;CACF;AACF"}

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

@@ -0,0 +1,41 @@
+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":";;;;;;;;;;;;;;UAoBiB,gBAAgB,wBAAwB;EAAkB;WACjE,QAAQ,sCAAsC;EACtD,KAAK,SAAS;;;;;;;;;;;;;;;;;;iBAuBA,sBAAsB,wBAAwB;EAAkB;GAC9E,gBAAgB,SAChB,UAAU,SAAS,SAAS,SAAS,YAAY,UAChD,gBAAgB,SAAS"}

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

@@ -0,0 +1,46 @@
+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.
+*
+* 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

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;CAAe,CAAC;CAE9C,MAAM,mBAA4B,cAAc,eAAe,IAAI,CAAC,CAAC,OAAO;CAC5E,MAAM,cAAc,YAA2B,OAAO,gBAAgB,EAAE,QAAQ,CAAC;CAEjF,OAAO;EACL,IAAI,WAAW;GACb,OAAO;EACT;EAEA,KAAK,SAAwB;GAC3B,IAAI,SAAS,MAAM,aAAa;GAChC,MAAM,UAAU,WAAW;GAC3B,MAAM,aAAa,QAAQ,SAAS,OAAO;GAC3C,IAAI,eAAe,SAAS,WAAW,UAAU;EACnD;EAEA,UAAgB;GACd,IAAI,SAAS,MAAM,aAAa;GAChC,WAAW,WAAW;EACxB;CACF;AACF"}