@decocms/blocks 7.22.2 → 7.23.0

package/package.json

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

package/src/cms/index.ts

@@ -81,6 +81,8 @@ export {
   WELL_KNOWN_TYPES,
 } from "./resolve";
 export type { SectionLoaderFn } from "./sectionLoaders";
+export type { SectionLoaderContext } from "./sectionLoaderContext";
+export { buildSectionLoaderContext } from "./sectionLoaderContext";
 export {
   isLayoutSection,
   registerCacheableSections,

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

@@ -82,6 +82,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 +204,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 +241,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

@@ -14,10 +14,17 @@ 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
@@ -368,9 +375,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));
 }
 
 /**

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[]> = {