@avocadostudio-ai/site-sdk 0.1.0 → 0.2.0

package/dist/draft-context-core.test.js

@@ -0,0 +1,146 @@
+/**
+ * Who may see unpublished content, and which frame may drive the editor.
+ *
+ * Both questions used to be answered by the query string. `?__editor=1` alone
+ * turned on the draft content store — in production, on the customer's own
+ * domain — and `editorOrigin` was accepted from the same URL after a check that
+ * only asked whether it parsed as http(s). One GET rendered another session's
+ * drafts and pointed the postMessage bridge wherever the caller said.
+ */
+import { test, describe, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { resolveDraftContextCore } from "./draft-context-core.js";
+import { resolveTrustedEditorOrigin, editorOriginAllowlist, isLoopbackOrigin } from "./draft-common.js";
+const SECRET = "s3cr3t-draft-key";
+const saved = {};
+const KEYS = ["NODE_ENV", "DRAFT_MODE_SECRET", "NEXT_PUBLIC_EDITOR_ORIGIN", "AVOCADO_EDITOR_ORIGINS"];
+function setEnv(values) {
+    for (const key of KEYS) {
+        if (!(key in saved))
+            saved[key] = process.env[key];
+    }
+    for (const [key, value] of Object.entries(values)) {
+        if (value === undefined)
+            delete process.env[key];
+        else
+            process.env[key] = value;
+    }
+}
+afterEach(() => {
+    for (const key of KEYS) {
+        if (saved[key] === undefined)
+            delete process.env[key];
+        else
+            process.env[key] = saved[key];
+    }
+});
+function adapter(overrides) {
+    return { isDraftMode: false, getCookie: () => undefined, ...overrides };
+}
+describe("resolveDraftContextCore — production gate", () => {
+    test("__editor=1 alone no longer opens the content store", async () => {
+        setEnv({ NODE_ENV: "production", DRAFT_MODE_SECRET: SECRET });
+        const ctx = await resolveDraftContextCore({ __editor: "1", siteId: "acme", session: "victim" }, adapter());
+        assert.equal(ctx, null);
+    });
+    test("a wrong secret is refused", async () => {
+        setEnv({ NODE_ENV: "production", DRAFT_MODE_SECRET: SECRET });
+        const ctx = await resolveDraftContextCore({ __editor: "1", siteId: "acme", secret: "guess" }, adapter());
+        assert.equal(ctx, null);
+    });
+    test("the configured secret opens it — the cookie-blocked iframe case", async () => {
+        setEnv({ NODE_ENV: "production", DRAFT_MODE_SECRET: SECRET });
+        const ctx = await resolveDraftContextCore({ __editor: "1", siteId: "acme", secret: SECRET }, adapter());
+        assert.equal(ctx?.siteId, "acme");
+    });
+    test("draft mode already enabled opens it — the secret-gated cookie path", async () => {
+        setEnv({ NODE_ENV: "production", DRAFT_MODE_SECRET: SECRET });
+        const ctx = await resolveDraftContextCore({ siteId: "acme" }, adapter({ isDraftMode: true }));
+        assert.equal(ctx?.siteId, "acme");
+    });
+    test("with no secret configured, production stays shut rather than open", async () => {
+        setEnv({ NODE_ENV: "production", DRAFT_MODE_SECRET: undefined });
+        const ctx = await resolveDraftContextCore({ __editor: "1", siteId: "acme", secret: "anything" }, adapter());
+        assert.equal(ctx, null);
+    });
+    test("development is unchanged — the parameter alone still works", async () => {
+        setEnv({ NODE_ENV: "development", DRAFT_MODE_SECRET: undefined });
+        const ctx = await resolveDraftContextCore({ __editor: "1", siteId: "acme" }, adapter());
+        assert.equal(ctx?.siteId, "acme");
+    });
+});
+describe("resolveDraftContextCore — editor origin", () => {
+    test("an unlisted origin from the URL is ignored in favour of the configured one", async () => {
+        setEnv({
+            NODE_ENV: "production",
+            DRAFT_MODE_SECRET: SECRET,
+            NEXT_PUBLIC_EDITOR_ORIGIN: "https://editor.example.com"
+        });
+        const ctx = await resolveDraftContextCore({ siteId: "acme", secret: SECRET, editorOrigin: "https://attacker.example" }, adapter());
+        assert.equal(ctx?.editorOrigin, "https://editor.example.com");
+    });
+    test("a listed origin from the URL is honoured", async () => {
+        setEnv({
+            NODE_ENV: "production",
+            DRAFT_MODE_SECRET: SECRET,
+            NEXT_PUBLIC_EDITOR_ORIGIN: "https://editor.example.com",
+            AVOCADO_EDITOR_ORIGINS: "https://staging-editor.example.com, https://other.example.com"
+        });
+        const ctx = await resolveDraftContextCore({ siteId: "acme", secret: SECRET, editorOrigin: "https://staging-editor.example.com" }, adapter());
+        assert.equal(ctx?.editorOrigin, "https://staging-editor.example.com");
+    });
+    test("a hostile origin in the cookie is ignored too", async () => {
+        setEnv({
+            NODE_ENV: "production",
+            DRAFT_MODE_SECRET: SECRET,
+            NEXT_PUBLIC_EDITOR_ORIGIN: "https://editor.example.com"
+        });
+        const ctx = await resolveDraftContextCore({ siteId: "acme", secret: SECRET }, adapter({ getCookie: (name) => (name === "editor_origin" ? "https%3A%2F%2Fattacker.example" : undefined) }));
+        assert.equal(ctx?.editorOrigin, "https://editor.example.com");
+    });
+});
+describe("resolveTrustedEditorOrigin", () => {
+    test("keeps the fallback when there is no candidate", () => {
+        assert.equal(resolveTrustedEditorOrigin({ candidate: undefined, fallback: "https://a.example", isDev: false, env: {} }), "https://a.example");
+    });
+    test("accepts loopback in development, at any port", () => {
+        for (const candidate of ["http://localhost:4100", "http://localhost:4101", "http://127.0.0.1:5173"]) {
+            assert.equal(resolveTrustedEditorOrigin({ candidate, fallback: "http://localhost:4100", isDev: true, env: {} }), candidate);
+        }
+    });
+    test("refuses loopback in production — an operator must list it", () => {
+        assert.equal(resolveTrustedEditorOrigin({
+            candidate: "http://localhost:4100",
+            fallback: "https://editor.example.com",
+            isDev: false,
+            env: {}
+        }), "https://editor.example.com");
+    });
+    test("the fallback itself is always trusted", () => {
+        assert.equal(resolveTrustedEditorOrigin({
+            candidate: "https://editor.example.com",
+            fallback: "https://editor.example.com",
+            isDev: false,
+            env: {}
+        }), "https://editor.example.com");
+    });
+});
+describe("editorOriginAllowlist", () => {
+    test("merges both variables, normalises, and de-duplicates", () => {
+        const list = editorOriginAllowlist({
+            AVOCADO_EDITOR_ORIGINS: "https://a.example/, https://b.example",
+            NEXT_PUBLIC_EDITOR_ORIGIN: "https://a.example"
+        });
+        assert.deepEqual(list, ["https://a.example", "https://b.example"]);
+    });
+    test("drops entries that are not http(s) origins", () => {
+        const list = editorOriginAllowlist({ AVOCADO_EDITOR_ORIGINS: "javascript:alert(1), not-a-url, ftp://x.example" });
+        assert.deepEqual(list, []);
+    });
+});
+test("isLoopbackOrigin recognises the local spellings and nothing else", () => {
+    assert.equal(isLoopbackOrigin("http://localhost:4100"), true);
+    assert.equal(isLoopbackOrigin("http://127.0.0.1:3000"), true);
+    assert.equal(isLoopbackOrigin("https://localhost.attacker.example"), false);
+    assert.equal(isLoopbackOrigin("https://example.com"), false);
+});

package/dist/editor-cors.d.ts

@@ -1,3 +1,15 @@
+/**
+ * CORS for the editor API routes a host app mounts.
+ *
+ * The dev editor runs on its own origin (`localhost:4100`), so the routes have
+ * to answer cross-origin requests from it. That default used to be added
+ * unconditionally, which meant a deployed site kept answering CORS-approved
+ * requests to a `localhost` origin: any page a visitor had open could read that
+ * site's draft content out of its own browser. Now the development default is
+ * only assumed in development, and a deployment says what it allows.
+ */
 export declare function getEditorCorsOrigins(): Set<string>;
+/** Test seam — the cache is a module global, and env changes must be able to take effect. */
+export declare function resetEditorCorsOrigins(): void;
 export declare function applyEditorCors(response: Response, requestOrigin: string | null): Response;
 export declare function createEditorCorsOptionsHandler(): (request: Request) => Response;

package/dist/editor-cors.js

@@ -1,15 +1,40 @@
+/**
+ * CORS for the editor API routes a host app mounts.
+ *
+ * The dev editor runs on its own origin (`localhost:4100`), so the routes have
+ * to answer cross-origin requests from it. That default used to be added
+ * unconditionally, which meant a deployed site kept answering CORS-approved
+ * requests to a `localhost` origin: any page a visitor had open could read that
+ * site's draft content out of its own browser. Now the development default is
+ * only assumed in development, and a deployment says what it allows.
+ */
+const DEV_EDITOR_ORIGIN = "http://localhost:4100";
 let cachedOrigins;
+function parseOrigins(value) {
+    return (value ?? "")
+        .split(",")
+        .map((entry) => entry.trim().replace(/\/+$/, ""))
+        .filter(Boolean);
+}
 export function getEditorCorsOrigins() {
     if (cachedOrigins)
         return cachedOrigins;
-    const defaults = ["http://localhost:4100"];
-    const extra = (process.env.EDITOR_CORS_ORIGINS ?? "")
-        .split(",")
-        .map((value) => value.trim())
-        .filter(Boolean);
-    cachedOrigins = new Set([...defaults, ...extra]);
+    const configured = parseOrigins(process.env.EDITOR_CORS_ORIGINS);
+    /*
+     * `NEXT_PUBLIC_EDITOR_ORIGIN` is what the app already tells the browser to
+     * talk to, so a deployment that set it has already named its editor and
+     * should not have to name it twice.
+     */
+    const declaredEditor = parseOrigins(process.env.NEXT_PUBLIC_EDITOR_ORIGIN);
+    const isProduction = process.env.NODE_ENV === "production";
+    const defaults = isProduction ? [] : [DEV_EDITOR_ORIGIN];
+    cachedOrigins = new Set([...defaults, ...declaredEditor, ...configured]);
     return cachedOrigins;
 }
+/** Test seam — the cache is a module global, and env changes must be able to take effect. */
+export function resetEditorCorsOrigins() {
+    cachedOrigins = undefined;
+}
 export function applyEditorCors(response, requestOrigin) {
     const vary = response.headers.get("Vary") ?? "";
     const hasOrigin = vary.split(",").map((v) => v.trim().toLowerCase()).includes("origin");

package/dist/editor-cors.test.d.ts

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

package/dist/editor-cors.test.js

@@ -0,0 +1,66 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { applyEditorCors, getEditorCorsOrigins, resetEditorCorsOrigins } from "./editor-cors.js";
+function withEnv(env, fn) {
+    const previous = {};
+    for (const [key, value] of Object.entries(env)) {
+        previous[key] = process.env[key];
+        if (value === undefined)
+            delete process.env[key];
+        else
+            process.env[key] = value;
+    }
+    resetEditorCorsOrigins();
+    try {
+        fn();
+    }
+    finally {
+        for (const [key, value] of Object.entries(previous)) {
+            if (value === undefined)
+                delete process.env[key];
+            else
+                process.env[key] = value;
+        }
+        resetEditorCorsOrigins();
+    }
+}
+const CLEAN = { EDITOR_CORS_ORIGINS: undefined, NEXT_PUBLIC_EDITOR_ORIGIN: undefined };
+test("the dev editor origin is allowed in development", () => {
+    withEnv({ ...CLEAN, NODE_ENV: "development" }, () => {
+        assert.ok(getEditorCorsOrigins().has("http://localhost:4100"));
+    });
+});
+test("the dev editor origin is not allowed in production", () => {
+    /*
+     * The bug this replaces: a deployed site answered CORS-approved requests to
+     * localhost:4100, so any page a visitor had open could read the site's drafts
+     * out of that visitor's browser.
+     */
+    withEnv({ ...CLEAN, NODE_ENV: "production" }, () => {
+        assert.equal(getEditorCorsOrigins().has("http://localhost:4100"), false);
+    });
+});
+test("a production deployment allows exactly what it names", () => {
+    withEnv({ ...CLEAN, NODE_ENV: "production", EDITOR_CORS_ORIGINS: "https://editor.example.com" }, () => {
+        const origins = getEditorCorsOrigins();
+        assert.ok(origins.has("https://editor.example.com"));
+        assert.equal(origins.size, 1);
+    });
+});
+test("the editor origin the app already advertises does not have to be named twice", () => {
+    withEnv({ ...CLEAN, NODE_ENV: "production", NEXT_PUBLIC_EDITOR_ORIGIN: "https://editor.example.com/" }, () => {
+        // Trailing slash stripped — an Origin header never has one, so a config
+        // that carries one would silently match nothing.
+        assert.ok(getEditorCorsOrigins().has("https://editor.example.com"));
+    });
+});
+test("an allowed origin gets the CORS headers and a disallowed one does not", () => {
+    withEnv({ ...CLEAN, NODE_ENV: "production", EDITOR_CORS_ORIGINS: "https://editor.example.com" }, () => {
+        const allowed = applyEditorCors(new Response(null), "https://editor.example.com");
+        assert.equal(allowed.headers.get("Access-Control-Allow-Origin"), "https://editor.example.com");
+        const denied = applyEditorCors(new Response(null), "https://evil.example.com");
+        assert.equal(denied.headers.get("Access-Control-Allow-Origin"), null);
+        // Vary is set either way, or a cache would serve one origin's answer to another.
+        assert.equal(denied.headers.get("Vary"), "Origin");
+    });
+});

package/dist/editor-manifest.d.ts

@@ -1,3 +1,2 @@
-import { blockDefinitionSchema, blockManifestSchema, validateByJsonSchemaLike, validateManifestDefaultProps, type BlockDefinition, type BlockManifest } from "@avocadostudio-ai/shared";
-export { blockDefinitionSchema, blockManifestSchema, validateByJsonSchemaLike, validateManifestDefaultProps, type BlockDefinition, type BlockManifest };
-export declare function buildBlockManifest(): BlockManifest;
+import { buildBlockManifest, blockDefinitionSchema, blockManifestSchema, validateByJsonSchemaLike, validateManifestDefaultProps, type BlockDefinition, type BlockManifest } from "@avocadostudio-ai/shared";
+export { buildBlockManifest, blockDefinitionSchema, blockManifestSchema, validateByJsonSchemaLike, validateManifestDefaultProps, type BlockDefinition, type BlockManifest };

package/dist/editor-manifest.js

@@ -1,65 +1,13 @@
-import { getBlockJsonSchema, getBlockMeta, allowedBlockTypes, defaultPropsForType } from "@avocadostudio-ai/shared";
-import { blockDefinitionSchema, blockManifestSchema, validateByJsonSchemaLike, validateManifestDefaultProps } from "@avocadostudio-ai/shared";
-export { blockDefinitionSchema, blockManifestSchema, validateByJsonSchemaLike, validateManifestDefaultProps };
-// --- Manifest builder ---
-// Built fresh each time to include custom blocks registered after initial load.
-// Custom site blocks call registerBlock() in their schema.ts (imported via blocks/register.ts),
-// which adds them to allowedBlockTypes. The manifest must reflect ALL registered blocks,
-// not just the standard library ones.
-export function buildBlockManifest() {
-    const blocks = allowedBlockTypes
-        .map((type) => {
-        const meta = getBlockMeta(type);
-        const propsSchema = getBlockJsonSchema(type);
-        if (!propsSchema)
-            return null; // skip blocks without schema (shouldn't happen but be safe)
-        const finalSchema = applyMetaEnumsToSchema(propsSchema, meta);
-        // Only attach defaultProps that actually satisfy the block's schema.
-        // defaultPropsForType() hands custom (non-core) blocks a generic CTA-shaped
-        // fallback; if that violates a custom schema (e.g. a richtext field expecting
-        // a doc object, not a string) it would fail validateManifestDefaultProps and
-        // poison the WHOLE manifest, making every block read as "unknown" in the editor.
-        const candidateDefaults = defaultPropsForType(type);
-        const defaultProps = validateByJsonSchemaLike(finalSchema, candidateDefaults)
-            ? candidateDefaults
-            : undefined;
-        return {
-            type,
-            displayName: meta?.displayName ?? type,
-            propsSchema: finalSchema,
-            defaultProps
-        };
-    })
-        .filter((b) => b !== null);
-    return { version: 1, blocks };
-}
-/**
- * Fold enum options declared in the block's registry `meta.fields` into the
- * derived JSON schema. A site can declare `f.enum("Gap", ["sm","md","lg"])` in
- * its block meta while the Zod prop stays a plain `z.string()` (so any value
- * still validates). Without this, manifest-driven custom blocks lose the enum
- * and the editor renders a free-text input instead of a dropdown. We only add
- * `enum` (the editor reads it to pick a select control); validation is type-only
- * (see validateByJsonSchemaLike), so widening here never rejects stored content.
+/*
+ * The manifest builder itself now lives in `@avocadostudio-ai/shared`.
+ *
+ * It moved because the SDK was no longer its only caller: the orchestrator
+ * serves the same manifest at `GET /blocks/manifest` so an MCP agent can
+ * discover the *target site's* block vocabulary instead of whatever happens to
+ * be registered in its own process. `shared` is the one package both the SDK
+ * and orchestrator-core already depend on, so it is where a single answer can
+ * live. This module stays as the SDK's public entry point — every site
+ * template, example and doc imports `buildBlockManifest` from here.
  */
-function applyMetaEnumsToSchema(schema, meta) {
-    if (!meta?.fields)
-        return schema;
-    const properties = schema.properties;
-    if (!properties || typeof properties !== "object")
-        return schema;
-    let next;
-    for (const [key, fieldMeta] of Object.entries(meta.fields)) {
-        if (fieldMeta.kind !== "enum" || !fieldMeta.options?.length)
-            continue;
-        const prop = properties[key];
-        if (!prop || typeof prop !== "object" || Array.isArray(prop))
-            continue;
-        const propObj = prop;
-        if (Array.isArray(propObj.enum))
-            continue; // schema already carries an enum
-        next ??= { ...schema, properties: { ...properties } };
-        next.properties[key] = { ...propObj, type: "string", enum: [...fieldMeta.options] };
-    }
-    return next ?? schema;
-}
+import { buildBlockManifest, blockDefinitionSchema, blockManifestSchema, validateByJsonSchemaLike, validateManifestDefaultProps } from "@avocadostudio-ai/shared";
+export { buildBlockManifest, blockDefinitionSchema, blockManifestSchema, validateByJsonSchemaLike, validateManifestDefaultProps };

package/dist/editor-matcher.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The route matcher that decides which requests the editor rewrite even sees.
+ *
+ * Separate from `proxy.ts` because it is pure string logic with no dependency
+ * on Next: the rewrite itself needs `NextResponse`, but the matcher is just a
+ * pattern, and Next 16 requires it to be inlined at the call site anyway. Its
+ * own module means a caller that only wants the pattern — the scaffolder
+ * templates, a test, a non-Next host — does not have to pull in `next/server`.
+ */
+/** Default route prefix that the dynamic editor/draft page lives under. */
+export declare const DEFAULT_PREVIEW_ROUTE = "/preview-draft";
+/**
+ * Build the `config.matcher` pattern that skips Next internals, the API routes,
+ * static assets, and the preview route itself.
+ *
+ * Next.js 16 requires the `config` export in a `proxy.ts` to be a **static
+ * object literal** — it is read by static analysis, so it cannot be a factory
+ * return value, a spread, or an imported constant. Use this helper at authoring
+ * time (or copy the string it produces) to write that literal by hand:
+ *
+ * ```ts
+ * export const config = {
+ *   matcher: ["/((?!_next|preview-draft|api|favicon\\.ico|icon\\.svg|logos/|generated-images/|.*\\.).*)"],
+ * }
+ * ```
+ */
+export declare function buildEditorMatcher(previewRoute?: string): string;

package/dist/editor-matcher.js

@@ -0,0 +1,34 @@
+/**
+ * The route matcher that decides which requests the editor rewrite even sees.
+ *
+ * Separate from `proxy.ts` because it is pure string logic with no dependency
+ * on Next: the rewrite itself needs `NextResponse`, but the matcher is just a
+ * pattern, and Next 16 requires it to be inlined at the call site anyway. Its
+ * own module means a caller that only wants the pattern — the scaffolder
+ * templates, a test, a non-Next host — does not have to pull in `next/server`.
+ */
+/** Default route prefix that the dynamic editor/draft page lives under. */
+export const DEFAULT_PREVIEW_ROUTE = "/preview-draft";
+/**
+ * Build the `config.matcher` pattern that skips Next internals, the API routes,
+ * static assets, and the preview route itself.
+ *
+ * Next.js 16 requires the `config` export in a `proxy.ts` to be a **static
+ * object literal** — it is read by static analysis, so it cannot be a factory
+ * return value, a spread, or an imported constant. Use this helper at authoring
+ * time (or copy the string it produces) to write that literal by hand:
+ *
+ * ```ts
+ * export const config = {
+ *   matcher: ["/((?!_next|preview-draft|api|favicon\\.ico|icon\\.svg|logos/|generated-images/|.*\\.).*)"],
+ * }
+ * ```
+ */
+export function buildEditorMatcher(previewRoute = DEFAULT_PREVIEW_ROUTE) {
+    // Escape special regex chars in the route prefix. The leading slash is
+    // dropped rather than sliced off blindly: `slice(1)` on a route written
+    // without one turned "preview" into "review" and matched nothing anybody
+    // could see.
+    const escapedRoute = previewRoute.replace(/^\/+/, "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return `/((?!_next|${escapedRoute}|api|favicon\\.ico|icon\\.svg|logos/|generated-images/|.*\\.).*)`;
+}

package/dist/editor-query.js

@@ -1,4 +1,10 @@
-const EDITOR_KEYS = ["session", "siteId", "editorOrigin", "__editor"];
+/*
+ * `secret` is carried alongside these so an in-site navigation stays in editor
+ * mode when the draft cookie is blocked. It is deliberately last: everything
+ * here ends up in hrefs the preview renders, so keep the list to what editor
+ * mode actually needs to survive a click.
+ */
+const EDITOR_KEYS = ["session", "siteId", "editorOrigin", "__editor", "secret"];
 export function buildEditorQuerySuffix(searchParams) {
     const params = new URLSearchParams();
     for (const key of EDITOR_KEYS) {

package/dist/index.d.ts

@@ -3,3 +3,5 @@ export type { SiteConfig } from "@avocadostudio-ai/shared";
 export { pageDocSchema } from "./types.ts";
 export { buildSlug } from "./editor-query.ts";
 export { renderBlocks } from "./render-blocks.tsx";
+export { buildPageMetadata, derivePageDescription, derivePageTitle, stripMarkdown, truncateForMeta, DEFAULT_SITE_DESCRIPTION, } from "./page-metadata.ts";
+export type { PageMetadata, BuildPageMetadataOptions } from "./page-metadata.ts";

package/dist/index.js

@@ -3,3 +3,5 @@ export { pageDocSchema } from "./types.js";
 export { buildSlug } from "./editor-query.js";
 // Block rendering
 export { renderBlocks } from "./render-blocks.js";
+// SEO / metadata
+export { buildPageMetadata, derivePageDescription, derivePageTitle, stripMarkdown, truncateForMeta, DEFAULT_SITE_DESCRIPTION, } from "./page-metadata.js";

package/dist/integration-check.js

@@ -1,4 +1,5 @@
 import { getConfiguredDraftSecret } from "@avocadostudio-ai/shared";
+import { editorOriginAllowlist } from "./draft-common.js";
 let checked = false;
 /**
  * Run once on first editor API request to validate essential integration config.
@@ -13,7 +14,16 @@ export function checkIntegrationOnce() {
     const draftSecret = getConfiguredDraftSecret(process.env);
     if (!draftSecret) {
         warnings.push("DRAFT_MODE_SECRET is not set — editor draft mode will not work. " +
-            "Set DRAFT_MODE_SECRET (or VITE_SITE_DRAFT_SECRET) in your .env file.");
+            "Set DRAFT_MODE_SECRET (or VITE_SITE_DRAFT_SECRET) in your .env file. " +
+            "In production this is what authorizes a request to see unpublished content.");
+    }
+    // 1b. Editor origin allowlist — the postMessage target and the frame allowed
+    // to drive inline edits. Without one, a caller-supplied origin has nothing to
+    // be checked against and editor mode silently has no bridge.
+    if (process.env.NODE_ENV === "production" && editorOriginAllowlist().length === 0) {
+        warnings.push("No editor origin is configured — set NEXT_PUBLIC_EDITOR_ORIGIN (and " +
+            "AVOCADO_EDITOR_ORIGINS for any additional editor deployments). Origins " +
+            "arriving in the URL are not trusted unless they are listed.");
     }
     // 2. Orchestrator URL
     const orchestratorUrl = process.env.ORCHESTRATOR_URL?.trim();

package/dist/manifest-utils.d.ts

@@ -6,6 +6,19 @@ export type ManifestFieldInfo = {
     listImageFields: Map<string, Map<string, Set<string>>>;
     /** All list field names per block type (e.g. CardGrid → {"cards"}, FeatureGrid → {"features"}) */
     listFieldNames: Map<string, Set<string>>;
+    /**
+     * Rich-text fields stored as a ProseMirror *document* rather than a markdown
+     * string, per block type.
+     *
+     * An integration whose CMS has real rich text (Sanity Portable Text,
+     * Contentful Rich Text) maps those fields to a document so nothing is
+     * flattened. It needs to know which props those are at both boundaries — to
+     * convert on read and to convert back on publish — and hand-maintaining the
+     * list is how the two ends drift apart.
+     */
+    documentFields: Map<string, Set<string>>;
+    /** The same, for fields inside list items (e.g. FAQ → items → {"answer"}). */
+    listDocumentFields: Map<string, Map<string, Set<string>>>;
 };
 /**
  * Derive field metadata per block type from the manifest's propsSchema.

package/dist/manifest-utils.js

@@ -1,4 +1,4 @@
-import { deriveFieldMetaFromSchema } from "@avocadostudio-ai/shared";
+import { resolveManifestFieldMeta, isProseMirrorDocSchema } from "@avocadostudio-ai/shared";
 const _cache = new WeakMap();
 /**
  * Derive field metadata per block type from the manifest's propsSchema.
@@ -14,14 +14,27 @@ export function getManifestImageFields(manifest) {
     const imageFields = new Map();
     const listImageFields = new Map();
     const listFieldNames = new Map();
+    const documentFields = new Map();
+    const listDocumentFields = new Map();
     for (const block of manifest.blocks) {
-        const { fields, listFields } = deriveFieldMetaFromSchema(block.propsSchema);
+        const { fields, listFields } = resolveManifestFieldMeta(block);
+        const props = (block.propsSchema.properties ?? {});
         const imgs = new Set();
         for (const [key, meta] of Object.entries(fields)) {
             if (meta.kind === "image")
                 imgs.add(key);
         }
         imageFields.set(block.type, imgs);
+        // `kind` alone cannot tell the two apart — a markdown string and a document
+        // are both "richtext" to the editor. The schema can: a document self-
+        // identifies by pinning its `type` to the literal "doc".
+        const docs = new Set();
+        for (const key of Object.keys(fields)) {
+            if (isProseMirrorDocSchema(props[key]))
+                docs.add(key);
+        }
+        if (docs.size > 0)
+            documentFields.set(block.type, docs);
         const listNames = new Set(Object.keys(listFields));
         if (listNames.size > 0)
             listFieldNames.set(block.type, listNames);
@@ -37,8 +50,22 @@ export function getManifestImageFields(manifest) {
         }
         if (listImgs.size > 0)
             listImageFields.set(block.type, listImgs);
+        const listDocs = new Map();
+        for (const [listKey, listMeta] of Object.entries(listFields)) {
+            const listSchema = props[listKey];
+            const itemProps = (listSchema?.items?.properties ?? {});
+            const itemDocs = new Set();
+            for (const itemKey of Object.keys(listMeta.itemFields)) {
+                if (isProseMirrorDocSchema(itemProps[itemKey]))
+                    itemDocs.add(itemKey);
+            }
+            if (itemDocs.size > 0)
+                listDocs.set(listKey, itemDocs);
+        }
+        if (listDocs.size > 0)
+            listDocumentFields.set(block.type, listDocs);
     }
-    const result = { imageFields, listImageFields, listFieldNames };
+    const result = { imageFields, listImageFields, listFieldNames, documentFields, listDocumentFields };
     _cache.set(manifest, result);
     return result;
 }

package/dist/manifest-utils.test.d.ts

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

package/dist/manifest-utils.test.js

@@ -0,0 +1,72 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { getManifestImageFields } from "./manifest-utils.js";
+/**
+ * A rich-text prop can be stored two ways, and an integration has to tell them
+ * apart at both boundaries — convert on read, convert back on publish. The
+ * editor's `FieldKind` cannot help: a markdown string and a ProseMirror
+ * document are both `richtext` to it. The schema can, because a document pins
+ * its `type` to the literal "doc".
+ */
+const MANIFEST = {
+    version: 1,
+    blocks: [
+        {
+            type: "RichText",
+            propsSchema: {
+                type: "object",
+                properties: {
+                    title: { type: "string" },
+                    body: { type: "string", contentMediaType: "text/markdown" }
+                }
+            }
+        },
+        {
+            type: "ArticleBody",
+            propsSchema: {
+                type: "object",
+                properties: {
+                    title: { type: "string" },
+                    body: { type: "object", properties: { type: { const: "doc" }, content: { type: "array" } } }
+                }
+            }
+        },
+        {
+            type: "FAQ",
+            propsSchema: {
+                type: "object",
+                properties: {
+                    items: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: {
+                                q: { type: "string" },
+                                answer: { type: "object", properties: { type: { const: "doc" }, content: { type: "array" } } }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    ]
+};
+const info = getManifestImageFields(MANIFEST);
+test("a document-valued rich-text prop is reported under documentFields", () => {
+    assert.deepEqual([...(info.documentFields.get("ArticleBody") ?? [])], ["body"]);
+});
+test("a markdown-string rich-text prop is not", () => {
+    assert.equal(info.documentFields.has("RichText"), false);
+});
+test("a document-valued field inside a list item is reported too", () => {
+    assert.deepEqual([...(info.listDocumentFields.get("FAQ")?.get("items") ?? [])], ["answer"]);
+});
+test("a block with no document fields is absent rather than present-and-empty", () => {
+    // Callers do `documentFields.get(type) ?? new Set()`, so an empty entry would
+    // work — but keeping the map to blocks that actually have one makes a
+    // debugging dump of it readable.
+    assert.equal(info.documentFields.has("FAQ"), false);
+});
+test("the derivation is cached by manifest reference", () => {
+    assert.equal(getManifestImageFields(MANIFEST), info);
+});