@sarmal/core 0.25.0 → 0.26.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { B as BaseRendererOptions, E as Engine, S as SarmalInstance, C as CurveDef, P as Point, R as RendererOptions, a as ControlPoint, b as SarmalOptions } from './types-BZpzgNau.cjs';
-export { J as JumpOptions, c as RuntimeRenderOptions, d as SeekOptions, T as TrailColor, e as TrailStyle } from './types-BZpzgNau.cjs';
+import { B as BaseRendererOptions, E as Engine, S as SarmalInstance, C as CurveDef, P as Point, R as RendererOptions, a as ControlPoint, b as SarmalOptions } from './types-zbxUgcmZ.cjs';
+export { J as JumpOptions, c as RuntimeRenderOptions, d as SeekOptions, T as TrailColor, e as TrailStyle } from './types-zbxUgcmZ.cjs';
 export { CurveName, curves } from './curves/index.cjs';
 export { artemis2 } from './curves/artemis2.cjs';
 export { astroid } from './curves/astroid.cjs';
@@ -97,11 +97,11 @@ declare function createRenderer(options: RendererOptions): SarmalInstance;
  *  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`
+ * @param points  At least 1 point.  An empty array yields `(0, 0)`.  A single point returns that point for every `phase`
+ * @param phase   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 position `phase`
  */
-declare function evaluateCatmullRom(points: Array<ControlPoint>, t: number): Point;
+declare function evaluateCatmullRom(points: Array<ControlPoint>, phase: 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.
@@ -111,7 +111,7 @@ declare function evaluateCatmullRom(points: Array<ControlPoint>, t: number): Poi
  *                ! Must contain at least 3 points.
  * @param opts    Optional overrides for the returned `CurveDef`.
  * @param opts.name  Display name for the curve. Defaults to `"drawn"`.
- * @returns       A `CurveDef` with `period: 2π`, `kind: "drawn"`, and the spline evaluator as its `fn`.
+ * @returns       A `CurveDef` with `period: 2π` and the spline evaluator as its `fn`.
  * @throws        If `points` has fewer than 3 entries.
  *
  * @example

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { B as BaseRendererOptions, E as Engine, S as SarmalInstance, C as CurveDef, P as Point, R as RendererOptions, a as ControlPoint, b as SarmalOptions } from './types-BZpzgNau.js';
-export { J as JumpOptions, c as RuntimeRenderOptions, d as SeekOptions, T as TrailColor, e as TrailStyle } from './types-BZpzgNau.js';
+import { B as BaseRendererOptions, E as Engine, S as SarmalInstance, C as CurveDef, P as Point, R as RendererOptions, a as ControlPoint, b as SarmalOptions } from './types-zbxUgcmZ.js';
+export { J as JumpOptions, c as RuntimeRenderOptions, d as SeekOptions, T as TrailColor, e as TrailStyle } from './types-zbxUgcmZ.js';
 export { CurveName, curves } from './curves/index.js';
 export { artemis2 } from './curves/artemis2.js';
 export { astroid } from './curves/astroid.js';
@@ -97,11 +97,11 @@ declare function createRenderer(options: RendererOptions): SarmalInstance;
  *  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`
+ * @param points  At least 1 point.  An empty array yields `(0, 0)`.  A single point returns that point for every `phase`
+ * @param phase   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 position `phase`
  */
-declare function evaluateCatmullRom(points: Array<ControlPoint>, t: number): Point;
+declare function evaluateCatmullRom(points: Array<ControlPoint>, phase: 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.
@@ -111,7 +111,7 @@ declare function evaluateCatmullRom(points: Array<ControlPoint>, t: number): Poi
  *                ! Must contain at least 3 points.
  * @param opts    Optional overrides for the returned `CurveDef`.
  * @param opts.name  Display name for the curve. Defaults to `"drawn"`.
- * @returns       A `CurveDef` with `period: 2π`, `kind: "drawn"`, and the spline evaluator as its `fn`.
+ * @returns       A `CurveDef` with `period: 2π` and the spline evaluator as its `fn`.
  * @throws        If `points` has fewer than 3 entries.
  *
  * @example

package/dist/index.js

@@ -72,21 +72,21 @@ function createEngine(curveDef, trailLength = 120) {
   }
   let curve = resolveCurve(curveDef);
   const trail = new CircularBuffer(trailLength);
-  let t = 0;
+  let phase = 0;
   let actualTime = 0;
   let userSpeedOverride = null;
   let morphCurveB = null;
   let _morphAlpha = null;
   let _morphStrategy = "normalized";
   let _speedTransition = null;
-  function sampleSkeleton(c, sampleT) {
+  function sampleSkeleton(c, samplePhase) {
     if (c.skeletonFn) {
-      return c.skeletonFn(sampleT);
+      return c.skeletonFn(samplePhase);
     }
     if (c.skeleton === "live") {
-      return c.fn(sampleT, actualTime, EMPTY_PARAMS);
+      return c.fn(samplePhase, actualTime, EMPTY_PARAMS);
     }
-    return c.fn(sampleT, 0, EMPTY_PARAMS);
+    return c.fn(samplePhase, 0, EMPTY_PARAMS);
   }
   return {
     tick(deltaTime) {
@@ -104,15 +104,15 @@ function createEngine(curveDef, trailLength = 120) {
       if (morphCurveB !== null && _morphAlpha !== null) {
         effectiveSpeed = lerp(effectiveSpeed, morphCurveB.speed, _morphAlpha);
       }
-      t = (t + effectiveSpeed * deltaTime) % curve.period;
+      phase = (phase + effectiveSpeed * deltaTime) % curve.period;
       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 b = morphCurveB.fn(tB, actualTime, EMPTY_PARAMS);
+        const a = curve.fn(phase, actualTime, EMPTY_PARAMS);
+        const phaseB = _morphStrategy === "normalized" ? phase / curve.period * morphCurveB.period : phase;
+        const b = morphCurveB.fn(phaseB, actualTime, EMPTY_PARAMS);
         trail.push(a.x + (b.x - a.x) * _morphAlpha, a.y + (b.y - a.y) * _morphAlpha);
       } else {
-        const point = curve.fn(t, actualTime, EMPTY_PARAMS);
+        const point = curve.fn(phase, actualTime, EMPTY_PARAMS);
         trail.push(point.x, point.y);
       }
       return trail.toArray();
@@ -130,30 +130,30 @@ function createEngine(curveDef, trailLength = 120) {
       return _morphAlpha;
     },
     reset() {
-      t = 0;
+      phase = 0;
       actualTime = 0;
       trail.clear();
     },
-    jump(newT, { clearTrail = false } = {}) {
-      t = (newT % curve.period + curve.period) % curve.period;
+    jump(newPhase, { clearTrail = false } = {}) {
+      phase = (newPhase % curve.period + curve.period) % curve.period;
       if (clearTrail) {
         trail.clear();
       }
     },
-    seek(targetT, { wrap = false, step = curve.period / trailLength } = {}) {
+    seek(targetPhase, { wrap = false, step = curve.period / trailLength } = {}) {
       const advance = curve.speed * step;
-      const target = (targetT % curve.period + curve.period) % curve.period;
+      const target = (targetPhase % curve.period + curve.period) % curve.period;
       const targetTime = target / curve.speed;
-      t = target;
+      phase = target;
       actualTime = targetTime;
       trail.clear();
       const pointsFromStart = Math.floor(target / advance) + 1;
       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 time = targetTime - i * step;
-        const point = curve.fn(wrappedT, time, EMPTY_PARAMS);
+        const samplePhase = target - i * advance;
+        const wrappedPhase = (samplePhase % curve.period + curve.period) % curve.period;
+        const elapsed = targetTime - i * step;
+        const point = curve.fn(wrappedPhase, elapsed, EMPTY_PARAMS);
         trail.push(point.x, point.y);
       }
     },
@@ -166,10 +166,10 @@ function createEngine(curveDef, trailLength = 120) {
         const frozenStrategy = _morphStrategy;
         curve = {
           ...frozenB,
-          fn: (sampleT, time, params) => {
-            const a = frozenA.fn(sampleT, time, params);
-            const tB = frozenStrategy === "normalized" ? sampleT / frozenA.period * frozenB.period : sampleT;
-            const b = frozenB.fn(tB, time, params);
+          fn: (samplePhase, elapsed, params) => {
+            const a = frozenA.fn(samplePhase, elapsed, params);
+            const phaseB = frozenStrategy === "normalized" ? samplePhase / frozenA.period * frozenB.period : samplePhase;
+            const b = frozenB.fn(phaseB, elapsed, params);
             return {
               x: a.x + (b.x - a.x) * frozenAlpha,
               y: a.y + (b.y - a.y) * frozenAlpha
@@ -187,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;
+          phase = phase / curve.period * morphCurveB.period;
         }
         curve = morphCurveB;
       }
@@ -199,10 +199,10 @@ function createEngine(curveDef, trailLength = 120) {
       const points2 = new Array(steps);
       if (morphCurveB !== null && _morphAlpha !== null) {
         for (let i = 0; i < steps; i++) {
-          const sampleT = i / (steps - 1) * curve.period;
-          const a = sampleSkeleton(curve, sampleT);
-          const tB = _morphStrategy === "normalized" ? sampleT / curve.period * morphCurveB.period : sampleT;
-          const b = sampleSkeleton(morphCurveB, tB);
+          const samplePhase = i / (steps - 1) * curve.period;
+          const a = sampleSkeleton(curve, samplePhase);
+          const phaseB = _morphStrategy === "normalized" ? samplePhase / curve.period * morphCurveB.period : samplePhase;
+          const b = sampleSkeleton(morphCurveB, phaseB);
           points2[i] = {
             x: a.x + (b.x - a.x) * _morphAlpha,
             y: a.y + (b.y - a.y) * _morphAlpha
@@ -211,8 +211,8 @@ function createEngine(curveDef, trailLength = 120) {
         return points2;
       }
       for (let i = 0; i < steps; i++) {
-        const sampleT = i / (steps - 1) * curve.period;
-        points2[i] = sampleSkeleton(curve, sampleT);
+        const samplePhase = i / (steps - 1) * curve.period;
+        points2[i] = sampleSkeleton(curve, samplePhase);
       }
       return points2;
     },
@@ -743,8 +743,8 @@ function createRenderer(options) {
   if (!engine.isLiveSkeleton) {
     buildSkeletonCanvas();
   }
-  if (options.initialT !== void 0) {
-    engine.seek(options.initialT);
+  if (options.initialPhase !== void 0) {
+    engine.seek(options.initialPhase);
   }
   renderFrame(0);
   const shouldAutoStart = options.autoStart !== false;
@@ -878,8 +878,8 @@ 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;
-    pts[i] = curveDef.skeletonFn ? curveDef.skeletonFn(t) : curveDef.fn(t, 0, EMPTY_PARAMS2);
+    const phase = i / (samples - 1) * period;
+    pts[i] = curveDef.skeletonFn ? curveDef.skeletonFn(phase) : curveDef.fn(phase, 0, EMPTY_PARAMS2);
   }
   return pts;
 }
@@ -1089,8 +1089,8 @@ function createSVGRenderer(options) {
       animationId = requestAnimationFrame(loop);
     }
   }
-  if (options.initialT !== void 0) {
-    engine.seek(options.initialT);
+  if (options.initialPhase !== void 0) {
+    engine.seek(options.initialPhase);
   }
   renderFrame(0);
   const shouldAutoStart = options.autoStart !== false;
@@ -1240,7 +1240,7 @@ function catmullRom1D(p0, p1, p2, p3, 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(points2, t) {
+function evaluateCatmullRom(points2, phase) {
   const N = points2.length;
   if (N === 0) {
     return { x: 0, y: 0 };
@@ -1248,13 +1248,13 @@ function evaluateCatmullRom(points2, t) {
   if (N === 1) {
     return { x: points2[0][0], y: points2[0][1] };
   }
-  t = (t % PERIOD + PERIOD) % PERIOD;
+  phase = (phase % PERIOD + PERIOD) % PERIOD;
   const segmentSize = PERIOD / N;
-  let i = Math.floor(t / segmentSize);
+  let i = Math.floor(phase / segmentSize);
   if (i >= N) {
     i = N - 1;
   }
-  let u = (t - i * segmentSize) / segmentSize;
+  let u = (phase - i * segmentSize) / segmentSize;
   u = Math.max(0, Math.min(1, u));
   const p0 = points2[(i - 1 + N) % N];
   const p1 = points2[i];
@@ -1284,9 +1284,8 @@ function drawCurve(points2, opts) {
   const pts = points2.map(([x, y]) => [x, y]);
   return {
     name: opts?.name ?? "drawn",
-    fn: (t) => evaluateCatmullRom(pts, t),
-    period: PERIOD,
-    kind: "drawn"
+    fn: (phase) => evaluateCatmullRom(pts, phase),
+    period: PERIOD
   };
 }
 
@@ -1321,9 +1320,9 @@ var artemis2 = {
 
 // src/curves/astroid.ts
 var TWO_PI2 = Math.PI * 2;
-function astroidFn(t, _time, _params) {
-  const c = Math.cos(t);
-  const s = Math.sin(t);
+function astroidFn(phase, _elapsed, _params) {
+  const c = Math.cos(phase);
+  const s = Math.sin(phase);
   return {
     x: c * c * c,
     y: s * s * s
@@ -1338,10 +1337,10 @@ var astroid = {
 
 // src/curves/deltoid.ts
 var TWO_PI3 = Math.PI * 2;
-function deltoidFn(t, _time, _params) {
+function deltoidFn(phase, _elapsed, _params) {
   return {
-    x: 2 * Math.cos(t) + Math.cos(2 * t),
-    y: 2 * Math.sin(t) - Math.sin(2 * t)
+    x: 2 * Math.cos(phase) + Math.cos(2 * phase),
+    y: 2 * Math.sin(phase) - Math.sin(2 * phase)
   };
 }
 var deltoid = {
@@ -1353,10 +1352,10 @@ var deltoid = {
 
 // src/curves/epicycloid3.ts
 var TWO_PI4 = Math.PI * 2;
-function epicycloid3Fn(t, _time, _params) {
+function epicycloid3Fn(phase, _elapsed, _params) {
   return {
-    x: 4 * Math.cos(t) - Math.cos(4 * t),
-    y: 4 * Math.sin(t) - Math.sin(4 * t)
+    x: 4 * Math.cos(phase) - Math.cos(4 * phase),
+    y: 4 * Math.sin(phase) - Math.sin(4 * phase)
   };
 }
 var epicycloid3 = {
@@ -1368,18 +1367,18 @@ var epicycloid3 = {
 
 // src/curves/epitrochoid7.ts
 var TWO_PI5 = Math.PI * 2;
-function epitrochoid7Fn(t, _time, _params) {
-  const d = 1 + 0.55 * Math.sin(t * 0.5);
+function epitrochoid7Fn(phase, _elapsed, _params) {
+  const d = 1 + 0.55 * Math.sin(phase * 0.5);
   return {
-    x: 7 * Math.cos(t) - d * Math.cos(7 * t),
-    y: 7 * Math.sin(t) - d * Math.sin(7 * t)
+    x: 7 * Math.cos(phase) - d * Math.cos(7 * phase),
+    y: 7 * Math.sin(phase) - d * Math.sin(7 * phase)
   };
 }
-function epitrochoid7SkeletonFn(t) {
+function epitrochoid7SkeletonFn(phase) {
   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)
+    x: 7 * Math.cos(phase) - d * Math.cos(7 * phase),
+    y: 7 * Math.sin(phase) - d * Math.sin(7 * phase)
   };
 }
 var epitrochoid7 = {
@@ -1392,11 +1391,11 @@ var epitrochoid7 = {
 
 // src/curves/lissajous32.ts
 var TWO_PI6 = Math.PI * 2;
-function lissajous32Fn(t, time, _params) {
-  const phi = time * 0.45;
+function lissajous32Fn(phase, elapsed, _params) {
+  const phi = elapsed * 0.45;
   return {
-    x: Math.sin(3 * t + phi),
-    y: Math.sin(2 * t)
+    x: Math.sin(3 * phase + phi),
+    y: Math.sin(2 * phase)
   };
 }
 var lissajous32 = {
@@ -1409,11 +1408,11 @@ var lissajous32 = {
 
 // src/curves/lissajous43.ts
 var TWO_PI7 = Math.PI * 2;
-function lissajous43Fn(t, time, _params) {
-  const phi = time * 0.38;
+function lissajous43Fn(phase, elapsed, _params) {
+  const phi = elapsed * 0.38;
   return {
-    x: Math.sin(4 * t + phi),
-    y: Math.sin(3 * t)
+    x: Math.sin(4 * phase + phi),
+    y: Math.sin(3 * phase)
   };
 }
 var lissajous43 = {
@@ -1426,9 +1425,9 @@ var lissajous43 = {
 
 // src/curves/lame.ts
 var TWO_PI8 = 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);
+function lameFn(phase, elapsed, _params) {
+  const p = 1.75 + 1.25 * Math.sin(elapsed * 0.48);
+  const c = Math.cos(phase), s = Math.sin(phase);
   return {
     x: Math.sign(c) * Math.pow(Math.abs(c), p),
     y: Math.sign(s) * Math.pow(Math.abs(s), p)
@@ -1444,11 +1443,11 @@ var lame = {
 
 // src/curves/rose3.ts
 var TWO_PI9 = Math.PI * 2;
-function rose3Fn(t, _time, _params) {
-  const r = Math.cos(3 * t);
+function rose3Fn(phase, _elapsed, _params) {
+  const r = Math.cos(3 * phase);
   return {
-    x: r * Math.cos(t),
-    y: r * Math.sin(t)
+    x: r * Math.cos(phase),
+    y: r * Math.sin(phase)
   };
 }
 var rose3 = {
@@ -1460,11 +1459,11 @@ var rose3 = {
 
 // src/curves/rose5.ts
 var TWO_PI10 = Math.PI * 2;
-function rose5Fn(t, _time, _params) {
-  const r = Math.cos(5 * t);
+function rose5Fn(phase, _elapsed, _params) {
+  const r = Math.cos(5 * phase);
   return {
-    x: r * Math.cos(t),
-    y: r * Math.sin(t)
+    x: r * Math.cos(phase),
+    y: r * Math.sin(phase)
   };
 }
 var rose5 = {
@@ -1476,11 +1475,11 @@ var rose5 = {
 
 // src/curves/rose52.ts
 var FOUR_PI = Math.PI * 4;
-function rose52Fn(t, _time, _params) {
-  const r = Math.cos(5 / 2 * t);
+function rose52Fn(phase, _elapsed, _params) {
+  const r = Math.cos(5 / 2 * phase);
   return {
-    x: r * Math.cos(t),
-    y: r * Math.sin(t)
+    x: r * Math.cos(phase),
+    y: r * Math.sin(phase)
   };
 }
 var rose52 = {
@@ -1492,11 +1491,11 @@ var rose52 = {
 
 // src/curves/star.ts
 var TWO_PI11 = Math.PI * 2;
-function starFn(t, _time, _params) {
-  const r = Math.abs(Math.cos(5 / 2 * t)) + 0.35 * Math.abs(Math.cos(15 / 2 * t)) + 0.15 * Math.abs(Math.cos(25 / 2 * t));
+function starFn(phase, _elapsed, _params) {
+  const r = Math.abs(Math.cos(5 / 2 * phase)) + 0.35 * Math.abs(Math.cos(15 / 2 * phase)) + 0.15 * Math.abs(Math.cos(25 / 2 * phase));
   return {
-    x: r * Math.cos(t),
-    y: r * Math.sin(t)
+    x: r * Math.cos(phase),
+    y: r * Math.sin(phase)
   };
 }
 var star = {
@@ -1508,11 +1507,11 @@ var star = {
 
 // src/curves/star4.ts
 var TWO_PI12 = Math.PI * 2;
-function star4Fn(t, _time, _params) {
-  const r = Math.abs(Math.cos(2 * t)) + 0.35 * Math.abs(Math.cos(6 * t)) + 0.15 * Math.abs(Math.cos(10 * t));
+function star4Fn(phase, _elapsed, _params) {
+  const r = Math.abs(Math.cos(2 * phase)) + 0.35 * Math.abs(Math.cos(6 * phase)) + 0.15 * Math.abs(Math.cos(10 * phase));
   return {
-    x: r * Math.cos(t),
-    y: r * Math.sin(t)
+    x: r * Math.cos(phase),
+    y: r * Math.sin(phase)
   };
 }
 var star4 = {
@@ -1524,11 +1523,11 @@ var star4 = {
 
 // src/curves/star7.ts
 var TWO_PI13 = Math.PI * 2;
-function star7Fn(t, _time, _params) {
-  const r = Math.abs(Math.cos(7 / 2 * t)) + 0.35 * Math.abs(Math.cos(21 / 2 * t)) + 0.15 * Math.abs(Math.cos(35 / 2 * t));
+function star7Fn(phase, _elapsed, _params) {
+  const r = Math.abs(Math.cos(7 / 2 * phase)) + 0.35 * Math.abs(Math.cos(21 / 2 * phase)) + 0.15 * Math.abs(Math.cos(35 / 2 * phase));
   return {
-    x: r * Math.cos(t),
-    y: r * Math.sin(t)
+    x: r * Math.cos(phase),
+    y: r * Math.sin(phase)
   };
 }
 var star7 = {