canvas-designer

# Canvas Design Skill

Covers all canvas design fundamentals: project management, multimedia principles, AI image generation, web image search, and design marker processing. Video generation on canvas is supported via dedicated reference docs.

---

## Execution

All Python code in this skill runs via `run_sdk_snippet`:

```tool
run_sdk_snippet(
    python_code="""
from sdk.tool import tool
result = tool.call('create_canvas', {"project_path": "my-design"})
print(result.content)
"""
)
```

**Result object:** fields are `result.ok` (bool) and `result.content` (str). Always read tool output from `result.content` — it contains all relevant information including element IDs and error messages. The Result object is not subscriptable; do not use `result['key']`.

---

## Project Concept

Design projects are uniquely identified by `project_path`. All canvas tools require this parameter.

**Canvas selection:** Default to reusing the same canvas project. Only create a new one when the user explicitly says "create new canvas" or "new project". If no project path is specified, find or reuse an existing project first.

**Mentioned project (`[@design_canvas_project:path]`):** When the user message contains a `[@design_canvas_project:path]` mention, the `path` after the colon is the exact `project_path` to use in all canvas tool calls. Use it verbatim — do not truncate, shorten, or rename. Do not call `create_canvas` to make a new project; proceed directly with the mentioned path. The path is workspace-relative and may span multiple levels (e.g. `folder-a/folder-b/my-project`).

---

## Multimedia Principles

**Prohibited:**
- Shell commands for media processing
- Modifying original image or video files
- Deleting canvas elements
- Using file tools (`write_file`, `edit_file`, shell) on `magic.project.js` — use canvas tools only
- Creating separate elements on canvas to fake image editing
- Using general `web_search` to find images for canvas — this fetches webpage snippets, not downloadable images; use `search_canvas_images` instead

**Correct approach:**
- Image content changes → `generate_canvas_images` (creates new element; keep original)
- Web image search for canvas → read [reference/image/image-search.md](reference/image/image-search.md) first, then `search_canvas_images`
- Video generation → `generate_canvas_videos` (see Video Generation section below)
- Recover missing canvas layers from local project media files → only use `restore_canvas_media` when the user explicitly asks to restore/rebuild canvas layers or `magic.project.js` from existing `images/` / `videos/` files
- Original elements and media files must remain unchanged

**Tool priority:**
- Static output (poster, illustration, cover, still image) → image tools
- Web/internet images to place on canvas → `search_canvas_images` (read reference first)
- Dynamic output (video, animation, shot, clip) → video tools (see [Video Generation](#video-generation) below)

---

## Core Tools

### create_canvas

| Parameter | Required | Description |
|---|---|---|
| `project_path` | Yes | Full workspace-relative path for the project. May be a single folder (`brand-design`) or a nested path (`folder-a/folder-b/my-project`). When `[@design_canvas_project:path]` is mentioned, use that exact `path` verbatim. Otherwise, name the folder in the user's language. |

Returns: `{ project_path, project_name }`

### generate_canvas_images

| Parameter | Required | Description |
|---|---|---|
| `project_path` | Yes | Project path |
| `tasks` | Yes | List of image generation tasks; each task produces one image |

**Task object:**

| Field | Required | Description |
|---|---|---|
| `prompt` | Yes | Generation prompt for this image |
| `name` | Yes | Canvas element label. Must be in the user's language and reflect the specific content of this image — name the actual subjects, not the category or a numbered slot. [Correct] name the specific subjects depicted, in the user's language. [Wrong] English slug when the user is Chinese, or a generic category + style number |
| `size` | Conditional | Image dimensions `"WxH"`, e.g. `"2048x2048"`. Required when `reference_images` is empty; omit to auto-read from the largest reference image |
| `reference_images` | No | Reference image paths (workspace-relative). Images inside the project use project-relative paths, e.g. `images/cat.jpg`; images outside the project use workspace-relative paths, e.g. `other-project/images/ref.png`. Omit or pass `[]` for text-only generation |
| `element_id` | No | Existing element ID to overwrite (for retrying a failed placeholder) |

Returns: succeeded element names via `result.content`; when a task fails, `result.content` includes the `element_id` of the failed placeholder for retry.

### restore_canvas_media

Recover missing image/video canvas elements by scanning the current canvas project's local `images/` and `videos/` folders and adding media files that are not already referenced in `magic.project.js`.

**Strict trigger boundary:** Only call this tool when the user clearly and specifically asks to restore/recover/rebuild canvas layers or `magic.project.js` from existing local media files, such as:
- "magic.project.js was overwritten; scan images/videos and add the layers back"
- "restore canvas media from the images folder"
- "recover missing canvas layers from local images/videos"

Do not call `restore_canvas_media` for normal image generation, video generation, image search, canvas editing, layout changes, missing-file debugging, or vague requests like "fix the canvas" unless the user explicitly identifies this local-media recovery need.

**Confirmation rule:** The tool defaults to `dry_run=true`. First call it in dry-run mode and show the user what would be restored. Only call it with `dry_run=false` after the user confirms the recovery.

**Do not operate the canvas during recovery:** From the dry-run preview through the confirmed restore completion, do not call other canvas-modifying to