vinext 0.1.8 → 0.2.1

package/dist/plugins/rsc-reference-validation-normalizer.js

@@ -0,0 +1,48 @@
+//#region src/plugins/rsc-reference-validation-normalizer.ts
+const REFERENCE_VALIDATION_ID_PREFIX = "\0virtual:vite-rsc/reference-validation?";
+function parseReferenceValidationQuery(id) {
+	const queryStart = id.indexOf("?");
+	if (queryStart === -1) return null;
+	return Object.fromEntries(new URLSearchParams(id.slice(queryStart + 1)));
+}
+function normalizeReferenceKey(id) {
+	return id.replaceAll("\0", "__x00__");
+}
+function hasReference(referenceMetaMap, referenceId) {
+	if (!referenceMetaMap || !referenceId) return false;
+	const normalizedReferenceId = normalizeReferenceKey(referenceId);
+	return Object.values(referenceMetaMap).some((meta) => normalizeReferenceKey(meta.referenceKey) === normalizedReferenceId);
+}
+/**
+* @vitejs/plugin-rsc stores dev virtual client-reference keys in Vite's encoded
+* `/@id/__x00__...` form, but React's SSR consumer can ask validation for the
+* decoded `/@id/\0...` form. Treat those as equivalent and fall through to the
+* upstream validator for all other invalid references.
+*/
+function createRscReferenceValidationNormalizerPlugin() {
+	let rscApi;
+	return {
+		name: "vinext:rsc-reference-validation-normalizer",
+		enforce: "pre",
+		apply(_config, env) {
+			return env.command === "serve" && env.isPreview !== true;
+		},
+		configResolved(config) {
+			rscApi = config.plugins.find((plugin) => plugin.name === "rsc:minimal")?.api;
+		},
+		load: {
+			filter: { id: /^\u0000virtual:vite-rsc\/reference-validation\?/ },
+			handler(id) {
+				if (!id.startsWith(REFERENCE_VALIDATION_ID_PREFIX)) return null;
+				const query = parseReferenceValidationQuery(id);
+				if (!query) return null;
+				const manager = rscApi?.manager;
+				if (query.type === "client" && hasReference(manager?.clientReferenceMetaMap, query.id)) return "export {}";
+				if (query.type === "server" && hasReference(manager?.serverReferenceMetaMap, query.id)) return "export {}";
+				return null;
+			}
+		}
+	};
+}
+//#endregion
+export { createRscReferenceValidationNormalizerPlugin };

package/dist/plugins/sass.d.ts

@@ -35,6 +35,22 @@ type VitePreprocessorOptions = {
 declare function createSassTildeImporter(root: string): {
   findFileUrl(url: string): URL | null;
 };
+type SassLoadedStylesheet = {
+  contents: string;
+  syntax: "scss" | "indented" | "css";
+};
+/**
+ * Preserve source-asset provenance for `url()` references inside imported Sass
+ * partials. Vite's transform hook only sees the entry stylesheet after Sass has
+ * flattened its imports, at which point relative URLs from a partial have lost
+ * the partial's source filename. Marking the partial before compilation keeps
+ * byte-identical assets associated with their original basenames.
+ */
+declare function createSassCssUrlAssetImporter(): {
+  canonicalize(url: string): URL | null;
+  load(canonicalUrl: URL): SassLoadedStylesheet | null;
+  rewriteImports(source: string, filename: string): string;
+};
 declare function buildSassPreprocessorOptions(sassOptions: Record<string, unknown> | null | undefined): VitePreprocessorOptions | undefined;
 /**
  * Create a per-build binding of {@link SassAwareFileSystemLoader}.
@@ -59,4 +75,4 @@ declare function createSassAwareFileSystemLoader(): {
   setResolvedConfig: (config: ResolvedConfig) => void;
 };
 //#endregion
-export { buildSassPreprocessorOptions, createSassAwareFileSystemLoader, createSassTildeImporter };
+export { buildSassPreprocessorOptions, createSassAwareFileSystemLoader, createSassCssUrlAssetImporter, createSassTildeImporter };

package/dist/plugins/sass.js

@@ -1,3 +1,4 @@
+import { markCssUrlAssetReferences, rebaseCssUrlAssetReferences } from "../build/css-url-assets.js";
 import { createRequire } from "node:module";
 import fs from "node:fs";
 import path from "node:path";
@@ -75,6 +76,78 @@ function createSassTildeImporter(root) {
 		}
 	} };
 }
+function sassStylesheetCandidates(importPath) {
+	const extension = path.extname(importPath);
+	const directory = path.dirname(importPath);
+	const basename = path.basename(importPath, extension);
+	const candidates = [];
+	const extensions = extension ? [extension] : [
+		".scss",
+		".sass",
+		".css"
+	];
+	for (const candidateExtension of extensions) {
+		const basePath = extension ? importPath : `${importPath}${candidateExtension}`;
+		candidates.push(basePath);
+		candidates.push(path.join(directory, `_${basename}${candidateExtension}`));
+	}
+	for (const candidateExtension of extensions) {
+		candidates.push(path.join(importPath, `index${candidateExtension}`));
+		candidates.push(path.join(importPath, `_index${candidateExtension}`));
+	}
+	return candidates;
+}
+function deriveSassNamespace(importUrl) {
+	const parts = importUrl.replaceAll("\\", "/").replace(/\/$/, "").split("/");
+	let basename = parts.pop() ?? "stylesheet";
+	basename = basename.replace(/^_/, "").replace(/\..*$/, "");
+	if (basename === "index" && parts.length > 0) basename = (parts.pop() ?? basename).replace(/^_/, "").replace(/\..*$/, "");
+	return basename;
+}
+/**
+* Preserve source-asset provenance for `url()` references inside imported Sass
+* partials. Vite's transform hook only sees the entry stylesheet after Sass has
+* flattened its imports, at which point relative URLs from a partial have lost
+* the partial's source filename. Marking the partial before compilation keeps
+* byte-identical assets associated with their original basenames.
+*/
+function createSassCssUrlAssetImporter() {
+	const markedStylesheets = /* @__PURE__ */ new Map();
+	const importUrlPrefix = "vinext-css-url-asset:";
+	const prepareStylesheet = (filename, entryDirectory) => {
+		const contents = fs.readFileSync(filename, "utf8");
+		const marked = markCssUrlAssetReferences(rebaseCssUrlAssetReferences(contents, path.dirname(filename), entryDirectory) ?? contents, filename);
+		if (marked === null) return null;
+		const extension = path.extname(filename).toLowerCase();
+		return {
+			contents: rewriteImports(marked, filename, entryDirectory),
+			syntax: extension === ".sass" ? "indented" : extension === ".css" ? "css" : "scss"
+		};
+	};
+	const rewriteImports = (source, filename, entryDirectory = path.dirname(filename)) => source.replace(/(@(import|use|forward)\s+)(["'])(\.[^"']+)\3([^;]*;?)/g, (match, prefix, rule, quote, importUrl, suffix) => {
+		const importPath = path.resolve(path.dirname(filename), importUrl);
+		for (const candidate of sassStylesheetCandidates(importPath)) {
+			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);
+			const namespace = rule === "use" && !/\bas\s+(?:\*|[-\w]+)/.test(suffix) ? ` as ${deriveSassNamespace(importUrl)}` : "";
+			return `${prefix}${quote}${importUrlPrefix}${encodeURIComponent(candidate)}${quote}${namespace}${suffix}`;
+		}
+		return match;
+	});
+	return {
+		canonicalize(url) {
+			if (!url.startsWith(importUrlPrefix)) return null;
+			return pathToFileURL(decodeURIComponent(url.slice(21)));
+		},
+		load(canonicalUrl) {
+			return markedStylesheets.get(canonicalUrl.href) ?? null;
+		},
+		rewriteImports
+	};
+}
 function buildSassPreprocessorOptions(sassOptions) {
 	if (!sassOptions || typeof sassOptions !== "object") return void 0;
 	const { prependData, additionalData, includePaths, loadPaths, ...rest } = sassOptions;
@@ -265,4 +338,4 @@ function createSassAwareFileSystemLoader() {
 	};
 }
 //#endregion
-export { buildSassPreprocessorOptions, createSassAwareFileSystemLoader, createSassTildeImporter };
+export { buildSassPreprocessorOptions, createSassAwareFileSystemLoader, createSassCssUrlAssetImporter, createSassTildeImporter };

package/dist/plugins/styled-jsx.d.ts

@@ -0,0 +1,16 @@
+import { Plugin } from "vite";
+
+//#region src/plugins/styled-jsx.d.ts
+type NextSwcModule = {
+  loadBindings(): Promise<unknown>;
+  transform(source: string, options: Record<string, unknown>): Promise<{
+    code: string;
+    map?: string;
+  }>;
+};
+type StyledJsxPluginOptions = {
+  importModule?: (url: string) => Promise<NextSwcModule>;
+};
+declare function createStyledJsxPlugin(initialProjectRoot: string, options?: StyledJsxPluginOptions): Plugin;
+//#endregion
+export { createStyledJsxPlugin };

package/dist/plugins/styled-jsx.js

@@ -0,0 +1,149 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import { parseAst } from "vite";
+import { pathToFileURL } from "node:url";
+//#region src/plugins/styled-jsx.ts
+const STYLED_JSX_IMPORT_RE = /^styled-jsx(?:\/.*)?$/;
+const NODE_MODULES_RE = /[\\/]node_modules[\\/]/;
+const STYLED_JSX_SOURCE_RE = /(?:<style\b|from\s+["']styled-jsx\/css["']|require\s*\(\s*["']styled-jsx\/css["']\s*\))/;
+const STYLED_JSX_CSS_RE = /(?:from\s+["']styled-jsx\/css["']|require\s*\(\s*["']styled-jsx\/css["']\s*\))/;
+function hasStyledJsxTag(source, id) {
+	const cleanId = id.split("?")[0];
+	const extension = path.extname(cleanId);
+	const lang = extension === ".ts" || extension === ".mts" || extension === ".cts" ? "ts" : "tsx";
+	let ast;
+	try {
+		ast = parseAst(source, { lang });
+	} catch {
+		return false;
+	}
+	const pending = [ast];
+	const visited = /* @__PURE__ */ new Set();
+	while (pending.length > 0) {
+		const value = pending.pop();
+		if (!value || typeof value !== "object" || visited.has(value)) continue;
+		visited.add(value);
+		const node = value;
+		if (node.type === "JSXOpeningElement") {
+			const name = node.name;
+			if (name?.type === "JSXIdentifier" && name.name === "style") {
+				if (node.attributes?.some((attribute) => {
+					if (attribute.type !== "JSXAttribute") return false;
+					const attributeName = attribute.name;
+					return attributeName?.type === "JSXIdentifier" && attributeName.name === "jsx";
+				})) return true;
+			}
+		}
+		for (const child of Object.values(node)) if (Array.isArray(child)) pending.push(...child);
+		else if (child && typeof child === "object") pending.push(child);
+	}
+	return false;
+}
+function createProjectRequire(projectRoot) {
+	return createRequire(path.join(projectRoot, "package.json"));
+}
+function resolveNextRequire(projectRoot) {
+	try {
+		return createRequire(createProjectRequire(projectRoot).resolve("next/package.json"));
+	} catch {
+		return null;
+	}
+}
+function parserOptions(id) {
+	const extension = path.extname(id.split("?")[0]);
+	if (extension === ".ts" || extension === ".tsx") return {
+		syntax: "typescript",
+		tsx: extension === ".tsx",
+		decorators: true
+	};
+	return {
+		syntax: "ecmascript",
+		jsx: true
+	};
+}
+function createStyledJsxPlugin(initialProjectRoot, options = {}) {
+	let projectRoot = initialProjectRoot;
+	let development = false;
+	let nextRequire;
+	let compilerPromise = null;
+	const importModule = options.importModule ?? ((url) => import(url));
+	function getNextRequire() {
+		nextRequire ??= resolveNextRequire(projectRoot);
+		return nextRequire;
+	}
+	async function getCompiler() {
+		if (!compilerPromise) {
+			const requireFromNext = getNextRequire();
+			if (!requireFromNext) throw new Error("[vinext] styled-jsx requires an installed next package so vinext can use its matching compiler.");
+			compilerPromise = importModule(pathToFileURL(requireFromNext.resolve("next/dist/build/swc")).href).then(async (compiler) => {
+				await compiler.loadBindings();
+				return compiler;
+			});
+		}
+		return compilerPromise;
+	}
+	return {
+		name: "vinext:styled-jsx",
+		enforce: "pre",
+		configResolved(config) {
+			development = config.command === "serve";
+			if (config.root !== projectRoot) {
+				projectRoot = config.root;
+				nextRequire = void 0;
+				compilerPromise = null;
+			}
+		},
+		resolveId: {
+			filter: { id: STYLED_JSX_IMPORT_RE },
+			handler(source) {
+				try {
+					return getNextRequire()?.resolve(source) ?? null;
+				} catch {}
+				try {
+					return createProjectRequire(projectRoot).resolve(source);
+				} catch {
+					return null;
+				}
+			}
+		},
+		transform: {
+			filter: {
+				id: {
+					include: /\.[cm]?[jt]sx?(?:\?.*)?$/,
+					exclude: NODE_MODULES_RE
+				},
+				code: STYLED_JSX_SOURCE_RE
+			},
+			async handler(source, id) {
+				if (NODE_MODULES_RE.test(id.split("?")[0])) return null;
+				const hasStyledJsxCss = STYLED_JSX_CSS_RE.test(source);
+				const hasStyledJsxElement = !hasStyledJsxCss && hasStyledJsxTag(source, id);
+				if (!hasStyledJsxCss && !hasStyledJsxElement) return null;
+				if (!getNextRequire()) throw new Error("[vinext] styled-jsx requires an installed next package so vinext can use its matching compiler.");
+				const result = await (await getCompiler()).transform(source, {
+					filename: id.split("?")[0],
+					sourceMaps: true,
+					module: { type: "es6" },
+					styledJsx: { useLightningcss: false },
+					jsc: {
+						parser: parserOptions(id),
+						transform: {
+							react: {
+								runtime: "automatic",
+								development,
+								useBuiltins: true
+							},
+							optimizer: { simplify: false }
+						}
+					}
+				});
+				return {
+					code: result.code,
+					map: result.map ?? null
+				};
+			}
+		}
+	};
+}
+//#endregion
+export { createStyledJsxPlugin };

package/dist/plugins/typeof-window.d.ts

@@ -6,7 +6,7 @@ type EnvironmentLike = {
   };
 };
 declare function getTypeofWindowReplacement(environment: EnvironmentLike): WindowType;
-declare function replaceTypeofWindow(code: string, replacement: WindowType): {
+declare function replaceTypeofWindow(code: string, replacement: WindowType, id?: string): {
   code: string;
   map: import("magic-string").SourceMap;
 } | null;

package/dist/plugins/typeof-window.js

@@ -1,55 +1,17 @@
 import { collectBindingNames, forEachAstChild, hasRange, isAstRecord, isIdentifierNamed, nodeArray } from "./ast-utils.js";
+import { collectDirectScopeBindings, collectLoopScopeBindings, collectSwitchScopeBindings, collectVarScopeBindings, createAstScope, hasAstBinding, isFunctionNode } from "./ast-scope.js";
+import path from "node:path";
 import { parseAst } from "vite";
 import MagicString from "magic-string";
 //#region src/plugins/typeof-window.ts
-function createScope(parent) {
-	return {
-		parent,
-		bindings: /* @__PURE__ */ new Set()
-	};
-}
-function hasBinding(scope, name) {
-	for (let current = scope; current; current = current.parent) if (current.bindings.has(name)) return true;
-	return false;
-}
-function collectScopeBindings(node, scope) {
-	forEachAstChild(node, (child) => {
-		if (child.type === "ExportNamedDeclaration" || child.type === "ExportDefaultDeclaration") {
-			if (isAstRecord(child.declaration)) collectScopeBindings(child, scope);
-			return;
-		}
-		if (child.type === "FunctionDeclaration" || child.type === "ClassDeclaration") {
-			collectBindingNames(child.id, scope.bindings);
-			return;
-		}
-		if (child.type === "VariableDeclaration") {
-			for (const declaration of nodeArray(child.declarations)) if (isAstRecord(declaration)) collectBindingNames(declaration.id, scope.bindings);
-			return;
-		}
-		if (child.type === "ImportDeclaration") {
-			for (const specifier of nodeArray(child.specifiers)) if (isAstRecord(specifier)) collectBindingNames(specifier.local, scope.bindings);
-		}
-	});
-}
-function collectVarBindings(node, scope, isRoot = true) {
-	if (!isRoot && (node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression")) return;
-	if (node.type === "VariableDeclaration" && node.kind === "var") {
-		for (const declaration of nodeArray(node.declarations)) if (isAstRecord(declaration)) collectBindingNames(declaration.id, scope.bindings);
-	}
-	forEachAstChild(node, (child) => collectVarBindings(child, scope, false));
-}
-function isFunctionNode(node) {
-	return node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression";
-}
 function createChildScope(node, parent) {
-	if (node.type !== "Program" && node.type !== "BlockStatement" && node.type !== "StaticBlock" && node.type !== "SwitchStatement" && node.type !== "CatchClause" && node.type !== "ForStatement" && node.type !== "ForInStatement" && node.type !== "ForOfStatement" && node.type !== "ClassDeclaration" && node.type !== "ClassExpression") return null;
-	const scope = createScope(parent);
+	if (node.type !== "Program" && node.type !== "BlockStatement" && node.type !== "StaticBlock" && node.type !== "TSModuleBlock" && node.type !== "CatchClause" && node.type !== "ForStatement" && node.type !== "ForInStatement" && node.type !== "ForOfStatement" && node.type !== "ClassDeclaration" && node.type !== "ClassExpression") return null;
+	const scope = createAstScope(parent);
 	if (node.type === "ClassDeclaration" || node.type === "ClassExpression") collectBindingNames(node.id, scope.bindings);
 	else if (node.type === "CatchClause") collectBindingNames(node.param, scope.bindings);
-	collectScopeBindings(node, scope);
-	if (node.type === "SwitchStatement") {
-		for (const switchCase of nodeArray(node.cases)) if (isAstRecord(switchCase)) collectScopeBindings(switchCase, scope);
-	}
+	collectDirectScopeBindings(node, scope);
+	if (node.type === "StaticBlock" || node.type === "TSModuleBlock") collectVarScopeBindings(node, scope);
+	if (node.type === "ForStatement" || node.type === "ForInStatement" || node.type === "ForOfStatement") collectLoopScopeBindings(node, scope);
 	return scope;
 }
 function getTypeofWindowReplacement(environment) {
@@ -70,42 +32,52 @@ function evaluateTypeofWindowComparison(node, replacement, scope) {
 	].includes(String(node.operator))) return null;
 	const left = isAstRecord(node.left) ? node.left : null;
 	const right = isAstRecord(node.right) ? node.right : null;
-	const leftIsTypeofWindow = left?.type === "UnaryExpression" && left.operator === "typeof" && isIdentifierNamed(left.argument, "window") && !hasBinding(scope, "window");
-	const rightIsTypeofWindow = right?.type === "UnaryExpression" && right.operator === "typeof" && isIdentifierNamed(right.argument, "window") && !hasBinding(scope, "window");
+	const leftIsTypeofWindow = left?.type === "UnaryExpression" && left.operator === "typeof" && isIdentifierNamed(left.argument, "window") && !hasAstBinding(scope, "window");
+	const rightIsTypeofWindow = right?.type === "UnaryExpression" && right.operator === "typeof" && isIdentifierNamed(right.argument, "window") && !hasAstBinding(scope, "window");
 	const comparedValue = leftIsTypeofWindow ? stringLiteralValue(right) : rightIsTypeofWindow ? stringLiteralValue(left) : null;
 	if (comparedValue === null) return null;
 	const equal = replacement === comparedValue;
 	return node.operator === "==" || node.operator === "===" ? equal : !equal;
 }
-function replaceTypeofWindow(code, replacement) {
+function replaceTypeofWindow(code, replacement, id = "file.js") {
 	if (!/typeof\s+window/.test(code)) return null;
+	const extension = path.extname(id.split("?", 1)[0]);
+	const lang = extension === ".ts" || extension === ".mts" || extension === ".cts" ? "ts" : extension === ".tsx" ? "tsx" : extension === ".jsx" ? "jsx" : "js";
 	let ast;
 	try {
-		ast = parseAst(code);
+		ast = parseAst(code, { lang });
 	} catch {
 		return null;
 	}
 	const output = new MagicString(code);
 	let changed = false;
 	if (!isAstRecord(ast)) return null;
-	const rootScope = createScope(null);
-	collectScopeBindings(ast, rootScope);
-	collectVarBindings(ast, rootScope);
+	const rootScope = createAstScope(null);
+	collectDirectScopeBindings(ast, rootScope);
+	collectVarScopeBindings(ast, rootScope);
 	function visit(node, parentScope) {
 		if (isFunctionNode(node)) {
-			const parameterScope = createScope(parentScope);
+			const parameterScope = createAstScope(parentScope);
 			collectBindingNames(node.id, parameterScope.bindings);
 			for (const parameter of nodeArray(node.params)) {
 				collectBindingNames(parameter, parameterScope.bindings);
 				if (isAstRecord(parameter)) visit(parameter, parameterScope);
 			}
 			if (isAstRecord(node.body)) if (node.body.type === "BlockStatement") {
-				const bodyScope = createScope(parameterScope);
-				collectVarBindings(node.body, bodyScope);
+				const bodyScope = createAstScope(parameterScope);
+				collectDirectScopeBindings(node.body, bodyScope);
+				collectVarScopeBindings(node.body, bodyScope);
 				visit(node.body, bodyScope);
 			} else visit(node.body, parameterScope);
 			return;
 		}
+		if (node.type === "SwitchStatement") {
+			if (isAstRecord(node.discriminant)) visit(node.discriminant, parentScope);
+			const switchScope = createAstScope(parentScope);
+			collectSwitchScopeBindings(node, switchScope);
+			for (const switchCase of nodeArray(node.cases)) if (isAstRecord(switchCase)) visit(switchCase, switchScope);
+			return;
+		}
 		const scope = createChildScope(node, parentScope) ?? parentScope;
 		if (node.type === "IfStatement" && hasRange(node)) {
 			const result = evaluateTypeofWindowComparison(node.test, replacement, scope);
@@ -132,7 +104,7 @@ function replaceTypeofWindow(code, replacement) {
 				return;
 			}
 		}
-		if (node.type === "UnaryExpression" && node.operator === "typeof" && isIdentifierNamed(node.argument, "window") && !hasBinding(scope, "window") && hasRange(node)) {
+		if (node.type === "UnaryExpression" && node.operator === "typeof" && isIdentifierNamed(node.argument, "window") && !hasAstBinding(scope, "window") && hasRange(node)) {
 			output.overwrite(node.start, node.end, JSON.stringify(replacement));
 			changed = true;
 			return;

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

@@ -83,7 +83,12 @@ type AppRoute = {
   routePath: string | null; /** Ordered list of layout files from root to leaf */
   layouts: string[]; /** Ordered list of all discovered template files from root to leaf (not necessarily aligned 1:1 with layouts) */
   templates: string[]; /** Parallel route slots (from @slot directories at the route's directory level) */
-  parallelSlots: ParallelSlot[];
+  parallelSlots: ParallelSlot[]; /** Stable implicit children-slot identity for parallel-slot sub-route families. */
+  childrenSlot?: {
+    id: string;
+    ownerTreePath: string;
+    state: "active" | "default" | "unmatched";
+  };
   /**
    * Interception markers not wrapped in an `@slot` directory.
    * On soft-nav, the intercepting page replaces the entire page response.
@@ -122,7 +127,16 @@ type AppRoute = {
    * Includes route groups and dynamic segments (as template strings like "[id]").
    * Used at render time to compute the child segments for useSelectedLayoutSegments().
    */
-  routeSegments: string[]; /** Tree position (directory depth from app/ root) for each template. */
+  routeSegments: string[];
+  /**
+   * Active filesystem segments for the default `children` slot.
+   *
+   * Synthetic routes materialized only from named parallel-slot pages still
+   * use the full `routeSegments` for URL matching, params, and route identity,
+   * but their children slot renders the parent's default.tsx. In that case the
+   * active children segments remain at the parent route.
+   */
+  childrenRouteSegments?: string[]; /** Tree position (directory depth from app/ root) for each template. */
   templateTreePositions?: number[];
   /**
    * Tree position (directory depth from app/ root) for each layout.
@@ -276,6 +290,13 @@ type RouteManifest = {
   graphVersion: GraphVersion;
   segmentGraph: StaticSegmentGraph;
 };
+/**
+ * Build the App Router route graph by scanning `appDir`.
+ *
+ * `appDir` must be forward-slash. Every path in the graph is derived from it
+ * with `path.posix.*` and `findFile`, so a native appDir would produce mixed
+ * separators on Windows. Production callers normalize it at their entry.
+ */
 declare function buildAppRouteGraph(appDir: string, matcher: ValidFileMatcher): Promise<{
   routes: AppRouteGraphRoute[];
   routeManifest: RouteManifest;