coily 0.12.2 → 0.13.1

package/dist/{system-coAFNYnb.d.ts → system-86fsXJN_.d.ts}

@@ -4,75 +4,94 @@ interface SpringState {
   readonly velocity: number;
 }
 interface BaseOptions {
+  /**
+   * Decimal places of the resting threshold: a spring rests once its
+   * remaining motion cannot reach half a unit in the last place,
+   * 0.5 × 10⁻ᵖ. Values are never rounded — precision only decides rest.
+   * @default 2
+   */
+  readonly precision?: number | undefined;
+}
+interface WithMass {
   /**
    * Mass of the spring system.
    * @default 1
    */
-  mass?: number | undefined;
+  readonly mass?: number | undefined;
+}
+interface WithoutMass {
   /**
-   * Precision for resting threshold.
-   * @default 2
+   * Mass is derived from the other parameters in this input shape
+   * and cannot be provided.
    */
-  precision?: number | undefined;
+  readonly mass?: undefined;
 }
 interface WithTension {
   /**
    * Spring stiffness coefficient.
    * Must be greater than 0.
    */
-  tension: number;
+  readonly tension: number;
 }
 interface WithDamping {
   /**
    * Viscous damping coefficient.
    * Must be greater than or equal to 0.
    */
-  damping: number;
+  readonly damping: number;
 }
 interface WithDampingRatio {
   /**
    * Ratio of damping to critical damping (0 = undamped, 1 = critically damped).
    * Must be greater than or equal to 0.
    */
-  dampingRatio: number;
+  readonly dampingRatio: number;
 }
 interface WithBounce {
   /**
    * Bounciness of the spring. Converted to dampingRatio as `1 - bounce`.
    * [-1, 1]
    */
-  bounce: number;
+  readonly bounce: number;
 }
 interface WithDuration {
   /**
    * Target settle duration in milliseconds.
    * Must be greater than 0.
    */
-  duration: number;
+  readonly duration: number;
 }
 interface WithDisplacement {
   /**
    * Initial displacement used for duration-based envelope calculation.
    * @default 1
    */
-  displacement?: number | undefined;
+  readonly displacement?: number | undefined;
 }
-interface DirectOptions extends BaseOptions, WithTension, WithDamping {}
-interface TensionRatioOptions extends BaseOptions, WithTension, WithDampingRatio {}
-interface TensionBounceOptions extends BaseOptions, WithTension, WithBounce {}
-interface DampingRatioOptions extends BaseOptions, WithDamping, WithDampingRatio {}
-interface DampingBounceOptions extends BaseOptions, WithDamping, WithBounce {}
-interface TensionDampingRatioOptions extends BaseOptions, WithTension, WithDamping, WithDampingRatio {}
-interface TensionDampingBounceOptions extends BaseOptions, WithTension, WithDamping, WithBounce {}
-interface DurationOptions extends BaseOptions, WithDampingRatio, WithDuration, WithDisplacement {}
-interface BounceDurationOptions extends BaseOptions, WithBounce, WithDuration, WithDisplacement {}
-interface TensionDurationOptions extends BaseOptions, WithTension, WithDampingRatio, WithDuration, WithDisplacement {}
-interface TensionBounceDurationOptions extends BaseOptions, WithTension, WithBounce, WithDuration, WithDisplacement {}
-interface DampingDurationOptions extends BaseOptions, WithDamping, WithDampingRatio, WithDuration, WithDisplacement {}
-interface DampingBounceDurationOptions extends BaseOptions, WithDamping, WithBounce, WithDuration, WithDisplacement {}
-type SpringOptions = DirectOptions | TensionRatioOptions | TensionBounceOptions | DampingRatioOptions | DampingBounceOptions | TensionDampingRatioOptions | TensionDampingBounceOptions | DurationOptions | BounceDurationOptions | TensionDurationOptions | TensionBounceDurationOptions | DampingDurationOptions | DampingBounceDurationOptions;
+interface DirectOptions extends BaseOptions, WithMass, WithTension, WithDamping {}
+interface TensionRatioOptions extends BaseOptions, WithMass, WithTension, WithDampingRatio {}
+interface TensionBounceOptions extends BaseOptions, WithMass, WithTension, WithBounce {}
+interface DampingRatioOptions extends BaseOptions, WithMass, WithDamping, WithDampingRatio {}
+interface DampingBounceOptions extends BaseOptions, WithMass, WithDamping, WithBounce {}
+interface TensionDampingRatioOptions extends BaseOptions, WithoutMass, WithTension, WithDamping, WithDampingRatio {}
+interface TensionDampingBounceOptions extends BaseOptions, WithoutMass, WithTension, WithDamping, WithBounce {}
+interface DurationOptions extends BaseOptions, WithMass, WithDampingRatio, WithDuration, WithDisplacement {}
+interface BounceDurationOptions extends BaseOptions, WithMass, WithBounce, WithDuration, WithDisplacement {}
+interface TensionDurationOptions extends BaseOptions, WithoutMass, WithTension, WithDampingRatio, WithDuration, WithDisplacement {}
+interface TensionBounceDurationOptions extends BaseOptions, WithoutMass, WithTension, WithBounce, WithDuration, WithDisplacement {}
+interface DampingDurationOptions extends BaseOptions, WithoutMass, WithDamping, WithDampingRatio, WithDuration, WithDisplacement {}
+interface DampingBounceDurationOptions extends BaseOptions, WithoutMass, WithDamping, WithBounce, WithDuration, WithDisplacement {}
+type SpringOptionKeys = 'mass' | 'tension' | 'damping' | 'dampingRatio' | 'bounce' | 'duration' | 'displacement' | 'precision';
+/**
+ * Marks every option key foreign to `T` as "absent or undefined", so mixing
+ * properties from different input shapes fails to type-check instead of
+ * silently resolving to an unintended shape at runtime.
+ */
+type Exact<T> = T & { [K in Exclude<SpringOptionKeys, keyof T>]?: undefined; };
+type SpringOptions = Exact<DirectOptions> | Exact<TensionRatioOptions> | Exact<TensionBounceOptions> | Exact<DampingRatioOptions> | Exact<DampingBounceOptions> | Exact<TensionDampingRatioOptions> | Exact<TensionDampingBounceOptions> | Exact<DurationOptions> | Exact<BounceDurationOptions> | Exact<TensionDurationOptions> | Exact<TensionBounceDurationOptions> | Exact<DampingDurationOptions> | Exact<DampingBounceDurationOptions>;
 /**
- * Immutable spring configuration.
+ * Immutable spring configuration. Instances are frozen — to change a spring's
+ * behavior, assign a new config via `spring.config`.
  */
 declare class SpringConfig {
   static readonly default: SpringConfig;
@@ -83,7 +102,7 @@ declare class SpringConfig {
   readonly naturalFrequency: number;
   readonly criticalDamping: number;
   readonly dampingRatio: number;
-  readonly precisionMultiplier: number;
+  /** Resting threshold in value units: half a unit in the last `precision` place. */
   readonly restingMagnitude: number;
   constructor(input: SpringOptions);
   /**
@@ -111,43 +130,43 @@ declare class SpringConfig {
  * Direct physical parameters. You control stiffness and friction exactly;
  * mass defaults to 1.
  */
-declare function defineSpring(input: DirectOptions): SpringConfig;
+declare function defineSpring(input: Exact<DirectOptions>): SpringConfig;
 /**
  * Tension sets the stiffness; dampingRatio controls oscillation character
  * (0 = undamped, 1 = critically damped, >1 = overdamped).
  * Damping is derived as `2 * dampingRatio * sqrt(mass * tension)`.
  */
-declare function defineSpring(input: TensionRatioOptions): SpringConfig;
+declare function defineSpring(input: Exact<TensionRatioOptions>): SpringConfig;
 /**
  * Tension sets the stiffness; bounce controls how oscillatory the spring is,
  * from -1 (overdamped, no oscillation) to 1 (maximum bounce).
  * Damping is derived to match the requested bounciness.
  */
-declare function defineSpring(input: TensionBounceOptions): SpringConfig;
+declare function defineSpring(input: Exact<TensionBounceOptions>): SpringConfig;
 /**
  * Damping is given directly; dampingRatio is used to derive tension
  * as `damping² / (4 * dampingRatio² * mass)`.
  * dampingRatio must be greater than 0.
  */
-declare function defineSpring(input: DampingRatioOptions): SpringConfig;
+declare function defineSpring(input: Exact<DampingRatioOptions>): SpringConfig;
 /**
  * Damping is given directly; bounce controls how oscillatory the spring is.
  * Tension is derived to match the requested bounciness.
  * bounce must be less than 1.
  */
-declare function defineSpring(input: DampingBounceOptions): SpringConfig;
+declare function defineSpring(input: Exact<DampingBounceOptions>): SpringConfig;
 /**
  * All three physical knobs specified — mass is derived
  * as `damping² / (4 * dampingRatio² * tension)`.
  * dampingRatio must be greater than 0.
  */
-declare function defineSpring(input: TensionDampingRatioOptions): SpringConfig;
+declare function defineSpring(input: Exact<TensionDampingRatioOptions>): SpringConfig;
 /**
  * All three physical knobs specified — mass is derived
  * from tension, damping, and the requested bounciness.
  * bounce must be less than 1.
  */
-declare function defineSpring(input: TensionDampingBounceOptions): SpringConfig;
+declare function defineSpring(input: Exact<TensionDampingBounceOptions>): SpringConfig;
 /**
  * Duration-based configuration. The spring is tuned so that its envelope
  * decays to the resting threshold within the given duration.
@@ -155,7 +174,7 @@ declare function defineSpring(input: TensionDampingBounceOptions): SpringConfig;
  * to match your actual animation range for accurate timing.
  * Tension and damping are both derived from dampingRatio and duration.
  */
-declare function defineSpring(input: DurationOptions): SpringConfig;
+declare function defineSpring(input: Exact<DurationOptions>): SpringConfig;
 /**
  * Duration-based configuration. The spring is tuned so that its envelope
  * decays to the resting threshold within the given duration.
@@ -164,14 +183,14 @@ declare function defineSpring(input: DurationOptions): SpringConfig;
  * Bounce controls how oscillatory the motion is while settling.
  * Tension and damping are both derived.
  */
-declare function defineSpring(input: BounceDurationOptions): SpringConfig;
+declare function defineSpring(input: Exact<BounceDurationOptions>): SpringConfig;
 /**
  * Duration-based with a tension constraint. Mass is derived from tension
  * and the computed natural frequency; damping follows from mass and dampingRatio.
  * Duration assumes a displacement of 1 by default — provide `displacement`
  * to match your actual animation range for accurate timing.
  */
-declare function defineSpring(input: TensionDurationOptions): SpringConfig;
+declare function defineSpring(input: Exact<TensionDurationOptions>): SpringConfig;
 /**
  * Duration-based with a tension constraint. Bounce controls how oscillatory
  * the motion is while settling. Mass is derived from tension and the
@@ -179,14 +198,14 @@ declare function defineSpring(input: TensionDurationOptions): SpringConfig;
  * Duration assumes a displacement of 1 by default — provide `displacement`
  * to match your actual animation range for accurate timing.
  */
-declare function defineSpring(input: TensionBounceDurationOptions): SpringConfig;
+declare function defineSpring(input: Exact<TensionBounceDurationOptions>): SpringConfig;
 /**
  * Duration-based with a damping constraint. Mass is derived from damping,
  * dampingRatio, and the computed natural frequency; tension follows from mass.
  * Duration assumes a displacement of 1 by default — provide `displacement`
  * to match your actual animation range for accurate timing.
  */
-declare function defineSpring(input: DampingDurationOptions): SpringConfig;
+declare function defineSpring(input: Exact<DampingDurationOptions>): SpringConfig;
 /**
  * Duration-based with a damping constraint. Bounce controls how oscillatory
  * the motion is while settling. Mass is derived from damping and the
@@ -194,11 +213,21 @@ declare function defineSpring(input: DampingDurationOptions): SpringConfig;
  * Duration assumes a displacement of 1 by default — provide `displacement`
  * to match your actual animation range for accurate timing.
  */
-declare function defineSpring(input: DampingBounceDurationOptions): SpringConfig;
+declare function defineSpring(input: Exact<DampingBounceDurationOptions>): SpringConfig;
+//#endregion
+//#region src/flush-queue.d.ts
+declare class FlushQueue {
+  #private;
+  request(callback: () => void): void;
+  batch(fn: () => void): void;
+  enter(): void;
+  exit(): void;
+}
 //#endregion
 //#region src/motion.d.ts
 declare class Motion {
   #private;
+  _pass: number;
   constructor(config: SpringConfig, position: number, velocity: number);
   get position(): number;
   set position(value: number);
@@ -208,18 +237,25 @@ declare class Motion {
   get isResting(): boolean;
   configure(config: SpringConfig): void;
   tick(dt: number, emit?: boolean): void;
+  finish(): void;
   onUpdate(callback: () => void): () => void;
   onStart(callback: () => void): () => void;
   onStop(callback: () => void): () => void;
+  onDispose(callback: () => void): () => void;
   dispose(): void;
 }
 //#endregion
 //#region src/motion-set.d.ts
 declare class MotionSet {
   #private;
+  reduced: boolean;
+  onWake: (() => void) | null;
+  readonly flushes: FlushQueue;
   constructor(debug?: boolean);
+  get size(): number;
   add(motion: Motion): void;
   remove(motion: Motion): void;
+  finishAll(): void;
   tick(dt: number): void;
 }
 //#endregion
@@ -252,99 +288,99 @@ declare class Spring {
   set config(value: SpringConfig | null);
   get timeRemaining(): number;
   get isResting(): boolean;
+  get settled(): Promise<void>;
   jumpTo(value: number): void;
   dispose(): void;
   onUpdate(callback: () => void): () => void;
   onStart(callback: () => void): () => void;
   onStop(callback: () => void): () => void;
+  onDispose(callback: () => void): () => void;
 }
 //#endregion
-//#region src/vector2.d.ts
-interface Vector2 {
-  x: number;
-  y: number;
-}
-//#endregion
-//#region src/spring2d.d.ts
-interface Spring2DWithOffset {
-  spring: Spring2D;
-  offset?: Vector2 | undefined;
-}
-type Spring2DTarget = Vector2 | Spring2D | Spring2DWithOffset;
-interface DisplacedSpring2DPosition {
-  target?: Spring2DTarget | undefined;
-  value?: Vector2 | undefined;
+//#region src/spring-object.d.ts
+/**
+ * Compile-time validation of a value shape: every channel must be a `number`,
+ * every branch a plain object or array with at least one channel. Used as
+ * `value: T & Shape<T>` so an invalid channel errors on that property rather
+ * than on the whole argument. Purely structural — interfaces satisfy it
+ * without index signatures — and mirrored by the runtime
+ * validation for untyped callers. Optional and `undefined`-typed channels
+ * are rejected: a channel that may be absent would make two springs of the
+ * same declared shape structurally incompatible at runtime.
+ */
+type Shape<T> = 0 extends 1 & T ? T : T extends number ? number : T extends ((...args: never) => unknown) | (abstract new (...args: never) => unknown) ? never : T extends readonly never[] ? never : T extends object ? keyof T extends never ? never : { [K in keyof T]-?: 0 extends 1 & T[K] ? T[K] : undefined extends T[K] ? never : Shape<T[K]>; } : never;
+/**
+ * A partial view of a value shape: the same nesting with any subset of the
+ * numeric channels present. Absent (or `undefined`) channels are left alone.
+ */
+type PartialShape<T> = T extends number ? number : { readonly [K in keyof T]?: PartialShape<T[K]> | undefined; };
+/**
+ * A deep-readonly view of a value shape. Composite reads (`target`, `value`,
+ * `velocity`) return the spring's live mirror objects — refreshed in place
+ * on every read — so their channels are typed read-only.
+ */
+type ReadonlyShape<T> = T extends number ? number : { readonly [K in keyof T]: ReadonlyShape<T[K]>; };
+/**
+ * Configuration for a spring object: a single `SpringConfig` applied to every
+ * channel, or an object mirroring the value shape with configs at any level.
+ * A config at a subtree applies to every channel below it; deeper configs win.
+ * `null` reverts to the default config (or the leader's while following).
+ * Configs are always `SpringConfig` instances (from `defineSpring`), so a
+ * plain object is unambiguously a config shape and any non-config leaf it
+ * reaches is an error.
+ */
+type ConfigShape<T> = SpringConfig | null | (T extends number ? never : { readonly [K in keyof T]?: ConfigShape<T[K]> | undefined; });
+interface SpringObjectWithOffset<T extends object> {
+  readonly spring: SpringObject<T>;
+  readonly offset?: PartialShape<T> | undefined;
 }
-type Spring2DPosition = Vector2 | DisplacedSpring2DPosition;
-declare class Spring2D {
+type SpringObjectTarget<T extends object> = PartialShape<T> | SpringObject<T> | SpringObjectWithOffset<T>;
+declare class SpringObject<in out T extends object> {
   #private;
-  constructor(motions: MotionSet, position: Spring2DPosition, config?: SpringConfig);
-  get target(): Vector2;
-  set target(value: Spring2DTarget);
-  get value(): Readonly<Vector2>;
-  set value(value: Vector2);
-  get velocity(): Readonly<Vector2>;
-  set velocity(value: Vector2);
+  constructor(motions: MotionSet, value: T & Shape<T>, config?: ConfigShape<T>);
+  get target(): ReadonlyShape<T>;
+  set target(value: SpringObjectTarget<T>);
+  get value(): ReadonlyShape<T>;
+  set value(value: PartialShape<T>);
+  get velocity(): ReadonlyShape<T>;
+  set velocity(value: PartialShape<T>);
   get config(): SpringConfig | null;
-  get mass(): number;
-  get tension(): number;
-  get damping(): number;
-  get dampingRatio(): number;
-  get precision(): number;
-  set config(value: SpringConfig | null);
+  set config(value: ConfigShape<T>);
   get timeRemaining(): number;
   get isResting(): boolean;
-  jumpTo(value: Vector2): void;
+  get settled(): Promise<void>;
+  jumpTo(value: PartialShape<T>): void;
   dispose(): void;
   onUpdate(callback: () => void): () => void;
   onStart(callback: () => void): () => void;
   onStop(callback: () => void): () => void;
+  onDispose(callback: () => void): () => void;
 }
 //#endregion
 //#region src/ticker.d.ts
 interface TickerOptions {
-  /**
-   * The target frames per second for the simulation loop
-   *
-   * must be greater than 0, defaults to 60
-   */
-  fps?: number | undefined;
-  /**
-   * The maximum elapsed time (in ms) before a frame is considered a lag spike
-   * (e.g. from a backgrounded tab). When exceeded, `adjustedLag` is used instead
-   * of the real elapsed time. Set to 0 to disable lag detection.
-   *
-   * must be greater than or equal to 0, defaults to 500
-   */
-  lagThreshold?: number | undefined;
-  /**
-   * The substitute elapsed time (in ms) used when a lag spike is detected.
-   * Clamped to be at most `lagThreshold`.
-   *
-   * must be greater than or equal to 0, defaults to 33
-   */
-  adjustedLag?: number | undefined;
+  readonly fps?: number | undefined;
+  readonly lagThreshold?: number | undefined;
+  readonly adjustedLag?: number | undefined;
 }
 //#endregion
 //#region src/system.d.ts
 interface SpringSystemOptions extends TickerOptions {
   debug?: boolean | undefined;
+  reducedMotion?: 'user' | 'always' | 'never' | undefined;
 }
 interface SpringSystem {
   createSpring(position: SpringPosition, config?: SpringConfig): Spring;
-  createSpring2D(position: Spring2DPosition, config?: SpringConfig): Spring2D;
-  /** Advance all springs by `dt` milliseconds, without affecting internal timing. */
+  createSpringObject<T extends object>(value: T & Shape<T>, config?: ConfigShape<T>): SpringObject<T>;
   advance(dt: number): void;
-  /** Start the animation loop. */
   start(): void;
-  /** Stop the animation loop. */
   stop(): void;
-  /** Whether the animation loop is currently running. */
   readonly running: boolean;
+  readonly reducedMotion: boolean;
   fps: number;
   lagThreshold: number;
   adjustedLag: number;
 }
 declare function createSpringSystem(options?: SpringSystemOptions): SpringSystem;
 //#endregion
-export { defineSpring as _, Spring2D as a, Spring2DWithOffset as c, SpringPosition as d, SpringTarget as f, SpringState as g, SpringOptions as h, TickerOptions as i, Vector2 as l, SpringConfig as m, SpringSystemOptions as n, Spring2DPosition as o, SpringWithOffset as p, createSpringSystem as r, Spring2DTarget as s, SpringSystem as t, Spring as u };
+export { SpringOptions as _, ConfigShape as a, Shape as c, SpringObjectWithOffset as d, Spring as f, SpringConfig as g, SpringWithOffset as h, TickerOptions as i, SpringObject as l, SpringTarget as m, SpringSystemOptions as n, PartialShape as o, SpringPosition as p, createSpringSystem as r, ReadonlyShape as s, SpringSystem as t, SpringObjectTarget as u, SpringState as v, defineSpring as y };