@mapled/next 0.11.1 → 0.11.3

package/README.md

@@ -284,6 +284,17 @@ const about = await mapled.getRecordBySlug("pages", "about", { release: live!.re
 
 `createClient({ key, release: 12 })` pins every read — a way to hold a site on a known-good release without publishing anything. A release never changes, so pinned reads are cached until the next publish (`revalidate: false` unless you pass your own); a release that doesn't exist fails with a 404 `RELEASE_NOT_FOUND` rather than reading as a missing record. In preview (draft mode) the pin is dropped: drafts are unversioned.
 
+### Read in a language
+
+A project with several languages (Mapled: Settings → Languages) translates the fields an editor marked as translated. Every read takes `locale`:
+
+```ts
+const about = await mapled.getRecordBySlug("pages", "about", { locale: "ru" });
+const { records, locale } = await mapled.getRecords("articles", { locale: "pt-BR", sort: "-date" }); // locale: "pt-BR"
+```
+
+A translated field answers in that language, or in the first language of the project's fallback chain that has a value — the default language at the end — so a value is never missing where the default language has one; shared fields come as they are. Filters, sorts and slug lookups see that language too, and the answer names the language it is in (`locale`). `createClient({ key, locale: "ru" })` reads everything in that language (a read's own `locale` wins). Without `locale` a read answers in the project's default language, as before. A language the project doesn't have — or that the release you read was published without — fails with a 400 `INVALID_QUERY`.
+
 ## Rich text
 
 `rich_text` values are Markdown (headings, lists, links, bold/italic, images as `![alt](url)`). Render them with a Markdown component such as `react-markdown` — never inject them as raw HTML.
@@ -347,7 +358,7 @@ export default function RootLayout({ children }: { children: ReactNode }) {
 }
 ```
 
-`<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`:
+`<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. The first check counts too: when the release it finds was acknowledged by your site's cache after the page was requested — a publish between the render 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 rendered, the tab can't tell). A page requested within ten seconds after the site answered a publish's webhook may refresh once for nothing. To offer the update instead of applying it under the reader, pass `onPublish`:
 
 ```tsx
 "use client";
@@ -389,7 +400,7 @@ export async function POST(req: Request) {
 }
 ```
 
-- 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.
+- The route answers `{ release, publishedAt, acknowledgedAt }` — the number of publishes, the time of the last one and when your site's cache answered its webhook (0.11.3 and later; the Pages Router's route answers the first two), 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" />`.
@@ -546,7 +557,7 @@ 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.
+- 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`, `release=N` to read a published release by its number and `locale=ru` to read in one of the project's languages: a translated field answers in it or in the first language of the project's fallback chain that has a value, filters and slug lookups see that language, and the answer carries `locale`. 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`.
@@ -559,8 +570,8 @@ Preview (drafts on the site) is built on Next.js draft mode and ships with this
 
 - `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)`
+- every read: `expand` (relation keys, dotted for a second level), `fields` (data keys to keep), `release` (pin to a published release), `locale` (read in one of the project's languages, through its fallback chain), `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, opts?)`, `create(collection, data)`, `update(collection, id, data)`, `remove(collection, id)` — `list` and `get` take `locale` too
 - `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

package/dist/index.d.ts

@@ -38,6 +38,11 @@ export type ReadOptions = {
         never changes, so pinned reads stay cached until the next publish
         (`revalidate: false` unless you say otherwise). */
     release?: number;
+    /** Read in this language: a translated field answers in it, or in the
+        first language of the project's fallback chain that has a value —
+        the default language at the end. One of the project's languages, in
+        any case (`pt_br` → `pt-BR`); another is a 400 INVALID_QUERY. */
+    locale?: string;
 };
 export type ListOptions = ReadOptions & {
     /** Filters on top-level fields, ANDed: { slug: "about", price: { gte: 10 } }. */
@@ -52,6 +57,8 @@ export type ListResult<T = Record<string, unknown>> = {
     records: MapledRecord<T>[];
     total: number;
     release: number;
+    /** The language the answer is in — when the read asked for one. */
+    locale?: string;
     /** Renamed fields whose previous keys this answer still serves, by
         collection: `{ products: { price: "amount" } }`. Absent when nothing
         was renamed. Outside production the SDK warns about each once. */
@@ -127,8 +134,8 @@ export interface MapledAppClient<S extends ContentSchema = ContentSchema> {
         records: AppRecord<T>[];
         total: number;
     }>;
-    get<K extends keyof CollectionsOf<S> & string>(collection: K, id: string): Promise<AppRecord<CollectionsOf<S>[K]> | null>;
-    get<T = Data>(collection: LooseKey<S, CollectionsOf<S>>, id: string): Promise<AppRecord<T> | null>;
+    get<K extends keyof CollectionsOf<S> & string>(collection: K, id: string, opts?: AppReadOptions): Promise<AppRecord<CollectionsOf<S>[K]> | null>;
+    get<T = Data>(collection: LooseKey<S, CollectionsOf<S>>, id: string, opts?: AppReadOptions): Promise<AppRecord<T> | null>;
     create<K extends keyof CollectionsOf<S> & string>(collection: K, data: CollectionsOf<S>[K]): Promise<AppRecord<CollectionsOf<S>[K]>>;
     create<T = Data>(collection: LooseKey<S, CollectionsOf<S>>, data: LooseData<S, T>): Promise<AppRecord<T>>;
     update<K extends keyof CollectionsOf<S> & string>(collection: K, id: string, data: CollectionsOf<S>[K]): Promise<AppRecord<CollectionsOf<S>[K]>>;
@@ -146,11 +153,17 @@ export type AppListOptions = {
     sort?: string;
     limit?: number;
     offset?: number;
+    /** Read in this language, through the project's fallback chain (as `ReadOptions.locale`). */
+    locale?: string;
 };
+export type AppReadOptions = Pick<AppListOptions, "locale">;
 export declare function createClient<S extends ContentSchema = ContentSchema>(config: {
     key: string;
     apiUrl?: string;
+    /** Every read of this client is pinned to this release. */
     release?: number;
+    /** Every read of this client is in this language (`ReadOptions.locale`); a read's own `locale` wins. */
+    locale?: string;
 }): MapledClient<S>;
 /** Live data (operational collections): the site's backend reads and
     writes records that take effect immediately — no publish involved.

package/dist/index.js

@@ -106,6 +106,10 @@ export function createClient(config) {
         // drafts are unversioned: a pin only shapes published reads
         if (release !== undefined && !draft)
             search.set("release", String(release));
+        // a language shapes drafts too; an empty one means the client's
+        const locale = opts.locale || config.locale;
+        if (locale)
+            search.set("locale", locale);
         const qs = search.toString();
         const init = draft
             ? {
@@ -206,6 +210,11 @@ export function createAppClient(config) {
     const base = (config.apiUrl ?? "https://api.mapled.io").replace(/\/+$/, "");
     if (!config.serverKey)
         throw new Error("Mapled: a server key is required.");
+    // the same refusal @mapled/client makes: the server key must never
+    // reach the browser, whatever bundling put this module there
+    if (typeof window !== "undefined" && typeof document !== "undefined") {
+        throw new Error("Mapled: the server key must never reach a browser — call createAppClient from your server.");
+    }
     async function call(method, path, search, data) {
         const qs = search?.toString();
         const res = await fetch(`${base}${path}${qs ? `?${qs}` : ""}`, {
@@ -246,11 +255,16 @@ export function createAppClient(config) {
                 search.set("limit", String(opts.limit));
             if (opts.offset !== undefined)
                 search.set("offset", String(opts.offset));
+            if (opts.locale)
+                search.set("locale", opts.locale);
             return call("GET", collectionPath(collection), search);
         },
-        async get(collection, id) {
+        async get(collection, id, opts = {}) {
             try {
-                const body = await call("GET", `${collectionPath(collection)}/${encodeURIComponent(id)}`);
+                const search = new URLSearchParams();
+                if (opts.locale)
+                    search.set("locale", opts.locale);
+                const body = await call("GET", `${collectionPath(collection)}/${encodeURIComponent(id)}`, search);
                 return body.record;
             }
             catch (err) {

package/dist/live-pages.js

@@ -14,7 +14,7 @@
     `next/router`, nor a Pages one `next/navigation`. */
 import { useRouter } from "next/router";
 import { useEffect, useRef } from "react";
-import { watchFrom } from "./watch.js";
+import { startFrom, 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;
@@ -36,29 +36,6 @@ function refresh(router) {
         .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
@@ -129,14 +106,12 @@ export function MapledLive({ endpoint, interval, onPublish }) {
             }
         },
     }, 
-    // 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]);
+    // the first answer names what is live, not what the page read: one
+    // that went live after the page was asked for — a publish between
+    // getServerSideProps and the first check, or while a tab opened in
+    // the background waited to be shown — counts as a publish, with no
+    // `previous`: which release the page read, the tab can't tell
+    // (watch.ts, «where the page is»)
+    startFrom(followed)), [endpoint, interval]);
     return null;
 }

package/dist/live.js

@@ -8,27 +8,40 @@
     It asks the release route (`createReleaseHandler` from
     "@mapled/next/server", mounted at /api/mapled/release — under the
     site's basePath, when next.config sets one) every few seconds and, when a publish lands, refreshes the page's server
-    components in place — scroll position and client state stay. */
+    components in place — scroll position and client state stay. Its
+    first answer counts too, when the release it names went live for the
+    pages after this page was asked for: a publish between the render and
+    the first check, or while a tab opened in the background waited to be
+    shown. */
 import { useRouter } from "next/navigation";
 import { useEffect, useRef } from "react";
-import { watchRelease } from "./watch.js";
+import { startFrom, watchFrom } from "./watch.js";
 export function MapledLive({ endpoint, interval, onPublish }) {
     const router = useRouter();
     const custom = useRef(onPublish);
+    /** 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);
     useEffect(() => {
         custom.current = onPublish;
     }, [onPublish]);
-    useEffect(() => watchRelease({
+    useEffect(() => watchFrom({
         endpoint,
         interval,
         onPublish: (next, previous) => {
+            followed.current = next.release;
             refreshPastBrowserCache();
             if (custom.current)
                 custom.current(next, previous);
             else
                 router.refresh();
         },
-    }), [endpoint, interval, router]);
+    }, 
+    // the first answer names what is live, not what the page read: one
+    // the site's cache acknowledged after the page was asked for counts
+    // as a publish, with no `previous` — which release the page read,
+    // the tab can't tell (watch.ts, «where the page is»)
+    startFrom(followed)), [endpoint, interval, router]);
     return null;
 }
 /** The layers this module has put over `fetch`. */

package/dist/server.d.ts

@@ -49,7 +49,10 @@ type ReleaseOptions = {
     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. */
+    again. A deployment the webhook doesn't reach names none. The answer
+    says when Mapled recorded the acknowledgement (`acknowledgedAt`): a
+    page asked for after that renders the release, so a tab whose page is
+    older knows to refresh on its first check. */
 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

@@ -29,8 +29,15 @@ export async function verifySignature(secret, body, signature) {
 }
 const DRAFT_COOKIE = "mapled_draft";
 /** Same-app relative path only — preview links can't bounce elsewhere. */
+/** The app's rule for a same-site path (`SAME_APP_PATH` of `@mapled/shared`,
+    ported literally — this package has no runtime dependencies): one
+    leading slash and not a second, no backslash, no control character or
+    space. A browser reads `/\host` and `/<tab>/host` as another host, so
+    anything else answers `/` — the exit route takes no token and would be
+    an open redirect at the customer's site otherwise. */
+const SAME_SITE_PATH = /^\/(?![\/\\])[^\\\x00-\x20\x7f]*$/;
 function safeNext(raw) {
-    return raw && /^\/(?!\/)/.test(raw) ? raw : "/";
+    return raw && SAME_SITE_PATH.test(raw) ? raw : "/";
 }
 /** GET handler for the preview route (mount at /api/mapled/preview).
     Trades the one-time link token from Mapled for a draft session,
@@ -151,10 +158,10 @@ function asPointer(body) {
 }
 /** The pointer's `webhook` as Mapled writes it; anything else throws. */
 function asAcknowledged(body) {
-    const { cache = null } = (body ?? {});
+    const { cache = null, deliveredAt } = (body ?? {});
     if (cache !== null && typeof cache !== "string")
         throw new Error("Mapled's answer wasn't a release");
-    return { ...asPointer(body), cache };
+    return { ...asPointer(body), cache, deliveredAt: typeof deliveredAt === "string" ? deliveredAt : null };
 }
 /** The pointer and, when asked with `?webhook=1`, the release the site
     has acknowledged through its publish webhook: null — the project has
@@ -170,16 +177,23 @@ async function readPointer(url, init) {
     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 };
+const UNACKNOWLEDGED = { ...NONE, cache: null, deliveredAt: null };
+/** the App Router route naming none */
+const UNKNOWN = { ...NONE, acknowledgedAt: 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. */
+    is another cache's, or names none — and when Mapled recorded the
+    acknowledgement: the cache had let go of the release before by then,
+    so a page asked for later renders it. Of an acknowledgement past
+    `live` (a copy behind Mapled) the time is that later release's — a tab
+    whose page is older than it refreshes, as it should, one asked for in
+    between refreshes once for nothing. */
 function follow(acknowledged, live, mark) {
     if (acknowledged.cache !== mark || acknowledged.release === null)
-        return NONE;
+        return UNKNOWN;
     if (acknowledged.release >= (live.release ?? 0))
-        return live;
-    return { release: acknowledged.release, publishedAt: acknowledged.publishedAt };
+        return { ...live, acknowledgedAt: acknowledged.deliveredAt };
+    return { release: acknowledged.release, publishedAt: acknowledged.publishedAt, acknowledgedAt: acknowledged.deliveredAt };
 }
 /** The release route, whichever router mounts it: one answer reused for
     `ttl` seconds, in this instance and at the CDN in front of it —
@@ -227,7 +241,7 @@ function releaseAnswers(options, next) {
         const cached = await readPointer(url, { headers, next });
         const live = cached.live;
         if (live.release === null || !cached.acknowledged)
-            return { answer: NONE };
+            return { answer: UNKNOWN };
         const mark = await cacheMark();
         let acknowledged = cached.acknowledged;
         let trouble;
@@ -306,7 +320,10 @@ function releaseAnswers(options, next) {
     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. */
+    again. A deployment the webhook doesn't reach names none. The answer
+    says when Mapled recorded the acknowledgement (`acknowledgedAt`): a
+    page asked for after that renders the release, so a tab whose page is
+    older knows to refresh on its first check. */
 export function createReleaseHandler(options) {
     const answer = releaseAnswers(options, { revalidate: options.revalidate ?? 3600, tags: ["mapled"] });
     return async function GET(req) {

package/dist/watch.d.ts

@@ -7,6 +7,13 @@ export type Release = {
     release: number;
     publishedAt: string;
 };
+/** The route's answer as the watch reads it: the release and, when the
+    route says (the App Router's does), when this site's cache
+    acknowledged it through the publish webhook — from then on the pages
+    render it. Not part of the package's API. */
+export type Answer = Release & {
+    acknowledgedAt?: string;
+};
 export type WatchOptions = {
     /** Where the release route is mounted, asked as written (default
         "/api/mapled/release" under the site's `basePath`). */
@@ -24,6 +31,35 @@ export type WatchOptions = {
     Next a browser has no `process`, and Node no such variable: "". Not
     part of the package's API. */
 export declare function nextBasePath(): string;
+/** Whether a moment `at` (as the route's answer states it) came after
+    this document was asked for. 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 `at` refreshes
+    once for nothing. Not part of the package's API. */
+export declare function wentLiveAfterPage(at: string, headers: Headers): boolean;
+/** Whether the first answer's release went live for this site's pages
+    after the page was asked for — then the page may have read the release
+    before it. The App Router's route says when this site's cache
+    acknowledged the release through the publish webhook
+    (`acknowledgedAt`): the cache let go of the old release before the
+    site answered, and Mapled recorded the answer after, so a page asked
+    for later than that renders the release, whatever the cache held
+    before — and the route names no release its cache hasn't acknowledged
+    (§18.8). A route that doesn't say — the Pages Router's, whose pages
+    read the live release as Mapled has it, or one of the site's own —
+    leaves the publish's time. Not part of the package's API. */
+export declare function newerThanPage(first: Answer, headers: Headers): boolean;
+/** The `from` of a `<MapledLive />`: the first answer counts as a publish
+    when it went live after the page was asked for; a watch restarted for
+    a new route or pace starts from the newest release the page has
+    started from or heard of (`followed`, which the component's
+    `onPublish` raises), not from the time. Not part of the package's API. */
+export declare function startFrom(followed: {
+    current: number | undefined;
+}): (first: Answer, headers: Headers) => number | null;
 /** 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
@@ -35,4 +71,4 @@ export declare function watchRelease(options: WatchOptions): () => void;
     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;
+export declare function watchFrom(options: WatchOptions, from?: (first: Answer, headers: Headers) => number | null): () => void;

package/dist/watch.js

@@ -25,12 +25,67 @@ export function nextBasePath() {
 function pointer(body) {
     if (!body || typeof body !== "object")
         return undefined;
-    const { release, publishedAt } = body;
+    const { release, publishedAt, acknowledgedAt } = body;
     if (release === null)
         return null;
     if (!Number.isInteger(release) || release < 1 || typeof publishedAt !== "string")
         return undefined;
-    return { release: release, publishedAt };
+    return typeof acknowledgedAt === "string" ? { release: release, publishedAt, acknowledgedAt } : { release: release, publishedAt };
+}
+/* ---- where the page is ----
+
+   The first answer names what is live, not what the page read. A publish
+   between the page's render and the first check — or while a tab opened
+   in the background waited to be shown before asking, for hours maybe —
+   leaves the tab on the old release until the next publish, unless that
+   first answer counts as one. Which release the page read, the tab can't
+   tell; when the release went live for the pages, it can. */
+/** 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 a moment `at` (as the route's answer states it) came after
+    this document was asked for. 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 `at` refreshes
+    once for nothing. Not part of the package's API. */
+export function wentLiveAfterPage(at, 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(at) > askedAt + offset - MARGIN_MS;
+}
+/** Whether the first answer's release went live for this site's pages
+    after the page was asked for — then the page may have read the release
+    before it. The App Router's route says when this site's cache
+    acknowledged the release through the publish webhook
+    (`acknowledgedAt`): the cache let go of the old release before the
+    site answered, and Mapled recorded the answer after, so a page asked
+    for later than that renders the release, whatever the cache held
+    before — and the route names no release its cache hasn't acknowledged
+    (§18.8). A route that doesn't say — the Pages Router's, whose pages
+    read the live release as Mapled has it, or one of the site's own —
+    leaves the publish's time. Not part of the package's API. */
+export function newerThanPage(first, headers) {
+    return wentLiveAfterPage(first.acknowledgedAt ?? first.publishedAt, headers);
+}
+/** The `from` of a `<MapledLive />`: the first answer counts as a publish
+    when it went live after the page was asked for; a watch restarted for
+    a new route or pace starts from the newest release the page has
+    started from or heard of (`followed`, which the component's
+    `onPublish` raises), not from the time. Not part of the package's API. */
+export function startFrom(followed) {
+    return (first, headers) => {
+        const from = followed.current ?? (newerThanPage(first, headers) ? null : first.release);
+        followed.current = Math.max(first.release, followed.current ?? 0);
+        return from;
+    };
 }
 /** Starts watching; returns the function that stops it. The first answer
     is where the watch starts from; `onPublish` runs once per release that
@@ -83,7 +138,7 @@ export function watchFrom(options, from) {
                 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 };
+                    news = { next: { release: now.release, publishedAt: now.publishedAt }, previous: seen };
                     seen = now.release;
                 }
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapled/next",
-  "version": "0.11.1",
+  "version": "0.11.3",
   "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",