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

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 ## Unreleased
 
+- 1.0.0-next.8. Preview on a live site, in draft mode on its production
+  domain. `preview()` takes the legacy key a site already holds (`pk_`, `sk_`
+  or unprefixed), as the API does: Capa checks the token with any key that
+  reads the project, and refuses a token made for another project. It used to
+  throw a `TypeError` for a legacy key before any request. Draft reads through
+  the SDK still take a `cap_` key only, and the legacy-key warning says so.
+- Next.js: `createPreviewRoute` and `exitPreviewRoute` take Next's `cookies`.
+  Given it, the draft cookie is re-set
+  `HttpOnly; Secure; SameSite=None; Partitioned; Path=/; Max-Age=3600`
+  (`maxAge` changes the hour), so Safari 26.2 and later send it inside the
+  editor's frame and it no longer lasts until the browser closes. Exit and a
+  bad link delete it partitioned, which is the only deletion that reaches
+  it. `redirect` is optional now: left out, each route answers with its own
+  307, marked `X-Robots-Tag: noindex, nofollow`,
+  `Referrer-Policy: no-referrer` and `Cache-Control: private, no-store`, and
+  the preview route's carries the editor's `frame-ancestors`. Given
+  `redirect`, a route calls it as before.
+- Next.js: `capaHeaders({ adminOrigins })` returns rules for `next.config`'s
+  `headers()` that send `X-Robots-Tag: noindex, nofollow` and
+  `Content-Security-Policy: frame-ancestors 'self' https://app.capacms.com`
+  on a request carrying the draft cookie or a `capa-preview`, `capa-edit` or
+  `capa-view` query, and on nothing else, so a visitor's response is
+  unchanged. Also exported: `draftHeaders`, `frameAncestors` (it throws for a
+  value that is not a bare origin), `frameDraftCookie`, `clearDraftCookie`,
+  `CAPA_ADMIN_ORIGIN`, `DRAFT_ROBOTS_TAG`, `DRAFT_COOKIE_MAX_AGE`,
+  `PREVIEW_PARAM` and `VIEW_PARAM`.
+- Next.js: `capaMiddleware` marks every edit-mode response, and every request
+  carrying `capa-edit` or `capa-view`, `X-Robots-Tag: noindex, nofollow`, and
+  `resolveEditRequest` returns that value as `robotsTag`.
+- Docs: "Add preview to a live site without changing it", the steps for a
+  site that keeps its own Capa reads, and why `editMode()` and
+  `getCapaClient()` make a static page dynamic.
 - 1.0.0-next.7. Browsers: the `/api/` and legacy clients called the platform `fetch` as a
   method of their config, which a browser refuses ("Failed to execute 'fetch'
   on 'Window': Illegal invocation"), so every read from a browser failed unless
@@ -165,7 +197,7 @@
   as it takes a tool spec.
 
   The tool spec. `buildGraphQLQuery`, `graphqlToSelect` and `selectToGraphQL`
-  move between the spec the Explorer and `@capa/mcp` share, GraphQL text and
+  move between the spec the Explorer and `@capacms/mcp` share, GraphQL text and
   the equal REST request, written exactly as the API writes it in
   `extensions.capa.rest`: the filter as `where` JSON, and a system key a
   field shadows as `$tags`, `$createdAt` or `author.$id`. They nest at most 4

package/README.md

@@ -47,12 +47,14 @@ under Developers > Keys.
 The legacy key your site already holds works too, for every read: a `pk_`
 or `sk_` key, or an older key with no prefix, since every key but `cap_` is
 a legacy key to the API. That covers `entries`, `graphql`,
-`graphqlSchema`, `pages`, `me` and `versions`. The first client built with
-one prints a warning once per process, naming the `cap_` key to mint. Draft
-previews keep their rule and take a `cap_` key only: `preview()`,
-`draftClient`'s `draft` config, and `CAPA_DRAFT_KEY` for `getCapaClient` and
-`graphql()` throw a `TypeError` for a legacy key before any request. An
-`apiKey` that is not a string is refused where the client is built.
+`graphqlSchema`, `pages`, `me`, `versions` and `preview`: a site checks an
+editor's preview link with the key it already holds, and Capa refuses a link
+made for another project. The first client built with one prints a warning
+once per process, naming the `cap_` key to mint. Draft reads through the SDK
+keep their rule and take a `cap_` key only: `draftClient`'s `draft` config,
+and `CAPA_DRAFT_KEY` for `getCapaClient` and `graphql()`, throw a `TypeError`
+for a legacy key before any request. An `apiKey` that is not a string is
+refused where the client is built.
 
 `CAPA_API_URL` and `CAPA_KEY` are the names every Capa tool reads: the
 `/nextjs` helpers, `capa-codegen` and Capa's MCP server, so one `.env` serves
@@ -1273,8 +1275,9 @@ editor sees the path without a link to open it.
 
 ### Quick start (Next.js)
 
-Set `CAPA_API_URL`, `CAPA_KEY` (`cap_live_`) and `CAPA_DRAFT_KEY` (`cap_test_`).
-Draft previews take `cap_` keys only (see Keys). Then:
+Set `CAPA_API_URL`, `CAPA_KEY` (`cap_live_`, or the legacy key your site
+holds) and `CAPA_DRAFT_KEY` (`cap_test_`). Draft reads through the SDK take a
+`cap_` key only (see Keys). Then:
 
 ```ts
 // middleware.ts
@@ -1283,10 +1286,13 @@ import { capaMiddleware } from "@capacms/sdk/nextjs";
 export const middleware = capaMiddleware({ NextResponse });
 
 // app/api/capa/preview/route.ts  (and exit/route.ts with exitPreviewRoute)
-import { draftMode } from "next/headers";
-import { redirect } from "next/navigation";
+import { cookies, draftMode } from "next/headers";
 import { createPreviewRoute } from "@capacms/sdk/nextjs";
-export const GET = createPreviewRoute({ draftMode, redirect });
+export const GET = createPreviewRoute({ draftMode, cookies });
+
+// next.config.mjs
+import { capaHeaders } from "@capacms/sdk/nextjs";
+export default { async headers() { return capaHeaders(); } };
 
 // in a page: getCapaClient({ draftMode, headers }), then <h1 {...fieldAttrs(post).title}>
 // in the root layout: const edit = await editMode({ draftMode, headers }) from @capacms/sdk/nextjs,
@@ -1346,11 +1352,20 @@ payload, or your own JSON endpoint. The page then shows the draft with no
 the draft or edit state alongside the entry and hand it to `capaAttrs`:
 
 ```tsx
-// getServerSideProps, a +page.server.ts load, useAsyncData on the server...
-return { props: { entry, edit: draft } };
+// pages/articles/[id].tsx on the Pages Router. A +page.server.ts load or
+// useAsyncData on the server hands over the flag the same way.
+import type { Entry } from "@capacms/sdk/next";
+import type { Articles } from "./capa-types";
+
+export async function getServerSideProps({ draftMode = false }) {
+  const entry = (await capa.entries.get<Articles>("articles", "entry-id"))!.data;
+  return { props: { entry, edit: draftMode } };
+}
 
 // in the component
-<h1 {...capaAttrs(entry, "title", edit)}>{entry.fields.title}</h1>
+export default function Page({ entry, edit }: { entry: Entry<Articles>; edit: boolean }) {
+  return <h1 {...capaAttrs(entry, "title", edit)}>{entry.fields.title}</h1>;
+}
 ```
 
 Or re-mark the entries where they arrive with `markEditEntries(data)` when the
@@ -1388,6 +1403,7 @@ 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;
 }
 ```
@@ -1441,18 +1457,124 @@ export function middleware(request: NextRequest) {
 `/api/draft` is the route handler shown under "Open a draft in your own site"
 above, reading `token` and `path`.
 
-**Cookies in a frame.** The editor frames your site from another site, and a
-browser only sends a cookie into a cross-site frame when it is
-`SameSite=None; Secure`. Next sets the draft-mode cookie that way in a
-production build. `next dev` sets it `SameSite=Lax`, so re-set it as
-`SameSite=None; Secure` in your draft route while developing (browsers accept
-`Secure` on `http://localhost`). Safari's third-party cookie blocking can still
-drop it, which is why every preview load carries a fresh token and step 3
-honours it on any page.
-
-**Let Capa frame the site.** Send
-`Content-Security-Policy: frame-ancestors 'self' https://app.capacms.com` (your
-admin origin) so the editor can frame the site and nothing else can.
+**Cookies in a frame.** The editor frames your site from another site. A
+browser sends a cookie into a cross-site frame only when it is
+`SameSite=None; Secure`, and Safari 26.2 and later only when it is
+`Partitioned` too. Next sets the draft-mode cookie with neither `Partitioned`
+nor `Max-Age`, so it is dropped in Safari's frame and, everywhere else, opens
+every draft on the site until the browser closes. Pass Next's `cookies` to
+`createPreviewRoute` and `exitPreviewRoute` and they re-set it as
+`HttpOnly; Secure; SameSite=None; Partitioned; Path=/; Max-Age=3600`, and
+delete it the same way. `maxAge` changes the hour. In your own route, call
+`frameDraftCookie(cookies)` after `enable()` and `clearDraftCookie(cookies)`
+after `disable()`. A browser that drops the cookie still gets a fresh token on
+every preview load, which step 3 honours on any page.
+
+Leave `redirect` out of both routes. Each then answers with its own 307,
+marked `X-Robots-Tag: noindex, nofollow`, `Referrer-Policy: no-referrer` (the
+token is in the URL) and `Cache-Control: private, no-store`. Next's
+`redirect()` cannot carry headers, so passing it keeps the old redirect.
+
+**Mark drafts, and let Capa frame them.** `capaHeaders()` returns rules for
+`next.config`'s `headers()` that send `X-Robots-Tag: noindex, nofollow` and
+`Content-Security-Policy: frame-ancestors 'self' https://app.capacms.com` on a
+request carrying the draft cookie or a `capa-preview`, `capa-edit` or
+`capa-view` query, and on nothing else. A visitor's response, cached or not,
+is unchanged. Pass `adminOrigins` to name another admin, such as one running
+locally, and pass the same list to `createPreviewRoute`. A browser applies
+every CSP it is sent, so if your site sends its own `frame-ancestors` or
+`X-Frame-Options`, leave them off draft responses with
+`missing: [{ type: "cookie", key: DRAFT_COOKIE }]` on that rule.
+`capaMiddleware` marks its edit-mode responses noindex too, and
+`resolveEditRequest` returns the value as `robotsTag`.
+
+### Add preview to a live site without changing it
+
+A live Next.js site that reads Capa with its own code keeps that code. Preview
+adds a branch that only draft mode switches on, and draft mode is off for
+every visitor, at build time and during ISR. Reading
+`(await draftMode()).isEnabled` leaves a static page static, so a visitor gets
+the same pages, headers and cache as before.
+
+1. **Read drafts in draft mode.** In the helper that fetches from Capa, before
+   the existing fetch, read the same URL with a draft key and no cache. The
+   data has the same shape, so every page renders unchanged.
+
+   ```ts
+   // lib/capa-draft.ts
+   import "server-only";
+   import { draftMode } from "next/headers";
+
+   export async function isDraft(): Promise<boolean> {
+     // draftMode() throws outside a request (generateStaticParams, some build steps).
+     try { return (await draftMode()).isEnabled; } catch { return false; }
+   }
+
+   // in the fetch helper, before the existing fetch, which stays as it is
+   if (await isDraft()) {
+     return fetch(`https://api.capacms.com/v2/api/${endpoint}${query}`, {
+       headers: { "x-api-key": process.env.CAPA_DRAFT_KEY! },
+       cache: "no-store",
+     }).then(parse); // the helper's existing parse
+   }
+   ```
+
+   The draft key is any key of yours whose environment is not `production`
+   (see Preview is a key, not a flag). Keep it server-only, never in a
+   `NEXT_PUBLIC_` variable, and keep the branch in a `server-only` module: a
+   helper a client component also imports would bundle it.
+
+2. **Add the preview and exit routes** with `createPreviewRoute({ draftMode,
+   cookies })` and `exitPreviewRoute({ draftMode, cookies })`, as in the Quick
+   start. Set `CAPA_API_URL` to `https://api.capacms.com` and `CAPA_KEY` to
+   the production key the site already reads with, server-only: the routes
+   check the editor's token with it.
+
+3. **Add the middleware behind a matcher**, so a visitor's request never runs
+   it. Next reads `config` from the file itself, so write the matcher out:
+
+   ```ts
+   // middleware.ts (proxy.ts on Next 16)
+   import { NextResponse } from "next/server";
+   import { capaMiddleware } from "@capacms/sdk/nextjs";
+
+   export const middleware = capaMiddleware({ NextResponse });
+   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" }] },
+     ],
+   };
+   ```
+
+4. **Add `capaHeaders()`** to `next.config`'s `headers()`, as in the Quick
+   start: drafts are marked noindex and only the Capa admin can frame them.
+
+5. **Start the overlay and tag fields in draft mode.** In the root layout:
+
+   ```tsx
+   const draft = await isDraft();
+   {draft ? <CapaOverlay adminOrigins={["https://app.capacms.com"]} /> : null}
+   ```
+
+   Tag an editable field with `{...capaAttrs({ id: entry.id }, "title", draft)}`.
+   With `draft` false it returns `{}`, so a visitor's HTML gains no
+   attribute. The field is its key in the entry, which is its namespace.
+
+6. **Route handlers that set their own `Cache-Control`** must send
+   `private, no-store` in draft mode. Otherwise a CDN keeps a draft fetched by
+   the editor's browser and serves it to everyone.
+
+Do not call `editMode()`, `getCapaClient()` or `resolveEditRequest()` from a
+static or ISR page or layout. Each reads `headers()`, which makes every route
+that calls it dynamic: the HTML stays the same, but the site loses ISR and
+renders every view. `isDraft()` above is the static-safe check. The editor's
+Published view then shows the static page without the overlay.
+
+In Capa, set the project's preview URL to the site's production origin, and
+give each model with a page a route pattern, or Preview has no link to open.
 
 ### The protocol
 

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;

package/dist/nextjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_API_VERSION = exports.CAPA_ENV_ALIASES = exports.CAPA_ENV = exports.EDIT_CACHE_CONTROL = exports.DRAFT_COOKIE = exports.EDIT_HEADER = exports.EDIT_PARAM = exports.LAYOUT_PAGE = exports.gql = exports.MEDIA_TAG = exports.GRAPHQL_TAG = void 0;
+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.LAYOUT_PAGE = exports.gql = exports.MEDIA_TAG = exports.GRAPHQL_TAG = void 0;
 exports.withCache = withCache;
 exports.modelTag = modelTag;
 exports.tagsFor = tagsFor;
@@ -15,6 +15,11 @@ 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;
@@ -284,6 +289,10 @@ function pagesFor(client) {
  * 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
@@ -322,6 +331,7 @@ function verifiedEdit(headers) {
  *     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;
  *   }
  *
@@ -348,7 +358,13 @@ async function resolveEditRequest(request, client) {
     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 };
+    return {
+        edit,
+        verified,
+        headers,
+        cacheControl: edit ? exports.EDIT_CACHE_CONTROL : null,
+        robotsTag: edit ? exports.DRAFT_ROBOTS_TAG : null,
+    };
 }
 // ------------------------------------------------- five-minute integration ---
 /**
@@ -570,26 +586,166 @@ function safeSitePath(value) {
         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 { 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.
  */
 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("capa-preview") ?? "";
+        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("capa-preview") ? url.pathname : null));
+        const path = safeSitePath(url.searchParams.get("path") ?? (url.searchParams.has(exports.PREVIEW_PARAM) ? url.pathname : null));
         let claim = null;
         let failed = false;
         try {
@@ -601,18 +757,36 @@ function createPreviewRoute(input) {
         const draft = await input.draftMode();
         if (!claim) {
             draft.disable?.();
-            return input.redirect(`${path}?preview=${failed ? "unavailable" : "expired"}`);
+            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 input.redirect(safeSitePath(claim.path ?? path));
+        return go(safeSitePath(claim.path ?? path));
     };
 }
-/** `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.
+ */
 function exitPreviewRoute(input) {
     return async (request) => {
         (await input.draftMode()).disable?.();
-        return input.redirect(safeSitePath(new URL(request.url).searchParams.get("path")));
+        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 });
     };
 }
 /**
@@ -626,12 +800,25 @@ function exitPreviewRoute(input) {
  * - `?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" }] },
+ *     ],
+ *   };
  */
 function capaMiddleware(input) {
     const previewRoute = input.previewRoute ?? "/api/capa/preview";
     return async (request) => {
-        const token = request.nextUrl.searchParams.get("capa-preview");
+        const token = request.nextUrl.searchParams.get(exports.PREVIEW_PARAM);
         if (token) {
             const target = request.nextUrl.clone();
             target.pathname = previewRoute;
@@ -641,7 +828,7 @@ function capaMiddleware(input) {
             return input.NextResponse.rewrite(target);
         }
         const headers = new Headers(request.headers);
-        if (request.nextUrl.searchParams.get("capa-view") === "published") {
+        if (request.nextUrl.searchParams.get(exports.VIEW_PARAM) === "published") {
             const cookies = request.cookies
                 .getAll()
                 .filter((cookie) => cookie.name !== exports.DRAFT_COOKIE)
@@ -658,6 +845,11 @@ function capaMiddleware(input) {
         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;
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capacms/sdk",
-  "version": "1.0.0-next.7",
+  "version": "1.0.0-next.8",
   "description": "The TypeScript SDK for Capa's content API: REST and GraphQL reads typed from your models, Next.js caching and live preview, and codegen.",
   "license": "UNLICENSED",
   "homepage": "https://docs.capacms.com/api",
@@ -89,6 +89,6 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "tsc -p tsconfig.json && node --test test/comments.test.js test/codegen.test.js test/client.test.js test/next-client.test.js test/nextjs.test.js test/webhooks.test.js test/attrs.test.js test/overlay.test.js test/inflate.test.js test/field-names.test.js test/next-graphql.test.js test/graphql-codegen.test.js test/graphql-contract.test.js test/readme-snippets.test.js test/nextjs-app.test.js test/package-json.test.js test/changelog.test.js test/published-docs.test.js test/builder-messages.test.js && tsc -p test/types/tsconfig.consumer.json --noEmit && tsc -p test/types/tsconfig.nonstrict.json --noEmit"
+    "test": "tsc -p tsconfig.json && node --test test/comments.test.js test/codegen.test.js test/client.test.js test/next-client.test.js test/nextjs.test.js test/webhooks.test.js test/attrs.test.js test/overlay.test.js test/inflate.test.js test/field-names.test.js test/next-graphql.test.js test/graphql-codegen.test.js test/graphql-contract.test.js test/readme-snippets.test.js test/nextjs-app.test.js test/nextjs-preview-app.test.js test/package-json.test.js test/changelog.test.js test/published-docs.test.js test/builder-messages.test.js && tsc -p test/types/tsconfig.consumer.json --noEmit && tsc -p test/types/tsconfig.nonstrict.json --noEmit && tsc -p test/types/tsconfig.next.json --noEmit"
   }
 }