Animation - step-based explainer diagrams

.anim.json files open in Nimbalyst's Animation editor: a named scene plus an ordered list of steps that assign states to the scene's parts. You write plain JSON. Any agent can author or edit one with Write and Edit -- there is no binary format and no tool call required.

When to use this

• Explaining how a system behaves over time: a request crossing a network, a consensus round, a cache filling, a build pipeline, a queue draining.
• Turning a static architecture diagram into something that plays.
• Showing a failure and a recovery: the retry, the rollback, the rejected review.

Do not use it when a static diagram says the same thing. If nothing changes between the first frame and the last, you want Excalidraw or a Mermaid block, not an animation.

The mental model

Three rules drive every decision in this format:

1. The document says what is true when, never how to tween. There are no keyframes, easing curves, or property tracks. You assign a state to a part, and CSS transitions interpolate. Adding motion means naming a state, not scripting a timeline.
2. States are cumulative. A step asserts only what changes; every part it does not mention keeps whatever the previous step left it in. Write deltas. To turn something off you must explicitly set it back -- it will not decay on its own.
3. Ids are names, not handles. store, title-card, queueTask01. You will reference them constantly in set blocks; make them readable.

Times are integer milliseconds. Never frame indices, never floats.

Document structure

{
  "version": 1,
  "stage": { "width": 1200, "height": 640, "fps": 25 },
  "parts": { "<id>": { "type": "node" | "edge" | "label" | "shape", ... } },
  "steps": [ { "id": "...", "duration": 800, "caption": "...", "set": { ... } } ]
}

stage