@avocadostudio-ai/site-sdk 0.7.0 → 0.9.0

package/dist/page-metadata.test.js

@@ -1,105 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-import { buildPageMetadata, derivePageDescription, derivePageTitle, stripMarkdown, truncateForMeta } from "./page-metadata.js";
-const basePage = {
-    id: "p_test",
-    slug: "/test",
-    title: "Test Page",
-    updatedAt: "2026-03-13T00:00:00.000Z",
-    blocks: [],
-};
-test("derivePageDescription prefers an explicit description", () => {
-    const page = { ...basePage, meta: { description: "Explicit description for search snippets." } };
-    assert.equal(derivePageDescription(page), "Explicit description for search snippets.");
-});
-test("derivePageDescription falls back to the first block that reads like prose", () => {
-    const page = {
-        ...basePage,
-        blocks: [
-            { id: "b0", type: "Hero", props: { heading: "Avocados" } },
-            { id: "b1", type: "Hero", props: { subheading: "Learn how to pick, store, and prepare avocados quickly." } },
-        ],
-    };
-    assert.match(derivePageDescription(page), /pick, store, and prepare avocados quickly/i);
-});
-test("derivePageDescription skips block text too short to be a summary", () => {
-    const page = {
-        ...basePage,
-        blocks: [{ id: "b1", type: "CTA", props: { text: "Buy now" } }],
-    };
-    // "Buy now" is a label, not a description — the generated fallback wins.
-    assert.match(derivePageDescription(page), /^Test Page\./);
-});
-test("derivePageDescription strips markdown and caps length", () => {
-    const page = {
-        ...basePage,
-        blocks: [
-            {
-                id: "b2",
-                type: "RichText",
-                props: {
-                    body: "# Title\n\nThis is **a long markdown description** with [a link](https://example.com) that should be normalized and capped to a search-friendly length without weird symbols lingering around.",
-                },
-            },
-        ],
-    };
-    const description = derivePageDescription(page);
-    assert.ok(description.length <= 161, `too long: ${description.length}`);
-    assert.equal(description.includes("**"), false);
-    assert.equal(description.includes("[a link]"), false);
-    /*
-     * The words have to survive, not just the brackets. Asserting only that
-     * "[a link]" is gone passed while the replacement wrote a literal `$1` over
-     * the link text, because the pattern it referred to had no capture group.
-     */
-    assert.ok(description.includes("a link"), `link text was dropped: ${description}`);
-    assert.equal(description.includes("$1"), false, `replacement token leaked: ${description}`);
-});
-test("stripMarkdown keeps link text and drops the target", () => {
-    assert.equal(stripMarkdown("Book a [guided tour](/tours) with our team."), "Book a guided tour with our team.");
-    // An image has no text worth keeping — alt text describes the picture, not
-    // the sentence — so it goes entirely rather than leaving its alt behind.
-    assert.equal(stripMarkdown("Before ![a photo](/p.png) after."), "Before after.");
-});
-test("truncateForMeta ends in exactly one period", () => {
-    const cutAfterASentence = `${"A".repeat(100)} end of the first sentence here. ${"B".repeat(80)}`;
-    const out = truncateForMeta(cutAfterASentence);
-    assert.equal(out.endsWith(".."), false, `doubled the period: ${JSON.stringify(out.slice(-20))}`);
-    assert.equal(out.endsWith("."), true);
-    assert.ok(out.length <= 161, `too long: ${out.length}`);
-});
-test("derivePageDescription never returns empty", () => {
-    assert.ok(derivePageDescription(basePage).length > 0);
-});
-test("derivePageTitle prefers meta.title over the document title", () => {
-    assert.equal(derivePageTitle(basePage), "Test Page");
-    assert.equal(derivePageTitle({ ...basePage, meta: { title: "SEO Title" } }), "SEO Title");
-    // An all-whitespace meta title is not a title.
-    assert.equal(derivePageTitle({ ...basePage, meta: { title: "   " } }), "Test Page");
-});
-test("buildPageMetadata emits title, description and Open Graph", () => {
-    const meta = buildPageMetadata({ ...basePage, meta: { description: "A page about avocados and how to eat them." } });
-    assert.equal(meta.title, "Test Page");
-    assert.equal(meta.description, "A page about avocados and how to eat them.");
-    assert.equal(meta.openGraph?.title, "Test Page");
-    assert.equal(meta.openGraph?.description, "A page about avocados and how to eat them.");
-    assert.equal(meta.openGraph?.type, "website");
-});
-test("buildPageMetadata only claims a large image card when there is an image", () => {
-    const without = buildPageMetadata(basePage);
-    assert.equal(without.openGraph?.images, undefined);
-    assert.equal(without.twitter?.card, undefined);
-    const with_ = buildPageMetadata({ ...basePage, meta: { ogImage: "https://cdn.example.com/og.png" } });
-    assert.deepEqual(with_.openGraph?.images, ["https://cdn.example.com/og.png"]);
-    assert.equal(with_.twitter?.card, "summary_large_image");
-    assert.deepEqual(with_.twitter?.images, ["https://cdn.example.com/og.png"]);
-});
-test("buildPageMetadata carries siteName and canonical when given", () => {
-    const meta = buildPageMetadata(basePage, { siteName: "Avocado Co", canonical: "https://example.com/test" });
-    assert.equal(meta.openGraph?.siteName, "Avocado Co");
-    assert.equal(meta.openGraph?.url, "https://example.com/test");
-    assert.equal(meta.alternates?.canonical, "https://example.com/test");
-    const bare = buildPageMetadata(basePage);
-    assert.equal(bare.alternates, undefined);
-    assert.equal(bare.openGraph?.siteName, undefined);
-});

package/dist/proxy.test.d.ts

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

package/dist/proxy.test.js

@@ -1,182 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-import { NextRequest, NextResponse } from "next/server";
-import { buildEditorMatcher, createEditorProxy, editorPreviewRewrite, trailingSlashRedirect, 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`);
-});
-/*
- * `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");
-});
-/*
- * The two halves, on their own.
- *
- * A site that already has a `middleware.ts` cannot hand the whole file to
- * `createEditorProxy` and has to compose — which until now meant re-deriving
- * the trailing-slash redirect from the docs. One integration did, and wrote
- * `request.nextUrl.clone()`, because that is what every Next example uses for
- * a URL you intend to modify. A `NextURL` re-applies trailing-slash
- * normalisation when it serialises, so the redirect stripped the slash it had
- * just added and pointed at the URL it came from: every page on the site in an
- * infinite redirect, reproducing only in a browser. `curl` without `-L` sees
- * one perfectly ordinary 308, which is how it survived a session and a half.
- */
-test("the redirect is built from request.url, not from a NextURL that would undo it", () => {
-    const response = trailingSlashRedirect(request("https://site.test/bern"));
-    assert.equal(response?.status, 308);
-    assert.equal(response?.headers.get("location"), "https://site.test/bern/", "a location without the slash is the loop: the browser asks again and gets the same answer");
-});
-test("an already-canonical URL, the root, and a file are left alone", () => {
-    assert.equal(trailingSlashRedirect(request("https://site.test/bern/")), null);
-    assert.equal(trailingSlashRedirect(request("https://site.test/")), null, "redirecting / never terminates");
-    assert.equal(trailingSlashRedirect(request("https://site.test/logo.svg")), null);
-});
-test("the API routes are never redirected, whatever the caller's matcher says", () => {
-    /*
-     * The proxy's own matcher excludes these, but a hand-composed middleware
-     * brings its own matcher and it is usually wider. A slash added here
-     * re-creates by hand the exact 308 on `/api/editor/*` that
-     * `skipTrailingSlashRedirect` was turned on to stop — and the symptom is a
-     * CORS error that names nothing.
-     */
-    assert.equal(trailingSlashRedirect(request("https://site.test/api/editor/blocks")), null);
-    assert.equal(trailingSlashRedirect(request("https://site.test/_next/static/chunk")), null);
-});
-test("the redirect keeps the query string when called directly too", () => {
-    const response = trailingSlashRedirect(request("https://site.test/bern?__editor=1"));
-    assert.equal(response?.headers.get("location"), "https://site.test/bern/?__editor=1");
-});
-test("editorPreviewRewrite answers null for a visitor, so the caller runs its own middleware", () => {
-    assert.equal(editorPreviewRewrite(request("https://site.test/about")), null, "null is 'not mine', not 'pass this through' — a composing caller has its own work to do");
-    assert.equal(rewriteOf(editorPreviewRewrite(request("https://site.test/about?__editor=1"))), "https://site.test/preview-draft/about?__editor=1");
-});
-test("the composed form behaves like the factory it was extracted from", () => {
-    const { proxy } = createEditorProxy({ trailingSlash: true });
-    const compose = (r) => trailingSlashRedirect(r) ?? editorPreviewRewrite(r) ?? NextResponse.next();
-    for (const url of [
-        "https://site.test/bern",
-        "https://site.test/bern/",
-        "https://site.test/bern?__editor=1",
-        "https://site.test/bern/?__editor=1",
-        "https://site.test/"
-    ]) {
-        const fromFactory = proxy(request(url));
-        const fromParts = compose(request(url));
-        assert.equal(fromParts.status, fromFactory.status, url);
-        assert.equal(fromParts.headers.get("location"), fromFactory.headers.get("location"), url);
-        assert.equal(rewriteOf(fromParts), rewriteOf(fromFactory), url);
-    }
-});

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

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

package/dist/publish/field-diff.test.js

@@ -1,350 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { diffFields, diffPage, groupPatches, mergeDiffs, describeUnsupported, deepEqual, sanityPaths, indexPaths } from "./field-diff.js";
-const ctx = { lang: "de" };
-/** The common case: the prop is the field, and the value round-trips. */
-const plain = (key) => ({
-    rehydrate: (props) => props[key]
-});
-test("an unchanged field emits nothing", () => {
-    const specs = { heading: plain("heading") };
-    const diff = diffFields({
-        specs,
-        props: { heading: "Same" },
-        source: { heading: "Same" },
-        ctx,
-        documentId: "doc1",
-        where: "/ → hero",
-        paths: sanityPaths
-    });
-    assert.deepEqual(diff.patches, []);
-    assert.deepEqual(diff.unsupported, []);
-});
-test("a changed field is set at the path that owns it", () => {
-    const diff = diffFields({
-        specs: { heading: plain("heading") },
-        props: { heading: "After" },
-        source: { heading: "Before" },
-        ctx,
-        documentId: "doc1",
-        prefix: 'pageBuilder[_key=="b1"].',
-        where: "/ → hero",
-        paths: sanityPaths
-    });
-    assert.deepEqual(diff.patches, [
-        { documentId: "doc1", path: 'pageBuilder[_key=="b1"].heading', value: "After" }
-    ]);
-});
-test("cmsKey writes to the field the CMS actually has", () => {
-    const diff = diffFields({
-        specs: { heading: { ...plain("heading"), cmsKey: "headingOverride" } },
-        props: { heading: "After" },
-        // Keyed the way the CMS keys it. The version of this test that wrote
-        // `{ heading: "Before" }` passed against the bug below, because a baseline
-        // of `undefined` also produces a patch at the right path.
-        source: { headingOverride: "Before" },
-        ctx,
-        documentId: "doc1",
-        where: "/ → hero",
-        paths: sanityPaths
-    });
-    assert.deepEqual(diff.patches, [
-        { documentId: "doc1", path: "headingOverride", value: "After" }
-    ]);
-});
-test("an unchanged cmsKey field emits nothing", () => {
-    // The regression this file exists for. `diffFields` read the baseline from
-    // the *props* key while pathing the patch from `cmsKey`, so every spec that
-    // used the option compared its value against `undefined` and republished it
-    // on every publish, edited or not.
-    const diff = diffFields({
-        specs: { heading: { ...plain("heading"), cmsKey: "headingOverride" } },
-        props: { heading: "Same" },
-        source: { headingOverride: "Same" },
-        ctx,
-        documentId: "doc1",
-        where: "/ → hero",
-        paths: sanityPaths
-    });
-    assert.deepEqual(diff.patches, []);
-});
-test("a cmsKey spec's rehydrate receives the value the CMS holds", () => {
-    // Partial inversion is the whole point of passing `before`: return the stored
-    // object with one key replaced and everything the projection dropped
-    // survives. Hand `rehydrate` an `undefined` and it has nothing to merge into,
-    // so the patch overwrites instead of editing.
-    const seen = [];
-    const diff = diffFields({
-        specs: {
-            alt: {
-                cmsKey: "image",
-                rehydrate: (props, before) => {
-                    seen.push(before);
-                    return { ...before, alt: props.alt };
-                }
-            }
-        },
-        props: { alt: "A team in action" },
-        source: { image: { _type: "image", asset: { _ref: "image-abc" }, alt: "Old" } },
-        ctx,
-        documentId: "doc1",
-        where: "/ → hero",
-        paths: sanityPaths
-    });
-    assert.deepEqual(seen, [{ _type: "image", asset: { _ref: "image-abc" }, alt: "Old" }]);
-    assert.deepEqual(diff.patches, [
-        {
-            documentId: "doc1",
-            path: "image",
-            value: { _type: "image", asset: { _ref: "image-abc" }, alt: "A team in action" }
-        }
-    ]);
-});
-test("rehydrate receives the stored value, so an inversion can be partial", () => {
-    // The whole reason a snapshot contract cannot work: the editor saw
-    // `image.url`, the CMS holds an asset reference beside it, and only the
-    // integration knows how to put one back without destroying the other.
-    const specs = {
-        image: {
-            rehydrate: (props, before) => ({
-                ...before,
-                alt: props.imageAlt ?? undefined
-            })
-        }
-    };
-    const diff = diffFields({
-        specs,
-        props: { imageAlt: "New alt" },
-        source: { image: { _type: "image", asset: { _ref: "image-abc" }, alt: "Old alt" } },
-        ctx,
-        documentId: "doc1",
-        where: "/ → hero",
-        paths: sanityPaths
-    });
-    assert.deepEqual(diff.patches[0].value, {
-        _type: "image",
-        asset: { _ref: "image-abc" },
-        alt: "New alt"
-    });
-});
-// ---------------------------------------------------------------------------
-// The refusals
-// ---------------------------------------------------------------------------
-test("refusal 1 — a projection that cannot be inverted is reported, not guessed", () => {
-    const specs = {
-        image: {
-            rehydrate: (props, before) => ({ ...before, url: props.imageUrl }),
-            write: ({ before, after, emit, reject, path }) => {
-                const was = before;
-                const now = after;
-                if (was?.alt !== now.alt)
-                    emit(`${path}.alt`, now.alt);
-                if (was?.url !== now.url) {
-                    reject(`the image was replaced (${now.url})`, "The CMS stores an asset reference; the file has to be uploaded first.");
-                }
-            }
-        }
-    };
-    const diff = diffFields({
-        specs,
-        props: { imageUrl: "https://example.com/new.png" },
-        source: { image: { url: "https://cdn.example.com/old.png", alt: "Old" } },
-        ctx,
-        documentId: "doc1",
-        where: "/ → hero",
-        paths: sanityPaths
-    });
-    assert.deepEqual(diff.patches, [], "nothing may be written for a value that cannot be expressed");
-    assert.equal(diff.unsupported.length, 1);
-    assert.match(diff.unsupported[0].change, /image was replaced/);
-    assert.match(String(diff.unsupported[0].remedy), /uploaded first/);
-});
-test("refusal 2 — adding or removing list items is a document-shaped change", () => {
-    const specs = {
-        cards: {
-            rehydrate: (props) => props.cards,
-            itemFields: { title: plain("title") }
-        }
-    };
-    const diff = diffFields({
-        specs,
-        props: { cards: [{ _key: "k1", title: "One" }, { _key: "k2", title: "Two" }] },
-        source: { cards: [{ _key: "k1", title: "One" }] },
-        ctx,
-        documentId: "doc1",
-        where: "/ → cardGrid",
-        paths: sanityPaths
-    });
-    assert.ok(diff.unsupported.some((u) => /added to or removed/.test(u.change)));
-});
-test("refusal 3 — an item the CMS has never seen has no path to patch", () => {
-    const specs = {
-        cards: {
-            rehydrate: (props) => props.cards,
-            itemFields: { title: plain("title") }
-        }
-    };
-    const diff = diffFields({
-        specs,
-        props: { cards: [{ _key: "k1", title: "One" }, { title: "Brand new" }] },
-        source: { cards: [{ _key: "k1", title: "One" }, { _key: "k2", title: "Two" }] },
-        ctx,
-        documentId: "doc1",
-        where: "/ → cardGrid",
-        paths: sanityPaths
-    });
-    assert.ok(diff.unsupported.some((u) => /new item/.test(u.change)));
-    assert.ok(!diff.patches.some((p) => p.value === "Brand new"), "a keyless item must not be written to whatever path happens to be at its index");
-});
-test("refusal 4 — a block with no upstream document is reported, never skipped", () => {
-    const diff = diffPage({
-        page: {
-            slug: "/prices",
-            blocks: [{ id: "b_new", type: "pba_pricingSection", props: { heading: "Hi" } }]
-        },
-        ctx,
-        paths: sanityPaths,
-        locate: () => null
-    });
-    assert.deepEqual(diff.patches, []);
-    assert.equal(diff.unsupported.length, 1);
-    assert.match(diff.unsupported[0].change, /new "pba_pricingSection" block/);
-    assert.equal(diff.unsupported[0].where, "/prices → pba_pricingSection");
-});
-// ---------------------------------------------------------------------------
-// Lists, keys, and the reason index addressing is not the default
-// ---------------------------------------------------------------------------
-test("a list item is patched at its own key, not at its position", () => {
-    const specs = {
-        cards: {
-            rehydrate: (props) => props.cards,
-            itemFields: { title: plain("title") }
-        }
-    };
-    // The upstream order is the reverse of the editor's. Index addressing would
-    // write "Renamed" onto the wrong card.
-    const diff = diffFields({
-        specs,
-        props: { cards: [{ _key: "k2", title: "Renamed" }, { _key: "k1", title: "One" }] },
-        source: { cards: [{ _key: "k1", title: "One" }, { _key: "k2", title: "Two" }] },
-        ctx,
-        documentId: "doc1",
-        where: "/ → cardGrid",
-        paths: sanityPaths
-    });
-    assert.deepEqual(diff.patches, [
-        { documentId: "doc1", path: 'cards[_key=="k2"].title', value: "Renamed" }
-    ]);
-});
-test("index addressing is available and says what it costs", () => {
-    const specs = {
-        rows: {
-            rehydrate: (props) => props.rows,
-            itemFields: { label: plain("label") },
-            itemKey: (item) => String(item.id)
-        }
-    };
-    const diff = diffFields({
-        specs,
-        props: { rows: [{ id: "7", label: "After" }] },
-        source: { rows: [{ id: "7", label: "Before" }] },
-        ctx,
-        documentId: "doc1",
-        where: "/ → table",
-        paths: indexPaths
-    });
-    assert.deepEqual(diff.patches, [{ documentId: "doc1", path: "rows[0].label", value: "After" }]);
-});
-test("a custom itemKey identifies items that have no _key", () => {
-    const specs = {
-        rows: {
-            rehydrate: (props) => props.rows,
-            itemFields: { label: plain("label") },
-            itemKey: (item) => (typeof item.id === "string" ? item.id : undefined)
-        }
-    };
-    const diff = diffFields({
-        specs,
-        props: { rows: [{ id: "r1", label: "After" }] },
-        source: { rows: [{ id: "r1", label: "Before" }] },
-        ctx,
-        documentId: "doc1",
-        where: "/ → table",
-        paths: sanityPaths
-    });
-    assert.deepEqual(diff.patches, [
-        { documentId: "doc1", path: 'rows[_key=="r1"].label', value: "After" }
-    ]);
-});
-// ---------------------------------------------------------------------------
-// Routing across documents
-// ---------------------------------------------------------------------------
-test("one block can write to two documents", () => {
-    // A block placed by a shared section: its heading override belongs to the
-    // page, the rest of it belongs to the section every page shares.
-    const diff = diffPage({
-        page: {
-            slug: "/",
-            blocks: [{ id: "b1", type: "sharedSection", props: { heading: "Page heading", body: "Shared body" } }]
-        },
-        ctx,
-        paths: sanityPaths,
-        locate: () => [
-            {
-                documentId: "page-1",
-                prefix: 'pageBuilder[_key=="b1"].',
-                specs: { heading: { ...plain("heading"), cmsKey: "headingOverride" } },
-                source: { headingOverride: "Old page heading" }
-            },
-            {
-                documentId: "section-9",
-                prefix: "content[0].",
-                specs: { body: plain("body") },
-                source: { body: "Old shared body" }
-            }
-        ]
-    });
-    assert.deepEqual(groupPatches(diff.patches), [
-        { documentId: "page-1", set: { 'pageBuilder[_key=="b1"].headingOverride': "Page heading" } },
-        { documentId: "section-9", set: { "content[0].body": "Shared body" } }
-    ]);
-});
-test("a page with nothing changed issues no write at all", () => {
-    const diff = diffPage({
-        page: { slug: "/", blocks: [{ id: "b1", type: "hero", props: { heading: "Same" } }] },
-        ctx,
-        paths: sanityPaths,
-        locate: () => ({
-            documentId: "page-1",
-            prefix: "",
-            specs: { heading: plain("heading") },
-            source: { heading: "Same" }
-        })
-    });
-    assert.deepEqual(groupPatches(diff.patches), [], "an unchanged publish must not touch the CMS");
-});
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-test("deepEqual treats null and undefined as the same absence", () => {
-    // A CMS that omits an empty field and an editor that sends `undefined` are
-    // saying the same thing; treating them as a change rewrites every optional
-    // field on every publish.
-    assert.ok(deepEqual(null, undefined));
-    assert.ok(deepEqual({ a: [1, { b: "c" }] }, { a: [1, { b: "c" }] }));
-    assert.ok(!deepEqual({ a: 1 }, { a: 1, b: 2 }));
-    assert.ok(!deepEqual([1, 2], { 0: 1, 1: 2 }));
-});
-test("mergeDiffs and describeUnsupported produce something a person can read", () => {
-    const merged = mergeDiffs([
-        { patches: [{ documentId: "d", path: "a", value: 1 }], unsupported: [] },
-        {
-            patches: [],
-            unsupported: [{ where: "/ → hero", change: "the image was replaced", remedy: "Upload it first." }]
-        }
-    ]);
-    assert.equal(merged.patches.length, 1);
-    assert.deepEqual(describeUnsupported(merged.unsupported), [
-        "/ → hero: the image was replaced — Upload it first."
-    ]);
-});