@decocms/tanstack 8.0.0 → 8.1.0-next.0

package/src/index.ts

@@ -1,7 +1,17 @@
 export {
+  DecoPageRenderer,
+  DecoRootLayout,
+  DraftPreviewIndicator,
+  NavigationProgress,
+  PreviewProviders,
+  SectionList,
+  SectionRenderer,
+  StableOutlet,
+} from "./hooks";
+export {
+  CmsPage,
   cmsHomeRouteConfig,
   cmsRouteConfig,
-  CmsPage,
   decoInvokeRouteConfig,
   decoMetaRouteConfig,
   decoRenderRouteConfig,
@@ -11,23 +21,23 @@ export {
   NotFoundPage,
   withSiteGlobals,
 } from "./routes";
-export {
-  DecoPageRenderer,
-  DecoRootLayout,
-  NavigationProgress,
-  PreviewProviders,
-  SectionList,
-  SectionRenderer,
-  StableOutlet,
-} from "./hooks";
-export { createDecoWorkerEntry } from "./sdk/workerEntry";
-export { setupTanstackFastDeploy } from "./setupFastDeploy";
+export type { CreateDecoRouterOptions } from "./sdk/router";
 export {
   createDecoRouter,
   decoParseSearch,
   decoStringifySearch,
 } from "./sdk/router";
-export type { CreateDecoRouterOptions } from "./sdk/router";
+export type {
+  SpeculationAction,
+  SpeculationEagerness,
+  SpeculationRulesConfig,
+} from "./sdk/speculationRules";
+export {
+  buildSpeculationRules,
+  DEFAULT_EXCLUDED_HREF_MATCHES,
+} from "./sdk/speculationRules";
+export { createDecoWorkerEntry } from "./sdk/workerEntry";
+export { setupTanstackFastDeploy } from "./setupFastDeploy";
 // createInvokeFn is intentionally NOT re-exported from this root barrel.
 // Its body contains a `createServerFn(...).handler(...)` call that is not a
 // top-level variable declarator (it's returned from a factory function) --
@@ -42,3 +52,10 @@ export type { CreateDecoRouterOptions } from "./sdk/router";
 // parses (never imports) to emit real top-level createServerFn declarations
 // into each site's own src/server/invoke.gen.ts. Import it from the
 // dedicated "@decocms/tanstack/sdk/createInvoke" subpath instead.
+// decoServerFnFetch is intentionally NOT re-exported from this root barrel
+// either. A site wires it in `src/start.ts`, which is part of the CLIENT
+// bundle; importing it from here would drag `createDecoWorkerEntry` (and the
+// whole server graph behind it) into that bundle. Import it from the dedicated
+// "@decocms/tanstack/sdk/serverFnFetch" subpath instead.
+// Next major (v8): the binding's documented surface. See /next/api-reference#loaders.
+export { kvLoader } from "./v8/kvLoader";

package/src/routes/cmsRoute.test.ts

@@ -1,9 +1,17 @@
-import { registerCacheableSections, registerSectionLoader } from "@decocms/blocks/cms";
+import {
+  registerCacheableSections,
+  registerSectionLoader,
+  runSectionLoaders,
+} from "@decocms/blocks/cms";
 import type { ResolvedSection } from "@decocms/blocks/cms";
 import { describe, expect, it } from "vitest";
 import {
+  CmsPagePendingFallback,
+  cmsHomeRouteConfig,
+  cmsRouteConfig,
   parseLoadCmsHomePageInput,
   parseLoadCmsPageInput,
+  enrichGlobals,
   runSectionLoadersWithSeo,
 } from "./cmsRoute";
 
@@ -98,3 +106,162 @@ describe("runSectionLoadersWithSeo (#355)", () => {
     expect(enrichedSeoSection).toBeNull();
   });
 });
+
+/**
+ * Regression guard: `site.global` / `site.pageSections` entries never went
+ * through `runSectionLoaders`. `resolveSiteGlobals()` resolves only their
+ * *props* (and SWR-caches that across visitors for 5 minutes), so a global
+ * section's `loader` export simply never ran — the component rendered with
+ * raw CMS props and every loader-derived field was `undefined`.
+ *
+ * The visible symptom on a real storefront: an analytics global that has to
+ * emit its event inline, in document order (before the page-view global's
+ * script), could not do so at all. Rewriting it as a client-side `useQuery`
+ * moved the event to after hydration, which reorders the dataLayer.
+ */
+describe("enrichGlobals — site.global loaders run per request", () => {
+  it("runs a global section's loader with the real request", async () => {
+    const component = `test/sections/GlobalLoader-${Date.now()}.tsx`;
+    const seen: string[] = [];
+    registerSectionLoader(component, async (props, req) => {
+      seen.push(req.headers.get("cookie") ?? "");
+      return { ...props, loaded: true };
+    });
+
+    const global: ResolvedSection = { component, props: {}, key: component, index: 0 };
+    const request = new Request("https://store.com/", { headers: { cookie: "sid=abc" } });
+
+    const result = await enrichGlobals([global], [], request);
+
+    expect((result[0].props as any).loaded).toBe(true);
+    expect(seen).toEqual(["sid=abc"]);
+  });
+
+  it("dedupes before running loaders — a page-overridden global never pays for its loader", async () => {
+    const component = `test/sections/GlobalDedupe-${Date.now()}.tsx`;
+    let calls = 0;
+    registerSectionLoader(component, async (props) => {
+      calls++;
+      return props;
+    });
+
+    const global: ResolvedSection = { component, props: {}, key: component, index: 0 };
+    const pageSection: ResolvedSection = { component, props: {}, key: `${component}-page`, index: 1 };
+
+    const result = await enrichGlobals([global], [pageSection], new Request("https://store.com/"));
+
+    expect(result).toEqual([]);
+    expect(calls).toBe(0);
+  });
+
+  it("preserves global order and passes through globals with no registered loader", async () => {
+    const withLoader = `test/sections/GlobalA-${Date.now()}.tsx`;
+    const withoutLoader = `test/sections/GlobalB-${Date.now()}.tsx`;
+    registerSectionLoader(withLoader, async (props) => ({ ...props, loaded: true }));
+
+    const globals: ResolvedSection[] = [
+      { component: withLoader, props: {}, key: withLoader, index: 0 },
+      { component: withoutLoader, props: { raw: 1 }, key: withoutLoader, index: 1 },
+    ];
+
+    const result = await enrichGlobals(globals, [], new Request("https://store.com/"));
+
+    expect(result.map((s) => s.component)).toEqual([withLoader, withoutLoader]);
+    expect((result[0].props as any).loaded).toBe(true);
+    expect((result[1].props as any).raw).toBe(1);
+  });
+
+  it("is a no-op when every global is deduped away", async () => {
+    expect(await enrichGlobals([], [], new Request("https://store.com/"))).toEqual([]);
+  });
+
+  /**
+   * Both call sites dedupe against the page's RAW sections so the globals'
+   * loaders can run concurrently with the page's instead of behind them. That
+   * is only sound while `runSectionLoaders` leaves `section.component`
+   * untouched — `dedupeGlobals` reads nothing else. If a future change makes a
+   * loader rewrite `component` (or add/drop sections), the two dedupe targets
+   * stop agreeing and an overridden global would render twice. Lock it here.
+   */
+  it("dedupes identically against raw and loader-enriched page sections", async () => {
+    const shared = `test/sections/GlobalInvariant-${Date.now()}.tsx`;
+    const globalOnly = `test/sections/GlobalOnly-${Date.now()}.tsx`;
+    registerSectionLoader(shared, async (props) => ({ ...props, loaded: true }));
+    registerSectionLoader(globalOnly, async (props) => ({ ...props, loaded: true }));
+
+    const globals: ResolvedSection[] = [
+      { component: globalOnly, props: {}, key: globalOnly, index: 0 },
+      { component: shared, props: {}, key: shared, index: 1 },
+    ];
+    const rawPageSections: ResolvedSection[] = [
+      { component: shared, props: { sku: "1" }, key: `${shared}-page`, index: 0 },
+    ];
+
+    const request = new Request("https://store.com/");
+    const enrichedPageSections = await runSectionLoaders(rawPageSections, request);
+
+    // The loader must not have touched `component` — the whole premise.
+    expect(enrichedPageSections.map((s) => s.component)).toEqual(
+      rawPageSections.map((s) => s.component),
+    );
+
+    const viaRaw = await enrichGlobals(globals, rawPageSections, request);
+    const viaEnriched = await enrichGlobals(globals, enrichedPageSections, request);
+
+    expect(viaRaw.map((s) => s.component)).toEqual([globalOnly]);
+    expect(viaRaw.map((s) => s.component)).toEqual(viaEnriched.map((s) => s.component));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Pending UI defaults
+// ---------------------------------------------------------------------------
+//
+// There is deliberately NO default pendingComponent. Setting one turns every
+// navigation slower than `pendingMs` (200ms) into a page → skeleton → page swap
+// held for at least `pendingMinMs` (300ms). Deferral pulls most navigations into
+// the 200–600ms band, i.e. exactly the window where that swap costs more than it
+// buys, and this is a catch-all route, so one skeleton shape would have to serve
+// PDP, PLP, search, and institutional pages alike. Keeping the previous page on
+// screen until the new one commits is the better default; a site that wants a
+// skeleton opts in per-shape.
+//
+// `pendingMs`/`pendingMinMs` DO keep defaults — they are inert without a
+// pendingComponent, and they also govern a site-provided one.
+
+describe("cmsRouteConfig / cmsHomeRouteConfig — pending UI defaults", () => {
+  const base = { siteName: "Loja", defaultTitle: "Loja" };
+
+  it("ships NO default pendingComponent — the previous page stays until commit", () => {
+    expect("pendingComponent" in cmsRouteConfig(base)).toBe(false);
+    expect("pendingComponent" in cmsHomeRouteConfig({ defaultTitle: "Loja" })).toBe(false);
+  });
+
+  it("honors a site-provided pendingComponent on both route configs", () => {
+    const custom = () => null;
+    expect(cmsRouteConfig({ ...base, pendingComponent: custom }).pendingComponent).toBe(custom);
+    expect(
+      cmsHomeRouteConfig({ defaultTitle: "Loja", pendingComponent: custom }).pendingComponent,
+    ).toBe(custom);
+  });
+
+  it("treats an explicit null the same as omitting it", () => {
+    expect("pendingComponent" in cmsRouteConfig({ ...base, pendingComponent: null })).toBe(false);
+    expect(
+      "pendingComponent" in cmsHomeRouteConfig({ defaultTitle: "Loja", pendingComponent: null }),
+    ).toBe(false);
+  });
+
+  it("still exports CmsPagePendingFallback as an opt-in starting point", () => {
+    expect(typeof CmsPagePendingFallback).toBe("function");
+    expect(
+      cmsRouteConfig({ ...base, pendingComponent: CmsPagePendingFallback }).pendingComponent,
+    ).toBe(CmsPagePendingFallback);
+  });
+
+  it("keeps the documented pendingMs / pendingMinMs defaults", () => {
+    const cfg = cmsRouteConfig(base);
+    expect(cfg.pendingMs).toBe(200);
+    expect(cfg.pendingMinMs).toBe(300);
+  });
+});

package/src/routes/cmsRoute.ts

@@ -49,6 +49,7 @@ import {
   detectCacheProfile,
   routeCacheDefaults,
 } from "@decocms/blocks/sdk/cacheHeaders";
+import { takeExperimentAssignments } from "@decocms/blocks/sdk/experiments";
 import {
   parseSegmentCookie,
   SEGMENT_COOKIE,
@@ -116,9 +117,16 @@ const SEGMENT_COOKIE_MAX_AGE = 60 * 60 * 24 * 365;
  *
  * `encode: (v) => v` keeps the raw base64 intact — @decocms/apps
  * OneDollarStats reads the cookie with `atob()` directly.
+ *
+ * Experiment assignments (`sdk/experiments.ts`) merge in through the same
+ * writer rather than setting their own cookie — one `deco_segment`, one
+ * Set-Cookie. That is why this runs AFTER the section loaders: CMS matchers
+ * decide during page resolution, but an experiment is resolved inside a
+ * loader, so persisting before the loaders ran would drop the assignment and
+ * the visitor would re-roll on every request.
  */
-function persistFlags(matcherCtx: MatcherContext): StoredFlag[] {
-  const recorded = matcherCtx.flags ?? [];
+function persistFlags(matcherCtx: MatcherContext, experiments: StoredFlag[] = []): StoredFlag[] {
+  const recorded = [...(matcherCtx.flags ?? []), ...experiments];
   if (!recorded.length) return [];
 
   const raw = matcherCtx.cookies?.[SEGMENT_COOKIE];
@@ -168,6 +176,46 @@ export async function runSectionLoadersWithSeo(
   };
 }
 
+/**
+ * Dedupe `site.global` / `site.pageSections` against the page's own sections,
+ * then run the survivors' loaders against the real per-request Request.
+ *
+ * `resolveSiteGlobals()` only resolves a global's *props* — and it SWR-caches
+ * that result for 5 minutes across every visitor. Until now nothing ever fed
+ * globals through `runSectionLoaders`, so a global section's `loader` export
+ * simply never ran: the component rendered with the raw CMS props and every
+ * loader-derived field arrived `undefined`. Sites worked around it by moving
+ * the work client-side (a `useQuery` over `/deco/invoke`), which changes both
+ * the timing and the SSR output — an analytics global that has to emit its
+ * event inline, in document order, cannot be rewritten that way at all.
+ *
+ * Loaders run per request and are NOT cached here; only the prop resolution
+ * behind `resolveSiteGlobals()` keeps its 5-minute cache. Dedupe runs first so
+ * a global that the page overrides never pays for its loader.
+ *
+ * Section-level caching still applies: a global registered via
+ * `registerLayoutSections` / `registerCacheableSections` goes through the same
+ * cache tiers as any other section inside `runSectionLoaders`.
+ *
+ * `pageSections` may be the page's RAW sections — it does not have to be the
+ * loader-enriched ones. `dedupeGlobals` reads only `section.component`, and no
+ * branch of `runSingleSectionLoaderImpl` ever rewrites `component` (every path
+ * returns `section` or `{ ...section, props }`, 1:1, never adding or dropping
+ * entries). Passing the raw list is what lets this run CONCURRENTLY with the
+ * page's own loaders instead of behind them.
+ *
+ * @internal exported for tests
+ */
+export async function enrichGlobals(
+  globalSections: ResolvedSection[],
+  pageSections: ResolvedSection[],
+  request: Request,
+): Promise<ResolvedSection[]> {
+  const kept = dedupeGlobals(globalSections, pageSections);
+  if (kept.length === 0) return kept;
+  return runSectionLoaders(kept, request);
+}
+
 async function loadCmsPageInternal(fullPath: string, resolveGlobals: boolean) {
   const [basePath] = fullPath.split("?");
   // On client-side navigation getRequestUrl() is the /_serverFn/... endpoint,
@@ -188,7 +236,6 @@ async function loadCmsPageInternal(fullPath: string, resolveGlobals: boolean) {
   };
   const page = await resolveDecoPage(basePath, matcherCtx);
   if (!page) return null;
-  const flags = persistFlags(matcherCtx);
 
   const request = new Request(urlWithSearch, {
     headers: originRequest.headers,
@@ -200,17 +247,33 @@ async function loadCmsPageInternal(fullPath: string, resolveGlobals: boolean) {
   // identical for SSR (F5) and SPA (<Link>) navigations — see #233 for the
   // previous SPA-breakage when `withSiteGlobals` ran client-side and saw an
   // empty client-bundled `blocks.gen.ts`.
-  const [{ enrichedSections, enrichedSeoSection }, globals] = await Promise.all([
-    runSectionLoadersWithSeo(page.resolvedSections, page.seoSection, request),
-    resolveGlobals ? resolveSiteGlobals() : Promise.resolve(EMPTY_GLOBALS),
-  ]);
-
-  // Page sections take precedence over globals — dedupe drops any global
-  // whose component is already rendered by the page.
-  const mergedSections: ResolvedSection[] = [
-    ...dedupeGlobals(globals.resolvedSections, enrichedSections),
-    ...enrichedSections,
-  ];
+  const [{ enrichedSections, enrichedSeoSection }, { globals, enrichedGlobals }] =
+    await Promise.all([
+      runSectionLoadersWithSeo(page.resolvedSections, page.seoSection, request),
+      (async () => {
+        const globals = resolveGlobals ? await resolveSiteGlobals(matcherCtx) : EMPTY_GLOBALS;
+        return {
+          globals,
+          // Deduped against the page's RAW sections on purpose — see enrichGlobals.
+          // Waiting for `enrichedSections` would put the globals' loaders behind
+          // the page's on the TTFB critical path for no benefit.
+          enrichedGlobals: await enrichGlobals(
+            globals.resolvedSections,
+            page.resolvedSections,
+            request,
+          ),
+        };
+      })(),
+    ]);
+
+  // After the loaders — a loader-resolved experiment assignment must be in the
+  // cookie this response sets. See persistFlags.
+  const flags = persistFlags(matcherCtx, takeExperimentAssignments());
+
+  // Page sections take precedence over globals — dedupe drops any global whose
+  // component is already rendered by the page. The survivors ran their own
+  // loaders above, concurrently with the page's (see enrichGlobals).
+  const mergedSections: ResolvedSection[] = [...enrichedGlobals, ...enrichedSections];
 
   // Pre-import eager section modules so their default exports are cached
   // in resolvedComponents. This ensures SSR renders with direct component
@@ -278,13 +341,18 @@ export const loadCmsPage = createServerFn({ method: "GET" })
     // Using basePath only caused /s?q=a and /s?q=b to share one promise,
     // returning wrong/empty results for search and filtered PLPs.
     //
-    // Client-nav resolves all sections eagerly (#277). An in-flight SSR response
-    // for the same path may carry deferredSections; sharing that promise with a
-    // concurrent SPA transition would smuggle those deferred sections in, causing
-    // loadDeferredSection to run without the per-request commerce app context.
-    // Use separate dedup buckets for SSR vs client-nav. `resolveGlobals` is also
-    // part of the key — otherwise a `resolveGlobals: false` request could return
-    // (or share a promise with) a `resolveGlobals: true` response for the same path.
+    // SSR and client-nav produce the same eager/deferred split now, so the
+    // original reason for the `__nav:` bucket — a client-nav request must never
+    // inherit an SSR response's deferredSections (#277) — no longer applies. It
+    // is kept anyway, because this map is module-global and the payload it
+    // shares carries `pageUrl`, `flags`, and `device` derived from whichever
+    // request won the race. That cross-request bleed is pre-existing and wider
+    // than this bucket (two concurrent same-path requests already collide on
+    // cookies/UA/geo), but SSR and client-nav are exactly the pair whose
+    // `derivePageUrl` inputs differ most, so collapsing them would widen a
+    // known hole for no gain. `resolveGlobals` is part of the key for the same
+    // reason: a `resolveGlobals: false` request must not share a promise with a
+    // `resolveGlobals: true` one.
     const clientNav = isClientNavigation(fullPath, getRequestUrl());
     const inflightKey =
       (clientNav ? `__nav:${fullPath}` : fullPath) + (resolveGlobals ? "" : "|noGlobals");
@@ -329,16 +397,24 @@ export const loadCmsHomePage = createServerFn({ method: "GET" })
     };
     const page = await resolveDecoPage("/", matcherCtx);
     if (!page) return null;
-    const flags = persistFlags(matcherCtx);
-    const [{ enrichedSections, enrichedSeoSection }, globals] = await Promise.all([
-      runSectionLoadersWithSeo(page.resolvedSections, page.seoSection, request),
-      resolveGlobals ? resolveSiteGlobals() : Promise.resolve(EMPTY_GLOBALS),
-    ]);
-
-    const mergedSections: ResolvedSection[] = [
-      ...dedupeGlobals(globals.resolvedSections, enrichedSections),
-      ...enrichedSections,
-    ];
+    const [{ enrichedSections, enrichedSeoSection }, { globals, enrichedGlobals }] =
+      await Promise.all([
+        runSectionLoadersWithSeo(page.resolvedSections, page.seoSection, request),
+        (async () => {
+          const globals = resolveGlobals ? await resolveSiteGlobals(matcherCtx) : EMPTY_GLOBALS;
+          return {
+            globals,
+            enrichedGlobals: await enrichGlobals(
+              globals.resolvedSections,
+              page.resolvedSections,
+              request,
+            ),
+          };
+        })(),
+      ]);
+    const flags = persistFlags(matcherCtx, takeExperimentAssignments());
+
+    const mergedSections: ResolvedSection[] = [...enrichedGlobals, ...enrichedSections];
 
     const eagerKeys = mergedSections.map((s) => s.component);
     await preloadSectionComponents(eagerKeys);
@@ -381,9 +457,16 @@ export const loadCmsHomePage = createServerFn({ method: "GET" })
 // ---------------------------------------------------------------------------
 
 /**
- * @deprecated Prefer TanStack native streaming via `deferredPromises` in the
- * route loader. This POST server function is kept for backward compatibility
- * and as a fallback for SPA navigations.
+ * Resolves + enriches a single deferred section on demand, server-side.
+ *
+ * This is the deferred-resolution path for BOTH the initial SSR document and
+ * client (SPA) navigations — `deferredPromises`/TanStack native streaming is
+ * SSR-only, because promises cannot cross the server-fn JSON boundary. It
+ * rebuilds `MatcherContext` from the real incoming request (url/path/cookies/
+ * request), so the second hop sees the same per-request state the first one did
+ * (the `deco_segment` cookie set by the page response is already present, so
+ * sticky A/B decisions stay consistent — `flags` is intentionally left unset
+ * here: this response must not re-roll or re-persist the cohort cookie).
  */
 export const loadDeferredSection = createServerFn({ method: "POST" })
   .inputValidator(
@@ -547,8 +630,21 @@ export interface CmsRouteOptions {
    * Defaults to `["skuId"]` — variant selection is client-side only.
    */
   ignoreSearchParams?: string[];
-  /** Custom pending component shown during SPA navigation. */
-  pendingComponent?: () => any;
+  /**
+   * Pending component shown during SPA navigation while the route loader runs.
+   *
+   * NO DEFAULT, deliberately. With none set, TanStack keeps the previous page on
+   * screen until the new one commits — which at the sub-second latencies this
+   * route now sees is usually the better feel. Setting one buys feedback on a
+   * slow navigation at the cost of a page → skeleton → page swap on every
+   * navigation slower than {@link pendingMs} (held for at least
+   * {@link pendingMinMs}), and this is a *catch-all* route, so one skeleton
+   * shape has to serve PDP, PLP, search, and institutional pages alike.
+   * {@link CmsPagePendingFallback} is exported as a starting point; prefer a
+   * per-shape skeleton, or `NavigationProgress` (`@decocms/tanstack`) for
+   * feedback that does not replace the page at all.
+   */
+  pendingComponent?: (() => any) | null;
   /**
    * Custom error boundary rendered when the loader / page resolution throws.
    * Defaults to {@link CmsPageErrorFallback} (branded "instability" page with a
@@ -560,12 +656,23 @@ export interface CmsRouteOptions {
    * Delay (ms) before showing the pending component during SPA navigation.
    * If the loader resolves before this threshold, no pending UI is shown.
    * Prevents skeleton flash on fast cache-hit navigations. Default: 200.
+   * Inert unless {@link pendingComponent} is set.
+   *
+   * This is a *catch-all* route, so the same value covers a sub-100ms PLP facet
+   * toggle and a cold PDP. Raising it only DELAYS the skeleton on the slow
+   * navigation (a 1s `pendingMs` still shows it on a 2s nav) — it does not
+   * suppress it. Use {@link pendingMinMs} for the flicker case where the loader
+   * lands just after the threshold.
    */
   pendingMs?: number;
   /**
    * Minimum display time (ms) for the pending component once shown.
    * Prevents jarring flash when data arrives shortly after the threshold.
-   * Default: 300.
+   * Default: 300. Inert unless {@link pendingComponent} is set.
+   *
+   * Independent of {@link pendingMs}, and applied after it: worst-case a
+   * navigation is held for `pendingMs + pendingMinMs` of visible skeleton
+   * before the new page commits.
    */
   pendingMinMs?: number;
   /**
@@ -894,7 +1001,8 @@ export function cmsHomeRouteConfig(options: {
   defaultDescription?: string;
   /** Site name for OG title composition. Defaults to defaultTitle. */
   siteName?: string;
-  pendingComponent?: () => any;
+  /** See `CmsRouteOptions.pendingComponent` — no default, deliberately. */
+  pendingComponent?: (() => any) | null;
   /** Delay (ms) before showing pending component. Default: 200. */
   pendingMs?: number;
   /** Minimum display time (ms) for pending component. Default: 300. */
@@ -908,6 +1016,7 @@ export function cmsHomeRouteConfig(options: {
     defaultTitle,
     defaultDescription,
     siteName,
+    pendingComponent,
     pendingMs = 200,
     pendingMinMs = 300,
     errorComponent = CmsPageErrorFallback,
@@ -928,7 +1037,7 @@ export function cmsHomeRouteConfig(options: {
       // See cmsRouteConfig loader for rationale.
       return page;
     },
-    ...(options.pendingComponent ? { pendingComponent: options.pendingComponent } : {}),
+    ...(pendingComponent ? { pendingComponent } : {}),
     pendingMs,
     pendingMinMs,
     errorComponent,

package/src/routes/pageUrl.test.ts

@@ -4,8 +4,8 @@ import { derivePageUrl, isClientNavigation } from "./pageUrl";
 describe("derivePageUrl (#280 — client-nav request URL)", () => {
   it("SSR real page without query: rebuilds from fullPath", () => {
     expect(
-      derivePageUrl("/granado/produto", new URL("https://o.com/granado/produto")),
-    ).toBe("https://o.com/granado/produto");
+      derivePageUrl("/acme/produto", new URL("https://o.com/acme/produto")),
+    ).toBe("https://o.com/acme/produto");
   });
 
   it("SSR real page preserves duplicate query params from the server URL", () => {
@@ -21,10 +21,10 @@ describe("derivePageUrl (#280 — client-nav request URL)", () => {
   it("client nav without query: rebuilds from fullPath, NOT the /_serverFn URL", () => {
     // The regression guard: getRequestUrl() is the serverFn endpoint here.
     const serverUrl = new URL(
-      "https://o.com/_serverFn/loadCmsPage?payload=%2Fgranado%2Fproduto",
+      "https://o.com/_serverFn/loadCmsPage?payload=%2Facme%2Fproduto",
     );
-    expect(derivePageUrl("/granado/produto", serverUrl)).toBe(
-      "https://o.com/granado/produto",
+    expect(derivePageUrl("/acme/produto", serverUrl)).toBe(
+      "https://o.com/acme/produto",
     );
   });
 
@@ -50,7 +50,7 @@ describe("isClientNavigation (SPA vs SSR detection)", () => {
 
   it("SSR real page without query (path matches): false", () => {
     expect(
-      isClientNavigation("/granado/produto", new URL("https://o.com/granado/produto")),
+      isClientNavigation("/acme/produto", new URL("https://o.com/acme/produto")),
     ).toBe(false);
   });
 

package/src/routes/pageUrl.ts

@@ -36,10 +36,11 @@ export function derivePageUrl(fullPath: string, serverUrl: URL): string {
  * `serverUrl.pathname` is NOT the page path. On a real document request (SSR /
  * full reload, including bots) `serverUrl.pathname === basePath`.
  *
- * Section deferral is a streaming-SSR optimization (shrinks the initial HTML /
- * TTFB). On a client navigation the server fn returns JSON in one shot — there
- * is no streaming benefit, so deferral only adds a round-trip and a skeleton.
- * Callers use this to resolve all sections eagerly on SPA navigation.
+ * This does NOT gate section deferral: a client nav gets the same eager/deferred
+ * split as SSR, because the route loader is blocking and awaiting the below-fold
+ * sections freezes the transition. Callers use it to rebuild the real page URL
+ * (`derivePageUrl`) and to tell a SPA nav apart from a genuine AJAX consumer
+ * (`isProgrammaticFetch`) — both send `Sec-Fetch-Dest: empty`.
  *
  * Mirrors the `serverUrl.pathname === basePath` comparison `derivePageUrl`
  * already relies on, so the two stay consistent and we avoid hardcoding the

package/src/routes/withSiteGlobals.test.ts

@@ -121,6 +121,43 @@ describe("withSiteGlobals", () => {
       expect(mockedResolvePageSections).toHaveBeenCalledTimes(1);
     });
 
+    it("threads matcherCtx to resolvePageSections", async () => {
+      mockedLoadBlocks.mockReturnValue({
+        site: { global: [{ __resolveType: "Alert" }] },
+      });
+      mockedResolvePageSections.mockResolvedValue([{ component: "A.tsx", props: {}, key: "k0" }]);
+
+      const ctx = { path: "/farm-etc" } as any;
+      await resolveSiteGlobals(ctx);
+
+      expect(mockedResolvePageSections).toHaveBeenCalledWith(
+        [{ __resolveType: "Alert" }],
+        ctx,
+      );
+    });
+
+    it("caches per path — different routes don't share a matched variant", async () => {
+      mockedLoadBlocks.mockReturnValue({
+        site: { global: [{ __resolveType: "Alert" }] },
+      });
+      mockedResolvePageSections
+        .mockResolvedValueOnce([{ component: "EtcAlert.tsx", props: {}, key: "etc" }])
+        .mockResolvedValueOnce([{ component: "HomeAlert.tsx", props: {}, key: "home" }]);
+
+      const etc = await resolveSiteGlobals({ path: "/farm-etc" } as any);
+      const home = await resolveSiteGlobals({ path: "/" } as any);
+
+      // Distinct paths resolve independently (no cross-route leak)...
+      expect(etc.resolvedSections[0].key).toBe("etc");
+      expect(home.resolvedSections[0].key).toBe("home");
+      expect(mockedResolvePageSections).toHaveBeenCalledTimes(2);
+
+      // ...and the same path is still served from cache.
+      const etcAgain = await resolveSiteGlobals({ path: "/farm-etc" } as any);
+      expect(etcAgain.resolvedSections[0].key).toBe("etc");
+      expect(mockedResolvePageSections).toHaveBeenCalledTimes(2);
+    });
+
     it("invalidates cache when onChange fires", async () => {
       mockedLoadBlocks.mockReturnValue({
         site: { global: [{ __resolveType: "Analytics" }] },