@rangojs/router 0.30.0 → 0.31.0

package/dist/types/build/generate-route-types.d.ts

@@ -4,5 +4,5 @@ export { generatePerModuleTypesSource, generateRouteTypesSource, } from "./route
 export { DEFAULT_EXCLUDE_PATTERNS, type ScanFilter, createScanFilter, findTsFiles, isInSkippedScanDir, } from "./route-types/scan-filter.js";
 export { writePerModuleRouteTypes, writePerModuleRouteTypesForFile, } from "./route-types/per-module-writer.js";
 export { type UnresolvableReason, type UnresolvableInclude, extractIncludesWithDiagnostics, } from "./route-types/include-resolution.js";
-export { extractUrlsFromRouter, extractBasenameFromRouter, type UrlsExtractionResult, buildCombinedRouteMapForRouterFile, detectUnresolvableIncludes, detectUnresolvableIncludesForUrlsFile, findNestedRouterConflict, formatNestedRouterConflictError, findRouterFiles, findHostRouterFiles, writeCombinedRouteTypes, genFileTsPath, resolveSearchSchemas, } from "./route-types/router-processing.js";
+export { extractUrlsFromRouter, type UrlsExtractionResult, buildCombinedRouteMapForRouterFile, detectUnresolvableIncludes, detectUnresolvableIncludesForUrlsFile, findNestedRouterConflict, formatNestedRouterConflictError, findRouterFiles, findHostRouterFiles, writeCombinedRouteTypes, genFileTsPath, resolveSearchSchemas, } from "./route-types/router-processing.js";
 export { findUrlsVariableNames } from "./route-types/per-module-writer.js";

package/dist/types/build/route-types/include-resolution.d.ts

@@ -1,5 +1,5 @@
 import ts from "typescript";
-export type UnresolvableReason = "factory-call" | "dynamic-expression" | "unresolvable-import" | "file-not-found";
+export type UnresolvableReason = "factory-call" | "dynamic-expression" | "unresolvable-import" | "file-not-found" | "unresolvable-basename";
 export interface UnresolvableInclude {
     pathPrefix: string;
     namePrefix: string | null;

package/dist/types/build/route-types/router-processing.d.ts

@@ -30,11 +30,6 @@ export type UrlsExtractionResult = {
  * Returns either a variable name or an inline code block.
  */
 export declare function extractUrlsFromRouter(code: string): UrlsExtractionResult | null;
-/**
- * Extract the `basename` string literal from createRouter({ basename: "..." }).
- * Returns the basename value or undefined if not present.
- */
-export declare function extractBasenameFromRouter(code: string): string | undefined;
 export declare function genFileTsPath(sourceFile: string): string;
 export declare function resolveSearchSchemas(publicRouteNames: string[], runtimeSchemas: Record<string, Record<string, string>> | undefined, sourceFile: string): Record<string, Record<string, string>> | undefined;
 /**
@@ -47,8 +42,9 @@ export declare function buildCombinedRouteMapForRouterFile(routerFilePath: strin
 };
 /**
  * Walk the full include tree starting from a router file and detect
- * all includes that the static parser cannot resolve.
- * Returns an array of diagnostics; empty means fully resolvable.
+ * all includes that the static parser cannot resolve, plus an explicit
+ * createRouter `basename` it cannot read (every pattern would lack the
+ * prefix). Returns an array of diagnostics; empty means fully resolvable.
  */
 export declare function detectUnresolvableIncludes(routerFilePath: string): UnresolvableInclude[];
 /**

package/dist/types/suspense-audit.d.ts

@@ -68,6 +68,19 @@ export interface BoundaryAudit {
     /** The fallback's effect was cleaned up in this task (auditFallback). */
     fallbackGone: boolean;
 }
+/**
+ * One loaded copy of this module. A test that re-imports the module after
+ * vi.resetModules() runs two, and the one its static imports use is not the
+ * one on `__rangoSuspenseAudit`. The router's unit-test lock resets and
+ * checks each (src/__tests__/kit/suspense-audit-lock.ts).
+ */
+export interface SuspenseAuditInstance {
+    /** The violation counters above zero and the last events, if any. */
+    violations(): string | undefined;
+    forget(): void;
+    /** Resolves once the judgments queued so far have run. */
+    settle(): Promise<void>;
+}
 export declare function createBoundaryAudit(boundary: string, segmentId: string): BoundaryAudit;
 /**
  * Render phase: the value this render hands the boundary.
@@ -153,5 +166,10 @@ export declare function auditTreeCause(cause: TreeUpdateCause): void;
  * readers subscribe to, or through a pending promise read with use().
  */
 export declare function auditTreeUpdate(root?: unknown): void;
-/** Forget every tree and mount seen so far. For tests of the audit itself. */
+/**
+ * Forget every tree, mount, hand-over and count seen so far: the root that
+ * held them is gone. A test unmounts its root, production never does
+ * (testing/render-route.tsx, src/__tests__/kit/suspense-audit-lock.ts).
+ * Creates no report: with the audit off there is none.
+ */
 export declare function forgetSuspenseAudit(): void;

package/dist/types/vite/discovery/build-versions.d.ts

@@ -194,22 +194,26 @@ export declare function isSourceMap(fileName: string): boolean;
  * hashed by the routers that reach it (resolveRouterMembers), so nothing the
  * map says is lost by skipping it.
  *
- * Works on the region comments, so a minified server build (which has none)
- * keeps the map in every router's hash: more clearing, never less.
+ * Works on the module markers, so a minified server build (which has none),
+ * or a map no marker follows, keeps the map in every router's hash: more
+ * clearing, never less.
  */
 export declare function stripServerReferenceMap(source: string): string;
 /**
- * Take the module paths out of a chunk's region comments.
+ * Take the module paths out of a chunk's module markers.
  *
- * The bundler prints one before each module's code, and the path says where
- * the build ran, not what it built: it is relative to the directory `vite
- * build` was started from (`vite build apps/web` from a repository root
- * prints other paths than `vite build` in the app), it holds the pnpm store
- * directory with its peer suffix, and a virtual id is printed verbatim,
- * absolute paths in its query included. The code under the comment is hashed
- * either way.
+ * The path says where the build ran, not what it built: it is relative to the
+ * directory `vite build` was started from (`vite build apps/web` from a
+ * repository root prints other paths than `vite build` in the app), it holds
+ * the pnpm store directory with its peer suffix, and a virtual id is printed
+ * verbatim, absolute paths in its query included. The code after the marker
+ * is hashed either way.
+ *
+ * A `//#region` line is always a marker. A `// ` line is one only when it
+ * names a module of the chunk (`moduleIds`): a kept comment or a line of a
+ * multi-line string can start the same way, and is hashed.
  */
-export declare function stripRegionPaths(source: string): string;
+export declare function stripModulePaths(source: string, moduleIds: readonly string[]): string;
 /** One thing a version is a hash of: its name and the digest of its bytes. */
 export type VersionInput = readonly [name: string, digest: string];
 /** One bundle file, digested once for every router. */
@@ -237,8 +241,8 @@ export interface DigestedFile {
  *
  * Three things are taken out of a chunk's text first, each because it says
  * where or how the build ran: the server-reference map's body
- * ({@link stripServerReferenceMap}), the paths in region comments
- * ({@link stripRegionPaths}), and the hashed names of bundle files. A name
+ * ({@link stripServerReferenceMap}), the paths in module markers
+ * ({@link stripModulePaths}), and the hashed names of bundle files. A name
  * carries the content hash of its file, and every chunk importing the file
  * has the name in its bytes, so one router's change would otherwise move the
  * digest of every chunk naming its chunk. Only names with a content hash are

package/dist/types/vite/plugins/stable-rsc-output.d.ts

@@ -41,7 +41,7 @@ export declare function canonicalAssetsManifestBinding(code: string): string | u
  *    (`ServerReferencesManager.claimMap`), which varies with the concurrent
  *    scan builds (e2e/test-app: 2 of 2 consecutive builds differed). Sorted
  *    here so a minified server build, where stripServerReferenceMap finds no
- *    region comments, still hashes the same bytes.
+ *    module markers, still hashes the same bytes.
  * 2. Local name of the assets-manifest import. plugin-rsc imports the manifest
  *    under three names; the bundler merges them into one import per chunk and
  *    keeps a different one from build to build (the cache-versions fixture:

package/dist/types/vite/temp-rsc-server.d.ts

@@ -1,12 +1,14 @@
 /**
  * The discovery temp RSC server: a minimal Vite server whose module runner
  * imports the user's router files. Shared by dev discovery
- * (discovery/dev-server-phase.ts) and build discovery
- * (discovery/build-discovery-phase.ts).
+ * (discovery/dev-server-phase.ts), build discovery
+ * (discovery/build-discovery-phase.ts) and `rango generate --runtime`
+ * (build/runtime-discovery.ts).
  *
  * Sits in src/vite/, not src/vite/discovery/: the loader hook URL below
- * resolves against this module's import.meta.url, and the published bundle
- * (dist/vite/index.js) ships the hook at the same relative path.
+ * resolves against this module's import.meta.url, and the published bundles
+ * (dist/vite/index.js, dist/bin/rango.js) ship the hook at the same relative
+ * path.
  */
 import type { ViteDevServer } from "vite";
 import type { DiscoveryState } from "./discovery/state.js";
@@ -36,4 +38,6 @@ export declare function createTempRscServer(state: DiscoveryState, options?: {
      * shell capture actually runs.
      */
     realSsrEntry?: boolean;
+    /** Caller-specific plugins, appended after the forwarded user plugins. */
+    plugins?: import("vite").Plugin[];
 }): Promise<ViteDevServer>;

package/dist/types/vite/utils/forward-user-plugins.d.ts

@@ -20,6 +20,8 @@ export interface ForwardedRunnerConfig {
 /**
  * Extract the data-only config slice to mirror into the discovery temp server.
  * `alias` is included here so callers no longer need to thread it separately.
+ * Accepts the unresolved config too: `rango generate --runtime` must not
+ * resolve it (that runs rango()'s configResolved, which writes gen files).
  *
  * `tsconfigPaths` is forwarded so Vite 8's native tsconfig `paths` resolution
  * (a top-level `resolve` flag, off by default) reaches the temp server. The
@@ -34,4 +36,4 @@ export interface ForwardedRunnerConfig {
  * replaced the deprecated `esbuild` transform option with `oxc`, so we read and
  * forward `oxc` exclusively — no `esbuild` field is touched.
  */
-export declare function pickForwardedRunnerConfig(config: ResolvedConfig): ForwardedRunnerConfig;
+export declare function pickForwardedRunnerConfig(config: Pick<ResolvedConfig | UserConfig, "resolve" | "define" | "oxc">): ForwardedRunnerConfig;

package/dist/vite/index.js

@@ -4841,6 +4841,11 @@ function getAppVersion() {
 }
 
 // src/router/basename.ts
+function normalizeBasename(basename2) {
+  if (!basename2) return void 0;
+  const trimmed = basename2.replace(/^\/+|\/+$/g, "");
+  return trimmed ? "/" + trimmed : void 0;
+}
 function prefixBasename(path6, basename2) {
   if (!basename2 || !path6.startsWith("/") || path6 === basename2 || path6.startsWith(basename2 + "/") || path6.startsWith(basename2 + "?") || path6.startsWith(basename2 + "#")) {
     return path6;
@@ -5988,7 +5993,7 @@ function serializeSearchSchema(route2, value) {
     throw projectionError(route2, 'path option "search" must be an object');
   }
   const entries = [];
-  for (const key of Object.keys(value).sort()) {
+  for (const key of Object.keys(value)) {
     const schemaValue = value[key];
     if (typeof schemaValue !== "string" || !SEARCH_SCHEMA_VALUES.has(schemaValue)) {
       throw projectionError(
@@ -7141,7 +7146,7 @@ function resolveVersionsFrom(table, routerId2) {
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.30.0",
+  version: "0.31.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -7334,7 +7339,7 @@ var package_default = {
     tag: "latest"
   },
   scripts: {
-    build: "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    build: "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js && mkdir -p dist/bin/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/bin/plugins/cloudflare-protocol-loader-hook.mjs",
     "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
     prepublishOnly: "pnpm build",
     typecheck: "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
@@ -8053,20 +8058,39 @@ var SERVER_CSS_MODULE = /^virtual:vite-rsc\/css\?type=rsc&id=([^&]+)/;
 function isSourceMap(fileName) {
   return fileName.endsWith(".map");
 }
-var SERVER_REFERENCES_REGION_START = `//#region \\0${SERVER_REFERENCES_MODULE_ID.slice(1)}
-`;
-var REGION_END = "//#endregion";
+var MODULE_MARKER = /^\/\/(#region)? (.+)$/gm;
+var SERVER_REFERENCE_MAP = new RegExp(
+  `(^//(?:#region)? ${escapeRegExp(`\\0${SERVER_REFERENCES_MODULE_ID.slice(1)}`)}
+)[\\s\\S]*?(?=^//(?: |#endregion))`,
+  "m"
+);
 function stripServerReferenceMap(source) {
-  const start = source.indexOf(SERVER_REFERENCES_REGION_START);
-  if (start === -1) return source;
-  const bodyStart = start + SERVER_REFERENCES_REGION_START.length;
-  const end = source.indexOf(REGION_END, bodyStart);
-  if (end === -1) return source;
-  return source.slice(0, bodyStart) + source.slice(end);
+  return source.replace(SERVER_REFERENCE_MAP, "$1");
+}
+function printedModuleIds(moduleIds) {
+  const printed = /* @__PURE__ */ new Set();
+  for (const id of moduleIds) {
+    if (!isAbsolutePath(id)) {
+      printed.add(id.replaceAll("\0", "\\0"));
+      continue;
+    }
+    const segments = id.replaceAll("\\", "/").split("/");
+    for (let index = 0; index < segments.length; index++) {
+      printed.add(segments.slice(index).join("/"));
+    }
+  }
+  return printed;
 }
-var REGION_LINE = /^\/\/#region .*$/gm;
-function stripRegionPaths(source) {
-  return source.replace(REGION_LINE, "//#region");
+function stripModulePaths(source, moduleIds) {
+  let printed;
+  return source.replace(
+    MODULE_MARKER,
+    (line, region, name) => {
+      if (region) return "//#region";
+      printed ??= printedModuleIds(moduleIds);
+      return printed.has(name.replace(/^(?:\.\.\/)+/, "")) ? "//" : line;
+    }
+  );
 }
 var FILE_REFERENCE = "\0";
 var FOREIGN_FILE = "~";
@@ -8118,8 +8142,9 @@ function digestBundle(bundle, projectRoot, read, label) {
       };
     }
     const references = [];
-    const text = stripRegionPaths(
-      stripServerReferenceMap(decoder3.decode(bytes))
+    const text = stripModulePaths(
+      stripServerReferenceMap(decoder3.decode(bytes)),
+      chunk.moduleIds
     );
     const blanked = reference ? text.replace(reference, (name) => {
       references.push(fileOfBaseName.get(name));
@@ -9305,14 +9330,7 @@ function collectCreateRouterCallChain(endpoint) {
     current = receiver;
   }
 }
-function extractAllUrlsFromRouter(code) {
-  const sourceFile = ts5.createSourceFile(
-    "router.tsx",
-    code,
-    ts5.ScriptTarget.Latest,
-    true,
-    ts5.ScriptKind.TSX
-  );
+function findRouterUrls(sourceFile) {
   let result = null;
   function visit(node) {
     if (result) return;
@@ -9340,7 +9358,7 @@ function extractAllUrlsFromRouter(code) {
           if (urls2) extracted.push(urls2);
         }
         if (extracted.length > 0) {
-          result = extracted;
+          result = { createRouterCall, extractions: extracted };
           return;
         }
       }
@@ -9348,13 +9366,9 @@ function extractAllUrlsFromRouter(code) {
     ts5.forEachChild(node, visit);
   }
   visit(sourceFile);
-  return result ?? [];
-}
-function extractUrlsFromRouter(code) {
-  const extractions = extractAllUrlsFromRouter(code);
-  return extractions[extractions.length - 1] ?? null;
+  return result;
 }
-function extractBasenameFromRouter(code) {
+function extractAllUrlsFromRouter(code) {
   const sourceFile = ts5.createSourceFile(
     "router.tsx",
     code,
@@ -9362,25 +9376,112 @@ function extractBasenameFromRouter(code) {
     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 === "basename" && ts5.isStringLiteral(prop.initializer)) {
-              result = prop.initializer.text;
-              return;
-            }
-          }
+  return findRouterUrls(sourceFile)?.extractions ?? [];
+}
+function extractUrlsFromRouter(code) {
+  const extractions = extractAllUrlsFromRouter(code);
+  return extractions[extractions.length - 1] ?? null;
+}
+function unwrapTypeOperators(expr) {
+  while (ts5.isAsExpression(expr) || ts5.isSatisfiesExpression(expr)) {
+    expr = expr.expression;
+  }
+  return expr;
+}
+function hasModifier(statement, kind) {
+  return ts5.canHaveModifiers(statement) && (ts5.getModifiers(statement)?.some((m) => m.kind === kind) ?? false);
+}
+function findTopLevelConst(sourceFile, name, exported) {
+  for (const statement of sourceFile.statements) {
+    if (ts5.isVariableStatement(statement) && statement.declarationList.flags & ts5.NodeFlags.Const && !hasModifier(statement, ts5.SyntaxKind.DeclareKeyword) && (!exported || hasModifier(statement, ts5.SyntaxKind.ExportKeyword))) {
+      for (const decl of statement.declarationList.declarations) {
+        if (ts5.isIdentifier(decl.name) && decl.name.text === name) {
+          return decl.initializer && unwrapTypeOperators(decl.initializer);
         }
       }
     }
-    ts5.forEachChild(node, visit);
   }
-  visit(sourceFile);
-  return result;
+  return void 0;
+}
+function findNamedImport(sourceFile, name) {
+  for (const statement of sourceFile.statements) {
+    if (!ts5.isImportDeclaration(statement) || !ts5.isStringLiteral(statement.moduleSpecifier) || statement.importClause?.isTypeOnly) {
+      continue;
+    }
+    const bindings = statement.importClause?.namedBindings;
+    if (!bindings || !ts5.isNamedImports(bindings)) continue;
+    for (const el of bindings.elements) {
+      if (!el.isTypeOnly && el.name.text === name) {
+        return {
+          specifier: statement.moduleSpecifier.text,
+          exportedName: el.propertyName?.text ?? name
+        };
+      }
+    }
+  }
+  return void 0;
+}
+function resolveTopLevelConst(name, sourceFile, routerFilePath) {
+  const local = findTopLevelConst(sourceFile, name, false);
+  if (local) return local;
+  const imported = findNamedImport(sourceFile, name);
+  if (!imported) return void 0;
+  const target = resolveImportPath(imported.specifier, routerFilePath);
+  if (!target) return void 0;
+  const targetSource = readFileSync4(target, "utf-8");
+  return findTopLevelConst(
+    ts5.createSourceFile(target, targetSource, ts5.ScriptTarget.Latest, true),
+    imported.exportedName,
+    true
+  );
+}
+function isTopLevelScope(node) {
+  for (let p = node.parent; !ts5.isSourceFile(p); p = p.parent) {
+    if (ts5.isFunctionLike(p) || ts5.isClassLike(p) || ts5.isBlock(p) || ts5.isCaseBlock(p) || ts5.isModuleBlock(p) || ts5.isIterationStatement(p, false)) {
+      return false;
+    }
+  }
+  return true;
+}
+function resolveRouterBasename(routerSource, routerFilePath) {
+  const sourceFile = ts5.createSourceFile(
+    routerFilePath,
+    routerSource,
+    ts5.ScriptTarget.Latest,
+    true,
+    ts5.ScriptKind.TSX
+  );
+  const options = findRouterUrls(sourceFile)?.createRouterCall.arguments[0];
+  const prop = options && ts5.isObjectLiteralExpression(options) ? options.properties.find(
+    (p) => (ts5.isPropertyAssignment(p) || ts5.isShorthandPropertyAssignment(p)) && ts5.isIdentifier(p.name) && p.name.text === "basename"
+  ) : void 0;
+  if (!prop) return {};
+  const valueExpr = ts5.isPropertyAssignment(prop) ? prop.initializer : prop.name;
+  const expr = unwrapTypeOperators(valueExpr);
+  let value = getStringValue(expr);
+  if (value === null && isTopLevelScope(prop)) {
+    if (ts5.isIdentifier(expr)) {
+      const init = resolveTopLevelConst(expr.text, sourceFile, routerFilePath);
+      value = init ? getStringValue(init) : null;
+    } else if (ts5.isPropertyAccessExpression(expr) && ts5.isIdentifier(expr.expression)) {
+      const owner = resolveTopLevelConst(
+        expr.expression.text,
+        sourceFile,
+        routerFilePath
+      );
+      value = owner ? resolveConstMember(owner, expr.name.text) : null;
+    }
+  }
+  return value === null ? { unresolved: valueExpr.getText(sourceFile).replace(/\s+/g, " ") } : { value };
+}
+function resolveConstMember(owner, name) {
+  if (!ts5.isObjectLiteralExpression(owner) || owner.properties.some(ts5.isSpreadAssignment)) {
+    return null;
+  }
+  const member = owner.properties.find(
+    (p) => ts5.isPropertyAssignment(p) && ts5.isIdentifier(p.name) && p.name.text === name
+  );
+  return member ? getStringValue(unwrapTypeOperators(member.initializer)) : null;
 }
 function applyBasenameToRoutes(result, basename2) {
   const prefixed = {};
@@ -9478,8 +9579,9 @@ function buildCombinedRouteMapForRouterFile(routerFilePath) {
   if (extractions.length === 0) {
     return { routes: {}, searchSchemas: {} };
   }
-  const rawBasename = extractBasenameFromRouter(routerSource);
-  const basename2 = rawBasename ? ("/" + rawBasename.replace(/^\/+|\/+$/g, "")).replace(/^\/$/, "") : void 0;
+  const basename2 = normalizeBasename(
+    resolveRouterBasename(routerSource, routerFilePath).value
+  );
   const result = { routes: {}, searchSchemas: {} };
   const memo = createScanMemo();
   for (const extraction of extractions) {
@@ -12673,7 +12775,8 @@ async function createTempRscServer(state, options = {}) {
       // to resolveId/load (plus transform for import rewriters, see
       // IMPORT_REWRITE_PLUGINS) and placed last so framework resolution runs first;
       // Vite re-sorts by `enforce`, so `enforce: "pre"` resolvers still lead.
-      ...state.userResolvePlugins
+      ...state.userResolvePlugins,
+      ...options.plugins ?? []
     ]
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -259,7 +259,7 @@
     "node": ">=24.0.0"
   },
   "scripts": {
-    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js && mkdir -p dist/bin/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/bin/plugins/cloudflare-protocol-loader-hook.mjs",
     "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
     "test": "playwright test",

package/skills/rango/SKILL.md

@@ -445,11 +445,11 @@ npx rango generate src/urls.tsx src/api/
 
 Three modes:
 
-| Flag        | Behavior                                                                                                                                    |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| (none)      | Static parser. Exits with an error, writing nothing, if an `include()` can't be resolved statically (factory or dynamic).                   |
-| `--static`  | Static parser, but writes partial output and prints the unresolvable includes as warnings.                                                  |
-| `--runtime` | Vite-based runtime discovery (full coverage; needs `vite`; `@vitejs/plugin-rsc` comes with the router). `--config <path>` picks the config. |
+| Flag        | Behavior                                                                                                                                                                                                      |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| (none)      | Static parser. Exits with an error, writing nothing, if an `include()` can't be resolved statically (factory or dynamic), or an explicit `createRouter` `basename` isn't a string literal or top-level const. |
+| `--static`  | Static parser, but writes partial output (an unreadable basename leaves patterns unprefixed) and prints the diagnostics as warnings.                                                                          |
+| `--runtime` | Vite-based runtime discovery (full coverage; needs `vite`; `@vitejs/plugin-rsc` comes with the router). `--config <path>` picks the config.                                                                   |
 
 ### Auto-detection
 

package/skills/testing/response-routes.md

@@ -82,14 +82,15 @@ describe("api routes via dispatch", () => {
 
 - trailing-slash redirects from the trie — a route with `trailingSlash: "never"` or `"always"` answers the other form with a 308 and the `Location` (query preserved). A route with no `trailingSlash` serves its URL with and without a trailing slash, with no redirect, as production does;
 - the open-redirect guard on browser-followed redirects (a cross-origin `Location` is rewritten to the basename root unless `redirect(url, { external: true })`);
-- content-negotiated routes (`Vary: Accept` appended);
+- content-negotiated routes whose winning route is a response route (`Vary: Accept` appended);
 - the reloads production answers inside the global middleware chain: a request whose `_rsc_v` names another deploy's document version (`setBuildVersions`, `./serve-shell-request.md`), and a `_rsc_partial` request whose `_rsc_rid` names another router (a cross-app navigation), get an `X-RSC-Reload` at the visitor's URL — on any route, a component route or an unmatched path included;
 - cached response routes (`cache({ ... })` around a `path.json` etc.): hit, SWR, and tag writes. The cache write is scheduled via `waitUntil` (a microtask in tests), so flush microtasks between the seeding `dispatch` and the one that asserts the hit;
 - `createRouter({ telemetry })` `request.start` / `request.end` / `request.error` events, all with one `requestId`, which a response route's `request.timeout` carries too (a rewritten pass's included), and `createRouter({ onError })` for cache-read/write failures.
 
 ## Caveats
 
-- Hitting a COMPONENT (RSC) route throws a clear directive error: `dispatch` is for response routes + redirects + 404 + content negotiation, plus the global + route-level middleware guard stack on RESPONSE routes — it never renders React. Use Flight primitives or e2e to exercise component rendering.
+- Hitting a COMPONENT (RSC) route throws a clear directive error: `dispatch` is for response routes + redirects + 404 + negotiation won by a response route, plus the global + route-level middleware guard stack on RESPONSE routes — it never renders React. Use Flight primitives or e2e to exercise component rendering.
+- On a content-negotiated URL, any `Accept` the page route wins throws the same error. Serve that request with `serveShellRequest(router, url, { headers: { accept } })` (`./serve-shell-request.md`): it runs the production handler and answers the HTML document or the Flight stream, with `Vary: Accept`.
 - A COMPONENT route's guard stack cannot run here. Assert it at e2e, or extract the middleware fn and unit-test it with `runMiddleware` (see `./middleware.md`).
 - JSON serialization is bare, applied in `response-route-handler.ts`: a `path.json` handler that returns a value is serialized verbatim (`JSON.stringify(value)`, status 200, `application/json`) — no envelope. Returning or throwing a `Response` (e.g. `Response.json(x)`) uses the same control-flow path. Any other thrown error takes the error's status (`RouterError.status`, else 500, or a non-200 status already set upstream in the request pipeline). On a `path.json` route the body is an RFC 9457 problem+json object `{ title, status, detail, code }` (`application/problem+json;charset=utf-8`), where `code` is the `RouterError.code`, else `"INTERNAL"`, and the `type` member is omitted. On text/html/xml/md routes the body is `text/plain`: the `RouterError` message, the error message in dev, or `"Internal Server Error"` in production. Assert the shape matching what your handler returns.
 - Setup: needs the preset (alias + virtual stubs) or a Vite-RSC env (see `./setup.md`); a bare router import throws on Vite virtuals.

package/skills/typesafety/generated-files-and-cli.md

@@ -111,7 +111,8 @@ imports it directly, so `Rango.Env`, `Rango.Vars`, and optional
 and client helpers.
 
 CLI flags: the default mode fails (and writes nothing) when an `include()` cannot
-be resolved statically (factory functions, dynamic expressions); `--static`
+be resolved statically (factory functions, dynamic expressions) or an explicit
+`createRouter` `basename` is not a string literal or top-level const; `--static`
 accepts partial output with warnings; `--runtime` uses Vite-based discovery for
 full coverage (needs `vite`, optional
 `--config <path>`). Passing a directory scans it for router and `urls()` files.

package/src/bin/rango.ts

@@ -189,23 +189,23 @@ function runStaticGeneration(args: string[], mode: "default" | "static") {
 
   if (uniqueDiagnostics.length > 0 && mode === "default") {
     // Hard error: no files written
-    console.error("\n[rango] Unresolvable includes detected:\n");
+    console.error("\n[rango] Unresolvable routes detected:\n");
     formatDiagnostics(uniqueDiagnostics);
     console.error(
-      "\nThe static parser cannot resolve these includes because they use " +
-        "factory functions or dynamic expressions.\n\n" +
+      "\nThe static parser cannot resolve these includes or basename because " +
+        "they use factory functions or dynamic expressions. A basename must be " +
+        "a string literal or a top-level const (in the router file or imported " +
+        "from a relative module).\n\n" +
         "Options:\n" +
         "  rango generate <path> --runtime   Use Vite-based discovery (requires vite)\n" +
-        "  rango generate <path> --static    Accept partial output (missing routes above)\n",
+        "  rango generate <path> --static    Accept partial output (missing routes or basename prefix above)\n",
     );
     process.exit(1);
   }
 
   if (uniqueDiagnostics.length > 0 && mode === "static") {
     // Warning: partial output accepted
-    console.warn(
-      "\n[rango] Warning: partial output (unresolvable includes):\n",
-    );
+    console.warn("\n[rango] Warning: partial output (unresolvable routes):\n");
     formatDiagnostics(uniqueDiagnostics);
     console.warn("");
   }
@@ -317,7 +317,12 @@ function formatDiagnostics(
   diagnostics: Array<UnresolvableInclude & { routerFile: string }>,
 ) {
   for (const d of diagnostics) {
-    const prefix = d.namePrefix ? `${d.namePrefix}.*` : `${d.pathPrefix}*`;
+    const prefix =
+      d.reason === "unresolvable-basename"
+        ? "createRouter basename"
+        : d.namePrefix
+          ? `${d.namePrefix}.*`
+          : `${d.pathPrefix}*`;
     console.error(`  ${prefix}`);
     console.error(`    Reason:  ${d.reason} -- ${d.detail}`);
     console.error(`    Source:  ${d.sourceFile}`);

package/src/build/generate-route-types.ts

@@ -26,7 +26,6 @@ export {
 } from "./route-types/include-resolution.js";
 export {
   extractUrlsFromRouter,
-  extractBasenameFromRouter,
   type UrlsExtractionResult,
   buildCombinedRouteMapForRouterFile,
   detectUnresolvableIncludes,

package/src/build/route-types/include-resolution.ts

@@ -12,7 +12,8 @@ export type UnresolvableReason =
   | "factory-call"
   | "dynamic-expression"
   | "unresolvable-import"
-  | "file-not-found";
+  | "file-not-found"
+  | "unresolvable-basename";
 
 export interface UnresolvableInclude {
   pathPrefix: string;