@timber-js/app 0.1.29 → 0.1.31

package/dist/plugins/chunks.d.ts

@@ -3,9 +3,16 @@
  *
  * Splits client bundles into cache tiers based on update frequency:
  *
- * Tier 1: vendor-react  — react, react-dom, scheduler (changes rarely)
- * Tier 2: vendor-timber — timber runtime, RSC runtime (changes per framework update)
- * Tier 3: [route]-*     — per-route app code (changes per deploy, handled by Vite defaults)
+ * Tier 1: vendor-react    — react, react-dom, scheduler (changes rarely)
+ * Tier 2: vendor-timber   — timber runtime, RSC runtime (changes per framework update)
+ * Tier 3: vendor-app      — user node_modules (changes on dependency updates)
+ * Tier 4: shared-app      — small shared app utilities/components (< 5KB source)
+ * Tier 5: [route]-*       — per-route page/layout chunks (default Rollup splitting)
+ *
+ * The shared-app tier prevents tiny utility modules (constants, helpers,
+ * small UI components) from becoming individual chunks when shared across
+ * routes. Without this, Rolldown creates per-module chunks for any code
+ * shared between two or more entry points, producing many sub-1KB chunks.
  *
  * Server environments (RSC, SSR) are left to Vite's default chunking since
  * Cloudflare Workers load all code from a single deployment bundle with no
@@ -17,8 +24,8 @@ import type { Plugin } from 'vite';
 /**
  * Categorize a module ID into a cache tier chunk name.
  *
- * Returns a chunk name for vendor modules, or undefined to let
- * Rollup's default splitting handle app/route code.
+ * Returns a chunk name for vendor modules and small shared app code,
+ * or undefined to let Rollup's default splitting handle route code.
  */
 export declare function assignChunk(id: string): string | undefined;
 /**
@@ -27,7 +34,11 @@ export declare function assignChunk(id: string): string | undefined;
  * The RSC plugin creates separate entry points for each 'use client' module,
  * which manualChunks can't merge. This function is passed as the RSC plugin's
  * `clientChunks` callback to group timber internals into a single chunk.
- * User and third-party client components are left to default per-route splitting.
+ *
+ * User client components that are small (< 5KB) are grouped into shared-client
+ * to prevent thin facade wrappers from becoming individual chunks. This handles
+ * the RSC client reference facade problem where each 'use client' module gets
+ * a ~100-300 byte re-export wrapper chunk.
  */
 export declare function assignClientChunk(meta: {
     id: string;

package/dist/plugins/chunks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunks.d.ts","sourceRoot":"","sources":["../../src/plugins/chunks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAoB1D;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,MAAM,GAAG,SAAS,CAErB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAoBrC"}
+{"version":3,"file":"chunks.d.ts","sourceRoot":"","sources":["../../src/plugins/chunks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAmGnC;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CA4B1D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,MAAM,GAAG,SAAS,CAarB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAoBrC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "description": "Vite-native React framework for Cloudflare Workers — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",

package/src/client/browser-entry.ts

@@ -52,7 +52,7 @@ import { isPageUnloading } from './unload-guard.js';
 import { NavigationProvider, getNavigationState, setNavigationState } from './navigation-context.js';
 import { setupServerLogReplay, setupClientErrorForwarding } from './browser-dev.js';
 import { handleLinkClick, handleLinkHover } from './browser-links.js';
-import { TransitionRoot, transitionRender } from './transition-root.js';
+import { TransitionRoot, transitionRender, navigateTransition } from './transition-root.js';
 
 // ─── Server Action Dispatch ──────────────────────────────────────
 
@@ -368,22 +368,12 @@ function bootstrap(runtimeConfig: typeof config): void {
       },
 
       // Render decoded RSC tree via TransitionRoot's state-based mechanism.
-      // Wraps with NavigationProvider (for atomic useParams/usePathname updates)
-      // and TimberNuqsAdapter (for nuqs context).
+      // Used for non-navigation renders (popstate cached replay, applyRevalidation).
+      // Wraps with NavigationProvider + TimberNuqsAdapter.
       //
-      // The router calls setNavigationState() before renderRoot(), so
-      // getNavigationState() returns the new params/pathname. By wrapping
-      // the element in NavigationProvider here, the context value and the
-      // RSC tree are passed to startTransition(() => setState()) in the same
-      // call — making the update atomic. Preserved layout components that call
-      // useParams() or usePathname() re-render in the same pass as the
-      // new tree, preventing the dual-active-state flash.
-      //
-      // Using transitionRender instead of reactRoot.render() enables
-      // client-side Suspense deferral: React keeps the old committed tree
-      // visible while new Suspense boundaries in the navigation resolve.
-      // This is the client-side equivalent of deferSuspenseFor on the server.
-      // See design/05-streaming.md.
+      // 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();
         const withNav = createElement(NavigationProvider, { value: navState }, element as React.ReactNode);
@@ -391,6 +381,26 @@ function bootstrap(runtimeConfig: typeof config): void {
         transitionRender(wrapped);
       },
 
+      // Run a navigation inside a React transition with optimistic pending URL.
+      // The entire fetch + state update runs inside startTransition. useOptimistic
+      // shows the pending URL immediately and reverts to null when the transition
+      // 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).
+      navigateTransition: (pendingUrl: string, perform) => {
+        return navigateTransition(pendingUrl, async () => {
+          const payload = await perform((rawPayload: unknown) => {
+            const navState = getNavigationState();
+            const withNav = createElement(NavigationProvider, { value: navState }, rawPayload as React.ReactNode);
+            return createElement(TimberNuqsAdapter, null, withNav);
+          });
+          return payload as React.ReactNode;
+        });
+      },
+
       // Schedule a callback after the next paint so scroll operations
       // happen after React commits the new content to the DOM.
       // Double-rAF ensures the browser has painted the new frame.

package/src/client/link-status-provider.tsx

@@ -2,39 +2,29 @@
 
 // LinkStatusProvider — client component that provides per-link pending status
 // via React context. Used inside <Link> to power useLinkStatus().
+//
+// Reads pendingUrl from PendingNavigationContext (provided by TransitionRoot).
+// The pending URL is set as an URGENT update at navigation start (shows
+// immediately) and cleared inside startTransition when the new tree commits
+// (atomic with params/pathname). This eliminates both:
+// 1. The delay before showing the spinner (urgent update, not deferred)
+// 2. The gap between spinner disappearing and active state updating (same commit)
 
-import { useSyncExternalStore, type ReactNode } from 'react';
+import type { ReactNode } from 'react';
 import { LinkStatusContext, type LinkStatus } from './use-link-status.js';
-import { getRouter } from './router-ref.js';
+import { usePendingNavigationUrl } from './pending-navigation-context.js';
 
 const NOT_PENDING: LinkStatus = { pending: false };
 const IS_PENDING: LinkStatus = { pending: true };
 
 /**
- * Client component that subscribes to the router's pending URL and provides
- * a scoped LinkStatusContext to children. Renders no extra DOM — just a
- * context provider around children.
+ * Client component that reads the pending URL from PendingNavigationContext
+ * and provides a scoped LinkStatusContext to children. Renders no extra DOM —
+ * just a context provider around children.
  */
 export function LinkStatusProvider({ href, children }: { href: string; children: ReactNode }) {
-  const status = useSyncExternalStore(
-    (callback) => {
-      try {
-        return getRouter().onPendingChange(callback);
-      } catch {
-        return () => {};
-      }
-    },
-    () => {
-      try {
-        const pendingUrl = getRouter().getPendingUrl();
-        if (pendingUrl === href) return IS_PENDING;
-        return NOT_PENDING;
-      } catch {
-        return NOT_PENDING;
-      }
-    },
-    () => NOT_PENDING
-  );
+  const pendingUrl = usePendingNavigationUrl();
+  const status = pendingUrl === href ? IS_PENDING : NOT_PENDING;
 
   return <LinkStatusContext.Provider value={status}>{children}</LinkStatusContext.Provider>;
 }

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

@@ -0,0 +1,66 @@
+/**
+ * PendingNavigationContext — React context for the in-flight navigation URL.
+ *
+ * Provided by TransitionRoot. The value is the URL being navigated to,
+ * or null when idle. Used by:
+ * - LinkStatusProvider to show per-link pending spinners
+ * - useNavigationPending to return a global pending boolean
+ *
+ * The pending URL is set as an URGENT update (shows immediately) and
+ * cleared inside startTransition (commits atomically with the new tree).
+ * This ensures pending state appears instantly on navigation start and
+ * disappears in the same React commit as the new params/tree.
+ *
+ * Separate from NavigationContext (which holds params + pathname) because
+ * the pending URL is managed as React state in TransitionRoot, while
+ * params/pathname are set via module-level state read by renderRoot.
+ * Both contexts commit together in the same transition.
+ *
+ * See design/19-client-navigation.md §"NavigationContext"
+ */
+
+import React, { createElement, type ReactNode } from 'react';
+
+// ---------------------------------------------------------------------------
+// Lazy context initialization (same pattern as NavigationContext)
+// ---------------------------------------------------------------------------
+
+let _context: React.Context<string | null> | undefined;
+
+function getOrCreateContext(): React.Context<string | null> | undefined {
+  if (_context !== undefined) return _context;
+  if (typeof React.createContext === 'function') {
+    _context = React.createContext<string | null>(null);
+  }
+  return _context;
+}
+
+/**
+ * Read the pending navigation URL from context.
+ * Returns null during SSR (no provider) or in the RSC environment.
+ * Internal — used by LinkStatusProvider and useNavigationPending.
+ */
+export function usePendingNavigationUrl(): string | null {
+  const ctx = getOrCreateContext();
+  if (!ctx) return null;
+  if (typeof React.useContext !== 'function') return null;
+  return React.useContext(ctx);
+}
+
+// ---------------------------------------------------------------------------
+// Provider component
+// ---------------------------------------------------------------------------
+
+export function PendingNavigationProvider({
+  value,
+  children,
+}: {
+  value: string | null;
+  children?: ReactNode;
+}): React.ReactElement {
+  const ctx = getOrCreateContext();
+  if (!ctx) {
+    return children as React.ReactElement;
+  }
+  return createElement(ctx.Provider, { value }, children);
+}

package/src/client/router.ts

@@ -54,6 +54,21 @@ export interface RouterDeps {
   afterPaint?: (callback: () => void) => void;
   /** Apply resolved head elements (title, meta tags) to the DOM after navigation. */
   applyHead?: (elements: HeadElement[]) => void;
+  /**
+   * Run a navigation inside a React transition with optimistic pending URL.
+   * The pending URL shows immediately (useOptimistic urgent update) and
+   * reverts when the transition commits (atomic with the new tree).
+   *
+   * The `perform` callback receives a `wrapPayload` function to wrap the
+   * decoded RSC payload with NavigationProvider + NuqsAdapter before
+   * TransitionRoot sets it as the new element.
+   *
+   * If not provided (tests), the router falls back to renderRoot.
+   */
+  navigateTransition?: (
+    pendingUrl: string,
+    perform: (wrapPayload: (payload: unknown) => unknown) => Promise<unknown>,
+  ) => Promise<void>;
 }
 
 /** Result of fetching an RSC payload — includes head elements and segment metadata. */
@@ -304,6 +319,9 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     if (pending === value && pendingUrl === newPendingUrl) return;
     pending = value;
     pendingUrl = newPendingUrl;
+    // Notify external store listeners (non-React consumers).
+    // React-facing pending state is handled by useOptimistic in
+    // TransitionRoot via navigateTransition — not this function.
     for (const listener of pendingListeners) {
       listener(value);
     }
@@ -347,6 +365,31 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     setNavigationState({ params: resolvedParams, pathname });
   }
 
+  /**
+   * Render a payload via navigateTransition (production) or renderRoot (tests).
+   * The perform callback should fetch data, update state, and return the payload.
+   * In production, the entire callback runs inside a React transition with
+   * useOptimistic for the pending URL. In tests, the payload is rendered directly.
+   */
+  async function renderViaTransition(
+    pendingUrl: string,
+    perform: () => Promise<FetchResult>,
+  ): Promise<HeadElement[] | null> {
+    if (deps.navigateTransition) {
+      let headElements: HeadElement[] | null = null;
+      await deps.navigateTransition(pendingUrl, async (wrapPayload) => {
+        const result = await perform();
+        headElements = result.headElements;
+        return wrapPayload(result.payload);
+      });
+      return headElements;
+    }
+    // Fallback: no transition (tests, no React tree)
+    const result = await perform();
+    renderPayload(result.payload);
+    return result.headElements;
+  }
+
   /** Apply head elements (title, meta tags) to the DOM if available. */
   function applyHead(elements: HeadElement[] | null | undefined): void {
     if (elements && deps.applyHead) {
@@ -363,6 +406,60 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     }
   }
 
+  /**
+   * Core navigation logic shared between the transition and fallback paths.
+   * Fetches the RSC payload, updates all state, and returns the result.
+   */
+  async function performNavigationFetch(
+    url: string,
+    options: { replace: boolean },
+  ): Promise<FetchResult> {
+    // Check prefetch cache first. PrefetchResult has optional segmentInfo/params
+    // fields — normalize to null for FetchResult compatibility.
+    const prefetched = prefetchCache.consume(url);
+    let result: FetchResult | undefined = prefetched
+      ? {
+          payload: prefetched.payload,
+          headElements: prefetched.headElements,
+          segmentInfo: prefetched.segmentInfo ?? null,
+          params: prefetched.params ?? null,
+        }
+      : undefined;
+
+    if (result === undefined) {
+      // Fetch RSC payload with state tree for partial rendering.
+      // Send current URL for intercepting route resolution (modal pattern).
+      const stateTree = segmentCache.serializeStateTree();
+      const rawCurrentUrl = deps.getCurrentUrl();
+      const currentUrl = rawCurrentUrl.startsWith('http')
+        ? new URL(rawCurrentUrl).pathname
+        : new URL(rawCurrentUrl, 'http://localhost').pathname;
+      result = await fetchRscPayload(url, deps, stateTree, currentUrl);
+    }
+
+    // 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);
+    }
+
+    // Store the payload in the history stack
+    historyStack.push(url, {
+      payload: result.payload,
+      headElements: result.headElements,
+      params: result.params,
+    });
+
+    // Update the segment cache with the new route's segment tree.
+    updateSegmentCache(result.segmentInfo);
+
+    // Update navigation state (params + pathname) before rendering.
+    updateNavigationState(result.params, url);
+
+    return result;
+  }
+
   async function navigate(url: string, options: NavigationOptions = {}): Promise<void> {
     const scroll = options.scroll !== false;
     const replace = options.replace === true;
@@ -378,54 +475,14 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     setPending(true, url);
 
     try {
-      // Check prefetch cache first
-      let result = prefetchCache.consume(url);
-
-      if (result === undefined) {
-        // Fetch RSC payload with state tree for partial rendering.
-        // Send current URL for intercepting route resolution (modal pattern).
-        const stateTree = segmentCache.serializeStateTree();
-        const rawCurrentUrl = deps.getCurrentUrl();
-        const currentUrl = rawCurrentUrl.startsWith('http')
-          ? new URL(rawCurrentUrl).pathname
-          : new URL(rawCurrentUrl, 'http://localhost').pathname;
-        result = await fetchRscPayload(url, deps, stateTree, currentUrl);
-      }
-
-      // Update the browser history — replace mode overwrites the current entry
-      if (replace) {
-        deps.replaceState({ timber: true, scrollY: 0 }, '', url);
-      } else {
-        deps.pushState({ timber: true, scrollY: 0 }, '', url);
-      }
-
-      // Store the payload in the history stack
-      historyStack.push(url, {
-        payload: result.payload,
-        headElements: result.headElements,
-        params: result.params,
-      });
-
-      // Update the segment cache with the new route's segment tree.
-      // This must happen before the next navigation so the state tree
-      // header reflects the currently mounted segments.
-      updateSegmentCache(result.segmentInfo);
-
-      // Update navigation state (params + pathname) before rendering.
-      // The renderRoot callback reads this state and wraps the RSC element
-      // in NavigationProvider — so the context value and the element tree
-      // are passed to reactRoot.render() in the same call, making the
-      // update atomic. Preserved layouts see new params in the same render
-      // pass as the new tree, preventing the dual-active-row flash.
-      updateNavigationState(result.params, url);
-      renderPayload(result.payload);
+      const headElements = await renderViaTransition(url, () =>
+        performNavigationFetch(url, { replace }),
+      );
 
       // Update document.title and <meta> tags with the new page's metadata
-      applyHead(result.headElements);
+      applyHead(headElements);
 
       // Notify nuqs adapter (and any other listeners) that navigation completed.
-      // The nuqs adapter syncs its searchParams state from window.location.search
-      // on this event so URL-bound inputs reflect the new URL after navigation.
       window.dispatchEvent(new Event('timber:navigation-end'));
 
       // Scroll-to-top on forward navigation, or restore captured position
@@ -441,17 +498,12 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       });
     } catch (error) {
       // Server-side redirect during RSC fetch → soft router navigation.
-      // access.ts called redirect() — the server returns X-Timber-Redirect
-      // header, and fetchRscPayload throws RedirectError. We re-navigate
-      // to the redirect target using the router for a seamless SPA transition.
       if (error instanceof RedirectError) {
         setPending(false);
         await navigate(error.redirectUrl, { replace: true });
         return;
       }
-      // Abort errors from the fetch (user refreshed or navigated away
-      // while the RSC payload was loading) are not application errors.
-      // Swallow them silently — the page is being replaced.
+      // Abort errors are not application errors — swallow silently.
       if (isAbortError(error)) return;
       throw error;
     } finally {
@@ -465,23 +517,20 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     setPending(true, currentUrl);
 
     try {
-      // No state tree sent — server renders the complete RSC payload
-      const result = await fetchRscPayload(currentUrl, deps);
-
-      // Update the history entry with the fresh payload
-      historyStack.push(currentUrl, {
-        payload: result.payload,
-        headElements: result.headElements,
-        params: result.params,
+      const headElements = await renderViaTransition(currentUrl, async () => {
+        // No state tree sent — server renders the complete RSC payload
+        const result = await fetchRscPayload(currentUrl, deps);
+        historyStack.push(currentUrl, {
+          payload: result.payload,
+          headElements: result.headElements,
+          params: result.params,
+        });
+        updateSegmentCache(result.segmentInfo);
+        updateNavigationState(result.params, currentUrl);
+        return result;
       });
 
-      // Update segment cache with fresh segment info from full render
-      updateSegmentCache(result.segmentInfo);
-
-      // Atomic update — see navigate() for rationale on NavigationProvider.
-      updateNavigationState(result.params, currentUrl);
-      renderPayload(result.payload);
-      applyHead(result.headElements);
+      applyHead(headElements);
     } finally {
       setPending(false);
     }
@@ -509,17 +558,20 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // or when the entry doesn't exist at all.
       setPending(true, url);
       try {
-        const stateTree = segmentCache.serializeStateTree();
-        const result = await fetchRscPayload(url, deps, stateTree);
-        updateSegmentCache(result.segmentInfo);
-        updateNavigationState(result.params, url);
-        historyStack.push(url, {
-          payload: result.payload,
-          headElements: result.headElements,
-          params: result.params,
+        const headElements = await renderViaTransition(url, async () => {
+          const stateTree = segmentCache.serializeStateTree();
+          const result = await fetchRscPayload(url, deps, stateTree);
+          updateSegmentCache(result.segmentInfo);
+          updateNavigationState(result.params, url);
+          historyStack.push(url, {
+            payload: result.payload,
+            headElements: result.headElements,
+            params: result.params,
+          });
+          return result;
         });
-        renderPayload(result.payload);
-        applyHead(result.headElements);
+
+        applyHead(headElements);
         afterPaint(() => {
           deps.scrollTo(0, scrollY);
           window.dispatchEvent(new Event('timber:scroll-restored'));