canvas

Canvas Skill

Overview

The workspace canvas is an infinite board where you can create, position, and manipulate visual elements. You have two tools:

• `get_canvas_state` -- Read what shapes are on the board, their positions, types, and properties.
• `apply_canvas_actions` -- Create, update, delete, move, resize, reorder, align, or distribute shapes.

Always read the board before making layout-sensitive changes.

Coordinate System

• Origin (0, 0) is at the top-left of the canvas.
• Positive x goes right, positive y goes down.
• All positions and sizes are in canvas units.

Supported Shape Types

• geo -- Geometric shapes (rectangles, ellipses). Props: color, fill, text.
• text -- Text labels. Props: text, color.
• note -- Sticky notes. Props: text, color.
• iframe -- Embedded web content. Requires url (https only). Optional: componentPath, componentName, componentProps.
• image -- Embedded images. Props: src (HTTPS image URL), altText. For local files, copy to .canvas/assets/ and use https://<domain>:5904/<filename> as src.
• video -- Embedded videos. Props: src (HTTPS video URL), altText. Local files work the same way as images via .canvas/assets/.

Reading the Board: get_canvas_state

Returns shapes at three detail levels:

• focusedShapes -- Full detail for shapes near the viewport or focus area. Geo/text/note shapes include color, fill, text. Iframe shapes include url, componentName, componentPath. Image shapes include src, altText, and filepath (local file path in .canvas/assets/, if applicable). Video shapes include src and altText.
• blurryShapes -- Position and basic info for shapes farther away. Iframe shapes include only componentName. Image shapes include src and filepath. Video shapes include src.
• peripheralClusters -- Aggregated counts for distant shape groups.
• summary -- Quick text description of everything on the canvas.

Pass an optional focus_area ({x, y, w, h}) to zoom into a specific region.

Example call with no arguments (uses current viewport):

{"focus_area": null}

Example response:

{
  "focusedShapes": [
    {
      "shapeId": "box-1",
      "shapeType": "geo",
      "x": 100, "y": 100, "w": 200, "h": 150,
      "color": "blue", "fill": "solid", "text": "Frontend"
    },
    {
      "shapeId": "preview-1",
      "shapeType": "iframe",
      "x": 400, "y": 100, "w": 1280, "h": 720,
      "url": "https://<resolved-domain>.replit.dev/preview/hello-world/Card",
      "componentName": "Card",
      "componentPath": "mockup/src/components/mockups/hello-world/Card.tsx"
    }
  ],
  "blurryShapes": [
    {
      "shapeId": "distant-iframe",
      "shapeType": "iframe",
      "x": 5000, "y": 100, "w": 1280, "h": 720,
      "componentName": "Sidebar"
    }
  ],
  "peripheralClusters": [],
  "viewport": {"x": 0, "y": 0, "w": 1920, "h": 1080},
  "summary": "2 shapes on canvas.",
  "focusedOmittedCount": 0,
  "blurryOmittedCount": 0
}

Focused iframe shapes include url, componentName, and componentPath. Blurry iframe shapes only include componentName (no URL or path). Focused image shapes include src, altText, and filepath. Focused video shapes include src and altText. Blurry image shapes include src and filepath. Blurry video shapes include src.

Modifying the Board: apply_canvas_actions

Send an ordered list of actions. Each action has a type field. Results are returned per-action with generated shapeId values.

Create

Set a shapeId so you can reference the shape later.

{
  "type": "create",
  "shapeId": "my-box",
  "shape": {
    "type": "geo",
    "x": 100, "y": 100, "w": 200, "h": 150,
    "color": "blue", "fill": "solid", "text": "Hello"
  }
}

Create Iframe

Embed live web content. The url must use https://.

To get the URL for a Replit dev server, run echo $REPLIT_DOMAINS in the shell to get the domain, then construct the full URL. For the main app on port 5000, no port suffix is needed. For other ports, append :<port>.

Always resolve the actual domain first -- do not pass literal template strings as the iframe URL.

{
  "type": "create",
  "shapeId": "app-preview",
  "shape": {
    "type": "iframe",
    "x": 0, "y": 0, "w": 1280, "h": 720,
    "url": "https://<resolved-domain>.replit.dev",
    "componentName": "App Preview"
  }
}

• url -- Required. Must be https. This is what actually loads content.
• componentPath -- File path shown in the title bar (metadata label only).
• componentName -- Display name shown in the title bar (metadata label only).
• componentProps -- Extra props dict merged into shape props.

To embed individual React components (not just the full app), you need a component preview server that renders each component at its own URL. Use the mockup-sandbox skill to set it up.

Create Image

Embed an image on the canvas.

From an external URL:

{
  "type": "create",
  "shapeId": "hero-image",
  "shape": {
    "type": "image",
    "x": 0, "y": 0, "w": 800, "h": 600,
    "src": "https://example.com/hero.png",
    "altText": "Hero banner image"
  }
}

From a local file (copy to .canvas/assets/, resolve domain, use port 5904):

mkdir -p .canvas/assets
cp assets/hero.png .canvas/assets/hero.png
echo $REPLIT_DOMAINS  # e.g. abc123.replit.dev

{
  "type": "create",
  "shapeId": "hero-image",
  "shape": {
    "type": "image",
    "x": 0, "y": 0, "w": 800, "h": 600,
    "src": "https://<resolved-domain>:5904/hero.png",
    "altText": "Hero banner image"
  }
}

Create Video

Embed a video on the canvas. Local files work the same way as images via .canvas/assets/.

From an external URL:

{
  "type": "create",
  "shapeId": "demo-video",
  "shape": {
    "type": "video",
    "x": 0, "y": 0, "w": 1280, "h": 720,
    "src": "https://example.com/demo.mp4",
    "altText": "Product demo video"
  }
}

From a local file:

cp assets/demo.mp4 .canvas/assets/demo.mp4

{
  "type": "create",
  "shapeId": "demo-video",
  "shape": {
    "type": "video",
    "x": 0, "y": 0, "w": 1280, "h": 720,
    "src": "https://<resolved-domain>:5904/demo.mp4",
    "altText": "Product demo video"
  }
}

Update

Only include the fields you want to change. Always set shapeType to the shape's type (from getcanvasstate).

{
  "type": "update",
  "shapeId": "my-box",
  "updates": {"shapeType": "geo", "color": "red", "text": "Updated"}
}

Delete

{"type": "delete", "shapeId": "my-box"}

Move

{"type": "move", "shapeId": "my-box", "x": 300, "y": 200}

Resize

{"type": "resize", "shapeId": "my-box", "w": 400, "h": 300}

Reorder (Z-index)

Direction: "front" or "back".

{"type": "reorder", "shapeId": "my-box", "direction": "front"}

Align

Align multiple shapes. Options: "left", "center-horizontal", "right", "top", "center-vertical", "bottom".

{
  "type": "align",
  "shapeIds": ["box-1", "box-2", "box-3"],
  "alignment": "center-horizontal"
}

Distribute

Evenly space shapes. Direction: "horizontal" or "vertical".

{
  "type": "distribute",
  "shapeIds": ["box-1", "box-2", "box-3"],
  "direction": "horizontal"
}

Iframe Rules & Gotchas

• URL must be `https` -- http and about:blank are rejected.
• Resolve the domain first -- run echo $REPLIT_DOMAINS in the shell, then build the URL from the result. Never pass a literal template string as the URL.
• Port rules: no port suffix = port 5000 (main app). For other servers, append :<port>.
• External sites may block embedding -- sites with X-Frame-Options: DENY or restrictive CSP headers will show a blank iframe. Replit dev URLs work fine.
• For component previews, use the mockup sandbox -- do not embed the main app's dev server URL to preview individual components. The main app URL shows the entire app with navigation, layout, and routing — not an isolated component. Use the mockup-sandbox skill to set up a preview server, then embed /preview/{folder}/{Component} URLs. This gives you isolated components that can be iterated on independently.

Placeholder Workflow

Since iframe URLs must be https (no about:blank), to plan a layout before you have real URLs:

1. Create geo shapes at the desired positions with labels describing what goes there.
2. Once you have the real URLs, delete the geo shapes.
3. Create iframe shapes at the same positions with the actual URLs.

Typical Workflow

1. Call get_canvas_state to see what's on the board.
2. Use the summary and focusedShapes to understand positions and IDs.
3. Call apply_canvas_actions with a batch of changes.
4. Communicate and offer to show -- Tell the user what you placed and where, referencing shape names or labels so they can orient themselves. Then ask if they'd like you to focus on the new or changed shapes (e.g. "Want me to pan to the new layout?"). Don't auto-focus -- moving the viewport while the user is working is disorienting.
5. Show on request -- When the user confirms, call focus_canvas_shapes with the IDs of all relevant shapes. Use animate_ms: 500 for a smooth transition.

Error Codes

• SHAPE_NOT_FOUND -- Shape ID doesn't exist.
• UNSUPPORTED_SHAPE_TYPE -- Invalid shape type.
• INVALID_PROPS -- Bad property values (e.g., non-https iframe URL).
• VALIDATION_FAILED -- Shape with that ID already exists.
• INSUFFICIENT_SHAPES -- Not enough shapes for align/distribute.

Best Practices

1. Read before writing -- Always call get_canvas_state before layout-sensitive changes.
2. Set shapeId on create -- So you can reference, update, or delete the shape later.
3. Offer to show your work. After creating or significantly modifying shapes, don't auto-focus the viewport -- the user may be looking at something else and sudden panning is disorienting. Instead, finish your work and ask the user if they'd like to see it (e.g. "Would you like me to focus on the new shapes?"). When the user confirms, call focus_canvas_shapes on the affected shape IDs with animate_ms: 500 for smooth transitions. After a batch of creates, focus on all new shape IDs together in a single call.
4. Batch actions -- Group related changes in one apply_canvas_actions call.
5. Use https URLs -- Iframe shapes reject http URLs.
6. Label iframes -- Set componentPath and componentName so users can identify embedded content.
7. Use focus_area -- For large boards, pass a region to get_canvas_state to get detail where you need it.

Viewport Presets

• Mobile: 390 x 844
• Tablet: 768 x 1024
• Desktop: 1280 x 720