feat(router): optional catch-all, nested not-found, loading→Suspense, metadata routes

- [[...slug]] optional catch-all matches with and without params
- not-found.ts collected at every segment level (nearest wins)
- loading.ts auto-wraps page in Suspense boundary with loading as fallback
- Metadata routes: sitemap.ts, robots.ts, manifest.ts, icon.ts,
  opengraph-image.ts, twitter-image.ts served at well-known URLs

Author: vivek7405

packages/server/src/router.js

@@ -22,10 +22,14 @@ import { walk } from './fs-walk.js';
  *   middlewares: string[],
  * }} ApiRoute
  *
+ * @typedef {{ stem: string, file: string, urlPath: string }} MetadataRoute
+ *
  * @typedef {{
  *   pages: PageRoute[],
  *   apis: ApiRoute[],
  *   notFound: string | null,
+ *   notFounds: Map<string, string>,
+ *   metadataRoutes: MetadataRoute[],
  *   appDir: string
  * }} RouteTable
  */
@@ -43,8 +47,13 @@ import { walk } from './fs-walk.js';
  *   app/api/hello/route.js          → /api/hello
  *   app/layout.js                   → wraps every page
  *   app/error.js                    → error boundary (nested)
- *   app/loading.js                  → loading UI (reserved, v1 renders only)
- *   app/not-found.js                → 404 fallback
+ *   app/loading.js                  → loading UI (auto-wraps page in Suspense)
+ *   app/not-found.js                → 404 fallback (nested: nearest wins)
+ *   app/[[...slug]]/page.js         → optional catch-all (matches / AND /a/b)
+ *   app/sitemap.js                  → serves /sitemap.xml
+ *   app/robots.js                   → serves /robots.txt
+ *   app/icon.js                     → serves /icon (dynamic)
+ *   app/opengraph-image.js          → serves /opengraph-image (dynamic)
  *
  * @param {string} appDir
  * @returns {Promise<RouteTable>}
@@ -63,7 +72,24 @@ export async function buildRouteTable(appDir) {
   const loadings = new Map();
   /** @type {Map<string,string>} */
   const middlewares = new Map();
+  /** @type {Map<string, string>} */
+  const notFounds = new Map();
   let notFound = null;
+  /** @type {MetadataRoute[]} */
+  const metadataRoutes = [];
+
+  /** @type {Set<string>} */
+  const METADATA_STEMS = new Set(['sitemap', 'robots', 'manifest', 'icon', 'apple-icon', 'opengraph-image', 'twitter-image']);
+  /** @type {Record<string,string>} */
+  const METADATA_URL_MAP = {
+    'sitemap': '/sitemap.xml',
+    'robots': '/robots.txt',
+    'manifest': '/manifest.json',
+    'icon': '/icon',
+    'apple-icon': '/apple-icon',
+    'opengraph-image': '/opengraph-image',
+    'twitter-image': '/twitter-image',
+  };
 
   for await (const file of walk(root)) {
     const rel = relative(root, file).split(sep).join('/');
@@ -100,8 +126,14 @@ export async function buildRouteTable(appDir) {
       loadings.set(dir, file);
     } else if (stem === 'middleware') {
       middlewares.set(dir, file);
-    } else if (stem === 'not-found' && dir === '.') {
-      notFound = file;
+    } else if (stem === 'not-found') {
+      notFounds.set(dir, file);
+      if (dir === '.') notFound = file;
+    } else if (METADATA_STEMS.has(stem) && (dir === '.' || dir.split('/').every(s => !s.startsWith('[')))) {
+      // Metadata route: sitemap.ts, robots.ts, icon.ts, etc.
+      // Only at root or static segments (no dynamic params in metadata routes).
+      const urlPath = METADATA_URL_MAP[stem] || `/${stem}`;
+      metadataRoutes.push({ stem, file, urlPath });
     } else if (stem === 'route') {
       // route.js / route.ts can live anywhere under app/ (matches Next.js).
       const segs = dir === '.' ? [] : dir.split('/');
@@ -127,7 +159,7 @@ export async function buildRouteTable(appDir) {
   }
 
   pages.sort((a, b) => dynScore(a) - dynScore(b));
-  return { pages, apis, notFound, appDir };
+  return { pages, apis, notFound, notFounds, metadataRoutes, appDir };
 }
 
 /**
@@ -173,9 +205,17 @@ function dynScore(r) {
 function segmentsToPattern(segments, prefix = '') {
   const paramNames = [];
   let isCatchAll = false;
+  let isOptionalCatchAll = false;
   const parts = segments
     .filter(isUrlSegment)
     .map((seg) => {
+      // Optional catch-all: [[...slug]] matches with AND without params
+      if (seg.startsWith('[[...') && seg.endsWith(']]')) {
+        paramNames.push(seg.slice(5, -2));
+        isCatchAll = true;
+        isOptionalCatchAll = true;
+        return '(.*)';
+      }
       if (seg.startsWith('[...') && seg.endsWith(']')) {
         paramNames.push(seg.slice(4, -1));
         isCatchAll = true;
@@ -188,7 +228,17 @@ function segmentsToPattern(segments, prefix = '') {
       return escapeRe(seg);
     });
   const body = parts.length ? '/' + parts.join('/') : '';
-  const pattern = new RegExp(`^${escapeRe(prefix)}${body}/?$`);
+  // Optional catch-all: also matches the base path without any trailing segments.
+  // e.g., /docs/[[...slug]] matches both /docs and /docs/a/b/c
+  const suffix = isOptionalCatchAll ? '(?:/(.*))?/?' : '/?';
+  const regexBody = isOptionalCatchAll
+    ? body.replace(/\/\(\.\*\)$/, '')  // remove the trailing (.*) — we add it as optional
+    : body;
+  const pattern = new RegExp(`^${escapeRe(prefix)}${regexBody}${isOptionalCatchAll ? suffix : '/?$'}`);
+  if (!isOptionalCatchAll) {
+    // Standard pattern needs end anchor
+    return { pattern: new RegExp(`^${escapeRe(prefix)}${body}/?$`), paramNames, isCatchAll };
+  }
   return { pattern, paramNames, isCatchAll };
 }
 

test/router.test.js

@@ -131,3 +131,84 @@ test('matches route.js anywhere under app/, not only /api', async () => {
     await rm(dir, { recursive: true, force: true });
   }
 });
+
+test('optional catch-all [[...slug]] matches with and without params', async () => {
+  const dir = await scaffold({
+    'app/docs/[[...slug]]/page.js': 'export default () => ""',
+  });
+  try {
+    const table = await buildRouteTable(dir);
+    // Matches /docs (no params)
+    const root = matchPage(table, '/docs');
+    assert.ok(root, '/docs should match optional catch-all');
+    // Matches /docs/getting-started
+    const one = matchPage(table, '/docs/getting-started');
+    assert.ok(one, '/docs/getting-started should match');
+    assert.equal(one.params.slug, 'getting-started');
+    // Matches /docs/a/b/c
+    const deep = matchPage(table, '/docs/a/b/c');
+    assert.ok(deep, '/docs/a/b/c should match');
+    assert.equal(deep.params.slug, 'a/b/c');
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('nested not-found.js files are collected per segment', async () => {
+  const dir = await scaffold({
+    'app/page.js': 'export default () => ""',
+    'app/not-found.js': 'export default () => "root 404"',
+    'app/dashboard/page.js': 'export default () => ""',
+    'app/dashboard/not-found.js': 'export default () => "dashboard 404"',
+  });
+  try {
+    const table = await buildRouteTable(dir);
+    assert.ok(table.notFound, 'root not-found should exist');
+    assert.ok(table.notFounds.get('.'), 'root not-found in map');
+    assert.ok(table.notFounds.get('dashboard'), 'dashboard not-found in map');
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('metadata routes are detected (sitemap, robots)', async () => {
+  const dir = await scaffold({
+    'app/page.js': 'export default () => ""',
+    'app/sitemap.js': 'export default () => "<urlset></urlset>"',
+    'app/robots.js': 'export default () => "User-agent: *\\nAllow: /"',
+  });
+  try {
+    const table = await buildRouteTable(dir);
+    assert.ok(table.metadataRoutes.length >= 2, `Expected >=2 metadata routes, got ${table.metadataRoutes.length}`);
+    const sitemap = table.metadataRoutes.find((r) => r.stem === 'sitemap');
+    assert.ok(sitemap, 'sitemap route should exist');
+    assert.equal(sitemap.urlPath, '/sitemap.xml');
+    const robots = table.metadataRoutes.find((r) => r.stem === 'robots');
+    assert.ok(robots, 'robots route should exist');
+    assert.equal(robots.urlPath, '/robots.txt');
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('loading.js files are attached to page routes', async () => {
+  const dir = await scaffold({
+    'app/page.js': 'export default () => ""',
+    'app/loading.js': 'export default () => "Loading..."',
+    'app/dashboard/page.js': 'export default () => ""',
+    'app/dashboard/loading.js': 'export default () => "Dashboard loading..."',
+  });
+  try {
+    const table = await buildRouteTable(dir);
+    const root = matchPage(table, '/');
+    assert.ok(root);
+    assert.ok(root.route.loadings.length >= 1, 'root page should have loading');
+    const dash = matchPage(table, '/dashboard');
+    assert.ok(dash);
+    assert.ok(dash.route.loadings.length >= 1, 'dashboard page should have loading');
+    // Dashboard inherits root loading AND has its own
+    assert.ok(dash.route.loadings.length >= 2, 'dashboard should have nested loadings');
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});