@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.191

package/src/client/slot-provider.tsx

@@ -0,0 +1,32 @@
+/**
+ * SlotsProvider — wraps a revived cached shell to supply live slot content
+ * to the SlotOutlet holes inside it (TIM-1173).
+ *
+ * Values MERGE with the nearest parent provider so that nesting a
+ * cache.component SlotsProvider inside a layout SlotsProvider preserves
+ * the layout's `children` slot while adding the component's own slots.
+ * Inner values override outer ones with the same name (spread order).
+ *
+ * Tree structure per cached-component instance:
+ *   SlotsProvider(values={children: <Live />})
+ *     └── revived shell
+ *          └── SlotOutlet(slot="children") → reads context → <Live />
+ *
+ * See design/45-cache-lifetimes.md §Slot Components.
+ */
+
+'use client';
+
+import { createElement, useContext, type ReactNode } from 'react';
+import { SlotContext, type SlotValues } from './slot-context.js';
+
+interface SlotsProviderProps {
+  values: SlotValues;
+  children: ReactNode;
+}
+
+export function SlotsProvider({ values, children }: SlotsProviderProps) {
+  const parent = useContext(SlotContext);
+  const merged = parent ? { ...parent, ...values } : values;
+  return createElement(SlotContext.Provider, { value: merged }, children);
+}

package/src/client/ssr-data.ts

@@ -28,6 +28,8 @@ import {
   _setSsrDataProvider,
   _setCurrentSsrData,
 } from './state.js';
+import type { CoercedParams } from '../shared/param-value.js';
+import type { SlotParamsRecord } from '../shared/slot-params.js';
 
 // ─── Types ────────────────────────────────────────────────────────
 
@@ -39,14 +41,27 @@ export interface SsrData {
   /** The request's cookies as name→value pairs */
   cookies: Map<string, string>;
   /** The request's route params (e.g. { id: '123' }) */
-  params: Record<string, string | string[]>;
+  params: CoercedParams;
   /**
-   * Mutable reference to NavContext for error boundary → RSC communication.
-   * When TimberErrorBoundary catches a DenySignal, it sets
-   * `_navContext._denyHandledByBoundary = true` to prevent the RSC entry
-   * from promoting the denial to page-level. See LOCAL-298.
+   * Per-slot params keyed by slot tree path, absent when the request rendered
+   * no slot with params of its own (TIM-1285).
    */
-  _navContext?: { _denyHandledByBoundary?: boolean };
+  slotParams?: SlotParamsRecord;
+  /**
+   * Mutable reference to NavContext for error boundary → pipeline communication.
+   *
+   * When TimberErrorBoundary catches a DenySignal during SSR, it:
+   * 1. Sets `statusCode` to the deny status (e.g., 403) — so the HTTP
+   *    Response has the correct status code without a re-render.
+   * 2. Sets `_denyHandledByBoundary = true` — so the pipeline skips
+   *    the redundant renderDenyPage() re-render.
+   *
+   * This runs synchronously during Fizz rendering, BEFORE onShellReady,
+   * so the status code is committed before any bytes are sent.
+   *
+   * See TIM-664, design/04-authorization.md §"React.cache Scope in Deny/Error Re-renders"
+   */
+  _navContext?: { statusCode?: number; _denyHandledByBoundary?: boolean };
 }
 
 // ─── ALS-Backed Provider ─────────────────────────────────────────

package/src/client/stale-client.ts

@@ -0,0 +1,191 @@
+/**
+ * Stale Client — knowing when this bundle has been superseded.
+ *
+ * Layer 1 of version skew handling (see design/33-version-skew.md) is
+ * proactive: the server compares `X-Timber-Deployment-Id` against the current
+ * build and answers a stale client with `X-Timber-Reload: 1`. That covers
+ * every RSC navigation and every server action — as long as there is a server
+ * in the request path.
+ *
+ * This module is the reactive half, plus the state both halves feed. It
+ * recognizes the two error shapes a stale client produces on its own:
+ *
+ * 1. **Stale client references** — React's Flight client throws
+ *    "Could not find the module …" when an RSC payload names a client module
+ *    ID that isn't in this bundle's manifest.
+ * 2. **Chunk load failures** — a content-hashed chunk that no longer exists on
+ *    the CDN fails to `import()`. Every engine words this differently.
+ *
+ * It matters most for `output: 'static'`, where there is no server to send the
+ * reload header and this is the *only* skew detection that can run.
+ *
+ * **Nothing here reloads the page.** A stale client is recorded, not acted on;
+ * the router turns the next user-initiated navigation into a full document
+ * load. See design/33-version-skew.md §"Recovery on the next navigation" for
+ * why — a self-issued `location.reload()` cannot tell a recovery from a bounce
+ * between two live deployments, and mid-rollout it produces exactly that loop.
+ *
+ * See TIM-1260, TIM-1275.
+ */
+
+// The only import: the shared unload state. Kept minimal because this module
+// is reached from the error boundary, a `'use client'` component evaluated in
+// the SSR graph too — a dependency on the client fetch layer would drag that
+// graph along with it.
+import { isPageUnloading } from './unload-guard.js';
+
+// ─── Error Shapes ────────────────────────────────────────────────
+
+/**
+ * Substrings that identify a failed dynamic import, lowercased for
+ * case-insensitive matching. Engines and bundlers each word this
+ * differently and none of them expose a stable error code.
+ */
+const CHUNK_LOAD_PATTERNS = [
+  // Chromium
+  'failed to fetch dynamically imported module',
+  // Firefox
+  'error loading dynamically imported module',
+  // Safari
+  'importing a module script failed',
+  // Vite's preload helper, for the stylesheet of a lazily-imported chunk
+  'unable to preload css for',
+];
+
+/** Substring React's Flight client uses when a client module ID is unknown. */
+const STALE_REFERENCE_PATTERN = 'could not find the module';
+
+/**
+ * Pull a comparable message out of an unknown thrown value. Rejections cross
+ * enough boundaries (event handlers, `unhandledrejection`, Vite's preload
+ * event) that the value is not reliably an `Error`.
+ */
+function messageOf(error: unknown): string {
+  if (typeof error === 'string') return error.toLowerCase();
+  if (error instanceof Error) return error.message.toLowerCase();
+  if (error && typeof error === 'object' && 'message' in error) {
+    const message = (error as { message: unknown }).message;
+    if (typeof message === 'string') return message.toLowerCase();
+  }
+  return '';
+}
+
+/**
+ * True when the error is React's "client reference not in this manifest"
+ * failure — the payload was produced by a build this bundle doesn't match.
+ */
+export function isStaleClientReference(error: unknown): boolean {
+  return messageOf(error).includes(STALE_REFERENCE_PATTERN);
+}
+
+/**
+ * True when the error is a failed dynamic import or CSS preload — the
+ * content-hashed chunk this bundle asks for is gone from the CDN.
+ */
+export function isChunkLoadError(error: unknown): boolean {
+  if (error instanceof Error && error.name === 'ChunkLoadError') return true;
+  const message = messageOf(error);
+  return CHUNK_LOAD_PATTERNS.some((pattern) => message.includes(pattern));
+}
+
+// ─── Staleness ───────────────────────────────────────────────────
+
+/**
+ * True once this client is known to be running against a superseded
+ * deployment. One-way: a document that has gone stale cannot come back, since
+ * the only way to get fresh code is to load a new document.
+ *
+ * In-memory on purpose. Persisting it would be wrong — the next document gets
+ * whatever build the server hands it, and if that one is stale too it will
+ * find out the same way.
+ */
+let stale = false;
+
+/**
+ * True once {@link initStaleClient} has seen a deployment ID — i.e. this is a
+ * production build. False in dev, where nothing is ever stale: HMR owns code
+ * updates, and a failed dynamic import is a real error the developer needs to
+ * see rather than something a page load fixes.
+ */
+let deployed = false;
+
+/** Whether this client has been superseded by a newer deployment. */
+export function isClientStale(): boolean {
+  return stale;
+}
+
+/**
+ * Record that the origin has told us this client is stale — the `X-Timber-Reload`
+ * header on an RSC or action response. Authoritative, so it is not gated on
+ * anything: a dev server never sends the header in the first place.
+ */
+export function markClientStale(): void {
+  stale = true;
+}
+
+/**
+ * Record staleness if `error` is one of the shapes a superseded bundle
+ * produces. Returns whether it did, so a caller mid-navigation can decide to
+ * hard-navigate instead of surfacing the error.
+ *
+ * Inference, unlike {@link markClientStale}, so it is gated on being a
+ * production build. This is the single place that gate lives — call sites
+ * cannot see each other, and "remember to gate the next one too" is not a
+ * guarantee.
+ */
+export function markStaleFromError(error: unknown): boolean {
+  if (!deployed) return false;
+
+  // A document being torn down aborts its in-flight dynamic imports, and an
+  // aborted import reads exactly like a chunk the CDN has dropped. That is not
+  // evidence of staleness, and the bit outlives the teardown that produced it:
+  // a document entering the back-forward cache is frozen, not destroyed, so a
+  // false positive recorded on the way out would cost the *restored* page its
+  // client-side navigation for good. `unload-guard.ts` clears its own flag on
+  // a persisted `pageshow`; this one is one-way by design, so it has to not be
+  // set in the first place.
+  if (isPageUnloading()) return false;
+
+  if (!isStaleClientReference(error) && !isChunkLoadError(error)) return false;
+  stale = true;
+  return true;
+}
+
+// ─── Initialization ──────────────────────────────────────────────
+
+/**
+ * The underlying error Vite attaches to a `vite:preloadError` event.
+ *
+ * Narrowed at runtime rather than cast: the property is Vite's, not ours, and
+ * a shape change should fall back to matching the event itself rather than
+ * silently reading `undefined` forever.
+ */
+function preloadErrorPayload(event: Event): unknown {
+  return 'payload' in event ? (event as Event & { payload: unknown }).payload : event;
+}
+
+/**
+ * Arm the module, and register the listeners that catch stale-client errors
+ * never passing through the router: a lazily imported client component, a
+ * preloaded stylesheet, anything that rejects outside a navigation.
+ *
+ * No-op when `deploymentId` is null — that is dev. Called from the browser
+ * entry before hydration, so it precedes any render or navigation that could
+ * throw.
+ */
+export function initStaleClient(deploymentId: string | null): void {
+  if (!deploymentId) return;
+  deployed = true;
+
+  // Vite dispatches this for failed chunk/CSS preloads. Note what is *not*
+  // here: `preventDefault()`. Recording staleness is not recovering from this
+  // error — the page is still broken until the user navigates — so Vite must
+  // go on rethrowing it rather than have it silently swallowed.
+  window.addEventListener('vite:preloadError', (event) => {
+    markStaleFromError(preloadErrorPayload(event));
+  });
+
+  window.addEventListener('unhandledrejection', (event: PromiseRejectionEvent) => {
+    markStaleFromError(event.reason);
+  });
+}

package/src/client/state.ts

@@ -3,7 +3,7 @@
  *
  * ALL mutable module-level state that must have singleton semantics across
  * the client bundle lives here. Individual modules (router-ref.ts, ssr-data.ts,
- * use-params.ts, use-search-params.ts, unload-guard.ts) import from this file
+ * use-segment-params.ts, use-search-params.ts, unload-guard.ts) import from this file
  * and re-export thin wrapper functions.
  *
  * Why: In Vite dev, a module is instantiated separately if reached via different
@@ -19,7 +19,9 @@
  * §"Singleton State Registry".
  */
 
-import type { RouterInstance } from './router.js';
+import type { CoercedParams } from '../shared/param-value.js';
+import type { SlotParamsRecord } from '../shared/slot-params.js';
+import type { RouterInstance } from './router-types.js';
 import type { SsrData } from './ssr-data.js';
 
 // ─── Router (from router-ref.ts) ──────────────────────────────────────────
@@ -50,15 +52,27 @@ export function _setCurrentSsrData(data: SsrData | undefined): void {
   currentSsrData = data;
 }
 
-// ─── Route Params (from use-params.ts) ──────────────────────────────────────
+// ─── Route Params (from use-segment-params.ts) ──────────────────────────────────────
 
 /** Current route params snapshot — replaced (not mutated) on each navigation. */
-export let currentParams: Record<string, string | string[]> = {};
+export let currentParams: CoercedParams = {};
 
-export function _setCurrentParams(params: Record<string, string | string[]>): void {
+export function _setCurrentParams(params: CoercedParams): void {
   currentParams = params;
 }
 
+/**
+ * Per-slot params snapshot, keyed by slot tree path — the module-level
+ * fallback behind `useSegmentParams(slotPath)` when no NavigationContext is
+ * mounted (tests, calls outside a component). Replaced, never mutated, on
+ * each navigation. See TIM-1285.
+ */
+export let currentSlotParams: SlotParamsRecord | null = null;
+
+export function _setCurrentSlotParams(slotParams: SlotParamsRecord | null): void {
+  currentSlotParams = slotParams;
+}
+
 /** Listeners notified when currentParams changes. */
 export const paramsListeners = new Set<() => void>();
 

package/src/client/top-loader.tsx

@@ -3,11 +3,11 @@
  *
  * 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
- * (`topLoader: { enabled: false }`) and use `useNavigationPending()` directly.
+ * (`topLoader: { enabled: false }`) and use `usePendingNavigation()` directly.
  *
  * Animation approach: pure CSS @keyframes. The bar crawls from 0% to ~90%
  * width over ~30s using ease-out timing. When navigation completes, the bar
@@ -21,14 +21,14 @@
  * stays invisible during the delay period. If navigation finishes before the
  * delay, the bar was never visible so the finish transition is also invisible.
  *
- * See design/19-client-navigation.md §"useNavigationPending()"
+ * See design/19-client-navigation.md §"usePendingNavigation()"
  * See LOCAL-336 for design decisions.
  */
 
 'use client';
 
 import { useState, createElement } from 'react';
-import { usePendingNavigationUrl } from './navigation-context.js';
+import { usePendingNavigation } from './use-pending-navigation.js';
 
 // ─── Types ───────────────────────────────────────────────────────
 
@@ -39,7 +39,7 @@ export interface TopLoaderConfig {
   color?: string;
   /** Bar height in pixels. Default: 3. */
   height?: number;
-  /** Show subtle glow/shadow effect. Default: true. */
+  /** Show subtle glow/shadow effect. Default: false. */
   shadow?: boolean;
   /** Delay in ms before showing the bar. Default: 0. */
   delay?: number;
@@ -51,7 +51,7 @@ export interface TopLoaderConfig {
 
 const DEFAULT_COLOR = '#2299DD';
 const DEFAULT_HEIGHT = 3;
-const DEFAULT_SHADOW = true;
+const DEFAULT_SHADOW = false;
 const DEFAULT_DELAY = 0;
 const DEFAULT_Z_INDEX = 1600;
 
@@ -97,9 +97,10 @@ function ensureKeyframes(): void {
 // ─── Component ───────────────────────────────────────────────────
 
 /**
- * Internal top-loader component. Injected by TransitionRoot.
+ * Internal top-loader component. Injected by NavigationRoot.
  *
- * Reads pending navigation state from PendingNavigationContext.
+ * Reads pending navigation state from the router's external store, via
+ * usePendingNavigation() — the one pending representation (TIM-1307).
  * Phase transitions are derived synchronously during render:
  *
  *   hidden → crawling:   when isPending becomes true
@@ -111,8 +112,10 @@ function ensureKeyframes(): void {
  * (getDerivedStateFromProps pattern) or triggered by DOM events.
  */
 export function TopLoader({ config }: { config?: TopLoaderConfig }): React.ReactElement | null {
-  const pendingUrl = usePendingNavigationUrl();
-  const isPending = pendingUrl !== null;
+  // Read pending state from the router's external store via
+  // useSyncExternalStore (inside usePendingNavigation). Only this
+  // component re-renders when pending changes — no full-tree re-render.
+  const isPending = usePendingNavigation();
 
   const color = config?.color ?? DEFAULT_COLOR;
   const height = config?.height ?? DEFAULT_HEIGHT;

package/src/client/unload-guard.ts

@@ -8,6 +8,11 @@
  * unloaded so error boundaries and error handlers can suppress abort-related
  * errors during the unload window.
  *
+ * This is the single owner of "is this document going away". Anything that
+ * needs the answer imports `isPageUnloading()` — an unload flag maintained a
+ * second time somewhere else is a flag that will drift out of agreement with
+ * this one (TIM-1260).
+ *
  * Mutable state is delegated to client/state.ts for singleton guarantees.
  * See design/18-build-system.md §"Singleton State Registry"
  *
@@ -16,16 +21,43 @@
 
 import { unloading, _setUnloading } from './state.js';
 
+/**
+ * Departure is *committed*: `pagehide` has fired, or this document has called
+ * reload() on itself. `beforeunload` alone doesn't qualify — it is
+ * speculative, and the user can still cancel out of it.
+ */
+let committed = false;
+
 if (typeof window !== 'undefined') {
   window.addEventListener('beforeunload', () => {
     _setUnloading(true);
+
+    // An app with an unsaved-changes prompt can have this cancelled. Nothing
+    // fires to say so, so the only signal is that the page is still running
+    // afterwards — and timers are blocked while the modal is up, so this task
+    // cannot run until the user has chosen. If they left, `pagehide` has
+    // already committed and this is a no-op.
+    setTimeout(() => {
+      if (!committed) _setUnloading(false);
+    }, 0);
   });
 
-  // Also detect pagehide for bfcache-aware browsers (Safari).
-  // pagehide fires for both navigations and page hide events.
+  // pagehide is the committed-departure event, and fires for both navigations
+  // and bfcache entry. Safari in particular may skip beforeunload entirely.
   window.addEventListener('pagehide', () => {
+    committed = true;
     _setUnloading(true);
   });
+
+  window.addEventListener('pageshow', (event) => {
+    // A bfcache restore un-does the teardown `pagehide` announced: the same
+    // document is alive again, with this module's state intact. Without the
+    // reset, every consumer would go on suppressing errors on a live page.
+    if (event.persisted) {
+      committed = false;
+      _setUnloading(false);
+    }
+  });
 }
 
 /**

package/src/client/use-cookie.ts

@@ -8,8 +8,17 @@
  * See design/29-cookies.md §"useCookie(name) Hook"
  */
 
-import { useSyncExternalStore } from 'react';
+// Namespace access, not `import { useSyncExternalStore }`. This module is
+// reachable from `@timber-js/app/cookies` — `defineCookie()` exposes both a
+// server `.get()` and a client `.useCookie()`, so the entry is isomorphic and
+// loads in the RSC environment. React's `react-server` export withholds
+// `useSyncExternalStore` exactly as it withholds `createContext`, and a *named*
+// ESM import of a missing export fails at module instantiation, before any
+// code runs. Same rule as `client/params-context.ts` (TIM-1297, TIM-1298).
+import * as React from 'react';
+import { parseCookie, stringifySetCookie } from 'cookie';
 import { getSsrData } from './ssr-data.js';
+import { assertValidCookieName } from '../cookies/validation.js';
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -38,26 +47,31 @@ type Listener = () => void;
 const listeners = new Map<string, Set<Listener>>();
 
 /** Parse a cookie name from document.cookie. */
-function getCookieValue(name: string): string | undefined {
+export function getCookieValue(name: string): string | undefined {
   if (typeof document === 'undefined') return undefined;
-  const match = document.cookie.match(
-    new RegExp('(?:^|;\\s*)' + name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\s*=\\s*([^;]*)')
-  );
-  return match ? decodeURIComponent(match[1]) : undefined;
+  const cookies = parseCookie(document.cookie);
+  return cookies[name];
 }
 
 /** Serialize options into a cookie string suffix. */
-function serializeOptions(options?: ClientCookieOptions): string {
+export function serializeOptions(options?: ClientCookieOptions): string {
   if (!options) return '; Path=/; SameSite=Lax';
-  const parts: string[] = [];
-  parts.push(`Path=${options.path ?? '/'}`);
-  if (options.domain) parts.push(`Domain=${options.domain}`);
-  if (options.maxAge !== undefined) parts.push(`Max-Age=${options.maxAge}`);
-  if (options.expires) parts.push(`Expires=${options.expires.toUTCString()}`);
   const sameSite = options.sameSite ?? 'lax';
-  parts.push(`SameSite=${sameSite.charAt(0).toUpperCase()}${sameSite.slice(1)}`);
-  if (options.secure) parts.push('Secure');
-  return '; ' + parts.join('; ');
+  // Build a Set-Cookie string via the cookie package, then strip the
+  // `__placeholder__=` name=value prefix to get just the attributes.
+  const full = stringifySetCookie({
+    name: '__placeholder__',
+    value: '',
+    path: options.path ?? '/',
+    domain: options.domain,
+    maxAge: options.maxAge,
+    expires: options.expires,
+    sameSite,
+    secure: options.secure,
+  });
+  // Strip everything up to and including the first "; "
+  const idx = full.indexOf('; ');
+  return idx >= 0 ? full.slice(idx) : '';
 }
 
 /** Notify all subscribers for a given cookie name. */
@@ -68,6 +82,17 @@ function notify(name: string): void {
   }
 }
 
+/**
+ * Notify useCookie subscribers that a cookie value changed.
+ * Called by defineCookie's imperative client .set()/.delete() methods
+ * so mounted useCookie() consumers re-render.
+ *
+ * @internal — framework use only
+ */
+export function notifyCookieChange(name: string): void {
+  notify(name);
+}
+
 // ─── Hook ─────────────────────────────────────────────────────────────────
 
 /**
@@ -99,12 +124,39 @@ export function useCookie(
   };
 
   const getSnapshot = (): string | undefined => getCookieValue(name);
-  const getServerSnapshot = (): string | undefined => getSsrData()?.cookies.get(name);
+  const getServerSnapshot = (): string | undefined => {
+    // During SSR, read the ALS-backed request cookies.
+    const ssrData = getSsrData();
+    if (ssrData) return ssrData.cookies.get(name);
+    // During client hydration there is no SSR data (it lives in the server's
+    // module graph), but React still calls getServerSnapshot. document.cookie
+    // holds the same cookies the server rendered with, so reading it here
+    // keeps the hydration render consistent with the server HTML.
+    // See design/29-cookies.md §"SSR Hydration".
+    return getCookieValue(name);
+  };
 
-  const value = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+  const value = React.useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+
+  // Validate the name once per hook instance — names are typically
+  // stable string literals, so this catches the bug at first render
+  // rather than on every write. Throws via `assertValidCookieName` with
+  // a precise error if the name violates RFC 7230 token rules.
+  assertValidCookieName(name);
 
   const setCookie: CookieSetter = (newValue: string, options?: ClientCookieOptions) => {
+    if (typeof newValue !== 'string') {
+      throw new Error(
+        `[timber] useCookie(${JSON.stringify(name)}): value must be a string, got ${typeof newValue}.\n` +
+          `  To store a JSON-serializable value, use defineCookie + jsonCookieCodec from\n` +
+          `  '@timber-js/app/cookies' and call its useCookie() hook instead.`
+      );
+    }
     const merged = { ...defaultOptions, ...options };
+    // Auto-encode mirrors the server's `cookies().set()` contract:
+    // values are URL-encoded on write, URL-decoded on read, so the
+    // logical bytes round-trip losslessly. See design/29-cookies.md
+    // §"Encoding Contract".
     document.cookie = `${name}=${encodeURIComponent(newValue)}${serializeOptions(merged)}`;
     notify(name);
   };

package/src/client/use-link-status.ts

@@ -1,26 +1,26 @@
 'use client';
 
-// useLinkStatus — returns { pending: true } while the nearest parent <Link>'s
+// useLinkStatus — returns { isPending: true } while the nearest parent <Link>'s
 // navigation is in flight. No arguments — scoped via React context.
 // See design/19-client-navigation.md §"useLinkStatus()"
 
 import { useContext, createContext } from 'react';
 
 export interface LinkStatus {
-  pending: boolean;
+  isPending: boolean;
 }
 
 /**
  * React context provided by <Link>. Holds the pending status
  * for that specific link's navigation.
  */
-export const LinkStatusContext = createContext<LinkStatus>({ pending: false });
+export const LinkStatusContext = createContext<LinkStatus>({ isPending: false });
 
 /**
- * Returns `{ pending: true }` while the nearest parent `<Link>` component's
+ * Returns `{ isPending: true }` while the nearest parent `<Link>` component's
  * navigation is in flight. Must be used inside a `<Link>` component's children.
  *
- * Unlike `useNavigationPending()` which is global, this hook is scoped to
+ * Unlike `usePendingNavigation()` which is global, this hook is scoped to
  * the nearest parent `<Link>` — only the link the user clicked shows pending.
  *
  * ```tsx
@@ -28,8 +28,8 @@ export const LinkStatusContext = createContext<LinkStatus>({ pending: false });
  * import { Link, useLinkStatus } from '@timber-js/app/client'
  *
  * function Hint() {
- *   const { pending } = useLinkStatus()
- *   return <span className={pending ? 'opacity-50' : ''} />
+ *   const { isPending } = useLinkStatus()
+ *   return <span className={isPending ? 'opacity-50' : ''} />
  * }
  *
  * export function NavLink({ href, children }) {

package/src/client/use-pathname.ts

@@ -31,6 +31,7 @@ export function usePathname(): string {
   // Try reading from NavigationContext (client-side, inside React tree).
   // During SSR, no NavigationProvider is mounted, so this returns null.
   try {
+    // eslint-disable-next-line react-hooks/rules-of-hooks -- conditional on environment, not render path
     const navContext = useNavigationContext();
     if (navContext !== null) {
       return navContext.pathname;

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

@@ -0,0 +1,40 @@
+import { useSyncExternalStore } from 'react';
+import { getRouterOrNull } from './router-ref.js';
+
+function subscribe(onStoreChange: () => void): () => void {
+  const router = getRouterOrNull();
+  if (!router) return () => {};
+  return router.onPendingChange(onStoreChange);
+}
+
+function getSnapshot(): boolean {
+  const router = getRouterOrNull();
+  return router ? router.isPending() : false;
+}
+
+const getServerSnapshot = getSnapshot;
+
+/**
+ * Returns true while an RSC navigation is in flight.
+ *
+ * Reads from the router's external pending store via useSyncExternalStore.
+ * Only components that call this hook re-render when pending state
+ * changes — no full-tree re-render.
+ *
+ * ```tsx
+ * 'use client'
+ * import { usePendingNavigation } from '@timber-js/app/client'
+ *
+ * export function NavBar() {
+ *   const isPending = usePendingNavigation()
+ *   return (
+ *     <nav className={isPending ? 'opacity-50' : ''}>
+ *       <Link href="/dashboard">Dashboard</Link>
+ *     </nav>
+ *   )
+ * }
+ * ```
+ */
+export function usePendingNavigation(): boolean {
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}