@mapled/next 0.7.0 → 0.8.0

package/README.md

@@ -1,21 +1,220 @@
 # @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) • [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
 
 ```bash
 npm install @mapled/next
 ```
 
-Grab the delivery key in Mapled: project → Integrations → **Your site**, and put it in your site's env:
+Grab the delivery key in Mapled: project settings (the gear in the project's header) → **Integrations** → **Your site**, and put it in your site's env:
 
 ```bash
 MAPLED_KEY=mk_live_…
 ```
 
+## Integrate by hand
+
+An AI agent connected through [`@mapled/mcp`](https://www.npmjs.com/package/@mapled/mcp) does all of this for you. Nothing in it needs one, though: this is the same integration, step by step — from a Next.js site with hardcoded content to a site its editors run from Mapled. Plan on an hour for a small site.
+
+You need a Mapled project where you can change the structure (the builder plan), a Next.js 14+ site on the App Router, and Node 18 or newer. The example is a site with a homepage and a blog; the keys (`homepage`, `articles`) are whatever you choose in step 1.
+
+### 1. Model the content
+
+In Mapled, open the project and press the wrench in the header (**Structure**) → **Collections**. Create a **single** for every one-off part of the site (`homepage`, `footer`) and a **collection** for every list of alike things (`articles`, `team`), then **Add field** for each text, image and link the code hardcodes today.
+
+- Keys are what the code reads — `getRecords("articles")`, `data.title`. A key can be renamed later and the old one keeps working as an alias, but it is a migration: choose them with care.
+- A collection whose records have pages of their own needs a **Slug** field — `getRecordBySlug` finds records by it.
+- Write a **Help text** for every field. Editors see it under the field; write it for someone who has never seen the code.
+- Mark a field **Sensitive** when editors keep it but the site must never receive it.
+
+### 2. Fill it in and publish once
+
+Open **Content**, move the hardcoded texts and images into records, then **Review & publish**. The site only ever reads published releases: before the first publish the delivery API answers 404 “Nothing published yet.” — `getSingle` and `getRecord` read that as `null`, `getRecords` throws.
+
+### 3. Link the repository and generate types
+
+```bash
+npx @mapled/cli auth login
+npx @mapled/cli project link
+npx @mapled/cli types generate
+npx @mapled/cli schema pull
+```
+
+Your browser opens Mapled, you pick the project and authorize; `project link` writes `mapled.json`, `types generate` writes `mapled-types.ts` — an interface per collection and single, tied together by `MapledSchema` — and `schema pull` records the schema the site is built against in `mapled/schema.json`, which `schema diff` and `doctor` compare with Mapled later. ([`@mapled/cli`](https://www.npmjs.com/package/@mapled/cli) has the details of every command used here.)
+
+### 4. Create the client
+
+Install the package and set `MAPLED_KEY` ([Install](#install)) in `.env.local` and in your hosting's environment. Then one client for the whole site:
+
+```ts
+// lib/mapled.ts
+import { createClient } from "@mapled/next";
+import type { MapledSchema } from "../mapled-types";
+
+export const mapled = createClient<MapledSchema>({ key: process.env.MAPLED_KEY! });
+```
+
+With `MapledSchema` every read is typed by its key, and a misspelled collection or field is a build error.
+
+### 5. Replace the hardcoded content with reads
+
+Read in Server Components — no client-side fetching, no loading states. A single:
+
+```tsx
+// app/page.tsx
+import { assetUrl } from "@mapled/next";
+import { mapled } from "../lib/mapled";
+
+export default async function Home() {
+  const home = await mapled.getSingle("homepage");
+  if (!home) return null; // nothing published yet
+
+  return (
+    <main>
+      <h1>{home.data.headline}</h1>
+      <p>{home.data.intro}</p>
+      {home.data.cover ? <img src={assetUrl(home.data.cover, { width: 1280 })} alt="" /> : null}
+    </main>
+  );
+}
+```
+
+A list:
+
+```tsx
+// app/blog/page.tsx
+import Link from "next/link";
+import { mapled } from "../../lib/mapled";
+
+export default async function Blog() {
+  const { records } = await mapled.getRecords("articles", { sort: "-date", limit: 20 });
+
+  return (
+    <ul>
+      {records.map((post) => (
+        <li key={post.id}>
+          <Link href={`/blog/${post.data.slug}`}>{post.data.title}</Link>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+A page per record — new records get their page without a deploy:
+
+```tsx
+// app/blog/[slug]/page.tsx
+import { notFound } from "next/navigation";
+import Markdown from "react-markdown";
+import { mapled } from "../../../lib/mapled";
+
+export async function generateStaticParams() {
+  const { records } = await mapled.getRecords("articles", { fields: ["slug"] });
+  return records.map((post) => ({ slug: post.data.slug }));
+}
+
+export default async function Article({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const post = await mapled.getRecordBySlug("articles", slug);
+  if (!post) notFound();
+
+  return (
+    <article>
+      <h1>{post.data.title}</h1>
+      <Markdown>{post.data.body}</Markdown>
+    </article>
+  );
+}
+```
+
+(`params` is a Promise since Next.js 15; on 14 it is the plain object.) Rich text is Markdown — render it with a component such as `react-markdown`, never as raw HTML. Leave in the code what editors shouldn't touch: layout, navigation structure, anything that is logic rather than content.
+
+### 6. Refresh the site on publish
+
+Reads are cached (`revalidate: 3600`) and tagged; a webhook refreshes them the moment someone publishes.
+
+```ts
+// app/api/mapled/revalidate/route.ts
+import { createRevalidateHandler } from "@mapled/next/server";
+
+export const POST = createRevalidateHandler({
+  secret: process.env.MAPLED_WEBHOOK_SECRET!,
+});
+```
+
+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
+// app/api/mapled/preview/route.ts
+import { createPreviewHandler } from "@mapled/next/server";
+
+export const GET = createPreviewHandler();
+```
+
+```ts
+// app/api/mapled/preview/exit/route.ts
+import { createExitPreviewHandler } from "@mapled/next/server";
+
+export const GET = createExitPreviewHandler();
+```
+
+The **Preview** button in Mapled opens the site at the origin of the webhook URL from step 6, on exactly this path — `/api/mapled/preview` — so keep the route there. It turns on Next.js draft mode, and every read of the client switches to live drafts, uncached, with no changes in your components.
+
+### 8. Forms
+
+A contact or signup form posts straight to Mapled; submissions land in **Forms**, with e-mail notifications and spam protection. Create the form once:
+
+```bash
+npx @mapled/cli forms create "Contact"
+```
+
+and post to it from the site — see [Forms](#forms) for the component.
+
+### 9. Live data
+
+Orders, bookings, votes — records the site's backend writes and reads immediately, without Publish — go to collections created with the mode **Live data** and are reached with the server key: see [Live data](#live-data).
+
+### 10. Record the integration
+
+```bash
+npx @mapled/cli scan --write
+npx @mapled/cli bindings push
+npx @mapled/cli md pull
+```
+
+`scan` reads the code and writes `mapled/manifest.json`: which page reads which collection and field. `bindings push` sends it to Mapled, so editors see where a field appears and get a warning before a change would break the site (**Structure** → **Bindings**). `md pull` writes `MAPLED.md`, the guide for whoever works on the site next — person or AI agent. Commit `mapled.json`, `mapled-types.ts`, `mapled/schema.json`, `mapled/manifest.json` and `MAPLED.md`; never commit an env file.
+
+### 11. Check everything
+
+```bash
+npx @mapled/cli doctor
+```
+
+It checks the integration from both sides — the repository and what Mapled sees of the deployed site. The list below is what an agent's setup has to pass before Mapled calls it complete; `doctor` answers all of it except the last two lines, which are yours to check:
+
+- the site reads content from Mapled (“Site reads content — Last read …”);
+- a publish refreshes it (“Publish webhook — Delivered …”);
+- **Preview** in Mapled opens the site with drafts (“Preview on the site — Responds at …”);
+- bindings are pushed and healthy, and the integration is in sync (“Bindings”, “Integration”);
+- no env file or secret is tracked by git (“Secrets in git”);
+- every field has a help text (**Structure** → **Collections**);
+- the site builds.
+
+Later, when the structure changes in Mapled, `npx @mapled/cli schema diff` says what changed and whether it breaks the site; after updating the code, run `types generate`, `scan --write`, `bindings push` and `md pull` again.
+
 ## Read published content
 
 ```ts
@@ -114,7 +313,67 @@ export const POST = createRevalidateHandler({
 });
 ```
 
-Then in Mapled (project → Integrations → **Your site**) set the revalidation webhook to `https://your-site.com/api/mapled/revalidate` and copy the signing secret into `MAPLED_WEBHOOK_SECRET`. Every publish sends a signed ping; the handler verifies the `x-mapled-signature` HMAC and revalidates the `mapled` tags.
+Then in Mapled (**Integrations** → **Your site**) set the revalidation webhook to `https://your-site.com/api/mapled/revalidate` and copy the signing secret into `MAPLED_WEBHOOK_SECRET`. Every publish sends a signed ping; the handler verifies the `x-mapled-signature` HMAC and revalidates the `mapled` tags.
+
+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.
 
 ## Preview drafts
 
@@ -134,6 +393,64 @@ export const GET = createExitPreviewHandler();
 
 The **Preview** button in Mapled opens your site through a one-time link: the route turns on Next.js draft mode, and every `getRecords`/`getRecord`/`getSingle` call automatically switches to live drafts, uncached. No code changes in your components — the client detects draft mode on its own. Sessions last two hours; `/api/mapled/preview/exit` leaves preview.
 
+Mapled finds the site by the revalidation webhook's URL — preview opens at its origin, on `/api/mapled/preview` — so set the webhook up first and keep the route on that path.
+
+## Forms
+
+A form is created once — `npx @mapled/cli forms create "Contact"`, or by your AI agent — and gets a key (`contact`). The site posts submissions as flat JSON with the delivery key; they show up in Mapled under **Forms** right away, and the form's recipients — the project's owners, unless its settings name others — get an e-mail. Forms never wait for Publish.
+
+```tsx
+// app/contact/ContactForm.tsx
+"use client";
+
+import { useState, type FormEvent } from "react";
+
+const CONSENT = "I agree to be contacted about my request.";
+
+export function ContactForm() {
+  const [state, setState] = useState<"idle" | "sending" | "sent" | "failed">("idle");
+
+  async function submit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    setState("sending");
+    const form = new FormData(event.currentTarget);
+    const res = await fetch("https://api.mapled.io/v1/delivery/forms/contact", {
+      method: "POST",
+      headers: { "content-type": "application/json", "x-mapled-key": process.env.NEXT_PUBLIC_MAPLED_KEY! },
+      body: JSON.stringify({
+        name: form.get("name"),
+        email: form.get("email"),
+        message: form.get("message"),
+        _gotcha: form.get("_gotcha"), // the honeypot: people leave it empty
+        _consent: form.get("consent") ? CONSENT : undefined,
+        _page: window.location.pathname,
+      }),
+    });
+    setState(res.ok ? "sent" : "failed");
+  }
+
+  if (state === "sent") return <p>Thank you — we'll be in touch.</p>;
+  return (
+    <form onSubmit={submit}>
+      <input name="name" required />
+      <input name="email" type="email" required />
+      <textarea name="message" required />
+      <input name="_gotcha" tabIndex={-1} autoComplete="off" aria-hidden="true" style={{ display: "none" }} />
+      <label>
+        <input name="consent" type="checkbox" required /> {CONSENT}
+      </label>
+      <button disabled={state === "sending"}>Send</button>
+      {state === "failed" ? <p>That didn't go through. Try again in a minute.</p> : null}
+    </form>
+  );
+}
+```
+
+- The endpoint is open to browsers (CORS) and takes the **delivery key** — the one key that is safe in client code. Expose it as `NEXT_PUBLIC_MAPLED_KEY`; never the server key or the webhook secret. To keep even that out of the bundle, post from a Server Action with `MAPLED_KEY` instead — all visitors then share your server's address for the limit below.
+- The body is one flat object: up to 50 fields of text (5,000 characters), numbers and booleans. Keys starting with `_` are instructions, not answers: `_gotcha` (a hidden field bots fill in — such submissions are accepted and filed as spam), `_consent` (the exact label of the consent checkbox the visitor ticked, kept as evidence), `_page` (where the form was), `_test: true` (a test submission: no e-mail, not counted).
+- `201 { "ok": true }` on success. `400 VALIDATION_FAILED` for a body of another shape, `404` for an unknown key or form, `429 RATE_LIMITED` past 30 submissions a minute per form and address, `429 FORMS_LIMIT` when the project's monthly submissions are used up, `410 PROJECT_ARCHIVED` for an archived project.
+- `npx @mapled/cli forms list` shows the project's forms and their URLs.
+
 ## Live data
 
 Operational collections skip the publish cycle — saves take effect immediately. Your site's backend reads **and writes** them through the Application Data API with the project's **server key** (Mapled: Integrations → Your site). Server-side only; the key must never reach the browser.
@@ -155,12 +472,43 @@ 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.
 
+## 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`.
+
+| Request | Answer |
+| --- | --- |
+| `GET /v1/delivery/collections/{collection}/records` | `{ records: [{ id, data, expanded? }], total, release }` |
+| `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 |
+| `POST /v1/delivery/forms/{form}` | `201 { ok: true }` — see [Forms](#forms) |
+
+```bash
+curl -H "x-mapled-key: $MAPLED_KEY" \
+  "https://api.mapled.io/v1/delivery/collections/articles/records?filter[featured]=true&filter[date][gte]=2026-01-01&sort=-date&limit=10&expand=author&fields=title,slug"
+```
+
+- 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: 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": { … } }`.
+
+Preview (drafts on the site) is built on Next.js draft mode and ships with this package only.
+
 ## API
 
 - `createClient({ key, apiUrl?, release? })` → `getRecords(collection, opts?)`, `getRecord(collection, id, opts?)`, `getRecordBySlug(collection, slug, opts?)`, `getSingle(key, opts?)`, `getRelease()`; `createClient<MapledSchema>(…)` with the generated `MapledSchema` types every read by its key (`MapledClient<S>`, `MapledAppClient<S>` name the typed clients)
 - list `opts`: `filter` (a value for equality, or `{ eq, ne, lt, lte, gt, gte, in, contains }` — text takes eq/ne/in/contains, numbers and dates comparisons, booleans eq/ne, image and relation ids eq/ne/in; a one-to-many relation matches when it includes the id), `sort` (`"field"` / `"-field"`, not on relations or images), `limit` (≤100), `offset`
 - every read: `expand` (relation keys, dotted for a second level), `fields` (data keys to keep), `release` (pin to a published release), `revalidate`, `tags`; a query the schema can't answer fails with a 400 `INVALID_QUERY` message, and errors carry the API's `code` on `MapledError`
+- `createAppClient({ serverKey, apiUrl? })` → `list(collection, opts?)`, `get(collection, id)`, `create(collection, data)`, `update(collection, id, data)`, `remove(collection, id)`
+- `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
 - `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

@@ -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

@@ -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.d.ts

@@ -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

@@ -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

@@ -25,3 +25,19 @@ export declare function createRevalidateHandler(options: {
         client fetch. */
     tags?: string[];
 }): (req: Request) => Promise<Response>;
+/** GET handler for the release route (mount at /api/mapled/release):
+    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. One answer is 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. */
+export declare function createReleaseHandler(options: {
+    key: string;
+    apiUrl?: string;
+    /** Seconds one answer is reused (default 5, at least 1). */
+    ttl?: number;
+    /** 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>;

package/dist/server.js

@@ -99,3 +99,72 @@ export function createRevalidateHandler(options) {
         return Response.json({ revalidated: true });
     };
 }
+/** GET handler for the release route (mount at /api/mapled/release):
+    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. One answer is 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. */
+export function createReleaseHandler(options) {
+    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: { revalidate: options.revalidate ?? 3600, tags: ["mapled"] },
+            };
+            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();
+        }
+    }
+    return async function GET(req) {
+        // read first: a handler that looks at its request is never prerendered
+        const asked = req.headers.get("if-none-match");
+        if (Date.now() - askedAt >= ttlMs) {
+            loading ??= load().finally(() => {
+                loading = null;
+            });
+            await loading;
+        }
+        if (!held) {
+            return Response.json({ error: "The live release isn't available right now." }, { status: 502, headers: { "cache-control": "no-store" } });
+        }
+        // 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 new Response(null, { status: 304, headers });
+        }
+        return Response.json(held, { headers });
+    };
+}

package/dist/watch.d.ts

@@ -0,0 +1,23 @@
+/** 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;

package/dist/watch.js

@@ -0,0 +1,96 @@
+/** 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) {
+    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 ? now.release : null;
+                }
+                else 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

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