@sarmal/core 0.3.0 → 0.4.1

package/dist/index.d.cts

@@ -1,112 +1,155 @@
 interface Point {
-    x: number;
-    y: number;
+  x: number;
+  y: number;
 }
 interface CurveDef {
-    name: string;
-    fn: (t: number, time: 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;
+  name: string;
+  fn: (t: number, time: 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;
 }
+type SeekOptions = {
+  /**
+   * Decides whether the sarmal trail should be cleared when `seek` is called
+   */
+  clearTrail?: boolean;
+};
+type SeekWithTrailOptions = {
+  /**
+   * When true, the trail wraps around the period boundary,
+   *  which results in a full trail even near `t=0`
+   * By default, the trail stops at `t=0`, which results in a partial trail near the start
+   * @default false
+   */
+  wrap?: boolean;
+  /**
+   * Time gap between each trail point (in same units as `t`)
+   * Smaller value means a trail that is more dense
+   * @default period / trailLength
+   */
+  step?: number;
+};
 interface Engine {
-    /**
-     * Advances the Sarmal simulation by the given delta time (dt) in seconds.
-     * Internally, this increases the simulation time `t` by `speed * dt`,
-     *  wraps `t` at `period`, evaluates the curve's parametric function `fn(t)`,
-     *  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;
-    /**
-     * Resets the simulation state, by clearing the trail and reverting internal time `t` to 0.
-     * The next call to `tick` will start fresh from the beginning of the curve.
-     */
-    reset(): void;
-    /**
-     * 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 `t=0` to `t=period`
-     *
-     * The skeleton is always derived from the curve's state at `t=0` using `fn(t, 0)`
-     * This represents the full path the sarmal would trace on its first complete cycle,
-     *  rendered as a static background reference.
-     *
-     * The number of sample points is automatically derived from the curve's period.
-     */
-    getSarmalSkeleton(): Array<Point>;
+  /**
+   * Advances the Sarmal simulation by the given delta time (dt) in seconds.
+   * Internally, this increases the simulation time `t` by `speed * dt`,
+   *  wraps `t` at `period`, evaluates the curve's parametric function `fn(t)`,
+   *  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;
+  /**
+   * Resets the simulation state, by clearing the trail and reverting internal time `t` to 0.
+   * The next call to `tick` will start fresh from the beginning of the curve.
+   */
+  reset(): void;
+  /**
+   * 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 `t=0` to `t=period`
+   *
+   * The skeleton is always derived from the curve's state at `t=0` using `fn(t, 0)`
+   * This represents the full path the sarmal would trace on its first complete cycle,
+   *  rendered as a static background reference.
+   *
+   * The number of sample points is automatically derived from the curve's period.
+   */
+  getSarmalSkeleton(): Array<Point>;
+  /**
+   * Sets the simulation time `t` directly to the specified value.
+   * By default, the trail is preserved
+   * @param t The time value to seek to (will be wrapped into [0, period))
+   */
+  seek(t: number, options?: SeekOptions): void;
+  /**
+   * Seeks to `t` and rebuilds the trail as if the animation naturally arrived there from `t=0`
+   * @param t The time value to seek to (will be wrapped into [0, period))
+   */
+  seekWithTrail(t: number, options?: SeekWithTrailOptions): void;
 }
 interface SarmalInstance {
-    start(): void;
-    stop(): void;
-    /** Resets the engine and clears the trail */
-    reset(): void;
-    /** Stops the animation and cleans up resources */
-    destroy(): void;
+  start(): void;
+  stop(): void;
+  /** Resets the engine and clears the trail */
+  reset(): void;
+  /** Stops the animation and cleans up resources */
+  destroy(): void;
+  /**
+   * Sets the simulation time `t` directly to the specified value.
+   * By default, the trail is preserved
+   * @param t The time value to seek to (will be wrapped into [0, period))
+   */
+  seek(t: number, options?: SeekOptions): void;
+  /**
+   * Seeks to `t` and rebuilds the trail as if the animation naturally arrived there from `t=0`
+   * @param t The time value to seek to (will be wrapped into [0, period))
+   */
+  seekWithTrail(t: number, options?: SeekWithTrailOptions): void;
 }
 interface RendererOptions {
-    /** Target canvas element that will contain the Sarmal */
-    canvas: HTMLCanvasElement;
-    engine: Engine;
-    /**
-     * @default '#ffffff'
-     */
-    skeletonColor?: string;
-    /**
-     * @default '#ffffff'
-     */
-    trailColor?: string;
-    /**
-     * @default '#ffffff'
-     */
-    headColor?: string;
-    /** @default 4 */
-    headRadius?: number;
-    /** @default 20 */
-    glowSize?: number;
+  /** Target canvas element that will contain the Sarmal */
+  canvas: HTMLCanvasElement;
+  engine: Engine;
+  /**
+   * @default '#ffffff'
+   */
+  skeletonColor?: string;
+  /**
+   * @default '#ffffff'
+   */
+  trailColor?: string;
+  /**
+   * @default '#ffffff'
+   */
+  headColor?: string;
+  /** @default 4 */
+  headRadius?: number;
+  /** @default 20 */
+  glowSize?: number;
 }
 interface SarmalOptions extends Omit<RendererOptions, "canvas" | "engine"> {
-    /** @default 120 */
-    trailLength?: number;
+  /** @default 120 */
+  trailLength?: number;
 }
 
 interface SVGRendererOptions {
-    /** Container element that will contain the SVG */
-    container: Element;
-    engine: Engine;
-    /** @default '#ffffff' */
-    skeletonColor?: string;
-    /** @default '#ffffff' */
-    trailColor?: string;
-    /** @default '#ffffff' */
-    headColor?: string;
-    /** @default 4 */
-    headRadius?: number;
-    /** @default 20 */
-    glowSize?: number;
-    /** @default 'Loading' */
-    ariaLabel?: string;
+  /** Container element that will contain the SVG */
+  container: Element;
+  engine: Engine;
+  /** @default '#ffffff' */
+  skeletonColor?: string;
+  /** @default '#ffffff' */
+  trailColor?: string;
+  /** @default '#ffffff' */
+  headColor?: string;
+  /** @default 4 */
+  headRadius?: number;
+  /** @default 20 */
+  glowSize?: number;
+  /** @default 'Loading' */
+  ariaLabel?: string;
 }
 interface SVGSarmalOptions extends Omit<SVGRendererOptions, "container" | "engine"> {
-    /** @default 120 */
-    trailLength?: number;
+  /** @default 120 */
+  trailLength?: number;
 }
 /**
  * Creates a live SVG renderer for sarmal animations
@@ -124,7 +167,11 @@ declare function createSVGRenderer(options: SVGRendererOptions): SarmalInstance;
  * sarmal.start()
  * ```
  */
-declare function createSarmalSVG(container: Element, curveDef: CurveDef, options?: SVGSarmalOptions): SarmalInstance;
+declare function createSarmalSVG(
+  container: Element,
+  curveDef: CurveDef,
+  options?: SVGSarmalOptions,
+): SarmalInstance;
 
 /**
  * Creates the core simulation engine for a sarmal
@@ -158,6 +205,27 @@ declare const curves: Record<string, CurveDef>;
  * sarmal.start()
  * ```
  */
-declare function createSarmal(canvas: HTMLCanvasElement, curveDef: CurveDef, options?: SarmalOptions): SarmalInstance;
+declare function createSarmal(
+  canvas: HTMLCanvasElement,
+  curveDef: CurveDef,
+  options?: SarmalOptions,
+): SarmalInstance;
 
-export { type CurveDef, type Engine, type Point, type RendererOptions, type SVGRendererOptions, type SVGSarmalOptions, type SarmalInstance, type SarmalOptions, createEngine, createRenderer, createSVGRenderer, createSarmal, createSarmalSVG, curves };
+export {
+  type CurveDef,
+  type Engine,
+  type Point,
+  type RendererOptions,
+  type SVGRendererOptions,
+  type SVGSarmalOptions,
+  type SarmalInstance,
+  type SarmalOptions,
+  type SeekOptions,
+  type SeekWithTrailOptions,
+  createEngine,
+  createRenderer,
+  createSVGRenderer,
+  createSarmal,
+  createSarmalSVG,
+  curves,
+};

package/dist/index.d.ts

@@ -1,112 +1,155 @@
 interface Point {
-    x: number;
-    y: number;
+  x: number;
+  y: number;
 }
 interface CurveDef {
-    name: string;
-    fn: (t: number, time: 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;
+  name: string;
+  fn: (t: number, time: 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;
 }
+type SeekOptions = {
+  /**
+   * Decides whether the sarmal trail should be cleared when `seek` is called
+   */
+  clearTrail?: boolean;
+};
+type SeekWithTrailOptions = {
+  /**
+   * When true, the trail wraps around the period boundary,
+   *  which results in a full trail even near `t=0`
+   * By default, the trail stops at `t=0`, which results in a partial trail near the start
+   * @default false
+   */
+  wrap?: boolean;
+  /**
+   * Time gap between each trail point (in same units as `t`)
+   * Smaller value means a trail that is more dense
+   * @default period / trailLength
+   */
+  step?: number;
+};
 interface Engine {
-    /**
-     * Advances the Sarmal simulation by the given delta time (dt) in seconds.
-     * Internally, this increases the simulation time `t` by `speed * dt`,
-     *  wraps `t` at `period`, evaluates the curve's parametric function `fn(t)`,
-     *  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;
-    /**
-     * Resets the simulation state, by clearing the trail and reverting internal time `t` to 0.
-     * The next call to `tick` will start fresh from the beginning of the curve.
-     */
-    reset(): void;
-    /**
-     * 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 `t=0` to `t=period`
-     *
-     * The skeleton is always derived from the curve's state at `t=0` using `fn(t, 0)`
-     * This represents the full path the sarmal would trace on its first complete cycle,
-     *  rendered as a static background reference.
-     *
-     * The number of sample points is automatically derived from the curve's period.
-     */
-    getSarmalSkeleton(): Array<Point>;
+  /**
+   * Advances the Sarmal simulation by the given delta time (dt) in seconds.
+   * Internally, this increases the simulation time `t` by `speed * dt`,
+   *  wraps `t` at `period`, evaluates the curve's parametric function `fn(t)`,
+   *  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;
+  /**
+   * Resets the simulation state, by clearing the trail and reverting internal time `t` to 0.
+   * The next call to `tick` will start fresh from the beginning of the curve.
+   */
+  reset(): void;
+  /**
+   * 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 `t=0` to `t=period`
+   *
+   * The skeleton is always derived from the curve's state at `t=0` using `fn(t, 0)`
+   * This represents the full path the sarmal would trace on its first complete cycle,
+   *  rendered as a static background reference.
+   *
+   * The number of sample points is automatically derived from the curve's period.
+   */
+  getSarmalSkeleton(): Array<Point>;
+  /**
+   * Sets the simulation time `t` directly to the specified value.
+   * By default, the trail is preserved
+   * @param t The time value to seek to (will be wrapped into [0, period))
+   */
+  seek(t: number, options?: SeekOptions): void;
+  /**
+   * Seeks to `t` and rebuilds the trail as if the animation naturally arrived there from `t=0`
+   * @param t The time value to seek to (will be wrapped into [0, period))
+   */
+  seekWithTrail(t: number, options?: SeekWithTrailOptions): void;
 }
 interface SarmalInstance {
-    start(): void;
-    stop(): void;
-    /** Resets the engine and clears the trail */
-    reset(): void;
-    /** Stops the animation and cleans up resources */
-    destroy(): void;
+  start(): void;
+  stop(): void;
+  /** Resets the engine and clears the trail */
+  reset(): void;
+  /** Stops the animation and cleans up resources */
+  destroy(): void;
+  /**
+   * Sets the simulation time `t` directly to the specified value.
+   * By default, the trail is preserved
+   * @param t The time value to seek to (will be wrapped into [0, period))
+   */
+  seek(t: number, options?: SeekOptions): void;
+  /**
+   * Seeks to `t` and rebuilds the trail as if the animation naturally arrived there from `t=0`
+   * @param t The time value to seek to (will be wrapped into [0, period))
+   */
+  seekWithTrail(t: number, options?: SeekWithTrailOptions): void;
 }
 interface RendererOptions {
-    /** Target canvas element that will contain the Sarmal */
-    canvas: HTMLCanvasElement;
-    engine: Engine;
-    /**
-     * @default '#ffffff'
-     */
-    skeletonColor?: string;
-    /**
-     * @default '#ffffff'
-     */
-    trailColor?: string;
-    /**
-     * @default '#ffffff'
-     */
-    headColor?: string;
-    /** @default 4 */
-    headRadius?: number;
-    /** @default 20 */
-    glowSize?: number;
+  /** Target canvas element that will contain the Sarmal */
+  canvas: HTMLCanvasElement;
+  engine: Engine;
+  /**
+   * @default '#ffffff'
+   */
+  skeletonColor?: string;
+  /**
+   * @default '#ffffff'
+   */
+  trailColor?: string;
+  /**
+   * @default '#ffffff'
+   */
+  headColor?: string;
+  /** @default 4 */
+  headRadius?: number;
+  /** @default 20 */
+  glowSize?: number;
 }
 interface SarmalOptions extends Omit<RendererOptions, "canvas" | "engine"> {
-    /** @default 120 */
-    trailLength?: number;
+  /** @default 120 */
+  trailLength?: number;
 }
 
 interface SVGRendererOptions {
-    /** Container element that will contain the SVG */
-    container: Element;
-    engine: Engine;
-    /** @default '#ffffff' */
-    skeletonColor?: string;
-    /** @default '#ffffff' */
-    trailColor?: string;
-    /** @default '#ffffff' */
-    headColor?: string;
-    /** @default 4 */
-    headRadius?: number;
-    /** @default 20 */
-    glowSize?: number;
-    /** @default 'Loading' */
-    ariaLabel?: string;
+  /** Container element that will contain the SVG */
+  container: Element;
+  engine: Engine;
+  /** @default '#ffffff' */
+  skeletonColor?: string;
+  /** @default '#ffffff' */
+  trailColor?: string;
+  /** @default '#ffffff' */
+  headColor?: string;
+  /** @default 4 */
+  headRadius?: number;
+  /** @default 20 */
+  glowSize?: number;
+  /** @default 'Loading' */
+  ariaLabel?: string;
 }
 interface SVGSarmalOptions extends Omit<SVGRendererOptions, "container" | "engine"> {
-    /** @default 120 */
-    trailLength?: number;
+  /** @default 120 */
+  trailLength?: number;
 }
 /**
  * Creates a live SVG renderer for sarmal animations
@@ -124,7 +167,11 @@ declare function createSVGRenderer(options: SVGRendererOptions): SarmalInstance;
  * sarmal.start()
  * ```
  */
-declare function createSarmalSVG(container: Element, curveDef: CurveDef, options?: SVGSarmalOptions): SarmalInstance;
+declare function createSarmalSVG(
+  container: Element,
+  curveDef: CurveDef,
+  options?: SVGSarmalOptions,
+): SarmalInstance;
 
 /**
  * Creates the core simulation engine for a sarmal
@@ -158,6 +205,27 @@ declare const curves: Record<string, CurveDef>;
  * sarmal.start()
  * ```
  */
-declare function createSarmal(canvas: HTMLCanvasElement, curveDef: CurveDef, options?: SarmalOptions): SarmalInstance;
+declare function createSarmal(
+  canvas: HTMLCanvasElement,
+  curveDef: CurveDef,
+  options?: SarmalOptions,
+): SarmalInstance;
 
-export { type CurveDef, type Engine, type Point, type RendererOptions, type SVGRendererOptions, type SVGSarmalOptions, type SarmalInstance, type SarmalOptions, createEngine, createRenderer, createSVGRenderer, createSarmal, createSarmalSVG, curves };
+export {
+  type CurveDef,
+  type Engine,
+  type Point,
+  type RendererOptions,
+  type SVGRendererOptions,
+  type SVGSarmalOptions,
+  type SarmalInstance,
+  type SarmalOptions,
+  type SeekOptions,
+  type SeekWithTrailOptions,
+  createEngine,
+  createRenderer,
+  createSVGRenderer,
+  createSarmal,
+  createSarmalSVG,
+  curves,
+};