@sarmal/core 0.33.0 → 0.35.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { B as BaseRendererOptions, E as Engine, S as SarmalInstance, C as CurveDef, R as RendererOptions, a as ControlPoint, P as Point, b as SarmalOptions } from './types-BBuUk6nn.cjs';
-export { J as JumpOptions, c as RuntimeRenderOptions, d as SeekOptions, T as TrailColor, e as TrailStyle } from './types-BBuUk6nn.cjs';
+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-_f27GDkU.cjs';
+export { d as BaseRuntimeRenderOptions, J as JumpOptions, e as RuntimeRenderOptions, f as SeekOptions } from './types-_f27GDkU.cjs';
 export { CurveName, curves } from './curves/index.cjs';
-export { B as BoundaryResult, S as SarmalPalette, c as computeBoundaries, p as palettes } from './renderer-shared-Ke9BeK1P.cjs';
+export { B as BoundaryResult, S as SarmalPalette, c as computeBoundaries, p as palettes } from './renderer-shared-C3KCEABq.cjs';
 export { artemis2 } from './curves/artemis2.cjs';
 export { astroid } from './curves/astroid.cjs';
 export { deltoid } from './curves/deltoid.cjs';
@@ -53,6 +53,82 @@ declare function createSVGRenderer(options: SVGRendererOptions): SarmalInstance;
  */
 declare function createSarmalSVG(container: SVGSVGElement, curveDef: CurveDef, options?: SVGSarmalOptions): SarmalInstance;
 
+interface DotMatrixSarmalOptions extends Pick<BaseRendererOptions, "autoStart" | "pauseOnHidden" | "initialPhase"> {
+    /**
+     * 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;
+}
+/**
+ * Creates a dot matrix renderer for a sarmal animation on a canvas element.
+ *
+ * The renderer maps the animation's trail to a grid of dots.
+ * Each frame, the grid is cleared and rebuilt: dots near the head of the trail are bright,
+ *  dots near the tail are dim, and dots with no trail activity are barely visible (5% opacity).
+ *
+ * Grid geometry is derived from `cols` and `rows`.
+ * For example, a 240x240 canvas with `cols: 32, rows: 32` produces 1024 dots with cells approximately 7.5x7.5 px each.
+ *
+ * At init, a pixel mask is computed that records which canvas pixels belong to each dot.
+ * Each frame, RGBA values are written directly into a typed array (one entry per lit pixel)
+ *  and flushed to the canvas with a single `ctx.putImageData` call.
+ * Frame cost is flat regardless of how many dots are lit or what grid size is used.
+ *
+ * @param canvas - The canvas element to draw into.
+ *                 Its `width` and `height` HTML attributes determine the rendering area.
+ *                 CSS display size is not read.
+ * @param curveDef - The curve to animate.
+ * @param options - Optional configuration for grid size, color, roundness, and lifecycle.
+ * @returns A `SarmalInstance` with the standard `play` / `pause` / `destroy` / `morphTo` interface.
+ *
+ * @example
+ * ```ts
+ * import { createSarmalDotMatrix, curves } from '@sarmal/core'
+ *
+ * const instance = createSarmalDotMatrix(canvas, curves.lissajous43, {
+ *   cols: 32,
+ *   rows: 32,
+ *   trailColor: '#2dd4bf',
+ * })
+ * ```
+ */
+declare function createSarmalDotMatrix(canvas: HTMLCanvasElement, curveDef: CurveDef, options?: DotMatrixSarmalOptions): SarmalInstance<DotMatrixRuntimeRenderOptions>;
+
 declare function createEngine(curveDef: CurveDef, trailLength?: number): Engine;
 
 /**
@@ -119,4 +195,4 @@ declare function drawCurve(points: Array<ControlPoint>, opts?: {
  */
 declare function createSarmal(canvas: HTMLCanvasElement, curveDef: CurveDef, options?: SarmalOptions): SarmalInstance;
 
-export { BaseRendererOptions, CurveDef, Engine, Point, RendererOptions, type SVGRendererOptions, type SVGSarmalOptions, SarmalInstance, SarmalOptions, createEngine, createRenderer, createSVGRenderer, createSarmal, createSarmalSVG, drawCurve, evaluateCatmullRom };
+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 };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { B as BaseRendererOptions, E as Engine, S as SarmalInstance, C as CurveDef, R as RendererOptions, a as ControlPoint, P as Point, b as SarmalOptions } from './types-BBuUk6nn.js';
-export { J as JumpOptions, c as RuntimeRenderOptions, d as SeekOptions, T as TrailColor, e as TrailStyle } from './types-BBuUk6nn.js';
+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-_f27GDkU.js';
+export { d as BaseRuntimeRenderOptions, J as JumpOptions, e as RuntimeRenderOptions, f as SeekOptions } from './types-_f27GDkU.js';
 export { CurveName, curves } from './curves/index.js';
-export { B as BoundaryResult, S as SarmalPalette, c as computeBoundaries, p as palettes } from './renderer-shared-Bdca4O4G.js';
+export { B as BoundaryResult, S as SarmalPalette, c as computeBoundaries, p as palettes } from './renderer-shared-DyOI68gd.js';
 export { artemis2 } from './curves/artemis2.js';
 export { astroid } from './curves/astroid.js';
 export { deltoid } from './curves/deltoid.js';
@@ -53,6 +53,82 @@ declare function createSVGRenderer(options: SVGRendererOptions): SarmalInstance;
  */
 declare function createSarmalSVG(container: SVGSVGElement, curveDef: CurveDef, options?: SVGSarmalOptions): SarmalInstance;
 
+interface DotMatrixSarmalOptions extends Pick<BaseRendererOptions, "autoStart" | "pauseOnHidden" | "initialPhase"> {
+    /**
+     * 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;
+}
+/**
+ * Creates a dot matrix renderer for a sarmal animation on a canvas element.
+ *
+ * The renderer maps the animation's trail to a grid of dots.
+ * Each frame, the grid is cleared and rebuilt: dots near the head of the trail are bright,
+ *  dots near the tail are dim, and dots with no trail activity are barely visible (5% opacity).
+ *
+ * Grid geometry is derived from `cols` and `rows`.
+ * For example, a 240x240 canvas with `cols: 32, rows: 32` produces 1024 dots with cells approximately 7.5x7.5 px each.
+ *
+ * At init, a pixel mask is computed that records which canvas pixels belong to each dot.
+ * Each frame, RGBA values are written directly into a typed array (one entry per lit pixel)
+ *  and flushed to the canvas with a single `ctx.putImageData` call.
+ * Frame cost is flat regardless of how many dots are lit or what grid size is used.
+ *
+ * @param canvas - The canvas element to draw into.
+ *                 Its `width` and `height` HTML attributes determine the rendering area.
+ *                 CSS display size is not read.
+ * @param curveDef - The curve to animate.
+ * @param options - Optional configuration for grid size, color, roundness, and lifecycle.
+ * @returns A `SarmalInstance` with the standard `play` / `pause` / `destroy` / `morphTo` interface.
+ *
+ * @example
+ * ```ts
+ * import { createSarmalDotMatrix, curves } from '@sarmal/core'
+ *
+ * const instance = createSarmalDotMatrix(canvas, curves.lissajous43, {
+ *   cols: 32,
+ *   rows: 32,
+ *   trailColor: '#2dd4bf',
+ * })
+ * ```
+ */
+declare function createSarmalDotMatrix(canvas: HTMLCanvasElement, curveDef: CurveDef, options?: DotMatrixSarmalOptions): SarmalInstance<DotMatrixRuntimeRenderOptions>;
+
 declare function createEngine(curveDef: CurveDef, trailLength?: number): Engine;
 
 /**
@@ -119,4 +195,4 @@ declare function drawCurve(points: Array<ControlPoint>, opts?: {
  */
 declare function createSarmal(canvas: HTMLCanvasElement, curveDef: CurveDef, options?: SarmalOptions): SarmalInstance;
 
-export { BaseRendererOptions, CurveDef, Engine, Point, RendererOptions, type SVGRendererOptions, type SVGSarmalOptions, SarmalInstance, SarmalOptions, createEngine, createRenderer, createSVGRenderer, createSarmal, createSarmalSVG, drawCurve, evaluateCatmullRom };
+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 };

package/dist/index.js

@@ -518,6 +518,7 @@ function getPaletteColor(palette, position, timeOffset = 0) {
   return lerpOklab(c1, c2, t);
 }
 var TRAIL_STYLES = ["default", "gradient-static", "gradient-animated"];
+var BASE_RENDER_OPTION_KEYS = /* @__PURE__ */ new Set(["trailColor", "trailStyle"]);
 var RENDER_OPTION_KEYS = /* @__PURE__ */ new Set([
   "trailColor",
   "headColor",
@@ -526,6 +527,19 @@ var RENDER_OPTION_KEYS = /* @__PURE__ */ new Set([
   "headRadius",
   "trailWidth"
 ]);
+function validateBaseRenderOptions(partial) {
+  for (const key of Object.keys(partial)) {
+    if (!BASE_RENDER_OPTION_KEYS.has(key)) {
+      throw new TypeError(`[sarmal] setRenderOptions: unsupported key "${key}" for this renderer`);
+    }
+  }
+  if (partial.trailColor !== void 0) {
+    assertTrailColor(partial.trailColor);
+  }
+  if (partial.trailStyle !== void 0) {
+    assertTrailStyle(partial.trailStyle);
+  }
+}
 function validateRenderOptions(partial) {
   for (const key of Object.keys(partial)) {
     if (!RENDER_OPTION_KEYS.has(key)) {
@@ -1401,6 +1415,371 @@ function createSarmalSVG(container, curveDef, options) {
   return createSVGRenderer({ container, engine, ...rendererOpts });
 }
 
+// src/renderer-dot-matrix.ts
+function createSarmalDotMatrix(canvas, curveDef, options) {
+  const {
+    cols = 32,
+    rows = 32,
+    roundness = 1,
+    trailLength: trailLengthOpt,
+    trailColor: initialColor = "#ffffff",
+    trailStyle: initialTrailStyle = "default",
+    autoStart = true,
+    pauseOnHidden: pauseOnHiddenOpt = true,
+    initialPhase
+  } = options ?? {};
+  const trailLength = trailLengthOpt ?? cols * 3;
+  const engine = createEngine(curveDef, trailLength);
+  if (!canvas.getContext("2d")) {
+    throw new Error("[sarmal] Could not get 2d context from canvas");
+  }
+  const ctx = canvas.getContext("2d");
+  const W = canvas.width;
+  const H = canvas.height;
+  const cellW = W / cols;
+  const cellH = H / rows;
+  const dotR = Math.min(cellW, cellH) * 0.36;
+  let gradientRgb;
+  if (Array.isArray(initialColor)) {
+    validateBaseRenderOptions({ trailColor: initialColor });
+    gradientRgb = initialColor.map(colorToRgb);
+  } else {
+    gradientRgb = null;
+  }
+  let colorRgb = gradientRgb ? gradientRgb[0] : colorToRgb(initialColor);
+  let currentTrailStyle = initialTrailStyle;
+  let animTime = 0;
+  const ANIM_PERIOD = 6;
+  const grid = new Float32Array(cols * rows);
+  let scale = 1;
+  let offsetX = 0;
+  let offsetY = 0;
+  let pixelMaskStarts = new Uint32Array(0);
+  let pixelMaskLengths = new Uint32Array(0);
+  let pixelMaskIndices = new Uint32Array(0);
+  let pixelMaskCoverages = new Float32Array(0);
+  let bgImageData = null;
+  let frameImageData = null;
+  let animationId = null;
+  let lastTime = 0;
+  let pausedByVisibility = false;
+  let morphResolve = null;
+  let morphReject = null;
+  let morphDurationMs = DEFAULT_MORPH_DURATION_MS;
+  let morphProgress = 0;
+  function computePixelMask() {
+    const starts = new Uint32Array(cols * rows);
+    const lengths = new Uint32Array(cols * rows);
+    const allIndices = [];
+    const allCoverages = [];
+    const cornerR = roundness * dotR;
+    const cornerR2 = cornerR * cornerR;
+    const SSAA = 4;
+    const SSAA2 = SSAA * SSAA;
+    for (let row = 0; row < rows; row++) {
+      for (let col = 0; col < cols; col++) {
+        const dotIdx = row * cols + col;
+        const cx = (col + 0.5) * cellW;
+        const cy = (row + 0.5) * cellH;
+        const x0 = Math.max(0, Math.floor(cx - dotR - 1));
+        const x1 = Math.min(W - 1, Math.ceil(cx + dotR + 1));
+        const y0 = Math.max(0, Math.floor(cy - dotR - 1));
+        const y1 = Math.min(H - 1, Math.ceil(cy + dotR + 1));
+        starts[dotIdx] = allIndices.length;
+        let count = 0;
+        for (let py = y0; py <= y1; py++) {
+          for (let px = x0; px <= x1; px++) {
+            let hits = 0;
+            for (let sy = 0; sy < SSAA; sy++) {
+              const spyCenter = py + (sy + 0.5) / SSAA;
+              for (let sx = 0; sx < SSAA; sx++) {
+                const spxCenter = px + (sx + 0.5) / SSAA;
+                const dx = Math.max(Math.abs(spxCenter - cx) - (dotR - cornerR), 0);
+                const dy = Math.max(Math.abs(spyCenter - cy) - (dotR - cornerR), 0);
+                if (dx * dx + dy * dy <= cornerR2) {
+                  hits++;
+                }
+              }
+            }
+            if (hits > 0) {
+              allIndices.push((py * W + px) * 4);
+              allCoverages.push(hits / SSAA2);
+              count++;
+            }
+          }
+        }
+        lengths[dotIdx] = count;
+      }
+    }
+    pixelMaskStarts = starts;
+    pixelMaskLengths = lengths;
+    pixelMaskIndices = new Uint32Array(allIndices);
+    pixelMaskCoverages = new Float32Array(allCoverages);
+  }
+  function buildBgImageData() {
+    bgImageData = new ImageData(W, H);
+    const bg = gradientRgb ? gradientRgb[0] : colorRgb;
+    const baseAlpha = 0.05 * 255;
+    const { data } = bgImageData;
+    const n = cols * rows;
+    for (let dotIdx = 0; dotIdx < n; dotIdx++) {
+      const start = pixelMaskStarts[dotIdx];
+      const len = pixelMaskLengths[dotIdx];
+      for (let k = 0; k < len; k++) {
+        const px = pixelMaskIndices[start + k];
+        const coverage = pixelMaskCoverages[start + k];
+        data[px] = bg.r;
+        data[px + 1] = bg.g;
+        data[px + 2] = bg.b;
+        data[px + 3] = Math.round(baseAlpha * coverage);
+      }
+    }
+  }
+  function sampleGradientRgb(stops, t) {
+    const n = stops.length;
+    const scaled = Math.max(0, Math.min(1, t)) * (n - 1);
+    const i = Math.min(Math.floor(scaled), n - 2);
+    const a = stops[i];
+    const bStop = stops[i + 1];
+    const mix = scaled - i;
+    return {
+      r: Math.round(a.r + (bStop.r - a.r) * mix),
+      g: Math.round(a.g + (bStop.g - a.g) * mix),
+      b: Math.round(a.b + (bStop.b - a.b) * mix)
+    };
+  }
+  function calculateBoundaries(skel) {
+    const b = computeBoundaries(skel, W, H);
+    if (b) {
+      scale = b.scale;
+      offsetX = b.offsetX;
+      offsetY = b.offsetY;
+    }
+  }
+  function mapPt(x, y) {
+    const px = x * scale + offsetX;
+    const py = y * scale + offsetY;
+    return [
+      Math.max(0, Math.min(cols - 1, Math.round(px / W * (cols - 1)))),
+      Math.max(0, Math.min(rows - 1, Math.round(py / H * (rows - 1))))
+    ];
+  }
+  function stamp(c, r, intensity) {
+    const idx = r * cols + c;
+    if (intensity > grid[idx]) {
+      grid[idx] = intensity;
+    }
+  }
+  function buildGrid(deltaTime) {
+    const trail = engine.tick(deltaTime);
+    const count = engine.trailCount;
+    grid.fill(0);
+    for (let i = 0; i < count; i++) {
+      const pt = trail[i];
+      const intensity = (i + 1) / count;
+      const [c, r] = mapPt(pt.x, pt.y);
+      stamp(c, r, intensity);
+      if (i < count - 1) {
+        const next = trail[i + 1];
+        const [nc, nr] = mapPt(next.x, next.y);
+        const steps = Math.ceil(Math.max(Math.abs(nc - c), Math.abs(nr - r))) * 2;
+        for (let s = 1; s < steps; s++) {
+          const t = s / steps;
+          const ix = pt.x + (next.x - pt.x) * t;
+          const iy = pt.y + (next.y - pt.y) * t;
+          const ii = intensity + 1 / count * t;
+          const [ic, ir] = mapPt(ix, iy);
+          stamp(ic, ir, ii);
+        }
+      }
+    }
+  }
+  function draw() {
+    if (!bgImageData || !frameImageData) {
+      return;
+    }
+    frameImageData.data.set(bgImageData.data);
+    const { data } = frameImageData;
+    const sineOffset = currentTrailStyle === "gradient-animated" ? 0.15 * Math.sin(animTime / ANIM_PERIOD * 2 * Math.PI) : 0;
+    const n = cols * rows;
+    for (let dotIdx = 0; dotIdx < n; dotIdx++) {
+      const intensity = grid[dotIdx];
+      if (intensity <= 0) {
+        continue;
+      }
+      let r, g, b;
+      if (gradientRgb !== null) {
+        const t = Math.max(0, Math.min(1, intensity + sineOffset));
+        ({ r, g, b } = sampleGradientRgb(gradientRgb, t));
+      } else {
+        ({ r, g, b } = colorRgb);
+      }
+      const baseA = (0.08 + intensity * 0.92) * 255;
+      const start = pixelMaskStarts[dotIdx];
+      const len = pixelMaskLengths[dotIdx];
+      for (let k = 0; k < len; k++) {
+        const px = pixelMaskIndices[start + k];
+        const coverage = pixelMaskCoverages[start + k];
+        data[px] = r;
+        data[px + 1] = g;
+        data[px + 2] = b;
+        data[px + 3] = Math.round(baseA * coverage);
+      }
+    }
+    ctx.putImageData(frameImageData, 0, 0);
+  }
+  function renderFrame(deltaTime) {
+    if (engine.morphAlpha !== null) {
+      morphProgress = Math.min(1, morphProgress + deltaTime / (morphDurationMs / 1e3));
+      engine.setMorphAlpha(morphProgress);
+      calculateBoundaries(engine.getSarmalSkeleton());
+      if (morphProgress >= 1) {
+        engine.completeMorph();
+        morphResolve?.();
+        morphResolve = null;
+        morphReject = null;
+        morphProgress = 0;
+        calculateBoundaries(engine.getSarmalSkeleton());
+      }
+    } else if (engine.isLiveSkeleton) {
+      calculateBoundaries(engine.getSarmalSkeleton());
+    }
+    if (currentTrailStyle === "gradient-animated") {
+      animTime += deltaTime;
+    }
+    buildGrid(deltaTime);
+    draw();
+  }
+  function loop(timestamp = performance.now()) {
+    const deltaTime = Math.min((timestamp - lastTime) / 1e3, 1 / 30);
+    lastTime = timestamp;
+    renderFrame(deltaTime);
+    animationId = requestAnimationFrame(loop);
+  }
+  calculateBoundaries(engine.getSarmalSkeleton());
+  computePixelMask();
+  frameImageData = new ImageData(W, H);
+  buildBgImageData();
+  if (initialPhase !== void 0) {
+    engine.seek(initialPhase);
+  }
+  renderFrame(0);
+  const instance = {
+    /** Starts the animation loop. Does nothing if already running. */
+    play() {
+      if (animationId !== null) return;
+      lastTime = performance.now();
+      loop();
+    },
+    /** Pauses the animation loop. Preserves current trail state. */
+    pause() {
+      if (animationId === null) return;
+      cancelAnimationFrame(animationId);
+      animationId = null;
+      engine.cancelSpeedTransition();
+    },
+    /** Resets the animation to the start of the curve and clears the grid. */
+    reset() {
+      engine.reset();
+      grid.fill(0);
+    },
+    /** Stops the animation and removes all event listeners. */
+    destroy() {
+      if (animationId !== null) {
+        cancelAnimationFrame(animationId);
+        animationId = null;
+      }
+      document.removeEventListener("visibilitychange", handleVisibilityChange);
+      if (morphReject !== null) {
+        morphReject(new Error("[sarmal] Instance destroyed during morph"));
+        morphResolve = null;
+        morphReject = null;
+      }
+    },
+    ...enginePassthroughs(engine),
+    /**
+     * 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 (morphResolve !== null) {
+        engine.completeMorph();
+        morphResolve();
+        morphResolve = null;
+        morphReject = null;
+        morphProgress = 0;
+      }
+      morphDurationMs = opts?.duration ?? DEFAULT_MORPH_DURATION_MS;
+      morphProgress = 0;
+      engine.startMorph(target, opts?.morphStrategy);
+      return new Promise((resolve, reject) => {
+        morphResolve = resolve;
+        morphReject = reject;
+      });
+    },
+    /**
+     * Updates render options on a live instance without stopping the animation.
+     *
+     * Supported: `trailColor` and `trailStyle`.
+     * ! Unsupported fields (`headColor`, `skeletonColor`, `headRadius`, `trailWidth`) throw.
+     * ! Validation fails the entire call if any field is invalid, leaving options unchanged.
+     */
+    setRenderOptions(partial) {
+      validateBaseRenderOptions(partial);
+      let needsRebuildBg = false;
+      if (partial.trailColor !== void 0) {
+        if (Array.isArray(partial.trailColor)) {
+          gradientRgb = partial.trailColor.map(colorToRgb);
+          colorRgb = gradientRgb[0];
+        } else {
+          gradientRgb = null;
+          colorRgb = colorToRgb(partial.trailColor);
+        }
+        needsRebuildBg = true;
+      }
+      if (partial.trailStyle !== void 0) {
+        currentTrailStyle = partial.trailStyle;
+        if (currentTrailStyle === "default") {
+          animTime = 0;
+        }
+      }
+      if (needsRebuildBg) {
+        buildBgImageData();
+      }
+      if (currentTrailStyle !== "default" && gradientRgb === null) {
+        console.warn(
+          "[sarmal] dot matrix: gradient trailStyle has no effect without a trailColor array"
+        );
+      }
+    }
+  };
+  function handleVisibilityChange() {
+    if (document.hidden) {
+      if (animationId !== null) {
+        instance.pause();
+        pausedByVisibility = true;
+      }
+    } else {
+      if (pausedByVisibility) {
+        pausedByVisibility = false;
+        instance.play();
+      }
+    }
+  }
+  if (pauseOnHiddenOpt) {
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+  }
+  const shouldAutoStart = autoStart !== false;
+  const actuallyAutoStart = shouldAutoStart && !(pauseOnHiddenOpt && document.hidden);
+  if (actuallyAutoStart) {
+    instance.play();
+  } else if (shouldAutoStart) {
+    pausedByVisibility = true;
+  }
+  return instance;
+}
+
 // src/catmull-rom.ts
 var PERIOD = 2 * Math.PI;
 function catmullRom1D(p0, p1, p2, p3, u) {
@@ -1730,6 +2109,6 @@ function createSarmal(canvas, curveDef, options) {
   return createRenderer({ canvas, engine, ...rendererOpts });
 }
 
-export { artemis2, astroid, computeBoundaries, createEngine, createRenderer, createSVGRenderer, createSarmal, createSarmalSVG, curves, deltoid, drawCurve, epicycloid3, epitrochoid7, evaluateCatmullRom, lame, lissajous32, lissajous43, palettes, rose3, rose5 };
+export { artemis2, astroid, computeBoundaries, createEngine, createRenderer, createSVGRenderer, createSarmal, createSarmalDotMatrix, createSarmalSVG, curves, deltoid, drawCurve, epicycloid3, epitrochoid7, evaluateCatmullRom, lame, lissajous32, lissajous43, palettes, rose3, rose5 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map