@timber-js/app 0.2.0-alpha.166 → 0.2.0-alpha.168

package/src/client/router.ts

@@ -155,6 +155,13 @@ export interface RouterDeps {
    * as a full page load with an unknown fragment landing at the top.
    */
   scrollToHash?: (hash: string) => boolean;
+
+  /**
+   * Whether the client segment cache is enabled. When false (the default),
+   * the router does not send X-Timber-State-Tree headers and does not
+   * populate the segment cache. Every navigation gets a full RSC payload.
+   */
+  clientSegmentCache?: boolean;
 }
 
 export interface RouterInstance {
@@ -292,6 +299,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
   /** Update the segment cache from server-provided segment metadata. */
   function updateSegmentCache(segmentInfo: SegmentInfo[] | null | undefined): void {
+    if (!deps.clientSegmentCache) return;
     if (!segmentInfo || segmentInfo.length === 0) return;
     const tree = buildSegmentTree(segmentInfo);
     if (tree) {
@@ -306,6 +314,89 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     }
   }
 
+  /**
+   * Atomically update all navigation-owned state for a new page. Every
+   * code path that changes the "current page" must go through this
+   * function — making "forgot a field" impossible by construction.
+   *
+   * The three operations:
+   * 1. Segment cache — update from server-provided segment metadata
+   * 2. Navigation state — params + pathname for useSegmentParams/usePathname
+   * 3. History stack — store the payload for instant back/forward replay
+   */
+  function commitNavigation(
+    url: string,
+    opts: {
+      payload: unknown;
+      params?: Record<string, string | string[]> | null;
+      segmentInfo?: SegmentInfo[] | null;
+      /** When true, clear the segment cache if segmentInfo is empty
+       *  (popstate replay for entries without layout metadata). */
+      clearSegmentCacheOnEmpty?: boolean;
+    }
+  ): NavigationState {
+    if (opts.segmentInfo && opts.segmentInfo.length > 0) {
+      updateSegmentCache(opts.segmentInfo);
+    } else if (opts.clearSegmentCacheOnEmpty) {
+      segmentCache.clear();
+    }
+
+    const navState = updateNavigationState(opts.params, url);
+
+    historyStack.push(url, {
+      payload: opts.payload,
+      params: navState.params,
+      segmentInfo: opts.segmentInfo,
+    });
+
+    return navState;
+  }
+
+  /**
+   * Wrap a navigation in the standard abort/pending/cleanup lifecycle.
+   * Consolidates the createNavAbort + setPending + staleness-guarded
+   * finally that was duplicated across navigate, refresh, and both
+   * handlePopState paths. AbortErrors are swallowed (not application
+   * errors); all other errors propagate to the caller.
+   */
+  async function runNavigation(
+    url: string,
+    fn: (navAbort: AbortController) => Promise<void>,
+    externalSignal?: AbortSignal
+  ): Promise<void> {
+    const navAbort = createNavAbort(externalSignal);
+    setPending(true, url);
+    try {
+      await fn(navAbort);
+    } catch (error) {
+      if (isAbortError(error)) return;
+      throw error;
+    } finally {
+      if (currentNavAbort === navAbort) {
+        currentNavAbort = null;
+        setPending(false);
+        deps.completeRouterNavigation?.();
+      }
+    }
+  }
+
+  /**
+   * Resolve thenable payloads in the test/fallback path (no navigateTransition).
+   * In production, React handles thenables from createFromFetch directly via
+   * Suspense. In tests, renderRoot is a plain mock that expects resolved values.
+   */
+  async function resolveForFallback(payload: unknown): Promise<unknown> {
+    if (
+      !deps.navigateTransition &&
+      payload != null &&
+      typeof payload === 'object' &&
+      'then' in payload
+    ) {
+      return await (payload as PromiseLike<unknown>);
+    }
+    return payload;
+  }
+
   function isPartialNavigation(skippedSegments: string[] | null | undefined): boolean {
     return skippedSegments != null && skippedSegments.length > 0;
   }
@@ -357,9 +448,11 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
   /**
    * Render a payload via navigateTransition (production) or renderRoot (tests).
-   * The perform callback should fetch data, update state, and return the
-   * FetchResult plus the NavigationState (so it can be passed explicitly
-   * to wrapPayload/renderRoot without temporal coupling).
+   * The perform callback should fetch data, call commitNavigation, and return
+   * the FetchResult plus the NavigationState.
+   *
+   * State management (segmentCache, navState, historyStack) is handled by
+   * commitNavigation inside perform — this function only handles rendering.
    */
   async function renderViaTransition(
     url: string,
@@ -372,11 +465,6 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         if (isPartialNavigation(result.skippedSegments)) {
           const segmentUpdates = buildSegmentUpdates(result);
 
-          historyStack.push(url, {
-            payload: null,
-            params: result.params,
-          });
-
           // Re-wrap the CURRENT element with new context values.
           // SegmentOutlets read updates from SegmentUpdateContext;
           // NavigationProvider gets new params/pathname.
@@ -389,10 +477,6 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         }
 
         // Full navigation — empty updates, render the new tree.
-        historyStack.push(url, {
-          payload: result.payload,
-          params: result.params,
-        });
         const element = wrapPayload(result.payload, result.navState);
         return { element, decodePromise: result.decodePromise };
       });
@@ -400,24 +484,8 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     }
     // Fallback: no transition (tests, no React tree)
     const result = await perform();
-    if (isPartialNavigation(result.skippedSegments)) {
-      historyStack.push(url, {
-        payload: null,
-        params: result.params,
-      });
-    } else {
-      // Resolve thenables before storing/rendering in the fallback path
-      // (tests without navigateTransition). In production, React handles
-      // thenables via Suspense; in tests, renderRoot expects resolved values.
-      const payload =
-        result.payload != null && typeof result.payload === 'object' && 'then' in result.payload
-          ? await (result.payload as PromiseLike<unknown>)
-          : result.payload;
-      historyStack.push(url, {
-        payload,
-        params: result.params,
-      });
-      renderPayload(payload, result.navState);
+    if (!isPartialNavigation(result.skippedSegments)) {
+      renderPayload(result.payload, result.navState);
     }
   }
 
@@ -480,7 +548,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     if (result === undefined) {
       // Fetch RSC payload with state tree for partial rendering.
       // Send current URL for intercepting route resolution (modal pattern).
-      const stateTree = segmentCache.serializeStateTree();
+      const stateTree = deps.clientSegmentCache ? segmentCache.serializeStateTree() : undefined;
       const rawCurrentUrl = deps.getCurrentUrl();
       const currentUrl = rawCurrentUrl.startsWith('http')
         ? new URL(rawCurrentUrl).pathname
@@ -505,18 +573,21 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       deps.setRouterNavigating?.(false);
     }
 
-    // NOTE: History push is deferred — the merged payload (after segment
-    // merging in renderViaTransition) is stored by the caller, not here.
-    // Storing result.payload here would record the partial (pre-merge)
-    // RSC tree, causing handlePopState to replay an incomplete tree.
-
-    // Update the segment cache with the new route's segment tree.
-    updateSegmentCache(result.segmentInfo);
-
-    // Update navigation state and capture it for explicit passing.
-    const navState = updateNavigationState(result.params, url);
+    // Resolve thenable payloads in the test path so popstate replay
+    // and renderPayload receive plain values (see resolveForFallback).
+    const payload = await resolveForFallback(result.payload);
+
+    // Atomically update all navigation state via commitNavigation.
+    // Partial navigations store null payload — the partial RSC tree
+    // can't be replayed standalone; popstate will fetch fresh.
+    const isPartial = isPartialNavigation(result.skippedSegments);
+    const navState = commitNavigation(url, {
+      payload: isPartial ? null : payload,
+      params: result.params,
+      segmentInfo: result.segmentInfo,
+    });
 
-    return { ...result, navState };
+    return { ...result, payload, navState };
   }
 
   async function navigate(url: string, options: NavigationOptions = {}): Promise<void> {
@@ -534,10 +605,6 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     const hash = hashIndex === -1 ? '' : url.slice(hashIndex);
     const fetchUrl = hashIndex === -1 ? url : url.slice(0, hashIndex);
 
-    // Create an abort controller for this navigation. Links to the external
-    // signal (Navigation API's event.signal) when provided.
-    const navAbort = createNavAbort(externalSignal);
-
     // Capture the departing page's scroll position for scroll={false} preservation.
     const currentScrollY = deps.getScrollY();
 
@@ -549,114 +616,69 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       deps.replaceState({ timber: true, scrollY: currentScrollY }, '', deps.getCurrentUrl());
     }
 
-    // When Navigation API is active, initiate the navigation via
-    // navigation.navigate() BEFORE the fetch. Unlike history.pushState()
-    // which commits the URL synchronously (so Chrome sees it as "done"),
-    // navigation.navigate() fires the navigate event before committing.
-    // Our handler intercepts with a deferred promise, and Chrome shows
-    // its native loading indicator until completeRouterNavigation()
-    // resolves it in the finally block (same time as TopLoader clears).
     let effectiveSkipHistory = skipHistory;
-    if (!skipHistory && deps.navigationNavigate) {
-      deps.setRouterNavigating?.(true);
-      deps.navigationNavigate(url, replace);
-      deps.setRouterNavigating?.(false);
-      effectiveSkipHistory = true;
-    }
-
-    setPending(true, url);
 
-    try {
-      await renderViaTransition(fetchUrl, () =>
-        performNavigationFetch(fetchUrl, {
-          replace,
-          commitUrl: url,
-          signal: navAbort.signal,
-          skipHistory: effectiveSkipHistory,
-        })
-      );
+    await runNavigation(
+      url,
+      async (navAbort) => {
+        // When Navigation API is active, initiate the navigation via
+        // navigation.navigate() BEFORE the fetch. Must happen after
+        // createNavAbort supersedes the previous navigation (done by
+        // runNavigation) so the old deferred is resolved first.
+        if (!effectiveSkipHistory && deps.navigationNavigate) {
+          deps.setRouterNavigating?.(true);
+          deps.navigationNavigate(url, replace);
+          deps.setRouterNavigating?.(false);
+          effectiveSkipHistory = true;
+        }
 
-      // Notify nuqs adapter (and any other listeners) that navigation completed.
-      window.dispatchEvent(new Event('timber:navigation-end'));
+        try {
+          await renderViaTransition(fetchUrl, () =>
+            performNavigationFetch(fetchUrl, {
+              replace,
+              commitUrl: url,
+              signal: navAbort.signal,
+              skipHistory: effectiveSkipHistory,
+            })
+          );
 
-      // Scroll-to-top on forward navigation, scroll to the #fragment target
-      // when the URL has one, or restore captured position for scroll={false}.
-      // React's render() on the document root can reset scroll during DOM
-      // reconciliation, so all scroll must be actively managed.
-      if (scroll && hash) {
-        scrollToHashAfterPaint(hash);
-      } else {
-        restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
-      }
-    } catch (error) {
-      // Version skew — server has been redeployed. Full page reload
-      // so the browser fetches the new bundle. See TIM-446.
-      if (error instanceof VersionSkewError) {
-        setHardNavigating(true);
-        window.location.reload();
-        return new Promise(() => {}) as never;
-      }
-      // Server-side redirect during RSC fetch → soft router navigation.
-      // The redirect navigate will push/replace its own URL.
-      if (error instanceof RedirectError) {
-        // Drop the redirect if a newer navigation superseded this one
-        // while the redirect response was in flight — the newer
-        // navigation wins, same as the stale-transition guard.
-        if (currentNavAbort !== navAbort) return;
-        // The recursive navigate() supersedes this one via createNavAbort,
-        // which also resolves this navigation's Navigation API deferred.
-        await navigate(error.redirectUrl, { replace: true });
-        return;
-      }
-      // Server 5xx error — hard-navigate so the server renders the
-      // error page as HTML. See design/10-error-handling.md
-      // §"Error Page Rendering for Client Navigation".
-      //
-      // Set hard-navigating flag BEFORE setting window.location.href:
-      // 1. Prevents Navigation API from intercepting → infinite loop
-      // 2. Causes NavigationRoot to throw unresolvedThenable → prevents
-      //    React from rendering children during page teardown (avoids
-      //    "Rendered more hooks" crashes). See TIM-626.
-      if (error instanceof ServerErrorResponse) {
-        setHardNavigating(true);
-        window.location.href = error.url;
-        return new Promise(() => {}) as never;
-      }
-      // Abort errors are not application errors — swallow silently.
-      if (isAbortError(error)) return;
-      throw error;
-    } finally {
-      // Staleness guard (TIM-1034): only clean up when this navigation
-      // still owns the abort controller. When a newer navigation
-      // superseded this one, createNavAbort() already replaced
-      // currentNavAbort — running setPending(false) /
-      // completeRouterNavigation() here would clear the NEWER
-      // navigation's pending state and resolve its Navigation API
-      // deferred. The superseding navigation resolved OUR deferred in
-      // createNavAbort().
-      if (currentNavAbort === navAbort) {
-        // Clear the abort controller so we don't abort a completed
-        // navigation when the next one starts. In dev mode, the RSC body
-        // stream stays open after data arrives (React's Flight client
-        // waits for debug rows). Aborting a "completed" navigation kills
-        // the open stream reader → "BodyStreamBuffer was aborted".
-        currentNavAbort = null;
-        setPending(false);
-        // Resolve the Navigation API deferred — clears the browser's
-        // native loading state (tab spinner) at the same time as the
-        // TopLoader.
-        deps.completeRouterNavigation?.();
-      }
-    }
+          // Notify nuqs adapter (and any other listeners) that navigation completed.
+          window.dispatchEvent(new Event('timber:navigation-end'));
+
+          // Scroll-to-top on forward navigation, scroll to the #fragment target
+          // when the URL has one, or restore captured position for scroll={false}.
+          if (scroll && hash) {
+            scrollToHashAfterPaint(hash);
+          } else {
+            restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
+          }
+        } catch (error) {
+          if (error instanceof VersionSkewError) {
+            setHardNavigating(true);
+            window.location.reload();
+            await new Promise(() => {});
+          }
+          if (error instanceof RedirectError) {
+            if (currentNavAbort !== navAbort) return;
+            await navigate(error.redirectUrl, { replace: true });
+            return;
+          }
+          if (error instanceof ServerErrorResponse) {
+            setHardNavigating(true);
+            window.location.href = error.url;
+            await new Promise(() => {});
+          }
+          throw error;
+        }
+      },
+      externalSignal
+    );
   }
 
   async function refresh(): Promise<void> {
     const currentUrl = deps.getCurrentUrl();
-    const navAbort = createNavAbort();
 
-    setPending(true, currentUrl);
-
-    try {
+    await runNavigation(currentUrl, async (navAbort) => {
       await renderViaTransition(currentUrl, async () => {
         // No state tree sent — server renders the complete RSC payload
         const result = await fetchRscPayload(
@@ -666,22 +688,15 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           undefined,
           navAbort.signal
         );
-        // History push handled by renderViaTransition (stores merged payload)
-        updateSegmentCache(result.segmentInfo);
-        const navState = updateNavigationState(result.params, currentUrl);
-        return { ...result, navState };
+        const payload = await resolveForFallback(result.payload);
+        const navState = commitNavigation(currentUrl, {
+          payload,
+          params: result.params,
+          segmentInfo: result.segmentInfo,
+        });
+        return { ...result, payload, navState };
       });
-    } catch (error) {
-      if (isAbortError(error)) return;
-      throw error;
-    } finally {
-      // Staleness guard (TIM-1034) — see navigate()'s finally block.
-      if (currentNavAbort === navAbort) {
-        currentNavAbort = null;
-        setPending(false);
-        deps.completeRouterNavigation?.();
-      }
-    }
+    });
   }
 
   async function handlePopState(
@@ -697,47 +712,53 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     if (entry && entry.payload !== null) {
       // Replay cached payload — no server roundtrip.
       //
-      // A forward navigation may still be in flight (back pressed while a
-      // slow RSC fetch was pending). createNavAbort() supersedes it: aborts
-      // its fetch and invalidates its render transition so the stale
-      // forward payload can't commit over this replay (TIM-1022). The
-      // replay itself is synchronous — nothing to abort later — so the
-      // controller is cleared immediately, and any pending state left by
-      // the superseded navigation is reset.
-      createNavAbort(externalSignal);
-      currentNavAbort = null;
-      setPending(false);
-      const navState = updateNavigationState(entry.params, url);
-      renderPayload(entry.payload, navState);
-      restoreScrollAfterPaint(scrollY);
+      // runNavigation supersedes any in-flight forward navigation (TIM-1022):
+      // aborts its fetch and invalidates its render transition so the stale
+      // forward payload can't commit over this replay. The replay itself is
+      // synchronous — the fn resolves immediately.
+      await runNavigation(
+        url,
+        async () => {
+          // clearSegmentCacheOnEmpty: popstate to an entry without layout
+          // metadata (e.g., initial SSR page) clears the cache so the next
+          // forward navigation gets a full render.
+          const navState = commitNavigation(url, {
+            payload: entry.payload,
+            params: entry.params,
+            segmentInfo: entry.segmentInfo,
+            clearSegmentCacheOnEmpty: true,
+          });
+          renderPayload(entry.payload, navState);
+          restoreScrollAfterPaint(scrollY);
+        },
+        externalSignal
+      );
     } else {
       // No cached payload — fetch from server.
       // This happens when navigating back to the initial SSR'd page
       // (its payload is null since it was rendered via SSR, not RSC fetch)
       // or when the entry doesn't exist at all.
-      const navAbort = createNavAbort(externalSignal);
-      setPending(true, url);
-      try {
-        await renderViaTransition(url, async () => {
-          const stateTree = segmentCache.serializeStateTree();
-          const result = await fetchRscPayload(url, deps, stateTree, undefined, navAbort.signal);
-          updateSegmentCache(result.segmentInfo);
-          const navState = updateNavigationState(result.params, url);
-          // History push handled by renderViaTransition (stores merged payload)
-          return { ...result, navState };
-        });
+      await runNavigation(
+        url,
+        async (navAbort) => {
+          await renderViaTransition(url, async () => {
+            const stateTree = deps.clientSegmentCache
+              ? segmentCache.serializeStateTree()
+              : undefined;
+            const result = await fetchRscPayload(url, deps, stateTree, undefined, navAbort.signal);
+            const payload = await resolveForFallback(result.payload);
+            const navState = commitNavigation(url, {
+              payload,
+              params: result.params,
+              segmentInfo: result.segmentInfo,
+            });
+            return { ...result, payload, navState };
+          });
 
-        restoreScrollAfterPaint(scrollY);
-      } catch (error) {
-        if (isAbortError(error)) return;
-        throw error;
-      } finally {
-        // Staleness guard (TIM-1034) — see navigate()'s finally block.
-        if (currentNavAbort === navAbort) {
-          currentNavAbort = null;
-          setPending(false);
-        }
-      }
+          restoreScrollAfterPaint(scrollY);
+        },
+        externalSignal
+      );
     }
   }
 
@@ -756,7 +777,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     if (historyStack.has(fetchUrl)) return;
 
     // Fire-and-forget fetch
-    const stateTree = segmentCache.serializeStateTree();
+    const stateTree = deps.clientSegmentCache ? segmentCache.serializeStateTree() : undefined;
     void fetchRscPayload(fetchUrl, deps, stateTree).then(
       (result) => {
         result.decodePromise?.catch(() => {});
@@ -783,21 +804,16 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // Render the piggybacked element tree from a server action response.
       // Updates the current history entry with the fresh payload —
       // same as refresh() but without a server fetch.
-      // Revalidation payloads are already resolved (no Flight thenable),
-      // so no segment merging is needed — just cache and render.
       const currentUrl = deps.getCurrentUrl();
 
-      // Revalidation doesn't change params/pathname — preserve current state.
-      // DO NOT call updateNavigationState(null, ...) here: that normalizes
-      // params to {}, clearing dynamic route params on every action response.
-      const navState = getNavigationState();
-
-      // Keep params on the overwritten entry — dropping them would make
-      // away-and-back navigation replay this page with params normalized
-      // to {} (TIM-1037).
-      historyStack.push(currentUrl, {
+      // Preserve existing segmentInfo so away-and-back navigation replays
+      // with a correct segment cache (TIM-1037). Preserve current params
+      // so dynamic route params aren't cleared to {}.
+      const existingEntry = historyStack.get(currentUrl);
+      const navState = commitNavigation(currentUrl, {
         payload: element,
-        params: navState.params,
+        params: getNavigationState().params,
+        segmentInfo: existingEntry?.segmentInfo,
       });
       renderPayload(element, navState);
     },

package/src/codec.ts

@@ -80,8 +80,10 @@ export const codec = {
   integer: {
     parse(value: string | string[] | undefined): number {
       const str = Array.isArray(value) ? value[0] : value;
+      if (!str || !/^(?:0|-?[1-9]\d*)$/.test(str))
+        throw new Error(`Expected integer, got '${str}'`);
       const n = Number(str);
-      if (!Number.isInteger(n)) throw new Error(`Expected integer, got '${str}'`);
+      if (!Number.isSafeInteger(n)) throw new Error(`Expected integer, got '${str}'`);
       return n;
     },
     serialize(value: number): string | null {

package/src/config-types.ts

@@ -46,9 +46,6 @@ export interface TimberUserConfig {
    */
   clientJavascript?: boolean | ClientJavascriptConfig;
   adapter?: unknown;
-  cacheHandler?: unknown;
-  /** CDN purge handler — called on revalidateTag/cache.invalidate to purge CDN-cached responses. */
-  cdnPurge?: unknown;
   allowedOrigins?: string[];
   csrf?: boolean;
   limits?: {
@@ -56,40 +53,6 @@ export interface TimberUserConfig {
     uploadBodySize?: string;
     maxFields?: number;
   };
-  /**
-   * Server-action form handling.
-   *
-   * See design/08-forms-and-actions.md §"Validation errors" and
-   * design/13-security.md §"Sensitive field stripping".
-   */
-  /**
-   * Server action runtime behavior.
-   *
-   * See design/08-forms-and-actions.md §"Middleware for Server Actions".
-   */
-  actions?: {
-    /**
-     * Run `middleware.ts` on server action requests before dispatching.
-     *
-     * **Default: `true`** — middleware runs on every action POST so
-     * authentication, rate limiting, tenant isolation, IP allow-listing,
-     * and request-header injection apply uniformly to page renders, route
-     * handlers, and server actions. This closes the auth-bypass class of
-     * issue identified by Next.js CVE-2025-29927: developers can put a
-     * single auth check in `middleware.ts` and trust that it gates every
-     * unsafe-method request.
-     *
-     * Set to `false` to restore the legacy behavior where actions skip
-     * middleware entirely. This is **not recommended** outside of niche
-     * cases (e.g. middleware that rewrites POST bodies and would corrupt
-     * action submissions). When false, you are responsible for placing
-     * auth, rate limiting, and other cross-cutting checks inside every
-     * action — typically via `createActionClient({ middleware: ... })`.
-     *
-     * See TIM-871.
-     */
-    runMiddleware?: boolean;
-  };
   forms?: {
     /**
      * Strip sensitive fields (passwords, tokens, CVV, SSN, etc.) from the
@@ -286,6 +249,22 @@ export interface TimberUserConfig {
    * ```
    */
   buildDir?: string;
+  /**
+   * Enable the client-side segment cache for partial navigation.
+   *
+   * When enabled, the router serializes the mounted segment tree into an
+   * `X-Timber-State-Tree` header on every client navigation. The server
+   * skips re-rendering unchanged sync layouts and sends a partial RSC
+   * payload. The client merges the partial payload with its cached segments.
+   *
+   * When disabled (the default), every navigation gets a full RSC payload.
+   *
+   * This is a performance optimization only — not a security boundary.
+   * The server always runs all `access.ts` files regardless.
+   *
+   * See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+   */
+  clientSegmentCache?: boolean;
   topLoader?: {
     /** Whether the top-loader is enabled. Default: true. */
     enabled?: boolean;