68 lines
2.5 KiB
Markdown
68 lines
2.5 KiB
Markdown
# CanvasOperationPlan reference
|
|
|
|
## Required envelope
|
|
|
|
Every request passed to `yedir_apply_canvas_operation` has this shape:
|
|
|
|
```json
|
|
{
|
|
"canvasId": "canvas UUID",
|
|
"operationPlan": {
|
|
"version": 1,
|
|
"operationId": "stable unique ID",
|
|
"operation": "create_text_node",
|
|
"projectId": "same canvas UUID",
|
|
"baseCanvasRevision": "updatedAt from yedir_get_canvas",
|
|
"baseCanvasUpdatedAt": "updatedAt from yedir_get_canvas",
|
|
"textContent": "Example"
|
|
}
|
|
}
|
|
```
|
|
|
|
`operationId` is the idempotency key. Keep it stable across retries of the same logical write.
|
|
|
|
## Operations
|
|
|
|
| Operation | Required fields | Notes |
|
|
| --- | --- | --- |
|
|
| `create_agent_slot` | `slot` | `slotType` is `image`, `video`, or `ui-screen`. |
|
|
| `create_text_node` | `textContent` | Optional `targetPosition` or placement fields. |
|
|
| `fill_slot` | `targetSlotId`, `media` or `mediaItems` | Media type must match the slot. |
|
|
| `insert_beside` | `anchorNodeId`, `media` or `mediaItems` | Preserves the source. |
|
|
| `append_revision` | `sourceNodeIds`, `media` or `mediaItems` | Preferred for revised media. |
|
|
| `replace_node_media` | target, media, `confirmed: true` | Destructive; require explicit confirmation. |
|
|
| `add_annotation` | target and `textContent` or `annotations` | Annotation types: text-note, arrow-note, box, freehand, crop-box. |
|
|
| `link_nodes` | at least two `targetNodeIds` | Optional `edgeType`. |
|
|
| `move_nodes` | targets, `targetPosition`, `confirmed: true` | Require explicit confirmation. |
|
|
| `delete_nodes` | targets, `confirmed: true` | Require explicit confirmation. |
|
|
| `rename_node` | target and `textContent` | Changes the node title. |
|
|
| `update_note` | target and `textContent` | Updates note content. |
|
|
| `update_text` | target and `textContent` | Updates a text node. |
|
|
|
|
Use `targetNodeIds` for mutations, `sourceNodeIds` for provenance, and `anchorNodeId` for relative placement. A request may reference at most 20 nodes or media items.
|
|
|
|
## Placement
|
|
|
|
- `placement`: `right`, `left`, `below`, `above`, or `viewport-center`.
|
|
- `placementStrategy`: `single`, `row`, `grid`, `overlay`, or `beside_each_source`.
|
|
- `layoutStrategy`: `row`, `column`, or `grid`.
|
|
- `spacing`: positive number up to 240.
|
|
|
|
## Media item
|
|
|
|
```json
|
|
{
|
|
"mediaItemId": "stable item ID",
|
|
"type": "image",
|
|
"url": "https://public-or-signed-media-url",
|
|
"assetId": "optional UUID",
|
|
"width": 1024,
|
|
"height": 1024,
|
|
"title": "Result",
|
|
"prompt": "source prompt",
|
|
"sourceNodeIds": ["source node ID"]
|
|
}
|
|
```
|
|
|
|
Only HTTP and HTTPS media URLs are accepted.
|