# Driving PureAnim from an AI agent

**Status:** Live.
**Editor:** https://flekta.app/app
**This file:** https://flekta.app/agents.md
**Command reference:** https://flekta.app/scripting.md

---

## Who this is for

You are an AI assistant that can control a web browser, and someone has asked you to animate an SVG in PureAnim — something like *"open PureAnim, load my logo, and make the bell swing."*

You do not need an API key, an account, or a PureAnim plugin. The editor has a **script console** that runs authoring commands against the open document, and every control you need to reach it has a stable `data-testid`. Your job is to operate that console.

If you were instead asked to write a script for a human to paste, you only need [scripting.md](https://flekta.app/scripting.md) — stop reading here.

---

## 1. What your browser tooling must be able to do

| Capability | Needed? | Used for |
|---|---|---|
| Navigate to a URL | **Required** | Opening the editor |
| Click an element | **Required** | Menus and the Run button |
| Type into a field | **Required** | Entering the script |
| Read text from an element, or screenshot | **Required** | Reading results back |
| Set a file on a file input | Optional | Loading the user's SVG unattended |
| Evaluate JavaScript in the page | **Strongly preferred** | `window.pureanim`, which replaces most of the clicking |

Chrome DevTools MCP and Playwright MCP both cover all six. A browser tool limited to click / type / screenshot still works — you read results from a screenshot of the log panel, and the user loads their own file.

**Check your tool list first.** In a browser that supports WebMCP, PureAnim registers four tools — `pureanim_get_state`, `pureanim_list_commands`, `pureanim_run_script`, `pureanim_set_time`. If you can see them, use them and ignore the rest of this section; they need no selectors and no setup on your side.

**Otherwise, if you can evaluate JavaScript, use `window.pureanim`.** Same executor, same guarantees, reachable from any browser: one call instead of six interactions, with results returned as JSON instead of read off a screenshot. §2 covers it.

**Do not reach past it into the editor's internals.** `window.pureanim` is the only global PureAnim exposes. The document itself lives in React state you can neither see nor usefully patch, so the API and the script console are the two ways in — and both are complete.

---

## 2. The loop

Every selector below is stable and safe to depend on.

### If you have tools or JavaScript, skip Steps 3–6

The user turns on **Preferences → Allow agent control** once. It is off by default and you cannot enable it yourself — ask them, in those words. That switch is what registers the WebMCP tools and installs the global; until it is on, neither exists.

Four WebMCP tools appear where the browser supports them. `pureanim_run_script` is the one that authors — it takes `source`, the same script you would type into the console. `pureanim_list_commands` returns all 115 command names, so you never have to guess at the surface. To **draw something new** ("add a hamster"), call `api.createLayer({ svg })` with an SVG fragment of paths and shapes — not `pasteLayers`, which cannot parse markup inside the script sandbox. Unsupported markup (gradients, `<style>`, `url()` paints, text) is rejected with a message that says why, and a rejected call changes nothing; see "Shapes" in [scripting.md](https://flekta.app/scripting.md). There is no tool per command on purpose: a script applies as one atomic change that a single undo reverses, and splitting it across calls would cost the user one undo step per command and could leave a half-animated document behind. Batch related edits into one script.

The same four operations are on the page as a global:

```js
window.pureanim.version              // 1 — branch on this if it ever changes
window.pureanim.getState()           // { hasDocument, layers, labels, animationLength, currentTime, canvas: { width, height } }
await window.pureanim.run(source)    // authors, commits, resolves after the change paints
await window.pureanim.setTime(1.5)   // seconds — moves the playhead so you can screenshot a pose
```

`run` hands you the outcome instead of printing it:

```js
const out = await window.pureanim.run(`
  api.setProperty({ layer: "layer-2", prop: "rotate", value: "12deg", at: 20 });
  return api.listLayers();
`);
// { ok: true, value: [...], log: [...], summary: { changed: true, … }, warnings: [] }
```

A `return` in your script comes back as `value`, `console.log` lines come back as `log`, and a failure is `{ ok: false, error, line, code }` with the line number in **your** source. Because `run` resolves only after the edit has painted, a screenshot taken on the next line is already current — no polling.

Steps 1 and 2 below still apply either way: you have to open the editor and get a document into it. If the tools are absent and `window.pureanim` is `undefined`, the user has not switched the preference on (or the build predates it), so ask — and fall back to the console if they would rather not.

### Step 1 — open the editor

Navigate to `https://flekta.app/app`, or to the user's local dev server if they gave you one.

### Step 2 — make sure a document is loaded

**Edit → Scripting is disabled until the project has layers.** If the canvas shows the empty state, load something first:

- **If you can set files on inputs:** put the SVG on `[data-testid="new-project-svg-input"]` (accepts `.svg` and `.json`; opens it in a new project tab). To restore a saved PureAnim project into the current tab, use `[data-testid="restore-json-input"]` (`.json` only). Both inputs are hidden by design — set the file directly rather than clicking them.
- **If your upload tool works by intercepting a file chooser:** click `[data-testid="svg-dropzone"]` first, then supply the path.
- **Otherwise:** ask the user to drag their SVG onto the canvas, and continue once they confirm.

### Step 3 — open the console

Click the **Edit** button in the top menu bar, then the menu item `[data-testid="script-menu"]` (labelled *Scripting*). The docked console `[data-testid="script-dialog"]` appears at the bottom of the editor.

### Step 4 — look before you write

Type into `[data-testid="script-source"]` and click `[data-testid="script-run"]`:

```js
console.log(api.getProjectSummary());
console.log(api.listLayers());
```

### Step 5 — read the result

Two elements carry the output:

- `[data-testid="script-log"]` — everything the script logged, as text.
- `[data-testid="script-result"]` — the outcome line. Its `data-ok` attribute is `"true"` or `"false"`. On failure it reads `Line 12: <message>` with the line number in **your** script.

**This is the only channel that exists.** Command results are returned to your code, not displayed — a script that calls `api.listLayers()` without logging it shows you nothing.

### Step 6 — author, run, verify

Write the real script, run it, confirm `data-ok="true"`, then screenshot the canvas to see the pose. Iterate in the same dialog; it stays open between runs.

---

## 3. Finding the layer the user means

The user says "the bell". The document says `layer-6`. This is the hardest part of the job, and harder than you will expect, so read this section before you touch anything.

**A freshly imported SVG has no meaningful layer names.** Import walks the markup and names every animatable element `layer-0`, `layer-1`, `layer-2` … in document order. The element's own `id` is *not* carried across. `api.listLayers()` returns a `label`, but on a new import it is just the id again — real labels exist only in a saved project where a human renamed things.

So `listLayers()` will not tell you which layer is the bell. What it does give you is structure, and that is usually enough:

- **`type`** is the SVG tag name — `g` for a group, `path`, `circle`, `rect`. The thing a user names ("the bell", "the duck") is very often a `g`, not a leaf.
- **`api.getLayerTree()`** gives nesting and z-order. A three-element group sitting alone at the top of the tree is a far better candidate than the eleventh `path` in a decorative cluster.
- **Probe it.** Set a candidate to `opacity: "0"`, screenshot the canvas, and see what vanished. Undo with `⌘Z` / `Ctrl+Z` — one keystroke reverses the whole run — and try the next one. Two or three probes identify almost anything.
- **Ask.** Showing the user the layer list and asking "which of these is the bell?" costs one turn and beats animating the wrong element.

**Name what you identify.** Once you know, `api.setLayerLabel({ layer, label })` records it on the layer, so the user's timeline reads `bell` instead of `layer-6`, later runs can find it by name, and the saved project keeps it. Do this as a matter of course — it is the most useful thing you can leave behind.

Getting this wrong is the failure a user notices instantly, and no amount of good motion makes up for it.

---

## 4. Things that will trip you up

**Typing the script.** Use your tool's *type* or *fill* action on the textarea. Do **not** set `value` through JavaScript — React does not observe direct property assignment, so the box will look correct and run as empty.

**Time is a percentage.** `at` is `0`–`100`, never seconds or frames. This is what makes scripts duration-independent.

**Values are strings with units.** `"10px"`, `"45deg"`, `"0.5"`. A bare `10` is rejected with an error naming the unit.

**Host globals are blocked.** `fetch`, `document`, `window`, `localStorage`, `eval`, and similar identifiers are rejected before the script runs — including when they appear as property names, so `obj.self` fails. `console` is the exception: it is bound to the console's log panel.

**Nothing is half-applied.** If the script throws, the document is untouched. The log is still returned, so logging before a risky line tells you what the script saw.

**One run is one undo step.** `⌘Z` reverses an entire script, however many commands it ran. A run that changes nothing is not committed at all, so inspecting costs the user no undo history.

**You cannot move the playhead from a script.** Screenshots show whatever time the playhead sits on. Call `window.pureanim.setTime(seconds)` if you have it; otherwise either ask the user to scrub, or read the computed value with `api.getCompiledTimeline({ layer })`. The seek clamps to the work area, so the playhead stays inside the range the user is previewing.

---

## 5. A complete first session

```js
// Run 1 — orient yourself. Changes nothing, costs no undo step.
console.log(api.getProjectSummary());
console.log(api.listLayers());
```

Read `[data-testid="script-log"]`, pick the layer, then:

```js
// Run 2 — a swing on the bell, anchored at its top so it pivots properly.
// `layer-2` came from §3: probed, confirmed, then named.
const bell = "layer-2";
api.setLayerLabel({ layer: bell, label: "bell" });
api.setProperty({ layer: bell, prop: "transformOrigin", value: "top center", at: 0 });
api.setProperty({ layer: bell, prop: "rotate", value: "0deg", at: 0 });
api.setProperty({ layer: bell, prop: "rotate", value: "12deg", at: 20 });
api.setProperty({ layer: bell, prop: "rotate", value: "-9deg", at: 45 });
api.setProperty({ layer: bell, prop: "rotate", value: "5deg", at: 70 });
api.setProperty({ layer: bell, prop: "rotate", value: "0deg", at: 100 });
api.setLayerEase({ layer: bell, ease: "ease-in-out" });
console.log(api.validateProject());
```

Confirm `data-ok="true"`, screenshot the canvas, and tell the user what you did in terms they used — "the bell now swings and settles" — not in command names.

**Read [scripting.md](https://flekta.app/scripting.md) before writing anything beyond this.** It has all the commands, the property channels, and §6 on what separates motion that reads well from motion that is merely correct. Never invent a command that is not listed there.

---

## 6. Setup, for the human

If your assistant cannot control a browser yet, give it one. Cursor has a built-in Browser tool that needs no configuration and is enough for everything above except file upload. For full control, add Chrome DevTools MCP to `.cursor/mcp.json` (or your client's equivalent):

```json
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}
```

To have the agent work in a Chrome window you can watch, start Chrome with `--remote-debugging-port=9222 --user-data-dir=/tmp/pureanim-chrome` and add `--browserUrl=http://127.0.0.1:9222` to those args. Note that enabling the debugging port lets any local program drive that browser, so use a throwaway profile rather than your main one.

Then switch on **Preferences → Allow agent control** in the editor. That is what registers PureAnim's WebMCP tools and exposes `window.pureanim`, and it is the difference between an assistant that works reliably and one that misclicks. It is off by default because it is a standing capability: while it is on, anything running in the page can edit your document. One ⌘Z still reverses any single run, and the setting is remembered per browser, so switch it off when you are done.

WebMCP support is currently Chrome-only, behind an origin trial. In other browsers the registration is a harmless no-op and `window.pureanim` is the route agents take instead. Note that the preference is stored per browser profile, as are your projects — so if your agent's tooling launches its own fresh Chrome rather than attaching to yours, it will find an empty editor with the switch off.

Projects are stored locally in your browser, so an agent running on a remote machine cannot see them — the browser has to be yours.