@timber-js/app 0.2.0-alpha.14 → 0.2.0-alpha.141

package/src/plugins/routing.ts

@@ -10,25 +10,65 @@
 
 import type { Plugin, ViteDevServer } from 'vite';
 import { writeFile, mkdir } from 'node:fs/promises';
+import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { scanRoutes } from '#/routing/scanner.js';
-import { generateRouteMap } from '#/routing/codegen.js';
-import { collectInterceptionRewrites } from '#/routing/interception.js';
+import { scanRoutes } from '../routing/scanner.js';
+import { generateRouteMap } from '../routing/codegen.js';
+import { collectInterceptionRewrites } from '../routing/interception.js';
 import {
-  lintStatusFileDirectives,
-  formatStatusFileLintWarnings,
-} from '#/routing/status-file-lint.js';
-import type { RouteTree, SegmentNode, RouteFile } from '#/routing/types.js';
-import type { PluginContext } from '#/index.js';
+  buildDirToRouteMap,
+  writeSegmentTypes,
+  type SegmentInfo,
+} from '../routing/segment-codegen.js';
+import { validateSchemaAgainstRoutes } from '../routing/schema-validation.js';
+
+import {
+  lintConventions,
+  checkAppDirExists,
+  formatConventionWarnings,
+} from '../routing/convention-lint.js';
+import type { RouteTree, SegmentNode, RouteFile } from '../routing/types.js';
+import type { PluginContext } from '../plugin-context.js';
 
 const VIRTUAL_MODULE_ID = 'virtual:timber-route-manifest';
 const RESOLVED_VIRTUAL_ID = `\0${VIRTUAL_MODULE_ID}`;
 
+// TIM-830: Search-params registry virtual module.
+//
+// Statically imports the `searchParams` named export from every page
+// that exports one, and registers each definition into the shared
+// search-params registry keyed by the un-interpolated route pattern
+// (e.g. '/products/[id]'). This lets `<Link>` serialize flat
+// `Partial<T>` values at runtime without callers importing the
+// definition at the call site.
+//
+// The imports are STATIC (`import { searchParams as r0 } from '...'`)
+// so Vite/Rolldown tree-shakes each page's component body out of the
+// registry chunk — only the `searchParams` named export is pulled in.
+const SEARCH_PARAMS_REGISTRY_ID = 'virtual:timber-search-params-registry';
+const RESOLVED_SEARCH_PARAMS_REGISTRY_ID = `\0${SEARCH_PARAMS_REGISTRY_ID}`;
+
+// TIM-931: Schema virtual module.
+//
+// When app/schema.ts exists, this module imports it and resolves the
+// bracket-keyed segmentParams codecs into a bare-name codec map for
+// runtime coercion. When no schema exists, exports null.
+const SCHEMA_ID = 'virtual:timber-schema';
+const RESOLVED_SCHEMA_ID = `\0${SCHEMA_ID}`;
+
+// TIM-935: $segment virtual module prefix.
+// Resolved ID encodes segment info as JSON after the prefix.
+//
+// Each route directory gets a virtual module that exports the route
+// and segmentPath. `import { route, segmentPath } from './$segment'`
+// resolves to `\0$segment:<json>`.
+const SEGMENT_PREFIX = '\0$segment:';
+
 /**
  * File convention names we track for changes that require manifest regeneration.
  */
 const ROUTE_FILE_PATTERNS =
-  /\/(page|layout|middleware|access|route|error|default|denied|search-params|\d{3}|[45]xx|not-found|forbidden|unauthorized|sitemap|robots|manifest|favicon|icon|opengraph-image|twitter-image|apple-icon)\./;
+  /\/(page|layout|middleware|access|route|error|global-error|default|denied|params|schema|\d{3}|[45]xx|not-found|forbidden|unauthorized|sitemap|robots|manifest|favicon|icon|opengraph-image|apple-icon)\./;
 
 /**
  * Create the timber-routing Vite plugin.
@@ -44,12 +84,25 @@ const CODEGEN_OUTPUT = '.timber/timber-routes.d.ts';
  * Uses a triple-slash reference so TypeScript auto-discovers the generated
  * route map without the user needing to edit tsconfig.json — same pattern
  * as Next.js's next-env.d.ts.
+ *
+ * Also references `vite/client` so side-effect imports like
+ * `import './globals.css'` type-check without ts(2882), and so
+ * `import.meta.env`, `import.meta.hot`, `import.meta.glob`, asset
+ * imports (`*.png`, `*.svg`, …), CSS modules, and `?url`/`?raw`/
+ * `?inline` query variants all resolve without the user editing
+ * tsconfig.json themselves. Next.js's next-env.d.ts plays the same
+ * role via `next/types/global`.
+ *
+ * `vite` is a peer dep of `@timber-js/app`, so the reference always
+ * resolves in a correctly-installed project.
  */
 const TIMBER_ENV_DTS = [
   '// This file is auto-generated by timber.js. Do not edit.',
-  '// It ensures TypeScript picks up the generated route types.',
-  '// eslint-disable-next-line @typescript-eslint/triple-slash-reference',
+  '// It ensures TypeScript picks up the generated route types and',
+  '// Vite-provided ambient types (CSS, assets, import.meta.env, HMR).',
+  '/* eslint-disable @typescript-eslint/triple-slash-reference */',
   '/// <reference path=".timber/timber-routes.d.ts" />',
+  '/// <reference types="vite/client" />',
   '',
 ].join('\n');
 
@@ -70,6 +123,7 @@ function writeCodegen(ctx: PluginContext): void {
       Promise.all([
         writeFile(routesPath, content, 'utf-8'),
         writeFile(envPath, TIMBER_ENV_DTS, 'utf-8'),
+        writeSegmentTypes(ctx.routeTree!, ctx.appDir, ctx.root),
       ])
     )
     .catch((err) => {
@@ -82,20 +136,48 @@ export function timberRouting(ctx: PluginContext): Plugin {
   /** Track warned files to avoid repeating warnings on rescan. */
   const warnedFiles = new Set<string>();
 
+  /** Maps absolute filesystem directory → segment info for $segment resolution. */
+  let dirToRoute: Map<string, SegmentInfo> = new Map();
+
   function rescan(): void {
+    // Check app/ directory exists before scanning
+    const appDirWarning = checkAppDirExists(ctx.appDir);
+    if (appDirWarning) {
+      const formatted = formatConventionWarnings([appDirWarning]);
+      if (formatted) process.stderr.write(`${formatted}\n`);
+      // Still create an empty tree so the rest of the pipeline doesn't crash
+      ctx.routeTree = {
+        root: {
+          segmentName: '',
+          segmentType: 'static',
+          urlPath: '/',
+          children: [],
+          slots: {},
+        },
+      };
+      return;
+    }
+
     ctx.timer.start('route-scan');
     ctx.routeTree = scanRoutes(ctx.appDir, {
       pageExtensions: ctx.config.pageExtensions,
     });
     ctx.timer.end('route-scan');
+    dirToRoute = buildDirToRouteMap(ctx.routeTree, ctx.appDir);
     writeCodegen(ctx);
 
-    // Lint status files for missing 'use client' directive
-    const warnings = lintStatusFileDirectives(ctx.routeTree);
-    const newWarnings = warnings.filter((w) => !warnedFiles.has(w.filePath));
-    if (newWarnings.length > 0) {
-      for (const w of newWarnings) warnedFiles.add(w.filePath);
-      console.warn(formatStatusFileLintWarnings(newWarnings));
+    // Validate schema keys against filesystem segments.
+    // Warns on stale keys, bracket form mismatches, and missing keys.
+    // See design/41-global-params.md §Auto-Scaffolding
+    warnSchemaValidation(ctx);
+
+    // Lint conventions (empty app, missing methods, missing root layout)
+    const conventionWarnings = lintConventions(ctx.routeTree, ctx.appDir);
+    const newConventionWarnings = conventionWarnings.filter((w) => !warnedFiles.has(w.id));
+    if (newConventionWarnings.length > 0) {
+      for (const w of newConventionWarnings) warnedFiles.add(w.id);
+      const formatted = formatConventionWarnings(newConventionWarnings);
+      if (formatted) process.stderr.write(`${formatted}\n`);
     }
   }
 
@@ -110,7 +192,7 @@ export function timberRouting(ctx: PluginContext): Plugin {
      * - <root>/virtual:timber-route-manifest (Vite SSR build root prefix)
      * - \0virtual:timber-route-manifest (RSC plugin re-imports)
      */
-    resolveId(id: string) {
+    resolveId(id: string, importer?: string) {
       // Strip \0 prefix if present (RSC plugin generates these)
       const cleanId = id.startsWith('\0') ? id.slice(1) : id;
 
@@ -123,6 +205,35 @@ export function timberRouting(ctx: PluginContext): Plugin {
         return RESOLVED_VIRTUAL_ID;
       }
 
+      // TIM-830: Search-params registry virtual module
+      if (
+        cleanId === SEARCH_PARAMS_REGISTRY_ID ||
+        cleanId.endsWith(`/${SEARCH_PARAMS_REGISTRY_ID}`)
+      ) {
+        return RESOLVED_SEARCH_PARAMS_REGISTRY_ID;
+      }
+
+      // TIM-931: Schema virtual module
+      if (cleanId === SCHEMA_ID || cleanId.endsWith(`/${SCHEMA_ID}`)) {
+        return RESOLVED_SCHEMA_ID;
+      }
+
+      // TIM-935: $segment virtual module.
+      // Resolves `import { route } from './$segment'` based on the
+      // importing file's directory in the app/ tree.
+      if (
+        importer &&
+        (cleanId === './$segment' || cleanId === './$segment.js' || cleanId === './$segment.ts')
+      ) {
+        // Strip \0 prefix from importer if present
+        const cleanImporter = importer.startsWith('\0') ? importer.slice(1) : importer;
+        const importerDir = cleanImporter.substring(0, cleanImporter.lastIndexOf('/'));
+        const segmentInfo = dirToRoute.get(importerDir);
+        if (segmentInfo !== undefined) {
+          return `${SEGMENT_PREFIX}${JSON.stringify(segmentInfo)}`;
+        }
+      }
+
       return null;
     },
 
@@ -133,14 +244,36 @@ export function timberRouting(ctx: PluginContext): Plugin {
      * with absolute import paths for all file references.
      */
     load(id: string) {
-      if (id !== RESOLVED_VIRTUAL_ID) return null;
+      if (id === RESOLVED_VIRTUAL_ID) {
+        // If routeTree hasn't been built yet (shouldn't happen), scan now
+        if (!ctx.routeTree) {
+          rescan();
+        }
+        return generateManifestModule(ctx.routeTree!, ctx.root);
+      }
 
-      // If routeTree hasn't been built yet (shouldn't happen), scan now
-      if (!ctx.routeTree) {
-        rescan();
+      if (id === RESOLVED_SEARCH_PARAMS_REGISTRY_ID) {
+        if (!ctx.routeTree) {
+          rescan();
+        }
+        return generateSearchParamsRegistryModule(ctx.routeTree!);
+      }
+
+      if (id === RESOLVED_SCHEMA_ID) {
+        return generateSchemaModule(ctx.appDir);
       }
 
-      return generateManifestModule(ctx.routeTree!);
+      // TIM-935: $segment virtual module — exports route and segmentPath.
+      if (id.startsWith(SEGMENT_PREFIX)) {
+        const info: SegmentInfo = JSON.parse(id.slice(SEGMENT_PREFIX.length));
+        return [
+          `export const ROUTE = ${JSON.stringify(info.route)};`,
+          `export const SEGMENT_PATH = ${JSON.stringify(info.segmentPath)};`,
+          '',
+        ].join('\n');
+      }
+
+      return null;
     },
 
     /**
@@ -168,20 +301,49 @@ export function timberRouting(ctx: PluginContext): Plugin {
       // Watch the app directory
       devServer.watcher.add(ctx.appDir);
 
-      const handleFileChange = (filePath: string) => {
-        // Only react to route-significant files in the app directory
+      /** Snapshot of the last generated manifest, used to detect structural changes. */
+      let lastManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree, ctx.root) : '';
+
+      /**
+       * Handle a route-significant file being added or removed.
+       * Always triggers a full-reload since the route tree structure changed.
+       */
+      const handleStructuralChange = (filePath: string) => {
         if (!filePath.startsWith(ctx.appDir)) return;
         if (!ROUTE_FILE_PATTERNS.test(filePath)) return;
 
-        // Rescan the route tree
         rescan();
-
-        // Invalidate the virtual module in all environments
+        lastManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree, ctx.root) : '';
         invalidateManifest(devServer);
       };
 
-      devServer.watcher.on('add', handleFileChange);
-      devServer.watcher.on('unlink', handleFileChange);
+      /**
+       * Handle a route file's content changing.
+       *
+       * Most content edits (JSX changes, fixing typos) don't affect route
+       * metadata — Vite's React Fast Refresh handles those via normal HMR.
+       * Only rescan and full-reload when route metadata actually changed
+       * (e.g., searchParams export added/removed, metadata export changed).
+       */
+      const handleContentChange = (filePath: string) => {
+        if (!filePath.startsWith(ctx.appDir)) return;
+        if (!ROUTE_FILE_PATTERNS.test(filePath)) return;
+
+        rescan();
+        const newManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree, ctx.root) : '';
+        if (newManifest !== lastManifest) {
+          lastManifest = newManifest;
+          invalidateManifest(devServer);
+        }
+        // Otherwise: content edit didn't change route metadata — let Vite HMR handle it
+      };
+
+      devServer.watcher.on('add', handleStructuralChange);
+      devServer.watcher.on('unlink', handleStructuralChange);
+      // Watch content changes to page files — searchParams detection depends
+      // on file contents (export const searchParams), not just file presence.
+      // But only full-reload when route metadata actually changes.
+      devServer.watcher.on('change', handleContentChange);
       // Also watch renames (which are add+unlink) — handled by the above
     },
   };
@@ -193,14 +355,58 @@ export function timberRouting(ctx: PluginContext): Plugin {
  * When the route tree changes, any environment that has imported the manifest
  * needs to be invalidated so the next request/transform picks up the new tree.
  */
+/** Set of warning keys we've already emitted — avoid repeating on every rescan. */
+const _warnedKeys = new Set<string>();
+
+/**
+ * Validate schema keys against the filesystem route tree.
+ * Warns on stale keys, bracket form mismatches, and missing keys.
+ * Uses the already-scanned route tree instead of re-scanning.
+ */
+function warnSchemaValidation(ctx: PluginContext): void {
+  if (!ctx.routeTree) return;
+  const warnings = validateSchemaAgainstRoutes(ctx.routeTree, ctx.appDir);
+
+  for (const w of warnings) {
+    const warnKey = `${w.type}:${w.key}`;
+    if (_warnedKeys.has(warnKey)) continue;
+    _warnedKeys.add(warnKey);
+
+    switch (w.type) {
+      case 'stale-key':
+        console.warn(`[timber] ${w.message}`);
+        break;
+      case 'bracket-mismatch':
+        console.warn(`[timber] ${w.message}`);
+        break;
+      case 'missing-key':
+        console.warn(`[timber] ${w.message}`);
+        break;
+    }
+  }
+}
+
 function invalidateManifest(server: ViteDevServer): void {
   for (const envName of Object.keys(server.environments)) {
     const env = server.environments[envName];
     if (!env?.moduleGraph) continue;
 
-    const mod = env.moduleGraph.getModuleById(RESOLVED_VIRTUAL_ID);
-    if (mod) {
-      env.moduleGraph.invalidateModule(mod);
+    for (const virtualId of [
+      RESOLVED_VIRTUAL_ID,
+      RESOLVED_SEARCH_PARAMS_REGISTRY_ID,
+      RESOLVED_SCHEMA_ID,
+    ]) {
+      const mod = env.moduleGraph.getModuleById(virtualId);
+      if (mod) {
+        env.moduleGraph.invalidateModule(mod);
+      }
+    }
+
+    // TIM-935: Invalidate all $segment virtual modules (prefixed \0$segment:)
+    for (const mod of env.moduleGraph.idToModuleMap.values()) {
+      if (mod.id?.startsWith(SEGMENT_PREFIX)) {
+        env.moduleGraph.invalidateModule(mod);
+      }
     }
   }
 
@@ -208,13 +414,132 @@ function invalidateManifest(server: ViteDevServer): void {
   server.hot.send({ type: 'full-reload' });
 }
 
+/**
+ * TIM-830: Walk the route tree and collect every page that exports a
+ * `searchParams` definition, then emit a module that statically imports
+ * each export and registers it into the shared search-params registry.
+ *
+ * Keys use the un-interpolated route pattern (e.g. '/products/[id]') so
+ * <Link> can look up the definition from the original `href` prop before
+ * segmentParams are interpolated.
+ */
+/** Schema file extensions to check, in priority order. */
+const SCHEMA_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
+
+/**
+ * TIM-931: Generate the virtual:timber-schema module.
+ *
+ * When app/schema.{ts,tsx,js,jsx} exists, generates a module that
+ * imports the schema and resolves its segmentParams codecs into a
+ * bare-name codec map for runtime coercion.
+ *
+ * When no schema exists, exports null.
+ */
+function generateSchemaModule(appDir: string): string {
+  let schemaPath: string | null = null;
+  for (const ext of SCHEMA_EXTENSIONS) {
+    const candidate = join(appDir, `schema${ext}`);
+    if (existsSync(candidate)) {
+      schemaPath = candidate;
+      break;
+    }
+  }
+
+  if (!schemaPath) {
+    return [
+      '// Auto-generated schema loader — no app/schema.ts found.',
+      'export default null;',
+    ].join('\n');
+  }
+
+  return [
+    '// Auto-generated schema loader — do not edit.',
+    '// Generated by timber-routing plugin (TIM-931).',
+    '',
+    `import schema from ${JSON.stringify(schemaPath)};`,
+    `import { resolveSchemaCodecs } from '@timber-js/app/params';`,
+    '',
+    'const globalCodecs = schema?.segmentParams',
+    '  ? resolveSchemaCodecs(schema.segmentParams)',
+    '  : null;',
+    '',
+    'export default globalCodecs;',
+  ].join('\n');
+}
+
+function generateSearchParamsRegistryModule(tree: RouteTree): string {
+  const entries: Array<{ urlPath: string; filePath: string }> = [];
+
+  function walk(node: SegmentNode): void {
+    // params.ts is the canonical location for `export const searchParams`;
+    // page.tsx is the legacy fallback (see codegen.ts `collectRoutes`).
+    if (node.page) {
+      if (node.params && fileHasSearchParamsExport(node.params.filePath)) {
+        entries.push({ urlPath: node.urlPath, filePath: node.params.filePath });
+      } else if (fileHasSearchParamsExport(node.page.filePath)) {
+        entries.push({ urlPath: node.urlPath, filePath: node.page.filePath });
+      }
+    }
+    for (const child of node.children) walk(child);
+    for (const slot of Object.values(node.slots)) walk(slot);
+  }
+  walk(tree.root);
+
+  // Deterministic order for stable output / snapshots
+  entries.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
+
+  const lines: string[] = [];
+  lines.push('// Auto-generated search-params registry — do not edit.');
+  lines.push('// Generated by timber-routing plugin (TIM-830).');
+  lines.push('');
+  lines.push("import { registerSearchParams } from '@timber-js/app/search-params';");
+  lines.push('');
+
+  // Static imports — Vite/Rolldown tree-shakes the page component body out
+  // of this chunk, leaving only the `searchParams` named export.
+  entries.forEach((entry, i) => {
+    lines.push(`import { searchParams as r${i} } from ${JSON.stringify(entry.filePath)};`);
+  });
+  lines.push('');
+
+  entries.forEach((entry, i) => {
+    lines.push(`registerSearchParams(${JSON.stringify(entry.urlPath)}, r${i});`);
+  });
+  lines.push('');
+
+  // Exporting an empty object keeps the module a real ESM module even
+  // when there are zero entries (no top-level imports in that case).
+  lines.push('export {};');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Lightweight check for a `searchParams` named export. Mirrors
+ * `fileHasExport('searchParams')` in routing/codegen.ts so we stay
+ * in sync with what the type codegen detects.
+ */
+function fileHasSearchParamsExport(filePath: string): boolean {
+  try {
+    if (!existsSync(filePath)) return false;
+    const content = readFileSync(filePath, 'utf-8');
+    return (
+      /export\s+(const|let|var)\s+searchParams\b/.test(content) ||
+      /export\s*\{[^}]*\bsearchParams\b[^}]*\}/.test(content)
+    );
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Generate the virtual module source code for the route manifest.
  *
  * The output is a default-exported object containing the serialized route tree.
  * All file references use absolute paths (required for virtual modules).
  */
-function generateManifestModule(tree: RouteTree): string {
+function generateManifestModule(tree: RouteTree, viteRoot: string): string {
   const imports: string[] = [];
   let importIndex = 0;
 
@@ -301,17 +626,20 @@ function generateManifestModule(tree: RouteTree): string {
         `${nextIndent}denied: { load: ${v}, filePath: ${JSON.stringify(node.denied.filePath)} },`
       );
     }
-    if (node.searchParams) {
-      const v = addImport(node.searchParams);
+    if (node.params) {
+      const v = addImport(node.params);
       parts.push(
-        `${nextIndent}searchParams: { load: ${v}, filePath: ${JSON.stringify(node.searchParams.filePath)} },`
+        `${nextIndent}params: { load: ${v}, filePath: ${JSON.stringify(node.params.filePath)} },`
       );
     }
+    // searchParams is now a named export from page.tsx, not a separate file.
+    // The page module's searchParams export is loaded via the page's lazy import.
+    // Runtime registration happens in the route loader using the page module.
 
     // Status-code files
-    if (node.statusFiles && node.statusFiles.size > 0) {
+    if (node.statusFiles && Object.keys(node.statusFiles).length > 0) {
       const statusEntries: string[] = [];
-      for (const [code, file] of node.statusFiles) {
+      for (const [code, file] of Object.entries(node.statusFiles)) {
         const v = addImport(file);
         statusEntries.push(
           `${nextIndent}    ${JSON.stringify(code)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`
@@ -321,9 +649,9 @@ function generateManifestModule(tree: RouteTree): string {
     }
 
     // JSON status-code files
-    if (node.jsonStatusFiles && node.jsonStatusFiles.size > 0) {
+    if (node.jsonStatusFiles && Object.keys(node.jsonStatusFiles).length > 0) {
       const jsonEntries: string[] = [];
-      for (const [code, file] of node.jsonStatusFiles) {
+      for (const [code, file] of Object.entries(node.jsonStatusFiles)) {
         const v = addImport(file);
         jsonEntries.push(
           `${nextIndent}    ${JSON.stringify(code)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`
@@ -333,9 +661,9 @@ function generateManifestModule(tree: RouteTree): string {
     }
 
     // Legacy status files
-    if (node.legacyStatusFiles && node.legacyStatusFiles.size > 0) {
+    if (node.legacyStatusFiles && Object.keys(node.legacyStatusFiles).length > 0) {
       const legacyEntries: string[] = [];
-      for (const [name, file] of node.legacyStatusFiles) {
+      for (const [name, file] of Object.entries(node.legacyStatusFiles)) {
         const v = addImport(file);
         legacyEntries.push(
           `${nextIndent}    ${JSON.stringify(name)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`
@@ -347,9 +675,9 @@ function generateManifestModule(tree: RouteTree): string {
     }
 
     // Metadata route files (sitemap.ts, robots.ts, icon.tsx, etc.)
-    if (node.metadataRoutes && node.metadataRoutes.size > 0) {
+    if (node.metadataRoutes && Object.keys(node.metadataRoutes).length > 0) {
       const metaEntries: string[] = [];
-      for (const [name, file] of node.metadataRoutes) {
+      for (const [name, file] of Object.entries(node.metadataRoutes)) {
         const v = addImport(file);
         metaEntries.push(
           `${nextIndent}    ${JSON.stringify(name)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`
@@ -367,9 +695,11 @@ function generateManifestModule(tree: RouteTree): string {
     }
 
     // Parallel slots
-    if (node.slots.size > 0) {
+    const slotKeys = Object.keys(node.slots);
+    if (slotKeys.length > 0) {
       const slotEntries: string[] = [];
-      for (const [slotName, slotNode] of node.slots) {
+      for (const slotName of slotKeys) {
+        const slotNode = node.slots[slotName]!;
         slotEntries.push(
           `${nextIndent}    ${JSON.stringify(slotName)}: ${serializeNode(slotNode, nextIndent + '  ')}`
         );
@@ -391,6 +721,13 @@ function generateManifestModule(tree: RouteTree): string {
     proxyLine = `  proxy: { load: ${v}, filePath: ${JSON.stringify(tree.proxy.filePath)} },`;
   }
 
+  // Global error page (Tier 2)
+  let globalErrorLine = '';
+  if (tree.globalError) {
+    const v = addImport(tree.globalError);
+    globalErrorLine = `  globalError: { load: ${v}, filePath: ${JSON.stringify(tree.globalError.filePath)} },`;
+  }
+
   // Interception rewrites — computed at build time from the route tree.
   // Only interceptedPattern and interceptingPrefix are needed at runtime.
   const rewrites = collectInterceptionRewrites(tree.root);
@@ -406,7 +743,9 @@ function generateManifestModule(tree: RouteTree): string {
     ...imports,
     '',
     'const manifest = {',
+    `  viteRoot: ${JSON.stringify(viteRoot)},`,
     proxyLine,
+    globalErrorLine,
     rewritesLine,
     `  root: ${rootSerialized},`,
     '};',

package/src/plugins/server-bundle.ts

@@ -13,6 +13,31 @@
 
 import type { Plugin } from 'vite';
 
+// Build-time-only packages that must never be bundled into the runtime
+// server environments. With `noExternal: true` rolldown otherwise follows
+// the transitive graph through the user's `timber.config.ts` (loaded by the
+// `virtual:timber-cache-handler` dynamic import) into adapter code, dragging
+// build tooling into the prod server bundle. The most visible symptom is
+// rolldown trying to parse `fsevents.node` as JS and failing with
+// `[UNLOADABLE_DEPENDENCY] … stream did not contain valid UTF-8`.
+//
+//   - `nitro`, `@mdx-js/rollup`              — build-time tooling reachable
+//     transitively through adapter modules and timber's own MDX activation.
+//   - `rollup`                                — pulled in by nitro and
+//     @mdx-js/rollup; declares `fsevents` as an optional native dep.
+//   - `fsevents`, `chokidar`                  — native/optional deps of
+//     rollup/vite. They are macOS-only file watchers with no runtime use
+//     in a server bundle.
+//
+// Mirrored on both rsc and ssr environments. See TIM-988.
+const BUILD_ONLY_EXTERNALS: string[] = [
+  'nitro',
+  'rollup',
+  '@mdx-js/rollup',
+  'fsevents',
+  'chokidar',
+];
+
 export function timberServerBundle(): Plugin[] {
   const bundlePlugin: Plugin = {
     name: 'timber-server-bundle',
@@ -80,11 +105,11 @@ export function timberServerBundle(): Plugin[] {
         ssr: { target: 'webworker' },
         environments: {
           rsc: {
-            resolve: { noExternal: true },
+            resolve: { noExternal: true, external: BUILD_ONLY_EXTERNALS },
             define: serverDefine,
           },
           ssr: {
-            resolve: { noExternal: true },
+            resolve: { noExternal: true, external: BUILD_ONLY_EXTERNALS },
             define: serverDefine,
           },
         },
@@ -137,5 +162,36 @@ export function timberServerBundle(): Plugin[] {
     },
   };
 
-  return [bundlePlugin, esmInitFixPlugin];
+  // Fix Rolldown's `createRequire(import.meta.url)` CJS interop shim for
+  // Cloudflare Workers. Rolldown emits this for CJS dependencies (e.g.
+  // @opentelemetry/context-async-hooks) that use `require()`. On Workers,
+  // `import.meta.url` is `undefined` for non-entry modules, causing:
+  //   TypeError: The argument 'path' must be a file URL object, a file URL
+  //   string, or an absolute path string. Received 'undefined'
+  //
+  // The fix: provide a fallback URL when `import.meta.url` is undefined.
+  // The actual URL doesn't matter — `createRequire` only needs it for
+  // resolving relative paths, but the only `__require()` calls are for
+  // Node built-ins (events, async_hooks) which resolve from any base.
+  //
+  // The top-level `ssr: { target: 'webworker' }` was supposed to prevent
+  // this, but it doesn't propagate to custom environments (rsc) in Vite's
+  // Environment API. See LOCAL-405.
+  const createRequireFixPlugin: Plugin = {
+    name: 'timber-create-require-fix',
+    applyToEnvironment(environment) {
+      return environment.name === 'rsc' || environment.name === 'ssr';
+    },
+    renderChunk(code) {
+      const pattern = 'createRequire(import.meta.url)';
+      if (!code.includes(pattern)) return null;
+
+      return {
+        code: code.replace(pattern, 'createRequire(import.meta.url || "file:///app")'),
+        map: null,
+      };
+    },
+  };
+
+  return [bundlePlugin, esmInitFixPlugin, createRequireFixPlugin];
 }