@decocms/blocks 7.60.0 → 7.62.0

package/package.json

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

package/src/cms/index.ts

@@ -85,6 +85,7 @@ export type {
   DanglingReferenceHandler,
   DecoPageResult,
   DeferredSection,
+  Deferred,
   MatcherContext,
   PageSeo,
   ResolvedSection,
@@ -97,10 +98,12 @@ export {
   clearCommerceLoaders,
   evaluateMatcher,
   extractSeoFromProps,
+  asResolved,
   extractSeoFromSections,
   getAsyncRenderingConfig,
   getDeferredRawProps,
   isBot,
+  isDeferred,
   isEagerRequest,
   isSeoSection,
   onBeforeResolve,
@@ -113,6 +116,7 @@ export {
   registerNeverDeferSections,
   registerSeoSections,
   resolveDecoPage,
+  resolveDeferred,
   resolveDeferredSection,
   resolveDeferredSectionFull,
   resolvePageSections,

package/src/cms/resolve.test.ts

@@ -25,14 +25,18 @@ import { findPageByPath } from "./loader";
 import { getSection } from "./registry";
 import type { AsyncRenderingConfig, DeferredSection, MatcherContext } from "./resolve";
 import {
+  asResolved,
   clearCommerceLoaders,
+  layoutCacheKey,
   DEFAULT_FOLD_THRESHOLD,
   extractSeoFromProps,
   getAsyncRenderingConfig,
+  isDeferred,
   isEagerRequest,
   reExtractRawProps,
   registerCommerceLoader,
   registerMatcher,
+  resolveDeferred,
   registerEagerSections,
   registerAlwaysDeferSections,
   registerNeverDeferSections,
@@ -1170,3 +1174,160 @@ describe("hidden array items (never matcher)", () => {
     expect(result.items).toEqual([null, { label: "kept" }]);
   });
 });
+
+// ---------------------------------------------------------------------------
+// resolved-layout cache — device is part of the key
+// ---------------------------------------------------------------------------
+//
+// The key used to be the component path alone, so the first visitor's variant
+// was served to everyone for the whole TTL. A real store had to leave Header
+// and Footer OUT of registerLayoutSections because of it, and then re-resolved
+// both on every page and every navigation. These cases pin the axis; without
+// them a refactor could silently collapse the key again and the symptom (a
+// mobile header on desktop) only shows up in production, minutes later.
+
+describe("layoutCacheKey — the resolved-layout cache is segmented by device", () => {
+  const MOBILE_UA = "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0) Mobile Safari";
+  const TABLET_UA = "Mozilla/5.0 (iPad; CPU OS 17_0) Safari/605";
+  const DESKTOP_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Chrome/120 Safari/537.36";
+  const KEY = "site/sections/Header.tsx";
+
+  // The key used to be the component path alone. A site whose Header takes a
+  // per-request device prop therefore served the first visitor's variant to
+  // everyone for the whole 5-minute TTL — a mobile header on desktop. The only
+  // escape was leaving Header/Footer out of `registerLayoutSections`, which is
+  // what a real store did, and it then re-resolved both on every page and every
+  // navigation.
+
+  it("mobile, tablet and desktop are three distinct keys", () => {
+    const keys = [MOBILE_UA, TABLET_UA, DESKTOP_UA].map((ua) => layoutCacheKey(KEY, { userAgent: ua }));
+    expect(new Set(keys).size).toBe(3);
+  });
+
+  it("the same device yields the same key — the cache still works", () => {
+    expect(layoutCacheKey(KEY, { userAgent: DESKTOP_UA })).toBe(
+      layoutCacheKey(KEY, { userAgent: DESKTOP_UA }),
+    );
+  });
+
+  it("different components never share a key on the same device", () => {
+    expect(layoutCacheKey("site/sections/Header.tsx", { userAgent: MOBILE_UA })).not.toBe(
+      layoutCacheKey("site/sections/Footer.tsx", { userAgent: MOBILE_UA }),
+    );
+  });
+
+  it("a missing userAgent still produces a key (no crash, no undefined axis)", () => {
+    const noCtx = layoutCacheKey(KEY);
+    expect(noCtx).toContain(KEY);
+    expect(noCtx).not.toContain("undefined");
+    // An absent UA must land on the SAME bucket as a request whose UA is empty,
+    // so a health check and a real desktop hit do not fragment the cache twice.
+    expect(noCtx).toBe(layoutCacheKey(KEY, { userAgent: "" }));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// asResolved / deferred props
+// ---------------------------------------------------------------------------
+//
+// The CMS resolver is recursive and resolves EVERY `__resolveType` it finds in a
+// section's props — including branches the section will not render. Measured on
+// a real store, a PDP's `notFoundSections` (the 404 fallback) carried a shelf
+// whose `products` was a full-text search: 1703ms of the eager critical path of
+// every product page, result thrown away. `asResolved(v, true)` is the opt-out.
+
+describe("asResolved — deferred props", () => {
+  const LOADER = "test/loaders/expensive.ts";
+  let calls = 0;
+
+  beforeEach(() => {
+    calls = 0;
+    clearCommerceLoaders();
+    registerCommerceLoader(LOADER, async () => {
+      calls += 1;
+      return { products: ["p1", "p2"] };
+    });
+  });
+
+  afterEach(() => clearCommerceLoaders());
+
+  const expensive = { __resolveType: LOADER };
+
+  it("without asResolved the loader runs during the page pass", async () => {
+    const out = (await resolveValue({ fallback: expensive })) as any;
+    expect(calls).toBe(1);
+    expect(out.fallback).toEqual({ products: ["p1", "p2"] });
+  });
+
+  it("asResolved(v) hands the value back untouched — the loader never runs", async () => {
+    const out = (await resolveValue({ fallback: asResolved(expensive) })) as any;
+    expect(calls).toBe(0);
+    // The raw node comes through, NOT its resolution.
+    expect(out.fallback).toEqual(expensive);
+  });
+
+  it("asResolved(v, true) yields a thunk and does NOT resolve until called", async () => {
+    const out = (await resolveValue({ fallback: asResolved(expensive, true) })) as any;
+
+    expect(calls).toBe(0);
+    expect(isDeferred(out.fallback)).toBe(true);
+
+    expect(await resolveDeferred(out.fallback)).toEqual({ products: ["p1", "p2"] });
+    expect(calls).toBe(1);
+  });
+
+  it("the branch that never calls the thunk pays nothing", async () => {
+    const out = (await resolveValue({
+      shown: expensive,
+      fallback: asResolved(expensive, true),
+    })) as any;
+    // Only the rendered branch resolved. This is the whole point: 1 upstream
+    // call instead of 2 for a page that renders one of the two.
+    expect(calls).toBe(1);
+    expect(out.shown).toEqual({ products: ["p1", "p2"] });
+  });
+
+  it("a thunk is dropped by JSON.stringify — the unused branch leaves the payload too", async () => {
+    const out = (await resolveValue({ fallback: asResolved(expensive, true) })) as any;
+    expect(JSON.parse(JSON.stringify(out))).toEqual({});
+  });
+
+  it("resolveDeferred is tolerant of a plain value (admin preview path)", async () => {
+    // The admin preview does not run `onBeforeResolveProps`, so the prop arrives
+    // already resolved. A section must read the same either way.
+    expect(await resolveDeferred([{ a: 1 }])).toEqual([{ a: 1 }]);
+    expect(await resolveDeferred(undefined)).toBeUndefined();
+  });
+
+  it("the thunk resolves in THIS request's context, not a context-free one", async () => {
+    // The invariant that makes deferring safe: a cookie/UA-gated prop must not
+    // silently resolve against an anonymous request when the section calls it.
+    const PROBE = "test/matchers/deferredProbe.ts";
+    const seen: MatcherContext[] = [];
+    registerMatcher(PROBE, (_rule, ctx) => {
+      seen.push(ctx);
+      return true;
+    });
+    const gated = {
+      __resolveType: WELL_KNOWN_TYPES.MULTIVARIATE,
+      variants: [{ rule: { __resolveType: PROBE }, value: expensive }],
+    };
+    const ctx: MatcherContext = {
+      userAgent: "Mozilla/5.0 (iPhone) Mobile Safari",
+      url: "https://store.com/x/p",
+      cookies: { VtexIdclientAutCookie: "tok" },
+    };
+
+    const out = (await resolveValue({ fallback: asResolved(gated, true) }, undefined, ctx)) as any;
+    expect(seen).toHaveLength(0); // nothing evaluated yet
+
+    await resolveDeferred(out.fallback);
+
+    expect(seen).not.toHaveLength(0);
+    for (const c of seen) {
+      expect(c.cookies).toEqual(ctx.cookies);
+      expect(c.userAgent).toBe(ctx.userAgent);
+      expect(c.url).toBe(ctx.url);
+    }
+  });
+});

package/src/cms/resolve.ts

@@ -14,6 +14,7 @@ import {
   registerActionSchemas,
   registerLoaderSchemas,
 } from "./schema";
+import { detectDevice } from "../sdk/detectDevice";
 import { isLayoutSection, markSectionDegraded, runSingleSectionLoader } from "./sectionLoaders";
 
 // globalThis-backed: share state across Vite server function split modules
@@ -868,8 +869,38 @@ async function internalResolve(value: unknown, rctx: ResolveContext): Promise<un
 
   const childCtx: ResolveContext = { ...rctx, depth: rctx.depth + 1 };
 
-  // "resolved" short-circuit
-  if (resolveType === "resolved") return obj.data ?? null;
+  // ── `asResolved` ─────────────────────────────────────────────────────────
+  //
+  // `{ __resolveType: "resolved", data }` hands `data` back untouched — the
+  // caller is telling us it is already resolved.
+  //
+  // With `deferred: true` it instead becomes a THUNK, and `data` is not walked
+  // at all during the page pass. That is the point: the CMS resolver is
+  // recursive and resolves every `__resolveType` it finds in a section's props,
+  // including branches the section will not render. Measured on a real store, a
+  // PDP's `notFoundSections` — the 404 fallback — carried a shelf whose
+  // `products` was a full-text search: 1703ms of the EAGER critical path of
+  // EVERY product page, with the result thrown away. Same shape applies to tab
+  // content, modal content and unmatched A/B branches.
+  //
+  // The thunk closes over `childCtx`, so resolving it later still sees THIS
+  // request: cookies, UA and url reach the matchers, and `rctx.memo` dedupes
+  // named-block references the page already resolved. It does NOT dedupe
+  // commerce loaders — those are keyed by their own cache layer, not the memo
+  // (see the "Named block reference (memoized)" branch), so a deferred prop
+  // pointing at the same loader as a rendered one still calls it twice.
+  //
+  // HAZARD, and it is why this is opt-in per prop: a thunk cannot be
+  // serialized. If a section defers a prop and never calls it, the prop reaches
+  // the client as `undefined` (JSON.stringify drops functions). Defer only what
+  // the section itself resolves, and only on the branch that needs it.
+  if (resolveType === "resolved") {
+    if (obj.deferred === true) {
+      const raw = obj.data;
+      return () => internalResolve(raw, childCtx);
+    }
+    return obj.data ?? null;
+  }
 
   // Lazy section wrapper — unwrap single inner section
   if (resolveType === WELL_KNOWN_TYPES.LAZY) {
@@ -1105,6 +1136,33 @@ interface ResolvedSectionsCache {
 const resolvedLayoutCache = new Map<string, ResolvedSectionsCache>();
 const resolvedLayoutInflight = new Map<string, Promise<ResolvedSection[]>>();
 
+/**
+ * Cache key for a resolved layout block, segmented by DEVICE.
+ *
+ * The key used to be the component path alone, and that made the cache unusable
+ * for any site whose Header/Footer takes a per-request device prop: the first
+ * visitor's variant was served to everyone for the whole TTL (mobile header on
+ * desktop and vice-versa). The only escape was to leave those sections out of
+ * `registerLayoutSections` entirely — which is what a real store did, and it
+ * then re-resolved Header and Footer on every single page and navigation.
+ *
+ * Device is the right default axis because it is the one thing the framework
+ * itself injects into every section (`sectionLoaderContext` → `detectDevice`),
+ * so a layout section can depend on it WITHOUT the site opting into anything.
+ * A layout that does not vary by device just gets up to 3 identical entries —
+ * a bounded, negligible cost against silently serving the wrong markup.
+ *
+ * Anything else a layout varies on (region, sales channel, locale) is
+ * site-specific and NOT covered here: those sections should stay out of
+ * `registerLayoutSections` until there is a demonstrated need for a `vary`
+ * hook. Adding axes nobody asked for only shrinks the hit rate.
+ *
+ * Exported for unit testing.
+ */
+export function layoutCacheKey(blockKey: string, matcherCtx?: MatcherContext): string {
+  return `${blockKey}::${detectDevice(matcherCtx?.userAgent ?? "")}`;
+}
+
 function getCachedResolvedLayout(blockKey: string): ResolvedSection[] | null {
   const entry = resolvedLayoutCache.get(blockKey);
   if (!entry) return null;
@@ -1754,6 +1812,65 @@ export async function resolveSectionsList(
   return [];
 }
 
+// ---------------------------------------------------------------------------
+// Deferred props (`asResolved`)
+// ---------------------------------------------------------------------------
+
+/** A prop deferred with `asResolved(value, true)`: call it to resolve. */
+export type Deferred<T> = () => Promise<T>;
+
+/**
+ * Mark a prop as already-resolved, or defer its resolution to the section.
+ *
+ * Use it from a section's `onBeforeResolveProps`, which runs on the RAW CMS
+ * props before the resolver walks them:
+ *
+ * ```ts
+ * export const onBeforeResolveProps = (props: Props) => ({
+ *   ...props,
+ *   // The 404 fallback: only the branch that renders it should pay for it.
+ *   notFoundSections: asResolved(props.notFoundSections, true),
+ * })
+ *
+ * export const loader = async (props: Props) => {
+ *   if (props.page) return { ...props, notFoundSections: [] }
+ *   return { ...props, notFoundSections: await resolveDeferred(props.notFoundSections) }
+ * }
+ * ```
+ *
+ * - `asResolved(v)` — hand `v` back untouched; the resolver does not walk it.
+ * - `asResolved(v, true)` — the section receives a {@link Deferred} thunk and
+ *   decides whether to pay for it.
+ *
+ * A deferred prop that is never called reaches the client as `undefined`: a
+ * thunk cannot be serialized. That is deliberate — it is what keeps the unused
+ * branch out of the hydration payload too — but it means you must resolve it on
+ * the branch that renders it.
+ */
+export function asResolved<T>(value: T, defer?: boolean): T {
+  return {
+    __resolveType: "resolved",
+    data: value,
+    ...(defer ? { deferred: true } : {}),
+  } as unknown as T;
+}
+
+/** True when a prop came through as a {@link Deferred} thunk. */
+export function isDeferred<T>(value: unknown): value is Deferred<T> {
+  return typeof value === "function";
+}
+
+/**
+ * Resolve a possibly-deferred prop.
+ *
+ * Tolerant of a plain value, so a section reads the same whether the prop was
+ * deferred, marked already-resolved, or left alone — and so the admin preview
+ * (which does not run `onBeforeResolveProps`) keeps working.
+ */
+export async function resolveDeferred<T>(value: Deferred<T> | T): Promise<T> {
+  return isDeferred<T>(value) ? await value() : (value as T);
+}
+
 // ---------------------------------------------------------------------------
 // Page-level SEO — extracted from registered SEO sections after resolution
 // ---------------------------------------------------------------------------
@@ -2127,20 +2244,21 @@ async function resolveDecoPageImpl(
           const layoutKey = isRawSectionLayout(section);
 
           if (layoutKey) {
-            const cached = getCachedResolvedLayout(layoutKey);
+            const cacheKey = layoutCacheKey(layoutKey, rctx.matcherCtx);
+            const cached = getCachedResolvedLayout(cacheKey);
             if (cached) return cached;
 
-            const inflight = resolvedLayoutInflight.get(layoutKey);
+            const inflight = resolvedLayoutInflight.get(cacheKey);
             if (inflight) return inflight;
 
             const p = withInflightTimeout(
               resolveRawSection(section, rctx).then((results) => {
-                setCachedResolvedLayout(layoutKey, results);
+                setCachedResolvedLayout(cacheKey, results);
                 return results;
               }),
-              `resolvedLayout ${layoutKey}`,
-            ).finally(() => resolvedLayoutInflight.delete(layoutKey));
-            resolvedLayoutInflight.set(layoutKey, p);
+              `resolvedLayout ${cacheKey}`,
+            ).finally(() => resolvedLayoutInflight.delete(cacheKey));
+            resolvedLayoutInflight.set(cacheKey, p);
             return p;
           }
 
@@ -2224,20 +2342,21 @@ export async function resolvePageSections(
         const layoutKey = isRawSectionLayout(section);
 
         if (layoutKey) {
-          const cached = getCachedResolvedLayout(layoutKey);
+          const cacheKey = layoutCacheKey(layoutKey, rctx.matcherCtx);
+          const cached = getCachedResolvedLayout(cacheKey);
           if (cached) return cached;
 
-          const inflight = resolvedLayoutInflight.get(layoutKey);
+          const inflight = resolvedLayoutInflight.get(cacheKey);
           if (inflight) return inflight;
 
           const p = withInflightTimeout(
             resolveRawSection(section, rctx).then((results) => {
-              setCachedResolvedLayout(layoutKey, results);
+              setCachedResolvedLayout(cacheKey, results);
               return results;
             }),
-            `resolvedLayout ${layoutKey}`,
-          ).finally(() => resolvedLayoutInflight.delete(layoutKey));
-          resolvedLayoutInflight.set(layoutKey, p);
+            `resolvedLayout ${cacheKey}`,
+          ).finally(() => resolvedLayoutInflight.delete(cacheKey));
+          resolvedLayoutInflight.set(cacheKey, p);
           return p;
         }