toiljs 0.0.3 → 0.0.5

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;
@@ -87,10 +95,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 +112,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,11 +2,47 @@ 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';
 
-/** Returns a `./`-prefixed POSIX path from the `.toil` dir to `abs`, for use in generated imports. */
+/**
+ * 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.
+ */
+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` +
+    `\n` +
+    `declare module '*.css' {}\n` +
+    `declare module '*.scss' {}\n` +
+    `declare module '*.sass' {}\n` +
+    `declare module '*.less' {}\n` +
+    `declare module '*.styl' {}\n` +
+    `declare module '*.stylus' {}\n` +
+    `declare module '*.pcss' {}\n` +
+    `declare module '*.sss' {}\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, **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;
 }
@@ -24,8 +60,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));
+}
+
 /**
- * Generates the `.toil/` working dir (routes table, mount entry, HTML) and returns the scanned
+ * 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, 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[] {
@@ -35,49 +120,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 so `new BinaryWriter()` etc. resolve in the IDE without an import.
-    // Script-mode declaration file (no top-level import/export → the `declare const`s are truly
-    // global, and it's not a module so it can't confuse ESLint's project service). The inline
-    // `import('toiljs/io')` type only needs the normal `toiljs/io` export to resolve. At the
-    // project root because TypeScript's `include` globs skip dot-directories (so it can't live in .toil).
-    const envSrc =
-        `// AUTO-GENERATED by toil — do not edit.\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`;
-    fs.writeFileSync(path.join(cfg.root, 'toil-env.d.ts'), envSrc);
-
-    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.root, 'toil-env.d.ts'), TOIL_ENV_DTS);
+
+    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,6 +44,9 @@ export async function start(opts: ToilCommandOptions = {}): Promise<RunningBacke
     return startBackend({ root: outDir, port: cfg.port });
 }
 
-export { defineConfig } from './config.js';
-export type { ToilConfig } from './config.js';
+export { defineConfig, loadConfig } from './config.js';
+export { TOIL_ENV_DTS } from './generate.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

@@ -12,8 +12,10 @@ export function toilPlugin(cfg: ResolvedToilConfig): Plugin {
     return {
         name: 'toil',
         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)),

package/src/compiler/vite.ts

@@ -1,8 +1,10 @@
+import { createRequire } from 'node:module';
 import path from 'node:path';
+import { pathToFileURL } from 'node:url';
 
 import react from '@vitejs/plugin-react';
 import { nodePolyfills } from 'vite-plugin-node-polyfills';
-import { mergeConfig, type InlineConfig } from 'vite';
+import { mergeConfig, type InlineConfig, type PluginOption } from 'vite';
 
 import { type ResolvedToilConfig } from './config.js';
 import { toilPlugin } from './plugin.js';
@@ -21,6 +23,23 @@ function assetFileName(name: string): string {
     return 'assets/[name][extname]';
 }
 
+/**
+ * Loads the Tailwind v4 Vite plugin if the project has `@tailwindcss/vite` installed (added by
+ * `toiljs create`/`configure` when Tailwind is enabled). Resolved from the project root so it picks
+ * up the project's copy; returns `undefined` when Tailwind is off, so the plugin simply isn't added.
+ */
+async function tailwindPlugin(root: string): Promise<PluginOption | undefined> {
+    let resolved: string;
+    try {
+        resolved = createRequire(path.join(root, 'package.json')).resolve('@tailwindcss/vite');
+    } catch {
+        return undefined;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- dynamic import() is typed any
+    const mod: { default?: () => PluginOption } = await import(pathToFileURL(resolved).href);
+    return mod.default?.();
+}
+
 /** Splits React's runtime into its own long-lived chunk for better caching. */
 function manualChunks(id: string): string | undefined {
     if (!id.includes('node_modules')) return undefined;
@@ -36,21 +55,24 @@ function manualChunks(id: string): string | undefined {
 
 /**
  * Builds the framework-owned Vite config. Vite's `root` is the generated `.toil` dir so its
- * `index.html` emits at the output root (assets resolve correctly); `fs.allow` opens the
- * project (for `client/`) and the framework runtime. The opinionated default — Node polyfills
+ * `index.html` (built from the project's `public/index.html` template) emits at the output root
+ * with assets resolving correctly; static `public/` assets are mirrored to `.toil/public` and
+ * picked up via Vite's default publicDir. `fs.allow` opens the project (for `client/`) and the
+ * framework runtime. The opinionated default — Node polyfills
  * (Buffer/global/process), React plugin, toil route plugin, typed asset folders, React chunk
  * splitting and tuned build options — is applied here; `toiljs/client` is aliased to the
  * runtime, and the user's `client.vite` overrides deep-merge on top.
  */
-export function createViteConfig(cfg: ResolvedToilConfig): InlineConfig {
-    // .../build/client/index.js -> framework package root (covers build/ + node_modules in dev)
+export async function createViteConfig(cfg: ResolvedToilConfig): Promise<InlineConfig> {
     const frameworkRoot = path.resolve(path.dirname(cfg.runtimePath), '..', '..');
+    const tailwind = await tailwindPlugin(cfg.root);
 
     const base: InlineConfig = {
         root: cfg.toilDir,
         base: cfg.base,
         configFile: false,
         plugins: [
+            tailwind,
             nodePolyfills({ globals: { Buffer: true, global: true, process: true } }),
             react(),
             toilPlugin(cfg),
@@ -58,6 +80,7 @@ export function createViteConfig(cfg: ResolvedToilConfig): InlineConfig {
         resolve: {
             alias: {
                 'toiljs/client': cfg.runtimePath,
+                'toiljs/routes': path.join(cfg.toilDir, 'routes.ts'),
             },
             dedupe: ['react', 'react-dom'],
         },

package/src/io/BinaryReader.ts

@@ -25,7 +25,6 @@ export class BinaryReader {
         return this.buffer.byteLength;
     }
 
-    // Helpers for comparisons; unchanged
     public static stringCompare(a: string, b: string): number {
         return a.localeCompare(b);
     }
@@ -123,7 +122,6 @@ export class BinaryReader {
     public readU128(be: boolean = true): bigint {
         const raw = this.readBytes(U128_BYTE_LENGTH);
         let bytes = raw;
-        // If data was written in little-endian, we reverse before interpreting
         if (!be) {
             bytes = this.reverseBytes(raw);
         }
@@ -150,10 +148,8 @@ export class BinaryReader {
             bytes = this.reverseBytes(raw);
         }
 
-        // Construct as a 128-bit two's complement
         let value = BigInt('0x' + this.toHexString(bytes));
 
-        // If the top bit is set (sign bit in big-endian), interpret negative
         const signBitMask = 0x80;
         if ((bytes[0] as number) & signBitMask) {
             const twoTo128 = BigInt(1) << BigInt(128);
@@ -281,7 +277,7 @@ export class BinaryReader {
     }
 
     public readU8Array(): u8[] {
-        const length = this.readU16(true); // by default big-endian
+        const length = this.readU16(true);
         const result: u8[] = new Array<u8>(length);
         for (let i = 0; i < length; i++) {
             result[i] = this.readU8();