@capacms/sdk 1.0.0-next.0 → 1.0.0-next.2

package/README.md

@@ -326,6 +326,107 @@ const capa = await draftClient({
 Set the preview base URL for your project in Capa (Settings), otherwise the
 editor sees the path without a link to open it.
 
+## Live preview
+
+The Capa editor can show your site beside the form: focus a field and its spot
+on the page is outlined, click the page and the editor jumps to the field, save
+and the draft re-renders in place. It needs three things on your side. A
+complete, runnable example is `examples/sdk-demo` in this repository.
+
+### 1. Tag what an editor can click
+
+`capaAttrs(entry, field, enabled)` from `@capacms/sdk/next` returns the two
+attributes the overlay looks for. `field` is the field's namespace, which is its
+key in `entry.fields`, and it autocompletes when the entry is typed. Pass the
+draft flag as `enabled` so a published page ships no entry ids.
+
+```tsx
+import { capaAttrs } from "@capacms/sdk/next";
+
+<h1 {...capaAttrs(article, "title", isDraft)}>{article.fields.title}</h1>
+```
+
+### 2. Start the overlay in draft mode
+
+```tsx
+// app/capa-overlay.tsx
+"use client";
+import { useEffect } from "react";
+import { useRouter } from "next/navigation";
+import { startOverlay } from "@capacms/sdk/overlay";
+
+export function CapaOverlay({ adminOrigins }: { adminOrigins: string[] }) {
+  const router = useRouter();
+  useEffect(() => startOverlay({ adminOrigins, onRefresh: () => router.refresh() }), [adminOrigins, router]);
+  return null;
+}
+```
+
+Render it from your root layout only when `(await draftMode()).isEnabled`.
+`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.
+
+### 3. Accept the preview link on any page
+
+The editor loads `<preview base URL><path>?capa-preview=<token>`. Honour the
+token on the request itself, not only on a dedicated route: rewrite any request
+carrying it to your draft route, verify it with `preview`, enable draft mode and
+redirect back.
+
+```ts
+// middleware.ts
+export function middleware(request: NextRequest) {
+  // The editor's Published view: render this one request without draft mode.
+  if (request.nextUrl.searchParams.get("capa-view") === "published") {
+    const headers = new Headers(request.headers);
+    const cookies = request.cookies.getAll().filter((c) => c.name !== "__prerender_bypass");
+    headers.set("cookie", cookies.map((c) => `${c.name}=${encodeURIComponent(c.value)}`).join("; "));
+    return NextResponse.next({ request: { headers } });
+  }
+  const token = request.nextUrl.searchParams.get("capa-preview");
+  if (!token) return NextResponse.next();
+  const target = request.nextUrl.clone();
+  target.pathname = "/api/draft";
+  target.search = `?token=${encodeURIComponent(token)}&path=${encodeURIComponent(request.nextUrl.pathname)}`;
+  return NextResponse.rewrite(target);
+}
+```
+
+`/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.
+
+### The protocol
+
+Every message is `{ source, v: 1, type, ...fields }`. 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`.
+`acceptMessage(event, allowedOrigins, parent)` is the site's filter, exported
+for your own tests.
+
+Since 1.0.0-next.2 the site also sends `visible { entryId, field }` while the
+page scrolls (at most every 150ms, and only when it changes): the tagged element
+at the centre of the viewport, chosen by `pickCentred`. At the very top of a
+page, where a heading can never reach the centre, it is the topmost visible
+element instead, and at the very bottom the bottommost. The editor's "Follow the
+page" scrolls the form to that field. It is additive and still `v: 1`: an older
+overlay never sends it and the editor simply does not follow.
+
 ## Not yet
 
 `--select-from-depth`, `capa convert-url`, `capa persist`, GraphQL, and `/api/`

package/dist/next/attrs.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The attributes that make a rendered field clickable in Capa's live preview.
+ *
+ *   <h1 {...capaAttrs(entry, "title", isDraft)}>{entry.fields.title}</h1>
+ *
+ * `field` is the field's namespace, which is the key it has in `entry.fields`:
+ * the API renders every field under its namespace, and the Capa editor tags
+ * each field row with that same namespace, so one string names the field on
+ * both sides of the preview frame.
+ *
+ * Pass `enabled = false` outside draft mode and the element carries nothing, so
+ * a published page never ships entry ids in its markup.
+ */
+export type CapaAttrs = {
+    "data-capa-entry": string;
+    "data-capa-field": string;
+} | {
+    "data-capa-entry"?: undefined;
+    "data-capa-field"?: undefined;
+};
+export declare function capaAttrs<T = Record<string, unknown>>(entry: {
+    id: string;
+    fields?: T;
+}, field: Extract<keyof T, string>, enabled?: boolean): CapaAttrs;

package/dist/next/attrs.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.capaAttrs = capaAttrs;
+function capaAttrs(entry, field, enabled = true) {
+    if (!enabled)
+        return {};
+    return { "data-capa-entry": entry.id, "data-capa-field": field };
+}

package/dist/next/index.d.ts

@@ -1,3 +1,5 @@
 export { CapaError, createClient, isCapaError, resolveNextConfig, serializeSelect, } from "./client";
+export { capaAttrs } from "./attrs";
+export type { CapaAttrs } from "./attrs";
 export type { CallOptions, CapaNextClient, CapaNextConfig, EntriesResource, Entry, Filter, FilterOperator, FilterScalar, FilterValue, GetOptions, ListOptions, Page, PageDetail, PageInfo, PageSummary, PagesListOptions, PagesResource, PreviewClaim, ResponseMeta, Single, } from "./client";
 export type { CapaRelation, CapaRelationList, RelationSelectOptions, Select, SelectItem, SelectSort, } from "./select-types";

package/dist/next/index.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.serializeSelect = exports.resolveNextConfig = exports.isCapaError = exports.createClient = exports.CapaError = void 0;
+exports.capaAttrs = exports.serializeSelect = exports.resolveNextConfig = exports.isCapaError = exports.createClient = exports.CapaError = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "CapaError", { enumerable: true, get: function () { return client_1.CapaError; } });
 Object.defineProperty(exports, "createClient", { enumerable: true, get: function () { return client_1.createClient; } });
 Object.defineProperty(exports, "isCapaError", { enumerable: true, get: function () { return client_1.isCapaError; } });
 Object.defineProperty(exports, "resolveNextConfig", { enumerable: true, get: function () { return client_1.resolveNextConfig; } });
 Object.defineProperty(exports, "serializeSelect", { enumerable: true, get: function () { return client_1.serializeSelect; } });
+var attrs_1 = require("./attrs");
+Object.defineProperty(exports, "capaAttrs", { enumerable: true, get: function () { return attrs_1.capaAttrs; } });

package/dist/nextjs/index.js

@@ -94,9 +94,22 @@ function routeOf(file) {
     if (typeof file !== "string" || file === "") {
         throw new TypeError("@capacms/sdk/nextjs: routeOf needs a file path.");
     }
-    // `import.meta.url` is a file: URL, and a Windows path uses backslashes.
-    const withoutScheme = file.startsWith("file://") ? file.slice("file://".length) : file;
-    const normalised = withoutScheme.replace(/\\/g, "/").split("?")[0];
+    // `import.meta.url` is a file: URL, and a Windows path uses backslashes. A
+    // file: URL is percent-encoded (`[slug]` arrives as `%5Bslug%5D`), so it is
+    // decoded; a plain path is taken as written.
+    const isUrl = file.startsWith("file://");
+    const withoutScheme = isUrl ? file.slice("file://".length) : file;
+    const unquoted = withoutScheme.split("?")[0].split("#")[0];
+    let decoded = unquoted;
+    if (isUrl) {
+        try {
+            decoded = decodeURIComponent(unquoted);
+        }
+        catch {
+            // A malformed escape: keep the raw text and let the checks below judge it.
+        }
+    }
+    const normalised = decoded.replace(/\\/g, "/");
     const parts = normalised.split("/").filter((part) => part !== "" && part !== ".");
     // The LAST router root wins, so a project with its own `app/` inside
     // `packages/site/app/...` resolves against the one nearest the route.

package/dist/overlay/index.d.ts

@@ -0,0 +1,20 @@
+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 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.
+     */
+    onRefresh?: () => void | Promise<void>;
+}
+/**
+ * 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;

package/dist/overlay/index.js

@@ -0,0 +1,402 @@
+"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.startOverlay = startOverlay;
+/**
+ * `@capacms/sdk/overlay`: the site half of Capa's live preview.
+ *
+ *   "use client";
+ *   useEffect(() => startOverlay({ adminOrigins: ["https://app.capacms.com"] }), []);
+ *
+ * Inside the Capa editor's preview frame this outlines the element an editor is
+ * working on, reports clicks on tagged elements back to the editor, and
+ * re-renders the draft after a save. Outside a frame it does nothing at all:
+ * no listeners, no DOM, no cost.
+ *
+ * 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 BLUE = "#2563eb";
+const TAGGED = "[data-capa-entry][data-capa-field]";
+/** 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. */
+const RESTORE_WINDOW_MS = 1500;
+/** `visible` is sent at most this often while the page scrolls. */
+const VISIBLE_THROTTLE_MS = 150;
+const noop = () => { };
+let running = null;
+/**
+ * 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.
+ */
+function startOverlay(options) {
+    if (typeof window === "undefined" || typeof document === "undefined")
+        return noop;
+    // Not framed: this is an ordinary visit to the site.
+    if (window.parent === window)
+        return noop;
+    if (running) {
+        running.setOptions(options);
+        return running.dispose;
+    }
+    running = createOverlay(options);
+    return running.dispose;
+}
+function createOverlay(initial) {
+    let origins = (0, protocol_1.normaliseOrigins)(initial.adminOrigins ?? []);
+    let onRefresh = initial.onRefresh;
+    /** 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;
+    let lastReady = "";
+    let pendingScroll = null;
+    let layer = null;
+    let frame = 0;
+    let readyFrame = 0;
+    let hoverFrame = 0;
+    let lastPointer = null;
+    let visibleTimer = 0;
+    let lastVisible = "";
+    const post = (message) => {
+        if (!adminOrigin)
+            return;
+        window.parent.postMessage(message, adminOrigin);
+    };
+    // ------------------------------------------------------------- drawing ---
+    const ensureLayer = () => {
+        if (layer && layer.isConnected)
+            return layer;
+        layer = document.createElement("div");
+        layer.setAttribute("data-capa-overlay", "");
+        layer.setAttribute("aria-hidden", "true");
+        Object.assign(layer.style, {
+            position: "fixed",
+            inset: "0",
+            pointerEvents: "none",
+            zIndex: "2147483647",
+            overflow: "hidden",
+        });
+        document.body.appendChild(layer);
+        return layer;
+    };
+    const tagged = () => Array.from(document.querySelectorAll(TAGGED));
+    const matching = (entryId, field) => tagged().filter((el) => el.getAttribute("data-capa-entry") === entryId &&
+        (field === null || el.getAttribute("data-capa-field") === field));
+    const box = (el, style, label) => {
+        const rect = el.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0)
+            return null;
+        const pad = style === "faint" ? 1 : 3;
+        const div = document.createElement("div");
+        Object.assign(div.style, {
+            position: "absolute",
+            left: `${rect.left - pad}px`,
+            top: `${rect.top - pad}px`,
+            width: `${rect.width + pad * 2}px`,
+            height: `${rect.height + pad * 2}px`,
+            boxSizing: "border-box",
+            borderRadius: "3px",
+            border: style === "faint"
+                ? "1px solid rgba(37, 99, 235, 0.35)"
+                : style === "hover"
+                    ? `2px dashed ${BLUE}`
+                    : `2px solid ${BLUE}`,
+        });
+        if (label) {
+            const chip = document.createElement("span");
+            chip.textContent = label;
+            // Above the box when there is room, tucked inside its top edge when the
+            // element sits at the very top of the viewport.
+            const above = rect.top - pad >= 20;
+            Object.assign(chip.style, {
+                position: "absolute",
+                left: "-2px",
+                top: above ? "-20px" : "0px",
+                background: BLUE,
+                color: "#fff",
+                font: "500 11px/18px system-ui, -apple-system, 'Segoe UI', sans-serif",
+                padding: "0 6px",
+                borderRadius: "3px",
+                whiteSpace: "nowrap",
+                letterSpacing: "0",
+            });
+            div.appendChild(chip);
+        }
+        return div;
+    };
+    const draw = () => {
+        frame = 0;
+        const nothing = !outlineAll && !highlight && !hovered;
+        if (nothing) {
+            if (layer)
+                layer.replaceChildren();
+            return;
+        }
+        const target = ensureLayer();
+        const boxes = [];
+        const active = highlight ? matching(highlight.entryId, highlight.field) : [];
+        if (outlineAll) {
+            for (const el of tagged()) {
+                if (active.includes(el))
+                    continue;
+                const b = box(el, "faint", null);
+                if (b)
+                    boxes.push(b);
+            }
+        }
+        if (hovered && hovered.isConnected && !active.includes(hovered)) {
+            const b = box(hovered, "hover", hovered.getAttribute("data-capa-field"));
+            if (b)
+                boxes.push(b);
+        }
+        active.forEach((el, i) => {
+            const label = i === 0 ? (highlight?.field ?? "entry") : null;
+            const b = box(el, "active", label);
+            if (b)
+                boxes.push(b);
+        });
+        target.replaceChildren(...boxes);
+    };
+    const render = () => {
+        if (frame)
+            return;
+        frame = window.requestAnimationFrame(draw);
+    };
+    // --------------------------------------------------------------- ready ---
+    const sendReady = (force) => {
+        readyFrame = 0;
+        if (!adminOrigin)
+            return;
+        const entries = [];
+        for (const el of tagged()) {
+            const id = el.getAttribute("data-capa-entry");
+            if (id && !entries.includes(id))
+                entries.push(id);
+        }
+        const path = window.location.pathname;
+        const key = `${path}\n${entries.join(",")}`;
+        if (!force && key === lastReady)
+            return;
+        lastReady = key;
+        post((0, protocol_1.readyMessage)(path, entries));
+    };
+    const scheduleReady = () => {
+        if (readyFrame)
+            return;
+        readyFrame = window.requestAnimationFrame(() => sendReady(false));
+    };
+    // ------------------------------------------------------------- visible ---
+    /**
+     * Which tagged element sits at the centre of the viewport, reported when it
+     * changes. The editor's "Follow the page" scrolls the form to match. Sent
+     * only to an admin that has said hello, and only on a change, so a still
+     * page sends nothing.
+     */
+    const reportVisible = () => {
+        visibleTimer = 0;
+        if (!adminOrigin)
+            return;
+        const boxes = tagged().map((el) => {
+            const rect = el.getBoundingClientRect();
+            return {
+                entryId: el.getAttribute("data-capa-entry") ?? "",
+                field: el.getAttribute("data-capa-field") ?? "",
+                top: rect.top,
+                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);
+        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));
+    };
+    const onScroll = () => {
+        render();
+        if (!visibleTimer)
+            visibleTimer = window.setTimeout(reportVisible, VISIBLE_THROTTLE_MS);
+    };
+    // -------------------------------------------------------------- scroll ---
+    const restoreScroll = () => {
+        if (!pendingScroll)
+            return;
+        if (Date.now() > pendingScroll.until) {
+            pendingScroll = null;
+            return;
+        }
+        if (Math.abs(window.scrollY - pendingScroll.y) > 1)
+            window.scrollTo(0, pendingScroll.y);
+    };
+    // A `location.reload()` fallback left the position behind before it went.
+    try {
+        const saved = window.sessionStorage.getItem(SCROLL_KEY);
+        if (saved !== null) {
+            window.sessionStorage.removeItem(SCROLL_KEY);
+            const y = Number(saved);
+            if (Number.isFinite(y)) {
+                pendingScroll = { y, until: Date.now() + RESTORE_WINDOW_MS };
+                window.requestAnimationFrame(restoreScroll);
+            }
+        }
+    }
+    catch {
+        // Storage blocked (a sandboxed or third-party frame): start at the top.
+    }
+    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();
+            return;
+        }
+        pendingScroll = { y, until: Date.now() + RESTORE_WINDOW_MS };
+        Promise.resolve()
+            .then(() => onRefresh?.())
+            .catch(() => window.location.reload())
+            .finally(() => window.requestAnimationFrame(restoreScroll));
+    };
+    // ------------------------------------------------------------ messages ---
+    const onMessage = (event) => {
+        const message = (0, protocol_1.acceptMessage)(event, origins, window.parent);
+        if (!message)
+            return;
+        switch (message.type) {
+            case "hello":
+                adminOrigin = event.origin;
+                lastVisible = "";
+                sendReady(true);
+                render();
+                return;
+            case "highlight": {
+                if (message.entryId === "") {
+                    highlight = null;
+                    render();
+                    return;
+                }
+                highlight = { entryId: message.entryId, field: message.field };
+                const first = matching(message.entryId, message.field)[0];
+                if (first)
+                    first.scrollIntoView({ block: "center", behavior: "smooth" });
+                render();
+                return;
+            }
+            case "outline":
+                outlineAll = message.on;
+                render();
+                return;
+            case "refresh":
+                refresh();
+                return;
+        }
+    };
+    // --------------------------------------------------------- interaction ---
+    const taggedFrom = (target) => {
+        const el = target;
+        return el && typeof el.closest === "function" ? el.closest(TAGGED) : null;
+    };
+    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)
+            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") ?? ""));
+    };
+    const updateHover = () => {
+        hoverFrame = 0;
+        const el = taggedFrom(lastPointer);
+        if (el === hovered)
+            return;
+        hovered = el;
+        post(el
+            ? (0, protocol_1.hoverMessage)(el.getAttribute("data-capa-entry") ?? "", el.getAttribute("data-capa-field"))
+            : (0, protocol_1.hoverMessage)("", null));
+        render();
+    };
+    const onPointerMove = (event) => {
+        if (!adminOrigin)
+            return;
+        lastPointer = event.target;
+        if (!hoverFrame)
+            hoverFrame = window.requestAnimationFrame(updateHover);
+    };
+    const onPointerLeave = () => {
+        lastPointer = null;
+        if (!hoverFrame)
+            hoverFrame = window.requestAnimationFrame(updateHover);
+    };
+    const observer = new MutationObserver((records) => {
+        // Our own layer redrawing is not the page changing.
+        if (records.every((r) => layer !== null && (r.target === layer || layer.contains(r.target))))
+            return;
+        scheduleReady();
+        render();
+        restoreScroll();
+    });
+    window.addEventListener("message", onMessage);
+    window.addEventListener("scroll", onScroll, { capture: true, passive: true });
+    window.addEventListener("resize", render, { passive: true });
+    window.addEventListener("popstate", scheduleReady);
+    document.addEventListener("click", onClick, true);
+    document.addEventListener("pointermove", onPointerMove, { capture: true, passive: true });
+    document.documentElement.addEventListener("pointerleave", onPointerLeave);
+    observer.observe(document.body, { childList: true, subtree: true, characterData: true });
+    const dispose = () => {
+        window.removeEventListener("message", onMessage);
+        window.removeEventListener("scroll", onScroll, { capture: true });
+        window.removeEventListener("resize", render);
+        window.removeEventListener("popstate", scheduleReady);
+        document.removeEventListener("click", onClick, true);
+        document.removeEventListener("pointermove", onPointerMove, { capture: true });
+        document.documentElement.removeEventListener("pointerleave", onPointerLeave);
+        observer.disconnect();
+        for (const id of [frame, readyFrame, hoverFrame])
+            if (id)
+                window.cancelAnimationFrame(id);
+        if (visibleTimer)
+            window.clearTimeout(visibleTimer);
+        layer?.remove();
+        layer = null;
+        if (running?.dispose === dispose)
+            running = null;
+    };
+    return {
+        dispose,
+        setOptions: (next) => {
+            origins = (0, protocol_1.normaliseOrigins)(next.adminOrigins ?? []);
+            onRefresh = next.onRefresh;
+            if (adminOrigin && !origins.includes(adminOrigin))
+                adminOrigin = null;
+        },
+    };
+}

package/dist/overlay/protocol.d.ts

@@ -0,0 +1,134 @@
+/**
+ * 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 declare const PROTOCOL_VERSION = 1;
+export declare const ADMIN_SOURCE = "capa-admin";
+export declare const SITE_SOURCE = "capa";
+export type AdminMessage = {
+    source: typeof ADMIN_SOURCE;
+    v: 1;
+    type: "hello";
+} | {
+    source: typeof ADMIN_SOURCE;
+    v: 1;
+    type: "highlight";
+    entryId: string;
+    field: string | null;
+} | {
+    source: typeof ADMIN_SOURCE;
+    v: 1;
+    type: "outline";
+    on: boolean;
+} | {
+    source: typeof ADMIN_SOURCE;
+    v: 1;
+    type: "refresh";
+};
+export type SiteMessage = {
+    source: typeof SITE_SOURCE;
+    v: 1;
+    type: "ready";
+    path: string;
+    entries: string[];
+} | {
+    source: typeof SITE_SOURCE;
+    v: 1;
+    type: "select";
+    entryId: string;
+    field: string;
+} | {
+    source: typeof SITE_SOURCE;
+    v: 1;
+    type: "hover";
+    entryId: string;
+    field: string | null;
+} | {
+    source: typeof SITE_SOURCE;
+    v: 1;
+    type: "visible";
+    entryId: string;
+    field: string;
+};
+/** The parts of a `MessageEvent` the filter reads, so a test can hand in a literal. */
+export interface MessageLike {
+    origin: string;
+    source: unknown;
+    data: unknown;
+}
+/**
+ * `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 declare function normaliseOrigins(origins: readonly string[]): string[];
+/**
+ * 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 declare function acceptMessage(event: MessageLike, allowedOrigins: readonly string[], parent: unknown): AdminMessage | null;
+export declare function readyMessage(path: string, entries: string[]): SiteMessage;
+export declare function selectMessage(entryId: string, field: string): SiteMessage;
+export declare function hoverMessage(entryId: string, field: string | null): SiteMessage;
+export declare function visibleMessage(entryId: string, field: string): SiteMessage;
+/** The part of a tagged element `pickCentred` reads, so a test can hand in literals. */
+export interface TaggedBox {
+    entryId: string;
+    field: string;
+    /** `getBoundingClientRect()`, viewport coordinates. */
+    top: number;
+    bottom: number;
+}
+/**
+ * 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 declare function pickCentred(boxes: readonly TaggedBox[], viewportHeight: number, edge?: "top" | "bottom" | null): TaggedBox | null;
+/**
+ * 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 declare function scrollEdge(scrollY: number, viewportHeight: number, scrollHeight: number): "top" | "bottom" | null;

package/dist/overlay/protocol.js

@@ -0,0 +1,184 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SITE_SOURCE = exports.ADMIN_SOURCE = exports.PROTOCOL_VERSION = void 0;
+exports.normaliseOrigins = normaliseOrigins;
+exports.acceptMessage = acceptMessage;
+exports.readyMessage = readyMessage;
+exports.selectMessage = selectMessage;
+exports.hoverMessage = hoverMessage;
+exports.visibleMessage = visibleMessage;
+exports.pickCentred = pickCentred;
+exports.scrollEdge = scrollEdge;
+exports.PROTOCOL_VERSION = 1;
+exports.ADMIN_SOURCE = "capa-admin";
+exports.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".
+ */
+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`).
+ */
+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 !== exports.ADMIN_SOURCE || m.v !== exports.PROTOCOL_VERSION)
+        return null;
+    switch (m.type) {
+        case "hello":
+            return { source: exports.ADMIN_SOURCE, v: 1, type: "hello" };
+        case "refresh":
+            return { source: exports.ADMIN_SOURCE, v: 1, type: "refresh" };
+        case "outline":
+            if (typeof m.on !== "boolean")
+                return null;
+            return { source: exports.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: exports.ADMIN_SOURCE, v: 1, type: "highlight", entryId: m.entryId, field: m.field };
+        default:
+            return null;
+    }
+}
+function readyMessage(path, entries) {
+    return { source: exports.SITE_SOURCE, v: 1, type: "ready", path, entries };
+}
+function selectMessage(entryId, field) {
+    return { source: exports.SITE_SOURCE, v: 1, type: "select", entryId, field };
+}
+function hoverMessage(entryId, field) {
+    return entryId === ""
+        ? { source: exports.SITE_SOURCE, v: 1, type: "hover", entryId: "", field: null }
+        : { source: exports.SITE_SOURCE, v: 1, type: "hover", entryId, field };
+}
+function visibleMessage(entryId, field) {
+    return { source: exports.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.
+ */
+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.
+ */
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capacms/sdk",
-  "version": "1.0.0-next.0",
+  "version": "1.0.0-next.2",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
@@ -39,6 +39,10 @@
       "types": "./dist/nextjs/index.d.ts",
       "default": "./dist/nextjs/index.js"
     },
+    "./overlay": {
+      "types": "./dist/overlay/index.d.ts",
+      "default": "./dist/overlay/index.js"
+    },
     "./package.json": "./package.json"
   },
   "typesVersions": {
@@ -49,6 +53,9 @@
       "nextjs": [
         "dist/nextjs/index.d.ts"
       ],
+      "overlay": [
+        "dist/overlay/index.d.ts"
+      ],
       "*": [
         "dist/index.d.ts"
       ]
@@ -64,6 +71,6 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "tsc -p tsconfig.json && node --test test/codegen.test.js test/client.test.js test/next-client.test.js test/nextjs.test.js test/webhooks.test.js && tsc -p test/types/tsconfig.consumer.json --noEmit"
+    "test": "tsc -p tsconfig.json && node --test 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 && tsc -p test/types/tsconfig.consumer.json --noEmit"
   }
 }