@decocms/tanstack 7.33.1 → 7.34.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/tanstack",
-  "version": "7.33.1",
+  "version": "7.34.1",
   "type": "module",
   "description": "Deco framework binding for TanStack Start + Cloudflare Workers",
   "repository": {
@@ -24,9 +24,9 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.33.1",
-    "@decocms/blocks-admin": "7.33.1",
-    "@decocms/blocks-cli": "7.33.1",
+    "@decocms/blocks": "7.34.1",
+    "@decocms/blocks-admin": "7.34.1",
+    "@decocms/blocks-cli": "7.34.1",
     "@deco-cx/warp-node": "^0.3.16",
     "fast-json-patch": "^3.1.0",
     "ws": "^8.18.0"

package/src/hooks/DecoRootLayout.tsx

@@ -2,6 +2,7 @@ import { useEffect, type ReactNode } from "react";
 import { HeadContent, Scripts, ScriptOnce } from "@tanstack/react-router";
 import { LiveControls } from "@decocms/blocks/hooks";
 import { ANALYTICS_SCRIPT } from "@decocms/blocks/sdk/analytics";
+import { DraftPreviewIndicator } from "./DraftPreviewIndicator";
 import { NavigationProgress } from "./NavigationProgress";
 import { StableOutlet } from "./StableOutlet";
 
@@ -102,6 +103,7 @@ export function DecoRootLayout({
 					<StableOutlet />
 				</main>
 				{children}
+				<DraftPreviewIndicator />
 				<LiveControls site={siteName} />
 				<ScriptOnce children={ANALYTICS_SCRIPT} />
 				<Scripts />

package/src/hooks/DraftPreviewIndicator.test.tsx

@@ -0,0 +1,60 @@
+import { RequestContext } from "@decocms/blocks/sdk/requestContext";
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { renderToString } from "react-dom/server";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { DRAFT_POINTER_BAG_KEY, DRAFT_POINTER_GLOBAL } from "../sdk/draftShared";
+import { DraftPreviewIndicator } from "./DraftPreviewIndicator";
+
+const POINTER = "abc.preview-studio.decocms.com@v1";
+
+function renderInRequest(pointer: string | null): string {
+  return RequestContext.run(new Request("https://example.com/"), () => {
+    if (pointer) RequestContext.setBag(DRAFT_POINTER_BAG_KEY, pointer);
+    return renderToString(<DraftPreviewIndicator />);
+  });
+}
+
+describe("DraftPreviewIndicator — SSR", () => {
+  it("publishes the pointer on a global so client hydration matches", () => {
+    const html = renderInRequest(POINTER);
+    expect(html).toContain(`window.${DRAFT_POINTER_GLOBAL}=`);
+    expect(html).toContain(JSON.stringify(POINTER));
+    // The chip itself fails closed — nothing visible until the client effect.
+    expect(html).not.toContain("Preview mode");
+  });
+
+  it("renders nothing when the request is not drafting", () => {
+    expect(renderInRequest(null)).toBe("");
+  });
+});
+
+describe("DraftPreviewIndicator — client", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  const win = window as unknown as Record<string, string | undefined>;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    win[DRAFT_POINTER_GLOBAL] = undefined;
+  });
+
+  it("mounts the badge from the published global (cookie-nav, no bag on the client)", () => {
+    win[DRAFT_POINTER_GLOBAL] = POINTER;
+    act(() => root.render(<DraftPreviewIndicator />));
+    expect(container.textContent).toContain("Preview mode");
+  });
+
+  it("renders nothing when no pointer is published", () => {
+    act(() => root.render(<DraftPreviewIndicator />));
+    expect(container.textContent).toBe("");
+  });
+});

package/src/hooks/DraftPreviewIndicator.tsx

@@ -0,0 +1,62 @@
+/**
+ * Preview-mode badge gate — the TanStack binding.
+ *
+ * Mounts the shared `DraftPreviewBadge` (`@decocms/blocks/preview`) only when
+ * the request is rendering a draft. `DecoRootLayout` renders it automatically,
+ * so sites get the badge on a package bump with no code change; it renders
+ * nothing at all on ordinary (published) traffic.
+ *
+ * ## Isomorphic pointer, hydration-safe
+ *
+ * TanStack Start renders this component on BOTH server and client (no RSC
+ * boundary). The pointer only exists server-side (the request bag), so:
+ *
+ *  - **Server:** read it from `RequestContext` and emit a tiny inline `<script>`
+ *    that publishes it on `window.<GLOBAL>`. Inline scripts execute during HTML
+ *    parse, before hydration.
+ *  - **Client:** `RequestContext` resolves to a no-op stub in the browser
+ *    bundle (the `browser` export condition), so the bag read returns
+ *    undefined and we fall back to `window.<GLOBAL>` — which the just-executed
+ *    inline script set to the server's value, so the hydration render computes
+ *    the SAME pointer and the `<script>` node reconciles cleanly.
+ *
+ * Reading the bag first (then the global) — rather than branching on
+ * `typeof window` — is also what makes this testable under jsdom, where
+ * `window` always exists.
+ *
+ * The badge itself starts hidden and reveals via a client effect (fails
+ * closed), so the visible chip never participates in the hydration diff.
+ */
+import { DraftPreviewBadge } from "@decocms/blocks/preview";
+import { RequestContext } from "@decocms/blocks/sdk/requestContext";
+import { DRAFT_POINTER_BAG_KEY, DRAFT_POINTER_GLOBAL } from "../sdk/draftShared";
+
+/**
+ * The active draft pointer. Server: the request bag (set by `bindRequestDraft`).
+ * Client: the bag is a stub → undefined → fall back to the published global.
+ */
+function activePointer(): string | null {
+  const fromBag = RequestContext.getBag<string>(DRAFT_POINTER_BAG_KEY);
+  if (fromBag) return fromBag;
+  if (typeof window !== "undefined") {
+    return (window as unknown as Record<string, string | undefined>)[DRAFT_POINTER_GLOBAL] ?? null;
+  }
+  return null;
+}
+
+export function DraftPreviewIndicator() {
+  const pointer = activePointer();
+  if (!pointer) return null;
+  return (
+    <>
+      {/* Publishes a JSON-encoded pointer this server resolved (not user
+          input) so the client's hydration render matches. See the module doc. */}
+      <script
+        dangerouslySetInnerHTML={{
+          __html: `window.${DRAFT_POINTER_GLOBAL}=${JSON.stringify(pointer)}`,
+        }}
+      />
+      <DraftPreviewBadge pointer={pointer} />
+    </>
+  );
+}

package/src/hooks/index.ts

@@ -4,6 +4,7 @@ export {
   SectionRenderer,
 } from "./DecoPageRenderer";
 export { DecoRootLayout, type DecoRootLayoutProps } from "./DecoRootLayout";
+export { DraftPreviewIndicator } from "./DraftPreviewIndicator";
 export { NavigationProgress } from "./NavigationProgress";
 export { StableOutlet } from "./StableOutlet";
 export { default as PreviewProviders } from "./PreviewProviders";

package/src/index.ts

@@ -14,6 +14,7 @@ export {
 export {
   DecoPageRenderer,
   DecoRootLayout,
+  DraftPreviewIndicator,
   NavigationProgress,
   PreviewProviders,
   SectionList,

package/src/sdk/draft.test.ts

@@ -0,0 +1,231 @@
+import {
+  clearDraftCache,
+  getRequestDraftOverride,
+  setDraftPreviewHosts,
+} from "@decocms/blocks/cms";
+import { RequestContext } from "@decocms/blocks/sdk/requestContext";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import {
+  applyDraftCookieAndHeaders,
+  bindRequestDraft,
+  type DraftDecision,
+  installPreviewHostsFromBlocks,
+  registerDraftOverride,
+  requestCarriesDraft,
+} from "./draft";
+import { DRAFT_POINTER_BAG_KEY } from "./draftShared";
+
+const HOST = "preview.example";
+const DRAFT_BLOCKS = { "pages-home": { title: "draft" } };
+
+function req(opts: { url?: string; host?: string; cookie?: string } = {}): Request {
+  const headers = new Headers();
+  headers.set("host", opts.host ?? HOST);
+  if (opts.cookie) headers.set("cookie", opts.cookie);
+  return new Request(opts.url ?? `https://${opts.host ?? HOST}/some/page`, { headers });
+}
+
+/** A fetch stub serving the sandbox decofile; throws if `fail`. */
+function sandboxFetch(fail = false): typeof fetch {
+  return (async () => {
+    if (fail) throw new Error("unreachable");
+    return new Response(JSON.stringify(DRAFT_BLOCKS), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    });
+  }) as unknown as typeof fetch;
+}
+
+beforeEach(() => {
+  clearDraftCache();
+  // Allowlist is globalThis-backed (the site block's previewHosts), so no env
+  // needed — this makes the feature "enabled" for the tests below.
+  setDraftPreviewHosts([HOST, "localhost:3100"]);
+});
+
+afterEach(() => {
+  setDraftPreviewHosts([]);
+});
+
+describe("requestCarriesDraft", () => {
+  it("is inert when no allowlist is configured", () => {
+    setDraftPreviewHosts([]);
+    const url = new URL(`https://${HOST}/p?__draft=abc.preview-studio.decocms.com@v1`);
+    expect(requestCarriesDraft(req({ url: url.toString() }), url)).toBe(false);
+  });
+
+  it("detects the ?__draft= entry param", () => {
+    const url = new URL(`https://${HOST}/p?__draft=abc.preview-studio.decocms.com@v1`);
+    expect(requestCarriesDraft(req({ url: url.toString() }), url)).toBe(true);
+  });
+
+  it("detects the navigation cookie (SPA nav after entry)", () => {
+    const url = new URL(`https://${HOST}/p`);
+    expect(
+      requestCarriesDraft(req({ url: url.toString(), cookie: "__deco_draft=abc.x@v1" }), url),
+    ).toBe(true);
+  });
+
+  it("is false on ?__draft=off (leaving preview)", () => {
+    const url = new URL(`https://${HOST}/p?__draft=off`);
+    expect(
+      requestCarriesDraft(req({ url: url.toString(), cookie: "__deco_draft=abc.x@v1" }), url),
+    ).toBe(false);
+  });
+
+  it("is structurally inert on a non-preview host, param or not", () => {
+    const url = new URL("https://prod.example/p?__draft=abc.x@v1");
+    expect(requestCarriesDraft(req({ url: url.toString(), host: "prod.example" }), url)).toBe(
+      false,
+    );
+  });
+});
+
+describe("bindRequestDraft", () => {
+  it("binds the resolved draft to the request bag on entry", async () => {
+    registerDraftOverride();
+    const pointer = "abc.preview-studio.decocms.com@v1";
+    const request = req({ url: `https://${HOST}/p?__draft=${pointer}` });
+
+    const decision = await RequestContext.run(request, async () => {
+      const d = await bindRequestDraft(request, sandboxFetch());
+      // loadBlocks() reads this back via the DI getter registered above.
+      expect(getRequestDraftOverride()).toEqual(DRAFT_BLOCKS);
+      return d;
+    });
+
+    expect(decision).toEqual({ previewing: true, setCookie: pointer, clearCookie: false });
+  });
+
+  it("carries the draft across navigation via the cookie (no re-set)", async () => {
+    registerDraftOverride();
+    const pointer = "abc.preview-studio.decocms.com@v1";
+    const request = req({ url: `https://${HOST}/other`, cookie: `__deco_draft=${pointer}` });
+
+    const decision = await RequestContext.run(request, () =>
+      bindRequestDraft(request, sandboxFetch()),
+    );
+
+    // previewing, but setCookie is null — the cookie is already present.
+    expect(decision).toEqual({ previewing: true, setCookie: null, clearCookie: false });
+  });
+
+  it("decodes a URL-encoded cookie so the badge pointer round-trips (no double-encode)", async () => {
+    // The cookie is written with encodeURIComponent (`:`→%3A, `@`→%40); the
+    // pointer stashed for the badge must be the DECODED value, or the badge's
+    // share link would re-encode an already-encoded string.
+    registerDraftOverride();
+    const decoded = "abc.localhost:60534@v7";
+    const request = req({
+      url: `https://${HOST}/other`,
+      cookie: `__deco_draft=${encodeURIComponent(decoded)}`,
+    });
+
+    const stored = await RequestContext.run(request, async () => {
+      await bindRequestDraft(request, sandboxFetch());
+      return RequestContext.getBag<string>(DRAFT_POINTER_BAG_KEY);
+    });
+
+    expect(stored).toBe(decoded);
+  });
+
+  it("stays previewing (uncacheable) even when the draft fails to resolve", async () => {
+    const request = req({ url: `https://${HOST}/p?__draft=abc.preview-studio.decocms.com@v1` });
+    const decision = await RequestContext.run(request, () =>
+      bindRequestDraft(request, sandboxFetch(true)),
+    );
+    expect(decision.previewing).toBe(true);
+    expect(decision.setCookie).toBe("abc.preview-studio.decocms.com@v1");
+  });
+
+  it("clears the cookie on ?__draft=off", async () => {
+    const request = req({ url: `https://${HOST}/p?__draft=off`, cookie: "__deco_draft=x@v1" });
+    const decision = await RequestContext.run(request, () => bindRequestDraft(request));
+    expect(decision).toEqual({ previewing: false, setCookie: null, clearCookie: true });
+  });
+
+  it("is inert on a non-preview host", async () => {
+    const request = req({
+      url: "https://prod.example/p?__draft=abc.x@v1",
+      host: "prod.example",
+    });
+    const decision = await RequestContext.run(request, () => bindRequestDraft(request));
+    expect(decision).toEqual({ previewing: false, setCookie: null, clearCookie: false });
+  });
+});
+
+describe("applyDraftCookieAndHeaders", () => {
+  const entry: DraftDecision = {
+    previewing: true,
+    setCookie: "abc@v1",
+    clearCookie: false,
+  };
+
+  it("sets a cross-site-iframe-safe cookie and the anti-leak headers on entry", () => {
+    const res = new Response("ok");
+    applyDraftCookieAndHeaders(res, entry);
+
+    const cookie = res.headers.get("set-cookie") ?? "";
+    expect(cookie).toContain("__deco_draft=abc%40v1"); // pointer is URL-encoded
+    expect(cookie).toContain("SameSite=None");
+    expect(cookie).toContain("Secure");
+    expect(cookie).toContain("Partitioned");
+    expect(cookie).toContain("HttpOnly");
+
+    expect(res.headers.get("cache-control")).toBe("no-store, private");
+    expect(res.headers.get("vary")).toBe("Cookie");
+    expect(res.headers.get("x-robots-tag")).toBe("noindex, nofollow");
+  });
+
+  it("expires the cookie when leaving preview", () => {
+    const res = new Response("ok");
+    applyDraftCookieAndHeaders(res, { previewing: false, setCookie: null, clearCookie: true });
+    expect(res.headers.get("set-cookie") ?? "").toContain("Max-Age=0");
+    // Not previewing → no cache/index headers.
+    expect(res.headers.get("cache-control")).toBeNull();
+  });
+
+  it("merges Cookie into an existing Vary instead of clobbering it", () => {
+    const res = new Response("ok", { headers: { Vary: "Accept-Encoding" } });
+    applyDraftCookieAndHeaders(res, { previewing: true, setCookie: null, clearCookie: false });
+    expect(res.headers.get("vary")).toBe("Accept-Encoding, Cookie");
+  });
+
+  it("leaves a Vary that already lists Cookie untouched (no token dropped)", () => {
+    const res = new Response("ok", { headers: { Vary: "Accept-Encoding, Cookie" } });
+    applyDraftCookieAndHeaders(res, { previewing: true, setCookie: null, clearCookie: false });
+    expect(res.headers.get("vary")).toBe("Accept-Encoding, Cookie");
+  });
+
+  it("does nothing for an ordinary (non-draft) response", () => {
+    const res = new Response("ok");
+    applyDraftCookieAndHeaders(res, { previewing: false, setCookie: null, clearCookie: false });
+    expect(res.headers.get("set-cookie")).toBeNull();
+    expect(res.headers.get("cache-control")).toBeNull();
+  });
+});
+
+describe("installPreviewHostsFromBlocks", () => {
+  it("installs previewHosts from the site block (either casing)", async () => {
+    setDraftPreviewHosts([]);
+    installPreviewHostsFromBlocks({ Site: { previewHosts: ["fila.vtex.app"] } });
+
+    // Verified through the wire: an allowed host now previews.
+    const request = req({
+      url: "https://fila.vtex.app/p?__draft=abc.preview-studio.decocms.com@v1",
+      host: "fila.vtex.app",
+    });
+    const url = new URL(request.url);
+    expect(requestCarriesDraft(request, url)).toBe(true);
+  });
+
+  it("ignores blocks without previewHosts", () => {
+    setDraftPreviewHosts([]);
+    installPreviewHostsFromBlocks({ site: {} });
+    const url = new URL("https://fila.vtex.app/p?__draft=x@v1");
+    expect(requestCarriesDraft(req({ url: url.toString(), host: "fila.vtex.app" }), url)).toBe(
+      false,
+    );
+  });
+});

package/src/sdk/draft.ts

@@ -0,0 +1,254 @@
+/**
+ * Draft preview — the TanStack Start / Cloudflare Workers binding.
+ *
+ * `@decocms/blocks`'s `draftSource` owns the framework-agnostic half (token
+ * parsing, origin validation, fetch, version cache, the host allowlist). This
+ * file binds a resolved draft to the current request and drives the cookie +
+ * cache/indexing headers.
+ *
+ * ## Why this is simpler than the Next.js binding
+ *
+ * The Next binding (`@decocms/nextjs`'s `draft.ts`/`draftMiddleware.ts`) fights
+ * two App Router constraints that do NOT exist here:
+ *
+ *  1. **Request scope.** App Router never enters an AsyncLocalStorage request
+ *     scope, so Next backs the per-request draft slot with React `cache()` and
+ *     has to await `ensureDraft` from the *page* (a layout's await does not gate
+ *     its children). TanStack already wraps every request in
+ *     `RequestContext.run(request, …)` (see `workerEntry.ts`), so the draft just
+ *     rides the request bag — `loadBlocks()` reads it back through the
+ *     dependency-injected getter registered by {@link registerDraftOverride}.
+ *
+ *  2. **Static-vs-dynamic rewrite.** `dynamic`/`revalidate` are static route
+ *     exports in App Router, so Next rewrites drafted requests onto an
+ *     encoded `app/%5Fdraft/…` route to escape ISR. The worker decides
+ *     cacheability per request, so a drafted request simply bypasses the edge
+ *     cache (see `requestCarriesDraft`) — no rewrite dance.
+ *
+ * Like Next, the whole feature is inert unless the site opts in: an allowlist
+ * (the site block's `previewHosts`, or the `DECO_ALLOWED_PREVIEW_HOSTS`
+ * override) must name the request's host. Upgrading the package can never be
+ * enough to start rendering unpublished content.
+ */
+
+import {
+  DRAFT_COOKIE_NAME,
+  DRAFT_QUERY_PARAM,
+  isDraftHostAllowed,
+  isDraftPreviewEnabled,
+  resolveDraftForRequest,
+  setDraftOverrideGetter,
+  setDraftPreviewHosts,
+} from "@decocms/blocks/cms";
+import { RequestContext } from "@decocms/blocks/sdk/requestContext";
+import { DRAFT_POINTER_BAG_KEY } from "./draftShared";
+
+/** RequestContext bag key the resolved draft decofile is stashed under. */
+const DRAFT_BAG_KEY = "deco:draftBlocks";
+
+/**
+ * Cookie lifetime. Short on purpose: a preview session is minutes, and a stale
+ * pointer would keep pinning an old content version. Matches the Next binding.
+ */
+const DRAFT_COOKIE_MAX_AGE = 60 * 30;
+
+// ---------------------------------------------------------------------------
+// Runtime binding (dependency injection into @decocms/blocks)
+// ---------------------------------------------------------------------------
+
+let registered = false;
+
+/**
+ * Register the request-scoped draft getter with the runtime, once.
+ *
+ * `loadBlocks()` consults `getRequestDraftOverride()` as a fallback after its
+ * own `withBlocksOverride` scope; this points that fallback at the
+ * RequestContext bag {@link bindRequestDraft} fills. Idempotent and safe to
+ * call at setup: outside a request scope `getBag` returns undefined, so
+ * `loadBlocks()` behaves exactly as before.
+ */
+export function registerDraftOverride(): void {
+  if (registered) return;
+  registered = true;
+  setDraftOverrideGetter(
+    () => RequestContext.getBag<Record<string, unknown>>(DRAFT_BAG_KEY) ?? null,
+  );
+}
+
+/**
+ * Install the site block's `previewHosts` as the draft-preview allowlist.
+ *
+ * Reads the BASE blocks (the `setBlocks()` argument / `loadBlocks()` at setup
+ * time), never the request-time merged blocks: an allowlist readable through
+ * the draft override could be rewritten by the very draft it gates.
+ * `DECO_ALLOWED_PREVIEW_HOSTS` remains an operational override that replaces
+ * this list when set. Handles both decofile shapes (`site` / `Site`), same as
+ * `withSiteGlobals`.
+ */
+export function installPreviewHostsFromBlocks(blocks: Record<string, unknown> | undefined): void {
+  const site = (blocks?.site ?? blocks?.Site) as { previewHosts?: unknown } | undefined;
+  if (Array.isArray(site?.previewHosts)) setDraftPreviewHosts(site.previewHosts);
+}
+
+// ---------------------------------------------------------------------------
+// Per-request resolution + response decoration
+// ---------------------------------------------------------------------------
+
+/**
+ * Read one cookie value out of a raw `Cookie:` header.
+ *
+ * Decodes the value — the cookie is written with `encodeURIComponent` (see
+ * `draftCookie`), and `@decocms/blocks`'s own cookie reader decodes too, so a
+ * cookie-carried pointer must round-trip identically or the badge's share link
+ * would double-encode it. Decode defensively: a malformed `%` sequence
+ * (a crafted cookie) falls back to the raw value rather than throwing and
+ * 500-ing the request.
+ */
+function readCookie(cookieHeader: string | null, name: string): string | null {
+  if (!cookieHeader) return null;
+  for (const part of cookieHeader.split(";")) {
+    const eq = part.indexOf("=");
+    if (eq === -1) continue;
+    if (part.slice(0, eq).trim() === name) {
+      const raw = part.slice(eq + 1).trim();
+      try {
+        return decodeURIComponent(raw);
+      } catch {
+        return raw;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Whether a request is in draft mode — carries a live `?__draft=` param or the
+ * navigation cookie — on a host allowed to preview.
+ *
+ * A pure, synchronous, network-free check (no fetch, no resolve): the worker
+ * uses it to keep drafted requests out of the shared edge cache *before* doing
+ * any work. Gated on `isDraftPreviewEnabled()` first, so a build without the
+ * allowlist configured is completely unaffected — a stray `?__draft=` on a
+ * production domain neither renders a draft nor even bypasses the cache.
+ */
+export function requestCarriesDraft(request: Request, url: URL): boolean {
+  if (!isDraftPreviewEnabled()) return false;
+  const host = request.headers.get("x-forwarded-host") ?? request.headers.get("host");
+  if (!isDraftHostAllowed(host)) return false;
+  const param = url.searchParams.get(DRAFT_QUERY_PARAM);
+  if (param === "off") return false;
+  if (param) return true;
+  return readCookie(request.headers.get("cookie"), DRAFT_COOKIE_NAME) !== null;
+}
+
+/** The cookie/header actions a drafted request implies for its response. */
+export interface DraftDecision {
+  /**
+   * The request is previewing (a pointer is present on an allowed host), so its
+   * response must never be cached under the shared (cookie-only) URL — even if
+   * the draft failed to resolve and the page fell back to published content.
+   */
+  previewing: boolean;
+  /** Persist this pointer in the navigation cookie (set only on `?__draft=` entry). */
+  setCookie: string | null;
+  /** Clear the navigation cookie (`?__draft=off`). */
+  clearCookie: boolean;
+}
+
+const INERT: DraftDecision = { previewing: false, setCookie: null, clearCookie: false };
+
+/**
+ * Resolve this request's draft, if any, and bind it to the RequestContext so
+ * every `loadBlocks()` in the render sees the merged decofile.
+ *
+ * Call inside `RequestContext.run`, before the page render. Returns the
+ * cookie/header decision for the worker to apply to the final response. A
+ * missing allowlist, disallowed host, or `?__draft=off` all short-circuit
+ * without touching the network; a resolve failure degrades to published but
+ * still reports `previewing: true` so the response stays uncacheable.
+ */
+export async function bindRequestDraft(
+  request: Request,
+  fetchImpl?: typeof fetch,
+): Promise<DraftDecision> {
+  if (!isDraftPreviewEnabled()) return INERT;
+
+  const url = new URL(request.url);
+  const host = request.headers.get("x-forwarded-host") ?? request.headers.get("host");
+  // Authoritative host gate — unlike Next, there is no separate middleware
+  // module graph, so this single check bounds the whole feature.
+  if (!isDraftHostAllowed(host)) return INERT;
+
+  const param = url.searchParams.get(DRAFT_QUERY_PARAM);
+  if (param === "off") return { previewing: false, setCookie: null, clearCookie: true };
+
+  const cookie = readCookie(request.headers.get("cookie"), DRAFT_COOKIE_NAME);
+  const pointer = param ?? cookie ?? null;
+  if (!pointer) return INERT;
+
+  const blocks = await resolveDraftForRequest(request, { fetchImpl });
+  if (blocks) {
+    RequestContext.setBag(DRAFT_BAG_KEY, blocks);
+    // Expose the pointer to the SSR React tree so the preview badge can render
+    // and build its share/exit links. Only when the draft actually bound —
+    // the badge means "you're looking at draft content", matching Next.
+    RequestContext.setBag(DRAFT_POINTER_BAG_KEY, pointer);
+  }
+
+  // Persist only on entry (`?__draft=`); in-preview navigation rides the cookie
+  // already present.
+  return { previewing: true, setCookie: param ?? null, clearCookie: false };
+}
+
+/** Build the `Set-Cookie` value for the draft navigation cookie. */
+function draftCookie(value: string, maxAge: number): string {
+  // SameSite=None; Secure is mandatory for the cross-site preview iframe, and
+  // Partitioned (CHIPS) keeps it working as browsers wind down unpartitioned
+  // third-party cookies. HttpOnly: the pointer is read server-side only.
+  return `${DRAFT_COOKIE_NAME}=${value}; Path=/; Max-Age=${maxAge}; HttpOnly; Secure; SameSite=None; Partitioned`;
+}
+
+/** Set a header defensively — some replayed responses seal their headers. */
+function trySet(response: Response, key: string, value: string): void {
+  try {
+    response.headers.set(key, value);
+  } catch {
+    /* sealed headers (cached replay) — best-effort */
+  }
+}
+
+/**
+ * Apply the cookie lifecycle and the cache/indexing headers a draft response
+ * requires.
+ *
+ * The caching headers are the difference between a preview and a leak: with the
+ * pointer in a cookie, a drafted response and a published one share an
+ * identical URL, so `no-store` is what stops a CDN keyed on URL alone from
+ * serving unpublished content to a real visitor. `Vary: Cookie` keeps any
+ * intermediary that does respect it from mixing the two; `X-Robots-Tag` keeps a
+ * leaked draft out of search results.
+ */
+export function applyDraftCookieAndHeaders(response: Response, decision: DraftDecision): void {
+  if (decision.clearCookie) {
+    response.headers.append("set-cookie", draftCookie("", 0));
+  } else if (decision.setCookie) {
+    response.headers.append(
+      "set-cookie",
+      draftCookie(encodeURIComponent(decision.setCookie), DRAFT_COOKIE_MAX_AGE),
+    );
+  }
+
+  if (decision.previewing) {
+    trySet(response, "cache-control", "no-store, private");
+    // Add Cookie to Vary without dropping tokens already there (e.g.
+    // Accept-Encoding). Moot under no-store, but correct for any intermediary
+    // that honours Vary anyway.
+    const existingVary = response.headers.get("vary");
+    if (!existingVary) {
+      trySet(response, "vary", "Cookie");
+    } else if (!/\bcookie\b/i.test(existingVary)) {
+      trySet(response, "vary", `${existingVary}, Cookie`);
+    }
+    trySet(response, "x-robots-tag", "noindex, nofollow");
+  }
+}

package/src/sdk/draftShared.ts

@@ -0,0 +1,16 @@
+/**
+ * Client-bundle-safe constants shared by the server-side draft binding
+ * (`./draft`, which imports the server-only `@decocms/blocks/cms`) and the
+ * isomorphic preview-badge indicator (`../hooks/DraftPreviewIndicator`, which
+ * must stay client-safe). Kept in their own module so the indicator never has
+ * to import `./draft` and drag `node:async_hooks` into the browser bundle.
+ */
+
+/** RequestContext bag key the active draft pointer is stashed under during SSR. */
+export const DRAFT_POINTER_BAG_KEY = "deco:draftPointer";
+
+/**
+ * Global the SSR pass publishes the pointer on, so the client's hydration
+ * render reads the same value (RequestContext is a no-op stub in the browser).
+ */
+export const DRAFT_POINTER_GLOBAL = "__DECO_DRAFT_POINTER__";

package/src/sdk/workerEntry.test.ts

@@ -493,3 +493,113 @@ describe("X-Cache-Segment — custom SegmentKey fields (#284)", () => {
     expect(res.headers.get("X-Cache-Segment")).toBe("desktop|sc=1|f=a,b");
   });
 });
+
+describe("draft preview (pull-based)", () => {
+  const POINTER = "abc.localhost:1234@v1";
+  const SANDBOX_URL = "http://abc.localhost:1234/_sandbox/decofile";
+  const DRAFT_BLOCKS = { "pages-home": { name: "home", path: "/", title: "DRAFTED" } };
+
+  // A serverEntry that reflects the currently-loaded home title, so a test can
+  // prove the draft override actually reached the render (not just the headers).
+  const REFLECT_ENTRY = {
+    fetch: async () => {
+      const { loadBlocks } = await import("@decocms/blocks/cms");
+      const home = (loadBlocks()["pages-home"] as { title?: string } | undefined) ?? {};
+      return new Response(home.title ?? "PUBLISHED", { status: 200 });
+    },
+  };
+
+  let realFetch: typeof fetch;
+  afterEach(async () => {
+    globalThis.fetch = realFetch;
+    const { setDraftPreviewHosts, clearDraftCache } = await import("@decocms/blocks/cms");
+    setDraftPreviewHosts([]);
+    clearDraftCache();
+    __resetKvHydrationStateForTests();
+    setBlocks({});
+  });
+
+  async function enable() {
+    const { setDraftPreviewHosts, clearDraftCache } = await import("@decocms/blocks/cms");
+    setBlocks({ "pages-home": { name: "home", path: "/", title: "PUBLISHED" } });
+    setDraftPreviewHosts(["example.com"]);
+    clearDraftCache();
+    realFetch = globalThis.fetch;
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      if (String(input) === SANDBOX_URL) {
+        return new Response(JSON.stringify(DRAFT_BLOCKS), {
+          status: 200,
+          headers: { "content-type": "application/json" },
+        });
+      }
+      throw new Error(`unexpected fetch: ${String(input)}`);
+    }) as unknown as typeof fetch;
+  }
+
+  it("binds the draft, bypasses the edge cache, and stamps the anti-leak headers", async () => {
+    await enable();
+    const worker = createDecoWorkerEntry(REFLECT_ENTRY, { observability: false });
+    const res = await worker.fetch(
+      new Request(`https://example.com/?__draft=${POINTER}`, {
+        headers: { host: "example.com" },
+      }),
+      EMPTY_ENV,
+      MOCK_CTX,
+    );
+
+    // The render saw the merged draft decofile.
+    expect(await res.text()).toBe("DRAFTED");
+    // Never cached under the shared URL.
+    expect(res.headers.get("X-Cache")).toBe("BYPASS");
+    expect(res.headers.get("Cache-Control")).toContain("no-store");
+    expect(res.headers.get("X-Robots-Tag")).toBe("noindex, nofollow");
+    // Entry persists the navigation cookie.
+    const cookie = res.headers.get("set-cookie") ?? "";
+    expect(cookie).toContain("__deco_draft=");
+    expect(cookie).toContain("SameSite=None");
+    expect(cookie).toContain("Partitioned");
+  });
+
+  it("carries the draft across navigation via the cookie alone", async () => {
+    await enable();
+    const worker = createDecoWorkerEntry(REFLECT_ENTRY, { observability: false });
+    const res = await worker.fetch(
+      new Request("https://example.com/other", {
+        headers: { host: "example.com", cookie: `__deco_draft=${POINTER}` },
+      }),
+      EMPTY_ENV,
+      MOCK_CTX,
+    );
+    expect(await res.text()).toBe("DRAFTED");
+    expect(res.headers.get("X-Cache")).toBe("BYPASS");
+  });
+
+  it("is structurally inert on a non-preview host", async () => {
+    await enable(); // allowlist = example.com only
+    const worker = createDecoWorkerEntry(REFLECT_ENTRY, { observability: false });
+    const res = await worker.fetch(
+      new Request(`https://prod.example/?__draft=${POINTER}`, {
+        headers: { host: "prod.example" },
+      }),
+      EMPTY_ENV,
+      MOCK_CTX,
+    );
+    expect(await res.text()).toBe("PUBLISHED");
+    expect(res.headers.get("X-Robots-Tag")).toBeNull();
+    expect(res.headers.get("set-cookie")).toBeNull();
+  });
+
+  it("stays inert on any host when no allowlist is configured", async () => {
+    setBlocks({ "pages-home": { name: "home", path: "/", title: "PUBLISHED" } });
+    const worker = createDecoWorkerEntry(REFLECT_ENTRY, { observability: false });
+    const res = await worker.fetch(
+      new Request(`https://example.com/?__draft=${POINTER}`, {
+        headers: { host: "example.com" },
+      }),
+      EMPTY_ENV,
+      MOCK_CTX,
+    );
+    expect(await res.text()).toBe("PUBLISHED");
+    expect(res.headers.get("X-Robots-Tag")).toBeNull();
+  });
+});

package/src/sdk/workerEntry.ts

@@ -71,6 +71,14 @@ import { type Device, isMobileUA } from "@decocms/blocks/sdk/useDevice";
 import { getRenderShellConfig } from "@decocms/blocks-admin/admin/setup";
 import { buildHtmlShell } from "@decocms/blocks-admin/sdk/htmlShell";
 import { getAppMiddleware } from "@decocms/blocks-admin/sdk/setupApps";
+import {
+  applyDraftCookieAndHeaders,
+  bindRequestDraft,
+  type DraftDecision,
+  installPreviewHostsFromBlocks,
+  registerDraftOverride,
+  requestCarriesDraft,
+} from "./draft";
 import { ensureBlocksHydrated, maybePollRevision } from "./kvHydration";
 import { DECO_POWERED_BY, installDefaultUserAgent } from "./outboundHeaders";
 
@@ -803,6 +811,22 @@ function installAutoGeoListener(): void {
   update(loadBlocks());
 }
 
+let _draftPreviewInstalled = false;
+
+/**
+ * Wire draft preview once: register the request-scoped draft getter with the
+ * runtime and keep the `previewHosts` allowlist in sync with the base decofile.
+ * Registered unconditionally (idempotent), but the feature stays fully inert
+ * until an allowlist names the request's host — see `./draft`.
+ */
+function installDraftPreviewListener(): void {
+  if (_draftPreviewInstalled) return;
+  _draftPreviewInstalled = true;
+  registerDraftOverride();
+  onChange((blocks) => installPreviewHostsFromBlocks(blocks));
+  installPreviewHostsFromBlocks(loadBlocks());
+}
+
 const IMMUTABLE_HEADERS: Record<string, string> = {
   "Cache-Control": `public, max-age=${ONE_YEAR}, immutable`,
   Vary: "Accept-Encoding",
@@ -883,6 +907,10 @@ export function createDecoWorkerEntry(
     installAutoGeoListener();
   }
 
+  // Draft preview (pull-based): getter DI + previewHosts sync. Inert unless
+  // the site opts in via `previewHosts` / DECO_ALLOWED_PREVIEW_HOSTS.
+  installDraftPreviewListener();
+
   /** Resolve the effective geo granularity for the current request. */
   function effectiveGeoKey(): "off" | "country" | "region" | "city" {
     return geoCacheKeyOpt === "auto" ? _autoGeoKey : geoCacheKeyOpt;
@@ -963,7 +991,10 @@ export function createDecoWorkerEntry(
   function isCacheable(request: Request, url: URL): boolean {
     if (request.method !== "GET") return false;
     if (isBypassPath(url.pathname)) return false;
-    if (url.searchParams.has("__deco_draft")) return false;
+    // Draft preview: never cache a request in draft mode. Keys on the real
+    // `?__draft=` param OR the navigation cookie (SPA nav after entry), gated
+    // on an allowed preview host — see requestCarriesDraft.
+    if (requestCarriesDraft(request, url)) return false;
     if (url.searchParams.has("__deco_preview")) return false;
     if (url.searchParams.has("pathTemplate")) return false;
     // Forced matcher results must never be served from (or stored in) the
@@ -1452,6 +1483,12 @@ export function createDecoWorkerEntry(
       // become no-ops.
       const identity = { requestId: "", traceId: "" };
 
+      // Draft-preview decision — resolved inside RequestContext.run (below) so
+      // the resolved decofile binds to the request bag before the render, then
+      // lifted here so the cookie + no-store/noindex headers can be stamped on
+      // the final response. Inert on non-preview builds/hosts.
+      let draftDecision: DraftDecision = { previewing: false, setCookie: null, clearCookie: false };
+
       // Wrap the entire request in a RequestContext so that all code
       // in the call stack (loaders, invoke handlers, vtexFetchWithCookies)
       // can access the request and write response headers.
@@ -1480,6 +1517,11 @@ export function createDecoWorkerEntry(
         // production request without changing global sampling rates.
         if (new URL(request.url).searchParams.has("__d")) _setDebugSampled();
 
+        // Resolve + bind any draft preview BEFORE the render, so every
+        // loadBlocks() in the call stack sees the merged draft decofile via
+        // the request bag. Cheap no-op unless the site opts in.
+        draftDecision = await bindRequestDraft(request);
+
         // Wrap inner handler in a single root span carrying our normalized
         // path/method attributes. The framework span flows BOTH ways:
         //  - via the OTLP direct-POST tracer (when DECO_OTEL_TRACES_ENDPOINT
@@ -1591,6 +1633,11 @@ export function createDecoWorkerEntry(
         }
       }
 
+      // Draft preview: persist/clear the navigation cookie and stamp the
+      // no-store/noindex headers so a drafted response is never cached under
+      // its shared (cookie-only) URL. No-op when not previewing.
+      applyDraftCookieAndHeaders(finalResponse, draftDecision);
+
       // Metrics + structured request log. Done after security headers so
       // the recorded status reflects what the client actually receives.
       // Both calls are no-ops when no meter / logger is configured.
@@ -1829,6 +1876,20 @@ export function createDecoWorkerEntry(
           ? ((caches as unknown as { default?: Cache }).default ?? null)
           : null;
 
+      // Draft preview: a drafted SPA navigation fetches its section data via
+      // this POST, carrying the draft cookie. The draft is already bound to the
+      // request bag (bindRequestDraft, above), so origin renders it — but the
+      // body-hash cache key does not vary on the cookie, so it must bypass the
+      // shared cache entirely or it would leak drafts / serve stale published.
+      if (requestCarriesDraft(request, url)) {
+        const origin = await serverEntry.fetch(request, env, ctx);
+        const resp = new Response(origin.body, origin);
+        resp.headers.set("Cache-Control", "no-store, private");
+        resp.headers.set("X-Cache", "BYPASS");
+        resp.headers.set("X-Cache-Reason", "draft-preview");
+        return resp;
+      }
+
       // Build segment once — used for logged-in check and cache key
       const sfnSegment = buildSegment ? buildSegment(request) : undefined;