procedural_animation_canvas v1.0.0

name: procedural_animation_canvas description: Make real animation in HTML Canvas 2D with code: direct motion with timing and easing craft, prototype timing on hard stepped frames first, run a clean fixed-timestep engine, and export a working MP4 through the browser (captureStream + MediaRecorder with a frame-perfect stepping path and ffmpeg fallback). Use when someone wants programmatic 2D animation, motion graphics from code, bouncing/flying/squashing motion, or recording a canvas animation to a video file.

Procedural Animation in Canvas 2D

Purpose

Teach an agent to make Canvas 2D animation that feels directed, not generated: motion with deliberate timing and easing, a cheap prototype loop for judging timing before smoothing, a small engine that keeps simulation deterministic, and an export path that produces a real, playable MP4. The engine lives in assets/engine.js; the craft lives in the references.

Workflow

1. Write the move as data, not as drawing code. Build a timeline of named channels with makeTimeline().add('x', {from, to, duration, delay, ease}). Duration is the feeling; set it before anything else. See references/direction-guide.md for how to choose timings, easings, and where anticipation/squash/arcs belong.
2. Prototype on hard frames. Before smoothing, judge the timing with stepPlayback({fps: 6, duration, render}) or swap the real easing for steps(6). Fix durations and delays while motion is still cheap. If the stepped version reads, smoothing will work; if it does not, no curve will save it.
3. Write one drawScene(t, ctx) function. It takes seconds, draws the whole frame, and touches nothing else. The timeline gives you values; drawScene turns them into pixels. This same function drives the live preview, the step preview, and the export, so they can never drift apart.
4. Preview live. startLoop({canvas, update, render}) runs simulation on a fixed timestep (accumulator, spiral-of-death clamp) with interpolated rendering, so motion is deterministic at any display refresh rate.
5. Export. Frame-perfect path first: `recordFrames({width, height, fps, duration, renderFrame})` steps a hidden canvas through every frame and pushes each one manually with requestFrame(). If that is unavailable, recordLive(canvas, {fps, duration}) records the live canvas. Both negotiate codecs via pickMime(): native MP4 on Chrome/Edge 126+ and Safari 14.1+, WebM on Firefox. WebM output gets transcoded with the ffmpeg command in references/export-pipeline.md. Open assets/demo.html (a working bounce: live, step, and record buttons) to see the whole loop end to end.

Output Contract

• Deliverable: an MP4 (h264, yuv420p, +faststart) that plays everywhere, or a WebM plus the ffmpeg command that converts it.
• The animation is defined by a timeline and one drawScene(t, ctx); live preview and export share that function, never two parallel implementations.
• Export resolution and fps are set explicitly in the export call, not read from the screen.

Operating Rules

1. Never animate with raw per-frame increments (x += 1). Every move is a tween with a duration and an easing. Increments make motion frame-rate dependent and undirectable.
2. Ease out of starts, ease into stops. linear is for machines (wheels, conveyors), never for starts and stops.
3. One overshoot per scene. backOut and easeOutElastic fight each other if you stack them.
4. Prototype timing on hard frames (step 2) before committing to curves. Changing durations after the fact is a rewrite of the motion.
5. Never record the canvas the user interacts with. Export drives a hidden canvas; the visible one is a preview.
6. Never promise MP4 on a browser that cannot make it. pickMime() decides; Firefox exports WebM, and that is correct behavior, not a failure.
7. Engine math stays DOM-free. The easing/tween/timeline core in assets/engine.js has zero DOM dependencies and is covered by assets/test-engine.js (node test-engine.js); run it after any change.