@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

package/src/plugins/routing.ts

@@ -9,93 +9,129 @@
  */
 
 import type { Plugin, ViteDevServer } from 'vite';
-import { writeFile, mkdir } from 'node:fs/promises';
 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.ts';
+import { buildDirToRouteMap, type SegmentInfo } from '../routing/segment-codegen.ts';
+import { writeRouteCodegen, flushCodegenWrites } from '../routing/codegen-write.ts';
+import { validateSchemaAgainstRoutes } from '../routing/schema-validation.ts';
+import { generateManifestModule, generateSchemaModule } from '../routing/manifest-codegen.ts';
 import {
-  lintStatusFileDirectives,
-  formatStatusFileLintWarnings,
-} from '#/routing/status-file-lint.js';
-import type { RouteTree, SegmentNode, RouteFile } from '#/routing/types.js';
-import type { PluginContext } from '#/index.js';
+  lintConventions,
+  checkAppDirExists,
+  formatConventionWarnings,
+} from '../routing/convention-lint.ts';
+import type { PluginContext } from '../plugin-context.ts';
 
 const VIRTUAL_MODULE_ID = 'virtual:timber-route-manifest';
 const RESOLVED_VIRTUAL_ID = `\0${VIRTUAL_MODULE_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|schema|\d{3}|[45]xx|sitemap|robots|manifest|favicon|icon|opengraph-image|apple-icon)\./;
 
 /**
  * Create the timber-routing Vite plugin.
  *
  * Hooks: resolveId, load, buildStart, configureServer
  */
-/** Absolute path to the generated route map declaration file. */
-const CODEGEN_OUTPUT = '.timber/timber-routes.d.ts';
-
-/**
- * Content of the timber-env.d.ts file written to the project root.
- *
- * 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.
- */
-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',
-  '/// <reference path=".timber/timber-routes.d.ts" />',
-  '',
-].join('\n');
-
 /**
  * Write the generated route map and the timber-env.d.ts reference file.
  *
- * Fire-and-forget — never awaited to avoid blocking the hot path.
- * Errors are swallowed; a missing .d.ts is a developer UX issue, not a runtime failure.
+ * Not awaited, to avoid blocking the hot path — use `flushCodegenWrites()` to
+ * wait for the writes to land. Failures are logged, not thrown: a missing .d.ts
+ * is a developer UX issue in dev/build, not a runtime failure. (`timber check`
+ * calls `writeRouteCodegen` directly and does treat a failure as fatal.)
  */
 function writeCodegen(ctx: PluginContext): void {
   if (!ctx.routeTree) return;
-  const timberDir = join(ctx.root, '.timber');
-  const content = generateRouteMap(ctx.routeTree, { appDir: ctx.appDir, outputDir: timberDir });
-  const routesPath = join(ctx.root, CODEGEN_OUTPUT);
-  const envPath = join(ctx.root, 'timber-env.d.ts');
-  mkdir(timberDir, { recursive: true })
-    .then(() =>
-      Promise.all([
-        writeFile(routesPath, content, 'utf-8'),
-        writeFile(envPath, TIMBER_ENV_DTS, 'utf-8'),
-      ])
-    )
-    .catch((err) => {
-      // Non-fatal — types are a dev convenience, but log so issues are visible
-      console.warn('[timber] Failed to write codegen output:', err);
-    });
+  // The analyze crawl child only needs the route tree for
+  // classification — codegen writes are fire-and-forget and can be
+  // truncated by the child's process.exit, leaving partial .d.ts
+  // files on disk.
+  if (process.env.TIMBER_ANALYZE === '1') return;
+  void writeRouteCodegen(ctx.routeTree, ctx.appDir, ctx.root).catch((err) => {
+    console.warn('[timber] Failed to write codegen output:', err);
+  });
 }
 
 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, {
+    const tree = scanRoutes(ctx.appDir, {
       pageExtensions: ctx.config.pageExtensions,
     });
     ctx.timer.end('route-scan');
+
+    // Lint conventions (empty app, missing methods, missing root layout).
+    // Runs on the scanned tree *before* it is published: error-level findings
+    // are proven-fatal misconfigurations — the app cannot render at all — so
+    // the tree must not reach codegen, the manifest, or a live dev server's
+    // module graph. Fail loudly rather than let the developer discover it as
+    // an unattributed React error on an unrelated page (TIM-1329). Never
+    // deduplicated against `warnedFiles`: an error must not be downgraded to
+    // silence by an earlier scan in the same process.
+    const conventionWarnings = lintConventions(tree, ctx.appDir);
+    const fatal = conventionWarnings.filter((w) => w.level === 'error');
+    if (fatal.length > 0) {
+      throw new Error(formatConventionWarnings(fatal, { color: false }));
+    }
+
+    ctx.routeTree = tree;
+    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);
+
+    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 +146,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 +159,27 @@ export function timberRouting(ctx: PluginContext): Plugin {
         return RESOLVED_VIRTUAL_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 +190,29 @@ 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 (id === RESOLVED_SCHEMA_ID) {
+        return generateSchemaModule(ctx.appDir);
+      }
 
-      // If routeTree hasn't been built yet (shouldn't happen), scan now
-      if (!ctx.routeTree) {
-        rescan();
+      // 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 generateManifestModule(ctx.routeTree!);
+      return null;
     },
 
     /**
@@ -154,6 +226,19 @@ export function timberRouting(ctx: PluginContext): Plugin {
       rescan();
     },
 
+    /**
+     * Wait for the codegen writes started by `buildStart` before the build
+     * reports done.
+     *
+     * `writeCodegen` runs unawaited so route scanning never blocks on disk.
+     * Without this the build can finish — and the CLI can exit — while the
+     * generated `.d.ts` files are still being written, leaving a project root
+     * with no route types after an apparently successful build.
+     */
+    closeBundle() {
+      return flushCodegenWrites();
+    },
+
     /**
      * Set up file watcher in dev mode.
      *
@@ -168,20 +253,102 @@ 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) : '';
+
+      /**
+       * Rescan without letting a rejected route tree kill the dev server.
+       *
+       * `rescan()` throws on hard misconfigurations — duplicate conventions,
+       * route collisions, a status file that is not a client component. Those
+       * throws are correct at startup and in `vite build`, but here they run
+       * inside a chokidar listener, where an exception is an unhandled
+       * rejection that takes the process down mid-edit. Report and keep the
+       * last good tree so the server stays up and the fix is one save away.
+       *
+       * Returns false when the scan failed, so callers skip the manifest
+       * regeneration that would otherwise publish a stale tree as fresh.
+       */
+      /**
+       * True while the last rescan is still failing.
+       *
+       * Recovery has to force a reload even when the manifest is byte-identical.
+       * Adding a missing `'use client'` back to a status file changes no route
+       * metadata, so the content-change path would send nothing and leave the
+       * error overlay on screen over a page that is now fine.
+       */
+      let scanFailed = false;
+
+      const rescanSafely = (): boolean => {
+        try {
+          rescan();
+          if (scanFailed) {
+            scanFailed = false;
+            // Force the reload: see `scanFailed`.
+            lastManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree, ctx.root) : '';
+            invalidateManifest(devServer);
+          }
+          return true;
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          process.stderr.write(
+            `[timber] Route scan failed — keeping previous routes.\n${message}\n`
+          );
+          scanFailed = true;
+
+          // The terminal is not the only surface that needs this. Keeping the
+          // previous tree keeps the *server* alive, but it does not un-edit the
+          // file: Vite still re-transforms it, so the very next render hits the
+          // failure this scan just diagnosed — and the browser's version of it
+          // names nothing. Put the diagnosis where the developer is looking.
+          devServer.hot.send({
+            type: 'error',
+            err: { message, stack: '', plugin: 'timber-routing' },
+          });
+          return false;
+        }
+      };
+
+      /**
+       * 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
+        if (!rescanSafely()) return;
+        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;
+
+        if (!rescanSafely()) return;
+        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,228 +360,57 @@ 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.
  */
-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);
-    }
-  }
-
-  // Trigger HMR full reload — route changes are structural
-  server.hot.send({ type: 'full-reload' });
-}
+/** Set of warning keys we've already emitted — avoid repeating on every rescan. */
+const _warnedKeys = new Set<string>();
 
 /**
- * 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).
+ * 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 generateManifestModule(tree: RouteTree): string {
-  const imports: string[] = [];
-  let importIndex = 0;
-
-  /**
-   * Create a lazy import expression for a route file.
-   * Returns the import variable name.
-   */
-  function addImport(file: RouteFile): string {
-    const varName = `_route${importIndex++}`;
-    imports.push(`const ${varName} = () => import("${file.filePath}");`);
-    return varName;
-  }
-
-  /**
-   * Serialize a segment node to a JS object literal.
-   */
-  function serializeNode(node: SegmentNode, indent: string): string {
-    const nextIndent = indent + '  ';
-    const parts: string[] = [];
-
-    parts.push(`${nextIndent}segmentName: ${JSON.stringify(node.segmentName)},`);
-    parts.push(`${nextIndent}segmentType: ${JSON.stringify(node.segmentType)},`);
-    parts.push(`${nextIndent}urlPath: ${JSON.stringify(node.urlPath)},`);
-
-    if (node.paramName) {
-      parts.push(`${nextIndent}paramName: ${JSON.stringify(node.paramName)},`);
-    }
-
-    if (node.interceptionMarker) {
-      parts.push(`${nextIndent}interceptionMarker: ${JSON.stringify(node.interceptionMarker)},`);
-    }
-    if (node.interceptedSegmentName) {
-      parts.push(
-        `${nextIndent}interceptedSegmentName: ${JSON.stringify(node.interceptedSegmentName)},`
-      );
-    }
-
-    // File conventions — absolute paths as lazy imports
-    if (node.page) {
-      const v = addImport(node.page);
-      parts.push(
-        `${nextIndent}page: { load: ${v}, filePath: ${JSON.stringify(node.page.filePath)} },`
-      );
-    }
-    if (node.layout) {
-      const v = addImport(node.layout);
-      parts.push(
-        `${nextIndent}layout: { load: ${v}, filePath: ${JSON.stringify(node.layout.filePath)} },`
-      );
-    }
-    if (node.middleware) {
-      const v = addImport(node.middleware);
-      parts.push(
-        `${nextIndent}middleware: { load: ${v}, filePath: ${JSON.stringify(node.middleware.filePath)} },`
-      );
-    }
-    if (node.access) {
-      const v = addImport(node.access);
-      parts.push(
-        `${nextIndent}access: { load: ${v}, filePath: ${JSON.stringify(node.access.filePath)} },`
-      );
-    }
-    if (node.route) {
-      const v = addImport(node.route);
-      parts.push(
-        `${nextIndent}route: { load: ${v}, filePath: ${JSON.stringify(node.route.filePath)} },`
-      );
-    }
-    if (node.error) {
-      const v = addImport(node.error);
-      parts.push(
-        `${nextIndent}error: { load: ${v}, filePath: ${JSON.stringify(node.error.filePath)} },`
-      );
-    }
-    if (node.default) {
-      const v = addImport(node.default);
-      parts.push(
-        `${nextIndent}default: { load: ${v}, filePath: ${JSON.stringify(node.default.filePath)} },`
-      );
-    }
-    if (node.denied) {
-      const v = addImport(node.denied);
-      parts.push(
-        `${nextIndent}denied: { load: ${v}, filePath: ${JSON.stringify(node.denied.filePath)} },`
-      );
-    }
-    if (node.searchParams) {
-      const v = addImport(node.searchParams);
-      parts.push(
-        `${nextIndent}searchParams: { load: ${v}, filePath: ${JSON.stringify(node.searchParams.filePath)} },`
-      );
-    }
-
-    // Status-code files
-    if (node.statusFiles && node.statusFiles.size > 0) {
-      const statusEntries: string[] = [];
-      for (const [code, file] of node.statusFiles) {
-        const v = addImport(file);
-        statusEntries.push(
-          `${nextIndent}    ${JSON.stringify(code)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`
-        );
-      }
-      parts.push(`${nextIndent}statusFiles: {\n${statusEntries.join(',\n')}\n${nextIndent}},`);
-    }
-
-    // JSON status-code files
-    if (node.jsonStatusFiles && node.jsonStatusFiles.size > 0) {
-      const jsonEntries: string[] = [];
-      for (const [code, file] of node.jsonStatusFiles) {
-        const v = addImport(file);
-        jsonEntries.push(
-          `${nextIndent}    ${JSON.stringify(code)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`
-        );
-      }
-      parts.push(`${nextIndent}jsonStatusFiles: {\n${jsonEntries.join(',\n')}\n${nextIndent}},`);
+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;
     }
+  }
+}
 
-    // Legacy status files
-    if (node.legacyStatusFiles && node.legacyStatusFiles.size > 0) {
-      const legacyEntries: string[] = [];
-      for (const [name, file] of node.legacyStatusFiles) {
-        const v = addImport(file);
-        legacyEntries.push(
-          `${nextIndent}    ${JSON.stringify(name)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`
-        );
-      }
-      parts.push(
-        `${nextIndent}legacyStatusFiles: {\n${legacyEntries.join(',\n')}\n${nextIndent}},`
-      );
-    }
+function invalidateManifest(server: ViteDevServer): void {
+  for (const envName of Object.keys(server.environments)) {
+    const env = server.environments[envName];
+    if (!env?.moduleGraph) continue;
 
-    // Metadata route files (sitemap.ts, robots.ts, icon.tsx, etc.)
-    if (node.metadataRoutes && node.metadataRoutes.size > 0) {
-      const metaEntries: string[] = [];
-      for (const [name, file] of node.metadataRoutes) {
-        const v = addImport(file);
-        metaEntries.push(
-          `${nextIndent}    ${JSON.stringify(name)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`
-        );
+    for (const virtualId of [RESOLVED_VIRTUAL_ID, RESOLVED_SCHEMA_ID]) {
+      const mod = env.moduleGraph.getModuleById(virtualId);
+      if (mod) {
+        env.moduleGraph.invalidateModule(mod);
       }
-      parts.push(`${nextIndent}metadataRoutes: {\n${metaEntries.join(',\n')}\n${nextIndent}},`);
     }
 
-    // Children
-    if (node.children.length > 0) {
-      const childNodes = node.children.map((c) => serializeNode(c, nextIndent));
-      parts.push(`${nextIndent}children: [\n${childNodes.join(',\n')}\n${nextIndent}],`);
-    } else {
-      parts.push(`${nextIndent}children: [],`);
-    }
-
-    // Parallel slots
-    if (node.slots.size > 0) {
-      const slotEntries: string[] = [];
-      for (const [slotName, slotNode] of node.slots) {
-        slotEntries.push(
-          `${nextIndent}    ${JSON.stringify(slotName)}: ${serializeNode(slotNode, nextIndent + '  ')}`
-        );
+    // 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);
       }
-      parts.push(`${nextIndent}slots: {\n${slotEntries.join(',\n')}\n${nextIndent}},`);
-    } else {
-      parts.push(`${nextIndent}slots: {},`);
     }
-
-    return `${indent}{\n${parts.join('\n')}\n${indent}}`;
   }
 
-  const rootSerialized = serializeNode(tree.root, '  ');
-
-  // Proxy file
-  let proxyLine = '';
-  if (tree.proxy) {
-    const v = addImport(tree.proxy);
-    proxyLine = `  proxy: { load: ${v}, filePath: ${JSON.stringify(tree.proxy.filePath)} },`;
-  }
-
-  // Interception rewrites — computed at build time from the route tree.
-  // Only interceptedPattern and interceptingPrefix are needed at runtime.
-  const rewrites = collectInterceptionRewrites(tree.root);
-  const rewritesLine =
-    rewrites.length > 0
-      ? `  interceptionRewrites: ${JSON.stringify(rewrites.map((r) => ({ interceptedPattern: r.interceptedPattern, interceptingPrefix: r.interceptingPrefix })))},`
-      : '';
-
-  const code = [
-    '// Auto-generated route manifest — do not edit.',
-    '// Generated by timber-routing plugin.',
-    '',
-    ...imports,
-    '',
-    'const manifest = {',
-    proxyLine,
-    rewritesLine,
-    `  root: ${rootSerialized},`,
-    '};',
-    '',
-    'export default manifest;',
-  ]
-    .filter((line) => line !== undefined && line !== '')
-    .join('\n');
-
-  return code;
+  // Trigger HMR full reload — route changes are structural
+  server.hot.send({ type: 'full-reload' });
 }