@rangojs/router 0.0.0-experimental.9eb4192e → 0.0.0-experimental.a014d2b7

package/dist/vite/index.js

@@ -10,6 +10,13 @@ import fs from "node:fs";
 // src/vite/plugins/expose-id-utils.ts
 import path from "node:path";
 import crypto from "node:crypto";
+
+// src/regex-escape.ts
+function escapeRegExp(input) {
+  return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// src/vite/plugins/expose-id-utils.ts
 function normalizePath(p) {
   return p.split(path.sep).join("/");
 }
@@ -21,8 +28,8 @@ function hashId(filePath, exportName) {
 function makeStubId(filePath, exportName, isBuild) {
   return isBuild ? hashId(filePath, exportName) : `${filePath}#${exportName}`;
 }
-function hashInlineId(filePath, lineNumber, index) {
-  const input = index !== void 0 && index > 0 ? `${filePath}:${lineNumber}:${index}` : `${filePath}:${lineNumber}`;
+function hashInlineId(filePath, fnName, index) {
+  const input = `${filePath}:${fnName}:${index}`;
   return crypto.createHash("sha256").update(input).digest("hex").slice(0, 8);
 }
 function buildExportMap(program) {
@@ -158,7 +165,9 @@ function countArgs(code, startPos, endPos) {
   while (i < endPos) {
     const skipped = skipStringOrComment(code, i);
     if (skipped > i) {
-      hasContent = true;
+      const ch = code[i];
+      const isComment = ch === "/" && i + 1 < code.length && (code[i + 1] === "/" || code[i + 1] === "*");
+      if (!isComment) hasContent = true;
       i = skipped;
       continue;
     }
@@ -187,12 +196,73 @@ function findStatementEnd(code, pos) {
   }
   return i;
 }
-function escapeRegExp(input) {
-  return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function findCallParenAfterGenerics(code, afterCalleeIndex) {
+  let i = afterCalleeIndex;
+  while (i < code.length) {
+    const skipped = skipStringOrComment(code, i);
+    if (skipped > i) {
+      i = skipped;
+      continue;
+    }
+    if (/\s/.test(code[i])) {
+      i++;
+      continue;
+    }
+    break;
+  }
+  if (i >= code.length) return -1;
+  if (code[i] === "(") return i;
+  if (code[i] === "<") {
+    let depth = 0;
+    while (i < code.length) {
+      const skipped = skipStringOrComment(code, i);
+      if (skipped > i) {
+        i = skipped;
+        continue;
+      }
+      const ch = code[i];
+      if (ch === "<") {
+        depth++;
+      } else if (ch === ">") {
+        depth--;
+        if (depth === 0) {
+          i++;
+          break;
+        }
+      }
+      i++;
+    }
+    if (depth !== 0) return -1;
+    while (i < code.length) {
+      const skipped = skipStringOrComment(code, i);
+      if (skipped > i) {
+        i = skipped;
+        continue;
+      }
+      if (/\s/.test(code[i])) {
+        i++;
+        continue;
+      }
+      break;
+    }
+    if (i < code.length && code[i] === "(") return i;
+    return -1;
+  }
+  return -1;
 }
 
 // src/vite/debug.ts
 import debugFactory from "debug";
+var NS = {
+  config: "rango:config",
+  discovery: "rango:discovery",
+  routes: "rango:routes",
+  prerender: "rango:prerender",
+  build: "rango:build",
+  dev: "rango:dev",
+  transform: "rango:transform",
+  chunks: "rango:chunks"
+};
 if (process.env.INTERNAL_RANGO_DEBUG) {
   const existing = debugFactory.disable();
   debugFactory.enable(existing ? `${existing},rango:*` : "rango:*");
@@ -228,19 +298,34 @@ function createCounter(debug11, label) {
   let totalMs = 0;
   let slowestMs = 0;
   let slowestFile = "";
-  let flushed = false;
+  const record = (file, ms) => {
+    n++;
+    totalMs += ms;
+    if (ms > slowestMs) {
+      slowestMs = ms;
+      slowestFile = file;
+    }
+  };
   return {
-    record(file, ms) {
-      n++;
-      totalMs += ms;
-      if (ms > slowestMs) {
-        slowestMs = ms;
-        slowestFile = file;
+    record,
+    time(file, fn) {
+      const start = performance.now();
+      let out;
+      try {
+        out = fn();
+      } catch (err) {
+        record(file, performance.now() - start);
+        throw err;
+      }
+      if (out && typeof out.then === "function") {
+        return out.finally(
+          () => record(file, performance.now() - start)
+        );
       }
+      record(file, performance.now() - start);
+      return out;
     },
     flush() {
-      if (flushed) return;
-      flushed = true;
       if (n === 0) return;
       debug11(
         "%s: %d files, %sms total, slowest %sms %s",
@@ -250,12 +335,16 @@ function createCounter(debug11, label) {
         slowestMs.toFixed(1),
         slowestFile
       );
+      n = 0;
+      totalMs = 0;
+      slowestMs = 0;
+      slowestFile = "";
     }
   };
 }
 
 // src/vite/plugins/expose-action-id.ts
-var debug = createRangoDebugger("rango:transform");
+var debug = createRangoDebugger(NS.transform);
 function getRscPluginApi(config) {
   let plugin = config.plugins.find((p) => p.name === "rsc:minimal");
   if (!plugin) {
@@ -264,7 +353,7 @@ function getRscPluginApi(config) {
     );
     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.`
+        `[rango:expose-action-id] RSC plugin found by API structure (name: "${plugin.name}"). Consider updating the name lookup if the plugin was renamed.`
       );
     }
   }
@@ -365,7 +454,7 @@ function exposeActionId() {
       }
       if (!rscPluginApi) {
         throw new Error(
-          "[rsc-router] Could not find @vitejs/plugin-rsc. @rangojs/router requires the Vite RSC plugin, which is included automatically by rango()."
+          "[rango] Could not find @vitejs/plugin-rsc. @rangojs/router requires the Vite RSC plugin, which is included automatically by rango()."
         );
       }
       if (!isBuild) return;
@@ -402,7 +491,6 @@ function exposeActionId() {
         counterTransform?.record(id, performance.now() - start);
       }
     },
-    // Build mode: renderChunk runs after all transforms and bundling complete
     renderChunk(code, chunk) {
       const start = counterRender ? performance.now() : 0;
       try {
@@ -437,17 +525,17 @@ function exposeActionId() {
 
 // src/vite/plugins/expose-internal-ids.ts
 import { parseAst as parseAst2 } from "vite";
-import MagicString4 from "magic-string";
+import MagicString3 from "magic-string";
 import path4 from "node:path";
 
 // src/vite/utils/ast-handler-extract.ts
 function isDirectivePrologueStatement(node) {
   return node?.type === "ExpressionStatement" && typeof node.directive === "string";
 }
-function findImportInsertionPos(code, parseAst4) {
+function findImportInsertionPos(code, parseAst5) {
   let program;
   try {
-    program = parseAst4(code, { jsx: true });
+    program = parseAst5(code, { lang: "tsx" });
   } catch {
     return 0;
   }
@@ -484,10 +572,10 @@ function walkNode(node, parent, ancestors, enter) {
   }
   ancestors.pop();
 }
-function findHandlerCalls(code, fnName, parseAst4) {
+function findHandlerCalls(code, fnName, parseAst5) {
   let program;
   try {
-    program = parseAst4(code, { jsx: true });
+    program = parseAst5(code, { lang: "tsx" });
   } catch {
     return [];
   }
@@ -559,18 +647,18 @@ function getImportedLocalNamesFromProgram(program, importedName) {
   }
   return localNames;
 }
-function getImportedLocalNames(code, importedName, parseAst4) {
+function getImportedLocalNames(code, importedName, parseAst5) {
   try {
-    const program = parseAst4(code, { jsx: true });
+    const program = parseAst5(code, { lang: "tsx" });
     return getImportedLocalNamesFromProgram(program, importedName);
   } catch {
     return /* @__PURE__ */ new Set();
   }
 }
-function extractImportDeclarations(code, parseAst4) {
+function extractImportDeclarations(code, parseAst5) {
   let program;
   try {
-    program = parseAst4(code, { jsx: true });
+    program = parseAst5(code, { lang: "tsx" });
   } catch {
     return [];
   }
@@ -594,13 +682,18 @@ function isInertExpression(node) {
         (e) => e === null || isInertExpression(e)
       );
     case "ObjectExpression":
-      return (node.properties ?? []).every(
-        (p) => p.type === "Property" && (!p.computed || isInertExpression(p.key)) && isInertExpression(p.value)
-      );
+      return (node.properties ?? []).every((p) => {
+        if (p.type === "SpreadElement" || p.type === "RestElement") {
+          return isInertExpression(p.argument);
+        }
+        return p.type === "Property" && (!p.computed || isInertExpression(p.key)) && isInertExpression(p.value);
+      });
     case "UnaryExpression":
       return isInertExpression(node.argument);
     case "BinaryExpression":
       return isInertExpression(node.left) && isInertExpression(node.right);
+    case "LogicalExpression":
+      return isInertExpression(node.left) && isInertExpression(node.right);
     case "ConditionalExpression":
       return isInertExpression(node.test) && isInertExpression(node.consequent) && isInertExpression(node.alternate);
     case "SpreadElement":
@@ -622,10 +715,10 @@ function isSafeVariableDeclaration(node, handlerNames) {
     (d) => isSafeDeclaratorInit(d.init) && !(d.init?.type === "CallExpression" && d.init.callee?.type === "Identifier" && handlerNames.has(d.init.callee.name))
   );
 }
-function extractModuleLevelDeclarations(code, parseAst4, handlerNames) {
+function extractModuleLevelDeclarations(code, parseAst5, handlerNames) {
   let program;
   try {
-    program = parseAst4(code, { jsx: true });
+    program = parseAst5(code, { lang: "tsx" });
   } catch {
     return [];
   }
@@ -656,27 +749,25 @@ function extractModuleLevelDeclarations(code, parseAst4, handlerNames) {
   }
   return declarations;
 }
-function transformInlineHandlers(fnName, virtualPrefix, s, code, filePath, virtualRegistry, moduleId, parseAst4) {
-  const sites = findHandlerCalls(code, fnName, parseAst4);
+function transformInlineHandlers(fnName, virtualPrefix, s, code, filePath, virtualRegistry, moduleId, parseAst5) {
+  const sites = findHandlerCalls(code, fnName, parseAst5);
   const inlineSites = sites.filter((site) => site.exportInfo === null);
   if (inlineSites.length === 0) return false;
-  const imports = extractImportDeclarations(code, parseAst4);
-  const staticNames = getImportedLocalNames(code, "Static", parseAst4);
-  const prerenderNames = getImportedLocalNames(code, "Prerender", parseAst4);
+  const imports = extractImportDeclarations(code, parseAst5);
+  const staticNames = getImportedLocalNames(code, "Static", parseAst5);
+  const prerenderNames = getImportedLocalNames(code, "Prerender", parseAst5);
   const handlerNames = /* @__PURE__ */ new Set([...staticNames, ...prerenderNames]);
   const declarations = extractModuleLevelDeclarations(
     code,
-    parseAst4,
+    parseAst5,
     handlerNames
   );
-  const lineCounts = /* @__PURE__ */ new Map();
   const importStatements = [];
-  for (const site of inlineSites) {
-    const lineCount = lineCounts.get(site.lineNumber) ?? 0;
-    lineCounts.set(site.lineNumber, lineCount + 1);
-    const hash = hashInlineId(filePath, site.lineNumber, lineCount);
+  for (const [siteIndex, site] of inlineSites.entries()) {
+    const hash = hashInlineId(filePath, fnName, siteIndex);
     const exportName = `__sh_${hash}`;
-    const virtualId = `\0${virtualPrefix}${filePath}:${site.lineNumber}${lineCount > 0 ? `:${lineCount}` : ""}`;
+    const idSuffix = `${filePath}:${fnName}:${siteIndex}`;
+    const virtualId = `\0${virtualPrefix}${idSuffix}`;
     const handlerCode = code.slice(site.callStart, site.callEnd);
     virtualRegistry.set(virtualId, {
       originalModuleId: moduleId,
@@ -686,12 +777,12 @@ function transformInlineHandlers(fnName, virtualPrefix, s, code, filePath, virtu
       exportName
     });
     s.overwrite(site.callStart, site.callEnd, exportName);
-    const importId = `${virtualPrefix}${filePath}:${site.lineNumber}${lineCount > 0 ? `:${lineCount}` : ""}`;
+    const importId = `${virtualPrefix}${idSuffix}`;
     importStatements.push(`import { ${exportName} } from "${importId}";`);
   }
   if (importStatements.length > 0) {
     const importBlock = importStatements.join("\n") + "\n";
-    const insertionPos = findImportInsertionPos(code, parseAst4);
+    const insertionPos = findImportInsertionPos(code, parseAst5);
     if (insertionPos === 0) {
       s.prepend(importBlock);
     } else {
@@ -718,6 +809,138 @@ var STRICT_CREATE_CONFIGS = [
 
 // src/vite/plugins/expose-ids/export-analysis.ts
 import { parseAst } from "vite";
+
+// src/build/route-types/source-scan.ts
+function isLineTerminator(ch) {
+  const c = ch.charCodeAt(0);
+  return c === 10 || c === 13 || c === 8232 || c === 8233;
+}
+var REGEX_PRECEDING_KEYWORDS = /* @__PURE__ */ new Set([
+  "return",
+  "typeof",
+  "instanceof",
+  "in",
+  "of",
+  "new",
+  "delete",
+  "void",
+  "do",
+  "else",
+  "yield",
+  "await",
+  "case",
+  "throw"
+]);
+function isRegexPositionAt(code, slashPos, prevChar) {
+  if (prevChar === void 0) return true;
+  if (prevChar === ")" || prevChar === "]" || prevChar === "}") return false;
+  if (!/[\w$]/.test(prevChar)) return true;
+  let k = slashPos - 1;
+  while (k >= 0 && /\s/.test(code[k])) k--;
+  const wordEnd = k + 1;
+  while (k >= 0 && /[\w$]/.test(code[k])) k--;
+  return REGEX_PRECEDING_KEYWORDS.has(code.slice(k + 1, wordEnd));
+}
+function makeCodeClassifier(code) {
+  const n = code.length;
+  let i = 0;
+  let skipStart = -1;
+  let skipEnd = -1;
+  let lastSig;
+  return (q) => {
+    if (q >= skipStart && q < skipEnd) return false;
+    while (i < n && i <= q) {
+      const c = code[i];
+      const d = i + 1 < n ? code[i + 1] : "";
+      let end = -1;
+      let transparent = false;
+      if (c === "/" && d === "/") {
+        let j = i + 2;
+        while (j < n && !isLineTerminator(code[j])) j++;
+        end = j;
+        transparent = true;
+      } else if (c === "/" && d === "*") {
+        let j = i + 2;
+        while (j < n && !(code[j] === "*" && code[j + 1] === "/")) j++;
+        end = Math.min(n, j + 2);
+        transparent = true;
+      } else if (c === '"' || c === "'" || c === "`") {
+        let j = i + 1;
+        while (j < n) {
+          if (code[j] === "\\") {
+            j += 2;
+            continue;
+          }
+          if (code[j] === c) {
+            j++;
+            break;
+          }
+          j++;
+        }
+        end = j;
+      } else if (c === "/" && d !== "/" && d !== "*" && isRegexPositionAt(code, i, lastSig)) {
+        let j = i + 1;
+        let inClass = false;
+        let closed = false;
+        while (j < n && !isLineTerminator(code[j])) {
+          const r = code[j];
+          if (r === "\\") {
+            j += 2;
+            continue;
+          }
+          if (r === "[") inClass = true;
+          else if (r === "]") inClass = false;
+          else if (r === "/" && !inClass) {
+            j++;
+            closed = true;
+            break;
+          }
+          j++;
+        }
+        if (closed) {
+          while (j < n && /[a-z]/.test(code[j])) j++;
+          end = j;
+        }
+      }
+      if (end >= 0) {
+        if (q < end) {
+          skipStart = i;
+          skipEnd = end;
+          return false;
+        }
+        i = end;
+        if (!transparent) lastSig = "x";
+      } else {
+        if (!/\s/.test(c)) lastSig = c;
+        i++;
+      }
+    }
+    return true;
+  };
+}
+function firstCodeMatchIndex(code, pattern) {
+  const inCode = makeCodeClassifier(code);
+  pattern.lastIndex = 0;
+  let m;
+  while ((m = pattern.exec(code)) !== null) {
+    if (inCode(m.index)) return m.index;
+    if (pattern.lastIndex <= m.index) pattern.lastIndex = m.index + 1;
+  }
+  return -1;
+}
+function codeMatchIndices(code, pattern) {
+  const inCode = makeCodeClassifier(code);
+  const indices = [];
+  pattern.lastIndex = 0;
+  let m;
+  while ((m = pattern.exec(code)) !== null) {
+    if (inCode(m.index)) indices.push(m.index);
+    if (pattern.lastIndex <= m.index) pattern.lastIndex = m.index + 1;
+  }
+  return indices;
+}
+
+// src/vite/plugins/expose-ids/export-analysis.ts
 function isExportOnlyFile(code, bindings) {
   if (bindings.length === 0) return false;
   const knownLocals = /* @__PURE__ */ new Set();
@@ -746,12 +969,40 @@ function isExportOnlyFile(code, bindings) {
   }
   return true;
 }
-function countCreateCallsForNames(code, fnNames) {
-  const pattern = new RegExp(
-    `\\b(?:${fnNames.map(escapeRegExp).join("|")})\\s*(?:<[^>]*>\\s*)?\\(`,
-    "g"
+function createCallPattern(fnNames) {
+  return new RegExp(`\\b(?:${fnNames.map(escapeRegExp).join("|")})\\b`, "g");
+}
+function createCallStartIndices(code, fnNames) {
+  return codeMatchIndices(code, createCallPattern(fnNames)).filter(
+    (index) => findCallParenAfterGenerics(
+      code,
+      index + matchedNameLength(code, index)
+    ) !== -1
   );
-  return (code.match(pattern) || []).length;
+}
+function matchedNameLength(code, index) {
+  let i = index;
+  while (i < code.length && /[A-Za-z0-9_$]/.test(code[i])) i++;
+  return i - index;
+}
+function countCreateCallsForNames(code, fnNames) {
+  return createCallStartIndices(code, fnNames).length;
+}
+function offsetToLineColumn(code, index) {
+  let line = 1;
+  let lineStart = 0;
+  const end = Math.min(index, code.length);
+  for (let i = 0; i < end; i++) {
+    if (code[i] === "\n") {
+      line++;
+      lineStart = i + 1;
+    }
+  }
+  return { line, column: index - lineStart + 1 };
+}
+function findUnsupportedCreateCallSites(code, fnNames, supportedBindings) {
+  const supported = new Set(supportedBindings.map((b) => b.callExprStart));
+  return createCallStartIndices(code, fnNames).filter((index) => !supported.has(index)).map((index) => offsetToLineColumn(code, index));
 }
 function getImportedFnNames(code, importedName) {
   const importPattern = /import\s*\{([^}]*)\}\s*from\s*["']@rangojs\/router(?:\/[^"']*)?["']/g;
@@ -782,6 +1033,17 @@ function getCalledIdentifierFromCall(callExpr) {
   }
   return null;
 }
+function unwrapSignatureWrappedCall(init, fnNameSet) {
+  if (init?.type !== "CallExpression") return init;
+  const directId = getCalledIdentifierFromCall(init);
+  if (directId && fnNameSet.has(directId)) return init;
+  const firstArg = init.arguments?.[0];
+  if (firstArg?.type === "CallExpression") {
+    const innerId = getCalledIdentifierFromCall(firstArg);
+    if (innerId && fnNameSet.has(innerId)) return firstArg;
+  }
+  return init;
+}
 function collectCreateExportBindingsFallback(code, fnNames) {
   const alternation = fnNames.map(escapeRegExp).join("|");
   const exportConstPattern = new RegExp(
@@ -841,7 +1103,7 @@ function collectCreateExportBindingsFallback(code, fnNames) {
 function collectCreateExportBindings(code, fnNames, program) {
   if (!program) {
     try {
-      program = parseAst(code, { jsx: true });
+      program = parseAst(code, { lang: "tsx" });
     } catch {
       return collectCreateExportBindingsFallback(code, fnNames);
     }
@@ -854,16 +1116,16 @@ function collectCreateExportBindings(code, fnNames, program) {
       return;
     }
     for (const decl of varDecl.declarations ?? []) {
-      const calledIdentifier = getCalledIdentifierFromCall(decl?.init);
-      if (decl?.id?.type !== "Identifier" || decl?.init?.type !== "CallExpression" || !calledIdentifier || !fnNameSet.has(calledIdentifier)) {
+      const callExpr = unwrapSignatureWrappedCall(decl?.init, fnNameSet);
+      const calledIdentifier = getCalledIdentifierFromCall(callExpr);
+      if (decl?.id?.type !== "Identifier" || callExpr?.type !== "CallExpression" || !calledIdentifier || !fnNameSet.has(calledIdentifier)) {
         continue;
       }
       const localName = decl.id.name;
       const exportNames = exportMap.get(localName) ?? [];
       if (exportNames.length === 0) continue;
-      const callStart = decl.init.start;
-      const callEnd = decl.init.end;
-      const calleeEnd = decl.init.callee.end;
+      const callEnd = callExpr.end;
+      const calleeEnd = callExpr.callee.end;
       let openParenPos = -1;
       for (let i = calleeEnd; i < callEnd; i++) {
         if (code[i] === "(") {
@@ -877,10 +1139,10 @@ function collectCreateExportBindings(code, fnNames, program) {
       bindings.push({
         localName,
         exportNames,
-        callExprStart: decl.init.start,
+        callExprStart: callExpr.start,
         callOpenParenPos: openParenPos,
         callCloseParenPos: closeParenPos,
-        argCount: decl.init.arguments?.length ?? 0,
+        argCount: callExpr.arguments?.length ?? 0,
         statementEnd
       });
     }
@@ -899,9 +1161,20 @@ function collectCreateExportBindings(code, fnNames, program) {
   }
   return bindings;
 }
-function buildUnsupportedShapeWarning(filePath, fnName) {
-  return [
-    `[rsc-router] Unsupported ${fnName} shape in "${filePath}".`,
+function buildUnsupportedShapeWarning(filePath, fnName, sites = []) {
+  const lines = [`[rango] Unsupported ${fnName} shape in "${filePath}".`];
+  if (sites.length === 1) {
+    const s = sites[0];
+    lines.push(
+      `The ${fnName}(...) call at ${filePath}:${s.line}:${s.column} has no stable $$id injected \u2014 it is not in a supported shape.`
+    );
+  } else if (sites.length > 1) {
+    lines.push(
+      `These ${fnName}(...) calls have no stable $$id injected \u2014 they are not in a supported shape:`
+    );
+    for (const s of sites) lines.push(`  - ${filePath}:${s.line}:${s.column}`);
+  }
+  lines.push(
     `Supported shapes are:`,
     `  - export const X = ${fnName}(...)`,
     `  - const X = ${fnName}(...); export { X }`,
@@ -909,7 +1182,8 @@ function buildUnsupportedShapeWarning(filePath, fnName) {
     `Potentially unsupported forms include:`,
     `  - export let/var X = ${fnName}(...)`,
     `  - inline ${fnName}(...) calls`
-  ].join("\n");
+  );
+  return lines.join("\n");
 }
 
 // src/vite/plugins/expose-ids/loader-transform.ts
@@ -922,11 +1196,13 @@ function generateClientLoaderStubs(bindings, code, filePath, isBuild) {
   if (!isExportOnlyFile(code, bindings)) return null;
   const lines = [];
   for (const binding of bindings) {
-    for (const name of binding.exportNames) {
-      const loaderId = isBuild ? hashId(filePath, name) : `${filePath}#${name}`;
-      lines.push(
-        `export const ${name} = { __brand: "loader", $$id: "${loaderId}" };`
-      );
+    const primaryName = binding.exportNames[0];
+    const loaderId = makeStubId(filePath, primaryName, isBuild);
+    lines.push(
+      `export const ${primaryName} = { __brand: "loader", $$id: "${loaderId}" };`
+    );
+    for (const alias of binding.exportNames.slice(1)) {
+      lines.push(`export const ${alias} = ${primaryName};`);
     }
   }
   return { code: lines.join("\n") + "\n" };
@@ -935,7 +1211,7 @@ function transformLoaders(bindings, s, filePath, isBuild) {
   let hasChanges = false;
   for (const binding of bindings) {
     const exportName = binding.exportNames[0];
-    const loaderId = isBuild ? hashId(filePath, exportName) : `${filePath}#${exportName}`;
+    const loaderId = makeStubId(filePath, exportName, isBuild);
     const paramInjection = binding.argCount === 1 ? `, undefined, "${loaderId}"` : `, "${loaderId}"`;
     s.appendLeft(binding.callCloseParenPos, paramInjection);
     const propInjection = `
@@ -947,23 +1223,13 @@ ${binding.localName}.$$id = "${loaderId}";`;
 }
 
 // src/vite/plugins/expose-ids/handler-transform.ts
-import MagicString2 from "magic-string";
-function analyzeCreateHandleArgs(code, startPos, endPos) {
-  const content = code.slice(startPos, endPos).trim();
-  return { hasArgs: content.length > 0 };
-}
-function transformHandles(bindings, s, code, filePath, isBuild) {
+function transformHandles(bindings, s, filePath, isBuild) {
   let hasChanges = false;
   for (const binding of bindings) {
     const exportName = binding.exportNames[0];
-    const args = analyzeCreateHandleArgs(
-      code,
-      binding.callOpenParenPos + 1,
-      binding.callCloseParenPos
-    );
-    const handleId = isBuild ? hashId(filePath, exportName) : `${filePath}#${exportName}`;
+    const handleId = makeStubId(filePath, exportName, isBuild);
     let paramInjection;
-    if (!args.hasArgs) {
+    if (binding.argCount === 0) {
       paramInjection = `undefined, "${handleId}"`;
     } else {
       paramInjection = `, "${handleId}"`;
@@ -980,7 +1246,7 @@ function transformLocationState(bindings, s, filePath, isBuild) {
   let hasChanges = false;
   for (const binding of bindings) {
     const exportName = binding.exportNames[0];
-    const stateKey = isBuild ? hashId(filePath, exportName) : `${filePath}#${exportName}`;
+    const stateKey = makeStubId(filePath, exportName, isBuild);
     const propInjection = `
 ${binding.localName}.__rsc_ls_key = "__rsc_ls_${stateKey}";`;
     s.appendRight(binding.statementEnd, propInjection);
@@ -992,7 +1258,7 @@ function generateWholeFileStubs(cfg, bindings, code, filePath, isBuild) {
   if (!isExportOnlyFile(code, bindings)) return null;
   const exportNames = bindings.flatMap((b) => b.exportNames);
   const stubs = exportNames.map((name) => {
-    const handlerId = isBuild ? hashId(filePath, name) : `${filePath}#${name}`;
+    const handlerId = makeStubId(filePath, name, isBuild);
     return `export const ${name} = { __brand: "${cfg.brand}", $$id: "${handlerId}" };`;
   });
   return { code: stubs.join("\n") + "\n", map: null };
@@ -1001,7 +1267,7 @@ function stubHandlerExprs(cfg, bindings, s, filePath, isBuild) {
   let hasChanges = false;
   for (const binding of bindings) {
     const exportName = binding.exportNames[0];
-    const handlerId = isBuild ? hashId(filePath, exportName) : `${filePath}#${exportName}`;
+    const handlerId = makeStubId(filePath, exportName, isBuild);
     s.overwrite(
       binding.callExprStart,
       binding.callCloseParenPos + 1,
@@ -1015,7 +1281,7 @@ function transformHandlerIds(cfg, bindings, s, filePath, isBuild) {
   let hasChanges = false;
   for (const binding of bindings) {
     const exportName = binding.exportNames[0];
-    const handlerId = isBuild ? hashId(filePath, exportName) : `${filePath}#${exportName}`;
+    const handlerId = makeStubId(filePath, exportName, isBuild);
     let paramInjection;
     if (binding.argCount === 0) {
       paramInjection = `undefined, "${handlerId}"`;
@@ -1034,40 +1300,72 @@ ${binding.localName}.$$id = "${handlerId}";`;
 }
 
 // src/vite/plugins/expose-ids/router-transform.ts
-import MagicString3 from "magic-string";
+import MagicString2 from "magic-string";
 import path3 from "node:path";
 import { createHash } from "node:crypto";
-var debug2 = createRangoDebugger("rango:transform");
-function transformRouter(code, filePath, routerFnNames, absolutePath) {
+var debug2 = createRangoDebugger(NS.transform);
+function skipLeadingTrivia(code, start, end) {
+  let i = start;
+  while (i < end) {
+    const skipped = skipStringOrComment(code, i);
+    if (skipped > i) {
+      i = skipped;
+      continue;
+    }
+    if (/\s/.test(code[i])) {
+      i++;
+      continue;
+    }
+    break;
+  }
+  return i;
+}
+function transformRouter(code, filePath, routerFnNames, absolutePath, warn) {
   const pat = new RegExp(
-    `\\b(?:${routerFnNames.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})\\s*(?:<[^>]*>)?\\s*\\(`,
+    `\\b(?:${routerFnNames.map(escapeRegExp).join("|")})\\b`,
     "g"
   );
   let match;
-  const s = new MagicString3(code);
+  const s = new MagicString2(code);
   let changed = false;
-  const basename3 = path3.basename(filePath).replace(/\.(tsx?|jsx?)$/, "");
-  const routeNamesImport = `./${basename3}.named-routes.gen.js`;
+  const unsupportedSites = [];
+  const basename2 = path3.basename(filePath).replace(/\.(tsx?|jsx?)$/, "");
+  const routeNamesImport = `./${basename2}.named-routes.gen.js`;
   const routeNamesVar = `__rsc_rn`;
+  const codeOffsets = new Set(codeMatchIndices(code, pat));
+  pat.lastIndex = 0;
   while ((match = pat.exec(code)) !== null) {
+    if (!codeOffsets.has(match.index)) continue;
     const callStart = match.index;
-    const parenPos = match.index + match[0].length - 1;
+    const calleeEnd = match.index + match[0].length;
+    const parenPos = findCallParenAfterGenerics(code, calleeEnd);
+    if (parenPos === -1) continue;
     const closeParen = findMatchingParen(code, parenPos + 1);
     const callArgs = code.slice(parenPos + 1, closeParen);
-    if (callArgs.includes("$$id")) continue;
+    if (callArgs.includes(`$$routeNames: ${routeNamesVar}`)) continue;
+    const sourceFilePath = absolutePath ?? filePath;
     const lineNumber = code.slice(0, callStart).split("\n").length;
     const hash = createHash("sha256").update(`${filePath}:${lineNumber}`).digest("hex").slice(0, 8);
-    changed = true;
-    const sourceFilePath = absolutePath ?? filePath;
     const injected = ` $$id: "${hash}", $$sourceFile: "${sourceFilePath}", $$routeNames: ${routeNamesVar},`;
-    const afterParen = callArgs.trimStart();
-    if (afterParen.startsWith("{")) {
-      const bracePos = code.indexOf("{", parenPos + 1);
-      s.appendRight(bracePos + 1, injected);
-    } else if (afterParen.startsWith(")")) {
+    const argsContentStart = skipLeadingTrivia(code, parenPos + 1, closeParen);
+    const firstArgChar = code[argsContentStart];
+    if (firstArgChar === "{") {
+      changed = true;
+      s.appendRight(argsContentStart + 1, injected);
+    } else if (argsContentStart >= closeParen - 1) {
+      changed = true;
       s.appendRight(parenPos + 1, `{${injected} }`);
+    } else {
+      const lastNl = code.lastIndexOf("\n", callStart - 1);
+      const column = callStart - (lastNl + 1) + 1;
+      unsupportedSites.push({ line: lineNumber, column });
     }
   }
+  if (unsupportedSites.length > 0 && warn) {
+    warn(
+      buildUnsupportedShapeWarning(filePath, "createRouter", unsupportedSites)
+    );
+  }
   if (!changed) return null;
   s.prepend(
     `import { NamedRoutes as ${routeNamesVar} } from "${routeNamesImport}";
@@ -1101,11 +1399,13 @@ function exposeRouterId() {
       try {
         const filePath = normalizePath(path3.relative(projectRoot, id));
         const routerFnNames = getImportedFnNames(code, "createRouter");
+        const warn = typeof this.warn === "function" ? (message) => this.warn(message) : void 0;
         return transformRouter(
           code,
           filePath,
           routerFnNames,
-          normalizePath(id)
+          normalizePath(id),
+          warn
         );
       } finally {
         counter?.record(id, performance.now() - start);
@@ -1115,7 +1415,7 @@ function exposeRouterId() {
 }
 
 // src/vite/plugins/expose-internal-ids.ts
-var debug3 = createRangoDebugger("rango:transform");
+var debug3 = createRangoDebugger(NS.transform);
 var VIRTUAL_LOADER_MANIFEST = "virtual:rsc-router/loader-manifest";
 var RESOLVED_VIRTUAL_LOADER_MANIFEST = "\0" + VIRTUAL_LOADER_MANIFEST;
 var VIRTUAL_HANDLER_PREFIX = "virtual:handler-extract:";
@@ -1201,6 +1501,7 @@ ${lazyImports.join(",\n")}
     // --------------- Loader pre-scan (build mode) ---------------
     async buildStart() {
       if (!isBuild) return;
+      if (this.environment && this.environment.name !== "rsc") return;
       const fs2 = await import("node:fs/promises");
       const SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", "dist", "build", "coverage"]);
       async function scanDir(dir) {
@@ -1307,7 +1608,7 @@ ${lazyImports.join(",\n")}
           }
           if (_cachedAst !== void 0 || _astParseFailed) return _cachedAst;
           try {
-            _cachedAst = parseAst2(code, { jsx: true });
+            _cachedAst = parseAst2(code, { lang: "tsx" });
           } catch {
             _astParseFailed = true;
           }
@@ -1330,13 +1631,16 @@ ${lazyImports.join(",\n")}
           const hasCode = cfg.fnName === "createLoader" ? hasLoaderCode : cfg.fnName === "createHandle" ? hasHandleCode : hasLocationStateCode;
           if (!hasCode) continue;
           const fnNames = getFnNames(cfg.fnName);
-          const totalCalls = countCreateCallsForNames(code, fnNames);
-          const supportedBindings = getBindings(code, fnNames).length;
-          if (totalCalls <= supportedBindings) continue;
+          const sites = findUnsupportedCreateCallSites(
+            code,
+            fnNames,
+            getBindings(code, fnNames)
+          );
+          if (sites.length === 0) continue;
           const warnKey = `${id}::${cfg.fnName}`;
           if (unsupportedShapeWarnings.has(warnKey)) continue;
           unsupportedShapeWarnings.add(warnKey);
-          this.warn(buildUnsupportedShapeWarning(filePath, cfg.fnName));
+          this.warn(buildUnsupportedShapeWarning(filePath, cfg.fnName, sites));
         }
         if (hasLoaderCode && isRscEnv) {
           const fnNames = getFnNames("createLoader");
@@ -1373,15 +1677,6 @@ ${lazyImports.join(",\n")}
           );
           if (wholeFile) return wholeFile;
         }
-        if (hasPrerenderHandlerCode && isRscEnv && isBuild) {
-          const fnNames = getFnNames(PRERENDER_CONFIG.fnName);
-          const exportNames = getBindings(code, fnNames).map(
-            (b) => b.exportNames[0]
-          );
-          if (exportNames.length > 0) {
-            prerenderHandlerModules.set(id, exportNames);
-          }
-        }
         let changed = false;
         const handlerConfigs = [
           hasStaticHandlerCode && STATIC_CONFIG,
@@ -1394,7 +1689,7 @@ ${lazyImports.join(",\n")}
           const totalCalls = countCreateCallsForNames(code, fnNames);
           const supportedBindings = getBindings(code, fnNames).length;
           if (totalCalls > supportedBindings) {
-            const iterS = new MagicString4(code);
+            const iterS = new MagicString3(code);
             const result = transformInlineHandlers(
               cfg.fnName,
               VIRTUAL_HANDLER_PREFIX,
@@ -1559,16 +1854,24 @@ ${lazyImports.join(",\n")}
             return { code: lines.join("\n") + "\n", map: null };
           }
         }
-        if (hasStaticHandlerCode && isRscEnv && isBuild) {
-          const fnNames = getFnNames(STATIC_CONFIG.fnName);
-          const exportNames = getBindings(code, fnNames).map(
-            (b) => b.exportNames[0]
-          );
-          if (exportNames.length > 0) {
-            staticHandlerModules.set(id, exportNames);
+        if (isRscEnv && isBuild) {
+          const trackTypes = [
+            [
+              hasPrerenderHandlerCode,
+              PRERENDER_CONFIG,
+              prerenderHandlerModules
+            ],
+            [hasStaticHandlerCode, STATIC_CONFIG, staticHandlerModules]
+          ];
+          for (const [has2, cfg, trackMap] of trackTypes) {
+            if (!has2) continue;
+            const exportNames = getBindings(code, getFnNames(cfg.fnName)).map(
+              (b) => b.exportNames[0]
+            );
+            if (exportNames.length > 0) trackMap.set(id, exportNames);
           }
         }
-        const s = new MagicString4(code);
+        const s = new MagicString3(code);
         if (hasLoaderCode) {
           const fnNames = getFnNames("createLoader");
           changed = transformLoaders(
@@ -1583,7 +1886,6 @@ ${lazyImports.join(",\n")}
           changed = transformHandles(
             getBindings(code, fnNames),
             s,
-            code,
             filePath,
             isBuild
           ) || changed;
@@ -1597,41 +1899,13 @@ ${lazyImports.join(",\n")}
             isBuild
           ) || changed;
         }
-        if (hasPrerenderHandlerCode) {
-          const fnNames = getFnNames(PRERENDER_CONFIG.fnName);
-          const bindings = getBindings(code, fnNames);
-          if (isRscEnv) {
-            changed = transformHandlerIds(
-              PRERENDER_CONFIG,
-              bindings,
-              s,
-              filePath,
-              isBuild
-            ) || changed;
-          } else {
-            changed = stubHandlerExprs(
-              PRERENDER_CONFIG,
-              bindings,
-              s,
-              filePath,
-              isBuild
-            ) || changed;
-          }
-        }
-        if (hasStaticHandlerCode) {
-          const fnNames = getFnNames(STATIC_CONFIG.fnName);
-          const bindings = getBindings(code, fnNames);
-          if (isRscEnv) {
-            changed = transformHandlerIds(
-              STATIC_CONFIG,
-              bindings,
-              s,
-              filePath,
-              isBuild
-            ) || changed;
-          } else {
-            changed = stubHandlerExprs(STATIC_CONFIG, bindings, s, filePath, isBuild) || changed;
-          }
+        const finalHandlerConfigs = [
+          hasPrerenderHandlerCode && PRERENDER_CONFIG,
+          hasStaticHandlerCode && STATIC_CONFIG
+        ].filter((c) => !!c);
+        for (const cfg of finalHandlerConfigs) {
+          const bindings = getBindings(code, getFnNames(cfg.fnName));
+          changed = (isRscEnv ? transformHandlerIds(cfg, bindings, s, filePath, isBuild) : stubHandlerExprs(cfg, bindings, s, filePath, isBuild)) || changed;
         }
         if (!changed) return;
         return {
@@ -1647,10 +1921,11 @@ ${lazyImports.join(",\n")}
 
 // src/vite/plugins/use-cache-transform.ts
 import path5 from "node:path";
-import MagicString5 from "magic-string";
-var debug4 = createRangoDebugger("rango:transform");
+import MagicString4 from "magic-string";
+var debug4 = createRangoDebugger(NS.transform);
 var CACHE_RUNTIME_IMPORT = "@rangojs/router/cache-runtime";
 var LAYOUT_TEMPLATE_PATTERN = /\/(layout|template)\.(tsx?|jsx?)$/;
+var USE_CACHE_DIRECTIVE_RE = /^use cache(:\s*[\w-]+)?$/;
 function useCacheTransform() {
   let projectRoot = "";
   let isBuild = false;
@@ -1687,8 +1962,8 @@ function useCacheTransform() {
         } = rscTransforms;
         let ast;
         try {
-          const { parseAst: parseAst4 } = await import("vite");
-          ast = parseAst4(code);
+          const { parseAst: parseAst5 } = await import("vite");
+          ast = parseAst5(code, { lang: "tsx" });
         } catch {
           return;
         }
@@ -1722,7 +1997,7 @@ function useCacheTransform() {
   };
 }
 function transformFileLevelUseCache(code, ast, filePath, sourceId, isBuild, isLayoutOrTemplate, transformWrapExport) {
-  const nonFunctionExports = [];
+  const unconfirmedExports = [];
   const { exportNames, output } = transformWrapExport(code, ast, {
     runtime: (value, name) => {
       const funcId = isBuild ? hashId(filePath, name) : `${filePath}#${name}`;
@@ -1731,20 +2006,21 @@ function transformFileLevelUseCache(code, ast, filePath, sourceId, isBuild, isLa
     rejectNonAsyncFunction: false,
     filter: (name, meta) => {
       if (name === "default" && isLayoutOrTemplate) return false;
-      if (meta.isFunction === false) {
-        nonFunctionExports.push(name);
+      if (meta.isFunction !== true) {
+        unconfirmedExports.push(name);
         return false;
       }
       return true;
     }
   });
-  if (nonFunctionExports.length > 0) {
+  if (unconfirmedExports.length > 0) {
+    const plural = unconfirmedExports.length > 1;
     throw new Error(
-      `[rango:use-cache] File-level "use cache" in ${sourceId} cannot wrap non-function export${nonFunctionExports.length > 1 ? "s" : ""}: ${nonFunctionExports.map((n) => `"${n}"`).join(", ")}. Only function exports can be cached. Either remove "use cache" from the file level and add it inside individual functions, or move the non-function exports to a separate module.`
+      `[rango:use-cache] File-level "use cache" in ${sourceId} only wraps exports that are statically-confirmed functions. ${plural ? "These exports are" : "This export is"} not: ${unconfirmedExports.map((n) => `"${n}"`).join(", ")}. Declare them directly (export async function foo() {} or export const foo = async () => {}). A factory or otherwise statically-indeterminate initializer (export const foo = makeCached(fn)) is rejected even if it returns a function at runtime -- rewrite it as a direct async function, or move non-function exports to a separate module.`
     );
   }
   if (exportNames.length === 0) {
-    const s = new MagicString5(code);
+    const s = new MagicString4(code);
     const directive2 = findFileLevelDirective(ast);
     if (directive2) {
       s.overwrite(
@@ -1779,7 +2055,7 @@ function transformFileLevelUseCache(code, ast, filePath, sourceId, isBuild, isLa
 function transformFunctionLevelUseCache(code, ast, filePath, sourceId, isBuild, transformHoistInlineDirective) {
   try {
     const { output, names } = transformHoistInlineDirective(code, ast, {
-      directive: /^use cache(:\s*[\w-]+)?$/,
+      directive: USE_CACHE_DIRECTIVE_RE,
       runtime: (value, name, meta) => {
         const funcId = isBuild ? hashId(filePath, name) : `${filePath}#${name}`;
         const profileMatch = meta.directiveMatch[1];
@@ -1809,14 +2085,13 @@ function findFileLevelDirective(ast) {
   }
   return null;
 }
-var VALID_DIRECTIVE_RE = /^use cache(:\s*[\w-]+)?$/;
 var NEAR_MISS_RE = /^use cache:\s*.+$/;
 function warnOnNearMissDirectives(ast, fileId, warn) {
   const visit = (node) => {
     if (!node || typeof node !== "object") return;
     if (node.type === "ExpressionStatement" && node.expression?.type === "Literal" && typeof node.expression.value === "string") {
       const value = node.expression.value;
-      if (value.startsWith("use cache") && NEAR_MISS_RE.test(value) && !VALID_DIRECTIVE_RE.test(value)) {
+      if (value.startsWith("use cache") && NEAR_MISS_RE.test(value) && !USE_CACHE_DIRECTIVE_RE.test(value)) {
         const profilePart = value.slice("use cache:".length).trim();
         warn(
           `[rango:use-cache] "${value}" in ${fileId} has an invalid profile name "${profilePart}". Profile names must match [a-zA-Z0-9_-]+. This directive will be ignored.`
@@ -1840,7 +2115,7 @@ function warnOnNearMissDirectives(ast, fileId, warn) {
 }
 
 // src/vite/plugins/client-ref-dedup.ts
-var debug5 = createRangoDebugger("rango:transform");
+var debug5 = createRangoDebugger(NS.transform);
 var CLIENT_IN_SERVER_PROXY_PREFIX = "virtual:vite-rsc/client-in-server-package-proxy/";
 function extractPackageName(absolutePath) {
   const marker = "/node_modules/";
@@ -1857,7 +2132,6 @@ function extractPackageName(absolutePath) {
 }
 function clientRefDedup() {
   let clientExclude = [];
-  let hits = 0;
   const dedupedPackages = /* @__PURE__ */ new Set();
   return {
     name: "@rangojs/router:client-ref-dedup",
@@ -1868,10 +2142,9 @@ function clientRefDedup() {
       clientExclude = clientEnv?.optimizeDeps?.exclude ?? config.optimizeDeps?.exclude ?? [];
     },
     buildEnd() {
-      if (debug5 && hits > 0) {
+      if (debug5 && dedupedPackages.size > 0) {
         debug5(
-          "client-ref-dedup: %d redirects across %d packages (%s)",
-          hits,
+          "client-ref-dedup: redirected %d package(s) (%s)",
           dedupedPackages.size,
           [...dedupedPackages].join(",")
         );
@@ -1881,14 +2154,10 @@ function clientRefDedup() {
       if (this.environment?.name !== "client") return;
       if (!importer?.includes(CLIENT_IN_SERVER_PROXY_PREFIX)) return;
       if (!source.includes("/node_modules/")) return;
-      if (!importer) return;
       const packageName = extractPackageName(source);
       if (!packageName) return;
       if (clientExclude.includes(packageName)) return;
-      if (debug5) {
-        hits++;
-        dedupedPackages.add(packageName);
-      }
+      if (debug5) dedupedPackages.add(packageName);
       return `\0rango:dedup/${packageName}`;
     },
     load(id) {
@@ -1915,7 +2184,7 @@ import {
 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";
+import { initBrowserApp, Rango } from "@rangojs/router/browser";
 
 async function initializeApp() {
   const deps = {
@@ -1926,11 +2195,16 @@ async function initializeApp() {
     createTemporaryReferenceSet,
   };
 
-  await initBrowserApp({ rscStream, deps });
+  // initBrowserApp resolves the initial payload and returns the browser app
+  // context, including strictMode (default true) from createRouter. StrictMode
+  // is the default; createRouter({ strictMode: false }) ships the opt-out in the
+  // payload metadata. StrictMode emits no DOM, so toggling never changes markup.
+  const { strictMode } = await initBrowserApp({ rscStream, deps });
 
+  const app = createElement(Rango);
   hydrateRoot(
     document,
-    createElement(StrictMode, null, createElement(RSCRouter))
+    strictMode === false ? app : createElement(StrictMode, null, app)
   );
 }
 
@@ -1950,7 +2224,14 @@ export const renderHTML = createSSRHandler({
     import.meta.viteRsc.loadBootstrapScriptContent("index"),
 });
 `.trim();
+var RSC_ENTRY_BOOTSTRAP_IMPORTS = [
+  "virtual:rsc-router/routes-manifest",
+  "virtual:rsc-router/loader-manifest"
+];
 function getVirtualEntryRSC(routerPath) {
+  const bootstrapImports = RSC_ENTRY_BOOTSTRAP_IMPORTS.map(
+    (id) => `import "${id}";`
+  ).join("\n");
   return `
 import {
   renderToReadableStream,
@@ -1964,15 +2245,9 @@ 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";
+// Startup bootstrap imports (routes + loader manifests). See
+// RSC_ENTRY_BOOTSTRAP_IMPORTS \u2014 the same list the custom-entry injector uses.
+${bootstrapImports}
 
 // Lazily create the handler on first request so that ESM live bindings
 // have resolved by the time we read \`router\`. During HMR the module may
@@ -1983,6 +2258,11 @@ export default function handler(request, env) {
     _handler = createRSCHandler({
       router,
       version: VERSION,
+      // Forward the router's CSP nonce provider. createRSCHandler reads the
+      // provider only from options.nonce; without this, createRouter({ nonce })
+      // is silently dropped on the Node preset (the Cloudflare path wires it via
+      // router.fetch). router.nonce is undefined when unconfigured, a safe no-op.
+      nonce: router.nonce,
       deps: {
         renderToReadableStream,
         decodeReply,
@@ -2017,7 +2297,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.9eb4192e",
+  version: "0.0.0-experimental.a014d2b7",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -2127,6 +2407,11 @@ var package_default = {
       "react-server": "./src/cache/cache-runtime.ts",
       default: "./src/cache/cache-runtime.ts"
     },
+    "./cloudflare": {
+      types: "./src/cloudflare/index.ts",
+      "react-server": "./src/cloudflare/index.ts",
+      default: "./src/cloudflare/index.ts"
+    },
     "./theme": {
       types: "./src/theme/index.ts",
       default: "./src/theme/index.ts"
@@ -2143,6 +2428,31 @@ var package_default = {
     "./host/testing": {
       types: "./src/host/testing.ts",
       default: "./src/host/testing.ts"
+    },
+    "./testing": {
+      types: "./src/testing/index.ts",
+      default: "./src/testing/index.ts"
+    },
+    "./testing/vitest": {
+      types: "./src/testing/vitest.ts",
+      default: "./dist/testing/vitest.js"
+    },
+    "./testing/dom": {
+      types: "./src/testing/dom.entry.ts",
+      default: "./src/testing/dom.entry.ts"
+    },
+    "./testing/e2e": {
+      types: "./src/testing/e2e/index.ts",
+      default: "./src/testing/e2e/index.ts"
+    },
+    "./testing/flight": {
+      types: "./src/testing/flight.entry.ts",
+      "react-server": "./src/testing/flight.entry.ts",
+      default: "./src/testing/flight.entry.ts"
+    },
+    "./testing/flight-matchers": {
+      types: "./src/testing/flight-matchers.ts",
+      default: "./src/testing/flight-matchers.ts"
     }
   },
   publishConfig: {
@@ -2150,48 +2460,70 @@ var package_default = {
     tag: "experimental"
   },
   scripts: {
-    build: "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && 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' && chmod +x dist/bin/rango.js",
+    build: "pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
     prepublishOnly: "pnpm build",
-    typecheck: "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit",
+    typecheck: "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
     test: "playwright test",
     "test:ui": "playwright test --ui",
+    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-routes --project=hmr-basename --project=hmr-prerender --no-deps --workers=1",
     "test:unit": "vitest run",
-    "test:unit:watch": "vitest"
+    "test:unit:watch": "vitest",
+    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
   },
   dependencies: {
-    "@vitejs/plugin-rsc": "^0.5.23",
+    "@types/debug": "^4.1.12",
+    "@vitejs/plugin-rsc": "^0.5.27",
     debug: "^4.4.1",
     "magic-string": "^0.30.17",
-    picomatch: "^4.0.3",
-    "rsc-html-stream": "^0.0.7"
+    picomatch: "^4.0.4",
+    "rsc-html-stream": "^0.0.7",
+    tinyexec: "^0.3.2"
   },
   devDependencies: {
     "@playwright/test": "^1.49.1",
-    "@types/debug": "^4.1.12",
+    "@shared/e2e": "workspace:*",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@types/node": "^24.10.1",
     "@types/react": "catalog:",
     "@types/react-dom": "catalog:",
-    esbuild: "^0.27.0",
+    esbuild: "^0.28.1",
+    "happy-dom": "^20.10.1",
     jiti: "^2.6.1",
     react: "catalog:",
     "react-dom": "catalog:",
-    tinyexec: "^0.3.2",
     typescript: "^5.3.0",
-    vitest: "^4.0.0"
+    vitest: "^4.1.9"
   },
   peerDependencies: {
-    "@cloudflare/vite-plugin": "^1.25.0",
-    "@vitejs/plugin-rsc": "^0.5.23",
-    react: "^18.0.0 || ^19.0.0",
-    vite: "^7.3.0"
+    "@cloudflare/vite-plugin": "^1.42.1",
+    "@playwright/test": "^1.49.1",
+    "@testing-library/react": ">=16",
+    "@vitejs/plugin-rsc": "^0.5.27",
+    react: ">=19.2.6 <20",
+    "react-dom": ">=19.2.6 <20",
+    vite: "^8.0.16",
+    vitest: ">=3"
   },
   peerDependenciesMeta: {
     "@cloudflare/vite-plugin": {
       optional: true
     },
+    "@playwright/test": {
+      optional: true
+    },
+    "@testing-library/react": {
+      optional: true
+    },
     vite: {
       optional: true
+    },
+    vitest: {
+      optional: true
     }
+  },
+  engines: {
+    node: "^20.19.0 || >=22.12.0"
   }
 };
 
@@ -2265,10 +2597,10 @@ function extractParamsFromPattern(pattern) {
 function formatRouteEntry(key, pattern, _params, search) {
   const hasSearch = search && Object.keys(search).length > 0;
   if (!hasSearch) {
-    return `  ${key}: "${pattern}",`;
+    return `  ${key}: ${JSON.stringify(pattern)},`;
   }
-  const searchBody = Object.entries(search).map(([k, v]) => `${k}: "${v}"`).join(", ");
-  return `  ${key}: { path: "${pattern}", search: { ${searchBody} } },`;
+  const searchBody = Object.entries(search).map(([k, v]) => `${k}: ${JSON.stringify(v)}`).join(", ");
+  return `  ${key}: { path: ${JSON.stringify(pattern)}, search: { ${searchBody} } },`;
 }
 
 // src/build/route-types/ast-route-extraction.ts
@@ -2294,8 +2626,8 @@ function extractObjectStringProperties(node) {
 }
 
 // src/build/route-types/ast-route-extraction.ts
-function extractRoutesFromSource(code) {
-  const sourceFile = ts2.createSourceFile(
+function extractRoutesFromSource(code, sourceFileArg) {
+  const sourceFile = sourceFileArg ?? ts2.createSourceFile(
     "input.tsx",
     code,
     ts2.ScriptTarget.Latest,
@@ -2375,16 +2707,44 @@ export const NamedRoutes = {
 ${objectBody}
 } as const;
 
+// Aliased so the augmentation below does not pay a homomorphic mapped-type
+// instantiation per route; \`as const\` already makes the members readonly.
+type NamedRoutesShape = typeof NamedRoutes;
+
 declare global {
-  namespace RSCRouter {
-    interface GeneratedRouteMap extends Readonly<typeof NamedRoutes> {}
+  namespace Rango {
+    interface GeneratedRouteMap extends NamedRoutesShape {}
   }
 }
 `;
 }
 
 // src/build/route-types/scan-filter.ts
+import { join, relative } from "node:path";
 import picomatch from "picomatch";
+var DEFAULT_EXCLUDE_PATTERNS = [
+  "**/__tests__/**",
+  "**/__mocks__/**",
+  "**/dist/**",
+  "**/coverage/**",
+  "**/*.test.{ts,tsx,js,jsx}",
+  "**/*.spec.{ts,tsx,js,jsx}"
+];
+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;
+  };
+}
 
 // src/build/route-types/per-module-writer.ts
 import ts4 from "typescript";
@@ -2393,6 +2753,33 @@ import ts4 from "typescript";
 import { readFileSync, existsSync as existsSync2 } from "node:fs";
 import { dirname, resolve as resolve2 } from "node:path";
 import ts3 from "typescript";
+function createScanMemo() {
+  return { files: /* @__PURE__ */ new Map(), blockSourceFiles: /* @__PURE__ */ new Map() };
+}
+function parseBlock(memo, block) {
+  if (memo) {
+    const cached = memo.blockSourceFiles.get(block);
+    if (cached) return cached;
+  }
+  const sf = ts3.createSourceFile(
+    "input.tsx",
+    block,
+    ts3.ScriptTarget.Latest,
+    true,
+    ts3.ScriptKind.TSX
+  );
+  if (memo) memo.blockSourceFiles.set(block, sf);
+  return sf;
+}
+function readSourceMemoized(memo, realPath) {
+  if (memo) {
+    const cached = memo.files.get(realPath);
+    if (cached !== void 0) return cached;
+  }
+  const source = readFileSync(realPath, "utf-8");
+  if (memo) memo.files.set(realPath, source);
+  return source;
+}
 function extractNamePrefixFromInclude(node) {
   if (node.arguments.length >= 3) {
     const thirdArg = node.arguments[2];
@@ -2408,8 +2795,8 @@ function extractNamePrefixFromInclude(node) {
   }
   return null;
 }
-function extractIncludesWithDiagnostics(code) {
-  const sourceFile = ts3.createSourceFile(
+function extractIncludesWithDiagnostics(code, sourceFileArg) {
+  const sourceFile = sourceFileArg ?? ts3.createSourceFile(
     "input.tsx",
     code,
     ts3.ScriptTarget.Latest,
@@ -2463,7 +2850,7 @@ function extractIncludesWithDiagnostics(code) {
   return { resolved, unresolvable };
 }
 function resolveImportedVariable(code, localName) {
-  const importRegex = /import\s*\{([^}]+)\}\s*from\s*["']([^"']+)["']/g;
+  const importRegex = /import\s*(?:[\w$]+\s*,\s*)?\{([^}]+)\}\s*from\s*["']([^"']+)["']/g;
   let match;
   while ((match = importRegex.exec(code)) !== null) {
     const imports = match[1];
@@ -2500,8 +2887,8 @@ function resolveImportPath(importSpec, fromFile) {
   }
   return null;
 }
-function extractUrlsBlockForVariable(code, varName) {
-  const sourceFile = ts3.createSourceFile(
+function extractUrlsBlockForVariable(code, varName, sourceFileArg) {
+  const sourceFile = sourceFileArg ?? ts3.createSourceFile(
     "input.tsx",
     code,
     ts3.ScriptTarget.Latest,
@@ -2523,16 +2910,20 @@ function extractUrlsBlockForVariable(code, varName) {
   visit(sourceFile);
   return result;
 }
-function buildRouteMapFromBlock(block, fullSource, filePath, visited, searchSchemasOut, diagnosticsOut) {
+function buildRouteMapFromBlock(block, fullSource, filePath, visited, searchSchemasOut, diagnosticsOut, memo) {
   const routeMap = {};
-  const localRoutes = extractRoutesFromSource(block);
+  const blockSourceFile = parseBlock(memo, block);
+  const localRoutes = extractRoutesFromSource(block, blockSourceFile);
   for (const { name, pattern, search } of localRoutes) {
     routeMap[name] = pattern;
     if (search && searchSchemasOut) {
       searchSchemasOut[name] = search;
     }
   }
-  const { resolved: includes, unresolvable } = extractIncludesWithDiagnostics(block);
+  const { resolved: includes, unresolvable } = extractIncludesWithDiagnostics(
+    block,
+    blockSourceFile
+  );
   if (diagnosticsOut) {
     for (const entry of unresolvable) {
       diagnosticsOut.push({ ...entry, sourceFile: filePath });
@@ -2559,12 +2950,15 @@ function buildRouteMapFromBlock(block, fullSource, filePath, visited, searchSche
         targetFile,
         imported.exportedName,
         visited,
-        diagnosticsOut
+        diagnosticsOut,
+        void 0,
+        memo
       );
     } else {
       const sameFileBlock = extractUrlsBlockForVariable(
         fullSource,
-        variableName
+        variableName,
+        parseBlock(memo, fullSource)
       );
       if (!sameFileBlock) {
         if (diagnosticsOut) {
@@ -2582,7 +2976,9 @@ function buildRouteMapFromBlock(block, fullSource, filePath, visited, searchSche
         filePath,
         variableName,
         visited,
-        diagnosticsOut
+        diagnosticsOut,
+        void 0,
+        memo
       );
     }
     if (namePrefix === null) {
@@ -2606,18 +3002,19 @@ function buildRouteMapFromBlock(block, fullSource, filePath, visited, searchSche
   }
   return routeMap;
 }
-function buildCombinedRouteMapWithSearch(filePath, variableName, visited, diagnosticsOut, inlineBlock) {
+function buildCombinedRouteMapWithSearch(filePath, variableName, visited, diagnosticsOut, inlineBlock, memo) {
   visited = visited ?? /* @__PURE__ */ new Set();
+  memo = memo ?? createScanMemo();
   const realPath = resolve2(filePath);
   const key = variableName ? `${realPath}:${variableName}` : realPath;
   if (visited.has(key)) {
-    console.warn(`[rsc-router] Circular include detected, skipping: ${key}`);
+    console.warn(`[rango] Circular include detected, skipping: ${key}`);
     return { routes: {}, searchSchemas: {} };
   }
   visited.add(key);
   let source;
   try {
-    source = readFileSync(realPath, "utf-8");
+    source = readSourceMemoized(memo, realPath);
   } catch {
     return { routes: {}, searchSchemas: {} };
   }
@@ -2625,7 +3022,11 @@ function buildCombinedRouteMapWithSearch(filePath, variableName, visited, diagno
   if (inlineBlock) {
     block = inlineBlock;
   } else if (variableName) {
-    const extracted = extractUrlsBlockForVariable(source, variableName);
+    const extracted = extractUrlsBlockForVariable(
+      source,
+      variableName,
+      parseBlock(memo, source)
+    );
     if (!extracted) return { routes: {}, searchSchemas: {} };
     block = extracted;
   } else {
@@ -2638,7 +3039,8 @@ function buildCombinedRouteMapWithSearch(filePath, variableName, visited, diagno
     realPath,
     visited,
     searchSchemas,
-    diagnosticsOut
+    diagnosticsOut,
+    memo
   );
   visited.delete(key);
   return { routes, searchSchemas };
@@ -2653,7 +3055,7 @@ import {
   readdirSync
 } from "node:fs";
 import {
-  join,
+  join as join2,
   dirname as dirname2,
   resolve as resolve3,
   sep,
@@ -2672,6 +3074,7 @@ function countPublicRouteEntries(source) {
   return count;
 }
 var ROUTER_CALL_PATTERN = /\bcreateRouter\s*[<(]/;
+var ROUTER_CALL_PATTERN_G = /\bcreateRouter\s*[<(]/g;
 function isRoutableSourceFile(name) {
   return (name.endsWith(".ts") || name.endsWith(".tsx") || name.endsWith(".js") || name.endsWith(".jsx")) && !name.includes(".gen.") && !name.includes(".test.") && !name.includes(".spec.");
 }
@@ -2681,14 +3084,14 @@ function findRouterFilesRecursive(dir, filter, results) {
     entries = readdirSync(dir, { withFileTypes: true });
   } catch (err) {
     console.warn(
-      `[rsc-router] Failed to scan directory ${dir}: ${err.message}`
+      `[rango] Failed to scan directory ${dir}: ${err.message}`
     );
     return;
   }
   const childDirs = [];
   const routerFilesInDir = [];
   for (const entry of entries) {
-    const fullPath = join(dir, entry.name);
+    const fullPath = join2(dir, entry.name);
     if (entry.isDirectory()) {
       if (entry.name === "node_modules" || entry.name === "dist" || entry.name === "coverage" || entry.name === "__tests__" || entry.name === "__mocks__" || entry.name.startsWith("."))
         continue;
@@ -2699,7 +3102,7 @@ function findRouterFilesRecursive(dir, filter, results) {
     if (filter && !filter(fullPath)) continue;
     try {
       const source = readFileSync2(fullPath, "utf-8");
-      if (ROUTER_CALL_PATTERN.test(source)) {
+      if (ROUTER_CALL_PATTERN.test(source) && firstCodeMatchIndex(source, ROUTER_CALL_PATTERN_G) >= 0) {
         routerFilesInDir.push(fullPath);
       }
     } catch {
@@ -2737,7 +3140,7 @@ function findNestedRouterConflict(routerFiles) {
   }
   return null;
 }
-function formatNestedRouterConflictError(conflict, prefix = "[rsc-router]") {
+function formatNestedRouterConflictError(conflict, prefix = "[rango]") {
   return `${prefix} Nested router roots are not supported.
 Router root: ${conflict.ancestor}
 Nested router: ${conflict.nested}
@@ -2833,19 +3236,38 @@ function extractBasenameFromRouter(code) {
   visit(sourceFile);
   return result;
 }
-function applyBasenameToRoutes(result, basename3) {
+function applyBasenameToRoutes(result, basename2) {
   const prefixed = {};
   for (const [name, pattern] of Object.entries(result.routes)) {
     if (pattern === "/") {
-      prefixed[name] = basename3;
-    } else if (basename3.endsWith("/") && pattern.startsWith("/")) {
-      prefixed[name] = basename3 + pattern.slice(1);
+      prefixed[name] = basename2;
+    } else if (basename2.endsWith("/") && pattern.startsWith("/")) {
+      prefixed[name] = basename2 + pattern.slice(1);
     } else {
-      prefixed[name] = basename3 + pattern;
+      prefixed[name] = basename2 + pattern;
     }
   }
   return { routes: prefixed, searchSchemas: result.searchSchemas };
 }
+function genFileTsPath(sourceFile) {
+  const base = pathBasename(sourceFile).replace(/\.(tsx?|jsx?)$/, "");
+  return join2(dirname2(sourceFile), `${base}.named-routes.gen.ts`);
+}
+function resolveSearchSchemas(publicRouteNames, runtimeSchemas, sourceFile) {
+  if (runtimeSchemas && Object.keys(runtimeSchemas).length > 0) {
+    return runtimeSchemas;
+  }
+  const staticParsed = buildCombinedRouteMapForRouterFile(sourceFile);
+  if (Object.keys(staticParsed.searchSchemas).length === 0) {
+    return runtimeSchemas;
+  }
+  const filtered = {};
+  for (const name of publicRouteNames) {
+    const schema = staticParsed.searchSchemas[name];
+    if (schema) filtered[name] = schema;
+  }
+  return Object.keys(filtered).length > 0 ? filtered : runtimeSchemas;
+}
 function buildCombinedRouteMapForRouterFile(routerFilePath) {
   let routerSource;
   try {
@@ -2858,7 +3280,7 @@ function buildCombinedRouteMapForRouterFile(routerFilePath) {
     return { routes: {}, searchSchemas: {} };
   }
   const rawBasename = extractBasenameFromRouter(routerSource);
-  const basename3 = rawBasename ? ("/" + rawBasename.replace(/^\/+|\/+$/g, "")).replace(/^\/$/, "") : void 0;
+  const basename2 = rawBasename ? ("/" + rawBasename.replace(/^\/+|\/+$/g, "")).replace(/^\/$/, "") : void 0;
   let result;
   if (extraction.kind === "inline") {
     result = buildCombinedRouteMapWithSearch(
@@ -2883,8 +3305,8 @@ function buildCombinedRouteMapForRouterFile(routerFilePath) {
       result = buildCombinedRouteMapWithSearch(routerFilePath, extraction.name);
     }
   }
-  if (basename3) {
-    result = applyBasenameToRoutes(result, basename3);
+  if (basename2) {
+    result = applyBasenameToRoutes(result, basename2);
   }
   return result;
 }
@@ -2895,11 +3317,11 @@ function findRouterFiles(root, filter) {
 }
 function writeCombinedRouteTypes(root, knownRouterFiles, opts) {
   try {
-    const oldCombinedPath = join(root, "src", "named-routes.gen.ts");
+    const oldCombinedPath = join2(root, "src", "named-routes.gen.ts");
     if (existsSync3(oldCombinedPath)) {
       unlinkSync(oldCombinedPath);
       console.log(
-        `[rsc-router] Removed stale combined route types: ${oldCombinedPath}`
+        `[rango] Removed stale combined route types: ${oldCombinedPath}`
       );
     }
   } catch {
@@ -2921,18 +3343,12 @@ function writeCombinedRouteTypes(root, knownRouterFiles, opts) {
       }
       if (!extractUrlsFromRouter(routerSource)) continue;
     }
-    const routerBasename = pathBasename(routerFilePath).replace(
-      /\.(tsx?|jsx?)$/,
-      ""
-    );
-    const outPath = join(
-      dirname2(routerFilePath),
-      `${routerBasename}.named-routes.gen.ts`
-    );
+    const outPath = genFileTsPath(routerFilePath);
     const existing = existsSync3(outPath) ? readFileSync2(outPath, "utf-8") : null;
     if (Object.keys(result.routes).length === 0) {
       if (!existing) {
         const emptySource = generateRouteTypesSource({});
+        opts?.onWrite?.(outPath, emptySource);
         writeFileSync(outPath, emptySource);
       }
       continue;
@@ -2952,16 +3368,38 @@ function writeCombinedRouteTypes(root, knownRouterFiles, opts) {
           continue;
         }
       }
+      opts?.onWrite?.(outPath, source);
       writeFileSync(outPath, source);
       console.log(
-        `[rsc-router] Generated route types (${Object.keys(result.routes).length} routes) -> ${outPath}`
+        `[rango] Generated route types (${Object.keys(result.routes).length} routes) -> ${outPath}`
       );
     }
   }
 }
 
 // src/vite/plugins/version-plugin.ts
+import { parseAst as parseAst4 } from "vite";
+
+// src/vite/utils/directive-prologue.ts
 import { parseAst as parseAst3 } from "vite";
+function hasUseClientDirective(source) {
+  let program;
+  try {
+    program = parseAst3(source, { lang: "tsx" });
+  } catch {
+    return false;
+  }
+  for (const node of program.body ?? []) {
+    if (node?.type === "ExpressionStatement" && node.expression?.type === "Literal" && typeof node.expression.value === "string") {
+      if (node.expression.value === "use client") return true;
+      continue;
+    }
+    break;
+  }
+  return false;
+}
+
+// src/vite/plugins/version-plugin.ts
 function isCodeModule(id) {
   return /\.(tsx?|jsx?)($|\?)/.test(id);
 }
@@ -2969,23 +3407,13 @@ function normalizeModuleId(id) {
   return id.split("?", 1)[0];
 }
 function getClientModuleSignature(source) {
+  if (!hasUseClientDirective(source)) return void 0;
   let program;
   try {
-    program = parseAst3(source, { jsx: true });
+    program = parseAst4(source, { lang: "tsx" });
   } catch {
     return void 0;
   }
-  let isUseClient = false;
-  for (const node of program.body ?? []) {
-    if (node?.type === "ExpressionStatement" && node.expression?.type === "Literal" && typeof node.expression.value === "string") {
-      if (node.expression.value === "use client") {
-        isUseClient = true;
-      }
-      continue;
-    }
-    break;
-  }
-  if (!isUseClient) return void 0;
   const exports = /* @__PURE__ */ new Set();
   let hasDefault = false;
   let hasExportAll = false;
@@ -3054,11 +3482,12 @@ function createVersionPlugin() {
   let currentVersion = buildVersion;
   let isDev = false;
   let server = null;
+  let resolvedCacheDir;
   const clientModuleSignatures = /* @__PURE__ */ new Map();
   let versionCounter = 0;
   const bumpVersion = (reason) => {
     currentVersion = Date.now().toString(16) + String(++versionCounter);
-    console.log(`[rsc-router] ${reason}, version updated: ${currentVersion}`);
+    console.log(`[rango] ${reason}, version updated: ${currentVersion}`);
     const rscEnv = server?.environments?.rsc;
     const versionMod = rscEnv?.moduleGraph?.getModuleById(
       "\0" + VIRTUAL_IDS.version
@@ -3072,6 +3501,7 @@ function createVersionPlugin() {
     enforce: "pre",
     configResolved(config) {
       isDev = config.command === "serve";
+      resolvedCacheDir = config.cacheDir ? String(config.cacheDir).replace(/\\/g, "/") : void 0;
     },
     configureServer(devServer) {
       server = devServer;
@@ -3108,11 +3538,11 @@ function createVersionPlugin() {
       }
       return null;
     },
-    // Track RSC module changes and update version
     async hotUpdate(ctx) {
       if (!isDev) return;
       const isRscModule = this.environment?.name === "rsc";
       if (!isRscModule) return;
+      if (isViteDepCachePath(ctx.file, resolvedCacheDir)) return;
       if (ctx.modules.length === 1 && ctx.modules[0].id === "\0" + VIRTUAL_IDS.version) {
         return;
       }
@@ -3142,13 +3572,24 @@ function createVersionPlugin() {
     }
   };
 }
+function isViteDepCachePath(filePath, cacheDir) {
+  if (!filePath) return false;
+  const normalized = filePath.replace(/\\/g, "/");
+  if (cacheDir) {
+    const normalizedCacheDir = cacheDir.replace(/\\/g, "/").replace(/\/+$/, "");
+    if (normalized === normalizedCacheDir || normalized.startsWith(normalizedCacheDir + "/")) {
+      return true;
+    }
+  }
+  return /\/node_modules\/\.vite[^/]*\//.test(normalized) || normalized.includes("/.vite-isolated/");
+}
 
 // src/vite/utils/shared-utils.ts
 import * as Vite from "vite";
 
 // src/vite/plugins/performance-tracks.ts
 import { readFile } from "node:fs/promises";
-var debug6 = createRangoDebugger("rango:transform");
+var debug6 = createRangoDebugger(NS.transform);
 var RSDW_PATCH_RE = /((?:var|let|const)\s+\w+\s*=\s*root\._children\s*,\s*(\w+)\s*=\s*root\._debugInfo\s*[;,])/;
 function buildPatchReplacement(match, debugInfoVar) {
   return `${match}
@@ -3170,22 +3611,15 @@ function patchRsdwClientDebugInfoRecovery(code) {
   };
 }
 function performanceTracksOptimizeDepsPlugin() {
+  const RSDW_CLIENT_RE = /react-server-dom-webpack-client\.browser\.(development|production)\.js$/;
   return {
     name: "@rangojs/router:performance-tracks-optimize-deps",
-    setup(build) {
-      build.onLoad(
-        {
-          filter: /react-server-dom-webpack-client\.browser\.(development|production)\.js$/
-        },
-        async (args) => {
-          const code = await readFile(args.path, "utf8");
-          const patched = patchRsdwClientDebugInfoRecovery(code);
-          return {
-            contents: patched.code,
-            loader: "js"
-          };
-        }
-      );
+    async load(id) {
+      const cleanId = id.split("?")[0] ?? id;
+      if (!RSDW_CLIENT_RE.test(cleanId)) return null;
+      const code = await readFile(cleanId, "utf8");
+      const patched = patchRsdwClientDebugInfoRecovery(code);
+      return { code: patched.code };
     }
   };
 }
@@ -3212,24 +3646,27 @@ function performanceTracksPlugin() {
 }
 
 // src/vite/utils/shared-utils.ts
-var versionEsbuildPlugin = {
+function resolveRscEntryFromConfig(config) {
+  const entries = config.environments?.["rsc"]?.optimizeDeps?.entries;
+  if (typeof entries === "string") return entries;
+  if (Array.isArray(entries) && entries.length > 0) return entries[0];
+  return void 0;
+}
+var versionRolldownPlugin = {
   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"
-      })
-    );
+  resolveId(id) {
+    if (id === VIRTUAL_IDS.version) return "\0" + VIRTUAL_IDS.version;
+    return void 0;
+  },
+  load(id) {
+    if (id === "\0" + VIRTUAL_IDS.version) {
+      return getVirtualVersionContent("dev");
+    }
+    return void 0;
   }
 };
-var sharedEsbuildOptions = {
-  plugins: [versionEsbuildPlugin, performanceTracksOptimizeDepsPlugin()]
+var sharedRolldownOptions = {
+  plugins: [versionRolldownPlugin, performanceTracksOptimizeDepsPlugin()]
 };
 function createVirtualEntriesPlugin(entries, routerPathRef) {
   const virtualModules = {};
@@ -3271,8 +3708,29 @@ function createVirtualEntriesPlugin(entries, routerPathRef) {
     }
   };
 }
+function isContentHashedAssetConflict(message) {
+  if (!message) return false;
+  const match = /The emitted file "?([^"\s]+)"? overwrites a previously emitted file/.exec(
+    message
+  );
+  if (!match) return false;
+  const fileName = match[1];
+  const base = fileName.slice(fileName.lastIndexOf("/") + 1);
+  const dot = base.lastIndexOf(".");
+  if (dot <= 0) return false;
+  const stem = base.slice(0, dot);
+  const HASH_LEN = 8;
+  if (stem.length < HASH_LEN + 1 || stem[stem.length - HASH_LEN - 1] !== "-") {
+    return false;
+  }
+  const hash = stem.slice(-HASH_LEN);
+  return /^[A-Za-z0-9_-]+$/.test(hash) && /[A-Z0-9]/.test(hash);
+}
 function onwarn(warning, defaultHandler) {
-  if (warning.code === "MODULE_LEVEL_DIRECTIVE" || warning.code === "SOURCEMAP_ERROR" || warning.code === "EMPTY_BUNDLE") {
+  if (warning.code === "MODULE_LEVEL_DIRECTIVE" || warning.code === "SOURCEMAP_ERROR" || warning.code === "EMPTY_BUNDLE" || warning.code === "INEFFECTIVE_DYNAMIC_IMPORT") {
+    return;
+  }
+  if (warning.code === "FILE_NAME_CONFLICT" && isContentHashedAssetConflict(warning.message)) {
     return;
   }
   if (warning.message?.includes("Sourcemap is likely to be incorrect")) {
@@ -3291,28 +3749,153 @@ function getManualChunks(id) {
     return "react";
   }
   const packageName = getPublishedPackageName();
-  if (normalized.includes(`node_modules/${packageName}/`) || normalized.includes("packages/rsc-router/") || normalized.includes("packages/rangojs-router/")) {
+  if (normalized.includes(`node_modules/${packageName}/`) || /\/packages\/(rsc-router|rangojs-router)\/(src|dist)\//.test(normalized)) {
     return "router";
   }
   return void 0;
 }
 
-// src/vite/utils/banner.ts
-var rangoVersion = package_default.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}\u2551\u2551 \u2551 \u2560\u2550\u255D \u2551  \u2560\u2566\u255D\u2560\u2550\u2563\u2551\u2551\u2551\u2551 \u2566\u2551 \u2551${reset}${dim}        *           \u2727${reset}
+// src/vite/plugins/client-ref-hashing.ts
+import { relative as relative2 } from "node:path";
+import { createHash as createHash2 } from "node:crypto";
+var debug7 = createRangoDebugger(NS.transform);
+var CLIENT_PKG_PROXY_PREFIX = "/@id/__x00__virtual:vite-rsc/client-package-proxy/";
+var CLIENT_IN_SERVER_PKG_PROXY_PREFIX = "/@id/__x00__virtual:vite-rsc/client-in-server-package-proxy/";
+var FS_PREFIX = "/@fs/";
+function hashRefKey(relativeId) {
+  return createHash2("sha256").update(relativeId).digest("hex").slice(0, 12);
+}
+function computeProductionHash(projectRoot, refKey) {
+  let toHash;
+  if (refKey.startsWith(CLIENT_PKG_PROXY_PREFIX)) {
+    toHash = refKey.slice(CLIENT_PKG_PROXY_PREFIX.length);
+  } else if (refKey.startsWith(CLIENT_IN_SERVER_PKG_PROXY_PREFIX)) {
+    const absPath = decodeURIComponent(
+      refKey.slice(CLIENT_IN_SERVER_PKG_PROXY_PREFIX.length)
+    );
+    toHash = relative2(projectRoot, absPath).replaceAll("\\", "/");
+  } else if (refKey.startsWith(FS_PREFIX)) {
+    const absPath = refKey.slice(FS_PREFIX.length - 1);
+    toHash = relative2(projectRoot, absPath).replaceAll("\\", "/");
+  } else if (refKey.startsWith("/")) {
+    toHash = refKey.slice(1);
+  } else {
+    return refKey;
+  }
+  return hashRefKey(toHash);
+}
+var REGISTER_CLIENT_REF_RE = /registerClientReference\(\s*(?:(?:\([^)]*\))|(?:\(\)[\s\S]*?\}))\s*,\s*"([^"]+)"\s*,\s*"[^"]+"\s*\)/g;
+function transformClientRefs(code, projectRoot) {
+  if (!code.includes("registerClientReference")) return null;
+  let hasReplacement = false;
+  const result = code.replace(
+    REGISTER_CLIENT_REF_RE,
+    (match, refKey) => {
+      const hash = computeProductionHash(projectRoot, refKey);
+      if (hash === refKey) return match;
+      hasReplacement = true;
+      return match.replace(`"${refKey}"`, `"${hash}"`);
+    }
+  );
+  return hasReplacement ? result : null;
+}
+function hashClientRefs(projectRoot) {
+  const counter = createCounter(debug7, "hash-client-refs");
+  return {
+    name: "@rangojs/router:hash-client-refs",
+    enforce: "post",
+    applyToEnvironment(env) {
+      return env.name === "rsc";
+    },
+    buildEnd() {
+      counter?.flush();
+    },
+    transform(code, id) {
+      const start = counter ? performance.now() : 0;
+      try {
+        const result = transformClientRefs(code, projectRoot);
+        if (result === null) return;
+        return { code: result, map: null };
+      } finally {
+        counter?.record(id, performance.now() - start);
+      }
+    }
+  };
+}
+
+// src/vite/utils/client-chunks.ts
+var debugChunks = createRangoDebugger(NS.chunks);
+function isSharedRuntime(meta) {
+  return [meta.id, meta.normalizedId].some(
+    (path6) => path6.includes("/node_modules/") || /\/@rangojs\/router\//.test(path6) || /\/packages\/(rangojs-router|rsc-router)\/(src|dist)\//.test(path6)
+  );
+}
+function sanitizeGroup(name) {
+  return name.replace(/[^a-zA-Z0-9_-]+/g, "_").replace(/^_+|_+$/g, "") || "app";
+}
+var ROUTE_ROOT_DIRS = /* @__PURE__ */ new Set([
+  "routes",
+  "route",
+  "pages",
+  "page",
+  "app",
+  "features",
+  "feature",
+  "views",
+  "view",
+  "handlers",
+  "urls",
+  "modules",
+  "screens",
+  "sections"
+]);
+function directoryClientChunks(meta, ctx) {
+  if (isSharedRuntime(meta)) {
+    return void 0;
+  }
+  if (ctx?.fallbackRefs.size && ctx.fallbackRefs.has(hashRefKey(meta.normalizedId))) {
+    debugChunks?.("fallback %s -> app-fallback", meta.normalizedId);
+    return "app-fallback";
+  }
+  const segments = meta.normalizedId.split("/").filter(Boolean);
+  const dirCount = segments.length - 1;
+  if (dirCount >= 1) {
+    for (let i = 0; i < dirCount - 1; i++) {
+      if (ROUTE_ROOT_DIRS.has(segments[i].toLowerCase())) {
+        const group = `app-${sanitizeGroup(segments[i + 1])}`;
+        debugChunks?.("split %s -> %s", meta.normalizedId, group);
+        return group;
+      }
+    }
+  }
+  debugChunks?.(
+    "shared %s (no route-root marker; inherits default grouping)",
+    meta.normalizedId
+  );
+  return void 0;
+}
+function resolveClientChunks(option, ctx) {
+  if (!option) return void 0;
+  if (option === true) return (meta) => directoryClientChunks(meta, ctx);
+  return option;
+}
+
+// src/vite/utils/banner.ts
+var rangoVersion = package_default.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}\u2551\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 \u2551${reset}${dim}                          *            \u2727.    \u2571${reset}
@@ -3333,15 +3916,7 @@ function createVersionInjectorPlugin(rscEntryPath) {
     enforce: "pre",
     configResolved(config) {
       let entryPath = rscEntryPath;
-      if (!entryPath) {
-        const rscEnvConfig = config.environments?.["rsc"];
-        const entries = rscEnvConfig?.optimizeDeps?.entries;
-        if (typeof entries === "string") {
-          entryPath = entries;
-        } else if (Array.isArray(entries) && entries.length > 0) {
-          entryPath = entries[0];
-        }
-      }
+      if (!entryPath) entryPath = resolveRscEntryFromConfig(config);
       if (entryPath) {
         resolvedEntryPath = resolve4(config.root, entryPath);
       }
@@ -3353,11 +3928,10 @@ function createVersionInjectorPlugin(rscEntryPath) {
       if (normalizedId !== normalizedEntry) {
         return null;
       }
-      const prepend = [];
+      const prepend = RSC_ENTRY_BOOTSTRAP_IMPORTS.map(
+        (id2) => `import "${id2}";`
+      );
       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";`);
@@ -3366,8 +3940,21 @@ function createVersionInjectorPlugin(rscEntryPath) {
           "createRSCHandler({\n  version: VERSION,"
         );
       }
-      if (prepend.length === 0 && newCode === code) return null;
-      newCode = prepend.join("\n") + (prepend.length > 0 ? "\n" : "") + newCode;
+      const lines = newCode.split("\n");
+      let insertAt = 0;
+      while (insertAt < lines.length) {
+        const trimmed = lines[insertAt].trim();
+        if (trimmed === "" || /^\/\/\/\s*<reference\b/.test(trimmed)) {
+          insertAt++;
+        } else {
+          break;
+        }
+      }
+      newCode = [
+        ...lines.slice(0, insertAt),
+        ...prepend,
+        ...lines.slice(insertAt)
+      ].join("\n");
       return {
         code: newCode,
         map: null
@@ -3377,28 +3964,27 @@ function createVersionInjectorPlugin(rscEntryPath) {
 }
 
 // src/vite/plugins/cjs-to-esm.ts
-var debug7 = createRangoDebugger("rango:transform");
+var debug8 = createRangoDebugger(NS.transform);
 function createCjsToEsmPlugin() {
-  const counter = createCounter(debug7, "cjs-to-esm");
+  let isProduction = false;
   return {
     name: "@rangojs/router:cjs-to-esm",
     enforce: "pre",
-    buildEnd() {
-      counter?.flush();
+    configResolved(config) {
+      isProduction = config.isProduction;
     },
     transform(code, id) {
-      const cleanId = id.split("?")[0];
-      const __t0 = counter ? performance.now() : 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 cleanId = id.split("?")[0].replaceAll("\\", "/");
+      if (cleanId.includes("vendor/react-server-dom/client.browser.js")) {
+        const isProd = isProduction;
         const cjsFile = isProd ? "./cjs/react-server-dom-webpack-client.browser.production.js" : "./cjs/react-server-dom-webpack-client.browser.development.js";
-        counter?.record(id, performance.now() - __t0);
+        debug8?.("cjs-to-esm entry redirect %s", id);
         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")) {
+      if (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] : "";
@@ -3428,7 +4014,7 @@ function createCjsToEsmPlugin() {
           "export const $1 ="
         );
         transformed = license + "\n" + transformed;
-        counter?.record(id, performance.now() - __t0);
+        debug8?.("cjs-to-esm body rewrite %s", id);
         return {
           code: transformed,
           map: null
@@ -3446,6 +4032,19 @@ import { readFileSync as readFileSync6 } from "node:fs";
 import { createRequire as createRequire2, register } from "node:module";
 import { pathToFileURL } from "node:url";
 
+// src/vite/inject-client-debug.ts
+function injectClientDebugFlag(id) {
+  if (!id.includes("internal-debug")) return null;
+  const norm = id.replace(/\\/g, "/");
+  const isInternalDebug = /\/internal-debug\.[cm]?[jt]sx?(\?|$)/.test(norm) && (norm.includes("/@rangojs/router/") || norm.includes("/packages/rangojs-router/"));
+  if (!isInternalDebug) return null;
+  return {
+    code: `export const INTERNAL_RANGO_DEBUG = ${!!process.env.INTERNAL_RANGO_DEBUG};
+`,
+    map: null
+  };
+}
+
 // src/vite/plugins/virtual-stub-plugin.ts
 function createVirtualStubPlugin() {
   const STUB_PREFIXES = [
@@ -3517,7 +4116,7 @@ function createCloudflareProtocolStubPlugin() {
       if (!code.includes(CF_PREFIX)) return null;
       let ast;
       try {
-        ast = this.parse(code);
+        ast = this.parse(code, { lang: "tsx" });
       } catch {
         return null;
       }
@@ -3577,72 +4176,6 @@ function walk(node, visit) {
   }
 }
 
-// src/vite/plugins/client-ref-hashing.ts
-import { relative } from "node:path";
-import { createHash as createHash2 } from "node:crypto";
-var debug8 = createRangoDebugger("rango:transform");
-var CLIENT_PKG_PROXY_PREFIX = "/@id/__x00__virtual:vite-rsc/client-package-proxy/";
-var CLIENT_IN_SERVER_PKG_PROXY_PREFIX = "/@id/__x00__virtual:vite-rsc/client-in-server-package-proxy/";
-var FS_PREFIX = "/@fs/";
-function computeProductionHash(projectRoot, refKey) {
-  let toHash;
-  if (refKey.startsWith(CLIENT_PKG_PROXY_PREFIX)) {
-    toHash = refKey.slice(CLIENT_PKG_PROXY_PREFIX.length);
-  } else if (refKey.startsWith(CLIENT_IN_SERVER_PKG_PROXY_PREFIX)) {
-    const absPath = decodeURIComponent(
-      refKey.slice(CLIENT_IN_SERVER_PKG_PROXY_PREFIX.length)
-    );
-    toHash = relative(projectRoot, absPath).replaceAll("\\", "/");
-  } else if (refKey.startsWith(FS_PREFIX)) {
-    const absPath = refKey.slice(FS_PREFIX.length - 1);
-    toHash = relative(projectRoot, absPath).replaceAll("\\", "/");
-  } else if (refKey.startsWith("/")) {
-    toHash = refKey.slice(1);
-  } else {
-    return refKey;
-  }
-  return createHash2("sha256").update(toHash).digest("hex").slice(0, 12);
-}
-var REGISTER_CLIENT_REF_RE = /registerClientReference\(\s*(?:(?:\([^)]*\))|(?:\(\)[\s\S]*?\}))\s*,\s*"([^"]+)"\s*,\s*"[^"]+"\s*\)/g;
-function transformClientRefs(code, projectRoot) {
-  if (!code.includes("registerClientReference")) return null;
-  let hasReplacement = false;
-  const result = code.replace(
-    REGISTER_CLIENT_REF_RE,
-    (match, refKey) => {
-      const hash = computeProductionHash(projectRoot, refKey);
-      if (hash === refKey) return match;
-      hasReplacement = true;
-      return match.replace(`"${refKey}"`, `"${hash}"`);
-    }
-  );
-  return hasReplacement ? result : null;
-}
-function hashClientRefs(projectRoot) {
-  const counter = createCounter(debug8, "hash-client-refs");
-  return {
-    name: "@rangojs/router:hash-client-refs",
-    // Run after the RSC plugin's transform (default enforce is normal)
-    enforce: "post",
-    applyToEnvironment(env) {
-      return env.name === "rsc";
-    },
-    buildEnd() {
-      counter?.flush();
-    },
-    transform(code, id) {
-      const start = counter ? performance.now() : 0;
-      try {
-        const result = transformClientRefs(code, projectRoot);
-        if (result === null) return;
-        return { code: result, map: null };
-      } finally {
-        counter?.record(id, performance.now() - start);
-      }
-    }
-  };
-}
-
 // src/vite/utils/bundle-analysis.ts
 function findMatchingParenInBundle(code, openParenPos) {
   let depth = 1;
@@ -3673,7 +4206,7 @@ function extractHandlerExportsFromChunk(chunkCode, handlerModules, fnName, detec
       if (detectPassthrough) {
         const eFnName = escapeRegExp(fnName);
         const callStartRe = new RegExp(
-          `const\\s+${eName}\\s*=\\s*${eFnName}\\s*(?:<[^>]*>)?\\s*\\(`
+          `(?:const|let|var)\\s+${eName}\\s*=\\s*${eFnName}\\s*(?:<[^>]*>)?\\s*\\(`
         );
         const callStart = callStartRe.exec(chunkCode);
         if (callStart) {
@@ -3698,7 +4231,7 @@ function evictHandlerCode(code, exports, fnName, brand) {
     if (passthrough) continue;
     const eName = escapeRegExp(name);
     const callStartRe = new RegExp(
-      `const\\s+${eName}\\s*=\\s*${eFnName}\\s*(?:<[^>]*>)?\\s*\\(`
+      `(?:const|let|var)\\s+${eName}\\s*=\\s*${eFnName}\\s*(?:<[^>]*>)?\\s*\\(`
     );
     const startMatch = callStartRe.exec(modified);
     if (!startMatch) continue;
@@ -3733,6 +4266,8 @@ function createDiscoveryState(entryPath, opts) {
     projectRoot: "",
     isBuildMode: false,
     userResolveAlias: void 0,
+    userRunnerConfig: void 0,
+    userResolvePlugins: [],
     scanFilter: void 0,
     cachedRouterFiles: void 0,
     opts,
@@ -3754,7 +4289,8 @@ function createDiscoveryState(entryPath, opts) {
     devServerOrigin: null,
     devServer: null,
     selfWrittenGenFiles: /* @__PURE__ */ new Map(),
-    SELF_WRITE_WINDOW_MS: 5e3
+    SELF_WRITE_WINDOW_MS: 5e3,
+    lastDiscoveryError: null
   };
 }
 
@@ -3766,6 +4302,12 @@ function markSelfGenWrite(state, filePath, content) {
   state.selfWrittenGenFiles.set(filePath, { at: Date.now(), hash });
 }
 function consumeSelfGenWrite(state, filePath) {
+  return checkSelfGenWrite(state, filePath, true);
+}
+function peekSelfGenWrite(state, filePath) {
+  return checkSelfGenWrite(state, filePath, false);
+}
+function checkSelfGenWrite(state, filePath, consume) {
   const info = state.selfWrittenGenFiles.get(filePath);
   if (!info) return false;
   if (Date.now() - info.at > state.SELF_WRITE_WINDOW_MS) {
@@ -3776,7 +4318,7 @@ function consumeSelfGenWrite(state, filePath) {
     const current = readFileSync3(filePath, "utf-8");
     const currentHash = createHash3("sha256").update(current).digest("hex");
     if (currentHash === info.hash) {
-      state.selfWrittenGenFiles.delete(filePath);
+      if (consume) state.selfWrittenGenFiles.delete(filePath);
       return true;
     }
     return false;
@@ -3786,11 +4328,57 @@ function consumeSelfGenWrite(state, filePath) {
   }
 }
 
-// src/vite/utils/manifest-utils.ts
+// src/router/logging.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+
+// src/internal-debug.ts
+var INTERNAL_RANGO_DEBUG = typeof process !== "undefined" && Boolean(process.env?.INTERNAL_RANGO_DEBUG);
+
+// src/router/logging.ts
+var routerLogContext = new AsyncLocalStorage();
+
+// src/router/pattern-matching.ts
+function parsePattern(pattern) {
+  const segments = [];
+  const segmentRegex = /\/(:([a-zA-Z_][a-zA-Z0-9_]*)(\(([^)]+)\))?(\?)?([^/]*)|(\*)|([^/]+))/g;
+  let match;
+  while ((match = segmentRegex.exec(pattern)) !== null) {
+    const [
+      ,
+      ,
+      paramName,
+      ,
+      constraint,
+      optional,
+      suffix,
+      wildcard,
+      staticText
+    ] = match;
+    if (wildcard) {
+      segments.push({ type: "wildcard", value: "*", optional: false });
+    } else if (paramName) {
+      segments.push({
+        type: "param",
+        value: paramName,
+        optional: optional === "?",
+        constraint: constraint ? constraint.split("|") : void 0,
+        suffix: suffix || void 0
+      });
+    } else if (staticText) {
+      segments.push({ type: "static", value: staticText, optional: false });
+    }
+  }
+  return segments;
+}
+
+// src/build/prefix-tree-utils.ts
 function flattenLeafEntries(prefixTree, routeManifest, result) {
-  function visit(node) {
+  function visit(node, ancestorStaticPrefixes) {
     const children = node.children || {};
     if (Object.keys(children).length === 0 && node.routes && node.routes.length > 0) {
+      if (ancestorStaticPrefixes.has(node.staticPrefix)) {
+        return;
+      }
       const routes = {};
       for (const name of node.routes) {
         if (name in routeManifest) {
@@ -3799,13 +4387,15 @@ function flattenLeafEntries(prefixTree, routeManifest, result) {
       }
       result.push({ staticPrefix: node.staticPrefix, routes });
     } else {
+      const nextAncestors = new Set(ancestorStaticPrefixes);
+      nextAncestors.add(node.staticPrefix);
       for (const child of Object.values(children)) {
-        visit(child);
+        visit(child, nextAncestors);
       }
     }
   }
   for (const node of Object.values(prefixTree)) {
-    visit(node);
+    visit(node, /* @__PURE__ */ new Set());
   }
 }
 function buildRouteToStaticPrefix(prefixTree, result) {
@@ -3822,6 +4412,219 @@ function buildRouteToStaticPrefix(prefixTree, result) {
     visit(node);
   }
 }
+
+// src/build/route-trie.ts
+function buildRouteTrie(routeManifest, routeAncestry, routeToStaticPrefix, routeTrailingSlash, prerenderRouteNames, passthroughRouteNames, responseTypeRoutes) {
+  const root = {};
+  for (const [routeName, pattern] of Object.entries(routeManifest)) {
+    const ancestry = routeAncestry[routeName] || [];
+    const staticPrefix = routeToStaticPrefix[routeName] || "";
+    const trailingSlash = routeTrailingSlash?.[routeName];
+    const responseType = responseTypeRoutes?.[routeName];
+    const hasTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
+    const normalizedPattern = hasTrailingSlash ? pattern.slice(0, -1) : pattern;
+    const segments = parsePattern(normalizedPattern);
+    insertRoute(root, segments, 0, {
+      n: routeName,
+      sp: staticPrefix,
+      a: ancestry,
+      ...trailingSlash ? { ts: trailingSlash } : {},
+      ...prerenderRouteNames?.has(routeName) ? { pr: true } : {},
+      ...passthroughRouteNames?.has(routeName) ? { pt: true } : {},
+      ...responseType ? { rt: responseType } : {}
+    });
+  }
+  sortSuffixParams(root);
+  return root;
+}
+function sortSuffixParams(node) {
+  if (node.xp) {
+    const sorted = {};
+    for (const suffix of Object.keys(node.xp).sort(
+      (a, b) => b.length - a.length
+    )) {
+      sorted[suffix] = node.xp[suffix];
+    }
+    node.xp = sorted;
+    for (const child of Object.values(node.xp)) {
+      sortSuffixParams(child.c);
+    }
+  }
+  if (node.s) {
+    for (const child of Object.values(node.s)) {
+      sortSuffixParams(child);
+    }
+  }
+  if (node.p) {
+    sortSuffixParams(node.p.c);
+  }
+}
+function buildPerRouterTrie(manifest) {
+  const ancestry = manifest._routeAncestry;
+  if (!ancestry || Object.keys(ancestry).length === 0) {
+    return null;
+  }
+  const routeToStaticPrefix = {};
+  for (const name of Object.keys(manifest.routeManifest)) {
+    routeToStaticPrefix[name] = "";
+  }
+  if (manifest.prefixTree) {
+    buildRouteToStaticPrefix(manifest.prefixTree, routeToStaticPrefix);
+  }
+  return buildRouteTrie(
+    manifest.routeManifest,
+    ancestry,
+    routeToStaticPrefix,
+    manifest.routeTrailingSlash,
+    manifest.prerenderRoutes ? new Set(manifest.prerenderRoutes) : void 0,
+    manifest.passthroughRoutes ? new Set(manifest.passthroughRoutes) : void 0,
+    manifest.responseTypeRoutes
+  );
+}
+function insertRoute(node, segments, index, leaf) {
+  const constraints = {};
+  for (const seg of segments) {
+    if (seg.type === "param") {
+      if (seg.constraint) {
+        constraints[seg.value] = seg.constraint;
+      }
+    }
+  }
+  const leafBase = {
+    ...leaf,
+    ...Object.keys(constraints).length > 0 ? { cv: constraints } : {}
+  };
+  insertSegments(node, segments, index, leafBase, []);
+}
+function toVariant(leaf, responseType) {
+  return leaf.pa ? { routeKey: leaf.n, responseType, pa: leaf.pa } : { routeKey: leaf.n, responseType };
+}
+function mergeLeaves(existing, leaf) {
+  if (!existing) return leaf;
+  if (existing.rt && leaf.rt) {
+    const merged = leaf;
+    merged.nv = existing.nv || [];
+    merged.nv.push(toVariant(existing, existing.rt));
+    return merged;
+  }
+  if (leaf.rt && !existing.rt) {
+    if (!existing.nv) {
+      existing.nv = [];
+      existing.rf = true;
+    }
+    existing.nv.push(toVariant(leaf, leaf.rt));
+    return existing;
+  }
+  if (!leaf.rt && existing.rt) {
+    if (!leaf.nv) leaf.nv = [];
+    if (existing.nv) leaf.nv.push(...existing.nv);
+    leaf.nv.push(toVariant(existing, existing.rt));
+    return leaf;
+  }
+  return leaf;
+}
+function mergeLeaf(node, leaf) {
+  node.r = mergeLeaves(node.r, leaf);
+}
+function buildLeaf(leafBase, paramNames) {
+  return paramNames.length > 0 ? { ...leafBase, pa: [...paramNames] } : { ...leafBase };
+}
+function insertSegments(node, segments, index, leafBase, paramNames) {
+  if (index >= segments.length) {
+    mergeLeaf(node, buildLeaf(leafBase, paramNames));
+    return;
+  }
+  const segment = segments[index];
+  if (segment.type === "static") {
+    if (!node.s) node.s = {};
+    if (!node.s[segment.value]) node.s[segment.value] = {};
+    insertSegments(
+      node.s[segment.value],
+      segments,
+      index + 1,
+      leafBase,
+      paramNames
+    );
+  } else if (segment.type === "param") {
+    if (segment.optional) {
+      insertSegments(node, segments, index + 1, leafBase, paramNames);
+    }
+    if (segment.suffix) {
+      if (!node.xp) node.xp = {};
+      if (!node.xp[segment.suffix]) {
+        node.xp[segment.suffix] = { n: segment.value, c: {} };
+      }
+      insertSegments(node.xp[segment.suffix].c, segments, index + 1, leafBase, [
+        ...paramNames,
+        segment.value
+      ]);
+    } else {
+      if (!node.p) {
+        node.p = { n: segment.value, c: {} };
+      }
+      insertSegments(node.p.c, segments, index + 1, leafBase, [
+        ...paramNames,
+        segment.value
+      ]);
+    }
+  } else if (segment.type === "wildcard") {
+    const wildLeaf = {
+      ...buildLeaf(leafBase, paramNames),
+      pn: "*"
+    };
+    const existing = node.w ? { ...node.w } : void 0;
+    const merged = mergeLeaves(existing, wildLeaf);
+    node.w = merged;
+  }
+}
+
+// src/build/collect-fallback-refs.ts
+var CLIENT_REF = /* @__PURE__ */ Symbol.for("react.client.reference");
+var MAX_DEPTH = 40;
+var SYNTHETIC_PROPS = {
+  error: new Error("rango: build-time fallback-chunk discovery"),
+  reset: () => {
+  },
+  pathname: "/",
+  info: { componentStack: "" }
+};
+function isReactNodeLike(v) {
+  return Array.isArray(v) || typeof v === "object" && v !== null && "$$typeof" in v;
+}
+function walkElementTree(node, report, depth) {
+  if (node == null || depth > MAX_DEPTH) return;
+  if (Array.isArray(node)) {
+    for (const child of node) walkElementTree(child, report, depth + 1);
+    return;
+  }
+  if (typeof node !== "object") return;
+  const el = node;
+  const type = el.type;
+  if (type?.$$typeof === CLIENT_REF && typeof type.$$id === "string") {
+    report(type.$$id.split("#")[0]);
+  }
+  const props = el.props;
+  if (props && typeof props === "object") {
+    walkElementTree(props.children, report, depth + 1);
+    for (const key in props) {
+      if (key === "children") continue;
+      const value = props[key];
+      if (isReactNodeLike(value)) walkElementTree(value, report, depth + 1);
+    }
+  }
+}
+function collectFallbackClientRefs(boundary, report) {
+  try {
+    let node = boundary;
+    if (typeof node === "function") {
+      node = node(SYNTHETIC_PROPS);
+    }
+    walkElementTree(node, report, 0);
+  } catch {
+  }
+}
+
+// src/vite/utils/manifest-utils.ts
 function jsonParseExpression(value) {
   const json = JSON.stringify(value);
   const escaped = json.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
@@ -3829,6 +4632,9 @@ function jsonParseExpression(value) {
 }
 
 // src/context-var.ts
+function hasContextVars(variables) {
+  return Object.keys(variables).length > 0 || Object.getOwnPropertySymbols(variables).length > 0;
+}
 var NON_CACHEABLE_KEYS = /* @__PURE__ */ Symbol.for(
   "rango:non-cacheable-keys"
 );
@@ -3869,9 +4675,6 @@ import {
   writeFileSync as writeFileSync2
 } from "node:fs";
 import { resolve as resolve5 } from "node:path";
-function escapeRegExp2(str) {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
 function encodePathParam(value) {
   return String(value).split("/").map((segment) => encodeURIComponent(segment)).join("/");
 }
@@ -3879,7 +4682,7 @@ function substituteRouteParams(pattern, params, encode = encodeURIComponent) {
   let result = pattern;
   let hadOmittedOptional = false;
   for (const [key, value] of Object.entries(params)) {
-    const escaped = escapeRegExp2(key);
+    const escaped = escapeRegExp(key);
     if (value === "") {
       result = result.replace(
         new RegExp(`:${escaped}(\\([^)]*\\))?(?!\\?)`),
@@ -3912,13 +4715,24 @@ async function runWithConcurrency(items, concurrency, fn) {
     return;
   }
   let nextIndex = 0;
+  let firstError;
+  let failed = false;
   async function worker() {
-    while (nextIndex < items.length) {
+    while (nextIndex < items.length && !failed) {
       const idx = nextIndex++;
-      await fn(items[idx]);
+      try {
+        await fn(items[idx]);
+      } catch (err) {
+        if (!failed) {
+          failed = true;
+          firstError = err;
+        }
+        return;
+      }
     }
   }
   await Promise.all(Array.from({ length: limit }, () => worker()));
+  if (failed) throw firstError;
 }
 function groupByConcurrency(entries) {
   const map = /* @__PURE__ */ new Map();
@@ -3965,6 +4779,23 @@ function notifyOnError(registry, error, phase, routeKey, pathname, skipped) {
     break;
   }
 }
+function resolvePrerenderError(registry, error, onError, label, elapsed, phase, routeKey, pathname) {
+  const isSkip = error?.name === "Skip";
+  if (isSkip || onError === "warn") {
+    if (isSkip) {
+      console.log(`[rango]   SKIP ${label} (${elapsed}ms) - ${error.message}`);
+    } else {
+      console.warn(
+        `[rango]   WARN ${label} (${elapsed}ms) - render error, not pre-rendered (prerender.onError: "warn"): ${error.message}`
+      );
+    }
+    notifyOnError(registry, error, phase, routeKey, pathname, true);
+    return;
+  }
+  console.error(`[rango]   FAIL ${label} (${elapsed}ms) - ${error.message}`);
+  notifyOnError(registry, error, phase, routeKey, pathname);
+  throw error;
+}
 function getStagedAssetDir(projectRoot) {
   return resolve5(projectRoot, "node_modules/.rangojs-router-build/rsc-assets");
 }
@@ -3998,7 +4829,7 @@ function copyStagedBuildAssets(projectRoot, fileNames) {
 }
 
 // src/vite/discovery/prerender-collection.ts
-var debug9 = createRangoDebugger("rango:prerender");
+var debug9 = createRangoDebugger(NS.prerender);
 async function expandPrerenderRoutes(state, rscEnv, registry, allManifests) {
   if (!state.opts?.enableBuildPrerender || !state.isBuildMode) return;
   const overallStart = debug9 ? performance.now() : 0;
@@ -4032,7 +4863,7 @@ async function expandPrerenderRoutes(state, rscEnv, registry, allManifests) {
   const progressInterval = totalDynamic > 0 ? setInterval(() => {
     const elapsed = ((performance.now() - paramsStart) / 1e3).toFixed(1);
     console.log(
-      `[rsc-router] Resolving prerender params... ${resolvedRoutes}/${totalDynamic} routes (${elapsed}s)`
+      `[rango] Resolving prerender params... ${resolvedRoutes}/${totalDynamic} routes (${elapsed}s)`
     );
   }, 5e3) : void 0;
   try {
@@ -4069,7 +4900,7 @@ async function expandPrerenderRoutes(state, rscEnv, registry, allManifests) {
                 get env() {
                   if (buildEnv !== void 0) return buildEnv;
                   throw new Error(
-                    "[rsc-router] ctx.env is not available during build-time getParams(). Configure buildEnv in your rango() plugin options to enable build-time env access."
+                    "[rango] ctx.env is not available during build-time getParams(). Configure buildEnv in your rango() plugin options to enable build-time env access."
                   );
                 }
               };
@@ -4081,7 +4912,7 @@ async function expandPrerenderRoutes(state, rscEnv, registry, allManifests) {
                 (performance.now() - getParamsStart).toFixed(1)
               );
               const concurrency = def.options?.concurrency ?? 1;
-              const hasBuildVars = Object.keys(buildVars).length > 0 || Object.getOwnPropertySymbols(buildVars).length > 0;
+              const hasBuildVars = hasContextVars(buildVars);
               for (const params of paramsList) {
                 let url = substituteRouteParams(
                   pattern,
@@ -4110,7 +4941,7 @@ async function expandPrerenderRoutes(state, rscEnv, registry, allManifests) {
               resolvedRoutes++;
               if (err.name === "Skip") {
                 console.log(
-                  `[rsc-router]   SKIP route "${routeName}" - ${err.message}`
+                  `[rango]   SKIP route "${routeName}" - ${err.message}`
                 );
                 notifyOnError(
                   registry,
@@ -4123,14 +4954,14 @@ async function expandPrerenderRoutes(state, rscEnv, registry, allManifests) {
                 continue;
               }
               console.error(
-                `[rsc-router] Failed to get params for prerender route "${routeName}": ${err.message}`
+                `[rango] Failed to get params for prerender route "${routeName}": ${err.message}`
               );
               notifyOnError(registry, err, "prerender", routeName);
               throw err;
             }
           } else {
             console.warn(
-              `[rsc-router] Dynamic prerender route "${routeName}" has no getParams(), skipping`
+              `[rango] Dynamic prerender route "${routeName}" has no getParams(), skipping`
             );
           }
         }
@@ -4141,7 +4972,7 @@ async function expandPrerenderRoutes(state, rscEnv, registry, allManifests) {
       clearInterval(progressInterval);
       const elapsed = ((performance.now() - paramsStart) / 1e3).toFixed(1);
       console.log(
-        `[rsc-router] Resolved prerender params: ${resolvedRoutes}/${totalDynamic} routes (${elapsed}s)`
+        `[rango] Resolved prerender params: ${resolvedRoutes}/${totalDynamic} routes (${elapsed}s)`
       );
     }
   }
@@ -4155,7 +4986,7 @@ async function expandPrerenderRoutes(state, rscEnv, registry, allManifests) {
   const maxConcurrency = Math.max(...entries.map((e) => e.concurrency));
   const concurrencyNote = maxConcurrency > 1 ? ` (concurrency: ${maxConcurrency})` : "";
   console.log(
-    `[rsc-router] Pre-rendering ${entries.length} URL(s)${concurrencyNote}...`
+    `[rango] Pre-rendering ${entries.length} URL(s)${concurrencyNote}...`
   );
   debug9?.(
     "prerender loop: %d entries, max concurrency %d",
@@ -4166,6 +4997,7 @@ async function expandPrerenderRoutes(state, rscEnv, registry, allManifests) {
   const manifestEntries = {};
   let doneCount = 0;
   let skipCount = 0;
+  const prerenderOnError = state.opts?.prerenderOnError ?? "fail";
   const startTotal = performance.now();
   const groups = groupByConcurrency(entries);
   for (const group of groups) {
@@ -4188,7 +5020,7 @@ async function expandPrerenderRoutes(state, rscEnv, registry, allManifests) {
             if (result.passthrough) {
               const elapsed2 = (performance.now() - startUrl).toFixed(0);
               console.log(
-                `[rsc-router]   PASS ${entry.urlPath.padEnd(40)} (${elapsed2}ms) - live fallback`
+                `[rango]   PASS ${entry.urlPath.padEnd(40)} (${elapsed2}ms) - live fallback`
               );
               doneCount++;
               break;
@@ -4208,10 +5040,9 @@ async function expandPrerenderRoutes(state, rscEnv, registry, allManifests) {
               const interceptKey = `${result.routeName}/${paramHash}/i`;
               const interceptValue = JSON.stringify({
                 segments: [...result.segments, ...result.interceptSegments],
-                handles: {
-                  ...result.handles,
-                  ...result.interceptHandles || {}
-                }
+                // interceptHandles is the pre-encoded MERGED (main + intercept)
+                // handle string (the producer merged before encoding).
+                handles: result.interceptHandles ?? ""
               });
               manifestEntries[interceptKey] = stageBuildAssetModule(
                 state.projectRoot,
@@ -4221,39 +5052,24 @@ async function expandPrerenderRoutes(state, rscEnv, registry, allManifests) {
             }
             const elapsed = (performance.now() - startUrl).toFixed(0);
             console.log(
-              `[rsc-router]   OK   ${entry.urlPath.padEnd(40)} (${elapsed}ms)`
+              `[rango]   OK   ${entry.urlPath.padEnd(40)} (${elapsed}ms)`
             );
             doneCount++;
             break;
           } catch (err) {
-            if (err.name === "Skip") {
-              const elapsed2 = (performance.now() - startUrl).toFixed(0);
-              console.log(
-                `[rsc-router]   SKIP ${entry.urlPath.padEnd(40)} (${elapsed2}ms) - ${err.message}`
-              );
-              skipCount++;
-              notifyOnError(
-                registry,
-                err,
-                "prerender",
-                entry.routeName,
-                entry.urlPath,
-                true
-              );
-              break;
-            }
             const elapsed = (performance.now() - startUrl).toFixed(0);
-            console.error(
-              `[rsc-router]   FAIL ${entry.urlPath.padEnd(40)} (${elapsed}ms) - ${err.message}`
-            );
-            notifyOnError(
+            resolvePrerenderError(
               registry,
               err,
+              prerenderOnError,
+              entry.urlPath.padEnd(40),
+              elapsed,
               "prerender",
               entry.routeName,
               entry.urlPath
             );
-            throw err;
+            skipCount++;
+            break;
           }
         }
       }
@@ -4266,7 +5082,7 @@ async function expandPrerenderRoutes(state, rscEnv, registry, allManifests) {
   const parts = [`${doneCount} done`];
   if (skipCount > 0) parts.push(`${skipCount} skipped`);
   console.log(
-    `[rsc-router] Pre-render complete: ${parts.join(", ")} (${totalElapsed}ms total)`
+    `[rango] Pre-render complete: ${parts.join(", ")} (${totalElapsed}ms total)`
   );
   debug9?.(
     "expandPrerenderRoutes done: %d done, %d skipped, %sms (overall %sms)",
@@ -4288,20 +5104,19 @@ async function renderStaticHandlers(state, rscEnv, registry) {
   let staticDone = 0;
   let staticSkip = 0;
   let totalStaticCount = 0;
+  const prerenderOnError = state.opts?.prerenderOnError ?? "fail";
   for (const [, exportNames] of state.resolvedStaticModules) {
     totalStaticCount += exportNames.length;
   }
   const startStatic = performance.now();
-  console.log(
-    `[rsc-router] Rendering ${totalStaticCount} static handler(s)...`
-  );
+  console.log(`[rango] Rendering ${totalStaticCount} static handler(s)...`);
   for (const [moduleId, exportNames] of state.resolvedStaticModules) {
     let mod;
     try {
       mod = await rscEnv.runner.import(moduleId);
     } catch (err) {
       console.error(
-        `[rsc-router] Failed to import static module ${moduleId}: ${err.message}`
+        `[rango] Failed to import static module ${moduleId}: ${err.message}`
       );
       notifyOnError(registry, err, "static");
       throw err;
@@ -4323,7 +5138,7 @@ async function renderStaticHandlers(state, rscEnv, registry) {
             !state.isBuildMode
           );
           if (result) {
-            const hasHandles = Object.keys(result.handles).length > 0;
+            const hasHandles = result.handles !== "";
             const exportValue = hasHandles ? JSON.stringify(result) : JSON.stringify(result.encoded);
             manifestEntries[def.$$id] = stageBuildAssetModule(
               state.projectRoot,
@@ -4331,36 +5146,28 @@ async function renderStaticHandlers(state, rscEnv, registry) {
               exportValue
             );
             const elapsed = (performance.now() - startHandler).toFixed(0);
-            console.log(
-              `[rsc-router]   OK   ${name.padEnd(40)} (${elapsed}ms)`
-            );
+            console.log(`[rango]   OK   ${name.padEnd(40)} (${elapsed}ms)`);
             staticDone++;
             handled = true;
             break;
           }
         } catch (err) {
-          if (err.name === "Skip") {
-            const elapsed2 = (performance.now() - startHandler).toFixed(0);
-            console.log(
-              `[rsc-router]   SKIP ${name.padEnd(40)} (${elapsed2}ms) - ${err.message}`
-            );
-            staticSkip++;
-            notifyOnError(registry, err, "static", void 0, void 0, true);
-            handled = true;
-            break;
-          }
           const elapsed = (performance.now() - startHandler).toFixed(0);
-          console.error(
-            `[rsc-router]   FAIL ${name.padEnd(40)} (${elapsed}ms) - ${err.message}`
+          resolvePrerenderError(
+            registry,
+            err,
+            prerenderOnError,
+            name.padEnd(40),
+            elapsed,
+            "static"
           );
-          notifyOnError(registry, err, "static");
-          throw err;
+          staticSkip++;
+          handled = true;
+          break;
         }
       }
       if (!handled) {
-        console.warn(
-          `[rsc-router] No router could render static handler "${name}"`
-        );
+        console.warn(`[rango] No router could render static handler "${name}"`);
       }
     }
   }
@@ -4371,7 +5178,7 @@ async function renderStaticHandlers(state, rscEnv, registry) {
   const staticParts = [`${staticDone} done`];
   if (staticSkip > 0) staticParts.push(`${staticSkip} skipped`);
   console.log(
-    `[rsc-router] Static render complete: ${staticParts.join(", ")} (${totalStaticElapsed}ms total)`
+    `[rango] Static render complete: ${staticParts.join(", ")} (${totalStaticElapsed}ms total)`
   );
   debug9?.(
     "renderStaticHandlers done: %d done, %d skipped, %sms (overall %sms)",
@@ -4382,8 +5189,82 @@ async function renderStaticHandlers(state, rscEnv, registry) {
   );
 }
 
+// src/vite/discovery/discovery-errors.ts
+function indent(text, pad) {
+  return text.split("\n").map((line) => line.length > 0 ? pad + line : line).join("\n");
+}
+async function invokeLazyMount(loader, context, errors) {
+  try {
+    await loader();
+  } catch (error) {
+    errors.push({ context, error });
+  }
+}
+function isLazyMount(route) {
+  return !!route && route.kind === "lazy" && typeof route.handler === "function";
+}
+async function resolveHostRouterHandlers(hostRegistry) {
+  const errors = [];
+  for (const [hostId, entry] of hostRegistry) {
+    for (const route of entry.routes) {
+      if (isLazyMount(route)) {
+        await invokeLazyMount(
+          route.handler,
+          `host "${hostId}" route handler`,
+          errors
+        );
+      }
+    }
+    if (isLazyMount(entry.fallback)) {
+      await invokeLazyMount(
+        entry.fallback.handler,
+        `host "${hostId}" fallback handler`,
+        errors
+      );
+    }
+  }
+  return errors;
+}
+function formatNoRoutersError(entryPath, errors) {
+  const base = `[rango] No routers found in registry after importing ${entryPath}`;
+  if (errors.length === 0) {
+    return base;
+  }
+  const formatted = errors.map(({ context, error }) => {
+    const err = error instanceof Error ? error : new Error(String(error));
+    const detail = err.stack ?? err.message;
+    return `  - while resolving ${context}:
+${indent(detail, "      ")}`;
+  }).join("\n");
+  return `${base}
+
+${errors.length} error(s) were caught during host-router discovery and likely explain why no routers were registered:
+${formatted}`;
+}
+function toCause(errors) {
+  if (errors.length === 0) return void 0;
+  if (errors.length === 1) return errors[0].error;
+  return new AggregateError(
+    errors.map((e) => e.error),
+    "Multiple host-router handlers failed during discovery"
+  );
+}
+var DiscoveryError = class _DiscoveryError extends Error {
+  constructor(entryPath, caught) {
+    super(formatNoRoutersError(entryPath, caught));
+    const cause = toCause(caught);
+    if (cause !== void 0) {
+      this.cause = cause;
+    }
+    this.name = "DiscoveryError";
+    this.entryPath = entryPath;
+    this.caught = caught;
+    Object.setPrototypeOf(this, _DiscoveryError.prototype);
+  }
+};
+
 // src/vite/discovery/discover-routers.ts
-var debug10 = createRangoDebugger("rango:discovery");
+var debug10 = createRangoDebugger(NS.discovery);
 async function discoverRouters(state, rscEnv) {
   if (!state.resolvedEntryPath) return;
   await timed(
@@ -4398,27 +5279,17 @@ async function discoverRouters(state, rscEnv) {
   );
   let registry = serverMod.RouterRegistry;
   if (!registry || registry.size === 0) {
+    const discoveryErrors = [];
     try {
       const hostRegistry = serverMod.HostRouterRegistry;
       if (hostRegistry && hostRegistry.size > 0) {
         console.log(
-          `[rsc-router] Found ${hostRegistry.size} host router(s), resolving lazy handlers...`
+          `[rango] 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 handlerErrors = await resolveHostRouterHandlers(hostRegistry);
+        discoveryErrors.push(...handlerErrors);
+        for (const { context, error } of handlerErrors) {
+          debug10?.("caught error while resolving %s: %O", context, error);
         }
         const freshServerMod = await rscEnv.runner.import(
           "@rangojs/router/server"
@@ -4429,12 +5300,11 @@ async function discoverRouters(state, rscEnv) {
           registry = freshRegistry;
         }
       }
-    } catch {
+    } catch (error) {
+      discoveryErrors.push({ context: "host-router discovery", error });
     }
     if (!registry || registry.size === 0) {
-      throw new Error(
-        `[rsc-router] No routers found in registry after importing ${state.resolvedEntryPath}`
-      );
+      throw new DiscoveryError(state.resolvedEntryPath, discoveryErrors);
     }
   }
   const buildMod = await timed(
@@ -4462,6 +5332,15 @@ async function discoverRouters(state, rscEnv) {
   let mergedRouteTrailingSlash = {};
   let routerMountIndex = 0;
   const allManifests = [];
+  const clientChunkCtx = state.opts?.clientChunkCtx;
+  const collectClientFallbackRef = clientChunkCtx ? (refKey) => clientChunkCtx.fallbackRefs.add(
+    computeProductionHash(state.projectRoot, refKey)
+  ) : void 0;
+  const collectFromBoundaryNode = (node) => {
+    if (collectClientFallbackRef) {
+      collectFallbackClientRefs(node, collectClientFallbackRef);
+    }
+  };
   const manifestGenStart = debug10 ? performance.now() : 0;
   for (const [id, router] of registry) {
     if (!router.urlpatterns || !generateManifestFull) {
@@ -4470,10 +5349,18 @@ async function discoverRouters(state, rscEnv) {
     const manifest = generateManifestFull(
       router.urlpatterns,
       routerMountIndex,
-      router.__basename ? { urlPrefix: router.__basename } : void 0
+      {
+        ...router.__basename ? { urlPrefix: router.__basename } : {},
+        ...collectClientFallbackRef ? { collectClientFallbackRef } : {}
+      }
     );
     routerMountIndex++;
     allManifests.push({ id, manifest });
+    if (collectClientFallbackRef) {
+      collectFromBoundaryNode(router.__defaultErrorBoundary);
+      collectFromBoundaryNode(router.__defaultNotFoundBoundary);
+      collectFromBoundaryNode(router.__notFound);
+    }
     const routeCount = Object.keys(manifest.routeManifest).length;
     const staticRoutes = Object.values(manifest.routeManifest).filter(
       (p) => !p.includes(":") && !p.includes("*")
@@ -4510,21 +5397,17 @@ async function discoverRouters(state, rscEnv) {
     if (manifest.routeTrailingSlash) {
       Object.assign(mergedRouteTrailingSlash, manifest.routeTrailingSlash);
     }
-    flattenLeafEntries(
-      manifest.prefixTree,
-      manifest.routeManifest,
-      newMergedPrecomputedEntries
-    );
-    newPerRouterManifestDataMap.set(id, manifest.routeManifest);
     const routerPrecomputed = [];
     flattenLeafEntries(
       manifest.prefixTree,
       manifest.routeManifest,
       routerPrecomputed
     );
+    newMergedPrecomputedEntries.push(...routerPrecomputed);
+    newPerRouterManifestDataMap.set(id, manifest.routeManifest);
     newPerRouterPrecomputedMap.set(id, routerPrecomputed);
     console.log(
-      `[rsc-router] Router "${id}" -> ${routeCount} routes (${staticRoutes} static, ${dynamicRoutes} dynamic)`
+      `[rango] Router "${id}" -> ${routeCount} routes (${staticRoutes} static, ${dynamicRoutes} dynamic)`
     );
   }
   if (registry.size > 1) {
@@ -4533,7 +5416,7 @@ async function discoverRouters(state, rscEnv) {
     );
     if (autoIds.length > 1) {
       console.warn(
-        `[rsc-router] WARNING: ${autoIds.length} routers use auto-generated IDs (${autoIds.join(", ")}). In multi-router setups, each createRouter() must have an explicit \`id\` option to ensure per-router manifest data is matched correctly at runtime. Example: createRouter({ id: "site", ... })`
+        `[rango] WARNING: ${autoIds.length} routers use auto-generated IDs (${autoIds.join(", ")}). In multi-router setups, each createRouter() must have an explicit \`id\` option to ensure per-router manifest data is matched correctly at runtime. Example: createRouter({ id: "site", ... })`
       );
     }
   }
@@ -4545,8 +5428,7 @@ async function discoverRouters(state, rscEnv) {
   let newMergedRouteTrie = null;
   const trieStart = debug10 ? performance.now() : 0;
   if (Object.keys(newMergedRouteManifest).length > 0) {
-    const buildRouteTrie = buildMod.buildRouteTrie;
-    if (buildRouteTrie && mergedRouteAncestry) {
+    if (mergedRouteAncestry) {
       const routeToStaticPrefix = {};
       for (const { manifest } of allManifests) {
         for (const name of Object.keys(manifest.routeManifest)) {
@@ -4578,31 +5460,16 @@ async function discoverRouters(state, rscEnv) {
         newMergedRouteManifest,
         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
+        mergedRouteTrailingSlash,
+        prerenderRouteNames,
+        passthroughRouteNames,
+        mergedResponseTypeRoutes
       );
       for (const { id, manifest } of allManifests) {
-        if (!manifest._routeAncestry || Object.keys(manifest._routeAncestry).length === 0)
-          continue;
-        const perRouterStaticPrefix = {};
-        for (const name of Object.keys(manifest.routeManifest)) {
-          perRouterStaticPrefix[name] = "";
+        const perRouterTrie = buildPerRouterTrie(manifest);
+        if (perRouterTrie) {
+          newPerRouterTrieMap.set(id, perRouterTrie);
         }
-        buildRouteToStaticPrefix(manifest.prefixTree, perRouterStaticPrefix);
-        const perRouterPrerenderNames = manifest.prerenderRoutes ? new Set(manifest.prerenderRoutes) : void 0;
-        const perRouterPassthroughNames = manifest.passthroughRoutes ? new Set(manifest.passthroughRoutes) : void 0;
-        const perRouterTrie = buildRouteTrie(
-          manifest.routeManifest,
-          manifest._routeAncestry,
-          perRouterStaticPrefix,
-          manifest.routeTrailingSlash && Object.keys(manifest.routeTrailingSlash).length > 0 ? manifest.routeTrailingSlash : void 0,
-          perRouterPrerenderNames && perRouterPrerenderNames.size > 0 ? perRouterPrerenderNames : void 0,
-          perRouterPassthroughNames && perRouterPassthroughNames.size > 0 ? perRouterPassthroughNames : void 0,
-          manifest.responseTypeRoutes && Object.keys(manifest.responseTypeRoutes).length > 0 ? manifest.responseTypeRoutes : void 0
-        );
-        newPerRouterTrieMap.set(id, perRouterTrie);
       }
     }
   }
@@ -4623,7 +5490,7 @@ async function discoverRouters(state, rscEnv) {
 }
 
 // src/vite/discovery/route-types-writer.ts
-import { dirname as dirname3, basename, join as join2, resolve as resolve6 } from "node:path";
+import { dirname as dirname3, join as join3, resolve as resolve6 } from "node:path";
 import { readFileSync as readFileSync4, writeFileSync as writeFileSync3, existsSync as existsSync5, unlinkSync as unlinkSync2 } from "node:fs";
 function filterUserNamedRoutes(manifest) {
   const filtered = {};
@@ -4634,39 +5501,20 @@ function filterUserNamedRoutes(manifest) {
   }
   return filtered;
 }
+function writeGenFileIfChanged(state, outPath, source, opts) {
+  const existing = existsSync5(outPath) ? readFileSync4(outPath, "utf-8") : null;
+  if (existing === source) return;
+  markSelfGenWrite(state, outPath, source);
+  writeFileSync3(outPath, source);
+  if (opts?.log) console.log(`[rango] Generated route types -> ${outPath}`);
+}
 function writeCombinedRouteTypesWithTracking(state, opts) {
   const routerFiles = state.cachedRouterFiles ?? findRouterFiles(state.projectRoot, state.scanFilter);
   state.cachedRouterFiles = routerFiles;
-  const preContent = /* @__PURE__ */ new Map();
-  for (const routerFilePath of routerFiles) {
-    const routerDir = dirname3(routerFilePath);
-    const routerBasename = basename(routerFilePath).replace(
-      /\.(tsx?|jsx?)$/,
-      ""
-    );
-    const outPath = join2(routerDir, `${routerBasename}.named-routes.gen.ts`);
-    try {
-      preContent.set(outPath, readFileSync4(outPath, "utf-8"));
-    } catch {
-    }
-  }
-  writeCombinedRouteTypes(state.projectRoot, routerFiles, opts);
-  for (const routerFilePath of routerFiles) {
-    const routerDir = dirname3(routerFilePath);
-    const routerBasename = basename(routerFilePath).replace(
-      /\.(tsx?|jsx?)$/,
-      ""
-    );
-    const outPath = join2(routerDir, `${routerBasename}.named-routes.gen.ts`);
-    if (!existsSync5(outPath)) continue;
-    try {
-      const content = readFileSync4(outPath, "utf-8");
-      if (content !== preContent.get(outPath)) {
-        markSelfGenWrite(state, outPath, content);
-      }
-    } catch {
-    }
-  }
+  writeCombinedRouteTypes(state.projectRoot, routerFiles, {
+    ...opts,
+    onWrite: (outPath, content) => markSelfGenWrite(state, outPath, content)
+  });
 }
 function writeRouteTypesFiles(state) {
   if (state.perRouterManifests.length === 0) return;
@@ -4674,11 +5522,11 @@ function writeRouteTypesFiles(state) {
     const entryDir = dirname3(
       resolve6(state.projectRoot, state.resolvedEntryPath)
     );
-    const oldCombinedPath = join2(entryDir, "named-routes.gen.ts");
+    const oldCombinedPath = join3(entryDir, "named-routes.gen.ts");
     if (existsSync5(oldCombinedPath)) {
       unlinkSync2(oldCombinedPath);
       console.log(
-        `[rsc-router] Removed stale combined route types: ${oldCombinedPath}`
+        `[rango] Removed stale combined route types: ${oldCombinedPath}`
       );
     }
   } catch {
@@ -4692,39 +5540,23 @@ function writeRouteTypesFiles(state) {
     if (!sourceFile) continue;
     if (sourceFile.includes("node_modules")) {
       throw new Error(
-        `[rsc-router] Router "${id}" has sourceFile inside node_modules: ${sourceFile}
+        `[rango] Router "${id}" has sourceFile inside node_modules: ${sourceFile}
 This means createRouter() stack trace parsing matched a Vite internal frame.
 Set an explicit \`id\` on createRouter() or check the call site.`
       );
     }
-    const routerDir = dirname3(sourceFile);
-    const routerBasename = basename(sourceFile).replace(/\.(tsx?|jsx?)$/, "");
-    const outPath = join2(routerDir, `${routerBasename}.named-routes.gen.ts`);
+    const outPath = genFileTsPath(sourceFile);
     const userRoutes = filterUserNamedRoutes(routeManifest);
-    let effectiveSearchSchemas = routeSearchSchemas;
-    if ((!effectiveSearchSchemas || Object.keys(effectiveSearchSchemas).length === 0) && sourceFile) {
-      const staticParsed = buildCombinedRouteMapForRouterFile(sourceFile);
-      if (Object.keys(staticParsed.searchSchemas).length > 0) {
-        const filtered = {};
-        for (const name of Object.keys(userRoutes)) {
-          const schema = staticParsed.searchSchemas[name];
-          if (schema) filtered[name] = schema;
-        }
-        if (Object.keys(filtered).length > 0) {
-          effectiveSearchSchemas = filtered;
-        }
-      }
-    }
+    const effectiveSearchSchemas = resolveSearchSchemas(
+      Object.keys(userRoutes),
+      routeSearchSchemas,
+      sourceFile
+    );
     const source = generateRouteTypesSource(
       userRoutes,
       effectiveSearchSchemas && Object.keys(effectiveSearchSchemas).length > 0 ? effectiveSearchSchemas : void 0
     );
-    const existing = existsSync5(outPath) ? readFileSync4(outPath, "utf-8") : null;
-    if (existing !== source) {
-      markSelfGenWrite(state, outPath, source);
-      writeFileSync3(outPath, source);
-      console.log(`[rsc-router] Generated route types -> ${outPath}`);
-    }
+    writeGenFileIfChanged(state, outPath, source, { log: true });
   }
 }
 function supplementGenFilesWithRuntimeRoutes(state) {
@@ -4762,23 +5594,17 @@ function supplementGenFilesWithRuntimeRoutes(state) {
         }
       }
     }
-    const routerDir = dirname3(sourceFile);
-    const routerBasename = basename(sourceFile).replace(/\.(tsx?|jsx?)$/, "");
-    const outPath = join2(routerDir, `${routerBasename}.named-routes.gen.ts`);
+    const outPath = genFileTsPath(sourceFile);
     const source = generateRouteTypesSource(
       mergedRoutes,
       Object.keys(mergedSearchSchemas).length > 0 ? mergedSearchSchemas : void 0
     );
-    const existing = existsSync5(outPath) ? readFileSync4(outPath, "utf-8") : null;
-    if (existing !== source) {
-      markSelfGenWrite(state, outPath, source);
-      writeFileSync3(outPath, source);
-    }
+    writeGenFileIfChanged(state, outPath, source);
   }
 }
 
 // src/vite/discovery/virtual-module-codegen.ts
-import { dirname as dirname4, basename as basename2, join as join3 } from "node:path";
+import { dirname as dirname4, basename, join as join4 } from "node:path";
 function generateRoutesManifestModule(state) {
   const hasManifest = state.mergedRouteManifest && Object.keys(state.mergedRouteManifest).length > 0;
   if (hasManifest) {
@@ -4789,11 +5615,11 @@ function generateRoutesManifestModule(state) {
     for (const entry of state.perRouterManifests) {
       if (entry.sourceFile) {
         const routerDir = dirname4(entry.sourceFile);
-        const routerBasename = basename2(entry.sourceFile).replace(
+        const routerBasename = basename(entry.sourceFile).replace(
           /\.(tsx?|jsx?)$/,
           ""
         );
-        const genPath = join3(
+        const genPath = join4(
           routerDir,
           `${routerBasename}.named-routes.gen.js`
         ).replaceAll("\\", "/");
@@ -4810,7 +5636,7 @@ function generateRoutesManifestModule(state) {
       }
     }
     const lines = [
-      `import { setCachedManifest, setPrecomputedEntries, setRouteTrie, setRouterManifest, registerRouterManifestLoader, clearAllRouterData } from "@rangojs/router/server";`,
+      `import { setCachedManifest, setRouterManifest, registerRouterManifestLoader, clearAllRouterData } from "@rangojs/router/server";`,
       ...genFileImports,
       // Clear stale per-router cached data (manifest, trie, precomputed entries)
       // before re-populating. In Cloudflare dev mode, program reloads re-evaluate
@@ -4846,18 +5672,6 @@ function generateRoutesManifestModule(state) {
         );
       }
     }
-    if (state.isBuildMode) {
-      if (state.mergedPrecomputedEntries && state.mergedPrecomputedEntries.length > 0) {
-        lines.push(
-          `setPrecomputedEntries(${jsonParseExpression(state.mergedPrecomputedEntries)});`
-        );
-      }
-      if (state.mergedRouteTrie) {
-        lines.push(
-          `setRouteTrie(${jsonParseExpression(state.mergedRouteTrie)});`
-        );
-      }
-    }
     for (const routerId of state.perRouterManifestDataMap.keys()) {
       lines.push(
         `registerRouterManifestLoader(${JSON.stringify(routerId)}, () => import(${JSON.stringify(VIRTUAL_ROUTES_MANIFEST_ID + "/" + routerId)}));`
@@ -4886,11 +5700,11 @@ function generatePerRouterModule(state, routerId) {
   const lines = [];
   if (routerEntry?.sourceFile) {
     const routerDir = dirname4(routerEntry.sourceFile);
-    const routerBasename = basename2(routerEntry.sourceFile).replace(
+    const routerBasename = basename(routerEntry.sourceFile).replace(
       /\.(tsx?|jsx?)$/,
       ""
     );
-    const genPath = join3(
+    const genPath = join4(
       routerDir,
       `${routerBasename}.named-routes.gen.js`
     ).replaceAll("\\", "/");
@@ -4913,7 +5727,7 @@ function generatePerRouterModule(state, routerId) {
       `export const precomputedEntries = ${jsonParseExpression(entries)};`
     );
   }
-  return lines.join("\n") || "// empty router manifest";
+  return lines.join("\n") || "";
 }
 
 // src/vite/discovery/bundle-postprocess.ts
@@ -4957,12 +5771,12 @@ function postprocessBundle(state) {
           writeFileSync4(chunkPath, result.code);
           const savedKB = (result.savedBytes / 1024).toFixed(1);
           console.log(
-            `[rsc-router] Evicted ${target.label} (${savedKB} KB saved): ${info.fileName}`
+            `[rango] Evicted ${target.label} (${savedKB} KB saved): ${info.fileName}`
           );
         }
       } catch (replaceErr) {
         console.warn(
-          `[rsc-router] Failed to evict ${target.label}: ${replaceErr.message}`
+          `[rango] Failed to evict ${target.label}: ${replaceErr.message}`
         );
       }
     }
@@ -4984,7 +5798,7 @@ function postprocessBundle(state) {
           manifestMap[key] = `./assets/${assetFileName}`;
         }
         const manifestCode = [
-          `const m=JSON.parse('${JSON.stringify(manifestMap).replace(/'/g, "\\'")}');`,
+          `const m=${jsonParseExpression(manifestMap)};`,
           `export function loadPrerenderAsset(s){return import(s)}`,
           `export default m;`,
           ""
@@ -5000,11 +5814,11 @@ function postprocessBundle(state) {
         writeFileSync4(rscEntryPath, injection + rscCode);
         const totalKB = (totalBytes / 1024).toFixed(1);
         console.log(
-          `[rsc-router] Wrote prerender assets (${totalKB} KB total, ${Object.keys(state.prerenderManifestEntries).length} entries)`
+          `[rango] Wrote prerender assets (${totalKB} KB total, ${Object.keys(state.prerenderManifestEntries).length} entries)`
         );
       } catch (err) {
         throw new Error(
-          `[rsc-router] Failed to write prerender assets: ${err.message}`
+          `[rango] Failed to write prerender assets: ${err.message}`
         );
       }
     }
@@ -5038,22 +5852,147 @@ function postprocessBundle(state) {
         writeFileSync4(rscEntryPath, injection + rscCode);
         const totalKB = (totalBytes / 1024).toFixed(1);
         console.log(
-          `[rsc-router] Wrote static assets (${totalKB} KB total, ${Object.keys(state.staticManifestEntries).length} entries)`
+          `[rango] Wrote static assets (${totalKB} KB total, ${Object.keys(state.staticManifestEntries).length} entries)`
         );
       } catch (err) {
         throw new Error(
-          `[rsc-router] Failed to write static assets: ${err.message}`
+          `[rango] Failed to write static assets: ${err.message}`
         );
       }
     }
   }
 }
 
+// src/vite/discovery/gate-state.ts
+function createDiscoveryGate(s, debug11) {
+  let gatePending = false;
+  let gateResolver = () => {
+  };
+  let inProgress = false;
+  let queued = false;
+  let pendingEvents = false;
+  const beginGate = () => {
+    if (gatePending) return;
+    s.discoveryDone = new Promise((resolve10) => {
+      gateResolver = resolve10;
+    });
+    gatePending = true;
+  };
+  const resolveGate = () => {
+    if (!gatePending) return;
+    if (inProgress || queued || pendingEvents) {
+      debug11?.(
+        "hmr: resolveGate deferred \u2014 work in flight (inProgress=%s queued=%s pendingEvents=%s)",
+        inProgress,
+        queued,
+        pendingEvents
+      );
+      return;
+    }
+    gatePending = false;
+    debug11?.("hmr: discoveryDone resolved");
+    gateResolver();
+  };
+  const noteRouteEvent = () => {
+    pendingEvents = true;
+    beginGate();
+  };
+  const runRefreshCycle = async (work) => {
+    if (inProgress) {
+      queued = true;
+      debug11?.("hmr: rediscovery in flight \u2014 queued for a follow-up cycle");
+      return;
+    }
+    pendingEvents = false;
+    inProgress = true;
+    try {
+      await work();
+    } finally {
+      inProgress = false;
+      if (queued) {
+        queued = false;
+        debug11?.("hmr: consuming queued rediscovery");
+        runRefreshCycle(work).catch((err) => {
+          debug11?.(
+            "hmr: queued cycle rejected \u2014 releasing gate (%s)",
+            err instanceof Error ? err.message : String(err)
+          );
+          resolveGate();
+        });
+      } else if (pendingEvents) {
+        debug11?.(
+          "hmr: holding gate for pending events (debounce not yet fired)"
+        );
+      } else {
+        resolveGate();
+      }
+    }
+  };
+  return {
+    beginGate,
+    resolveGate,
+    noteRouteEvent,
+    runRefreshCycle,
+    state: () => ({ gatePending, inProgress, queued, pendingEvents })
+  };
+}
+
+// src/vite/utils/forward-user-plugins.ts
+function isDenied(name) {
+  return name.startsWith("vite:") || name === "rsc" || name.startsWith("rsc:") || name.startsWith("@rangojs/router") || name.startsWith("@cloudflare/vite-plugin") || name.startsWith("vite-plugin-cloudflare");
+}
+function hasResolutionHooks(p) {
+  return Boolean(p.resolveId || p.load);
+}
+function stripToResolutionHooks(p) {
+  const stripped = { name: p.name };
+  if (p.enforce) stripped.enforce = p.enforce;
+  if (p.applyToEnvironment)
+    stripped.applyToEnvironment = p.applyToEnvironment;
+  if (p.resolveId) stripped.resolveId = p.resolveId;
+  if (p.load) stripped.load = p.load;
+  return stripped;
+}
+function selectForwardableResolvePlugins(plugins) {
+  if (!plugins) return [];
+  const forwarded = [];
+  for (const p of plugins) {
+    const name = p?.name;
+    if (!name || isDenied(name)) continue;
+    if (!hasResolutionHooks(p)) continue;
+    forwarded.push(stripToResolutionHooks(p));
+  }
+  return forwarded;
+}
+function pickForwardedRunnerConfig(config) {
+  const r = config.resolve ?? {};
+  const resolve10 = {};
+  if (r.alias !== void 0) resolve10.alias = r.alias;
+  if (r.dedupe !== void 0) resolve10.dedupe = r.dedupe;
+  if (r.conditions !== void 0) resolve10.conditions = r.conditions;
+  if (r.mainFields !== void 0) resolve10.mainFields = r.mainFields;
+  if (r.extensions !== void 0) resolve10.extensions = r.extensions;
+  if (r.preserveSymlinks !== void 0)
+    resolve10.preserveSymlinks = r.preserveSymlinks;
+  if (r.tsconfigPaths !== void 0) resolve10.tsconfigPaths = r.tsconfigPaths;
+  const userOxc = config.oxc;
+  const userJsx = userOxc && typeof userOxc === "object" && typeof userOxc.jsx === "object" && userOxc.jsx !== null ? userOxc.jsx : {};
+  const oxc = userOxc && typeof userOxc === "object" ? {
+    ...userOxc,
+    jsx: { ...userJsx, runtime: "automatic", importSource: "react" }
+  } : { jsx: { runtime: "automatic", importSource: "react" } };
+  return {
+    resolve: resolve10,
+    define: config.define,
+    oxc
+  };
+}
+
 // src/vite/router-discovery.ts
-var debugDiscovery = createRangoDebugger("rango:discovery");
-var debugRoutes = createRangoDebugger("rango:routes");
-var debugBuild = createRangoDebugger("rango:build");
-var debugDev = createRangoDebugger("rango:dev");
+var debugDiscovery = createRangoDebugger(NS.discovery);
+var debugRoutes = createRangoDebugger(NS.routes);
+var debugBuild = createRangoDebugger(NS.build);
+var debugDev = createRangoDebugger(NS.dev);
 var loaderHookRegistered = false;
 function ensureCloudflareProtocolLoaderRegistered() {
   if (loaderHookRegistered) return;
@@ -5064,21 +6003,29 @@ function ensureCloudflareProtocolLoaderRegistered() {
     );
   } catch (err) {
     console.warn(
-      `[rsc-router] Could not register Node ESM loader hook for cloudflare:* imports (${err?.message ?? err}). Falling back to Vite transform only.`
+      `[rango] Could not register Node ESM loader hook for cloudflare:* imports (${err?.message ?? err}). Falling back to Vite transform only.`
     );
   }
 }
 async function createTempRscServer(state, options = {}) {
   ensureCloudflareProtocolLoaderRegistered();
   const { default: rsc } = await import("@vitejs/plugin-rsc");
+  const runnerConfig = state.userRunnerConfig;
+  const resolveConfig = runnerConfig?.resolve ?? {
+    alias: state.userResolveAlias
+  };
+  const oxcConfig = runnerConfig?.oxc ?? {
+    jsx: { runtime: "automatic", importSource: "react" }
+  };
   return createViteServer({
     root: state.projectRoot,
     configFile: false,
     server: { middlewareMode: true },
     appType: "custom",
     logLevel: "silent",
-    resolve: { alias: state.userResolveAlias },
-    esbuild: { jsx: "automatic", jsxImportSource: "react" },
+    resolve: resolveConfig,
+    ...runnerConfig?.define ? { define: runnerConfig.define } : {},
+    oxc: oxcConfig,
     ...options.cacheDir && { cacheDir: options.cacheDir },
     plugins: [
       rsc({
@@ -5096,7 +6043,11 @@ async function createTempRscServer(state, options = {}) {
       // Dev prerender must use dev-mode IDs (path-based) to match the workerd
       // runtime. forceBuild produces hashed IDs for production bundle consistency.
       exposeInternalIds(options.forceBuild ? { forceBuild: true } : void 0),
-      exposeRouterId()
+      exposeRouterId(),
+      // Forwarded user resolution plugins (e.g. vite-tsconfig-paths). Stripped
+      // to resolveId/load and placed last so framework resolution runs first;
+      // Vite re-sorts by `enforce`, so `enforce: "pre"` resolvers still lead.
+      ...state.userResolvePlugins
     ]
   });
 }
@@ -5105,7 +6056,7 @@ async function resolveBuildEnv(option, factoryCtx) {
   if (option === "auto") {
     if (factoryCtx.preset !== "cloudflare") {
       throw new Error(
-        '[rsc-router] buildEnv: "auto" is only supported with preset: "cloudflare". Use a factory function or plain object for other presets.'
+        '[rango] buildEnv: "auto" is only supported with preset: "cloudflare". Use a factory function or plain object for other presets.'
       );
     }
     try {
@@ -5121,7 +6072,7 @@ async function resolveBuildEnv(option, factoryCtx) {
       };
     } catch (err) {
       throw new Error(
-        `[rsc-router] buildEnv: "auto" requires wrangler to be installed.
+        `[rango] buildEnv: "auto" requires wrangler to be installed.
 Install it with: pnpm add -D wrangler
 ${err.message}`
       );
@@ -5152,7 +6103,7 @@ async function releaseBuildEnv(s) {
     try {
       await s.buildEnvDispose();
     } catch (err) {
-      console.warn(`[rsc-router] buildEnv dispose failed: ${err.message}`);
+      console.warn(`[rango] buildEnv dispose failed: ${err.message}`);
     }
     s.buildEnvDispose = null;
   }
@@ -5165,31 +6116,31 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
   let viteMode = "production";
   return {
     name: "@rangojs/router:discovery",
-    config() {
-      const config = {
-        define: {
-          __RANGO_DEBUG__: JSON.stringify(!!process.env.INTERNAL_RANGO_DEBUG)
-        }
-      };
-      return config;
+    // Make INTERNAL_RANGO_DEBUG reach the CLIENT debug logs by just setting the
+    // env var. See injectClientDebugFlag: bakes the resolved flag into the
+    // internal-debug module so FE debug no longer depends on Vite delivering the
+    // `__RANGO_DEBUG__` define to the client (which it does only as an injected
+    // global whose presence varies across consumer setups). Runs in dev and build.
+    transform(_code, id) {
+      return injectClientDebugFlag(id);
     },
     configResolved(config) {
       s.projectRoot = config.root;
+      s.scanFilter = opts?.discovery ? createScanFilter(s.projectRoot, opts.discovery) : void 0;
       s.isBuildMode = config.command === "build";
       viteCommand = config.command;
       viteMode = config.mode;
       s.userResolveAlias = config.resolve.alias;
+      s.userRunnerConfig = pickForwardedRunnerConfig(config);
+      s.userResolvePlugins = selectForwardableResolvePlugins(
+        config.plugins
+      );
       if (!s.resolvedEntryPath && opts?.routerPathRef?.path) {
         s.resolvedEntryPath = opts.routerPathRef.path;
       }
       if (!s.resolvedEntryPath) {
-        const rscEnvConfig = config.environments?.["rsc"];
-        const entries = rscEnvConfig?.optimizeDeps?.entries;
-        if (typeof entries === "string") {
-          s.resolvedEntryPath = entries;
-        } else if (Array.isArray(entries) && entries.length > 0) {
-          s.resolvedEntryPath = entries[0];
-        }
+        const entry = resolveRscEntryFromConfig(config);
+        if (entry) s.resolvedEntryPath = entry;
       }
       if (opts?.staticRouteTypesGeneration !== false) {
         s.cachedRouterFiles = findRouterFiles(s.projectRoot, s.scanFilter);
@@ -5213,6 +6164,9 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
       const discoveryPromise = new Promise((resolve10) => {
         resolveDiscovery = resolve10;
       });
+      const gate = createDiscoveryGate(s, debugDiscovery);
+      const beginDiscoveryGate = gate.beginGate;
+      const resolveDiscoveryGate = gate.resolveGate;
       const getDevServerOrigin = () => server.resolvedUrls?.local?.[0]?.replace(/\/$/, "") || `http://localhost:${server.config.server.port || 5173}`;
       let prerenderTempServer = null;
       let prerenderNodeRegistry = null;
@@ -5225,35 +6179,155 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
         releaseBuildEnv(s).catch(() => {
         });
       });
+      async function importEntryAndRegistry(tempRscEnv) {
+        const flagAlreadySet = !!globalThis.__rscRouterDiscoveryActive;
+        if (!flagAlreadySet) {
+          globalThis.__rscRouterDiscoveryActive = true;
+        }
+        try {
+          debugDiscovery?.(
+            "importEntryAndRegistry: importing entry (flag=%s)",
+            globalThis.__rscRouterDiscoveryActive ?? false
+          );
+          await tempRscEnv.runner.import(s.resolvedEntryPath);
+          debugDiscovery?.(
+            "importEntryAndRegistry: entry import OK, fetching RouterRegistry"
+          );
+          const serverMod = await tempRscEnv.runner.import(
+            "@rangojs/router/server"
+          );
+          prerenderNodeRegistry = serverMod.RouterRegistry;
+          debugDiscovery?.(
+            "importEntryAndRegistry: registry size=%d",
+            prerenderNodeRegistry?.size ?? 0
+          );
+        } finally {
+          if (!flagAlreadySet) {
+            delete globalThis.__rscRouterDiscoveryActive;
+            debugDiscovery?.(
+              "importEntryAndRegistry: cleared __rscRouterDiscoveryActive"
+            );
+          }
+        }
+      }
       async function getOrCreateTempServer() {
-        if (prerenderNodeRegistry) {
-          return prerenderTempServer.environments?.rsc ?? null;
+        if (prerenderTempServer) {
+          const existingEnv = prerenderTempServer.environments?.rsc;
+          if (existingEnv?.runner) {
+            if (prerenderNodeRegistry) {
+              debugDiscovery?.(
+                "getOrCreateTempServer: cached temp runner reused"
+              );
+              return existingEnv;
+            }
+            debugDiscovery?.(
+              "getOrCreateTempServer: server alive but registry missing \u2014 re-importing"
+            );
+            try {
+              await importEntryAndRegistry(existingEnv);
+              return existingEnv;
+            } catch (err) {
+              debugDiscovery?.(
+                "getOrCreateTempServer: reuse import failed (%s) \u2014 closing orphan and creating fresh",
+                err?.message ?? String(err)
+              );
+              await prerenderTempServer.close().catch(() => {
+              });
+              prerenderTempServer = null;
+              prerenderNodeRegistry = null;
+            }
+          } else {
+            debugDiscovery?.(
+              "getOrCreateTempServer: existing server has no rsc.runner \u2014 closing and recreating"
+            );
+            await prerenderTempServer.close().catch(() => {
+            });
+            prerenderTempServer = null;
+            prerenderNodeRegistry = null;
+          }
         }
+        debugDiscovery?.(
+          "getOrCreateTempServer: creating new temp server, entry=%s",
+          s.resolvedEntryPath ?? "(unset)"
+        );
         try {
           prerenderTempServer = await createTempRscServer(s, {
             cacheDir: "node_modules/.vite_prerender"
           });
           const tempRscEnv = prerenderTempServer.environments?.rsc;
           if (tempRscEnv?.runner) {
-            await tempRscEnv.runner.import(s.resolvedEntryPath);
-            const serverMod = await tempRscEnv.runner.import(
-              "@rangojs/router/server"
-            );
-            prerenderNodeRegistry = serverMod.RouterRegistry;
+            await importEntryAndRegistry(tempRscEnv);
             return tempRscEnv;
           }
+          debugDiscovery?.(
+            "getOrCreateTempServer: tempRscEnv.runner unavailable"
+          );
         } catch (err) {
-          console.warn(
-            `[rsc-router] Failed to create temp runner: ${err.message}`
+          debugDiscovery?.(
+            "getOrCreateTempServer: FAILED message=%s",
+            err.message
           );
+          console.warn(`[rango] Failed to create temp runner: ${err.message}`);
         }
         return null;
       }
+      async function clearTempRegistries(tempRscEnv) {
+        try {
+          const serverMod = await tempRscEnv.runner.import(
+            "@rangojs/router/server"
+          );
+          if (typeof serverMod?.RouterRegistry?.clear === "function") {
+            serverMod.RouterRegistry.clear();
+          }
+          if (typeof serverMod?.HostRouterRegistry?.clear === "function") {
+            serverMod.HostRouterRegistry.clear();
+          }
+          debugDiscovery?.(
+            "clearTempRegistries: cleared RouterRegistry + HostRouterRegistry"
+          );
+        } catch (err) {
+          debugDiscovery?.(
+            "clearTempRegistries: import @rangojs/router/server failed (%s)",
+            err?.message ?? String(err)
+          );
+        }
+      }
+      async function refreshTempRscEnv() {
+        let tempRscEnv = await getOrCreateTempServer();
+        if (!tempRscEnv) return null;
+        const envGraph = tempRscEnv.moduleGraph;
+        const serverGraph = prerenderTempServer?.moduleGraph;
+        const target = envGraph?.invalidateAll ? envGraph : serverGraph?.invalidateAll ? serverGraph : null;
+        if (!target) {
+          debugDiscovery?.(
+            "refreshTempRscEnv: invalidateAll unavailable on env+server graphs, falling back to close+recreate"
+          );
+          if (prerenderTempServer) {
+            await prerenderTempServer.close().catch(() => {
+            });
+            prerenderTempServer = null;
+            prerenderNodeRegistry = null;
+          }
+          return await getOrCreateTempServer();
+        }
+        debugDiscovery?.(
+          "refreshTempRscEnv: invalidating module graph (%s)",
+          envGraph?.invalidateAll ? "env" : "server"
+        );
+        target.invalidateAll();
+        prerenderNodeRegistry = null;
+        await clearTempRegistries(tempRscEnv);
+        await importEntryAndRegistry(tempRscEnv);
+        return tempRscEnv;
+      }
       const discover = async () => {
         const discoverStart = performance.now();
         const rscEnv = server.environments?.rsc;
         if (!rscEnv?.runner) {
-          debugDiscovery?.("dev: no rsc runner (cloudflare path)");
+          debugDiscovery?.(
+            "dev: cloudflare path start, __rscRouterDiscoveryActive=%s",
+            globalThis.__rscRouterDiscoveryActive ?? false
+          );
           s.devServerOrigin = getDevServerOrigin();
           try {
             await timed(
@@ -5280,7 +6354,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
             }
           } catch (err) {
             console.warn(
-              `[rsc-router] Cloudflare dev discovery failed: ${err.message}
+              `[rango] Cloudflare dev discovery failed: ${err.message}
 ${err.stack}`
             );
           }
@@ -5324,7 +6398,7 @@ ${err.stack}`
           );
         } catch (err) {
           console.warn(
-            `[rsc-router] Router discovery failed: ${err.message}
+            `[rango] Router discovery failed: ${err.message}
 ${err.stack}`
           );
         } finally {
@@ -5335,9 +6409,11 @@ ${err.stack}`
           resolveDiscovery();
         }
       };
-      s.discoveryDone = new Promise((resolve10) => {
-        setTimeout(() => discover().then(resolve10, resolve10), 0);
-      });
+      beginDiscoveryGate();
+      setTimeout(
+        () => discover().then(resolveDiscoveryGate, resolveDiscoveryGate),
+        0
+      );
       let mainRegistry = null;
       const propagateDiscoveryState = async (rscEnv) => {
         const serverMod = await rscEnv.runner.import("@rangojs/router/server");
@@ -5355,20 +6431,15 @@ ${err.stack}`
         if (s.mergedRouteTrie && serverMod.setRouteTrie) {
           serverMod.setRouteTrie(s.mergedRouteTrie);
         }
-        if (serverMod.setRouterManifest) {
-          for (const [routerId, manifest] of s.perRouterManifestDataMap) {
-            serverMod.setRouterManifest(routerId, manifest);
-          }
-        }
-        if (serverMod.setRouterTrie) {
-          for (const [routerId, trie] of s.perRouterTrieMap) {
-            serverMod.setRouterTrie(routerId, trie);
-          }
-        }
-        if (serverMod.setRouterPrecomputedEntries) {
-          for (const [routerId, entries] of s.perRouterPrecomputedMap) {
-            serverMod.setRouterPrecomputedEntries(routerId, entries);
-          }
+        const perRouterSetters = [
+          [s.perRouterManifestDataMap, "setRouterManifest"],
+          [s.perRouterTrieMap, "setRouterTrie"],
+          [s.perRouterPrecomputedMap, "setRouterPrecomputedEntries"]
+        ];
+        for (const [map, fn] of perRouterSetters) {
+          const setter = serverMod[fn];
+          if (typeof setter !== "function") continue;
+          for (const [routerId, value] of map) setter(routerId, value);
         }
       };
       server.middlewares.use("/__rsc_prerender", async (req, res) => {
@@ -5402,7 +6473,7 @@ ${err.stack}`
             registry = serverMod.RouterRegistry ?? null;
           } catch (err) {
             console.warn(
-              `[rsc-router] Dev prerender module refresh failed: ${err.message}`
+              `[rango] Dev prerender module refresh failed: ${err.message}`
             );
             res.statusCode = 500;
             res.end(`Prerender handler error: ${err.message}`);
@@ -5447,10 +6518,9 @@ ${err.stack}`
             if (wantIntercept && result.interceptSegments?.length) {
               payload = {
                 segments: [...result.segments, ...result.interceptSegments],
-                handles: {
-                  ...result.handles,
-                  ...result.interceptHandles || {}
-                }
+                // Pre-encoded MERGED handle string from the producer (handles are
+                // Flight-encoded so Promise/ReactNode values survive the wire).
+                handles: result.interceptHandles ?? ""
               };
             } else {
               payload = { segments: result.segments, handles: result.handles };
@@ -5459,9 +6529,11 @@ ${err.stack}`
             logResult(200, `match ${result.routeName}`);
             return;
           } catch (err) {
-            console.warn(
-              `[rsc-router] Dev prerender failed for ${pathname}: ${err.message}`
-            );
+            if (err?.name !== "Skip") {
+              console.warn(
+                `[rango] Dev prerender error for ${pathname} (serving live instead): ${err.message}`
+              );
+            }
           }
         }
         res.statusCode = 404;
@@ -5486,38 +6558,96 @@ ${err.stack}`
           return true;
         };
         let routeChangeTimer;
-        let runtimeRediscoveryInProgress = false;
         const refreshRuntimeDiscovery = async () => {
           const rscEnv = server.environments?.rsc;
-          if (!rscEnv?.runner || runtimeRediscoveryInProgress) return;
-          runtimeRediscoveryInProgress = true;
-          const hmrStart = performance.now();
+          const hasMainRunner = !!rscEnv?.runner;
+          if (!hasMainRunner && s.perRouterManifests.length === 0) return;
+          await gate.runRefreshCycle(async () => {
+            const hmrStart = performance.now();
+            try {
+              if (hasMainRunner) {
+                await timed(
+                  debugDiscovery,
+                  "hmr discoverRouters",
+                  () => discoverRouters(s, rscEnv)
+                );
+                timedSync(
+                  debugDiscovery,
+                  "hmr writeRouteTypesFiles",
+                  () => writeRouteTypesFiles(s)
+                );
+                await timed(
+                  debugDiscovery,
+                  "hmr propagateDiscoveryState",
+                  () => propagateDiscoveryState(rscEnv)
+                );
+              } else {
+                const tempRscEnv = await timed(
+                  debugDiscovery,
+                  "hmr refreshTempRscEnv (cloudflare)",
+                  () => refreshTempRscEnv()
+                );
+                if (!tempRscEnv) {
+                  throw new Error(
+                    "temp runner unavailable for cloudflare HMR rediscovery"
+                  );
+                }
+                await timed(
+                  debugDiscovery,
+                  "hmr discoverRouters (cloudflare)",
+                  () => discoverRouters(s, tempRscEnv)
+                );
+                timedSync(
+                  debugDiscovery,
+                  "hmr writeRouteTypesFiles",
+                  () => writeRouteTypesFiles(s)
+                );
+              }
+              if (s.lastDiscoveryError) {
+                debugDiscovery?.(
+                  "hmr: cleared lastDiscoveryError (%s) after successful rediscovery",
+                  s.lastDiscoveryError.message
+                );
+                s.lastDiscoveryError = null;
+              }
+              if (rscEnv && !rscEnv.runner) forceCloudflareWorkerReload(rscEnv);
+            } catch (err) {
+              s.lastDiscoveryError = {
+                message: err?.message ?? String(err),
+                at: Date.now()
+              };
+              console.warn(
+                `[rango] Runtime re-discovery failed: ${err.message}`
+              );
+              debugDiscovery?.(
+                "hmr: lastDiscoveryError set (%s) \u2014 manifest preserved at last-good; recovery mode active (any in-scan source change will trigger rediscovery)",
+                err?.message
+              );
+            } finally {
+              debugDiscovery?.(
+                "hmr re-discovery done (%sms)",
+                (performance.now() - hmrStart).toFixed(1)
+              );
+            }
+          });
+        };
+        const forceCloudflareWorkerReload = (rscEnv) => {
+          if (!rscEnv?.hot) return;
           try {
-            await timed(
-              debugDiscovery,
-              "hmr discoverRouters",
-              () => discoverRouters(s, rscEnv)
-            );
-            timedSync(
-              debugDiscovery,
-              "hmr writeRouteTypesFiles",
-              () => writeRouteTypesFiles(s)
-            );
-            await timed(
-              debugDiscovery,
-              "hmr propagateDiscoveryState",
-              () => propagateDiscoveryState(rscEnv)
+            const graph = rscEnv.moduleGraph;
+            if (graph?.invalidateAll) {
+              graph.invalidateAll();
+              debugDiscovery?.("hmr: invalidated workerd rsc module graph");
+            }
+            rscEnv.hot.send({ type: "full-reload" });
+            debugDiscovery?.(
+              "hmr: forced workerd rsc env reload (full-reload)"
             );
           } catch (err) {
-            console.warn(
-              `[rsc-router] Runtime re-discovery failed: ${err.message}`
-            );
-          } finally {
             debugDiscovery?.(
-              "hmr re-discovery done (%sms)",
-              (performance.now() - hmrStart).toFixed(1)
+              "hmr: workerd reload failed: %s",
+              err?.message ?? err
             );
-            runtimeRediscoveryInProgress = false;
           }
         };
         const scheduleRouteRegeneration = () => {
@@ -5525,15 +6655,21 @@ ${err.stack}`
           routeChangeTimer = setTimeout(() => {
             routeChangeTimer = void 0;
             const regenStart = debugDiscovery ? performance.now() : 0;
+            const rscEnv = server.environments?.rsc;
+            const skipStaticWrite = !rscEnv?.runner && s.perRouterManifests.length > 0;
             try {
-              writeCombinedRouteTypesWithTracking(s);
-              if (s.perRouterManifests.length > 0) {
-                supplementGenFilesWithRuntimeRoutes(s);
+              if (skipStaticWrite) {
+                debugDiscovery?.(
+                  "watcher: skipping static write (cloudflare HMR \u2014 runtime rediscovery owns gen file)"
+                );
+              } else {
+                writeCombinedRouteTypesWithTracking(s);
+                if (s.perRouterManifests.length > 0) {
+                  supplementGenFilesWithRuntimeRoutes(s);
+                }
               }
             } catch (err) {
-              console.error(
-                `[rsc-router] Route regeneration error: ${err.message}`
-              );
+              console.error(`[rango] Route regeneration error: ${err.message}`);
             }
             debugDiscovery?.(
               "watcher: regenerated gen files (%sms)",
@@ -5542,31 +6678,65 @@ ${err.stack}`
             if (s.perRouterManifests.length > 0) {
               refreshRuntimeDiscovery().catch((err) => {
                 console.warn(
-                  `[rsc-router] Runtime re-discovery error: ${err.message}`
+                  `[rango] Runtime re-discovery error: ${err.message}`
                 );
+                resolveDiscoveryGate();
               });
             }
           }, 100);
         };
         const handleRouteFileChange = (filePath) => {
           if (maybeHandleGeneratedRouteFileMutation(filePath)) return;
-          if (!filePath.endsWith(".ts") && !filePath.endsWith(".tsx") && !filePath.endsWith(".js") && !filePath.endsWith(".jsx"))
+          if (!filePath.endsWith(".ts") && !filePath.endsWith(".tsx") && !filePath.endsWith(".js") && !filePath.endsWith(".jsx")) {
+            if (s.lastDiscoveryError) {
+              debugDiscovery?.(
+                "watcher: skip non-source %s [LASTERR %s]",
+                filePath,
+                s.lastDiscoveryError.message
+              );
+            }
+            return;
+          }
+          if (s.scanFilter && !s.scanFilter(filePath)) {
+            if (s.lastDiscoveryError) {
+              debugDiscovery?.(
+                "watcher: skip scan-filter %s [LASTERR %s]",
+                filePath,
+                s.lastDiscoveryError.message
+              );
+            }
             return;
-          if (s.scanFilter && !s.scanFilter(filePath)) return;
+          }
+          const inRecoveryMode = !!s.lastDiscoveryError;
           try {
             const source = readFileSync6(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;
-            debugDiscovery?.(
-              "watcher: %s matches (urls=%s, router=%s)",
-              filePath,
-              hasUrls,
-              hasCreateRouter
-            );
+            const isUseClient = trimmed.startsWith('"use client"') || trimmed.startsWith("'use client'");
+            if (!inRecoveryMode && isUseClient) return;
+            let hasUrls = source.includes("urls(");
+            let hasCreateRouter = /\bcreateRouter\s*[<(]/.test(source);
+            if (hasUrls) hasUrls = firstCodeMatchIndex(source, /urls\(/g) >= 0;
+            if (hasCreateRouter) {
+              hasCreateRouter = firstCodeMatchIndex(source, /\bcreateRouter\s*[<(]/g) >= 0;
+            }
+            if (!inRecoveryMode && !hasUrls && !hasCreateRouter) return;
+            if (inRecoveryMode) {
+              debugDiscovery?.(
+                "watcher: recovery rediscovery for %s (urls=%s, router=%s, useClient=%s) [LASTERR %s]",
+                filePath,
+                hasUrls,
+                hasCreateRouter,
+                isUseClient,
+                s.lastDiscoveryError.message
+              );
+            } else {
+              debugDiscovery?.(
+                "watcher: %s matches (urls=%s, router=%s)",
+                filePath,
+                hasUrls,
+                hasCreateRouter
+              );
+            }
             if (hasCreateRouter) {
               const nestedRouterConflict = findNestedRouterConflict([
                 ...s.cachedRouterFiles ?? [],
@@ -5580,8 +6750,19 @@ ${err.stack}`
               }
               s.cachedRouterFiles = void 0;
             }
+            if (s.perRouterManifests.length > 0) {
+              gate.noteRouteEvent();
+            }
             scheduleRouteRegeneration();
-          } catch {
+          } catch (readErr) {
+            if (s.lastDiscoveryError) {
+              debugDiscovery?.(
+                "watcher: read error %s: %s [LASTERR %s]",
+                filePath,
+                readErr?.message,
+                s.lastDiscoveryError.message
+              );
+            }
           }
         };
         server.watcher.on("add", handleRouteFileChange);
@@ -5627,7 +6808,7 @@ ${err.stack}`
         const rscEnv = tempServer.environments?.rsc;
         if (!rscEnv?.runner) {
           console.warn(
-            "[rsc-router] RSC environment runner not available during build, skipping manifest generation"
+            "[rango] RSC environment runner not available during build, skipping manifest generation"
           );
           return;
         }
@@ -5659,8 +6840,9 @@ ${err.stack}`
 ${err.stack}` : null
         ].filter(Boolean).join("\n");
         throw new Error(
-          `[rsc-router] Build-time router discovery failed:
-${details}`
+          `[rango] Build-time router discovery failed:
+${details}`,
+          { cause: err }
         );
       } finally {
         delete globalThis.__rscRouterDiscoveryActive;
@@ -5678,6 +6860,34 @@ ${details}`
         );
       }
     },
+    // Suppress vite's HMR cascade for our own gen-file writes.
+    //
+    // After every cf HMR cycle, refreshTempRscEnv → writeRouteTypesFiles
+    // writes the configured gen files (default `router.named-routes.gen.ts`,
+    // but the source filenames and gen suffix are user-configurable). The
+    // chokidar watcher then fires twice independently: our
+    // `handleRouteFileChange` (already short-circuited by
+    // `consumeSelfGenWrite` inside `maybeHandleGeneratedRouteFileMutation`),
+    // AND vite's own HMR pipeline (which invalidates the gen file's
+    // importers and triggers a second workerd full reload — visible to the
+    // user as a duplicate "[Rango] HMR: version changed" on the client).
+    //
+    // `peekSelfGenWrite` is the authoritative filter: its map only contains
+    // paths that `markSelfGenWrite` has registered, so it natively works
+    // for any configured gen-file name. It is non-consuming so the chokidar
+    // handler that fires later can still consume the same entry. Returning
+    // [] tells vite "no modules invalidated by this change" — safe because
+    // `s.perRouterManifests` is already up-to-date (the write that just
+    // happened is the consequence of our just-completed rediscovery).
+    handleHotUpdate(ctx) {
+      if (peekSelfGenWrite(s, ctx.file)) {
+        debugDiscovery?.(
+          "handleHotUpdate: suppressing self-write HMR cascade for %s",
+          ctx.file
+        );
+        return [];
+      }
+    },
     // Virtual module: provides the pre-generated route manifest as a JS module
     // that calls setCachedManifest() at import time.
     resolveId(id) {
@@ -5695,7 +6905,7 @@ ${details}`
           await timed(
             debugRoutes,
             "await discoveryDone (manifest)",
-            () => Promise.resolve(s.discoveryDone)
+            () => s.discoveryDone
           );
         }
         const code = await timed(
@@ -5712,7 +6922,7 @@ ${details}`
           await timed(
             debugRoutes,
             "await discoveryDone (per-router)",
-            () => Promise.resolve(s.discoveryDone)
+            () => s.discoveryDone
           );
         }
         const routerId = id.slice(perRouterPrefix.length);
@@ -5814,12 +7024,16 @@ ${details}`
 }
 
 // src/vite/rango.ts
-var debugConfig = createRangoDebugger("rango:config");
+var debugConfig = createRangoDebugger(NS.config);
 async function rango(options) {
   const rangoStart = performance.now();
   const resolvedOptions = options ?? { preset: "node" };
   const preset = resolvedOptions.preset ?? "node";
   const showBanner = resolvedOptions.banner ?? true;
+  const clientChunksOption = resolvedOptions.clientChunks ?? true;
+  const useBuiltInClientChunks = clientChunksOption === true;
+  const clientChunkCtx = useBuiltInClientChunks ? { fallbackRefs: /* @__PURE__ */ new Set() } : void 0;
+  const clientChunks = resolveClientChunks(clientChunksOption, clientChunkCtx);
   debugConfig?.("rango(%s) setup start", preset);
   const plugins = [];
   const rangoAliases = { ...getPackageAliases(), ...getVendorAliases() };
@@ -5851,14 +7065,20 @@ async function rango(options) {
       enforce: "pre",
       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
+            rolldownOptions: sharedRolldownOptions
           },
           resolve: {
-            alias: rangoAliases
+            alias: rangoAliases,
+            // Force a single React/React-DOM copy across all three RSC
+            // environments. RSC requires exactly one react/react-dom instance
+            // per environment runtime; consumer install topologies (pnpm
+            // strict layout, experimental React pins, third-party "use client"
+            // packages) can otherwise resolve duplicate copies, causing
+            // "Invalid hook call" / lost context. Child environments inherit
+            // this root dedupe, and Vite merges it with any consumer dedupe.
+            dedupe: ["react", "react-dom"]
           },
           build: {
             rollupOptions: { onwarn }
@@ -5867,30 +7087,22 @@ async function rango(options) {
             client: {
               build: {
                 rollupOptions: {
+                  onwarn,
                   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: [nested("rsc-html-stream/client")],
                 exclude: excludeDeps,
-                esbuildOptions: sharedEsbuildOptions
+                rolldownOptions: sharedRolldownOptions
               }
             },
             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: [
@@ -5906,14 +7118,11 @@ async function rango(options) {
                   )
                 ],
                 exclude: excludeDeps,
-                esbuildOptions: sharedEsbuildOptions
+                rolldownOptions: sharedRolldownOptions
               }
             },
             rsc: {
-              // RSC environment needs exclude list and esbuild options
-              // Exclude rsc-router modules to prevent createContext in RSC environment
               optimizeDeps: {
-                // Pre-bundle all RSC deps to prevent late discovery triggering ERR_OUTDATED_OPTIMIZED_DEP
                 include: [
                   "react",
                   "react/jsx-runtime",
@@ -5923,7 +7132,7 @@ async function rango(options) {
                   )
                 ],
                 exclude: excludeDeps,
-                esbuildOptions: sharedEsbuildOptions
+                rolldownOptions: sharedRolldownOptions
               }
             }
           }
@@ -5941,7 +7150,8 @@ async function rango(options) {
     plugins.push(
       rsc({
         entries: finalEntries,
-        serverHandler: false
+        serverHandler: false,
+        clientChunks
       })
     );
     plugins.push(clientRefDedup());
@@ -5959,7 +7169,7 @@ async function rango(options) {
           const list = candidates.map(
             (f) => "  - " + (f.startsWith(root) ? f.slice(root.length + 1) : f)
           ).join("\n");
-          throw new Error(`[rsc-router] Multiple routers found:
+          throw new Error(`[rango] Multiple routers found:
 ${list}`);
         }
       }
@@ -5978,18 +7188,27 @@ ${list}`);
         return {
           optimizeDeps: {
             exclude: excludeDeps,
-            esbuildOptions: sharedEsbuildOptions
+            rolldownOptions: sharedRolldownOptions
           },
           build: {
             rollupOptions: { onwarn }
           },
           resolve: {
-            alias: rangoAliases
+            alias: rangoAliases,
+            // Force a single React/React-DOM copy across all three RSC
+            // environments. RSC requires exactly one react/react-dom instance
+            // per environment runtime; consumer install topologies (pnpm
+            // strict layout, experimental React pins, third-party "use client"
+            // packages) can otherwise resolve duplicate copies, causing
+            // "Invalid hook call" / lost context. Child environments inherit
+            // this root dedupe, and Vite merges it with any consumer dedupe.
+            dedupe: ["react", "react-dom"]
           },
           environments: {
             client: {
               build: {
                 rollupOptions: {
+                  onwarn,
                   output: {
                     manualChunks: getManualChunks
                   }
@@ -6004,7 +7223,7 @@ ${list}`);
                   nested("rsc-html-stream/client")
                 ],
                 exclude: excludeDeps,
-                esbuildOptions: sharedEsbuildOptions,
+                rolldownOptions: sharedRolldownOptions,
                 entries: [VIRTUAL_IDS.browser]
               }
             },
@@ -6023,7 +7242,7 @@ ${list}`);
                   )
                 ],
                 exclude: excludeDeps,
-                esbuildOptions: sharedEsbuildOptions
+                rolldownOptions: sharedRolldownOptions
               }
             },
             rsc: {
@@ -6037,7 +7256,13 @@ ${list}`);
                     "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge"
                   )
                 ],
-                esbuildOptions: sharedEsbuildOptions
+                // Vite 8 does not propagate the top-level optimizeDeps.exclude
+                // (set in config()) to non-client envs, so the rsc env must set
+                // it explicitly — mirroring the node ssr env and the cloudflare
+                // rsc env. Without it a strict-pnpm npm-installed app can try to
+                // pre-bundle the router's own subpath entries and fail.
+                exclude: excludeDeps,
+                rolldownOptions: sharedRolldownOptions
               }
             }
           }
@@ -6054,7 +7279,7 @@ ${list}`);
         if (rscMinimalCount > 1 && !hasWarnedDuplicate) {
           hasWarnedDuplicate = true;
           console.warn(
-            "[rsc-router] Duplicate @vitejs/plugin-rsc detected. Remove rsc() from your vite config \u2014 rango() includes it automatically."
+            "[rango] Duplicate @vitejs/plugin-rsc detected. Remove rsc() from your vite config \u2014 rango() includes it automatically."
           );
         }
       }
@@ -6063,7 +7288,8 @@ ${list}`);
     plugins.push(performanceTracksPlugin());
     plugins.push(
       rsc({
-        entries: finalEntries
+        entries: finalEntries,
+        clientChunks
       })
     );
     plugins.push(clientRefDedup());
@@ -6078,8 +7304,7 @@ ${list}`);
         return;
       try {
         const source = readFileSync7(file, "utf-8");
-        const trimmed = source.trimStart();
-        if (trimmed.startsWith('"use client"') || trimmed.startsWith("'use client'")) {
+        if (hasUseClientDirective(source)) {
           return [];
         }
       } catch {
@@ -6102,7 +7327,10 @@ ${list}`);
       routerPathRef: discoveryRouterRef,
       enableBuildPrerender: prerenderEnabled,
       buildEnv: options?.buildEnv,
-      preset
+      preset,
+      prerenderOnError: options?.prerender?.onError,
+      discovery: options?.discovery,
+      clientChunkCtx
     })
   );
   debugConfig?.(
@@ -6117,7 +7345,7 @@ ${list}`);
 // src/vite/plugins/refresh-cmd.ts
 function poke() {
   return {
-    name: "vite-plugin-poke",
+    name: "@rangojs/router:poke",
     apply: "serve",
     configureServer(server) {
       const stdin = process.stdin;