Skip to main content

Documentation Index

Fetch the complete documentation index at: https://avocadostudioai.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
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.

​
Zero extra integration

Puck mode requires no additional integration work from the site developer. If your site is already integrated with Avocado Studio, Puck mode works automatically.
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: 
Chat Editor ──────────────→ ops ──→ Orchestrator ──→ Site
Puck Editor ──→ adapter ──→ ops ──→ Orchestrator ──→ Site
Adapter functionWhat 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
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

Click the gear icon on the site tile you want to configure.
3

Enable Puck

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

Open the editor

Click “Open Editor” — 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:
Block field typePuck field control
numberNumber input
enumSelect dropdown
headingLevelSelect (h1–h6)
richtextTextarea
imageCustom image picker
defaultText input
Blocks render using the same SharedBlockRenderer from @ai-site-editor/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 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

AspectChat EditorPuck Mode
Primary interactionNatural languageDrag-and-drop
PreviewIframe + postMessage bridgeIn-canvas rendering
Chat locationLeft sidebarRight sidebar (plugin)
Block editingCustom property panelPuck’s native field sidebar
Drag-and-dropCustom handlerPuck’s native DnD
PublishingFull publish flowFull publish flow

​
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, 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