toiljs 0.0.7 → 0.0.9

package/src/compiler/generate.ts

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { type ResolvedToilConfig } from './config.js';
 import { writeDocs } from './docs.js';
 import { scanRoutes, type ScannedRoute } from './routes.js';
+import { llmsTxt, robotsTxt, sitemapXml } from './seo.js';
 
 /**
  * Contents of the root `toil-env.d.ts`: ambient global types so `new BinaryWriter()` etc. resolve
@@ -35,11 +36,16 @@ const ASSET_MODULES = ASSET_EXTENSIONS.map(
 ).join('\n');
 
 export const TOIL_ENV_DTS =
-    `// AUTO-GENERATED by toil — do not edit.\n` +
+    `// AUTO-GENERATED by toil, do not edit.\n` +
+    // Types for image-optimization query imports (`import img from './x.png?w=400&format=webp'`).
+    `/// <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` +
@@ -56,6 +62,7 @@ export const TOIL_ENV_DTS =
     `    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`;
 
 /**
@@ -119,7 +126,7 @@ function routePathUnion(routes: ScannedRoute[]): string {
  */
 function routesDts(routes: ScannedRoute[]): string {
     return (
-        `// AUTO-GENERATED by toil — do not edit.\n` +
+        `// AUTO-GENERATED by toil, do not edit.\n` +
         `export {};\n` +
         `declare module 'toiljs/client' {\n` +
         `    interface Register {\n` +
@@ -198,30 +205,40 @@ export function generate(cfg: ResolvedToilConfig): ScannedRoute[] {
     const layoutFile = findLayout(cfg);
     const notFoundFile = findNotFound(cfg);
     const globalErrorFile = findGlobalError(cfg);
+    const imp = (f: string): string => `() => import(${JSON.stringify(relFromToil(cfg, f))})`;
+    const routeObj = (r: ScannedRoute): string => {
+        const layouts = findSpecialChain(cfg, r.file, 'layout', false).map(imp).join(', ');
+        const templates = findSpecialChain(cfg, r.file, 'template', true).map(imp).join(', ');
+        const parts = [
+            `pattern: ${JSON.stringify(r.pattern)}`,
+            `load: ${imp(r.file)}`,
+            `layouts: [${layouts}]`,
+        ];
+        if (templates) parts.push(`templates: [${templates}]`);
+        const loadingFile = findNearest(cfg, r.file, 'loading');
+        if (loadingFile) parts.push(`loading: ${imp(loadingFile)}`);
+        const errorFile = findNearest(cfg, r.file, 'error');
+        if (errorFile) parts.push(`errorComponent: ${imp(errorFile)}`);
+        if (r.intercept) parts.push(`intercept: true`);
+        return `{ ${parts.join(', ')} }`;
+    };
+    const mainRoutes = routes.filter((r) => r.slot === undefined);
+    const slotNames = [...new Set(routes.flatMap((r) => (r.slot ? [r.slot] : [])))];
+    const slotsBody = slotNames
+        .map((name) => {
+            const items = routes
+                .filter((r) => r.slot === name)
+                .map((r) => `    ${routeObj(r)},`)
+                .join('\n');
+            return `  ${JSON.stringify(name)}: [\n${items}\n  ],`;
+        })
+        .join('\n');
     const 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: string): string => `() => 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`;
@@ -229,24 +246,25 @@ export function generate(cfg: ResolvedToilConfig): ScannedRoute[] {
 
     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);
@@ -254,11 +272,31 @@ export function generate(cfg: ResolvedToilConfig): ScannedRoute[] {
 
     fs.writeFileSync(path.join(cfg.toilDir, 'index.html'), buildHtml(cfg));
     syncPublicAssets(cfg);
+    writeSeoFiles(cfg, routes);
     writeDocs(cfg.toilDir);
 
     return routes;
 }
 
+/**
+ * Writes the build-time SEO crawler files into `.toil/public` (Vite's publicDir, served in dev and
+ * copied to the output root in build): `robots.txt` (incl. AI-crawler directives), `sitemap.xml`
+ * (static routes), and `llms.txt` (AI guidance). No-op when SEO isn't configured.
+ */
+function writeSeoFiles(cfg: ResolvedToilConfig, routes: ScannedRoute[]): void {
+    if (!cfg.seo) return;
+    const dest = path.join(cfg.toilDir, 'public');
+    const files: [string, string][] = [
+        ['robots.txt', robotsTxt(cfg.seo)],
+        ['sitemap.xml', sitemapXml(cfg.seo, routes)],
+        ['llms.txt', llmsTxt(cfg.seo, routes)],
+    ];
+    const present = files.filter(([, content]) => content !== '');
+    if (present.length === 0) return;
+    fs.mkdirSync(dest, { recursive: true });
+    for (const [name, content] of present) fs.writeFileSync(path.join(dest, name), content);
+}
+
 /** Fallback HTML when the project has no `public/index.html` template. The entry script is added
  * by {@link buildHtml}. */
 const DEFAULT_HTML =
@@ -274,7 +312,7 @@ const ENTRY_SCRIPT = `<script type="module" src="./entry.tsx"></script>`;
 /**
  * Produces the `.toil/index.html` Vite entry from the project's `public/index.html` template (or
  * the built-in default if absent), ensuring the generated module entry script is present. Users
- * own the template — toil only guarantees the entry is wired, so it stays the SPA root.
+ * own the template, toil only guarantees the entry is wired, so it stays the SPA root.
  */
 function buildHtml(cfg: ResolvedToilConfig): string {
     const templatePath = path.join(cfg.publicDir, 'index.html');
@@ -293,7 +331,7 @@ function buildHtml(cfg: ResolvedToilConfig): string {
 
 /**
  * Mirrors the project's `public/` assets into `.toil/public/` (Vite's publicDir under the `.toil`
- * root), excluding the `index.html` template — that is processed into the entry above, and copying
+ * root), excluding the `index.html` template, that is processed into the entry above, and copying
  * it here would clobber the built, asset-hashed page. Cleared each run so deletions propagate.
  */
 function syncPublicAssets(cfg: ResolvedToilConfig): void {

package/src/compiler/image-report.ts

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

package/src/compiler/plugin.ts

@@ -11,7 +11,7 @@ import { generate } from './generate.js';
 export function toilPlugin(cfg: ResolvedToilConfig): Plugin {
     return {
         name: 'toil',
-        // Catch empty import specifiers in source and report the file — rolldown otherwise fails
+        // Catch empty import specifiers in source and report the file, rolldown otherwise fails
         // resolution with a cryptic "The specifiers must be a non-empty string. Received ''".
         transform(code, id) {
             const file = id.split('?')[0];
@@ -25,7 +25,7 @@ export function toilPlugin(cfg: ResolvedToilConfig): Plugin {
                 /\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.`,
+                    `toil: empty import specifier (e.g. \`import '';\`) in ${file}, remove or complete the import.`,
                 );
             }
             return null;

package/src/compiler/prerender.ts

@@ -0,0 +1,130 @@
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import type * as TS from 'typescript';
+import type { Plugin } from 'vite';
+
+import { type ResolvedToilConfig } from './config.js';
+import { scanRoutes } from './routes.js';
+import { injectSeoHtml, routeSeo } from './seo.js';
+
+type Ts = typeof TS;
+
+/** Loads the project's TypeScript (used to read each route's static `metadata`), or `null` if absent. */
+async function loadTypeScript(root: string): Promise<Ts | null> {
+    try {
+        const resolved = createRequire(path.join(root, 'package.json')).resolve('typescript');
+        const mod = (await import(pathToFileURL(resolved).href)) as { default?: Ts } & Ts;
+        return mod.default ?? mod;
+    } catch {
+        return null;
+    }
+}
+
+/** Marks an AST node that isn't a static literal (so its value can't be baked at build). */
+const UNRESOLVED = Symbol('unresolved');
+
+/** Statically evaluates a literal expression node to a JS value, or `UNRESOLVED` if it isn't one. */
+function evalNode(ts: Ts, node: TS.Expression): unknown {
+    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: unknown[] = [];
+        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;
+}
+
+/** Evaluates an object literal to a plain object, skipping any property that isn't a static literal. */
+function evalObject(ts: Ts, node: TS.ObjectLiteralExpression): Record<string, unknown> {
+    const obj: Record<string, unknown> = {};
+    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;
+}
+
+/**
+ * Extracts a route's `export const metadata = { … }` if it's a static object literal, returning the
+ * statically-evaluable subset (dynamic `generateMetadata` and computed values are skipped). `null`
+ * when the file has no static metadata.
+ */
+export function extractStaticMetadata(ts: Ts, filePath: string): Record<string, unknown> | null {
+    let source: string;
+    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;
+}
+
+/**
+ * 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.
+ */
+export function prerenderPlugin(cfg: ResolvedToilConfig): Plugin {
+    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/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,
                 });
             }
         }