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

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 ## 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

package/README.md

@@ -1275,6 +1275,13 @@ editor sees the path without a link to open it.
 
 ### Quick start (Next.js)
 
+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:
@@ -1422,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
 
@@ -1552,11 +1593,31 @@ the same pages, headers and cache as before.
 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:
+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 ? <CapaOverlay adminOrigins={["https://app.capacms.com"]} /> : null}
+   {draft ? <CapaPreview adminOrigins={["https://app.capacms.com"]} /> : null}
    ```
 
    Tag an editable field with `{...capaAttrs({ id: entry.id }, "title", draft)}`.
@@ -1576,9 +1637,85 @@ 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:
+
+```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`.
@@ -1593,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;