@mapled/next 0.10.0 → 0.11.1

package/README.md

@@ -369,11 +369,31 @@ export function UpdateNotice() {
 ```
 
 - It is polling, and it is cheap: tabs ask **your** route, never Mapled. The route reuses one answer for `ttl` seconds (default 5) — in the instance and, through `s-maxage`, at the CDN in front of it — and a check that finds nothing new is a 304. However many tabs are open, Mapled hears from the site a few times a minute, and the key's rate limit is left for reads.
-- The route reads the release under the same `mapled` cache tag as the content, so it moves when the webhook refreshes the cache and not before — a tab that refreshes on it never renders the old release again. Live updates therefore need the webhook from [Refresh on publish](#refresh-on-publish); without it both change only when their ISR window (`revalidate`, 3600 by default) runs out.
+- The route moves when the webhook has refreshed your site's cache, and not before — a tab that refreshes on it never renders the old release again. It reads the release under the same `mapled` cache tag as the content, and never names one newer than the release your site's cache last answered the publish webhook for: the webhook handler revalidates the cache before it answers, its answer carries the cache's mark (`x-mapled-cache`), and Mapled records the answer with the mark. So a cache entry filled early — after a deploy, an eviction, or when its `revalidate` window runs out between a publish and its webhook — doesn't move the route ahead of the pages. Only while a publish's webhook is on its way — or failing — does the route ask Mapled past its cache, once per `ttl`. Live updates therefore need the webhook from [Refresh on publish](#refresh-on-publish): until your site has answered a publish's webhook, the route names the release before it (`null` before the first one it answered), and without a webhook it names nothing new — nothing tells it when your pages have a release, so open tabs don't follow Publish. A new webhook address starts over: the site there hasn't answered anything yet.
+- Live updates follow the deployment the webhook reaches. Another deployment on the same key — a preview, a second site — renders from a cache of its own, which no publish revalidates, so its route names no release and its open tabs stay as they are. The route tells the answers apart by the mark: each Next.js cache keeps its own (`cacheMark()`), so deployments that share a cache share the mark, and one with a cache of its own has another. After a deploy onto a fresh cache — or once the cache has lost the mark — the route names no release until the next publish's webhook has been answered from that cache. (Before 0.11.0 such a deployment followed the webhook's one and could refresh its tabs into the release they already showed.)
+- A webhook handler of your own — one that refreshes more than the `mapled` tag, say — answers with the cache's mark, or the route names no release (it logs once why):
+
+```ts
+import { revalidateTag } from "next/cache";
+import { cacheMark, verifySignature } from "@mapled/next/server";
+
+export async function POST(req: Request) {
+  const body = await req.text();
+  const signature = req.headers.get("x-mapled-signature") ?? "";
+  if (!(await verifySignature(process.env.MAPLED_WEBHOOK_SECRET!, body, signature))) {
+    return Response.json({ error: "Invalid signature." }, { status: 401 });
+  }
+  revalidateTag("mapled");
+  // after revalidating: the mark says which cache has let go of the old release
+  return Response.json({ revalidated: true }, { headers: { "x-mapled-cache": await cacheMark() } });
+}
+```
+
 - The route answers `{ release, publishedAt }` — the number of publishes and the time of the last one, nothing else — and may be cached by anyone. While Mapled can't be reached it keeps answering the last release it knew.
+- Refreshes ask your site, not the browser's cache. `router.refresh()` asks for the page's Server Components at the same URL every time, and a static page answers with `s-maxage` and `stale-while-revalidate` but no `max-age`: stale for the browser at once, which Chrome and Edge serve anyway while they fetch a fresh copy behind it. So from the first publish a tab hears about, every refresh of the page goes with `cache: "no-cache"`, and your site may still answer 304. That covers the component's own refresh, the one your `onPublish` makes (like the button above), and any your code makes. The layer changes only the cache mode, and only of requests your server reads as a refresh of the page the tab is on. Navigations, server actions, your own requests and any request that sets its own `cache` go as they did. A layer over `fetch`, put in place with the first publish, does it; a `fetch` wrapper of your own keeps working either way. (Before 0.11.1 an open tab showed the release before the one it was told about, from its second publish on.)
 - Expect a publish to reach an open tab in about ten seconds with the defaults. `<MapledLive interval={3} />` and `createReleaseHandler({ key, ttl: 1 })` make it quicker at the price of more requests to your site.
 - With a `basePath` in `next.config`, the route answers under it, and so does the default: `<MapledLive />` asks `/docs/api/mapled/release` on a site with `basePath: "/docs"` — Next writes the basePath into the bundle, and the component reads it from there (0.10.0 and later; earlier versions ask `/api/mapled/release`). An `endpoint` you pass is asked as written, basePath included: `<MapledLive endpoint="/docs/live" />`.
-- Leave route segment config off the release route: `createReleaseHandler` sets how it is cached. `dynamic = "force-static"` turns it into a copy Next builds without the tab's request, and `fetchCache = "force-no-store"` reads the release past the cache tag — the route would move before the webhook refreshes the pages. `dynamic = "force-dynamic"` does the same when the handler's `revalidate` is `false` or `0`; at its default it is harmless. Middleware that runs on the route has to let the tab's `GET` through: no redirect, rewrite or sign-in wall. `output: "export"` has no server to run the route at all.
+- Leave route segment config off the release route: `createReleaseHandler` sets how it is cached. `dynamic = "force-static"` turns it into a copy Next builds without the tab's request, and `fetchCache = "force-no-store"` reads the release past the cache tag, so Mapled hears from the route every `ttl`. `dynamic = "force-dynamic"` does the same when the handler's `revalidate` is `false` or `0`; at its default it is harmless. On the webhook route, leave `fetchCache` off too: with `"force-no-store"` every answer names a new cache mark, and the release route may name no release. Middleware that runs on the route has to let the tab's `GET` through: no redirect, rewrite or sign-in wall. `output: "export"` has no server to run the route at all.
 
 Outside React, `watchRelease({ onPublish })` from `@mapled/next` is the same watch as a plain function — it returns the function that stops it.
 
@@ -506,6 +526,8 @@ await db.remove("orders", id);
 
 The server key reaches only operational collections with access class `public`/`server` — editorial content, internal and sensitive collections stay out of reach, and it grants nothing on the Management API.
 
+A write is checked against the collection's fields: data that doesn't fit them is a 400 `VALIDATION_FAILED`, a slug another record uses a 409 `SLUG_TAKEN`. A write that ran while a field it sends was renamed, removed or changed is a 409 `FIELDS_CHANGED` and writes nothing — send it again against the fields as they are now.
+
 ## Without Next.js: the HTTP API
 
 The client is a thin layer over a plain HTTP API, so any site — or a build script — can read Mapled. The base URL is `https://api.mapled.io`; every request carries the delivery key in `x-mapled-key`.
@@ -516,7 +538,7 @@ The client is a thin layer over a plain HTTP API, so any site — or a build scr
 | `GET /v1/delivery/collections/{collection}/records/{id}` | `{ record, release }` — 404 when it isn't in the release |
 | `GET /v1/delivery/collections/{collection}/records/by-slug/{slug}` | `{ record, release }` |
 | `GET /v1/delivery/singles/{single}` | `{ record, release }` — `record` is `null` while the single is empty |
-| `GET /v1/delivery/release` | `{ release, publishedAt }` — the release being served now; `null`s before the first publish |
+| `GET /v1/delivery/release` | `{ release, publishedAt }` — the release being served now; `null`s before the first publish. With `?webhook=1` also `webhook`: `{ release, publishedAt, deliveredAt, cache }` of the newest release your site answered the publish webhook for, with the `x-mapled-cache` mark the answer carried (`null`s before the first, and again after the webhook's address changes), or `null` when the project has no webhook |
 | `POST /v1/delivery/forms/{form}` | `201 { ok: true }` — see [Forms](#forms) |
 
 ```bash
@@ -528,7 +550,7 @@ curl -H "x-mapled-key: $MAPLED_KEY" \
 - Only published content of collections with access **Public** is served; sensitive fields are never in an answer. Image and file values are asset ids — `https://api.mapled.io/files/{id}` is the file, with `?w=`, `h=`, `fit=`, `fmt=`, `q=` for a resized variant.
 - Answers are per key — `Cache-Control: private` — with an `ETag`: send it back as `If-None-Match` and an unchanged answer is a 304. A read pinned with `release=N` never changes and may be cached for good. `GET /v1/delivery/release` is the cheap way to learn that something was published: relay it from a route of your own server, and `watchRelease({ endpoint, onPublish })` from `@mapled/next` — no framework in it — tells open tabs ([Live updates](#live-updates)).
 - Errors share one envelope: `{ error: { code, message, requestId } }`. A key gets 1,200 requests a minute; past that, 429 `RATE_LIMITED` with `retry-after`.
-- The publish webhook is a `POST` with a JSON body `{ event, project, release, at, id }` and the headers `x-mapled-event` (`release.published`, `project.restored` or `test`), `x-mapled-event-id` (the same on every retry — use it to deduplicate), `x-mapled-attempt` and `x-mapled-signature`: `sha256=` followed by the hex HMAC-SHA256 of the raw body with the signing secret. Compare in constant time, answer 2xx within 5 seconds. `verifySignature` from `@mapled/next/server` does the check anywhere Web Crypto exists.
+- The publish webhook is a `POST` with a JSON body `{ event, project, release, at, id }` and the headers `x-mapled-event` (`release.published`, `project.restored` or `test`), `x-mapled-event-id` (the same on every retry — use it to deduplicate), `x-mapled-attempt` and `x-mapled-signature`: `sha256=` followed by the hex HMAC-SHA256 of the raw body with the signing secret. Compare in constant time, answer 2xx within 5 seconds. `verifySignature` from `@mapled/next/server` does the check anywhere Web Crypto exists. An answer may carry `x-mapled-cache` — up to 64 letters, digits, `-` or `_` naming the cache the handler revalidated; Mapled records it with the release, and the `?webhook=1` pointer gives it back.
 - Live data: `GET` / `POST /v1/app/collections/{collection}/records` and `GET` / `PATCH` / `DELETE /v1/app/collections/{collection}/records/{id}` with the server key in `x-mapled-server-key`; writes send `{ "data": { … } }`.
 
 Preview (drafts on the site) is built on Next.js draft mode and ships with this package only.
@@ -545,5 +567,6 @@ Preview (drafts on the site) is built on Next.js draft mode and ships with this
 - `createReleaseHandler({ key, apiUrl?, ttl?, revalidate? })` — App Router `GET` handler of the release route; `<MapledLive endpoint? interval? onPublish? />` from `@mapled/next/live` and `watchRelease({ endpoint?, interval?, onPublish })` ask it
 - `createPagesReleaseHandler({ key, apiUrl?, ttl? })` — Pages Router API route of the release route (the default export of `pages/api/mapled/release.ts`); `<MapledLive endpoint? interval? onPublish? />` from `@mapled/next/live/pages` asks it
 - `verifySignature(secret, body, signature)` — if you'd rather build your own handler
+- `cacheMark()` — the mark of this deployment's Next.js cache: a webhook handler of your own answers with it in `x-mapled-cache` (`createRevalidateHandler` does), and `createReleaseHandler` follows only an answer that carries its own
 
 The delivery key only reads published, public content — safe to use anywhere.

package/dist/live.js

@@ -22,6 +22,7 @@ export function MapledLive({ endpoint, interval, onPublish }) {
         endpoint,
         interval,
         onPublish: (next, previous) => {
+            refreshPastBrowserCache();
             if (custom.current)
                 custom.current(next, previous);
             else
@@ -30,3 +31,102 @@ export function MapledLive({ endpoint, interval, onPublish }) {
     }), [endpoint, interval, router]);
     return null;
 }
+/** The layers this module has put over `fetch`. */
+const layers = new WeakSet();
+/** Sends every refresh of the page from now on past the browser's cache:
+    ours, the one `onPublish` makes later, and one the site makes for its
+    own reasons alike — a request doesn't say whose it is, and a refresh
+    asks for fresh content anyway. A layer over `fetch` does it, put in
+    place when the first publish lands: Next asks `fetch` when it sends,
+    not when it loads. Code that wraps `fetch` later wraps the layer too;
+    code that puts back a `fetch` it kept from before gets a new layer
+    over it on the next publish. A layer, once there, stays: removing it
+    could take someone else's wrapper out with it.
+    The layer keeps nothing from one request to the next. A bypass armed
+    by each publish and spent by the first request that looked like the
+    refresh was spent, again and again, by prefetches it couldn't be told
+    from once a `fetch` wrapper had dropped their priority (PR 442). */
+function refreshPastBrowserCache() {
+    let below;
+    try {
+        below = globalThis.fetch;
+    }
+    catch {
+        return;
+    }
+    if (typeof below !== "function" || layers.has(below))
+        return;
+    const layer = function (input, init) {
+        return below.call(this, input, needsBypass(input, init) ? bypassing(init) : init);
+    };
+    layers.add(layer);
+    try {
+        globalThis.fetch = layer;
+    }
+    catch {
+        // a fetch that may not be replaced: the refresh goes as before
+    }
+}
+/** Whether a request is one the site's server reads as the router's
+    refresh of the page the tab is on, left to the browser's default
+    cache mode:
+    - a GET for the page's server components (the `rsc` header) that is
+      not a prefetch (no prefetch header);
+    - asked from the root of the router's tree: the `refetch` marker at
+      the root of `next-router-state-tree`, which `router.refresh()` sets
+      in Next 14, 15 and 16;
+    - to the tab's own address, the query compared less the `_rsc` Next
+      adds. Next 16 asks a route it doesn't know yet from the root too,
+      and `?page=2` of this page is another page here.
+    Only what the server reads decides, which a `fetch` wrapper can't
+    change without breaking the page — not the `priority` the browser
+    keeps, which a wrapper drops when it makes a `Request` of Next's
+    `(url, init)` or passes one on as fields. So Next 16's full prefetch
+    of this page, asked from the root while its segment cache is empty,
+    goes past the cache too: the server can't tell it from the refresh.
+    A cache mode someone chose (`no-store`, `reload`, `force-cache`) is
+    theirs, and it stays. */
+function needsBypass(input, init) {
+    try {
+        const request = typeof Request === "function" && input instanceof Request ? input : null;
+        if ((init?.cache ?? request?.cache ?? "default") !== "default")
+            return false;
+        const headers = new Headers(init?.headers ?? request?.headers);
+        const method = (init?.method ?? request?.method ?? "GET").toUpperCase();
+        if (method !== "GET" || headers.get("rsc") !== "1")
+            return false;
+        if (headers.has("next-router-prefetch") || headers.has("next-router-segment-prefetch"))
+            return false;
+        const tree = JSON.parse(decodeURIComponent(headers.get("next-router-state-tree") ?? ""));
+        if (!Array.isArray(tree) || tree[3] !== "refetch")
+            return false;
+        const url = new URL(request ? request.url : String(input), location.href);
+        return url.origin === location.origin && url.pathname === location.pathname && query(url.search) === query(location.search);
+    }
+    catch {
+        return false;
+    }
+}
+/** The members of `RequestInit`, which `fetch` reads with getters and
+    all: a spread copies only an object's own fields, and a `Request`
+    handed on as the init keeps its members on its prototype. */
+const MEMBERS = ["body", "cache", "credentials", "duplex", "headers", "integrity", "keepalive", "method", "mode", "priority", "redirect", "referrer", "referrerPolicy", "signal", "window"];
+/** `init` as `fetch` would read it, with `cache: "no-cache"` — the one
+    change the layer makes. */
+function bypassing(init) {
+    const read = { ...init };
+    for (const key of MEMBERS) {
+        const value = init?.[key];
+        if (value !== undefined)
+            read[key] = value;
+    }
+    read.cache = "no-cache";
+    return read;
+}
+/** A query as the page reads it: Next 14 writes the request's anew, 15
+    and 16 append `_rsc` to it as it was. */
+function query(search) {
+    const params = new URLSearchParams(search);
+    params.delete("_rsc");
+    return params.toString();
+}

package/dist/server.d.ts

@@ -19,6 +19,16 @@ export declare function createPreviewHandler(options?: {
 }): (req: Request) => Promise<Response>;
 /** GET handler to leave preview (mount at /api/mapled/preview/exit). */
 export declare function createExitPreviewHandler(): (req: Request) => Promise<Response>;
+/** The mark of this deployment's Next.js cache: a random value made once
+    and kept in that cache, never expiring (`unstable_cache`). Handlers
+    that read through the same cache read the same mark; a deployment
+    with a cache of its own — a preview, another site on the same key —
+    reads another. `createRevalidateHandler` answers the publish webhook
+    with it (`x-mapled-cache`), Mapled records it with the release the
+    answer acknowledges, and the release route follows only an
+    acknowledgement its own cache gave (§18.8). Outside Next.js, or while
+    its cache doesn't answer, the mark is this process's. */
+export declare function cacheMark(): Promise<string>;
 export declare function createRevalidateHandler(options: {
     secret: string;
     /** Cache tags to refresh — defaults to ["mapled"], which covers every
@@ -34,10 +44,12 @@ type ReleaseOptions = {
 /** GET handler for the release route of an App Router site (mount at
     app/api/mapled/release/route.ts): the release this site serves right
     now, for `<MapledLive />` from "@mapled/next/live" to ask about. The
-    pointer is read under the "mapled" tag like the content is, so it
-    moves when the publish webhook refreshes the cache and not before — a
-    tab that refreshes on it renders the new release, never the old one
-    again. */
+    pointer is read under the "mapled" tag like the content is, and never
+    past the release this deployment's cache has acknowledged through the
+    publish webhook — however the cache entry was filled, the route moves
+    when the webhook has refreshed this cache and not before, so a tab
+    that refreshes on it renders the new release, never the old one
+    again. A deployment the webhook doesn't reach names none. */
 export declare function createReleaseHandler(options: ReleaseOptions & {
     /** ISR window of the pointer, the same as a read's (default 3600 — the webhook keeps it fresh). */
     revalidate?: number | false;

package/dist/server.js

@@ -83,6 +83,44 @@ export function createExitPreviewHandler() {
         });
     };
 }
+/** A mark as `cacheMark` makes them: 32 hex digits. */
+const MARK = /^[0-9a-f]{32}$/;
+function mint() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** what `unstable_cache` runs when the cache has no mark yet */
+async function minted() {
+    return mint();
+}
+/** the mark where no Next.js cache answers: this process's */
+let processMark;
+let nextCache;
+/** "next/cache", loaded once — by the first handler that needs it */
+const cacheModule = () => (nextCache ??= import("next/cache"));
+/** The mark of this deployment's Next.js cache: a random value made once
+    and kept in that cache, never expiring (`unstable_cache`). Handlers
+    that read through the same cache read the same mark; a deployment
+    with a cache of its own — a preview, another site on the same key —
+    reads another. `createRevalidateHandler` answers the publish webhook
+    with it (`x-mapled-cache`), Mapled records it with the release the
+    answer acknowledges, and the release route follows only an
+    acknowledgement its own cache gave (§18.8). Outside Next.js, or while
+    its cache doesn't answer, the mark is this process's. */
+export async function cacheMark() {
+    try {
+        const { unstable_cache } = await cacheModule();
+        // bound: Next keys the entry by the function's source, and a bound function's reads the same in every bundle
+        const mark = await unstable_cache(minted.bind(null), ["@mapled/next", "cache-mark"], { revalidate: false })();
+        if (typeof mark === "string" && MARK.test(mark))
+            return mark;
+    }
+    catch {
+        // outside Next.js, or its cache didn't answer
+    }
+    return (processMark ??= mint());
+}
 export function createRevalidateHandler(options) {
     if (!options.secret) {
         throw new Error("Mapled: the webhook secret is required.");
@@ -93,56 +131,151 @@ export function createRevalidateHandler(options) {
         if (!signature || !(await verifySignature(options.secret, body, signature))) {
             return Response.json({ error: "Invalid signature." }, { status: 401 });
         }
-        const { revalidateTag } = await import("next/cache");
+        const { revalidateTag } = await cacheModule();
         for (const tag of options.tags ?? ["mapled"])
             revalidateTag(tag);
-        return Response.json({ revalidated: true });
+        // which cache this answer speaks for: the release route follows only its own (§18.8)
+        return Response.json({ revalidated: true }, { headers: { "x-mapled-cache": await cacheMark() } });
     };
 }
+/** `{ release, publishedAt }` as Mapled writes it — a release, or nulls
+    before the first; anything else throws. */
+function asPointer(body) {
+    const { release = null, publishedAt = null } = (body ?? {});
+    if (release === null)
+        return { release: null, publishedAt: null };
+    if (!Number.isInteger(release) || release < 1 || typeof publishedAt !== "string") {
+        throw new Error("Mapled's answer wasn't a release");
+    }
+    return { release, publishedAt };
+}
+/** The pointer's `webhook` as Mapled writes it; anything else throws. */
+function asAcknowledged(body) {
+    const { cache = null } = (body ?? {});
+    if (cache !== null && typeof cache !== "string")
+        throw new Error("Mapled's answer wasn't a release");
+    return { ...asPointer(body), cache };
+}
+/** The pointer and, when asked with `?webhook=1`, the release the site
+    has acknowledged through its publish webhook: null — the project has
+    no webhook; undefined — this Mapled doesn't say. `copy` is the answer
+    as it came, to tell one cached copy from another. */
+async function readPointer(url, init) {
+    const res = await fetch(url, init);
+    if (!res.ok)
+        throw new Error(`Mapled answered ${res.status}`);
+    const copy = await res.text();
+    const body = JSON.parse(copy);
+    const webhook = body?.webhook;
+    return { live: asPointer(body), acknowledged: webhook === undefined ? undefined : webhook === null ? null : asAcknowledged(webhook), copy };
+}
+const NONE = { release: null, publishedAt: null };
+const UNACKNOWLEDGED = { ...NONE, cache: null };
+/** What the route names for a copy naming `live`: the release this
+    cache acknowledged, never past `live` — none when the acknowledgement
+    is another cache's, or names none. */
+function follow(acknowledged, live, mark) {
+    if (acknowledged.cache !== mark || acknowledged.release === null)
+        return NONE;
+    if (acknowledged.release >= (live.release ?? 0))
+        return live;
+    return { release: acknowledged.release, publishedAt: acknowledged.publishedAt };
+}
 /** The release route, whichever router mounts it: one answer reused for
     `ttl` seconds, in this instance and at the CDN in front of it —
     however many tabs ask, Mapled hears from the site a few times a
     minute. `next` is how the pointer is fetched: under the content's
     cache tag in the App Router, as is in the Pages Router, which has no
-    such cache. */
+    such cache.
+
+    Under the tag the answer is the one the site's cache holds, and an
+    entry can be filled at any moment — cold after a deploy, evicted,
+    expired — also between a publish's commit and its webhook, while the
+    pages still render the release before. So the App Router asks with
+    `?webhook=1` and never names a release newer than the one this
+    site's cache has acknowledged through the webhook: the site
+    revalidates before it answers, and Mapled records the answer with the
+    cache's mark. An answer from another cache — the deployment the
+    webhook reaches, when this one is a preview or another site on the
+    same key — says nothing of this one's pages. Nothing else proves a
+    release rendered — without a webhook, from a Mapled that doesn't say,
+    or while the acknowledgement is another cache's, the route names
+    none. Only while the cached copy names a release it doesn't say is
+    acknowledged does the route ask Mapled as it is now — the site may
+    have answered since the copy was made — once a ttl, until Mapled
+    says a webhook for it was answered. */
 function releaseAnswers(options, next) {
     if (!options.key)
         throw new Error("Mapled: a delivery key is required.");
     const base = (options.apiUrl ?? "https://api.mapled.io").replace(/\/+$/, "");
     const ttlMs = Math.max(1, options.ttl ?? 5) * 1000;
+    const headers = { "x-mapled-key": options.key };
     let held = null;
+    /** the cached copy Mapled has since said a webhook for was answered, and what that means here: not asked about again */
+    let settled = null;
     /** when Mapled was last asked — an answer or a failure, either waits a ttl */
     let askedAt = 0;
     let loading = null;
     let complained = false;
+    let unmarkedSaid = false;
+    /** What this site's pages render: the cached pointer, capped at the
+        release this site's cache has acknowledged. `trouble` — the read of
+        Mapled as it is now failed, and the answer is what the cached copy
+        says; `unmarked` — the acknowledgement names no cache. */
+    async function siteRelease() {
+        const url = `${base}/v1/delivery/release?webhook=1`;
+        const cached = await readPointer(url, { headers, next });
+        const live = cached.live;
+        if (live.release === null || !cached.acknowledged)
+            return { answer: NONE };
+        const mark = await cacheMark();
+        let acknowledged = cached.acknowledged;
+        let trouble;
+        // the copy may have been made between the site's answer and Mapled's record of it
+        if ((acknowledged.release ?? 0) < live.release) {
+            if (settled?.copy === cached.copy && settled.mark === mark)
+                return { answer: settled.answer };
+            try {
+                const now = await readPointer(url, { headers, cache: "no-store" });
+                // as Mapled has it now: a webhook removed or moved since the copy was made has acknowledged nothing
+                acknowledged = now.acknowledged ?? UNACKNOWLEDGED;
+                // answered for this copy's release — by this cache or another, asking again changes nothing
+                if ((acknowledged.release ?? 0) >= live.release)
+                    settled = { copy: cached.copy, mark, answer: follow(acknowledged, live, mark) };
+            }
+            catch (err) {
+                trouble = err ?? new Error("request failed");
+            }
+        }
+        return { answer: follow(acknowledged, live, mark), trouble, unmarked: acknowledged.release !== null && acknowledged.cache === null };
+    }
     async function load() {
+        let trouble;
+        let unmarked;
         try {
-            const init = {
-                headers: { "x-mapled-key": options.key },
-                ...(next ? { next } : {}),
-            };
-            const res = await fetch(`${base}/v1/delivery/release`, init);
-            if (!res.ok)
-                throw new Error(`Mapled answered ${res.status}`);
-            const body = (await res.json());
-            const release = body?.release ?? null;
-            const publishedAt = body?.publishedAt ?? null;
-            const published = Number.isInteger(release) && release >= 1 && typeof publishedAt === "string";
-            if (!published && release !== null)
-                throw new Error("Mapled's answer wasn't a release");
-            held = published ? { release, publishedAt } : { release: null, publishedAt: null };
-            complained = false;
+            if (next)
+                ({ answer: held, trouble, unmarked } = await siteRelease());
+            else
+                held = (await readPointer(`${base}/v1/delivery/release`, { headers })).live;
         }
         catch (err) {
             // the last answer stays good while Mapled can't be reached
-            if (!complained) {
-                complained = true;
-                console.error(`[mapled] The release route can't read the live release: ${err instanceof Error ? err.message : "request failed"}.`);
-            }
+            trouble = err ?? new Error("request failed");
         }
         finally {
             askedAt = Date.now();
         }
+        if (trouble === undefined)
+            complained = false;
+        else if (!complained) {
+            // one line for the developer, not one per poll
+            complained = true;
+            console.error(`[mapled] The release route can't read the live release: ${trouble instanceof Error ? trouble.message : "request failed"}.`);
+        }
+        if (unmarked && !unmarkedSaid) {
+            unmarkedSaid = true;
+            console.warn("[mapled] The release route names no release until your site answers a publish webhook with its cache's mark: createRevalidateHandler does (0.11.0 and later); a webhook handler of your own answers with `x-mapled-cache: await cacheMark()` (README, «Live updates»).");
+        }
     }
     /** `asked` — the tab's If-None-Match */
     return async function answer(asked) {
@@ -168,10 +301,12 @@ function releaseAnswers(options, next) {
 /** GET handler for the release route of an App Router site (mount at
     app/api/mapled/release/route.ts): the release this site serves right
     now, for `<MapledLive />` from "@mapled/next/live" to ask about. The
-    pointer is read under the "mapled" tag like the content is, so it
-    moves when the publish webhook refreshes the cache and not before — a
-    tab that refreshes on it renders the new release, never the old one
-    again. */
+    pointer is read under the "mapled" tag like the content is, and never
+    past the release this deployment's cache has acknowledged through the
+    publish webhook — however the cache entry was filled, the route moves
+    when the webhook has refreshed this cache and not before, so a tab
+    that refreshes on it renders the new release, never the old one
+    again. A deployment the webhook doesn't reach names none. */
 export function createReleaseHandler(options) {
     const answer = releaseAnswers(options, { revalidate: options.revalidate ?? 3600, tags: ["mapled"] });
     return async function GET(req) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapled/next",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Read published Mapled content in a Next.js site \u2014 delivery client, ISR tags, and a revalidation webhook handler.",
   "license": "MIT",
   "homepage": "https://mapled.io",