@rangojs/router 0.17.0 → 0.19.0

package/dist/vite/index.js

@@ -1587,10 +1587,10 @@ import path4 from "node:path";
 function isDirectivePrologueStatement(node) {
   return node?.type === "ExpressionStatement" && typeof node.directive === "string";
 }
-function findImportInsertionPos(code, parseAst6) {
+function findImportInsertionPos(code, parseAst7) {
   let program;
   try {
-    program = parseAst6(code, { lang: "tsx" });
+    program = parseAst7(code, { lang: "tsx" });
   } catch {
     return 0;
   }
@@ -1627,10 +1627,10 @@ function walkNode(node, parent, ancestors, enter) {
   }
   ancestors.pop();
 }
-function findHandlerCalls(code, fnName, parseAst6) {
+function findHandlerCalls(code, fnName, parseAst7) {
   let program;
   try {
-    program = parseAst6(code, { lang: "tsx" });
+    program = parseAst7(code, { lang: "tsx" });
   } catch {
     return [];
   }
@@ -1702,18 +1702,18 @@ function getImportedLocalNamesFromProgram(program, importedName) {
   }
   return localNames;
 }
-function getImportedLocalNames(code, importedName, parseAst6) {
+function getImportedLocalNames(code, importedName, parseAst7) {
   try {
-    const program = parseAst6(code, { lang: "tsx" });
+    const program = parseAst7(code, { lang: "tsx" });
     return getImportedLocalNamesFromProgram(program, importedName);
   } catch {
     return /* @__PURE__ */ new Set();
   }
 }
-function extractImportDeclarations(code, parseAst6) {
+function extractImportDeclarations(code, parseAst7) {
   let program;
   try {
-    program = parseAst6(code, { lang: "tsx" });
+    program = parseAst7(code, { lang: "tsx" });
   } catch {
     return [];
   }
@@ -1770,10 +1770,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, parseAst6, handlerNames) {
+function extractModuleLevelDeclarations(code, parseAst7, handlerNames) {
   let program;
   try {
-    program = parseAst6(code, { lang: "tsx" });
+    program = parseAst7(code, { lang: "tsx" });
   } catch {
     return [];
   }
@@ -1804,17 +1804,17 @@ function extractModuleLevelDeclarations(code, parseAst6, handlerNames) {
   }
   return declarations;
 }
-function transformInlineHandlers(fnName, virtualPrefix, s, code, filePath, virtualRegistry, moduleId, parseAst6) {
-  const sites = findHandlerCalls(code, fnName, parseAst6);
+function transformInlineHandlers(fnName, virtualPrefix, s, code, filePath, virtualRegistry, moduleId, parseAst7) {
+  const sites = findHandlerCalls(code, fnName, parseAst7);
   const inlineSites = sites.filter((site) => site.exportInfo === null);
   if (inlineSites.length === 0) return false;
-  const imports = extractImportDeclarations(code, parseAst6);
-  const staticNames = getImportedLocalNames(code, "Static", parseAst6);
-  const prerenderNames = getImportedLocalNames(code, "Prerender", parseAst6);
+  const imports = extractImportDeclarations(code, parseAst7);
+  const staticNames = getImportedLocalNames(code, "Static", parseAst7);
+  const prerenderNames = getImportedLocalNames(code, "Prerender", parseAst7);
   const handlerNames = /* @__PURE__ */ new Set([...staticNames, ...prerenderNames]);
   const declarations = extractModuleLevelDeclarations(
     code,
-    parseAst6,
+    parseAst7,
     handlerNames
   );
   const importStatements = [];
@@ -1837,7 +1837,7 @@ function transformInlineHandlers(fnName, virtualPrefix, s, code, filePath, virtu
   }
   if (importStatements.length > 0) {
     const importBlock = importStatements.join("\n") + "\n";
-    const insertionPos = findImportInsertionPos(code, parseAst6);
+    const insertionPos = findImportInsertionPos(code, parseAst7);
     if (insertionPos === 0) {
       s.prepend(importBlock);
     } else {
@@ -3103,8 +3103,8 @@ async function transformUseCache(code, id, options) {
   const { hasDirective: hasDirective2, transformWrapExport, transformHoistInlineDirective } = rscTransforms;
   let ast;
   try {
-    const { parseAst: parseAst6 } = await import("vite");
-    ast = parseAst6(code, { lang: "tsx" });
+    const { parseAst: parseAst7 } = await import("vite");
+    ast = parseAst7(code, { lang: "tsx" });
   } catch {
     return;
   }
@@ -3163,8 +3163,8 @@ async function transformFileLevelUseCache(code, ast, filePath, sourceId, isBuild
     );
   }
   if (exportNames.length === 0) {
-    const { default: MagicString4 } = await import("magic-string");
-    const s = new MagicString4(code);
+    const { default: MagicString5 } = await import("magic-string");
+    const s = new MagicString5(code);
     const directive2 = findFileLevelDirective(ast);
     if (directive2) {
       s.overwrite(
@@ -3288,6 +3288,782 @@ function warnOnNearMissDirectives(ast, fileId, warn) {
   }
 }
 
+// src/vite/plugins/transition-when-hoist.ts
+import { normalizePath as normalizePath2, parseAst as parseAst3 } from "vite";
+import MagicString4 from "magic-string";
+import { builtinModules } from "node:module";
+import { readFile } from "node:fs/promises";
+
+// src/route-name.ts
+var AUTO_GENERATED_ROUTE_PREFIX = "$path_";
+var INTERNAL_INCLUDE_SCOPE_PREFIX = "$prefix_";
+function isAutoGeneratedRouteName(name) {
+  return name.split(".").some((segment) => {
+    return segment.startsWith(AUTO_GENERATED_ROUTE_PREFIX) || segment.startsWith(INTERNAL_INCLUDE_SCOPE_PREFIX);
+  });
+}
+
+// src/transition-when-ref.ts
+var TransitionWhenError = class extends Error {
+  constructor() {
+    super(...arguments);
+    this.name = "TransitionWhenError";
+  }
+};
+function findTransitionWhenError(error) {
+  const seen = /* @__PURE__ */ new Set();
+  let current = error;
+  while (typeof current === "object" && current !== null && !seen.has(current)) {
+    seen.add(current);
+    if (current.name === "TransitionWhenError") {
+      return current;
+    }
+    current = current.cause;
+  }
+  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_";
+var Scope = class {
+  constructor(parent, isFunction, node) {
+    this.parent = parent;
+    this.isFunction = isFunction;
+    this.node = node;
+    this.declarations = /* @__PURE__ */ new Set();
+  }
+  nearestFunction() {
+    return this.isFunction || !this.parent ? this : this.parent.nearestFunction();
+  }
+  lookup(name) {
+    if (this.declarations.has(name)) return this;
+    return this.parent ? this.parent.lookup(name) : null;
+  }
+};
+var TYPE_KEYS = /* @__PURE__ */ new Set([
+  "typeAnnotation",
+  "returnType",
+  "typeParameters",
+  "typeArguments",
+  "superTypeArguments",
+  "implements"
+]);
+function jsxNameReference(name) {
+  if (name?.type === "JSXIdentifier") {
+    return /^[a-z]/.test(name.name) || name.name.includes("-") ? null : name;
+  }
+  let root = name;
+  while (root?.type === "JSXMemberExpression") root = root.object;
+  return root?.type === "JSXIdentifier" && root.name !== "this" ? root : null;
+}
+function patternNames(pattern, names = []) {
+  if (!pattern) return names;
+  switch (pattern.type) {
+    case "Identifier":
+      names.push(pattern.name);
+      break;
+    case "ObjectPattern":
+      for (const prop of pattern.properties) {
+        patternNames(prop.type === "RestElement" ? prop : prop.value, names);
+      }
+      break;
+    case "ArrayPattern":
+      for (const element of pattern.elements) patternNames(element, names);
+      break;
+    case "RestElement":
+      patternNames(pattern.argument, names);
+      break;
+    case "AssignmentPattern":
+      patternNames(pattern.left, names);
+      break;
+    case "TSParameterProperty":
+      patternNames(pattern.parameter, names);
+      break;
+  }
+  return names;
+}
+function analyzeScopes(program) {
+  const moduleScope = new Scope(null, true, program);
+  const scopeOf = /* @__PURE__ */ new Map([[program, moduleScope]]);
+  const references = [];
+  const declarePattern = (pattern, scope) => {
+    for (const name of patternNames(pattern)) scope.declarations.add(name);
+  };
+  const walkPattern = (pattern, scope, typeOnly) => {
+    if (!pattern) return;
+    switch (pattern.type) {
+      case "Identifier":
+        if (pattern.typeAnnotation) walk2(pattern.typeAnnotation, scope, true);
+        return;
+      case "ObjectPattern":
+        for (const prop of pattern.properties) {
+          if (prop.type === "RestElement") {
+            walkPattern(prop.argument, scope, typeOnly);
+          } else {
+            if (prop.computed) walk2(prop.key, scope, typeOnly);
+            walkPattern(prop.value, scope, typeOnly);
+          }
+        }
+        if (pattern.typeAnnotation) walk2(pattern.typeAnnotation, scope, true);
+        return;
+      case "ArrayPattern":
+        for (const element of pattern.elements) {
+          walkPattern(element, scope, typeOnly);
+        }
+        if (pattern.typeAnnotation) walk2(pattern.typeAnnotation, scope, true);
+        return;
+      case "RestElement":
+        walkPattern(pattern.argument, scope, typeOnly);
+        return;
+      case "AssignmentPattern":
+        walkPattern(pattern.left, scope, typeOnly);
+        walk2(pattern.right, scope, typeOnly);
+        return;
+      case "TSParameterProperty":
+        walkPattern(pattern.parameter, scope, typeOnly);
+        return;
+      default:
+        walk2(pattern, scope, typeOnly);
+    }
+  };
+  const hoistDeclarations = (statements, scope) => {
+    for (const statement of statements) {
+      const node = statement.type === "ExportNamedDeclaration" || statement.type === "ExportDefaultDeclaration" ? statement.declaration : statement;
+      if (!node) continue;
+      switch (node.type) {
+        case "ImportDeclaration":
+          for (const spec of node.specifiers) {
+            scope.declarations.add(spec.local.name);
+          }
+          break;
+        case "FunctionDeclaration":
+        case "ClassDeclaration":
+        case "TSEnumDeclaration":
+        case "TSTypeAliasDeclaration":
+        case "TSInterfaceDeclaration":
+        case "TSModuleDeclaration":
+          if (node.id?.type === "Identifier") {
+            scope.declarations.add(node.id.name);
+          }
+          break;
+        case "VariableDeclaration":
+          for (const declarator of node.declarations) {
+            declarePattern(
+              declarator.id,
+              node.kind === "var" ? scope.nearestFunction() : scope
+            );
+          }
+          break;
+      }
+    }
+  };
+  const walk2 = (node, scope, typeOnly) => {
+    if (!node || typeof node !== "object") return;
+    if (Array.isArray(node)) {
+      for (const item of node) walk2(item, scope, typeOnly);
+      return;
+    }
+    if (typeof node.type !== "string") return;
+    switch (node.type) {
+      case "Identifier":
+        references.push({ node, scope, typeOnly });
+        if (node.typeAnnotation) walk2(node.typeAnnotation, scope, true);
+        return;
+      case "ImportDeclaration":
+      case "ExportAllDeclaration":
+        return;
+      case "ExportNamedDeclaration":
+        if (node.declaration) walk2(node.declaration, scope, typeOnly);
+        else if (!node.source) {
+          for (const spec of node.specifiers) {
+            walk2(spec.local, scope, typeOnly || node.exportKind === "type");
+          }
+        }
+        return;
+      case "MemberExpression":
+        walk2(node.object, scope, typeOnly);
+        if (node.computed) walk2(node.property, scope, typeOnly);
+        return;
+      case "Property":
+      case "MethodDefinition":
+      case "PropertyDefinition":
+      case "TSPropertySignature":
+      case "TSMethodSignature":
+        if (node.computed) walk2(node.key, scope, typeOnly);
+        walk2(node.value, scope, typeOnly);
+        if (node.typeAnnotation) walk2(node.typeAnnotation, scope, true);
+        return;
+      case "LabeledStatement":
+        walk2(node.body, scope, typeOnly);
+        return;
+      case "BreakStatement":
+      case "ContinueStatement":
+      case "MetaProperty":
+        return;
+      case "JSXOpeningElement":
+      case "JSXClosingElement": {
+        const ref = jsxNameReference(node.name);
+        if (ref) references.push({ node: ref, scope, typeOnly });
+        walk2(node.typeArguments, scope, true);
+        walk2(node.attributes, scope, typeOnly);
+        return;
+      }
+      case "TSQualifiedName":
+        walk2(node.left, scope, typeOnly);
+        return;
+      case "TSEnumMember":
+        walk2(node.initializer, scope, typeOnly);
+        return;
+      case "TSTypeAliasDeclaration":
+      case "TSInterfaceDeclaration":
+        walk2(node.typeParameters, scope, true);
+        walk2(node.typeAnnotation ?? node.body, scope, true);
+        walk2(node.extends, scope, true);
+        return;
+      case "VariableDeclarator":
+        walkPattern(node.id, scope, typeOnly);
+        walk2(node.init, scope, typeOnly);
+        return;
+      case "FunctionDeclaration":
+      case "FunctionExpression":
+      case "ArrowFunctionExpression": {
+        const fnScope = new Scope(scope, true, node);
+        scopeOf.set(node, fnScope);
+        if (node.type === "FunctionExpression" && node.id) {
+          fnScope.declarations.add(node.id.name);
+        }
+        for (const param of node.params) declarePattern(param, fnScope);
+        walk2(node.typeParameters, fnScope, true);
+        for (const param of node.params) walkPattern(param, fnScope, typeOnly);
+        walk2(node.returnType, fnScope, true);
+        if (node.body?.type === "BlockStatement") {
+          hoistDeclarations(node.body.body, fnScope);
+          walk2(node.body.body, fnScope, typeOnly);
+        } else {
+          walk2(node.body, fnScope, typeOnly);
+        }
+        return;
+      }
+      case "ClassDeclaration":
+      case "ClassExpression": {
+        let classScope = scope;
+        if (node.type === "ClassExpression" && node.id) {
+          classScope = new Scope(scope, false, node);
+          classScope.declarations.add(node.id.name);
+          scopeOf.set(node, classScope);
+        }
+        walk2(node.superClass, classScope, typeOnly);
+        walk2(node.superTypeArguments, classScope, true);
+        walk2(node.typeParameters, classScope, true);
+        walk2(node.implements, classScope, true);
+        walk2(node.body, classScope, typeOnly);
+        return;
+      }
+      case "BlockStatement":
+      case "StaticBlock": {
+        const blockScope = new Scope(scope, false, node);
+        scopeOf.set(node, blockScope);
+        hoistDeclarations(node.body, blockScope);
+        walk2(node.body, blockScope, typeOnly);
+        return;
+      }
+      case "ForStatement":
+      case "ForInStatement":
+      case "ForOfStatement": {
+        const loopScope = new Scope(scope, false, node);
+        scopeOf.set(node, loopScope);
+        const head = node.type === "ForStatement" ? node.init : node.left;
+        if (head?.type === "VariableDeclaration") {
+          hoistDeclarations([head], loopScope);
+        }
+        for (const key of ["init", "left", "right", "test", "update", "body"]) {
+          walk2(node[key], loopScope, typeOnly);
+        }
+        return;
+      }
+      case "SwitchStatement": {
+        walk2(node.discriminant, scope, typeOnly);
+        const switchScope = new Scope(scope, false, node);
+        scopeOf.set(node, switchScope);
+        hoistDeclarations(
+          node.cases.flatMap((c) => c.consequent),
+          switchScope
+        );
+        for (const c of node.cases) {
+          walk2(c.test, switchScope, typeOnly);
+          walk2(c.consequent, switchScope, typeOnly);
+        }
+        return;
+      }
+      case "CatchClause": {
+        const catchScope = new Scope(scope, false, node);
+        scopeOf.set(node, catchScope);
+        if (node.param) {
+          declarePattern(node.param, catchScope);
+          walkPattern(node.param, catchScope, typeOnly);
+        }
+        walk2(node.body, catchScope, typeOnly);
+        return;
+      }
+    }
+    for (const key of Object.keys(node)) {
+      if (key === "type" || key === "start" || key === "end") continue;
+      walk2(node[key], scope, typeOnly || TYPE_KEYS.has(key));
+    }
+  };
+  hoistDeclarations(program.body, moduleScope);
+  walk2(program.body, moduleScope, false);
+  return { moduleScope, references, scopeOf };
+}
+function collectImports(program) {
+  const imports = /* @__PURE__ */ new Map();
+  for (const statement of program.body) {
+    if (statement.type !== "ImportDeclaration") continue;
+    const declTypeOnly = statement.importKind === "type";
+    for (const spec of statement.specifiers) {
+      imports.set(spec.local.name, {
+        source: statement.source.value,
+        imported: spec.type === "ImportDefaultSpecifier" ? "default" : spec.type === "ImportNamespaceSpecifier" ? "*" : spec.imported.type === "Identifier" ? spec.imported.name : String(spec.imported.value),
+        typeOnly: declTypeOnly || spec.importKind === "type"
+      });
+    }
+  }
+  return imports;
+}
+function hasUseClientDirective(program) {
+  for (const statement of program.body) {
+    if (statement.type !== "ExpressionStatement" || typeof statement.directive !== "string") {
+      return false;
+    }
+    if (statement.directive === "use client") return true;
+  }
+  return false;
+}
+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}`;
+}
+var ROUTER_SOURCE = "@rangojs/router";
+var EXPRESSION_WRAPPERS = /* @__PURE__ */ new Set([
+  "TSAsExpression",
+  "TSSatisfiesExpression",
+  "TSNonNullExpression",
+  "TSTypeAssertion",
+  "ParenthesizedExpression"
+]);
+function unwrapExpression(node) {
+  while (node && EXPRESSION_WRAPPERS.has(node.type)) node = node.expression;
+  return node;
+}
+function isFunctionLiteral(node) {
+  return node?.type === "ArrowFunctionExpression" || node?.type === "FunctionExpression";
+}
+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 = [];
+  const helpers = /* @__PURE__ */ new Map();
+  const routerExport = (callee, scope) => {
+    const routerImport = (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;
+    };
+    if (callee.type === "Identifier") {
+      const imported = routerImport(callee)?.imported;
+      return imported && imported !== "*" && imported !== "default" ? imported : null;
+    }
+    if (callee.type === "MemberExpression" && !callee.computed && callee.property.type === "Identifier" && routerImport(callee.object)?.imported === "*") {
+      return callee.property.name;
+    }
+    return null;
+  };
+  const registerUrlsCallback = (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()
+    };
+    if (param.type === "Identifier") bindings.objects.add(param.name);
+    if (param.type === "ObjectPattern") {
+      for (const prop of param.properties) {
+        if (!propertyKeyIs(prop, "transition")) continue;
+        const target = prop.value.type === "AssignmentPattern" ? prop.value.left : prop.value;
+        if (target.type === "Identifier") bindings.transitions.add(target.name);
+      }
+    }
+    helpers.set(fnScope, bindings);
+  };
+  const isRouterTransition = (callee, scope) => {
+    if (routerExport(callee, scope) === "transition") return true;
+    if (callee.type === "Identifier") {
+      const decl = scope.lookup(callee.name);
+      return !!decl && !!helpers.get(decl)?.transitions.has(callee.name);
+    }
+    if (callee.type === "MemberExpression" && !callee.computed && callee.property.type === "Identifier" && callee.property.name === "transition" && callee.object.type === "Identifier") {
+      const decl = scope.lookup(callee.object.name);
+      return !!decl && !!helpers.get(decl)?.objects.has(callee.object.name);
+    }
+    return false;
+  };
+  const visit = (node, scope) => {
+    if (!node || typeof node !== "object") return;
+    if (Array.isArray(node)) {
+      for (const item of node) visit(item, scope);
+      return;
+    }
+    if (typeof node.type !== "string") return;
+    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
+            });
+          }
+        }
+      }
+    }
+    for (const key of Object.keys(node)) {
+      if (key === "type" || key === "start" || key === "end") continue;
+      visit(node[key], own);
+    }
+  };
+  visit(program.body, moduleScope);
+  return sites;
+}
+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) {
+  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.`
+    };
+  };
+  const loads = (node, expression, why) => {
+    found = {
+      node,
+      detail: `\`${expression}\` ${why} Import client-safe modules statically, or export the predicate from a "use client" module.`
+    };
+  };
+  const visit = (node, boundary) => {
+    if (found || !node || typeof node !== "object") return;
+    if (Array.isArray(node)) {
+      for (const item of node) visit(item, boundary);
+      return;
+    }
+    if (typeof node.type !== "string") return;
+    switch (node.type) {
+      case "FunctionExpression":
+      case "FunctionDeclaration":
+        ownArguments.push(node);
+        boundary = node;
+        break;
+      case "ClassBody":
+        boundary = node;
+        break;
+      case "ThisExpression":
+        if (!boundary) capture(node, "this");
+        return;
+      case "Super":
+        if (!boundary || boundary === literal) capture(node, "super");
+        return;
+      case "JSXMemberExpression": {
+        let root = node;
+        while (root.type === "JSXMemberExpression") root = root.object;
+        if (root.name === "this" && !boundary) capture(root, "this");
+        return;
+      }
+      case "MetaProperty":
+        if (node.meta.name === "import") {
+          loads(node, "import.meta", "is the server module's.");
+        } else if (!boundary) {
+          capture(node, "new.target");
+        }
+        return;
+      case "MemberExpression":
+        if (node.object?.type === "MetaProperty") {
+          if (node.object.meta.name !== "import") break;
+          if (!node.computed && node.property.name === "env") return;
+          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."
+          );
+          return;
+        }
+        break;
+      case "ImportExpression":
+        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."
+        );
+        return;
+    }
+    for (const key of Object.keys(node)) {
+      if (key === "type" || key === "start" || key === "end") continue;
+      if (TYPE_KEYS.has(key)) continue;
+      visit(node[key], boundary);
+    }
+  };
+  visit(literal, null);
+  if (found) return found;
+  for (const ref of references) {
+    if (ref.typeOnly || ref.node.name !== "arguments") continue;
+    if (ref.node.start < literal.start || ref.node.end > literal.end) continue;
+    const owned = ownArguments.some(
+      (fn) => fn.start <= ref.node.start && ref.node.end <= fn.end
+    );
+    if (!owned) {
+      capture(ref.node, "arguments");
+      return found;
+    }
+  }
+  return null;
+}
+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) {
+  return new TransitionWhenError(
+    `[rango] transition({ when }) at ${file}:${lineColumn(code, node.start)}: \`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]);
+  let program;
+  try {
+    program = parseAst3(code, { lang: parseLang(file) });
+  } catch {
+    return null;
+  }
+  if (hasUseClientDirective(program)) return null;
+  const { moduleScope, references, scopeOf } = analyzeScopes(program);
+  const imports = collectImports(program);
+  const sites = findWhenSites(program, scopeOf, moduleScope, imports);
+  if (sites.length === 0) return null;
+  const s = new MagicString4(code);
+  const modules = [];
+  const header = [];
+  for (const site of sites) {
+    const { prop, value } = site;
+    if (prop.kind === "get" || prop.kind === "set") {
+      throw whenError(
+        file,
+        code,
+        prop,
+        `\`${prop.kind} when()\` is an accessor; \`when\` must be the predicate itself: \`when: (ctx) => ...\` or \`when(ctx) { ... }\`.`
+      );
+    }
+    if (value.type === "Identifier") {
+      const decl = site.scope.lookup(value.name);
+      if (decl && !(decl === moduleScope && imports.has(value.name))) {
+        throw whenError(
+          file,
+          code,
+          value,
+          `\`${value.name}\` is a server-module binding. Export the predicate from a "use client" module and import it, or write it inline.`
+        );
+      }
+      continue;
+    }
+    if (!isFunctionLiteral(value)) continue;
+    const lexical = findLexicalCapture(value, references, code);
+    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;
+      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.`
+      );
+    }
+    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)) {
+          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.`
+          );
+        }
+      }
+      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(),
+        `export const ${EXPORT_NAME} = ${source};`,
+        ""
+      ].join("\n")
+    );
+    const local = `${LOCAL_PREFIX}${index}`;
+    s.overwrite(
+      prop.start,
+      prop.end,
+      `${code.slice(prop.key.start, prop.key.end)}: ${local}`
+    );
+    header.push(
+      `import { ${EXPORT_NAME} as ${local} } from ${JSON.stringify(
+        `${file}?${TRANSITION_WHEN_QUERY}=${index}`
+      )};`
+    );
+  }
+  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;
+  }
+  s.appendLeft(insertAt, `${insertAt ? "\n" : ""}${header.join("\n")}
+`);
+  return {
+    code: s.toString(),
+    map: s.generateMap({ hires: true, source: file }),
+    modules
+  };
+}
+function parseHoistedWhenId(id) {
+  const q = id.indexOf("?");
+  if (q === -1) return null;
+  const params = new URLSearchParams(id.slice(q + 1));
+  const raw = params.get(TRANSITION_WHEN_QUERY);
+  if (raw === null || !/^\d+$/.test(raw)) return null;
+  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 {
+    name: "@rangojs/router:transition-when-hoist",
+    enforce: "pre",
+    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 module = modules?.[hoisted.index];
+      if (module === void 0) {
+        throw new TransitionWhenError(
+          `[rango] ${hoisted.file} has no inline transition({ when }) #${hoisted.index}.`
+        );
+      }
+      return module;
+    },
+    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;
+      emitted.delete(file);
+      const result = await hoistTransitionWhens(code, id, {
+        isServerOnlyImport: async (source) => {
+          const resolved = await this.resolve(source, id);
+          if (!resolved || resolved.external) return false;
+          const target = resolved.id.split("?", 1)[0];
+          if (target.includes("/node_modules/") || target.startsWith("\0")) {
+            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
+      });
+      return { code: result.code, map: result.map };
+    }
+  };
+}
+
 // src/vite/plugins/client-ref-dedup.ts
 init_debug();
 import { existsSync, readFileSync } from "node:fs";
@@ -3802,7 +4578,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.17.0",
+  version: "0.19.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -4220,15 +4996,6 @@ function extractRouteFromCallExpression(node) {
   };
 }
 
-// src/route-name.ts
-var AUTO_GENERATED_ROUTE_PREFIX = "$path_";
-var INTERNAL_INCLUDE_SCOPE_PREFIX = "$prefix_";
-function isAutoGeneratedRouteName(name) {
-  return name.split(".").some((segment) => {
-    return segment.startsWith(AUTO_GENERATED_ROUTE_PREFIX) || segment.startsWith(INTERNAL_INCLUDE_SCOPE_PREFIX);
-  });
-}
-
 // src/build/route-types/codegen.ts
 function generateRouteTypesSource(routeManifest, searchSchemas) {
   const entries = Object.entries(routeManifest).filter(([name]) => !isAutoGeneratedRouteName(name)).sort(([a], [b]) => a.localeCompare(b));
@@ -5269,14 +6036,14 @@ function writeCombinedRouteTypes(root, knownRouterFiles, opts) {
 }
 
 // src/vite/plugins/version-plugin.ts
-import { parseAst as parseAst4 } from "vite";
+import { parseAst as parseAst5 } from "vite";
 
 // src/vite/utils/directive-prologue.ts
-import { parseAst as parseAst3 } from "vite";
-function hasUseClientDirective(source) {
+import { parseAst as parseAst4 } from "vite";
+function hasUseClientDirective2(source) {
   let program;
   try {
-    program = parseAst3(source, { lang: "tsx" });
+    program = parseAst4(source, { lang: "tsx" });
   } catch {
     return false;
   }
@@ -5298,10 +6065,10 @@ function normalizeModuleId(id) {
   return id.split("?", 1)[0];
 }
 function getClientModuleSignature(source) {
-  if (!hasUseClientDirective(source)) return void 0;
+  if (!hasUseClientDirective2(source)) return void 0;
   let program;
   try {
-    program = parseAst4(source, { lang: "tsx" });
+    program = parseAst5(source, { lang: "tsx" });
   } catch {
     return void 0;
   }
@@ -5488,7 +6255,7 @@ import { isAbsolute as isAbsolute2, resolve as resolve4 } from "node:path";
 
 // src/vite/plugins/performance-tracks.ts
 init_debug();
-import { readFile } from "node:fs/promises";
+import { readFile as readFile2 } from "node:fs/promises";
 var debug5 = 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) {
@@ -5517,7 +6284,7 @@ function performanceTracksOptimizeDepsPlugin() {
     async load(id) {
       const cleanId = id.split("?")[0] ?? id;
       if (!RSDW_CLIENT_RE.test(cleanId)) return null;
-      const code = await readFile(cleanId, "utf8");
+      const code = await readFile2(cleanId, "utf8");
       const patched = patchRsdwClientDebugInfoRecovery(code);
       return { code: patched.code };
     }
@@ -6147,6 +6914,10 @@ import React from "react";
 // src/server/context.ts
 import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
 
+// src/rsc/shell-capture-constants.ts
+var SHELL_CAPTURE_MAX_WAIT_MS = 15e3;
+var PPR_LANE_HINT = 'Lane rule: only loader(Def, { ssr: false }) executes at capture and bakes its non-promise data; every other loader is live (masked at capture, fresh per request) and needs loading() or an inline <Suspense> above its reader. See the /ppr skill, "The loader lane rule" (node_modules/@rangojs/router/skills/ppr/SKILL.md).';
+
 // src/cache/cache-exec-scope.ts
 import { AsyncLocalStorage } from "node:async_hooks";
 
@@ -6158,6 +6929,8 @@ function _setCacheExecScopeProbe(probe) {
 
 // src/cache/cache-exec-scope.ts
 var cacheExecStorage = new AsyncLocalStorage();
+var IDENTITY_EXEMPT_KEY = /* @__PURE__ */ Symbol.for("rangojs-router:identity-exempt");
+var identityExemptStorage = globalThis[IDENTITY_EXEMPT_KEY] ??= new AsyncLocalStorage();
 function isInsideCacheExecScope() {
   return cacheExecStorage.getStore() !== void 0;
 }
@@ -6170,19 +6943,37 @@ var LOADER_SCOPE_KEY = /* @__PURE__ */ Symbol.for("rangojs-router:loader-scope")
 var loaderScopeALS = globalThis[LOADER_SCOPE_KEY] ??= new AsyncLocalStorage2();
 var LOADER_BODY_SCOPE_KEY = /* @__PURE__ */ Symbol.for("rangojs-router:loader-body-scope");
 var loaderBodyScopeALS = globalThis[LOADER_BODY_SCOPE_KEY] ??= new AsyncLocalStorage2();
+function requestReadCaptureFix(what) {
+  return {
+    capture: `The captured shell is served to every user of this URL, so request-scoped data read here would leak one user's ${what} to others. Read it inside a loader without ssr: false and consume it with useLoader, e.g. createLoader(async () => getUser(cookies().get("session")?.value)). ${PPR_LANE_HINT}`,
+    warning: "Read it in a loader without ssr: false and consume it with useLoader under loading() or an inline <Suspense> (a live hole). A promise the handler passes or pushes does not help: the capture waits for it."
+  };
+}
+var NON_CACHEABLE_READ = {
+  verb: "called",
+  fix: {
+    useCache: "The variable was created with { cache: false } or set with { cache: false }, and the cache key does not include its value, so the first caller's value would be served to later callers. Read it before calling the cached function and pass the value in as an argument so it becomes part of the cache key.",
+    cacheScope: "The variable was created with { cache: false } or set with { cache: false }, and its value would be stale on cache hit. Move the read outside the cached scope.",
+    ...requestReadCaptureFix("per-request variables")
+  }
+};
+function getLoaderBodyTags() {
+  return loaderBodyScopeALS.getStore()?.tags;
+}
+function getCurrentLoaderBodyId() {
+  return loaderBodyScopeALS.getStore()?.loaderId;
+}
 var PUSH_CALLBACK_SCOPE_KEY = /* @__PURE__ */ Symbol.for(
   "rangojs-router:push-callback-scope"
 );
 var pushCallbackScopeALS = globalThis[PUSH_CALLBACK_SCOPE_KEY] ??= new AsyncLocalStorage2();
 
-// src/rsc/shell-capture-constants.ts
-var SHELL_CAPTURE_MAX_WAIT_MS = 15e3;
-
 // src/rsc/shell-serve.ts
 var DEV_SHELL_PROBE_TIMEOUT_MS = 1e4;
 function normalizeCaptureTimeout(value) {
   return typeof value === "number" && Number.isFinite(value) && value >= 1 ? Math.min(value, SHELL_CAPTURE_MAX_WAIT_MS) : void 0;
 }
+var SHELL_PRELUDE_CHUNK_BYTES = 32 * 1024;
 
 // src/vite/inject-client-debug.ts
 function isRouterInternalDebugId(id) {
@@ -7713,7 +8504,7 @@ 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 relative4, resolve as resolve8 } from "node:path";
-import { normalizePath as normalizePath4, parseAst as parseAst5 } from "vite";
+import { normalizePath as normalizePath5, parseAst as parseAst6 } from "vite";
 
 // src/client-urls/server-projection.ts
 import * as React5 from "react";
@@ -8567,6 +9358,11 @@ init_logging();
 init_cache();
 init_rango_state();
 
+// src/browser/react/location-state-shared.ts
+function isLocationStateDefinition(value) {
+  return typeof value === "function" && "__rsc_ls_flash" in value;
+}
+
 // src/browser/react/NavigationProvider.tsx
 import { jsx as jsx7 } from "react/jsx-runtime";
 
@@ -8575,9 +9371,9 @@ import {
   forwardRef,
   useCallback as useCallback5,
   useContext as useContext15,
-  useEffect as useEffect15,
+  useEffect as useEffect14,
   useMemo as useMemo7,
-  useRef as useRef13,
+  useRef as useRef12,
   useSyncExternalStore
 } from "react";
 
@@ -8817,21 +9613,6 @@ function isPrefetchScopeDisabled(element) {
   return typeof element.closest === "function" && element.closest(PREFETCH_SCOPE_OPT_OUT_SELECTOR) !== null;
 }
 
-// src/browser/react/location-state.ts
-import { useState as useState14, useEffect as useEffect14, useRef as useRef12 } from "react";
-
-// src/browser/react/location-state-shared.ts
-function isLocationStateEntry(value) {
-  return value !== null && typeof value === "object" && "__rsc_ls_key" in value && "__rsc_ls_value" in value && typeof value.__rsc_ls_key === "string";
-}
-function resolveLocationStateEntries(entries) {
-  const result = {};
-  for (const entry of entries) {
-    result[entry.__rsc_ls_key] = entry.__rsc_ls_lazy ? entry.__rsc_ls_value() : entry.__rsc_ls_value;
-  }
-  return result;
-}
-
 // src/browser/react/Link.tsx
 init_loader();
 import { jsx as jsx8 } from "react/jsx-runtime";
@@ -8858,6 +9639,7 @@ var Link = forwardRef(function Link2({
   scroll = true,
   reloadDocument = false,
   revalidate: revalidate2,
+  transition: transition2,
   prefetch,
   prefetchKey,
   state,
@@ -8882,7 +9664,7 @@ var Link = forwardRef(function Link2({
     () => resolveAdaptiveStrategy(configuredStrategy),
     () => configuredStrategy === "adaptive" ? "hover" : configuredStrategy
   );
-  const internalRef = useRef13(null);
+  const internalRef = useRef12(null);
   const setRef = useCallback5(
     (node) => {
       internalRef.current = node;
@@ -8894,7 +9676,7 @@ var Link = forwardRef(function Link2({
     },
     [ref]
   );
-  const stateRef = useRef13(state);
+  const stateRef = useRef12(state);
   stateRef.current = state;
   const handleClick = useCallback5(
     (e) => {
@@ -8916,21 +9698,13 @@ var Link = forwardRef(function Link2({
       e.preventDefault();
       e.stopPropagation();
       const currentState = stateRef.current;
-      let resolvedState;
-      if (Array.isArray(currentState) && currentState.length > 0 && isLocationStateEntry(currentState[0])) {
-        resolvedState = resolveLocationStateEntries(
-          currentState
-        );
-      } else if (typeof currentState === "function") {
-        resolvedState = currentState();
-      } else if (currentState != null) {
-        resolvedState = currentState;
-      }
+      const state2 = typeof currentState === "function" && !(process.env.NODE_ENV !== "production" && isLocationStateDefinition(currentState)) ? currentState() : currentState ?? void 0;
       ctx.navigate(resolvedTo, {
         replace,
         scroll,
-        state: resolvedState,
-        revalidate: revalidate2
+        state: state2,
+        revalidate: revalidate2,
+        transition: transition2
       });
     },
     [
@@ -8940,6 +9714,7 @@ var Link = forwardRef(function Link2({
       replace,
       scroll,
       revalidate2,
+      transition2,
       ctx,
       onClick
     ]
@@ -8957,7 +9732,7 @@ var Link = forwardRef(function Link2({
       );
     }
   }, [resolvedStrategy, resolvedTo, isExternal, ctx, prefetchKey]);
-  useEffect15(() => {
+  useEffect14(() => {
     if (isExternal || !ctx?.store) return;
     const isViewport = resolvedStrategy === "viewport";
     const isRender = resolvedStrategy === "render";
@@ -9037,6 +9812,7 @@ var Link = forwardRef(function Link2({
       "data-scroll": scroll === false ? "false" : void 0,
       "data-replace": replace ? "true" : void 0,
       "data-revalidate": revalidate2 === false ? "false" : void 0,
+      "data-transition": transition2 === false ? "false" : void 0,
       ...props,
       children: /* @__PURE__ */ jsx8(LinkContext.Provider, { value: resolvedTo, children })
     }
@@ -9070,6 +9846,9 @@ var Breadcrumbs = createHandle(
   "__rsc_router_breadcrumbs__"
 );
 
+// src/browser/react/location-state.ts
+import { useState as useState14, useEffect as useEffect15, useRef as useRef13 } from "react";
+
 // src/href-client.ts
 function href(path6, mount) {
   if (mount && mount !== "/") {
@@ -9133,18 +9912,75 @@ var ALL_USE_ITEM_TYPES = new Set(
 );
 
 // src/server/request-context.ts
-import { AsyncLocalStorage as AsyncLocalStorage4 } from "node:async_hooks";
+import { AsyncLocalStorage as AsyncLocalStorage5 } from "node:async_hooks";
 init_cookie_name();
 
+// src/router/segment-resolution/mask-nested.ts
+import { cloneElement, isValidElement as isValidElement2 } from "react";
+
 // src/server/handle-store.ts
 var LOADER_SLOT = Object.freeze({ loader: true });
 
+// src/cache/cache-tag.ts
+import { AsyncLocalStorage as AsyncLocalStorage3 } from "node:async_hooks";
+var cacheTagStorage = new AsyncLocalStorage3();
+var segmentOwnerStorage = new AsyncLocalStorage3();
+var recordedTagCapture = globalThis[/* @__PURE__ */ Symbol.for("rangojs-router:recorded-tag-capture")] ??= new AsyncLocalStorage3();
+var identityReads = globalThis[/* @__PURE__ */ Symbol.for("rangojs-router:identity-reads")] ??= /* @__PURE__ */ new WeakMap();
+function activeTagSet() {
+  const capture = recordedTagCapture.getStore();
+  const body = getLoaderBodyTags();
+  if (capture && capture.outer === body) return capture.into;
+  return body ?? capture?.into;
+}
+globalThis[/* @__PURE__ */ Symbol.for("rangojs-router:identity-read-recorder")] = (surface, verb) => {
+  const set = activeTagSet();
+  if (set === void 0 || identityReads.has(set)) return;
+  identityReads.set(set, { surface, verb, bodyId: getCurrentLoaderBodyId() });
+};
+
 // src/router/router-context.ts
-import { AsyncLocalStorage as AsyncLocalStorage3 } from "async_hooks";
-var routerContext = new AsyncLocalStorage3();
+import { AsyncLocalStorage as AsyncLocalStorage4 } from "async_hooks";
+var routerContext = new AsyncLocalStorage4();
+
+// src/server/cookie-store.ts
+var REQUEST_READ_CACHE_FIX = {
+  useCache: 'Request-scoped data (cookies, headers) varies per request but is not reflected in the cache key, so cached results would be served to the wrong users. Extract the value before the cached function and pass it as an argument:\n\n  const locale = cookies().get("locale")?.value ?? "en";\n  const data = await getCachedData(locale); // locale is now in the cache key',
+  cacheScope: 'A cache() scope caches everything except loaders, so request-scoped data (cookies, headers) read here would be frozen into the shared cached shell and served to other users. Read it inside a loader instead \u2014 loaders always run fresh on every request, even on a cache hit:\n\n  loader("user", () => getUser(cookies().get("session")?.value));'
+};
+function requestReadWording(what) {
+  return {
+    verb: "called",
+    fix: { ...REQUEST_READ_CACHE_FIX, ...requestReadCaptureFix(what) },
+    record: false
+  };
+}
+var COOKIES_READ = requestReadWording("cookies");
+var HEADERS_READ = requestReadWording("headers");
+var REQUEST_HEADERS_READ = {
+  verb: "read",
+  fix: HEADERS_READ.fix
+};
+var RAW_COOKIES_READ = {
+  verb: "called",
+  fix: COOKIES_READ.fix
+};
+var THEME_READ_FIX = "On ppr and cache() routes, read the theme with useTheme() in a client component, or in a live loader (no ssr: false) with cookies().get(<storageKey>). The <html> theme class needs neither: the theme script sets it before paint. See the /theme skill (node_modules/@rangojs/router/skills/theme/SKILL.md).";
+var THEME_READ = {
+  verb: "read",
+  fix: {
+    useCache: "The theme comes from the visitor's cookie and is not in the cache key, so the first caller's theme would be served to later callers. Read it before the cached function and pass it in as an argument.",
+    cacheScope: "The theme comes from the visitor's cookie, so the first visitor's theme would be stored in the shared entry and served to everyone. " + THEME_READ_FIX,
+    capture: `The captured shell is served to every visitor of this URL, so the capturing visitor's theme would reach everyone. ${THEME_READ_FIX}`,
+    warning: THEME_READ_FIX
+  }
+};
+
+// src/cache/invalidation-order.ts
+var order = globalThis[/* @__PURE__ */ Symbol.for("rangojs-router:tag-invalidation-order")] ??= { seq: 0, tags: /* @__PURE__ */ new Map(), forgotten: 0 };
 
 // src/server/request-context.ts
-var requestContextStorage = new AsyncLocalStorage4();
+var requestContextStorage = new AsyncLocalStorage5();
 
 // src/route-definition/redirect.ts
 init_redirect_origin();
@@ -9281,7 +10117,7 @@ function serializeTransition(route2) {
   if (!source) return void 0;
   const config = {};
   for (const [key, value] of Object.entries(source)) {
-    if (value === void 0) continue;
+    if (value === void 0 || key === "when") continue;
     config[key] = typeof value === "object" && value !== null ? Object.freeze({ ...value }) : value;
   }
   return Object.freeze(config);
@@ -9306,7 +10142,8 @@ function serializeRoute(route2) {
     loaderIds: Object.freeze(loaderIds),
     hasLoading: route2.loading !== void 0,
     ...awaitedLoaderIndices.length > 0 ? { awaitedLoaderIndices: Object.freeze(awaitedLoaderIndices) } : {},
-    ...transition2 ? { transition: transition2 } : {}
+    ...transition2 ? { transition: transition2 } : {},
+    ...typeof route2.transition?.when === "function" ? { transitionWhen: true } : {}
   });
 }
 function serializeIntercept(record, index) {
@@ -9342,7 +10179,7 @@ var debug10 = createRangoDebugger(NS.discovery);
 function hasDefaultExport(code) {
   let program;
   try {
-    program = parseAst5(code, { lang: "tsx" });
+    program = parseAst6(code, { lang: "tsx" });
   } catch {
     return false;
   }
@@ -9359,18 +10196,18 @@ function hasDefaultExport(code) {
 function normalizeSource(state, id) {
   const cleanId = id.split("?", 1)[0];
   const absoluteId = isAbsolute3(cleanId) ? cleanId : resolve8(state.projectRoot, cleanId);
-  return normalizePath4(absoluteId);
+  return normalizePath5(absoluteId);
 }
 function referenceId(referenceKey) {
   return `${referenceKey}#default`;
 }
 function recordClientUrlsModule(state, code, id) {
-  if (!code.includes("clientUrls(") || !hasUseClientDirective(code) || !hasDefaultExport(code)) {
+  if (!code.includes("clientUrls(") || !hasUseClientDirective2(code) || !hasDefaultExport(code)) {
     return;
   }
   const source = normalizeSource(state, id);
-  const projectRoot = normalizePath4(resolve8(state.projectRoot));
-  const relativeId = normalizePath4(relative4(projectRoot, source));
+  const projectRoot = normalizePath5(resolve8(state.projectRoot));
+  const relativeId = normalizePath5(relative4(projectRoot, source));
   const outsideProject = relativeId === ".." || relativeId.startsWith("../") || isAbsolute3(relativeId);
   const devReferenceKey = outsideProject ? `/@fs${source}` : `/${relativeId}`;
   const sourceByReferenceId = state.clientUrlSourceByReferenceId ??= /* @__PURE__ */ new Map();
@@ -9606,7 +10443,10 @@ async function discoverRouters(state, rscEnv, ssrEnv) {
         await generateManifestFull(mount.patterns, routerMountIndex, {
           routerId: id,
           ...router.__basename ? { urlPrefix: router.__basename } : {},
-          ...collectClientFallbackRef ? { collectClientFallbackRef } : {}
+          ...collectClientFallbackRef ? { collectClientFallbackRef } : {},
+          // Discovery evaluates the tree in the react-server graph, where a
+          // "use client" import is a client reference: reject server `when`s.
+          validateTransitionWhen: true
         })
       );
       routerMountIndex++;
@@ -9727,6 +10567,8 @@ async function runShellPrerenderPhase(s, builder) {
   const candidates = s.shellCandidates;
   const startTotal = performance.now();
   console.log(`[rango] Shell-prerendering ${candidates.length} URL(s)...`);
+  const keepAlive = setInterval(() => {
+  }, 6e4);
   let restoreClientRequire;
   try {
     const rscEnv = tempServer.environments?.rsc;
@@ -9888,9 +10730,7 @@ async function runShellPrerenderPhase(s, builder) {
           const value = {
             entry: res.entry,
             ttl: policy.ttl,
-            swr: policy.swr,
-            tags: res.tags,
-            routeName: cand.routeName
+            tags: res.tags
           };
           staged.push({
             key: buildShellManifestKey(cand.urlPath),
@@ -9934,6 +10774,7 @@ async function runShellPrerenderPhase(s, builder) {
   } finally {
     delete globalThis.__loadPrerenderManifestModule;
     restoreClientRequire?.();
+    clearInterval(keepAlive);
   }
 }
 function writeShellManifest(s, rscOutDir, staged) {
@@ -10131,6 +10972,7 @@ function supplementGenFilesWithRuntimeRoutes(state) {
 import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync5 } from "node:fs";
 import { dirname as dirname4, basename, join as join7 } from "node:path";
 var MANIFEST_EXTERNALIZE_THRESHOLD = 512 * 1024;
+var TRANSITION_WHEN_VALIDATION = `enableTransitionWhenValidation();`;
 function devDiscoveryBootstrap(state) {
   if (state.isBuildMode || state.opts?.preset !== "cloudflare" || state.devDiscoveryEpoch === void 0) {
     return [];
@@ -10166,6 +11008,7 @@ function generateRoutesManifestModule(state) {
       }
     }
     const serverImports = [
+      "enableTransitionWhenValidation",
       "setCachedManifest",
       "setRouterManifest",
       ...state.isBuildMode ? ["registerRouterManifestLoader"] : [],
@@ -10180,7 +11023,8 @@ function generateRoutesManifestModule(state) {
       // this virtual module but the route-map-builder singleton retains old data
       // because it's not in the HMR invalidation chain. Without this clear, the
       // handler finds stale trie data and never rebuilds from updated urlpatterns.
-      `clearAllRouterData();`
+      `clearAllRouterData();`,
+      TRANSITION_WHEN_VALIDATION
     ];
     if (hasClientUrlModules) {
       lines2.push(`clearClientUrlProjections();`);
@@ -10230,12 +11074,12 @@ function generateRoutesManifestModule(state) {
     lines2.push(...devDiscoveryBootstrap(state));
     return lines2.join("\n");
   }
-  const lines = [];
+  const lines = [
+    `import { ${hasClientUrlModules ? "clearClientUrlProjections, " : ""}enableTransitionWhenValidation } from "@rangojs/router/server";`,
+    TRANSITION_WHEN_VALIDATION
+  ];
   if (hasClientUrlModules) {
-    lines.push(
-      `import { clearClientUrlProjections } from "@rangojs/router/server";`,
-      `clearClientUrlProjections();`
-    );
+    lines.push(`clearClientUrlProjections();`);
   }
   if (!state.isBuildMode) {
     const origin = state.devServerOrigin || state.devServer?.resolvedUrls?.local?.[0]?.replace(/\/$/, "") || state.devServer && `http://localhost:${state.devServer.config.server.port || 5173}`;
@@ -10245,7 +11089,7 @@ function generateRoutesManifestModule(state) {
     }
   }
   lines.push(...devDiscoveryBootstrap(state));
-  return lines.join("\n") || `// Route manifest will be populated at runtime`;
+  return lines.join("\n");
 }
 function shortHash(input) {
   let h = 2166136261;
@@ -10603,7 +11447,16 @@ async function createTempRscServer(state, options = {}) {
   return createViteServer({
     root: state.projectRoot,
     configFile: false,
-    server: { middlewareMode: true },
+    server: {
+      middlewareMode: true,
+      // Build mode: no file watching. buildStart installs the per-router tries
+      // into this realm and runShellPrerenderPhase reuses it after the bundles
+      // are written. A watched write in between (writeRouteTypesFiles' own
+      // <router>.named-routes.gen.ts, which every router file imports) can
+      // make Vite full-reload the RSC runner; the shell phase then matches in
+      // a fresh realm with no tries and a root path("/*") wins (#947).
+      ...options.forceBuild ? { watch: null } : {}
+    },
     appType: "custom",
     logLevel: "silent",
     resolve: resolveConfig,
@@ -10655,6 +11508,9 @@ async function createTempRscServer(state, options = {}) {
       ] : [],
       createVirtualStubPlugin(),
       createCloudflareProtocolStubPlugin(),
+      // Inline transition({ when }) literals become client references here
+      // too, or discovery would see (and reject) the plain function.
+      transitionWhenHoistPlugin(),
       // 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),
@@ -10742,6 +11598,25 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
   const s = createDiscoveryState(entryPath, opts);
   let viteCommand = "build";
   let viteMode = "production";
+  let transitionWhenOverlay = null;
+  const sendTransitionWhenOverlay = () => {
+    if (!transitionWhenOverlay) return;
+    s.devServer?.environments?.client?.hot?.send({
+      type: "error",
+      err: transitionWhenOverlay
+    });
+  };
+  const showTransitionWhenError = (err) => {
+    const whenError2 = findTransitionWhenError(err);
+    if (!whenError2) return void 0;
+    transitionWhenOverlay = {
+      message: whenError2.message,
+      stack: whenError2.stack ?? "",
+      plugin: "@rangojs/router"
+    };
+    sendTransitionWhenOverlay();
+    return whenError2;
+  };
   return {
     name: "@rangojs/router:discovery",
     // Make INTERNAL_RANGO_DEBUG reach the CLIENT debug logs by just setting the
@@ -10792,6 +11667,25 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
       if (s.isBuildMode) return;
       if (globalThis.__rscRouterDiscoveryActive) return;
       s.devServer = server;
+      server.environments?.client?.hot?.on?.(
+        "vite:client:connect",
+        (_payload, client) => {
+          if (transitionWhenOverlay) {
+            client?.send?.({ type: "error", err: transitionWhenOverlay });
+          }
+        }
+      );
+      let overlayResendQueued = false;
+      server.httpServer?.on("request", (req, res) => {
+        const isPage = req.url?.includes("_rsc") === true || req.headers.accept?.includes("text/html") === true;
+        if (transitionWhenOverlay && isPage && !overlayResendQueued) {
+          overlayResendQueued = true;
+          res.once("close", () => {
+            overlayResendQueued = false;
+            sendTransitionWhenOverlay();
+          });
+        }
+      });
       let workerReadyEpoch;
       const publishDevDiscoveryReady = (epoch) => {
         if (epoch <= (workerReadyEpoch ?? -1)) return;
@@ -11010,6 +11904,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
         } else {
           console.error(report.message);
         }
+        showTransitionWhenError(err);
       };
       const discover = async () => {
         const discoverStart = performance.now();
@@ -11426,9 +12321,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
             const body = JSON.stringify({
               entry: result.entry,
               ttl,
-              swr,
-              tags: result.tags,
-              routeName
+              tags: result.tags
             });
             devPrerenderCache.set(routerInstance, cacheKey, body);
             res.setHeader("content-type", "application/json");
@@ -11538,6 +12431,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
                 );
                 s.lastDiscoveryError = null;
               }
+              transitionWhenOverlay = null;
               if (rscEnv && !rscEnv.runner) {
                 const nextRouteShape = routeShapeSignature();
                 let expectedEpoch;
@@ -11556,9 +12450,14 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
                 message: err?.message ?? String(err),
                 at: Date.now()
               };
-              console.warn(
-                `[rango] Runtime re-discovery failed: ${err.message}`
-              );
+              const whenError2 = showTransitionWhenError(err);
+              if (whenError2) {
+                console.error(whenError2.message);
+              } else {
+                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
@@ -12458,7 +13357,7 @@ If this is a multi-app host router, export a createHostRouter() instance and set
         return;
       try {
         const source = readFileSync10(file, "utf-8");
-        if (hasUseClientDirective(source)) {
+        if (hasUseClientDirective2(source)) {
           return [];
         }
       } catch {
@@ -12466,6 +13365,7 @@ If this is a multi-app host router, export a createHostRouter() instance and set
     }
   });
   plugins.push(createLoaderDirectiveGuardPlugin());
+  plugins.push(transitionWhenHoistPlugin());
   plugins.push(createLoaderScanStubPlugin());
   plugins.push(exposeActionId());
   plugins.push(