@decocms/blocks 7.66.7 → 7.67.1

package/package.json

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

package/src/cms/client.ts

@@ -25,6 +25,9 @@
  *   `sdk/requestContextStorage.browser.ts`), so it's already safe for a
  *   browser bundle.
  * - `schema.ts` has no imports at all.
+ * - `deferredTrigger.ts` has no imports at all — it only reads the
+ *   `globalThis.__deco.asyncConfig` bag `resolve.ts` writes, which is exactly
+ *   why it is a standalone module instead of living in `resolve.ts`.
  *
  * Deliberately NOT re-exported here: `loader.ts`, `resolve.ts`,
  * `sectionLoaders.ts`, `loadDecofileDirectory.ts`, `blockSource.ts`, and
@@ -33,6 +36,8 @@
  * storage concerns that only make sense server-side — import them from
  * `@decocms/blocks/cms` instead.
  */
+export type { DeferredTrigger } from "./deferredTrigger";
+export { DEFAULT_DEFERRED_TRIGGER, getDeferredTrigger } from "./deferredTrigger";
 export type { OnBeforeResolveProps, SectionModule, SectionOptions } from "./registry";
 export {
   getResolvedComponent,

package/src/cms/deferredTrigger.test.ts

@@ -0,0 +1,32 @@
+import { beforeEach, describe, expect, it } from "vitest";
+
+import { DEFAULT_DEFERRED_TRIGGER, getDeferredTrigger } from "./deferredTrigger";
+
+/**
+ * `getDeferredTrigger()` is the client-side half of `deferredTrigger`. It must
+ * read the same `globalThis.__deco.asyncConfig` bag `setAsyncRenderingConfig()`
+ * writes WITHOUT importing `resolve.ts` — that module pulls `node:async_hooks`
+ * and `node:fs/promises`, which a browser bundle cannot take (see the header of
+ * `cms/client.ts`). So this file imports only the standalone module, and sets
+ * the global by hand.
+ */
+describe("getDeferredTrigger", () => {
+  beforeEach(() => {
+    delete (globalThis as any).__deco;
+  });
+
+  it("falls back to intersection when setAsyncRenderingConfig() never ran", () => {
+    expect(getDeferredTrigger()).toBe("intersection");
+    expect(DEFAULT_DEFERRED_TRIGGER).toBe("intersection");
+  });
+
+  it("falls back to intersection when the config exists but omits the option", () => {
+    (globalThis as any).__deco = { asyncConfig: { respectCmsLazy: true } };
+    expect(getDeferredTrigger()).toBe("intersection");
+  });
+
+  it("reads load off the shared global", () => {
+    (globalThis as any).__deco = { asyncConfig: { deferredTrigger: "load" } };
+    expect(getDeferredTrigger()).toBe("load");
+  });
+});

package/src/cms/deferredTrigger.ts

@@ -0,0 +1,58 @@
+/**
+ * Client-safe reader for the deferred-section trigger mode.
+ *
+ * Lives in its own module — with zero imports — so a browser bundle can reach
+ * it without dragging in `resolve.ts` (and its `node:async_hooks` /
+ * `node:fs/promises` chain). Same reasoning as `cms/client.ts`; see the header
+ * comment there.
+ *
+ * The value itself is written by `setAsyncRenderingConfig()` in `resolve.ts`,
+ * into the same `globalThis.__deco.asyncConfig` bag the server reads.
+ *
+ * WHERE THE SETTING HAS TO RUN: this is read in the browser, so
+ * `setAsyncRenderingConfig()` only takes effect if it runs in a module the
+ * client bundle also loads — normally `setup.ts`, imported from `router.tsx`.
+ * Set it from server-only code (the worker entry, `server.ts`) and the server
+ * defers the section as expected while the client silently falls back to
+ * `"intersection"`, which looks exactly like the option being ignored.
+ *
+ * WHO READS IT: only `@decocms/tanstack` (`DeferredSectionWrapper` in
+ * `hooks/DecoPageRenderer.tsx`). It lives here because that is where
+ * `AsyncRenderingConfig` lives; in `@decocms/nextjs` it is a no-op.
+ */
+
+/**
+ * How a deferred (⚡) section decides it's time to fetch its real markup.
+ *
+ * - `"intersection"` — wait until the skeleton is within 300px of the viewport.
+ *   Cheapest, and the default.
+ * - `"load"` — fetch as soon as the wrapper mounts, without waiting for scroll.
+ *   This is what Deco on Fresh does through `DispatchAsyncRender`'s
+ *   `partialTriggerMode: "load"`: the page ships a light skeleton HTML and then
+ *   materializes every deferred section right after hydration. Sites migrating
+ *   from Fresh need this to keep parity — under `"intersection"` alone, content
+ *   below the fold does not exist until the user scrolls, which loses
+ *   below-the-fold analytics impressions and leaves the document short.
+ *
+ * The tradeoff of `"load"` is a request burst: every deferred section fires its
+ * serverFn POST in the same commit, on first load and again on every SPA
+ * navigation. That is precisely what the rAF + observer path exists to avoid,
+ * and it is also exactly what Fresh does — so it is the right default for a
+ * migrated site and the wrong one for a page with many heavy deferred sections.
+ * The switch is site-wide; a per-section override (honouring the `loading` prop
+ * the CMS `Lazy.tsx` wrapper already carries, which the resolver currently
+ * discards) would be the finer-grained successor.
+ */
+export type DeferredTrigger = "intersection" | "load";
+
+export const DEFAULT_DEFERRED_TRIGGER: DeferredTrigger = "intersection";
+
+/**
+ * Read the configured trigger. Falls back to `"intersection"` when
+ * `setAsyncRenderingConfig()` was never called or omitted the option, so
+ * existing sites are not regressed by a framework bump.
+ */
+export function getDeferredTrigger(): DeferredTrigger {
+  const config = (globalThis as any).__deco?.asyncConfig;
+  return config?.deferredTrigger ?? DEFAULT_DEFERRED_TRIGGER;
+}

package/src/cms/index.ts

@@ -15,6 +15,8 @@ export {
   revisionKey,
   snapshotKey,
 } from "./blockSource";
+export type { DeferredTrigger } from "./deferredTrigger";
+export { DEFAULT_DEFERRED_TRIGGER, getDeferredTrigger } from "./deferredTrigger";
 export type {
   DraftPointer,
   ResolveDraftForRequestOptions,

package/src/cms/resolve.test.ts

@@ -460,6 +460,17 @@ describe("async rendering config defaults", () => {
     expect(cfg!.foldThreshold).toBe(Infinity);
     expect(cfg!.respectCmsLazy).toBe(true);
     expect(cfg!.botAwareSeo).toBe(false); // opt-in — off by default
+    expect(cfg!.deferredTrigger).toBe("intersection"); // opt-in — a bump changes nothing
+  });
+
+  it("carries deferredTrigger through, and a later partial call does not reset it", () => {
+    setAsyncRenderingConfig({ deferredTrigger: "load" });
+    expect(getAsyncRenderingConfig()!.deferredTrigger).toBe("load");
+
+    // applySectionConventions() re-calls this with only `alwaysEager` after the
+    // site's setup.ts ran — the trigger must survive that merge.
+    setAsyncRenderingConfig({ alwaysEager: ["site/sections/Header.tsx"] });
+    expect(getAsyncRenderingConfig()!.deferredTrigger).toBe("load");
   });
 
   it("preserves an explicit finite foldThreshold (opt-in)", () => {
@@ -469,6 +480,9 @@ describe("async rendering config defaults", () => {
 });
 
 describe("shouldDeferSection — admin is the source of truth", () => {
+  // Deliberately does NOT set `deferredTrigger`: this literal stands in for the
+  // ones outside the package, and it has to keep compiling after the field was
+  // added. If that ever breaks, the option stopped being backwards compatible.
   const mkCfg = (over: Partial<AsyncRenderingConfig> = {}): AsyncRenderingConfig => ({
     respectCmsLazy: true,
     foldThreshold: Infinity,

package/src/cms/resolve.ts

@@ -8,6 +8,7 @@ import { parseSegmentCookie, SEGMENT_COOKIE, type StoredFlag, trafficToPct } fro
 import { withInflightTimeout } from "../sdk/inflightTimeout";
 import { normalizeUrlsInObject } from "../sdk/normalizeUrls";
 import { stripTrackingParams } from "../sdk/urlUtils";
+import { DEFAULT_DEFERRED_TRIGGER, type DeferredTrigger } from "./deferredTrigger";
 import { findPageByPath, loadBlocks } from "./loader";
 import { getOnBeforeResolveProps, getSection, registerOnBeforeResolveProps } from "./registry";
 import {
@@ -113,6 +114,34 @@ export interface AsyncRenderingConfig {
    * @default true
    */
   respectCmsLazy: boolean;
+  /**
+   * When a deferred (⚡) section fetches its real markup on the client.
+   *
+   * `"intersection"` (default) waits for the skeleton to come within 300px of
+   * the viewport. `"load"` fetches as soon as the wrapper mounts — the
+   * behaviour Deco on Fresh gets from `DispatchAsyncRender`'s
+   * `partialTriggerMode: "load"`, where the page ships a light skeleton and
+   * then materializes every deferred section right after hydration.
+   *
+   * Sites migrating from Fresh generally want `"load"`: under `"intersection"`
+   * alone, everything below the fold does not exist until the user scrolls, so
+   * the document stays short and below-the-fold analytics impressions are lost.
+   * The cost is a request burst — every deferred section POSTs in the same
+   * commit, on load and on each SPA navigation.
+   *
+   * Read on the CLIENT, so it must be set from a module the browser bundle also
+   * loads (normally `setup.ts`, imported from `router.tsx`). Setting it from
+   * server-only code leaves the client on `"intersection"` with no warning.
+   * Only `@decocms/tanstack` reads it; a no-op in `@decocms/nextjs`.
+   *
+   * Optional on purpose. `setAsyncRenderingConfig()` always fills it, so the
+   * stored config never actually lacks it — but this interface is exported from
+   * `@decocms/blocks/cms`, and a required field would break the typecheck of
+   * anyone outside the package who builds an `AsyncRenderingConfig` literal.
+   * The only sanctioned reader, `getDeferredTrigger()`, already defaults.
+   * @default "intersection"
+   */
+  deferredTrigger?: DeferredTrigger;
   /**
    * Fold threshold: sections at or above this flat index are DEFERRED
    * (rendered as a skeleton and loaded on scroll), so their resolved props are
@@ -193,12 +222,15 @@ export function setAsyncRenderingConfig(config?: {
   foldThreshold?: number;
   alwaysEager?: string[];
   respectCmsLazy?: boolean;
+  deferredTrigger?: DeferredTrigger;
   botAwareSeo?: boolean;
 }): void {
   const existing = getAsyncConfig();
   const merged = new Set([...(existing?.alwaysEager ?? []), ...(config?.alwaysEager ?? [])]);
   G.__deco.asyncConfig = {
     respectCmsLazy: config?.respectCmsLazy ?? existing?.respectCmsLazy ?? true,
+    deferredTrigger:
+      config?.deferredTrigger ?? existing?.deferredTrigger ?? DEFAULT_DEFERRED_TRIGGER,
     foldThreshold: config?.foldThreshold ?? existing?.foldThreshold ?? DEFAULT_FOLD_THRESHOLD,
     alwaysEager: merged,
     botAwareSeo: config?.botAwareSeo ?? existing?.botAwareSeo ?? false,