@avocadostudio-ai/site-sdk 0.3.3 → 0.5.0

package/README.md

@@ -10,6 +10,25 @@ SDK for integrating any Next.js site with the Avocado Studio. Provides the contr
 npm install @avocadostudio-ai/site-sdk
 ```
 
+That is enough to render a site and serve the editor API. **Library mode — the
+orchestrator running inside your Next app — needs two more:**
+
+```bash
+npm install @avocadostudio-ai/orchestrator-core better-sqlite3
+```
+
+`orchestrator-core` is an *optional* peer dependency, which means no package
+manager installs it for you, and `@avocadostudio-ai/site-sdk/server` — where
+`createOrchestrator` lives — is a hard import of it.
+
+Nothing else. In particular you do **not** add `@avocadostudio-ai/shared` to
+describe your own blocks: `registerBlock`, `z` and the block-meta types are
+re-exported from [`@avocadostudio-ai/site-sdk/blocks`](#registering-your-own-block-schemas).
+The SDK does depend on `shared`, `blocks`, `preview-adapter` and `zod`, but a
+dependency of a dependency is not a specifier your own source may import —
+under pnpm those live in `.pnpm/`, where the SDK can reach them and your site
+cannot.
+
 ### 2. Wrap your Next config
 
 ```ts
@@ -132,7 +151,33 @@ DRAFT_MODE_SECRET=<random-secret>
 PUBLISH_TOKEN=<publish-auth-token>
 ```
 
-That's it. Your site now works with the AI editor.
+### That is not it — six more steps, and each one fails silently
+
+Steps 1–6 give you a site that renders `PageDoc` content and an editor API the
+editor can read. They do not give you an editable site, and every gap below
+presents as something *other* than a missing step:
+
+| Still missing | What it looks like when you skip it |
+|---|---|
+| the proxy (Next 16) or middleware (Next 15) | `?__editor=1` never reaches the preview route, so the editor frames your **published** page and edits appear to do nothing |
+| a `/preview-draft` route | nothing renders drafts; the iframe shows published content |
+| `EditorOverlay` on that route | the page frames and renders, and does not respond to a click |
+| `createOrchestrator` (library mode) | there is no orchestrator; the chat has nothing to talk to |
+| `registerBlocks`, if you have your own blocks | everything looks wired up until the first AI edit returns `Unknown block type` |
+| `editableProps` in your components | block selection works; not one *field* is editable |
+
+In order:
+
+- **[Library mode mounts two handlers, not one](#library-mode-mounts-two-handlers-not-one)** — `createOrchestrator` alongside the route in step 4, and both need the same `registerBlocks` and `blockTypes`.
+- **[The editor frames your page, not the preview route](#the-editor-frames-your-page-not-the-preview-route)** — the proxy, and the CSP that lets the editor frame you at all.
+- **[Registering your own block schemas](#registering-your-own-block-schemas)** — if your blocks are not Avocado's.
+- **[Mounting the overlay](#mounting-the-overlay)** — and turning selection *on* in the editor, which defaults to off and makes a correct integration look inert.
+- **[Marking up your components](#marking-up-your-components)** — the block wrapper first, then the fields. Budget for this one; it is the largest single cost.
+
+The first editor API request also prints a warning block for the configuration
+it can check from the inside (draft secret, editor origin, orchestrator URL).
+It cannot see the last three rows of that table — those live in your components,
+and the [coverage gate](#budget-for-this-part) is what keeps them honest.
 
 ## What You Implement
 
@@ -145,7 +190,7 @@ That's it. Your site now works with the AI editor.
 
 ## Exports
 
-All seventeen, because the six this table used to list were not the six an
+All twenty, because the six this table used to list were not the six an
 integration needs — `createOrchestrator` is the whole of library mode and was in
 none of them.
 
@@ -163,15 +208,20 @@ none of them.
 | `.../draft` | `resolveEditorContext`, `fetchEditorPage`, `fetchEditorSlugs`, `fetchEditorSiteConfig` |
 | `.../draft/core` | The draft context without Next's cookie APIs |
 | `.../editor` | `EditorOverlay`, `LivePreviewProvider`, `buildEditorQuerySuffix` |
+| `.../markers` | `editableProps`, `getPreviewWrapperProps` — the preview attributes, with no React behind them. **Import them from here**, not from `.../editor`, in any component a public page renders |
+| `.../blocks` | `registerBlock`, `z`, and the block-meta types (`FieldKind`, `FieldMeta`, `ListFieldMeta`, `BlockMeta`), so describing your own blocks needs no second package |
+| `.../coverage` | `editableCoverage` (the preview markers) and `panelCoverage` (the property panel) — gate both in CI |
 | `.../editor-manifest` | `buildBlockManifest` — the built-in blocks as a manifest |
 | `.../publish` | `diffPage`, `groupPatches`, `describeUnsupported` — the field-level publish walk |
 | `.../publish-handlers/json-file` | A ready-made `onPublish` that writes a JSON file |
 | `.../navigation` | `buildNavItems`, `buildSiteHeaderBlock` |
 | `.../seo` | `buildPageMetadata` and the title/description derivation |
 
-`useLivePreviewBlocks` is not here. It lives in
-`@avocadostudio-ai/preview-adapter`, which you must depend on directly to import
-from it (`LivePreviewProvider` itself is re-exported above, the hook is not).
+`useLivePreviewBlocks` is in `.../editor` too, beside `LivePreviewProvider`. It
+used to be the one import in our own walkthrough that a site following our own
+install line could not resolve: the provider was re-exported and the hook was
+not, so the example said to import it from `@avocadostudio-ai/preview-adapter`,
+which is a dependency of *this* package and not of yours.
 
 It is worth being precise about what it is for, because an earlier version of
 this paragraph was not. Rendering a live draft through **your own** components
@@ -452,6 +502,36 @@ A workspace link to `@avocadostudio-ai/orchestrator-core` is **not** enough. A
 linked package's own dependencies are never materialised in the host's tree, and
 a native module has to be resolvable from there.
 
+
+### `withAvocado` writes the framing headers for you
+
+As of this version you do not hand-write the CSP pair. `withAvocado` appends
+both rules, derived from the same `EDITOR_CORS_ORIGINS` /
+`NEXT_PUBLIC_EDITOR_ORIGIN` allowlist the editor API uses — so the two halves of
+the contract cannot disagree:
+
+```
+frame-ancestors 'self' http://localhost:4100 http://127.0.0.1:4100;
+```
+
+Two things it gets right that hand-written versions did not. It names **both
+loopback spellings**, because the CLI binds `127.0.0.1` and prints that while
+every doc says `localhost`, and `frame-ancestors` compares origins as strings.
+And it puts `missing: [{ type: "query", key: "__editor" }]` on the public rule —
+without that, both rules match an editor request, the browser receives two CSP
+headers and enforces their *intersection*, putting `frame-ancestors 'self'` back
+and blocking the frame it just allowed.
+
+Your own `headers()` entries come first and win, since Next uses the first match
+per header. Opt out entirely with `withAvocado(config, { framing: false })`.
+
+Serving the editor anywhere but `:4100` — which anyone already running the
+standalone stack has to — means setting `EDITOR_CORS_ORIGINS`, and that one
+variable now covers both halves. Left unset, the API answers **200 with no
+`access-control-allow-origin`** (the Sites page reports your site as *offline*)
+and the browser refuses the frame (**a blank rectangle**). Neither failure names
+a port, and neither says CORS or CSP.
+
 ## The editor frames your page, not the preview route
 
 The iframe's `src` is your site's own URL with a query parameter added:
@@ -626,7 +706,7 @@ until the first AI edit:
 
 ```ts
 // lib/register-blocks.ts
-import { registerBlock, z } from "@avocadostudio-ai/shared"
+import { registerBlock, z } from "@avocadostudio-ai/site-sdk/blocks"
 
 export function registerMyBlocks() {
   registerBlock("PricingTable", {
@@ -663,7 +743,7 @@ last in the file. Next's bundler does not reliably preserve module order across
 the RSC, SSR and route-handler layers, so the built-in schemas sometimes
 re-register on top of yours. The hook exists to replace that trick.
 
-### Import `z` from `@avocadostudio-ai/shared`, not from `zod`
+### Import `z` from `site-sdk/blocks`, not from `zod`
 
 `registerBlock` takes a `ZodObject`, and a Zod object is assignable only to one
 built by the *same copy* of the library. Your own `import { z } from "zod"`
@@ -671,7 +751,60 @@ resolves to whatever your tree hoisted — on any site that also uses Sanity tha
 is zod 3 — and the mismatch reports as a structural type error listing methods
 you have never called (`loose`, `safeExtend`, `exactPartial`, `def`, "and 21
 more"), with nothing anywhere saying there are two copies of zod. Importing `z`
-from `shared` gives you ours, and you need no direct `zod` dependency at all.
+from `site-sdk/blocks` gives you ours, and you need no direct `zod` dependency
+at all.
+
+`site-sdk/blocks` re-exports these from `@avocadostudio-ai/shared`, which the
+SDK already depends on. Import them from there and the rule above stops being
+something you have to remember: there is only one copy to reach.
+
+### What `kind` may be
+
+`meta.fields[…].kind` is a closed list, and it is not the list of HTML element
+names — `"select"` and `"textarea"` are both wrong:
+
+| What you want | What you write |
+|---|---|
+| a single-line string | `{ kind: "text" }` |
+| a multi-line box | `{ kind: "text", multiline: true }` — `multiline` is a flag, not a kind |
+| markdown / rich text | `{ kind: "richtext" }` |
+| a closed list of values | `{ kind: "enum", options: ["a", "b"] }` — a `string[]`, not `{ value, label }[]` |
+| an image | `{ kind: "image" }`, with its alt text as `{ kind: "imageAlt" }` |
+| a link | `{ kind: "url" }` for a bare href, `{ kind: "link" }` for `{ href, label }` |
+| an uploaded file | `{ kind: "file" }` |
+| the rest | `{ kind: "number" }`, `{ kind: "boolean" }`, `{ kind: "color" }`, `{ kind: "headingLevel" }` |
+
+In TypeScript a wrong `kind` is a compile error naming the whole union, which is
+how you would find this out anyway. In JavaScript it is silent: the panel falls
+back to a plain text input and the preview loses whatever affordance the right
+kind would have given the field.
+
+### Lists whose rows are not all the same shape
+
+`listFields` has a second form for that, and it is easy to miss because the
+common case does not use it. Give the list a `discriminator` naming the row
+property that says what the row is, and `itemFieldsByType` mapping each value of
+it to that variant's fields; `itemFields` stays as the fallback for a row whose
+type is not listed:
+
+```ts
+listFields: {
+  content: {
+    label: "Content",
+    discriminator: "type",
+    itemFields: { type: { kind: "text" }, text: { kind: "text", multiline: true } },
+    itemFieldsByType: {
+      heading:   { text: { kind: "text", label: "Heading" } },
+      paragraph: { text: { kind: "text", multiline: true } },
+      image:     { src: { kind: "image" }, alt: { kind: "imageAlt" } },
+    },
+  },
+}
+```
+
+Without it, a mixed list is described by whichever single shape you picked, and
+every row of every other shape renders that shape's fields against props it does
+not have.
 
 ### `schema` and `meta` are two halves that must agree
 
@@ -801,38 +934,159 @@ second false is the default.
 Once the picker is on, blocks are selectable. Individual *fields* are not,
 until:
 
-## Making fields editable
+## Marking up your components
+
+Two attributes carry the whole preview contract, and there is a helper for each.
+Import both from `@avocadostudio-ai/site-sdk/markers` — *not* from
+`.../editor`, which also exports `EditorOverlay` and will pull the editor into
+every public page that renders the same component ([see below](#import-the-markers-from-markers-not-from-editor)).
+
+### First, the block wrapper — without it nothing is selectable
+
+Selection is built entirely on `data-block-id`: a click resolves through
+`closest("[data-block-id]")`, and *no match* is read as "clicked outside any
+block", which **clears** the selection. So a preview that marks every field and
+no block frames, renders, scrolls and validates correctly, and deselects on
+every click — which looks exactly like the picker being switched off.
+
+Do it once, wherever you dispatch on block type, rather than in each block:
+
+```tsx
+import { getPreviewWrapperProps } from "@avocadostudio-ai/site-sdk/markers"
+
+export function BlockRenderer({ block, editorMode = false }) {
+  const rendered = renderBlock(block)
+  if (!editorMode || rendered === null) return rendered
+  return <div {...getPreviewWrapperProps(true, block.id, block.type)}>{rendered}</div>
+}
+```
+
+It returns `{}` when `editorMode` is false, so the published page renders
+precisely the markup it rendered before.
+
+### Then the fields
 
 The manifest tells the editor which blocks exist and what props they take. It
 does not tell it **where on the page a prop is rendered**, and nothing can derive
-that — so a site whose components carry no annotation gets block selection, the
-badge, move and delete, and not one editable field.
-
-Put `data-editable-target` on the DOM node that renders each prop:
+that — so a block with no field markers gets selection, the badge, move and
+delete, and not one editable field.
 
 ```tsx
-<h1 data-editable-target="heading">{heading}</h1>
-<p  data-editable-target="subheading">{subheading}</p>
+import { editableProps } from "@avocadostudio-ai/site-sdk/markers"
+
+<h1 {...editableProps("heading")}>{heading}</h1>
+<p  {...editableProps("subheading", { kind: "text" })}>{subheading}</p>
 
 {cards.map((card, i) => (
   <article key={card._key}>
-    <h3 data-editable-target={`cards[${i}].title`}>{card.title}</h3>
-    <img data-editable-target={`cards[${i}].imageUrl`} src={card.imageUrl} />
+    <h3 {...editableProps(`cards[${i}].title`)}>{card.title}</h3>
+    {/* on the wrapper, never on the <img> — see below */}
+    <div {...editableProps(`cards[${i}].imageUrl`, { kind: "image" })}>
+      <img src={card.imageUrl} alt={card.alt} />
+    </div>
   </article>
 ))}
 ```
 
 The path grammar is the same one operations use: `heading` for a scalar,
 `cards[0].title` for a list item's field, `cards[0].imageUrl` for its image.
+What the overlay reads here is what it sends back as the field to patch.
+
+There is no `editorMode` argument on `editableProps`, on purpose: these are
+inert data attributes that do nothing unless the overlay is mounted, and
+threading a flag down to every field is the step that does not get done.
+
+### An image field goes on the wrapper, not on the `<img>`
+
+The overlay *appends* its Change button into the marked element, and nothing can
+be appended into an `<img>` — it is a void element. Marking the image itself
+gives you a field that is listed in the property panel, highlights on hover, and
+has no button, with no error on either side.
+
+### `kind` is how your site says what a field is, in its own words
+
+Without it the overlay guesses an image from the prop name, against Avocado's
+own naming (`imageUrl`, `*.src`). A site whose field is `photoUrl` or `heroSrc`
+gets a picker in the property panel and no button in the preview. Pass the same
+word the block manifest uses — the [`kind` table](#what-kind-may-be) — and the
+guess never runs.
+
+### Import the markers from `/markers`, not from `/editor`
+
+`@avocadostudio-ai/site-sdk/editor` re-exports both helpers, so older code keeps
+working. But that entry also exports `EditorOverlay` and the live-preview
+provider, and most sites mark up components that their **public** pages render
+too. A `'use client'` component importing the two-line attribute helper from
+there drags the whole editor into the public bundle — measured on a real
+integration at **+66 kB First Load JS on every page**, for byte-identical
+markup. `/markers` has no React in it at all.
+
+### Budget for this part
 
 This is the one part of an integration that **cannot** live in an integration
-layer — it has to go inside your own components, one attribute per prop you want
-editable. Budget for it: it is usually the largest single cost of adopting the
-editor, and there is no way to add it from the outside.
+layer: it goes inside your own components, one call per prop you want editable.
+It is usually the largest single cost of adopting the editor, and there is no
+way to add it from the outside. Two real integrations landed at 36 and 51
+emission sites.
+
+Gate it in CI rather than trusting it to stay done. `editableCoverage` from
+`@avocadostudio-ai/site-sdk/coverage` compares the manifest's fields against the
+markers a rendered page actually carries, so a field that loses its marker in a
+refactor fails a build instead of silently losing inline editing:
+
+```js
+import { extractMarkedBlocks, editableCoverage, formatEditableCoverage }
+  from "@avocadostudio-ai/site-sdk/coverage"
+
+const manifest = await (await fetch(`${BASE}/api/editor/blocks`)).json()
+const html = await (await fetch(`${BASE}/?__editor=1`)).text()
+const report = editableCoverage(manifest, extractMarkedBlocks(html), { props })
+console.log(formatEditableCoverage(report))
+```
+
+Pass `props` — the blocks as rendered — or the report cannot tell a field that
+lost its marker from one that was empty on that page. Expect a ceiling below
+100%: a field that draws nothing (`sectionId`, an input's `placeholder`, a
+`<video>` poster) has no element to mark and stays panel-only.
+
+Declare those panel-only fields as `{ kind: "text", panelOnly: true }` and the
+ceiling goes away — the denominator becomes the set of fields that *could* carry
+a marker, so 100% is reachable and anything less is actionable.
 
-Two optional siblings control the labels the overlay draws:
-`data-editable-target-label` (the CSS `::before` tooltip) and
-`data-editable-label` (the floating pill). Both default to the target path.
+### And check the panel, which is the other half
+
+`editableCoverage` asks whether the preview offers each field. It says nothing
+about whether the property panel is *intelligible*, and that fails in ways a
+build, a type check and a manifest validation all pass through:
+
+```js
+import { panelCoverage, formatPanelCoverage } from "@avocadostudio-ai/site-sdk/coverage"
+import { getAllBlockMeta } from "@avocadostudio-ai/site-sdk/blocks"
+
+const report = panelCoverage(manifest, pages, { builtinTypes: getAllBlockMeta() })
+console.log(formatPanelCoverage(report))
+if (report.findings.length > 0) process.exit(1)
+```
+
+It compares what the panel will render against what your content actually holds,
+so it needs no browser and no screenshots:
+
+| finding | what it means |
+|---|---|
+| `colliding_type` | your block type name also exists in the editor's built-ins with a different shape. **Read this one first** — it usually explains several of the others |
+| `unlabelled_row` | the panel titles this list row `Item 4`; nobody can tell it from its neighbour |
+| `unmatched_branch` | a row's discriminant value has no `itemFieldsByType` entry, so it is edited against the union of every branch |
+| `incomplete_polymorphism` | a `discriminator` with no branch map, or the reverse — nothing narrows |
+| `orphan_prop` | your content holds it and nothing describes it, so the panel cannot show or edit it |
+| `filename_row_label` | an image row titled `IMG_20250904.webp` while a populated alt sits beside it |
+| `phantom_field` | declared for rows that never have it |
+
+Pass `builtinTypes` only if you want the collision findings; without it they are
+simply not reported, because an absent input is not evidence.
+
+An agent integrating a site can call the same check as
+`avocado-check-editing-surface` over MCP, and should, before reporting an
+integration as done.
 
 ## Environment Variables
 

package/dist/blocks.d.ts

@@ -0,0 +1,3 @@
+export { z } from "@avocadostudio-ai/shared";
+export { registerBlock, declareBlockCatalogue, getBlockMeta, getAllBlockMeta, getChromeTypes, isChrome, IMAGE_PLACEHOLDER, isImagePlaceholder, blockTypeToCamel, camelToBlockType, blockTypeToLower, lowerToBlockType, } from "@avocadostudio-ai/shared";
+export type { FieldKind, FieldMeta, ListFieldMeta, ImageSpec, BlockMeta, BlockType, BlockInstance, BlockRegistration, } from "@avocadostudio-ai/shared";

package/dist/blocks.js

@@ -0,0 +1,29 @@
+/*
+ * Everything a site needs to describe its own blocks, re-exported from the one
+ * package its install line names.
+ *
+ * `registerBlock` and the block-meta types live in `@avocadostudio-ai/shared`,
+ * which the SDK depends on — and a dependency of a dependency is not a
+ * specifier your own source may import. Under pnpm's isolated `node_modules`
+ * it sits under `.pnpm/` where the SDK can reach it and the site cannot, so
+ * `import { registerBlock } from "@avocadostudio-ai/shared"` fails outright on
+ * a clean `pnpm add @avocadostudio-ai/site-sdk`. Under npm's flat hoisting it
+ * resolves, which is worse: it keeps working until an unrelated dependency
+ * change re-hoists, and then breaks in a build that never mentions us.
+ *
+ * Importing `z` from here rather than from `zod` also makes the "same copy of
+ * zod" rule structural instead of merely documented: `registerBlock` takes a
+ * `z.ZodObject`, and a Zod object is only assignable to one built by the same
+ * copy of the library. A site that also uses a zod-3 SDK (Sanity, for one) and
+ * writes its schemas against its own hoisted `zod` gets a wall of structural
+ * type errors naming methods nobody has heard of, none of which say "you have
+ * two copies of zod".
+ *
+ * This entry is deliberately free of React components — importing it costs a
+ * site nothing in its client bundle.
+ */
+export { z } from "@avocadostudio-ai/shared";
+export { registerBlock, declareBlockCatalogue, getBlockMeta, getAllBlockMeta, getChromeTypes, isChrome, IMAGE_PLACEHOLDER, isImagePlaceholder, 
+// Block-type name conversions, for CMS adapters whose document types are
+// spelled differently from Avocado's (`Hero` vs `hero` vs `featureGrid`).
+blockTypeToCamel, camelToBlockType, blockTypeToLower, lowerToBlockType, } from "@avocadostudio-ai/shared";

package/dist/coverage.d.ts

@@ -0,0 +1,4 @@
+export { extractMarkedBlocks, editableCoverage, formatEditableCoverage } from "@avocadostudio-ai/shared";
+export type { MarkedBlock, BlockCoverageGap, EditableCoverage } from "@avocadostudio-ai/shared";
+export { panelCoverage, formatPanelCoverage } from "@avocadostudio-ai/shared";
+export type { PanelCoverage, PanelFinding, PanelFindingCode } from "@avocadostudio-ai/shared";

package/dist/coverage.js

@@ -0,0 +1,24 @@
+/*
+ * The CI-side half of the marker contract.
+ *
+ * `editableCoverage` compares the fields a block manifest declares against the
+ * `data-editable-target` markers a rendered page actually carries, so a field
+ * that loses its marker in a refactor fails a build instead of silently losing
+ * inline editing, its hover pill and its image Change button.
+ *
+ * Re-exported here because the site cannot import `@avocadostudio-ai/shared`
+ * directly — see `./blocks.ts`. Kept out of `./markers` so that nothing a page
+ * renders pulls an HTML scanner into its bundle.
+ */
+export { extractMarkedBlocks, editableCoverage, formatEditableCoverage } from "@avocadostudio-ai/shared";
+/*
+ * The other half. `editableCoverage` asks whether the *preview* offers each
+ * field; `panelCoverage` asks whether the *property panel* is intelligible —
+ * whether every list row can be told apart, whether polymorphic branches
+ * actually narrow, whether anything in your content is described by nothing.
+ *
+ * Pass the editor's own registry as `builtinTypes` to also learn where your
+ * block type names collide with Avocado's built-ins, which is the one finding
+ * that explains several of the others.
+ */
+export { panelCoverage, formatPanelCoverage } from "@avocadostudio-ai/shared";

package/dist/draft-fetch.js

@@ -1,10 +1,46 @@
 import { pageDocSchemaLenient, siteConfigSchema } from "@avocadostudio-ai/shared";
+/*
+ * The address of the orchestrator this site should read drafts from.
+ *
+ * The `127.0.0.1:4200` fallback is the *standalone* orchestrator, and a
+ * library-mode site by definition does not run one — its orchestrator is a
+ * route inside itself. Falling through to :4200 there is silent when nothing is
+ * listening (the fetch fails, the preview quietly serves published content, and
+ * every edit looks like it did nothing) and worse when something is: the fetch
+ * succeeds against a foreign process and the preview renders another project's
+ * pages, with a 200 on both sides. Anyone integrating is likely to have a :4200
+ * up, because that is exactly what the standalone stack runs on.
+ *
+ * So a mounted `createOrchestrator` now publishes its own address on
+ * `globalThis`, and it is preferred over the fallback. The key is a literal on
+ * both sides because `@avocadostudio-ai/orchestrator-core` is an optional peer
+ * — a site not in library mode does not have it installed, so neither package
+ * may import the other. See `orchestrator-core/src/handler/library-mount.ts`.
+ */
+const LIBRARY_MOUNT_KEY = "__avocado_library_mount__";
+function libraryModeOrchestratorUrl() {
+    const mount = globalThis[LIBRARY_MOUNT_KEY];
+    return mount?.observed ?? mount?.declared ?? null;
+}
+let warnedAboutFallback = false;
 export function getOrchestratorUrl() {
     const value = process.env.ORCHESTRATOR_URL?.trim();
     if (value)
         return value.replace(/\/$/, "");
-    if (process.env.NODE_ENV !== "production")
+    const mounted = libraryModeOrchestratorUrl();
+    if (mounted)
+        return mounted;
+    if (process.env.NODE_ENV !== "production") {
+        if (!warnedAboutFallback) {
+            warnedAboutFallback = true;
+            console.warn("[avocado] ORCHESTRATOR_URL is not set, and no library-mode orchestrator " +
+                "has registered itself — falling back to http://127.0.0.1:4200. If you " +
+                "mounted createOrchestrator inside this app, set ORCHESTRATOR_URL to its " +
+                "own URL (e.g. http://localhost:3000/api/avocado). Whatever is listening " +
+                "on :4200 is a different process, and it will answer.");
+        }
         return "http://127.0.0.1:4200";
+    }
     return null;
 }
 /**

package/dist/draft-fetch.test.js

@@ -1,6 +1,6 @@
 import { test, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { fetchEditorPage, fetchEditorSlugs, resetDraftFetchWarnings } from "./draft-fetch.js";
+import { fetchEditorPage, fetchEditorSlugs, getOrchestratorUrl, resetDraftFetchWarnings } from "./draft-fetch.js";
 let calls = [];
 let warnings = [];
 const realFetch = globalThis.fetch;
@@ -85,3 +85,69 @@ test("fetchEditorSlugs refuses the same way, and returns an empty list", async (
     assert.equal(calls.length, 1);
     assert.match(warnings[0], /fetchEditorSlugs/);
 });
+/*
+ * VI-04. With `ORCHESTRATOR_URL` unset, a library-mode site used to read its
+ * drafts from `127.0.0.1:4200` — the standalone orchestrator it does not run.
+ * When nothing is listening there the preview silently serves published content
+ * and every edit looks inert; when something is, the fetch succeeds and the
+ * preview renders a foreign project's pages. A mounted `createOrchestrator`
+ * now publishes its own address, and it must win.
+ */
+test("a mounted library-mode orchestrator beats the :4200 fallback", () => {
+    const prev = process.env.ORCHESTRATOR_URL;
+    const g = globalThis;
+    const prevMount = g["__avocado_library_mount__"];
+    try {
+        delete process.env.ORCHESTRATOR_URL;
+        g["__avocado_library_mount__"] = { declared: "http://localhost:3001/api/avocado" };
+        assert.equal(getOrchestratorUrl(), "http://localhost:3001/api/avocado");
+        // A real request the handler served outranks what config declared.
+        g["__avocado_library_mount__"] = {
+            declared: "http://localhost:3001/api/avocado",
+            observed: "https://villa.example.com/api/avocado"
+        };
+        assert.equal(getOrchestratorUrl(), "https://villa.example.com/api/avocado");
+        // And an explicit env var still outranks both.
+        process.env.ORCHESTRATOR_URL = "http://localhost:9999/api/avocado";
+        assert.equal(getOrchestratorUrl(), "http://localhost:9999/api/avocado");
+    }
+    finally {
+        if (prev === undefined)
+            delete process.env.ORCHESTRATOR_URL;
+        else
+            process.env.ORCHESTRATOR_URL = prev;
+        if (prevMount === undefined)
+            delete g["__avocado_library_mount__"];
+        else
+            g["__avocado_library_mount__"] = prevMount;
+    }
+});
+test("with nothing mounted the fallback still applies, and says so out loud", () => {
+    const prev = process.env.ORCHESTRATOR_URL;
+    const g = globalThis;
+    const prevMount = g["__avocado_library_mount__"];
+    const said = [];
+    const prevWarn = console.warn;
+    try {
+        delete process.env.ORCHESTRATOR_URL;
+        delete g["__avocado_library_mount__"];
+        console.warn = (...args) => { said.push(args.join(" ")); };
+        assert.equal(getOrchestratorUrl(), "http://127.0.0.1:4200");
+        assert.equal(said.length, 1, "the fallback warns exactly once");
+        assert.match(said[0], /ORCHESTRATOR_URL is not set/);
+        assert.match(said[0], /createOrchestrator/);
+        getOrchestratorUrl();
+        assert.equal(said.length, 1, "and not on every subsequent read");
+    }
+    finally {
+        console.warn = prevWarn;
+        if (prev === undefined)
+            delete process.env.ORCHESTRATOR_URL;
+        else
+            process.env.ORCHESTRATOR_URL = prev;
+        if (prevMount === undefined)
+            delete g["__avocado_library_mount__"];
+        else
+            g["__avocado_library_mount__"] = prevMount;
+    }
+});

package/dist/editor.d.ts

@@ -1,20 +1,8 @@
 export { EditorOverlay } from "./editor-overlay.tsx";
 export { buildEditorQuerySuffix } from "./editor-query.ts";
-export declare function getPreviewWrapperProps(editorMode: boolean, blockId: string, blockType: string): {
-    readonly "data-block-id"?: undefined;
-    readonly "data-block-type"?: undefined;
-    readonly className?: undefined;
-    readonly style?: undefined;
-} | {
-    readonly "data-block-id": string;
-    readonly "data-block-type": string;
-    readonly className: "editor-selectable";
-    readonly style: {
-        readonly viewTransitionName: `block-${string}`;
-    };
-};
+export { getPreviewWrapperProps, editableProps } from "./markers.ts";
 export { renderBlocks } from "./render-blocks.tsx";
 export { RenderedBlocks, PreviewBlock } from "./live-preview-blocks.tsx";
-export { LivePreviewProvider } from "@avocadostudio-ai/preview-adapter";
+export { LivePreviewProvider, useLivePreviewBlocks } from "@avocadostudio-ai/preview-adapter";
 export type { LivePreviewPage, LivePreviewBridgeApi } from "@avocadostudio-ai/preview-adapter";
 export { getEditorCorsOrigins, applyEditorCors, createEditorCorsOptionsHandler } from "./editor-cors.ts";

package/dist/editor.js

@@ -2,21 +2,30 @@
 export { EditorOverlay } from "./editor-overlay.js";
 // Editor query param utilities
 export { buildEditorQuerySuffix } from "./editor-query.js";
-// Block wrapper props for preview mode
-export function getPreviewWrapperProps(editorMode, blockId, blockType) {
-    if (!editorMode)
-        return {};
-    return {
-        "data-block-id": blockId,
-        "data-block-type": blockType,
-        className: "editor-selectable",
-        style: { viewTransitionName: `block-${blockId}` }
-    };
-}
+/*
+ * The two field/block attribute helpers live in `site-sdk/markers`, a leaf
+ * entry with no React in it. They are re-exported here so existing imports
+ * keep working — but import them from `@avocadostudio-ai/site-sdk/markers` in
+ * anything a public page can reach. This entry also exports `EditorOverlay`
+ * and the live-preview provider, and a `'use client'` component that reaches
+ * for the two-line attribute helper from here drags the whole editor into the
+ * public bundle: +66 kB First Load JS, for identical markup.
+ */
+export { getPreviewWrapperProps, editableProps } from "./markers.js";
 // Block rendering helper
 export { renderBlocks } from "./render-blocks.js";
 // Live-preview store renderer (streams field drafts through React)
 export { RenderedBlocks, PreviewBlock } from "./live-preview-blocks.js";
-export { LivePreviewProvider } from "@avocadostudio-ai/preview-adapter";
+/*
+ * The React live-preview path, both halves.
+ *
+ * `useLivePreviewBlocks` used to be the one documented import a site could not
+ * satisfy: `LivePreviewProvider` was re-exported here and the hook was not, so
+ * the walkthrough's own example told the reader to import from
+ * `@avocadostudio-ai/preview-adapter` — a dependency of this package, not of
+ * theirs. Under pnpm that does not resolve at all; under npm it resolves until
+ * a re-hoist. A provider with no way to read it was never a coherent boundary.
+ */
+export { LivePreviewProvider, useLivePreviewBlocks } from "@avocadostudio-ai/preview-adapter";
 // Editor CORS utilities
 export { getEditorCorsOrigins, applyEditorCors, createEditorCorsOptionsHandler } from "./editor-cors.js";

package/dist/live-preview-blocks.js

@@ -17,7 +17,7 @@ import { memo } from "react";
 import { SharedBlockRenderer, BlockErrorBoundary } from "@avocadostudio-ai/blocks";
 import { getChromeTypes } from "@avocadostudio-ai/shared";
 import { useLivePreviewBlocks } from "@avocadostudio-ai/preview-adapter";
-import { getPreviewWrapperProps } from "./editor.js";
+import { getPreviewWrapperProps } from "./markers.js";
 const CHROME_BLOCK_TYPES = new Set(getChromeTypes());
 export const PreviewBlock = memo(function PreviewBlock({ block }) {
     return (_jsx("div", { id: block.id, ...getPreviewWrapperProps(true, block.id, block.type), children: _jsx(BlockErrorBoundary, { blockId: block.id, blockType: block.type, resetKey: block, children: _jsx(SharedBlockRenderer, { block: block }) }) }));

package/dist/markers.d.ts

@@ -0,0 +1,78 @@
+import type { FieldKind } from "@avocadostudio-ai/shared";
+/**
+ * Mark the element that is one block, so the editor can select it.
+ *
+ * Selection is built entirely on `[data-block-id]`: a click in the preview
+ * resolves through `closest("[data-block-id]")`, and no match is read as
+ * "clicked outside any block", which *clears* the selection. Marking fields
+ * without this gets you a preview that frames, renders and scrolls correctly
+ * and deselects on every click — which looks exactly like selection mode being
+ * switched off.
+ *
+ * Returns `{}` when `editorMode` is false, so the published page renders
+ * precisely the markup it rendered before.
+ */
+export declare function getPreviewWrapperProps(editorMode: boolean, blockId: string, blockType: string): {
+    readonly "data-block-id"?: undefined;
+    readonly "data-block-type"?: undefined;
+    readonly className?: undefined;
+    readonly style?: undefined;
+} | {
+    readonly "data-block-id": string;
+    readonly "data-block-type": string;
+    readonly className: "editor-selectable";
+    readonly style: {
+        readonly viewTransitionName: `block-${string}`;
+    };
+};
+/**
+ * Mark the element that draws one editable field.
+ *
+ * This is the second half of instrumenting a preview, and until recently it was
+ * the half with no helper. `getPreviewWrapperProps` covers the block boundary
+ * and is named, exported and documented; the per-field attributes were prose in
+ * the integration guide with a link to a renderer to copy from. The predictable
+ * result is an integration that wraps every block and marks no fields — which
+ * frames, renders, selects, scrolls and opens the property panel correctly, and
+ * silently has no inline text editing, no field pills and no image buttons in
+ * the preview, because every one of those is found by walking
+ * `[data-editable-target]`.
+ *
+ * ```tsx
+ * <div className="hero__media" {...editableProps("imageUrl", { kind: "image" })}>
+ *   <Image src={props.imageUrl} … />
+ * </div>
+ * ```
+ *
+ * The path is the same grammar an operation uses — `title`, `cards[0].title`,
+ * `links[0].children[1].label` — because it is the same path: what the overlay
+ * reads here is what it sends back as the field to patch.
+ *
+ * **Put it on an element, not on the image.** For an image field the attribute
+ * belongs on the wrapper around the `<img>`, never on the image itself: the
+ * overlay appends its Change button *into* the marked element, and nothing can
+ * be appended into an `<img>`.
+ *
+ * **`kind` is how a site says what a field is in its own vocabulary.** Without
+ * it the overlay has to guess an image from the prop name, against Avocado's
+ * own naming (`imageUrl`, `*.src`) — so a site whose field is `photoUrl` or
+ * `heroSrc` gets a picker in the property panel and no button in the preview,
+ * with no error on either side. Pass the same word the block manifest uses and
+ * the guess never runs.
+ *
+ * There is no `editorMode` argument on purpose. These are inert data attributes
+ * that cost a few bytes and do nothing unless the overlay is mounted (all of
+ * its styling is scoped under `[data-editor-active]`), and most sites render
+ * their blocks through components shared with the public pages, where threading
+ * a flag down to every field is the step that does not get done.
+ */
+export declare function editableProps(path: string, options?: {
+    /** Text for the hover pill. Defaults to the path. */
+    label?: string;
+    /** What kind of field this is — the same vocabulary as the block manifest. */
+    kind?: FieldKind;
+}): {
+    readonly "data-editable-kind"?: FieldKind | undefined;
+    readonly "data-editable-target": string;
+    readonly "data-editable-target-label": string;
+};

package/dist/markers.js

@@ -0,0 +1,87 @@
+/*
+ * The two attribute helpers that instrument a preview — and nothing else.
+ *
+ * These are pure functions returning plain data attributes, but until this
+ * entry existed the only way to import them was `@avocadostudio-ai/site-sdk/
+ * editor`, which also exports `EditorOverlay` and the live-preview provider.
+ * Most sites render their blocks through components shared with their public
+ * pages, so following our own advice — mark the fields in the components you
+ * already have — pulled the whole editor into the public bundle. Measured on a
+ * real integration: **+66 kB First Load JS on every page**, for markup that was
+ * byte-for-byte identical.
+ *
+ * `site-sdk/editor` still re-exports both names, so nothing that already
+ * imports them breaks. Import them from here in anything a public page can
+ * reach.
+ */
+/**
+ * Mark the element that is one block, so the editor can select it.
+ *
+ * Selection is built entirely on `[data-block-id]`: a click in the preview
+ * resolves through `closest("[data-block-id]")`, and no match is read as
+ * "clicked outside any block", which *clears* the selection. Marking fields
+ * without this gets you a preview that frames, renders and scrolls correctly
+ * and deselects on every click — which looks exactly like selection mode being
+ * switched off.
+ *
+ * Returns `{}` when `editorMode` is false, so the published page renders
+ * precisely the markup it rendered before.
+ */
+export function getPreviewWrapperProps(editorMode, blockId, blockType) {
+    if (!editorMode)
+        return {};
+    return {
+        "data-block-id": blockId,
+        "data-block-type": blockType,
+        className: "editor-selectable",
+        style: { viewTransitionName: `block-${blockId}` }
+    };
+}
+/**
+ * Mark the element that draws one editable field.
+ *
+ * This is the second half of instrumenting a preview, and until recently it was
+ * the half with no helper. `getPreviewWrapperProps` covers the block boundary
+ * and is named, exported and documented; the per-field attributes were prose in
+ * the integration guide with a link to a renderer to copy from. The predictable
+ * result is an integration that wraps every block and marks no fields — which
+ * frames, renders, selects, scrolls and opens the property panel correctly, and
+ * silently has no inline text editing, no field pills and no image buttons in
+ * the preview, because every one of those is found by walking
+ * `[data-editable-target]`.
+ *
+ * ```tsx
+ * <div className="hero__media" {...editableProps("imageUrl", { kind: "image" })}>
+ *   <Image src={props.imageUrl} … />
+ * </div>
+ * ```
+ *
+ * The path is the same grammar an operation uses — `title`, `cards[0].title`,
+ * `links[0].children[1].label` — because it is the same path: what the overlay
+ * reads here is what it sends back as the field to patch.
+ *
+ * **Put it on an element, not on the image.** For an image field the attribute
+ * belongs on the wrapper around the `<img>`, never on the image itself: the
+ * overlay appends its Change button *into* the marked element, and nothing can
+ * be appended into an `<img>`.
+ *
+ * **`kind` is how a site says what a field is in its own vocabulary.** Without
+ * it the overlay has to guess an image from the prop name, against Avocado's
+ * own naming (`imageUrl`, `*.src`) — so a site whose field is `photoUrl` or
+ * `heroSrc` gets a picker in the property panel and no button in the preview,
+ * with no error on either side. Pass the same word the block manifest uses and
+ * the guess never runs.
+ *
+ * There is no `editorMode` argument on purpose. These are inert data attributes
+ * that cost a few bytes and do nothing unless the overlay is mounted (all of
+ * its styling is scoped under `[data-editor-active]`), and most sites render
+ * their blocks through components shared with the public pages, where threading
+ * a flag down to every field is the step that does not get done.
+ */
+export function editableProps(path, options) {
+    return {
+        "data-editable-target": path,
+        "data-editable-target-label": options?.label ?? path,
+        ...(options?.kind ? { "data-editable-kind": options.kind } : {})
+    };
+}

package/dist/next-config.test.js

@@ -97,14 +97,20 @@ test("withAvocado adds what is missing and keeps what was declared", () => {
 });
 test("a config that already declares everything is returned unchanged", () => {
     /*
-     * The other two halves are switched off because they always have something to
-     * add — image hosts, and the server externals — and this test is about the
-     * transpile contract on its own: when there is nothing to add, the wrapper
-     * hands back the very object it was given rather than a copy.
+     * The other halves are switched off because they always have something to add
+     * — image hosts, the server externals, and now the framing headers — and this
+     * test is about the transpile contract on its own: when there is nothing to
+     * add, the wrapper hands back the very object it was given rather than a copy.
      */
     const root = fixture({ "@avocadostudio-ai/shared": { main: "src/index.ts" } });
     const input = { transpilePackages: ["@avocadostudio-ai/shared"] };
-    assert.equal(withAvocado(input, { cwd: root, silent: true, images: false, serverExternals: false }), input);
+    assert.equal(withAvocado(input, {
+        cwd: root,
+        silent: true,
+        images: false,
+        serverExternals: false,
+        framing: false
+    }), input);
 });
 test("merging image hosts does not disturb the transpile list", () => {
     const root = fixture({ "@avocadostudio-ai/shared": { main: "src/index.ts" } });
@@ -353,3 +359,35 @@ test("trailingSlash: false leaves the whole thing to the app", () => {
     const config = withAvocado({ trailingSlash: true }, { cwd: root, silent: true, trailingSlash: false });
     assert.equal(config.skipTrailingSlashRedirect, undefined);
 });
+test("the framing headers are derived from the editor allowlist, both spellings", async () => {
+    const config = withAvocado({}, { cwd: EMPTY_DIR, env: { EDITOR_CORS_ORIGINS: "http://localhost:4103" } });
+    const rules = await config.headers();
+    const editorRule = rules.find((r) => r.has?.[0]?.key === "__editor");
+    const csp = editorRule.headers.find((h) => h.key === "Content-Security-Policy").value;
+    assert.match(csp, /http:\/\/localhost:4103/);
+    assert.match(csp, /http:\/\/127\.0\.0\.1:4103/, "the CLI binds 127.0.0.1 and prints it");
+    assert.match(csp, /^frame-ancestors 'self'/);
+});
+test("the public rule uses `missing:`, or the browser intersects two CSP headers", async () => {
+    const config = withAvocado({}, { cwd: EMPTY_DIR, env: {} });
+    const rules = await config.headers();
+    const publicRule = rules.find((r) => r.missing?.[0]?.key === "__editor");
+    assert.ok(publicRule, "without `missing:` both rules match an editor request");
+    assert.equal(publicRule.headers.find((h) => h.key === "Content-Security-Policy").value, "frame-ancestors 'self';");
+    assert.equal(publicRule.headers.find((h) => h.key === "X-Frame-Options").value, "SAMEORIGIN");
+});
+test("a site's own headers come first, and framing can be turned off", async () => {
+    const own = { source: "/:path*", headers: [{ key: "X-Mine", value: "1" }] };
+    const config = withAvocado({ headers: async () => [own] }, { cwd: EMPTY_DIR, env: {} });
+    const rules = await config.headers();
+    assert.deepEqual(rules[0], own, "Next uses the first match per header");
+    assert.equal(rules.length, 3);
+    const off = withAvocado({}, { cwd: EMPTY_DIR, env: {}, framing: false });
+    assert.equal(off.headers, undefined);
+});
+test("in production nothing is allowed to frame until a deployment names its editor", async () => {
+    const config = withAvocado({}, { cwd: EMPTY_DIR, env: { NODE_ENV: "production" } });
+    const rules = await config.headers();
+    const editorRule = rules.find((r) => r.has?.[0]?.key === "__editor");
+    assert.equal(editorRule.headers.find((h) => h.key === "Content-Security-Policy").value, "frame-ancestors 'self';");
+});

package/dist/render-blocks.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { SharedBlockRenderer, BlockErrorBoundary, getCustomRenderer } from "@avocadostudio-ai/blocks";
 import { getChromeTypes } from "@avocadostudio-ai/shared";
-import { getPreviewWrapperProps } from "./editor.js";
+import { getPreviewWrapperProps } from "./markers.js";
 /**
  * Renders a list of blocks with error boundaries.
  * When `editable` is true, adds preview wrapper attributes for editor overlay selection.

package/dist/server/orchestrator.d.ts

@@ -1 +1 @@
-export { createOrchestrator, jsonFileAdapter, editorApiAdapter, resolveCapabilities, cmsMediaSource, cmsMediaLabel, type CreateOrchestratorConfig, type OrchestratorHandler, type OrchestratorAuth, type AuthContext, type CmsAdapter, type CmsCapabilities, type CmsInlineAsset, type CmsPublishContext, type CmsPublishResult, type CmsPerspective, type CmsReadOptions, type CmsMediaItem, type CmsMediaPage, type CmsMediaQuery, type CmsMediaSource, type CmsMediaSourceConfig, type ResolvedCapabilities } from "@avocadostudio-ai/orchestrator-core";
+export { createOrchestrator, jsonFileAdapter, editorApiAdapter, resolveCapabilities, cmsMediaSource, cmsMediaUploader, cmsMediaLabel, type CreateOrchestratorConfig, type OrchestratorHandler, type OrchestratorAuth, type AuthContext, type CmsAdapter, type CmsCapabilities, type CmsInlineAsset, type CmsPublishContext, type CmsPublishResult, type CmsPerspective, type CmsReadOptions, type CmsMediaItem, type CmsMediaPage, type CmsMediaQuery, type CmsMediaUpload, type CmsMediaSource, type CmsMediaUploader, type CmsMediaSourceConfig, type ResolvedCapabilities } from "@avocadostudio-ai/orchestrator-core";

package/dist/server/orchestrator.js

@@ -11,4 +11,4 @@
 //
 // This file stays so `@avocadostudio-ai/site-sdk/server` — the entry point
 // every example, README and docs page uses — keeps resolving unchanged.
-export { createOrchestrator, jsonFileAdapter, editorApiAdapter, resolveCapabilities, cmsMediaSource, cmsMediaLabel } from "@avocadostudio-ai/orchestrator-core";
+export { createOrchestrator, jsonFileAdapter, editorApiAdapter, resolveCapabilities, cmsMediaSource, cmsMediaUploader, cmsMediaLabel } from "@avocadostudio-ai/orchestrator-core";

package/next-config.d.ts

@@ -44,6 +44,7 @@ export const AVOCADO_SERVER_EXTERNALS: string[]
 export function withAvocado<
   T extends {
     transpilePackages?: string[]
+    headers?: () => Promise<unknown[]> | unknown[]
     images?: { remotePatterns?: unknown[] }
     serverExternalPackages?: string[]
     trailingSlash?: boolean
@@ -70,9 +71,28 @@ export function withAvocado<
      * `createEditorProxy({ trailingSlash: true })`.
      */
     trailingSlash?: boolean
+    /**
+     * Set false to write the framing headers yourself.
+     *
+     * When true (the default), `withAvocado` appends a pair of `headers()` rules
+     * that let the editor frame `?__editor=1` requests — derived from the same
+     * `EDITOR_CORS_ORIGINS` / `NEXT_PUBLIC_EDITOR_ORIGIN` allowlist the editor
+     * API uses, so the two halves cannot disagree. Your own `headers()` entries
+     * come first and win, since Next uses the first match per header.
+     */
+    framing?: boolean
     /** Environment to read the orchestrator origin from. Defaults to `process.env`. */
     env?: Record<string, string | undefined>
   }
 ): T
 
+/** Every origin allowed to frame the preview, both loopback spellings included. */
+export function avocadoEditorOrigins(env?: Record<string, string | undefined>): string[]
+
+/** Just the framing headers, for a site that wants them without the rest. */
+export function withAvocadoFraming<T extends object>(
+  config?: T,
+  env?: Record<string, string | undefined>
+): T
+
 export default withAvocado

package/next-config.mjs

@@ -403,6 +403,88 @@ function builtOrchestratorCore(from, linked) {
  * as it was. Never throws — a helper that can break `next.config` is worse than
  * the bug it fixes.
  */
+
+/*
+ * The framing rule, derived from the one allowlist the site already has.
+ *
+ * A library-mode site names the editor's origin in two places and they must
+ * agree: CORS on the editor API, and `frame-ancestors` on the preview. Every
+ * integration so far hand-wrote the second in `next.config`, and every one of
+ * them hardcoded `:4100` — which is right until the editor is served anywhere
+ * else, and anyone who already runs the standalone stack has to serve it
+ * somewhere else. Then the two halves fail separately and silently: the API
+ * answers 200 with no `access-control-allow-origin` (the Sites page reports the
+ * site as *offline*) and the browser refuses the frame (the preview is a blank
+ * rectangle). Neither names a port, and neither says CORS or CSP.
+ *
+ * Two rules that are easy to get wrong by hand, and are why this is worth
+ * generating:
+ *
+ *  - **Both spellings.** The CLI binds `127.0.0.1` and prints it; every doc says
+ *    `localhost`. `frame-ancestors` compares origins as strings.
+ *  - **`missing:` on the public rule.** Without it both rules match an editor
+ *    request, the browser receives two CSP headers, and it enforces their
+ *    *intersection* — putting `frame-ancestors 'self'` back and blocking the
+ *    frame it just allowed.
+ */
+function bothLoopbackSpellings(origin) {
+  if (origin.includes("localhost")) return [origin, origin.replace("localhost", "127.0.0.1")]
+  if (origin.includes("127.0.0.1")) return [origin, origin.replace("127.0.0.1", "localhost")]
+  return [origin]
+}
+
+export function avocadoEditorOrigins(env = process.env) {
+  const parse = (value) =>
+    (value ?? "")
+      .split(",")
+      .map((entry) => entry.trim().replace(/\/+$/, ""))
+      .filter(Boolean)
+
+  // Mirrors `getEditorCorsOrigins`: a deployment names its editor, development
+  // assumes the one the CLI serves by default.
+  const defaults = env.NODE_ENV === "production" ? [] : ["http://localhost:4100"]
+  const named = [...parse(env.EDITOR_CORS_ORIGINS), ...parse(env.NEXT_PUBLIC_EDITOR_ORIGIN)]
+  return [...new Set([...defaults, ...named].flatMap(bothLoopbackSpellings))]
+}
+
+export function withAvocadoFraming(config = {}, env = process.env) {
+  const origins = avocadoEditorOrigins(env)
+  const existing = config.headers
+  const framing = [
+    {
+      source: "/:path*",
+      has: [{ type: "query", key: "__editor" }],
+      headers: [
+        {
+          key: "Content-Security-Policy",
+          value: `frame-ancestors 'self'${origins.length > 0 ? ` ${origins.join(" ")}` : ""};`
+        }
+      ]
+    },
+    {
+      source: "/:path*",
+      missing: [{ type: "query", key: "__editor" }],
+      headers: [
+        { key: "Content-Security-Policy", value: "frame-ancestors 'self';" },
+        { key: "X-Frame-Options", value: "SAMEORIGIN" }
+      ]
+    }
+  ]
+
+  return {
+    ...config,
+    async headers() {
+      const own = typeof existing === "function" ? ((await existing()) ?? []) : []
+      /*
+       * The site's own rules come first: Next uses the first matching entry per
+       * header, so a site that already set its own CSP keeps it and this adds
+       * nothing. Opt out entirely with `withAvocado(config, { framing: false })`.
+       */
+      return [...own, ...framing]
+    }
+  }
+}
+
 export function withAvocado(config = {}, options = {}) {
   const {
     cwd = process.cwd(),
@@ -410,6 +492,7 @@ export function withAvocado(config = {}, options = {}) {
     images = true,
     serverExternals = true,
     trailingSlash = true,
+    framing = true,
     env = process.env,
   } = options
 
@@ -434,9 +517,10 @@ export function withAvocado(config = {}, options = {}) {
    */
   const base = trailingSlash ? withAvocadoTrailingSlash(config) : config
   const withImages = images ? withAvocadoImages(base, env) : base
+  const framed = framing ? withAvocadoFraming(withImages, env) : withImages
   const result = serverExternals
-    ? withAvocadoServerExternals(withImages, linked === null ? [] : builtOrchestratorCore(cwd, linked))
-    : withImages
+    ? withAvocadoServerExternals(framed, linked === null ? [] : builtOrchestratorCore(cwd, linked))
+    : framed
 
   if (linked === null) return result
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/site-sdk",
-  "version": "0.3.3",
+  "version": "0.5.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,6 +21,21 @@
       "import": "./dist/editor.js",
       "default": "./dist/editor.js"
     },
+    "./markers": {
+      "types": "./dist/markers.d.ts",
+      "import": "./dist/markers.js",
+      "default": "./dist/markers.js"
+    },
+    "./blocks": {
+      "types": "./dist/blocks.d.ts",
+      "import": "./dist/blocks.js",
+      "default": "./dist/blocks.js"
+    },
+    "./coverage": {
+      "types": "./dist/coverage.d.ts",
+      "import": "./dist/coverage.js",
+      "default": "./dist/coverage.js"
+    },
     "./routes": {
       "types": "./dist/routes.d.ts",
       "import": "./dist/routes.js",
@@ -107,16 +122,16 @@
   ],
   "dependencies": {
     "zod": "^4.3.6",
-    "@avocadostudio-ai/blocks": "^0.3.3",
-    "@avocadostudio-ai/preview-adapter": "^0.3.3",
-    "@avocadostudio-ai/shared": "^0.3.3"
+    "@avocadostudio-ai/blocks": "^0.5.0",
+    "@avocadostudio-ai/preview-adapter": "^0.5.0",
+    "@avocadostudio-ai/shared": "^0.5.0"
   },
   "peerDependencies": {
     "next": ">=15.0.0",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
     "better-sqlite3": ">=12.0.0",
-    "@avocadostudio-ai/orchestrator-core": "^0.3.3"
+    "@avocadostudio-ai/orchestrator-core": "^0.5.0"
   },
   "peerDependenciesMeta": {
     "@avocadostudio-ai/orchestrator-core": {