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)
- 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.

---

## Canvas Rules

**Image operations:**
- Do not modify original image files — all content changes must create new elements
- Do not delete elements
- Do not alter image content through element properties
- Use `generate_canvas_images` for any content change; keep original elements intact
- "Add X to image" = image-to-image generation, not placing a separate element on canvas

**Workflow:**
- Default to reusing the existing canvas project; only create a new one when the user explicitly asks
- Never assume file paths — always use paths obtained from query results
- For image-to-image: use `visual_understanding` to analyze the reference image first — it returns both content description and dimensions. Use the description to inform your prompt; `size` can be omitted when reference images are provided (auto-resolved from the largest one), or set explicitly if the user wants a different output size.
- When the user references a canvas image, always call `visual_understanding` to understand its content before generating. This ensures your prompt accurately describes what to preserve and what to change.

**Generation timeout handling:**
- `run_sdk_snippet` automatically enforces a minimum 10-minute timeout for `generate_canvas_images` calls. You do not need to pass `timeout` unless the task is expected to take longer than 10 minutes.
- If a task fails, the result content includes the `element_id` of the failed placeholder. Pass that `ele