@rangojs/router 0.0.0-experimental.0b82333f

package/src/vite/discovery/prerender-collection.ts

@@ -0,0 +1,385 @@
+/**
+ * Prerender Collection
+ *
+ * Expands prerender routes into concrete URLs and renders them at build
+ * time. Also handles Static handler rendering for segment-level static
+ * generation.
+ */
+
+import { contextSet } from "../../context-var.js";
+import {
+  encodePathParam,
+  substituteRouteParams,
+  runWithConcurrency,
+  groupByConcurrency,
+  notifyOnError,
+  stageBuildAssetModule,
+} from "../utils/prerender-utils.js";
+import type { DiscoveryState } from "./state.js";
+
+/**
+ * Expand prerender routes into concrete URLs and render them via the
+ * RSC runner. Stages asset modules and stores key-to-file entries in
+ * state.prerenderManifestEntries.
+ */
+export async function expandPrerenderRoutes(
+  state: DiscoveryState,
+  rscEnv: any,
+  registry: Map<string, any>,
+  allManifests: Array<{ id: string; manifest: any }>,
+): Promise<void> {
+  if (!state.opts?.enableBuildPrerender || !state.isBuildMode) return;
+
+  type PrerenderEntry = {
+    urlPath: string;
+    routeName: string;
+    concurrency: number;
+    buildVars?: Record<string, any>;
+    isPassthroughRoute?: boolean;
+  };
+  const entries: PrerenderEntry[] = [];
+
+  // Build a merged route map for getParams context reverse()
+  const allRoutes: Record<string, string> = {};
+  for (const { manifest: m } of allManifests) {
+    if (m.routeManifest) Object.assign(allRoutes, m.routeManifest);
+  }
+  const getParamsReverse = (name: string, params?: Record<string, string>) => {
+    const pattern = allRoutes[name];
+    if (!pattern) throw new Error(`Unknown route: "${name}"`);
+    if (!params) return pattern;
+    return substituteRouteParams(pattern, params);
+  };
+
+  for (const { manifest } of allManifests) {
+    if (!manifest.prerenderRoutes) continue;
+    const defs = manifest._prerenderDefs || {};
+    for (const routeName of manifest.prerenderRoutes) {
+      const pattern = manifest.routeManifest[routeName];
+      if (!pattern) continue;
+      const def = defs[routeName];
+      const isPassthroughRoute = !!def?.options?.passthrough;
+      const hasDynamic = pattern.includes(":") || pattern.includes("*");
+      if (!hasDynamic) {
+        // Static route: use pattern directly (strip trailing slash for URL)
+        entries.push({
+          urlPath: pattern.replace(/\/$/, "") || "/",
+          routeName,
+          concurrency: 1,
+          isPassthroughRoute,
+        });
+      } else {
+        // Dynamic route: call getParams() to enumerate param combinations
+        if (def?.getParams) {
+          try {
+            const buildVars: Record<string, any> = {};
+            const getParamsCtx = {
+              build: true as const,
+              set: ((keyOrVar: any, value: any) => {
+                contextSet(buildVars, keyOrVar, value);
+              }) as any,
+              reverse: getParamsReverse,
+            };
+            const paramsList = await def.getParams(getParamsCtx);
+            const concurrency = def.options?.concurrency ?? 1;
+            const hasBuildVars =
+              Object.keys(buildVars).length > 0 ||
+              Object.getOwnPropertySymbols(buildVars).length > 0;
+            for (const params of paramsList) {
+              let url = substituteRouteParams(
+                pattern,
+                params as Record<string, string>,
+                encodePathParam,
+              );
+              // Anonymous wildcard fallback: use conventional keys if provided
+              if (url.includes("*")) {
+                const wildcardValue =
+                  (params as Record<string, string>)["*"] ??
+                  (params as Record<string, string>).splat;
+                if (wildcardValue !== undefined) {
+                  url = url.replace(/\*[^/]*$/, encodePathParam(wildcardValue));
+                }
+              }
+              entries.push({
+                urlPath: url.replace(/\/$/, "") || "/",
+                routeName,
+                concurrency,
+                ...(hasBuildVars ? { buildVars } : {}),
+                isPassthroughRoute,
+              });
+            }
+          } catch (err: any) {
+            // Skip in getParams() skips the entire route
+            if (err.name === "Skip") {
+              console.log(
+                `[rsc-router]   SKIP route "${routeName}" - ${err.message}`,
+              );
+              notifyOnError(
+                registry,
+                err,
+                "prerender",
+                routeName,
+                undefined,
+                true,
+              );
+              continue;
+            }
+            // Regular error: fail the build
+            console.error(
+              `[rsc-router] Failed to get params for prerender route "${routeName}": ${err.message}`,
+            );
+            notifyOnError(registry, err, "prerender", routeName);
+            throw err;
+          }
+        } else {
+          console.warn(
+            `[rsc-router] Dynamic prerender route "${routeName}" has no getParams(), skipping`,
+          );
+        }
+      }
+    }
+  }
+
+  if (entries.length === 0) return;
+
+  // Determine the max concurrency for the log header
+  const maxConcurrency = Math.max(...entries.map((e) => e.concurrency));
+  const concurrencyNote =
+    maxConcurrency > 1 ? ` (concurrency: ${maxConcurrency})` : "";
+  console.log(
+    `[rsc-router] Pre-rendering ${entries.length} URL(s)${concurrencyNote}...`,
+  );
+
+  const { hashParams } = await rscEnv.runner.import("@rangojs/router/build");
+
+  const manifestEntries: Record<string, string> = {};
+  let doneCount = 0;
+  let skipCount = 0;
+  const startTotal = performance.now();
+
+  // Group entries by concurrency for batched rendering.
+  // Within each group, all entries share the same concurrency limit.
+  const groups = groupByConcurrency(entries);
+
+  for (const group of groups) {
+    await runWithConcurrency(
+      group.entries,
+      group.concurrency,
+      async (entry) => {
+        const startUrl = performance.now();
+        for (const [, routerInstance] of registry) {
+          if (!routerInstance.matchForPrerender) continue;
+          try {
+            const result = await routerInstance.matchForPrerender(
+              entry.urlPath,
+              {},
+              entry.buildVars,
+              entry.isPassthroughRoute,
+            );
+            if (!result) continue;
+
+            // Handler returned ctx.passthrough() — skip manifest entry
+            if (result.passthrough) {
+              const elapsed = (performance.now() - startUrl).toFixed(0);
+              console.log(
+                `[rsc-router]   PASS ${entry.urlPath.padEnd(40)} (${elapsed}ms) - live fallback`,
+              );
+              doneCount++;
+              break;
+            }
+
+            const paramHash = hashParams(result.params || {});
+            const mainKey = `${result.routeName}/${paramHash}`;
+            const mainValue = JSON.stringify({
+              segments: result.segments,
+              handles: result.handles,
+            });
+            manifestEntries[mainKey] = stageBuildAssetModule(
+              state.projectRoot,
+              "__pr",
+              mainValue,
+            );
+            if (result.interceptSegments?.length) {
+              const interceptKey = `${result.routeName}/${paramHash}/i`;
+              const interceptValue = JSON.stringify({
+                segments: [...result.segments, ...result.interceptSegments],
+                handles: {
+                  ...result.handles,
+                  ...(result.interceptHandles || {}),
+                },
+              });
+              manifestEntries[interceptKey] = stageBuildAssetModule(
+                state.projectRoot,
+                "__pr",
+                interceptValue,
+              );
+            }
+            const elapsed = (performance.now() - startUrl).toFixed(0);
+            console.log(
+              `[rsc-router]   OK   ${entry.urlPath.padEnd(40)} (${elapsed}ms)`,
+            );
+            doneCount++;
+            break;
+          } catch (err: any) {
+            if (err.name === "Skip") {
+              const elapsed = (performance.now() - startUrl).toFixed(0);
+              console.log(
+                `[rsc-router]   SKIP ${entry.urlPath.padEnd(40)} (${elapsed}ms) - ${err.message}`,
+              );
+              skipCount++;
+              notifyOnError(
+                registry,
+                err,
+                "prerender",
+                entry.routeName,
+                entry.urlPath,
+                true,
+              );
+              break;
+            }
+            // Regular error: log, notify, and fail the build
+            const elapsed = (performance.now() - startUrl).toFixed(0);
+            console.error(
+              `[rsc-router]   FAIL ${entry.urlPath.padEnd(40)} (${elapsed}ms) - ${err.message}`,
+            );
+            notifyOnError(
+              registry,
+              err,
+              "prerender",
+              entry.routeName,
+              entry.urlPath,
+            );
+            throw err;
+          }
+        }
+      },
+    );
+  }
+
+  const totalElapsed = (performance.now() - startTotal).toFixed(0);
+  if (doneCount > 0) {
+    state.prerenderManifestEntries = manifestEntries;
+  }
+  const parts = [`${doneCount} done`];
+  if (skipCount > 0) parts.push(`${skipCount} skipped`);
+  console.log(
+    `[rsc-router] Pre-render complete: ${parts.join(", ")} (${totalElapsed}ms total)`,
+  );
+}
+
+/**
+ * Render Static handlers at build time. Each Static handler is called
+ * with a synthetic BuildContext and its output is RSC-serialized.
+ * Stages asset modules and stores handlerId-to-file entries in
+ * state.staticManifestEntries.
+ */
+export async function renderStaticHandlers(
+  state: DiscoveryState,
+  rscEnv: any,
+  registry: Map<string, any>,
+): Promise<void> {
+  if (
+    !state.opts?.enableBuildPrerender ||
+    !state.isBuildMode ||
+    !state.resolvedStaticModules?.size
+  )
+    return;
+
+  const manifestEntries: Record<string, string> = {};
+  let staticDone = 0;
+  let staticSkip = 0;
+  let totalStaticCount = 0;
+
+  // Count handlers for the log header
+  for (const [, exportNames] of state.resolvedStaticModules) {
+    totalStaticCount += exportNames.length;
+  }
+  const startStatic = performance.now();
+  console.log(
+    `[rsc-router] Rendering ${totalStaticCount} static handler(s)...`,
+  );
+
+  for (const [moduleId, exportNames] of state.resolvedStaticModules) {
+    let mod: any;
+    try {
+      mod = await rscEnv!.runner.import(moduleId);
+    } catch (err: any) {
+      console.error(
+        `[rsc-router] Failed to import static module ${moduleId}: ${err.message}`,
+      );
+      notifyOnError(registry, err, "static");
+      throw err;
+    }
+
+    for (const name of exportNames) {
+      const def = mod[name];
+      if (!def || def.__brand !== "staticHandler" || !def.$$id) continue;
+      // Passthrough handlers stay live in the bundle
+      if (def.options?.passthrough) continue;
+
+      const startHandler = performance.now();
+      let handled = false;
+      for (const [, routerInstance] of registry) {
+        if (!routerInstance.renderStaticSegment) continue;
+        try {
+          const result = await routerInstance.renderStaticSegment(
+            def.handler,
+            def.$$id,
+            (def as any).$$routePrefix,
+          );
+          if (result) {
+            const hasHandles = Object.keys(result.handles).length > 0;
+            const exportValue = hasHandles
+              ? JSON.stringify(result)
+              : JSON.stringify(result.encoded);
+            manifestEntries[def.$$id] = stageBuildAssetModule(
+              state.projectRoot,
+              "__st",
+              exportValue,
+            );
+            const elapsed = (performance.now() - startHandler).toFixed(0);
+            console.log(
+              `[rsc-router]   OK   ${name.padEnd(40)} (${elapsed}ms)`,
+            );
+            staticDone++;
+            handled = true;
+            break;
+          }
+        } catch (err: any) {
+          if (err.name === "Skip") {
+            const elapsed = (performance.now() - startHandler).toFixed(0);
+            console.log(
+              `[rsc-router]   SKIP ${name.padEnd(40)} (${elapsed}ms) - ${err.message}`,
+            );
+            staticSkip++;
+            notifyOnError(registry, err, "static", undefined, undefined, true);
+            handled = true;
+            break;
+          }
+          // Regular error: log, notify, and fail the build
+          const elapsed = (performance.now() - startHandler).toFixed(0);
+          console.error(
+            `[rsc-router]   FAIL ${name.padEnd(40)} (${elapsed}ms) - ${err.message}`,
+          );
+          notifyOnError(registry, err, "static");
+          throw err;
+        }
+      }
+      if (!handled) {
+        console.warn(
+          `[rsc-router] No router could render static handler "${name}"`,
+        );
+      }
+    }
+  }
+
+  const totalStaticElapsed = (performance.now() - startStatic).toFixed(0);
+  if (staticDone > 0) {
+    state.staticManifestEntries = manifestEntries;
+  }
+  const staticParts = [`${staticDone} done`];
+  if (staticSkip > 0) staticParts.push(`${staticSkip} skipped`);
+  console.log(
+    `[rsc-router] Static render complete: ${staticParts.join(", ")} (${totalStaticElapsed}ms total)`,
+  );
+}

package/src/vite/discovery/route-types-writer.ts

@@ -0,0 +1,258 @@
+/**
+ * Route Types Writer
+ *
+ * Generates and writes TypeScript route type files (named-routes.gen.ts)
+ * from discovered router manifests and static source parsing.
+ */
+
+import { dirname, basename, join, resolve } from "node:path";
+import { readFileSync, writeFileSync, existsSync, unlinkSync } from "node:fs";
+import {
+  generateRouteTypesSource,
+  writeCombinedRouteTypes,
+  findRouterFiles,
+  buildCombinedRouteMapForRouterFile,
+} from "../../build/generate-route-types.js";
+import type { DiscoveryState } from "./state.js";
+import { markSelfGenWrite } from "./self-gen-tracking.js";
+import { isAutoGeneratedRouteName } from "../../route-name.js";
+
+/**
+ * Filter out auto-generated route names from a manifest.
+ * Unnamed routes get "$path_"-prefixed names at runtime (see path-helper.ts).
+ * These should not appear in the typed gen file. User-defined names
+ * containing "$" (e.g. "$admin") are valid and preserved.
+ */
+function filterUserNamedRoutes(
+  manifest: Record<string, string>,
+): Record<string, string> {
+  const filtered: Record<string, string> = {};
+  for (const [name, pattern] of Object.entries(manifest)) {
+    if (!isAutoGeneratedRouteName(name)) {
+      filtered[name] = pattern;
+    }
+  }
+  return filtered;
+}
+
+/**
+ * Write combined route types for all router files.
+ * Only writes when content has changed to avoid triggering HMR loops.
+ */
+export function writeCombinedRouteTypesWithTracking(
+  state: DiscoveryState,
+  opts?: { preserveIfLarger?: boolean },
+): void {
+  const routerFiles =
+    state.cachedRouterFiles ??
+    findRouterFiles(state.projectRoot, state.scanFilter);
+  state.cachedRouterFiles = routerFiles;
+
+  // Snapshot pre-write content to detect which files actually change.
+  const preContent = new Map<string, string>();
+  for (const routerFilePath of routerFiles) {
+    const routerDir = dirname(routerFilePath);
+    const routerBasename = basename(routerFilePath).replace(
+      /\.(tsx?|jsx?)$/,
+      "",
+    );
+    const outPath = join(routerDir, `${routerBasename}.named-routes.gen.ts`);
+    try {
+      preContent.set(outPath, readFileSync(outPath, "utf-8"));
+    } catch {
+      // File doesn't exist yet — any write is a real change.
+    }
+  }
+
+  writeCombinedRouteTypes(state.projectRoot, routerFiles, opts);
+
+  // Mark only files that were actually written so the watcher can
+  // distinguish self-triggered change events from manual edits.
+  // Marking unchanged files creates stale entries that interfere with
+  // multi-server setups (e.g. shared webServer + isolated HMR server).
+  for (const routerFilePath of routerFiles) {
+    const routerDir = dirname(routerFilePath);
+    const routerBasename = basename(routerFilePath).replace(
+      /\.(tsx?|jsx?)$/,
+      "",
+    );
+    const outPath = join(routerDir, `${routerBasename}.named-routes.gen.ts`);
+    if (!existsSync(outPath)) continue;
+    try {
+      const content = readFileSync(outPath, "utf-8");
+      if (content !== preContent.get(outPath)) {
+        markSelfGenWrite(state, outPath, content);
+      }
+    } catch {
+      // Ignore transient fs errors while files are being rewritten.
+    }
+  }
+}
+
+/**
+ * Write per-router route types files from runtime discovery data.
+ */
+export function writeRouteTypesFiles(state: DiscoveryState): void {
+  if (state.perRouterManifests.length === 0) return;
+
+  // Delete old combined named-routes.gen.ts if it exists
+  try {
+    const entryDir = dirname(
+      resolve(state.projectRoot, state.resolvedEntryPath!),
+    );
+    const oldCombinedPath = join(entryDir, "named-routes.gen.ts");
+    if (existsSync(oldCombinedPath)) {
+      unlinkSync(oldCombinedPath);
+      console.log(
+        `[rsc-router] Removed stale combined route types: ${oldCombinedPath}`,
+      );
+    }
+  } catch {}
+
+  for (const {
+    id,
+    routeManifest,
+    routeSearchSchemas,
+    sourceFile,
+  } of state.perRouterManifests) {
+    if (!sourceFile) continue;
+
+    // Validate sourceFile points to a real project file, not node_modules or
+    // a Vite internal path. A bad sourceFile leads to route types written to
+    // the wrong location, causing non-deterministic type resolution.
+    if (sourceFile.includes("node_modules")) {
+      throw new Error(
+        `[rsc-router] Router "${id}" has sourceFile inside node_modules: ${sourceFile}\n` +
+          `This means createRouter() stack trace parsing matched a Vite internal frame.\n` +
+          `Set an explicit \`id\` on createRouter() or check the call site.`,
+      );
+    }
+
+    const routerDir = dirname(sourceFile);
+    const routerBasename = basename(sourceFile).replace(/\.(tsx?|jsx?)$/, "");
+    const outPath = join(routerDir, `${routerBasename}.named-routes.gen.ts`);
+
+    // Filter out auto-generated route names (e.g. "$path____debug_reverse-test")
+    // to match the static parser's output and prevent HMR oscillation.
+    const userRoutes = filterUserNamedRoutes(routeManifest);
+    let effectiveSearchSchemas = routeSearchSchemas;
+
+    // Runtime manifest may omit search schema metadata in some module-runner
+    // flows. Fall back to static source parsing from the router file.
+    if (
+      (!effectiveSearchSchemas ||
+        Object.keys(effectiveSearchSchemas).length === 0) &&
+      sourceFile
+    ) {
+      const staticParsed = buildCombinedRouteMapForRouterFile(sourceFile);
+      if (Object.keys(staticParsed.searchSchemas).length > 0) {
+        const filtered: Record<string, Record<string, string>> = {};
+        for (const name of Object.keys(userRoutes)) {
+          const schema = staticParsed.searchSchemas[name];
+          if (schema) filtered[name] = schema;
+        }
+        if (Object.keys(filtered).length > 0) {
+          effectiveSearchSchemas = filtered;
+        }
+      }
+    }
+
+    const source = generateRouteTypesSource(
+      userRoutes,
+      effectiveSearchSchemas && Object.keys(effectiveSearchSchemas).length > 0
+        ? effectiveSearchSchemas
+        : undefined,
+    );
+    const existing = existsSync(outPath)
+      ? readFileSync(outPath, "utf-8")
+      : null;
+    if (existing !== source) {
+      markSelfGenWrite(state, outPath, source);
+      writeFileSync(outPath, source);
+      console.log(`[rsc-router] Generated route types -> ${outPath}`);
+    }
+  }
+}
+
+/**
+ * Supplement gen files with route groups from runtime manifests that the
+ * static parser cannot resolve (factory calls like createDocsPatterns()).
+ * Only adds groups whose dot-prefix (e.g. "docs.") is entirely absent
+ * from the static output. Groups partially visible to the static parser
+ * are left alone so renames/removals propagate immediately without
+ * requiring a server restart.
+ *
+ * The runtime manifest (cachedManifest / perRouterManifestMap) is updated
+ * automatically: the virtual:rsc-router/routes-manifest module imports the
+ * gen file, so when we write new content here, Vite's HMR invalidates the
+ * virtual module and re-evaluates it on the next request.
+ */
+export function supplementGenFilesWithRuntimeRoutes(
+  state: DiscoveryState,
+): void {
+  // Cache static parsing results to avoid redundant I/O + parsing per router.
+  const parseCache = new Map<
+    string,
+    ReturnType<typeof buildCombinedRouteMapForRouterFile>
+  >();
+  const getParsed = (file: string) => {
+    let cached = parseCache.get(file);
+    if (!cached) {
+      cached = buildCombinedRouteMapForRouterFile(file);
+      parseCache.set(file, cached);
+    }
+    return cached;
+  };
+
+  for (const {
+    routeManifest,
+    routeSearchSchemas,
+    sourceFile,
+    factoryOnlyPrefixes,
+  } of state.perRouterManifests) {
+    if (!sourceFile) continue;
+    if (!factoryOnlyPrefixes || factoryOnlyPrefixes.size === 0) continue;
+
+    const staticParsed = getParsed(sourceFile);
+
+    // Merge: static routes (authoritative) + factory-only groups from runtime.
+    const mergedRoutes: Record<string, string> = { ...staticParsed.routes };
+    const mergedSearchSchemas: Record<string, Record<string, string>> = {
+      ...staticParsed.searchSchemas,
+    };
+
+    for (const [name, pattern] of Object.entries(routeManifest)) {
+      // Skip internal runtime-only names from unnamed routes/includes.
+      if (isAutoGeneratedRouteName(name)) continue;
+      const dotIdx = name.indexOf(".");
+      if (dotIdx <= 0) continue;
+      const prefix = name.substring(0, dotIdx + 1);
+      if (factoryOnlyPrefixes.has(prefix)) {
+        mergedRoutes[name] = pattern;
+        // Also merge search schemas from factory-generated routes
+        if (routeSearchSchemas?.[name]) {
+          mergedSearchSchemas[name] = routeSearchSchemas[name];
+        }
+      }
+    }
+
+    const routerDir = dirname(sourceFile);
+    const routerBasename = basename(sourceFile).replace(/\.(tsx?|jsx?)$/, "");
+    const outPath = join(routerDir, `${routerBasename}.named-routes.gen.ts`);
+    const source = generateRouteTypesSource(
+      mergedRoutes,
+      Object.keys(mergedSearchSchemas).length > 0
+        ? mergedSearchSchemas
+        : undefined,
+    );
+    const existing = existsSync(outPath)
+      ? readFileSync(outPath, "utf-8")
+      : null;
+    if (existing !== source) {
+      markSelfGenWrite(state, outPath, source);
+      writeFileSync(outPath, source);
+    }
+  }
+  // No manual manifest update needed: the virtual module imports the gen
+  // file, so Vite's HMR automatically re-evaluates it with fresh data.
+}

package/src/vite/discovery/self-gen-tracking.ts

@@ -0,0 +1,47 @@
+/**
+ * Self-Generated File Tracking
+ *
+ * Tracks gen files recently written by the discovery plugin so the
+ * file watcher can distinguish self-triggered change events from
+ * manual edits.
+ */
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import type { DiscoveryState } from "./state.js";
+
+export function markSelfGenWrite(
+  state: DiscoveryState,
+  filePath: string,
+  content: string,
+): void {
+  const hash = createHash("sha256").update(content).digest("hex");
+  state.selfWrittenGenFiles.set(filePath, { at: Date.now(), hash });
+}
+
+export function consumeSelfGenWrite(
+  state: DiscoveryState,
+  filePath: string,
+): boolean {
+  const info = state.selfWrittenGenFiles.get(filePath);
+  if (!info) return false;
+  if (Date.now() - info.at > state.SELF_WRITE_WINDOW_MS) {
+    state.selfWrittenGenFiles.delete(filePath);
+    return false;
+  }
+  try {
+    const current = readFileSync(filePath, "utf-8");
+    const currentHash = createHash("sha256").update(current).digest("hex");
+    if (currentHash === info.hash) {
+      state.selfWrittenGenFiles.delete(filePath);
+      return true;
+    }
+    // Hash mismatch: file was changed externally. Keep the entry so a
+    // subsequent watcher event from our own write can still be consumed
+    // (e.g. when multiple Vite servers watch the same directory).
+    return false;
+  } catch {
+    state.selfWrittenGenFiles.delete(filePath);
+    return false;
+  }
+}