@sarmal/core 0.9.10 → 0.12.0

package/dist/{types-cR2xOewv.d.ts → types-BzgdhxE0.d.ts}

@@ -42,13 +42,14 @@ interface CurveDef {
      */
     skeletonFn?: (t: number) => Point;
 }
-type SeekOptions = {
+type JumpOptions = {
     /**
-     * Decides whether the sarmal trail should be cleared when `seek` is called
+     * When true, clears the trail on jump. When false (default), the trail is left as-is.
+     * @default false
      */
     clearTrail?: boolean;
 };
-type SeekWithTrailOptions = {
+type SeekOptions = {
     /**
      * When true, the trail wraps around the period boundary,
      *  which results in a full trail even near `t=0`
@@ -64,6 +65,66 @@ type SeekWithTrailOptions = {
     step?: number;
 };
 type MorpStrategy = "raw" | "normalized";
+/**
+ * The shared animation state types
+ * Both `Engine` and `SarmalInstance` extend this
+ * In the renderer, these are passthroughs
+ */
+interface AnimationControls {
+    /**
+     * Resets the simulation state, 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;
+    /**
+     * Instantly moves the head to position `t`.
+     *
+     * ! 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 t The position to jump to (will be wrapped into [0, period))
+     */
+    jump(t: number, options?: JumpOptions): void;
+    /**
+     * Moves to `t` AND reconstructs the trail as if the animation naturally arrived there from `t=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 t The position to seek to (will be wrapped into [0, period))
+     */
+    seek(t: number, options?: SeekOptions): void;
+    /**
+     * Overrides the animation speed at runtime
+     * `0` freezes `t` 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
@@ -78,7 +139,7 @@ type MorphOptions = {
      */
     morphStrategy?: MorpStrategy;
 };
-interface Engine {
+interface Engine extends AnimationControls {
     /**
      * Advances the Sarmal simulation by the given delta time (dt) in seconds.
      * Internally, this increases the simulation time `t` by `speed * dt`,
@@ -94,11 +155,6 @@ interface Engine {
      * ! 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,
@@ -112,17 +168,6 @@ interface Engine {
      */
     getSarmalSkeleton(): Array<Point>;
     readonly isLiveSkeleton: boolean;
-    /**
-     * 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;
     /**
      * 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`
@@ -151,25 +196,17 @@ interface Engine {
      * `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 {
+interface SarmalInstance extends AnimationControls {
     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;
     /**
      * Smoothly transitions from the current curve to `target`.
      * The trail naturally reflects the new curve as new points are added.
@@ -220,4 +257,4 @@ interface SarmalOptions extends Omit<RendererOptions, "canvas" | "engine"> {
     trailLength?: number;
 }
 
-export type { CurveDef as C, Engine as E, PalettePreset as P, RendererOptions as R, SarmalInstance as S, TrailStyle as T, SarmalOptions as a, Point as b, SeekOptions as c, SeekWithTrailOptions as d };
+export type { CurveDef as C, Engine as E, JumpOptions as J, PalettePreset as P, RendererOptions as R, SarmalInstance as S, TrailStyle as T, SarmalOptions as a, Point as b, SeekOptions as c };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarmal/core",
-  "version": "0.9.10",
+  "version": "0.12.0",
   "description": "Curve path based loading indicators and their renderer",
   "keywords": [
     "animation",