@decocms/nextjs 8.5.2 → 8.7.0

package/src/assignments.ts

@@ -0,0 +1,278 @@
+/**
+ * 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 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">;
+
+const EXPERIMENTS = { block: "experiments", type: "split-traffic" } as const;
+const CAMPAIGNS = { block: "campaigns", type: "calendar" } as const;
+
+type Reader = ReturnType<CMS["client"]>;
+
+/** Plain code-unit order, the same on every server and locale. */
+const byCodeUnit = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function record(): Assignments {
+  return Object.create(null) as Assignments;
+}
+
+/**
+ * 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: Reader, type: string): Promise<boolean> {
+  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: Reader,
+  spec: { block: string; type: string },
+): Promise<Assignments | null> {
+  try {
+    if (!(await saves(client, spec.type))) return null;
+    const [value] = await client.resolve<unknown>(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: Pick<CMS, "client">,
+  options: ClientOptions,
+): Promise<RequestAssignments> {
+  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: Pick<CMS, "client">,
+  options: ClientOptions,
+): Promise<{ assignments: RequestAssignments; varies: boolean }> {
+  const version = typeof options.version === "string" ? options.version : null;
+  const none: RequestAssignments = { version, experiments: record(), campaigns: record() };
+  let client: Reader;
+  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: Readonly<Assignments>): string[] {
+  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: RequestAssignments): string {
+  const list = (names: string[]) => names.map(encodeURIComponent).join(",");
+  const parts: string[] = [];
+  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: string): string {
+  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: string): string | null {
+  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: Readonly<Assignments>): string {
+  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: PathAssignments): string {
+  const parts: string[] = [];
+  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: string): PathAssignments | null {
+  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<string>();
+  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: string, assignments: PathAssignments): string {
+  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: string): boolean {
+  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: Pick<CMS, "forRelease">,
+  assignments: PathAssignments,
+): Promise<PathAssignments> {
+  const on = Object.keys(assignments.experiments).filter(
+    (name) => assignments.experiments[name] === true,
+  );
+  if (on.length === 0) return assignments;
+  let saved: Record<string, unknown> = {};
+  try {
+    const [block] = await cms.forRelease().resolve<unknown>(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 };
+}

package/src/config/index.cjs

@@ -25,7 +25,7 @@
 
 /** `draftResponseHeaders(pointer)` (`src/draft.ts`), as `next.config` header entries. */
 const DRAFT_NO_STORE_HEADERS = [
-  { key: "Cache-Control", value: "no-store, private" },
+  { key: "Cache-Control", value: "max-age=0, no-cache, must-revalidate" },
   { key: "Vary", value: "Cookie" },
   { key: "X-Robots-Tag", value: "noindex, nofollow" },
 ];

package/src/draft.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
@@ -23,25 +23,56 @@ export 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 const DRAFT_HEADER = "x-deco-draft";
+export 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 const RELEASE_CHECK_HEADER = "x-deco-release-check";
 
 /** The URL prefix a drafted request is rewritten onto (`app/%5Fdraft/[[...path]]`). */
 export 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 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 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 function draftResponseHeaders(pointer: string | null | undefined): Record<string, string> {
-  if (!pointer) return {};
+export function draftResponseHeaders(
+  preview: string | boolean | null | undefined,
+): Record<string, string> {
+  if (!preview) return {};
   return {
-    "Cache-Control": "no-store, private",
+    "Cache-Control": DRAFT_CACHE_CONTROL,
     Vary: "Cookie",
     "X-Robots-Tag": "noindex, nofollow",
   };

package/src/drafts.ts

@@ -1,109 +1,35 @@
 /**
- * Which hosts may render drafts: v7's allowlist (`@decocms/blocks` 7.x
- * `cms/draftSource.ts`: `readAllowedHosts`, `isDraftHostAllowed`,
- * `isDraftPreviewEnabled`), ported as is. v7 read its override from the
- * `DECO_ALLOWED_PREVIEW_HOSTS` variable; here it is the `previewHosts` option,
- * and the site passes the same options to the proxy (`decideDraft`) and to
- * its pages (`bindDraft`).
+ * Which hosts may render drafts: the ones the CMS allows (`cms.readVersion`):
+ * the addresses Studio writes into the current release's metadata, plus
+ * `createCMS`'s `preview.hosts`; every host while the site has published no
+ * list, or with no `site` and no `preview.hosts`. The site declares nothing
+ * here (PO 2026-10-22). The proxy
+ * (`decideDraft`) and the pages (`bindDraft`) ask the same CMS.
  *
- * - The site's own preview hosts: the ones it declares, in the `CMS` block or
- *   as `createCMS({ preview: { hosts } })` (matched as `cms.draftPointer`
- *   matches them). A site that declares none has none, as in v7: blocks'
- *   own default (every host) doesn't count as a declaration.
- * - The hosts Deco runs the site on, named after the site and always added:
- *   `<site>.deco.site` and `<site>.deco-cx.workers.dev`, exact.
- * - `previewHosts: [...]` replaces the site's own list (the inferred hosts are
- *   still added); `previewHosts: "none"` turns previews off on every host.
- *
- * Hosts compare exactly, lowercased, port included (`localhost:3000`). The
- * host is the one the visitor asked for: `x-forwarded-host` behind a proxy,
- * else `host`.
+ * The host is the one the visitor asked for: `x-forwarded-host` behind a
+ * proxy, else `host`.
  *
  * The draft itself is the capability: a host check only bounds where a draft
  * link works. A request the check refuses gets the release, never an error.
  *
+ * What a link carries is a version, as `cms.readVersion` reads it: a draft
+ * pointer, or a published release's commit SHA (Studio's "Preview this
+ * version"), with the preview's moment and switched tests and campaigns
+ * (`__at`, `__test`, `__campaign`; `parseVersion` from `@decocms/blocks`).
+ * Both pass the same host check: a visitor on the live site never picks a
+ * version.
+ *
  * No React, no Next.js and no module state: the proxy and the pages share it.
  */
-import { type CMS, parseDraftPointer, type RequestLike } from "@decocms/blocks";
+import {
+  type CMS,
+  parseDraftPointer,
+  parseVersion,
+  type RequestLike,
+  type RequestVersion,
+} from "@decocms/blocks";
 import { DRAFT_COOKIE, DRAFT_PARAM } from "./draft.ts";
 
-export interface PreviewPolicy {
-  /** The site's name: `<site>.deco.site` and `<site>.deco-cx.workers.dev` may preview. */
-  site?: string;
-  /** Replaces the `CMS` block's preview hosts; `"none"` turns previews off everywhere. */
-  previewHosts?: readonly string[] | "none";
-}
-
-/** The hosts Deco runs `site` on, which may always preview (unless previews are off). */
-export function inferredPreviewHosts(site: string | undefined): string[] {
-  const s = (site ?? "").trim().toLowerCase();
-  return s ? [`${s}.deco.site`, `${s}.deco-cx.workers.dev`] : [];
-}
-
-function overrideHosts(policy: PreviewPolicy): string[] {
-  if (policy.previewHosts === "none") return ["none"];
-  return (policy.previewHosts ?? []).map((h) => h.trim().toLowerCase()).filter(Boolean);
-}
-
-/**
- * Whether `host` may preview without asking the CMS: `true` (an override or
- * inferred host), `false` (previews off, or the override leaves it out), or
- * `"cms"` when only the site's declared preview hosts can say (none declared:
- * `false`, see {@link declaresPreviewHosts}).
- */
-export function previewHostDecision(host: string, policy: PreviewPolicy): boolean | "cms" {
-  const override = overrideHosts(policy);
-  if (override.includes("none")) return false;
-  const h = host.trim().toLowerCase();
-  if (h === "") return false;
-  if (inferredPreviewHosts(policy.site).includes(h)) return true;
-  if (policy.previewHosts !== undefined) return override.includes(h);
-  return "cms";
-}
-
-/**
- * Whether any host may preview (v7's `isDraftPreviewEnabled`): a page checks
- * it before it reads the request's headers, so a site with previews off never
- * turns a static page dynamic. `false` for `previewHosts: "none"`; `true` with
- * a site name or an override list; otherwise whether the site declares
- * preview hosts and they allow any.
- */
-export async function isDraftPreviewEnabled(
-  cms: Pick<CMS, "settings" | "forRelease">,
-  policy: PreviewPolicy,
-): Promise<boolean> {
-  const override = overrideHosts(policy);
-  if (override.includes("none")) return false;
-  if (inferredPreviewHosts(policy.site).length > 0) return true;
-  if (policy.previewHosts !== undefined) return override.length > 0;
-  return (await declaresPreviewHosts(cms)) && (await cms.settings()).preview.hosts.length > 0;
-}
-
-/**
- * Whether the site declares its own preview hosts: in the `CMS` block, or as
- * `createCMS`'s `preview.hosts`. When it declares none, `cms.settings()`
- * reports blocks' default, every host (`["*"]`), which v7 never had: there,
- * a site without a list previewed only on its Deco hosts. The saved `CMS`
- * block tells an explicit `["*"]` from that default.
- */
-export async function declaresPreviewHosts(
-  cms: Pick<CMS, "settings" | "forRelease">,
-): Promise<boolean> {
-  const { hosts } = (await cms.settings()).preview;
-  if (hosts.length !== 1 || hosts[0] !== "*") return true;
-  try {
-    const [block] = await cms.forRelease().resolve<unknown>("CMS", { run: false });
-    const preview = isRecord(block) ? block.preview : undefined;
-    return isRecord(preview) && ("hosts" in preview || "__resolveType" in preview);
-  } catch {
-    return false;
-  }
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 const DRAFT_OFF = "off";
 
 function draftParam(request: RequestLike): string | null {
@@ -129,16 +55,16 @@ function readCookie(header: string | null, name: string): string | null {
 }
 
 /**
- * The pointer a request carries, as `@decocms/blocks` reads it: `?__draft=`
- * first, then the draft cookie; `null` for `?__draft=off` and for a value
- * that doesn't parse.
+ * What a request's Studio link asks for, as `@decocms/blocks` reads it:
+ * `?__draft=` first, then the draft cookie; `null` for `?__draft=off` and
+ * for a value that doesn't parse.
  */
-export function readDraftPointer(request: RequestLike): string | null {
+export function readDraftVersion(request: RequestLike): RequestVersion | null {
   const param = draftParam(request);
   if (param === DRAFT_OFF) return null;
-  if (param && parseDraftPointer(param) !== null) return param;
-  const cookie = readCookie(request.headers.get("cookie"), DRAFT_COOKIE);
-  return cookie && parseDraftPointer(cookie) !== null ? cookie : null;
+  const fromLink = param ? parseVersion(param) : null;
+  if (fromLink !== null) return fromLink;
+  return parseVersion(readCookie(request.headers.get("cookie"), DRAFT_COOKIE));
 }
 
 /** Whether the request carries a draft signal at all: without one the CMS is never asked. */
@@ -176,29 +102,44 @@ export function requestLike(
 }
 
 /**
- * The draft `request` renders under `policy`, or `null` for the release: the
- * pointer it carries, on a host the policy (or, when only it can say, the
- * `CMS` block) allows.
+ * What `request` renders (a draft pointer or a release's commit SHA, with
+ * the preview's moment and switched tests and campaigns), or `null` for the
+ * current release: what its Studio link carries, on a host the CMS allows.
  */
 export async function allowedDraft(
-  cms: Pick<CMS, "draftPointer" | "settings" | "forRelease">,
+  cms: Pick<CMS, "readVersion">,
   request: RequestLike,
-  policy: PreviewPolicy,
-): Promise<string | null> {
-  const pointer = readDraftPointer(request);
-  if (pointer === null) return null;
-  let host: string;
-  try {
-    host = new URL(request.url).host;
-  } catch {
-    return null;
-  }
-  const decision = previewHostDecision(host, policy);
-  const allowed =
-    decision === "cms"
-      ? (await declaresPreviewHosts(cms)) && (await cms.draftPointer(request)) !== null
-      : decision;
-  return allowed ? pointer : null;
+  releaseCheck?: string | null,
+): Promise<RequestVersion | null> {
+  const read = readDraftVersion(request);
+  if (read === null) return null;
+  return (await cms.readVersion(request, { releaseCheck })) === null ? null : read;
+}
+
+/** A draft pointer's version that names no draft: the release, nothing fetched. */
+const LOCAL_VERSION = "local";
+
+/** Whether a version names a saved draft (a pointer, not a release's SHA and not `local`). */
+export function namesDraft(version: string): boolean {
+  const parsed = parseDraftPointer(version);
+  return parsed !== null && parsed.version !== LOCAL_VERSION;
+}
+
+/**
+ * The release check of a request whose link names a draft
+ * (`cms.checkRelease()`), so its host check, its draft reads and its render
+ * share one read of `latest.json`: the one `forwarded` names when the CMS
+ * made it (the proxy's, for the same request), else a new one. `undefined`
+ * for any other request: the release, a release's SHA, no link.
+ */
+export async function draftReleaseCheck(
+  cms: Pick<CMS, "checkRelease">,
+  request: RequestLike,
+  forwarded?: string | null,
+): Promise<string | undefined> {
+  const read = readDraftVersion(request);
+  if (read === null || !namesDraft(read.version)) return undefined;
+  return cms.checkRelease(forwarded);
 }
 
 /**
@@ -223,7 +164,11 @@ export function endsPreview(request: RequestLike): boolean {
   return draftParam(request) === DRAFT_OFF;
 }
 
-/** Whether the request's own `?__draft=` carries `pointer` (a draft link, not the cookie). */
-export function fromDraftLink(request: RequestLike, pointer: string): boolean {
-  return draftParam(request) === pointer;
+/**
+ * The request's own `?__draft=` value when it is a version (a draft link,
+ * not the cookie): the value its cookie stores; `null` otherwise.
+ */
+export function draftLinkValue(request: RequestLike): string | null {
+  const param = draftParam(request);
+  return param && param !== DRAFT_OFF && parseVersion(param) !== null ? param : null;
 }

package/src/index.ts

@@ -11,7 +11,8 @@
  *   Outside Studio's frame, "." opens the page in Studio's editor.
  * - `StudioPage`: rendered inside each CMS page, `<StudioPage pathTemplate={page.path} />`,
  *   tells the bridge which page "." opens (the root layout doesn't re-render per page).
- * - `DRAFT_PARAM`, `DRAFT_COOKIE`, `DRAFT_HEADER`, `draftResponseHeaders`,
+ * - `DRAFT_PARAM`, `DRAFT_COOKIE`, `VERSION_HEADER`, `draftResponseHeaders`,
+ *   `VISITOR_HEADER`, `ASSIGNMENTS_HEADER`,
  *   `STUDIO_ORIGINS`, `STUDIO_FRAME_ANCESTORS`, `isStudioOrigin`: for a site
  *   that needs them in its own code (a route that sets its own headers, a CSP
  *   it writes itself). The package's own copy: it never imports
@@ -23,10 +24,12 @@
  */
 
 export { DraftBadge, StudioPage, type StudioPageInfo } from "@decocms/blocks/preview";
+export { ASSIGNMENTS_HEADER } from "./assignments.ts";
 export {
   DraftPreviewIndicator,
   type DraftPreviewIndicatorProps,
 } from "./DraftPreviewIndicator.tsx";
-export { DRAFT_COOKIE, DRAFT_HEADER, DRAFT_PARAM, draftResponseHeaders } from "./draft.ts";
+export { DRAFT_COOKIE, DRAFT_PARAM, draftResponseHeaders, VERSION_HEADER } from "./draft.ts";
 export { StudioBridge, type StudioBridgeProps } from "./StudioBridge.ts";
 export { isStudioOrigin, STUDIO_FRAME_ANCESTORS, STUDIO_ORIGINS } from "./studio.ts";
+export { VISITOR_HEADER } from "./visitor.ts";

package/src/instrumentation/index.ts

@@ -24,7 +24,7 @@
  * Labels: `http.route` is Next's route template (`unmatched` when Next names
  * none); RSC requests count under their page's route, as the requests they
  * are. `cache` is `DRAFT` for a draft render (the proxy forwarded
- * `x-deco-draft`, or the request was rewritten onto `/_draft`) and otherwise
+ * `x-deco-version`, or the request was rewritten onto `/_draft`) and otherwise
  * `BYPASS`: Next decides its cache (`x-nextjs-cache`) on the response, which
  * the span never sees.
  */
@@ -40,7 +40,7 @@ import type {
   Tracer,
   TracerProvider,
 } from "@opentelemetry/api";
-import { DRAFT_HEADER, DRAFT_ROUTE_PREFIX } from "../draft.ts";
+import { DRAFT_ROUTE_PREFIX, VERSION_HEADER } from "../draft.ts";
 
 type Api = typeof import("@opentelemetry/api");
 
@@ -235,7 +235,7 @@ function draftPropagator(DRAFT: symbol): TextMapPropagator {
     inject() {},
     extract(context, carrier, getter) {
       try {
-        const value = getter.get(carrier, DRAFT_HEADER);
+        const value = getter.get(carrier, VERSION_HEADER);
         return value !== undefined && value !== "" ? context.setValue(DRAFT, true) : context;
       } catch {
         return context;