@decocms/nextjs 8.5.2 → 8.7.0

package/README.md

@@ -6,8 +6,8 @@ Peers: `@decocms/blocks` (same version), `next` 16, `react` 19; optionally `@ope
 
 | Import | What it is for |
 | --- | --- |
-| `@decocms/nextjs/proxy` | Draft previews in `proxy.ts`: `decideDraft`, `draftRequestHeaders`, `rewriteToDraftRoute`, `applyDraft`, `isDraftRoutePath`, or `draftProxy` for a site with no proxy of its own. No React and no block map. |
-| `@decocms/nextjs/server` | Draft previews in Server Components: `bindDraft`, `activeDraftPointer`, `contentClient`. |
+| `@decocms/nextjs/proxy` | What a request reads, decided once in `proxy.ts`: `decideDraft`, `draftRequestHeaders`, `rewriteToDraftRoute`, `applyDraft`, `isDraftRoutePath`, `decideVisitor`, `visitorRequestHeaders`, `applyVisitor`, `decideAssignments`, `assignmentsRequestHeaders`, or `draftProxy` for a site with no proxy of its own; `assignmentsKey` for a site's own cache key; `rewriteToAssignmentsRoute`, `isAssignmentsRoutePath`, `assignmentsRoutePath` and `assignmentsSegment` for Next's own cache. No React and no block map. |
+| `@decocms/nextjs/server` | What the proxy decided, in Server Components: `bindDraft`, `activeDraftPointer`, `contentClient`; `assignedClient` for a page on the assignments route. |
 | `@decocms/nextjs` | `DraftPreviewIndicator` (the "Preview mode" badge on a draft page), `StudioBridge` (lets Studio's site editor drive the page) and `StudioPage` (tells it which page is on screen), plus the draft names and Studio's origins (below). |
 | `@decocms/nextjs/config` | `withDeco(nextConfig)`: the draft header rules and Studio's dev origins. CommonJS, so `next.config.js` can `require()` it. |
 | `@decocms/nextjs/instrumentation` | `register`, the `instrumentation.ts` hook that records `http.server.request.duration` from Next's own request span, and `serverRequestSpanProcessor()` for a site with its own OpenTelemetry SDK. |
@@ -18,9 +18,9 @@ Peers: `@decocms/blocks` (same version), `next` 16, `react` 19; optionally `@ope
 ## Drafts
 
 ```ts
-// src/cms.config.ts: the options both CMS handles share, and where drafts preview
-export const cmsConfig = { content };
-export const preview = { site: "my-store" };
+// src/cms.config.ts: the options both CMS handles share (with `site`, hosted releases and
+// the preview hosts Studio writes into them)
+export const cmsConfig = { content, site: "my-store" };
 
 // src/cms.ts and src/cms.proxy.ts
 export const cms = createCMS({ blocks, ...cmsConfig });
@@ -29,28 +29,95 @@ export const proxyCms = createCMS({ blocks: {}, ...cmsConfig }); // no block map
 // src/proxy.ts
 export async function proxy(request: NextRequest) {
   if (isDraftRoutePath(request.nextUrl.pathname)) return new NextResponse(null, { status: 404 });
-  const draft = await decideDraft(proxyCms, request, preview);
+  const draft = await decideDraft(proxyCms, request);
+  const visitor = decideVisitor(request, draft);
+  const assignments = await decideAssignments(proxyCms, draft, visitor);
+  const headers = assignmentsRequestHeaders(
+    visitorRequestHeaders(draftRequestHeaders(request, draft), visitor),
+    assignments,
+  );
   const response =
-    rewriteToDraftRoute(request, draft) ??
-    NextResponse.next({ request: { headers: draftRequestHeaders(request, draft) } });
-  return applyDraft(response, draft);
+    rewriteToDraftRoute(request, draft, visitor, assignments) ??
+    NextResponse.next({ request: { headers } });
+  return applyVisitor(applyDraft(response, draft), visitor);
 }
 
 // src/app/%5Fdraft/[[...path]]/page.tsx: the dynamic draft route (a literal `_draft` folder never routes)
 export const dynamic = "force-dynamic";
 export default async function DraftPage({ params, searchParams }) {
-  await bindDraft(cms, { searchParams: await searchParams, ...preview });
+  await bindDraft(cms, { searchParams: await searchParams });
   const client = contentClient(cms);
   // … resolve and render the page as on the published route …
   return <>{page}<DraftPreviewIndicator /></>;
 }
 ```
 
-Published pages stay static: the proxy sends only drafted requests to the draft route, sets the draft cookie, forwards the accepted pointer on `x-deco-draft` (removing any copy sent from outside), and marks the response `Cache-Control: no-store, private` and `X-Robots-Tag: noindex, nofollow`. A root layout that reads content calls `bindDraft(cms, preview)` too: it reads the forwarded header.
+Published pages stay cached (ISR, below): the proxy sends only preview requests to the draft route (any `?__draft=`, `off` included, or the draft cookie; never the assignments route), sets the draft cookie, forwards the accepted version on `x-deco-version` (removing any copy sent from outside), and marks the response exactly `Cache-Control: max-age=0, no-cache, must-revalidate`, `Vary: Cookie` and `X-Robots-Tag: noindex, nofollow`. A draft request checks for the latest release once (`cms.checkRelease()`) and forwards the check's id on `x-deco-release-check` (removing any copy sent from outside): the proxy's host check and read of the draft, `bindDraft`'s host check and the page's `contentClient` all wait for that one check, so one preview request fetches `latest.json` once (a page in another process than the proxy makes one check of its own). It reads a link's draft before forwarding it: a draft that can't be read anymore renders the release, expires the cookie and tells the pages on `x-deco-draft-unavailable`, so `DraftPreviewIndicator` shows a calm notice instead of an error page. A layout that reads content goes with its route, so the cached pages read no request: under the draft route (`app/%5Fdraft/layout.tsx`) it calls `bindDraft(cms)` and `contentClient(cms)`, which read the forwarded headers; under the assignments route (`app/%5Fassignments/[assignments]/layout.tsx`) it reads through `await assignedClient(cms, (await params).assignments)`. `bindDraft` reads `headers()`, and a cached page that reads a request header renders on every request instead, so never call it in the root layout or on the assignments route.
+
+A draft link can carry a published release's commit SHA instead of a draft (Studio's "Preview this version"), and either one can carry a preview time (`__at`) and tests and campaigns switched on or off (`__test`, `__campaign`), which `cms.readVersion` reads as the client's `date`, `experiments` and `campaigns`. All of it passes the same host check and renders on the draft route: a visitor on the live site never picks a version. A preview may switch on a test at 0%.
+
+### The visitor, the assignments and the client
+
+The proxy decides once per request. `decideVisitor(request, draft)` reads the visitor with `readVisitor` from `@decocms/blocks/experiments` (the `deco_segment` cookie, or a new visitor); `applyVisitor` sends its cookie on a first visit only, never from a preview. `decideAssignments(proxyCms, draft, visitor)` then decides each test and campaign on or off: `cms.client({ visitor, version, date, experiments, campaigns })` with the visitor and the Studio link's version, moment and switched tests and campaigns, resolving the saved `experiments` and `campaigns` blocks. `visitorRequestHeaders` and `assignmentsRequestHeaders` forward them on `x-deco-visitor` and `x-deco-assignments` (`draftRequestHeaders` always removes copies sent from outside).
+
+On the page, `bindDraft` binds the version and what the proxy forwarded (on the current release it binds the visitor and the assignments only when the release saves an `experiments` or `campaigns` block, and a test at 0% stays off whatever the header says), and `contentClient(cms)` builds `cms.client({ version, experiments, campaigns })` from them: the page decides nothing again. The pages trust those headers: behind the proxy they hold what it decided, and a request that reaches a page without it (a `matcher` that leaves the route out, or a site without the proxy) is read the same way, with whatever `x-deco-version` and `x-deco-assignments` it arrives with. Which routes go through the proxy, and how the others are protected, is the site's call. A cached page reads no request: the CMS's pages render on [the assignments route](#the-assignments-route), with the tests and campaigns the proxy decided in the path.
+
+The binding caches nothing. A site that caches pages in front of Next (a CDN keyed on a request header) keys on the request's assignments, never on the visitor: `assignmentsKey(assignments)` from `@decocms/nextjs/proxy`, with what `decideAssignments` gave, is the version, the tests on and the campaigns running (`""` when there are none). Visitors on the same side of every test share one entry, and a campaign starting or ending changes the key. To let Next's own cache do it, see [the assignments route](#the-assignments-route).
+
+### The assignments route
+
+The proxy decides, the page renders that. Next caches a page by its path (ISR), so the proxy puts its decision in the path: it rewrites each CMS page to `/_assignments/<assignments>/<path>`, and the page renders exactly the tests and campaigns that segment names. Next then keeps one entry per path and set of assignments and serves it to every visitor with the same ones; the page reads no request, so Next can cache it. CMS pages are ISR with `revalidate = 600` (10 minutes): Next serves a stored page for 10 minutes; the first request after that still gets the stored copy while Next renders the page again in the background for the requests after it. So a published change shows within about 10 minutes on a page people open, and a page nobody opened for longer shows its old copy once more. That delay (for example, a banner switching on late) is accepted. Never `force-static` on Next.js: a page that never expires would keep what it rendered first.
+
+```ts
+// src/proxy.ts
+import { isAssignmentsRoutePath, isDraftRoutePath, rewriteToAssignmentsRoute /* … */ } from "@decocms/nextjs/proxy";
+
+export async function proxy(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+  if (isDraftRoutePath(pathname) || isAssignmentsRoutePath(pathname)) return new NextResponse(null, { status: 404 });
+  const draft = await decideDraft(proxyCms, request, preview);
+  const visitor = decideVisitor(request, draft);
+  const assigned = isCmsPage(pathname) ? await rewriteToAssignmentsRoute(proxyCms, request, draft, visitor) : null;
+  if (assigned) return applyVisitor(applyDraft(assigned, draft), visitor);
+  const assignments = await decideAssignments(proxyCms, draft, visitor);
+  const headers = assignmentsRequestHeaders(visitorRequestHeaders(draftRequestHeaders(request, draft), visitor), assignments);
+  const response = rewriteToDraftRoute(request, draft, visitor, assignments) ?? NextResponse.next({ request: { headers } });
+  return applyVisitor(applyDraft(response, draft), visitor);
+}
+
+// Next's own files never go through the proxy: rewritten, every script and style would be a 404.
+export const config = { matcher: ["/((?!_next/|favicon.ico).*)"] };
+```
+
+```tsx
+// src/app/%5Fassignments/[assignments]/[[...path]]/page.tsx: every CMS page (a literal `_assignments` folder never routes)
+import { assignedClient } from "@decocms/nextjs/server";
+
+export const revalidate = 600; // 10 minutes; never force-static
+export async function generateStaticParams() {
+  return []; // no path at build time: each renders on its first request, then is cached
+}
+export default async function Page({ params }) {
+  const { assignments, path } = await params;
+  const client = await assignedClient(cms, assignments);
+  if (!client) notFound();
+  // … match the path and resolve the page through `client`, as on any page …
+}
+```
+
+- **What the segment holds**: every test of the saved `experiments` block on or off for the visitor and every campaign of the saved `campaigns` block running or not now (`readAssignments` on the current release), as `assignmentsSegment` writes it: `-` for none, otherwise base64url, one spelling per set of assignments. Visitors on the same side of every test get the same path; the visitor's id is never in it, and the rewritten request carries neither the visitor nor a draft header. A campaign starting or ending moves every visitor to a new path.
+- **The page renders what the path names**: `await assignedClient(cms, segment)` builds `cms.client({ experiments, campaigns })` with every test and campaign as the segment names it and no visitor, a client fully decided in advance, so every visitor on that side renders the same page. The page never checks a campaign's dates or rolls a test itself. A test now at 0% stays off whatever the segment names. A page Next renders again later (revalidation) shows the same tests and campaigns under the same path.
+- **The route trusts the path its proxy writes**: the proxy answers a direct hit on `/_assignments/…` with a 404, as it does for `/_draft/…`, so behind the proxy only its own rewrite reaches the route. A request that reaches the page some other way (a proxy `matcher` that leaves the route out, or a site without the proxy) renders the tests and campaigns its path names: `assignedClient` only keeps off a test at 0% and a test or a campaign the content doesn't have, and returns `null` (a 404) for a segment the proxy never writes. Which routes go through the proxy, and how the others are protected, is the site's call. Leaving off rather than answering 404 matters because Next caches a 404 under the path too: a path the proxy wrote before the page's server saw newly published content still renders.
+- **The URL asked for stays private**: when the content saves tests or campaigns, the rewrite marks the response `Cache-Control: private, no-cache`. Next keeps one cached page per path and set of assignments, but `/shoes` itself answers by the visitor's cookie and the moment, so a CDN in front must not keep Next's ISR `s-maxage` under it.
+- **A cached page reads no request**: `headers()`, `cookies()` or `searchParams` anywhere in the route (its layouts included, so no `bindDraft` there) make Next render it on every request instead of caching it, and a client component calling `useSearchParams()` renders on the client up to its nearest `<Suspense>`. `force-static` used to hide both by handing the page empty values; with ISR the page takes what it needs from the path, as the assignments do.
+- **Drafts and previews are never rewritten here**: a drafted request goes to the dynamic draft route, so nothing from a preview lands in Next's cache.
+- **Which paths**: only the CMS's pages (`isCmsPage` above is the site's own: routes of the app's own, such as `/blog` here, render as before). `draftProxy(proxyCms, { assignments: (request) => isCmsPage(request.nextUrl.pathname) })` does the same for a site with no proxy of its own.
+
+`examples/nextjs-binding-smoke` in the repository runs it: two visitors on opposite sides of a test get different paths, two on the same side get one cached entry (`x-nextjs-cache: HIT`), the route is ISR at 600 seconds, and a typed `/_assignments/…` path is a 404.
 
 ### Draft hosts
 
-v7's allowlist. A draft link (`?__draft=`) previews on the preview hosts the site declares (the `CMS` block's `preview.hosts`, or `createCMS`'s; a site that declares none has none, as in v7) and always on the hosts Deco runs the site on, `<site>.deco.site` and `<site>.deco-cx.workers.dev`. `previewHosts: [...]` replaces the declared list (v7's `DECO_ALLOWED_PREVIEW_HOSTS`, such as `["localhost:3000"]` in development); `previewHosts: "none"` turns previews off on every host. Hosts compare exactly, port included, on the host the visitor asked for (`x-forwarded-host`, else `host`). Pass the same options to `decideDraft` and `bindDraft`. On a host that may not preview, the page renders the release; `?__draft=off` still ends a preview anywhere.
+A draft link (`?__draft=`) previews on the hosts the CMS allows, which `cms.readVersion` checks: the addresses Studio writes into the current release's metadata (`previewHosts` in `latest.json`, read with `createCMS`'s `site`), plus `createCMS({ preview: { hosts } })`. The site lists nothing else. With no list, every host previews: a site with no `latest.json` on the CDN yet, or one published before Studio wrote `previewHosts` (its next publish writes the list), and content with no `site` unless `preview.hosts` lists hosts (such as `["localhost"]`). If `latest.json` can't be read (a network error, a 5xx, a malformed file), previews stay closed, besides `preview.hosts`, until a read succeeds. The host is the one the visitor asked for (`x-forwarded-host`, else `host`); the proxy and `bindDraft` ask the same CMS. On a host that may not preview, the page renders the release; `?__draft=off` still ends a preview anywhere.
 
 ## The layout
 
@@ -79,7 +146,7 @@ It renders a `<meta>` that React places in the `<head>`, so the page's own marku
 
 ## Names and Studio's origins
 
-For a site that needs them in its own code (a route that sets its own headers, a CSP it writes itself), `@decocms/nextjs` exports what the proxy, the pages and `withDeco` use: `DRAFT_PARAM` (`__draft`), `DRAFT_COOKIE` (`__deco_draft`), `DRAFT_HEADER` (`x-deco-draft`), `draftResponseHeaders(pointer)`, `STUDIO_ORIGINS`, `STUDIO_FRAME_ANCESTORS` and `isStudioOrigin(origin)`. They have the same values as `@decocms/tanstack`'s; each binding keeps its own copy and never imports the other.
+For a site that needs them in its own code (a route that sets its own headers, a CSP it writes itself), `@decocms/nextjs` exports what the proxy, the pages and `withDeco` use: `DRAFT_PARAM` (`__draft`), `DRAFT_COOKIE` (`__deco_draft`), `VERSION_HEADER` (`x-deco-version`), `VISITOR_HEADER` (`x-deco-visitor`), `ASSIGNMENTS_HEADER` (`x-deco-assignments`), `draftResponseHeaders(version)`, `STUDIO_ORIGINS`, `STUDIO_FRAME_ANCESTORS` and `isStudioOrigin(origin)`. They have the same values as `@decocms/tanstack`'s; each binding keeps its own copy and never imports the other.
 
 ## next.config
 
@@ -88,7 +155,7 @@ const { withDeco } = require("@decocms/nextjs/config");
 module.exports = withDeco({ images: { loader: "custom", loaderFile: "./src/image-loader.ts" } });
 ```
 
-`withDeco` puts v7's two draft header rules before your own (a `?__draft=` query, or the draft cookie: no-store, `Vary: Cookie`, noindex) and adds Studio's origins to `allowedDevOrigins`. Each can be turned off: `withDeco(config, { draftHeaders: false, studioOrigins: false })`. Next sets `Cache-Control` and `Vary` itself on dynamic pages, so only `X-Robots-Tag` is sure to arrive from these rules; the proxy's `applyDraft` sets all three on the responses it makes.
+`withDeco` puts v7's two draft header rules before your own (a `?__draft=` query, or the draft cookie: `max-age=0, no-cache, must-revalidate`, `Vary: Cookie`, noindex) and adds Studio's origins to `allowedDevOrigins`. Each can be turned off: `withDeco(config, { draftHeaders: false, studioOrigins: false })`. Next sets `Cache-Control` and `Vary` itself on dynamic pages, so only `X-Robots-Tag` is sure to arrive from these rules; the proxy's `applyDraft` sets all three on the responses it makes.
 
 ## Request metric
 
@@ -104,7 +171,7 @@ Next.js already measures every request it serves: one root span per request (`Ba
 | `http.route` | Next's route template: `/[[...path]]`, `/blog`, `/_draft/[[...path]]`. An RSC request counts under its page's route. `unmatched` when Next names none (an Edge route under `next start`) |
 | `http.request.method` | `GET`, `POST`, …; any other is `_OTHER` |
 | `status_class` | `2xx` … `5xx`; a request that threw is `5xx` |
-| `cache` | `DRAFT` for a draft render (the proxy forwarded `x-deco-draft`, or the request was rewritten onto `/_draft`), otherwise `BYPASS`: Next decides its own cache (`x-nextjs-cache`) on the response, which the span never sees |
+| `cache` | `DRAFT` for a draft render (the proxy forwarded `x-deco-version`, or the request was rewritten onto `/_draft`), otherwise `BYPASS`: Next decides its own cache (`x-nextjs-cache`) on the response, which the span never sees |
 
 - `@opentelemetry/api` is an optional peer: `register` uses the same copy Next does (yours when installed, else Next's compiled one) and does nothing if neither loads.
 - **Your own OpenTelemetry setup** (`@vercel/otel`, `NodeSDK`): only one tracer provider can be registered, so `register` leaves yours alone and logs how to combine them. Add the processor to yours instead: `registerOTel({ serviceName, spanProcessors: ["auto", serverRequestSpanProcessor()] })`.

package/dist/DraftPreviewIndicator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DraftPreviewIndicator.d.ts","sourceRoot":"","sources":["../src/DraftPreviewIndicator.tsx"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,MAAM,WAAW,0BAA0B;IACzC,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,qBAAqB,CAAC,EAAE,QAAQ,EAAE,GAAE,0BAA+B,GAAG,SAAS,CAI9F"}
+{"version":3,"file":"DraftPreviewIndicator.d.ts","sourceRoot":"","sources":["../src/DraftPreviewIndicator.tsx"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,MAAM,WAAW,0BAA0B;IACzC,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,qBAAqB,CAAC,EAAE,QAAQ,EAAE,GAAE,0BAA+B,GAAG,SAAS,CAI9F"}

package/dist/DraftPreviewIndicator.js

@@ -2,18 +2,19 @@ import { jsx as _jsx } from "react/jsx-runtime";
 /**
  * The "Preview mode" badge for the request's draft: a Server Component that
  * renders `DraftBadge` (`@decocms/blocks/preview`) only when `bindDraft`
- * bound a draft, so a published page emits nothing.
+ * bound a draft, so a published page emits nothing; when the link named a
+ * draft that can't be read anymore, the badge's calm notice instead.
  *
  * Render it inside the page, after `bindDraft` was awaited, never from a
  * layout: a layout renders alongside the page that fills it, so it may run
  * before the page bound its draft.
  */
 import { DraftBadge } from "@decocms/blocks/preview";
-import { activeDraftPointer } from "./server/slot.js";
+import { activeDraftPointer, draftUnavailable } from "./server/slot.js";
 export function DraftPreviewIndicator({ exitHref } = {}) {
     const pointer = activeDraftPointer();
     if (!pointer)
-        return null;
+        return draftUnavailable() ? _jsx(DraftBadge, { pointer: null, unavailable: true }) : null;
     return _jsx(DraftBadge, { pointer: pointer, exitHref: exitHref });
 }
 //# sourceMappingURL=DraftPreviewIndicator.js.map

package/dist/DraftPreviewIndicator.js.map

@@ -1 +1 @@
-{"version":3,"file":"DraftPreviewIndicator.js","sourceRoot":"","sources":["../src/DraftPreviewIndicator.tsx"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAOtD,MAAM,UAAU,qBAAqB,CAAC,EAAE,QAAQ,EAAE,GAA+B,EAAE;IACjF,MAAM,OAAO,GAAG,kBAAkB,EAAE,CAAC;IACrC,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,OAAO,KAAC,UAAU,IAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAI,CAAC;AAC9D,CAAC"}
+{"version":3,"file":"DraftPreviewIndicator.js","sourceRoot":"","sources":["../src/DraftPreviewIndicator.tsx"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAOxE,MAAM,UAAU,qBAAqB,CAAC,EAAE,QAAQ,EAAE,GAA+B,EAAE;IACjF,MAAM,OAAO,GAAG,kBAAkB,EAAE,CAAC;IACrC,IAAI,CAAC,OAAO;QAAE,OAAO,gBAAgB,EAAE,CAAC,CAAC,CAAC,KAAC,UAAU,IAAC,OAAO,EAAE,IAAI,EAAE,WAAW,SAAG,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3F,OAAO,KAAC,UAAU,IAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAI,CAAC;AAC9D,CAAC"}

package/dist/assignments.d.ts

@@ -0,0 +1,95 @@
+/**
+ * A request's assignments: what its content gives it, decided once, in the
+ * proxy, and handed to the page. The version it reads (a Studio link's draft
+ * or release SHA, `null` for the current release), each test of the saved
+ * `experiments` block on or off for its visitor, and each campaign of the
+ * saved `campaigns` block running or not at its date, with a preview's
+ * switched tests and campaigns on top. The page builds
+ * `cms.client({ version, experiments, campaigns })` from them, a client that
+ * decides nothing again.
+ *
+ * Two requests with the same assignments render the same content, so they
+ * share a cache entry: `assignmentsKey` for a cache keyed on a string,
+ * `assignmentsSegment` for Next's own path-keyed cache. The visitor id itself
+ * is never in either, or every visitor would miss. The binding caches nothing
+ * itself.
+ *
+ * The same reading as `@decocms/tanstack/worker`'s.
+ */
+import type { ClientOptions, CMS } from "@decocms/blocks";
+import type { Assignments } from "@decocms/blocks/experiments";
+export interface RequestAssignments {
+    /** The version read, `null` for the current release. */
+    version: string | null;
+    /** Each test of the saved `experiments` block: on or off. */
+    experiments: Readonly<Assignments>;
+    /** Each campaign of the saved `campaigns` block: running or not. */
+    campaigns: Readonly<Assignments>;
+}
+/**
+ * The request header the proxy hands the pages the assignments it decided on
+ * (`assignmentsSegment`), for `bindDraft` and `contentClient`. The proxy
+ * removes any copy that arrives from outside.
+ */
+export declare const ASSIGNMENTS_HEADER = "x-deco-assignments";
+/** What a page's path and the decisions header carry: the tests and campaigns, never the version or the visitor. */
+export type PathAssignments = Pick<RequestAssignments, "experiments" | "campaigns">;
+/**
+ * The assignments of one request: `cms.client(options)` (the version, the
+ * visitor, the date and a preview's switched tests and campaigns, as
+ * `cms.readVersion` reads them) resolving `experiments` and `campaigns`.
+ * Missing blocks (or content that doesn't load) give none, never an error.
+ */
+export declare function readAssignments(cms: Pick<CMS, "client">, options: ClientOptions): Promise<RequestAssignments>;
+/**
+ * `readAssignments`, and whether its page can differ by them: `true` when the
+ * content saves tests or campaigns (or couldn't be read, to stay safe), so a
+ * response keyed on them must never be shared by its URL alone.
+ */
+export declare function readAssignmentsAndScope(cms: Pick<CMS, "client">, options: ClientOptions): Promise<{
+    assignments: RequestAssignments;
+    varies: boolean;
+}>;
+/**
+ * The assignments as one stable string for a cache key:
+ * `v=<version>|x=<tests on>|c=<campaigns running>`, names sorted and
+ * URL-encoded, empty parts left out; `""` for none. The names that are off
+ * aren't in it: within one content revision they are the rest.
+ */
+export declare function assignmentsKey(assignments: RequestAssignments): string;
+/**
+ * The route a page renders on under the assignments its proxy made:
+ * `/_assignments/<assignments>/<path>`, mounted as `app/%5Fassignments/[assignments]/[[...path]]`
+ * (a literal `_assignments` folder is private in Next and never routes). The proxy
+ * rewrites to it (`rewriteToAssignmentsRoute`) and answers a direct hit with
+ * its 404, so a visitor can't pick the assignments by typing a path.
+ */
+export declare const ASSIGNMENTS_ROUTE_PREFIX = "/_assignments";
+/**
+ * The tests and campaigns as one path segment, every name with its state
+ * (`x=+on,-off|c=+running,-not`, base64url-encoded so Next passes it to the
+ * page unchanged), for Next's own path-keyed cache (ISR, the full route
+ * cache) and for the decisions header (`ASSIGNMENTS_HEADER`): `-` for none.
+ * The same assignments always give the same segment; the visitor is never in
+ * it.
+ */
+export declare function assignmentsSegment(assignments: PathAssignments): string;
+/**
+ * The tests and campaigns a segment carries, or `null` when it isn't one
+ * `assignmentsSegment` writes (malformed, or the same assignments spelled
+ * another way), so each set of assignments has exactly one path.
+ */
+export declare function parseAssignmentsSegment(segment: string): PathAssignments | null;
+/** `/_assignments/<segment><pathname>` (the bare prefix and segment for `/`). */
+export declare function assignmentsRoutePath(pathname: string, assignments: PathAssignments): string;
+/** Whether `pathname` is on the assignments route: a site's proxy answers a direct hit there with its 404. */
+export declare function isAssignmentsRoutePath(pathname: string): boolean;
+/**
+ * The tests a path or header names, as a page renders them on the current
+ * release: a test at 0% stays off whatever it says, so a forged path or
+ * header can't switch on a test nobody is in (a preview, on its own version,
+ * may). A name the content doesn't have stays out anyway (`cms.client`
+ * keeps only the block's names). Read from memory, unresolved.
+ */
+export declare function withoutDarkTests(cms: Pick<CMS, "forRelease">, assignments: PathAssignments): Promise<PathAssignments>;
+//# sourceMappingURL=assignments.d.ts.map

package/dist/assignments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assignments.d.ts","sourceRoot":"","sources":["../src/assignments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE/D,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,6DAA6D;IAC7D,WAAW,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IACnC,oEAAoE;IACpE,SAAS,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;CAClC;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAEvD,oHAAoH;AACpH,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,kBAAkB,EAAE,aAAa,GAAG,WAAW,CAAC,CAAC;AA4CpF;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,EACxB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,kBAAkB,CAAC,CAE7B;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,EACxB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC;IAAE,WAAW,EAAE,kBAAkB,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC,CAqB/D;AASD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,kBAAkB,GAAG,MAAM,CAStE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,kBAAkB,CAAC;AA8BxD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,eAAe,GAAG,MAAM,CAOvE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAwB/E;AAED,iFAAiF;AACjF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,eAAe,GAAG,MAAM,CAG3F;AAED,8GAA8G;AAC9G,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAIhE;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,EAC5B,WAAW,EAAE,eAAe,GAC3B,OAAO,CAAC,eAAe,CAAC,CAmB1B"}

package/dist/assignments.js

@@ -0,0 +1,229 @@
+/**
+ * The request header the proxy hands the pages the assignments it decided on
+ * (`assignmentsSegment`), for `bindDraft` and `contentClient`. The proxy
+ * removes any copy that arrives from outside.
+ */
+export const ASSIGNMENTS_HEADER = "x-deco-assignments";
+const EXPERIMENTS = { block: "experiments", type: "split-traffic" };
+const CAMPAIGNS = { block: "campaigns", type: "calendar" };
+/** Plain code-unit order, the same on every server and locale. */
+const byCodeUnit = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function record() {
+    return Object.create(null);
+}
+/**
+ * Whether the content saves a block of `type`: listing never fails on a
+ * missing block, so a site without tests or campaigns reports no error.
+ */
+async function saves(client, type) {
+    const [list] = await client.list(type);
+    return (list?.length ?? 0) > 0;
+}
+/** The saved `block` resolved, each name `true` or `false`; `null` when the content saves none. */
+async function decided(client, spec) {
+    try {
+        if (!(await saves(client, spec.type)))
+            return null;
+        const [value] = await client.resolve(spec.block);
+        const out = record();
+        if (!isRecord(value))
+            return out;
+        for (const name of Object.keys(value).sort(byCodeUnit))
+            out[name] = value[name] === true;
+        return out;
+    }
+    catch {
+        return record();
+    }
+}
+/**
+ * The assignments of one request: `cms.client(options)` (the version, the
+ * visitor, the date and a preview's switched tests and campaigns, as
+ * `cms.readVersion` reads them) resolving `experiments` and `campaigns`.
+ * Missing blocks (or content that doesn't load) give none, never an error.
+ */
+export async function readAssignments(cms, options) {
+    return (await readAssignmentsAndScope(cms, options)).assignments;
+}
+/**
+ * `readAssignments`, and whether its page can differ by them: `true` when the
+ * content saves tests or campaigns (or couldn't be read, to stay safe), so a
+ * response keyed on them must never be shared by its URL alone.
+ */
+export async function readAssignmentsAndScope(cms, options) {
+    const version = typeof options.version === "string" ? options.version : null;
+    const none = { version, experiments: record(), campaigns: record() };
+    let client;
+    try {
+        client = cms.client(options);
+    }
+    catch {
+        return { assignments: none, varies: true };
+    }
+    const [experiments, campaigns] = await Promise.all([
+        decided(client, EXPERIMENTS),
+        decided(client, CAMPAIGNS),
+    ]);
+    return {
+        assignments: {
+            version,
+            experiments: experiments ?? none.experiments,
+            campaigns: campaigns ?? none.campaigns,
+        },
+        varies: experiments !== null || campaigns !== null,
+    };
+}
+/** The names that are on, sorted. */
+function onNames(assignments) {
+    return Object.keys(assignments)
+        .filter((name) => assignments[name] === true)
+        .sort(byCodeUnit);
+}
+/**
+ * The assignments as one stable string for a cache key:
+ * `v=<version>|x=<tests on>|c=<campaigns running>`, names sorted and
+ * URL-encoded, empty parts left out; `""` for none. The names that are off
+ * aren't in it: within one content revision they are the rest.
+ */
+export function assignmentsKey(assignments) {
+    const list = (names) => names.map(encodeURIComponent).join(",");
+    const parts = [];
+    if (assignments.version)
+        parts.push(`v=${encodeURIComponent(assignments.version)}`);
+    const tests = onNames(assignments.experiments);
+    const campaigns = onNames(assignments.campaigns);
+    if (tests.length)
+        parts.push(`x=${list(tests)}`);
+    if (campaigns.length)
+        parts.push(`c=${list(campaigns)}`);
+    return parts.join("|");
+}
+/**
+ * The route a page renders on under the assignments its proxy made:
+ * `/_assignments/<assignments>/<path>`, mounted as `app/%5Fassignments/[assignments]/[[...path]]`
+ * (a literal `_assignments` folder is private in Next and never routes). The proxy
+ * rewrites to it (`rewriteToAssignmentsRoute`) and answers a direct hit with
+ * its 404, so a visitor can't pick the assignments by typing a path.
+ */
+export const ASSIGNMENTS_ROUTE_PREFIX = "/_assignments";
+/** The segment for content with no test and no campaign. */
+const NONE = "-";
+function toBase64Url(text) {
+    let binary = "";
+    for (const byte of new TextEncoder().encode(text))
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64Url(segment) {
+    if (!/^[A-Za-z0-9_-]+$/.test(segment))
+        return null;
+    try {
+        const binary = atob(segment.replace(/-/g, "+").replace(/_/g, "/"));
+        const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        return null;
+    }
+}
+/** `+name` on, `-name` off, names URL-encoded and sorted. */
+function encodeStates(states) {
+    return Object.keys(states)
+        .sort(byCodeUnit)
+        .map((name) => `${states[name] === true ? "+" : "-"}${encodeURIComponent(name)}`)
+        .join(",");
+}
+/**
+ * The tests and campaigns as one path segment, every name with its state
+ * (`x=+on,-off|c=+running,-not`, base64url-encoded so Next passes it to the
+ * page unchanged), for Next's own path-keyed cache (ISR, the full route
+ * cache) and for the decisions header (`ASSIGNMENTS_HEADER`): `-` for none.
+ * The same assignments always give the same segment; the visitor is never in
+ * it.
+ */
+export function assignmentsSegment(assignments) {
+    const parts = [];
+    const tests = encodeStates(assignments.experiments);
+    const campaigns = encodeStates(assignments.campaigns);
+    if (tests)
+        parts.push(`x=${tests}`);
+    if (campaigns)
+        parts.push(`c=${campaigns}`);
+    return parts.length === 0 ? NONE : toBase64Url(parts.join("|"));
+}
+/**
+ * The tests and campaigns a segment carries, or `null` when it isn't one
+ * `assignmentsSegment` writes (malformed, or the same assignments spelled
+ * another way), so each set of assignments has exactly one path.
+ */
+export function parseAssignmentsSegment(segment) {
+    if (segment === NONE)
+        return { experiments: record(), campaigns: record() };
+    const key = fromBase64Url(segment);
+    if (key === null)
+        return null;
+    const parsed = { experiments: record(), campaigns: record() };
+    const seen = new Set();
+    try {
+        for (const part of key.split("|")) {
+            const eq = part.indexOf("=");
+            const tag = part.slice(0, eq);
+            const list = part.slice(eq + 1);
+            if (eq <= 0 || list === "" || seen.has(tag) || (tag !== "x" && tag !== "c"))
+                return null;
+            seen.add(tag);
+            const target = tag === "x" ? parsed.experiments : parsed.campaigns;
+            for (const entry of list.split(",")) {
+                const state = entry[0];
+                if (state !== "+" && state !== "-")
+                    return null;
+                target[decodeURIComponent(entry.slice(1))] = state === "+";
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return assignmentsSegment(parsed) === segment ? parsed : null;
+}
+/** `/_assignments/<segment><pathname>` (the bare prefix and segment for `/`). */
+export function assignmentsRoutePath(pathname, assignments) {
+    const base = `${ASSIGNMENTS_ROUTE_PREFIX}/${assignmentsSegment(assignments)}`;
+    return pathname === "/" || pathname === "" ? base : `${base}${pathname}`;
+}
+/** Whether `pathname` is on the assignments route: a site's proxy answers a direct hit there with its 404. */
+export function isAssignmentsRoutePath(pathname) {
+    return (pathname === ASSIGNMENTS_ROUTE_PREFIX || pathname.startsWith(`${ASSIGNMENTS_ROUTE_PREFIX}/`));
+}
+/**
+ * The tests a path or header names, as a page renders them on the current
+ * release: a test at 0% stays off whatever it says, so a forged path or
+ * header can't switch on a test nobody is in (a preview, on its own version,
+ * may). A name the content doesn't have stays out anyway (`cms.client`
+ * keeps only the block's names). Read from memory, unresolved.
+ */
+export async function withoutDarkTests(cms, assignments) {
+    const on = Object.keys(assignments.experiments).filter((name) => assignments.experiments[name] === true);
+    if (on.length === 0)
+        return assignments;
+    let saved = {};
+    try {
+        const [block] = await cms.forRelease().resolve(EXPERIMENTS.block, { run: false });
+        if (isRecord(block) && block.__resolveType === EXPERIMENTS.type)
+            saved = block;
+    }
+    catch {
+        // No experiments block: every test the client is given stays out.
+    }
+    const experiments = record();
+    for (const name of Object.keys(assignments.experiments)) {
+        const pct = Object.hasOwn(saved, name) ? saved[name] : undefined;
+        const dark = typeof pct !== "number" || !Number.isFinite(pct) || Math.round(pct) <= 0;
+        experiments[name] = assignments.experiments[name] === true && !dark;
+    }
+    return { experiments, campaigns: assignments.campaigns };
+}
+//# sourceMappingURL=assignments.js.map

package/dist/assignments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assignments.js","sourceRoot":"","sources":["../src/assignments.ts"],"names":[],"mappings":"AA8BA;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,oBAAoB,CAAC;AAKvD,MAAM,WAAW,GAAG,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,eAAe,EAAW,CAAC;AAC7E,MAAM,SAAS,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAW,CAAC;AAIpE,kEAAkE;AAClE,MAAM,UAAU,GAAG,CAAC,CAAS,EAAE,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAElF,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,MAAM;IACb,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAgB,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,KAAK,CAAC,MAAc,EAAE,IAAY;IAC/C,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACvC,OAAO,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;AACjC,CAAC;AAED,mGAAmG;AACnG,KAAK,UAAU,OAAO,CACpB,MAAc,EACd,IAAqC;IAErC,IAAI,CAAC;QACH,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QACnD,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,MAAM,CAAC,OAAO,CAAU,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1D,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC;QACrB,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,OAAO,GAAG,CAAC;QACjC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;QACzF,OAAO,GAAG,CAAC;IACb,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,EAAE,CAAC;IAClB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,GAAwB,EACxB,OAAsB;IAEtB,OAAO,CAAC,MAAM,uBAAuB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC;AACnE,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,GAAwB,EACxB,OAAsB;IAEtB,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7E,MAAM,IAAI,GAAuB,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,CAAC;IACzF,IAAI,MAAc,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAC7C,CAAC;IACD,MAAM,CAAC,WAAW,EAAE,SAAS,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACjD,OAAO,CAAC,MAAM,EAAE,WAAW,CAAC;QAC5B,OAAO,CAAC,MAAM,EAAE,SAAS,CAAC;KAC3B,CAAC,CAAC;IACH,OAAO;QACL,WAAW,EAAE;YACX,OAAO;YACP,WAAW,EAAE,WAAW,IAAI,IAAI,CAAC,WAAW;YAC5C,SAAS,EAAE,SAAS,IAAI,IAAI,CAAC,SAAS;SACvC;QACD,MAAM,EAAE,WAAW,KAAK,IAAI,IAAI,SAAS,KAAK,IAAI;KACnD,CAAC;AACJ,CAAC;AAED,qCAAqC;AACrC,SAAS,OAAO,CAAC,WAAkC;IACjD,OAAO,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC;SAC5B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;SAC5C,IAAI,CAAC,UAAU,CAAC,CAAC;AACtB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,WAA+B;IAC5D,MAAM,IAAI,GAAG,CAAC,KAAe,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1E,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,WAAW,CAAC,OAAO;QAAE,KAAK,CAAC,IAAI,CAAC,KAAK,kBAAkB,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACpF,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IAC/C,MAAM,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;IACjD,IAAI,KAAK,CAAC,MAAM;QAAE,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACjD,IAAI,SAAS,CAAC,MAAM;QAAE,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACzD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,eAAe,CAAC;AAExD,4DAA4D;AAC5D,MAAM,IAAI,GAAG,GAAG,CAAC;AAEjB,SAAS,WAAW,CAAC,IAAY;IAC/B,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,MAAM,IAAI,IAAI,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IACvF,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AACjF,CAAC;AAED,SAAS,aAAa,CAAC,OAAe;IACpC,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IACnD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;QACnE,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QACpE,OAAO,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,6DAA6D;AAC7D,SAAS,YAAY,CAAC,MAA6B;IACjD,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;SACvB,IAAI,CAAC,UAAU,CAAC;SAChB,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;SAChF,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,WAA4B;IAC7D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,KAAK,GAAG,YAAY,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IACpD,MAAM,SAAS,GAAG,YAAY,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;IACtD,IAAI,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC;IACpC,IAAI,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC,CAAC;IAC5C,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAClE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAe;IACrD,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,CAAC;IAC5E,MAAM,GAAG,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC9B,MAAM,MAAM,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,CAAC;IAC9D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,IAAI,CAAC;QACH,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YAClC,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC7B,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;YAChC,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,GAAG,CAAC;gBAAE,OAAO,IAAI,CAAC;YACzF,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,MAAM,MAAM,GAAG,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC;YACnE,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;gBACpC,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;gBACvB,IAAI,KAAK,KAAK,GAAG,IAAI,KAAK,KAAK,GAAG;oBAAE,OAAO,IAAI,CAAC;gBAChD,MAAM,CAAC,kBAAkB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,KAAK,GAAG,CAAC;YAC7D,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,kBAAkB,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AAChE,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,oBAAoB,CAAC,QAAgB,EAAE,WAA4B;IACjF,MAAM,IAAI,GAAG,GAAG,wBAAwB,IAAI,kBAAkB,CAAC,WAAW,CAAC,EAAE,CAAC;IAC9E,OAAO,QAAQ,KAAK,GAAG,IAAI,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,QAAQ,EAAE,CAAC;AAC3E,CAAC;AAED,8GAA8G;AAC9G,MAAM,UAAU,sBAAsB,CAAC,QAAgB;IACrD,OAAO,CACL,QAAQ,KAAK,wBAAwB,IAAI,QAAQ,CAAC,UAAU,CAAC,GAAG,wBAAwB,GAAG,CAAC,CAC7F,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,GAA4B,EAC5B,WAA4B;IAE5B,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,MAAM,CACpD,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,IAAI,CACjD,CAAC;IACF,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,WAAW,CAAC;IACxC,IAAI,KAAK,GAA4B,EAAE,CAAC;IACxC,IAAI,CAAC;QACH,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,GAAG,CAAC,UAAU,EAAE,CAAC,OAAO,CAAU,WAAW,CAAC,KAAK,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;QAC3F,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,aAAa,KAAK,WAAW,CAAC,IAAI;YAAE,KAAK,GAAG,KAAK,CAAC;IACjF,CAAC;IAAC,MAAM,CAAC;QACP,kEAAkE;IACpE,CAAC;IACD,MAAM,WAAW,GAAG,MAAM,EAAE,CAAC;IAC7B,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,EAAE,CAAC;QACxD,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACjE,MAAM,IAAI,GAAG,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACtF,WAAW,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC;IACtE,CAAC;IACD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,CAAC,SAAS,EAAE,CAAC;AAC3D,CAAC"}

package/dist/draft.d.ts

@@ -1,7 +1,7 @@
 /**
  * The draft names and headers of a Deco Next.js site: the `?__draft=` link,
  * the cookie that keeps a preview going, the request header the proxy hands
- * the pages, and the response headers of a page rendered from a draft. The
+ * the pages the version on, and the response headers of a page rendered from a draft. The
  * proxy reads and writes them (`./drafts.ts`, `./proxy`); the pages read the
  * header (`./server`); `./config/index.cjs` repeats them (`config.test.ts`
  * holds them equal). This package's own copy: it never imports
@@ -20,18 +20,44 @@ export declare const DRAFT_PARAM = "__draft";
 export declare const DRAFT_COOKIE = "__deco_draft";
 /**
  * The request header the proxy sets on the request it hands the pages once it
- * accepted the draft: the pointer, already checked. The proxy removes any
- * copy that arrives from outside, and `bindDraft` repeats the host check, so a
- * client can't send one itself.
+ * accepted a Studio link: the version (a draft pointer or a release's commit
+ * SHA), already checked, without the preview's moment and switched tests
+ * (those are decided in the proxy: `ASSIGNMENTS_HEADER`). The proxy removes
+ * any copy that arrives from outside, and `bindDraft` repeats the host check,
+ * so a client can't send one itself.
  */
-export declare const DRAFT_HEADER = "x-deco-draft";
+export declare const VERSION_HEADER = "x-deco-version";
+/**
+ * The request header the proxy sets on a draft request it hands the pages:
+ * the id of the release check it made for it (`cms.checkRelease()`), so
+ * `bindDraft`'s host check and the page's draft reads wait for that check
+ * instead of making their own (one `latest.json` read per preview request).
+ * The proxy removes any copy that arrives from outside; an id the CMS didn't
+ * make (a proxy in another process) is a check of its own anyway.
+ */
+export declare const RELEASE_CHECK_HEADER = "x-deco-release-check";
 /** The URL prefix a drafted request is rewritten onto (`app/%5Fdraft/[[...path]]`). */
 export declare const DRAFT_ROUTE_PREFIX = "/_draft";
 /**
- * The response headers of a page rendered from a draft: never stored by a
- * browser or a CDN (`Cache-Control: no-store, private`, `Vary: Cookie`) and
- * never indexed (`X-Robots-Tag: noindex, nofollow`). `{}` when `pointer` is
- * `null`, so the result of the draft decision applies as is.
+ * The request header the proxy sets when the link named a draft that can't be
+ * read anymore (deleted, say): the pages render the release and
+ * `DraftPreviewIndicator` says so calmly. The proxy removes any copy that
+ * arrives from outside.
+ */
+export declare const DRAFT_UNAVAILABLE_HEADER = "x-deco-draft-unavailable";
+/**
+ * The `Cache-Control` of every response to a preview request (a request with
+ * `?__draft=`, whatever its value, or the draft cookie): always revalidated,
+ * never answered from a cache (PO 2026-10-23).
+ */
+export declare const DRAFT_CACHE_CONTROL = "max-age=0, no-cache, must-revalidate";
+/**
+ * The response headers of a preview: never answered from a browser's or a
+ * CDN's cache (`Cache-Control: max-age=0, no-cache, must-revalidate`, `Vary:
+ * Cookie`) and never indexed (`X-Robots-Tag: noindex, nofollow`). `{}` when
+ * `preview` is `null`, `false` or empty, so the result of the draft decision
+ * applies as is: pass the version, or whether the request carries a draft
+ * signal at all (`?__draft=off` and a refused or unavailable draft too).
  */
-export declare function draftResponseHeaders(pointer: string | null | undefined): Record<string, string>;
+export declare function draftResponseHeaders(preview: string | boolean | null | undefined): Record<string, string>;
 //# sourceMappingURL=draft.d.ts.map

package/dist/draft.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"draft.d.ts","sourceRoot":"","sources":["../src/draft.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,eAAO,MAAM,WAAW,YAAY,CAAC;AAErC;;;GAGG;AACH,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C,uFAAuF;AACvF,eAAO,MAAM,kBAAkB,YAAY,CAAC;AAE5C;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAO/F"}
+{"version":3,"file":"draft.d.ts","sourceRoot":"","sources":["../src/draft.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,eAAO,MAAM,WAAW,YAAY,CAAC;AAErC;;;GAGG;AACH,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAE/C;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D,uFAAuF;AACvF,eAAO,MAAM,kBAAkB,YAAY,CAAC;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,6BAA6B,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,yCAAyC,CAAC;AAE1E;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,GAC3C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxB"}