@sarmal/core 0.19.0 → 0.22.0

package/dist/index.d.cts

@@ -4,16 +4,16 @@ import {
   S as SarmalInstance,
   C as CurveDef,
   R as RendererOptions,
+  P as Point,
   a as SarmalOptions,
-} from "./types-frtEoAq6.cjs";
+} from "./types-DVerJ9cl.cjs";
 export {
   J as JumpOptions,
-  P as Point,
   b as RuntimeRenderOptions,
   c as SeekOptions,
   T as TrailColor,
   d as TrailStyle,
-} from "./types-frtEoAq6.cjs";
+} from "./types-DVerJ9cl.cjs";
 export { CurveName, curves } from "./curves/index.cjs";
 export { artemis2 } from "./curves/artemis2.cjs";
 export { astroid } from "./curves/astroid.cjs";
@@ -92,6 +92,45 @@ declare function createEngine(curveDef: CurveDef, trailLength?: number): Engine;
  */
 declare function createRenderer(options: RendererOptions): SarmalInstance;
 
+/**
+ * Evaluates a closed Catmull-Rom spline through every point in `points`
+ *
+ * The spline treats `points` as a **closed loop**
+ * The last point wraps back to the first,
+ *  and each segment uses a phantom predecessor / successor so the
+ *    curve passes exactly through every control point.
+ *
+ * @param points  At least 1 point.  An empty array yields `(0, 0)`.  A single point returns that point for every `t`
+ * @param t       Parametric position along the closed loop.  Wraps into `[0, 2π)` automatically, so values outside that range are remapped rather than rejected
+ * @returns       The `(x, y)` position on the spline at time `t`
+ */
+declare function evaluateCatmullRom(points: Array<[number, number]>, t: number): Point;
+/**
+ * The returned curve definition produces a closed Catmull-Rom spline that
+ *  passes through every point in order, looping back from the last point to the first.
+ *
+ * @param points  Array of control points in **normalized `[−1, 1]` space**,
+ *                  matching the playground's draw-mode coordinate system.
+ *                ! Must contain at least 3 points.
+ * @returns       A `CurveDef` with `period: 2π` and the spline evaluator as its `fn`.
+ *                `name` is set to `"custom"`.
+ * @throws        If `points` has fewer than 3 entries.
+ *
+ * @example
+ * ```ts
+ * import { createSarmal, drawCurve } from '@sarmal/core'
+ *
+ * const curve = drawCurve([
+ *   [-0.5,  0.3],
+ *   [ 0.2, -0.8],
+ *   [ 0.7,  0.4],
+ * ])
+ *
+ * createSarmal(canvas, curve)
+ * ```
+ */
+declare function drawCurve(points: Array<[number, number]>): CurveDef;
+
 /**
  * Creates a sarmal animation on a canvas element
  *
@@ -116,6 +155,7 @@ export {
   BaseRendererOptions,
   CurveDef,
   Engine,
+  Point,
   RendererOptions,
   type SVGRendererOptions,
   type SVGSarmalOptions,
@@ -127,5 +167,7 @@ export {
   createSVGRenderer,
   createSarmal,
   createSarmalSVG,
+  drawCurve,
+  evaluateCatmullRom,
   palettes,
 };

package/dist/index.d.ts

@@ -4,16 +4,16 @@ import {
   S as SarmalInstance,
   C as CurveDef,
   R as RendererOptions,
+  P as Point,
   a as SarmalOptions,
-} from "./types-frtEoAq6.js";
+} from "./types-DVerJ9cl.js";
 export {
   J as JumpOptions,
-  P as Point,
   b as RuntimeRenderOptions,
   c as SeekOptions,
   T as TrailColor,
   d as TrailStyle,
-} from "./types-frtEoAq6.js";
+} from "./types-DVerJ9cl.js";
 export { CurveName, curves } from "./curves/index.js";
 export { artemis2 } from "./curves/artemis2.js";
 export { astroid } from "./curves/astroid.js";
@@ -92,6 +92,45 @@ declare function createEngine(curveDef: CurveDef, trailLength?: number): Engine;
  */
 declare function createRenderer(options: RendererOptions): SarmalInstance;
 
+/**
+ * Evaluates a closed Catmull-Rom spline through every point in `points`
+ *
+ * The spline treats `points` as a **closed loop**
+ * The last point wraps back to the first,
+ *  and each segment uses a phantom predecessor / successor so the
+ *    curve passes exactly through every control point.
+ *
+ * @param points  At least 1 point.  An empty array yields `(0, 0)`.  A single point returns that point for every `t`
+ * @param t       Parametric position along the closed loop.  Wraps into `[0, 2π)` automatically, so values outside that range are remapped rather than rejected
+ * @returns       The `(x, y)` position on the spline at time `t`
+ */
+declare function evaluateCatmullRom(points: Array<[number, number]>, t: number): Point;
+/**
+ * The returned curve definition produces a closed Catmull-Rom spline that
+ *  passes through every point in order, looping back from the last point to the first.
+ *
+ * @param points  Array of control points in **normalized `[−1, 1]` space**,
+ *                  matching the playground's draw-mode coordinate system.
+ *                ! Must contain at least 3 points.
+ * @returns       A `CurveDef` with `period: 2π` and the spline evaluator as its `fn`.
+ *                `name` is set to `"custom"`.
+ * @throws        If `points` has fewer than 3 entries.
+ *
+ * @example
+ * ```ts
+ * import { createSarmal, drawCurve } from '@sarmal/core'
+ *
+ * const curve = drawCurve([
+ *   [-0.5,  0.3],
+ *   [ 0.2, -0.8],
+ *   [ 0.7,  0.4],
+ * ])
+ *
+ * createSarmal(canvas, curve)
+ * ```
+ */
+declare function drawCurve(points: Array<[number, number]>): CurveDef;
+
 /**
  * Creates a sarmal animation on a canvas element
  *
@@ -116,6 +155,7 @@ export {
   BaseRendererOptions,
   CurveDef,
   Engine,
+  Point,
   RendererOptions,
   type SVGRendererOptions,
   type SVGSarmalOptions,
@@ -127,5 +167,7 @@ export {
   createSVGRenderer,
   createSarmal,
   createSarmalSVG,
+  drawCurve,
+  evaluateCatmullRom,
   palettes,
 };

package/dist/index.js

@@ -426,6 +426,7 @@ var RENDER_OPTION_KEYS = /* @__PURE__ */ new Set([
   "headColor",
   "skeletonColor",
   "trailStyle",
+  "headRadius",
 ]);
 function validateRenderOptions(partial) {
   for (const key of Object.keys(partial)) {
@@ -445,6 +446,9 @@ function validateRenderOptions(partial) {
   if (partial.trailStyle !== void 0) {
     assertTrailStyle(partial.trailStyle);
   }
+  if (partial.headRadius !== void 0) {
+    assertHeadRadius(partial.headRadius);
+  }
 }
 function assertTrailColor(value) {
   if (typeof value === "string") {
@@ -502,6 +506,18 @@ function assertTrailStyle(value) {
     );
   }
 }
+function assertHeadRadius(value) {
+  if (typeof value !== "number") {
+    throw new TypeError(
+      `[sarmal] setRenderOptions: headRadius must be a number, got ${JSON.stringify(value)}`,
+    );
+  }
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new TypeError(
+      `[sarmal] setRenderOptions: headRadius must be a finite positive number, got ${value}`,
+    );
+  }
+}
 function resolveTrailMainColor(trailColor) {
   return typeof trailColor === "string" ? trailColor : trailColor[0];
 }
@@ -569,6 +585,7 @@ function createRenderer(options) {
   setupCanvas();
   let logicalWidth = canvas.width / dpr;
   let logicalHeight = canvas.height / dpr;
+  let headRadius = options.headRadius ?? getHeadDotRadius(logicalWidth, logicalHeight);
   let skeleton = [];
   let skeletonCanvas = null;
   let trail = [];
@@ -685,7 +702,7 @@ function createRenderer(options) {
     }
     const x = head.x * scale + offsetX;
     const y = head.y * scale + offsetY;
-    const r = options.headRadius ?? getHeadDotRadius(logicalWidth, logicalHeight);
+    const r = headRadius;
     ctx.fillStyle = headColor;
     ctx.beginPath();
     ctx.arc(x, y, r, 0, Math.PI * 2);
@@ -814,6 +831,9 @@ function createRenderer(options) {
       if (partial.headColor !== void 0) {
         userHeadColor = partial.headColor;
       }
+      if (partial.headRadius !== void 0) {
+        headRadius = partial.headRadius;
+      }
       if (userHeadColor === null) {
         headColor = resolveHeadColor(trailColor, trailStyle);
       } else {
@@ -871,12 +891,12 @@ function createSVGRenderer(options) {
   let skeletonColor = options.skeletonColor ?? "#ffffff";
   let userHeadColor = options.headColor ?? null;
   let headColor = userHeadColor ?? resolveHeadColor(trailColor, trailStyle);
+  let headRadius = options.headRadius ?? 1.5;
   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";
@@ -1152,6 +1172,10 @@ function createSVGRenderer(options) {
       if (partial.headColor !== void 0) {
         userHeadColor = partial.headColor;
       }
+      if (partial.headRadius !== void 0) {
+        headRadius = partial.headRadius;
+        headCircle.setAttribute("r", String(headRadius));
+      }
       if (userHeadColor === null) {
         headColor = resolveHeadColor(trailColor, trailStyle);
       } else {
@@ -1442,6 +1466,55 @@ var curves = {
   lame,
 };
 
+// src/catmull-rom.ts
+var PERIOD = 2 * Math.PI;
+function catmullRom1D(p0, p1, p2, p3, u) {
+  const u2 = u * u;
+  const u3 = u2 * u;
+  return (
+    0.5 *
+    (2 * p1 +
+      (-p0 + p2) * u +
+      (2 * p0 - 5 * p1 + 4 * p2 - p3) * u2 +
+      (-p0 + 3 * p1 - 3 * p2 + p3) * u3)
+  );
+}
+function evaluateCatmullRom(points, t) {
+  const N = points.length;
+  if (N === 0) {
+    return { x: 0, y: 0 };
+  }
+  if (N === 1) {
+    return { x: points[0][0], y: points[0][1] };
+  }
+  t = ((t % PERIOD) + PERIOD) % PERIOD;
+  const segmentSize = PERIOD / N;
+  let i = Math.floor(t / segmentSize);
+  if (i >= N) {
+    i = N - 1;
+  }
+  let u = (t - i * segmentSize) / segmentSize;
+  u = Math.max(0, Math.min(1, u));
+  const p0 = points[(i - 1 + N) % N];
+  const p1 = points[i];
+  const p2 = points[(i + 1) % N];
+  const p3 = points[(i + 2) % N];
+  return {
+    x: catmullRom1D(p0[0], p1[0], p2[0], p3[0], u),
+    y: catmullRom1D(p0[1], p1[1], p2[1], p3[1], u),
+  };
+}
+function drawCurve(points) {
+  if (points.length < 3) {
+    throw new Error(`drawCurve requires at least 3 points, received ${points.length}.`);
+  }
+  return {
+    name: "custom",
+    fn: (t) => evaluateCatmullRom(points, t),
+    period: PERIOD,
+  };
+}
+
 // src/index.ts
 function createSarmal(canvas, curveDef, options) {
   const { trailLength, ...rendererOpts } = options ?? {};
@@ -1459,8 +1532,10 @@ export {
   createSarmalSVG,
   curves,
   deltoid,
+  drawCurve,
   epicycloid3,
   epitrochoid7,
+  evaluateCatmullRom,
   lame,
   lissajous32,
   lissajous43,