toiljs 0.0.8 → 0.0.9

package/src/compiler/routes.ts

@@ -5,6 +5,10 @@ import path from 'node:path';
 export interface ScannedRoute {
     readonly file: string;
     readonly pattern: string;
+    /** Named parallel slot this route belongs to (from an `@slot` dir), or `undefined` for the main tree. */
+    readonly slot?: string;
+    /** True for an intercepting route (`(.)`/`(..)`/`(...)`), matched only on soft navigation. */
+    readonly intercept?: boolean;
 }
 
 const ROUTE_EXT = /\.(tsx|jsx)$/;
@@ -20,7 +24,19 @@ const SPECIAL_FILE = /^(layout|template|loading|error|global-error|404|not-found
  *   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)
+ *   @modal/photo/[id].tsx -> /photo/:id     (parallel slot: `@slot` adds no URL segment)
  */
+/** Converts a path segment's dynamic brackets to URL params (`[id]`→`:id`, `[...x]`→`*x`, `[[...x]]`→`**x`). */
+function toUrlSegment(segment: string): string {
+    return segment
+        .replace(/^\[\[\.\.\.(.+)\]\]$/, '**$1')
+        .replace(/^\[\.\.\.(.+)\]$/, '*$1')
+        .replace(/^\[(.+)\]$/, ':$1');
+}
+
+/** Interception markers: `(.)` same level, `(..)` up one, `(...)` from the routes root. */
+const INTERCEPT_RE = /^\((\.{1,3})\)(.+)$/;
+
 export function filePathToRoute(relPath: string): string {
     const withoutExt = relPath.replace(/\\/g, '/').replace(ROUTE_EXT, '');
     const segments = withoutExt.split('/').filter(Boolean);
@@ -28,17 +44,43 @@ export function filePathToRoute(relPath: string): string {
     for (let i = 0; i < segments.length; i++) {
         const segment = segments[i];
         if (/^\(.+\)$/.test(segment)) continue;
+        if (/^@/.test(segment)) continue; // parallel-slot marker, contributes no URL segment
         if (segment === 'index' && i === segments.length - 1) continue;
-        out.push(
-            segment
-                .replace(/^\[\[\.\.\.(.+)\]\]$/, '**$1')
-                .replace(/^\[\.\.\.(.+)\]$/, '*$1')
-                .replace(/^\[(.+)\]$/, ':$1'),
-        );
+        out.push(toUrlSegment(segment));
     }
     return '/' + out.join('/');
 }
 
+/**
+ * The URL an intercepting route targets, or `null` if the path has no `(.)`/`(..)`/`(...)` marker.
+ * The marker resolves the target relative to the route's position (ignoring `@slot`/`(group)`
+ * segments): `(.)` keeps the current level, `(..)` drops one, `(...)` resets to the root.
+ *   @modal/(.)photo/[id].tsx     -> /photo/:id
+ *   feed/@modal/(..)photo/[id].tsx -> /photo/:id
+ */
+export function interceptTarget(relPath: string): string | null {
+    const segments = relPath.replace(/\\/g, '/').replace(ROUTE_EXT, '').split('/').filter(Boolean);
+    const out: string[] = [];
+    let marked = false;
+    for (let i = 0; i < segments.length; i++) {
+        const segment = segments[i];
+        if (/^@/.test(segment)) continue;
+        const marker = INTERCEPT_RE.exec(segment);
+        if (marker) {
+            marked = true;
+            const dots = marker[1].length;
+            if (dots === 2) out.pop(); // (..) up one level
+            else if (dots === 3) out.length = 0; // (...) from the routes root
+            out.push(toUrlSegment(marker[2]));
+            continue;
+        }
+        if (/^\(.+\)$/.test(segment)) continue;
+        if (segment === 'index' && i === segments.length - 1) continue;
+        out.push(toUrlSegment(segment));
+    }
+    return marked ? '/' + out.join('/') : null;
+}
+
 /**
  * Ranks a pattern so more specific routes match first: static segments beat dynamic (`:x`),
  * which beat catch-all (`*x`); deeper routes beat shallower ones.
@@ -53,6 +95,15 @@ function specificity(pattern: string): number {
     return score;
 }
 
+/** The parallel-slot name for a route path (the first `@slot` segment), or `undefined`. */
+function slotOf(relPath: string): string | undefined {
+    for (const segment of relPath.replace(/\\/g, '/').split('/')) {
+        const match = /^@(.+)$/.exec(segment);
+        if (match) return match[1];
+    }
+    return undefined;
+}
+
 /** Recursively scans `routesDir` for `.tsx`/`.jsx` files, returning routes sorted by specificity. */
 export function scanRoutes(routesDir: string): ScannedRoute[] {
     if (!fs.existsSync(routesDir)) return [];
@@ -63,9 +114,13 @@ export function scanRoutes(routesDir: string): ScannedRoute[] {
             if (entry.isDirectory()) {
                 walk(full);
             } else if (ROUTE_EXT.test(entry.name) && !SPECIAL_FILE.test(entry.name)) {
+                const rel = path.relative(routesDir, full);
+                const target = interceptTarget(rel);
                 found.push({
                     file: full,
-                    pattern: filePathToRoute(path.relative(routesDir, full)),
+                    pattern: target ?? filePathToRoute(rel),
+                    slot: slotOf(rel),
+                    intercept: target !== null,
                 });
             }
         }

package/src/compiler/seo.ts

@@ -0,0 +1,356 @@
+import type { ScannedRoute } from './routes.js';
+
+/**
+ * Build-time SEO for the (otherwise JS-only) SPA: 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`. All pure string builders here; `generate.ts` wires them into the build output.
+ */
+
+/**
+ * OpenGraph defaults baked into the HTML, read by Facebook, Discord, Slack, LinkedIn, GitHub, and
+ * most link-preview crawlers. `image` should be an absolute URL (≥1200×630 for a large card).
+ */
+export interface SeoOpenGraph {
+    readonly title?: string;
+    readonly description?: string;
+    /** `og:type`, e.g. `'website'` or `'article'`. */
+    readonly type?: string;
+    readonly siteName?: string;
+    /** `og:locale`, e.g. `'en_US'`. */
+    readonly locale?: string;
+    /** `og:image`, the preview image (absolute URL). */
+    readonly image?: string;
+    /** `og:image:alt`. */
+    readonly imageAlt?: string;
+    /** `og:image:width` in px (helps Facebook/LinkedIn render without a re-fetch). */
+    readonly imageWidth?: number;
+    /** `og:image:height` in px. */
+    readonly imageHeight?: number;
+    /** `og:image:type`, e.g. `'image/png'`. */
+    readonly imageType?: string;
+}
+
+/** Twitter / X card. Unset fields fall back to the OpenGraph / top-level values. */
+export interface SeoTwitter {
+    /** `'summary'` | `'summary_large_image'` | … Defaults by whether an image is present. */
+    readonly card?: string;
+    readonly site?: string;
+    readonly creator?: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly image?: string;
+    readonly imageAlt?: string;
+}
+
+/** A `robots.txt` group. */
+export interface RobotsRule {
+    readonly userAgent?: string | readonly string[];
+    readonly allow?: readonly string[];
+    readonly disallow?: readonly string[];
+}
+
+/** `robots.txt` configuration. */
+export interface RobotsConfig {
+    readonly rules?: readonly RobotsRule[];
+    /** How to treat known AI crawlers (GPTBot, ClaudeBot, Google-Extended, …). Default `'allow'`. */
+    readonly ai?: 'allow' | 'disallow';
+    /** Explicit `Sitemap:` URL (defaults to `<url>/sitemap.xml` when `seo.url` is set). */
+    readonly sitemap?: string;
+}
+
+/** A page listed in `llms.txt`. */
+export interface LlmsPage {
+    readonly title: string;
+    readonly url: string;
+    readonly description?: string;
+}
+
+/** `llms.txt` configuration (the AI-crawler guidance file). */
+export interface LlmsConfig {
+    readonly title?: string;
+    readonly summary?: string;
+    /** Free-form instructions for AI/LLM crawlers. */
+    readonly instructions?: string;
+    /** Key pages; defaults to the site's static routes. */
+    readonly pages?: readonly LlmsPage[];
+}
+
+/** Build-time SEO configuration (under `client.seo`). */
+export interface SeoConfig {
+    /** Absolute site base URL, e.g. `https://toil.dev`, required for `sitemap.xml` and canonical/OG URLs. */
+    readonly url?: string;
+    /** Default document title baked into the HTML. */
+    readonly title?: string;
+    /** Default meta description. */
+    readonly description?: string;
+    /** Default robots directive, e.g. `'index, follow'`. */
+    readonly robotsMeta?: string;
+    /** `<meta name="theme-color">`, also the accent color of Discord/Slack link embeds. */
+    readonly themeColor?: string;
+    readonly openGraph?: SeoOpenGraph;
+    readonly twitter?: SeoTwitter;
+    /** Facebook-specific tags (`fb:app_id`). OpenGraph above covers the rest of the FB card. */
+    readonly facebook?: { readonly appId?: string };
+    /** JSON-LD structured data injected as `<script type="application/ld+json">`. */
+    readonly jsonLd?: Record<string, unknown> | readonly Record<string, unknown>[];
+    /** Origins to `<link rel="preconnect">` (early connection hints). */
+    readonly preconnect?: readonly string[];
+    /** Origins to `<link rel="dns-prefetch">`. */
+    readonly dnsPrefetch?: readonly string[];
+    /** `robots.txt` generation; `false` to skip. */
+    readonly robots?: RobotsConfig | false;
+    /** `sitemap.xml` generation; defaults to on when `url` is set. */
+    readonly sitemap?: boolean;
+    /** `llms.txt` (AI guidance) generation; `false` to skip, `true`/object to configure. */
+    readonly llms?: LlmsConfig | boolean;
+}
+
+/** Known AI / LLM crawler user-agents, for explicit allow/disallow in `robots.txt`. */
+const AI_CRAWLERS: readonly string[] = [
+    'GPTBot',
+    'OAI-SearchBot',
+    'ChatGPT-User',
+    'ClaudeBot',
+    'Claude-Web',
+    'anthropic-ai',
+    'Google-Extended',
+    'PerplexityBot',
+    'CCBot',
+    'Applebot-Extended',
+    'Bytespider',
+    'Amazonbot',
+    'Meta-ExternalAgent',
+];
+
+/** Escapes a value for use inside a double-quoted HTML attribute (prevents attribute-breakout XSS). */
+function escapeAttr(value: string): string {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+/** Escapes a value for HTML text content (e.g. `<title>`, XML text). */
+export function escapeHtml(value: string): string {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+/**
+ * Serializes a value for embedding in an inline `<script>` (JSON-LD). Escapes `<`, `>`, and `&`,
+ * which neutralizes `</script>` and `<!--` (the only HTML-significant sequences inside a script),
+ * so attacker-controlled data can't break out of the script element.
+ */
+function escapeJsonForScript(value: unknown): string {
+    return JSON.stringify(value)
+        .replace(/</g, '\\u003c')
+        .replace(/>/g, '\\u003e')
+        .replace(/&/g, '\\u0026');
+}
+function meta(attrs: Record<string, string | number | undefined>): string {
+    const pairs = Object.entries(attrs)
+        .filter((entry): entry is [string, string | number] => entry[1] !== undefined)
+        .map(([k, v]) => `${k}="${escapeAttr(String(v))}"`);
+    return `    <meta ${pairs.join(' ')} />`;
+}
+
+/** Joins a base URL and a route path into a clean absolute URL. */
+export function joinUrl(base: string, path: string): string {
+    return `${base.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`.replace(/\/$/, '') || base;
+}
+
+/** Static (parameter-free) route patterns, the ones that can be listed in a sitemap. */
+function staticPaths(routes: readonly ScannedRoute[]): string[] {
+    return routes
+        .filter((r) => r.slot === undefined && !r.intercept && !/[:*]/.test(r.pattern))
+        .map((r) => r.pattern)
+        .sort();
+}
+
+/** The site-level `<head>` fragment baked into the built HTML (title is handled separately). */
+export function seoHeadTags(seo: SeoConfig): string {
+    const lines: string[] = [];
+    if (seo.description !== undefined) lines.push(meta({ name: 'description', content: seo.description }));
+    if (seo.robotsMeta !== undefined) lines.push(meta({ name: 'robots', content: seo.robotsMeta }));
+    if (seo.themeColor !== undefined) lines.push(meta({ name: 'theme-color', content: seo.themeColor }));
+    if (seo.url !== undefined) lines.push(`    <link rel="canonical" href="${escapeAttr(seo.url)}" />`);
+
+    // OpenGraph (also drives Facebook, Discord, Slack, LinkedIn, GitHub previews).
+    const og = seo.openGraph;
+    const ogTitle = og?.title ?? seo.title;
+    const ogDesc = og?.description ?? seo.description;
+    if (ogTitle !== undefined) lines.push(meta({ property: 'og:title', content: ogTitle }));
+    if (ogDesc !== undefined) lines.push(meta({ property: 'og:description', content: ogDesc }));
+    lines.push(meta({ property: 'og:type', content: og?.type ?? 'website' }));
+    if (seo.url !== undefined) lines.push(meta({ property: 'og:url', content: seo.url }));
+    if (og?.siteName !== undefined) lines.push(meta({ property: 'og:site_name', content: og.siteName }));
+    if (og?.locale !== undefined) lines.push(meta({ property: 'og:locale', content: og.locale }));
+    if (og?.image !== undefined) {
+        lines.push(meta({ property: 'og:image', content: og.image }));
+        if (og.imageAlt !== undefined) lines.push(meta({ property: 'og:image:alt', content: og.imageAlt }));
+        if (og.imageType !== undefined) lines.push(meta({ property: 'og:image:type', content: og.imageType }));
+        if (og.imageWidth !== undefined) lines.push(meta({ property: 'og:image:width', content: og.imageWidth }));
+        if (og.imageHeight !== undefined) {
+            lines.push(meta({ property: 'og:image:height', content: og.imageHeight }));
+        }
+    }
+    if (seo.facebook?.appId !== undefined) {
+        lines.push(meta({ property: 'fb:app_id', content: seo.facebook.appId }));
+    }
+
+    // Twitter / X card. Unset fields fall back to OpenGraph / top-level values.
+    const tw = seo.twitter;
+    if (tw) {
+        const twImage = tw.image ?? og?.image;
+        const card = tw.card ?? (twImage !== undefined ? 'summary_large_image' : 'summary');
+        lines.push(meta({ name: 'twitter:card', content: card }));
+        if (tw.site !== undefined) lines.push(meta({ name: 'twitter:site', content: tw.site }));
+        if (tw.creator !== undefined) lines.push(meta({ name: 'twitter:creator', content: tw.creator }));
+        const twTitle = tw.title ?? ogTitle;
+        const twDesc = tw.description ?? ogDesc;
+        if (twTitle !== undefined) lines.push(meta({ name: 'twitter:title', content: twTitle }));
+        if (twDesc !== undefined) lines.push(meta({ name: 'twitter:description', content: twDesc }));
+        if (twImage !== undefined) lines.push(meta({ name: 'twitter:image', content: twImage }));
+        const twImageAlt = tw.imageAlt ?? og?.imageAlt;
+        if (twImageAlt !== undefined) lines.push(meta({ name: 'twitter:image:alt', content: twImageAlt }));
+    }
+
+    for (const origin of seo.preconnect ?? []) {
+        lines.push(`    <link rel="preconnect" href="${escapeAttr(origin)}" />`);
+    }
+    for (const origin of seo.dnsPrefetch ?? []) {
+        lines.push(`    <link rel="dns-prefetch" href="${escapeAttr(origin)}" />`);
+    }
+    if (seo.jsonLd !== undefined) {
+        lines.push(`    <script type="application/ld+json">${escapeJsonForScript(seo.jsonLd)}</script>`);
+    }
+    return lines.join('\n');
+}
+
+/** The default document title to bake into the HTML, if any. */
+export function seoTitle(seo: SeoConfig): string | undefined {
+    return seo.title;
+}
+
+/**
+ * Bakes the SEO `<head>` into an HTML document: replaces the existing `<title>` and `description`
+ * meta (so they aren't duplicated) and inserts the rest before `</head>`. Used for the shell and,
+ * per route, by the prerenderer.
+ */
+export function injectSeoHtml(html: string, seo: SeoConfig): string {
+    let out = html;
+    const title = seoTitle(seo);
+    if (title !== undefined) {
+        const tag = `<title>${escapeHtml(title)}</title>`;
+        out = /<title>[\s\S]*?<\/title>/i.test(out)
+            ? out.replace(/<title>[\s\S]*?<\/title>/i, tag)
+            : out.replace(/<\/head>/i, `    ${tag}\n  </head>`);
+    }
+    if (seo.description !== undefined) {
+        out = out.replace(/[ \t]*<meta\s+name=["']description["'][^>]*>\s*\n?/i, '');
+    }
+    const tags = seoHeadTags(seo);
+    if (tags) {
+        out = out.includes('</head>') ? out.replace(/<\/head>/i, `${tags}\n  </head>`) : `${tags}\n${out}`;
+    }
+    return out;
+}
+
+function asString(value: unknown): string | undefined {
+    return typeof value === 'string' ? value : undefined;
+}
+function asRecord(value: unknown): Record<string, unknown> {
+    return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : {};
+}
+
+/**
+ * Overlays a route's extracted `metadata` (title/description/openGraph/…) onto the site-wide
+ * {@link SeoConfig}, and points the canonical/`og:url` at the route's own URL. The result is what
+ * the prerenderer bakes into that route's HTML, per-file metadata winning over the site defaults.
+ */
+export function routeSeo(
+    seo: SeoConfig,
+    metadata: Record<string, unknown> | null,
+    pattern: string,
+): SeoConfig {
+    const routeUrl = seo.url !== undefined ? joinUrl(seo.url, pattern) : undefined;
+    if (!metadata) return { ...seo, url: routeUrl };
+    const og = asRecord(metadata.openGraph);
+    return {
+        ...seo,
+        url: asString(metadata.canonical) ?? routeUrl,
+        title: asString(metadata.title) ?? seo.title,
+        description: asString(metadata.description) ?? seo.description,
+        robotsMeta: asString(metadata.robots) ?? seo.robotsMeta,
+        themeColor: asString(metadata.themeColor) ?? seo.themeColor,
+        openGraph: {
+            ...seo.openGraph,
+            title: asString(og.title) ?? asString(metadata.title) ?? seo.openGraph?.title,
+            description: asString(og.description) ?? asString(metadata.description) ?? seo.openGraph?.description,
+            type: asString(og.type) ?? seo.openGraph?.type,
+            image: asString(og.image) ?? seo.openGraph?.image,
+            imageAlt: asString(og.imageAlt) ?? seo.openGraph?.imageAlt,
+            siteName: asString(og.siteName) ?? seo.openGraph?.siteName,
+        },
+    };
+}
+
+/** `robots.txt` contents. */
+export function robotsTxt(seo: SeoConfig): string {
+    if (seo.robots === false) return '';
+    const cfg: RobotsConfig = seo.robots ?? {};
+    const blocks: string[] = [];
+
+    const rules = cfg.rules ?? [{ userAgent: '*', allow: ['/'] }];
+    for (const rule of rules) {
+        const agents = rule.userAgent === undefined ? ['*'] : [rule.userAgent].flat();
+        const lines = agents.map((a) => `User-agent: ${a}`);
+        for (const p of rule.allow ?? []) lines.push(`Allow: ${p}`);
+        for (const p of rule.disallow ?? []) lines.push(`Disallow: ${p}`);
+        blocks.push(lines.join('\n'));
+    }
+
+    const aiDirective = cfg.ai === 'disallow' ? 'Disallow: /' : 'Allow: /';
+    blocks.push(
+        ['# AI / LLM crawlers', ...AI_CRAWLERS.map((a) => `User-agent: ${a}\n${aiDirective}`)].join('\n\n'),
+    );
+
+    const sitemap = cfg.sitemap ?? (seo.url !== undefined ? joinUrl(seo.url, 'sitemap.xml') : undefined);
+    if (sitemap !== undefined) blocks.push(`Sitemap: ${sitemap}`);
+
+    return blocks.join('\n\n') + '\n';
+}
+
+/** `sitemap.xml` from the site's static routes (requires `seo.url`); empty when no base URL. */
+export function sitemapXml(seo: SeoConfig, routes: readonly ScannedRoute[]): string {
+    if (seo.url === undefined || seo.sitemap === false) return '';
+    const urls = staticPaths(routes)
+        .map((p) => `  <url><loc>${escapeHtml(joinUrl(seo.url ?? '', p))}</loc></url>`)
+        .join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls}\n</urlset>\n`;
+}
+
+/** `llms.txt` (AI-crawler guidance) contents; empty when disabled. */
+export function llmsTxt(seo: SeoConfig, routes: readonly ScannedRoute[]): string {
+    if (seo.llms === false) return '';
+    const cfg: LlmsConfig = seo.llms === true || seo.llms === undefined ? {} : seo.llms;
+    const title = cfg.title ?? seo.title ?? seo.url ?? 'Site';
+    const out: string[] = [`# ${title}`];
+    const summary = cfg.summary ?? seo.description;
+    if (summary !== undefined) out.push(`\n> ${summary}`);
+    if (cfg.instructions !== undefined) out.push(`\n${cfg.instructions}`);
+
+    const pages: readonly LlmsPage[] =
+        cfg.pages ??
+        (seo.url !== undefined
+            ? staticPaths(routes).map(
+                  (p): LlmsPage => ({ title: p === '/' ? 'Home' : p, url: joinUrl(seo.url ?? '', p) }),
+              )
+            : []);
+    if (pages.length) {
+        out.push('\n## Pages\n');
+        for (const page of pages) {
+            out.push(`- [${page.title}](${page.url})${page.description !== undefined ? `: ${page.description}` : ''}`);
+        }
+    }
+    return out.join('\n') + '\n';
+}

package/src/compiler/vite.ts

@@ -8,8 +8,10 @@ import { nodePolyfills } from 'vite-plugin-node-polyfills';
 import { mergeConfig, type InlineConfig, type PluginOption } from 'vite';
 
 import { type ResolvedToilConfig } from './config.js';
+import { fontPreloadPlugin } from './fonts.js';
 import { imageReportPlugin } from './image-report.js';
 import { toilPlugin } from './plugin.js';
+import { prerenderPlugin } from './prerender.js';
 
 /** Image extensions routed to `images/` in the build output. */
 const IMAGE_EXT = /^(png|jpe?g|svg|gif|tiff|bmp|ico|webp|avif)$/i;
@@ -37,8 +39,7 @@ async function tailwindPlugin(root: string): Promise<PluginOption | undefined> {
     } 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);
+    const mod = (await import(pathToFileURL(resolved).href)) as { default?: () => PluginOption };
     return mod.default?.();
 }
 
@@ -60,9 +61,9 @@ function manualChunks(id: string): string | undefined {
  * `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
+ * 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
+ * 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 async function createViteConfig(cfg: ResolvedToilConfig): Promise<InlineConfig> {
@@ -85,6 +86,10 @@ export async function createViteConfig(cfg: ResolvedToilConfig): Promise<InlineC
                   })
                 : undefined,
             cfg.images ? imageReportPlugin(cfg.root, cfg.toilDir) : undefined,
+            // Static per-route SEO prerender (build only): bakes each route's metadata into its HTML.
+            cfg.seo ? prerenderPlugin(cfg) : undefined,
+            // Preload bundled fonts (build only). Disabled by `client.fonts: false`.
+            cfg.fonts ? fontPreloadPlugin(cfg) : undefined,
             nodePolyfills({ globals: { Buffer: true, global: true, process: true } }),
             react(),
             toilPlugin(cfg),

package/src/io/FastSet.ts

@@ -4,7 +4,7 @@ import { type FastRecord, type IndexKey, type PropertyExtendedKey } from './Fast
  * The Set counterpart to {@link FastMap}: an insertion-ordered set backed by an array (for
  * iteration/ordering) plus a record index (for O(1) membership), with bigint-key support.
  *
- * Authored to match FastMap's design — the upstream package ships no `FastSet`.
+ * Authored to match FastMap's design, the upstream package ships no `FastSet`.
  */
 export class FastSet<T extends PropertyExtendedKey> implements Disposable {
     protected _values: T[] = [];

package/src/io/index.ts

@@ -1,5 +1,5 @@
 /**
- * toiljs IO — native binary serialization + fast collections, exposed to the client both as
+ * toiljs IO, native binary serialization + fast collections, exposed to the client both as
  * `toiljs/io` imports and as ambient globals (see the generated `.toil/toil-env.d.ts`).
  */
 export { BinaryWriter } from './BinaryWriter.js';

package/src/io/types.ts

@@ -1,6 +1,6 @@
 /**
  * Branded numeric width aliases used by the binary IO classes. They are plain `number`/`bigint`
- * at runtime — the names document intent.
+ * at runtime, the names document intent.
  */
 export type i8 = number;
 export type i16 = number;

package/src/server/index.ts

@@ -2,7 +2,7 @@
  * toilscript server (WASM) entry, compiled to WebAssembly by `toilscript`.
  *
  * Placeholder module: a trivial exported function that compiles with the toilscript std.
- * Native decorators (e.g. `@main`) ship from toilscript directly — no transformer required.
+ * Native decorators (e.g. `@main`) ship from toilscript directly, no transformer required.
  */
 
 export function add(a: i32, b: i32): i32 {

package/src/server/main.ts

@@ -1,7 +1,7 @@
 /**
  * Server (WASM) entry point, compiled by the toilscript fork (`toilscript --target release`).
  *
- * `@main` is a toilscript-native decorator — no import needed. It marks this
+ * `@main` is a toilscript-native decorator, no import needed. It marks this
  * function as the module entry; the compiler exports it as the WebAssembly
  * export `main`.
  */

package/src/shared/index.ts

@@ -1,6 +1,6 @@
 /**
  * Shared primitives used across every toiljs target (client, compiler, cli, server tooling).
- * Placeholder — real shared types/utilities land here.
+ * Placeholder, real shared types/utilities land here.
  */
 
 export const FRAMEWORK_NAME = 'toiljs';

package/test/dom/error-overlay.test.tsx

@@ -0,0 +1,44 @@
+// @vitest-environment jsdom
+import { act, cleanup, fireEvent, render } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+    DevErrorBoundary,
+    DevErrorOverlay,
+    initDevErrorOverlay,
+} from '../../src/client/dev/error-overlay';
+
+afterEach(cleanup);
+
+function Boom(): never {
+    throw new Error('render boom');
+}
+
+describe('dev error overlay', () => {
+    it('surfaces an uncaught render error', () => {
+        // React logs caught boundary errors to console.error — silence it for a clean test run.
+        const spy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+        const { getByRole } = render(
+            <>
+                <DevErrorBoundary>
+                    <Boom />
+                </DevErrorBoundary>
+                <DevErrorOverlay />
+            </>,
+        );
+        expect(getByRole('alert').textContent).toContain('render boom');
+        spy.mockRestore();
+    });
+
+    it('surfaces an unhandled window error and dismisses it', async () => {
+        initDevErrorOverlay();
+        const { findByRole, queryByRole, getByText } = render(<DevErrorOverlay />);
+        act(() => {
+            window.dispatchEvent(new ErrorEvent('error', { error: new Error('async boom') }));
+        });
+        const alert = await findByRole('alert');
+        expect(alert.textContent).toContain('async boom');
+        fireEvent.click(getByText('Dismiss'));
+        expect(queryByRole('alert')).toBeNull();
+    });
+});

package/test/dom/revalidate.test.tsx

@@ -0,0 +1,38 @@
+// @vitest-environment jsdom
+import { act, cleanup, render } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { Router } from '../../src/client/routing/Router';
+import { clearLoaderData, revalidate, useLoaderData } from '../../src/client/routing/loader';
+import type { RouteDef } from '../../src/client/types';
+
+afterEach(cleanup);
+beforeEach(() => {
+    clearLoaderData();
+    window.history.replaceState({}, '', '/');
+});
+
+describe('revalidate refetches', () => {
+    it('re-runs the loader and updates the rendered data', async () => {
+        let n = 0;
+        function Page(): React.ReactNode {
+            const value = useLoaderData<number>();
+            return <p>val:{String(value)}</p>;
+        }
+        const routes: RouteDef[] = [
+            {
+                pattern: '/',
+                load: () => Promise.resolve({ default: Page, loader: () => (n += 1) }),
+                // matches the example: this route has a loading.tsx (keyed boundary + transition).
+                loading: () => Promise.resolve({ default: () => <p>loading</p> }),
+            },
+        ];
+        const { findByText } = render(<Router routes={routes} />);
+        await findByText('val:1');
+
+        act(() => {
+            revalidate();
+        });
+        await findByText('val:2');
+    });
+});