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

package/README.md

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

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

package/dist/default/core/composition/create-composition.js

@@ -0,0 +1,85 @@
+import { signal } from "../signals/primitives.js";
+//#region src/core/composition/create-composition.ts
+/**
+* Create a composition from a set of behaviors.
+*
+* Composition unions the behaviors' declared `stateKeys` / `contextKeys`
+* to know which signals to create. Each signal is seeded from
+* `initialState` / `initialContext` when supplied, defaulting to
+* `undefined`. Behaviors are responsible for writing their own slots
+* once their preconditions are met.
+*
+* Cross-behavior type conflicts (e.g. two behaviors disagreeing on a
+* field's type) surface as a compose-time type error via
+* `ValidateComposition`.
+*
+* @example
+* ```ts
+* const composition = createComposition([resolvePresentation, switchVideoTrack], {
+*   config: { parsePresentation: parseMultivariantPlaylist, initialBandwidth: 2_000_000 },
+*   initialState: { bandwidthState: { fastEstimate: 0, ... } },
+* });
+* ```
+*/
+/**
+* Create a typed signal map for a given set of keys, seeded from an
+* optional partial initial value.
+*
+* Pipeline: `Set` dedupes the iterable (insertion order preserved, so
+* first occurrence wins) → `Object.fromEntries` materializes one
+* `signal()` per unique key, seeded from `initial[key]` or `undefined`.
+*
+* Per-key value types live in TypeScript only — at runtime every signal
+* is `Signal<unknown>`. The boundary cast at the return narrows the wide
+* `Record<PropertyKey, Signal<unknown>>` shape to the caller's expected
+* per-key types from `S`.
+*
+* Used by `createComposition` to derive engine state/context maps from
+* the union of behaviors' declared `stateKeys` / `contextKeys`.
+*
+* @example
+* ```ts
+* interface State { count?: number; label?: string }
+* const state = buildSignalMap<State>(['count', 'label'], { count: 5 });
+* state.count.get(); // 5
+* state.label.get(); // undefined
+* ```
+*/
+function buildSignalMap(keys, initial) {
+	const init = initial;
+	const uniqueKeys = new Set(keys);
+	return Object.fromEntries([...uniqueKeys].map((key) => [key, signal(init[key])]));
+}
+function createComposition(behaviors, options) {
+	const validBehaviors = behaviors;
+	const state = buildSignalMap(validBehaviors.flatMap((b) => b.stateKeys), options?.initialState ?? {});
+	const context = buildSignalMap(validBehaviors.flatMap((b) => b.contextKeys), options?.initialContext ?? {});
+	const deps = {
+		state,
+		context,
+		config: options?.config ?? {}
+	};
+	const cleanups = validBehaviors.map((behavior) => behavior.setup(deps));
+	return {
+		state,
+		context,
+		async destroy() {
+			const results = [];
+			for (const cleanup of cleanups) {
+				if (cleanup == null) continue;
+				if (typeof cleanup === "function") results.push(cleanup());
+				else if ("destroy" in cleanup) results.push(cleanup.destroy());
+			}
+			await Promise.all(results);
+			for (const sig of Object.values(state)) sig.set(void 0);
+			for (const sig of Object.values(context)) sig.set(void 0);
+		}
+	};
+}
+function defineBehavior(behavior) {
+	return behavior;
+}
+//#endregion
+export { buildSignalMap, createComposition, defineBehavior };
+
+//# sourceMappingURL=create-composition.js.map

package/dist/default/core/composition/create-composition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-composition.js","names":[],"sources":["../../../../src/core/composition/create-composition.ts"],"sourcesContent":["import { type ReadonlySignal, type Signal, signal } from '../signals/primitives';\n\n/**\n * Cleanup returned by a behavior. Behaviors may return:\n * - `void` / `undefined` — no cleanup needed\n * - A function — called on destroy (may return a Promise)\n * - An object with `destroy()` — called on destroy (may return a Promise)\n */\nexport type BehaviorCleanup = void | (() => void | Promise<void>) | { destroy(): void | Promise<void> };\n\n/**\n * A signal map keyed by the fields of `S`. Each field is a writable signal.\n *\n * Optional fields on `S` map to required signal slots whose value type\n * includes `undefined`, ensuring every key has a signal even when the\n * underlying value is absent.\n *\n * Used in two roles:\n * - Engine-side **construction**: `Composition<S, C>` exposes its public\n *   surface as `StateSignals<S>` (everything writable) so external code\n *   can read or write any slot.\n * - Behavior **input convenience**: a behavior that writes to every slot\n *   can type its setup state param as `StateSignals<{ ... }>` rather than\n *   spelling out per-slot `Signal<T>` types.\n *\n * Behaviors that mix read-only and writable slots type the setup param\n * directly as a slot map (`{ x: Signal<T>; y: ReadonlySignal<U> }`)\n * instead of going through `StateSignals<>`.\n */\nexport type StateSignals<S extends object> = { [K in keyof S]-?: Signal<S[K]> };\n\n/**\n * A signal map keyed by the fields of `C`. Each field is a writable signal\n * for a platform object or actor reference. Same dual role as\n * `StateSignals<S>` — see its docblock.\n */\nexport type ContextSignals<C extends object> = { [K in keyof C]-?: Signal<C[K]> };\n\n/**\n * Slot-map shape — a record where each value is at least a `ReadonlySignal`.\n * `Signal<T>` is structurally a subtype of `ReadonlySignal<T>` (it adds\n * `.set()`), so a writable slot satisfies this bound too.\n *\n * This is the bound used for behavior `state` / `context` slot maps. It\n * lets a single behavior declare a *heterogeneous* slot map where some\n * slots are `Signal<T>` (writable) and others are `ReadonlySignal<T>`\n * (read-only) — making read/write intent explicit at the call site and\n * giving body-level enforcement (TS rejects `.set()` on a read-only slot).\n */\nexport type AnySlotMap = Record<PropertyKey, ReadonlySignal<unknown>>;\n\n/**\n * The deps object passed to each behavior by the composition.\n *\n * - `state` — slot map for state fields (reactive data). Per-slot read/\n *   write intent expressed via `Signal<T>` vs `ReadonlySignal<T>`.\n * - `context` — slot map for platform objects and actor references.\n * - `config` — static configuration, passed once at composition creation.\n */\nexport interface BehaviorDeps<StateMap extends AnySlotMap, ContextMap extends AnySlotMap, Cfg extends object> {\n  state: StateMap;\n  context: ContextMap;\n  config: Cfg;\n}\n\n/**\n * A behavior announces the state and context keys it needs alongside a\n * `setup` function that receives deps (state, context, config) and\n * returns an optional cleanup handle.\n *\n * The `stateKeys` / `contextKeys` declarations are the runtime expression\n * of the behavior's contract — the caller (e.g. `createComposition`) uses\n * them to know which signals to provide. The setup parameter type\n * declares the *slot map* (per-slot `Signal<T>` vs `ReadonlySignal<T>`);\n * together they form a complete contract.\n *\n * Manual `Behavior<>` literals (e.g. engine wrappers that forward keys\n * from a wrapped behavior, or pass-through behaviors like `shareSignals`)\n * opt out of exhaustiveness — the type alias is permissive (subset).\n * Source behaviors should use `defineBehavior` to get exhaustiveness\n * enforcement at the call site.\n */\nexport interface Behavior<\n  StateMap extends AnySlotMap = Empty,\n  ContextMap extends AnySlotMap = Empty,\n  Cfg extends object = Empty,\n> {\n  /** State keys this behavior reads/writes. Subset of `keyof StateMap`. */\n  stateKeys: readonly (keyof StateMap)[];\n  /** Context keys this behavior reads/writes. Subset of `keyof ContextMap`. */\n  contextKeys: readonly (keyof ContextMap)[];\n  setup: (deps: BehaviorDeps<StateMap, ContextMap, Cfg>) => BehaviorCleanup;\n}\n\n// =============================================================================\n// Behavior type inference\n// =============================================================================\n\n/** A behavior with an unconstrained setup — used as a generic bound. */\ntype AnyBehavior = {\n  stateKeys: readonly PropertyKey[];\n  contextKeys: readonly PropertyKey[];\n  setup: (deps: any) => BehaviorCleanup;\n};\n\n/** Extract the deps type from a behavior's setup function. */\ntype DepsOf<B> = B extends { setup: (deps: infer D, ...args: any[]) => any } ? D : never;\n\n/**\n * Empty-object fallback used when a behavior omits state, context, or config.\n *\n * Using `{}` rather than `object` is deliberate — `object & {x: T}` collapses\n * to `{x: never}` under TS's union-to-intersection conversion in some inference\n * contexts (likely a TS quirk around the `object` upper bound), whereas\n * `{} & {x: T}` simplifies cleanly to `{x: T}`.\n */\n// biome-ignore lint/complexity/noBannedTypes: see comment above\ntype Empty = {};\n\n/**\n * Unwrap a signal map back to its state/context shape.\n *\n * Inferring through `{ get(): infer V }` rather than `Signal<infer V>`\n * sidesteps `Signal`'s nominal/invariance behaviour — the conditional\n * matches structurally on the read side, and `V` is inferred covariantly.\n */\ntype UnwrapSignals<M> = M extends object ? { [K in keyof M]: M[K] extends { get(): infer V } ? V : never } : Empty;\n\n/** Infer the state shape a behavior requires from its deps parameter. */\nexport type InferBehaviorState<F> = DepsOf<F> extends { state: infer M } ? UnwrapSignals<M> : Empty;\n\n/** Infer the context shape a behavior requires from its deps parameter. */\nexport type InferBehaviorContext<F> = DepsOf<F> extends { context: infer M } ? UnwrapSignals<M> : Empty;\n\n/** Infer the config shape a behavior requires from its deps parameter. */\nexport type InferBehaviorConfig<F> = DepsOf<F> extends { config: infer C extends object } ? C : Empty;\n\n/**\n * Recursively intersect a per-behavior projection across the tuple.\n *\n * Iterating over the tuple directly avoids `UnionToIntersection`'s\n * function-contravariance trick, which produces unstable intersections\n * (collapsing concrete fields to `never` or unrelated types) when one of the\n * union members is the empty `{}` fallback.\n */\ntype IntersectBehaviors<Behaviors extends readonly AnyBehavior[], Project extends object> = Behaviors extends readonly [\n  infer First extends AnyBehavior,\n  ...infer Rest extends readonly AnyBehavior[],\n]\n  ? Apply<Project, First> & IntersectBehaviors<Rest, Project>\n  : Empty;\n\n/**\n * Apply a projection (one of the marker types below) to a single behavior.\n * Encoded as a discriminated dispatch so the recursion above can stay generic\n * and we don't have to write three near-identical recursive types.\n */\ntype Apply<Project extends object, F> = Project extends { kind: 'state' }\n  ? InferBehaviorState<F>\n  : Project extends { kind: 'context' }\n    ? InferBehaviorContext<F>\n    : Project extends { kind: 'config' }\n      ? InferBehaviorConfig<F>\n      : never;\n\ntype StateProjection = { kind: 'state' };\ntype ContextProjection = { kind: 'context' };\ntype ConfigProjection = { kind: 'config' };\n\n/** Resolve the combined state shape from an array of behaviors (intersection of all requirements). */\nexport type ResolveBehaviorState<Behaviors extends readonly AnyBehavior[]> =\n  IntersectBehaviors<Behaviors, StateProjection> extends infer R extends object ? R : Empty;\n\n/** Resolve the combined context shape from an array of behaviors (intersection of all requirements). */\nexport type ResolveBehaviorContext<Behaviors extends readonly AnyBehavior[]> =\n  IntersectBehaviors<Behaviors, ContextProjection> extends infer R extends object ? R : Empty;\n\n/** Resolve the combined config shape from an array of behaviors (intersection of all requirements). */\nexport type ResolveBehaviorConfig<Behaviors extends readonly AnyBehavior[]> =\n  IntersectBehaviors<Behaviors, ConfigProjection> extends infer R extends object ? R : Empty;\n\n/**\n * True if any property in `T` collapsed to `undefined` or `never` — indicating\n * a type conflict from intersecting incompatible behavior requirements.\n *\n * - Required conflicts: `{ v: number } & { v: string }` → `{ v: never }` — caught via `[never] extends [undefined]`\n * - Optional conflicts: `{ v?: number } & { v?: string }` → `{ v?: undefined }` — caught directly\n */\ntype HasConflict<T extends object> = true extends {\n  [K in keyof T]: [T[K]] extends [undefined] ? true : never;\n}[keyof T]\n  ? true\n  : false;\n\n// =============================================================================\n// Composition validation\n// =============================================================================\n\n/**\n * Validate that a behavior composition has no type conflicts.\n * Returns the behaviors tuple if valid, or an error message type if conflicts are detected.\n *\n * State, context, and config are all checked the same way — by intersecting\n * each behavior's requirement and looking for collapsed fields. The\n * intersection-based check applies the same rule to context as to state, so\n * two behaviors that disagree on a context field's type (e.g. `Surface` vs\n * `VideoSurface`) surface a conflict at compose time. The prior subtype-based\n * approach for owners is gone — the unified rule is simpler and catches the\n * cases where two behaviors silently agreed on a wider supertype.\n */\ntype ValidateComposition<Behaviors extends readonly AnyBehavior[]> =\n  HasConflict<ResolveBehaviorState<Behaviors>> extends true\n    ? 'Error: behaviors have conflicting state types'\n    : HasConflict<ResolveBehaviorContext<Behaviors>> extends true\n      ? 'Error: behaviors have conflicting context types'\n      : HasConflict<ResolveBehaviorConfig<Behaviors>> extends true\n        ? 'Error: behaviors have conflicting config types'\n        : [...Behaviors];\n\n// =============================================================================\n// Composition\n// =============================================================================\n\n/**\n * A composition of behaviors with shared state and context signal maps.\n */\nexport interface Composition<S extends object, C extends object> {\n  state: StateSignals<S>;\n  context: ContextSignals<C>;\n  destroy(): Promise<void>;\n}\n\n/**\n * Options for `createComposition`.\n *\n * Composition derives the state and context signal maps from each\n * behavior's declared `stateKeys` / `contextKeys`; `initialState` and\n * `initialContext` seed those signals at creation time. Any unseeded\n * signal starts as `undefined`.\n */\nexport interface CompositionOptions<S extends object, C extends object, Cfg extends object> {\n  /** Static configuration passed to every behavior. */\n  config?: Cfg;\n  /** Initial values for state signals — any subset of `keyof S`. */\n  initialState?: Partial<S>;\n  /** Initial values for context signals — any subset of `keyof C`. */\n  initialContext?: Partial<C>;\n}\n\n/**\n * Create a composition from a set of behaviors.\n *\n * Composition unions the behaviors' declared `stateKeys` / `contextKeys`\n * to know which signals to create. Each signal is seeded from\n * `initialState` / `initialContext` when supplied, defaulting to\n * `undefined`. Behaviors are responsible for writing their own slots\n * once their preconditions are met.\n *\n * Cross-behavior type conflicts (e.g. two behaviors disagreeing on a\n * field's type) surface as a compose-time type error via\n * `ValidateComposition`.\n *\n * @example\n * ```ts\n * const composition = createComposition([resolvePresentation, switchVideoTrack], {\n *   config: { parsePresentation: parseMultivariantPlaylist, initialBandwidth: 2_000_000 },\n *   initialState: { bandwidthState: { fastEstimate: 0, ... } },\n * });\n * ```\n */\n/**\n * Create a typed signal map for a given set of keys, seeded from an\n * optional partial initial value.\n *\n * Pipeline: `Set` dedupes the iterable (insertion order preserved, so\n * first occurrence wins) → `Object.fromEntries` materializes one\n * `signal()` per unique key, seeded from `initial[key]` or `undefined`.\n *\n * Per-key value types live in TypeScript only — at runtime every signal\n * is `Signal<unknown>`. The boundary cast at the return narrows the wide\n * `Record<PropertyKey, Signal<unknown>>` shape to the caller's expected\n * per-key types from `S`.\n *\n * Used by `createComposition` to derive engine state/context maps from\n * the union of behaviors' declared `stateKeys` / `contextKeys`.\n *\n * @example\n * ```ts\n * interface State { count?: number; label?: string }\n * const state = buildSignalMap<State>(['count', 'label'], { count: 5 });\n * state.count.get(); // 5\n * state.label.get(); // undefined\n * ```\n */\nexport function buildSignalMap<S extends object>(\n  keys: Iterable<PropertyKey>,\n  initial: Partial<S>\n): { [K in keyof S]-?: Signal<S[K]> } {\n  const init = initial as Record<PropertyKey, unknown>;\n  const uniqueKeys = new Set(keys);\n  return Object.fromEntries([...uniqueKeys].map((key) => [key, signal(init[key])])) as {\n    [K in keyof S]-?: Signal<S[K]>;\n  };\n}\n\nexport function createComposition<const Behaviors extends readonly AnyBehavior[]>(\n  behaviors: ValidateComposition<Behaviors>,\n  options?: CompositionOptions<\n    ResolveBehaviorState<Behaviors>,\n    ResolveBehaviorContext<Behaviors>,\n    ResolveBehaviorConfig<Behaviors>\n  >\n): Composition<ResolveBehaviorState<Behaviors>, ResolveBehaviorContext<Behaviors>> {\n  type S = ResolveBehaviorState<Behaviors>;\n  type C = ResolveBehaviorContext<Behaviors>;\n  type Cfg = ResolveBehaviorConfig<Behaviors>;\n\n  // ValidateComposition<Behaviors> is `[...Behaviors]` on success, an error\n  // string on conflict. The function body only runs when the call typechecks\n  // (i.e. the success case), so iterating as the behavior tuple is sound.\n  const validBehaviors = behaviors as unknown as readonly AnyBehavior[];\n\n  const state = buildSignalMap<S>(\n    validBehaviors.flatMap((b) => b.stateKeys),\n    options?.initialState ?? {}\n  );\n  const context = buildSignalMap<C>(\n    validBehaviors.flatMap((b) => b.contextKeys),\n    options?.initialContext ?? {}\n  );\n\n  const deps: BehaviorDeps<StateSignals<S>, ContextSignals<C>, Cfg> = {\n    state,\n    context,\n    config: (options?.config ?? {}) as Cfg,\n  };\n  const cleanups = validBehaviors.map((behavior) => behavior.setup(deps));\n\n  return {\n    state,\n    context,\n    async destroy() {\n      const results: (void | Promise<void>)[] = [];\n      for (const cleanup of cleanups) {\n        if (cleanup == null) continue;\n        if (typeof cleanup === 'function') {\n          results.push(cleanup());\n        } else if ('destroy' in cleanup) {\n          results.push(cleanup.destroy());\n        }\n      }\n      await Promise.all(results);\n      // Reset every signal to undefined as a final cleanup, matching the\n      // prior post-destroy `owners.set({})` semantics. A later stage will\n      // move per-signal cleanup into the behaviors that own the writes.\n      for (const sig of Object.values(state) as Signal<unknown>[]) sig.set(undefined);\n      for (const sig of Object.values(context) as Signal<unknown>[]) sig.set(undefined);\n    },\n  };\n}\n\n// =============================================================================\n// defineBehavior — typed factory with key/param consistency enforcement\n// =============================================================================\n\n/**\n * Compose-time exhaustiveness check.\n *\n * Adds a phantom error tag to the parameter shape when `Keys` does not\n * cover every key in `Slot`. The user's value won't satisfy the phantom\n * field requirement, so TS surfaces the failure at the call site with a\n * descriptive message. When exhaustive, the tag is `Empty` and adds no\n * constraint.\n */\ntype ExhaustiveKeys<Keys extends readonly PropertyKey[], Slot extends object, Name extends string> = [\n  keyof Slot,\n] extends [Keys[number]]\n  ? Empty\n  : { [K in `Error: ${Name}Keys must list every key in the typed slice`]: Exclude<keyof Slot, Keys[number]> };\n\n/**\n * Typed factory for behaviors that enforces single-behavior key/param\n * consistency: declared `stateKeys` must equal `keyof S` (where `S` is\n * inferred from the setup's `state` parameter type), and same for\n * `contextKeys` / `C`.\n *\n * The `const` modifier on `SK` / `CK` captures literal tuples so e.g.\n * `stateKeys: ['preload']` infers as `readonly ['preload']`, no `as\n * const` needed at the call site.\n *\n * Cross-behavior consistency at `createComposition` is unchanged — the\n * existing `IntersectBehaviors` machinery still runs over each\n * behavior's setup param type.\n *\n * @example\n * ```ts\n * export const syncPreload = defineBehavior({\n *   stateKeys: ['preload'],\n *   contextKeys: ['mediaElement'],\n *   setup: ({ state, context }: {\n *     state: StateSignals<{ preload?: 'auto' | 'metadata' | 'none' }>;\n *     context: ContextSignals<{ mediaElement?: HTMLMediaElement | undefined }>;\n *   }) => { ... },\n * });\n * ```\n */\n/**\n * Deps shape for a behavior whose deps slot is empty (no keys). When a\n * slot is empty, the corresponding deps field is optional — callers\n * (typically tests) can omit it, and it defaults to `{}` at runtime via\n * `createComposition`.\n *\n * When a slot has at least one key, the behavior reads `state.foo` /\n * `context.bar` / `config.baz` and we need the field to be required so\n * the access is type-safe.\n */\ntype RequireIfNonEmpty<Key extends string, T extends object> = keyof T extends never\n  ? { [K in Key]?: T }\n  : { [K in Key]: T };\n\ntype DepsForCfg<StateMap extends AnySlotMap, ContextMap extends AnySlotMap, Cfg extends object> = RequireIfNonEmpty<\n  'state',\n  StateMap\n> &\n  RequireIfNonEmpty<'context', ContextMap> &\n  RequireIfNonEmpty<'config', Cfg>;\n\nexport function defineBehavior<\n  StateMap extends AnySlotMap = Empty,\n  ContextMap extends AnySlotMap = Empty,\n  Cfg extends object = Empty,\n  const SK extends readonly (keyof StateMap)[] = readonly [],\n  const CK extends readonly (keyof ContextMap)[] = readonly [],\n  R extends BehaviorCleanup = BehaviorCleanup,\n>(\n  behavior: {\n    stateKeys: SK;\n    contextKeys: CK;\n    setup: (deps: { state: StateMap; context: ContextMap; config: Cfg }) => R;\n  } & ExhaustiveKeys<SK, StateMap, 'state'> &\n    ExhaustiveKeys<CK, ContextMap, 'context'>\n): {\n  stateKeys: SK;\n  contextKeys: CK;\n  setup: (deps: DepsForCfg<StateMap, ContextMap, Cfg>) => R;\n} {\n  // The runtime shape is identical; the cast bridges TS's view of the\n  // parameter (config required) to the return view (config optional when\n  // Cfg has no keys).\n  return behavior as unknown as {\n    stateKeys: SK;\n    contextKeys: CK;\n    setup: (deps: DepsForCfg<StateMap, ContextMap, Cfg>) => R;\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsSA,SAAgB,eACd,MACA,SACoC;CACpC,MAAM,OAAO;CACb,MAAM,aAAa,IAAI,IAAI,IAAI;CAC/B,OAAO,OAAO,YAAY,CAAC,GAAG,UAAU,CAAC,CAAC,KAAK,QAAQ,CAAC,KAAK,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC;AAGlF;AAEA,SAAgB,kBACd,WACA,SAKiF;CAQjF,MAAM,iBAAiB;CAEvB,MAAM,QAAQ,eACZ,eAAe,SAAS,MAAM,EAAE,SAAS,GACzC,SAAS,gBAAgB,CAAC,CAC5B;CACA,MAAM,UAAU,eACd,eAAe,SAAS,MAAM,EAAE,WAAW,GAC3C,SAAS,kBAAkB,CAAC,CAC9B;CAEA,MAAM,OAA8D;EAClE;EACA;EACA,QAAS,SAAS,UAAU,CAAC;CAC/B;CACA,MAAM,WAAW,eAAe,KAAK,aAAa,SAAS,MAAM,IAAI,CAAC;CAEtE,OAAO;EACL;EACA;EACA,MAAM,UAAU;GACd,MAAM,UAAoC,CAAC;GAC3C,KAAK,MAAM,WAAW,UAAU;IAC9B,IAAI,WAAW,MAAM;IACrB,IAAI,OAAO,YAAY,YACrB,QAAQ,KAAK,QAAQ,CAAC;SACjB,IAAI,aAAa,SACtB,QAAQ,KAAK,QAAQ,QAAQ,CAAC;GAElC;GACA,MAAM,QAAQ,IAAI,OAAO;GAIzB,KAAK,MAAM,OAAO,OAAO,OAAO,KAAK,GAAwB,IAAI,IAAI,KAAA,CAAS;GAC9E,KAAK,MAAM,OAAO,OAAO,OAAO,OAAO,GAAwB,IAAI,IAAI,KAAA,CAAS;EAClF;CACF;AACF;AAoEA,SAAgB,eAQd,UAUA;CAIA,OAAO;AAKT"}

package/dist/default/core/composition/share-signals.js

@@ -0,0 +1,39 @@
+//#region src/core/composition/share-signals.ts
+/**
+* Behavior factory that hands the composition's signal refs to a
+* consumer-supplied callback (`config.onSignalsReady`) at setup time.
+*
+* Generic over `S` and `C` — the caller instantiates with their own
+* state/context types, and the callback's parameter shape is fully
+* type-driven from those. Suitable for both reads and writes (per-slot
+* intent can be expressed by typing captured refs as `Signal<T>` or
+* `ReadonlySignal<T>` at the call site).
+*
+* By default declares no keys; the composition's state/context maps come from
+* other behaviors. Pass `inputStateKeys` / `inputContextKeys` to *materialize*
+* consumer-input slots that no other behavior produces — a slot the consumer
+* writes (e.g. `userAudioTrackSelection`) but only a rule reads. shareSignals
+* is the consumer boundary, so it's the natural place to bring those slots into
+* existence; readers then treat them as optional.
+*
+* Uses a `Behavior<>` literal (not `defineBehavior`) so its (possibly empty,
+* possibly partial) key arrays don't trip the exhaustiveness check — the
+* setup-param state/context shapes describe what the callback receives (the
+* full `S` / `C`), not the subset this behavior materializes.
+*/
+function makeShareSignals(inputStateKeys = [], inputContextKeys = []) {
+	return {
+		stateKeys: inputStateKeys,
+		contextKeys: inputContextKeys,
+		setup: ({ state, context, config }) => {
+			config.onSignalsReady?.({
+				state,
+				context
+			});
+		}
+	};
+}
+//#endregion
+export { makeShareSignals };
+
+//# sourceMappingURL=share-signals.js.map

package/dist/default/core/composition/share-signals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"share-signals.js","names":[],"sources":["../../../../src/core/composition/share-signals.ts"],"sourcesContent":["import type { Behavior, ContextSignals, StateSignals } from './create-composition';\n\n/**\n * Config consumed by the `shareSignals` behavior.\n *\n * The callback fires once during composition setup with the composition's\n * state and context signal refs. Capture them to drive the composition\n * externally (writes) or observe its state (reads).\n *\n * The callback runs while other behaviors are still in their setup phase —\n * for the typical \"capture refs, use later\" pattern this is fine (signal\n * refs are stable identities), but reading inside the callback may yield\n * only initial-seed values rather than what later behaviors write.\n */\nexport interface ShareSignalsConfig<S extends object, C extends object> {\n  onSignalsReady?: (signals: { state: StateSignals<S>; context: ContextSignals<C> }) => void;\n}\n\n/**\n * Behavior factory that hands the composition's signal refs to a\n * consumer-supplied callback (`config.onSignalsReady`) at setup time.\n *\n * Generic over `S` and `C` — the caller instantiates with their own\n * state/context types, and the callback's parameter shape is fully\n * type-driven from those. Suitable for both reads and writes (per-slot\n * intent can be expressed by typing captured refs as `Signal<T>` or\n * `ReadonlySignal<T>` at the call site).\n *\n * By default declares no keys; the composition's state/context maps come from\n * other behaviors. Pass `inputStateKeys` / `inputContextKeys` to *materialize*\n * consumer-input slots that no other behavior produces — a slot the consumer\n * writes (e.g. `userAudioTrackSelection`) but only a rule reads. shareSignals\n * is the consumer boundary, so it's the natural place to bring those slots into\n * existence; readers then treat them as optional.\n *\n * Uses a `Behavior<>` literal (not `defineBehavior`) so its (possibly empty,\n * possibly partial) key arrays don't trip the exhaustiveness check — the\n * setup-param state/context shapes describe what the callback receives (the\n * full `S` / `C`), not the subset this behavior materializes.\n */\nexport function makeShareSignals<S extends object, C extends object>(\n  inputStateKeys: readonly (keyof S)[] = [],\n  inputContextKeys: readonly (keyof C)[] = []\n): Behavior<StateSignals<S>, ContextSignals<C>, ShareSignalsConfig<S, C>> {\n  return {\n    stateKeys: inputStateKeys,\n    contextKeys: inputContextKeys,\n    setup: ({ state, context, config }) => {\n      config.onSignalsReady?.({ state, context });\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAwCA,SAAgB,iBACd,iBAAuC,CAAC,GACxC,mBAAyC,CAAC,GAC8B;CACxE,OAAO;EACL,WAAW;EACX,aAAa;EACb,QAAQ,EAAE,OAAO,SAAS,aAAa;GACrC,OAAO,iBAAiB;IAAE;IAAO;GAAQ,CAAC;EAC5C;CACF;AACF"}

package/dist/default/core/machine.js

@@ -0,0 +1,26 @@
+import { signal, untrack, update } from "./signals/primitives.js";
+//#region src/core/machine.ts
+/**
+* Provisions the shared mechanics for all machine-like primitives: a snapshot
+* signal, an untracked state reader, and a transition function.
+*
+* Internal — consumed by `createMachineActor` and `createMachineReactor`. Not part of the
+* public API.
+*/
+function createMachineCore(initialSnapshot) {
+	const snapshotSignal = signal(initialSnapshot);
+	const getState = () => untrack(() => snapshotSignal.get().value);
+	const transition = (to) => update(snapshotSignal, (current) => ({
+		...current,
+		value: to
+	}));
+	return {
+		snapshotSignal,
+		getState,
+		transition
+	};
+}
+//#endregion
+export { createMachineCore };
+
+//# sourceMappingURL=machine.js.map

package/dist/default/core/machine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine.js","names":[],"sources":["../../../src/core/machine.ts"],"sourcesContent":["import type { ReadonlySignal } from './signals/primitives';\nimport { signal, untrack, update } from './signals/primitives';\n\n// =============================================================================\n// Shared snapshot type\n// =============================================================================\n\n/**\n * Base snapshot for all machine-like primitives (Actors and Reactors).\n * Carries only the finite state value. Actors extend this with `context`.\n */\nexport interface MachineSnapshot<State extends string> {\n  value: State;\n}\n\n// =============================================================================\n// Shared interface\n// =============================================================================\n\n/**\n * Shared interface for all machine-like primitives.\n * Both Actors (message-driven) and Reactors (signal-driven) implement this.\n */\nexport interface Machine<Snapshot extends MachineSnapshot<string>> {\n  readonly snapshot: ReadonlySignal<Snapshot>;\n  destroy(): void;\n}\n\n// =============================================================================\n// Shared core factory\n// =============================================================================\n\n/**\n * Provisions the shared mechanics for all machine-like primitives: a snapshot\n * signal, an untracked state reader, and a transition function.\n *\n * Internal — consumed by `createMachineActor` and `createMachineReactor`. Not part of the\n * public API.\n */\nexport function createMachineCore<FullState extends string, Snapshot extends MachineSnapshot<FullState>>(\n  initialSnapshot: Snapshot\n) {\n  const snapshotSignal = signal(initialSnapshot);\n  const getState = (): FullState => untrack(() => snapshotSignal.get().value);\n  const transition = (to: FullState): void => update(snapshotSignal, (current) => ({ ...current, value: to }));\n  return { snapshotSignal, getState, transition };\n}\n"],"mappings":";;;;;;;;;AAuCA,SAAgB,kBACd,iBACA;CACA,MAAM,iBAAiB,OAAO,eAAe;CAC7C,MAAM,iBAA4B,cAAc,eAAe,IAAI,CAAC,CAAC,KAAK;CAC1E,MAAM,cAAc,OAAwB,OAAO,iBAAiB,aAAa;EAAE,GAAG;EAAS,OAAO;CAAG,EAAE;CAC3G,OAAO;EAAE;EAAgB;EAAU;CAAW;AAChD"}

package/dist/default/core/reactors/create-machine-reactor.js

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

package/dist/default/core/reactors/create-machine-reactor.js.map

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

package/dist/default/core/signals/effect.js

@@ -0,0 +1,41 @@
+import { Signal } from "signal-polyfill";
+//#region src/core/signals/effect.ts
+const pending = /* @__PURE__ */ new Set();
+const watcher = new Signal.subtle.Watcher(() => {
+	queueMicrotask(runPending);
+});
+function runPending() {
+	for (const c of watcher.getPending()) pending.add(c);
+	watcher.watch();
+	for (const c of pending) {
+		pending.delete(c);
+		c.get();
+	}
+}
+/**
+* Run a side effect whenever its signal dependencies change.
+*
+* Executes immediately (synchronous initial run), then re-runs on the next
+* microtask after any dependency changes. If the callback returns a function,
+* it is called before each re-run and when the effect is stopped — the same
+* cleanup contract as Preact Signals, Maverick Signals, and Svelte 5 $effect.
+*
+* Returns a cleanup function that stops the effect.
+*/
+function effect(fn) {
+	let cleanup;
+	const c = new Signal.Computed(() => {
+		if (typeof cleanup === "function") cleanup();
+		cleanup = fn();
+	});
+	watcher.watch(c);
+	c.get();
+	return () => {
+		watcher.unwatch(c);
+		if (typeof cleanup === "function") cleanup();
+	};
+}
+//#endregion
+export { effect };
+
+//# sourceMappingURL=effect.js.map

package/dist/default/core/signals/effect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect.js","names":[],"sources":["../../../../src/core/signals/effect.ts"],"sourcesContent":["import { Signal } from 'signal-polyfill';\n\n// Computeds waiting to re-run after their dependencies changed.\nconst pending = new Set<Signal.Computed<void>>();\n\nconst watcher = new Signal.subtle.Watcher(() => {\n  queueMicrotask(runPending);\n});\n\nfunction runPending() {\n  for (const c of watcher.getPending()) {\n    pending.add(c as Signal.Computed<void>);\n  }\n  watcher.watch(); // re-arm before running effects, in case they write signals\n  for (const c of pending) {\n    pending.delete(c);\n    c.get(); // re-run the effect body\n  }\n}\n\n/**\n * Run a side effect whenever its signal dependencies change.\n *\n * Executes immediately (synchronous initial run), then re-runs on the next\n * microtask after any dependency changes. If the callback returns a function,\n * it is called before each re-run and when the effect is stopped — the same\n * cleanup contract as Preact Signals, Maverick Signals, and Svelte 5 $effect.\n *\n * Returns a cleanup function that stops the effect.\n */\nexport function effect(fn: () => (() => void) | void): () => void {\n  let cleanup: (() => void) | void;\n  const c = new Signal.Computed(() => {\n    if (typeof cleanup === 'function') cleanup();\n    cleanup = fn();\n  });\n  watcher.watch(c);\n  c.get(); // initial run\n  return () => {\n    watcher.unwatch(c);\n    if (typeof cleanup === 'function') cleanup();\n  };\n}\n"],"mappings":";;AAGA,MAAM,0BAAU,IAAI,IAA2B;AAE/C,MAAM,UAAU,IAAI,OAAO,OAAO,cAAc;CAC9C,eAAe,UAAU;AAC3B,CAAC;AAED,SAAS,aAAa;CACpB,KAAK,MAAM,KAAK,QAAQ,WAAW,GACjC,QAAQ,IAAI,CAA0B;CAExC,QAAQ,MAAM;CACd,KAAK,MAAM,KAAK,SAAS;EACvB,QAAQ,OAAO,CAAC;EAChB,EAAE,IAAI;CACR;AACF;;;;;;;;;;;AAYA,SAAgB,OAAO,IAA2C;CAChE,IAAI;CACJ,MAAM,IAAI,IAAI,OAAO,eAAe;EAClC,IAAI,OAAO,YAAY,YAAY,QAAQ;EAC3C,UAAU,GAAG;CACf,CAAC;CACD,QAAQ,MAAM,CAAC;CACf,EAAE,IAAI;CACN,aAAa;EACX,QAAQ,QAAQ,CAAC;EACjB,IAAI,OAAO,YAAY,YAAY,QAAQ;CAC7C;AACF"}