toiljs 0.0.4 → 0.0.6

package/src/client/{match.ts → routing/match.ts}

@@ -6,7 +6,8 @@ export type RouteParams = Record<string, string>;
  * Pure and runtime-agnostic (used by the router and unit-tested directly).
  *   matchRoute('/', '/')                  -> {}
  *   matchRoute('/blog/:id', '/blog/42')   -> { id: '42' }
- *   matchRoute('/docs/*slug', '/docs/a/b') -> { slug: 'a/b' }   (catch-all)
+ *   matchRoute('/docs/*slug', '/docs/a/b') -> { slug: 'a/b' }   (catch-all, 1+ segments)
+ *   matchRoute('/docs/**slug', '/docs')   -> { slug: '' }       (optional catch-all, 0+ segments)
  *   matchRoute('/about', '/x')            -> null
  */
 export function matchRoute(pattern: string, pathname: string): RouteParams | null {
@@ -17,7 +18,15 @@ export function matchRoute(pattern: string, pathname: string): RouteParams | nul
     for (let i = 0; i < patternSegs.length; i++) {
         const p = patternSegs[i];
 
-        // Catch-all (`*slug`): captures the rest of the path (one or more segments).
+        // Optional catch-all (`**slug`): captures the rest of the path, matching zero or more segments.
+        if (p.startsWith('**')) {
+            params[p.slice(2)] = pathSegs
+                .slice(i)
+                .map((s) => decodeURIComponent(s))
+                .join('/');
+            return params;
+        }
+
         if (p.startsWith('*')) {
             const rest = pathSegs.slice(i);
             if (rest.length === 0) return null;
@@ -34,6 +43,5 @@ export function matchRoute(pattern: string, pathname: string): RouteParams | nul
         }
     }
 
-    // No catch-all consumed the tail: lengths must match exactly.
     return patternSegs.length === pathSegs.length ? params : null;
 }

package/src/client/routing/mount.tsx

@@ -0,0 +1,28 @@
+import { createRoot } from 'react-dom/client';
+
+import { initNavigation } from '../navigation/navigation.js';
+import { startPrefetcher } from '../navigation/prefetch.js';
+import { Router } from './Router.js';
+import type { LayoutLoader, NotFoundLoader, RouteDef } from '../types.js';
+
+/**
+ * Mounts the toil client app into `#root` and starts idle link prefetching. Called by the
+ * compiler-generated `.toil/entry.tsx`.
+ */
+export function mount(
+    routes: RouteDef[],
+    layout: LayoutLoader = null,
+    notFound: NotFoundLoader = null,
+): void {
+    const el = document.getElementById('root');
+    if (!el) throw new Error('toil: #root element not found');
+    initNavigation();
+    createRoot(el).render(
+        <Router
+            routes={routes}
+            layout={layout}
+            notFound={notFound}
+        />,
+    );
+    startPrefetcher(routes);
+}

package/src/client/routing/params-context.ts

@@ -0,0 +1,10 @@
+/**
+ * React context carrying the current route's dynamic params. The provider is set by {@link Router};
+ * read it with the {@link useParams} hook rather than consuming the context directly.
+ */
+import { createContext } from 'react';
+
+import type { RouteParams } from './match.js';
+
+/** Holds the params extracted from the active route (e.g. `{ id }` for `/blog/:id`). */
+export const ParamsContext = createContext<RouteParams>({});

package/src/client/types.ts

@@ -0,0 +1,36 @@
+/**
+ * Public router types shared across the client runtime. Kept dependency-free (type-only React
+ * imports) so any module can import them without pulling in component or DOM code.
+ */
+import type { ComponentType, ReactNode } from 'react';
+
+/** Lazy loader for a layout component (wraps children). */
+export type LayoutComponentLoader = () => Promise<{
+    default: ComponentType<{ children?: ReactNode }>;
+}>;
+
+/** Props passed to an `error.tsx` component: the thrown error and a function to retry rendering. */
+export interface RouteErrorProps {
+    readonly error: Error;
+    readonly reset: () => void;
+}
+
+/**
+ * A route entry produced by the compiler: a URL pattern, a lazy loader for its page component, and
+ * the chain of nested layout loaders (shallowest → deepest, from nested `layout.tsx` files) that wrap it.
+ */
+export interface RouteDef {
+    readonly pattern: string;
+    readonly load: () => Promise<{ default: ComponentType }>;
+    readonly layouts?: readonly LayoutComponentLoader[];
+    /** Nearest `loading.tsx` — shown as the Suspense fallback while this route loads. */
+    readonly loading?: () => Promise<{ default: ComponentType }>;
+    /** Nearest `error.tsx` — rendered by an error boundary around this route. */
+    readonly errorComponent?: () => Promise<{ default: ComponentType<RouteErrorProps> }>;
+}
+
+/** Optional root layout loader (wraps every page). `null` when the project defines no layout. */
+export type LayoutLoader = LayoutComponentLoader | null;
+
+/** Optional custom not-found (404) page loader, rendered when no route matches. */
+export type NotFoundLoader = (() => Promise<{ default: ComponentType }>) | null;

package/src/compiler/config.ts

@@ -12,7 +12,13 @@ export interface ClientConfig {
     readonly srcDir?: string;
     /** Routes directory, relative to `srcDir`. Default `routes`. */
     readonly routesDir?: string;
-    /** Production output directory, relative to root. Default `dist`. */
+    /**
+     * Static assets directory, relative to root. Default `<srcDir>/public` (e.g. `client/public`).
+     * Holds the `index.html` template (owned and edited by you) plus any files served as-is at the
+     * base path (favicons, images, …).
+     */
+    readonly publicDir?: string;
+    /** Production output directory, relative to root. Default `build/client`. */
     readonly outDir?: string;
     /** Public base path. Default `/`. */
     readonly base?: string;
@@ -27,7 +33,7 @@ export interface ClientConfig {
 }
 
 /**
- * Server-side (AssemblyScript → WASM) configuration. Reserved: the compiler does not yet
+ * Server-side (toilscript → WASM) configuration. Reserved: the compiler does not yet
  * build the server target via `toil build`; today it is compiled by `toilscript` directly.
  */
 export interface ServerConfig {
@@ -46,7 +52,7 @@ export interface ToilConfig {
     readonly root?: string;
     /** Client (TSX/React/Vite) configuration. */
     readonly client?: ClientConfig;
-    /** Server (AssemblyScript/WASM) configuration. */
+    /** Server (toilscript/WASM) configuration. */
     readonly server?: ServerConfig;
 }
 
@@ -56,6 +62,8 @@ export interface ResolvedToilConfig {
     readonly srcDir: string;
     readonly clientAbsDir: string;
     readonly routesAbsDir: string;
+    /** Absolute path to the static-assets dir (holds the `index.html` template). */
+    readonly publicDir: string;
     readonly toilDir: string;
     readonly outDir: string;
     readonly base: string;
@@ -70,14 +78,23 @@ export function defineConfig(config: ToilConfig): ToilConfig {
     return config;
 }
 
-const CONFIG_NAMES = ['toil.config.ts', 'toil.config.mts', 'toil.config.js', 'toil.config.mjs'];
+const CONFIG_NAMES = [
+    'toil.config.ts',
+    'toil.config.mts',
+    'toil.config.js',
+    'toil.config.mjs',
+    'toiljs.config.ts',
+    'toiljs.config.mts',
+    'toiljs.config.js',
+    'toiljs.config.mjs',
+];
 
 /** Path to the built client runtime (`build/client/index.js`), sibling to `build/compiler`. */
 function resolveRuntimePath(): string {
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../client/index.js');
 }
 
-/** Finds and loads `toil.config.*` from `root` (via Vite's bundling loader), then resolves defaults. */
+/** Finds and loads `toil.config.*` or `toiljs.config.*` from `root`, then resolves defaults. */
 export async function loadConfig(
     opts: { root?: string; port?: number } = {},
 ): Promise<ResolvedToilConfig> {
@@ -87,10 +104,6 @@ export async function loadConfig(
     for (const name of CONFIG_NAMES) {
         const candidate = path.join(root, name);
         if (fs.existsSync(candidate)) {
-            // Native ESM import (Node strips types from .ts/.mts). This keeps config loading
-            // independent of the project's tsconfig — which may `extends` a not-yet-installed
-            // package and would otherwise throw TSCONFIG_ERROR — and a file URL imports absolute
-            // paths correctly on Windows.
             // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- dynamic import() is typed `any`
             const loaded: { default?: ToilConfig } = await import(pathToFileURL(candidate).href);
             if (loaded.default) user = loaded.default;
@@ -108,8 +121,11 @@ export async function loadConfig(
         srcDir,
         clientAbsDir,
         routesAbsDir: path.join(clientAbsDir, routesDir),
+        publicDir: client.publicDir
+            ? path.resolve(root, client.publicDir)
+            : path.join(clientAbsDir, 'public'),
         toilDir: path.join(root, '.toil'),
-        outDir: client.outDir ?? 'dist',
+        outDir: client.outDir ?? 'build/client',
         base: client.base ?? '/',
         port: opts.port ?? client.port ?? 3000,
         runtimePath: resolveRuntimePath(),

package/src/compiler/docs.ts

@@ -0,0 +1,87 @@
+/**
+ * AI-assistant helper files. `toiljs create` writes a small pointer file for each tool at the
+ * project root (committed, yours to edit); the real documentation lives under `.toil/docs/`,
+ * regenerated on every `toiljs dev` / `toiljs build` so it stays in sync with the installed
+ * toiljs version. The pointer files just tell the agent to read `.toil/docs/`.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Shared body for the per-tool pointer files. */
+const POINTER_BODY = `# toiljs · AI assistant guide
+
+This is a **toiljs** project — a full-stack React framework (React + Vite client, file-based
+routing, and a toilscript→WebAssembly server).
+
+**Before editing this project, read the generated documentation in \`.toil/docs/\`.** It describes
+the conventions you must follow:
+
+- \`.toil/docs/index.md\` — overview and project layout
+- \`.toil/docs/routing.md\` — file-based routing, nested layouts, loading / error files
+- \`.toil/docs/client.md\` — the \`Toil\` global, Link / NavLink, router hooks
+- \`.toil/docs/styling.md\` — CSS / Sass / Less / Stylus / Tailwind (via \`toiljs configure\`)
+- \`.toil/docs/server.md\` — the toilscript server target
+- \`.toil/docs/cli.md\` — toiljs CLI commands
+
+\`.toil/docs/\` is regenerated by toiljs; do not edit it by hand. This pointer file is yours to edit.
+`;
+
+/** A selectable AI coding-tool helper: its id, label, and the root pointer file(s) it scaffolds. */
+export interface AiHelper {
+    readonly id: string;
+    readonly label: string;
+    readonly files: Record<string, string>;
+}
+
+/**
+ * Per-tool pointer files, individually selectable in `toiljs create`. Each tool reads its own
+ * conventional file: Claude Code → CLAUDE.md, Codex / others → AGENTS.md, Cursor → .cursor/rules,
+ * GitHub Copilot → .github/copilot-instructions.md. Written once by `create`; not regenerated.
+ */
+export const AI_HELPERS: readonly AiHelper[] = [
+    { id: 'claude', label: 'Claude Code (CLAUDE.md)', files: { 'CLAUDE.md': POINTER_BODY } },
+    { id: 'codex', label: 'Codex / AGENTS.md', files: { 'AGENTS.md': POINTER_BODY } },
+    {
+        id: 'cursor',
+        label: 'Cursor (.cursor/rules)',
+        files: {
+            '.cursor/rules/toiljs.mdc': `---\ndescription: toiljs project conventions\nalwaysApply: true\n---\n\n${POINTER_BODY}`,
+        },
+    },
+    {
+        id: 'copilot',
+        label: 'GitHub Copilot (.github/copilot-instructions.md)',
+        files: { '.github/copilot-instructions.md': POINTER_BODY },
+    },
+];
+
+/** All AI helper ids (the default selection). */
+export const AI_HELPER_IDS: readonly string[] = AI_HELPERS.map((h) => h.id);
+
+/** Merges the pointer files for the given helper ids into one path → content map. */
+export function aiHelperFiles(ids: readonly string[]): Record<string, string> {
+    const out: Record<string, string> = {};
+    for (const helper of AI_HELPERS) {
+        if (ids.includes(helper.id)) Object.assign(out, helper.files);
+    }
+    return out;
+}
+
+/** The framework docs written into `.toil/docs/` (placeholders for now), keyed by filename. */
+export const TOIL_DOCS: Record<string, string> = {
+    'index.md': '# toiljs\n\n<!-- TODO: overview and project layout -->\n',
+    'routing.md': '# Routing\n\n<!-- TODO: file-based routing, nested layouts, loading / error -->\n',
+    'client.md': '# Client runtime\n\n<!-- TODO: Toil global, Link / NavLink, router hooks -->\n',
+    'styling.md': '# Styling\n\n<!-- TODO: CSS / preprocessors / Tailwind via `toiljs configure` -->\n',
+    'server.md': '# Server (toilscript → WebAssembly)\n\n<!-- TODO -->\n',
+    'cli.md': '# CLI\n\n<!-- TODO: create / dev / build / start / configure -->\n',
+};
+
+/** Writes the framework docs into `<toilDir>/docs/`. Called by `generate` each dev/build. */
+export function writeDocs(toilDir: string): void {
+    const dir = path.join(toilDir, 'docs');
+    fs.mkdirSync(dir, { recursive: true });
+    for (const [name, content] of Object.entries(TOIL_DOCS)) {
+        fs.writeFileSync(path.join(dir, name), content);
+    }
+}

package/src/compiler/generate.ts

@@ -2,6 +2,7 @@ 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';
 
 /**
@@ -12,16 +13,52 @@ import { scanRoutes, type ScannedRoute } from './routes.js';
  * 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` +
+    `declare const Toil: typeof import('toiljs/client');\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`;
+    `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` +
+    `}\n`;
 
-/** Returns a `./`-prefixed POSIX path from the `.toil` dir to `abs`, for use in generated imports. */
+/**
+ * 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, '/');
+    let rel = path.relative(cfg.toilDir, abs).replace(/\\/g, '/').replace(/\.(tsx|jsx)$/, '');
     if (!rel.startsWith('.')) rel = './' + rel;
     return rel;
 }
@@ -39,8 +76,57 @@ function findNotFound(cfg: ResolvedToilConfig): string | undefined {
         .find((p) => fs.existsSync(p));
 }
 
+/** 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 `layout.{tsx,jsx}` in `dir`, or undefined. */
+function layoutIn(dir: string): string | undefined {
+    return ['layout.tsx', 'layout.jsx']
+        .map((name) => path.join(dir, name))
+        .find((p) => fs.existsSync(p));
+}
+
+/**
+ * Nested layout chain for a route file: `layout.{tsx,jsx}` at the routes root and each ancestor
+ * directory down to the file's own, shallowest → deepest. (The project root `client/layout.tsx`
+ * is handled separately as the top-level layout.)
+ */
+function findLayoutChain(cfg: ResolvedToilConfig, routeFile: string): string[] {
+    const relDir = path.dirname(path.relative(cfg.routesAbsDir, routeFile));
+    const segments = relDir === '.' ? [] : relDir.split(path.sep);
+    const chain: string[] = [];
+    let dir = cfg.routesAbsDir;
+    for (let i = 0; i <= segments.length; i++) {
+        if (i > 0) dir = path.join(dir, segments[i - 1]);
+        const layout = layoutIn(dir);
+        if (layout) chain.push(layout);
+    }
+    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, HTML) and returns the scanned
+ * 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[] {
@@ -50,40 +136,111 @@ export function generate(cfg: ResolvedToilConfig): ScannedRoute[] {
     const layoutFile = findLayout(cfg);
     const notFoundFile = findNotFound(cfg);
     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` +
         routes
-            .map(
-                (r) =>
-                    `  { pattern: ${JSON.stringify(r.pattern)}, load: () => import(${JSON.stringify(relFromToil(cfg, r.file))}) },`,
-            )
+            .map((r) => {
+                const imp = (f: string): string => `() => import(${JSON.stringify(relFromToil(cfg, f))})`;
+                const layouts = findLayoutChain(cfg, r.file).map(imp).join(', ');
+                const parts = [
+                    `pattern: ${JSON.stringify(r.pattern)}`,
+                    `load: ${imp(r.file)}`,
+                    `layouts: [${layouts}]`,
+                ];
+                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)}`);
+                return `  { ${parts.join(', ')} },`;
+            })
             .join('\n') +
         `\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`;
     fs.writeFileSync(path.join(cfg.toilDir, 'routes.ts'), routesSrc);
 
-    const entrySrc =
+    const globalsSrc =
+        `// @ts-nocheck\n` +
         `// AUTO-GENERATED by toil — do not edit.\n` +
-        `import { mount } from 'toiljs/client';\n` +
-        `import { BinaryWriter, BinaryReader, FastMap, FastSet } from 'toiljs/io';\n` +
-        `import { routes, layout, notFound } from './routes';\n\n` +
-        `// Expose toiljs IO as native globals (typed via ./toil-env.d.ts).\n` +
-        `Object.assign(globalThis, { BinaryWriter, BinaryReader, FastMap, FastSet });\n\n` +
-        `mount(routes, layout, notFound);\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`;
+    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 } from './routes';\n\n` +
+          `mount(routes, layout, notFound);\n`;
     fs.writeFileSync(path.join(cfg.toilDir, 'entry.tsx'), entrySrc);
 
-    // Ambient global types (see TOIL_ENV_DTS). Regenerated each dev/build; also written by
-    // `toiljs create` so a fresh project type-checks before its first build.
     fs.writeFileSync(path.join(cfg.root, 'toil-env.d.ts'), TOIL_ENV_DTS);
 
-    const htmlSrc =
-        `<!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` +
-        `    <title>Toil App</title>\n  </head>\n  <body>\n    <div id="root"></div>\n` +
-        `    <script type="module" src="./entry.tsx"></script>\n  </body>\n</html>\n`;
-    fs.writeFileSync(path.join(cfg.toilDir, 'index.html'), htmlSrc);
+    fs.writeFileSync(path.join(cfg.toilDir, 'index.html'), buildHtml(cfg));
+    syncPublicAssets(cfg);
+    writeDocs(cfg.toilDir);
 
     return routes;
 }
+
+/** 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 });
+}

package/src/compiler/index.ts

@@ -17,7 +17,7 @@ export interface ToilCommandOptions {
 export async function dev(opts: ToilCommandOptions = {}): Promise<ViteDevServer> {
     const cfg = await loadConfig(opts);
     generate(cfg);
-    const server = await createServer(createViteConfig(cfg));
+    const server = await createServer(await createViteConfig(cfg));
     await server.listen();
     server.printUrls();
     return server;
@@ -27,7 +27,7 @@ export async function dev(opts: ToilCommandOptions = {}): Promise<ViteDevServer>
 export async function build(opts: ToilCommandOptions = {}): Promise<void> {
     const cfg = await loadConfig(opts);
     generate(cfg);
-    await viteBuild(createViteConfig(cfg));
+    await viteBuild(await createViteConfig(cfg));
 }
 
 /**
@@ -44,7 +44,9 @@ export async function start(opts: ToilCommandOptions = {}): Promise<RunningBacke
     return startBackend({ root: outDir, port: cfg.port });
 }
 
-export { defineConfig } from './config.js';
+export { defineConfig, loadConfig } from './config.js';
 export { TOIL_ENV_DTS } from './generate.js';
-export type { ToilConfig } from './config.js';
+export { AI_HELPERS, AI_HELPER_IDS, aiHelperFiles, TOIL_DOCS } from './docs.js';
+export type { AiHelper } from './docs.js';
+export type { ToilConfig, ResolvedToilConfig } from './config.js';
 export type { RunningBackend, BackendOptions } from 'toiljs/backend';

package/src/compiler/plugin.ts

@@ -11,9 +11,30 @@ import { generate } from './generate.js';
 export function toilPlugin(cfg: ResolvedToilConfig): Plugin {
     return {
         name: 'toil',
+        // Catch empty import specifiers in source and report the file — rolldown otherwise fails
+        // resolution with a cryptic "The specifiers must be a non-empty string. Received ''".
+        transform(code, id) {
+            const file = id.split('?')[0];
+            if (id.includes('\0') || file.includes('/node_modules/') || !/\.[mc]?[jt]sx?$/.test(file)) {
+                return null;
+            }
+            const empty =
+                /^[ \t]*import\s+(['"])\1\s*;?[ \t]*$/m.test(code) ||
+                /^[ \t]*import\b[^'"\n]*\bfrom\s+(['"])\1/m.test(code) ||
+                /^[ \t]*export\b[^'"\n]*\bfrom\s+(['"])\1/m.test(code) ||
+                /\bimport\s*\(\s*(['"])\1\s*\)/.test(code);
+            if (empty) {
+                throw new Error(
+                    `toil: empty import specifier (e.g. \`import '';\`) in ${file} — remove or complete the import.`,
+                );
+            }
+            return null;
+        },
         configureServer(server) {
+            // Trailing slash so a sibling like `routes-extra/` doesn't match the `routes/` prefix.
+            const routesPrefix = cfg.routesAbsDir.replace(/\\/g, '/').replace(/\/?$/, '/');
             const onChange = (file: string): void => {
-                if (file.replace(/\\/g, '/').startsWith(cfg.routesAbsDir.replace(/\\/g, '/'))) {
+                if (file.replace(/\\/g, '/').startsWith(routesPrefix)) {
                     generate(cfg);
                     server.ws.send({ type: 'full-reload' });
                 }

package/src/compiler/routes.ts

@@ -8,14 +8,18 @@ export interface ScannedRoute {
 }
 
 const ROUTE_EXT = /\.(tsx|jsx)$/;
+/** Special files that live alongside routes but are not themselves pages. */
+const SPECIAL_FILE = /^(layout|loading|error|404|not-found)\.(tsx|jsx)$/;
 
 /**
  * Derives a route pattern from a route file path (relative to the routes dir).
  *   index.tsx          -> /
  *   about.tsx          -> /about
  *   blog/index.tsx     -> /blog
- *   blog/[id].tsx      -> /blog/:id
- *   docs/[...slug].tsx -> /docs/*slug   (catch-all)
+ *   blog/[id].tsx        -> /blog/:id
+ *   docs/[...slug].tsx   -> /docs/*slug    (catch-all)
+ *   docs/[[...slug]].tsx -> /docs/**slug   (optional catch-all)
+ *   (marketing)/about.tsx -> /about        (route group: parens add no URL segment)
  */
 export function filePathToRoute(relPath: string): string {
     const withoutExt = relPath.replace(/\\/g, '/').replace(ROUTE_EXT, '');
@@ -23,11 +27,13 @@ export function filePathToRoute(relPath: string): string {
     const out: string[] = [];
     for (let i = 0; i < segments.length; i++) {
         const segment = segments[i];
+        if (/^\(.+\)$/.test(segment)) continue;
         if (segment === 'index' && i === segments.length - 1) continue;
         out.push(
             segment
-                .replace(/^\[\.\.\.(.+)\]$/, '*$1') // catch-all [...slug] -> *slug
-                .replace(/^\[(.+)\]$/, ':$1'), // dynamic [id] -> :id
+                .replace(/^\[\[\.\.\.(.+)\]\]$/, '**$1')
+                .replace(/^\[\.\.\.(.+)\]$/, '*$1')
+                .replace(/^\[(.+)\]$/, ':$1'),
         );
     }
     return '/' + out.join('/');
@@ -41,8 +47,8 @@ function specificity(pattern: string): number {
     const segments = pattern.split('/').filter(Boolean);
     let score = segments.length * 10;
     for (const segment of segments) {
-        if (segment.startsWith('*')) score -= 5; // catch-all: lowest
-        else if (!segment.startsWith(':')) score += 5; // static: highest
+        if (segment.startsWith('*')) score -= 5;
+        else if (!segment.startsWith(':')) score += 5;
     }
     return score;
 }
@@ -56,7 +62,7 @@ export function scanRoutes(routesDir: string): ScannedRoute[] {
             const full = path.join(dir, entry.name);
             if (entry.isDirectory()) {
                 walk(full);
-            } else if (ROUTE_EXT.test(entry.name)) {
+            } else if (ROUTE_EXT.test(entry.name) && !SPECIAL_FILE.test(entry.name)) {
                 found.push({
                     file: full,
                     pattern: filePathToRoute(path.relative(routesDir, full)),