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

package/src/testing/dispatch.ts

@@ -37,6 +37,10 @@
  *   (?_rsc_partial / ?_rsc_action): converted to a 204 + X-RSC-Redirect via the
  *   real interceptRedirectForPartial, so fetch() does not auto-follow the 3xx —
  *   identical to production's no-location-state path.
+ * - The open-redirect guard (rsc/redirect-guard.ts) on full (browser-followed)
+ *   redirects: a cross-origin Location is rewritten to the basename root unless
+ *   redirect(url, { external: true }) opted out, mirroring production's single
+ *   handler chokepoint. Soft partial/action redirects are 204 and pass through.
  *
  * What dispatch DOES NOT support (and why):
  * - RSC component routes — rendering requires the Flight serializer + React
@@ -91,6 +95,13 @@ import {
   interceptRedirectForPartial,
   mergeStubHeadersAndFinalize,
 } from "../rsc/helpers.js";
+import { guardOutgoingRedirect } from "../rsc/redirect-guard.js";
+import { stringifyJsonRouteResult } from "../rsc/json-route-result.js";
+import {
+  EXTERNAL_REDIRECT_MARKER,
+  isExternalRedirect,
+  markExternalRedirect,
+} from "../redirect-origin.js";
 import { isWebSocketUpgradeResponse } from "../response-utils.js";
 import type { Rango } from "../router/router-interfaces.js";
 
@@ -154,7 +165,8 @@ function toRequest(request: Request | string): Request {
 /**
  * Serialize a NON-Response response-route handler result, mirroring the
  * router's handleResponseRoute() contract:
- * - "json" serializes the value verbatim (bare) with application/json,
+ * - "json" serializes the value (bare) with application/json, rejecting a nested
+ *   unresolved Promise via the shared stringifyJsonRouteResult guard,
  * - text/html/xml/md stringify with the mapped MIME type.
  *
  * A handler-returned Response is NOT routed here — callHandler re-wraps it via
@@ -167,7 +179,12 @@ function serializeResponseRouteResult(
   responseType: string,
 ): Response {
   if (responseType === "json") {
-    return new Response(JSON.stringify(result), {
+    // Serialize through the SAME guard production uses: a nested unresolved
+    // Promise (forgotten await) throws RESPONSE_NOT_SERIALIZABLE here, caught by
+    // callHandler's catch and mapped to the identical typed 500 production
+    // returns -- so a dispatch json test fails exactly where production would,
+    // instead of silently emitting {} and passing.
+    return new Response(stringifyJsonRouteResult(result), {
       status: 200,
       headers: { "content-type": "application/json;charset=utf-8" },
     });
@@ -252,16 +269,27 @@ function rewrapHandlerResponse(result: Response): Response {
   }
   const headers = new Headers();
   result.headers.forEach((value, key) => {
+    // Mirror production: never copy the reserved external-redirect marker off a
+    // handler result (it is not a trust signal; the opt-in is the out-of-band
+    // brand transferred below).
+    if (key.toLowerCase() === EXTERNAL_REDIRECT_MARKER) return;
     if (key.toLowerCase() === "set-cookie") {
       headers.append(key, value);
     } else {
       headers.set(key, value);
     }
   });
-  return createResponseWithMergedHeaders(result.body, {
+  const rewrapped = createResponseWithMergedHeaders(result.body, {
     status: result.status,
     headers,
   });
+  // Mirror production's rewrapResponse: transfer the out-of-band external brand
+  // only from a genuinely branded result (a real redirect(url, { external:
+  // true })), never from a proxied upstream's forged header.
+  if (isExternalRedirect(result)) {
+    markExternalRedirect(rewrapped);
+  }
+  return rewrapped;
 }
 
 /**
@@ -506,7 +534,6 @@ export async function dispatch<TEnv = any>(
             regex: null,
             paramNames: [],
             handler: mw.handler,
-            mountPrefix: null,
           } as MiddlewareEntry<TEnv>,
           params: mw.params,
         }),
@@ -569,13 +596,23 @@ export async function dispatch<TEnv = any>(
     // callbacks via finalizeResponse. dispatch is RSC-free, so the
     // createRedirectFlightResponse stand-in falls back to the no-state
     // 204 + X-RSC-Redirect (see the location-state divergence in the header).
+    let finalResponse: Response;
     if (isPartial || isAction) {
       const intercepted = interceptRedirectForPartial(
         mwResponse,
         (redirectUrl) => createSimpleRedirectResponse(redirectUrl),
       );
-      return finalizeResponse(intercepted ?? mwResponse);
+      finalResponse = finalizeResponse(intercepted ?? mwResponse);
+    } else {
+      finalResponse = finalizeResponse(mwResponse);
     }
-    return finalizeResponse(mwResponse);
+
+    // Mirror production's single open-redirect chokepoint (handler.ts): every
+    // browser-followed (3xx + Location) redirect is same-origin guarded before
+    // it leaves -- a cross-origin Location is rewritten to the basename root
+    // unless redirect(url, { external: true }) opted out. Soft partial/action
+    // redirects are 204 + X-RSC-Redirect and pass through untouched (the client
+    // validates them), so this is a no-op for them.
+    return guardOutgoingRedirect(finalResponse, url.origin, router.basename);
   });
 }

package/src/testing/e2e/index.ts

@@ -32,6 +32,7 @@ import { createRangoMatchers, type RangoMatchers } from "./matchers.js";
 
 export {
   assertCacheStatus,
+  assertCacheDecision,
   parseCacheHeader,
   createCacheSink,
   filterCacheDecisions,

package/src/testing/flight.ts

@@ -70,6 +70,14 @@ export interface RenderToFlightStringOptions {
   params?: Record<string, string>;
   /** Matched route name (drives `ctx.routeName` and scoped reverse). */
   routeName?: string;
+  /**
+   * Route name -> pattern map enabling a SCOPED `ctx.reverse()` (like
+   * `renderHandler`). Without it, a server component that reverses resolves
+   * against the GLOBAL route map and is order-dependent on whatever router
+   * registered last. Pass the router-under-test's map to make reversing
+   * deterministic.
+   */
+  routeMap?: Record<string, string>;
   /**
    * Context variables visible to the rendered tree via `ctx.get(...)` — as a
    * prior middleware would have set them. Seeds the SAME way the handler-test
@@ -82,6 +90,44 @@ export interface RenderToFlightStringOptions {
 
 const DEFAULT_URL = "http://localhost/";
 
+/**
+ * True when `error` is the out-of-react-server stub thrown by index.ts's
+ * server-only exports (getRequestContext/cookies/headers/...) — i.e. the bare
+ * `@rangojs/router` specifier resolved to index.ts, not index.rsc.ts, because
+ * the rsc Vitest project is missing the `rangoTestAliases` alias. Matches both
+ * substrings of `serverOnlyStubError` (index.ts) so a normal app error cannot
+ * over-match. Shared with render-handler.ts so the two Flight primitives report
+ * the same misconfiguration identically.
+ */
+export function isServerOnlyStubError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    error.message.includes("is only available from") &&
+    error.message.includes("react-server")
+  );
+}
+
+/**
+ * Rethrow a server tree render error. When it is the missing-rsc-alias stub
+ * (above), rethrow an actionable message naming `rangoTestAliases` instead of
+ * the opaque stub text; otherwise rethrow the original unchanged. Classify the
+ * ORIGINAL error before constructing the wrapper so the wrapper's `Original: ...`
+ * echo (which re-embeds the matched substrings) never re-triggers the predicate.
+ */
+function rethrowFlightRenderError(error: unknown): never {
+  if (isServerOnlyStubError(error)) {
+    throw new Error(
+      `The server component called a server-only API ` +
+        `(getRequestContext/cookies/headers/...) but "@rangojs/router" resolved to ` +
+        `the out-of-react-server stub. Add rangoTestAliases({ preset }) to your ` +
+        `vitest.rsc.config.ts \`resolve.alias\` so the bare specifier maps to ` +
+        `index.rsc.ts (the real react-server implementations). ` +
+        `Original: ${(error as Error).message}`,
+    );
+  }
+  throw error;
+}
+
 export function assertNoLegacyUrlOption(opts: object, fnName: string): void {
   if ("url" in opts) {
     throw new Error(
@@ -148,7 +194,7 @@ export async function serializeToFlightString(
   });
 
   return runWithRequestContext(ctx, () => {
-    setRequestContextParams(opts.params ?? {}, opts.routeName);
+    setRequestContextParams(opts.params ?? {}, opts.routeName, opts.routeMap);
     return serializeNodeToFlight(element, clientManifest, url.pathname);
   });
 }
@@ -170,7 +216,7 @@ export async function serializeNodeToFlight(
     },
   });
   const text = await new Response(stream).text();
-  if (didError) throw renderError;
+  if (didError) rethrowFlightRenderError(renderError);
   return text;
 }
 

package/src/testing/index.ts

@@ -52,6 +52,7 @@ export type { DispatchOptions } from "./dispatch.js";
 
 export {
   assertCacheStatus,
+  assertCacheDecision,
   parseCacheHeader,
   createCacheSink,
   filterCacheDecisions,

package/src/testing/render-handler.ts

@@ -31,6 +31,7 @@ import {
 import { createHandlerContext } from "../router/handler-context.js";
 import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
 import { isHandle, type Handle } from "../handle.js";
+import { withDefer } from "../defer.js";
 import type { HandlerContext } from "../types/handler-context.js";
 import type { LoaderDefinition } from "../types.js";
 import {
@@ -41,7 +42,13 @@ import {
 } from "./internal/seed-vars.js";
 
 export type { StateCookieSeed } from "./internal/seed-vars.js";
-import { assertNoLegacyUrlOption, serializeNodeToFlight } from "./flight.js";
+import {
+  assertNoLegacyUrlOption,
+  serializeNodeToFlight,
+  isServerOnlyStubError,
+} from "./flight.js";
+import type { SegmentCacheStore } from "../cache/types.js";
+import type { CacheProfile } from "../cache/profile-registry.js";
 import {
   deserializeFlight,
   makeClientManifest,
@@ -94,6 +101,19 @@ export interface RenderHandlerOptions<TEnv = any> {
    * `result.stateCookieName`.
    */
   stateCookie?: StateCookieSeed;
+  /**
+   * Segment cache store backing a `"use cache"` function the handler invokes
+   * (e.g. `new MemorySegmentCacheStore()`). Without it, `registerCachedFunction`
+   * takes the uncached bypass and the cached path is NOT exercised (the runtime
+   * emits a one-time warning under the test runner). Pair with `cacheProfiles`
+   * so the profile the directive names resolves.
+   */
+  cacheStore?: SegmentCacheStore;
+  /**
+   * Cache profiles in the `createRouter({ cacheProfiles })` shape, required for
+   * `"use cache: profileName"` resolution once a `cacheStore` is wired.
+   */
+  cacheProfiles?: Record<string, CacheProfile>;
 }
 
 /** Result of {@link renderHandler}. */
@@ -142,14 +162,6 @@ function headersToObject(headers: Headers): Record<string, string> {
   return out;
 }
 
-function isServerOnlyStubError(error: unknown): boolean {
-  return (
-    error instanceof Error &&
-    error.message.includes("is only available from") &&
-    error.message.includes("react-server")
-  );
-}
-
 function toRequest(
   request: Request | string | undefined,
   headers?: HeadersInit,
@@ -211,6 +223,8 @@ export async function renderHandler<TEnv = any>(
     variables: seedVariables({}, opts.vars),
     stateCookieName,
     version: opts.stateCookie?.version,
+    cacheStore: opts.cacheStore,
+    cacheProfiles: opts.cacheProfiles,
   });
 
   const loaderSeeds = new Map<unknown, unknown>(opts.loaders ?? []);
@@ -222,7 +236,11 @@ export async function renderHandler<TEnv = any>(
   let didThrow = false;
 
   await runWithRequestContext(reqCtx as RequestContext<TEnv>, async () => {
-    setRequestContextParams(opts.params ?? {}, opts.routeName);
+    // Scope the request-context reverse to opts.routeMap too (not just the
+    // handler context built below), so a nested server component reading
+    // getRequestContext().reverse() resolves against the same map as the
+    // handler's ctx.reverse -- matching renderToFlightString/renderServerTree.
+    setRequestContextParams(opts.params ?? {}, opts.routeName, opts.routeMap);
     const hctx = createHandlerContext<TEnv>(
       opts.params ?? {},
       reqCtx.request,
@@ -236,7 +254,8 @@ export async function renderHandler<TEnv = any>(
     (hctx as { use: unknown }).use = (item: unknown) => {
       if (isHandle(item)) {
         const handle = item as Handle<any, any>;
-        return (dataOrFn: unknown) => {
+        // withDefer attaches .defer() so the harness mirrors production's push.
+        return withDefer((dataOrFn: unknown) => {
           const value =
             typeof dataOrFn === "function"
               ? (dataOrFn as () => unknown)()
@@ -244,7 +263,7 @@ export async function renderHandler<TEnv = any>(
           const pushed = handlePushes.get(handle) ?? [];
           pushed.push(value);
           handlePushes.set(handle, pushed);
-        };
+        });
       }
       if (loaderSeeds.has(item)) return loaderSeeds.get(item);
       throw new RenderHandlerSetupError(

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";
 
@@ -160,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>;
   /**
@@ -224,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" });
@@ -404,6 +416,32 @@ export async function renderRoute(
 
   const historyKey = generateHistoryKey(url.href);
   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,
@@ -434,7 +472,23 @@ export async function renderRoute(
     initialSegments.map((s) => s.id),
   );
 
+  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);
@@ -465,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,

package/src/types/handler-context.ts

@@ -1,5 +1,6 @@
 import type { ReactNode } from "react";
 import type { Handle } from "../handle.js";
+import type { HandlePush } from "../defer.js";
 import type { ContextVar } from "../context-var.js";
 import type { MiddlewareFn } from "../router/middleware.js";
 import type { Theme } from "../theme/types.js";
@@ -274,6 +275,8 @@ export type HandlerContext<
    * For handles: Returns a push function to add data for this segment.
    * Handle data accumulates across all matched route segments.
    * Push accepts: direct value, Promise, or async callback (executed immediately).
+   * Or call `.defer()` to reserve the slot now and resolve it later (e.g. from a
+   * deep async component), with a timeout safety net — see {@link HandlePush}.
    *
    * @example
    * ```typescript
@@ -307,6 +310,13 @@ export type HandlerContext<
    *   });
    *   return <ProductPage />;
    * });
+   *
+   * // Handle usage - deferred (reserve the slot now, resolve from a deep component)
+   * route("product", (ctx) => {
+   *   const resolve = ctx.use(Breadcrumbs).defer({ timeoutMs: 5000, else: null });
+   *   loadCrumb(ctx.params.id).then(resolve); // resolver is push-equal
+   *   return <ProductPage />;                 // auto-resolves to `else` on timeout
+   * });
    * ```
    */
   use: {
@@ -315,7 +325,7 @@ export type HandlerContext<
     ): Promise<T>;
     <TData, TAccumulated = TData[]>(
       handle: Handle<TData, TAccumulated>,
-    ): (data: TData | Promise<TData> | (() => Promise<TData>)) => void;
+    ): HandlePush<TData>;
   };
   /**
    * Current theme (from cookie or default).
@@ -422,6 +432,18 @@ export type InternalHandlerContext<
   _responseType?: string;
   /** Route name for cache key scoping (prevents cross-route collisions). */
   _routeName?: string;
+  /**
+   * @internal Loader-cache override table: loaderId -> memoized data promise.
+   * A single stable ctx.use interceptor consults this instead of chaining one
+   * wrapper per cached loader (avoids O(N) dispatch). See loader-cache.ts.
+   */
+  _loaderCacheOverrides?: Map<string, Promise<any>>;
+  /**
+   * @internal ctx.use captured before the loader-cache interceptor was installed.
+   * The cache-miss execute runs the loader through this, bypassing the override
+   * table (so a loader cannot await its own in-flight memoized promise).
+   */
+  _loaderCacheOriginalUse?: (item: any) => any;
 };
 
 /**
@@ -613,6 +635,10 @@ export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
    * namespace import (`import * as CartActions`), any export of that module —
    * and `false` otherwise (including plain navigation with no action).
    *
+   * Called with NO arguments it answers "is this request an action at all?":
+   * `true` for any action, `false` on plain navigation. Use the bare form when
+   * you want to revalidate on every action regardless of which one fired.
+   *
    * Prefer this over hand-written `actionId` substring matches: it resolves the
    * action's stable `path#export` id from the imported reference, so a rename is
    * a type error in one place instead of silent drift across consumers. It
@@ -627,6 +653,7 @@ export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
    * import { addToCart, removeFromCart } from "./actions/cart";
    * import * as CartActions from "./actions/cart";
    *
+   * revalidate((ctx) => ctx.isAction() || undefined); // any action
    * revalidate((ctx) => ctx.isAction(addToCart) || undefined); // one action
    * revalidate((ctx) => ctx.isAction(addToCart, removeFromCart) || undefined); // several
    * revalidate((ctx) => ctx.isAction(CartActions) || undefined); // any in the module

package/src/vite/discovery/discover-routers.ts

@@ -11,6 +11,16 @@ import {
   formatNestedRouterConflictError,
   findNestedRouterConflict,
 } from "../../build/generate-route-types.js";
+// Pure data transforms over generateManifestFull's output. Imported directly
+// from source (not the public ./build barrel, and not the runner) because they
+// are realm-independent: buildRouteTrie/buildPerRouterTrie operate on plain
+// manifest data, and collectFallbackClientRefs keys on the global-registry
+// Symbol.for("react.client.reference"), so it detects client references in a
+// boundary tree regardless of which realm imported the walker. Only
+// generateManifestFull must stay on the runner (it invokes user handlers via
+// RangoContext from the runner realm) — see the runner.import below.
+import { buildRouteTrie, buildPerRouterTrie } from "../../build/route-trie.js";
+import { collectFallbackClientRefs } from "../../build/collect-fallback-refs.js";
 import {
   flattenLeafEntries,
   buildRouteToStaticPrefix,
@@ -107,7 +117,10 @@ export async function discoverRouters(
     }
   }
 
-  // Import build utilities for manifest generation
+  // generateManifestFull must run in the RSC runner realm: it invokes the
+  // user's urlpatterns.handler() via RangoContext, consuming router instances
+  // from the runner. The trie/fallback-ref builders are pure transforms over
+  // its output and are imported directly from source above.
   const buildMod = await timed(
     debug,
     "inner: import @rangojs/router/build",
@@ -158,11 +171,12 @@ export async function discoverRouters(
   // are NOT in EntryData, so generateManifestFull's walk misses them. Collect any
   // "use client" default boundary directly off the router instance. The value is
   // commonly a handler function wrapping the client boundary in server providers,
-  // so collectFallbackClientRefs invokes + walks the tree. Routed through buildMod
-  // so it runs in the same RSC runner realm the boundary value came from.
+  // so collectFallbackClientRefs invokes + walks the tree. The walker keys on the
+  // global-registry Symbol.for("react.client.reference"), so it detects client
+  // references in a runner-realm boundary tree even when imported here directly.
   const collectFromBoundaryNode = (node: unknown): void => {
-    if (collectClientFallbackRef && buildMod.collectFallbackClientRefs) {
-      buildMod.collectFallbackClientRefs(node, collectClientFallbackRef);
+    if (collectClientFallbackRef) {
+      collectFallbackClientRefs(node, collectClientFallbackRef);
     }
   };
 
@@ -293,8 +307,7 @@ export async function discoverRouters(
   let newMergedRouteTrie: any = null;
   const trieStart = debug ? performance.now() : 0;
   if (Object.keys(newMergedRouteManifest).length > 0) {
-    const buildRouteTrie = buildMod.buildRouteTrie;
-    if (buildRouteTrie && mergedRouteAncestry) {
+    if (mergedRouteAncestry) {
       // Build routeToStaticPrefix from saved manifests
       const routeToStaticPrefix: Record<string, string> = {};
       for (const { manifest } of allManifests) {
@@ -342,11 +355,9 @@ export async function discoverRouters(
       // Build per-router tries for multi-router isolation. Uses the single
       // shared buildPerRouterTrie so the production serialized trie is built by
       // exactly the same code as the dev/HMR runtime rebuild (manifest-init.ts).
-      const buildPerRouterTrie = buildMod.buildPerRouterTrie;
+      // Returns null for route-less manifests (route-trie.ts).
       for (const { id, manifest } of allManifests) {
-        const perRouterTrie = buildPerRouterTrie
-          ? buildPerRouterTrie(manifest)
-          : null;
+        const perRouterTrie = buildPerRouterTrie(manifest);
         if (perRouterTrie) {
           newPerRouterTrieMap.set(id, perRouterTrie);
         }