@avocadostudio-ai/site-sdk 0.2.0 → 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/dist/cli/register.js

@@ -67,6 +67,10 @@ function parseArgs(argv) {
             case "--preview-url":
                 out.previewUrl = next();
                 break;
+            case "--token":
+            case "--access-token":
+                out.token = next();
+                break;
             case "-h":
             case "--help":
                 out.help = true;
@@ -98,6 +102,9 @@ OPTIONAL
   --session <string>        Orchestrator session (default: dev)
   --purpose <string>        One-line site description for AI context
   --preview-url <url>       Preview URL (default: http://localhost:<port>)
+  --token <string>          Orchestrator access token (default: $ORCHESTRATOR_ACCESS_TOKEN).
+                            Required by any orchestrator that is credentialed —
+                            which a library-mode mount must be in production.
   --cwd <path>              Project directory (default: current working directory)
   -h, --help                Show this help
 
@@ -218,6 +225,13 @@ async function main() {
     const port = args.port ?? detectPortFromPackageJson(pkg) ?? 3000;
     // Resolve orchestrator URL
     const orchestrator = (args.orchestrator ?? process.env.ORCHESTRATOR_URL ?? "http://localhost:4200").replace(/\/+$/, "");
+    /*
+     * A credentialed orchestrator refuses `/sites/register` like any other route,
+     * and this CLI had no way to present a token — so the documented path for
+     * "wire up your site with your own coding agent" ended at a 401 for exactly
+     * the deployments the docs insist on securing.
+     */
+    const accessToken = (args.token ?? process.env.ORCHESTRATOR_ACCESS_TOKEN ?? "").trim();
     // Resolve / generate the draft secret
     const envPath = join(cwd, ".env.local");
     const existingEnv = existsSync(envPath) ? parseEnvFile(readFileSync(envPath, "utf-8")) : {};
@@ -246,7 +260,10 @@ async function main() {
     try {
         response = await fetch(`${orchestrator}/sites/register`, {
             method: "POST",
-            headers: { "content-type": "application/json" },
+            headers: {
+                "content-type": "application/json",
+                ...(accessToken ? { "x-access-token": accessToken } : {}),
+            },
             body: JSON.stringify({
                 siteId,
                 name,
@@ -272,6 +289,11 @@ async function main() {
     if (!response.ok) {
         const text = await response.text();
         process.stderr.write(`\nOrchestrator responded ${response.status}:\n  ${text}\n`);
+        if (response.status === 401 || response.status === 403) {
+            process.stderr.write(accessToken
+                ? `\nA token was sent and rejected. Check it matches ORCHESTRATOR_ACCESS_TOKEN\non the orchestrator, or the password behind ACCESS_PASSWORD_HASH.\n`
+                : `\nThis orchestrator is credentialed and no token was sent.\nPass --token <value>, or set ORCHESTRATOR_ACCESS_TOKEN.\n`);
+        }
         process.exit(1);
     }
     const result = (await response.json());

package/dist/draft-fetch.d.ts

@@ -1,14 +1,13 @@
 import type { PageDoc, SiteConfig } from "@avocadostudio-ai/shared";
 export declare function getOrchestratorUrl(): string | null;
-export declare function fetchEditorPage(slug: string, session: string, siteId: string, options?: {
+type DraftFetchOptions = {
     timeoutMs?: number;
     orchestratorUrl?: string;
-}): Promise<PageDoc | null>;
-export declare function fetchEditorSlugs(session: string, siteId: string, options?: {
-    timeoutMs?: number;
-    orchestratorUrl?: string;
-}): Promise<string[]>;
-export declare function fetchEditorSiteConfig(session: string, siteId: string, options?: {
-    timeoutMs?: number;
-    orchestratorUrl?: string;
-}): Promise<SiteConfig>;
+    accessToken?: string;
+};
+/** For tests: forget which refusals have already been reported. */
+export declare function resetDraftFetchWarnings(): void;
+export declare function fetchEditorPage(slug: string, session: string, siteId: string, options?: DraftFetchOptions): Promise<PageDoc | null>;
+export declare function fetchEditorSlugs(session: string, siteId: string, options?: DraftFetchOptions): Promise<string[]>;
+export declare function fetchEditorSiteConfig(session: string, siteId: string, options?: DraftFetchOptions): Promise<SiteConfig>;
+export {};

package/dist/draft-fetch.js

@@ -7,6 +7,25 @@ export function getOrchestratorUrl() {
         return "http://127.0.0.1:4200";
     return null;
 }
+/**
+ * The credential these reads present, if there is one.
+ *
+ * A library-mode orchestrator *must* be credentialed in production —
+ * `createOrchestrator` refuses every request under `NODE_ENV=production` with
+ * neither `ORCHESTRATOR_ACCESS_TOKEN` nor `ACCESS_PASSWORD_HASH` set. Until
+ * this existed, these three helpers sent no headers at all, so a site could not
+ * read its own drafts through the SDK its own docs told it to use.
+ *
+ * Read from the environment rather than passed in because the caller is a
+ * server component that has no session of its own. `ORCHESTRATOR_ACCESS_TOKEN`
+ * has no `NEXT_PUBLIC_` prefix, so it is `undefined` in a client bundle: if one
+ * of these ever gets pulled clientward the request degrades to no header
+ * instead of shipping the token to a browser.
+ */
+function resolveAccessToken(explicit) {
+    const token = explicit?.trim() || process.env.ORCHESTRATOR_ACCESS_TOKEN?.trim();
+    return token || undefined;
+}
 function buildCandidateBaseUrls(configuredBaseUrl) {
     const candidates = [configuredBaseUrl];
     try {
@@ -25,27 +44,64 @@ function buildCandidateBaseUrls(configuredBaseUrl) {
     }
     return candidates;
 }
-async function fetchWithTimeout(url, timeoutMs) {
+async function fetchWithTimeout(url, timeoutMs, token) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
     try {
-        const response = await fetch(url, { cache: "no-store", signal: controller.signal });
+        const response = await fetch(url, {
+            cache: "no-store",
+            signal: controller.signal,
+            ...(token ? { headers: { "x-access-token": token } } : {})
+        });
         return response;
     }
     finally {
         clearTimeout(timeoutId);
     }
 }
+/**
+ * A refusal is not an absence, and the difference is the whole bug.
+ *
+ * These helpers run per page render, so a 401 that fell through to `return
+ * null` produced a preview showing *published* content — no error, no log line,
+ * and a page that looks right. It is the hardest failure in the stack to see.
+ *
+ * Retrying the next candidate base URL cannot help either: the same missing
+ * credential will be missing there too. So a refusal stops the loop and says so
+ * once, rather than being spent on latency and silence.
+ */
+const REFUSAL_STATUSES = new Set([401, 403]);
+const warned = new Set();
+function warnRefused(fn, status, hadToken) {
+    const key = `${fn}:${status}:${hadToken}`;
+    if (warned.has(key))
+        return;
+    warned.add(key);
+    console.warn(`[site-sdk/draft] ${fn}: the orchestrator answered ${status}. ` +
+        (hadToken
+            ? "The token that was sent is not the one it accepts — check ORCHESTRATOR_ACCESS_TOKEN on both sides."
+            : "No credential was sent. Set ORCHESTRATOR_ACCESS_TOKEN, or pass `accessToken`.") +
+        " Drafts are unavailable, so this page is rendering published content.");
+}
+/** For tests: forget which refusals have already been reported. */
+export function resetDraftFetchWarnings() {
+    warned.clear();
+}
 export async function fetchEditorPage(slug, session, siteId, options) {
     const configuredBaseUrl = options?.orchestratorUrl ?? getOrchestratorUrl();
     if (!configuredBaseUrl)
         return null;
     const timeout = options?.timeoutMs ?? 5000;
+    const token = resolveAccessToken(options?.accessToken);
     const baseUrls = buildCandidateBaseUrls(configuredBaseUrl);
     for (const baseUrl of baseUrls) {
         try {
             const url = `${baseUrl}/draft/pages?session=${encodeURIComponent(session)}&siteId=${encodeURIComponent(siteId)}&slug=${encodeURIComponent(slug)}`;
-            const res = await fetchWithTimeout(url, timeout);
+            const res = await fetchWithTimeout(url, timeout, token);
+            if (REFUSAL_STATUSES.has(res.status)) {
+                warnRefused("fetchEditorPage", res.status, Boolean(token));
+                return null;
+            }
             if (!res.ok)
                 continue;
             const payload = (await res.json());
@@ -70,11 +126,16 @@ export async function fetchEditorSlugs(session, siteId, options) {
     if (!configuredBaseUrl)
         return [];
     const timeout = options?.timeoutMs ?? 5000;
+    const token = resolveAccessToken(options?.accessToken);
     const baseUrls = buildCandidateBaseUrls(configuredBaseUrl);
     for (const baseUrl of baseUrls) {
         try {
             const url = `${baseUrl}/draft/slugs?session=${encodeURIComponent(session)}&siteId=${encodeURIComponent(siteId)}`;
-            const res = await fetchWithTimeout(url, timeout);
+            const res = await fetchWithTimeout(url, timeout, token);
+            if (REFUSAL_STATUSES.has(res.status)) {
+                warnRefused("fetchEditorSlugs", res.status, Boolean(token));
+                return [];
+            }
             if (!res.ok)
                 continue;
             const payload = (await res.json());
@@ -95,11 +156,16 @@ export async function fetchEditorSiteConfig(session, siteId, options) {
     if (!configuredBaseUrl)
         return {};
     const timeout = options?.timeoutMs ?? 5000;
+    const token = resolveAccessToken(options?.accessToken);
     const baseUrls = buildCandidateBaseUrls(configuredBaseUrl);
     for (const baseUrl of baseUrls) {
         try {
             const url = `${baseUrl}/draft/site-config?session=${encodeURIComponent(session)}&siteId=${encodeURIComponent(siteId)}`;
-            const res = await fetchWithTimeout(url, timeout);
+            const res = await fetchWithTimeout(url, timeout, token);
+            if (REFUSAL_STATUSES.has(res.status)) {
+                warnRefused("fetchEditorSiteConfig", res.status, Boolean(token));
+                return {};
+            }
             if (!res.ok)
                 continue;
             const payload = (await res.json());

package/dist/draft-fetch.test.d.ts

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

package/dist/draft-fetch.test.js

@@ -0,0 +1,87 @@
+import { test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { fetchEditorPage, fetchEditorSlugs, resetDraftFetchWarnings } from "./draft-fetch.js";
+let calls = [];
+let warnings = [];
+const realFetch = globalThis.fetch;
+const realWarn = console.warn;
+/** Answer every request with `status`, recording what was asked and with what. */
+function stubFetch(status, body = {}) {
+    globalThis.fetch = (async (input, init) => {
+        const headers = new Headers(init?.headers ?? {});
+        calls.push({ url: String(input), token: headers.get("x-access-token") });
+        return new Response(JSON.stringify(body), {
+            status,
+            headers: { "content-type": "application/json" }
+        });
+    });
+}
+beforeEach(() => {
+    calls = [];
+    warnings = [];
+    resetDraftFetchWarnings();
+    console.warn = (msg) => { warnings.push(String(msg)); };
+    delete process.env.ORCHESTRATOR_ACCESS_TOKEN;
+});
+afterEach(() => {
+    globalThis.fetch = realFetch;
+    console.warn = realWarn;
+    delete process.env.ORCHESTRATOR_ACCESS_TOKEN;
+});
+test("the configured access token travels with the request", async () => {
+    process.env.ORCHESTRATOR_ACCESS_TOKEN = "s3cret";
+    stubFetch(404);
+    await fetchEditorPage("/about", "dev", "site", { orchestratorUrl: "http://example.test" });
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0].token, "s3cret");
+});
+test("an explicit token beats the environment", async () => {
+    process.env.ORCHESTRATOR_ACCESS_TOKEN = "from-env";
+    stubFetch(404);
+    await fetchEditorPage("/about", "dev", "site", {
+        orchestratorUrl: "http://example.test",
+        accessToken: "explicit"
+    });
+    assert.equal(calls[0].token, "explicit");
+});
+test("no credential configured sends no header, rather than an empty one", async () => {
+    stubFetch(404);
+    await fetchEditorPage("/about", "dev", "site", { orchestratorUrl: "http://example.test" });
+    assert.equal(calls[0].token, null);
+});
+test("a refusal stops the walk instead of retrying the same missing credential", async () => {
+    // `localhost` yields a second candidate (127.0.0.1); a 404 tries it, a 401
+    // must not — the credential that was missing is missing there too.
+    stubFetch(401, { error: "unauthorized" });
+    const page = await fetchEditorPage("/about", "dev", "site", {
+        orchestratorUrl: "http://localhost:4200"
+    });
+    assert.equal(page, null);
+    assert.equal(calls.length, 1, "a 401 must not be spent on the next candidate URL");
+});
+test("a refusal is reported, because otherwise the page just looks right", async () => {
+    stubFetch(401, { error: "unauthorized" });
+    await fetchEditorPage("/about", "dev", "site", { orchestratorUrl: "http://example.test" });
+    assert.equal(warnings.length, 1);
+    assert.match(warnings[0], /401/);
+    assert.match(warnings[0], /ORCHESTRATOR_ACCESS_TOKEN/);
+    assert.match(warnings[0], /published content/);
+});
+test("the same refusal is not reported once per rendered page", async () => {
+    stubFetch(401);
+    await fetchEditorPage("/a", "dev", "site", { orchestratorUrl: "http://example.test" });
+    await fetchEditorPage("/b", "dev", "site", { orchestratorUrl: "http://example.test" });
+    assert.equal(warnings.length, 1);
+});
+test("a 404 still falls through to the other candidate host", async () => {
+    stubFetch(404);
+    await fetchEditorPage("/about", "dev", "site", { orchestratorUrl: "http://localhost:4200" });
+    assert.equal(calls.length, 2, "the localhost/127.0.0.1 fallback must survive this change");
+});
+test("fetchEditorSlugs refuses the same way, and returns an empty list", async () => {
+    stubFetch(401);
+    const slugs = await fetchEditorSlugs("dev", "site", { orchestratorUrl: "http://localhost:4200" });
+    assert.deepEqual(slugs, []);
+    assert.equal(calls.length, 1);
+    assert.match(warnings[0], /fetchEditorSlugs/);
+});

package/dist/next-config.test.js

@@ -27,10 +27,41 @@ test("a package whose entry point is TypeScript needs transpiling", () => {
     assert.deepEqual(linkedAvocadoPackages(root), ["@avocadostudio-ai/shared"]);
 });
 test("a package installed from a registry does not", () => {
-    // Published, `main` points at built JavaScript — listing it would be noise.
-    const root = fixture({ "@avocadostudio-ai/shared": { main: "dist/index.js" } });
+    /*
+     * The shape every `@avocadostudio-ai` package actually has on npm, and the
+     * `types` field is the whole point of the fixture: `dist/index.d.ts` ends in
+     * `.ts`, so a naive TypeScript test matches it and transpiles the published
+     * package — which drags `orchestrator-core` into the bundle and fails the
+     * build on an optional peer.
+     *
+     * This test existed before that was found, with a fixture carrying `main`
+     * alone. It passed, on a package shape that does not occur on a registry.
+     */
+    const root = fixture({
+        "@avocadostudio-ai/shared": { main: "dist/index.js", types: "dist/index.d.ts" }
+    });
     assert.deepEqual(linkedAvocadoPackages(root), []);
 });
+test("a declaration file in an exports map is not a reason to transpile either", () => {
+    // The same trap one level down: an `exports` map carries its own `types`.
+    const root = fixture({
+        "@avocadostudio-ai/richtext": {
+            main: "dist/index.js",
+            exports: {
+                ".": { types: "./dist/index.d.ts", import: "./dist/index.js" },
+                "./package.json": "./package.json"
+            }
+        }
+    });
+    assert.deepEqual(linkedAvocadoPackages(root), []);
+});
+test("a linked package is still caught when its types point at source", () => {
+    // A workspace checkout points both fields at `src/`; that must still count.
+    const root = fixture({
+        "@avocadostudio-ai/shared": { main: "src/index.ts", types: "src/index.ts" }
+    });
+    assert.deepEqual(linkedAvocadoPackages(root), ["@avocadostudio-ai/shared"]);
+});
 test("a TypeScript entry hidden in an exports map still counts", () => {
     const root = fixture({
         "@avocadostudio-ai/blocks": {
@@ -239,6 +270,27 @@ test("serverExternals: false leaves both halves to the app", () => {
     const config = withAvocado({}, { cwd: EMPTY_DIR, serverExternals: false, env: NO_ENV });
     assert.equal(config.serverExternalPackages, undefined);
     assert.equal(config.webpack, undefined, "no hook is attached at all");
+    assert.equal(config.turbopack, undefined, "and nothing is declared on its behalf");
+});
+/*
+ * On Next 16 Turbopack is the default, and a config with a `webpack` key and no
+ * `turbopack` key fails the build outright — measured, on 16.3.4, against a
+ * project that installed the SDK from a tarball:
+ *
+ *   ERROR: This build is using Turbopack, with a `webpack` config and no
+ *   `turbopack` config.
+ *
+ * Since the hook above is attached whether or not the app asked for one, the
+ * empty Turbopack config has to travel with it.
+ */
+test("attaching a webpack hook also declares the turbopack config Next 16 demands", () => {
+    const config = withAvocado({}, { cwd: EMPTY_DIR, env: NO_ENV });
+    assert.equal(typeof config.webpack, "function", "the hook is still attached");
+    assert.deepEqual(config.turbopack, {}, "an empty turbopack config must travel with it");
+});
+test("an app's own turbopack config is never overwritten", () => {
+    const config = withAvocado({ turbopack: { resolveAlias: { underscore: "lodash" } } }, { cwd: EMPTY_DIR, env: NO_ENV });
+    assert.deepEqual(config.turbopack, { resolveAlias: { underscore: "lodash" } });
 });
 test("externals are applied even when there is nothing to transpile", () => {
     // The transpile derivation returns early twice — on a config that already
@@ -247,7 +299,57 @@ test("externals are applied even when there is nothing to transpile", () => {
     const config = withAvocado({}, { cwd: "/nonexistent-path-for-this-test", env: NO_ENV });
     assert.ok(config.serverExternalPackages.includes("better-sqlite3"));
 });
+/*
+ * Naming orchestrator-core's *dependencies* external does not stop Turbopack
+ * walking into orchestrator-core and resolving its `await import("googleapis")`
+ * statically. Measured on Next 16.3.4 against a real tarball install: the build
+ * fails on an optional peer the project never installed, with every provider
+ * SDK already in `serverExternalPackages`. Externalising the package itself is
+ * the fix, and it is only correct when the package arrived built.
+ */
+test("a registry-installed orchestrator-core is externalised, not walked", () => {
+    const root = fixture({
+        "@avocadostudio-ai/orchestrator-core": { main: "dist/index.js", types: "dist/index.d.ts" }
+    });
+    const config = withAvocado({}, { cwd: root, env: NO_ENV });
+    assert.ok(config.serverExternalPackages.includes("@avocadostudio-ai/orchestrator-core"), "a built orchestrator-core must be external, or Turbopack resolves its optional peers");
+});
+test("a linked orchestrator-core is transpiled instead, never externalised", () => {
+    // Externalising a package whose `main` is `src/index.ts` hands Node a
+    // TypeScript file to require — a build error traded for a runtime crash.
+    const root = fixture({ "@avocadostudio-ai/orchestrator-core": { main: "src/index.ts" } });
+    const config = withAvocado({}, { cwd: root, env: NO_ENV });
+    assert.deepEqual(config.transpilePackages, ["@avocadostudio-ai/orchestrator-core"]);
+    assert.equal(config.serverExternalPackages.includes("@avocadostudio-ai/orchestrator-core"), false, "a linked checkout must be compiled with the app, not handed to Node raw");
+});
 test("the exported list is what the helper actually applies", () => {
     const config = withAvocado({}, { cwd: EMPTY_DIR, env: NO_ENV });
     assert.deepEqual(config.serverExternalPackages, AVOCADO_SERVER_EXTERNALS);
 });
+/*
+ * `trailingSlash: true` is the setting that made the editor unreachable. Next
+ * applies its 308 to `/api/*` too, and a browser will not follow a redirect on
+ * a CORS preflight, so every editor API call failed before it was sent — with
+ * no error naming the config line responsible.
+ */
+test("a trailing-slash site stops redirecting, or the editor cannot reach it", () => {
+    const root = fixture({});
+    const config = withAvocado({ trailingSlash: true }, { cwd: root, silent: true });
+    assert.equal(config.skipTrailingSlashRedirect, true);
+    assert.equal(config.trailingSlash, true, "the app's own setting is not touched — only the redirect is");
+});
+test("a site without trailing slashes is left exactly as it was", () => {
+    const root = fixture({});
+    const config = withAvocado({}, { cwd: root, silent: true });
+    assert.equal(config.skipTrailingSlashRedirect, undefined, "the vast majority of sites never hit this, and must not inherit the workaround");
+});
+test("an app that already decided about the redirect keeps its decision", () => {
+    const root = fixture({});
+    const kept = withAvocado({ trailingSlash: true, skipTrailingSlashRedirect: false }, { cwd: root, silent: true });
+    assert.equal(kept.skipTrailingSlashRedirect, false, "a site that stated this has thought about it harder than a helper can");
+});
+test("trailingSlash: false leaves the whole thing to the app", () => {
+    const root = fixture({});
+    const config = withAvocado({ trailingSlash: true }, { cwd: root, silent: true, trailingSlash: false });
+    assert.equal(config.skipTrailingSlashRedirect, undefined);
+});

package/dist/proxy.d.ts

@@ -15,10 +15,47 @@ export type EditorProxyOptions = {
      */
     editorParam?: string;
     /**
-     * Name of the Next.js draft-mode bypass cookie.
+     * Name of the Next.js draft-mode bypass cookie, or `false` to ignore cookies
+     * entirely and key the rewrite on {@link EditorProxyOptions.editorParam} alone.
+     *
+     * The cookie is how navigation *inside* the editor iframe stays in draft mode:
+     * a link click carries no `__editor=1`, so without it the second page a user
+     * visits renders published content.
+     *
+     * But the cookie is Next's own, and it is not Avocado's to claim. Any other
+     * feature that calls `draftMode().enable()` sets the same
+     * `__prerender_bypass` — Sanity's Presentation tool and Contentful's live
+     * preview both do — and every one of *their* preview requests then lands on
+     * Avocado's preview route. On a site that already had Draft Mode before it had
+     * Avocado, pass `draftCookie: false` and the two stop fighting over it.
+     *
      * @default "__prerender_bypass"
      */
-    draftCookie?: string;
+    draftCookie?: string | false;
+    /**
+     * Set this to `true` on a site whose `next.config` sets `trailingSlash: true`.
+     *
+     * Such a site cannot talk to the editor until it *stops* letting Next issue
+     * the trailing-slash redirect. Next applies that 308 to `/api/*` as well, so
+     * `/api/editor/blocks` answers `308 → /api/editor/blocks/` — and while `fetch`
+     * follows a 308, a browser does **not** follow a redirect on a CORS preflight.
+     * The editor calls those routes from its own origin, so every editor API call
+     * fails before the request is made. A middleware rewrite cannot repair it
+     * either: Next's trailing-slash redirect runs *before* middleware.
+     *
+     * The fix is `skipTrailingSlashRedirect: true` — which `withAvocado` sets for
+     * you as soon as it sees `trailingSlash: true` — plus re-issuing the redirect
+     * by hand for everything that is not an API route. This flag is that second
+     * half, and the two must be turned on together: the config half alone stops a
+     * site redirecting to its canonical URLs.
+     *
+     * Only page paths are affected. The proxy's matcher already excludes `/api`,
+     * `_next` and anything with a file extension, which is exactly the set that
+     * should never have gained a trailing slash to begin with.
+     *
+     * @default false
+     */
+    trailingSlash?: boolean;
 };
 /**
  * Create a Next.js proxy function that rewrites editor/draft requests

package/dist/proxy.js

@@ -34,10 +34,36 @@ export { DEFAULT_PREVIEW_ROUTE, buildEditorMatcher } from "./editor-matcher.js";
 export function createEditorProxy(options) {
     const previewRoute = options?.previewRoute ?? DEFAULT_PREVIEW_ROUTE;
     const editorParam = options?.editorParam ?? "__editor";
-    const draftCookie = options?.draftCookie ?? "__prerender_bypass";
+    const draftCookie = options?.draftCookie === undefined ? "__prerender_bypass" : options.draftCookie;
+    const trailingSlash = options?.trailingSlash ?? false;
     function proxy(request) {
+        /*
+         * Before anything else, and deliberately: this stands in for a redirect
+         * Next would have issued before middleware ran, so a request that should
+         * never have been served at this URL must not be served at it here either.
+         * Rewriting first would answer `/about?__editor=1` with content the site
+         * publishes only at `/about/`.
+         */
+        if (trailingSlash) {
+            /*
+             * Built from `request.url`, not from `request.nextUrl.clone()`. NextURL
+             * normalises a trailing slash back *off* when it stringifies, so a
+             * redirect built from a clone points at the URL it is trying to leave —
+             * a redirect loop, and one that only a browser would ever have shown us.
+             * A plain URL does no normalising. It also keeps `basePath`, which
+             * `nextUrl.pathname` has already stripped.
+             */
+            const url = new URL(request.url);
+            if (url.pathname.length > 1 && !url.pathname.endsWith("/")) {
+                url.pathname = `${url.pathname}/`;
+                // 308, not 307: the method is preserved *and* the redirect is
+                // permanent, which is what Next's own trailing-slash redirect sends
+                // and what the site's existing search rankings were built on.
+                return NextResponse.redirect(url, 308);
+            }
+        }
         const isEditor = request.nextUrl.searchParams.get(editorParam) === "1";
-        const hasDraftCookie = request.cookies.has(draftCookie);
+        const hasDraftCookie = draftCookie !== false && request.cookies.has(draftCookie);
         if (isEditor || hasDraftCookie) {
             const url = request.nextUrl.clone();
             url.pathname = `${previewRoute}${url.pathname}`;

package/dist/proxy.test.js

@@ -70,3 +70,54 @@ test("the deprecated middleware entry point is the same rewrite under the old na
 test("DEFAULT_PREVIEW_ROUTE is what the factory actually defaults to", () => {
     assert.equal(rewriteOf(createEditorProxy().proxy(request("https://site.test/a?__editor=1"))), `https://site.test${DEFAULT_PREVIEW_ROUTE}/a?__editor=1`);
 });
+/*
+ * `trailingSlash: true` and the editor could not coexist. Next applies its 308
+ * to `/api/*` too, and a browser will not follow a redirect on a CORS preflight,
+ * so every editor API call failed before it was sent. `withAvocado` turns the
+ * redirect off; these pin the half that puts it back.
+ */
+const locationOf = (response) => response.headers.get("location");
+test("a trailing-slash site gets back the redirect the config turned off", () => {
+    const { proxy } = createEditorProxy({ trailingSlash: true });
+    const response = proxy(request("https://site.test/about"));
+    assert.equal(response.status, 308, "308, like Next's own — the site's rankings were built on a permanent redirect");
+    assert.equal(locationOf(response), "https://site.test/about/");
+});
+test("the redirect keeps the query string, or the editor loses its own parameter", () => {
+    const { proxy } = createEditorProxy({ trailingSlash: true });
+    assert.equal(locationOf(proxy(request("https://site.test/about?__editor=1"))), "https://site.test/about/?__editor=1");
+});
+test("an already-canonical path is rewritten, not redirected into a loop", () => {
+    const { proxy } = createEditorProxy({ trailingSlash: true });
+    const response = proxy(request("https://site.test/about/?__editor=1"));
+    assert.equal(response.status, 200);
+    assert.equal(rewriteOf(response), "https://site.test/preview-draft/about/?__editor=1");
+});
+test("the root is already canonical — redirecting it would never terminate", () => {
+    const { proxy } = createEditorProxy({ trailingSlash: true });
+    const response = proxy(request("https://site.test/?__editor=1"));
+    assert.equal(response.status, 200, "`/` already ends in a slash; redirecting it is a loop");
+    // Asserted as a prefix: the rewrite target goes through NextURL, which
+    // normalises the trailing slash according to the app's own config.
+    assert.match(rewriteOf(response) ?? "", /^https:\/\/site\.test\/preview-draft/);
+});
+test("the redirect comes before the rewrite, so no page is served at a URL the site does not publish", () => {
+    const { proxy } = createEditorProxy({ trailingSlash: true });
+    const response = proxy(request("https://site.test/about?__editor=1"));
+    assert.equal(rewriteOf(response), null, "an unslashed editor URL must redirect first, not render");
+});
+test("a site that never asked for trailing slashes is never redirected", () => {
+    const { proxy } = createEditorProxy();
+    assert.equal(proxy(request("https://site.test/about")).status, 200);
+    assert.equal(locationOf(proxy(request("https://site.test/about"))), null);
+});
+/*
+ * `__prerender_bypass` is Next's cookie, not Avocado's. A site that already used
+ * Draft Mode for its CMS's own preview sent every one of those requests into
+ * Avocado's preview route.
+ */
+test("draftCookie: false leaves Next's draft cookie to whoever else is using it", () => {
+    const { proxy } = createEditorProxy({ draftCookie: false });
+    assert.equal(rewriteOf(proxy(request("https://site.test/about", "__prerender_bypass=abc"))), null, "a Sanity or Contentful preview must not be hijacked into Avocado's route");
+    assert.equal(rewriteOf(proxy(request("https://site.test/about?__editor=1"))), "https://site.test/preview-draft/about?__editor=1", "the explicit editor parameter still works — that is the whole point of the opt-out");
+});

package/next-config.d.ts

@@ -36,15 +36,18 @@ export const AVOCADO_SERVER_EXTERNALS: string[]
 
 /**
  * Wrap a Next config so `transpilePackages` covers every linked Avocado package,
- * `images.remotePatterns` covers every host Avocado can serve an image from, and
- * Avocado's native and provider dependencies stay external to the server build.
- * Additive, and never throws.
+ * `images.remotePatterns` covers every host Avocado can serve an image from,
+ * Avocado's native and provider dependencies stay external to the server build,
+ * and a `trailingSlash: true` site stops redirecting the editor's API calls into
+ * a failed CORS preflight. Additive, and never throws.
  */
 export function withAvocado<
   T extends {
     transpilePackages?: string[]
     images?: { remotePatterns?: unknown[] }
     serverExternalPackages?: string[]
+    trailingSlash?: boolean
+    skipTrailingSlashRedirect?: boolean
     /** `null` is in Next's own type for this field, so the constraint admits it. */
     webpack?: ((config: any, context: any) => any) | null
   }
@@ -60,6 +63,13 @@ export function withAvocado<
      * yourself. Defaults to true.
      */
     serverExternals?: boolean
+    /**
+     * Set false to keep Next's trailing-slash redirect on a `trailingSlash: true`
+     * site — at the cost of the editor, whose API calls cannot survive a 308 on
+     * their CORS preflight. Defaults to true, and pairs with
+     * `createEditorProxy({ trailingSlash: true })`.
+     */
+    trailingSlash?: boolean
     /** Environment to read the orchestrator origin from. Defaults to `process.env`. */
     env?: Record<string, string | undefined>
   }

package/next-config.mjs

@@ -54,6 +54,18 @@
  * dependency, so `sharp` reached through the transpiled `orchestrator-core` got
  * bundled anyway. The two options interact, this helper sets both, and it is the
  * only place that knows it has to.
+ *
+ * ## And the fourth
+ *
+ * `trailingSlash: true` makes Next answer `/api/editor/blocks` with a 308 to
+ * `/api/editor/blocks/`. `fetch` follows that; a CORS preflight does not — a
+ * browser treats a redirect on `OPTIONS` as a network failure — so on a site
+ * with trailing slashes every editor API call fails before it is sent, and
+ * nothing in the error says why. `skipTrailingSlashRedirect` is the only way
+ * out, because the redirect runs before middleware and cannot be intercepted.
+ * Turning it off is safe only because the SDK's own proxy puts the redirect back
+ * for page routes — see `createEditorProxy({ trailingSlash: true })`, which is
+ * the other half of this and is not optional.
  */
 
 import { existsSync, readdirSync, readFileSync } from "node:fs"
@@ -70,7 +82,28 @@ function readJson(file) {
   }
 }
 
-/** Does any entry point in this manifest resolve to TypeScript? */
+/**
+ * An entry point that has to be compiled, as opposed to merely described.
+ *
+ * `.d.ts` ends in `.ts` and is not TypeScript that anything compiles — it is
+ * the type description of JavaScript that is already built. Every published
+ * package sets `types: "dist/index.d.ts"`, so a naive `/\.tsx?$/` matched all
+ * of them and this whole helper inverted on a registry install: it added the
+ * published packages to `transpilePackages`, and `transpilePackages` is
+ * precisely what drags `orchestrator-core` into the bundle and fails the build
+ * on an optional peer. The bug it exists to prevent was the bug it caused.
+ *
+ * The declaration test has to run against every string, not just `types` — an
+ * `exports` map carries its own `types` condition.
+ */
+const DECLARATION_FILE = /\.d\.[cm]?tsx?$/
+const TYPESCRIPT_FILE = /\.[cm]?tsx?$/
+
+function isCompilableEntry(entry) {
+  return TYPESCRIPT_FILE.test(entry) && !DECLARATION_FILE.test(entry)
+}
+
+/** Does any entry point in this manifest resolve to TypeScript source? */
 function shipsTypeScript(pkg) {
   const seen = []
   const walk = (value) => {
@@ -80,7 +113,7 @@ function shipsTypeScript(pkg) {
   walk(pkg.main)
   walk(pkg.types)
   walk(pkg.exports)
-  return seen.some((entry) => /\.tsx?$/.test(entry))
+  return seen.some(isCompilableEntry)
 }
 
 /** Every `node_modules` directory from `start` up to the filesystem root. */
@@ -232,6 +265,27 @@ export const AVOCADO_SERVER_EXTERNALS = [
   "@modelcontextprotocol/sdk",
 ]
 
+/**
+ * Stop Next issuing the trailing-slash redirect, so the editor's API calls can
+ * reach the site at all.
+ *
+ * Only for an app that asked for `trailingSlash: true`; every other config is
+ * returned untouched. An app that already stated a `skipTrailingSlashRedirect`
+ * of its own — either value — keeps it, because a site that has thought about
+ * this has thought about it harder than a helper can.
+ *
+ * This half alone is a regression: it stops `/about` redirecting to `/about/`,
+ * which for a site that has published slashed URLs for years is an SEO change
+ * nobody asked for. `createEditorProxy({ trailingSlash: true })` re-issues that
+ * 308 for page routes, and the pair is the fix. They are documented together
+ * and neither is useful without the other.
+ */
+function withAvocadoTrailingSlash(config) {
+  if (config.trailingSlash !== true) return config
+  if (config.skipTrailingSlashRedirect !== undefined) return config
+  return { ...config, skipTrailingSlashRedirect: true }
+}
+
 /**
  * Mark every entry in `AVOCADO_SERVER_EXTERNALS` external to the server build,
  * both ways it has to be said.
@@ -246,22 +300,34 @@ export const AVOCADO_SERVER_EXTERNALS = [
  * Both halves are additive: an app's own externals and its own `webpack` hook
  * run first and keep whatever they did.
  *
- * The hook is attached even for an app that had none, which has one cosmetic
- * cost: Next warns "Webpack is configured while Turbopack is not" for a
- * Turbopack app that declares no `turbopack` key of its own. Under Turbopack the
- * hook is never called and `serverExternalPackages` is what carries the fix, so
- * the warning is about an inert function. An app that would rather not see it
- * can declare `turbopack: {}` or opt out with `{ serverExternals: false }`.
+ * The hook is attached even for an app that had none, and on Next 16 that is not
+ * cosmetic. Turbopack is the default there, and a config carrying a `webpack`
+ * key with no `turbopack` key is a **build error**, not a warning:
+ *
+ *     ERROR: This build is using Turbopack, with a `webpack` config and no
+ *     `turbopack` config. This may be a mistake.
+ *
+ * Next's own message names the remedy — an empty `turbopack` config — so that is
+ * what goes in whenever we are the ones adding the hook and the app declared no
+ * Turbopack config of its own. It is inert on Next 15 and it never overwrites an
+ * app's own `turbopack` key. Under Turbopack the webpack hook is never called
+ * and `serverExternalPackages` carries the fix; under webpack the hook is what
+ * holds. Declaring both is the only way to be right on both.
+ *
+ * An app that would rather manage all of this itself opts out with
+ * `{ serverExternals: false }`, which attaches nothing.
  */
-function withAvocadoServerExternals(config) {
+function withAvocadoServerExternals(config, extra = []) {
+  const externals = [...AVOCADO_SERVER_EXTERNALS, ...extra]
   const declared = Array.isArray(config.serverExternalPackages) ? config.serverExternalPackages : []
-  const missing = AVOCADO_SERVER_EXTERNALS.filter((name) => !declared.includes(name))
+  const missing = externals.filter((name) => !declared.includes(name))
 
   const appWebpack = typeof config.webpack === "function" ? config.webpack : null
 
   return {
     ...config,
     ...(missing.length > 0 ? { serverExternalPackages: [...declared, ...missing] } : {}),
+    ...(config.turbopack === undefined ? { turbopack: {} } : {}),
     webpack(webpackConfig, context) {
       const result = appWebpack ? appWebpack(webpackConfig, context) : webpackConfig
       if (!context?.isServer) return result
@@ -277,7 +343,7 @@ function withAvocadoServerExternals(config) {
          */
         ({ request }, callback) => {
           if (!request) return callback()
-          for (const name of AVOCADO_SERVER_EXTERNALS) {
+          for (const name of externals) {
             if (request === name || request.startsWith(`${name}/`)) {
               return callback(null, `commonjs ${request}`)
             }
@@ -290,15 +356,46 @@ function withAvocadoServerExternals(config) {
   }
 }
 
+/**
+ * `orchestrator-core`, when it arrived built rather than linked.
+ *
+ * Naming its *dependencies* external is not enough. Turbopack resolves a
+ * dynamic import statically, so as long as it walks into
+ * `orchestrator-core/dist` at all it meets `await import("googleapis")` and
+ * fails the build over an optional peer the site deliberately never installed —
+ * `serverExternalPackages` notwithstanding, because that governs what is
+ * bundled, not what is traversed. Externalising the package itself is what
+ * stops the walk, and it is the one fix that appears in no list and no
+ * document; it was found by building a registry install on Next 16.
+ *
+ * Only when it is *not* linked. A workspace checkout points `main` at
+ * `src/index.ts`, and externalising that hands Node a TypeScript file to
+ * require at runtime — trading a build error for a crash on the first request.
+ */
+const ORCHESTRATOR_CORE = "@avocadostudio-ai/orchestrator-core"
+
+function builtOrchestratorCore(from, linked) {
+  if (linked.includes(ORCHESTRATOR_CORE)) return []
+  for (const nodeModules of nodeModulesDirs(from)) {
+    if (existsSync(join(nodeModules, ORCHESTRATOR_CORE, "package.json"))) return [ORCHESTRATOR_CORE]
+  }
+  return []
+}
+
 /**
  * Wrap a Next config so its `transpilePackages` covers every linked Avocado
  * package.
  *
  * Also merges Avocado's own image hosts into `images.remotePatterns`, since a
- * generated image comes from a host the site never chose, and marks Avocado's
+ * generated image comes from a host the site never chose, marks Avocado's
  * native and provider dependencies external to the server build, since neither
- * survives being bundled. Pass `{ images: false }` or
- * `{ serverExternals: false }` to manage either list yourself.
+ * survives being bundled, and — on a site that sets `trailingSlash: true` —
+ * turns off the redirect that would otherwise make every editor API call fail
+ * its CORS preflight. Pass `{ images: false }`, `{ serverExternals: false }` or
+ * `{ trailingSlash: false }` to manage any of them yourself.
+ *
+ * `trailingSlash` is the one that needs a second step: the SDK's proxy has to
+ * re-issue the redirect it turns off. See `withAvocadoTrailingSlash`.
  *
  * Additive and total: whatever the app already listed is kept in the order it
  * wrote it, unrelated entries included, its own `webpack` hook still runs and
@@ -312,24 +409,37 @@ export function withAvocado(config = {}, options = {}) {
     silent = false,
     images = true,
     serverExternals = true,
+    trailingSlash = true,
     env = process.env,
   } = options
 
   /*
-   * Applied before the `transpilePackages` derivation below, which has two
-   * early returns of its own — a config that already lists every linked package
-   * still needs its externals.
+   * Resolved first because the externals depend on it: whether
+   * `orchestrator-core` has to be external is exactly the question of whether
+   * it is linked. A filesystem this cannot read leaves both lists empty, which
+   * is the same "never throw" contract as before — a helper that can break
+   * `next.config` is worse than the bug it fixes.
    */
-  const withImages = images ? withAvocadoImages(config, env) : config
-  const result = serverExternals ? withAvocadoServerExternals(withImages) : withImages
-
-  let linked
+  let linked = null
   try {
     linked = linkedAvocadoPackages(cwd)
   } catch {
-    return result
+    linked = null
   }
 
+  /*
+   * Applied before the `transpilePackages` derivation below, which has two
+   * early returns of its own — a config that already lists every linked package
+   * still needs its externals.
+   */
+  const base = trailingSlash ? withAvocadoTrailingSlash(config) : config
+  const withImages = images ? withAvocadoImages(base, env) : base
+  const result = serverExternals
+    ? withAvocadoServerExternals(withImages, linked === null ? [] : builtOrchestratorCore(cwd, linked))
+    : withImages
+
+  if (linked === null) return result
+
   const declared = Array.isArray(result.transpilePackages) ? result.transpilePackages : []
   const missing = linked.filter((name) => !declared.includes(name))
   if (missing.length === 0) return result

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/site-sdk",
-  "version": "0.2.0",
+  "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/blocks": "0.2.0",
-    "@avocadostudio-ai/preview-adapter": "0.2.0",
-    "@avocadostudio-ai/shared": "0.2.0"
+    "@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.0"
+    "@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": {