@avocadostudio-ai/site-sdk 0.1.0 → 0.2.1

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);
+});

package/dist/middleware.d.ts

@@ -1,24 +1,10 @@
-import { NextResponse, type NextRequest } from "next/server";
+import { type EditorProxyOptions } from "./proxy.ts";
 /**
  * Options for the editor middleware factory.
+ *
+ * @deprecated Use {@link EditorProxyOptions} from `@avocadostudio-ai/site-sdk/proxy`.
  */
-export type EditorMiddlewareOptions = {
-    /**
-     * The internal route prefix that the dynamic editor/draft page lives under.
-     * @default "/preview-draft"
-     */
-    previewRoute?: string;
-    /**
-     * Query parameter that signals an editor iframe request.
-     * @default "__editor"
-     */
-    editorParam?: string;
-    /**
-     * Name of the Next.js draft-mode bypass cookie.
-     * @default "__prerender_bypass"
-     */
-    draftCookie?: string;
-};
+export type EditorMiddlewareOptions = EditorProxyOptions;
 /**
  * Create a Next.js middleware function that rewrites editor/draft requests
  * to a dynamic preview route, keeping the main page route fully static.
@@ -28,9 +14,25 @@ export type EditorMiddlewareOptions = {
  * import { createEditorMiddleware } from "@avocadostudio-ai/site-sdk/middleware"
  * export const { middleware, config } = createEditorMiddleware()
  * ```
+ *
+ * @deprecated Next.js 16 renamed the `middleware` file convention to `proxy`.
+ * Rename `middleware.ts` to `proxy.ts` and switch to `createEditorProxy` from
+ * `@avocadostudio-ai/site-sdk/proxy`. Note that Next 16 rejects this destructured
+ * form — `config` must be a static object literal in the file:
+ * ```ts
+ * import { createEditorProxy } from "@avocadostudio-ai/site-sdk/proxy"
+ *
+ * export const proxy = createEditorProxy().proxy
+ *
+ * export const config = {
+ *   matcher: ["/((?!_next|preview-draft|api|favicon\\.ico|icon\\.svg|logos/|generated-images/|.*\\.).*)"],
+ * }
+ * ```
+ * This entry point stays for Next.js 15 sites, where the destructured form
+ * works, and returns the identical rewrite under the older export name.
  */
 export declare function createEditorMiddleware(options?: EditorMiddlewareOptions): {
-    middleware: (request: NextRequest) => NextResponse<unknown>;
+    middleware: (request: import("next/server").NextRequest) => import("next/server").NextResponse<unknown>;
     config: {
         matcher: string[];
     };

package/dist/middleware.js

@@ -1,4 +1,4 @@
-import { NextResponse } from "next/server";
+import { createEditorProxy } from "./proxy.js";
 /**
  * Create a Next.js middleware function that rewrites editor/draft requests
  * to a dynamic preview route, keeping the main page route fully static.
@@ -8,27 +8,24 @@ import { NextResponse } from "next/server";
  * import { createEditorMiddleware } from "@avocadostudio-ai/site-sdk/middleware"
  * export const { middleware, config } = createEditorMiddleware()
  * ```
+ *
+ * @deprecated Next.js 16 renamed the `middleware` file convention to `proxy`.
+ * Rename `middleware.ts` to `proxy.ts` and switch to `createEditorProxy` from
+ * `@avocadostudio-ai/site-sdk/proxy`. Note that Next 16 rejects this destructured
+ * form — `config` must be a static object literal in the file:
+ * ```ts
+ * import { createEditorProxy } from "@avocadostudio-ai/site-sdk/proxy"
+ *
+ * export const proxy = createEditorProxy().proxy
+ *
+ * export const config = {
+ *   matcher: ["/((?!_next|preview-draft|api|favicon\\.ico|icon\\.svg|logos/|generated-images/|.*\\.).*)"],
+ * }
+ * ```
+ * This entry point stays for Next.js 15 sites, where the destructured form
+ * works, and returns the identical rewrite under the older export name.
  */
 export function createEditorMiddleware(options) {
-    const previewRoute = options?.previewRoute ?? "/preview-draft";
-    const editorParam = options?.editorParam ?? "__editor";
-    const draftCookie = options?.draftCookie ?? "__prerender_bypass";
-    function middleware(request) {
-        const isEditor = request.nextUrl.searchParams.get(editorParam) === "1";
-        const hasDraftCookie = request.cookies.has(draftCookie);
-        if (isEditor || hasDraftCookie) {
-            const url = request.nextUrl.clone();
-            url.pathname = `${previewRoute}${url.pathname}`;
-            return NextResponse.rewrite(url);
-        }
-        return NextResponse.next();
-    }
-    // Escape special regex chars in the route prefix (strip leading slash for the pattern)
-    const escapedRoute = previewRoute.slice(1).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    const config = {
-        matcher: [
-            `/((?!_next|${escapedRoute}|api|favicon\\.ico|icon\\.svg|logos/|generated-images/|.*\\.).*)`
-        ],
-    };
-    return { middleware, config };
+    const { proxy, config } = createEditorProxy(options);
+    return { middleware: proxy, config };
 }

package/dist/next-config.test.d.ts

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