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

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

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

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

package/dist/dev/core/composition/share-signals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"share-signals.d.ts","names":[],"sources":["../../../../src/core/composition/share-signals.ts"],"mappings":";;;;;AAcA;;;;;;;;;;UAAiB,kBAAA;EACf,cAAA,IAAkB,OAAA;IAAW,KAAA,EAAO,YAAA,CAAa,CAAA;IAAI,OAAA,EAAS,cAAA,CAAe,CAAA;EAAA;AAAA;;;;;;AAyB/E;;;;;;;;;;;;;;;;;iBAAgB,gBAAA,oCAAA,CACd,cAAA,mBAAgC,CAAA,KAChC,gBAAA,mBAAkC,CAAA,MACjC,QAAA,CAAS,YAAA,CAAa,CAAA,GAAI,cAAA,CAAe,CAAA,GAAI,kBAAA,CAAmB,CAAA,EAAG,CAAA"}

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

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

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

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

package/dist/dev/core/machine.d.ts

@@ -1,5 +1,4 @@
 import { ReadonlySignal } from "./signals/primitives.js";
-
 //#region src/core/machine.d.ts
 /**
  * Base snapshot for all machine-like primitives (Actors and Reactors).

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

@@ -1 +1 @@
-{"version":3,"file":"machine.d.ts","names":[],"sources":["../../../src/core/machine.ts"],"mappings":";;;;;AAWA;;UAAiB,eAAA;EACf,KAAA,EAAO,KAAA;AAAA;;;;;UAWQ,OAAA,kBAAyB,eAAA;EAAA,SAC/B,QAAA,EAAU,cAAA,CAAe,QAAA;EAClC,OAAA;AAAA"}
+{"version":3,"file":"machine.d.ts","names":[],"sources":["../../../src/core/machine.ts"],"mappings":";;;;;AAWA;UAAiB,eAAA;EACf,KAAA,EAAO,KAAA;AAAA;;;;;UAWQ,OAAA,kBAAyB,eAAA;EAAA,SAC/B,QAAA,EAAU,cAAA,CAAe,QAAA;EAClC,OAAA;AAAA"}

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

@@ -0,0 +1,93 @@
+import { Machine, MachineSnapshot } from "../machine.js";
+
+//#region src/core/reactors/create-machine-reactor.d.ts
+/**
+ * A reactive state-deriving function used in the `monitor` field.
+ *
+ * Returns the target state the reactor should be in. Any signals read inside
+ * the fn body create reactive dependencies — the framework re-evaluates it when
+ * those signals change and automatically calls `transition()` when the returned
+ * state differs from the current one.
+ */
+type ReactorDeriveFn<State extends string> = () => State;
+/**
+ * An effect function used in reactor `entry` and `effects` blocks.
+ *
+ * May return a cleanup function that runs before each re-evaluation and on
+ * state exit (including destroy).
+ */
+type ReactorEffectFn = () => (() => void) | {
+  abort(): void;
+} | void;
+/**
+ * Per-state effect grouping for a single reactor state.
+ *
+ * - `entry` effects run once on state entry. The fn body is automatically
+ *   untracked — no `untrack()` calls are needed inside. Use this for
+ *   one-time setup: reading current values, attaching event listeners, etc.
+ * - `effects` run on state entry and re-run whenever a signal read inside
+ *   the fn body changes. Use `untrack()` for reads you do not want to track.
+ *   Use this for work that must stay in sync with reactive state.
+ *
+ * Both are optional; pass `{}` for states with no effects.
+ */
+type ReactorStateDefinition = {
+  entry?: ReactorEffectFn | ReactorEffectFn[];
+  effects?: ReactorEffectFn | ReactorEffectFn[];
+};
+/**
+ * Full reactor definition passed to `createMachineReactor`.
+ *
+ * `State` is the set of domain-meaningful states. `'destroying'` and
+ * `'destroyed'` are always added by the framework as implicit terminal states —
+ * do not include them here.
+ */
+type ReactorDefinition<State extends string> = {
+  /** Initial state. */initial: State;
+  /**
+   * Reactive state derivation. Registered before per-state effects — the
+   * ordering guarantee ensures transitions fired here take effect before
+   * per-state effects re-evaluate in the same flush.
+   */
+  monitor?: ReactorDeriveFn<State> | ReactorDeriveFn<State>[];
+  /**
+   * Per-state effect groupings. Every valid state must be declared — pass `{}`
+   * for states with no effects. `entry` and `effects` each become independent
+   * `effect()` calls gated on that state, with their own cleanup lifecycles.
+   */
+  states: Record<State, ReactorStateDefinition>;
+};
+/** Live reactor instance returned by `createMachineReactor`. */
+type Reactor<State extends string> = Machine<MachineSnapshot<State>>;
+/**
+ * Creates a reactive Reactor from a declarative definition.
+ *
+ * A Reactor is driven by subscriptions to external signals rather than
+ * imperative messages. Each state holds an array of effect functions —
+ * every element becomes one independent `effect()` call gated on that state,
+ * with its own dependency tracking and cleanup lifecycle.
+ *
+ * `'destroying'` and `'destroyed'` are always implicit terminal states.
+ * `destroy()` transitions through both in sequence: `'destroying'` first (for
+ * potential async teardown in a future extension), then immediately `'destroyed'`
+ * for the synchronous base case. Active effect cleanups fire via disposal.
+ *
+ * @example
+ * const reactor = createMachineReactor({
+ *   initial: 'waiting',
+ *   monitor: () => srcSignal.get() ? 'active' : 'waiting',
+ *   states: {
+ *     active: {
+ *       // entry: runs once on state entry; fn body is automatically untracked.
+ *       entry: () => listen(el, 'play', handler),
+ *       // effects: re-runs whenever tracked signals change.
+ *       effects: () => { currentTimeSignal.get(); return cleanup; },
+ *     },
+ *     waiting: {},
+ *   }
+ * });
+ */
+declare function createMachineReactor<State extends string>(def: ReactorDefinition<State>): Reactor<State | 'destroying' | 'destroyed'>;
+//#endregion
+export { Reactor, ReactorDefinition, ReactorDeriveFn, ReactorEffectFn, ReactorStateDefinition, createMachineReactor };
+//# sourceMappingURL=create-machine-reactor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-machine-reactor.d.ts","names":[],"sources":["../../../../src/core/reactors/create-machine-reactor.ts"],"mappings":";;;;;AAiBA;;;;;AAQA;KARY,eAAA,+BAA8C,KAAA;;;;AAsB1D;;;KAdY,eAAA;EAAyC,KAAA;AAAA;;;;;;;;;;;;AA0BrD;KAZY,sBAAA;EACV,KAAA,GAAQ,eAAA,GAAkB,eAAA;EAC1B,OAAA,GAAU,eAAA,GAAkB,eAAA;AAAA;;;;;;;;KAUlB,iBAAA;EAAkB,qBAE5B,OAAA,EAAS,KAAA;EAAA;;;;;EAMT,OAAA,GAAU,eAAA,CAAgB,KAAA,IAAS,eAAA,CAAgB,KAAA;EAMnD;;;;;EAAA,MAAA,EAAQ,MAAA,CAAO,KAAA,EAAO,sBAAA;AAAA;;KAQZ,OAAA,yBAAgC,OAAA,CAAQ,eAAA,CAAgB,KAAA;;;;;;;;;;;;AAwCpE;;;;;;;;;;;;;;;;;iBAAgB,oBAAA,sBAAA,CACd,GAAA,EAAK,iBAAA,CAAkB,KAAA,IACtB,OAAA,CAAQ,KAAA"}

package/dist/{default/core → dev/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/dev/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/dev/core/signals/primitives.d.ts

@@ -1,10 +1,47 @@
 import { Signal } from "signal-polyfill";
 
 //#region src/core/signals/primitives.d.ts
+/** Read a signal value without tracking it as a dependency. */
+declare const untrack: <T>(fn: () => T) => T;
 /** A writable reactive value (read + write). */
 type Signal$1<T> = Signal.State<T>;
+/** A derived reactive value that re-evaluates when its dependencies change (read-only). */
+type Computed<T> = Signal.Computed<T>;
 /** A read-only view of a reactive value. */
 type ReadonlySignal<T> = Omit<Signal.State<T>, 'set'>;
+interface SignalOptions<T> {
+  equals?: (t: T, t2: T) => boolean;
+}
+/** Create a writable reactive value. */
+declare function signal<T>(initialValue: T, options?: SignalOptions<T>): Signal$1<T>;
+/** Create a computed reactive value. */
+declare function computed<T>(fn: () => T, options?: SignalOptions<T>): Computed<T>;
+/**
+ * Update a writable signal. Two forms:
+ *
+ * - **Updater function** `(current) => next`. Works for any signal type,
+ *   including `Signal<T | undefined>` — handle undefined in the updater.
+ * - **Partial object** to merge into the current state. Requires
+ *   `T extends object`.
+ *
+ * @example
+ * update(state, { playbackRate: 2 });
+ * update(state, (s) => ({ ...s, count: s.count + 1 }));
+ * update(maybeUndefinedSignal, (current) => current ?? defaultValue);
+ */
+declare function update<T>(signal: Signal$1<T>, updater: (current: T) => T): void;
+declare function update<T extends object>(signal: Signal$1<T>, updater: Partial<T>): void;
+/**
+ * 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.
+ */
+declare function snapshot<M extends Record<string, ReadonlySignal<unknown>>>(map: M): { [K in keyof M]: M[K] extends {
+  get(): infer V;
+} ? V : never };
 //#endregion
-export { ReadonlySignal, Signal$1 as Signal };
+export { Computed, ReadonlySignal, Signal$1 as Signal, SignalOptions, computed, signal, snapshot, untrack, update };
 //# sourceMappingURL=primitives.d.ts.map

package/dist/dev/core/signals/primitives.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"primitives.d.ts","names":[],"sources":["../../../../src/core/signals/primitives.ts"],"mappings":";;;AAMA;AAAA,KAAY,QAAA,MAAY,MAAA,CAAS,KAAA,CAAM,CAAA;;KAM3B,cAAA,MAAoB,IAAA,CAAK,MAAA,CAAS,KAAA,CAAM,CAAA"}
+{"version":3,"file":"primitives.d.ts","names":[],"sources":["../../../../src/core/signals/primitives.ts"],"mappings":";;;;cAGa,OAAA,MAAa,EAAA,QAAU,CAAA,KAAM,CAAA;;KAqB9B,QAAA,MAAY,MAAA,CAAS,KAAA,CAAM,CAAA;;KAG3B,QAAA,MAAc,MAAA,CAAS,QAAA,CAAS,CAAA;;KAGhC,cAAA,MAAoB,IAAA,CAAK,MAAA,CAAS,KAAA,CAAM,CAAA;AAAA,UAEnC,aAAA;EACf,MAAA,IAAU,CAAA,EAAG,CAAA,EAAG,EAAA,EAAI,CAAA;AAAA;;iBAIN,MAAA,GAAA,CAAU,YAAA,EAAc,CAAA,EAAG,OAAA,GAAU,aAAA,CAAc,CAAA,IAAK,QAAA,CAAO,CAAA;;iBAK/D,QAAA,GAAA,CAAY,EAAA,QAAU,CAAA,EAAG,OAAA,GAAU,aAAA,CAAc,CAAA,IAAK,QAAA,CAAS,CAAA;AAZ/E;;;;;;;;;;;;;AAAA,iBA6BgB,MAAA,GAAA,CAAU,MAAA,EAAQ,QAAA,CAAO,CAAA,GAAI,OAAA,GAAU,OAAA,EAAS,CAAA,KAAM,CAAA;AAAA,iBACtD,MAAA,kBAAA,CAAyB,MAAA,EAAQ,QAAA,CAAO,CAAA,GAAI,OAAA,EAAS,OAAA,CAAQ,CAAA;;;;;;;;;iBAqC7D,QAAA,WAAmB,MAAA,SAAe,cAAA,WAAA,CAChD,GAAA,EAAK,CAAA,iBACU,CAAA,GAAI,CAAA,CAAE,CAAA;EAAa,GAAA;AAAA,IAAmB,CAAA"}

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

@@ -0,0 +1,115 @@
+//#region src/core/tasks/task.d.ts
+/** Recursively marks all properties as readonly. */
+type DeepReadonly<T> = T extends (infer U)[] ? ReadonlyArray<DeepReadonly<U>> : T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]> } : T;
+type TaskStatus = 'pending' | 'running' | 'done' | 'error';
+/**
+ * Configuration for a Task.
+ */
+interface TaskConfig {
+  /**
+   * Identifier for this task.
+   * - string: used as-is
+   * - () => string: called once at construction time
+   * - undefined: a unique ID is generated via generateId()
+   */
+  id?: string | (() => string);
+  /**
+   * Optional external AbortSignal to compose with the task's internal one.
+   * The task's work is aborted when either the internal controller (via abort())
+   * or this external signal fires — whichever comes first.
+   */
+  signal?: AbortSignal;
+}
+/**
+ * Minimal contract for a schedulable unit of async work.
+ */
+interface TaskLike<TValue = void, TError = unknown> {
+  readonly id: string;
+  readonly status: TaskStatus;
+  readonly value: DeepReadonly<TValue> | undefined;
+  readonly error: DeepReadonly<TError> | undefined;
+  run(): Promise<TValue>;
+  abort(): void;
+}
+/**
+ * Generic reusable task that wraps an async run function.
+ *
+ * Owns its own AbortController so it can always be aborted independently.
+ * Optionally composes an external AbortSignal so that a parent's cancellation
+ * propagates into the task's work without requiring the caller to track the
+ * task separately.
+ *
+ * Ordering guarantee: `value` is written before `status` transitions to `'done'`;
+ * `error` is written before `status` transitions to `'error'`. Any reader
+ * observing `status === 'done'` is guaranteed `value` is already present.
+ */
+declare class Task<TValue = void, TError = unknown> implements TaskLike<TValue, TError> {
+  #private;
+  readonly id: string;
+  constructor(runFn: (signal: AbortSignal) => Promise<TValue>, config?: TaskConfig);
+  get status(): TaskStatus;
+  get value(): DeepReadonly<TValue> | undefined;
+  get error(): DeepReadonly<TError> | undefined;
+  run(): Promise<TValue>;
+  abort(): void;
+}
+/**
+ * Runs tasks concurrently, deduplicated by task id.
+ *
+ * If a task with a given id is already in flight, subsequent schedule() calls
+ * for that id are silently ignored until the first completes. Tasks are stored
+ * so abortAll() can cancel any in-flight work (e.g. on engine cleanup).
+ */
+declare class ConcurrentRunner {
+  #private;
+  schedule<TValue = void, TError = unknown>(task: TaskLike<TValue, TError>): Promise<TValue>;
+  /**
+   * Registers a callback to fire when all currently in-flight tasks settle.
+   * If the runner is already idle, the callback is never called. If abortAll()
+   * is called before the batch settles, the callback is superseded and silently
+   * dropped — no stale callbacks, no generation token required by the caller.
+   */
+  whenSettled(callback: () => void): void;
+  abortAll(): void;
+  destroy(): void;
+}
+/**
+ * Runs tasks one at a time in submission order.
+ *
+ * Each schedule() call returns a Promise that resolves or rejects with the
+ * task's result when it is eventually executed. Tasks wait in queue until the
+ * prior task completes.
+ *
+ * Serialization is achieved by chaining each task's run() onto the tail of a
+ * shared promise chain — no explicit queue or drain loop needed.
+ *
+ * abortAll() aborts all pending (not yet started) tasks and the currently
+ * in-flight task. Pending tasks still run briefly but receive an aborted
+ * signal and are expected to exit early.
+ */
+declare class SerialRunner {
+  #private;
+  schedule<TValue = void, TError = unknown>(task: TaskLike<TValue, TError>): Promise<TValue>;
+  /**
+   * A promise that resolves when all currently-scheduled tasks have settled.
+   * Use the reference as a generation token: capture it after scheduling a
+   * batch, then check identity in the resolution callback to detect whether
+   * a subsequent abortAll() + new batch has superseded this one.
+   */
+  get settled(): Promise<void>;
+  /**
+   * Registers a callback to fire when all currently-pending tasks settle.
+   * If the runner is already idle (no pending or running tasks), the callback
+   * is never called. If new tasks are scheduled before the current batch
+   * settles, the callback is superseded and silently dropped — no stale
+   * callbacks, no generation token required by the caller.
+   */
+  whenSettled(callback: () => void): void;
+  /** Aborts and clears queued tasks without touching the in-flight task. */
+  abortPending(): void;
+  abortAll(): void;
+  destroy(): void;
+}
+//#endregion
+export { ConcurrentRunner, SerialRunner, Task, TaskConfig, TaskLike, TaskStatus };
+//# sourceMappingURL=task.d.ts.map

package/dist/dev/core/tasks/task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.d.ts","names":[],"sources":["../../../../src/core/tasks/task.ts"],"mappings":";;KAQY,YAAA,MAAkB,CAAA,uBAC1B,aAAA,CAAc,YAAA,CAAa,CAAA,KAC3B,CAAA,yCACyB,CAAA,GAAI,YAAA,CAAa,CAAA,CAAE,CAAA,OAC1C,CAAA;AAAA,KAMM,UAAA;;;;UAKK,UAAA;EAZY;;;;;;EAmB3B,EAAA;EAtBuB;;;;;EA6BvB,MAAA,GAAS,WAAA;AAAA;;;;UAMM,QAAA;EAAA,SACN,EAAA;EAAA,SACA,MAAA,EAAQ,UAAA;EAAA,SACR,KAAA,EAAO,YAAA,CAAa,MAAA;EAAA,SACpB,KAAA,EAAO,YAAA,CAAa,MAAA;EAC7B,GAAA,IAAO,OAAA,CAAQ,MAAA;EACf,KAAA;AAAA;;;AA1BF;;;;;;;;;AAoBA;cAqBa,IAAA,6CAAiD,QAAA,CAAS,MAAA,EAAQ,MAAA;EAAA;WACpE,EAAA;EAST,WAAA,CAAY,KAAA,GAAQ,MAAA,EAAQ,WAAA,KAAgB,OAAA,CAAQ,MAAA,GAAS,MAAA,GAAS,UAAA;EAAA,IASlE,MAAA,CAAA,GAAU,UAAA;EAAA,IAIV,KAAA,CAAA,GAAS,YAAA,CAAa,MAAA;EAAA,IAItB,KAAA,CAAA,GAAS,YAAA,CAAa,MAAA;EAIpB,GAAA,CAAA,GAAO,OAAA,CAAQ,MAAA;EAcrB,KAAA,CAAA;AAAA;;;;;;;;cAgBW,gBAAA;EAAA;EAMX,QAAA,iCAAA,CAA0C,IAAA,EAAM,QAAA,CAAS,MAAA,EAAQ,MAAA,IAAU,OAAA,CAAQ,MAAA;EApFnE;;;;;;EAsHhB,WAAA,CAAY,QAAA;EAYZ,QAAA,CAAA;EAWA,OAAA,CAAA;AAAA;;;;;;;;;;;;;;;cAwBW,YAAA;EAAA;EAMX,QAAA,iCAAA,CAA0C,IAAA,EAAM,QAAA,CAAS,MAAA,EAAQ,MAAA,IAAU,OAAA,CAAQ,MAAA;EA1JnE;;;;;;EAAA,IAwLZ,OAAA,CAAA,GAAW,OAAA;EA9Kf;;;;;;;EAyLA,WAAA,CAAY,QAAA;EAhLR;EA6LJ,YAAA,CAAA;EAKA,QAAA,CAAA;EAKA,OAAA,CAAA;AAAA"}

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

@@ -1,10 +1,9 @@
-import { appendSegment } from "./dom/media/append-segment.js";
-import { loadSegments } from "./dom/features/load-segments.js";
-import { loadTextTrackCues } from "./dom/features/load-text-track-cues.js";
-import { CurrentTimeOwners, CurrentTimeState, trackCurrentTime } from "./dom/features/track-current-time.js";
-import { PlaybackInitiatedOwners, PlaybackInitiatedState, trackPlaybackInitiated } from "./dom/features/track-playback-initiated.js";
-import { PlaybackRateOwners, PlaybackRateState, trackPlaybackRate } from "./dom/features/track-playback-rate.js";
-import { flushBuffer } from "./dom/media/buffer-flusher.js";
-import { SpfMedia, SpfMediaAPI, SpfMediaMixin, SpfMediaProps, spfMediaDefaultProps } from "./dom/playback-engine/adapter.js";
-import { destroyVttParser, parseVttSegment } from "./dom/text/parse-vtt-segment.js";
-export { type CurrentTimeOwners, type CurrentTimeState, type PlaybackInitiatedOwners, type PlaybackInitiatedState, type PlaybackRateOwners, type PlaybackRateState, SpfMedia, type SpfMediaAPI, SpfMediaMixin, type SpfMediaProps, 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 { CurrentTimeContext, CurrentTimeState, trackCurrentTime } from "./playback/behaviors/dom/track-current-time.js";
+import { LoadTriggersContext, LoadTriggersState, trackLoadTriggers } from "./playback/behaviors/dom/track-load-triggers.js";
+import { PlaybackRateContext, PlaybackRateState, trackPlaybackRate } from "./playback/behaviors/dom/track-playback-rate.js";
+export { type CurrentTimeContext, type CurrentTimeState, type LoadTriggersContext, type LoadTriggersState, type PlaybackRateContext, type PlaybackRateState, appendSegment, destroyVttResolver, flushBuffer, loadAudioSegments, loadVideoSegments, resolveVttSegment, setupTextTrackActors, trackCurrentTime, trackLoadTriggers, trackPlaybackRate };