@decocms/nextjs 8.5.1 → 8.6.0

package/src/drafts.ts

@@ -1,109 +1,29 @@
 /**
- * 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, 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 +49,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 +96,17 @@ 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;
+): Promise<RequestVersion | null> {
+  const read = readDraftVersion(request);
+  if (read === null) return null;
+  return (await cms.readVersion(request)) === null ? null : read;
 }
 
 /**
@@ -223,7 +131,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;