@sarmal/core 0.31.0 → 0.34.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-zbxUgcmZ.cjs';
-export { J as JumpOptions, c as RuntimeRenderOptions, d as SeekOptions, T as TrailColor, e as TrailStyle } from './types-zbxUgcmZ.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-jqw_Q1WO.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.
+ *
+ * The background layer (all dim dots) is pre-rendered to an OffscreenCanvas at init and
+ *  restored each frame with a single `drawImage` call.
+ * Lit dots are batched by brightness level,
+ *  so the total draw calls per frame is around 10–12 regardless of grid size.
+ *
+ * @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-zbxUgcmZ.js';
-export { J as JumpOptions, c as RuntimeRenderOptions, d as SeekOptions, T as TrailColor, e as TrailStyle } from './types-zbxUgcmZ.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-OR--cv-t.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.
+ *
+ * The background layer (all dim dots) is pre-rendered to an OffscreenCanvas at init and
+ *  restored each frame with a single `drawImage` call.
+ * Lit dots are batched by brightness level,
+ *  so the total draw calls per frame is around 10–12 regardless of grid size.
+ *
+ * @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

@@ -373,11 +373,15 @@ function enginePassthroughs(engine) {
 }
 var palettes = {
   bard: ["#a855f7", "#3b82f6", "#14b8a6", "#ec4899"],
-  sunset: ["#f97316", "#dc2626", "#9333ea", "#f472b6"],
+  carnival: ["#ff6b6b", "#4ecdc4", "#ffe66d"],
   ocean: ["#1e3a8a", "#06b6d4", "#22d3ee", "#e0f2fe"],
+  sunset: ["#f97316", "#dc2626", "#9333ea", "#f472b6"],
   ice: ["#1e3a8a", "#67e8f9"],
-  fire: ["#7f1d1d", "#fbbf24"],
-  forest: ["#14532d", "#86efac"]
+  rocketpop: ["#08b8cd", "#ffffff", "#ff001f"],
+  neon: ["#00e5ff", "#7c3aed", "#e040fb"],
+  vaporwave: ["#ff71ce", "#01cdfe", "#b967ff"],
+  pastel: ["#c4b5fd", "#fbcfe8", "#bae6fd"],
+  sakura: ["#fff1f2", "#fda4af", "#fb7185"]
 };
 function hexToRgb(hex) {
   const n = parseInt(hex.slice(1), 16);
@@ -514,13 +518,28 @@ 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",
   "skeletonColor",
   "trailStyle",
-  "headRadius"
+  "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)) {
@@ -542,6 +561,9 @@ function validateRenderOptions(partial) {
   if (partial.headRadius !== void 0) {
     assertHeadRadius(partial.headRadius);
   }
+  if (partial.trailWidth !== void 0) {
+    assertTrailWidth(partial.trailWidth);
+  }
 }
 function assertTrailColor(value) {
   if (typeof value === "string") {
@@ -611,6 +633,18 @@ function assertHeadRadius(value) {
     );
   }
 }
+function assertTrailWidth(value) {
+  if (typeof value !== "number") {
+    throw new TypeError(
+      `[sarmal] setRenderOptions: trailWidth must be a number, got ${JSON.stringify(value)}`
+    );
+  }
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new TypeError(
+      `[sarmal] setRenderOptions: trailWidth must be a finite positive number, got ${value}`
+    );
+  }
+}
 function resolveTrailMainColor(trailColor) {
   return typeof trailColor === "string" ? trailColor : trailColor[0];
 }
@@ -679,7 +713,14 @@ function createRenderer(options) {
   setupCanvas();
   let logicalWidth = canvas.width / dpr;
   let logicalHeight = canvas.height / dpr;
+  if (options.headRadius !== void 0) {
+    validateRenderOptions({ headRadius: options.headRadius });
+  }
+  if (options.trailWidth !== void 0) {
+    validateRenderOptions({ trailWidth: options.trailWidth });
+  }
   let headRadius = options.headRadius ?? getHeadDotRadius(logicalWidth, logicalHeight);
+  let trailWidth = options.trailWidth ?? 1;
   let skeleton = [];
   let skeletonCanvas = null;
   let trail = [];
@@ -773,7 +814,9 @@ function createRenderer(options) {
         i,
         trailCount,
         toX,
-        toY
+        toY,
+        TRAIL_MIN_WIDTH * trailWidth,
+        TRAIL_MAX_WIDTH * trailWidth
       );
       if (trailStyle === "default") {
         ctx.fillStyle = `rgba(${trailSolidRgb},${opacity})`;
@@ -931,6 +974,9 @@ function createRenderer(options) {
       if (partial.headRadius !== void 0) {
         headRadius = partial.headRadius;
       }
+      if (partial.trailWidth !== void 0) {
+        trailWidth = partial.trailWidth;
+      }
       if (userHeadColor === null) {
         headColor = resolveHeadColor(trailColor, trailStyle);
       } else {
@@ -1029,7 +1075,14 @@ function createSVGRenderer(options) {
   const svgTrailMinWidth = TRAIL_MIN_WIDTH * viewSize / containerPx;
   const svgTrailMaxWidth = TRAIL_MAX_WIDTH * viewSize / containerPx;
   const svgSkeletonStrokeWidth = String(SKELETON_STROKE_WIDTH_PX * viewSize / containerPx);
+  if (options.headRadius !== void 0) {
+    validateRenderOptions({ headRadius: options.headRadius });
+  }
+  if (options.trailWidth !== void 0) {
+    validateRenderOptions({ trailWidth: options.trailWidth });
+  }
   headRadius = options.headRadius ?? SVG_DEFAULT_HEAD_RADIUS;
+  let trailWidth = options.trailWidth ?? 1;
   container.setAttribute("viewBox", `0 0 ${viewSize} ${viewSize}`);
   container.setAttribute("role", "img");
   container.setAttribute("aria-label", ariaLabel);
@@ -1124,8 +1177,8 @@ function createSVGRenderer(options) {
         trailCount,
         px,
         py,
-        svgTrailMinWidth,
-        svgTrailMaxWidth
+        svgTrailMinWidth * trailWidth,
+        svgTrailMaxWidth * trailWidth
       );
       const d = `M${l0x.toFixed(2)} ${l0y.toFixed(2)} L${l1x.toFixed(2)} ${l1y.toFixed(2)} L${r1x.toFixed(2)} ${r1y.toFixed(2)} L${r0x.toFixed(2)} ${r0y.toFixed(2)} Z`;
       trailPaths[i].setAttribute("d", d);
@@ -1317,6 +1370,9 @@ function createSVGRenderer(options) {
         headRadius = partial.headRadius;
         headCircle.setAttribute("r", String(headRadius));
       }
+      if (partial.trailWidth !== void 0) {
+        trailWidth = partial.trailWidth;
+      }
       if (userHeadColor === null) {
         headColor = resolveHeadColor(trailColor, trailStyle);
       } else {
@@ -1359,6 +1415,317 @@ function createSarmalSVG(container, curveDef, options) {
   return createSVGRenderer({ container, engine, ...rendererOpts });
 }
 
+// src/renderer-dot-matrix.ts
+var NUM_BUCKETS = 8;
+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 bgCanvas = 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 buildBgCanvas() {
+    bgCanvas = new OffscreenCanvas(W, H);
+    const bgCtx = bgCanvas.getContext("2d");
+    const bg = gradientRgb ? gradientRgb[0] : colorRgb;
+    bgCtx.fillStyle = `rgba(${bg.r},${bg.g},${bg.b},0.05)`;
+    bgCtx.beginPath();
+    for (let row = 0; row < rows; row++) {
+      for (let col = 0; col < cols; col++) {
+        const cx = (col + 0.5) * cellW;
+        const cy = (row + 0.5) * cellH;
+        bgCtx.roundRect(cx - dotR, cy - dotR, dotR * 2, dotR * 2, roundness * dotR);
+      }
+    }
+    bgCtx.fill();
+  }
+  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() {
+    ctx.clearRect(0, 0, W, H);
+    if (bgCanvas) {
+      ctx.drawImage(bgCanvas, 0, 0);
+    }
+    const animOffset = currentTrailStyle === "gradient-animated" ? Math.abs(animTime / ANIM_PERIOD % 2 - 1) * 0.35 : 0;
+    for (let bucket = 0; bucket < NUM_BUCKETS; bucket++) {
+      const lo = bucket / NUM_BUCKETS;
+      const hi = (bucket + 1) / NUM_BUCKETS;
+      const midpoint = (lo + hi) / 2;
+      const alpha = 0.08 + midpoint * 0.92;
+      let hasLit = false;
+      ctx.beginPath();
+      for (let row = 0; row < rows; row++) {
+        for (let col = 0; col < cols; col++) {
+          const intensity = grid[row * cols + col];
+          if (intensity > lo && intensity <= hi) {
+            const cx = (col + 0.5) * cellW;
+            const cy = (row + 0.5) * cellH;
+            ctx.roundRect(cx - dotR, cy - dotR, dotR * 2, dotR * 2, roundness * dotR);
+            hasLit = true;
+          }
+        }
+      }
+      if (hasLit) {
+        if (gradientRgb !== null) {
+          const t = ((midpoint + animOffset) % 1 + 1) % 1;
+          const { r, g, b } = sampleGradientRgb(gradientRgb, t);
+          ctx.fillStyle = `rgb(${r},${g},${b})`;
+        } else {
+          const { r, g, b } = colorRgb;
+          ctx.fillStyle = `rgb(${r},${g},${b})`;
+        }
+        ctx.globalAlpha = alpha;
+        ctx.fill();
+      }
+    }
+    ctx.globalAlpha = 1;
+  }
+  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());
+  buildBgCanvas();
+  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) {
+        buildBgCanvas();
+      }
+      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) {
@@ -1688,6 +2055,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