pastoria 1.1.0 → 1.2.1

package/dist/generate.js

@@ -1,67 +1,88 @@
 /**
  * @fileoverview Router Code Generator
  *
- * This script generates type-safe router configuration files by scanning TypeScript
- * source code for JSDoc annotations. It's part of the "Pastoria" routing framework.
+ * This script generates type-safe router configuration files using filesystem-based
+ * routing, similar to Next.js App Router.
  *
- * How it works:
- * 1. Scans all TypeScript files in the project for exported functions/classes
- * 2. Looks for JSDoc tags: @route, @resource, @appRoot, and @param
- * 3. Looks for exported classes that extend PastoriaRootContext for GraphQL context
- * 4. Generates files from templates:
- *    - js_resource.ts: Resource configuration for lazy loading
- *    - router.tsx: Client-side router with type-safe routes
- *    - app_root.ts: Re-export of the app root component (if @appRoot is found)
- *    - context.ts: Re-export of user's context class, or generate a default one
+ * ## Filesystem Routing Convention
  *
- * Usage:
- * - Add @route <route-name> to functions to create routes
- * - Add @param <name> <type> to document route parameters
- * - Add @resource <resource-name> to exports for lazy loading
- * - Add @appRoot to a component to designate it as the application root wrapper
- * - Add @gqlContext to a class extending PastoriaRootContext to provide a custom GraphQL context
- * - Add @serverRoute to functions to add an express handler
+ * Routes are defined by the directory structure under `pastoria/`:
+ * - `pastoria/page.tsx` → Route `/`
+ * - `pastoria/about/page.tsx` → Route `/about`
+ * - `pastoria/post/[slug]/page.tsx` → Route `/post/:slug`
+ * - `pastoria/app.tsx` → Root layout component
+ * - `pastoria/api/.../route.ts` → API route handlers
+ * - `pastoria/*.page.tsx` → Nested entry points
+ * - `pastoria/entrypoint.ts` → Manual entry point definitions
  *
- * The generator automatically creates Zod schemas for route parameters based on
- * TypeScript types, enabling runtime validation and type safety.
+ * ## Page Files
+ *
+ * Each `page.tsx` should:
+ * - Default export a React component
+ * - Optionally export `queries` object mapping query refs to Relay query types
+ *
+ * ## Generated Files
+ *
+ * Output is placed in `__generated__/router/`:
+ * - `js_resource.ts` - Resource configuration for lazy loading
+ * - `router.tsx` - Client-side router with type-safe routes
+ * - `app_root.ts` - Re-export of the app root component
+ * - `environment.ts` - Re-export of the user's PastoriaEnvironment
+ * - `server_handler.ts` - API route handlers
+ * - `types.ts` - PageProps and other type definitions
  */
 import { readFile } from 'node:fs/promises';
 import * as path from 'node:path';
 import pc from 'picocolors';
-import { SyntaxKind, ts, TypeFlags, } from 'ts-morph';
+import { SyntaxKind, TypeFlags, } from 'ts-morph';
+import { scanFilesystemRoutes, toRouterPath, } from './filesystem.js';
 import { logInfo, logWarn } from './logger.js';
-async function loadRouterTemplates(project, filename) {
-    async function loadSourceFile(fileName, templateFileName) {
-        const template = await readFile(templateFileName, 'utf-8');
-        const warningComment = `/*
+// ============================================================================
+// Template Loading
+// ============================================================================
+/**
+ * Loads a template file and creates a new source file with a generated header.
+ */
+async function loadRouterTemplate(project, filename) {
+    const templatePath = path.join(import.meta.dirname, '../templates', filename);
+    const outputPath = path.join('__generated__/router', filename);
+    const template = await readFile(templatePath, 'utf-8');
+    const warningComment = `/*
  * This file was generated by \`pastoria\`.
- * Do not modify this file directly. Instead, edit the template at ${path.basename(templateFileName)}.
+ * Do not modify this file directly.
  */
 
 `;
-        return project.createSourceFile(fileName, warningComment + template, {
-            overwrite: true,
-        });
-    }
-    const template = path.join(import.meta.dirname, '../templates', filename);
-    const output = path.join('__generated__/router', filename);
-    return loadSourceFile(output, template);
+    return project.createSourceFile(outputPath, warningComment + template, {
+        overwrite: true,
+    });
 }
-// Regex to quickly check if a file contains any Pastoria JSDoc tags
-export const PASTORIA_TAG_REGEX = /@(route|resource|appRoot|param|gqlContext|serverRoute)\b/;
+// ============================================================================
+// Query Parameter Collection
+// ============================================================================
+/**
+ * Collects query variables from Relay-generated query type files.
+ *
+ * For each query, looks up the generated `${queryName}$variables` type
+ * and extracts all property names and types.
+ */
 function collectQueryParameters(project, queries) {
     const vars = new Map();
     for (const query of queries) {
-        const variablesType = project
-            .getSourceFile(`__generated__/queries/${query}.graphql.ts`)
-            ?.getExportedDeclarations()
+        // Find the generated query file
+        const queryFile = project.getSourceFile(`__generated__/queries/${query}.graphql.ts`);
+        if (!queryFile)
+            continue;
+        // Get the variables type export
+        const variablesType = queryFile
+            .getExportedDeclarations()
             .get(`${query}$variables`)
             ?.at(0)
             ?.getType();
-        if (variablesType == null)
+        if (!variablesType)
             continue;
+        // Extract each property from the variables type
         for (const property of variablesType.getProperties()) {
-            // TODO: Detect conflicting types among properties declared.
             const propertyName = property.getName();
             const propertyType = property.getValueDeclaration()?.getType();
             if (propertyType) {
@@ -71,197 +92,16 @@ function collectQueryParameters(project, queries) {
     }
     return vars;
 }
-function collectPastoriaMetadata(project) {
-    const resources = new Map();
-    const routes = new Map();
-    const serverHandlers = new Map();
-    let appRoot = null;
-    let gqlContext = null;
-    function visitRouterNodes(sourceFile) {
-        // Skip generated files
-        if (sourceFile.getFilePath().includes('__generated__')) {
-            return;
-        }
-        // Skip files that don't contain any Pastoria JSDoc tags
-        const fileText = sourceFile.getFullText();
-        if (!PASTORIA_TAG_REGEX.test(fileText)) {
-            return;
-        }
-        sourceFile.getExportSymbols().forEach((symbol) => {
-            let routerResource = null;
-            let routerRoute = null;
-            const routeParams = new Map();
-            function visitJSDocTags(tag) {
-                if (ts.isJSDoc(tag)) {
-                    tag.tags?.forEach(visitJSDocTags);
-                }
-                else if (ts.isJSDocParameterTag(tag)) {
-                    const typeNode = tag.typeExpression?.type;
-                    const tc = project.getTypeChecker().compilerObject;
-                    const type = typeNode == null
-                        ? tc.getUnknownType()
-                        : tc.getTypeFromTypeNode(typeNode);
-                    routeParams.set(tag.name.getText(), type);
-                }
-                else if (typeof tag.comment === 'string') {
-                    switch (tag.tagName.getText()) {
-                        case 'route': {
-                            routerRoute = [
-                                tag.comment,
-                                { sourceFile, symbol, params: routeParams },
-                            ];
-                            break;
-                        }
-                        case 'resource': {
-                            routerResource = [
-                                tag.comment,
-                                {
-                                    sourceFile,
-                                    symbol,
-                                    queries: new Map(),
-                                    entryPoints: new Map(),
-                                },
-                            ];
-                            break;
-                        }
-                        case 'serverRoute': {
-                            serverHandlers.set(tag.comment, { sourceFile, symbol });
-                            break;
-                        }
-                    }
-                }
-                else {
-                    // Handle tags without comments (like @ExportedSymbol, @gqlContext)
-                    switch (tag.tagName.getText()) {
-                        case 'appRoot': {
-                            if (appRoot != null) {
-                                logWarn('Multiple @appRoot tags found. Using the first one.');
-                            }
-                            else {
-                                appRoot = {
-                                    sourceFile,
-                                    symbol,
-                                };
-                            }
-                            break;
-                        }
-                        case 'gqlContext': {
-                            // Check if this class extends PastoriaRootContext
-                            const declarations = symbol.getDeclarations();
-                            let extendsPastoriaRootContext = false;
-                            for (const decl of declarations) {
-                                if (decl.isKind(SyntaxKind.ClassDeclaration)) {
-                                    const classDecl = decl.asKindOrThrow(SyntaxKind.ClassDeclaration);
-                                    const extendsClause = classDecl.getExtends();
-                                    if (extendsClause != null) {
-                                        const baseClassName = extendsClause
-                                            .getExpression()
-                                            .getText();
-                                        if (baseClassName === 'PastoriaRootContext') {
-                                            extendsPastoriaRootContext = true;
-                                            break;
-                                        }
-                                    }
-                                }
-                            }
-                            if (extendsPastoriaRootContext) {
-                                if (gqlContext != null) {
-                                    logWarn('Multiple classes with @gqlContext extending PastoriaRootContext found. Using the first one.');
-                                }
-                                else {
-                                    gqlContext = {
-                                        sourceFile,
-                                        symbol,
-                                    };
-                                }
-                            }
-                            break;
-                        }
-                    }
-                }
-            }
-            symbol
-                .getDeclarations()
-                .flatMap((decl) => ts.getJSDocCommentsAndTags(decl.compilerNode))
-                .forEach(visitJSDocTags);
-            if (routerRoute != null) {
-                const [routeName, routeSymbol] = routerRoute;
-                routes.set(routeName, routeSymbol);
-                const { entryPoints, queries } = getResourceQueriesAndEntryPoints(routeSymbol.symbol);
-                if (routerResource == null && (entryPoints.size || queries.size)) {
-                    resources.set(`route(${routeName})`, {
-                        ...routeSymbol,
-                        entryPoints,
-                        queries,
-                    });
-                }
-            }
-            if (routerResource != null) {
-                const [resourceName, resourceSymbol] = routerResource;
-                const { entryPoints, queries } = getResourceQueriesAndEntryPoints(resourceSymbol.symbol);
-                resourceSymbol.queries = queries;
-                resourceSymbol.entryPoints = entryPoints;
-                resources.set(resourceName, resourceSymbol);
-            }
-        });
-    }
-    project.getSourceFiles().forEach(visitRouterNodes);
-    return { resources, routes, appRoot, gqlContext, serverHandlers };
-}
-function getResourceQueriesAndEntryPoints(symbol) {
-    const resource = {
-        queries: new Map(),
-        entryPoints: new Map(),
-    };
-    const decl = symbol.getValueDeclaration();
-    if (!decl)
-        return resource;
-    const t = decl.getType();
-    const aliasSymbol = t.getAliasSymbol();
-    if (aliasSymbol?.getName() === 'EntryPointComponent') {
-        const [queries, entryPoints] = t.getAliasTypeArguments();
-        queries?.getProperties().forEach((prop) => {
-            const queryRef = prop.getName();
-            const queryName = prop
-                .getValueDeclaration()
-                ?.getType()
-                .getAliasSymbol()
-                ?.getName();
-            if (queryName) {
-                resource.queries.set(queryRef, queryName);
-            }
-        });
-        entryPoints?.getProperties().forEach((prop) => {
-            const epRef = prop.getName();
-            const entryPointTypeRef = prop
-                .getValueDeclaration()
-                ?.asKind(SyntaxKind.PropertySignature)
-                ?.getTypeNode()
-                ?.asKind(SyntaxKind.TypeReference);
-            const entryPointTypeName = entryPointTypeRef?.getTypeName().getText();
-            if (entryPointTypeName !== 'EntryPoint') {
-                // TODO: Warn about found types not named EntryPoint
-                return;
-            }
-            const entryPointInner = entryPointTypeRef?.getTypeArguments().at(0);
-            const moduleTypeRef = entryPointInner?.asKind(SyntaxKind.TypeReference);
-            if (moduleTypeRef != null) {
-                const resourceName = moduleTypeRef
-                    ?.getTypeArguments()
-                    .at(0)
-                    ?.asKind(SyntaxKind.LiteralType)
-                    ?.getLiteral()
-                    .asKind(SyntaxKind.StringLiteral)
-                    ?.getLiteralText();
-                if (resourceName) {
-                    resource.entryPoints.set(epRef, resourceName);
-                }
-            }
-        });
-    }
-    return resource;
-}
+// ============================================================================
+// Zod Schema Generation
+// ============================================================================
+/**
+ * Generates a Zod schema string for a TypeScript type.
+ *
+ * Used to create runtime validation schemas for route parameters.
+ */
 function zodSchemaOfType(sf, tc, t) {
+    // Handle type aliases (custom types)
     if (t.aliasSymbol) {
         const decl = t.aliasSymbol.declarations?.at(0);
         if (decl == null) {
@@ -273,16 +113,18 @@ function zodSchemaOfType(sf, tc, t) {
             return `z.transform((s: string) => s as import('${importPath}').${t.aliasSymbol.getName()})`;
         }
     }
-    else if (t.getFlags() & TypeFlags.String) {
+    // Handle primitive types
+    if (t.getFlags() & TypeFlags.String) {
         return `z.pipe(z.string(), z.transform(decodeURIComponent))`;
     }
-    else if (t.getFlags() & TypeFlags.Number) {
+    if (t.getFlags() & TypeFlags.Number) {
         return `z.coerce.number<number>()`;
     }
-    else if (t.getFlags() & TypeFlags.Null) {
+    if (t.getFlags() & TypeFlags.Null) {
         return `z.preprocess(s => s == null ? undefined : s, z.undefined())`;
     }
-    else if (t.isUnion()) {
+    // Handle union types
+    if (t.isUnion()) {
         const nullishTypes = [];
         const nonNullishTypes = [];
         for (const s of t.types) {
@@ -302,282 +144,748 @@ function zodSchemaOfType(sf, tc, t) {
             return `z.union([${t.types.map((it) => zodSchemaOfType(sf, tc, it)).join(', ')}])`;
         }
     }
-    else if (tc.isArrayLikeType(t)) {
+    // Handle array types
+    if (tc.isArrayLikeType(t)) {
         const typeArg = tc.getTypeArguments(t)[0];
         const argZodSchema = typeArg == null ? `z.any()` : zodSchemaOfType(sf, tc, typeArg);
         return `z.array(${argZodSchema})`;
     }
-    else {
-        logWarn('Could not handle type:', tc.typeToString(t));
-        return `z.any()`;
+    // Fallback
+    logWarn('Could not handle type:', tc.typeToString(t));
+    return `z.any()`;
+}
+// ============================================================================
+// Entry Point Generation
+// ============================================================================
+/**
+ * Collects all query names from a page and its nested entry points.
+ */
+function collectAllQueries(page) {
+    const queries = new Set();
+    // Add main page queries
+    for (const queryName of page.queries.values()) {
+        queries.add(queryName);
+    }
+    // Add nested entry point queries
+    for (const nestedPage of page.nestedEntryPoints.values()) {
+        for (const queryName of nestedPage.queries.values()) {
+            queries.add(queryName);
+        }
     }
+    return queries;
 }
-function writeEntryPoint(writer, project, metadata, consumedQueries, resourceName, resource, parseVars = true) {
-    writer.writeLine(`root: JSResource.fromModuleId('${resourceName}'),`);
-    writer
-        .write(`getPreloadProps(${parseVars ? '{params, schema}' : ''})`)
-        .block(() => {
-        if (parseVars) {
-            writer.writeLine('const variables = schema.parse(params);');
+/**
+ * Writes an entry point definition for a filesystem-based page.
+ *
+ * Generates a getPreloadProps function that:
+ * 1. Sets up query preloading with the provided variables
+ * 2. Includes any nested entry points
+ *
+ * Note: Params are already parsed and typed by ROUTER_CONF schema via
+ * EntryPointParams<R>, so no additional parsing is needed here.
+ */
+function writeFilesystemEntryPoint(writer, project, page, resourceName, routePath, schemaExpression) {
+    const hasNestedEntryPoints = page.nestedEntryPoints.size > 0;
+    // Define schema locally so it can be referenced by wrappedGetPreloadProps
+    writer.writeLine(`const schema = ${schemaExpression};`);
+    // Generate query helper functions
+    writer.write('const queryHelpers = ').block(() => {
+        for (const [queryRef, queryName] of page.queries.entries()) {
+            writer.writeLine(`${queryRef}: (variables: ${queryName}$variables) => ({ parameters: ${queryName}Parameters, variables }),`);
         }
-        writer.write('return').block(() => {
+    });
+    writer.writeLine(';');
+    // Generate entry point helper functions
+    writer.write('const entryPointHelpers = ').block(() => {
+        for (const [epName, nestedPage] of page.nestedEntryPoints.entries()) {
+            const nestedResourceName = `${resourceName}#${epName}`;
+            // Build the combined variables type from all queries in this nested entry point
+            const nestedQueryNames = Array.from(nestedPage.queries.values());
+            const variablesType = nestedQueryNames.length === 0
+                ? 'Record<string, never>'
+                : nestedQueryNames.map((q) => `${q}$variables`).join(' & ');
             writer
-                .write('queries:')
+                .write(`${epName}: (variables: ${variablesType}) => (`)
                 .block(() => {
-                for (const [queryRef, query] of resource.queries.entries()) {
-                    consumedQueries.add(query);
-                    // Determine which variables this specific query needs
-                    const queryVars = collectQueryParameters(project, [query]);
-                    const hasVariables = queryVars.size > 0;
-                    writer
-                        .write(`${queryRef}:`)
-                        .block(() => {
-                        writer.writeLine(`parameters: ${query}Parameters,`);
-                        if (hasVariables) {
-                            const varNames = Array.from(queryVars.keys());
-                            // Always pick from the variables object
-                            writer.write(`variables: {`);
-                            writer.write(varNames.map((v) => `${v}: variables.${v}`).join(', '));
-                            writer.write(`}`);
-                        }
-                        else {
-                            // Query has no variables, pass empty object
-                            writer.write(`variables: {}`);
-                        }
-                        writer.newLine();
-                    })
-                        .write(',');
-                }
-            })
-                .writeLine(',');
-            writer.write('entryPoints:').block(() => {
-                for (const [epRef, subresourceName,] of resource.entryPoints.entries()) {
-                    const subresource = metadata.resources.get(subresourceName);
-                    if (subresource) {
-                        writer
-                            .write(`${epRef}:`)
-                            .block(() => {
-                            writer.writeLine(`entryPointParams: {},`);
-                            writer.write('entryPoint:').block(() => {
-                                writeEntryPoint(writer, project, metadata, consumedQueries, subresourceName, subresource, false);
+                writer.writeLine('entryPointParams: {},');
+                writer.write('entryPoint: ').block(() => {
+                    writer.writeLine(`root: JSResource.fromModuleId('${nestedResourceName}'),`);
+                    writer.write('getPreloadProps() ').block(() => {
+                        writer.write('return ').block(() => {
+                            writer.write('queries: ').block(() => {
+                                for (const [nestedQueryRef, nestedQueryName,] of nestedPage.queries.entries()) {
+                                    writer.writeLine(`${nestedQueryRef}: { parameters: ${nestedQueryName}Parameters, variables },`);
+                                }
                             });
-                        })
-                            .writeLine(',');
+                            writer.writeLine(',');
+                            writer.writeLine('entryPoints: undefined');
+                        });
+                    });
+                });
+            });
+            writer.writeLine('),');
+        }
+    });
+    writer.writeLine(';');
+    // Write getPreloadProps using the helpers
+    writer
+        .write(`function getPreloadProps({params, queries, entryPoints}: EntryPointParams<'${routePath}'>)`)
+        .block(() => {
+        // Params are already parsed and typed via EntryPointParams<R>
+        writer.writeLine('const variables = params;');
+        writer.write('return ').block(() => {
+            // Write queries using helpers
+            writer.write('queries: ').block(() => {
+                for (const [queryRef, _queryName] of page.queries.entries()) {
+                    const queryVars = collectQueryParameters(project, [
+                        page.queries.get(queryRef),
+                    ]);
+                    if (queryVars.size > 0) {
+                        const varNames = Array.from(queryVars.keys());
+                        writer.writeLine(`${queryRef}: queries.${queryRef}({${varNames.map((v) => `${v}: variables.${v}`).join(', ')}}),`);
+                    }
+                    else {
+                        writer.writeLine(`${queryRef}: queries.${queryRef}({}),`);
                     }
                 }
             });
+            writer.writeLine(',');
+            // Write entry points using helpers
+            if (hasNestedEntryPoints) {
+                writer.write('entryPoints: ').block(() => {
+                    for (const [epName, nestedPage,] of page.nestedEntryPoints.entries()) {
+                        // Collect all variables needed by this nested entry point
+                        const nestedVars = collectQueryParameters(project, Array.from(nestedPage.queries.values()));
+                        if (nestedVars.size > 0) {
+                            const varNames = Array.from(nestedVars.keys());
+                            writer.writeLine(`${epName}: entryPoints.${epName}({${varNames.map((v) => `${v}: variables.${v}`).join(', ')}}),`);
+                        }
+                        else {
+                            writer.writeLine(`${epName}: entryPoints.${epName}({}),`);
+                        }
+                    }
+                });
+            }
+            else {
+                writer.writeLine('entryPoints: undefined');
+            }
         });
     });
 }
-async function generateRouter(project, metadata) {
-    const routerTemplate = await loadRouterTemplates(project, 'router.tsx');
-    const tc = project.getTypeChecker().compilerObject;
-    let didAddJsResourceImport = false;
+// ============================================================================
+// Router Generation
+// ============================================================================
+/**
+ * Generates the router.tsx file with all route configurations.
+ *
+ * For each page discovered in the filesystem:
+ * 1. Generates an entry point function with getPreloadProps
+ * 2. Creates a route configuration entry with Zod schema
+ */
+async function generateRouter(project, fsMetadata) {
+    const routerTemplate = await loadRouterTemplate(project, 'router.tsx');
+    // Get the ROUTER_CONF object to add routes to
     const routerConf = routerTemplate
         .getVariableDeclarationOrThrow('ROUTER_CONF')
         .getInitializerIfKindOrThrow(SyntaxKind.AsExpression)
         .getExpressionIfKindOrThrow(SyntaxKind.ObjectLiteralExpression);
-    routerConf.getPropertyOrThrow('noop').remove();
-    let entryPointImportIndex = 0;
-    for (let [routeName, { sourceFile, symbol, params },] of metadata.routes.entries()) {
-        const filePath = path.relative(process.cwd(), sourceFile.getFilePath());
-        let entryPointExpression;
-        // Resource-routes are combined declarations of a resource and a route
-        // where we should generate the entrypoint for the route.
-        const isResourceRoute = Array.from(metadata.resources.entries()).find(([, { symbol: resourceSymbol }]) => symbol === resourceSymbol);
-        if (isResourceRoute) {
-            const [resourceName, resource] = isResourceRoute;
-            const entryPointFunctionName = `entrypoint_${resourceName.replace(/\W/g, '')}`;
-            if (!didAddJsResourceImport) {
-                didAddJsResourceImport = true;
+    // Only remove the noop placeholder if there are actual routes
+    // (keeping it prevents type errors when the config is empty)
+    const hasRoutes = fsMetadata.pages.size > 0 || fsMetadata.entryPoints.size > 0;
+    if (hasRoutes) {
+        routerConf.getPropertyOrThrow('noop').remove();
+    }
+    // Add JSResource import
+    routerTemplate.addImportDeclaration({
+        moduleSpecifier: './js_resource',
+        namedImports: ['JSResource', 'ModuleType'],
+    });
+    // Add helper types import from types.ts
+    routerTemplate.addImportDeclaration({
+        moduleSpecifier: './types',
+        namedImports: ['QueryHelpersForRoute', 'EntryPointHelpersForRoute'],
+        isTypeOnly: true,
+    });
+    const tc = project.getTypeChecker().compilerObject;
+    // Process each page
+    for (const [routePath, page] of fsMetadata.pages.entries()) {
+        // Create a unique resource name for this page
+        const resourceName = `fs:page(${routePath})`;
+        const safeResourceName = resourceName.replace(/[^a-zA-Z0-9]/g, '_');
+        // Check if this page has a custom entrypoint.ts
+        const hasCustomEntryPoint = page.customEntryPointPath != null;
+        // Import custom entrypoint exports if present
+        let customEntryPointAlias = null;
+        if (hasCustomEntryPoint) {
+            customEntryPointAlias = `customEp_${safeResourceName}`;
+            routerTemplate.addImportDeclaration({
+                moduleSpecifier: routerTemplate.getRelativePathAsModuleSpecifierTo(path.join(process.cwd(), page.customEntryPointPath)),
+                defaultImport: customEntryPointAlias,
+                namedImports: [
+                    { name: 'schema', alias: `${customEntryPointAlias}_schema` },
+                ],
+            });
+        }
+        // Collect all queries consumed by this page and its nested entry points
+        const consumedQueries = collectAllQueries(page);
+        // Add imports for query parameters and variable types (only needed for generated entry points)
+        if (!hasCustomEntryPoint) {
+            for (const queryName of consumedQueries) {
+                routerTemplate.addImportDeclaration({
+                    moduleSpecifier: `#genfiles/queries/${queryName}$parameters`,
+                    defaultImport: `${queryName}Parameters`,
+                });
+                // Add type-only import for variables (doesn't import runtime code)
+                routerTemplate.addImportDeclaration({
+                    moduleSpecifier: `#genfiles/queries/${queryName}.graphql`,
+                    namedImports: [`${queryName}$variables`],
+                    isTypeOnly: true,
+                });
+            }
+        }
+        // Build params schema from route params + query variables
+        // Track both the type and whether it's optional
+        const params = new Map();
+        // Add filesystem params as string types (using routeParams for optional info)
+        for (const routeParam of page.routeParams) {
+            params.set(routeParam.name, {
+                type: tc.getStringType(),
+                optional: routeParam.optional,
+            });
+        }
+        // Also include query variables (only needed for generated entry points)
+        if (!hasCustomEntryPoint && consumedQueries.size > 0) {
+            const queryParams = collectQueryParameters(project, Array.from(consumedQueries));
+            // Merge query params with route params (route params take precedence)
+            for (const [paramName, paramType] of queryParams) {
+                if (!params.has(paramName)) {
+                    params.set(paramName, { type: paramType, optional: false });
+                }
+            }
+        }
+        // Build schema expression string for the entry point to capture
+        let schemaExpression;
+        if (hasCustomEntryPoint) {
+            // Use the imported schema from the custom entrypoint
+            schemaExpression = `${customEntryPointAlias}_schema`;
+        }
+        else if (params.size === 0) {
+            schemaExpression = 'z.object({})';
+        }
+        else {
+            const schemaFields = Array.from(params.entries())
+                .map(([paramName, { type: paramType, optional: isOptional }]) => {
+                const baseSchema = zodSchemaOfType(routerTemplate, tc, paramType);
+                // Wrap optional params with z.optional()
+                const schema = isOptional ? `z.optional(${baseSchema})` : baseSchema;
+                return `${paramName}: ${schema}`;
+            })
+                .join(', ');
+            schemaExpression = `z.object({ ${schemaFields} })`;
+        }
+        // Generate the entry point function
+        if (hasCustomEntryPoint) {
+            // Custom entrypoint: use imported getPreloadProps but still wrap with helpers
+            // First, add query parameter imports needed for the helpers
+            for (const queryName of consumedQueries) {
                 routerTemplate.addImportDeclaration({
-                    moduleSpecifier: './js_resource',
-                    namedImports: ['JSResource', 'ModuleType'],
+                    moduleSpecifier: `#genfiles/queries/${queryName}$parameters`,
+                    defaultImport: `${queryName}Parameters`,
+                });
+                routerTemplate.addImportDeclaration({
+                    moduleSpecifier: `#genfiles/queries/${queryName}.graphql`,
+                    namedImports: [`${queryName}$variables`],
+                    isTypeOnly: true,
                 });
             }
-            const consumedQueries = new Set();
             routerTemplate.addFunction({
-                name: entryPointFunctionName,
-                returnType: `EntryPoint<ModuleType<'${resourceName}'>, EntryPointParams<'${routeName}'>>`,
+                name: `entrypoint_${safeResourceName}`,
                 statements: (writer) => {
+                    // Generate query helpers
+                    writer.write('const queryHelpers = ').block(() => {
+                        for (const [queryRef, queryName] of page.queries.entries()) {
+                            writer.writeLine(`${queryRef}: (variables: ${queryName}$variables) => ({ parameters: ${queryName}Parameters, variables }),`);
+                        }
+                    });
+                    writer.writeLine(';');
+                    // Generate entry point helpers
+                    writer.write('const entryPointHelpers = ').block(() => {
+                        for (const [epName, nestedPage,] of page.nestedEntryPoints.entries()) {
+                            const nestedResourceName = `${resourceName}#${epName}`;
+                            const nestedQueryNames = Array.from(nestedPage.queries.values());
+                            const variablesType = nestedQueryNames.length === 0
+                                ? 'Record<string, never>'
+                                : nestedQueryNames.map((q) => `${q}$variables`).join(' & ');
+                            writer
+                                .write(`${epName}: (variables: ${variablesType}) => (`)
+                                .block(() => {
+                                writer.writeLine('entryPointParams: {},');
+                                writer.write('entryPoint: ').block(() => {
+                                    writer.writeLine(`root: JSResource.fromModuleId('${nestedResourceName}'),`);
+                                    writer.write('getPreloadProps() ').block(() => {
+                                        writer.write('return ').block(() => {
+                                            writer.write('queries: ').block(() => {
+                                                for (const [nestedQueryRef, nestedQueryName,] of nestedPage.queries.entries()) {
+                                                    writer.writeLine(`${nestedQueryRef}: { parameters: ${nestedQueryName}Parameters, variables },`);
+                                                }
+                                            });
+                                            writer.writeLine(',');
+                                            writer.writeLine('entryPoints: undefined');
+                                        });
+                                    });
+                                });
+                            });
+                            writer.writeLine('),');
+                        }
+                    });
+                    writer.writeLine(';');
                     writer.write('return ').block(() => {
-                        writeEntryPoint(writer, project, metadata, consumedQueries, resourceName, resource);
+                        writer.writeLine(`root: JSResource.fromModuleId('${resourceName}'),`);
+                        writer.writeLine(`getPreloadProps: (p: {params: z.infer<typeof ${customEntryPointAlias}_schema>}) => ${customEntryPointAlias}({`);
+                        writer.writeLine('  params: p.params,');
+                        writer.writeLine('  queries: queryHelpers,');
+                        writer.writeLine('  entryPoints: entryPointHelpers,');
+                        writer.writeLine('}),');
                     });
                 },
             });
-            if (params.size === 0 && consumedQueries.size > 0) {
-                params = collectQueryParameters(project, Array.from(consumedQueries));
-            }
-            for (const query of consumedQueries) {
-                routerTemplate.addImportDeclaration({
-                    moduleSpecifier: `#genfiles/queries/${query}$parameters`,
-                    defaultImport: `${query}Parameters`,
-                });
-            }
-            entryPointExpression = entryPointFunctionName + '()';
         }
         else {
-            const importAlias = `e${entryPointImportIndex++}`;
-            const moduleSpecifier = routerTemplate.getRelativePathAsModuleSpecifierTo(sourceFile.getFilePath());
-            routerTemplate.addImportDeclaration({
-                moduleSpecifier,
-                namedImports: [
-                    {
-                        name: symbol.getName(),
-                        alias: importAlias,
-                    },
-                ],
+            // Generated entrypoint: create getPreloadProps from page queries
+            routerTemplate.addFunction({
+                name: `entrypoint_${safeResourceName}`,
+                statements: (writer) => {
+                    writeFilesystemEntryPoint(writer, project, page, resourceName, routePath, schemaExpression);
+                    writer.write('return ').block(() => {
+                        writer.writeLine(`root: JSResource.fromModuleId('${resourceName}'),`);
+                        writer.writeLine('getPreloadProps: (p: {params: Record<string, unknown>}) => getPreloadProps({');
+                        writer.writeLine('  params: p.params as z.infer<typeof schema>,');
+                        writer.writeLine('  queries: queryHelpers,');
+                        writer.writeLine('  entryPoints: entryPointHelpers,');
+                        writer.writeLine('}),');
+                    });
+                },
             });
-            entryPointExpression = importAlias;
         }
+        // Add route configuration (uses bracket format, converted to colon for radix3 at runtime)
         routerConf.addPropertyAssignment({
-            name: `"${routeName}"`,
+            name: `"${routePath}"`,
             initializer: (writer) => {
-                writer
-                    .write('{')
-                    .indent(() => {
-                    writer.writeLine(`entrypoint: ${entryPointExpression},`);
-                    if (params.size === 0) {
-                        writer.writeLine(`schema: z.object({})`);
-                    }
-                    else {
-                        writer.writeLine(`schema: z.object({`);
-                        for (const [paramName, paramType] of Array.from(params)) {
-                            writer.writeLine(`  ${paramName}: ${zodSchemaOfType(routerTemplate, tc, paramType)},`);
-                        }
-                        writer.writeLine('})');
-                    }
-                })
-                    .write('} as const');
+                writer.write('{').indent(() => {
+                    writer.writeLine(`entrypoint: entrypoint_${safeResourceName}(),`);
+                    writer.writeLine(`schema: ${schemaExpression}`);
+                });
+                writer.write('} as const');
             },
         });
-        logInfo('Created route', pc.cyan(routeName), 'for', pc.green(symbol.getName()), 'exported from', pc.yellow(filePath));
+        logInfo('Created route', pc.cyan(routePath), 'from', pc.yellow(page.filePath), hasCustomEntryPoint ? '(custom entrypoint)' : '');
     }
     await routerTemplate.save();
 }
-async function generateJsResource(project, metadata) {
-    const jsResourceTemplate = await loadRouterTemplates(project, 'js_resource.ts');
+// ============================================================================
+// JS Resource Generation
+// ============================================================================
+/**
+ * Generates the js_resource.ts file for lazy loading.
+ *
+ * Each page.tsx and *.page.tsx file becomes a lazy-loadable resource.
+ */
+async function generateJsResource(project, fsMetadata) {
+    const jsResourceTemplate = await loadRouterTemplate(project, 'js_resource.ts');
     const resourceConf = jsResourceTemplate
         .getVariableDeclarationOrThrow('RESOURCE_CONF')
         .getInitializerIfKindOrThrow(SyntaxKind.AsExpression)
         .getExpressionIfKindOrThrow(SyntaxKind.ObjectLiteralExpression);
-    resourceConf.getPropertyOrThrow('noop').remove();
-    for (const [resourceName, { sourceFile, symbol },] of metadata.resources.entries()) {
-        const filePath = path.relative(process.cwd(), sourceFile.getFilePath());
-        const moduleSpecifier = jsResourceTemplate.getRelativePathAsModuleSpecifierTo(sourceFile.getFilePath());
+    // Only remove the noop placeholder if there are actual pages
+    const hasPages = fsMetadata.pages.size > 0;
+    if (hasPages) {
+        resourceConf.getPropertyOrThrow('noop').remove();
+    }
+    // Process main pages
+    for (const [routePath, page] of fsMetadata.pages.entries()) {
+        const resourceName = `fs:page(${routePath})`;
+        const moduleSpecifier = jsResourceTemplate.getRelativePathAsModuleSpecifierTo(path.join(process.cwd(), page.filePath));
         resourceConf.addPropertyAssignment({
             name: `"${resourceName}"`,
             initializer: (writer) => {
                 writer.block(() => {
-                    writer
-                        .writeLine(`src: "${filePath}",`)
-                        .writeLine(`loader: () => import("${moduleSpecifier}").then(m => m.${symbol.getName()})`);
+                    writer.writeLine(`src: "${page.filePath}",`);
+                    writer.writeLine(`loader: (): Promise<ComponentType<PageProps<'${routePath}'>>> => import("${moduleSpecifier}").then(m => m.default)`);
                 });
             },
         });
-        logInfo('Created resource', pc.cyan(resourceName), 'for', pc.green(symbol.getName()), 'exported from', pc.yellow(filePath));
+        logInfo('Created resource', pc.cyan(resourceName), 'from', pc.yellow(page.filePath));
+        // Process nested entry points for this page
+        for (const [epName, nestedPage] of page.nestedEntryPoints.entries()) {
+            const nestedResourceName = `${resourceName}#${epName}`;
+            const nestedModuleSpecifier = jsResourceTemplate.getRelativePathAsModuleSpecifierTo(path.join(process.cwd(), nestedPage.filePath));
+            // Nested entry points use flattened keys like '/#search_results'
+            const nestedRouteKey = `${routePath}#${epName}`;
+            resourceConf.addPropertyAssignment({
+                name: `"${nestedResourceName}"`,
+                initializer: (writer) => {
+                    writer.block(() => {
+                        writer.writeLine(`src: "${nestedPage.filePath}",`);
+                        writer.writeLine(`loader: (): Promise<ComponentType<PageProps<'${nestedRouteKey}'>>> => import("${nestedModuleSpecifier}").then(m => m.default)`);
+                    });
+                },
+            });
+            logInfo('Created nested resource', pc.cyan(nestedResourceName), 'from', pc.yellow(nestedPage.filePath));
+        }
     }
     await jsResourceTemplate.save();
 }
-async function generateAppRoot(project, metadata) {
-    const targetDir = process.cwd();
-    const appRoot = metadata.appRoot;
-    if (appRoot == null) {
+// ============================================================================
+// Server Handler Generation
+// ============================================================================
+/**
+ * Generates server_handler.ts with API route handlers.
+ *
+ * Each route.ts file in the filesystem exports an express.Router
+ * that handles requests at that path.
+ */
+async function generateServerHandler(project, fsMetadata) {
+    if (fsMetadata.apiRoutes.size === 0) {
+        // No API routes found, delete the file if it exists
         await project
-            .getSourceFile('__generated__/router/app_root.ts')
+            .getSourceFile('__generated__/router/server_handler.ts')
             ?.deleteImmediately();
         return;
     }
-    const appRootSourceFile = appRoot.sourceFile;
-    const appRootSymbol = appRoot.symbol;
-    const filePath = path.relative(targetDir, appRootSourceFile.getFilePath());
-    const appRootFile = project.createSourceFile('__generated__/router/app_root.ts', '', { overwrite: true });
-    const moduleSpecifier = appRootFile.getRelativePathAsModuleSpecifierTo(appRootSourceFile.getFilePath());
-    appRootFile.addStatements(`/*
+    const serverHandlerFile = project.createSourceFile('__generated__/router/server_handler.ts', `/*
  * This file was generated by \`pastoria\`.
  * Do not modify this file directly.
  */
 
-export {${appRootSymbol.getName()} as App} from '${moduleSpecifier}';
-`);
-    await appRootFile.save();
-    logInfo('Created app root for', pc.green(appRootSymbol.getName()), 'exported from', pc.yellow(filePath));
+import express from 'express';
+export const router = express.Router();
+`, { overwrite: true });
+    let importIndex = 0;
+    for (const [routePath, apiRoute] of fsMetadata.apiRoutes.entries()) {
+        // Convert [param] to :param for Express router
+        const routerPath = toRouterPath(routePath);
+        const importAlias = `route${importIndex++}`;
+        const moduleSpecifier = serverHandlerFile.getRelativePathAsModuleSpecifierTo(path.join(process.cwd(), apiRoute.filePath));
+        serverHandlerFile.addImportDeclaration({
+            moduleSpecifier,
+            defaultImport: importAlias,
+        });
+        serverHandlerFile.addStatements(`router.use('${routerPath}', ${importAlias});`);
+        logInfo('Created API route', pc.cyan(routePath), 'from', pc.yellow(apiRoute.filePath));
+    }
+    await serverHandlerFile.save();
 }
-async function generateGraphqlContext(project, metadata) {
-    const targetDir = process.cwd();
-    const gqlContext = metadata.gqlContext;
-    const contextFile = project.createSourceFile('__generated__/router/context.ts', '', { overwrite: true });
-    if (gqlContext != null) {
-        const contextSourceFile = gqlContext.sourceFile;
-        const contextSymbol = gqlContext.symbol;
-        const filePath = path.relative(targetDir, contextSourceFile.getFilePath());
-        const moduleSpecifier = contextFile.getRelativePathAsModuleSpecifierTo(contextSourceFile.getFilePath());
-        contextFile.addStatements(`/*
- * This file was generated by \`pastoria\`.
- * Do not modify this file directly.
+// ============================================================================
+// Type Generation
+// ============================================================================
+/**
+ * Generates types.ts with PageProps type definitions.
+ *
+ * Creates types like PageProps<'/posts'> that include:
+ * - queries: Preloaded query references
+ * - entryPoints: Nested entry point references
  */
-
-export {${contextSymbol.getName()} as Context} from '${moduleSpecifier}';
-`);
-        logInfo('Created GraphQL context for', pc.green(contextSymbol.getName()), 'exported from', pc.yellow(filePath));
+async function generateTypes(project, fsMetadata) {
+    const typesFile = project.createSourceFile('__generated__/router/types.ts', '', { overwrite: true });
+    // Collect all query types to import (both the query type and $variables type)
+    const queryImports = new Set();
+    const variablesImports = new Set();
+    // Helper to build queries type string
+    function buildQueriesType(queries) {
+        if (queries.size === 0)
+            return '{}';
+        return `{ ${Array.from(queries.entries())
+            .map(([ref, queryTypeName]) => {
+            queryImports.add(queryTypeName);
+            return `${ref}: ${queryTypeName}`;
+        })
+            .join('; ')} }`;
+    }
+    // Helper to build query helper type for a route
+    function buildQueryHelpersType(queries) {
+        if (queries.size === 0)
+            return '{}';
+        return `{ ${Array.from(queries.entries())
+            .map(([ref, queryTypeName]) => {
+            variablesImports.add(queryTypeName);
+            return `${ref}: (variables: ${queryTypeName}$variables) => { parameters: unknown; variables: ${queryTypeName}$variables }`;
+        })
+            .join('; ')} }`;
+    }
+    // Helper to build entry point helper type for a route
+    function buildEntryPointHelpersType(routePath, nestedEntryPoints) {
+        if (nestedEntryPoints.size === 0)
+            return '{}';
+        return `{ ${Array.from(nestedEntryPoints.entries())
+            .map(([epName, nestedPage]) => {
+            const nestedTypeName = routeToTypeName(routePath, epName);
+            // Build intersection of all query variable types for this nested entry point
+            const queryNames = Array.from(nestedPage.queries.values());
+            queryNames.forEach((q) => variablesImports.add(q));
+            const variablesType = queryNames.length === 0
+                ? 'Record<string, never>'
+                : queryNames.map((q) => `${q}$variables`).join(' & ');
+            // Optional entry points can return undefined
+            const baseReturnType = `{ entryPointParams: Record<string, never>; entryPoint: EntryPoint<EntryPointComponent<${nestedTypeName}['queries'], ${nestedTypeName}['entryPoints'], {}, {}>, {}> }`;
+            const returnType = nestedPage.optional
+                ? `${baseReturnType} | undefined`
+                : baseReturnType;
+            return `${epName}: (variables: ${variablesType}) => ${returnType}`;
+        })
+            .join('; ')} }`;
+    }
+    // Helper to convert route path to a valid TypeScript identifier
+    function routeToTypeName(routePath, nestedName) {
+        // Convert /hello/[name] to Hello$name, /hello/[[name]] to Hello$$name, / to Root
+        const pathPart = routePath === '/'
+            ? 'Root'
+            : routePath
+                .slice(1) // remove leading /
+                .split('/')
+                .map((segment) => {
+                // Check for optional param first: [[name]] -> $$name
+                if (segment.startsWith('[[') && segment.endsWith(']]')) {
+                    return '$$' + segment.slice(2, -2);
+                }
+                // Check for required param: [name] -> $name
+                if (segment.startsWith('[') && segment.endsWith(']')) {
+                    return '$' + segment.slice(1, -1);
+                }
+                // Static segment: hello -> Hello (capitalize first letter)
+                return segment.charAt(0).toUpperCase() + segment.slice(1);
+            })
+                .join('');
+        if (nestedName) {
+            // Nested entry point: append _nestedName
+            return `Route${pathPart}_${nestedName}`;
+        }
+        return `Route${pathPart}`;
+    }
+    // Phase 1: Generate type aliases for nested entry points (leaf nodes - no dependencies)
+    const nestedTypeAliases = [];
+    for (const [routePath, page] of fsMetadata.pages.entries()) {
+        for (const [epName, nestedPage] of page.nestedEntryPoints.entries()) {
+            const typeName = routeToTypeName(routePath, epName);
+            const queriesType = buildQueriesType(nestedPage.queries);
+            nestedTypeAliases.push(`type ${typeName} = { queries: ${queriesType}; entryPoints: {} };`);
+        }
     }
-    else {
-        contextFile.addStatements(`/*
+    // Phase 2: Generate type aliases for main pages (can reference nested types)
+    const mainTypeAliases = [];
+    for (const [routePath, page] of fsMetadata.pages.entries()) {
+        const typeName = routeToTypeName(routePath);
+        const queriesType = buildQueriesType(page.queries);
+        let entryPointsType = '{}';
+        if (page.nestedEntryPoints.size > 0) {
+            const epTypes = Array.from(page.nestedEntryPoints.entries())
+                .map(([epName, nestedPage]) => {
+                const nestedTypeName = routeToTypeName(routePath, epName);
+                const optionalMarker = nestedPage.optional ? '?' : '';
+                return `${epName}${optionalMarker}: EntryPoint<EntryPointComponent<${nestedTypeName}['queries'], ${nestedTypeName}['entryPoints'], {}, {}>, {}>`;
+            })
+                .join('; ');
+            entryPointsType = `{ ${epTypes} }`;
+        }
+        mainTypeAliases.push(`type ${typeName} = { queries: ${queriesType}; entryPoints: ${entryPointsType} };`);
+    }
+    // Phase 3: Build PageQueryMap entries referencing the type aliases
+    const routeTypes = [];
+    for (const [routePath, page] of fsMetadata.pages.entries()) {
+        const typeName = routeToTypeName(routePath);
+        routeTypes.push(`  '${routePath}': ${typeName}`);
+        for (const epName of page.nestedEntryPoints.keys()) {
+            const nestedTypeName = routeToTypeName(routePath, epName);
+            routeTypes.push(`  '${routePath}#${epName}': ${nestedTypeName}`);
+        }
+    }
+    // Phase 4: Generate helper type aliases for each route
+    const queryHelperAliases = [];
+    const entryPointHelperAliases = [];
+    const queryHelpersMapEntries = [];
+    const entryPointHelpersMapEntries = [];
+    for (const [routePath, page] of fsMetadata.pages.entries()) {
+        const typeName = routeToTypeName(routePath);
+        // Query helpers type
+        const queryHelpersType = buildQueryHelpersType(page.queries);
+        queryHelperAliases.push(`type QueryHelpers_${typeName} = ${queryHelpersType};`);
+        queryHelpersMapEntries.push(`  '${routePath}': QueryHelpers_${typeName}`);
+        // Entry point helpers type
+        const entryPointHelpersType = buildEntryPointHelpersType(routePath, page.nestedEntryPoints);
+        entryPointHelperAliases.push(`type EntryPointHelpers_${typeName} = ${entryPointHelpersType};`);
+        entryPointHelpersMapEntries.push(`  '${routePath}': EntryPointHelpers_${typeName}`);
+    }
+    // Generate import statements for query types
+    const queryImportStatements = Array.from(queryImports)
+        .map((queryTypeName) => `import type {${queryTypeName}} from '#genfiles/queries/${queryTypeName}.graphql';`)
+        .join('\n');
+    // Generate import statements for $variables types
+    const variablesImportStatements = Array.from(variablesImports)
+        .map((queryTypeName) => `import type {${queryTypeName}$variables} from '#genfiles/queries/${queryTypeName}.graphql';`)
+        .join('\n');
+    typesFile.addStatements(`/*
  * This file was generated by \`pastoria\`.
  * Do not modify this file directly.
+ *
+ * Type definitions for filesystem-based routing.
  */
 
-import {PastoriaRootContext} from 'pastoria-runtime/server';
+import type {EntryPoint, EntryPointComponent, EntryPointProps} from 'react-relay/hooks';
+${queryImportStatements ? '\n' + queryImportStatements : ''}
+${variablesImportStatements ? '\n' + variablesImportStatements : ''}
+
+// Route type aliases - nested entry points (leaf nodes)
+${nestedTypeAliases.join('\n')}
+
+// Route type aliases - main pages
+${mainTypeAliases.join('\n')}
 
 /**
- * @gqlContext
+ * Map of route paths to their query types.
+ * Nested entry points use the format: '/route#entryPointName'
  */
-export class Context extends PastoriaRootContext {}
-`);
-        logInfo('No @gqlContext found, generating default', pc.green('Context'));
-    }
-    await contextFile.save();
+export interface PageQueryMap {
+${routeTypes.join(';\n')}${routeTypes.length > 0 ? ';' : ''}
 }
-async function generateServerHandler(project, metadata) {
-    if (metadata.serverHandlers.size === 0) {
-        await project
-            .getSourceFile('__generated__/router/server_handler.ts')
-            ?.deleteImmediately();
-        return;
-    }
-    const sourceText = `import express from 'express';
-export const router = express.Router();
-`;
-    const serverHandlerTemplate = project.createSourceFile('__generated__/router/server_handler.ts', sourceText, { overwrite: true });
-    let serverHandlerImportIndex = 0;
-    for (const [routeName, { symbol, sourceFile },] of metadata.serverHandlers.entries()) {
-        const importAlias = `e${serverHandlerImportIndex++}`;
-        const filePath = path.relative(process.cwd(), sourceFile.getFilePath());
-        const moduleSpecifier = serverHandlerTemplate.getRelativePathAsModuleSpecifierTo(sourceFile.getFilePath());
-        serverHandlerTemplate.addImportDeclaration({
-            moduleSpecifier,
-            namedImports: [{ name: symbol.getName(), alias: importAlias }],
-        });
-        serverHandlerTemplate.addStatements(`router.use('${routeName}', ${importAlias})`);
-        logInfo('Created server handler', pc.cyan(routeName), 'for', pc.green(symbol.getName()), 'exported from', pc.yellow(filePath));
-    }
-    await serverHandlerTemplate.save();
+
+// Query helper type aliases for each route
+${queryHelperAliases.join('\n')}
+
+// Entry point helper type aliases for each route
+${entryPointHelperAliases.join('\n')}
+
+/**
+ * Query helper functions for a route.
+ * Each helper takes typed variables and returns {parameters, variables} for Relay.
+ */
+export interface QueryHelpersMap {
+${queryHelpersMapEntries.join(';\n')}${queryHelpersMapEntries.length > 0 ? ';' : ''}
+}
+
+export type QueryHelpersForRoute<R extends string> = R extends keyof QueryHelpersMap
+  ? QueryHelpersMap[R]
+  : {};
+
+/**
+ * Entry point helper functions for a route.
+ * Each helper takes typed variables and returns the nested entry point configuration.
+ */
+export interface EntryPointHelpersMap {
+${entryPointHelpersMapEntries.join(';\n')}${entryPointHelpersMapEntries.length > 0 ? ';' : ''}
+}
+
+export type EntryPointHelpersForRoute<R extends string> = R extends keyof EntryPointHelpersMap
+  ? EntryPointHelpersMap[R]
+  : {};
+
+/**
+ * Props type for a page component at the given route.
+ * Uses EntryPointProps to transform raw query types to PreloadedQuery<...>.
+ *
+ * @example
+ * \`\`\`typescript
+ * // Main page
+ * export default function BlogPosts({ queries }: PageProps<'/posts'>) {
+ *   const data = usePreloadedQuery(query, queries.posts);
+ * }
+ *
+ * // Nested entry point
+ * export default function Sidebar({ queries }: PageProps<'/posts#sidebar'>) {
+ *   const data = usePreloadedQuery(query, queries.sidebarData);
+ * }
+ * \`\`\`
+ */
+export type PageProps<R extends keyof PageQueryMap> = EntryPointProps<
+  PageQueryMap[R]['queries'],
+  PageQueryMap[R]['entryPoints'],
+  {},
+  {}
+>;
+
+/**
+ * Return type for getPreloadProps in entrypoint.ts files.
+ * This type matches the structure expected by Relay's loadEntryPoint.
+ *
+ * @example
+ * \`\`\`typescript
+ * export default function getPreloadProps({
+ *   params,
+ *   queries,
+ *   entryPoints,
+ * }: EntryPointParams<'/posts'>): PreloadPropsForRoute<'/posts'> {
+ *   return {
+ *     queries: {
+ *       postsQuery: queries.postsQuery(params),
+ *     },
+ *     entryPoints: {
+ *       sidebar: entryPoints.sidebar({}),
+ *     },
+ *   };
+ * }
+ * \`\`\`
+ */
+export type PreloadPropsForRoute<R extends keyof PageQueryMap> = {
+  queries: {
+    [K in keyof PageQueryMap[R]['queries']]: {
+      parameters: unknown;
+      variables: unknown;
+    };
+  };
+  entryPoints: PageQueryMap[R]['entryPoints'] extends Record<string, never>
+    ? undefined
+    : {
+        [K in keyof PageQueryMap[R]['entryPoints']]: {
+          entryPointParams: unknown;
+          entryPoint: unknown;
+        };
+      };
+};
+`);
+    await typesFile.save();
+    logInfo('Generated PageProps types for', pc.cyan(`${fsMetadata.pages.size} routes`));
 }
-export async function generatePastoriaExports(project) {
-    const metadata = collectPastoriaMetadata(project);
-    await generateAppRoot(project, metadata);
-    await generateGraphqlContext(project, metadata);
-    return metadata;
+// ============================================================================
+// Main Generation Functions
+// ============================================================================
+/**
+ * Generates all Pastoria artifacts from the filesystem.
+ *
+ * This is the main entry point for code generation.
+ */
+export async function generatePastoriaArtifacts(project) {
+    // Scan the pastoria/ directory for routing files
+    const fsMetadata = scanFilesystemRoutes(project);
+    // Generate all artifacts
+    await Promise.all([
+        generateRouter(project, fsMetadata),
+        generateJsResource(project, fsMetadata),
+        generateServerHandler(project, fsMetadata),
+        generateTypes(project, fsMetadata),
+    ]);
+    return fsMetadata;
 }
-export async function generatePastoriaArtifacts(project, metadata = collectPastoriaMetadata(project)) {
-    await generateRouter(project, metadata);
-    await generateJsResource(project, metadata);
-    await generateServerHandler(project, metadata);
+/**
+ * Detects what capabilities are available based on source files.
+ */
+export async function detectCapabilities() {
+    const fs = await import('node:fs/promises');
+    const hasAppRoot = await fs
+        .stat('pastoria/app.tsx')
+        .then(() => true)
+        .catch(() => false);
+    const hasServerHandler = await fs
+        .stat('__generated__/router/server_handler.ts')
+        .then(() => true)
+        .catch(() => false);
+    return { hasAppRoot, hasServerHandler };
 }
+// ============================================================================
+// Entry Point Generation (for Vite plugin)
+// ============================================================================
+/**
+ * Generates the client entry point code.
+ */
 export function generateClientEntry({ hasAppRoot, }) {
-    const appImport = hasAppRoot
-        ? `import {App} from '#genfiles/router/app_root';`
-        : '';
+    const appImport = hasAppRoot ? `import App from './pastoria/app';` : '';
     const appValue = hasAppRoot ? 'App' : 'null';
     return `// Generated by Pastoria.
 import {createRouterApp} from '#genfiles/router/router';
@@ -592,10 +900,11 @@ async function main() {
 main();
 `;
 }
+/**
+ * Generates the server entry point code.
+ */
 export function generateServerEntry({ hasAppRoot, hasServerHandler, }) {
-    const appImport = hasAppRoot
-        ? `import {App} from '#genfiles/router/app_root';`
-        : '';
+    const appImport = hasAppRoot ? `import App from './pastoria/app';` : '';
     const appValue = hasAppRoot ? 'App' : 'null';
     const serverHandlerImport = hasServerHandler
         ? `import {router as serverHandler} from '#genfiles/router/server_handler';`
@@ -610,25 +919,15 @@ import {
   router__createAppFromEntryPoint,
   router__loadEntryPoint,
 } from '#genfiles/router/router';
-import {getSchema} from '#genfiles/schema/schema';
-import {Context} from '#genfiles/router/context';
+import environment from './pastoria/environment';
 ${appImport}
 ${serverHandlerImport}
 import express from 'express';
-import {GraphQLSchema, specifiedDirectives} from 'graphql';
-import {PastoriaConfig} from 'pastoria-config';
 import {createRouterHandler} from 'pastoria-runtime/server';
 import type {Manifest} from 'vite';
 
-const schemaConfig = getSchema().toConfig();
-const schema = new GraphQLSchema({
-  ...schemaConfig,
-  directives: [...specifiedDirectives, ...schemaConfig.directives],
-});
-
 export function createHandler(
   persistedQueries: Record<string, string>,
-  config: Required<PastoriaConfig>,
   manifest?: Manifest,
 ) {
   const routeHandler = createRouterHandler(
@@ -637,10 +936,8 @@ export function createHandler(
     router__loadEntryPoint,
     router__createAppFromEntryPoint,
     ${appValue},
-    schema,
-    (req) => Context.createFromRequest(req),
+    environment,
     persistedQueries,
-    config,
     manifest,
   );