@sarmal/core 0.1.0

package/dist/index.cjs

@@ -0,0 +1,354 @@
+'use strict';
+
+// src/engine.ts
+var TWO_PI = Math.PI * 2;
+var POINTS_PER_PERIOD_UNIT = 50;
+var CircularBuffer = class {
+  constructor(capacity) {
+    this.head = 0;
+    this.count = 0;
+    this.capacity = capacity;
+    this.data = Array.from({ length: capacity }, () => ({ x: 0, y: 0 }));
+  }
+  /**
+   * Array elements are pre-allocated and `head` pointer is manually assigned,
+   *  because AI said using `Array.shift` would be `O(n)` and this would be `O(1)`
+   *  and I don't know any better.
+   */
+  push(x, y) {
+    this.data[this.head] = { x, y };
+    this.head = (this.head + 1) % this.capacity;
+    if (this.count < this.capacity) {
+      this.count++;
+    }
+  }
+  toArray() {
+    const result = new Array(this.count);
+    const start = this.count < this.capacity ? 0 : this.head;
+    for (let i = 0; i < this.count; i++) {
+      const index = (start + i) % this.capacity;
+      const p = this.data[index];
+      result[i] = { x: p.x, y: p.y };
+    }
+    return result;
+  }
+  clear() {
+    this.head = 0;
+    this.count = 0;
+  }
+  get length() {
+    return this.count;
+  }
+};
+function createEngine(curveDef, trailLength = 120) {
+  const curve = {
+    name: curveDef.name,
+    fn: curveDef.fn,
+    period: curveDef.period ?? TWO_PI,
+    speed: curveDef.speed ?? 1
+  };
+  const trail = new CircularBuffer(trailLength);
+  let t = 0;
+  let actualTime = 0;
+  return {
+    tick(deltaTime) {
+      t = (t + curve.speed * deltaTime) % curve.period;
+      actualTime += deltaTime;
+      const point = curve.fn(t, actualTime, {});
+      trail.push(point.x, point.y);
+      return trail.toArray();
+    },
+    reset() {
+      t = 0;
+      actualTime = 0;
+      trail.clear();
+    },
+    getSarmalSkeleton() {
+      const steps = Math.ceil(curve.period * POINTS_PER_PERIOD_UNIT);
+      const points = new Array(steps);
+      for (let i = 0; i < steps; i++) {
+        const sampleT = i / (steps - 1) * curve.period;
+        const point = curve.fn(sampleT, 0, {});
+        points[i] = point;
+      }
+      return points;
+    }
+  };
+}
+
+// src/renderer.ts
+var DEFAULT_HEAD_RADIUS = 4;
+var DEFAULT_GLOW_SIZE = 20;
+var DEFAULT_SKELETON_COLOR = "#ffffff";
+var DEFAULT_SKELETON_OPACITY = 0.15;
+var FIT_PADDING = 0.1;
+var TRAIL_BATCH_SIZE = 10;
+var TRAIL_FADE_CURVE = 1.5;
+var TRAIL_MAX_OPACITY = 0.88;
+var TRAIL_MIN_WIDTH = 0.5;
+var TRAIL_MAX_WIDTH = 2.5;
+var GLOW_INNER_EDGE = 0.4;
+var GLOW_FALLOFF_OPACITY = 0.53;
+function hexToRgba(hex, alpha) {
+  const n = parseInt(hex.slice(1), 16);
+  return `rgba(${n >> 16},${n >> 8 & 255},${n & 255},${alpha})`;
+}
+function createRenderer(options) {
+  const canvas = options.canvas;
+  if (!canvas.getContext("2d")) {
+    throw new Error("Could not get 2d context from canvas");
+  }
+  const ctx = canvas.getContext("2d");
+  const engine = options.engine;
+  const opts = {
+    skeletonColor: options.skeletonColor ?? DEFAULT_SKELETON_COLOR,
+    trailColor: options.trailColor ?? "#ffffff",
+    headColor: options.headColor ?? "#ffffff",
+    headRadius: options.headRadius ?? DEFAULT_HEAD_RADIUS,
+    glowSize: options.glowSize ?? DEFAULT_GLOW_SIZE
+  };
+  let skeleton = [];
+  let trail = [];
+  let head = null;
+  let scale = 1;
+  let offsetX = 0;
+  let offsetY = 0;
+  let animationId = null;
+  let lastTime = 0;
+  function calculateBoundaries() {
+    if (skeleton.length === 0) {
+      return;
+    }
+    const first = skeleton[0];
+    let minX = first.x, maxX = first.x, minY = first.y, maxY = first.y;
+    for (const p of skeleton) {
+      if (p.x < minX) {
+        minX = p.x;
+      }
+      if (p.x > maxX) {
+        maxX = p.x;
+      }
+      if (p.y < minY) {
+        minY = p.y;
+      }
+      if (p.y > maxY) {
+        maxY = p.y;
+      }
+    }
+    const width = maxX - minX;
+    const height = maxY - minY;
+    const canvasWidth = canvas.width;
+    const canvasHeight = canvas.height;
+    const scaleX = canvasWidth / (width * (1 + FIT_PADDING * 2));
+    const scaleY = canvasHeight / (height * (1 + FIT_PADDING * 2));
+    scale = Math.min(scaleX, scaleY);
+    const boundsWidth = width * scale;
+    const boundsHeight = height * scale;
+    offsetX = (canvasWidth - boundsWidth) / 2 - minX * scale;
+    offsetY = (canvasHeight - boundsHeight) / 2 - minY * scale;
+  }
+  function transformCoordinateToPixel(p) {
+    return {
+      x: p.x * scale + offsetX,
+      y: p.y * scale + offsetY
+    };
+  }
+  function drawSkeleton() {
+    if (skeleton.length < 2) {
+      return;
+    }
+    ctx.strokeStyle = hexToRgba(opts.skeletonColor, DEFAULT_SKELETON_OPACITY);
+    ctx.lineWidth = 1.5;
+    ctx.beginPath();
+    const firstPixel = transformCoordinateToPixel(skeleton[0]);
+    ctx.moveTo(firstPixel.x, firstPixel.y);
+    for (let i = 1; i < skeleton.length; i++) {
+      const pixel = transformCoordinateToPixel(skeleton[i]);
+      ctx.lineTo(pixel.x, pixel.y);
+    }
+    ctx.stroke();
+  }
+  function drawTrail() {
+    if (trail.length < 2) {
+      return;
+    }
+    for (let b = 0; b < trail.length - 1; b += TRAIL_BATCH_SIZE) {
+      const bEnd = Math.min(b + TRAIL_BATCH_SIZE, trail.length - 1);
+      const progress = (b + bEnd) / 2 / (trail.length - 1);
+      const alpha = Math.pow(progress, TRAIL_FADE_CURVE) * TRAIL_MAX_OPACITY;
+      const lineWidth = TRAIL_MIN_WIDTH + progress * (TRAIL_MAX_WIDTH - TRAIL_MIN_WIDTH);
+      ctx.beginPath();
+      for (let i = b; i <= bEnd; i++) {
+        const pixel = transformCoordinateToPixel(trail[i]);
+        if (i === b) {
+          ctx.moveTo(pixel.x, pixel.y);
+        } else {
+          ctx.lineTo(pixel.x, pixel.y);
+        }
+      }
+      ctx.strokeStyle = hexToRgba(opts.trailColor, alpha);
+      ctx.lineWidth = lineWidth;
+      ctx.lineJoin = "round";
+      ctx.lineCap = "round";
+      ctx.stroke();
+    }
+  }
+  function drawHead() {
+    if (!head) {
+      return;
+    }
+    const { x, y } = transformCoordinateToPixel(head);
+    const gradient = ctx.createRadialGradient(x, y, 0, x, y, opts.glowSize);
+    gradient.addColorStop(0, opts.headColor);
+    gradient.addColorStop(GLOW_INNER_EDGE, hexToRgba(opts.headColor, GLOW_FALLOFF_OPACITY));
+    gradient.addColorStop(1, "transparent");
+    ctx.fillStyle = gradient;
+    ctx.beginPath();
+    ctx.arc(x, y, opts.glowSize, 0, Math.PI * 2);
+    ctx.fill();
+    ctx.fillStyle = opts.headColor;
+    ctx.beginPath();
+    ctx.arc(x, y, opts.headRadius, 0, Math.PI * 2);
+    ctx.fill();
+  }
+  function render() {
+    const now = performance.now();
+    const deltaTime = (now - lastTime) / 1e3;
+    lastTime = now;
+    trail = engine.tick(deltaTime);
+    head = trail.length > 0 ? trail[trail.length - 1] : null;
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+    drawSkeleton();
+    drawTrail();
+    drawHead();
+    animationId = requestAnimationFrame(render);
+  }
+  skeleton = engine.getSarmalSkeleton();
+  calculateBoundaries();
+  return {
+    start() {
+      if (animationId !== null) {
+        return;
+      }
+      lastTime = performance.now();
+      render();
+    },
+    stop() {
+      if (animationId === null) {
+        return;
+      }
+      cancelAnimationFrame(animationId);
+      animationId = null;
+    },
+    reset() {
+      engine.reset();
+      trail = [];
+      head = null;
+    },
+    destroy() {
+      if (animationId !== null) {
+        cancelAnimationFrame(animationId);
+        animationId = null;
+      }
+    }
+  };
+}
+
+// src/curves.ts
+var TWO_PI2 = Math.PI * 2;
+function epitrochoid7(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)
+  };
+}
+function astroid(t, _time, _params) {
+  const c = Math.cos(t);
+  const s = Math.sin(t);
+  return {
+    x: c * c * c,
+    y: s * s * s
+  };
+}
+function deltoid(t, _time, _params) {
+  return {
+    x: 2 * Math.cos(t) + Math.cos(2 * t),
+    y: 2 * Math.sin(t) - Math.sin(2 * t)
+  };
+}
+function rose5(t, _time, _params) {
+  const r = Math.cos(5 * t);
+  return {
+    x: r * Math.cos(t),
+    y: r * Math.sin(t)
+  };
+}
+function rose3(t, _time, _params) {
+  const r = Math.cos(3 * t);
+  return {
+    x: r * Math.cos(t),
+    y: r * Math.sin(t)
+  };
+}
+function artemis2(t, _time, _params) {
+  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
+  };
+}
+var curves = {
+  epitrochoid7: {
+    name: "Epitrochoid",
+    fn: epitrochoid7,
+    period: TWO_PI2,
+    speed: 1.4
+  },
+  astroid: {
+    name: "Astroid",
+    fn: astroid,
+    period: TWO_PI2,
+    speed: 1.1
+  },
+  deltoid: {
+    name: "Deltoid",
+    fn: deltoid,
+    period: TWO_PI2,
+    speed: 0.9
+  },
+  rose5: {
+    name: "Rose (n=5)",
+    fn: rose5,
+    period: TWO_PI2,
+    speed: 1
+  },
+  rose3: {
+    name: "Rose (n=3)",
+    fn: rose3,
+    period: TWO_PI2,
+    speed: 1.15
+  },
+  artemis2: {
+    name: "Artemis II",
+    fn: artemis2,
+    period: TWO_PI2,
+    speed: 0.7
+  }
+};
+
+// src/index.ts
+function createSarmal(canvas, curveDef, options) {
+  const { trailLength, ...rendererOpts } = options ?? {};
+  const engine = createEngine(curveDef, trailLength);
+  return createRenderer({ canvas, engine, ...rendererOpts });
+}
+
+exports.createEngine = createEngine;
+exports.createRenderer = createRenderer;
+exports.createSarmal = createSarmal;
+exports.curves = curves;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/engine.ts","../src/renderer.ts","../src/curves.ts","../src/index.ts"],"names":["TWO_PI"],"mappings":"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","file":"index.cjs","sourcesContent":["import type { CurveDef, Engine, Point } from \"./types\";\n\nconst TWO_PI = Math.PI * 2;\nconst POINTS_PER_PERIOD_UNIT = 50;\n\n/**\n * A fixed-size list of points with first in, last out method\n * The oldest entry is automatically discarded when the list is at capacity\n */\nclass CircularBuffer {\n  private data: Array<Point>;\n  private capacity: number;\n  private head: number = 0;\n  private count: number = 0;\n\n  constructor(capacity: number) {\n    this.capacity = capacity;\n    this.data = Array.from({ length: capacity }, () => ({ x: 0, y: 0 }));\n  }\n\n  /**\n   * Array elements are pre-allocated and `head` pointer is manually assigned,\n   *  because AI said using `Array.shift` would be `O(n)` and this would be `O(1)`\n   *  and I don't know any better.\n   */\n  push(x: number, y: number): void {\n    this.data[this.head] = { x: x, y: y };\n    this.head = (this.head + 1) % this.capacity;\n    if (this.count < this.capacity) {\n      this.count++;\n    }\n  }\n\n  toArray(): Array<Point> {\n    // oxlint-disable-next-line unicorn/no-new-array -- AI said it is pre-allocated for performance (runs every frame)\n    const result: Array<Point> = new Array(this.count);\n    const start = this.count < this.capacity ? 0 : this.head;\n    for (let i = 0; i < this.count; i++) {\n      const index = (start + i) % this.capacity;\n      const p = this.data[index]!;\n      result[i] = { x: p.x, y: p.y };\n    }\n    return result;\n  }\n\n  clear(): void {\n    this.head = 0;\n    this.count = 0;\n  }\n\n  get length(): number {\n    return this.count;\n  }\n}\n\n/**\n * Creates the core simulation engine for a sarmal\n *\n * it runs a clock (time `t`), asks the curve for the current Point position at that time,\n *  and remembers the last N positions so the renderer can draw the trail\n *\n * The engine is only responsible for math coordinates,\n *  so it is not responsible for drawing or colors\n *\n * @param curveDef A curve definition\n * @param trailLength default: `120`\n */\nexport function createEngine(curveDef: CurveDef, trailLength: number = 120): Engine {\n  const curve = {\n    name: curveDef.name,\n    fn: curveDef.fn,\n    period: curveDef.period ?? TWO_PI,\n    speed: curveDef.speed ?? 1,\n  };\n  const trail = new CircularBuffer(trailLength);\n  let t = 0;\n  let actualTime = 0;\n\n  return {\n    tick(deltaTime: number): Array<Point> {\n      t = (t + curve.speed * deltaTime) % curve.period;\n      actualTime += deltaTime;\n      const point = curve.fn(t, actualTime, {});\n      trail.push(point.x, point.y);\n      return trail.toArray();\n    },\n\n    reset(): void {\n      t = 0;\n      actualTime = 0;\n      trail.clear();\n    },\n\n    getSarmalSkeleton(): Array<Point> {\n      const steps = Math.ceil(curve.period * POINTS_PER_PERIOD_UNIT);\n      // oxlint-disable-next-line unicorn/no-new-array -- array is pre-allocated, filled immediately below\n      const points: Array<Point> = new Array(steps);\n      for (let i = 0; i < steps; i++) {\n        const sampleT = (i / (steps - 1)) * curve.period;\n        const point = curve.fn(sampleT, 0, {});\n        points[i] = point;\n      }\n      return points;\n    },\n  };\n}\n","import type { Point, RendererOptions, SarmalInstance } from \"./types\";\n\nconst DEFAULT_HEAD_RADIUS = 4;\nconst DEFAULT_GLOW_SIZE = 20;\nconst DEFAULT_SKELETON_COLOR = \"#ffffff\";\nconst DEFAULT_SKELETON_OPACITY = 0.15;\n\n/** Fraction of the bounding box added as padding when fitting the curve to the canvas */\nconst FIT_PADDING = 0.1;\n\n/**\n * The trail is drawn in batches of points\n * Each batch has lower opacity than the one that comes before it\n *  (0 = oldest/tail, 1 = newest/head)\n */\nconst TRAIL_BATCH_SIZE = 10;\n/** Higher values = sharper fade near the tail, more of the trail appears faint */\nconst TRAIL_FADE_CURVE = 1.5;\nconst TRAIL_MAX_OPACITY = 0.88;\n/** Line width of tail */\nconst TRAIL_MIN_WIDTH = 0.5;\n/** Line width of head */\nconst TRAIL_MAX_WIDTH = 2.5;\n\nconst GLOW_INNER_EDGE = 0.4;\n/** Opacity at the inner edge of the glow falloff */\nconst GLOW_FALLOFF_OPACITY = 0.53;\n\n// TODO: might as well accept rgb/rgba directly too\nfunction hexToRgba(hex: string, alpha: number): string {\n  const n = parseInt(hex.slice(1), 16);\n  return `rgba(${n >> 16},${(n >> 8) & 255},${n & 255},${alpha})`;\n}\n\n/**\n * Creates a Canvas 2D renderer for sarmal animations\n * Renders the skeleton, the trail, and the glowing dot.\n */\nexport function createRenderer(options: RendererOptions): SarmalInstance {\n  const canvas = options.canvas;\n  if (!canvas.getContext(\"2d\")) {\n    throw new Error(\"Could not get 2d context from canvas\");\n  }\n  const ctx = canvas.getContext(\"2d\")!;\n\n  const engine = options.engine;\n  const opts = {\n    skeletonColor: options.skeletonColor ?? DEFAULT_SKELETON_COLOR,\n    trailColor: options.trailColor ?? \"#ffffff\",\n    headColor: options.headColor ?? \"#ffffff\",\n    headRadius: options.headRadius ?? DEFAULT_HEAD_RADIUS,\n    glowSize: options.glowSize ?? DEFAULT_GLOW_SIZE,\n  };\n\n  let skeleton: Array<Point> = [];\n  let trail: Array<Point> = [];\n  let head: Point | null = null;\n  let scale = 1;\n  let offsetX = 0;\n  let offsetY = 0;\n  let animationId: number | null = null;\n  let lastTime = 0;\n\n  /**\n   * Computes how to map engine coordinates to canvas pixels\n   *\n   * Steps are roughly: curve fn -> coordinate point -> (scale + offset) -> pixel\n   *\n   * 1. Find the bounding box of the skeleton (min/max x/y in coordinates)\n   * 2. Compute a scale factor within the bounds into the canvas with padding\n   * 3. Compute offsets to center the curve in the canvas\n   */\n  function calculateBoundaries() {\n    if (skeleton.length === 0) {\n      return;\n    }\n\n    const first = skeleton[0]!;\n    let minX = first.x,\n      maxX = first.x,\n      minY = first.y,\n      maxY = first.y;\n    for (const p of skeleton) {\n      if (p.x < minX) {\n        minX = p.x;\n      }\n\n      if (p.x > maxX) {\n        maxX = p.x;\n      }\n\n      if (p.y < minY) {\n        minY = p.y;\n      }\n\n      if (p.y > maxY) {\n        maxY = p.y;\n      }\n    }\n\n    const width = maxX - minX;\n    const height = maxY - minY;\n    const canvasWidth = canvas.width;\n    const canvasHeight = canvas.height;\n\n    const scaleX = canvasWidth / (width * (1 + FIT_PADDING * 2));\n    const scaleY = canvasHeight / (height * (1 + FIT_PADDING * 2));\n    scale = Math.min(scaleX, scaleY);\n\n    const boundsWidth = width * scale;\n    const boundsHeight = height * scale;\n    offsetX = (canvasWidth - boundsWidth) / 2 - minX * scale;\n    offsetY = (canvasHeight - boundsHeight) / 2 - minY * scale;\n  }\n\n  function transformCoordinateToPixel(p: Point) {\n    return {\n      x: p.x * scale + offsetX,\n      y: p.y * scale + offsetY,\n    };\n  }\n\n  function drawSkeleton() {\n    if (skeleton.length < 2) {\n      return;\n    }\n\n    ctx.strokeStyle = hexToRgba(opts.skeletonColor, DEFAULT_SKELETON_OPACITY);\n    ctx.lineWidth = 1.5;\n    ctx.beginPath();\n\n    const firstPixel = transformCoordinateToPixel(skeleton[0]!);\n    ctx.moveTo(firstPixel.x, firstPixel.y);\n\n    for (let i = 1; i < skeleton.length; i++) {\n      const pixel = transformCoordinateToPixel(skeleton[i]!);\n      ctx.lineTo(pixel.x, pixel.y);\n    }\n\n    ctx.stroke();\n  }\n\n  function drawTrail() {\n    if (trail.length < 2) {\n      return;\n    }\n\n    for (let b = 0; b < trail.length - 1; b += TRAIL_BATCH_SIZE) {\n      const bEnd = Math.min(b + TRAIL_BATCH_SIZE, trail.length - 1);\n      /** Normalized position of this batch along the trail (0 = tail, 1 = head) */\n      const progress = (b + bEnd) / 2 / (trail.length - 1);\n      const alpha = Math.pow(progress, TRAIL_FADE_CURVE) * TRAIL_MAX_OPACITY;\n      const lineWidth = TRAIL_MIN_WIDTH + progress * (TRAIL_MAX_WIDTH - TRAIL_MIN_WIDTH);\n\n      ctx.beginPath();\n      for (let i = b; i <= bEnd; i++) {\n        const pixel = transformCoordinateToPixel(trail[i]!);\n        if (i === b) {\n          ctx.moveTo(pixel.x, pixel.y);\n        } else {\n          ctx.lineTo(pixel.x, pixel.y);\n        }\n      }\n\n      ctx.strokeStyle = hexToRgba(opts.trailColor, alpha);\n      ctx.lineWidth = lineWidth;\n      ctx.lineJoin = \"round\";\n      ctx.lineCap = \"round\";\n      ctx.stroke();\n    }\n  }\n\n  function drawHead() {\n    if (!head) {\n      return;\n    }\n\n    const { x, y } = transformCoordinateToPixel(head);\n\n    const gradient = ctx.createRadialGradient(x, y, 0, x, y, opts.glowSize);\n    gradient.addColorStop(0, opts.headColor);\n    gradient.addColorStop(GLOW_INNER_EDGE, hexToRgba(opts.headColor, GLOW_FALLOFF_OPACITY));\n    gradient.addColorStop(1, \"transparent\");\n\n    ctx.fillStyle = gradient;\n    ctx.beginPath();\n    ctx.arc(x, y, opts.glowSize, 0, Math.PI * 2);\n    ctx.fill();\n\n    ctx.fillStyle = opts.headColor;\n    ctx.beginPath();\n    ctx.arc(x, y, opts.headRadius, 0, Math.PI * 2);\n    ctx.fill();\n  }\n\n  function render() {\n    const now = performance.now();\n    const deltaTime = (now - lastTime) / 1000;\n    lastTime = now;\n\n    trail = engine.tick(deltaTime);\n    head = trail.length > 0 ? trail[trail.length - 1]! : null;\n\n    ctx.clearRect(0, 0, canvas.width, canvas.height);\n\n    drawSkeleton();\n    drawTrail();\n    drawHead();\n\n    animationId = requestAnimationFrame(render);\n  }\n\n  // Initialize skeleton on creation\n  skeleton = engine.getSarmalSkeleton();\n  calculateBoundaries();\n\n  return {\n    start() {\n      if (animationId !== null) {\n        return;\n      }\n\n      lastTime = performance.now();\n      render();\n    },\n\n    stop() {\n      if (animationId === null) {\n        return;\n      }\n      cancelAnimationFrame(animationId);\n      animationId = null;\n    },\n\n    reset() {\n      engine.reset();\n      trail = [];\n      head = null;\n    },\n\n    destroy() {\n      if (animationId !== null) {\n        cancelAnimationFrame(animationId);\n        animationId = null;\n      }\n    },\n  };\n}\n","import type { CurveDef, Point } from \"./types\";\n\nconst TWO_PI = Math.PI * 2;\n\n/** 7-lobed epitrochoid with a breathing distance parameter — d oscillates with t, making the loops pulse in and out */\nfunction epitrochoid7(t: number, _time: number, _params: Record<string, number>): Point {\n  const d = 1.0 + 0.55 * Math.sin(t * 0.5);\n  return {\n    x: 7 * Math.cos(t) - d * Math.cos(7 * t),\n    y: 7 * Math.sin(t) - d * Math.sin(7 * t),\n  };\n}\n\nfunction astroid(t: number, _time: number, _params: Record<string, number>): Point {\n  const c = Math.cos(t);\n  const s = Math.sin(t);\n  return {\n    x: c * c * c,\n    y: s * s * s,\n  };\n}\n\nfunction deltoid(t: number, _time: number, _params: Record<string, number>): Point {\n  return {\n    x: 2 * Math.cos(t) + Math.cos(2 * t),\n    y: 2 * Math.sin(t) - Math.sin(2 * t),\n  };\n}\n\nfunction rose5(t: number, _time: number, _params: Record<string, number>): Point {\n  const r = Math.cos(5 * t);\n  return {\n    x: r * Math.cos(t),\n    y: r * Math.sin(t),\n  };\n}\n\nfunction rose3(t: number, _time: number, _params: Record<string, number>): Point {\n  const r = Math.cos(3 * t);\n  return {\n    x: r * Math.cos(t),\n    y: r * Math.sin(t),\n  };\n}\n\n/**\n * Artemis II free-return lunar trajectory\n * @see https://www.nasa.gov/wp-content/uploads/2025/09/artemis-ii-map-508.pdf\n * a = x-axis asymmetry (widens one lobe),\n * b = y-axis asymmetry,\n * ox = horizontal offset to visually center the shape\n */\nfunction artemis2(t: number, _time: number, _params: Record<string, number>): Point {\n  const a = 0.35,\n    b = 0.15,\n    ox = 0.175;\n  const s = Math.sin(t),\n    c = Math.cos(t);\n  const denom = 1 + s * s;\n  return {\n    x: (c * (1 + a * c)) / denom - ox,\n    y: (s * c * (1 + b * c)) / denom,\n  };\n}\n\nexport const curves: Record<string, CurveDef> = {\n  epitrochoid7: {\n    name: \"Epitrochoid\",\n    fn: epitrochoid7,\n    period: TWO_PI,\n    speed: 1.4,\n  },\n  astroid: {\n    name: \"Astroid\",\n    fn: astroid,\n    period: TWO_PI,\n    speed: 1.1,\n  },\n  deltoid: {\n    name: \"Deltoid\",\n    fn: deltoid,\n    period: TWO_PI,\n    speed: 0.9,\n  },\n  rose5: {\n    name: \"Rose (n=5)\",\n    fn: rose5,\n    period: TWO_PI,\n    speed: 1.0,\n  },\n  rose3: {\n    name: \"Rose (n=3)\",\n    fn: rose3,\n    period: TWO_PI,\n    speed: 1.15,\n  },\n  artemis2: {\n    name: \"Artemis II\",\n    fn: artemis2,\n    period: TWO_PI,\n    speed: 0.7,\n  },\n};\n","export type {\n  Point,\n  CurveDef,\n  Engine,\n  SarmalInstance,\n  RendererOptions,\n  SarmalOptions,\n} from \"./types\";\n\nexport { createEngine } from \"./engine\";\nexport { createRenderer } from \"./renderer\";\nexport { curves } from \"./curves\";\n\nimport type { CurveDef, SarmalInstance, SarmalOptions } from \"./types\";\nimport { createEngine } from \"./engine\";\nimport { createRenderer } from \"./renderer\";\n\n/**\n * Creates a sarmal animation on a canvas element\n *\n * @example\n * ```ts\n * import { createSarmal, curves } from 'sarmal'\n * const sarmal = createSarmal(canvas, curves.artemis2)\n * sarmal.start()\n * ```\n */\nexport function createSarmal(\n  canvas: HTMLCanvasElement,\n  curveDef: CurveDef,\n  options?: SarmalOptions,\n): SarmalInstance {\n  const { trailLength, ...rendererOpts } = options ?? {};\n  const engine = createEngine(curveDef, trailLength);\n\n  return createRenderer({ canvas, engine, ...rendererOpts });\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,118 @@
+interface Point {
+    x: number;
+    y: number;
+}
+interface CurveDef {
+    name: string;
+    fn: (t: number, time: number, params: Record<string, number>) => Point;
+    /**
+     * @default (Math.PI * 2)
+     */
+    period?: number;
+    /**
+     * @default 1
+     */
+    speed?: number;
+    /**
+     * To indicate a compatible library version when providing the curve definitions
+     * Intended for potential backwards compatibility scenarios and futureproofing
+     */
+    version?: number;
+}
+interface Engine {
+    /**
+     * Advances the Sarmal simulation by the given delta time (dt) in seconds.
+     * Internally, this increases the simulation time `t` by `speed * dt`,
+     *  wraps `t` at `period`, evaluates the curve's parametric function `fn(t)`,
+     *  and appends the new point to the trail.
+     * Returns a `Point` array, which are sorted oldest to newest
+     * @param deltaTime Delta time in seconds (typically frame time from **requestAnimationFrame** or similar)
+     */
+    tick(deltaTime: number): Array<Point>;
+    /**
+     * Resets the simulation state, by clearing the trail and reverting internal time `t` to 0.
+     * The next call to `tick` will start fresh from the beginning of the curve.
+     */
+    reset(): void;
+    /**
+     * Returns the *skeleton* of the curve.
+     * In technicality, it just represents the complete traversal of the curve over one full period,
+     *  which is sampled at points from `t=0` to `t=period`
+     *
+     * The skeleton is always derived from the curve's state at `t=0` using `fn(t, 0)`
+     * This represents the full path the sarmal would trace on its first complete cycle,
+     *  rendered as a static background reference.
+     *
+     * The number of sample points is automatically derived from the curve's period.
+     */
+    getSarmalSkeleton(): Array<Point>;
+}
+interface SarmalInstance {
+    start(): void;
+    stop(): void;
+    /** Resets the engine and clears the trail */
+    reset(): void;
+    /** Stops the animation and cleans up resources */
+    destroy(): void;
+}
+interface RendererOptions {
+    /** Target canvas element that will contain the Sarmal */
+    canvas: HTMLCanvasElement;
+    engine: Engine;
+    /**
+     * @default '#ffffff'
+     */
+    skeletonColor?: string;
+    /**
+     * @default '#ffffff'
+     */
+    trailColor?: string;
+    /**
+     * @default '#ffffff'
+     */
+    headColor?: string;
+    /** @default 4 */
+    headRadius?: number;
+    /** @default 20 */
+    glowSize?: number;
+}
+interface SarmalOptions extends Omit<RendererOptions, "canvas" | "engine"> {
+    /** @default 120 */
+    trailLength?: number;
+}
+
+/**
+ * Creates the core simulation engine for a sarmal
+ *
+ * it runs a clock (time `t`), asks the curve for the current Point position at that time,
+ *  and remembers the last N positions so the renderer can draw the trail
+ *
+ * The engine is only responsible for math coordinates,
+ *  so it is not responsible for drawing or colors
+ *
+ * @param curveDef A curve definition
+ * @param trailLength default: `120`
+ */
+declare function createEngine(curveDef: CurveDef, trailLength?: number): Engine;
+
+/**
+ * Creates a Canvas 2D renderer for sarmal animations
+ * Renders the skeleton, the trail, and the glowing dot.
+ */
+declare function createRenderer(options: RendererOptions): SarmalInstance;
+
+declare const curves: Record<string, CurveDef>;
+
+/**
+ * Creates a sarmal animation on a canvas element
+ *
+ * @example
+ * ```ts
+ * import { createSarmal, curves } from 'sarmal'
+ * const sarmal = createSarmal(canvas, curves.artemis2)
+ * sarmal.start()
+ * ```
+ */
+declare function createSarmal(canvas: HTMLCanvasElement, curveDef: CurveDef, options?: SarmalOptions): SarmalInstance;
+
+export { type CurveDef, type Engine, type Point, type RendererOptions, type SarmalInstance, type SarmalOptions, createEngine, createRenderer, createSarmal, curves };

package/dist/index.d.ts

@@ -0,0 +1,118 @@
+interface Point {
+    x: number;
+    y: number;
+}
+interface CurveDef {
+    name: string;
+    fn: (t: number, time: number, params: Record<string, number>) => Point;
+    /**
+     * @default (Math.PI * 2)
+     */
+    period?: number;
+    /**
+     * @default 1
+     */
+    speed?: number;
+    /**
+     * To indicate a compatible library version when providing the curve definitions
+     * Intended for potential backwards compatibility scenarios and futureproofing
+     */
+    version?: number;
+}
+interface Engine {
+    /**
+     * Advances the Sarmal simulation by the given delta time (dt) in seconds.
+     * Internally, this increases the simulation time `t` by `speed * dt`,
+     *  wraps `t` at `period`, evaluates the curve's parametric function `fn(t)`,
+     *  and appends the new point to the trail.
+     * Returns a `Point` array, which are sorted oldest to newest
+     * @param deltaTime Delta time in seconds (typically frame time from **requestAnimationFrame** or similar)
+     */
+    tick(deltaTime: number): Array<Point>;
+    /**
+     * Resets the simulation state, by clearing the trail and reverting internal time `t` to 0.
+     * The next call to `tick` will start fresh from the beginning of the curve.
+     */
+    reset(): void;
+    /**
+     * Returns the *skeleton* of the curve.
+     * In technicality, it just represents the complete traversal of the curve over one full period,
+     *  which is sampled at points from `t=0` to `t=period`
+     *
+     * The skeleton is always derived from the curve's state at `t=0` using `fn(t, 0)`
+     * This represents the full path the sarmal would trace on its first complete cycle,
+     *  rendered as a static background reference.
+     *
+     * The number of sample points is automatically derived from the curve's period.
+     */
+    getSarmalSkeleton(): Array<Point>;
+}
+interface SarmalInstance {
+    start(): void;
+    stop(): void;
+    /** Resets the engine and clears the trail */
+    reset(): void;
+    /** Stops the animation and cleans up resources */
+    destroy(): void;
+}
+interface RendererOptions {
+    /** Target canvas element that will contain the Sarmal */
+    canvas: HTMLCanvasElement;
+    engine: Engine;
+    /**
+     * @default '#ffffff'
+     */
+    skeletonColor?: string;
+    /**
+     * @default '#ffffff'
+     */
+    trailColor?: string;
+    /**
+     * @default '#ffffff'
+     */
+    headColor?: string;
+    /** @default 4 */
+    headRadius?: number;
+    /** @default 20 */
+    glowSize?: number;
+}
+interface SarmalOptions extends Omit<RendererOptions, "canvas" | "engine"> {
+    /** @default 120 */
+    trailLength?: number;
+}
+
+/**
+ * Creates the core simulation engine for a sarmal
+ *
+ * it runs a clock (time `t`), asks the curve for the current Point position at that time,
+ *  and remembers the last N positions so the renderer can draw the trail
+ *
+ * The engine is only responsible for math coordinates,
+ *  so it is not responsible for drawing or colors
+ *
+ * @param curveDef A curve definition
+ * @param trailLength default: `120`
+ */
+declare function createEngine(curveDef: CurveDef, trailLength?: number): Engine;
+
+/**
+ * Creates a Canvas 2D renderer for sarmal animations
+ * Renders the skeleton, the trail, and the glowing dot.
+ */
+declare function createRenderer(options: RendererOptions): SarmalInstance;
+
+declare const curves: Record<string, CurveDef>;
+
+/**
+ * Creates a sarmal animation on a canvas element
+ *
+ * @example
+ * ```ts
+ * import { createSarmal, curves } from 'sarmal'
+ * const sarmal = createSarmal(canvas, curves.artemis2)
+ * sarmal.start()
+ * ```
+ */
+declare function createSarmal(canvas: HTMLCanvasElement, curveDef: CurveDef, options?: SarmalOptions): SarmalInstance;
+
+export { type CurveDef, type Engine, type Point, type RendererOptions, type SarmalInstance, type SarmalOptions, createEngine, createRenderer, createSarmal, curves };