@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.181

package/src/client/segment-outlet.tsx

@@ -0,0 +1,141 @@
+/**
+ * SegmentOutlet — client component boundary at each layout segment.
+ *
+ * Each layout in the segment tree is wrapped with a SegmentOutlet that:
+ * 1. Knows its segment path (prop from the server)
+ * 2. Reads from SegmentUpdateContext for partial navigation updates
+ * 3. Caches its rendered content in a ref across navigations
+ *
+ * On full navigation: receives new children via props, caches and renders them.
+ * On partial navigation (this segment skipped): the context map has no entry
+ * for this path, so the outlet returns cached content — preserving layout state.
+ * On partial navigation (this segment updated): the context map has content
+ * for this path, so the outlet renders the update.
+ *
+ * Uses React context instead of useSyncExternalStore to stay compatible
+ * with concurrent rendering (transitions). All outlets re-render when the
+ * context value changes, but each bails out quickly if its segment has
+ * no update — same approach as Next.js LayoutRouter.
+ *
+ * Security: performance optimization only. The server always runs all
+ * access.ts files regardless of segment skipping.
+ * See design/13-security.md §"State tree manipulation".
+ */
+
+'use client';
+
+import { useContext, useRef, type ReactNode } from 'react';
+import { SegmentUpdateContext } from './segment-update-context.js';
+
+export interface SegmentOutletProps {
+  /**
+   * Unique identifier for this segment. For normal segments this is the
+   * urlPath (e.g., "/", "/dashboard"). For route groups this includes the
+   * group name (e.g., "/(marketing)") to distinguish siblings that share
+   * the same urlPath. For slots this includes the slot name (e.g., "/@sidebar").
+   * Must match the segmentId used in state-tree-diff.ts.
+   */
+  segmentPath: string;
+
+  /** The segment's React subtree (layout + inner content). */
+  children: ReactNode;
+
+  /**
+   * When true, the outlet returns cached content instead of rendering
+   * new children. Used for skipped parallel route slots — the server
+   * sends an empty SegmentOutlet with skip=true, and the client keeps
+   * the previously cached slot content.
+   */
+  skip?: boolean;
+}
+
+// ─── Slot Content Cache ──────────────────────────────────────────
+// Persists slot content across SegmentOutlet fiber lifecycles.
+// When React creates new fibers during full navigation (e.g., the
+// server sends a complete new tree and React remounts the subtree),
+// useRef starts fresh with null. Skipped slots (skip=true, children=null)
+// would lose their cached content because contentRef.current is null.
+//
+// This globalThis-backed Map provides a fallback: SegmentOutlet stores
+// rendered content here whenever it renders non-null slot content, and
+// reads from it when skip=true but contentRef.current is null.
+//
+// Uses globalThis + Symbol.for for singleton guarantee across chunks —
+// same pattern as NavigationContext and SegmentUpdateContext.
+//
+// SSR safety: SegmentOutlet is 'use client' — during RSC rendering it's
+// serialized as a client reference and never executed. During SSR
+// (renderToReadableStream), the component IS executed but skip=true is
+// never sent (the server always renders full content). The cache may
+// accumulate entries during SSR but they're harmless — the skip=true
+// fallback path only activates on the client during SPA navigation.
+
+const SLOT_CACHE_KEY = Symbol.for('__timber_slot_content_cache');
+
+function getSlotContentCache(): Map<string, ReactNode> {
+  const g = globalThis as Record<symbol, unknown>;
+  if (!g[SLOT_CACHE_KEY]) {
+    g[SLOT_CACHE_KEY] = new Map<string, ReactNode>();
+  }
+  return g[SLOT_CACHE_KEY] as Map<string, ReactNode>;
+}
+
+/**
+ * Client component boundary at each layout segment in the element tree.
+ *
+ * On full navigation (context map is empty): renders children, caches in ref.
+ * On partial navigation: checks the context map for an update at segmentPath.
+ *   - Update found → renders update, caches in ref.
+ *   - No update → returns cached content (layout state preserved).
+ *
+ * React preserves component instances across reactRoot.render() calls
+ * when the same type appears at the same tree position. The ref persists
+ * across navigations because SegmentOutlet is reconciled, not remounted.
+ */
+export function SegmentOutlet({ segmentPath, children, skip }: SegmentOutletProps) {
+  const updates = useContext(SegmentUpdateContext);
+  const contentRef = useRef<ReactNode>(null);
+  const slotCache = getSlotContentCache();
+
+  const update = updates.get(segmentPath);
+
+  if (update !== undefined) {
+    contentRef.current = update;
+    slotCache.set(segmentPath, update);
+    return update;
+  }
+
+  // Skipped slot: keep cached content. The server sends skip=true for
+  // parallel route slots whose matched content hasn't changed. React
+  // reconciles this SegmentOutlet with the previous one at the same
+  // tree position, so the ref (cached content) is preserved.
+  if (skip) {
+    if (contentRef.current !== null) {
+      return contentRef.current;
+    }
+    // Fiber was remounted (contentRef is fresh null). Fall back to the
+    // globalThis-backed cache which persists across fiber lifecycles.
+    if (slotCache.has(segmentPath)) {
+      const cached = slotCache.get(segmentPath)!;
+      contentRef.current = cached;
+      return cached;
+    }
+    // No cached content anywhere — the SegmentOutlet instance is fresh
+    // and no prior render has populated the cache. Fall through to render
+    // children (null). The slot will be fully rendered next navigation.
+  }
+
+  if (contentRef.current === null) {
+    contentRef.current = children;
+    slotCache.set(segmentPath, children);
+    return children;
+  }
+
+  if (children !== contentRef.current) {
+    contentRef.current = children;
+    slotCache.set(segmentPath, children);
+    return children;
+  }
+
+  return contentRef.current;
+}

package/src/client/segment-update-context.ts

@@ -0,0 +1,42 @@
+/**
+ * SegmentUpdateContext — React context for partial navigation updates.
+ *
+ * During partial navigation (server skips unchanged sync layouts), the
+ * router builds a Map of segment path → ReactNode updates and passes it
+ * as the context value. Mounted SegmentOutlet components read from this
+ * context to decide whether to render the update or their cached content.
+ *
+ * SINGLETON GUARANTEE: Uses globalThis + Symbol.for — same pattern as
+ * NavigationContext. The RSC client bundler can duplicate this module
+ * across chunks (browser-entry graph + client-reference graph). With
+ * ESM output, each chunk gets its own module scope — a bare createContext
+ * at module level would create separate instances per chunk. globalThis
+ * guarantees a single instance regardless of duplication.
+ *
+ * See design/19-client-navigation.md §"Singleton Guarantee via globalThis"
+ */
+
+'use client';
+
+import React, { type ReactNode } from 'react';
+
+export const EMPTY_SEGMENT_UPDATES = new Map<string, ReactNode>();
+
+const CTX_KEY = Symbol.for('__timber_segment_update_ctx');
+
+function getOrCreateContext(): React.Context<Map<string, ReactNode>> {
+  const existing = (globalThis as Record<symbol, unknown>)[CTX_KEY] as
+    | React.Context<Map<string, ReactNode>>
+    | undefined;
+  if (existing !== undefined) return existing;
+  if (typeof React.createContext === 'function') {
+    const ctx = React.createContext<Map<string, ReactNode>>(EMPTY_SEGMENT_UPDATES);
+    (globalThis as Record<symbol, unknown>)[CTX_KEY] = ctx;
+    return ctx;
+  }
+  // RSC environment — createContext not available. Return a dummy that
+  // won't be used (outlets only render on the client).
+  return undefined as unknown as React.Context<Map<string, ReactNode>>;
+}
+
+export const SegmentUpdateContext = getOrCreateContext();

package/src/client/shallow-url.ts

@@ -0,0 +1,22 @@
+/**
+ * Shallow URL replacement — update the browser URL bar without triggering
+ * RSC navigation, TopLoader, or any server round-trip.
+ *
+ * Uses the Navigation API's `info: { shallow: true }` when available (Chrome),
+ * which the navigate event handler intercepts with a no-op handler. Falls back
+ * to raw `history.replaceState` (Safari/Firefox — no navigate event fired).
+ */
+
+import { getNavigationApi } from './navigation-api.js';
+
+export function replaceUrl(url: string): void {
+  const nav = getNavigationApi();
+  if (nav) {
+    nav.navigate(url, {
+      history: 'replace',
+      info: { shallow: true },
+    });
+  } else {
+    history.replaceState(history.state, '', url);
+  }
+}

package/src/client/slot-context.ts

@@ -0,0 +1,50 @@
+/**
+ * SlotContext — delivers live slot content to SlotOutlet holes inside
+ * cached component shells (TIM-1173).
+ *
+ * A `cache.component(Fn, { slots: [...] })` shell is captured with a
+ * stable <SlotOutlet slot={name} /> client reference in place of each
+ * declared slot prop. At request time the revived shell is wrapped in a
+ * SlotsProvider carrying the live slot values; each outlet reads its
+ * value from this context by name.
+ *
+ * Providers MERGE per-key with their parent: an inner SlotsProvider
+ * inherits the outer's values and overrides only the keys it declares.
+ * Two sibling instances each have their own provider and resolve
+ * independently. Layouts use a reserved slot name (LAYOUT_CHILDREN_SLOT)
+ * that cannot collide with user-declared slot names (TIM-1191).
+ *
+ * Generalizes the original layout children pattern (TIM-1181) from a
+ * single implicit `children` hole on layouts to explicitly declared,
+ * named slot props on any cached component. Layouts use this same
+ * context with the reserved LAYOUT_CHILDREN_SLOT key (TIM-1191).
+ *
+ * SINGLETON GUARANTEE: globalThis + Symbol.for — the RSC client bundler
+ * can duplicate this module across chunks; globalThis guarantees a single
+ * context instance.
+ *
+ * See design/45-cache-lifetimes.md §Slot Components.
+ */
+
+'use client';
+
+import React, { type ReactNode } from 'react';
+
+export type SlotValues = Record<string, ReactNode>;
+
+const CTX_KEY = Symbol.for('__timber_slot_ctx');
+
+function getOrCreateContext(): React.Context<SlotValues | null> {
+  const existing = (globalThis as Record<symbol, unknown>)[CTX_KEY] as
+    | React.Context<SlotValues | null>
+    | undefined;
+  if (existing !== undefined) return existing;
+  if (typeof React.createContext === 'function') {
+    const ctx = React.createContext<SlotValues | null>(null);
+    (globalThis as Record<symbol, unknown>)[CTX_KEY] = ctx;
+    return ctx;
+  }
+  return undefined as unknown as React.Context<SlotValues | null>;
+}
+
+export const SlotContext = getOrCreateContext();

package/src/client/slot-outlet.tsx

@@ -0,0 +1,22 @@
+/**
+ * SlotOutlet — the hole in a cached component shell (TIM-1173).
+ *
+ * At capture time the prebuilt runtime renders the wrapped component with
+ * <SlotOutlet slot={name} /> in place of each declared slot prop. Being a
+ * client component, it serializes into the flight payload as a stable,
+ * deterministic client reference — the same bytes regardless of what live
+ * content will fill the hole. At request time the revived shell sits under
+ * a SlotsProvider and each outlet reads its live value from SlotContext.
+ *
+ * See design/45-cache-lifetimes.md §Slot Components.
+ */
+
+'use client';
+
+import { useContext } from 'react';
+import { SlotContext } from './slot-context.js';
+
+export function SlotOutlet({ slot }: { slot: string }) {
+  const values = useContext(SlotContext);
+  return values ? (values[slot] ?? null) : null;
+}

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

@@ -41,12 +41,20 @@ export interface SsrData {
   /** The request's route params (e.g. { id: '123' }) */
   params: Record<string, string | string[]>;
   /**
-   * 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.
+   * 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?: { _denyHandledByBoundary?: boolean };
+  _navContext?: { statusCode?: number; _denyHandledByBoundary?: boolean };
 }
 
 // ─── ALS-Backed Provider ─────────────────────────────────────────

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
@@ -50,7 +50,7 @@ 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[]> = {};

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,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:
@@ -111,8 +111,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/use-cookie.ts

@@ -9,7 +9,9 @@
  */
 
 import { useSyncExternalStore } from 'react';
+import { parseCookie, stringifySetCookie } from 'cookie';
 import { getSsrData } from './ssr-data.js';
+import { assertValidCookieName } from '../cookies/validation.js';
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -38,26 +40,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 +75,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 +117,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);
 
+  // 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);
+}