@decocms/tanstack 8.0.0 → 8.1.0-next.0

package/src/sdk/workerEntry.ts

@@ -25,15 +25,20 @@
  * ```
  */
 
+import { draftPointer } from "@decocms/blocks";
 import {
   getRevision,
+  getSectionOptions,
   isBot,
   loadBlocks,
   type MatcherContext,
   onChange,
   resolveDecoPage,
+  resolveDeferredSectionFull,
   runSectionLoaders,
   runSingleSectionLoader,
+  serializeRenderJson,
+  stringifyWithoutSecrets,
 } from "@decocms/blocks/cms";
 import { DECO_MATCHERS_OVERRIDE_PARAM } from "@decocms/blocks/matchers/override";
 import { clearLoaderCache } from "@decocms/blocks/sdk/cachedLoader";
@@ -44,10 +49,19 @@ import {
   detectCacheProfile,
   edgeCacheConfig,
   getCacheProfile,
+  payloadHasTrackingParams,
   serverFnPagePath,
 } from "@decocms/blocks/sdk/cacheHeaders";
+import {
+  bindCacheStorage,
+  type CacheStorage,
+  createWebCacheStorage,
+  getCacheStorageContext,
+} from "@decocms/blocks/sdk/cacheStorage";
+import { djb2Hex } from "@decocms/blocks/sdk/djb2";
 import { isDevMode } from "@decocms/blocks/sdk/env";
 import { parseSegmentCookie, SEGMENT_COOKIE, segmentCacheToken } from "@decocms/blocks/sdk/flags";
+import { generateNonce, NONCE_BAG_KEY } from "@decocms/blocks/sdk/nonce";
 import {
   getActiveSpan,
   logRequest,
@@ -64,15 +78,37 @@ import {
 } from "@decocms/blocks/sdk/otel";
 import { setRuntimeEnv } from "@decocms/blocks/sdk/otelAdapters";
 import { parseTraceparent } from "@decocms/blocks/sdk/otelHttpTracer";
-import { loadRedirects, matchRedirect, type RedirectMap } from "@decocms/blocks/sdk/redirects";
+import {
+  loadRedirects,
+  matchExactRedirect,
+  matchPatternRedirect,
+  normalizePath,
+  type RedirectMap,
+} from "@decocms/blocks/sdk/redirects";
 import { RequestContext } from "@decocms/blocks/sdk/requestContext";
-import { cleanPathForCacheKey } from "@decocms/blocks/sdk/urlUtils";
+import { createResponseCache } from "@decocms/blocks/sdk/responseCache";
+import { cleanPathForCacheKey, hasTrackingParams } from "@decocms/blocks/sdk/urlUtils";
 import { type Device, isMobileUA } from "@decocms/blocks/sdk/useDevice";
 import { getRenderShellConfig } from "@decocms/blocks-admin/admin/setup";
+import { reconfigureAppsOnce } from "@decocms/blocks-admin/apps/autoconfig";
 import { buildHtmlShell } from "@decocms/blocks-admin/sdk/htmlShell";
 import { getAppMiddleware } from "@decocms/blocks-admin/sdk/setupApps";
+import { installUpstreamCache } from "../v8/binding";
+import { installBackgroundHook, runBackgroundTasks } from "./backgroundTasks";
+import { CSEG_BAG_KEY, CSEG_PARAM, segmentToken } from "./cdnSegment";
+import {
+  applyDraftCookieAndHeaders,
+  bindRequestDraft,
+  type DraftDecision,
+  installDecoSiteHostFromEnv,
+  installPreviewHostsFromBlocks,
+  registerDraftOverride,
+  requestCarriesDraft,
+} from "./draft";
 import { ensureBlocksHydrated, maybePollRevision } from "./kvHydration";
+import { lookupExactRedirect } from "./kvRedirects";
 import { DECO_POWERED_BY, installDefaultUserAgent } from "./outboundHeaders";
+import { type SpeculationRulesConfig, setSpeculationRules } from "./speculationRules";
 
 /**
  * Build-time identifier injected by `decoVitePlugin()` (see
@@ -187,7 +223,7 @@ export interface SegmentKey {
  * (not pulled into the client Vite build).
  */
 export interface AdminHandlers {
-  handleMeta: (request: Request) => Response;
+  handleMeta: (request: Request) => Response | Promise<Response>;
   handleDecofileRead: () => Response;
   handleDecofileReload: (request: Request) => Response | Promise<Response>;
   handleRender: (request: Request) => Response | Promise<Response>;
@@ -195,6 +231,11 @@ export interface AdminHandlers {
 }
 
 export interface DecoWorkerEntryOptions {
+  /** Choose storage once per request using the app's runtime bindings. Null disables shared storage.
+   * Omit to retain Web Cache API response caching and memory-only data caches.
+   */
+  cacheStorage?: (env: Record<string, unknown>, request: Request) => CacheStorage | null;
+
   /**
    * Admin route handlers (/live/_meta, /.decofile, /live/previews).
    * Pass the handlers from `@decocms/start/admin` here.
@@ -215,6 +256,44 @@ export interface DecoWorkerEntryOptions {
    */
   deviceSpecificKeys?: boolean;
 
+  /**
+   * Serve pages as structured per-section JSON on `?renderJson` (the mobile
+   * page-as-JSON path). Set to `false` to disable the endpoint site-wide —
+   * `?renderJson` then just renders the normal HTML page.
+   * @default true
+   */
+  renderJson?: boolean;
+
+  /**
+   * Serve the raw resolved page as JSON on `?asJson` (legacy admin-preview
+   * path). Set to `false` to disable it site-wide.
+   * @default true
+   */
+  asJson?: boolean;
+
+  /**
+   * Opt-in Speculation Rules API. When set, a `<script type="speculationrules">`
+   * is emitted in every page's <head> (via DecoRootLayout, so it's cache-safe)
+   * telling the browser to prerender/prefetch the next document on intent.
+   *
+   * Ships DISABLED (undefined). Only activate on sites whose analytics/pixel
+   * loaders are prerender-guarded (see ANALYTICS_SCRIPT / gtmScript in
+   * @decocms/blocks/sdk/analytics), otherwise a prerender can double-count.
+   * Scope candidates to hard-navigation links via `linkSelector` so client-
+   * routed `<Link>`s are excluded.
+   * @default undefined (disabled)
+   */
+  speculationRules?: SpeculationRulesConfig;
+
+  /**
+   * Cross-origin access to the `?renderJson` response. It is public page data
+   * (secrets + request-derived keys are stripped), so it defaults to open.
+   *   - unset (default) / `"*"` → any origin, without credentials (public API).
+   *   - `string[]`              → reflect a matching request Origin, *with* credentials.
+   *   - `false`                 → no CORS headers (same-origin + native apps only).
+   */
+  pageJsonCors?: string[] | "*" | false;
+
   /**
    * Build a full segment key from the incoming request.
    *
@@ -253,7 +332,6 @@ export interface DecoWorkerEntryOptions {
    * @default "PURGE_TOKEN"
    */
   purgeTokenEnv?: string | false;
-
   /**
    * Paths that should always bypass the edge cache, even if the
    * profile detector would otherwise cache them.
@@ -367,6 +445,24 @@ export interface DecoWorkerEntryOptions {
    */
   csp?: string[] | false;
 
+  /**
+   * How the `csp` directives are delivered.
+   *
+   *  - `"report-only"` (default): emitted as `Content-Security-Policy-Report-Only`.
+   *    Browsers report violations but never block — backward-compatible, zero risk.
+   *  - `"enforce"`: emitted as an enforced `Content-Security-Policy`, but ONLY on
+   *    non-cacheable (`CDN-Cache-Control: no-store`) HTML responses. A fresh nonce
+   *    is generated per request, threaded into every SSR inline `<script>` (via
+   *    `router.options.ssr.nonce` + the deco layout components) and into the
+   *    header's `script-src` (which also drops `'unsafe-inline'`). Cacheable
+   *    responses stay report-only, because a per-request nonce would desync from a
+   *    cached body and block every script. `'unsafe-eval'`, if present in the
+   *    site's `script-src`, is left untouched — remove it explicitly in your `csp`.
+   *
+   * @default "report-only"
+   */
+  cspMode?: "report-only" | "enforce";
+
   /**
    * Automatically inject Cloudflare geo data (country, region, city)
    * as internal cookies on every request so location matchers can read
@@ -444,18 +540,48 @@ export interface DecoWorkerEntryOptions {
   staticPaths?: string[];
 
   /**
-   * CDN-Cache-Control header strategy.
+   * CDN-Cache-Control header strategy — i.e. what Cloudflare's own CDN layer is
+   * allowed to do, as distinct from the Cache API this Worker manages directly.
    *
-   * - `"no-store"` (default): CDN never caches; every request invokes the Worker.
-   *   Correct when segment-based cache keys differ from the original URL.
-   * - `"match-profile"`: Set CDN-Cache-Control to a short TTL matching the
-   *   profile's edge.fresh value. Only safe when you are NOT using segment-based
-   *   cache keys (i.e., no `buildSegment` and `deviceSpecificKeys: false`).
-   * - A function: Return a CDN-Cache-Control value per profile, or `null` for no-store.
+   * The default is `"no-store"` because the Worker's cache key is a SYNTHETIC
+   * Request carrying `__seg`/`__cf_device`/`__cf_geo`/`__bot`/`__fetch`/`__abf`
+   * (see `buildCacheKey`), while the CDN keys on the raw URL and ignores `Vary`
+   * beyond `Accept-Encoding`. Letting the CDN cache by URL alone would serve
+   * desktop HTML to mobile, one region's to another, or a crawler's eager
+   * render to humans.
    *
-   * @default "no-store"
+   * - `"serverfn-segment"` (default): allow CDN caching for `/_serverFn`
+   *   requests whose URL carries a verified `__cseg` marker (see
+   *   `./cdnSegment` and `decoServerFnFetch`). The marker makes the CDN's key
+   *   equivalent to the Worker's. HTML documents keep `no-store` — the initial
+   *   navigation is a browser request with no client hook to attach a marker.
+   *
+   *   This is the default because it is inert until a marker actually arrives:
+   *   a client that never sends `__cseg` keeps getting `no-store`, so enabling
+   *   it cannot change behaviour on its own. That is what lets a site pick the
+   *   feature up from a version bump rather than a per-site change.
+   * - `"no-store"`: the CDN never caches; every request invokes the Worker.
+   *   Always correct, never fast. Set this to opt OUT.
+   * - `"match-profile"`: mirror the profile's `edge.fresh` as a CDN TTL. Sound
+   *   ONLY when the cache key is the raw URL — no `buildSegment`,
+   *   `deviceSpecificKeys: false`, `geoCacheKey: "off"`. Since
+   *   `deviceSpecificKeys` defaults to **true**, this is almost never the case;
+   *   when it isn't, the option is ignored with a warning rather than silently
+   *   cross-serving segments.
+   * - A function: return a CDN-Cache-Control value per profile, or `null` for
+   *   no-store. You own the correctness of the key/TTL pairing.
+   *
+   * Caching HTML is deliberately not covered here. It is not a header change:
+   * whatever sits in front of the Worker has to reproduce the key above, and
+   * the initial navigation has no client hook to attach a marker to.
+   *
+   * @default "serverfn-segment"
    */
-  cdnCacheControl?: "no-store" | "match-profile" | ((profile: CacheProfileName) => string | null);
+  cdnCacheControl?:
+    | "no-store"
+    | "serverfn-segment"
+    | "match-profile"
+    | ((profile: CacheProfileName) => string | null);
   /**
    * Auto-instrumentation via `instrumentWorker` is enabled by default. The
    * framework wraps the returned handler so that, when OTel env vars
@@ -674,6 +800,53 @@ export const DECO_ADMIN_FRAME_ANCESTORS: string[] = [
  */
 export const DEFAULT_FRAME_ANCESTORS_CSP = `frame-ancestors ${DECO_ADMIN_FRAME_ANCESTORS.join(" ")}`;
 
+/**
+ * Rewrite a `script-src` directive for nonce enforcement: drop `'unsafe-inline'`
+ * (a nonce makes it dead weight — and CSP ignores it once a nonce is present)
+ * and add `'nonce-<nonce>'` plus `'inline-speculation-rules'` (so the layout's
+ * `<script type="speculationrules">` still runs). `'unsafe-eval'` is left as-is.
+ */
+function hardenScriptSrc(directive: string, nonce: string): string {
+  const tokens = directive.trim().split(/\s+/).slice(1);
+  const kept = tokens.filter((t) => t.toLowerCase() !== "'unsafe-inline'");
+  for (const extra of [`'nonce-${nonce}'`, "'inline-speculation-rules'"]) {
+    if (!kept.includes(extra)) kept.push(extra);
+  }
+  return `script-src ${kept.join(" ")}`;
+}
+
+/**
+ * Build the enforced `Content-Security-Policy` value from the site's `csp`
+ * directives + the enforced `frame-ancestors`. The `script-src` directive is
+ * hardened with the request nonce (added if the site declared none). Any
+ * `frame-ancestors` the site put in `csp` is dropped in favour of the canonical
+ * enforced one.
+ */
+export function buildEnforcedCsp(
+  directives: string[],
+  frameAncestorsCsp: string,
+  nonce: string,
+): string {
+  const out: string[] = [];
+  let sawScriptSrc = false;
+  for (const directive of directives) {
+    const name = directive.trim().split(/\s+/)[0]?.toLowerCase();
+    if (name === "script-src") {
+      sawScriptSrc = true;
+      out.push(hardenScriptSrc(directive, nonce));
+    } else if (name === "frame-ancestors") {
+      // replaced by the canonical enforced frame-ancestors appended below
+    } else {
+      out.push(directive.trim());
+    }
+  }
+  if (!sawScriptSrc) {
+    out.push(`script-src 'self' 'nonce-${nonce}' 'inline-speculation-rules'`);
+  }
+  out.push(frameAncestorsCsp.trim());
+  return out.join("; ");
+}
+
 const DEFAULT_BYPASS_PATHS = ["/_build", "/deco/", "/live/", "/.decofile"];
 
 /**
@@ -723,11 +896,17 @@ function parseCookieNames(response: Response): string[] {
 /**
  * Check if ALL cookies in a response are in the safe list.
  * Returns true if the response has no cookies or only safe cookies.
+ *
+ * Fail-closed: a response that HAS a `set-cookie` we couldn't parse into names
+ * is treated as unsafe. The parser's fallback path (comma-splitting the
+ * combined header) is documented as unreliable, and the cost of the two
+ * outcomes is not symmetric — guessing "safe" here caches a personalized
+ * response into the shared edge entry.
  */
 function hasOnlySafeCookies(response: Response, safeCookieSet: Set<string>): boolean {
   if (!response.headers.has("set-cookie")) return true;
   const names = parseCookieNames(response);
-  if (names.length === 0) return true;
+  if (names.length === 0) return false;
   return names.every((name) => safeCookieSet.has(name));
 }
 
@@ -791,6 +970,15 @@ const FINGERPRINTED_ASSET_RE = /(?:\/_build)?\/assets\/.*-[a-zA-Z0-9_-]{8,}\.\w+
 // Sites that need city precision should set geoCacheKey: "city" explicitly.
 
 let _autoGeoKey: "off" | "region" = "off";
+/**
+ * Whether `_autoGeoKey` is an answer or still the pre-hydration default. It
+ * starts `"off"` and only becomes `"region"` once a decofile carrying a
+ * location matcher loads, so anything that *reports* on `"off"` (rather than
+ * just keying on it) has to wait for a non-empty decofile first. Recomputed on
+ * every change rather than latched, so a reset back to an empty decofile
+ * un-settles it.
+ */
+let _autoGeoSettled = false;
 let _autoGeoListenerInstalled = false;
 
 function installAutoGeoListener(): void {
@@ -798,11 +986,28 @@ function installAutoGeoListener(): void {
   _autoGeoListenerInstalled = true;
   const update = (blocks: Record<string, unknown>) => {
     _autoGeoKey = detectLocationMatcher(blocks) ? "region" : "off";
+    _autoGeoSettled = Object.keys(blocks).length > 0;
   };
   onChange(update);
   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",
@@ -829,6 +1034,39 @@ let _redirectMapRevision: string | null = null;
 // Factory
 // ---------------------------------------------------------------------------
 
+/**
+ * CORS headers for the `?renderJson` response, from
+ * {@link DecoWorkerEntryOptions.pageJsonCors}. `?renderJson` is public page data
+ * (secrets + request-derived keys are stripped), so the default is `"*"` — any
+ * origin, no credentials (the standard public-API CORS). `false` turns it off;
+ * a list reflects an allow-listed request Origin *with* credentials.
+ */
+function pageJsonCorsHeaders(
+  request: Request,
+  cors: string[] | "*" | false | undefined,
+): Record<string, string> {
+  if (cors === false) return {}; // explicitly disabled
+  const effective = cors ?? "*"; // default: any origin (no credentials)
+  const base = {
+    "Access-Control-Allow-Methods": "GET, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type, If-None-Match, Authorization",
+    "Access-Control-Expose-Headers": "ETag",
+  };
+  if (effective === "*") {
+    return { ...base, "Access-Control-Allow-Origin": "*" };
+  }
+  const origin = request.headers.get("origin");
+  if (origin && effective.includes(origin)) {
+    return {
+      ...base,
+      "Access-Control-Allow-Origin": origin,
+      "Access-Control-Allow-Credentials": "true",
+      Vary: "Origin",
+    };
+  }
+  return {}; // origin not allow-listed → no CORS headers
+}
+
 /**
  * Creates a Cloudflare Worker fetch handler that wraps a TanStack Start
  * server entry with intelligent edge caching.
@@ -857,15 +1095,21 @@ export function createDecoWorkerEntry(
     cacheVersionEnv = "BUILD_HASH",
     securityHeaders: securityHeadersOpt,
     csp: cspOpt,
+    cspMode = "report-only",
     autoInjectGeoCookies: geoOpt = true,
     geoCacheKey: geoCacheKeyOpt = "auto",
     safeCookies: safeCookiesOpt = DEFAULT_SAFE_COOKIES,
     staticPaths: staticPathsOpt = DEFAULT_STATIC_PATHS,
-    cdnCacheControl: cdnCacheControlOpt = "no-store",
+    cdnCacheControl: cdnCacheControlOpt = "serverfn-segment",
     observability: observabilityOpt,
     outboundUserAgent: outboundUserAgentOpt,
+    speculationRules: speculationRulesOpt,
   } = options;
 
+  // Speculation Rules — store the site-wide config in the shared singleton so
+  // DecoRootLayout (SSR) emits the tag in <head>. Inert unless the site opts in.
+  setSpeculationRules(speculationRulesOpt);
+
   // Patch global fetch once so every outbound request — apps calling
   // `fetch` directly, RequestContext.fetch, instrumentedFetch — carries a
   // User-Agent. Workers sends none by default, which WAFs on partner
@@ -883,6 +1127,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;
@@ -904,9 +1152,40 @@ export function createDecoWorkerEntry(
     return fromHeader || undefined;
   }
 
+  // Sites generated by older migration templates set `regionId` from the
+  // Cloudflare state on every request, which splits every page's cache ~27x
+  // (one copy per BR state) even when no content varies by location. The
+  // framework already does this backfill below, and only when a location
+  // matcher exists — so flag the redundant, unconditional version once.
+  let warnedGeoSegment = false;
+  /**
+   * Whether `effectiveGeoKey() === "off"` is a real answer or just the
+   * pre-hydration default. Under `geoCacheKey: "auto"` a request that lands
+   * before the decofile loads would otherwise latch the warning below and tell
+   * the team to delete a geo fallback its location matcher actually needs. An
+   * explicit `geoCacheKey` has no such race.
+   */
+  function geoKeySettled(): boolean {
+    return geoCacheKeyOpt !== "auto" || _autoGeoSettled;
+  }
   const buildSegment = rawBuildSegment
     ? (request: Request): SegmentKey => {
         const seg = rawBuildSegment(request);
+        if (
+          !warnedGeoSegment &&
+          seg.regionId &&
+          effectiveGeoKey() === "off" &&
+          geoKeySettled() &&
+          seg.regionId === readRegionFromRequest(request)
+        ) {
+          warnedGeoSegment = true;
+          console.warn(
+            `[deco] buildSegment sets regionId to the Cloudflare region ("${seg.regionId}") ` +
+              "but no website/matchers/location.ts block exists, so every page's edge cache " +
+              "is split per region for nothing. Return only the VTEX regionId from buildSegment " +
+              'and let geoCacheKey: "auto" backfill the region when a location matcher is added.',
+          );
+        }
         if (seg.regionId) return seg;
         if (effectiveGeoKey() === "off") return seg;
         const region = readRegionFromRequest(request);
@@ -916,6 +1195,10 @@ export function createDecoWorkerEntry(
 
   const safeCookieSet = new Set(safeCookiesOpt);
 
+  // One warning per worker instance, not per request — same pattern as
+  // `warnedLongMaxAge` in @decocms/blocks/sdk/cachedLoader.
+  let warnedMatchProfile = false;
+
   // Build the final security headers map (merged defaults + custom + CSP)
   const secHeaders: Record<string, string> | null = (() => {
     if (securityHeadersOpt === false) return null;
@@ -935,7 +1218,12 @@ export function createDecoWorkerEntry(
     return base;
   })();
 
-  function applySecurityHeaders(resp: Response): Response {
+  // The enforced frame-ancestors value that ends up on `Content-Security-Policy`
+  // (site override wins, else the deco default). Reused when we build the
+  // enforced nonce CSP so framing protection is preserved.
+  const frameAncestorsCsp = secHeaders?.["Content-Security-Policy"] ?? DEFAULT_FRAME_ANCESTORS_CSP;
+
+  function applySecurityHeaders(resp: Response, nonce?: string): Response {
     if (!secHeaders) return resp;
     const ct = resp.headers.get("content-type") ?? "";
     if (!ct.includes("text/html")) return resp;
@@ -943,10 +1231,45 @@ export function createDecoWorkerEntry(
     for (const [k, v] of Object.entries(secHeaders)) {
       if (!out.headers.has(k)) out.headers.set(k, v);
     }
+    // Enforced nonce CSP: enforce mode + a real nonce + a non-cacheable
+    // response only. On a cacheable response a per-request nonce baked into the
+    // (cached) body would desync from the header on the next HIT and block every
+    // script, so those stay report-only. `CDN-Cache-Control` is decided at the
+    // single response exit just before this call, so `no-store` is reliable here.
+    if (
+      cspMode === "enforce" &&
+      nonce &&
+      cspOpt &&
+      cspOpt.length > 0 &&
+      (out.headers.get("CDN-Cache-Control") ?? "").includes("no-store")
+    ) {
+      out.headers.delete("Content-Security-Policy-Report-Only");
+      out.headers.set(
+        "Content-Security-Policy",
+        buildEnforcedCsp(cspOpt, frameAncestorsCsp, nonce),
+      );
+    }
     return out;
   }
 
-  const allBypassPaths = [...(bypassPaths ?? DEFAULT_BYPASS_PATHS), ...extraBypassPaths];
+  // DEFAULT_BYPASS_PATHS is always included, even when a site passes its own
+  // `bypassPaths`. It used to be replaced, so a site adding one path silently
+  // lost `/deco/`, `/live/` and `/.decofile` — framework routes that must never
+  // be cached. Cache configuration from a site can tighten, never loosen.
+  const allBypassPaths = [
+    ...new Set([...DEFAULT_BYPASS_PATHS, ...(bypassPaths ?? []), ...extraBypassPaths]),
+  ];
+
+  // The logged-in bypass below reads `segment.loggedIn`, which only ever exists
+  // when the site supplies `buildSegment`. Without it, authenticated and
+  // anonymous visitors share one edge entry.
+  if (!rawBuildSegment) {
+    console.warn(
+      "[deco] createDecoWorkerEntry: no `buildSegment` configured — logged-in " +
+        "visitors share the anonymous edge cache entry. Required before enabling " +
+        "CDN caching.",
+    );
+  }
 
   // -- Helpers ----------------------------------------------------------------
 
@@ -963,7 +1286,12 @@ 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;
+    // A next-major draft (`?__draft=` or the `deco-draft` cookie): same rule.
+    if (draftPointer(request) !== null) 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
@@ -990,13 +1318,7 @@ export function createDecoWorkerEntry(
     return detectCacheProfile(target);
   }
 
-  const KNOWN_SEGMENT_FIELDS = new Set([
-    "device",
-    "loggedIn",
-    "salesChannel",
-    "regionId",
-    "flags",
-  ]);
+  const KNOWN_SEGMENT_FIELDS = new Set(["device", "loggedIn", "salesChannel", "regionId", "flags"]);
 
   function hashSegment(seg: SegmentKey): string {
     const parts: string[] = [seg.device];
@@ -1057,6 +1379,95 @@ export function createDecoWorkerEntry(
     return undefined;
   }
 
+  function isServerFnPathname(pathname: string): boolean {
+    return pathname.startsWith("/_serverFn/") || pathname.startsWith("/_server/");
+  }
+
+  /**
+   * Whether this `/_serverFn` request may be cached by Cloudflare's CDN.
+   *
+   * True only when the URL carries a `__cseg` marker (put there by
+   * `decoServerFnFetch` on the client) AND recomputing the segment from this
+   * request produces the same token. When it matches, the CDN's key — the raw
+   * URL — is equivalent to the Worker's synthetic key, so serving from the CDN
+   * cannot cross segments.
+   *
+   * Fail-closed on every axis: no marker (bot, curl, old client), diverging
+   * marker, forged marker, stale build, logged-in / region / sales channel, a
+   * custom segment dimension, a bot UA, or an A/B cohort cookie all keep
+   * today's `no-store`. The worst case is not caching — never a wrong response.
+   *
+   * `isBot` and the A/B cookie are checked HERE rather than inside
+   * `segmentToken` because they are request-only: the client cannot observe
+   * them, and they are exactly the two dimensions the original site-level
+   * version missed. They must use the same `isBot` / `segmentCacheToken` that
+   * `buildCacheKey` uses — keying and releasing off different predicates is how
+   * the two silently diverge.
+   */
+  function cdnCacheableServerFn(request: Request, url: URL, env: Record<string, unknown>): boolean {
+    if (!isServerFnPathname(url.pathname)) return false;
+
+    const marker = url.searchParams.get(CSEG_PARAM);
+    if (!marker) return false;
+
+    // Without buildSegment the logged-in bypass is inert (see the boot warning),
+    // so there is nothing reliable to verify the marker against.
+    if (!buildSegment) return false;
+
+    // `__bot=1` in buildCacheKey: bots render every section eagerly (~10x
+    // payload). Letting the CDN share one entry would serve that to humans, or
+    // the deferred one to crawlers.
+    if (isBot(request.headers.get("user-agent") ?? undefined)) return false;
+
+    // `__abf` in buildCacheKey: an A/B visitor must not get another cohort's
+    // cached variant.
+    if (segmentCacheToken(parseSegmentCookie(readRequestCookie(request, SEGMENT_COOKIE)))) {
+      return false;
+    }
+
+    // `__cf_geo` in buildCacheKey is a dimension the segment descriptor does not
+    // carry: it comes from `buildGeoCacheParam` (country/region/city) rather
+    // than from `buildSegment`. Fold it in so two visitors keyed differently by
+    // the Worker can never share a URL.
+    const expected = segmentToken(
+      requestSegmentDescriptor(request),
+      buildSegment(request).loggedIn === true,
+      getBuildHash(env),
+    );
+    return expected !== null && marker === expected;
+  }
+
+  /**
+   * The full set of dimensions the Worker keys this request on, as one string.
+   *
+   * MUST stay in step with `buildCacheKey` — it is the same question ("what
+   * makes this response different from another visitor's?") asked in a form
+   * that fits in a URL. A dimension present there and missing here is a
+   * cross-visitor leak, which is why both read the same helpers rather than
+   * re-deriving anything.
+   */
+  function requestSegmentDescriptor(request: Request): string {
+    if (!buildSegment) return "";
+    const parts = [hashSegment(buildSegment(request))];
+
+    const geo = buildGeoCacheParam(
+      (request as unknown as { cf?: Record<string, string> }).cf,
+      effectiveGeoKey(),
+    );
+    if (geo) parts.push(`geo=${geo}`);
+
+    return parts.join("|");
+  }
+
+  function requestCarriesTracking(url: URL): boolean {
+    if (hasTrackingParams(url.toString())) return true;
+    if (url.pathname.startsWith("/_serverFn/") || url.pathname.startsWith("/_server/")) {
+      const payload = url.searchParams.get("payload");
+      return !!payload && payloadHasTrackingParams(payload);
+    }
+    return false;
+  }
+
   function buildCacheKey(
     request: Request,
     env: Record<string, unknown>,
@@ -1116,8 +1527,13 @@ export function createDecoWorkerEntry(
     // bucket so a fetch-triggered eager response never poisons the navigation
     // (deferred) entry, and vice-versa. MUST use the same `Sec-Fetch-Dest:
     // empty` signal as isProgrammaticFetch so the key and render decisions can't
-    // diverge. `/_serverFn` (SPA-nav data) is excluded: it has its own keying
-    // and stays eager via isClientNavigation, not this bucket.
+    // diverge. `/_serverFn` (SPA-nav data) is excluded: it sends the same
+    // `Sec-Fetch-Dest: empty` but is NOT a programmatic fetch — it renders
+    // through DecoPageRenderer and so keeps the same deferred split as the
+    // document (isProgrammaticFetch bails on isClientNavigation for the same
+    // reason). It needs no bucket of its own here: its cache key is the
+    // `/_serverFn/...` pathname + canonicalized payload, which can never
+    // collide with a document entry.
     const secFetchDest = request.headers.get("sec-fetch-dest");
     const isServerFnPath =
       url.pathname.startsWith("/_serverFn/") || url.pathname.startsWith("/_server/");
@@ -1223,14 +1639,10 @@ export function createDecoWorkerEntry(
 
     const geoVariants = body.countries ?? [];
 
-    const cache = isDevMode()
-      ? null
-      : typeof caches !== "undefined"
-        ? ((caches as unknown as { default?: Cache }).default ?? null)
-        : null;
+    const cache = responseCache(request, env);
 
     if (!cache) {
-      return Response.json({ purged: [], total: 0, note: "Cache API unavailable" });
+      return Response.json({ purged: [], total: 0, note: "Cache storage unavailable" });
     }
 
     const baseUrl = new URL(request.url).origin;
@@ -1327,7 +1739,42 @@ export function createDecoWorkerEntry(
     const denied = authorizePurge(request, env);
     if (denied) return denied;
     clearLoaderCache();
-    return Response.json({ cleared: true, scope: "isolate" });
+    return Response.json({
+      cleared: true,
+      scope: "isolate",
+      ...(options.cacheStorage
+        ? { sharedStorage: "Entries expire by TTL; this endpoint clears memory only." }
+        : {}),
+    });
+  }
+
+  function responseCache(request: Request, env: Record<string, unknown>) {
+    if (isDevMode()) return null;
+    const context = getCacheStorageContext();
+    if (context?.disabled && new URL(request.url).pathname !== "/_cache/purge") return null;
+    let storage = context?.storage;
+    // Purge is authenticated before this helper runs, and needs storage even though
+    // ordinary Authorization-bearing requests bypass every shared cache.
+    if (options.cacheStorage && new URL(request.url).pathname === "/_cache/purge") {
+      try {
+        storage = options.cacheStorage(env, request);
+      } catch {
+        return null;
+      }
+    }
+    if (!options.cacheStorage) {
+      const native =
+        typeof caches !== "undefined"
+          ? (caches as unknown as { default?: Cache }).default
+          : undefined;
+      storage = native ? createWebCacheStorage(native, new URL(request.url).origin) : null;
+    }
+    return storage
+      ? createResponseCache(
+          storage,
+          JSON.stringify([new URL(request.url).origin, getBuildHash(env), getRevision()]),
+        )
+      : null;
   }
 
   // -- Admin route handler ---------------------------------------------------
@@ -1439,6 +1886,14 @@ export function createDecoWorkerEntry(
       const reqUrl = new URL(request.url);
       const method = request.method;
 
+      // Deco-hosted preview hosts (`<site>.deco.site`,
+      // `<site>.deco-cx.workers.dev`) inferred from the DECO_SITE_NAME
+      // binding. Installed before any draft
+      // gate runs (requestCarriesDraft participates in the cacheability
+      // decision below). The binding is deploy-constant, so this is an
+      // idempotent write.
+      installDecoSiteHostFromEnv(env);
+
       // Inject CF geo data as cookies for location matchers (before anything reads cookies)
       if (geoOpt) {
         request = injectGeoCookies(request);
@@ -1452,6 +1907,18 @@ 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 };
+
+      // Per-request CSP nonce (enforce mode only). Generated inside the
+      // RequestContext.run below — before the render — so SSR components and the
+      // router can read it from the bag, then lifted here so the enforced CSP
+      // header built after the render carries the same value.
+      let cspNonce: string | undefined;
+
       // 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.
@@ -1461,6 +1928,32 @@ export function createDecoWorkerEntry(
         // via getRuntimeEnv() in sdk/otelAdapters.ts.
         setRuntimeEnv(env);
 
+        // Fast-deploy: hydrate the in-memory decofile from KV on the first
+        // request per isolate (awaited, ~10-30ms once), then opportunistically
+        // poll for content changes (non-blocking, via ctx.waitUntil). No-op
+        // unless the DECO_KV binding + DECO_FAST_DEPLOY are present —
+        // non-migrated sites are unaffected.
+        //
+        // MUST come before reconfigureAppsOnce() and bindRequestDraft() below.
+        // Both read the decofile, and both are one-shot/latching:
+        //   - reconfigureAppsOnce() configures apps from the blocks it sees and
+        //     latches `reinitPromise` forever. Running it first means a
+        //     fastDeploy build (whose bundled decofile is `{}`) configures ZERO
+        //     apps, and the only recovery is setBlocks()'s onChange listener,
+        //     whose promise setBlocks drops unawaited — so the request would
+        //     proceed with no app loaders registered.
+        //   - bindRequestDraft() composes draft overrides into loadBlocks().
+        await ensureBlocksHydrated(env, ctx);
+        maybePollRevision(env, ctx);
+
+        // First-request re-configuration of apps. autoconfigApps() runs at
+        // module init (setup.ts), before `env` — and thus DECO_CRYPTO_KEY —
+        // is available, so encrypted app credentials (VTEX appKey/appToken,
+        // etc.) decrypt to null at startup. Now that env is in the ALS,
+        // getEnvVar() can reach the key; re-run configure once so apps pick up
+        // real credentials. No-op on every request after the first.
+        await reconfigureAppsOnce();
+
         // RequestContext.run already resolved request.id from the
         // inbound headers (precedence: x-request-id → cf-ray → UUID).
         // Lift it into the closure so the response-write path below has
@@ -1480,6 +1973,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
@@ -1505,6 +2003,29 @@ export function createDecoWorkerEntry(
 
             // Run app middleware (injects app state into RequestContext.bag,
             // runs registered middleware like VTEX cookie forwarding).
+            // Publish the segment token so the SSR can hand it to the browser
+            // (see sdk/cdnSegment). Only the server can compute this: region
+            // comes from `request.cf`, which the client never sees. Per-request
+            // via the RequestContext bag — a module-level global here would be
+            // the layout-cache race all over again.
+            if (buildSegment && cdnCacheControlOpt === "serverfn-segment") {
+              const token = segmentToken(
+                requestSegmentDescriptor(request),
+                buildSegment(request).loggedIn === true,
+                getBuildHash(env),
+              );
+              if (token) RequestContext.setBag(CSEG_BAG_KEY, token);
+            }
+
+            // CSP nonce (enforce mode only): produce it before the render and
+            // publish it in the bag so `createDecoRouter` (router.options.ssr.nonce)
+            // and the deco layout components pick it up while rendering. Lifted to
+            // `cspNonce` so applySecurityHeaders below stamps the matching header.
+            if (cspMode === "enforce") {
+              cspNonce = generateNonce();
+              RequestContext.setBag(NONCE_BAG_KEY, cspNonce);
+            }
+
             const appMw = getAppMiddleware();
             const innerResponse = appMw
               ? await appMw(request, () => handleRequest(request, env, ctx))
@@ -1536,7 +2057,28 @@ export function createDecoWorkerEntry(
       // invoke handlers, etc.) may independently append the same cookie.
       deduplicateSetCookies(response);
 
-      let finalResponse = applySecurityHeaders(response);
+      // `CDN-Cache-Control` is decided here, at the single response exit, so no
+      // branch can forget it. Two cases:
+      //
+      //  - `X-Cache: BYPASS` — the worker deliberately declined to cache, so
+      //    the CDN must not either. A dozen call sites set this; some deleted
+      //    the header, some didn't, and several still emitted the profile's
+      //    public `Cache-Control` (`public, s-maxage=900`) on the way out.
+      //  - header absent — a branch that returned before `dressResponse` and
+      //    expressed no opinion. `?asJson`, `?renderJson`, proxied responses and
+      //    the redirect paths all land here. Defaulting these to `no-store` is
+      //    what makes the invariant hold: an early return can only ever be
+      //    MORE restrictive than the cache layer, never accidentally public.
+      //
+      // A value already set by `dressResponse` (the cacheable path) is left
+      // alone — that is the one branch that has actually reasoned about whether
+      // the CDN key matches the worker key.
+      const bypassed = response.headers.get("X-Cache") === "BYPASS";
+      if (bypassed || !response.headers.has("CDN-Cache-Control")) {
+        response.headers.set("CDN-Cache-Control", "no-store");
+      }
+
+      let finalResponse = applySecurityHeaders(response, cspNonce);
 
       // Echo request.id + trace.id back to the client / tail worker.
       // The CF tail worker reads these headers off the response to
@@ -1591,6 +2133,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.
@@ -1627,6 +2174,21 @@ export function createDecoWorkerEntry(
   // `DECO_OTEL_*_ENDPOINT` env vars are configured, telemetry flows
   // without any change to the site's worker-entry. When the env vars are
   // absent the wrap is a no-op (no exporters created, no flush calls).
+  // `@decocms/blocks` background work (release checks, telemetry batches)
+  // queued during a request runs after its response, inside ctx.waitUntil.
+  installBackgroundHook();
+  // Next major: upstream GETs made with createInstrumentedFetch are cached
+  // with the Cache API (see ../v8/binding.ts).
+  installUpstreamCache();
+  const respond = handler.fetch;
+  handler.fetch = async (request, env, ctx) => {
+    try {
+      return await respond(request, env, ctx);
+    } finally {
+      runBackgroundTasks(ctx);
+    }
+  };
+
   return observabilityOpt === false
     ? handler
     : instrumentWorker(handler, (observabilityOpt as OtelOptions | undefined) ?? {});
@@ -1638,13 +2200,49 @@ export function createDecoWorkerEntry(
   ): Promise<Response> {
     const url = new URL(request.url);
 
-    // Fast-deploy: hydrate the in-memory decofile from KV on the first request
-    // per isolate (awaited, ~10-30ms once), then opportunistically poll for
-    // content changes (non-blocking, via ctx.waitUntil). No-op unless the
-    // DECO_KV binding is present — non-migrated sites are unaffected. Runs
-    // before admin routes so /.decofile reads reflect KV too.
-    await ensureBlocksHydrated(env, ctx);
-    maybePollRevision(env, ctx);
+    // NOTE: fast-deploy hydration does NOT run here. It must happen before
+    // `reconfigureAppsOnce()` and `bindRequestDraft()`, both of which run in
+    // the outer fetch above — see the `ensureBlocksHydrated` call there.
+
+    {
+      const segment = buildSegment?.(request);
+      const privateRequest =
+        requestCarriesDraft(request, url) ||
+        segment?.loggedIn === true ||
+        request.headers.has("authorization") ||
+        url.searchParams.has("__deco_preview") ||
+        url.searchParams.has(DECO_MATCHERS_OVERRIDE_PARAM) ||
+        request.headers.has(DECO_MATCHERS_OVERRIDE_PARAM) ||
+        url.pathname.startsWith("/live/previews") ||
+        url.pathname.startsWith("/deco/render");
+      let storage: CacheStorage | null = null;
+      try {
+        storage =
+          privateRequest || isDevMode() ? null : (options.cacheStorage?.(env, request) ?? null);
+      } catch {
+        /* Missing storage is a cache miss, never a storefront failure. */
+      }
+      bindCacheStorage({
+        storage,
+        disabled: privateRequest || isDevMode(),
+        scope: JSON.stringify([
+          new URL(request.url).origin,
+          getBuildHash(env),
+          getRevision(),
+          segment
+            ? hashSegment(segment)
+            : isMobileUA(request.headers.get("user-agent") ?? "")
+              ? "mobile"
+              : "desktop",
+          buildGeoCacheParam(
+            (request as unknown as { cf?: Record<string, string> }).cf,
+            effectiveGeoKey(),
+          ),
+          privateRequest ? crypto.randomUUID() : null,
+        ]),
+        waitUntil: (work) => ctx.waitUntil(work),
+      });
+    }
 
     // Admin routes (/_meta, /.decofile, /live/previews) — always handled first
     const adminResponse = await tryAdminRoute(request);
@@ -1672,7 +2270,15 @@ export function createDecoWorkerEntry(
       _redirectMap = loadRedirects(loadBlocks());
       _redirectMapRevision = currentRevision;
     }
-    const cmsRedirect = matchRedirect(url.pathname, _redirectMap!);
+    // Exact before glob, across BOTH sources. On a fast-deploy site the exact
+    // rules live under their own `redirect:<id>:<path>` KV keys and are absent
+    // from the decofile, so the in-memory exact hit is the non-fast-deploy
+    // case. Going straight to `matchRedirect` and only then to KV would let a
+    // glob win over an exact rule, inverting the precedence.
+    const cmsRedirect =
+      matchExactRedirect(url.pathname, _redirectMap!) ??
+      (await lookupExactRedirect(env as Record<string, unknown>, normalizePath(url.pathname))) ??
+      matchPatternRedirect(url.pathname, _redirectMap!);
     if (cmsRedirect) {
       return new Response(null, {
         status: cmsRedirect.status,
@@ -1680,8 +2286,146 @@ export function createDecoWorkerEntry(
       });
     }
 
+    // ?renderJson — structured JSON of the page for the mobile app. Lean shape
+    // ({ name, path, sections:[{ component, props }] }), each section projected
+    // through its `renderJson` export. Wins over ?asJson when both are present.
+    // CORS preflight for ?renderJson (only emits headers when pageJsonCors is set).
+    if (
+      options.renderJson !== false &&
+      request.method === "OPTIONS" &&
+      url.searchParams.has("renderJson")
+    ) {
+      return new Response(null, {
+        status: 204,
+        headers: pageJsonCorsHeaders(request, options.pageJsonCors),
+      });
+    }
+
+    if (
+      options.renderJson !== false &&
+      url.searchParams.has("renderJson") &&
+      request.method === "GET"
+    ) {
+      const basePath = url.pathname;
+      const cookies: Record<string, string> = {};
+      for (const pair of (request.headers.get("cookie") ?? "").split(";")) {
+        const [k, ...v] = pair.split("=");
+        if (k?.trim()) cookies[k.trim()] = v.join("=").trim();
+      }
+      const matcherCtx: MatcherContext = {
+        userAgent: request.headers.get("user-agent") ?? "",
+        url: url.toString(),
+        path: basePath,
+        cookies,
+        request,
+      };
+
+      // CORS for ?renderJson — off unless the site allow-lists origins via
+      // options.pageJsonCors (native apps need none; browsers get same-origin).
+      const corsHeaders = pageJsonCorsHeaders(request, options.pageJsonCors);
+
+      const page = await resolveDecoPage(basePath, matcherCtx);
+      if (!page) {
+        // Stable error envelope — the app gets a predictable "not found".
+        return Response.json(
+          { status: 404, notFound: true },
+          { status: 404, headers: corsHeaders },
+        );
+      }
+
+      // Drop web-only / app-owned sections BEFORE running their loaders so a
+      // dropped section never triggers its (expensive) VTEX call. Dual-sourced:
+      //   - the section's own `export const renderJson = false`
+      //   - the website app's renderJson.sectionsToIgnore (resolveType suffix)
+      const rjBlocks = loadBlocks();
+      const rjSite = rjBlocks["Site"] as Record<string, unknown> | undefined;
+      const rawIgnore = (rjSite?.renderJson as { sectionsToIgnore?: unknown })?.sectionsToIgnore;
+      const ignoreSuffixes = (Array.isArray(rawIgnore) ? rawIgnore : [])
+        .filter((s): s is string => typeof s === "string")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+      const isDropped = (component: string) =>
+        getSectionOptions(component)?.renderJson === false ||
+        ignoreSuffixes.some((suffix) => component.endsWith(suffix));
+      const getSectionModule = (component: string) => ({
+        renderJson: getSectionOptions(component)?.renderJson,
+      });
+
+      const jsonHeaders = {
+        ...corsHeaders,
+        "Content-Type": "application/json; charset=utf-8",
+        "Cache-Control": "public, max-age=0, must-revalidate",
+      };
+      const withEtag = (body: string): Response => {
+        // Contract-stable ETag over the serialized body: identical → 304.
+        const etag = `"rj-${djb2Hex(body)}"`;
+        if (request.headers.get("if-none-match") === etag) {
+          return new Response(null, { status: 304, headers: { ...corsHeaders, ETag: etag } });
+        }
+        return new Response(body, { headers: { ...jsonHeaders, ETag: etag } });
+      };
+
+      // Lazy single-section fetch: `?renderJson&__section=<index>` resolves ONE
+      // deferred section (the placeholder the whole-page envelope emitted) and
+      // returns its serialized `{ component, props }`.
+      const sectionParam = url.searchParams.get("__section");
+      if (sectionParam !== null) {
+        const sectionIndex = Number(sectionParam);
+        const ds = page.deferredSections.find((d) => d.index === sectionIndex);
+        if (!ds || isDropped(ds.component)) {
+          return Response.json(
+            { status: 404, notFound: true },
+            { status: 404, headers: corsHeaders },
+          );
+        }
+        const resolved = await resolveDeferredSectionFull(ds, basePath, request, matcherCtx);
+        if (!resolved) {
+          return Response.json(
+            { status: 404, notFound: true },
+            { status: 404, headers: corsHeaders },
+          );
+        }
+        const [serialized] = serializeRenderJson(
+          [{ component: resolved.component, props: resolved.props }],
+          { getSectionModule, sectionsToIgnore: ignoreSuffixes },
+        );
+        if (!serialized) {
+          return Response.json(
+            { status: 404, notFound: true },
+            { status: 404, headers: corsHeaders },
+          );
+        }
+        return withEtag(stringifyWithoutSecrets(serialized));
+      }
+
+      // Whole page: eager sections are resolved + projected inline; deferred
+      // sections become `{ component, lazyUrl }` placeholders the app fetches on
+      // demand (interleaved by their position in the page).
+      const keptSections = page.resolvedSections.filter((s) => !isDropped(s.component));
+      const enrichedSections = await runSectionLoaders(keptSections, request);
+      const lazyUrlFor = (ref: { index: number }): string => {
+        const u = new URL(url.toString());
+        u.searchParams.set("__section", String(ref.index));
+        return u.pathname + u.search;
+      };
+
+      const sections = serializeRenderJson(
+        enrichedSections.map((s) => ({ component: s.component, props: s.props, index: s.index })),
+        {
+          getSectionModule,
+          // Belt-and-suspenders: keptSections already dropped these, but the
+          // serializer re-checks so a section that slipped through is still cut.
+          sectionsToIgnore: ignoreSuffixes,
+          deferred: page.deferredSections.map((d) => ({ component: d.component, index: d.index })),
+          lazyUrlFor,
+        },
+      );
+
+      return withEtag(stringifyWithoutSecrets({ name: page.name, path: page.path, sections }));
+    }
+
     // ?asJson — return resolved page data as JSON (legacy deco compat)
-    if (url.searchParams.has("asJson") && request.method === "GET") {
+    if (options.asJson !== false && url.searchParams.has("asJson") && request.method === "GET") {
       const basePath = url.pathname;
       const cookies: Record<string, string> = {};
       for (const pair of (request.headers.get("cookie") ?? "").split(";")) {
@@ -1716,7 +2460,7 @@ export function createDecoWorkerEntry(
 
       // Merge site-wide SEO defaults into seo props
       const blocks = loadBlocks();
-      const site = blocks["Site"] as Record<string, unknown> | undefined;
+      const site = (blocks["Site"] ?? blocks["site"]) as Record<string, unknown> | undefined;
       const fullSiteSeo = (site?.seo as Record<string, unknown>) ?? {};
 
       // When SeoV2 loader ran, use its output as base (preserves key order)
@@ -1823,11 +2567,21 @@ export function createDecoWorkerEntry(
       request.method === "POST" &&
       (url.pathname.startsWith("/_serverFn/") || url.pathname.startsWith("/_server/"))
     ) {
-      const serverFnCache = isDevMode()
-        ? null
-        : typeof caches !== "undefined"
-          ? ((caches as unknown as { default?: Cache }).default ?? null)
-          : null;
+      const serverFnCache = responseCache(request, env);
+
+      // 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;
@@ -1860,7 +2614,14 @@ export function createDecoWorkerEntry(
       // work correctly. We only read the body for the cache key hash.
       const originClone = request.clone();
       const body = await request.text();
-      const bodyHash = await hashText(body);
+      // Key on the body with tracking params stripped (a deferred section's
+      // `pageUrl` carries the landing URL, so `?gclid=…` otherwise mints one
+      // entry per ad click), but never *store* a response rendered from a
+      // tracked body: it embeds that URL, and every later visitor would get it.
+      const sfnCarriesTracking = shouldStripTracking && payloadHasTrackingParams(body);
+      const bodyHash = await hashText(
+        shouldStripTracking ? canonicalizeServerFnPayloadForCacheKey(body, []) : body,
+      );
 
       // Build a synthetic GET cache key from the URL + body hash + segment
       // Includes device, salesChannel, regionId, flags — so users in
@@ -1923,7 +2684,15 @@ export function createDecoWorkerEntry(
           ctx.waitUntil(
             (async () => {
               try {
-                const bgReq = new Request(request, { body, method: "POST" });
+                // Revalidate from the canonical body, for the same reason the
+                // HTML path revalidates from the clean URL: the entry is keyed
+                // on it, and a render from the tracked body embeds that landing
+                // URL. Rendering the tracked body would only be discarded,
+                // leaving the entry stale for the rest of the SWR window.
+                const bgBody = sfnCarriesTracking
+                  ? canonicalizeServerFnPayloadForCacheKey(body, [])
+                  : body;
+                const bgReq = new Request(request, { body: bgBody, method: "POST" });
                 const bgOrigin = await serverEntry.fetch(bgReq, env, ctx);
                 if (
                   bgOrigin.status === 200 &&
@@ -1977,8 +2746,8 @@ export function createDecoWorkerEntry(
         return resp;
       }
 
-      // Store in edge cache
-      if (serverFnCache) {
+      // Store in edge cache (see sfnCarriesTracking above)
+      if (serverFnCache && !sfnCarriesTracking) {
         try {
           const ttl = sfnEdge.fresh + Math.max(sfnEdge.swr, sfnEdge.sie);
           const toStore = origin.clone();
@@ -2003,6 +2772,9 @@ export function createDecoWorkerEntry(
       for (const [k, v] of Object.entries(hdrs)) resp.headers.set(k, v);
       resp.headers.set("X-Cache", "MISS");
       resp.headers.set("X-Cache-Profile", sfnProfile);
+      // Same label the HTML path emits, so the documented probe works on a
+      // deferred section too.
+      if (sfnCarriesTracking) resp.headers.set("X-Cache-Store", "skipped-tracking");
       return resp;
     }
 
@@ -2048,6 +2820,13 @@ export function createDecoWorkerEntry(
     // Cacheable request — build segment-aware cache key
     const { key: cacheKey, segment } = buildCacheKey(request, env);
 
+    // The key drops tracking params, but the renderer sees the raw URL and
+    // embeds it (page URL, router match id, analytics payloads, pagination
+    // base URLs). Storing that response under the clean key served one ad
+    // visitor's `gclid` to everyone. Tracked requests still READ the clean
+    // entry; only clean requests WRITE it.
+    const skipStoreTracking = shouldStripTracking && requestCarriesTracking(url);
+
     // Logged-in users always bypass the cache (personalized content)
     if (segment?.loggedIn) {
       const origin = await serverEntry.fetch(request, env, ctx);
@@ -2059,11 +2838,7 @@ export function createDecoWorkerEntry(
     }
 
     // Check Cache API — disabled in local dev to avoid stale responses
-    const cache = isDevMode()
-      ? null
-      : typeof caches !== "undefined"
-        ? ((caches as unknown as { default?: Cache }).default ?? null)
-        : null;
+    const cache = responseCache(request, env);
 
     const profile = getProfile(url);
     const edgeConfig = edgeCacheConfig(profile);
@@ -2080,17 +2855,45 @@ export function createDecoWorkerEntry(
 
       // CDN-Cache-Control: controls Cloudflare's automatic CDN layer
       // (separate from Cache API which the worker manages directly).
-      if (cdnCacheControlOpt === "no-store") {
-        out.headers.set("CDN-Cache-Control", "no-store");
+      const cdnPublic = `public, max-age=${edgeConfig.fresh}`;
+      const cdnCacheable = edgeConfig.isPublic && edgeConfig.fresh > 0;
+
+      if (cdnCacheControlOpt === "serverfn-segment") {
+        // Only `/_serverFn` requests whose URL carries a verified segment
+        // marker. Everything else — including every HTML document, which has no
+        // client hook to attach a marker on the initial navigation — keeps
+        // `no-store`.
+        out.headers.set(
+          "CDN-Cache-Control",
+          cdnCacheable && cdnCacheableServerFn(request, url, env) ? cdnPublic : "no-store",
+        );
       } else if (cdnCacheControlOpt === "match-profile") {
-        if (edgeConfig.isPublic && edgeConfig.fresh > 0) {
-          out.headers.set("CDN-Cache-Control", `public, max-age=${edgeConfig.fresh}`);
-        } else {
+        // `match-profile` is only sound when the Worker's cache key is the raw
+        // URL. It almost never is: `deviceSpecificKeys` defaults to true, so
+        // every site keys on `__cf_device` even without a `buildSegment`, and a
+        // location matcher adds `__cf_geo`. Honoring the option under those
+        // conditions would serve desktop HTML to mobile, or one region's to
+        // another — silently. Refuse, and say why once.
+        const keyed =
+          buildSegment !== undefined || deviceSpecificKeys || effectiveGeoKey() !== "off";
+        if (keyed) {
+          if (!warnedMatchProfile) {
+            warnedMatchProfile = true;
+            console.warn(
+              '[deco] cdnCacheControl: "match-profile" ignored — the edge cache key is ' +
+                "segmented (buildSegment / deviceSpecificKeys / geoCacheKey), which the CDN " +
+                "cannot reproduce from the URL alone. Keeping CDN-Cache-Control: no-store.",
+            );
+          }
           out.headers.set("CDN-Cache-Control", "no-store");
+        } else {
+          out.headers.set("CDN-Cache-Control", cdnCacheable ? cdnPublic : "no-store");
         }
       } else if (typeof cdnCacheControlOpt === "function") {
         const val = cdnCacheControlOpt(profile);
         out.headers.set("CDN-Cache-Control", val ?? "no-store");
+      } else {
+        out.headers.set("CDN-Cache-Control", "no-store");
       }
 
       out.headers.set("X-Cache", xCache);
@@ -2103,7 +2906,9 @@ export function createDecoWorkerEntry(
       return out;
     }
 
-    // Helper: store a response in Cache API with the full retention window
+    // Helper: store a response in Cache API with the full retention window.
+    // Callers own the tracking decision: a response is storable iff it was
+    // rendered from the clean URL this `cacheKey` represents.
     function storeInCache(resp: Response) {
       if (!cache) return;
       try {
@@ -2123,10 +2928,46 @@ export function createDecoWorkerEntry(
       }
     }
 
+    // A tracked request must revalidate from the CLEAN URL. The renderer
+    // embeds the URL it was given, and the entry being refreshed is keyed
+    // clean — so rendering the tracked URL here is either poisoning (what this
+    // used to do) or dead weight (`storeInCache` drops it), which would leave
+    // the entry stale for the whole SWR window while every ad visitor pays a
+    // full SSR that refreshes nothing. Rendering clean costs the same fetch
+    // and actually warms the entry, so paid traffic keeps the cache alive.
+    function revalidationRequest(): Request {
+      if (!skipStoreTracking) return request;
+      const clean = new URL(cleanPathForCacheKey(url.toString()), url.origin);
+      // A GET server fn can carry the tracking inside `payload` (the page it
+      // loads), not in its own query — strip it there too, or this renders and
+      // stores the tracked page under the clean key.
+      const payload = clean.searchParams.get("payload");
+      if (
+        payload &&
+        (clean.pathname.startsWith("/_serverFn/") || clean.pathname.startsWith("/_server/"))
+      ) {
+        clean.searchParams.set("payload", canonicalizeServerFnPayloadForCacheKey(payload, []));
+      }
+      // Build the init field by field instead of passing `request` as init:
+      // whether the `new Request(url, request)` form carries `cf` over is
+      // runtime-dependent, and a location matcher reading a dropped `cf` would
+      // store a wrong-region render under a region-keyed entry. No body — this
+      // path is GET-only (every other method bypasses the cache above) — and
+      // no `signal`, so a client disconnecting mid-revalidation doesn't abort
+      // the refresh that the next visitor is going to read.
+      const cf = (request as unknown as { cf?: unknown }).cf;
+      return new Request(clean.toString(), {
+        method: request.method,
+        headers: request.headers,
+        redirect: request.redirect,
+        ...(cf ? { cf } : {}),
+      } as RequestInit);
+    }
+
     // Helper: background revalidation (fetch origin, store result)
     function revalidateInBackground() {
       ctx.waitUntil(
-        Promise.resolve(serverEntry.fetch(request, env, ctx))
+        Promise.resolve(serverEntry.fetch(revalidationRequest(), env, ctx))
           .then((origin) => {
             // Never overwrite a good entry with a degraded 200 (a critical
             // section failed) — that would poison the cache. Leave the stale
@@ -2301,7 +3142,13 @@ export function createDecoWorkerEntry(
     const cacheOrigin = origin.headers.has("set-cookie")
       ? stripSafeCookiesForCache(origin, safeCookieSet)
       : origin;
-    storeInCache(cacheOrigin);
-    return dressResponse(origin, "MISS");
+    // This render saw the tracked URL and embedded it — never store it under
+    // the clean key. The next clean visitor fills the entry.
+    if (!skipStoreTracking) storeInCache(cacheOrigin);
+    return dressResponse(
+      origin,
+      "MISS",
+      skipStoreTracking ? { "X-Cache-Store": "skipped-tracking" } : undefined,
+    );
   }
 }