@rangojs/router 0.0.0-experimental.35 → 0.0.0-experimental.358c376d

package/src/build/route-types/router-processing.ts

@@ -15,10 +15,13 @@ import {
 import ts from "typescript";
 import { generateRouteTypesSource } from "./codegen.js";
 import type { ScanFilter } from "./scan-filter.js";
+import { firstCodeMatchIndex } from "./source-scan.js";
 import {
   resolveImportedVariable,
   resolveImportPath,
   buildCombinedRouteMapWithSearch,
+  createScanMemo,
+  type ScanMemo,
   type UnresolvableInclude,
 } from "./include-resolution.js";
 import { findUrlsVariableNames } from "./per-module-writer.js";
@@ -38,6 +41,8 @@ function countPublicRouteEntries(source: string): number {
 }
 
 const ROUTER_CALL_PATTERN = /\bcreateRouter\s*[<(]/;
+// Global variant for the code-region scan (firstCodeMatchIndex sets lastIndex).
+const ROUTER_CALL_PATTERN_G = /\bcreateRouter\s*[<(]/g;
 
 function isRoutableSourceFile(name: string): boolean {
   return (
@@ -45,12 +50,39 @@ function isRoutableSourceFile(name: string): boolean {
       name.endsWith(".tsx") ||
       name.endsWith(".js") ||
       name.endsWith(".jsx")) &&
-    !name.includes(".gen.")
+    !name.includes(".gen.") &&
+    !name.includes(".test.") &&
+    !name.includes(".spec.")
   );
 }
 
-function findRouterFilesRecursive(
+function isExcludedScanDir(name: string): boolean {
+  return (
+    name === "node_modules" ||
+    name === "dist" ||
+    name === "coverage" ||
+    name === "__tests__" ||
+    name === "__mocks__" ||
+    name.startsWith(".")
+  );
+}
+
+/**
+ * Recursively collect source files whose code contains `pattern` (a comment- or
+ * string-only mention is ignored via firstCodeMatchIndex). Shared by createRouter
+ * and createHostRouter discovery, which differ only in the call pattern and
+ * `stopAtMatchDir`: createRouter treats a directory containing a match as a router
+ * root and stops descending it; createHostRouter descends the whole tree (the host
+ * entry sits above the sub-app router roots).
+ *
+ * `pattern` is the non-global tester (no lastIndex state); `patternG` is its global
+ * twin for the code-region scan.
+ */
+function findCallSiteFilesRecursive(
   dir: string,
+  pattern: RegExp,
+  patternG: RegExp,
+  stopAtMatchDir: boolean,
   filter: ScanFilter | undefined,
   results: string[],
 ): void {
@@ -59,19 +91,18 @@ function findRouterFilesRecursive(
     entries = readdirSync(dir, { withFileTypes: true });
   } catch (err) {
     console.warn(
-      `[rsc-router] Failed to scan directory ${dir}: ${(err as Error).message}`,
+      `[rango] Failed to scan directory ${dir}: ${(err as Error).message}`,
     );
     return;
   }
 
   const childDirs: string[] = [];
-  const routerFilesInDir: string[] = [];
+  const matchesInDir: string[] = [];
 
   for (const entry of entries) {
     const fullPath = join(dir, entry.name);
     if (entry.isDirectory()) {
-      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
-      childDirs.push(fullPath);
+      if (!isExcludedScanDir(entry.name)) childDirs.push(fullPath);
       continue;
     }
 
@@ -80,23 +111,36 @@ function findRouterFilesRecursive(
 
     try {
       const source = readFileSync(fullPath, "utf-8");
-      if (ROUTER_CALL_PATTERN.test(source)) {
-        routerFilesInDir.push(fullPath);
+      // Fast path: most files contain no `createRouter(` at all, so the cheap
+      // raw regex short-circuits before the code-region scan. Only a file that
+      // mentions the token (real call OR a comment/string mention) is rescanned
+      // over code regions — allocation-free, never building a stripped copy —
+      // so a mention inside a comment or string is not mistaken for a real
+      // router file (which previously triggered a spurious "Multiple routers
+      // found" error).
+      if (pattern.test(source) && firstCodeMatchIndex(source, patternG) >= 0) {
+        matchesInDir.push(fullPath);
       }
     } catch {
       continue;
     }
   }
 
-  // A directory that contains a router file is treated as a router root.
-  // Once found, deeper directories are skipped to avoid redundant scans.
-  if (routerFilesInDir.length > 0) {
-    results.push(...routerFilesInDir);
-    return;
-  }
-
-  for (const childDir of childDirs) {
-    findRouterFilesRecursive(childDir, filter, results);
+  results.push(...matchesInDir);
+
+  // createRouter (stopAtMatchDir): a directory that contains a match is a router
+  // root, so deeper directories are skipped. createHostRouter: always descend.
+  if (!stopAtMatchDir || matchesInDir.length === 0) {
+    for (const childDir of childDirs) {
+      findCallSiteFilesRecursive(
+        childDir,
+        pattern,
+        patternG,
+        stopAtMatchDir,
+        filter,
+        results,
+      );
+    }
   }
 }
 
@@ -132,7 +176,7 @@ export function findNestedRouterConflict(
 
 export function formatNestedRouterConflictError(
   conflict: { ancestor: string; nested: string },
-  prefix = "[rsc-router]",
+  prefix = "[rango]",
 ): string {
   return (
     `${prefix} Nested router roots are not supported.\n` +
@@ -147,13 +191,51 @@ export function formatNestedRouterConflictError(
 // ---------------------------------------------------------------------------
 
 /**
- * Extract the url patterns variable from a router file using AST.
- * Detects two patterns:
- *   1. createRouter(...).routes(variableName)
- *   2. createRouter({ urls: variableName, ... })
- * Returns the local variable name.
+ * Result of extracting URL patterns from a router file.
+ * - "variable": a named variable reference (e.g., `.routes(patterns)` or `urls: patterns`)
+ * - "inline": an inline builder function (e.g., `.routes(({ path }) => [...])` or `urls: ({ path }) => [...]`)
  */
-export function extractUrlsVariableFromRouter(code: string): string | null {
+export type UrlsExtractionResult =
+  | { kind: "variable"; name: string }
+  | { kind: "inline"; block: string };
+
+function isCreateRouterCall(node: ts.Node): boolean {
+  if (!ts.isCallExpression(node)) return false;
+  const callee = node.expression;
+  return ts.isIdentifier(callee) && callee.text === "createRouter";
+}
+
+function extractUrlsArgument(
+  node: ts.Expression,
+  sourceFile: ts.SourceFile,
+): UrlsExtractionResult | null {
+  if (ts.isIdentifier(node)) {
+    return { kind: "variable", name: node.text };
+  }
+  if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
+    return { kind: "inline", block: node.getText(sourceFile) };
+  }
+  return null;
+}
+
+/** Return a createRouter call chain in runtime registration order. */
+function collectCreateRouterCallChain(
+  endpoint: ts.CallExpression,
+): ts.CallExpression[] | null {
+  const calls: ts.CallExpression[] = [];
+  let current = endpoint;
+
+  while (true) {
+    calls.push(current);
+    if (isCreateRouterCall(current)) return calls.reverse();
+    if (!ts.isPropertyAccessExpression(current.expression)) return null;
+    const receiver = current.expression.expression;
+    if (!ts.isCallExpression(receiver)) return null;
+    current = receiver;
+  }
+}
+
+function extractAllUrlsFromRouter(code: string): UrlsExtractionResult[] {
   const sourceFile = ts.createSourceFile(
     "router.tsx",
     code,
@@ -161,52 +243,102 @@ export function extractUrlsVariableFromRouter(code: string): string | null {
     true,
     ts.ScriptKind.TSX,
   );
-  let result: string | null = null;
-
-  function isCreateRouterCall(node: ts.Node): boolean {
-    if (!ts.isCallExpression(node)) return false;
-    const callee = node.expression;
-    return ts.isIdentifier(callee) && callee.text === "createRouter";
-  }
+  let result: UrlsExtractionResult[] | null = null;
 
   function visit(node: ts.Node) {
     if (result) return;
+    if (ts.isCallExpression(node)) {
+      const chain = collectCreateRouterCallChain(node);
+      if (chain) {
+        const extracted: UrlsExtractionResult[] = [];
+        const createRouterCall = chain[0];
+
+        for (const callArg of createRouterCall.arguments) {
+          if (!ts.isObjectLiteralExpression(callArg)) continue;
+          for (const prop of callArg.properties) {
+            if (
+              !ts.isPropertyAssignment(prop) ||
+              !ts.isIdentifier(prop.name) ||
+              prop.name.text !== "urls"
+            ) {
+              continue;
+            }
+            const urls = extractUrlsArgument(prop.initializer, sourceFile);
+            if (urls) extracted.push(urls);
+            break;
+          }
+        }
 
-    // Pattern 1: createRouter(...).routes(variableName)
-    // The AST shape is CallExpression(.routes) -> PropertyAccessExpression -> CallExpression(createRouter)
-    if (
-      ts.isCallExpression(node) &&
-      ts.isPropertyAccessExpression(node.expression) &&
-      node.expression.name.text === "routes" &&
-      node.arguments.length >= 1 &&
-      ts.isIdentifier(node.arguments[0])
-    ) {
-      // Walk up the chain: createRouter().middleware(...).routes(x) etc.
-      // The innermost call should be createRouter(...)
-      let inner: ts.Expression = node.expression.expression;
-      while (
-        ts.isCallExpression(inner) &&
-        ts.isPropertyAccessExpression(inner.expression)
-      ) {
-        inner = inner.expression.expression;
-      }
-      if (isCreateRouterCall(inner)) {
-        result = (node.arguments[0] as ts.Identifier).text;
-        return;
+        for (const call of chain.slice(1)) {
+          if (
+            !ts.isPropertyAccessExpression(call.expression) ||
+            call.expression.name.text !== "routes" ||
+            call.arguments.length === 0
+          ) {
+            continue;
+          }
+          const urls = extractUrlsArgument(call.arguments[0], sourceFile);
+          if (urls) extracted.push(urls);
+        }
+
+        if (extracted.length > 0) {
+          result = extracted;
+          return;
+        }
       }
     }
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return result ?? [];
+}
+
+/**
+ * Extract the url patterns from a router file using AST.
+ * Detects four patterns:
+ *   1. createRouter(...).routes(variableName)
+ *   2. createRouter({ urls: variableName, ... })
+ *   3. createRouter(...).routes(({ path, ... }) => [...])
+ *   4. createRouter({ urls: ({ path, ... }) => [...], ... })
+ * Returns either a variable name or an inline code block.
+ */
+export function extractUrlsFromRouter(
+  code: string,
+): UrlsExtractionResult | null {
+  const extractions = extractAllUrlsFromRouter(code);
+  return extractions[extractions.length - 1] ?? null;
+}
+
+/**
+ * Extract the `basename` string literal from createRouter({ basename: "..." }).
+ * Returns the basename value or undefined if not present.
+ */
+export function extractBasenameFromRouter(code: string): string | undefined {
+  const sourceFile = ts.createSourceFile(
+    "router.tsx",
+    code,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+  let result: string | undefined;
 
-    // Pattern 2: createRouter({ urls: variableName, ... })
-    if (isCreateRouterCall(node)) {
-      const callExpr = node as ts.CallExpression;
-      for (const arg of callExpr.arguments) {
+  function visit(node: ts.Node) {
+    if (result !== undefined) return;
+    if (
+      ts.isCallExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.expression.text === "createRouter"
+    ) {
+      for (const arg of node.arguments) {
         if (ts.isObjectLiteralExpression(arg)) {
           for (const prop of arg.properties) {
             if (
               ts.isPropertyAssignment(prop) &&
               ts.isIdentifier(prop.name) &&
-              prop.name.text === "urls" &&
-              ts.isIdentifier(prop.initializer)
+              prop.name.text === "basename" &&
+              ts.isStringLiteral(prop.initializer)
             ) {
               result = prop.initializer.text;
               return;
@@ -215,7 +347,6 @@ export function extractUrlsVariableFromRouter(code: string): string | null {
         }
       }
     }
-
     ts.forEachChild(node, visit);
   }
 
@@ -223,9 +354,134 @@ export function extractUrlsVariableFromRouter(code: string): string | null {
   return result;
 }
 
+/** Apply a basename prefix to all route patterns in a result set. */
+function applyBasenameToRoutes(
+  result: {
+    routes: Record<string, string>;
+    searchSchemas: Record<string, Record<string, string>>;
+  },
+  basename: string,
+): {
+  routes: Record<string, string>;
+  searchSchemas: Record<string, Record<string, string>>;
+} {
+  const prefixed: Record<string, string> = {};
+  for (const [name, pattern] of Object.entries(result.routes)) {
+    if (pattern === "/") {
+      prefixed[name] = basename;
+    } else if (basename.endsWith("/") && pattern.startsWith("/")) {
+      prefixed[name] = basename + pattern.slice(1);
+    } else {
+      prefixed[name] = basename + pattern;
+    }
+  }
+  return { routes: prefixed, searchSchemas: result.searchSchemas };
+}
+
+type RouteMapWithSearch = {
+  routes: Record<string, string>;
+  searchSchemas: Record<string, Record<string, string>>;
+};
+
+function resolveRouterUrlsExtraction(
+  routerFilePath: string,
+  routerSource: string,
+  extraction: UrlsExtractionResult,
+  diagnosticsOut: UnresolvableInclude[] | undefined,
+  memo: ScanMemo,
+): RouteMapWithSearch {
+  if (extraction.kind === "inline") {
+    return buildCombinedRouteMapWithSearch(
+      routerFilePath,
+      undefined,
+      new Set(),
+      diagnosticsOut,
+      extraction.block,
+      memo,
+    );
+  }
+
+  const imported = resolveImportedVariable(routerSource, extraction.name);
+  if (imported) {
+    const targetFile = resolveImportPath(imported.specifier, routerFilePath);
+    if (!targetFile) {
+      diagnosticsOut?.push({
+        pathPrefix: "/",
+        namePrefix: null,
+        reason: "file-not-found",
+        sourceFile: routerFilePath,
+        detail: `import "${imported.specifier}" resolved to no file`,
+      });
+      return { routes: {}, searchSchemas: {} };
+    }
+    return buildCombinedRouteMapWithSearch(
+      targetFile,
+      imported.exportedName,
+      new Set(),
+      diagnosticsOut,
+      undefined,
+      memo,
+    );
+  }
+
+  return buildCombinedRouteMapWithSearch(
+    routerFilePath,
+    extraction.name,
+    new Set(),
+    diagnosticsOut,
+    undefined,
+    memo,
+  );
+}
+
+function mergeRouteMaps(
+  target: RouteMapWithSearch,
+  source: RouteMapWithSearch,
+): void {
+  for (const [name, pattern] of Object.entries(source.routes)) {
+    target.routes[name] = pattern;
+    const search = source.searchSchemas[name];
+    if (search) {
+      target.searchSchemas[name] = search;
+    } else {
+      delete target.searchSchemas[name];
+    }
+  }
+}
+
+// Filesystem path of the generated route-types file for a router source file.
+// Native separators — matches the self-gen-tracking Map key the watcher compares.
+export function genFileTsPath(sourceFile: string): string {
+  const base = pathBasename(sourceFile).replace(/\.(tsx?|jsx?)$/, "");
+  return join(dirname(sourceFile), `${base}.named-routes.gen.ts`);
+}
+
+// Search schemas for the gen file: prefer the runtime manifest's; when it omits
+// them (some module-runner flows) fall back to static parsing filtered to the
+// public route-name set. Returns the runtime value unchanged otherwise.
+export function resolveSearchSchemas(
+  publicRouteNames: string[],
+  runtimeSchemas: Record<string, Record<string, string>> | undefined,
+  sourceFile: string,
+): Record<string, Record<string, string>> | undefined {
+  if (runtimeSchemas && Object.keys(runtimeSchemas).length > 0) {
+    return runtimeSchemas;
+  }
+  const staticParsed = buildCombinedRouteMapForRouterFile(sourceFile);
+  if (Object.keys(staticParsed.searchSchemas).length === 0) {
+    return runtimeSchemas;
+  }
+  const filtered: Record<string, Record<string, string>> = {};
+  for (const name of publicRouteNames) {
+    const schema = staticParsed.searchSchemas[name];
+    if (schema) filtered[name] = schema;
+  }
+  return Object.keys(filtered).length > 0 ? filtered : runtimeSchemas;
+}
+
 /**
- * Resolve routes and search schemas from a router source file by following the
- * variable passed to `.routes(...)` or `urls: ...` in createRouter options.
+ * Resolve routes and search schemas from every direct mount in a createRouter
+ * chain. Registrations are merged in runtime order, with later mounts winning.
  */
 export function buildCombinedRouteMapForRouterFile(routerFilePath: string): {
   routes: Record<string, string>;
@@ -238,21 +494,38 @@ export function buildCombinedRouteMapForRouterFile(routerFilePath: string): {
     return { routes: {}, searchSchemas: {} };
   }
 
-  const urlsVarName = extractUrlsVariableFromRouter(routerSource);
-  if (!urlsVarName) {
+  const extractions = extractAllUrlsFromRouter(routerSource);
+  if (extractions.length === 0) {
     return { routes: {}, searchSchemas: {} };
   }
 
-  const imported = resolveImportedVariable(routerSource, urlsVarName);
-  if (imported) {
-    const targetFile = resolveImportPath(imported.specifier, routerFilePath);
-    if (!targetFile) {
-      return { routes: {}, searchSchemas: {} };
-    }
-    return buildCombinedRouteMapWithSearch(targetFile, imported.exportedName);
+  // Detect basename from createRouter({ basename: "..." })
+  const rawBasename = extractBasenameFromRouter(routerSource);
+  const basename = rawBasename
+    ? ("/" + rawBasename.replace(/^\/+|\/+$/g, "")).replace(/^\/$/, "")
+    : undefined;
+
+  const result: RouteMapWithSearch = { routes: {}, searchSchemas: {} };
+  const memo = createScanMemo();
+  for (const extraction of extractions) {
+    mergeRouteMaps(
+      result,
+      resolveRouterUrlsExtraction(
+        routerFilePath,
+        routerSource,
+        extraction,
+        undefined,
+        memo,
+      ),
+    );
   }
 
-  return buildCombinedRouteMapWithSearch(routerFilePath, urlsVarName);
+  // Apply basename prefix to all extracted route patterns
+  if (basename) {
+    return applyBasenameToRoutes(result, basename);
+  }
+
+  return result;
 }
 
 // ---------------------------------------------------------------------------
@@ -275,43 +548,20 @@ export function detectUnresolvableIncludes(
     return [];
   }
 
-  // Extract the urls variable from the router file
-  const urlsVarName = extractUrlsVariableFromRouter(source);
-  if (!urlsVarName) return [];
-
-  // Resolve where the urls variable comes from
-  const imported = resolveImportedVariable(source, urlsVarName);
-  let targetFile: string;
-  let exportedName: string | undefined;
-
-  if (imported) {
-    const resolved = resolveImportPath(imported.specifier, realPath);
-    if (!resolved) {
-      return [
-        {
-          pathPrefix: "/",
-          namePrefix: null,
-          reason: "file-not-found",
-          sourceFile: realPath,
-          detail: `import "${imported.specifier}" resolved to no file`,
-        },
-      ];
-    }
-    targetFile = resolved;
-    exportedName = imported.exportedName;
-  } else {
-    // Same-file urls() definition
-    targetFile = realPath;
-    exportedName = urlsVarName;
-  }
+  const extractions = extractAllUrlsFromRouter(source);
+  if (extractions.length === 0) return [];
 
   const diagnostics: UnresolvableInclude[] = [];
-  buildCombinedRouteMapWithSearch(
-    targetFile,
-    exportedName,
-    new Set(),
-    diagnostics,
-  );
+  const memo = createScanMemo();
+  for (const extraction of extractions) {
+    resolveRouterUrlsExtraction(
+      realPath,
+      source,
+      extraction,
+      diagnostics,
+      memo,
+    );
+  }
   return diagnostics;
 }
 
@@ -352,7 +602,38 @@ export function detectUnresolvableIncludesForUrlsFile(
  */
 export function findRouterFiles(root: string, filter?: ScanFilter): string[] {
   const result: string[] = [];
-  findRouterFilesRecursive(root, filter, result);
+  findCallSiteFilesRecursive(
+    root,
+    ROUTER_CALL_PATTERN,
+    ROUTER_CALL_PATTERN_G,
+    true,
+    filter,
+    result,
+  );
+  return result;
+}
+
+const HOST_ROUTER_CALL_PATTERN = /\bcreateHostRouter\s*[<(]/;
+const HOST_ROUTER_CALL_PATTERN_G = /\bcreateHostRouter\s*[<(]/g;
+
+/**
+ * Scan for files containing createHostRouter() and return their paths. Unlike
+ * findRouterFiles, this does NOT stop at the first router-root directory -- a host
+ * entry typically sits above the sub-app router roots, so the whole tree is scanned.
+ */
+export function findHostRouterFiles(
+  root: string,
+  filter?: ScanFilter,
+): string[] {
+  const result: string[] = [];
+  findCallSiteFilesRecursive(
+    root,
+    HOST_ROUTER_CALL_PATTERN,
+    HOST_ROUTER_CALL_PATTERN_G,
+    false,
+    filter,
+    result,
+  );
   return result;
 }
 
@@ -365,7 +646,10 @@ export function findRouterFiles(root: string, filter?: ScanFilter): string[] {
 export function writeCombinedRouteTypes(
   root: string,
   knownRouterFiles?: string[],
-  opts?: { preserveIfLarger?: boolean },
+  opts?: {
+    preserveIfLarger?: boolean;
+    onWrite?: (outPath: string, content: string) => void;
+  },
 ): void {
   // Delete old combined named-routes.gen.ts if it exists (stale from older versions)
   try {
@@ -373,7 +657,7 @@ export function writeCombinedRouteTypes(
     if (existsSync(oldCombinedPath)) {
       unlinkSync(oldCombinedPath);
       console.log(
-        `[rsc-router] Removed stale combined route types: ${oldCombinedPath}`,
+        `[rango] Removed stale combined route types: ${oldCombinedPath}`,
       );
     }
   } catch {}
@@ -387,54 +671,31 @@ export function writeCombinedRouteTypes(
   }
 
   for (const routerFilePath of routerFilePaths) {
-    let routerSource: string;
-    try {
-      routerSource = readFileSync(routerFilePath, "utf-8");
-    } catch {
-      continue;
-    }
-    // Extract the urls variable name from .routes(varName) or urls: varName
-    const urlsVarName = extractUrlsVariableFromRouter(routerSource);
-    if (!urlsVarName) continue;
-
-    // Resolve the variable to its source module
-    let result: {
-      routes: Record<string, string>;
-      searchSchemas: Record<string, Record<string, string>>;
-    };
-
-    const imported = resolveImportedVariable(routerSource, urlsVarName);
-    if (imported) {
-      // Variable is imported from another module
-      const targetFile = resolveImportPath(imported.specifier, routerFilePath);
-      if (!targetFile) continue;
-      result = buildCombinedRouteMapWithSearch(
-        targetFile,
-        imported.exportedName,
-      );
-    } else {
-      // Variable is defined in the same file
-      result = buildCombinedRouteMapWithSearch(routerFilePath, urlsVarName);
+    const result = buildCombinedRouteMapForRouterFile(routerFilePath);
+    if (
+      Object.keys(result.routes).length === 0 &&
+      Object.keys(result.searchSchemas).length === 0
+    ) {
+      // Check if the file even has a createRouter call — if not, skip entirely.
+      // If it does, fall through to write an empty placeholder below.
+      let routerSource: string;
+      try {
+        routerSource = readFileSync(routerFilePath, "utf-8");
+      } catch {
+        continue;
+      }
+      if (!extractUrlsFromRouter(routerSource)) continue;
     }
 
-    const routerBasename = pathBasename(routerFilePath).replace(
-      /\.(tsx?|jsx?)$/,
-      "",
-    );
-    const outPath = join(
-      dirname(routerFilePath),
-      `${routerBasename}.named-routes.gen.ts`,
-    );
+    const outPath = genFileTsPath(routerFilePath);
     const existing = existsSync(outPath)
       ? readFileSync(outPath, "utf-8")
       : null;
 
-    // When the static parser can't extract routes (e.g. callback-style urls()),
-    // write an empty placeholder so the build-time transform's injected import
-    // resolves. Runtime discovery will overwrite this with the real routes.
     if (Object.keys(result.routes).length === 0) {
       if (!existing) {
         const emptySource = generateRouteTypesSource({});
+        opts?.onWrite?.(outPath, emptySource);
         writeFileSync(outPath, emptySource);
       }
       continue;
@@ -446,11 +707,6 @@ export function writeCombinedRouteTypes(
       hasSearchSchemas ? result.searchSchemas : undefined,
     );
     if (existing !== source) {
-      // On initial dev startup, don't overwrite a file from runtime discovery
-      // (which has all dynamic routes) with a smaller set from the static
-      // parser. The static parser can't see routes generated by Array.from()
-      // or other dynamic code. During HMR (file watcher), always write so
-      // newly added routes appear immediately.
       if (opts?.preserveIfLarger && existing) {
         const existingCount = countPublicRouteEntries(existing);
         const newCount = Object.keys(result.routes).filter(
@@ -460,9 +716,10 @@ export function writeCombinedRouteTypes(
           continue;
         }
       }
+      opts?.onWrite?.(outPath, source);
       writeFileSync(outPath, source);
       console.log(
-        `[rsc-router] Generated route types (${Object.keys(result.routes).length} routes) -> ${outPath}`,
+        `[rango] Generated route types (${Object.keys(result.routes).length} routes) -> ${outPath}`,
       );
     }
   }