@timber-js/app 0.1.29 → 0.1.31

package/dist/client/transition-root.d.ts

@@ -11,41 +11,61 @@
  * 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 { type ReactNode } from 'react';
 /**
  * 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 declare function TransitionRoot({ initial }: {
     initial: ReactNode;
 }): ReactNode;
 /**
- * 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 declare 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 declare function navigateTransition(pendingUrl: string, perform: () => Promise<ReactNode>): Promise<void>;
 /**
  * Check if the TransitionRoot is mounted and ready for renders.
  * Used by browser-entry.ts to guard against renders before hydration.

package/dist/client/transition-root.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transition-root.d.ts","sourceRoot":"","sources":["../../src/client/transition-root.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAalE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,EAAE,OAAO,EAAE,EAAE;IAAE,OAAO,EAAE,SAAS,CAAA;CAAE,GAAG,SAAS,CAY7E;AAID;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAIzD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C"}
+{"version":3,"file":"transition-root.d.ts","sourceRoot":"","sources":["../../src/client/transition-root.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAuBf;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,EAAE,OAAO,EAAE,EAAE;IAAE,OAAO,EAAE,SAAS,CAAA;CAAE,GAAG,SAAS,CA8B7E;AAID;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAIzD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,GAChC,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C"}

package/dist/client/use-navigation-pending.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-navigation-pending.d.ts","sourceRoot":"","sources":["../../src/client/use-navigation-pending.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAgB9C"}
+{"version":3,"file":"use-navigation-pending.d.ts","sourceRoot":"","sources":["../../src/client/use-navigation-pending.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAI9C"}

package/dist/index.js

@@ -1,6 +1,6 @@
 import { r as setViteServer, t as formatSize } from "./_chunks/format-DNt20Kt8.js";
 import { i as scanRoutes, n as generateRouteMap, t as collectInterceptionRewrites } from "./_chunks/interception-DGDIjDbR.js";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
@@ -12748,7 +12748,8 @@ function detectDynamicFontCallAst(source, importedNames) {
 	} catch {
 		return null;
 	}
-	return walkForDynamicCalls(ast, new Set(importedNames), source);
+	const nameSet = new Set(importedNames);
+	return walkForDynamicCalls(ast, nameSet, source);
 }
 /**
 * Recursively walk the AST looking for CallExpression nodes where
@@ -14067,14 +14068,119 @@ function timberReactProd() {
 //#endregion
 //#region src/plugins/chunks.ts
 /**
+* timber-chunks — Vite sub-plugin for intelligent client chunk splitting.
+*
+* 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: 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
+* benefit from cache-tier separation.
+*
+* Design docs: 27-chunking-strategy.md
+*/
+/**
+* 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.
+*/
+var SMALL_MODULE_THRESHOLD = 5 * 1024;
+/**
+* Route convention file basenames (without extension).
+* These files define route segments and must stay in per-route chunks
+* to preserve route-based code splitting.
+*/
+var 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.
+*/
+var sizeCache = /* @__PURE__ */ new Map();
+/**
+* Get the source file size, with caching.
+* Returns Infinity for virtual modules or files that can't be stat'd.
+*/
+function getSourceSize(id) {
+	const cached = sizeCache.get(id);
+	if (cached !== void 0) 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) {
+	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) {
+	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) {
+	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) {
+	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) {
+	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.
 */
 function assignChunk(id) {
-	if (id.includes("node_modules/react-dom") || id.includes("node_modules/react/") || id.includes("node_modules/scheduler")) return "vendor-react";
-	if (id.includes("/timber-app/") || id.includes("react-server-dom") || id.includes("@vitejs/plugin-rsc")) return "vendor-timber";
+	if (isReactVendor(id)) return "vendor-react";
+	if (isTimberRuntime(id)) return "vendor-timber";
+	if (isUserVendor(id)) return "vendor-app";
+	if (!id.includes("\0") && id.startsWith("/") && !isRouteFile(id)) {
+		if (getSourceSize(id) < SMALL_MODULE_THRESHOLD) return "shared-app";
+	}
 }
 /**
 * Group timber's internal 'use client' modules into the vendor-timber chunk.
@@ -14082,10 +14188,17 @@ function assignChunk(id) {
 * 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.
 */
 function assignClientChunk(meta) {
 	if (meta.id.includes("/timber-app/")) return "vendor-timber";
+	if (!meta.id.includes("\0") && meta.id.startsWith("/")) {
+		if (getSourceSize(meta.id) < SMALL_MODULE_THRESHOLD) return "shared-client";
+	}
 }
 /**
 * Create the timber-chunks Vite plugin.