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 the best of both worlds: direct manipulation and natural-language editing.
Puck mode requires no additional integration work from the site developer. If your site is already integrated with Avocado Studio, Puck mode works automatically.
/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:
Chat Editor ──────────────→ ops ──→ Orchestrator ──→ Site
Puck Editor ──→ adapter ──→ ops ──→ Orchestrator ──→ Site
| Adapter function | What it does |
|---|
pageToPuckData() | Converts PageDoc → PuckData so the Puck canvas can render it |
buildOpsFromPuckDiff() | Converts Puck state changes back into standard operations |
createPuckConfig() | Converts the block manifest into Puck field definitions |
Enabling per site
Puck mode is controlled per-site via the site settings panel.
Open the Sites page
Navigate to /sites in the editor.
Open site settings
Click the gear icon on the site tile you want to configure.
Enable Puck
In the General tab, check “Use visual editor (Puck)”.
Open the editor
Click “Open Editor” — the site opens at /editor/puck?siteId=<id> instead of the chat editor.
/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:
| Block field type | Puck field control |
|---|
number | Number input |
enum | Select dropdown |
headingLevel | Select (h1–h6) |
richtext | Textarea |
image | Custom image picker |
| default | Text input |
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:
- User drags, reorders, or edits a field in the Puck canvas
- The system diffs the previous and current state
- Operations (
add_block, remove_block, update_props, move_block) are generated
- Ops are sent to
POST /ops on the orchestrator
Agent mode
If AGENT_API_KEY is set in the orchestrator .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.
Comparison with chat editor
| Aspect | Chat Editor | Puck Mode |
|---|
| Primary interaction | Natural language | Drag-and-drop |
| Preview | Iframe + postMessage bridge | In-canvas rendering |
| Chat location | Left sidebar | Right sidebar (plugin) |
| Block editing | Custom property panel | Puck’s native field sidebar |
| Drag-and-drop | Custom handler | Puck’s native DnD |
| Publishing | Full publish flow | Full publish flow |
Publishing
Puck’s built-in “Publish” button triggers the full publish workflow:
- Pending draft edits are flushed immediately
POST /publish is called on the orchestrator (same endpoint as the chat editor)- The Puck button shows a loading state while the publish is in progress
- 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, not inside the Next.js site iframe
- 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
