@sarmal/core 0.35.0 → 0.36.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-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';
+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-CCgSK31t.cjs';
+export { d as BaseRuntimeRenderOptions, J as JumpOptions, e as RuntimeRenderOptions, f as SeekOptions } from './types-CCgSK31t.cjs';
 export { CurveName, curves } from './curves/index.cjs';
-export { B as BoundaryResult, S as SarmalPalette, c as computeBoundaries, p as palettes } from './renderer-shared-C3KCEABq.cjs';
+export { B as BoundaryResult, S as SarmalPalette, c as computeBoundaries, p as palettes } from './renderer-shared-CFimm7VD.cjs';
 export { artemis2 } from './curves/artemis2.cjs';
 export { astroid } from './curves/astroid.cjs';
 export { deltoid } from './curves/deltoid.cjs';
@@ -53,7 +53,7 @@ declare function createSVGRenderer(options: SVGRendererOptions): SarmalInstance;
  */
 declare function createSarmalSVG(container: SVGSVGElement, curveDef: CurveDef, options?: SVGSarmalOptions): SarmalInstance;
 
-interface DotMatrixSarmalOptions extends Pick<BaseRendererOptions, "autoStart" | "pauseOnHidden" | "initialPhase"> {
+interface DotMatrixSarmalOptions extends Pick<BaseRendererOptions, "autoStart" | "pauseOnHidden" | "initialPhase" | "skeletonColor"> {
     /**
      * Number of dot columns in the grid.
      * @default 32

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-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';
+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-CCgSK31t.js';
+export { d as BaseRuntimeRenderOptions, J as JumpOptions, e as RuntimeRenderOptions, f as SeekOptions } from './types-CCgSK31t.js';
 export { CurveName, curves } from './curves/index.js';
-export { B as BoundaryResult, S as SarmalPalette, c as computeBoundaries, p as palettes } from './renderer-shared-DyOI68gd.js';
+export { B as BoundaryResult, S as SarmalPalette, c as computeBoundaries, p as palettes } from './renderer-shared-BZV9ELOa.js';
 export { artemis2 } from './curves/artemis2.js';
 export { astroid } from './curves/astroid.js';
 export { deltoid } from './curves/deltoid.js';
@@ -53,7 +53,7 @@ declare function createSVGRenderer(options: SVGRendererOptions): SarmalInstance;
  */
 declare function createSarmalSVG(container: SVGSVGElement, curveDef: CurveDef, options?: SVGSarmalOptions): SarmalInstance;
 
-interface DotMatrixSarmalOptions extends Pick<BaseRendererOptions, "autoStart" | "pauseOnHidden" | "initialPhase"> {
+interface DotMatrixSarmalOptions extends Pick<BaseRendererOptions, "autoStart" | "pauseOnHidden" | "initialPhase" | "skeletonColor"> {
     /**
      * Number of dot columns in the grid.
      * @default 32

package/dist/index.js

@@ -320,7 +320,9 @@ function computeTrailQuad(trail, i, trailCount, toX, toY, minWidth = TRAIL_MIN_W
   };
 }
 function computeBoundaries(pts, logicalWidth, logicalHeight, minPaddingPx = FIT_PADDING_MIN) {
-  if (pts.length === 0) return null;
+  if (pts.length === 0) {
+    return null;
+  }
   const first = pts[0];
   let minX = first.x, maxX = first.x, minY = first.y, maxY = first.y;
   for (const p of pts) {
@@ -518,7 +520,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"]);
+var BASE_RENDER_OPTION_KEYS = /* @__PURE__ */ new Set([
+  "trailColor",
+  "trailStyle",
+  "skeletonColor"
+]);
 var RENDER_OPTION_KEYS = /* @__PURE__ */ new Set([
   "trailColor",
   "headColor",
@@ -539,6 +545,9 @@ function validateBaseRenderOptions(partial) {
   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)) {
@@ -1424,6 +1433,7 @@ function createSarmalDotMatrix(canvas, curveDef, options) {
     trailLength: trailLengthOpt,
     trailColor: initialColor = "#ffffff",
     trailStyle: initialTrailStyle = "default",
+    skeletonColor: skeletonColorOpt = "#ffffff",
     autoStart = true,
     pauseOnHidden: pauseOnHiddenOpt = true,
     initialPhase
@@ -1439,14 +1449,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;
@@ -1460,6 +1464,8 @@ function createSarmalDotMatrix(canvas, curveDef, options) {
   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;
@@ -1518,7 +1524,7 @@ function createSarmalDotMatrix(canvas, curveDef, options) {
   }
   function buildBgImageData() {
     bgImageData = new ImageData(W, H);
-    const bg = gradientRgb ? gradientRgb[0] : colorRgb;
+    const bg = colorRgb;
     const baseAlpha = 0.05 * 255;
     const { data } = bgImageData;
     const n = cols * rows;
@@ -1535,18 +1541,61 @@ function createSarmalDotMatrix(canvas, curveDef, options) {
       }
     }
   }
-  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 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);
@@ -1600,7 +1649,8 @@ function createSarmalDotMatrix(canvas, curveDef, options) {
     }
     frameImageData.data.set(bgImageData.data);
     const { data } = frameImageData;
-    const sineOffset = currentTrailStyle === "gradient-animated" ? 0.15 * Math.sin(animTime / ANIM_PERIOD * 2 * Math.PI) : 0;
+    writeSkeletonPixels(data);
+    const timeOffset = currentTrailStyle === "gradient-animated" ? animTime / ANIM_PERIOD : 0;
     const n = cols * rows;
     for (let dotIdx = 0; dotIdx < n; dotIdx++) {
       const intensity = grid[dotIdx];
@@ -1608,9 +1658,8 @@ function createSarmalDotMatrix(canvas, curveDef, options) {
         continue;
       }
       let r, g, b;
-      if (gradientRgb !== null) {
-        const t = Math.max(0, Math.min(1, intensity + sineOffset));
-        ({ r, g, b } = sampleGradientRgb(gradientRgb, t));
+      if (gradientOklab !== null) {
+        ({ r, g, b } = oklabToRgb(getPaletteColor(gradientOklab, intensity, timeOffset)));
       } else {
         ({ r, g, b } = colorRgb);
       }
@@ -1628,21 +1677,26 @@ function createSarmalDotMatrix(canvas, curveDef, options) {
     }
     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) {
-        engine.completeMorph();
-        morphResolve?.();
-        morphResolve = null;
-        morphReject = null;
-        morphProgress = 0;
+        completeMorphNow();
         calculateBoundaries(engine.getSarmalSkeleton());
       }
+      computeSkeletonGrid(engine.getSarmalSkeleton());
     } else if (engine.isLiveSkeleton) {
       calculateBoundaries(engine.getSarmalSkeleton());
+      computeSkeletonGrid(engine.getSarmalSkeleton());
     }
     if (currentTrailStyle === "gradient-animated") {
       animTime += deltaTime;
@@ -1656,8 +1710,12 @@ function createSarmalDotMatrix(canvas, curveDef, options) {
     renderFrame(deltaTime);
     animationId = requestAnimationFrame(loop);
   }
+  validateBaseRenderOptions({ trailColor: initialColor, skeletonColor: skeletonColorOpt });
+  applyColor(initialColor);
+  applySkeletonColor(skeletonColorOpt);
   calculateBoundaries(engine.getSarmalSkeleton());
   computePixelMask();
+  computeSkeletonGrid(engine.getSarmalSkeleton());
   frameImageData = new ImageData(W, H);
   buildBgImageData();
   if (initialPhase !== void 0) {
@@ -1667,13 +1725,17 @@ function createSarmalDotMatrix(canvas, curveDef, options) {
   const instance = {
     /** Starts the animation loop. Does nothing if already running. */
     play() {
-      if (animationId !== null) return;
+      if (animationId !== null) {
+        return;
+      }
       lastTime = performance.now();
       loop();
     },
     /** Pauses the animation loop. Preserves current trail state. */
     pause() {
-      if (animationId === null) return;
+      if (animationId === null) {
+        return;
+      }
       cancelAnimationFrame(animationId);
       animationId = null;
       engine.cancelSpeedTransition();
@@ -1704,11 +1766,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;
@@ -1721,23 +1779,20 @@ function createSarmalDotMatrix(canvas, curveDef, options) {
     /**
      * Updates render options on a live instance without stopping the animation.
      *
-     * Supported: `trailColor` and `trailStyle`.
-     * ! Unsupported fields (`headColor`, `skeletonColor`, `headRadius`, `trailWidth`) throw.
+     * 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) {
-        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.skeletonColor !== void 0) {
+        applySkeletonColor(partial.skeletonColor);
+      }
       if (partial.trailStyle !== void 0) {
         currentTrailStyle = partial.trailStyle;
         if (currentTrailStyle === "default") {
@@ -1747,9 +1802,13 @@ function createSarmalDotMatrix(canvas, curveDef, options) {
       if (needsRebuildBg) {
         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.'
         );
       }
     }