@avocadostudio-ai/site-sdk 0.2.3 → 0.3.0

package/README.md

@@ -241,8 +241,14 @@ const myAdapter: CmsAdapter = {
     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: { createPage: false },
+  capabilities: { createPages: false },
 }
 ```
 
@@ -264,6 +270,65 @@ empty*. See [Publishing back to a real CMS](#publishing-back-to-a-real-cms).
 `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
@@ -344,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`,
@@ -421,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 —

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.3",
+  "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/blocks": "0.2.3",
-    "@avocadostudio-ai/shared": "0.2.3",
-    "@avocadostudio-ai/preview-adapter": "0.2.3"
+    "@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.3"
+    "@avocadostudio-ai/orchestrator-core": "^0.3.0"
   },
   "peerDependenciesMeta": {
     "@avocadostudio-ai/orchestrator-core": {