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

package/dist/esm/overlay/protocol.js

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

package/dist/esm/package.json

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

package/dist/nextjs/overlay.d.ts

@@ -1,5 +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;
 }
-export declare function CapaOverlay({ adminOrigins }: CapaOverlayProps): null;
+/**
+ * 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/nextjs/overlay.js

@@ -18,18 +18,61 @@ exports.CapaOverlay = CapaOverlay;
  *
  * 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.
+ * 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.
  */
 const react_1 = require("react");
 const navigation_1 = require("next/navigation");
-const overlay_1 = require("../overlay");
-function CapaOverlay({ adminOrigins }) {
+const index_js_1 = require("../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.
+ */
+function CapaOverlay({ adminOrigins, refresh = "in-place", refreshTimeoutMs }) {
     const router = (0, navigation_1.useRouter)();
+    const [refreshing, startRefresh] = (0, react_1.useTransition)();
+    const [, nudge] = (0, react_1.useState)(0);
+    /** One resolver per refresh waiting for its transition to commit. */
+    const waiting = (0, react_1.useRef)([]);
     // A string, so a new array with the same origins does not restart it.
     const origins = adminOrigins.join(",");
-    (0, react_1.useEffect)(() => (0, overlay_1.startOverlay)({
+    (0, react_1.useEffect)(() => (0, index_js_1.startOverlay)({
         adminOrigins: origins.split(",").filter(Boolean),
-        onRefresh: () => router.refresh(),
-    }), [origins, router]);
+        onRefresh: refresh === "reload"
+            ? undefined
+            : () => new Promise((resolve) => {
+                waiting.current.push(resolve);
+                startRefresh(() => router.refresh());
+            }),
+        refreshTimeoutMs,
+    }), [origins, router, refresh, refreshTimeoutMs]);
+    (0, react_1.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/overlay/index.d.ts

@@ -1,5 +1,5 @@
-export { acceptMessage, hoverMessage, normaliseOrigins, pickCentred, readyMessage, scrollEdge, selectMessage, visibleMessage, ADMIN_SOURCE, PROTOCOL_VERSION, SITE_SOURCE, } from "./protocol";
-export type { AdminMessage, MessageLike, SiteMessage, TaggedBox } from "./protocol";
+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
@@ -9,9 +9,21 @@ export interface OverlayOptions {
     /**
      * 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

package/dist/overlay/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SITE_SOURCE = exports.PROTOCOL_VERSION = exports.ADMIN_SOURCE = exports.visibleMessage = exports.selectMessage = exports.scrollEdge = exports.readyMessage = exports.pickCentred = exports.normaliseOrigins = exports.hoverMessage = exports.acceptMessage = void 0;
+exports.REFRESH_TIMEOUT_MS = exports.SITE_SOURCE = exports.PROTOCOL_VERSION = exports.ADMIN_SOURCE = exports.visibleMessage = exports.selectMessage = exports.scrollEdge = exports.readyMessage = exports.pickCentred = exports.normaliseOrigins = exports.hoverMessage = exports.acceptMessage = void 0;
 exports.startOverlay = startOverlay;
 /**
  * `@capacms/sdk/overlay`: the site half of Capa's live preview.
@@ -13,30 +13,52 @@ exports.startOverlay = startOverlay;
  * re-renders the draft after a save. Outside a frame it does nothing at all:
  * no listeners, no DOM, no cost.
  *
+ * A click on a tagged element selects its field. 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, so an editor can move between pages.
+ *
  * Vanilla DOM and no imports beyond the pure protocol module, so it works in
  * any framework and adds nothing to a bundle that does not call it.
  */
-const protocol_1 = require("./protocol");
-var protocol_2 = require("./protocol");
-Object.defineProperty(exports, "acceptMessage", { enumerable: true, get: function () { return protocol_2.acceptMessage; } });
-Object.defineProperty(exports, "hoverMessage", { enumerable: true, get: function () { return protocol_2.hoverMessage; } });
-Object.defineProperty(exports, "normaliseOrigins", { enumerable: true, get: function () { return protocol_2.normaliseOrigins; } });
-Object.defineProperty(exports, "pickCentred", { enumerable: true, get: function () { return protocol_2.pickCentred; } });
-Object.defineProperty(exports, "readyMessage", { enumerable: true, get: function () { return protocol_2.readyMessage; } });
-Object.defineProperty(exports, "scrollEdge", { enumerable: true, get: function () { return protocol_2.scrollEdge; } });
-Object.defineProperty(exports, "selectMessage", { enumerable: true, get: function () { return protocol_2.selectMessage; } });
-Object.defineProperty(exports, "visibleMessage", { enumerable: true, get: function () { return protocol_2.visibleMessage; } });
-Object.defineProperty(exports, "ADMIN_SOURCE", { enumerable: true, get: function () { return protocol_2.ADMIN_SOURCE; } });
-Object.defineProperty(exports, "PROTOCOL_VERSION", { enumerable: true, get: function () { return protocol_2.PROTOCOL_VERSION; } });
-Object.defineProperty(exports, "SITE_SOURCE", { enumerable: true, get: function () { return protocol_2.SITE_SOURCE; } });
+const protocol_js_1 = require("./protocol.js");
+var protocol_js_2 = require("./protocol.js");
+Object.defineProperty(exports, "acceptMessage", { enumerable: true, get: function () { return protocol_js_2.acceptMessage; } });
+Object.defineProperty(exports, "hoverMessage", { enumerable: true, get: function () { return protocol_js_2.hoverMessage; } });
+Object.defineProperty(exports, "normaliseOrigins", { enumerable: true, get: function () { return protocol_js_2.normaliseOrigins; } });
+Object.defineProperty(exports, "pickCentred", { enumerable: true, get: function () { return protocol_js_2.pickCentred; } });
+Object.defineProperty(exports, "readyMessage", { enumerable: true, get: function () { return protocol_js_2.readyMessage; } });
+Object.defineProperty(exports, "scrollEdge", { enumerable: true, get: function () { return protocol_js_2.scrollEdge; } });
+Object.defineProperty(exports, "selectMessage", { enumerable: true, get: function () { return protocol_js_2.selectMessage; } });
+Object.defineProperty(exports, "visibleMessage", { enumerable: true, get: function () { return protocol_js_2.visibleMessage; } });
+Object.defineProperty(exports, "ADMIN_SOURCE", { enumerable: true, get: function () { return protocol_js_2.ADMIN_SOURCE; } });
+Object.defineProperty(exports, "PROTOCOL_VERSION", { enumerable: true, get: function () { return protocol_js_2.PROTOCOL_VERSION; } });
+Object.defineProperty(exports, "SITE_SOURCE", { enumerable: true, get: function () { return protocol_js_2.SITE_SOURCE; } });
 const BLUE = "#2563eb";
 const TAGGED = "[data-capa-entry][data-capa-field]";
+/** What a ⌘-click on a tagged element follows when it sits in one. */
+const LINK = "a[href]";
 /** Survives the `location.reload()` fallback so the page comes back where it was. */
 const SCROLL_KEY = "capa-overlay:scrollY";
-/** How long a refresh keeps putting the scroll position back while the page re-renders. */
+/** How long a refresh keeps putting the scroll position back once the page has re-rendered. */
 const RESTORE_WINDOW_MS = 1500;
+/** How long an in-place refresh may take before the page reloads instead. */
+exports.REFRESH_TIMEOUT_MS = 10_000;
 /** `visible` is sent at most this often while the page scrolls. */
 const VISIBLE_THROTTLE_MS = 150;
+/**
+ * Apple platforms open a link with ⌘, Windows and Linux with Ctrl. Read from
+ * the browser's own platform report, falling back to the user agent.
+ */
+function isApple(nav) {
+    if (!nav)
+        return false;
+    const data = nav.userAgentData;
+    return /mac|iphone|ipad|ipod/i.test(data?.platform || nav.platform || nav.userAgent || "");
+}
+/** A usable refresh timeout: a positive number of milliseconds, or the default. */
+function timeoutOf(ms) {
+    return typeof ms === "number" && ms > 0 && Number.isFinite(ms) ? ms : exports.REFRESH_TIMEOUT_MS;
+}
 const noop = () => { };
 let running = null;
 /**
@@ -58,15 +80,26 @@ function startOverlay(options) {
     return running.dispose;
 }
 function createOverlay(initial) {
-    let origins = (0, protocol_1.normaliseOrigins)(initial.adminOrigins ?? []);
+    let origins = (0, protocol_js_1.normaliseOrigins)(initial.adminOrigins ?? []);
     let onRefresh = initial.onRefresh;
+    let refreshTimeout = timeoutOf(initial.refreshTimeoutMs);
+    const apple = isApple(typeof navigator === "undefined" ? undefined : navigator);
+    const linkHint = apple ? "⌘-click to open link" : "Ctrl-click to open link";
     /** The origin that said hello. Every message this page sends goes there and nowhere else. */
     let adminOrigin = null;
     let highlight = null;
     let outlineAll = false;
     let hovered = null;
+    /** The link the pointer is in, when it is also over a tagged element: a ⌘-click follows it. */
+    let hoveredLink = null;
     let lastReady = "";
+    /** Where a refresh keeps the page. `until` is Infinity while the refresh is still pending. */
     let pendingScroll = null;
+    /** Counts refreshes, so only the latest one settles the scroll or reloads. */
+    let refreshes = 0;
+    let refreshTimer = 0;
+    /** True while this overlay replays a ⌘-click as a plain click, which it must let through. */
+    let following = false;
     let layer = null;
     let frame = 0;
     let readyFrame = 0;
@@ -161,13 +194,16 @@ function createOverlay(initial) {
                     boxes.push(b);
             }
         }
+        // Over a link, the label says how to follow it.
+        const hint = hovered && hoveredLink ? ` · ${linkHint}` : "";
         if (hovered && hovered.isConnected && !active.includes(hovered)) {
-            const b = box(hovered, "hover", hovered.getAttribute("data-capa-field"));
+            const b = box(hovered, "hover", `${hovered.getAttribute("data-capa-field") ?? ""}${hint}`);
             if (b)
                 boxes.push(b);
         }
         active.forEach((el, i) => {
-            const label = i === 0 ? (highlight?.field ?? "entry") : null;
+            const name = i === 0 ? (highlight?.field ?? "entry") : null;
+            const label = el === hovered && hint ? `${name ?? el.getAttribute("data-capa-field") ?? ""}${hint}` : name;
             const b = box(el, "active", label);
             if (b)
                 boxes.push(b);
@@ -195,7 +231,7 @@ function createOverlay(initial) {
         if (!force && key === lastReady)
             return;
         lastReady = key;
-        post((0, protocol_1.readyMessage)(path, entries));
+        post((0, protocol_js_1.readyMessage)(path, entries));
     };
     const scheduleReady = () => {
         if (readyFrame)
@@ -222,15 +258,15 @@ function createOverlay(initial) {
                 bottom: rect.bottom,
             };
         });
-        const edge = (0, protocol_1.scrollEdge)(window.scrollY, window.innerHeight, document.documentElement.scrollHeight);
-        const pick = (0, protocol_1.pickCentred)(boxes, window.innerHeight, edge);
+        const edge = (0, protocol_js_1.scrollEdge)(window.scrollY, window.innerHeight, document.documentElement.scrollHeight);
+        const pick = (0, protocol_js_1.pickCentred)(boxes, window.innerHeight, edge);
         if (!pick)
             return;
         const key = `${pick.entryId}\n${pick.field}`;
         if (key === lastVisible)
             return;
         lastVisible = key;
-        post((0, protocol_1.visibleMessage)(pick.entryId, pick.field));
+        post((0, protocol_js_1.visibleMessage)(pick.entryId, pick.field));
     };
     const onScroll = () => {
         render();
@@ -263,27 +299,63 @@ function createOverlay(initial) {
     catch {
         // Storage blocked (a sandboxed or third-party frame): start at the top.
     }
+    /** The editor scrolled on purpose: stop putting the old position back. */
+    const onScrollIntent = () => {
+        pendingScroll = null;
+    };
+    const reload = (y) => {
+        try {
+            window.sessionStorage.setItem(SCROLL_KEY, String(y));
+        }
+        catch {
+            // Nowhere to keep it; the reload lands at the top.
+        }
+        window.location.reload();
+    };
+    /**
+     * Re-render the draft in place, or reload. While an in-place refresh is
+     * pending the position is held (a page whose re-render moves things keeps
+     * its place), and for a moment after it lands. A refresh that fails, or is
+     * still pending after `refreshTimeout`, reloads from where the editor is.
+     */
     const refresh = () => {
         const y = window.scrollY;
-        if (!onRefresh) {
-            try {
-                window.sessionStorage.setItem(SCROLL_KEY, String(y));
-            }
-            catch {
-                // Nowhere to keep it; the reload lands at the top.
-            }
-            window.location.reload();
+        const refreshFn = onRefresh;
+        if (!refreshFn) {
+            reload(y);
             return;
         }
-        pendingScroll = { y, until: Date.now() + RESTORE_WINDOW_MS };
+        const id = ++refreshes;
+        pendingScroll = { y, until: Infinity };
+        if (refreshTimer)
+            window.clearTimeout(refreshTimer);
+        refreshTimer = window.setTimeout(() => {
+            refreshTimer = 0;
+            if (id === refreshes)
+                reload(pendingScroll?.y ?? window.scrollY);
+        }, refreshTimeout);
         Promise.resolve()
-            .then(() => onRefresh?.())
-            .catch(() => window.location.reload())
-            .finally(() => window.requestAnimationFrame(restoreScroll));
+            .then(() => refreshFn())
+            .then(() => {
+            // A later refresh owns the timer and the scroll from here on.
+            if (id !== refreshes)
+                return;
+            window.clearTimeout(refreshTimer);
+            refreshTimer = 0;
+            if (pendingScroll)
+                pendingScroll = { y: pendingScroll.y, until: Date.now() + RESTORE_WINDOW_MS };
+            window.requestAnimationFrame(restoreScroll);
+        }, () => {
+            if (id !== refreshes)
+                return;
+            window.clearTimeout(refreshTimer);
+            refreshTimer = 0;
+            reload(pendingScroll?.y ?? window.scrollY);
+        });
     };
     // ------------------------------------------------------------ messages ---
     const onMessage = (event) => {
-        const message = (0, protocol_1.acceptMessage)(event, origins, window.parent);
+        const message = (0, protocol_js_1.acceptMessage)(event, origins, window.parent);
         if (!message)
             return;
         switch (message.type) {
@@ -316,31 +388,71 @@ function createOverlay(initial) {
         }
     };
     // --------------------------------------------------------- interaction ---
-    const taggedFrom = (target) => {
+    const closestFrom = (target, selector) => {
         const el = target;
-        return el && typeof el.closest === "function" ? el.closest(TAGGED) : null;
+        return el && typeof el.closest === "function" ? el.closest(selector) : null;
+    };
+    const taggedFrom = (target) => closestFrom(target, TAGGED);
+    /**
+     * A ⌘-click on a tagged link: click the same spot again, without the
+     * modifier, and let it through. The site then follows the link in this
+     * frame exactly as it would for a visitor's click: a Next `<Link>`
+     * navigates client-side, a plain `<a>` loads the page, `target` and the
+     * site's own handlers are honoured. The browser's own ⌘-click would open a
+     * new tab, outside the editor.
+     */
+    const follow = (event) => {
+        const target = event.target;
+        const click = new MouseEvent("click", {
+            bubbles: true,
+            cancelable: true,
+            composed: true,
+            view: window,
+            detail: event.detail,
+            screenX: event.screenX,
+            screenY: event.screenY,
+            clientX: event.clientX,
+            clientY: event.clientY,
+            button: 0,
+        });
+        following = true;
+        try {
+            target.dispatchEvent(click);
+        }
+        finally {
+            following = false;
+        }
     };
     const onClick = (event) => {
         // Only once the admin has said hello: a framed page that is not talking to
-        // Capa keeps its links working.
-        if (!adminOrigin)
+        // Capa keeps its links working. And never the plain click `follow` sends.
+        if (!adminOrigin || following)
             return;
         const el = taggedFrom(event.target);
         if (!el)
             return;
         event.preventDefault();
         event.stopPropagation();
-        post((0, protocol_1.selectMessage)(el.getAttribute("data-capa-entry") ?? "", el.getAttribute("data-capa-field") ?? ""));
+        if ((apple ? event.metaKey : event.ctrlKey) && closestFrom(event.target, LINK)) {
+            follow(event);
+            return;
+        }
+        post((0, protocol_js_1.selectMessage)(el.getAttribute("data-capa-entry") ?? "", el.getAttribute("data-capa-field") ?? ""));
     };
     const updateHover = () => {
         hoverFrame = 0;
         const el = taggedFrom(lastPointer);
-        if (el === hovered)
+        const link = el ? closestFrom(lastPointer, LINK) : null;
+        if (el === hovered && link === hoveredLink)
             return;
+        const moved = el !== hovered;
         hovered = el;
-        post(el
-            ? (0, protocol_1.hoverMessage)(el.getAttribute("data-capa-entry") ?? "", el.getAttribute("data-capa-field"))
-            : (0, protocol_1.hoverMessage)("", null));
+        hoveredLink = link;
+        if (moved) {
+            post(el
+                ? (0, protocol_js_1.hoverMessage)(el.getAttribute("data-capa-entry") ?? "", el.getAttribute("data-capa-field"))
+                : (0, protocol_js_1.hoverMessage)("", null));
+        }
         render();
     };
     const onPointerMove = (event) => {
@@ -363,10 +475,13 @@ function createOverlay(initial) {
         render();
         restoreScroll();
     });
+    const INTENT = ["wheel", "touchmove", "keydown"];
     window.addEventListener("message", onMessage);
     window.addEventListener("scroll", onScroll, { capture: true, passive: true });
     window.addEventListener("resize", render, { passive: true });
     window.addEventListener("popstate", scheduleReady);
+    for (const type of INTENT)
+        window.addEventListener(type, onScrollIntent, { capture: true, passive: true });
     document.addEventListener("click", onClick, true);
     document.addEventListener("pointermove", onPointerMove, { capture: true, passive: true });
     document.documentElement.addEventListener("pointerleave", onPointerLeave);
@@ -376,6 +491,8 @@ function createOverlay(initial) {
         window.removeEventListener("scroll", onScroll, { capture: true });
         window.removeEventListener("resize", render);
         window.removeEventListener("popstate", scheduleReady);
+        for (const type of INTENT)
+            window.removeEventListener(type, onScrollIntent, { capture: true });
         document.removeEventListener("click", onClick, true);
         document.removeEventListener("pointermove", onPointerMove, { capture: true });
         document.documentElement.removeEventListener("pointerleave", onPointerLeave);
@@ -385,6 +502,11 @@ function createOverlay(initial) {
                 window.cancelAnimationFrame(id);
         if (visibleTimer)
             window.clearTimeout(visibleTimer);
+        // A refresh still pending when the overlay goes must not reload the page later.
+        if (refreshTimer)
+            window.clearTimeout(refreshTimer);
+        refreshTimer = 0;
+        refreshes++;
         layer?.remove();
         layer = null;
         if (running?.dispose === dispose)
@@ -393,8 +515,9 @@ function createOverlay(initial) {
     return {
         dispose,
         setOptions: (next) => {
-            origins = (0, protocol_1.normaliseOrigins)(next.adminOrigins ?? []);
+            origins = (0, protocol_js_1.normaliseOrigins)(next.adminOrigins ?? []);
             onRefresh = next.onRefresh;
+            refreshTimeout = timeoutOf(next.refreshTimeoutMs);
             if (adminOrigin && !origins.includes(adminOrigin))
                 adminOrigin = null;
         },