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

package/src/client/browser-entry.ts

@@ -28,7 +28,7 @@ import {
   createFromFetch,
   setServerCallback,
   encodeReply,
-} from '#/rsc-runtime/browser.js';
+} from '../rsc-runtime/browser.js';
 // Shared-state modules MUST be imported from @timber-js/app/client (the public
 // barrel) so they resolve to the same module instances as user code. In Vite dev,
 // user code imports @timber-js/app/client from dist/ via package.json exports.
@@ -47,12 +47,24 @@ import {
   NavigationProvider,
   getNavigationState,
   setNavigationState,
+  type NavigationState,
 } from './navigation-context.js';
 import { setupServerLogReplay, setupClientErrorForwarding } from './browser-dev.js';
 // browser-links.ts removed — Link components own their click/hover handlers directly.
 // See LOCAL-340.
 import { TransitionRoot, transitionRender, navigateTransition } from './transition-root.js';
-import { isStaleClientReference, triggerStaleReload, clearStaleReloadFlag } from './stale-reload.js';
+import {
+  isStaleClientReference,
+  isChunkLoadError,
+  triggerStaleReload,
+  clearStaleReloadFlag,
+} from './stale-reload.js';
+import {
+  setClientDeploymentId,
+  getClientDeploymentId,
+  DEPLOYMENT_ID_HEADER,
+  RELOAD_HEADER,
+} from './rsc-fetch.js';
 
 // ─── Server Action Dispatch ──────────────────────────────────────
 
@@ -81,14 +93,28 @@ setServerCallback(async (id: string, args: unknown[]) => {
   let hasRedirect = false;
   let headElementsJson: string | null = null;
 
+  // Build action request headers. Include deployment ID for version
+  // skew detection (TIM-446) — the server rejects stale actions gracefully.
+  const actionHeaders: Record<string, string> = {
+    'Accept': 'text/x-component',
+    'x-rsc-action': id,
+  };
+  const actionDeploymentId = getClientDeploymentId();
+  if (actionDeploymentId) {
+    actionHeaders[DEPLOYMENT_ID_HEADER] = actionDeploymentId;
+  }
+
   const response = fetch(window.location.href, {
     method: 'POST',
-    headers: {
-      'Accept': 'text/x-component',
-      'x-rsc-action': id,
-    },
+    headers: actionHeaders,
     body,
   }).then((res) => {
+    // Version skew detection (TIM-446): if the server signals a reload,
+    // trigger a full page load to pick up the new deployment.
+    if (res.headers.get(RELOAD_HEADER) === '1') {
+      window.location.reload();
+      throw new Error('Version skew detected — reloading page');
+    }
     hasRevalidation = res.headers.get('X-Timber-Revalidation') === '1';
     hasRedirect = res.headers.get('X-Timber-Redirect') != null;
     headElementsJson = res.headers.get('X-Timber-Head');
@@ -155,7 +181,17 @@ setServerCallback(async (id: string, args: unknown[]) => {
  * Hydrates the server-rendered HTML with React, then initializes
  * client-side navigation for SPA transitions.
  */
-/** Read scroll position from window or scroll containers. */
+/**
+ * Read the current scroll position.
+ *
+ * Checks window scroll first, then explicit `data-timber-scroll-restoration`
+ * containers. With segment tree merging, shared layouts are reconciled in
+ * place via `cloneElement` — React preserves their DOM and scroll state
+ * naturally. We don't need to auto-detect overflow containers; only
+ * explicitly marked containers are tracked.
+ *
+ * See design/19-client-navigation.md §"Overflow Scroll Containers".
+ */
 function getScrollY(): number {
   if (window.scrollY || document.documentElement.scrollTop || document.body.scrollTop) {
     return window.scrollY || document.documentElement.scrollTop || document.body.scrollTop;
@@ -163,74 +199,24 @@ function getScrollY(): number {
   for (const el of document.querySelectorAll('[data-timber-scroll-restoration]')) {
     if ((el as HTMLElement).scrollTop > 0) return (el as HTMLElement).scrollTop;
   }
-  // Auto-detect: if window isn't scrolled, check for overflow containers.
-  // Common pattern: layouts use a scrollable div (overflow-y: auto/scroll)
-  // inside a fixed-height parent (h-screen). In this case window.scrollY is
-  // always 0 and the real scroll position lives on the overflow container.
-  const container = findOverflowContainer();
-  if (container && container.scrollTop > 0) return container.scrollTop;
   return 0;
 }
 
-/**
- * Find the primary overflow scroll container in the document.
- *
- * Walks direct children of body and their immediate children looking for
- * an element with overflow-y: auto|scroll that is actually scrollable
- * (scrollHeight > clientHeight). Returns the first match, or null.
- *
- * This heuristic covers the common layout patterns:
- *   <body> → <root-layout> → <div class="overflow-y-auto">
- *   <body> → <root-layout> → <main> → <nested-layout overflow-y-auto>
- *
- * We limit depth to 3 to avoid expensive full-tree traversals while still
- * reaching nested layout scroll containers (e.g., parallel route layouts
- * inside a root layout's <main> element).
- *
- * DIVERGENCE FROM NEXT.JS: Next.js's ScrollAndFocusHandler scrolls only
- * document.documentElement.scrollTop — it does NOT handle overflow containers.
- * Layouts using h-screen + overflow-y-auto have the same scroll bug in Next.js.
- * This heuristic is a deliberate improvement. The tradeoff is fragility: depth-3
- * traversal may miss deeply nested containers or match the wrong element.
- * See design/19-client-navigation.md §"Overflow Scroll Containers".
- */
-function findOverflowContainer(): HTMLElement | null {
-  const candidates: HTMLElement[] = [];
-  // Check body's descendants up to depth 3. Depth 3 covers the common case:
-  //   <body> → <root-layout-div> → <main> → <overflow-container>
-  // React context providers (SegmentProvider, NavigationProvider) don't add
-  // DOM elements, so depth 3 from body reaches nested layout scroll containers.
-  for (const child of document.body.children) {
-    candidates.push(child as HTMLElement);
-    for (const grandchild of child.children) {
-      candidates.push(grandchild as HTMLElement);
-      for (const greatGrandchild of grandchild.children) {
-        candidates.push(greatGrandchild as HTMLElement);
-      }
-    }
-  }
-  for (const el of candidates) {
-    if (!(el instanceof HTMLElement)) continue;
-    const style = getComputedStyle(el);
-    const overflowY = style.overflowY;
-    if (
-      (overflowY === 'auto' || overflowY === 'scroll') &&
-      el.scrollHeight > el.clientHeight
-    ) {
-      return el;
-    }
-  }
-  return null;
-}
-
 function bootstrap(runtimeConfig: typeof config): void {
   const _config = runtimeConfig;
 
-  // Take manual control of scroll restoration. React's render() on the
-  // document root resets scroll during DOM reconciliation, so the browser's
-  // native scroll restoration (scrollRestoration = 'auto') doesn't work —
-  // the browser restores scroll, then React's commit resets it to 0.
-  // We save/restore scroll positions explicitly in the history stack.
+  // Initialize deployment ID for version skew detection (TIM-446).
+  // In dev mode this is null — skew checks are skipped.
+  const deploymentId = (_config as Record<string, unknown>).deploymentId as string | null;
+  if (deploymentId) {
+    setClientDeploymentId(deploymentId);
+  }
+
+  // Take manual control of scroll restoration. Even though segment tree
+  // merging preserves shared layout DOM via cloneElement (so React doesn't
+  // reset scroll on those elements), the root-level reactRoot.render() with
+  // a new element tree can still cause scroll resets on the document during
+  // reconciliation. Manual control ensures consistent behavior.
   window.history.scrollRestoration = 'manual';
 
   // Hydrate the React tree from the RSC payload.
@@ -246,7 +232,13 @@ function bootstrap(runtimeConfig: typeof config): void {
   // For subsequent navigations, it's fetched from the server.
   type FlightSegment = [isBootstrap: 0] | [isData: 1, data: string];
 
-  const timberChunks = (self as unknown as Record<string, FlightSegment[]>).__timber_f;
+  // __timber_f is initialized in <head> via flightInitScript() (see
+  // flight-scripts.ts). If it doesn't exist, skip Flight decoding
+  // entirely and fall through to the createRoot branch.
+  // Do NOT defensively create it here: that would cause
+  // createFromReadableStream to be called on an empty stream, producing
+  // a "Connection closed" error on hydration. See TIM-552.
+  const timberChunks = (self as unknown as Record<string, FlightSegment[] | undefined>).__timber_f;
 
   let _reactRoot: Root | null = null;
   let initialElement: unknown = null;
@@ -318,6 +310,28 @@ function bootstrap(runtimeConfig: typeof config): void {
     // Leaving the stream open is harmless: the page is being torn down.
     function onDOMContentLoaded(): void {
       if (isPageUnloading()) return;
+
+      // In dev mode, do NOT close the stream. React's RSC renderer
+      // includes debug owner/stack references ($1, $14, etc.) in the
+      // Flight payload that point to rows delivered through the debug
+      // channel, not the main Flight stream. The browser Flight client
+      // tracks these as pending chunks. Closing the stream with
+      // unresolved chunks triggers reportGlobalError("Connection closed")
+      // which kills the entire React tree.
+      //
+      // Leaving the stream open is harmless: React has already received
+      // all data rows and can hydrate fully. The pending debug chunks
+      // just remain unresolved (they're only used for React DevTools
+      // component stacks, not rendering).
+      //
+      // In production, debug rows are not emitted, so closing is safe.
+      if (process.env.NODE_ENV === 'development') {
+        // Mark as flushed so no more data is buffered, but don't close.
+        streamFlushed = true;
+        dataBuffer = undefined;
+        return;
+      }
+
       if (streamWriter && !streamFlushed) {
         streamWriter.close();
         streamFlushed = true;
@@ -329,9 +343,23 @@ function bootstrap(runtimeConfig: typeof config): void {
     if (document.readyState === 'loading') {
       document.addEventListener('DOMContentLoaded', onDOMContentLoaded, false);
     } else {
-      // DOM already parsed — close after a microtask to ensure
-      // any pending push() calls from inline scripts have executed.
-      setTimeout(onDOMContentLoaded);
+      // DOM already parsed. All inline RSC <script> tags have already
+      // executed and pushed their data into the buffer. The buffer was
+      // flushed into the stream during start() above.
+      //
+      // Close via queueMicrotask rather than setTimeout. setTimeout
+      // defers to the next macrotask, which can race with React's
+      // Flight client read loop — if React finishes reading all queued
+      // chunks and issues a reader.read() that pends, the stream is
+      // NOT closed yet (setTimeout hasn't fired), so React sees an
+      // open stream and waits. Then setTimeout fires and closes it.
+      // This works in theory but some React Flight builds interpret
+      // a mid-read close as "Connection closed" rather than clean EOF.
+      // queueMicrotask fires at the end of the current microtask
+      // checkpoint — after start() and createFromReadableStream
+      // initialization but before any macrotask, giving React a
+      // consistent close signal. See TIM-524.
+      queueMicrotask(onDOMContentLoaded);
     }
 
     const element = createFromReadableStream(rscPayload);
@@ -347,7 +375,7 @@ function bootstrap(runtimeConfig: typeof config): void {
 
     // ── Initialize navigation state BEFORE hydration ───────────────────
     // Read server-embedded params and set navigation state so that
-    // useParams() and usePathname() return correct values during hydration.
+    // useSegmentParams() and usePathname() return correct values during hydration.
     // This must happen before hydrateRoot so the NavigationProvider
     // wrapping the element has the right values on the initial render.
     const earlyParams = (self as unknown as Record<string, unknown>).__timber_params;
@@ -381,7 +409,10 @@ function bootstrap(runtimeConfig: typeof config): void {
       element as React.ReactNode
     );
     const wrapped = createElement(TimberNuqsAdapter, null, withNav);
-    const rootElement = createElement(TransitionRoot, { initial: wrapped, topLoaderConfig: _config.topLoader });
+    const rootElement = createElement(TransitionRoot, {
+      initial: wrapped,
+      topLoaderConfig: _config.topLoader,
+    });
     _reactRoot = hydrateRoot(document, rootElement, {
       // Suppress recoverable hydration errors from deny/error signals
       // inside Suspense boundaries. The server already handled these
@@ -401,12 +432,24 @@ function bootstrap(runtimeConfig: typeof config): void {
       },
     });
   } else {
-    // No RSC payload available (plugin hasn't inlined it yet) — create a
-    // non-hydrated root so client navigation can still render RSC payloads.
-    // The initial SSR HTML remains as-is; the first client navigation will
-    // replace it with a React-managed tree.
+    // No RSC payload available — create a non-hydrated root so client
+    // navigation can still render RSC payloads. The initial SSR HTML
+    // remains as-is; the first client navigation will replace it with
+    // a React-managed tree.
     initRouter();
+    // Mount TransitionRoot so navigateTransition is wired up for client
+    // navigation. Without this, navigation from SSR-only/shell-less pages
+    // updates URL/history but leaves stale page content (TIM-580).
+    const navState = getNavigationState();
+    const placeholder = createElement('div') as unknown as React.ReactNode;
+    const withNav = createElement(NavigationProvider, { value: navState }, placeholder);
+    const wrapped = createElement(TimberNuqsAdapter, null, withNav);
+    const rootElement = createElement(TransitionRoot, {
+      initial: wrapped,
+      topLoaderConfig: _config.topLoader,
+    });
     _reactRoot = createRoot(document);
+    _reactRoot.render(rootElement);
   }
 
   // ── Router initialization (hoisted above hydrateRoot) ────────────────
@@ -420,23 +463,20 @@ function bootstrap(runtimeConfig: typeof config): void {
       pushState: (data, unused, url) => window.history.pushState(data, unused, url),
       replaceState: (data, unused, url) => window.history.replaceState(data, unused, url),
       scrollTo: (x, y) => {
+        // Scroll the document viewport.
         window.scrollTo(x, y);
         document.documentElement.scrollTop = y;
         document.body.scrollTop = y;
-        // Also scroll any element explicitly marked as a scroll container.
+        // Scroll any element explicitly marked as a scroll container.
+        // With segment tree merging, shared layouts (sidebars, nav bars)
+        // are reconciled in place via cloneElement — React preserves their
+        // DOM and scroll state naturally. We no longer auto-detect overflow
+        // containers, which previously found the wrong element (e.g.,
+        // scrolling a sidebar instead of the main content area).
+        // Use `data-timber-scroll-restoration` to opt in specific containers.
         for (const el of document.querySelectorAll('[data-timber-scroll-restoration]')) {
           (el as HTMLElement).scrollTop = y;
         }
-        // Auto-detect overflow containers for layouts that scroll inside
-        // a fixed-height wrapper (e.g., h-screen + overflow-y-auto).
-        // In these layouts, window.scrollY is always 0 and the real scroll
-        // lives on the overflow container. Without this, forward navigation
-        // between pages that share a layout with parallel route slots won't
-        // scroll to top — the router's window.scrollTo(0,0) is a no-op.
-        const container = findOverflowContainer();
-        if (container) {
-          container.scrollTop = y;
-        }
       },
       getCurrentUrl: () => window.location.pathname + window.location.search,
       getScrollY,
@@ -471,8 +511,10 @@ function bootstrap(runtimeConfig: typeof config): void {
       // For navigation renders (navigate, refresh, popstate-with-fetch),
       // navigateTransition is used instead — it wraps the entire navigation
       // in a React transition with useOptimistic for the pending URL.
-      renderRoot: (element: unknown) => {
-        const navState = getNavigationState();
+      //
+      // navState is passed explicitly by the router — no temporal coupling
+      // with getNavigationState().
+      renderRoot: (element: unknown, navState: NavigationState) => {
         const withNav = createElement(
           NavigationProvider,
           { value: navState },
@@ -488,13 +530,11 @@ function bootstrap(runtimeConfig: typeof config): void {
       // commits (atomic with the new tree + params).
       //
       // The perform callback receives a wrapPayload function that wraps the
-      // decoded RSC payload with NavigationProvider + NuqsAdapter — this must
-      // happen inside the transition so the NavigationProvider reads the
-      // UPDATED navigation state (set by the router inside perform).
+      // decoded RSC payload with NavigationProvider + NuqsAdapter. navState
+      // is passed explicitly by the router — no getNavigationState() needed.
       navigateTransition: (pendingUrl: string, perform) => {
         return navigateTransition(pendingUrl, async () => {
-          const payload = await perform((rawPayload: unknown) => {
-            const navState = getNavigationState();
+          const payload = await perform((rawPayload: unknown, navState: NavigationState) => {
             const withNav = createElement(
               NavigationProvider,
               { value: navState },
@@ -586,7 +626,6 @@ function bootstrap(runtimeConfig: typeof config): void {
     scrollTimer = setTimeout(() => {
       const state = window.history.state;
       if (state && typeof state === 'object') {
-        // Use getScrollY to capture scroll from overflow containers too.
         window.history.replaceState({ ...state, scrollY: getScrollY() }, '');
       }
     }, 100);
@@ -655,8 +694,21 @@ clearStaleReloadFlag();
 // If the payload references a module ID from a newer deployment, the error
 // surfaces as an unhandled rejection during React's render/hydration cycle.
 // This handler catches those errors and triggers a full page reload.
+//
+// Also catches chunk load failures (dynamic import of missing assets after
+// a deployment) — these surface as "Failed to fetch dynamically imported module"
+// or "Loading chunk <name> failed" errors. See TIM-446.
 window.addEventListener('unhandledrejection', (event) => {
-  if (isStaleClientReference(event.reason)) {
+  if (isStaleClientReference(event.reason) || isChunkLoadError(event.reason)) {
+    event.preventDefault();
+    triggerStaleReload();
+  }
+});
+
+// Also catch synchronous errors from chunk loads (some browsers throw
+// TypeError synchronously instead of via unhandled rejection).
+window.addEventListener('error', (event) => {
+  if (isChunkLoadError(event.error)) {
     event.preventDefault();
     triggerStaleReload();
   }

package/src/client/error-boundary.tsx

@@ -65,7 +65,16 @@ type ParsedDigest = DenyDigest | RenderErrorDigest | RedirectDigest;
 
 export interface TimberErrorBoundaryProps {
   /** The component to render when an error is caught. */
-  fallbackComponent: (...args: unknown[]) => ReactNode;
+  fallbackComponent?: (...args: unknown[]) => ReactNode;
+  /**
+   * Pre-rendered fallback element. Used for MDX status files which are server
+   * components and cannot be passed as function props across the RSC→client
+   * boundary. When set, rendered directly instead of calling fallbackComponent.
+   *
+   * See design/10-error-handling.md §"Status-Code File Variants" — MDX status
+   * files are server components by default (zero client JS).
+   */
+  fallbackElement?: ReactNode;
   /**
    * Status code filter. If set, only catches errors matching this status.
    * 400 = any 4xx, 500 = any 5xx, specific number = exact match.
@@ -162,6 +171,14 @@ export class TimberErrorBoundary extends Component<
       }
     }
 
+    // Pre-rendered fallback element (MDX status files) — render directly.
+    // MDX components are server components that cannot be passed as function
+    // props across the RSC→client boundary. Instead, they are pre-rendered
+    // as elements in the RSC environment and passed here as fallbackElement.
+    if (this.props.fallbackElement != null) {
+      return this.props.fallbackElement;
+    }
+
     // Render the fallback component with the right props shape.
     if (parsed?.type === 'deny') {
       return createElement(this.props.fallbackComponent as never, {

package/src/client/error-reconstituter.tsx

@@ -0,0 +1,65 @@
+'use client';
+
+/**
+ * Reconstitutes a SerializableError into a real Error instance before
+ * passing to the user's error component.
+ *
+ * TSX error pages are 'use client' components that receive { error: Error, digest, reset }.
+ * Error objects are not RSC-serializable (React Flight throws "Only plain objects
+ * can be passed to Client Components"). This wrapper receives the error as a plain
+ * SerializableError object, reconstitutes a real Error instance, and passes it
+ * to the user's error component — ensuring error instanceof Error works correctly.
+ *
+ * See design/spike-TIM-565-unify-error-pages.md §"Edge Case B"
+ * See design/10-error-handling.md §"RSC → SSR for Error Pages via SerializableError"
+ */
+
+import { createElement, type ReactNode, type ComponentType } from 'react';
+
+/**
+ * Plain-object representation of an Error that can cross the RSC → client boundary.
+ * Stack is only included in dev mode (gated by isDevMode() on the server).
+ */
+export interface SerializableError {
+  message: string;
+  name: string;
+  stack?: string;
+}
+
+/**
+ * Props for the ErrorReconstituter wrapper component.
+ * All props are RSC-serializable:
+ * - error: plain object (SerializableError)
+ * - digest: plain JSON or null
+ * - reset: undefined (only meaningful on client after boundary catch)
+ * - component: client module reference (RSC Flight serializes as opaque ref)
+ */
+interface ErrorReconstituterProps {
+  error: SerializableError;
+  digest: { code: string; data: unknown } | null;
+  reset: undefined;
+  component: ComponentType<{
+    error: Error;
+    digest: { code: string; data: unknown } | null;
+    reset: (() => void) | undefined;
+  }>;
+}
+
+/**
+ * Reconstitute a SerializableError into a real Error instance and render
+ * the user's error component with the proper props.
+ */
+export function ErrorReconstituter({
+  error: serialized,
+  digest,
+  reset,
+  component,
+}: ErrorReconstituterProps): ReactNode {
+  // Reconstitute a real Error so instanceof checks work in user code
+  const error = Object.assign(new Error(serialized.message), {
+    name: serialized.name,
+    ...(serialized.stack != null ? { stack: serialized.stack } : {}),
+  });
+
+  return createElement(component, { error, digest, reset });
+}

package/src/client/form.tsx

@@ -12,8 +12,8 @@
  */
 
 import { useActionState as reactUseActionState, useTransition } from 'react';
-import type { ActionResult, ValidationErrors } from '#/server/action-client';
-import type { FormFlashData } from '#/server/form-flash';
+import type { ActionResult, ValidationErrors } from '../server/action-client';
+import type { FormFlashData } from '../server/form-flash';
 
 // ─── Types ───────────────────────────────────────────────────────────────
 

package/src/client/index.ts

@@ -5,6 +5,7 @@ export type { JsonSerializable, RenderErrorDigest } from './types';
 
 // Navigation
 export { Link, interpolateParams, resolveHref, validateLinkHref, buildLinkProps } from './link';
+export { mergePreservedSearchParams } from '../shared/merge-search-params.js';
 export type { LinkProps, LinkPropsWithHref, LinkPropsWithParams } from './link';
 export type { OnNavigateHandler, OnNavigateEvent } from './link';
 export { createRouter } from './router';
@@ -12,6 +13,7 @@ export type {
   RouterInstance,
   NavigationOptions,
   RouterDeps,
+  RouterPhase,
   RscDecoder,
   RootRenderer,
 } from './router';
@@ -42,7 +44,7 @@ export { useActionState, useFormAction, useFormErrors } from './form';
 export type { UseActionStateFn, UseActionStateReturn, FormErrorsResult } from './form';
 
 // Params
-export { useParams, setCurrentParams } from './use-params';
+export { useSegmentParams, setCurrentParams } from './use-params';
 
 // Navigation context (framework-internal, used by browser-entry for atomic updates)
 export { NavigationProvider, getNavigationState, setNavigationState } from './navigation-context';
@@ -55,6 +57,13 @@ export { useQueryStates, bindUseQueryStates } from './use-query-states';
 export { useCookie } from './use-cookie';
 export type { ClientCookieOptions, CookieSetter } from './use-cookie';
 
+// Register the client cookie module with defineCookie's lazy reference.
+// This runs at module load time in the client/SSR environment, wiring up
+// the useCookie hook without a top-level import in define-cookie.ts.
+import * as _useCookieMod from './use-cookie.js';
+import { _registerUseCookieModule } from '../cookies/define-cookie.js';
+_registerUseCookieModule(_useCookieMod);
+
 // SSR data (framework-internal, used by ssr-entry to provide request data to hooks)
 export { setSsrData, clearSsrData, getSsrData } from './ssr-data';
 export type { SsrData } from './ssr-data';

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

@@ -0,0 +1,136 @@
+/**
+ * Link Pending Store — module-level singleton for per-link pending state.
+ *
+ * Tracks which link instance is currently navigating so that only the
+ * clicked link shows pending. All other links remain unaffected — zero
+ * wasted re-renders.
+ *
+ * The store holds:
+ * - A reference to the currently navigating link's state setter
+ * - A navigation counter to guard against stale clears (race condition
+ *   when the user clicks Link B before Link A's navigation completes)
+ *
+ * Flow:
+ * 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) →
+ *    calls setter(IDLE) inside the transition (batched, atomic with tree)
+ *    Only clears if navId matches (prevents stale T1 from clearing T2's link)
+ *
+ * SINGLETON GUARANTEE: Uses `globalThis` via `Symbol.for` keys (same
+ * pattern as NavigationContext) because the RSC client bundler can
+ * duplicate this module across chunks. Module-level variables would
+ * create separate instances per chunk.
+ *
+ * See design/19-client-navigation.md §"Per-Link Pending State"
+ */
+
+import type { LinkStatus } from './use-link-status.js';
+
+// ─── Types ───────────────────────────────────────────────────────
+
+export interface LinkPendingInstance {
+  setLinkStatus: (status: LinkStatus) => void;
+}
+
+// ─── Singleton Storage ───────────────────────────────────────────
+
+const LINK_PENDING_KEY = Symbol.for('__timber_link_pending');
+
+/** Status object indicating link is pending — shared reference */
+export const PENDING_LINK_STATUS: LinkStatus = { pending: true };
+
+/** Status object indicating link is idle — shared reference */
+export const IDLE_LINK_STATUS: LinkStatus = { pending: false };
+
+interface LinkPendingState {
+  /** The link instance that initiated the current navigation, or null */
+  current: LinkPendingInstance | null;
+  /** Monotonically increasing counter — guards against stale clears */
+  navId: number;
+}
+
+function getStore(): LinkPendingState {
+  const g = globalThis as Record<symbol, unknown>;
+  if (!g[LINK_PENDING_KEY]) {
+    g[LINK_PENDING_KEY] = { current: null, navId: 0 };
+  }
+  return g[LINK_PENDING_KEY] as LinkPendingState;
+}
+
+// ─── Public API ──────────────────────────────────────────────────
+
+/**
+ * Register the link instance that initiated the current navigation.
+ *
+ * Called from <Link>'s click handler before router.navigate().
+ * - Resets the previous pending link to IDLE (urgent update, immediate)
+ * - Does NOT set the new link to PENDING here — the Link's click handler
+ *   calls setLinkStatus(PENDING) directly for the eager show
+ * - Increments the navId counter for stale-clear protection
+ *
+ * Pass `null` to clear (e.g., for programmatic navigations).
+ */
+export function setLinkForCurrentNavigation(link: LinkPendingInstance | null): void {
+  const store = getStore();
+  const prev = store.current;
+
+  // Reset previous pending link to idle (urgent update — shows immediately)
+  if (prev && prev !== link) {
+    prev.setLinkStatus(IDLE_LINK_STATUS);
+  }
+
+  store.current = link;
+  store.navId++;
+}
+
+/**
+ * Get the current navigation ID. Called at the start of the transition
+ * to capture the ID before async work begins.
+ */
+export function getCurrentNavId(): number {
+  return getStore().navId;
+}
+
+/**
+ * Reset the current link's pending state to IDLE, but only if the navId
+ * matches. Called inside TransitionRoot's startTransition after the async
+ * work completes — the setter call is a transition update, so it commits
+ * atomically with the new tree.
+ *
+ * The navId guard prevents stale transitions from clearing a newer
+ * navigation's pending state. Scenario:
+ *   Click A → navId=1, T1 starts
+ *   Click B → navId=2, A reset to IDLE, T2 starts
+ *   T1 completes → resetLinkPending(1) → navId is 2, skip ✓
+ *   T2 completes → resetLinkPending(2) → navId is 2, clear ✓
+ */
+export function resetLinkPending(forNavId: number): void {
+  const store = getStore();
+  if (store.navId === forNavId && store.current) {
+    store.current.setLinkStatus(IDLE_LINK_STATUS);
+    store.current = null;
+  }
+}
+
+/**
+ * Clean up the link pending store entirely. Safety net for error paths.
+ */
+export function clearLinkPendingSetter(): void {
+  const store = getStore();
+  store.current = null;
+}
+
+/**
+ * Unmount a link instance from navigation tracking. Called when a Link
+ * component unmounts while it is the current navigation link. Prevents
+ * calling setState on an unmounted component.
+ */
+export function unmountLinkForCurrentNavigation(link: LinkPendingInstance): void {
+  const store = getStore();
+  if (store.current === link) {
+    store.current = null;
+  }
+}