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

package/src/use-loader.tsx

@@ -15,14 +15,6 @@ import { OutletContext, type OutletContextValue } from "./outlet-context.js";
 import { loaderStore, type LoaderEntry } from "./loader-store.js";
 import type { LoaderDefinition, LoadOptions } from "./types.js";
 
-/**
- * A shareable GET — a `load()` call that reads data (GET or defaulted method)
- * with no request body. Params are allowed. This is the gate for keyed sharing:
- * when a hook is given an explicit `key`, every shareable GET writes to the
- * keyed bucket so co-keyed readers (including parameterized views) refresh
- * together. Non-GET methods and body-bearing calls are mutations and stay local
- * to the call site.
- */
 function isShareableGet(options: LoadOptions | undefined): boolean {
   if (!options) return true;
   if (options.method && options.method !== "GET") return false;
@@ -32,44 +24,14 @@ function isShareableGet(options: LoadOptions | undefined): boolean {
   return true;
 }
 
-/**
- * Plain route-context refetch — a `load()` call with no options or a
- * trivially-defaulted GET (no params, no body). Results from these are
- * broadcast to every component reading the same loader id via the shared
- * store, so a layout's refetch button updates page + parallel-slot reads
- * automatically.
- *
- * Calls with explicit `params`, an explicit non-GET method, or a `body`
- * stay local to the call site — that preserves the today-semantics of
- * `useFetchLoader(SearchLoader).load({ params: { q } })` style code where
- * each component owns its own fetched view. (An explicit `key` opts a
- * parameterized GET back into sharing; see `isShareableGet`.)
- */
 function isPlainRefetch(options: LoadOptions | undefined): boolean {
   if (!isShareableGet(options)) return false;
   if (options?.params && Object.keys(options.params).length > 0) return false;
   return true;
 }
 
-// Per-hook unique suffix for grouped reads that have no explicit `key`. Such a
-// read must NOT share the bare `loader.$$id` bucket, or a cross-loader group
-// refresh would leak into unrelated unkeyed readers of the same loader (which
-// the contract keeps local). Sharing within a group is opt-in via an explicit
-// `key`; without one, each grouped read gets its own private bucket. The value
-// is only ever used as a client-side store bucket key (never rendered), so the
-// counter has no SSR/hydration consistency requirement.
 let privateGroupBucketSeq = 0;
 
-/**
- * Extract a specific loader's data from a content ReactNode.
- *
- * When a route registers loaders via loader(), the resolved data lives in
- * the route's OutletProvider (rendered as <Outlet /> content). Parallel
- * slots are siblings of <Outlet />, so they can't find it by walking
- * the parent context chain. This helper traverses wrapper elements
- * (MountContextProvider, ViewTransition, etc.) to reach the OutletProvider
- * and extract the loader data directly.
- */
 const NOT_FOUND = Symbol("not-found");
 
 function extractContentLoaderData(
@@ -85,10 +47,6 @@ function extractContentLoaderData(
     return props.loaderData[loaderId];
   }
 
-  // LoaderBoundary: loaderIds + loaderDataPromise (already resolved array).
-  // When the segment has loading(), loaderData is resolved inside
-  // LoaderBoundary via use(). If the promise was pre-awaited (forceAwait
-  // or isAction), the prop is a raw array we can index into.
   if (
     props.loaderIds &&
     Array.isArray(props.loaderIds) &&
@@ -98,7 +56,6 @@ function extractContentLoaderData(
     const idx = (props.loaderIds as string[]).indexOf(loaderId);
     if (idx !== -1) {
       const data = (props.loaderDataPromise as any[])[idx];
-      // loaderDataPromise entries may be { ok, data } result objects
       if (data && typeof data === "object" && "ok" in data) {
         return data.ok ? data.data : NOT_FOUND;
       }
@@ -106,118 +63,45 @@ function extractContentLoaderData(
     }
   }
 
-  // Traverse into wrapper elements (MountContextProvider, ViewTransition,
-  // Suspense wrappers, etc.)
   if (props.children) return extractContentLoaderData(props.children, loaderId);
   return NOT_FOUND;
 }
 
-/**
- * Payload returned by loader RSC requests
- */
 interface LoaderRscPayload<T = unknown> {
   loaderResult: T;
   loaderError?: { message: string; name: string };
 }
 
-/**
- * Load function type for fetching loader data from the client
- */
 export type LoadFunction<T> = (options?: LoadOptions) => Promise<T>;
 
-/**
- * Result type for useLoader hook (strict - data is required)
- */
 export interface UseLoaderResult<T> {
-  /** The loaded data - guaranteed to exist when loader is registered on route */
   data: T;
-  /** True while a load() is in progress */
   isLoading: boolean;
-  /** Error from the most recent load attempt, null if successful */
   error: Error | null;
-  /** Function to trigger a fetch (only works if loader is fetchable) */
   load: LoadFunction<T>;
-  /** Alias for load */
   refetch: LoadFunction<T>;
 }
 
-/**
- * Result type for useFetchLoader hook (flexible - data is optional)
- */
 export interface UseFetchLoaderResult<T> {
-  /** The loaded data - may be undefined if not yet fetched or not in context */
   data: T | undefined;
-  /** True while a load() is in progress */
   isLoading: boolean;
-  /** Error from the most recent load attempt, null if successful */
   error: Error | null;
-  /** Function to trigger a fetch (only works if loader is fetchable) */
   load: LoadFunction<T>;
-  /** Alias for load */
   refetch: LoadFunction<T>;
 }
 
-/**
- * Options for useLoader hook
- */
 export interface UseLoaderOptions {
-  /**
-   * If true (default), errors from load() will be thrown to the nearest error boundary.
-   * If false, errors are only captured in the `error` state.
-   * @default true
-   */
   throwOnError?: boolean;
-  /**
-   * Client refresh key. Partitions the shared refresh store so that only hooks
-   * using the same `key` refresh together when one of them calls `load()`.
-   *
-   * Without a `key` (default), a plain `load()` on a route-registered loader
-   * broadcasts to every reader of that loader, and any parameterized / unregistered
-   * load stays local to the calling hook. With a `key`:
-   *   - readers of the same loader that share a `key` form one refresh group —
-   *     a `load()` from any of them updates the whole group, including
-   *     parameterized GETs;
-   *   - readers with different keys are independent;
-   *   - it works even when the loader is NOT registered on the route (keyed
-   *     `useFetchLoader`), letting unrelated components opt into sharing.
-   *
-   * This is a client-side refresh identity only. It is unrelated to the server
-   * `cache({ key })` option and to `revalidate()`; it never changes the request
-   * sent to the server.
-   */
   key?: string;
-  /**
-   * Cross-loader refresh group tag(s). Tag reads of DIFFERENT loaders with a
-   * shared name, then call `useRefreshLoaders()(name)` to refresh the whole group
-   * at once. Pass an array to tag one read into several groups — it is refreshed
-   * when ANY of its groups is refreshed, so a coarse tag can cover the whole set
-   * while a finer tag targets a subset. Each member is refreshed with a plain GET
-   * against the current route URL — no params, no body, no mutation methods —
-   * because a group spans heterogeneous loaders with different param/return
-   * shapes.
-   *
-   * For parameterized sharing of a SINGLE loader, use `key` instead; group
-   * members should be registered or non-parameterized-keyed reads (a plain-GET
-   * group refresh would drop any per-call params).
-   */
   refreshGroup?: string | string[];
 }
 
-/**
- * Internal hook implementation shared by useLoader and useFetchLoader
- */
 function useLoaderInternal<T>(
   loader: LoaderDefinition<T>,
   options?: UseLoaderOptions,
 ): UseFetchLoaderResult<T> {
   const context = useContext(OutletContext);
 
-  // Get data from context (SSR/navigation). `hasContextData` distinguishes
-  // "loader registered on the route, value happens to be undefined" from
-  // "loader is not in any parent's context at all". The shared store is
-  // only consulted when the loader really is in route context — that
-  // preserves per-component isolation for ad-hoc useFetchLoader callers
-  // who use the same fetchable loader without registering it.
   const { contextData, hasContextData } = useMemo((): {
     contextData: T | undefined;
     hasContextData: boolean;
@@ -230,9 +114,6 @@ function useLoaderInternal<T>(
           hasContextData: true,
         };
       }
-      // Check content element — the route's OutletProvider is rendered as
-      // <Outlet /> content (a child), so its loaderData isn't in the parent
-      // chain. Parallel slots need to reach into it to find route-level loaders.
       const contentData = extractContentLoaderData(
         current.content,
         loader.$$id,
@@ -245,23 +126,8 @@ function useLoaderInternal<T>(
     return { contextData: undefined, hasContextData: false };
   }, [context, loader.$$id]);
 
-  // Shared subscription: every component reading the same loader id sees
-  // the same snapshot, so a plain refetch from one component propagates to
-  // the others. Mirrors the convention used by useParams / useLinkStatus —
-  // useState seeded from the store, useEffect subscribes for updates and
-  // calls setState inside startTransition so subscriber re-renders don't
-  // trip Suspense fallbacks during a refetch (matches the per-hook
-  // startTransition the old code wrapped setFetchedData in).
   const loaderId = loader.$$id;
-  // Client refresh key. The shared store is partitioned by bucket key so that
-  // only hooks with the same `key` refresh together. Default (no key) keeps the
-  // historical behavior: one bucket per loader id.
   const key = options?.key;
-  // Normalize the refresh-group tag(s) to a stable, deduped, sorted list. The
-  // joined `groupKey` string is the subscribe effect's dependency, so passing an
-  // inline array literal (`refreshGroup={["a", "b"]}`) does not force a
-  // resubscribe on every render. An empty list means "no groups" — identical to
-  // omitting the option (`hasGroups` stays false, no private bucket is created).
   const refreshGroupOption = options?.refreshGroup;
   const groupKey =
     refreshGroupOption === undefined
@@ -276,10 +142,6 @@ function useLoaderInternal<T>(
     [groupKey],
   );
   const hasGroups = groupList.length > 0;
-  // A grouped reader with no explicit key gets a private per-hook bucket so a
-  // cross-loader group refresh cannot leak into the bare `loader.$$id` bucket
-  // shared by unrelated unkeyed readers. Sharing within a group is opt-in via
-  // an explicit `key`.
   const privateBucketIdRef = useRef<string | null>(null);
   if (hasGroups && key === undefined && privateBucketIdRef.current === null) {
     privateBucketIdRef.current = `__rg${privateGroupBucketSeq++}`;
@@ -289,12 +151,6 @@ function useLoaderInternal<T>(
   const bucketKey =
     effectiveKey === undefined ? loaderId : `${loaderId}::${effectiveKey}`;
 
-  // Plain-GET refresh thunk registered with the store for cross-loader group
-  // refresh (useRefreshLoaders). Always shares into this hook's bucket, never
-  // touches lastSharedRequestIdRef (so a group refresh never render-throws —
-  // errors surface via `error` and reject the refreshGroups() promise instead),
-  // and sends no params/body. Stable across navigations (depends only on
-  // loaderId + bucketKey), so the store keeps one current thunk per bucket.
   const groupRefetch = useCallback(async (): Promise<void> => {
     if (!loaderId) return;
     const requestId = loaderStore.reserveRequestId(bucketKey);
@@ -333,9 +189,6 @@ function useLoaderInternal<T>(
       ? sharedState.snapshot
       : loaderStore.getSnapshot(bucketKey);
   useEffect(() => {
-    // Sync any value the store committed between this hook's lazy
-    // initializer and effect-time (e.g. a sibling that mounted earlier
-    // already triggered a load()).
     const initial = loaderStore.getSnapshot(bucketKey);
     if (initial !== sharedSnapshot) {
       startTransition(() => {
@@ -430,10 +283,6 @@ function useLoaderInternal<T>(
 
   const throwOnError = options?.throwOnError ?? true;
 
-  // Refs for values used inside load() that should NOT cause callback identity
-  // churn. loader.$$id can change if a reusable component receives a different
-  // loader without remounting; data changes on every navigation. Refs keep the
-  // callback stable while always reading the latest values.
   const loaderIdRef = useRef(loaderId);
   loaderIdRef.current = loaderId;
   const bucketKeyRef = useRef(bucketKey);
@@ -443,8 +292,6 @@ function useLoaderInternal<T>(
   const hasContextDataRef = useRef(hasContextData);
   hasContextDataRef.current = hasContextData;
 
-  // Load function for fetching data via the ?_rsc_loader endpoint.
-  // Supports GET (data fetching) and POST/PUT/PATCH/DELETE (mutations).
   const load = useCallback(
     async (loadOptions?: LoadOptions): Promise<T> => {
       const id = loaderIdRef.current;
@@ -455,20 +302,8 @@ function useLoaderInternal<T>(
       }
 
       const bucket = bucketKeyRef.current;
-      // A dedicated bucket means this read owns a bucket distinct from the bare
-      // loader id — either an explicit `key` (`$$id::key`) or a refreshGroup's
-      // private bucket (`$$id::<private>`).
       const hasDedicatedBucket = bucket !== id;
 
-      // Deciding shared vs local:
-      //   - With a dedicated bucket, every shareable GET (params allowed) writes
-      //     to that bucket — the key/group is an explicit opt-in to sharing, and
-      //     a direct load() must land in the same bucket a group refresh uses.
-      //   - On the bare loader-id bucket, sharing is only correct when the
-      //     loader is registered on the route and the call is a plain refetch —
-      //     otherwise two unrelated components calling load() on the same
-      //     fetchable loader would overwrite each other's local view.
-      // Mutations (non-GET / body) stay local in both cases.
       const shared = hasDedicatedBucket
         ? isShareableGet(loadOptions)
         : isPlainRefetch(loadOptions) && hasContextDataRef.current;
@@ -477,9 +312,6 @@ function useLoaderInternal<T>(
       if (shared) {
         sharedRequestId = loaderStore.reserveRequestId(bucket);
         lastSharedRequestIdRef.current = sharedRequestId;
-        // beginRequest flips loading on AND clears any prior error so a
-        // throwOnError: false consumer doesn't keep showing the stale
-        // error during the retry. Gated on requestId === latest.
         loaderStore.beginRequest(bucket, sharedRequestId);
       } else {
         localRequestId = ++localRequestIdRef.current;
@@ -505,8 +337,6 @@ function useLoaderInternal<T>(
             loadOptions?.params && Object.keys(loadOptions.params).length > 0;
 
           if (bodyValue instanceof FormData) {
-            // FormData body — send as multipart/form-data (preserves File objects).
-            // Params are appended as a JSON string in a special field.
             if (hasParams) {
               bodyValue.set(
                 "_rsc_loader_params",
@@ -519,7 +349,6 @@ function useLoaderInternal<T>(
               body: bodyValue,
             };
           } else {
-            // JSON body — send params and body as JSON
             const bodyPayload: {
               params?: Record<string, string>;
               body?: unknown;
@@ -541,7 +370,6 @@ function useLoaderInternal<T>(
             };
           }
         } else {
-          // GET - send params in query string
           if (
             loadOptions?.params &&
             Object.keys(loadOptions.params).length > 0
@@ -571,12 +399,8 @@ function useLoaderInternal<T>(
 
         const result = payload.loaderResult;
         if (shared) {
-          // finishData is gated on requestId; a stale response is dropped.
           loaderStore.finishData(bucket, sharedRequestId, result);
         } else if (localRequestId === localRequestIdRef.current) {
-          // Local-branch gate, mirrors the shared-branch requestId check:
-          // if a newer load() was issued from this hook before this one
-          // resolved, drop the stale result.
           startTransition(() => {
             setLocalFetchedData({ has: true, value: result });
             setLocalIsLoading(false);
@@ -594,12 +418,9 @@ function useLoaderInternal<T>(
         if (throwOnError) {
           throw err;
         }
-        // When throwOnError is false, return the latest data snapshot (previous
-        // successful value or undefined). Caller should check error state.
         return dataRef.current as T;
       } finally {
         if (shared) {
-          // setLoading is gated; only the latest request flips the flag off.
           loaderStore.setLoading(bucket, sharedRequestId, false);
         }
       }
@@ -607,13 +428,6 @@ function useLoaderInternal<T>(
     [throwOnError],
   );
 
-  // Throw during render if there's an error and throwOnError is true.
-  // - Local errors always belong to this hook, so always throw on opt-in.
-  // - Shared errors throw only when this hook initiated the failing
-  //   request (entry.requestId matches lastSharedRequestIdRef). Sibling
-  //   readers expose the error via `error` but do not throw, so a
-  //   throwOnError: true reader never explodes because of someone else's
-  //   throwOnError: false load() failure.
   if (throwOnError) {
     if (localError) throw localError;
     if (

package/src/vite/discovery/bundle-postprocess.ts

@@ -9,6 +9,7 @@ import { resolve } from "node:path";
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { evictHandlerCode } from "../utils/bundle-analysis.js";
 import { copyStagedBuildAssets } from "../utils/prerender-utils.js";
+import { jsonParseExpression } from "../utils/manifest-utils.js";
 import type { DiscoveryState } from "./state.js";
 
 /**
@@ -104,7 +105,7 @@ export function postprocessBundle(state: DiscoveryState): void {
         }
 
         const manifestCode = [
-          `const m=JSON.parse('${JSON.stringify(manifestMap).replace(/'/g, "\\'")}');`,
+          `const m=${jsonParseExpression(manifestMap)};`,
           `export function loadPrerenderAsset(s){return import(s)}`,
           `export default m;`,
           "",

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);
     }
   };
 
@@ -243,20 +257,19 @@ export async function discoverRouters(
     // Flatten prefix tree leaf nodes into precomputed entries.
     // Leaf nodes (no children) can have their routes used directly by
     // evaluateLazyEntry() without running the handler at runtime.
+    // Walk once into a per-router array, then fold it into the merged array;
+    // the merged and per-router entries are identical, so a second walk is
+    // redundant. Append order is preserved within and across routers.
+    const routerPrecomputed: PrecomputedEntry[] = [];
     flattenLeafEntries(
       manifest.prefixTree,
       manifest.routeManifest,
-      newMergedPrecomputedEntries,
+      routerPrecomputed,
     );
+    newMergedPrecomputedEntries.push(...routerPrecomputed);
 
     // Store per-router manifest and precomputed entries for isolated virtual modules.
     newPerRouterManifestDataMap.set(id, manifest.routeManifest);
-    const routerPrecomputed: PrecomputedEntry[] = [];
-    flattenLeafEntries(
-      manifest.prefixTree,
-      manifest.routeManifest,
-      routerPrecomputed,
-    );
     newPerRouterPrecomputedMap.set(id, routerPrecomputed);
 
     console.log(
@@ -294,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) {
@@ -343,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/discovery/virtual-module-codegen.ts

@@ -49,7 +49,6 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
         );
         genFileVars.push(varName);
       } else {
-        // Routers without sourceFile: inline their manifest data directly
         routersWithoutGenFile.push({
           id: entry.id,
           manifest: entry.routeManifest,
@@ -68,14 +67,12 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
       `clearAllRouterData();`,
     ];
 
-    // Flatten NamedRoutes entries: search schema objects -> plain string paths
     if (genFileVars.length > 0) {
       lines.push(
         `function __flat(r) { const o = {}; for (const [k, v] of Object.entries(r)) o[k] = typeof v === "string" ? v : v.path; return o; }`,
       );
     }
 
-    // Build the merged manifest from gen file imports + inlined data
     if (genFileVars.length === 1 && routersWithoutGenFile.length === 0) {
       lines.push(`setCachedManifest(__flat(${genFileVars[0]}));`);
     } else {
@@ -86,7 +83,6 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
       lines.push(`setCachedManifest({ ${parts.join(", ")} });`);
     }
 
-    // Set per-router manifests
     let genVarIdx = 0;
     for (const entry of state.perRouterManifests) {
       if (entry.sourceFile) {
@@ -114,8 +110,6 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
     // against live router.urlpatterns, which is always correct after a
     // program reload.
 
-    // Register lazy loaders for per-router manifest modules.
-    // Each import() uses a static string literal so Rollup creates separate chunks.
     for (const routerId of state.perRouterManifestDataMap.keys()) {
       lines.push(
         `registerRouterManifestLoader(${JSON.stringify(routerId)}, () => import(${JSON.stringify(VIRTUAL_ROUTES_MANIFEST_ID + "/" + routerId)}));`,
@@ -129,9 +123,6 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
     return lines.join("\n");
   }
 
-  // No manifest: either discovery hasn't completed or no runner (Cloudflare dev).
-  // Still inject __PRERENDER_DEV_URL so the prerender store can fetch on-demand.
-  // Re-resolve origin now since the server is listening by module load time.
   if (!state.isBuildMode) {
     const origin =
       state.devServerOrigin ||
@@ -160,7 +151,6 @@ export function generatePerRouterModule(
   const lines: string[] = [];
 
   if (routerEntry?.sourceFile) {
-    // Import manifest from the gen file so HMR auto-propagates
     const routerDir = dirname(routerEntry.sourceFile);
     const routerBasename = basename(routerEntry.sourceFile).replace(
       /\.(tsx?|jsx?)$/,
@@ -189,5 +179,5 @@ export function generatePerRouterModule(
       `export const precomputedEntries = ${jsonParseExpression(entries)};`,
     );
   }
-  return lines.join("\n") || "// empty router manifest";
+  return lines.join("\n") || "";
 }

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">;
 }
 
 /**
@@ -156,12 +169,25 @@ export interface RangoCloudflareOptions extends RangoBaseOptions {
   /**
    * Deployment preset for Cloudflare Workers.
    * When using cloudflare preset:
-   * - @vitejs/plugin-rsc is NOT added (cloudflare plugin adds it)
+   * - @vitejs/plugin-rsc IS still added by rango(), but with `serverHandler: false`
+   *   (the cloudflare plugin owns the RSC worker/server entry); only `client` and
+   *   `ssr` virtual entries are configured, no rsc entry
    * - Your worker entry (e.g., worker.rsc.tsx) imports the router directly
    * - Browser and SSR use virtual entries
    * - 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;
 }
 
 /**