@rangojs/router 0.29.0 → 0.30.1

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;
@@ -475,15 +475,15 @@ export interface TestRouterHandle {
    * await act(async () => tail.resolve());
    * // useNavigation(): idle, isStreaming false
    *
-   * A navigation started while React holds a page goes inside
-   * `await act(async () => ...)`. Its first update makes React retry the held
-   * page, which suspends again; a synchronous act() scope drops that retry
-   * and React renders no later update of the same priority.
+   * A navigation started while React holds a page shows its page once the
+   * call resolves, with or without act(). A `<Link>` click over a held page
+   * still goes inside `await act(async () => ...)` (docs/testing.md).
    *
    * @example
-   * await act(async () => {
-   *   await router.navigate("/products/3", { transition: false });
-   * });
+   * await router.navigate("/products/2", { loaders: [[ProductLoader, next]] });
+   * // React holds /products/2
+   * await router.navigate("/products/3", { transition: false });
+   * // /products/3 is on screen
    */
   navigate(
     url: string,
@@ -914,9 +914,10 @@ export async function renderRoute(
     const handle = eventController.startNavigation(
       new URL(target, TEST_ORIGIN).href,
     );
-    // Synchronous, in the caller's task: a <Link> click's own act() scope
-    // takes it, and no act() of the caller's can overlap it.
-    act(() => eventController.flushRouteState());
+    // Runs in the caller's task, so a <Link> click's own act() takes it.
+    // Awaited: React retries a held page with this update, and an unawaited
+    // act() drops that suspended retry for good.
+    await act(() => eventController.flushRouteState());
     try {
       const streamUntil = navOptions?.streamUntil;
       if (streamUntil) {
@@ -927,18 +928,19 @@ export async function renderRoute(
         });
         if (handle.signal.aborted) return;
         const stream = handle.startStreaming();
-        act(() => eventController.flushRouteState());
+        await act(() => eventController.flushRouteState());
         // A navigation that is left stops counting as streaming at the abort
         // (partial-update.ts endStream); the abort's notification goes out
         // with the newer navigation's.
         handle.signal.addEventListener("abort", () => stream.end(), {
           once: true,
         });
-        const end = (): void =>
-          act(() => {
+        const end = async (): Promise<void> => {
+          await act(() => {
             stream.end();
             eventController.flushRouteState();
           });
+        };
         void streamUntil.then(end, end);
       }
       await commitNavigation(handle, target, navOptions);
@@ -1184,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,
   });

package/src/vite/discovery/build-versions.ts

@@ -593,11 +593,23 @@ export function isSourceMap(fileName: string): boolean {
 }
 
 /**
- * The bundler's region comments around plugin-rsc's server-reference map, as
- * they appear in an unminified chunk (`\0` is printed as two characters).
+ * The bundler's module marker: the comment line before each module's code in
+ * an unminified chunk, naming the module (`\0` printed as two characters).
+ * rolldown before 1.2.15 wraps the code in `//#region <id>` and
+ * `//#endregion`; 1.2.15 (rolldown/rolldown#11235) prints only `// <id>`
+ * where the module starts.
  */
-const SERVER_REFERENCES_REGION_START = `//#region \\0${SERVER_REFERENCES_MODULE_ID.slice(1)}\n`;
-const REGION_END = "//#endregion";
+const MODULE_MARKER = /^\/\/(#region)? (.+)$/gm;
+/**
+ * plugin-rsc's server-reference map: its marker in either form (group 1), and
+ * its body up to the next `// ` line or the region's end. The body stops at
+ * any `// ` line, a comment of its own included, so it never takes in the
+ * code of the module after it.
+ */
+const SERVER_REFERENCE_MAP = new RegExp(
+  `(^//(?:#region)? ${escapeRegExp(`\\0${SERVER_REFERENCES_MODULE_ID.slice(1)}`)}\n)[\\s\\S]*?(?=^//(?: |#endregion))`,
+  "m",
+);
 
 /**
  * Drop the body of the server-reference map from a chunk's source.
@@ -609,33 +621,61 @@ const REGION_END = "//#endregion";
  * 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 function stripServerReferenceMap(source: string): string {
-  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");
 }
 
-const REGION_LINE = /^\/\/#region .*$/gm;
+/**
+ * Every way the bundler can print one of `moduleIds` in a marker. rolldown
+ * prints a path relative to its working directory (`stabilize_id`), so any
+ * trailing run of the path's segments, and any other id as it is.
+ */
+function printedModuleIds(moduleIds: readonly string[]): Set<string> {
+  const printed = new Set<string>();
+  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;
+}
 
 /**
- * Take the module paths out of a chunk's region comments.
+ * Take the module paths out of a chunk's module markers.
+ *
+ * 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.
  *
- * 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.
+ * 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 function stripRegionPaths(source: string): string {
-  return source.replace(REGION_LINE, "//#region");
+export function stripModulePaths(
+  source: string,
+  moduleIds: readonly string[],
+): string {
+  let printed: Set<string> | undefined;
+  return source.replace(
+    MODULE_MARKER,
+    (line, region: string | undefined, name: string) => {
+      if (region) return "//#region";
+      printed ??= printedModuleIds(moduleIds);
+      return printed.has(name.replace(/^(?:\.\.\/)+/, "")) ? "//" : line;
+    },
+  );
 }
 
 /** One thing a version is a hash of: its name and the digest of its bytes. */
@@ -676,8 +716,8 @@ const FOREIGN_FILE = "~";
  *
  * 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
@@ -756,8 +796,9 @@ export function digestBundle(
       };
     }
     const references: string[] = [];
-    const text = stripRegionPaths(
+    const text = stripModulePaths(
       stripServerReferenceMap(decoder.decode(bytes)),
+      chunk.moduleIds,
     );
     const blanked = reference
       ? text.replace(reference, (name) => {

package/src/vite/plugins/stable-rsc-output.ts

@@ -121,7 +121,7 @@ export function canonicalAssetsManifestBinding(
  *    (`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: