@capacms/sdk 1.0.0-next.7 → 1.0.0-next.9

package/dist/esm/overlay/protocol.js

@@ -0,0 +1,173 @@
+/**
+ * The live preview protocol, site side. Pure: no DOM, no globals, so it can be
+ * tested under plain `node --test`.
+ *
+ * The Capa admin frames the site and the two talk over `postMessage`. Every
+ * message is a plain object `{ source, v: 1, type, ...fields }`:
+ *
+ *   admin -> site  (source "capa-admin")
+ *     hello     {}                                   sent on the frame's load
+ *     highlight { entryId, field: string | null }    entryId "" clears
+ *     outline   { on: boolean }                      outline every tagged element
+ *     refresh   {}                                   re-render the draft
+ *
+ *   site -> admin  (source "capa")
+ *     ready     { path, entries }                    after hello, and after every navigation
+ *     select    { entryId, field }                   a tagged element was clicked
+ *     hover     { entryId, field } | { entryId: "", field: null }
+ *     visible   { entryId, field }                   the tagged element at the centre of the
+ *                                                    viewport changed (throttled, on scroll)
+ *
+ * `visible` arrived in 1.0.0-next.2 and is OPTIONAL: it is still `v: 1`,
+ * because an admin that does not know it drops an unknown type, and an older
+ * overlay simply never sends it. Additive messages keep the version; only a
+ * change to an existing shape would move it.
+ *
+ * The admin keeps its own copy of these shapes (`apps/admin`, no dependency on
+ * this package). If you change one side, change the other.
+ */
+export const PROTOCOL_VERSION = 1;
+export const ADMIN_SOURCE = "capa-admin";
+export const SITE_SOURCE = "capa";
+/**
+ * `https://admin.example.com/` and `https://admin.example.com` are one origin,
+ * and a configured value that is not a URL at all is dropped rather than
+ * compared as a string, because `"*"` must never mean "anyone".
+ */
+export function normaliseOrigins(origins) {
+    const out = [];
+    for (const raw of origins) {
+        if (typeof raw !== "string" || raw.trim() === "")
+            continue;
+        try {
+            const origin = new URL(raw.trim()).origin;
+            if (origin !== "null" && !out.includes(origin))
+                out.push(origin);
+        }
+        catch {
+            // Not a URL: never an origin anybody can send from.
+        }
+    }
+    return out;
+}
+/**
+ * The one gate every incoming message goes through. A message is accepted only
+ * when all of these hold, and is `null` otherwise:
+ *
+ *   - it came from the window that framed this page (`parent`), not from a
+ *     popup, a sibling frame or this page itself
+ *   - its origin is one the site configured as its admin
+ *   - it says it is from the admin, speaks version 1, and has a known type
+ *     whose fields have the right shapes
+ *
+ * `allowedOrigins` is expected already normalised (`normaliseOrigins`).
+ */
+export function acceptMessage(event, allowedOrigins, parent) {
+    if (!event || event.source !== parent || parent == null)
+        return null;
+    if (typeof event.origin !== "string" || !allowedOrigins.includes(event.origin))
+        return null;
+    const data = event.data;
+    if (typeof data !== "object" || data === null || Array.isArray(data))
+        return null;
+    const m = data;
+    if (m.source !== ADMIN_SOURCE || m.v !== PROTOCOL_VERSION)
+        return null;
+    switch (m.type) {
+        case "hello":
+            return { source: ADMIN_SOURCE, v: 1, type: "hello" };
+        case "refresh":
+            return { source: ADMIN_SOURCE, v: 1, type: "refresh" };
+        case "outline":
+            if (typeof m.on !== "boolean")
+                return null;
+            return { source: ADMIN_SOURCE, v: 1, type: "outline", on: m.on };
+        case "highlight":
+            if (typeof m.entryId !== "string")
+                return null;
+            if (m.field !== null && typeof m.field !== "string")
+                return null;
+            return { source: ADMIN_SOURCE, v: 1, type: "highlight", entryId: m.entryId, field: m.field };
+        default:
+            return null;
+    }
+}
+export function readyMessage(path, entries) {
+    return { source: SITE_SOURCE, v: 1, type: "ready", path, entries };
+}
+export function selectMessage(entryId, field) {
+    return { source: SITE_SOURCE, v: 1, type: "select", entryId, field };
+}
+export function hoverMessage(entryId, field) {
+    return entryId === ""
+        ? { source: SITE_SOURCE, v: 1, type: "hover", entryId: "", field: null }
+        : { source: SITE_SOURCE, v: 1, type: "hover", entryId, field };
+}
+export function visibleMessage(entryId, field) {
+    return { source: SITE_SOURCE, v: 1, type: "visible", entryId, field };
+}
+/** Above any element height, so a box that misses the centre line never outranks one that crosses it. */
+const MISS_FLOOR = 1e9;
+/**
+ * The tagged element a reader is looking at: the one that contains the
+ * viewport's horizontal centre line, and when several do (a field inside a
+ * card that is also tagged) the SMALLEST, because the innermost element is
+ * the specific one. When none crosses the line, the nearest one that is at
+ * least partly on screen. Null when nothing tagged is on screen at all.
+ *
+ * `edge` is where the page is scrolled to. A heading near the top of a page
+ * can never reach the centre line, because the page cannot scroll above its
+ * top; at the top the topmost visible element is the one being read, and at
+ * the bottom the bottommost. The same rule a table of contents' scroll spy
+ * uses.
+ *
+ * Pure, so the admin's "follow the page" can be tested without a DOM.
+ */
+export function pickCentred(boxes, viewportHeight, edge = null) {
+    const centre = viewportHeight / 2;
+    let best = null;
+    let bestScore = Infinity;
+    for (const b of boxes) {
+        if (!b.entryId || !b.field)
+            continue;
+        if (b.bottom <= 0 || b.top >= viewportHeight || b.bottom <= b.top)
+            continue;
+        const height = b.bottom - b.top;
+        let score;
+        if (edge === "top") {
+            // Topmost first; of two that start together, the smaller (inner) one.
+            score = b.top * MISS_FLOOR + height;
+        }
+        else if (edge === "bottom") {
+            score = (viewportHeight - b.bottom) * MISS_FLOOR + height;
+        }
+        else {
+            // Crossing the line scores by height (smaller wins) and always beats a
+            // box that misses it, which scores by its distance from the line on top
+            // of a floor no height can reach.
+            score =
+                b.top <= centre && b.bottom >= centre
+                    ? height
+                    : MISS_FLOOR + Math.min(Math.abs(b.top - centre), Math.abs(b.bottom - centre));
+        }
+        if (score < bestScore) {
+            best = b;
+            bestScore = score;
+        }
+    }
+    return best;
+}
+/**
+ * Which edge a scroll position is at, for `pickCentred`. A page that does not
+ * scroll at all is at neither: nothing moves, and the centre rule stands.
+ */
+export function scrollEdge(scrollY, viewportHeight, scrollHeight) {
+    const max = scrollHeight - viewportHeight;
+    if (max <= 1)
+        return null;
+    if (scrollY <= 1)
+        return "top";
+    if (scrollY >= max - 1)
+        return "bottom";
+    return null;
+}

package/dist/esm/package.json

@@ -0,0 +1,4 @@
+{
+  "type": "module",
+  "sideEffects": false
+}

package/dist/next/client.d.ts

@@ -9,9 +9,9 @@ export interface CapaNextConfig {
     baseUrl: string;
     /**
      * A `cap_` key, or the legacy key a site already holds: `pk_`, `sk_`, or
-     * an older key with no prefix. A legacy key reads through every read call
-     * and warns once per process; `preview()` and draft reads take a `cap_` key
-     * only.
+     * an older key with no prefix. A legacy key reads through every read call,
+     * `preview()` included, and warns once per process; the draft clients of
+     * `@capacms/sdk/nextjs` take a `cap_` key only.
      */
     apiKey: string;
     version: string;
@@ -210,7 +210,7 @@ export interface EntriesResource {
  * One suggestion drawn from a page's own reads.
  *
  * Computed on the API, never here. Three clients want this answer (this SDK,
- * the Capa admin and `@capa/mcp`), and a second implementation of "this page
+ * the Capa admin and `@capacms/mcp`), and a second implementation of "this page
  * over-fetches" would drift from the first the moment a threshold moved.
  */
 export interface PageInsight {
@@ -401,8 +401,8 @@ export interface CapaNextClient<Q = UntypedQuery, O extends GraphQLCallOptions =
      * Returns the claim, or NULL when the token is invalid or expired, because
      * both mean the same thing to a preview route: do not enable draft mode.
      * Every other failure throws, so a Capa outage does not look like a bad link.
-     * Needs a `cap_` key: a client built with a legacy key throws a
-     * `TypeError` here before any request.
+     * Takes any key the site holds, a legacy `pk_`, `sk_` or unprefixed key
+     * included: Capa answers a token minted for another tenant as invalid.
      */
     preview(token: string, options?: CallOptions): Promise<PreviewClaim | null>;
     me<T = Record<string, unknown>>(options?: CallOptions): Promise<T>;

package/dist/next/client.js

@@ -501,7 +501,8 @@ function createClient(config) {
             return readSchema(options.signal);
         },
         async preview(token, options = {}) {
-            (0, key_family_1.requirePreviewKey)(resolved.apiKey);
+            // Any key the site holds, legacy included: the API checks the token
+            // belongs to the key's own tenant (see key-family.ts).
             const query = new URLSearchParams();
             query.set("token", token);
             try {

package/dist/next/field-names.js

@@ -28,7 +28,7 @@ exports.readPath = readPath;
  *
  * The API's own writer is `writeName` in `@capa/shared`. This package ships
  * with no runtime dependencies, so the rule is copied here and in
- * `@capa/mcp`, and test/fixtures/field-names.json pins all three to the same
+ * `@capacms/mcp`, and test/fixtures/field-names.json pins all three to the same
  * vectors.
  */
 const system_keys_1 = require("./system-keys");

package/dist/next/graphql/introspection.d.ts

@@ -4,7 +4,7 @@
  *
  * One request carries both the standard introspection selection and the
  * `version` root field, so a schema summary always says which platform version
- * it describes. Kept byte-stable: `@capa/mcp` sends the same text, and a
+ * it describes. Kept byte-stable: `@capacms/mcp` sends the same text, and a
  * persisted copy of it is one hash for every client.
  *
  * Deprecated arguments and input fields are asked for too, with their

package/dist/next/graphql/introspection.js

@@ -5,7 +5,7 @@
  *
  * One request carries both the standard introspection selection and the
  * `version` root field, so a schema summary always says which platform version
- * it describes. Kept byte-stable: `@capa/mcp` sends the same text, and a
+ * it describes. Kept byte-stable: `@capacms/mcp` sends the same text, and a
  * persisted copy of it is one hash for every client.
  *
  * Deprecated arguments and input fields are asked for too, with their

package/dist/next/graphql/plan.js

@@ -80,7 +80,7 @@ function didYouMean(wanted, candidates) {
 /**
  * The refusal for a model the key reads that GraphQL leaves out (N1): REST
  * serves it, so the message names that read and why, and suggests no other
- * model. `@capa/mcp` says the same, pinned by a test.
+ * model. `@capacms/mcp` says the same, pinned by a test.
  */
 function restOnlyModel(namespace, restOnly) {
     // N1 leaves models out when their type names would collide, as these
@@ -176,7 +176,7 @@ function checkSort(value, model, where) {
 // A spec written as REST writes a read (`author.name` or `author(name)` for a
 // relation's fields, `*` for every field, `-publishedAt` for a sort) is
 // refused with what to write instead, spelled out, since the same read is one
-// edit away. @capa/mcp refuses them in the same words, pinned by
+// edit away. @capacms/mcp refuses them in the same words, pinned by
 // test/fixtures/graphql-rest-forms.json.
 /** A REST sort key as a sort value: `-publishedAt` is `publishedAt_DESC`, `author.name` is `author__name_ASC`. */
 function restSortValue(value) {

package/dist/next/key-family.d.ts

@@ -2,16 +2,18 @@
  * key-family.ts — which keys `@capacms/sdk/next` takes, and for what.
  *
  * A `cap_` key is the `/api/` key: scoped, hashed at rest, and the only kind
- * a draft preview takes, both to verify a preview token and to read drafts.
- * Every other key is legacy, which is the API's rule
- * (`apps/api/src/api-next/auth/key-format.ts`): the `pk_` and `sk_` keys, and
- * the unprefixed keys older tenants were minted, all reach `/api/` with the
- * grants their permission gives. So every read call takes them, and the first
- * client built with one warns once per process, naming the key to mint.
+ * the draft clients take to read drafts. Every other key is legacy, which is
+ * the API's rule (`apps/api/src/api-next/auth/key-format.ts`): the `pk_` and
+ * `sk_` keys, and the unprefixed keys older tenants were minted, all reach
+ * `/api/` with the grants their permission gives. So every read call takes
+ * them, `preview()` included: `GET /api/preview` asks for `instance:read`,
+ * which every legacy permission grants, and refuses a token minted for another
+ * tenant. The first client built with one warns once per process, naming the
+ * key to mint.
  *
  * The `cap_` prefix is the whole rule, case-sensitive, as on the API:
  * `CAP_live_…` is not a key Capa mints, so it is looked up as a legacy key.
- * `@capa/mcp` applies the same rule, and both packages are tested against one
+ * `@capacms/mcp` applies the same rule, and both packages are tested against one
  * vector file, `test/fixtures/key-family.json`.
  */
 export type KeyFamily = "cap" | "legacy";
@@ -19,11 +21,6 @@ export type KeyFamily = "cap" | "legacy";
 export declare function keyFamily(apiKey: unknown): KeyFamily | null;
 /** Warn about a legacy key once per process: a site builds a client per request. */
 export declare function warnLegacyKeyOnce(apiKey: string): void;
-/**
- * Throws for a legacy key: verifying a preview token takes a `cap_` key. A
- * value that is no key at all is `resolveNextConfig`'s to refuse, by name.
- */
-export declare function requirePreviewKey(apiKey: string): void;
 /**
  * Throws for a legacy key: a draft read takes a `cap_` key. `holder` names
  * where the key came from (`CAPA_DRAFT_KEY`, `the draft config`), so the

package/dist/next/key-family.js

@@ -3,22 +3,23 @@
  * key-family.ts — which keys `@capacms/sdk/next` takes, and for what.
  *
  * A `cap_` key is the `/api/` key: scoped, hashed at rest, and the only kind
- * a draft preview takes, both to verify a preview token and to read drafts.
- * Every other key is legacy, which is the API's rule
- * (`apps/api/src/api-next/auth/key-format.ts`): the `pk_` and `sk_` keys, and
- * the unprefixed keys older tenants were minted, all reach `/api/` with the
- * grants their permission gives. So every read call takes them, and the first
- * client built with one warns once per process, naming the key to mint.
+ * the draft clients take to read drafts. Every other key is legacy, which is
+ * the API's rule (`apps/api/src/api-next/auth/key-format.ts`): the `pk_` and
+ * `sk_` keys, and the unprefixed keys older tenants were minted, all reach
+ * `/api/` with the grants their permission gives. So every read call takes
+ * them, `preview()` included: `GET /api/preview` asks for `instance:read`,
+ * which every legacy permission grants, and refuses a token minted for another
+ * tenant. The first client built with one warns once per process, naming the
+ * key to mint.
  *
  * The `cap_` prefix is the whole rule, case-sensitive, as on the API:
  * `CAP_live_…` is not a key Capa mints, so it is looked up as a legacy key.
- * `@capa/mcp` applies the same rule, and both packages are tested against one
+ * `@capacms/mcp` applies the same rule, and both packages are tested against one
  * vector file, `test/fixtures/key-family.json`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.keyFamily = keyFamily;
 exports.warnLegacyKeyOnce = warnLegacyKeyOnce;
-exports.requirePreviewKey = requirePreviewKey;
 exports.requireDraftKey = requireDraftKey;
 exports.__resetKeyWarningForTests = __resetKeyWarningForTests;
 const LEGACY_PREFIX = /^(pk|sk)_/;
@@ -46,17 +47,8 @@ function warnLegacyKeyOnce(apiKey) {
     if (warned)
         return;
     warned = true;
-    console.warn(`@capacms/sdk/next: this client reads with a ${legacyKind(apiKey)}. Reads work as they do with a cap_ key. ` +
-        `Draft previews need a cap_ key: mint one ${MINT}`);
-}
-/**
- * Throws for a legacy key: verifying a preview token takes a `cap_` key. A
- * value that is no key at all is `resolveNextConfig`'s to refuse, by name.
- */
-function requirePreviewKey(apiKey) {
-    if (!isLegacy(apiKey))
-        return;
-    throw new TypeError(`@capacms/sdk/next: preview needs a cap_ key, and this client holds a ${legacyKind(apiKey)}. Mint a cap_ key ${MINT}`);
+    console.warn(`@capacms/sdk/next: this client reads with a ${legacyKind(apiKey)}. Reads and preview links work as they do with a cap_ key. ` +
+        `Draft reads need a cap_ key: mint one ${MINT}`);
 }
 /**
  * Throws for a legacy key: a draft read takes a `cap_` key. `holder` names

package/dist/nextjs/index.d.ts

@@ -111,6 +111,10 @@ export type { PreviewClaim };
  * clickable. It never switches the site to draft data.
  */
 export declare const EDIT_PARAM = "capa-edit";
+/** The query parameter a Capa preview link carries: `?capa-preview=<token>`. */
+export declare const PREVIEW_PARAM = "capa-preview";
+/** The query parameter of the editor's Published view: `?capa-view=published`. */
+export declare const 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
@@ -157,6 +161,8 @@ export interface EditRequest {
     headers: Headers;
     /** `EDIT_CACHE_CONTROL` in edit mode, otherwise null. Set it on the response. */
     cacheControl: string | null;
+    /** `DRAFT_ROBOTS_TAG` in edit mode, otherwise null. Set it on the response as `X-Robots-Tag`. */
+    robotsTag: string | null;
 }
 /**
  * The middleware half of edit mode.
@@ -165,6 +171,7 @@ export interface EditRequest {
  *     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;
  *   }
  *
@@ -323,29 +330,149 @@ export declare function graphql<D extends keyof CapaDocuments>(document: D, ...r
 export declare function graphql<TData = Record<string, unknown>, TVariables = Record<string, unknown>, D extends string = string>(document: NotARecordedDocument<D, TypedDocument<TData, TVariables> | D>, ...rest: VariablesThenOptions<TVariables, NextGraphQLOptions>): Promise<GraphQLResult<TData>>;
 /** Only a path on this site: never `//elsewhere.example` or a full URL. */
 export declare function safeSitePath(value: string | null | undefined): string;
+/** The Capa admin's origin: what frames a draft in the editor, unless a site names another. */
+export declare const 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. */
+export declare const DRAFT_ROBOTS_TAG = "noindex, nofollow";
+/** How long the draft cookie lasts, in seconds: one hour, as a preview token does. */
+export declare const 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`.
+ */
+export declare function frameAncestors(adminOrigins?: readonly string[]): string;
+/**
+ * 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.
+ */
+export declare function draftHeaders(options?: {
+    adminOrigins?: readonly string[];
+}): Record<string, string>;
+/** One rule of `next.config`'s `headers()`, in the shape Next takes. */
+export interface NextHeaderRule {
+    source: string;
+    has: Array<{
+        type: "cookie" | "query";
+        key: string;
+    }>;
+    headers: Array<{
+        key: string;
+        value: string;
+    }>;
+}
+/**
+ * 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.
+ */
+export declare function capaHeaders(options?: {
+    adminOrigins?: readonly string[];
+}): NextHeaderRule[];
+/** The part of Next's `cookies()` store (`next/headers`) the draft-cookie helpers use. */
+export interface DraftCookieJar {
+    get(name: string): {
+        value: string;
+    } | undefined;
+    set(cookie: {
+        name: string;
+        value: string;
+        path: string;
+        httpOnly: boolean;
+        secure: boolean;
+        sameSite: "none";
+        partitioned: boolean;
+        maxAge?: number;
+        expires?: Date;
+    }): unknown;
+}
+/** Next's `cookies` from `next/headers`, or anything shaped like it. */
+export type CookiesFn = () => DraftCookieJar | Promise<DraftCookieJar>;
+/**
+ * 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.
+ */
+export declare function frameDraftCookie(cookies: CookiesFn, options?: {
+    maxAge?: number;
+}): Promise<boolean>;
+/**
+ * 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.
+ */
+export declare function clearDraftCookie(cookies: CookiesFn): Promise<void>;
 /**
  * `app/api/capa/preview/route.ts`:
  *
- *   import { draftMode } from "next/headers";
- *   import { redirect } from "next/navigation";
- *   export const GET = createPreviewRoute({ draftMode, redirect });
+ *   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`.
+ * `?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.
  */
 export declare function createPreviewRoute(input: {
     draftMode: DraftModeFn;
-    redirect: (url: string) => never | void;
+    /** Next's `cookies`. Given, the draft cookie lasts `maxAge` seconds and works in the editor's frame. */
+    cookies?: CookiesFn;
+    /** Next's `redirect`. Leave it out for a redirect that carries the draft headers. */
+    redirect?: (url: string) => never | void;
     client?: () => Pick<CapaNextClient, "preview">;
-    /** Runs after draft mode is enabled, before the redirect (cookie tweaks). */
+    /** Runs after draft mode is enabled and the cookie re-set, before the redirect (cookie tweaks). */
     onEnable?: () => void | Promise<void>;
+    /** The origins allowed to frame a draft. `[CAPA_ADMIN_ORIGIN]` when left out. */
+    adminOrigins?: readonly string[];
+    /** Seconds the draft cookie lasts, given `cookies`. `DRAFT_COOKIE_MAX_AGE` (one hour) when left out. */
+    maxAge?: number;
 }): (request: Request) => Promise<Response | void>;
-/** `app/api/capa/exit/route.ts`: `export const GET = exitPreviewRoute({ draftMode, redirect });` */
+/**
+ * `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.
+ */
 export declare function exitPreviewRoute(input: {
     draftMode: DraftModeFn;
-    redirect: (url: string) => never | void;
+    cookies?: CookiesFn;
+    redirect?: (url: string) => never | void;
 }): (request: Request) => Promise<Response | void>;
 interface MiddlewareRequest {
     url: string;
@@ -381,7 +508,20 @@ interface NextResponseLike {
  * - `?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`.
+ * - 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" }] },
+ *     ],
+ *   };
  */
 export declare function capaMiddleware(input: {
     NextResponse: NextResponseLike;