@avocadostudio-ai/site-sdk 0.2.1 → 0.3.0

package/README.md

@@ -10,7 +10,66 @@ SDK for integrating any Next.js site with the Avocado Studio. Provides the contr
 npm install @avocadostudio-ai/site-sdk
 ```
 
-### 2. Create the page component
+### 2. Wrap your Next config
+
+```ts
+// next.config.ts
+import { withAvocado } from "@avocadostudio-ai/site-sdk/next-config"
+
+export default withAvocado({ /* your config */ })
+```
+
+Not optional, and the failures it prevents all look like something else:
+
+- **Native binaries and provider SDKs get bundled.** `better-sqlite3` and
+  `sharp` build fine and die loading their `.node` file on the first request;
+  Turbopack resolves `orchestrator-core`'s optional `await import(...)` peers
+  statically and fails the build over a package you deliberately never
+  installed. `serverExternalPackages` alone does not fix it — `transpilePackages`
+  overrides server externals for a *transitive* dependency. This sets both.
+- **Generated images 500.** Avocado writes image URLs from hosts your site never
+  chose (Unsplash, the image models' blob storage), and `next/image` refuses any
+  host missing from `images.remotePatterns`.
+- **`trailingSlash: true` makes the editor unreachable** — see below.
+
+Pass `{ images: false }`, `{ serverExternals: false }` or
+`{ trailingSlash: false }` as a second argument to manage any of them yourself.
+
+#### If your site sets `trailingSlash: true`, read this
+
+Next applies its trailing-slash 308 to `/api/*` as well, so
+`/api/editor/blocks` answers `308 → /api/editor/blocks/`. `fetch` follows a 308.
+**A CORS preflight does not** — a browser treats a redirect on `OPTIONS` as a
+network failure — and the editor calls those routes from its own origin. Every
+editor API call therefore fails before it is sent, and the browser reports a
+generic CORS error that names nothing. Middleware cannot repair it either: the
+redirect runs before middleware.
+
+`withAvocado` sets `skipTrailingSlashRedirect: true` for you. **That half alone
+is a regression** — it stops your site redirecting `/about` to `/about/`, on
+every URL you have ever published. The SDK's proxy puts the redirect back for
+page routes, and you have to turn it on:
+
+```ts
+// proxy.ts   (middleware.ts on Next 15)
+import { createEditorProxy } from "@avocadostudio-ai/site-sdk/proxy"
+
+export const proxy = createEditorProxy({ trailingSlash: true }).proxy
+
+export const config = {
+  matcher: ["/((?!_next|preview-draft|api|favicon\\.ico|icon\\.svg|logos/|generated-images/|.*\\.).*)"],
+}
+```
+
+These two are a pair. Nothing checks that you set both, because the config
+cannot see your proxy and the proxy cannot read the config.
+
+> Do not hand-roll that redirect from `request.nextUrl.clone()`. NextURL
+> normalises the trailing slash back *off* when it stringifies, so the 308
+> points at the URL it is trying to leave and the browser gives up after five
+> hops. `createEditorProxy` builds it from `request.url`.
+
+### 3. Create the page component
 
 ```tsx
 // app/[[...slug]]/page.tsx
@@ -38,7 +97,7 @@ Export `generateMetadata` too, or every page inherits the root layout's
 from the page and calls `notFound()` for an unknown slug, so add an
 `app/not-found.tsx` if you want your own chrome around the 404.
 
-### 3. Create the editor API route
+### 4. Create the editor API route
 
 ```tsx
 // app/api/editor/[...path]/route.ts
@@ -55,14 +114,14 @@ export const { GET, POST, OPTIONS } = createEditorApiHandler({
 })
 ```
 
-### 4. Add styles
+### 5. Add styles
 
 ```tsx
 // app/layout.tsx
 import "@avocadostudio-ai/blocks/styles.css"
 ```
 
-### 5. Set environment variables
+### 6. Set environment variables
 
 ```env
 # Required
@@ -86,14 +145,34 @@ 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
+integration needs — `createOrchestrator` is the whole of library mode and was in
+none of them.
+
 | Import | What it provides |
 |---|---|
 | `@avocadostudio-ai/site-sdk` | Types (`PageDoc`, `BlockInstance`), `buildSlug`, `renderBlocks` |
-| `@avocadostudio-ai/site-sdk/page` | `createSitePage` — page component factory |
-| `@avocadostudio-ai/site-sdk/routes` | `createEditorApiHandler` — API route factory |
-| `@avocadostudio-ai/site-sdk/draft` | `resolveEditorContext`, `fetchEditorPage` |
-| `@avocadostudio-ai/site-sdk/editor` | `renderBlocks`, `EditorOverlay` |
-| `@avocadostudio-ai/site-sdk/navigation` | `buildNavItems`, `buildSiteHeaderBlock` |
+| `.../page` | `createSitePage` — page component factory |
+| `.../routes` | `createEditorApiHandler` — the `/api/editor/*` route factory |
+| `.../routes/core` | The same handlers without Next's `draftMode()`, for a non-Next host |
+| `.../server` | **`createOrchestrator`**, `jsonFileAdapter`, `editorApiAdapter`, `resolveCapabilities`, and the `CmsAdapter` / `CreateOrchestratorConfig` types |
+| `.../next-config` | `withAvocado`, `AVOCADO_IMAGE_HOSTS`, `AVOCADO_SERVER_EXTERNALS` |
+| `.../proxy` | `createEditorProxy` — the Next 16 `proxy.ts` rewrite |
+| `.../middleware` | `createEditorMiddleware` — the same thing under the Next 15 name |
+| `.../matcher` | `buildEditorMatcher` — just the matcher string, no `next/server` import |
+| `.../draft` | `resolveEditorContext`, `fetchEditorPage`, `fetchEditorSlugs`, `fetchEditorSiteConfig` |
+| `.../draft/core` | The draft context without Next's cookie APIs |
+| `.../editor` | `EditorOverlay`, `LivePreviewProvider`, `buildEditorQuerySuffix` |
+| `.../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` — the hook that reads `LivePreviewProvider`, and the only
+way to render a live draft through **your own** components rather than Avocado's
+— is not here. It lives in `@avocadostudio-ai/preview-adapter`, which you have to
+install directly.
 
 ## API Contract
 
@@ -107,6 +186,149 @@ Your site exposes these endpoints via `createEditorApiHandler`:
 | `/api/editor/pages` | GET | Return all published pages |
 | `/api/editor/publish` | POST | Receive pages from editor, persist to CMS |
 
+## Library mode mounts two handlers, not one
+
+`createOrchestrator` is not a replacement for `createEditorApiHandler`. It is an
+addition, and the editor does not work without both.
+
+```ts
+// app/api/avocado/[[...path]]/route.ts   — the orchestrator
+import { createOrchestrator } from "@avocadostudio-ai/site-sdk/server"
+
+const handler = createOrchestrator({ basePath: "/api/avocado", adapter: myAdapter })
+export const GET = handler
+export const POST = handler
+export const OPTIONS = handler
+```
+
+```ts
+// app/api/editor/[...path]/route.ts      — still required
+import { createEditorApiHandler } from "@avocadostudio-ai/site-sdk/routes"
+
+export const { GET, POST, OPTIONS } = createEditorApiHandler({ getPages, getManifest })
+```
+
+The editor UI asks the orchestrator for plans and operations, and asks **your
+site's own origin** for `/api/editor/blocks` and `/api/editor/pages`. Mount only
+the orchestrator and the editor loads, connects, and answers four requests with
+`net::ERR_FAILED` in a console you have to open to see.
+
+## The adapter contract
+
+`createOrchestrator({ adapter })` is the whole of library mode: SQLite is the
+working copy for drafts, undo and chat state, and the adapter is your actual
+content store. It is read on a cold session and written on publish.
+
+```ts
+import type { CmsAdapter } from "@avocadostudio-ai/site-sdk/server"
+
+const myAdapter: CmsAdapter = {
+  /** Short, DNS-safe. Used for telemetry and the bootstrap cache. */
+  id: "sanity",
+
+  /** Does `getPages` honour `options.perspective`? Silence means no. */
+  perspectives: Boolean(process.env.SANITY_API_READ_TOKEN),
+
+  /** Every page for this site. Failures are logged, not fatal — the session starts empty. */
+  async getPages(options) {
+    return fetchPages({ draft: options?.perspective === "draft" })
+  },
+
+  /** Optional. Absent means publish is a local no-op. */
+  async onPublish(pages, config, context) {
+    // context.published — what you last reported, when the orchestrator has it
+    // context.assets    — base64 blobs from chat-generated images, for you to upload
+    return { ok: true, unsupported: [] }
+  },
+
+  /** Optional. Fills the editor's image picker from your media library. */
+  async getMedia({ query, page, limit }) {
+    const res = await searchAssets(query, page, limit)
+    return { items: res.assets, totalPages: res.pageCount, label: "Sanity" }
+  },
+
+  /** Static, because /whoami must answer it with the CMS unreachable. */
+  capabilities: { createPages: false },
+}
+```
+
+Two parts of that are easy to get wrong:
+
+**`perspectives` defaults to "no", and the other flags default to "yes".** That
+asymmetry is deliberate: capabilities are permissions, where the safe answer is
+to allow what nobody forbade; `perspectives` is an ability, where the safe answer
+is not to claim one nobody implemented. An adapter wrongly believed to read
+drafts makes the publish diff assert that unpublished work is live.
+
+**`onPublish` should diff, not overwrite.** Every CMS read is a projection — an
+asset reference flattened to a URL, rich text flattened to a string — and writing
+the projection back destroys what it was projected from. `context.published` is
+the baseline; `undefined` means *no baseline available*, never *the site was
+empty*. See [Publishing back to a real CMS](#publishing-back-to-a-real-cms).
+
+`CmsAdapter`, `CmsCapabilities`, `CmsPublishContext`, `CmsPerspective` and
+`CreateOrchestratorConfig` are all exported from
+`@avocadostudio-ai/site-sdk/server`.
+
+### Filling the image picker
+
+`getMedia` is optional and silent by default: implement it and the editor's
+asset picker grows a CMS tab, leave it off and it does not. `/status/planner`
+reports `features.cmsMedia` and `/whoami` reports `capabilities.readsMedia`,
+both derived from whether the method exists — an adapter cannot claim a media
+library it did not implement.
+
+If your CMS is Contentful, Sanity or Strapi, `cmsMediaSource` writes the method
+for you:
+
+```ts
+import { cmsMediaSource, type CmsAdapter } from "@avocadostudio-ai/site-sdk/server"
+
+export function sanityAdapter(): CmsAdapter {
+  return {
+    id: "sanity",
+    getPages: (options) => getSanityPages(options?.perspective),
+    getMedia: cmsMediaSource({
+      provider: "sanity",
+      projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID!,
+      dataset: process.env.NEXT_PUBLIC_SANITY_DATASET,
+      token: process.env.SANITY_API_TOKEN
+    })
+  }
+}
+```
+
+It is a convenience, not the contract. Any other CMS returns the same shape
+itself:
+
+```ts
+getMedia: async ({ query, page, limit }) => {
+  const res = await myCms.assets.search({ q: query, page, perPage: limit })
+  return {
+    items: res.assets.map((a) => ({
+      id: a.id,
+      name: a.filename,
+      imageUrl: a.url,
+      thumbUrl: a.thumb ?? a.url,
+      alt: a.altText
+    })),
+    totalPages: res.pageCount,
+    label: "My CMS"
+  }
+}
+```
+
+`query` is a free-text filter and may be absent; `page` is 1-based and `limit`
+is clamped to 50 before it reaches you. Return an empty page rather than
+throwing when the upstream call fails — the picker renders an empty grid, and a
+rejected promise inside a modal shows the user nothing at all.
+
+The credentials stay on the server. Before this method existed the picker
+called Contentful, Sanity and Strapi from the browser, over a union of exactly
+those three compiled into the editor — which is why a fourth CMS could bring
+its own adapter, blocks and publish handler and still had no way to bring its
+own images.
+
 ## Library mode needs a credential
 
 `createOrchestrator()` mounts on your own domain and can edit and publish your
@@ -187,6 +409,62 @@ 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.
 
+## The editor frames your page, not the preview route
+
+The iframe's `src` is your site's own URL with a query parameter added:
+
+```
+http://localhost:3000/de?__editor=1&session=dev&siteId=my-site
+```
+
+`createEditorProxy` then rewrites that request onto the preview route. **The
+rewrite does not re-run Next's header matching**, so `headers()` was already
+evaluated against `/de` — the public path — and the preview HTML comes back
+wearing the public site's headers.
+
+That matters for exactly one thing, and it is the first thing an adopter sees
+after wiring everything up correctly: **a site that sends `frame-ancestors` or
+`X-Frame-Options` cannot be framed**, and the failure is a blank rectangle. The
+response is correct, the render is correct, and the browser refuses to display
+it.
+
+Scope the exception to the query parameter, which is the only part of the
+request Next sees before the rewrite:
+
+```js
+async headers() {
+  const editor = "http://localhost:4100 http://127.0.0.1:4100"
+  return [
+    {
+      source: "/:path*",
+      has: [{ type: "query", key: "__editor" }],
+      headers: [{ key: "Content-Security-Policy", value: `frame-ancestors 'self' ${editor};` }]
+    },
+    {
+      source: "/:path*",
+      missing: [{ type: "query", key: "__editor" }],
+      headers: [
+        { key: "Content-Security-Policy", value: "frame-ancestors 'self';" },
+        { key: "X-Frame-Options", value: "SAMEORIGIN" }
+      ]
+    }
+  ]
+}
+```
+
+Two things that are easy to get wrong here:
+
+**The `missing:` on the public rule is load-bearing.** Without it both rules
+match an editor request and the browser gets two `Content-Security-Policy`
+headers — which it reads as their *intersection*, putting `frame-ancestors
+'self'` back and blocking the frame again.
+
+**Name both spellings of the loopback address.** The CLI binds `127.0.0.1` and
+prints that; everything written down says `localhost`. `frame-ancestors` and
+CORS both compare origins as strings, so a rule copied from this page and an
+editor opened at the URL the CLI printed will never match. The SDK's own
+development CORS default now accepts both; your CSP has to say both too.
+
 ## Telling the orchestrator where your site is
 
 An agent's only way to see what it just edited is `POST /preview/screenshot`,
@@ -220,11 +498,11 @@ string, a document reference resolved to one language's href, rich text
 flattened to markdown. Writing the projection back replaces the reference with
 the flattening and destroys the document.
 
-So publish a **diff**, not a snapshot. `@ai-site-editor/site-sdk/publish` owns
+So publish a **diff**, not a snapshot. `@avocadostudio-ai/site-sdk/publish` owns
 the walk:
 
 ```ts
-import { diffPage, groupPatches, describeUnsupported } from "@ai-site-editor/site-sdk/publish"
+import { diffPage, groupPatches, describeUnsupported } from "@avocadostudio-ai/site-sdk/publish"
 
 const diff = diffPage({
   page,
@@ -264,9 +542,14 @@ Two things worth knowing before you write one.
 
 **List items match on their own key, not their position.** An index-addressed
 patch lands on the wrong row the moment anything reorders the array upstream.
-`sanityPaths` (the default) addresses `field[_key=="…"]`; `indexPaths` exists for
-stores with no element identity and is only correct when your publish is the
-only writer.
+`sanityPaths` addresses `field[_key=="…"]`; `indexPaths` exists for stores with
+no element identity and is only correct when your publish is the only writer.
+
+`paths` is a **required** argument to both `diffFields` and `diffPage`. It used
+to default to `sanityPaths`, which meant a Contentful or Strapi publisher that
+never mentioned it emitted `_key` patches against a store that has no `_key` —
+the wrong answer, arrived at quietly. Nothing can infer which CMS you are
+writing to, so it asks.
 
 **Refusing is a result, not an error.** Four things a field diff cannot express
 — a replaced image, a retyped link, a list item added or removed, a new block —
@@ -281,6 +564,88 @@ absent after a restart that reloaded the draft from storage. Treat `undefined`
 as "no baseline available", never as "the site was empty": publishing every
 field on that assumption is the overwrite all of this exists to prevent.
 
+## Registering your own block schemas
+
+The manifest at `/api/editor/blocks` tells the **editor** what exists. It is not
+what validates an edit — that is the global block registry in
+`@avocadostudio-ai/shared`, which starts out holding only Avocado's built-ins.
+Ship a manifest and no registration and the editor looks completely wired up
+until the first AI edit:
+
+```json
+{"error":"Invalid props for PricingTable: Unknown block type: PricingTable","errorCode":"schema_violation"}
+```
+
+```ts
+// lib/register-blocks.ts
+import { registerBlock, z } from "@avocadostudio-ai/shared"
+
+export function registerMyBlocks() {
+  registerBlock("PricingTable", {
+    schema: z.object({
+      title: z.string().min(1),
+      // A list needs BOTH halves — see the warning below.
+      tiers: z.array(z.object({
+        name: z.string().min(1),
+        price: z.string().min(1),
+      })).optional(),
+    }).catchall(z.unknown()),
+
+    meta: {
+      displayName: "Pricing Table",
+      fields: { title: { kind: "text" } },
+      listFields: {
+        tiers: { label: "Tiers", itemFields: { name: { kind: "text" }, price: { kind: "text" } } },
+      },
+    },
+  })
+}
+```
+
+Hand that function to whichever handler you mount — both re-run it after the
+built-ins have registered, so your definitions land on top:
+
+```ts
+createEditorApiHandler({ getPages, getManifest, registerBlocks: registerMyBlocks })
+createOrchestrator({ adapter, registerBlocks: registerMyBlocks })
+```
+
+Do **not** instead rely on a side-effect `import "@/lib/register-blocks"` placed
+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`
+
+`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"`
+resolves to whatever your tree hoisted — on any site that also uses Sanity that
+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.
+
+### `schema` and `meta` are two halves that must agree
+
+`meta.listFields` says how to *label* a list's rows. The props schema is what
+says the list exists, and the property panel renders rows from the schema — so a
+list named only in the meta shows no rows and no Add control, with no error
+anywhere. Validation passes, operations apply, the preview renders, publishing
+diffs the rows correctly. The only symptom is an absence in one panel.
+
+That failure hides especially well behind `.catchall(z.unknown())`, which most
+CMS integrations need (see [Publishing back to a real CMS](#publishing-back-to-a-real-cms),
+which recommends keeping a `__source` snapshot in block props): the catchall
+swallows the undeclared array as an unmodelled extra.
+
+`registerBlock` now warns when it sees the contradiction:
+
+```
+[avocado] PricingTable: meta.listFields declares "tiers" but the schema has no `tiers`.
+The property panel renders list rows from the schema, so this list will show no rows
+and no Add control. Declare it alongside the meta, e.g. tiers: z.array(z.object({ … })).optional()
+```
+
 ## Telling the orchestrator which blocks you render
 
 Importing anything from `@avocadostudio-ai/shared` registers Avocado's 18
@@ -309,6 +674,39 @@ Declaring a type you never registered is not silently dropped: it has no schema
 to describe, so it cannot reach the manifest, and the orchestrator logs a warning
 naming it the first time the manifest is served.
 
+## Making fields editable
+
+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:
+
+```tsx
+<h1 data-editable-target="heading">{heading}</h1>
+<p  data-editable-target="subheading">{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} />
+  </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.
+
+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.
+
+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.
+
 ## Environment Variables
 
 | Variable | Required | Description |

package/dist/editor-cors.d.ts

@@ -1,7 +1,8 @@
 /**
  * CORS for the editor API routes a host app mounts.
  *
- * The dev editor runs on its own origin (`localhost:4100`), so the routes have
+ * The dev editor runs on its own origin (`localhost:4100`, or the `127.0.0.1`
+ * spelling the CLI prints), so the routes have
  * to answer cross-origin requests from it. That default used to be added
  * unconditionally, which meant a deployed site kept answering CORS-approved
  * requests to a `localhost` origin: any page a visitor had open could read that

package/dist/editor-cors.js

@@ -1,14 +1,27 @@
 /**
  * CORS for the editor API routes a host app mounts.
  *
- * The dev editor runs on its own origin (`localhost:4100`), so the routes have
+ * The dev editor runs on its own origin (`localhost:4100`, or the `127.0.0.1`
+ * spelling the CLI prints), so the routes have
  * to answer cross-origin requests from it. That default used to be added
  * unconditionally, which meant a deployed site kept answering CORS-approved
  * requests to a `localhost` origin: any page a visitor had open could read that
  * site's draft content out of its own browser. Now the development default is
  * only assumed in development, and a deployment says what it allows.
  */
-const DEV_EDITOR_ORIGIN = "http://localhost:4100";
+/*
+ * Both spellings of the same loopback address, because the product uses both.
+ *
+ * The CLI binds `127.0.0.1` and prints `http://127.0.0.1:4100`; every README,
+ * env table and example says `http://localhost:4100`. CORS and
+ * `frame-ancestors` compare origins as strings, so an editor started by our own
+ * CLI, opened at the URL our own CLI printed, was rejected by our own default —
+ * and the symptom is a blank iframe with a console message naming an origin
+ * that looks like it should have matched.
+ *
+ * Development only, as below: a deployment still has to name its editor.
+ */
+const DEV_EDITOR_ORIGINS = ["http://localhost:4100", "http://127.0.0.1:4100"];
 let cachedOrigins;
 function parseOrigins(value) {
     return (value ?? "")
@@ -27,7 +40,7 @@ export function getEditorCorsOrigins() {
      */
     const declaredEditor = parseOrigins(process.env.NEXT_PUBLIC_EDITOR_ORIGIN);
     const isProduction = process.env.NODE_ENV === "production";
-    const defaults = isProduction ? [] : [DEV_EDITOR_ORIGIN];
+    const defaults = isProduction ? [] : DEV_EDITOR_ORIGINS;
     cachedOrigins = new Set([...defaults, ...declaredEditor, ...configured]);
     return cachedOrigins;
 }

package/dist/editor-cors.test.js

@@ -64,3 +64,22 @@ test("an allowed origin gets the CORS headers and a disallowed one does not", ()
         assert.equal(denied.headers.get("Vary"), "Origin");
     });
 });
+/*
+ * The CLI binds `127.0.0.1` and prints that URL; the docs all say `localhost`.
+ * Origins compare as strings, so the editor our own CLI starts has to be
+ * allowed under the spelling our own CLI printed.
+ */
+test("development allows both spellings of the loopback editor origin", () => {
+    withEnv({ ...CLEAN, NODE_ENV: "development" }, () => {
+        const origins = getEditorCorsOrigins();
+        assert.ok(origins.has("http://localhost:4100"), "the spelling the docs use");
+        assert.ok(origins.has("http://127.0.0.1:4100"), "the spelling the CLI prints");
+    });
+});
+test("production still allows neither by default", () => {
+    withEnv({ ...CLEAN, NODE_ENV: "production" }, () => {
+        const origins = getEditorCorsOrigins();
+        assert.equal(origins.has("http://localhost:4100"), false);
+        assert.equal(origins.has("http://127.0.0.1:4100"), false);
+    });
+});

package/dist/publish/field-diff.d.ts

@@ -124,7 +124,15 @@ export declare function diffFields<Ctx>(args: {
     /** Path prefix this object sits at, e.g. `pageBuilder[_key=="b1"].`. */
     prefix?: string;
     where: string;
-    paths?: PathSyntax;
+    /**
+     * How this CMS addresses one element of a list. Required, and deliberately
+     * so: it used to default to `sanityPaths`, which meant a Contentful or
+     * Strapi publisher that never mentioned it emitted `field[_key=="…"]`
+     * patches against a store with no `_key`. The wrong answer was the quiet
+     * one — a default cannot know which CMS it is writing to, and the cost of
+     * guessing wrong is a patch applied to the wrong row.
+     */
+    paths: PathSyntax;
 }): FieldDiff;
 /**
  * Fold a flat patch list into one `set` object per document.
@@ -180,7 +188,8 @@ export declare function diffPage<Ctx>(args: {
         type: string;
         props: Record<string, unknown>;
     }): BlockTarget<Ctx> | BlockTarget<Ctx>[] | null;
-    paths?: PathSyntax;
+    /** How this CMS addresses one element of a list. See `diffFields`. */
+    paths: PathSyntax;
     /** How a block is named in a report. Defaults to `"/slug → type"`. */
     where?(pageSlug: string, block: {
         id: string;

package/dist/publish/field-diff.js

@@ -71,7 +71,11 @@ function defaultItemKey(item) {
  * cannot make a patch land on the wrong row.
  */
 export function diffFields(args) {
-    const paths = args.paths ?? sanityPaths;
+    /* A JS caller gets no compile error, so say it loudly rather than picking
+     * one. Silently choosing a syntax is the bug this parameter exists to stop. */
+    if (!args.paths)
+        throw new TypeError("diffFields: `paths` is required — pass sanityPaths or indexPaths");
+    const paths = args.paths;
     const prefix = args.prefix ?? "";
     const patches = [];
     const unsupported = [];

package/dist/publish/field-diff.test.js

@@ -14,7 +14,8 @@ test("an unchanged field emits nothing", () => {
         source: { heading: "Same" },
         ctx,
         documentId: "doc1",
-        where: "/ → hero"
+        where: "/ → hero",
+        paths: sanityPaths
     });
     assert.deepEqual(diff.patches, []);
     assert.deepEqual(diff.unsupported, []);
@@ -27,7 +28,8 @@ test("a changed field is set at the path that owns it", () => {
         ctx,
         documentId: "doc1",
         prefix: 'pageBuilder[_key=="b1"].',
-        where: "/ → hero"
+        where: "/ → hero",
+        paths: sanityPaths
     });
     assert.deepEqual(diff.patches, [
         { documentId: "doc1", path: 'pageBuilder[_key=="b1"].heading', value: "After" }
@@ -40,7 +42,8 @@ test("cmsKey writes to the field the CMS actually has", () => {
         source: { heading: "Before" },
         ctx,
         documentId: "doc1",
-        where: "/ → hero"
+        where: "/ → hero",
+        paths: sanityPaths
     });
     assert.equal(diff.patches[0].path, "headingOverride");
 });
@@ -62,7 +65,8 @@ test("rehydrate receives the stored value, so an inversion can be partial", () =
         source: { image: { _type: "image", asset: { _ref: "image-abc" }, alt: "Old alt" } },
         ctx,
         documentId: "doc1",
-        where: "/ → hero"
+        where: "/ → hero",
+        paths: sanityPaths
     });
     assert.deepEqual(diff.patches[0].value, {
         _type: "image",
@@ -94,7 +98,8 @@ test("refusal 1 — a projection that cannot be inverted is reported, not guesse
         source: { image: { url: "https://cdn.example.com/old.png", alt: "Old" } },
         ctx,
         documentId: "doc1",
-        where: "/ → hero"
+        where: "/ → hero",
+        paths: sanityPaths
     });
     assert.deepEqual(diff.patches, [], "nothing may be written for a value that cannot be expressed");
     assert.equal(diff.unsupported.length, 1);
@@ -114,7 +119,8 @@ test("refusal 2 — adding or removing list items is a document-shaped change",
         source: { cards: [{ _key: "k1", title: "One" }] },
         ctx,
         documentId: "doc1",
-        where: "/ → cardGrid"
+        where: "/ → cardGrid",
+        paths: sanityPaths
     });
     assert.ok(diff.unsupported.some((u) => /added to or removed/.test(u.change)));
 });
@@ -131,7 +137,8 @@ test("refusal 3 — an item the CMS has never seen has no path to patch", () =>
         source: { cards: [{ _key: "k1", title: "One" }, { _key: "k2", title: "Two" }] },
         ctx,
         documentId: "doc1",
-        where: "/ → cardGrid"
+        where: "/ → cardGrid",
+        paths: sanityPaths
     });
     assert.ok(diff.unsupported.some((u) => /new item/.test(u.change)));
     assert.ok(!diff.patches.some((p) => p.value === "Brand new"), "a keyless item must not be written to whatever path happens to be at its index");
@@ -143,6 +150,7 @@ test("refusal 4 — a block with no upstream document is reported, never skipped
             blocks: [{ id: "b_new", type: "pba_pricingSection", props: { heading: "Hi" } }]
         },
         ctx,
+        paths: sanityPaths,
         locate: () => null
     });
     assert.deepEqual(diff.patches, []);
@@ -168,7 +176,8 @@ test("a list item is patched at its own key, not at its position", () => {
         source: { cards: [{ _key: "k1", title: "One" }, { _key: "k2", title: "Two" }] },
         ctx,
         documentId: "doc1",
-        where: "/ → cardGrid"
+        where: "/ → cardGrid",
+        paths: sanityPaths
     });
     assert.deepEqual(diff.patches, [
         { documentId: "doc1", path: 'cards[_key=="k2"].title', value: "Renamed" }
@@ -226,6 +235,7 @@ test("one block can write to two documents", () => {
             blocks: [{ id: "b1", type: "sharedSection", props: { heading: "Page heading", body: "Shared body" } }]
         },
         ctx,
+        paths: sanityPaths,
         locate: () => [
             {
                 documentId: "page-1",
@@ -250,6 +260,7 @@ test("a page with nothing changed issues no write at all", () => {
     const diff = diffPage({
         page: { slug: "/", blocks: [{ id: "b1", type: "hero", props: { heading: "Same" } }] },
         ctx,
+        paths: sanityPaths,
         locate: () => ({
             documentId: "page-1",
             prefix: "",

package/dist/server/orchestrator.d.ts

@@ -1 +1 @@
-export { createOrchestrator, jsonFileAdapter, editorApiAdapter, resolveCapabilities, type CreateOrchestratorConfig, type OrchestratorHandler, type OrchestratorAuth, type AuthContext, type CmsAdapter, type CmsCapabilities, type CmsInlineAsset, type CmsPublishContext, type CmsPublishResult, type CmsPerspective, type CmsReadOptions, type ResolvedCapabilities } from "@avocadostudio-ai/orchestrator-core";
+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";

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 } from "@avocadostudio-ai/orchestrator-core";
+export { createOrchestrator, jsonFileAdapter, editorApiAdapter, resolveCapabilities, cmsMediaSource, cmsMediaLabel } from "@avocadostudio-ai/orchestrator-core";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/site-sdk",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -107,16 +107,16 @@
   ],
   "dependencies": {
     "zod": "^4.3.6",
-    "@avocadostudio-ai/shared": "0.2.1",
-    "@avocadostudio-ai/blocks": "0.2.1",
-    "@avocadostudio-ai/preview-adapter": "0.2.1"
+    "@avocadostudio-ai/preview-adapter": "^0.3.0",
+    "@avocadostudio-ai/blocks": "^0.3.0",
+    "@avocadostudio-ai/shared": "^0.3.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.2.1"
+    "@avocadostudio-ai/orchestrator-core": "^0.3.0"
   },
   "peerDependenciesMeta": {
     "@avocadostudio-ai/orchestrator-core": {
@@ -132,6 +132,17 @@
     "typescript": "^5.7.3"
   },
   "description": "SDK for adding Avocado Studio AI editing and live preview to a Next.js site",
+  "keywords": [
+    "avocado",
+    "avocado-studio",
+    "nextjs",
+    "cms",
+    "visual-editing",
+    "page-builder",
+    "ai",
+    "content-editor",
+    "draft-mode"
+  ],
   "license": "Apache-2.0",
   "homepage": "https://github.com/avocadostudio-ai/avocado/tree/main/packages/site-sdk#readme",
   "bugs": {