jac-client 0.2.13__py3-none-any.whl → 0.2.15__py3-none-any.whl

jac_client/plugin/src/impl/compiler.impl.jac

@@ -22,8 +22,16 @@ impl ViteCompiler.compile(
     );
     client_globals_map = self.jac_compiler.extract_globals(module_manifest, module);
     collected_globals: dict[(str, Any)] = dict(client_globals_map);
+    visited: set[Path] = set();
     self.compile_dependencies_recursively(
         module_path,
+        visited=visited,
+        collected_exports=collected_exports,
+        collected_globals=collected_globals
+    );
+    # Scan pages/ directory for file-based routing (compiles page files too)
+    self._has_pages = self._scan_and_compile_pages(
+        visited=visited,
         collected_exports=collected_exports,
         collected_globals=collected_globals
     );
@@ -55,12 +63,110 @@ impl ViteCompiler.compile_and_bundle(
 impl ViteCompiler.create_entry_file(self: ViteCompiler, module_path: Path) -> None {
     # Use _entry.js to avoid conflict with compiled modules that may be named main.js
     entry_file = self.compiled_dir / '_entry.js';
-    # Derive the app module filename from the entry point (e.g., main.jac -> main.js, app.jac -> app.js)
-    app_module_name = module_path.stem;
-    entry_content = f'import React from "react";\nimport {{ createRoot }} from "react-dom/client";\nimport {{ app as App }} from "./{app_module_name}.js";\nimport {{ JacClientErrorBoundary, ErrorFallback }} from "@jac/runtime";\n\nconst root = createRoot(document.getElementById("root"));\nroot.render(\n\tReact.createElement(\n\t\tJacClientErrorBoundary,{{ FallbackComponent: ErrorFallback }},\n\t\tReact.createElement(App, null)\n\t)\n);\n';
+    if self._has_pages {
+        # File-based routing mode: import from generated _routes.js
+        entry_content = self._create_pages_entry_content(module_path);
+    } else {
+        # Explicit routing mode: import app from entry module (original behavior)
+        app_module_name = module_path.stem;
+        entry_content = f'import React from "react";\nimport {{ createRoot }} from "react-dom/client";\nimport {{ app as App }} from "./{app_module_name}.js";\nimport {{ JacClientErrorBoundary, ErrorFallback }} from "@jac/runtime";\n\nconst root = createRoot(document.getElementById("root"));\nroot.render(\n\tReact.createElement(\n\t\tJacClientErrorBoundary,{{ FallbackComponent: ErrorFallback }},\n\t\tReact.createElement(App, null)\n\t)\n);\n';
+    }
     entry_file.write_text(entry_content, encoding='utf-8');
 }
 
+impl ViteCompiler._create_pages_entry_content(
+    self: ViteCompiler, module_path: Path
+) -> str {
+    lines: list[str] = [];
+    auth_redirect = "/login";
+    try {
+        import from ..config_loader { PluginConfig }
+        config = PluginConfig.load(self.project_dir);
+        if config and config?.routing and config.routing {
+            auth_redirect = config.routing.get('auth_redirect', '/login');
+        }
+    } except Exception { }
+    # Check if main.jac exists and exports app (used as wrapper)
+    app_module = self.compiled_dir / f"{module_path.stem}.js";
+    has_app_wrapper = app_module.exists();
+    # --- Imports ---
+    lines.append('import React from "react";');
+    lines.append('import { createRoot } from "react-dom/client";');
+    lines.append('import { BrowserRouter, Routes, Route } from "react-router-dom";');
+    lines.append(
+        'import { JacClientErrorBoundary, ErrorFallback, AuthGuard } from "@jac/runtime";'
+    );
+    lines.append('import { routes, layouts } from "./_routes.js";');
+    if has_app_wrapper {
+        lines.append(f'import {{ app as AppWrapper }} from "./{module_path.stem}.js";');
+    }
+    lines.append('');
+    # --- Route helpers ---
+    lines.append('const publicRoutes = routes.filter(r => !r.auth);');
+    lines.append('const authRoutes = routes.filter(r => r.auth);');
+    lines.append('const RootLayout = layouts["/"] || null;');
+    lines.append('');
+    lines.append('function renderRoutes(routeList) {');
+    lines.append('\treturn routeList.map(r =>');
+    lines.append(
+        '\t\tReact.createElement(Route, { key: r.path, path: r.path, element: React.createElement(r.element, null) })'
+    );
+    lines.append('\t);');
+    lines.append('}');
+    lines.append('');
+    # --- Auth guard routes (reused in both layout and non-layout paths) ---
+    # AuthGuard is a runtime function compiled with plain parameters (not React props
+    # destructuring), so we wrap it in a component that passes the redirect string directly.
+    lines.append(
+        f'function _AuthGuardRoute() {{ return AuthGuard("{auth_redirect}"); }}'
+    );
+    lines.append(
+        'const authGuardElement = React.createElement(_AuthGuardRoute, null);'
+    );
+    lines.append('');
+    # --- Single App component with one BrowserRouter ---
+    lines.append('function App() {');
+    lines.append('\tconst routeChildren = [');
+    lines.append('\t\t...renderRoutes(publicRoutes),');
+    lines.append(
+        '\t\tReact.createElement(Route, { key: "__auth", element: authGuardElement },'
+    );
+    lines.append('\t\t\t...renderRoutes(authRoutes)');
+    lines.append('\t\t),');
+    lines.append('\t];');
+    lines.append('');
+    lines.append('\tconst routeTree = RootLayout');
+    lines.append(
+        '\t\t? React.createElement(Route, { element: React.createElement(RootLayout, null) }, ...routeChildren)'
+    );
+    lines.append('\t\t: routeChildren;');
+    lines.append('');
+    lines.append('\treturn React.createElement(BrowserRouter, null,');
+    lines.append('\t\tReact.createElement(Routes, null,');
+    lines.append('\t\t\t...(Array.isArray(routeTree) ? routeTree : [routeTree])');
+    lines.append('\t\t)');
+    lines.append('\t);');
+    lines.append('}');
+    lines.append('');
+    # --- Root render ---
+    if has_app_wrapper {
+        lines.append(
+            'const appElement = React.createElement(AppWrapper, null, React.createElement(App, null));'
+        );
+    } else {
+        lines.append('const appElement = React.createElement(App, null);');
+    }
+    lines.append('');
+    lines.append('const root = createRoot(document.getElementById("root"));');
+    lines.append('root.render(');
+    lines.append(
+        '\tReact.createElement(JacClientErrorBoundary, { FallbackComponent: ErrorFallback }, appElement)'
+    );
+    lines.append(');');
+    lines.append('');
+    return "\n".join(lines);
+}
+
 """Copy assets from root assets/ folder to compiled/assets/ for @jac-client/assets alias."""
 impl ViteCompiler.copy_root_assets(self: ViteCompiler) -> None {
     root_assets_dir = self.project_dir / 'assets';
@@ -171,28 +277,10 @@ impl ViteCompiler.compile_dependencies_recursively(
     combined_js = self.jac_compiler.add_runtime_imports(module_js);
     try {
         relative_path = module_path.relative_to(source_root);
-        # Handle compound extensions like .cl.jac, .impl.jac -> .js
-        rel_str = str(relative_path);
-        for compound_ext in ['.cl.jac', '.impl.jac', '.test.jac'] {
-            if rel_str.endswith(compound_ext) {
-                rel_str = rel_str[:-len(compound_ext)] + '.js';
-                break;
-            }
-        } else {
-            rel_str = str(relative_path.with_suffix('.js'));
-        }
+        rel_str = self._jac_path_to_js(str(relative_path));
         output_path = self.compiled_dir / rel_str;
     } except ValueError {
-        # Handle compound extensions in filename
-        name = module_path.name;
-        for compound_ext in ['.cl.jac', '.impl.jac', '.test.jac'] {
-            if name.endswith(compound_ext) {
-                name = name[:-len(compound_ext)] + '.js';
-                break;
-            }
-        } else {
-            name = module_path.stem + '.js';
-        }
+        name = self._jac_path_to_js(module_path.name);
         output_path = self.compiled_dir / name;
     }
     output_path.parent.mkdir(parents=True, exist_ok=True);
@@ -247,6 +335,109 @@ impl ViteCompiler.compile_runtime_utils(self: ViteCompiler) -> tuple[str, list[s
     return (runtimeutils_js, all_exports);
 }
 
+"""Convert a .jac relative path string to .js, handling compound extensions."""
+impl ViteCompiler._jac_path_to_js(self: ViteCompiler, rel_str: str) -> str {
+    for compound_ext in self.COMPOUND_EXTENSIONS {
+        if rel_str.endswith(compound_ext) {
+            return rel_str[:-len(compound_ext)] + '.js';
+        }
+    }
+    return str(Path(rel_str).with_suffix('.js'));
+}
+
+"""Scan pages/ directory, compile page files, and generate _routes.js manifest.
+Returns True if pages/ exists and routes were generated."""
+impl ViteCompiler._scan_and_compile_pages(
+    self: ViteCompiler,
+    visited: (set[Path] | None) = None,
+    collected_exports: (set[str] | None) = None,
+    collected_globals: (dict[(str, Any)] | None) = None
+) -> bool {
+    scanner = RouteScanner(self.project_dir);
+    if not scanner.has_pages_dir() {
+        return False;
+    }
+    routes = scanner.scan();
+    if not routes and not scanner.get_layouts() {
+        return False;
+    }
+    self._route_scanner = scanner;
+    # Compile each page file through the standard pipeline
+    source_root = self.project_dir;
+    for page_file in scanner.get_page_files() {
+        self.compile_dependencies_recursively(
+            page_file,
+            visited=visited,
+            collected_exports=collected_exports,
+            collected_globals=collected_globals,
+            source_root=source_root
+        );
+    }
+    self._generate_routes_manifest();
+    return True;
+}
+
+"""Generate _routes.js manifest from previously scanned route entries."""
+impl ViteCompiler._generate_routes_manifest(self: ViteCompiler) -> None {
+    scanner = self._route_scanner;
+    # Use cached results from _scan_and_compile_pages — don't re-scan
+    routes = scanner._routes;
+    layouts = scanner.get_layouts();
+    lines: list[str] = [];
+    # Import page components
+    for route in routes {
+        if route.is_layout {
+            continue;
+        }
+        # Compute relative import path from pages/ to compiled/pages/
+        try {
+            rel_path = route.file_path.relative_to(self.project_dir);
+        } except ValueError {
+            rel_path = route.file_path.relative_to(scanner.pages_dir.parent);
+        }
+        rel_str = self._jac_path_to_js(str(rel_path));
+        lines.append(
+            f'import {{ page as {route.component_import} }} from "./{rel_str}";'
+        );
+    }
+    # Import layout components
+    for (prefix, layout) in layouts.items() {
+        try {
+            rel_path = layout.file_path.relative_to(self.project_dir);
+        } except ValueError {
+            rel_path = layout.file_path.relative_to(scanner.pages_dir.parent);
+        }
+        rel_str = self._jac_path_to_js(str(rel_path));
+        lines.append(
+            f'import {{ layout as {layout.component_import} }} from "./{rel_str}";'
+        );
+    }
+    lines.append('');
+    # Export routes array
+    lines.append('export const routes = [');
+    for route in routes {
+        if route.is_layout {
+            continue;
+        }
+        auth_str = "true" if route.auth_required else "false";
+        lines.append(
+            f'\t{{ path: "{route.path}", element: {route.component_import}, auth: {auth_str} }},'
+        );
+    }
+    lines.append('];');
+    lines.append('');
+    # Export layouts object
+    lines.append('export const layouts = {');
+    for (prefix, layout) in layouts.items() {
+        lines.append(f'\t"{prefix}": {layout.component_import},');
+    }
+    lines.append('};');
+    lines.append('');
+    manifest_path = self.compiled_dir / '_routes.js';
+    manifest_path.parent.mkdir(parents=True, exist_ok=True);
+    manifest_path.write_text("\n".join(lines), encoding='utf-8');
+}
+
 """Initialize the Vite compiler."""
 impl ViteCompiler.init(
     self: ViteCompiler,
@@ -294,4 +485,6 @@ impl ViteCompiler.init(
     self.import_processor = ImportProcessor();
     self.asset_processor = AssetProcessor();
     self.vite_bundler = ViteBundler(self.project_dir, vite_output_dir, vite_minify);
+    self._has_pages = False;
+    self._route_scanner = None;
 }

jac_client/plugin/src/impl/package_installer.impl.jac

@@ -40,6 +40,7 @@ impl PackageInstaller.uninstall_package(
 """Regenerate package.json from jac.toml and run bun install."""
 impl PackageInstaller._regenerate_and_install(self: PackageInstaller) -> None {
     import from jac_client.plugin.utils { ensure_bun_available }
+    import from jaclang.cli.console { console }
     # Ensure bun is available before proceeding
     if not ensure_bun_available() {
         raise ClientBundleError('Bun is required. Install manually: https://bun.sh') from None ;
@@ -51,14 +52,14 @@ impl PackageInstaller._regenerate_and_install(self: PackageInstaller) -> None {
     bundler._ensure_root_package_json();
     try {
         # Run bun install to actually install the packages
-        print("\n  ⏳ Installing packages...\n", flush=True);
+        console.print("\n  ⏳ Installing packages...\n");
         result = subprocess.run(
             ['bun', 'install'], cwd=self.project_dir, check=False, text=True
         );
         if result.returncode != 0 {
             raise ClientBundleError('Failed to install packages (see output above)') ;
         }
-        print("\n  ✔ Packages installed", flush=True);
+        console.print("\n  ✔ Packages installed");
     } finally {
         # Always clean up root package.json and move bun.lockb
         bundler._cleanup_root_package_files();

jac_client/plugin/src/impl/route_scanner.impl.jac

@@ -0,0 +1,201 @@
+import re;
+import from pathlib { Path }
+import from operator { attrgetter }
+import from jaclang.runtimelib.client_bundle { ClientBundleError }
+
+impl RouteEntry.init(
+    self: RouteEntry,
+    path: str,
+    component_import: str,
+    file_path: Path,
+    auth_required: bool = False,
+    is_layout: bool = False,
+    is_catch_all: bool = False,
+    children: (list[RouteEntry] | None) = None
+) {
+    self.path = path;
+    self.component_import = component_import;
+    self.file_path = file_path;
+    self.auth_required = auth_required;
+    self.is_layout = is_layout;
+    self.is_catch_all = is_catch_all;
+    self.children = children if children is not None else [];
+}
+
+impl RouteScanner.init(self: RouteScanner, project_root: Path) {
+    self.project_root = project_root;
+    self.pages_dir = project_root / self.PAGES_DIR_NAME;
+    self._routes: list[RouteEntry] = [];
+    self._layouts: dict[(str, RouteEntry)] = {};
+    self._page_files: list[Path] = [];
+}
+
+impl RouteScanner.has_pages_dir(self: RouteScanner) -> bool {
+    return self.pages_dir.exists() and self.pages_dir.is_dir();
+}
+
+impl RouteScanner.scan(self: RouteScanner) -> list[RouteEntry] {
+    if not self.has_pages_dir() {
+        return [];
+    }
+    self._routes = [];
+    self._layouts = {};
+    self._page_files = [];
+    self._routes = self._scan_directory(self.pages_dir);
+    self._detect_collisions(self._routes);
+    return self._routes;
+}
+
+"""Return layouts discovered during the last scan, keyed by URL prefix."""
+impl RouteScanner.get_layouts(self: RouteScanner) -> dict[(str, RouteEntry)] {
+    return self._layouts;
+}
+
+impl RouteScanner.get_page_files(self: RouteScanner) -> list[Path] {
+    return self._page_files;
+}
+
+impl RouteScanner._scan_directory(
+    self: RouteScanner,
+    dir_path: Path,
+    url_prefix: str = "",
+    auth_required: bool = False
+) -> list[RouteEntry] {
+    routes: list[RouteEntry] = [];
+    # Collect and sort entries for deterministic route ordering
+    entries = sorted(dir_path.iterdir(), key=attrgetter('name'));
+    for entry in entries {
+        if entry.is_dir() {
+            dir_name = entry.name;
+            # Route groups: (public), (auth), etc.
+            group_match = re.match(r'^\((\w+)\)$', dir_name);
+            if group_match {
+                group_name = group_match.group(1);
+                group_auth = auth_required or (group_name == self.AUTH_GROUP_NAME);
+                # Route groups don't add to the URL path
+                child_routes = self._scan_directory(entry, url_prefix, group_auth);
+                routes.extend(child_routes);
+            } else {
+                # Regular subdirectory — adds to URL path
+                child_prefix = f"{url_prefix}/{dir_name}";
+                child_routes = self._scan_directory(entry, child_prefix, auth_required);
+                routes.extend(child_routes);
+            }
+        } elif entry.is_file() and entry.suffix == '.jac' {
+            if any(suffix in entry.name for suffix in self.SKIP_SUFFIXES) {
+                continue;
+            }
+            stem = entry.stem;
+            # layout.jac — not a route, it's a layout wrapper
+            if stem == self.LAYOUT_FILENAME {
+                layout_key = url_prefix or "/";
+                if layout_key in self._layouts {
+                    raise ClientBundleError(
+                        f"Layout collision: '{layout_key}' has layouts from both "
+                        f"'{self._layouts[layout_key].file_path}' and '{entry}'. "
+                        f"Remove one of them."
+                    ) ;
+                }
+                component_name = self._file_to_component_name(entry);
+                layout_entry = RouteEntry(
+                    path=layout_key,
+                    component_import=component_name,
+                    file_path=entry,
+                    is_layout=True
+                );
+                self._layouts[layout_key] = layout_entry;
+                self._page_files.append(entry);
+                continue;
+            }
+            route_segment = self._file_to_route_path(stem);
+            is_catch_all = stem.startswith('[...');
+            if stem == self.INDEX_FILENAME {
+                # index.jac maps to the directory path
+                route_path = url_prefix or "/";
+            } else {
+                route_path = f"{url_prefix}/{route_segment}";
+            }
+            component_name = self._file_to_component_name(entry);
+            route = RouteEntry(
+                path=route_path,
+                component_import=component_name,
+                file_path=entry,
+                auth_required=auth_required,
+                is_catch_all=is_catch_all
+            );
+            routes.append(route);
+            self._page_files.append(entry);
+        }
+    }
+    return routes;
+}
+
+"""Convert a filename stem to a React Router route path segment.
+
+    index       → (empty, handled by caller)
+    about       → about
+    [id]        → :id
+    [...slug]   → *
+"""
+impl RouteScanner._file_to_route_path(self: RouteScanner, filename: str) -> str {
+    # Catch-all: [...slug] → *
+    catch_all_match = re.match(r'^\[\.\.\.(\w+)\]$', filename);
+    if catch_all_match {
+        return "*";
+    }
+    # Dynamic segment: [id] → :id
+    dynamic_match = re.match(r'^\[(\w+)\]$', filename);
+    if dynamic_match {
+        return f":{dynamic_match.group(1)}";
+    }
+    # Static segment
+    return filename;
+}
+
+"""Generate a unique component import name from a page file path.
+
+    pages/index.jac             → PagesIndex
+    pages/about.jac             → PagesAbout
+    pages/(auth)/dashboard.jac  → PagesDashboard
+    pages/users/[id].jac        → PagesUsersId
+    pages/[...slug].jac         → PagesSlug
+"""
+impl RouteScanner._file_to_component_name(self: RouteScanner, file_path: Path) -> str {
+    try {
+        relative = file_path.relative_to(self.pages_dir);
+    } except ValueError {
+        relative = Path(file_path.name);
+    }
+    parts: list[str] = [];
+    for part in relative.with_suffix('').parts {
+        # Skip route group directories like (auth), (public)
+        if re.match(r'^\(\w+\)$', part) {
+            continue;
+        }
+        # Strip catch-all prefix: [...slug] → slug
+        clean = re.sub(r'^\[\.\.\.(\w+)\]$', r'\1', part);
+        # Strip dynamic brackets: [id] → id
+        clean = re.sub(r'^\[(\w+)\]$', r'\1', clean);
+        parts.append(clean[0].upper() + clean[1:] if len(clean) > 0 else clean);
+    }
+    return self.COMPONENT_PREFIX + "".join(parts);
+}
+
+impl RouteScanner._detect_collisions(
+    self: RouteScanner, routes: list[RouteEntry]
+) -> None {
+    seen: dict[(str, Path)] = {};
+    for route in routes {
+        if route.is_layout {
+            continue;
+        }
+        if route.path in seen {
+            raise ClientBundleError(
+                f"Route collision: '{route.path}' is defined by both "
+                f"'{seen[route.path]}' and '{route.file_path}'. "
+                f"Remove one of them."
+            ) ;
+        }
+        seen[route.path] = route.file_path;
+    }
+}

jac_client/plugin/src/impl/vite_bundler.impl.jac

@@ -1,11 +1,17 @@
+import from jaclang.cli.console { console }
+
 """Get the client build directory from project config."""
 impl ViteBundler._get_client_dir(self: ViteBundler) -> Path {
-    # Try to get from project config
+    # Try to get from project config, but only if it matches our project dir
     try {
         import from jaclang.project.config { get_config }
         config = get_config();
         if config is not None {
-            return config.get_client_dir();
+            config_root = config.project_root;
+            if config_root is not None
+            and config_root.resolve() == self.project_dir.resolve() {
+                return config.get_client_dir();
+            }
         }
     } except ImportError { }
     # Fallback to default
@@ -482,7 +488,7 @@ impl ViteBundler.build(self: ViteBundler, entry_file: Optional[Path] = None) ->
             }
             try {
                 # Install to .jac/client/node_modules with progress feedback
-                print("\n  ⏳ Installing dependencies...\n", flush=True);
+                console.print("\n  ⏳ Installing dependencies...\n");
                 start_time = time.time();
                 result = subprocess.run(
                     ['bun', 'install'],
@@ -497,7 +503,7 @@ impl ViteBundler.build(self: ViteBundler, entry_file: Optional[Path] = None) ->
                     error_msg = f"Dependency installation failed after {elapsed:.1f}s\n\n{error_output}\nCommand: bun install";
                     raise ClientBundleError(error_msg) from None ;
                 }
-                print(f"\n  ✔ Dependencies installed ({elapsed:.1f}s)", flush=True);
+                console.print(f"\n  ✔ Dependencies installed ({elapsed:.1f}s)");
             } except FileNotFoundError {
                 # This shouldn't happen since we check for bun at the start
                 raise ClientBundleError(
@@ -530,7 +536,7 @@ impl ViteBundler.build(self: ViteBundler, entry_file: Optional[Path] = None) ->
             command = ['bun', 'run', 'build'];
         }
         # Run vite from client build directory so it can find node_modules
-        print("\n  ⏳ Building client bundle...\n", flush=True);
+        console.print("\n  ⏳ Building client bundle...\n");
         start_time = time.time();
         result = subprocess.run(
             command, cwd=build_dir, check=False, text=True, capture_output=True
@@ -543,7 +549,7 @@ impl ViteBundler.build(self: ViteBundler, entry_file: Optional[Path] = None) ->
             )}";
             raise ClientBundleError(error_msg) from None ;
         }
-        print(f"\n  ✔ Client bundle built ({elapsed:.1f}s)", flush=True);
+        console.print(f"\n  ✔ Client bundle built ({elapsed:.1f}s)");
     } finally {
         # Clean up temporary package.json in client build dir
         build_package_json = build_dir / 'package.json';
@@ -766,19 +772,17 @@ impl ViteBundler.start_dev_server(self: ViteBundler, port: int = 3000) -> Any {
             shutil.copy2(generated_package_json, build_package_json);
         }
         try {
-            print("\n  ⏳ Installing dependencies...\n", flush=True);
+            console.print("\n  ⏳ Installing dependencies...\n");
             start_time = time.time();
             result = subprocess.run(
                 ['bun', 'install'], cwd=build_dir, check=False, text=True
             );
             elapsed = time.time() - start_time;
             if result.returncode != 0 {
-                print(
-                    f"\n  ✖ bun install failed after {elapsed:.1f}s", file=sys.stderr
-                );
+                console.error(f"\n  ✖ bun install failed after {elapsed:.1f}s");
                 raise ClientBundleError("Failed to install dependencies") ;
             }
-            print(f"\n  ✔ Dependencies installed ({elapsed:.1f}s)", flush=True);
+            console.print(f"\n  ✔ Dependencies installed ({elapsed:.1f}s)");
         } finally {
             # Clean up temp package.json
             if build_package_json.exists() {

jac_client/plugin/src/route_scanner.jac

@@ -0,0 +1,44 @@
+"""File-based route scanner for pages/ directory convention."""
+import from pathlib { Path }
+
+"""A single route entry derived from a file in pages/."""
+class RouteEntry {
+    def init(
+        self: RouteEntry,
+        path: str,
+        component_import: str,
+        file_path: Path,
+        auth_required: bool = False,
+        is_layout: bool = False,
+        is_catch_all: bool = False,
+        children: (list[RouteEntry] | None) = None
+    );
+}
+
+"""Scans a pages/ directory and produces a route tree."""
+class RouteScanner {
+    with entry {
+        PAGES_DIR_NAME = 'pages';
+        LAYOUT_FILENAME = 'layout';
+        INDEX_FILENAME = 'index';
+        AUTH_GROUP_NAME = 'auth';
+        COMPONENT_PREFIX = 'Pages';
+        SKIP_SUFFIXES = ['.cl.', '.impl.', '.test.'];
+    }
+
+    def init(self: RouteScanner, project_root: Path);
+    def has_pages_dir(self: RouteScanner) -> bool;
+    def scan(self: RouteScanner) -> list[RouteEntry];
+    def get_layouts(self: RouteScanner) -> dict[(str, RouteEntry)];
+    def get_page_files(self: RouteScanner) -> list[Path];
+    def _scan_directory(
+        self: RouteScanner,
+        dir_path: Path,
+        url_prefix: str = "",
+        auth_required: bool = False
+    ) -> list[RouteEntry];
+
+    def _file_to_route_path(self: RouteScanner, filename: str) -> str;
+    def _file_to_component_name(self: RouteScanner, file_path: Path) -> str;
+    def _detect_collisions(self: RouteScanner, routes: list[RouteEntry]) -> None;
+}