@avocadostudio-ai/site-sdk 0.2.0 → 0.2.1

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