@decocms/blocks 7.66.6 → 7.67.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks",
-  "version": "7.66.6",
+  "version": "7.67.0",
   "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/loader.test.ts

@@ -222,6 +222,79 @@ describe("findPageByPath specificity", () => {
   });
 });
 
+describe("getAllPages — page blocks without the `pages-` prefix", () => {
+  afterEach(() => {
+    setBlocks({});
+  });
+
+  it("routes a page block whose key lacks the prefix", () => {
+    // Decofiles carried over from Deco on Fresh hold page blocks under
+    // arbitrary keys: renaming a page in the CMS renames its snapshot file,
+    // and the key follows the filename. Fresh enumerated pages by
+    // __resolveType, so these routed fine there.
+    setBlocks({
+      "plp-verao": {
+        name: "Verão",
+        path: "/verao",
+        sections: [],
+        __resolveType: "website/pages/Page.tsx",
+      },
+    });
+
+    const match = findPageByPath("/verao");
+    expect(match?.blockKey).toBe("plp-verao");
+  });
+
+  it("still ranks by path specificity across both key shapes", () => {
+    setBlocks({
+      "pages-catch-all": {
+        name: "Catch all",
+        path: "/*",
+        sections: [],
+      },
+      "plp-inverno": {
+        name: "Inverno",
+        path: "/inverno",
+        sections: [],
+        __resolveType: "website/pages/Page.tsx",
+      },
+    });
+
+    // The literal must win over the catch-all regardless of which one
+    // carries the prefix.
+    expect(findPageByPath("/inverno")?.blockKey).toBe("plp-inverno");
+    expect(findPageByPath("/qualquer-outra")?.blockKey).toBe("pages-catch-all");
+  });
+
+  it("ignores non-page blocks that happen to carry a path", () => {
+    // A loader block is not a page: no __resolveType match, no prefix.
+    setBlocks({
+      "some-loader": {
+        name: "Not a page",
+        path: "/not-a-page",
+        sections: [],
+        __resolveType: "site/loaders/whatever.ts",
+      },
+    });
+
+    expect(findPageByPath("/not-a-page")).toBeNull();
+  });
+
+  it("keeps honouring the prefix when there is no __resolveType", () => {
+    // The admin emits prefixed keys and does not always write a
+    // __resolveType onto the snapshot — the fast path must still apply.
+    setBlocks({
+      "pages-sem-tipo": {
+        name: "Sem tipo",
+        path: "/sem-tipo",
+        sections: [],
+      },
+    });
+
+    expect(findPageByPath("/sem-tipo")?.blockKey).toBe("pages-sem-tipo");
+  });
+});
+
 describe("loadBlocks draft override — key percent-encoding", () => {
   // The published decofile encodes special characters in block keys
   // (`pages-Home%20(principal)-1`); the Studio draft emits them raw

package/src/cms/loader.ts

@@ -282,6 +282,36 @@ function pathSpecificityKey(path: string): [number, number, number] {
   return [hasWildcard ? 0 : 1, literals, params];
 }
 
+// Literal rather than WELL_KNOWN_TYPES.PAGE: resolve.ts already imports from
+// this module, so importing back would close a cycle.
+const PAGE_RESOLVE_TYPE = "website/pages/Page.tsx";
+
+/**
+ * Is this block a page?
+ *
+ * The `pages-` prefix is kept as a fast path because it is what the admin
+ * emits and it short-circuits the vast majority of blocks without a property
+ * read. But it cannot be the *only* test: a decofile carried over from Deco on
+ * Fresh can hold page blocks under any key — renaming one in the CMS renames
+ * its snapshot file, and `loadDecofileDirectory` preserves whatever key the
+ * filename already had.
+ *
+ * Those blocks are pages in every way that matters (`website/pages/Page.tsx`,
+ * a `path`, `sections`), and on Fresh they routed fine: `website/loaders/pages.ts`
+ * enumerated by `__resolveType`, not by key. Filtering on the prefix alone makes
+ * them invisible, so every one of their URLs falls through to whatever catch-all
+ * the site has — usually a 404 — and they disappear from the CMS sitemap too.
+ * One storefront in this state has 205 such blocks against 107 prefixed ones.
+ */
+function isPageBlock(key: string, block: unknown): boolean {
+  if (key.startsWith("pages-")) return true;
+  return (
+    typeof block === "object" &&
+    block !== null &&
+    (block as Resolvable).__resolveType === PAGE_RESOLVE_TYPE
+  );
+}
+
 export function getAllPages(): Array<{ key: string; page: DecoPage }> {
   const blocks = loadBlocks();
   const pages: Array<{
@@ -291,7 +321,7 @@ export function getAllPages(): Array<{ key: string; page: DecoPage }> {
   }> = [];
 
   for (const [key, block] of Object.entries(blocks)) {
-    if (!key.startsWith("pages-")) continue;
+    if (!isPageBlock(key, block)) continue;
     const page = block as DecoPage;
     if (!page.sections) continue;
     if (!page.path) continue;

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,