@videojs/spf 10.0.0-beta.30 → 10.0.0-beta.32

package/dist/dev/core/composition/create-composition.d.ts

@@ -1,10 +1,8 @@
 import { ReadonlySignal, Signal } from "../signals/primitives.js";
 //#region src/core/composition/create-composition.d.ts
 /**
- * Cleanup returned by a behavior. Behaviors may return:
- * - `void` / `undefined` — no cleanup needed
- * - A function — called on destroy (may return a Promise)
- * - An object with `destroy()` — called on destroy (may return a Promise)
+ * Cleanup returned by a behavior. Behaviors may return: - `void` / `undefined` — no cleanup needed - A function —
+ * called on destroy (may return a Promise) - An object with `destroy()` — called on destroy (may return a Promise)
  */
 type BehaviorCleanup = void | (() => void | Promise<void>) | {
   destroy(): void | Promise<void>;
@@ -12,46 +10,40 @@ type BehaviorCleanup = void | (() => void | Promise<void>) | {
 /**
  * A signal map keyed by the fields of `S`. Each field is a writable signal.
  *
- * Optional fields on `S` map to required signal slots whose value type
- * includes `undefined`, ensuring every key has a signal even when the
- * underlying value is absent.
+ * Optional fields on `S` map to required signal slots whose value type includes `undefined`, ensuring every key has a
+ * signal even when the underlying value is absent.
  *
  * Used in two roles:
- * - Engine-side **construction**: `Composition<S, C>` exposes its public
- *   surface as `StateSignals<S>` (everything writable) so external code
- *   can read or write any slot.
- * - Behavior **input convenience**: a behavior that writes to every slot
- *   can type its setup state param as `StateSignals<{ ... }>` rather than
- *   spelling out per-slot `Signal<T>` types.
  *
- * Behaviors that mix read-only and writable slots type the setup param
- * directly as a slot map (`{ x: Signal<T>; y: ReadonlySignal<U> }`)
- * instead of going through `StateSignals<>`.
+ * - Engine-side **construction**: `Composition<S, C>` exposes its public surface as `StateSignals<S>` (everything
+ *   writable) so external code can read or write any slot.
+ * - Behavior **input convenience**: a behavior that writes to every slot can type its setup state param as
+ *   `StateSignals<{ ... }>` rather than spelling out per-slot `Signal<T>` types.
+ *
+ * Behaviors that mix read-only and writable slots type the setup param directly as a slot map (`{ x: Signal<T>; y:
+ * ReadonlySignal<U> }`) instead of going through `StateSignals<>`.
  */
 type StateSignals<S extends object> = { [K in keyof S]-?: Signal<S[K]>; };
 /**
- * A signal map keyed by the fields of `C`. Each field is a writable signal
- * for a platform object or actor reference. Same dual role as
- * `StateSignals<S>` — see its docblock.
+ * A signal map keyed by the fields of `C`. Each field is a writable signal for a platform object or actor reference.
+ * Same dual role as `StateSignals<S>` — see its docblock.
  */
 type ContextSignals<C extends object> = { [K in keyof C]-?: Signal<C[K]>; };
 /**
- * Slot-map shape — a record where each value is at least a `ReadonlySignal`.
- * `Signal<T>` is structurally a subtype of `ReadonlySignal<T>` (it adds
- * `.set()`), so a writable slot satisfies this bound too.
+ * Slot-map shape — a record where each value is at least a `ReadonlySignal`. `Signal<T>` is structurally a subtype of
+ * `ReadonlySignal<T>` (it adds `.set()`), so a writable slot satisfies this bound too.
  *
- * This is the bound used for behavior `state` / `context` slot maps. It
- * lets a single behavior declare a *heterogeneous* slot map where some
- * slots are `Signal<T>` (writable) and others are `ReadonlySignal<T>`
- * (read-only) — making read/write intent explicit at the call site and
- * giving body-level enforcement (TS rejects `.set()` on a read-only slot).
+ * This is the bound used for behavior `state` / `context` slot maps. It lets a single behavior declare a
+ * _heterogeneous_ slot map where some slots are `Signal<T>` (writable) and others are `ReadonlySignal<T>` (read-only) —
+ * making read/write intent explicit at the call site and giving body-level enforcement (TS rejects `.set()` on a
+ * read-only slot).
  */
 type AnySlotMap = Record<PropertyKey, ReadonlySignal<unknown>>;
 /**
  * The deps object passed to each behavior by the composition.
  *
- * - `state` — slot map for state fields (reactive data). Per-slot read/
- *   write intent expressed via `Signal<T>` vs `ReadonlySignal<T>`.
+ * - `state` — slot map for state fields (reactive data). Per-slot read/ write intent expressed via `Signal<T>` vs
+ *   `ReadonlySignal<T>`.
  * - `context` — slot map for platform objects and actor references.
  * - `config` — static configuration, passed once at composition creation.
  */
@@ -61,21 +53,16 @@ interface BehaviorDeps<StateMap extends AnySlotMap, ContextMap extends AnySlotMa
   config: Cfg;
 }
 /**
- * A behavior announces the state and context keys it needs alongside a
- * `setup` function that receives deps (state, context, config) and
- * returns an optional cleanup handle.
+ * A behavior announces the state and context keys it needs alongside a `setup` function that receives deps (state,
+ * context, config) and returns an optional cleanup handle.
  *
- * The `stateKeys` / `contextKeys` declarations are the runtime expression
- * of the behavior's contract — the caller (e.g. `createComposition`) uses
- * them to know which signals to provide. The setup parameter type
- * declares the *slot map* (per-slot `Signal<T>` vs `ReadonlySignal<T>`);
- * together they form a complete contract.
+ * The `stateKeys` / `contextKeys` declarations are the runtime expression of the behavior's contract — the caller (e.g.
+ * `createComposition`) uses them to know which signals to provide. The setup parameter type declares the _slot map_
+ * (per-slot `Signal<T>` vs `ReadonlySignal<T>`); together they form a complete contract.
  *
- * Manual `Behavior<>` literals (e.g. engine wrappers that forward keys
- * from a wrapped behavior, or pass-through behaviors like `shareSignals`)
- * opt out of exhaustiveness — the type alias is permissive (subset).
- * Source behaviors should use `defineBehavior` to get exhaustiveness
- * enforcement at the call site.
+ * Manual `Behavior<>` literals (e.g. engine wrappers that forward keys from a wrapped behavior, or pass-through
+ * behaviors like `shareSignals`) opt out of exhaustiveness — the type alias is permissive (subset). Source behaviors
+ * should use `defineBehavior` to get exhaustiveness enforcement at the call site.
  */
 interface Behavior<StateMap extends AnySlotMap = Empty, ContextMap extends AnySlotMap = Empty, Cfg extends object = Empty> {
   /** State keys this behavior reads/writes. Subset of `keyof StateMap`. */
@@ -97,18 +84,16 @@ type DepsOf<B> = B extends {
 /**
  * Empty-object fallback used when a behavior omits state, context, or config.
  *
- * Using `{}` rather than `object` is deliberate — `object & {x: T}` collapses
- * to `{x: never}` under TS's union-to-intersection conversion in some inference
- * contexts (likely a TS quirk around the `object` upper bound), whereas
- * `{} & {x: T}` simplifies cleanly to `{x: T}`.
+ * Using `{}` rather than `object` is deliberate — `object & {x: T}` collapses to `{x: never}` under TS's
+ * union-to-intersection conversion in some inference contexts (likely a TS quirk around the `object` upper bound),
+ * whereas `{} & {x: T}` simplifies cleanly to `{x: T}`.
  */
 type Empty = {};
 /**
  * Unwrap a signal map back to its state/context shape.
  *
- * Inferring through `{ get(): infer V }` rather than `Signal<infer V>`
- * sidesteps `Signal`'s nominal/invariance behaviour — the conditional
- * matches structurally on the read side, and `V` is inferred covariantly.
+ * Inferring through `{ get(): infer V }` rather than `Signal<infer V>` sidesteps `Signal`'s nominal/invariance
+ * behaviour — the conditional matches structurally on the read side, and `V` is inferred covariantly.
  */
 type UnwrapSignals<M> = M extends object ? { [K in keyof M]: M[K] extends {
   get(): infer V;
@@ -128,16 +113,14 @@ type InferBehaviorConfig<F> = DepsOf<F> extends {
 /**
  * Recursively intersect a per-behavior projection across the tuple.
  *
- * Iterating over the tuple directly avoids `UnionToIntersection`'s
- * function-contravariance trick, which produces unstable intersections
- * (collapsing concrete fields to `never` or unrelated types) when one of the
- * union members is the empty `{}` fallback.
+ * Iterating over the tuple directly avoids `UnionToIntersection`'s function-contravariance trick, which produces
+ * unstable intersections (collapsing concrete fields to `never` or unrelated types) when one of the union members is
+ * the empty `{}` fallback.
  */
 type IntersectBehaviors<Behaviors extends readonly AnyBehavior[], Project extends object> = Behaviors extends readonly [infer First extends AnyBehavior, ...infer Rest extends readonly AnyBehavior[]] ? Apply<Project, First> & IntersectBehaviors<Rest, Project> : Empty;
 /**
- * Apply a projection (one of the marker types below) to a single behavior.
- * Encoded as a discriminated dispatch so the recursion above can stay generic
- * and we don't have to write three near-identical recursive types.
+ * Apply a projection (one of the marker types below) to a single behavior. Encoded as a discriminated dispatch so the
+ * recursion above can stay generic and we don't have to write three near-identical recursive types.
  */
 type Apply<Project extends object, F> = Project extends {
   kind: 'state';
@@ -162,29 +145,25 @@ type ResolveBehaviorContext<Behaviors extends readonly AnyBehavior[]> = Intersec
 /** Resolve the combined config shape from an array of behaviors (intersection of all requirements). */
 type ResolveBehaviorConfig<Behaviors extends readonly AnyBehavior[]> = IntersectBehaviors<Behaviors, ConfigProjection> extends (infer R extends object) ? R : Empty;
 /**
- * True if any property in `T` collapsed to `undefined` or `never` — indicating
- * a type conflict from intersecting incompatible behavior requirements.
+ * True if any property in `T` collapsed to `undefined` or `never` — indicating a type conflict from intersecting
+ * incompatible behavior requirements.
  *
  * - Required conflicts: `{ v: number } & { v: string }` → `{ v: never }` — caught via `[never] extends [undefined]`
  * - Optional conflicts: `{ v?: number } & { v?: string }` → `{ v?: undefined }` — caught directly
  */
 type HasConflict<T extends object> = true extends { [K in keyof T]: [T[K]] extends [undefined] ? true : never; }[keyof T] ? true : false;
 /**
- * Validate that a behavior composition has no type conflicts.
- * Returns the behaviors tuple if valid, or an error message type if conflicts are detected.
+ * Validate that a behavior composition has no type conflicts. Returns the behaviors tuple if valid, or an error message
+ * type if conflicts are detected.
  *
- * State, context, and config are all checked the same way — by intersecting
- * each behavior's requirement and looking for collapsed fields. The
- * intersection-based check applies the same rule to context as to state, so
- * two behaviors that disagree on a context field's type (e.g. `Surface` vs
- * `VideoSurface`) surface a conflict at compose time. The prior subtype-based
- * approach for owners is gone — the unified rule is simpler and catches the
- * cases where two behaviors silently agreed on a wider supertype.
+ * State, context, and config are all checked the same way — by intersecting each behavior's requirement and looking for
+ * collapsed fields. The intersection-based check applies the same rule to context as to state, so two behaviors that
+ * disagree on a context field's type (e.g. `Surface` vs `VideoSurface`) surface a conflict at compose time. The prior
+ * subtype-based approach for owners is gone — the unified rule is simpler and catches the cases where two behaviors
+ * silently agreed on a wider supertype.
  */
 type ValidateComposition<Behaviors extends readonly AnyBehavior[]> = HasConflict<ResolveBehaviorState<Behaviors>> extends true ? 'Error: behaviors have conflicting state types' : HasConflict<ResolveBehaviorContext<Behaviors>> extends true ? 'Error: behaviors have conflicting context types' : HasConflict<ResolveBehaviorConfig<Behaviors>> extends true ? 'Error: behaviors have conflicting config types' : [...Behaviors];
-/**
- * A composition of behaviors with shared state and context signal maps.
- */
+/** A composition of behaviors with shared state and context signal maps. */
 interface Composition<S extends object, C extends object> {
   state: StateSignals<S>;
   context: ContextSignals<C>;
@@ -193,10 +172,8 @@ interface Composition<S extends object, C extends object> {
 /**
  * Options for `createComposition`.
  *
- * Composition derives the state and context signal maps from each
- * behavior's declared `stateKeys` / `contextKeys`; `initialState` and
- * `initialContext` seed those signals at creation time. Any unseeded
- * signal starts as `undefined`.
+ * Composition derives the state and context signal maps from each behavior's declared `stateKeys` / `contextKeys`;
+ * `initialState` and `initialContext` seed those signals at creation time. Any unseeded signal starts as `undefined`.
  */
 interface CompositionOptions<S extends object, C extends object, Cfg extends object> {
   /** Static configuration passed to every behavior. */
@@ -210,48 +187,39 @@ declare function createComposition<const Behaviors extends readonly AnyBehavior[
 /**
  * Compose-time exhaustiveness check.
  *
- * Adds a phantom error tag to the parameter shape when `Keys` does not
- * cover every key in `Slot`. The user's value won't satisfy the phantom
- * field requirement, so TS surfaces the failure at the call site with a
- * descriptive message. When exhaustive, the tag is `Empty` and adds no
- * constraint.
+ * Adds a phantom error tag to the parameter shape when `Keys` does not cover every key in `Slot`. The user's value
+ * won't satisfy the phantom field requirement, so TS surfaces the failure at the call site with a descriptive message.
+ * When exhaustive, the tag is `Empty` and adds no constraint.
  */
 type ExhaustiveKeys<Keys extends readonly PropertyKey[], Slot extends object, Name extends string> = [keyof Slot] extends [Keys[number]] ? Empty : { [K in `Error: ${Name}Keys must list every key in the typed slice`]: Exclude<keyof Slot, Keys[number]>; };
 /**
- * Typed factory for behaviors that enforces single-behavior key/param
- * consistency: declared `stateKeys` must equal `keyof S` (where `S` is
- * inferred from the setup's `state` parameter type), and same for
- * `contextKeys` / `C`.
+ * Typed factory for behaviors that enforces single-behavior key/param consistency: declared `stateKeys` must equal
+ * `keyof S` (where `S` is inferred from the setup's `state` parameter type), and same for `contextKeys` / `C`.
  *
- * The `const` modifier on `SK` / `CK` captures literal tuples so e.g.
- * `stateKeys: ['preload']` infers as `readonly ['preload']`, no `as
- * const` needed at the call site.
+ * The `const` modifier on `SK` / `CK` captures literal tuples so e.g. `stateKeys: ['preload']` infers as `readonly
+ * ['preload']`, no `as const` needed at the call site.
  *
- * Cross-behavior consistency at `createComposition` is unchanged — the
- * existing `IntersectBehaviors` machinery still runs over each
- * behavior's setup param type.
+ * Cross-behavior consistency at `createComposition` is unchanged — the existing `IntersectBehaviors` machinery still
+ * runs over each behavior's setup param type.
  *
  * @example
- * ```ts
- * export const syncPreload = defineBehavior({
+ *   ```ts
+ *   export const syncPreload = defineBehavior({
  *   stateKeys: ['preload'],
  *   contextKeys: ['mediaElement'],
  *   setup: ({ state, context }: {
- *     state: StateSignals<{ preload?: 'auto' | 'metadata' | 'none' }>;
- *     context: ContextSignals<{ mediaElement?: HTMLMediaElement | undefined }>;
+ *   state: StateSignals<{ preload?: 'auto' | 'metadata' | 'none' }>;
+ *   context: ContextSignals<{ mediaElement?: HTMLMediaElement | undefined }>;
  *   }) => { ... },
- * });
- * ```
+ *   });
+ *   ```;
  */
 /**
- * Deps shape for a behavior whose deps slot is empty (no keys). When a
- * slot is empty, the corresponding deps field is optional — callers
- * (typically tests) can omit it, and it defaults to `{}` at runtime via
- * `createComposition`.
+ * Deps shape for a behavior whose deps slot is empty (no keys). When a slot is empty, the corresponding deps field is
+ * optional — callers (typically tests) can omit it, and it defaults to `{}` at runtime via `createComposition`.
  *
- * When a slot has at least one key, the behavior reads `state.foo` /
- * `context.bar` / `config.baz` and we need the field to be required so
- * the access is type-safe.
+ * When a slot has at least one key, the behavior reads `state.foo` / `context.bar` / `config.baz` and we need the field
+ * to be required so the access is type-safe.
  */
 type RequireIfNonEmpty<Key extends string, T extends object> = keyof T extends never ? { [K in Key]?: T; } : { [K in Key]: T; };
 type DepsForCfg<StateMap extends AnySlotMap, ContextMap extends AnySlotMap, Cfg extends object> = RequireIfNonEmpty<'state', StateMap> & RequireIfNonEmpty<'context', ContextMap> & RequireIfNonEmpty<'config', Cfg>;

package/dist/dev/core/composition/create-composition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-composition.d.ts","names":[],"sources":["../../../../src/core/composition/create-composition.ts"],"mappings":";;;;;;;;KAQY,uCAAuC;EAAmB,kBAAkB;;;;;;;;;;;;;;;;;;;;;KAqB5E,aAAa,uBAAuB,WAAW,MAAM,OAAO,EAAE;;;;;;KAO9D,eAAe,uBAAuB,WAAW,MAAM,OAAO,EAAE;;;;;;;;;;;;KAahE,aAAa,OAAO,aAAa;;;;;;;;;UAU5B,aAAa,iBAAiB,YAAY,mBAAmB,YAAY;EACxF,OAAO;EACP,SAAS;EACT,QAAQ;;;;;;;;;;;;;;;;;;;UAoBO,SACf,iBAAiB,aAAa,OAC9B,mBAAmB,aAAa,OAChC,qBAAqB;;EAGrB,2BAA2B;;EAE3B,6BAA6B;EAC7B,QAAQ,MAAM,aAAa,UAAU,YAAY,SAAS;;;KAQvD;EACH,oBAAoB;EACpB,sBAAsB;EACtB,QAAQ,cAAc;;;KAInB,OAAO,KAAK;EAAY,QAAQ,YAAY,MAAM;IAAwB;;;;;;;;;KAW1E;;;;;;;;KASA,cAAc,KAAK,sBAAsB,WAAW,IAAI,EAAE;EAAa,aAAa;IAAM,eAAc;;KAGjG,mBAAmB,KAAK,OAAO;EAAa,aAAa;IAAM,cAAc,KAAK;;KAGlF,qBAAqB,KAAK,OAAO;EAAa,eAAe;IAAM,cAAc,KAAK;;KAGtF,oBAAoB,KAAK,OAAO;EAAa,cAAc;IAAqB,IAAI;;;;;;;;;KAU3F,mBAAmB,2BAA2B,eAAe,0BAA0B,kCACpF,cAAc,sBACX,sBAAsB,iBAE7B,MAAM,SAAS,SAAS,mBAAmB,MAAM,WACjD;;;;;;KAOC,MAAM,wBAAwB,KAAK;EAAkB;IACtD,mBAAmB,KACnB;EAAkB;IAChB,qBAAqB,KACrB;EAAkB;IAChB,oBAAoB;KAGvB;EAAoB;;KACpB;EAAsB;;KACtB;EAAqB;;;KAGd,qBAAqB,2BAA2B,iBAC1D,mBAAmB,WAAW,gCAA+B,oBAAmB,IAAI;;KAG1E,uBAAuB,2BAA2B,iBAC5D,mBAAmB,WAAW,kCAAiC,oBAAmB,IAAI;;KAG5E,sBAAsB,2BAA2B,iBAC3D,mBAAmB,WAAW,iCAAgC,oBAAmB,IAAI;;;;;;;;KASlF,YAAY,oCACd,WAAW,KAAK,EAAE,gDACb;;;;;;;;;;;;;KAoBH,oBAAoB,2BAA2B,iBAClD,YAAY,qBAAqB,6EAE7B,YAAY,uBAAuB,+EAEjC,YAAY,sBAAsB,kFAE5B;;;;UASG,YAAY,kBAAkB;EAC7C,OAAO,aAAa;EACpB,SAAS,eAAe;EACxB,WAAW;;;;;;;;;;UAWI,mBAAmB,kBAAkB,kBAAkB;;EAEtE,SAAS;;EAET,eAAe,QAAQ;;EAEvB,iBAAiB,QAAQ;;iBA2DX,wBAAwB,2BAA2B,eACjE,WAAW,oBAAoB,YAC/B,UAAU,mBACR,qBAAqB,YACrB,uBAAuB,YACvB,sBAAsB,cAEvB,YAAY,qBAAqB,YAAY,uBAAuB;;;;;;;;;;KA8DlE,eAAe,sBAAsB,eAAe,qBAAqB,8BACtE,eACG,gBACP,WACG,eAAe,oDAAoD,cAAc,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAsCzF,kBAAkB,oBAAoB,0BAA0B,qBAC9D,KAAK,OAAO,UACZ,KAAK,MAAM;KAEb,WAAW,iBAAiB,YAAY,mBAAmB,YAAY,sBAAsB,2BAEhG,YAEA,6BAA6B,cAC7B,4BAA4B;iBAEd,eACd,iBAAiB,aAAa,OAC9B,mBAAmB,aAAa,OAChC,qBAAqB,aACf,2BAA2B,iCAC3B,2BAA2B,6BACjC,UAAU,kBAAkB,iBAE5B;EACE,WAAW;EACX,aAAa;EACb,QAAQ;IAAQ,OAAO;IAAU,SAAS;IAAY,QAAQ;QAAU;IACtE,eAAe,IAAI,qBACrB,eAAe,IAAI;EAErB,WAAW;EACX,aAAa;EACb,QAAQ,MAAM,WAAW,UAAU,YAAY,SAAS"}
+{"version":3,"file":"create-composition.d.ts","names":[],"sources":["../../../../src/core/composition/create-composition.ts"],"mappings":";;;;;;KAMY,uCAAuC;EAAmB,kBAAkB;;;;;;;;;;;;;;;;;;KAkB5E,aAAa,uBAAuB,WAAW,MAAM,OAAO,EAAE;;;;;KAM9D,eAAe,uBAAuB,WAAW,MAAM,OAAO,EAAE;;;;;;;;;;KAWhE,aAAa,OAAO,aAAa;;;;;;;;;UAU5B,aAAa,iBAAiB,YAAY,mBAAmB,YAAY;EACxF,OAAO;EACP,SAAS;EACT,QAAQ;;;;;;;;;;;;;;UAeO,SACf,iBAAiB,aAAa,OAC9B,mBAAmB,aAAa,OAChC,qBAAqB;;EAGrB,2BAA2B;;EAE3B,6BAA6B;EAC7B,QAAQ,MAAM,aAAa,UAAU,YAAY,SAAS;;;KAQvD;EACH,oBAAoB;EACpB,sBAAsB;EACtB,QAAQ,cAAc;;;KAInB,OAAO,KAAK;EAAY,QAAQ,YAAY,MAAM;IAAwB;;;;;;;;KAW1E;;;;;;;KAQA,cAAc,KAAK,sBAAsB,WAAW,IAAI,EAAE;EAAa,aAAa;IAAM,eAAc;;KAGjG,mBAAmB,KAAK,OAAO;EAAa,aAAa;IAAM,cAAc,KAAK;;KAGlF,qBAAqB,KAAK,OAAO;EAAa,eAAe;IAAM,cAAc,KAAK;;KAGtF,oBAAoB,KAAK,OAAO;EAAa,cAAc;IAAqB,IAAI;;;;;;;;KAS3F,mBAAmB,2BAA2B,eAAe,0BAA0B,kCACpF,cAAc,sBACX,sBAAsB,iBAE7B,MAAM,SAAS,SAAS,mBAAmB,MAAM,WACjD;;;;;KAMC,MAAM,wBAAwB,KAAK;EAAkB;IACtD,mBAAmB,KACnB;EAAkB;IAChB,qBAAqB,KACrB;EAAkB;IAChB,oBAAoB;KAGvB;EAAoB;;KACpB;EAAsB;;KACtB;EAAqB;;;KAGd,qBAAqB,2BAA2B,iBAC1D,mBAAmB,WAAW,gCAA+B,oBAAmB,IAAI;;KAG1E,uBAAuB,2BAA2B,iBAC5D,mBAAmB,WAAW,kCAAiC,oBAAmB,IAAI;;KAG5E,sBAAsB,2BAA2B,iBAC3D,mBAAmB,WAAW,iCAAgC,oBAAmB,IAAI;;;;;;;;KASlF,YAAY,oCACd,WAAW,KAAK,EAAE,gDACb;;;;;;;;;;;KAkBH,oBAAoB,2BAA2B,iBAClD,YAAY,qBAAqB,6EAE7B,YAAY,uBAAuB,+EAEjC,YAAY,sBAAsB,kFAE5B;;UAOG,YAAY,kBAAkB;EAC7C,OAAO,aAAa;EACpB,SAAS,eAAe;EACxB,WAAW;;;;;;;;UASI,mBAAmB,kBAAkB,kBAAkB;;EAEtE,SAAS;;EAET,eAAe,QAAQ;;EAEvB,iBAAiB,QAAQ;;iBAyDX,wBAAwB,2BAA2B,eACjE,WAAW,oBAAoB,YAC/B,UAAU,mBACR,qBAAqB,YACrB,uBAAuB,YACvB,sBAAsB,cAEvB,YAAY,qBAAqB,YAAY,uBAAuB;;;;;;;;KAiElE,eAAe,sBAAsB,eAAe,qBAAqB,8BACtE,eACG,gBACP,WACG,eAAe,oDAAoD,cAAc,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA+BzF,kBAAkB,oBAAoB,0BAA0B,qBAC9D,KAAK,OAAO,UACZ,KAAK,MAAM;KAEb,WAAW,iBAAiB,YAAY,mBAAmB,YAAY,sBAAsB,2BAEhG,YAEA,6BAA6B,cAC7B,4BAA4B;iBAEd,eACd,iBAAiB,aAAa,OAC9B,mBAAmB,aAAa,OAChC,qBAAqB,aACf,2BAA2B,iCAC3B,2BAA2B,6BACjC,UAAU,kBAAkB,iBAE5B;EACE,WAAW;EACX,aAAa;EACb,QAAQ;IAAQ,OAAO;IAAU,SAAS;IAAY,QAAQ;QAAU;IACtE,eAAe,IAAI,qBACrB,eAAe,IAAI;EAErB,WAAW;EACX,aAAa;EACb,QAAQ,MAAM,WAAW,UAAU,YAAY,SAAS"}

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

@@ -3,47 +3,44 @@ import { signal } from "../signals/primitives.js";
 /**
 * 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.
+* 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`.
+* Cross-behavior type conflicts (e.g. two behaviors disagreeing on a field's type) surface as a compose-time type error
+* via `ValidateComposition`.
 *
 * @example
-* ```ts
-* const composition = createComposition([resolvePresentation, switchVideoTrack], {
+*   ```ts
+*   const composition = createComposition([resolvePresentation, switchVideoTrack], {
 *   config: { parsePresentation: parseMultivariantPlaylist, initialBandwidth: 2_000_000 },
 *   initialState: { bandwidthState: { fastEstimate: 0, ... } },
-* });
-* ```
+*   });
+*   ```;
 */
 /**
-* Create a typed signal map for a given set of keys, seeded from an
-* optional partial initial value.
+* 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`.
+* 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`.
+* 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`.
+* 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
-* ```
+*   ```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;

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

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

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

@@ -3,14 +3,12 @@ import { Behavior, ContextSignals, StateSignals } from "./create-composition.js"
 /**
  * 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 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.
+ * 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: {
@@ -19,26 +17,21 @@ interface ShareSignalsConfig<S extends object, C extends object> {
   }) => void;
 }
 /**
- * Behavior factory that hands the composition's signal refs to a
- * consumer-supplied callback (`config.onSignalsReady`) at setup time.
+ * 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).
+ * 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.
+ * 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.
+ * 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

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

@@ -1 +1 @@
-{"version":3,"file":"share-signals.d.ts","names":[],"sources":["../../../../src/core/composition/share-signals.ts"],"mappings":";;;;;;;;;;;;;;UAciB,mBAAmB,kBAAkB;EACpD,kBAAkB;IAAW,OAAO,aAAa;IAAI,SAAS,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;iBAyB/D,iBAAiB,kBAAkB,kBACjD,iCAAgC,MAChC,mCAAkC,OACjC,SAAS,aAAa,IAAI,eAAe,IAAI,mBAAmB,GAAG"}
+{"version":3,"file":"share-signals.d.ts","names":[],"sources":["../../../../src/core/composition/share-signals.ts"],"mappings":";;;;;;;;;;;;UAYiB,mBAAmB,kBAAkB;EACpD,kBAAkB;IAAW,OAAO,aAAa;IAAI,SAAS,eAAe;;;;;;;;;;;;;;;;;;;;iBAoB/D,iBAAiB,kBAAkB,kBACjD,iCAAgC,MAChC,mCAAkC,OACjC,SAAS,aAAa,IAAI,eAAe,IAAI,mBAAmB,GAAG"}

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

@@ -1,25 +1,20 @@
 //#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.
+* 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).
+* 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.
+* 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.
+* 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 {

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

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