@avocadostudio-ai/site-sdk 0.3.2 → 0.4.0

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/editor.d.ts

@@ -1,3 +1,4 @@
+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): {
@@ -13,6 +14,57 @@ export declare function getPreviewWrapperProps(editorMode: boolean, blockId: str
         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 { renderBlocks } from "./render-blocks.tsx";
 export { RenderedBlocks, PreviewBlock } from "./live-preview-blocks.tsx";
 export { LivePreviewProvider } from "@avocadostudio-ai/preview-adapter";

package/dist/editor.js

@@ -13,6 +13,54 @@ export function getPreviewWrapperProps(editorMode, blockId, blockType) {
         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.
+ */
+export function editableProps(path, options) {
+    return {
+        "data-editable-target": path,
+        "data-editable-target-label": options?.label ?? path,
+        ...(options?.kind ? { "data-editable-kind": options.kind } : {})
+    };
+}
 // Block rendering helper
 export { renderBlocks } from "./render-blocks.js";
 // Live-preview store renderer (streams field drafts through React)

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/dist/server/orchestrator.d.ts

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

package/dist/server/orchestrator.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/site-sdk",
-  "version": "0.3.2",
+  "version": "0.4.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.3.2",
-    "@avocadostudio-ai/preview-adapter": "^0.3.2",
-    "@avocadostudio-ai/shared": "^0.3.2"
+    "@avocadostudio-ai/blocks": "^0.4.0",
+    "@avocadostudio-ai/preview-adapter": "^0.4.0",
+    "@avocadostudio-ai/shared": "^0.4.0"
   },
   "peerDependencies": {
     "next": ">=15.0.0",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
     "better-sqlite3": ">=12.0.0",
-    "@avocadostudio-ai/orchestrator-core": "^0.3.2"
+    "@avocadostudio-ai/orchestrator-core": "^0.4.0"
   },
   "peerDependenciesMeta": {
     "@avocadostudio-ai/orchestrator-core": {