@decocms/tanstack 7.59.0 → 7.59.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@decocms/tanstack",
3
- "version": "7.59.0",
3
+ "version": "7.59.1",
4
4
  "type": "module",
5
5
  "description": "Deco framework binding for TanStack Start + Cloudflare Workers",
6
6
  "repository": {
@@ -27,9 +27,9 @@
27
27
  "lint:unused": "knip"
28
28
  },
29
29
  "dependencies": {
30
- "@decocms/blocks": "7.59.0",
31
- "@decocms/blocks-admin": "7.59.0",
32
- "@decocms/blocks-cli": "7.59.0",
30
+ "@decocms/blocks": "7.59.1",
31
+ "@decocms/blocks-admin": "7.59.1",
32
+ "@decocms/blocks-cli": "7.59.1",
33
33
  "@deco-cx/warp-node": "^0.3.16",
34
34
  "fast-json-patch": "^3.1.0",
35
35
  "ws": "^8.18.0"
@@ -307,9 +307,9 @@ function DeferredSectionWrapper({
307
307
  const el = ref.current;
308
308
  if (!el) return;
309
309
 
310
- if (typeof IntersectionObserver === "undefined") {
310
+ const key = stableKey;
311
+ const load = () => {
311
312
  triggered.current = true;
312
- const key0 = stableKey;
313
313
  loadFn({
314
314
  component: deferred.component,
315
315
  pagePath,
@@ -317,37 +317,60 @@ function DeferredSectionWrapper({
317
317
  index: deferred.index,
318
318
  })
319
319
  .then((result) => {
320
- if (result) deferredSectionCache.set(key0, { section: result, ts: Date.now() });
320
+ if (result) deferredSectionCache.set(key, { section: result, ts: Date.now() });
321
321
  setSection(result);
322
322
  })
323
323
  .catch((e) => setError(e));
324
+ };
325
+
326
+ if (typeof IntersectionObserver === "undefined") {
327
+ load();
324
328
  return;
325
329
  }
326
330
 
327
- const observer = new IntersectionObserver(
328
- ([entry]) => {
329
- if (entry?.isIntersecting && !triggered.current) {
330
- triggered.current = true;
331
- observer.disconnect();
332
- const key1 = stableKey;
333
- loadFn({
334
- component: deferred.component,
335
- pagePath,
336
- pageUrl,
337
- index: deferred.index,
338
- })
339
- .then((result) => {
340
- if (result) deferredSectionCache.set(key1, { section: result, ts: Date.now() });
341
- setSection(result);
342
- })
343
- .catch((e) => setError(e));
344
- }
345
- },
346
- { rootMargin: "300px" },
347
- );
348
-
349
- observer.observe(el);
350
- return () => observer.disconnect();
331
+ let observer: IntersectionObserver | undefined;
332
+ const startObserving = () => {
333
+ if (triggered.current) return;
334
+ observer = new IntersectionObserver(
335
+ ([entry]) => {
336
+ if (entry?.isIntersecting && !triggered.current) {
337
+ observer?.disconnect();
338
+ load();
339
+ }
340
+ },
341
+ { rootMargin: "300px" },
342
+ );
343
+ observer.observe(el);
344
+ };
345
+
346
+ // Wait one frame before observing, so the router's scroll reset lands first.
347
+ //
348
+ // On a client (SPA) navigation the scroll position is still wherever the
349
+ // user left the PREVIOUS page when this effect runs. TanStack resets it from
350
+ // the `onRendered` event, which is emitted in a `useLayoutEffect`
351
+ // (react-router's `OnRendered`) that depends on the `resolvedLocation` store
352
+ // — and that store is written from ANOTHER `useLayoutEffect` (Transitioner).
353
+ // So the reset necessarily lands one commit after the one that mounts these
354
+ // skeletons, and React flushes this commit's passive effects before starting
355
+ // that follow-up render. Verified ordering: observe → scroll reset.
356
+ //
357
+ // Observing synchronously therefore evaluates intersection against the stale
358
+ // scroll offset: a user navigating from the bottom of a long page has every
359
+ // skeleton "in view" at once, so every deferred section fires its serverFn
360
+ // POST simultaneously on commit — the exact thundering herd deferral exists
361
+ // to avoid. One frame is enough to let the reset apply.
362
+ //
363
+ // `triggered` is re-checked inside, so a section that resolved from cache in
364
+ // the meantime never starts an observer.
365
+ if (typeof requestAnimationFrame === "undefined") {
366
+ startObserving();
367
+ return () => observer?.disconnect();
368
+ }
369
+ const raf = requestAnimationFrame(startObserving);
370
+ return () => {
371
+ cancelAnimationFrame(raf);
372
+ observer?.disconnect();
373
+ };
351
374
  }, [deferred.component, deferred.index, deferred.propsHash, pagePath, pageUrl, section, loadFn]);
352
375
 
353
376
  if (error) {
@@ -495,6 +518,11 @@ interface Props {
495
518
  * Unawaited promises for deferred sections, keyed by `d_<index>`.
496
519
  * Created by the route loader for TanStack native SSR streaming.
497
520
  * When provided, takes precedence over `loadDeferredSectionFn`.
521
+ *
522
+ * SSR-ONLY: promises cannot cross the server-fn JSON boundary, so a client
523
+ * (SPA) navigation never receives them. Any site that defers sections needs
524
+ * `loadDeferredSectionFn` wired regardless — it is the only path that works
525
+ * for both SSR and client nav.
498
526
  */
499
527
  deferredPromises?: Record<string, Promise<ResolvedSection | null>>;
500
528
  pagePath?: string;
@@ -509,7 +537,15 @@ interface Props {
509
537
  device?: Device;
510
538
  loadingFallback?: ReactNode;
511
539
  errorFallback?: ReactNode;
512
- /** @deprecated Use deferredPromises instead (TanStack native streaming). */
540
+ /**
541
+ * IntersectionObserver-driven loader for deferred sections — wire this to
542
+ * `deferredSectionLoader` from `@decocms/tanstack`.
543
+ *
544
+ * NOT deprecated: `deferredPromises` only covers SSR (promises can't be
545
+ * serialized through a server fn), so this is the only deferred-resolution
546
+ * path available on a client (SPA) navigation. Without it, deferred sections
547
+ * on a SPA transition render a skeleton that never resolves.
548
+ */
513
549
  loadDeferredSectionFn?: (data: {
514
550
  component: string;
515
551
  rawProps?: Record<string, unknown>;
@@ -0,0 +1,58 @@
1
+ import { renderToStaticMarkup } from "react-dom/server";
2
+ import { describe, expect, it, vi } from "vitest";
3
+
4
+ // The component only needs the router's isLoading flag.
5
+ let isLoading = true;
6
+ vi.mock("@tanstack/react-router", () => ({
7
+ useRouterState: ({ select }: { select: (s: { isLoading: boolean }) => unknown }) =>
8
+ select({ isLoading }),
9
+ }));
10
+
11
+ const { NavigationProgress } = await import("./NavigationProgress");
12
+
13
+ /**
14
+ * The bug this guards: the bar used to be painted with the Tailwind utility
15
+ * `bg-brand-primary-500`. That token is a *site* concern — framework code
16
+ * cannot assume it exists. On a Tailwind v4 theme that resets
17
+ * `--color-*: initial` the utility is never generated, so the class resolves to
18
+ * nothing and the bar is fully transparent: an invisible progress indicator, in
19
+ * production, with no build error and nothing in the console.
20
+ *
21
+ * The fix paints through an inline custom-property expression, which a CSS build
22
+ * cannot elide. It has to satisfy BOTH directions at once: sites that never
23
+ * defined the token must still see a bar, and sites that DID must keep their
24
+ * brand color rather than silently dropping to black — hence the var-with-
25
+ * fallback rather than a bare `currentColor`.
26
+ */
27
+ describe("NavigationProgress — visibility does not depend on site color tokens", () => {
28
+ it("paints via inline style, never a site-defined Tailwind color utility", () => {
29
+ isLoading = true;
30
+ const html = renderToStaticMarkup(<NavigationProgress />);
31
+
32
+ expect(html).not.toMatch(/bg-brand-/);
33
+ expect(html).toMatch(/background-color:\s*currentColor/);
34
+ });
35
+
36
+ it("keeps the brand token when the site defines it, and falls back when it does not", () => {
37
+ isLoading = true;
38
+ const html = renderToStaticMarkup(<NavigationProgress />);
39
+
40
+ // Both halves matter: the var preserves branding for sites where the old
41
+ // utility worked, the fallback is what makes it visible for those where it
42
+ // silently did not.
43
+ expect(html).toContain("--color-brand-primary-500");
44
+ expect(html).toMatch(/var\(--color-brand-primary-500,\s*currentColor\)/);
45
+ });
46
+
47
+ it("accepts an explicit color so a site can brand it without that token name", () => {
48
+ isLoading = true;
49
+ const html = renderToStaticMarkup(<NavigationProgress color="#ff0080" />);
50
+ expect(html).toContain("#ff0080");
51
+ expect(html).not.toContain("--color-brand-primary-500");
52
+ });
53
+
54
+ it("renders nothing when the router is idle", () => {
55
+ isLoading = false;
56
+ expect(renderToStaticMarkup(<NavigationProgress />)).toBe("");
57
+ });
58
+ });
@@ -5,17 +5,59 @@ const PROGRESS_CSS = `
5
5
  .nav-progress-bar { animation: progressSlide 1s ease-in-out infinite; }
6
6
  `;
7
7
 
8
+ /**
9
+ * Brand token when the site defines it, inherited text color when it does not.
10
+ *
11
+ * The bar used to be painted with the Tailwind utility `bg-brand-primary-500`.
12
+ * That token is a *site* concern, and framework code cannot assume it exists: on
13
+ * a Tailwind v4 theme that resets `--color-*: initial` the utility is never
14
+ * generated, so the class resolved to nothing and the bar rendered fully
15
+ * transparent — an invisible progress indicator, in production, with no build
16
+ * error and nothing in the console.
17
+ *
18
+ * A CSS custom property with a fallback fixes that without regressing the sites
19
+ * where it already worked: they keep their brand color (Tailwind v4 emits
20
+ * `--color-brand-primary-500` for a `brand-primary` palette entry), and
21
+ * everyone else falls back to `currentColor` instead of nothing. Unlike a
22
+ * utility class, neither half can be dropped by a CSS build.
23
+ */
24
+ const DEFAULT_COLOR = "var(--color-brand-primary-500, currentColor)";
25
+
26
+ export interface NavigationProgressProps {
27
+ /**
28
+ * Bar color. Any CSS color or custom-property expression. Defaults to
29
+ * {@link DEFAULT_COLOR} — the site's `brand-primary-500` token when defined,
30
+ * otherwise the inherited text color. Pass an explicit value to brand the bar
31
+ * without relying on that token name.
32
+ */
33
+ color?: string;
34
+ }
35
+
8
36
  /**
9
37
  * Top-of-page loading bar that appears during SPA navigation.
10
38
  * Uses the router's isLoading state — no extra dependencies.
11
39
  */
12
- export function NavigationProgress() {
40
+ export function NavigationProgress({ color = DEFAULT_COLOR }: NavigationProgressProps = {}) {
13
41
  const isLoading = useRouterState({ select: (s) => s.isLoading });
14
42
  if (!isLoading) return null;
15
43
  return (
16
- <div className="fixed top-0 left-0 right-0 z-[9999] h-1 bg-brand-primary-500/20 overflow-hidden">
44
+ <div
45
+ className="fixed top-0 left-0 right-0 z-[9999] h-1 overflow-hidden"
46
+ style={{ color }}
47
+ role="progressbar"
48
+ aria-label="Carregando página"
49
+ >
17
50
  <style dangerouslySetInnerHTML={{ __html: PROGRESS_CSS }} />
18
- <div className="nav-progress-bar h-full w-1/3 bg-brand-primary-500 rounded-full" />
51
+ {/* Track and bar are siblings so the track's 20% alpha does not
52
+ inherit onto the bar (opacity applies to the whole subtree). */}
53
+ <div
54
+ className="absolute inset-0"
55
+ style={{ backgroundColor: "currentColor", opacity: 0.2 }}
56
+ />
57
+ <div
58
+ className="nav-progress-bar absolute inset-y-0 left-0 w-1/3 rounded-full"
59
+ style={{ backgroundColor: "currentColor" }}
60
+ />
19
61
  </div>
20
62
  );
21
63
  }
@@ -0,0 +1,91 @@
1
+ import { act, useEffect, useLayoutEffect, useState } from "react";
2
+ import { createRoot } from "react-dom/client";
3
+ import { describe, expect, it } from "vitest";
4
+
5
+ /**
6
+ * Guards the frame gate in `DeferredSectionWrapper`'s IntersectionObserver
7
+ * effect (`DecoPageRenderer.tsx`).
8
+ *
9
+ * Enabling deferral on client navigation made a latent ordering problem
10
+ * reachable. On a SPA transition the scroll position is still wherever the user
11
+ * left the previous page when the new page's skeletons mount. TanStack resets it
12
+ * from the `onRendered` event, emitted by a `useLayoutEffect` in react-router's
13
+ * `OnRendered` that depends on the `resolvedLocation` store — which is itself
14
+ * written from another `useLayoutEffect` (`Transitioner`). The reset therefore
15
+ * lands one commit AFTER the mount commit, and React flushes the mount commit's
16
+ * passive effects before starting that follow-up render.
17
+ *
18
+ * Net effect without a gate: the observer evaluates intersection against the
19
+ * stale offset, so a user navigating from the bottom of a long page has every
20
+ * skeleton in view simultaneously and every deferred section fires its serverFn
21
+ * POST at once — the thundering herd deferral exists to avoid.
22
+ *
23
+ * This models that exact effect topology rather than mounting the real router,
24
+ * because the ordering is a property of React's commit/flush sequence, not of
25
+ * TanStack. If React ever changes it so passive effects run after a
26
+ * layout-effect-triggered re-render, the first case flips and the gate can go.
27
+ */
28
+ function runOrdering(gate: "none" | "raf") {
29
+ const order: string[] = [];
30
+
31
+ /** Stands in for TanStack's Transitioner writing `resolvedLocation`. */
32
+ function Transitioner({ setResolved }: { setResolved: (n: number) => void }) {
33
+ useLayoutEffect(() => setResolved(1), [setResolved]);
34
+ return null;
35
+ }
36
+
37
+ /** Stands in for `OnRendered` → `onRendered` → scroll-restoration reset. */
38
+ function OnRendered({ resolved }: { resolved: number }) {
39
+ useLayoutEffect(() => {
40
+ if (resolved > 0) order.push("SCROLL_RESET");
41
+ }, [resolved]);
42
+ return null;
43
+ }
44
+
45
+ /** Stands in for DeferredSectionWrapper's observer effect. */
46
+ function DeferredWrapper() {
47
+ useEffect(() => {
48
+ const observe = () => order.push("OBSERVE");
49
+ if (gate === "none") {
50
+ observe();
51
+ return;
52
+ }
53
+ const raf = requestAnimationFrame(observe);
54
+ return () => cancelAnimationFrame(raf);
55
+ }, []);
56
+ return null;
57
+ }
58
+
59
+ function App() {
60
+ const [resolved, setResolved] = useState(0);
61
+ return (
62
+ <>
63
+ {/* Deliberately first: children flush before the root's own effects. */}
64
+ <DeferredWrapper />
65
+ <Transitioner setResolved={setResolved} />
66
+ <OnRendered resolved={resolved} />
67
+ </>
68
+ );
69
+ }
70
+
71
+ const el = document.createElement("div");
72
+ document.body.appendChild(el);
73
+ act(() => {
74
+ createRoot(el).render(<App />);
75
+ });
76
+ return order;
77
+ }
78
+
79
+ describe("deferred observer vs router scroll reset", () => {
80
+ it("observing synchronously loses the race — this is why the gate exists", () => {
81
+ // If this ever reports SCROLL_RESET first, React's flush order changed and
82
+ // the requestAnimationFrame gate in DecoPageRenderer is dead weight.
83
+ expect(runOrdering("none")).toEqual(["OBSERVE", "SCROLL_RESET"]);
84
+ });
85
+
86
+ it("one frame is enough for the scroll reset to land first", () => {
87
+ // rAF does not run inside act(), so the reset is the only thing recorded —
88
+ // i.e. observation is strictly after it, which is the point.
89
+ expect(runOrdering("raf")).toEqual(["SCROLL_RESET"]);
90
+ });
91
+ });
@@ -2,6 +2,9 @@ import { registerCacheableSections, registerSectionLoader } from "@decocms/block
2
2
  import type { ResolvedSection } from "@decocms/blocks/cms";
3
3
  import { describe, expect, it } from "vitest";
4
4
  import {
5
+ CmsPagePendingFallback,
6
+ cmsHomeRouteConfig,
7
+ cmsRouteConfig,
5
8
  parseLoadCmsHomePageInput,
6
9
  parseLoadCmsPageInput,
7
10
  runSectionLoadersWithSeo,
@@ -98,3 +101,56 @@ describe("runSectionLoadersWithSeo (#355)", () => {
98
101
  expect(enrichedSeoSection).toBeNull();
99
102
  });
100
103
  });
104
+
105
+ // ---------------------------------------------------------------------------
106
+ // Pending UI defaults
107
+ // ---------------------------------------------------------------------------
108
+ //
109
+ // There is deliberately NO default pendingComponent. Setting one turns every
110
+ // navigation slower than `pendingMs` (200ms) into a page → skeleton → page swap
111
+ // held for at least `pendingMinMs` (300ms). Deferral pulls most navigations into
112
+ // the 200–600ms band, i.e. exactly the window where that swap costs more than it
113
+ // buys, and this is a catch-all route, so one skeleton shape would have to serve
114
+ // PDP, PLP, search, and institutional pages alike. Keeping the previous page on
115
+ // screen until the new one commits is the better default; a site that wants a
116
+ // skeleton opts in per-shape.
117
+ //
118
+ // `pendingMs`/`pendingMinMs` DO keep defaults — they are inert without a
119
+ // pendingComponent, and they also govern a site-provided one.
120
+
121
+ describe("cmsRouteConfig / cmsHomeRouteConfig — pending UI defaults", () => {
122
+ const base = { siteName: "Loja", defaultTitle: "Loja" };
123
+
124
+ it("ships NO default pendingComponent — the previous page stays until commit", () => {
125
+ expect("pendingComponent" in cmsRouteConfig(base)).toBe(false);
126
+ expect("pendingComponent" in cmsHomeRouteConfig({ defaultTitle: "Loja" })).toBe(false);
127
+ });
128
+
129
+ it("honors a site-provided pendingComponent on both route configs", () => {
130
+ const custom = () => null;
131
+ expect(cmsRouteConfig({ ...base, pendingComponent: custom }).pendingComponent).toBe(custom);
132
+ expect(
133
+ cmsHomeRouteConfig({ defaultTitle: "Loja", pendingComponent: custom }).pendingComponent,
134
+ ).toBe(custom);
135
+ });
136
+
137
+ it("treats an explicit null the same as omitting it", () => {
138
+ expect("pendingComponent" in cmsRouteConfig({ ...base, pendingComponent: null })).toBe(false);
139
+ expect(
140
+ "pendingComponent" in cmsHomeRouteConfig({ defaultTitle: "Loja", pendingComponent: null }),
141
+ ).toBe(false);
142
+ });
143
+
144
+ it("still exports CmsPagePendingFallback as an opt-in starting point", () => {
145
+ expect(typeof CmsPagePendingFallback).toBe("function");
146
+ expect(
147
+ cmsRouteConfig({ ...base, pendingComponent: CmsPagePendingFallback }).pendingComponent,
148
+ ).toBe(CmsPagePendingFallback);
149
+ });
150
+
151
+ it("keeps the documented pendingMs / pendingMinMs defaults", () => {
152
+ const cfg = cmsRouteConfig(base);
153
+ expect(cfg.pendingMs).toBe(200);
154
+ expect(cfg.pendingMinMs).toBe(300);
155
+ });
156
+ });
@@ -289,13 +289,18 @@ export const loadCmsPage = createServerFn({ method: "GET" })
289
289
  // Using basePath only caused /s?q=a and /s?q=b to share one promise,
290
290
  // returning wrong/empty results for search and filtered PLPs.
291
291
  //
292
- // Client-nav resolves all sections eagerly (#277). An in-flight SSR response
293
- // for the same path may carry deferredSections; sharing that promise with a
294
- // concurrent SPA transition would smuggle those deferred sections in, causing
295
- // loadDeferredSection to run without the per-request commerce app context.
296
- // Use separate dedup buckets for SSR vs client-nav. `resolveGlobals` is also
297
- // part of the key — otherwise a `resolveGlobals: false` request could return
298
- // (or share a promise with) a `resolveGlobals: true` response for the same path.
292
+ // SSR and client-nav produce the same eager/deferred split now, so the
293
+ // original reason for the `__nav:` bucket — a client-nav request must never
294
+ // inherit an SSR response's deferredSections (#277) — no longer applies. It
295
+ // is kept anyway, because this map is module-global and the payload it
296
+ // shares carries `pageUrl`, `flags`, and `device` derived from whichever
297
+ // request won the race. That cross-request bleed is pre-existing and wider
298
+ // than this bucket (two concurrent same-path requests already collide on
299
+ // cookies/UA/geo), but SSR and client-nav are exactly the pair whose
300
+ // `derivePageUrl` inputs differ most, so collapsing them would widen a
301
+ // known hole for no gain. `resolveGlobals` is part of the key for the same
302
+ // reason: a `resolveGlobals: false` request must not share a promise with a
303
+ // `resolveGlobals: true` one.
299
304
  const clientNav = isClientNavigation(fullPath, getRequestUrl());
300
305
  const inflightKey =
301
306
  (clientNav ? `__nav:${fullPath}` : fullPath) + (resolveGlobals ? "" : "|noGlobals");
@@ -392,9 +397,16 @@ export const loadCmsHomePage = createServerFn({ method: "GET" })
392
397
  // ---------------------------------------------------------------------------
393
398
 
394
399
  /**
395
- * @deprecated Prefer TanStack native streaming via `deferredPromises` in the
396
- * route loader. This POST server function is kept for backward compatibility
397
- * and as a fallback for SPA navigations.
400
+ * Resolves + enriches a single deferred section on demand, server-side.
401
+ *
402
+ * This is the deferred-resolution path for BOTH the initial SSR document and
403
+ * client (SPA) navigations — `deferredPromises`/TanStack native streaming is
404
+ * SSR-only, because promises cannot cross the server-fn JSON boundary. It
405
+ * rebuilds `MatcherContext` from the real incoming request (url/path/cookies/
406
+ * request), so the second hop sees the same per-request state the first one did
407
+ * (the `deco_segment` cookie set by the page response is already present, so
408
+ * sticky A/B decisions stay consistent — `flags` is intentionally left unset
409
+ * here: this response must not re-roll or re-persist the cohort cookie).
398
410
  */
399
411
  export const loadDeferredSection = createServerFn({ method: "POST" })
400
412
  .inputValidator(
@@ -558,8 +570,21 @@ export interface CmsRouteOptions {
558
570
  * Defaults to `["skuId"]` — variant selection is client-side only.
559
571
  */
560
572
  ignoreSearchParams?: string[];
561
- /** Custom pending component shown during SPA navigation. */
562
- pendingComponent?: () => any;
573
+ /**
574
+ * Pending component shown during SPA navigation while the route loader runs.
575
+ *
576
+ * NO DEFAULT, deliberately. With none set, TanStack keeps the previous page on
577
+ * screen until the new one commits — which at the sub-second latencies this
578
+ * route now sees is usually the better feel. Setting one buys feedback on a
579
+ * slow navigation at the cost of a page → skeleton → page swap on every
580
+ * navigation slower than {@link pendingMs} (held for at least
581
+ * {@link pendingMinMs}), and this is a *catch-all* route, so one skeleton
582
+ * shape has to serve PDP, PLP, search, and institutional pages alike.
583
+ * {@link CmsPagePendingFallback} is exported as a starting point; prefer a
584
+ * per-shape skeleton, or `NavigationProgress` (`@decocms/tanstack`) for
585
+ * feedback that does not replace the page at all.
586
+ */
587
+ pendingComponent?: (() => any) | null;
563
588
  /**
564
589
  * Custom error boundary rendered when the loader / page resolution throws.
565
590
  * Defaults to {@link CmsPageErrorFallback} (branded "instability" page with a
@@ -571,12 +596,23 @@ export interface CmsRouteOptions {
571
596
  * Delay (ms) before showing the pending component during SPA navigation.
572
597
  * If the loader resolves before this threshold, no pending UI is shown.
573
598
  * Prevents skeleton flash on fast cache-hit navigations. Default: 200.
599
+ * Inert unless {@link pendingComponent} is set.
600
+ *
601
+ * This is a *catch-all* route, so the same value covers a sub-100ms PLP facet
602
+ * toggle and a cold PDP. Raising it only DELAYS the skeleton on the slow
603
+ * navigation (a 1s `pendingMs` still shows it on a 2s nav) — it does not
604
+ * suppress it. Use {@link pendingMinMs} for the flicker case where the loader
605
+ * lands just after the threshold.
574
606
  */
575
607
  pendingMs?: number;
576
608
  /**
577
609
  * Minimum display time (ms) for the pending component once shown.
578
610
  * Prevents jarring flash when data arrives shortly after the threshold.
579
- * Default: 300.
611
+ * Default: 300. Inert unless {@link pendingComponent} is set.
612
+ *
613
+ * Independent of {@link pendingMs}, and applied after it: worst-case a
614
+ * navigation is held for `pendingMs + pendingMinMs` of visible skeleton
615
+ * before the new page commits.
580
616
  */
581
617
  pendingMinMs?: number;
582
618
  /**
@@ -905,7 +941,8 @@ export function cmsHomeRouteConfig(options: {
905
941
  defaultDescription?: string;
906
942
  /** Site name for OG title composition. Defaults to defaultTitle. */
907
943
  siteName?: string;
908
- pendingComponent?: () => any;
944
+ /** See `CmsRouteOptions.pendingComponent` — no default, deliberately. */
945
+ pendingComponent?: (() => any) | null;
909
946
  /** Delay (ms) before showing pending component. Default: 200. */
910
947
  pendingMs?: number;
911
948
  /** Minimum display time (ms) for pending component. Default: 300. */
@@ -919,6 +956,7 @@ export function cmsHomeRouteConfig(options: {
919
956
  defaultTitle,
920
957
  defaultDescription,
921
958
  siteName,
959
+ pendingComponent,
922
960
  pendingMs = 200,
923
961
  pendingMinMs = 300,
924
962
  errorComponent = CmsPageErrorFallback,
@@ -939,7 +977,7 @@ export function cmsHomeRouteConfig(options: {
939
977
  // See cmsRouteConfig loader for rationale.
940
978
  return page;
941
979
  },
942
- ...(options.pendingComponent ? { pendingComponent: options.pendingComponent } : {}),
980
+ ...(pendingComponent ? { pendingComponent } : {}),
943
981
  pendingMs,
944
982
  pendingMinMs,
945
983
  errorComponent,
@@ -36,10 +36,11 @@ export function derivePageUrl(fullPath: string, serverUrl: URL): string {
36
36
  * `serverUrl.pathname` is NOT the page path. On a real document request (SSR /
37
37
  * full reload, including bots) `serverUrl.pathname === basePath`.
38
38
  *
39
- * Section deferral is a streaming-SSR optimization (shrinks the initial HTML /
40
- * TTFB). On a client navigation the server fn returns JSON in one shot — there
41
- * is no streaming benefit, so deferral only adds a round-trip and a skeleton.
42
- * Callers use this to resolve all sections eagerly on SPA navigation.
39
+ * This does NOT gate section deferral: a client nav gets the same eager/deferred
40
+ * split as SSR, because the route loader is blocking and awaiting the below-fold
41
+ * sections freezes the transition. Callers use it to rebuild the real page URL
42
+ * (`derivePageUrl`) and to tell a SPA nav apart from a genuine AJAX consumer
43
+ * (`isProgrammaticFetch`) — both send `Sec-Fetch-Dest: empty`.
43
44
  *
44
45
  * Mirrors the `serverUrl.pathname === basePath` comparison `derivePageUrl`
45
46
  * already relies on, so the two stay consistent and we avoid hardcoding the
@@ -1368,8 +1368,13 @@ export function createDecoWorkerEntry(
1368
1368
  // bucket so a fetch-triggered eager response never poisons the navigation
1369
1369
  // (deferred) entry, and vice-versa. MUST use the same `Sec-Fetch-Dest:
1370
1370
  // empty` signal as isProgrammaticFetch so the key and render decisions can't
1371
- // diverge. `/_serverFn` (SPA-nav data) is excluded: it has its own keying
1372
- // and stays eager via isClientNavigation, not this bucket.
1371
+ // diverge. `/_serverFn` (SPA-nav data) is excluded: it sends the same
1372
+ // `Sec-Fetch-Dest: empty` but is NOT a programmatic fetch — it renders
1373
+ // through DecoPageRenderer and so keeps the same deferred split as the
1374
+ // document (isProgrammaticFetch bails on isClientNavigation for the same
1375
+ // reason). It needs no bucket of its own here: its cache key is the
1376
+ // `/_serverFn/...` pathname + canonicalized payload, which can never
1377
+ // collide with a document entry.
1373
1378
  const secFetchDest = request.headers.get("sec-fetch-dest");
1374
1379
  const isServerFnPath =
1375
1380
  url.pathname.startsWith("/_serverFn/") || url.pathname.startsWith("/_server/");