Truecanvas

A Figma-like canvas for your real React components. The code is the document.

truecanvas.dev

Truecanvas renders your actual .tsx components on an infinite canvas, lets you compose them visually, and writes every change back to plain TSX in your repo. There is no built-in AI: it is agent-first through MCP, so Claude Code, Cursor, Codex or any MCP client can read your design system, edit frames and take screenshots, while you watch and steer in the editor.

• Real components, not drawings. Layers are instances of your components. The props panel is generated from their TypeScript types (status: "working" | "idle" becomes a dropdown).

• Code is the document. A canvas is canvas/<name>.canvas.tsx. Edits are minimal text patches that keep your formatting, so diffs are reviewable and your editor and the canvas stay in sync both ways.

• Agent-first. 39 MCP tools: read the tree, list components and design tokens, insert JSX, set props, wrap in auto layout, create variant grids, add shader backgrounds, screenshot frames, and see what the user has selected.

• Shaders. Install @paper-design/shaders-react and its ~30 animated shaders show up in the Components panel, with color pickers, sliders from their documented ranges and one-click presets. Add one behind any frame with "Shader background". Pause all motion with ⇧P to save battery.

• Design on your real pages. "Add a page from your app" (Pages +) adds any App Router page as a linked frame: its layers are the page's own JSX, and editing them edits page.tsx (and the layout, for things like the navbar) directly. Right-click → Explore a copy to try ideas without touching the page, then Apply to page to write the result back as a minimal diff.

• Build with plain elements and components. The Insert menu (＋ in the toolbar, T for text) and the Basics in Assets add text, headings, links, buttons, lists, stacks, rows, grids, sections, images and inputs as Tailwind-styled JSX. New component creates a component file; select layers and press Ctrl/⌘+Alt+K to turn them into a component (imports come along). Right-click any component → Edit main component opens it on the components page: its layers are the component's own JSX, edits go to its file, and every instance follows. className={cn("…", className)} stays merged: only the static classes change.

• Pages, layers, assets. Pages are canvas files you can add, rename, duplicate and delete (with undo). Layers have search, editor-only hide and lock, and custom names stored as data-name so your agent sees them too. Assets shows live thumbnails of your components, rendered by your app, plus every shader preset.

• Motion. Play a frame (▶ on its label) to scroll inside it at screen height, so scroll reveals run like on the site, and replay entrance animations anytime. Paused frames and agent screenshots show every animation finished, never half faded. The Motion section adds a scroll reveal (fade up, blur in, scale in…) or a text animation (word by word, letter by letter, typewriter…) to any layer: Truecanvas adds Reveal and TextAnimate to your components once (plain React, no dependencies) and wraps the layer in them.

• Mobile presets. iPhone, Pixel, Galaxy, iPad and desktop frame sizes, with device chrome (status bar, Dynamic Island, home indicator) and touch emulation in agent screenshots.

• Everything is undoable. Edits from you, your agent and your code editor land in one activity feed with undo/redo.

• Light, dark, system. Per-frame theme (Inherit / Light / Dark) and a canvas-wide theme, applied live without reloading frames.

• Lightweight. No second dev server. Frames render through your existing next dev, the editor is a static bundle, and headless Chromium only starts when an agent asks for a screenshot.

Status: early (v0.1). Next.js App Router + Tailwind first. Linux-first, tested on Fedora 43.

Quick start

In a Next.js app (App Router, Next 15.3+):

npx truecanvas

That's it. The first time, it asks once, then adds the dev dependency, wraps next.config, adds a canvas script, links your homepage as the first canvas and offers to connect your agents. Then it starts your app (if it isn't running) and opens the editor. After that, anyone on the project starts it with npm run canvas.

A new app:

npm create truecanvas@latest my-app
cd my-app && npm run canvas

A Next.js app (TypeScript, Tailwind, App Router) with Truecanvas set up and committed. pnpm create truecanvas, yarn create truecanvas and bun create truecanvas work too.

Something off? npx truecanvas doctor checks Node, Next, React, Tailwind, the config, agents, screenshots and git, with a one-line fix for each problem.

Prefer an app to a terminal? npx truecanvas open opens the Truecanvas window: your projects, one tab each, "Clone from GitHub" and "New project". npx truecanvas desktop adds it to your app launcher (Linux).

Connect your agent

npx truecanvas connect

This writes the Truecanvas MCP server into the project's .mcp.json (and .cursor/mcp.json / .vscode/mcp.json when the project uses those editors). Commit it: everyone who clones the repo gets Truecanvas in Claude Code, Cursor or VS Code with no setup.

Then select something on the canvas and ask: "Make my selection denser", "Create a dark copy of the Chat frame and check it with a screenshot", "Show every status of SessionRow".

Related MCP server: figma-ui-mcp

The Truecanvas window

npx truecanvas desktop   # adds Truecanvas to your app launcher (GNOME, KDE…)
npx truecanvas hub       # or start it from a terminal

One window for all your projects, with tabs like a browser. The Dashboard lists your recent projects (with their favicons) and the Next.js apps it finds on your computer. You can open a folder, set up Truecanvas in an existing app, or create a new project. Each tab is a project's editor. Opening a tab starts that project's app on free ports, and closing it stops the app and frees the memory (the tab bar shows how much is in use).

The hub serves MCP at the same http://localhost:4800/mcp, and your agent works on the project in the active tab. It can also call list_projects and open_project to switch itself.

Collaborate

Everything Truecanvas makes is a file in your repo: canvases, comments, linked pages, the motion components they use, and .mcp.json. So git is the collaboration layer, and a team works on design the way it works on code.

The workflow

1. Set up once, commit it. npx truecanvas in the repo, then commit package.json, canvas/, next.config and .mcp.json. Teammates run their usual install and npm run canvas; their agents are already connected.

2. Design on real pages. Linked frames are your production pages: editing them edits page.tsx. For bigger ideas, right-click → Explore a copy, iterate freely (you or your agent), then Apply to page. Delete explorations once applied.

3. One branch per change. On main, Truecanvas offers to start a branch and brings your edits along.

4. Commit from the Git panel. It lists what changed per frame in plain words and drafts the message.

5. Open a pull request from the panel: the description shows each changed frame, before and after.

6. Review in Truecanvas too. In the Truecanvas window, a project's menu → Pull requests… checks out any PR and shows it on the canvas, live, not just as pictures. Leave comments on frames; they're saved in the branch, and agents can read and resolve them.

7. Merge. There's no handoff: the design is already the code.

Designers who don't use a terminal can do all of it from the Truecanvas window: Clone from GitHub (clones, installs, sets up), open the project, branch, commit, open and review PRs.

What's in the Git panel

• Git panel (the branch pill at the top left): what changed, frame by frame, in plain words ("Restyled h1 (+text-orange-600)", "Added a fade-up reveal to p"), with a commit message drafted from it. Changed frames get a dot on the canvas. Design commits include canvases, comments, linked pages and the motion components they use.

• Review changes: a full-screen before/after of each changed frame against the last commit (rendered by your app), plus the code diff.

• Branch first: on main with changes, Truecanvas offers to start a branch (named from the page and frames) and carries your edits over.

• Pull requests (GitHub, through the gh CLI): push and open a PR in one step. Its description lists the changes per frame, optionally with before/after images stored on a truecanvas-previews branch of the same repo. The branch pill then shows the PR's state: open, checks running or failing, approved, merged. No GitHub remote yet? "Publish" creates the repo (private by default).

• Compare: render this page as it was on another branch or commit, side by side or as an overlay with an opacity slider. Changed and new frames are flagged. This works because Truecanvas renders any version of the code.

• Comments (C): pin a comment on a frame or layer. Threads are saved in canvas/<page>.comments.json, so they travel with branches and show up in pull requests. Agents read them with list_comments (including the current source of the commented layer), fix things, and resolve_comment with a note.

Good to know

• Async, like code. Collaboration happens through branches and pull requests. Live multiplayer on one canvas isn't supported; the live cursors you see are agents working on your machine.

• Merges. Canvas files are TSX with one block per frame and minimal edits, so two people changing different frames merge cleanly. When both change the same frame, resolve it like any code conflict and Truecanvas re-renders the result.

• One agent config for everyone. .mcp.json points at http://localhost:4800/mcp, which works whether each person runs npm run canvas or the Truecanvas window.

Linked frames

A new project's first canvas links your homepage. Any page can be linked from Pages + or with the import_page tool:

<Frame name="Home" x={0} y={0} width={1440} page="src/app/(marketing)/page.tsx">
  <MarketingLayout>
    <HomePage />
  </MarketingLayout>
</Frame>

• The frame renders the real page through its layouts. Its layers are the JSX of page.tsx and of the layouts around it, and every edit goes to the file that layer lives in, keeping that file's formatting. The frame label shows Live · page.tsx.

• Undo, the Git panel (linked pages count as design files) and Compare (the page is rendered as it was at that commit) all work on the page files.

• Only plain composition is editable: a page whose component fetches data or has logic before its return is shown as one layer, View only. Explore a copy to design on it.

• Explore a copy creates <Frame from="src/app/…/page.tsx"> with the page's JSX inline, in the canvas file. Apply to page replaces the page's returned JSX with the exploration's, adds the imports it needs and removes the ones it no longer uses.

• Page and layout layers get ids like src/app/page.tsx#12:8, stamped only in next dev. Production builds are untouched.

A canvas file

"use client";
import { Canvas, Frame } from "truecanvas";
import { SessionRow } from "@/components/app/session-row";

export default function ChatCanvas() {
  return (
    <Canvas>
      <Frame name="Sessions" x={0} y={0} width={320}>
        <div className="flex flex-col gap-1 p-3">
          <SessionRow title="Review release readiness" status="working" elapsed="2m" active />
          <SessionRow title="Draft the Q4 changelog" status="review" source="slack" elapsed="3h" />
        </div>
      </Frame>
      <Frame name="Sessions dark" x={360} y={0} width={320} theme="dark">
        {/* … */}
      </Frame>
    </Canvas>
  );
}

• <Frame>: name, x, y, width, optional height (omit to hug content), optional theme ("light" | "dark", omit to inherit), optional device ("iphone-16", "pixel-9", "ipad-mini"…), optional page (linked frame) or from (exploration of a page).

• Each frame renders in its own iframe at its own width, so media queries, portals and position: fixed behave like the real app.

• Keep props literal (status="working") to make them editable. Expressions such as {items.map(…)} still render, but they are read-only in the inspector.

MCP tools

Node ids are line:col of the JSX tag (file#line:col for layers of a linked page) and change after edits. Every write returns the fresh ids of the affected frame. Catalog components are imported automatically.

How it works

  your browser                          truecanvas dev (Node, 127.0.0.1:4800)
 ┌───────────────────────────┐  REST/SSE ┌──────────────────────────────────┐
 │ editor UI (static bundle) │◀─────────▶│ Workspace: parse → patch → write │◀── MCP ── your agent
 │  ┌──────┐ ┌──────┐        │           │ (Babel + magic-string, undo log) │
 │  │iframe│ │iframe│ frames │           │ Catalog: TS checker → prop types │
 │  └──┬───┘ └──┬───┘        │           └───────────────┬──────────────────┘
 └─────┼────────┼────────────┘                           │ writes canvas/*.canvas.tsx
       │        └── postMessage: hit-test, rects, theme  ▼
       └──────────── /truecanvas/[canvas]?frame=… ── your `next dev` (HMR)

1. A Turbopack/webpack loader stamps each JSX element in *.canvas.tsx with data-tc="line:col" (dev only, same line, no layout impact).

2. In the iframe, a tiny runtime answers "what's under this point?" by walking React's fiber tree to the nearest stamped element. No wrapper elements, and it works with portals and components that don't forward props.

3. The editor turns your gestures into commands. The server patches the source text and writes it, and Next's HMR re-renders the frame.

4. Agents use the same commands over MCP, so whatever you can do, they can do.

Configuration

Optional truecanvas.config.json at the project root:

{
  "appUrl": "http://localhost:3000",
  "port": 4800,
  "canvasDir": "canvas",
  "components": ["components/**/*.tsx"],
  "darkMode": { "strategy": "class", "value": "dark" },
  "libraries": ["@paper-design/shaders-react"],
  "editor": "code"
}

libraries adds npm packages to the Components panel (Paper shaders are detected automatically when installed). darkMode tells frames how your app switches themes: a class on <html> (strategy: "class"), or an attribute ({ "strategy": "attribute", "attribute": "data-theme", "value": "dark", "lightValue": "light" }).

Shortcuts

On Linux, ⌘ is Ctrl. Pan with space-drag, middle mouse or two-finger scroll. Zoom with Ctrl+scroll or pinch.

Requirements

• Node 20+, Next.js 15.3+ (App Router), React 19. Tailwind is optional but the style controls write Tailwind classes.

• Linux and macOS. Windows is untested.

• For screenshots and PR images: Chrome/Chromium, or a Playwright browser in ~/.cache/ms-playwright. Set TRUECANVAS_CHROME to point at one.

• For pull requests: the GitHub CLI (gh auth login).

npx truecanvas doctor checks all of this.

Develop

pnpm install
pnpm build                      # library + editor bundle
pnpm --filter truecanvas test   # engine tests
pnpm dev                        # builds, then starts the playground app + editor
pnpm --filter truecanvas dev:editor   # editor with Vite HMR on :4801 (proxies the API)
pnpm pack:local                 # an installable build, plus the command to add it to a project

Running the CLI from this checkout (node packages/truecanvas/dist/cli.js) installs a tarball of your local build into projects instead of the npm release.

Releasing: pnpm release 0.2.0 bumps truecanvas and create-truecanvas, commits and tags; git push --follow-tags runs the release workflow, which tests and publishes both to npm with provenance (needs an NPM_TOKEN secret in the GitHub repo).

Roadmap

• Multi-frame drag and reparenting by dragging on the canvas

• Vite + React Router support, then CSS Modules

• Inline prop editing for ReactNode slots

• Desktop shell (AppImage / Flatpak) once the web version settles

License

MIT