@rangojs/router 0.0.0-experimental.124 → 0.0.0-experimental.126

package/src/testing/render-route.tsx

@@ -23,6 +23,10 @@
  *     client context (see the `loaders` / `locationState` / `handles` options) —
  *     nothing is executed on the server. This exercises the read path
  *     (useLoader / useLocationState / useHandle from context), not the run path.
+ *   - navigate() commits synchronously, so it does NOT drive the navigation
+ *     lifecycle: useNavigation().state, useLinkStatus().pending, and
+ *     useAction().state stay "idle". Assert pending/loading/submitting transition
+ *     states with renderServerTree / e2e instead (navigate() warns once if used).
  * What it DOES cover: client hooks that read NavigationProvider /
  * OutletContext — useParams, useReverse, useHref, useMount, useNavigation,
  * useRouter, usePathname, useSearchParams, Outlet nesting, useLoader /
@@ -53,6 +57,7 @@ import type { LocationStateDefinition } from "../browser/react/location-state-sh
 import type { Handle } from "../handle.js";
 import type { ThemeConfig } from "../theme/types.js";
 import { resolveThemeConfig } from "../theme/constants.js";
+import { isUnderTestRunner } from "../runtime-env.js";
 
 const TEST_ORIGIN = "http://localhost";
 
@@ -63,11 +68,6 @@ const TEST_ORIGIN = "http://localhost";
  */
 export type HandleDataSeed = Record<string, Record<string, unknown[]>>;
 
-// Loaders and location-state defs carry an id (`$$id` / `__rsc_ls_key`) that the
-// Vite plugin injects at build time; in a bare test it is "". These helpers
-// assign a synthetic stable id (mutating the handle, tracked per-object) so that
-// seeding by reference lines up with the read path (useLoader / useLocationState
-// both read the id off the handle at call time).
 const syntheticIds = new WeakMap<object, string>();
 let syntheticIdCounter = 0;
 
@@ -86,7 +86,6 @@ function ensureSyntheticId(
   return id;
 }
 
-/** One-level clone of a raw handle seed so we don't mutate the caller's object. */
 function cloneHandleSeed(seed?: HandleDataSeed): HandleDataSeed {
   const out: HandleDataSeed = {};
   for (const [name, segMap] of Object.entries(seed ?? {})) {
@@ -95,12 +94,6 @@ function cloneHandleSeed(seed?: HandleDataSeed): HandleDataSeed {
   return out;
 }
 
-/**
- * One node of the route definition passed to renderRoute. The array models a
- * single matched route plus its optional layout chain — element order is
- * outermost layout first, the leaf route last (the same root-to-leaf order the
- * real matcher produces).
- */
 export interface RenderRouteSpec {
   /**
    * The route pattern this node matches, e.g. "/products/:productId". The LAST
@@ -172,7 +165,10 @@ export interface RenderRouteOptions {
   /**
    * Explicit params. Merged over (and overriding) params extracted from the
    * `request` URL. Use this when the URL alone cannot express the params, or to
-   * avoid relying on URL parsing.
+   * avoid relying on URL parsing. Supplying params also OPTS OUT of the
+   * request/leaf match check: a `request` whose pathname does not resolve the
+   * leaf is normally rejected under the test runner, but passing params here
+   * tells renderRoute the request is intentionally not the param source.
    */
   params?: Record<string, string>;
   /**
@@ -236,6 +232,10 @@ export interface RenderRouteOptions {
    * exactly as `renderSegments` does in production (a segment whose `mountPath`
    * is set is wrapped in a MountContextProvider). Normalized like a path prefix
    * (leading slash forced, trailing stripped, bare "/" -> root). Defaults to "/".
+   * An explicitly-passed `request` must match the leaf `path` directly (paths are
+   * include-RELATIVE; the mount does NOT rewrite the request) — pass the relative
+   * path, not the mount-prefixed one, or renderRoute throws rather than silently
+   * rendering empty params.
    *
    * @example
    * renderRoute([{ path: "/c/wine", Component: ProductPage }], { mount: "/shop" });
@@ -281,11 +281,6 @@ interface ResolvedMatch {
   pathname: string;
 }
 
-/**
- * Match a pathname against the leaf spec's pattern and extract params.
- * Returns null when the pattern does not match (params then fall back to the
- * caller-provided `options.params`).
- */
 function matchLeaf(
   pattern: string,
   pathname: string,
@@ -303,7 +298,6 @@ function matchLeaf(
   return params;
 }
 
-/** Derive a usable initial pathname from a leaf pattern when none is given. */
 function staticPrefix(pattern: string): string {
   const out: string[] = [];
   for (const part of pattern.split("/")) {
@@ -314,13 +308,6 @@ function staticPrefix(pattern: string): string {
   return "/" + out.join("/");
 }
 
-/**
- * Build the synthetic ResolvedSegment[] for a matched route. Produces, in
- * root-to-leaf order: one layout segment per non-leaf spec, then the leaf route
- * segment, plus a loader segment for each seeded loader id attached to the
- * owning spec. Segment ids follow the real convention (L0, L0L1, ..., the leaf
- * route as L0...R{n}; loaders as {parentId}D{i}.{loaderId}).
- */
 function buildSegments(
   routes: RenderRouteSpec[],
   params: Record<string, string>,
@@ -353,20 +340,13 @@ function buildSegments(
       params,
       belongsToRoute: true,
     };
-    // Model an include() mount: every component segment in the chain shares the
-    // same prefix, so renderSegments wraps each in a MountContextProvider and
-    // useMount() resolves the mounted prefix (production sets mountPath on every
-    // segment of an included subtree). Must be applied identically at both
-    // buildSegments call sites or segment-structure-assert flags a remount.
     if (mount) node.mountPath = mount;
-    // A leaf-owned layout component wraps the route via its own layout element.
     if (isLeaf && spec.layout) {
       const Layout = spec.layout;
       node.layout = <Layout />;
     }
     segments.push(node);
 
-    // Determine which seeded loader ids this spec owns.
     const ownedIds = spec.loaderIds
       ? spec.loaderIds.filter((id) => id in loaderData)
       : isLeaf
@@ -390,30 +370,6 @@ function buildSegments(
   return segments;
 }
 
-/**
- * Render a CLIENT component (and its layout chain) inside the router's
- * NavigationProvider for unit testing. Exported from `@rangojs/router/testing/dom`
- * (its own entry, kept out of the main `@rangojs/router/testing` barrel so that
- * barrel never references React/@testing-library/react). Async so the heavy
- * @testing-library/react dependency is loaded only at call time.
- *
- * @example
- * ```tsx
- * // @vitest-environment happy-dom
- * import { renderRoute } from "@rangojs/router/testing/dom";
- *
- * function Product() {
- *   const { productId } = useParams<{ productId: string }>();
- *   const reverse = useReverse({ product: "/products/:productId" });
- *   return <a href={reverse("product", { productId: "2" })}>{productId}</a>;
- * }
- *
- * const { getByText, router } = await renderRoute(
- *   [{ path: "/products/:productId", Component: Product }],
- *   { request: "/products/1" },
- * );
- * ```
- */
 export async function renderRoute(
   routes: RenderRouteSpec[],
   options: RenderRouteOptions = {},
@@ -421,9 +377,6 @@ export async function renderRoute(
   if (routes.length === 0) {
     throw new Error("renderRoute: `routes` must contain at least one entry");
   }
-  // The pre-rename `initialUrl` option was renamed to `request`. A plain-JS or
-  // spread-defeated caller still passing it would otherwise be silently ignored;
-  // fail loud with the migration name instead.
   if ("initialUrl" in options) {
     throw new Error(
       "renderRoute: the `initialUrl` option was renamed to `request`. " +
@@ -439,30 +392,19 @@ export async function renderRoute(
   const initialUrl = requestUrl ?? staticPrefix(leaf.path) ?? "/";
   const url = new URL(initialUrl, TEST_ORIGIN);
 
-  // Seed loader data: explicit-id entries from `loaderData`, plus by-reference
-  // entries from `loaders` (assigning synthetic ids to real handles whose `$$id`
-  // is empty in a bare test).
   const loaderData: Record<string, unknown> = { ...(options.loaderData ?? {}) };
   for (const [loader, data] of options.loaders ?? []) {
     loaderData[ensureSyntheticId(loader as object, "$$id")] = data;
   }
 
-  // Seed location state into history.state so useLocationState(def) resolves.
-  // Keyed defs read history.state[def.__rsc_ls_key]; assign a synthetic key when
-  // the injected one is empty (bare test). RESET history.state to only this
-  // call's seeds (not a merge) so a previous render's seeded state does not leak
-  // into a later render in the same DOM environment.
   if (typeof window !== "undefined") {
     const stateObj: Record<string, unknown> = {};
     for (const [def, value] of options.locationState ?? []) {
       stateObj[ensureSyntheticId(def as object, "__rsc_ls_key")] = value;
     }
-    // No URL arg: useLocationState reads history.state (not the URL), and passing
-    // a TEST_ORIGIN URL would trip the DOM env's same-origin check.
     window.history.replaceState(stateObj, "");
   }
 
-  // Resolve params: URL-extracted params first, explicit params override.
   const resolve = (pathname: string): ResolvedMatch => {
     const matched = matchLeaf(leaf.path, pathname) ?? {};
     return {
@@ -472,11 +414,34 @@ export async function renderRoute(
   };
   const initialMatch = resolve(url.pathname);
 
-  // Reuse the real browser primitives so context shape matches production.
   const historyKey = generateHistoryKey(url.href);
-  // Normalize the include() mount prefix once and apply it at BOTH buildSegments
-  // call sites (initial + navigate) so mountPath is consistent across renders.
   const mount = normalizeBasename(options.mount);
+  // Fail loud on a request that cannot resolve the leaf route (a typo, or the
+  // mount-prefixed-vs-relative confusion) instead of silently rendering empty
+  // params (matchLeaf -> null -> {}). renderRoute paths are include-RELATIVE and
+  // resolve() matches the request against the leaf as-is, so the request must be
+  // the relative form — a mount does NOT rewrite it. Only checked when `request`
+  // was passed explicitly (a defaulted request is staticPrefix of the leaf and
+  // always matches). Skipped when explicit `params` are supplied: those are
+  // merged over the URL-extracted params in resolve(), so the request is
+  // intentionally not the param source and an empty matchLeaf is not the trap.
+  // Gated on the test runner so it can never affect production.
+  if (
+    options.request !== undefined &&
+    Object.keys(options.params ?? {}).length === 0 &&
+    isUnderTestRunner() &&
+    matchLeaf(leaf.path, url.pathname) === null
+  ) {
+    throw new Error(
+      `renderRoute: request "${url.pathname}" does not match the leaf route ` +
+        `"${leaf.path}"${mount ? ` (mount "${mount}")` : ""}. renderRoute paths ` +
+        `are include-RELATIVE: pass a request that matches "${leaf.path}" ` +
+        `(e.g. "${staticPrefix(leaf.path)}"). A mount does NOT auto-rewrite the ` +
+        `request — pass the relative path, not the mount-prefixed one. If the ` +
+        `request URL intentionally does not carry the params, pass them ` +
+        `explicitly via the \`params\` option to bypass this check.`,
+    );
+  }
   const initialSegments = buildSegments(
     routes,
     initialMatch.params,
@@ -490,20 +455,12 @@ export async function renderRoute(
     initialSegments,
     crossTabSync: false,
   });
-  // Seed handle data: raw `handle` entries plus by-reference `handles` attached
-  // to the leaf route segment under each handle's id (so useHandle(handle)
-  // resolves the pushed values).
   const leafRouteSegmentId =
     [...initialSegments].reverse().find((s) => s.type === "route")?.id ??
     initialSegments[initialSegments.length - 1]?.id;
   const handleSeed: HandleDataSeed = cloneHandleSeed(options.handle);
   for (const [handle, values] of options.handles ?? []) {
     if (leafRouteSegmentId === undefined) continue;
-    // createHandle always has a non-empty $$id (the Vite plugin injects one, and
-    // createHandle assigns a runtime fallback otherwise) with its REAL collect
-    // registered — so seeding under handle.$$id makes useHandle(handle) run the
-    // handle's actual collect/accumulator (custom collects included), not just a
-    // default flatten.
     const id = (handle as unknown as { $$id: string }).$$id;
     (handleSeed[id] ??= {})[leafRouteSegmentId] = values;
   }
@@ -515,15 +472,23 @@ export async function renderRoute(
     initialSegments.map((s) => s.id),
   );
 
-  // Client-only navigation: re-resolve against the in-memory routes and emit a
-  // re-render. No server fetch — only routes passed to renderRoute exist. The
-  // store update is flushed inside act() so React commits before callers
-  // assert, mirroring how a real navigation lands a single payload swap.
-  // NOTE: the seeded `loaderData` is reused for the target route too (no
-  // per-route loader fetch in a unit test), so every seeded loader stays
-  // available after navigate() — unlike a real navigation, which would fetch
-  // the target route's own loaders. This is a deliberate test-isolation design.
+  let warnedNavLifecycle = false;
   const navigate = async (target: string): Promise<void> => {
+    // renderRoute commits navigations synchronously (no server fetch, no Flight
+    // stream), so it never drives the navigation lifecycle. The transition state
+    // useNavigation()/useLinkStatus()/useAction() read stays "idle" — asserting a
+    // pending/loading/submitting state here proves nothing. Warn once (per render)
+    // under the test runner so that false-confidence trap is loud, not silent.
+    if (isUnderTestRunner() && !warnedNavLifecycle) {
+      warnedNavLifecycle = true;
+      console.warn(
+        "renderRoute: navigate()/useRouter().push commit synchronously and do " +
+          "NOT drive the navigation lifecycle. useNavigation().state, " +
+          'useLinkStatus().pending, and useAction().state stay "idle" here. ' +
+          "Assert params/pathname/content after navigate(); use renderServerTree " +
+          "or e2e to assert pending/loading/submitting transition states.",
+      );
+    }
     const nextUrl = new URL(target, TEST_ORIGIN);
     const match = resolve(nextUrl.pathname);
     const segments = buildSegments(routes, match.params, loaderData, mount);
@@ -554,18 +519,26 @@ export async function renderRoute(
   );
   const initialTree = await renderSegments(initialSegments);
 
-  const result = render(
-    <NavigationProvider
-      store={store}
-      eventController={eventController}
-      initialPayload={{ root: initialTree, metadata: initialMetadata }}
-      bridge={bridge}
-      basename={normalizeBasename(options.basename)}
-      themeConfig={
-        options.theme === undefined ? null : resolveThemeConfig(options.theme)
-      }
-    />,
-  );
+  // Wrap render in an awaited async act so a tree that suspends (async loaders,
+  // loading states, deferred handle entries that arrive as a Promise) settles its
+  // Suspense within act — otherwise React orphans the resolution ("a component
+  // suspended inside an act scope, but the act call was not awaited") and the
+  // resolved content never reaches the asserted DOM.
+  let result!: Awaited<ReturnType<typeof render>>;
+  await act(async () => {
+    result = render(
+      <NavigationProvider
+        store={store}
+        eventController={eventController}
+        initialPayload={{ root: initialTree, metadata: initialMetadata }}
+        bridge={bridge}
+        basename={normalizeBasename(options.basename)}
+        themeConfig={
+          options.theme === undefined ? null : resolveThemeConfig(options.theme)
+        }
+      />,
+    );
+  });
 
   const router: TestRouterHandle = {
     navigate,
@@ -578,7 +551,6 @@ export async function renderRoute(
   return Object.assign(result, { router });
 }
 
-/** Minimal RscMetadata for client-side re-renders (no server-only fields). */
 function makeMetadata(
   pathname: string,
   segments: ResolvedSegment[],

package/src/testing/run-loader.ts

@@ -177,10 +177,6 @@ export interface RunLoaderOptions<TEnv = any> {
   handles?: ReadonlyArray<readonly [Handle<any, any>, unknown]>;
 }
 
-/**
- * Merge `search` into a request's URL, returning a value `toRequest` can build.
- * Keeps the original method/headers/body when a Request was passed.
- */
 function withSearch(
   request: Request | string | undefined,
   search: Record<string, string> | undefined,
@@ -206,16 +202,6 @@ export type RunnableLoader<T> =
   | ((ctx: TestLoaderContext) => Promise<T> | T)
   | LoaderDefinition<T, any>;
 
-/**
- * Resolve the function to run from either a raw body or a `createLoader()` handle.
- *
- * A handle carries no inline body (`createLoader` registers it in the fetchable
- * registry by `$$id`), so recover it from there — `def.fn` first (a hand-built
- * def), then the registry. This works when the handle resolves through the
- * SERVER build (the consumer's `@rangojs/router` under `rangoTestConfig`, which
- * registers the fn); the CLIENT stub drops the body, so a handle imported that
- * way is unrecoverable and we say so explicitly.
- */
 function resolveLoaderFn<T>(
   loader: RunnableLoader<T>,
 ): (ctx: TestLoaderContext) => Promise<T> | T {
@@ -237,31 +223,11 @@ function resolveLoaderFn<T>(
   return fn as (ctx: TestLoaderContext) => Promise<T> | T;
 }
 
-/**
- * Run a loader and return its resolved data. Pass the RAW loader body, or a
- * registered `createLoader()` handle (its fn is recovered from the registry).
- *
- * @example
- * ```ts
- * // raw body
- * const a = await runLoader(
- *   async (ctx) => ({ id: ctx.params.id, user: ctx.get("user") }),
- *   { params: { id: "42" }, vars: { user: { name: "Ada" } } },
- * );
- * // registered createLoader() handle (recovered from the registry)
- * const b = await runLoader(ProductLoader, { params: { id: "42" } });
- * ```
- */
-// Build the createTestRequestContext options from runLoader's options. Shared by
-// runLoader (returns the loader data) and runLoaderResult (also snapshots effects).
 function buildLoaderCtxOpts(
   opts: RunLoaderOptions,
 ): CreateTestContextOptions<any> {
   return {
     env: opts.env,
-    // Bake opts.search into the request URL itself so ctx.request.url, ctx.url,
-    // and ctx.searchParams all agree (production carries the query string on the
-    // real request — a loader reading ctx.request.url must see it too).
     request: withSearch(opts.request, opts.search),
     requestInit: opts.method ? { method: opts.method } : undefined,
     vars: opts.vars,
@@ -276,33 +242,19 @@ function buildLoaderCtxOpts(
   };
 }
 
-// Enter `reqCtx` and run `fn` with a seeded TestLoaderContext (the same ctx shape
-// a real loader receives). The single place the loader context is built, so
-// runLoader and runLoaderResult share identical loader-context semantics.
 function runWithLoaderContext<R>(
   reqCtx: RequestContext<any>,
   opts: RunLoaderOptions,
   fn: (ctx: TestLoaderContext) => R,
 ): R {
-  // Seed values for ctx.use(SomeHandle), matched by handle reference (so a real
-  // handle resolves regardless of its build-injected $$id).
   const handleSeeds = new Map<unknown, unknown>(opts.handles ?? []);
-
-  // Seed values for ctx.use(OtherLoader), matched by loader reference (same model
-  // as renderHandler/renderRoute). Checked before the `use` resolver.
   const loaderSeeds = new Map<unknown, unknown>(opts.loaders ?? []);
-
-  // Tracks whether the mocked render barrier has settled. ctx.use(handle)
-  // reads are gated on this, matching production (loader-resolution.ts).
   let renderedResolved = false;
 
   return runWithRequestContext(reqCtx, () => {
     const reverse = opts.routeMap
       ? createReverseFunction(opts.routeMap, opts.routeName, opts.params ?? {})
       : ((() => {
-          // Documented contract: reverse requires routeMap. Do NOT fall back to
-          // reqCtx.reverse (the global route map) — that leaks whichever routes
-          // another test registered and contradicts the documented behavior.
           throw new Error(
             "ctx.reverse() requires the `routeMap` option in runLoader(). " +
               "Pass { routeMap: { name: pattern, ... } } to enable reverse().",
@@ -323,10 +275,6 @@ function runWithLoaderContext<R>(
       executionContext: reqCtx.executionContext,
       get: reqCtx.get as TestLoaderContext["get"],
       use: ((dep: LoaderDefinition<any, any> | Handle<any, any>) => {
-        // Match production (loader-resolution.ts): reading a handle in a loader
-        // requires the render barrier to have settled. Gate BEFORE returning a
-        // seed, so a loader that forgets `await ctx.rendered()` fails in the
-        // test exactly as it would at runtime.
         if (isHandle(dep) && !renderedResolved) {
           throw new Error(
             `ctx.use(handle) in a loader requires "await ctx.rendered()" first. ` +
@@ -334,16 +282,8 @@ function runWithLoaderContext<R>(
               `the render tree has settled.`,
           );
         }
-        // Handle reads (ctx.use(SomeHandle)) resolve from the seeded map first.
         if (handleSeeds.has(dep)) return handleSeeds.get(dep);
-        // Post-barrier, an UNSEEDED handle must match production
-        // (loader-resolution.ts -> collectHandleData), which runs the handle's
-        // registered collect over empty segments (collect([])) rather than
-        // throwing or leaking into the loader resolver. Resolve it via
-        // collectHandle, which recovers and runs that same collect.
         if (isHandle(dep)) return collectHandle(dep, []);
-        // Loader reads (ctx.use(OtherLoader)) resolve from the seeded map next,
-        // then the dynamic `use` resolver, then the real request-context use().
         if (loaderSeeds.has(dep)) return loaderSeeds.get(dep);
         if (opts.use) return opts.use(dep as LoaderDefinition<any, any>);
         return reqCtx.use(dep as LoaderDefinition<any, any>);
@@ -358,7 +298,6 @@ function runWithLoaderContext<R>(
               if (typeof opts.rendered === "function") {
                 await opts.rendered();
               }
-              // Barrier has settled: subsequent ctx.use(handle) reads resolve.
               renderedResolved = true;
             }
           : () => {
@@ -377,13 +316,6 @@ function runWithLoaderContext<R>(
   });
 }
 
-/**
- * Run a loader and return its resolved data.
- *
- * Effects the loader sets (cookies, response headers, a thrown redirect) are NOT
- * observable here — use {@link runLoaderResult} for an auth-style loader that
- * sets a `Set-Cookie` and/or `throw redirect(...)`.
- */
 export async function runLoader<T>(
   loader: RunnableLoader<T>,
   opts: RunLoaderOptions = {},
@@ -395,12 +327,6 @@ export async function runLoader<T>(
   );
 }
 
-/**
- * What a loader run accumulated: its data PLUS the response effects it produced,
- * surfaced as PUBLIC values (parity with `runMiddleware`/`runInRequestContext`)
- * so an effect-setting loader is assertable without casting through the
- * `@internal` request context.
- */
 export interface RunLoaderResult<T> {
   /**
    * The loader's resolved data (the value bare `runLoader` returns), or
@@ -430,25 +356,6 @@ export interface RunLoaderResult<T> {
   stateCookieName: string;
 }
 
-/**
- * Run a loader AND surface the response effects it produced. The richer sibling
- * of {@link runLoader} (which returns the bare data): use this when the loader
- * sets a cookie / response header / location-state, or `throw redirect(...)`, and
- * the test must assert that output.
- *
- * @example
- * ```ts
- * // AuthLoader: validates, sets a `session` cookie, then `throw redirect("/")`.
- * const { thrown, response, cookies } = await runLoaderResult(AuthLoader, {
- *   request: new Request("https://app.test/login?token=ok"),
- * });
- * expect((thrown as Response).headers.get("Location")).toBe("/");
- * expect(cookies.session).toBeDefined();
- * expect(
- *   response.headers.getSetCookie().some((c) => c.startsWith("session=")),
- * ).toBe(true);
- * ```
- */
 export async function runLoaderResult<T>(
   loader: RunnableLoader<T>,
   opts: RunLoaderOptions = {},
@@ -465,9 +372,6 @@ export async function runLoaderResult<T>(
       Promise.resolve(loaderFn(loaderCtx)),
     );
   } catch (error) {
-    // Capture (do NOT re-throw): a loader's success path is often
-    // `throw redirect(...)`, and the cookie/flash it set before the throw must
-    // stay observable (parity with runInRequestContext).
     thrown = error;
   }
   return { result, ...buildRunSnapshot(reqCtx, thrown, stateCookieName) };

package/src/testing/run-middleware.ts

@@ -133,21 +133,6 @@ export interface RunMiddlewareResult<TEnv = any> {
   stateCookieName: string;
 }
 
-/**
- * Run a middleware chain and return the response plus observable context.
- *
- * @example
- * ```ts
- * const { response, ctx, nextCalled } = await runMiddleware(
- *   async (ctx, next) => {
- *     if (!ctx.get("user")) return new Response(null, { status: 401 });
- *     return next();
- *   },
- *   { request: "/dashboard", vars: [["user", { id: 1 }]] },
- * );
- * // nextCalled === 1, response.status === 200
- * ```
- */
 export async function runMiddleware<TEnv = any>(
   mw: MiddlewareFn<TEnv> | MiddlewareFn<TEnv>[],
   opts: RunMiddlewareOptions<TEnv>,
@@ -181,11 +166,6 @@ export async function runMiddleware<TEnv = any>(
     return opts.next?.() ?? new Response(null, { status: 200 });
   };
 
-  // Match production: app/response middleware receive ctx.reverse built from the
-  // route map ALONE (no matched route name or current params), so reversing a
-  // parameterized route without explicit params does NOT auto-fill from the
-  // current request. Passing routeName/params here would recreate the
-  // false-confidence class fixed in dispatch.
   const reverse = opts.routeMap
     ? (createReverseFunction(opts.routeMap) as (
         name: string,
@@ -194,12 +174,6 @@ export async function runMiddleware<TEnv = any>(
       ) => string)
     : undefined;
 
-  // Keep the RETURNED ctx.reverse consistent with the map-only reverse the
-  // chain receives. createTestRequestContext installs an auto-fill reverse
-  // (correct for the loader phase) when routeName/params are passed, but
-  // production app/response middleware see a map-only reverse. Without this,
-  // a middleware reading getRequestContext().reverse — or a consumer asserting
-  // on result.ctx.reverse — would observe auto-fill that production never does.
   if (reverse) {
     (ctx as RequestContext<TEnv>).reverse =
       reverse as RequestContext<TEnv>["reverse"];