@rangojs/router 0.30.0 → 0.31.0

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;
 }
 

package/src/build/runtime-discovery.ts

@@ -1,5 +1,6 @@
-import { resolve } from "node:path";
+import { basename, resolve } from "node:path";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import type { Plugin, PluginOption, ViteDevServer } from "vite";
 import {
   generateRouteTypesSource,
   genFileTsPath,
@@ -35,13 +36,10 @@ export async function discoverAndWriteRouteTypes(
   routeCount: number;
   outputFiles: string[];
 }> {
-  let createViteServer: typeof import("vite").createServer;
   let loadConfigFromFile: typeof import("vite").loadConfigFromFile;
-  let rsc: any;
 
   try {
     const vite = await import("vite");
-    createViteServer = vite.createServer;
     loadConfigFromFile = vite.loadConfigFromFile;
   } catch {
     throw new Error(
@@ -50,61 +48,57 @@ export async function discoverAndWriteRouteTypes(
   }
 
   try {
-    const rscMod = await import("@vitejs/plugin-rsc");
-    rsc = rscMod.default;
+    await import("@vitejs/plugin-rsc");
   } catch {
     throw new Error(
       "Runtime discovery requires '@vitejs/plugin-rsc'. Install it with: pnpm add -D @vitejs/plugin-rsc",
     );
   }
 
-  const { createVersionPlugin } =
-    await import("../vite/plugins/version-plugin.ts");
-  const { createVirtualStubPlugin } =
-    await import("../vite/plugins/virtual-stub-plugin.ts");
+  const { createTempRscServer } = await import("../vite/temp-rsc-server.js");
+  const { createDiscoveryState } = await import("../vite/discovery/state.js");
+  const { discoverClientUrlProjections } =
+    await import("../vite/discovery/client-urls-projection.js");
+  const { pickForwardedRunnerConfig, selectForwardableResolvePlugins } =
+    await import("../vite/utils/forward-user-plugins.js");
 
-  // Load user's vite config to get resolve.alias (unless provided directly)
-  let userResolveAlias: any = opts.resolveAlias;
-  if (!userResolveAlias) {
-    const configPath = opts.configFile;
+  // The discovery temp server of `vite dev/build` (expose-internal-ids, the
+  // cloudflare:* stubs, the user's resolver plugins and resolve/define/oxc).
+  // The config stays unresolved: resolving it would run rango()'s
+  // configResolved, which writes the static gen files. Forwarded resolvers
+  // therefore run without their own config/configResolved hooks.
+  const entryPath = resolve(opts.entry);
+  const state = createDiscoveryState(entryPath, undefined);
+  state.projectRoot = opts.root;
+  state.userResolveAlias = opts.resolveAlias;
+  if (!opts.resolveAlias) {
     try {
       const loaded = await loadConfigFromFile(
         { command: "serve", mode: "development" },
-        configPath,
+        opts.configFile,
         opts.root,
       );
-      if (loaded?.config?.resolve?.alias) {
-        userResolveAlias = loaded.config.resolve.alias;
+      if (loaded) {
+        state.userRunnerConfig = pickForwardedRunnerConfig(loaded.config);
+        state.userResolvePlugins = selectForwardableResolvePlugins(
+          await flattenPluginOptions(loaded.config.plugins),
+        );
       }
-    } catch {
-      // Config loading failed; proceed without aliases
+    } catch (err: any) {
+      // Discovery without the app's resolvers fails later on an unrelated
+      // import; name the cause here.
+      console.warn(
+        `[rango] Could not load the Vite config (${err?.message ?? err}); discovering without its resolve config and plugins`,
+      );
     }
   }
 
-  const entryPath = resolve(opts.entry);
-  let tempServer: any = null;
+  let tempServer: ViteDevServer | null = null;
 
   try {
-    tempServer = await createViteServer({
-      root: opts.root,
-      configFile: false,
-      server: { middlewareMode: true },
-      appType: "custom",
-      logLevel: "silent",
+    tempServer = await createTempRscServer(state, {
       cacheDir: "node_modules/.vite_rango_generate",
-      resolve: userResolveAlias ? { alias: userResolveAlias } : undefined,
-      esbuild: { jsx: "automatic", jsxImportSource: "react" },
-      plugins: [
-        rsc({
-          entries: {
-            client: "virtual:entry-client",
-            ssr: "virtual:entry-ssr",
-            rsc: entryPath,
-          },
-        }),
-        createVersionPlugin(),
-        createVirtualStubPlugin(),
-      ],
+      plugins: [missingGenFileStubPlugin()],
     });
 
     const rscEnv = (tempServer.environments as any)?.rsc;
@@ -125,6 +119,14 @@ export async function discoverAndWriteRouteTypes(
       );
     }
 
+    // include() of a clientUrls() module resolves from these projections.
+    await discoverClientUrlProjections(
+      state,
+      (tempServer.environments as any)?.ssr,
+      serverMod,
+      rscEnv,
+    );
+
     // Import build utilities for manifest generation
     const buildMod = await rscEnv.runner.import("@rangojs/router/build");
     const generateManifestFull = buildMod.generateManifestFull;
@@ -149,7 +151,11 @@ export async function discoverAndWriteRouteTypes(
       const mountManifests = [];
       for (const mount of mounts) {
         mountManifests.push(
-          await generateManifestFull(mount.patterns, globalMountIndex),
+          await generateManifestFull(
+            mount.patterns,
+            globalMountIndex,
+            router.__basename ? { urlPrefix: router.__basename } : undefined,
+          ),
         );
         globalMountIndex++;
       }
@@ -232,3 +238,46 @@ export async function discoverAndWriteRouteTypes(
     }
   }
 }
+
+const MISSING_GEN_PREFIX = "\0rango-missing-named-routes-gen:";
+
+/**
+ * expose-router-id makes every createRouter() file import its sibling
+ * `./<name>.named-routes.gen.js`. `vite dev/build` write those from static
+ * parsing before discovery; the CLI does not, so a missing one resolves to an
+ * empty NamedRoutes here and discovery writes the real file. An existing gen
+ * file loads from disk as usual.
+ */
+function missingGenFileStubPlugin(): Plugin {
+  return {
+    name: "@rangojs/router:missing-gen-file-stub",
+    enforce: "pre",
+    resolveId(id, importer) {
+      if (!importer || !id.endsWith(".named-routes.gen.js")) return null;
+      const genPath = genFileTsPath(importer.split("?", 1)[0]);
+      if (id !== `./${basename(genPath, ".ts")}.js` || existsSync(genPath)) {
+        return null;
+      }
+      return MISSING_GEN_PREFIX + genPath;
+    },
+    load(id) {
+      return id.startsWith(MISSING_GEN_PREFIX)
+        ? "export const NamedRoutes = {};\n"
+        : null;
+    },
+  };
+}
+
+/**
+ * Flatten an unresolved `plugins` option (nested arrays, promises, falsy
+ * entries) the way Vite's config resolution does, without running any hook.
+ */
+async function flattenPluginOptions(
+  option: PluginOption | undefined,
+): Promise<Plugin[]> {
+  const value = await option;
+  if (Array.isArray(value)) {
+    return (await Promise.all(value.map(flattenPluginOptions))).flat();
+  }
+  return value ? [value as Plugin] : [];
+}

package/src/client-urls/server-projection.ts

@@ -170,8 +170,10 @@ function serializeSearchSchema(
     throw projectionError(route, 'path option "search" must be an object');
   }
 
+  // Source order, not sorted: the build writes the gen file's search keys from
+  // this projection and must match `rango generate`'s static parse (#1322).
   const entries: Array<[string, SearchSchemaValue]> = [];
-  for (const key of Object.keys(value).sort()) {
+  for (const key of Object.keys(value)) {
     const schemaValue = (value as Record<string, unknown>)[key];
     if (
       typeof schemaValue !== "string" ||

package/src/suspense-audit.ts

@@ -233,10 +233,24 @@ const handedSeen = new Map<string, WeakSet<object>>();
 // Thenables the router handed unread that React found already settled when
 // it read them: it suspended on a value that was there. The one cause of a
 // fallback the router owns (I3); consumed by the fallback it caused.
-const needless = new WeakSet<object>();
+let needless = new WeakSet<object>();
 
 let report: SuspenseAuditReport | undefined;
 
+/**
+ * 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>;
+}
+
 function getReport(): SuspenseAuditReport {
   if (report) return report;
   const created: SuspenseAuditReport = {
@@ -277,9 +291,16 @@ function getReport(): SuspenseAuditReport {
   };
   report = created;
   if (typeof window !== "undefined") {
-    (
-      window as unknown as { __rangoSuspenseAudit?: SuspenseAuditReport }
-    ).__rangoSuspenseAudit = created;
+    const target = window as unknown as {
+      __rangoSuspenseAudit?: SuspenseAuditReport;
+      __rangoSuspenseAudits?: SuspenseAuditInstance[];
+    };
+    target.__rangoSuspenseAudit = created;
+    (target.__rangoSuspenseAudits ??= []).push({
+      violations: () => violationSummary(created),
+      forget: forgetSuspenseAudit,
+      settle: () => new Promise((resolve) => afterMicrotasks(resolve)),
+    });
   }
   return created;
 }
@@ -306,17 +327,35 @@ const RULES: Record<SuspenseAuditKind, [invariant: string, counter: Counter]> =
     mutated: ["I7", "mutations"],
   };
 
+function eventLine(
+  kind: SuspenseAuditKind,
+  boundary: string,
+  detail: string,
+): string {
+  return `${RULES[kind][0]} ${kind} at ${boundary}: ${detail}`;
+}
+
+function violationSummary(r: SuspenseAuditReport): string | undefined {
+  const counts = Object.values(RULES)
+    .filter(([, counter]) => r[counter] > 0)
+    .map(([invariant, counter]) => `${invariant} ${counter}: ${r[counter]}`);
+  if (counts.length === 0) return undefined;
+  const events = r.events.map(
+    (event) => `  ${eventLine(event.kind, event.boundary, event.detail)}`,
+  );
+  return [counts.join(", "), ...events].join("\n");
+}
+
 function violate(
   kind: SuspenseAuditKind,
   boundary: string,
   detail: string,
 ): void {
-  const [invariant, counter] = RULES[kind];
   const r = getReport();
-  r[counter] += 1;
+  r[RULES[kind][1]] += 1;
   r.events.push({ kind, boundary, detail, url: href(), at: performance.now() });
   if (r.events.length > MAX_EVENTS) r.events.shift();
-  console.error(`${PREFIX} ${invariant} ${kind} at ${boundary}: ${detail}`);
+  console.error(`${PREFIX} ${eventLine(kind, boundary, detail)}`);
 }
 
 // Every hand-over, mount and fallback, for a debug run to read back. Call
@@ -617,9 +656,9 @@ let pendingRoot: PromiseLike<unknown> | undefined;
 // I7: the fields of each segment object handed to React, at hand-over, and
 // the segments themselves, weakly: the history cache keeps a tree's segments
 // after the next tree drops them, and a write there is still a write.
-const handedFields = new WeakMap<object, Record<string, unknown>>();
+let handedFields = new WeakMap<object, Record<string, unknown>>();
 const handedSegments = new Set<WeakRef<object>>();
-const trackedSegments = new WeakSet<object>();
+let trackedSegments = new WeakSet<object>();
 
 function heldTree(): TreeAudit | undefined {
   if (pendingRoot) {
@@ -1016,15 +1055,23 @@ export 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 function forgetSuspenseAudit(): void {
   held = undefined;
   handedSegments.clear();
+  handedFields = new WeakMap();
+  trackedSegments = new WeakSet();
+  needless = new WeakSet();
   pendingRoot = undefined;
   treeCause = undefined;
   unmounted.clear();
   remounted.length = 0;
   settledSinceTree.clear();
   mountCounts.clear();
-  getReport().reset();
+  report?.reset();
 }

package/src/testing/render-route.tsx

@@ -128,7 +128,7 @@ import { isUnderTestRunner } from "../runtime-env.js";
 import { setupNavigationBridgeDelegatedPrefetch } from "../browser/navigation-bridge.js";
 import { resetPrefetchObserverForTesting } from "../browser/prefetch/observer.js";
 import type { PrefetchStrategy } from "../router/prefetch-default.js";
-import { auditTreeCause } from "../suspense-audit.js";
+import { auditTreeCause, forgetSuspenseAudit } from "../suspense-audit.js";
 
 const TEST_ORIGIN = "http://localhost";
 let activePrefetchRegistrations = 0;
@@ -1186,6 +1186,10 @@ export async function renderRoute(
     ...makeMetadata(url.pathname, initialSegments, initialMatch.params),
     defaultPrefetch: options.defaultPrefetch,
   };
+  // The suspense audit holds one document's tree and mounts: a root an earlier
+  // renderRoute mounted is gone (a test unmounts its root, production never
+  // does). A no-op unless this repo's tests run the audit.
+  forgetSuspenseAudit();
   const initialTree = await renderSegments(initialSegments, {
     outletPending: options.outletPending,
   });