⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
code-explainer
Animate source code changing between versions and step through execution state in MG scenes.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
// README
A film here is a folder of plain files: film.json places clips on tracks, and each motion-graphics
scene is a React component animated with GSAP. Because it is code, a coding agent can write it,
read its own errors, look at the frames it made and fix them — and you can review the diff.
my-film/code/
├── film.json the running order: tracks of mg / video / audio clips
├── mg/intro.tsx a scene — React + GSAP, every frame a pure function of time
├── assets/ footage, images, audio, fonts (yours, or fetched with `anim` commands)
├── skills/ the manuals your agent reads before it writes
└── AGENTS.md the editor's manual (CLAUDE.md is the same file)
The engine owns the clock. Scenes never run their own timers, so every frame is reproducible:
what you see in the preview is exactly what anim render writes to the mp4.
Quick start
Requirements: Node.js 22+ and ffmpeg on your PATH. The first anim check, look or
render downloads the headless Chromium every frame is drawn with (via Playwright, about 100 MB,
once).
npm install -g animspark
anim new "a 20-second launch video for a note-taking app" --sec 20 --dir notes-launch
cd notes-launch/code
Open the folder in your agent and ask for the film. It reads AGENTS.md and the skills, writes
film.json and mg/*.tsx, and checks its own work with anim check and anim look.
While it works, watch the film take shape:
anim preview
anim preview is a timeline player that follows every save: the picture refreshes in place, the
timeline re-evaluates, and compile or runtime errors appear with links to the exact line in your
editor. It is read-only on purpose — the source is the single place a film changes.
When it's right:
anim render # → .anim-out/film.mp4
Commands
| Command | What it does |
|---|---|
anim new "<brief>" [--sec 30] [--aspect 16:9] | Create a workspace with the manual and skills installed |
anim check [--timeline] | Validate film.json and compile every scene the way the player will |
anim look [--from s --to s] [--fps n] | Contact sheet of frames — how the agent sees pacing |
anim look --at <s> | One full-resolution frame |
anim look --sound | Draw the mix: loudness, which sound sits where |
anim preview [--port n] | Live timeline player in the browser |
anim render [--fps n] [--width px] | Burn the mp4 (and poster, and audio) into .anim-out/ |
anim clip <id> [--format webm|prores|png] | Export one clip, with transparency |
anim mcp | Run as a local MCP server for agents that prefer tools |
anim login | Connect AnimSpark Cloud for voice, sound effects, images and fonts |
Every command takes --help.
How a film is made
film.json is the edit. Clips have a start (at), an optional source window (time) and a
transform; tracks stack top to bottom.
{
"stage": { "w": 1920, "h": 1080 },
"tracks": [
{ "kind": "mg", "clips": [
{ "id": "intro", "src": "mg/intro", "at": 0 },
{ "id": "card", "src": "mg/card", "at": 4.2 }
] },
{ "kind": "audio", "clips": [
{ "id": "bed", "src": "assets/audio/music/bed.ts", "at": 0, "volume": 0.4 }
] }
]
}
A scene is a component. Animate with useGSAP; the host drives the timeline, so seeking to any
frame gives the same picture.
import { useRef } from 'react';
import { gsap } from 'gsap';
import { useGSAP } from '@gsap/react';
export const durationSec = 4;
export default function Intro() {
const root = useRef<HTMLDivElement>(null);
useGSAP(() => {
gsap.from('.word', { yPercent: 120, stagger: 0.08, duration: 0.9, ease: 'expo.out' });
}, { scope: root });
return (
<div ref={root} style={{ position: 'absolute', inset: 0, display: 'grid', placeItems: 'center', background: '#0b0b10' }}>
<h1 style={{ fontFamily: 'Inter', fontSize: 140, color: '#fff', overflow: 'hidden' }}>
{'Write films in code'.split(' ').map((w) => <span key={w} className="word" style={{ display: 'inline-block', marginRight: 32 }}>{w}</span>)}
</h1>
</div>
);
}
Music is code too. assets/audio/music/bed.ts above is a muspark score —
chords, arpeggios, drums, a General MIDI soundfont — rendered to audio on your machine. No
account, no samples to license.
Fonts from a library of 200+ open-licensed families (Latin, Chinese, Japanese, Korean) load by
name — write fontFamily: 'Playfair Display' and the preview and render both fetch it.
Scene libraries ship in the box: formulas, code and scientific plots (@animspark/stem), score
views (@muspark/ui), plus three.js, p5, d3, world-atlas and the rest of the allow-listed npm
packages — charts and maps are drawn straight with d3, and the skills show how.
Voice, sound effects and images
Everything above runs offline. Some things can't be written as code: narration, sound effects,
transcription, stock images. Those are anim commands backed by
AnimSpark Cloud — run anim login once with an API key — or by
your own provider keys through an open provider interface. See docs/cloud.md.
anim audio voice --language en --prompt "warm, confident narrator" # pick a voice
anim audio tts --voice <voiceId> --text "Meet Notes. The fastest way to think."
anim audio sfx --prompt "soft UI click" --sec 1
Use with your agent
anim new writes AGENTS.md and CLAUDE.md, so Claude Code, Codex and Cursor pick up the manual on
their own. Prefer tools? anim mcp exposes check, look, render and the media commands over
MCP. Setup snippets for each agent are in docs/agents.md.
What's in this repository
| Package | |
|---|---|
packages/engine | The anim CLI: check, look, render, clip, preview, MCP, cloud providers |
packages/film-build | Evaluates and compiles films; mixdown |
packages/film-runtime | The runtime scenes run in: clock, useGSAP bridge, useStage, useLocal |
packages/core | The film contract: film.json schema, audio manifests, shared types |
[packages/player](packages/player |
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
packages/engine/prompts/skills/code-explainer/SKILL.md7.8 KBupstream ↗
--- name: code-explainer description: "Animate source code changing between versions and step through execution state in MG scenes." --- Explain code: use `CodeMorph` for source that changes between versions and `ExecutionTrace` for the variables and call stack during line-by-line execution. Import both from `@animspark/stem`. Explain one change or one execution step at a time and keep everything else still. Provide code snapshots and execution records separately; do not mix them in one component. ## CodeMorph Pairs and moves tokens between several complete versions of a source file. Suited to showing refactors, syntax conversions and changes in API usage. The input is source snapshots; the component does not run them. ```tsx <CodeMorph states={['const value = load(url)', 'const value = await load(url)']} filename="loader.ts" lang="typescript" /> ``` ### Providing source snapshots `states` is a `string[]` in order. Each item is one complete source, with lines separated by `\n`; there is no patch format and no diff to provide. Provide at least one snapshot; with only one, the code is shown statically. `progress` goes from `0` to `states.length - 1`: an integer selects one snapshot, and a fraction is the transition between two neighboring snapshots. For example, `1.25` means the second snapshot is a quarter of the way to the third. Out-of-range values are clamped to the first and last snapshots. ```ts const states = [ 'let total = 0\ntotal = total + 3', 'let total = 0\ntotal += 3', 'let total = 0\ntotal += 3\nconsole.log(total)', ]; ``` ### How tokens keep their identity Tokens are paired by "token text + which occurrence of it in the whole source". Matched tokens move to their new line and column; tokens only in the old snapshot fade out, and tokens only in the new snapshot fade in. Tokens take no custom `key`, and there is no analysis of variable scope or the AST. When a variable or symbol with the same name occurs several times, inserting a new occurrence can change the pairing of every later one. Splitting a complex refactor into consecutive small steps reduces wrong visual associations. Tokens move in straight lines and do not route around other tokens. ### Props | Prop | Type | Default and notes | | --- | --- | --- | | `states` | `string[]` | Defaults to two demo sources, `const value = load()` and `const value = await load()`. In real use, provide your own snapshots explicitly. | | `progress` | `number` | Defaults to `0`; the snapshot index, may be fractional. | | `filename` | `string` | Defaults to `example.ts`, shown in the editor title bar. | | `lang` | `string` | Defaults to `typescript`, shown as an uppercase label in the top-right corner; it does not select a different lexer. | | `ref` | `React.Ref<StemHandle>` | Handle to this component instance. | | `style` | `React.CSSProperties` | Size, position and style of the outer box. | | `className` | `string` | CSS class name of the outer box. | ### Example: shortening an assignment ```tsx import { useRef } from 'react'; import { gsap } from 'gsap'; import { useGSAP } from '@gsap/react'; import { CodeMorph, type StemHandle } from '@animspark/stem'; const states = ['let total = 0\ntotal = total + 3', 'let total = 0\ntotal += 3']; export function Example() { const code = useRef<StemHandle>(null); useGSAP(() => { const h = code.current!; gsap.timeline().to(h.P, { progress: 1, duration: 1, ease: 'none', onUpdate: h.render, }, 0.5); }); return <CodeMorph ref={code} states={states} progress={0} filename="sum.ts" lang="typescript" style={{ width: 960, height: 540 }} />; } ``` ### Limits of language support and layout Highlighting uses a simple line-based regex lexer that recognizes common JS/TS/Python keywords, numbers, strings, comments and symbols. Every `lang` shares these rules; multi-line strings, block comments spanning lines and language-specific syntax are not guaranteed to be recognized. Indent with spaces; tabs are not expanded to an editor tab width. The component always draws the editor's dark background, font, syntax colors, line numbers and the snapshot indicator dots at the bottom; there are no `theme`, `fontSize` or `colors` props. The box suits a 16:9 ratio; CSS changes only the outer box and does not replace the inner syntax colors. Code does not wrap or scroll, and the font size does not shrink with longer source. For a long program, excerpt the contiguous part you need to explain so the content does not overflow the box. If you only need a static code card or a completely different editor design, laying it out in ordinary DOM is more direct. ## ExecutionTrace Keeps the source still and shows the current line, variables, call stack and a note from snapshots provided in advance. The component displays an execution; it is not an execution engine and does not work out variable values or call relationships by itself. ### One step is one complete snapshot `code` holds the source string and `steps` holds the execution snapshots. Each snapshot means either "before this line runs" or "after this line runs"; keep one convention throughout. The example below means "after": ```ts const code = 'let total = 0\ntotal += 3\nconsole.log(total)'; const steps = [ { line: 1, vars: { total: 0 }, stack: ['main'], note: 'Initialize total' }, { line: 2, vars: { total: 3 }, stack: ['main'], note: 'Add three' }, { line: 3, vars: { total: 3 }, stack: ['main'], note: 'Print result' }, ]; ``` For a complex algorithm, record the real execution with a script first, then pass the snapshots in as ordinary data. Write the complete current state in every step: omitting `vars` or `stack` shows an empty state; nothing is inherited from the previous snapshot. | Snapshot field | Type | Display behavior | | --- | --- | --- | | `line` | `number` | Source line number starting at **1**; omitted, it points at the first line; out of range, it is clamped to the first or last line. Use integers. | | `vars` | object from variable name to JSON value | Shows the first 7 entries in property order. Objects and arrays are shown as JSON strings. | | `stack` | `string[]` | Call frame names from outermost to innermost; the last frame is the current one. Keep it within 5 frames. | | `note` | `string` | A short explanation of the current step. Omitted, it shows `Executing line N`. | Values in `vars` are strings, numbers, booleans, null, arrays or plain objects; do not pass functions or circular references. Variable names, values, call frames and notes do not wrap. ### `step` is a discrete index `step: 0` is the first snapshot and `step: 1` the second. Fractions are floored and clamped to `0…steps.length - 1`, so `1.8` still shows the second one. Variable values and the highlighted line are not interpolated between snapshots. To switch step by step, use `tl.set(h.P, { step: index }, time)` and redraw in the timeline's `onUpdate`; both forward playback and seeking back then refresh the snapshot. A continuous tween of `step` also plays, but the picture only switches after flooring; when each step must appear at an exact time, set each integer index separately. ### Props | Prop | Type | Default and notes | | --- | --- | --- | | `code` | `string` | Defaults to `const answer = 42`. Separate lines with `\n`; keep the source unchanged during playback. | | `steps` | array of snapshot objects | Defaults to one demo snapshot showing `answer: 42`. In real use, provide your own complete snapshots explicitly. | | `step` | `number` | Defaults to `0`; zero-based snapshot index. | | `filename` | `string` | Defaults to `trace.ts`, shown in the editor title bar. | | `lang` | `string` | Defaults to `typescript`. The prop is accepted but the current rendering does not use it. | | `ref` | `React.Ref<StemHandle>` | Handle to this component instance. | | `style` | `React.CSSProperties` | Size, position and style of the outer box. | | `className` | `string` | CSS class name of the outer boxREADME.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/animspark-animspark-packages-engine-prompts-skills-code-explainer.md