toiljs 0.0.8 → 0.0.9

package/build/compiler/fonts.js

@@ -0,0 +1,64 @@
+const FONT_RE = /\.(woff2|woff|ttf|otf)$/i;
+const FONT_TYPE = {
+    woff2: 'font/woff2',
+    woff: 'font/woff',
+    ttf: 'font/ttf',
+    otf: 'font/otf',
+};
+function kb(bytes) {
+    return `${(bytes / 1000).toFixed(2)} kB`;
+}
+export function fontPreloadTags(fileNames, base) {
+    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',
+        };
+    });
+}
+export function fontPreloadPlugin(cfg) {
+    let logger;
+    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;
+                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),
+                };
+            },
+        },
+    };
+}

package/build/compiler/generate.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { writeDocs } from './docs.js';
 import { scanRoutes } from './routes.js';
+import { llmsTxt, robotsTxt, sitemapXml } from './seo.js';
 const STYLE_EXTENSIONS = ['css', 'scss', 'sass', 'less', 'styl', 'stylus', 'pcss', 'sss'];
 const ASSET_EXTENSIONS = [
     'svg',
@@ -17,13 +18,15 @@ const ASSET_EXTENSIONS = [
 ];
 const STYLE_MODULES = STYLE_EXTENSIONS.map((ext) => `declare module '*.${ext}' {}`).join('\n');
 const ASSET_MODULES = ASSET_EXTENSIONS.map((ext) => `declare module '*.${ext}' {\n    const src: string;\n    export default src;\n}`).join('\n');
-export const TOIL_ENV_DTS = `// AUTO-GENERATED by toil — do not edit.\n` +
+export const TOIL_ENV_DTS = `// AUTO-GENERATED by toil, do not edit.\n` +
     `/// <reference types="vite-imagetools/client" />\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 RouteErrorProps = import('toiljs/client').RouteErrorProps;\n` +
     `}\n` +
     `declare const BinaryWriter: typeof import('toiljs/io').BinaryWriter;\n` +
@@ -40,6 +43,7 @@ export const TOIL_ENV_DTS = `// AUTO-GENERATED by toil — do not edit.\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` +
     `}\n`;
 function relFromToil(cfg, abs) {
     let rel = path.relative(cfg.toilDir, abs).replace(/\\/g, '/').replace(/\.(tsx|jsx)$/, '');
@@ -82,7 +86,7 @@ function routePathUnion(routes) {
     return members.size ? [...members].join(' | ') : 'string';
 }
 function routesDts(routes) {
-    return (`// AUTO-GENERATED by toil — do not edit.\n` +
+    return (`// AUTO-GENERATED by toil, do not edit.\n` +
         `export {};\n` +
         `declare module 'toiljs/client' {\n` +
         `    interface Register {\n` +
@@ -142,62 +146,91 @@ export function generate(cfg) {
     const layoutFile = findLayout(cfg);
     const notFoundFile = findNotFound(cfg);
     const globalErrorFile = findGlobalError(cfg);
+    const imp = (f) => `() => import(${JSON.stringify(relFromToil(cfg, f))})`;
+    const routeObj = (r) => {
+        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 routesSrc = `// @ts-nocheck\n` +
-        `// AUTO-GENERATED by toil — do not edit.\n` +
+        `// AUTO-GENERATED by toil, do not edit.\n` +
         `import type { RouteDef, LayoutLoader, NotFoundLoader } from 'toiljs/client';\n\n` +
-        `export const routes: RouteDef[] = [\n` +
-        routes
-            .map((r) => {
-            const imp = (f) => `() => import(${JSON.stringify(relFromToil(cfg, f))})`;
-            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)}`);
-            return `  { ${parts.join(', ')} },`;
-        })
-            .join('\n') +
-        `\n];\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`;
     fs.writeFileSync(path.join(cfg.toilDir, 'routes.ts'), routesSrc);
     const globalsSrc = `// @ts-nocheck\n` +
-        `// AUTO-GENERATED by toil — do not edit.\n` +
+        `// AUTO-GENERATED by toil, do not edit.\n` +
         `import * as Toil from 'toiljs/client';\n` +
         `import { BinaryWriter, BinaryReader, FastMap, FastSet } from 'toiljs/io';\n\n` +
-        `Object.assign(globalThis, { Toil, BinaryWriter, BinaryReader, FastMap, FastSet });\n`;
+        `Object.assign(globalThis, { Toil, BinaryWriter, BinaryReader, FastMap, FastSet });\n` +
+        `Toil.setViewTransitions(${String(cfg.viewTransitions)});\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` +
+            `// 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` +
+            `// AUTO-GENERATED by toil, do not edit.\n` +
             `import './globals';\n` +
             `import { mount } from 'toiljs/client';\n` +
-            `import { routes, layout, notFound, globalError } from './routes';\n\n` +
-            `mount(routes, layout, notFound, globalError);\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(routes));
     fs.writeFileSync(path.join(cfg.toilDir, 'index.html'), buildHtml(cfg));
     syncPublicAssets(cfg);
+    writeSeoFiles(cfg, routes);
     writeDocs(cfg.toilDir);
     return routes;
 }
+function writeSeoFiles(cfg, routes) {
+    if (!cfg.seo)
+        return;
+    const dest = path.join(cfg.toilDir, 'public');
+    const files = [
+        ['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);
+}
 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` +

package/build/compiler/plugin.js

@@ -12,7 +12,7 @@ export function toilPlugin(cfg) {
                 /^[ \t]*export\b[^'"\n]*\bfrom\s+(['"])\1/m.test(code) ||
                 /\bimport\s*\(\s*(['"])\1\s*\)/.test(code);
             if (empty) {
-                throw new Error(`toil: empty import specifier (e.g. \`import '';\`) in ${file} — remove or complete the import.`);
+                throw new Error(`toil: empty import specifier (e.g. \`import '';\`) in ${file}, remove or complete the import.`);
             }
             return null;
         },

package/build/compiler/prerender.d.ts

@@ -0,0 +1,7 @@
+import type * as TS from 'typescript';
+import type { Plugin } from 'vite';
+import { type ResolvedToilConfig } from './config.js';
+type Ts = typeof TS;
+export declare function extractStaticMetadata(ts: Ts, filePath: string): Record<string, unknown> | null;
+export declare function prerenderPlugin(cfg: ResolvedToilConfig): Plugin;
+export {};

package/build/compiler/prerender.js

@@ -0,0 +1,111 @@
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { scanRoutes } from './routes.js';
+import { injectSeoHtml, routeSeo } from './seo.js';
+async function loadTypeScript(root) {
+    try {
+        const resolved = createRequire(path.join(root, 'package.json')).resolve('typescript');
+        const mod = (await import(pathToFileURL(resolved).href));
+        return mod.default ?? mod;
+    }
+    catch {
+        return null;
+    }
+}
+const UNRESOLVED = Symbol('unresolved');
+function evalNode(ts, node) {
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+        return node.text;
+    if (ts.isNumericLiteral(node))
+        return Number(node.text);
+    if (node.kind === ts.SyntaxKind.TrueKeyword)
+        return true;
+    if (node.kind === ts.SyntaxKind.FalseKeyword)
+        return false;
+    if (node.kind === ts.SyntaxKind.NullKeyword)
+        return null;
+    if (ts.isArrayLiteralExpression(node)) {
+        const out = [];
+        for (const el of node.elements) {
+            const value = evalNode(ts, el);
+            if (value === UNRESOLVED)
+                return UNRESOLVED;
+            out.push(value);
+        }
+        return out;
+    }
+    if (ts.isObjectLiteralExpression(node))
+        return evalObject(ts, node);
+    return UNRESOLVED;
+}
+function evalObject(ts, node) {
+    const obj = {};
+    for (const prop of node.properties) {
+        if (!ts.isPropertyAssignment(prop))
+            continue;
+        const key = ts.isIdentifier(prop.name)
+            ? prop.name.text
+            : ts.isStringLiteral(prop.name)
+                ? prop.name.text
+                : null;
+        if (key === null)
+            continue;
+        const value = evalNode(ts, prop.initializer);
+        if (value !== UNRESOLVED)
+            obj[key] = value;
+    }
+    return obj;
+}
+export function extractStaticMetadata(ts, filePath) {
+    let source;
+    try {
+        source = fs.readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const sf = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    for (const stmt of sf.statements) {
+        if (!ts.isVariableStatement(stmt))
+            continue;
+        if (!stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword))
+            continue;
+        for (const decl of stmt.declarationList.declarations) {
+            if (ts.isIdentifier(decl.name) &&
+                decl.name.text === 'metadata' &&
+                decl.initializer &&
+                ts.isObjectLiteralExpression(decl.initializer)) {
+                return evalObject(ts, decl.initializer);
+            }
+        }
+    }
+    return null;
+}
+export function prerenderPlugin(cfg) {
+    return {
+        name: 'toil:prerender-seo',
+        apply: 'build',
+        async closeBundle() {
+            if (!cfg.seo)
+                return;
+            const outDir = path.resolve(cfg.root, cfg.outDir);
+            const shellPath = path.join(outDir, 'index.html');
+            if (!fs.existsSync(shellPath))
+                return;
+            const shell = fs.readFileSync(shellPath, 'utf8');
+            const ts = await loadTypeScript(cfg.root);
+            const routes = scanRoutes(cfg.routesAbsDir).filter((r) => r.slot === undefined && !r.intercept && !/[:*]/.test(r.pattern));
+            for (const route of routes) {
+                const metadata = ts ? extractStaticMetadata(ts, route.file) : null;
+                const html = injectSeoHtml(shell, routeSeo(cfg.seo, metadata, route.pattern));
+                const target = route.pattern === '/'
+                    ? shellPath
+                    : path.join(outDir, route.pattern.replace(/^\//, ''), 'index.html');
+                fs.mkdirSync(path.dirname(target), { recursive: true });
+                fs.writeFileSync(target, html);
+            }
+        },
+    };
+}

package/build/compiler/routes.d.ts

@@ -1,6 +1,9 @@
 export interface ScannedRoute {
     readonly file: string;
     readonly pattern: string;
+    readonly slot?: string;
+    readonly intercept?: boolean;
 }
 export declare function filePathToRoute(relPath: string): string;
+export declare function interceptTarget(relPath: string): string | null;
 export declare function scanRoutes(routesDir: string): ScannedRoute[];

package/build/compiler/routes.js

@@ -2,6 +2,13 @@ import fs from 'node:fs';
 import path from 'node:path';
 const ROUTE_EXT = /\.(tsx|jsx)$/;
 const SPECIAL_FILE = /^(layout|template|loading|error|global-error|404|not-found)\.(tsx|jsx)$/;
+function toUrlSegment(segment) {
+    return segment
+        .replace(/^\[\[\.\.\.(.+)\]\]$/, '**$1')
+        .replace(/^\[\.\.\.(.+)\]$/, '*$1')
+        .replace(/^\[(.+)\]$/, ':$1');
+}
+const INTERCEPT_RE = /^\((\.{1,3})\)(.+)$/;
 export function filePathToRoute(relPath) {
     const withoutExt = relPath.replace(/\\/g, '/').replace(ROUTE_EXT, '');
     const segments = withoutExt.split('/').filter(Boolean);
@@ -10,15 +17,41 @@ export function filePathToRoute(relPath) {
         const segment = segments[i];
         if (/^\(.+\)$/.test(segment))
             continue;
+        if (/^@/.test(segment))
+            continue;
         if (segment === 'index' && i === segments.length - 1)
             continue;
-        out.push(segment
-            .replace(/^\[\[\.\.\.(.+)\]\]$/, '**$1')
-            .replace(/^\[\.\.\.(.+)\]$/, '*$1')
-            .replace(/^\[(.+)\]$/, ':$1'));
+        out.push(toUrlSegment(segment));
     }
     return '/' + out.join('/');
 }
+export function interceptTarget(relPath) {
+    const segments = relPath.replace(/\\/g, '/').replace(ROUTE_EXT, '').split('/').filter(Boolean);
+    const out = [];
+    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();
+            else if (dots === 3)
+                out.length = 0;
+            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;
+}
 function specificity(pattern) {
     const segments = pattern.split('/').filter(Boolean);
     let score = segments.length * 10;
@@ -30,6 +63,14 @@ function specificity(pattern) {
     }
     return score;
 }
+function slotOf(relPath) {
+    for (const segment of relPath.replace(/\\/g, '/').split('/')) {
+        const match = /^@(.+)$/.exec(segment);
+        if (match)
+            return match[1];
+    }
+    return undefined;
+}
 export function scanRoutes(routesDir) {
     if (!fs.existsSync(routesDir))
         return [];
@@ -41,9 +82,13 @@ export function scanRoutes(routesDir) {
                 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/build/compiler/seo.d.ts

@@ -0,0 +1,70 @@
+import type { ScannedRoute } from './routes.js';
+export interface SeoOpenGraph {
+    readonly title?: string;
+    readonly description?: string;
+    readonly type?: string;
+    readonly siteName?: string;
+    readonly locale?: string;
+    readonly image?: string;
+    readonly imageAlt?: string;
+    readonly imageWidth?: number;
+    readonly imageHeight?: number;
+    readonly imageType?: string;
+}
+export interface SeoTwitter {
+    readonly card?: string;
+    readonly site?: string;
+    readonly creator?: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly image?: string;
+    readonly imageAlt?: string;
+}
+export interface RobotsRule {
+    readonly userAgent?: string | readonly string[];
+    readonly allow?: readonly string[];
+    readonly disallow?: readonly string[];
+}
+export interface RobotsConfig {
+    readonly rules?: readonly RobotsRule[];
+    readonly ai?: 'allow' | 'disallow';
+    readonly sitemap?: string;
+}
+export interface LlmsPage {
+    readonly title: string;
+    readonly url: string;
+    readonly description?: string;
+}
+export interface LlmsConfig {
+    readonly title?: string;
+    readonly summary?: string;
+    readonly instructions?: string;
+    readonly pages?: readonly LlmsPage[];
+}
+export interface SeoConfig {
+    readonly url?: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly robotsMeta?: string;
+    readonly themeColor?: string;
+    readonly openGraph?: SeoOpenGraph;
+    readonly twitter?: SeoTwitter;
+    readonly facebook?: {
+        readonly appId?: string;
+    };
+    readonly jsonLd?: Record<string, unknown> | readonly Record<string, unknown>[];
+    readonly preconnect?: readonly string[];
+    readonly dnsPrefetch?: readonly string[];
+    readonly robots?: RobotsConfig | false;
+    readonly sitemap?: boolean;
+    readonly llms?: LlmsConfig | boolean;
+}
+export declare function escapeHtml(value: string): string;
+export declare function joinUrl(base: string, path: string): string;
+export declare function seoHeadTags(seo: SeoConfig): string;
+export declare function seoTitle(seo: SeoConfig): string | undefined;
+export declare function injectSeoHtml(html: string, seo: SeoConfig): string;
+export declare function routeSeo(seo: SeoConfig, metadata: Record<string, unknown> | null, pattern: string): SeoConfig;
+export declare function robotsTxt(seo: SeoConfig): string;
+export declare function sitemapXml(seo: SeoConfig, routes: readonly ScannedRoute[]): string;
+export declare function llmsTxt(seo: SeoConfig, routes: readonly ScannedRoute[]): string;