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

package/dist/server/route-element-builder.d.ts

@@ -18,6 +18,16 @@ import type { RouteMatch } from './pipeline.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
 import { DenySignal, RedirectSignal } from './primitives.js';
 import type { InterceptionContext } from './pipeline.js';
+/**
+ * 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 declare function isClientReference(component: unknown): boolean;
 /**
  * Thrown when a defineSegmentParams codec's parse() fails.
  * The pipeline catches this and responds with 404.

package/dist/server/route-element-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-element-builder.d.ts","sourceRoot":"","sources":["../../src/server/route-element-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAK9D,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAM7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAMzD;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAID,qDAAqD;AACrD,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CACvC;AAED,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAC3C,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,wFAAwF;IACxF,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC;IAC5B,2CAA2C;IAC3C,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,wDAAwD;IACxD,gBAAgB,EAAE,oBAAoB,EAAE,CAAC;IACzC,qCAAqC;IACrC,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,4DAA4D;IAC5D,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;aAE7B,MAAM,EAAE,UAAU,GAAG,cAAc;aACnC,gBAAgB,EAAE,oBAAoB,EAAE;aACxC,QAAQ,EAAE,mBAAmB,EAAE;gBAF/B,MAAM,EAAE,UAAU,GAAG,cAAc,EACnC,gBAAgB,EAAE,oBAAoB,EAAE,EACxC,QAAQ,EAAE,mBAAmB,EAAE;CAIlD;AA8DD;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,YAAY,CAAC,EAAE,mBAAmB,EAClC,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,GACnC,OAAO,CAAC,kBAAkB,CAAC,CA6R7B"}
+{"version":3,"file":"route-element-builder.d.ts","sourceRoot":"","sources":["../../src/server/route-element-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAK9D,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAM7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAezD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,OAAO,GAAG,OAAO,CAM7D;AAID;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAID,qDAAqD;AACrD,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CACvC;AAED,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAC3C,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,wFAAwF;IACxF,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC;IAC5B,2CAA2C;IAC3C,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,wDAAwD;IACxD,gBAAgB,EAAE,oBAAoB,EAAE,CAAC;IACzC,qCAAqC;IACrC,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,4DAA4D;IAC5D,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;aAE7B,MAAM,EAAE,UAAU,GAAG,cAAc;aACnC,gBAAgB,EAAE,oBAAoB,EAAE;aACxC,QAAQ,EAAE,mBAAmB,EAAE;gBAF/B,MAAM,EAAE,UAAU,GAAG,cAAc,EACnC,gBAAgB,EAAE,oBAAoB,EAAE,EACxC,QAAQ,EAAE,mBAAmB,EAAE;CAIlD;AA8DD;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,YAAY,CAAC,EAAE,mBAAmB,EAClC,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,GACnC,OAAO,CAAC,kBAAkB,CAAC,CAiT7B"}

package/dist/server/slot-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"slot-resolver.d.ts","sourceRoot":"","sources":["../../src/server/slot-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAOH,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGrE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,KAAK,eAAe,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,KAAK,CAAC,YAAY,CAAC;AAmHlE;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,mBAAmB,EAC7B,KAAK,EAAE,UAAU,EACjB,CAAC,EAAE,eAAe,EAClB,YAAY,CAAC,EAAE,mBAAmB,GACjC,OAAO,CAAC,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,CA+FpC"}
+{"version":3,"file":"slot-resolver.d.ts","sourceRoot":"","sources":["../../src/server/slot-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAQH,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGrE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,KAAK,eAAe,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,KAAK,CAAC,YAAY,CAAC;AAmHlE;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,mBAAmB,EAC7B,KAAK,EAAE,UAAU,EACjB,CAAC,EAAE,eAAe,EAClB,YAAY,CAAC,EAAE,mBAAmB,GACjC,OAAO,CAAC,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,CAgGpC"}

package/dist/server/ssr-wrappers.d.ts

@@ -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
@@ -25,7 +25,7 @@ import { type ReactNode } from 'react';
  * on both sides.
  *
  * Client tree (browser-entry.ts):
- *   TransitionRoot
+ *   NavigationRoot
  *     → PendingNavigationProvider
  *       → Fragment(TopLoader, element)
  *         → TimberNuqsAdapter
@@ -34,7 +34,7 @@ import { type ReactNode } from 'react';
  *               → [RSC element]
  *
  * SSR tree (this function):
- *   SsrTransitionRoot
+ *   SsrNavigationRoot
  *     → SsrPendingProvider
  *       → Fragment(SsrTopLoader, element)
  *         → SsrNuqsWrapper

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.68",
+  "version": "0.2.0-alpha.69",
   "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",

package/src/client/browser-entry.ts

@@ -59,11 +59,12 @@ import { setupServerLogReplay, setupClientErrorForwarding } from './browser-dev.
 // browser-links.ts removed — Link components own their click/hover handlers directly.
 // See LOCAL-340.
 import {
-  TransitionRoot,
+  NavigationRoot,
   transitionRender,
   navigateTransition,
   installDeferredNavigation,
-} from './transition-root.js';
+  setHardNavigating,
+} from './navigation-root.js';
 import {
   isStaleClientReference,
   isChunkLoadError,
@@ -157,7 +158,10 @@ setServerCallback(async (id: string, args: unknown[]) => {
       const router = getRouter();
       void router.navigate(wrapper._redirect);
     } catch {
-      // Router not yet initialized — fall back to full navigation
+      // Router not yet initialized — fall back to full navigation.
+      // Set hard-navigating flag to prevent Navigation API interception
+      // and React from rendering during page teardown. See TIM-626.
+      setHardNavigating(true);
       window.location.href = wrapper._redirect;
     }
     return undefined;
@@ -413,10 +417,10 @@ function bootstrap(runtimeConfig: typeof config): void {
     // Hydrate on document — the root layout renders the full <html> tree,
     // so React owns the entire document from the root.
     // Wrap with NavigationProvider (for atomic useParams/usePathname),
-    // TimberNuqsAdapter (for nuqs context), and TransitionRoot (for
+    // TimberNuqsAdapter (for nuqs context), and NavigationRoot (for
     // transition-based rendering during client navigation).
     //
-    // TransitionRoot holds the element in React state and updates via
+    // NavigationRoot holds the element in React state and updates via
     // startTransition, so React keeps old UI visible while new Suspense
     // boundaries resolve during navigation. See design/05-streaming.md.
     const navState = getNavigationState();
@@ -426,7 +430,7 @@ function bootstrap(runtimeConfig: typeof config): void {
       element as React.ReactNode
     );
     const wrapped = createElement(TimberNuqsAdapter, null, withNav);
-    const rootElement = createElement(TransitionRoot, {
+    const rootElement = createElement(NavigationRoot, {
       initial: wrapped,
       topLoaderConfig: _config.topLoader,
     });
@@ -470,13 +474,13 @@ function bootstrap(runtimeConfig: typeof config): void {
     // Instead, installDeferredNavigation sets up one-shot callbacks so the
     // first navigateTransition/transitionRender call creates the root on
     // `document` with the navigated content. After that initial render,
-    // TransitionRoot's real startTransition-based callbacks take over.
+    // NavigationRoot's real startTransition-based callbacks take over.
     //
     // This also fixes TIM-580 (navigation from SSR-only pages) because the
-    // deferred callbacks ensure TransitionRoot is mounted before the first
+    // deferred callbacks ensure NavigationRoot is mounted before the first
     // navigation completes.
     installDeferredNavigation((initial) => {
-      const rootElement = createElement(TransitionRoot, {
+      const rootElement = createElement(NavigationRoot, {
         initial,
         topLoaderConfig: _config.topLoader,
       });
@@ -489,7 +493,7 @@ function bootstrap(runtimeConfig: typeof config): void {
   // Extracted into a function so both the hydration and createRoot paths
   // can call it. Must run before hydrateRoot so useRouter() works during
   // the initial render. renderRoot uses transitionRender which is set
-  // by the TransitionRoot component during hydration.
+  // by the NavigationRoot component during hydration.
   function initRouter(): void {
     // Feature-detect Navigation API. When available, the navigate event
     // replaces popstate for back/forward and catches external navigations.
@@ -543,7 +547,7 @@ function bootstrap(runtimeConfig: typeof config): void {
         }
       },
 
-      // Render decoded RSC tree via TransitionRoot's state-based mechanism.
+      // Render decoded RSC tree via NavigationRoot's state-based mechanism.
       // Used for non-navigation renders (popstate cached replay, applyRevalidation).
       // Wraps with NavigationProvider + TimberNuqsAdapter.
       //

package/src/client/link-pending-store.ts

@@ -14,8 +14,8 @@
  * 1. Link click handler: setLinkForCurrentNavigation(instance) →
  *    resets previous link (urgent), sets new link pending (urgent),
  *    stores setter + increments navId
- * 2. TransitionRoot startTransition: captures navId, does async work
- * 3. TransitionRoot commit: resetLinkPending(capturedNavId) →
+ * 2. NavigationRoot startTransition: captures navId, does async work
+ * 3. NavigationRoot commit: resetLinkPending(capturedNavId) →
  *    calls setter(IDLE) inside the transition (batched, atomic with tree)
  *    Only clears if navId matches (prevents stale T1 from clearing T2's link)
  *
@@ -96,7 +96,7 @@ export function getCurrentNavId(): number {
 
 /**
  * Reset the current link's pending state to IDLE, but only if the navId
- * matches. Called inside TransitionRoot's startTransition after the async
+ * matches. Called inside NavigationRoot's startTransition after the async
  * work completes — the setter call is a transition update, so it commits
  * atomically with the new tree.
  *

package/src/client/link.tsx

@@ -409,7 +409,7 @@ export function Link({
   // setter is invoked during navigation — zero other links re-render.
   //
   // Eager show: click handler calls setLinkStatus(PENDING) directly (urgent).
-  // Atomic clear: TransitionRoot calls resetLinkPending(navId) inside
+  // Atomic clear: NavigationRoot calls resetLinkPending(navId) inside
   // startTransition — batched with the new tree commit.
   //
   // See design/19-client-navigation.md §"Per-Link Pending State"
@@ -482,7 +482,7 @@ export function Link({
         // Only this Link re-renders — all other Links are unaffected.
         setLinkStatus(PENDING_LINK_STATUS);
 
-        // Register this link in the pending store so TransitionRoot can
+        // Register this link in the pending store so NavigationRoot can
         // reset it to IDLE inside startTransition (atomic with new tree).
         // Also resets any previous pending link to IDLE.
         setLinkForCurrentNavigation(linkInstanceRef.current);

package/src/client/navigation-api.ts

@@ -19,6 +19,7 @@
 
 import type { NavigationApi, NavigateEvent } from './navigation-api-types.js';
 import { consumeNavLinkMetadata } from './nav-link-store.js';
+import { isHardNavigating } from './navigation-root.js';
 
 // ─── Feature Detection ───────────────────────────────────────────
 
@@ -152,6 +153,15 @@ export function setupNavigationApi(callbacks: NavigationApiCallbacks): Navigatio
     // Skip non-interceptable navigations (cross-origin, etc.)
     if (!event.canIntercept) return;
 
+    // Hard navigation guard: when the router has triggered a full page
+    // load (500 error, version skew), skip interception entirely so the
+    // browser performs the MPA navigation. Without this guard, setting
+    // window.location.href fires a navigate event that we'd intercept,
+    // running the RSC pipeline again → 500 → window.location.href →
+    // navigate event → infinite loop.
+    // See design/19-client-navigation.md §"Hard Navigation Guard"
+    if (isHardNavigating()) return;
+
     // Skip download requests
     if (event.downloadRequest) return;
 

package/src/client/navigation-context.ts

@@ -62,7 +62,7 @@ export interface NavigationState {
  * Context instances are stored on globalThis (NOT in module-level
  * variables) because the ESM bundler can duplicate this module across
  * chunks. Module-level variables would create separate instances per
- * chunk — the provider in TransitionRoot (index chunk) would use
+ * chunk — the provider in NavigationRoot (index chunk) would use
  * context A while the consumer in useNavigationPending (shared chunk)
  * reads from context B. globalThis guarantees a single instance.
  *
@@ -168,7 +168,7 @@ export function getNavigationState(): NavigationState {
 
 /**
  * Separate context for the in-flight navigation URL. Provided by
- * TransitionRoot (urgent useState), consumed by useNavigationPending
+ * NavigationRoot (urgent useState), consumed by useNavigationPending
  * and TopLoader. Per-link pending state uses useOptimistic instead
  * (see link-pending-store.ts).
  *

package/src/client/navigation-root.tsx

@@ -0,0 +1,346 @@
+/**
+ * NavigationRoot — 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.
+ *
+ * NavigationRoot 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.
+ *
+ * Hard navigation guard: When a hard navigation is triggered (500 error,
+ * version skew), the component throws an unresolved thenable AFTER all
+ * hooks to suspend forever — preventing React from rendering children
+ * during page teardown. The throw must come after hooks to satisfy
+ * React's rules (same hook count every render) while still preventing
+ * child renders that could hit hook count mismatches in components
+ * whose positions shift during teardown. This pattern is borrowed from
+ * Next.js (app-router.tsx pushRef.mpaNavigation — also after hooks).
+ *
+ * See design/05-streaming.md §"deferSuspenseFor"
+ * See design/19-client-navigation.md §"NavigationContext"
+ */
+
+import { useState, startTransition, 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';
+
+// ─── Navigation Transition Counter ──────────────────────────────
+// Monotonically increasing counter that increments each time
+// navigateTransition() is called. Used to detect stale transitions:
+// if a newer transition started while the current one's perform()
+// was in flight, the current transition is stale and should reject.
+//
+// Separate from the link-pending navId (which only increments on
+// link clicks). This counter covers all navigation types: link clicks,
+// programmatic navigate(), refresh(), and handlePopState().
+//
+// Uses globalThis for singleton guarantee across chunks — same pattern
+// as NavigationContext and the link pending store.
+
+const NAV_TRANSITION_KEY = Symbol.for('__timber_nav_transition_counter');
+
+function getTransitionCounter(): { id: number } {
+  const g = globalThis as Record<symbol, unknown>;
+  if (!g[NAV_TRANSITION_KEY]) {
+    g[NAV_TRANSITION_KEY] = { id: 0 };
+  }
+  return g[NAV_TRANSITION_KEY] as { id: number };
+}
+
+// ─── Hard Navigation Guard ──────────────────────────────────────
+
+/**
+ * Module-level flag indicating a hard (MPA) navigation is in progress.
+ *
+ * When true:
+ * - NavigationRoot throws an unresolved thenable to suspend forever,
+ *   preventing React from rendering children during page teardown
+ *   (avoids "Rendered more hooks" crashes).
+ * - The Navigation API handler skips interception, letting the browser
+ *   perform a full page load (prevents infinite loops where
+ *   window.location.href → navigate event → router.navigate → 500 →
+ *   window.location.href → ...).
+ *
+ * Uses globalThis for singleton guarantee across chunks (same pattern
+ * as NavigationContext). See design/19-client-navigation.md §"Singleton
+ * Guarantee via globalThis".
+ */
+const HARD_NAV_KEY = Symbol.for('__timber_hard_navigating');
+
+function getHardNavStore(): { value: boolean } {
+  const g = globalThis as Record<symbol, unknown>;
+  if (!g[HARD_NAV_KEY]) {
+    g[HARD_NAV_KEY] = { value: false };
+  }
+  return g[HARD_NAV_KEY] as { value: boolean };
+}
+
+/**
+ * Set the hard-navigating flag. Call this BEFORE setting
+ * window.location.href or window.location.reload() to prevent:
+ * 1. React from rendering children during page teardown
+ * 2. Navigation API from intercepting the hard navigation
+ */
+export function setHardNavigating(value: boolean): void {
+  getHardNavStore().value = value;
+}
+
+/**
+ * Check if a hard navigation is in progress.
+ * Used by NavigationRoot (throw unresolvedThenable) and by the
+ * Navigation API handler (skip interception).
+ */
+export function isHardNavigating(): boolean {
+  return getHardNavStore().value;
+}
+
+/**
+ * A thenable that never resolves. When thrown during React render,
+ * it causes the component to suspend forever — React keeps the
+ * old committed tree visible and never attempts to render children.
+ *
+ * This is the same pattern Next.js uses in app-router.tsx for MPA
+ * navigations (pushRef.mpaNavigation → throw unresolvedThenable).
+ */
+// eslint-disable-next-line unicorn/no-thenable -- Intentionally a never-resolving thenable
+// for React's Suspense mechanism. Same pattern as Next.js's unresolvedThenable.
+const unresolvedThenable = { then() {} } as PromiseLike<never>;
+
+// ─── 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 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(NavigationRoot, { initial: wrapped });
+ *   reactRoot = hydrateRoot(document, rootEl);
+ *
+ * Subsequent navigations:
+ *   navigateTransition(url, async () => { fetch; return wrappedElement; });
+ *
+ * Non-navigation renders:
+ *   transitionRender(newWrappedElement);
+ */
+export function NavigationRoot({
+  initial,
+  topLoaderConfig,
+}: {
+  initial: ReactNode;
+  topLoaderConfig?: TopLoaderConfig;
+}): ReactNode {
+  const [element, setElement] = useState<ReactNode>(initial);
+  const [pendingUrl, setPendingUrl] = useState<string | null>(null);
+
+  // NOTE: We use standalone `startTransition` (imported from 'react'),
+  // NOT `useTransition`. The `useTransition` hook's `startTransition`
+  // is tied to a single fiber and tracks one async callback at a time.
+  // When two navigations overlap (click slow-page, then click dashboard),
+  // calling useTransition's startTransition twice with concurrent async
+  // callbacks corrupts React's internal hook tracking — causing
+  // "Rendered more hooks than during the previous render."
+  //
+  // Standalone `startTransition` creates independent transition lanes
+  // for each call, so concurrent navigations don't interfere. We don't
+  // need useTransition's `isPending` — we track pending state via our
+  // own `pendingUrl` useState.
+  //
+  // This matches the Next.js pattern (TIM-625): "No useTransition in
+  // the router at all — only standalone startTransition."
+
+  // 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);
+
+    // Increment the transition counter SYNCHRONOUSLY (before startTransition
+    // schedules the async work). Each call gets a unique transId; the counter
+    // is the same globalThis singleton, so a newer call always has a higher id.
+    const counter = getTransitionCounter();
+    const transId = ++counter.id;
+
+    return new Promise<void>((resolve, reject) => {
+      startTransition(async () => {
+        // Capture the link-level nav ID for resetLinkPending (which has its
+        // own guard). The transition counter (transId) is the primary stale
+        // detection — it covers all navigation types (link clicks, programmatic
+        // navigate, refresh, handlePopState), not just link-initiated ones.
+        const linkNavId = getCurrentNavId();
+        try {
+          const newElement = await perform();
+          // Only commit state if this is still the active navigation.
+          // A superseded transition's updates must be dropped entirely.
+          if (counter.id === transId) {
+            setElement(newElement);
+            setPendingUrl(null);
+            resetLinkPending(linkNavId);
+            resolve();
+          } else {
+            // Stale transition — a newer navigation has superseded this one.
+            // Reject so the caller (navigate/refresh/handlePopState) doesn't
+            // run post-transition side effects (applyHead, scroll, event
+            // dispatch) with stale data. All callers catch AbortError.
+            reject(new DOMException('Navigation superseded', 'AbortError'));
+          }
+        } catch (err) {
+          // Only clear pending if this is still the active navigation.
+          // Stale transitions must not touch state — doing so corrupts
+          // React's transition tracking and causes hook count mismatches.
+          if (counter.id === transId) {
+            setPendingUrl(null);
+            resetLinkPending(linkNavId);
+          }
+          reject(err);
+        }
+      });
+    });
+  };
+
+  // ─── Hard navigation guard ─────────────────────────────────
+  // When a hard navigation is in progress (500 error, version skew),
+  // suspend forever to prevent React from rendering children during
+  // page teardown. This avoids "Rendered more hooks" crashes in
+  // CHILD components whose hook counts may shift during teardown.
+  //
+  // CRITICAL: This throw MUST come AFTER all hooks (the two
+  // useState calls above). React requires the same hooks to run on
+  // every render. If we threw before hooks, React would see 0 hooks
+  // on the re-render vs 2 hooks on the initial render — triggering
+  // the exact "Rendered more hooks" error we're trying to prevent.
+  //
+  // By placing it after hooks but before the return, all hooks
+  // satisfy React's rules, but the thrown thenable prevents any
+  // children from rendering. Same pattern as Next.js app-router.tsx
+  // (pushRef.mpaNavigation — also placed after all hooks).
+  if (isHardNavigating()) {
+    throw unresolvedThenable;
+  }
+
+  // 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 (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 NavigationRoot mounted (shouldn't happen in production)
+  return perform().then(() => {});
+}
+
+/**
+ * Check if the NavigationRoot is mounted and ready for renders.
+ * Used by browser-entry.ts to guard against renders before hydration.
+ */
+export function isNavigationRootReady(): 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, NavigationRoot 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);
+  };
+}