8.5 KiB
ADR 0097: Command macros (saved commands)
- Status: accepted (2026-11-14)
- Relates to: roadmap M6 (command macros), ADR 0001 (undo over persistent snapshots), ADR 0004
(destructive actions), ADR 0017 (WebAssembly plug-ins and
plugin_may_call), ADR 0065 (templates: files in the settings folder the shell passes in), ADR 0073 (groups refuse timeline commands), ADR 0016 (auto-keying motion tweens)
Context
Animate users repeat the same few edits all day (rotate, fade, nudge, add a keyframe, set an ease) and expect to keep them: in Animate's History panel they select steps and choose Save As Command; the command then appears at the end of the Commands menu, can get a keyboard shortcut, and Manage Saved Commands renames and deletes them. Run Command… runs a command file someone sent. Behaviour was learnt from Adobe's public help pages for the History panel and the Commands menu and by observation; no Adobe code, file format or asset was used (Animate stores JSFL scripts; ours are JSON lists of registry commands).
Everything in AniCraft is already a registry command, so a macro is naturally "these command ids with these params, in order". The questions were: where the steps come from, what a step that names this document's things (element and layer ids) means elsewhere, what a macro may call, how a run stays one undo step and transactional, where the files live, and how macros get shortcuts from a shortcut map whose actions are all known at build time.
Decision
-
History records the commands of each step.
history::Snapshotgainscommands: Option<Arc<[Recorded]>>, the(id, params)of every top-level mutating command that changed the document since the previous step: one for a plain edit, all of them for a gesture (a drag), the marquee's provisional cut and the edit that used it together. Undo and redo carry them with the label. A live preview's revert drops what it reverted; undo, redo, healing a cut and opening a document drop what wasn't recorded. Consecutive plainelement.translate {dx, dy}add up into one, so a drag of 600 moves is one step. A step keeps at most 4096 commands and 1 MiB of params (Nonepast that: "too many to keep"), and the bytes count against the undo budget. Nested commands (a plug-in's, a macro's) are not recorded on their own:macro.runrecords its steps (Session::record_as), so a run can be saved again with other steps;plugin.runrecords itself and therefore can't be kept. -
Steps are rewritten to act on the selection, or refused with the step named. Save As Command never stores ids of this document's things. For each recorded param in
TARGETS(layer(s),element(s),id(s),shape,path,symbol): it is dropped when the command's params doc marks it optional (key?) and, but for layers, says its default is the selection; the step then acts on the selection or the active layer. Any other target, and any param inFIXED(bitmap,sound,folder,bone,parent,items, and a bone'sfrom/to), refuses the step: "step 4 “Move Points” can't be kept: it works on particular objects of this document". The params docs are the contract the registry already keeps for every command (the guide's command reference is generated from them); a test pins the behaviour on representative commands. Selections and the playhead are not steps (selection commands don't change the document), so a macro runs on whatever is selected, as in Animate. -
A macro may call what a plug-in may, and never
macro.*.macro_may_callisplugin_may_callplus themacronamespace refused. So macros never open or write files, use the clipboard, undo, change preferences or run plug-ins or other macros (no recursion), and plug-ins may not call anymacro.*command (reading files and running macros is outside the sandbox). The rule is checked when a file is read and again before each step runs. -
A run is one undo step and transactional.
macro.runis a mutating command whose steps run throughexecute_nested(checked and atomic, no history of their own). At the first failing step it returns "“Turn and Fade” stopped at step 3 of 3 (Taller row): … Nothing was changed." andSession::executeputs the document, selection and playhead back. The step is labelled with the macro's name.execute_nestednow also refuses timeline commands inside an open group (asexecutedoes, ADR 0073) and finishes each command's motion-tween auto-key on its own, so a step in a macro keys a tween exactly as the command alone does (plug-in runs benefit too). -
Files: one small JSON file per macro in the settings folder.
Commands/<name>.json={"format": "anicraft-command", "version": 1, "steps": [{"cmd", "params", "label"}]}. The file's name is the macro's name (no name inside to go stale when a file is renamed or shared); a bare JSON array of{cmd, params}(ananicraft-cli runscript) reads too, andcommandis accepted forcmd(the MCP spelling). Reading is bounded: 1 MiB, 1000 steps, known commands only, object params, labels cut to 200 characters without control characters; a newer version is refused with a clear message. The order of the Commands menu isCommands/.order.json(a dot name no macro can have); files not in it follow by name. Names follow the template rules (no path characters, no Windows device names). As with templates (ADR 0065) the shell passes the folder (platform::commands_dir,ANICRAFT_COMMANDS_DIRfor tests); screenshot runs use a temporary folder; the browser build has none yet. -
Commands.
macro.run {name + folder | path | steps}(Commands › Run Command…, asks for a file),macro.list {folder}(Commands › Manage Saved Commands…),macro.history(every history step as Save As Command keeps it:keep,why,rewritten),macro.save {folder, name, history | steps},macro.rename,macro.move,macro.deleteandmacro.import. Replacing a file asks first and deleting always does (ADR 0004: undo can't bring a file back), for every front end. Everything works headless:anicraft-cli exec doc macro.run '{"path": …}',anicraft-cli run doc macro.json(it reads either format) and MCP'sanicraft_run. -
Shortcuts through the existing map. A macro is an action
macro:<name>in the "Commands" group of Keyboard Shortcuts, bound, reset and checked for clashes like any other; Manage Saved Commands' Shortcut… opens the editor on it, already waiting for the keys. Actions are&'static strthroughout the map and the editor, so macro names are interned once each (bounded at 4096 distinct names a run) rather than reworking the shortcut system for owned strings. Bindings live in the preferences under the action id and survive a start before the folder is read; a rename moves them, a delete drops them; a chord bound twice by a hand-edited file stays with the action listed first. -
Desktop flow. In the History panel Ctrl+click picks steps and Shift+click a range (a plain click still travels); a step's context menu picks it or saves it. Save As Command… (the panel's footer, or the context menu) shows the picked steps with what was rewritten and why a step can't be kept, and asks for a name; Save is disabled until every step can be kept. Saved macros appear at the end of the Commands menu with their keys. Manage Saved Commands lists them with Run, ↑/↓ (reorder), Shortcut…, Rename…, Delete… and Add from File….
Consequences
- Every undo step costs a few more bytes (its commands' JSON), counted in the undo budget.
- A step whose params name document things the command can't do without (moving particular path points, painting bone weights, placing a particular Library item) can't be saved; the message says which step and why. Steps that ran as plug-ins can't be saved either.
- The rewrite relies on params docs following the
key?and "default: the selected …" conventions; a new command that names an element without saying so is refused, never replayed wrongly. - Interning keeps each macro name for the life of the process (bytes per name).
Not yet
Replaying picked steps without saving them (Animate's Replay), a slider for travelling history separately from picking, macros in the browser build (no folder) and the command palette, editing a macro's steps or params in the app, recording selection changes as steps, and macros that ask for a value when they run.