vinext 1.0.0-beta.1 → 1.0.0-beta.3

package/dist/init-cloudflare.js

@@ -16,7 +16,7 @@ function validateCloudflarePlatformSetup(context, cloudflare) {
 	const projectInfo = detectProject(context.root);
 	const wranglerPath = ["wrangler.jsonc", "wrangler.json"].map((fileName) => path.join(context.root, fileName)).find((candidate) => fs.existsSync(candidate));
 	const wranglerCode = wranglerPath ? fs.readFileSync(wranglerPath, "utf-8") : void 0;
-	const updatedWranglerCode = wranglerCode ? updateWranglerConfigForCloudflare(wranglerCode, cloudflare) : void 0;
+	const updatedWranglerCode = wranglerCode ? updateWranglerConfigForCloudflare(wranglerCode, cloudflare, { root: context.root }) : void 0;
 	const imagesBinding = updatedWranglerCode ? getWranglerImagesBinding(updatedWranglerCode) : "IMAGES";
 	if (context.existingViteConfigPath) updateViteConfigForCloudflare(context.existingViteConfigPath, fs.readFileSync(context.existingViteConfigPath, "utf-8"), {
 		isAppRouter: context.isAppRouter,
@@ -56,7 +56,7 @@ function setupCloudflarePlatform(context, cloudflare) {
 		fs.writeFileSync(path.join(context.root, "wrangler.jsonc"), generateWranglerConfig(projectInfo, cloudflare, context.today), "utf-8");
 		generatedPlatformFiles.push("wrangler.jsonc");
 	} else if (wranglerCode) {
-		const updatedConfig = updateWranglerConfigForCloudflare(wranglerCode, cloudflare);
+		const updatedConfig = updateWranglerConfigForCloudflare(wranglerCode, cloudflare, { root: context.root });
 		if (updatedConfig !== wranglerCode) {
 			fs.writeFileSync(wranglerPath, updatedConfig, "utf-8");
 			generatedPlatformFiles.push(path.basename(wranglerPath));
@@ -79,8 +79,19 @@ function setupCloudflarePlatform(context, cloudflare) {
 		] : []
 	};
 }
+/**
+* `main` is what makes a Wrangler config a Worker rather than a static-assets
+* project. A custom `worker/index.*` wins when present; otherwise the
+* router-selected entry resolves to the App or Pages Router handler at build
+* time.
+*/
+function resolveWorkerEntry(root) {
+	if (fs.existsSync(path.join(root, "worker", "index.ts"))) return "./worker/index.ts";
+	if (fs.existsSync(path.join(root, "worker", "index.js"))) return "./worker/index.js";
+	return "vinext/server/fetch-handler";
+}
 function generateWranglerConfig(info, options = DEFAULT_CLOUDFLARE_INIT_OPTIONS, today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0]) {
-	const workerEntry = (fs.existsSync(path.join(info.root, "worker", "index.ts")) ? "./worker/index.ts" : fs.existsSync(path.join(info.root, "worker", "index.js")) ? "./worker/index.js" : void 0) ?? "vinext/server/fetch-handler";
+	const workerEntry = resolveWorkerEntry(info.root);
 	const config = {
 		$schema: "node_modules/wrangler/config-schema.json",
 		name: info.projectName,
@@ -258,13 +269,20 @@ function appendTopLevelJsonProperty(code, property) {
 	const structuralBefore = stripJsonComments(before);
 	return `${before}${!/,\s*$/.test(structuralBefore) && !/{\s*$/.test(structuralBefore) ? "," : ""}\n${property}\n${code.slice(closing)}`;
 }
-function updateWranglerConfigForCloudflare(code, options) {
+function updateWranglerConfigForCloudflare(code, options, context = {}) {
+	let config;
 	try {
-		JSON.parse(stripJsonComments(code));
+		config = JSON.parse(stripJsonComments(code));
 	} catch (cause) {
 		throw new Error("Could not parse the existing Wrangler JSON/JSONC config.", { cause });
 	}
+	if (Object.hasOwn(config, "pages_build_output_dir")) throw new Error("The existing Wrangler config uses \"pages_build_output_dir\", which cannot be combined with the Worker \"main\" required by vinext. Remove \"pages_build_output_dir\" and rerun vinext init.");
 	let output = code;
+	if (!findTopLevelJsonProperty(output, "main")) {
+		const workerEntry = resolveWorkerEntry(context.root ?? process.cwd());
+		output = appendTopLevelJsonProperty(output, `  "main": ${JSON.stringify(workerEntry)}`);
+	}
+	if (!findTopLevelJsonProperty(output, "assets")) output = appendTopLevelJsonProperty(output, "  \"assets\": { \"directory\": \"dist/client\", \"not_found_handling\": \"none\", \"binding\": \"ASSETS\" }");
 	if (options.cdnCache === "workers-cache") {
 		const cacheProperty = findTopLevelJsonProperty(output, "cache");
 		if (!cacheProperty) output = appendTopLevelJsonProperty(output, "  \"cache\": { \"enabled\": true }");
@@ -613,6 +631,41 @@ function endsWithCommaIgnoringWhitespaceAndComments(code) {
 function cloudflarePluginExpression(isAppRouter, binding) {
 	return isAppRouter ? `${binding}({\n  viteEnvironment: {\n    name: "rsc",\n    childEnvironments: ["ssr"],\n  },\n})` : `${binding}()`;
 }
+/**
+* An existing bare `cloudflare()` call is left as-is by `ensurePlugins`, which
+* only adds plugins that are absent. For the App Router that silently drops
+* `viteEnvironment`, so the RSC environment never runs in workerd.
+*/
+function ensureCloudflareViteEnvironment(output, config, binding, isAppRouter, code) {
+	if (!isAppRouter) return;
+	const call = findPluginCall(config, binding);
+	if (!call) return;
+	const viteEnvironment = `viteEnvironment: { name: "rsc", childEnvironments: ["ssr"] }`;
+	const firstArgument = call.arguments[0];
+	if (!firstArgument) {
+		output.appendLeft(call.end - 1, `{ ${viteEnvironment} }`);
+		return;
+	}
+	if (firstArgument.type === "SpreadElement" || firstArgument.type !== "ObjectExpression") throw new Error("The cloudflare() plugin options must be a static object for vinext init to configure the App Router Vite environment.");
+	const argumentObject = firstArgument;
+	const existingViteEnvironment = argumentObject.properties.filter((property) => property.type === "Property" && propertyName(property) === "viteEnvironment").at(-1);
+	if (existingViteEnvironment) {
+		const propertyIndex = argumentObject.properties.lastIndexOf(existingViteEnvironment);
+		if (argumentObject.properties.slice(propertyIndex + 1).some((property) => property.type === "SpreadElement")) throw new Error("The cloudflare() viteEnvironment option must appear after any spread properties so vinext init can verify it.");
+		if (existingViteEnvironment.value.type !== "ObjectExpression") throw new Error("The cloudflare() viteEnvironment option must be a static object with name: \"rsc\" and childEnvironments containing \"ssr\".");
+		const environmentObject = existingViteEnvironment.value;
+		const nameProperties = environmentObject.properties.filter((property) => property.type === "Property" && propertyName(property) === "name");
+		const childEnvironmentProperties = environmentObject.properties.filter((property) => property.type === "Property" && propertyName(property) === "childEnvironments");
+		const name = nameProperties[0];
+		const childEnvironments = childEnvironmentProperties[0];
+		const hasAmbiguousProperties = environmentObject.properties.some((property) => property.type === "SpreadElement") || nameProperties.length !== 1 || childEnvironmentProperties.length !== 1;
+		const hasRequiredName = name?.value.type === "Literal" && name.value.value === "rsc";
+		const hasRequiredChild = childEnvironments?.value.type === "ArrayExpression" && childEnvironments.value.elements.some((element) => element?.type === "Literal" && element.value === "ssr");
+		if (hasAmbiguousProperties || !hasRequiredName || !hasRequiredChild) throw new Error("The cloudflare() viteEnvironment option must statically set name: \"rsc\" and include \"ssr\" in childEnvironments.");
+		return;
+	}
+	insertObjectProperty(output, argumentObject, `${code.slice(0, call.start).split("\n").at(-1)?.match(/^\s*/)?.[0] ?? ""}  ${viteEnvironment},`, code);
+}
 function findPluginCall(config, binding) {
 	const plugins = findProperty(config, "plugins");
 	if (!plugins || plugins.value.type !== "ArrayExpression") return void 0;
@@ -819,6 +872,7 @@ function updateViteConfigForCloudflare(filePath, code, options) {
 		expression: cloudflarePluginExpression(options.isAppRouter, cloudflareBinding),
 		binding: cloudflareBinding
 	}], code);
+	ensureCloudflareViteEnvironment(output, config, cloudflareBinding, options.isAppRouter, code);
 	if (existingVinextCall) if (existingVinextCall.arguments.length === 0 && (cacheAdditions.length > 0 || imageOptimizerExpression || needsPrerender)) {
 		const properties = [];
 		if (cacheAdditions.length > 0) properties.push(`cache: { ${cacheAdditions.map(({ name, expression }) => `${name}: ${expression}`).join(", ")} }`);

package/dist/init.d.ts

@@ -3,14 +3,15 @@ import { getReactUpgradeDeps } from "./utils/react-version.js";
 
 //#region src/init.d.ts
 type InitOptions = {
-  /** Project root directory */root: string; /** Dev server port (default: 3001) */
-  port?: number; /** Skip the compatibility check step */
+  /** Project root directory */root: string; /** Dev server port (default: 3001), or false to omit the port flag. */
+  port?: number | false; /** Skip the compatibility check step */
   skipCheck?: boolean; /** Force overwrite even if vite.config.ts exists */
   force?: boolean; /** Deployment target selected by the user */
   platform?: InitPlatform; /** Configure build-time pre-rendering for all discovered static routes */
   prerender?: boolean; /** Cloudflare cache and image choices. */
   cloudflare?: CloudflareInitOptions; /** Install missing dependencies with the detected package manager (default: true). */
-  install?: boolean; /** @internal — override exec for testing (avoids ESM spy issues) */
+  install?: boolean; /** Script naming style (default: namespaced, e.g. dev:vinext). */
+  scriptNames?: "namespaced" | "standard"; /** @internal — override exec for testing (avoids ESM spy issues) */
   _exec?: (cmd: string, opts: {
     cwd: string;
     stdio: string;
@@ -34,8 +35,9 @@ declare function generateViteConfig(_isAppRouter: boolean, prerender?: boolean):
  * Add vinext scripts to package.json without overwriting existing scripts.
  * Returns the list of script names that were added.
  */
-declare function addScripts(root: string, port: number, platform?: InitPlatform, options?: {
+declare function addScripts(root: string, port: number | false, platform?: InitPlatform, options?: {
   warmCdnCache?: boolean;
+  scriptNames?: "namespaced" | "standard";
 }): string[];
 type InitDependencyGroups = {
   dependencies: string[];

package/dist/init.js

@@ -78,22 +78,16 @@ function addScripts(root, port, platform = "node", options = {}) {
 		const pkg = JSON.parse(raw);
 		if (!pkg.scripts) pkg.scripts = {};
 		const added = [];
-		if (!pkg.scripts["dev:vinext"]) {
-			pkg.scripts["dev:vinext"] = `vinext dev --port ${port}`;
-			added.push("dev:vinext");
-		}
-		if (!pkg.scripts["build:vinext"]) {
-			pkg.scripts["build:vinext"] = "vinext build";
-			added.push("build:vinext");
-		}
-		if (!pkg.scripts["start:vinext"]) {
-			pkg.scripts["start:vinext"] = platform === "cloudflare" ? "wrangler dev --config dist/server/wrangler.json" : "vinext start";
-			added.push("start:vinext");
-		}
-		if (platform === "cloudflare" && !pkg.scripts["deploy:vinext"]) {
-			pkg.scripts["deploy:vinext"] = options.warmCdnCache ? "vinext-cloudflare deploy --config dist/server/wrangler.json --experimental-warm-cdn-cache" : "vinext-cloudflare deploy --config dist/server/wrangler.json";
-			added.push("deploy:vinext");
-		}
+		const addScript = (name, command) => {
+			const scriptName = options.scriptNames === "standard" ? name : `${name}:vinext`;
+			if (pkg.scripts[scriptName]) return;
+			pkg.scripts[scriptName] = command;
+			added.push(scriptName);
+		};
+		addScript("dev", port === false ? "vinext dev" : `vinext dev --port ${port}`);
+		addScript("build", "vinext build");
+		addScript("start", platform === "cloudflare" ? "wrangler dev --config dist/server/wrangler.json" : "vinext start");
+		if (platform === "cloudflare") addScript("deploy", options.warmCdnCache ? "vinext-cloudflare deploy --config dist/server/wrangler.json --experimental-warm-cdn-cache" : "vinext-cloudflare deploy --config dist/server/wrangler.json");
 		if (added.length > 0) fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
 		return added;
 	} catch {
@@ -342,7 +336,10 @@ async function init(options) {
 		existingViteConfigPath = renamedPath;
 	}
 	const addedTypeModule = ensureESModule(root);
-	const addedScripts = addScripts(root, port, platform, { warmCdnCache: options.cloudflare?.warmCdnCache ?? false });
+	const addedScripts = addScripts(root, port, platform, {
+		warmCdnCache: options.cloudflare?.warmCdnCache ?? false,
+		scriptNames: options.scriptNames
+	});
 	const setupContext = {
 		root,
 		isAppRouter: isApp,
@@ -436,15 +433,16 @@ async function init(options) {
 	if (updatedGitignore) console.log(`    ${terminalStyle.green("✓")} Added vinext output directories to .gitignore`);
 	const nextSteps = [...platformSetup.nextSteps];
 	if (dependencyInstallNeedsApproval) nextSteps.push("Dependency installation is incomplete because pnpm blocked dependency build scripts:", "1. Review and approve the required build scripts:", "   pnpm approve-builds", "2. Finish installing dependencies:", "   pnpm install");
-	const deployCommandStep = platform === "cloudflare" ? `    ${pmName} run deploy:vinext Deploy to Cloudflare Workers\n` : "";
+	const scriptName = (name) => options.scriptNames === "standard" ? name : `${name}:vinext`;
+	const deployCommandStep = platform === "cloudflare" ? `    ${pmName} run ${scriptName("deploy")} Deploy to Cloudflare Workers\n` : "";
 	const startCommandDescription = platform === "cloudflare" ? "Start the built Worker locally with Wrangler" : "Start vinext production server";
 	console.log(`
   ${terminalStyle.cyan(terminalStyle.bold("Next steps:"))}
 ${nextSteps.map((step) => `    ${step}`).join("\n")}${nextSteps.length > 0 ? "\n" : ""}
-    ${pmName} run dev:vinext    Start the vinext dev server
-    ${pmName} run build:vinext  Build production output
-    ${pmName} run start:vinext  ${startCommandDescription}
-${deployCommandStep}    ${pmName} run dev           Start Next.js (still works as before)
+    ${pmName} run ${scriptName("dev")}    Start the vinext dev server
+    ${pmName} run ${scriptName("build")}  Build production output
+    ${pmName} run ${scriptName("start")}  ${startCommandDescription}
+${deployCommandStep}${options.scriptNames === "standard" ? "" : `    ${pmName} run dev           Start Next.js (still works as before)\n`}
 `);
 	return {
 		installedDeps: [.../* @__PURE__ */ new Set([...dependencyEntriesAdded, ...devDependencyEntriesAdded])],

package/dist/plugins/extensionless-dynamic-import.js

@@ -1,4 +1,5 @@
 import { DYNAMIC_IMPORT_PRESCAN, forEachAstChild, hasRange, isAstRecord, nodeArray } from "./ast-utils.js";
+import { createTransformCache } from "./transform-cache.js";
 import { parseAst } from "vite";
 import MagicString from "magic-string";
 //#region src/plugins/extensionless-dynamic-import.ts
@@ -23,6 +24,7 @@ const TRANSFORMABLE_EXTENSIONS = /* @__PURE__ */ new Set([
 ]);
 function createExtensionlessDynamicImportPlugin() {
 	let moduleExtensions = MODULE_EXTENSIONS;
+	const cached = createTransformCache();
 	return {
 		name: "vinext:extensionless-dynamic-import",
 		enforce: "pre",
@@ -38,28 +40,31 @@ function createExtensionlessDynamicImportPlugin() {
 				code: DYNAMIC_IMPORT_PRESCAN
 			},
 			handler(code, id) {
-				const lang = langForId(id);
-				let ast;
-				try {
-					ast = parseAst(code, { lang });
-				} catch {
-					return null;
-				}
-				const imports = collectExtensionlessImports(ast, code, moduleExtensions);
-				if (imports.length === 0) return null;
-				const output = new MagicString(code);
-				for (const dynamicImport of imports) {
-					const source = code.slice(dynamicImport.sourceStart, dynamicImport.sourceEnd);
-					output.overwrite(dynamicImport.start, dynamicImport.end, buildReplacement(source, dynamicImport.globPattern, dynamicImport.moduleExtensions));
-				}
-				return {
-					code: output.toString(),
-					map: output.generateMap({ hires: "boundary" })
-				};
+				return cached(id, code, moduleExtensions, () => transformExtensionlessImports(code, id, moduleExtensions));
 			}
 		}
 	};
 }
+function transformExtensionlessImports(code, id, moduleExtensions) {
+	const lang = langForId(id);
+	let ast;
+	try {
+		ast = parseAst(code, { lang });
+	} catch {
+		return null;
+	}
+	const imports = collectExtensionlessImports(ast, code, moduleExtensions);
+	if (imports.length === 0) return null;
+	const output = new MagicString(code);
+	for (const dynamicImport of imports) {
+		const source = code.slice(dynamicImport.sourceStart, dynamicImport.sourceEnd);
+		output.overwrite(dynamicImport.start, dynamicImport.end, buildReplacement(source, dynamicImport.globPattern, dynamicImport.moduleExtensions));
+	}
+	return {
+		code: output.toString(),
+		map: output.generateMap({ hires: "boundary" })
+	};
+}
 function langForId(id) {
 	const clean = id.split("?", 1)[0];
 	const dot = clean.lastIndexOf(".");

package/dist/plugins/ignore-dynamic-requests.js

@@ -1,5 +1,6 @@
 import path, { toSlash } from "../deps/.pnpm/pathslash@0.1.0/deps/pathslash/dist/index.js";
 import { DYNAMIC_IMPORT_PRESCAN, collectBindingNames, forEachAstChild, hasRange, isAstRecord, isIdentifierNamed, mayContainDynamicImport, nodeArray } from "./ast-utils.js";
+import { createTransformCache } from "./transform-cache.js";
 import { collectDirectScopeBindings, collectLoopScopeBindings, collectSwitchScopeBindings, collectVarScopeBindings, hasAstBinding, isFunctionNode } from "./ast-scope.js";
 import { parseAst } from "vite";
 import { fileURLToPath } from "node:url";
@@ -505,6 +506,7 @@ function transformVeryDynamicRequests(code, id) {
 	};
 }
 function createIgnoreDynamicRequestsPlugin(getTranspiledPackages = () => []) {
+	const cached = createTransformCache();
 	return {
 		name: "vinext:ignore-dynamic-requests",
 		enforce: "pre",
@@ -519,7 +521,7 @@ function createIgnoreDynamicRequestsPlugin(getTranspiledPackages = () => []) {
 				if (!shouldTransformVeryDynamicRequests(this.environment, cleanId, getTranspiledPackages())) return null;
 				const absoluteId = path.resolve(cleanId);
 				if (absoluteId === VINEXT_SOURCE_ROOT || absoluteId.startsWith(`${VINEXT_SOURCE_ROOT}/`) || PLUGIN_RSC_PATH.test(absoluteId)) return null;
-				return transformVeryDynamicRequests(code, id);
+				return cached(id, code, void 0, () => transformVeryDynamicRequests(code, id));
 			}
 		}
 	};

package/dist/plugins/import-meta-url.js

@@ -19,6 +19,7 @@ const TRANSFORMABLE_SCRIPT_EXTENSIONS = /* @__PURE__ */ new Set([
 function createImportMetaUrlPlugin(options) {
 	let rootPaths;
 	let outputDirs = [];
+	const transformCache = /* @__PURE__ */ new Map();
 	function getRootPaths() {
 		const root = options.getRoot();
 		if (!root) return rootPaths;
@@ -46,12 +47,22 @@ function createImportMetaUrlPlugin(options) {
 				if (!paths) return null;
 				const canonicalId = transformableModuleCanonicalId(cleanModuleId(id), paths);
 				if (!canonicalId) return null;
-				const rewritten = rewriteCanonicalSourceIdentity(code, canonicalId, paths, this.environment?.name === "client" ? "client" : "server");
-				if (!rewritten) return null;
-				return {
-					code: rewritten.code,
-					map: rewritten.map
-				};
+				const environment = this.environment?.name === "client" ? "client" : "server";
+				let entry = transformCache.get(id);
+				if (!entry || entry.source !== code || entry.canonicalRoot !== paths.canonicalRoot || entry.canonicalId !== canonicalId) {
+					entry = {
+						source: code,
+						canonicalRoot: paths.canonicalRoot,
+						canonicalId,
+						results: /* @__PURE__ */ new Map()
+					};
+					transformCache.set(id, entry);
+				}
+				const cached = entry.results.get(environment);
+				if (cached) return cached.value;
+				const value = rewriteCanonicalSourceIdentity(code, canonicalId, paths, environment);
+				entry.results.set(environment, { value });
+				return value;
 			}
 		}
 	};

package/dist/plugins/og-assets.js

@@ -109,7 +109,7 @@ const OG_WASM_ASSETS = ["resvg.wasm", "yoga.wasm"];
 */
 function findEmittedWasmAsset(bundle, baseName) {
 	const stem = baseName.replace(/\.wasm$/, "");
-	const re = new RegExp(`^${stem}(?:-[\\w-]+)?\\.wasm$`);
+	const re = new RegExp(`^${stem}(?:[-.][\\w-]+)?\\.wasm$`);
 	for (const output of Object.values(bundle)) {
 		if (output.type !== "asset") continue;
 		if (re.test(path.basename(output.fileName))) return output.fileName;

package/dist/plugins/require-context.js

@@ -1,4 +1,5 @@
 import { forEachAstChild, hasRange, isAstRecord, nodeArray } from "./ast-utils.js";
+import { createTransformCache } from "./transform-cache.js";
 import { parseAst } from "vite";
 import MagicString from "magic-string";
 //#region src/plugins/require-context.ts
@@ -13,6 +14,7 @@ const TRANSFORMABLE_EXTENSIONS = /* @__PURE__ */ new Set([
 	".cts"
 ]);
 function createRequireContextPlugin() {
+	const cached = createTransformCache();
 	return {
 		name: "vinext:require-context",
 		enforce: "pre",
@@ -22,25 +24,28 @@ function createRequireContextPlugin() {
 				code: /\brequire\b[\s\S]*\.context/
 			},
 			handler(code, id) {
-				const lang = langForId(id);
-				let ast;
-				try {
-					ast = parseAst(code, { lang });
-				} catch {
-					return null;
-				}
-				const calls = collectRequireContextCalls(ast);
-				if (calls.length === 0) return null;
-				const output = new MagicString(code);
-				for (const call of calls) output.overwrite(call.range.start, call.range.end, buildReplacement(call));
-				return {
-					code: output.toString(),
-					map: output.generateMap({ hires: "boundary" })
-				};
+				return cached(id, code, void 0, () => transformRequireContext(code, id));
 			}
 		}
 	};
 }
+function transformRequireContext(code, id) {
+	const lang = langForId(id);
+	let ast;
+	try {
+		ast = parseAst(code, { lang });
+	} catch {
+		return null;
+	}
+	const calls = collectRequireContextCalls(ast);
+	if (calls.length === 0) return null;
+	const output = new MagicString(code);
+	for (const call of calls) output.overwrite(call.range.start, call.range.end, buildReplacement(call));
+	return {
+		code: output.toString(),
+		map: output.generateMap({ hires: "boundary" })
+	};
+}
 function langForId(id) {
 	const clean = id.split("?", 1)[0];
 	const dot = clean.lastIndexOf(".");

package/dist/plugins/transform-cache.d.ts

@@ -0,0 +1,19 @@
+//#region src/plugins/transform-cache.d.ts
+/**
+ * Memoizes a pure per-module transform across the repeated build passes
+ * (scan client/server references + rsc/client/ssr builds), which feed the
+ * same module source through the same transform up to five times.
+ *
+ * Entries are keyed by module id and replaced when the source changes, so dev
+ * rebuilds retain at most one source version per id. `variant` distinguishes
+ * results that also depend on an environment-derived input (e.g. the
+ * typeof-window replacement); callers must pass a primitive or stable
+ * reference. Cached values include `null` ("no transform applies") so the
+ * negative case is not recomputed either.
+ *
+ * Only safe for transforms whose result depends solely on (id, source,
+ * variant) — no filesystem or plugin-state reads inside `compute`.
+ */
+declare function createTransformCache<V, R>(): (id: string, source: string, variant: V, compute: () => R) => R;
+//#endregion
+export { createTransformCache };

package/dist/plugins/transform-cache.js

@@ -0,0 +1,36 @@
+//#region src/plugins/transform-cache.ts
+/**
+* Memoizes a pure per-module transform across the repeated build passes
+* (scan client/server references + rsc/client/ssr builds), which feed the
+* same module source through the same transform up to five times.
+*
+* Entries are keyed by module id and replaced when the source changes, so dev
+* rebuilds retain at most one source version per id. `variant` distinguishes
+* results that also depend on an environment-derived input (e.g. the
+* typeof-window replacement); callers must pass a primitive or stable
+* reference. Cached values include `null` ("no transform applies") so the
+* negative case is not recomputed either.
+*
+* Only safe for transforms whose result depends solely on (id, source,
+* variant) — no filesystem or plugin-state reads inside `compute`.
+*/
+function createTransformCache() {
+	const cache = /* @__PURE__ */ new Map();
+	return (id, source, variant, compute) => {
+		let entry = cache.get(id);
+		if (entry?.source !== source) {
+			entry = {
+				source,
+				results: /* @__PURE__ */ new Map()
+			};
+			cache.set(id, entry);
+		}
+		const boxed = entry.results.get(variant);
+		if (boxed) return boxed.value;
+		const value = compute();
+		entry.results.set(variant, { value });
+		return value;
+	};
+}
+//#endregion
+export { createTransformCache };

package/dist/routing/app-route-graph.d.ts

@@ -24,8 +24,13 @@ type InterceptingRoute = {
   pagePath: string; /** Filesystem segments from app/ root to the intercepting page directory. */
   sourcePageSegments?: string[]; /** Absolute layout paths inside the intercepting route tree, outermost to innermost */
   layoutPaths: string[]; /** Normalized branch segments accumulated at each intercept layout. */
-  layoutSegments?: string[][]; /** Full normalized interception branch segments through the page. */
-  branchSegments?: string[]; /** Parameter names for dynamic segments */
+  layoutSegments?: string[][]; /** Loading conventions inside the intercepted branch, outermost to innermost. */
+  loadingPaths?: string[]; /** Tree positions for loadingPaths in the normalized interception branch. */
+  loadingTreePositions?: number[]; /** Full normalized interception branch segments through the page. */
+  branchSegments?: string[]; /** Nearest not-found convention inside the interception branch. */
+  notFoundPath?: string | null; /** Slot-root-relative branch segments used to scope not-found params. */
+  notFoundBranchSegments?: string[]; /** Tree position relative to the normalized interception branch. */
+  notFoundTreePosition?: number | null; /** Parameter names for dynamic segments */
   params: string[];
   /**
    * Synthetic page-carrier slot id for sibling (slot-less) interception.
@@ -38,15 +43,20 @@ type ParallelSlot = {
   key: string; /** Slot name (e.g. "team" from @team) */
   name: string; /** Absolute path to the @slot directory that owns this slot. Internal routing metadata. */
   ownerDir: string; /** Stable tree path for the directory whose layout owns this slot. */
-  ownerTreePath: string; /** Whether the slot owner directory declares its own page component. */
+  ownerTreePath: string; /** Directory depth of the slot owner from app/ root. */
+  ownerTreePosition?: number; /** Whether the slot owner directory declares its own page component. */
   hasPage: boolean; /** Absolute path to the slot's page component */
   pagePath: string | null; /** Absolute path to the slot's default.tsx fallback */
   defaultPath: string | null; /** Absolute path to the slot's layout component (wraps slot content) */
   layoutPath: string | null; /** Nested active-branch layouts whose exports contribute route config. */
   configLayoutPaths?: string[]; /** Tree positions of configLayoutPaths relative to the slot root. */
   configLayoutTreePositions?: number[]; /** Absolute path to the slot's loading component */
-  loadingPath: string | null; /** Absolute path to the slot's error component */
-  errorPath: string | null; /** Intercepting routes within this slot */
+  loadingPath: string | null; /** Per-segment loading components from the slot root to its active page. */
+  loadingPaths?: string[]; /** Slot-root-relative tree positions aligned with loadingPaths. */
+  loadingTreePositions?: number[]; /** Absolute path to the slot's error component */
+  errorPath: string | null; /** Nearest not-found convention for the slot's active branch. */
+  notFoundPath?: string | null; /** Tree position of that convention relative to the slot root. */
+  notFoundTreePosition?: number | null; /** Intercepting routes within this slot */
   interceptingRoutes: InterceptingRoute[];
   /**
    * The layout index (0-based, in route.layouts[]) that this slot belongs to.
@@ -94,8 +104,10 @@ type AppRoute = {
    * On soft-nav, the intercepting page replaces the entire page response.
    * Empty array when there are no sibling-style interception markers.
    */
-  siblingIntercepts: InterceptingRoute[]; /** Loading component path */
-  loadingPath: string | null; /** Error component path (leaf directory only) */
+  siblingIntercepts: InterceptingRoute[]; /** Loading component path (leaf directory only) */
+  loadingPath: string | null; /** Per-segment loading component paths, aligned with loadingTreePositions. */
+  loadingPaths?: string[]; /** Tree position (directory depth from app/ root) for each loading boundary. */
+  loadingTreePositions?: number[]; /** Error component path (leaf directory only) */
   errorPath: string | null;
   /**
    * Per-layout error boundary paths, aligned with the layouts array.
@@ -105,7 +117,8 @@ type AppRoute = {
   layoutErrorPaths: (string | null)[]; /** Per-segment error boundary paths, aligned with errorTreePositions. */
   errorPaths?: string[]; /** Tree position (directory depth from app/ root) for each error boundary. */
   errorTreePositions?: number[]; /** Not-found component path (nearest, walking up from page dir) */
-  notFoundPath: string | null;
+  notFoundPath: string | null; /** Tree position of the nearest not-found component's owning segment. */
+  notFoundTreePosition?: number | null;
   /**
    * Not-found component paths per layout level (aligned with layouts array).
    * Each entry is the not-found.tsx at that layout's directory, or null.
@@ -119,8 +132,10 @@ type AppRoute = {
    * Used to create per-layout ForbiddenBoundary.
    */
   forbiddenPaths: (string | null)[]; /** Forbidden component path (403) at the route's directory level */
-  forbiddenPath: string | null; /** Unauthorized component path (401) at the route's directory level */
-  unauthorizedPath: string | null; /** Unauthorized component paths per layout level (aligned with layouts array). */
+  forbiddenPath: string | null; /** Tree position of the nearest forbidden component's owning segment. */
+  forbiddenTreePosition?: number | null; /** Unauthorized component path (401) at the route's directory level */
+  unauthorizedPath: string | null; /** Tree position of the nearest unauthorized component's owning segment. */
+  unauthorizedTreePosition?: number | null; /** Unauthorized component paths per layout level (aligned with layouts array). */
   unauthorizedPaths: (string | null)[];
   /**
    * Filesystem segments from app/ root to the route's directory.
@@ -298,6 +313,7 @@ declare function buildAppRouteGraph(appDir: string, matcher: ValidFileMatcher):
   routeManifest: RouteManifest;
 }>;
 declare function computeRootParamNames(routeSegments: readonly string[], layoutTreePositions: readonly number[]): string[];
+declare function patternsStructurallyEquivalent(a: readonly string[], b: readonly string[]): boolean;
 /**
  * Find the best route to attach a sibling intercept to, given the directory
  * that contains the interception marker.
@@ -351,4 +367,4 @@ declare function computeAppRouteStaticSiblings(allRoutes: readonly {
   patternParts?: readonly string[] | null;
 }): string[];
 //#endregion
-export { AppRoute, AppRouteGraphRoute, AppRouteSemanticIds, GraphVersion, RootBoundaryId, RouteManifest, RouteManifestInterception, RouteManifestRootBoundary, RouteManifestRoute, RouteManifestSlotBinding, StaticSegmentGraph, buildAppRouteGraph, computeAppRouteStaticSiblings, computeRootParamNames, convertSegmentsToRouteParts, findOwnerRouteForDir, isInvisibleSegment };
+export { AppRoute, AppRouteGraphRoute, AppRouteSemanticIds, GraphVersion, RootBoundaryId, RouteManifest, RouteManifestInterception, RouteManifestRootBoundary, RouteManifestRoute, RouteManifestSlotBinding, StaticSegmentGraph, buildAppRouteGraph, computeAppRouteStaticSiblings, computeRootParamNames, convertSegmentsToRouteParts, findOwnerRouteForDir, isInvisibleSegment, patternsStructurallyEquivalent };