@decocms/tanstack 7.22.2 → 7.24.0

package/package.json

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

package/src/routes/cmsRoute.ts

@@ -21,20 +21,17 @@
  * ```
  */
 
-import { createServerFn } from "@tanstack/react-start";
-import {
-  getCookies,
-  getRequest,
-  getRequestHeader,
-  getRequestUrl,
-  setCookie,
-  setResponseHeader,
-} from "@tanstack/react-start/server";
-import { createElement } from "react";
+import type {
+  DeferredSection,
+  MatcherContext,
+  PageSeo,
+  ResolvedSection,
+} from "@decocms/blocks/cms";
 import {
   extractSeoFromProps,
   extractSeoFromSections,
   getDeferredRawProps,
+  getDegradedSections,
   getSiteSeo,
   preloadSectionComponents,
   reExtractRawProps,
@@ -44,13 +41,6 @@ import {
   runSectionLoaders,
   runSingleSectionLoader,
 } from "@decocms/blocks/cms";
-import type { DeferredSection, MatcherContext, PageSeo, ResolvedSection } from "@decocms/blocks/cms";
-import {
-  parseSegmentCookie,
-  SEGMENT_COOKIE,
-  serializeSegmentCookie,
-  type StoredFlag,
-} from "@decocms/blocks/sdk/flags";
 import { withTracing } from "@decocms/blocks/middleware/observability";
 import {
   type CacheProfileName,
@@ -58,8 +48,24 @@ import {
   detectCacheProfile,
   routeCacheDefaults,
 } from "@decocms/blocks/sdk/cacheHeaders";
+import {
+  parseSegmentCookie,
+  SEGMENT_COOKIE,
+  type StoredFlag,
+  serializeSegmentCookie,
+} from "@decocms/blocks/sdk/flags";
 import { normalizeUrlsInObject } from "@decocms/blocks/sdk/normalizeUrls";
 import { type Device, detectDevice } from "@decocms/blocks/sdk/useDevice";
+import { createServerFn } from "@tanstack/react-start";
+import {
+  getCookies,
+  getRequest,
+  getRequestHeader,
+  getRequestUrl,
+  setCookie,
+  setResponseHeader,
+} from "@tanstack/react-start/server";
+import { createElement } from "react";
 import { derivePageUrl, isClientNavigation } from "./pageUrl";
 import { dedupeGlobals, resolveSiteGlobals } from "./withSiteGlobals";
 import type { SiteGlobalRef } from "./withSiteGlobals";
@@ -221,11 +227,23 @@ async function loadCmsPageInternal(fullPath: string, resolveGlobals: boolean) {
   // Destructure seoSection out — it's an internal artifact, not serialized to client
   const { seoSection: _seo, ...pageData } = page;
 
+  // Anti-cache-poisoning: if a critical section loader failed, this page is
+  // rendering with raw/empty data. Flag the response so the edge refuses to
+  // cache the broken 200 and serves stale instead (see workerEntry.ts). Without
+  // this, the empty page would be cached as healthy for the whole retention
+  // window and stale-if-error would never fire.
+  const degraded = getDegradedSections();
+  if (degraded.length > 0) {
+    setResponseHeader("X-Deco-Degraded", "true");
+    console.warn(`[cms] page degraded — critical sections failed: ${degraded.join(", ")}`);
+  }
+
   return {
     ...pageData,
     resolvedSections: normalizeUrlsInObject(mergedSections),
     deferredSections: normalizeUrlsInObject(page.deferredSections),
     cacheProfile,
+    degraded: degraded.length > 0,
     pageUrl: urlWithSearch,
     pagePath: basePath,
     seo,
@@ -324,10 +342,20 @@ export const loadCmsHomePage = createServerFn({ method: "GET" })
 
     const { seoSection: _seo, ...pageData } = page;
 
+    // Same anti-cache-poisoning flag as loadCmsPageInternal — the homepage is the
+    // highest-traffic, most-cached route, so it must not be exempt. The actual
+    // X-Deco-Degraded header is emitted by the route `headers:` callback from
+    // this `degraded` field (a reliable document-response channel).
+    const degraded = getDegradedSections();
+    if (degraded.length > 0) {
+      console.warn(`[cms] home degraded — critical sections failed: ${degraded.join(", ")}`);
+    }
+
     return {
       ...pageData,
       resolvedSections: normalizeUrlsInObject(mergedSections),
       deferredSections: normalizeUrlsInObject(page.deferredSections),
+      degraded: degraded.length > 0,
       pagePath: "/",
       pageUrl: serverUrl.toString(),
       seo,
@@ -375,14 +403,17 @@ export const loadDeferredSection = createServerFn({ method: "POST" })
     // Resolve rawProps: prefer client-provided (backward compat), then server cache,
     // then re-extract from the page as a last resort (handles cross-isolate cache miss
     // on Cloudflare Workers and TTL expiry for slow-scrolling users).
-    const rawProps = clientRawProps
-      ?? (index !== undefined ? getDeferredRawProps(pagePath, component, index) : null)
-      ?? (index !== undefined
+    const rawProps =
+      clientRawProps ??
+      (index !== undefined ? getDeferredRawProps(pagePath, component, index) : null) ??
+      (index !== undefined
         ? await reExtractRawProps(pagePath, component, index, matcherCtx)
         : null);
 
     if (!rawProps) {
-      console.warn(`[CMS] Deferred section cache miss: ${component} at index ${index} on ${pagePath}`);
+      console.warn(
+        `[CMS] Deferred section cache miss: ${component} at index ${index} on ${pagePath}`,
+      );
       return null;
     }
 
@@ -405,10 +436,18 @@ export const loadDeferredSection = createServerFn({ method: "POST" })
     });
     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");
+    // Anti-cache-poisoning: if this deferred section's loader failed (e.g. an
+    // empty product shelf during a VTEX outage), do NOT mark it cacheable —
+    // otherwise the empty shelf would be stored in serverFnCache and served to
+    // every visitor for the full retention window. Flag it degraded instead.
+    if (getDegradedSections().length > 0) {
+      setResponseHeader("X-Deco-Degraded", "true");
+    } else {
+      // 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);
   });
@@ -443,6 +482,43 @@ export function CmsPagePendingFallback() {
   );
 }
 
+/**
+ * Default branded error boundary for CMS routes. Rendered when page resolution
+ * throws (as opposed to returning no match, which is a 404 / not-found path) —
+ * e.g. an uncaught throw in `resolveDecoPage` / `buildPageSeo` /
+ * `resolveSiteGlobals` during a VTEX outage. Without an `errorComponent` the
+ * loader rejection surfaces as a raw 500 white screen.
+ *
+ * This is the COLD-CACHE last resort: whenever a warm edge entry exists the
+ * worker serves it as `STALE-ERROR` before the request ever reaches here.
+ * Sites override via `cmsRouteConfig({ errorComponent })`.
+ */
+export function CmsPageErrorFallback(props: { reset?: () => void }) {
+  return createElement(
+    "div",
+    { className: "min-h-[60vh] flex items-center justify-center px-4 text-center" },
+    createElement(
+      "div",
+      { className: "max-w-md flex flex-col items-center gap-4" },
+      createElement("h1", { className: "text-2xl font-bold" }, "Estamos com uma instabilidade"),
+      createElement(
+        "p",
+        { className: "opacity-70" },
+        "Não conseguimos carregar esta página agora. Tente novamente em instantes.",
+      ),
+      createElement(
+        "button",
+        {
+          type: "button",
+          className: "btn btn-primary",
+          onClick: () => (props.reset ? props.reset() : undefined),
+        },
+        "Tentar de novo",
+      ),
+    ),
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Route configuration factory
 // ---------------------------------------------------------------------------
@@ -462,6 +538,13 @@ export interface CmsRouteOptions {
   ignoreSearchParams?: string[];
   /** Custom pending component shown during SPA navigation. */
   pendingComponent?: () => any;
+  /**
+   * Custom error boundary rendered when the loader / page resolution throws.
+   * Defaults to {@link CmsPageErrorFallback} (branded "instability" page with a
+   * retry button) so an outage degrades gracefully instead of a raw 500.
+   * Receives TanStack Router's `{ error, reset }`.
+   */
+  errorComponent?: (props: { error: Error; reset: () => void }) => any;
   /**
    * Delay (ms) before showing the pending component during SPA navigation.
    * If the loader resolves before this threshold, no pending UI is shown.
@@ -497,6 +580,7 @@ export interface CmsRouteOptions {
 type CmsPageLoaderData = {
   name?: string;
   cacheProfile?: CacheProfileName;
+  degraded?: boolean;
   seo?: PageSeo;
   device?: Device;
   resolvedSections?: Array<{ component: string }>;
@@ -702,6 +786,7 @@ export function cmsRouteConfig(options: CmsRouteOptions) {
     pendingMs = 200,
     pendingMinMs = 300,
     ssr: ssrMode,
+    errorComponent = CmsPageErrorFallback,
     resolveGlobals,
   } = options;
 
@@ -711,8 +796,7 @@ export function cmsRouteConfig(options: CmsRouteOptions) {
     // Catch-all search validation: preserve all URL search params so they
     // reach loaderDeps. Without this, TanStack Router may strip unknown
     // params (e.g. ?q=, filter.*, page, sort) during SPA navigation.
-    validateSearch: (search: Record<string, unknown>) =>
-      search as Record<string, string>,
+    validateSearch: (search: Record<string, unknown>) => search as Record<string, string>,
 
     loaderDeps: ({ search }: { search: Record<string, string> }) => {
       const filtered = Object.fromEntries(
@@ -763,13 +847,21 @@ export function cmsRouteConfig(options: CmsRouteOptions) {
     ...(pendingComponent ? { pendingComponent } : {}),
     pendingMs,
     pendingMinMs,
+    errorComponent,
     ...(ssrMode !== undefined ? { ssr: ssrMode } : {}),
 
     ...routeCacheDefaults("product"),
 
     headers: ({ loaderData }: { loaderData?: CmsPageLoaderData }) => {
       const profile = loaderData?.cacheProfile ?? "listing";
-      return cacheHeaders(profile);
+      const headers = cacheHeaders(profile);
+      // Emit the degraded flag on the DOCUMENT response via the route headers
+      // callback — the reliable channel (same one cacheHeaders rides), unlike
+      // setResponseHeader inside the server fn which may not reach the document.
+      // The worker treats a 200 + X-Deco-Degraded like a 5xx (no store, serve
+      // stale) to prevent caching an empty page during a VTEX outage.
+      if (loaderData?.degraded) headers["X-Deco-Degraded"] = "true";
+      return headers;
     },
 
     head: ({ loaderData }: { loaderData?: CmsPageLoaderData }) =>
@@ -793,6 +885,8 @@ export function cmsHomeRouteConfig(options: {
   pendingMs?: number;
   /** Minimum display time (ms) for pending component. Default: 300. */
   pendingMinMs?: number;
+  /** Error boundary for loader throws. Defaults to {@link CmsPageErrorFallback}. */
+  errorComponent?: (props: { error: Error; reset: () => void }) => any;
   /** See `CmsRouteOptions.resolveGlobals` — default `true`. */
   resolveGlobals?: boolean;
 }) {
@@ -802,6 +896,7 @@ export function cmsHomeRouteConfig(options: {
     siteName,
     pendingMs = 200,
     pendingMinMs = 300,
+    errorComponent = CmsPageErrorFallback,
     resolveGlobals,
   } = options;
 
@@ -822,8 +917,13 @@ export function cmsHomeRouteConfig(options: {
     ...(options.pendingComponent ? { pendingComponent: options.pendingComponent } : {}),
     pendingMs,
     pendingMinMs,
+    errorComponent,
     ...routeCacheDefaults("static"),
-    headers: () => cacheHeaders("static"),
+    headers: ({ loaderData }: { loaderData?: CmsPageLoaderData }) => {
+      const headers = cacheHeaders("static");
+      if (loaderData?.degraded) headers["X-Deco-Degraded"] = "true";
+      return headers;
+    },
     head: ({ loaderData }: { loaderData?: CmsPageLoaderData }) =>
       buildHead(loaderData, siteName ?? defaultTitle, defaultTitle, defaultDescription),
   };

package/src/sdk/workerEntry.test.ts

@@ -1,5 +1,6 @@
 import { setBlocks } from "@decocms/blocks/cms";
 import { afterEach, describe, expect, it } from "vitest";
+import { __resetKvHydrationStateForTests } from "./kvHydration";
 import {
   buildGeoCacheParam,
   createDecoWorkerEntry,
@@ -9,7 +10,6 @@ import {
   detectLocationMatcher,
   injectGeoCookies,
 } from "./workerEntry";
-import { __resetKvHydrationStateForTests } from "./kvHydration";
 
 const EMPTY_ENV = {};
 const MOCK_CTX = {
@@ -59,10 +59,7 @@ describe("injectGeoCookies", () => {
   });
 
   it("strips cf-ipcity from the outgoing Request headers while preserving the value in __cf_geo_city cookie", () => {
-    const req = makeRequest(
-      { city: "Brasília", country: "BR" },
-      { "cf-ipcity": "Brasília" },
-    );
+    const req = makeRequest({ city: "Brasília", country: "BR" }, { "cf-ipcity": "Brasília" });
 
     const out = injectGeoCookies(req);
 
@@ -91,10 +88,7 @@ describe("injectGeoCookies", () => {
   });
 
   it("preserves a pre-existing cookie header", () => {
-    const req = makeRequest(
-      { region: "São Paulo" },
-      { cookie: "vtex_segment=abc; another=xyz" },
-    );
+    const req = makeRequest({ region: "São Paulo" }, { cookie: "vtex_segment=abc; another=xyz" });
 
     const out = injectGeoCookies(req);
 
@@ -161,8 +155,11 @@ describe("detectLocationMatcher", () => {
   it("returns true when decofile has a website/matchers/location.ts __resolveType", () => {
     const blocks = {
       "audiences/geo-audience.json": {
-        "__resolveType": "website/flags/audience.ts",
-        "matcher": { "__resolveType": "website/matchers/location.ts", "includeLocations": [{ "country": "BR" }] },
+        __resolveType: "website/flags/audience.ts",
+        matcher: {
+          __resolveType: "website/matchers/location.ts",
+          includeLocations: [{ country: "BR" }],
+        },
       },
     };
     expect(detectLocationMatcher(blocks)).toBe(true);
@@ -171,8 +168,8 @@ describe("detectLocationMatcher", () => {
   it("returns false when decofile has no location matcher", () => {
     const blocks = {
       "audiences/device-audience.json": {
-        "__resolveType": "website/flags/audience.ts",
-        "matcher": { "__resolveType": "website/matchers/device.ts" },
+        __resolveType: "website/flags/audience.ts",
+        matcher: { __resolveType: "website/matchers/device.ts" },
       },
     };
     expect(detectLocationMatcher(blocks)).toBe(false);
@@ -185,8 +182,8 @@ describe("detectLocationMatcher", () => {
   it("returns true when the matcher is nested deeply", () => {
     const blocks = {
       "pages/home.json": {
-        "variant": {
-          "matcher": { "__resolveType": "website/matchers/location.ts" },
+        variant: {
+          matcher: { __resolveType: "website/matchers/location.ts" },
         },
       },
     };
@@ -196,8 +193,8 @@ describe("detectLocationMatcher", () => {
   it("returns false when location.ts appears only in a non-resolveType string value (no false positive)", () => {
     const blocks = {
       "content/help.json": {
-        "__resolveType": "website/sections/RichText.tsx",
-        "body": "This page is controlled by website/matchers/location.ts for geo targeting.",
+        __resolveType: "website/sections/RichText.tsx",
+        body: "This page is controlled by website/matchers/location.ts for geo targeting.",
       },
     };
     expect(detectLocationMatcher(blocks)).toBe(false);
@@ -218,11 +215,7 @@ describe("CMS redirects", () => {
       },
     });
     const worker = createDecoWorkerEntry(MOCK_SERVER_ENTRY, { observability: false });
-    const res = await worker.fetch(
-      new Request("https://example.com/old"),
-      EMPTY_ENV,
-      MOCK_CTX,
-    );
+    const res = await worker.fetch(new Request("https://example.com/old"), EMPTY_ENV, MOCK_CTX);
     expect(res.status).toBe(301);
     expect(res.headers.get("Location")).toBe("/new");
   });
@@ -252,11 +245,7 @@ describe("CMS redirects", () => {
       },
     });
     const worker = createDecoWorkerEntry(MOCK_SERVER_ENTRY, { observability: false });
-    const res = await worker.fetch(
-      new Request("https://example.com/promo"),
-      EMPTY_ENV,
-      MOCK_CTX,
-    );
+    const res = await worker.fetch(new Request("https://example.com/promo"), EMPTY_ENV, MOCK_CTX);
     expect(res.status).toBe(302);
     expect(res.headers.get("Location")).toBe("/promo%C3%A7%C3%A3o");
   });
@@ -269,11 +258,7 @@ describe("CMS redirects", () => {
       },
     });
     const worker = createDecoWorkerEntry(MOCK_SERVER_ENTRY, { observability: false });
-    const res = await worker.fetch(
-      new Request("https://example.com/promo"),
-      EMPTY_ENV,
-      MOCK_CTX,
-    );
+    const res = await worker.fetch(new Request("https://example.com/promo"), EMPTY_ENV, MOCK_CTX);
     expect(res.status).toBe(302);
     expect(res.headers.get("Location")).toBe("/sale");
   });
@@ -286,11 +271,7 @@ describe("CMS redirects", () => {
       },
     });
     const worker = createDecoWorkerEntry(MOCK_SERVER_ENTRY, { observability: false });
-    const res = await worker.fetch(
-      new Request("https://example.com/other"),
-      EMPTY_ENV,
-      MOCK_CTX,
-    );
+    const res = await worker.fetch(new Request("https://example.com/other"), EMPTY_ENV, MOCK_CTX);
     expect(res.status).toBe(200);
   });
 
@@ -299,11 +280,7 @@ describe("CMS redirects", () => {
     const worker = createDecoWorkerEntry(MOCK_SERVER_ENTRY, { observability: false });
 
     // First request with no redirects — falls through
-    const res1 = await worker.fetch(
-      new Request("https://example.com/v1"),
-      EMPTY_ENV,
-      MOCK_CTX,
-    );
+    const res1 = await worker.fetch(new Request("https://example.com/v1"), EMPTY_ENV, MOCK_CTX);
     expect(res1.status).toBe(200);
 
     // Hot-reload: add a redirect
@@ -315,13 +292,49 @@ describe("CMS redirects", () => {
     });
 
     // Same path should now redirect
-    const res2 = await worker.fetch(
-      new Request("https://example.com/v1"),
+    const res2 = await worker.fetch(new Request("https://example.com/v1"), EMPTY_ENV, MOCK_CTX);
+    expect(res2.status).toBe(301);
+    expect(res2.headers.get("Location")).toBe("/v2");
+  });
+});
+
+describe("degraded origin (anti-cache-poisoning)", () => {
+  afterEach(() => {
+    setBlocks({});
+    __resetKvHydrationStateForTests();
+  });
+
+  it("never caches a degraded 200 and marks it no-store", async () => {
+    setBlocks({});
+    const degradedEntry = {
+      fetch: async () =>
+        new Response("empty shelf", {
+          status: 200,
+          headers: { "X-Deco-Degraded": "true" },
+        }),
+    };
+    const worker = createDecoWorkerEntry(degradedEntry, { observability: false });
+    const res = await worker.fetch(
+      new Request("https://example.com/some-category"),
       EMPTY_ENV,
       MOCK_CTX,
     );
-    expect(res2.status).toBe(301);
-    expect(res2.headers.get("Location")).toBe("/v2");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("X-Cache")).toBe("BYPASS");
+    expect(res.headers.get("X-Cache-Reason")).toBe("degraded");
+    expect(res.headers.get("Cache-Control")).toContain("no-store");
+  });
+
+  it("serves a healthy 200 origin without the degraded bypass", async () => {
+    setBlocks({});
+    const worker = createDecoWorkerEntry(MOCK_SERVER_ENTRY, { observability: false });
+    const res = await worker.fetch(
+      new Request("https://example.com/some-category"),
+      EMPTY_ENV,
+      MOCK_CTX,
+    );
+    expect(res.status).toBe(200);
+    expect(res.headers.get("X-Cache-Reason")).not.toBe("degraded");
   });
 });
 

package/src/sdk/workerEntry.ts

@@ -25,12 +25,10 @@
  * ```
  */
 
-import { getRenderShellConfig } from "@decocms/blocks-admin/admin/setup";
-import { getAppMiddleware } from "@decocms/blocks-admin/sdk/setupApps";
 import {
+  getRevision,
   isBot,
   loadBlocks,
-  getRevision,
   type MatcherContext,
   onChange,
   resolveDecoPage,
@@ -39,7 +37,6 @@ import {
 } from "@decocms/blocks/cms";
 import { DECO_MATCHERS_OVERRIDE_PARAM } from "@decocms/blocks/matchers/override";
 import { clearLoaderCache } from "@decocms/blocks/sdk/cachedLoader";
-import { loadRedirects, matchRedirect, type RedirectMap } from "@decocms/blocks/sdk/redirects";
 import {
   type CacheProfileName,
   cacheHeaders,
@@ -49,9 +46,8 @@ import {
   getCacheProfile,
   serverFnPagePath,
 } from "@decocms/blocks/sdk/cacheHeaders";
+import { isDevMode } from "@decocms/blocks/sdk/env";
 import { parseSegmentCookie, SEGMENT_COOKIE, segmentCacheToken } from "@decocms/blocks/sdk/flags";
-import { buildHtmlShell } from "@decocms/blocks-admin/sdk/htmlShell";
-import { ensureBlocksHydrated, maybePollRevision } from "./kvHydration";
 import {
   getActiveSpan,
   logRequest,
@@ -66,13 +62,17 @@ import {
   instrumentWorker,
   type OtelOptions,
 } from "@decocms/blocks/sdk/otel";
-import { DECO_POWERED_BY, installDefaultUserAgent } from "./outboundHeaders";
 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 { RequestContext } from "@decocms/blocks/sdk/requestContext";
 import { cleanPathForCacheKey } from "@decocms/blocks/sdk/urlUtils";
 import { type Device, isMobileUA } from "@decocms/blocks/sdk/useDevice";
-import { isDevMode } from "@decocms/blocks/sdk/env";
+import { getRenderShellConfig } from "@decocms/blocks-admin/admin/setup";
+import { buildHtmlShell } from "@decocms/blocks-admin/sdk/htmlShell";
+import { getAppMiddleware } from "@decocms/blocks-admin/sdk/setupApps";
+import { ensureBlocksHydrated, maybePollRevision } from "./kvHydration";
+import { DECO_POWERED_BY, installDefaultUserAgent } from "./outboundHeaders";
 
 /**
  * Build-time identifier injected by `decoVitePlugin()` (see
@@ -1074,10 +1074,7 @@ export function createDecoWorkerEntry(
     // (skuId/idsku) that the loader ignores — otherwise `/p?skuId=X` and `/p`
     // get distinct keys and every variant-carrying PDP→PDP nav MISSes, even
     // though the resolved response is identical. Keeps PLP filter params intact.
-    if (
-      url.pathname.startsWith("/_serverFn/") ||
-      url.pathname.startsWith("/_server/")
-    ) {
+    if (url.pathname.startsWith("/_serverFn/") || url.pathname.startsWith("/_server/")) {
       const payload = url.searchParams.get("payload");
       if (payload) {
         url.searchParams.set("payload", canonicalizeServerFnPayloadForCacheKey(payload));
@@ -1122,8 +1119,8 @@ export function createDecoWorkerEntry(
     // diverge. `/_serverFn` (SPA-nav data) is excluded: it has its own keying
     // and stays eager via isClientNavigation, not this bucket.
     const secFetchDest = request.headers.get("sec-fetch-dest");
-    const isServerFnPath = url.pathname.startsWith("/_serverFn/") ||
-      url.pathname.startsWith("/_server/");
+    const isServerFnPath =
+      url.pathname.startsWith("/_serverFn/") || url.pathname.startsWith("/_server/");
     if (!isServerFnPath && secFetchDest === "empty") {
       url.searchParams.set("__fetch", "1");
     }
@@ -1135,7 +1132,9 @@ export function createDecoWorkerEntry(
     // keep sharing one entry. A freshly-assigned visitor sets the cookie on the
     // response, which is not a "safe" cookie, so that one response bypasses the
     // cache and never poisons the shared entry.
-    const flagToken = segmentCacheToken(parseSegmentCookie(readRequestCookie(request, SEGMENT_COOKIE)));
+    const flagToken = segmentCacheToken(
+      parseSegmentCookie(readRequestCookie(request, SEGMENT_COOKIE)),
+    );
     if (flagToken) {
       url.searchParams.set("__abf", flagToken);
     }
@@ -2129,7 +2128,10 @@ export function createDecoWorkerEntry(
       ctx.waitUntil(
         Promise.resolve(serverEntry.fetch(request, env, ctx))
           .then((origin) => {
-            if (origin.status === 200) {
+            // Never overwrite a good entry with a degraded 200 (a critical
+            // section failed) — that would poison the cache. Leave the stale
+            // entry in place until a healthy revalidation succeeds.
+            if (origin.status === 200 && origin.headers.get("X-Deco-Degraded") !== "true") {
               // Only cache if response has no cookies or only safe cookies.
               // Strip safe cookies from the cached copy.
               if (hasOnlySafeCookies(origin, safeCookieSet)) {
@@ -2247,6 +2249,38 @@ export function createDecoWorkerEntry(
       return resp;
     }
 
+    // Degraded origin — a critical section loader failed, so this 200 carries
+    // raw/empty data (e.g. an empty product shelf during a VTEX outage). Treat
+    // it like a 5xx for caching: prefer a warm stale entry (STALE-ERROR) and
+    // NEVER store it. Without this, the broken page would be cached as healthy
+    // for the full retention window and stale-if-error would never fire —
+    // turning a seconds-long blip into hours of empty pages.
+    if (origin.headers.get("X-Deco-Degraded") === "true") {
+      if (cached && edgeConfig.sie > 0) {
+        const storedAtStr = cached.headers.get("X-Deco-Stored-At");
+        const storedAt = storedAtStr ? Number(storedAtStr) : 0;
+        const ageSec = storedAt > 0 ? (Date.now() - storedAt) / 1000 : Infinity;
+        if (ageSec < edgeConfig.fresh + edgeConfig.sie) {
+          console.warn(
+            `[edge-cache] Origin degraded, serving stale (age=${Math.round(ageSec)}s, sie=${edgeConfig.sie}s)`,
+          );
+          recordCacheMetric(true, profile, "STALE-ERROR", "edge");
+          return dressResponse(cached, "STALE-ERROR", {
+            "X-Cache-Age": String(Math.round(ageSec)),
+            "X-Cache-Reason": "degraded",
+          });
+        }
+      }
+      // Cold cache — serve the degraded page but never persist it.
+      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", "degraded");
+      appendResourceHints(resp);
+      return resp;
+    }
+
     const profileConfig = getCacheProfile(profile);
 
     if (!profileConfig.isPublic || profileConfig.edge.fresh === 0) {