npm - @mapled/next - Versions diffs - 0.7.1 → 0.9.0 - Mend

@mapled/next 0.7.1 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/README.md CHANGED Viewed

@@ -1,12 +1,12 @@
 # @mapled/next
-Read published [Mapled](https://mapled.io) content in a Next.js site — a delivery client with ISR cache tags, plus a revalidation webhook handler so publishes show up instantly.
+Read published [Mapled](https://mapled.io) content in a Next.js site — a delivery client with ISR cache tags, a revalidation webhook handler so publishes show up instantly, and live updates for the tabs that are already open.
 Mapled is a hosted headless CMS built for sites created with AI. Your agent (or you) models collections and fills in content; this package is how the site reads what's published.
 - [Install](#install)
 - [Integrate by hand](#integrate-by-hand) — the whole integration step by step, no AI agent needed
-- Reference: [Read published content](#read-published-content) • [Rich text](#rich-text) • [Images](#images) • [Refresh on publish](#refresh-on-publish) • [Preview drafts](#preview-drafts) • [Forms](#forms) • [Live data](#live-data) • [Without Next.js: the HTTP API](#without-nextjs-the-http-api) • [API](#api)
+- Reference: [Read published content](#read-published-content) • [Rich text](#rich-text) • [Images](#images) • [Refresh on publish](#refresh-on-publish) • [Live updates](#live-updates) • [Preview drafts](#preview-drafts) • [Forms](#forms) • [Live data](#live-data) • [Without Next.js: the HTTP API](#without-nextjs-the-http-api) • [API](#api)
 ## Install
@@ -153,6 +153,8 @@ export const POST = createRevalidateHandler({
 Deploy, then in Mapled → **Integrations** → **Your site** save `https://your-site.com/api/mapled/revalidate` as the **Revalidation webhook**, copy the **Signing secret** into `MAPLED_WEBHOOK_SECRET` (hosting env and `.env.local`), redeploy, and press **Send test ping**: the delivery shows up under **Recent deliveries** as Delivered. The URL has to be public — Mapled refuses addresses that resolve to a private network.
+Optional: pages that are already open can follow a publish too, without a reload — a route and one component, see [Live updates](#live-updates).
 ### 7. Preview drafts
 ```ts
@@ -315,6 +317,96 @@ Then in Mapled (**Integrations** → **Your site**) set the revalidation webhook
 Each ping is tried up to three times (after 2 and 6 seconds, 5 seconds to answer); **Recent deliveries** keeps them for 30 days, and a failed one can be sent again from there. **Rotate secret** replaces the signing secret at once — deliveries fail until the site has the new one.
+## Live updates
+The webhook refreshes the site's cache; a page someone already has open still shows what it rendered. Two files make open tabs follow Publish as well. A route that says which release the site serves:
+```ts
+// app/api/mapled/release/route.ts
+import { createReleaseHandler } from "@mapled/next/server";
+export const GET = createReleaseHandler({ key: process.env.MAPLED_KEY! });
+```
+and one component in the root layout:
+```tsx
+// app/layout.tsx
+import type { ReactNode } from "react";
+import { MapledLive } from "@mapled/next/live";
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        {children}
+        <MapledLive />
+      </body>
+    </html>
+  );
+}
+```
+`<MapledLive />` renders nothing. While the tab is visible it asks the route every 10 seconds (`interval`, in seconds), and when a publish lands it calls `router.refresh()`: Server Components re-render with the new release in place — scroll position and client state stay. A hidden tab doesn't ask; it checks the moment it is shown again. To offer the update instead of applying it under the reader, pass `onPublish`:
+```tsx
+"use client";
+import { useRouter } from "next/navigation";
+import { useState } from "react";
+import { MapledLive } from "@mapled/next/live";
+export function UpdateNotice() {
+  const router = useRouter();
+  const [fresh, setFresh] = useState(false);
+  return (
+    <>
+      <MapledLive onPublish={() => setFresh(true)} />
+      {fresh ? <button onClick={() => { router.refresh(); setFresh(false); }}>New content — refresh</button> : null}
+    </>
+  );
+}
+```
+- 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 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.
+- 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.
+Outside React, `watchRelease({ onPublish })` from `@mapled/next` is the same watch as a plain function — it returns the function that stops it.
+### Pages Router
+A site on `pages/` mounts the route as an API route and renders the component from `@mapled/next/live/pages` in its custom App:
+```ts
+// Pages Router: pages/api/mapled/release.ts
+import { createPagesReleaseHandler } from "@mapled/next/server";
+export default createPagesReleaseHandler({ key: process.env.MAPLED_KEY! });
+```
+```tsx
+// Pages Router: pages/_app.tsx
+import type { AppProps } from "next/app";
+import { MapledLive } from "@mapled/next/live/pages";
+export default function App({ Component, pageProps }: AppProps) {
+  return (
+    <>
+      <Component {...pageProps} />
+      <MapledLive />
+    </>
+  );
+}
+```
+On a publish it replaces the page with itself through `next/router`, so the page's data runs again and it re-renders with the new props in place: scroll position and client state stay. A `#hash` in the address goes: while there is one, a replace to the same page runs no data, and every render the router makes scrolls back to the hash's anchor. For the router it is a navigation to the same URL, so `routeChangeStart` and `routeChangeComplete` fire — a pageview counter listening to them counts it too. A publish that lands while the reader is on the way to another page, or to an anchor on this one, doesn't cancel that navigation: it waits for the page they land on and refreshes that one. The first check counts too: when the release it finds went live after the page was requested — a publish between `getServerSideProps` and that check, or while a tab opened in the background waited to be shown — the page refreshes, and `onPublish` gets `previous` as `null` (which release the page read, the tab can't tell). A page requested within ten seconds after a publish may refresh once for nothing. `endpoint`, `interval` and `onPublish` work as above. (`<MapledLive />` from `@mapled/next/live` would reload the whole tab here.)
+- **Pages that follow Publish read in `getServerSideProps`.** The Pages Router has no cache tag the route could share with a page, so `createPagesReleaseHandler` answers the live release as Mapled has it, and it moves the moment someone publishes. A page that reads in `getServerSideProps` reads that same release, so the refresh always renders the new content. Keep such a page out of shared caches — Next.js sends it uncached unless you set `Cache-Control` yourself.
+- A `getStaticProps` page can't keep up: it is a copy Next.js regenerates on its own schedule — when its `revalidate` window runs out, or when a webhook of yours calls `res.revalidate` — and the route can't wait for that. A tab that refreshes before the copy does gets the old copy back and won't hear of this publish again. Read the pages that should follow Publish in `getServerSideProps` instead.
+- Reads a page makes in the browser aren't part of its data: reload them in `onPublish`.
 ## Preview drafts
 Mount the preview routes:
@@ -432,7 +524,7 @@ curl -H "x-mapled-key: $MAPLED_KEY" \
 - Lists take `filter[field]=value` or `filter[field][op]=value` (`eq`, `ne`, `lt`, `lte`, `gt`, `gte`, `in` — comma-separated, `contains`), `sort=field` / `sort=-field`, `limit` (1–100, default 100) and `offset`. Every read takes `expand` (relation keys, dotted for a second level), `fields` and `release=N` to read a published release by its number. A query the schema can't answer is a 400 `INVALID_QUERY` that says why.
 - 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.
+- 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.
 - 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": { … } }`.
@@ -448,6 +540,8 @@ Preview (drafts on the site) is built on Next.js draft mode and ships with this
 - `assetUrl(id, { width?, height?, fit?, format?, quality?, apiUrl? })` — URL of an image or file value
 - `createRevalidateHandler({ secret, tags? })` — App Router `POST` handler
 - `createPreviewHandler({ apiUrl?, appUrl? })`, `createExitPreviewHandler()` — App Router `GET` handlers of the preview routes
+- `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
 The delivery key only reads published, public content — safe to use anywhere.

package/dist/index.d.ts CHANGED Viewed

@@ -1,6 +1,7 @@
 /** Mapled delivery client for Next.js sites.
     Reads published content only — pair it with the revalidation webhook
     handler from "@mapled/next/server" for instant updates on publish. */
+export { watchRelease, type Release, type WatchOptions } from "./watch.js";
 export type MapledRecord<T = Record<string, unknown>> = {
     id: string;
     data: T;
@@ -158,4 +159,3 @@ export declare function createAppClient<S extends ContentSchema = ContentSchema>
     serverKey: string;
     apiUrl?: string;
 }): MapledAppClient<S>;
-export {};

package/dist/index.js CHANGED Viewed

@@ -1,6 +1,7 @@
 /** Mapled delivery client for Next.js sites.
     Reads published content only — pair it with the revalidation webhook
     handler from "@mapled/next/server" for instant updates on publish. */
+export { watchRelease } from "./watch.js";
 /** Renamed fields (previous keys): Mapled keeps serving a renamed field
     under its old key — and accepting it in filters, sorts and writes —
     until the alias is removed in Field settings, and names such keys in

package/dist/live-pages.d.ts ADDED Viewed

@@ -0,0 +1,4 @@
+import type { MapledLiveProps } from "./live.js";
+export type { MapledLiveProps } from "./live.js";
+export type { Release } from "./watch.js";
+export declare function MapledLive({ endpoint, interval, onPublish }: MapledLiveProps): null;

package/dist/live-pages.js ADDED Viewed

@@ -0,0 +1,142 @@
+"use client";
+/** Open tabs of a Pages Router site follow Publish. Render it once, in
+    the custom App:
+    pages/_app.tsx:
+      import { MapledLive } from "@mapled/next/live/pages";
+      <><Component {...pageProps} /><MapledLive /></>
+    It asks the release route (`createPagesReleaseHandler` from
+    "@mapled/next/server", mounted at pages/api/mapled/release) every few
+    seconds and, when a publish lands, runs the page's data again through
+    the router, in place — scroll position and client state stay. A
+    module of its own, so an App Router bundle never pulls in
+    `next/router`, nor a Pages one `next/navigation`. */
+import { useRouter } from "next/router";
+import { useEffect, useRef } from "react";
+import { watchFrom } from "./watch.js";
+/** The Pages Router's way to re-run a page's data: a replace to where the
+    tab already is. Two details make it an actual refresh — the client
+    keeps `getStaticProps` data it fetched once, so its cache is skipped;
+    and while the address has a #hash, the router takes any replace to
+    the same path — with the hash or without it — for a hash change that
+    runs no data, and every render it makes scrolls back to the hash's
+    anchor. So the hash is left first, without scrolling, and stays gone:
+    putting it back would throw the reader back to the anchor. */
+function refresh(router) {
+    const at = router.asPath;
+    const cut = at.indexOf("#");
+    const path = cut === -1 ? at : at.slice(0, cut);
+    const run = () => router.replace(path, undefined, { scroll: false, unstable_skipClientCache: true });
+    (cut === -1
+        ? run()
+        : // false: another navigation took over — the tab is somewhere else now
+            router.replace(path, undefined, { scroll: false, shallow: true }).then((ok) => ok && run()))
+        // the router has reported it (routeChangeError), and a page it can't load it loads in full
+        .catch(() => false);
+}
+const landed = (trip, now) => !trip.moving && now !== trip.from;
+/** Mapled stamps a release when its publish starts, not when it commits
+    (a big one takes seconds), and its clock and the site's differ a
+    little: a release stamped up to this long before the page was asked
+    for may still be newer than what the page read. */
+const MARGIN_MS = 10_000;
+/** Whether `first` went live after this document was asked for — then
+    the page may have read the release before it: a publish between
+    getServerSideProps and the first check, or while a tab opened in the
+    background waited to be shown before asking. Compared on the servers'
+    clock, which the route's answer tells (`Date`, plus `Age` from a CDN),
+    so a browser whose clock is off changes nothing; an answer without
+    `Date` leaves the browser's own. Every error of the estimate — a
+    second's rounding in `Date`, the time the answer took to arrive —
+    makes a refresh likelier, never rarer; a page asked for within the
+    margin after a publish refreshes once for nothing. */
+function newerThanPage(first, headers) {
+    const askedAt = globalThis.performance?.timeOrigin;
+    if (askedAt === undefined)
+        return false;
+    const date = Date.parse(headers.get("date") ?? "");
+    const offset = Number.isNaN(date) ? 0 : date + (Number(headers.get("age")) || 0) * 1000 - Date.now();
+    return Date.parse(first.publishedAt) > askedAt + offset - MARGIN_MS;
+}
+export function MapledLive({ endpoint, interval, onPublish }) {
+    // the Pages Router hands out a new router object on every render: the
+    // watch reads the latest one and restarts only for a new route or pace
+    const router = useRouter();
+    const latest = useRef({ router, onPublish });
+    const trip = useRef({ moving: false, from: null, owed: false });
+    /** the newest release the page has started from or heard of — a watch
+        restarted for a new route or pace starts from it, not from the time */
+    const followed = useRef(undefined);
+    /** runs a refresh owed by a publish mid-navigation, once the page it
+        led to has rendered — the router's end-of-navigation event and
+        React's effect with the new router object come in either order */
+    const settle = () => {
+        const now = latest.current.router;
+        if (trip.current.owed && landed(trip.current, now)) {
+            trip.current.owed = false;
+            refresh(now);
+        }
+    };
+    useEffect(() => {
+        latest.current = { router, onPublish };
+        settle();
+    }, [router, onPublish]);
+    useEffect(() => {
+        const { events } = latest.current.router;
+        const start = () => {
+            trip.current.moving = true;
+            trip.current.from = latest.current.router;
+        };
+        const end = () => {
+            trip.current.moving = false;
+            settle();
+        };
+        // a cancelled navigation is not an end: what cancelled it is itself a
+        // navigation, which has started, or a hash change, or leaves the page
+        const failed = (err) => {
+            if (!err?.cancelled)
+                end();
+        };
+        // a jump to an anchor has no routeChangeStart, but the router awaits
+        // its render all the same
+        events.on("routeChangeStart", start);
+        events.on("hashChangeStart", start);
+        events.on("routeChangeComplete", end);
+        events.on("routeChangeError", failed);
+        events.on("hashChangeComplete", end);
+        return () => {
+            events.off("routeChangeStart", start);
+            events.off("hashChangeStart", start);
+            events.off("routeChangeComplete", end);
+            events.off("routeChangeError", failed);
+            events.off("hashChangeComplete", end);
+        };
+    }, []);
+    useEffect(() => watchFrom({
+        endpoint,
+        interval,
+        onPublish: (next, previous) => {
+            followed.current = next.release;
+            const { router: now, onPublish: custom } = latest.current;
+            if (custom)
+                custom(next, previous);
+            else if (!landed(trip.current, now))
+                trip.current.owed = true;
+            else {
+                trip.current.owed = false;
+                refresh(now);
+            }
+        },
+    },
+    // the first answer names what is live, not what the page read:
+    // one that went live after the page was asked for counts as a
+    // publish, with no `previous` — which release the page read, the
+    // tab can't tell
+    (first, headers) => {
+        const from = followed.current ?? (newerThanPage(first, headers) ? null : first.release);
+        followed.current = Math.max(first.release, followed.current ?? 0);
+        return from;
+    }), [endpoint, interval]);
+    return null;
+}

package/dist/live.d.ts ADDED Viewed

@@ -0,0 +1,12 @@
+import { type Release } from "./watch.js";
+export type { Release } from "./watch.js";
+export type MapledLiveProps = {
+    /** Where the release route is mounted (default "/api/mapled/release"). */
+    endpoint?: string;
+    /** Seconds between checks while the tab is visible (default 10, at least 2). */
+    interval?: number;
+    /** Runs instead of the refresh — to offer "New content — refresh"
+        rather than change the page under the reader. */
+    onPublish?: (next: Release, previous: number | null) => void;
+};
+export declare function MapledLive({ endpoint, interval, onPublish }: MapledLiveProps): null;

package/dist/live.js ADDED Viewed

@@ -0,0 +1,32 @@
+"use client";
+/** Open tabs follow Publish. Render it once, in the root layout:
+    app/layout.tsx:
+      import { MapledLive } from "@mapled/next/live";
+      <body>{children}<MapledLive /></body>
+    It asks the release route (`createReleaseHandler` from
+    "@mapled/next/server", mounted at /api/mapled/release) every few
+    seconds and, when a publish lands, refreshes the page's server
+    components in place — scroll position and client state stay. */
+import { useRouter } from "next/navigation";
+import { useEffect, useRef } from "react";
+import { watchRelease } from "./watch.js";
+export function MapledLive({ endpoint, interval, onPublish }) {
+    const router = useRouter();
+    const custom = useRef(onPublish);
+    useEffect(() => {
+        custom.current = onPublish;
+    }, [onPublish]);
+    useEffect(() => watchRelease({
+        endpoint,
+        interval,
+        onPublish: (next, previous) => {
+            if (custom.current)
+                custom.current(next, previous);
+            else
+                router.refresh();
+        },
+    }), [endpoint, interval, router]);
+    return null;
+}

package/dist/server.d.ts CHANGED Viewed

@@ -25,3 +25,42 @@ export declare function createRevalidateHandler(options: {
         client fetch. */
     tags?: string[];
 }): (req: Request) => Promise<Response>;
+type ReleaseOptions = {
+    key: string;
+    apiUrl?: string;
+    /** Seconds one answer is reused (default 5, at least 1). */
+    ttl?: number;
+};
+/** 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. */
+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;
+}): (req: Request) => Promise<Response>;
+/** What the Pages Router hands an API route: `NextApiRequest` and
+    `NextApiResponse` are these and more. */
+type PagesApiRequest = {
+    method?: string;
+    headers: Record<string, string | string[] | undefined>;
+};
+type PagesApiResponse = {
+    statusCode: number;
+    setHeader(name: string, value: string): unknown;
+    end(body?: string): unknown;
+};
+/** The release route of a Pages Router site — the default export of
+    pages/api/mapled/release.ts, for `<MapledLive />` from
+    "@mapled/next/live/pages" to ask about. The Pages Router has no cache
+    tag a route could share with a page, so the pointer is Mapled's live
+    release, read every `ttl` seconds: it moves the moment someone
+    publishes. A page that reads in `getServerSideProps` reads that same
+    release, and a tab refreshed on it renders the new content; a
+    `getStaticProps` page is a copy Next regenerates on its own schedule,
+    which the pointer can't wait for (README, «Live updates»). */
+export declare function createPagesReleaseHandler(options: ReleaseOptions): (req: PagesApiRequest, res: PagesApiResponse) => Promise<void>;
+export {};

package/dist/server.js CHANGED Viewed

@@ -99,3 +99,117 @@ export function createRevalidateHandler(options) {
         return Response.json({ revalidated: true });
     };
 }
+/** 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. */
+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;
+    let held = null;
+    /** when Mapled was last asked — an answer or a failure, either waits a ttl */
+    let askedAt = 0;
+    let loading = null;
+    let complained = false;
+    async function load() {
+        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;
+        }
+        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"}.`);
+            }
+        }
+        finally {
+            askedAt = Date.now();
+        }
+    }
+    /** `asked` — the tab's If-None-Match */
+    return async function answer(asked) {
+        if (Date.now() - askedAt >= ttlMs) {
+            loading ??= load().finally(() => {
+                loading = null;
+            });
+            await loading;
+        }
+        if (!held) {
+            return { status: 502, headers: { "cache-control": "no-store" }, body: { error: "The live release isn't available right now." } };
+        }
+        // the CDN's copy lives no longer than this instance's
+        const left = Math.max(1, Math.ceil((ttlMs - (Date.now() - askedAt)) / 1000));
+        const etag = `W/"r${held.release ?? 0}"`;
+        const headers = { "cache-control": `public, max-age=0, s-maxage=${left}`, etag };
+        if (asked && asked.split(",").some((t) => t.trim().replace(/^W\//, "") === etag.slice(2))) {
+            return { status: 304, headers };
+        }
+        return { status: 200, headers, body: held };
+    };
+}
+/** 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. */
+export function createReleaseHandler(options) {
+    const answer = releaseAnswers(options, { revalidate: options.revalidate ?? 3600, tags: ["mapled"] });
+    return async function GET(req) {
+        // read first: a handler that looks at its request is never prerendered
+        const { status, headers, body } = await answer(req.headers.get("if-none-match"));
+        return status === 304 ? new Response(null, { status, headers }) : Response.json(body, { status, headers });
+    };
+}
+/** The release route of a Pages Router site — the default export of
+    pages/api/mapled/release.ts, for `<MapledLive />` from
+    "@mapled/next/live/pages" to ask about. The Pages Router has no cache
+    tag a route could share with a page, so the pointer is Mapled's live
+    release, read every `ttl` seconds: it moves the moment someone
+    publishes. A page that reads in `getServerSideProps` reads that same
+    release, and a tab refreshed on it renders the new content; a
+    `getStaticProps` page is a copy Next regenerates on its own schedule,
+    which the pointer can't wait for (README, «Live updates»). */
+export function createPagesReleaseHandler(options) {
+    const answer = releaseAnswers(options);
+    return async function handler(req, res) {
+        const method = req.method ?? "GET";
+        if (method !== "GET" && method !== "HEAD") {
+            res.statusCode = 405;
+            res.setHeader("allow", "GET, HEAD");
+            res.end();
+            return;
+        }
+        const asked = req.headers["if-none-match"];
+        const { status, headers, body } = await answer(Array.isArray(asked) ? asked.join(",") : (asked ?? null));
+        res.statusCode = status;
+        for (const [name, value] of Object.entries(headers))
+            res.setHeader(name, value);
+        if (body === undefined) {
+            res.end();
+            return;
+        }
+        // written as is: res.json would swap the ETag for a hash of the body
+        res.setHeader("content-type", "application/json; charset=utf-8");
+        res.end(method === "HEAD" ? undefined : JSON.stringify(body));
+    };
+}

package/dist/watch.d.ts ADDED Viewed

@@ -0,0 +1,30 @@
+/** Publish notifications for open tabs: the page asks its own server
+    which release is live (the route `createReleaseHandler` from
+    "@mapled/next/server" serves) and hears about it when that moves.
+    Framework-free on purpose — `<MapledLive />` from "@mapled/next/live"
+    is this plus `router.refresh()`. */
+export type Release = {
+    release: number;
+    publishedAt: string;
+};
+export type WatchOptions = {
+    /** Where the release route is mounted (default "/api/mapled/release"). */
+    endpoint?: string;
+    /** Seconds between checks while the tab is visible (default 10, at least 2). */
+    interval?: number;
+    /** A publish landed: `next` is live now; `previous` is the release the
+        watch knew before — null when nothing was published yet. */
+    onPublish: (next: Release, previous: number | null) => void;
+};
+/** Starts watching; returns the function that stops it. The first answer
+    is where the watch starts from; `onPublish` runs once per release that
+    comes after it. A hidden tab doesn't ask — it checks the moment it is
+    shown again — and a route that fails is asked less and less often. */
+export declare function watchRelease(options: WatchOptions): () => void;
+/** The watch behind `watchRelease`, for a caller that can tell more about
+    where to start than the first answer can. `from` gets the first
+    release the route names, with the answer's headers, and returns the
+    release the page is on — the first answer's own number to start from
+    it, an older one (or null: not known) to hand the first answer to
+    `onPublish` as well. Not part of the package's API. */
+export declare function watchFrom(options: WatchOptions, from?: (first: Release, headers: Headers) => number | null): () => void;

package/dist/watch.js ADDED Viewed

@@ -0,0 +1,104 @@
+/** Publish notifications for open tabs: the page asks its own server
+    which release is live (the route `createReleaseHandler` from
+    "@mapled/next/server" serves) and hears about it when that moves.
+    Framework-free on purpose — `<MapledLive />` from "@mapled/next/live"
+    is this plus `router.refresh()`. */
+const DEFAULT_ENDPOINT = "/api/mapled/release";
+const MAX_BACKOFF_MS = 5 * 60_000;
+/** The route's answer — null before the first publish — or undefined
+    when it isn't one. */
+function pointer(body) {
+    if (!body || typeof body !== "object")
+        return undefined;
+    const { release, publishedAt } = body;
+    if (release === null)
+        return null;
+    if (!Number.isInteger(release) || release < 1 || typeof publishedAt !== "string")
+        return undefined;
+    return { release: release, publishedAt };
+}
+/** Starts watching; returns the function that stops it. The first answer
+    is where the watch starts from; `onPublish` runs once per release that
+    comes after it. A hidden tab doesn't ask — it checks the moment it is
+    shown again — and a route that fails is asked less and less often. */
+export function watchRelease(options) {
+    return watchFrom(options);
+}
+/** The watch behind `watchRelease`, for a caller that can tell more about
+    where to start than the first answer can. `from` gets the first
+    release the route names, with the answer's headers, and returns the
+    release the page is on — the first answer's own number to start from
+    it, an older one (or null: not known) to hand the first answer to
+    `onPublish` as well. Not part of the package's API. */
+export function watchFrom(options, from) {
+    const endpoint = options.endpoint ?? DEFAULT_ENDPOINT;
+    const everyMs = Math.max(2, options.interval ?? 10) * 1000;
+    const doc = typeof document === "undefined" ? null : document;
+    /** undefined until the first answer; null while nothing is published */
+    let seen;
+    let failures = 0;
+    let stopped = false;
+    let timer;
+    let inFlight = null;
+    const visible = () => !doc || doc.visibilityState !== "hidden";
+    const schedule = () => {
+        if (stopped || !visible())
+            return;
+        timer = setTimeout(check, Math.min(everyMs * 2 ** failures, MAX_BACKOFF_MS));
+    };
+    async function check() {
+        if (stopped || inFlight)
+            return;
+        const request = new AbortController();
+        inFlight = request;
+        let news = null;
+        try {
+            // no-cache: the browser revalidates by ETag, so a quiet check is a 304
+            const res = await fetch(endpoint, { cache: "no-cache", headers: { accept: "application/json" }, signal: request.signal });
+            const now = res.ok ? pointer(await res.json()) : undefined;
+            if (stopped)
+                return;
+            if (now === undefined) {
+                failures += 1;
+            }
+            else {
+                failures = 0;
+                if (seen === undefined)
+                    seen = now ? (from ? from(now, res.headers) : now.release) : null;
+                if (now && now.release > (seen ?? 0)) {
+                    // releases only grow (a rollback is a new one): an answer from a
+                    // server that hasn't caught up yet never looks like news
+                    news = { next: now, previous: seen };
+                    seen = now.release;
+                }
+            }
+        }
+        catch {
+            if (stopped)
+                return;
+            failures += 1;
+        }
+        finally {
+            if (inFlight === request)
+                inFlight = null;
+        }
+        schedule();
+        // after the next check is set: a callback that throws doesn't end the watch
+        if (news)
+            options.onPublish(news.next, news.previous);
+    }
+    const onVisibility = () => {
+        clearTimeout(timer);
+        if (visible())
+            void check();
+    };
+    doc?.addEventListener("visibilitychange", onVisibility);
+    if (visible())
+        void check();
+    return () => {
+        stopped = true;
+        clearTimeout(timer);
+        inFlight?.abort();
+        doc?.removeEventListener("visibilitychange", onVisibility);
+    };
+}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@mapled/next",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "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",
@@ -27,6 +27,14 @@
     "./server": {
       "types": "./dist/server.d.ts",
       "default": "./dist/server.js"
+    },
+    "./live": {
+      "types": "./dist/live.d.ts",
+      "default": "./dist/live.js"
+    },
+    "./live/pages": {
+      "types": "./dist/live-pages.d.ts",
+      "default": "./dist/live-pages.js"
     }
   },
   "files": [