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

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

package/src/vite/discovery/prerender-collection.ts

@@ -6,7 +6,7 @@
  * generation.
  */
 
-import { contextSet } from "../../context-var.js";
+import { contextSet, hasContextVars } from "../../context-var.js";
 import {
   encodePathParam,
   substituteRouteParams,
@@ -135,9 +135,7 @@ export async function expandPrerenderRoutes(
                 (performance.now() - getParamsStart).toFixed(1),
               );
               const concurrency = def.options?.concurrency ?? 1;
-              const hasBuildVars =
-                Object.keys(buildVars).length > 0 ||
-                Object.getOwnPropertySymbols(buildVars).length > 0;
+              const hasBuildVars = hasContextVars(buildVars);
               for (const params of paramsList) {
                 let url = substituteRouteParams(
                   pattern,

package/src/vite/discovery/state.ts

@@ -20,6 +20,11 @@ export interface PluginOptions {
   buildEnv?: import("../plugin-types.js").BuildEnvOption;
   /** Deployment preset (needed for buildEnv "auto" resolution). */
   preset?: "node" | "cloudflare";
+  /**
+   * Route-discovery scan filter (glob include/exclude) from rango() config.
+   * Compiled into `DiscoveryState.scanFilter` once `projectRoot` is known.
+   */
+  discovery?: { include?: string[]; exclude?: string[] };
   /**
    * Shared context the built-in clientChunks strategy reads. Discovery populates
    * it (registered fallback hashes + single-router name) before the client build

package/src/vite/plugin-types.ts

@@ -127,16 +127,18 @@ interface RangoBaseOptions {
   clientChunks?: ClientChunks;
 
   /**
-   * Environment bindings available to Prerender and Static handlers at build
-   * time via `ctx.env`. Applies to both production build and dev on-demand
-   * prerender (`/__rsc_prerender`).
-   *
-   * This is the build-time env supplied by the Vite plugin, not the live
-   * request env. It is shared across all prerender invocations for the build.
+   * Filter which files route discovery scans, by glob. Paths are matched
+   * root-relative (e.g. `src/routes/**`). `include` restricts discovery to
+   * matching files; `exclude` removes matches (the defaults cover tests, dist,
+   * coverage, etc.). Mirrors the CLI's `--include`/`--exclude`.
    *
-   * @default false
+   * @example
+   * rango({ discovery: { include: ["src/routes/**"] } })
    */
-  buildEnv?: BuildEnvOption;
+  discovery?: {
+    include?: string[];
+    exclude?: string[];
+  };
 }
 
 /**
@@ -147,6 +149,17 @@ export interface RangoNodeOptions extends RangoBaseOptions {
    * Deployment preset. Defaults to 'node' when not specified.
    */
   preset?: "node";
+
+  /**
+   * Environment bindings available to Prerender and Static handlers at build
+   * time via `ctx.env`. Shared across all prerender invocations for the build.
+   *
+   * `"auto"` is Cloudflare-only (it resolves the wrangler platform proxy), so it
+   * is not accepted on the Node preset — pass an object or a factory instead.
+   *
+   * @default false
+   */
+  buildEnv?: Exclude<BuildEnvOption, "auto">;
 }
 
 /**
@@ -164,6 +177,17 @@ export interface RangoCloudflareOptions extends RangoBaseOptions {
    * - Build-time manifest generation is auto-detected from the resolved RSC environment config
    */
   preset: "cloudflare";
+
+  /**
+   * Environment bindings available to Prerender and Static handlers at build
+   * time via `ctx.env`. Shared across all prerender invocations for the build.
+   *
+   * `"auto"` resolves the Cloudflare platform proxy via wrangler
+   * `getPlatformProxy()`.
+   *
+   * @default false
+   */
+  buildEnv?: BuildEnvOption;
 }
 
 /**

package/src/vite/plugins/refresh-cmd.ts

@@ -20,7 +20,7 @@ import type { Plugin } from "vite";
  */
 export function poke(): Plugin {
   return {
-    name: "vite-plugin-poke",
+    name: "@rangojs/router:poke",
     apply: "serve",
 
     configureServer(server) {

package/src/vite/plugins/use-cache-transform.ts

@@ -132,7 +132,7 @@ function transformFileLevelUseCache(
   isLayoutOrTemplate: boolean,
   transformWrapExport: (typeof import("@vitejs/plugin-rsc/transforms"))["transformWrapExport"],
 ) {
-  const nonFunctionExports: string[] = [];
+  const unconfirmedExports: string[] = [];
 
   const { exportNames, output } = transformWrapExport(code, ast, {
     runtime: (value: string, name: string) => {
@@ -142,22 +142,33 @@ function transformFileLevelUseCache(
     rejectNonAsyncFunction: false,
     filter: (name: string, meta: { isFunction?: boolean }) => {
       if (name === "default" && isLayoutOrTemplate) return false;
-      if (meta.isFunction === false) {
-        nonFunctionExports.push(name);
+      // isFunction is boolean | undefined: true = confirmed function, false =
+      // confirmed non-function, undefined = cannot tell statically (e.g. a
+      // factory/HOF initializer `const x = makeCached(fn)`). Deliberate policy:
+      // require a confirmed function and reject everything else, including
+      // indeterminate initializers that may be functions at runtime -- rewrite
+      // those as direct async functions. (Pre-#1246 plugin-rsc reported false,
+      // not undefined, here, so === false would wrongly wrap them post-bump.)
+      if (meta.isFunction !== true) {
+        unconfirmedExports.push(name);
         return false;
       }
       return true;
     },
   });
 
-  if (nonFunctionExports.length > 0) {
+  if (unconfirmedExports.length > 0) {
+    const plural = unconfirmedExports.length > 1;
     throw new Error(
-      `[rango:use-cache] File-level "use cache" in ${sourceId} cannot wrap ` +
-        `non-function export${nonFunctionExports.length > 1 ? "s" : ""}: ` +
-        `${nonFunctionExports.map((n) => `"${n}"`).join(", ")}. ` +
-        `Only function exports can be cached. Either remove "use cache" from ` +
-        `the file level and add it inside individual functions, or move the ` +
-        `non-function exports to a separate module.`,
+      `[rango:use-cache] File-level "use cache" in ${sourceId} only wraps ` +
+        `exports that are statically-confirmed functions. ` +
+        `${plural ? "These exports are" : "This export is"} not: ` +
+        `${unconfirmedExports.map((n) => `"${n}"`).join(", ")}. ` +
+        `Declare them directly (export async function foo() {} or ` +
+        `export const foo = async () => {}). A factory or otherwise ` +
+        `statically-indeterminate initializer (export const foo = makeCached(fn)) ` +
+        `is rejected even if it returns a function at runtime -- rewrite it as a ` +
+        `direct async function, or move non-function exports to a separate module.`,
     );
   }
 

package/src/vite/rango.ts

@@ -428,6 +428,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
       enableBuildPrerender: prerenderEnabled,
       buildEnv: options?.buildEnv,
       preset,
+      discovery: options?.discovery,
       clientChunkCtx,
     }),
   );

package/src/vite/router-discovery.ts

@@ -16,6 +16,7 @@ import {
   formatNestedRouterConflictError,
   findNestedRouterConflict,
   findRouterFiles,
+  createScanFilter,
 } from "../build/generate-route-types.js";
 import { firstCodeMatchIndex } from "../build/route-types/source-scan.js";
 import { createVersionPlugin } from "./plugins/version-plugin.js";
@@ -326,6 +327,12 @@ export function createRouterDiscoveryPlugin(
 
     configResolved(config) {
       s.projectRoot = config.root;
+      // Compile the optional discovery scan filter (glob include/exclude) now
+      // that the project root is known. findRouterFiles() below — and the
+      // build/HMR rediscovery paths — honor s.scanFilter.
+      s.scanFilter = opts?.discovery
+        ? createScanFilter(s.projectRoot, opts.discovery)
+        : undefined;
       s.isBuildMode = config.command === "build";
       viteCommand = config.command as "serve" | "build";
       viteMode = config.mode;