@sarmal/core 0.37.1 → 0.38.0

package/README.md

@@ -1,7 +1,7 @@
 # @sarmal/core
 
 <p align="center">
-  <strong>Parametric curve animations for loading/thinking indicators</strong>
+  <strong>Beautiful animated curves for loading states and ambient motion</strong>
 </p>
 
 <div align="center">
@@ -12,14 +12,14 @@
 
 ---
 
-**@sarmal/core** is a lightweight library for rendering elegant parametric curve animations.
+**@sarmal/core** is a lightweight library for animated curves on canvas and SVG.
 
-The animations can be used anywhere you want. Use it for loading spinners, progress indicators, or to indicate that your very special AI model is _thinking_, up to you.
+Use it for loading animations, thinking indicators, ambient decoration — or whatever else you have in mind.
 
 In web applications or directly in your terminal (`npx @sarmal/core`).
 
 - **Canvas & SVG renderers**: choose one or the other, but why not both?
-- **standard curves**: default cliche curves any LLM can generate in seconds, from classic spirals to custom parametric paths
+- **standard curves**: classic spirals, roses, Lissajous figures — plus draw your own with point arrays
 - **TIME CONTROL**: programmatic time stepping, seeking, and trail effects
 - **Zero dependencies**: tiny bundle, quick to get started
 - **TypeScript-first**: because who would build anyhing complex in pure JS?!

package/dist/auto-init.cjs

@@ -364,15 +364,42 @@ function computeBoundaries(pts, logicalWidth, logicalHeight, minPaddingPx = FIT_
     offsetY: (logicalHeight - h * scale) / 2 - minY * scale
   };
 }
-function enginePassthroughs(engine) {
+var DESTROYED_ERROR = "[sarmal] Instance has been destroyed and cannot be used again. Call pause() instead of destroy() for temporary suspension.";
+function enginePassthroughs(engine, isDestroyed) {
+  function guard() {
+    if (isDestroyed()) {
+      throw new Error(DESTROYED_ERROR);
+    }
+  }
   return {
-    jump: engine.jump,
-    seek: engine.seek,
-    setSpeed: engine.setSpeed,
-    getSpeed: engine.getSpeed,
-    resetSpeed: engine.resetSpeed,
-    setSpeedOver: engine.setSpeedOver,
-    getSarmalSkeleton: engine.getSarmalSkeleton
+    jump(phase, options) {
+      guard();
+      engine.jump(phase, options);
+    },
+    seek(phase, options) {
+      guard();
+      engine.seek(phase, options);
+    },
+    setSpeed(speed) {
+      guard();
+      engine.setSpeed(speed);
+    },
+    getSpeed() {
+      guard();
+      return engine.getSpeed();
+    },
+    resetSpeed() {
+      guard();
+      engine.resetSpeed();
+    },
+    setSpeedOver(speed, duration) {
+      guard();
+      return engine.setSpeedOver(speed, duration);
+    },
+    getSarmalSkeleton() {
+      guard();
+      return engine.getSarmalSkeleton();
+    }
   };
 }
 function hexToRgb(hex) {
@@ -731,6 +758,7 @@ function createRenderer(options) {
   let animationId = null;
   let lastTime = 0;
   let pausedByVisibility = false;
+  let destroyed = false;
   let morphResolve = null;
   let morphReject = null;
   let morphDurationMs = DEFAULT_MORPH_DURATION_MS;
@@ -902,6 +930,9 @@ function createRenderer(options) {
   const shouldAutoStart = options.autoStart !== false;
   const instance = {
     play() {
+      if (destroyed) {
+        throw new Error(DESTROYED_ERROR);
+      }
       if (animationId !== null) {
         return;
       }
@@ -909,6 +940,9 @@ function createRenderer(options) {
       loop();
     },
     pause() {
+      if (destroyed) {
+        throw new Error(DESTROYED_ERROR);
+      }
       if (animationId === null) {
         return;
       }
@@ -917,24 +951,36 @@ function createRenderer(options) {
       engine.cancelSpeedTransition();
     },
     reset() {
+      if (destroyed) {
+        throw new Error(DESTROYED_ERROR);
+      }
       engine.reset();
       trail = [];
       head = null;
     },
     destroy() {
+      if (destroyed) {
+        return;
+      }
+      destroyed = true;
       if (animationId !== null) {
         cancelAnimationFrame(animationId);
         animationId = null;
       }
       document.removeEventListener("visibilitychange", handleVisibilityChange);
+      engine.cancelSpeedTransition();
       if (morphReject !== null) {
-        morphReject(new Error("Instance destroyed during morph"));
+        morphReject(new Error("[sarmal] Instance destroyed during morph"));
         morphResolve = null;
         morphReject = null;
       }
+      ctx.clearRect(0, 0, logicalWidth, logicalHeight);
     },
-    ...enginePassthroughs(engine),
+    ...enginePassthroughs(engine, () => destroyed),
     morphTo(target, options2) {
+      if (destroyed) {
+        throw new Error(DESTROYED_ERROR);
+      }
       if (morphResolve !== null) {
         engine.completeMorph();
         morphResolve();
@@ -951,6 +997,9 @@ function createRenderer(options) {
       });
     },
     setRenderOptions(partial) {
+      if (destroyed) {
+        throw new Error(DESTROYED_ERROR);
+      }
       validateRenderOptions(partial);
       if (partial.trailColor !== void 0) {
         trailColor = partial.trailColor;
@@ -1205,6 +1254,7 @@ function createSVGRenderer(options) {
   let animationId = null;
   let lastTime = 0;
   let pausedByVisibility = false;
+  let destroyed = false;
   const prefersReducedMotion = typeof window !== "undefined" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
   let morphResolve = null;
   let morphReject = null;
@@ -1273,6 +1323,9 @@ function createSVGRenderer(options) {
   const shouldAutoStart = options.autoStart !== false;
   const instance = {
     play() {
+      if (destroyed) {
+        throw new Error(DESTROYED_ERROR);
+      }
       if (animationId !== null) {
         return;
       }
@@ -1280,6 +1333,9 @@ function createSVGRenderer(options) {
       loop();
     },
     pause() {
+      if (destroyed) {
+        throw new Error(DESTROYED_ERROR);
+      }
       if (animationId === null) {
         return;
       }
@@ -1288,23 +1344,34 @@ function createSVGRenderer(options) {
       engine.cancelSpeedTransition();
     },
     reset() {
+      if (destroyed) {
+        throw new Error(DESTROYED_ERROR);
+      }
       engine.reset();
     },
     destroy() {
+      if (destroyed) {
+        return;
+      }
+      destroyed = true;
       if (animationId !== null) {
         cancelAnimationFrame(animationId);
         animationId = null;
       }
       document.removeEventListener("visibilitychange", handleVisibilityChange);
+      engine.cancelSpeedTransition();
       if (morphReject !== null) {
-        morphReject(new Error("Instance destroyed during morph"));
+        morphReject(new Error("[sarmal] Instance destroyed during morph"));
         morphResolve = null;
         morphReject = null;
       }
       group.remove();
     },
-    ...enginePassthroughs(engine),
+    ...enginePassthroughs(engine, () => destroyed),
     morphTo(target, options2) {
+      if (destroyed) {
+        throw new Error(DESTROYED_ERROR);
+      }
       if (morphResolve !== null) {
         engine.completeMorph();
         morphResolve();
@@ -1330,6 +1397,9 @@ function createSVGRenderer(options) {
       });
     },
     setRenderOptions(partial) {
+      if (destroyed) {
+        throw new Error(DESTROYED_ERROR);
+      }
       validateRenderOptions(partial);
       const prevTrailStyle = trailStyle;
       if (partial.trailColor !== void 0) {
@@ -1459,6 +1529,7 @@ function createSarmalDotMatrix(canvas, curveDef, options) {
   let animationId = null;
   let lastTime = 0;
   let pausedByVisibility = false;
+  let destroyed = false;
   let morphResolve = null;
   let morphReject = null;
   let morphDurationMs = DEFAULT_MORPH_DURATION_MS;
@@ -1712,6 +1783,9 @@ function createSarmalDotMatrix(canvas, curveDef, options) {
   const instance = {
     /** Starts the animation loop. Does nothing if already running. */
     play() {
+      if (destroyed) {
+        throw new Error(DESTROYED_ERROR);
+      }
       if (animationId !== null) {
         return;
       }
@@ -1720,6 +1794,9 @@ function createSarmalDotMatrix(canvas, curveDef, options) {
     },
     /** Pauses the animation loop. Preserves current trail state. */
     pause() {
+      if (destroyed) {
+        throw new Error(DESTROYED_ERROR);
+      }
       if (animationId === null) {
         return;
       }
@@ -1729,29 +1806,46 @@ function createSarmalDotMatrix(canvas, curveDef, options) {
     },
     /** Resets the animation to the start of the curve and clears the grid. */
     reset() {
+      if (destroyed) {
+        throw new Error(DESTROYED_ERROR);
+      }
       engine.reset();
       grid.fill(0);
     },
-    /** Stops the animation and removes all event listeners. */
+    /**
+     * Permanently stops the animation and clears the visual output.
+     * Calling any method on a destroyed instance throws an error.
+     * `destroy()` is idempotent — calling it multiple times is safe.
+     */
     destroy() {
+      if (destroyed) {
+        return;
+      }
+      destroyed = true;
       if (animationId !== null) {
         cancelAnimationFrame(animationId);
         animationId = null;
       }
       document.removeEventListener("visibilitychange", handleVisibilityChange);
+      engine.cancelSpeedTransition();
       if (morphReject !== null) {
         morphReject(new Error("[sarmal] Instance destroyed during morph"));
         morphResolve = null;
         morphReject = null;
       }
+      grid.fill(0);
+      ctx.clearRect(0, 0, canvas.width, canvas.height);
     },
-    ...enginePassthroughs(engine),
+    ...enginePassthroughs(engine, () => destroyed),
     /**
      * Smoothly transitions from the current curve to `target`.
      * If a morph is already in progress, it is snapped to completion before the new one starts.
      * @returns A Promise that resolves when the transition finishes.
      */
     morphTo(target, opts) {
+      if (destroyed) {
+        throw new Error(DESTROYED_ERROR);
+      }
       if (morphResolve !== null) {
         completeMorphNow();
       }
@@ -1771,6 +1865,9 @@ function createSarmalDotMatrix(canvas, curveDef, options) {
      * ! Validation fails the entire call if any field is invalid, leaving options unchanged.
      */
     setRenderOptions(partial) {
+      if (destroyed) {
+        throw new Error(DESTROYED_ERROR);
+      }
       validateBaseRenderOptions(partial);
       let needsRebuildBg = false;
       if (partial.trailColor !== void 0) {