@rangojs/router 0.0.0-experimental.7a20d911 → 0.0.0-experimental.7cf4e116

package/src/vite/discovery/route-types-writer.ts

@@ -5,13 +5,15 @@
  * from discovered router manifests and static source parsing.
  */
 
-import { dirname, basename, join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { readFileSync, writeFileSync, existsSync, unlinkSync } from "node:fs";
 import {
   generateRouteTypesSource,
   writeCombinedRouteTypes,
   findRouterFiles,
   buildCombinedRouteMapForRouterFile,
+  genFileTsPath,
+  resolveSearchSchemas,
 } from "../../build/generate-route-types.js";
 import type { DiscoveryState } from "./state.js";
 import { markSelfGenWrite } from "./self-gen-tracking.js";
@@ -35,6 +37,22 @@ function filterUserNamedRoutes(
   return filtered;
 }
 
+// Write a gen file only when content changed, marking the write as
+// self-generated BEFORE writeFileSync so the watcher distinguishes it from a
+// manual edit (the HMR self-gen-loop guard).
+function writeGenFileIfChanged(
+  state: DiscoveryState,
+  outPath: string,
+  source: string,
+  opts?: { log?: boolean },
+): void {
+  const existing = existsSync(outPath) ? readFileSync(outPath, "utf-8") : null;
+  if (existing === source) return;
+  markSelfGenWrite(state, outPath, source);
+  writeFileSync(outPath, source);
+  if (opts?.log) console.log(`[rango] Generated route types -> ${outPath}`);
+}
+
 /**
  * Write combined route types for all router files.
  * Only writes when content has changed to avoid triggering HMR loops.
@@ -48,45 +66,16 @@ export function writeCombinedRouteTypesWithTracking(
     findRouterFiles(state.projectRoot, state.scanFilter);
   state.cachedRouterFiles = routerFiles;
 
-  // Snapshot pre-write content to detect which files actually change.
-  const preContent = new Map<string, string>();
-  for (const routerFilePath of routerFiles) {
-    const routerDir = dirname(routerFilePath);
-    const routerBasename = basename(routerFilePath).replace(
-      /\.(tsx?|jsx?)$/,
-      "",
-    );
-    const outPath = join(routerDir, `${routerBasename}.named-routes.gen.ts`);
-    try {
-      preContent.set(outPath, readFileSync(outPath, "utf-8"));
-    } catch {
-      // File doesn't exist yet — any write is a real change.
-    }
-  }
-
-  writeCombinedRouteTypes(state.projectRoot, routerFiles, opts);
-
-  // Mark only files that were actually written so the watcher can
-  // distinguish self-triggered change events from manual edits.
-  // Marking unchanged files creates stale entries that interfere with
-  // multi-server setups (e.g. shared webServer + isolated HMR server).
-  for (const routerFilePath of routerFiles) {
-    const routerDir = dirname(routerFilePath);
-    const routerBasename = basename(routerFilePath).replace(
-      /\.(tsx?|jsx?)$/,
-      "",
-    );
-    const outPath = join(routerDir, `${routerBasename}.named-routes.gen.ts`);
-    if (!existsSync(outPath)) continue;
-    try {
-      const content = readFileSync(outPath, "utf-8");
-      if (content !== preContent.get(outPath)) {
-        markSelfGenWrite(state, outPath, content);
-      }
-    } catch {
-      // Ignore transient fs errors while files are being rewritten.
-    }
-  }
+  // Mark each gen file as self-generated BEFORE it is written, via the onWrite
+  // callback fired at every writeFileSync site, so the watcher distinguishes
+  // self-triggered change events from manual edits. The callback fires only
+  // for files actually written, so unchanged files are never marked (stale
+  // entries interfere with multi-server setups such as a shared webServer plus
+  // an isolated HMR server).
+  writeCombinedRouteTypes(state.projectRoot, routerFiles, {
+    ...opts,
+    onWrite: (outPath, content) => markSelfGenWrite(state, outPath, content),
+  });
 }
 
 /**
@@ -104,7 +93,7 @@ export function writeRouteTypesFiles(state: DiscoveryState): void {
     if (existsSync(oldCombinedPath)) {
       unlinkSync(oldCombinedPath);
       console.log(
-        `[rsc-router] Removed stale combined route types: ${oldCombinedPath}`,
+        `[rango] Removed stale combined route types: ${oldCombinedPath}`,
       );
     }
   } catch {}
@@ -122,40 +111,22 @@ export function writeRouteTypesFiles(state: DiscoveryState): void {
     // the wrong location, causing non-deterministic type resolution.
     if (sourceFile.includes("node_modules")) {
       throw new Error(
-        `[rsc-router] Router "${id}" has sourceFile inside node_modules: ${sourceFile}\n` +
+        `[rango] Router "${id}" has sourceFile inside node_modules: ${sourceFile}\n` +
           `This means createRouter() stack trace parsing matched a Vite internal frame.\n` +
           `Set an explicit \`id\` on createRouter() or check the call site.`,
       );
     }
 
-    const routerDir = dirname(sourceFile);
-    const routerBasename = basename(sourceFile).replace(/\.(tsx?|jsx?)$/, "");
-    const outPath = join(routerDir, `${routerBasename}.named-routes.gen.ts`);
+    const outPath = genFileTsPath(sourceFile);
 
     // Filter out auto-generated route names (e.g. "$path____debug_reverse-test")
     // to match the static parser's output and prevent HMR oscillation.
     const userRoutes = filterUserNamedRoutes(routeManifest);
-    let effectiveSearchSchemas = routeSearchSchemas;
-
-    // Runtime manifest may omit search schema metadata in some module-runner
-    // flows. Fall back to static source parsing from the router file.
-    if (
-      (!effectiveSearchSchemas ||
-        Object.keys(effectiveSearchSchemas).length === 0) &&
-      sourceFile
-    ) {
-      const staticParsed = buildCombinedRouteMapForRouterFile(sourceFile);
-      if (Object.keys(staticParsed.searchSchemas).length > 0) {
-        const filtered: Record<string, Record<string, string>> = {};
-        for (const name of Object.keys(userRoutes)) {
-          const schema = staticParsed.searchSchemas[name];
-          if (schema) filtered[name] = schema;
-        }
-        if (Object.keys(filtered).length > 0) {
-          effectiveSearchSchemas = filtered;
-        }
-      }
-    }
+    const effectiveSearchSchemas = resolveSearchSchemas(
+      Object.keys(userRoutes),
+      routeSearchSchemas,
+      sourceFile,
+    );
 
     const source = generateRouteTypesSource(
       userRoutes,
@@ -163,14 +134,7 @@ export function writeRouteTypesFiles(state: DiscoveryState): void {
         ? effectiveSearchSchemas
         : undefined,
     );
-    const existing = existsSync(outPath)
-      ? readFileSync(outPath, "utf-8")
-      : null;
-    if (existing !== source) {
-      markSelfGenWrite(state, outPath, source);
-      writeFileSync(outPath, source);
-      console.log(`[rsc-router] Generated route types -> ${outPath}`);
-    }
+    writeGenFileIfChanged(state, outPath, source, { log: true });
   }
 }
 
@@ -236,22 +200,14 @@ export function supplementGenFilesWithRuntimeRoutes(
       }
     }
 
-    const routerDir = dirname(sourceFile);
-    const routerBasename = basename(sourceFile).replace(/\.(tsx?|jsx?)$/, "");
-    const outPath = join(routerDir, `${routerBasename}.named-routes.gen.ts`);
+    const outPath = genFileTsPath(sourceFile);
     const source = generateRouteTypesSource(
       mergedRoutes,
       Object.keys(mergedSearchSchemas).length > 0
         ? mergedSearchSchemas
         : undefined,
     );
-    const existing = existsSync(outPath)
-      ? readFileSync(outPath, "utf-8")
-      : null;
-    if (existing !== source) {
-      markSelfGenWrite(state, outPath, source);
-      writeFileSync(outPath, source);
-    }
+    writeGenFileIfChanged(state, outPath, source);
   }
   // No manual manifest update needed: the virtual module imports the gen
   // file, so Vite's HMR automatically re-evaluates it with fresh data.

package/src/vite/discovery/self-gen-tracking.ts

@@ -22,6 +22,32 @@ export function markSelfGenWrite(
 export function consumeSelfGenWrite(
   state: DiscoveryState,
   filePath: string,
+): boolean {
+  return checkSelfGenWrite(state, filePath, true);
+}
+
+/**
+ * Non-consuming variant. Used by the `handleHotUpdate` plugin hook to
+ * suppress vite's HMR cascade for our own gen-file writes WITHOUT
+ * consuming the entry — `consumeSelfGenWrite` (called later from the
+ * chokidar `change` handler in `handleRouteFileChange`) still needs to
+ * see and consume the same entry to short-circuit our regen path.
+ *
+ * Both hooks fire for the same file change event:
+ *   - `handleHotUpdate` runs first (vite's HMR pipeline).
+ *   - chokidar `change` callback runs after (filesystem watcher).
+ */
+export function peekSelfGenWrite(
+  state: DiscoveryState,
+  filePath: string,
+): boolean {
+  return checkSelfGenWrite(state, filePath, false);
+}
+
+function checkSelfGenWrite(
+  state: DiscoveryState,
+  filePath: string,
+  consume: boolean,
 ): boolean {
   const info = state.selfWrittenGenFiles.get(filePath);
   if (!info) return false;
@@ -33,7 +59,7 @@ export function consumeSelfGenWrite(
     const current = readFileSync(filePath, "utf-8");
     const currentHash = createHash("sha256").update(current).digest("hex");
     if (currentHash === info.hash) {
-      state.selfWrittenGenFiles.delete(filePath);
+      if (consume) state.selfWrittenGenFiles.delete(filePath);
       return true;
     }
     // Hash mismatch: file was changed externally. Keep the entry so a

package/src/vite/discovery/state.ts

@@ -20,6 +20,24 @@ 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[] };
+  /**
+   * What to do when a Prerender/Static render throws at build time, from
+   * rango({ prerender: { onError } }). "fail" (default) fails the build; "warn"
+   * logs and skips baking the URL. See {@link import("../plugin-types.js").RangoOptions}.
+   */
+  prerenderOnError?: "fail" | "warn";
+  /**
+   * Shared context the built-in clientChunks strategy reads. Discovery populates
+   * it (registered fallback hashes + single-router name) before the client build
+   * invokes the strategy. Present only when the built-in strategy is active
+   * (`clientChunks: true`/default); undefined for `false` or a custom function.
+   */
+  clientChunkCtx?: import("../utils/client-chunks.js").ClientChunkContext;
 }
 
 export interface PrecomputedEntry {
@@ -45,6 +63,21 @@ export interface DiscoveryState {
   projectRoot: string;
   isBuildMode: boolean;
   userResolveAlias: any;
+  /**
+   * Data-only slice of the user's resolved config (resolve.* incl. native
+   * tsconfigPaths, define, oxc) mirrored into the discovery temp server so it
+   * resolves and transforms modules the same way the real environment does.
+   * See `utils/forward-user-plugins.ts`.
+   */
+  userRunnerConfig:
+    | import("../utils/forward-user-plugins.js").ForwardedRunnerConfig
+    | undefined;
+  /**
+   * User resolution plugins (resolveId/load), stripped to their resolution
+   * surface, forwarded into the discovery temp server. Lets third-party
+   * resolvers such as vite-tsconfig-paths participate in discovery.
+   */
+  userResolvePlugins: import("vite").Plugin[];
   scanFilter: ScanFilter | undefined;
   cachedRouterFiles: string[] | undefined;
   opts: PluginOptions | undefined;
@@ -76,6 +109,14 @@ export interface DiscoveryState {
   resolvedBuildEnv?: Record<string, unknown>;
   /** Cleanup function for build-time env resources (e.g., miniflare). */
   buildEnvDispose?: (() => Promise<void> | void) | null;
+
+  /**
+   * Set when the most recent HMR re-discovery threw. Cleared on the next
+   * successful discovery. Surfaced via debug logs so we can detect "manifest
+   * frozen at last-good after error → user fix in non-route file → no
+   * rediscovery trigger" scenarios.
+   */
+  lastDiscoveryError?: { message: string; at: number } | null;
 }
 
 export function createDiscoveryState(
@@ -87,6 +128,8 @@ export function createDiscoveryState(
     projectRoot: "",
     isBuildMode: false,
     userResolveAlias: undefined,
+    userRunnerConfig: undefined,
+    userResolvePlugins: [],
     scanFilter: undefined,
     cachedRouterFiles: undefined,
     opts,
@@ -113,5 +156,6 @@ export function createDiscoveryState(
     devServer: null,
     selfWrittenGenFiles: new Map(),
     SELF_WRITE_WINDOW_MS: 5_000,
+    lastDiscoveryError: null,
   };
 }

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,
@@ -58,7 +57,7 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
     }
 
     const lines = [
-      `import { setCachedManifest, setPrecomputedEntries, setRouteTrie, setRouterManifest, registerRouterManifestLoader, clearAllRouterData } from "@rangojs/router/server";`,
+      `import { setCachedManifest, setRouterManifest, registerRouterManifestLoader, clearAllRouterData } from "@rangojs/router/server";`,
       ...genFileImports,
       // Clear stale per-router cached data (manifest, trie, precomputed entries)
       // before re-populating. In Cloudflare dev mode, program reloads re-evaluate
@@ -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) {
@@ -101,31 +97,19 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
       }
     }
 
-    // In dev mode, skip trie and precomputed entries injection. These are
-    // computed once during initial discovery and become stale after route
-    // changes. A stale trie would incorrectly match removed routes. The
-    // handler falls back to Phase 2 regex matching against the live
-    // router.urlpatterns, which is always correct after a program reload.
-    // In build mode, the trie is always fresh (built from the final route
-    // tree) so it's safe to inject.
-    if (state.isBuildMode) {
-      if (
-        state.mergedPrecomputedEntries &&
-        state.mergedPrecomputedEntries.length > 0
-      ) {
-        lines.push(
-          `setPrecomputedEntries(${jsonParseExpression(state.mergedPrecomputedEntries)});`,
-        );
-      }
-      if (state.mergedRouteTrie) {
-        lines.push(
-          `setRouteTrie(${jsonParseExpression(state.mergedRouteTrie)});`,
-        );
-      }
-    }
+    // Per-router trie and precomputedEntries are NOT inlined eagerly.
+    // They live in the per-router lazy chunks (generatePerRouterModule) and
+    // are loaded via ensureRouterManifest(routerId), which is awaited before
+    // every request in router.fetch() and before findMatch is reached.
+    // Inlining the merged versions here would duplicate the per-router data
+    // (the merged trie/precomputedEntries equal the per-router data for
+    // single-router apps; for multi-router, the merged trie is dead code
+    // because find-match.ts only consumes per-router tries).
+    //
+    // In dev mode, the handler also falls back to Phase 2 regex matching
+    // 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)}));`,
@@ -139,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 ||
@@ -170,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?)$/,
@@ -199,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/index.ts

@@ -13,6 +13,8 @@ export type {
   RangoNodeOptions,
   RangoCloudflareOptions,
   RangoOptions,
+  ClientChunks,
+  ClientChunkMeta,
   BuildEnvOption,
   BuildEnvFactory,
   BuildEnvFactoryContext,

package/src/vite/inject-client-debug.ts

@@ -0,0 +1,36 @@
+/**
+ * Bake the resolved INTERNAL_RANGO_DEBUG value into the router's `internal-debug`
+ * module so the flag reaches the CLIENT debug logs by just setting the env var.
+ *
+ * internal-debug.ts normally reads the flag via `typeof __RANGO_DEBUG__`, a Vite
+ * define. That delivery is unreliable on the client: in dev Vite ships the define
+ * only as an injected global whose presence varies across consumer setups, so the
+ * module can fall through to `process.env` (undefined in the browser) and the FE
+ * debug flag silently stays false while the server logs work. A Vite `transform`
+ * runs on the module regardless of how (or whether) the define is delivered, in
+ * both dev and build and for every environment, so the discovery plugin uses this
+ * to replace the module with the resolved literal.
+ *
+ * Returns null for any module that is not the router's internal-debug module.
+ */
+export function injectClientDebugFlag(
+  id: string,
+): { code: string; map: null } | null {
+  // Cheap early-out: this hook runs on every module in every environment.
+  if (!id.includes("internal-debug")) return null;
+  const norm = id.replace(/\\/g, "/");
+  // Scope to the router's own internal-debug module: the published package
+  // (`/@rangojs/router/`, incl. pnpm's nested layout) or the monorepo workspace
+  // (`/packages/rangojs-router/`). The package-anchored path avoids matching a
+  // consumer file that merely sits under a directory named `rangojs-router`.
+  const isInternalDebug =
+    /\/internal-debug\.[cm]?[jt]sx?(\?|$)/.test(norm) &&
+    (norm.includes("/@rangojs/router/") ||
+      norm.includes("/packages/rangojs-router/"));
+  if (!isInternalDebug) return null;
+  // Emit the whole module: internal-debug.ts has a single export, kept in sync.
+  return {
+    code: `export const INTERNAL_RANGO_DEBUG = ${!!process.env.INTERNAL_RANGO_DEBUG};\n`,
+    map: null,
+  };
+}

package/src/vite/plugin-types.ts

@@ -47,6 +47,64 @@ export type BuildEnvOption =
   | Record<string, unknown>
   | BuildEnvFactory;
 
+// -- Client chunking --------------------------------------------------------
+
+/**
+ * Metadata for one client ("use client") module, passed to a {@link ClientChunks}
+ * function. Mirrors the shape `@vitejs/plugin-rsc` passes to its own
+ * `clientChunks` option.
+ */
+export interface ClientChunkMeta {
+  /** Absolute module id of the "use client" file. */
+  id: string;
+  /** Normalized (posix) module id — convenient for path-based matching. */
+  normalizedId: string;
+  /**
+   * The RSC/server chunk that statically imports this client reference. This is
+   * the key used for the default grouping when no override is supplied: a single
+   * router that statically imports every route yields ONE `serverChunk`, hence
+   * one client chunk for all routes.
+   */
+  serverChunk: string;
+}
+
+/**
+ * Controls how client ("use client") components are grouped into browser
+ * chunks, i.e. per-route / per-feature code splitting of the client bundle.
+ *
+ * Without splitting, a single router ships ONE client chunk containing every
+ * route's client components (and their CSS) — navigating to one route downloads
+ * every other route's client code. (Host sub-apps loaded via a dynamic `import()`
+ * are the exception: each forms its own chunk.) This option controls how that
+ * monolith is split.
+ *
+ * Behavior branches:
+ * - `true` / omitted (**default**, pre-1.0): Rango's built-in **directory
+ *   strategy**. It splits app `"use client"` modules by **route id** — the segment
+ *   after a route-root directory (`routes`, `app`, `pages`, `features`, `handlers`,
+ *   …) — so `routes/dashboard/**` becomes `app-dashboard` at any nesting depth.
+ *   Where it finds NO route structure (a flat `src/components/`, or host sub-apps
+ *   already split by a dynamic `import()`), it inherits the default grouping
+ *   unchanged — so the shared `src/components` chunk stays shared and host apps do
+ *   not leak across each other. Shared runtime (React, the router, `node_modules`)
+ *   is never split.
+ * - `false`: opt out — inherit `@vitejs/plugin-rsc`'s default grouping everywhere
+ *   (one chunk per router / per host sub-app).
+ * - function: full override. Return a chunk group name, or `undefined` to fall
+ *   back to the default grouping for that one module. Forwarded directly to
+ *   `@vitejs/plugin-rsc`'s `clientChunks`.
+ *
+ * Every module maps to exactly one group, so there is no byte duplication: a
+ * component used by two routes lives in one group and is fetched whenever it
+ * renders. Put genuinely shared client components OUTSIDE route directories so
+ * they land in the shared group rather than one route's chunk.
+ *
+ * @default true
+ */
+export type ClientChunks =
+  | boolean
+  | ((meta: ClientChunkMeta) => string | undefined);
+
 // -- Plugin options ---------------------------------------------------------
 
 /**
@@ -60,16 +118,52 @@ interface RangoBaseOptions {
   banner?: boolean;
 
   /**
-   * 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`).
+   * Group client ("use client") components into browser chunks for per-route /
+   * per-feature code splitting. On by default (pre-1.0); pass `false` to opt out.
+   * See {@link ClientChunks}.
    *
-   * 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.
+   * @default true
+   */
+  clientChunks?: ClientChunks;
+
+  /**
+   * 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[];
+  };
+
+  /**
+   * What to do when a `Prerender` route's or `Static` handler's render throws at
+   * build time. Otherwise the route error boundary catches it and the rendered
+   * error page is baked as the artifact, then served as an HTTP 200 — a silent,
+   * user-visible breakage (issue #587). Independent of this setting, a render may
+   * `throw new Skip()` (from `@rangojs/router`) to skip a single URL/handler.
+   *
+   * - `"fail"` (**default**): fail the build, naming the URL/handler and the
+   *   original render error.
+   * - `"warn"`: log a warning and skip baking the artifact — it is never served as a
+   *   baked 200 error page. `"warn"` is a build-unblock, NOT a runtime contract for
+   *   the skipped entry: the route falls through to normal resolution, which may
+   *   render live (its handler is still bundled — e.g. when nothing else baked) or
+   *   404 (once prerender handler eviction has run for other baked entries), so the
+   *   outcome depends on the rest of the build, and a skipped `Static()` handler's
+   *   evicted code can surface as an error. For DEFINED runtime behavior use
+   *   `Passthrough()` (a live fallback) or `throw new Skip()` (an intentional skip);
+   *   otherwise prefer the default `"fail"`.
+   *
+   * @default "fail"
+   */
+  prerender?: {
+    onError?: "fail" | "warn";
+  };
 }
 
 /**
@@ -80,6 +174,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">;
 }
 
 /**
@@ -89,12 +194,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;
 }
 
 /**