@sarmal/core 0.18.0 → 0.20.0

package/README.md

@@ -62,18 +62,7 @@ Or with **auto-init** without having to write any JS:
 
 ## Standard Curves
 
-| Name           | Description                                |
-| -------------- | ------------------------------------------ |
-| `artemis2`     | Artemis II free-return lunar trajectory    |
-| `epitrochoid7` | 7-lobed epitrochoid with dynamic variation |
-| `astroid`      | 4-cusped astroid                           |
-| `deltoid`      | 3-cusped deltoid                           |
-| `rose5`        | 5-petal rose curve                         |
-| `rose3`        | 3-petal rose curve                         |
-| `lissajous32`  | Lissajous 3:2 with live skeleton           |
-| `lissajous43`  | Lissajous 4:3 with live skeleton           |
-| `epicycloid3`  | 3-cusped epicycloid                        |
-| `lame`         | Lamé curve with live skeleton              |
+See [sarmal.art/docs#curves](https://sarmal.art/docs#curves) for the full list of built-in curves.
 
 ## Documentation
 

package/dist/auto-init.cjs

@@ -300,12 +300,20 @@ function computeNormal(trail, i) {
   const tangent = computeTangent(trail, i);
   return { x: -tangent.y, y: tangent.x };
 }
-function computeTrailQuad(trail, i, trailCount, toX, toY) {
+function computeTrailQuad(
+  trail,
+  i,
+  trailCount,
+  toX,
+  toY,
+  minWidth = TRAIL_MIN_WIDTH,
+  maxWidth = TRAIL_MAX_WIDTH,
+) {
   const progress = i / (trailCount - 1);
   const nextProgress = (i + 1) / (trailCount - 1);
   const opacity = Math.pow(progress, TRAIL_FADE_CURVE) * TRAIL_MAX_OPACITY;
-  const w0 = (TRAIL_MIN_WIDTH + progress * (TRAIL_MAX_WIDTH - TRAIL_MIN_WIDTH)) / 2;
-  const w1 = (TRAIL_MIN_WIDTH + nextProgress * (TRAIL_MAX_WIDTH - TRAIL_MIN_WIDTH)) / 2;
+  const w0 = (minWidth + progress * (maxWidth - minWidth)) / 2;
+  const w1 = (minWidth + nextProgress * (maxWidth - minWidth)) / 2;
   const curr = trail[i];
   const next = trail[i + 1];
   const n0 = computeNormal(trail, i);
@@ -816,6 +824,350 @@ function createRenderer(options) {
   return instance;
 }
 
+// src/renderer-svg.ts
+var EMPTY_PARAMS2 = {};
+var HIGH_TRAIL_LENGTH_THRESHOLD = 5e3;
+function pointsToPathString(pts, scale, offsetX, offsetY) {
+  if (pts.length < 2) {
+    return "";
+  }
+  const px = (p) => (p.x * scale + offsetX).toFixed(2);
+  const py = (p) => (p.y * scale + offsetY).toFixed(2);
+  let d = `M${px(pts[0])} ${py(pts[0])}`;
+  for (let i = 1; i < pts.length; i++) {
+    d += ` L${px(pts[i])} ${py(pts[i])}`;
+  }
+  return d + " Z";
+}
+function sampleCurveSkeleton(curveDef) {
+  const period = curveDef.period ?? Math.PI * 2;
+  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;
+    pts[i] = curveDef.skeletonFn ? curveDef.skeletonFn(t) : curveDef.fn(t, 0, EMPTY_PARAMS2);
+  }
+  return pts;
+}
+function el(tag) {
+  return document.createElementNS("http://www.w3.org/2000/svg", tag);
+}
+function createSVGRenderer(options) {
+  const { container, engine } = options;
+  const poolSize = engine.trailLength;
+  if (poolSize > HIGH_TRAIL_LENGTH_THRESHOLD) {
+    console.warn(
+      `[sarmal] High trailLength in SVG renderer (${poolSize}). Consider using the canvas renderer for long trails.`,
+    );
+  }
+  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 viewSize = 100;
+  const headRadius = options.headRadius ?? 1.5;
+  const svgTrailMinWidth = 0.25;
+  const svgTrailMaxWidth = 1.25;
+  const svgSkeletonStrokeWidth = "0.75";
+  container.setAttribute("viewBox", `0 0 ${viewSize} ${viewSize}`);
+  container.setAttribute("role", "img");
+  container.setAttribute("aria-label", ariaLabel);
+  const group = el("g");
+  const titleEl = el("title");
+  titleEl.textContent = ariaLabel;
+  group.appendChild(titleEl);
+  const skeletonPath = el("path");
+  skeletonPath.setAttribute("data-sarmal-role", "skeleton");
+  skeletonPath.setAttribute("fill", "none");
+  skeletonPath.setAttribute("stroke", skeletonColor);
+  skeletonPath.setAttribute("stroke-opacity", String(DEFAULT_SKELETON_OPACITY));
+  skeletonPath.setAttribute("stroke-width", svgSkeletonStrokeWidth);
+  if (skeletonColor === "transparent") {
+    skeletonPath.setAttribute("visibility", "hidden");
+  }
+  group.appendChild(skeletonPath);
+  const skeletonPathA = el("path");
+  skeletonPathA.setAttribute("fill", "none");
+  skeletonPathA.setAttribute("stroke", skeletonColor);
+  skeletonPathA.setAttribute("stroke-width", svgSkeletonStrokeWidth);
+  skeletonPathA.setAttribute("visibility", "hidden");
+  group.appendChild(skeletonPathA);
+  const skeletonPathB = el("path");
+  skeletonPathB.setAttribute("fill", "none");
+  skeletonPathB.setAttribute("stroke", skeletonColor);
+  skeletonPathB.setAttribute("stroke-width", svgSkeletonStrokeWidth);
+  skeletonPathB.setAttribute("visibility", "hidden");
+  group.appendChild(skeletonPathB);
+  let morphPathABuilt = "";
+  let morphPathBBuilt = "";
+  const trailPaths = [];
+  for (let i = 0; i < poolSize; i++) {
+    const path = el("path");
+    path.setAttribute("fill", trailSolid);
+    group.appendChild(path);
+    trailPaths.push(path);
+  }
+  const headCircle = el("circle");
+  headCircle.setAttribute("data-sarmal-role", "head");
+  headCircle.setAttribute("fill", headColor);
+  headCircle.setAttribute("r", String(headRadius));
+  group.appendChild(headCircle);
+  container.appendChild(group);
+  let gradientAnimTime = 0;
+  let scale = 1;
+  let offsetX = 0;
+  let offsetY = 0;
+  function applyBoundaries(skeleton2) {
+    const b = computeBoundaries(skeleton2, viewSize, viewSize);
+    if (b) {
+      scale = b.scale;
+      offsetX = b.offsetX;
+      offsetY = b.offsetY;
+    }
+  }
+  function px(p) {
+    return p.x * scale + offsetX;
+  }
+  function py(p) {
+    return p.y * scale + offsetY;
+  }
+  function updateSkeleton(skeleton2) {
+    skeletonPath.setAttribute("d", pointsToPathString(skeleton2, scale, offsetX, offsetY));
+  }
+  const skeleton = engine.getSarmalSkeleton();
+  applyBoundaries(skeleton);
+  if (!engine.isLiveSkeleton) {
+    updateSkeleton(skeleton);
+  }
+  function updateTrail(trail, trailCount) {
+    if (trailCount < 2) {
+      for (const p of trailPaths) {
+        p.setAttribute("d", "");
+      }
+      return;
+    }
+    const drawnCount = trailCount - 1;
+    for (let i = 0; i < drawnCount; i++) {
+      const { l0x, l0y, r0x, r0y, l1x, l1y, r1x, r1y, opacity, progress } = computeTrailQuad(
+        trail,
+        i,
+        trailCount,
+        px,
+        py,
+        svgTrailMinWidth,
+        svgTrailMaxWidth,
+      );
+      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(trailPalette, progress, timeOffset);
+        trailPaths[i].setAttribute("fill", `rgb(${r},${g},${b})`);
+      }
+    }
+    for (let i = drawnCount; i < trailPaths.length; i++) {
+      trailPaths[i].setAttribute("d", "");
+    }
+  }
+  function updateHead(trail, trailCount) {
+    if (trailCount === 0) {
+      return;
+    }
+    const head = trail[trailCount - 1];
+    const x = px(head);
+    const y = py(head);
+    headCircle.setAttribute("cx", String(x));
+    headCircle.setAttribute("cy", String(y));
+  }
+  let animationId = null;
+  let lastTime = 0;
+  const prefersReducedMotion =
+    typeof window !== "undefined" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  let morphResolve = null;
+  let morphReject = null;
+  let morphDurationMs = DEFAULT_MORPH_DURATION_MS;
+  let morphTarget = null;
+  let morphAlpha = 0;
+  function renderFrame(deltaTime) {
+    if (trailStyle === "gradient-animated") {
+      gradientAnimTime += deltaTime * 1e3;
+    }
+    if (engine.morphAlpha !== null) {
+      morphAlpha = Math.min(1, morphAlpha + deltaTime / (morphDurationMs / 1e3));
+      engine.setMorphAlpha(morphAlpha);
+      if (morphPathABuilt) {
+        skeletonPathA.setAttribute("d", morphPathABuilt);
+        skeletonPathA.setAttribute("visibility", "visible");
+        skeletonPathA.setAttribute(
+          "stroke-opacity",
+          String((1 - morphAlpha) * DEFAULT_SKELETON_OPACITY),
+        );
+      }
+      if (morphPathBBuilt) {
+        skeletonPathB.setAttribute("d", morphPathBBuilt);
+        skeletonPathB.setAttribute("visibility", "visible");
+        skeletonPathB.setAttribute("stroke-opacity", String(morphAlpha * DEFAULT_SKELETON_OPACITY));
+      }
+      if (morphAlpha >= 1) {
+        engine.completeMorph();
+        morphResolve?.();
+        morphResolve = null;
+        morphReject = null;
+        morphTarget = null;
+        morphAlpha = 0;
+        morphPathABuilt = "";
+        morphPathBBuilt = "";
+        skeletonPathA.setAttribute("visibility", "hidden");
+        skeletonPathB.setAttribute("visibility", "hidden");
+        const newSkeleton = engine.getSarmalSkeleton();
+        applyBoundaries(newSkeleton);
+        updateSkeleton(newSkeleton);
+      }
+    }
+    const trail = engine.tick(deltaTime);
+    const trailCount = engine.trailCount;
+    if (engine.isLiveSkeleton && engine.morphAlpha === null) {
+      const liveSkeleton = engine.getSarmalSkeleton();
+      applyBoundaries(liveSkeleton);
+      updateSkeleton(liveSkeleton);
+    }
+    updateTrail(trail, trailCount);
+    updateHead(trail, trailCount);
+  }
+  function loop() {
+    const now = performance.now();
+    const deltaTime = Math.min((now - lastTime) / 1e3, 1 / 30);
+    lastTime = now;
+    renderFrame(deltaTime);
+    if (!prefersReducedMotion) {
+      animationId = requestAnimationFrame(loop);
+    }
+  }
+  if (options.initialT !== void 0) {
+    engine.seek(options.initialT);
+  }
+  renderFrame(0);
+  const shouldAutoStart = options.autoStart !== false;
+  const instance = {
+    play() {
+      if (animationId !== null) {
+        return;
+      }
+      lastTime = performance.now();
+      loop();
+    },
+    pause() {
+      if (animationId === null) {
+        return;
+      }
+      cancelAnimationFrame(animationId);
+      animationId = null;
+      engine.cancelSpeedTransition();
+    },
+    reset() {
+      engine.reset();
+    },
+    destroy() {
+      if (animationId !== null) {
+        cancelAnimationFrame(animationId);
+        animationId = null;
+      }
+      if (morphReject !== null) {
+        morphReject(new Error("Instance destroyed during morph"));
+        morphResolve = null;
+        morphReject = null;
+      }
+      group.remove();
+    },
+    ...enginePassthroughs(engine),
+    morphTo(target, options2) {
+      if (morphResolve !== null) {
+        engine.completeMorph();
+        morphResolve();
+        morphResolve = null;
+        morphReject = null;
+        morphAlpha = 0;
+        skeletonPathA.setAttribute("visibility", "hidden");
+        skeletonPathB.setAttribute("visibility", "hidden");
+      }
+      morphDurationMs = options2?.duration ?? DEFAULT_MORPH_DURATION_MS;
+      morphTarget = target;
+      morphAlpha = 0;
+      const currentSkeleton = engine.getSarmalSkeleton();
+      morphPathABuilt = pointsToPathString(currentSkeleton, scale, offsetX, offsetY);
+      engine.startMorph(target, options2?.morphStrategy);
+      if (morphTarget) {
+        const targetSkeleton = sampleCurveSkeleton(target);
+        morphPathBBuilt = pointsToPathString(targetSkeleton, scale, offsetX, offsetY);
+      }
+      return new Promise((resolve, reject) => {
+        morphResolve = resolve;
+        morphReject = reject;
+      });
+    },
+    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();
+  }
+  return instance;
+}
+function createSarmalSVG(container, curveDef, options) {
+  const { trailLength, ...rendererOpts } = options ?? {};
+  const engine = createEngine(curveDef, trailLength);
+  return createSVGRenderer({ container, engine, ...rendererOpts });
+}
+
 // src/curves/artemis2.ts
 var TWO_PI2 = Math.PI * 2;
 function artemis2Fn(t, _time, _params) {
@@ -1101,10 +1453,24 @@ function parseTrailColor(value) {
   } catch {}
   return value;
 }
+function buildOptions(el2) {
+  return {
+    ...(el2.dataset.trailColor && {
+      trailColor: parseTrailColor(el2.dataset.trailColor),
+    }),
+    ...(el2.dataset.skeletonColor && { skeletonColor: el2.dataset.skeletonColor }),
+    ...(el2.dataset.headColor && { headColor: el2.dataset.headColor }),
+    ...(el2.dataset.headRadius && { headRadius: parseFloat(el2.dataset.headRadius) }),
+    ...(el2.dataset.trailLength && { trailLength: parseInt(el2.dataset.trailLength, 10) }),
+    ...(el2.dataset.trailStyle && {
+      trailStyle: el2.dataset.trailStyle,
+    }),
+  };
+}
 function init() {
-  const canvases = document.querySelectorAll("canvas[data-sarmal]");
-  canvases.forEach((canvas) => {
-    const curveName = canvas.getAttribute("data-sarmal");
+  const elements = document.querySelectorAll("canvas[data-sarmal], svg[data-sarmal]");
+  elements.forEach((el2) => {
+    const curveName = el2.getAttribute("data-sarmal");
     if (curveName == null) {
       return console.warn("[sarmal] curveName is required");
     }
@@ -1112,20 +1478,13 @@ function init() {
     if (!curveDef) {
       return console.error(`[sarmal] "${curveName}" is not a valid curve name`);
     }
-    const instance = createSarmal(canvas, curveDef, {
-      ...(canvas.dataset.trailColor && {
-        trailColor: parseTrailColor(canvas.dataset.trailColor),
-      }),
-      ...(canvas.dataset.skeletonColor && { skeletonColor: canvas.dataset.skeletonColor }),
-      ...(canvas.dataset.headColor && { headColor: canvas.dataset.headColor }),
-      ...(canvas.dataset.headRadius && { headRadius: parseFloat(canvas.dataset.headRadius) }),
-      ...(canvas.dataset.trailLength && { trailLength: parseInt(canvas.dataset.trailLength, 10) }),
-      ...(canvas.dataset.trailStyle && {
-        trailStyle: canvas.dataset.trailStyle,
-      }),
-    });
-    if (canvas.dataset.speed) {
-      instance.setSpeed(parseFloat(canvas.dataset.speed));
+    const options = buildOptions(el2);
+    const instance =
+      el2 instanceof HTMLCanvasElement
+        ? createSarmal(el2, curveDef, options)
+        : createSarmalSVG(el2, curveDef, options);
+    if (el2.dataset.speed) {
+      instance.setSpeed(parseFloat(el2.dataset.speed));
     }
   });
 }