settled-reach/.claude/skills/frame0-wireframe/references/api-reference.md

Frame0 HTTP API Reference

Frame0 exposes a local HTTP API when the desktop app is running.

Endpoint

POST http://localhost:{port}/execute_command
Content-Type: application/json

Default port: 58320 (override via FRAME0_PORT env var or --port flag).

Request / Response

{"command": "namespace:action", "args": { ... }}

{"success": true, "data": { ... }}
{"success": false, "error": "description"}

---

Type Mapping

Frame0 uses different type names for create vs get:

Create API (type)	Get API (internal)	Description
Rectangle	Box	Rectangle with optional corners
Ellipse	Ellipse	Circle/ellipse
Text	Text	Text label
Line	Line	Line/polyline
Frame	Frame	Container from library
Freehand	Freehand	Freehand drawing
Highlighter	Highlighter	Highlighter stroke

The sync script handles this mapping transparently.

Color Tokens

Frame0 maps hex colors to theme tokens on creation (convertColors: true):

Hex	Token	Role
#1a1e24	$sage3	Background
#2a3040	$slate5	Fill
#333340	$slate6	Stroke
#c8d0e0	$mint12	Text
#c8d8f0	$blue12	Accent

Both hex and token strings work in the API. Tokens are preserved on round-trip.

---

Commands

shape:create-shape

{
  "command": "shape:create-shape",
  "args": {
    "type": "Rectangle",
    "shapeProps": {
      "name": "my-button",
      "left": 100, "top": 200, "width": 120, "height": 36,
      "fillColor": "#2a3040",
      "strokeColor": "#c8d8f0",
      "corners": [4, 4, 4, 4]
    },
    "parentId": "optional-parent-shape-id",
    "convertColors": true
  }
}

Returns: shape ID (string).

shape:get-shape

{"command": "shape:get-shape", "args": {"shapeId": "id"}}

shape:update-shape

{
  "command": "shape:update-shape",
  "args": {
    "shapeId": "id",
    "shapeProps": {"fillColor": "#1a1e24", "text": "Updated"},
    "convertColors": true
  }
}

shape:move

{"command": "shape:move", "args": {"shapeId": "id", "dx": 50, "dy": -20}}

shape:create-connector

{
  "command": "shape:create-connector",
  "args": {
    "tailId": "source-id",
    "headId": "target-id",
    "shapeProps": {"strokeColor": "#c8d8f0"},
    "convertColors": true
  }
}

shape:create-icon

{
  "command": "shape:create-icon",
  "args": {
    "iconName": "search",
    "shapeProps": {"left": 100, "top": 100, "width": 24, "height": 24}
  }
}

shape:get-available-icons

{"command": "shape:get-available-icons", "args": {}}

shape:group / shape:ungroup

{"command": "shape:group", "args": {"shapeIdArray": ["id1", "id2"]}}
{"command": "shape:ungroup", "args": {"shapeIdArray": ["group-id"]}}

edit:delete / edit:duplicate

{"command": "edit:delete", "args": {"shapeIdArray": ["id1", "id2"]}}
{"command": "edit:duplicate", "args": {"shapeIdArray": ["id"], "dx": 20, "dy": 0}}

page:add

{"command": "page:add", "args": {"pageProps": {"name": "Page Name"}}}

Returns: {id, type, name}.

page:get

{"command": "page:get", "args": {"pageId": "id", "exportShapes": true}}

page:get-current-page

{"command": "page:get-current-page", "args": {}}

Returns: page ID string.

page:set-current-page

{"command": "page:set-current-page", "args": {"pageId": "id"}}

doc:get (list all pages)

{"command": "doc:get", "args": {"exportPages": true, "exportShapes": false}}

page:delete

{"command": "page:delete", "args": {"pageId": "id"}}

file:export-image

{
  "command": "file:export-image",
  "args": {
    "pageId": "optional-page-id",
    "format": "image/png",
    "fillBackground": true
  }
}

Formats: image/png, image/jpeg, image/webp, image/svg+xml. Returns: base64-encoded image data.

view:fit-to-screen

{"command": "view:fit-to-screen", "args": {}}

---

Shape Properties

Property	Type	Notes
name	string	Shape identifier/label
left	number	X position (origin: top-left)
top	number	Y position
width	number	Width in pixels
height	number	Height in pixels
fillColor	string	Hex or $token
strokeColor	string	Hex or $token
strokeWidth	number	Border width
fontColor	string	Text color (hex or $token)
fontSize	number	Font size in pixels
fontFamily	string	Font name (Frame0 default: Loranthus)
text	string	Text content
wordWrap	boolean	Enable word wrapping
corners	number[4]	Border radius [TL, TR, BR, BL]
roughness	number	Sketch roughness (Frame0 default: 1)
constraints	array	Auto-sizing constraints
horzAlign	string	Horizontal text alignment
vertAlign	string	Vertical text alignment
fillStyle	string	Fill style (none for transparent)
path	array	Coordinate pairs for lines