@decocms/blocks 7.22.2 → 7.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks",
-  "version": "7.22.2",
+  "version": "7.24.0",
   "type": "module",
   "engines": {
     "node": ">=24"

package/src/cms/index.ts

@@ -1,3 +1,5 @@
+export type { ApplySectionConventionsInput, SectionMetaEntry } from "./applySectionConventions";
+export { applySectionConventions } from "./applySectionConventions";
 export type { BlockSnapshot, BlockSource, KVNamespace } from "./blockSource";
 export {
   BUILD_HASH_ENV,
@@ -50,10 +52,11 @@ export type {
 } from "./resolve";
 export {
   addSkipResolveType,
+  cacheDeferredRawProps,
+  clearCommerceLoaders,
   evaluateMatcher,
   extractSeoFromProps,
   extractSeoFromSections,
-  cacheDeferredRawProps,
   getAsyncRenderingConfig,
   getDeferredRawProps,
   isBot,
@@ -63,43 +66,24 @@ export {
   registerBotPattern,
   registerCommerceLoader,
   registerCommerceLoaders,
-  unregisterCommerceLoader,
-  clearCommerceLoaders,
-  registerMatcher,
   registerEagerSections,
+  registerMatcher,
   registerNeverDeferSections,
   registerSeoSections,
   resolveDecoPage,
-  resolvePageSections,
-  resolvePageSeoBlock,
   resolveDeferredSection,
   resolveDeferredSectionFull,
+  resolvePageSections,
+  resolvePageSeoBlock,
   resolveValue,
   setAsyncRenderingConfig,
   setDanglingReferenceHandler,
   setResolveErrorHandler,
+  unregisterCommerceLoader,
   WELL_KNOWN_TYPES,
 } from "./resolve";
-export type { SectionLoaderFn } from "./sectionLoaders";
-export {
-  isLayoutSection,
-  registerCacheableSections,
-  registerLayoutSections,
-  registerSectionLoader,
-  registerSectionLoaders,
-  runSectionLoaders,
-  runSingleSectionLoader,
-  unregisterLayoutSections,
-} from "./sectionLoaders";
-export {
-  compose,
-  withDevice,
-  withMobile,
-  withSearchParam,
-  withSectionLoader,
-} from "./sectionMixins";
-export type { ApplySectionConventionsInput, SectionMetaEntry } from "./applySectionConventions";
-export { applySectionConventions } from "./applySectionConventions";
+export type { SectionLoaderContext } from "./sectionLoaderContext";
+export { buildSectionLoaderContext } from "./sectionLoaderContext";
 export type {
   ActionConfig,
   AppSchemas,
@@ -121,3 +105,25 @@ export {
   registerMatcherSchema,
   registerMatcherSchemas,
 } from "./schema";
+export type { SectionLoaderFn } from "./sectionLoaders";
+export {
+  getDegradedSections,
+  isCriticalSection,
+  isLayoutSection,
+  markSectionDegraded,
+  registerCacheableSections,
+  registerLayoutSections,
+  registerNonCriticalSections,
+  registerSectionLoader,
+  registerSectionLoaders,
+  runSectionLoaders,
+  runSingleSectionLoader,
+  unregisterLayoutSections,
+} from "./sectionLoaders";
+export {
+  compose,
+  withDevice,
+  withMobile,
+  withSearchParam,
+  withSectionLoader,
+} from "./sectionMixins";

package/src/cms/resolve.ts

@@ -13,7 +13,7 @@ import { withInflightTimeout } from "../sdk/inflightTimeout";
 import { normalizeUrlsInObject } from "../sdk/normalizeUrls";
 import { findPageByPath, loadBlocks } from "./loader";
 import { getOnBeforeResolveProps, getSection, registerOnBeforeResolveProps } from "./registry";
-import { isLayoutSection, runSingleSectionLoader } from "./sectionLoaders";
+import { isLayoutSection, markSectionDegraded, runSingleSectionLoader } from "./sectionLoaders";
 
 // globalThis-backed: share state across Vite server function split modules
 const G = globalThis as any;
@@ -911,6 +911,11 @@ async function internalResolve(value: unknown, rctx: ResolveContext): Promise<un
       return await commerceLoader(resolvedProps);
     } catch (error) {
       onResolveError(error, resolveType, "Commerce loader");
+      // Commerce loaders (VTEX product/PLP/PDP data) are the primary source of
+      // page-body data — this is exactly the layer that fails during a VTEX
+      // outage. Flag the page degraded so the edge won't cache the empty
+      // result as a healthy 200 (see X-Deco-Degraded in cmsRoute/workerEntry).
+      markSectionDegraded(resolveType);
       return null;
     }
   }

package/src/cms/sectionLoaderContext.test.ts

@@ -0,0 +1,111 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { RequestContext } from "../sdk/requestContext";
+import { buildSectionLoaderContext } from "./sectionLoaderContext";
+
+const MOBILE_UA =
+  "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 Mobile/15E148";
+const DESKTOP_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36";
+const TABLET_UA = "Mozilla/5.0 (iPad; CPU OS 17_0 like Mac OS X) AppleWebKit/605.1.15";
+
+function reqWithUA(ua: string, url = "https://store.example/path?q=shoes"): Request {
+  return new Request(url, { headers: { "user-agent": ua } });
+}
+
+describe("buildSectionLoaderContext", () => {
+  describe("device", () => {
+    it("detects mobile / desktop / tablet from the request User-Agent", () => {
+      expect(buildSectionLoaderContext(reqWithUA(MOBILE_UA)).device).toBe("mobile");
+      expect(buildSectionLoaderContext(reqWithUA(DESKTOP_UA)).device).toBe("desktop");
+      expect(buildSectionLoaderContext(reqWithUA(TABLET_UA)).device).toBe("tablet");
+    });
+
+    it("defaults to desktop when there is no User-Agent", () => {
+      expect(buildSectionLoaderContext(new Request("https://store.example/")).device).toBe(
+        "desktop",
+      );
+    });
+
+    it("never throws for a minimal/mock request without headers", () => {
+      const badReq = { url: "not a url" } as unknown as Request;
+      expect(() => buildSectionLoaderContext(badReq)).not.toThrow();
+      expect(buildSectionLoaderContext(badReq).device).toBe("desktop");
+    });
+  });
+
+  describe("app state", () => {
+    it("resolves ctx.<appName> to the app's registered state inside a request scope", async () => {
+      const req = reqWithUA(DESKTOP_UA);
+      await RequestContext.run(req, async () => {
+        RequestContext.setBag("app:vtex:state", { config: { account: "acme" } });
+        const ctx = buildSectionLoaderContext(req);
+        expect((ctx as any).vtex).toEqual({ config: { account: "acme" } });
+        expect(ctx.getAppState("vtex")).toEqual({ config: { account: "acme" } });
+      });
+    });
+
+    it("returns undefined for an unconfigured app (no fake object)", async () => {
+      const req = reqWithUA(DESKTOP_UA);
+      await RequestContext.run(req, async () => {
+        const ctx = buildSectionLoaderContext(req);
+        expect((ctx as any).salesforce).toBeUndefined();
+      });
+    });
+
+    it("returns undefined for app state outside a request scope", () => {
+      const ctx = buildSectionLoaderContext(reqWithUA(DESKTOP_UA));
+      expect((ctx as any).vtex).toBeUndefined();
+    });
+  });
+
+  describe("response.headers", () => {
+    it("writes through to RequestContext.responseHeaders inside a scope", async () => {
+      const req = reqWithUA(DESKTOP_UA);
+      await RequestContext.run(req, async () => {
+        const ctx = buildSectionLoaderContext(req);
+        ctx.response.headers.set("set-cookie", "a=1");
+        expect(RequestContext.responseHeaders.get("set-cookie")).toBe("a=1");
+      });
+    });
+
+    it("degrades to an inert Headers outside a scope (does not throw)", () => {
+      const ctx = buildSectionLoaderContext(reqWithUA(DESKTOP_UA));
+      expect(() => ctx.response.headers.set("x", "y")).not.toThrow();
+    });
+  });
+
+  describe("invoke (server-side self-fetch)", () => {
+    let fetchMock: ReturnType<typeof vi.fn>;
+
+    beforeEach(() => {
+      fetchMock = vi
+        .fn()
+        .mockResolvedValue(new Response(JSON.stringify({ ok: true }), { status: 200 }));
+      vi.stubGlobal("fetch", fetchMock);
+    });
+
+    afterEach(() => {
+      vi.unstubAllGlobals();
+    });
+
+    it("POSTs to the request's absolute origin /deco/invoke/<key>", async () => {
+      const ctx = buildSectionLoaderContext(reqWithUA(DESKTOP_UA, "https://store.example/pdp"));
+      const result = await ctx.invoke.vtex.loaders.product.detailsPageGQL({ slug: "x" });
+
+      expect(result).toEqual({ ok: true });
+      const [url, init] = fetchMock.mock.calls[0];
+      expect(url).toBe("https://store.example/deco/invoke/vtex/loaders/product/detailsPageGQL");
+      expect(init.method).toBe("POST");
+      expect(JSON.parse(init.body)).toEqual({ slug: "x" });
+    });
+
+    it("injects the request AbortSignal when invoked inside a request scope", async () => {
+      const req = reqWithUA(DESKTOP_UA, "https://store.example/pdp");
+      await RequestContext.run(req, async () => {
+        const ctx = buildSectionLoaderContext(req);
+        await ctx.invoke.vtex.loaders.x({});
+        const [, init] = fetchMock.mock.calls[0];
+        expect(init.signal).toBeInstanceOf(AbortSignal);
+      });
+    });
+  });
+});

package/src/cms/sectionLoaderContext.ts

@@ -0,0 +1,113 @@
+/**
+ * Section-loader compatibility context (`ctx`) — issue #305.
+ *
+ * deco.cx (Fresh) section loaders use a 3-arg signature
+ * `(props, req, ctx: AppContext)`, where `ctx` exposes device detection,
+ * `ctx.invoke.*`, per-app state (`ctx.vtex`, `ctx.salesforce`, …) and
+ * `ctx.response.headers`. `@decocms/blocks` invokes loaders with only
+ * `(props, req)`, so migrated loaders read `undefined` and throw.
+ *
+ * Rather than delete `ctx` (which would force rewriting every migrated
+ * loader by hand), we re-assemble a **real** compat `ctx` from the primitives
+ * the framework already has — no fabricated stubs (policy D3):
+ *
+ * - `device`  → {@link detectDevice} on the request User-Agent. Derived from
+ *   `req` (NOT `RequestContext`) on purpose: the `createServerFn` path used in
+ *   dev / SPA navigation is not wrapped in `RequestContext.run`, so a
+ *   RequestContext-only device would silently degrade to "desktop" there.
+ * - `invoke`  → the same nested invoke proxy the client uses, but pointed at
+ *   an absolute self-origin and routed through `RequestContext.fetch` so the
+ *   request's AbortSignal propagates. `ctx.invoke.vtex.loaders.x(props)` works
+ *   server-side via a self-fetch to `/deco/invoke`.
+ * - app state → `RequestContext.getAppState(name)`; any unknown property access
+ *   (`ctx.vtex`, `ctx.salesforce`, …) resolves to the app's registered state
+ *   or `undefined`. Real lookup, not a fake object.
+ * - `response.headers` → `RequestContext.responseHeaders` when in a request
+ *   scope; an inert `Headers` otherwise (writes don't propagate in dev/SPA but
+ *   never crash).
+ */
+
+import { type Device, detectDevice } from "../sdk/detectDevice";
+import { createAppInvokeWith } from "../sdk/invoke";
+import { RequestContext } from "../sdk/requestContext";
+
+/**
+ * The compat context handed to section loaders as the 3rd argument.
+ *
+ * It is indexable (`[appName: string]: unknown`) because Fresh loaders read
+ * per-app state off `ctx` directly (`ctx.vtex`, `ctx.salesforce`, …). Those
+ * reads resolve through {@link RequestContext.getAppState}. Migrated code
+ * should still optional-chain deep app-state reads (`ctx.vtex?.config`), since
+ * an app that isn't configured yields `undefined`.
+ */
+export interface SectionLoaderContext {
+  /** Device type detected from the request User-Agent. */
+  device: Device;
+  /**
+   * Nested invoke proxy (`ctx.invoke.vtex.loaders.x(props)`), bound to this
+   * request's origin and AbortSignal. Works server-side via self-fetch.
+   */
+  invoke: any;
+  /** Outgoing response headers (e.g. for Set-Cookie forwarding). */
+  response: { headers: Headers };
+  /** Typed access to an app's request-scoped state. */
+  getAppState: <T>(appName: string) => T | undefined;
+  /** Per-app state read directly off ctx (Fresh compatibility). */
+  [appName: string]: unknown;
+}
+
+/**
+ * Build the compat {@link SectionLoaderContext} for a single loader call.
+ * Cheap to construct (device detect + lazy proxies), so it's fine to build
+ * per section loader invocation.
+ */
+export function buildSectionLoaderContext(req: Request): SectionLoaderContext {
+  // Defensive: `req` may be a minimal/mock request without a real `headers`
+  // object. Building the ctx must never throw — that would take down the
+  // loader before it runs.
+  const device = detectDevice(req.headers?.get?.("user-agent") ?? "");
+
+  let origin = "";
+  try {
+    origin = new URL(req.url).origin;
+  } catch {
+    // Relative/opaque request URL — fall back to a relative base path.
+  }
+
+  const invoke = createAppInvokeWith({
+    basePath: `${origin}/deco/invoke`,
+    fetcher: (input, init) => RequestContext.fetch(input, init),
+  });
+
+  const base = {
+    device,
+    invoke,
+    get response(): { headers: Headers } {
+      // `responseHeaders` throws outside a request scope (dev/SPA serverFn
+      // path). Degrade to an inert Headers rather than crash the loader.
+      let headers: Headers;
+      try {
+        headers = RequestContext.responseHeaders;
+      } catch {
+        headers = new Headers();
+      }
+      return { headers };
+    },
+    getAppState<T>(appName: string): T | undefined {
+      return RequestContext.getAppState<T>(appName);
+    },
+  };
+
+  const known = new Set(["device", "invoke", "response", "getAppState"]);
+
+  // Wrap so unknown property access (`ctx.vtex`, `ctx.salesforce`, …) resolves
+  // to the app's registered state. Known fields fall through to `base`.
+  return new Proxy(base as SectionLoaderContext, {
+    get(target, prop, receiver) {
+      if (typeof prop === "string" && !known.has(prop) && !(prop in target)) {
+        return RequestContext.getAppState(prop);
+      }
+      return Reflect.get(target, prop, receiver);
+    },
+  });
+}

package/src/cms/sectionLoaders.test.ts

@@ -1,10 +1,13 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { configureTracer, type Span } from "../sdk/observability";
+import { RequestContext } from "../sdk/requestContext";
 import type { ResolvedSection } from "./resolve";
 import {
+  getDegradedSections,
   isLayoutSection,
   registerCacheableSections,
   registerLayoutSections,
+  registerNonCriticalSections,
   registerSectionLoader,
   registerSectionLoaders,
   runSectionLoaders,
@@ -19,6 +22,7 @@ beforeEach(() => {
   G.__deco.sectionLoaderRegistry.clear();
   G.__deco.layoutSections.clear();
   G.__deco.cacheableSections.clear();
+  G.__deco.nonCriticalSections.clear();
 });
 
 const makeSection = (component: string, props: Record<string, unknown> = {}): ResolvedSection => ({
@@ -28,6 +32,78 @@ const makeSection = (component: string, props: Record<string, unknown> = {}): Re
   index: 0,
 });
 
+describe("section degradation tracking (anti-cache-poisoning)", () => {
+  const failing = async () => {
+    throw new Error("VTEX down");
+  };
+
+  it("marks a critical section as degraded when its loader throws", async () => {
+    registerSectionLoader("site/sections/ProductShelf.tsx", failing);
+    const section = makeSection("site/sections/ProductShelf.tsx");
+    const request = new Request("https://store.com/p");
+
+    const degraded = await RequestContext.run(request, async () => {
+      // Loader throws → section degrades to raw props (does not reject).
+      const result = await runSingleSectionLoader(section, request);
+      expect(result.component).toBe("site/sections/ProductShelf.tsx");
+      return getDegradedSections();
+    });
+
+    expect(degraded).toContain("site/sections/ProductShelf.tsx");
+  });
+
+  it("does NOT mark a non-critical section as degraded", async () => {
+    registerSectionLoader("site/sections/Decorative.tsx", failing);
+    registerNonCriticalSections(["site/sections/Decorative.tsx"]);
+    const section = makeSection("site/sections/Decorative.tsx");
+    const request = new Request("https://store.com/p");
+
+    const degraded = await RequestContext.run(request, async () => {
+      await runSingleSectionLoader(section, request);
+      return getDegradedSections();
+    });
+
+    expect(degraded).toEqual([]);
+  });
+
+  it("does NOT mark a failing LAYOUT section as degraded (avoids site-wide poisoning)", async () => {
+    registerSectionLoader("site/sections/Header.tsx", failing);
+    registerLayoutSections(["site/sections/Header.tsx"]);
+    const section = makeSection("site/sections/Header.tsx");
+    const request = new Request("https://store.com/p");
+
+    const degraded = await RequestContext.run(request, async () => {
+      await runSingleSectionLoader(section, request);
+      return getDegradedSections();
+    });
+
+    // A flaky Header/Footer must not flip every page to X-Deco-Degraded.
+    expect(degraded).toEqual([]);
+  });
+
+  it("does not flag a page whose loaders all succeed", async () => {
+    registerSectionLoader("site/sections/Ok.tsx", async (p: Record<string, unknown>) => p);
+    const section = makeSection("site/sections/Ok.tsx");
+    const request = new Request("https://store.com/p");
+
+    const degraded = await RequestContext.run(request, async () => {
+      await runSingleSectionLoader(section, request);
+      return getDegradedSections();
+    });
+
+    expect(degraded).toEqual([]);
+  });
+
+  it("is a no-op outside a request scope (does not throw)", async () => {
+    registerSectionLoader("site/sections/NoScope.tsx", failing);
+    const section = makeSection("site/sections/NoScope.tsx");
+    const request = new Request("https://store.com/p");
+    // No RequestContext.run wrapper — must not throw.
+    await expect(runSingleSectionLoader(section, request)).resolves.toBeTruthy();
+    expect(getDegradedSections()).toEqual([]);
+  });
+});
+
 describe("runSingleSectionLoader — page context injection", () => {
   it("injects __pageUrl and __pagePath into loader props", async () => {
     // Two-arg signature so loader.mock.calls[0] types as [props, req].
@@ -82,6 +158,59 @@ describe("runSingleSectionLoader — page context injection", () => {
     const result = await runSingleSectionLoader(section, new Request("https://store.com/"));
     expect(result).toBe(section);
   });
+
+  it("passes a 3rd-arg compat ctx (device from UA) — regular path (#305)", async () => {
+    const loader = vi.fn(
+      async (props: Record<string, unknown>, _req: Request, ctx?: { device?: string }) => ({
+        ...props,
+        seenDevice: ctx?.device,
+      }),
+    );
+    registerSectionLoader("site/sections/Ctx.tsx", loader);
+
+    const section = makeSection("site/sections/Ctx.tsx", {});
+    const mobileReq = new Request("https://store.com/", {
+      headers: { "user-agent": "iPhone Mobile Safari" },
+    });
+    const result = await runSingleSectionLoader(section, mobileReq);
+
+    expect((result.props as Record<string, unknown>).seenDevice).toBe("mobile");
+  });
+
+  it("passes the compat ctx through layout and cacheable paths (#305)", async () => {
+    const layoutLoader = vi.fn(
+      async (props: Record<string, unknown>, _req: Request, ctx?: { device?: string }) => ({
+        ...props,
+        seenDevice: ctx?.device,
+      }),
+    );
+    const cacheableLoader = vi.fn(
+      async (props: Record<string, unknown>, _req: Request, ctx?: { device?: string }) => ({
+        ...props,
+        seenDevice: ctx?.device,
+      }),
+    );
+    registerSectionLoader("site/sections/CtxHeader.tsx", layoutLoader);
+    registerLayoutSections(["site/sections/CtxHeader.tsx"]);
+    registerSectionLoader("site/sections/CtxShelf.tsx", cacheableLoader);
+    registerCacheableSections({ "site/sections/CtxShelf.tsx": { maxAge: 60_000 } });
+
+    const mobileReq = new Request("https://store.com/", {
+      headers: { "user-agent": "iPhone Mobile Safari" },
+    });
+
+    const layoutResult = await runSingleSectionLoader(
+      makeSection("site/sections/CtxHeader.tsx"),
+      mobileReq,
+    );
+    const cacheableResult = await runSingleSectionLoader(
+      makeSection("site/sections/CtxShelf.tsx"),
+      mobileReq,
+    );
+
+    expect((layoutResult.props as Record<string, unknown>).seenDevice).toBe("mobile");
+    expect((cacheableResult.props as Record<string, unknown>).seenDevice).toBe("mobile");
+  });
 });
 
 describe("runSingleSectionLoader — cache keying", () => {
@@ -151,9 +280,7 @@ describe("unregisterLayoutSections", () => {
   });
 
   it("is a no-op for keys that were never registered", () => {
-    expect(() =>
-      unregisterLayoutSections(["site/sections/Never.tsx"]),
-    ).not.toThrow();
+    expect(() => unregisterLayoutSections(["site/sections/Never.tsx"])).not.toThrow();
     expect(isLayoutSection("site/sections/Never.tsx")).toBe(false);
   });
 });
@@ -190,10 +317,7 @@ describe("registerSectionLoaders — request-dependent + layout warning (#206)",
   it("warns when a composed loader contains any request-dependent mixin", () => {
     registerLayoutSections(["site/sections/Footer.tsx"]);
     registerSectionLoaders({
-      "site/sections/Footer.tsx": compose(
-        withSearchParam(),
-        async (props) => props,
-      ),
+      "site/sections/Footer.tsx": compose(withSearchParam(), async (props) => props),
     });
     expect(warnSpy).toHaveBeenCalled();
   });

package/src/cms/sectionLoaders.ts

@@ -9,15 +9,23 @@
  * inside the TanStack Start server function.
  */
 
+import { RequestContext } from "@decocms/blocks/sdk/requestContext";
 import { getCacheProfile } from "../sdk/cacheHeaders";
 import { djb2 } from "../sdk/djb2";
 import { withInflightTimeout } from "../sdk/inflightTimeout";
 import { withTracing } from "../sdk/observability";
 import type { ResolvedSection } from "./resolve";
+import { buildSectionLoaderContext, type SectionLoaderContext } from "./sectionLoaderContext";
 
 export type SectionLoaderFn = (
   props: Record<string, unknown>,
   req: Request,
+  /**
+   * Compat context (issue #305). Optional so 2-arg loaders/mixins remain
+   * valid — they simply ignore the extra argument. Framework-supplied at the
+   * call site via {@link buildSectionLoaderContext}.
+   */
+  ctx?: SectionLoaderContext,
 ) => Promise<Record<string, unknown>> | Record<string, unknown>;
 
 // globalThis-backed: server function split modules need access
@@ -26,9 +34,56 @@ if (!G.__deco) G.__deco = {};
 if (!G.__deco.sectionLoaderRegistry) G.__deco.sectionLoaderRegistry = new Map();
 if (!G.__deco.layoutSections) G.__deco.layoutSections = new Set();
 if (!G.__deco.cacheableSections) G.__deco.cacheableSections = new Map();
+if (!G.__deco.nonCriticalSections) G.__deco.nonCriticalSections = new Set();
 
 const loaderRegistry: Map<string, SectionLoaderFn> = G.__deco.sectionLoaderRegistry;
 
+// ---------------------------------------------------------------------------
+// Degradation tracking (anti-cache-poisoning)
+//
+// When a section loader throws, the section renders with raw (un-enriched)
+// props — e.g. a product shelf with no products during a VTEX outage. Today
+// that degraded page is emitted as a healthy 200 and the edge caches it for the
+// full retention window, so stale-if-error never fires and users see an empty
+// page for hours. We record each CRITICAL section degradation on a
+// request-scoped collector; the CMS route reads it and emits `X-Deco-Degraded`
+// so the worker refuses to cache the broken page and serves stale instead.
+//
+// Every section is critical by default (a registered loader failing means
+// intended data is missing). Decorative sections whose empty state is harmless
+// can opt out via `registerNonCriticalSections`.
+// ---------------------------------------------------------------------------
+
+const DEGRADED_BAG_KEY = "deco:degraded-sections";
+const nonCriticalSections: Set<string> = G.__deco.nonCriticalSections;
+
+/** Mark section keys whose loader failure should NOT make the page uncacheable. */
+export function registerNonCriticalSections(keys: string[]): void {
+  for (const k of keys) nonCriticalSections.add(k);
+}
+
+/** A section is critical (its failure degrades the page) unless opted out. */
+export function isCriticalSection(key: string): boolean {
+  return !nonCriticalSections.has(key);
+}
+
+/**
+ * Record that a critical section rendered with raw props because its loader
+ * threw. No-op outside a request scope or for non-critical sections.
+ */
+export function markSectionDegraded(component: string): void {
+  if (!isCriticalSection(component)) return;
+  const set = RequestContext.getBag<Set<string>>(DEGRADED_BAG_KEY) ?? new Set<string>();
+  set.add(component);
+  RequestContext.setBag(DEGRADED_BAG_KEY, set);
+}
+
+/** Component keys of critical sections that degraded during this request. */
+export function getDegradedSections(): string[] {
+  const set = RequestContext.getBag<Set<string>>(DEGRADED_BAG_KEY);
+  return set ? [...set] : [];
+}
+
 // ---------------------------------------------------------------------------
 // Cacheable section loaders — SWR cache for section loader results
 // ---------------------------------------------------------------------------
@@ -368,9 +423,14 @@ function injectPageContext(
   return enriched;
 }
 
-/** Wrap a loader so it receives __pageUrl/__pagePath in its props. */
+/**
+ * Wrap a loader so it receives __pageUrl/__pagePath in its props AND the
+ * 3rd-arg compat `ctx` (issue #305). This is the single choke point that all
+ * four invocation paths (regular, layout, cacheable, SWR refresh) route
+ * through, so building `ctx` here covers every path.
+ */
 function withPageContext(loader: SectionLoaderFn): SectionLoaderFn {
-  return (props, req) => loader(injectPageContext(props, req), req);
+  return (props, req) => loader(injectPageContext(props, req), req, buildSectionLoaderContext(req));
 }
 
 /**
@@ -420,6 +480,11 @@ async function runSingleSectionLoaderImpl(
         result = await resolveLayoutSection(section, wrapped, request);
       } catch (error) {
         console.error(`[SectionLoader] Error in layout "${section.component}":`, error);
+        // Deliberately NOT marked degraded: layout sections (Header/Footer/Theme)
+        // render on every page, so a flaky layout loader would flip the whole
+        // site to X-Deco-Degraded and defeat edge caching everywhere. A failed
+        // layout renders raw chrome, which is acceptable — page-body data
+        // integrity (product shelves/PLP/PDP) is what the degraded signal guards.
         result = section;
       }
     } else {
@@ -429,6 +494,7 @@ async function runSingleSectionLoaderImpl(
           result = await runCacheableSectionLoader(section, wrapped, request, cacheConfig);
         } catch (error) {
           console.error(`[SectionLoader] Error in cacheable "${section.component}":`, error);
+          markSectionDegraded(section.component);
           result = section;
         }
       } else {
@@ -437,6 +503,7 @@ async function runSingleSectionLoaderImpl(
           result = { ...section, props: enrichedProps };
         } catch (error) {
           console.error(`[SectionLoader] Error in "${section.component}":`, error);
+          markSectionDegraded(section.component);
           result = section;
         }
       }

package/src/cms/sectionMixins.ts

@@ -83,10 +83,10 @@ export function withSearchParam(): SectionLoaderFn {
  * ```
  */
 export function compose(...mixins: SectionLoaderFn[]): SectionLoaderFn {
-  const composed: SectionLoaderFn = async (props, req) => {
+  const composed: SectionLoaderFn = async (props, req, ctx) => {
     let result = { ...props };
     for (const mixin of mixins) {
-      const partial = await mixin(result, req);
+      const partial = await mixin(result, req, ctx);
       result = { ...result, ...partial };
     }
     return result;
@@ -138,12 +138,14 @@ export function compose(...mixins: SectionLoaderFn[]): SectionLoaderFn {
 export function withSectionLoader(
   modImport: () => Promise<unknown>,
 ): SectionLoaderFn {
-  return async (props, req) => {
+  return async (props, req, ctx) => {
     const mod = (await modImport()) as { loader?: unknown } | undefined;
     const loader = mod?.loader;
     if (typeof loader !== "function") return props;
     try {
-      const result = await (loader as SectionLoaderFn)(props, req);
+      // Forward the compat `ctx` (issue #305) so migrated Fresh loaders that
+      // read `ctx.device`/`ctx.invoke`/`ctx.<app>` get the real 3rd argument.
+      const result = await (loader as SectionLoaderFn)(props, req, ctx);
       return result ?? props;
     } catch (error) {
       console.error("[withSectionLoader] section loader threw:", error);

package/src/sdk/invoke.ts

@@ -199,12 +199,71 @@ export function createAppInvoke<T extends Record<string, any>>(
   basePath?: string,
 ): NestedFromFlat<T>;
 export function createAppInvoke(basePath = "/deco/invoke"): any {
+  return createAppInvokeWith({ basePath });
+}
+
+/**
+ * Default nested invoke proxy bound to `/deco/invoke`.
+ *
+ * Replaces site-level `~/runtime.ts` shims that wrap the same `createAppInvoke`
+ * call. Importing this singleton means no per-site boilerplate.
+ *
+ * @example
+ * ```ts
+ * import { invoke } from "@decocms/start/sdk/invoke";
+ *
+ * await invoke.vtex.actions.checkout.addItemsToCart({ orderFormId, orderItems });
+ * await invoke.site.loaders.Wishlist.getWishlist({});
+ * ```
+ *
+ * For a custom `basePath` or typed handlers, call `createAppInvoke()` directly:
+ * ```ts
+ * const invoke = createAppInvoke<Handlers>("/my/invoke");
+ * ```
+ */
+export const invoke = createAppInvoke();
+
+/**
+ * A `fetch`-compatible function. Lets callers route the invoke proxy's HTTP
+ * calls through a custom transport — e.g. server-side, an absolute-origin
+ * self-fetch that injects the request's AbortSignal (`RequestContext.fetch`).
+ */
+export type InvokeFetcher = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+/**
+ * Like {@link createAppInvoke}, but with an injectable `fetcher`.
+ *
+ * The default `createAppInvoke` targets a relative path (`/deco/invoke`) via
+ * the global `fetch`, which only works in the browser. Server-side callers
+ * (e.g. a section loader's `ctx.invoke`) need an **absolute** base URL plus a
+ * fetcher that forwards the request's AbortSignal. This factory keeps the exact
+ * same nested-proxy semantics and 404→`.ts` retry, only swapping the transport.
+ *
+ * @example
+ * ```ts
+ * const origin = new URL(req.url).origin;
+ * const invoke = createAppInvokeWith({
+ *   basePath: `${origin}/deco/invoke`,
+ *   fetcher: (input, init) => RequestContext.fetch(input, init),
+ * });
+ * await invoke.vtex.loaders.product.detailsPageGQL({ slug });
+ * ```
+ */
+export function createAppInvokeWith(options?: { basePath?: string; fetcher?: InvokeFetcher }): any;
+export function createAppInvokeWith<T extends Record<string, any>>(options?: {
+  basePath?: string;
+  fetcher?: InvokeFetcher;
+}): NestedFromFlat<T>;
+export function createAppInvokeWith(options?: { basePath?: string; fetcher?: InvokeFetcher }): any {
+  const basePath = options?.basePath ?? "/deco/invoke";
+  const fetcher: InvokeFetcher = options?.fetcher ?? ((input, init) => fetch(input, init));
+
   function buildProxy(path: string[]): any {
     return new Proxy(
       Object.assign(async (props: any) => {
         const key = path.join("/");
         for (const k of [key, `${key}.ts`]) {
-          const response = await fetch(`${basePath}/${k}`, {
+          const response = await fetcher(`${basePath}/${k}`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify(props ?? {}),
@@ -237,24 +296,3 @@ export function createAppInvoke(basePath = "/deco/invoke"): any {
 
   return buildProxy([]);
 }
-
-/**
- * Default nested invoke proxy bound to `/deco/invoke`.
- *
- * Replaces site-level `~/runtime.ts` shims that wrap the same `createAppInvoke`
- * call. Importing this singleton means no per-site boilerplate.
- *
- * @example
- * ```ts
- * import { invoke } from "@decocms/start/sdk/invoke";
- *
- * await invoke.vtex.actions.checkout.addItemsToCart({ orderFormId, orderItems });
- * await invoke.site.loaders.Wishlist.getWishlist({});
- * ```
- *
- * For a custom `basePath` or typed handlers, call `createAppInvoke()` directly:
- * ```ts
- * const invoke = createAppInvoke<Handlers>("/my/invoke");
- * ```
- */
-export const invoke = createAppInvoke();

package/src/types/index.ts

@@ -4,8 +4,22 @@
  * without depending on the Deno-specific @deco/deco package.
  */
 
+/**
+ * Compat context handed to ported deco.cx (Fresh) section loaders as the 3rd
+ * argument (issue #305). `state` is the app state; `device`/`invoke`/`response`
+ * mirror what Fresh's `ctx` exposed, and the index signature lets migrated
+ * loaders read per-app state directly off `ctx` (`ctx.vtex`, `ctx.salesforce`).
+ * Deep reads should still be optional-chained — an unconfigured app is
+ * `undefined`. See `@decocms/blocks/cms`'s `SectionLoaderContext` for the
+ * runtime shape.
+ */
 export interface FnContext<TState = any> {
   state: TState;
+  device?: "mobile" | "tablet" | "desktop";
+  invoke?: any;
+  response?: { headers: Headers };
+  getAppState?: <T>(appName: string) => T | undefined;
+  [key: string]: any;
 }
 
 export type App<TManifest = any, TState = any, TDeps extends any[] = any[]> = {