@timber-js/app 0.1.29 → 0.1.31

package/src/client/transition-root.tsx

@@ -11,65 +11,105 @@
  * a transition update. React keeps the old committed tree visible while
  * any new Suspense boundaries in the transition resolve.
  *
- * This is the client-side equivalent of deferSuspenseFor on the server:
- * the old content stays visible until the new content is ready, avoiding
- * flash-of-fallback during fast navigations.
+ * Also manages `pendingUrl` via `useOptimistic`. During a navigation
+ * transition, the optimistic value (the target URL) shows immediately
+ * while the transition is pending, and automatically reverts to null
+ * when the transition commits. This ensures useLinkStatus and
+ * useNavigationPending show the pending state immediately and clear
+ * atomically with the new tree — same pattern Next.js uses with
+ * useOptimistic per Link instance, adapted for timber's server-component
+ * Link with global click delegation.
  *
  * See design/05-streaming.md §"deferSuspenseFor"
+ * See design/19-client-navigation.md §"NavigationContext"
  */
 
-import { useState, startTransition, type ReactNode } from 'react';
+import {
+  useState,
+  useOptimistic,
+  startTransition,
+  createElement,
+  type ReactNode,
+} from 'react';
+import { PendingNavigationProvider } from './pending-navigation-context.js';
 
-// ─── Module-level render function ────────────────────────────────
+// ─── Module-level functions ──────────────────────────────────────
 
 /**
  * Module-level reference to the state setter wrapped in startTransition.
- * Set during TransitionRoot's render. This is safe because there is
- * exactly one TransitionRoot per application (the document root).
+ * Used for non-navigation renders (applyRevalidation, popstate replay).
  */
 let _transitionRender: ((element: ReactNode) => void) | null = null;
 
+/**
+ * Module-level reference to the navigation transition function.
+ * Wraps a full navigation (fetch + render) in a single startTransition
+ * with useOptimistic for the pending URL.
+ */
+let _navigateTransition: ((
+  pendingUrl: string,
+  perform: () => Promise<ReactNode>,
+) => Promise<void>) | null = null;
+
 // ─── Component ───────────────────────────────────────────────────
 
 /**
  * Root wrapper component that enables transition-based rendering.
  *
- * Renders no DOM elements — returns the current element directly.
- * This means the DOM tree matches the server-rendered HTML during
- * hydration (TransitionRoot is invisible to the DOM).
+ * Renders PendingNavigationProvider around children for the pending URL
+ * context. The DOM tree matches the server-rendered HTML during hydration
+ * (the provider renders no extra DOM elements).
  *
  * Usage in browser-entry.ts:
  *   const rootEl = createElement(TransitionRoot, { initial: wrapped });
  *   reactRoot = hydrateRoot(document, rootEl);
  *
  * Subsequent navigations:
+ *   navigateTransition(url, async () => { fetch; return wrappedElement; });
+ *
+ * Non-navigation renders:
  *   transitionRender(newWrappedElement);
  */
 export function TransitionRoot({ initial }: { initial: ReactNode }): ReactNode {
   const [element, setElement] = useState<ReactNode>(initial);
+  const [optimisticPendingUrl, setOptimisticPendingUrl] = useOptimistic<string | null>(null);
 
-  // Update the module-level ref on every render so it always points
-  // to the current component instance's setState.
+  // Non-navigation render (revalidation, popstate cached replay).
   _transitionRender = (newElement: ReactNode) => {
     startTransition(() => {
       setElement(newElement);
     });
   };
 
-  return element;
+  // Full navigation transition. The entire navigation (fetch + state updates)
+  // runs inside startTransition. useOptimistic shows the pending URL immediately
+  // (urgent) and reverts to null when the transition commits (atomic with new tree).
+  _navigateTransition = (pendingUrl: string, perform: () => Promise<ReactNode>) => {
+    return new Promise<void>((resolve, reject) => {
+      startTransition(async () => {
+        try {
+          setOptimisticPendingUrl(pendingUrl);
+          const newElement = await perform();
+          setElement(newElement);
+          resolve();
+        } catch (err) {
+          reject(err);
+        }
+      });
+    });
+  };
+
+  return createElement(PendingNavigationProvider, { value: optimisticPendingUrl }, element);
 }
 
 // ─── Public API ──────────────────────────────────────────────────
 
 /**
- * Trigger a transition render. React keeps the old committed tree
- * visible while any new Suspense boundaries in the update resolve.
- *
- * This is the function called by the router's renderRoot callback
- * instead of reactRoot.render() directly.
+ * Trigger a transition render for non-navigation updates.
+ * React keeps the old committed tree visible while any new Suspense
+ * boundaries in the update resolve.
  *
- * Falls back to no-op if TransitionRoot hasn't mounted yet (shouldn't
- * happen in practice — TransitionRoot mounts during hydration).
+ * Used for: applyRevalidation, popstate replay with cached payload.
  */
 export function transitionRender(element: ReactNode): void {
   if (_transitionRender) {
@@ -77,6 +117,30 @@ export function transitionRender(element: ReactNode): void {
   }
 }
 
+/**
+ * Run a full navigation inside a React transition with optimistic pending URL.
+ *
+ * The `perform` callback runs inside `startTransition` — it should fetch the
+ * RSC payload, update router state, and return the wrapped React element.
+ * The pending URL shows immediately (useOptimistic urgent update) and reverts
+ * to null when the transition commits (atomic with the new tree).
+ *
+ * Returns a Promise that resolves when the async work completes (note: the
+ * React transition may not have committed yet, but all state updates are done).
+ *
+ * Used for: navigate(), refresh(), popstate with fetch.
+ */
+export function navigateTransition(
+  pendingUrl: string,
+  perform: () => Promise<ReactNode>,
+): Promise<void> {
+  if (_navigateTransition) {
+    return _navigateTransition(pendingUrl, perform);
+  }
+  // Fallback: no TransitionRoot mounted (shouldn't happen in production)
+  return perform().then(() => {});
+}
+
 /**
  * Check if the TransitionRoot is mounted and ready for renders.
  * Used by browser-entry.ts to guard against renders before hydration.

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

@@ -1,8 +1,11 @@
 // useNavigationPending — returns true while an RSC navigation is in flight.
 // See design/19-client-navigation.md §"useNavigationPending()"
+//
+// Reads from PendingNavigationContext (provided by TransitionRoot) so the
+// pending state shows immediately (urgent update) and clears atomically
+// with the new tree (same startTransition commit).
 
-import { useSyncExternalStore } from 'react';
-import { getRouter } from './router-ref.js';
+import { usePendingNavigationUrl } from './pending-navigation-context.js';
 
 /**
  * Returns true while an RSC navigation is in flight.
@@ -29,19 +32,7 @@ import { getRouter } from './router-ref.js';
  * ```
  */
 export function useNavigationPending(): boolean {
-  return useSyncExternalStore(
-    (callback) => {
-      const router = getRouter();
-      return router.onPendingChange(callback);
-    },
-    () => {
-      try {
-        return getRouter().isPending();
-      } catch {
-        return false;
-      }
-    },
-    // Server snapshot — always false during SSR
-    () => false
-  );
+  const pendingUrl = usePendingNavigationUrl();
+  // During SSR or outside PendingNavigationProvider, no navigation is pending
+  return pendingUrl !== null;
 }

package/src/plugins/chunks.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
@@ -14,34 +21,140 @@
  * Design docs: 27-chunking-strategy.md
  */
 
+import { statSync } from 'node:fs';
 import type { Plugin } from 'vite';
 
+/**
+ * Source file size threshold for the shared-app chunk.
+ * Modules under this size that aren't route files get merged into shared-app
+ * instead of getting their own tiny chunks.
+ */
+const SMALL_MODULE_THRESHOLD = 5 * 1024; // 5KB
+
+/**
+ * Route convention file basenames (without extension).
+ * These files define route segments and must stay in per-route chunks
+ * to preserve route-based code splitting.
+ */
+const ROUTE_FILE_BASENAMES = new Set([
+  'page',
+  'layout',
+  'loading',
+  'error',
+  'not-found',
+  'template',
+  'access',
+  'middleware',
+  'default',
+  'route',
+]);
+
+/**
+ * Cache for source file sizes to avoid repeated statSync calls.
+ * Populated lazily during the build.
+ */
+const sizeCache = new Map<string, number>();
+
+/**
+ * Get the source file size, with caching.
+ * Returns Infinity for virtual modules or files that can't be stat'd.
+ */
+function getSourceSize(id: string): number {
+  const cached = sizeCache.get(id);
+  if (cached !== undefined) return cached;
+
+  try {
+    const size = statSync(id).size;
+    sizeCache.set(id, size);
+    return size;
+  } catch {
+    sizeCache.set(id, Infinity);
+    return Infinity;
+  }
+}
+
+/**
+ * Extract the basename without extension from a module ID.
+ * e.g. '/project/app/dashboard/page.tsx' → 'page'
+ */
+function getBasename(id: string): string {
+  const lastSlash = id.lastIndexOf('/');
+  const filename = lastSlash >= 0 ? id.substring(lastSlash + 1) : id;
+  const dotIndex = filename.indexOf('.');
+  return dotIndex >= 0 ? filename.substring(0, dotIndex) : filename;
+}
+
+/**
+ * Check if a module is a React ecosystem package (tier 1).
+ */
+function isReactVendor(id: string): boolean {
+  return (
+    id.includes('node_modules/react-dom') ||
+    id.includes('node_modules/react/') ||
+    id.includes('node_modules/scheduler')
+  );
+}
+
+/**
+ * Check if a module is part of the timber framework runtime (tier 2).
+ */
+function isTimberRuntime(id: string): boolean {
+  return (
+    id.includes('/timber-app/') ||
+    id.includes('react-server-dom') ||
+    id.includes('@vitejs/plugin-rsc')
+  );
+}
+
+/**
+ * Check if a module is a user-installed node_modules dependency (tier 3).
+ * Excludes React ecosystem and timber runtime packages which have their own tiers.
+ */
+function isUserVendor(id: string): boolean {
+  return id.includes('node_modules/') && !isReactVendor(id) && !isTimberRuntime(id);
+}
+
+/**
+ * Check if a module is a route convention file that should stay per-route.
+ */
+function isRouteFile(id: string): boolean {
+  return ROUTE_FILE_BASENAMES.has(getBasename(id));
+}
+
 /**
  * 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 function assignChunk(id: string): string | undefined {
   // Tier 1: React ecosystem — changes on version bumps only
-  if (
-    id.includes('node_modules/react-dom') ||
-    id.includes('node_modules/react/') ||
-    id.includes('node_modules/scheduler')
-  ) {
+  if (isReactVendor(id)) {
     return 'vendor-react';
   }
 
   // Tier 2: timber framework runtime — changes on framework updates
-  if (
-    id.includes('/timber-app/') ||
-    id.includes('react-server-dom') ||
-    id.includes('@vitejs/plugin-rsc')
-  ) {
+  if (isTimberRuntime(id)) {
     return 'vendor-timber';
   }
 
-  // Everything else: Rollup's default splitting (per-route chunks)
+  // Tier 3: User vendor libraries — changes on dependency updates
+  if (isUserVendor(id)) {
+    return 'vendor-app';
+  }
+
+  // Tier 4: Small shared app modules — prevents tiny per-module chunks
+  // Skip route files (page, layout, etc.) to preserve route-based splitting.
+  // Skip virtual modules (contain \0 or don't start with /) as they have no
+  // meaningful source size.
+  if (!id.includes('\0') && id.startsWith('/') && !isRouteFile(id)) {
+    const size = getSourceSize(id);
+    if (size < SMALL_MODULE_THRESHOLD) {
+      return 'shared-app';
+    }
+  }
+
+  // Tier 5: Rollup's default splitting (per-route page/layout chunks, large shared modules)
 }
 
 /**
@@ -50,14 +163,29 @@ export 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 function assignClientChunk(meta: {
   id: string;
   normalizedId: string;
   serverChunk: string;
 }): string | undefined {
+  // Timber framework client modules → vendor-timber
   if (meta.id.includes('/timber-app/')) return 'vendor-timber';
+
+  // Small user client components → shared-client (prevents facade micro-chunks)
+  if (!meta.id.includes('\0') && meta.id.startsWith('/')) {
+    const size = getSourceSize(meta.id);
+    if (size < SMALL_MODULE_THRESHOLD) {
+      return 'shared-client';
+    }
+  }
+
+  // Large user/third-party client components → default per-route splitting
 }
 
 /**