@timber-js/app 0.2.0-alpha.68 → 0.2.0-alpha.69

package/src/client/router.ts

@@ -18,6 +18,7 @@ import {
   ServerErrorResponse,
   VersionSkewError,
 } from './rsc-fetch.js';
+import { setHardNavigating } from './navigation-root.js';
 import type { FetchResult } from './rsc-fetch.js';
 
 // ─── Types ───────────────────────────────────────────────────────
@@ -90,7 +91,7 @@ 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. The `wrapPayload` function
+   * NavigationRoot sets it as the new element. The `wrapPayload` function
    * receives the NavigationState explicitly — no temporal coupling with
    * getNavigationState().
    *
@@ -262,7 +263,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     routerPhase = next;
     // Notify external store listeners (non-React consumers).
     // React-facing pending state is handled by useOptimistic in
-    // TransitionRoot via navigateTransition — not this function.
+    // NavigationRoot via navigateTransition — not this function.
     for (const listener of pendingListeners) {
       listener(value);
     }
@@ -519,7 +520,10 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     } catch (error) {
       // Version skew — server has been redeployed. Trigger full page reload
       // so the browser fetches the new bundle. See TIM-446.
+      // Set hard-navigating flag to prevent Navigation API interception
+      // and React from rendering during page teardown. See TIM-626.
       if (error instanceof VersionSkewError) {
+        setHardNavigating(true);
         // Import triggerStaleReload dynamically to avoid circular deps
         // and keep the reload logic centralized with its loop guard.
         const { triggerStaleReload } = await import('./stale-reload.js');
@@ -538,7 +542,14 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // 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;
       }
@@ -546,6 +557,15 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       if (isAbortError(error)) return;
       throw error;
     } finally {
+      // 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". By clearing the controller here,
+      // createNavAbort() becomes a no-op for completed navigations.
+      if (currentNavAbort === navAbort) {
+        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.
@@ -576,7 +596,15 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       });
 
       applyHead(headElements);
+    } catch (error) {
+      // Stale transition (superseded by a newer navigation) or aborted
+      // fetch — silently ignore. See TIM-629.
+      if (isAbortError(error)) return;
+      throw error;
     } finally {
+      if (currentNavAbort === navAbort) {
+        currentNavAbort = null;
+      }
       setPending(false);
       deps.completeRouterNavigation?.();
     }
@@ -619,7 +647,15 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
         applyHead(headElements);
         restoreScrollAfterPaint(scrollY);
+      } catch (error) {
+        // Stale transition (superseded by a newer navigation) or aborted
+        // fetch — silently ignore. See TIM-629.
+        if (isAbortError(error)) return;
+        throw error;
       } finally {
+        if (currentNavAbort === navAbort) {
+          currentNavAbort = null;
+        }
         setPending(false);
       }
     }

package/src/client/top-loader.tsx

@@ -3,7 +3,7 @@
  *
  * Shows an animated progress bar at the top of the viewport while an RSC
  * navigation is in flight. Injected automatically by the framework into
- * TransitionRoot — users never render this component directly.
+ * NavigationRoot — users never render this component directly.
  *
  * Configuration is via timber.config.ts `topLoader` key. Enabled by default.
  * Users who want a fully custom progress indicator disable the built-in one
@@ -97,7 +97,7 @@ function ensureKeyframes(): void {
 // ─── Component ───────────────────────────────────────────────────
 
 /**
- * Internal top-loader component. Injected by TransitionRoot.
+ * Internal top-loader component. Injected by NavigationRoot.
  *
  * Reads pending navigation state from PendingNavigationContext.
  * Phase transitions are derived synchronously during render:

package/src/client/use-navigation-pending.ts

@@ -1,7 +1,7 @@
 // useNavigationPending — returns true while an RSC navigation is in flight.
 // See design/19-client-navigation.md §"useNavigationPending()"
 //
-// Reads from PendingNavigationContext (provided by TransitionRoot) so the
+// Reads from PendingNavigationContext (provided by NavigationRoot) so the
 // pending state shows immediately (urgent update) and clears atomically
 // with the new tree (same startTransition commit).
 

package/src/server/route-element-builder.ts

@@ -34,6 +34,34 @@ import type { InterceptionContext } from './pipeline.js';
 import { shouldSkipSegment } from './state-tree-diff.js';
 import { loadModule } from './safe-load.js';
 
+// ─── Client Reference Detection ──────────────────────────────────────────
+
+/**
+ * Symbol used by React Flight to mark client references.
+ * Client references are proxy objects created by @vitejs/plugin-rsc for
+ * 'use client' modules in the RSC environment. They must be passed to
+ * createElement() — calling them as functions throws:
+ * "Unexpectedly client reference export 'default' is called on server"
+ */
+const CLIENT_REFERENCE_TAG = Symbol.for('react.client.reference');
+
+/**
+ * Detect whether a component is a React client reference.
+ * Client references have $$typeof set to Symbol.for('react.client.reference')
+ * by registerClientReference() in the React Flight server runtime.
+ *
+ * Used to skip OTEL tracing wrappers that would call the component as a
+ * function. Client components must go through createElement only — they are
+ * serialized as references in the RSC Flight stream, not executed on the server.
+ */
+export function isClientReference(component: unknown): boolean {
+  return (
+    component != null &&
+    typeof component === 'function' &&
+    (component as unknown as Record<string, unknown>).$$typeof === CLIENT_REFERENCE_TAG
+  );
+}
+
 // ─── Param Coercion Error ─────────────────────────────────────────────────
 
 /**
@@ -308,16 +336,25 @@ export async function buildRouteElement(
   // Build element tree: page wrapped in layouts (innermost to outermost)
   const h = createElement as (...args: unknown[]) => React.ReactElement;
 
-  // Wrap the page component in an OTEL span
-  const TracedPage = async (props: Record<string, unknown>) => {
-    return withSpan(
-      'timber.page',
-      { 'timber.route': match.segments[match.segments.length - 1]?.urlPath ?? '/' },
-      () => (PageComponent as (props: Record<string, unknown>) => unknown)(props)
-    );
-  };
-
-  let element = h(TracedPage, {});
+  // Build the page element.
+  // Client references ('use client' pages) must NOT be called as functions —
+  // they are proxy objects that throw when invoked. They must go through
+  // createElement only, which serializes them as client references in the
+  // RSC Flight stream. OTEL tracing is skipped for client components.
+  // See TIM-627 for the original bug.
+  let element: React.ReactElement;
+  if (isClientReference(PageComponent)) {
+    element = h(PageComponent, {});
+  } else {
+    const TracedPage = async (props: Record<string, unknown>) => {
+      return withSpan(
+        'timber.page',
+        { 'timber.route': match.segments[match.segments.length - 1]?.urlPath ?? '/' },
+        () => (PageComponent as (props: Record<string, unknown>) => unknown)(props)
+      );
+    };
+    element = h(TracedPage, {});
+  }
 
   // Build a lookup of layout components by segment for O(1) access.
   const layoutBySegment = new Map(
@@ -429,22 +466,33 @@ export async function buildRouteElement(
           ? `${segment.urlPath === '/' ? '' : segment.urlPath}/${segment.segmentName}`
           : segment.urlPath;
 
-      // Wrap the layout component in an OTEL span
-      const layoutComponentRef = layoutComponent;
-      const TracedLayout = async (props: Record<string, unknown>) => {
-        return withSpan('timber.layout', { 'timber.segment': segmentId }, () =>
-          (layoutComponentRef as (props: Record<string, unknown>) => unknown)(props)
-        );
-      };
+      // Build the layout element.
+      // Same client reference guard as pages — client layouts must not be
+      // called as functions. OTEL tracing is skipped for client components.
+      let layoutElement: React.ReactElement;
+      if (isClientReference(layoutComponent)) {
+        layoutElement = h(layoutComponent, {
+          ...slotProps,
+          children: element,
+        });
+      } else {
+        const layoutComponentRef = layoutComponent;
+        const TracedLayout = async (props: Record<string, unknown>) => {
+          return withSpan('timber.layout', { 'timber.segment': segmentId }, () =>
+            (layoutComponentRef as (props: Record<string, unknown>) => unknown)(props)
+          );
+        };
+        layoutElement = h(TracedLayout, {
+          ...slotProps,
+          children: element,
+        });
+      }
 
       element = h(SegmentProvider, {
         segments: segmentPath,
         segmentId,
         parallelRouteKeys,
-        children: h(TracedLayout, {
-          ...slotProps,
-          children: element,
-        }),
+        children: layoutElement,
       });
     }
   }

package/src/server/slot-resolver.ts

@@ -20,6 +20,7 @@ import { TimberErrorBoundary } from '../client/error-boundary.js';
 import SlotErrorFallback from '../client/slot-error-fallback.js';
 import { SlotAccessGate } from './access-gate.js';
 import { wrapSegmentWithErrorBoundaries } from './error-boundary-wrapper.js';
+import { isClientReference } from './route-element-builder.js';
 import { loadModule } from './safe-load.js';
 import type { InterceptionContext, RouteMatch } from './pipeline.js';
 import { DenySignal, RedirectSignal } from './primitives.js';
@@ -177,44 +178,45 @@ export async function resolveSlotElement(
       // §"Slot Access Failure = Graceful Degradation"
       const denyFallback = await renderDefaultFallback(slotNode, h);
 
-      // Wrap the slot page to catch ALL errors at the component level.
-      // This prevents errors from leaving unresolved Flight rows in the
-      // RSC stream — when a slot component throws and the error propagates
-      // to React's Flight renderer, it may not emit a resolution row for
-      // the slot's lazy reference. The client's createFromReadableStream
-      // then throws "Connection closed" when the stream ends with pending
-      // references. By catching all errors here and returning a fallback,
-      // React sees a resolved component and emits a proper Flight row.
+      // Build the slot page element.
+      // Client references ('use client' pages) must NOT be called as functions —
+      // they are proxy objects that throw when invoked. For client references,
+      // use createElement directly. Error catching is unnecessary because client
+      // references are serialized as references in the RSC Flight stream — they
+      // don't execute on the server. See TIM-627.
       //
-      // DenySignal (from notFound() or deny()) returns the deny fallback.
-      // All other errors return the deny fallback or null — the slot
-      // gracefully degrades rather than breaking the entire page.
-      // See TIM-524.
-      const SafeSlotPage = async (props: Record<string, unknown>) => {
-        try {
-          return await (SlotPage as (props: Record<string, unknown>) => unknown)(props);
-        } catch (error) {
-          // RedirectSignal must propagate — the pipeline handles redirects
-          // at the top level. Swallowing it here would silently return
-          // fallback content instead of redirecting. See TIM-554.
-          if (error instanceof RedirectSignal) {
-            throw error;
-          }
-          if (error instanceof DenySignal) {
+      // For server components, wrap in SafeSlotPage to catch ALL errors at the
+      // component level. This prevents errors from leaving unresolved Flight
+      // rows in the RSC stream — see TIM-524 for details.
+      let element: React.ReactElement;
+      if (isClientReference(SlotPage)) {
+        element = h(SlotPage, {});
+      } else {
+        const SafeSlotPage = async (props: Record<string, unknown>) => {
+          try {
+            return await (SlotPage as (props: Record<string, unknown>) => unknown)(props);
+          } catch (error) {
+            // RedirectSignal must propagate — the pipeline handles redirects
+            // at the top level. Swallowing it here would silently return
+            // fallback content instead of redirecting. See TIM-554.
+            if (error instanceof RedirectSignal) {
+              throw error;
+            }
+            if (error instanceof DenySignal) {
+              return denyFallback;
+            }
+            // Log the error but don't re-throw — returning fallback ensures
+            // the Flight row is resolved and the page hydrates correctly.
+            logRenderError({
+              method: '',
+              path: '',
+              error,
+            });
             return denyFallback;
           }
-          // Log the error but don't re-throw — returning fallback ensures
-          // the Flight row is resolved and the page hydrates correctly.
-          logRenderError({
-            method: '',
-            path: '',
-            error,
-          });
-          return denyFallback;
-        }
-      };
-
-      let element: React.ReactElement = h(SafeSlotPage, {});
+        };
+        element = h(SafeSlotPage, {});
+      }
 
       // Wrap with error boundaries and layouts from intermediate slot segments
       // (everything between slot root and leaf). Process innermost-first, same

package/src/server/ssr-entry.ts

@@ -227,7 +227,7 @@ export async function handleSsr(
       const _decodeEnd = performance.now();
 
       // Wrap with the same component tree structure as the client hydration
-      // tree (TransitionRoot → PendingNavigationProvider → TopLoader →
+      // tree (NavigationRoot → PendingNavigationProvider → TopLoader →
       // TimberNuqsAdapter → NuqsAdapterProvider → NavigationProvider).
       // This ensures useId() produces matching IDs on both sides, preventing
       // hydration mismatches in libraries like Radix UI. See TIM-532.

package/src/server/ssr-wrappers.tsx

@@ -8,7 +8,7 @@
  * Radix UI that rely on useId() internally.
  *
  * The client tree (browser-entry.ts) wraps the RSC element with:
- *   TransitionRoot → PendingNavigationProvider → Fragment(TopLoader, ...) →
+ *   NavigationRoot → PendingNavigationProvider → Fragment(TopLoader, ...) →
  *     TimberNuqsAdapter → NuqsAdapterProvider → NavigationProvider → element
  *
  * The SSR tree must produce the same component boundaries. These wrappers
@@ -23,15 +23,15 @@ import { createElement, Fragment, type ReactNode } from 'react';
 import { withNuqsSsrAdapter } from './nuqs-ssr-provider.js';
 
 /**
- * SSR equivalent of TransitionRoot.
+ * SSR equivalent of NavigationRoot.
  *
- * On the client, TransitionRoot uses useState + useTransition and renders:
+ * On the client, NavigationRoot uses useState and standalone startTransition, rendering:
  *   PendingNavigationProvider(Fragment(TopLoader, element))
  *
  * This SSR version matches the component boundary depth without client
  * hooks. It renders SsrPendingProvider → Fragment(SsrTopLoader, children).
  */
-function SsrTransitionRoot({
+function SsrNavigationRoot({
   children,
   hasTopLoader,
 }: {
@@ -97,7 +97,7 @@ function SsrNuqsWrapper({
  * on both sides.
  *
  * Client tree (browser-entry.ts):
- *   TransitionRoot
+ *   NavigationRoot
  *     → PendingNavigationProvider
  *       → Fragment(TopLoader, element)
  *         → TimberNuqsAdapter
@@ -106,7 +106,7 @@ function SsrNuqsWrapper({
  *               → [RSC element]
  *
  * SSR tree (this function):
- *   SsrTransitionRoot
+ *   SsrNavigationRoot
  *     → SsrPendingProvider
  *       → Fragment(SsrTopLoader, element)
  *         → SsrNuqsWrapper
@@ -125,8 +125,8 @@ export function wrapSsrElement(
 ): ReactNode {
   // Build inside-out to match the client's createElement chain:
   //   NavigationProvider(TimberNuqsAdapter(element))
-  //   → passed as initial to TransitionRoot
-  //   → TransitionRoot renders PendingNavigationProvider(Fragment(TopLoader, initial))
+  //   → passed as initial to NavigationRoot
+  //   → NavigationRoot renders PendingNavigationProvider(Fragment(TopLoader, initial))
 
   // 1. Innermost: NavigationProvider equivalent
   const withNav = createElement(SsrNavigationProvider, null, element);
@@ -134,6 +134,6 @@ export function wrapSsrElement(
   // 2. TimberNuqsAdapter equivalent (wraps withNuqsSsrAdapter for the actual nuqs provider)
   const withNuqs = createElement(SsrNuqsWrapper, { searchParams, children: withNav });
 
-  // 3. Outermost: TransitionRoot equivalent (PendingNavigationProvider + TopLoader)
-  return createElement(SsrTransitionRoot, { hasTopLoader, children: withNuqs });
+  // 3. Outermost: NavigationRoot equivalent (PendingNavigationProvider + TopLoader)
+  return createElement(SsrNavigationRoot, { hasTopLoader, children: withNuqs });
 }

package/dist/client/transition-root.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"transition-root.d.ts","sourceRoot":"","sources":["../../src/client/transition-root.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAoD,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAEzF,OAAO,EAAa,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAsBlE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,EAC7B,OAAO,EACP,eAAe,GAChB,EAAE;IACD,OAAO,EAAE,SAAS,CAAC;IACnB,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC,GAAG,SAAS,CA2DZ;AAID;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAIzD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,GAChC,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,cAAc,EAAE,CAAC,OAAO,EAAE,SAAS,KAAK,IAAI,GAAG,IAAI,CAc5F"}

package/src/client/transition-root.tsx

@@ -1,205 +0,0 @@
-/**
- * TransitionRoot — Wrapper component for transition-based rendering.
- *
- * Solves the "new boundary has no old content" problem for client-side
- * navigation. When React renders a completely new Suspense boundary via
- * root.render(), it shows the fallback immediately — root.render() is
- * always an urgent update regardless of startTransition.
- *
- * TransitionRoot holds the current element in React state. Navigation
- * updates call startTransition(() => setState(newElement)), which IS
- * a transition update. React keeps the old committed tree visible while
- * any new Suspense boundaries in the transition resolve.
- *
- * Also manages `pendingUrl` as React state with an urgent/transition split:
- * - Navigation START: `setPendingUrl(url)` is an urgent update — React
- *   commits it before the next paint, showing the spinner immediately.
- * - Navigation END: `setPendingUrl(null)` is inside `startTransition`
- *   alongside `setElement(newTree)` — both commit atomically, so the
- *   spinner disappears in the same frame as the new content appears.
- *
- * See design/05-streaming.md §"deferSuspenseFor"
- * See design/19-client-navigation.md §"NavigationContext"
- */
-
-import { useState, useTransition, createElement, Fragment, type ReactNode } from 'react';
-import { PendingNavigationProvider } from './navigation-context.js';
-import { TopLoader, type TopLoaderConfig } from './top-loader.js';
-import { getCurrentNavId, resetLinkPending } from './link-pending-store.js';
-
-// ─── Module-level functions ──────────────────────────────────────
-
-/**
- * Module-level reference to the state setter wrapped in startTransition.
- * Used for non-navigation renders (applyRevalidation, popstate replay).
- */
-let _transitionRender: ((element: ReactNode) => void) | null = null;
-
-/**
- * Module-level reference to the navigation transition function.
- * Wraps a full navigation (fetch + render) in a single startTransition
- * with useOptimistic for the pending URL.
- */
-let _navigateTransition:
-  | ((pendingUrl: string, perform: () => Promise<ReactNode>) => Promise<void>)
-  | null = null;
-
-// ─── Component ───────────────────────────────────────────────────
-
-/**
- * Root wrapper component that enables transition-based rendering.
- *
- * Renders PendingNavigationProvider around children for the pending URL
- * context. The DOM tree matches the server-rendered HTML during hydration
- * (the provider renders no extra DOM elements).
- *
- * Usage in browser-entry.ts:
- *   const rootEl = createElement(TransitionRoot, { initial: wrapped });
- *   reactRoot = hydrateRoot(document, rootEl);
- *
- * Subsequent navigations:
- *   navigateTransition(url, async () => { fetch; return wrappedElement; });
- *
- * Non-navigation renders:
- *   transitionRender(newWrappedElement);
- */
-export function TransitionRoot({
-  initial,
-  topLoaderConfig,
-}: {
-  initial: ReactNode;
-  topLoaderConfig?: TopLoaderConfig;
-}): ReactNode {
-  const [element, setElement] = useState<ReactNode>(initial);
-  const [pendingUrl, setPendingUrl] = useState<string | null>(null);
-  const [, startTransition] = useTransition();
-
-  // Non-navigation render (revalidation, popstate cached replay).
-  _transitionRender = (newElement: ReactNode) => {
-    startTransition(() => {
-      setElement(newElement);
-    });
-  };
-
-  // Full navigation transition.
-  // setPendingUrl(url) is an URGENT update — React commits it before the next
-  // paint, so the pending spinner appears immediately when navigation starts.
-  // Inside startTransition: the async fetch + setElement + setPendingUrl(null)
-  // are deferred. When the transition commits, the new tree and pendingUrl=null
-  // both apply in the same React commit — making the pending→active transition
-  // atomic (no frame where pending is false but the old tree is still visible).
-  _navigateTransition = (url: string, perform: () => Promise<ReactNode>) => {
-    // Urgent: show pending state immediately (for TopLoader / useNavigationPending)
-    setPendingUrl(url);
-
-    return new Promise<void>((resolve, reject) => {
-      startTransition(async () => {
-        // Capture the current nav ID before async work begins.
-        // Used to guard against stale clears when a newer navigation
-        // supersedes this one.
-        const navId = getCurrentNavId();
-        try {
-          const newElement = await perform();
-          setElement(newElement);
-          // Clear pending inside the transition — commits atomically with new tree
-          setPendingUrl(null);
-          // Reset per-link pending state. The navId guard ensures a stale
-          // transition (T1) doesn't clear a newer navigation's (T2) link.
-          // The setter call is a transition update — batched with setElement
-          // and setPendingUrl, so pending clears atomically with new tree.
-          // See design/19-client-navigation.md §"Per-Link Pending State"
-          resetLinkPending(navId);
-          resolve();
-        } catch (err) {
-          // Clear pending on error too
-          setPendingUrl(null);
-          resetLinkPending(navId);
-          reject(err);
-        }
-      });
-    });
-  };
-
-  // Inject TopLoader alongside the element tree inside PendingNavigationProvider.
-  // The TopLoader reads pendingUrl from context to show/hide the progress bar.
-  // It is rendered only when not explicitly disabled via config.
-  const showTopLoader = topLoaderConfig?.enabled !== false;
-  const children = showTopLoader
-    ? createElement(Fragment, null, createElement(TopLoader, { config: topLoaderConfig }), element)
-    : element;
-  return createElement(PendingNavigationProvider, { value: pendingUrl }, children);
-}
-
-// ─── Public API ──────────────────────────────────────────────────
-
-/**
- * Trigger a transition render for non-navigation updates.
- * React keeps the old committed tree visible while any new Suspense
- * boundaries in the update resolve.
- *
- * Used for: applyRevalidation, popstate replay with cached payload.
- */
-export function transitionRender(element: ReactNode): void {
-  if (_transitionRender) {
-    _transitionRender(element);
-  }
-}
-
-/**
- * Run a full navigation inside a React transition with optimistic pending URL.
- *
- * The `perform` callback runs inside `startTransition` — it should fetch the
- * RSC payload, update router state, and return the wrapped React element.
- * The pending URL shows immediately (useOptimistic urgent update) and reverts
- * to null when the transition commits (atomic with the new tree).
- *
- * Returns a Promise that resolves when the async work completes (note: the
- * React transition may not have committed yet, but all state updates are done).
- *
- * Used for: navigate(), refresh(), popstate with fetch.
- */
-export function navigateTransition(
-  pendingUrl: string,
-  perform: () => Promise<ReactNode>
-): Promise<void> {
-  if (_navigateTransition) {
-    return _navigateTransition(pendingUrl, perform);
-  }
-  // Fallback: no TransitionRoot mounted (shouldn't happen in production)
-  return perform().then(() => {});
-}
-
-/**
- * Check if the TransitionRoot is mounted and ready for renders.
- * Used by browser-entry.ts to guard against renders before hydration.
- */
-export function isTransitionRootReady(): boolean {
-  return _transitionRender !== null;
-}
-
-/**
- * Install one-shot deferred callbacks for the no-RSC bootstrap path (TIM-600).
- *
- * When there's no RSC payload, we can't create a React root immediately —
- * `createRoot(document).render(...)` would blank the SSR HTML. Instead,
- * this sets up `_transitionRender` and `_navigateTransition` so that the
- * first client navigation triggers root creation via `createAndMount`.
- *
- * After `createAndMount` runs, TransitionRoot renders and overwrites these
- * callbacks with its real `startTransition`-based implementations.
- */
-export function installDeferredNavigation(createAndMount: (initial: ReactNode) => void): void {
-  let mounted = false;
-  const mountOnce = (element: ReactNode) => {
-    if (mounted) return;
-    mounted = true;
-    createAndMount(element);
-  };
-  _transitionRender = (element: ReactNode) => {
-    mountOnce(element);
-  };
-  _navigateTransition = async (_pendingUrl: string, perform: () => Promise<ReactNode>) => {
-    const element = await perform();
-    mountOnce(element);
-  };
-}