@sarmal/core 0.27.0 → 0.28.1

package/dist/types-zbxUgcmZ.d.cts

@@ -1,6 +1,6 @@
 interface Point {
-  x: number;
-  y: number;
+    x: number;
+    y: number;
 }
 /**
  * A control point for drawn curves, represented as a
@@ -9,64 +9,64 @@ interface Point {
  */
 type ControlPoint = [number, number];
 interface CurveDef {
-  name: string;
-  /**
-   * The parametric function that defines the curve shape.
-   * @param phase Current position along the curve, in [0, period)
-   * @param elapsed Elapsed actual time in seconds. It is always increasing, and never resets on period wrap
-   * @param params Named parameter overrides. intentional forward-compatible parameter
-   */
-  fn: (phase: number, elapsed: number, params: Record<string, number>) => Point;
-  /**
-   * @default (Math.PI * 2)
-   */
-  period?: number;
-  /**
-   * @default 1
-   */
-  speed?: number;
-  /**
-   * To indicate a compatible library version when providing the curve definitions
-   * Intended for potential backwards compatibility scenarios and futureproofing
-   */
-  version?: number;
-  /**
-   * Skeleton rendering mode:
-   * - 'static': Skeleton is computed once at init from `fn(phase, 0)` and cached
-   * - 'live': Skeleton is recomputed each frame using `fn(phase, actualTime)` specifically for curves whose shape drifts *over time*
-   * @default "static"
-   */
-  skeleton?: "static" | "live";
-  /**
-   * An **override** function for computing a skeleton independent of `fn`
-   * If provided, this function is used instead of `fn` to sample the skeleton,
-   *  and the result is cached just like like 'static' mode
-   * @param phase The parametric position along the curve (0 to period)
-   * @returns The point on the skeleton at position `phase`
-   */
-  skeletonFn?: (phase: number) => Point;
+    name: string;
+    /**
+     * The parametric function that defines the curve shape.
+     * @param phase Current position along the curve, in [0, period)
+     * @param elapsed Elapsed actual time in seconds. It is always increasing, and never resets on period wrap
+     * @param params Named parameter overrides. intentional forward-compatible parameter
+     */
+    fn: (phase: number, elapsed: number, params: Record<string, number>) => Point;
+    /**
+     * @default (Math.PI * 2)
+     */
+    period?: number;
+    /**
+     * @default 1
+     */
+    speed?: number;
+    /**
+     * To indicate a compatible library version when providing the curve definitions
+     * Intended for potential backwards compatibility scenarios and futureproofing
+     */
+    version?: number;
+    /**
+     * Skeleton rendering mode:
+     * - 'static': Skeleton is computed once at init from `fn(phase, 0)` and cached
+     * - 'live': Skeleton is recomputed each frame using `fn(phase, actualTime)` specifically for curves whose shape drifts *over time*
+     * @default "static"
+     */
+    skeleton?: "static" | "live";
+    /**
+     * An **override** function for computing a skeleton independent of `fn`
+     * If provided, this function is used instead of `fn` to sample the skeleton,
+     *  and the result is cached just like like 'static' mode
+     * @param phase The parametric position along the curve (0 to period)
+     * @returns The point on the skeleton at position `phase`
+     */
+    skeletonFn?: (phase: number) => Point;
 }
 type JumpOptions = {
-  /**
-   * When true, clears the trail on jump. When false (default), the trail is left as-is.
-   * @default false
-   */
-  clearTrail?: boolean;
+    /**
+     * When true, clears the trail on jump. When false (default), the trail is left as-is.
+     * @default false
+     */
+    clearTrail?: boolean;
 };
 type SeekOptions = {
-  /**
-   * When true, the trail wraps around the period boundary,
-   *  which results in a full trail even near `phase=0`
-   * By default, the trail stops at `phase=0`, which results in a partial trail near the start
-   * @default false
-   */
-  wrap?: boolean;
-  /**
-   * Time gap between each trail point (in same units as `phase`)
-   * Smaller value means a trail that is more dense
-   * @default period / trailLength
-   */
-  step?: number;
+    /**
+     * When true, the trail wraps around the period boundary,
+     *  which results in a full trail even near `phase=0`
+     * By default, the trail stops at `phase=0`, which results in a partial trail near the start
+     * @default false
+     */
+    wrap?: boolean;
+    /**
+     * Time gap between each trail point (in same units as `phase`)
+     * Smaller value means a trail that is more dense
+     * @default period / trailLength
+     */
+    step?: number;
 };
 type MorpStrategy = "raw" | "normalized";
 /**
@@ -75,169 +75,169 @@ type MorpStrategy = "raw" | "normalized";
  * In the renderer, these are passthroughs
  */
 interface AnimationControls {
-  /**
-   * Resets the simulation state, clearing the trail and reverting internal `phase` to 0
-   * The next call to `tick` will start fresh from the beginning of the curve
-   */
-  reset(): void;
-  /**
-   * Instantly moves the head to position `phase`.
-   *
-   * ! Does NOT update `actualTime`.
-   *
-   * Trail is left untouched by default. You can pass `clearTrail: true` to wipe it.
-   * Use for morphing mid-flight or any time you don't need trail context.
-   * @param phase The position to jump to (will be wrapped into [0, period))
-   */
-  jump(phase: number, options?: JumpOptions): void;
-  /**
-   * Moves to `phase` AND reconstructs the trail as if the animation naturally arrived there from `phase=0`
-   * Also updates `actualTime` to match. Trail is always rebuilt from scratch
-   * Use for initialisation or any jump where you want the trail to look meaningful
-   * @param phase The position to seek to (will be wrapped into [0, period))
-   */
-  seek(phase: number, options?: SeekOptions): void;
-  /**
-   * Overrides the animation speed at runtime
-   * `0` freezes `phase` but the loop keeps running
-   * Negative values reverse traversal.
-   *
-   * ! Does NOT affect a curve's inherent speed given in CurveDef
-   * @param speed 0 = freeze, negative = reverse, no upper bound
-   */
-  setSpeed(speed: number): void;
-  /**
-   * Returns the *effective speed* the engine is currently using:
-   * `userSpeedOverride` if set, otherwise the curve's default speed.
-   * This is what `tick()` actually uses
-   */
-  getSpeed(): number;
-  /**
-   * Drops the speed override and defers back to the curve's inherent default speed.
-   * ! Sets `userSpeedOverride` to `null`
-   */
-  resetSpeed(): void;
-  /**
-   * Transitions to the target speed over `duration` milliseconds using linear interpolation.
-   * Resolves when the transition completes.
-   *
-   * Calling this while a transition is already in progress cancels the old transition
-   * (rejecting its Promise) and starts a new one from the current interpolated speed.
-   *
-   * @param speed Target speed
-   * @param duration Transition duration in milliseconds (must be > 0)
-   */
-  setSpeedOver(speed: number, duration: number): Promise<void>;
+    /**
+     * Resets the simulation state, clearing the trail and reverting internal `phase` to 0
+     * The next call to `tick` will start fresh from the beginning of the curve
+     */
+    reset(): void;
+    /**
+     * Instantly moves the head to position `phase`.
+     *
+     * ! Does NOT update `actualTime`.
+     *
+     * Trail is left untouched by default. You can pass `clearTrail: true` to wipe it.
+     * Use for morphing mid-flight or any time you don't need trail context.
+     * @param phase The position to jump to (will be wrapped into [0, period))
+     */
+    jump(phase: number, options?: JumpOptions): void;
+    /**
+     * Moves to `phase` AND reconstructs the trail as if the animation naturally arrived there from `phase=0`
+     * Also updates `actualTime` to match. Trail is always rebuilt from scratch
+     * Use for initialisation or any jump where you want the trail to look meaningful
+     * @param phase The position to seek to (will be wrapped into [0, period))
+     */
+    seek(phase: number, options?: SeekOptions): void;
+    /**
+     * Overrides the animation speed at runtime
+     * `0` freezes `phase` but the loop keeps running
+     * Negative values reverse traversal.
+     *
+     * ! Does NOT affect a curve's inherent speed given in CurveDef
+     * @param speed 0 = freeze, negative = reverse, no upper bound
+     */
+    setSpeed(speed: number): void;
+    /**
+     * Returns the *effective speed* the engine is currently using:
+     * `userSpeedOverride` if set, otherwise the curve's default speed.
+     * This is what `tick()` actually uses
+     */
+    getSpeed(): number;
+    /**
+     * Drops the speed override and defers back to the curve's inherent default speed.
+     * ! Sets `userSpeedOverride` to `null`
+     */
+    resetSpeed(): void;
+    /**
+     * Transitions to the target speed over `duration` milliseconds using linear interpolation.
+     * Resolves when the transition completes.
+     *
+     * Calling this while a transition is already in progress cancels the old transition
+     * (rejecting its Promise) and starts a new one from the current interpolated speed.
+     *
+     * @param speed Target speed
+     * @param duration Transition duration in milliseconds (must be > 0)
+     */
+    setSpeedOver(speed: number, duration: number): Promise<void>;
 }
 type MorphOptions = {
-  /**
-   * Duration of the morph transition in milliseconds
-   * @default 300
-   */
-  duration?: number;
-  /**
-   * Strategy for lerping between curves with different periods:
-   * - 'normalized': maps `phase` proportionally into each curve's period (smooth for all period ratios)
-   * - 'raw': uses the same `phase` for both curves (can produce incoherent results for mismatched periods)
-   * @default 'normalized'
-   */
-  morphStrategy?: MorpStrategy;
+    /**
+     * Duration of the morph transition in milliseconds
+     * @default 300
+     */
+    duration?: number;
+    /**
+     * Strategy for lerping between curves with different periods:
+     * - 'normalized': maps `phase` proportionally into each curve's period (smooth for all period ratios)
+     * - 'raw': uses the same `phase` for both curves (can produce incoherent results for mismatched periods)
+     * @default 'normalized'
+     */
+    morphStrategy?: MorpStrategy;
 };
 interface Engine extends AnimationControls {
-  /**
-   * Advances the Sarmal simulation by the given delta time (dt) in seconds.
-   * Internally, this increases the simulation `phase` by `speed * dt`,
-   *  wraps `phase` at `period`, evaluates the curve's parametric function `fn(phase)`,
-   *  and appends the new point to the trail.
-   * Returns the pre-allocated trail buffer, which has the *same* reference every call
-   * ! Do not use `Array.length` to determine size
-   * @param deltaTime Delta time in seconds (typically frame time from **requestAnimationFrame** or similar)
-   */
-  tick(deltaTime: number): Array<Point>;
-  /**
-   * Number of valid points in the trail buffer returned by the last `tick()` call
-   * ! Use this instead of `trail.length`
-   */
-  readonly trailCount: number;
-  /**
-   * The maximum capacity of the trail buffer, which is set at engine creation
-   * This is the upper bound for `trailCount`
-   */
-  readonly trailLength: number;
-  /**
-   * Returns the *skeleton* of the curve.
-   * In technicality, it just represents the complete traversal of the curve over one full period,
-   *  which is sampled at points from `phase=0` to `phase=period`
-   *
-   * For "static" skeletons, this returns the same array on every call
-   * For "live" skeletons, this returns a different array each frame
-   * For `skeletonFn` overrides, this returns the skeleton from that function, which is *always* static
-   *
-   * The number of sample points is automatically derived from the curve's period.
-   */
-  getSarmalSkeleton(): Array<Point>;
-  readonly isLiveSkeleton: boolean;
-  /**
-   * Begins a smooth transition from the current curve to `target`
-   * Saves the current curve as `curveA`, registers `target` as `curveB`, and resets `morphAlpha` to `0`
-   *
-   * If called while a morph is already in progress,
-   *  the interpolated state is frozen and becomes the new `curveA`
-   * @param target The curve to transition to
-   * @param strategy 'normalized' maps phase proportionally into each curve's period (default), 'raw' uses the same phase
-   */
-  startMorph(target: CurveDef, strategy?: MorpStrategy): void;
-  /**
-   * Sets the interpolation amount between `curveA` and `curveB`.
-   * 0 = full curveA
-   * 1 = full curveB
-   * Called by the renderer each frame as `actualTime` advances
-   * @param alpha A value in [0, 1]
-   */
-  setMorphAlpha(alpha: number): void;
-  /**
-   * Finalises the morph: `curveB` becomes the new active curve and `morphAlpha` is reset to `null`
-   * ! Called by the renderer when alpha reaches `1`
-   */
-  completeMorph(): void;
-  /**
-   * Current interpolation progress between `curveA` and `curveB`
-   * `null` when no morph is in progress
-   */
-  readonly morphAlpha: number | null;
-  /**
-   * Cancels any in-progress speed transition initiated by `setSpeedOver()`.
-   * Called internally by the renderer's `stop()` method.
-   */
-  cancelSpeedTransition(): void;
+    /**
+     * Advances the Sarmal simulation by the given delta time (dt) in seconds.
+     * Internally, this increases the simulation `phase` by `speed * dt`,
+     *  wraps `phase` at `period`, evaluates the curve's parametric function `fn(phase)`,
+     *  and appends the new point to the trail.
+     * Returns the pre-allocated trail buffer, which has the *same* reference every call
+     * ! Do not use `Array.length` to determine size
+     * @param deltaTime Delta time in seconds (typically frame time from **requestAnimationFrame** or similar)
+     */
+    tick(deltaTime: number): Array<Point>;
+    /**
+     * Number of valid points in the trail buffer returned by the last `tick()` call
+     * ! Use this instead of `trail.length`
+     */
+    readonly trailCount: number;
+    /**
+     * The maximum capacity of the trail buffer, which is set at engine creation
+     * This is the upper bound for `trailCount`
+     */
+    readonly trailLength: number;
+    /**
+     * Returns the *skeleton* of the curve.
+     * In technicality, it just represents the complete traversal of the curve over one full period,
+     *  which is sampled at points from `phase=0` to `phase=period`
+     *
+     * For "static" skeletons, this returns the same array on every call
+     * For "live" skeletons, this returns a different array each frame
+     * For `skeletonFn` overrides, this returns the skeleton from that function, which is *always* static
+     *
+     * The number of sample points is automatically derived from the curve's period.
+     */
+    getSarmalSkeleton(): Array<Point>;
+    readonly isLiveSkeleton: boolean;
+    /**
+     * Begins a smooth transition from the current curve to `target`
+     * Saves the current curve as `curveA`, registers `target` as `curveB`, and resets `morphAlpha` to `0`
+     *
+     * If called while a morph is already in progress,
+     *  the interpolated state is frozen and becomes the new `curveA`
+     * @param target The curve to transition to
+     * @param strategy 'normalized' maps phase proportionally into each curve's period (default), 'raw' uses the same phase
+     */
+    startMorph(target: CurveDef, strategy?: MorpStrategy): void;
+    /**
+     * Sets the interpolation amount between `curveA` and `curveB`.
+     * 0 = full curveA
+     * 1 = full curveB
+     * Called by the renderer each frame as `actualTime` advances
+     * @param alpha A value in [0, 1]
+     */
+    setMorphAlpha(alpha: number): void;
+    /**
+     * Finalises the morph: `curveB` becomes the new active curve and `morphAlpha` is reset to `null`
+     * ! Called by the renderer when alpha reaches `1`
+     */
+    completeMorph(): void;
+    /**
+     * Current interpolation progress between `curveA` and `curveB`
+     * `null` when no morph is in progress
+     */
+    readonly morphAlpha: number | null;
+    /**
+     * Cancels any in-progress speed transition initiated by `setSpeedOver()`.
+     * Called internally by the renderer's `stop()` method.
+     */
+    cancelSpeedTransition(): void;
 }
 interface SarmalInstance extends AnimationControls {
-  /** Starts the animation loop (requestAnimationFrame). If already running, does nothing. */
-  play(): void;
-  /** Pauses the animation loop (cancelAnimationFrame) and cancels any speed transition. Preserves state. */
-  pause(): void;
-  /** Stops the animation and cleans up resources */
-  destroy(): void;
-  /**
-   * Returns the skeleton of the curve:
-   * The complete traversal over one full period, sampled at points from phase=0 to phase=period.
-   */
-  getSarmalSkeleton(): Array<Point>;
-  /**
-   * Smoothly transitions from the current curve to `target`.
-   * The trail naturally reflects the new curve as new points are added.
-   * @param target The curve to transition to
-   * @param options.duration How long the morph takes in milliseconds (default: 300)
-   * @param options.morphStrategy 'normalized' uses proportional phase mapping (default), 'raw' uses same phase
-   * @returns Promise that resolves when the morph is complete
-   */
-  morphTo(target: CurveDef, options?: MorphOptions): Promise<void>;
-  /**
-   * Changes render options on a live SarmalInstance without destroying and recreating it.
-   *
-   * ! Validation fails the operation completely if any of the fields fail the chceck.
-   */
-  setRenderOptions(partial: RuntimeRenderOptions): void;
+    /** Starts the animation loop (requestAnimationFrame). If already running, does nothing. */
+    play(): void;
+    /** Pauses the animation loop (cancelAnimationFrame) and cancels any speed transition. Preserves state. */
+    pause(): void;
+    /** Stops the animation and cleans up resources */
+    destroy(): void;
+    /**
+     * Returns the skeleton of the curve:
+     * The complete traversal over one full period, sampled at points from phase=0 to phase=period.
+     */
+    getSarmalSkeleton(): Array<Point>;
+    /**
+     * Smoothly transitions from the current curve to `target`.
+     * The trail naturally reflects the new curve as new points are added.
+     * @param target The curve to transition to
+     * @param options.duration How long the morph takes in milliseconds (default: 300)
+     * @param options.morphStrategy 'normalized' uses proportional phase mapping (default), 'raw' uses same phase
+     * @returns Promise that resolves when the morph is complete
+     */
+    morphTo(target: CurveDef, options?: MorphOptions): Promise<void>;
+    /**
+     * Changes render options on a live SarmalInstance without destroying and recreating it.
+     *
+     * ! Validation fails the operation completely if any of the fields fail the chceck.
+     */
+    setRenderOptions(partial: RuntimeRenderOptions): void;
 }
 /**
  * With 'gradient-animated' the colors cycle along the trail over time
@@ -258,82 +258,68 @@ type TrailColor = string | string[];
  * Passing `"transparent"` for `skeletonColor` hides the skeleton. Any other value must be a valid {@link TrailColor}.
  */
 interface RuntimeRenderOptions {
-  trailColor?: TrailColor;
-  /** 6-digit hex string to override, or `null` to make it automatic */
-  headColor?: string | null;
-  /** 6-digit hex string, or `"transparent"` to hide the skeleton. */
-  skeletonColor?: string;
-  trailStyle?: TrailStyle;
-  /** Radius of the head dot.
-   * - Canvas: CSS pixels. Auto-derived from container size if omitted.
-   * - SVG: viewBox units (0–100 space). Default: `0.5`. */
-  headRadius?: number;
+    trailColor?: TrailColor;
+    /** 6-digit hex string to override, or `null` to make it automatic */
+    headColor?: string | null;
+    /** 6-digit hex string, or `"transparent"` to hide the skeleton. */
+    skeletonColor?: string;
+    trailStyle?: TrailStyle;
+    /** Radius of the head dot.
+     * - Canvas: CSS pixels. Auto-derived from container size if omitted.
+     * - SVG: viewBox units (0–100 space). Default: `0.5`. */
+    headRadius?: number;
 }
 /**
  * Common renderer options shared between canvas and SVG renderers.
  * Extracted to avoid duplication and ensure consistency.
  */
 interface BaseRendererOptions {
-  /**
-   * Whether to start the animation loop automatically on creation.
-   * @default true
-   */
-  autoStart?: boolean;
-  /**
-   * Whether to automatically pause the animation when the browser tab is hidden
-   *  and resume it when the tab becomes visible again.
-   * @default true
-   */
-  pauseOnHidden?: boolean;
-  /**
-   * Initial position along the curve (phase value). If provided, seek(initialPhase) is called before the first frame.
-   * @default undefined (no seek performed, starts at phase=0)
-   */
-  initialPhase?: number;
-  /**
-   * @default '#ffffff'
-   */
-  skeletonColor?: string;
-  /**
-   * Single hex color for default trails, or an array of hex colors for gradient trails.
-   * @default '#ffffff'
-   */
-  trailColor?: TrailColor;
-  /**
-   * Hex color for the head dot.
-   * If omitted, the color is derived from the trail
-   */
-  headColor?: string;
-  /** @default 4 */
-  headRadius?: number;
-  /**
-   * Trail rendering style
-   * @default 'default'
-   */
-  trailStyle?: TrailStyle;
+    /**
+     * Whether to start the animation loop automatically on creation.
+     * @default true
+     */
+    autoStart?: boolean;
+    /**
+     * Whether to automatically pause the animation when the browser tab is hidden
+     *  and resume it when the tab becomes visible again.
+     * @default true
+     */
+    pauseOnHidden?: boolean;
+    /**
+     * Initial position along the curve (phase value). If provided, seek(initialPhase) is called before the first frame.
+     * @default undefined (no seek performed, starts at phase=0)
+     */
+    initialPhase?: number;
+    /**
+     * @default '#ffffff'
+     */
+    skeletonColor?: string;
+    /**
+     * Single hex color for default trails, or an array of hex colors for gradient trails.
+     * @default '#ffffff'
+     */
+    trailColor?: TrailColor;
+    /**
+     * Hex color for the head dot.
+     * If omitted, the color is derived from the trail
+     */
+    headColor?: string;
+    /** @default 4 */
+    headRadius?: number;
+    /**
+     * Trail rendering style
+     * @default 'default'
+     */
+    trailStyle?: TrailStyle;
 }
 interface RendererOptions extends BaseRendererOptions {
-  /** Target canvas element that will contain the Sarmal */
-  canvas: HTMLCanvasElement;
-  engine: Engine;
+    /** Target canvas element that will contain the Sarmal */
+    canvas: HTMLCanvasElement;
+    engine: Engine;
 }
 interface SarmalOptions extends Omit<RendererOptions, "canvas" | "engine"> {
-  /** @default 120 */
-  trailLength?: number;
+    /** @default 120 */
+    trailLength?: number;
 }
 
-export type {
-  BaseRendererOptions as B,
-  CurveDef as C,
-  Engine as E,
-  JumpOptions as J,
-  Point as P,
-  RendererOptions as R,
-  SarmalInstance as S,
-  TrailColor as T,
-  ControlPoint as a,
-  SarmalOptions as b,
-  RuntimeRenderOptions as c,
-  SeekOptions as d,
-  TrailStyle as e,
-};
+export type { BaseRendererOptions as B, CurveDef as C, Engine as E, JumpOptions as J, Point as P, RendererOptions as R, SarmalInstance as S, TrailColor as T, ControlPoint as a, SarmalOptions as b, RuntimeRenderOptions as c, SeekOptions as d, TrailStyle as e };