@pixerate/editor 0.79.0 → 0.81.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.79.0",
+  "version": "0.81.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",
@@ -140,6 +140,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "THIRD_PARTY_NOTICES.md"
   ],
   "sideEffects": false,
@@ -176,6 +177,7 @@
     "@types/dagre": "^0.7.54",
     "@types/markdown-it": "^14.2.0",
     "@types/node": "^24.0.0",
+    "fast-check": "^3.23.2",
     "mermaid": "12.0.0",
     "tiptap-markdown": "^0.8.10",
     "tsup": "^8.4.0",

package/skills/README.md

@@ -0,0 +1,55 @@
+# Agent skills
+
+Each editor domain in `@pixerate/editor` ships an [Agent Skill](https://agentskills.io): a
+`SKILL.md` that teaches a model when and how to use that domain's tools, and the practice an
+expert in the domain would follow. They are published with the package, so an app or agent
+that uses the tools can load the matching skill.
+
+| Skill | Covers |
+| --- | --- |
+| [`pixerate-agent-tools`](pixerate-agent-tools/SKILL.md) | What every editor has in common: the MCP bridge, tool naming and namespaces, `list_commands` / `run_command` / `run_commands`, errors, undo. Load it with any domain skill. |
+| [`pixerate-rich-text`](pixerate-rich-text/SKILL.md) | Documents and prompts: text, tables, find and replace, charts in documents, prompt variables. |
+| [`pixerate-spreadsheet`](pixerate-spreadsheet/SKILL.md) | Cells, ranges, rows and columns, filters, merges. |
+| [`pixerate-canvas`](pixerate-canvas/SKILL.md) | Node-graph canvas, components and variants, arranging, shape booleans, keyframe animation. |
+| [`pixerate-vector`](pixerate-vector/SKILL.md) | Vector paths, styles, gradients, effects, blends, Pathfinder, SVG. |
+| [`pixerate-chart`](pixerate-chart/SKILL.md) | Chart specs, data, series, presets, trendlines, Office and Mermaid charts. |
+| [`pixerate-diagram`](pixerate-diagram/SKILL.md) | Mermaid diagrams: nodes, edges, groups, layout. |
+| [`pixerate-image-editor`](pixerate-image-editor/SKILL.md) | Adjustments, adjustment layers, selections and masks. |
+| [`pixerate-animation-editor`](pixerate-animation-editor/SKILL.md) | Vector animation: shots, commands, timing, Flair and Lottie. |
+| [`pixerate-video-editor`](pixerate-video-editor/SKILL.md) | Non-linear video editing: tracks, clips, transitions, export. |
+| [`pixerate-generation`](pixerate-generation/SKILL.md) | Planning, estimating and running paid media generation. |
+| [`pixerate-parameters`](pixerate-parameters/SKILL.md) | Effect parameters, presets and keyframes. |
+
+## Using them
+
+Copy or symlink the directories into your agent's skills folder, for example for Claude Code:
+
+```bash
+cp -R node_modules/@pixerate/editor/skills/* .claude/skills/
+```
+
+Skills use bare tool names (`get_chart`). A host that namespaces providers exposes them as
+`<namespace>__get_chart`.
+
+## Maintaining them
+
+A skill is part of its domain's agent path (see section 4 of `AGENTS.md`). When you add,
+rename or remove a tool or command, or change how one should be used, update the skill in the
+same change.
+
+- **Format.** YAML frontmatter with `name` (the directory name) and `description` (what the
+  skill covers and when to use it, at most 1024 characters), then: a mental model, a working
+  method, best practices, a tool reference, commands (if any) and pitfalls. Keep `SKILL.md`
+  under 500 lines and move long reference material to `references/*.md`.
+- **Tool tables.** Every tool and command id the domain exposes is the first cell of exactly
+  one table row: `` | `get_chart` | when and how to use it | ``. Say when to reach for it, what
+  it returns, the arguments that matter (with units and defaults) and what to call before or
+  after.
+- **The test.** `packages/core/tests/agent-skills.test.ts` builds every provider and command
+  set and fails when a skill misses a tool, lists one that no longer exists, or a new
+  `create*ToolProvider` / `create*Commands` factory is not mapped to a skill. A new domain
+  gets a new skill directory, an entry in `expectedBySkill()` and `FACTORIES`, and a row in
+  the table above.
+- **Workflows and practice.** The test cannot check advice. When a feature changes the best
+  way to do something (a new batch tool, a new check, a better default), update the working
+  method and best practices too.

package/skills/pixerate-agent-tools/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: pixerate-agent-tools
+description: How to drive any Pixerate editor (rich text, spreadsheet, canvas, vector, chart, diagram, image, animation, video, generation) through its agent tools - finding the right editor over the MCP bridge, reading tool names and namespaces, running editor commands with list_commands / run_command / run_commands, batching with result references, undo, and recovering from tool errors. Use whenever Pixerate editor tools are available, before the domain skill for the editor at hand.
+---
+
+# Driving Pixerate editors with agent tools
+
+Every Pixerate editor exposes the same kind of tool surface: a strict, one-tool-per-operation
+set of MCP tools from its tool provider, plus (where the host registers them) its commands
+through three generic command tools. This skill covers what is common to all of them. Each
+editor domain has its own skill for its tools: `pixerate-rich-text`, `pixerate-spreadsheet`,
+`pixerate-canvas`, `pixerate-vector`, `pixerate-chart`, `pixerate-diagram`,
+`pixerate-image-editor`, `pixerate-animation-editor`, `pixerate-video-editor`,
+`pixerate-generation` and `pixerate-parameters`.
+
+## How tools are named
+
+- Tool names are `snake_case` verbs on a noun: `get_*` / `list_*` / `find_*` / `render_*` read,
+  everything else writes.
+- When several editors register a tool with the same name, or a host gives a provider a
+  namespace, the name is prefixed: `chart__get_chart`, `doc-1__find_text`. Skills use the bare
+  name; match on the suffix after `__`.
+- The annotations are reliable: `readOnlyHint: true` never changes anything, `destructiveHint:
+  true` removes content, `idempotentHint: true` is safe to retry.
+- The tool list changes while you work (an editor mounts, a chart becomes read-only and its
+  write tools disappear). If a tool you used before is gone, list tools again rather than guess.
+
+## Working method
+
+1. **Read before you write.** Start with the domain's `get_*` tool. Write tools take the ids,
+   ranges and positions that read tools return; never invent an id.
+2. **Prefer the specific tool.** A dedicated tool (`set_chart_values`, `add_video_clip`) has a
+   strict schema and a precise error; use generic commands only for what has no tool.
+3. **Batch related edits.** Use the domain's batch tool (`edit_animation`, `edit_video`,
+   `run_commands` with `atomic: true`) so a multi-step change is one undo step and either all
+   applies or none does. Use `dry_run` where offered when you are unsure.
+4. **Use what writes return.** Writes return what they created or changed (new ids, the
+   resulting range or value). Chain on those rather than re-reading the whole state.
+5. **Check, then look.** Run the domain's `check_*` tool and fix every error and warning.
+   Render (`render_*`, `view_editor`) after a batch of edits, not after every edit: images cost
+   tokens, so use them for what text cannot tell you (overlap, legibility, balance).
+6. **Undo your own mistakes** with the domain's `undo_*` tool or the `history.undo` command, not
+   by hand-reverting with more edits.
+
+## Errors
+
+A failed call comes back as an `isError` result whose text says what was wrong and how to fix
+it, with `structuredContent.error.code`:
+
+- `invalid_arguments`: the arguments do not match the schema; `details` names each bad path.
+  Fix the arguments and call again.
+- `tool_failed`: the editor refused the change (unknown id, out-of-range position, read-only
+  target). Nothing was applied. Read the state again, then retry with valid input.
+- `unknown_tool`: the tool is not registered now (the editor closed, or it is read-only).
+
+Never repeat an identical failing call. Never work around a read-only refusal; tell the user.
+
+## Tool reference
+
+| Tool | Use it to |
+| --- | --- |
+| `list_editors` | See which editors are open in the browser and connected to the MCP bridge (id, name, kind, tool count, last activity). Call it first when tools come through the bridge; pass an id or part of a name as `editor` to any tool to pick one when several are open, otherwise the most recently active editor with that tool answers. If none is connected, ask the user to open the app and connect it. |
+| `list_commands` | Discover the commands an editor registers: id, label, group, params JSON Schema, shortcuts, and whether each is enabled now (with the reason when it is not). Filter with `query`; pass `enabledOnly: true` to see only what you can run now. |
+| `run_command` | Run one command by `id` with `params` matching its schema. Disabled commands and unknown params fail with a reason; read it before retrying. |
+| `run_commands` | Run several commands in order as `steps`. A param string `"$0.id"` or `"$last.id"` is replaced by that path of an earlier step's result, so a step can use an id an earlier step created. Pass `atomic: true` and a `label` to make the batch one undo step that rolls back entirely on failure; without it, steps before a failure stay applied. |
+
+## Commands
+
+These history commands are registered wherever a host shares a history with its command
+registry. Domain editors also have their own `undo_*` / `redo_*` tools.
+
+| Command | Use it to |
+| --- | --- |
+| `history.undo` | Revert the last change (one tool call or one atomic batch is one step). |
+| `history.redo` | Re-apply the change you just undid. |

package/skills/pixerate-animation-editor/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: pixerate-animation-editor
+description: How to author and edit vector animations (motion graphics, logo reveals, animated icons, explainer scenes, UI micro-interactions) in the Pixerate animation editor through its agent tools - artwork SVG with ids, shots of commands (enter, exit, draw, move, rotate, scale, fade, morph, Smart Animate match, follow a path, pulse, shake, wiggle), easing and springs, stagger, camera, beat and voiceover cues, drivers, reusable clips, checking, rendering frames and contact sheets, and exporting to Flair or Lottie. Use when animation tools such as get_animation, insert_shots or edit_animation are available, or when asked to animate, time, ease, stagger or export vector motion.
+---
+
+# Pixerate animation editor
+
+A scene is **artwork** (an SVG parsed into vector paths and groups, each with an id) plus an
+ordered list of **shots**. A shot optionally moves the camera, plays its `run` of commands,
+then holds (default 600 ms). Commands play one after another unless `"with": "previous"`;
+each has a default length taken from the content (enter 600 ms, exit 450, move 700, draw
+follows the path length), so leave `duration` out unless you mean to change the pace. Every
+frame is a pure function of time.
+
+Ids: element ids come from `get_animation` (`elements`) or `find_animation_elements`; shot ids
+are ones you choose (`"intro"`); commands are addressed by shot id plus their index in the run.
+Times are milliseconds, positions are document units of the artwork. Anything that enters
+later is hidden until its `enter`; anything that never enters is visible from the start.
+
+For errors, namespaced tool names and the generic command tools, see `pixerate-agent-tools`.
+The full command vocabulary (every type, option and default) is in
+[references/commands.md](references/commands.md).
+
+## Working method
+
+1. **Read.** `get_animation` for elements, shots with timing, clips, drivers and issues. If
+   there is no artwork, `set_animation_artwork_svg` first (give every element you will animate
+   an id), or start from `import_flair_effect` / `import_pptx_animation`. For outlined text,
+   `get_text_layout` shows the letter, word and line units.
+2. **Plan shots, one idea each.** Write down what the viewer should notice in each shot and in
+   what order, then map each beat to a command. Hidden end states (morph / match targets,
+   follow paths) must exist in the artwork before you reference them.
+3. **Write in batches.** `insert_shots` for whole shots; `edit_animation` for several related
+   edits as one undo step (`dry_run: true` first when unsure; `"$0.indexes[0]"` and
+   `"$last.shot"` refer to earlier ops). Refine with `add_commands`, `update_command`,
+   `move_command`, `delete_commands`. Use `write_animation` only to replace every shot.
+4. **Fit and cue.** `fit_animation` to hit a length (keep shots whose pace matters). For music
+   or voiceover, `set_animation_settings` with `beat` or `narration`, read cues with
+   `get_timing_grid`, and give shots `"at": { "beat": n }` or `{ "word": i }`.
+5. **Check.** `check_animation`; fix every error and warning (codes such as `too-fast`,
+   `overlap`, `out-of-frame`, `enter-visible`, `cue-missed`). Use `get_motion_path` for
+   spacing and arcs as numbers.
+6. **Look.** `render_animation_frame` with `shot` + `at: "end"`, or `times` for a contact sheet,
+   plus `onion_skin` / `motion_paths` to see motion in one picture. Render after a batch, not
+   after every edit. `seek_animation` shows the person a moment.
+7. **Export** when asked: `export_flair_motion`, `export_flair_effect` (after
+   `set_animation_controls`) or `export_lottie`; read the returned notes on what was sampled
+   or dropped.
+
+## Best practices
+
+- **One idea per shot, one focal motion at a time.** Stage the action so the eye knows where
+  to look; secondary elements move less, later, or not at all. Use the camera (`frame` a
+  node) to direct attention rather than moving everything.
+- **Ease every change.** Arrivals ease out (decelerate into place; the default for `enter`),
+  exits ease in (`exit` with `ease: "ease-in"`), moves ease in-out (the default). Use `linear`
+  only for mechanical motion (a constant spin, a progress bar) or loops.
+- **Timing by size and distance.** Small UI changes 150-300 ms, element entrances 300-600 ms,
+  large moves and camera moves 600-1200 ms. Nothing under 120 ms (`too-fast`). Big things
+  move slower than small things.
+- **Anticipation and follow-through.** `ease-in-back` for a wind-up before a fast exit;
+  `pop`, `rise`, `ease-out-back` or a spring preset (`spring-gentle`, `spring-quick`) for
+  overshoot and settle on arrival. Use `spring-bouncy` sparingly; it reads as playful.
+- **Overlapping action.** Stagger related items 40-120 ms (`stagger`, or `split` with
+  `cascade` for text) instead of moving them in lockstep; start secondary motion with
+  `"with": "previous"` plus a small `delay` so it trails the lead.
+- **Arcs.** Natural movement curves: use `move` with `via` waypoints (one smooth path) instead
+  of chained moves that stop at each point, or `follow` a path node.
+- **Hold long enough to read.** Leave each result on screen (shot `hold`, default 600 ms);
+  roughly 250 ms per word for text that must be read, longer for the final frame or logo.
+- **Exaggeration with restraint.** Emphasis (`pulse`, `shake`, `teeter`, `color-pulse`) is for
+  one thing that needs attention, once; it returns to rest on its own.
+- **Motion blur** only for genuinely fast motion (`motionBlur: { shutter: 180 }`); it affects the
+  stage and rendered frames, not Flair or Lottie exports.
+- **Accessibility.** Avoid flashing: never more than three flashes a second (WCAG 2.3.1), so
+  keep `color-pulse` and fades on large areas slow and few. Avoid large-scale parallax, zooms
+  and spinning for essential UI motion; ship a reduced-motion alternative (the host should
+  swap in a fade or the end state under `prefers-reduced-motion`; this editor does not
+  generate one). Loops that run longer than 5 s need a way to pause (WCAG 2.2.2).
+- **Interactive pieces.** For a button or toggle set `trigger` (`click`, `hover`, `press`,
+  `scroll`); for a click toggle, make the last shot restore the starting state.
+
+## Tool reference
+
+### Read
+
+| Tool | Use it to |
+| --- | --- |
+| `get_animation` | Start here. Returns name, artwork size, length (ms), loop, elements (id, type, name, parent, bounds, solid paints, live effects with numeric params), every shot with each command's index, start, end and `flairPrimitive`, clips, drivers, controls and an issue summary, plus `readOnly` when edits are refused. `includeElements: false` (default true) skips the element list on large artwork. |
+| `get_shot` | Read one shot as stored (`shot` id) with its start/end and each command's start/end in ms; cheaper than `get_animation` while refining one shot. |
+| `find_animation_elements` | Find elements whose id or name contains `query` (case-insensitive; `limit` default 20, max 200) when the artwork is large. Returns id, type, name, parent, bounds, paints, effects. |
+| `get_text_layout` | Before animating outlined text with `split`: returns the `group`'s lines, words and letter ids in reading order. Errors if the element is not a group of paths (convert text to outlines, one path a letter, and group it). |
+| `get_motion_path` | Check spacing, arcs and landing points as numbers: samples a `node`'s centre (document units) from `from` to `to` ms every `step` ms (default 33, at most 400 samples), with where each moving change starts and ends. |
+| `get_timing_grid` | List beats (number, ms, bar, beat in bar) and narration words (index, text, start, end) between `from` and `to` (`limit` default 200), and which shot plays at each, to choose `at` cues. Empty, with a hint, when no beat grid or narration is set. |
+| `check_animation` | After every batch of writes. Lists issues with a code, severity, shot, command index, node ids, measured vs needed values and how to fix it. Fix errors and warnings; notes are advisory. |
+| `render_animation_frame` | Look at the result: `time` (ms) or `shot` + `at` (`start`, `middle`, `end`; default end). `times` (2-16 moments) makes a labelled contact sheet (`columns` 1-8). `onion_skin` adds ghost frames (`before` default 2, `after` 0, `spacing` ms or `"commands"`); `motion_paths` (true or ids) draws travel paths. SVG by default; `format: "png"` only when the host can rasterize. |
+| `export_flair_motion` | Get the scene as a Flair SvgMotion `{ svg, animate }` with hold, sampled-step count and notes. `fps` (default scene fps, else 30), `curves` and `behaviors` (default true), `flair` target version (default 0.39; older versions get springs, steps, behaviours and curves sampled). |
+| `export_flair_effect` | Get a Flair catalog vector effect (`id` kebab-case, `name`, `description`, `category` default icon, `tags`, plus `curves` / `behaviors` / `flair` as above). Call `set_animation_controls` first so colours become `{{name: color}}` controls. |
+| `export_lottie` | Get Lottie (Bodymovin v5) JSON for lottie-web and mobile players, with a marker per shot, `fps` (default scene fps, else 30), the sampled keyframe count and notes on what was not carried over (gradients, dashes, reveal clips, morphs that change point counts). |
+
+### Write
+
+| Tool | Use it to |
+| --- | --- |
+| `seek_animation` | Show the person a moment: `time` (ms) or the start of a `shot`, with `play` true or false. Does not change the scene. |
+| `set_animation_artwork_svg` | Replace the artwork with a standalone `svg` (with a viewBox) as one undo step. Put an id on every element you will animate; refused if existing shots name ids the new artwork lacks. Returns the elements. |
+| `import_pptx_animation` | Replace the whole scene with a PowerPoint slide's shapes and animation pane (`data` base64 .pptx, `slide` default 1): one shot per click, delays, repeats and acceleration kept; text, pictures and charts are left out with notes. Run with `dry_run: true` first. |
+| `set_animation_drivers` | Replace all drivers (empty list clears): a target's `x`, `y`, `rotation`, `scaleX`, `scaleY` or `opacity` follows a source node's property as change · `factor` + `offset`, optionally `clamp`ed. For parallax, wheels that turn as they roll, shadows that fade as something rises. |
+| `set_animation_clip` | Define, replace or (with `clip: null`) delete a named reusable clip whose `run` targets `"$"`; play it with a `play` command on any nodes. Prefer a clip over repeated identical commands. |
+| `copy_animation` | Give the nodes in `to` every command that animates `from` (all shots or `shots`), each copy starting with its original, optionally `stagger`ed (ms). Quick for one-off duplication; use a clip for motion you will reuse. |
+| `fit_animation` | Make the scene last `seconds` by setting shot `speed`, keeping proportions; shots in `keep` play as written. `dry_run: true` reports the new length and speeds first. |
+| `import_flair_effect` | Replace the whole scene with a Flair vector `effect` or SvgMotion `motion` (give exactly one; optional `name`). Placeholders become colour controls; each Flair step becomes a shot. Use `dry_run: true` first. |
+| `insert_shots` | Add one or more complete shots (`id`, `run`, optional `label`, `camera`, `hold`, `speed`, `at`) at position `at` (default the end). Returns every shot's timing and issues. |
+| `update_shot` | Change one shot's `label`, `camera`, `run`, `hold`, `speed`, `at` or `id` via `set`, and clear `label`, `camera`, `hold`, `speed` or `at` via `remove`. |
+| `delete_shots` | Remove shots by id (one undo step). |
+| `move_shot` | Reorder a shot to index `to` (0 = first). |
+| `add_commands` | Add commands to a shot's run at index `at` (default the end). Returns the indexes they got and their timing; use those indexes for later updates. |
+| `update_command` | Change one command (by `shot` and `command` index): fields in `set` replace, names in `remove` clear (e.g. `"delay"`). Returns the command and its timing. |
+| `delete_commands` | Remove commands from a shot by index; later commands move up, so re-read indexes afterwards. |
+| `move_command` | Move one command to index `to` in its run; a `"with": "previous"` command then starts with its new neighbour. |
+| `set_animation_settings` | Set `name`, `description`, `loop` (none, loop, ping-pong), `trigger` (click, hover, press, scroll, or null), export `fps` (default 30), scene `steps` (12 = on twos; null smooth), `motionBlur`, `beat` (`bpm`, `offset`, `meter`), `narration` word timings, or `target` length [min, max] seconds. |
+| `set_animation_controls` | Set the colour controls (`name`, `type: "color"`, `default` #rrggbb used in the scene, `label`) and `presets` a Flair effect exposes. Replaces existing controls; an empty list clears. |
+| `edit_animation` | Apply several ops (`set_settings`, `insert_shots`, `update_shot`, `delete_shots`, `move_shot`, `add_commands`, `update_command`, `move_command`, `delete_commands`, `set_controls`) as one all-or-nothing undo step; refer to earlier outcomes with `"$0.indexes[0]"`, `"$last.shot"`. `dry_run: true` validates without applying. The default for multi-step changes. |
+| `write_animation` | Replace every shot (and optionally settings, controls, presets) while keeping the artwork. Only for a full rewrite; per-operation tools give better errors. |
+| `undo_animation` | Undo your last edit (one tool call or one `edit_animation` batch). |
+| `redo_animation` | Redo the edit you just undid. |
+
+## Pitfalls
+
+- **Unknown ids are refused** with a "did you mean" suggestion. Take ids from `get_animation` or
+  the elements `set_animation_artwork_svg` returns; never guess them.
+- **`enter-visible`**: an element that enters while already showing blinks out first. Give an
+  element that should appear later an `enter` before anything else moves it; do not `enter` an
+  element that should be visible from the start. `exit-hidden` is the reverse: enter it first.
+- **`overlap`**: two commands changing the same property at once; the later takes over. Sequence
+  them, or use `"blend": "add"` on move, rotate or scale to stack. Emphasis already stacks.
+- **Reveals need a box**: `wipe`, `iris`, `split` on a lone straight line fade instead
+  (`reveal-no-box`); use `draw` / `undraw` for lines.
+- **Morph and match targets stay hidden.** Draw the end state as a separate hidden node or group;
+  for `match`, parts the end state adds need a partner (same name) in the start group, or they
+  never appear (`match-unpaired`).
+- **Draw a group one way.** Do not mix per-stroke drawing (`order`, `pace`, `comet`) with a plain
+  `draw` on the same group in one scene.
+- **Indexes shift.** After `delete_commands` or `move_command`, indexes change; use what the write
+  returned or `get_shot` before the next index-based edit.
+- **Springs set their own length.** Leave `duration` out with a spring; a short `duration` cuts it
+  off (`spring-cut-short`).
+- **Click triggers** play nothing until the first click; each click plays the next shot. A
+  triggered scene ignores `loop` (`trigger-loop`), and clicks decide when shots start, so do not
+  give its shots `at` cues (`click-cue`).
+- **Exports approximate.** Motion blur is never exported; Lottie drops gradients, dashes and reveal
+  clips; back eases on colours or opacity are sampled for Flair. Read the notes and tell the
+  user what changed.
+- **Read-only**: when `get_animation` returns `readOnly`, write tools are hidden; read, render and
+  export still work. Tell the user rather than working around it.

package/skills/pixerate-animation-editor/references/commands.md

@@ -0,0 +1,123 @@
+# Animation command vocabulary
+
+Every command is an object with a `type` and (except `wait`) `targets`: element ids from
+`get_animation`. A group animates as one. Times are ms, distances document units, angles
+degrees clockwise. Commands share names and defaults with Flair's motion primitives
+(`get_animation` shows each command's `flairPrimitive`).
+
+## Fields every command takes
+
+- `targets`: element ids (at least one).
+- `duration`: length per target. Leave it out: each type has a default (below) and `draw`
+  follows the path length. With `repeat`, it is one cycle.
+- `delay`: wait before starting (default 0).
+- `stagger`: start each further target this much later (default 0).
+- `with`: `"after"` (default) starts when the commands before it finish; `"previous"` starts
+  together with the command before.
+- `ease`: a preset (`linear`, `ease`, `ease-in`, `ease-out`, `ease-in-out`, `ease-in-back`,
+  `ease-out-back`, `ease-out-elastic`, `ease-in-elastic`, `ease-in-out-elastic`, `elastic`,
+  `spring`, `spring-gentle`, `spring-quick`, `spring-bouncy`, `spring-slow`, `hold`), or
+  `{ "type": "cubic-bezier", x1, y1, x2, y2 }`, `{ "type": "spring", stiffness (170),
+  damping (26), mass (1), velocity (0) }`, `{ "type": "elastic", amplitude (1), period (0.3),
+  mode (out | in | in-out) }`. Default: cubic ease-out for entrances, ease-in-out for moves.
+  A spring with no `duration` lasts until it settles.
+- `note`: why the command is there, in a few words.
+- `split`: `letter`, `word` or `line` for outlined text (a group of letter paths), staggered
+  40 / 120 / 300 ms per unit; `cascade`: `forward` (default), `backward`, `center`, `edges`,
+  `random` (deterministic).
+- `repeat` (1-1000, not for enter or exit) and `repeatMode`: `loop` (default), `mirror`
+  (every other cycle backwards), `offset` (carry on: rotate by 90 with repeat 4 is a full turn).
+- `steps`: hold poses on a grid of this many frames per second (12 = on twos).
+
+## Default lengths (ms)
+
+enter 600, exit 450, move 700 (+400 per `via` point), rotate 700, scale 500, fade 400,
+style 500, morph 900, match 900, follow 1400, pulse 600, shake 500, teeter 600, wave 1000,
+wiggle 1500, color-pulse 600, effect 900, play (the clip's own length). Shot hold 600,
+camera move 1000.
+
+## Entrances and exits
+
+- `enter` brings hidden targets in. `style`:
+  - `fade` (default); `pop` (scales up past full size and settles; `scale` start, default 0.5);
+    `grow` (from nothing); `slide` (`direction` of travel, default up; `distance` default 40);
+    `draw` (outline drawn on, then the fill fades in); `zoom` (settles from larger; `scale`
+    default 1.6); `rise` (rises a short way, overshooting a touch; `distance` default 20).
+  - Reveals through a clip over the target's box: `wipe` (edge travels `direction`, default
+    right), `iris` (from the centre; `shape` circle or box), `split` (from a line through the
+    middle; `orientation` horizontal or vertical). Need a box with width and height.
+  - Drawing options for groups: `order` (`together` default, or `sequence`), `pace` (`time`
+    or `speed`), `align` (`start` / `end`, with speed), `sortBy` (`document` or `distance`,
+    with sequence), `origin` { x, y } for a radial reveal.
+- `exit` takes targets out. `style`: `fade` (default), `shrink`, `slide` (default down,
+  `distance` 40), `undraw`, `wipe`. Same drawing options as enter.
+
+## Pose and paint
+
+- `move`: `by` { x, y } offset or `to` { x, y } for the centre. `via`: up to 64 waypoints the
+  centre passes through smoothly without overshoot; `pacing` `even` (default, steady speed)
+  or `equal` (same time per stretch). `blend` default replace.
+- `rotate`: `by` degrees or `to` degrees from rest. `blend` default replace.
+- `scale`: `to` a factor or { x, y } (required); `geometric: true` for an even-rate zoom.
+- `fade`: `to` opacity 0-1 (required).
+- `style`: blends solid `fill`, `stroke` (CSS colours, mixed in OKLab) and `strokeWidth`. On a
+  group it changes every path in it.
+- `draw`: draws strokes to `to` (default 1) from `from` (default what is drawn now);
+  `comet`: a travelling stroke this fraction long that runs off the end. Drawing options as
+  enter.
+
+## Shape change and paths
+
+- `morph`: each target takes the shape and paint of node `into` (keep `into` hidden).
+- `match` (Smart Animate): tweens a group into group `into`, part by part. Parts pair by name,
+  then by id with the group ids taken out (`card-a-title` and `card-b-title`), then by kind in
+  order. Unpaired parts fade out; parts of `into` with no partner never appear.
+- `follow`: moves targets along path node `path` (it can be hidden), `from` / `to` fractions
+  (default 0 / 1); `rotate: true` turns with the path, and moves or shakes made meanwhile turn
+  with it.
+
+## Emphasis (returns to rest; `blend` default add, so it stacks on other motion)
+
+- `pulse`: scales up and back; `amount` extra scale (0.15), `count` (1).
+- `shake`: side to side, settling; `amount` (8), `count` (3), `axis` horizontal or vertical.
+- `teeter`: rocks about the centre; `angle` (8), `count` (3).
+- `wave`: bobs without settling; `amount` (6), `count` (2).
+- `wiggle`: smooth seeded noise; `amount` (6), `frequency` Hz (3), `octaves` (2), `rotate`
+  degrees (0), `seed` (default from the target id; the same seed wanders the same way).
+- `color-pulse`: tints `fill` or `stroke` (`paint`) toward `color` (default #f59e0b) and back;
+  `count` (1).
+
+`blend: "add"` on move, rotate or scale makes them a stacking layer too (what they add stays);
+`blend: "replace"` on emphasis makes it take over instead.
+
+## Other
+
+- `effect`: tweens numeric `param` of live path effect `effect` (ids from the element's
+  `effects` in `get_animation`) `to` a value.
+- `play`: plays clip `clip` (defined with `set_animation_clip`, commands targeting `"$"`) on
+  the targets; `speed` (0.05-20, default 1), `delay`, `stagger`, `with`. Clips cannot play clips.
+- `wait`: waits `duration` ms (no targets).
+
+## Shots
+
+`{ id, run, label?, camera?, hold?, speed?, at? }`
+
+- `id` matches `^[A-Za-z0-9_][\w.-]*$` and is unique.
+- `camera`: `{ x, y, width, height }` or `{ frame: "<node id>", padding (24) }`, with `ms`
+  (default 1000), `ease`, `geometric`. The first shot cuts to its camera.
+- `hold`: ms after the commands (default 600).
+- `speed`: plays the whole shot this many times as fast (0.05-20; `fit_animation` sets it).
+- `at`: `{ beat: n }` (2.5 is the "and" of beat 3), `{ word: i }` or `{ ms: t }`; the shot
+  before holds until the cue. Needs a `beat` grid or `narration` set with
+  `set_animation_settings`; `check_animation` reports `cue-missed` when the previous shot runs
+  past it.
+
+## Drivers
+
+`set_animation_drivers({ drivers: [{ target, property, source: { node, property }, factor (1),
+offset (0), clamp: [min, max] }] })`, properties `x`, `y`, `rotation`, `scaleX`, `scaleY`,
+`opacity`. The target's change from rest = source change · factor + offset, added to offsets
+and turns, multiplied into scales and opacity, on top of the target's own commands. Examples:
+parallax (`x` follows `x` · 0.5), a rolling wheel (`rotation` follows `x` · 360 / (2π · radius)),
+a shadow that fades as a ball rises (`opacity` follows `y` · 0.005). Cycles are reported by
+`check_animation` (`driver-cycle`).