@rangojs/router 0.22.1 → 0.24.0

package/dist/vite/index.js

@@ -119,10 +119,10 @@ __export(client_ref_hashing_exports, {
   hashRefKey: () => hashRefKey,
   transformClientRefs: () => transformClientRefs
 });
-import { relative as relative2 } from "node:path";
-import { createHash as createHash2 } from "node:crypto";
+import { relative as relative4 } from "node:path";
+import { createHash as createHash3 } from "node:crypto";
 function hashRefKey(relativeId) {
-  return createHash2("sha256").update(relativeId).digest("hex").slice(0, 12);
+  return createHash3("sha256").update(relativeId).digest("hex").slice(0, 12);
 }
 function computeProductionHash(projectRoot, refKey) {
   let toHash;
@@ -132,10 +132,10 @@ function computeProductionHash(projectRoot, refKey) {
     const absPath = decodeURIComponent(
       refKey.slice(CLIENT_IN_SERVER_PKG_PROXY_PREFIX.length)
     );
-    toHash = relative2(projectRoot, absPath).replaceAll("\\", "/");
+    toHash = relative4(projectRoot, absPath).replaceAll("\\", "/");
   } else if (refKey.startsWith(FS_PREFIX)) {
     const absPath = refKey.slice(FS_PREFIX.length - 1);
-    toHash = relative2(projectRoot, absPath).replaceAll("\\", "/");
+    toHash = relative4(projectRoot, absPath).replaceAll("\\", "/");
   } else if (refKey.startsWith("/")) {
     toHash = refKey.slice(1);
   } else {
@@ -733,6 +733,15 @@ var init_segment_fragments = __esm({
   }
 });
 
+// src/prefetch-markers.ts
+var PREFETCH_HEADER;
+var init_prefetch_markers = __esm({
+  "src/prefetch-markers.ts"() {
+    "use strict";
+    PREFETCH_HEADER = "X-Rango-Prefetch";
+  }
+});
+
 // src/browser/prefetch/fetch.ts
 function setPrefetchDecoder(fn) {
   decoder = fn;
@@ -826,7 +835,7 @@ function executePrefetchFetch(wildcardKey, sourceKey, fetchUrl, forceSourceScope
     headers: {
       "X-Rango-State": rangoState,
       "X-RSC-Router-Client-Path": window.location.href,
-      "X-Rango-Prefetch": "1",
+      [PREFETCH_HEADER]: "1",
       ...isFragmentPassthroughEnabled() && {
         [SEGMENT_FRAGMENT_CAPABILITY_HEADER]: "1"
       }
@@ -1006,6 +1015,7 @@ var init_fetch = __esm({
     init_logging();
     init_response_adapter();
     init_segment_fragments();
+    init_prefetch_markers();
     decoder = null;
     PREFETCH_FETCH_TIMEOUT_MS = 3e4;
   }
@@ -1633,10 +1643,10 @@ import path4 from "node:path";
 function isDirectivePrologueStatement(node) {
   return node?.type === "ExpressionStatement" && typeof node.directive === "string";
 }
-function findImportInsertionPos(code, parseAst8) {
+function findImportInsertionPos(code, parseAst9) {
   let program;
   try {
-    program = parseAst8(code, { lang: "tsx" });
+    program = parseAst9(code, { lang: "tsx" });
   } catch {
     return 0;
   }
@@ -1673,10 +1683,10 @@ function walkNode(node, parent, ancestors, enter) {
   }
   ancestors.pop();
 }
-function findHandlerCalls(code, fnName, parseAst8) {
+function findHandlerCalls(code, fnName, parseAst9) {
   let program;
   try {
-    program = parseAst8(code, { lang: "tsx" });
+    program = parseAst9(code, { lang: "tsx" });
   } catch {
     return [];
   }
@@ -1748,18 +1758,18 @@ function getImportedLocalNamesFromProgram(program, importedName) {
   }
   return localNames;
 }
-function getImportedLocalNames(code, importedName, parseAst8) {
+function getImportedLocalNames(code, importedName, parseAst9) {
   try {
-    const program = parseAst8(code, { lang: "tsx" });
+    const program = parseAst9(code, { lang: "tsx" });
     return getImportedLocalNamesFromProgram(program, importedName);
   } catch {
     return /* @__PURE__ */ new Set();
   }
 }
-function extractImportDeclarations(code, parseAst8) {
+function extractImportDeclarations(code, parseAst9) {
   let program;
   try {
-    program = parseAst8(code, { lang: "tsx" });
+    program = parseAst9(code, { lang: "tsx" });
   } catch {
     return [];
   }
@@ -1816,10 +1826,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, parseAst8, handlerNames) {
+function extractModuleLevelDeclarations(code, parseAst9, handlerNames) {
   let program;
   try {
-    program = parseAst8(code, { lang: "tsx" });
+    program = parseAst9(code, { lang: "tsx" });
   } catch {
     return [];
   }
@@ -1850,17 +1860,17 @@ function extractModuleLevelDeclarations(code, parseAst8, handlerNames) {
   }
   return declarations;
 }
-function transformInlineHandlers(fnName, virtualPrefix, s, code, filePath, virtualRegistry, moduleId, parseAst8) {
-  const sites = findHandlerCalls(code, fnName, parseAst8);
+function transformInlineHandlers(fnName, virtualPrefix, s, code, filePath, virtualRegistry, moduleId, parseAst9) {
+  const sites = findHandlerCalls(code, fnName, parseAst9);
   const inlineSites = sites.filter((site) => site.exportInfo === null);
   if (inlineSites.length === 0) return false;
-  const imports = extractImportDeclarations(code, parseAst8);
-  const staticNames = getImportedLocalNames(code, "Static", parseAst8);
-  const prerenderNames = getImportedLocalNames(code, "Prerender", parseAst8);
+  const imports = extractImportDeclarations(code, parseAst9);
+  const staticNames = getImportedLocalNames(code, "Static", parseAst9);
+  const prerenderNames = getImportedLocalNames(code, "Prerender", parseAst9);
   const handlerNames = /* @__PURE__ */ new Set([...staticNames, ...prerenderNames]);
   const declarations = extractModuleLevelDeclarations(
     code,
-    parseAst8,
+    parseAst9,
     handlerNames
   );
   const importStatements = [];
@@ -1883,7 +1893,7 @@ function transformInlineHandlers(fnName, virtualPrefix, s, code, filePath, virtu
   }
   if (importStatements.length > 0) {
     const importBlock = importStatements.join("\n") + "\n";
-    const insertionPos = findImportInsertionPos(code, parseAst8);
+    const insertionPos = findImportInsertionPos(code, parseAst9);
     if (insertionPos === 0) {
       s.prepend(importBlock);
     } else {
@@ -1893,6 +1903,70 @@ function transformInlineHandlers(fnName, virtualPrefix, s, code, filePath, virtu
   return true;
 }
 
+// src/build/route-types/scan-filter.ts
+import { isAbsolute, join, relative } from "node:path";
+import { readdirSync } from "node:fs";
+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;
+  };
+}
+function isUniversallySkippedScanDir(name) {
+  return name === "node_modules" || name === "dist" || name === "coverage" || name.startsWith(".");
+}
+function isInSkippedScanDir(root, absolutePath) {
+  const rel = relative(root, absolutePath);
+  if (isAbsolute(rel)) return false;
+  const dirs = rel.split(/[\\/]/).slice(0, -1);
+  if (dirs[0] === "..") return false;
+  return dirs.some(isUniversallySkippedScanDir);
+}
+function isSkippedSourceScanDir(name) {
+  return isUniversallySkippedScanDir(name) || name === "build";
+}
+function findTsFiles(dir, filter) {
+  const results = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch (err) {
+    console.warn(
+      `[rango] Failed to scan directory ${dir}: ${err.message}`
+    );
+    return results;
+  }
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (isSkippedSourceScanDir(entry.name)) continue;
+      results.push(...findTsFiles(fullPath, filter));
+    } else if ((entry.name.endsWith(".ts") || entry.name.endsWith(".tsx") || entry.name.endsWith(".js") || entry.name.endsWith(".jsx")) && !entry.name.includes(".gen.")) {
+      if (filter && !filter(fullPath)) continue;
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
 // src/vite/plugins/expose-ids/types.ts
 var PRERENDER_CONFIG = {
   fnName: "Prerender",
@@ -2433,6 +2507,15 @@ function compareStrings(a, b) {
 // src/vite/discovery/state.ts
 var VIRTUAL_ROUTES_MANIFEST_ID = "virtual:rsc-router/routes-manifest";
 var VIRTUAL_LOADER_MANIFEST_ID = "virtual:rsc-router/loader-manifest";
+function recordDiscoveryFailure(state, err) {
+  state.lastDiscoveryError = {
+    message: err?.message ?? String(err),
+    at: Date.now()
+  };
+}
+function canRefreshRuntimeDiscovery(state) {
+  return state.perRouterManifests.length > 0 || !!state.lastDiscoveryError;
+}
 function createDiscoveryState(entryPath, opts) {
   return {
     resolvedEntryPath: entryPath,
@@ -2733,7 +2816,6 @@ ${lazyImports.join(",\n")}
       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) {
         const results = [];
         try {
@@ -2741,7 +2823,7 @@ ${lazyImports.join(",\n")}
           for (const entry of entries) {
             const fullPath = path4.join(dir, entry.name);
             if (entry.isDirectory()) {
-              if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith(".")) {
+              if (!isSkippedSourceScanDir(entry.name)) {
                 results.push(...await scanDir(fullPath));
               }
             } else if (/\.(ts|tsx|js|jsx)$/.test(entry.name)) {
@@ -3201,18 +3283,18 @@ async function transformUseCache(code, id, options) {
       return;
     }
   }
-  const { hasDirective: hasDirective2, transformWrapExport, transformHoistInlineDirective } = rscTransforms;
+  const { hasDirective: hasDirective4, transformWrapExport, transformHoistInlineDirective } = rscTransforms;
   let ast;
   try {
-    const { parseAst: parseAst8 } = await import("vite");
-    ast = parseAst8(code, { lang: "tsx" });
+    const { parseAst: parseAst9 } = await import("vite");
+    ast = parseAst9(code, { lang: "tsx" });
   } catch {
     return;
   }
   stripNullDirectiveFields(ast);
   const filePath = normalizePath(path5.relative(options.root, id));
   const isLayoutOrTemplate = LAYOUT_TEMPLATE_PATTERN.test(id);
-  if (hasDirective2(ast.body, "use cache")) {
+  if (hasDirective4(ast.body, "use cache")) {
     return transformFileLevelUseCache(
       code,
       ast,
@@ -3221,7 +3303,7 @@ async function transformUseCache(code, id, options) {
       options.isBuild,
       isLayoutOrTemplate,
       transformWrapExport,
-      hasDirective2
+      hasDirective4
     );
   }
   const functionResult = transformFunctionLevelUseCache(
@@ -3235,7 +3317,7 @@ async function transformUseCache(code, id, options) {
   warnOnNearMissDirectives(ast, id, options.warn);
   if (functionResult) return functionResult;
 }
-async function transformFileLevelUseCache(code, ast, filePath, sourceId, isBuild, isLayoutOrTemplate, transformWrapExport, hasDirective2) {
+async function transformFileLevelUseCache(code, ast, filePath, sourceId, isBuild, isLayoutOrTemplate, transformWrapExport, hasDirective4) {
   const unconfirmedExports = [];
   const { exportNames, output } = transformWrapExport(code, ast, {
     runtime: (value, name) => {
@@ -3247,7 +3329,7 @@ async function transformFileLevelUseCache(code, ast, filePath, sourceId, isBuild
       if (name === "default" && isLayoutOrTemplate) return false;
       if (name.startsWith("$$hoist_")) return false;
       if (isHoistedServerReferenceRebind(meta.valueNode)) return false;
-      if (functionHasUseServerDirective(meta.valueNode, hasDirective2)) {
+      if (functionHasUseServerDirective(meta.valueNode, hasDirective4)) {
         return false;
       }
       if (meta.isFunction !== true) {
@@ -3264,8 +3346,8 @@ async function transformFileLevelUseCache(code, ast, filePath, sourceId, isBuild
     );
   }
   if (exportNames.length === 0) {
-    const { default: MagicString5 } = await import("magic-string");
-    const s = new MagicString5(code);
+    const { default: MagicString6 } = await import("magic-string");
+    const s = new MagicString6(code);
     const directive2 = findFileLevelDirective(ast);
     if (directive2) {
       s.overwrite(
@@ -3341,13 +3423,13 @@ function isHoistedServerReferenceRebind(valueNode) {
   const first = valueNode.arguments[0];
   return first !== void 0 && first.type === "Identifier" && first.name.startsWith("$$hoist_");
 }
-function functionHasUseServerDirective(valueNode, hasDirective2) {
+function functionHasUseServerDirective(valueNode, hasDirective4) {
   if (!valueNode || !("body" in valueNode)) return false;
   const { body } = valueNode;
   if (!body || Array.isArray(body) || body.type !== "BlockStatement") {
     return false;
   }
-  return hasDirective2(
+  return hasDirective4(
     body.body,
     "use server"
   );
@@ -3390,10 +3472,10 @@ function warnOnNearMissDirectives(ast, fileId, warn) {
 }
 
 // src/vite/plugins/transition-when-hoist.ts
-import { normalizePath as normalizePath2, parseAst as parseAst3 } from "vite";
+import { normalizePath as normalizePath3, parseAst as parseAst3 } from "vite";
 import MagicString4 from "magic-string";
 import { builtinModules } from "node:module";
-import { readFile } from "node:fs/promises";
+import { hasDirective as hasDirective2 } from "@vitejs/plugin-rsc/transforms";
 
 // src/route-name.ts
 var AUTO_GENERATED_ROUTE_PREFIX = "$path_";
@@ -3424,10 +3506,7 @@ function findTransitionWhenError(error) {
   return void 0;
 }
 
-// src/vite/plugins/transition-when-hoist.ts
-var TRANSITION_WHEN_QUERY = "rango-when";
-var EXPORT_NAME = "__rango_when";
-var LOCAL_PREFIX = "__rango_when_";
+// src/vite/plugins/hoist/scope.ts
 var Scope = class {
   constructor(parent, isFunction, node) {
     this.parent = parent;
@@ -3733,29 +3812,23 @@ function collectImports(program) {
   }
   return imports;
 }
-function hasUseClientDirective(program) {
+
+// src/vite/plugins/hoist/literal.ts
+function directivePrologueEnd(program) {
+  let end = 0;
   for (const statement of program.body) {
     if (statement.type !== "ExpressionStatement" || typeof statement.directive !== "string") {
-      return false;
+      break;
     }
-    if (statement.directive === "use client") return true;
+    end = statement.end;
   }
-  return false;
+  return end;
 }
-function lineColumn(code, offset) {
-  let line = 1;
-  let column = 1;
-  for (let i = 0; i < offset && i < code.length; i++) {
-    if (code[i] === "\n") {
-      line++;
-      column = 1;
-    } else {
-      column++;
-    }
-  }
-  return `${line}:${column}`;
+function parseLang(file) {
+  if (/\.[cm]?ts$/.test(file)) return "ts";
+  if (/\.[cm]?jsx?$/.test(file)) return "jsx";
+  return "tsx";
 }
-var ROUTER_SOURCE = "@rangojs/router";
 var EXPRESSION_WRAPPERS = /* @__PURE__ */ new Set([
   "TSAsExpression",
   "TSSatisfiesExpression",
@@ -3773,51 +3846,50 @@ function isFunctionLiteral(node) {
 function propertyKeyIs(prop, name) {
   return prop?.type === "Property" && !prop.computed && (prop.key.type === "Identifier" && prop.key.name === name || prop.key.type === "Literal" && prop.key.value === name);
 }
-function findWhenSites(program, scopeOf, moduleScope, imports) {
-  const sites = [];
+function findHelperCalls(program, scopeOf, moduleScope, imports, spec) {
+  const calls = [];
   const helpers = /* @__PURE__ */ new Map();
-  const routerExport = (callee, scope) => {
-    const routerImport = (id) => {
+  const sourceExport = (callee, scope) => {
+    const sourceImport = (id) => {
       if (id?.type !== "Identifier") return null;
       if (scope.lookup(id.name) !== moduleScope) return null;
       const binding = imports.get(id.name);
-      return binding?.source === ROUTER_SOURCE && !binding.typeOnly ? binding : null;
+      return binding && spec.sources.has(binding.source) && !binding.typeOnly ? binding : null;
     };
     if (callee.type === "Identifier") {
-      const imported = routerImport(callee)?.imported;
+      const imported = sourceImport(callee)?.imported;
       return imported && imported !== "*" && imported !== "default" ? imported : null;
     }
-    if (callee.type === "MemberExpression" && !callee.computed && callee.property.type === "Identifier" && routerImport(callee.object)?.imported === "*") {
+    if (callee.type === "MemberExpression" && !callee.computed && callee.property.type === "Identifier" && sourceImport(callee.object)?.imported === "*") {
       return callee.property.name;
     }
     return null;
   };
-  const registerUrlsCallback = (callback) => {
+  const registerBuilderCallback = (callback) => {
     const fnScope = scopeOf.get(callback);
     let param = callback.params[0];
     if (param?.type === "AssignmentPattern") param = param.left;
     if (!fnScope || !param) return;
-    const bindings = {
-      transitions: /* @__PURE__ */ new Set(),
-      objects: /* @__PURE__ */ new Set()
-    };
+    const bindings = { names: /* @__PURE__ */ new Set(), objects: /* @__PURE__ */ new Set() };
     if (param.type === "Identifier") bindings.objects.add(param.name);
     if (param.type === "ObjectPattern") {
       for (const prop of param.properties) {
-        if (!propertyKeyIs(prop, "transition")) continue;
+        if (!propertyKeyIs(prop, spec.helper)) continue;
         const target = prop.value.type === "AssignmentPattern" ? prop.value.left : prop.value;
-        if (target.type === "Identifier") bindings.transitions.add(target.name);
+        if (target.type === "Identifier") bindings.names.add(target.name);
       }
     }
     helpers.set(fnScope, bindings);
   };
-  const isRouterTransition = (callee, scope) => {
-    if (routerExport(callee, scope) === "transition") return true;
+  const isHelper = (callee, scope) => {
+    if (spec.directImport && sourceExport(callee, scope) === spec.helper) {
+      return true;
+    }
     if (callee.type === "Identifier") {
       const decl = scope.lookup(callee.name);
-      return !!decl && !!helpers.get(decl)?.transitions.has(callee.name);
+      return !!decl && !!helpers.get(decl)?.names.has(callee.name);
     }
-    if (callee.type === "MemberExpression" && !callee.computed && callee.property.type === "Identifier" && callee.property.name === "transition" && callee.object.type === "Identifier") {
+    if (callee.type === "MemberExpression" && !callee.computed && callee.property.type === "Identifier" && callee.property.name === spec.helper && callee.object.type === "Identifier") {
       const decl = scope.lookup(callee.object.name);
       return !!decl && !!helpers.get(decl)?.objects.has(callee.object.name);
     }
@@ -3833,20 +3905,10 @@ function findWhenSites(program, scopeOf, moduleScope, imports) {
     const own = scopeOf.get(node) ?? scope;
     if (node.type === "CallExpression") {
       const callback = node.arguments[0];
-      if (isFunctionLiteral(callback) && routerExport(node.callee, own) === "urls") {
-        registerUrlsCallback(callback);
-      }
-      if (node.arguments[0]?.type === "ObjectExpression" && isRouterTransition(node.callee, own)) {
-        for (const prop of node.arguments[0].properties) {
-          if (propertyKeyIs(prop, "when")) {
-            sites.push({
-              prop,
-              value: unwrapExpression(prop.value),
-              scope: own
-            });
-          }
-        }
+      if (isFunctionLiteral(callback) && sourceExport(node.callee, own) === spec.builder) {
+        registerBuilderCallback(callback);
       }
+      if (isHelper(node.callee, own)) calls.push({ call: node, scope: own });
     }
     for (const key of Object.keys(node)) {
       if (key === "type" || key === "start" || key === "end") continue;
@@ -3854,27 +3916,21 @@ function findWhenSites(program, scopeOf, moduleScope, imports) {
     }
   };
   visit(program.body, moduleScope);
-  return sites;
+  return calls;
 }
-var LEXICAL_CAPTURE = {
-  this: "`this` in an arrow is the enclosing server function's `this`.",
-  arguments: "`arguments` in an arrow is the enclosing server function's `arguments`.",
-  super: "`super` refers to the enclosing server object.",
-  "new.target": "`new.target` in an arrow is the enclosing server function's."
-};
-function findLexicalCapture(literal, references, code) {
+function findLexicalCapture(literal, references, code, messages) {
   const ownArguments = [];
   let found = null;
   const capture = (node, what) => {
     found = {
       node,
-      detail: `${LEXICAL_CAPTURE[what]} Read what you need from \`to.params\`/\`to.state\`, or export the predicate from a "use client" module.`
+      detail: `${messages.lexical[what]} ${messages.captureHint}`
     };
   };
   const loads = (node, expression, why) => {
     found = {
       node,
-      detail: `\`${expression}\` ${why} Import client-safe modules statically, or export the predicate from a "use client" module.`
+      detail: `\`${expression}\` ${why} ${messages.loadsHint}`
     };
   };
   const visit = (node, boundary) => {
@@ -3907,7 +3963,7 @@ function findLexicalCapture(literal, references, code) {
       }
       case "MetaProperty":
         if (node.meta.name === "import") {
-          loads(node, "import.meta", "is the server module's.");
+          loads(node, "import.meta", messages.importMetaWhy);
         } else if (!boundary) {
           capture(node, "new.target");
         }
@@ -3919,7 +3975,7 @@ function findLexicalCapture(literal, references, code) {
           loads(
             node,
             node.computed ? "import.meta[...]" : `import.meta.${node.property.name}`,
-            "is resolved against the server module; only `import.meta.env` is available to an inline predicate."
+            messages.importMetaMemberWhy
           );
           return;
         }
@@ -3928,7 +3984,7 @@ function findLexicalCapture(literal, references, code) {
         loads(
           node,
           `import(${code.slice(node.source.start, node.source.end)})`,
-          "loads a module at run time, which the build cannot check is client-safe."
+          messages.dynamicImportWhy
         );
         return;
     }
@@ -3953,32 +4009,150 @@ function findLexicalCapture(literal, references, code) {
   }
   return null;
 }
+function collectFreeReferences(literal, references, moduleScope, imports) {
+  const used = /* @__PURE__ */ new Map();
+  const bindings = [];
+  const globals = [];
+  for (const ref of references) {
+    if (ref.node.start < literal.start || ref.node.end > literal.end) continue;
+    const decl = ref.scope.lookup(ref.node.name);
+    if (!decl) {
+      if (!ref.typeOnly) globals.push(ref);
+      continue;
+    }
+    if (decl.node.start >= literal.start && decl.node.end <= literal.end && decl !== moduleScope) {
+      continue;
+    }
+    if (decl === moduleScope && imports.has(ref.node.name)) {
+      const valueUse = !ref.typeOnly && !imports.get(ref.node.name).typeOnly;
+      used.set(ref.node.name, (used.get(ref.node.name) ?? false) || valueUse);
+      continue;
+    }
+    if (ref.typeOnly) continue;
+    bindings.push(ref);
+  }
+  return { imports: used, bindings, globals };
+}
+async function emitImports(used, imports, checkValueImport) {
+  const bySource = /* @__PURE__ */ new Map();
+  for (const [local, valueUse] of used) {
+    const binding = imports.get(local);
+    if (valueUse) await checkValueImport(local, binding);
+    const lines = bySource.get(binding.source) ?? [];
+    const typePrefix = valueUse ? "" : "type ";
+    if (binding.imported === "*") {
+      lines.push(
+        `import ${typePrefix}* as ${local} from ${JSON.stringify(binding.source)};`
+      );
+    } else if (binding.imported === "default") {
+      lines.push(
+        `import ${typePrefix}${local} from ${JSON.stringify(binding.source)};`
+      );
+    } else {
+      const spec = binding.imported === local ? local : `${JSON.stringify(binding.imported)} as ${local}`;
+      lines.push(
+        `import ${typePrefix}{ ${spec} } from ${JSON.stringify(binding.source)};`
+      );
+    }
+    bySource.set(binding.source, lines);
+  }
+  return [...bySource.values()].flat();
+}
+
+// src/vite/plugins/hoist/source.ts
+import { readFile } from "node:fs/promises";
+import { normalizePath as normalizePath2 } from "vite";
+var SOURCE_FILE_RE = /\.[cm]?[jt]sx?$/;
+async function readSource(file) {
+  try {
+    return await readFile(file, "utf-8");
+  } catch {
+    return null;
+  }
+}
+async function resolveSourceTarget(ctx, source, importer, options) {
+  const resolved2 = await ctx.resolve(source, importer);
+  if (!resolved2 || resolved2.external) return null;
+  const target = resolved2.id.split("?", 1)[0];
+  if (target.startsWith("\0")) return null;
+  if (options.skipNodeModules && target.includes("/node_modules/")) {
+    return null;
+  }
+  return target;
+}
+async function recordEmitted(emitted, file, value) {
+  emitted.set(file, { disk: await readSource(file), value });
+}
+async function loadEmittedOrDisk(emitted, hoistedFile, rehoist) {
+  const disk = await readSource(hoistedFile);
+  const entry = emitted.get(normalizePath2(hoistedFile));
+  if (entry && (disk === null || entry.disk === disk)) return entry.value;
+  return disk === null ? void 0 : rehoist(disk);
+}
+
+// src/vite/plugins/transition-when-hoist.ts
+var TRANSITION_WHEN_QUERY = "rango-when";
+var EXPORT_NAME = "__rango_when";
+var LOCAL_PREFIX = "__rango_when_";
+var ROUTER_SOURCES = /* @__PURE__ */ new Set(["@rangojs/router"]);
+function findWhenSites(program, scopeOf, moduleScope, imports) {
+  const sites = [];
+  for (const { call, scope } of findHelperCalls(
+    program,
+    scopeOf,
+    moduleScope,
+    imports,
+    {
+      sources: ROUTER_SOURCES,
+      builder: "urls",
+      helper: "transition",
+      directImport: true
+    }
+  )) {
+    if (call.arguments[0]?.type !== "ObjectExpression") continue;
+    for (const prop of call.arguments[0].properties) {
+      if (propertyKeyIs(prop, "when")) {
+        sites.push({ prop, value: unwrapExpression(prop.value), scope });
+      }
+    }
+  }
+  return sites;
+}
+var WHEN_CAPTURE_MESSAGES = {
+  lexical: {
+    this: "`this` in an arrow is the enclosing server function's `this`.",
+    arguments: "`arguments` in an arrow is the enclosing server function's `arguments`.",
+    super: "`super` refers to the enclosing server object.",
+    "new.target": "`new.target` in an arrow is the enclosing server function's."
+  },
+  captureHint: 'Read what you need from `to.params`/`to.state`, or export the predicate from a "use client" module.',
+  loadsHint: 'Import client-safe modules statically, or export the predicate from a "use client" module.',
+  importMetaWhy: "is the server module's.",
+  importMetaMemberWhy: "is resolved against the server module; only `import.meta.env` is available to an inline predicate.",
+  dynamicImportWhy: "loads a module at run time, which the build cannot check is client-safe."
+};
 var NODE_BUILTINS = new Set(builtinModules);
 function isServerOnlySpecifier(source) {
   return source === "server-only" || source.startsWith("node:") || source.startsWith("cloudflare:") || NODE_BUILTINS.has(source);
 }
 var ROUTER_IMPORT_RE = /["']@rangojs\/router["']/;
 var WHEN_RE = /\bwhen\b/;
-function parseLang(file) {
-  if (/\.[cm]?ts$/.test(file)) return "ts";
-  if (/\.[cm]?jsx?$/.test(file)) return "jsx";
-  return "tsx";
-}
 function whenError(file, code, node, detail) {
+  const { line, column } = offsetToLineColumn(code, node.start);
   return new TransitionWhenError(
-    `[rango] transition({ when }) at ${file}:${lineColumn(code, node.start)}: \`when\` runs in the browser; ${detail}`
+    `[rango] transition({ when }) at ${file}:${line}:${column}: \`when\` runs in the browser; ${detail}`
   );
 }
 async function hoistTransitionWhens(code, id, deps = {}) {
   if (!ROUTER_IMPORT_RE.test(code) || !WHEN_RE.test(code)) return null;
-  const file = normalizePath2(id.split("?", 1)[0]);
+  const file = normalizePath3(id.split("?", 1)[0]);
   let program;
   try {
     program = parseAst3(code, { lang: parseLang(file) });
   } catch {
     return null;
   }
-  if (hasUseClientDirective(program)) return null;
+  if (hasDirective2(program.body, "use client")) return null;
   const { moduleScope, references, scopeOf } = analyzeScopes(program);
   const imports = collectImports(program);
   const sites = findWhenSites(program, scopeOf, moduleScope, imports);
@@ -4009,66 +4183,43 @@ async function hoistTransitionWhens(code, id, deps = {}) {
       continue;
     }
     if (!isFunctionLiteral(value)) continue;
-    const lexical = findLexicalCapture(value, references, code);
+    const lexical = findLexicalCapture(
+      value,
+      references,
+      code,
+      WHEN_CAPTURE_MESSAGES
+    );
     if (lexical) throw whenError(file, code, lexical.node, lexical.detail);
-    const used = /* @__PURE__ */ new Map();
-    for (const ref of references) {
-      if (ref.node.start < value.start || ref.node.end > value.end) continue;
-      const decl = ref.scope.lookup(ref.node.name);
-      if (!decl) continue;
-      if (decl.node.start >= value.start && decl.node.end <= value.end && decl !== moduleScope) {
-        continue;
-      }
-      if (decl === moduleScope && imports.has(ref.node.name)) {
-        const valueUse = !ref.typeOnly && !imports.get(ref.node.name).typeOnly;
-        used.set(ref.node.name, (used.get(ref.node.name) ?? false) || valueUse);
-        continue;
-      }
-      if (ref.typeOnly) continue;
+    const free = collectFreeReferences(value, references, moduleScope, imports);
+    const binding = free.bindings[0];
+    if (binding) {
       throw whenError(
         file,
         code,
-        ref.node,
-        `\`${ref.node.name}\` is a server-module binding. Read it from \`to.params\`/\`to.state\`, or export the predicate from a "use client" module.`
+        binding.node,
+        `\`${binding.node.name}\` is a server-module binding. Read it from \`to.params\`/\`to.state\`, or export the predicate from a "use client" module.`
       );
     }
-    const bySource = /* @__PURE__ */ new Map();
-    for (const [local2, valueUse] of used) {
-      const binding = imports.get(local2);
-      if (valueUse) {
-        if (isServerOnlySpecifier(binding.source) || await deps.isServerOnlyImport?.(binding.source)) {
+    const importLines = await emitImports(
+      free.imports,
+      imports,
+      async (local2, imported) => {
+        if (isServerOnlySpecifier(imported.source) || await deps.isServerOnlyImport?.(imported.source)) {
           throw whenError(
             file,
             code,
             value,
-            `\`${local2}\` is imported from "${binding.source}", a server-only module. Import only client-safe modules into an inline predicate, or export it from a "use client" module.`
+            `\`${local2}\` is imported from "${imported.source}", a server-only module. Import only client-safe modules into an inline predicate, or export it from a "use client" module.`
           );
         }
       }
-      const lines = bySource.get(binding.source) ?? [];
-      const typePrefix = valueUse ? "" : "type ";
-      if (binding.imported === "*") {
-        lines.push(
-          `import ${typePrefix}* as ${local2} from ${JSON.stringify(binding.source)};`
-        );
-      } else if (binding.imported === "default") {
-        lines.push(
-          `import ${typePrefix}${local2} from ${JSON.stringify(binding.source)};`
-        );
-      } else {
-        const spec = binding.imported === local2 ? local2 : `${JSON.stringify(binding.imported)} as ${local2}`;
-        lines.push(
-          `import ${typePrefix}{ ${spec} } from ${JSON.stringify(binding.source)};`
-        );
-      }
-      bySource.set(binding.source, lines);
-    }
+    );
     const source = prop.method ? `${value.async ? "async " : ""}function${value.generator ? "*" : ""} ` + code.slice(value.start, value.end) : code.slice(value.start, value.end);
     const index = modules.length;
     modules.push(
       [
         `"use client";`,
-        ...[...bySource.values()].flat(),
+        ...importLines,
         `export const ${EXPORT_NAME} = ${source};`,
         ""
       ].join("\n")
@@ -4086,13 +4237,7 @@ async function hoistTransitionWhens(code, id, deps = {}) {
     );
   }
   if (modules.length === 0) return null;
-  let insertAt = 0;
-  for (const statement of program.body) {
-    if (statement.type !== "ExpressionStatement" || typeof statement.directive !== "string") {
-      break;
-    }
-    insertAt = statement.end;
-  }
+  const insertAt = directivePrologueEnd(program);
   s.appendLeft(insertAt, `${insertAt ? "\n" : ""}${header.join("\n")}
 `);
   return {
@@ -4110,13 +4255,6 @@ function parseHoistedWhenId(id) {
   return { file: id.slice(0, q), index: Number(raw) };
 }
 var SERVER_ONLY_IMPORT_RE = /\bimport\s+["']server-only["']/;
-async function readSource(file) {
-  try {
-    return await readFile(file, "utf-8");
-  } catch {
-    return null;
-  }
-}
 function transitionWhenHoistPlugin() {
   const emitted = /* @__PURE__ */ new Map();
   return {
@@ -4125,10 +4263,11 @@ function transitionWhenHoistPlugin() {
     async load(id) {
       const hoisted = parseHoistedWhenId(id);
       if (!hoisted) return;
-      const file = normalizePath2(hoisted.file);
-      const disk = await readSource(hoisted.file);
-      const entry = emitted.get(file);
-      const modules = entry && (disk === null || entry.disk === disk) ? entry.modules : disk === null ? void 0 : (await hoistTransitionWhens(disk, hoisted.file))?.modules;
+      const modules = await loadEmittedOrDisk(
+        emitted,
+        hoisted.file,
+        async (disk) => (await hoistTransitionWhens(disk, hoisted.file))?.modules
+      );
       const module = modules?.[hoisted.index];
       if (module === void 0) {
         throw new TransitionWhenError(
@@ -4140,35 +4279,397 @@ function transitionWhenHoistPlugin() {
     async transform(code, id) {
       if (this.environment?.name !== "rsc") return;
       if (id.includes("/node_modules/") || parseHoistedWhenId(id)) return;
-      const file = normalizePath2(id.split("?", 1)[0]);
-      if (!/\.[cm]?[jt]sx?$/.test(file)) return;
+      const file = normalizePath3(id.split("?", 1)[0]);
+      if (!SOURCE_FILE_RE.test(file)) return;
       emitted.delete(file);
       const result = await hoistTransitionWhens(code, id, {
         isServerOnlyImport: async (source) => {
-          const resolved2 = await this.resolve(source, id);
-          if (!resolved2 || resolved2.external) return false;
-          const target = resolved2.id.split("?", 1)[0];
-          if (target.includes("/node_modules/") || target.startsWith("\0")) {
-            return false;
-          }
+          const target = await resolveSourceTarget(this, source, id, {
+            skipNodeModules: true
+          });
+          if (target === null) return false;
           const text = await readSource(target);
           return text !== null && SERVER_ONLY_IMPORT_RE.test(text);
         }
       });
       if (!result) return;
-      emitted.set(file, {
-        disk: await readSource(file),
-        modules: result.modules
-      });
+      await recordEmitted(emitted, file, result.modules);
       return { code: result.code, map: result.map };
     }
   };
 }
 
+// src/vite/plugins/client-urls-revalidate-hoist.ts
+import { normalizePath as normalizePath4, parseAst as parseAst5 } from "vite";
+import MagicString5 from "magic-string";
+import { createHash as createHash2 } from "node:crypto";
+import { relative as relative2 } from "node:path";
+import { hasDirective as hasDirective3 } from "@vitejs/plugin-rsc/transforms";
+
+// src/client-urls/hoisted-revalidate.ts
+var HOISTED_REVALIDATE_KEY = "$$rangoRevalidate";
+function isHoistedRevalidateRef(value) {
+  return typeof value === "object" && value !== null && typeof value[HOISTED_REVALIDATE_KEY] === "string";
+}
+
+// src/vite/utils/directive-prologue.ts
+import { parseAst as parseAst4 } from "vite";
+function hasUseClientDirective(source) {
+  let program;
+  try {
+    program = parseAst4(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/client-urls-revalidate-hoist.ts
+var CLIENT_URLS_REVALIDATE_QUERY = "rango-revalidate";
+var REGISTER = "__rango_registerClientUrlRevalidators";
+var CLIENT_SOURCES = /* @__PURE__ */ new Set(["@rangojs/router/client"]);
+var BROWSER_GLOBALS = /* @__PURE__ */ new Set([
+  "window",
+  "document",
+  "navigator",
+  "localStorage",
+  "sessionStorage",
+  "location",
+  "history"
+]);
+var NOT_A_FUNCTION = /* @__PURE__ */ new Set([
+  "ObjectExpression",
+  "ArrayExpression",
+  "Literal",
+  "TemplateLiteral",
+  "ClassExpression"
+]);
+var CAPTURE_MESSAGES = {
+  lexical: {
+    this: "`this` in an arrow is the enclosing function's `this`.",
+    arguments: "`arguments` in an arrow is the enclosing function's.",
+    super: "`super` refers to the enclosing object.",
+    "new.target": "`new.target` in an arrow is the enclosing function's."
+  },
+  captureHint: "Read what you need from the predicate's argument.",
+  loadsHint: "Import server-safe modules statically.",
+  importMetaWhy: `is the "use client" module's.`,
+  importMetaMemberWhy: 'is resolved against the "use client" module; only `import.meta.env` is available to a hoisted predicate.',
+  dynamicImportWhy: "loads a module at run time, which the build cannot check is server-safe."
+};
+var CLIENT_URLS_RE = /\bclientUrls\b/;
+var CLIENT_IMPORT_RE = /["']@rangojs\/router\/client["']/;
+var REVALIDATE_RE = /\brevalidate\b/;
+function mayHoist(code) {
+  return code.includes("use client") && CLIENT_URLS_RE.test(code) && CLIENT_IMPORT_RE.test(code) && REVALIDATE_RE.test(code);
+}
+function revalidateError(file, code, node, detail) {
+  const { line, column } = offsetToLineColumn(code, node.start);
+  return new Error(
+    `[rango] clientUrls() revalidate() at ${file}:${line}:${column}: revalidate() runs on the server; ${detail}`
+  );
+}
+var FINGERPRINT_SKIP = /* @__PURE__ */ new Set([
+  "type",
+  "start",
+  "end",
+  "loc",
+  "range",
+  "raw",
+  "extra",
+  "shorthand",
+  // TS-only flags (`let x!: T`), lost with the types.
+  "definite",
+  ...TYPE_KEYS
+]);
+function fingerprint(node) {
+  const out = [];
+  const visit = (value) => {
+    if (value === null || value === void 0) return;
+    if (Array.isArray(value)) {
+      out.push("[");
+      for (const item of value) visit(item);
+      out.push("]");
+      return;
+    }
+    if (typeof value !== "object") {
+      out.push(JSON.stringify(typeof value === "bigint" ? `${value}n` : value));
+      return;
+    }
+    let entry = value;
+    if (typeof entry.type === "string") {
+      entry = unwrapExpression(entry);
+      if (entry.type.startsWith("TS")) {
+        visit(entry.expression);
+        return;
+      }
+      out.push(entry.type, "(");
+      if (entry.type === "TemplateElement") {
+        out.push(JSON.stringify(entry.value.raw));
+      }
+    }
+    for (const key of Object.keys(entry)) {
+      if (FINGERPRINT_SKIP.has(key)) continue;
+      if (key === "optional" && entry.type === "Identifier") continue;
+      out.push(key);
+      visit(entry[key]);
+    }
+    if (typeof entry.type === "string") out.push(")");
+  };
+  visit(node);
+  return out.join(" ");
+}
+function keyOf(relativeFile, predicate) {
+  return createHash2("sha256").update(relativeFile).update("\0").update(fingerprint(predicate)).digest("hex").slice(0, 12);
+}
+async function hoistClientUrlsRevalidates(code, id, deps) {
+  if (!mayHoist(code)) return null;
+  const file = normalizePath4(id.split("?", 1)[0]);
+  let program;
+  try {
+    program = parseAst5(code, { lang: parseLang(file) });
+  } catch {
+    return null;
+  }
+  if (!hasDirective3(program.body, "use client")) return null;
+  const { moduleScope, references, scopeOf } = analyzeScopes(program);
+  const imports = collectImports(program);
+  const calls = findHelperCalls(program, scopeOf, moduleScope, imports, {
+    sources: CLIENT_SOURCES,
+    builder: "clientUrls",
+    helper: "revalidate",
+    directImport: false
+  });
+  if (calls.length === 0) return null;
+  const relativeFile = normalizePath4(relative2(deps.root, file));
+  const s = new MagicString5(code);
+  const used = /* @__PURE__ */ new Map();
+  const entries = /* @__PURE__ */ new Map();
+  for (const { call } of calls) {
+    const [arg, extra] = call.arguments;
+    if (!arg || extra || arg.type === "SpreadElement") {
+      throw revalidateError(
+        file,
+        code,
+        call,
+        "`revalidate()` takes exactly one predicate."
+      );
+    }
+    const value = unwrapExpression(arg);
+    if (NOT_A_FUNCTION.has(value.type)) {
+      throw revalidateError(
+        file,
+        code,
+        value,
+        "`revalidate()` expects a predicate function."
+      );
+    }
+    if (isFunctionLiteral(value) && (value.async || value.generator)) {
+      throw revalidateError(
+        file,
+        code,
+        value,
+        `a${value.async ? "n `async`" : " generator"} function returns ${value.async ? "a Promise" : "an iterator"}, which the router ignores: return a boolean, \`{ defaultShouldRevalidate }\`, or nothing.`
+      );
+    }
+    const lexical = findLexicalCapture(
+      value,
+      references,
+      code,
+      CAPTURE_MESSAGES
+    );
+    if (lexical)
+      throw revalidateError(file, code, lexical.node, lexical.detail);
+    const free = collectFreeReferences(value, references, moduleScope, imports);
+    const binding = free.bindings[0];
+    if (binding) {
+      const name = binding.node.name;
+      throw revalidateError(
+        file,
+        code,
+        binding.node,
+        binding.scope.lookup(name) === moduleScope ? `\`${name}\` is declared in this "use client" module. Move the predicate to its own module (without "use client") and import it, or write it inline.` : `\`${name}\` is a binding of the enclosing function. Read what you need from the predicate's argument (\`currentParams\`, \`nextUrl\`, \`context\`, \`actionResult\`, ...).`
+      );
+    }
+    const browserGlobal = free.globals.find(
+      (ref) => BROWSER_GLOBALS.has(ref.node.name)
+    );
+    if (browserGlobal) {
+      throw revalidateError(
+        file,
+        code,
+        browserGlobal.node,
+        `\`${browserGlobal.node.name}\` is a browser global. Put the input on the request (a cookie or a search param) and read it from the predicate's argument, or refresh the loader with useRefreshLoaders.`
+      );
+    }
+    const unchecked = [...free.imports].filter(
+      ([local, valueUse]) => valueUse && !used.get(local)
+    );
+    const clientOnly = await Promise.all(
+      unchecked.map(([local]) => isClientOnly(imports.get(local), deps))
+    );
+    const offender = unchecked.find((_, i) => clientOnly[i]);
+    if (offender) {
+      const [local] = offender;
+      throw revalidateError(
+        file,
+        code,
+        value,
+        `\`${local}\` is imported from "${imports.get(local).source}", a client-only module: on the server a "use client" module's exports are client references and cannot be called. Import the predicate's inputs from a module without "use client".`
+      );
+    }
+    for (const [local, valueUse] of free.imports) {
+      used.set(local, (used.get(local) ?? false) || valueUse);
+    }
+    const source = code.slice(value.start, value.end);
+    const key = keyOf(relativeFile, value);
+    entries.set(key, source);
+    s.overwrite(
+      arg.start,
+      arg.end,
+      `{ ${HOISTED_REVALIDATE_KEY}: ${JSON.stringify(key)} }`
+    );
+  }
+  const importLines = await emitImports(used, imports, () => {
+  });
+  const module = [
+    `import { registerClientUrlRevalidators as ${REGISTER} } from "@rangojs/router/server";`,
+    ...importLines,
+    `${REGISTER}({`,
+    ...[...entries].map(
+      ([key, source]) => `  ${JSON.stringify(key)}: ${source},`
+    ),
+    `});`,
+    ""
+  ].join("\n");
+  return {
+    code: s.toString(),
+    map: s.generateMap({ hires: true, source: file }),
+    module,
+    keys: [...entries.keys()]
+  };
+}
+async function isClientOnly(binding, deps) {
+  return binding.source === "client-only" || Boolean(await deps.isClientModule?.(binding.source));
+}
+function parseHoistedRevalidateId(id) {
+  const q = id.indexOf("?");
+  if (q === -1) return null;
+  const params = new URLSearchParams(id.slice(q + 1));
+  return params.has(CLIENT_URLS_REVALIDATE_QUERY) ? id.slice(0, q) : null;
+}
+var HOISTED_ID_RE = new RegExp(
+  `[?&]${CLIENT_URLS_REVALIDATE_QUERY}(?:[=&]|$)`
+);
+var SOURCE_ID_RE = /\.[cm]?[jt]sx?(?:\?|$)/;
+var NODE_MODULES_RE = /\/node_modules\//;
+function clientUrlsRevalidateHoistPlugin() {
+  const emitted = /* @__PURE__ */ new Map();
+  const clientModules = /* @__PURE__ */ new Map();
+  let root = process.cwd();
+  const isClientFile = (file) => {
+    let known = clientModules.get(file);
+    if (!known) {
+      known = readSource(file).then(
+        (text) => text !== null && text.includes("use client") && hasUseClientDirective(text)
+      );
+      clientModules.set(file, known);
+    }
+    return known;
+  };
+  return [
+    {
+      name: "@rangojs/router:client-urls-revalidate-hoist",
+      enforce: "pre",
+      configResolved(config) {
+        root = config.root;
+      },
+      buildStart() {
+        clientModules.clear();
+      },
+      watchChange(id) {
+        const file = normalizePath4(id);
+        clientModules.delete(file);
+        emitted.delete(file);
+      },
+      load: {
+        filter: { id: HOISTED_ID_RE },
+        async handler(id) {
+          const hoistedFile = parseHoistedRevalidateId(id);
+          if (hoistedFile === null) return;
+          const module = await loadEmittedOrDisk(
+            emitted,
+            hoistedFile,
+            async (disk) => (await hoistClientUrlsRevalidates(disk, hoistedFile, { root }))?.module
+          );
+          return module ?? "export {};\n";
+        }
+      },
+      transform: {
+        filter: {
+          id: {
+            include: SOURCE_ID_RE,
+            exclude: [NODE_MODULES_RE, HOISTED_ID_RE]
+          },
+          code: CLIENT_URLS_RE
+        },
+        async handler(code, id) {
+          if (id.includes("/node_modules/") || parseHoistedRevalidateId(id)) {
+            return;
+          }
+          const file = normalizePath4(id.split("?", 1)[0]);
+          if (!SOURCE_FILE_RE.test(file)) return;
+          const rsc = this.environment?.name === "rsc";
+          if (rsc) emitted.delete(file);
+          const result = await hoistClientUrlsRevalidates(code, id, {
+            root,
+            isClientModule: rsc ? async (source) => {
+              const target = await resolveSourceTarget(this, source, id, {
+                skipNodeModules: false
+              });
+              return target !== null && await isClientFile(target);
+            } : void 0
+          });
+          if (!result) return;
+          if (rsc) await recordEmitted(emitted, file, result.module);
+          return { code: result.code, map: result.map };
+        }
+      }
+    },
+    {
+      name: "@rangojs/router:client-urls-revalidate-register",
+      enforce: "post",
+      applyToEnvironment: (env) => env.name === "rsc",
+      transform: {
+        filter: { code: "registerClientReference" },
+        handler(code, id) {
+          if (parseHoistedRevalidateId(id)) return;
+          const file = normalizePath4(id.split("?", 1)[0]);
+          if (!emitted.has(file)) return;
+          const s = new MagicString5(code);
+          s.append(
+            `
+import ${JSON.stringify(`${file}?${CLIENT_URLS_REVALIDATE_QUERY}`)};
+`
+          );
+          return { code: s.toString(), map: s.generateMap({ hires: true }) };
+        }
+      }
+    }
+  ];
+}
+
 // src/vite/plugins/client-ref-dedup.ts
 init_debug();
 import { existsSync, readFileSync } from "node:fs";
-import { isAbsolute, join, normalize, relative } from "node:path";
+import { isAbsolute as isAbsolute2, join as join2, normalize, relative as relative3 } from "node:path";
 var debug4 = createRangoDebugger(NS.transform);
 var CLIENT_IN_SERVER_PROXY_PREFIX = "virtual:vite-rsc/client-in-server-package-proxy/";
 var DEDUP_PREFIX = "\0rango:dedup/";
@@ -4201,7 +4702,7 @@ function readPackageMetadata(source, cache3) {
   if (!root) return;
   const cached = cache3.get(root);
   if (cached !== void 0) return cached ?? void 0;
-  const packageJsonPath = join(root, "package.json");
+  const packageJsonPath = join2(root, "package.json");
   if (!existsSync(packageJsonPath)) {
     cache3.set(root, null);
     return;
@@ -4254,8 +4755,8 @@ function getPublicSpecifierCandidates(metadata, packageSpecifier, source) {
     return [];
   }
   const candidates = /* @__PURE__ */ new Set();
-  const sourceRelative = `./${relative(metadata.root, source).replaceAll("\\", "/")}`;
-  if (sourceRelative.startsWith("./../") || isAbsolute(sourceRelative.slice(2))) {
+  const sourceRelative = `./${relative3(metadata.root, source).replaceAll("\\", "/")}`;
+  if (sourceRelative.startsWith("./../") || isAbsolute2(sourceRelative.slice(2))) {
     return [];
   }
   for (const [exportKey, target] of Object.entries(metadata.exports)) {
@@ -4342,7 +4843,7 @@ function clientRefDedup() {
     configResolved(config) {
       const clientEnv = config.environments?.["client"];
       clientExclude = clientEnv?.optimizeDeps?.exclude ?? config.optimizeDeps?.exclude ?? [];
-      rootImporter = join(config.root, "index.html");
+      rootImporter = join2(config.root, "index.html");
       resolvePackage = config.createResolver({ scan: true });
     },
     buildEnd() {
@@ -4411,12 +4912,12 @@ function clientRefDedup() {
 }
 
 // src/vite/plugins/stable-rsc-output.ts
-import { parseAst as parseAst4 } from "vite";
+import { parseAst as parseAst6 } from "vite";
 
 // src/vite/discovery/build-versions.ts
-import { createHash as createHash3 } from "node:crypto";
+import { createHash as createHash4 } from "node:crypto";
 import { isBuiltin } from "node:module";
-import { posix, relative as relative3 } from "node:path";
+import { posix, relative as relative5 } from "node:path";
 
 // src/router-versions.ts
 var DEFAULT_ROUTER_VERSIONS_KEY = "*";
@@ -4990,7 +5491,7 @@ function resolveRouterMembers(server, client, routers) {
   return members;
 }
 function sha256(value) {
-  return createHash3("sha256").update(value).digest("hex");
+  return createHash4("sha256").update(value).digest("hex");
 }
 var baseName = posix.basename;
 function isAbsolutePath(path6) {
@@ -5011,7 +5512,7 @@ function portableModuleId(id, projectRoot) {
     return path6.slice(nodeModules + 1).replace(PNPM_PEER_SUFFIX, "$1");
   }
   if (isAbsolutePath(path6)) {
-    return relative3(projectRoot, path6).replaceAll("\\", "/");
+    return relative5(projectRoot, path6).replaceAll("\\", "/");
   }
   return withoutWorkingDirectory(path6).replace(
     /([?&][^=&]+=)([^&]+)/g,
@@ -5372,7 +5873,7 @@ function literalProperties(object) {
 function defaultExportProperties(code) {
   let program;
   try {
-    program = parseAst4(code);
+    program = parseAst6(code);
   } catch {
     return void 0;
   }
@@ -5428,7 +5929,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.22.1",
+  version: "0.24.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -5887,58 +6388,6 @@ declare global {
 `;
 }
 
-// src/build/route-types/scan-filter.ts
-import { join as join2, relative as relative4 } from "node:path";
-import { readdirSync } from "node:fs";
-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 = relative4(root, absolutePath);
-    if (excludeMatcher && excludeMatcher(rel)) return false;
-    if (includeMatcher) return includeMatcher(rel);
-    return true;
-  };
-}
-function findTsFiles(dir, filter) {
-  const results = [];
-  let entries;
-  try {
-    entries = readdirSync(dir, { withFileTypes: true });
-  } catch (err) {
-    console.warn(
-      `[rango] Failed to scan directory ${dir}: ${err.message}`
-    );
-    return results;
-  }
-  for (const entry of entries) {
-    const fullPath = join2(dir, entry.name);
-    if (entry.isDirectory()) {
-      if (entry.name === "node_modules" || entry.name.startsWith(".") || entry.name === "dist" || entry.name === "build" || entry.name === "coverage")
-        continue;
-      results.push(...findTsFiles(fullPath, filter));
-    } else if ((entry.name.endsWith(".ts") || entry.name.endsWith(".tsx") || entry.name.endsWith(".js") || entry.name.endsWith(".jsx")) && !entry.name.includes(".gen.")) {
-      if (filter && !filter(fullPath)) continue;
-      results.push(fullPath);
-    }
-  }
-  return results;
-}
-
 // src/build/route-types/per-module-writer.ts
 import ts4 from "typescript";
 
@@ -6513,7 +6962,7 @@ 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.");
 }
 function isExcludedScanDir(name) {
-  return name === "node_modules" || name === "dist" || name === "coverage" || name === "__tests__" || name === "__mocks__" || name.startsWith(".");
+  return isUniversallySkippedScanDir(name) || name === "__tests__" || name === "__mocks__";
 }
 function findCallSiteFilesRecursive(dir, pattern, patternG, stopAtMatchDir, filter, results) {
   let entries;
@@ -6896,28 +7345,7 @@ function writeCombinedRouteTypes(root, knownRouterFiles, opts) {
 }
 
 // src/vite/plugins/version-plugin.ts
-import { parseAst as parseAst6 } from "vite";
-
-// src/vite/utils/directive-prologue.ts
-import { parseAst as parseAst5 } from "vite";
-function hasUseClientDirective2(source) {
-  let program;
-  try {
-    program = parseAst5(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
+import { parseAst as parseAst7 } from "vite";
 function isCodeModule(id) {
   return /\.(tsx?|jsx?)($|\?)/.test(id);
 }
@@ -6925,10 +7353,10 @@ function normalizeModuleId(id) {
   return id.split("?", 1)[0];
 }
 function getClientModuleSignature(source) {
-  if (!hasUseClientDirective2(source)) return void 0;
+  if (!hasUseClientDirective(source)) return void 0;
   let program;
   try {
-    program = parseAst6(source, { lang: "tsx" });
+    program = parseAst7(source, { lang: "tsx" });
   } catch {
     return void 0;
   }
@@ -7103,7 +7531,7 @@ function isViteDepCachePath(filePath, cacheDir) {
 
 // src/vite/utils/shared-utils.ts
 import * as Vite from "vite";
-import { isAbsolute as isAbsolute2, resolve as resolve4 } from "node:path";
+import { isAbsolute as isAbsolute3, resolve as resolve4 } from "node:path";
 
 // src/vite/plugins/performance-tracks.ts
 init_debug();
@@ -7190,7 +7618,7 @@ var sharedRolldownOptions = {
 function normalizeHostRouterEntry(rawInput, root, exists) {
   const raw = rawInput.replaceAll("\\", "/");
   const isRelative = raw.startsWith("./") || raw.startsWith("../");
-  const isRooted = raw.startsWith("/") || isAbsolute2(rawInput);
+  const isRooted = raw.startsWith("/") || isAbsolute3(rawInput);
   if (isRooted) return raw;
   if (isRelative) {
     if (!exists(resolve4(root, raw))) {
@@ -7680,7 +8108,7 @@ function createCjsToEsmPlugin() {
 }
 
 // src/vite/router-discovery.ts
-import { createServer as createViteServer } from "vite";
+import { createServer as createViteServer, normalizePath as normalizePath8 } from "vite";
 import { dirname as dirname7, join as join10, resolve as resolve13 } from "node:path";
 import { existsSync as existsSync12, readFileSync as readFileSync11 } from "node:fs";
 import { createRequire as createRequire3, register } from "node:module";
@@ -8073,10 +8501,10 @@ function evictHandlerCode(code, exports, fnName, brand) {
 }
 
 // src/vite/discovery/self-gen-tracking.ts
-import { createHash as createHash4 } from "node:crypto";
+import { createHash as createHash5 } from "node:crypto";
 import { readFileSync as readFileSync4 } from "node:fs";
 function markSelfGenWrite(state, filePath, content) {
-  const hash = createHash4("sha256").update(content).digest("hex");
+  const hash = createHash5("sha256").update(content).digest("hex");
   state.selfWrittenGenFiles.set(filePath, { at: Date.now(), hash });
 }
 function consumeSelfGenWrite(state, filePath) {
@@ -8094,7 +8522,7 @@ function checkSelfGenWrite(state, filePath, consume) {
   }
   try {
     const current = readFileSync4(filePath, "utf-8");
-    const currentHash = createHash4("sha256").update(current).digest("hex");
+    const currentHash = createHash5("sha256").update(current).digest("hex");
     if (currentHash === info.hash) {
       if (consume) state.selfWrittenGenFiles.delete(filePath);
       return true;
@@ -8262,7 +8690,7 @@ function insertSegments(node, segments, index, leafBase, paramNames) {
   }
   const segment = segments[index];
   if (segment.type === "static") {
-    if (!node.s) node.s = {};
+    if (!node.s) node.s = /* @__PURE__ */ Object.create(null);
     if (!node.s[segment.value]) node.s[segment.value] = {};
     insertSegments(
       node.s[segment.value],
@@ -8562,6 +8990,13 @@ function jsonParseExpression(value) {
 }
 
 // src/context-var.ts
+function createVar(options) {
+  return {
+    __brand: "context-var",
+    key: /* @__PURE__ */ Symbol(),
+    cache: options?.cache !== false
+  };
+}
 function hasContextVars(variables) {
   return Object.keys(variables).length > 0 || Object.getOwnPropertySymbols(variables).length > 0;
 }
@@ -8574,7 +9009,11 @@ function getNonCacheableKeys(variables) {
   }
   return variables[NON_CACHEABLE_KEYS];
 }
-var FORBIDDEN_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+var FORBIDDEN_KEYS = /* @__PURE__ */ new Set([
+  "__proto__",
+  "constructor",
+  "prototype"
+]);
 function contextSet(variables, keyOrVar, value, options) {
   if (typeof keyOrVar === "string") {
     if (FORBIDDEN_KEYS.has(keyOrVar)) {
@@ -8595,7 +9034,7 @@ function contextSet(variables, keyOrVar, value, options) {
 }
 
 // src/vite/utils/prerender-utils.ts
-import { createHash as createHash5 } from "node:crypto";
+import { createHash as createHash6 } from "node:crypto";
 import {
   copyFileSync,
   existsSync as existsSync6,
@@ -8768,7 +9207,7 @@ function resetStagedBuildAssets(projectRoot) {
 }
 function writeBuildAssetModule(dir, prefix, exportValue) {
   mkdirSync(dir, { recursive: true });
-  const contentHash = createHash5("sha256").update(exportValue).digest("hex").slice(0, 8);
+  const contentHash = createHash6("sha256").update(exportValue).digest("hex").slice(0, 8);
   const fileName = `${prefix}-${contentHash}.js`;
   const filePath = resolve7(dir, fileName);
   if (!existsSync6(filePath)) {
@@ -9303,8 +9742,8 @@ init_client_ref_hashing();
 
 // src/vite/discovery/client-urls-projection.ts
 import { existsSync as existsSync7, readFileSync as readFileSync5 } from "node:fs";
-import { isAbsolute as isAbsolute3, relative as relative5, resolve as resolve8 } from "node:path";
-import { normalizePath as normalizePath5, parseAst as parseAst7 } from "vite";
+import { isAbsolute as isAbsolute4, relative as relative6, resolve as resolve8 } from "node:path";
+import { normalizePath as normalizePath7, parseAst as parseAst8 } from "vite";
 
 // src/client-urls/server-projection.ts
 import * as React5 from "react";
@@ -9614,7 +10053,7 @@ import { createContext as createContext4 } from "react";
 var OutletContext = createContext4(null);
 
 // src/route-content-wrapper.tsx
-import { Component, Suspense, use, useMemo as useMemo3 } from "react";
+import { Component, Suspense, use as use2, useMemo as useMemo3 } from "react";
 
 // src/outlet-provider.tsx
 import {
@@ -9662,10 +10101,27 @@ function getAppVersion() {
   return currentVersion2;
 }
 
+// src/router/basename.ts
+function prefixBasename(path6, basename2) {
+  if (!basename2 || !path6.startsWith("/") || path6 === basename2 || path6.startsWith(basename2 + "/") || path6.startsWith(basename2 + "?") || path6.startsWith(basename2 + "#")) {
+    return path6;
+  }
+  return path6 === "/" ? basename2 : basename2 + path6;
+}
+
 // src/loader-redirect.tsx
 init_validate_redirect_origin();
 init_redirect_origin();
 
+// src/browser/defer.ts
+import { use } from "react";
+
+// src/thenable-status.ts
+var SETTLED_THENABLE = Object.assign(
+  Promise.resolve(void 0),
+  { status: "fulfilled", value: void 0, _debugInfo: [] }
+);
+
 // src/route-content-wrapper.tsx
 import { jsx as jsx4 } from "react/jsx-runtime";
 import { createElement as createElement3 } from "react";
@@ -9674,7 +10130,7 @@ import { createElement as createElement3 } from "react";
 import {
   isValidElement,
   startTransition as startTransition2,
-  use as use2,
+  use as use3,
   useCallback,
   useContext as useContext7,
   useEffect as useEffect5,
@@ -9684,12 +10140,6 @@ import {
   useState as useState3
 } from "react";
 
-// src/thenable-status.ts
-var SETTLED_THENABLE = Object.assign(
-  Promise.resolve(void 0),
-  { status: "fulfilled", value: void 0, _debugInfo: [] }
-);
-
 // src/loader-store.ts
 var EMPTY_SNAPSHOT = Object.freeze({
   value: void 0,
@@ -9751,7 +10201,7 @@ import {
   useCallback as useCallback4,
   useMemo as useMemo7,
   useRef as useRef11,
-  use as use3,
+  use as use4,
   startTransition as startTransition5
 } from "react";
 
@@ -10068,13 +10518,10 @@ var Link = forwardRef(function Link2({
 }, ref) {
   const ctx = useContext15(NavigationStoreContext);
   const isExternal = isExternalUrl(to, ctx?.origin);
-  const resolvedTo = useMemo8(() => {
-    if (isExternal) return to;
-    const bn = ctx?.basename;
-    if (!bn || !to.startsWith("/") || to.startsWith(bn + "/") || to === bn)
-      return to;
-    return to === "/" ? bn : bn + to;
-  }, [to, isExternal, ctx?.basename]);
+  const resolvedTo = useMemo8(
+    () => isExternal ? to : prefixBasename(to, ctx?.basename),
+    [to, isExternal, ctx?.basename]
+  );
   const configuredStrategy = prefetch ?? ctx?.defaultPrefetch ?? ENVIRONMENT_DEFAULT_PREFETCH;
   const internalRef = useRef13(null);
   const setRef = useCallback5(
@@ -10331,6 +10778,19 @@ var ALL_USE_ITEM_TYPES = new Set(
 
 // src/server/request-context.ts
 import { AsyncLocalStorage as AsyncLocalStorage5 } from "node:async_hooks";
+
+// src/server/slot-accessors.ts
+function slotAccessor(slot, enumerable) {
+  return {
+    get() {
+      return this[slot]();
+    },
+    enumerable,
+    configurable: true
+  };
+}
+
+// src/server/request-context.ts
 init_cookie_name();
 
 // src/router/segment-resolution/mask-nested.ts
@@ -10395,12 +10855,41 @@ var THEME_READ = {
   }
 };
 
+// src/router/segment-resolution/prefetch-deferral.ts
+init_prefetch_markers();
+
+// src/cache/document-cache-policy.ts
+init_cookie_name();
+
+// src/server/rewrite-trail.ts
+var REWRITE_TRAIL = createVar();
+
 // src/cache/invalidation-order.ts
 var order = globalThis[/* @__PURE__ */ Symbol.for("rangojs-router:tag-invalidation-order")] ??= { seq: 0, tags: /* @__PURE__ */ new Map(), forgotten: 0 };
 var responseStarts = globalThis[/* @__PURE__ */ Symbol.for("rangojs-router:response-execution-start")] ??= /* @__PURE__ */ new WeakMap();
 
 // src/server/request-context.ts
 var requestContextStorage = new AsyncLocalStorage5();
+var RES_SLOT = /* @__PURE__ */ Symbol("rango.requestContext.res");
+var RENDER_BARRIER_SLOT = /* @__PURE__ */ Symbol(
+  "rango.requestContext.renderBarrier"
+);
+var RES_DESCRIPTOR = {
+  ...slotAccessor(RES_SLOT, true),
+  set(_) {
+    throw new Error(
+      "ctx.res is read-only. Use ctx.header() to set response headers, or cookies() for cookie mutations."
+    );
+  }
+};
+var RENDER_BARRIER_DESCRIPTOR = slotAccessor(
+  RENDER_BARRIER_SLOT,
+  true
+);
+var DERIVED_RENDER_BARRIER_DESCRIPTOR = {
+  ...RENDER_BARRIER_DESCRIPTOR,
+  enumerable: false
+};
 
 // src/route-definition/redirect.ts
 init_redirect_origin();
@@ -10542,7 +11031,10 @@ function serializeTransition(route2) {
   }
   return Object.freeze(config);
 }
-function serializeRoute(route2) {
+function indicesWhere(items, pred) {
+  return items.flatMap((item, index) => pred(item) ? [index] : []);
+}
+function serializeRoute(route2, options) {
   const loaderIds = route2.loaders.map(({ loader: loader2 }, index) => {
     if (typeof loader2.$$id !== "string" || loader2.$$id.length === 0) {
       throw projectionError(
@@ -10552,7 +11044,25 @@ function serializeRoute(route2) {
     }
     return loader2.$$id;
   });
-  const awaitedLoaderIndices = route2.loaders.map(({ ssr }, index) => ssr === false ? index : -1).filter((index) => index >= 0);
+  const loaderRevalidate = route2.loaders.map(
+    ({ loader: loader2, revalidate: revalidate2 }) => revalidate2.flatMap((entry) => {
+      if (isHoistedRevalidateRef(entry)) return [entry.$$rangoRevalidate];
+      if (options.hoisted) {
+        throw new Error(
+          `clientUrls() revalidate() on loader "${loader2.$$id}" of route "${route2.pattern}" was not hoisted to the server: call the builder's revalidate() helper with an inline function or an imported predicate.`
+        );
+      }
+      return [];
+    })
+  );
+  const awaitedLoaderIndices = indicesWhere(
+    route2.loaders,
+    ({ ssr }) => ssr === false
+  );
+  const deferrableLoaderIndices = indicesWhere(
+    route2.loaders,
+    ({ prefetch }) => prefetch === false
+  );
   const transition2 = serializeTransition(route2);
   return Object.freeze({
     id: route2.id,
@@ -10562,6 +11072,12 @@ function serializeRoute(route2) {
     loaderIds: Object.freeze(loaderIds),
     hasLoading: route2.loading !== void 0,
     ...awaitedLoaderIndices.length > 0 ? { awaitedLoaderIndices: Object.freeze(awaitedLoaderIndices) } : {},
+    ...deferrableLoaderIndices.length > 0 ? { deferrableLoaderIndices: Object.freeze(deferrableLoaderIndices) } : {},
+    ...loaderRevalidate.some((keys) => keys.length > 0) ? {
+      loaderRevalidate: Object.freeze(
+        loaderRevalidate.map((keys) => Object.freeze(keys))
+      )
+    } : {},
     ...transition2 ? { transition: transition2 } : {},
     ...typeof route2.transition?.when === "function" ? { transitionWhen: true } : {}
   });
@@ -10582,15 +11098,24 @@ function serializeIntercept(record, index) {
     hasLoading: record.loading !== void 0
   });
 }
-function serializeClientUrlPatterns(patterns) {
+function serializeClientUrlPatterns(patterns, options = {}) {
   return Object.freeze({
     version: 1,
-    routes: Object.freeze(patterns.routes.map(serializeRoute)),
+    routes: Object.freeze(
+      patterns.routes.map((route2) => serializeRoute(route2, options))
+    ),
     intercepts: Object.freeze(
       (patterns.intercepts ?? []).map(serializeIntercept)
     )
   });
 }
+function projectClientUrlsModule(namespace, options = {}) {
+  const definition = namespace.default;
+  if (typeof definition !== "object" && typeof definition !== "function" || definition === null || definition.__brand !== "client-urls") {
+    return void 0;
+  }
+  return serializeClientUrlPatterns(definition, options);
+}
 
 // src/vite/discovery/client-urls-projection.ts
 init_client_ref_hashing();
@@ -10599,7 +11124,7 @@ var debug10 = createRangoDebugger(NS.discovery);
 function hasDefaultExport(code) {
   let program;
   try {
-    program = parseAst7(code, { lang: "tsx" });
+    program = parseAst8(code, { lang: "tsx" });
   } catch {
     return false;
   }
@@ -10615,20 +11140,20 @@ function hasDefaultExport(code) {
 }
 function normalizeSource(state, id) {
   const cleanId = id.split("?", 1)[0];
-  const absoluteId = isAbsolute3(cleanId) ? cleanId : resolve8(state.projectRoot, cleanId);
-  return normalizePath5(absoluteId);
+  const absoluteId = isAbsolute4(cleanId) ? cleanId : resolve8(state.projectRoot, cleanId);
+  return normalizePath7(absoluteId);
 }
 function referenceId(referenceKey) {
   return `${referenceKey}#default`;
 }
 function recordClientUrlsModule(state, code, id) {
-  if (!code.includes("clientUrls(") || !hasUseClientDirective2(code) || !hasDefaultExport(code)) {
+  if (!code.includes("clientUrls(") || !hasUseClientDirective(code) || !hasDefaultExport(code)) {
     return;
   }
   const source = normalizeSource(state, id);
-  const projectRoot = normalizePath5(resolve8(state.projectRoot));
-  const relativeId = normalizePath5(relative5(projectRoot, source));
-  const outsideProject = relativeId === ".." || relativeId.startsWith("../") || isAbsolute3(relativeId);
+  const projectRoot = normalizePath7(resolve8(state.projectRoot));
+  const relativeId = normalizePath7(relative6(projectRoot, source));
+  const outsideProject = relativeId === ".." || relativeId.startsWith("../") || isAbsolute4(relativeId);
   const devReferenceKey = outsideProject ? `/@fs${source}` : `/${relativeId}`;
   const sourceByReferenceId = state.clientUrlSourceByReferenceId ??= /* @__PURE__ */ new Map();
   sourceByReferenceId.set(referenceId(devReferenceKey), source);
@@ -10672,18 +11197,19 @@ async function refreshRecordedClientUrlProjections(state, ssrEnv, serverMod) {
     }
   }
   for (const [source, referenceIds] of referenceIdsBySource) {
-    let definition;
+    let module;
     try {
-      definition = (await ssrEnv.runner.import(source)).default;
+      module = await ssrEnv.runner.import(source);
     } catch {
       continue;
     }
-    if (typeof definition !== "object" && typeof definition !== "function" || definition === null || definition.__brand !== "client-urls") {
+    let projection;
+    try {
+      projection = projectClientUrlsModule(module, { hoisted: true });
+    } catch {
       continue;
     }
-    const projection = serializeClientUrlPatterns(
-      definition
-    );
+    if (!projection) continue;
     debug10?.(
       "pre-entry refresh %s -> [%s]",
       source,
@@ -10738,17 +11264,24 @@ async function discoverClientUrlProjections(state, ssrEnv, serverMod) {
         cause
       );
     }
-    const definition = module.default;
-    if (typeof definition !== "object" && typeof definition !== "function" || definition === null || definition.__brand !== "client-urls") {
+    let projection;
+    try {
+      projection = projectClientUrlsModule(module, { hoisted: true });
+    } catch (cause) {
+      throw projectionError2(
+        referenceIds[0],
+        source,
+        cause instanceof Error ? cause.message : String(cause),
+        cause
+      );
+    }
+    if (!projection) {
       throw projectionError2(
         referenceIds[0],
         source,
         'the module default export must be created by clientUrls() and have __brand === "client-urls"'
       );
     }
-    const projection = serializeClientUrlPatterns(
-      definition
-    );
     for (const referenceId2 of referenceIds) {
       nextProjections.set(referenceId2, projection);
     }
@@ -10767,13 +11300,51 @@ async function discoverClientUrlProjections(state, ssrEnv, serverMod) {
 
 // src/vite/discovery/discover-routers.ts
 var debug11 = createRangoDebugger(NS.discovery);
+var SERVER_MODULE_ID = "@rangojs/router/server";
+var MAX_DISCOVERY_PASSES = 3;
+var RUNNER_RELOADED = /* @__PURE__ */ Symbol("rango.discovery.runnerReloaded");
+async function runnerReloadedSince(rscEnv, serverMod) {
+  try {
+    return await rscEnv.runner.import(SERVER_MODULE_ID) !== serverMod;
+  } catch {
+    return false;
+  }
+}
 async function discoverRouters(state, rscEnv, ssrEnv) {
-  if (!state.resolvedEntryPath) return;
-  const serverMod = await timed(
-    debug11,
-    "inner: import @rangojs/router/server",
-    () => rscEnv.runner.import("@rangojs/router/server")
-  );
+  const entryPath = state.resolvedEntryPath;
+  if (!entryPath) return;
+  for (let pass = 1; ; pass++) {
+    const serverMod = await timed(
+      debug11,
+      "inner: import @rangojs/router/server",
+      () => rscEnv.runner.import(SERVER_MODULE_ID)
+    );
+    let result;
+    try {
+      result = await discoverRoutersPass(
+        state,
+        rscEnv,
+        ssrEnv,
+        entryPath,
+        serverMod
+      );
+    } catch (error) {
+      if (!await runnerReloadedSince(rscEnv, serverMod)) throw error;
+      result = RUNNER_RELOADED;
+    }
+    if (result !== RUNNER_RELOADED) return result;
+    if (pass === MAX_DISCOVERY_PASSES) {
+      throw new Error(
+        `[rango] Route discovery did not settle: the RSC module runner reloaded during ${MAX_DISCOVERY_PASSES} consecutive discovery passes.`
+      );
+    }
+    debug11?.(
+      "inner: module runner reloaded mid-pass, redoing discovery (pass %d)",
+      pass + 1
+    );
+  }
+}
+async function discoverRoutersPass(state, rscEnv, ssrEnv, entryPath, serverMod) {
   await timed(
     debug11,
     "inner: refresh recorded client URL projections",
@@ -10782,9 +11353,10 @@ async function discoverRouters(state, rscEnv, ssrEnv) {
   await timed(
     debug11,
     "inner: import entry",
-    () => rscEnv.runner.import(state.resolvedEntryPath)
+    () => rscEnv.runner.import(entryPath)
   );
-  let registry = serverMod.RouterRegistry;
+  if (await runnerReloadedSince(rscEnv, serverMod)) return RUNNER_RELOADED;
+  const registry = serverMod.RouterRegistry;
   if (!registry || registry.size === 0) {
     const discoveryErrors = [];
     try {
@@ -10798,20 +11370,15 @@ async function discoverRouters(state, rscEnv, ssrEnv) {
         for (const { context, error } of handlerErrors) {
           debug11?.("caught error while resolving %s: %O", context, error);
         }
-        const freshServerMod = await rscEnv.runner.import(
-          "@rangojs/router/server"
-        );
-        const freshRegistry = freshServerMod.RouterRegistry;
-        if (freshRegistry && freshRegistry.size > 0) {
-          Object.assign(serverMod, freshServerMod);
-          registry = freshRegistry;
+        if (await runnerReloadedSince(rscEnv, serverMod)) {
+          return RUNNER_RELOADED;
         }
       }
     } catch (error) {
       discoveryErrors.push({ context: "host-router discovery", error });
     }
     if (!registry || registry.size === 0) {
-      throw new DiscoveryError(state.resolvedEntryPath, discoveryErrors);
+      throw new DiscoveryError(entryPath, discoveryErrors);
     }
   }
   await timed(
@@ -10960,6 +11527,7 @@ async function discoverRouters(state, rscEnv, ssrEnv) {
       }
     }
   }
+  if (await runnerReloadedSince(rscEnv, serverMod)) return RUNNER_RELOADED;
   state.mergedRouteManifest = newMergedRouteManifest;
   state.perRouterManifests = newPerRouterManifests;
   state.perRouterManifestDataMap = newPerRouterManifestDataMap;
@@ -10997,7 +11565,7 @@ import { dirname as dirname4, join as join6, resolve as resolve9 } from "node:pa
 init_debug();
 
 // src/vite/discovery/installed-packages.ts
-import { createHash as createHash6 } from "node:crypto";
+import { createHash as createHash7 } from "node:crypto";
 import {
   existsSync as existsSync8,
   readdirSync as readdirSync3,
@@ -11014,7 +11582,7 @@ function linkTarget(path6) {
   }
 }
 function digestDirectory(dir) {
-  const hash = createHash6("sha256");
+  const hash = createHash7("sha256");
   const entered = /* @__PURE__ */ new Set();
   const visit = (current, prefix) => {
     const real = realpathSync(current);
@@ -11727,6 +12295,17 @@ function devDiscoveryBootstrap(state) {
   const epoch = state.devDiscoveryEpoch;
   return [`globalThis.__RANGO_DEV_DISCOVERY_EPOCH = ${epoch};`];
 }
+function clientUrlProjectionReplay(state) {
+  const projections = [...state.clientUrlProjectionMap ?? []].sort(
+    ([a], [b]) => compareStrings(a, b)
+  );
+  return [
+    `clearClientUrlProjections();`,
+    ...projections.map(
+      ([referenceId2, projection]) => `setClientUrlProjection(${JSON.stringify(referenceId2)}, ${jsonParseExpression(projection)});`
+    )
+  ];
+}
 function generateRoutesManifestModule(state) {
   const hasManifest = state.mergedRouteManifest && Object.keys(state.mergedRouteManifest).length > 0;
   const hasClientUrlModules = Boolean(state.clientUrlSourceByReferenceId?.size);
@@ -11773,17 +12352,7 @@ function generateRoutesManifestModule(state) {
       `clearAllRouterData();`,
       TRANSITION_WHEN_VALIDATION
     ];
-    if (hasClientUrlModules) {
-      lines2.push(`clearClientUrlProjections();`);
-      const projections = [...state.clientUrlProjectionMap ?? []].sort(
-        ([a], [b]) => compareStrings(a, b)
-      );
-      for (const [referenceId2, projection] of projections) {
-        lines2.push(
-          `setClientUrlProjection(${JSON.stringify(referenceId2)}, ${jsonParseExpression(projection)});`
-        );
-      }
-    }
+    if (hasClientUrlModules) lines2.push(...clientUrlProjectionReplay(state));
     if (varIdx > 0) {
       lines2.push(
         `function __flat(r) { const o = {}; for (const [k, v] of Object.entries(r)) o[k] = typeof v === "string" ? v : v.path; return o; }`
@@ -11825,12 +12394,10 @@ function generateRoutesManifestModule(state) {
     return lines2.join("\n");
   }
   const lines = [
-    `import { ${hasClientUrlModules ? "clearClientUrlProjections, " : ""}enableTransitionWhenValidation } from "@rangojs/router/server";`,
+    `import { ${hasClientUrlModules ? "clearClientUrlProjections, setClientUrlProjection, " : ""}enableTransitionWhenValidation } from "@rangojs/router/server";`,
     TRANSITION_WHEN_VALIDATION
   ];
-  if (hasClientUrlModules) {
-    lines.push(`clearClientUrlProjections();`);
-  }
+  if (hasClientUrlModules) lines.push(...clientUrlProjectionReplay(state));
   if (!state.isBuildMode) {
     const origin = state.devServerOrigin || state.devServer?.resolvedUrls?.local?.[0]?.replace(/\/$/, "") || state.devServer && `http://localhost:${state.devServer.config.server.port || 5173}`;
     if (origin) {
@@ -12169,6 +12736,12 @@ var debugDiscovery = createRangoDebugger(NS.discovery);
 var debugRoutes = createRangoDebugger(NS.routes);
 var debugBuild = createRangoDebugger(NS.build);
 var debugDev = createRangoDebugger(NS.dev);
+function modulesForFile(graph, file) {
+  return graph.getModulesByFile(normalizePath8(file));
+}
+function isFileOutsideApp(root, file, rscGraph) {
+  return isInSkippedScanDir(root, file) && !(rscGraph && modulesForFile(rscGraph, file)?.size);
+}
 var loaderHookRegistered = false;
 function ensureCloudflareProtocolLoaderRegistered() {
   if (loaderHookRegistered) return;
@@ -12261,6 +12834,10 @@ async function createTempRscServer(state, options = {}) {
       // Inline transition({ when }) literals become client references here
       // too, or discovery would see (and reject) the plain function.
       transitionWhenHoistPlugin(),
+      // clientUrls() revalidate() predicates move to the server here too:
+      // discovery serializes the SSR copy's markers and the RSC realm
+      // registers the predicates the materialized stubs call.
+      ...clientUrlsRevalidateHoistPlugin(),
       // 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),
@@ -12697,12 +13274,18 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
               "acquireBuildEnv",
               () => acquireBuildEnv(s, viteCommand, viteMode)
             );
-            tempRscEnv = (await timed(
+            const temp = await timed(
               debugDiscovery,
               "getOrCreateTempServer",
               () => getOrCreateTempServer()
-            )).env;
-            if (tempRscEnv) {
+            );
+            tempRscEnv = temp.env;
+            if (!tempRscEnv) {
+              recordDiscoveryFailure(
+                s,
+                temp.error ?? "temp runner unavailable for discovery"
+              );
+            } else {
               optimizerHashBefore2 = tempRscEnv.depsOptimizer?.metadata?.browserHash;
               await timed(
                 debugDiscovery,
@@ -12720,6 +13303,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
               );
             }
           } catch (err) {
+            recordDiscoveryFailure(s, err);
             emitDiscoveryFailure(
               err,
               optimizerHashBefore2,
@@ -12761,6 +13345,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
             () => propagateDiscoveryState(rscEnv)
           );
         } catch (err) {
+          recordDiscoveryFailure(s, err);
           emitDiscoveryFailure(
             err,
             optimizerHashBefore,
@@ -13117,6 +13702,11 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
       });
       if (opts?.staticRouteTypesGeneration !== false) {
         const isGeneratedRouteFile = (filePath) => filePath.endsWith(".gen.ts") && (filePath.includes("named-routes.gen.ts") || filePath.includes("urls.gen.ts"));
+        const isOutsideApp = (filePath) => isFileOutsideApp(
+          s.projectRoot,
+          filePath,
+          server.environments?.rsc?.moduleGraph
+        );
         const regenerateGeneratedRouteFiles = () => {
           if (s.perRouterManifests.length > 0) {
             writeRouteTypesFiles(s);
@@ -13148,15 +13738,24 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
           return true;
         };
         let routeChangeTimer;
+        const invalidateRoutesManifestModule = (rscEnv) => {
+          for (const virtualId of [
+            VIRTUAL_ROUTES_MANIFEST_ID,
+            `\0${VIRTUAL_ROUTES_MANIFEST_ID}`
+          ]) {
+            const virtualMod = rscEnv.moduleGraph?.getModuleById?.(virtualId);
+            if (virtualMod) rscEnv.moduleGraph.invalidateModule(virtualMod);
+          }
+        };
         const refreshRuntimeDiscovery = async () => {
           const rscEnv = server.environments?.rsc;
           const hasMainRunner = !!rscEnv?.runner;
-          if (!hasMainRunner && s.perRouterManifests.length === 0) return;
           let previousRouteShape = routeShapeSignature();
           await gate.runRefreshCycle(async () => {
             const hmrStart = performance.now();
             try {
               if (hasMainRunner) {
+                const recoveringColdStart = s.perRouterManifests.length === 0;
                 await timed(
                   debugDiscovery,
                   "hmr discoverRouters",
@@ -13172,6 +13771,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
                   "hmr propagateDiscoveryState",
                   () => propagateDiscoveryState(rscEnv)
                 );
+                if (recoveringColdStart) invalidateRoutesManifestModule(rscEnv);
               } else {
                 const tempRscEnv = await timed(
                   debugDiscovery,
@@ -13220,10 +13820,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
                 forceCloudflareWorkerReload(rscEnv, expectedEpoch);
               }
             } catch (err) {
-              s.lastDiscoveryError = {
-                message: err?.message ?? String(err),
-                at: Date.now()
-              };
+              recordDiscoveryFailure(s, err);
               const whenError2 = showTransitionWhenError(err);
               if (whenError2) {
                 console.error(whenError2.message);
@@ -13317,15 +13914,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
                   server.environments?.ssr,
                   serverMod
                 );
-                for (const virtualId of [
-                  VIRTUAL_ROUTES_MANIFEST_ID,
-                  `\0${VIRTUAL_ROUTES_MANIFEST_ID}`
-                ]) {
-                  const virtualMod = rscEnv.moduleGraph?.getModuleById?.(virtualId);
-                  if (virtualMod) {
-                    rscEnv.moduleGraph.invalidateModule(virtualMod);
-                  }
-                }
+                invalidateRoutesManifestModule(rscEnv);
               } catch (err) {
                 debugDiscovery?.(
                   "watcher: clientUrls projection pre-refresh failed: %s",
@@ -13351,7 +13940,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
               "watcher: regenerated gen files (%sms)",
               (performance.now() - regenStart).toFixed(1)
             );
-            if (s.perRouterManifests.length > 0) {
+            if (canRefreshRuntimeDiscovery(s)) {
               refreshRuntimeDiscovery().catch((err) => {
                 console.warn(
                   `[rango] Runtime re-discovery error: ${err.message}`
@@ -13362,6 +13951,13 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
           }, 100);
         };
         const handleRouteFileChange = (filePath) => {
+          if (isOutsideApp(filePath)) {
+            debugDiscovery?.(
+              "watcher: skip %s (outside the discovery scan)",
+              filePath
+            );
+            return;
+          }
           if (maybeHandleGeneratedRouteFileMutation(filePath)) return;
           if (!filePath.endsWith(".ts") && !filePath.endsWith(".tsx") && !filePath.endsWith(".js") && !filePath.endsWith(".jsx")) {
             if (s.lastDiscoveryError) {
@@ -13436,9 +14032,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
                 }
                 const seen = /* @__PURE__ */ new Set();
                 for (const file of routerSourceFiles) {
-                  const mods = rscGraph.getModulesByFile(
-                    file.replaceAll("\\", "/")
-                  );
+                  const mods = modulesForFile(rscGraph, file);
                   if (!mods) {
                     debugDiscovery?.(
                       "watcher: clientUrls invalidation found no rsc modules for %s",
@@ -13470,7 +14064,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
               }
               s.cachedRouterFiles = void 0;
             }
-            if (s.perRouterManifests.length > 0) {
+            if (canRefreshRuntimeDiscovery(s)) {
               gate.noteRouteEvent();
             }
             scheduleRouteRegeneration();
@@ -13488,7 +14082,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
         server.watcher.on("add", handleRouteFileChange);
         server.watcher.on("change", handleRouteFileChange);
         server.watcher.on("unlink", (filePath) => {
-          if (!isGeneratedRouteFile(filePath)) return;
+          if (!isGeneratedRouteFile(filePath) || isOutsideApp(filePath)) return;
           const hasRunner = !!server.environments?.rsc?.runner;
           if (!hasRunner) return;
           regenerateGeneratedRouteFiles();
@@ -14166,7 +14760,7 @@ If this is a multi-app host router, export a createHostRouter() instance and set
         return;
       try {
         const source = readFileSync12(file, "utf-8");
-        if (hasUseClientDirective2(source)) {
+        if (hasUseClientDirective(source)) {
           return [];
         }
       } catch {
@@ -14175,6 +14769,7 @@ If this is a multi-app host router, export a createHostRouter() instance and set
   });
   plugins.push(createLoaderDirectiveGuardPlugin());
   plugins.push(transitionWhenHoistPlugin());
+  plugins.push(...clientUrlsRevalidateHoistPlugin());
   plugins.push(createLoaderScanStubPlugin());
   plugins.push(exposeActionId());
   plugins.push(