vinext 1.0.0-beta.2 → 1.0.0-beta.4

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/plugins/client-reference-dedup.js

@@ -1,3 +1,4 @@
+import path, { toSlash } from "../deps/.pnpm/pathslash@0.1.0/deps/pathslash/dist/index.js";
 import { isUnknownRecord } from "../utils/record.js";
 import { readFile } from "node:fs/promises";
 //#region src/plugins/client-reference-dedup.ts
@@ -156,14 +157,15 @@ function clientReferenceDedupPlugin(options = {}) {
 			async handler(id, importer) {
 				if (this.environment?.name !== "client") return;
 				if (!importer || !importer.includes(PROXY_MARKER)) return;
-				if (!id.startsWith("/") || !id.includes("/node_modules/")) return;
-				const packageName = extractPackageName(id);
+				const normalizedId = toSlash(id);
+				if (!path.isAbsolute(normalizedId) || !normalizedId.includes("/node_modules/")) return;
+				const packageName = extractPackageName(normalizedId);
 				if (!packageName) return;
 				if (excludeSet.has(packageName)) return;
-				let packageImportPromise = packageImportCache.get(id);
+				let packageImportPromise = packageImportCache.get(normalizedId);
 				if (!packageImportPromise) {
-					packageImportPromise = extractPackageImportSpecifier(id, readPackageJson);
-					packageImportCache.set(id, packageImportPromise);
+					packageImportPromise = extractPackageImportSpecifier(normalizedId, readPackageJson);
+					packageImportCache.set(normalizedId, packageImportPromise);
 				}
 				const packageImport = await packageImportPromise;
 				if (!packageImport) return;

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/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/sass.js

@@ -3,7 +3,7 @@ import { markCssUrlAssetReferences, rebaseCssUrlAssetReferences } from "../build
 import { createRequire } from "node:module";
 import fs from "node:fs";
 import { preprocessCSS } from "vite";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 //#region src/plugins/sass.ts
 /**
 * Map a Next.js `sassOptions` object onto Vite's
@@ -130,8 +130,7 @@ function createSassCssUrlAssetImporter() {
 			if (!fs.statSync(candidate, { throwIfNoEntry: false })?.isFile()) continue;
 			const prepared = prepareStylesheet(candidate, entryDirectory);
 			if (prepared === null) return match;
-			const canonicalUrl = pathToFileURL(candidate);
-			markedStylesheets.set(canonicalUrl.href, prepared);
+			markedStylesheets.set(candidate, prepared);
 			const namespace = rule === "use" && !/\bas\s+(?:\*|[-\w]+)/.test(suffix) ? ` as ${deriveSassNamespace(importUrl)}` : "";
 			return `${prefix}${quote}${importUrlPrefix}${encodeURIComponent(candidate)}${quote}${namespace}${suffix}`;
 		}
@@ -143,7 +142,7 @@ function createSassCssUrlAssetImporter() {
 			return pathToFileURL(decodeURIComponent(url.slice(21)));
 		},
 		load(canonicalUrl) {
-			return markedStylesheets.get(canonicalUrl.href) ?? null;
+			return markedStylesheets.get(toSlash(fileURLToPath(canonicalUrl))) ?? null;
 		},
 		rewriteImports
 	};

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,7 +24,9 @@ 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. */
+  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. */
@@ -41,14 +43,17 @@ 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 */
+  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 */
@@ -99,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.
@@ -306,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.
@@ -359,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 };