@avocadostudio-ai/site-sdk 0.2.1 → 0.2.3

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,84 @@ 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: [] }
+  },
+
+  /** Static, because /whoami must answer it with the CMS unreachable. */
+  capabilities: { createPage: 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`.
+
 ## Library mode needs a credential
 
 `createOrchestrator()` mounts on your own domain and can edit and publish your
@@ -220,11 +377,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,
@@ -281,6 +438,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 +548,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/site-sdk",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "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/blocks": "0.2.3",
+    "@avocadostudio-ai/shared": "0.2.3",
+    "@avocadostudio-ai/preview-adapter": "0.2.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.2.1"
+    "@avocadostudio-ai/orchestrator-core": "^0.2.3"
   },
   "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": {