@timber-js/app 0.1.29 → 0.1.30

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.30",
   "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

@@ -289,12 +289,14 @@ function bootstrap(runtimeConfig: typeof config): void {
       setNavigationState({
         params: earlyParams as Record<string, string | string[]>,
         pathname: window.location.pathname,
+        pendingUrl: null,
       });
       delete (self as unknown as Record<string, unknown>).__timber_params;
     } else {
       setNavigationState({
         params: {},
         pathname: window.location.pathname,
+        pendingUrl: null,
       });
     }
 
@@ -439,6 +441,7 @@ function bootstrap(runtimeConfig: typeof config): void {
     setNavigationState({
       params: lateTimberParams as Record<string, string | string[]>,
       pathname: window.location.pathname,
+      pendingUrl: null,
     });
     delete (self as unknown as Record<string, unknown>).__timber_params;
   }

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

@@ -2,39 +2,33 @@
 
 // LinkStatusProvider — client component that provides per-link pending status
 // via React context. Used inside <Link> to power useLinkStatus().
+//
+// Reads pendingUrl from NavigationContext so the pending status updates
+// atomically with params/pathname in the same React commit. This prevents
+// the gap where the spinner disappears before the active state updates.
 
-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 { useNavigationContext } from './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 NavigationContext and
+ * provides a scoped LinkStatusContext to children. Renders no extra DOM —
+ * just a context provider around children.
+ *
+ * Because pendingUrl lives in NavigationContext alongside params and pathname,
+ * all three update in the same React commit via renderRoot(). This eliminates
+ * the two-commit timing gap that existed when pendingUrl was read via
+ * useSyncExternalStore (external module-level state) while params came from
+ * NavigationContext (React context).
  */
 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 navState = useNavigationContext();
+  // During SSR or outside NavigationProvider, never pending
+  const status = navState?.pendingUrl === href ? IS_PENDING : NOT_PENDING;
 
   return <LinkStatusContext.Provider value={status}>{children}</LinkStatusContext.Provider>;
 }

package/src/client/navigation-context.ts

@@ -35,6 +35,14 @@ import React, { createElement, type ReactNode } from 'react';
 export interface NavigationState {
   params: Record<string, string | string[]>;
   pathname: string;
+  /**
+   * The URL currently being navigated to, or null if idle.
+   * Used by LinkStatusProvider to determine pending status atomically
+   * with params/pathname — all three update in the same React commit
+   * via NavigationProvider, preventing the gap where the spinner
+   * disappears before the active state updates.
+   */
+  pendingUrl: string | null;
 }
 
 // ---------------------------------------------------------------------------
@@ -107,7 +115,7 @@ export function NavigationProvider({ value, children }: NavigationProviderProps)
  * This exists only as a communication channel between the router
  * (which knows the new nav state) and renderRoot (which wraps the element).
  */
-let _currentNavState: NavigationState = { params: {}, pathname: '/' };
+let _currentNavState: NavigationState = { params: {}, pathname: '/', pendingUrl: null };
 
 export function setNavigationState(state: NavigationState): void {
   _currentNavState = state;

package/src/client/router.ts

@@ -6,7 +6,7 @@ import type { SegmentInfo } from './segment-cache';
 import { HistoryStack } from './history';
 import type { HeadElement } from './head';
 import { setCurrentParams } from './use-params.js';
-import { setNavigationState } from './navigation-context.js';
+import { getNavigationState, setNavigationState } from './navigation-context.js';
 
 // ─── Types ───────────────────────────────────────────────────────
 
@@ -298,15 +298,27 @@ export function createRouter(deps: RouterDeps): RouterInstance {
   let pending = false;
   let pendingUrl: string | null = null;
   const pendingListeners = new Set<(pending: boolean) => void>();
+  /** Last rendered payload — used to re-render at navigation start with pendingUrl set. */
+  let lastRenderedPayload: unknown = null;
 
   function setPending(value: boolean, url?: string): void {
     const newPendingUrl = value && url ? url : null;
     if (pending === value && pendingUrl === newPendingUrl) return;
     pending = value;
     pendingUrl = newPendingUrl;
+    // Notify external store listeners (useNavigationPending, etc.)
     for (const listener of pendingListeners) {
       listener(value);
     }
+    // When navigation starts, re-render the current tree with pendingUrl
+    // set in NavigationContext. This makes the pending state visible to
+    // LinkStatusProvider atomically via React context, avoiding the
+    // two-commit gap between useSyncExternalStore and context updates.
+    if (value && lastRenderedPayload !== null) {
+      const currentState = getNavigationState();
+      setNavigationState({ ...currentState, pendingUrl: newPendingUrl });
+      renderPayload(lastRenderedPayload);
+    }
   }
 
   /** Update the segment cache from server-provided segment metadata. */
@@ -320,22 +332,29 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
   /** Render a decoded RSC payload into the DOM if a renderer is available. */
   function renderPayload(payload: unknown): void {
+    lastRenderedPayload = payload;
     if (deps.renderRoot) {
       deps.renderRoot(payload);
     }
   }
 
   /**
-   * Update navigation state (params + pathname) for the next render.
+   * Update navigation state (params + pathname + pendingUrl) for the next render.
    *
    * Sets both the module-level fallback (for tests and SSR) and the
    * navigation context state (read by renderRoot to wrap the element
    * in NavigationProvider). The context update is atomic with the tree
    * render — both are passed to reactRoot.render() in the same call.
+   *
+   * pendingUrl is included so that LinkStatusProvider (which reads from
+   * NavigationContext) sees the pending state change in the same React
+   * commit as params/pathname — preventing the gap where the spinner
+   * disappears before the active state updates.
    */
   function updateNavigationState(
     params: Record<string, string | string[]> | null | undefined,
-    url: string
+    url: string,
+    navPendingUrl: string | null = null
   ): void {
     const resolvedParams = params ?? {};
     // Module-level fallback for tests (no NavigationProvider) and SSR
@@ -344,7 +363,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     const pathname = url.startsWith('http')
       ? new URL(url).pathname
       : url.split('?')[0] || '/';
-    setNavigationState({ params: resolvedParams, pathname });
+    setNavigationState({ params: resolvedParams, pathname, pendingUrl: navPendingUrl });
   }
 
   /** Apply head elements (title, meta tags) to the DOM if available. */

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

@@ -1,8 +1,12 @@
 // useNavigationPending — returns true while an RSC navigation is in flight.
 // See design/19-client-navigation.md §"useNavigationPending()"
+//
+// Reads from NavigationContext so the pending state updates atomically
+// with params/pathname in the same React commit. Falls back to the
+// router's external store when no NavigationProvider is mounted (SSR,
+// tests without a React tree).
 
-import { useSyncExternalStore } from 'react';
-import { getRouter } from './router-ref.js';
+import { useNavigationContext } from './navigation-context.js';
 
 /**
  * Returns true while an RSC navigation is in flight.
@@ -29,19 +33,8 @@ 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 navState = useNavigationContext();
+  // During SSR or outside NavigationProvider, no navigation is pending
+  if (!navState) return false;
+  return navState.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
 }
 
 /**