@timber-js/app 0.2.0-alpha.6 → 0.2.0-alpha.60

package/src/client/router.ts

@@ -6,13 +6,18 @@ import type { SegmentInfo } from './segment-cache';
 import { HistoryStack } from './history';
 import type { HeadElement } from './head';
 import { setCurrentParams } from './use-params.js';
-import { setNavigationState } from './navigation-context.js';
 import {
-  SegmentElementCache,
-  cacheSegmentElements,
-  mergeSegmentTree,
-} from './segment-merger.js';
-import { fetchRscPayload, RedirectError } from './rsc-fetch.js';
+  setNavigationState,
+  getNavigationState,
+  type NavigationState,
+} from './navigation-context.js';
+import { SegmentElementCache, cacheSegmentElements, mergeSegmentTree } from './segment-merger.js';
+import {
+  fetchRscPayload,
+  RedirectError,
+  ServerErrorResponse,
+  VersionSkewError,
+} from './rsc-fetch.js';
 import type { FetchResult } from './rsc-fetch.js';
 
 // ─── Types ───────────────────────────────────────────────────────
@@ -35,8 +40,12 @@ export type RscDecoder = (fetchPromise: Promise<Response>) => unknown;
  * Function that renders a decoded RSC element tree into the DOM.
  * In production: reactRoot.render(element).
  * In tests: a no-op or mock.
+ *
+ * Receives the current NavigationState explicitly — no temporal
+ * coupling with setNavigationState/getNavigationState. The renderer
+ * wraps the element in NavigationProvider with this state.
  */
-export type RootRenderer = (element: unknown) => void;
+export type RootRenderer = (element: unknown, navState: NavigationState) => void;
 
 /**
  * Platform dependencies injected for testability. In production these
@@ -68,13 +77,17 @@ export interface RouterDeps {
    *
    * The `perform` callback receives a `wrapPayload` function to wrap the
    * decoded RSC payload with NavigationProvider + NuqsAdapter before
-   * TransitionRoot sets it as the new element.
+   * TransitionRoot sets it as the new element. The `wrapPayload` function
+   * receives the NavigationState explicitly — no temporal coupling with
+   * getNavigationState().
    *
    * If not provided (tests), the router falls back to renderRoot.
    */
   navigateTransition?: (
     pendingUrl: string,
-    perform: (wrapPayload: (payload: unknown) => unknown) => Promise<unknown>
+    perform: (
+      wrapPayload: (payload: unknown, navState: NavigationState) => unknown
+    ) => Promise<unknown>
   ) => Promise<void>;
 }
 
@@ -134,21 +147,40 @@ function isAbortError(error: unknown): boolean {
  * Create a router instance. In production, called once at app hydration
  * with real browser APIs. In tests, called with mock dependencies.
  */
+/**
+ * Router navigation phase — discriminated union replacing scattered
+ * `pending` + `pendingUrl` boolean flags.
+ *
+ * - `idle`: No navigation in flight. The committed params/pathname
+ *   are current.
+ * - `navigating`: A fetch or render is in progress. `targetUrl` is
+ *   the destination being navigated to.
+ */
+export type RouterPhase = { phase: 'idle' } | { phase: 'navigating'; targetUrl: string };
+
 export function createRouter(deps: RouterDeps): RouterInstance {
   const segmentCache = new SegmentCache();
   const prefetchCache = new PrefetchCache();
   const historyStack = new HistoryStack();
   const segmentElementCache = new SegmentElementCache();
 
-  let pending = false;
-  let pendingUrl: string | null = null;
+  let routerPhase: RouterPhase = { phase: 'idle' };
   const pendingListeners = new Set<(pending: boolean) => void>();
 
   function setPending(value: boolean, url?: string): void {
-    const newPendingUrl = value && url ? url : null;
-    if (pending === value && pendingUrl === newPendingUrl) return;
-    pending = value;
-    pendingUrl = newPendingUrl;
+    const next: RouterPhase =
+      value && url ? { phase: 'navigating', targetUrl: url } : { phase: 'idle' };
+    // Skip no-op updates
+    if (
+      routerPhase.phase === next.phase &&
+      (routerPhase.phase === 'idle' ||
+        (routerPhase.phase === 'navigating' &&
+          next.phase === 'navigating' &&
+          routerPhase.targetUrl === next.targetUrl))
+    ) {
+      return;
+    }
+    routerPhase = next;
     // Notify external store listeners (non-React consumers).
     // React-facing pending state is handled by useOptimistic in
     // TransitionRoot via navigateTransition — not this function.
@@ -167,9 +199,9 @@ export function createRouter(deps: RouterDeps): RouterInstance {
   }
 
   /** Render a decoded RSC payload into the DOM if a renderer is available. */
-  function renderPayload(payload: unknown): void {
+  function renderPayload(payload: unknown, navState: NavigationState): void {
     if (deps.renderRoot) {
-      deps.renderRoot(payload);
+      deps.renderRoot(payload, navState);
     }
   }
 
@@ -198,32 +230,34 @@ export function createRouter(deps: RouterDeps): RouterInstance {
   /**
    * Update navigation state (params + pathname) for the next render.
    *
-   * Sets both the module-level fallback (for tests and SSR) and the
-   * navigation context state (read by renderRoot to wrap the element
-   * in NavigationProvider). The context update is atomic with the tree
-   * render — both are passed to reactRoot.render() in the same call.
+   * Sets the module-level fallback (for tests and SSR) and the
+   * globalThis bridge, then returns the NavigationState so callers
+   * can pass it explicitly to renderRoot/wrapPayload — eliminating
+   * temporal coupling with getNavigationState().
    */
   function updateNavigationState(
     params: Record<string, string | string[]> | null | undefined,
     url: string
-  ): void {
+  ): NavigationState {
     const resolvedParams = params ?? {};
     // Module-level fallback for tests (no NavigationProvider) and SSR
     setCurrentParams(resolvedParams);
-    // Navigation context — read by renderRoot to wrap the RSC element
+    // globalThis bridge — kept for backward compat
     const pathname = url.startsWith('http') ? new URL(url).pathname : url.split('?')[0] || '/';
-    setNavigationState({ params: resolvedParams, pathname });
+    const navState: NavigationState = { params: resolvedParams, pathname };
+    setNavigationState(navState);
+    return navState;
   }
 
   /**
    * Render a payload via navigateTransition (production) or renderRoot (tests).
-   * The perform callback should fetch data, update state, and return the payload.
-   * In production, the entire callback runs inside a React transition with
-   * useOptimistic for the pending URL. In tests, the payload is rendered directly.
+   * 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).
    */
   async function renderViaTransition(
     url: string,
-    perform: () => Promise<FetchResult>
+    perform: () => Promise<FetchResult & { navState: NavigationState }>
   ): Promise<HeadElement[] | null> {
     if (deps.navigateTransition) {
       let headElements: HeadElement[] | null = null;
@@ -239,7 +273,9 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           headElements: result.headElements,
           params: result.params,
         });
-        return wrapPayload(merged);
+        // Pass navState explicitly — wrapPayload wraps element in
+        // NavigationProvider with this state, no getNavigationState() needed.
+        return wrapPayload(merged, result.navState);
       });
       return headElements;
     }
@@ -253,7 +289,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       headElements: result.headElements,
       params: result.params,
     });
-    renderPayload(merged);
+    renderPayload(merged, result.navState);
     return result.headElements;
   }
 
@@ -273,6 +309,17 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     }
   }
 
+  /**
+   * Schedule scroll restoration after the next paint and fire the
+   * scroll-restored event. Used by navigate, popstate, and refresh.
+   */
+  function restoreScrollAfterPaint(scrollY: number): void {
+    afterPaint(() => {
+      deps.scrollTo(0, scrollY);
+      window.dispatchEvent(new Event('timber:scroll-restored'));
+    });
+  }
+
   /**
    * Core navigation logic shared between the transition and fallback paths.
    * Fetches the RSC payload, updates all state, and returns the result.
@@ -280,7 +327,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
   async function performNavigationFetch(
     url: string,
     options: { replace: boolean }
-  ): Promise<FetchResult> {
+  ): Promise<FetchResult & { navState: NavigationState }> {
     // Check prefetch cache first. PrefetchResult has optional segmentInfo/params
     // fields — normalize to null for FetchResult compatibility.
     const prefetched = prefetchCache.consume(url);
@@ -320,10 +367,10 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     // Update the segment cache with the new route's segment tree.
     updateSegmentCache(result.segmentInfo);
 
-    // Update navigation state (params + pathname) before rendering.
-    updateNavigationState(result.params, url);
+    // Update navigation state and capture it for explicit passing.
+    const navState = updateNavigationState(result.params, url);
 
-    return result;
+    return { ...result, navState };
   }
 
   async function navigate(url: string, options: NavigationOptions = {}): Promise<void> {
@@ -354,21 +401,31 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // Scroll-to-top on forward navigation, 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.
-      afterPaint(() => {
-        if (scroll) {
-          deps.scrollTo(0, 0);
-        } else {
-          deps.scrollTo(0, currentScrollY);
-        }
-        window.dispatchEvent(new Event('timber:scroll-restored'));
-      });
+      restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
     } catch (error) {
+      // Version skew — server has been redeployed. Trigger full page reload
+      // so the browser fetches the new bundle. See TIM-446.
+      if (error instanceof VersionSkewError) {
+        // Import triggerStaleReload dynamically to avoid circular deps
+        // and keep the reload logic centralized with its loop guard.
+        const { triggerStaleReload } = await import('./stale-reload.js');
+        triggerStaleReload();
+        // Return a never-resolving promise — page is reloading.
+        return new Promise(() => {}) as never;
+      }
       // Server-side redirect during RSC fetch → soft router navigation.
       if (error instanceof RedirectError) {
         setPending(false);
         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".
+      if (error instanceof ServerErrorResponse) {
+        window.location.href = error.url;
+        return new Promise(() => {}) as never;
+      }
       // Abort errors are not application errors — swallow silently.
       if (isAbortError(error)) return;
       throw error;
@@ -388,8 +445,8 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         const result = await fetchRscPayload(currentUrl, deps);
         // History push handled by renderViaTransition (stores merged payload)
         updateSegmentCache(result.segmentInfo);
-        updateNavigationState(result.params, currentUrl);
-        return result;
+        const navState = updateNavigationState(result.params, currentUrl);
+        return { ...result, navState };
       });
 
       applyHead(headElements);
@@ -406,13 +463,10 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
     if (entry && entry.payload !== null) {
       // Replay cached payload — no server roundtrip
-      updateNavigationState(entry.params, url);
-      renderPayload(entry.payload);
+      const navState = updateNavigationState(entry.params, url);
+      renderPayload(entry.payload, navState);
       applyHead(entry.headElements);
-      afterPaint(() => {
-        deps.scrollTo(0, scrollY);
-        window.dispatchEvent(new Event('timber:scroll-restored'));
-      });
+      restoreScrollAfterPaint(scrollY);
     } else {
       // No cached payload — fetch from server.
       // This happens when navigating back to the initial SSR'd page
@@ -421,19 +475,18 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       setPending(true, url);
       try {
         const headElements = await renderViaTransition(url, async () => {
-          const stateTree = segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths());
+          const stateTree = segmentCache.serializeStateTree(
+            segmentElementCache.getMergeablePaths()
+          );
           const result = await fetchRscPayload(url, deps, stateTree);
           updateSegmentCache(result.segmentInfo);
-          updateNavigationState(result.params, url);
+          const navState = updateNavigationState(result.params, url);
           // History push handled by renderViaTransition (stores merged payload)
-          return result;
+          return { ...result, navState };
         });
 
         applyHead(headElements);
-        afterPaint(() => {
-          deps.scrollTo(0, scrollY);
-          window.dispatchEvent(new Event('timber:scroll-restored'));
-        });
+        restoreScrollAfterPaint(scrollY);
       } finally {
         setPending(false);
       }
@@ -465,8 +518,8 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     navigate,
     refresh,
     handlePopState,
-    isPending: () => pending,
-    getPendingUrl: () => pendingUrl,
+    isPending: () => routerPhase.phase === 'navigating',
+    getPendingUrl: () => (routerPhase.phase === 'navigating' ? routerPhase.targetUrl : null),
     onPendingChange(listener) {
       pendingListeners.add(listener);
       return () => pendingListeners.delete(listener);
@@ -483,7 +536,11 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         payload: merged,
         headElements,
       });
-      renderPayload(merged);
+      // 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();
+      renderPayload(merged, navState);
       applyHead(headElements);
     },
     initSegmentCache: (segments: SegmentInfo[]) => updateSegmentCache(segments),

package/src/client/rsc-fetch.ts

@@ -23,7 +23,7 @@ export interface FetchResult {
   headElements: HeadElement[] | null;
   /** Segment metadata from X-Timber-Segments header for populating the segment cache. */
   segmentInfo: SegmentInfo[] | null;
-  /** Route params from X-Timber-Params header for populating useParams(). */
+  /** Route params from X-Timber-Params header for populating useSegmentParams(). */
   params: Record<string, string | string[]> | null;
   /** Segment paths that were skipped by the server (for client-side merging). */
   skippedSegments: string[] | null;
@@ -58,6 +58,43 @@ function appendRscParam(url: string): string {
   return `${url}${separator}_rsc=${generateCacheBustId()}`;
 }
 
+// ─── Deployment ID ───────────────────────────────────────────────
+
+/**
+ * The client's deployment ID, set at bootstrap from the runtime config.
+ * Sent with every RSC/action request for version skew detection.
+ * Null in dev mode. See TIM-446.
+ */
+let clientDeploymentId: string | null = null;
+
+/** Set the client deployment ID. Called once at bootstrap. */
+export function setClientDeploymentId(id: string | null): void {
+  clientDeploymentId = id;
+}
+
+/** Get the client deployment ID. */
+export function getClientDeploymentId(): string | null {
+  return clientDeploymentId;
+}
+
+// ─── Reload Signal ───────────────────────────────────────────────
+
+/** Header name used by the server to signal a version skew reload. */
+export const RELOAD_HEADER = 'X-Timber-Reload';
+
+/** Header name for the client's deployment ID. */
+export const DEPLOYMENT_ID_HEADER = 'X-Timber-Deployment-Id';
+
+/**
+ * Check if a response signals a version skew reload.
+ * Triggers a full page reload if the server indicates the client is stale.
+ */
+export function checkReloadSignal(response: Response): boolean {
+  return response.headers.get(RELOAD_HEADER) === '1';
+}
+
+// ─── Header Builder ──────────────────────────────────────────────
+
 export function buildRscHeaders(
   stateTree: { segments: string[] } | undefined,
   currentUrl?: string
@@ -75,6 +112,13 @@ export function buildRscHeaders(
   if (currentUrl) {
     headers['X-Timber-URL'] = currentUrl;
   }
+  // Send deployment ID for version skew detection (TIM-446).
+  // The server compares this against the current build's ID.
+  // On mismatch, the server signals a reload instead of returning
+  // an RSC payload with mismatched module references.
+  if (clientDeploymentId) {
+    headers[DEPLOYMENT_ID_HEADER] = clientDeploymentId;
+  }
   return headers;
 }
 
@@ -135,7 +179,7 @@ export function extractSkippedSegments(response: Response): string[] | null {
  * Extract route params from the X-Timber-Params response header.
  * Returns null if the header is missing or malformed.
  *
- * Used to populate useParams() after client-side navigation.
+ * Used to populate useSegmentParams() after client-side navigation.
  */
 export function extractParams(response: Response): Record<string, string | string[]> | null {
   const header = response.headers.get('X-Timber-Params');
@@ -161,6 +205,35 @@ export class RedirectError extends Error {
   }
 }
 
+/**
+ * Thrown when the server signals a version skew (X-Timber-Reload header).
+ * Caught in navigate() to trigger a full page reload via triggerStaleReload().
+ * See TIM-446.
+ */
+export class VersionSkewError extends Error {
+  constructor() {
+    super('Version skew detected — server has been redeployed');
+  }
+}
+
+/**
+ * Thrown when the server returns a 5xx error for an RSC payload request.
+ * The server sends X-Timber-Error header and a JSON body instead of a
+ * broken RSC stream. Caught in navigate() to trigger a hard navigation
+ * so the server can render the error page as HTML.
+ *
+ * See design/10-error-handling.md §"Error Page Rendering for Client Navigation"
+ */
+export class ServerErrorResponse extends Error {
+  readonly status: number;
+  readonly url: string;
+  constructor(status: number, url: string) {
+    super(`Server error ${status} during navigation to ${url}`);
+    this.status = status;
+    this.url = url;
+  }
+}
+
 // ─── Fetch ───────────────────────────────────────────────────────
 
 /**
@@ -192,6 +265,12 @@ export async function fetchRscPayload(
     let params: Record<string, string | string[]> | null = null;
     let skippedSegments: string[] | null = null;
     const wrappedPromise = fetchPromise.then((response) => {
+      // Version skew detection (TIM-446): if the server signals a reload,
+      // throw VersionSkewError so the caller (router navigate) can trigger
+      // a full page reload via triggerStaleReload().
+      if (checkReloadSignal(response)) {
+        throw new VersionSkewError();
+      }
       // Detect server-side redirects. The server returns 204 + X-Timber-Redirect
       // for RSC payload requests instead of a raw 302, because fetch with
       // redirect: "manual" turns 302s into opaque redirects (status 0, null body)
@@ -202,6 +281,13 @@ export async function fetchRscPayload(
       if (redirectLocation) {
         throw new RedirectError(redirectLocation);
       }
+      // Detect server 5xx errors. The server returns X-Timber-Error header
+      // with a JSON body instead of a broken RSC stream. Hard-navigate so
+      // the server renders the error page as HTML via the SSR-only path.
+      // See design/10-error-handling.md §"Error Page Rendering for Client Navigation"
+      if (response.headers.get('X-Timber-Error') === '1') {
+        throw new ServerErrorResponse(response.status, url);
+      }
       headElements = extractHeadElements(response);
       segmentInfo = extractSegmentInfo(response);
       params = extractParams(response);

package/src/client/segment-cache.ts

@@ -11,7 +11,7 @@ export interface PrefetchResult {
   headElements: HeadElement[] | null;
   /** Segment metadata from X-Timber-Segments header for populating the segment cache. */
   segmentInfo?: SegmentInfo[] | null;
-  /** Route params from X-Timber-Params header for populating useParams(). */
+  /** Route params from X-Timber-Params header for populating useSegmentParams(). */
   params?: Record<string, string | string[]> | null;
   /** Segment paths skipped by the server (for client-side merging). */
   skippedSegments?: string[] | null;

package/src/client/segment-context.ts

@@ -52,7 +52,12 @@ interface SegmentProviderProps {
  * Wraps each layout to provide segment position context.
  * Injected by rsc-entry.ts during element tree construction.
  */
-export function SegmentProvider({ segments, segmentId: _segmentId, parallelRouteKeys, children }: SegmentProviderProps) {
+export function SegmentProvider({
+  segments,
+  segmentId: _segmentId,
+  parallelRouteKeys,
+  children,
+}: SegmentProviderProps) {
   const value = useMemo(
     () => ({ segments, parallelRouteKeys }),
     // segments and parallelRouteKeys are static per layout — they don't change

package/src/client/segment-merger.ts

@@ -186,10 +186,7 @@ function walkChildren(children: ReactNode, out: CachedSegmentEntry[]): void {
  * Cache all segment subtrees from a fully-rendered RSC element tree.
  * Call this after every full RSC payload render (navigate, refresh, hydration).
  */
-export function cacheSegmentElements(
-  element: unknown,
-  cache: SegmentElementCache
-): void {
+export function cacheSegmentElements(element: unknown, cache: SegmentElementCache): void {
   const segments = extractSegments(element);
   for (const entry of segments) {
     cache.set(entry.segmentPath, entry);
@@ -208,10 +205,7 @@ export function cacheSegmentElements(
  */
 type TreePath = Array<{ element: ReactElement; childIndex: number }>;
 
-function findSegmentProviderPath(
-  node: ReactElement,
-  targetPath?: string
-): TreePath | null {
+function findSegmentProviderPath(node: ReactElement, targetPath?: string): TreePath | null {
   const children = (node.props as { children?: ReactNode }).children;
   if (children == null) return null;
 

package/src/client/segment-outlet.tsx

@@ -0,0 +1,86 @@
+/**
+ * SegmentOutlet — client component boundary at each layout segment.
+ *
+ * Replaces the post-hoc tree walking in segment-merger.ts with an explicit
+ * client component at each segment boundary. Each outlet:
+ *
+ * 1. Knows its own segment path (prop from the server)
+ * 2. Caches its children in a ref across navigations
+ * 3. When `keepCurrent` is true (partial navigation, this segment skipped),
+ *    returns the previously cached children — layout state is preserved
+ * 4. When `keepCurrent` is false (full navigation or this segment changed),
+ *    stores and renders the new children
+ *
+ * This eliminates the need for client-side element tree walking, which
+ * breaks on real RSC trees due to opaque client component lazy refs,
+ * Suspense thenables, and AccessGate wrappers.
+ *
+ * Architecture is similar to Next.js's `<LayoutRouter>` client component —
+ * each layout boundary is an explicit client component that manages its
+ * own subtree. See design/19-client-navigation.md.
+ *
+ * Security: This is a performance optimization only. The server always
+ * runs all access.ts files regardless of segment skipping. A fabricated
+ * keepCurrent prop can only cause stale layouts — never auth bypass.
+ * See design/13-security.md §"State tree manipulation".
+ */
+
+'use client';
+
+import { useRef, type ReactNode } from 'react';
+
+export interface SegmentOutletProps {
+  /**
+   * Unique identifier for this segment. For normal segments this is the
+   * urlPath (e.g., "/", "/dashboard"). For route groups this includes the
+   * group name (e.g., "/(marketing)") to distinguish siblings that share
+   * the same urlPath. Must match the segmentId used in state-tree-diff.ts.
+   */
+  segmentPath: string;
+
+  /**
+   * When true, the outlet returns its previously cached children instead
+   * of rendering the new children prop. Set by the server when this
+   * segment was skipped (the client already has the layout mounted).
+   *
+   * On the first render (SSR/hydration), this is always false — there's
+   * no cached content yet. On subsequent partial navigations, the server
+   * sets this to true for segments it skipped rendering.
+   */
+  keepCurrent?: boolean;
+
+  /** The segment's React subtree (layout + inner content). */
+  children: ReactNode;
+}
+
+/**
+ * Client component boundary at each layout segment in the element tree.
+ *
+ * On full navigation: receives new children, stores them, renders them.
+ * On partial navigation (keepCurrent=true): ignores children prop,
+ * returns previously stored content — React reconciles the same elements,
+ * preserving all client component state in the layout subtree.
+ *
+ * React preserves the ref across `reactRoot.render()` calls because:
+ * - SegmentOutlet has a stable type (client component module reference)
+ * - It appears at the same tree position on every navigation
+ * - React reconciles same-type, same-position → instance preserved
+ */
+export function SegmentOutlet({
+  segmentPath: _segmentPath,
+  keepCurrent = false,
+  children,
+}: SegmentOutletProps) {
+  // Store content in a ref to avoid triggering re-renders on cache updates.
+  // The ref persists across reactRoot.render() calls because React reconciles
+  // the same component type at the same tree position.
+  const contentRef = useRef<ReactNode>(null);
+
+  if (!keepCurrent) {
+    // Full render or this segment was re-rendered — store and render new content
+    contentRef.current = children;
+  }
+  // else: keepCurrent=true — return previously cached content
+
+  return contentRef.current;
+}