Skip to main content

​
Overview

Puck mode is an alternative editing experience that replaces the default chat-driven editor with a visual drag-and-drop canvas powered by Puck. AI chat remains available as a sidebar plugin, so users get both: direct manipulation and natural-language editing. It is experimental. Turning it on is a per-site setting anyone with access to Site settings can flip; the sections after Enabling per site are for developers.

​
No extra integration, with one catch

Puck mode requires no additional integration work from the site developer. If your site is already integrated with Avocado Studio, Puck mode opens on it.
The catch is what the canvas can draw. It renders blocks with Avocado’s built-in block components, not with your site’s own components or its theme. A block type your site defines itself, with no built-in renderer, appears on the canvas as a dashed placeholder — No renderer is registered for this block in the editor runtime — though its fields still edit in the sidebar. On a site built mostly from its own blocks, the default chat editor, which previews the real site, is the better tool. Your site talks to the orchestrator — not to the editor UI. Whether the user edits via chat or via the Puck canvas, the orchestrator receives the same operations through the same endpoints (/ops, /draft/pages, /chat). The site never knows which editor produced the changes. This is possible because Puck mode runs entirely inside the editor app, with an adapter layer that translates between Puck’s data model and ours: This means you integrate once with Avocado Studio and get both editing experiences — chat-driven AI editing and visual drag-and-drop — without any extra work on your site.

​
Enabling per site

Puck mode is controlled per-site via the site settings panel.
1

Open the Sites page

Navigate to /sites in the editor.
2

Open site settings

Press the gear button on the site’s card. (From inside the editor, the site menu in the top bar has Site settings too.)
3

Enable Puck

In the General tab, check Use visual editor (Puck).
4

Open the editor

Click Open editor on the card — the site opens at /editor/puck?siteId=<id> instead of the chat editor.
Sites without the flag continue to open the default chat editor at /editor.

​
How it works

​
Block registration

When Puck mode loads, it fetches the block manifest from your site’s /api/editor/blocks endpoint — the same manifest the chat editor uses. createPuckConfig() converts each block definition into a Puck-compatible component with appropriate field controls: Blocks render using the same SharedBlockRenderer from @avocadostudio-ai/blocks, so what you see in Puck matches what renders on the live site.

​
AI chat integration

Chat is registered as a Puck plugin panel in the right sidebar. It uses the same chat engine, endpoints, and AI planning as the main editor:
  • /chat for standard planning and ops
  • /agent/start + /agent/stream for agent mode (when enabled)
  • Selection context is passed automatically — the AI knows which block is selected

​
Auto-save

Edits are persisted automatically with a 600ms debounce:
  1. User drags, reorders, or edits a field in the Puck canvas
  2. The system diffs the previous and current state
  3. Operations (add_block, remove_block, update_props, move_block) are generated
  4. Ops are sent to POST /ops on the orchestrator

​
Agent mode

If AGENT_API_KEY is set in the standalone orchestrator’s .env, the editor detects agent mode availability from GET /status/planner. When enabled, the chat sidebar can run multi-step autonomous editing via the agent loop. Library mode (createOrchestrator()) always reports agent mode off, and in production the standalone server mounts the agent routes only with AGENT_SURFACE=on — see environment variables.

​
Comparison with the AI chat editor

​
Publishing

Puck’s built-in “Publish” button triggers the full publish workflow:
  1. Pending draft edits are flushed immediately
  2. POST /publish is called on the orchestrator (same endpoint as the chat editor)
  3. The Puck button shows a loading state while the publish is in progress
  4. A “View deploy” link appears in the header after a successful deployment
Publishing uses the same usePublish hook as the main editor — it supports Git-based deploy, Vercel deploy hooks, and site contract publishing.

​
Architecture

​
Current limitations

Puck mode is experimental. The following features are not yet available:
  • No live site preview — blocks render in the Puck canvas with the built-in renderers, not inside your site’s preview, so your theme and your own block components do not show
  • Custom blocks render as placeholders — see the catch above
  • Chat attachments are not sent — the attach button works, but files are not yet passed to the planner from Puck’s chat panel
  • No nested zones — only flat content arrays; nested layout zones are not yet supported
  • Image upload — basic URL picker only, no upload progress or validation

A tour of the editor

The chat editor Puck mode sits alongside, on the same blocks and the same publishing pipeline.

Block system

What Puck is dragging: manifests, field metadata and validation.