@avocadostudio-ai/site-sdk 0.4.0 → 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,72 +1,8 @@
-import type { FieldKind } from "@avocadostudio-ai/shared";
 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}`;
-    };
-};
-/**
- * Mark the element that draws one editable field.
- *
- * This is the second half of instrumenting a preview, and until now 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;
-};
+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,69 +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}` }
-    };
-}
-/**
- * Mark the element that draws one editable field.
- *
- * This is the second half of instrumenting a preview, and until now 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.
+/*
+ * 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 function editableProps(path, options) {
-    return {
-        "data-editable-target": path,
-        "data-editable-target-label": options?.label ?? path,
-        ...(options?.kind ? { "data-editable-kind": options.kind } : {})
-    };
-}
+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/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.4.0",
+  "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.4.0",
-    "@avocadostudio-ai/preview-adapter": "^0.4.0",
-    "@avocadostudio-ai/shared": "^0.4.0"
+    "@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.4.0"
+    "@avocadostudio-ai/orchestrator-core": "^0.5.0"
   },
   "peerDependenciesMeta": {
     "@avocadostudio-ai/orchestrator-core": {