@sarmal/core 0.37.1 → 0.38.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { B as BaseRendererOptions, E as Engine, S as SarmalInstance, C as CurveDef, T as TrailColor, a as TrailStyle, D as DotMatrixRuntimeRenderOptions, R as RendererOptions, b as ControlPoint, P as Point, c as SarmalOptions } from './types-B1XeFpuq.cjs';
-export { d as BaseRuntimeRenderOptions, J as JumpOptions, M as MorphStrategy, e as RuntimeRenderOptions, f as SeekOptions } from './types-B1XeFpuq.cjs';
+import { B as BaseRendererOptions, E as Engine, S as SarmalInstance, C as CurveDef, R as RendererOptions, D as DotMatrixSarmalOptions, a as DotMatrixRuntimeRenderOptions, b as ControlPoint, P as Point, c as SarmalOptions } from './types-CmPFR9U3.cjs';
+export { d as BaseDotMatrixOptions, e as BaseInit, f as BaseRuntimeRenderOptions, g as BaseSarmalOptions, h as CanvasInit, i as DotMatrixInit, J as JumpOptions, M as MorphStrategy, j as RuntimeRenderOptions, k as SeekOptions, T as TrailColor, l as TrailStyle } from './types-CmPFR9U3.cjs';
 export { CurveName, curves } from './curves/index.cjs';
-export { B as BoundaryResult, S as SarmalPalette, c as computeBoundaries, p as palettes } from './renderer-shared-Bcc_1IaT.cjs';
+export { B as BoundaryResult, S as SarmalPalette, c as computeBoundaries, p as palettes } from './renderer-shared-Bh33A5Av.cjs';
 export { artemis2 } from './curves/artemis2.cjs';
 export { astroid } from './curves/astroid.cjs';
 export { deltoid } from './curves/deltoid.cjs';
@@ -53,47 +53,14 @@ declare function createSVGRenderer(options: SVGRendererOptions): SarmalInstance;
  */
 declare function createSarmalSVG(container: SVGSVGElement, curveDef: CurveDef, options?: SVGSarmalOptions): SarmalInstance;
 
-interface DotMatrixSarmalOptions extends Pick<BaseRendererOptions, "autoStart" | "pauseOnHidden" | "initialPhase" | "skeletonColor"> {
-    /**
-     * Number of dot columns in the grid.
-     * @default 32
-     */
-    cols?: number;
-    /**
-     * Number of dot rows in the grid.
-     * @default 32
-     */
-    rows?: number;
-    /**
-     * Controls the corner rounding of each dot.
-     * `0` renders as a sharp-cornered square,
-     * `1` renders as a full circle.
-     * Values between `0` and `1` give rounded rectangles.
-     * @default 1
-     */
-    roundness?: number;
-    /**
-     * Number of trail points to keep.
-     * Larger values mean the trail extends further back from the head.
-     * @default cols * 3
-     */
-    trailLength?: number;
-    /**
-     * Color of lit dots. Single color string for solid mode; array of two or more colors for gradient mode.
-     * Gradient mode samples a color per dot based on its position in the trail (tail → head).
-     * Background dots always use the first color at 5% opacity.
-     * @default '#ffffff'
-     */
-    trailColor?: TrailColor;
-    /**
-     * Trail rendering style.
-     * - `'default'` — solid color, alpha varies by intensity.
-     * - `'gradient-static'` — each dot's color is sampled from the `trailColor` gradient. Requires `trailColor` array.
-     * - `'gradient-animated'` — same as `gradient-static` but the gradient phase shifts over time.
-     * @default 'default'
-     */
-    trailStyle?: TrailStyle;
-}
+declare function createEngine(curveDef: CurveDef, trailLength?: number): Engine;
+
+/**
+ * Creates a Canvas 2D renderer for sarmal animations
+ * Renders the skeleton and the trail
+ */
+declare function createRenderer(options: RendererOptions): SarmalInstance;
+
 /**
  * Creates a dot matrix renderer for a sarmal animation on a canvas element.
  *
@@ -129,14 +96,6 @@ interface DotMatrixSarmalOptions extends Pick<BaseRendererOptions, "autoStart" |
  */
 declare function createSarmalDotMatrix(canvas: HTMLCanvasElement, curveDef: CurveDef, options?: DotMatrixSarmalOptions): SarmalInstance<DotMatrixRuntimeRenderOptions>;
 
-declare function createEngine(curveDef: CurveDef, trailLength?: number): Engine;
-
-/**
- * Creates a Canvas 2D renderer for sarmal animations
- * Renders the skeleton and the trail
- */
-declare function createRenderer(options: RendererOptions): SarmalInstance;
-
 /**
  * Evaluates a closed Catmull-Rom spline through every point in `points`
  *
@@ -195,4 +154,4 @@ declare function drawCurve(points: Array<ControlPoint>, opts?: {
  */
 declare function createSarmal(canvas: HTMLCanvasElement, curveDef: CurveDef, options?: SarmalOptions): SarmalInstance;
 
-export { BaseRendererOptions, CurveDef, DotMatrixRuntimeRenderOptions, type DotMatrixSarmalOptions, Engine, Point, RendererOptions, type SVGRendererOptions, type SVGSarmalOptions, SarmalInstance, SarmalOptions, TrailColor, TrailStyle, createEngine, createRenderer, createSVGRenderer, createSarmal, createSarmalDotMatrix, createSarmalSVG, drawCurve, evaluateCatmullRom };
+export { BaseRendererOptions, CurveDef, DotMatrixRuntimeRenderOptions, DotMatrixSarmalOptions, Engine, Point, RendererOptions, type SVGRendererOptions, type SVGSarmalOptions, SarmalInstance, SarmalOptions, createEngine, createRenderer, createSVGRenderer, createSarmal, createSarmalDotMatrix, createSarmalSVG, drawCurve, evaluateCatmullRom };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { B as BaseRendererOptions, E as Engine, S as SarmalInstance, C as CurveDef, T as TrailColor, a as TrailStyle, D as DotMatrixRuntimeRenderOptions, R as RendererOptions, b as ControlPoint, P as Point, c as SarmalOptions } from './types-B1XeFpuq.js';
-export { d as BaseRuntimeRenderOptions, J as JumpOptions, M as MorphStrategy, e as RuntimeRenderOptions, f as SeekOptions } from './types-B1XeFpuq.js';
+import { B as BaseRendererOptions, E as Engine, S as SarmalInstance, C as CurveDef, R as RendererOptions, D as DotMatrixSarmalOptions, a as DotMatrixRuntimeRenderOptions, b as ControlPoint, P as Point, c as SarmalOptions } from './types-CmPFR9U3.js';
+export { d as BaseDotMatrixOptions, e as BaseInit, f as BaseRuntimeRenderOptions, g as BaseSarmalOptions, h as CanvasInit, i as DotMatrixInit, J as JumpOptions, M as MorphStrategy, j as RuntimeRenderOptions, k as SeekOptions, T as TrailColor, l as TrailStyle } from './types-CmPFR9U3.js';
 export { CurveName, curves } from './curves/index.js';
-export { B as BoundaryResult, S as SarmalPalette, c as computeBoundaries, p as palettes } from './renderer-shared-DWPVHjKZ.js';
+export { B as BoundaryResult, S as SarmalPalette, c as computeBoundaries, p as palettes } from './renderer-shared-2tEwOWJm.js';
 export { artemis2 } from './curves/artemis2.js';
 export { astroid } from './curves/astroid.js';
 export { deltoid } from './curves/deltoid.js';
@@ -53,47 +53,14 @@ declare function createSVGRenderer(options: SVGRendererOptions): SarmalInstance;
  */
 declare function createSarmalSVG(container: SVGSVGElement, curveDef: CurveDef, options?: SVGSarmalOptions): SarmalInstance;
 
-interface DotMatrixSarmalOptions extends Pick<BaseRendererOptions, "autoStart" | "pauseOnHidden" | "initialPhase" | "skeletonColor"> {
-    /**
-     * Number of dot columns in the grid.
-     * @default 32
-     */
-    cols?: number;
-    /**
-     * Number of dot rows in the grid.
-     * @default 32
-     */
-    rows?: number;
-    /**
-     * Controls the corner rounding of each dot.
-     * `0` renders as a sharp-cornered square,
-     * `1` renders as a full circle.
-     * Values between `0` and `1` give rounded rectangles.
-     * @default 1
-     */
-    roundness?: number;
-    /**
-     * Number of trail points to keep.
-     * Larger values mean the trail extends further back from the head.
-     * @default cols * 3
-     */
-    trailLength?: number;
-    /**
-     * Color of lit dots. Single color string for solid mode; array of two or more colors for gradient mode.
-     * Gradient mode samples a color per dot based on its position in the trail (tail → head).
-     * Background dots always use the first color at 5% opacity.
-     * @default '#ffffff'
-     */
-    trailColor?: TrailColor;
-    /**
-     * Trail rendering style.
-     * - `'default'` — solid color, alpha varies by intensity.
-     * - `'gradient-static'` — each dot's color is sampled from the `trailColor` gradient. Requires `trailColor` array.
-     * - `'gradient-animated'` — same as `gradient-static` but the gradient phase shifts over time.
-     * @default 'default'
-     */
-    trailStyle?: TrailStyle;
-}
+declare function createEngine(curveDef: CurveDef, trailLength?: number): Engine;
+
+/**
+ * Creates a Canvas 2D renderer for sarmal animations
+ * Renders the skeleton and the trail
+ */
+declare function createRenderer(options: RendererOptions): SarmalInstance;
+
 /**
  * Creates a dot matrix renderer for a sarmal animation on a canvas element.
  *
@@ -129,14 +96,6 @@ interface DotMatrixSarmalOptions extends Pick<BaseRendererOptions, "autoStart" |
  */
 declare function createSarmalDotMatrix(canvas: HTMLCanvasElement, curveDef: CurveDef, options?: DotMatrixSarmalOptions): SarmalInstance<DotMatrixRuntimeRenderOptions>;
 
-declare function createEngine(curveDef: CurveDef, trailLength?: number): Engine;
-
-/**
- * Creates a Canvas 2D renderer for sarmal animations
- * Renders the skeleton and the trail
- */
-declare function createRenderer(options: RendererOptions): SarmalInstance;
-
 /**
  * Evaluates a closed Catmull-Rom spline through every point in `points`
  *
@@ -195,4 +154,4 @@ declare function drawCurve(points: Array<ControlPoint>, opts?: {
  */
 declare function createSarmal(canvas: HTMLCanvasElement, curveDef: CurveDef, options?: SarmalOptions): SarmalInstance;
 
-export { BaseRendererOptions, CurveDef, DotMatrixRuntimeRenderOptions, type DotMatrixSarmalOptions, Engine, Point, RendererOptions, type SVGRendererOptions, type SVGSarmalOptions, SarmalInstance, SarmalOptions, TrailColor, TrailStyle, createEngine, createRenderer, createSVGRenderer, createSarmal, createSarmalDotMatrix, createSarmalSVG, drawCurve, evaluateCatmullRom };
+export { BaseRendererOptions, CurveDef, DotMatrixRuntimeRenderOptions, DotMatrixSarmalOptions, Engine, Point, RendererOptions, type SVGRendererOptions, type SVGSarmalOptions, SarmalInstance, SarmalOptions, createEngine, createRenderer, createSVGRenderer, createSarmal, createSarmalDotMatrix, createSarmalSVG, drawCurve, evaluateCatmullRom };

package/dist/index.js

@@ -362,15 +362,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();
+    }
   };
 }
 var palettes = {
@@ -741,6 +768,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;
@@ -912,6 +940,9 @@ function createRenderer(options) {
   const shouldAutoStart = options.autoStart !== false;
   const instance = {
     play() {
+      if (destroyed) {
+        throw new Error(DESTROYED_ERROR);
+      }
       if (animationId !== null) {
         return;
       }
@@ -919,6 +950,9 @@ function createRenderer(options) {
       loop();
     },
     pause() {
+      if (destroyed) {
+        throw new Error(DESTROYED_ERROR);
+      }
       if (animationId === null) {
         return;
       }
@@ -927,24 +961,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();
@@ -961,6 +1007,9 @@ function createRenderer(options) {
       });
     },
     setRenderOptions(partial) {
+      if (destroyed) {
+        throw new Error(DESTROYED_ERROR);
+      }
       validateRenderOptions(partial);
       if (partial.trailColor !== void 0) {
         trailColor = partial.trailColor;
@@ -1215,6 +1264,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;
@@ -1283,6 +1333,9 @@ function createSVGRenderer(options) {
   const shouldAutoStart = options.autoStart !== false;
   const instance = {
     play() {
+      if (destroyed) {
+        throw new Error(DESTROYED_ERROR);
+      }
       if (animationId !== null) {
         return;
       }
@@ -1290,6 +1343,9 @@ function createSVGRenderer(options) {
       loop();
     },
     pause() {
+      if (destroyed) {
+        throw new Error(DESTROYED_ERROR);
+      }
       if (animationId === null) {
         return;
       }
@@ -1298,23 +1354,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();
@@ -1340,6 +1407,9 @@ function createSVGRenderer(options) {
       });
     },
     setRenderOptions(partial) {
+      if (destroyed) {
+        throw new Error(DESTROYED_ERROR);
+      }
       validateRenderOptions(partial);
       const prevTrailStyle = trailStyle;
       if (partial.trailColor !== void 0) {
@@ -1469,6 +1539,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;
@@ -1722,6 +1793,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;
       }
@@ -1730,6 +1804,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;
       }
@@ -1739,29 +1816,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();
       }
@@ -1781,6 +1875,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) {