Tool Reference

Create a new session. Returns a URL the user opens in their browser. Once connected, all design tools execute in real-time. Only one session is active at a time.

// Create a session
create_session({ label: "Landing page design" })
// → Returns { designUrl: "https://efecto.app/design?session=abc123" }

Check if the browser is connected, pending calls, etc.

Close the active session. Disconnects the browser and cleans up.

Returns the full document as JSX-like markup. Each element has a data-id for referencing in other tools. Always call this before modifying an existing design.

Returns the currently selected nodes with serialized JSX subtrees. Use to understand user context before making edits.

Lists all artboards with IDs, names, dimensions, and positions.

Search for nodes by name, text content, type, or className.

Returns JSX for a specific node or artboard subtree (faster than get_document for one section).

Creates a new artboard. Set className to "flex flex-col" for vertical layout.

create_artboard({
  name: "Desktop",
  width: 1440,
  height: 900,
  className: "flex flex-col",
  backgroundColor: "#ffffff"
})

Adds a complete section from JSX-like markup. Most efficient for complex layouts.

add_section({
  parentId: "artboard-1",
  jsx: `<section className="flex flex-col items-center justify-center py-24 px-8 bg-black text-white">
  <h1 className="text-6xl font-bold tracking-tight mb-4">Build faster</h1>
  <p className="text-xl text-gray-400 max-w-2xl text-center">Ship beautiful products with AI-powered design.</p>
  <button className="mt-8 px-8 py-3 bg-white text-black rounded-full font-medium">Get Started</button>
</section>`
})

Adds a single node to the document tree.

Replaces an existing node with new JSX content in-place. Preserves position in parent.

Updates properties of an existing node. Only specified properties are changed.

update_node({
  nodeId: "node-abc123",
  textContent: "New heading text",
  className: "text-4xl font-bold text-white"
})

Updates only the className of a node. Replaces existing className entirely.

Updates multiple nodes in a single call. Efficient for bulk changes.

batch_update({
  updates: [
    { nodeId: "node-1", textContent: "Updated" },
    { nodeId: "node-2", className: "text-red-500" },
  ]
})

Updates artboard properties (resize, rename, change background).

Sets the fill (background) of a node or artboard. Supports solid colors, gradients, and images. Handles dual-write automatically.

Moves a node to a new parent or reorders within current parent.

Duplicates a node and all its children. Inserted after the original.

Duplicates an entire artboard with all content. Creates a deep copy with fresh IDs.

Groups selected nodes into a new frame container.

Ungroups a frame container, moving its children up to the parent.

Changes z-order: "front" = bring to top, "back" = send to bottom.

Deletes one or more nodes and all their children.

Deletes an artboard and all its contents.

Creates a new blank document, replacing the current one. Discards unsaved changes.

Renames the document.

Undoes the last action (Cmd+Z).

Redoes the last undone action (Cmd+Shift+Z).

Zooms the viewport to fit all artboards. Useful after creating multiple artboards.

Zooms the viewport to fit a specific artboard.

Selects nodes on the canvas to highlight for the user. Empty array deselects all.

Deselects all currently selected nodes.

Shows or hides a node. Hidden nodes remain in the tree but are not rendered.

Aligns multiple nodes along a shared axis.

Distributes nodes evenly with equal spacing.

Repositions an artboard on the canvas. Use to lay out multi-screen flows (e.g. Desktop at 0,0, Tablet at 1540,0).

Sets the viewport zoom level and/or pan position. Zoom 1.0 = 100%.

Exports an artboard or node as an image (PNG, JPEG, WebP, SVG). Returns base64 data URL.