@avocadostudio-ai/site-sdk 0.3.2 → 0.3.3

package/README.md

@@ -706,12 +706,26 @@ If you render Avocado's blocks (a scaffolded site does), skip this. If your site
 brought its own, declare them:
 
 ```ts
-export const { GET, POST } = createOrchestrator({
-  adapter,
-  blockTypes: ["acme_hero", "acme_splitSection", "acme_pricing"]
+const SITE_BLOCK_TYPES = ["acme_hero", "acme_splitSection", "acme_pricing"]
+
+// app/api/avocado/[[...path]]/route.ts
+export const { GET, POST } = createOrchestrator({ adapter, blockTypes: SITE_BLOCK_TYPES })
+
+// app/api/editor/[...path]/route.ts — the same list, again
+export const { GET, POST, OPTIONS } = createEditorApiHandler({
+  getPages,
+  blockTypes: SITE_BLOCK_TYPES
 })
 ```
 
+**Both handlers, every time.** The declaration is shared state, so setting it in
+one place looks sufficient and is not: a Next route module is evaluated on the
+first request *to that route*, and the editor asks `/api/editor/blocks` — served
+by `createEditorApiHandler` — before it has any reason to call the orchestrator.
+Declare it only on the orchestrator and the first manifest the editor sees is
+your types plus all eighteen built-ins. Verify with
+`curl -s localhost:3000/api/editor/blocks | jq '.blocks | length'`.
+
 The declaration is exclusive. The manifest narrows to it, the planner is only
 told about those types, and `add_block` refuses anything outside it with a
 message naming what the site does render. Nothing is removed from the registry,

package/dist/editor-api-blocks-catalogue.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/editor-api-blocks-catalogue.test.js

@@ -0,0 +1,73 @@
+/*
+ * `/api/editor/blocks` is the endpoint the editor actually reads, and it is
+ * served by a different route module than the orchestrator.
+ *
+ * `createOrchestrator({ blockTypes })` declares the catalogue too, and because
+ * the declaration lives on `globalThis` that looked like enough for both. It is
+ * not: a Next route module is evaluated on the first request *to that route*,
+ * so an editor that asks for the manifest before anything has touched
+ * `/api/avocado/*` is answered by a process where `createOrchestrator` has never
+ * run. What comes back is the site's own blocks plus all of Avocado's built-ins,
+ * which the site has no renderer for — and an agent reading that list will
+ * happily add a `Hero` that applies cleanly and draws nothing.
+ *
+ * These tests therefore never construct an orchestrator.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { z, registerBlock, declareBlockCatalogue } from "@avocadostudio-ai/shared";
+import { createEditorApiHandler } from "./editor-api-handler.js";
+registerBlock("site_ownHero", {
+    schema: z.object({ headline: z.string() }).catchall(z.unknown()),
+    meta: { displayName: "Own Hero", fields: { headline: { kind: "text" } } }
+});
+async function manifestTypes(config) {
+    const { GET } = createEditorApiHandler(config);
+    const res = await GET(new Request("http://site.test/api/editor/blocks"), {
+        params: Promise.resolve({ path: ["blocks"] })
+    });
+    assert.equal(res.status, 200);
+    const body = (await res.json());
+    return body.blocks.map((b) => b.type);
+}
+test("without blockTypes the manifest still offers Avocado's built-ins", async () => {
+    declareBlockCatalogue(null);
+    const types = await manifestTypes({ getPages: () => [] });
+    assert.ok(types.includes("site_ownHero"));
+    assert.ok(types.includes("Hero"), "the built-ins are registered transitively and nothing has narrowed them");
+});
+test("blockTypes narrows /api/editor/blocks with no orchestrator in the process", async () => {
+    declareBlockCatalogue(null);
+    const types = await manifestTypes({ getPages: () => [], blockTypes: ["site_ownHero"] });
+    assert.deepEqual(types, ["site_ownHero"]);
+});
+test("blockTypes composes with registerBlocks", async () => {
+    declareBlockCatalogue(null);
+    let registered = 0;
+    const types = await manifestTypes({
+        getPages: () => [],
+        blockTypes: ["site_lateBlock"],
+        registerBlocks: () => {
+            registered += 1;
+            registerBlock("site_lateBlock", {
+                schema: z.object({ title: z.string() }).catchall(z.unknown()),
+                meta: { displayName: "Late Block", fields: { title: { kind: "text" } } }
+            });
+        }
+    });
+    assert.equal(registered, 1);
+    assert.deepEqual(types, ["site_lateBlock"]);
+});
+test("the declaration is re-made per request, so another copy cannot lift it", async () => {
+    declareBlockCatalogue(null);
+    const { GET } = createEditorApiHandler({ getPages: () => [], blockTypes: ["site_ownHero"] });
+    const ask = async () => {
+        const res = await GET(new Request("http://site.test/api/editor/blocks"), {
+            params: Promise.resolve({ path: ["blocks"] })
+        });
+        return (await res.json()).blocks.map((b) => b.type);
+    };
+    assert.deepEqual(await ask(), ["site_ownHero"]);
+    declareBlockCatalogue(null); // as if another module had lifted it
+    assert.deepEqual(await ask(), ["site_ownHero"]);
+});

package/dist/editor-api-handler.d.ts

@@ -1,7 +1,7 @@
 import type { OnPublishFn } from "./editor-routes.ts";
 import { type BlockManifest } from "./editor-manifest.ts";
 import type { PageDoc } from "./types.ts";
-import type { SiteConfig } from "@avocadostudio-ai/shared";
+import { type SiteConfig } from "@avocadostudio-ai/shared";
 export interface EditorApiHandlerConfig {
     getPages: () => PageDoc[] | Promise<PageDoc[]>;
     /**
@@ -24,6 +24,24 @@ export interface EditorApiHandlerConfig {
      * first, then `getManifest` is invoked.
      */
     registerBlocks?: () => void;
+    /**
+     * The block types this site renders, narrowing `/api/editor/blocks` to them.
+     *
+     * `createOrchestrator` takes the same option and declares the same catalogue,
+     * and for a while that was assumed to be enough for both routes: the
+     * declaration lives on `globalThis`, so one handler's call is visible to the
+     * other. What that reasoning missed is *when* it runs. A Next route module is
+     * evaluated on the first request to that route, so a site whose editor asks
+     * for `/api/editor/blocks` before anything has touched `/api/avocado/*` gets
+     * the manifest built before `createOrchestrator` has ever been called — and
+     * the answer is the site's own blocks plus all of Avocado's built-ins, which
+     * the site has no renderer for.
+     *
+     * Declaring it here closes that window, and passing it to both handlers is
+     * harmless: the declaration records names and the manifest is rebuilt per
+     * request.
+     */
+    blockTypes?: readonly string[];
     onPublish?: OnPublishFn;
     /** Secret token required for publish requests. Checked against x-publish-token header. */
     publishSecret?: string;

package/dist/editor-api-handler.js

@@ -3,6 +3,7 @@ import { createBlocksHandler, createPagesHandler, createPublishHandler } from ".
 import { applyEditorCors } from "./editor-cors.js";
 import { checkIntegrationOnce } from "./integration-check.js";
 import { buildBlockManifest } from "./editor-manifest.js";
+import { declareBlockCatalogue } from "@avocadostudio-ai/shared";
 /**
  * Creates a single catch-all route handler that serves all editor API endpoints.
  *
@@ -24,9 +25,12 @@ import { buildBlockManifest } from "./editor-manifest.js";
 export function createEditorApiHandler(config) {
     const draftEnable = createDraftEnableHandler();
     const draftDisable = createDraftDisableHandler();
-    const manifestBuilder = config.registerBlocks
+    const needsPreamble = Boolean(config.registerBlocks || config.blockTypes);
+    const manifestBuilder = needsPreamble
         ? () => {
-            config.registerBlocks();
+            config.registerBlocks?.();
+            if (config.blockTypes)
+                declareBlockCatalogue(config.blockTypes);
             return (config.getManifest ?? buildBlockManifest)();
         }
         : config.getManifest;

package/dist/publish/field-diff.js

@@ -83,7 +83,17 @@ export function diffFields(args) {
     const reject = (where) => (change, remedy) => unsupported.push({ where, change, ...(remedy ? { remedy } : {}) });
     for (const [name, spec] of Object.entries(args.specs)) {
         const field = spec.cmsKey ?? name;
-        const before = args.source?.[name];
+        /*
+         * Both of these read the CMS key, not the props key. They used to disagree:
+         * the baseline came from `source[name]` while the patch path was built from
+         * `cmsKey ?? name`. A spec that actually used `cmsKey` therefore compared
+         * against `undefined`, never matched, and emitted a patch on every publish
+         * whether or not anything had been edited — the precise overwrite this
+         * module exists to prevent. Worse, `rehydrate` was handed that `undefined`
+         * as the stored value, so a partial inversion had nothing to merge into and
+         * dropped everything the projection had not carried.
+         */
+        const before = args.source?.[field];
         const after = spec.rehydrate(args.props, before, args.ctx);
         if (deepEqual(before, after))
             continue;

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

@@ -39,13 +39,66 @@ test("cmsKey writes to the field the CMS actually has", () => {
     const diff = diffFields({
         specs: { heading: { ...plain("heading"), cmsKey: "headingOverride" } },
         props: { heading: "After" },
-        source: { heading: "Before" },
+        // Keyed the way the CMS keys it. The version of this test that wrote
+        // `{ heading: "Before" }` passed against the bug below, because a baseline
+        // of `undefined` also produces a patch at the right path.
+        source: { headingOverride: "Before" },
+        ctx,
+        documentId: "doc1",
+        where: "/ → hero",
+        paths: sanityPaths
+    });
+    assert.deepEqual(diff.patches, [
+        { documentId: "doc1", path: "headingOverride", value: "After" }
+    ]);
+});
+test("an unchanged cmsKey field emits nothing", () => {
+    // The regression this file exists for. `diffFields` read the baseline from
+    // the *props* key while pathing the patch from `cmsKey`, so every spec that
+    // used the option compared its value against `undefined` and republished it
+    // on every publish, edited or not.
+    const diff = diffFields({
+        specs: { heading: { ...plain("heading"), cmsKey: "headingOverride" } },
+        props: { heading: "Same" },
+        source: { headingOverride: "Same" },
         ctx,
         documentId: "doc1",
         where: "/ → hero",
         paths: sanityPaths
     });
-    assert.equal(diff.patches[0].path, "headingOverride");
+    assert.deepEqual(diff.patches, []);
+});
+test("a cmsKey spec's rehydrate receives the value the CMS holds", () => {
+    // Partial inversion is the whole point of passing `before`: return the stored
+    // object with one key replaced and everything the projection dropped
+    // survives. Hand `rehydrate` an `undefined` and it has nothing to merge into,
+    // so the patch overwrites instead of editing.
+    const seen = [];
+    const diff = diffFields({
+        specs: {
+            alt: {
+                cmsKey: "image",
+                rehydrate: (props, before) => {
+                    seen.push(before);
+                    return { ...before, alt: props.alt };
+                }
+            }
+        },
+        props: { alt: "A team in action" },
+        source: { image: { _type: "image", asset: { _ref: "image-abc" }, alt: "Old" } },
+        ctx,
+        documentId: "doc1",
+        where: "/ → hero",
+        paths: sanityPaths
+    });
+    assert.deepEqual(seen, [{ _type: "image", asset: { _ref: "image-abc" }, alt: "Old" }]);
+    assert.deepEqual(diff.patches, [
+        {
+            documentId: "doc1",
+            path: "image",
+            value: { _type: "image", asset: { _ref: "image-abc" }, alt: "A team in action" }
+        }
+    ]);
 });
 test("rehydrate receives the stored value, so an inversion can be partial", () => {
     // The whole reason a snapshot contract cannot work: the editor saw
@@ -241,7 +294,7 @@ test("one block can write to two documents", () => {
                 documentId: "page-1",
                 prefix: 'pageBuilder[_key=="b1"].',
                 specs: { heading: { ...plain("heading"), cmsKey: "headingOverride" } },
-                source: { heading: "Old page heading" }
+                source: { headingOverride: "Old page heading" }
             },
             {
                 documentId: "section-9",

package/package.json

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