toiljs 0.0.11 → 0.0.12

package/src/compiler/generate.ts

@@ -1,373 +1,378 @@
-import fs from 'node:fs';
-import path from 'node:path';
-
-import { type ResolvedToilConfig } from './config.js';
-import { writeDocs } from './docs.js';
-import { scanRoutes, type ScannedRoute } from './routes.js';
-import { llmsTxt, robotsTxt, sitemapXml } from './seo.js';
-
-/**
- * Contents of the root `toil-env.d.ts`: ambient global types so `new BinaryWriter()` etc. resolve
- * in the IDE without an import. Script-mode declaration (no top-level import/export → the
- * `declare const`s are truly global, and it's not a module that could confuse ESLint's project
- * service); the inline `import('toiljs/io')` type only needs the normal `toiljs/io` export.
- * Lives at the project root because TypeScript's `include` globs skip dot-directories.
- * Exported so `toiljs create` can write it during scaffolding, before the first dev/build.
- */
-/** Side-effect style imports (e.g. `import './styles/main.css'`). */
-const STYLE_EXTENSIONS = ['css', 'scss', 'sass', 'less', 'styl', 'stylus', 'pcss', 'sss'];
-/** Asset imports whose default export is the resolved URL string (e.g. `import logo from './logo.svg'`). */
-const ASSET_EXTENSIONS = [
-    'svg',
-    'png',
-    'jpg',
-    'jpeg',
-    'gif',
-    'webp',
-    'avif',
-    'ico',
-    'bmp',
-    'apng',
-];
-
-const STYLE_MODULES = STYLE_EXTENSIONS.map((ext) => `declare module '*.${ext}' {}`).join('\n');
-const ASSET_MODULES = ASSET_EXTENSIONS.map(
-    (ext) => `declare module '*.${ext}' {\n    const src: string;\n    export default src;\n}`,
-).join('\n');
-
-export const TOIL_ENV_DTS =
-    `// AUTO-GENERATED by toil, do not edit.\n` +
-    // Types for image-optimization query imports (`import img from './x.png?w=400&format=webp'`).
-    `/// <reference types="vite-imagetools/client" />\n` +
-    `declare const Toil: typeof import('toiljs/client');\n` +
-    `declare namespace Toil {\n` +
-    `    type LoaderArgs = import('toiljs/client').LoaderArgs;\n` +
-    `    type LoaderFunction<T = unknown> = import('toiljs/client').LoaderFunction<T>;\n` +
-    `    type Revalidate = import('toiljs/client').Revalidate;\n` +
-    `    type Metadata = import('toiljs/client').Metadata;\n` +
-    `    type GenerateMetadata<T = unknown> = import('toiljs/client').GenerateMetadata<T>;\n` +
-    `    type RouteErrorProps = import('toiljs/client').RouteErrorProps;\n` +
-    `    type Href = import('toiljs/client').Href;\n` +
-    `    type RoutePath = import('toiljs/client').RoutePath;\n` +
-    `}\n` +
-    `declare const BinaryWriter: typeof import('toiljs/io').BinaryWriter;\n` +
-    `declare const BinaryReader: typeof import('toiljs/io').BinaryReader;\n` +
-    `declare const FastMap: typeof import('toiljs/io').FastMap;\n` +
-    `declare const FastSet: typeof import('toiljs/io').FastSet;\n` +
-    `\n` +
-    `${STYLE_MODULES}\n` +
-    `\n` +
-    `${ASSET_MODULES}\n` +
-    `\n` +
-    `declare module 'toiljs/routes' {\n` +
-    `    export const routes: import('toiljs/client').RouteDef[];\n` +
-    `    export const layout: import('toiljs/client').LayoutLoader;\n` +
-    `    export const notFound: import('toiljs/client').NotFoundLoader;\n` +
-    `    export const globalError: import('toiljs/client').ErrorComponentLoader;\n` +
-    `    export const slots: Record<string, import('toiljs/client').RouteDef[]>;\n` +
-    `}\n`;
-
-/**
- * Returns a `./`-prefixed, **extensionless** POSIX module specifier from `.toil` to `abs`, for use
- * in generated `import(...)` calls. Extensionless so TypeScript doesn't demand
- * `allowImportingTsExtensions` (TS5097) when the generated files are checked; Vite still resolves it.
- */
-function relFromToil(cfg: ResolvedToilConfig, abs: string): string {
-    let rel = path.relative(cfg.toilDir, abs).replace(/\\/g, '/').replace(/\.(tsx|jsx)$/, '');
-    if (!rel.startsWith('.')) rel = './' + rel;
-    return rel;
-}
-
-function findLayout(cfg: ResolvedToilConfig): string | undefined {
-    return ['layout.tsx', 'layout.jsx']
-        .map((name) => path.join(cfg.clientAbsDir, name))
-        .find((p) => fs.existsSync(p));
-}
-
-/** Finds an optional custom not-found page at `client/404.{tsx,jsx}`. */
-function findNotFound(cfg: ResolvedToilConfig): string | undefined {
-    return ['404.tsx', '404.jsx']
-        .map((name) => path.join(cfg.clientAbsDir, name))
-        .find((p) => fs.existsSync(p));
-}
-
-/** Finds an optional root error boundary at `client/global-error.{tsx,jsx}`. */
-function findGlobalError(cfg: ResolvedToilConfig): string | undefined {
-    return ['global-error.tsx', 'global-error.jsx']
-        .map((name) => path.join(cfg.clientAbsDir, name))
-        .find((p) => fs.existsSync(p));
-}
-
-/**
- * Builds the `RoutePath` union for typed `Link`/`navigate` hrefs: static routes as string literals,
- * dynamic/catch-all as `` `…/${string}` `` templates (optional catch-all also emits its bare prefix).
- */
-function routePathUnion(routes: ScannedRoute[]): string {
-    const members = new Set<string>();
-    for (const route of routes) {
-        const segments = route.pattern.split('/').filter(Boolean);
-        const isDynamic = segments.some((s) => s.startsWith(':') || s.startsWith('*'));
-        if (!isDynamic) {
-            members.add(`'${route.pattern}'`);
-            continue;
-        }
-        const parts = segments.map((s) => (s.startsWith(':') || s.startsWith('*') ? '${string}' : s));
-        members.add('`/' + parts.join('/') + '`');
-        const optionalIdx = segments.findIndex((s) => s.startsWith('**'));
-        if (optionalIdx !== -1) {
-            const prefix = '/' + segments.slice(0, optionalIdx).join('/');
-            members.add(`'${prefix}'`);
-        }
-    }
-    return members.size ? [...members].join(' | ') : 'string';
-}
-
-/**
- * The `toil-routes.d.ts` contents: a module augmentation registering the project's route paths so
- * `Link`/`navigate`/`useRouter` hrefs are type-checked. Regenerated each dev/build.
- */
-function routesDts(cfg: ResolvedToilConfig, routes: ScannedRoute[]): string {
-    // Type-only namespace import of every route module (erased at build) so editors don't flag a
-    // route's `loader` / `metadata` / `generateMetadata` / `revalidate` / `default` exports as unused
-    // — the compiler consumes them via dynamic `import()`, which editors don't count as a reference.
-    const refs = routes.map((route, i) => {
-        let rel = path.relative(cfg.root, route.file).replace(/\\/g, '/').replace(/\.(tsx|jsx)$/, '');
-        if (!rel.startsWith('.')) rel = `./${rel}`;
-        return { name: `_toilRoute${String(i)}`, rel };
-    });
-    const imports = refs.map((m) => `import type * as ${m.name} from ${JSON.stringify(m.rel)};\n`).join('');
-    const referenced = refs.length
-        ? `export type _ToilRouteModules = [${refs.map((m) => `typeof ${m.name}`).join(', ')}];\n`
-        : `export {};\n`;
-    return (
-        `// AUTO-GENERATED by toil, do not edit.\n` +
-        imports +
-        referenced +
-        `declare module 'toiljs/client' {\n` +
-        `    interface Register {\n` +
-        `        routePath: ${routePathUnion(routes)};\n` +
-        `    }\n` +
-        `}\n`
-    );
-}
-
-/** Finds the user-owned app entry at `client/toil.{tsx,jsx}` (where `mount` is called). */
-function findEntry(cfg: ResolvedToilConfig): string | undefined {
-    return ['toil.tsx', 'toil.jsx']
-        .map((name) => path.join(cfg.clientAbsDir, name))
-        .find((p) => fs.existsSync(p));
-}
-
-/** A `<base>.{tsx,jsx}` in `dir`, or undefined. */
-function specialIn(dir: string, base: string): string | undefined {
-    return [`${base}.tsx`, `${base}.jsx`]
-        .map((name) => path.join(dir, name))
-        .find((p) => fs.existsSync(p));
-}
-
-/**
- * Chain of `<base>.{tsx,jsx}` files wrapping a route, shallowest → deepest: the routes root and each
- * ancestor directory down to the file's own. With `includeClientRoot`, `client/<base>` is prepended
- * as the outermost (used by templates; the root `client/layout.tsx` is instead the top-level layout).
- */
-function findSpecialChain(
-    cfg: ResolvedToilConfig,
-    routeFile: string,
-    base: string,
-    includeClientRoot: boolean,
-): string[] {
-    const chain: string[] = [];
-    const relDir = path.dirname(path.relative(cfg.routesAbsDir, routeFile));
-    const segments = relDir === '.' ? [] : relDir.split(path.sep);
-    // A parallel-slot route (one under an `@slot` segment) is rendered INTO a parent layout's
-    // `<Slot>`. Its own layout/template chain must therefore start at the `@slot` directory, not the
-    // routes root: the parent segments' layouts already wrap the slot, so re-including them here
-    // would nest the slot inside itself and recurse. For non-slot routes this is the full chain.
-    const slotIdx = segments.findIndex((s) => s.startsWith('@'));
-    const startAt = slotIdx < 0 ? 0 : slotIdx + 1;
-    if (includeClientRoot && slotIdx < 0) {
-        const root = specialIn(cfg.clientAbsDir, base);
-        if (root) chain.push(root);
-    }
-    let dir = cfg.routesAbsDir;
-    for (let i = 0; i <= segments.length; i++) {
-        if (i > 0) dir = path.join(dir, segments[i - 1]);
-        if (i < startAt) continue;
-        const found = specialIn(dir, base);
-        if (found) chain.push(found);
-    }
-    return chain;
-}
-
-/** Nearest special file named `base` (e.g. `loading`/`error`) from the route's dir up to the routes root. */
-function findNearest(cfg: ResolvedToilConfig, routeFile: string, base: string): string | undefined {
-    const root = path.resolve(cfg.routesAbsDir);
-    let dir = path.dirname(routeFile);
-    for (;;) {
-        const found = [`${base}.tsx`, `${base}.jsx`]
-            .map((name) => path.join(dir, name))
-            .find((p) => fs.existsSync(p));
-        if (found) return found;
-        if (path.resolve(dir) === root) return undefined;
-        const parent = path.dirname(dir);
-        if (parent === dir) return undefined;
-        dir = parent;
-    }
-}
-
-/**
- * Generates the `.toil/` working dir (routes table, mount entry, the HTML entry built from the
- * project's `public/index.html` template, and mirrored `public/` assets) and returns the scanned
- * routes. Called before every dev/build and on route add/remove during dev.
- */
-export function generate(cfg: ResolvedToilConfig): ScannedRoute[] {
-    const routes = scanRoutes(cfg.routesAbsDir);
-    fs.mkdirSync(cfg.toilDir, { recursive: true });
-
-    const layoutFile = findLayout(cfg);
-    const notFoundFile = findNotFound(cfg);
-    const globalErrorFile = findGlobalError(cfg);
-    const imp = (f: string): string => `() => import(${JSON.stringify(relFromToil(cfg, f))})`;
-    const routeObj = (r: ScannedRoute): string => {
-        const layouts = findSpecialChain(cfg, r.file, 'layout', false).map(imp).join(', ');
-        const templates = findSpecialChain(cfg, r.file, 'template', true).map(imp).join(', ');
-        const parts = [
-            `pattern: ${JSON.stringify(r.pattern)}`,
-            `load: ${imp(r.file)}`,
-            `layouts: [${layouts}]`,
-        ];
-        if (templates) parts.push(`templates: [${templates}]`);
-        const loadingFile = findNearest(cfg, r.file, 'loading');
-        if (loadingFile) parts.push(`loading: ${imp(loadingFile)}`);
-        const errorFile = findNearest(cfg, r.file, 'error');
-        if (errorFile) parts.push(`errorComponent: ${imp(errorFile)}`);
-        if (r.intercept) parts.push(`intercept: true`);
-        return `{ ${parts.join(', ')} }`;
-    };
-    const mainRoutes = routes.filter((r) => r.slot === undefined);
-    const slotNames = [...new Set(routes.flatMap((r) => (r.slot ? [r.slot] : [])))];
-    const slotsBody = slotNames
-        .map((name) => {
-            const items = routes
-                .filter((r) => r.slot === name)
-                .map((r) => `    ${routeObj(r)},`)
-                .join('\n');
-            return `  ${JSON.stringify(name)}: [\n${items}\n  ],`;
-        })
-        .join('\n');
-    const routesSrc =
-        `// @ts-nocheck\n` +
-        `// AUTO-GENERATED by toil, do not edit.\n` +
-        `import type { RouteDef, LayoutLoader, NotFoundLoader } from 'toiljs/client';\n\n` +
-        `export const routes: RouteDef[] = [\n${mainRoutes.map((r) => `  ${routeObj(r)},`).join('\n')}\n];\n\n` +
-        `export const slots: Record<string, RouteDef[]> = {\n${slotsBody}\n};\n\n` +
-        `export const layout: LayoutLoader = ${layoutFile ? `() => import(${JSON.stringify(relFromToil(cfg, layoutFile))})` : 'null'};\n` +
-        `export const notFound: NotFoundLoader = ${notFoundFile ? `() => import(${JSON.stringify(relFromToil(cfg, notFoundFile))})` : 'null'};\n` +
-        `export const globalError = ${globalErrorFile ? `() => import(${JSON.stringify(relFromToil(cfg, globalErrorFile))})` : 'null'};\n`;
-    fs.writeFileSync(path.join(cfg.toilDir, 'routes.ts'), routesSrc);
-
-    const globalsSrc =
-        `// @ts-nocheck\n` +
-        `// AUTO-GENERATED by toil, do not edit.\n` +
-        `import * as Toil from 'toiljs/client';\n` +
-        `import { BinaryWriter, BinaryReader, FastMap, FastSet } from 'toiljs/io';\n\n` +
-        `Object.assign(globalThis, { Toil, BinaryWriter, BinaryReader, FastMap, FastSet });\n` +
-        `Toil.setViewTransitions(${String(cfg.viewTransitions)});\n`;
-    fs.writeFileSync(path.join(cfg.toilDir, 'globals.ts'), globalsSrc);
-
-    const entryFile = findEntry(cfg);
-    const entrySrc = entryFile
-        ? `// @ts-nocheck\n` +
-          `// AUTO-GENERATED by toil, do not edit.\n` +
-          `import './globals';\n` +
-          `import ${JSON.stringify(relFromToil(cfg, entryFile))};\n`
-        : `// @ts-nocheck\n` +
-          `// AUTO-GENERATED by toil, do not edit.\n` +
-          `import './globals';\n` +
-          `import { mount } from 'toiljs/client';\n` +
-          `import { routes, layout, notFound, globalError, slots } from './routes';\n\n` +
-          `mount(routes, layout, notFound, globalError, slots);\n`;
-    fs.writeFileSync(path.join(cfg.toilDir, 'entry.tsx'), entrySrc);
-
-    fs.writeFileSync(path.join(cfg.root, 'toil-env.d.ts'), TOIL_ENV_DTS);
-    fs.writeFileSync(path.join(cfg.root, 'toil-routes.d.ts'), routesDts(cfg, routes));
-
-    fs.writeFileSync(path.join(cfg.toilDir, 'index.html'), buildHtml(cfg));
-    syncPublicAssets(cfg);
-    writeSeoFiles(cfg, routes);
-    writeDocs(cfg.toilDir);
-
-    return routes;
-}
-
-/**
- * Writes the build-time SEO crawler files into `.toil/public` (Vite's publicDir, served in dev and
- * copied to the output root in build): `robots.txt` (incl. AI-crawler directives), `sitemap.xml`
- * (static routes), and `llms.txt` (AI guidance). No-op when SEO isn't configured.
- */
-function writeSeoFiles(cfg: ResolvedToilConfig, routes: ScannedRoute[]): void {
-    if (!cfg.seo) return;
-    const dest = path.join(cfg.toilDir, 'public');
-    const files: [string, string][] = [
-        ['robots.txt', robotsTxt(cfg.seo)],
-        ['sitemap.xml', sitemapXml(cfg.seo, routes)],
-        ['llms.txt', llmsTxt(cfg.seo, routes)],
-    ];
-    const present = files.filter(([, content]) => content !== '');
-    if (present.length === 0) return;
-    fs.mkdirSync(dest, { recursive: true });
-    for (const [name, content] of present) fs.writeFileSync(path.join(dest, name), content);
-}
-
-/** Fallback HTML when the project has no `public/index.html` template. The entry script is added
- * by {@link buildHtml}. */
-const DEFAULT_HTML =
-    `<!doctype html>\n<html lang="en">\n  <head>\n    <meta charset="utf-8" />\n` +
-    `    <meta name="viewport" content="width=device-width, initial-scale=1" />\n` +
-    `    <meta name="description" content="" />\n` +
-    `    <title>Toil App</title>\n  </head>\n  <body>\n    <div id="root"></div>\n` +
-    `  </body>\n</html>\n`;
-
-/** The module entry that boots the app, injected into the HTML (resolved relative to `.toil`). */
-const ENTRY_SCRIPT = `<script type="module" src="./entry.tsx"></script>`;
-
-/**
- * Produces the `.toil/index.html` Vite entry from the project's `public/index.html` template (or
- * the built-in default if absent), ensuring the generated module entry script is present. Users
- * own the template, toil only guarantees the entry is wired, so it stays the SPA root.
- */
-function buildHtml(cfg: ResolvedToilConfig): string {
-    const templatePath = path.join(cfg.publicDir, 'index.html');
-    let html = fs.existsSync(templatePath)
-        ? fs.readFileSync(templatePath, 'utf8')
-        : DEFAULT_HTML;
-    // Inject the entry only if the template doesn't already reference it as a module script
-    // (matching the literal filename anywhere in the file would be too eager).
-    if (!/src=["']\.\/entry\.tsx["']/.test(html)) {
-        html = html.includes('</body>')
-            ? html.replace('</body>', `    ${ENTRY_SCRIPT}\n  </body>`)
-            : `${html}\n${ENTRY_SCRIPT}\n`;
-    }
-    return html;
-}
-
-/**
- * Mirrors the project's `public/` assets into `.toil/public/` (Vite's publicDir under the `.toil`
- * root), excluding the `index.html` template, that is processed into the entry above, and copying
- * it here would clobber the built, asset-hashed page. Cleared each run so deletions propagate.
- */
-function syncPublicAssets(cfg: ResolvedToilConfig): void {
-    const dest = path.join(cfg.toilDir, 'public');
-    fs.rmSync(dest, { recursive: true, force: true });
-    if (!fs.existsSync(cfg.publicDir)) return;
-
-    let copied = 0;
-    for (const entry of fs.readdirSync(cfg.publicDir, { withFileTypes: true })) {
-        if (entry.name === 'index.html') continue;
-        fs.cpSync(path.join(cfg.publicDir, entry.name), path.join(dest, entry.name), {
-            recursive: true,
-        });
-        copied++;
-    }
-    if (copied === 0) fs.rmSync(dest, { recursive: true, force: true });
-}
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { type ResolvedToilConfig } from './config.js';
+import { writeDocs } from './docs.js';
+import { buildPageIndex, pagesModuleSource } from './pages.js';
+import { scanRoutes, type ScannedRoute } from './routes.js';
+import { llmsTxt, robotsTxt, sitemapXml } from './seo.js';
+
+/**
+ * Contents of the root `toil-env.d.ts`: ambient global types so `new BinaryWriter()` etc. resolve
+ * in the IDE without an import. Script-mode declaration (no top-level import/export → the
+ * `declare const`s are truly global, and it's not a module that could confuse ESLint's project
+ * service); the inline `import('toiljs/io')` type only needs the normal `toiljs/io` export.
+ * Lives at the project root because TypeScript's `include` globs skip dot-directories.
+ * Exported so `toiljs create` can write it during scaffolding, before the first dev/build.
+ */
+/** Side-effect style imports (e.g. `import './styles/main.css'`). */
+const STYLE_EXTENSIONS = ['css', 'scss', 'sass', 'less', 'styl', 'stylus', 'pcss', 'sss'];
+/** Asset imports whose default export is the resolved URL string (e.g. `import logo from './logo.svg'`). */
+const ASSET_EXTENSIONS = ['svg', 'png', 'jpg', 'jpeg', 'gif', 'webp', 'avif', 'ico', 'bmp', 'apng'];
+
+const STYLE_MODULES = STYLE_EXTENSIONS.map((ext) => `declare module '*.${ext}' {}`).join('\n');
+const ASSET_MODULES = ASSET_EXTENSIONS.map(
+    (ext) => `declare module '*.${ext}' {\n    const src: string;\n    export default src;\n}`,
+).join('\n');
+
+export const TOIL_ENV_DTS =
+    `// AUTO-GENERATED by toil, do not edit.\n` +
+    // Types for image-optimization query imports (`import img from './x.png?w=400&format=webp'`).
+    `/// <reference types="vite-imagetools/client" />\n` +
+    `declare const Toil: typeof import('toiljs/client');\n` +
+    `declare namespace Toil {\n` +
+    `    type LoaderArgs = import('toiljs/client').LoaderArgs;\n` +
+    `    type LoaderFunction<T = unknown> = import('toiljs/client').LoaderFunction<T>;\n` +
+    `    type Revalidate = import('toiljs/client').Revalidate;\n` +
+    `    type Metadata = import('toiljs/client').Metadata;\n` +
+    `    type GenerateMetadata<T = unknown> = import('toiljs/client').GenerateMetadata<T>;\n` +
+    `    type RouteErrorProps = import('toiljs/client').RouteErrorProps;\n` +
+    `    type Href = import('toiljs/client').Href;\n` +
+    `    type RoutePath = import('toiljs/client').RoutePath;\n` +
+    `    type PageMeta = import('toiljs/client').PageMeta;\n` +
+    `    type SearchHints = import('toiljs/client').SearchHints;\n` +
+    `}\n` +
+    `declare const BinaryWriter: typeof import('toiljs/io').BinaryWriter;\n` +
+    `declare const BinaryReader: typeof import('toiljs/io').BinaryReader;\n` +
+    `declare const FastMap: typeof import('toiljs/io').FastMap;\n` +
+    `declare const FastSet: typeof import('toiljs/io').FastSet;\n` +
+    `\n` +
+    `${STYLE_MODULES}\n` +
+    `\n` +
+    `${ASSET_MODULES}\n` +
+    `\n` +
+    `declare module 'toiljs/routes' {\n` +
+    `    export const routes: import('toiljs/client').RouteDef[];\n` +
+    `    export const layout: import('toiljs/client').LayoutLoader;\n` +
+    `    export const notFound: import('toiljs/client').NotFoundLoader;\n` +
+    `    export const globalError: import('toiljs/client').ErrorComponentLoader;\n` +
+    `    export const slots: Record<string, import('toiljs/client').RouteDef[]>;\n` +
+    `    export const pages: import('toiljs/client').PageMeta[];\n` +
+    `}\n`;
+
+/**
+ * Returns a `./`-prefixed, **extensionless** POSIX module specifier from `.toil` to `abs`, for use
+ * in generated `import(...)` calls. Extensionless so TypeScript doesn't demand
+ * `allowImportingTsExtensions` (TS5097) when the generated files are checked; Vite still resolves it.
+ */
+function relFromToil(cfg: ResolvedToilConfig, abs: string): string {
+    let rel = path
+        .relative(cfg.toilDir, abs)
+        .replace(/\\/g, '/')
+        .replace(/\.(tsx|jsx)$/, '');
+    if (!rel.startsWith('.')) rel = './' + rel;
+    return rel;
+}
+
+function findLayout(cfg: ResolvedToilConfig): string | undefined {
+    return ['layout.tsx', 'layout.jsx']
+        .map((name) => path.join(cfg.clientAbsDir, name))
+        .find((p) => fs.existsSync(p));
+}
+
+/** Finds an optional custom not-found page at `client/404.{tsx,jsx}`. */
+function findNotFound(cfg: ResolvedToilConfig): string | undefined {
+    return ['404.tsx', '404.jsx']
+        .map((name) => path.join(cfg.clientAbsDir, name))
+        .find((p) => fs.existsSync(p));
+}
+
+/** Finds an optional root error boundary at `client/global-error.{tsx,jsx}`. */
+function findGlobalError(cfg: ResolvedToilConfig): string | undefined {
+    return ['global-error.tsx', 'global-error.jsx']
+        .map((name) => path.join(cfg.clientAbsDir, name))
+        .find((p) => fs.existsSync(p));
+}
+
+/**
+ * Builds the `RoutePath` union for typed `Link`/`navigate` hrefs: static routes as string literals,
+ * dynamic/catch-all as `` `…/${string}` `` templates (optional catch-all also emits its bare prefix).
+ */
+function routePathUnion(routes: ScannedRoute[]): string {
+    const members = new Set<string>();
+    for (const route of routes) {
+        const segments = route.pattern.split('/').filter(Boolean);
+        const isDynamic = segments.some((s) => s.startsWith(':') || s.startsWith('*'));
+        if (!isDynamic) {
+            members.add(`'${route.pattern}'`);
+            continue;
+        }
+        const parts = segments.map((s) =>
+            s.startsWith(':') || s.startsWith('*') ? '${string}' : s,
+        );
+        members.add('`/' + parts.join('/') + '`');
+        const optionalIdx = segments.findIndex((s) => s.startsWith('**'));
+        if (optionalIdx !== -1) {
+            const prefix = '/' + segments.slice(0, optionalIdx).join('/');
+            members.add(`'${prefix}'`);
+        }
+    }
+    return members.size ? [...members].join(' | ') : 'string';
+}
+
+/**
+ * The `toil-routes.d.ts` contents: a module augmentation registering the project's route paths so
+ * `Link`/`navigate`/`useRouter` hrefs are type-checked. Regenerated each dev/build.
+ */
+function routesDts(cfg: ResolvedToilConfig, routes: ScannedRoute[]): string {
+    // Type-only namespace import of every route module (erased at build) so editors don't flag a
+    // route's `loader` / `metadata` / `generateMetadata` / `revalidate` / `default` exports as unused
+    // — the compiler consumes them via dynamic `import()`, which editors don't count as a reference.
+    const refs = routes.map((route, i) => {
+        let rel = path
+            .relative(cfg.root, route.file)
+            .replace(/\\/g, '/')
+            .replace(/\.(tsx|jsx)$/, '');
+        if (!rel.startsWith('.')) rel = `./${rel}`;
+        return { name: `_toilRoute${String(i)}`, rel };
+    });
+    const imports = refs
+        .map((m) => `import type * as ${m.name} from ${JSON.stringify(m.rel)};\n`)
+        .join('');
+    const referenced = refs.length
+        ? `export type _ToilRouteModules = [${refs.map((m) => `typeof ${m.name}`).join(', ')}];\n`
+        : `export {};\n`;
+    return (
+        `// AUTO-GENERATED by toil, do not edit.\n` +
+        imports +
+        referenced +
+        `declare module 'toiljs/client' {\n` +
+        `    interface Register {\n` +
+        `        routePath: ${routePathUnion(routes)};\n` +
+        `    }\n` +
+        `}\n`
+    );
+}
+
+/** Finds the user-owned app entry at `client/toil.{tsx,jsx}` (where `mount` is called). */
+function findEntry(cfg: ResolvedToilConfig): string | undefined {
+    return ['toil.tsx', 'toil.jsx']
+        .map((name) => path.join(cfg.clientAbsDir, name))
+        .find((p) => fs.existsSync(p));
+}
+
+/** A `<base>.{tsx,jsx}` in `dir`, or undefined. */
+function specialIn(dir: string, base: string): string | undefined {
+    return [`${base}.tsx`, `${base}.jsx`]
+        .map((name) => path.join(dir, name))
+        .find((p) => fs.existsSync(p));
+}
+
+/**
+ * Chain of `<base>.{tsx,jsx}` files wrapping a route, shallowest → deepest: the routes root and each
+ * ancestor directory down to the file's own. With `includeClientRoot`, `client/<base>` is prepended
+ * as the outermost (used by templates; the root `client/layout.tsx` is instead the top-level layout).
+ */
+function findSpecialChain(
+    cfg: ResolvedToilConfig,
+    routeFile: string,
+    base: string,
+    includeClientRoot: boolean,
+): string[] {
+    const chain: string[] = [];
+    const relDir = path.dirname(path.relative(cfg.routesAbsDir, routeFile));
+    const segments = relDir === '.' ? [] : relDir.split(path.sep);
+    // A parallel-slot route (one under an `@slot` segment) is rendered INTO a parent layout's
+    // `<Slot>`. Its own layout/template chain must therefore start at the `@slot` directory, not the
+    // routes root: the parent segments' layouts already wrap the slot, so re-including them here
+    // would nest the slot inside itself and recurse. For non-slot routes this is the full chain.
+    const slotIdx = segments.findIndex((s) => s.startsWith('@'));
+    const startAt = slotIdx < 0 ? 0 : slotIdx + 1;
+    if (includeClientRoot && slotIdx < 0) {
+        const root = specialIn(cfg.clientAbsDir, base);
+        if (root) chain.push(root);
+    }
+    let dir = cfg.routesAbsDir;
+    for (let i = 0; i <= segments.length; i++) {
+        if (i > 0) dir = path.join(dir, segments[i - 1]);
+        if (i < startAt) continue;
+        const found = specialIn(dir, base);
+        if (found) chain.push(found);
+    }
+    return chain;
+}
+
+/** Nearest special file named `base` (e.g. `loading`/`error`) from the route's dir up to the routes root. */
+function findNearest(cfg: ResolvedToilConfig, routeFile: string, base: string): string | undefined {
+    const root = path.resolve(cfg.routesAbsDir);
+    let dir = path.dirname(routeFile);
+    for (;;) {
+        const found = [`${base}.tsx`, `${base}.jsx`]
+            .map((name) => path.join(dir, name))
+            .find((p) => fs.existsSync(p));
+        if (found) return found;
+        if (path.resolve(dir) === root) return undefined;
+        const parent = path.dirname(dir);
+        if (parent === dir) return undefined;
+        dir = parent;
+    }
+}
+
+/**
+ * Generates the `.toil/` working dir (routes table, mount entry, the HTML entry built from the
+ * project's `public/index.html` template, and mirrored `public/` assets) and returns the scanned
+ * routes. Called before every dev/build and on route add/remove during dev.
+ */
+export function generate(cfg: ResolvedToilConfig): ScannedRoute[] {
+    const routes = scanRoutes(cfg.routesAbsDir);
+    fs.mkdirSync(cfg.toilDir, { recursive: true });
+
+    const layoutFile = findLayout(cfg);
+    const notFoundFile = findNotFound(cfg);
+    const globalErrorFile = findGlobalError(cfg);
+    const imp = (f: string): string => `() => import(${JSON.stringify(relFromToil(cfg, f))})`;
+    const routeObj = (r: ScannedRoute): string => {
+        const layouts = findSpecialChain(cfg, r.file, 'layout', false).map(imp).join(', ');
+        const templates = findSpecialChain(cfg, r.file, 'template', true).map(imp).join(', ');
+        const parts = [
+            `pattern: ${JSON.stringify(r.pattern)}`,
+            `load: ${imp(r.file)}`,
+            `layouts: [${layouts}]`,
+        ];
+        if (templates) parts.push(`templates: [${templates}]`);
+        const loadingFile = findNearest(cfg, r.file, 'loading');
+        if (loadingFile) parts.push(`loading: ${imp(loadingFile)}`);
+        const errorFile = findNearest(cfg, r.file, 'error');
+        if (errorFile) parts.push(`errorComponent: ${imp(errorFile)}`);
+        if (r.intercept) parts.push(`intercept: true`);
+        return `{ ${parts.join(', ')} }`;
+    };
+    const mainRoutes = routes.filter((r) => r.slot === undefined);
+    const slotNames = [...new Set(routes.flatMap((r) => (r.slot ? [r.slot] : [])))];
+    const slotsBody = slotNames
+        .map((name) => {
+            const items = routes
+                .filter((r) => r.slot === name)
+                .map((r) => `    ${routeObj(r)},`)
+                .join('\n');
+            return `  ${JSON.stringify(name)}: [\n${items}\n  ],`;
+        })
+        .join('\n');
+    const pages = buildPageIndex(cfg.root, routes);
+    const routesSrc =
+        `// @ts-nocheck\n` +
+        `// AUTO-GENERATED by toil, do not edit.\n` +
+        `import type { RouteDef, LayoutLoader, NotFoundLoader, PageMeta } from 'toiljs/client';\n\n` +
+        `export const routes: RouteDef[] = [\n${mainRoutes.map((r) => `  ${routeObj(r)},`).join('\n')}\n];\n\n` +
+        `export const slots: Record<string, RouteDef[]> = {\n${slotsBody}\n};\n\n` +
+        `export const layout: LayoutLoader = ${layoutFile ? `() => import(${JSON.stringify(relFromToil(cfg, layoutFile))})` : 'null'};\n` +
+        `export const notFound: NotFoundLoader = ${notFoundFile ? `() => import(${JSON.stringify(relFromToil(cfg, notFoundFile))})` : 'null'};\n` +
+        `export const globalError = ${globalErrorFile ? `() => import(${JSON.stringify(relFromToil(cfg, globalErrorFile))})` : 'null'};\n\n` +
+        pagesModuleSource(pages);
+    fs.writeFileSync(path.join(cfg.toilDir, 'routes.ts'), routesSrc);
+
+    const globalsSrc =
+        `// @ts-nocheck\n` +
+        `// AUTO-GENERATED by toil, do not edit.\n` +
+        `import * as Toil from 'toiljs/client';\n` +
+        `import { BinaryWriter, BinaryReader, FastMap, FastSet } from 'toiljs/io';\n` +
+        `import { pages } from './routes';\n\n` +
+        `Object.assign(globalThis, { Toil, BinaryWriter, BinaryReader, FastMap, FastSet });\n` +
+        `Toil.setViewTransitions(${String(cfg.viewTransitions)});\n` +
+        `Toil.registerPages(pages);\n`;
+    fs.writeFileSync(path.join(cfg.toilDir, 'globals.ts'), globalsSrc);
+
+    const entryFile = findEntry(cfg);
+    const entrySrc = entryFile
+        ? `// @ts-nocheck\n` +
+          `// AUTO-GENERATED by toil, do not edit.\n` +
+          `import './globals';\n` +
+          `import ${JSON.stringify(relFromToil(cfg, entryFile))};\n`
+        : `// @ts-nocheck\n` +
+          `// AUTO-GENERATED by toil, do not edit.\n` +
+          `import './globals';\n` +
+          `import { mount } from 'toiljs/client';\n` +
+          `import { routes, layout, notFound, globalError, slots } from './routes';\n\n` +
+          `mount(routes, layout, notFound, globalError, slots);\n`;
+    fs.writeFileSync(path.join(cfg.toilDir, 'entry.tsx'), entrySrc);
+
+    fs.writeFileSync(path.join(cfg.root, 'toil-env.d.ts'), TOIL_ENV_DTS);
+    fs.writeFileSync(path.join(cfg.root, 'toil-routes.d.ts'), routesDts(cfg, routes));
+
+    fs.writeFileSync(path.join(cfg.toilDir, 'index.html'), buildHtml(cfg));
+    syncPublicAssets(cfg);
+    writeSeoFiles(cfg, routes);
+    writeDocs(cfg.toilDir);
+
+    return routes;
+}
+
+/**
+ * Writes the build-time SEO crawler files into `.toil/public` (Vite's publicDir, served in dev and
+ * copied to the output root in build): `robots.txt` (incl. AI-crawler directives), `sitemap.xml`
+ * (static routes), and `llms.txt` (AI guidance). No-op when SEO isn't configured.
+ */
+function writeSeoFiles(cfg: ResolvedToilConfig, routes: ScannedRoute[]): void {
+    if (!cfg.seo) return;
+    const dest = path.join(cfg.toilDir, 'public');
+    const files: [string, string][] = [
+        ['robots.txt', robotsTxt(cfg.seo)],
+        ['sitemap.xml', sitemapXml(cfg.seo, routes)],
+        ['llms.txt', llmsTxt(cfg.seo, routes)],
+    ];
+    const present = files.filter(([, content]) => content !== '');
+    if (present.length === 0) return;
+    fs.mkdirSync(dest, { recursive: true });
+    for (const [name, content] of present) fs.writeFileSync(path.join(dest, name), content);
+}
+
+/** Fallback HTML when the project has no `public/index.html` template. The entry script is added
+ * by {@link buildHtml}. */
+const DEFAULT_HTML =
+    `<!doctype html>\n<html lang="en">\n  <head>\n    <meta charset="utf-8" />\n` +
+    `    <meta name="viewport" content="width=device-width, initial-scale=1" />\n` +
+    `    <meta name="description" content="" />\n` +
+    `    <title>Toil App</title>\n  </head>\n  <body>\n    <div id="root"></div>\n` +
+    `  </body>\n</html>\n`;
+
+/** The module entry that boots the app, injected into the HTML (resolved relative to `.toil`). */
+const ENTRY_SCRIPT = `<script type="module" src="./entry.tsx"></script>`;
+
+/**
+ * Produces the `.toil/index.html` Vite entry from the project's `public/index.html` template (or
+ * the built-in default if absent), ensuring the generated module entry script is present. Users
+ * own the template, toil only guarantees the entry is wired, so it stays the SPA root.
+ */
+function buildHtml(cfg: ResolvedToilConfig): string {
+    const templatePath = path.join(cfg.publicDir, 'index.html');
+    let html = fs.existsSync(templatePath) ? fs.readFileSync(templatePath, 'utf8') : DEFAULT_HTML;
+    // Inject the entry only if the template doesn't already reference it as a module script
+    // (matching the literal filename anywhere in the file would be too eager).
+    if (!/src=["']\.\/entry\.tsx["']/.test(html)) {
+        html = html.includes('</body>')
+            ? html.replace('</body>', `    ${ENTRY_SCRIPT}\n  </body>`)
+            : `${html}\n${ENTRY_SCRIPT}\n`;
+    }
+    return html;
+}
+
+/**
+ * Mirrors the project's `public/` assets into `.toil/public/` (Vite's publicDir under the `.toil`
+ * root), excluding the `index.html` template, that is processed into the entry above, and copying
+ * it here would clobber the built, asset-hashed page. Cleared each run so deletions propagate.
+ */
+function syncPublicAssets(cfg: ResolvedToilConfig): void {
+    const dest = path.join(cfg.toilDir, 'public');
+    fs.rmSync(dest, { recursive: true, force: true });
+    if (!fs.existsSync(cfg.publicDir)) return;
+
+    let copied = 0;
+    for (const entry of fs.readdirSync(cfg.publicDir, { withFileTypes: true })) {
+        if (entry.name === 'index.html') continue;
+        fs.cpSync(path.join(cfg.publicDir, entry.name), path.join(dest, entry.name), {
+            recursive: true,
+        });
+        copied++;
+    }
+    if (copied === 0) fs.rmSync(dest, { recursive: true, force: true });
+}