@sarmal/core 0.33.0 → 0.35.0

package/dist/curves/lissajous32.d.cts

@@ -1,4 +1,4 @@
-import { C as CurveDef } from '../types-BBuUk6nn.cjs';
+import { C as CurveDef } from '../types-_f27GDkU.cjs';
 
 /**
  * Lissajous curve with frequency ratio 3:2

package/dist/curves/lissajous32.d.ts

@@ -1,4 +1,4 @@
-import { C as CurveDef } from '../types-BBuUk6nn.js';
+import { C as CurveDef } from '../types-_f27GDkU.js';
 
 /**
  * Lissajous curve with frequency ratio 3:2

package/dist/curves/lissajous43.d.cts

@@ -1,4 +1,4 @@
-import { C as CurveDef } from '../types-BBuUk6nn.cjs';
+import { C as CurveDef } from '../types-_f27GDkU.cjs';
 
 /**
  * Lissajous curve with frequency ratio 4:3

package/dist/curves/lissajous43.d.ts

@@ -1,4 +1,4 @@
-import { C as CurveDef } from '../types-BBuUk6nn.js';
+import { C as CurveDef } from '../types-_f27GDkU.js';
 
 /**
  * Lissajous curve with frequency ratio 4:3

package/dist/curves/rose3.d.cts

@@ -1,4 +1,4 @@
-import { C as CurveDef } from '../types-BBuUk6nn.cjs';
+import { C as CurveDef } from '../types-_f27GDkU.cjs';
 
 /**
  * Rose curve with 3 petals

package/dist/curves/rose3.d.ts

@@ -1,4 +1,4 @@
-import { C as CurveDef } from '../types-BBuUk6nn.js';
+import { C as CurveDef } from '../types-_f27GDkU.js';
 
 /**
  * Rose curve with 3 petals

package/dist/curves/rose5.d.cts

@@ -1,4 +1,4 @@
-import { C as CurveDef } from '../types-BBuUk6nn.cjs';
+import { C as CurveDef } from '../types-_f27GDkU.cjs';
 
 /**
  * Rose curve with 5 petals

package/dist/curves/rose5.d.ts

@@ -1,4 +1,4 @@
-import { C as CurveDef } from '../types-BBuUk6nn.js';
+import { C as CurveDef } from '../types-_f27GDkU.js';
 
 /**
  * Rose curve with 5 petals

package/dist/curves/rose52.d.cts

@@ -1,4 +1,4 @@
-import { C as CurveDef } from '../types-BBuUk6nn.cjs';
+import { C as CurveDef } from '../types-_f27GDkU.cjs';
 
 /**
  * Rose curve with n=5/2 that traces 5 petals over two full revolutions

package/dist/curves/rose52.d.ts

@@ -1,4 +1,4 @@
-import { C as CurveDef } from '../types-BBuUk6nn.js';
+import { C as CurveDef } from '../types-_f27GDkU.js';
 
 /**
  * Rose curve with n=5/2 that traces 5 petals over two full revolutions

package/dist/curves/star.d.cts

@@ -1,4 +1,4 @@
-import { C as CurveDef } from '../types-BBuUk6nn.cjs';
+import { C as CurveDef } from '../types-_f27GDkU.cjs';
 
 /**
  * 5-pointed star based on Fourier harmonics.

package/dist/curves/star.d.ts

@@ -1,4 +1,4 @@
-import { C as CurveDef } from '../types-BBuUk6nn.js';
+import { C as CurveDef } from '../types-_f27GDkU.js';
 
 /**
  * 5-pointed star based on Fourier harmonics.

package/dist/curves/star4.d.cts

@@ -1,4 +1,4 @@
-import { C as CurveDef } from '../types-BBuUk6nn.cjs';
+import { C as CurveDef } from '../types-_f27GDkU.cjs';
 
 /**
  * 4-pointed star based on Fourier harmonics.

package/dist/curves/star4.d.ts

@@ -1,4 +1,4 @@
-import { C as CurveDef } from '../types-BBuUk6nn.js';
+import { C as CurveDef } from '../types-_f27GDkU.js';
 
 /**
  * 4-pointed star based on Fourier harmonics.

package/dist/curves/star7.d.cts

@@ -1,4 +1,4 @@
-import { C as CurveDef } from '../types-BBuUk6nn.cjs';
+import { C as CurveDef } from '../types-_f27GDkU.cjs';
 
 /**
  * 7-pointed star based on Fourier harmonics.

package/dist/curves/star7.d.ts

@@ -1,4 +1,4 @@
-import { C as CurveDef } from '../types-BBuUk6nn.js';
+import { C as CurveDef } from '../types-_f27GDkU.js';
 
 /**
  * 7-pointed star based on Fourier harmonics.

package/dist/index.cjs

@@ -520,6 +520,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",
@@ -528,6 +529,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)) {
@@ -1403,6 +1417,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) {
@@ -1739,6 +2118,7 @@ exports.createEngine = createEngine;
 exports.createRenderer = createRenderer;
 exports.createSVGRenderer = createSVGRenderer;
 exports.createSarmal = createSarmal;
+exports.createSarmalDotMatrix = createSarmalDotMatrix;
 exports.createSarmalSVG = createSarmalSVG;
 exports.curves = curves;
 exports.deltoid = deltoid;