toiljs 0.0.81 → 0.0.82

package/src/compiler/prerender.ts

@@ -7,7 +7,7 @@ import type * as TS from 'typescript';
 import type { Plugin } from 'vite';
 
 import { type ResolvedToilConfig } from './config.js';
-import { scanRoutes } from './routes.js';
+import { patternToBracketFile, scanRoutes, staticSectionPattern } from './routes.js';
 import { injectSeoHtml, routeSeo } from './seo.js';
 
 type Ts = typeof TS;
@@ -115,12 +115,51 @@ export function extractStaticMetadata(ts: Ts, filePath: string): Record<string,
     return extractStaticExports(ts, filePath, ['metadata']).metadata ?? null;
 }
 
+/**
+ * True when the route file has a literal `export const <name> = true`. Used to detect the edge-SSR
+ * opt-in (`export const ssr = true`) without spinning up a Vite SSR server, so the static prerender
+ * can leave SSR routes to the SSR path.
+ */
+export function exportsTrue(ts: Ts, filePath: string, name: string): boolean {
+    let source: string;
+    try {
+        source = fs.readFileSync(filePath, 'utf8');
+    } catch {
+        return false;
+    }
+    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 === name &&
+                decl.initializer?.kind === ts.SyntaxKind.TrueKeyword
+            ) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
 /**
  * Build-only plugin that statically pre-renders per-route HTML for SEO. After the bundle is written,
- * it takes the built shell (`index.html`), and for each static route bakes that route's
- * `metadata` (merged over the site-wide `seo` defaults) into a `<route>/index.html` so a JS-less
- * crawler hitting the route gets correct per-page tags. Dynamic (`generateMetadata`) and `:param`
- * routes are skipped (no data at build) and fall back to the client-rendered shell.
+ * it takes the built shell (`index.html`), and for each route bakes that route's `metadata` (merged
+ * over the site-wide `seo` defaults) into a browsable HTML file so a JS-less crawler gets correct
+ * per-page tags:
+ *   - a STATIC route (`/about`) -> `<route>/index.html`;
+ *   - a DYNAMIC route (`/blog/:id`) -> a literal bracket template `blog/[id].html` that the static
+ *     server serves for any concrete `/blog/<x>` and the client router hydrates. Its canonical points
+ *     at the route's static section (`/blog`); the client sets the exact per-value URL on hydration.
+ * A dynamic template is a file, never a `<seg>/index.html` folder, so it never shadows a sibling.
  */
 export function prerenderPlugin(cfg: ResolvedToilConfig): Plugin {
     return {
@@ -139,15 +178,29 @@ export function prerenderPlugin(cfg: ResolvedToilConfig): Plugin {
             const ts = await loadTypeScript(cfg.root);
 
             const routes = scanRoutes(cfg.routesAbsDir).filter(
-                (r) => r.slot === undefined && !r.intercept && !/[:*]/.test(r.pattern),
+                (r) => r.slot === undefined && !r.intercept,
             );
             for (const route of routes) {
+                const isDynamic = /[:*]/.test(route.pattern);
+                // A dynamic route that opts into edge SSR (`export const ssr = true`) is rendered by
+                // the SSR template path. Baking a static bracket template would let the edge's
+                // static-first serving shadow it, so leave SSR routes to SSR. (When `ts` is null the
+                // check is skipped and we bake anyway: fail-OPEN deliberately favors the common
+                // non-SSR dynamic route, which would 404 without a template; typescript is always
+                // present in a real toiljs project, so this branch is effectively unreachable.)
+                if (isDynamic && ts && exportsTrue(ts, route.file, 'ssr')) continue;
                 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');
+                // A dynamic route's concrete URL is unknown at build, so its canonical/OG URL points
+                // at the static section (`/blog/:id` -> `/blog`); the client refines it on hydration.
+                const seoPattern = isDynamic ? staticSectionPattern(route.pattern) : route.pattern;
+                const html = injectSeoHtml(shell, routeSeo(cfg.seo, metadata, seoPattern));
+                // Dynamic -> a literal bracket template (`blog/[id].html`); static -> `<route>/index.html`
+                // (the `/` route is the shell itself). The bracket file is never a folder+index.html.
+                const target = isDynamic
+                    ? path.join(outDir, patternToBracketFile(route.pattern))
+                    : route.pattern === '/'
+                      ? shellPath
+                      : path.join(outDir, route.pattern.replace(/^\//, ''), 'index.html');
                 fs.mkdirSync(path.dirname(target), { recursive: true });
                 fs.writeFileSync(target, html);
             }

package/src/compiler/routes.ts

@@ -34,6 +34,44 @@ function toUrlSegment(segment: string): string {
         .replace(/^\[(.+)\]$/, ':$1');
 }
 
+/** Inverse of {@link toUrlSegment}: turns a URL pattern segment back into its on-disk bracket
+ *  form (`:id`→`[id]`, `*x`→`[...x]`, `**x`→`[[...x]]`). Static segments pass through unchanged. */
+function bracketSegment(segment: string): string {
+    if (segment.startsWith('**')) return `[[...${segment.slice(2)}]]`;
+    if (segment.startsWith('*')) return `[...${segment.slice(1)}]`;
+    if (segment.startsWith(':')) return `[${segment.slice(1)}]`;
+    return segment;
+}
+
+/**
+ * The on-disk HTML filename (relative to the build output dir) a DYNAMIC route pattern bakes to:
+ * the inverse of the scan mapping, with the last segment as the file and the rest as directories.
+ * This is the literal bracket template the static server serves for any matching URL and the client
+ * router hydrates, so it must not become a `<seg>/index.html` folder (which would shadow siblings).
+ *   /blog/:id      -> blog/[id].html
+ *   /docs/*slug    -> docs/[...slug].html
+ *   /docs/**slug   -> docs/[[...slug]].html
+ *   /:category/:id -> [category]/[id].html
+ */
+export function patternToBracketFile(pattern: string): string {
+    return pattern.split('/').filter(Boolean).map(bracketSegment).join('/') + '.html';
+}
+
+/**
+ * The static "section" of a pattern: the same pattern with every dynamic (`:`/`*`) segment dropped.
+ * Used as the canonical/OG base URL when baking a dynamic route's build-time SEO (the concrete
+ * per-value URL is unknown at build; the client sets it on hydration).
+ *   /blog/:id      -> /blog
+ *   /:category/:id -> /
+ */
+export function staticSectionPattern(pattern: string): string {
+    const kept = pattern
+        .split('/')
+        .filter(Boolean)
+        .filter((s) => !s.startsWith(':') && !s.startsWith('*'));
+    return '/' + kept.join('/');
+}
+
 /** Interception markers: `(.)` same level, `(..)` up one, `(...)` from the routes root. */
 const INTERCEPT_RE = /^\((\.{1,3})\)(.+)$/;
 

package/src/devserver/http/runtime.ts

@@ -84,6 +84,106 @@ export function resolveStaticFile(root: string, requestPath: string): string | n
     return resolveFileInside(root, decoded.replace(/^\/+/, ''));
 }
 
+// --- Dynamic bracket-template routing (mirrors the toil-backend edge) ---------
+//
+// The build emits a dynamic route `blog/[id].tsx` as a literal `blog/[id].html`
+// template that boots the SPA for any concrete `/blog/<x>`. When no exact file
+// matches, walk the URL segments and, at each directory, serve a bracket sibling
+// using the client router's precedence: a real subdir wins (static > dynamic),
+// then `[x].html` (one segment), then `[x]/` (descend), then `[...x].html` (1+),
+// then `[[...x]].html` (0+). Directory scans are memoized.
+
+interface DirDynamic {
+    singleFile: string | null;
+    singleDir: string | null;
+    catchall: string | null;
+    optCatchall: string | null;
+}
+
+const dynDirCache = new Map<string, DirDynamic>();
+
+function classifyBracket(name: string, isDir: boolean): keyof DirDynamic | null {
+    if (isDir) {
+        if (name.startsWith('[') && name.endsWith(']') && !name.includes('...') && name.length > 2)
+            return 'singleDir';
+        return null;
+    }
+    if (!name.endsWith('.html')) return null;
+    const stem = name.slice(0, -'.html'.length);
+    if (stem.startsWith('[[...') && stem.endsWith(']]') && stem.length > 7) return 'optCatchall';
+    if (stem.startsWith('[...') && stem.endsWith(']') && stem.length > 5) return 'catchall';
+    if (stem.startsWith('[') && stem.endsWith(']') && !stem.startsWith('[..') && stem.length > 2)
+        return 'singleFile';
+    return null;
+}
+
+function scanDirDynamic(absDir: string): DirDynamic {
+    const cached = dynDirCache.get(absDir);
+    if (cached) return cached;
+    const d: DirDynamic = { singleFile: null, singleDir: null, catchall: null, optCatchall: null };
+    try {
+        for (const e of fs.readdirSync(absDir, { withFileTypes: true })) {
+            const kind = classifyBracket(e.name, e.isDirectory());
+            if (kind === null) continue;
+            const cur = d[kind];
+            if (cur === null || e.name < cur) d[kind] = e.name;
+        }
+    } catch {
+        // missing/unreadable directory: no templates
+    }
+    dynDirCache.set(absDir, d);
+    return d;
+}
+
+const joinRel = (dir: string, name: string): string => (dir === '' ? name : `${dir}/${name}`);
+
+function isDirInside(root: string, rel: string): boolean {
+    const resolved = path.resolve(root, rel);
+    if (resolved !== root && !resolved.startsWith(root + path.sep)) return false;
+    try {
+        return fs.statSync(resolved).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+function resolveDynamicWalk(root: string, dir: string, segs: string[], i: number): string | null {
+    if (i >= segs.length) {
+        // Nothing left: only an optional catch-all (0 segments) serves the bare dir.
+        const oc = scanDirDynamic(path.join(root, dir)).optCatchall;
+        return oc === null ? null : joinRel(dir, oc);
+    }
+    const isLast = i + 1 === segs.length;
+    // A real static subdirectory wins over any dynamic template at this level.
+    const child = joinRel(dir, segs[i]);
+    if (isDirInside(root, child)) {
+        const r = resolveDynamicWalk(root, child, segs, i + 1);
+        if (r !== null) return r;
+    }
+    const d = scanDirDynamic(path.join(root, dir));
+    if (isLast && d.singleFile !== null) return joinRel(dir, d.singleFile);
+    if (d.singleDir !== null) {
+        const r = resolveDynamicWalk(root, joinRel(dir, d.singleDir), segs, i + 1);
+        if (r !== null) return r;
+    }
+    if (d.catchall !== null) return joinRel(dir, d.catchall);
+    if (d.optCatchall !== null) return joinRel(dir, d.optCatchall);
+    return null;
+}
+
+/** Resolve a request path to a bracket-template file (`blog/[id].html`) if one matches, else null. */
+export function resolveDynamicFile(root: string, requestPath: string): string | null {
+    let decoded: string;
+    try {
+        decoded = decodeURIComponent(requestPath);
+    } catch {
+        return null;
+    }
+    const segs = decoded.split('/').filter(Boolean);
+    const rel = resolveDynamicWalk(root, '', segs, 0);
+    return rel === null ? null : resolveFileInside(root, rel);
+}
+
 export interface PreparedHttpResponse {
     readonly status: number;
     readonly headers: readonly (readonly [string, string])[];

package/src/devserver/production.ts

@@ -31,6 +31,7 @@ import {
     isDispatchableMethod,
     prepareSsrResponse,
     prepareWasmResponse,
+    resolveDynamicFile,
     resolveStaticFile,
     runtimeServerOptions,
     toEnvelopeRequest,
@@ -456,7 +457,12 @@ async function startBuiltHttpServer(
             // lookup EVERY route served the root index.html, so view-source on e.g. /login showed
             // the home page's <head> (title/description/canonical/og) instead of the page's own.
             const routeHtml = resolveStaticFile(paths.staticRoot, `${request.path}/index.html`);
-            response.sendFile(routeHtml ?? paths.indexHtml);
+            // A dynamic route with no baked concrete page is served by its bracket template
+            // (`blog/[id].html`) matched the way the client router matches, mirroring the edge; the
+            // client then hydrates it for the concrete URL. Falls back to the root shell if none.
+            const dynHtml =
+                routeHtml === null ? resolveDynamicFile(paths.staticRoot, request.path) : null;
+            response.sendFile(routeHtml ?? dynHtml ?? paths.indexHtml);
             return;
         }
 

package/test/dynamic-routing.test.ts

@@ -0,0 +1,132 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import ts from 'typescript';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { exportsTrue } from '../src/compiler/prerender';
+import { patternToBracketFile, staticSectionPattern } from '../src/compiler/routes';
+import { resolveDynamicFile } from '../src/devserver/http/runtime';
+
+describe('patternToBracketFile', () => {
+    it('inverts URL patterns back to on-disk bracket filenames', () => {
+        expect(patternToBracketFile('/blog/:id')).toBe('blog/[id].html');
+        expect(patternToBracketFile('/docs/*slug')).toBe('docs/[...slug].html');
+        expect(patternToBracketFile('/docs/**slug')).toBe('docs/[[...slug]].html');
+        expect(patternToBracketFile('/:category/:id')).toBe('[category]/[id].html');
+        expect(patternToBracketFile('/gallery/photo/:id')).toBe('gallery/photo/[id].html');
+    });
+});
+
+describe('staticSectionPattern', () => {
+    it('strips dynamic segments to the static section (for the template canonical)', () => {
+        expect(staticSectionPattern('/blog/:id')).toBe('/blog');
+        expect(staticSectionPattern('/docs/*slug')).toBe('/docs');
+        expect(staticSectionPattern('/:category/:id')).toBe('/');
+        expect(staticSectionPattern('/gallery/photo/:id')).toBe('/gallery/photo');
+    });
+});
+
+describe('exportsTrue (edge-SSR opt-in detection)', () => {
+    const files: string[] = [];
+    function tmp(source: string): string {
+        const file = path.join(os.tmpdir(), `toil-ssrflag-${String(files.length)}-${process.pid}.tsx`);
+        fs.writeFileSync(file, source);
+        files.push(file);
+        return file;
+    }
+    afterEach(() => {
+        for (const f of files.splice(0)) fs.rmSync(f, { force: true });
+    });
+
+    it('detects `export const ssr = true`', () => {
+        expect(exportsTrue(ts, tmp(`export const ssr = true;\nexport default () => null;\n`), 'ssr')).toBe(
+            true,
+        );
+    });
+    it('is false for ssr=false, a non-literal, or an absent export', () => {
+        expect(exportsTrue(ts, tmp(`export const ssr = false;\n`), 'ssr')).toBe(false);
+        expect(exportsTrue(ts, tmp(`const ssr = true;\n`), 'ssr')).toBe(false); // not exported
+        expect(exportsTrue(ts, tmp(`export const other = true;\n`), 'ssr')).toBe(false);
+    });
+});
+
+describe('resolveDynamicFile (self-host bracket routing, mirrors the edge)', () => {
+    const roots: string[] = [];
+    function siteRoot(): string {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), 'toil-dyn-'));
+        roots.push(root);
+        return root;
+    }
+    function write(root: string, rel: string, body = '<html></html>'): void {
+        const full = path.join(root, rel);
+        fs.mkdirSync(path.dirname(full), { recursive: true });
+        fs.writeFileSync(full, body);
+    }
+    afterEach(() => {
+        for (const d of roots.splice(0)) fs.rmSync(d, { recursive: true, force: true });
+    });
+
+    it('serves a single-segment [id].html for a matching URL, one segment only', () => {
+        const root = siteRoot();
+        write(root, 'blog/[id].html', 'blog-shell');
+        expect(resolveDynamicFile(root, '/blog/hello')).toBe(path.join(root, 'blog/[id].html'));
+        expect(resolveDynamicFile(root, '/blog/a/b')).toBeNull();
+    });
+
+    it('serves a required catch-all for 1+ segments but not zero', () => {
+        const root = siteRoot();
+        write(root, 'docs/[...slug].html', 'docs');
+        expect(resolveDynamicFile(root, '/docs/a')).toBe(path.join(root, 'docs/[...slug].html'));
+        expect(resolveDynamicFile(root, '/docs/a/b/c')).toBe(path.join(root, 'docs/[...slug].html'));
+        expect(resolveDynamicFile(root, '/docs')).toBeNull();
+        // Parity with the client router + edge: a literal `index.html` segment is a slug (matches
+        // the catch-all), while a bare `/docs/` is zero trailing segments (no required-catch-all match).
+        expect(resolveDynamicFile(root, '/docs/index.html')).toBe(
+            path.join(root, 'docs/[...slug].html'),
+        );
+        expect(resolveDynamicFile(root, '/docs/')).toBeNull();
+    });
+
+    it('serves an optional catch-all for 0+ segments', () => {
+        const root = siteRoot();
+        write(root, 'files/[[...slug]].html', 'files');
+        expect(resolveDynamicFile(root, '/files')).toBe(path.join(root, 'files/[[...slug]].html'));
+        expect(resolveDynamicFile(root, '/files/a/b')).toBe(path.join(root, 'files/[[...slug]].html'));
+    });
+
+    it('prefers single over catch-all for one segment, catch-all for deeper', () => {
+        const root = siteRoot();
+        write(root, 'shop/[id].html', 'one');
+        write(root, 'shop/[...rest].html', 'many');
+        expect(fs.readFileSync(resolveDynamicFile(root, '/shop/x') as string, 'utf8')).toBe('one');
+        expect(fs.readFileSync(resolveDynamicFile(root, '/shop/x/y') as string, 'utf8')).toBe('many');
+    });
+
+    it('prefers a real static subdirectory over a dynamic sibling', () => {
+        const root = siteRoot();
+        write(root, 'blog/[id].html', 'template');
+        write(root, 'blog/about/deep/[id].html', 'deep');
+        // /blog/about/deep/7 descends the real dirs to the deep template, not blog/[id].html.
+        expect(resolveDynamicFile(root, '/blog/about/deep/7')).toBe(
+            path.join(root, 'blog/about/deep/[id].html'),
+        );
+    });
+
+    it('resolves a nested bracket directory', () => {
+        const root = siteRoot();
+        write(root, '[category]/[id].html', 'cat');
+        expect(resolveDynamicFile(root, '/electronics/9')).toBe(
+            path.join(root, '[category]/[id].html'),
+        );
+        expect(resolveDynamicFile(root, '/electronics')).toBeNull();
+    });
+
+    it('returns null when no bracket template exists', () => {
+        const root = siteRoot();
+        write(root, 'about/index.html', 'about');
+        expect(resolveDynamicFile(root, '/blog/foo')).toBeNull();
+        expect(resolveDynamicFile(root, '/x/y/z')).toBeNull();
+    });
+});