> ## Documentation Index
> Fetch the complete documentation index at: https://opencanvas.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# What Is the DesignJS Canvas?

> Understand how DesignJS renders real HTML/CSS in a GrapesJS iframe, how components are structured, and how human and agent edits stay in sync.

The DesignJS canvas is a live HTML/CSS rendering environment embedded in your browser. When you drag a block onto the canvas or when an AI agent calls `add_components`, the result is real HTML being rendered inside an iframe — not a vector shape, not a preview approximation. The same HTML that appears in the canvas is the HTML that ships to your application.

## How the canvas renders

The canvas uses [GrapesJS](https://grapesjs.com), an open-source web builder framework, to manage a visual editing layer over a live iframe. Inside that iframe, Tailwind CSS v4 is loaded from CDN. This means:

* Any Tailwind utility class you or your agent writes resolves correctly in the canvas.
* The iframe is a fully functional HTML document — you can inspect its elements in your browser's DevTools.
* CSS you write is actual CSS, not a style representation that gets converted later.

The editor shell (the panels, toolbars, and layer tree surrounding the canvas) is separate from the iframe. It runs as a React application and communicates with the GrapesJS instance through its API.

## What a component is

In GrapesJS terminology, every element on the canvas is a **component** — a node in the document tree. Each component has:

* A unique **ID** used by MCP tools to target specific elements.
* A **tag name** (e.g., `div`, `button`, `img`).
* A list of **CSS classes** (Tailwind utilities and custom classes).
* **Attributes** (e.g., `src`, `href`, `data-*`).
* Optional **text content** for leaf nodes.
* A list of **children**, which are themselves components.

This recursive tree structure is what the `get_tree` MCP tool returns. You can inspect it yourself by calling `get_tree` from your agent, or by opening the Layers panel on the right side of the editor.

## Selecting components

You select a component by clicking it in the canvas or clicking its entry in the Layers panel. The editor highlights the selection with a bounding box and populates the Style panel with that component's current CSS properties.

The `get_selection` MCP tool returns the component IDs of whatever is currently selected. This lets an agent check what you have selected before operating on it — useful for workflows where you select a component visually and then ask the agent to modify it.

## How human edits and agent edits converge

Both your edits and the agent's edits go through the same GrapesJS component model. There is one source of truth: the in-memory component tree managed by GrapesJS.

* When you drag a block or change a style in the Style panel, GrapesJS updates its internal model immediately.
* When the agent calls `add_components`, `update_styles`, or `delete_nodes`, the MCP server relays those calls over a WebSocket to the browser, where they execute as GrapesJS API calls — the same API that the editor UI uses.

This means there is no merge conflict model, no "agent layer" vs "human layer." Both parties operate on the same model, and changes are reflected in real time for both.

<Note>
  If the agent and you edit the same component at the same time, last write wins — GrapesJS does not implement operational transforms. In practice, this is rarely an issue because agent calls are explicit tool invocations that take milliseconds to complete.
</Note>

## The block palette

The left panel contains a block palette with 25 pre-built blocks organized into categories: Layout, Typography, Form, and Media. Clicking a block inserts it into the canvas at the root level. These blocks are plain HTML with Tailwind classes — the same kind of HTML the `add_components` tool accepts.

## CSS variables

Beyond per-component styles, the canvas supports **CSS custom properties** (variables) applied to the iframe's `:root`. These act as design tokens: define `--brand-primary` once and reference it across all your components. The `get_variables` and `set_variables` MCP tools let an agent read and write these tokens programmatically. Variables are saved to `.designjs.json` and reapplied when you reload the canvas.

## Saving and restoring state

The canvas saves its full state — the component tree, per-component styles, and CSS variables — to `.designjs.json` in your project directory. Saves happen automatically every 30 seconds and whenever you press `Cmd+S` (Mac) or `Ctrl+S` (Windows/Linux). When you reload the page, the canvas reads that file and restores exactly what you had.

<Tip>
  Because `.designjs.json` is plain JSON, you can commit it to your git repository and restore any saved canvas state by checking out the file.
</Tip>