@avocadostudio-ai/site-sdk 0.1.0 → 0.2.0

package/dist/proxy.d.ts

@@ -0,0 +1,58 @@
+import { NextResponse, type NextRequest } from "next/server";
+export { DEFAULT_PREVIEW_ROUTE, buildEditorMatcher } from "./editor-matcher.ts";
+/**
+ * Options for the editor proxy factory.
+ */
+export type EditorProxyOptions = {
+    /**
+     * 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;
+};
+/**
+ * Create a Next.js proxy function that rewrites editor/draft requests
+ * to a dynamic preview route, keeping the main page route fully static.
+ *
+ * Next.js 16 renamed the `middleware` file convention to `proxy`. Usage in
+ * `proxy.ts` — note that `config` must be written as a literal, because Next 16
+ * rejects both `export const { proxy, config } = createEditorProxy()` and
+ * `export const config = editor.config` with "Next.js can't recognize the
+ * exported `config` field in route. It needs to be a static object":
+ *
+ * ```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/|.*\\.).*)"],
+ * }
+ * ```
+ *
+ * On Next.js 15 the file is still called `middleware.ts` and the destructured
+ * form works — see `createEditorMiddleware` in
+ * `@avocadostudio-ai/site-sdk/middleware`.
+ *
+ * The returned `config` is kept for that Next 15 path and for tests; on Next 16
+ * inline the literal instead. {@link buildEditorMatcher} produces the string.
+ *
+ * The rewrite only reads the URL and cookies, so it runs unchanged on the
+ * Node.js runtime that `proxy` mandates.
+ */
+export declare function createEditorProxy(options?: EditorProxyOptions): {
+    proxy: (request: NextRequest) => NextResponse<unknown>;
+    config: {
+        matcher: string[];
+    };
+};

package/dist/proxy.js

@@ -0,0 +1,50 @@
+import { NextResponse } from "next/server";
+import { DEFAULT_PREVIEW_ROUTE, buildEditorMatcher } from "./editor-matcher.js";
+export { DEFAULT_PREVIEW_ROUTE, buildEditorMatcher } from "./editor-matcher.js";
+/**
+ * Create a Next.js proxy function that rewrites editor/draft requests
+ * to a dynamic preview route, keeping the main page route fully static.
+ *
+ * Next.js 16 renamed the `middleware` file convention to `proxy`. Usage in
+ * `proxy.ts` — note that `config` must be written as a literal, because Next 16
+ * rejects both `export const { proxy, config } = createEditorProxy()` and
+ * `export const config = editor.config` with "Next.js can't recognize the
+ * exported `config` field in route. It needs to be a static object":
+ *
+ * ```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/|.*\\.).*)"],
+ * }
+ * ```
+ *
+ * On Next.js 15 the file is still called `middleware.ts` and the destructured
+ * form works — see `createEditorMiddleware` in
+ * `@avocadostudio-ai/site-sdk/middleware`.
+ *
+ * The returned `config` is kept for that Next 15 path and for tests; on Next 16
+ * inline the literal instead. {@link buildEditorMatcher} produces the string.
+ *
+ * The rewrite only reads the URL and cookies, so it runs unchanged on the
+ * Node.js runtime that `proxy` mandates.
+ */
+export function createEditorProxy(options) {
+    const previewRoute = options?.previewRoute ?? DEFAULT_PREVIEW_ROUTE;
+    const editorParam = options?.editorParam ?? "__editor";
+    const draftCookie = options?.draftCookie ?? "__prerender_bypass";
+    function proxy(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();
+    }
+    const config = { matcher: [buildEditorMatcher(previewRoute)] };
+    return { proxy, config };
+}

package/dist/proxy.test.d.ts

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

package/dist/proxy.test.js

@@ -0,0 +1,72 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { NextRequest } from "next/server";
+import { buildEditorMatcher, createEditorProxy, DEFAULT_PREVIEW_ROUTE } from "./proxy.js";
+import { createEditorMiddleware } from "./middleware.js";
+/*
+ * The rewrite that keeps the published route static and sends editor traffic to
+ * the dynamic one. It is the single piece of Next config every integrator has
+ * to copy, and until now nothing exercised it — the contract in the READMEs
+ * (`export const { middleware, config } = ...`) turned out not to work on
+ * Next 16 at all, and no test noticed.
+ */
+const rewriteOf = (response) => response.headers.get("x-middleware-rewrite");
+const request = (url, cookie) => new NextRequest(url, cookie ? { headers: { cookie } } : undefined);
+test("an editor request is rewritten to the preview route", () => {
+    const { proxy } = createEditorProxy();
+    const rewrite = rewriteOf(proxy(request("https://site.test/about?__editor=1")));
+    assert.equal(rewrite, "https://site.test/preview-draft/about?__editor=1");
+});
+test("a draft-mode cookie is rewritten even without the query parameter", () => {
+    const { proxy } = createEditorProxy();
+    const rewrite = rewriteOf(proxy(request("https://site.test/about", "__prerender_bypass=abc")));
+    assert.equal(rewrite, "https://site.test/preview-draft/about");
+});
+test("an ordinary visitor is passed straight through", () => {
+    const { proxy } = createEditorProxy();
+    const response = proxy(request("https://site.test/about"));
+    assert.equal(rewriteOf(response), null, "a published page must not be rewritten to the dynamic route");
+    assert.equal(response.headers.get("x-middleware-next"), "1");
+});
+test("__editor with any value other than 1 is not an editor request", () => {
+    const { proxy } = createEditorProxy();
+    assert.equal(rewriteOf(proxy(request("https://site.test/?__editor=0"))), null);
+});
+test("the preview route and cookie name can be overridden together", () => {
+    const { proxy, config } = createEditorProxy({
+        previewRoute: "/draft",
+        editorParam: "edit",
+        draftCookie: "my_bypass",
+    });
+    assert.equal(rewriteOf(proxy(request("https://site.test/x?edit=1"))), "https://site.test/draft/x?edit=1");
+    assert.equal(rewriteOf(proxy(request("https://site.test/x", "my_bypass=1"))), "https://site.test/draft/x");
+    assert.match(config.matcher[0], /draft/);
+});
+test("the matcher skips the preview route itself, or the rewrite would loop", () => {
+    const matcher = new RegExp(`^${buildEditorMatcher()}$`);
+    assert.equal(matcher.test("/preview-draft/about"), false);
+    assert.equal(matcher.test("/_next/static/chunk.js"), false);
+    assert.equal(matcher.test("/api/editor/pages"), false);
+    assert.equal(matcher.test("/favicon.ico"), false);
+    assert.equal(matcher.test("/about"), true);
+    assert.equal(matcher.test("/"), true);
+});
+test("a custom preview route is escaped into the matcher", () => {
+    const matcher = new RegExp(`^${buildEditorMatcher("/draft.preview")}$`);
+    assert.equal(matcher.test("/draft.preview/about"), false);
+    // The `.` is escaped, so it does not match any character.
+    assert.equal(matcher.test("/draftxpreview/about"), true);
+});
+test("the deprecated middleware entry point is the same rewrite under the old name", () => {
+    /*
+     * Kept working for Next 15 sites, where `export const { middleware, config }`
+     * still parses. On Next 16 the file is `proxy.ts` and `config` has to be a
+     * literal — see `createEditorProxy`.
+     */
+    const { middleware, config } = createEditorMiddleware();
+    assert.equal(rewriteOf(middleware(request("https://site.test/about?__editor=1"))), "https://site.test/preview-draft/about?__editor=1");
+    assert.deepEqual(config, createEditorProxy().config);
+});
+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`);
+});

package/dist/publish/field-diff.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Publishing an edited page back to a CMS, as a field-level diff.
+ *
+ * `onPublish(pages, config)` means "here are the full PageDocs, store them".
+ * That is implementable when the CMS shape *is* the editor shape — a JSON file
+ * — and not otherwise. Every real CMS read is a projection: an asset reference
+ * flattened to a URL string, a document reference resolved to an href for one
+ * language, a rich-text tree flattened to markdown. Writing the projection back
+ * replaces the reference with the flattening and destroys the document.
+ *
+ * So a real integration publishes a diff: walk the same field specs used to
+ * project, compare each field against the value it was projected from, and emit
+ * a set at the key-addressed path that owns it. The first integration to do
+ * this hand-wrote about 230 lines of it. This is that shape, generalised, so
+ * the next one does not.
+ *
+ * **What is here and what is not.** The mechanism is general: the walk, the
+ * unchanged-field skip, list items matched on a stable key rather than an
+ * index, routing a block's patches to a document other than the page's, and the
+ * vocabulary for reporting a change that cannot be expressed. The *inversions*
+ * are not, and cannot be — `rehydrate` undoes a projection only the integration
+ * knows it made. Neither is uploading an asset or re-resolving a reference;
+ * those are per-CMS capabilities, and until an integration has them the honest
+ * answer is `unsupported`, which is why that is a first-class result here
+ * rather than a thrown error.
+ */
+/** How a CMS addresses one element of a list. */
+export interface PathSyntax {
+    /** `prefix` + field, e.g. `pageBuilder[_key=="b1"].heading`. */
+    field(prefix: string, field: string): string;
+    /** The prefix for one item of a list, given its key and position. */
+    item(prefix: string, field: string, key: string, index: number): string;
+}
+/**
+ * Sanity addresses array elements by `_key`, never by index — an index-addressed
+ * patch races any concurrent edit that reorders the array.
+ */
+export declare const sanityPaths: PathSyntax;
+/**
+ * Index addressing, for stores that have no element identity (Strapi component
+ * lists, a plain JSON array). Correct only when the publish is the only writer:
+ * anything that reorders between read and write silently patches the wrong row,
+ * which is exactly what `_key` exists to prevent.
+ */
+export declare const indexPaths: PathSyntax;
+/** One `set` to apply, addressed at the field that owns the value. */
+export interface FieldPatch {
+    documentId: string;
+    path: string;
+    value: unknown;
+}
+/**
+ * A change the editor made that this integration cannot express.
+ *
+ * Reported rather than guessed at. A publisher that silently drops these
+ * reports success for an edit the site will never show; one that guesses writes
+ * a URL where a reference belongs. Both are worse than saying so.
+ */
+export interface UnsupportedChange {
+    /** In the editor's own terms — the page and block a person would recognise. */
+    where: string;
+    /** What was done. */
+    change: string;
+    /** What would have to exist for it to work, when that is known. */
+    remedy?: string;
+}
+export interface FieldDiff {
+    patches: FieldPatch[];
+    unsupported: UnsupportedChange[];
+}
+/**
+ * Emits patches for one changed field, or reports why it cannot.
+ *
+ * This is where a lossy projection is caught. `writeFigure` in the reference
+ * integration sets `alt` — which round-trips — and reports the image itself,
+ * because Sanity stores an asset reference and the editor hands back a URL.
+ */
+export type FieldWriter<Ctx> = (change: {
+    before: unknown;
+    after: unknown;
+    /** The fully-addressed path of this field. */
+    path: string;
+    where: string;
+    ctx: Ctx;
+    emit: (path: string, value: unknown) => void;
+    reject: (change: string, remedy?: string) => void;
+}) => void;
+export interface PublishFieldSpec<Ctx = unknown> {
+    /** The CMS field name, when it differs from the props key. */
+    cmsKey?: string;
+    /**
+     * Undo the projection: given the edited props and the value the CMS holds,
+     * return what the CMS should hold now.
+     *
+     * `before` is passed so an inversion can be partial — return the stored
+     * object with one key replaced, and everything the projection dropped
+     * survives untouched. That is the difference between editing a field and
+     * overwriting a document.
+     */
+    rehydrate(props: Record<string, unknown>, before: unknown, ctx: Ctx): unknown;
+    /** `"set"` writes the value at its path. A function decides for itself. */
+    write?: "set" | FieldWriter<Ctx>;
+    /** For a list field: the specs for one item. */
+    itemFields?: Record<string, PublishFieldSpec<Ctx>>;
+    /** How an item identifies itself upstream. Defaults to reading `_key`. */
+    itemKey?(item: Record<string, unknown>): string | undefined;
+}
+export type FieldSpecs<Ctx> = Record<string, PublishFieldSpec<Ctx>>;
+/** Structural equality, for "did this field actually change". */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/**
+ * Diff one object's fields against the source it was projected from.
+ *
+ * `props` is what the editor holds; `source` is what the CMS holds. Recurses
+ * into list fields, matching items on their own key so a reorder upstream
+ * cannot make a patch land on the wrong row.
+ */
+export declare function diffFields<Ctx>(args: {
+    specs: FieldSpecs<Ctx>;
+    props: Record<string, unknown>;
+    source: Record<string, unknown>;
+    ctx: Ctx;
+    documentId: string;
+    /** Path prefix this object sits at, e.g. `pageBuilder[_key=="b1"].`. */
+    prefix?: string;
+    where: string;
+    paths?: PathSyntax;
+}): FieldDiff;
+/**
+ * Fold a flat patch list into one `set` object per document.
+ *
+ * Most CMS clients take a single patch per document rather than one per field,
+ * and a caller that concatenates diffs from several blocks will have several
+ * entries for the same document. Documents with nothing to set are dropped, so
+ * an unchanged page issues no write at all.
+ */
+export declare function groupPatches(patches: FieldPatch[]): Array<{
+    documentId: string;
+    set: Record<string, unknown>;
+}>;
+/** Merge diffs from several blocks or pages into one. */
+export declare function mergeDiffs(diffs: FieldDiff[]): FieldDiff;
+/** Where one block's values live upstream, and how to invert them. */
+export interface BlockTarget<Ctx> {
+    /** The CMS document that owns these values — not necessarily the page's. */
+    documentId: string;
+    /** Path prefix within that document, e.g. `pageBuilder[_key=="b1"].`. */
+    prefix: string;
+    specs: FieldSpecs<Ctx>;
+    /** What the CMS holds for this block: the value the props were projected from. */
+    source: Record<string, unknown>;
+}
+/**
+ * Diff every block on a page.
+ *
+ * The routing decision stays with the integration — `locate` is where a block
+ * placed by a shared section writes to the *section* document rather than the
+ * page, and where a per-placement heading override stays page-local. Only the
+ * integration knows its own document graph. What is owned here is the loop, the
+ * report for a block with nowhere to write, and the `where` string a person has
+ * to be able to recognise.
+ *
+ * Returning `null` from `locate` reports the block as unpublishable rather than
+ * skipping it silently. That is almost always a block the editor added: the CMS
+ * has no document behind it, so there is no path to patch, and a publisher that
+ * quietly dropped it would report success for content the site will never show.
+ */
+export declare function diffPage<Ctx>(args: {
+    page: {
+        slug: string;
+        blocks: Array<{
+            id: string;
+            type: string;
+            props: Record<string, unknown>;
+        }>;
+    };
+    ctx: Ctx;
+    locate(block: {
+        id: string;
+        type: string;
+        props: Record<string, unknown>;
+    }): BlockTarget<Ctx> | BlockTarget<Ctx>[] | null;
+    paths?: PathSyntax;
+    /** How a block is named in a report. Defaults to `"/slug → type"`. */
+    where?(pageSlug: string, block: {
+        id: string;
+        type: string;
+    }): string;
+}): FieldDiff;
+/** One line per refusal, in the editor's terms. For surfacing to a person. */
+export declare function describeUnsupported(unsupported: UnsupportedChange[]): string[];

package/dist/publish/field-diff.js

@@ -0,0 +1,252 @@
+/**
+ * Publishing an edited page back to a CMS, as a field-level diff.
+ *
+ * `onPublish(pages, config)` means "here are the full PageDocs, store them".
+ * That is implementable when the CMS shape *is* the editor shape — a JSON file
+ * — and not otherwise. Every real CMS read is a projection: an asset reference
+ * flattened to a URL string, a document reference resolved to an href for one
+ * language, a rich-text tree flattened to markdown. Writing the projection back
+ * replaces the reference with the flattening and destroys the document.
+ *
+ * So a real integration publishes a diff: walk the same field specs used to
+ * project, compare each field against the value it was projected from, and emit
+ * a set at the key-addressed path that owns it. The first integration to do
+ * this hand-wrote about 230 lines of it. This is that shape, generalised, so
+ * the next one does not.
+ *
+ * **What is here and what is not.** The mechanism is general: the walk, the
+ * unchanged-field skip, list items matched on a stable key rather than an
+ * index, routing a block's patches to a document other than the page's, and the
+ * vocabulary for reporting a change that cannot be expressed. The *inversions*
+ * are not, and cannot be — `rehydrate` undoes a projection only the integration
+ * knows it made. Neither is uploading an asset or re-resolving a reference;
+ * those are per-CMS capabilities, and until an integration has them the honest
+ * answer is `unsupported`, which is why that is a first-class result here
+ * rather than a thrown error.
+ */
+/**
+ * Sanity addresses array elements by `_key`, never by index — an index-addressed
+ * patch races any concurrent edit that reorders the array.
+ */
+export const sanityPaths = {
+    field: (prefix, field) => `${prefix}${field}`,
+    item: (prefix, field, key) => `${prefix}${field}[_key=="${key}"]`
+};
+/**
+ * Index addressing, for stores that have no element identity (Strapi component
+ * lists, a plain JSON array). Correct only when the publish is the only writer:
+ * anything that reorders between read and write silently patches the wrong row,
+ * which is exactly what `_key` exists to prevent.
+ */
+export const indexPaths = {
+    field: (prefix, field) => `${prefix}${field}`,
+    item: (prefix, field, _key, index) => `${prefix}${field}[${index}]`
+};
+/** Structural equality, for "did this field actually change". */
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || a === undefined || b === null || b === undefined) {
+        return (a === null || a === undefined) && (b === null || b === undefined);
+    }
+    if (typeof a !== "object" || typeof b !== "object")
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    const ak = Object.keys(a);
+    const bk = Object.keys(b);
+    if (ak.length !== bk.length)
+        return false;
+    return ak.every((k) => deepEqual(a[k], b[k]));
+}
+function defaultItemKey(item) {
+    const key = item._key ?? item._id ?? item.id;
+    return typeof key === "string" && key.length > 0 ? key : undefined;
+}
+/**
+ * Diff one object's fields against the source it was projected from.
+ *
+ * `props` is what the editor holds; `source` is what the CMS holds. Recurses
+ * into list fields, matching items on their own key so a reorder upstream
+ * cannot make a patch land on the wrong row.
+ */
+export function diffFields(args) {
+    const paths = args.paths ?? sanityPaths;
+    const prefix = args.prefix ?? "";
+    const patches = [];
+    const unsupported = [];
+    const emit = (path, value) => patches.push({ documentId: args.documentId, path, value });
+    const reject = (where) => (change, remedy) => unsupported.push({ where, change, ...(remedy ? { remedy } : {}) });
+    for (const [name, spec] of Object.entries(args.specs)) {
+        const field = spec.cmsKey ?? name;
+        const before = args.source?.[name];
+        const after = spec.rehydrate(args.props, before, args.ctx);
+        if (deepEqual(before, after))
+            continue;
+        const path = paths.field(prefix, field);
+        if (spec.itemFields) {
+            const nested = diffList({
+                spec,
+                before,
+                after,
+                rows: args.props[name],
+                ctx: args.ctx,
+                documentId: args.documentId,
+                prefix,
+                field,
+                name,
+                where: args.where,
+                paths
+            });
+            patches.push(...nested.patches);
+            unsupported.push(...nested.unsupported);
+            continue;
+        }
+        if (typeof spec.write === "function") {
+            spec.write({ before, after, path, where: args.where, ctx: args.ctx, emit, reject: reject(args.where) });
+            continue;
+        }
+        emit(path, after);
+    }
+    return { patches, unsupported };
+}
+/**
+ * Cards, tiers, accordion rows — recursed into and matched on the item's own
+ * key.
+ *
+ * An item without one cannot be addressed, which is exactly the case of a row
+ * the editor added: the CMS has never seen it and has no key to patch. Adding
+ * and removing rows is a document-shaped write, not a field-shaped one, so it
+ * is reported rather than attempted.
+ */
+function diffList(args) {
+    const itemFields = args.spec.itemFields;
+    if (!itemFields)
+        return { patches: [], unsupported: [] };
+    const previous = Array.isArray(args.before) ? args.before : [];
+    const next = Array.isArray(args.after) ? args.after : [];
+    const rows = Array.isArray(args.rows) ? args.rows : [];
+    const keyOf = args.spec.itemKey ?? defaultItemKey;
+    const patches = [];
+    const unsupported = [];
+    if (previous.length !== next.length) {
+        unsupported.push({
+            where: args.where,
+            change: `items were added to or removed from "${args.name}"`,
+            remedy: "Only edits to existing items publish as a field diff; the list's length is a document-level change."
+        });
+    }
+    const byKey = new Map();
+    for (const entry of previous) {
+        const key = keyOf(entry);
+        if (key)
+            byKey.set(key, entry);
+    }
+    next.forEach((entry, index) => {
+        const key = keyOf(entry);
+        const was = key ? byKey.get(key) : undefined;
+        if (!key || !was) {
+            unsupported.push({
+                where: args.where,
+                change: `a new item in "${args.name}" cannot be published`,
+                remedy: "It has no upstream key, so there is no path to patch. Create it in the CMS first."
+            });
+            return;
+        }
+        const nested = diffFields({
+            specs: itemFields,
+            props: rows[index] ?? {},
+            source: was,
+            ctx: args.ctx,
+            documentId: args.documentId,
+            prefix: `${args.paths.item(args.prefix, args.field, key, index)}.`,
+            where: args.where,
+            paths: args.paths
+        });
+        patches.push(...nested.patches);
+        unsupported.push(...nested.unsupported);
+    });
+    return { patches, unsupported };
+}
+/**
+ * Fold a flat patch list into one `set` object per document.
+ *
+ * Most CMS clients take a single patch per document rather than one per field,
+ * and a caller that concatenates diffs from several blocks will have several
+ * entries for the same document. Documents with nothing to set are dropped, so
+ * an unchanged page issues no write at all.
+ */
+export function groupPatches(patches) {
+    const byDocument = new Map();
+    for (const patch of patches) {
+        let set = byDocument.get(patch.documentId);
+        if (!set) {
+            set = {};
+            byDocument.set(patch.documentId, set);
+        }
+        set[patch.path] = patch.value;
+    }
+    return [...byDocument.entries()]
+        .filter(([, set]) => Object.keys(set).length > 0)
+        .map(([documentId, set]) => ({ documentId, set }));
+}
+/** Merge diffs from several blocks or pages into one. */
+export function mergeDiffs(diffs) {
+    return {
+        patches: diffs.flatMap((d) => d.patches),
+        unsupported: diffs.flatMap((d) => d.unsupported)
+    };
+}
+/**
+ * Diff every block on a page.
+ *
+ * The routing decision stays with the integration — `locate` is where a block
+ * placed by a shared section writes to the *section* document rather than the
+ * page, and where a per-placement heading override stays page-local. Only the
+ * integration knows its own document graph. What is owned here is the loop, the
+ * report for a block with nowhere to write, and the `where` string a person has
+ * to be able to recognise.
+ *
+ * Returning `null` from `locate` reports the block as unpublishable rather than
+ * skipping it silently. That is almost always a block the editor added: the CMS
+ * has no document behind it, so there is no path to patch, and a publisher that
+ * quietly dropped it would report success for content the site will never show.
+ */
+export function diffPage(args) {
+    const nameOf = args.where ?? ((slug, block) => `${slug} → ${block.type}`);
+    const diffs = [];
+    for (const block of args.page.blocks) {
+        const where = nameOf(args.page.slug, block);
+        const located = args.locate(block);
+        if (!located) {
+            diffs.push({
+                patches: [],
+                unsupported: [
+                    {
+                        where,
+                        change: `a new "${block.type}" block was added`,
+                        remedy: "There is no upstream document behind it to patch. Create the block in the CMS first."
+                    }
+                ]
+            });
+            continue;
+        }
+        for (const target of Array.isArray(located) ? located : [located]) {
+            diffs.push(diffFields({
+                specs: target.specs,
+                props: block.props ?? {},
+                source: target.source,
+                ctx: args.ctx,
+                documentId: target.documentId,
+                prefix: target.prefix,
+                where,
+                paths: args.paths
+            }));
+        }
+    }
+    return mergeDiffs(diffs);
+}
+/** One line per refusal, in the editor's terms. For surfacing to a person. */
+export function describeUnsupported(unsupported) {
+    return unsupported.map((u) => `${u.where}: ${u.change}${u.remedy ? ` — ${u.remedy}` : ""}`);
+}

package/dist/publish/field-diff.test.d.ts

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