@decocms/blocks 7.34.2 → 7.34.3

package/package.json

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

package/src/cms/applySectionConventions.ts

@@ -10,6 +10,7 @@ import { registerSection, registerSectionsSync } from "./registry";
 import {
   type AsyncRenderingConfig,
   getAsyncRenderingConfig,
+  registerAlwaysDeferSections,
   registerEagerSections,
   registerNeverDeferSections,
   registerSeoSections,
@@ -24,6 +25,7 @@ import {
 export interface SectionMetaEntry {
   eager?: boolean;
   neverDefer?: boolean;
+  deferred?: boolean;
   cache?: string;
   layout?: boolean;
   sync?: boolean;
@@ -48,6 +50,7 @@ export function applySectionConventions(input: ApplySectionConventionsInput): vo
 
   const eagerSections: string[] = [];
   const neverDeferSections: string[] = [];
+  const alwaysDeferSections: string[] = [];
   const layoutSections: string[] = [];
   const seoSections: string[] = [];
   const cacheableSections: Record<string, CacheableSectionInput> = {};
@@ -55,6 +58,7 @@ export function applySectionConventions(input: ApplySectionConventionsInput): vo
   for (const [key, entry] of Object.entries(meta)) {
     if (entry.eager) eagerSections.push(key);
     if (entry.neverDefer) neverDeferSections.push(key);
+    if (entry.deferred) alwaysDeferSections.push(key);
     if (entry.layout) layoutSections.push(key);
     if (entry.seo) seoSections.push(key);
     if (entry.cache) cacheableSections[key] = entry.cache as CacheableSectionInput;
@@ -88,6 +92,10 @@ export function applySectionConventions(input: ApplySectionConventionsInput): vo
     registerNeverDeferSections(neverDeferSections);
   }
 
+  if (alwaysDeferSections.length > 0) {
+    registerAlwaysDeferSections(alwaysDeferSections);
+  }
+
   // Always initialize asyncConfig so CMS Lazy deferral (`respectCmsLazy`) is
   // active — this is what makes the admin ⚡ toggle the source of truth. Without
   // it, asyncConfig stays null, `useAsync` is false in resolveDecoPage, and

package/src/cms/resolve.test.ts

@@ -32,6 +32,7 @@ import {
   isEagerRequest,
   registerCommerceLoader,
   registerEagerSections,
+  registerAlwaysDeferSections,
   registerNeverDeferSections,
   resolveDecoPage,
   resolveDeferredSectionFull,
@@ -468,6 +469,22 @@ describe("shouldDeferSection — admin is the source of truth", () => {
     expect(shouldDeferSection(section, 5, mkCfg({ foldThreshold: 3 }), false)).toBe(true);
     expect(shouldDeferSection(section, 1, mkCfg({ foldThreshold: 3 }), false)).toBe(false);
   });
+
+  it("`export const deferred = true` defers one section even with respectCmsLazy off", () => {
+    const key = "site/sections/HeavyPLP.tsx";
+    registerAlwaysDeferSections([key]);
+    const section = { __resolveType: key };
+    // Not ⚡-wrapped and respectCmsLazy disabled — the per-section flag is the
+    // only thing forcing deferral here.
+    expect(shouldDeferSection(section, 0, mkCfg({ respectCmsLazy: false }), false)).toBe(true);
+  });
+
+  it("`export const deferred = true` still stays eager for bots (SEO)", () => {
+    const key = "site/sections/HeavyPLPBot.tsx";
+    registerAlwaysDeferSections([key]);
+    const section = { __resolveType: key };
+    expect(shouldDeferSection(section, 0, mkCfg({ respectCmsLazy: false }), true)).toBe(false);
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/cms/resolve.ts

@@ -243,6 +243,28 @@ function isNeverDeferSection(key: string): boolean {
   return (G.__deco.neverDeferSectionKeys as Set<string> | undefined)?.has(key) ?? false;
 }
 
+// ---------------------------------------------------------------------------
+// Permanent alwaysDefer section registry
+// ---------------------------------------------------------------------------
+
+/**
+ * Register sections that declared `export const deferred = true`.
+ * These sections are ALWAYS deferred (rendered client-side on scroll),
+ * independent of the global `respectCmsLazy` config — the per-section opt-in
+ * for async-rendering a single heavy section (e.g. a PLP grid) without
+ * turning on deferral site-wide. Bots stay eager via the `isBotReq`
+ * short-circuit in {@link shouldDeferSection}.
+ */
+export function registerAlwaysDeferSections(keys: string[]): void {
+  G.__deco.alwaysDeferSectionKeys ??= new Set();
+  const set: Set<string> = G.__deco.alwaysDeferSectionKeys;
+  for (const k of keys) set.add(k);
+}
+
+function isAlwaysDeferSection(key: string): boolean {
+  return (G.__deco.alwaysDeferSectionKeys as Set<string> | undefined)?.has(key) ?? false;
+}
+
 // ---------------------------------------------------------------------------
 // Deferred rawProps cache — keeps rawProps server-side to trim HTML payload
 // ---------------------------------------------------------------------------
@@ -1497,6 +1519,12 @@ export function shouldDeferSection(
   const finalKey = resolveFinalSectionKey(section, matcherCtx);
   if (!finalKey) return false;
 
+  // ── PER-SECTION FORCE-DEFER (`export const deferred = true`) ───────────────
+  // Explicit code-level opt-in to defer one section regardless of the global
+  // `respectCmsLazy` config — lets a site async-render a single heavy section
+  // without a site-wide skeleton sweep. Bots already returned eager above.
+  if (isAlwaysDeferSection(finalKey)) return true;
+
   // ── ADMIN IS THE SOURCE OF TRUTH ──────────────────────────────────────────
   // If the editor marked the section ⚡ (wrapped in CMS Lazy/Deferred at any
   // nesting level, including multivariate flags), it is deferred —