edit
Apply ordered fence edits to project documents, canvases, design systems, and films, returning changed elements, refs, diagnostics, and preview screenshots.
Instructions
Edit the project's documents. text holds one or more fences, applied in order: bl (a canvas, blueprint rows: omit ids for new elements, lead with an id or #ref to modify, delete(#ref) to remove, preview(#a, #b) as a row for a screenshot), html (a canvas, HTML with inline CSS converted to elements), ds (a design system, statements spliced), bm (a film, the whole document replaced). The first row of every fence is file(path): file("Projects/Launch"), file("Styles/default.ds"), file("Motion/Launch.bm"). A call holds fences on any number of documents, canvases included, applied in order, one result entry per fence; a #ref and a // label checkpoint belong to the canvas of their fence. A bl fence's rows apply as they go and the first bad row halts with one line. The answer is the block result: the canvas fact, what changed, the refs, the diagnostics, the notes and a screenshot of the preview row. Pass your sessionId from init. (External MCP clients: call init first for usage docs. Hosted-CLI and sub-agents have docs pre-loaded.)
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "edit"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | The fences: ```<bl|bm|ds|html> on its own line, file(path) as the first row, the rows, ``` on its own line. Several fences in one text apply in order. | |
| project | No | Optional: run THIS call against a project other than the session's bound one: a name or key from list_projects (or an unambiguous name/handle substring), or the absolute path of a project folder (one holding .bl files, or an empty one), which opens in the background and is added to list_projects. Unknown/ambiguous is refused with candidates. | |
| textFile | No | Instead of text: the absolute path of a local file holding the fences, for a block a script generated. Same pipeline and same answer as text, plus a `job:` line. With no requestId the id is a hash of the bytes, so resending the same file after a timeout converges on the first answer; a file whose bytes changed is a new request. Desktop only. | |
| requestId | No | Optional idempotency key. Pass a stable, unique id for this logical request and REUSE the SAME id if you retry after a timeout or relay error: the retry converges on the original result instead of applying a second time. The id is one request: for 2 minutes after a success, a call reusing it with the same text answers the first result, and with different text is refused with nothing applied, so new text takes a new id. | |
| sessionId | No | Your session id from init (refs and design-system state are per session). | |
| background | No | Optional. true answers a `job:` id at once and runs the call on; wait({job}) blocks until it ends and answers its result. An edit waits its turn behind other agents' writes instead of refusing. Use it for a call that may outlast your client's timeout. | |
| designSystem | No | Optional. Design-system mode for this and all later calls (sticky, once set it persists until changed). One of: `"default"` (use the project default DS, token discipline enforced, no bare hex/numerics on tokenizable slots); `"new"` (author your own DS, write a ```ds fence before any bl rows); `"none"` (sovereign, bare hex/numeric values allowed); or the name of a brand YOU authored earlier this session. Omit to keep the current mode (external sessions default to `"none"`). | |
| response_mode | No | Optional. "full" (default) answers the block result with the blueprint of every affected element, or a read handle when that blueprint runs past 50 rows. "compact" answers the block result with a read handle instead of the blueprint, names up to 6 changed elements (past 6, 5 and a count), and keeps every warning, error and new ref. |