@capacms/sdk 1.0.0-next.1 → 1.0.0-next.10

package/dist/nextjs/index.js

@@ -1,13 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DRAFT_COOKIE_MAX_AGE = exports.DRAFT_ROBOTS_TAG = exports.CAPA_ADMIN_ORIGIN = exports.DEFAULT_API_VERSION = exports.CAPA_ENV_ALIASES = exports.CAPA_ENV = exports.EDIT_CACHE_CONTROL = exports.DRAFT_COOKIE = exports.EDIT_HEADER = exports.VIEW_PARAM = exports.PREVIEW_PARAM = exports.EDIT_PARAM = exports.createCapaImageLoader = exports.capaImageLoader = exports.LAYOUT_PAGE = exports.gql = exports.MEDIA_TAG = exports.GRAPHQL_TAG = void 0;
 exports.withCache = withCache;
+exports.modelTag = modelTag;
 exports.tagsFor = tagsFor;
 exports.revalidateFromWebhook = revalidateFromWebhook;
 exports.draftClient = draftClient;
 exports.routeOf = routeOf;
 exports.preview = preview;
 exports.pagesFor = pagesFor;
+exports.editMode = editMode;
+exports.resolveEditRequest = resolveEditRequest;
+exports.getPublishedClient = getPublishedClient;
+exports.getCapaClient = getCapaClient;
+exports.graphql = graphql;
+exports.safeSitePath = safeSitePath;
+exports.frameAncestors = frameAncestors;
+exports.draftHeaders = draftHeaders;
+exports.capaHeaders = capaHeaders;
+exports.frameDraftCookie = frameDraftCookie;
+exports.clearDraftCookie = clearDraftCookie;
+exports.createPreviewRoute = createPreviewRoute;
+exports.exitPreviewRoute = exitPreviewRoute;
+exports.capaMiddleware = capaMiddleware;
 const next_1 = require("../next");
+Object.defineProperty(exports, "gql", { enumerable: true, get: function () { return next_1.gql; } });
+Object.defineProperty(exports, "LAYOUT_PAGE", { enumerable: true, get: function () { return next_1.LAYOUT_PAGE; } });
+const client_1 = require("../next/client");
+const sha256_1 = require("../next/graphql/sha256");
+const key_family_1 = require("../next/key-family");
 /** Add Next.js fetch-cache options without importing `next/*`. */
 function withCache(fetchImpl, options) {
     return (async (input, init = {}) => {
@@ -21,6 +42,39 @@ function withCache(fetchImpl, options) {
         return fetchImpl(input, { ...init, next });
     });
 }
+/**
+ * The Next.js cache tag for every read of a model, by its namespace. A GraphQL
+ * query names its models by namespace (`articles`), not by id, so this is the
+ * tag a GraphQL read is cached under, and `revalidateFromWebhook` revalidates
+ * it when an entry of that model changes.
+ */
+function modelTag(namespace) {
+    return `capa:model:${namespace}`;
+}
+/**
+ * The tag `graphql()` keeps a read under when it gives a `revalidate` and no
+ * `tags`, and that `revalidateFromWebhook` revalidates on every content
+ * change: such a page is never stale after a publish, at the price of
+ * refreshing on any publish. Name the models it reads with
+ * `tagsFor({ namespace })` to refresh it only when one of those changes. A
+ * read with neither `tags` nor `revalidate` is not kept at all.
+ */
+exports.GRAPHQL_TAG = "capa:graphql";
+/**
+ * The tag `tagsFor({ namespace })` adds beside its model tags, and that
+ * `revalidateFromWebhook` revalidates on a media event: a GraphQL read shows
+ * a file's URL and alt text whichever models it names, so editing a file in
+ * the media library refreshes it.
+ */
+exports.MEDIA_TAG = "capa:media";
+/**
+ * Next.js cache tags for a read. `model`, `entry`, `key` and `tenant` are the
+ * API's surrogate keys (`m:`, `e:`, `k:`, `t:`), by id; `namespace` is one
+ * `capa:model:<namespace>` tag per model a GraphQL query reads, which
+ * `capa-codegen --graphql` lists as `<Name>Models`, and `MEDIA_TAG`, since
+ * the query may show a file from the media library. Each pairs with
+ * `revalidateFromWebhook`.
+ */
 function tagsFor(input) {
     const tags = [];
     if (input.model)
@@ -31,9 +85,26 @@ function tagsFor(input) {
         tags.push(`k:${input.key}`);
     if (input.tenant)
         tags.push(`t:${input.tenant}`);
+    const namespaces = typeof input.namespace === "string" ? [input.namespace] : (input.namespace ?? []);
+    for (const namespace of namespaces)
+        if (namespace)
+            tags.push(modelTag(namespace));
+    if (namespaces.some(Boolean))
+        tags.push(exports.MEDIA_TAG);
     return tags;
 }
-/** Revalidate the concrete entry and model identities carried by a webhook. */
+/**
+ * Revalidate every tag a webhook's entry and model can be cached under: the
+ * entry (`e:`), the model by id (`m:`) and by namespace (`capa:model:`, the
+ * tag a GraphQL read uses). The namespace is `data.modelNamespace` on
+ * `instance.published`, `instance.unpublished` and `model.published`, and
+ * `data.namespace` on the other events (docs/WEBHOOKS.md). Any of those, and
+ * a `media.` event, also revalidates `GRAPHQL_TAG`, the tag of a `graphql()`
+ * read that named no tags. A `media.` event (a file's alt text, name or
+ * visibility changed, or the file went) revalidates the file's own key
+ * (`f:<fileId>`, as REST's `Surrogate-Key` names it) and `MEDIA_TAG`, which
+ * every read tagged by namespace carries, since it may show that file.
+ */
 async function revalidateFromWebhook(input) {
     const data = input.payload?.data ?? input.payload;
     const tags = [];
@@ -42,14 +113,34 @@ async function revalidateFromWebhook(input) {
         tags.push(`e:${entryId}`);
     if (typeof data?.modelId === "string" && data.modelId)
         tags.push(`m:${data.modelId}`);
+    const namespace = data?.modelNamespace ?? data?.namespace;
+    if (typeof namespace === "string" && namespace)
+        tags.push(modelTag(namespace));
+    const media = typeof input.payload?.type === "string" && input.payload.type.startsWith("media.");
+    if (media) {
+        if (typeof data?.fileId === "string" && data.fileId)
+            tags.push(`f:${data.fileId}`);
+        tags.push(exports.MEDIA_TAG);
+    }
+    if (tags.length > 0 || media)
+        tags.push(exports.GRAPHQL_TAG);
     const unique = [...new Set(tags)];
     for (const tag of unique)
         await input.revalidateTag(tag);
     return unique;
 }
-/** Select a client using server-only draft state supplied by the caller. */
+/**
+ * Select a client using server-only draft state supplied by the caller. Pass
+ * codegen's `CapaQuery` to type the builder, as with `createClient`:
+ * `draftClient<CapaQuery>({ ... })`. `production` may hold the legacy key a
+ * site already has; `draft` needs a `cap_` key, and a legacy one throws a
+ * `TypeError` when draft mode selects it.
+ */
 async function draftClient(input) {
-    return (0, next_1.createClient)((await input.isDraft()) ? input.draft : input.production);
+    if (!(await input.isDraft()))
+        return (0, next_1.createClient)(input.production);
+    (0, key_family_1.requireDraftKey)(input.draft?.apiKey, "the draft config");
+    return (0, next_1.createClient)(input.draft);
 }
 // ------------------------------------------------------------------ pages ---
 /**
@@ -64,6 +155,16 @@ async function draftClient(input) {
  *   src/app/(marketing)/pricing/page.tsx     -> /pricing
  *   pages/blog/[slug].tsx                    -> /blog/[slug]
  *   app/page.tsx                             -> /
+ *   app/layout.tsx, app/blog/template.tsx    -> (layout)
+ *
+ * A LAYOUT IS NOT A PAGE. `layout.*` and `template.*` render around every page
+ * below them, and a layout is not told which one: Next hands it no pathname.
+ * So its reads cannot be charged to the page being rendered, and charging them
+ * to the route its own file sits at is wrong: a root layout's Site singleton
+ * and nav would all be recorded as reads of `/`. `routeOf` returns
+ * `LAYOUT_PAGE` (`"(layout)"`) for these files instead, and a read that names
+ * it sends no `Capa-Page` at all. Pass `routeOf(import.meta.url)` from a layout
+ * exactly as from a page and it does the right thing.
  *
  * WHAT IS DROPPED, and why each one:
  *
@@ -74,8 +175,7 @@ async function draftClient(input) {
  *   parallel slots `@modal`               the same
  *   the `(.)` intercept marker            an intercepting route at the SAME
  *                                         level renders the segment beside it
- *   `page.*`, `layout.*`, `route.*`,      leaf files, not segments
- *   `default.*`, `template.*`
+ *   `page.*`, `route.*`, `default.*`      leaf files, not segments
  *   `index` in the pages router           the folder IS the route
  *   the extension                         never in a URL
  *
@@ -87,7 +187,9 @@ async function draftClient(input) {
  * case the message says to pass the page string yourself.
  */
 const ROUTER_ROOTS = new Set(["app", "pages"]);
-const LEAF_FILES = new Set(["page", "layout", "route", "default", "template"]);
+const LEAF_FILES = new Set(["page", "route", "default"]);
+/** Files that render around many routes, so they name none. */
+const LAYOUT_FILES = new Set(["layout", "template"]);
 /** `(..)photo`, `(..)(..)photo`, `(...)photo`: the URL is not here. */
 const OUTER_INTERCEPT = /^(\(\.\.\.\)|(\(\.\.\))+)/;
 function routeOf(file) {
@@ -131,6 +233,9 @@ function routeOf(file) {
             const dot = part.lastIndexOf(".");
             if (dot > 0)
                 part = part.slice(0, dot);
+            // Only in the app router: `pages/layout.tsx` is a page at `/layout`.
+            if (parts[rootIndex] === "app" && LAYOUT_FILES.has(part))
+                return next_1.LAYOUT_PAGE;
             if (LEAF_FILES.has(part))
                 continue;
             // The pages router: `pages/blog/index.tsx` is `/blog`.
@@ -176,3 +281,580 @@ async function preview(token, client) {
 function pagesFor(client) {
     return client.pages;
 }
+// next/image: let Capa's CDN resize. `@capacms/sdk/nextjs/image-loader` is the
+// same loader as a default export, the entry to name in `images.loaderFile`.
+var image_loader_1 = require("./image-loader");
+Object.defineProperty(exports, "capaImageLoader", { enumerable: true, get: function () { return image_loader_1.capaImageLoader; } });
+Object.defineProperty(exports, "createCapaImageLoader", { enumerable: true, get: function () { return image_loader_1.createCapaImageLoader; } });
+// -------------------------------------------------------------- edit mode ---
+/**
+ * The query parameter that turns edit mode on for one request without draft
+ * content: `?capa-edit=<token>`, where the token is a Capa preview token. The
+ * Capa editor's Published view sends it so the published page is still
+ * clickable. It never switches the site to draft data.
+ */
+exports.EDIT_PARAM = "capa-edit";
+/** The query parameter a Capa preview link carries: `?capa-preview=<token>`. */
+exports.PREVIEW_PARAM = "capa-preview";
+/** The query parameter of the editor's Published view: `?capa-view=published`. */
+exports.VIEW_PARAM = "capa-view";
+/**
+ * The request header `resolveEditRequest` sets once a `capa-edit` token has
+ * been verified, for `editMode()` to read. Any copy a browser sent is removed
+ * first, so it cannot be forged from outside.
+ */
+exports.EDIT_HEADER = "x-capa-edit";
+/** The cookie Next's `draftMode().enable()` sets. */
+exports.DRAFT_COOKIE = "__prerender_bypass";
+/** What every edit-mode response must send: never cached, never shared. */
+exports.EDIT_CACHE_CONTROL = "private, no-store";
+/**
+ * Whether this request renders in edit mode: Next draft mode is on, or the
+ * request carried a verified `capa-edit` token (see `resolveEditRequest`).
+ *
+ * Pass Next's own functions; this package imports nothing from `next`:
+ *
+ *   import { draftMode, headers } from "next/headers";
+ *   const edit = await editMode({ draftMode, headers });
+ *   const client = createClient({ ...config, editMode: edit });
+ *
+ * A client built with `editMode: edit` marks what it reads, and `capaAttrs`
+ * then tags those entries and only those.
+ */
+async function editMode(input) {
+    const [draft, headers] = await Promise.all([input.draftMode(), input.headers()]);
+    return draft.isEnabled === true || verifiedEdit(headers);
+}
+/** Whether `resolveEditRequest` verified a `capa-edit` token for this request. */
+function verifiedEdit(headers) {
+    return headers.get(exports.EDIT_HEADER) === "1";
+}
+/**
+ * The middleware half of edit mode.
+ *
+ *   export async function middleware(request: NextRequest) {
+ *     const edit = await resolveEditRequest(request, publishedClient());
+ *     const response = NextResponse.next({ request: { headers: edit.headers } });
+ *     if (edit.cacheControl) response.headers.set("Cache-Control", edit.cacheControl);
+ *     if (edit.robotsTag) response.headers.set("X-Robots-Tag", edit.robotsTag);
+ *     return response;
+ *   }
+ *
+ * The token is checked with Capa (`client.preview`), exactly as a preview link
+ * is: the site never holds the signing key. A bad, expired or unverifiable
+ * token means not in edit mode; it never throws, because a broken edit link
+ * must still render the public page.
+ */
+async function resolveEditRequest(request, client) {
+    const headers = new Headers(request.headers);
+    headers.delete(exports.EDIT_HEADER);
+    const token = new URL(String(request.url)).searchParams.get(exports.EDIT_PARAM);
+    let verified = false;
+    if (token) {
+        try {
+            verified = (await client.preview(token)) !== null;
+        }
+        catch {
+            verified = false;
+        }
+    }
+    if (verified)
+        headers.set(exports.EDIT_HEADER, "1");
+    const draft = request.cookies?.has(exports.DRAFT_COOKIE) ??
+        (headers.get("cookie") ?? "").split(/;\s*/).some((c) => c.startsWith(`${exports.DRAFT_COOKIE}=`));
+    const edit = verified || draft;
+    return {
+        edit,
+        verified,
+        headers,
+        cacheControl: edit ? exports.EDIT_CACHE_CONTROL : null,
+        robotsTag: edit ? exports.DRAFT_ROBOTS_TAG : null,
+    };
+}
+// ------------------------------------------------- five-minute integration ---
+/**
+ * Where the env-driven helpers read their settings (M6): the one pair of
+ * names the whole product uses (the MCP server, `capa-codegen`, `capa
+ * persist`, every curl example in the API docs).
+ */
+exports.CAPA_ENV = {
+    baseUrl: "CAPA_API_URL",
+    apiKey: "CAPA_KEY",
+    draftKey: "CAPA_DRAFT_KEY",
+    version: "CAPA_API_VERSION",
+};
+/** Older names that still work, read only when the name above is unset. */
+exports.CAPA_ENV_ALIASES = {
+    CAPA_API_URL: "CAPA_BASE_URL",
+    CAPA_KEY: "CAPA_API_KEY",
+};
+exports.DEFAULT_API_VERSION = "2026-10-01";
+function readOne(name) {
+    const env = globalThis.process?.env;
+    const value = env?.[name];
+    return value === undefined || value === "" ? undefined : value;
+}
+function readEnv(name) {
+    const alias = exports.CAPA_ENV_ALIASES[name];
+    return readOne(name) ?? (alias ? readOne(alias) : undefined);
+}
+function requireEnv(name) {
+    const value = readEnv(name);
+    if (value)
+        return value;
+    const alias = exports.CAPA_ENV_ALIASES[name];
+    throw new Error(`@capacms/sdk/nextjs: ${name} is not set${alias ? ` (${alias} also works)` : ""}.`);
+}
+/**
+ * A client config from env, `key` naming the env var for the key. A setting
+ * `config` gives is used as given and its env var is never read, so a full
+ * `config` needs no env at all.
+ */
+function envConfig(config, key) {
+    return {
+        ...config,
+        baseUrl: config?.baseUrl ?? requireEnv(exports.CAPA_ENV.baseUrl),
+        apiKey: config?.apiKey ?? requireEnv(key),
+        version: config?.version ?? readEnv(exports.CAPA_ENV.version) ?? exports.DEFAULT_API_VERSION,
+    };
+}
+/** The published or the draft config from env; the draft key must be a `cap_` key. */
+function modeConfig(config, draft) {
+    if (!draft)
+        return envConfig(config, exports.CAPA_ENV.apiKey);
+    const settings = envConfig(config, exports.CAPA_ENV.draftKey);
+    (0, key_family_1.requireDraftKey)(settings.apiKey, config?.apiKey !== undefined ? "config.apiKey" : exports.CAPA_ENV.draftKey);
+    return settings;
+}
+/**
+ * The published-key client from env: what verifying a token needs. `overrides`
+ * win over env, and pass codegen's `CapaQuery` to type the builder:
+ * `getPublishedClient<CapaQuery>()`.
+ */
+function getPublishedClient(overrides = {}) {
+    return (0, next_1.createClient)(envConfig(overrides, exports.CAPA_ENV.apiKey));
+}
+/**
+ * The client for this request, from env: the draft key under draft mode,
+ * otherwise the published key, and `editMode` worked out for you.
+ *
+ *   import { draftMode, headers } from "next/headers";
+ *   const capa = await getCapaClient<CapaQuery>({ draftMode, headers });
+ *   const { data } = await capa.graphql.query(selection, { tags: tagsFor({ namespace: "articles" }) });
+ *
+ * `CapaQuery` (from `capa-codegen --graphql`) types the builder, as with
+ * `createClient`; leave it out for an untyped client. `config` wins over env.
+ *
+ * Its REST reads are sent as `createClient` sends them, which Next does not
+ * keep. Its GraphQL reads, a document or the builder, are sent the same way
+ * unless a call gives `tags` or `revalidate`, so a publish shows up on both
+ * alike. Given either, a read is kept in Next's data cache exactly as
+ * `graphql()` keeps it: a published read with no errors, never a draft or an
+ * edit-mode page.
+ */
+async function getCapaClient(input) {
+    const draft = (await input.draftMode()).isEnabled === true;
+    const edit = await editMode({ draftMode: input.draftMode, headers: input.headers });
+    const settings = modeConfig(input.config, draft);
+    const client = (0, next_1.createClient)({ editMode: edit, ...settings });
+    const read = { draft, edit, settings, given: input.unstable_cache };
+    const graphql = (0, client_1.graphqlClient)((document, variables, options = {}) => {
+        const { tags, revalidate, ...call } = options;
+        return readInNext(read, document, variables, call, { tags, revalidate });
+    });
+    return { ...client, graphql };
+}
+let loadedUnstableCache;
+/**
+ * Next's own `unstable_cache`, loaded on first use, or null where `next/cache`
+ * cannot be loaded (Next not installed). The package never imports `next/*`
+ * at the top, so a Node script can import this file without Next.
+ */
+function nextUnstableCache() {
+    if (loadedUnstableCache === undefined) {
+        try {
+            loadedUnstableCache = require("next/cache").unstable_cache ?? null;
+        }
+        catch {
+            loadedUnstableCache = null;
+        }
+    }
+    return loadedUnstableCache;
+}
+/** Thrown inside `unstable_cache` so that a result with errors is never stored; caught at once. */
+class NotCached extends Error {
+    result;
+    constructor(result) {
+        super(`@capacms/sdk/nextjs: this GraphQL read answered with errors, so it was not cached: ${result.errors[0]?.message ?? "unknown error"}`);
+        this.result = result;
+        this.name = "NotCached";
+    }
+}
+/**
+ * What a cached read is keyed by: everything that changes its answer. The key
+ * is hashed, so the API key never reaches the cache's index.
+ */
+async function cacheKeyOf(settings, document, variables, call) {
+    return [
+        "@capacms/sdk/nextjs graphql",
+        settings.baseUrl,
+        await (0, sha256_1.sha256Hex)(settings.apiKey),
+        settings.version ?? "",
+        String(settings.contract ?? ""),
+        settings.schemaChecksum ?? "",
+        document,
+        JSON.stringify(variables ?? null),
+        call.operationName ?? "",
+        call.persisted ? "persisted" : "",
+        call.method ?? "",
+    ];
+}
+async function graphql(document, variables, options = {}) {
+    const { tags, revalidate, draft: draftOption, draftMode, headers, config, unstable_cache: given, ...call } = options;
+    const draft = draftOption ?? (draftMode ? (await draftMode()).isEnabled === true : false);
+    const edit = draft || (headers ? verifiedEdit(await headers()) : false);
+    const read = { draft, edit, settings: modeConfig(config, draft), given };
+    return readInNext(read, document, variables, call, { tags, revalidate });
+}
+/**
+ * Whether a read said anything about Next's cache: tags to keep it under, or a
+ * `revalidate`. One that said neither is sent as the REST reads are, so a
+ * publish shows up on both the same way.
+ */
+function namesCaching({ tags, revalidate }) {
+    return (tags !== undefined && tags.length > 0) || revalidate !== undefined;
+}
+/**
+ * One GraphQL read in Next, for `graphql()` and `getCapaClient`.
+ *
+ * With no `tags` and no `revalidate` it is sent exactly as `entries.list` and
+ * `entries.get` send theirs: a plain fetch with no `cache` and no `next`, which
+ * Next does not keep, so the page shows a publish on its next render whether
+ * it reads by REST or by GraphQL. Given `tags` or a `revalidate`, Next's data
+ * cache holds a published read with no errors, and the fetch under it is never
+ * cached. A draft, an edit-mode read (its entries carry marks a cached copy
+ * would lose) and `revalidate: 0` are not cached.
+ */
+async function readInNext(read, document, variables, call, options) {
+    const { draft, edit, settings, given } = read;
+    if (!draft && !edit && !namesCaching(options)) {
+        return (0, next_1.createClient)({ editMode: false, ...settings }).graphql(document, variables, call);
+    }
+    // `tags: []` names no tag, so the read is kept under `GRAPHQL_TAG` like one
+    // with no tags: kept under none, nothing could ever revalidate it.
+    const tags = options.tags && options.tags.length > 0 ? options.tags : undefined;
+    const revalidate = options.revalidate;
+    const baseFetch = settings.fetch ?? globalThis.fetch;
+    const cache = given ?? nextUnstableCache();
+    if (cache && !draft) {
+        if (edit || revalidate === 0) {
+            return (0, next_1.createClient)({ editMode: edit, ...settings, fetch: withCache(baseFetch, { revalidate: 0 }) }).graphql(document, variables, call);
+        }
+        const client = (0, next_1.createClient)({ editMode: false, ...settings, fetch: baseFetch });
+        let sent = false;
+        const send = async () => {
+            sent = true;
+            const result = await client.graphql(document, variables, call);
+            if (result.errors.length > 0)
+                throw new NotCached(result);
+            return result;
+        };
+        const keyParts = await cacheKeyOf(settings, document, variables, call);
+        const cacheOptions = { tags: tags ?? [exports.GRAPHQL_TAG] };
+        if (revalidate !== undefined)
+            cacheOptions.revalidate = revalidate;
+        try {
+            return await cache(send, keyParts, cacheOptions)();
+        }
+        catch (error) {
+            if (error instanceof NotCached)
+                return error.result;
+            // Next's own `unstable_cache` throws before it reads anything outside a
+            // Next request (a script, a test, a build step with no cache): the read
+            // is then sent as below. One passed in throws as it did.
+            if (given || sent)
+                throw error;
+        }
+    }
+    const client = (0, next_1.createClient)({
+        editMode: edit,
+        ...settings,
+        fetch: draft
+            ? withCache(baseFetch, { revalidate: 0 })
+            : withCache(baseFetch, { tags: tags ?? [exports.GRAPHQL_TAG], revalidate }),
+    });
+    return client.graphql(document, variables, call);
+}
+/** Only a path on this site: never `//elsewhere.example` or a full URL. */
+function safeSitePath(value) {
+    if (!value || !value.startsWith("/") || value.startsWith("//"))
+        return "/";
+    return value;
+}
+// -------------------------------------------------------- draft responses ---
+/** The Capa admin's origin: what frames a draft in the editor, unless a site names another. */
+exports.CAPA_ADMIN_ORIGIN = "https://app.capacms.com";
+/** `X-Robots-Tag` on every draft and edit-mode response: a draft is never indexed, nor its links followed. */
+exports.DRAFT_ROBOTS_TAG = "noindex, nofollow";
+/** How long the draft cookie lasts, in seconds: one hour, as a preview token does. */
+exports.DRAFT_COOKIE_MAX_AGE = 3600;
+/**
+ * `frame-ancestors 'self' <origins>`, the CSP directive that lets the Capa
+ * editor frame a draft and nothing else frame it. Each origin is a scheme and
+ * a host, with a port when it has one, and is written as the URL parser
+ * normalises it, so no `;` or quote can reach the policy. Anything else, a
+ * path or a query included, throws a `TypeError`.
+ */
+function frameAncestors(adminOrigins = [exports.CAPA_ADMIN_ORIGIN]) {
+    const origins = new Set();
+    for (const value of adminOrigins)
+        origins.add(originOf(value));
+    return ["frame-ancestors 'self'", ...origins].join(" ");
+}
+function originOf(value) {
+    let url = null;
+    try {
+        url = typeof value === "string" ? new URL(value) : null;
+    }
+    catch {
+        url = null;
+    }
+    const bare = url !== null &&
+        (url.protocol === "https:" || url.protocol === "http:") &&
+        url.pathname === "/" &&
+        url.search === "" &&
+        url.hash === "" &&
+        url.username === "" &&
+        url.password === "";
+    if (!bare) {
+        throw new TypeError(`@capacms/sdk/nextjs: ${JSON.stringify(value)} is not an origin. Pass a scheme and a host, such as ${exports.CAPA_ADMIN_ORIGIN}.`);
+    }
+    return url.origin;
+}
+/**
+ * The headers every draft response carries: `X-Robots-Tag: noindex, nofollow`,
+ * and `Content-Security-Policy: frame-ancestors 'self' https://app.capacms.com`
+ * (or the `adminOrigins` given). Throws for an origin that is not one.
+ */
+function draftHeaders(options = {}) {
+    return {
+        "X-Robots-Tag": exports.DRAFT_ROBOTS_TAG,
+        "Content-Security-Policy": frameAncestors(options.adminOrigins),
+    };
+}
+/**
+ * Rules for `next.config`'s `headers()` that send `draftHeaders` on draft
+ * responses only:
+ *
+ *   // next.config.mjs
+ *   import { capaHeaders } from "@capacms/sdk/nextjs";
+ *   export default { async headers() { return [...capaHeaders()]; } };
+ *
+ * A rule matches a request carrying the draft cookie, or a `capa-preview`,
+ * `capa-edit` or `capa-view` query. A visitor's request carries none of
+ * them, so its response, cached or not, is exactly what it was. Next checks
+ * the cookie by name, not by value, so a forged cookie only adds these
+ * headers to the forger's own response.
+ *
+ * A site that sends its own `frame-ancestors` or `X-Frame-Options` must leave
+ * them off draft responses (`missing: [{ type: "cookie", key: DRAFT_COOKIE }]`
+ * on its rule): a browser applies every CSP it is sent, so the strictest wins.
+ */
+function capaHeaders(options = {}) {
+    const headers = () => Object.entries(draftHeaders(options)).map(([key, value]) => ({ key, value }));
+    const conditions = [
+        { type: "cookie", key: exports.DRAFT_COOKIE },
+        { type: "query", key: exports.PREVIEW_PARAM },
+        { type: "query", key: exports.EDIT_PARAM },
+        { type: "query", key: exports.VIEW_PARAM },
+    ];
+    return conditions.map((condition) => ({ source: "/:path*", has: [condition], headers: headers() }));
+}
+/** The attributes a draft cookie needs to be sent inside the Capa editor's cross-site frame. */
+const FRAMED = { path: "/", httpOnly: true, secure: true, sameSite: "none", partitioned: true };
+function draftCookieMaxAge(maxAge = exports.DRAFT_COOKIE_MAX_AGE) {
+    if (typeof maxAge !== "number" || !Number.isInteger(maxAge) || maxAge <= 0) {
+        throw new TypeError(`@capacms/sdk/nextjs: maxAge must be a whole number of seconds above 0, and got ${String(maxAge)}.`);
+    }
+    return maxAge;
+}
+/**
+ * Re-set the cookie `draftMode().enable()` just set, so the Capa editor can
+ * use it: `HttpOnly; Secure; SameSite=None; Partitioned; Path=/` and
+ * `Max-Age` one hour (`maxAge` seconds). Next sets it with no `Max-Age`, so
+ * it unlocks every draft on the site until the browser closes, and without
+ * `Partitioned`, which Safari 26.2 and later need to send a cookie into a
+ * cross-site frame. Call it after `enable()`, in the same route handler.
+ * Resolves false, and sets nothing, when there is no draft cookie to re-set.
+ */
+async function frameDraftCookie(cookies, options = {}) {
+    const maxAge = draftCookieMaxAge(options.maxAge);
+    const jar = await cookies();
+    const current = jar.get(exports.DRAFT_COOKIE);
+    if (!current?.value)
+        return false;
+    jar.set({ name: exports.DRAFT_COOKIE, value: current.value, ...FRAMED, maxAge });
+    return true;
+}
+/**
+ * Delete the draft cookie `frameDraftCookie` set. A partitioned cookie is
+ * deleted only by a `Set-Cookie` that is partitioned too, which
+ * `draftMode().disable()` is not. Call it after `disable()`; it replaces
+ * `disable()`'s own deletion, since a response sets one cookie per name. A
+ * draft cookie set without `Partitioned`, before a site used
+ * `frameDraftCookie`, ends when the browser closes, as it always did.
+ */
+async function clearDraftCookie(cookies) {
+    (await cookies()).set({ name: exports.DRAFT_COOKIE, value: "", ...FRAMED, expires: new Date(0) });
+}
+/**
+ * The preview and exit routes' own redirect. Next's `redirect()` throws and
+ * answers for the route, so it cannot carry headers; this one is a plain
+ * `Response`, to which Next appends every cookie the route set. It sets no
+ * cookie itself: Next keeps one per name, and the response's own would win.
+ */
+function routeRedirect(location, headers) {
+    return new Response(null, {
+        status: 307,
+        headers: { Location: location, "Cache-Control": exports.EDIT_CACHE_CONTROL, "Referrer-Policy": "no-referrer", ...headers },
+    });
+}
+/**
+ * `app/api/capa/preview/route.ts`:
+ *
+ *   import { cookies, draftMode } from "next/headers";
+ *   export const GET = createPreviewRoute({ draftMode, cookies });
+ *
+ * Checks the token with Capa (the site never holds the signing key), turns
+ * draft mode on and lands on the entry's page. A bad or expired token lands on
+ * the page without draft mode and `?preview=expired`; Capa unreachable gives
+ * `?preview=unavailable`. The token is checked with any key the site holds,
+ * its legacy key included (`getPublishedClient`, from `CAPA_KEY`).
+ *
+ * Given `cookies`, the draft cookie is re-set by `frameDraftCookie`: one hour,
+ * and sent inside the editor's frame. With no `redirect`, the route answers
+ * with its own 307, marked `X-Robots-Tag: noindex, nofollow`,
+ * `Referrer-Policy: no-referrer` (the token is in the URL),
+ * `Cache-Control: private, no-store` and the editor's `frame-ancestors`.
+ * Given Next's `redirect`, it is called instead, as before, and the redirect
+ * carries none of those.
+ */
+function createPreviewRoute(input) {
+    // Checked here, so a bad origin or maxAge fails where the route is built.
+    const headers = draftHeaders({ adminOrigins: input.adminOrigins });
+    const maxAge = draftCookieMaxAge(input.maxAge);
+    const go = (location) => input.redirect ? input.redirect(location) : routeRedirect(location, headers);
+    return async (request) => {
+        const url = new URL(request.url);
+        const token = url.searchParams.get("token") ?? url.searchParams.get(exports.PREVIEW_PARAM) ?? "";
+        // Reached two ways: directly, or through the middleware's rewrite of a page
+        // URL carrying `?capa-preview=`, where Next may hand over the ORIGINAL URL.
+        // Then the page itself is the path.
+        const path = safeSitePath(url.searchParams.get("path") ?? (url.searchParams.has(exports.PREVIEW_PARAM) ? url.pathname : null));
+        let claim = null;
+        let failed = false;
+        try {
+            claim = await (input.client ?? getPublishedClient)().preview(token);
+        }
+        catch {
+            failed = true;
+        }
+        const draft = await input.draftMode();
+        if (!claim) {
+            draft.disable?.();
+            if (input.cookies)
+                await clearDraftCookie(input.cookies);
+            return go(`${path}?preview=${failed ? "unavailable" : "expired"}`);
+        }
+        draft.enable?.();
+        if (input.cookies)
+            await frameDraftCookie(input.cookies, { maxAge });
+        await input.onEnable?.();
+        return go(safeSitePath(claim.path ?? path));
+    };
+}
+/**
+ * `app/api/capa/exit/route.ts`:
+ *
+ *   import { cookies, draftMode } from "next/headers";
+ *   export const GET = exitPreviewRoute({ draftMode, cookies });
+ *
+ * Turns draft mode off and lands on `?path=`. Given `cookies`, the framed
+ * cookie `createPreviewRoute` set is deleted too. With no `redirect`, the route
+ * answers with its own 307, marked noindex and never cached.
+ */
+function exitPreviewRoute(input) {
+    return async (request) => {
+        (await input.draftMode()).disable?.();
+        if (input.cookies)
+            await clearDraftCookie(input.cookies);
+        const location = safeSitePath(new URL(request.url).searchParams.get("path"));
+        if (input.redirect)
+            return input.redirect(location);
+        return routeRedirect(location, { "X-Robots-Tag": exports.DRAFT_ROBOTS_TAG });
+    };
+}
+/**
+ * `middleware.ts` in one line:
+ *
+ *   import { NextResponse } from "next/server";
+ *   export const middleware = capaMiddleware({ NextResponse });
+ *
+ * - `?capa-preview=<token>` on any page goes to `previewRoute`, which turns
+ *   draft mode on and comes back;
+ * - `?capa-view=published` renders without the draft cookie, for the editor's
+ *   Published view;
+ * - `?capa-edit=<token>` turns edit mode on (ids and overlay, published data);
+ * - every edit-mode response is `private, no-store`, and it and every request
+ *   carrying `capa-edit` or `capa-view` is `X-Robots-Tag: noindex, nofollow`.
+ *
+ * Give it a `matcher` so a visitor's request never runs it (Next reads
+ * `config` from the file itself, so it is written out there):
+ *
+ *   export const config = {
+ *     matcher: [
+ *       { source: "/:path*", has: [{ type: "query", key: "capa-preview" }] },
+ *       { source: "/:path*", has: [{ type: "query", key: "capa-edit" }] },
+ *       { source: "/:path*", has: [{ type: "query", key: "capa-view" }] },
+ *       { source: "/:path*", has: [{ type: "cookie", key: "__prerender_bypass" }] },
+ *     ],
+ *   };
+ */
+function capaMiddleware(input) {
+    const previewRoute = input.previewRoute ?? "/api/capa/preview";
+    return async (request) => {
+        const token = request.nextUrl.searchParams.get(exports.PREVIEW_PARAM);
+        if (token) {
+            const target = request.nextUrl.clone();
+            target.pathname = previewRoute;
+            target.search = "";
+            target.searchParams.set("token", token);
+            target.searchParams.set("path", request.nextUrl.pathname);
+            return input.NextResponse.rewrite(target);
+        }
+        const headers = new Headers(request.headers);
+        if (request.nextUrl.searchParams.get(exports.VIEW_PARAM) === "published") {
+            const cookies = request.cookies
+                .getAll()
+                .filter((cookie) => cookie.name !== exports.DRAFT_COOKIE)
+                .map((cookie) => `${cookie.name}=${encodeURIComponent(cookie.value)}`)
+                .join("; ");
+            if (cookies)
+                headers.set("cookie", cookies);
+            else
+                headers.delete("cookie");
+        }
+        // The client is built only when a token needs checking, so a missing env
+        // value cannot break every page of the site.
+        const edit = await resolveEditRequest({ url: request.url, headers }, { preview: (t) => (input.client ?? getPublishedClient)().preview(t) });
+        const response = input.NextResponse.next({ request: { headers: edit.headers } });
+        if (edit.cacheControl)
+            response.headers.set("Cache-Control", edit.cacheControl);
+        // A capa- link is the editor's, verified or not, and never a page to index.
+        const capaLink = request.nextUrl.searchParams.has(exports.EDIT_PARAM) || request.nextUrl.searchParams.has(exports.VIEW_PARAM);
+        const robots = edit.robotsTag ?? (capaLink ? exports.DRAFT_ROBOTS_TAG : null);
+        if (robots)
+            response.headers.set("X-Robots-Tag", robots);
+        return response;
+    };
+}