@sarmal/core 0.37.4 → 0.38.0

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) {