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

package/src/testing/flight-matchers.ts

@@ -42,14 +42,6 @@ interface MatcherResult {
   message: () => string;
 }
 
-/**
- * Matcher object for `expect.extend(flightMatchers)`.
- *
- * - `toMatchFlight(received, expected)` — `received` is a rendered Flight
- *   string; passes if its normalized form contains `expected`.
- * - `toMatchFlightSnapshot(received)` — delegates to vitest's snapshot on the
- *   normalized Flight string.
- */
 export const flightMatchers: {
   toMatchFlight(received: string, expected: string): MatcherResult;
   toMatchFlightSnapshot(received: string): MatcherResult;
@@ -78,12 +70,7 @@ export const flightMatchers: {
   },
 
   toMatchFlightSnapshot(received: string): MatcherResult {
-    // Delegate to vitest's snapshot engine on the normalized string. The
-    // snapshot is keyed by the current test file/title (vitest tracks this via
-    // the active test context), not by this call site, so delegating through a
-    // freshly imported `expect` is reliable.
     expect(normalizeFlight(received)).toMatchSnapshot();
-    // toMatchSnapshot throws on mismatch; reaching here means it passed.
     return {
       pass: true,
       message: () => "Flight snapshot matched.",

package/src/testing/flight-normalize.ts

@@ -1,36 +1,9 @@
-/**
- * normalizeFlight — scrub volatile bits from a Flight wire string so snapshots
- * are stable across runs/machines.
- *
- * This is two regex replacements and NOTHING else. It is split out of flight.ts
- * on purpose: flight.ts top-level imports the vendored react-server-dom
- * serializer, which throws when imported outside the `react-server` export
- * condition. The flight-matchers module (and a consumer's shared `setupFiles`
- * that does `expect.extend(flightMatchers)`) must be importable under the PLAIN
- * node condition, so the normalizer it needs cannot live next to that import.
- * flight.ts re-exports normalizeFlight from here, so the public surface of the
- * `@rangojs/router/testing/flight` entry is unchanged.
- */
-
-// Volatile leading reference row: `:N<timestamp>` (dev debug-info anchor).
+// Volatile leading reference row: `:N<timestamp>` (dev only).
 const REFERENCE_ROW_RE = /^:N[\d.]+\n/;
-// Absolute file:// paths embedded in dev STACK rows. The serializer emits stack
-// frames as `["Component","file:///abs/path.tsx",<line>,<col>,...]`, so the
-// path is a quoted JSON string immediately followed by `",<line>,<col>`. The
-// lookahead scopes the scrub to exactly that frame shape, leaving a legitimate
-// `file://` href in RENDERED content (e.g. `{"href":"file:///x"}`) untouched.
+// Absolute file:// paths in dev stack rows. Pattern matches frames
+// `["Component","file:///path",<line>,<col>...]` and scrubs the path only.
 const FILE_URL_RE = /file:\/\/[^"\\]+(?=",\d+,\d+)/g;
 
-/**
- * Scrub volatile bits from a Flight string so snapshots are stable across runs
- * and machines:
- * - the leading `:N<timestamp>` reference row (dev only),
- * - absolute `file://...` paths inside dev stack rows.
- *
- * Under NODE_ENV=production these rows are already absent; normalize is a
- * no-op safety net there. In dev mode it removes the machine/clock-specific
- * noise while leaving the rendered tree intact.
- */
 export function normalizeFlight(flight: string): string {
   return flight
     .replace(REFERENCE_ROW_RE, "")

package/src/testing/flight.ts

@@ -82,13 +82,6 @@ export interface RenderToFlightStringOptions {
 
 const DEFAULT_URL = "http://localhost/";
 
-/**
- * Guard the pre-rename `{ url }` option (renamed to `{ request }`). A plain-JS
- * consumer, or one whose object spread defeats the compile-time type error,
- * would otherwise have `{ url }` SILENTLY ignored and render against
- * http://localhost/. Throw a clear migration error instead. Cheap: a single
- * `in` check on the already-built options object.
- */
 export function assertNoLegacyUrlOption(opts: object, fnName: string): void {
   if ("url" in opts) {
     throw new Error(
@@ -100,11 +93,6 @@ export function assertNoLegacyUrlOption(opts: object, fnName: string): void {
   }
 }
 
-/**
- * Wrap a single element in the minimal ResolvedSegment + RscPayload shape that
- * mirrors Rango's wire format, so the serialized output matches what a real
- * route segment would emit.
- */
 function wrapAsPayload(element: ReactNode, pathname: string): RscPayload {
   const segment: ResolvedSegment = {
     id: "test",
@@ -137,20 +125,9 @@ export async function renderToFlightString(
   opts: RenderToFlightStringOptions = {},
 ): Promise<string> {
   assertNoLegacyUrlOption(opts, "renderToFlightString");
-  // Server-only trees: empty client manifest. A client reference would emit an
-  // unresolvable `I` row here; use renderServerTree (flight-tree.ts) when the
-  // tree has client boundaries you want to inspect.
   return serializeToFlightString(element, opts, {});
 }
 
-/**
- * Shared serialize core: set up a request context, wrap the element as a Rango
- * payload, and serialize it with the given client-reference manifest. Used by
- * {@link renderToFlightString} (empty manifest) and renderServerTree (a manifest
- * that resolves every registered client reference).
- *
- * Must run under the `react-server` export condition (see module header).
- */
 export async function serializeToFlightString(
   element: ReactNode,
   opts: RenderToFlightStringOptions,
@@ -167,8 +144,6 @@ export async function serializeToFlightString(
     env: opts.env ?? {},
     request,
     url,
-    // Seed vars so a server component reading ctx.get(MyVar) during render sees
-    // them — same seeding the handler-test primitives use.
     variables: seedVariables({}, opts.vars),
   });
 
@@ -178,28 +153,12 @@ export async function serializeToFlightString(
   });
 }
 
-/**
- * Serialize a node to a Flight string, ASSUMING a request context is already
- * active (i.e. called inside `runWithRequestContext`). This is the core
- * `renderHandler` reuses: it enters its own context, builds a HandlerContext,
- * invokes the handler, then serializes the returned RSC in that SAME context (so
- * cookies/headers/vars/handles the handler set are all on one context).
- *
- * Must run under the `react-server` export condition (see module header).
- */
 export async function serializeNodeToFlight(
   node: ReactNode,
   clientManifest: unknown,
   pathname: string,
 ): Promise<string> {
   const payload = wrapAsPayload(node, pathname);
-  // Capture (do NOT rethrow) the first render error. The serializer calls
-  // onError from its own scheduled work; throwing there escapes as an unhandled
-  // rejection AND leaves the stream un-closed, so the drain below would hang
-  // until the test times out. Production's onError returns void (rsc-rendering.ts)
-  // so the stream completes with an error row. We mirror that — let the stream
-  // finish — then surface the error as a clean rejection after draining, so
-  // `await expect(...).rejects.toThrow()` works.
   let renderError: unknown;
   let didError = false;
   const stream = RSDServer.renderToReadableStream(payload, clientManifest, {
@@ -210,18 +169,11 @@ export async function serializeNodeToFlight(
       }
     },
   });
-  // Drain inside the context so async components see ctx during streaming.
   const text = await new Response(stream).text();
   if (didError) throw renderError;
   return text;
 }
 
-/**
- * Smoke check that the vendored serializer subpath still resolves and exposes
- * `renderToReadableStream`. The vendored path is private to plugin-rsc; a minor
- * bump could relocate it. Call this in a test to fail loudly with a clear
- * message instead of an opaque import error.
- */
 export function assertFlightRuntimeAvailable(): void {
   if (typeof RSDServer.renderToReadableStream !== "function") {
     throw new Error(

package/src/testing/generated-routes.ts

@@ -32,14 +32,6 @@ interface RouterWithRouteMap {
   findMatch?: (pathname: string) => unknown;
 }
 
-/**
- * Derive a best-effort concrete path from a route pattern so `findMatch` can be
- * invoked to expand a lazy include. `:param`, `:param(constraint)`, optional
- * `:param?`, and `*` are all replaced with a literal segment. A constrained
- * param may not match its constraint (so that one route's match fails), but
- * since matching ANY route in an include expands ALL of the include's routes,
- * a sibling route in the same include will still trigger expansion.
- */
 function concretePath(pattern: string): string {
   return (
     pattern
@@ -50,17 +42,6 @@ function concretePath(pattern: string): string {
   );
 }
 
-/**
- * Force-expand the router's lazy `include()`d routes into `router.routeMap`.
- *
- * All Rango includes are lazy — their child routes only populate `routeMap` when
- * the router first matches a path inside them (in production the build-time
- * manifest virtual carries the full map; in a bare test that virtual is absent).
- * To make the whole-app drift check work in a unit test, we trigger expansion by
- * calling `findMatch` on a concrete path derived from each known pattern. This is
- * idempotent and side-effect-free beyond populating the route map. Routers that
- * don't expose `findMatch` (e.g. a plain `{ routeMap }` object) are left as-is.
- */
 function expandLazyIncludes(
   router: RouterWithRouteMap,
   patterns: Iterable<string>,
@@ -70,10 +51,7 @@ function expandLazyIncludes(
   for (const pattern of patterns) {
     try {
       findMatch.call(router, concretePath(pattern));
-    } catch {
-      // A pattern that fails to match (constrained param, etc.) is fine — a
-      // sibling route in the same include still triggers expansion.
-    }
+    } catch {}
   }
 }
 
@@ -100,11 +78,6 @@ export interface GeneratedRoutesDiff {
   ok: boolean;
 }
 
-/**
- * Normalize a route map value to its pattern string. Route maps may carry
- * either a bare pattern string or a `{ path, ... }` object (for response/search
- * routes); compare on the `path`.
- */
 function patternOf(value: unknown): string {
   if (typeof value === "string") return value;
   if (
@@ -118,19 +91,12 @@ function patternOf(value: unknown): string {
   return String(value);
 }
 
-/**
- * Compute the diff between a router's runtime route map and a generated map.
- */
 export function diffGeneratedRoutes(
   router: RouterWithRouteMap,
   generatedMap?: Record<string, unknown>,
 ): GeneratedRoutesDiff {
   const generated = generatedMap ?? getGlobalRouteMap();
 
-  // Lazy `include()`d routes are absent from `routeMap` until first matched, so
-  // expand them first (using the generated patterns to drive the matches) —
-  // otherwise every included route is a false `missing`. No-op for plain
-  // `{ routeMap }` objects that don't expose `findMatch`.
   expandLazyIncludes(
     router,
     Object.values(generated).map((v) => patternOf(v)),
@@ -155,12 +121,6 @@ export function diffGeneratedRoutes(
   }
 
   for (const name of Object.keys(runtime)) {
-    // Auto-generated internal names ($path_*/$prefix_*) live in the runtime
-    // mergedRouteMap but are deliberately excluded from the generated
-    // *.named-routes.gen.ts file (route-types-writer / runtime-discovery skip
-    // them). Reporting them as `extra` would throw on a perfectly in-sync app
-    // that simply uses an unnamed path()/include() route, so skip them here to
-    // match exactly the surface the generator emits.
     if (isAutoGeneratedRouteName(name)) continue;
     if (!(name in generated)) {
       extra.push(name);

package/src/testing/index.ts

@@ -34,7 +34,6 @@
  * - RSC:         see @rangojs/router/testing/flight
  */
 
-// Unit
 export { runMiddleware } from "./run-middleware.js";
 export type {
   RunMiddlewareOptions,
@@ -48,15 +47,9 @@ export type {
   TestLoaderContext,
 } from "./run-loader.js";
 
-// Integration
 export { dispatch } from "./dispatch.js";
 export type { DispatchOptions } from "./dispatch.js";
 
-// renderRoute lives at `@rangojs/router/testing/dom` — it pulls React, the
-// browser runtime, and @testing-library/react types, which this barrel keeps
-// out so node-only unit suites depend on none of them.
-
-// Cross-cutting: cache/prerender status
 export {
   assertCacheStatus,
   parseCacheHeader,
@@ -68,9 +61,6 @@ export type {
   CacheStatusTarget,
   CacheSink,
 } from "./cache-status.js";
-// The telemetry event types a cache-status assertion inspects (createCacheSink
-// records CacheDecisionEvents; filterCacheDecisions narrows them). Re-exported
-// here so a test can annotate the events without reaching past `@rangojs/router/testing`.
 export type {
   TelemetryEvent,
   TelemetrySink,
@@ -79,10 +69,8 @@ export type {
   CacheSegmentStatus,
 } from "../router/telemetry.js";
 
-// Cross-cutting: handle collect/accumulator
 export { collectHandle } from "./collect-handle.js";
 
-// Cross-cutting: generated-route drift
 export {
   diffGeneratedRoutes,
   assertGeneratedRoutesMatch,
@@ -92,7 +80,6 @@ export type {
   GeneratedRouteMismatch,
 } from "./generated-routes.js";
 
-// Advanced: build a real RequestContext for bespoke loader/middleware setups
 export {
   createTestRequestContext,
   runInRequestContext,
@@ -108,12 +95,4 @@ export type {
   StateCookieSeed,
 } from "./internal/context.js";
 
-// The low-level context runner that enters a RequestContext (the same one the
-// RSC handler uses for server actions). Re-exported so a ctx built with
-// createTestRequestContext can be entered directly; runInRequestContext is the
-// one-call convenience over createTestRequestContext + runWithRequestContext.
 export { runWithRequestContext } from "../server/request-context.js";
-
-// The E2E harness is NOT re-exported here: it must be imported from
-// `@rangojs/router/testing/e2e` so it stays loadable in a plain Playwright
-// runner (this barrel pulls in router-manifest code that needs Vite virtuals).

package/src/testing/internal/context.ts

@@ -28,8 +28,6 @@ import type { CacheProfile } from "../../cache/profile-registry.js";
 
 const DEFAULT_ORIGIN = "http://localhost/";
 
-// VarsInit + seedVariables live in ./seed-vars.js (react-server-safe) so the
-// Flight tier can seed vars too; re-exported here for existing importers.
 export type { VarsInit, StateCookieSeed };
 export { seedVariables };
 
@@ -39,10 +37,9 @@ export function toRequest(
   init?: RequestInit,
 ): Request {
   if (request instanceof Request) return request;
-  if (typeof request === "string") {
-    return new Request(new URL(request, DEFAULT_ORIGIN), init);
-  }
-  return new Request(DEFAULT_ORIGIN, init);
+  return typeof request === "string"
+    ? new Request(new URL(request, DEFAULT_ORIGIN), init)
+    : new Request(DEFAULT_ORIGIN, init);
 }
 
 export interface CreateTestContextOptions<TEnv> {
@@ -146,10 +143,6 @@ export function createTestRequestContext<TEnv>(
   const request = toRequest(opts.request, opts.requestInit);
   const url = new URL(request.url);
   const variables = seedVariables(opts.variables ?? {}, opts.vars);
-  // Always seed a resolved name so invalidateClientCache() rotates (and emits
-  // the Set-Cookie) like production instead of no-opping; opts.stateCookie
-  // customizes the name/version. Surfaced on the result so a consumer asserts
-  // the rotation against the same name without recomputing it.
   const stateCookieName = resolveSeededStateCookieName(opts.stateCookie);
   const ctx = createRequestContext<TEnv>({
     env: (opts.env ?? {}) as TEnv,
@@ -174,10 +167,6 @@ export function createTestRequestContext<TEnv>(
       opts.params ?? {},
     ) as RequestContext<TEnv>["reverse"];
   }
-  // ctx.reverse is assigned the routeMap-scoped reverse (string-accepting) above;
-  // expose it through the relaxed type so a test reverses a local route name
-  // without casting. The runtime value matches; RequestContext's reverse is
-  // declared against the narrower global route-name union, hence the cast.
   return {
     ctx: ctx as unknown as TestRequestContextObject<TEnv>,
     request,
@@ -246,13 +235,6 @@ export interface RunInRequestContextResult<T> {
   stateCookieName: string;
 }
 
-/**
- * Snapshot the observable effects a run left on `ctx` (cookies + location
- * state). Reads the fields directly off the ctx object, so it works both inside
- * and outside the AsyncLocalStorage scope (no `getRequestContext()`). Headers are
- * snapshotted separately from the final {@link Response} (via
- * {@link headersToObject}) so a thrown redirect's `Location` is included.
- */
 export function snapshotRunEffects<TEnv>(ctx: RequestContext<TEnv>): {
   cookies: Record<string, string>;
   locationState: Record<string, unknown>;
@@ -263,12 +245,6 @@ export function snapshotRunEffects<TEnv>(ctx: RequestContext<TEnv>): {
   };
 }
 
-/**
- * The response headers as a plain `{ name: value }` object, EXCLUDING
- * `set-cookie` (surfaced parsed on `cookies`). Names are lowercased (HTTP header
- * names are case-insensitive). Read from the final response so a thrown
- * redirect's `Location` and any `ctx.header(...)` both appear.
- */
 export function headersToObject(headers: Headers): Record<string, string> {
   const out: Record<string, string> = {};
   headers.forEach((value, name) => {
@@ -278,14 +254,6 @@ export function headersToObject(headers: Headers): Record<string, string> {
   return out;
 }
 
-/**
- * Build the observable response from what the run accumulated on `ctx.res`. When
- * `fn` threw a `Response` (a `redirect()`/`notFound()`), that Response IS the
- * response — merge the accumulated Set-Cookie/other headers into it (the
- * framework does this when it catches the thrown Response in production), with
- * its status/Location preserved. Otherwise snapshot the stub (status + headers).
- * The `Response`/`Headers` constructors copy, so the result is immutable.
- */
 export function buildRunResponse<TEnv>(
   ctx: RequestContext<TEnv>,
   thrown: unknown,
@@ -305,14 +273,6 @@ export function buildRunResponse<TEnv>(
   return new Response(null, { status: stub.status, headers: stub.headers });
 }
 
-/**
- * Snapshot the shared run-result envelope fields (everything except the primary
- * value) from what a run left on `ctx`: the captured `thrown`, the merged
- * `response`, the effective `cookies`/`headers` views, the `locationState`, and
- * the resolved `stateCookieName`. Shared by `runInRequestContext` and
- * `runLoaderResult` so the snapshot sequence lives once; each spreads it next to
- * its own primary field (`result` / `data`).
- */
 export function buildRunSnapshot<TEnv>(
   ctx: RequestContext<TEnv>,
   thrown: unknown,
@@ -382,8 +342,6 @@ export async function runInRequestContext<T, TEnv = unknown>(
   try {
     result = (await runWithRequestContext(ctx, () => fn(ctx))) as T;
   } catch (error) {
-    // Capture (do NOT re-throw): a redirect/notFound action throws its Response
-    // on the SUCCESS path, and its cookie/flash output must stay observable.
     thrown = error;
   }
   return { result, ...buildRunSnapshot(ctx, thrown, stateCookieName) };

package/src/testing/internal/seed-vars.ts

@@ -9,14 +9,6 @@
 import { contextSet, type ContextVar } from "../../context-var.js";
 import { resolveStateCookieName } from "../../router/state-cookie-name.js";
 
-/**
- * Seed for the rango state cookie a handler/action/loader rotates when it calls
- * `invalidateClientCache()`. Production always resolves a name at router init
- * (so rotation always fires); the test stub did not, so the call silently
- * no-opped. Supplying this (or accepting the defaults) closes that gap. Lives in
- * the react-server-safe seed module so both the node tier (createTestRequestContext)
- * and the Flight tier (renderHandler) share one shape and one default.
- */
 export interface StateCookieSeed {
   /**
    * Cookie-name prefix, sanitized then composed with `routerId` exactly like
@@ -36,37 +28,19 @@ export interface StateCookieSeed {
   version?: string;
 }
 
-/**
- * Resolve the state cookie name a seed maps to, mirroring `createRouter`'s
- * `resolveStateCookieName` so a test asserts the SAME name production writes.
- * The default routerId `"router_0"` matches a single default router.
- */
 export function resolveSeededStateCookieName(seed?: StateCookieSeed): string {
   return resolveStateCookieName(seed?.prefix, seed?.routerId ?? "router_0");
 }
 
-/**
- * Initializer for seeded context variables (as a prior middleware would have
- * set, or a server component would read during render). Either a plain object
- * keyed by var name (the common, best-inferring form: `{ user: u }`) or a list
- * of `[key, value]` tuples where the key may be a `createVar()` handle or a
- * string (`[[userVar, u], ["flag", true]]`).
- */
 export type VarsInit =
   | Record<string, unknown>
   | ReadonlyArray<readonly [ContextVar<unknown> | string, unknown]>;
 
-/**
- * Preload variables as if set by upstream middleware (or visible to a rendered
- * server tree). Accepts entries keyed by either a ContextVar (from createVar) or
- * a string, matching ctx.set().
- */
 export function seedVariables(
   variables: Record<string, unknown>,
   vars?: VarsInit,
 ): Record<string, unknown> {
   if (!vars) return variables;
-  // Array/iterable form -> use the tuples as-is; plain object -> its entries.
   const entries: Iterable<readonly [ContextVar<unknown> | string, unknown]> =
     Symbol.iterator in (vars as object)
       ? (vars as ReadonlyArray<

package/src/testing/render-handler.ts

@@ -134,11 +134,6 @@ export interface RenderHandlerResult {
  */
 class RenderHandlerSetupError extends Error {}
 
-// Local copy (not imported from internal/context.ts): that module is the NODE
-// tier and is deliberately NOT react-server-safe (the reason seed-vars.ts was
-// split out), and render-handler ships from the react-server ./testing/flight
-// entry. A 6-line pure projection is cheaper to duplicate than to route a
-// shared util across that boundary.
 function headersToObject(headers: Headers): Record<string, string> {
   const out: Record<string, string> = {};
   headers.forEach((value, name) => {
@@ -147,15 +142,6 @@ function headersToObject(headers: Headers): Record<string, string> {
   return out;
 }
 
-/**
- * Detect the server-only-API stub throw: when a handler/component imports
- * getRequestContext()/cookies()/etc. from the BARE `@rangojs/router` specifier
- * (the out-of-react-server stub in index.ts) instead of the react-server build.
- * In an rsc test this happens when the vitest.rsc.config.ts `resolve.alias` does
- * not map the bare specifier to `index.rsc.ts` (the `rangoTestAliases` preset).
- * The dual-substring match keeps a legitimate handler throw from being
- * reclassified as a setup error.
- */
 function isServerOnlyStubError(error: unknown): boolean {
   return (
     error instanceof Error &&
@@ -175,20 +161,6 @@ function toRequest(
   return new Request(DEFAULT_URL, { headers });
 }
 
-/**
- * Build the result `response` from the request-context stub and, when present,
- * the Response the handler returned or threw (`source`). The stub cookies and
- * headers are merged in (Set-Cookie appended to preserve duplicates, other stub
- * headers filled in without clobbering the source), mirroring dispatch.ts's
- * rewrap.
- *
- * The source's BODY is carried over (not dropped): a response route returns a
- * `new Response(JSON.stringify(...))`, so callers reach for
- * `await result.response.text()`/`.json()`. Pre-fix this rewrapped to
- * `new Response(null, ...)` and the body was lost irrecoverably. A body is a
- * single-use stream; `source` is not read again here or by renderHandler, so
- * handing its body to the new Response is safe.
- */
 function buildResponse(reqCtx: RequestContext<any>, source: unknown): Response {
   const stub = reqCtx.res;
   if (source instanceof Response) {
@@ -231,9 +203,6 @@ export async function renderHandler<TEnv = any>(
   if (opts.clientComponents) registerClientComponents(opts.clientComponents);
   const request = toRequest(opts.request, opts.headers);
   const url = new URL(request.url);
-  // Seed a resolved name so a handler calling invalidateClientCache() rotates
-  // (emits the Set-Cookie) like production; opts.stateCookie customizes it. Also
-  // surfaced on the result so a consumer asserts the rotation without recomputing.
   const stateCookieName = resolveSeededStateCookieName(opts.stateCookie);
   const reqCtx = createRequestContext<TEnv>({
     env: (opts.env ?? {}) as TEnv,
@@ -264,17 +233,10 @@ export async function renderHandler<TEnv = any>(
       opts.routeMap ?? {},
       opts.routeName,
     );
-    // Seed ctx.use: a handle returns a push fn that RECORDS (so ctx.use(Meta)
-    // doesn't crash and pushes are assertable); a loader returns its seeded data
-    // (no real loader run).
     (hctx as { use: unknown }).use = (item: unknown) => {
       if (isHandle(item)) {
         const handle = item as Handle<any, any>;
         return (dataOrFn: unknown) => {
-          // Mirror production's push fn (loader-resolution.ts): a FUNCTION arg
-          // (ctx.use(Meta)(() => fetchMeta())) is CALLED and its result is
-          // recorded, not the function itself. An async callback records the
-          // promise it returns, same as production (which does not await it).
           const value =
             typeof dataOrFn === "function"
               ? (dataOrFn as () => unknown)()
@@ -294,8 +256,6 @@ export async function renderHandler<TEnv = any>(
 
     try {
       out = await handler(hctx as HandlerContext<any, TEnv>);
-      // Serialize the RSC in THIS context, so nested async server components see
-      // getRequestContext()/cookies()/vars while they render.
       if (out !== undefined && !(out instanceof Response)) {
         flight = await serializeNodeToFlight(
           out as ReactNode,
@@ -304,13 +264,7 @@ export async function renderHandler<TEnv = any>(
         );
       }
     } catch (error) {
-      // A harness misconfiguration (unseeded loader) is the consumer's mistake —
-      // surface it as a rejection, not as a captured handler throw.
       if (error instanceof RenderHandlerSetupError) throw error;
-      // Same for the server-only-API stub throw: the handler read
-      // getRequestContext()/cookies() but the bare `@rangojs/router` resolved to
-      // the throwing stub. Rethrow LOUDLY with the fix, instead of silently
-      // capturing it (which surfaces as an opaque tree:undefined + bare throw).
       if (isServerOnlyStubError(error)) {
         throw new RenderHandlerSetupError(
           `renderHandler: the handler called a server-only API (getRequestContext/cookies/...) ` +
@@ -320,8 +274,6 @@ export async function renderHandler<TEnv = any>(
             `Original: ${(error as Error).message}`,
         );
       }
-      // Otherwise captured, NOT re-thrown: a handler's success path is often
-      // `throw redirect(...)`; its cookies/flash must stay observable.
       didThrow = true;
       thrown = error;
     }
@@ -342,7 +294,6 @@ export async function renderHandler<TEnv = any>(
       }
     )._locationState ?? [],
   );
-  // Deserialize outside the context (the client deserializer needs no ctx).
   const tree =
     flight !== undefined ? await deserializeFlight(flight) : undefined;