@spirograph/anim

Optional animation driver for the spirograph: decides how much to draw at a given progress (frame plans) and schedules the drawing rhythm. It pairs with @spirograph/core — add it only when you need the simulated "pen tracing the pattern" animation.

What it adds (and what it deliberately doesn't)

• No pollution of core — all animation math lives in core's pure data operations (buildRenderData's perPenLimit prefix truncation, computeSteps, computeGearPose). This library only handles scheduling and frame plans; it never stuffs timers / DOM into core.
• Injectable scheduler — browsers / RN use requestAnimationFrame, Node falls back to setTimeout; the FrameScheduler interface is plug-and-play.
• Cross-platform consistency — createFramePlan is a pure function; the browser canvas and a future react-native-svg consume the same frame plan.

Install

npm install @spirograph/anim @spirograph/core

Usage

import { createFramePlan, DrawAnimation, autoScheduler } from '@spirograph/anim';
import { buildItems, computeBounds, computeTransform, buildRenderData } from '@spirograph/core';

const items = buildItems(state);
const t = computeTransform(computeBounds(items.map(i => i.curve)), 800, 800, 32);

// Per frame: how much each pen draws at a given progress (pure function)
const plan = createFramePlan(items, 0.42, { step: true });
const data = buildRenderData(items, t, { perPenLimit: plan.perPenPoints.map(n => Math.max(0, n - 1)) });

// Drive the animation (scheduler injectable)
const anim = new DrawAnimation(
  (progress) => renderFrame(createFramePlan(items, progress, { step: true })),
  () => renderFinal(),
  15_000,          // base duration ms
  autoScheduler(), // browser/RN rAF; Node auto-falls back to timer
);
anim.setSpeed(2);
anim.start();
anim.pause(); anim.resume(); anim.stop();

Schedulers

| Scheduler | Platform | Description | |---|---|---| | rafScheduler() | browser / RN | global requestAnimationFrame + performance.now; falls back to ~16ms timer without rAF | | timerScheduler() | Node | setTimeout fallback (~16ms) | | autoScheduler() | any | uses rAF when available, otherwise timer (default) |

Spirograph Generator (live demo)

The Spirograph Generator is the browser demo UI that drives this animation driver — a vanilla <canvas> editor where the gear/pen model can be tweaked live and animated, with PNG / SVG export and URL-based sharing.

▶ Try the full app — no install needed: https://leiwan5.github.io/spirograph/

Sibling packages

@spirograph/* is a small npm-workspaces monorepo — every package is a thin adapter or layer around the shared pure core, so colors, math, and animation frames stay pixel-consistent across renderers. The other independently publishable packages:

| Package | What it is | |---|---| | @spirograph/core | Pure cross-platform math, gradients, SVG/PNG generation — zero DOM / Node deps | | @spirograph/canvas | Browser-only Canvas 2D glue: renderer + PNG/SVG export helpers | | @spirograph/react | React <SpirographCanvas> / <SpirographAnimated> | | @spirograph/svelte | Svelte 5 <SpirographCanvas> / <SpirographAnimated> | | @spirograph/react-native | React Native SVG components on react-native-svg | | @spirograph/cli | CLI: URL-query / JSON → PNG / SVG files |

Build / publish

npm run build   # tsc -b → dist/

↳ Part of the spirograph-generator monorepo. See it animate live at https://leiwan5.github.io/spirograph/.