@sarmal/core 0.36.4 → 0.37.0

package/dist/auto-init.d.cts

@@ -1,6 +1,12 @@
 /**
  * Scans for `<canvas data-sarmal="curveName">` and `<svg data-sarmal="curveName">`
  *  when **DOMContentLoaded** is triggered, and creates a Sarmal instance for each one.
+ *
+ * Renderer selection:
+ * - `svg[data-sarmal]` → SVG renderer (`createSarmalSVG`)
+ * - `canvas[data-sarmal]` with no `data-renderer`, or `data-renderer="canvas"` → canvas ribbon renderer (`createSarmal`)
+ * - `canvas[data-sarmal][data-renderer="dot-matrix"]` → dot matrix renderer (`createSarmalDotMatrix`)
+ * - `canvas[data-sarmal]` with any other `data-renderer` value → `console.error`, element skipped
  */
 declare function init(): void;
 

package/dist/auto-init.d.ts

@@ -1,6 +1,12 @@
 /**
  * Scans for `<canvas data-sarmal="curveName">` and `<svg data-sarmal="curveName">`
  *  when **DOMContentLoaded** is triggered, and creates a Sarmal instance for each one.
+ *
+ * Renderer selection:
+ * - `svg[data-sarmal]` → SVG renderer (`createSarmalSVG`)
+ * - `canvas[data-sarmal]` with no `data-renderer`, or `data-renderer="canvas"` → canvas ribbon renderer (`createSarmal`)
+ * - `canvas[data-sarmal][data-renderer="dot-matrix"]` → dot matrix renderer (`createSarmalDotMatrix`)
+ * - `canvas[data-sarmal]` with any other `data-renderer` value → `console.error`, element skipped
  */
 declare function init(): void;
 

package/dist/auto-init.js

@@ -508,6 +508,11 @@ 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",
+  "skeletonColor"
+]);
 var RENDER_OPTION_KEYS = /* @__PURE__ */ new Set([
   "trailColor",
   "headColor",
@@ -516,6 +521,22 @@ 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);
+  }
+  if (partial.skeletonColor !== void 0) {
+    assertSkeletonColor(partial.skeletonColor);
+  }
+}
 function validateRenderOptions(partial) {
   for (const key of Object.keys(partial)) {
     if (!RENDER_OPTION_KEYS.has(key)) {
@@ -1391,6 +1412,413 @@ 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",
+    skeletonColor: skeletonColorOpt = "#ffffff",
+    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 gradientOklab = [];
+  let colorRgb = { r: 255, g: 255, b: 255 };
+  let trailStyle = initialTrailStyle;
+  let trailColor = initialColor;
+  let gradientAnimTime = 0;
+  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 skeletonColorOklab = null;
+  const skeletonDotGrid = new Uint8Array(cols * rows);
+  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 = 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 applyColor(color) {
+    colorRgb = colorToRgb(resolveTrailMainColor(color));
+    gradientOklab = resolveTrailPalette(color).map((c) => parseColorToOklab(c));
+  }
+  function applySkeletonColor(color) {
+    skeletonColorOklab = color === "transparent" ? null : parseColorToOklab(color);
+  }
+  function computeSkeletonGrid(skel) {
+    skeletonDotGrid.fill(0);
+    const count = skel.length;
+    for (let i = 0; i < count; i++) {
+      const pt = skel[i];
+      const [c, r] = mapPt(pt.x, pt.y);
+      skeletonDotGrid[r * cols + c] = 1;
+      if (i < count - 1) {
+        const next = skel[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 [ic, ir] = mapPt(ix, iy);
+          skeletonDotGrid[ir * cols + ic] = 1;
+        }
+      }
+    }
+  }
+  function writeSkeletonPixels(data) {
+    if (skeletonColorOklab === null) {
+      return;
+    }
+    const { r, g, b } = oklabToRgb(skeletonColorOklab);
+    const skelBaseAlpha = DEFAULT_SKELETON_OPACITY * 255;
+    const n = cols * rows;
+    for (let dotIdx = 0; dotIdx < n; dotIdx++) {
+      if (!skeletonDotGrid[dotIdx]) {
+        continue;
+      }
+      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(skelBaseAlpha * coverage);
+      }
+    }
+  }
+  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;
+    writeSkeletonPixels(data);
+    const timeOffset = trailStyle === "gradient-animated" ? gradientAnimTime * 5e-4 : 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 (trailStyle !== "default") {
+        ({ r, g, b } = oklabToRgb(getPaletteColor(gradientOklab, intensity, timeOffset)));
+      } else {
+        ({ r, g, b } = colorRgb);
+      }
+      const skelFloor = skeletonColorOklab !== null && skeletonDotGrid[dotIdx] === 1 ? DEFAULT_SKELETON_OPACITY * 255 : 0;
+      const baseA = Math.max(skelFloor, (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 completeMorphNow() {
+    engine.completeMorph();
+    morphResolve?.();
+    morphResolve = null;
+    morphReject = null;
+    morphProgress = 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) {
+        completeMorphNow();
+        calculateBoundaries(engine.getSarmalSkeleton());
+      }
+      computeSkeletonGrid(engine.getSarmalSkeleton());
+    } else if (engine.isLiveSkeleton) {
+      calculateBoundaries(engine.getSarmalSkeleton());
+      computeSkeletonGrid(engine.getSarmalSkeleton());
+    }
+    if (trailStyle === "gradient-animated") {
+      gradientAnimTime += deltaTime * 1e3;
+    }
+    buildGrid(deltaTime);
+    draw();
+  }
+  function loop(timestamp = performance.now()) {
+    const deltaTime = Math.min((timestamp - lastTime) / 1e3, 1 / 30);
+    lastTime = timestamp;
+    renderFrame(deltaTime);
+    animationId = requestAnimationFrame(loop);
+  }
+  validateBaseRenderOptions({ trailColor: initialColor, skeletonColor: skeletonColorOpt });
+  applyColor(initialColor);
+  applySkeletonColor(skeletonColorOpt);
+  warnIfTrailColorMismatch(trailColor, trailStyle);
+  calculateBoundaries(engine.getSarmalSkeleton());
+  computePixelMask();
+  computeSkeletonGrid(engine.getSarmalSkeleton());
+  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) {
+        completeMorphNow();
+      }
+      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`, `trailStyle`, and `skeletonColor`.
+     * ! Unsupported fields (`headColor`, `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) {
+        trailColor = partial.trailColor;
+        applyColor(trailColor);
+        needsRebuildBg = true;
+      }
+      if (partial.skeletonColor !== void 0) {
+        applySkeletonColor(partial.skeletonColor);
+      }
+      if (partial.trailStyle !== void 0) {
+        trailStyle = partial.trailStyle;
+        if (trailStyle === "default") {
+          gradientAnimTime = 0;
+        }
+      }
+      if (needsRebuildBg) {
+        buildBgImageData();
+      }
+      if (partial.trailColor !== void 0 || partial.trailStyle !== void 0) {
+        warnIfTrailColorMismatch(trailColor, trailStyle);
+      }
+    }
+  };
+  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) {
@@ -1731,7 +2159,15 @@ function parseTrailColor(value) {
   }
   return value;
 }
+function parseBoolAttr(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  return value !== "false";
+}
 function buildOptions(el2) {
+  const autoStart = parseBoolAttr(el2.dataset.autoStart);
+  const pauseOnHidden = parseBoolAttr(el2.dataset.pauseOnHidden);
   return {
     ...el2.dataset.trailColor && {
       trailColor: parseTrailColor(el2.dataset.trailColor)
@@ -1742,9 +2178,38 @@ function buildOptions(el2) {
     ...el2.dataset.trailLength && { trailLength: parseInt(el2.dataset.trailLength, 10) },
     ...el2.dataset.trailStyle && {
       trailStyle: el2.dataset.trailStyle
+    },
+    ...el2.dataset.trailWidth && { trailWidth: parseFloat(el2.dataset.trailWidth) },
+    ...autoStart !== void 0 && { autoStart },
+    ...pauseOnHidden !== void 0 && { pauseOnHidden },
+    // `!==` undefined so that data-initial-phase="0" is correctly passed as 0
+    ...el2.dataset.initialPhase !== void 0 && {
+      initialPhase: parseFloat(el2.dataset.initialPhase)
     }
   };
 }
+function buildDotMatrixOptions(el2) {
+  const autoStart = parseBoolAttr(el2.dataset.autoStart);
+  const pauseOnHidden = parseBoolAttr(el2.dataset.pauseOnHidden);
+  return {
+    ...el2.dataset.trailColor && {
+      trailColor: parseTrailColor(el2.dataset.trailColor)
+    },
+    ...el2.dataset.skeletonColor && { skeletonColor: el2.dataset.skeletonColor },
+    ...el2.dataset.trailStyle && {
+      trailStyle: el2.dataset.trailStyle
+    },
+    ...el2.dataset.trailLength && { trailLength: parseInt(el2.dataset.trailLength, 10) },
+    ...autoStart !== void 0 && { autoStart },
+    ...pauseOnHidden !== void 0 && { pauseOnHidden },
+    ...el2.dataset.initialPhase !== void 0 && {
+      initialPhase: parseFloat(el2.dataset.initialPhase)
+    },
+    ...el2.dataset.cols && { cols: parseInt(el2.dataset.cols, 10) },
+    ...el2.dataset.rows && { rows: parseInt(el2.dataset.rows, 10) },
+    ...el2.dataset.roundness && { roundness: parseFloat(el2.dataset.roundness) }
+  };
+}
 function init() {
   const elements = document.querySelectorAll("canvas[data-sarmal], svg[data-sarmal]");
   elements.forEach((el2) => {
@@ -1756,8 +2221,13 @@ function init() {
     if (!curveDef) {
       return console.error(`[sarmal] "${curveName}" is not a valid curve name`);
     }
-    const options = buildOptions(el2);
-    const instance = el2 instanceof HTMLCanvasElement ? createSarmal(el2, curveDef, options) : createSarmalSVG(el2, curveDef, options);
+    const renderer = el2.dataset.renderer;
+    if (el2 instanceof HTMLCanvasElement && renderer !== void 0 && renderer !== "canvas" && renderer !== "dot-matrix") {
+      return console.error(
+        `[sarmal] Unknown data-renderer value: "${renderer}". Expected "canvas" or "dot-matrix".`
+      );
+    }
+    const instance = el2 instanceof HTMLCanvasElement && renderer === "dot-matrix" ? createSarmalDotMatrix(el2, curveDef, buildDotMatrixOptions(el2)) : el2 instanceof HTMLCanvasElement ? createSarmal(el2, curveDef, buildOptions(el2)) : createSarmalSVG(el2, curveDef, buildOptions(el2));
     if (el2.dataset.speed) {
       instance.setSpeed(parseFloat(el2.dataset.speed));
     }