@decocms/start 1.3.6 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "1.3.6",
+  "version": "1.4.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/src/cms/applySectionConventions.ts

@@ -15,6 +15,7 @@ import {
   registerLayoutSections,
 } from "./sectionLoaders";
 import {
+  registerEagerSections,
   registerSeoSections,
   setAsyncRenderingConfig,
   getAsyncRenderingConfig,
@@ -77,6 +78,9 @@ export function applySectionConventions(input: ApplySectionConventionsInput): vo
   }
 
   if (eagerSections.length > 0) {
+    // Permanent registry — survives subsequent setAsyncRenderingConfig() calls
+    registerEagerSections(eagerSections);
+    // Also add to alwaysEager for backward compat with code that reads the config
     const existing = getAsyncRenderingConfig() ?? {};
     setAsyncRenderingConfig({
       ...existing,

package/src/cms/index.ts

@@ -41,13 +41,16 @@ export {
   evaluateMatcher,
   extractSeoFromProps,
   extractSeoFromSections,
+  cacheDeferredRawProps,
   getAsyncRenderingConfig,
+  getDeferredRawProps,
   isSeoSection,
   onBeforeResolve,
   registerBotPattern,
   registerCommerceLoader,
   registerCommerceLoaders,
   registerMatcher,
+  registerEagerSections,
   registerSeoSections,
   resolveDecoPage,
   resolvePageSections,

package/src/cms/resolve.test.ts

@@ -30,6 +30,7 @@ describe("resolveDeferredSectionFull", () => {
       component: "site/sections/ProductShelf.tsx",
       key: "site/sections/ProductShelf.tsx",
       index: 5,
+      propsHash: "test",
       rawProps: { title: "Best Sellers" },
     };
 

package/src/cms/resolve.ts

@@ -2,12 +2,14 @@ import { findPageByPath, loadBlocks } from "./loader";
 import { getOnBeforeResolveProps, getSection, registerOnBeforeResolveProps } from "./registry";
 import { isLayoutSection, runSingleSectionLoader } from "./sectionLoaders";
 import { normalizeUrlsInObject } from "../sdk/normalizeUrls";
+import { djb2Hex } from "../sdk/djb2";
 
 // globalThis-backed: share state across Vite server function split modules
 const G = globalThis as any;
 if (!G.__deco) G.__deco = {};
 if (!G.__deco.commerceLoaders) G.__deco.commerceLoaders = {};
 if (!G.__deco.customMatchers) G.__deco.customMatchers = {};
+if (!G.__deco.eagerSectionKeys) G.__deco.eagerSectionKeys = new Set<string>();
 
 // ---------------------------------------------------------------------------
 // onBeforeResolveProps helper — eagerly loads the section module if needed
@@ -69,9 +71,19 @@ export interface DeferredSection {
   key: string;
   /** Position in the original page section list. */
   index: number;
-  /** CMS-resolved props without section-loader enrichment. */
+  /**
+   * Short hash of rawProps for client-side cache busting.
+   * Keeps the serialized payload small — full rawProps are resolved
+   * server-side from the deferred props cache or page re-resolution.
+   */
+  propsHash: string;
+  /**
+   * CMS-resolved props without section-loader enrichment.
+   * @deprecated Stripped before serialization to reduce HTML payload.
+   * Only present server-side in the rawProps cache.
+   */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  rawProps: Record<string, any>;
+  rawProps?: Record<string, any>;
 }
 
 // ---------------------------------------------------------------------------
@@ -120,10 +132,15 @@ export function setAsyncRenderingConfig(config?: {
   alwaysEager?: string[];
   respectCmsLazy?: boolean;
 }): void {
+  const existing = getAsyncConfig();
+  const merged = new Set([
+    ...(existing?.alwaysEager ?? []),
+    ...(config?.alwaysEager ?? []),
+  ]);
   G.__deco.asyncConfig = {
-    respectCmsLazy: config?.respectCmsLazy ?? true,
-    foldThreshold: config?.foldThreshold ?? Infinity,
-    alwaysEager: new Set(config?.alwaysEager ?? []),
+    respectCmsLazy: config?.respectCmsLazy ?? existing?.respectCmsLazy ?? true,
+    foldThreshold: config?.foldThreshold ?? existing?.foldThreshold ?? Infinity,
+    alwaysEager: merged,
   };
 }
 
@@ -132,6 +149,64 @@ export function getAsyncRenderingConfig(): AsyncRenderingConfig | null {
   return getAsyncConfig();
 }
 
+// ---------------------------------------------------------------------------
+// Permanent eager section registry — survives setAsyncRenderingConfig() calls
+// ---------------------------------------------------------------------------
+
+/**
+ * Register sections that declared `export const eager = true`.
+ * This is a permanent registry that cannot be overwritten by
+ * subsequent calls to `setAsyncRenderingConfig()`.
+ */
+export function registerEagerSections(keys: string[]): void {
+  const set: Set<string> = G.__deco.eagerSectionKeys;
+  for (const k of keys) set.add(k);
+}
+
+function isEagerSection(key: string): boolean {
+  return (G.__deco.eagerSectionKeys as Set<string>).has(key);
+}
+
+// ---------------------------------------------------------------------------
+// Deferred rawProps cache — keeps rawProps server-side to trim HTML payload
+// ---------------------------------------------------------------------------
+
+const DEFERRED_PROPS_TTL = 120_000; // 2 minutes
+const deferredRawPropsCache = new Map<string, { rawProps: Record<string, unknown>; ts: number }>();
+
+function deferredPropsCacheKey(pagePath: string, component: string, index: number): string {
+  return `${pagePath}::${component}::${index}`;
+}
+
+export function cacheDeferredRawProps(
+  pagePath: string,
+  component: string,
+  index: number,
+  rawProps: Record<string, unknown>,
+): void {
+  const key = deferredPropsCacheKey(pagePath, component, index);
+  deferredRawPropsCache.set(key, { rawProps, ts: Date.now() });
+
+  // Lazy eviction: remove expired entries when cache grows
+  if (deferredRawPropsCache.size > 500) {
+    const now = Date.now();
+    for (const [k, v] of deferredRawPropsCache) {
+      if (now - v.ts > DEFERRED_PROPS_TTL) deferredRawPropsCache.delete(k);
+    }
+  }
+}
+
+export function getDeferredRawProps(
+  pagePath: string,
+  component: string,
+  index: number,
+): Record<string, unknown> | null {
+  const key = deferredPropsCacheKey(pagePath, component, index);
+  const entry = deferredRawPropsCache.get(key);
+  if (!entry || Date.now() - entry.ts > DEFERRED_PROPS_TTL) return null;
+  return entry.rawProps;
+}
+
 // ---------------------------------------------------------------------------
 // Bot detection — bots always receive fully eager pages for SEO
 // ---------------------------------------------------------------------------
@@ -932,6 +1007,8 @@ function shouldDeferSection(
   const finalKey = resolveFinalSectionKey(section, matcherCtx);
   if (!finalKey) return false;
 
+  // Permanent registry — `export const eager = true` cannot be clobbered
+  if (isEagerSection(finalKey)) return false;
   if (cfg.alwaysEager.has(finalKey)) return false;
   if (isLayoutSection(finalKey)) return false;
 
@@ -1024,6 +1101,7 @@ function resolveSectionShallow(
         component: rt,
         key: rt,
         index: -1,
+        propsHash: djb2Hex(JSON.stringify(rawProps)),
         rawProps: rawProps as Record<string, unknown>,
       };
     }
@@ -1241,6 +1319,14 @@ export async function resolveDecoPage(
         const deferred = resolveSectionShallow(section, ctx);
         if (deferred) {
           deferred.index = currentFlatIndex;
+
+          // Cache rawProps server-side and strip from the deferred object
+          // so they are NOT serialized into the HTML payload.
+          if (deferred.rawProps) {
+            cacheDeferredRawProps(targetPath, deferred.component, currentFlatIndex, deferred.rawProps);
+            delete deferred.rawProps;
+          }
+
           deferredSections.push(deferred);
           deferredOk = true;
         }
@@ -1441,9 +1527,16 @@ export async function resolveDeferredSectionFull(
   request: Request,
   matcherCtx?: MatcherContext,
 ): Promise<ResolvedSection | null> {
+  // rawProps may be stripped from the client payload — resolve from cache or page
+  const rawProps = ds.rawProps
+    ?? getDeferredRawProps(pagePath, ds.component, ds.index)
+    ?? await reExtractRawProps(pagePath, ds.component, ds.index, matcherCtx);
+
+  if (!rawProps) return null;
+
   const section = await resolveDeferredSection(
     ds.component,
-    ds.rawProps,
+    rawProps,
     pagePath,
     matcherCtx,
   );
@@ -1452,3 +1545,44 @@ export async function resolveDeferredSectionFull(
   const enriched = await runSingleSectionLoader(section, request);
   return normalizeUrlsInObject(enriched);
 }
+
+/**
+ * Fallback for deferred rawProps cache miss: re-resolve the page and extract
+ * rawProps for the section at the given index. Expensive but ensures correctness
+ * when the in-memory cache has been evicted (different isolate, TTL expired).
+ */
+async function reExtractRawProps(
+  pagePath: string,
+  component: string,
+  sectionIndex: number,
+  matcherCtx?: MatcherContext,
+): Promise<Record<string, unknown> | null> {
+  ensureInitialized();
+
+  const match = findPageByPath(pagePath);
+  if (!match) return null;
+
+  const { page } = match;
+  const ctx: MatcherContext = { ...matcherCtx, path: pagePath };
+
+  let rawSections: unknown[];
+  if (Array.isArray(page.sections)) {
+    rawSections = page.sections;
+  } else {
+    const rctx: ResolveContext = { matcherCtx: ctx, memo: new Map(), depth: 0 };
+    rawSections = await resolveSectionsList(page.sections, rctx);
+  }
+
+  if (sectionIndex < 0 || sectionIndex >= rawSections.length) return null;
+
+  const section = rawSections[sectionIndex];
+  const shallow = resolveSectionShallow(section, ctx);
+  if (!shallow || shallow.component !== component) return null;
+
+  // Cache for subsequent requests
+  if (shallow.rawProps) {
+    cacheDeferredRawProps(pagePath, component, sectionIndex, shallow.rawProps);
+  }
+
+  return shallow.rawProps ?? null;
+}

package/src/hooks/DecoPageRenderer.tsx

@@ -19,7 +19,7 @@ import {
   setResolvedComponent,
 } from "../cms/registry";
 import type { DeferredSection, ResolvedSection } from "../cms/resolve";
-import { djb2Hex } from "../sdk/djb2";
+
 import { SectionErrorBoundary } from "./SectionErrorFallback";
 
 type LazyComponent = ReturnType<typeof lazy>;
@@ -235,9 +235,10 @@ interface DeferredSectionWrapperProps {
   errorFallback?: ReactNode;
   loadFn: (data: {
     component: string;
-    rawProps: Record<string, unknown>;
+    rawProps?: Record<string, unknown>;
     pagePath: string;
     pageUrl?: string;
+    index?: number;
   }) => Promise<ResolvedSection | null>;
 }
 
@@ -249,8 +250,7 @@ function DeferredSectionWrapper({
   errorFallback,
   loadFn,
 }: DeferredSectionWrapperProps) {
-  const propsHash = djb2Hex(JSON.stringify(deferred.rawProps));
-  const stableKey = `${pagePath}::${deferred.component}::${deferred.index}::${propsHash}`;
+  const stableKey = `${pagePath}::${deferred.component}::${deferred.index}::${deferred.propsHash ?? ""}`;
   const [section, setSection] = useState<ResolvedSection | null>(() =>
     typeof document === "undefined" ? null : getCachedDeferredSection(stableKey),
   );
@@ -308,9 +308,9 @@ function DeferredSectionWrapper({
       const key0 = stableKey;
       loadFn({
         component: deferred.component,
-        rawProps: deferred.rawProps,
         pagePath,
         pageUrl,
+        index: deferred.index,
       })
         .then((result) => {
           if (result) deferredSectionCache.set(key0, { section: result, ts: Date.now() });
@@ -328,9 +328,9 @@ function DeferredSectionWrapper({
           const key1 = stableKey;
           loadFn({
             component: deferred.component,
-            rawProps: deferred.rawProps,
             pagePath,
             pageUrl,
+            index: deferred.index,
           })
             .then((result) => {
               if (result) deferredSectionCache.set(key1, { section: result, ts: Date.now() });
@@ -344,7 +344,7 @@ function DeferredSectionWrapper({
 
     observer.observe(el);
     return () => observer.disconnect();
-  }, [deferred.component, deferred.rawProps, pagePath, pageUrl, section, loadFn]);
+  }, [deferred.component, deferred.index, deferred.propsHash, pagePath, pageUrl, section, loadFn]);
 
   if (error) {
     const errFallback = loadedOptions?.errorFallback
@@ -402,7 +402,9 @@ function DeferredSectionSkeleton({
 }) {
   const options = getSectionOptions(deferred.component);
   if (options?.loadingFallback) {
-    return createElement(options.loadingFallback, deferred.rawProps);
+    // rawProps are no longer serialized to the client — pass empty object.
+    // LoadingFallback components should be pure layout skeletons.
+    return createElement(options.loadingFallback, deferred.rawProps ?? {});
   }
   if (fallback) return <>{fallback}</>;
   if (isDev) return <DevMissingFallbackWarning component={deferred.component} />;
@@ -466,9 +468,10 @@ interface Props {
   /** @deprecated Use deferredPromises instead (TanStack native streaming). */
   loadDeferredSectionFn?: (data: {
     component: string;
-    rawProps: Record<string, unknown>;
+    rawProps?: Record<string, unknown>;
     pagePath: string;
     pageUrl?: string;
+    index?: number;
   }) => Promise<ResolvedSection | null>;
 }
 

package/src/routes/cmsRoute.ts

@@ -27,6 +27,7 @@ import {
   getRequest,
   getRequestHeader,
   getRequestUrl,
+  setResponseHeader,
 } from "@tanstack/react-start/server";
 import { createElement } from "react";
 import { preloadSectionComponents } from "../cms/registry";
@@ -34,6 +35,7 @@ import type { DeferredSection, MatcherContext, PageSeo, ResolvedSection } from "
 import {
   extractSeoFromProps,
   extractSeoFromSections,
+  getDeferredRawProps,
   resolveDecoPage,
   resolveDeferredSection,
   resolveDeferredSectionFull,
@@ -197,7 +199,8 @@ export const loadDeferredSection = createServerFn({ method: "POST" })
     (data: unknown) =>
       data as {
         component: string;
-        rawProps: Record<string, any>;
+        /** @deprecated rawProps are now resolved server-side from the deferred props cache. */
+        rawProps?: Record<string, any>;
         pagePath: string;
         pageUrl?: string;
         /** Original position in the page section list — preserved for correct SPA ordering. */
@@ -205,7 +208,7 @@ export const loadDeferredSection = createServerFn({ method: "POST" })
       },
   )
   .handler(async (ctx) => {
-    const { component, rawProps, pagePath, pageUrl, index } = ctx.data;
+    const { component, rawProps: clientRawProps, pagePath, pageUrl, index } = ctx.data;
 
     const originRequest = getRequest();
     const serverUrl = getRequestUrl().toString();
@@ -217,6 +220,15 @@ export const loadDeferredSection = createServerFn({ method: "POST" })
       request: originRequest,
     };
 
+    // Resolve rawProps: prefer client-provided (backward compat), then server cache
+    const rawProps = clientRawProps
+      ?? (index !== undefined ? getDeferredRawProps(pagePath, component, index) : null);
+
+    if (!rawProps) {
+      console.warn(`[CMS] Deferred section cache miss: ${component} at index ${index} on ${pagePath}`);
+      return null;
+    }
+
     const section = await resolveDeferredSection(component, rawProps, pagePath, matcherCtx);
     if (!section) return null;
 
@@ -227,6 +239,12 @@ export const loadDeferredSection = createServerFn({ method: "POST" })
       headers: originRequest.headers,
     });
     const enriched = await runSingleSectionLoader(section, request);
+
+    // Signal to the worker entry that this response is safe to edge-cache.
+    // Without this header, POST _serverFn responses are passed through
+    // without caching (checkout actions, invoke mutations, etc.).
+    setResponseHeader("X-Deco-Cacheable", "true");
+
     return normalizeUrlsInObject(enriched);
   });
 
@@ -246,14 +264,16 @@ export const deferredSectionLoader = async ({
   rawProps,
   pagePath,
   pageUrl,
+  index,
 }: {
   component: string;
-  rawProps: Record<string, unknown>;
+  rawProps?: Record<string, unknown>;
   pagePath: string;
   pageUrl?: string;
+  index?: number;
 }): Promise<ResolvedSection | null> => {
   return loadDeferredSection({
-    data: { component, rawProps, pagePath, pageUrl },
+    data: { component, rawProps, pagePath, pageUrl, index },
   });
 };
 

package/src/sdk/cacheHeaders.ts

@@ -267,7 +267,6 @@ const builtinPatterns: CachePattern[] = [
     test: (p) =>
       p.startsWith("/api/") ||
       p.startsWith("/deco/") ||
-      p.startsWith("/_server") ||
       p.startsWith("/_build"),
     profile: "none",
   },

package/src/sdk/workerEntry.ts

@@ -179,7 +179,7 @@ export interface DecoWorkerEntryOptions {
   /**
    * Paths that should always bypass the edge cache, even if the
    * profile detector would otherwise cache them.
-   * Defaults include `/_server`, `/_build`, `/assets`, `/deco/`.
+   * Defaults include `/_build`, `/deco/`, `/live/`, `/.decofile`.
    */
   bypassPaths?: string[];
 
@@ -295,6 +295,63 @@ export interface DecoWorkerEntryOptions {
    * @default true
    */
   autoInjectGeoCookies?: boolean;
+
+  /**
+   * Cookie names considered "safe" for caching — these are public/anonymous
+   * cookies that do not carry per-user session or auth data.
+   *
+   * When a response contains ONLY safe cookies, it is still eligible for
+   * Cache API storage. The safe cookies are stripped from the cached copy
+   * but kept on the response served to the current user.
+   *
+   * If the response contains ANY cookie NOT in this list, the response
+   * bypasses caching entirely (existing behavior).
+   *
+   * @default DEFAULT_SAFE_COOKIES (vtex_is_session, vtex_is_anonymous, vtex_segment, _deco_bucket)
+   *
+   * @example
+   * ```ts
+   * createDecoWorkerEntry(serverEntry, {
+   *   safeCookies: [
+   *     ...DEFAULT_SAFE_COOKIES,
+   *     "my_custom_analytics_cookie",
+   *   ],
+   * });
+   * ```
+   */
+  safeCookies?: string[];
+
+  /**
+   * Additional static paths (beyond fingerprinted assets) that should
+   * receive long-lived immutable cache headers.
+   *
+   * Useful for non-fingerprinted resources like fonts that live at
+   * stable URLs (e.g., `/fonts/Lato-Regular.woff2`).
+   *
+   * @default ["/fonts/"]
+   *
+   * @example
+   * ```ts
+   * createDecoWorkerEntry(serverEntry, {
+   *   staticPaths: ["/fonts/", "/static/", "/images/icons/"],
+   * });
+   * ```
+   */
+  staticPaths?: string[];
+
+  /**
+   * CDN-Cache-Control header strategy.
+   *
+   * - `"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.
+   *
+   * @default "no-store"
+   */
+  cdnCacheControl?: "no-store" | "match-profile" | ((profile: CacheProfileName) => string | null);
 }
 
 // ---------------------------------------------------------------------------
@@ -379,7 +436,110 @@ export const DEFAULT_SECURITY_HEADERS: Record<string, string> = {
   "Cross-Origin-Opener-Policy": "same-origin-allow-popups",
 };
 
-const DEFAULT_BYPASS_PATHS = ["/_server", "/_build", "/deco/", "/live/", "/.decofile"];
+const DEFAULT_BYPASS_PATHS = ["/_build", "/deco/", "/live/", "/.decofile"];
+
+/**
+ * Cookie names that are safe for caching — they carry anonymous/public
+ * segment data, not per-user auth tokens.
+ *
+ * VTEX Intelligent Search sets `vtex_is_session` and `vtex_is_anonymous`
+ * on every response. `vtex_segment` encodes the sales channel.
+ * `_deco_bucket` is the A/B test cohort cookie.
+ */
+export const DEFAULT_SAFE_COOKIES: string[] = [
+  "vtex_is_session",
+  "vtex_is_anonymous",
+  "vtex_segment",
+  "_deco_bucket",
+];
+
+const DEFAULT_STATIC_PATHS = ["/fonts/"];
+
+/**
+ * Parse Set-Cookie header values and return cookie names.
+ */
+function parseCookieNames(response: Response): string[] {
+  const names: string[] = [];
+  // getSetCookie() returns individual Set-Cookie values (available in Workers runtime)
+  const setCookies = (response.headers as any).getSetCookie?.() as string[] | undefined;
+  if (setCookies) {
+    for (const sc of setCookies) {
+      const eqIdx = sc.indexOf("=");
+      if (eqIdx > 0) names.push(sc.slice(0, eqIdx).trim());
+    }
+  } else {
+    // Fallback: parse from combined header (less reliable but covers edge cases)
+    const combined = response.headers.get("set-cookie") ?? "";
+    for (const part of combined.split(",")) {
+      const eqIdx = part.indexOf("=");
+      if (eqIdx > 0) {
+        const name = part.slice(0, eqIdx).trim();
+        // Skip attributes like "Expires=..." that appear after semicolons
+        if (!name.includes(";") && name.length > 0) names.push(name);
+      }
+    }
+  }
+  return names;
+}
+
+/**
+ * Check if ALL cookies in a response are in the safe list.
+ * Returns true if the response has no cookies or only safe cookies.
+ */
+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;
+  return names.every((name) => safeCookieSet.has(name));
+}
+
+/**
+ * Clone a response, stripping Set-Cookie headers that match the safe list.
+ * Uses response.clone() to preserve the original body for the served response.
+ * The returned copy is intended for cache storage only.
+ */
+function stripSafeCookiesForCache(response: Response, safeCookieSet: Set<string>): Response {
+  const clone = response.clone();
+  const setCookies = (response.headers as any).getSetCookie?.() as string[] | undefined;
+  if (!setCookies || setCookies.length === 0) return clone;
+
+  // Remove all Set-Cookie headers, then re-add only unsafe ones
+  clone.headers.delete("set-cookie");
+  for (const sc of setCookies) {
+    const eqIdx = sc.indexOf("=");
+    const name = eqIdx > 0 ? sc.slice(0, eqIdx).trim() : "";
+    if (name && !safeCookieSet.has(name)) {
+      clone.headers.append("set-cookie", sc);
+    }
+  }
+  return clone;
+}
+
+/**
+ * Deduplicate Set-Cookie headers — keep only the LAST occurrence of
+ * each cookie name. Multiple layers (VTEX middleware, invoke handlers,
+ * etc.) may independently append the same cookie.
+ */
+function deduplicateSetCookies(response: Response): void {
+  const setCookies = (response.headers as any).getSetCookie?.() as string[] | undefined;
+  if (!setCookies || setCookies.length <= 1) return;
+
+  // Build map: cookie name → last Set-Cookie value
+  const seen = new Map<string, string>();
+  for (const sc of setCookies) {
+    const eqIdx = sc.indexOf("=");
+    const name = eqIdx > 0 ? sc.slice(0, eqIdx).trim() : sc;
+    seen.set(name, sc);
+  }
+
+  // If no duplicates, nothing to do
+  if (seen.size === setCookies.length) return;
+
+  response.headers.delete("set-cookie");
+  for (const sc of seen.values()) {
+    response.headers.append("set-cookie", sc);
+  }
+}
 
 const FINGERPRINTED_ASSET_RE = /(?:\/_build)?\/assets\/.*-[a-zA-Z0-9_-]{8,}\.\w+$/;
 
@@ -388,6 +548,15 @@ const IMMUTABLE_HEADERS: Record<string, string> = {
   Vary: "Accept-Encoding",
 };
 
+/** SHA-256 hex hash of a string — used for POST body cache keys. */
+async function hashText(text: string): Promise<string> {
+  const data = new TextEncoder().encode(text);
+  const buf = await crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(buf))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
 // ---------------------------------------------------------------------------
 // Factory
 // ---------------------------------------------------------------------------
@@ -421,8 +590,13 @@ export function createDecoWorkerEntry(
     securityHeaders: securityHeadersOpt,
     csp: cspOpt,
     autoInjectGeoCookies: geoOpt = true,
+    safeCookies: safeCookiesOpt = DEFAULT_SAFE_COOKIES,
+    staticPaths: staticPathsOpt = DEFAULT_STATIC_PATHS,
+    cdnCacheControl: cdnCacheControlOpt = "no-store",
   } = options;
 
+  const safeCookieSet = new Set(safeCookiesOpt);
+
   // Build the final security headers map (merged defaults + custom + CSP)
   const secHeaders: Record<string, string> | null = (() => {
     if (securityHeadersOpt === false) return null;
@@ -456,7 +630,9 @@ export function createDecoWorkerEntry(
   }
 
   function isStaticAsset(pathname: string): boolean {
-    return fingerprintedAssetPattern.test(pathname);
+    if (fingerprintedAssetPattern.test(pathname)) return true;
+    // Non-fingerprinted static paths (e.g., /fonts/)
+    return staticPathsOpt.some((sp) => pathname.startsWith(sp));
   }
 
   function isCacheable(request: Request, url: URL): boolean {
@@ -756,6 +932,10 @@ export function createDecoWorkerEntry(
       return handleRequest(request, env, ctx);
       });
 
+      // Deduplicate Set-Cookie headers — multiple layers (VTEX middleware,
+      // invoke handlers, etc.) may independently append the same cookie.
+      deduplicateSetCookies(response);
+
       return applySecurityHeaders(response);
     },
   };
@@ -835,6 +1015,168 @@ export function createDecoWorkerEntry(
         return origin;
       }
 
+      // -----------------------------------------------------------------
+      // POST _serverFn — edge-cacheable using body-hash as cache key.
+      // These carry public CMS section data (shelves, deferred sections)
+      // that benefits from edge caching despite being POST requests.
+      // -----------------------------------------------------------------
+      if (
+        request.method === "POST" &&
+        (url.pathname.startsWith("/_serverFn/") || url.pathname.startsWith("/_server/"))
+      ) {
+        const serverFnCache =
+          typeof caches !== "undefined"
+            ? ((caches as unknown as { default?: Cache }).default ?? null)
+            : null;
+
+        // Build segment once — used for logged-in check and cache key
+        const sfnSegment = buildSegment ? buildSegment(request) : undefined;
+
+        // Logged-in users always bypass — personalized content must not leak
+        if (sfnSegment?.loggedIn) {
+          const origin = await serverEntry.fetch(request, env, ctx);
+          const resp = new Response(origin.body, origin);
+          resp.headers.set("Cache-Control", "private, no-cache, no-store, must-revalidate");
+          resp.headers.set("X-Cache", "BYPASS");
+          resp.headers.set("X-Cache-Reason", "logged-in");
+          return resp;
+        }
+
+        // Clone request before consuming body — the clone goes to origin
+        // untouched so TanStack Start internals (cookie passthrough, etc.)
+        // 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);
+
+        // Build a synthetic GET cache key from the URL + body hash + segment
+        // Includes device, salesChannel, regionId, flags — so users in
+        // different regions or channels get separate cache entries.
+        const cacheKeyUrl = new URL(request.url);
+        cacheKeyUrl.searchParams.set("__body", bodyHash);
+        if (cacheVersionEnv !== false) {
+          const version = (env[cacheVersionEnv] as string) || "";
+          if (version) cacheKeyUrl.searchParams.set("__v", version);
+        }
+        if (sfnSegment) {
+          cacheKeyUrl.searchParams.set("__seg", hashSegment(sfnSegment));
+        } else if (deviceSpecificKeys) {
+          const device = isMobileUA(request.headers.get("user-agent") ?? "") ? "mobile" : "desktop";
+          cacheKeyUrl.searchParams.set("__cf_device", device);
+        }
+        // Include CF geo data so location-based content doesn't leak across geos
+        const cf = (request as unknown as { cf?: Record<string, string> }).cf;
+        if (cf) {
+          const geoParts: string[] = [];
+          if (cf.country) geoParts.push(cf.country);
+          if (cf.region) geoParts.push(cf.region);
+          if (cf.city) geoParts.push(cf.city);
+          if (geoParts.length) cacheKeyUrl.searchParams.set("__cf_geo", geoParts.join("|"));
+        }
+        const sfnCacheKey = new Request(cacheKeyUrl.toString(), { method: "GET" });
+
+        // Use "listing" profile for server function responses
+        const sfnProfile: CacheProfileName = "listing";
+        const sfnEdge = edgeCacheConfig(sfnProfile);
+
+        // Check edge cache
+        let sfnCached: Response | undefined;
+        if (serverFnCache) {
+          try {
+            sfnCached = await serverFnCache.match(sfnCacheKey) ?? undefined;
+          } catch { /* Cache API unavailable */ }
+        }
+
+        if (sfnCached && sfnEdge.fresh > 0) {
+          const storedAt = Number(sfnCached.headers.get("X-Deco-Stored-At") || "0");
+          const ageSec = storedAt > 0 ? (Date.now() - storedAt) / 1000 : Infinity;
+
+          if (ageSec < sfnEdge.fresh) {
+            const out = new Response(sfnCached.body, sfnCached);
+            const hdrs = cacheHeaders(sfnProfile);
+            for (const [k, v] of Object.entries(hdrs)) out.headers.set(k, v);
+            out.headers.set("X-Cache", "HIT");
+            out.headers.set("X-Cache-Profile", sfnProfile);
+            return out;
+          }
+
+          if (ageSec < sfnEdge.fresh + sfnEdge.swr) {
+            // Stale-while-revalidate: serve stale, refresh in background
+            ctx.waitUntil(
+              (async () => {
+                try {
+                  const bgReq = new Request(request, { body, method: "POST" });
+                  const bgOrigin = await serverEntry.fetch(bgReq, env, ctx);
+                  if (
+                    bgOrigin.status === 200 &&
+                    bgOrigin.headers.get("X-Deco-Cacheable") === "true" &&
+                    !bgOrigin.headers.has("set-cookie") &&
+                    serverFnCache
+                  ) {
+                    const ttl = sfnEdge.fresh + Math.max(sfnEdge.swr, sfnEdge.sie);
+                    const toStore = bgOrigin.clone();
+                    toStore.headers.set("Cache-Control", `public, max-age=${ttl}`);
+                    toStore.headers.set("X-Deco-Stored-At", String(Date.now()));
+                    toStore.headers.delete("CDN-Cache-Control");
+                    toStore.headers.delete("X-Deco-Cacheable");
+                    await serverFnCache.put(sfnCacheKey, toStore);
+                  }
+                } catch { /* background revalidation failed */ }
+              })(),
+            );
+            const out = new Response(sfnCached.body, sfnCached);
+            const hdrs = cacheHeaders(sfnProfile);
+            for (const [k, v] of Object.entries(hdrs)) out.headers.set(k, v);
+            out.headers.set("X-Cache", "STALE-HIT");
+            out.headers.set("X-Cache-Profile", sfnProfile);
+            out.headers.set("X-Cache-Age", String(Math.round(ageSec)));
+            return out;
+          }
+        }
+
+        // Cache MISS — fetch origin with the body we already read
+        const origin = await serverEntry.fetch(originClone, env, ctx);
+
+        // Only cache responses explicitly marked as cacheable by the handler
+        // (loadDeferredSection sets X-Deco-Cacheable: true). Checkout actions,
+        // invoke mutations, and other server functions are passed through.
+        const isCacheableResponse =
+          origin.headers.get("X-Deco-Cacheable") === "true" &&
+          !origin.headers.has("set-cookie") &&
+          origin.status === 200;
+
+        if (!isCacheableResponse) {
+          const resp = new Response(origin.body, origin);
+          resp.headers.delete("X-Deco-Cacheable");
+          resp.headers.set("X-Cache", "BYPASS");
+          resp.headers.set("X-Cache-Reason", origin.headers.has("set-cookie")
+            ? "set-cookie"
+            : "not-cacheable");
+          return resp;
+        }
+
+        // Store in edge cache
+        if (serverFnCache) {
+          try {
+            const ttl = sfnEdge.fresh + Math.max(sfnEdge.swr, sfnEdge.sie);
+            const toStore = origin.clone();
+            toStore.headers.set("Cache-Control", `public, max-age=${ttl}`);
+            toStore.headers.set("X-Deco-Stored-At", String(Date.now()));
+            toStore.headers.delete("CDN-Cache-Control");
+            toStore.headers.delete("X-Deco-Cacheable");
+            ctx.waitUntil(serverFnCache.put(sfnCacheKey, toStore));
+          } catch { /* Cache API unavailable */ }
+        }
+
+        const resp = new Response(origin.body, origin);
+        resp.headers.delete("X-Deco-Cacheable");
+        const hdrs = cacheHeaders(sfnProfile);
+        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);
+        return resp;
+      }
+
       // Non-cacheable requests — pass through but protect against accidental caching
       if (!isCacheable(request, url)) {
         const origin = await serverEntry.fetch(request, env, ctx);
@@ -850,10 +1192,28 @@ export function createDecoWorkerEntry(
         }
 
         const resp = new Response(origin.body, origin);
+
+        // Responses with private Set-Cookie headers carry per-user tokens —
+        // never expose them with public cache headers.
+        // Safe/public cookies (e.g., vtex_is_session) are allowed through.
+        if (origin.headers.has("set-cookie") && !hasOnlySafeCookies(origin, safeCookieSet)) {
+          resp.headers.set("Cache-Control", "private, no-cache, no-store, must-revalidate");
+          resp.headers.delete("CDN-Cache-Control");
+          resp.headers.set("X-Cache", "BYPASS");
+          resp.headers.set("X-Cache-Reason", "private-set-cookie");
+          return resp;
+        }
+
+        // Set cache headers from the detected profile so the response
+        // is explicit about cacheability (avoids ambiguous empty header).
+        const hdrsNc = cacheHeaders(profile);
+        for (const [k, v] of Object.entries(hdrsNc)) resp.headers.set(k, v);
+
         const reason = request.method !== "GET"
           ? `method:${request.method}`
           : "bypass-path";
         resp.headers.set("X-Cache", "BYPASS");
+        resp.headers.set("X-Cache-Profile", profile);
         resp.headers.set("X-Cache-Reason", reason);
         return resp;
       }
@@ -885,7 +1245,22 @@ export function createDecoWorkerEntry(
         const out = new Response(resp.body, resp);
         const hdrs = cacheHeaders(profile);
         for (const [k, v] of Object.entries(hdrs)) out.headers.set(k, v);
-        out.headers.set("CDN-Cache-Control", "no-store");
+
+        // 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");
+        } else if (cdnCacheControlOpt === "match-profile") {
+          if (edgeConfig.isPublic && edgeConfig.fresh > 0) {
+            out.headers.set("CDN-Cache-Control", `public, max-age=${edgeConfig.fresh}`);
+          } else {
+            out.headers.set("CDN-Cache-Control", "no-store");
+          }
+        } else if (typeof cdnCacheControlOpt === "function") {
+          const val = cdnCacheControlOpt(profile);
+          out.headers.set("CDN-Cache-Control", val ?? "no-store");
+        }
+
         out.headers.set("X-Cache", xCache);
         out.headers.set("X-Cache-Profile", profile);
         if (segment) out.headers.set("X-Cache-Segment", hashSegment(segment));
@@ -917,8 +1292,15 @@ export function createDecoWorkerEntry(
       function revalidateInBackground() {
         ctx.waitUntil(
           Promise.resolve(serverEntry.fetch(request, env, ctx)).then((origin) => {
-            if (origin.status === 200 && !origin.headers.has("set-cookie")) {
-              storeInCache(origin);
+            if (origin.status === 200) {
+              // Only cache if response has no cookies or only safe cookies.
+              // Strip safe cookies from the cached copy.
+              if (hasOnlySafeCookies(origin, safeCookieSet)) {
+                const cleanOrigin = origin.headers.has("set-cookie")
+                  ? stripSafeCookiesForCache(origin, safeCookieSet)
+                  : origin;
+                storeInCache(cleanOrigin);
+              }
             }
           }).catch(() => {
             // Background revalidation failed — stale entry stays until SIE expires
@@ -998,14 +1380,16 @@ export function createDecoWorkerEntry(
         return resp;
       }
 
-      // Responses with Set-Cookie must never be cached — they carry
-      // per-user session/auth tokens that would leak to other users.
-      if (origin.headers.has("set-cookie")) {
+      // Responses with private Set-Cookie headers must never be cached —
+      // they carry per-user session/auth tokens that would leak to other users.
+      // Safe/public cookies (IS session, segment, etc.) are stripped from the
+      // cached copy but kept on the response served to the current user.
+      if (origin.headers.has("set-cookie") && !hasOnlySafeCookies(origin, safeCookieSet)) {
         const resp = new Response(origin.body, origin);
         resp.headers.set("Cache-Control", "private, no-cache, no-store, must-revalidate");
         resp.headers.delete("CDN-Cache-Control");
         resp.headers.set("X-Cache", "BYPASS");
-        resp.headers.set("X-Cache-Reason", "set-cookie");
+        resp.headers.set("X-Cache-Reason", "private-set-cookie");
         appendResourceHints(resp);
         return resp;
       }
@@ -1025,7 +1409,12 @@ export function createDecoWorkerEntry(
       // dressResponse() calls new Response(resp.body, resp) which locks
       // the ReadableStream. Calling clone() on a locked body corrupts
       // the stream in Workers runtime, causing Error 1101.
-      storeInCache(origin);
+      // Strip safe cookies from the cached copy so they don't leak
+      // to other users, but the current user still gets them.
+      const cacheOrigin = origin.headers.has("set-cookie")
+        ? stripSafeCookiesForCache(origin, safeCookieSet)
+        : origin;
+      storeInCache(cacheOrigin);
       return dressResponse(origin, "MISS");
   }
 }

package/src/vite/plugin.js

@@ -131,12 +131,40 @@ export function decoVitePlugin() {
                 ) {
                   return "vendor-react";
                 }
+
+                // TanStack Router — client-side router (always needed)
                 if (
                   id.includes("@tanstack/react-router") ||
-                  id.includes("@tanstack/start")
+                  id.includes("@tanstack/router-core")
+                ) {
+                  return "vendor-router";
+                }
+
+                // TanStack Start — specific checks before broad catch-all
+                // (react-start-client includes "react-start" so must come first)
+                if (
+                  id.includes("@tanstack/react-start-client") ||
+                  id.includes("@tanstack/start-client-core")
+                ) {
+                  return "vendor-router";
+                }
+                // Server-only TanStack packages — let Rollup tree-shake
+                if (
+                  id.includes("@tanstack/react-start-server") ||
+                  id.includes("@tanstack/start-server-core")
                 ) {
+                  return undefined;
+                }
+                // Remaining @tanstack/start (storage-context, plugin-core, etc.)
+                if (id.includes("@tanstack/start")) {
                   return "vendor-router";
                 }
+
+                // isbot — server-only (bot detection in resolve.ts)
+                if (id.includes("node_modules/isbot")) {
+                  return undefined;
+                }
+
                 if (id.includes("@tanstack/react-query")) {
                   return "vendor-query";
                 }