@rangojs/router 0.0.0-experimental.10

package/dist/vite/index.js

@@ -0,0 +1,3039 @@
+// src/vite/index.ts
+import { createServer as createViteServer } from "vite";
+import * as Vite from "vite";
+import { resolve as resolve3, join as join2, dirname as dirname2, basename } from "node:path";
+import { createHash } from "node:crypto";
+import { createRequire } from "node:module";
+import { mkdirSync, writeFileSync as writeFileSync2, readFileSync as readFileSync2, existsSync as existsSync3, unlinkSync as unlinkSync2 } from "node:fs";
+
+// src/build/generate-route-types.ts
+import { readFileSync, writeFileSync, existsSync, readdirSync, unlinkSync } from "node:fs";
+import { join, dirname, resolve, relative, basename as pathBasename } from "node:path";
+import picomatch from "picomatch";
+function extractRoutesFromSource(code) {
+  const routes = [];
+  const regex = /\bpath(?:\.(?:json|text|html|xml|image|stream|any))?\s*\(/g;
+  let match;
+  while ((match = regex.exec(code)) !== null) {
+    const result = parsePathCall(code, match.index + match[0].length);
+    if (result) routes.push(result);
+  }
+  return routes;
+}
+function generatePerModuleTypesSource(routes) {
+  const valid = routes.filter(({ name }) => {
+    if (!name || /["'\\`\n\r]/.test(name)) {
+      console.warn(`[rsc-router] Skipping route with invalid name: ${JSON.stringify(name)}`);
+      return false;
+    }
+    return true;
+  });
+  const deduped = /* @__PURE__ */ new Map();
+  for (const { name, pattern } of valid) {
+    deduped.set(name, pattern);
+  }
+  const sorted = [...deduped.entries()].sort(([a], [b]) => a.localeCompare(b));
+  const body = sorted.map(([name, pattern]) => {
+    const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : `"${name}"`;
+    return `  ${key}: "${pattern}",`;
+  }).join("\n");
+  return `// Auto-generated by @rangojs/router - do not edit
+export const routes = {
+${body}
+} as const;
+export type routes = typeof routes;
+`;
+}
+function isWhitespace(ch) {
+  return ch === " " || ch === "	" || ch === "\n" || ch === "\r";
+}
+function readString(code, pos) {
+  const quote = code[pos];
+  if (quote !== '"' && quote !== "'") return null;
+  let value = "";
+  pos++;
+  while (pos < code.length) {
+    if (code[pos] === "\\") {
+      pos++;
+      if (pos < code.length) {
+        value += code[pos];
+        pos++;
+      }
+      continue;
+    }
+    if (code[pos] === quote) {
+      return { value, end: pos + 1 };
+    }
+    value += code[pos];
+    pos++;
+  }
+  return null;
+}
+function skipStringLiteral(code, pos) {
+  const quote = code[pos];
+  if (quote === "`") {
+    pos++;
+    while (pos < code.length) {
+      if (code[pos] === "\\") {
+        pos += 2;
+        continue;
+      }
+      if (code[pos] === "`") return pos + 1;
+      if (code[pos] === "$" && pos + 1 < code.length && code[pos + 1] === "{") {
+        pos += 2;
+        let braceDepth = 1;
+        while (pos < code.length && braceDepth > 0) {
+          if (code[pos] === "{") braceDepth++;
+          else if (code[pos] === "}") braceDepth--;
+          else if (code[pos] === "\\") pos++;
+          else if (code[pos] === '"' || code[pos] === "'" || code[pos] === "`") {
+            pos = skipStringLiteral(code, pos);
+            continue;
+          }
+          if (braceDepth > 0) pos++;
+        }
+        continue;
+      }
+      pos++;
+    }
+    return pos;
+  }
+  pos++;
+  while (pos < code.length) {
+    if (code[pos] === "\\") {
+      pos += 2;
+      continue;
+    }
+    if (code[pos] === quote) return pos + 1;
+    pos++;
+  }
+  return pos;
+}
+function matchesNameColon(code, pos) {
+  if (code.slice(pos, pos + 4) !== "name") return false;
+  if (pos > 0 && /\w/.test(code[pos - 1])) return false;
+  const afterName = pos + 4;
+  if (afterName < code.length && /\w/.test(code[afterName])) return false;
+  let checkPos = afterName;
+  while (checkPos < code.length && isWhitespace(code[checkPos])) checkPos++;
+  return code[checkPos] === ":";
+}
+function extractNameValue(code, pos) {
+  pos += 4;
+  while (pos < code.length && isWhitespace(code[pos])) pos++;
+  pos++;
+  while (pos < code.length && isWhitespace(code[pos])) pos++;
+  return readString(code, pos);
+}
+function parsePathCall(code, pos) {
+  while (pos < code.length && isWhitespace(code[pos])) pos++;
+  const patternStr = readString(code, pos);
+  if (!patternStr) return null;
+  const pattern = patternStr.value;
+  pos = patternStr.end;
+  let depth = 1;
+  let name = null;
+  while (pos < code.length && depth > 0) {
+    const ch = code[pos];
+    if (isWhitespace(ch)) {
+      pos++;
+      continue;
+    }
+    if (ch === "/" && pos + 1 < code.length && code[pos + 1] === "/") {
+      pos += 2;
+      while (pos < code.length && code[pos] !== "\n") pos++;
+      continue;
+    }
+    if (ch === "/" && pos + 1 < code.length && code[pos + 1] === "*") {
+      pos += 2;
+      while (pos < code.length - 1 && !(code[pos] === "*" && code[pos + 1] === "/"))
+        pos++;
+      pos += 2;
+      continue;
+    }
+    if (depth === 2 && ch === "n" && matchesNameColon(code, pos)) {
+      const nameResult = extractNameValue(code, pos);
+      if (nameResult) {
+        name = nameResult.value;
+        pos = nameResult.end;
+        continue;
+      }
+    }
+    if (ch === '"' || ch === "`" || ch === "'" && (pos === 0 || !/\w/.test(code[pos - 1]))) {
+      pos = skipStringLiteral(code, pos);
+      continue;
+    }
+    if (ch === "(" || ch === "{" || ch === "[") depth++;
+    else if (ch === ")" || ch === "}" || ch === "]") depth--;
+    pos++;
+  }
+  if (name === null) return null;
+  return { name, pattern };
+}
+function generateRouteTypesSource(routeManifest) {
+  const entries = Object.entries(routeManifest).sort(
+    ([a], [b]) => a.localeCompare(b)
+  );
+  const interfaceBody = entries.map(([name, pattern]) => `      "${name}": "${pattern}";`).join("\n");
+  return `// Auto-generated by @rangojs/router - do not edit
+export {};
+
+declare global {
+  namespace RSCRouter {
+    interface GeneratedRouteMap {
+${interfaceBody}
+    }
+  }
+}
+`;
+}
+var DEFAULT_EXCLUDE_PATTERNS = [
+  "**/__tests__/**",
+  "**/__mocks__/**",
+  "**/dist/**",
+  "**/coverage/**",
+  "**/*.test.{ts,tsx}",
+  "**/*.spec.{ts,tsx}"
+];
+function createScanFilter(root, opts) {
+  const { include, exclude } = opts;
+  const hasInclude = include && include.length > 0;
+  const hasCustomExclude = exclude !== void 0;
+  if (!hasInclude && !hasCustomExclude) return void 0;
+  const effectiveExclude = exclude ?? DEFAULT_EXCLUDE_PATTERNS;
+  const includeMatcher = hasInclude ? picomatch(include) : null;
+  const excludeMatcher = effectiveExclude.length > 0 ? picomatch(effectiveExclude) : null;
+  return (absolutePath) => {
+    const rel = relative(root, absolutePath);
+    if (excludeMatcher && excludeMatcher(rel)) return false;
+    if (includeMatcher) return includeMatcher(rel);
+    return true;
+  };
+}
+function findTsFiles(dir, filter) {
+  const results = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch (err) {
+    console.warn(`[rsc-router] Failed to scan directory ${dir}: ${err.message}`);
+    return results;
+  }
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+      results.push(...findTsFiles(fullPath, filter));
+    } else if ((entry.name.endsWith(".ts") || entry.name.endsWith(".tsx")) && !entry.name.includes(".gen.")) {
+      if (filter && !filter(fullPath)) continue;
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+function writePerModuleRouteTypes(root, filter) {
+  const files = findTsFiles(root, filter);
+  for (const filePath of files) {
+    writePerModuleRouteTypesForFile(filePath);
+  }
+}
+function writePerModuleRouteTypesForFile(filePath) {
+  try {
+    const source = readFileSync(filePath, "utf-8");
+    if (!source.includes("urls(")) return;
+    const routes = extractRoutesFromSource(source);
+    if (routes.length === 0) return;
+    const genPath = filePath.replace(/\.(tsx?)$/, ".gen.ts");
+    const genSource = generatePerModuleTypesSource(routes);
+    const existing = existsSync(genPath) ? readFileSync(genPath, "utf-8") : null;
+    if (existing !== genSource) {
+      writeFileSync(genPath, genSource);
+      console.log(`[rsc-router] Generated route types -> ${genPath}`);
+    }
+  } catch (err) {
+    console.warn(`[rsc-router] Failed to generate route types for ${filePath}: ${err.message}`);
+  }
+}
+function extractIncludesFromSource(code) {
+  const results = [];
+  const regex = /\binclude\s*\(/g;
+  let match;
+  while ((match = regex.exec(code)) !== null) {
+    const result = parseIncludeCall(code, match.index + match[0].length);
+    if (result) results.push(result);
+  }
+  return results;
+}
+function parseIncludeCall(code, pos) {
+  while (pos < code.length && isWhitespace(code[pos])) pos++;
+  const prefixStr = readString(code, pos);
+  if (!prefixStr) return null;
+  const pathPrefix = prefixStr.value;
+  pos = prefixStr.end;
+  while (pos < code.length && isWhitespace(code[pos])) pos++;
+  if (pos >= code.length || code[pos] !== ",") return null;
+  pos++;
+  while (pos < code.length && isWhitespace(code[pos])) pos++;
+  const varStart = pos;
+  while (pos < code.length && /[\w$]/.test(code[pos])) pos++;
+  if (pos === varStart) return null;
+  const variableName = code.slice(varStart, pos);
+  let namePrefix = null;
+  let depth = 1;
+  while (pos < code.length && depth > 0) {
+    const ch = code[pos];
+    if (isWhitespace(ch)) {
+      pos++;
+      continue;
+    }
+    if (ch === "/" && pos + 1 < code.length && code[pos + 1] === "/") {
+      pos += 2;
+      while (pos < code.length && code[pos] !== "\n") pos++;
+      continue;
+    }
+    if (ch === "/" && pos + 1 < code.length && code[pos + 1] === "*") {
+      pos += 2;
+      while (pos < code.length - 1 && !(code[pos] === "*" && code[pos + 1] === "/"))
+        pos++;
+      pos += 2;
+      continue;
+    }
+    if (depth === 2 && ch === "n" && matchesNameColon(code, pos)) {
+      const nameResult = extractNameValue(code, pos);
+      if (nameResult) {
+        namePrefix = nameResult.value;
+        pos = nameResult.end;
+        continue;
+      }
+    }
+    if (ch === '"' || ch === "`" || ch === "'" && (pos === 0 || !/\w/.test(code[pos - 1]))) {
+      pos = skipStringLiteral(code, pos);
+      continue;
+    }
+    if (ch === "(" || ch === "{" || ch === "[") depth++;
+    else if (ch === ")" || ch === "}" || ch === "]") depth--;
+    pos++;
+  }
+  return { pathPrefix, variableName, namePrefix };
+}
+function resolveImportedVariable(code, localName) {
+  const importRegex = /import\s*\{([^}]+)\}\s*from\s*["']([^"']+)["']/g;
+  let match;
+  while ((match = importRegex.exec(code)) !== null) {
+    const imports = match[1];
+    const specifier = match[2];
+    const parts = imports.split(",").map((s) => s.trim()).filter(Boolean);
+    for (const part of parts) {
+      const asMatch = part.match(/^(\w+)\s+as\s+(\w+)$/);
+      if (asMatch && asMatch[2] === localName)
+        return { specifier, exportedName: asMatch[1] };
+      if (part === localName) return { specifier, exportedName: localName };
+    }
+  }
+  return null;
+}
+function resolveImportPath(importSpec, fromFile) {
+  if (!importSpec.startsWith(".")) return null;
+  const dir = dirname(fromFile);
+  let base = importSpec;
+  if (base.endsWith(".js")) base = base.slice(0, -3);
+  else if (base.endsWith(".mjs")) base = base.slice(0, -4);
+  const candidates = [
+    resolve(dir, base + ".ts"),
+    resolve(dir, base + ".tsx"),
+    resolve(dir, base + "/index.ts"),
+    resolve(dir, base + "/index.tsx")
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function extractUrlsBlockForVariable(code, varName) {
+  const pattern = new RegExp(
+    `(?:export\\s+)?(?:const|let|var)\\s+${escapeRegExp(varName)}\\s*=\\s*urls\\s*\\(`
+  );
+  const match = pattern.exec(code);
+  if (!match) return null;
+  const openParen = match.index + match[0].length - 1;
+  let depth = 1;
+  let pos = openParen + 1;
+  while (pos < code.length && depth > 0) {
+    const ch = code[pos];
+    if (ch === '"' || ch === "`" || ch === "'" && (pos === 0 || !/\w/.test(code[pos - 1]))) {
+      pos = skipStringLiteral(code, pos);
+      continue;
+    }
+    if (ch === "/" && pos + 1 < code.length && code[pos + 1] === "/") {
+      pos += 2;
+      while (pos < code.length && code[pos] !== "\n") pos++;
+      continue;
+    }
+    if (ch === "/" && pos + 1 < code.length && code[pos + 1] === "*") {
+      pos += 2;
+      while (pos < code.length - 1 && !(code[pos] === "*" && code[pos + 1] === "/"))
+        pos++;
+      pos += 2;
+      continue;
+    }
+    if (ch === "(" || ch === "{" || ch === "[") depth++;
+    else if (ch === ")" || ch === "}" || ch === "]") depth--;
+    pos++;
+  }
+  return code.slice(openParen, pos);
+}
+function buildCombinedRouteMap(filePath, variableName, visited) {
+  visited = visited ?? /* @__PURE__ */ new Set();
+  const realPath = resolve(filePath);
+  const key = variableName ? `${realPath}:${variableName}` : realPath;
+  if (visited.has(key)) return {};
+  visited.add(key);
+  let source;
+  try {
+    source = readFileSync(realPath, "utf-8");
+  } catch {
+    return {};
+  }
+  let block;
+  if (variableName) {
+    const extracted = extractUrlsBlockForVariable(source, variableName);
+    if (!extracted) return {};
+    block = extracted;
+  } else {
+    block = source;
+  }
+  return buildRouteMapFromBlock(block, source, realPath, visited);
+}
+function buildRouteMapFromBlock(block, fullSource, filePath, visited) {
+  const routeMap = {};
+  const localRoutes = extractRoutesFromSource(block);
+  for (const { name, pattern } of localRoutes) {
+    routeMap[name] = pattern;
+  }
+  const includes = extractIncludesFromSource(block);
+  for (const { pathPrefix, variableName, namePrefix } of includes) {
+    let childRoutes;
+    const imported = resolveImportedVariable(fullSource, variableName);
+    if (imported) {
+      const targetFile = resolveImportPath(imported.specifier, filePath);
+      if (!targetFile) continue;
+      childRoutes = buildCombinedRouteMap(
+        targetFile,
+        imported.exportedName,
+        visited
+      );
+    } else {
+      childRoutes = buildCombinedRouteMap(filePath, variableName, visited);
+    }
+    for (const [name, pattern] of Object.entries(childRoutes)) {
+      const prefixedName = namePrefix ? `${namePrefix}.${name}` : name;
+      const prefixedPattern = pattern === "/" ? pathPrefix || "/" : pathPrefix + pattern;
+      routeMap[prefixedName] = prefixedPattern;
+    }
+  }
+  return routeMap;
+}
+function extractUrlsVariableFromRouter(code) {
+  const routesCallMatch = code.match(/\.routes\s*\(\s*([a-zA-Z_$][\w$]*)\s*\)/);
+  if (routesCallMatch) return routesCallMatch[1];
+  const urlsOptionMatch = code.match(/urls\s*:\s*([a-zA-Z_$][\w$]*)/);
+  if (urlsOptionMatch) return urlsOptionMatch[1];
+  return null;
+}
+function findRouterFiles(root, filter) {
+  const files = findTsFiles(root, filter);
+  const result = [];
+  for (const filePath of files) {
+    if (filePath.includes(".gen.")) continue;
+    try {
+      const source = readFileSync(filePath, "utf-8");
+      if (/\bcreateRouter\s*[<(]/.test(source)) {
+        result.push(filePath);
+      }
+    } catch {
+      continue;
+    }
+  }
+  return result;
+}
+function writeCombinedRouteTypes(root, knownRouterFiles) {
+  try {
+    const oldCombinedPath = join(root, "src", "named-routes.gen.ts");
+    if (existsSync(oldCombinedPath)) {
+      unlinkSync(oldCombinedPath);
+      console.log(`[rsc-router] Removed stale combined route types: ${oldCombinedPath}`);
+    }
+  } catch {
+  }
+  const routerFilePaths = knownRouterFiles ?? findRouterFiles(root);
+  if (routerFilePaths.length === 0) return;
+  for (const routerFilePath of routerFilePaths) {
+    let routerSource;
+    try {
+      routerSource = readFileSync(routerFilePath, "utf-8");
+    } catch {
+      continue;
+    }
+    const urlsVarName = extractUrlsVariableFromRouter(routerSource);
+    if (!urlsVarName) continue;
+    let routeMap;
+    const imported = resolveImportedVariable(routerSource, urlsVarName);
+    if (imported) {
+      const targetFile = resolveImportPath(imported.specifier, routerFilePath);
+      if (!targetFile) continue;
+      routeMap = buildCombinedRouteMap(targetFile, imported.exportedName);
+    } else {
+      routeMap = buildCombinedRouteMap(routerFilePath, urlsVarName);
+    }
+    if (Object.keys(routeMap).length === 0) continue;
+    const routerBasename = pathBasename(routerFilePath).replace(/\.(tsx?|jsx?)$/, "");
+    const outPath = join(dirname(routerFilePath), `${routerBasename}.named-routes.gen.ts`);
+    const source = generateRouteTypesSource(routeMap);
+    const existing = existsSync(outPath) ? readFileSync(outPath, "utf-8") : null;
+    if (existing !== source) {
+      writeFileSync(outPath, source);
+      console.log(`[rsc-router] Generated route types (${Object.keys(routeMap).length} routes) -> ${outPath}`);
+    }
+  }
+}
+
+// src/vite/expose-action-id.ts
+import MagicString from "magic-string";
+import path from "node:path";
+import fs from "node:fs";
+function getRscPluginApi(config) {
+  let plugin = config.plugins.find((p) => p.name === "rsc:minimal");
+  if (!plugin) {
+    plugin = config.plugins.find(
+      (p) => p.api?.manager?.serverReferenceMetaMap !== void 0
+    );
+    if (plugin) {
+      console.warn(
+        `[rsc-router:expose-action-id] RSC plugin found by API structure (name: "${plugin.name}"). Consider updating the name lookup if the plugin was renamed.`
+      );
+    }
+  }
+  return plugin?.api;
+}
+function normalizePath(p) {
+  return p.split(path.sep).join("/");
+}
+function isUseServerModule(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    const trimmed = content.replace(/^\s*\/\/[^\n]*\n/gm, "").replace(/^\s*\/\*[\s\S]*?\*\/\s*/gm, "").trimStart();
+    return trimmed.startsWith('"use server"') || trimmed.startsWith("'use server'");
+  } catch {
+    return false;
+  }
+}
+function transformServerReferences(code, sourceId, hashToFileMap) {
+  if (!code.includes("createServerReference(")) {
+    return null;
+  }
+  const pattern = /((?:\$\$\w+\.)?createServerReference)\(("[^"]+#[^"]+")([^)]*)\)/g;
+  const s = new MagicString(code);
+  let hasChanges = false;
+  let match;
+  while ((match = pattern.exec(code)) !== null) {
+    hasChanges = true;
+    const [fullMatch, fnCall, idArg, rest] = match;
+    const start = match.index;
+    const end = start + fullMatch.length;
+    let finalIdArg = idArg;
+    if (hashToFileMap) {
+      const idValue = idArg.slice(1, -1);
+      const hashMatch = idValue.match(/^([^#]+)#(.+)$/);
+      if (hashMatch) {
+        const [, hash, actionName] = hashMatch;
+        const filePath = hashToFileMap.get(hash);
+        if (filePath) {
+          finalIdArg = `"${filePath}#${actionName}"`;
+        }
+      }
+    }
+    const replacement = `(function(fn) { fn.$$id = ${finalIdArg}; return fn; })(${fnCall}(${idArg}${rest}))`;
+    s.overwrite(start, end, replacement);
+  }
+  if (!hasChanges) {
+    return null;
+  }
+  return {
+    code: s.toString(),
+    map: s.generateMap({ source: sourceId, includeContent: true })
+  };
+}
+function transformRegisterServerReference(code, sourceId, hashToFileMap) {
+  if (!hashToFileMap || !code.includes("registerServerReference(")) {
+    return null;
+  }
+  const pattern = /registerServerReference\(([^,]+),\s*"([^"]+)",\s*"([^"]+)"\)/g;
+  const s = new MagicString(code);
+  let hasChanges = false;
+  let match;
+  while ((match = pattern.exec(code)) !== null) {
+    const [fullMatch, fnArg, hash, exportName] = match;
+    const start = match.index;
+    const end = start + fullMatch.length;
+    const filePath = hashToFileMap.get(hash);
+    if (filePath) {
+      hasChanges = true;
+      const filePathId = `${filePath}#${exportName}`;
+      const replacement = `(function(fn) { fn.$id = "${filePathId}"; return fn; })(registerServerReference(${fnArg}, "${hash}", "${exportName}"))`;
+      s.overwrite(start, end, replacement);
+    }
+  }
+  if (!hasChanges) {
+    return null;
+  }
+  return {
+    code: s.toString(),
+    map: s.generateMap({ source: sourceId, includeContent: true })
+  };
+}
+function exposeActionId() {
+  let config;
+  let isBuild = false;
+  let hashToFileMap;
+  let rscPluginApi;
+  return {
+    name: "@rangojs/router:expose-action-id",
+    // Run after all other plugins (including RSC plugin's transforms)
+    enforce: "post",
+    configResolved(resolvedConfig) {
+      config = resolvedConfig;
+      isBuild = config.command === "build";
+      rscPluginApi = getRscPluginApi(config);
+    },
+    buildStart() {
+      if (!rscPluginApi) {
+        rscPluginApi = getRscPluginApi(config);
+      }
+      if (!rscPluginApi) {
+        throw new Error(
+          "[rsc-router] Could not find @vitejs/plugin-rsc. @rangojs/router requires the Vite RSC plugin.\nThe RSC plugin should be included automatically. If you disabled it with\nrango({ rsc: false }), add rsc() before rango() in your config."
+        );
+      }
+      if (!isBuild) return;
+      hashToFileMap = /* @__PURE__ */ new Map();
+      const { serverReferenceMetaMap } = rscPluginApi.manager;
+      for (const [absolutePath, meta] of Object.entries(
+        serverReferenceMetaMap
+      )) {
+        if (!isUseServerModule(absolutePath)) {
+          continue;
+        }
+        const relativePath = normalizePath(
+          path.relative(config.root, absolutePath)
+        );
+        hashToFileMap.set(meta.referenceKey, relativePath);
+      }
+    },
+    // Dev mode only: transform hook runs after RSC plugin creates server references
+    // In dev mode, IDs already contain file paths, not hashes
+    transform(code, id) {
+      if (isBuild) {
+        return;
+      }
+      if (!code.includes("createServerReference(")) {
+        return;
+      }
+      if (id.includes("/node_modules/")) {
+        return;
+      }
+      return transformServerReferences(code, id);
+    },
+    // Build mode: renderChunk runs after all transforms and bundling complete
+    renderChunk(code, chunk) {
+      const isRscEnv = this.environment?.name === "rsc";
+      const effectiveMap = isRscEnv ? hashToFileMap : void 0;
+      const result = transformServerReferences(
+        code,
+        chunk.fileName,
+        effectiveMap
+      );
+      if (isRscEnv && hashToFileMap) {
+        const codeToTransform = result ? result.code : code;
+        const registerResult = transformRegisterServerReference(
+          codeToTransform,
+          chunk.fileName,
+          hashToFileMap
+        );
+        if (registerResult) {
+          return { code: registerResult.code, map: registerResult.map };
+        }
+      }
+      if (result) {
+        return { code: result.code, map: result.map };
+      }
+      return null;
+    }
+  };
+}
+
+// src/vite/expose-loader-id.ts
+import MagicString2 from "magic-string";
+import path2 from "node:path";
+import crypto from "node:crypto";
+function normalizePath2(p) {
+  return p.split(path2.sep).join("/");
+}
+function hashLoaderId(filePath, exportName) {
+  const input = `${filePath}#${exportName}`;
+  const hash = crypto.createHash("sha256").update(input).digest("hex");
+  return `${hash.slice(0, 8)}#${exportName}`;
+}
+function hasCreateLoaderImport(code) {
+  const pattern = /import\s*\{[^}]*\bcreateLoader\b[^}]*\}\s*from\s*["']@rangojs\/router(?:\/server)?["']/;
+  return pattern.test(code);
+}
+function countCreateLoaderArgs(code, startPos, endPos) {
+  let depth = 0;
+  let argCount = 0;
+  let hasContent = false;
+  for (let i = startPos; i < endPos; i++) {
+    const char = code[i];
+    if (char === "(" || char === "[" || char === "{") {
+      depth++;
+      hasContent = true;
+    } else if (char === ")" || char === "]" || char === "}") {
+      depth--;
+    } else if (char === "," && depth === 0) {
+      argCount++;
+    } else if (!/\s/.test(char)) {
+      hasContent = true;
+    }
+  }
+  return hasContent ? argCount + 1 : 0;
+}
+function generateClientLoaderStubs(code, filePath, isBuild) {
+  const loaderPattern = /export\s+const\s+(\w+)\s*=\s*createLoader\s*\(/g;
+  const loaders = [];
+  let match;
+  while ((match = loaderPattern.exec(code)) !== null) {
+    loaders.push(match[1]);
+  }
+  if (loaders.length === 0) {
+    return null;
+  }
+  const allExports = /export\s+(const|let|var|function|class|default)\s+(\w+)/g;
+  let exportMatch;
+  const nonLoaderExports = [];
+  while ((exportMatch = allExports.exec(code)) !== null) {
+    const name = exportMatch[2];
+    if (!loaders.includes(name)) {
+      nonLoaderExports.push(name);
+    }
+  }
+  if (nonLoaderExports.length > 0) {
+    return null;
+  }
+  const stubs = loaders.map((name) => {
+    const loaderId = isBuild ? hashLoaderId(filePath, name) : `${filePath}#${name}`;
+    return `export const ${name} = { __brand: "loader", $$id: "${loaderId}" };`;
+  });
+  return {
+    code: stubs.join("\n") + "\n"
+  };
+}
+function transformLoaderExports(code, filePath, sourceId, isBuild = false) {
+  if (!code.includes("createLoader")) {
+    return null;
+  }
+  if (!hasCreateLoaderImport(code)) {
+    return null;
+  }
+  const pattern = /export\s+const\s+(\w+)\s*=\s*createLoader\s*\(/g;
+  const s = new MagicString2(code);
+  let hasChanges = false;
+  let match;
+  while ((match = pattern.exec(code)) !== null) {
+    const exportName = match[1];
+    const matchEnd = match.index + match[0].length;
+    let parenDepth = 1;
+    let i = matchEnd;
+    while (i < code.length && parenDepth > 0) {
+      if (code[i] === "(") parenDepth++;
+      if (code[i] === ")") parenDepth--;
+      i++;
+    }
+    const closeParenPos = i - 1;
+    const argCount = countCreateLoaderArgs(code, matchEnd, closeParenPos);
+    let statementEnd = i;
+    while (statementEnd < code.length && /\s/.test(code[statementEnd])) {
+      statementEnd++;
+    }
+    if (code[statementEnd] === ";") {
+      statementEnd++;
+    }
+    const loaderId = isBuild ? hashLoaderId(filePath, exportName) : `${filePath}#${exportName}`;
+    const paramInjection = argCount === 1 ? `, undefined, "${loaderId}"` : `, "${loaderId}"`;
+    s.appendLeft(closeParenPos, paramInjection);
+    const propInjection = `
+${exportName}.$$id = "${loaderId}";`;
+    s.appendRight(statementEnd, propInjection);
+    hasChanges = true;
+  }
+  if (!hasChanges) {
+    return null;
+  }
+  return {
+    code: s.toString(),
+    map: s.generateMap({ source: sourceId, includeContent: true })
+  };
+}
+var VIRTUAL_LOADER_MANIFEST = "virtual:rsc-router/loader-manifest";
+var RESOLVED_VIRTUAL_LOADER_MANIFEST = "\0" + VIRTUAL_LOADER_MANIFEST;
+function exposeLoaderId() {
+  let config;
+  let isBuild = false;
+  const loaderRegistry = /* @__PURE__ */ new Map();
+  const pendingLoaderScans = /* @__PURE__ */ new Map();
+  return {
+    name: "@rangojs/router:expose-loader-id",
+    enforce: "post",
+    configResolved(resolvedConfig) {
+      config = resolvedConfig;
+      isBuild = config.command === "build";
+    },
+    async buildStart() {
+      if (!isBuild) return;
+      const fs2 = await import("node:fs/promises");
+      async function scanDir(dir) {
+        const results = [];
+        try {
+          const entries = await fs2.readdir(dir, { withFileTypes: true });
+          for (const entry of entries) {
+            const fullPath = path2.join(dir, entry.name);
+            if (entry.isDirectory()) {
+              if (entry.name !== "node_modules") {
+                results.push(...await scanDir(fullPath));
+              }
+            } else if (/\.(ts|tsx|js|jsx)$/.test(entry.name)) {
+              results.push(fullPath);
+            }
+          }
+        } catch {
+        }
+        return results;
+      }
+      try {
+        const srcDir = path2.join(config.root, "src");
+        const files = await scanDir(srcDir);
+        for (const filePath of files) {
+          const content = await fs2.readFile(filePath, "utf-8");
+          if (!content.includes("createLoader")) continue;
+          if (!hasCreateLoaderImport(content)) continue;
+          const pattern = /export\s+const\s+(\w+)\s*=\s*createLoader\s*\(/g;
+          const relativePath = normalizePath2(
+            path2.relative(config.root, filePath)
+          );
+          let match;
+          while ((match = pattern.exec(content)) !== null) {
+            const exportName = match[1];
+            const hashedId = hashLoaderId(relativePath, exportName);
+            loaderRegistry.set(hashedId, {
+              filePath: relativePath,
+              exportName
+            });
+          }
+        }
+      } catch (error) {
+        console.warn("[exposeLoaderId] Pre-scan failed:", error);
+      }
+    },
+    resolveId(id) {
+      if (id === VIRTUAL_LOADER_MANIFEST) {
+        return RESOLVED_VIRTUAL_LOADER_MANIFEST;
+      }
+    },
+    load(id) {
+      if (id === RESOLVED_VIRTUAL_LOADER_MANIFEST) {
+        if (!isBuild) {
+          return `import { setLoaderImports } from "@rangojs/router/server";
+
+// Dev mode: empty map, loaders are resolved dynamically via path parsing
+setLoaderImports({});
+`;
+        }
+        const lazyImports = [];
+        for (const [hashedId, { filePath, exportName }] of loaderRegistry) {
+          lazyImports.push(
+            `  "${hashedId}": () => import("/${filePath}").then(m => m.${exportName})`
+          );
+        }
+        if (lazyImports.length === 0) {
+          return `import { setLoaderImports } from "@rangojs/router/server";
+
+// No fetchable loaders discovered during build
+setLoaderImports({});
+`;
+        }
+        const code = `import { setLoaderImports } from "@rangojs/router/server";
+
+// Lazy import map - loaders are loaded on-demand when first requested
+setLoaderImports({
+${lazyImports.join(",\n")}
+});
+`;
+        return code;
+      }
+    },
+    transform(code, id) {
+      if (id.includes("/node_modules/")) {
+        return;
+      }
+      if (!code.includes("createLoader")) {
+        return;
+      }
+      if (!hasCreateLoaderImport(code)) {
+        return;
+      }
+      const envName = this.environment?.name;
+      const isRscEnv = envName === "rsc";
+      const relativePath = normalizePath2(path2.relative(config.root, id));
+      if (isRscEnv) {
+        const pattern = /export\s+const\s+(\w+)\s*=\s*createLoader\s*\(/g;
+        let match;
+        while ((match = pattern.exec(code)) !== null) {
+          const exportName = match[1];
+          const hashedId = hashLoaderId(relativePath, exportName);
+          loaderRegistry.set(hashedId, { filePath: relativePath, exportName });
+        }
+      }
+      if (!isRscEnv) {
+        const stubResult = generateClientLoaderStubs(code, relativePath, isBuild);
+        if (stubResult) {
+          return stubResult;
+        }
+      }
+      return transformLoaderExports(code, relativePath, id, isBuild);
+    }
+  };
+}
+
+// src/vite/expose-handle-id.ts
+import MagicString3 from "magic-string";
+import path3 from "node:path";
+import crypto2 from "node:crypto";
+function normalizePath3(p) {
+  return p.split(path3.sep).join("/");
+}
+function hashHandleId(filePath, exportName) {
+  const input = `${filePath}#${exportName}`;
+  const hash = crypto2.createHash("sha256").update(input).digest("hex");
+  return `${hash.slice(0, 8)}#${exportName}`;
+}
+function hasCreateHandleImport(code) {
+  const pattern = /import\s*\{[^}]*\bcreateHandle\b[^}]*\}\s*from\s*["']@rangojs\/router(?:\/[^"']+)?["']/;
+  return pattern.test(code);
+}
+function analyzeCreateHandleArgs(code, startPos, endPos) {
+  const content = code.slice(startPos, endPos).trim();
+  if (!content) {
+    return { hasArgs: false, firstArgIsString: false, firstArgIsFunction: false };
+  }
+  const firstArgIsString = /^["']/.test(content);
+  const firstArgIsFunction = content.startsWith("(") || content.startsWith("function") || // Check for identifier that could be a collect function reference
+  /^[a-zA-Z_$][a-zA-Z0-9_$]*\s*(?:,|$)/.test(content);
+  return { hasArgs: true, firstArgIsString, firstArgIsFunction };
+}
+function transformHandleExports(code, filePath, sourceId, isBuild = false) {
+  if (!code.includes("createHandle")) {
+    return null;
+  }
+  if (!hasCreateHandleImport(code)) {
+    return null;
+  }
+  const pattern = /export\s+const\s+(\w+)\s*=\s*createHandle\s*(?:<[^>]*>)?\s*\(/g;
+  const s = new MagicString3(code);
+  let hasChanges = false;
+  let match;
+  while ((match = pattern.exec(code)) !== null) {
+    const exportName = match[1];
+    const matchEnd = match.index + match[0].length;
+    let parenDepth = 1;
+    let i = matchEnd;
+    while (i < code.length && parenDepth > 0) {
+      if (code[i] === "(") parenDepth++;
+      if (code[i] === ")") parenDepth--;
+      i++;
+    }
+    const closeParenPos = i - 1;
+    const args = analyzeCreateHandleArgs(code, matchEnd, closeParenPos);
+    let statementEnd = i;
+    while (statementEnd < code.length && /\s/.test(code[statementEnd])) {
+      statementEnd++;
+    }
+    if (code[statementEnd] === ";") {
+      statementEnd++;
+    }
+    const handleId = isBuild ? hashHandleId(filePath, exportName) : `${filePath}#${exportName}`;
+    let paramInjection;
+    if (!args.hasArgs) {
+      paramInjection = `undefined, "${handleId}"`;
+    } else {
+      paramInjection = `, "${handleId}"`;
+    }
+    s.appendLeft(closeParenPos, paramInjection);
+    const propInjection = `
+${exportName}.$$id = "${handleId}";`;
+    s.appendRight(statementEnd, propInjection);
+    hasChanges = true;
+  }
+  if (!hasChanges) {
+    return null;
+  }
+  return {
+    code: s.toString(),
+    map: s.generateMap({ source: sourceId, includeContent: true })
+  };
+}
+function exposeHandleId() {
+  let config;
+  let isBuild = false;
+  return {
+    name: "@rangojs/router:expose-handle-id",
+    enforce: "post",
+    configResolved(resolvedConfig) {
+      config = resolvedConfig;
+      isBuild = config.command === "build";
+    },
+    transform(code, id) {
+      if (id.includes("/node_modules/")) {
+        return;
+      }
+      if (!code.includes("createHandle")) {
+        return;
+      }
+      if (!hasCreateHandleImport(code)) {
+        return;
+      }
+      const relativePath = normalizePath3(path3.relative(config.root, id));
+      return transformHandleExports(code, relativePath, id, isBuild);
+    }
+  };
+}
+
+// src/vite/expose-location-state-id.ts
+import MagicString4 from "magic-string";
+import path4 from "node:path";
+import crypto3 from "node:crypto";
+function normalizePath4(p) {
+  return p.split(path4.sep).join("/");
+}
+function hashLocationStateKey(filePath, exportName) {
+  const input = `${filePath}#${exportName}`;
+  const hash = crypto3.createHash("sha256").update(input).digest("hex");
+  return `${hash.slice(0, 8)}#${exportName}`;
+}
+function hasCreateLocationStateImport(code) {
+  const pattern = /import\s*\{[^}]*\bcreateLocationState\b[^}]*\}\s*from\s*["']@rangojs\/router(?:\/[^"']+)?["']/;
+  return pattern.test(code);
+}
+function transformLocationStateExports(code, filePath, sourceId, isBuild = false) {
+  if (!code.includes("createLocationState")) {
+    return null;
+  }
+  if (!hasCreateLocationStateImport(code)) {
+    return null;
+  }
+  const pattern = /export\s+const\s+(\w+)\s*=\s*createLocationState\s*(?:<[^>]*>)?\s*\(/g;
+  const s = new MagicString4(code);
+  let hasChanges = false;
+  let match;
+  while ((match = pattern.exec(code)) !== null) {
+    const exportName = match[1];
+    const matchEnd = match.index + match[0].length;
+    let parenDepth = 1;
+    let i = matchEnd;
+    while (i < code.length && parenDepth > 0) {
+      if (code[i] === "(") parenDepth++;
+      if (code[i] === ")") parenDepth--;
+      i++;
+    }
+    const closeParenPos = i - 1;
+    const content = code.slice(matchEnd, closeParenPos).trim();
+    const hasArgs = content.length > 0;
+    let statementEnd = i;
+    while (statementEnd < code.length && /\s/.test(code[statementEnd])) {
+      statementEnd++;
+    }
+    if (code[statementEnd] === ";") {
+      statementEnd++;
+    }
+    const stateKey = isBuild ? hashLocationStateKey(filePath, exportName) : `${filePath}#${exportName}`;
+    if (!hasArgs) {
+      s.appendLeft(closeParenPos, `"${stateKey}"`);
+    } else {
+      continue;
+    }
+    const propInjection = `
+${exportName}.__rsc_ls_key = "__rsc_ls_${stateKey}";`;
+    s.appendRight(statementEnd, propInjection);
+    hasChanges = true;
+  }
+  if (!hasChanges) {
+    return null;
+  }
+  return {
+    code: s.toString(),
+    map: s.generateMap({ source: sourceId, includeContent: true })
+  };
+}
+function exposeLocationStateId() {
+  let config;
+  let isBuild = false;
+  return {
+    name: "@rangojs/router:expose-location-state-id",
+    enforce: "post",
+    configResolved(resolvedConfig) {
+      config = resolvedConfig;
+      isBuild = config.command === "build";
+    },
+    transform(code, id) {
+      if (id.includes("/node_modules/")) {
+        return;
+      }
+      if (!code.includes("createLocationState")) {
+        return;
+      }
+      if (!hasCreateLocationStateImport(code)) {
+        return;
+      }
+      const relativePath = normalizePath4(path4.relative(config.root, id));
+      return transformLocationStateExports(code, relativePath, id, isBuild);
+    }
+  };
+}
+
+// src/vite/expose-prerender-handler-id.ts
+import MagicString5 from "magic-string";
+import path5 from "node:path";
+import crypto4 from "node:crypto";
+function normalizePath5(p) {
+  return p.split(path5.sep).join("/");
+}
+function hashPrerenderHandlerId(filePath, exportName) {
+  const input = `${filePath}#${exportName}`;
+  const hash = crypto4.createHash("sha256").update(input).digest("hex");
+  return `${hash.slice(0, 8)}#${exportName}`;
+}
+function hasCreatePrerenderHandlerImport(code) {
+  const pattern = /import\s*\{[^}]*\bcreatePrerenderHandler\b[^}]*\}\s*from\s*["']@rangojs\/router(?:\/[^"']+)?["']/;
+  return pattern.test(code);
+}
+function skipStringOrComment(code, pos) {
+  const ch = code[pos];
+  if (ch === '"' || ch === "'") {
+    for (let j = pos + 1; j < code.length; j++) {
+      if (code[j] === "\\") {
+        j++;
+        continue;
+      }
+      if (code[j] === ch) return j + 1;
+    }
+    return code.length;
+  }
+  if (ch === "`") {
+    let j = pos + 1;
+    while (j < code.length) {
+      if (code[j] === "\\") {
+        j += 2;
+        continue;
+      }
+      if (code[j] === "`") return j + 1;
+      if (code[j] === "$" && j + 1 < code.length && code[j + 1] === "{") {
+        j += 2;
+        let braceDepth = 1;
+        while (j < code.length && braceDepth > 0) {
+          const inner = skipStringOrComment(code, j);
+          if (inner > j) {
+            j = inner;
+            continue;
+          }
+          if (code[j] === "{") braceDepth++;
+          else if (code[j] === "}") braceDepth--;
+          if (braceDepth > 0) j++;
+        }
+        if (braceDepth === 0) j++;
+        continue;
+      }
+      j++;
+    }
+    return j;
+  }
+  if (ch === "/" && pos + 1 < code.length) {
+    if (code[pos + 1] === "/") {
+      const eol = code.indexOf("\n", pos + 2);
+      return eol === -1 ? code.length : eol + 1;
+    }
+    if (code[pos + 1] === "*") {
+      const end = code.indexOf("*/", pos + 2);
+      return end === -1 ? code.length : end + 2;
+    }
+  }
+  return pos;
+}
+function findMatchingParen(code, startPos) {
+  let depth = 1;
+  let i = startPos;
+  while (i < code.length && depth > 0) {
+    const skipped = skipStringOrComment(code, i);
+    if (skipped > i) {
+      i = skipped;
+      continue;
+    }
+    if (code[i] === "(") depth++;
+    if (code[i] === ")") depth--;
+    i++;
+  }
+  return i;
+}
+function countArgs(code, startPos, endPos) {
+  let depth = 0;
+  let argCount = 0;
+  let hasContent = false;
+  let i = startPos;
+  while (i < endPos) {
+    const skipped = skipStringOrComment(code, i);
+    if (skipped > i) {
+      hasContent = true;
+      i = skipped;
+      continue;
+    }
+    const char = code[i];
+    if (char === "(" || char === "[" || char === "{") {
+      depth++;
+      hasContent = true;
+    } else if (char === ")" || char === "]" || char === "}") {
+      depth--;
+    } else if (char === "," && depth === 0) {
+      argCount++;
+    } else if (!/\s/.test(char)) {
+      hasContent = true;
+    }
+    i++;
+  }
+  return hasContent ? argCount + 1 : 0;
+}
+function transformPrerenderHandlerExports(code, filePath, sourceId, isBuild = false) {
+  if (!code.includes("createPrerenderHandler")) {
+    return null;
+  }
+  if (!hasCreatePrerenderHandlerImport(code)) {
+    return null;
+  }
+  const pattern = /export\s+const\s+(\w+)\s*=\s*createPrerenderHandler\s*(?:<[^>]*>)?\s*\(/g;
+  const s = new MagicString5(code);
+  let hasChanges = false;
+  let match;
+  while ((match = pattern.exec(code)) !== null) {
+    const exportName = match[1];
+    const matchEnd = match.index + match[0].length;
+    const afterClose = findMatchingParen(code, matchEnd);
+    const closeParenPos = afterClose - 1;
+    const argCount = countArgs(code, matchEnd, closeParenPos);
+    let statementEnd = afterClose;
+    while (statementEnd < code.length && /\s/.test(code[statementEnd])) {
+      statementEnd++;
+    }
+    if (code[statementEnd] === ";") {
+      statementEnd++;
+    }
+    const handlerId = isBuild ? hashPrerenderHandlerId(filePath, exportName) : `${filePath}#${exportName}`;
+    let paramInjection;
+    if (argCount === 0) {
+      paramInjection = `undefined, "${handlerId}"`;
+    } else if (argCount === 1) {
+      paramInjection = `, undefined, "${handlerId}"`;
+    } else {
+      paramInjection = `, "${handlerId}"`;
+    }
+    s.appendLeft(closeParenPos, paramInjection);
+    const propInjection = `
+${exportName}.$$id = "${handlerId}";`;
+    s.appendRight(statementEnd, propInjection);
+    hasChanges = true;
+  }
+  if (!hasChanges) {
+    return null;
+  }
+  return {
+    code: s.toString(),
+    map: s.generateMap({ source: sourceId, includeContent: true, hires: "boundary" })
+  };
+}
+function generateWholeFileHandlerStubs(code, filePath, isBuild) {
+  const handlerPattern = /export\s+const\s+(\w+)\s*=\s*createPrerenderHandler\s*(?:<[^>]*>)?\s*\(/g;
+  const handlers = [];
+  let match;
+  while ((match = handlerPattern.exec(code)) !== null) {
+    handlers.push(match[1]);
+  }
+  if (handlers.length === 0) return null;
+  if (/export\s*\{/.test(code) || /export\s*\*/.test(code)) {
+    return null;
+  }
+  const allExports = /export\s+(const|let|var|function|class|default)\s+(\w+)/g;
+  let exportMatch;
+  while ((exportMatch = allExports.exec(code)) !== null) {
+    const name = exportMatch[2];
+    if (!handlers.includes(name)) {
+      return null;
+    }
+  }
+  const stubs = handlers.map((name) => {
+    const handlerId = isBuild ? hashPrerenderHandlerId(filePath, name) : `${filePath}#${name}`;
+    return `export const ${name} = { __brand: "prerenderHandler", $$id: "${handlerId}" };`;
+  });
+  return { code: stubs.join("\n") + "\n", map: null };
+}
+function generatePrerenderHandlerStubs(code, filePath, sourceId, isBuild = false) {
+  const pattern = /export\s+const\s+(\w+)\s*=\s*(createPrerenderHandler\s*(?:<[^>]*>)?\s*\()/g;
+  const s = new MagicString5(code);
+  let hasChanges = false;
+  let match;
+  while ((match = pattern.exec(code)) !== null) {
+    const exportName = match[1];
+    const callStart = match.index + match[0].length - match[2].length;
+    const openParenPos = match.index + match[0].length;
+    const afterCloseParen = findMatchingParen(code, openParenPos);
+    const handlerId = isBuild ? hashPrerenderHandlerId(filePath, exportName) : `${filePath}#${exportName}`;
+    s.overwrite(
+      callStart,
+      afterCloseParen,
+      `{ __brand: "prerenderHandler", $$id: "${handlerId}" }`
+    );
+    hasChanges = true;
+  }
+  if (!hasChanges) return null;
+  return {
+    code: s.toString(),
+    map: s.generateMap({ source: sourceId, includeContent: true, hires: "boundary" })
+  };
+}
+function exposePrerenderHandlerId() {
+  let config;
+  let isBuild = false;
+  const prerenderHandlerModules = /* @__PURE__ */ new Map();
+  return {
+    name: "@rangojs/router:expose-prerender-handler-id",
+    enforce: "post",
+    api: {
+      prerenderHandlerModules
+    },
+    configResolved(resolvedConfig) {
+      config = resolvedConfig;
+      isBuild = config.command === "build";
+    },
+    transform(code, id) {
+      if (id.includes("/node_modules/")) {
+        return;
+      }
+      if (!code.includes("createPrerenderHandler")) {
+        return;
+      }
+      if (!hasCreatePrerenderHandlerImport(code)) {
+        return;
+      }
+      const relativePath = normalizePath5(path5.relative(config.root, id));
+      const isRscEnv = this.environment?.name === "rsc";
+      if (!isRscEnv) {
+        return generateWholeFileHandlerStubs(code, relativePath, isBuild) ?? generatePrerenderHandlerStubs(code, relativePath, id, isBuild);
+      }
+      if (isBuild) {
+        const handlerPattern = /export\s+const\s+(\w+)\s*=\s*createPrerenderHandler\s*(?:<[^>]*>)?\s*\(/g;
+        const exportNames = [];
+        let m;
+        while ((m = handlerPattern.exec(code)) !== null) {
+          exportNames.push(m[1]);
+        }
+        if (exportNames.length > 0) {
+          prerenderHandlerModules.set(id, exportNames);
+        }
+      }
+      return transformPrerenderHandlerExports(code, relativePath, id, isBuild);
+    }
+  };
+}
+
+// src/vite/virtual-entries.ts
+var VIRTUAL_ENTRY_BROWSER = `
+import {
+  createFromReadableStream,
+  createFromFetch,
+  setServerCallback,
+  encodeReply,
+  createTemporaryReferenceSet,
+} from "@rangojs/router/internal/deps/browser";
+import { createElement, StrictMode } from "react";
+import { hydrateRoot } from "react-dom/client";
+import { rscStream } from "@rangojs/router/internal/deps/html-stream-client";
+import { initBrowserApp, RSCRouter } from "@rangojs/router/browser";
+
+async function initializeApp() {
+  const deps = {
+    createFromFetch,
+    createFromReadableStream,
+    encodeReply,
+    setServerCallback,
+    createTemporaryReferenceSet,
+  };
+
+  await initBrowserApp({ rscStream, deps });
+
+  hydrateRoot(
+    document,
+    createElement(StrictMode, null, createElement(RSCRouter))
+  );
+}
+
+initializeApp().catch(console.error);
+`.trim();
+var VIRTUAL_ENTRY_SSR = `
+import { createFromReadableStream } from "@rangojs/router/internal/deps/ssr";
+import { renderToReadableStream } from "react-dom/server.edge";
+import { injectRSCPayload } from "@rangojs/router/internal/deps/html-stream-server";
+import { createSSRHandler } from "@rangojs/router/ssr";
+
+export const renderHTML = createSSRHandler({
+  createFromReadableStream,
+  renderToReadableStream,
+  injectRSCPayload,
+  loadBootstrapScriptContent: () =>
+    import.meta.viteRsc.loadBootstrapScriptContent("index"),
+});
+`.trim();
+function getVirtualEntryRSC(routerPath) {
+  return `
+import {
+  renderToReadableStream,
+  decodeReply,
+  createTemporaryReferenceSet,
+  loadServerAction,
+  decodeAction,
+  decodeFormState,
+} from "@rangojs/router/internal/deps/rsc";
+import { router } from "${routerPath}";
+import { createRSCHandler } from "@rangojs/router/internal/rsc-handler";
+import { VERSION } from "@rangojs/router:version";
+
+// Import loader manifest to ensure all fetchable loaders are registered at startup
+// This is critical for serverless/multi-process deployments where the loader module
+// might not be imported before a GET request arrives
+import "virtual:rsc-router/loader-manifest";
+
+// Import pre-generated route manifest so href() works immediately on cold start.
+// In build mode, this contains the full route map generated at build time.
+// In dev mode, this is a no-op (manifest is populated in-memory by the discovery plugin).
+import "virtual:rsc-router/routes-manifest";
+
+export default createRSCHandler({
+  router,
+  version: VERSION,
+  deps: {
+    renderToReadableStream,
+    decodeReply,
+    createTemporaryReferenceSet,
+    loadServerAction,
+    decodeAction,
+    decodeFormState,
+  },
+  loadSSRModule: () =>
+    import.meta.viteRsc.loadModule("ssr", "index"),
+});
+`.trim();
+}
+var VIRTUAL_IDS = {
+  browser: "virtual:rsc-router/entry.browser.js",
+  ssr: "virtual:rsc-router/entry.ssr.js",
+  rsc: "virtual:rsc-router/entry.rsc.js",
+  version: "@rangojs/router:version"
+};
+function getVirtualVersionContent(version) {
+  return `export const VERSION = ${JSON.stringify(version)};`;
+}
+
+// src/vite/package-resolution.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { resolve as resolve2 } from "node:path";
+
+// package.json
+var package_default = {
+  name: "@rangojs/router",
+  version: "0.0.0-experimental.10",
+  type: "module",
+  description: "Django-inspired RSC router with composable URL patterns",
+  author: "Ivo Todorov",
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/ivogt/vite-rsc.git",
+    directory: "packages/rangojs-router"
+  },
+  homepage: "https://github.com/ivogt/vite-rsc#readme",
+  bugs: {
+    url: "https://github.com/ivogt/vite-rsc/issues"
+  },
+  publishConfig: {
+    access: "public",
+    tag: "experimental"
+  },
+  keywords: [
+    "react",
+    "rsc",
+    "react-server-components",
+    "router",
+    "vite"
+  ],
+  exports: {
+    ".": {
+      "react-server": "./src/index.rsc.ts",
+      types: "./src/index.rsc.ts",
+      default: "./src/index.ts"
+    },
+    "./server": {
+      types: "./src/server.ts",
+      import: "./src/server.ts"
+    },
+    "./client": {
+      "react-server": "./src/client.rsc.tsx",
+      types: "./src/client.tsx",
+      default: "./src/client.tsx"
+    },
+    "./browser": {
+      types: "./src/browser/index.ts",
+      default: "./src/browser/index.ts"
+    },
+    "./ssr": {
+      types: "./src/ssr/index.tsx",
+      default: "./src/ssr/index.tsx"
+    },
+    "./rsc": {
+      "react-server": "./src/rsc/index.ts",
+      types: "./src/rsc/index.ts",
+      default: "./src/rsc/index.ts"
+    },
+    "./vite": {
+      types: "./src/vite/index.ts",
+      import: "./dist/vite/index.js"
+    },
+    "./types": {
+      types: "./src/vite/version.d.ts"
+    },
+    "./__internal": {
+      types: "./src/__internal.ts",
+      default: "./src/__internal.ts"
+    },
+    "./internal/deps/browser": {
+      types: "./src/deps/browser.ts",
+      default: "./src/deps/browser.ts"
+    },
+    "./internal/deps/ssr": {
+      types: "./src/deps/ssr.ts",
+      default: "./src/deps/ssr.ts"
+    },
+    "./internal/deps/rsc": {
+      "react-server": "./src/deps/rsc.ts",
+      types: "./src/deps/rsc.ts",
+      default: "./src/deps/rsc.ts"
+    },
+    "./internal/deps/html-stream-client": {
+      types: "./src/deps/html-stream-client.ts",
+      default: "./src/deps/html-stream-client.ts"
+    },
+    "./internal/deps/html-stream-server": {
+      types: "./src/deps/html-stream-server.ts",
+      default: "./src/deps/html-stream-server.ts"
+    },
+    "./internal/rsc-handler": {
+      "react-server": "./src/rsc/handler.ts",
+      types: "./src/rsc/handler.ts",
+      default: "./src/rsc/handler.ts"
+    },
+    "./cache": {
+      "react-server": "./src/cache/index.ts",
+      types: "./src/cache/index.ts",
+      default: "./src/cache/index.ts"
+    },
+    "./theme": {
+      types: "./src/theme/index.ts",
+      default: "./src/theme/index.ts"
+    },
+    "./build": {
+      types: "./src/build/index.ts",
+      import: "./src/build/index.ts"
+    },
+    "./host": {
+      "react-server": "./src/host/index.ts",
+      types: "./src/host/index.ts",
+      default: "./src/host/index.ts"
+    },
+    "./host/testing": {
+      types: "./src/host/testing.ts",
+      default: "./src/host/testing.ts"
+    }
+  },
+  files: [
+    "src",
+    "!src/**/__tests__",
+    "!src/**/__mocks__",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "dist",
+    "skills",
+    "CLAUDE.md",
+    "README.md"
+  ],
+  bin: {
+    rango: "./dist/bin/rango.js"
+  },
+  scripts: {
+    build: "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && pnpm dlx esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node'",
+    prepublishOnly: "pnpm build",
+    typecheck: "tsc --noEmit",
+    test: "playwright test",
+    "test:ui": "playwright test --ui",
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest"
+  },
+  peerDependencies: {
+    "@cloudflare/vite-plugin": "^1.21.0",
+    "@vitejs/plugin-rsc": "^0.5.14",
+    react: "^18.0.0 || ^19.0.0",
+    vite: "^7.3.0"
+  },
+  peerDependenciesMeta: {
+    "@cloudflare/vite-plugin": {
+      optional: true
+    },
+    vite: {
+      optional: true
+    }
+  },
+  dependencies: {
+    "@vitejs/plugin-rsc": "^0.5.14",
+    "magic-string": "^0.30.17",
+    picomatch: "^4.0.3",
+    "rsc-html-stream": "^0.0.7"
+  },
+  devDependencies: {
+    "@playwright/test": "^1.49.1",
+    "@types/node": "^24.10.1",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
+    esbuild: "^0.27.0",
+    jiti: "^2.6.1",
+    react: "catalog:",
+    "react-dom": "catalog:",
+    tinyexec: "^0.3.2",
+    typescript: "^5.3.0",
+    vitest: "^4.0.0"
+  }
+};
+
+// src/vite/package-resolution.ts
+var VIRTUAL_PACKAGE_NAME = "@rangojs/router";
+function getPublishedPackageName() {
+  return package_default.name;
+}
+function isInstalledFromNpm() {
+  const packageName = getPublishedPackageName();
+  return existsSync2(resolve2(process.cwd(), "node_modules", packageName));
+}
+function isWorkspaceDevelopment() {
+  return !isInstalledFromNpm();
+}
+var PACKAGE_SUBPATHS = [
+  "",
+  "/browser",
+  "/client",
+  "/server",
+  "/rsc",
+  "/ssr",
+  "/internal/deps/browser",
+  "/internal/deps/html-stream-client",
+  "/internal/deps/ssr",
+  "/internal/deps/rsc"
+];
+function getExcludeDeps() {
+  const packageName = getPublishedPackageName();
+  const excludes = [];
+  for (const subpath of PACKAGE_SUBPATHS) {
+    excludes.push(`${packageName}${subpath}`);
+    if (packageName !== VIRTUAL_PACKAGE_NAME) {
+      excludes.push(`${VIRTUAL_PACKAGE_NAME}${subpath}`);
+    }
+  }
+  return excludes;
+}
+var ALIAS_SUBPATHS = [
+  "/internal/deps/browser",
+  "/internal/deps/ssr",
+  "/internal/deps/rsc",
+  "/internal/deps/html-stream-client",
+  "/internal/deps/html-stream-server",
+  "/browser",
+  "/client",
+  "/server",
+  "/rsc",
+  "/ssr"
+];
+function getPackageAliases() {
+  if (isWorkspaceDevelopment()) {
+    return {};
+  }
+  const packageName = getPublishedPackageName();
+  const aliases = {};
+  for (const subpath of ALIAS_SUBPATHS) {
+    aliases[`${VIRTUAL_PACKAGE_NAME}${subpath}`] = `${packageName}${subpath}`;
+  }
+  return aliases;
+}
+
+// src/vite/index.ts
+var versionEsbuildPlugin = {
+  name: "@rangojs/router-version",
+  setup(build) {
+    build.onResolve({ filter: /^rsc-router:version$/ }, (args) => ({
+      path: args.path,
+      namespace: "@rangojs/router-virtual"
+    }));
+    build.onLoad({ filter: /.*/, namespace: "@rangojs/router-virtual" }, () => ({
+      contents: `export const VERSION = "dev";`,
+      loader: "js"
+    }));
+  }
+};
+var sharedEsbuildOptions = {
+  plugins: [versionEsbuildPlugin]
+};
+function createVirtualEntriesPlugin(entries, routerPath) {
+  const virtualModules = {};
+  if (entries.client === VIRTUAL_IDS.browser) {
+    virtualModules[VIRTUAL_IDS.browser] = VIRTUAL_ENTRY_BROWSER;
+  }
+  if (entries.ssr === VIRTUAL_IDS.ssr) {
+    virtualModules[VIRTUAL_IDS.ssr] = VIRTUAL_ENTRY_SSR;
+  }
+  if (entries.rsc === VIRTUAL_IDS.rsc && routerPath) {
+    const absoluteRouterPath = routerPath.startsWith(".") ? "/" + routerPath.slice(2) : routerPath;
+    virtualModules[VIRTUAL_IDS.rsc] = getVirtualEntryRSC(absoluteRouterPath);
+  }
+  return {
+    name: "@rangojs/router:virtual-entries",
+    enforce: "pre",
+    resolveId(id) {
+      if (id in virtualModules) {
+        return "\0" + id;
+      }
+      if (id.startsWith("\0") && id.slice(1) in virtualModules) {
+        return id;
+      }
+      return null;
+    },
+    load(id) {
+      if (id.startsWith("\0virtual:rsc-router/")) {
+        const virtualId = id.slice(1);
+        if (virtualId in virtualModules) {
+          return virtualModules[virtualId];
+        }
+      }
+      return null;
+    }
+  };
+}
+function getManualChunks(id) {
+  const normalized = Vite.normalizePath(id);
+  if (normalized.includes("node_modules/react/") || normalized.includes("node_modules/react-dom/") || normalized.includes("node_modules/react-server-dom-webpack/") || normalized.includes("node_modules/@vitejs/plugin-rsc/")) {
+    return "react";
+  }
+  const packageName = getPublishedPackageName();
+  if (normalized.includes(`node_modules/${packageName}/`) || normalized.includes("packages/rsc-router/") || normalized.includes("packages/rangojs-router/")) {
+    return "router";
+  }
+  return void 0;
+}
+function createVersionPlugin() {
+  const buildVersion = Date.now().toString(16);
+  let currentVersion = buildVersion;
+  let isDev = false;
+  let server = null;
+  return {
+    name: "@rangojs/router:version",
+    enforce: "pre",
+    configResolved(config) {
+      isDev = config.command === "serve";
+    },
+    configureServer(devServer) {
+      server = devServer;
+    },
+    resolveId(id) {
+      if (id === VIRTUAL_IDS.version) {
+        return "\0" + id;
+      }
+      return null;
+    },
+    load(id) {
+      if (id === "\0" + VIRTUAL_IDS.version) {
+        return getVirtualVersionContent(currentVersion);
+      }
+      return null;
+    },
+    // Track RSC module changes and update version
+    hotUpdate(ctx) {
+      if (!isDev) return;
+      const isRscModule = this.environment?.name === "rsc";
+      if (isRscModule && ctx.modules.length > 0) {
+        currentVersion = Date.now().toString(16);
+        console.log(
+          `[rsc-router] RSC module changed, version updated: ${currentVersion}`
+        );
+        if (server) {
+          const rscEnv = server.environments?.rsc;
+          if (rscEnv?.moduleGraph) {
+            const versionMod = rscEnv.moduleGraph.getModuleById(
+              "\0" + VIRTUAL_IDS.version
+            );
+            if (versionMod) {
+              rscEnv.moduleGraph.invalidateModule(versionMod);
+            }
+          }
+        }
+      }
+    }
+  };
+}
+function flattenLeafEntries(prefixTree, routeManifest, result) {
+  function visit(node) {
+    const children = node.children || {};
+    if (Object.keys(children).length === 0 && node.routes && node.routes.length > 0) {
+      const routes = {};
+      for (const name of node.routes) {
+        if (name in routeManifest) {
+          routes[name] = routeManifest[name];
+        }
+      }
+      result.push({ staticPrefix: node.staticPrefix, routes });
+    } else {
+      for (const child of Object.values(children)) {
+        visit(child);
+      }
+    }
+  }
+  for (const node of Object.values(prefixTree)) {
+    visit(node);
+  }
+}
+function buildRouteToStaticPrefix(prefixTree, result) {
+  function visit(node) {
+    const sp = node.staticPrefix || "";
+    for (const name of node.routes || []) {
+      result[name] = sp;
+    }
+    for (const child of Object.values(node.children || {})) {
+      visit(child);
+    }
+  }
+  for (const node of Object.values(prefixTree)) {
+    visit(node);
+  }
+}
+function createRouterDiscoveryPlugin(entryPath, opts) {
+  let projectRoot = "";
+  let isBuildMode = false;
+  let userResolveAlias = void 0;
+  let scanFilter;
+  let cachedRouterFiles;
+  let mergedRouteManifest = null;
+  let perRouterManifests = [];
+  let prerenderBuildUrls = null;
+  let prerenderRouteHashMap = {};
+  let rscPluginManager = null;
+  let cfIntegrationApi = null;
+  let discoveryDone = null;
+  let mergedPrecomputedEntries = null;
+  let mergedRouteTrie = null;
+  async function discoverRouters(rscEnv) {
+    await rscEnv.runner.import(entryPath);
+    const serverMod = await rscEnv.runner.import("@rangojs/router/server");
+    let registry = serverMod.RouterRegistry;
+    if (!registry || registry.size === 0) {
+      try {
+        const hostMod = await rscEnv.runner.import("@rangojs/router/host");
+        const hostRegistry = hostMod.HostRouterRegistry;
+        if (hostRegistry && hostRegistry.size > 0) {
+          console.log(
+            `[rsc-router] Found ${hostRegistry.size} host router(s), resolving lazy handlers...`
+          );
+          for (const [, entry] of hostRegistry) {
+            for (const route of entry.routes) {
+              if (typeof route.handler === "function") {
+                try {
+                  await route.handler();
+                } catch {
+                }
+              }
+            }
+            if (entry.fallback && typeof entry.fallback.handler === "function") {
+              try {
+                await entry.fallback.handler();
+              } catch {
+              }
+            }
+          }
+          const freshServerMod = await rscEnv.runner.import("@rangojs/router/server");
+          const freshRegistry = freshServerMod.RouterRegistry;
+          if (freshRegistry && freshRegistry.size > 0) {
+            Object.assign(serverMod, freshServerMod);
+            registry = freshRegistry;
+          }
+        }
+      } catch {
+      }
+      if (!registry || registry.size === 0) {
+        throw new Error(
+          `[rsc-router] No routers found in registry after importing ${entryPath}`
+        );
+      }
+    }
+    const buildMod = await rscEnv.runner.import("@rangojs/router/build");
+    const generateManifest = buildMod.generateManifest;
+    mergedRouteManifest = {};
+    mergedPrecomputedEntries = [];
+    perRouterManifests = [];
+    let mergedRouteAncestry = {};
+    let mergedRouteTrailingSlash = {};
+    let routerMountIndex = 0;
+    const allManifests = [];
+    for (const [id, router] of registry) {
+      if (!router.urlpatterns || !generateManifest) {
+        continue;
+      }
+      const manifest = generateManifest(router.urlpatterns, routerMountIndex);
+      routerMountIndex++;
+      allManifests.push({ id, manifest });
+      const routeCount = Object.keys(manifest.routeManifest).length;
+      const staticRoutes = Object.values(manifest.routeManifest).filter(
+        (p) => !p.includes(":") && !p.includes("*")
+      ).length;
+      const dynamicRoutes = routeCount - staticRoutes;
+      Object.assign(mergedRouteManifest, manifest.routeManifest);
+      perRouterManifests.push({ id, routeManifest: manifest.routeManifest, sourceFile: router.__sourceFile });
+      if (manifest._routeAncestry) {
+        Object.assign(mergedRouteAncestry, manifest._routeAncestry);
+      }
+      if (manifest.routeTrailingSlash) {
+        Object.assign(mergedRouteTrailingSlash, manifest.routeTrailingSlash);
+      }
+      flattenLeafEntries(manifest.prefixTree, manifest.routeManifest, mergedPrecomputedEntries);
+      const hash = hashRouterId(id);
+      const outDir = join2(projectRoot, "dist", "static", `__${hash}`);
+      mkdirSync(outDir, { recursive: true });
+      writeFileSync2(
+        join2(outDir, "routes.json"),
+        JSON.stringify(manifest.routeManifest, null, 2) + "\n"
+      );
+      writeFileSync2(
+        join2(outDir, "prefixes.json"),
+        JSON.stringify(manifest.prefixTree, null, 2) + "\n"
+      );
+      console.log(
+        `[rsc-router] Router "${id}" -> ${routeCount} routes (${staticRoutes} static, ${dynamicRoutes} dynamic) -> dist/static/__${hash}/`
+      );
+    }
+    if (mergedRouteManifest && Object.keys(mergedRouteManifest).length > 0) {
+      const buildRouteTrie = buildMod.buildRouteTrie;
+      if (buildRouteTrie && mergedRouteAncestry) {
+        const routeToStaticPrefix = {};
+        for (const { manifest } of allManifests) {
+          for (const name of Object.keys(manifest.routeManifest)) {
+            if (!(name in routeToStaticPrefix)) {
+              routeToStaticPrefix[name] = "";
+            }
+          }
+          buildRouteToStaticPrefix(manifest.prefixTree, routeToStaticPrefix);
+        }
+        const prerenderRouteNames = /* @__PURE__ */ new Set();
+        const passthroughRouteNames = /* @__PURE__ */ new Set();
+        const mergedResponseTypeRoutes = {};
+        for (const { manifest } of allManifests) {
+          if (manifest.prerenderRoutes) {
+            for (const name of manifest.prerenderRoutes) {
+              prerenderRouteNames.add(name);
+            }
+          }
+          if (manifest.passthroughRoutes) {
+            for (const name of manifest.passthroughRoutes) {
+              passthroughRouteNames.add(name);
+            }
+          }
+          if (manifest.responseTypeRoutes) {
+            Object.assign(mergedResponseTypeRoutes, manifest.responseTypeRoutes);
+          }
+        }
+        mergedRouteTrie = buildRouteTrie(
+          mergedRouteManifest,
+          mergedRouteAncestry,
+          routeToStaticPrefix,
+          Object.keys(mergedRouteTrailingSlash).length > 0 ? mergedRouteTrailingSlash : void 0,
+          prerenderRouteNames.size > 0 ? prerenderRouteNames : void 0,
+          passthroughRouteNames.size > 0 ? passthroughRouteNames : void 0,
+          Object.keys(mergedResponseTypeRoutes).length > 0 ? mergedResponseTypeRoutes : void 0
+        );
+      }
+    }
+    if (opts?.enableBuildPrerender) {
+      const urls = [];
+      const routeHashMap = {};
+      for (const { id, manifest } of allManifests) {
+        if (!manifest.prerenderRoutes) continue;
+        const rHash = hashRouterId(id);
+        const defs = manifest._prerenderDefs || {};
+        for (const routeName of manifest.prerenderRoutes) {
+          routeHashMap[routeName] = rHash;
+          const pattern = manifest.routeManifest[routeName];
+          if (!pattern) continue;
+          const hasDynamic = pattern.includes(":") || pattern.includes("*");
+          if (!hasDynamic) {
+            urls.push(pattern.replace(/\/$/, "") || "/");
+          } else {
+            const def = defs[routeName];
+            if (def?.getParams) {
+              try {
+                const paramsList = await def.getParams();
+                for (const params of paramsList) {
+                  let url = pattern;
+                  for (const [key, value] of Object.entries(params)) {
+                    url = url.replace(`:${key}`, encodeURIComponent(String(value)));
+                  }
+                  urls.push(url.replace(/\/$/, "") || "/");
+                }
+              } catch (err) {
+                console.warn(
+                  `[rsc-router] Failed to get params for prerender route "${routeName}": ${err.message}`
+                );
+              }
+            } else {
+              console.warn(
+                `[rsc-router] Dynamic prerender route "${routeName}" has no getParams(), skipping`
+              );
+            }
+          }
+        }
+      }
+      if (urls.length > 0) {
+        prerenderBuildUrls = urls;
+        prerenderRouteHashMap = routeHashMap;
+        console.log(
+          `[rsc-router] Pre-render URLs: ${urls.join(", ")}`
+        );
+      }
+    }
+    return serverMod;
+  }
+  function writeRouteTypesFiles() {
+    if (perRouterManifests.length === 0) return;
+    try {
+      const entryDir = dirname2(resolve3(projectRoot, entryPath));
+      const oldCombinedPath = join2(entryDir, "named-routes.gen.ts");
+      if (existsSync3(oldCombinedPath)) {
+        unlinkSync2(oldCombinedPath);
+        console.log(`[rsc-router] Removed stale combined route types: ${oldCombinedPath}`);
+      }
+    } catch {
+    }
+    for (const { routeManifest, sourceFile } of perRouterManifests) {
+      if (!sourceFile) continue;
+      try {
+        const routerDir = dirname2(sourceFile);
+        const routerBasename = basename(sourceFile).replace(/\.(tsx?|jsx?)$/, "");
+        const outPath = join2(routerDir, `${routerBasename}.named-routes.gen.ts`);
+        const source = generateRouteTypesSource(routeManifest);
+        const existing = existsSync3(outPath) ? readFileSync2(outPath, "utf-8") : null;
+        if (existing !== source) {
+          writeFileSync2(outPath, source);
+          console.log(`[rsc-router] Generated route types -> ${outPath}`);
+        }
+      } catch (err) {
+        console.warn(`[rsc-router] Failed to write named-routes.gen.ts: ${err.message}`);
+      }
+    }
+  }
+  return {
+    name: "@rangojs/router:discovery",
+    configResolved(config) {
+      projectRoot = config.root;
+      isBuildMode = config.command === "build";
+      userResolveAlias = config.resolve.alias;
+      if (opts?.include || opts?.exclude) {
+        scanFilter = createScanFilter(projectRoot, {
+          include: opts.include,
+          exclude: opts.exclude
+        });
+      }
+      if (opts?.staticRouteTypesGeneration !== false) {
+        writePerModuleRouteTypes(projectRoot, scanFilter);
+        cachedRouterFiles = findRouterFiles(projectRoot, scanFilter);
+        writeCombinedRouteTypes(projectRoot, cachedRouterFiles);
+      }
+      if (opts?.enableBuildPrerender) {
+        const rscPlugin = config.plugins.find((p) => p.name === "rsc:minimal");
+        if (rscPlugin?.api?.manager) {
+          rscPluginManager = rscPlugin.api.manager;
+        }
+        const cfPlugin = config.plugins.find(
+          (p) => p.name === "@rangojs/router:cloudflare-integration"
+        );
+        if (cfPlugin?.api) {
+          cfIntegrationApi = cfPlugin.api;
+        }
+      }
+    },
+    // Dev mode: discover routers and populate manifest in memory.
+    // Skipped in build mode (buildStart handles it).
+    configureServer(server) {
+      if (isBuildMode) return;
+      if (globalThis.__rscRouterDiscoveryActive) return;
+      let resolveDiscovery;
+      const discoveryPromise = new Promise((resolve4) => {
+        resolveDiscovery = resolve4;
+      });
+      const discover = async () => {
+        const rscEnv = server.environments?.rsc;
+        if (!rscEnv?.runner) {
+          resolveDiscovery();
+          return;
+        }
+        try {
+          const serverMod = await rscEnv.runner.import("@rangojs/router/server");
+          if (serverMod?.setManifestReadyPromise) {
+            serverMod.setManifestReadyPromise(discoveryPromise);
+          }
+          await discoverRouters(rscEnv);
+          if (opts?.staticRouteTypesGeneration === false) {
+            writeRouteTypesFiles();
+          }
+          if (mergedRouteManifest && serverMod?.setCachedManifest) {
+            serverMod.setCachedManifest(mergedRouteManifest);
+          }
+          if (mergedPrecomputedEntries && mergedPrecomputedEntries.length > 0 && serverMod?.setPrecomputedEntries) {
+            serverMod.setPrecomputedEntries(mergedPrecomputedEntries);
+          }
+          if (mergedRouteTrie && serverMod?.setRouteTrie) {
+            serverMod.setRouteTrie(mergedRouteTrie);
+          }
+        } catch (err) {
+          console.warn(
+            `[rsc-router] Router discovery failed: ${err.message}
+${err.stack}`
+          );
+        } finally {
+          resolveDiscovery();
+        }
+      };
+      discoveryDone = new Promise((resolve4) => {
+        setTimeout(() => discover().then(resolve4, resolve4), 0);
+      });
+      if (opts?.staticRouteTypesGeneration !== false) {
+        server.watcher.on("change", (filePath) => {
+          if (filePath.endsWith(".gen.ts")) return;
+          if (!filePath.endsWith(".ts") && !filePath.endsWith(".tsx")) return;
+          if (scanFilter && !scanFilter(filePath)) return;
+          try {
+            const source = readFileSync2(filePath, "utf-8");
+            const trimmed = source.trimStart();
+            if (trimmed.startsWith('"use client"') || trimmed.startsWith("'use client'")) return;
+            const hasUrls = source.includes("urls(");
+            const hasCreateRouter = /\bcreateRouter\s*[<(]/.test(source);
+            if (!hasUrls && !hasCreateRouter) return;
+            if (hasUrls) {
+              writePerModuleRouteTypesForFile(filePath);
+            }
+            if (hasCreateRouter) {
+              cachedRouterFiles = void 0;
+            }
+            writeCombinedRouteTypes(projectRoot, cachedRouterFiles);
+          } catch {
+          }
+        });
+      }
+    },
+    // Build mode: create a temporary Vite dev server to access the RSC
+    // environment's module runner, then discover routers and generate manifests.
+    // The manifest data is stored for the virtual module's load hook.
+    async buildStart() {
+      if (!isBuildMode) return;
+      if (mergedRouteManifest !== null) return;
+      let tempServer = null;
+      try {
+        globalThis.__rscRouterDiscoveryActive = true;
+        const { default: rsc } = await import("@vitejs/plugin-rsc");
+        tempServer = await createViteServer({
+          root: projectRoot,
+          configFile: false,
+          server: { middlewareMode: true },
+          appType: "custom",
+          logLevel: "silent",
+          // Use the resolved aliases from the real config (includes user's path aliases
+          // like @/ -> src/ AND package aliases from rsc-router)
+          resolve: { alias: userResolveAlias },
+          // Enable automatic JSX runtime so .tsx files don't need `import React`.
+          // Without this, esbuild defaults to classic mode (React.createElement)
+          // which fails when lazy host-router handlers load sub-app modules with JSX.
+          esbuild: { jsx: "automatic", jsxImportSource: "react" },
+          plugins: [
+            rsc({ entries: { client: "virtual:entry-client", ssr: "virtual:entry-ssr", rsc: entryPath } }),
+            createVersionPlugin(),
+            // Stub virtual modules that the RSC entry may import
+            // (e.g., virtual:rsc-router/routes-manifest, virtual:rsc-router/loader-manifest)
+            createVirtualStubPlugin()
+          ]
+        });
+        const rscEnv = tempServer.environments?.rsc;
+        if (!rscEnv?.runner) {
+          console.warn(
+            "[rsc-router] RSC environment runner not available during build, skipping manifest generation"
+          );
+          return;
+        }
+        await discoverRouters(rscEnv);
+        writeRouteTypesFiles();
+      } catch (err) {
+        delete globalThis.__rscRouterDiscoveryActive;
+        if (tempServer) {
+          await tempServer.close();
+        }
+        throw new Error(
+          `[rsc-router] Build-time router discovery failed: ${err.message}`
+        );
+      } finally {
+        delete globalThis.__rscRouterDiscoveryActive;
+        if (tempServer) {
+          await tempServer.close();
+        }
+      }
+    },
+    // Virtual module: provides the pre-generated route manifest as a JS module
+    // that calls setCachedManifest() at import time.
+    resolveId(id) {
+      if (id === VIRTUAL_ROUTES_MANIFEST_ID) {
+        return "\0" + VIRTUAL_ROUTES_MANIFEST_ID;
+      }
+      return null;
+    },
+    async load(id) {
+      if (id === "\0" + VIRTUAL_ROUTES_MANIFEST_ID) {
+        if (discoveryDone) {
+          await discoveryDone;
+          console.log(`[rsc-router] Virtual module loaded after discovery (${mergedRouteManifest ? Object.keys(mergedRouteManifest).length + " routes" : "no data"})`);
+        }
+        const hasManifest = mergedRouteManifest && Object.keys(mergedRouteManifest).length > 0;
+        if (hasManifest) {
+          const lines = [
+            `import { setCachedManifest, setPrecomputedEntries, setRouteTrie } from "@rangojs/router/server";`,
+            `setCachedManifest(${JSON.stringify(mergedRouteManifest)});`
+          ];
+          if (mergedPrecomputedEntries && mergedPrecomputedEntries.length > 0) {
+            lines.push(`setPrecomputedEntries(${JSON.stringify(mergedPrecomputedEntries)});`);
+          }
+          if (mergedRouteTrie) {
+            lines.push(`setRouteTrie(${JSON.stringify(mergedRouteTrie)});`);
+          }
+          return lines.join("\n");
+        }
+        return `// Route manifest will be populated at runtime`;
+      }
+      return null;
+    },
+    // Build-time pre-rendering: spawn a child Node.js process to import the
+    // built worker and render each prerender URL to static HTML.
+    // A separate process is needed because Vite registers module resolution
+    // hooks that interfere with importing the bundled worker.
+    //
+    // RETRY SEMANTICS:
+    // Vite's environment-aware builder calls closeBundle once per environment
+    // build (rsc -> client -> ssr). Pre-rendering requires BOTH the client
+    // assets manifest AND the SSR bundle, so early calls bail out silently.
+    // The `order: "post"` ensures this runs after other plugins' closeBundle
+    // hooks. `sequential: true` prevents concurrent closeBundle execution
+    // across environments, avoiding race conditions on shared state like
+    // prerenderBuildUrls. The null-guard on prerenderBuildUrls ensures we
+    // run at most once even if closeBundle fires again after the SSR build.
+    closeBundle: {
+      order: "post",
+      sequential: true,
+      async handler() {
+        if (!isBuildMode || !prerenderBuildUrls?.length) return;
+        if (!rscPluginManager?.buildAssetsManifest) return;
+        const ssrPath = resolve3(projectRoot, "dist/rsc/ssr/index.js");
+        if (!existsSync3(ssrPath)) return;
+        if (prerenderBuildUrls === null) return;
+        const urlsToRender = prerenderBuildUrls;
+        prerenderBuildUrls = null;
+        try {
+          rscPluginManager.writeAssetsManifest(["ssr", "rsc"]);
+        } catch (err) {
+          console.warn(
+            `[rsc-router] Failed to write assets manifest early: ${err.message}`
+          );
+        }
+        console.log(
+          `[rsc-router] Pre-rendering ${urlsToRender.length} route(s)...`
+        );
+        const scriptPath = resolve3(projectRoot, "dist/.prerender.mjs");
+        const scriptContent = generatePrerenderScript(projectRoot, urlsToRender, prerenderRouteHashMap);
+        writeFileSync2(scriptPath, scriptContent);
+        try {
+          const { execFileSync } = await import("node:child_process");
+          const cleanEnv = { ...process.env };
+          delete cleanEnv.NODE_OPTIONS;
+          delete cleanEnv.TSX;
+          execFileSync(process.execPath, ["--no-warnings", scriptPath], {
+            stdio: "inherit",
+            cwd: projectRoot,
+            env: cleanEnv
+          });
+          const chunkInfo = cfIntegrationApi?.handlerChunkInfo;
+          if (chunkInfo) {
+            const chunkPath = resolve3(projectRoot, "dist/rsc", chunkInfo.fileName);
+            try {
+              let code = readFileSync2(chunkPath, "utf-8");
+              const originalSize = Buffer.byteLength(code);
+              for (const { name, handlerId, passthrough } of chunkInfo.exports) {
+                if (passthrough) continue;
+                const callStartRe = new RegExp(
+                  `const\\s+${name}\\s*=\\s*createPrerenderHandler\\s*(?:<[^>]*>)?\\s*\\(`
+                );
+                const startMatch = callStartRe.exec(code);
+                if (!startMatch) continue;
+                const openParenPos = startMatch.index + startMatch[0].length;
+                let depth = 1;
+                let pos = openParenPos;
+                while (pos < code.length && depth > 0) {
+                  const ch = code[pos];
+                  if (ch === '"' || ch === "'" || ch === "`") {
+                    pos++;
+                    while (pos < code.length && code[pos] !== ch) {
+                      if (code[pos] === "\\") pos++;
+                      pos++;
+                    }
+                  } else if (ch === "(") {
+                    depth++;
+                  } else if (ch === ")") {
+                    depth--;
+                  }
+                  pos++;
+                }
+                if (depth !== 0) continue;
+                let rangeEnd = pos;
+                while (rangeEnd < code.length && /\s/.test(code[rangeEnd])) rangeEnd++;
+                if (code[rangeEnd] === ";") rangeEnd++;
+                const matched = code.slice(startMatch.index, rangeEnd);
+                if (!matched.includes(handlerId)) continue;
+                const stub = `const ${name} = { __brand: "prerenderHandler", $$id: "${handlerId}" };`;
+                code = code.slice(0, startMatch.index) + stub + code.slice(rangeEnd);
+                code = code.replace(
+                  new RegExp(`\\n${name}\\.\\$\\$id\\s*=\\s*"[^"]+";`),
+                  ""
+                );
+              }
+              writeFileSync2(chunkPath, code);
+              const newSize = Buffer.byteLength(code);
+              const savedKB = ((originalSize - newSize) / 1024).toFixed(1);
+              console.log(
+                `[rsc-router] Evicted handler code from RSC bundle (${savedKB} KB saved): ${chunkInfo.fileName}`
+              );
+            } catch (replaceErr) {
+              console.warn(
+                `[rsc-router] Failed to evict handler code: ${replaceErr.message}`
+              );
+            }
+          }
+          try {
+            const { readdirSync: readDir } = await import("node:fs");
+            const prerenderData = {};
+            const staticDir = resolve3(projectRoot, "dist/static");
+            for (const hashDir of readDir(staticDir).filter((d) => d.startsWith("__"))) {
+              const prerenderDir = resolve3(staticDir, hashDir, "prerender");
+              if (!existsSync3(prerenderDir)) continue;
+              for (const routeDir of readDir(prerenderDir)) {
+                const routePath = resolve3(prerenderDir, routeDir);
+                for (const file of readDir(routePath).filter((f) => f.endsWith(".flight"))) {
+                  const paramHash = file.slice(0, -7);
+                  const key = `${routeDir}/${paramHash}`;
+                  const content = readFileSync2(resolve3(routePath, file), "utf-8");
+                  prerenderData[key] = JSON.parse(content);
+                }
+              }
+            }
+            if (Object.keys(prerenderData).length > 0) {
+              const rscEntryPath = resolve3(projectRoot, "dist/rsc/index.js");
+              if (existsSync3(rscEntryPath)) {
+                let rscCode = readFileSync2(rscEntryPath, "utf-8");
+                const injection = `globalThis.__PRERENDER_DATA = ${JSON.stringify(prerenderData)};
+`;
+                rscCode = injection + rscCode;
+                writeFileSync2(rscEntryPath, rscCode);
+                const dataSize = (Buffer.byteLength(injection) / 1024).toFixed(1);
+                console.log(
+                  `[rsc-router] Injected prerender data into RSC bundle (${dataSize} KB, ${Object.keys(prerenderData).length} entries)`
+                );
+              }
+            }
+          } catch (injectErr) {
+            console.warn(
+              `[rsc-router] Failed to inject prerender data: ${injectErr.message}`
+            );
+          }
+        } catch (err) {
+          console.warn(
+            `[rsc-router] Build-time pre-rendering failed: ${err.message}`
+          );
+        } finally {
+          try {
+            const { rmSync } = await import("node:fs");
+            rmSync(scriptPath, { force: true });
+          } catch {
+          }
+        }
+      }
+    }
+  };
+}
+function generatePrerenderScript(projectRoot, urls, routeHashMap) {
+  return `
+import { mkdirSync, writeFileSync, symlinkSync, existsSync, readdirSync, statSync, lstatSync, rmSync } from "node:fs";
+import { resolve } from "node:path";
+
+const projectRoot = ${JSON.stringify(projectRoot)};
+const urls = ${JSON.stringify(urls)};
+const routeHashMap = ${JSON.stringify(routeHashMap)};
+
+// DJB2 hash matching the runtime param-hash utility
+function djb2Hex(str) {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = ((hash << 5) + hash + str.charCodeAt(i)) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+
+function hashParams(params) {
+  const entries = Object.entries(params);
+  if (entries.length === 0) return "_";
+  const sorted = entries.sort(([a], [b]) => a.localeCompare(b));
+  const str = sorted.map(([k, v]) => k + "=" + v).join("&");
+  return djb2Hex(str);
+}
+
+// Extract params from a URL by matching against the route pattern.
+// The route pattern uses :paramName syntax.
+function extractParams(urlPath, pattern) {
+  const urlParts = urlPath.split("/").filter(Boolean);
+  const patternParts = pattern.split("/").filter(Boolean);
+  const params = {};
+  for (let i = 0; i < patternParts.length; i++) {
+    if (patternParts[i].startsWith(":")) {
+      const paramName = patternParts[i].slice(1);
+      params[paramName] = decodeURIComponent(urlParts[i] || "");
+    }
+  }
+  return params;
+}
+
+// Mock workerd globals (bundled worker accesses globalThis.Cloudflare.compatibilityFlags)
+globalThis.Cloudflare = { compatibilityFlags: { enable_nodejs_process_v2: false } };
+
+// Create symlinks for project root directories under dist/ so that relative
+// paths from import.meta.dirname (dist/rsc/assets/) resolve correctly.
+const symlinks = [];
+try {
+  for (const entry of readdirSync(projectRoot)) {
+    if (entry === "dist" || entry === "node_modules" || entry.startsWith(".")) continue;
+    const target = resolve(projectRoot, entry);
+    const link = resolve(projectRoot, "dist", entry);
+    try {
+      if (!existsSync(link) && statSync(target).isDirectory()) {
+        symlinkSync(target, link);
+        symlinks.push(link);
+      }
+    } catch {}
+  }
+} catch {}
+
+const mockEnv = new Proxy({}, {
+  get(_, prop) {
+    if (prop === "toString" || prop === Symbol.toPrimitive) return () => "[PrerenderEnv]";
+    if (prop === Symbol.toStringTag) return "PrerenderEnv";
+    if (prop === "Variables") return {};
+    if (prop === "ASSETS") return { fetch: () => new Response("", { status: 404 }) };
+    throw new Error("Cloudflare binding \\"" + String(prop) + "\\" not available in prerender");
+  },
+});
+const mockCtx = { waitUntil: () => {}, passThroughOnException: () => {} };
+
+try {
+  const mod = await import(resolve(projectRoot, "dist/rsc/index.js"));
+  const worker = mod.default;
+  if (!worker?.fetch) {
+    console.warn("[rsc-router] Built worker has no fetch handler, skipping pre-render");
+    process.exit(0);
+  }
+
+  let rendered = 0;
+  for (const urlPath of urls) {
+    try {
+      // Collect serialized segments for this route
+      const response = await worker.fetch(
+        new Request("http://localhost" + urlPath + "?__no_cache&__prerender_collect", {
+          headers: { Accept: "text/html" },
+        }),
+        mockEnv,
+        mockCtx,
+      );
+      if (response.status !== 200) {
+        console.warn("[rsc-router] Pre-render collect " + urlPath + " returned " + response.status + ", skipping");
+        continue;
+      }
+      const data = await response.json();
+      const { segments, handles, routeName } = data;
+      if (!routeName || !segments) {
+        console.warn("[rsc-router] Pre-render collect " + urlPath + " missing routeName or segments, skipping");
+        continue;
+      }
+
+      const routerHash = routeHashMap[routeName];
+      if (!routerHash) {
+        console.warn("[rsc-router] No router hash for route " + routeName + ", skipping");
+        continue;
+      }
+
+      // Compute param hash from the matched route params
+      // The response carries routeName; we compute params from the URL
+      // using the route manifest pattern. For static routes, paramHash is "_".
+      const paramHash = hashParams(data.params || {});
+
+      // Write .flight file
+      const flightDir = resolve(projectRoot, "dist", "static",
+        "__" + routerHash, "prerender", routeName);
+      mkdirSync(flightDir, { recursive: true });
+      const flightPath = resolve(flightDir, paramHash + ".flight");
+      writeFileSync(flightPath, JSON.stringify({ segments, handles }));
+
+      rendered++;
+      console.log("[rsc-router] Pre-rendered: " + routeName + " (" + urlPath + ") -> " + paramHash + ".flight");
+    } catch (err) {
+      console.warn("[rsc-router] Pre-render failed for " + urlPath + ": " + err.message);
+    }
+  }
+
+  if (rendered > 0) {
+    console.log("[rsc-router] Pre-rendered " + rendered + "/" + urls.length + " route(s) to dist/static/");
+  }
+} finally {
+  for (const link of symlinks) {
+    try { if (lstatSync(link).isSymbolicLink()) rmSync(link); } catch {}
+  }
+}
+`.trim();
+}
+var VIRTUAL_ROUTES_MANIFEST_ID = "virtual:rsc-router/routes-manifest";
+function resolveDiscoveryEntryPath(options, routerPath) {
+  if (options.preset === "cloudflare") {
+    const wranglerPaths = ["wrangler.json", "wrangler.jsonc"];
+    for (const filename of wranglerPaths) {
+      if (existsSync3(filename)) {
+        try {
+          const raw = readFileSync2(filename, "utf-8");
+          const cleaned = raw.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
+          const config = JSON.parse(cleaned);
+          if (config.main) {
+            return config.main;
+          }
+        } catch {
+        }
+      }
+    }
+    return void 0;
+  }
+  return routerPath;
+}
+function createVirtualStubPlugin() {
+  const STUB_PREFIXES = [
+    "virtual:rsc-router/",
+    "virtual:entry-",
+    "virtual:vite-rsc/"
+  ];
+  return {
+    name: "@rangojs/router:virtual-stubs",
+    resolveId(id) {
+      if (STUB_PREFIXES.some((p) => id.startsWith(p))) {
+        return "\0stub:" + id;
+      }
+      return null;
+    },
+    load(id) {
+      if (id.startsWith("\0stub:")) {
+        return "export default {}";
+      }
+      return null;
+    }
+  };
+}
+function hashRouterId(id) {
+  return createHash("sha256").update(id).digest("hex").slice(0, 12);
+}
+function createVersionInjectorPlugin(rscEntryPath) {
+  let projectRoot = "";
+  let resolvedEntryPath = "";
+  return {
+    name: "@rangojs/router:version-injector",
+    enforce: "pre",
+    configResolved(config) {
+      projectRoot = config.root;
+      resolvedEntryPath = resolve3(projectRoot, rscEntryPath);
+    },
+    transform(code, id) {
+      const normalizedId = Vite.normalizePath(id);
+      const normalizedEntry = Vite.normalizePath(resolvedEntryPath);
+      if (normalizedId !== normalizedEntry) {
+        return null;
+      }
+      const prepend = [];
+      let newCode = code;
+      if (!code.includes("virtual:rsc-router/routes-manifest")) {
+        prepend.push(`import "virtual:rsc-router/routes-manifest";`);
+      }
+      const needsVersion = code.includes("createRSCHandler") && !code.includes("@rangojs/router:version") && /createRSCHandler\s*\(\s*\{/.test(code);
+      if (needsVersion) {
+        prepend.push(`import { VERSION } from "@rangojs/router:version";`);
+        newCode = newCode.replace(
+          /createRSCHandler\s*\(\s*\{/,
+          "createRSCHandler({\n  version: VERSION,"
+        );
+      }
+      if (prepend.length === 0 && newCode === code) return null;
+      newCode = prepend.join("\n") + (prepend.length > 0 ? "\n" : "") + newCode;
+      return {
+        code: newCode,
+        map: null
+      };
+    }
+  };
+}
+var _require = createRequire(import.meta.url);
+var _rangoVersion = _require("../../package.json").version;
+var _bannerPrinted = false;
+function printBanner(mode, preset, version) {
+  if (_bannerPrinted) return;
+  _bannerPrinted = true;
+  const dim = "\x1B[2m";
+  const bold = "\x1B[1m";
+  const reset = "\x1B[0m";
+  const banner = `
+${dim}  \u2726        \u2726          \u2727.           .          .${reset}
+${dim} \u2571${reset}    ${bold}\u2554\u2550\u2557${reset}${dim}      *      \u2571                   \u2726             *${reset}
+${dim}      ${reset}${bold}\u2551 \u2551${reset} ${bold}\u2554\u2550\u2557${reset}${dim}                    *                \u2727.   \u2571${reset}
+${dim}   ${reset}${bold}\u2554\u2557 \u2551 \u2551 \u2551 \u2551${reset}${dim}                          *               \u2571${reset}
+${dim}   ${reset}${bold}\u2551\u2551 \u2551 \u2551 \u2551 \u2551  \u2566\u2550\u2557\u2554\u2550\u2557\u2554\u2557\u2554\u2554\u2550\u2557\u2554\u2550\u2557${reset}${dim}             \u2727              \u2726${reset}
+${dim}  ${reset}${bold}\u2550\u2563\u2551 \u2551 \u2560\u2550\u255D \u2551  \u2560\u2566\u255D\u2560\u2550\u2563\u2551\u2551\u2551\u2551 \u2566\u2551 \u2551${reset}${dim}        *           \u2727${reset}
+${dim}   ${reset}${bold}\u2551\u255A\u2550\u255D \u2554\u2550\u2550\u2550\u255D  \u2569\u255A\u2550\u2569 \u2569\u255D\u255A\u255D\u255A\u2550\u255D\u255A\u2550\u255D${reset}${dim}            \u2726          .      *${reset}
+${dim}   ${reset}${bold}\u255A\u2550\u2550\u2557 \u2551${reset}${dim} *      RSC Wrangler         \u2727                \u2726${reset}
+${dim}  *   ${reset}${bold}\u2551 \u2560\u2550${reset}${dim}                         *            \u2727.    \u2571${reset}
+${bold}\u2550\u2550\u2550\u2550\u2550\u2550\u255D \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2569\u2550\u2550\u2550${reset}${dim}                  \u2726            *${reset}
+
+   v${version} \xB7 ${preset} \xB7 ${mode}
+`;
+  console.log(banner);
+}
+async function rango(options) {
+  const resolvedOptions = options ?? { preset: "node" };
+  const preset = resolvedOptions.preset ?? "node";
+  const showBanner = resolvedOptions.banner ?? true;
+  const plugins = [];
+  const rangoAliases = getPackageAliases();
+  const excludeDeps = getExcludeDeps();
+  let rscEntryPath = null;
+  let routerPath;
+  const prerenderEnabled = preset === "cloudflare";
+  if (preset === "cloudflare") {
+    const { default: rsc } = await import("@vitejs/plugin-rsc");
+    const finalEntries = {
+      client: VIRTUAL_IDS.browser,
+      ssr: VIRTUAL_IDS.ssr
+    };
+    const cfApi = { handlerChunkInfo: null };
+    let resolvedPrerenderModules;
+    plugins.push({
+      name: "@rangojs/router:cloudflare-integration",
+      enforce: "pre",
+      api: cfApi,
+      config() {
+        return {
+          // Exclude rsc-router modules from optimization to prevent module duplication
+          // This ensures the same Context instance is used by both browser entry and RSC proxy modules
+          optimizeDeps: {
+            exclude: excludeDeps,
+            esbuildOptions: sharedEsbuildOptions
+          },
+          resolve: {
+            alias: rangoAliases
+          },
+          environments: {
+            client: {
+              build: {
+                rollupOptions: {
+                  output: {
+                    manualChunks: getManualChunks
+                  }
+                }
+              },
+              // Pre-bundle rsc-html-stream to prevent discovery during first request
+              // Exclude rsc-router modules to ensure same Context instance
+              optimizeDeps: {
+                include: ["rsc-html-stream/client"],
+                exclude: excludeDeps,
+                esbuildOptions: sharedEsbuildOptions
+              }
+            },
+            ssr: {
+              // Build SSR inside RSC directory so wrangler can deploy self-contained dist/rsc
+              build: {
+                outDir: "./dist/rsc/ssr"
+              },
+              resolve: {
+                // Ensure single React instance in SSR child environment
+                dedupe: ["react", "react-dom"]
+              },
+              // Pre-bundle SSR entry and React for proper module linking with childEnvironments
+              // All deps must be listed to avoid late discovery triggering ERR_OUTDATED_OPTIMIZED_DEP
+              optimizeDeps: {
+                entries: [finalEntries.ssr],
+                include: [
+                  "react",
+                  "react-dom",
+                  "react-dom/server.edge",
+                  "react-dom/static.edge",
+                  "react/jsx-runtime",
+                  "react/jsx-dev-runtime",
+                  "rsc-html-stream/server",
+                  "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge"
+                ],
+                exclude: excludeDeps,
+                esbuildOptions: sharedEsbuildOptions
+              }
+            },
+            rsc: {
+              build: {
+                rollupOptions: {
+                  output: {
+                    manualChunks(id) {
+                      if (resolvedPrerenderModules?.has(id)) {
+                        return "__prerender-handlers";
+                      }
+                    }
+                  }
+                }
+              },
+              // RSC environment needs exclude list and esbuild options
+              // Exclude rsc-router modules to prevent createContext in RSC environment
+              optimizeDeps: {
+                exclude: excludeDeps,
+                esbuildOptions: sharedEsbuildOptions
+              }
+            }
+          }
+        };
+      },
+      configResolved(config) {
+        if (showBanner) {
+          const mode = config.command === "serve" ? process.argv.includes("preview") ? "preview" : "dev" : "build";
+          printBanner(mode, "cloudflare", _rangoVersion);
+        }
+        const prerenderPlugin = config.plugins.find(
+          (p) => p.name === "@rangojs/router:expose-prerender-handler-id"
+        );
+        resolvedPrerenderModules = prerenderPlugin?.api?.prerenderHandlerModules;
+      },
+      // Record handler chunk metadata during RSC build for post-prerender replacement.
+      // Rollup minifies EXPORT names (e.g. ArticlesIndex -> r) but keeps internal
+      // variable names intact. We search for original names from prerenderHandlerModules.
+      generateBundle(_options, bundle) {
+        if (this.environment?.name !== "rsc") return;
+        if (!resolvedPrerenderModules?.size) return;
+        for (const [fileName, chunk] of Object.entries(bundle)) {
+          if (chunk.type !== "chunk") continue;
+          if (!fileName.includes("__prerender-handlers")) continue;
+          const handlers = [];
+          for (const [, handlerNames] of resolvedPrerenderModules) {
+            for (const name of handlerNames) {
+              const idPattern = new RegExp(
+                `\\b${name}\\.\\$\\$id\\s*=\\s*"([^"]+)"`
+              );
+              const match = chunk.code.match(idPattern);
+              if (match) {
+                const callStartRe = new RegExp(
+                  `const\\s+${name}\\s*=\\s*createPrerenderHandler\\s*(?:<[^>]*>)?\\s*\\(`
+                );
+                const callStart = callStartRe.exec(chunk.code);
+                let isPassthrough = false;
+                if (callStart) {
+                  const openPos = callStart.index + callStart[0].length;
+                  let depth = 1;
+                  let p = openPos;
+                  while (p < chunk.code.length && depth > 0) {
+                    const ch = chunk.code[p];
+                    if (ch === '"' || ch === "'" || ch === "`") {
+                      p++;
+                      while (p < chunk.code.length && chunk.code[p] !== ch) {
+                        if (chunk.code[p] === "\\") p++;
+                        p++;
+                      }
+                    } else if (ch === "(") {
+                      depth++;
+                    } else if (ch === ")") {
+                      depth--;
+                    }
+                    p++;
+                  }
+                  if (depth === 0) {
+                    const callBody = chunk.code.slice(callStart.index, p);
+                    isPassthrough = /passthrough\s*:\s*(!0|true)/.test(callBody);
+                  }
+                }
+                handlers.push({ name, handlerId: match[1], passthrough: isPassthrough });
+              }
+            }
+          }
+          if (handlers.length > 0) {
+            cfApi.handlerChunkInfo = { fileName, exports: handlers };
+          }
+          break;
+        }
+      }
+    });
+    plugins.push(createVirtualEntriesPlugin(finalEntries));
+    plugins.push(
+      rsc({
+        get entries() {
+          return finalEntries;
+        },
+        serverHandler: false
+      })
+    );
+  } else {
+    const nodeOptions = resolvedOptions;
+    routerPath = nodeOptions.router;
+    if (!routerPath) {
+      const earlyFilter = createScanFilter(process.cwd(), {
+        include: resolvedOptions.include,
+        exclude: resolvedOptions.exclude
+      });
+      const candidates = findRouterFiles(process.cwd(), earlyFilter);
+      if (candidates.length === 1) {
+        const abs = candidates[0];
+        const rel = abs.startsWith(process.cwd()) ? "./" + abs.slice(process.cwd().length + 1) : abs;
+        routerPath = rel;
+      } else if (candidates.length > 1) {
+        const cwd = process.cwd();
+        const list = candidates.map((f) => "  - " + (f.startsWith(cwd) ? f.slice(cwd.length + 1) : f)).join("\n");
+        throw new Error(
+          `[rsc-router] Multiple routers found. Specify \`router\` to choose one:
+${list}`
+        );
+      }
+    }
+    const rscOption = nodeOptions.rsc ?? true;
+    if (rscOption !== false) {
+      const { default: rsc } = await import("@vitejs/plugin-rsc");
+      const userEntries = typeof rscOption === "boolean" ? {} : rscOption.entries || {};
+      const finalEntries = {
+        client: userEntries.client ?? VIRTUAL_IDS.browser,
+        ssr: userEntries.ssr ?? VIRTUAL_IDS.ssr,
+        rsc: userEntries.rsc ?? VIRTUAL_IDS.rsc
+      };
+      rscEntryPath = userEntries.rsc ?? null;
+      let hasWarnedDuplicate = false;
+      plugins.push({
+        name: "@rangojs/router:rsc-integration",
+        enforce: "pre",
+        config() {
+          const useVirtualClient = finalEntries.client === VIRTUAL_IDS.browser;
+          const useVirtualSSR = finalEntries.ssr === VIRTUAL_IDS.ssr;
+          const useVirtualRSC = finalEntries.rsc === VIRTUAL_IDS.rsc;
+          return {
+            // Exclude rsc-router modules from optimization to prevent module duplication
+            // This ensures the same Context instance is used by both browser entry and RSC proxy modules
+            optimizeDeps: {
+              exclude: excludeDeps,
+              esbuildOptions: sharedEsbuildOptions
+            },
+            resolve: {
+              alias: rangoAliases
+            },
+            environments: {
+              client: {
+                build: {
+                  rollupOptions: {
+                    output: {
+                      manualChunks: getManualChunks
+                    }
+                  }
+                },
+                // Always exclude rsc-router modules, conditionally add virtual entry
+                optimizeDeps: {
+                  exclude: excludeDeps,
+                  esbuildOptions: sharedEsbuildOptions,
+                  ...useVirtualClient && {
+                    // Tell Vite to scan the virtual entry for dependencies
+                    entries: [VIRTUAL_IDS.browser]
+                  }
+                }
+              },
+              ...useVirtualSSR && {
+                ssr: {
+                  optimizeDeps: {
+                    entries: [VIRTUAL_IDS.ssr],
+                    // Pre-bundle all SSR deps to prevent late discovery triggering ERR_OUTDATED_OPTIMIZED_DEP
+                    include: [
+                      "react",
+                      "react-dom",
+                      "react-dom/server.edge",
+                      "react-dom/static.edge",
+                      "react/jsx-runtime",
+                      "react/jsx-dev-runtime",
+                      "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge"
+                    ],
+                    exclude: excludeDeps,
+                    esbuildOptions: sharedEsbuildOptions
+                  }
+                }
+              },
+              ...useVirtualRSC && {
+                rsc: {
+                  optimizeDeps: {
+                    entries: [VIRTUAL_IDS.rsc],
+                    // Pre-bundle React for RSC to ensure single instance
+                    include: ["react", "react/jsx-runtime"],
+                    esbuildOptions: sharedEsbuildOptions
+                  }
+                }
+              }
+            }
+          };
+        },
+        configResolved(config) {
+          if (showBanner) {
+            const mode = config.command === "serve" ? process.argv.includes("preview") ? "preview" : "dev" : "build";
+            printBanner(mode, "node", _rangoVersion);
+          }
+          const rscMinimalCount = config.plugins.filter(
+            (p) => p.name === "rsc:minimal"
+          ).length;
+          if (rscMinimalCount > 1 && !hasWarnedDuplicate) {
+            hasWarnedDuplicate = true;
+            console.warn(
+              "[rsc-router] Duplicate @vitejs/plugin-rsc detected. Remove rsc() from your config or use rango({ rsc: false }) for manual configuration."
+            );
+          }
+        }
+      });
+      plugins.push(createVirtualEntriesPlugin(finalEntries, routerPath));
+      plugins.push(
+        rsc({
+          entries: finalEntries
+        })
+      );
+    }
+  }
+  plugins.push(exposeActionId());
+  plugins.push(exposeLoaderId());
+  plugins.push(exposeHandleId());
+  plugins.push(exposeLocationStateId());
+  plugins.push(exposePrerenderHandlerId());
+  plugins.push(createVersionPlugin());
+  const discoveryEntryPath = resolveDiscoveryEntryPath(
+    resolvedOptions,
+    preset !== "cloudflare" ? routerPath : void 0
+  );
+  const injectorEntryPath = rscEntryPath ?? (preset === "cloudflare" ? discoveryEntryPath : null);
+  if (injectorEntryPath) {
+    plugins.push(createVersionInjectorPlugin(injectorEntryPath));
+  }
+  plugins.push(createCjsToEsmPlugin());
+  if (discoveryEntryPath) {
+    plugins.push(createRouterDiscoveryPlugin(discoveryEntryPath, {
+      enableBuildPrerender: prerenderEnabled,
+      staticRouteTypesGeneration: resolvedOptions.staticRouteTypesGeneration,
+      include: resolvedOptions.include,
+      exclude: resolvedOptions.exclude
+    }));
+  }
+  return plugins;
+}
+function createCjsToEsmPlugin() {
+  return {
+    name: "@rangojs/router:cjs-to-esm",
+    enforce: "pre",
+    transform(code, id) {
+      const cleanId = id.split("?")[0];
+      if (cleanId.includes("vendor/react-server-dom/client.browser.js") || cleanId.includes("vendor\\react-server-dom\\client.browser.js")) {
+        const isProd = process.env.NODE_ENV === "production";
+        const cjsFile = isProd ? "./cjs/react-server-dom-webpack-client.browser.production.js" : "./cjs/react-server-dom-webpack-client.browser.development.js";
+        return {
+          code: `export * from "${cjsFile}";`,
+          map: null
+        };
+      }
+      if ((cleanId.includes("vendor/react-server-dom/cjs/") || cleanId.includes("vendor\\react-server-dom\\cjs\\")) && cleanId.includes("client.browser")) {
+        let transformed = code;
+        const licenseMatch = transformed.match(/^\/\*\*[\s\S]*?\*\//);
+        const license = licenseMatch ? licenseMatch[0] : "";
+        if (license) {
+          transformed = transformed.slice(license.length);
+        }
+        transformed = transformed.replace(/^\s*["']use strict["'];\s*/, "");
+        transformed = transformed.replace(
+          /^\s*["']production["']\s*!==\s*process\.env\.NODE_ENV\s*&&\s*\(function\s*\(\)\s*\{/,
+          ""
+        );
+        transformed = transformed.replace(/\}\)\(\);?\s*$/, "");
+        transformed = transformed.replace(
+          /var\s+React\s*=\s*require\s*\(\s*["']react["']\s*\)\s*,[\s\n]+ReactDOM\s*=\s*require\s*\(\s*["']react-dom["']\s*\)\s*,/g,
+          'import React from "react";\nimport ReactDOM from "react-dom";\nvar '
+        );
+        transformed = transformed.replace(
+          /var\s+ReactDOM\s*=\s*require\s*\(\s*["']react-dom["']\s*\)\s*,/g,
+          'import ReactDOM from "react-dom";\nvar '
+        );
+        transformed = transformed.replace(
+          /exports\.(\w+)\s*=\s*function\s*\(/g,
+          "export function $1("
+        );
+        transformed = transformed.replace(
+          /exports\.(\w+)\s*=/g,
+          "export const $1 ="
+        );
+        transformed = license + "\n" + transformed;
+        return {
+          code: transformed,
+          map: null
+        };
+      }
+      return null;
+    }
+  };
+}
+export {
+  exposeActionId,
+  exposeHandleId,
+  exposeLoaderId,
+  exposeLocationStateId,
+  exposePrerenderHandlerId,
+  rango
+};