@sarmal/core 0.34.0 → 0.35.1

package/dist/index.d.cts

@@ -104,10 +104,10 @@ interface DotMatrixSarmalOptions extends Pick<BaseRendererOptions, "autoStart" |
  * 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.
+ * 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.

package/dist/index.d.ts

@@ -104,10 +104,10 @@ interface DotMatrixSarmalOptions extends Pick<BaseRendererOptions, "autoStart" |
  * 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.
+ * 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.

package/dist/index.js

@@ -1416,7 +1416,6 @@ function createSarmalSVG(container, curveDef, options) {
 }
 
 // src/renderer-dot-matrix.ts
-var NUM_BUCKETS = 8;
 function createSarmalDotMatrix(canvas, curveDef, options) {
   const {
     cols = 32,
@@ -1440,14 +1439,8 @@ function createSarmalDotMatrix(canvas, curveDef, options) {
   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 gradientOklab = null;
+  let colorRgb = { r: 255, g: 255, b: 255 };
   let currentTrailStyle = initialTrailStyle;
   let animTime = 0;
   const ANIM_PERIOD = 6;
@@ -1455,7 +1448,12 @@ function createSarmalDotMatrix(canvas, curveDef, options) {
   let scale = 1;
   let offsetX = 0;
   let offsetY = 0;
-  let bgCanvas = null;
+  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;
@@ -1463,33 +1461,82 @@ function createSarmalDotMatrix(canvas, curveDef, options) {
   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();
+  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;
-        bgCtx.roundRect(cx - dotR, cy - dotR, dotR * 2, dotR * 2, roundness * dotR);
+        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);
       }
     }
-    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 applyColor(color) {
+    if (Array.isArray(color)) {
+      gradientOklab = color.map((c) => parseColorToOklab(c));
+      colorRgb = oklabToRgb(gradientOklab[0]);
+    } else {
+      gradientOklab = null;
+      colorRgb = colorToRgb(color);
+    }
   }
   function calculateBoundaries(skel) {
     const b = computeBoundaries(skel, W, H);
@@ -1538,43 +1585,44 @@ function createSarmalDotMatrix(canvas, curveDef, options) {
     }
   }
   function draw() {
-    ctx.clearRect(0, 0, W, H);
-    if (bgCanvas) {
-      ctx.drawImage(bgCanvas, 0, 0);
+    if (!bgImageData || !frameImageData) {
+      return;
     }
-    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();
+    frameImageData.data.set(bgImageData.data);
+    const { data } = frameImageData;
+    const timeOffset = currentTrailStyle === "gradient-animated" ? animTime / ANIM_PERIOD : 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 (gradientOklab !== null) {
+        ({ r, g, b } = oklabToRgb(getPaletteColor(gradientOklab, intensity, timeOffset)));
+      } 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.globalAlpha = 1;
+    ctx.putImageData(frameImageData, 0, 0);
+  }
+  function completeMorphNow() {
+    engine.completeMorph();
+    morphResolve?.();
+    morphResolve = null;
+    morphReject = null;
+    morphProgress = 0;
   }
   function renderFrame(deltaTime) {
     if (engine.morphAlpha !== null) {
@@ -1582,11 +1630,7 @@ function createSarmalDotMatrix(canvas, curveDef, options) {
       engine.setMorphAlpha(morphProgress);
       calculateBoundaries(engine.getSarmalSkeleton());
       if (morphProgress >= 1) {
-        engine.completeMorph();
-        morphResolve?.();
-        morphResolve = null;
-        morphReject = null;
-        morphProgress = 0;
+        completeMorphNow();
         calculateBoundaries(engine.getSarmalSkeleton());
       }
     } else if (engine.isLiveSkeleton) {
@@ -1604,8 +1648,12 @@ function createSarmalDotMatrix(canvas, curveDef, options) {
     renderFrame(deltaTime);
     animationId = requestAnimationFrame(loop);
   }
+  validateBaseRenderOptions({ trailColor: initialColor });
+  applyColor(initialColor);
   calculateBoundaries(engine.getSarmalSkeleton());
-  buildBgCanvas();
+  computePixelMask();
+  frameImageData = new ImageData(W, H);
+  buildBgImageData();
   if (initialPhase !== void 0) {
     engine.seek(initialPhase);
   }
@@ -1650,11 +1698,7 @@ function createSarmalDotMatrix(canvas, curveDef, options) {
      */
     morphTo(target, opts) {
       if (morphResolve !== null) {
-        engine.completeMorph();
-        morphResolve();
-        morphResolve = null;
-        morphReject = null;
-        morphProgress = 0;
+        completeMorphNow();
       }
       morphDurationMs = opts?.duration ?? DEFAULT_MORPH_DURATION_MS;
       morphProgress = 0;
@@ -1675,13 +1719,7 @@ function createSarmalDotMatrix(canvas, curveDef, options) {
       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);
-        }
+        applyColor(partial.trailColor);
         needsRebuildBg = true;
       }
       if (partial.trailStyle !== void 0) {
@@ -1691,11 +1729,15 @@ function createSarmalDotMatrix(canvas, curveDef, options) {
         }
       }
       if (needsRebuildBg) {
-        buildBgCanvas();
+        buildBgImageData();
       }
-      if (currentTrailStyle !== "default" && gradientRgb === null) {
+      if (currentTrailStyle !== "default" && gradientOklab === null) {
+        console.warn(
+          `[sarmal] dot matrix: trailColor is a single color but trailStyle is "${currentTrailStyle}"; the trail will render as a solid color. Pass an array of hex colors to use a real gradient.`
+        );
+      } else if (currentTrailStyle === "default" && gradientOklab !== null) {
         console.warn(
-          "[sarmal] dot matrix: gradient trailStyle has no effect without a trailColor array"
+          '[sarmal] dot matrix: trailColor is an array but trailStyle is "default"; only the first color will be used. Pass a gradient trailStyle to use the whole palette.'
         );
       }
     }