toiljs 0.0.7 → 0.0.9

package/src/client/routing/loader.ts

@@ -2,12 +2,19 @@
  * Route data loaders. A route file may export a `loader` alongside its default component; the
  * loader runs on navigation, in parallel with the route's chunk load, and the page suspends until
  * it resolves (so `loading.tsx` shows and `useNavigationPending` is true). The page reads the
- * result with `useLoaderData()`. Results are cached per navigation+URL (revalidated on each
- * navigation); `clearLoaderData()` (router.refresh) busts the cache.
+ * result with `useLoaderData<typeof loader>()`.
+ *
+ * Caching: results are cached by URL (`pathname + search`). Re-renders reuse the cached result (the
+ * loader does not re-run). Across navigations, the cache policy comes from the route's optional
+ * `export const revalidate` ({@link Revalidate}): by default the loader re-runs on every navigation;
+ * a number keeps data fresh for that many seconds; `false` caches until manual invalidation.
+ * `revalidate()` / `router.refresh()` bust the cache to force a refetch.
  */
 import { createContext, useContext, type ComponentType } from 'react';
 
-import { navigationEpoch } from '../navigation/navigation.js';
+import type { HeadSpec } from '../head/head.js';
+import { resolveMetadata, type GenerateMetadata, type Metadata } from '../head/metadata.js';
+import { refresh as rerender } from '../navigation/navigation.js';
 import type { RouteDef } from '../types.js';
 import type { RouteParams } from './match.js';
 
@@ -20,72 +27,140 @@ export interface LoaderArgs {
 /** A route `loader`: `export const loader = ({ params }) => …` (sync or async). */
 export type LoaderFunction<T = unknown> = (args: LoaderArgs) => T | Promise<T>;
 
+/**
+ * Per-route cache policy, set with `export const revalidate` in a route file:
+ * - `0` (default): re-run the loader on every navigation to the route.
+ * - a positive number: reuse cached data across navigations for that many **seconds**, then refetch.
+ * - `false`: cache indefinitely until manually invalidated (`revalidate()` / `router.refresh()`).
+ */
+export type Revalidate = number | false;
+
+/** Resolves the data type for {@link useLoaderData}: `typeof loader` → its (awaited) return, else `T`. */
+export type LoaderData<T> = T extends (...args: never[]) => infer R ? Awaited<R> : T;
+
 interface RouteModule {
     default: ComponentType;
     loader?: LoaderFunction;
+    revalidate?: Revalidate;
+    metadata?: Metadata;
+    generateMetadata?: GenerateMetadata;
 }
 interface RouteData {
     Component: ComponentType;
     data: unknown;
+    /** Resolved baseline head from the route's `metadata` / `generateMetadata`, if any. */
+    head?: HeadSpec;
 }
 interface Entry {
     status: 'pending' | 'done' | 'error';
     promise: Promise<void>;
     value?: RouteData;
     error?: unknown;
+    /** `Date.now()` when the fetch settled (`0` while pending). */
+    loadedAt: number;
+    /** Cache policy captured from the route module once loaded. */
+    revalidate: Revalidate;
+    /** Navigation epoch at which this entry was (re)fetched. */
+    epoch: number;
+    /** Whether the route exports a `loader`, a route without one has no data that can change. */
+    hasLoader: boolean;
 }
 
 const cache = new Map<string, Entry>();
-const MAX_ENTRIES = 16;
+const MAX_ENTRIES = 32;
+
+/** Cache key for a URL: path + query (hash is ignored, it never changes loader data). */
+export function loaderKey(pathname: string, search: string): string {
+    return `${pathname}${search}`;
+}
 
 /** Loads the route module and runs its loader (if any), in parallel where possible. */
-async function loadRoute(route: RouteDef, params: RouteParams): Promise<RouteData> {
+async function loadRoute(
+    route: RouteDef,
+    params: RouteParams,
+): Promise<{ data: RouteData; revalidate: Revalidate; hasLoader: boolean }> {
     const mod: RouteModule = await route.load();
     const searchParams = new URLSearchParams(
         typeof window === 'undefined' ? '' : window.location.search,
     );
     const data = mod.loader ? await mod.loader({ params, searchParams }) : undefined;
-    return { Component: mod.default, data };
+    let head: HeadSpec | undefined;
+    if (mod.generateMetadata) {
+        head = resolveMetadata(await mod.generateMetadata({ params, searchParams, data }));
+    } else if (mod.metadata) {
+        head = resolveMetadata(mod.metadata);
+    }
+    return {
+        data: { Component: mod.default, data, head },
+        revalidate: mod.revalidate ?? 0,
+        hasLoader: mod.loader != null,
+    };
 }
 
-/** Drops entries from previous navigations (and caps the cache as a backstop). */
-function prune(): void {
-    const current = `${String(navigationEpoch())}:`;
-    for (const key of cache.keys()) {
-        if (!key.startsWith(current)) cache.delete(key);
-    }
+/** Whether a settled entry must be refetched for the current navigation. */
+function isStale(entry: Entry, epoch: number): boolean {
+    if (entry.status === 'error') return true; // always retry a failed load
+    // A route with no loader has no data that can change, keep it cached so repeat navigations
+    // render synchronously (instant) instead of re-suspending and remounting on every switch.
+    if (!entry.hasLoader) return false;
+    if (entry.revalidate === false) return false; // cache forever
+    if (entry.revalidate === 0) return entry.epoch !== epoch; // refetch once per navigation
+    return Date.now() - entry.loadedAt >= entry.revalidate * 1000; // time-based staleness
+}
+
+/** Starts (and caches) a fresh fetch for `key`. */
+function startFetch(route: RouteDef, params: RouteParams, key: string, epoch: number): Entry {
+    const created: Entry = {
+        status: 'pending',
+        promise: Promise.resolve(),
+        loadedAt: 0,
+        revalidate: 0,
+        epoch,
+        hasLoader: false,
+    };
+    created.promise = loadRoute(route, params).then(
+        (result) => {
+            created.value = result.data;
+            created.revalidate = result.revalidate;
+            created.hasLoader = result.hasLoader;
+            created.loadedAt = Date.now();
+            created.status = 'done';
+        },
+        (error: unknown) => {
+            created.error = error;
+            created.loadedAt = Date.now();
+            created.status = 'error';
+        },
+    );
+    cache.set(key, created);
     while (cache.size > MAX_ENTRIES) {
         const oldest = cache.keys().next().value;
-        if (oldest === undefined) break;
+        if (oldest === undefined || oldest === key) break;
         cache.delete(oldest);
     }
+    return created;
 }
 
 /**
- * Reads (or starts) the route's module + loader data for `key`, suspending until ready. Throws the
- * loader's error so the route's `error.tsx` boundary can catch it.
+ * Reads (or starts) the route's module + loader data for the URL `key`, suspending until ready.
+ * Throws the loader's error so the route's `error.tsx` boundary can catch it. `epoch` is the current
+ * navigation epoch, used to refetch once-per-navigation under the default cache policy.
  */
-export function readRouteData(route: RouteDef, params: RouteParams, key: string): RouteData {
+export function readRouteData(
+    route: RouteDef,
+    params: RouteParams,
+    key: string,
+    epoch: number,
+): RouteData {
     let entry = cache.get(key);
-    if (!entry) {
-        const created: Entry = { status: 'pending', promise: Promise.resolve() };
-        created.promise = loadRoute(route, params).then(
-            (value) => {
-                created.value = value;
-                created.status = 'done';
-            },
-            (error: unknown) => {
-                created.error = error;
-                created.status = 'error';
-            },
-        );
-        cache.set(key, created);
-        prune();
-        entry = created;
+    if (entry && entry.status !== 'pending' && isStale(entry, epoch)) {
+        entry = undefined; // stale → drop and refetch below
     }
+    entry ??= startFetch(route, params, key, epoch);
     if (entry.status === 'pending') throw entry.promise;
     if (entry.status === 'error') throw entry.error;
-    return entry.value as RouteData;
+    if (!entry.value) throw entry.promise;
+    return entry.value;
 }
 
 /** Clears all cached loader data, so the next render re-runs loaders (used by router.refresh). */
@@ -93,10 +168,58 @@ export function clearLoaderData(): void {
     cache.clear();
 }
 
+/** Cache key for an href (relative or absolute), matching {@link loaderKey}. */
+function keyForHref(href: string): string | undefined {
+    if (typeof window === 'undefined') return undefined;
+    try {
+        const url = new URL(href, window.location.href);
+        return loaderKey(url.pathname, url.search);
+    } catch {
+        return undefined;
+    }
+}
+
+/**
+ * Invalidates cached loader data so it refetches on the next render. With no argument, clears every
+ * route; with an `href`, clears just that route's entry. Pair with a re-render (the active route
+ * refetches and suspends), see {@link revalidate}.
+ */
+export function invalidateLoaderData(href?: string): void {
+    if (href === undefined) {
+        cache.clear();
+        return;
+    }
+    const key = keyForHref(href);
+    if (key !== undefined) cache.delete(key);
+}
+
+/**
+ * Invalidates loader data and re-renders so the active route refetches. Call after a mutation to
+ * refresh the current route (`revalidate()`), or target another route by href
+ * (`revalidate('/posts')`). Usable outside React (e.g. in an event handler after a `fetch`).
+ */
+export function revalidate(href?: string): void {
+    invalidateLoaderData(href);
+    rerender();
+}
+
 /** Holds the active route's loader data; provided by the Router, read by {@link useLoaderData}. */
 export const LoaderDataContext = createContext<unknown>(undefined);
 
-/** The data returned by the active route's `loader` (`undefined` if it has none). */
-export function useLoaderData<T = unknown>(): T {
-    return useContext(LoaderDataContext) as T;
+/**
+ * The data returned by the active route's `loader`. Three ways to type it, easiest first:
+ *
+ * 1. **Pass the loader**, zero generics, fully inferred from your loader's return:
+ *    `const data = useLoaderData(loader);`
+ * 2. Pass `typeof loader` as a type argument: `useLoaderData<typeof loader>();`
+ * 3. Pass an explicit shape: `useLoaderData<Post>();`
+ *
+ * With no argument and no type, it returns `unknown` (never `any`), so the data is there at runtime,
+ * but you must annotate or narrow before using it. There's no way to infer the type from a bare call:
+ * TypeScript can't tell which file (and so which `loader`) the call belongs to, hence option 1.
+ */
+export function useLoaderData<L extends LoaderFunction>(loader: L): Awaited<ReturnType<L>>;
+export function useLoaderData<T = unknown>(): LoaderData<T>;
+export function useLoaderData(_loader?: LoaderFunction): unknown {
+    return useContext(LoaderDataContext);
 }

package/src/client/routing/mount.tsx

@@ -1,5 +1,11 @@
 import { createRoot } from 'react-dom/client';
 
+import {
+    DevErrorBoundary,
+    DevErrorOverlay,
+    initDevErrorOverlay,
+    isDevMode,
+} from '../dev/error-overlay.js';
 import { initNavigation } from '../navigation/navigation.js';
 import { startPrefetcher } from '../navigation/prefetch.js';
 import { Router } from './Router.js';
@@ -14,17 +20,33 @@ export function mount(
     layout: LayoutLoader = null,
     notFound: NotFoundLoader = null,
     globalError: ErrorComponentLoader = null,
+    slots: Record<string, RouteDef[]> = {},
 ): void {
     const el = document.getElementById('root');
     if (!el) throw new Error('toil: #root element not found');
     initNavigation();
-    createRoot(el).render(
+    const app = (
         <Router
             routes={routes}
             layout={layout}
             notFound={notFound}
             globalError={globalError}
-        />,
+            slots={slots}
+        />
     );
-    startPrefetcher(routes);
+    // In dev, wrap the app in the error overlay so uncaught render/async errors surface on screen
+    // (not a blank page). In production it's omitted entirely.
+    if (isDevMode()) {
+        initDevErrorOverlay();
+        createRoot(el).render(
+            <>
+                <DevErrorBoundary>{app}</DevErrorBoundary>
+                <DevErrorOverlay />
+            </>,
+        );
+    } else {
+        createRoot(el).render(app);
+    }
+    // Prefetch across the main tree and every slot tree (one prefetcher owns the whole table).
+    startPrefetcher([...routes, ...Object.values(slots).flat()]);
 }

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

@@ -0,0 +1,7 @@
+/**
+ * Context carrying the rendered element for each parallel-route slot (`@slot`), keyed by name.
+ * Provided by the Router for the current URL, consumed by {@link Slot}.
+ */
+import { createContext, type ReactNode } from 'react';
+
+export const SlotContext = createContext<Record<string, ReactNode>>({});

package/src/client/types.ts

@@ -12,7 +12,7 @@ import type { ComponentType, ReactNode } from 'react';
 export interface Register {}
 
 /**
- * Union of the project's route paths — static routes as literals, dynamic/catch-all as
+ * Union of the project's route paths, static routes as literals, dynamic/catch-all as
  * `` `…/${string}` `` templates. Falls back to `string` before the types are generated.
  */
 export type RoutePath = Register extends { routePath: infer P }
@@ -56,12 +56,14 @@ export interface RouteDef {
     readonly pattern: string;
     readonly load: () => Promise<{ default: ComponentType }>;
     readonly layouts?: readonly LayoutComponentLoader[];
-    /** `template.tsx` chain (root → nested) — like layouts, but re-mounted on each navigation. */
+    /** `template.tsx` chain (root → nested), like layouts, but re-mounted on each navigation. */
     readonly templates?: readonly LayoutComponentLoader[];
-    /** Nearest `loading.tsx` — shown as the Suspense fallback while this route loads. */
+    /** 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. */
+    /** Nearest `error.tsx`, rendered by an error boundary around this route. */
     readonly errorComponent?: () => Promise<{ default: ComponentType<RouteErrorProps> }>;
+    /** Intercepting route (`(.)`/`(..)`/`(...)`), matched in its slot only on soft navigation. */
+    readonly intercept?: boolean;
 }
 
 /** Optional root layout loader (wraps every page). `null` when the project defines no layout. */

package/src/compiler/config.ts

@@ -4,6 +4,10 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { type InlineConfig } from 'vite';
 
+import { type SeoConfig } from './seo.js';
+
+export type { SeoConfig } from './seo.js';
+
 /**
  * Client-side (TSX/React/Vite) configuration. All fields optional; sensible defaults applied.
  */
@@ -24,9 +28,31 @@ export interface ClientConfig {
     readonly base?: string;
     /** Dev server port. Default `3000`. */
     readonly port?: number;
+    /**
+     * Optimize imported images at build time (resize/convert via `vite-imagetools` + sharp): an
+     * import like `logo.png?w=400;800&format=webp&as=srcset` emits resized, compressed variants.
+     * Default `true`. Set `false` to disable the pipeline (images are then served as-is).
+     */
+    readonly images?: boolean;
+    /**
+     * Preload bundled fonts at build time: injects `<link rel="preload" as="font">` for each
+     * `@font-face` font so it loads in parallel with the CSS (faster text paint). Default `true`.
+     */
+    readonly fonts?: boolean;
+    /**
+     * Animate cross-page navigations with the browser View Transitions API (a crossfade by default;
+     * add `view-transition-name` in CSS for shared-element transitions). Respects
+     * `prefers-reduced-motion`. Default `false`.
+     */
+    readonly viewTransitions?: boolean;
+    /**
+     * Build-time SEO: bakes site-level metadata into the HTML `<head>` (so JS-less crawlers and AI
+     * bots see real tags) and generates `robots.txt`, `sitemap.xml`, and `llms.txt`. Omit to skip.
+     */
+    readonly seo?: SeoConfig;
     /**
      * Raw Vite escape hatch, deep-merged over the framework's opinionated config.
-     * This is NOT the client config itself — toil owns the Vite setup; use this only
+     * This is NOT the client config itself, toil owns the Vite setup; use this only
      * to override specific Vite options.
      */
     readonly vite?: InlineConfig;
@@ -68,6 +94,14 @@ export interface ResolvedToilConfig {
     readonly outDir: string;
     readonly base: string;
     readonly port: number;
+    /** Whether build-time image optimization (`vite-imagetools`) is enabled. */
+    readonly images: boolean;
+    /** Whether build-time font preloading is enabled. */
+    readonly fonts: boolean;
+    /** Whether animated View Transitions are enabled for navigation. */
+    readonly viewTransitions: boolean;
+    /** Build-time SEO config, or `null` when not configured. */
+    readonly seo: SeoConfig | null;
     /** Absolute path to the framework client runtime (`toiljs/client`). */
     readonly runtimePath: string;
     readonly vite: InlineConfig;
@@ -104,8 +138,7 @@ export async function loadConfig(
     for (const name of CONFIG_NAMES) {
         const candidate = path.join(root, name);
         if (fs.existsSync(candidate)) {
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- dynamic import() is typed `any`
-            const loaded: { default?: ToilConfig } = await import(pathToFileURL(candidate).href);
+            const loaded = (await import(pathToFileURL(candidate).href)) as { default?: ToilConfig };
             if (loaded.default) user = loaded.default;
             break;
         }
@@ -128,6 +161,10 @@ export async function loadConfig(
         outDir: client.outDir ?? 'build/client',
         base: client.base ?? '/',
         port: opts.port ?? client.port ?? 3000,
+        images: client.images ?? true,
+        fonts: client.fonts ?? true,
+        viewTransitions: client.viewTransitions ?? false,
+        seo: client.seo ?? null,
         runtimePath: resolveRuntimePath(),
         vite: client.vite ?? {},
     };

package/src/compiler/docs.ts

@@ -10,18 +10,18 @@ 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
+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/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.
 `;
@@ -82,10 +82,10 @@ export const TOIL_DOCS: Record<string, string> = {
         '',
         '## Project layout',
         '',
-        '- `client/` — the app: `routes/` (file-based), `layout.tsx`, `components/`, `styles/`,',
+        '- `client/`, the app: `routes/` (file-based), `layout.tsx`, `components/`, `styles/`,',
         '  `public/`, and `toil.tsx` (the entry that calls `Toil.mount`).',
-        '- `server/` — the toilscript → WASM target (`@main` entry), compiled by `toilscript`.',
-        '- `toil.config.ts` — configuration via `defineConfig` (`toiljs.config.ts` also works).',
+        '- `server/`, the toilscript → WASM target (`@main` entry), compiled by `toilscript`.',
+        '- `toil.config.ts`, configuration via `defineConfig` (`toiljs.config.ts` also works).',
         '- Generated, gitignored, do not edit: `.toil/` (working dir), `toil-env.d.ts` (ambient',
         '  globals), `toil-routes.d.ts` (typed routes).',
         '',
@@ -106,17 +106,17 @@ export const TOIL_DOCS: Record<string, string> = {
         '## Route files',
         '',
         '- `index.tsx` → `/`, `about.tsx` → `/about`, `blog/index.tsx` → `/blog`',
-        '- `[id].tsx` → dynamic `/:id` — read with `Toil.useParams<{ id: string }>()`',
+        '- `[id].tsx` → dynamic `/:id`, read with `Toil.useParams<{ id: string }>()`',
         '- `[...slug].tsx` → catch-all (1+ segments); `[[...slug]].tsx` → optional catch-all (0+)',
         '- `(group)/` → route group: groups files / scopes a layout, adds no URL segment',
         '',
         '## Special files',
         '',
-        '- `layout.tsx` — wraps the routes beneath it. Root `client/layout.tsx` wraps everything;',
+        '- `layout.tsx`, wraps the routes beneath it. Root `client/layout.tsx` wraps everything;',
         '  nested `routes/**/layout.tsx` compose inside it.',
-        '- `loading.tsx` — Suspense fallback shown while a route (chunk + loader) loads',
-        '- `error.tsx` — error boundary; receives `{ error, reset }` (`Toil.RouteErrorProps`)',
-        '- `client/404.tsx` — shown when no route matches',
+        '- `loading.tsx`, Suspense fallback shown while a route (chunk + loader) loads',
+        '- `error.tsx`, error boundary; receives `{ error, reset }` (`Toil.RouteErrorProps`)',
+        '- `client/404.tsx`, shown when no route matches',
         '',
         '## Data loaders',
         '',
@@ -138,12 +138,12 @@ export const TOIL_DOCS: Record<string, string> = {
         '- `Toil.Link` / `Toil.NavLink` (adds an active class) / `Toil.useRouter()`',
         '  (push / replace / back / forward / refresh / prefetch)',
         '- `Toil.useParams`, `usePathname`, `useSearchParams`, `useNavigationPending`',
-        '- Hrefs are type-checked against your routes — a typo is a compile error.',
+        '- Hrefs are type-checked against your routes, a typo is a compile error.',
     ]),
     'client.md': doc([
         '# Client runtime',
         '',
-        'Everything is on the `Toil` global — no imports needed in route files.',
+        'Everything is on the `Toil` global, no imports needed in route files.',
         '',
         '## Entry',
         '',
@@ -159,7 +159,7 @@ export const TOIL_DOCS: Record<string, string> = {
         '- Navigation: `navigate`, `useRouter`, `useNavigate`',
         '- Location: `usePathname`, `useSearchParams`, `useParams`, `useNavigationPending`',
         '- Data: `useLoaderData` (see `routing.md`)',
-        '- Head: `useHead`, `useTitle`, `<Head>` — set the `<title>` / meta per route',
+        '- Head: `useHead`, `useTitle`, `<Head>`, set the `<title>` / meta per route',
         '- Realtime: `useChannel`, `connectChannel` (WebSocket to the backend at `/_toil`)',
         '- IO globals (no `Toil.` prefix): `BinaryWriter`, `BinaryReader`, `FastMap`, `FastSet`',
         '',
@@ -198,9 +198,9 @@ export const TOIL_DOCS: Record<string, string> = {
         '',
         '`server/` is the toilscript source, compiled to WebAssembly by `toilscript`.',
         '',
-        '- `server/main.ts` — the `@main` entry, exported as the WASM `main`.',
-        '- `server/index.ts` — your functions.',
-        '- `server/tsconfig.json` — extends `toilscript/std/assembly.json` (AssemblyScript/toilscript',
+        '- `server/main.ts`, the `@main` entry, exported as the WASM `main`.',
+        '- `server/index.ts`, your functions.',
+        '- `server/tsconfig.json`, extends `toilscript/std/assembly.json` (AssemblyScript/toilscript',
         '  globals like `i32`, not the DOM), so editors resolve server types correctly.',
         '- `npm run build:server` (or `npm run build`) emits `build/server/release.wasm`.',
         '',
@@ -209,12 +209,12 @@ export const TOIL_DOCS: Record<string, string> = {
     'cli.md': doc([
         '# CLI',
         '',
-        '- `toiljs create [name]` — scaffold a project. Flags: `--template app|minimal`,',
+        '- `toiljs create [name]`, scaffold a project. Flags: `--template app|minimal`,',
         '  `--style css|sass|less|stylus`, `--tailwind`, `--no-ai`, `-y`/`--yes`.',
-        '- `toiljs dev` — dev server with HMR (`--port`, `--root`).',
-        '- `toiljs build` — production build → `build/client` (chain `toilscript` for the server).',
-        '- `toiljs start` — self-host the built app (hyper-express) with a `/_toil` WebSocket channel.',
-        '- `toiljs configure` — toggle styling features on an existing project (see `styling.md`).',
+        '- `toiljs dev`, dev server with HMR (`--port`, `--root`).',
+        '- `toiljs build`, production build → `build/client` (chain `toilscript` for the server).',
+        '- `toiljs start`, self-host the built app (hyper-express) with a `/_toil` WebSocket channel.',
+        '- `toiljs configure`, toggle styling features on an existing project (see `styling.md`).',
     ]),
 };
 

package/src/compiler/fonts.ts

@@ -0,0 +1,87 @@
+import type { HtmlTagDescriptor, Logger, Plugin } from 'vite';
+
+import { type ResolvedToilConfig } from './config.js';
+
+/**
+ * Build-time font optimization. Bundled font files (`@font-face` `url(...)` imports) are emitted +
+ * hashed by Vite, but without a hint the browser only discovers them after parsing CSS, delaying
+ * text paint. This injects a `<link rel="preload" as="font" crossorigin>` for each bundled font so
+ * it loads in parallel with the CSS, and logs what it preloaded (mirrors the image-optimization log).
+ */
+const FONT_RE = /\.(woff2|woff|ttf|otf)$/i;
+const FONT_TYPE: Record<string, string> = {
+    woff2: 'font/woff2',
+    woff: 'font/woff',
+    ttf: 'font/ttf',
+    otf: 'font/otf',
+};
+
+function kb(bytes: number): string {
+    return `${(bytes / 1000).toFixed(2)} kB`;
+}
+
+/** Builds the `<link rel="preload">` head tags for a set of bundled font file names. */
+export function fontPreloadTags(fileNames: readonly string[], base: string): HtmlTagDescriptor[] {
+    const prefix = base.endsWith('/') ? base : `${base}/`;
+    return fileNames
+        .filter((name) => FONT_RE.test(name))
+        .map((name) => {
+            const ext = name.split('.').pop()?.toLowerCase() ?? '';
+            return {
+                tag: 'link',
+                attrs: {
+                    rel: 'preload',
+                    as: 'font',
+                    type: FONT_TYPE[ext] ?? `font/${ext}`,
+                    href: `${prefix}${name}`,
+                    crossorigin: '',
+                },
+                injectTo: 'head',
+            };
+        });
+}
+
+/** Build-only plugin that preloads bundled fonts and logs them. Disabled by `client.fonts: false`. */
+export function fontPreloadPlugin(cfg: ResolvedToilConfig): Plugin {
+    let logger: Logger | undefined;
+    let logged = false;
+    return {
+        name: 'toil:font-preload',
+        apply: 'build',
+        configResolved(config) {
+            logger = config.logger;
+        },
+        transformIndexHtml: {
+            order: 'post',
+            handler(html, ctx) {
+                const bundle = ctx.bundle ?? {};
+                const fonts = Object.values(bundle).filter(
+                    (file) => file.type === 'asset' && FONT_RE.test(file.fileName),
+                );
+                if (fonts.length === 0) return html;
+
+                // Log once (the same template's HTML is transformed per emitted page).
+                if (!logged && logger) {
+                    logged = true;
+                    logger.info('');
+                    logger.info(`  ✓ preloaded ${String(fonts.length)} font${fonts.length === 1 ? '' : 's'}`);
+                    for (const file of fonts) {
+                        const size =
+                            file.type === 'asset' && typeof file.source !== 'string'
+                                ? kb(file.source.byteLength)
+                                : '';
+                        logger.info(`    → ${file.fileName}  ${size}`);
+                    }
+                }
+
+                return {
+                    html,
+                    tags: fontPreloadTags(
+                        fonts.map((f) => f.fileName),
+                        cfg.base,
+                    ),
+                };
+            },
+        },
+    };
+}