toiljs 0.0.115 → 0.0.117

package/src/compiler/generate.ts

@@ -1,471 +0,0 @@
-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 { type ScannedRoute, scanRoutes } from './routes.js';
-import { llmsTxt, robotsTxt, sitemapXml } from './seo.js';
-
-/**
- * Contents of the root `toil-env.d.ts`: ambient global types so `new DataWriter()` 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');
-
-/**
- * Types for vite-imagetools query imports (e.g. `import src from './hero.png?w=800&as=srcset'`).
- * Declared inline rather than via `/// <reference types="vite-imagetools/client" />` because
- * vite-imagetools v10 ships no `client` types entry, and the package lives in toiljs's own
- * node_modules (unresolvable from a symlinked consumer). One `*` wildcard each, matching any
- * specifier ending in the directive.
- */
-const IMAGETOOLS_MODULES = [
-    `declare module '*as=srcset' {\n    const src: string;\n    export default src;\n}`,
-    `declare module '*as=url' {\n    const src: string;\n    export default src;\n}`,
-    `declare module '*as=metadata' {\n    const metadata: { src: string; width?: number; height?: number; format?: string }[];\n    export default metadata;\n}`,
-    // `import hero from './hero.webp?toil'` -> a Toil.Image source carrying an auto-generated blur LQIP
-    // and intrinsic size (see compiler/image-blur.ts). Pass it straight to `<Toil.Image src={hero} />`.
-    `declare module '*?toil' {\n    const image: { src: string; width: number; height: number; blurDataURL: string };\n    export default image;\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 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 GenerateStaticParams = import('toiljs/client').GenerateStaticParams;\n` +
-    `    type StaticParams = import('toiljs/client').StaticParams;\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 FastMap: typeof import('toiljs/io').FastMap;\n` +
-    `declare const FastSet: typeof import('toiljs/io').FastSet;\n` +
-    `declare const DataWriter: typeof import('toiljs/io').DataWriter;\n` +
-    `declare const DataReader: typeof import('toiljs/io').DataReader;\n` +
-    `declare const parseError: typeof import('toiljs/client').parseError;\n` +
-    `\n` +
-    `${STYLE_MODULES}\n` +
-    `\n` +
-    `${ASSET_MODULES}\n` +
-    `\n` +
-    `${IMAGETOOLS_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`;
-
-/**
- * Contents of `<serverDir>/toil-server-env.d.ts`: editor-only ambient
- * declarations for the toiljs server-runtime globals. ALIASES the real runtime
- * types (the same trick the IO globals use above), so a global-built `Cookie`
- * is the exact type the runtime APIs (`Response.setCookie`, `SecureCookies.seal`)
- * expect; redeclaring them as standalone classes makes a second, nominally-
- * incompatible `Cookie` (private fields). Regenerated by `buildServer` on every
- * build/dev so existing projects auto-migrate. Keep the declarations in sync
- * with the `toiljs create` scaffold (`src/cli/create.ts`).
- */
-export const TOIL_SERVER_ENV_DTS =
-    `// AUTO-GENERATED by toil, do not edit. Editor-only ambient declarations for\n` +
-    `// the toiljs server-runtime globals (Cookie, Cookies, SecureCookies, the\n` +
-    `// cookie enums): @global in the runtime, used with no import. These alias the\n` +
-    `// real runtime types so a global-built Cookie is exactly what Response.setCookie\n` +
-    `// / SecureCookies.seal expect. The toilscript compiler registers them itself.\n` +
-    `declare const SameSite: typeof import('toiljs/server/runtime/http/cookie').SameSite;\n` +
-    `type SameSite = import('toiljs/server/runtime/http/cookie').SameSite;\n` +
-    `declare const CookieEncoding: typeof import('toiljs/server/runtime/http/cookie').CookieEncoding;\n` +
-    `type CookieEncoding = import('toiljs/server/runtime/http/cookie').CookieEncoding;\n` +
-    `declare const CookiePrefix: typeof import('toiljs/server/runtime/http/cookie').CookiePrefix;\n` +
-    `type CookiePrefix = import('toiljs/server/runtime/http/cookie').CookiePrefix;\n` +
-    `declare const CookieValidation: typeof import('toiljs/server/runtime/http/cookie').CookieValidation;\n` +
-    `type CookieValidation = import('toiljs/server/runtime/http/cookie').CookieValidation;\n` +
-    `declare const Cookie: typeof import('toiljs/server/runtime/http/cookie').Cookie;\n` +
-    `type Cookie = import('toiljs/server/runtime/http/cookie').Cookie;\n` +
-    `declare const CookieMap: typeof import('toiljs/server/runtime/http/cookies').CookieMap;\n` +
-    `type CookieMap = import('toiljs/server/runtime/http/cookies').CookieMap;\n` +
-    `declare const Cookies: typeof import('toiljs/server/runtime/http/cookies').Cookies;\n` +
-    `type Cookies = import('toiljs/server/runtime/http/cookies').Cookies;\n` +
-    `declare const SecureCookies: typeof import('toiljs/server/runtime/http/securecookies').SecureCookies;\n` +
-    `type SecureCookies = import('toiljs/server/runtime/http/securecookies').SecureCookies;\n` +
-    `declare const Time: typeof import('toiljs/server/runtime/time').Time;\n` +
-    `// Email, rate-limit, 2FA, and auth globals (server/globals/*), hand-declared\n` +
-    `// because their AssemblyScript source can't be type-aliased from tsc.\n` +
-    `declare enum EmailStatus { Sent, Disabled, Budget, RecipientCapped, Deduped, TryLater, BadRecipient, ProviderError }\n` +
-    `declare namespace EmailService { function send(to: string, subject: string, body: string, purpose?: string, html?: string): EmailStatus; }\n` +
-    `declare class RenderedEmail { subject: string; body: string; html: string; constructor(subject: string, body: string, html: string); }\n` +
-    `declare class EmailTemplate { constructor(subject: string, body: string, html?: string); render(vars: Map<string, string>): RenderedEmail; send(to: string, vars: Map<string, string>, purpose?: string): EmailStatus; }\n` +
-    // `RateLimit` (the @ratelimit strategy enum) is declared by toilscript's std d.ts,
-    // which owns the @ratelimit decorator; declaring it here too would collide.
-    `declare namespace RateLimitService { function guard(routeId: i32, strategy: i32, limit: i32, window: i32): import('toiljs/server/runtime/response').Response | null; function guardKeyed(routeId: i32, strategy: i32, limit: i32, window: i32, key: string): import('toiljs/server/runtime/response').Response | null; }\n` +
-    `declare namespace Environment { function get(key: string): string | null; function getSecure(key: string): string | null; }\n` +
-    `declare class TwoFactorIssue { code: string; token: string; constructor(code: string, token: string); }\n` +
-    `declare class TwoFactorChallenge { token: string; status: EmailStatus; constructor(token: string, status: EmailStatus); }\n` +
-    `declare namespace TwoFactor { const DEFAULT_TTL_SECS: u64; const DEFAULT_DIGITS: i32; function setSecret(secret: Uint8Array): void; function issue(recipient: string, purpose: string, ttlSecs?: u64, digits?: i32): TwoFactorIssue; function send(recipient: string, purpose: string, ttlSecs?: u64, digits?: i32): TwoFactorChallenge; function verify(token: string, recipient: string, code: string): bool; }\n` +
-    `declare namespace AuthService { const SESSION_COOKIE: string; const USER_COOKIE: string; const LOGIN_CONTEXT: string; const PUBLIC_KEY_LEN: i32; const SIGNATURE_LEN: i32; const DEFAULT_SESSION_TTL_SECS: u64; function setSecret(secret: Uint8Array): void; function hasSession(): bool; function getSessionBytes(): Uint8Array | null; function getUser(): __ToilAuthUser | null; function userId(): ToilUserId | null; function enable(): void; function mintSession(userData: Uint8Array, ttlSecs?: u64): Cookie; function clearSession(): Cookie; function userCookie(userData: Uint8Array, ttlSecs?: u64): Cookie; function clearUserCookie(): Cookie; function buildLoginMessage(sub: string, aud: string, cid: Uint8Array, nonce: Uint8Array, iat: u64, exp: u64, ciphertext: Uint8Array, memKiB: u32, iterations: u32, parallelism: u32, serverKemKeyId: Uint8Array): Uint8Array; function verifyLogin(publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): bool; const KEM_CIPHERTEXT_LEN: i32; const KEM_SECRET_KEY_LEN: i32; const KEM_PUBLIC_KEY_LEN: i32; const SHARED_SECRET_LEN: i32; const OPRF_ELEMENT_LEN: i32; const OPRF_SEED_LEN: i32; const SESSION_KEY_LABEL: string; const SERVER_CONFIRM_LABEL: string; function setOprfSeed(seed: Uint8Array): void; function setServerKemSecretKey(secretKey: Uint8Array): void; function setServerKemPublicKey(publicKey: Uint8Array): void; function serverKemKeyId(): Uint8Array; function oprfEvaluate(username: string, blinded: Uint8Array): Uint8Array; function mlkemDecapsulate(ciphertext: Uint8Array): Uint8Array; function sha256(data: Uint8Array): Uint8Array; function deriveSessionKey(sharedSecret: Uint8Array, transcriptHash: Uint8Array): Uint8Array; function serverConfirmTag(sessionKey: Uint8Array, transcriptHash: Uint8Array): Uint8Array; const REGISTER_CONTEXT: string; function buildRegisterMessage(username: string, publicKey: Uint8Array): Uint8Array; function verifyRegister(publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): bool; }\n` +
-    `interface __ToilAuthUser {}\n` +
-    `declare class ToilUserId { w0: u64; w1: u64; w2: u64; w3: u64; constructor(w0?: u64, w1?: u64, w2?: u64, w3?: u64); static derive(mldsaPublicKey: Uint8Array, identifier: string, domain: string): ToilUserId; static fromBytes(b: Uint8Array): ToilUserId; toBytes(): Uint8Array; toHex(): string; isZero(): bool; equals(other: ToilUserId): bool; }\n` +
-    // Built-in auth (server.auth): injected by --authUser. Mints a session for the program's single @user
-    // (built-in or the app's extended one): constructs it, sets the reserved identity, encodes it.
-    `declare function __toilEncodeAuthUser(toilUserId: Uint8Array, username: string): Uint8Array;\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;
-}
-
-export 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).
- */
-export 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 { FastMap, FastSet, DataWriter, DataReader } from 'toiljs/io';\n` +
-        `import { pages } from './routes';\n\n` +
-        `Object.assign(globalThis, { Toil, FastMap, FastSet, DataWriter, DataReader, Server: Toil.Server, parseError: Toil.parseError });\n` +
-        `Toil.setViewTransitions(${String(cfg.viewTransitions)});\n` +
-        `Toil.setTransitions(${String(cfg.transitions)});\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>`;
-
-/** Toil's component base CSS, baked into the shell `<head>` so built-in components (the `Image`
- * `fill`/blur layout) style via overridable classes instead of forced-inline styles, and stay
- * SSR-safe (present before JS). The app can restyle `.toil-img-*` freely. */
-const TOIL_BASE_STYLE =
-    `<style id="toil-base">` +
-    `.toil-img-fill-box{display:block;overflow:hidden}` +
-    `.toil-img-fill{display:block;width:100%;height:100%;object-fit:cover}` +
-    `.toil-img-blur{background-size:cover;background-position:center;filter:blur(20px)}` +
-    `.toil-img-skeleton{background:linear-gradient(90deg,#ececed 25%,#f4f4f5 37%,#ececed 63%);background-size:400% 100%;animation:toil-img-shimmer 1.4s ease infinite}` +
-    `@keyframes toil-img-shimmer{0%{background-position:100% 50%}100%{background-position:0 50%}}` +
-    `@media (prefers-reduced-motion:reduce){.toil-img-skeleton{animation:none}}` +
-    `</style>`;
-
-/**
- * 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`;
-    }
-    // Ship toil's component base CSS once, so `Image` `fill`/blur lay out via overridable classes
-    // instead of inline styles. Idempotent (keyed on the `toil-base` id).
-    if (!html.includes('id="toil-base"')) {
-        html = html.includes('</head>')
-            ? html.replace('</head>', `    ${TOIL_BASE_STYLE}\n  </head>`)
-            : `${TOIL_BASE_STYLE}\n${html}`;
-    }
-    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/image-blur.ts

@@ -1,42 +0,0 @@
-import type { Plugin } from 'vite';
-
-/** An image import carrying the `?toil` flag: `import hero from './hero.webp?toil'`. */
-const TOIL_QUERY = /[?&]toil(?:&|$)/;
-/** Raster formats sharp can downscale into an LQIP. (SVG/animated stay as-is — no blur.) */
-const RASTER = /\.(?:png|jpe?g|webp|avif|gif|tiff?)(?:\?|$)/i;
-
-/**
- * Auto-generates a tiny blurred base64 LQIP (low-quality image placeholder) for raster images imported
- * with the `?toil` flag, and returns a `{ src, width, height, blurDataURL }` object that `Toil.Image`
- * consumes to auto-fill its `blurDataURL` (`placeholder="blur"`) and its aspect-ratio — the way Next.js
- * bakes a `blurDataURL` for static image imports. Runs in dev and build (Vite `load`); `sharp` is loaded
- * lazily so it only costs anything when a `?toil` import is actually resolved.
- *
- * Usage: `import hero from './hero.webp?toil'` then `<Toil.Image src={hero} placeholder="blur" />`.
- * The bare `src` is re-imported with no query, so Vite/imagetools still optimize + hash the real asset
- * (this plugin only adds the placeholder + intrinsic size); it skips itself on that bare import.
- */
-export function imageBlurPlugin(): Plugin {
-    return {
-        name: 'toil:image-blur',
-        enforce: 'pre',
-        async load(id) {
-            if (!TOIL_QUERY.test(id) || !RASTER.test(id)) return undefined;
-            const file = id.replace(/\?.*$/, '');
-            const { default: sharp } = await import('sharp');
-            const meta = await sharp(file).metadata();
-            // ~24px longest edge, blurred, webp — a few hundred base64 bytes, inlined as a data URI.
-            const lqip = await sharp(file)
-                .resize(24, 24, { fit: 'inside' })
-                .blur()
-                .webp({ quality: 40 })
-                .toBuffer();
-            const blurDataURL = `data:image/webp;base64,${lqip.toString('base64')}`;
-            return (
-                `import src from ${JSON.stringify(file)};\n` +
-                `export default { src, width: ${meta.width ?? 0}, height: ${meta.height ?? 0}, ` +
-                `blurDataURL: ${JSON.stringify(blurDataURL)} };\n`
-            );
-        },
-    };
-}

package/src/compiler/image-report.ts

@@ -1,88 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-
-import pc from 'picocolors';
-import type { Logger, Plugin } from 'vite';
-
-/** Raster/vector outputs the image pipeline may emit. */
-const IMAGE_RE = /\.(png|jpe?g|webp|avif|gif|tiff|svg)$/i;
-
-/** Formats a byte count like Vite's asset table (kB, base 1000). */
-function kb(bytes: number): string {
-    return `${(bytes / 1000).toFixed(2)} kB`;
-}
-
-interface Variant {
-    readonly out: string;
-    readonly outSize: number;
-}
-
-/**
- * Build-only plugin that reports which imported images the pipeline optimized, each source image,
- * its emitted variant(s), and the size saved. `public/` assets (copied as-is) never enter the
- * bundle, so they don't appear here. Logs nothing when no images were processed.
- *
- * `viteRoot` is Vite's root (the `.toil` dir) that emitted assets' `originalFileNames` are relative
- * to; `projectRoot` is used only to print friendly source paths.
- */
-export function imageReportPlugin(projectRoot: string, viteRoot: string): Plugin {
-    let logger: Logger | undefined;
-    return {
-        name: 'toil:image-report',
-        apply: 'build',
-        configResolved(config) {
-            logger = config.logger;
-        },
-        writeBundle(_options, bundle) {
-            // Group emitted image assets by their source file.
-            const bySource = new Map<
-                string,
-                { label: string; inSize: number | null; variants: Variant[] }
-            >();
-            for (const file of Object.values(bundle)) {
-                if (file.type !== 'asset' || !IMAGE_RE.test(file.fileName)) continue;
-                const source = file.originalFileNames[0];
-                const key = source ?? file.fileName;
-                const outSize =
-                    typeof file.source === 'string'
-                        ? Buffer.byteLength(file.source)
-                        : file.source.byteLength;
-
-                let entry = bySource.get(key);
-                if (!entry) {
-                    let inSize: number | null = null;
-                    let label = '(generated)';
-                    if (source !== undefined) {
-                        const abs = path.resolve(viteRoot, source);
-                        label = path.relative(projectRoot, abs);
-                        try {
-                            inSize = fs.statSync(abs).size;
-                        } catch {
-                            inSize = null;
-                        }
-                    }
-                    entry = { label, inSize, variants: [] };
-                    bySource.set(key, entry);
-                }
-                entry.variants.push({ out: file.fileName, outSize });
-            }
-
-            if (bySource.size === 0 || !logger) return;
-
-            const count = bySource.size;
-            logger.info('');
-            logger.info(pc.green(`  ✓ optimized ${String(count)} image${count === 1 ? '' : 's'}`));
-            for (const { label, inSize, variants } of bySource.values()) {
-                logger.info(`  ${pc.dim(label)}`);
-                for (const v of variants) {
-                    const saved =
-                        inSize && inSize > 0
-                            ? pc.green(`  -${String(Math.round((1 - v.outSize / inSize) * 100))}%`)
-                            : '';
-                    const from = inSize ? `${kb(inSize)} → ` : '';
-                    logger.info(`    ${pc.dim('→')} ${v.out}  ${from}${kb(v.outSize)}${saved}`);
-                }
-            }
-        },
-    };
-}