@sarmal/core 0.31.0 → 0.34.0

package/dist/curves/lissajous32.d.ts

@@ -1,4 +1,4 @@
-import { C as CurveDef } from '../types-zbxUgcmZ.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-zbxUgcmZ.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-zbxUgcmZ.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-zbxUgcmZ.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-zbxUgcmZ.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-zbxUgcmZ.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-zbxUgcmZ.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-zbxUgcmZ.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-zbxUgcmZ.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-zbxUgcmZ.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-zbxUgcmZ.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-zbxUgcmZ.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-zbxUgcmZ.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-zbxUgcmZ.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-zbxUgcmZ.js';
+import { C as CurveDef } from '../types-_f27GDkU.js';
 
 /**
  * 7-pointed star based on Fourier harmonics.

package/dist/index.cjs

@@ -375,11 +375,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);
@@ -516,13 +520,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)) {
@@ -544,6 +563,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") {
@@ -613,6 +635,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];
 }
@@ -681,7 +715,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 = [];
@@ -775,7 +816,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})`;
@@ -933,6 +976,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 {
@@ -1031,7 +1077,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);
@@ -1126,8 +1179,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);
@@ -1319,6 +1372,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 {
@@ -1361,6 +1417,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) {
@@ -1697,6 +2064,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;