@decocms/nextjs 8.5.2 → 8.6.0

package/src/proxy/index.ts

@@ -1,5 +1,6 @@
 /**
- * `@decocms/nextjs/proxy`: draft previews in a Next.js proxy (`proxy.ts`, or
+ * `@decocms/nextjs/proxy`: draft previews, the visitor and what a request's
+ * content gives it, decided once, in a Next.js proxy (`proxy.ts`, or
  * `middleware.ts` before Next 16). No React and no block map: pass the proxy
  * a CMS handle made with an empty block map and the app's options, which
  * shares the app's instance (one per process) without pulling the site's
@@ -10,90 +11,230 @@
  * export const proxyCms = createCMS({ blocks: {}, ...cmsConfig });
  * ```
  *
- * A site with a proxy of its own calls the pieces (`decideDraft`, then
- * `draftRequestHeaders` on the request it forwards, then `applyDraft` on the
- * response); a site without one exports `draftProxy(...)`.
+ * A site with a proxy of its own calls the pieces (`decideDraft`,
+ * `decideVisitor` and `decideAssignments`, then `draftRequestHeaders`,
+ * `visitorRequestHeaders` and `assignmentsRequestHeaders` on the request it
+ * forwards, then `applyDraft` and `applyVisitor` on the response); a site
+ * without one exports `draftProxy(...)`.
  *
- * Statically rendered pages can't read a draft, so a drafted request to one
- * is rewritten onto a dynamic draft route (`/_draft/<path>`, mounted as
+ * The proxy decides: the version (`decideDraft`: a Studio link's draft or old
+ * release, after the host allowlist, with the preview's moment and switched
+ * tests and campaigns), the visitor (`decideVisitor`: `readVisitor` from
+ * `@decocms/blocks/experiments`, the `deco_segment` cookie or a new visitor)
+ * and, from both, each test and campaign on or off (`decideAssignments`:
+ * `cms.client({ version, visitor, date, experiments, campaigns })` resolving
+ * the saved `experiments` and `campaigns` blocks). It forwards them on
+ * `x-deco-version`, `x-deco-visitor` and `x-deco-assignments` (copies from
+ * outside are always removed), and the page builds
+ * `cms.client({ version, experiments, campaigns })` from them
+ * (`contentClient`), deciding nothing again. It sends the visitor's cookie on
+ * a first visit only, never from a preview.
+ *
+ * Cached (ISR) pages can't read a request, so a drafted request to one is
+ * rewritten onto a dynamic draft route (`/_draft/<path>`, mounted as
  * `app/%5Fdraft/...`: a literal `_draft` folder is private in Next and never
- * routes).
+ * routes), and a published one onto the assignments route
+ * (`/_assignments/<assignments>/<path>`, `rewriteToAssignmentsRoute`), where
+ * `assignedClient` from `@decocms/nextjs/server` builds the client from the
+ * path.
+ *
+ * The binding caches nothing. A site that caches in front of its pages (a
+ * CDN keyed on a request header) keys on the request's assignments, never on
+ * the visitor: `assignmentsKey(await decideAssignments(proxyCms, draft,
+ * visitor))`, `""` when there are none.
  *
  * The proxy measures no requests: it runs before Next routes and renders the
  * page. `http.server.request.duration` comes from Next's own request span
  * (`register` from `@decocms/nextjs/instrumentation`).
  */
-import type { CMS } from "@decocms/blocks";
+import type { CMS, RequestVersion } from "@decocms/blocks";
+import { readVisitor, serializeVisitor, type Visitor } from "@decocms/blocks/experiments";
 import { type NextRequest, NextResponse } from "next/server.js";
-import { DRAFT_HEADER, DRAFT_ROUTE_PREFIX, draftResponseHeaders } from "../draft.ts";
+import {
+  ASSIGNMENTS_HEADER,
+  assignmentsRoutePath,
+  assignmentsSegment,
+  isAssignmentsRoutePath,
+  type RequestAssignments,
+  readAssignmentsAndScope,
+} from "../assignments.ts";
+import { DRAFT_ROUTE_PREFIX, draftResponseHeaders, VERSION_HEADER } from "../draft.ts";
 import {
   allowedDraft,
   draftCookie,
+  draftLinkValue,
   endsPreview,
-  fromDraftLink,
   hasDraftSignal,
-  type PreviewPolicy,
   requestLike,
 } from "../drafts.ts";
+import { VISITOR_HEADER } from "../visitor.ts";
 
-export {
-  inferredPreviewHosts,
-  type PreviewPolicy,
-  previewHostDecision,
-  requestLike,
-} from "../drafts.ts";
+export { requestLike } from "../drafts.ts";
 
-/** What the proxy needs from the CMS: the site's declared preview hosts and their check. */
-export type CMSHandle = Pick<CMS, "draftPointer" | "settings" | "forRelease">;
+/** What the draft decision needs from the CMS: its preview host check, and the release. */
+export type CMSHandle = Pick<CMS, "readVersion" | "forRelease">;
 
 /** What the proxy does with a request's draft state. */
 export interface DraftDecision {
-  /** The draft this request renders, after the host check; `null` for the release. */
-  pointer: string | null;
-  /** The `Set-Cookie` the response carries: storing a draft link's pointer, or ending a preview. */
+  /**
+   * What this request's Studio link asks for, after the host check: the
+   * version (a draft pointer, or a release's commit SHA) and the preview's
+   * moment and switched tests and campaigns, in the shape of
+   * `cms.client()`'s options; `null` for the current release.
+   */
+  version: RequestVersion | null;
+  /** The `Set-Cookie` the response carries: storing a link's version, or ending a preview. */
   setCookie: string | null;
 }
 
-export { DRAFT_ROUTE_PREFIX } from "../draft.ts";
+export {
+  ASSIGNMENTS_HEADER,
+  ASSIGNMENTS_ROUTE_PREFIX,
+  assignmentsKey,
+  assignmentsRoutePath,
+  assignmentsSegment,
+  isAssignmentsRoutePath,
+  type PathAssignments,
+  parseAssignmentsSegment,
+  type RequestAssignments,
+  readAssignments,
+} from "../assignments.ts";
+export { DRAFT_ROUTE_PREFIX, VERSION_HEADER } from "../draft.ts";
 
-const INERT: DraftDecision = Object.freeze({ pointer: null, setCookie: null });
+const INERT: DraftDecision = Object.freeze({ version: null, setCookie: null });
 
 /**
- * The draft a request renders and the cookie its response sets, under
- * `policy` (the same options the pages pass to `bindDraft`). A request with
+ * The version a request renders and the cookie its response sets, on a host
+ * the CMS allows (as the pages' `bindDraft` checks again). A request with
  * no `?__draft=` and no draft cookie never reaches the CMS.
  */
 export async function decideDraft(
   cms: CMSHandle,
   request: NextRequest | Request,
-  policy: PreviewPolicy = {},
 ): Promise<DraftDecision> {
   const url = new URL(request.url);
   const like = requestLike(request.headers, url.pathname + url.search, url.host);
   if (like === null || !hasDraftSignal(like)) return INERT;
   // Ending a preview is allowed on any host, so a cookie set earlier always goes.
-  if (endsPreview(like)) return { pointer: null, setCookie: draftCookie("", ["Max-Age=0"]) };
-  const pointer = await allowedDraft(cms, like, policy);
-  if (pointer === null) return INERT;
-  return {
-    pointer,
-    setCookie: fromDraftLink(like, pointer) ? draftCookie(encodeURIComponent(pointer)) : null,
-  };
+  if (endsPreview(like)) return { version: null, setCookie: draftCookie("", ["Max-Age=0"]) };
+  const version = await allowedDraft(cms, like);
+  if (version === null) return INERT;
+  const link = draftLinkValue(like);
+  return { version, setCookie: link ? draftCookie(encodeURIComponent(link)) : null };
 }
 
+/** The headers the proxy writes for the pages: never taken from outside. */
+const OWN_HEADERS = [VERSION_HEADER, VISITOR_HEADER, ASSIGNMENTS_HEADER];
+
 /**
- * The request headers to forward: the accepted pointer on `x-deco-draft`, so
- * the root layout can bind the draft on the same request (a layout gets no
+ * The request headers to forward: the accepted version on `x-deco-version`,
+ * so the root layout can bind the draft on the same request (a layout gets no
  * `searchParams`, and on a draft link the cookie is only on the response).
- * A copy that arrives from outside is always removed.
+ * A copy that arrives from outside is always removed, and so are any
+ * `x-deco-visitor` and `x-deco-assignments` (`visitorRequestHeaders` and
+ * `assignmentsRequestHeaders` set the proxy's own).
  */
 export function draftRequestHeaders(
   request: NextRequest | Request,
   decision: DraftDecision,
 ): Headers {
   const headers = new Headers(request.headers);
-  if (decision.pointer) headers.set(DRAFT_HEADER, decision.pointer);
-  else headers.delete(DRAFT_HEADER);
+  for (const name of OWN_HEADERS) headers.delete(name);
+  if (decision.version) headers.set(VERSION_HEADER, decision.version.version);
+  return headers;
+}
+
+/** The visitor of one request. */
+export interface VisitorDecision {
+  /** Who is visiting: the `deco_segment` cookie's visitor, or a new one. */
+  visitor: Visitor;
+  /** The `deco_segment` `Set-Cookie`, on a first visit to the live site; `null` otherwise. */
+  setCookie: string | null;
+}
+
+/** Whether the visitor asked over https (`x-forwarded-proto` first, as a host in front reports it). */
+function isHttps(request: NextRequest | Request): boolean {
+  const forwarded = request.headers.get("x-forwarded-proto")?.split(",")[0]?.trim();
+  if (forwarded) return forwarded === "https";
+  return new URL(request.url).protocol === "https:";
+}
+
+/**
+ * The visitor of a request (`readVisitor`: the `deco_segment` cookie, or a
+ * new visitor when it had no id) and the cookie to send back, only on a first
+ * visit and never from a preview (`draft` holds a version): Studio is not a
+ * visitor. Reads no content.
+ */
+export function decideVisitor(
+  request: NextRequest | Request,
+  draft: DraftDecision,
+): VisitorDecision {
+  // `readVisitor` makes the cookie `Secure` unless the request came over plain http.
+  const { visitor, cookie } = readVisitor({
+    url: isHttps(request) ? "https://localhost/" : "http://localhost/",
+    headers: request.headers,
+  });
+  return { visitor, setCookie: draft.version === null ? cookie : null };
+}
+
+/**
+ * The forwarded headers with the visitor on `x-deco-visitor`. Pass it the
+ * headers `draftRequestHeaders` gave, which already removed a copy from
+ * outside.
+ */
+export function visitorRequestHeaders(headers: Headers, decision: VisitorDecision): Headers {
+  const out = new Headers(headers);
+  out.set(VISITOR_HEADER, serializeVisitor(decision.visitor));
+  return out;
+}
+
+/** The `deco_segment` cookie on the response, on a first visit. */
+export function applyVisitor<R extends Response>(response: R, decision: VisitorDecision): R {
+  if (decision.setCookie) response.headers.append("set-cookie", decision.setCookie);
+  return response;
+}
+
+/**
+ * Each test and campaign on or off for this request, decided once:
+ * `cms.client({ visitor, ...version })` (the visitor, and the Studio link's
+ * version, moment and switched tests and campaigns) resolving the saved
+ * `experiments` and `campaigns` blocks. Missing blocks, or content that
+ * doesn't load, give none, never an error.
+ */
+export function decideAssignments(
+  cms: Pick<CMS, "client">,
+  draft: DraftDecision,
+  visitor: VisitorDecision,
+): Promise<RequestAssignments> {
+  return readAssignmentsAndScope(cms, { visitor: visitor.visitor, ...draft.version }).then(
+    (read) => read.assignments,
+  );
+}
+
+/**
+ * The forwarded headers with the decided tests and campaigns on
+ * `x-deco-assignments` (`assignmentsSegment`), for `bindDraft` and
+ * `contentClient`. Pass it the headers `draftRequestHeaders` gave.
+ */
+export function assignmentsRequestHeaders(
+  headers: Headers,
+  assignments: RequestAssignments,
+): Headers {
+  const out = new Headers(headers);
+  out.set(ASSIGNMENTS_HEADER, assignmentsSegment(assignments));
+  return out;
+}
+
+/** The request headers to forward: the version's and, when given, the visitor's and the assignments. */
+function forwardedHeaders(
+  request: NextRequest | Request,
+  draft: DraftDecision,
+  visitor: VisitorDecision | undefined,
+  assignments: RequestAssignments | undefined,
+): Headers {
+  let headers = draftRequestHeaders(request, draft);
+  if (visitor !== undefined) headers = visitorRequestHeaders(headers, visitor);
+  if (assignments !== undefined) headers = assignmentsRequestHeaders(headers, assignments);
   return headers;
 }
 
@@ -104,61 +245,133 @@ export function isDraftRoutePath(pathname: string): boolean {
 
 /**
  * The rewrite of a drafted request onto the draft route, keeping its path and
- * forwarding the pointer; `null` when the request isn't drafted or is already
- * on the draft route.
+ * forwarding the version and, when given, the visitor (`decideVisitor`) and
+ * the assignments (`decideAssignments`); `null` when the request isn't
+ * drafted or is already on the draft route.
  */
 export function rewriteToDraftRoute(
   request: NextRequest,
   decision: DraftDecision,
+  visitor?: VisitorDecision,
+  assignments?: RequestAssignments,
 ): NextResponse | null {
-  if (!decision.pointer) return null;
+  if (!decision.version) return null;
   const url = request.nextUrl.clone();
   if (isDraftRoutePath(url.pathname)) return null;
   url.pathname = `${DRAFT_ROUTE_PREFIX}${url.pathname}`;
   return NextResponse.rewrite(url, {
-    request: { headers: draftRequestHeaders(request, decision) },
+    request: { headers: forwardedHeaders(request, decision, visitor, assignments) },
+  });
+}
+
+/** An assignments-route response's `Cache-Control` when its content has tests or campaigns. */
+const ASSIGNED_CACHE_CONTROL = "private, no-cache";
+
+/**
+ * The rewrite of a published request onto the assignments route,
+ * `/_assignments/<assignments>/<path>`: each test on or off for the visitor
+ * and each campaign running or not now (`readAssignments` on the current
+ * release), as one path segment, so Next's own path-keyed cache (ISR, the
+ * full route cache) keeps one entry per set of assignments. Visitors on the
+ * same side of every test share a path; the visitor id is never in it, and
+ * the page reads neither the visitor nor the version (the proxy's headers are
+ * removed from the request it forwards), so Next can cache it. The page
+ * builds its client with `assignedClient` from `@decocms/nextjs/server`,
+ * `cms.client({ experiments, campaigns })` from the path: the proxy decides,
+ * the page renders that. A cached page (ISR, `revalidate = 600`) is about 10
+ * minutes stale (the first request after that still gets it while Next
+ * renders it again), a banner switching on late, which is accepted.
+ *
+ * `null` for a drafted request (it renders on the draft route, never cached)
+ * and for a path already on the draft or assignments route. When the content
+ * saves tests or campaigns, the response is marked `Cache-Control: private,
+ * no-cache`: Next keeps one cached page per set of assignments, but the URL
+ * the visitor asked for answers by their cookie and the moment, so a CDN in
+ * front must not share it. Call it only for the paths the assignments route
+ * renders (the CMS's pages), and answer a direct hit on the route with a 404
+ * (`isAssignmentsRoutePath`).
+ */
+export async function rewriteToAssignmentsRoute(
+  cms: Pick<CMS, "client">,
+  request: NextRequest,
+  draft: DraftDecision,
+  visitor: VisitorDecision,
+): Promise<NextResponse | null> {
+  if (draft.version) return null;
+  const url = request.nextUrl.clone();
+  if (isDraftRoutePath(url.pathname) || isAssignmentsRoutePath(url.pathname)) return null;
+  const { assignments, varies } = await readAssignmentsAndScope(cms, { visitor: visitor.visitor });
+  url.pathname = assignmentsRoutePath(url.pathname, assignments);
+  const response = NextResponse.rewrite(url, {
+    request: { headers: draftRequestHeaders(request, INERT) },
   });
+  // The URL the visitor asked for answers differently by their cookie and the moment: a
+  // shared cache in front (a CDN) must not keep Next's ISR `s-maxage` under it.
+  if (varies) response.headers.set("Cache-Control", ASSIGNED_CACHE_CONTROL);
+  return response;
 }
 
 /**
  * The cookie and the response headers of a draft: `Set-Cookie`, and for a
  * drafted response `Cache-Control: no-store, private`, `Vary: Cookie` and
  * `X-Robots-Tag: noindex, nofollow` (`draftResponseHeaders`). With the
- * pointer in a cookie a draft shares its URL with the published page, so a
+ * version in a cookie a draft shares its URL with the published page, so a
  * cache keyed on the URL alone would serve it to visitors.
  */
 export function applyDraft<R extends Response>(response: R, decision: DraftDecision): R {
   if (decision.setCookie) response.headers.append("set-cookie", decision.setCookie);
-  for (const [name, value] of Object.entries(draftResponseHeaders(decision.pointer))) {
+  for (const [name, value] of Object.entries(draftResponseHeaders(decision.version?.version))) {
     response.headers.set(name, value);
   }
   return response;
 }
 
-export interface DraftProxyOptions extends PreviewPolicy {
+export interface DraftProxyOptions {
   /**
    * Which drafted requests go to the draft route (a statically rendered
    * page's). Default: every drafted request outside the draft route. Return
    * `false` for a route that is already dynamic and binds the draft itself.
    */
   rewrite?: (request: NextRequest) => boolean;
+  /**
+   * Which published requests render on the assignments route
+   * (`rewriteToAssignmentsRoute`): the CMS's pages, when the site mounts
+   * `app/%5Fassignments/[assignments]/[[...path]]`. Default: none. A direct
+   * hit on the route gets a 404 once this is set.
+   */
+  assignments?: (request: NextRequest) => boolean;
 }
 
 /**
- * The whole draft flow for a site with no proxy of its own:
- * `export const proxy = draftProxy(proxyCms, { site: "my-store" })`.
+ * The whole flow for a site with no proxy of its own:
+ * `export const proxy = draftProxy(proxyCms)`. Every
+ * request it forwards carries the version, the visitor and the assignments
+ * it decided.
  */
 export function draftProxy(
-  cms: CMSHandle,
+  cms: CMSHandle & Pick<CMS, "client">,
   options: DraftProxyOptions = {},
 ): (request: NextRequest) => Promise<NextResponse> {
-  const { rewrite = () => true, ...policy } = options;
+  const { rewrite = () => true, assignments } = options;
   return async (request) => {
-    const decision = await decideDraft(cms, request, policy);
-    const rewritten = rewrite(request) ? rewriteToDraftRoute(request, decision) : null;
-    const response =
-      rewritten ??
-      NextResponse.next({ request: { headers: draftRequestHeaders(request, decision) } });
-    return applyDraft(response, decision);
+    if (assignments && isAssignmentsRoutePath(request.nextUrl.pathname)) {
+      return new NextResponse(null, { status: 404 });
+    }
+    const decision = await decideDraft(cms, request);
+    const visitor = decideVisitor(request, decision);
+    const onAssignmentsRoute = decision.version === null && assignments?.(request) === true;
+    const rewritten = onAssignmentsRoute
+      ? await rewriteToAssignmentsRoute(cms, request, decision, visitor)
+      : null;
+    let response = rewritten;
+    if (response === null) {
+      const decided = await decideAssignments(cms, decision, visitor);
+      response =
+        (rewrite(request) ? rewriteToDraftRoute(request, decision, visitor, decided) : null) ??
+        NextResponse.next({
+          request: { headers: forwardedHeaders(request, decision, visitor, decided) },
+        });
+    }
+    return applyVisitor(applyDraft(response, decision), visitor);
   };
 }

package/src/server/index.ts

@@ -2,76 +2,195 @@
  * `@decocms/nextjs/server`: draft previews in Server Components (pages,
  * layouts, route handlers). Server only: it reads `next/headers`.
  *
- * A page (and, through the `x-deco-draft` header the proxy forwards, the root
- * layout) binds the request's draft before it reads content, then reads
- * through `contentClient(cms)`:
+ * The proxy decides what a request reads (`@decocms/nextjs/proxy`): the
+ * version, the visitor, and each test and campaign on or off, forwarded on
+ * `x-deco-version`, `x-deco-visitor` and `x-deco-assignments`. A page (and,
+ * through those headers, the root layout) binds them before it reads
+ * content, then reads through `contentClient(cms)`, which builds
+ * `cms.client({ version, experiments, campaigns })` and decides nothing
+ * again:
  *
  * ```tsx
  * export default async function Page({ searchParams }) {
- *   await bindDraft(cms, { searchParams: await searchParams, site: "my-store" });
+ *   await bindDraft(cms, { searchParams: await searchParams });
  *   const client = contentClient(cms);
  *   …
  *   return <>{sections}<DraftPreviewIndicator /></>;
  * }
  * ```
  *
- * The host check is the proxy's (`decideDraft`), repeated here with the same
- * options, so a route the proxy doesn't match, or a forged `x-deco-draft`,
- * still gets the release on a host that may not preview.
+ * The host check is the proxy's (`decideDraft`), repeated here against the
+ * same CMS, so a route the proxy doesn't match, or a forged `x-deco-version`,
+ * still gets the release on a host that may not preview. On the release, a
+ * test at 0% stays off whatever `x-deco-assignments` says.
  */
 
-import type { Client, CMS } from "@decocms/blocks";
+import type { Client, ClientOptions, CMS } from "@decocms/blocks";
+import { parseVisitor } from "@decocms/blocks/experiments";
 import { headers } from "next/headers.js";
-import { DRAFT_HEADER, DRAFT_PARAM } from "../draft.ts";
-import { allowedDraft, isDraftPreviewEnabled, type PreviewPolicy, requestLike } from "../drafts.ts";
+import {
+  ASSIGNMENTS_HEADER,
+  type PathAssignments,
+  parseAssignmentsSegment,
+  withoutDarkTests,
+} from "../assignments.ts";
+import { DRAFT_PARAM, VERSION_HEADER } from "../draft.ts";
+import { allowedDraft, requestLike } from "../drafts.ts";
+import { VISITOR_HEADER } from "../visitor.ts";
 import { activeDraftPointer, draftSlot } from "./slot.ts";
 
-export { type PreviewPolicy, requestLike } from "../drafts.ts";
+export {
+  ASSIGNMENTS_ROUTE_PREFIX,
+  assignmentsSegment,
+  type PathAssignments,
+  parseAssignmentsSegment,
+} from "../assignments.ts";
+export { requestLike } from "../drafts.ts";
 export { activeDraftPointer };
 
 /** A page's `searchParams` prop, awaited. */
 export type SearchParams = Record<string, string | string[] | undefined>;
 
-export interface BindDraftOptions extends PreviewPolicy {
-  /** The page's own `searchParams` (a layout has none: it reads the proxy's `x-deco-draft`). */
+export interface BindDraftOptions {
+  /** The page's own `searchParams` (a layout has none: it reads the proxy's `x-deco-version`). */
   searchParams?: SearchParams;
 }
 
+type BindCMS = Pick<CMS, "readVersion" | "forRelease">;
+
 function firstParam(searchParams: SearchParams | undefined, key: string): string | null {
   const raw = searchParams?.[key];
   return (Array.isArray(raw) ? raw[0] : raw) ?? null;
 }
 
 /**
- * Binds the request's draft, if any: the page's own `?__draft=` first (`off`
- * leaves preview), then the pointer the proxy forwarded on `x-deco-draft`,
- * then the draft cookie, each on a host the options allow. Returns whether a
- * draft was bound. With previews off on every host it returns `false`
- * without reading the request, so a static page stays static.
+ * Binds what the request reads: the version, if any (the page's own
+ * `?__draft=` first, `off` leaving preview, then the version the proxy
+ * forwarded on `x-deco-version`, then the draft cookie, each on a host the
+ * CMS allows), and what the proxy decided (`x-deco-assignments`) and the
+ * visitor it read (`x-deco-visitor`). Returns whether a version was bound:
+ * a draft, or a published release's commit SHA (Studio's "Preview this
+ * version"). It reads the request's headers, so it belongs on the draft
+ * route; a cached (ISR) page reads what its path names (`assignedClient`).
  */
-export async function bindDraft(
-  cms: Pick<CMS, "draftPointer" | "settings" | "forRelease">,
-  options: BindDraftOptions = {},
-): Promise<boolean> {
-  const { searchParams, ...policy } = options;
-  if (!(await isDraftPreviewEnabled(cms, policy))) return false;
+export async function bindDraft(cms: BindCMS, options: BindDraftOptions = {}): Promise<boolean> {
+  if (await bindVersion(cms, options)) {
+    // A preview renders per request anyway, and may switch on a test at 0%.
+    await bindForwarded(cms, false);
+    return true;
+  }
+  if (await variesByVisitor(cms)) await bindForwarded(cms, true);
+  return false;
+}
+
+/** The visitor and the assignments the proxy forwarded, if any. */
+async function bindForwarded(cms: BindCMS, release: boolean): Promise<void> {
+  const requestHeaders = await headers();
+  const slot = draftSlot();
+  slot.visitor = parseVisitor(requestHeaders.get(VISITOR_HEADER));
+  const decided = parseAssignmentsSegment(requestHeaders.get(ASSIGNMENTS_HEADER) ?? "");
+  slot.assignments = decided && release ? await withoutDarkTests(cms, decided) : decided;
+}
+
+/**
+ * Whether the release saves an `experiments` block (the built-in
+ * `split-traffic`) or a `campaigns` block (the built-in `calendar`) with a
+ * name in it: only then does a page vary by what the proxy decided. Read from
+ * memory, unresolved; `false` when both are missing.
+ */
+async function variesByVisitor(cms: Pick<CMS, "forRelease">): Promise<boolean> {
+  const saves = async (name: string, type: string): Promise<boolean> => {
+    try {
+      const [block] = await cms.forRelease().resolve<unknown>(name, { run: false });
+      if (typeof block !== "object" || block === null) return false;
+      const record = block as Record<string, unknown>;
+      return (
+        record.__resolveType === type && Object.keys(record).some((key) => key !== "__resolveType")
+      );
+    } catch {
+      return false;
+    }
+  };
+  const [tests, campaigns] = await Promise.all([
+    saves("experiments", "split-traffic"),
+    saves("campaigns", "calendar"),
+  ]);
+  return tests || campaigns;
+}
+
+async function bindVersion(cms: BindCMS, options: BindDraftOptions): Promise<boolean> {
+  const { searchParams } = options;
   const param = firstParam(searchParams, DRAFT_PARAM);
   if (param === "off") return false;
   const requestHeaders = await headers();
-  const forwarded = param ?? requestHeaders.get(DRAFT_HEADER);
+  const forwarded = param ?? requestHeaders.get(VERSION_HEADER);
   const query = forwarded ? `?${DRAFT_PARAM}=${encodeURIComponent(forwarded)}` : "";
   const request = requestLike(requestHeaders as Headers, `/${query}`);
-  const pointer = request ? await allowedDraft(cms, request, policy) : null;
-  if (pointer === null) return false;
-  draftSlot().pointer = pointer;
+  const version = request ? await allowedDraft(cms, request) : null;
+  if (version === null) return false;
+  draftSlot().version = version;
   return true;
 }
 
 /**
- * The content client for this request: the draft `bindDraft` bound, or the
- * release.
+ * The content client for this request, from what `bindDraft` bound:
+ * `cms.client({ version, experiments, campaigns })` with the tests and
+ * campaigns the proxy decided, deciding nothing again. On a route the proxy
+ * didn't decide for, the visitor and the preview's moment and switched tests
+ * and campaigns decide instead. Create one per request.
+ */
+export function contentClient(cms: Pick<CMS, "client">): Client {
+  const { version, visitor, assignments } = draftSlot();
+  const options: ClientOptions = { visitor, version: version?.version ?? null };
+  if (version?.date !== undefined) options.date = version.date;
+  const experiments = over(version?.experiments, assignments?.experiments);
+  const campaigns = over(version?.campaigns, assignments?.campaigns);
+  if (experiments !== undefined) options.experiments = experiments;
+  if (campaigns !== undefined) options.campaigns = campaigns;
+  return cms.client(options);
+}
+
+/** `decided` over `preview`, name by name; `undefined` when neither has any. */
+function over(
+  preview: Readonly<Record<string, boolean>> | undefined,
+  decided: Readonly<Record<string, boolean>> | undefined,
+): Record<string, boolean> | undefined {
+  if (preview === undefined && decided === undefined) return undefined;
+  return { ...preview, ...decided };
+}
+
+/**
+ * The content client of a page on the assignments route
+ * (`app/%5Fassignments/[assignments]/[[...path]]`, which the proxy's
+ * `rewriteToAssignmentsRoute` rewrites the CMS's pages to): the current
+ * release, read as `cms.client({ experiments, campaigns })` with every test
+ * and campaign the path's segment names on or off as the proxy decided, and
+ * no visitor. The proxy decides, the page renders that, reading no request,
+ * so Next can cache it (ISR, `revalidate = 600`). A test at 0% stays off
+ * whatever the path names, and a test or a campaign the content doesn't have
+ * stays out, never an error: a 404 here would be cached under the path by
+ * Next. `null` only when the segment isn't one the proxy writes: the page
+ * answers with `notFound()`.
+ *
+ * ```tsx
+ * export const revalidate = 600;
+ * export async function generateStaticParams() {
+ *   return [];
+ * }
+ * export default async function Page({ params }) {
+ *   const { assignments, path } = await params;
+ *   const client = await assignedClient(cms, assignments);
+ *   if (!client) notFound();
+ *   …
+ * }
+ * ```
  */
-export function contentClient(cms: Pick<CMS, "forDraft" | "forRelease">): Client {
-  const pointer = activeDraftPointer();
-  return pointer ? cms.forDraft(pointer) : cms.forRelease();
+export async function assignedClient(
+  cms: Pick<CMS, "client" | "forRelease">,
+  segment: string,
+): Promise<Client | null> {
+  const parsed = parseAssignmentsSegment(segment);
+  if (parsed === null) return null;
+  const assignments: PathAssignments = await withoutDarkTests(cms, parsed);
+  return cms.client({ experiments: assignments.experiments, campaigns: assignments.campaigns });
 }