Motion by Frapea

PLAY IT THROUGH. Puts the composition on the user's stage and plays it from frame 0 through the real preview — the path a person watches, which inspect_composition does not take — from the first frame to the last. Buffering is fine; any error ends it. Answers within about 20 s: {status:"running", at, total} means call again with the same id to keep waiting (it continues the same run). Then {status:"done", verdict:"ok"|"problems", problems, warnings} or {status:"incomplete", reason} — hidden (ask the user to bring the tab to the front), interrupted, edited. A piece is not finished until this says ok. It takes over the stage while it runs, so tell_user first.

Closes a composition and removes it from the user's tabs. Use it to clear up attempts you made along the way — an agent that leaves ten of them behind has handed the user the tidying. Needs an explicit id; it will never guess the active one.

Pairs you with a Motion browser tab. The user has an eight-character code on screen, under the Connect MCP button — something like K7M4-P2Q9. Call this once at the start. It returns a session token; pass that token to every other tool. The code itself stops working the moment it is used, so keep the token, not the code.

Writes a new composition and opens it as a tab in front of the user. `files` maps path to TSX source and must include the entry (default composition.tsx). Read read_skill {topic:'motion'} and {topic:'motion-craft'} first — this API is not guessable and the craft guide is what stops the result looking generated. Aim well beyond a slide deck. With UI-like parts, write them in their own file with a partsBoard prop (default false) and check the board before building scenes.

Starts a Motion session WITHOUT the user having a tab open. Use this when they have no pairing code — you can create and edit compositions immediately, and give them the returned link when they want to watch. Anything needing to SEE the result (inspect_composition) or touching their media still requires them to open it: send them the link, then call wait_for_tab rather than asking them to report back. The scene is kept for 24 hours after the last change.

One composition in full: manifest, every source file, and current prop values. Read this before update_composition so you edit what is actually there.

The raw bytes of one file, base64. Capped at about 600 KB — for anything larger, and for every video, use inspect_media instead: it answers what is IN the file for a fraction of the size.

WHAT WENT WRONG in the user's tab: frames that failed to render (with the frame and the engine's own words), a preview that stopped moving (and at which frame, and why), compositions that would not load, clips that will not decode, missing footage, failed exports, a page the browser killed — plus warnings (notes about unread styles and the like). Call it FIRST when the user says something is broken or looks wrong. Works while the tab is hidden or closed: the tab sends what it saw to the session as it happens. `current` belongs to the composition as it is now; `earlier` counts problems an edit has since left behind. New problems also arrive on their own: any tool result may carry a `problems` list of what is new since you last heard. An empty list only covers what the tab has actually played — run check_playback for a full pass.

LOOK AT WHAT YOU MADE. Renders frames of a composition and returns them as one labelled contact sheet. Pass atFrames (up to 12), or omit them: the sheet is then an even spread PLUS the joins between your scenes (labelled "end of a scene", "start of a scene", "mid transition") — where a card caught half-way or an empty gap hides. ONE frame comes back large (1560 px), two at 960 — ask for one when you need to see detail: padding, a label off centre, a fill over its border. `props` are merged over the composition's for this picture only — {partsBoard:true} draws the parts board without changing anything. Each frame reports its content share (how much is not background) — compare frames of one piece: one far below its neighbours is usually a gap between scenes. Use it after every create or update — timing, spacing and whether text fits are things you cannot verify by reading your own source.

Looks INSIDE a file. Returns ONE contact sheet — every requested moment as a labelled cell in a single grid image. Pass atSec (up to 12 timestamps, seconds); omit it for an even spread across the whole clip. This is how you analyse a video second by second without paying for a dozen separate images.

The compositions open in the tab, and which one is on screen.

The user's media library: folders, and files with id, name, kind, size and folder. `storage` says whether a file is 'linked' (still on their disk) or 'copied' (held by the browser) — a linked file can need the user to re-grant access after a reload.

Library housekeeping. action: 'move' (ids + toFolder), 'delete' (ids), 'createFolder' (name + optional parent), 'deleteFolder' (folder — the files inside move up one level, nothing is lost).

Adds a file to the library from a URL — the BROWSER fetches it, so nothing travels through this connection, but it only works on https hosts that send CORS headers. TO UPLOAD A FILE YOU ALREADY HAVE ON DISK, DO NOT USE THIS: run `curl -X POST --data-binary @FILE 'BRIDGE/media/upload?token=TOKEN&name=NAME'` from your shell instead (up to 10 MB). Reading a file into `data` costs hundreds of thousands of tokens for something curl streams for free; `data` is for small generated assets only.

Motion's authoring guides. Read {topic:'motion'} first — it is the API contract: what compiles, what resolves, what renders. Then {topic:'motion-craft'} ALWAYS before writing a line, because the API guide alone produces compositions that render correctly and look generated. 'motion-text' for typography, 'motion-effects' for named looks, 'motion-transitions' for sequencing scenes inside one composition. 'motion-examples' before choosing a look: two whole pieces that look nothing alike. 'motion-workflow' is about working while someone watches: showing progress, and checking your own frames for overflow — read it before a job of more than one scene. 'motion-review' is the argument that makes a piece better than its first draft: a creative director, a designer and a marketer judge your frames in rounds — read it for anything with an audience and a purpose.

Sets prop values on a composition — the same values the user's controls change. Merged, so you can send one key.

PUT A SENTENCE ON THEIR SCREEN, as you work. They are watching the Motion tab while you build, and between your tool calls it shows nothing — a busy agent and a hung one look identical from there. Call this at every step that takes more than a few seconds: what you are about to do, what just landed, what you had to fix. Write like a person talking to someone over their shoulder, one sentence, no jargon. kind:'done' when the whole job is finished and kind:'problem' the moment you are stuck — those are the two endings they are waiting for. Read read_skill {topic:'motion-workflow'} for how this fits the rest.

Edits an existing composition. `files` is MERGED by path, so send only what changed. Changing the schema keeps any prop values that still have a home.

WAIT UNTIL THEY HAVE MOTION OPEN. Everything that has to SEE a composition — inspect_composition, and anything touching their media — runs in their browser, so it needs the tab. Ask them to open the session link, then call this instead of asking them to tell you when it is ready. It returns as soon as the tab connects, or after about 25 seconds with tabConnected false — in which case call it again, or give up and say so. Do not spin on it: two or three waits, then tell them you are waiting and stop.