@timber-js/app 0.2.0-alpha.67 → 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 ───────────────────────────────────────────────────────
@@ -27,6 +28,19 @@ export interface NavigationOptions {
   scroll?: boolean;
   /** Use replaceState instead of pushState (replaces current history entry) */
   replace?: boolean;
+  /**
+   * @internal AbortSignal from the Navigation API's NavigateEvent.
+   * When provided, the signal is linked to the router's per-navigation
+   * AbortController so in-flight RSC fetches are cancelled when a new
+   * navigation starts.
+   */
+  _signal?: AbortSignal;
+  /**
+   * @internal Skip pushState/replaceState — the Navigation API has already
+   * updated the URL via event.intercept(). Used for external navigations
+   * intercepted by the navigate event handler.
+   */
+  _skipHistory?: boolean;
 }
 
 /**
@@ -77,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().
    *
@@ -89,6 +103,42 @@ export interface RouterDeps {
       wrapPayload: (payload: unknown, navState: NavigationState) => unknown
     ) => Promise<unknown>
   ) => Promise<void>;
+
+  /**
+   * Whether the Navigation API is active and handling traversals.
+   * When true, the popstate handler is a no-op — the Navigation API's
+   * navigate event covers back/forward button presses.
+   */
+  navigationApiActive?: boolean;
+
+  /**
+   * Called around pushState/replaceState to set a flag that prevents
+   * the Navigation API's navigate listener from double-handling
+   * router-initiated navigations.
+   */
+  setRouterNavigating?: (value: boolean) => void;
+
+  /**
+   * Save scroll position via the Navigation API's per-entry state.
+   * When provided, used instead of history.replaceState for scroll storage.
+   */
+  saveNavigationEntryScroll?: (scrollY: number) => void;
+
+  /**
+   * Signal that a router-initiated navigation has completed. Resolves the
+   * deferred promise that ties the browser's native loading state to the
+   * navigation lifecycle. Called in the finally block of navigate/refresh,
+   * aligned with when the TopLoader's pendingUrl clears.
+   */
+  completeRouterNavigation?: () => void;
+
+  /**
+   * Initiate a navigation via the Navigation API (`navigation.navigate()`).
+   * Fires the navigate event BEFORE committing the URL, allowing Chrome
+   * to show its native loading indicator. Falls back to pushState when
+   * unavailable.
+   */
+  navigationNavigate?: (url: string, replace: boolean) => void;
 }
 
 export interface RouterInstance {
@@ -97,7 +147,7 @@ export interface RouterInstance {
   /** Full re-render of the current URL — no state tree sent */
   refresh(): Promise<void>;
   /** Handle a popstate event (back/forward button). scrollY is read from history.state. */
-  handlePopState(url: string, scrollY?: number): Promise<void>;
+  handlePopState(url: string, scrollY?: number, externalSignal?: AbortSignal): Promise<void>;
   /** Whether a navigation is currently in flight */
   isPending(): boolean;
   /** The URL currently being navigated to, or null if idle */
@@ -167,6 +217,36 @@ export function createRouter(deps: RouterDeps): RouterInstance {
   let routerPhase: RouterPhase = { phase: 'idle' };
   const pendingListeners = new Set<(pending: boolean) => void>();
 
+  // AbortController for the current in-flight navigation.
+  // When a new navigation starts, the previous controller is aborted,
+  // cancelling any in-progress RSC fetch. This provides automatic
+  // cancellation of stale fetches regardless of Navigation API support.
+  let currentNavAbort: AbortController | null = null;
+
+  /**
+   * Create a new AbortController for a navigation, aborting any
+   * previous in-flight navigation. Optionally links to an external
+   * signal (e.g., from the Navigation API's NavigateEvent.signal).
+   */
+  function createNavAbort(externalSignal?: AbortSignal): AbortController {
+    // Abort previous navigation's fetch
+    currentNavAbort?.abort();
+    const controller = new AbortController();
+    currentNavAbort = controller;
+
+    // If an external signal is provided (e.g., Navigation API),
+    // forward its abort to our controller.
+    if (externalSignal) {
+      if (externalSignal.aborted) {
+        controller.abort();
+      } else {
+        externalSignal.addEventListener('abort', () => controller.abort(), { once: true });
+      }
+    }
+
+    return controller;
+  }
+
   function setPending(value: boolean, url?: string): void {
     const next: RouterPhase =
       value && url ? { phase: 'navigating', targetUrl: url } : { phase: 'idle' };
@@ -183,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);
     }
@@ -326,7 +406,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
    */
   async function performNavigationFetch(
     url: string,
-    options: { replace: boolean }
+    options: { replace: boolean; signal?: AbortSignal; skipHistory?: boolean }
   ): Promise<FetchResult & { navState: NavigationState }> {
     // Check prefetch cache first. PrefetchResult has optional segmentInfo/params
     // fields — normalize to null for FetchResult compatibility.
@@ -349,14 +429,21 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       const currentUrl = rawCurrentUrl.startsWith('http')
         ? new URL(rawCurrentUrl).pathname
         : new URL(rawCurrentUrl, 'http://localhost').pathname;
-      result = await fetchRscPayload(url, deps, stateTree, currentUrl);
+      result = await fetchRscPayload(url, deps, stateTree, currentUrl, options.signal);
     }
 
-    // Update the browser history — replace mode overwrites the current entry
-    if (options.replace) {
-      deps.replaceState({ timber: true, scrollY: 0 }, '', url);
-    } else {
-      deps.pushState({ timber: true, scrollY: 0 }, '', url);
+    // Update the browser history — skip when the Navigation API has already
+    // updated the URL via event.intercept() (external navigations).
+    if (!options.skipHistory) {
+      // Set the router-navigating flag so the Navigation API's navigate
+      // listener doesn't double-intercept this pushState/replaceState.
+      deps.setRouterNavigating?.(true);
+      if (options.replace) {
+        deps.replaceState({ timber: true, scrollY: 0 }, '', url);
+      } else {
+        deps.pushState({ timber: true, scrollY: 0 }, '', url);
+      }
+      deps.setRouterNavigating?.(false);
     }
 
     // NOTE: History push is deferred — the merged payload (after segment
@@ -376,20 +463,48 @@ export function createRouter(deps: RouterDeps): RouterInstance {
   async function navigate(url: string, options: NavigationOptions = {}): Promise<void> {
     const scroll = options.scroll !== false;
     const replace = options.replace === true;
+    const externalSignal = options._signal as AbortSignal | undefined;
+    const skipHistory = options._skipHistory === true;
+
+    // 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();
 
-    // Save the departing page's scroll position in history.state before
-    // pushing a new entry. This ensures back/forward navigation can restore
-    // the correct scroll position from the browser's per-entry state.
-    deps.replaceState({ timber: true, scrollY: currentScrollY }, '', deps.getCurrentUrl());
+    // Save the departing page's scroll position — use Navigation API entry
+    // state when available, otherwise fall back to history.state.
+    if (deps.saveNavigationEntryScroll) {
+      deps.saveNavigationEntryScroll(currentScrollY);
+    } else {
+      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 {
       const headElements = await renderViaTransition(url, () =>
-        performNavigationFetch(url, { replace })
+        performNavigationFetch(url, {
+          replace,
+          signal: navAbort.signal,
+          skipHistory: effectiveSkipHistory,
+        })
       );
 
       // Update document.title and <meta> tags with the new page's metadata
@@ -405,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');
@@ -414,15 +532,24 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         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) {
         setPending(false);
+        deps.completeRouterNavigation?.();
         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;
       }
@@ -430,19 +557,38 @@ 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.
+      deps.completeRouterNavigation?.();
     }
   }
 
   async function refresh(): Promise<void> {
     const currentUrl = deps.getCurrentUrl();
+    const navAbort = createNavAbort();
 
     setPending(true, currentUrl);
 
     try {
       const headElements = await renderViaTransition(currentUrl, async () => {
         // No state tree sent — server renders the complete RSC payload
-        const result = await fetchRscPayload(currentUrl, deps);
+        const result = await fetchRscPayload(
+          currentUrl,
+          deps,
+          undefined,
+          undefined,
+          navAbort.signal
+        );
         // History push handled by renderViaTransition (stores merged payload)
         updateSegmentCache(result.segmentInfo);
         const navState = updateNavigationState(result.params, currentUrl);
@@ -450,12 +596,25 @@ 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?.();
     }
   }
 
-  async function handlePopState(url: string, scrollY: number = 0): Promise<void> {
+  async function handlePopState(
+    url: string,
+    scrollY: number = 0,
+    externalSignal?: AbortSignal
+  ): Promise<void> {
     // Scroll position is read from history.state by the caller (browser-entry.ts)
     // and passed in. This is more reliable than tracking scroll per-URL in memory
     // because the browser maintains per-entry state even with duplicate URLs.
@@ -472,13 +631,14 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // 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 {
         const headElements = await renderViaTransition(url, async () => {
           const stateTree = segmentCache.serializeStateTree(
             segmentElementCache.getMergeablePaths()
           );
-          const result = await fetchRscPayload(url, deps, stateTree);
+          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)
@@ -487,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/rsc-fetch.ts

@@ -249,7 +249,8 @@ export async function fetchRscPayload(
   url: string,
   deps: RouterDeps,
   stateTree?: { segments: string[] },
-  currentUrl?: string
+  currentUrl?: string,
+  signal?: AbortSignal
 ): Promise<FetchResult> {
   const rscUrl = appendRscParam(url);
   const headers = buildRscHeaders(stateTree, currentUrl);
@@ -260,7 +261,7 @@ export async function fetchRscPayload(
     //
     // Intercept the response to read X-Timber-Head before createFromFetch
     // consumes the body. Reading headers does NOT consume the body stream.
-    const fetchPromise = deps.fetch(rscUrl, { headers, redirect: 'manual' });
+    const fetchPromise = deps.fetch(rscUrl, { headers, redirect: 'manual', signal });
     let headElements: HeadElement[] | null = null;
     let segmentInfo: SegmentInfo[] | null = null;
     let params: Record<string, string | string[]> | null = null;
@@ -303,7 +304,7 @@ export async function fetchRscPayload(
     return { payload, headElements, segmentInfo, params, skippedSegments };
   }
   // Test/fallback path: return raw text
-  const response = await deps.fetch(rscUrl, { headers, redirect: 'manual' });
+  const response = await deps.fetch(rscUrl, { headers, redirect: 'manual', signal });
   // Check for redirect in test path too
   if (response.status >= 300 && response.status < 400) {
     const location = response.headers.get('Location');

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
@@ -28,7 +28,7 @@
 'use client';
 
 import { useState, createElement } from 'react';
-import { usePendingNavigationUrl } from './navigation-context.js';
+import { usePendingNavigationUrl, hasNativeNavigationTransition } from './navigation-context.js';
 
 // ─── Types ───────────────────────────────────────────────────────
 
@@ -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:
@@ -112,7 +112,15 @@ function ensureKeyframes(): void {
  */
 export function TopLoader({ config }: { config?: TopLoaderConfig }): React.ReactElement | null {
   const pendingUrl = usePendingNavigationUrl();
-  const isPending = pendingUrl !== null;
+  // Navigation is pending when either:
+  // 1. Our React-based pending URL is set (standard path), OR
+  // 2. The Navigation API has an active transition (external navigations
+  //    intercepted by the navigate event that haven't completed yet).
+  // In practice these are almost always in sync — the Navigation API
+  // transition is active while our pendingUrl is set. This check ensures
+  // the top-loader also shows for external navigations caught by the
+  // Navigation API before our React state updates.
+  const isPending = pendingUrl !== null || hasNativeNavigationTransition();
 
   const color = config?.color ?? DEFAULT_COLOR;
   const height = config?.height ?? DEFAULT_HEIGHT;

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.