@rangojs/router 0.5.1 → 0.6.0

package/README.md

@@ -439,10 +439,14 @@ For response-aware and path-based utilities (`href()`, `Rango.Path`,
 // router.tsx
 const router = createRouter<AppBindings>({}).routes(urlpatterns);
 
+// The alias is required: an interface heritage clause cannot take a `typeof`
+// type query directly (TS1109), so extend through a named alias.
+type AppRoutes = typeof router.routeMap;
+
 declare global {
   namespace Rango {
     interface Env extends AppEnv {}
-    interface RegisteredRoutes extends typeof router.routeMap {}
+    interface RegisteredRoutes extends AppRoutes {}
   }
 }
 ```

package/dist/bin/rango.js

@@ -274,6 +274,10 @@ function readSourceMemoized(memo, realPath) {
   if (memo) memo.files.set(realPath, source);
   return source;
 }
+function isUrlsDefinitionCall(node) {
+  const callee = node.expression;
+  return ts3.isIdentifier(callee) && (callee.text === "urls" || callee.text === "clientUrls");
+}
 function extractNamePrefixFromInclude(node) {
   if (node.arguments.length >= 3) {
     const thirdArg = node.arguments[2];
@@ -366,11 +370,8 @@ function resolveDefaultExportTarget(code, sourceFile) {
       const expr = node.expression;
       if (ts3.isIdentifier(expr)) {
         result = { variableName: expr.text };
-      } else if (ts3.isCallExpression(expr)) {
-        const callee = expr.expression;
-        if (ts3.isIdentifier(callee) && callee.text === "urls") {
-          result = { inlineBlock: expr.getText(sourceFile) };
-        }
+      } else if (ts3.isCallExpression(expr) && isUrlsDefinitionCall(expr)) {
+        result = { inlineBlock: expr.getText(sourceFile) };
       }
       return;
     }
@@ -441,6 +442,13 @@ function extractIncludesWithDiagnostics(code, sourceFileArg) {
   return { resolved, unresolvable };
 }
 function resolveImportedVariable(code, localName) {
+  const defaultImportRegex = /import\s+([\w$]+)\s*(?:,\s*\{[^}]*\})?\s+from\s*["']([^"']+)["']/g;
+  let defaultMatch;
+  while ((defaultMatch = defaultImportRegex.exec(code)) !== null) {
+    if (defaultMatch[1] === localName) {
+      return { specifier: defaultMatch[2], exportedName: "default" };
+    }
+  }
   const importRegex = /import\s*(?:[\w$]+\s*,\s*)?\{([^}]+)\}\s*from\s*["']([^"']+)["']/g;
   let match;
   while ((match = importRegex.exec(code)) !== null) {
@@ -490,8 +498,7 @@ function extractUrlsBlockForVariable(code, varName, sourceFileArg) {
   function visit(node) {
     if (result) return;
     if (ts3.isVariableDeclaration(node) && ts3.isIdentifier(node.name) && node.name.text === varName && node.initializer && ts3.isCallExpression(node.initializer)) {
-      const callee = node.initializer.expression;
-      if (ts3.isIdentifier(callee) && callee.text === "urls") {
+      if (isUrlsDefinitionCall(node.initializer)) {
         result = node.initializer.getText(sourceFile);
         return;
       }
@@ -707,6 +714,48 @@ function buildCombinedRouteMapWithSearch(filePath, variableName, visited, diagno
   let block;
   if (inlineBlock) {
     block = inlineBlock;
+  } else if (variableName === "default") {
+    const defaultTarget = resolveDefaultExportTarget(
+      source,
+      parseBlock(memo, source)
+    );
+    if (!defaultTarget) {
+      visited.delete(key);
+      return { routes: {}, searchSchemas: {} };
+    }
+    if (defaultTarget.inlineBlock) {
+      block = defaultTarget.inlineBlock;
+    } else {
+      const targetName = defaultTarget.variableName;
+      const imported = resolveImportedVariable(source, targetName);
+      if (imported) {
+        const targetFile = resolveImportPath(imported.specifier, realPath);
+        if (!targetFile) {
+          visited.delete(key);
+          return { routes: {}, searchSchemas: {} };
+        }
+        const result = buildCombinedRouteMapWithSearch(
+          targetFile,
+          imported.exportedName,
+          visited,
+          diagnosticsOut,
+          void 0,
+          memo
+        );
+        visited.delete(key);
+        return result;
+      }
+      const extracted = extractUrlsBlockForVariable(
+        source,
+        targetName,
+        parseBlock(memo, source)
+      );
+      if (!extracted) {
+        visited.delete(key);
+        return { routes: {}, searchSchemas: {} };
+      }
+      block = extracted;
+    }
   } else if (variableName) {
     const extracted = extractUrlsBlockForVariable(
       source,
@@ -754,7 +803,7 @@ function findUrlsVariableNames(code) {
   function visit(node) {
     if (ts4.isVariableDeclaration(node) && ts4.isIdentifier(node.name) && node.initializer && ts4.isCallExpression(node.initializer)) {
       const callee = node.initializer.expression;
-      if (ts4.isIdentifier(callee) && callee.text === "urls") {
+      if (ts4.isIdentifier(callee) && (callee.text === "urls" || callee.text === "clientUrls")) {
         names.push(node.name.text);
       }
     }
@@ -766,7 +815,7 @@ function findUrlsVariableNames(code) {
 function writePerModuleRouteTypesForFile(filePath) {
   try {
     const source = readFileSync2(filePath, "utf-8");
-    if (!source.includes("urls(")) return;
+    if (!source.includes("urls(") && !source.includes("clientUrls(")) return;
     const varNames = findUrlsVariableNames(source);
     let routes;
     if (varNames.length > 0) {
@@ -1057,7 +1106,33 @@ 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 extractUrlsFromRouter(code) {
+function isCreateRouterCall(node) {
+  if (!ts5.isCallExpression(node)) return false;
+  const callee = node.expression;
+  return ts5.isIdentifier(callee) && callee.text === "createRouter";
+}
+function extractUrlsArgument(node, sourceFile) {
+  if (ts5.isIdentifier(node)) {
+    return { kind: "variable", name: node.text };
+  }
+  if (ts5.isArrowFunction(node) || ts5.isFunctionExpression(node)) {
+    return { kind: "inline", block: node.getText(sourceFile) };
+  }
+  return null;
+}
+function collectCreateRouterCallChain(endpoint) {
+  const calls = [];
+  let current = endpoint;
+  while (true) {
+    calls.push(current);
+    if (isCreateRouterCall(current)) return calls.reverse();
+    if (!ts5.isPropertyAccessExpression(current.expression)) return null;
+    const receiver = current.expression.expression;
+    if (!ts5.isCallExpression(receiver)) return null;
+    current = receiver;
+  }
+}
+function extractAllUrlsFromRouter(code) {
   const sourceFile = ts5.createSourceFile(
     "router.tsx",
     code,
@@ -1066,58 +1141,45 @@ function extractUrlsFromRouter(code) {
     ts5.ScriptKind.TSX
   );
   let result = null;
-  function isCreateRouterCall(node) {
-    if (!ts5.isCallExpression(node)) return false;
-    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) && 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 callArg of callExpr.arguments) {
-        if (ts5.isObjectLiteralExpression(callArg)) {
+    if (ts5.isCallExpression(node)) {
+      const chain = collectCreateRouterCallChain(node);
+      if (chain) {
+        const extracted = [];
+        const createRouterCall = chain[0];
+        for (const callArg of createRouterCall.arguments) {
+          if (!ts5.isObjectLiteralExpression(callArg)) continue;
           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;
+            if (!ts5.isPropertyAssignment(prop) || !ts5.isIdentifier(prop.name) || prop.name.text !== "urls") {
+              continue;
             }
+            const urls = extractUrlsArgument(prop.initializer, sourceFile);
+            if (urls) extracted.push(urls);
+            break;
           }
         }
+        for (const call of chain.slice(1)) {
+          if (!ts5.isPropertyAccessExpression(call.expression) || call.expression.name.text !== "routes" || call.arguments.length === 0) {
+            continue;
+          }
+          const urls = extractUrlsArgument(call.arguments[0], sourceFile);
+          if (urls) extracted.push(urls);
+        }
+        if (extracted.length > 0) {
+          result = extracted;
+          return;
+        }
       }
     }
     ts5.forEachChild(node, visit);
   }
   visit(sourceFile);
-  return result;
+  return result ?? [];
+}
+function extractUrlsFromRouter(code) {
+  const extractions = extractAllUrlsFromRouter(code);
+  return extractions[extractions.length - 1] ?? null;
 }
 function extractBasenameFromRouter(code) {
   const sourceFile = ts5.createSourceFile(
@@ -1160,6 +1222,59 @@ function applyBasenameToRoutes(result, basename) {
   }
   return { routes: prefixed, searchSchemas: result.searchSchemas };
 }
+function resolveRouterUrlsExtraction(routerFilePath, routerSource, extraction, diagnosticsOut, memo) {
+  if (extraction.kind === "inline") {
+    return buildCombinedRouteMapWithSearch(
+      routerFilePath,
+      void 0,
+      /* @__PURE__ */ new Set(),
+      diagnosticsOut,
+      extraction.block,
+      memo
+    );
+  }
+  const imported = resolveImportedVariable(routerSource, extraction.name);
+  if (imported) {
+    const targetFile = resolveImportPath(imported.specifier, routerFilePath);
+    if (!targetFile) {
+      diagnosticsOut?.push({
+        pathPrefix: "/",
+        namePrefix: null,
+        reason: "file-not-found",
+        sourceFile: routerFilePath,
+        detail: `import "${imported.specifier}" resolved to no file`
+      });
+      return { routes: {}, searchSchemas: {} };
+    }
+    return buildCombinedRouteMapWithSearch(
+      targetFile,
+      imported.exportedName,
+      /* @__PURE__ */ new Set(),
+      diagnosticsOut,
+      void 0,
+      memo
+    );
+  }
+  return buildCombinedRouteMapWithSearch(
+    routerFilePath,
+    extraction.name,
+    /* @__PURE__ */ new Set(),
+    diagnosticsOut,
+    void 0,
+    memo
+  );
+}
+function mergeRouteMaps(target, source) {
+  for (const [name, pattern] of Object.entries(source.routes)) {
+    target.routes[name] = pattern;
+    const search = source.searchSchemas[name];
+    if (search) {
+      target.searchSchemas[name] = search;
+    } else {
+      delete target.searchSchemas[name];
+    }
+  }
+}
 function genFileTsPath(sourceFile) {
   const base = pathBasename(sourceFile).replace(/\.(tsx?|jsx?)$/, "");
   return join2(dirname2(sourceFile), `${base}.named-routes.gen.ts`);
@@ -1186,38 +1301,28 @@ function buildCombinedRouteMapForRouterFile(routerFilePath) {
   } catch {
     return { routes: {}, searchSchemas: {} };
   }
-  const extraction = extractUrlsFromRouter(routerSource);
-  if (!extraction) {
+  const extractions = extractAllUrlsFromRouter(routerSource);
+  if (extractions.length === 0) {
     return { routes: {}, searchSchemas: {} };
   }
   const rawBasename = extractBasenameFromRouter(routerSource);
   const basename = rawBasename ? ("/" + rawBasename.replace(/^\/+|\/+$/g, "")).replace(/^\/$/, "") : void 0;
-  let result;
-  if (extraction.kind === "inline") {
-    result = buildCombinedRouteMapWithSearch(
-      routerFilePath,
-      void 0,
-      void 0,
-      void 0,
-      extraction.block
+  const result = { routes: {}, searchSchemas: {} };
+  const memo = createScanMemo();
+  for (const extraction of extractions) {
+    mergeRouteMaps(
+      result,
+      resolveRouterUrlsExtraction(
+        routerFilePath,
+        routerSource,
+        extraction,
+        void 0,
+        memo
+      )
     );
-  } 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);
-    }
   }
   if (basename) {
-    result = applyBasenameToRoutes(result, basename);
+    return applyBasenameToRoutes(result, basename);
   }
   return result;
 }
@@ -1229,47 +1334,19 @@ function detectUnresolvableIncludes(routerFilePath) {
   } catch {
     return [];
   }
-  const extraction = extractUrlsFromRouter(source);
-  if (!extraction) return [];
+  const extractions = extractAllUrlsFromRouter(source);
+  if (extractions.length === 0) return [];
   const diagnostics = [];
-  if (extraction.kind === "inline") {
-    buildCombinedRouteMapWithSearch(
+  const memo = createScanMemo();
+  for (const extraction of extractions) {
+    resolveRouterUrlsExtraction(
       realPath,
-      void 0,
-      /* @__PURE__ */ new Set(),
+      source,
+      extraction,
       diagnostics,
-      extraction.block
+      memo
     );
-    return diagnostics;
-  }
-  const imported = resolveImportedVariable(source, extraction.name);
-  let targetFile;
-  let exportedName;
-  if (imported) {
-    const resolved = resolveImportPath(imported.specifier, realPath);
-    if (!resolved) {
-      return [
-        {
-          pathPrefix: "/",
-          namePrefix: null,
-          reason: "file-not-found",
-          sourceFile: realPath,
-          detail: `import "${imported.specifier}" resolved to no file`
-        }
-      ];
-    }
-    targetFile = resolved;
-    exportedName = imported.exportedName;
-  } else {
-    targetFile = realPath;
-    exportedName = extraction.name;
   }
-  buildCombinedRouteMapWithSearch(
-    targetFile,
-    exportedName,
-    /* @__PURE__ */ new Set(),
-    diagnostics
-  );
   return diagnostics;
 }
 function detectUnresolvableIncludesForUrlsFile(filePath) {
@@ -1390,6 +1467,138 @@ var init_generate_route_types = __esm({
   }
 });
 
+// src/build/merge-full-manifests.ts
+function clonePrefixNode(node) {
+  return {
+    staticPrefix: node.staticPrefix,
+    fullPrefix: node.fullPrefix,
+    ...node.namePrefix === void 0 ? {} : { namePrefix: node.namePrefix },
+    children: clonePrefixTree(node.children),
+    routes: [...node.routes]
+  };
+}
+function clonePrefixTree(tree) {
+  return Object.fromEntries(
+    Object.entries(tree).map(([prefix, node]) => [
+      prefix,
+      clonePrefixNode(node)
+    ])
+  );
+}
+function removeRoutesFromPrefixTree(tree, routeNames) {
+  return Object.fromEntries(
+    Object.entries(tree).map(([prefix, node]) => [
+      prefix,
+      {
+        staticPrefix: node.staticPrefix,
+        fullPrefix: node.fullPrefix,
+        ...node.namePrefix === void 0 ? {} : { namePrefix: node.namePrefix },
+        children: removeRoutesFromPrefixTree(node.children, routeNames),
+        routes: node.routes.filter((name) => !routeNames.has(name))
+      }
+    ])
+  );
+}
+function mergePrefixTrees(earlier, later) {
+  const merged = clonePrefixTree(earlier);
+  for (const [prefix, laterNode] of Object.entries(later)) {
+    const earlierNode = merged[prefix];
+    if (!earlierNode) {
+      merged[prefix] = clonePrefixNode(laterNode);
+      continue;
+    }
+    merged[prefix] = {
+      staticPrefix: laterNode.staticPrefix,
+      fullPrefix: laterNode.fullPrefix,
+      ...laterNode.namePrefix === void 0 ? {} : { namePrefix: laterNode.namePrefix },
+      children: mergePrefixTrees(earlierNode.children, laterNode.children),
+      routes: [.../* @__PURE__ */ new Set([...earlierNode.routes, ...laterNode.routes])]
+    };
+  }
+  return merged;
+}
+function mergeRouteRecord(earlier, later, overwrittenRoutes, cloneValue) {
+  const merged = {};
+  for (const [name, value] of Object.entries(earlier ?? {})) {
+    if (!overwrittenRoutes.has(name)) merged[name] = cloneValue(value);
+  }
+  for (const [name, value] of Object.entries(later ?? {})) {
+    merged[name] = cloneValue(value);
+  }
+  return Object.keys(merged).length > 0 ? merged : void 0;
+}
+function mergeRouteList(earlier, later, overwrittenRoutes) {
+  const merged = [
+    ...(earlier ?? []).filter((name) => !overwrittenRoutes.has(name)),
+    ...later ?? []
+  ];
+  const unique = [...new Set(merged)];
+  return unique.length > 0 ? unique : void 0;
+}
+function mergeFullManifests(manifests) {
+  let merged = {
+    prefixTree: {},
+    routeManifest: {}
+  };
+  for (const manifest of manifests) {
+    const overwrittenRoutes = new Set(Object.keys(manifest.routeManifest));
+    const prefixTreeWithoutOverwrites = removeRoutesFromPrefixTree(
+      merged.prefixTree,
+      overwrittenRoutes
+    );
+    merged = {
+      prefixTree: mergePrefixTrees(
+        prefixTreeWithoutOverwrites,
+        manifest.prefixTree
+      ),
+      routeManifest: {
+        ...merged.routeManifest,
+        ...manifest.routeManifest
+      },
+      routeTrailingSlash: mergeRouteRecord(
+        merged.routeTrailingSlash,
+        manifest.routeTrailingSlash,
+        overwrittenRoutes,
+        (value) => value
+      ),
+      prerenderRoutes: mergeRouteList(
+        merged.prerenderRoutes,
+        manifest.prerenderRoutes,
+        overwrittenRoutes
+      ),
+      passthroughRoutes: mergeRouteList(
+        merged.passthroughRoutes,
+        manifest.passthroughRoutes,
+        overwrittenRoutes
+      ),
+      responseTypeRoutes: mergeRouteRecord(
+        merged.responseTypeRoutes,
+        manifest.responseTypeRoutes,
+        overwrittenRoutes,
+        (value) => value
+      ),
+      routeSearchSchemas: mergeRouteRecord(
+        merged.routeSearchSchemas,
+        manifest.routeSearchSchemas,
+        overwrittenRoutes,
+        (value) => ({ ...value })
+      ),
+      _prerenderDefs: mergeRouteRecord(
+        merged._prerenderDefs,
+        manifest._prerenderDefs,
+        overwrittenRoutes,
+        (value) => value
+      )
+    };
+  }
+  return merged;
+}
+var init_merge_full_manifests = __esm({
+  "src/build/merge-full-manifests.ts"() {
+    "use strict";
+  }
+});
+
 // src/vite/plugins/virtual-entries.ts
 function getVirtualVersionContent(version) {
   return `export const VERSION = ${JSON.stringify(version)};`;
@@ -1798,20 +2007,28 @@ async function discoverAndWriteRouteTypes(opts) {
       );
     }
     const buildMod = await rscEnv.runner.import("@rangojs/router/build");
-    const generateManifest = buildMod.generateManifest;
-    if (!generateManifest) {
-      throw new Error("generateManifest not found in @rangojs/router/build");
+    const generateManifestFull = buildMod.generateManifestFull;
+    if (!generateManifestFull) {
+      throw new Error(
+        "generateManifestFull not found in @rangojs/router/build"
+      );
     }
     const outputFiles = [];
     let totalRouteCount = 0;
-    let routerMountIndex = 0;
+    let globalMountIndex = 0;
+    let routerCount = 0;
     for (const [id, router] of registry) {
-      if (!router.urlpatterns) continue;
-      const manifest = await generateManifest(
-        router.urlpatterns,
-        routerMountIndex
-      );
-      routerMountIndex++;
+      const mounts = router.__urlpatternMounts ?? (router.urlpatterns ? [{ patterns: router.urlpatterns }] : []);
+      if (mounts.length === 0) continue;
+      const mountManifests = [];
+      for (const mount of mounts) {
+        mountManifests.push(
+          await generateManifestFull(mount.patterns, globalMountIndex)
+        );
+        globalMountIndex++;
+      }
+      const manifest = mergeFullManifests(mountManifests);
+      routerCount++;
       const rawManifest = manifest.routeManifest;
       const routeManifest = {};
       for (const [name, pattern] of Object.entries(rawManifest)) {
@@ -1856,7 +2073,7 @@ Set an explicit \`id\` on createRouter() or check the call site.`
       );
     }
     return {
-      routerCount: routerMountIndex,
+      routerCount,
       routeCount: totalRouteCount,
       outputFiles
     };
@@ -1870,6 +2087,7 @@ var init_runtime_discovery = __esm({
   "src/build/runtime-discovery.ts"() {
     "use strict";
     init_generate_route_types();
+    init_merge_full_manifests();
     init_route_name();
   }
 });
@@ -1982,7 +2200,7 @@ function runStaticGeneration(args, mode) {
       if (/\bcreateRouter\s*[<(]/.test(source)) {
         routerFiles.push(filePath);
       }
-      if (source.includes("urls(")) {
+      if (source.includes("urls(") || source.includes("clientUrls(")) {
         urlsFiles.push(filePath);
       }
     } catch (err) {
@@ -2070,7 +2288,7 @@ async function runRuntimeDiscovery(args, configFile) {
       if (/\bcreateRouter\s*[<(]/.test(source)) {
         routerEntries.push(filePath);
       }
-      if (source.includes("urls(")) {
+      if (source.includes("urls(") || source.includes("clientUrls(")) {
         writePerModuleRouteTypesForFile(filePath);
       }
     } catch {

package/dist/types/browser/event-controller.d.ts

@@ -180,6 +180,12 @@ export interface EventController {
     subscribe(listener: StateListener): () => void;
     subscribeToAction(actionId: string, listener: ActionStateListener): () => void;
     subscribeToHandles(listener: HandleListener): () => void;
+    /**
+     * Deliver queued location, params, navigation, and handle notifications now.
+     * NavigationProvider calls this inside the payload update so React assigns
+     * every route-state hook update to the same normal or transition lane.
+     */
+    flushRouteState(): void;
     setHandleData(data: HandleData, matched?: string[], isPartial?: boolean, 
     /**
      * Segment ids that were re-resolved on the server this request (the

package/dist/types/browser/react/use-router.d.ts

@@ -2,8 +2,8 @@ import type { RouterInstance } from "../types.js";
 /**
  * Hook to access router actions (push, replace, refresh, prefetch, back, forward).
  *
- * Returns a STABLE reference that never changes, so components using
- * useRouter() do not re-render on navigation state changes.
+ * Returns a STABLE reference per component, so components using useRouter()
+ * do not re-render on navigation state changes.
  * For reactive navigation state, use useNavigation() instead.
  *
  * Methods read `basename` from the context on each call. It is set once from
@@ -11,10 +11,17 @@ import type { RouterInstance } from "../types.js";
  * is a full document load (X-RSC-Reload), so the target app mounts fresh with
  * its own basename.
  *
+ * RELATIVE paths (no leading `/`, no scheme/query/hash) resolve against the
+ * current include() mount: `router.push("cart")` inside `include("/shop")`
+ * navigates to `/shop/cart`. Absolute paths stay APP-absolute — unlike
+ * basename, the mount is scoped, and absolute pushes legitimately target
+ * outside it, so they are never auto-prefixed.
+ *
  * @example
  * ```tsx
  * const router = useRouter();
- * router.push("/products");
+ * router.push("/products");   // app-absolute
+ * router.push("cart");        // mount-relative
  * router.replace("/login", { scroll: false });
  * router.prefetch("/dashboard");
  * router.back();