@sarmal/core 0.14.0 → 0.15.0

package/dist/index.js

@@ -61,13 +61,13 @@ function resolveCurve(curveDef) {
     period,
     speed,
     skeleton: curveDef.skeleton,
-    skeletonFn: curveDef.skeletonFn
+    skeletonFn: curveDef.skeletonFn,
   };
 }
 function createEngine(curveDef, trailLength = 120) {
   if (!Number.isFinite(trailLength) || trailLength <= 0) {
     throw new RangeError(
-      `[sarmal] trailLength must be a positive finite number, got ${trailLength}`
+      `[sarmal] trailLength must be a positive finite number, got ${trailLength}`,
     );
   }
   let curve = resolveCurve(curveDef);
@@ -108,7 +108,7 @@ function createEngine(curveDef, trailLength = 120) {
       actualTime += deltaTime;
       if (morphCurveB !== null && _morphAlpha !== null) {
         const a = curve.fn(t, actualTime, EMPTY_PARAMS);
-        const tB = _morphStrategy === "normalized" ? t / curve.period * morphCurveB.period : t;
+        const tB = _morphStrategy === "normalized" ? (t / curve.period) * morphCurveB.period : t;
         const b = morphCurveB.fn(tB, actualTime, EMPTY_PARAMS);
         trail.push(a.x + (b.x - a.x) * _morphAlpha, a.y + (b.y - a.y) * _morphAlpha);
       } else {
@@ -132,14 +132,14 @@ function createEngine(curveDef, trailLength = 120) {
       trail.clear();
     },
     jump(newT, { clearTrail = false } = {}) {
-      t = (newT % curve.period + curve.period) % curve.period;
+      t = ((newT % curve.period) + curve.period) % curve.period;
       if (clearTrail) {
         trail.clear();
       }
     },
     seek(targetT, { wrap = false, step = curve.period / trailLength } = {}) {
       const advance = curve.speed * step;
-      const target = (targetT % curve.period + curve.period) % curve.period;
+      const target = ((targetT % curve.period) + curve.period) % curve.period;
       const targetTime = target / curve.speed;
       t = target;
       actualTime = targetTime;
@@ -148,7 +148,7 @@ function createEngine(curveDef, trailLength = 120) {
       const count = wrap ? trailLength : Math.min(trailLength, pointsFromStart);
       for (let i = count - 1; i >= 0; i--) {
         const sampleT = target - i * advance;
-        const wrappedT = (sampleT % curve.period + curve.period) % curve.period;
+        const wrappedT = ((sampleT % curve.period) + curve.period) % curve.period;
         const time = targetTime - i * step;
         const point = curve.fn(wrappedT, time, EMPTY_PARAMS);
         trail.push(point.x, point.y);
@@ -165,13 +165,16 @@ function createEngine(curveDef, trailLength = 120) {
           ...frozenB,
           fn: (sampleT, time, params) => {
             const a = frozenA.fn(sampleT, time, params);
-            const tB = frozenStrategy === "normalized" ? sampleT / frozenA.period * frozenB.period : sampleT;
+            const tB =
+              frozenStrategy === "normalized"
+                ? (sampleT / frozenA.period) * frozenB.period
+                : sampleT;
             const b = frozenB.fn(tB, time, params);
             return {
               x: a.x + (b.x - a.x) * frozenAlpha,
-              y: a.y + (b.y - a.y) * frozenAlpha
+              y: a.y + (b.y - a.y) * frozenAlpha,
             };
-          }
+          },
         };
       }
       _morphStrategy = strategy;
@@ -184,7 +187,7 @@ function createEngine(curveDef, trailLength = 120) {
     completeMorph() {
       if (morphCurveB !== null) {
         if (_morphStrategy === "normalized" && curve.period !== morphCurveB.period) {
-          t = t / curve.period * morphCurveB.period;
+          t = (t / curve.period) * morphCurveB.period;
         }
         curve = morphCurveB;
       }
@@ -196,19 +199,22 @@ function createEngine(curveDef, trailLength = 120) {
       const points = new Array(steps);
       if (morphCurveB !== null && _morphAlpha !== null) {
         for (let i = 0; i < steps; i++) {
-          const sampleT = i / (steps - 1) * curve.period;
+          const sampleT = (i / (steps - 1)) * curve.period;
           const a = sampleSkeleton(curve, sampleT);
-          const tB = _morphStrategy === "normalized" ? sampleT / curve.period * morphCurveB.period : sampleT;
+          const tB =
+            _morphStrategy === "normalized"
+              ? (sampleT / curve.period) * morphCurveB.period
+              : sampleT;
           const b = sampleSkeleton(morphCurveB, tB);
           points[i] = {
             x: a.x + (b.x - a.x) * _morphAlpha,
-            y: a.y + (b.y - a.y) * _morphAlpha
+            y: a.y + (b.y - a.y) * _morphAlpha,
           };
         }
         return points;
       }
       for (let i = 0; i < steps; i++) {
-        const sampleT = i / (steps - 1) * curve.period;
+        const sampleT = (i / (steps - 1)) * curve.period;
         points[i] = sampleSkeleton(curve, sampleT);
       }
       return points;
@@ -250,7 +256,7 @@ function createEngine(curveDef, trailLength = 120) {
         _speedTransition.reject(new Error("Speed transition cancelled"));
         _speedTransition = null;
       }
-    }
+    },
   };
 }
 
@@ -313,13 +319,16 @@ function computeTrailQuad(trail, i, trailCount, toX, toY) {
     r1x: nx - n1.x * w1,
     r1y: ny - n1.y * w1,
     opacity,
-    progress
+    progress,
   };
 }
 function computeBoundaries(pts, logicalWidth, logicalHeight) {
   if (pts.length === 0) return null;
   const first = pts[0];
-  let minX = first.x, maxX = first.x, minY = first.y, maxY = first.y;
+  let minX = first.x,
+    maxX = first.x,
+    minY = first.y,
+    maxY = first.y;
   for (const p of pts) {
     if (p.x < minX) {
       minX = p.x;
@@ -338,7 +347,7 @@ function computeBoundaries(pts, logicalWidth, logicalHeight) {
   const h = maxY - minY;
   if (w === 0 && h === 0) {
     throw new Error(
-      "[sarmal] Degenerate curve: all skeleton points are identical. Check that your curve fn returns distinct points for different values of t."
+      "[sarmal] Degenerate curve: all skeleton points are identical. Check that your curve fn returns distinct points for different values of t.",
     );
   }
   const scaleXProportional = logicalWidth / (w * (1 + FIT_PADDING * 2));
@@ -349,12 +358,12 @@ function computeBoundaries(pts, logicalWidth, logicalHeight) {
     scaleXProportional,
     scaleYProportional,
     scaleXMinPadding,
-    scaleYMinPadding
+    scaleYMinPadding,
   );
   return {
     scale,
     offsetX: (logicalWidth - w * scale) / 2 - minX * scale,
-    offsetY: (logicalHeight - h * scale) / 2 - minY * scale
+    offsetY: (logicalHeight - h * scale) / 2 - minY * scale,
   };
 }
 function enginePassthroughs(engine) {
@@ -364,33 +373,25 @@ function enginePassthroughs(engine) {
     setSpeed: engine.setSpeed,
     getSpeed: engine.getSpeed,
     resetSpeed: engine.resetSpeed,
-    setSpeedOver: engine.setSpeedOver
+    setSpeedOver: engine.setSpeedOver,
   };
 }
-var GRADIENT = {
+var palettes = {
   bard: ["#a855f7", "#3b82f6", "#14b8a6", "#ec4899"],
   sunset: ["#f97316", "#dc2626", "#9333ea", "#f472b6"],
   ocean: ["#1e3a8a", "#06b6d4", "#22d3ee", "#e0f2fe"],
   ice: ["#1e3a8a", "#67e8f9"],
   fire: ["#7f1d1d", "#fbbf24"],
-  forest: ["#14532d", "#86efac"]
-};
-var PRESETS = {
-  bard: GRADIENT.bard,
-  sunset: GRADIENT.sunset,
-  ocean: GRADIENT.ocean,
-  ice: GRADIENT.ice,
-  fire: GRADIENT.fire,
-  forest: GRADIENT.forest
+  forest: ["#14532d", "#86efac"],
 };
 function hexToRgb(hex) {
   const n = parseInt(hex.slice(1), 16);
-  return { r: n >> 16, g: n >> 8 & 255, b: n & 255 };
+  return { r: n >> 16, g: (n >> 8) & 255, b: n & 255 };
 }
 var lerpRgb = (a, b, t) => ({
   r: Math.round(a.r + (b.r - a.r) * t),
   g: Math.round(a.g + (b.g - a.g) * t),
-  b: Math.round(a.b + (b.b - a.b) * t)
+  b: Math.round(a.b + (b.b - a.b) * t),
 });
 function getPaletteColor(palette, position, timeOffset = 0) {
   if (palette.length === 0) {
@@ -407,21 +408,123 @@ function getPaletteColor(palette, position, timeOffset = 0) {
   const c2 = hexToRgb(palette[(idx + 1) % palette.length]);
   return lerpRgb(c1, c2, t);
 }
-function resolvePalette(palette, trailStyle) {
-  if (Array.isArray(palette)) {
-    return palette;
+var HEX_COLOR_RE = /^#[0-9a-fA-F]{6}$/;
+var TRAIL_STYLES = ["default", "gradient-static", "gradient-animated"];
+var RENDER_OPTION_KEYS = /* @__PURE__ */ new Set([
+  "trailColor",
+  "headColor",
+  "skeletonColor",
+  "trailStyle",
+]);
+function validateRenderOptions(partial) {
+  for (const key of Object.keys(partial)) {
+    if (!RENDER_OPTION_KEYS.has(key)) {
+      throw new TypeError(`[sarmal] setRenderOptions: unknown key "${key}"`);
+    }
+  }
+  if (partial.trailColor !== void 0) {
+    assertTrailColor(partial.trailColor);
+  }
+  if (partial.headColor !== void 0) {
+    assertHeadColor(partial.headColor);
+  }
+  if (partial.skeletonColor !== void 0) {
+    assertSkeletonColor(partial.skeletonColor);
+  }
+  if (partial.trailStyle !== void 0) {
+    assertTrailStyle(partial.trailStyle);
+  }
+}
+function assertTrailColor(value) {
+  if (typeof value === "string") {
+    if (!HEX_COLOR_RE.test(value)) {
+      throw new TypeError(
+        `[sarmal] setRenderOptions: trailColor must be a 6-digit hex string, got "${value}"`,
+      );
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    if (value.length < 2) {
+      throw new RangeError(
+        `[sarmal] setRenderOptions: trailColor array must have at least 2 entries, got ${value.length}`,
+      );
+    }
+    for (let i = 0; i < value.length; i++) {
+      const entry = value[i];
+      if (typeof entry !== "string" || !HEX_COLOR_RE.test(entry)) {
+        throw new TypeError(
+          `[sarmal] setRenderOptions: trailColor[${i}] must be a 6-digit hex string, got ${JSON.stringify(entry)}`,
+        );
+      }
+    }
+    return;
+  }
+  throw new TypeError(
+    `[sarmal] setRenderOptions: trailColor must be a 6-digit hex string or an array of hex strings, got ${JSON.stringify(value)}`,
+  );
+}
+function assertHeadColor(value) {
+  if (value === null) {
+    return;
   }
-  if (palette && palette in PRESETS) {
-    return PRESETS[palette];
+  if (typeof value !== "string" || !HEX_COLOR_RE.test(value)) {
+    throw new TypeError(
+      `[sarmal] setRenderOptions: headColor must be a 6-digit hex string or null, got ${JSON.stringify(value)}`,
+    );
+  }
+}
+function assertSkeletonColor(value) {
+  if (value === "transparent") {
+    return;
+  }
+  if (typeof value !== "string" || !HEX_COLOR_RE.test(value)) {
+    throw new TypeError(
+      `[sarmal] setRenderOptions: skeletonColor must be a 6-digit hex string or "transparent", got ${JSON.stringify(value)}`,
+    );
+  }
+}
+function assertTrailStyle(value) {
+  if (!TRAIL_STYLES.includes(value)) {
+    throw new RangeError(
+      `[sarmal] setRenderOptions: trailStyle must be one of "default", "gradient-static", "gradient-animated", got ${JSON.stringify(value)}`,
+    );
+  }
+}
+function resolveTrailMainColor(trailColor) {
+  return typeof trailColor === "string" ? trailColor : trailColor[0];
+}
+function resolveTrailPalette(trailColor) {
+  return typeof trailColor === "string" ? [trailColor] : trailColor;
+}
+function resolveHeadColor(trailColor, trailStyle) {
+  if (trailStyle === "default") {
+    return resolveTrailMainColor(trailColor);
+  }
+  const palette = resolveTrailPalette(trailColor);
+  const last = palette[palette.length - 1];
+  const { r, g, b } = hexToRgb(last);
+  return `rgb(${r},${g},${b})`;
+}
+function warnIfTrailColorMismatch(trailColor, trailStyle) {
+  if (trailStyle === "default" && Array.isArray(trailColor)) {
+    console.warn(
+      '[sarmal] trailColor is an array but trailStyle is "default"; only the first color will be used. Pass a gradient trailStyle to use the whole palette.',
+    );
+    return;
+  }
+  if (trailStyle !== "default" && typeof trailColor === "string") {
+    console.warn(
+      `[sarmal] trailColor is a single color but trailStyle is "${trailStyle}"; the trail will render as a solid color. Pass an array of hex colors to use a real gradient.`,
+    );
   }
-  return trailStyle === "gradient-animated" ? GRADIENT.bard : GRADIENT.ice;
 }
 
 // src/renderer.ts
-var DEFAULT_SKELETON_COLOR = "#ffffff";
+var WHITE_HEX = "#ffffff";
 function hexToRgbComponents(hex) {
   const n = parseInt(hex.slice(1), 16);
-  return `${n >> 16},${n >> 8 & 255},${n & 255}`;
+  return `${n >> 16},${(n >> 8) & 255},${n & 255}`;
 }
 function applyDprSizing(target, logicalWidth, logicalHeight, dpr) {
   target.style.width = `${logicalWidth}px`;
@@ -436,22 +539,14 @@ function createRenderer(options) {
   }
   const ctx = canvas.getContext("2d");
   const engine = options.engine;
-  const trailStyle = options.trailStyle ?? "default";
-  const trailColor = options.trailColor ?? "#ffffff";
-  const palette = resolvePalette(options.palette, trailStyle);
-  function defaultHeadColor() {
-    if (trailStyle !== "default") {
-      const { r, g, b } = getPaletteColor(palette, 1);
-      return `rgb(${r},${g},${b})`;
-    }
-    return trailColor;
-  }
-  const opts = {
-    skeletonColor: options.skeletonColor ?? DEFAULT_SKELETON_COLOR,
-    trailColor,
-    headColor: options.headColor ?? defaultHeadColor()
-  };
-  const trailRgb = hexToRgbComponents(opts.trailColor);
+  let trailStyle = options.trailStyle ?? "default";
+  let trailColor = options.trailColor ?? WHITE_HEX;
+  let skeletonColor = options.skeletonColor ?? WHITE_HEX;
+  let userHeadColor = options.headColor ?? null;
+  let headColor = userHeadColor ?? resolveHeadColor(trailColor, trailStyle);
+  let trailSolidRgb = hexToRgbComponents(resolveTrailMainColor(trailColor));
+  let trailPalette = resolveTrailPalette(trailColor);
+  warnIfTrailColorMismatch(trailColor, trailStyle);
   const dpr = typeof window !== "undefined" ? window.devicePixelRatio || 1 : 1;
   function setupCanvas() {
     const rect = canvas.getBoundingClientRect();
@@ -486,11 +581,13 @@ function createRenderer(options) {
     }
   }
   function buildSkeletonCanvas() {
-    if (skeleton.length < 2) return;
+    if (skeleton.length < 2) {
+      return;
+    }
     skeletonCanvas = new OffscreenCanvas(canvas.width, canvas.height);
     const skeletonCtx = skeletonCanvas.getContext("2d");
     skeletonCtx.setTransform(dpr, 0, 0, dpr, 0, 0);
-    skeletonCtx.strokeStyle = `rgba(${hexToRgbComponents(opts.skeletonColor)},${DEFAULT_SKELETON_OPACITY})`;
+    skeletonCtx.strokeStyle = `rgba(${hexToRgbComponents(skeletonColor)},${DEFAULT_SKELETON_OPACITY})`;
     skeletonCtx.lineWidth = 1.5;
     skeletonCtx.beginPath();
     const first = skeleton[0];
@@ -502,8 +599,10 @@ function createRenderer(options) {
     skeletonCtx.stroke();
   }
   function drawSkeletonPath(pts, opacity) {
-    if (pts.length < 2) return;
-    ctx.strokeStyle = `rgba(${hexToRgbComponents(opts.skeletonColor)},${opacity})`;
+    if (pts.length < 2) {
+      return;
+    }
+    ctx.strokeStyle = `rgba(${hexToRgbComponents(skeletonColor)},${opacity})`;
     ctx.lineWidth = 1.5;
     ctx.beginPath();
     ctx.moveTo(pts[0].x * scale + offsetX, pts[0].y * scale + offsetY);
@@ -513,7 +612,7 @@ function createRenderer(options) {
     ctx.stroke();
   }
   function drawSkeleton() {
-    if (opts.skeletonColor === "transparent") {
+    if (skeletonColor === "transparent") {
       return;
     }
     if (engine.morphAlpha !== null) {
@@ -524,7 +623,7 @@ function createRenderer(options) {
       if (skeleton.length < 2) {
         return;
       }
-      ctx.strokeStyle = `rgba(${hexToRgbComponents(opts.skeletonColor)},${DEFAULT_SKELETON_OPACITY})`;
+      ctx.strokeStyle = `rgba(${hexToRgbComponents(skeletonColor)},${DEFAULT_SKELETON_OPACITY})`;
       ctx.lineWidth = 1.5;
       ctx.beginPath();
       const first = skeleton[0];
@@ -550,13 +649,13 @@ function createRenderer(options) {
         i,
         trailCount,
         toX,
-        toY
+        toY,
       );
       if (trailStyle === "default") {
-        ctx.fillStyle = `rgba(${trailRgb},${opacity})`;
+        ctx.fillStyle = `rgba(${trailSolidRgb},${opacity})`;
       } else {
         const timeOffset = trailStyle === "gradient-animated" ? gradientAnimTime * 5e-4 : 0;
-        const color = getPaletteColor(palette, progress, timeOffset);
+        const color = getPaletteColor(trailPalette, progress, timeOffset);
         ctx.fillStyle = `rgba(${color.r},${color.g},${color.b},${opacity})`;
       }
       ctx.beginPath();
@@ -574,8 +673,9 @@ function createRenderer(options) {
     }
     const x = head.x * scale + offsetX;
     const y = head.y * scale + offsetY;
-    const r = options.headRadius ?? Math.max(2, 3 * Math.sqrt(Math.min(logicalWidth, logicalHeight) / 160));
-    ctx.fillStyle = opts.headColor;
+    const r =
+      options.headRadius ?? Math.max(2, 3 * Math.sqrt(Math.min(logicalWidth, logicalHeight) / 160));
+    ctx.fillStyle = headColor;
     ctx.beginPath();
     ctx.arc(x, y, r, 0, Math.PI * 2);
     ctx.fill();
@@ -675,7 +775,35 @@ function createRenderer(options) {
       return new Promise((resolve) => {
         morphResolve = resolve;
       });
-    }
+    },
+    setRenderOptions(partial) {
+      validateRenderOptions(partial);
+      if (partial.trailColor !== void 0) {
+        trailColor = partial.trailColor;
+        trailSolidRgb = hexToRgbComponents(resolveTrailMainColor(trailColor));
+        trailPalette = resolveTrailPalette(trailColor);
+      }
+      if (partial.skeletonColor !== void 0) {
+        skeletonColor = partial.skeletonColor;
+        if (skeletonColor !== "transparent" && !engine.isLiveSkeleton) {
+          buildSkeletonCanvas();
+        }
+      }
+      if (partial.trailStyle !== void 0) {
+        trailStyle = partial.trailStyle;
+      }
+      if (partial.headColor !== void 0) {
+        userHeadColor = partial.headColor;
+      }
+      if (userHeadColor === null) {
+        headColor = resolveHeadColor(trailColor, trailStyle);
+      } else {
+        headColor = userHeadColor;
+      }
+      if (partial.trailColor !== void 0 || partial.trailStyle !== void 0) {
+        warnIfTrailColorMismatch(trailColor, trailStyle);
+      }
+    },
   };
   if (shouldAutoStart) {
     instance.play();
@@ -701,7 +829,7 @@ function sampleCurveSkeleton(curveDef) {
   const samples = Math.ceil(period * 50);
   const pts = Array.from({ length: samples });
   for (let i = 0; i < samples; i++) {
-    const t = i / (samples - 1) * period;
+    const t = (i / (samples - 1)) * period;
     pts[i] = curveDef.skeletonFn ? curveDef.skeletonFn(t) : curveDef.fn(t, 0, EMPTY_PARAMS2);
   }
   return pts;
@@ -711,47 +839,48 @@ function el(tag) {
 }
 function createSVGRenderer(options) {
   const { container, engine } = options;
-  const trailColor = options.trailColor ?? "#ffffff";
-  const trailStyle = options.trailStyle ?? "default";
-  const palette = resolvePalette(options.palette, trailStyle);
-  const opts = {
-    skeletonColor: options.skeletonColor ?? "#ffffff",
-    trailColor,
-    headColor: options.headColor ?? (trailStyle !== "default" ? (() => {
-      const { r, g, b } = getPaletteColor(palette, 1);
-      return `rgb(${r},${g},${b})`;
-    })() : trailColor),
-    ariaLabel: options.ariaLabel ?? "Loading"
-  };
+  let trailStyle = options.trailStyle ?? "default";
+  let trailColor = options.trailColor ?? "#ffffff";
+  let skeletonColor = options.skeletonColor ?? "#ffffff";
+  let userHeadColor = options.headColor ?? null;
+  let headColor = userHeadColor ?? resolveHeadColor(trailColor, trailStyle);
+  let trailSolid = resolveTrailMainColor(trailColor);
+  let trailPalette = resolveTrailPalette(trailColor);
+  const ariaLabel = options.ariaLabel ?? "Loading";
+  warnIfTrailColorMismatch(trailColor, trailStyle);
   const rect = container.getBoundingClientRect();
   const width = rect.width || 200;
   const height = rect.height || 200;
-  const headRadius = options.headRadius ?? Math.max(2, 3 * Math.sqrt(Math.min(width, height) / 160));
+  const headRadius =
+    options.headRadius ?? Math.max(2, 3 * Math.sqrt(Math.min(width, height) / 160));
   const svg = el("svg");
   svg.setAttribute("width", String(width));
   svg.setAttribute("height", String(height));
   svg.setAttribute("viewBox", `0 0 ${width} ${height}`);
   svg.setAttribute("role", "img");
-  svg.setAttribute("aria-label", opts.ariaLabel);
+  svg.setAttribute("aria-label", ariaLabel);
   const titleEl = el("title");
-  titleEl.textContent = opts.ariaLabel;
+  titleEl.textContent = ariaLabel;
   svg.appendChild(titleEl);
   const skeletonPath = el("path");
   skeletonPath.setAttribute("data-sarmal-role", "skeleton");
   skeletonPath.setAttribute("fill", "none");
-  skeletonPath.setAttribute("stroke", opts.skeletonColor);
+  skeletonPath.setAttribute("stroke", skeletonColor);
   skeletonPath.setAttribute("stroke-opacity", String(DEFAULT_SKELETON_OPACITY));
   skeletonPath.setAttribute("stroke-width", "1.5");
+  if (skeletonColor === "transparent") {
+    skeletonPath.setAttribute("visibility", "hidden");
+  }
   svg.appendChild(skeletonPath);
   const skeletonPathA = el("path");
   skeletonPathA.setAttribute("fill", "none");
-  skeletonPathA.setAttribute("stroke", opts.skeletonColor);
+  skeletonPathA.setAttribute("stroke", skeletonColor);
   skeletonPathA.setAttribute("stroke-width", "1.5");
   skeletonPathA.setAttribute("visibility", "hidden");
   svg.appendChild(skeletonPathA);
   const skeletonPathB = el("path");
   skeletonPathB.setAttribute("fill", "none");
-  skeletonPathB.setAttribute("stroke", opts.skeletonColor);
+  skeletonPathB.setAttribute("stroke", skeletonColor);
   skeletonPathB.setAttribute("stroke-width", "1.5");
   skeletonPathB.setAttribute("visibility", "hidden");
   svg.appendChild(skeletonPathB);
@@ -760,13 +889,13 @@ function createSVGRenderer(options) {
   const trailPaths = [];
   for (let i = 0; i < MAX_TRAIL_SEGMENTS; i++) {
     const path = el("path");
-    path.setAttribute("fill", opts.trailColor);
+    path.setAttribute("fill", trailSolid);
     svg.appendChild(path);
     trailPaths.push(path);
   }
   const headCircle = el("circle");
   headCircle.setAttribute("data-sarmal-role", "head");
-  headCircle.setAttribute("fill", opts.headColor);
+  headCircle.setAttribute("fill", headColor);
   headCircle.setAttribute("r", String(headRadius));
   svg.appendChild(headCircle);
   container.appendChild(svg);
@@ -809,14 +938,14 @@ function createSVGRenderer(options) {
         i,
         trailCount,
         px,
-        py
+        py,
       );
       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);
       trailPaths[i].setAttribute("fill-opacity", opacity.toFixed(3));
       if (trailStyle !== "default") {
         const timeOffset = trailStyle === "gradient-animated" ? gradientAnimTime * 5e-4 : 0;
-        const { r, g, b } = getPaletteColor(palette, progress, timeOffset);
+        const { r, g, b } = getPaletteColor(trailPalette, progress, timeOffset);
         trailPaths[i].setAttribute("fill", `rgb(${r},${g},${b})`);
       }
     }
@@ -836,7 +965,8 @@ function createSVGRenderer(options) {
   }
   let animationId = null;
   let lastTime = 0;
-  const prefersReducedMotion = typeof window !== "undefined" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  const prefersReducedMotion =
+    typeof window !== "undefined" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
   let morphResolve = null;
   let morphDurationMs = DEFAULT_MORPH_DURATION_MS;
   let morphTarget = null;
@@ -853,7 +983,7 @@ function createSVGRenderer(options) {
         skeletonPathA.setAttribute("visibility", "visible");
         skeletonPathA.setAttribute(
           "stroke-opacity",
-          String((1 - morphAlpha) * DEFAULT_SKELETON_OPACITY)
+          String((1 - morphAlpha) * DEFAULT_SKELETON_OPACITY),
         );
       }
       if (morphPathBBuilt) {
@@ -949,7 +1079,52 @@ function createSVGRenderer(options) {
       return new Promise((resolve) => {
         morphResolve = resolve;
       });
-    }
+    },
+    setRenderOptions(partial) {
+      validateRenderOptions(partial);
+      const prevTrailStyle = trailStyle;
+      if (partial.trailColor !== void 0) {
+        trailColor = partial.trailColor;
+        trailSolid = resolveTrailMainColor(trailColor);
+        trailPalette = resolveTrailPalette(trailColor);
+        if (trailStyle === "default") {
+          for (const p of trailPaths) {
+            p.setAttribute("fill", trailSolid);
+          }
+        }
+      }
+      if (partial.skeletonColor !== void 0) {
+        skeletonColor = partial.skeletonColor;
+        if (skeletonColor === "transparent") {
+          skeletonPath.setAttribute("visibility", "hidden");
+        } else {
+          skeletonPath.setAttribute("stroke", skeletonColor);
+          skeletonPath.removeAttribute("visibility");
+          skeletonPathA.setAttribute("stroke", skeletonColor);
+          skeletonPathB.setAttribute("stroke", skeletonColor);
+        }
+      }
+      if (partial.trailStyle !== void 0) {
+        trailStyle = partial.trailStyle;
+        if (prevTrailStyle !== "default" && trailStyle === "default") {
+          for (const p of trailPaths) {
+            p.setAttribute("fill", trailSolid);
+          }
+        }
+      }
+      if (partial.headColor !== void 0) {
+        userHeadColor = partial.headColor;
+      }
+      if (userHeadColor === null) {
+        headColor = resolveHeadColor(trailColor, trailStyle);
+      } else {
+        headColor = userHeadColor;
+      }
+      headCircle.setAttribute("fill", headColor);
+      if (partial.trailColor !== void 0 || partial.trailStyle !== void 0) {
+        warnIfTrailColorMismatch(trailColor, trailStyle);
+      }
+    },
   };
   if (shouldAutoStart) {
     instance.play();
@@ -965,19 +1140,22 @@ function createSarmalSVG(container, curveDef, options) {
 // src/curves/artemis2.ts
 var TWO_PI2 = Math.PI * 2;
 function artemis2Fn(t, _time, _params) {
-  const a = 0.35, b = 0.15, ox = 0.175;
-  const s = Math.sin(t), c = Math.cos(t);
+  const a = 0.35,
+    b = 0.15,
+    ox = 0.175;
+  const s = Math.sin(t),
+    c = Math.cos(t);
   const denom = 1 + s * s;
   return {
-    x: c * (1 + a * c) / denom - ox,
-    y: s * c * (1 + b * c) / denom
+    x: (c * (1 + a * c)) / denom - ox,
+    y: (s * c * (1 + b * c)) / denom,
   };
 }
 var artemis2 = {
   name: "Artemis II",
   fn: artemis2Fn,
   period: TWO_PI2,
-  speed: 0.7
+  speed: 0.7,
 };
 
 // src/curves/astroid.ts
@@ -987,14 +1165,14 @@ function astroidFn(t, _time, _params) {
   const s = Math.sin(t);
   return {
     x: c * c * c,
-    y: s * s * s
+    y: s * s * s,
   };
 }
 var astroid = {
   name: "Astroid",
   fn: astroidFn,
   period: TWO_PI3,
-  speed: 1.1
+  speed: 1.1,
 };
 
 // src/curves/deltoid.ts
@@ -1002,14 +1180,14 @@ var TWO_PI4 = Math.PI * 2;
 function deltoidFn(t, _time, _params) {
   return {
     x: 2 * Math.cos(t) + Math.cos(2 * t),
-    y: 2 * Math.sin(t) - Math.sin(2 * t)
+    y: 2 * Math.sin(t) - Math.sin(2 * t),
   };
 }
 var deltoid = {
   name: "Deltoid",
   fn: deltoidFn,
   period: TWO_PI4,
-  speed: 0.9
+  speed: 0.9,
 };
 
 // src/curves/epicycloid3.ts
@@ -1017,14 +1195,14 @@ var TWO_PI5 = Math.PI * 2;
 function epicycloid3Fn(t, _time, _params) {
   return {
     x: 4 * Math.cos(t) - Math.cos(4 * t),
-    y: 4 * Math.sin(t) - Math.sin(4 * t)
+    y: 4 * Math.sin(t) - Math.sin(4 * t),
   };
 }
 var epicycloid3 = {
   name: "Epicycloid (n=3)",
   fn: epicycloid3Fn,
   period: TWO_PI5,
-  speed: 0.75
+  speed: 0.75,
 };
 
 // src/curves/epitrochoid7.ts
@@ -1033,14 +1211,14 @@ function epitrochoid7Fn(t, _time, _params) {
   const d = 1 + 0.55 * Math.sin(t * 0.5);
   return {
     x: 7 * Math.cos(t) - d * Math.cos(7 * t),
-    y: 7 * Math.sin(t) - d * Math.sin(7 * t)
+    y: 7 * Math.sin(t) - d * Math.sin(7 * t),
   };
 }
 function epitrochoid7SkeletonFn(t) {
   const d = 1.275;
   return {
     x: 7 * Math.cos(t) - d * Math.cos(7 * t),
-    y: 7 * Math.sin(t) - d * Math.sin(7 * t)
+    y: 7 * Math.sin(t) - d * Math.sin(7 * t),
   };
 }
 var epitrochoid7 = {
@@ -1048,7 +1226,7 @@ var epitrochoid7 = {
   fn: epitrochoid7Fn,
   period: TWO_PI6,
   speed: 1.4,
-  skeletonFn: epitrochoid7SkeletonFn
+  skeletonFn: epitrochoid7SkeletonFn,
 };
 
 // src/curves/lissajous32.ts
@@ -1057,7 +1235,7 @@ function lissajous32Fn(t, time, _params) {
   const phi = time * 0.45;
   return {
     x: Math.sin(3 * t + phi),
-    y: Math.sin(2 * t)
+    y: Math.sin(2 * t),
   };
 }
 var lissajous32 = {
@@ -1065,7 +1243,7 @@ var lissajous32 = {
   fn: lissajous32Fn,
   period: TWO_PI7,
   speed: 2,
-  skeleton: "live"
+  skeleton: "live",
 };
 
 // src/curves/lissajous43.ts
@@ -1074,7 +1252,7 @@ function lissajous43Fn(t, time, _params) {
   const phi = time * 0.38;
   return {
     x: Math.sin(4 * t + phi),
-    y: Math.sin(3 * t)
+    y: Math.sin(3 * t),
   };
 }
 var lissajous43 = {
@@ -1082,17 +1260,18 @@ var lissajous43 = {
   fn: lissajous43Fn,
   period: TWO_PI8,
   speed: 1.8,
-  skeleton: "live"
+  skeleton: "live",
 };
 
 // src/curves/lame.ts
 var TWO_PI9 = Math.PI * 2;
 function lameFn(t, time, _params) {
   const p = 1.75 + 1.25 * Math.sin(time * 0.48);
-  const c = Math.cos(t), s = Math.sin(t);
+  const c = Math.cos(t),
+    s = Math.sin(t);
   return {
     x: Math.sign(c) * Math.pow(Math.abs(c), p),
-    y: Math.sign(s) * Math.pow(Math.abs(s), p)
+    y: Math.sign(s) * Math.pow(Math.abs(s), p),
   };
 }
 var lame = {
@@ -1100,7 +1279,7 @@ var lame = {
   fn: lameFn,
   period: TWO_PI9,
   speed: 1,
-  skeleton: "live"
+  skeleton: "live",
 };
 
 // src/curves/rose3.ts
@@ -1109,14 +1288,14 @@ function rose3Fn(t, _time, _params) {
   const r = Math.cos(3 * t);
   return {
     x: r * Math.cos(t),
-    y: r * Math.sin(t)
+    y: r * Math.sin(t),
   };
 }
 var rose3 = {
   name: "Rose (n=3)",
   fn: rose3Fn,
   period: TWO_PI10,
-  speed: 1.15
+  speed: 1.15,
 };
 
 // src/curves/rose5.ts
@@ -1125,14 +1304,14 @@ function rose5Fn(t, _time, _params) {
   const r = Math.cos(5 * t);
   return {
     x: r * Math.cos(t),
-    y: r * Math.sin(t)
+    y: r * Math.sin(t),
   };
 }
 var rose5 = {
   name: "Rose (n=5)",
   fn: rose5Fn,
   period: TWO_PI11,
-  speed: 1
+  speed: 1,
 };
 
 // src/curves/index.ts
@@ -1146,7 +1325,7 @@ var curves = {
   lissajous32,
   lissajous43,
   epicycloid3,
-  lame
+  lame,
 };
 
 // src/index.ts
@@ -1156,6 +1335,24 @@ function createSarmal(canvas, curveDef, options) {
   return createRenderer({ canvas, engine, ...rendererOpts });
 }
 
-export { artemis2, astroid, createEngine, createRenderer, createSVGRenderer, createSarmal, createSarmalSVG, curves, deltoid, epicycloid3, epitrochoid7, lame, lissajous32, lissajous43, rose3, rose5 };
+export {
+  artemis2,
+  astroid,
+  createEngine,
+  createRenderer,
+  createSVGRenderer,
+  createSarmal,
+  createSarmalSVG,
+  curves,
+  deltoid,
+  epicycloid3,
+  epitrochoid7,
+  lame,
+  lissajous32,
+  lissajous43,
+  palettes,
+  rose3,
+  rose5,
+};
+//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map