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

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

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

package/dist/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,UAAU;CAC7B,MAAM,EAAE,gBAAgB,UAAU,eAAe,kBAAgE;EAC/G,OAAO,IAAI;EACX,SAAS,IAAI;EACd,CAAC;CAEF,MAAM,mBAA4B,cAAc,eAAe,KAAK,CAAC,QAAQ;CAE7E,MAAM,cAAc,YAA2B;AAC7C,SAAO,gBAAgB,EAAE,SAAS,CAAC;;AAGrC,QAAO;EACL,IAAI,WAAW;AACb,UAAO;;EAGT,KAAK,SAAwB;GAC3B,MAAM,QAAQ,UAAU;AACxB,OAAI,UAAU,YAAa;GAE3B,MAAM,UADW,IAAI,OAAO,QACF,KAAK,QAAQ;AAGvC,OAAI,CAAC,QAAS;AACd,WAAQ,SAAS;IACf,SAAS,YAAY;IACrB;IACA,aAAa,OAAkB,WAAW,GAAgB;IAC1D;IACA,GAAI,SAAS,EAAE,QAAQ,GAAG,EAAE;IAC7B,CAAsD;GAEvD,MAAM,WAAW,UAAU;AAC3B,OAAI,aAAa,aAAa;IAC5B,MAAM,cAAc,IAAI,OAAO;AAC/B,QAAI,aAAa,aAAa,QAAQ;KACpC,MAAM,cAAc,YAAY;AAChC,YAAO,kBAAkB;AACvB,UAAI,UAAU,KAAK,SAAU;AAC7B,iBAAW,YAAY;OACvB;;;;EAKR,UAAgB;AACd,OAAI,UAAU,KAAK,YAAa;AAChC,WAAQ,SAAS;AACjB,cAAW,YAAY;;EAE1B"}

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

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

package/dist/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;EAAgB,CAAC;CAE/C,MAAM,mBAA4B,cAAc,eAAe,KAAK,CAAC,QAAQ;CAC7E,MAAM,cAAc,YAA2B,OAAO,gBAAgB,EAAE,SAAS,CAAC;AAElF,QAAO;EACL,IAAI,WAAW;AACb,UAAO;;EAGT,KAAK,SAAwB;AAC3B,OAAI,UAAU,KAAK,YAAa;GAChC,MAAM,UAAU,YAAY;GAC5B,MAAM,aAAa,QAAQ,SAAS,QAAQ;AAC5C,OAAI,eAAe,QAAS,YAAW,WAAW;;EAGpD,UAAgB;AACd,OAAI,UAAU,KAAK,YAAa;AAChC,cAAW,YAAY;;EAE1B"}

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, switchVideoQuality], {
+*   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 { 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, switchVideoQuality], {\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,KAAK;AAChC,QAAO,OAAO,YAAY,CAAC,GAAG,WAAW,CAAC,KAAK,QAAQ,CAAC,KAAK,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC;;AAKnF,SAAgB,kBACd,WACA,SAKiF;CAQjF,MAAM,iBAAiB;CAEvB,MAAM,QAAQ,eACZ,eAAe,SAAS,MAAM,EAAE,UAAU,EAC1C,SAAS,gBAAgB,EAAE,CAC5B;CACD,MAAM,UAAU,eACd,eAAe,SAAS,MAAM,EAAE,YAAY,EAC5C,SAAS,kBAAkB,EAAE,CAC9B;CAED,MAAM,OAA8D;EAClE;EACA;EACA,QAAS,SAAS,UAAU,EAAE;EAC/B;CACD,MAAM,WAAW,eAAe,KAAK,aAAa,SAAS,MAAM,KAAK,CAAC;AAEvE,QAAO;EACL;EACA;EACA,MAAM,UAAU;GACd,MAAM,UAAoC,EAAE;AAC5C,QAAK,MAAM,WAAW,UAAU;AAC9B,QAAI,WAAW,KAAM;AACrB,QAAI,OAAO,YAAY,WACrB,SAAQ,KAAK,SAAS,CAAC;aACd,aAAa,QACtB,SAAQ,KAAK,QAAQ,SAAS,CAAC;;AAGnC,SAAM,QAAQ,IAAI,QAAQ;AAI1B,QAAK,MAAM,OAAO,OAAO,OAAO,MAAM,CAAuB,KAAI,IAAI,KAAA,EAAU;AAC/E,QAAK,MAAM,OAAO,OAAO,OAAO,QAAQ,CAAuB,KAAI,IAAI,KAAA,EAAU;;EAEpF;;AAqEH,SAAgB,eAQd,UAUA;AAIA,QAAO"}

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

@@ -0,0 +1,37 @@
+//#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).
+*
+* Declares no keys of its own (`stateKeys: []`, `contextKeys: []`); the
+* composition's state/context maps come from other behaviors' key
+* declarations. This behavior just observes/forwards whatever signals
+* the composition built.
+*
+* Uses a `Behavior<>` literal (not `defineBehavior`) so the empty key
+* arrays don't trip the exhaustiveness check — the setup-param state/
+* context shapes here describe what the consumer's callback receives,
+* not keys this behavior needs created.
+*/
+function makeShareSignals() {
+	return {
+		stateKeys: [],
+		contextKeys: [],
+		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 * Declares no keys of its own (`stateKeys: []`, `contextKeys: []`); the\n * composition's state/context maps come from other behaviors' key\n * declarations. This behavior just observes/forwards whatever signals\n * the composition built.\n *\n * Uses a `Behavior<>` literal (not `defineBehavior`) so the empty key\n * arrays don't trip the exhaustiveness check — the setup-param state/\n * context shapes here describe what the consumer's callback receives,\n * not keys this behavior needs created.\n */\nexport function makeShareSignals<S extends object, C extends object>(): Behavior<\n  StateSignals<S>,\n  ContextSignals<C>,\n  ShareSignalsConfig<S, C>\n> {\n  return {\n    stateKeys: [],\n    contextKeys: [],\n    setup: ({ state, context, config }) => {\n      config.onSignalsReady?.({ state, context });\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAsCA,SAAgB,mBAId;AACA,QAAO;EACL,WAAW,EAAE;EACb,aAAa,EAAE;EACf,QAAQ,EAAE,OAAO,SAAS,aAAa;AACrC,UAAO,iBAAiB;IAAE;IAAO;IAAS,CAAC;;EAE9C"}

package/dist/{dev/core → default/core/reactors}/create-machine-reactor.js

@@ -1,7 +1,7 @@
-import { effect } from "./signals/effect.js";
-import { untrack } from "./signals/primitives.js";
-import { createMachineCore } from "./machine.js";
-//#region src/core/create-machine-reactor.ts
+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.

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,EAAE,GAAG,MAAM,QAAQ,EAAE,GAAG,IAAI,CAAC,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCtG,SAAgB,qBACd,KAC6C;CAG7C,MAAM,EAAE,gBAAgB,UAAU,eAAe,kBAAyD,EACxG,OAAO,IAAI,SACZ,CAAC;CAEF,MAAM,kBAAqC,EAAE;CAE7C,MAAM,cAAc,WAAwC;AAC1D,MAAI,CAAC,OAAQ,QAAO,KAAA;AACpB,MAAI,OAAO,WAAW,WAAY,QAAO;AACzC,eAAa,OAAO,OAAO;;CAW7B,MAAM,aAA2C,mBAAmB,QAAQ,SAAS;CAErF,MAAM,cAAc,aAClB,SAAS,UAAU,gBAAgB,SAAS,UAAU;CAMxD,MAAM,cAAkC,CACtC,GAAG,QAAQ,IAAI,QAAQ,CAAC,KAAK,QAAQ;EACnC,UAAU;GACR,MAAM,SAAS,IAAI;AACnB,OAAI,WAAY,UAAU,CAAY,YAAW,OAAoB;;EAEvE,YAAY;EACb,EAAE,EACH,GAAI,OAAO,QAAQ,IAAI,OAAO,CAA4C,SAAS,CAAC,OAAO,cAAc;EACvG,MAAM,cAAc,aAAmC,SAAS,UAAU;AAC1E,SAAO,CACL,GAAG,QAAQ,SAAS,MAAM,CAAC,KAAK,QAAQ;GAAE;GAAI,YAAY;GAAY,UAAU;GAAW,EAAE,EAC7F,GAAG,QAAQ,SAAS,QAAQ,CAAC,KAAK,QAAQ;GAAE;GAAI,YAAY;GAAY,EAAE,CAC3E;GACD,CACH;CAED,MAAM,YAAY,EAAE,IAAI,YAAY,YAAY,aAAa,eAC3D,aAAa;AAEX,MAAI,WADa,eAAe,KAAK,CACb,CAAE;EAC1B,MAAM,iBAAiB,IAAI;AAC3B,SAAO,WAAW,SAAS,SAAS,EAAE,CAAC;GACvC;AAEJ,iBAAgB,KAAK,GAAG,YAAY,IAAI,SAAS,CAAC;AAElD,QAAO;EACL,IAAI,WAAW;AACb,UAAO;;EAGT,UAAgB;GACd,MAAM,QAAQ,UAAU;AACxB,OAAI,UAAU,gBAAgB,UAAU,YAAa;AAIrD,cAAW,aAAa;AACxB,cAAW,YAAY;AACvB,QAAK,MAAM,WAAW,gBAAiB,UAAS;;EAEnD"}

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

@@ -2,6 +2,23 @@ import { Signal } from "signal-polyfill";
 //#region src/core/signals/primitives.ts
 /** Read a signal value without tracking it as a dependency. */
 const untrack = Signal.subtle.untrack;
+/**
+* Read a signal's current value without tracking it as a dependency. Sugar
+* for `untrack(() => signal.get())` to reduce boilerplate at single-read
+* sites. Structurally typed to accept any signal-like (Signal, Computed,
+* ReadonlySignal).
+*
+* Accepts an optional `transform` to project the value in the same call;
+* the default is the identity function so the single-arg form returns `T`
+* unchanged.
+*
+* @example
+* const value = peek(someSignal);
+* const id = peek(presentationSignal, (p) => p?.id);
+*/
+function peek(source, transform = (v) => v) {
+	return untrack(() => transform(source.get()));
+}
 /** Create a writable reactive value. */
 function signal(initialValue, options) {
 	return new Signal.State(initialValue, options);
@@ -10,23 +27,28 @@ function signal(initialValue, options) {
 function computed(fn, options) {
 	return new Signal.Computed(fn, options);
 }
-/**
-* Update a writable signal. Accepts either a partial object to merge into the
-* current state, or an updater function that receives the current state and
-* returns the next state.
-*
-* @example
-* update(state, { playbackRate: 2 });
-* update(state, (s) => ({ ...s, count: s.count + 1 }));
-*/
 function update(signal, updater) {
 	const current = untrack(() => signal.get());
-	signal.set(typeof updater === "function" ? updater(current) : {
+	if (typeof updater === "function") signal.set(updater(current));
+	else signal.set({
 		...current,
 		...updater
 	});
 }
+/**
+* Read every signal in a map and return a plain object snapshot. Each read
+* tracks in the surrounding Computed/Effect — equivalent to calling `.get()`
+* on a single `Signal<S>` over the merged shape.
+*
+* Convenience for behaviors that pass whole state/context snapshots to pure
+* helpers; prefer per-field reads when only a few fields are needed.
+*/
+function snapshot(map) {
+	const out = {};
+	for (const key in map) out[key] = map[key].get();
+	return out;
+}
 //#endregion
-export { computed, signal, untrack, update };
+export { computed, peek, signal, snapshot, untrack, update };
 
 //# sourceMappingURL=primitives.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"primitives.js","names":["SignalNS"],"sources":["../../../../src/core/signals/primitives.ts"],"sourcesContent":["import { Signal as SignalNS } from 'signal-polyfill';\n\n/** Read a signal value without tracking it as a dependency. */\nexport const untrack: <T>(fn: () => T) => T = SignalNS.subtle.untrack;\n\n/** A writable reactive value (read + write). */\nexport type Signal<T> = SignalNS.State<T>;\n\n/** A derived reactive value that re-evaluates when its dependencies change (read-only). */\nexport type Computed<T> = SignalNS.Computed<T>;\n\n/** A read-only view of a reactive value. */\nexport type ReadonlySignal<T> = Omit<SignalNS.State<T>, 'set'>;\n\nexport interface SignalOptions<T> {\n  equals?: (t: T, t2: T) => boolean;\n}\n\n/** Create a writable reactive value. */\nexport function signal<T>(initialValue: T, options?: SignalOptions<T>): Signal<T> {\n  return new SignalNS.State(initialValue, options as SignalNS.Options<T>);\n}\n\n/** Create a computed reactive value. */\nexport function computed<T>(fn: () => T, options?: SignalOptions<T>): Computed<T> {\n  return new SignalNS.Computed(fn, options as SignalNS.Options<T>);\n}\n\n/**\n * Update a writable signal. Accepts either a partial object to merge into the\n * current state, or an updater function that receives the current state and\n * returns the next state.\n *\n * @example\n * update(state, { playbackRate: 2 });\n * update(state, (s) => ({ ...s, count: s.count + 1 }));\n */\nexport function update<T extends object>(signal: Signal<T>, updater: Partial<T> | ((current: T) => T)): void {\n  const current = untrack(() => signal.get());\n  signal.set(typeof updater === 'function' ? updater(current) : { ...current, ...updater });\n}\n"],"mappings":";;;AAGA,MAAa,UAAiCA,OAAS,OAAO;;AAgB9D,SAAgB,OAAU,cAAiB,SAAuC;AAChF,QAAO,IAAIA,OAAS,MAAM,cAAc,QAA+B;;;AAIzE,SAAgB,SAAY,IAAa,SAAyC;AAChF,QAAO,IAAIA,OAAS,SAAS,IAAI,QAA+B;;;;;;;;;;;AAYlE,SAAgB,OAAyB,QAAmB,SAAiD;CAC3G,MAAM,UAAU,cAAc,OAAO,KAAK,CAAC;AAC3C,QAAO,IAAI,OAAO,YAAY,aAAa,QAAQ,QAAQ,GAAG;EAAE,GAAG;EAAS,GAAG;EAAS,CAAC"}
+{"version":3,"file":"primitives.js","names":["SignalNS"],"sources":["../../../../src/core/signals/primitives.ts"],"sourcesContent":["import { Signal as SignalNS } from 'signal-polyfill';\n\n/** Read a signal value without tracking it as a dependency. */\nexport const untrack: <T>(fn: () => T) => T = SignalNS.subtle.untrack;\n\n/**\n * Read a signal's current value without tracking it as a dependency. Sugar\n * for `untrack(() => signal.get())` to reduce boilerplate at single-read\n * sites. Structurally typed to accept any signal-like (Signal, Computed,\n * ReadonlySignal).\n *\n * Accepts an optional `transform` to project the value in the same call;\n * the default is the identity function so the single-arg form returns `T`\n * unchanged.\n *\n * @example\n * const value = peek(someSignal);\n * const id = peek(presentationSignal, (p) => p?.id);\n */\nexport function peek<T, R = T>(source: { get(): T }, transform: (value: T) => R = (v: T) => v as unknown as R): R {\n  return untrack(() => transform(source.get()));\n}\n\n/** A writable reactive value (read + write). */\nexport type Signal<T> = SignalNS.State<T>;\n\n/** A derived reactive value that re-evaluates when its dependencies change (read-only). */\nexport type Computed<T> = SignalNS.Computed<T>;\n\n/** A read-only view of a reactive value. */\nexport type ReadonlySignal<T> = Omit<SignalNS.State<T>, 'set'>;\n\nexport interface SignalOptions<T> {\n  equals?: (t: T, t2: T) => boolean;\n}\n\n/** Create a writable reactive value. */\nexport function signal<T>(initialValue: T, options?: SignalOptions<T>): Signal<T> {\n  return new SignalNS.State(initialValue, options as SignalNS.Options<T>);\n}\n\n/** Create a computed reactive value. */\nexport function computed<T>(fn: () => T, options?: SignalOptions<T>): Computed<T> {\n  return new SignalNS.Computed(fn, options as SignalNS.Options<T>);\n}\n\n/**\n * Update a writable signal. Two forms:\n *\n * - **Updater function** `(current) => next`. Works for any signal type,\n *   including `Signal<T | undefined>` — handle undefined in the updater.\n * - **Partial object** to merge into the current state. Requires\n *   `T extends object`.\n *\n * @example\n * update(state, { playbackRate: 2 });\n * update(state, (s) => ({ ...s, count: s.count + 1 }));\n * update(maybeUndefinedSignal, (current) => current ?? defaultValue);\n */\nexport function update<T>(signal: Signal<T>, updater: (current: T) => T): void;\nexport function update<T extends object>(signal: Signal<T>, updater: Partial<T>): void;\nexport function update<T>(signal: Signal<T>, updater: ((current: T) => T) | object): void {\n  const current = untrack(() => signal.get());\n  if (typeof updater === 'function') {\n    signal.set((updater as (current: T) => T)(current));\n  } else {\n    // Partial<T> form — `T extends object` enforced by the public overload.\n    signal.set({ ...(current as object), ...updater } as T);\n  }\n}\n\n/**\n * Equality comparator for objects with an optional `id` field. Designed for\n * use as a `computed` `equals` option when reacting to identity changes\n * (Ham-shaped objects, JSON-API-shaped resources) while filtering internal\n * updates that preserve the id.\n *\n * Handles undefined inputs symmetrically: both undefined → equal; one\n * undefined → different.\n *\n * @example\n * const presentationById = computed(() => state.presentation.get(), {\n *   equals: equalsById,\n * });\n */\nexport function equalsById<T extends { id?: string }>(a: T | undefined, b: T | undefined): boolean {\n  return a?.id === b?.id;\n}\n\n/**\n * Read every signal in a map and return a plain object snapshot. Each read\n * tracks in the surrounding Computed/Effect — equivalent to calling `.get()`\n * on a single `Signal<S>` over the merged shape.\n *\n * Convenience for behaviors that pass whole state/context snapshots to pure\n * helpers; prefer per-field reads when only a few fields are needed.\n */\nexport function snapshot<M extends Record<string, ReadonlySignal<unknown>>>(\n  map: M\n): { [K in keyof M]: M[K] extends { get(): infer V } ? V : never } {\n  const out = {} as { [K in keyof M]: M[K] extends { get(): infer V } ? V : never };\n  for (const key in map) {\n    out[key] = map[key]!.get() as never;\n  }\n  return out;\n}\n"],"mappings":";;;AAGA,MAAa,UAAiCA,OAAS,OAAO;;;;;;;;;;;;;;;AAgB9D,SAAgB,KAAe,QAAsB,aAA8B,MAAS,GAAsB;AAChH,QAAO,cAAc,UAAU,OAAO,KAAK,CAAC,CAAC;;;AAiB/C,SAAgB,OAAU,cAAiB,SAAuC;AAChF,QAAO,IAAIA,OAAS,MAAM,cAAc,QAA+B;;;AAIzE,SAAgB,SAAY,IAAa,SAAyC;AAChF,QAAO,IAAIA,OAAS,SAAS,IAAI,QAA+B;;AAkBlE,SAAgB,OAAU,QAAmB,SAA6C;CACxF,MAAM,UAAU,cAAc,OAAO,KAAK,CAAC;AAC3C,KAAI,OAAO,YAAY,WACrB,QAAO,IAAK,QAA8B,QAAQ,CAAC;KAGnD,QAAO,IAAI;EAAE,GAAI;EAAoB,GAAG;EAAS,CAAM;;;;;;;;;;AA8B3D,SAAgB,SACd,KACiE;CACjE,MAAM,MAAM,EAAE;AACd,MAAK,MAAM,OAAO,IAChB,KAAI,OAAO,IAAI,KAAM,KAAK;AAE5B,QAAO"}

package/dist/default/core/{task.js → tasks/task.js}

@@ -1,6 +1,6 @@
-import { generateId } from "./utils/generate-id.js";
 import { anyAbortSignal } from "@videojs/utils/events";
-//#region src/core/task.ts
+import { generateId } from "@videojs/utils/string";
+//#region src/core/tasks/task.ts
 /**
 * Generic reusable task that wraps an async run function.
 *

package/dist/default/core/tasks/task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.js","names":["#runFn","#abortController","#signal","#status","#value","#error","#pending","#destroyed","#settled","#resolveSettled","#chain","#current"],"sources":["../../../../src/core/tasks/task.ts"],"sourcesContent":["import { anyAbortSignal } from '@videojs/utils/events';\nimport { generateId } from '@videojs/utils/string';\n\n// =============================================================================\n// DeepReadonly\n// =============================================================================\n\n/** Recursively marks all properties as readonly. */\nexport type DeepReadonly<T> = T extends (infer U)[]\n  ? ReadonlyArray<DeepReadonly<U>>\n  : T extends object\n    ? { readonly [K in keyof T]: DeepReadonly<T[K]> }\n    : T;\n\n// =============================================================================\n// Task\n// =============================================================================\n\nexport type TaskStatus = 'pending' | 'running' | 'done' | 'error';\n\n/**\n * Configuration for a Task.\n */\nexport interface TaskConfig {\n  /**\n   * Identifier for this task.\n   * - string: used as-is\n   * - () => string: called once at construction time\n   * - undefined: a unique ID is generated via generateId()\n   */\n  id?: string | (() => string);\n\n  /**\n   * Optional external AbortSignal to compose with the task's internal one.\n   * The task's work is aborted when either the internal controller (via abort())\n   * or this external signal fires — whichever comes first.\n   */\n  signal?: AbortSignal;\n}\n\n/**\n * Minimal contract for a schedulable unit of async work.\n */\nexport interface TaskLike<TValue = void, TError = unknown> {\n  readonly id: string;\n  readonly status: TaskStatus;\n  readonly value: DeepReadonly<TValue> | undefined;\n  readonly error: DeepReadonly<TError> | undefined;\n  run(): Promise<TValue>;\n  abort(): void;\n}\n\n/**\n * Generic reusable task that wraps an async run function.\n *\n * Owns its own AbortController so it can always be aborted independently.\n * Optionally composes an external AbortSignal so that a parent's cancellation\n * propagates into the task's work without requiring the caller to track the\n * task separately.\n *\n * Ordering guarantee: `value` is written before `status` transitions to `'done'`;\n * `error` is written before `status` transitions to `'error'`. Any reader\n * observing `status === 'done'` is guaranteed `value` is already present.\n */\nexport class Task<TValue = void, TError = unknown> implements TaskLike<TValue, TError> {\n  readonly id: string;\n  readonly #runFn: (signal: AbortSignal) => Promise<TValue>;\n  readonly #abortController = new AbortController();\n  readonly #signal: AbortSignal;\n\n  #status: TaskStatus = 'pending';\n  #value: TValue | undefined = undefined;\n  #error: TError | undefined = undefined;\n\n  constructor(runFn: (signal: AbortSignal) => Promise<TValue>, config?: TaskConfig) {\n    this.#runFn = runFn;\n    const rawId = config?.id;\n    this.id = typeof rawId === 'function' ? rawId() : (rawId ?? generateId());\n    this.#signal = config?.signal\n      ? anyAbortSignal([this.#abortController.signal, config.signal])\n      : this.#abortController.signal;\n  }\n\n  get status(): TaskStatus {\n    return this.#status;\n  }\n\n  get value(): DeepReadonly<TValue> | undefined {\n    return this.#value as DeepReadonly<TValue> | undefined;\n  }\n\n  get error(): DeepReadonly<TError> | undefined {\n    return this.#error as DeepReadonly<TError> | undefined;\n  }\n\n  async run(): Promise<TValue> {\n    this.#status = 'running';\n    try {\n      const result = await this.#runFn(this.#signal);\n      this.#value = result; // value before status — ordering guarantee\n      this.#status = 'done';\n      return result;\n    } catch (e) {\n      this.#error = e as TError; // error before status — ordering guarantee\n      this.#status = 'error';\n      throw e;\n    }\n  }\n\n  abort(): void {\n    this.#abortController.abort();\n  }\n}\n\n// =============================================================================\n// ConcurrentRunner\n// =============================================================================\n\n/**\n * Runs tasks concurrently, deduplicated by task id.\n *\n * If a task with a given id is already in flight, subsequent schedule() calls\n * for that id are silently ignored until the first completes. Tasks are stored\n * so abortAll() can cancel any in-flight work (e.g. on engine cleanup).\n */\nexport class ConcurrentRunner {\n  readonly #pending = new Map<string, { task: TaskLike<unknown, unknown>; promise: Promise<unknown> }>();\n  #settled: Promise<void> = Promise.resolve();\n  #resolveSettled: (() => void) | null = null;\n  #destroyed = false;\n\n  schedule<TValue = void, TError = unknown>(task: TaskLike<TValue, TError>): Promise<TValue> {\n    if (this.#destroyed) return Promise.resolve() as Promise<TValue>;\n    const existing = this.#pending.get(task.id);\n    if (existing) return existing.promise as Promise<TValue>;\n\n    if (this.#pending.size === 0) {\n      this.#settled = new Promise((resolve) => {\n        this.#resolveSettled = resolve;\n      });\n    }\n\n    const promise = task.run();\n    // Suppress unhandled rejection for callers that ignore the return value.\n    promise.catch(() => {});\n    // Cleanup: update pending and resolve settled regardless of outcome.\n    const cleanup = () => {\n      this.#pending.delete(task.id);\n      if (this.#pending.size === 0) {\n        this.#resolveSettled?.();\n        this.#resolveSettled = null;\n      }\n    };\n    promise.then(cleanup, cleanup);\n\n    this.#pending.set(task.id, { task: task as TaskLike<unknown, unknown>, promise: promise as Promise<unknown> });\n    return promise;\n  }\n\n  /**\n   * Registers a callback to fire when all currently in-flight tasks settle.\n   * If the runner is already idle, the callback is never called. If abortAll()\n   * is called before the batch settles, the callback is superseded and silently\n   * dropped — no stale callbacks, no generation token required by the caller.\n   */\n  whenSettled(callback: () => void): void {\n    if (this.#pending.size === 0) return;\n    const captured = this.#settled;\n    captured.then(\n      () => {\n        if (this.#settled !== captured) return;\n        callback();\n      },\n      () => {}\n    );\n  }\n\n  abortAll(): void {\n    for (const { task } of this.#pending.values()) task.abort();\n    this.#pending.clear();\n    // Resolve the current settled promise so any .then() handlers are queued,\n    // then replace the reference — whenSettled callbacks that captured the old\n    // reference will see the identity mismatch and be dropped.\n    this.#resolveSettled?.();\n    this.#resolveSettled = null;\n    this.#settled = Promise.resolve();\n  }\n\n  destroy(): void {\n    this.#destroyed = true;\n    this.abortAll();\n  }\n}\n\n// =============================================================================\n// SerialRunner\n// =============================================================================\n\n/**\n * Runs tasks one at a time in submission order.\n *\n * Each schedule() call returns a Promise that resolves or rejects with the\n * task's result when it is eventually executed. Tasks wait in queue until the\n * prior task completes.\n *\n * Serialization is achieved by chaining each task's run() onto the tail of a\n * shared promise chain — no explicit queue or drain loop needed.\n *\n * abortAll() aborts all pending (not yet started) tasks and the currently\n * in-flight task. Pending tasks still run briefly but receive an aborted\n * signal and are expected to exit early.\n */\nexport class SerialRunner {\n  #chain: Promise<unknown> = Promise.resolve();\n  readonly #pending = new Set<TaskLike<unknown, unknown>>();\n  #current: TaskLike<unknown, unknown> | null = null;\n  #destroyed = false;\n\n  schedule<TValue = void, TError = unknown>(task: TaskLike<TValue, TError>): Promise<TValue> {\n    if (this.#destroyed) return Promise.resolve() as Promise<TValue>;\n    const t = task as TaskLike<unknown, unknown>;\n    this.#pending.add(t);\n\n    const result = this.#chain\n      .then(() => {\n        this.#pending.delete(t);\n        this.#current = t;\n        return task.run();\n      })\n      .finally(() => {\n        this.#current = null;\n      });\n\n    // Advance the chain regardless of whether this task succeeds or fails.\n    this.#chain = result.then(\n      () => {},\n      () => {}\n    );\n\n    return result as Promise<TValue>;\n  }\n\n  /**\n   * A promise that resolves when all currently-scheduled tasks have settled.\n   * Use the reference as a generation token: capture it after scheduling a\n   * batch, then check identity in the resolution callback to detect whether\n   * a subsequent abortAll() + new batch has superseded this one.\n   */\n  get settled(): Promise<void> {\n    return this.#chain as Promise<void>;\n  }\n\n  /**\n   * Registers a callback to fire when all currently-pending tasks settle.\n   * If the runner is already idle (no pending or running tasks), the callback\n   * is never called. If new tasks are scheduled before the current batch\n   * settles, the callback is superseded and silently dropped — no stale\n   * callbacks, no generation token required by the caller.\n   */\n  whenSettled(callback: () => void): void {\n    if (this.#pending.size === 0 && this.#current === null) return;\n    const currentChain = this.#chain;\n    currentChain.then(\n      () => {\n        if (this.#chain !== currentChain) return;\n        callback();\n      },\n      () => {}\n    );\n  }\n\n  /** Aborts and clears queued tasks without touching the in-flight task. */\n  abortPending(): void {\n    for (const task of this.#pending) task.abort();\n    this.#pending.clear();\n  }\n\n  abortAll(): void {\n    this.abortPending();\n    this.#current?.abort();\n  }\n\n  destroy(): void {\n    this.#destroyed = true;\n    this.abortAll();\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AAgEA,IAAa,OAAb,MAAuF;CACrF;CACA;CACA,mBAA4B,IAAI,iBAAiB;CACjD;CAEA,UAAsB;CACtB,SAA6B,KAAA;CAC7B,SAA6B,KAAA;CAE7B,YAAY,OAAiD,QAAqB;AAChF,QAAA,QAAc;EACd,MAAM,QAAQ,QAAQ;AACtB,OAAK,KAAK,OAAO,UAAU,aAAa,OAAO,GAAI,SAAS,YAAY;AACxE,QAAA,SAAe,QAAQ,SACnB,eAAe,CAAC,MAAA,gBAAsB,QAAQ,OAAO,OAAO,CAAC,GAC7D,MAAA,gBAAsB;;CAG5B,IAAI,SAAqB;AACvB,SAAO,MAAA;;CAGT,IAAI,QAA0C;AAC5C,SAAO,MAAA;;CAGT,IAAI,QAA0C;AAC5C,SAAO,MAAA;;CAGT,MAAM,MAAuB;AAC3B,QAAA,SAAe;AACf,MAAI;GACF,MAAM,SAAS,MAAM,MAAA,MAAY,MAAA,OAAa;AAC9C,SAAA,QAAc;AACd,SAAA,SAAe;AACf,UAAO;WACA,GAAG;AACV,SAAA,QAAc;AACd,SAAA,SAAe;AACf,SAAM;;;CAIV,QAAc;AACZ,QAAA,gBAAsB,OAAO;;;;;;;;;;AAejC,IAAa,mBAAb,MAA8B;CAC5B,2BAAoB,IAAI,KAA8E;CACtG,WAA0B,QAAQ,SAAS;CAC3C,kBAAuC;CACvC,aAAa;CAEb,SAA0C,MAAiD;AACzF,MAAI,MAAA,UAAiB,QAAO,QAAQ,SAAS;EAC7C,MAAM,WAAW,MAAA,QAAc,IAAI,KAAK,GAAG;AAC3C,MAAI,SAAU,QAAO,SAAS;AAE9B,MAAI,MAAA,QAAc,SAAS,EACzB,OAAA,UAAgB,IAAI,SAAS,YAAY;AACvC,SAAA,iBAAuB;IACvB;EAGJ,MAAM,UAAU,KAAK,KAAK;AAE1B,UAAQ,YAAY,GAAG;EAEvB,MAAM,gBAAgB;AACpB,SAAA,QAAc,OAAO,KAAK,GAAG;AAC7B,OAAI,MAAA,QAAc,SAAS,GAAG;AAC5B,UAAA,kBAAwB;AACxB,UAAA,iBAAuB;;;AAG3B,UAAQ,KAAK,SAAS,QAAQ;AAE9B,QAAA,QAAc,IAAI,KAAK,IAAI;GAAQ;GAA6C;GAA6B,CAAC;AAC9G,SAAO;;;;;;;;CAST,YAAY,UAA4B;AACtC,MAAI,MAAA,QAAc,SAAS,EAAG;EAC9B,MAAM,WAAW,MAAA;AACjB,WAAS,WACD;AACJ,OAAI,MAAA,YAAkB,SAAU;AAChC,aAAU;WAEN,GACP;;CAGH,WAAiB;AACf,OAAK,MAAM,EAAE,UAAU,MAAA,QAAc,QAAQ,CAAE,MAAK,OAAO;AAC3D,QAAA,QAAc,OAAO;AAIrB,QAAA,kBAAwB;AACxB,QAAA,iBAAuB;AACvB,QAAA,UAAgB,QAAQ,SAAS;;CAGnC,UAAgB;AACd,QAAA,YAAkB;AAClB,OAAK,UAAU;;;;;;;;;;;;;;;;;AAsBnB,IAAa,eAAb,MAA0B;CACxB,SAA2B,QAAQ,SAAS;CAC5C,2BAAoB,IAAI,KAAiC;CACzD,WAA8C;CAC9C,aAAa;CAEb,SAA0C,MAAiD;AACzF,MAAI,MAAA,UAAiB,QAAO,QAAQ,SAAS;EAC7C,MAAM,IAAI;AACV,QAAA,QAAc,IAAI,EAAE;EAEpB,MAAM,SAAS,MAAA,MACZ,WAAW;AACV,SAAA,QAAc,OAAO,EAAE;AACvB,SAAA,UAAgB;AAChB,UAAO,KAAK,KAAK;IACjB,CACD,cAAc;AACb,SAAA,UAAgB;IAChB;AAGJ,QAAA,QAAc,OAAO,WACb,UACA,GACP;AAED,SAAO;;;;;;;;CAST,IAAI,UAAyB;AAC3B,SAAO,MAAA;;;;;;;;;CAUT,YAAY,UAA4B;AACtC,MAAI,MAAA,QAAc,SAAS,KAAK,MAAA,YAAkB,KAAM;EACxD,MAAM,eAAe,MAAA;AACrB,eAAa,WACL;AACJ,OAAI,MAAA,UAAgB,aAAc;AAClC,aAAU;WAEN,GACP;;;CAIH,eAAqB;AACnB,OAAK,MAAM,QAAQ,MAAA,QAAe,MAAK,OAAO;AAC9C,QAAA,QAAc,OAAO;;CAGvB,WAAiB;AACf,OAAK,cAAc;AACnB,QAAA,SAAe,OAAO;;CAGxB,UAAgB;AACd,QAAA,YAAkB;AAClB,OAAK,UAAU"}

package/dist/default/dom.js

@@ -1,10 +1,9 @@
-import { loadSegments } from "./dom/features/load-segments.js";
-import { destroyVttParser, parseVttSegment } from "./dom/text/parse-vtt-segment.js";
-import { loadTextTrackCues } from "./dom/features/load-text-track-cues.js";
-import { trackCurrentTime } from "./dom/features/track-current-time.js";
-import { trackPlaybackInitiated } from "./dom/features/track-playback-initiated.js";
-import { trackPlaybackRate } from "./dom/features/track-playback-rate.js";
-import { appendSegment } from "./dom/media/append-segment.js";
-import { flushBuffer } from "./dom/media/buffer-flusher.js";
-import { SpfMedia, SpfMediaMixin, spfMediaDefaultProps } from "./dom/playback-engine/adapter.js";
-export { SpfMedia, SpfMediaMixin, appendSegment, destroyVttParser, flushBuffer, loadSegments, loadTextTrackCues, parseVttSegment, spfMediaDefaultProps, trackCurrentTime, trackPlaybackInitiated, trackPlaybackRate };
+import { appendSegment } from "./media/dom/mse/append-segment.js";
+import { flushBuffer } from "./media/dom/mse/buffer-flusher.js";
+import { destroyVttResolver, resolveVttSegment } from "./media/dom/text/resolve-vtt-segment.js";
+import { loadAudioSegments, loadVideoSegments } from "./playback/behaviors/dom/load-segments.js";
+import { setupTextTrackActors } from "./playback/behaviors/dom/setup-text-track-actors.js";
+import { trackCurrentTime } from "./playback/behaviors/dom/track-current-time.js";
+import { trackLoadTriggers } from "./playback/behaviors/dom/track-load-triggers.js";
+import { trackPlaybackRate } from "./playback/behaviors/dom/track-playback-rate.js";
+export { appendSegment, destroyVttResolver, flushBuffer, loadAudioSegments, loadVideoSegments, resolveVttSegment, setupTextTrackActors, trackCurrentTime, trackLoadTriggers, trackPlaybackRate };

package/dist/default/hls.js

@@ -0,0 +1,3 @@
+import { createSimpleHlsEngine } from "./playback/engines/hls/engine.js";
+import { SimpleHlsMediaElement, SimpleHlsMediaMixin, simpleHlsMediaDefaultProps } from "./playback/engines/hls/adapter.js";
+export { SimpleHlsMediaElement, SimpleHlsMediaMixin, createSimpleHlsEngine, simpleHlsMediaDefaultProps };

package/dist/default/index.js

@@ -1,14 +1,23 @@
+import { computed, signal, snapshot, untrack, update } from "./core/signals/primitives.js";
+import { createComposition, defineBehavior } from "./core/composition/create-composition.js";
+import { makeShareSignals } from "./core/composition/share-signals.js";
+import { effect } from "./core/signals/effect.js";
+import { ConcurrentRunner, SerialRunner, Task } from "./core/tasks/task.js";
+import { createMachineActor } from "./core/actors/create-machine-actor.js";
+import { createTransitionActor } from "./core/actors/create-transition-actor.js";
+import { createMachineReactor } from "./core/reactors/create-machine-reactor.js";
 //#region src/index.ts
 /**
 * Stream Processing Framework (SPF) for Video.js 10
 *
-* Bundle size target: < 20KB (minified + gzipped)
-* Primary use case: CMAF HLS playback with Video.js v10
+* The compositional primitives: createComposition, signals, tasks, actors,
+* reactors. Media-domain helpers and the HLS playback engine live behind
+* the `./dom` and `./hls` subpaths.
 *
 * @packageDocumentation
 */
 const VERSION = "0.1.0";
 //#endregion
-export { VERSION };
+export { ConcurrentRunner, SerialRunner, Task, VERSION, computed, createComposition, createMachineActor, createMachineReactor, createTransitionActor, defineBehavior, effect, makeShareSignals, signal, snapshot, untrack, update };
 
 //# sourceMappingURL=index.js.map

package/dist/default/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/index.ts"],"sourcesContent":["/**\n * Stream Processing Framework (SPF) for Video.js 10\n *\n * Bundle size target: < 20KB (minified + gzipped)\n * Primary use case: CMAF HLS playback with Video.js v10\n *\n * @packageDocumentation\n */\n\n// Public API exports will be added here as features are implemented\n\nexport const VERSION = '0.1.0';\n"],"mappings":";;;;;;;;;AAWA,MAAa,UAAU"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/index.ts"],"sourcesContent":["/**\n * Stream Processing Framework (SPF) for Video.js 10\n *\n * The compositional primitives: createComposition, signals, tasks, actors,\n * reactors. Media-domain helpers and the HLS playback engine live behind\n * the `./dom` and `./hls` subpaths.\n *\n * @packageDocumentation\n */\n\nexport const VERSION = '0.1.0';\n\n// =============================================================================\n// Composition\n// =============================================================================\n\nexport type {\n  Behavior,\n  BehaviorCleanup,\n  BehaviorDeps,\n  Composition,\n  CompositionOptions,\n  ContextSignals,\n  InferBehaviorConfig,\n  InferBehaviorContext,\n  InferBehaviorState,\n  ResolveBehaviorConfig,\n  ResolveBehaviorContext,\n  ResolveBehaviorState,\n  StateSignals,\n} from './core/composition/create-composition';\nexport { createComposition, defineBehavior } from './core/composition/create-composition';\nexport type { ShareSignalsConfig } from './core/composition/share-signals';\nexport { makeShareSignals } from './core/composition/share-signals';\n\n// =============================================================================\n// Signals\n// =============================================================================\n\nexport { effect } from './core/signals/effect';\nexport type { Computed, ReadonlySignal, Signal, SignalOptions } from './core/signals/primitives';\nexport { computed, signal, snapshot, untrack, update } from './core/signals/primitives';\n\n// =============================================================================\n// Tasks\n// =============================================================================\n\nexport type { TaskConfig, TaskLike, TaskStatus } from './core/tasks/task';\nexport { ConcurrentRunner, SerialRunner, Task } from './core/tasks/task';\n\n// =============================================================================\n// Machine (shared by actors and reactors)\n// =============================================================================\n\nexport type { Machine, MachineSnapshot } from './core/machine';\n\n// =============================================================================\n// Actors\n// =============================================================================\n\nexport type { ActorSnapshot, CallbackActor, SignalActor } from './core/actors/actor';\nexport type {\n  ActorDefinition,\n  ActorStateDefinition,\n  HandlerContext,\n  MessageActor,\n  RunnerLike,\n} from './core/actors/create-machine-actor';\nexport { createMachineActor } from './core/actors/create-machine-actor';\nexport type { TransitionActor } from './core/actors/create-transition-actor';\nexport { createTransitionActor } from './core/actors/create-transition-actor';\n\n// =============================================================================\n// Reactors\n// =============================================================================\n\nexport type {\n  Reactor,\n  ReactorDefinition,\n  ReactorDeriveFn,\n  ReactorEffectFn,\n  ReactorStateDefinition,\n} from './core/reactors/create-machine-reactor';\nexport { createMachineReactor } from './core/reactors/create-machine-reactor';\n"],"mappings":";;;;;;;;;;;;;;;;;;AAUA,MAAa,UAAU"}

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

@@ -0,0 +1,83 @@
+//#region src/media/abr/quality-selection.ts
+/**
+* Default quality selection configuration.
+* Values match Shaka Player upgrade threshold (0.85 = 15% headroom).
+*/
+const DEFAULT_QUALITY_CONFIG = {
+	safetyMargin: .85,
+	upgradeMargin: 1.15
+};
+/**
+* Select the track to apply now, given current bandwidth, a current
+* selection (optional), and tuning. Returns:
+*
+* - The bandwidth-fitting optimal when no `currentTrack` is supplied.
+* - The optimal when it's a downgrade vs. `currentTrack` (downgrades
+*   apply immediately — no hysteresis).
+* - The optimal when it clears `currentTrack.bandwidth * upgradeMargin`
+*   (upgrade clears hysteresis).
+* - `currentTrack` itself when an upgrade doesn't clear the margin
+*   (stay put — caller checks identity to no-op).
+*
+* "Optimal" is the highest-bandwidth track where the available bandwidth
+* meets the safety requirement (`currentBandwidth >= track.bandwidth / safetyMargin`).
+* Falls back to the lowest-bandwidth track when nothing fits the safety
+* margin (preserves a definitive pick under under-bandwidth conditions).
+*
+* @example
+* const tracks = [low, mid, high];
+* selectQuality(tracks, 5_000_000, { currentTrack: low });
+* // Returns `high` if 5 Mbps clears safety AND high.bandwidth >= low.bandwidth * upgradeMargin.
+* // Returns `low` (no-op signal) otherwise.
+*/
+function selectQuality(tracks, currentBandwidth, opts = {}) {
+	if (tracks.length === 0) return;
+	const safetyMargin = opts.safetyMargin ?? DEFAULT_QUALITY_CONFIG.safetyMargin;
+	const upgradeMargin = opts.upgradeMargin ?? DEFAULT_QUALITY_CONFIG.upgradeMargin;
+	const { currentTrack } = opts;
+	const sortedTracks = tracks.slice().sort((a, b) => a.bandwidth - b.bandwidth);
+	let chosen;
+	for (const track of sortedTracks) if (currentBandwidth >= track.bandwidth / safetyMargin) {
+		if (!chosen || track.bandwidth > chosen.bandwidth || track.bandwidth === chosen.bandwidth && hasHigherResolution(track, chosen)) chosen = track;
+	}
+	const optimal = chosen ?? sortedTracks[0];
+	if (!optimal) return void 0;
+	if (!currentTrack) return optimal;
+	if (optimal.bandwidth < currentTrack.bandwidth) return optimal;
+	if (optimal.bandwidth >= currentTrack.bandwidth * upgradeMargin) return optimal;
+	return currentTrack;
+}
+/**
+* Select the lowest-bandwidth track from the candidate set.
+*
+* Used as a safety-net fallback by callers that need a definitive pick when
+* a primary selection algorithm declines to choose. Pairs naturally with
+* `selectQuality` — when ABR has no good answer (e.g., all candidates
+* exceed available bandwidth and the algorithm doesn't fall back
+* internally), the lowest bitrate is the safest default.
+*
+* @param tracks - Candidate tracks (can be unsorted)
+* @returns The lowest-bandwidth track, or `undefined` if `tracks` is empty
+*
+* @example
+* const fallback = selectLowestQuality(tracks);
+*/
+function selectLowestQuality(tracks) {
+	if (tracks.length === 0) return void 0;
+	return tracks.reduce((min, t) => t.bandwidth < min.bandwidth ? t : min);
+}
+/**
+* Check if track A has higher resolution than track B.
+* Compares by total pixel count (width × height).
+*
+* @param trackA - First track to compare
+* @param trackB - Second track to compare
+* @returns True if trackA has more pixels than trackB
+*/
+function hasHigherResolution(trackA, trackB) {
+	return (trackA.width ?? 0) * (trackA.height ?? 0) > (trackB.width ?? 0) * (trackB.height ?? 0);
+}
+//#endregion
+export { DEFAULT_QUALITY_CONFIG, selectLowestQuality, selectQuality };
+
+//# sourceMappingURL=quality-selection.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"quality-selection.js","names":[],"sources":["../../../../src/media/abr/quality-selection.ts"],"sourcesContent":["/**\n * Quality Selection Algorithm\n *\n * Selects optimal video track based on bandwidth estimate with safety margin.\n * Stateless selection - picks highest quality that fits bandwidth.\n *\n * Key concepts:\n * - **Safety margin** (0.85): Pick track where bandwidth >= track.bandwidth / 0.85\n * - This ensures 15% headroom to avoid buffering\n * - At same bandwidth, prefer higher resolution\n */\n\nimport type { PartiallyResolvedVideoTrack, VideoTrack } from '../types';\n\n/**\n * Quality selection configuration.\n */\nexport interface QualityConfig {\n  /**\n   * Safety margin (0-1).\n   * To select a track, need: currentBandwidth >= track.bandwidth / safetyMargin.\n   * Default 0.85 means track must use ≤85% of available bandwidth (15% headroom).\n   */\n  safetyMargin: number;\n  /**\n   * Upgrade hysteresis ratio (>= 1). When `currentTrack` is supplied, an\n   * upgrade is applied only if `optimal.bandwidth >= currentTrack.bandwidth * upgradeMargin`.\n   * Downgrades are always applied. Default 1.15 means optimal must clear\n   * the current bandwidth by at least 15% to trigger an upgrade.\n   */\n  upgradeMargin: number;\n}\n\n/**\n * Default quality selection configuration.\n * Values match Shaka Player upgrade threshold (0.85 = 15% headroom).\n */\nexport const DEFAULT_QUALITY_CONFIG: QualityConfig = {\n  safetyMargin: 0.85,\n  upgradeMargin: 1.15,\n};\n\n/**\n * Options for `selectQuality`. Spread of `Partial<QualityConfig>` plus a\n * runtime-supplied `currentTrack` for upgrade-vs-downgrade decisions.\n */\nexport interface SelectQualityOpts extends Partial<QualityConfig> {\n  /**\n   * Track currently selected. When supplied, `selectQuality` returns\n   * `currentTrack` (no change) for upgrades that don't clear the\n   * `upgradeMargin`. When omitted, no hysteresis is applied — the\n   * computed optimal is returned regardless.\n   */\n  currentTrack?: PartiallyResolvedVideoTrack | VideoTrack;\n}\n\n/**\n * Select the track to apply now, given current bandwidth, a current\n * selection (optional), and tuning. Returns:\n *\n * - The bandwidth-fitting optimal when no `currentTrack` is supplied.\n * - The optimal when it's a downgrade vs. `currentTrack` (downgrades\n *   apply immediately — no hysteresis).\n * - The optimal when it clears `currentTrack.bandwidth * upgradeMargin`\n *   (upgrade clears hysteresis).\n * - `currentTrack` itself when an upgrade doesn't clear the margin\n *   (stay put — caller checks identity to no-op).\n *\n * \"Optimal\" is the highest-bandwidth track where the available bandwidth\n * meets the safety requirement (`currentBandwidth >= track.bandwidth / safetyMargin`).\n * Falls back to the lowest-bandwidth track when nothing fits the safety\n * margin (preserves a definitive pick under under-bandwidth conditions).\n *\n * @example\n * const tracks = [low, mid, high];\n * selectQuality(tracks, 5_000_000, { currentTrack: low });\n * // Returns `high` if 5 Mbps clears safety AND high.bandwidth >= low.bandwidth * upgradeMargin.\n * // Returns `low` (no-op signal) otherwise.\n */\nexport function selectQuality(\n  tracks: readonly (PartiallyResolvedVideoTrack | VideoTrack)[],\n  currentBandwidth: number,\n  opts: SelectQualityOpts = {}\n): PartiallyResolvedVideoTrack | VideoTrack | undefined {\n  if (tracks.length === 0) {\n    return undefined;\n  }\n\n  const safetyMargin = opts.safetyMargin ?? DEFAULT_QUALITY_CONFIG.safetyMargin;\n  const upgradeMargin = opts.upgradeMargin ?? DEFAULT_QUALITY_CONFIG.upgradeMargin;\n  const { currentTrack } = opts;\n\n  // Sort tracks by bandwidth (lowest first)\n  const sortedTracks = tracks.slice().sort((a, b) => a.bandwidth - b.bandwidth);\n\n  // Start with no selection\n  let chosen: PartiallyResolvedVideoTrack | VideoTrack | undefined;\n\n  for (const track of sortedTracks) {\n    // Check if we have enough bandwidth for this track with safety margin\n    // Required bandwidth = track.bandwidth / safetyMargin\n    const requiredBandwidth = track.bandwidth / safetyMargin;\n\n    if (currentBandwidth >= requiredBandwidth) {\n      // We can support this track - prefer it if better than current choice\n      if (\n        !chosen ||\n        track.bandwidth > chosen.bandwidth ||\n        (track.bandwidth === chosen.bandwidth && hasHigherResolution(track, chosen))\n      ) {\n        chosen = track;\n      }\n    }\n  }\n\n  // If no track fits with safety margin, fall back to lowest quality\n  const optimal = chosen ?? sortedTracks[0];\n  if (!optimal) return undefined;\n\n  // Apply upgrade hysteresis. No currentTrack → no hysteresis, return\n  // optimal. Downgrade (optimal.bandwidth < current) → always apply.\n  // Upgrade → only when `optimal.bandwidth >= current * upgradeMargin`,\n  // else stay put (return currentTrack so caller's id-compare no-ops).\n  if (!currentTrack) return optimal;\n  if (optimal.bandwidth < currentTrack.bandwidth) return optimal;\n  if (optimal.bandwidth >= currentTrack.bandwidth * upgradeMargin) return optimal;\n  return currentTrack;\n}\n\n/**\n * Select the lowest-bandwidth track from the candidate set.\n *\n * Used as a safety-net fallback by callers that need a definitive pick when\n * a primary selection algorithm declines to choose. Pairs naturally with\n * `selectQuality` — when ABR has no good answer (e.g., all candidates\n * exceed available bandwidth and the algorithm doesn't fall back\n * internally), the lowest bitrate is the safest default.\n *\n * @param tracks - Candidate tracks (can be unsorted)\n * @returns The lowest-bandwidth track, or `undefined` if `tracks` is empty\n *\n * @example\n * const fallback = selectLowestQuality(tracks);\n */\nexport function selectLowestQuality<T extends { bandwidth: number }>(tracks: readonly T[]): T | undefined {\n  if (tracks.length === 0) return undefined;\n  return tracks.reduce((min, t) => (t.bandwidth < min.bandwidth ? t : min));\n}\n\n/**\n * Check if track A has higher resolution than track B.\n * Compares by total pixel count (width × height).\n *\n * @param trackA - First track to compare\n * @param trackB - Second track to compare\n * @returns True if trackA has more pixels than trackB\n */\nfunction hasHigherResolution(\n  trackA: PartiallyResolvedVideoTrack | VideoTrack,\n  trackB: PartiallyResolvedVideoTrack | VideoTrack\n): boolean {\n  const pixelsA = (trackA.width ?? 0) * (trackA.height ?? 0);\n  const pixelsB = (trackB.width ?? 0) * (trackB.height ?? 0);\n  return pixelsA > pixelsB;\n}\n"],"mappings":";;;;;AAqCA,MAAa,yBAAwC;CACnD,cAAc;CACd,eAAe;CAChB;;;;;;;;;;;;;;;;;;;;;;;;AAuCD,SAAgB,cACd,QACA,kBACA,OAA0B,EAAE,EAC0B;AACtD,KAAI,OAAO,WAAW,EACpB;CAGF,MAAM,eAAe,KAAK,gBAAgB,uBAAuB;CACjE,MAAM,gBAAgB,KAAK,iBAAiB,uBAAuB;CACnE,MAAM,EAAE,iBAAiB;CAGzB,MAAM,eAAe,OAAO,OAAO,CAAC,MAAM,GAAG,MAAM,EAAE,YAAY,EAAE,UAAU;CAG7E,IAAI;AAEJ,MAAK,MAAM,SAAS,aAKlB,KAAI,oBAFsB,MAAM,YAAY;MAKxC,CAAC,UACD,MAAM,YAAY,OAAO,aACxB,MAAM,cAAc,OAAO,aAAa,oBAAoB,OAAO,OAAO,CAE3E,UAAS;;CAMf,MAAM,UAAU,UAAU,aAAa;AACvC,KAAI,CAAC,QAAS,QAAO,KAAA;AAMrB,KAAI,CAAC,aAAc,QAAO;AAC1B,KAAI,QAAQ,YAAY,aAAa,UAAW,QAAO;AACvD,KAAI,QAAQ,aAAa,aAAa,YAAY,cAAe,QAAO;AACxE,QAAO;;;;;;;;;;;;;;;;;AAkBT,SAAgB,oBAAqD,QAAqC;AACxG,KAAI,OAAO,WAAW,EAAG,QAAO,KAAA;AAChC,QAAO,OAAO,QAAQ,KAAK,MAAO,EAAE,YAAY,IAAI,YAAY,IAAI,IAAK;;;;;;;;;;AAW3E,SAAS,oBACP,QACA,QACS;AAGT,SAFiB,OAAO,SAAS,MAAM,OAAO,UAAU,MACvC,OAAO,SAAS,MAAM,OAAO,UAAU"}

package/dist/default/{core → media}/buffer/back-buffer.js

@@ -1,4 +1,4 @@
-//#region src/core/buffer/back-buffer.ts
+//#region src/media/buffer/back-buffer.ts
 /**
 * Default back buffer configuration.
 */
@@ -41,6 +41,6 @@ function calculateBackBufferFlushPoint(segments, currentTime, config = DEFAULT_B
 	return segmentsBefore[segmentsToFlush].startTime;
 }
 //#endregion
-export { calculateBackBufferFlushPoint };
+export { DEFAULT_BACK_BUFFER_CONFIG, calculateBackBufferFlushPoint };
 
 //# sourceMappingURL=back-buffer.js.map

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

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