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

package/CHANGELOG.md

@@ -2,6 +2,69 @@
 
 ## Unreleased
 
+- 1.0.0-next.9. Live preview on sites in production.
+  `@capacms/sdk/nextjs/overlay` and `@capacms/sdk/overlay` reach a bundler as
+  ES modules (the `import` condition, built to `dist/esm`) and stay CommonJS
+  for `require`. The CommonJS overlay's `require("next/navigation")` made
+  webpack keep every `next/navigation` export in the module that re-exports
+  them, which sits in chunks a visitor loads, so loading the overlay, even
+  lazily, changed a site's visitor chunks (17 on one site). An ES
+  `import { useRouter }` leaves them as they were.
+- `<CapaOverlay />`: a save's `router.refresh()` runs in a React transition,
+  and while it is pending the overlay makes a no-op state update every 300 ms.
+  Under React 19.2 and Next 15.5 a draft refresh could stay suspended after
+  its whole response had arrived, inside a Suspense boundary already on
+  screen (a root `loading.tsx` makes one), and show nothing until some other
+  state update. A refresh that has not landed within `refreshTimeoutMs`
+  (10 seconds) reloads the page instead, at the same scroll position.
+  `refresh="reload"` reloads on every save.
+- `startOverlay`: `onRefresh` may return a promise. The overlay waits for it
+  up to `refreshTimeoutMs` and reloads if it rejects or is still pending; a
+  function that returns nothing counts as done at once, as before. A reload
+  after a failed refresh now keeps the scroll position too. The position is
+  held while a refresh is pending, and an editor who scrolls meanwhile is not
+  pulled back. `REFRESH_TIMEOUT_MS` is exported.
+- Inside the editor's frame, a ⌘-click (Ctrl-click on Windows and Linux) on a
+  tagged element that is a link, or sits inside one, follows the link in the
+  frame instead of selecting the field, and the hover label says so. A plain
+  click still selects, and an untagged link navigates as before. No message
+  between the overlay and the editor changed.
+- Docs: load the overlay lazily from a small client component, since a direct
+  import from the root layout puts its code in the layout's chunk, which every
+  visitor downloads; and skip a page transition's `FrozenRoute` in draft mode,
+  or a save fetches the draft and shows nothing.
+- 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 +228,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,16 @@ 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:
+Preview needs `@capacms/sdk` 1.0.0-next.8 or later. The `latest` tag is
+older and has no `capaHeaders`, so install the `next` tag:
+
+```sh
+pnpm add @capacms/sdk@next
+```
+
+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 +1293,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 +1359,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 +1410,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;
 }
 ```
@@ -1406,11 +1429,45 @@ import { CapaOverlay } from "@capacms/sdk/nextjs/overlay";
 `@capacms/sdk/overlay` in your own effect.
 
 Render it from your root layout only in edit mode
-(`await editMode({ draftMode, headers })`), so a visitor never downloads it.
+(`await editMode({ draftMode, headers })`), so it never runs for a visitor.
+Imported this way, its code still sits in the layout's chunk, which every
+visitor downloads. To keep it out, load it lazily from a small client
+component, as step 5 of "Add preview to a live site without changing it"
+shows. Both overlay entry points reach a bundler as ES modules, so loading
+the overlay leaves the rest of a visitor's chunks as they were.
+
 `startOverlay` returns a disposer and is safe to call twice. Outside a frame it
 does nothing at all, and inside one it only listens to a parent window at one of
-`adminOrigins`. Without `onRefresh` a save reloads the page; the scroll position
-is kept either way.
+`adminOrigins`.
+
+**Clicks inside the editor's frame.** A click on a tagged element selects its
+field in the editor. A ⌘-click (Ctrl-click on Windows and Linux) on a tagged
+element that is a link, or sits inside one, follows the link inside the frame
+instead, so an editor can move between pages. The hover label says so over a
+link. A link with no tag on or around it navigates as usual.
+
+**After a save.** `<CapaOverlay />` re-renders the draft in place with
+`router.refresh()` and keeps the scroll position.
+
+- The refresh runs in a React transition. While it is pending, the overlay
+  makes a no-op state update every 300 ms. Under React 19.2 and Next 15.5, a
+  draft refresh can otherwise stay suspended after its whole response has
+  arrived, when the page sits inside a Suspense boundary that is already on
+  screen (a root `loading.tsx` makes one), and show nothing until some other
+  state update.
+- A refresh that has not landed after `refreshTimeoutMs` (10 seconds) reloads
+  the page instead, which comes back to the same scroll position.
+- `refresh="reload"` reloads the page on every save, for a site that prefers
+  it:
+
+```tsx
+<CapaOverlay adminOrigins={["https://app.capacms.com"]} refresh="reload" />
+```
+
+With `startOverlay`, `onRefresh` may return a promise that settles once the new
+draft is on screen. The overlay waits for it up to `refreshTimeoutMs`, and
+reloads if it rejects or is still pending. Without `onRefresh` every save
+reloads. The scroll position is kept every way.
 
 ### 3. Accept the preview link on any page
 
@@ -1441,22 +1498,224 @@ 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.
+**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.** Load the overlay
+   lazily from a small client component, so its code is not in a chunk a
+   visitor downloads, and render that component from the root layout in
+   draft mode only:
+
+   ```tsx
+   // components/capa-preview.tsx
+   "use client";
+   import { lazy, Suspense } from "react";
+
+   const CapaOverlay = lazy(() =>
+     import("@capacms/sdk/nextjs/overlay").then((m) => ({ default: m.CapaOverlay })),
+   );
+
+   export default function CapaPreview({ adminOrigins }: { adminOrigins: string[] }) {
+     return (
+       <Suspense fallback={null}>
+         <CapaOverlay adminOrigins={adminOrigins} />
+       </Suspense>
+     );
+   }
+
+   // app/layout.tsx
+   const draft = await isDraft();
+   {draft ? <CapaPreview 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.
+
+### A save that shows nothing: a page transition that freezes the route
+
+A site that animates page changes with framer-motion often wraps each page in
+a `FrozenRoute`, which pins Next's `LayoutRouterContext` so the page that is
+leaving keeps its content while it animates out:
 
-**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.
+```tsx
+"use client";
+
+import { useContext, useRef } from "react";
+import { LayoutRouterContext } from "next/dist/shared/lib/app-router-context.shared-runtime";
+
+const FrozenRoute = ({ children }: { children: React.ReactNode }) => {
+  const context = useContext(LayoutRouterContext);
+  const frozen = useRef(context).current;
+
+  return (
+    <LayoutRouterContext.Provider value={frozen}>
+      {children}
+    </LayoutRouterContext.Provider>
+  );
+};
+
+export default FrozenRoute;
+```
+
+The pinned context keeps the page as the frame first drew it. After a save,
+`router.refresh()` fetches the draft and nothing on screen changes, and no
+overlay setting can reach inside the freeze. Skip it in draft mode only. Give
+the page-transition wrapper a `live` prop:
+
+```tsx
+"use client";
+
+import { usePathname } from "next/navigation";
+import { AnimatePresence, motion } from "framer-motion";
+import FrozenRoute from "./frozen-route";
+
+const PageAnimatePresence = ({
+  children,
+  live,
+}: {
+  children: React.ReactNode;
+  /** Capa preview (draft mode only): no freeze, so an editor's save shows in place. */
+  live?: boolean;
+}) => {
+  const pathname = usePathname();
+
+  return (
+    <AnimatePresence mode="wait">
+      <motion.div className="flex flex-col flex-grow" key={pathname}>
+        {live ? children : <FrozenRoute>{children}</FrozenRoute>}
+      </motion.div>
+    </AnimatePresence>
+  );
+};
+
+export default PageAnimatePresence;
+```
+
+and pass it from the root layout as a conditional spread, so a visitor's
+props, and the RSC payload that carries them, are exactly what they were:
+
+```tsx
+// app/layout.tsx
+const draft = await isDraft();
+
+<PageAnimatePresence {...(draft ? { live: true } : {})}>
+  {children}
+</PageAnimatePresence>
+```
+
+Writing `live={draft}` instead would send `live: false` to every visitor.
+To find the freeze, search the site for `LayoutRouterContext`.
 
 ### The protocol
 
-Every message is `{ source, v: 1, type, ...fields }`. The admin sends
+Every message is `{ source, v: 1, type, ...fields }`. `source` is
+`capa-admin` on the admin's messages and `capa` on the site's. The admin sends
 `hello`, `highlight { entryId, field }` (`entryId: ""` clears), `outline { on }`
 and `refresh`. The site answers `ready { path, entries }` after every hello and
 every navigation, `select { entryId, field }` on a click, and `hover`.
@@ -1471,6 +1730,10 @@ and at the very bottom the bottommost. The editor's "Follow the page" scrolls
 the form to that field. An overlay older than 1.0.0-next.2 never sends it, and
 the editor then does not follow.
 
+Following a link with ⌘-click sends no message of its own: the page the link
+leads to answers with `ready`, as after any navigation, so an editor of any
+version follows along.
+
 ## Not yet
 
 `--select-from-depth`, `capa convert-url`, GraphQL mutations, and `/api/`

package/dist/esm/nextjs/overlay.d.ts

@@ -0,0 +1,30 @@
+export interface CapaOverlayProps {
+    /** The Capa admin origins allowed to drive the overlay. */
+    adminOrigins: string[];
+    /**
+     * How a save shows. `"in-place"` (the default) re-renders the draft with
+     * `router.refresh()`, and reloads the page only if that has not landed
+     * within `refreshTimeoutMs`. `"reload"` reloads the page on every save.
+     * The scroll position is kept either way.
+     */
+    refresh?: "in-place" | "reload";
+    /** How long an in-place refresh may take before the page reloads instead. 10 seconds. */
+    refreshTimeoutMs?: number;
+}
+/**
+ * The refresh runs in a transition, so `isPending` says when the new draft
+ * has been committed to the screen, and the overlay settles the refresh
+ * then: it puts the scroll position back, and a refresh that has not
+ * committed within `refreshTimeoutMs` reloads.
+ *
+ * While the transition is pending the overlay makes a no-op state update
+ * every `REFRESH_NUDGE_MS`. React 19.2 under Next 15.5 can leave a draft
+ * refresh suspended after every part of its streamed response has arrived:
+ * the page suspends inside an already visible Suspense boundary (a root
+ * `loading.tsx` makes one around every page), and the signal that its data
+ * is ready is lost, so nothing commits until some other state update. Any
+ * state update makes React retry the suspended render, which then completes.
+ * A refresh that commits on its own stops the nudges at once. Draft mode
+ * only: a visitor never runs this component.
+ */
+export declare function CapaOverlay({ adminOrigins, refresh, refreshTimeoutMs }: CapaOverlayProps): null;

package/dist/esm/nextjs/overlay.js

@@ -0,0 +1,75 @@
+"use client";
+/**
+ * `<CapaOverlay />`: Capa's live preview overlay as one Next.js client
+ * component (M6).
+ *
+ *   // app/layout.tsx (a server component)
+ *   import { CapaOverlay } from "@capacms/sdk/nextjs/overlay";
+ *   {edit ? <CapaOverlay adminOrigins={["https://app.capacms.com"]} /> : null}
+ *
+ * Render it only in edit mode (`editMode()` from `@capacms/sdk/nextjs`), so a
+ * visitor never downloads it. Inside the Capa editor it outlines the focused
+ * field, reports clicks back, and on a save re-renders the page with
+ * `router.refresh()`, keeping the scroll position. Outside a Capa frame it does
+ * nothing at all.
+ *
+ * Its own entry point, apart from `@capacms/sdk/nextjs`, because it imports
+ * `react` and `next/navigation` and is a client module: the server helpers must
+ * stay free of both. A bundler that imports it gets an ES module, so it sees
+ * that only `useRouter` is used from `next/navigation` and leaves the chunks a
+ * visitor loads as they were.
+ */
+import { useEffect, useRef, useState, useTransition } from "react";
+import { useRouter } from "next/navigation";
+import { startOverlay } from "../overlay/index.js";
+/**
+ * While a refresh is pending, the overlay updates its own unused state this
+ * often. See `CapaOverlay` for why.
+ */
+const REFRESH_NUDGE_MS = 300;
+/**
+ * The refresh runs in a transition, so `isPending` says when the new draft
+ * has been committed to the screen, and the overlay settles the refresh
+ * then: it puts the scroll position back, and a refresh that has not
+ * committed within `refreshTimeoutMs` reloads.
+ *
+ * While the transition is pending the overlay makes a no-op state update
+ * every `REFRESH_NUDGE_MS`. React 19.2 under Next 15.5 can leave a draft
+ * refresh suspended after every part of its streamed response has arrived:
+ * the page suspends inside an already visible Suspense boundary (a root
+ * `loading.tsx` makes one around every page), and the signal that its data
+ * is ready is lost, so nothing commits until some other state update. Any
+ * state update makes React retry the suspended render, which then completes.
+ * A refresh that commits on its own stops the nudges at once. Draft mode
+ * only: a visitor never runs this component.
+ */
+export function CapaOverlay({ adminOrigins, refresh = "in-place", refreshTimeoutMs }) {
+    const router = useRouter();
+    const [refreshing, startRefresh] = useTransition();
+    const [, nudge] = useState(0);
+    /** One resolver per refresh waiting for its transition to commit. */
+    const waiting = useRef([]);
+    // A string, so a new array with the same origins does not restart it.
+    const origins = adminOrigins.join(",");
+    useEffect(() => startOverlay({
+        adminOrigins: origins.split(",").filter(Boolean),
+        onRefresh: refresh === "reload"
+            ? undefined
+            : () => new Promise((resolve) => {
+                waiting.current.push(resolve);
+                startRefresh(() => router.refresh());
+            }),
+        refreshTimeoutMs,
+    }), [origins, router, refresh, refreshTimeoutMs]);
+    useEffect(() => {
+        if (!refreshing) {
+            // Committed: every refresh started before now is on screen.
+            for (const settle of waiting.current.splice(0))
+                settle();
+            return;
+        }
+        const timer = window.setInterval(() => nudge((n) => n + 1), REFRESH_NUDGE_MS);
+        return () => window.clearInterval(timer);
+    }, [refreshing]);
+    return null;
+}

package/dist/esm/overlay/index.d.ts

@@ -0,0 +1,32 @@
+export { acceptMessage, hoverMessage, normaliseOrigins, pickCentred, readyMessage, scrollEdge, selectMessage, visibleMessage, ADMIN_SOURCE, PROTOCOL_VERSION, SITE_SOURCE, } from "./protocol.js";
+export type { AdminMessage, MessageLike, SiteMessage, TaggedBox } from "./protocol.js";
+export interface OverlayOptions {
+    /**
+     * The Capa admin origins allowed to drive this page, for example
+     * `["https://app.capacms.com"]`. A message from anywhere else is ignored.
+     */
+    adminOrigins: string[];
+    /**
+     * How to re-render the draft after the editor saves. `router.refresh()` in a
+     * Next app. Without it the page reloads. Scroll position is kept either way.
+     *
+     * Return a promise that settles once the new draft is on screen, and the
+     * overlay waits for it: a promise that rejects, or is still pending after
+     * `refreshTimeoutMs`, falls back to a reload, which keeps the scroll
+     * position too. A function that returns nothing counts as done at once.
+     */
+    onRefresh?: () => void | Promise<void>;
+    /**
+     * How long `onRefresh`'s promise may stay pending before the page reloads
+     * instead. 10 seconds.
+     */
+    refreshTimeoutMs?: number;
+}
+/** How long an in-place refresh may take before the page reloads instead. */
+export declare const REFRESH_TIMEOUT_MS = 10000;
+/**
+ * Start the overlay. Returns a disposer that removes every listener and the
+ * drawing layer. Calling it again while it runs updates the options and returns
+ * the same disposer, so a React effect that runs twice does not listen twice.
+ */
+export declare function startOverlay(options: OverlayOptions): () => void;