@timber-js/app 0.2.0-alpha.151 → 0.2.0-alpha.153

package/dist/index.js

@@ -1,8 +1,8 @@
 import { c as isDynamicMetadataExtension, l as isMetadataRouteServePath, r as canonicalize } from "./_chunks/canonicalize-P41GR6tY.js";
 import { t as matchUrlParts } from "./_chunks/tree-match-D2l830j2.js";
-import { h as swallow } from "./_chunks/logger-CM0clugc.js";
-import { s as scanRoutes } from "./_chunks/cli-schema-sync-DJDdyEae.js";
-import { a as generateRouteMap, i as validateSchemaAgainstRoutes, n as collectInterceptionRewrites, o as readFileCached, t as collectLeafRoutes } from "./_chunks/walkers-DvWDj453.js";
+import { h as swallow } from "./_chunks/logger-DvmCWhN9.js";
+import { s as scanRoutes } from "./_chunks/cli-schema-sync-ChsRzw8o.js";
+import { a as generateRouteMap, i as validateSchemaAgainstRoutes, n as collectInterceptionRewrites, o as readFileCached, t as collectLeafRoutes } from "./_chunks/walkers-DZuFKqFX.js";
 import { a as mergeFileConfig, c as resolveClientJavascript, i as loadTimberConfigFile, o as resolveAppDir, r as createPluginContext, s as resolveBuildDir, u as createNoopTimer } from "./_chunks/plugin-context-GfDWsdd2.js";
 import { t as fnv1aHash } from "./_chunks/fast-hash-D6hIVt1Y.js";
 import { t as formatSize } from "./_chunks/format-CfwjgPz9.js";
@@ -1153,6 +1153,14 @@ function validateConfig(config) {
 			value: config.sitemap.defaultPriority
 		});
 	}
+	if (config.budget != null && typeof config.budget === "object") {
+		if (config.budget.firstLoadJs !== void 0 && (typeof config.budget.firstLoadJs !== "number" || config.budget.firstLoadJs <= 0)) errors.push({
+			field: "budget.firstLoadJs",
+			message: `budget.firstLoadJs must be a positive number in bytes (got ${JSON.stringify(config.budget.firstLoadJs)}).`,
+			value: config.budget.firstLoadJs,
+			suggestion: "Example: budget: { firstLoadJs: 150_000 } for a ~150 kB limit."
+		});
+	}
 	for (const key of Object.keys(config)) if (!knownKeys.has(key)) errors.push({
 		field: key,
 		message: `Unknown config option: "${key}".`,
@@ -1248,7 +1256,8 @@ var init_config_validation = __esmMin((() => {
 		reactCompiler: true,
 		sitemap: true,
 		buildDir: true,
-		topLoader: true
+		topLoader: true,
+		budget: true
 	}));
 	RED$1 = "\x1B[31m";
 	BOLD$1 = "\x1B[1m";
@@ -6734,11 +6743,52 @@ function timberReactProd() {
 //#endregion
 //#region src/plugins/chunks.ts
 /**
+* Build a map from absolute module IDs in non-facade RSC chunks to the
+* absolute facade module paths that transitively import them.
+*
+* Used by `clientChunkGroup` to reclassify `shared:` client references
+* that are only consumed by a single route boundary (TIM-1107).
+*/
+function buildFacadeAncestryMap(bundle) {
+	const chunks = /* @__PURE__ */ new Map();
+	for (const [file, asset] of Object.entries(bundle)) if (asset.type === "chunk") chunks.set(file, asset);
+	const importedBy = /* @__PURE__ */ new Map();
+	for (const [file, chunk] of chunks) for (const imp of chunk.imports) {
+		let parents = importedBy.get(imp);
+		if (!parents) {
+			parents = [];
+			importedBy.set(imp, parents);
+		}
+		parents.push(file);
+	}
+	function facadeAncestors(file, visited) {
+		if (visited.has(file)) return [];
+		visited.add(file);
+		const chunk = chunks.get(file);
+		if (!chunk) return [];
+		if (chunk.facadeModuleId) return [chunk.facadeModuleId];
+		const parents = importedBy.get(file) ?? [];
+		const result = [];
+		for (const p of parents) for (const f of facadeAncestors(p, visited)) result.push(f);
+		return result;
+	}
+	const moduleToFacades = /* @__PURE__ */ new Map();
+	for (const [file, chunk] of chunks) {
+		if (chunk.facadeModuleId) continue;
+		const facades = facadeAncestors(file, /* @__PURE__ */ new Set());
+		if (facades.length === 0) continue;
+		const unique = [...new Set(facades)];
+		for (const modId of chunk.moduleIds) moduleToFacades.set(modId, unique);
+	}
+	return moduleToFacades;
+}
+/**
 * Create the timber-chunks Vite plugin.
 *
-* Currently a no-op — Rolldown's default splitting produces the desired
-* output (one main bundle + per-route chunks). The plugin is retained as
-* a hook point for future chunking adjustments.
+* Rolldown's default splitting produces the desired output (one main
+* bundle + per-route chunks). This plugin's main job is building the
+* facade ancestry map during the RSC build so `clientChunkGroup` can
+* reclassify shared client references to their correct route boundary.
 *
 * NOTE: Ideally we'd use Rolldown's `format: 'app'` (module registry format)
 * which guarantees single-copy module semantics like webpack/Turbopack.
@@ -6748,21 +6798,31 @@ function timberReactProd() {
 *
 * Design docs: 27-chunking-strategy.md
 */
-function timberChunks() {
-	return { name: "timber-chunks" };
+function timberChunks(ctx) {
+	return {
+		name: "timber-chunks",
+		generateBundle(_options, bundle) {
+			if (this.environment?.name !== "rsc") return;
+			ctx.sharedModuleFacades = buildFacadeAncestryMap(bundle);
+		}
+	};
 }
 //#endregion
 //#region src/plugins/client-chunks.ts
 /**
 * Client chunk grouping strategy for @vitejs/plugin-rsc.
 *
-* Groups client reference modules by layout boundary to balance route-scoped
-* code splitting with HTTP request count. A constant group name would collapse
-* all routes into one chunk (every page downloads every client component).
-* Per-serverChunk grouping creates many sub-500B files. Layout-boundary
-* grouping is the middle ground.
+* Groups client reference modules by the **consuming route's** layout boundary
+* (derived from `meta.serverChunk`), not by the module's own file location.
+* This ensures components in shared directories (e.g. `components/`) land in
+* the chunk of the route that uses them, not in a single catch-all chunk.
+*
+* For `shared:` modules (client references in non-facade RSC chunks), the
+* function consults a facade ancestry map built during the RSC build. If all
+* consuming facades belong to the same route boundary, the module is
+* reclassified to that boundary instead of falling through to `client-shared`.
 *
-* See design/27-chunking-strategy.md, TIM-440, TIM-499.
+* See design/27-chunking-strategy.md, TIM-440, TIM-499, TIM-1104, TIM-1107.
 */
 /**
 * Check whether a root-relative path lives under the app directory,
@@ -6795,34 +6855,53 @@ function findAppBoundary(path, appPrefix) {
 	};
 }
 /**
+* For a `shared:` client reference, check the facade ancestry map to
+* see if all consuming facades belong to the same route boundary.
+* Returns the boundary segment name, or null if the module is
+* genuinely shared across multiple boundaries.
+*/
+function reclassifySharedModule(meta, appPrefix, root, sharedModuleFacades) {
+	const facades = sharedModuleFacades.get(meta.id);
+	if (!facades || facades.length === 0) return null;
+	const boundaries = /* @__PURE__ */ new Set();
+	for (const facade of facades) {
+		const result = findAppBoundary(relative(root, facade).replace(/\\/g, "/"), appPrefix);
+		if (result.inApp && result.segment) boundaries.add(result.segment);
+		else if (result.inApp) return null;
+		else return null;
+	}
+	if (boundaries.size === 1) return [...boundaries][0];
+	return null;
+}
+/**
 * Derive a chunk group name for a client reference module.
 *
-* Groups by the first non-group route segment under appDir so that all
-* client components belonging to the same layout boundary land in one
-* chunk. For example:
+* Always derives the group from the **consuming route** (`serverChunk`'s
+* facade path), not from the module's own file location. This prevents
+* components in shared directories (e.g. `app/components/`, `src/lib/`)
+* from collapsing into a single chunk when they're only used by one route.
+*
+* For `shared:` modules (non-facade RSC chunks), consults the facade
+* ancestry map to reclassify modules that are only consumed by a single
+* route boundary. This prevents large dependencies from polluting
+* `client-shared` when they're route-scoped (TIM-1107).
+*
+* Examples:
 *   - `facade:app/dashboard/settings/page.tsx` → `"client-dashboard"`
 *   - `facade:app/(group-a)/group-page-a/page.tsx` → `"client-group-page-a"`
 *   - `facade:app/layout.tsx` (root layout) → `"client-shared"`
-*   - `shared:...` (shared across chunks) → `"client-shared"`
-*
-* When a 'use client' module lives outside the app directory (e.g. in
-* src/posts/ or src/components/), the function falls back to deriving
-* the layout boundary from the serverChunk's facade path. This prevents
-* lazily-loaded client dependencies (e.g. via import.meta.glob) from
-* being hoisted into the shared chunk when they're only used by a
-* specific route.
-*
-* This balances route-scoped code splitting with HTTP request count:
-* fewer chunks than per-serverChunk, but still avoids downloading every
-* client component on every page.
-*/
-function clientChunkGroup(meta, appDir, root) {
-	const { normalizedId, serverChunk } = meta;
-	if (serverChunk.startsWith("shared:")) return "client-shared";
+*   - `shared:...` (shared across chunks) → reclassified or `"client-shared"`
+*/
+function clientChunkGroup(meta, appDir, root, sharedModuleFacades) {
+	const { serverChunk } = meta;
 	const appPrefix = relative(root, appDir).replace(/\\/g, "/") + "/";
-	const result = findAppBoundary(normalizedId, appPrefix);
-	if (result.inApp && result.segment) return `client-${result.segment}`;
-	if (result.inApp) return "client-shared";
+	if (serverChunk.startsWith("shared:")) {
+		if (sharedModuleFacades) {
+			const boundary = reclassifySharedModule(meta, appPrefix, root, sharedModuleFacades);
+			if (boundary) return `client-${boundary}`;
+		}
+		return "client-shared";
+	}
 	if (serverChunk.startsWith("facade:")) {
 		const facadePath = serverChunk.slice(7).replace(/\\/g, "/");
 		const facadeResult = findAppBoundary(facadePath, appPrefix);
@@ -7397,6 +7476,14 @@ function buildRouteReport(entries, sharedSize) {
 	lines.push("○  (Static)   λ  (Dynamic)   ƒ  (Function)");
 	return lines;
 }
+/** Check route entries against a First-Load-JS budget and return warning lines. */
+function buildWarnings(entries, budget) {
+	if (!budget?.firstLoadJs) return [];
+	const limit = budget.firstLoadJs;
+	const warnings = [];
+	for (const entry of entries) if (entry.firstLoadSize > limit) warnings.push(`⚠ ${entry.path} first-load JS (${formatSize(entry.firstLoadSize)}) exceeds budget (${formatSize(limit)})`);
+	return warnings;
+}
 function pad(str, width, align = "right") {
 	const gap = Math.max(0, width - stripAnsi(str).length);
 	return align === "left" ? " ".repeat(gap) + str : str + " ".repeat(gap);
@@ -7430,7 +7517,42 @@ function findChunkForFile(filePath, bundle) {
 	}
 	return null;
 }
-function buildEntries(routeTree, chunkSizes, bundle, outputMode) {
+/**
+* Derive the expected client chunk group prefix for a route.
+*
+* Mirrors the `clientChunkGroup` logic: extract the first non-group segment
+* from the route's file path under appDir. Routes at the root level or
+* without a matching segment return null (their JS is in client-shared).
+*/
+function routeChunkGroupPrefix(entryFilePath, appDir, root) {
+	const appPrefix = relative(root, appDir).replace(/\\/g, "/") + "/";
+	const relPath = relative(root, entryFilePath).replace(/\\/g, "/");
+	if (!relPath.startsWith(appPrefix)) return null;
+	const segments = relPath.slice(appPrefix.length).split("/");
+	for (const seg of segments) {
+		if (seg.includes(".")) break;
+		if (seg.startsWith("(") && seg.endsWith(")")) continue;
+		return `client-${seg}`;
+	}
+	return null;
+}
+/**
+* Find all client bundle chunks belonging to a chunk group.
+*
+* Uses the chunk's `name` property (set by Rolldown from the `clientChunks`
+* callback's return value) for exact matching. The `name` is the group name
+* itself (e.g. `client-docs`), not the hashed filename.
+*/
+function findChunksForGroup(groupName, chunkSizes, bundle) {
+	if (!bundle) return [];
+	const matched = [];
+	for (const [fileName, item] of Object.entries(bundle)) {
+		if (item.type !== "chunk") continue;
+		if (item.name === groupName && chunkSizes.has(fileName)) matched.push(fileName);
+	}
+	return matched;
+}
+function buildEntries(routeTree, chunkSizes, bundle, outputMode, appDir, root) {
 	const routeInfos = collectRoutes(routeTree);
 	let totalGzip = 0;
 	for (const s of chunkSizes.values()) totalGzip += s.gzip;
@@ -7440,14 +7562,32 @@ function buildEntries(routeTree, chunkSizes, bundle, outputMode) {
 		let raw = 0;
 		let gzip = 0;
 		if (info.entryFilePath) {
-			const chunk = findChunkForFile(info.entryFilePath, bundle);
-			if (chunk) {
-				const s = chunkSizes.get(chunk);
-				if (s) {
-					raw = s.raw;
-					gzip = s.gzip;
+			let matched = false;
+			if (appDir && root) {
+				const groupPrefix = routeChunkGroupPrefix(info.entryFilePath, appDir, root);
+				if (groupPrefix) {
+					const chunks = findChunksForGroup(groupPrefix, chunkSizes, bundle);
+					for (const chunk of chunks) {
+						const s = chunkSizes.get(chunk);
+						if (s) {
+							raw += s.raw;
+							gzip += s.gzip;
+						}
+						routeChunkFiles.add(chunk);
+					}
+					if (chunks.length > 0) matched = true;
+				}
+			}
+			if (!matched) {
+				const chunk = findChunkForFile(info.entryFilePath, bundle);
+				if (chunk) {
+					const s = chunkSizes.get(chunk);
+					if (s) {
+						raw = s.raw;
+						gzip = s.gzip;
+					}
+					routeChunkFiles.add(chunk);
 				}
-				routeChunkFiles.add(chunk);
 			}
 		}
 		entries.push({
@@ -7525,11 +7665,16 @@ function timberBuildReport(ctx) {
 					firstLoadSize: 0
 				})),
 				sharedGzip: 0
-			} : buildEntries(ctx.routeTree, chunkSizes, clientBundle, outputMode);
+			} : buildEntries(ctx.routeTree, chunkSizes, clientBundle, outputMode, ctx.appDir, ctx.root);
 			const elapsed = ((performance.now() - buildStart) / 1e3).toFixed(2);
 			const lines = buildRouteReport(entries, sharedGzip);
 			logger.info("");
 			for (const line of lines) logger.info(line);
+			const warnings = buildWarnings(entries, ctx.config.budget);
+			if (warnings.length > 0) {
+				logger.info("");
+				for (const w of warnings) logger.warn(w);
+			}
 			logger.info("");
 			logger.info(`✓ built ${entries.length} routes for all three environments (rsc, ssr, client) in ${elapsed}s`);
 			logger.info("");
@@ -7931,7 +8076,7 @@ function createRscOptions(ctx, encryptionKeyExpr) {
 			ssr: "virtual:timber-ssr-entry",
 			client: "virtual:timber-browser-entry"
 		},
-		clientChunks: (meta) => clientChunkGroup(meta, ctx.appDir, ctx.root)
+		clientChunks: (meta) => clientChunkGroup(meta, ctx.appDir, ctx.root, ctx.sharedModuleFacades)
 	};
 	Object.defineProperty(options, "enableActionEncryption", {
 		get() {
@@ -8092,7 +8237,7 @@ function timber(config) {
 		timberContent(ctx),
 		timberServerBundle(),
 		timberCloudflareWasm(ctx),
-		timberChunks(),
+		timberChunks(ctx),
 		timberBuildReport(ctx),
 		timberAdapterBuild(ctx),
 		timberDevLogs(ctx),