@rangojs/router 0.0.0-experimental.55 → 0.0.0-experimental.56

package/dist/bin/rango.js

@@ -450,7 +450,7 @@ function buildRouteMapFromBlock(block, fullSource, filePath, visited, searchSche
   }
   return routeMap;
 }
-function buildCombinedRouteMapWithSearch(filePath, variableName, visited, diagnosticsOut) {
+function buildCombinedRouteMapWithSearch(filePath, variableName, visited, diagnosticsOut, inlineBlock) {
   visited = visited ?? /* @__PURE__ */ new Set();
   const realPath = resolve(filePath);
   const key = variableName ? `${realPath}:${variableName}` : realPath;
@@ -466,7 +466,9 @@ function buildCombinedRouteMapWithSearch(filePath, variableName, visited, diagno
     return { routes: {}, searchSchemas: {} };
   }
   let block;
-  if (variableName) {
+  if (inlineBlock) {
+    block = inlineBlock;
+  } else if (variableName) {
     const extracted = extractUrlsBlockForVariable(source, variableName);
     if (!extracted) return { routes: {}, searchSchemas: {} };
     block = extracted;
@@ -671,7 +673,7 @@ Router root: ${conflict.ancestor}
 Nested router: ${conflict.nested}
 Move the nested router into a sibling directory or configure it as a separate app root.`;
 }
-function extractUrlsVariableFromRouter(code) {
+function extractUrlsFromRouter(code) {
   const sourceFile = ts5.createSourceFile(
     "router.tsx",
     code,
@@ -685,24 +687,70 @@ function extractUrlsVariableFromRouter(code) {
     const callee = node.expression;
     return ts5.isIdentifier(callee) && callee.text === "createRouter";
   }
+  function isInlineBuilder(node) {
+    return ts5.isArrowFunction(node) || ts5.isFunctionExpression(node);
+  }
+  function isRoutesOnCreateRouter(node) {
+    if (!ts5.isPropertyAccessExpression(node.expression) || node.expression.name.text !== "routes")
+      return false;
+    let inner = node.expression.expression;
+    while (ts5.isCallExpression(inner) && ts5.isPropertyAccessExpression(inner.expression)) {
+      inner = inner.expression.expression;
+    }
+    return isCreateRouterCall(inner);
+  }
   function visit(node) {
     if (result) return;
-    if (ts5.isCallExpression(node) && ts5.isPropertyAccessExpression(node.expression) && node.expression.name.text === "routes" && node.arguments.length >= 1 && ts5.isIdentifier(node.arguments[0])) {
-      let inner = node.expression.expression;
-      while (ts5.isCallExpression(inner) && ts5.isPropertyAccessExpression(inner.expression)) {
-        inner = inner.expression.expression;
-      }
-      if (isCreateRouterCall(inner)) {
-        result = node.arguments[0].text;
-        return;
+    if (ts5.isCallExpression(node) && node.arguments.length >= 1 && isRoutesOnCreateRouter(node)) {
+      const arg = node.arguments[0];
+      if (ts5.isIdentifier(arg)) {
+        result = { kind: "variable", name: arg.text };
+      } else if (isInlineBuilder(arg)) {
+        result = { kind: "inline", block: arg.getText(sourceFile) };
       }
+      return;
     }
     if (isCreateRouterCall(node)) {
       const callExpr = node;
-      for (const arg of callExpr.arguments) {
+      for (const callArg of callExpr.arguments) {
+        if (ts5.isObjectLiteralExpression(callArg)) {
+          for (const prop of callArg.properties) {
+            if (ts5.isPropertyAssignment(prop) && ts5.isIdentifier(prop.name) && prop.name.text === "urls") {
+              if (ts5.isIdentifier(prop.initializer)) {
+                result = { kind: "variable", name: prop.initializer.text };
+              } else if (isInlineBuilder(prop.initializer)) {
+                result = {
+                  kind: "inline",
+                  block: prop.initializer.getText(sourceFile)
+                };
+              }
+              return;
+            }
+          }
+        }
+      }
+    }
+    ts5.forEachChild(node, visit);
+  }
+  visit(sourceFile);
+  return result;
+}
+function extractBasenameFromRouter(code) {
+  const sourceFile = ts5.createSourceFile(
+    "router.tsx",
+    code,
+    ts5.ScriptTarget.Latest,
+    true,
+    ts5.ScriptKind.TSX
+  );
+  let result;
+  function visit(node) {
+    if (result !== void 0) return;
+    if (ts5.isCallExpression(node) && ts5.isIdentifier(node.expression) && node.expression.text === "createRouter") {
+      for (const arg of node.arguments) {
         if (ts5.isObjectLiteralExpression(arg)) {
           for (const prop of arg.properties) {
-            if (ts5.isPropertyAssignment(prop) && ts5.isIdentifier(prop.name) && prop.name.text === "urls" && ts5.isIdentifier(prop.initializer)) {
+            if (ts5.isPropertyAssignment(prop) && ts5.isIdentifier(prop.name) && prop.name.text === "basename" && ts5.isStringLiteral(prop.initializer)) {
               result = prop.initializer.text;
               return;
             }
@@ -715,6 +763,19 @@ function extractUrlsVariableFromRouter(code) {
   visit(sourceFile);
   return result;
 }
+function applyBasenameToRoutes(result, basename2) {
+  const prefixed = {};
+  for (const [name, pattern] of Object.entries(result.routes)) {
+    if (pattern === "/") {
+      prefixed[name] = basename2;
+    } else if (basename2.endsWith("/") && pattern.startsWith("/")) {
+      prefixed[name] = basename2 + pattern.slice(1);
+    } else {
+      prefixed[name] = basename2 + pattern;
+    }
+  }
+  return { routes: prefixed, searchSchemas: result.searchSchemas };
+}
 function buildCombinedRouteMapForRouterFile(routerFilePath) {
   let routerSource;
   try {
@@ -722,19 +783,40 @@ function buildCombinedRouteMapForRouterFile(routerFilePath) {
   } catch {
     return { routes: {}, searchSchemas: {} };
   }
-  const urlsVarName = extractUrlsVariableFromRouter(routerSource);
-  if (!urlsVarName) {
+  const extraction = extractUrlsFromRouter(routerSource);
+  if (!extraction) {
     return { routes: {}, searchSchemas: {} };
   }
-  const imported = resolveImportedVariable(routerSource, urlsVarName);
-  if (imported) {
-    const targetFile = resolveImportPath(imported.specifier, routerFilePath);
-    if (!targetFile) {
-      return { routes: {}, searchSchemas: {} };
+  const rawBasename = extractBasenameFromRouter(routerSource);
+  const basename2 = rawBasename ? ("/" + rawBasename.replace(/^\/+|\/+$/g, "")).replace(/^\/$/, "") : void 0;
+  let result;
+  if (extraction.kind === "inline") {
+    result = buildCombinedRouteMapWithSearch(
+      routerFilePath,
+      void 0,
+      void 0,
+      void 0,
+      extraction.block
+    );
+  } else {
+    const imported = resolveImportedVariable(routerSource, extraction.name);
+    if (imported) {
+      const targetFile = resolveImportPath(imported.specifier, routerFilePath);
+      if (!targetFile) {
+        return { routes: {}, searchSchemas: {} };
+      }
+      result = buildCombinedRouteMapWithSearch(
+        targetFile,
+        imported.exportedName
+      );
+    } else {
+      result = buildCombinedRouteMapWithSearch(routerFilePath, extraction.name);
     }
-    return buildCombinedRouteMapWithSearch(targetFile, imported.exportedName);
   }
-  return buildCombinedRouteMapWithSearch(routerFilePath, urlsVarName);
+  if (basename2) {
+    result = applyBasenameToRoutes(result, basename2);
+  }
+  return result;
 }
 function detectUnresolvableIncludes(routerFilePath) {
   const realPath = resolve2(routerFilePath);
@@ -744,9 +826,20 @@ function detectUnresolvableIncludes(routerFilePath) {
   } catch {
     return [];
   }
-  const urlsVarName = extractUrlsVariableFromRouter(source);
-  if (!urlsVarName) return [];
-  const imported = resolveImportedVariable(source, urlsVarName);
+  const extraction = extractUrlsFromRouter(source);
+  if (!extraction) return [];
+  const diagnostics = [];
+  if (extraction.kind === "inline") {
+    buildCombinedRouteMapWithSearch(
+      realPath,
+      void 0,
+      /* @__PURE__ */ new Set(),
+      diagnostics,
+      extraction.block
+    );
+    return diagnostics;
+  }
+  const imported = resolveImportedVariable(source, extraction.name);
   let targetFile;
   let exportedName;
   if (imported) {
@@ -766,9 +859,8 @@ function detectUnresolvableIncludes(routerFilePath) {
     exportedName = imported.exportedName;
   } else {
     targetFile = realPath;
-    exportedName = urlsVarName;
+    exportedName = extraction.name;
   }
-  const diagnostics = [];
   buildCombinedRouteMapWithSearch(
     targetFile,
     exportedName,
@@ -816,25 +908,15 @@ function writeCombinedRouteTypes(root, knownRouterFiles, opts) {
     throw new Error(formatNestedRouterConflictError(nestedRouterConflict));
   }
   for (const routerFilePath of routerFilePaths) {
-    let routerSource;
-    try {
-      routerSource = readFileSync3(routerFilePath, "utf-8");
-    } catch {
-      continue;
-    }
-    const urlsVarName = extractUrlsVariableFromRouter(routerSource);
-    if (!urlsVarName) continue;
-    let result;
-    const imported = resolveImportedVariable(routerSource, urlsVarName);
-    if (imported) {
-      const targetFile = resolveImportPath(imported.specifier, routerFilePath);
-      if (!targetFile) continue;
-      result = buildCombinedRouteMapWithSearch(
-        targetFile,
-        imported.exportedName
-      );
-    } else {
-      result = buildCombinedRouteMapWithSearch(routerFilePath, urlsVarName);
+    const result = buildCombinedRouteMapForRouterFile(routerFilePath);
+    if (Object.keys(result.routes).length === 0 && Object.keys(result.searchSchemas).length === 0) {
+      let routerSource;
+      try {
+        routerSource = readFileSync3(routerFilePath, "utf-8");
+      } catch {
+        continue;
+      }
+      if (!extractUrlsFromRouter(routerSource)) continue;
     }
     const routerBasename = pathBasename(routerFilePath).replace(
       /\.(tsx?|jsx?)$/,

package/dist/vite/index.js

@@ -1745,7 +1745,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.55",
+  version: "0.0.0-experimental.56",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -2317,7 +2317,7 @@ function buildRouteMapFromBlock(block, fullSource, filePath, visited, searchSche
   }
   return routeMap;
 }
-function buildCombinedRouteMapWithSearch(filePath, variableName, visited, diagnosticsOut) {
+function buildCombinedRouteMapWithSearch(filePath, variableName, visited, diagnosticsOut, inlineBlock) {
   visited = visited ?? /* @__PURE__ */ new Set();
   const realPath = resolve2(filePath);
   const key = variableName ? `${realPath}:${variableName}` : realPath;
@@ -2333,7 +2333,9 @@ function buildCombinedRouteMapWithSearch(filePath, variableName, visited, diagno
     return { routes: {}, searchSchemas: {} };
   }
   let block;
-  if (variableName) {
+  if (inlineBlock) {
+    block = inlineBlock;
+  } else if (variableName) {
     const extracted = extractUrlsBlockForVariable(source, variableName);
     if (!extracted) return { routes: {}, searchSchemas: {} };
     block = extracted;
@@ -2452,7 +2454,7 @@ Router root: ${conflict.ancestor}
 Nested router: ${conflict.nested}
 Move the nested router into a sibling directory or configure it as a separate app root.`;
 }
-function extractUrlsVariableFromRouter(code) {
+function extractUrlsFromRouter(code) {
   const sourceFile = ts5.createSourceFile(
     "router.tsx",
     code,
@@ -2466,24 +2468,70 @@ function extractUrlsVariableFromRouter(code) {
     const callee = node.expression;
     return ts5.isIdentifier(callee) && callee.text === "createRouter";
   }
+  function isInlineBuilder(node) {
+    return ts5.isArrowFunction(node) || ts5.isFunctionExpression(node);
+  }
+  function isRoutesOnCreateRouter(node) {
+    if (!ts5.isPropertyAccessExpression(node.expression) || node.expression.name.text !== "routes")
+      return false;
+    let inner = node.expression.expression;
+    while (ts5.isCallExpression(inner) && ts5.isPropertyAccessExpression(inner.expression)) {
+      inner = inner.expression.expression;
+    }
+    return isCreateRouterCall(inner);
+  }
   function visit(node) {
     if (result) return;
-    if (ts5.isCallExpression(node) && ts5.isPropertyAccessExpression(node.expression) && node.expression.name.text === "routes" && node.arguments.length >= 1 && ts5.isIdentifier(node.arguments[0])) {
-      let inner = node.expression.expression;
-      while (ts5.isCallExpression(inner) && ts5.isPropertyAccessExpression(inner.expression)) {
-        inner = inner.expression.expression;
-      }
-      if (isCreateRouterCall(inner)) {
-        result = node.arguments[0].text;
-        return;
+    if (ts5.isCallExpression(node) && node.arguments.length >= 1 && isRoutesOnCreateRouter(node)) {
+      const arg = node.arguments[0];
+      if (ts5.isIdentifier(arg)) {
+        result = { kind: "variable", name: arg.text };
+      } else if (isInlineBuilder(arg)) {
+        result = { kind: "inline", block: arg.getText(sourceFile) };
       }
+      return;
     }
     if (isCreateRouterCall(node)) {
       const callExpr = node;
-      for (const arg of callExpr.arguments) {
+      for (const callArg of callExpr.arguments) {
+        if (ts5.isObjectLiteralExpression(callArg)) {
+          for (const prop of callArg.properties) {
+            if (ts5.isPropertyAssignment(prop) && ts5.isIdentifier(prop.name) && prop.name.text === "urls") {
+              if (ts5.isIdentifier(prop.initializer)) {
+                result = { kind: "variable", name: prop.initializer.text };
+              } else if (isInlineBuilder(prop.initializer)) {
+                result = {
+                  kind: "inline",
+                  block: prop.initializer.getText(sourceFile)
+                };
+              }
+              return;
+            }
+          }
+        }
+      }
+    }
+    ts5.forEachChild(node, visit);
+  }
+  visit(sourceFile);
+  return result;
+}
+function extractBasenameFromRouter(code) {
+  const sourceFile = ts5.createSourceFile(
+    "router.tsx",
+    code,
+    ts5.ScriptTarget.Latest,
+    true,
+    ts5.ScriptKind.TSX
+  );
+  let result;
+  function visit(node) {
+    if (result !== void 0) return;
+    if (ts5.isCallExpression(node) && ts5.isIdentifier(node.expression) && node.expression.text === "createRouter") {
+      for (const arg of node.arguments) {
         if (ts5.isObjectLiteralExpression(arg)) {
           for (const prop of arg.properties) {
-            if (ts5.isPropertyAssignment(prop) && ts5.isIdentifier(prop.name) && prop.name.text === "urls" && ts5.isIdentifier(prop.initializer)) {
+            if (ts5.isPropertyAssignment(prop) && ts5.isIdentifier(prop.name) && prop.name.text === "basename" && ts5.isStringLiteral(prop.initializer)) {
               result = prop.initializer.text;
               return;
             }
@@ -2496,6 +2544,19 @@ function extractUrlsVariableFromRouter(code) {
   visit(sourceFile);
   return result;
 }
+function applyBasenameToRoutes(result, basename3) {
+  const prefixed = {};
+  for (const [name, pattern] of Object.entries(result.routes)) {
+    if (pattern === "/") {
+      prefixed[name] = basename3;
+    } else if (basename3.endsWith("/") && pattern.startsWith("/")) {
+      prefixed[name] = basename3 + pattern.slice(1);
+    } else {
+      prefixed[name] = basename3 + pattern;
+    }
+  }
+  return { routes: prefixed, searchSchemas: result.searchSchemas };
+}
 function buildCombinedRouteMapForRouterFile(routerFilePath) {
   let routerSource;
   try {
@@ -2503,19 +2564,40 @@ function buildCombinedRouteMapForRouterFile(routerFilePath) {
   } catch {
     return { routes: {}, searchSchemas: {} };
   }
-  const urlsVarName = extractUrlsVariableFromRouter(routerSource);
-  if (!urlsVarName) {
+  const extraction = extractUrlsFromRouter(routerSource);
+  if (!extraction) {
     return { routes: {}, searchSchemas: {} };
   }
-  const imported = resolveImportedVariable(routerSource, urlsVarName);
-  if (imported) {
-    const targetFile = resolveImportPath(imported.specifier, routerFilePath);
-    if (!targetFile) {
-      return { routes: {}, searchSchemas: {} };
+  const rawBasename = extractBasenameFromRouter(routerSource);
+  const basename3 = rawBasename ? ("/" + rawBasename.replace(/^\/+|\/+$/g, "")).replace(/^\/$/, "") : void 0;
+  let result;
+  if (extraction.kind === "inline") {
+    result = buildCombinedRouteMapWithSearch(
+      routerFilePath,
+      void 0,
+      void 0,
+      void 0,
+      extraction.block
+    );
+  } else {
+    const imported = resolveImportedVariable(routerSource, extraction.name);
+    if (imported) {
+      const targetFile = resolveImportPath(imported.specifier, routerFilePath);
+      if (!targetFile) {
+        return { routes: {}, searchSchemas: {} };
+      }
+      result = buildCombinedRouteMapWithSearch(
+        targetFile,
+        imported.exportedName
+      );
+    } else {
+      result = buildCombinedRouteMapWithSearch(routerFilePath, extraction.name);
     }
-    return buildCombinedRouteMapWithSearch(targetFile, imported.exportedName);
   }
-  return buildCombinedRouteMapWithSearch(routerFilePath, urlsVarName);
+  if (basename3) {
+    result = applyBasenameToRoutes(result, basename3);
+  }
+  return result;
 }
 function findRouterFiles(root, filter) {
   const result = [];
@@ -2540,25 +2622,15 @@ function writeCombinedRouteTypes(root, knownRouterFiles, opts) {
     throw new Error(formatNestedRouterConflictError(nestedRouterConflict));
   }
   for (const routerFilePath of routerFilePaths) {
-    let routerSource;
-    try {
-      routerSource = readFileSync2(routerFilePath, "utf-8");
-    } catch {
-      continue;
-    }
-    const urlsVarName = extractUrlsVariableFromRouter(routerSource);
-    if (!urlsVarName) continue;
-    let result;
-    const imported = resolveImportedVariable(routerSource, urlsVarName);
-    if (imported) {
-      const targetFile = resolveImportPath(imported.specifier, routerFilePath);
-      if (!targetFile) continue;
-      result = buildCombinedRouteMapWithSearch(
-        targetFile,
-        imported.exportedName
-      );
-    } else {
-      result = buildCombinedRouteMapWithSearch(routerFilePath, urlsVarName);
+    const result = buildCombinedRouteMapForRouterFile(routerFilePath);
+    if (Object.keys(result.routes).length === 0 && Object.keys(result.searchSchemas).length === 0) {
+      let routerSource;
+      try {
+        routerSource = readFileSync2(routerFilePath, "utf-8");
+      } catch {
+        continue;
+      }
+      if (!extractUrlsFromRouter(routerSource)) continue;
     }
     const routerBasename = pathBasename(routerFilePath).replace(
       /\.(tsx?|jsx?)$/,
@@ -3853,7 +3925,11 @@ async function discoverRouters(state, rscEnv) {
     if (!router.urlpatterns || !generateManifestFull) {
       continue;
     }
-    const manifest = generateManifestFull(router.urlpatterns, routerMountIndex);
+    const manifest = generateManifestFull(
+      router.urlpatterns,
+      routerMountIndex,
+      router.__basename ? { urlPrefix: router.__basename } : void 0
+    );
     routerMountIndex++;
     allManifests.push({ id, manifest });
     const routeCount = Object.keys(manifest.routeManifest).length;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.55",
+  "version": "0.0.0-experimental.56",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/links/SKILL.md

@@ -139,7 +139,9 @@ function GlobalNav() {
 }
 ```
 
-`href()` is an identity function at runtime but provides compile-time validation via `ValidPaths` type. Paths are validated against registered route patterns using `PatternToPath`.
+`href()` provides compile-time validation via `ValidPaths` type. Paths are validated against registered route patterns using `PatternToPath`.
+
+`href()` is a raw path helper — it is **not** basename-aware. It returns the path as-is (or with the include mount prefix via `useHref()`). For basename-aware navigation, use `Link`, `useRouter().push()`, or `reverse()`, which auto-prefix root-relative paths with the router's basename.
 
 ## Client: useHref()
 

package/skills/middleware/SKILL.md

@@ -26,6 +26,8 @@ const router = createRouter<AppEnv>({})
   .routes(urlpatterns);
 ```
 
+When the router has a `basename`, pattern-scoped `.use()` patterns are automatically prefixed. For example, with `basename: "/app"`, `.use("/admin/*", mw)` matches `/app/admin/*`.
+
 ### Route middleware (`middleware()` in `urls()`)
 
 Registered inside `urls()` callback. Wraps **rendering only** -- it does NOT wrap server action execution. Actions run before route middleware, so when route middleware executes during post-action revalidation, it can observe state that the action set (cookies, context variables, headers).

package/skills/router-setup/SKILL.md

@@ -78,6 +78,11 @@ interface RSCRouterOptions<TEnv> {
   // Document component wrapping entire app
   document?: ComponentType<{ children: ReactNode }>;
 
+  // URL prefix for sub-path deployments (e.g. "/admin")
+  // All routes, reverse(), href(), Link, redirect(), and router.use()
+  // patterns are automatically prefixed. Route names stay unprefixed.
+  basename?: string;
+
   // Enable per-request performance timeline (console waterfall + Server-Timing header)
   debugPerformance?: boolean;
 
@@ -124,6 +129,36 @@ interface RSCRouterOptions<TEnv> {
 }
 ```
 
+## Basename (Sub-Path Deployment)
+
+When your app is served under a sub-path (e.g. `/admin` or `/v2`), set `basename`:
+
+```typescript
+const router = createRouter({
+  basename: "/admin",
+  document: Document,
+}).routes(({ path, include }) => [
+  path("/", Dashboard, { name: "home" }), // matches /admin
+  path("/users", Users, { name: "users" }), // matches /admin/users
+  include("/api", apiPatterns, { name: "api" }), // matches /admin/api/*
+]);
+
+router.reverse("home"); // "/admin"
+router.reverse("users"); // "/admin/users"
+```
+
+Router-owned APIs are basename-aware:
+
+- `reverse()` returns prefixed paths
+- `<Link to="/users">` renders `<a href="/admin/users">`
+- `redirect("/login")` redirects to `"/admin/login"`
+- `router.use("/users/*", mw)` matches `/admin/users/*`
+- `useRouter().push("/users")` navigates to `/admin/users`
+- Route names stay unprefixed (`"home"`, not `"admin.home"`)
+
+Note: `href()` is a raw path helper and does **not** auto-prefix with basename.
+Use `reverse()` or `<Link>` for basename-aware URLs.
+
 ## Using the Request Handler
 
 The router provides a `fetch` method to handle RSC requests:

package/src/browser/navigation-bridge.ts

@@ -448,6 +448,12 @@ export function createNavigationBridge(
         store.setCurrentUrl(url);
         store.setPath(new URL(url).pathname);
 
+        // Restore router identity from cache so subsequent navigations
+        // don't falsely detect an app switch.
+        if (cached?.routerId) {
+          store.setRouterId?.(cached.routerId);
+        }
+
         // Render from cache - force await to skip loading fallbacks
         try {
           const root = await renderSegments(cachedSegments, {

package/src/browser/navigation-client.ts

@@ -61,6 +61,7 @@ export function createNavigationClient(
         staleRevalidation,
         interceptSourceUrl,
         version,
+        routerId,
         hmr,
       } = options;
 
@@ -88,6 +89,9 @@ export function createNavigationClient(
       if (version) {
         fetchUrl.searchParams.set("_rsc_v", version);
       }
+      if (routerId) {
+        fetchUrl.searchParams.set("_rsc_rid", routerId);
+      }
 
       // Check completed in-memory prefetch cache before making a network request.
       // The cache key includes the source URL (previousUrl) because the