@lovrozagar/flare 0.1.0

package/src/generators/index.ts

@@ -0,0 +1,1589 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, extname, join, posix } from "node:path";
+import { parse as babelParse } from "@babel/parser";
+import { parseSeconds } from "../duration/index.ts";
+import type { AuthenticateMode } from "../route-builder/types.ts";
+import { extractLayoutKey } from "../router-primitives/paths.ts";
+
+export type PrefetchStrategy = false | "intent" | "render" | "viewport";
+
+export type ExtractedStaticDeferMode = "resolve" | "stream";
+
+export interface ExtractedCacheConfig {
+	client?: {
+		cacheDeferred?: boolean;
+		gcTime?: number;
+		prefetch?: PrefetchStrategy;
+		prefetchGcTime?: number;
+		prefetchStaleTime?: number;
+		staleTime?: number;
+	};
+	isr?: true | "dynamic";
+	isrDefer?: ExtractedStaticDeferMode;
+	isrDynamicParams?: boolean;
+	isrRevalidate?: number;
+	ssg?: true | "dynamic";
+	ssgDefer?: ExtractedStaticDeferMode;
+}
+
+export interface ExtractedInterceptConfig {
+	from: string[];
+	render: string;
+}
+
+export interface RouteDefinition {
+	authenticateMode: AuthenticateMode;
+	exportName: string;
+	filePath: string;
+	cache: ExtractedCacheConfig;
+	hasInput: boolean;
+	intercept?: ExtractedInterceptConfig;
+	responseRoute: boolean;
+	type: "layout" | "page" | "path-segment" | "root-layout";
+	virtualPath: string;
+}
+
+export interface GenerateResult {
+	layouts: number;
+	routes: number;
+	warnings: string[];
+}
+
+/**
+ * Write a generated file with a checksum header.
+ * Skips the write when the existing file's checksum matches (idempotent).
+ */
+function writeGenFile(filePath: string, body: string, generator: string): void {
+	const normalized = body.replace(/\n*$/, "\n");
+	const hash = createHash("sha256").update(normalized).digest("hex").slice(0, 12);
+
+	const ext = filePath.endsWith(".d.ts") ? ".d.ts" : extname(filePath);
+	const header =
+		ext === ".sql"
+			? `-- @generated by ${generator} — do not edit. checksum: ${hash}`
+			: `/* @generated by ${generator} — do not edit. checksum: ${hash} */`;
+	const fullContent = `${header}\n${normalized}`;
+
+	if (existsSync(filePath)) {
+		const existing = readFileSync(filePath, "utf-8");
+		const firstLine = existing.split("\n")[0] ?? "";
+		const match = firstLine.match(/checksum: ([0-9a-f]{12})/);
+		if (match?.[1] === hash) return;
+	}
+
+	mkdirSync(dirname(filePath), { recursive: true });
+	writeFileSync(filePath, fullContent, "utf-8");
+}
+
+const BUILDER_TO_TYPE: Record<string, RouteDefinition["type"]> = {
+	createLayout: "layout",
+	createPage: "page",
+	createPathSegment: "path-segment",
+	createRootLayout: "root-layout",
+};
+
+/* Next export boundary — used to scope chain detection to the current definition */
+const NEXT_EXPORT_RE = /\nexport\s+const\s+/;
+
+const NUMERIC_RE = (key: string) => new RegExp(`${key}\\s*:\\s*([\\d_]+)`);
+const DURATION_STR_RE = (key: string) => new RegExp(`${key}\\s*:\\s*["'\`](\\d+[smhd])["'\`]`);
+const PREFETCH_RE = /prefetch\s*:\s*["'`](intent|render|viewport)["'`]/;
+
+/** Escape a string for safe interpolation into generated double-quoted JS/TS string literals. */
+function escapeCodegenStr(s: string): string {
+	return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r");
+}
+
+/**
+ * Skip past a string/template/comment at position i, returning the index of the last char consumed.
+ * Returns i unchanged if the character at i is not a string/comment opener.
+ */
+export function skipStringOrComment(code: string, start: number): number {
+	const ch = code[start];
+	let pos = start;
+
+	/* Single/double quoted strings */
+	if (ch === '"' || ch === "'") {
+		const q = ch;
+		pos++;
+		while (pos < code.length && code[pos] !== q) {
+			if (code[pos] === "\\") pos++;
+			pos++;
+		}
+		return pos;
+	}
+
+	/* Template literals */
+	if (ch === "`") {
+		pos++;
+		while (pos < code.length && code[pos] !== "`") {
+			if (code[pos] === "\\") {
+				pos++;
+			} else if (code[pos] === "$" && pos + 1 < code.length && code[pos + 1] === "{") {
+				pos += 2;
+				let tDepth = 1;
+				while (pos < code.length && tDepth > 0) {
+					if (code[pos] === "{") tDepth++;
+					else if (code[pos] === "}") tDepth--;
+					if (tDepth > 0) pos++;
+				}
+			}
+			pos++;
+		}
+		return pos;
+	}
+
+	/* Block comments */
+	if (ch === "/" && pos + 1 < code.length && code[pos + 1] === "*") {
+		pos += 2;
+		while (pos < code.length && !(code[pos] === "*" && pos + 1 < code.length && code[pos + 1] === "/")) {
+			pos++;
+		}
+		return pos + 1;
+	}
+
+	/* Line comments */
+	if (ch === "/" && pos + 1 < code.length && code[pos + 1] === "/") {
+		pos += 2;
+		while (pos < code.length && code[pos] !== "\n") pos++;
+		return pos;
+	}
+
+	return start;
+}
+
+/**
+ * Extract the full argument of `.cache(...)` by counting braces.
+ * Returns the text between the outermost `{` and `}`, or null if not found.
+ * String-aware: skips braces inside strings, template literals, and comments.
+ */
+function extractCacheArg(chainText: string): string | null {
+	const start = chainText.indexOf(".cache(");
+	if (start === -1) return null;
+
+	let depth = 0;
+	let openIdx = -1;
+	for (let i = start + 7; i < chainText.length; i++) {
+		const skipped = skipStringOrComment(chainText, i);
+		if (skipped !== i) {
+			i = skipped;
+			continue;
+		}
+		if (chainText[i] === "{") {
+			if (depth === 0) openIdx = i + 1;
+			depth++;
+		} else if (chainText[i] === "}") {
+			depth--;
+			if (depth === 0) return chainText.slice(openIdx, i);
+		}
+	}
+	return null;
+}
+
+/**
+ * Extract the content of a nested `key: { ... }` block from a config body.
+ */
+function extractNestedBlock(body: string, key: string): string | null {
+	const re = new RegExp(`${key}\\s*:\\s*\\{`);
+	const match = re.exec(body);
+	if (!match) return null;
+
+	let depth = 0;
+	const start = (match.index ?? 0) + match[0].length;
+	for (let i = start; i < body.length; i++) {
+		const skipped = skipStringOrComment(body, i);
+		if (skipped !== i) {
+			i = skipped;
+			continue;
+		}
+		if (body[i] === "{") depth++;
+		else if (body[i] === "}") {
+			if (depth === 0) return body.slice(start, i);
+			depth--;
+		}
+	}
+	return null;
+}
+
+function extractNumeric(text: string, key: string, unit?: "ms" | "s"): number | undefined {
+	/* try duration string first: key: "5m" */
+	const dm = DURATION_STR_RE(key).exec(text);
+	if (dm?.[1]) {
+		const seconds = parseSeconds(dm[1] as `${number}${"d" | "h" | "m" | "s"}`);
+		return unit === "ms" ? seconds * 1000 : seconds;
+	}
+	/* fall back to raw numeric: key: 5000 */
+	const m = NUMERIC_RE(key).exec(text);
+	if (!m) return undefined;
+	return Number((m[1] ?? "").replace(/_/g, ""));
+}
+
+export function extractCacheFromChain(chainText: string): ExtractedCacheConfig {
+	const config: ExtractedCacheConfig = {};
+
+	const body = extractCacheArg(chainText);
+	if (!body) return config;
+
+	/* client: { cacheDeferred, staleTime, gcTime, prefetch, prefetchStaleTime, prefetchGcTime } */
+	const clientBlock = extractNestedBlock(body, "client");
+	if (clientBlock) {
+		const client: NonNullable<ExtractedCacheConfig["client"]> = {};
+
+		if (/cacheDeferred\s*:\s*true/.test(clientBlock)) {
+			client.cacheDeferred = true;
+		}
+
+		const st = extractNumeric(clientBlock, "staleTime", "ms");
+		if (st !== undefined) client.staleTime = st;
+		const gc = extractNumeric(clientBlock, "gcTime", "ms");
+		if (gc !== undefined) client.gcTime = gc;
+		const pst = extractNumeric(clientBlock, "prefetchStaleTime", "ms");
+		if (pst !== undefined) client.prefetchStaleTime = pst;
+		const pgc = extractNumeric(clientBlock, "prefetchGcTime", "ms");
+		if (pgc !== undefined) client.prefetchGcTime = pgc;
+
+		const prefetchMatch = PREFETCH_RE.exec(clientBlock);
+		if (prefetchMatch) {
+			client.prefetch = prefetchMatch[1] as "intent" | "render" | "viewport";
+		}
+		if (/prefetch\s*:\s*false/.test(clientBlock)) {
+			client.prefetch = false;
+		}
+
+		if (Object.keys(client).length > 0) config.client = client;
+	}
+
+	/* ssg: true | () => ... | { defer?, params? } */
+	const ssgBlock = extractNestedBlock(body, "ssg");
+	if (ssgBlock) {
+		const hasParams = /params\s*:\s*(async\s+)?\(/.test(ssgBlock) || /params\s*:\s*(async\s+)?function/.test(ssgBlock);
+		config.ssg = hasParams ? "dynamic" : true;
+
+		const deferMatch = /defer\s*:\s*["'`](resolve|stream)["'`]/.exec(ssgBlock);
+		if (deferMatch) {
+			config.ssgDefer = deferMatch[1] as ExtractedStaticDeferMode;
+		}
+	} else if (/ssg\s*:\s*true/.test(body)) {
+		config.ssg = true;
+	} else if (/ssg\s*:\s*(async\s+)?\(/.test(body) || /ssg\s*:\s*(async\s+)?function/.test(body)) {
+		config.ssg = "dynamic";
+	}
+
+	/* isr: true | { revalidate?, params?, defer?, dynamicParams? } */
+	const isrBlock = extractNestedBlock(body, "isr");
+	if (isrBlock) {
+		const hasParams = /params\s*:\s*(async\s+)?\(/.test(isrBlock) || /params\s*:\s*(async\s+)?function/.test(isrBlock);
+		config.isr = hasParams ? "dynamic" : true;
+
+		const revalidate = extractNumeric(isrBlock, "revalidate", "s");
+		if (revalidate !== undefined) {
+			config.isrRevalidate = revalidate;
+		}
+
+		const deferMatch = /defer\s*:\s*["'`](resolve|stream)["'`]/.exec(isrBlock);
+		if (deferMatch) {
+			config.isrDefer = deferMatch[1] as ExtractedStaticDeferMode;
+		}
+
+		if (/dynamicParams\s*:\s*false/.test(isrBlock)) {
+			config.isrDynamicParams = false;
+		} else if (/dynamicParams\s*:\s*true/.test(isrBlock)) {
+			config.isrDynamicParams = true;
+		}
+	} else if (/isr\s*:\s*true/.test(body)) {
+		config.isr = true;
+	}
+
+	return config;
+}
+
+/**
+ * Extract the full argument of `.intercept(...)` by counting braces.
+ * Returns the text between the outermost `{` and `}`, or null if not found.
+ */
+function extractInterceptArg(chainText: string): string | null {
+	const start = chainText.indexOf(".intercept(");
+	if (start === -1) return null;
+
+	let depth = 0;
+	let openIdx = -1;
+	for (let i = start + 11; i < chainText.length; i++) {
+		const skipped = skipStringOrComment(chainText, i);
+		if (skipped !== i) {
+			i = skipped;
+			continue;
+		}
+		if (chainText[i] === "{") {
+			if (depth === 0) openIdx = i + 1;
+			depth++;
+		} else if (chainText[i] === "}") {
+			depth--;
+			if (depth === 0) return chainText.slice(openIdx, i);
+		}
+	}
+	return null;
+}
+
+export function extractInterceptFromChain(chainText: string): ExtractedInterceptConfig | undefined {
+	const body = extractInterceptArg(chainText);
+	if (!body) return undefined;
+
+	/* Extract from: [...] array */
+	const fromMatch = /from\s*:\s*\[([^\]]*)\]/.exec(body);
+	if (!fromMatch) return undefined;
+	const fromRaw = fromMatch[1] ?? "";
+	const from = fromRaw
+		.split(",")
+		.map((s) => s.trim().replace(/^["'`]|["'`]$/g, ""))
+		.filter((s) => s.length > 0);
+
+	/* Extract render: "..." string */
+	const renderMatch = /render\s*:\s*["'`]([^"'`]+)["'`]/.exec(body);
+	if (!renderMatch) return undefined;
+	const render = renderMatch[1] ?? "";
+
+	if (from.length === 0 || render.length === 0) return undefined;
+
+	return { from, render };
+}
+
+/**
+ * Unwrap a member expression chain to find the root callee name.
+ * e.g. `createPage("x").cache({}).authenticate()` → the root call is `createPage`.
+ */
+function findRootCallee(node: unknown): string | null {
+	const n = node as Record<string, unknown>;
+	if (n.type === "Identifier") return n.name as string;
+	if (n.type === "CallExpression") return findRootCallee(n.callee);
+	if (n.type === "MemberExpression") return findRootCallee(n.object);
+	return null;
+}
+
+/**
+ * Extract the first string argument from a CallExpression node's arguments.
+ * Handles the innermost call in a chain by recursing into callee.
+ */
+function findInnermostCallArgs(node: unknown): unknown[] | null {
+	const n = node as Record<string, unknown>;
+	if (n.type !== "CallExpression") return null;
+
+	const callee = n.callee as Record<string, unknown>;
+	if (callee.type === "Identifier") return n.arguments as unknown[];
+	if (callee.type === "MemberExpression") {
+		const obj = callee.object as Record<string, unknown>;
+		return findInnermostCallArgs(obj);
+	}
+	if (callee.type === "CallExpression") return findInnermostCallArgs(callee);
+	return null;
+}
+
+function extractStringValue(node: unknown): string | null {
+	const n = node as Record<string, unknown>;
+	if (n.type === "StringLiteral") return n.value as string;
+	if (n.type === "TemplateLiteral") {
+		const quasis = n.quasis as Array<Record<string, unknown>>;
+		if (quasis.length === 1) {
+			const cooked = (quasis[0] as Record<string, unknown>).value as Record<string, unknown>;
+			return cooked.cooked as string;
+		}
+	}
+	return null;
+}
+
+export function extractRouteDefinitions(src: string, filePath: string): RouteDefinition[] {
+	let ast: ReturnType<typeof babelParse>;
+	try {
+		ast = babelParse(src, {
+			plugins: ["typescript", "jsx"],
+			sourceType: "module",
+		});
+	} catch {
+		return [];
+	}
+
+	const results: RouteDefinition[] = [];
+
+	for (const stmt of ast.program.body) {
+		if (stmt.type !== "ExportNamedDeclaration") continue;
+		const decl = stmt.declaration;
+		if (!decl || decl.type !== "VariableDeclaration") continue;
+
+		for (const declarator of decl.declarations) {
+			if (declarator.id.type !== "Identifier") continue;
+			if (!declarator.init) continue;
+
+			const rootCallee = findRootCallee(declarator.init);
+			if (!rootCallee) continue;
+
+			const type = BUILDER_TO_TYPE[rootCallee];
+			if (!type) continue;
+
+			const args = findInnermostCallArgs(declarator.init);
+			if (!args || args.length === 0) continue;
+
+			const virtualPath = extractStringValue(args[0]);
+			if (!virtualPath) continue;
+
+			const exportName = declarator.id.name;
+
+			/* Scope chain to text between this declaration's init start and next export boundary */
+			const initStart = declarator.init.start ?? 0;
+			const rest = src.slice(initStart);
+			const nextExport = NEXT_EXPORT_RE.exec(rest);
+			const chainText = nextExport ? rest.slice(0, nextExport.index) : rest;
+
+			const hasAuthenticateOptional = /\.authenticateOptional\s*\(/.test(chainText);
+			const hasAuthenticate = /\.authenticate\s*\(/.test(chainText);
+			const authenticateMode: AuthenticateMode = hasAuthenticateOptional ? "optional" : !!hasAuthenticate;
+			const hasInput = /\.input\s*(?:<[^>]*>)?\s*\(/.test(chainText);
+			const responseRoute = /\.response\s*\(/.test(chainText);
+			const cache = extractCacheFromChain(chainText);
+			const intercept = extractInterceptFromChain(chainText);
+
+			results.push({
+				authenticateMode,
+				cache,
+				exportName,
+				filePath,
+				hasInput,
+				intercept,
+				responseRoute,
+				type,
+				virtualPath,
+			});
+		}
+	}
+
+	return results;
+}
+
+export function validateRouteDefinitions(defs: RouteDefinition[]): string[] {
+	const errors: string[] = [];
+	const pages = new Map<string, string>();
+	const layouts = new Map<string, string>();
+	const rootLayouts = new Map<string, string>();
+
+	/* 1. Virtual path uniqueness per type */
+	for (const def of defs) {
+		let bucket = pages;
+		if (def.type === "root-layout") bucket = rootLayouts;
+		else if (def.type === "layout") bucket = layouts;
+		const existing = bucket.get(def.virtualPath);
+		if (existing) {
+			errors.push(`Duplicate ${def.type} at "${def.virtualPath}" in ${def.filePath} (already defined in ${existing})`);
+		} else {
+			bucket.set(def.virtualPath, def.filePath);
+		}
+	}
+
+	/* 2. Variable path conflicts (different virtual paths → same resolved URL) */
+	const pagesByVarPath = new Map<string, { filePath: string; virtualPath: string }>();
+	for (const def of defs) {
+		if (def.type !== "page") continue;
+		const varPath = computeUrlPattern(def.virtualPath);
+		const existing = pagesByVarPath.get(varPath);
+		if (existing && existing.virtualPath !== def.virtualPath) {
+			errors.push(
+				`Variable path conflict: "${def.virtualPath}" and "${existing.virtualPath}" both resolve to "${varPath}" (${def.filePath} vs ${existing.filePath})`,
+			);
+		} else if (!existing) {
+			pagesByVarPath.set(varPath, { filePath: def.filePath, virtualPath: def.virtualPath });
+		}
+	}
+
+	/* 3. Pre-root segments must be param-only */
+	for (const def of defs) {
+		const parts = def.virtualPath.split("/");
+		const rootIdx = parts.findIndex((p) => p.startsWith("_") && p.endsWith("_") && p.length >= 3);
+		if (rootIdx > 0) {
+			for (let i = 0; i < rootIdx; i++) {
+				const seg = parts[i] ?? "";
+				if (!seg.startsWith("[")) {
+					errors.push(
+						`Invalid pre-root segment "${seg}" in "${def.virtualPath}" (${def.filePath}). Only [param], [[param]], [...param], [[...param]] segments allowed before root layout.`,
+					);
+				}
+			}
+		}
+	}
+
+	/* 4. Catch-all conflicts: a catch-all page shadows a more specific sibling page */
+	const pageDefs = defs.filter((d) => d.type === "page");
+	for (const catchAll of pageDefs) {
+		const parts = catchAll.virtualPath.split("/");
+		const lastPart = parts[parts.length - 1] ?? "";
+		if (!lastPart.startsWith("[...") && !lastPart.startsWith("[[...")) continue;
+
+		const prefix = parts.slice(0, -1).join("/");
+		for (const other of pageDefs) {
+			if (other === catchAll) continue;
+			if (other.virtualPath.startsWith(`${prefix}/`) && other.virtualPath !== catchAll.virtualPath) {
+				errors.push(
+					`Catch-all conflict: "${catchAll.virtualPath}" shadows "${other.virtualPath}" (${catchAll.filePath} vs ${other.filePath})`,
+				);
+			}
+		}
+	}
+
+	return errors;
+}
+
+function computeUrlPattern(virtualPath: string): string {
+	/* Remove root prefix (+ pre-root segments) and group segments */
+	const parts = virtualPath.split("/");
+	const rootIdx = parts.findIndex((p) => p.startsWith("_") && p.endsWith("_") && p.length >= 3);
+	const urlParts: string[] = [];
+
+	for (let i = 0; i < parts.length; i++) {
+		const part = parts[i] ?? "";
+		/* Skip the root layout segment itself (e.g. _root_) */
+		if (i === rootIdx) continue;
+		/* Skip non-param pre-root segments */
+		if (rootIdx >= 0 && i < rootIdx && !part.startsWith("[")) continue;
+		/* Skip group segments (e.g. (shop)) */
+		if (part.startsWith("(") && part.endsWith(")")) continue;
+		/* Skip empty segments (trailing slash = index route) */
+		if (part === "") continue;
+		urlParts.push(part);
+	}
+
+	const url = `/${urlParts.join("/")}`;
+	return url === "" ? "/" : url;
+}
+
+function relativeImportPath(from: string, to: string): string {
+	const fromParts = from.split("/");
+	const toParts = to.split("/");
+
+	/* Remove filename from 'from' */
+	fromParts.pop();
+
+	/* Find common prefix */
+	let common = 0;
+	while (common < fromParts.length && common < toParts.length && fromParts[common] === toParts[common]) {
+		common++;
+	}
+
+	const ups = fromParts.length - common;
+	const downs = toParts.slice(common);
+
+	const prefix = ups > 0 ? Array(ups).fill("..").join("/") : ".";
+
+	/* Remove .ts/.tsx extension */
+	const last = downs[downs.length - 1] ?? "";
+	downs[downs.length - 1] = last.replace(/\.(tsx?|ts)$/, "");
+
+	return `${prefix}/${downs.join("/")}`;
+}
+
+function formatRouteMeta(def: RouteDefinition): string {
+	const parts: string[] = [];
+	if (def.authenticateMode === true) parts.push("authenticate: true");
+	else if (def.authenticateMode === "optional") parts.push(`authenticate: "optional"`);
+
+	if (def.cache.client) {
+		const cp: string[] = [];
+		if (def.cache.client.cacheDeferred === true) cp.push("cacheDeferred: true");
+		if (def.cache.client.staleTime !== undefined) cp.push(`staleTime: ${def.cache.client.staleTime}`);
+		if (def.cache.client.gcTime !== undefined) cp.push(`gcTime: ${def.cache.client.gcTime}`);
+		if (def.cache.client.prefetch !== undefined) {
+			const pv = def.cache.client.prefetch;
+			cp.push(pv === false ? "prefetch: false" : `prefetch: "${pv}"`);
+		}
+		if (def.cache.client.prefetchStaleTime !== undefined)
+			cp.push(`prefetchStaleTime: ${def.cache.client.prefetchStaleTime}`);
+		if (def.cache.client.prefetchGcTime !== undefined) cp.push(`prefetchGcTime: ${def.cache.client.prefetchGcTime}`);
+		if (cp.length > 0) parts.push(`client: { ${cp.join(", ")} }`);
+	}
+
+	if (def.cache.isr) {
+		const sp: string[] = [`mode: "isr"`];
+		if (def.cache.isrDefer) sp.push(`defer: "${def.cache.isrDefer}"`);
+		if (def.cache.isrDynamicParams === false) {
+			sp.push("dynamicParams: false");
+		}
+		if (def.cache.isrRevalidate !== undefined) {
+			sp.push(`revalidate: ${def.cache.isrRevalidate}`);
+		}
+		parts.push(`static: { ${sp.join(", ")} }`);
+	} else if (def.cache.ssg) {
+		const sp: string[] = [`mode: "static"`];
+		if (def.cache.ssgDefer) sp.push(`defer: "${def.cache.ssgDefer}"`);
+		parts.push(`static: { ${sp.join(", ")} }`);
+	}
+
+	if (def.intercept) {
+		const fromArr = def.intercept.from.map((f) => `"${escapeCodegenStr(f)}"`).join(", ");
+		parts.push(`intercept: { from: [${fromArr}], render: "${escapeCodegenStr(def.intercept.render)}" }`);
+	}
+
+	return parts.length > 0 ? ` ${parts.join(", ")} ` : "";
+}
+
+export function generateRouteInserts(defs: RouteDefinition[], outputDir: string): string {
+	const pages = defs.filter((d) => d.type === "page");
+	const lines: string[] = [];
+
+	for (const def of pages) {
+		const urlPattern = computeUrlPattern(def.virtualPath);
+		const importPath = relativeImportPath(`${outputDir}/routes.gen.ts`, def.filePath);
+		const routeType = def.responseRoute ? "x" : "r";
+		const meta = formatRouteMeta(def);
+
+		lines.push(
+			`insertRoute(tree, "${escapeCodegenStr(urlPattern)}", {`,
+			`\te: "${escapeCodegenStr(def.exportName)}",`,
+			`\to: {${meta}},`,
+			`\tp: () => import("${escapeCodegenStr(importPath)}").then(m => ({ default: m["${escapeCodegenStr(def.exportName)}"] })),`,
+			`\tt: "${routeType}",`,
+			`\tv: "${escapeCodegenStr(urlPattern)}",`,
+			`\tx: "${escapeCodegenStr(def.virtualPath)}",`,
+			"})",
+			"",
+		);
+	}
+
+	return lines.join("\n");
+}
+
+export function generateLayoutsRecord(defs: RouteDefinition[], outputDir: string): string {
+	const layouts = defs.filter((d) => d.type === "layout" || d.type === "root-layout" || d.type === "path-segment");
+
+	if (layouts.length === 0) {
+		return [
+			"export const layouts: Record<string, () => Promise<{ default: unknown }>> = {}",
+			"export const layoutModuleIds: Record<string, string> = {}",
+		].join("\n");
+	}
+
+	const entries: string[] = [];
+	const moduleIdEntries: string[] = [];
+	for (const def of layouts) {
+		const importPath = relativeImportPath(`${outputDir}/routes.gen.ts`, def.filePath);
+		const key = def.type === "path-segment" ? extractLayoutKey(def.virtualPath) : def.virtualPath;
+		entries.push(
+			`\t"${escapeCodegenStr(key)}": () => import("${escapeCodegenStr(importPath)}").then(m => ({ default: m["${escapeCodegenStr(def.exportName)}"] })),`,
+		);
+		moduleIdEntries.push(`\t"${escapeCodegenStr(key)}": "${escapeCodegenStr(def.filePath)}",`);
+	}
+
+	return [
+		"export const layouts: Record<string, () => Promise<{ default: unknown }>> = {",
+		...entries,
+		"}",
+		"",
+		"export const layoutModuleIds: Record<string, string> = {",
+		...moduleIdEntries,
+		"}",
+	].join("\n");
+}
+
+export interface TreeBuildNode {
+	c?: TreeBuildNode;
+	n?: string;
+	o?: TreeBuildNode;
+	p?: TreeBuildNode;
+	q?: TreeBuildNode;
+	routeKey?: string;
+	s: Record<string, TreeBuildNode>;
+}
+
+function createBuildNode(paramName?: string): TreeBuildNode {
+	const node: TreeBuildNode = { s: {} };
+	if (paramName !== undefined) node.n = paramName;
+	return node;
+}
+
+export function buildRouteTree(routes: Array<{ routeKey: string; urlPattern: string }>): TreeBuildNode {
+	const root = createBuildNode();
+
+	for (const { routeKey, urlPattern } of routes) {
+		const segments = urlPattern.split("/").filter((seg) => seg.length > 0);
+		let node = root;
+
+		for (const segment of segments) {
+			const optionalCatchAll = segment.match(/^\[\[\.\.\.(\w+)\]\]$/);
+			if (optionalCatchAll) {
+				if (!node.o) node.o = createBuildNode(optionalCatchAll[1]);
+				node = node.o;
+				continue;
+			}
+
+			const optionalParam = segment.match(/^\[\[(\w+)\]\]$/);
+			if (optionalParam) {
+				if (!node.q) node.q = createBuildNode(optionalParam[1]);
+				node = node.q;
+				continue;
+			}
+
+			const catchAll = segment.match(/^\[\.\.\.(\w+)\]$/);
+			if (catchAll) {
+				if (!node.c) node.c = createBuildNode(catchAll[1]);
+				node = node.c;
+				continue;
+			}
+
+			const param = segment.match(/^\[(\w+)\]$/);
+			if (param) {
+				if (!node.p) node.p = createBuildNode(param[1]);
+				node = node.p;
+				continue;
+			}
+
+			const key = segment.toLowerCase();
+			let child = node.s[key];
+			if (!child) {
+				child = createBuildNode();
+				node.s[key] = child;
+			}
+			node = child;
+		}
+
+		node.routeKey = routeKey;
+	}
+
+	return root;
+}
+
+const VALID_IDENT_RE = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+
+function quoteKey(key: string): string {
+	return VALID_IDENT_RE.test(key) ? key : `"${key}"`;
+}
+
+export function serializeTreeNode(node: TreeBuildNode): string {
+	const parts: string[] = [];
+
+	if (node.c) parts.push(`c: ${serializeTreeNode(node.c)}`);
+	if (node.n !== undefined) parts.push(`n: "${node.n}"`);
+	if (node.o) parts.push(`o: ${serializeTreeNode(node.o)}`);
+	if (node.p) parts.push(`p: ${serializeTreeNode(node.p)}`);
+	if (node.q) parts.push(`q: ${serializeTreeNode(node.q)}`);
+	if (node.routeKey) parts.push(`r: ${node.routeKey}`);
+
+	const entries = Object.entries(node.s);
+	if (entries.length === 0) {
+		parts.push("s: E");
+	} else {
+		const serialized = entries.map(([k, child]) => `${quoteKey(k)}: ${serializeTreeNode(child)}`).join(", ");
+		parts.push(`s: S({ ${serialized} })`);
+	}
+
+	return `{ ${parts.join(", ")} }`;
+}
+
+function serializeRouteMeta(def: RouteDefinition): string {
+	const meta = formatRouteMeta(def);
+	return `{${meta}}`;
+}
+
+export function generateRoutesFile(defs: RouteDefinition[], outputDir: string): string {
+	const pages = defs.filter((d) => d.type === "page");
+	const layouts = generateLayoutsRecord(defs, outputDir);
+
+	/* Detect whether any auth routes exist (for auth type derivation) */
+	const hasAuth = defs.some(
+		(d) => !d.responseRoute && (d.authenticateMode === true || d.authenticateMode === "optional"),
+	);
+
+	/* Detect whether any pages have .input() for search params typing */
+	const hasSearchParams = pages.some((d) => !d.responseRoute && d.hasInput);
+
+	/* Detect queryClientGetter in router source */
+	const routerFilePath = posix.join(posix.dirname(outputDir), "router");
+	let hasQueryClient = false;
+	for (const ext of [".ts", ".tsx"]) {
+		try {
+			const routerSource = readFileSync(`${routerFilePath}${ext}`, "utf-8");
+			if (routerSource.includes("queryClientGetter")) {
+				hasQueryClient = true;
+			}
+			break;
+		} catch {
+			/* file doesn't exist with this extension */
+		}
+	}
+
+	const serverHandler = resolveCreateServerExport(outputDir);
+	const registry = generateRouteRegistry(defs, outputDir, hasAuth, hasQueryClient, serverHandler !== null);
+
+	/* Deduplicate meta objects */
+	const metaMap = new Map<string, string>();
+	const metaDecls: string[] = [];
+	let metaIdx = 0;
+
+	for (const def of pages) {
+		const metaStr = serializeRouteMeta(def);
+		if (!metaMap.has(metaStr)) {
+			const varName = `O${metaIdx++}`;
+			metaMap.set(metaStr, varName);
+			metaDecls.push(`const ${varName} = ${metaStr} as const`);
+		}
+	}
+
+	/* Build route declarations */
+	const routeDecls: string[] = [];
+	const treeInputs: Array<{ routeKey: string; urlPattern: string }> = [];
+
+	for (let i = 0; i < pages.length; i++) {
+		const def = pages[i];
+		if (!def) continue;
+		const routeKey = `R${i}`;
+		const urlPattern = computeUrlPattern(def.virtualPath);
+		const importPath = relativeImportPath(`${outputDir}/routes.gen.ts`, def.filePath);
+		const routeType = def.responseRoute ? "x" : "r";
+		const metaVar = metaMap.get(serializeRouteMeta(def));
+
+		routeDecls.push(
+			[
+				`const ${routeKey}: RouteData = {`,
+				`\te: "${def.exportName}",`,
+				`\tf: "${def.filePath}",`,
+				`\to: ${metaVar},`,
+				`\tp: () => import("${importPath}").then(m => ({ default: m.${def.exportName} })),`,
+				`\tt: "${routeType}",`,
+				`\tv: "${urlPattern}",`,
+				`\tx: "${def.virtualPath}",`,
+				"}",
+			].join("\n"),
+		);
+
+		treeInputs.push({ routeKey, urlPattern });
+	}
+
+	/* Build and serialize tree */
+	const tree = buildRouteTree(treeInputs);
+	const treeStr = serializeTreeNode(tree);
+
+	const flareImports: string[] = ["TreeNode"];
+	if (pages.length > 0) flareImports.push("RouteData");
+	if (hasSearchParams) flareImports.push("InferParams", "InferSearchParams");
+	flareImports.sort();
+
+	const lines: string[] = [
+		"/* Auto-generated by flare — do not edit */",
+		`import type { ${flareImports.join(", ")} } from "@lovrozagar/flare/codegen"`,
+	];
+	if (serverHandler) {
+		lines.push(`import type { ${serverHandler.exportName} as _FlareHandler } from "${serverHandler.importPath}"`);
+	}
+	lines.push("", "const E: Record<string, TreeNode> = Object.create(null)");
+
+	if (treeStr.includes("S(")) {
+		lines.push(
+			"function S(o: Record<string, TreeNode>): Record<string, TreeNode> { return Object.assign(Object.create(null), o) }",
+		);
+	}
+
+	if (metaDecls.length > 0) {
+		lines.push("", ...metaDecls);
+	}
+
+	if (routeDecls.length > 0) {
+		lines.push("", ...routeDecls);
+	}
+
+	lines.push("", `export const routeTree: TreeNode = ${treeStr}`, "", layouts, registry);
+
+	return lines.join("\n");
+}
+
+export interface RouteParam {
+	name: string;
+	type: string;
+}
+
+/** Extract param names and types from a URL pattern. */
+export function extractParamsFromPattern(urlPattern: string): RouteParam[] {
+	const params: RouteParam[] = [];
+	const parts = urlPattern.split("/");
+
+	for (const part of parts) {
+		/* Optional catch-all: [[...name]] */
+		const optCatch = part.match(/^\[\[\.\.\.(.+?)\]\]$/);
+		if (optCatch) {
+			params.push({ name: optCatch[1] ?? "", type: "string[] | undefined" });
+			continue;
+		}
+		/* Required catch-all: [...name] */
+		const reqCatch = part.match(/^\[\.\.\.(.+?)\]$/);
+		if (reqCatch) {
+			params.push({ name: reqCatch[1] ?? "", type: "string[]" });
+			continue;
+		}
+		/* Optional single param: [[name]] */
+		const optSingle = part.match(/^\[\[(\w+)\]\]$/);
+		if (optSingle) {
+			params.push({ name: optSingle[1] ?? "", type: "string | undefined" });
+			continue;
+		}
+		/* Required single param: [name] */
+		const single = part.match(/^\[(.+?)\]$/);
+		if (single) {
+			params.push({ name: single[1] ?? "", type: "string" });
+		}
+	}
+
+	return params.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Compute parent layout virtualPaths for a given route, sorted root-first. */
+export function computeParentLayouts(virtualPath: string, layoutPaths: string[]): string[] {
+	return layoutPaths
+		.filter((lp) => lp !== virtualPath && virtualPath.startsWith(`${lp}/`))
+		.sort((a, b) => a.length - b.length);
+}
+
+/** Generate virtual module type declarations as a reference to the flare package types. */
+export function generateVirtualModuleTypes(): string {
+	return `/// <reference types="vite/client" />\n/// <reference types="@lovrozagar/flare/virtual-types" />\n`;
+}
+
+function resolveCreateServerExport(outputDir: string): { exportName: string; importPath: string } | null {
+	const serverFilePath = posix.join(posix.dirname(outputDir), "server");
+	for (const ext of [".ts", ".tsx"]) {
+		try {
+			const serverSource = readFileSync(`${serverFilePath}${ext}`, "utf-8");
+			const match = serverSource.match(/export\s+const\s+(\w+)\s*=\s*createServer/);
+			if (match?.[1]) {
+				return {
+					exportName: match[1],
+					importPath: relativeImportPath(`${outputDir}/routes.gen.ts`, serverFilePath),
+				};
+			}
+		} catch {
+			/* missing extension */
+		}
+	}
+	return null;
+}
+
+/** Generate TypeScript declaration merging block for route type registry. */
+export function generateRouteRegistry(
+	defs: RouteDefinition[],
+	outputDir: string,
+	hasAuth?: boolean,
+	hasQueryClient?: boolean,
+	hasServer = false,
+): string {
+	/* routes: URL path → params (pages only, no response routes) */
+	const pages = defs
+		.filter((d) => d.type === "page" && !d.responseRoute)
+		.map((d) => ({
+			params: extractParamsFromPattern(computeUrlPattern(d.virtualPath)),
+			url: computeUrlPattern(d.virtualPath),
+		}))
+		.sort((a, b) => a.url.localeCompare(b.url));
+
+	const routeEntries: string[] = [];
+	for (const page of pages) {
+		if (page.params.length === 0) {
+			routeEntries.push(`\t\t\t"${escapeCodegenStr(page.url)}": {}`);
+		} else {
+			const paramEntries = page.params.map((p) => `${p.name}: ${p.type}`).join(", ");
+			routeEntries.push(`\t\t\t"${escapeCodegenStr(page.url)}": { params: { ${paramEntries} } }`);
+		}
+	}
+
+	/* routeModules: virtualPath → typeof import(...)["exportName"] (all non-response) */
+	const moduleDefs = defs.filter((d) => !d.responseRoute).sort((a, b) => a.virtualPath.localeCompare(b.virtualPath));
+
+	const moduleEntries: string[] = [];
+	for (const def of moduleDefs) {
+		const importPath = relativeImportPath(`${outputDir}/routes.gen.ts`, def.filePath);
+		moduleEntries.push(
+			`\t\t\t"${escapeCodegenStr(def.virtualPath)}": typeof import("${escapeCodegenStr(importPath)}")["${escapeCodegenStr(def.exportName)}"]`,
+		);
+	}
+
+	/* routeParents: virtualPath → parent layout chain tuple */
+	const layoutPaths = defs.filter((d) => d.type === "layout" || d.type === "root-layout").map((d) => d.virtualPath);
+
+	const parentEntries: string[] = [];
+	for (const def of moduleDefs) {
+		const parents = computeParentLayouts(def.virtualPath, layoutPaths);
+		if (parents.length === 0) {
+			parentEntries.push(`\t\t\t"${escapeCodegenStr(def.virtualPath)}": []`);
+		} else {
+			const tuple = parents.map((p) => `"${escapeCodegenStr(p)}"`).join(", ");
+			parentEntries.push(`\t\t\t"${escapeCodegenStr(def.virtualPath)}": [${tuple}]`);
+		}
+	}
+
+	/* authModes: virtualPath → AuthenticateMode (only for non-false entries) */
+	const authEntries: string[] = [];
+	for (const def of moduleDefs) {
+		if (def.authenticateMode === true) {
+			authEntries.push(`\t\t\t"${escapeCodegenStr(def.virtualPath)}": true`);
+		} else if (def.authenticateMode === "optional") {
+			authEntries.push(`\t\t\t"${escapeCodegenStr(def.virtualPath)}": "optional"`);
+		}
+	}
+
+	const lines = [
+		"",
+		"/* Route type registry — auto-generated */",
+		'declare module "@lovrozagar/flare/codegen" {',
+		"\tinterface FlareRegister {",
+		"\t\troutes: {",
+		...routeEntries,
+		"\t\t}",
+		"\t\trouteModules: {",
+		...moduleEntries,
+		"\t\t}",
+		"\t\trouteParents: {",
+		...parentEntries,
+		"\t\t}",
+	];
+
+	if (authEntries.length > 0) {
+		lines.push("\t\tauthModes: {");
+		lines.push(...authEntries);
+		lines.push("\t\t}");
+	}
+
+	/* routeSearchParams: URL path → InferSearchParams for pages with .input() */
+	const searchEntries: string[] = [];
+	for (const page of pages) {
+		const def = defs.find((d) => !d.responseRoute && d.hasInput && computeUrlPattern(d.virtualPath) === page.url);
+		if (def) {
+			const importPath = relativeImportPath(`${outputDir}/routes.gen.ts`, def.filePath);
+			searchEntries.push(
+				`\t\t\t"${escapeCodegenStr(page.url)}": InferSearchParams<typeof import("${escapeCodegenStr(importPath)}")["${escapeCodegenStr(def.exportName)}"]>`,
+			);
+		}
+	}
+
+	if (searchEntries.length > 0) {
+		lines.push("\t\trouteSearchParams: {");
+		lines.push(...searchEntries);
+		lines.push("\t\t}");
+	}
+
+	/* routeParams: URL path → InferParams for pages with .input() */
+	const paramInferEntries: string[] = [];
+	for (const page of pages) {
+		const def = defs.find((d) => !d.responseRoute && d.hasInput && computeUrlPattern(d.virtualPath) === page.url);
+		if (def) {
+			const importPath = relativeImportPath(`${outputDir}/routes.gen.ts`, def.filePath);
+			paramInferEntries.push(
+				`\t\t\t"${escapeCodegenStr(page.url)}": InferParams<typeof import("${escapeCodegenStr(importPath)}")["${escapeCodegenStr(def.exportName)}"]>`,
+			);
+		}
+	}
+
+	if (paramInferEntries.length > 0) {
+		lines.push("\t\trouteParams: {");
+		lines.push(...paramInferEntries);
+		lines.push("\t\t}");
+	}
+
+	if (hasServer && hasAuth) {
+		lines.push(`\t\tauth: NonNullable<Awaited<ReturnType<NonNullable<typeof _FlareHandler["authenticateFn"]>>>>`);
+	}
+
+	if (hasServer) {
+		lines.push(`\t\tenv: Parameters<typeof _FlareHandler["fetch"]>[1]`);
+		lines.push(`\t\tserverContext: Awaited<ReturnType<NonNullable<typeof _FlareHandler["serverContext"]>>>`);
+	}
+	if (hasQueryClient) {
+		lines.push("\t\thasQueryClient: true");
+	}
+
+	lines.push("\t}", "}", "");
+	return lines.join("\n");
+}
+
+export interface ScanOptions {
+	ignorePrefix?: string;
+	rootDir: string;
+	srcDir?: string;
+}
+
+export function scanSourceFiles(options: ScanOptions): RouteDefinition[] {
+	const srcPath = join(options.rootDir, options.srcDir ?? "src");
+	const prefix = options.ignorePrefix ?? "_";
+	const defs: RouteDefinition[] = [];
+
+	let entries: string[];
+	try {
+		entries = readdirSync(srcPath, { recursive: true }) as string[];
+	} catch {
+		return defs;
+	}
+
+	for (const entry of entries) {
+		/* Normalize to posix separators */
+		const rel = entry.replace(/\\/g, "/");
+
+		/* Skip non-ts files */
+		if (!rel.endsWith(".ts") && !rel.endsWith(".tsx")) continue;
+
+		/* Skip generated files and node_modules */
+		if (rel.includes("_gen/") || rel.includes("node_modules")) continue;
+		if (rel.endsWith(".gen.ts") || rel.endsWith(".gen.tsx")) continue;
+
+		/* Skip directories starting with ignorePrefix (except _word_ route convention like _root_) */
+		const segments = rel.split("/");
+		/* _word_ or __word__ patterns are route conventions, not ignored dirs */
+		const isRouteConvention = (seg: string) => /^_[^_].*[^_]_$|^__[^_].*[^_]__$/.test(seg);
+		const hasIgnoredDir = segments.some(
+			(seg, i) => i < segments.length - 1 && seg.startsWith(prefix) && !isRouteConvention(seg),
+		);
+		if (hasIgnoredDir) continue;
+
+		const fullPath = posix.join(srcPath, rel);
+		let content: string;
+		try {
+			content = readFileSync(fullPath, "utf-8");
+		} catch {
+			continue;
+		}
+
+		defs.push(...extractRouteDefinitions(content, posix.join(options.srcDir ?? "src", rel)));
+	}
+
+	return defs;
+}
+
+/* ── Filesystem-based codegen ─────────────────────────────────────── */
+
+const ROUTE_SUFFIX_RE = /\.(page|layout|root-layout|path-segment)\.(tsx?|jsx?)$/;
+
+const BUILDER_EXPORT_RE =
+	/export\s+const\s+\w+\s*=\s*(createPage|createLayout|createRootLayout|createPathSegment)\s*(?:<[^>]*>)?\s*\(/;
+
+const ROOT_SCOPE_RE = /^_[^/]+_$/;
+
+export type FsLayoutIssueKind = "missing-root-scope" | "string-style-route" | "suffix-outside-routes";
+
+export interface FsLayoutIssue {
+	filePath: string;
+	kind: FsLayoutIssueKind;
+	line?: number;
+	message: string;
+}
+
+export function formatFsLayoutWarning(issue: FsLayoutIssue): string {
+	const loc = issue.line !== undefined ? `${issue.filePath}:${issue.line}` : issue.filePath;
+	return `${loc} — ${issue.message}`;
+}
+
+/** Detect route type from filename suffix. Returns null for non-route files. */
+export function detectRouteType(fileName: string): RouteDefinition["type"] | null {
+	const match = ROUTE_SUFFIX_RE.exec(fileName);
+	if (!match) return null;
+	return (match[1] ?? null) as RouteDefinition["type"] | null;
+}
+
+const BUILDER_MAP: Record<RouteDefinition["type"], string> = {
+	layout: "createLayout",
+	page: "createPage",
+	"path-segment": "createPathSegment",
+	"root-layout": "createRootLayout",
+};
+
+const BUILDER_SUBPATH_MAP: Record<string, string> = {
+	createLayout: "@lovrozagar/flare/layout",
+	createPage: "@lovrozagar/flare/page",
+	createPathSegment: "@lovrozagar/flare/path-segment",
+	createRootLayout: "@lovrozagar/flare/root-layout",
+};
+
+function builderSubpath(fn: string): string {
+	return BUILDER_SUBPATH_MAP[fn] ?? `@lovrozagar/flare/${fn.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`;
+}
+
+/**
+ * Derive a virtual path from a file's position in the routes/ directory.
+ * Folder structure maps directly to virtual path. Returns null for ignored dirs.
+ */
+export function deriveVirtualPath(filePath: string, routesDir: string): string | null {
+	const withoutRoutes = filePath.startsWith(`${routesDir}/`) ? filePath.slice(routesDir.length + 1) : filePath;
+	const segments = withoutRoutes.split("/");
+
+	/* Remove filename */
+	segments.pop();
+
+	const pathParts: string[] = [];
+
+	for (const seg of segments) {
+		/* [_]name → escaped underscore, literal _name segment */
+		if (seg.startsWith("[_]")) {
+			pathParts.push(`_${seg.slice(3)}`);
+			continue;
+		}
+
+		/* _name (single underscore, no trailing) → ignored directory */
+		if (seg.startsWith("_") && !seg.endsWith("_")) {
+			return null;
+		}
+
+		/* Everything else maps directly: _root_, (group), [param], regular segments */
+		pathParts.push(seg);
+	}
+
+	/* index as last segment → trailing / (index route convention) */
+	if (pathParts.length > 0 && pathParts[pathParts.length - 1] === "index") {
+		pathParts[pathParts.length - 1] = "";
+	}
+
+	return pathParts.join("/");
+}
+
+function isRouteConventionDir(seg: string): boolean {
+	return /^_[^_].*[^_]_$|^__[^_].*[^_]__$/.test(seg);
+}
+
+function hasRootScope(virtualPath: string): boolean {
+	return virtualPath.split("/").some((seg) => ROOT_SCOPE_RE.test(seg) && seg.length >= 3);
+}
+
+function isIgnoredDirSegment(seg: string, ignorePrefix: string): boolean {
+	return seg.startsWith(ignorePrefix) && !isRouteConventionDir(seg) && !seg.startsWith("[_]");
+}
+
+/**
+ * Inspect a project tree against the filesystem-codegen convention.
+ * `fsVirtualPaths: true` requires suffix files under `src/routes/_name_/`.
+ */
+export function inspectFsCodegenLayout(options: ScanOptions): FsLayoutIssue[] {
+	const srcDir = options.srcDir ?? "src";
+	const srcPath = join(options.rootDir, srcDir);
+	const prefix = options.ignorePrefix ?? "_";
+	const issues: FsLayoutIssue[] = [];
+
+	let entries: string[];
+	try {
+		entries = readdirSync(srcPath, { recursive: true }) as string[];
+	} catch {
+		return issues;
+	}
+
+	for (const entry of entries) {
+		const rel = entry.replace(/\\/g, "/");
+		if (!rel.endsWith(".ts") && !rel.endsWith(".tsx") && !rel.endsWith(".js") && !rel.endsWith(".jsx")) continue;
+		if (rel.includes("_gen/") || rel.includes("node_modules")) continue;
+		if (rel.endsWith(".gen.ts") || rel.endsWith(".gen.tsx")) continue;
+
+		const segments = rel.split("/");
+		const fileName = segments[segments.length - 1] ?? "";
+		const dirs = segments.slice(0, -1);
+		if (dirs.some((seg) => isIgnoredDirSegment(seg, prefix))) continue;
+
+		const filePath = posix.join(srcDir, rel);
+		const type = detectRouteType(fileName);
+		const underRoutes = rel.startsWith("routes/");
+
+		if (type) {
+			if (!underRoutes) {
+				issues.push({
+					filePath,
+					kind: "suffix-outside-routes",
+					message: `uses the .${type} suffix but is not under ${srcDir}/routes/`,
+				});
+				continue;
+			}
+			const rawPath = deriveVirtualPath(rel, "routes");
+			if (!rawPath) continue;
+			if (!hasRootScope(rawPath)) {
+				issues.push({
+					filePath,
+					kind: "missing-root-scope",
+					message: `is not inside a _name_ root-scope folder (move to ${srcDir}/routes/_root_/... or ${srcDir}/routes/_admin_/...)`,
+				});
+			}
+			continue;
+		}
+
+		if (!underRoutes) continue;
+
+		const fullPath = posix.join(srcPath, rel);
+		let content: string;
+		try {
+			content = readFileSync(fullPath, "utf-8");
+		} catch {
+			continue;
+		}
+		const match = BUILDER_EXPORT_RE.exec(content);
+		const builder = match?.[1];
+		if (!builder) continue;
+		const line = content.slice(0, match?.index ?? 0).split("\n").length;
+		issues.push({
+			filePath,
+			kind: "string-style-route",
+			line,
+			message: `declares ${builder}(...) but has no .page/.layout/.root-layout/.path-segment suffix — skipped`,
+		});
+	}
+
+	return issues;
+}
+
+export function formatFsCodegenError(issues: FsLayoutIssue[]): string {
+	const groups: Record<FsLayoutIssueKind, FsLayoutIssue[]> = {
+		"missing-root-scope": [],
+		"string-style-route": [],
+		"suffix-outside-routes": [],
+	};
+	for (const issue of issues) groups[issue.kind].push(issue);
+
+	const lines = ["fsVirtualPaths is enabled, but the project does not follow the filesystem route convention.", ""];
+
+	if (groups["string-style-route"].length > 0) {
+		lines.push("String-style route files (invisible to filesystem codegen):");
+		for (const issue of groups["string-style-route"]) {
+			lines.push(`  - ${formatFsLayoutWarning(issue)}`);
+		}
+		lines.push("");
+	}
+	if (groups["missing-root-scope"].length > 0) {
+		lines.push("Route files outside a _name_ root scope:");
+		for (const issue of groups["missing-root-scope"]) {
+			lines.push(`  - ${formatFsLayoutWarning(issue)}`);
+		}
+		lines.push("");
+	}
+	if (groups["suffix-outside-routes"].length > 0) {
+		lines.push("Suffix route files outside src/routes/:");
+		for (const issue of groups["suffix-outside-routes"]) {
+			lines.push(`  - ${formatFsLayoutWarning(issue)}`);
+		}
+		lines.push("");
+	}
+
+	lines.push(
+		"Expected layout:",
+		'  src/routes/_root_/root.root-layout.tsx        →  createRootLayout("_root_")',
+		'  src/routes/_root_/home.page.tsx               →  createPage("_root_/")',
+		'  src/routes/_root_/about/about.page.tsx        →  createPage("_root_/about")',
+		'  src/routes/_root_/(blog)/blog.layout.tsx      →  createLayout("_root_/(blog)")',
+		'  src/routes/_root_/users/[id]/user.page.tsx    →  createPage("_root_/users/[id]")',
+		"",
+		"Directories starting with _ (except _name_ root scopes) are ignored.",
+		"Use [_]name for a literal _name URL segment.",
+		"",
+		"To keep writing virtual paths yourself:",
+		"  flare({ codegen: { fsVirtualPaths: false } })",
+	);
+
+	return lines.join("\n");
+}
+
+/** Write or update the route builder declaration in a source file. */
+export function writeRouteDeclaration(filePath: string, virtualPath: string, routeType: RouteDefinition["type"]): void {
+	const builderFn = BUILDER_MAP[routeType];
+	const content = readFileSync(filePath, "utf-8");
+
+	const newDeclLine = `export const route = ${builderFn}("${escapeCodegenStr(virtualPath)}")`;
+
+	/* Check for existing builder call to update (matches any builder type for rename support) */
+	const anyBuilderRe =
+		/export const route = (createPage|createLayout|createRootLayout|createPathSegment)\s*(?:<[^>]*>)?\s*\(\s*["'`][^"'`]*["'`]\)/;
+	const match = anyBuilderRe.exec(content);
+
+	if (match) {
+		/* Path and builder unchanged — skip write */
+		if (match[0] === newDeclLine) return;
+
+		/* Also fix import if builder type changed */
+		const oldBuilderFn = match[1] ?? "";
+		let updated = content.slice(0, match.index) + newDeclLine + content.slice(match.index + match[0].length);
+		if (oldBuilderFn !== builderFn) {
+			updated = updated.replace(
+				new RegExp(
+					`import\\s*\\{\\s*${oldBuilderFn}\\s*\\}\\s*from\\s*["'\`](?:@lovrozagar/)?flare(?:/[\\w-]+)?["'\`]`,
+				),
+				`import { ${builderFn} } from "${builderSubpath(builderFn)}"`,
+			);
+		}
+		writeFileSync(filePath, updated, "utf-8");
+		return;
+	}
+
+	/* Missing declaration — prepend import + builder call, preserve existing content */
+	const header = [
+		`import { ${builderFn} } from "${builderSubpath(builderFn)}"`,
+		"",
+		"/* @flare-generated */",
+		newDeclLine,
+	].join("\n");
+
+	const trimmed = content.trim();
+	const output = trimmed.length === 0 ? `${header}\n` : `${header}\n${trimmed}\n`;
+	writeFileSync(filePath, output, "utf-8");
+}
+
+/** Scan routes/ for filesystem-based route files and return RouteDefinitions. */
+export function scanSourceFilesFsCodegen(options: ScanOptions): RouteDefinition[] {
+	const srcPath = join(options.rootDir, options.srcDir ?? "src");
+	const routesDir = "routes";
+	const defs: RouteDefinition[] = [];
+
+	let entries: string[];
+	try {
+		entries = readdirSync(srcPath, { recursive: true }) as string[];
+	} catch {
+		return defs;
+	}
+
+	for (const entry of entries) {
+		const rel = entry.replace(/\\/g, "/");
+
+		/* Only process files under routes/ */
+		if (!rel.startsWith(`${routesDir}/`)) continue;
+
+		/* Skip generated files */
+		if (rel.includes("_gen/") || rel.endsWith(".gen.ts") || rel.endsWith(".gen.tsx")) continue;
+
+		/* Detect route type from suffix */
+		const fileName = rel.split("/").pop() ?? "";
+		const type = detectRouteType(fileName);
+		if (!type) continue;
+
+		/* Derive virtual path from folder position */
+		const rawPath = deriveVirtualPath(rel, routesDir);
+		if (!rawPath) continue;
+
+		/* Pages at a root convention boundary get trailing / to distinguish from layouts.
+		 * e.g. _root_/home.page.tsx → _root_/ (variable path /), not _root_ (layout namespace) */
+		const isRootBoundary = type === "page" && /^(\[[^\]]+\]\/)*_[^/]+_$/.test(rawPath);
+		const virtualPath = isRootBoundary ? `${rawPath}/` : rawPath;
+
+		/* Read file content for chain method detection */
+		const fullPath = posix.join(srcPath, rel);
+		let content: string;
+		try {
+			content = readFileSync(fullPath, "utf-8");
+		} catch {
+			continue;
+		}
+
+		/* Extract chain metadata from file content */
+		const hasAuthenticateOptional = /\.authenticateOptional\s*\(/.test(content);
+		const hasAuthenticate = /\.authenticate\s*\(/.test(content);
+		const authenticateMode: AuthenticateMode = hasAuthenticateOptional ? "optional" : !!hasAuthenticate;
+		const hasInput = /\.input\s*(?:<[^>]*>)?\s*\(/.test(content);
+		const responseRoute = /\.response\s*\(/.test(content);
+		const cache = extractCacheFromChain(content);
+		const intercept = extractInterceptFromChain(content);
+
+		defs.push({
+			authenticateMode,
+			cache,
+			exportName: "route",
+			filePath: posix.join(options.srcDir ?? "src", rel),
+			hasInput,
+			intercept,
+			responseRoute,
+			type,
+			virtualPath,
+		});
+	}
+
+	return defs;
+}
+
+export interface RunGenerateOptions {
+	fsCodegen?: boolean;
+	ignorePrefix?: string;
+	outputPath?: string;
+	rootDir: string;
+	srcDir?: string;
+	typesOutputPath?: string;
+}
+
+export function runGenerate(options: RunGenerateOptions): GenerateResult {
+	const outputPath = options.outputPath ?? "src/_gen/routes.gen.ts";
+	const outputDir = dirname(outputPath);
+	const warnings: string[] = [];
+	const skipFiles = new Set<string>();
+
+	/* fsCodegen pre-step: derive virtual paths from filesystem and write into source files */
+	if (options.fsCodegen) {
+		const layoutIssues = inspectFsCodegenLayout({
+			ignorePrefix: options.ignorePrefix,
+			rootDir: options.rootDir,
+			srcDir: options.srcDir,
+		});
+		for (const issue of layoutIssues) skipFiles.add(issue.filePath);
+
+		const fsDefs = scanSourceFilesFsCodegen({
+			rootDir: options.rootDir,
+			srcDir: options.srcDir,
+		}).filter((def) => !skipFiles.has(def.filePath));
+
+		/* No usable suffix routes + layout issues → the whole tree is wrong. */
+		if (fsDefs.length === 0 && layoutIssues.length > 0) {
+			throw new Error(formatFsCodegenError(layoutIssues));
+		}
+
+		for (const issue of layoutIssues) {
+			const warning = formatFsLayoutWarning(issue);
+			warnings.push(warning);
+			console.warn(`[flare:generate] ${warning}`);
+		}
+
+		for (const def of fsDefs) {
+			const fullPath = join(options.rootDir, def.filePath);
+			writeRouteDeclaration(fullPath, def.virtualPath, def.type);
+		}
+
+		const hasPage = fsDefs.some((d) => d.type === "page");
+		const hasRootLayout = fsDefs.some((d) => d.type === "root-layout");
+		if (hasPage && !hasRootLayout) {
+			const warning =
+				"no *.root-layout.tsx found — pages will render without a root layout (expected src/routes/_root_/*.root-layout.tsx)";
+			warnings.push(warning);
+			console.warn(`[flare:generate] ${warning}`);
+		}
+	}
+
+	/* Always scan via regex — reads the createPage("...") strings from source files */
+	let defs = scanSourceFiles({
+		ignorePrefix: options.ignorePrefix,
+		rootDir: options.rootDir,
+		srcDir: options.srcDir,
+	});
+
+	/* fs mode only emits suffix files that passed layout inspection */
+	if (options.fsCodegen) {
+		defs = defs.filter((def) => {
+			if (skipFiles.has(def.filePath)) return false;
+			const name = def.filePath.split("/").pop() ?? "";
+			return detectRouteType(name) !== null;
+		});
+	}
+
+	const errors = validateRouteDefinitions(defs);
+	if (errors.length > 0) {
+		throw new Error(`Route validation failed:\n${errors.join("\n")}`);
+	}
+
+	const fullOutputPath = join(options.rootDir, outputPath);
+	const virtualTypesPath = options.typesOutputPath
+		? join(options.rootDir, options.typesOutputPath)
+		: join(dirname(fullOutputPath), "types.gen.d.ts");
+
+	/* Library packages and empty folders are not Flare apps — do not leave a stub _gen. */
+	if (defs.length === 0) {
+		for (const leftover of [fullOutputPath, virtualTypesPath]) {
+			if (existsSync(leftover)) unlinkSync(leftover);
+		}
+		return { layouts: 0, routes: 0, warnings };
+	}
+
+	const content = generateRoutesFile(defs, outputDir);
+	writeGenFile(fullOutputPath, content, "flare");
+
+	/* Write virtual module type declarations as a .d.ts file (must be ambient, not in a module) */
+	writeGenFile(virtualTypesPath, generateVirtualModuleTypes(), "flare");
+
+	const routes = defs.filter((d) => d.type === "page").length;
+	const layouts = defs.filter(
+		(d) => d.type === "layout" || d.type === "root-layout" || d.type === "path-segment",
+	).length;
+
+	return { layouts, routes, warnings };
+}