@rangojs/router 0.30.1 → 0.32.0

package/skills/testing/serve-shell-request.md

@@ -30,19 +30,20 @@ A `Prerender` route is served as in production: from the artifact `router.matchF
 
 ### Returns — `ServeShellRequestResult`
 
-| Field          | Type                                              | Meaning                                                                                                                                                                                                                            |
-| -------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `shellStatus`  | `"HIT" \| "MISS" \| null`                         | `x-rango-shell`; null when the serve path did not consider the request (not a `ppr` route, a nonce'd request, a partial request).                                                                                                  |
-| `replayStatus` | `PprReplayStatus \| null`                         | `x-rango-ppr-replay` on a partial request: `{ outcome: "HIT", freshness }` or `{ outcome: "BYPASS", reason }`.                                                                                                                     |
-| `prelude`      | `string \| undefined`                             | The prelude a HIT served (the capture's Flight text). `undefined` unless `shellStatus` is `"HIT"`.                                                                                                                                 |
-| `flight`       | `string \| undefined`                             | The Flight payload this request rendered: a HIT's tail, a document render, or a partial response. `undefined` when no Flight rendered (a redirect, a middleware response).                                                         |
-| `key`          | `string`                                          | The shell key the serve path resolved for a document it read (MISS or HIT), request partition included. Otherwise (no `ppr`, a partial request) the URL's key without a partition.                                                 |
-| `readEntry`    | `() => Promise<ShellCacheEntry \| null>`          | Reads the document entry under `key` from the request's store (a passive `getShell`). A read: on a store with a shell memo it warms the memo, so call it after the reads you count.                                                |
-| `readHandles`  | `() => Promise<ShellRequestHandles \| undefined>` | Decodes the response's handle data as the browser reads it: `{ hydration, late }` (see "Handles and loader data"). `undefined` when no Flight rendered.                                                                            |
-| `readDeferred` | `() => Promise<string[] \| undefined>`            | The ids of the segments the payload marks deferred (a prefetch skipped them; the fill renders them), in payload order. `[]` when nothing was deferred, `undefined` when no Flight rendered.                                        |
-| `readAction`   | `() => Promise<ShellRequestAction \| undefined>`  | For an `action` request, the call's answer as the browser reads it: `{ ok, result, revalidationError }` (see "A server action called from the page"). `undefined` when no Flight rendered or the payload carries no action result. |
-| `response`     | `Response`                                        | Status and headers. Its body is already read.                                                                                                                                                                                      |
-| `body`         | `string`                                          | The body text.                                                                                                                                                                                                                     |
+| Field               | Type                                                  | Meaning                                                                                                                                                                                                                            |
+| ------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `shellStatus`       | `"HIT" \| "MISS" \| null`                             | `x-rango-shell`; null when the serve path did not consider the request (not a `ppr` route, a nonce'd request, a partial request).                                                                                                  |
+| `replayStatus`      | `PprReplayStatus \| null`                             | `x-rango-ppr-replay` on a partial request: `{ outcome: "HIT", freshness }` or `{ outcome: "BYPASS", reason }`.                                                                                                                     |
+| `prelude`           | `string \| undefined`                                 | The prelude a HIT served (the capture's Flight text). `undefined` unless `shellStatus` is `"HIT"`.                                                                                                                                 |
+| `flight`            | `string \| undefined`                                 | The Flight payload this request rendered: a HIT's tail, a document render, or a partial response. `undefined` when no Flight rendered (a redirect, a middleware response).                                                         |
+| `key`               | `string`                                              | The shell key the serve path resolved for a document it read (MISS or HIT), request partition included. Otherwise (no `ppr`, a partial request) the URL's key without a partition.                                                 |
+| `readEntry`         | `() => Promise<ShellCacheEntry \| null>`              | Reads the document entry under `key` from the request's store (a passive `getShell`). A read: on a store with a shell memo it warms the memo, so call it after the reads you count.                                                |
+| `readHandles`       | `() => Promise<ShellRequestHandles \| undefined>`     | Decodes the response's handle data as the browser reads it: `{ hydration, late }` (see "Handles and loader data"). `undefined` when no Flight rendered.                                                                            |
+| `readDeferred`      | `() => Promise<string[] \| undefined>`                | The ids of the segments the payload marks deferred (a prefetch skipped them; the fill renders them), in payload order. `[]` when nothing was deferred, `undefined` when no Flight rendered.                                        |
+| `readAction`        | `() => Promise<ShellRequestAction \| undefined>`      | For an `action` request, the call's answer as the browser reads it: `{ ok, result, revalidationError }` (see "A server action called from the page"). `undefined` when no Flight rendered or the payload carries no action result. |
+| `readLocationState` | `() => Promise<Record<string, unknown> \| undefined>` | The payload's location state as the browser reads it: `{ [Def.__rsc_ls_key]: value }` (see "Location state on a document"). `undefined` when it carries none or no Flight rendered.                                                |
+| `response`          | `Response`                                            | Status and headers. Its body is already read.                                                                                                                                                                                      |
+| `body`              | `string`                                              | The body text.                                                                                                                                                                                                                     |
 
 ### `resetShellTestState(): Promise<void>`
 
@@ -415,6 +416,30 @@ expect(await result.readPayloadFormState()).toEqual(result.formState);
 - Request headers come from `headers`. No `Origin` is sent by default, which the origin guard allows.
 - Not with `partial`. The hydration itself (`hydrateRoot` taking the state, the hook not resetting) is e2e.
 
+## Location state on a document
+
+A document carries the location state its handler, middleware or no-JS form action set, in its bootstrap payload; `readLocationState()` reads it as the browser does. A document request that redirects carries its state to the target in a one-shot cookie instead (`Set-Cookie`, `<stateCookieName>-ls`, `__Host-` on https): pass that cookie on the target's request, as the browser does when it follows the redirect, and read what the target's payload carries.
+
+```tsx
+const redirected = await serveShellRequest(router, "/payment/callback");
+const setCookie = redirected.response.headers
+  .getSetCookie()
+  .find((c) => /-ls=/.test(c.split(";")[0]!))!;
+
+const target = await serveShellRequest(router, "/checkout", {
+  headers: { cookie: setCookie.split(";")[0]!, "sec-fetch-dest": "document" },
+});
+expect(await target.readLocationState()).toEqual({
+  [FlashMessage.__rsc_ls_key]: { text: "Payment declined" },
+});
+expect(target.response.headers.get("cache-control")).toBe("private, no-store");
+```
+
+- Only a GET document request of the target's pathname reads the cookie, and clears it (`Max-Age=0` on its response). Where the request sends `Sec-Fetch-Dest`, it must be `document`, `iframe` or `frame`: a prefetch or `fetch()` (`empty`) leaves the cookie to the navigation. Without the header the request counts as a navigation.
+- A document that carries state, and the redirect carrying it on, leave `Cache-Control: private, no-store`; the document cache neither stores nor serves them. On a `ppr` route, state set before its handler ran, by middleware or a redirect's cookie, rides the live payload: the request is still a `MISS` that captures or a `HIT`, and `prelude` holds none of it. State its handler sets keeps the route from being stored as a shell (`readEntry()` is null).
+- For a `form` request, the re-rendered document carries what the action set; a redirecting action carries it in the cookie, as above.
+- What a reader shows is client-side: seed it with `renderRoute({ hydrate: true, documentLocationState })` (see [`./client-components.md`](./client-components.md)).
+
 ## A server action called from the page
 
 `serveShellRequest(router, url, { action: { ref, id, args, segments } })` sends the request a JS server action call makes from the page at `url`, as `browser/server-action-bridge.ts` sends it: a POST of `args` with `?_rsc_action`, the `rsc-action` header, `X-RSC-Router-Client-Path` and `_rsc_segments`. `ref` is registered under `id` (`<module id>#<export name>`, any unique string of that shape in a test) so the handler loads it by id. The response is the action's Flight payload: its return value and the segments it re-rendered, `flight` as for any other request. Pass the segment ids the page holds as `segments`, so the request has segments to revalidate; without them the server holds none. Read them from the `metadata.matched` of a `partial` request's payload (`flight`), as in "Testing `prefetch: false`" above.

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/skills/ux-architecture/SKILL.md

@@ -313,9 +313,12 @@ The rule: **prefetch broadly, and flag what is expensive.**
 - On a server route, `loading(fallback, { prefetch: false })` keeps the whole
   entry behind that fallback out of the prefetch (`/route`, "`loading()`
   options"). A group's `loading()` takes no options.
-- When the target's `revalidate()` reads `currentUrl` or `currentParams`, give
-  the Link `prefetchKey=":source"`: the default prefetch entry is shared by
-  every source page (`src/browser/react/Link.tsx`, `prefetchKey`).
+- The default prefetch entry is shared by every source page. When the
+  target's `revalidate()` reads `currentParams`, `currentUrl` or
+  `fromRouteName` and keeps the segment, the router scopes that prefetch to
+  the page that sent it (`x-rsc-prefetch-scope: source`): another page
+  prefetches its own. `prefetchKey=":source"` on the Link scopes every
+  prefetch of it (`src/browser/react/Link.tsx`, `prefetchKey`).
 
 ### 2.7 transition() and view transitions
 

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/browser/history-state.ts

@@ -158,8 +158,9 @@ export function stripShellMissMarker(): void {
  * the server rendered this document without them. One pass before hydration
  * (initBrowserApp; renderRoute's `hydrate` mode), so no reader needs to know
  * the page began as a document load, and a slot nobody reads is removed too.
- * No server-set state exists yet to lose: a document response carries none
- * (rsc-rendering.ts attaches it to partial payloads only).
+ * Server-set state is not lost to it: the state a document response carries
+ * is merged after this pass (applyDocumentLocationState), so a `~r` slot the
+ * server set for this load survives this load and no later one.
  *
  * A slot is recognised by its key alone (the `~r` suffix): at start-up the
  * module that defines it may not be loaded.
@@ -185,6 +186,27 @@ export function clearLocationStateOnDocumentLoad(): void {
   if (next) window.history.replaceState(next, "");
 }
 
+/**
+ * Merge the location state a document response carried (its bootstrap
+ * payload's `metadata.locationState`, server/document-location-state.ts)
+ * into the entry the document loaded on. Start-up runs it after
+ * clearLocationStateOnDocumentLoad and the version is set, before the entry
+ * is committed for readers (initBrowserApp; renderRoute's `hydrate` mode),
+ * so readers get it once they have hydrated, as stored state. Only typed
+ * slots are taken.
+ */
+export function applyDocumentLocationState(
+  locationState: Record<string, unknown> | undefined,
+): void {
+  if (!locationState) return;
+  let slots: Record<string, unknown> | undefined;
+  for (const key of Object.keys(locationState)) {
+    if (!isLocationStateKey(key)) continue;
+    (slots ??= {})[key] = locationState[key];
+  }
+  if (slots) mergeLocationState(slots);
+}
+
 /**
  * Merge server-set location state into the current history entry and return
  * the entry state written. Readers see it when the caller commits it

package/src/browser/react/Link.tsx

@@ -110,23 +110,20 @@ export interface LinkProps extends Omit<
    * keyed on Rango state + target URL. This is correct for routes whose
    * response shape doesn't depend on where the user navigates from.
    *
-   * Set `":source"` when this Link's response would legitimately differ
-   * based on the source page — typically when the target route (or one
-   * of its layouts) uses a custom `revalidate()` handler that reads
-   * `currentUrl` / `currentParams`, and the wildcard entry would
-   * therefore serve the wrong diff to a navigation from a different
-   * source.
+   * Set `":source"` to scope every prefetch of this Link to the page that
+   * sent it, when its response would differ by source page in a way the
+   * server cannot see.
    *
-   * A route an intercept targets is scoped to the source automatically
-   * (server-side `x-rsc-prefetch-scope: source`), whether or not the
-   * intercept applies from this page: the modal and the full page are
-   * both source-specific. Every other route stays shared, so `":source"`
-   * is only needed for custom revalidation logic.
+   * The server scopes a prefetch to its source automatically
+   * (`x-rsc-prefetch-scope: source`) when an intercept targets the route,
+   * whether or not it applies from this page (the modal and the full page
+   * are both source-specific), and when a `revalidate()` of the target
+   * read `currentParams`, `currentUrl` or `fromRouteName` and kept the
+   * segment: that diff is the source page's (#1331). Every other response
+   * stays shared.
    *
    * @example
    * ```tsx
-   * // Route uses a `revalidate()` that branches on currentUrl — opt in
-   * // so prefetches don't bleed across source pages.
    * <Link to="/dashboard" prefetch="hover" prefetchKey=":source" />
    * ```
    */

package/src/browser/react/location-state-shared.ts

@@ -462,6 +462,12 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
  * The key is auto-injected by the Vite exposeInternalIds plugin as a property
  * based on file path and export name. No manual key required.
  *
+ * One definition is one slot in `history.state`. Entries of different
+ * definitions accumulate, but for the same definition the last write wins:
+ * two `ctx.setLocationState(Def(...))` calls in one response, or
+ * `redirect(url, { state: [Def(a), Def(b)] })`, deliver only the later
+ * value. To combine writes, make the state an array and write it once.
+ *
  * @param options Optional configuration
  * @returns A typed state definition for use with Link and useLocationState
  *
@@ -675,7 +681,8 @@ export function isLocationStateEntry(
 }
 
 /**
- * Resolve state entries into a flat object for history.state
+ * Resolve state entries into a flat object for history.state. One slot per
+ * definition: a later entry of the same definition replaces an earlier one.
  */
 export function resolveLocationStateEntries(
   entries: LocationStateEntry[],

package/src/browser/rsc-router.tsx

@@ -47,6 +47,7 @@ import {
 import { createAppShellRef } from "./app-shell.js";
 import { bootLog, IS_BROWSER_DEBUG } from "./logging.js";
 import {
+  applyDocumentLocationState,
   clearLocationStateOnDocumentLoad,
   stripShellMissMarker,
 } from "./history-state.js";
@@ -274,8 +275,10 @@ export async function initBrowserApp(
     setSuspenseAuditStreamProbe(() => eventController.getState().isStreaming);
   }
 
-  // The document's entry, after the clearOnReload pass and under the version
-  // set above: what readers get once they have hydrated.
+  // The state the document response carried, after the clearOnReload pass
+  // and under the version set above.
+  applyDocumentLocationState(initialPayload.metadata?.locationState);
+  // The document's entry: what readers get once they have hydrated.
   eventController.commitLocationState(window.history.state);
 
   // Initialize event controller with segment order (even without handles)

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;

package/src/build/route-types/router-processing.ts

@@ -26,6 +26,8 @@ import {
 } from "./include-resolution.js";
 import { findUrlsVariableNames } from "./per-module-writer.js";
 import { isAutoGeneratedRouteName } from "../../route-name.js";
+import { normalizeBasename } from "../../router/basename.js";
+import { getStringValue } from "./ast-helpers.js";
 
 function countPublicRouteEntries(source: string): number {
   const matches =
@@ -232,15 +234,16 @@ function collectCreateRouterCallChain(
   }
 }
 
-function extractAllUrlsFromRouter(code: string): UrlsExtractionResult[] {
-  const sourceFile = ts.createSourceFile(
-    "router.tsx",
-    code,
-    ts.ScriptTarget.Latest,
-    true,
-    ts.ScriptKind.TSX,
-  );
-  let result: UrlsExtractionResult[] | null = null;
+// The first createRouter chain (in source order) that mounts urls, with its
+// extractions in runtime order. Route types and basename both come from it.
+function findRouterUrls(sourceFile: ts.SourceFile): {
+  createRouterCall: ts.CallExpression;
+  extractions: UrlsExtractionResult[];
+} | null {
+  let result: {
+    createRouterCall: ts.CallExpression;
+    extractions: UrlsExtractionResult[];
+  } | null = null;
 
   function visit(node: ts.Node) {
     if (result) return;
@@ -279,7 +282,7 @@ function extractAllUrlsFromRouter(code: string): UrlsExtractionResult[] {
         }
 
         if (extracted.length > 0) {
-          result = extracted;
+          result = { createRouterCall, extractions: extracted };
           return;
         }
       }
@@ -288,7 +291,18 @@ function extractAllUrlsFromRouter(code: string): UrlsExtractionResult[] {
   }
 
   visit(sourceFile);
-  return result ?? [];
+  return result;
+}
+
+function extractAllUrlsFromRouter(code: string): UrlsExtractionResult[] {
+  const sourceFile = ts.createSourceFile(
+    "router.tsx",
+    code,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+  return findRouterUrls(sourceFile)?.extractions ?? [];
 }
 
 /**
@@ -307,48 +321,189 @@ export function extractUrlsFromRouter(
   return extractions[extractions.length - 1] ?? null;
 }
 
+function unwrapTypeOperators(expr: ts.Expression): ts.Expression {
+  while (ts.isAsExpression(expr) || ts.isSatisfiesExpression(expr)) {
+    expr = expr.expression;
+  }
+  return expr;
+}
+
+function hasModifier(statement: ts.Statement, kind: ts.SyntaxKind): boolean {
+  return (
+    ts.canHaveModifiers(statement) &&
+    (ts.getModifiers(statement)?.some((m) => m.kind === kind) ?? false)
+  );
+}
+
+// `exported` limits the lookup to `export const name = ...`; an export list or
+// re-export is not followed.
+function findTopLevelConst(
+  sourceFile: ts.SourceFile,
+  name: string,
+  exported: boolean,
+): ts.Expression | undefined {
+  for (const statement of sourceFile.statements) {
+    if (
+      ts.isVariableStatement(statement) &&
+      statement.declarationList.flags & ts.NodeFlags.Const &&
+      !hasModifier(statement, ts.SyntaxKind.DeclareKeyword) &&
+      (!exported || hasModifier(statement, ts.SyntaxKind.ExportKeyword))
+    ) {
+      for (const decl of statement.declarationList.declarations) {
+        if (ts.isIdentifier(decl.name) && decl.name.text === name) {
+          return decl.initializer && unwrapTypeOperators(decl.initializer);
+        }
+      }
+    }
+  }
+  return undefined;
+}
+
+// The value import binding `name` in the router file: a named import
+// (`import { X }` / `import { Y as X }`). Read from the AST, so a commented-out
+// or quoted import never matches. Default and namespace imports are not read.
+function findNamedImport(
+  sourceFile: ts.SourceFile,
+  name: string,
+): { specifier: string; exportedName: string } | undefined {
+  for (const statement of sourceFile.statements) {
+    if (
+      !ts.isImportDeclaration(statement) ||
+      !ts.isStringLiteral(statement.moduleSpecifier) ||
+      statement.importClause?.isTypeOnly
+    ) {
+      continue;
+    }
+    const bindings = statement.importClause?.namedBindings;
+    if (!bindings || !ts.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 undefined;
+}
+
+// The top-level const `name` refers to: declared in the router file or
+// exported as a const by a relative module it is imported from by name.
+function resolveTopLevelConst(
+  name: string,
+  sourceFile: ts.SourceFile,
+  routerFilePath: string,
+): ts.Expression | undefined {
+  const local = findTopLevelConst(sourceFile, name, false);
+  if (local) return local;
+  const imported = findNamedImport(sourceFile, name);
+  if (!imported) return undefined;
+  const target = resolveImportPath(imported.specifier, routerFilePath);
+  if (!target) return undefined;
+  const targetSource = readFileSync(target, "utf-8");
+  return findTopLevelConst(
+    ts.createSourceFile(target, targetSource, ts.ScriptTarget.Latest, true),
+    imported.exportedName,
+    true,
+  );
+}
+
+// Inside any nested scope a local declaration can shadow the top-level
+// binding, and resolving it anyway would emit a wrong prefix.
+function isTopLevelScope(node: ts.Node): boolean {
+  for (let p = node.parent; !ts.isSourceFile(p); p = p.parent) {
+    if (
+      ts.isFunctionLike(p) ||
+      ts.isClassLike(p) ||
+      ts.isBlock(p) ||
+      ts.isCaseBlock(p) ||
+      ts.isModuleBlock(p) ||
+      ts.isIterationStatement(p, false)
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
 /**
- * Extract the `basename` string literal from createRouter({ basename: "..." }).
- * Returns the basename value or undefined if not present.
+ * Read inline createRouter({ basename: X }) where X is a string literal, a
+ * top-level const, or `Const.prop` on a top-level const object literal.
+ * `unresolved` is the source of any other X.
  */
-export function extractBasenameFromRouter(code: string): string | undefined {
+function resolveRouterBasename(
+  routerSource: string,
+  routerFilePath: string,
+): { value?: string; unresolved?: string } {
   const sourceFile = ts.createSourceFile(
-    "router.tsx",
-    code,
+    routerFilePath,
+    routerSource,
     ts.ScriptTarget.Latest,
     true,
     ts.ScriptKind.TSX,
   );
-  let result: string | undefined;
-
-  function visit(node: ts.Node) {
-    if (result !== undefined) return;
-    if (
-      ts.isCallExpression(node) &&
-      ts.isIdentifier(node.expression) &&
-      node.expression.text === "createRouter"
+  // Read from the createRouter call whose urls the route types use. Only an
+  // explicit `basename` key counts: one inside a spread
+  // (`createRouter({ ...shared })`) or a non-literal options argument stays
+  // unread and unreported.
+  const options = findRouterUrls(sourceFile)?.createRouterCall.arguments[0];
+  const prop =
+    options && ts.isObjectLiteralExpression(options)
+      ? options.properties.find(
+          (p): p is ts.PropertyAssignment | ts.ShorthandPropertyAssignment =>
+            (ts.isPropertyAssignment(p) ||
+              ts.isShorthandPropertyAssignment(p)) &&
+            ts.isIdentifier(p.name) &&
+            p.name.text === "basename",
+        )
+      : undefined;
+  if (!prop) return {};
+
+  const valueExpr = ts.isPropertyAssignment(prop)
+    ? prop.initializer
+    : prop.name;
+  const expr = unwrapTypeOperators(valueExpr);
+  let value = getStringValue(expr);
+  if (value === null && isTopLevelScope(prop)) {
+    if (ts.isIdentifier(expr)) {
+      const init = resolveTopLevelConst(expr.text, sourceFile, routerFilePath);
+      value = init ? getStringValue(init) : null;
+    } else if (
+      ts.isPropertyAccessExpression(expr) &&
+      ts.isIdentifier(expr.expression)
     ) {
-      for (const arg of node.arguments) {
-        if (ts.isObjectLiteralExpression(arg)) {
-          for (const prop of arg.properties) {
-            if (
-              ts.isPropertyAssignment(prop) &&
-              ts.isIdentifier(prop.name) &&
-              prop.name.text === "basename" &&
-              ts.isStringLiteral(prop.initializer)
-            ) {
-              result = prop.initializer.text;
-              return;
-            }
-          }
-        }
-      }
+      const owner = resolveTopLevelConst(
+        expr.expression.text,
+        sourceFile,
+        routerFilePath,
+      );
+      value = owner ? resolveConstMember(owner, expr.name.text) : null;
     }
-    ts.forEachChild(node, visit);
   }
+  return value === null
+    ? { unresolved: valueExpr.getText(sourceFile).replace(/\s+/g, " ") }
+    : { value };
+}
 
-  visit(sourceFile);
-  return result;
+// String value of `owner.name` when owner is an object literal. A spread may
+// override the property, so an owner containing one is not resolved.
+function resolveConstMember(owner: ts.Expression, name: string): string | null {
+  if (
+    !ts.isObjectLiteralExpression(owner) ||
+    owner.properties.some(ts.isSpreadAssignment)
+  ) {
+    return null;
+  }
+  const member = owner.properties.find(
+    (p): p is ts.PropertyAssignment =>
+      ts.isPropertyAssignment(p) &&
+      ts.isIdentifier(p.name) &&
+      p.name.text === name,
+  );
+  return member
+    ? getStringValue(unwrapTypeOperators(member.initializer))
+    : null;
 }
 
 /** Apply a basename prefix to all route patterns in a result set. */
@@ -496,11 +651,9 @@ export function buildCombinedRouteMapForRouterFile(routerFilePath: string): {
     return { routes: {}, searchSchemas: {} };
   }
 
-  // Detect basename from createRouter({ basename: "..." })
-  const rawBasename = extractBasenameFromRouter(routerSource);
-  const basename = rawBasename
-    ? ("/" + rawBasename.replace(/^\/+|\/+$/g, "")).replace(/^\/$/, "")
-    : undefined;
+  const basename = normalizeBasename(
+    resolveRouterBasename(routerSource, routerFilePath).value,
+  );
 
   const result: RouteMapWithSearch = { routes: {}, searchSchemas: {} };
   const memo = createScanMemo();
@@ -531,8 +684,9 @@ export function buildCombinedRouteMapForRouterFile(routerFilePath: string): {
 
 /**
  * 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 function detectUnresolvableIncludes(
   routerFilePath: string,
@@ -559,6 +713,16 @@ export function detectUnresolvableIncludes(
       memo,
     );
   }
+  const { unresolved } = resolveRouterBasename(source, realPath);
+  if (unresolved !== undefined) {
+    diagnostics.push({
+      pathPrefix: "/",
+      namePrefix: null,
+      reason: "unresolvable-basename",
+      sourceFile: realPath,
+      detail: `basename \`${unresolved}\` is not a string literal or top-level const; every pattern would lack the prefix`,
+    });
+  }
   return diagnostics;
 }