@screenbook/cli 1.1.2 → 1.2.0

package/dist/index.mjs

@@ -9,6 +9,7 @@ import { defineConfig } from "@screenbook/core";
 import pc from "picocolors";
 import { execSync, spawn } from "node:child_process";
 import prompts from "prompts";
+import { parse } from "@babel/parser";
 import { minimatch } from "minimatch";
 
 //#region src/utils/config.ts
@@ -166,14 +167,34 @@ function getCycleSummary(result) {
 */
 const ERRORS = {
 	ROUTES_PATTERN_MISSING: {
-		title: "routesPattern not configured",
-		suggestion: "Add routesPattern to your screenbook.config.ts to specify where your route files are located.",
+		title: "Routes configuration not found",
+		suggestion: "Add routesPattern (for file-based routing) or routesFile (for config-based routing) to your screenbook.config.ts.",
 		example: `import { defineConfig } from "@screenbook/core"
 
+// Option 1: File-based routing (Next.js, Nuxt, etc.)
 export default defineConfig({
-  routesPattern: "src/pages/**/page.tsx",  // Adjust for your framework
+  routesPattern: "src/pages/**/page.tsx",
+})
+
+// Option 2: Config-based routing (Vue Router, React Router, etc.)
+export default defineConfig({
+  routesFile: "src/router/routes.ts",
 })`
 	},
+	ROUTES_FILE_NOT_FOUND: (filePath) => ({
+		title: `Routes file not found: ${filePath}`,
+		suggestion: "Check the routesFile path in your screenbook.config.ts. The file should export a routes array.",
+		example: `import { defineConfig } from "@screenbook/core"
+
+export default defineConfig({
+  routesFile: "src/router/routes.ts",  // Make sure this file exists
+})`
+	}),
+	ROUTES_FILE_PARSE_ERROR: (filePath, error) => ({
+		title: `Failed to parse routes file: ${filePath}`,
+		message: error,
+		suggestion: "Ensure the file exports a valid routes array. Check for syntax errors or unsupported patterns."
+	}),
 	CONFIG_NOT_FOUND: {
 		title: "Configuration file not found",
 		suggestion: "Run 'screenbook init' to create a screenbook.config.ts file, or create one manually.",
@@ -733,13 +754,19 @@ async function checkDependencies(cwd) {
 			...pkg.dependencies,
 			...pkg.devDependencies
 		};
+		const unifiedVersion = allDeps.screenbook;
 		const coreVersion = allDeps["@screenbook/core"];
 		const cliVersion = allDeps["@screenbook/cli"];
+		if (unifiedVersion) return {
+			name: "Dependencies",
+			status: "pass",
+			message: `screenbook@${unifiedVersion}`
+		};
 		if (!coreVersion && !cliVersion) return {
 			name: "Dependencies",
 			status: "fail",
 			message: "Screenbook packages not installed",
-			suggestion: "Run 'pnpm add -D @screenbook/core @screenbook/cli' to install"
+			suggestion: "Run 'pnpm add -D screenbook' or 'pnpm add -D @screenbook/core @screenbook/cli' to install"
 		};
 		if (!coreVersion) return {
 			name: "Dependencies",
@@ -864,8 +891,14 @@ async function checkVersionCompatibility(cwd) {
 			...pkg.dependencies,
 			...pkg.devDependencies
 		};
+		const unifiedVersion = allDeps.screenbook;
 		const coreVersion = allDeps["@screenbook/core"];
 		const cliVersion = allDeps["@screenbook/cli"];
+		if (unifiedVersion) return {
+			name: "Version compatibility",
+			status: "pass",
+			message: "Using unified screenbook package"
+		};
 		if (!coreVersion || !cliVersion) return {
 			name: "Version compatibility",
 			status: "warn",
@@ -931,6 +964,721 @@ function displayResults(results, verbose) {
 	}
 }
 
+//#endregion
+//#region src/utils/routeParserUtils.ts
+/**
+* Resolve relative import path to absolute path
+*/
+function resolveImportPath(importPath, baseDir) {
+	if (importPath.startsWith(".")) return resolve(baseDir, importPath);
+	return importPath;
+}
+/**
+* Flatten nested routes into a flat list with computed properties
+*/
+function flattenRoutes(routes, parentPath = "", depth = 0) {
+	const result = [];
+	for (const route of routes) {
+		if (route.redirect && !route.component) continue;
+		let fullPath;
+		if (route.path.startsWith("/")) fullPath = route.path;
+		else if (parentPath === "/") fullPath = `/${route.path}`;
+		else fullPath = parentPath ? `${parentPath}/${route.path}` : `/${route.path}`;
+		fullPath = fullPath.replace(/\/+/g, "/");
+		if (fullPath !== "/" && fullPath.endsWith("/")) fullPath = fullPath.slice(0, -1);
+		if (fullPath === "") fullPath = parentPath || "/";
+		if (route.component || !route.children) result.push({
+			fullPath,
+			name: route.name,
+			componentPath: route.component,
+			screenId: pathToScreenId(fullPath),
+			screenTitle: pathToScreenTitle(fullPath),
+			depth
+		});
+		if (route.children) result.push(...flattenRoutes(route.children, fullPath, depth + 1));
+	}
+	return result;
+}
+/**
+* Convert route path to screen ID
+* /user/:id/profile -> user.id.profile
+*/
+function pathToScreenId(path) {
+	if (path === "/" || path === "") return "home";
+	return path.replace(/^\//, "").replace(/\/$/, "").split("/").map((segment) => {
+		if (segment.startsWith(":")) return segment.slice(1);
+		if (segment.startsWith("*")) return segment.slice(1) || "catchall";
+		return segment;
+	}).join(".");
+}
+/**
+* Convert route path to screen title
+* /user/:id/profile -> Profile
+*/
+function pathToScreenTitle(path) {
+	if (path === "/" || path === "") return "Home";
+	const segments = path.replace(/^\//, "").replace(/\/$/, "").split("/").filter((s) => !s.startsWith(":") && !s.startsWith("*"));
+	return (segments[segments.length - 1] || "Home").split(/[-_]/).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+
+//#endregion
+//#region src/utils/tanstackRouterParser.ts
+/**
+* Parse TanStack Router configuration file and extract routes
+*/
+function parseTanStackRouterConfig(filePath, preloadedContent) {
+	const absolutePath = resolve(filePath);
+	const routesFileDir = dirname(absolutePath);
+	const warnings = [];
+	let content;
+	if (preloadedContent !== void 0) content = preloadedContent;
+	else try {
+		content = readFileSync(absolutePath, "utf-8");
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to read routes file "${absolutePath}": ${message}`);
+	}
+	let ast;
+	try {
+		ast = parse(content, {
+			sourceType: "module",
+			plugins: ["typescript", "jsx"]
+		});
+	} catch (error) {
+		if (error instanceof SyntaxError) throw new Error(`Syntax error in routes file "${absolutePath}": ${error.message}`);
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to parse routes file "${absolutePath}": ${message}`);
+	}
+	const routeMap = /* @__PURE__ */ new Map();
+	for (const node of ast.program.body) collectRouteDefinitions(node, routeMap, routesFileDir, warnings);
+	for (const node of ast.program.body) processAddChildrenCalls(node, routeMap, warnings);
+	const routes = buildRouteTree(routeMap, warnings);
+	if (routes.length === 0) warnings.push("No routes found. Supported patterns: 'createRootRoute()', 'createRoute()', and '.addChildren([...])'");
+	return {
+		routes,
+		warnings
+	};
+}
+/**
+* Collect route definitions from AST nodes
+*/
+function collectRouteDefinitions(node, routeMap, baseDir, warnings) {
+	if (node.type === "VariableDeclaration") for (const decl of node.declarations) {
+		if (decl.id.type !== "Identifier") continue;
+		const variableName = decl.id.name;
+		if (decl.init?.type === "CallExpression") {
+			const routeDef = extractRouteFromCallExpression(decl.init, variableName, baseDir, warnings);
+			if (routeDef) routeMap.set(variableName, routeDef);
+		}
+		if (decl.init?.type === "CallExpression" && decl.init.callee?.type === "MemberExpression" && decl.init.callee.property?.type === "Identifier" && decl.init.callee.property.name === "lazy") {
+			const createRouteCall = decl.init.callee.object;
+			if (createRouteCall?.type === "CallExpression") {
+				const routeDef = extractRouteFromCallExpression(createRouteCall, variableName, baseDir, warnings);
+				if (routeDef) {
+					const lazyArg = decl.init.arguments[0];
+					if (lazyArg) {
+						const lazyPath = extractLazyImportPath$1(lazyArg, baseDir, warnings);
+						if (lazyPath) routeDef.component = lazyPath;
+					}
+					routeMap.set(variableName, routeDef);
+				}
+			}
+		}
+	}
+	if (node.type === "ExportNamedDeclaration" && node.declaration?.type === "VariableDeclaration") for (const decl of node.declaration.declarations) {
+		if (decl.id.type !== "Identifier") continue;
+		const variableName = decl.id.name;
+		if (decl.init?.type === "CallExpression") {
+			const routeDef = extractRouteFromCallExpression(decl.init, variableName, baseDir, warnings);
+			if (routeDef) routeMap.set(variableName, routeDef);
+		}
+	}
+}
+/**
+* Extract route definition from a CallExpression (createRoute or createRootRoute)
+*/
+function extractRouteFromCallExpression(callNode, variableName, baseDir, warnings) {
+	const callee = callNode.callee;
+	let isRoot = false;
+	let optionsArg = callNode.arguments[0];
+	if (callee.type === "Identifier") {
+		if (callee.name === "createRootRoute") isRoot = true;
+		else if (callee.name === "createRootRouteWithContext") isRoot = true;
+		else if (callee.name !== "createRoute") return null;
+	} else if (callee.type === "CallExpression") {
+		const innerCallee = callee.callee;
+		if (innerCallee?.type === "Identifier" && innerCallee.name === "createRootRouteWithContext") {
+			isRoot = true;
+			optionsArg = callNode.arguments[0];
+		} else return null;
+	} else return null;
+	const routeDef = {
+		variableName,
+		isRoot
+	};
+	if (optionsArg?.type === "ObjectExpression") for (const prop of optionsArg.properties) {
+		if (prop.type !== "ObjectProperty") continue;
+		if (prop.key.type !== "Identifier") continue;
+		switch (prop.key.name) {
+			case "path":
+				if (prop.value.type === "StringLiteral") routeDef.path = normalizeTanStackPath(prop.value.value);
+				else {
+					const loc = prop.loc ? ` at line ${prop.loc.start.line}` : "";
+					warnings.push(`Dynamic path value (${prop.value.type})${loc}. Only string literal paths can be statically analyzed.`);
+				}
+				break;
+			case "component":
+				routeDef.component = extractComponentValue(prop.value, baseDir, warnings);
+				break;
+			case "getParentRoute":
+				if (prop.value.type === "ArrowFunctionExpression") {
+					const body = prop.value.body;
+					if (body.type === "Identifier") routeDef.parentVariableName = body.name;
+					else {
+						const loc = prop.loc ? ` at line ${prop.loc.start.line}` : "";
+						warnings.push(`Dynamic getParentRoute${loc}. Only static route references can be analyzed.`);
+					}
+				}
+				break;
+		}
+	}
+	return routeDef;
+}
+/**
+* Extract component value from different patterns
+* Returns undefined with a warning for unrecognized patterns
+*/
+function extractComponentValue(node, baseDir, warnings) {
+	if (node.type === "Identifier") return node.name;
+	if (node.type === "CallExpression") {
+		const callee = node.callee;
+		if (callee.type === "Identifier" && callee.name === "lazyRouteComponent") {
+			const importArg = node.arguments[0];
+			if (importArg) return extractLazyImportPath$1(importArg, baseDir, warnings);
+			const loc = node.loc ? ` at line ${node.loc.start.line}` : "";
+			warnings.push(`lazyRouteComponent called without arguments${loc}. Expected arrow function with import().`);
+			return;
+		}
+		return;
+	}
+	if (node.type === "ArrowFunctionExpression") {
+		if (node.body.type === "JSXElement") {
+			const openingElement = node.body.openingElement;
+			if (openingElement?.name?.type === "JSXIdentifier") return openingElement.name.name;
+			if (openingElement?.name?.type === "JSXMemberExpression") {
+				const loc = node.loc ? ` at line ${node.loc.start.line}` : "";
+				warnings.push(`Namespaced JSX component${loc}. Component extraction not fully supported for member expressions.`);
+				return;
+			}
+		}
+		if (node.body.type === "BlockStatement") {
+			const loc = node.loc ? ` at line ${node.loc.start.line}` : "";
+			warnings.push(`Arrow function with block body${loc}. Only concise arrow functions returning JSX directly can be analyzed.`);
+			return;
+		}
+		if (node.body.type === "JSXFragment") {
+			const loc = node.loc ? ` at line ${node.loc.start.line}` : "";
+			warnings.push(`JSX Fragment detected${loc}. Cannot extract component name from fragments.`);
+			return;
+		}
+	}
+}
+/**
+* Extract import path from lazy function patterns
+*/
+function extractLazyImportPath$1(node, baseDir, warnings) {
+	if (node.type === "ArrowFunctionExpression") {
+		const body = node.body;
+		if (body.type === "CallExpression" && body.callee.type === "Import") {
+			if (body.arguments[0]?.type === "StringLiteral") return resolveImportPath(body.arguments[0].value, baseDir);
+		}
+		if (body.type === "CallExpression" && body.callee.type === "MemberExpression" && body.callee.object?.type === "CallExpression" && body.callee.object.callee?.type === "Import") {
+			const importCall = body.callee.object;
+			if (importCall.arguments[0]?.type === "StringLiteral") return resolveImportPath(importCall.arguments[0].value, baseDir);
+		}
+	}
+	const loc = node.loc ? ` at line ${node.loc.start.line}` : "";
+	warnings.push(`Unrecognized lazy pattern (${node.type})${loc}. Expected arrow function with import().`);
+}
+/**
+* Process addChildren calls to establish parent-child relationships
+*/
+function processAddChildrenCalls(node, routeMap, warnings) {
+	if (node.type === "VariableDeclaration") for (const decl of node.declarations) processAddChildrenExpression(decl.init, routeMap, warnings);
+	if (node.type === "ExportNamedDeclaration" && node.declaration?.type === "VariableDeclaration") for (const decl of node.declaration.declarations) processAddChildrenExpression(decl.init, routeMap, warnings);
+}
+/**
+* Recursively process addChildren expressions
+*/
+function processAddChildrenExpression(expr, routeMap, warnings) {
+	if (!expr) return void 0;
+	if (expr.type === "CallExpression" && expr.callee?.type === "MemberExpression" && expr.callee.property?.type === "Identifier" && expr.callee.property.name === "addChildren") {
+		let parentVarName;
+		if (expr.callee.object?.type === "Identifier") parentVarName = expr.callee.object.name;
+		else if (expr.callee.object?.type === "CallExpression") parentVarName = processAddChildrenExpression(expr.callee.object, routeMap, warnings);
+		if (!parentVarName) return void 0;
+		const parentDef = routeMap.get(parentVarName);
+		if (!parentDef) {
+			const loc = expr.loc ? ` at line ${expr.loc.start.line}` : "";
+			warnings.push(`Parent route "${parentVarName}" not found${loc}. Ensure it's defined with createRoute/createRootRoute.`);
+			return;
+		}
+		const childrenArg = expr.arguments[0];
+		if (childrenArg?.type === "ArrayExpression") {
+			const childNames = [];
+			for (const element of childrenArg.elements) {
+				if (!element) continue;
+				if (element.type === "Identifier") childNames.push(element.name);
+				else if (element.type === "CallExpression") {
+					const nestedParent = processAddChildrenExpression(element, routeMap, warnings);
+					if (nestedParent) childNames.push(nestedParent);
+				} else if (element.type === "SpreadElement") {
+					const loc = element.loc ? ` at line ${element.loc.start.line}` : "";
+					warnings.push(`Spread operator detected${loc}. Routes from spread cannot be statically analyzed.`);
+				}
+			}
+			parentDef.children = childNames;
+		}
+		return parentVarName;
+	}
+}
+/**
+* Build the route tree from collected definitions
+*/
+function buildRouteTree(routeMap, warnings) {
+	const rootDefs = Array.from(routeMap.values()).filter((def) => def.isRoot);
+	if (rootDefs.length === 0) return buildTreeFromParentRelations(routeMap, warnings);
+	const routes = [];
+	for (const rootDef of rootDefs) {
+		const rootRoute = buildRouteFromDefinition(rootDef, routeMap, warnings, /* @__PURE__ */ new Set());
+		if (rootRoute) {
+			if (rootRoute.children && rootRoute.children.length > 0) routes.push(...rootRoute.children);
+			else if (rootRoute.path) routes.push(rootRoute);
+		}
+	}
+	return routes;
+}
+/**
+* Build tree when there's no explicit root route
+* Falls back to finding routes that have no parent relationship defined
+*/
+function buildTreeFromParentRelations(routeMap, warnings) {
+	const topLevelDefs = Array.from(routeMap.values()).filter((def) => !def.parentVariableName && !def.isRoot);
+	const routes = [];
+	for (const def of topLevelDefs) {
+		const route = buildRouteFromDefinition(def, routeMap, warnings, /* @__PURE__ */ new Set());
+		if (route) routes.push(route);
+	}
+	return routes;
+}
+/**
+* Build a ParsedRoute from a RouteDefinition
+* @param visited - Set of visited variable names for circular reference detection
+*/
+function buildRouteFromDefinition(def, routeMap, warnings, visited) {
+	if (visited.has(def.variableName)) {
+		warnings.push(`Circular reference detected: route "${def.variableName}" references itself in the route tree.`);
+		return null;
+	}
+	visited.add(def.variableName);
+	const route = {
+		path: def.path ?? "",
+		component: def.component
+	};
+	if (def.children && def.children.length > 0) {
+		const children = [];
+		for (const childName of def.children) {
+			const childDef = routeMap.get(childName);
+			if (childDef) {
+				const childRoute = buildRouteFromDefinition(childDef, routeMap, warnings, visited);
+				if (childRoute) children.push(childRoute);
+			} else warnings.push(`Child route "${childName}" not found. Ensure it's defined with createRoute.`);
+		}
+		if (children.length > 0) route.children = children;
+	}
+	return route;
+}
+/**
+* Normalize TanStack Router path syntax to standard format
+* /$ (trailing catch-all) -> /*
+* $  (standalone splat)   -> *
+* $param (dynamic segment) -> :param
+*/
+function normalizeTanStackPath(path) {
+	return path.replace(/\/\$$/, "/*").replace(/^\$$/, "*").replace(/\$([a-zA-Z_][a-zA-Z0-9_]*)/g, ":$1");
+}
+/**
+* Detect if content is TanStack Router based on patterns
+*/
+function isTanStackRouterContent(content) {
+	if (content.includes("@tanstack/react-router")) return true;
+	if (content.includes("createRootRoute")) return true;
+	if (content.includes("createRoute") && content.includes("getParentRoute")) return true;
+	if (content.includes("lazyRouteComponent")) return true;
+	if (/\.addChildren\s*\(/.test(content)) return true;
+	return false;
+}
+
+//#endregion
+//#region src/utils/reactRouterParser.ts
+/**
+* Router factory function names to detect
+*/
+const ROUTER_FACTORY_NAMES = [
+	"createBrowserRouter",
+	"createHashRouter",
+	"createMemoryRouter"
+];
+/**
+* Parse React Router configuration file and extract routes
+*/
+function parseReactRouterConfig(filePath, preloadedContent) {
+	const absolutePath = resolve(filePath);
+	const routesFileDir = dirname(absolutePath);
+	const warnings = [];
+	let content;
+	if (preloadedContent !== void 0) content = preloadedContent;
+	else try {
+		content = readFileSync(absolutePath, "utf-8");
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to read routes file "${absolutePath}": ${message}`);
+	}
+	let ast;
+	try {
+		ast = parse(content, {
+			sourceType: "module",
+			plugins: ["typescript", "jsx"]
+		});
+	} catch (error) {
+		if (error instanceof SyntaxError) throw new Error(`Syntax error in routes file "${absolutePath}": ${error.message}`);
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to parse routes file "${absolutePath}": ${message}`);
+	}
+	const routes = [];
+	for (const node of ast.program.body) {
+		if (node.type === "VariableDeclaration") {
+			for (const decl of node.declarations) if (decl.init?.type === "CallExpression") {
+				const callee = decl.init.callee;
+				if (callee.type === "Identifier" && ROUTER_FACTORY_NAMES.includes(callee.name)) {
+					const firstArg = decl.init.arguments[0];
+					if (firstArg?.type === "ArrayExpression") {
+						const parsed = parseRoutesArray$1(firstArg, routesFileDir, warnings);
+						routes.push(...parsed);
+					}
+				}
+			}
+		}
+		if (node.type === "ExportNamedDeclaration" && node.declaration?.type === "VariableDeclaration") for (const decl of node.declaration.declarations) {
+			if (decl.init?.type === "CallExpression") {
+				const callee = decl.init.callee;
+				if (callee.type === "Identifier" && ROUTER_FACTORY_NAMES.includes(callee.name)) {
+					const firstArg = decl.init.arguments[0];
+					if (firstArg?.type === "ArrayExpression") {
+						const parsed = parseRoutesArray$1(firstArg, routesFileDir, warnings);
+						routes.push(...parsed);
+					}
+				}
+			}
+			if (decl.id.type === "Identifier" && decl.id.name === "routes" && decl.init?.type === "ArrayExpression") {
+				const parsed = parseRoutesArray$1(decl.init, routesFileDir, warnings);
+				routes.push(...parsed);
+			}
+		}
+		if (node.type === "VariableDeclaration") {
+			for (const decl of node.declarations) if (decl.id.type === "Identifier" && decl.id.name === "routes" && decl.init?.type === "ArrayExpression") {
+				const parsed = parseRoutesArray$1(decl.init, routesFileDir, warnings);
+				routes.push(...parsed);
+			}
+		}
+		if (node.type === "ExportDefaultDeclaration" && node.declaration.type === "ArrayExpression") {
+			const parsed = parseRoutesArray$1(node.declaration, routesFileDir, warnings);
+			routes.push(...parsed);
+		}
+		if (node.type === "ExportDefaultDeclaration" && node.declaration.type === "TSSatisfiesExpression" && node.declaration.expression.type === "ArrayExpression") {
+			const parsed = parseRoutesArray$1(node.declaration.expression, routesFileDir, warnings);
+			routes.push(...parsed);
+		}
+	}
+	if (routes.length === 0) warnings.push("No routes found. Supported patterns: 'createBrowserRouter([...])', 'export const routes = [...]', or 'export default [...]'");
+	return {
+		routes,
+		warnings
+	};
+}
+/**
+* Parse an array expression containing route objects
+*/
+function parseRoutesArray$1(arrayNode, baseDir, warnings) {
+	const routes = [];
+	for (const element of arrayNode.elements) {
+		if (!element) continue;
+		if (element.type === "SpreadElement") {
+			const loc = element.loc ? ` at line ${element.loc.start.line}` : "";
+			warnings.push(`Spread operator detected${loc}. Routes from spread cannot be statically analyzed.`);
+			continue;
+		}
+		if (element.type === "ObjectExpression") {
+			const route = parseRouteObject$1(element, baseDir, warnings);
+			if (route) routes.push(route);
+		} else {
+			const loc = element.loc ? ` at line ${element.loc.start.line}` : "";
+			warnings.push(`Non-object route element (${element.type})${loc}. Only object literals can be statically analyzed.`);
+		}
+	}
+	return routes;
+}
+/**
+* Parse a single route object expression
+*/
+function parseRouteObject$1(objectNode, baseDir, warnings) {
+	const route = { path: "" };
+	let isIndexRoute = false;
+	let hasPath = false;
+	for (const prop of objectNode.properties) {
+		if (prop.type !== "ObjectProperty") continue;
+		if (prop.key.type !== "Identifier") continue;
+		switch (prop.key.name) {
+			case "path":
+				if (prop.value.type === "StringLiteral") {
+					route.path = prop.value.value;
+					hasPath = true;
+				} else {
+					const loc = prop.loc ? ` at line ${prop.loc.start.line}` : "";
+					warnings.push(`Dynamic path value (${prop.value.type})${loc}. Only string literal paths can be statically analyzed.`);
+				}
+				break;
+			case "index":
+				if (prop.value.type === "BooleanLiteral" && prop.value.value === true) isIndexRoute = true;
+				break;
+			case "element":
+				route.component = extractComponentFromJSX(prop.value, warnings);
+				break;
+			case "Component":
+				if (prop.value.type === "Identifier") route.component = prop.value.name;
+				break;
+			case "lazy": {
+				const lazyPath = extractLazyImportPath(prop.value, baseDir, warnings);
+				if (lazyPath) route.component = lazyPath;
+				break;
+			}
+			case "children":
+				if (prop.value.type === "ArrayExpression") route.children = parseRoutesArray$1(prop.value, baseDir, warnings);
+				break;
+		}
+	}
+	if (isIndexRoute) {
+		route.path = "";
+		return route;
+	}
+	if (!hasPath && !isIndexRoute) {
+		if (route.children && route.children.length > 0) {
+			route.path = "";
+			return route;
+		}
+		return null;
+	}
+	return route;
+}
+/**
+* Extract component name from JSX element
+* element: <Dashboard /> -> "Dashboard"
+*/
+function extractComponentFromJSX(node, warnings) {
+	if (node.type === "JSXElement") {
+		const openingElement = node.openingElement;
+		if (openingElement?.name?.type === "JSXIdentifier") return openingElement.name.name;
+		if (openingElement?.name?.type === "JSXMemberExpression") {
+			const parts = [];
+			let current = openingElement.name;
+			while (current) {
+				if (current.type === "JSXIdentifier") {
+					parts.unshift(current.name);
+					break;
+				}
+				if (current.type === "JSXMemberExpression") {
+					if (current.property?.type === "JSXIdentifier") parts.unshift(current.property.name);
+					current = current.object;
+				} else break;
+			}
+			return parts.join(".");
+		}
+		if (node.children && node.children.length > 0 && openingElement?.name?.type === "JSXIdentifier") {
+			const wrapperName = openingElement.name.name;
+			for (const child of node.children) if (child.type === "JSXElement") {
+				if (extractComponentFromJSX(child, warnings)) {
+					warnings.push(`Wrapper component detected: <${wrapperName}>. Using wrapper name for screen.`);
+					return wrapperName;
+				}
+			}
+		}
+	}
+	if (node.type === "JSXFragment") return;
+}
+/**
+* Extract import path from lazy function
+* lazy: () => import("./pages/Dashboard") -> resolved path
+*/
+function extractLazyImportPath(node, baseDir, warnings) {
+	if (node.type === "ArrowFunctionExpression") {
+		const body = node.body;
+		if (body.type === "CallExpression" && body.callee.type === "Import") {
+			if (body.arguments[0]?.type === "StringLiteral") return resolveImportPath(body.arguments[0].value, baseDir);
+			const loc$1 = node.loc ? ` at line ${node.loc.start.line}` : "";
+			warnings.push(`Lazy import with dynamic path${loc$1}. Only string literal imports can be statically analyzed.`);
+			return;
+		}
+	}
+	const loc = node.loc ? ` at line ${node.loc.start.line}` : "";
+	warnings.push(`Unrecognized lazy pattern (${node.type})${loc}. Expected arrow function with import().`);
+}
+/**
+* Detect if content is React Router based on patterns
+*/
+function isReactRouterContent(content) {
+	if (content.includes("createBrowserRouter") || content.includes("createHashRouter") || content.includes("createMemoryRouter") || content.includes("RouteObject")) return true;
+	if (/element:\s*</.test(content)) return true;
+	if (/Component:\s*[A-Z]/.test(content)) return true;
+	return false;
+}
+/**
+* Detect if content is Vue Router based on patterns
+*/
+function isVueRouterContent(content) {
+	if (content.includes("RouteRecordRaw") || content.includes("vue-router") || content.includes(".vue")) return true;
+	return false;
+}
+/**
+* Detect router type from file content
+*/
+function detectRouterType(content) {
+	if (isTanStackRouterContent(content)) return "tanstack-router";
+	if (isReactRouterContent(content)) return "react-router";
+	if (isVueRouterContent(content)) return "vue-router";
+	return "unknown";
+}
+
+//#endregion
+//#region src/utils/vueRouterParser.ts
+/**
+* Parse Vue Router configuration file and extract routes
+*/
+function parseVueRouterConfig(filePath, preloadedContent) {
+	const absolutePath = resolve(filePath);
+	const routesFileDir = dirname(absolutePath);
+	const warnings = [];
+	let content;
+	if (preloadedContent !== void 0) content = preloadedContent;
+	else try {
+		content = readFileSync(absolutePath, "utf-8");
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to read routes file "${absolutePath}": ${message}`);
+	}
+	let ast;
+	try {
+		ast = parse(content, {
+			sourceType: "module",
+			plugins: ["typescript", "jsx"]
+		});
+	} catch (error) {
+		if (error instanceof SyntaxError) throw new Error(`Syntax error in routes file "${absolutePath}": ${error.message}`);
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to parse routes file "${absolutePath}": ${message}`);
+	}
+	const routes = [];
+	for (const node of ast.program.body) {
+		if (node.type === "ExportNamedDeclaration" && node.declaration?.type === "VariableDeclaration") {
+			for (const decl of node.declaration.declarations) if (decl.id.type === "Identifier" && decl.id.name === "routes" && decl.init?.type === "ArrayExpression") {
+				const parsed = parseRoutesArray(decl.init, routesFileDir, warnings);
+				routes.push(...parsed);
+			}
+		}
+		if (node.type === "VariableDeclaration") {
+			for (const decl of node.declarations) if (decl.id.type === "Identifier" && decl.id.name === "routes" && decl.init?.type === "ArrayExpression") {
+				const parsed = parseRoutesArray(decl.init, routesFileDir, warnings);
+				routes.push(...parsed);
+			}
+		}
+		if (node.type === "ExportDefaultDeclaration" && node.declaration.type === "ArrayExpression") {
+			const parsed = parseRoutesArray(node.declaration, routesFileDir, warnings);
+			routes.push(...parsed);
+		}
+		if (node.type === "ExportDefaultDeclaration" && node.declaration.type === "TSSatisfiesExpression" && node.declaration.expression.type === "ArrayExpression") {
+			const parsed = parseRoutesArray(node.declaration.expression, routesFileDir, warnings);
+			routes.push(...parsed);
+		}
+	}
+	if (routes.length === 0) warnings.push("No routes array found. Supported patterns: 'export const routes = [...]', 'export default [...]', or 'export default [...] satisfies RouteRecordRaw[]'");
+	return {
+		routes,
+		warnings
+	};
+}
+/**
+* Parse an array expression containing route objects
+*/
+function parseRoutesArray(arrayNode, baseDir, warnings) {
+	const routes = [];
+	for (const element of arrayNode.elements) {
+		if (!element) continue;
+		if (element.type === "SpreadElement") {
+			const loc = element.loc ? ` at line ${element.loc.start.line}` : "";
+			warnings.push(`Spread operator detected${loc}. Routes from spread cannot be statically analyzed.`);
+			continue;
+		}
+		if (element.type === "ObjectExpression") {
+			const route = parseRouteObject(element, baseDir, warnings);
+			if (route) routes.push(route);
+		}
+	}
+	return routes;
+}
+/**
+* Parse a single route object expression
+*/
+function parseRouteObject(objectNode, baseDir, warnings) {
+	const route = { path: "" };
+	for (const prop of objectNode.properties) {
+		if (prop.type !== "ObjectProperty") continue;
+		if (prop.key.type !== "Identifier") continue;
+		switch (prop.key.name) {
+			case "path":
+				if (prop.value.type === "StringLiteral") route.path = prop.value.value;
+				break;
+			case "name":
+				if (prop.value.type === "StringLiteral") route.name = prop.value.value;
+				break;
+			case "redirect":
+				if (prop.value.type === "StringLiteral") route.redirect = prop.value.value;
+				break;
+			case "component":
+				route.component = extractComponentPath(prop.value, baseDir);
+				break;
+			case "children":
+				if (prop.value.type === "ArrayExpression") route.children = parseRoutesArray(prop.value, baseDir, warnings);
+				break;
+		}
+	}
+	if (!route.path) return null;
+	return route;
+}
+/**
+* Extract component path from various component definitions
+*/
+function extractComponentPath(node, baseDir) {
+	if (node.type === "Identifier") return;
+	if (node.type === "ArrowFunctionExpression") {
+		const body = node.body;
+		if (body.type === "CallExpression" && body.callee.type === "Import") {
+			if (body.arguments[0]?.type === "StringLiteral") return resolveImportPath(body.arguments[0].value, baseDir);
+		}
+		if (body.type === "CallExpression" && body.callee.type === "Import") {
+			for (const arg of body.arguments) if (arg.type === "StringLiteral") return resolveImportPath(arg.value, baseDir);
+		}
+	}
+}
+
 //#endregion
 //#region src/commands/generate.ts
 const generateCommand = define({
@@ -967,92 +1715,229 @@ const generateCommand = define({
 		const dryRun = ctx.values.dryRun ?? false;
 		const force = ctx.values.force ?? false;
 		const interactive = ctx.values.interactive ?? false;
-		if (!config.routesPattern) {
+		if (!config.routesPattern && !config.routesFile) {
 			logger.errorWithHelp(ERRORS.ROUTES_PATTERN_MISSING);
 			process.exit(1);
 		}
-		logger.info("Scanning for route files...");
-		logger.blank();
-		const routeFiles = await glob(config.routesPattern, {
-			cwd,
+		if (config.routesFile) {
+			await generateFromRoutesFile(config.routesFile, cwd, {
+				dryRun,
+				force,
+				interactive
+			});
+			return;
+		}
+		await generateFromRoutesPattern(config.routesPattern, cwd, {
+			dryRun,
+			force,
+			interactive,
 			ignore: config.ignore
 		});
-		if (routeFiles.length === 0) {
-			logger.warn(`No route files found matching: ${config.routesPattern}`);
-			return;
+	}
+});
+/**
+* Generate screen.meta.ts files from a router config file (Vue Router or React Router)
+*/
+async function generateFromRoutesFile(routesFile, cwd, options) {
+	const { dryRun, force, interactive } = options;
+	const absoluteRoutesFile = resolve(cwd, routesFile);
+	if (!existsSync(absoluteRoutesFile)) {
+		logger.errorWithHelp(ERRORS.ROUTES_FILE_NOT_FOUND(routesFile));
+		process.exit(1);
+	}
+	const routerType = detectRouterType(readFileSync(absoluteRoutesFile, "utf-8"));
+	const routerTypeDisplay = routerType === "tanstack-router" ? "TanStack Router" : routerType === "react-router" ? "React Router" : routerType === "vue-router" ? "Vue Router" : "unknown";
+	logger.info(`Parsing routes from ${logger.path(routesFile)} (${routerTypeDisplay})...`);
+	logger.blank();
+	let parseResult;
+	try {
+		if (routerType === "tanstack-router") parseResult = parseTanStackRouterConfig(absoluteRoutesFile);
+		else if (routerType === "react-router") parseResult = parseReactRouterConfig(absoluteRoutesFile);
+		else parseResult = parseVueRouterConfig(absoluteRoutesFile);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		logger.errorWithHelp(ERRORS.ROUTES_FILE_PARSE_ERROR(routesFile, message));
+		process.exit(1);
+	}
+	for (const warning of parseResult.warnings) logger.warn(warning);
+	const flatRoutes = flattenRoutes(parseResult.routes);
+	if (flatRoutes.length === 0) {
+		logger.warn("No routes found in the config file");
+		return;
+	}
+	logger.log(`Found ${flatRoutes.length} routes`);
+	logger.blank();
+	let created = 0;
+	let skipped = 0;
+	for (const route of flatRoutes) {
+		const metaPath = determineMetaPath(route, cwd);
+		const absoluteMetaPath = resolve(cwd, metaPath);
+		if (!force && existsSync(absoluteMetaPath)) {
+			if (!interactive) {
+				skipped++;
+				continue;
+			}
+			logger.itemWarn(`Exists: ${logger.path(metaPath)} (use --force to overwrite)`);
+			skipped++;
+			continue;
 		}
-		logger.log(`Found ${routeFiles.length} route files`);
-		logger.blank();
-		let created = 0;
-		let skipped = 0;
-		for (const routeFile of routeFiles) {
-			const routeDir = dirname(routeFile);
-			const metaPath = join(routeDir, "screen.meta.ts");
-			const absoluteMetaPath = join(cwd, metaPath);
-			if (!force && existsSync(absoluteMetaPath)) {
-				if (!interactive) {
-					skipped++;
-					continue;
-				}
-				logger.itemWarn(`Exists: ${logger.path(metaPath)} (use --force to overwrite)`);
+		const screenMeta = {
+			id: route.screenId,
+			title: route.screenTitle,
+			route: route.fullPath
+		};
+		if (interactive) {
+			const result = await promptForScreen(route.fullPath, screenMeta);
+			if (result.skip) {
+				logger.itemWarn(`Skipped: ${logger.path(metaPath)}`);
 				skipped++;
 				continue;
 			}
-			const screenMeta = inferScreenMeta(routeDir, config.routesPattern);
-			if (interactive) {
-				const result = await promptForScreen(routeFile, screenMeta);
-				if (result.skip) {
-					logger.itemWarn(`Skipped: ${logger.path(metaPath)}`);
-					skipped++;
-					continue;
-				}
-				const content = generateScreenMetaContent(result.meta, {
-					owner: result.owner,
-					tags: result.tags
-				});
-				if (dryRun) {
-					logger.step(`Would create: ${logger.path(metaPath)}`);
-					logger.log(`    ${logger.dim(`id: "${result.meta.id}"`)}`);
-					logger.log(`    ${logger.dim(`title: "${result.meta.title}"`)}`);
-					logger.log(`    ${logger.dim(`route: "${result.meta.route}"`)}`);
-					if (result.owner.length > 0) logger.log(`    ${logger.dim(`owner: [${result.owner.map((o) => `"${o}"`).join(", ")}]`)}`);
-					if (result.tags.length > 0) logger.log(`    ${logger.dim(`tags: [${result.tags.map((t) => `"${t}"`).join(", ")}]`)}`);
-					logger.blank();
-				} else {
-					writeFileSync(absoluteMetaPath, content);
-					logger.itemSuccess(`Created: ${logger.path(metaPath)}`);
-				}
-			} else {
-				const content = generateScreenMetaContent(screenMeta);
-				if (dryRun) {
-					logger.step(`Would create: ${logger.path(metaPath)}`);
-					logger.log(`    ${logger.dim(`id: "${screenMeta.id}"`)}`);
-					logger.log(`    ${logger.dim(`title: "${screenMeta.title}"`)}`);
-					logger.log(`    ${logger.dim(`route: "${screenMeta.route}"`)}`);
-					logger.blank();
-				} else {
-					writeFileSync(absoluteMetaPath, content);
-					logger.itemSuccess(`Created: ${logger.path(metaPath)}`);
-				}
+			const content = generateScreenMetaContent(result.meta, {
+				owner: result.owner,
+				tags: result.tags
+			});
+			if (dryRun) {
+				logDryRunOutput(metaPath, result.meta, result.owner, result.tags);
+				created++;
+			} else if (safeWriteFile(absoluteMetaPath, metaPath, content)) created++;
+		} else {
+			const content = generateScreenMetaContent(screenMeta);
+			if (dryRun) {
+				logDryRunOutput(metaPath, screenMeta);
+				created++;
+			} else if (safeWriteFile(absoluteMetaPath, metaPath, content)) created++;
+		}
+	}
+	logSummary(created, skipped, dryRun);
+}
+/**
+* Generate screen.meta.ts files from route files matching a glob pattern
+*/
+async function generateFromRoutesPattern(routesPattern, cwd, options) {
+	const { dryRun, force, interactive, ignore } = options;
+	logger.info("Scanning for route files...");
+	logger.blank();
+	const routeFiles = await glob(routesPattern, {
+		cwd,
+		ignore
+	});
+	if (routeFiles.length === 0) {
+		logger.warn(`No route files found matching: ${routesPattern}`);
+		return;
+	}
+	logger.log(`Found ${routeFiles.length} route files`);
+	logger.blank();
+	let created = 0;
+	let skipped = 0;
+	for (const routeFile of routeFiles) {
+		const routeDir = dirname(routeFile);
+		const metaPath = join(routeDir, "screen.meta.ts");
+		const absoluteMetaPath = join(cwd, metaPath);
+		if (!force && existsSync(absoluteMetaPath)) {
+			if (!interactive) {
+				skipped++;
+				continue;
+			}
+			logger.itemWarn(`Exists: ${logger.path(metaPath)} (use --force to overwrite)`);
+			skipped++;
+			continue;
+		}
+		const screenMeta = inferScreenMeta(routeDir, routesPattern);
+		if (interactive) {
+			const result = await promptForScreen(routeFile, screenMeta);
+			if (result.skip) {
+				logger.itemWarn(`Skipped: ${logger.path(metaPath)}`);
+				skipped++;
+				continue;
 			}
-			created++;
+			const content = generateScreenMetaContent(result.meta, {
+				owner: result.owner,
+				tags: result.tags
+			});
+			if (dryRun) {
+				logDryRunOutput(metaPath, result.meta, result.owner, result.tags);
+				created++;
+			} else if (safeWriteFile(absoluteMetaPath, metaPath, content)) created++;
+		} else {
+			const content = generateScreenMetaContent(screenMeta);
+			if (dryRun) {
+				logDryRunOutput(metaPath, screenMeta);
+				created++;
+			} else if (safeWriteFile(absoluteMetaPath, metaPath, content)) created++;
 		}
+	}
+	logSummary(created, skipped, dryRun);
+}
+/**
+* Determine where to place screen.meta.ts for a route
+*/
+function determineMetaPath(route, cwd) {
+	if (route.componentPath) {
+		const relativePath = relative(cwd, dirname(route.componentPath));
+		if (!relativePath.startsWith("..")) return join(relativePath, "screen.meta.ts");
+	}
+	return join("src", "screens", route.screenId.replace(/\./g, "/"), "screen.meta.ts");
+}
+/**
+* Ensure the directory for a file exists
+*/
+function ensureDirectoryExists(filePath) {
+	const dir = dirname(filePath);
+	if (!existsSync(dir)) try {
+		mkdirSync(dir, { recursive: true });
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to create directory "${dir}": ${message}`);
+	}
+}
+/**
+* Safely write a file with error handling
+* Returns true if successful, false if failed
+*/
+function safeWriteFile(absolutePath, relativePath, content) {
+	try {
+		ensureDirectoryExists(absolutePath);
+		writeFileSync(absolutePath, content);
+		logger.itemSuccess(`Created: ${logger.path(relativePath)}`);
+		return true;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		logger.itemError(`Failed to create ${logger.path(relativePath)}: ${message}`);
+		return false;
+	}
+}
+/**
+* Log dry run output for a screen
+*/
+function logDryRunOutput(metaPath, meta, owner, tags) {
+	logger.step(`Would create: ${logger.path(metaPath)}`);
+	logger.log(`    ${logger.dim(`id: "${meta.id}"`)}`);
+	logger.log(`    ${logger.dim(`title: "${meta.title}"`)}`);
+	logger.log(`    ${logger.dim(`route: "${meta.route}"`)}`);
+	if (owner && owner.length > 0) logger.log(`    ${logger.dim(`owner: [${owner.map((o) => `"${o}"`).join(", ")}]`)}`);
+	if (tags && tags.length > 0) logger.log(`    ${logger.dim(`tags: [${tags.map((t) => `"${t}"`).join(", ")}]`)}`);
+	logger.blank();
+}
+/**
+* Log summary after generation
+*/
+function logSummary(created, skipped, dryRun) {
+	logger.blank();
+	if (dryRun) {
+		logger.info(`Would create ${created} files (${skipped} already exist)`);
 		logger.blank();
-		if (dryRun) {
-			logger.info(`Would create ${created} files (${skipped} already exist)`);
+		logger.log(`Run without ${logger.code("--dry-run")} to create files`);
+	} else {
+		logger.done(`Created ${created} files (${skipped} skipped)`);
+		if (created > 0) {
 			logger.blank();
-			logger.log(`Run without ${logger.code("--dry-run")} to create files`);
-		} else {
-			logger.done(`Created ${created} files (${skipped} skipped)`);
-			if (created > 0) {
-				logger.blank();
-				logger.log(logger.bold("Next steps:"));
-				logger.log("  1. Review and customize the generated screen.meta.ts files");
-				logger.log(`  2. Run ${logger.code("screenbook dev")} to view your screen catalog`);
-			}
+			logger.log(logger.bold("Next steps:"));
+			logger.log("  1. Review and customize the generated screen.meta.ts files");
+			logger.log(`  2. Run ${logger.code("screenbook dev")} to view your screen catalog`);
 		}
 	}
-});
+}
 /**
 * Parse comma-separated string into array
 */
@@ -1694,7 +2579,7 @@ const lintCommand = define({
 		const cwd = process.cwd();
 		const adoption = config.adoption ?? { mode: "full" };
 		let hasWarnings = false;
-		if (!config.routesPattern) {
+		if (!config.routesPattern && !config.routesFile) {
 			logger.errorWithHelp(ERRORS.ROUTES_PATTERN_MISSING);
 			process.exit(1);
 		}
@@ -1705,6 +2590,10 @@ const lintCommand = define({
 			if (adoption.minimumCoverage != null) logger.log(`Minimum coverage: ${adoption.minimumCoverage}%`);
 		}
 		logger.blank();
+		if (config.routesFile) {
+			await lintRoutesFile(config.routesFile, cwd, config, adoption, ctx.values.allowCycles ?? false, ctx.values.strict ?? false);
+			return;
+		}
 		let routeFiles = await glob(config.routesPattern, {
 			cwd,
 			ignore: config.ignore
@@ -1809,6 +2698,9 @@ const lintCommand = define({
 			} else if (error instanceof Error) {
 				logger.warn(`Failed to analyze screens.json: ${error.message}`);
 				hasWarnings = true;
+			} else {
+				logger.warn(`Failed to analyze screens.json: ${String(error)}`);
+				hasWarnings = true;
 			}
 		}
 		if (hasWarnings) {
@@ -1818,6 +2710,188 @@ const lintCommand = define({
 	}
 });
 /**
+* Lint screen.meta.ts coverage for routesFile mode (config-based routing)
+*/
+async function lintRoutesFile(routesFile, cwd, config, adoption, allowCycles, strict) {
+	let hasWarnings = false;
+	const absoluteRoutesFile = resolve(cwd, routesFile);
+	if (!existsSync(absoluteRoutesFile)) {
+		logger.errorWithHelp(ERRORS.ROUTES_FILE_NOT_FOUND(routesFile));
+		process.exit(1);
+	}
+	logger.log(`Parsing routes from ${logger.path(routesFile)}...`);
+	logger.blank();
+	let flatRoutes;
+	try {
+		const content = readFileSync(absoluteRoutesFile, "utf-8");
+		const routerType = detectRouterType(content);
+		let parseResult;
+		if (routerType === "tanstack-router") parseResult = parseTanStackRouterConfig(absoluteRoutesFile, content);
+		else if (routerType === "react-router") parseResult = parseReactRouterConfig(absoluteRoutesFile, content);
+		else parseResult = parseVueRouterConfig(absoluteRoutesFile, content);
+		for (const warning of parseResult.warnings) {
+			logger.warn(warning);
+			hasWarnings = true;
+		}
+		flatRoutes = flattenRoutes(parseResult.routes);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		logger.errorWithHelp(ERRORS.ROUTES_FILE_PARSE_ERROR(routesFile, message));
+		process.exit(1);
+	}
+	if (flatRoutes.length === 0) {
+		logger.warn("No routes found in the config file");
+		return hasWarnings;
+	}
+	const metaFiles = await glob(config.metaPattern, {
+		cwd,
+		ignore: config.ignore
+	});
+	const metaDirs = /* @__PURE__ */ new Set();
+	const metaDirsByName = /* @__PURE__ */ new Map();
+	for (const metaFile of metaFiles) {
+		const dir = dirname(metaFile);
+		metaDirs.add(dir);
+		const baseName = dir.split("/").pop()?.toLowerCase() || "";
+		if (baseName) metaDirsByName.set(baseName, dir);
+	}
+	const missingMeta = [];
+	const covered = [];
+	for (const route of flatRoutes) {
+		if (route.componentPath?.endsWith("Layout")) continue;
+		let matched = false;
+		const metaPath = determineMetaDir(route, cwd);
+		if (metaDirs.has(metaPath)) matched = true;
+		if (!matched && route.componentPath) {
+			const componentName = route.componentPath.toLowerCase();
+			if (metaDirsByName.has(componentName)) matched = true;
+			if (!matched) {
+				const parts = route.componentPath.split(/(?=[A-Z])/);
+				const lastPart = parts[parts.length - 1];
+				if (parts.length > 1 && lastPart) {
+					if (metaDirsByName.has(lastPart.toLowerCase())) matched = true;
+				}
+			}
+		}
+		if (!matched) {
+			const screenPath = route.screenId.replace(/\./g, "/");
+			for (const dir of metaDirs) if (dir.endsWith(screenPath)) {
+				matched = true;
+				break;
+			}
+		}
+		if (matched) covered.push(route);
+		else missingMeta.push(route);
+	}
+	const total = covered.length + missingMeta.length;
+	const coveredCount = covered.length;
+	const missingCount = missingMeta.length;
+	const coveragePercent = Math.round(coveredCount / total * 100);
+	logger.log(`Found ${total} routes`);
+	logger.log(`Coverage: ${coveredCount}/${total} (${coveragePercent}%)`);
+	logger.blank();
+	const minimumCoverage = adoption.minimumCoverage ?? 100;
+	const passedCoverage = coveragePercent >= minimumCoverage;
+	if (missingCount > 0) {
+		logger.log(`Missing screen.meta.ts (${missingCount} routes):`);
+		logger.blank();
+		for (const route of missingMeta) {
+			const suggestedMetaPath = determineSuggestedMetaPath(route, cwd);
+			logger.itemError(`${route.fullPath}  ${logger.dim(`(${route.screenId})`)}`);
+			logger.log(`    ${logger.dim("→")} ${logger.path(suggestedMetaPath)}`);
+		}
+		logger.blank();
+	}
+	if (!passedCoverage) {
+		logger.error(`Lint failed: Coverage ${coveragePercent}% is below minimum ${minimumCoverage}%`);
+		process.exit(1);
+	} else if (missingCount > 0) {
+		logger.success(`Coverage ${coveragePercent}% meets minimum ${minimumCoverage}%`);
+		if (adoption.mode === "progressive") logger.log(`  ${logger.dim("Tip:")} Increase minimumCoverage in config to gradually improve coverage`);
+	} else logger.done("All routes have screen.meta.ts files");
+	const screensPath = join(cwd, config.outDir, "screens.json");
+	if (existsSync(screensPath)) try {
+		const content = readFileSync(screensPath, "utf-8");
+		const screens = JSON.parse(content);
+		const orphans = findOrphanScreens(screens);
+		if (orphans.length > 0) {
+			hasWarnings = true;
+			logger.blank();
+			logger.warn(`Orphan screens detected (${orphans.length}):`);
+			logger.blank();
+			logger.log("  These screens have no entryPoints and are not");
+			logger.log("  referenced in any other screen's 'next' array.");
+			logger.blank();
+			for (const orphan of orphans) logger.itemWarn(`${orphan.id}  ${logger.dim(orphan.route)}`);
+			logger.blank();
+			logger.log(`  ${logger.dim("Consider adding entryPoints or removing these screens.")}`);
+		}
+		if (!allowCycles) {
+			const cycleResult = detectCycles(screens);
+			if (cycleResult.hasCycles) {
+				hasWarnings = true;
+				logger.blank();
+				logger.warn(getCycleSummary(cycleResult));
+				logger.log(formatCycleWarnings(cycleResult.cycles));
+				logger.blank();
+				if (cycleResult.disallowedCycles.length > 0) {
+					logger.log(`  ${logger.dim("Use 'allowCycles: true' in screen.meta.ts to allow intentional cycles.")}`);
+					if (strict) {
+						logger.blank();
+						logger.errorWithHelp(ERRORS.CYCLES_DETECTED(cycleResult.disallowedCycles.length));
+						process.exit(1);
+					}
+				}
+			}
+		}
+		const invalidNavs = findInvalidNavigations(screens);
+		if (invalidNavs.length > 0) {
+			hasWarnings = true;
+			logger.blank();
+			logger.warn(`Invalid navigation targets (${invalidNavs.length}):`);
+			logger.blank();
+			logger.log("  These navigation references point to non-existent screens.");
+			logger.blank();
+			for (const inv of invalidNavs) logger.itemWarn(`${inv.screenId} → ${logger.dim(inv.field)}: "${inv.target}"`);
+			logger.blank();
+			logger.log(`  ${logger.dim("Check that these screen IDs exist in your codebase.")}`);
+		}
+	} catch (error) {
+		if (error instanceof SyntaxError) {
+			logger.warn("Failed to parse screens.json - file may be corrupted");
+			logger.log(`  ${logger.dim("Run 'screenbook build' to regenerate.")}`);
+			hasWarnings = true;
+		} else if (error instanceof Error) {
+			logger.warn(`Failed to analyze screens.json: ${error.message}`);
+			hasWarnings = true;
+		} else {
+			logger.warn(`Failed to analyze screens.json: ${String(error)}`);
+			hasWarnings = true;
+		}
+	}
+	if (hasWarnings) {
+		logger.blank();
+		logger.warn("Lint completed with warnings.");
+	}
+	return hasWarnings;
+}
+/**
+* Determine the directory where screen.meta.ts should be for a route
+*/
+function determineMetaDir(route, cwd) {
+	if (route.componentPath) {
+		const relativePath = relative(cwd, dirname(route.componentPath));
+		if (!relativePath.startsWith("..")) return relativePath;
+	}
+	return join("src", "screens", route.screenId.replace(/\./g, "/"));
+}
+/**
+* Determine the suggested screen.meta.ts path for a route
+*/
+function determineSuggestedMetaPath(route, cwd) {
+	return join(determineMetaDir(route, cwd), "screen.meta.ts");
+}
+/**
 * Find navigation references that point to non-existent screens.
 * Checks `next`, `entryPoints` arrays and mock navigation targets.
 */