@rangojs/router 0.30.0 → 0.30.1

package/dist/bin/rango.js

@@ -1644,7 +1644,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@rangojs/router",
-      version: "0.30.0",
+      version: "0.30.1",
       description: "Django-inspired RSC router with composable URL patterns",
       keywords: [
         "react",

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/vite/index.js

@@ -7141,7 +7141,7 @@ function resolveVersionsFrom(table, routerId2) {
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.30.0",
+  version: "0.30.1",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -8053,20 +8053,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");
 }
-var REGION_LINE = /^\/\/#region .*$/gm;
-function stripRegionPaths(source) {
-  return source.replace(REGION_LINE, "//#region");
+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;
+}
+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 +8137,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));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.30.0",
+  "version": "0.30.1",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

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/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,
   });

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: