@rangojs/router 0.0.0-experimental.21 → 0.0.0-experimental.21efdd86

package/src/use-loader.tsx

@@ -1,9 +1,70 @@
 "use client";
 
-import { useCallback, useContext, useEffect, useRef, useState } from "react";
+import {
+  isValidElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
 import { OutletContext, type OutletContextValue } from "./outlet-context.js";
 import type { LoaderDefinition, LoadOptions } from "./types.js";
 
+/**
+ * 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(
+  node: ReactNode,
+  loaderId: string,
+): unknown | typeof NOT_FOUND {
+  if (!isValidElement(node)) return NOT_FOUND;
+  const props = node.props as Record<string, any> | undefined;
+  if (!props) return NOT_FOUND;
+
+  // Direct OutletProvider with loaderData
+  if (props.loaderData && loaderId in props.loaderData) {
+    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) &&
+    props.loaderDataPromise &&
+    !(props.loaderDataPromise instanceof Promise)
+  ) {
+    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;
+      }
+      return data;
+    }
+  }
+
+  // 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
  */
@@ -71,19 +132,27 @@ function useLoaderInternal<T>(
   const context = useContext(OutletContext);
 
   // Get data from context (SSR/navigation)
-  const getContextData = useCallback((): T | undefined => {
+  const contextData = useMemo((): T | undefined => {
     let current: OutletContextValue | null | undefined = context;
     while (current) {
       if (current.loaderData && loader.$$id in current.loaderData) {
         return current.loaderData[loader.$$id] as T;
       }
+      // 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,
+      );
+      if (contentData !== NOT_FOUND) {
+        return contentData as T;
+      }
       current = current.parent;
     }
     return undefined;
   }, [context, loader.$$id]);
 
-  const contextData = getContextData();
-
   // Local state for fetched data (from load() calls)
   const [fetchedData, setFetchedData] = useState<T | undefined>(undefined);
   const [isLoading, setIsLoading] = useState(false);

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

@@ -31,25 +31,25 @@ export function postprocessBundle(state: DiscoveryState): void {
     state.rscEntryFileName ?? "index.js",
   );
 
-  // 1. Evict handler code from __prerender-handlers and __static-handlers chunks.
-  // handlerChunkInfo/staticHandlerChunkInfo are populated by generateBundle
+  // 1. Evict handler code from whichever chunks contain handler exports.
+  // handlerChunkInfoMap/staticHandlerChunkInfoMap are populated by generateBundle
   // after the production RSC build. In Vite 6 multi-environment builds, the
-  // RSC build runs twice (analysis + production). Chunk info is only available
-  // after the production pass, so we run eviction whenever it becomes available.
+  // RSC build runs twice (analysis + production). The maps are cleared at the
+  // start of each generateBundle pass so only production data is used here.
   const evictionTargets: Array<{
-    info: typeof state.handlerChunkInfo;
+    infos: Iterable<import("./state.js").ChunkInfo>;
     fnName: string;
     brand: string;
     label: string;
   }> = [
     {
-      info: state.handlerChunkInfo,
+      infos: state.handlerChunkInfoMap.values(),
       fnName: "Prerender",
       brand: "prerenderHandler",
       label: "handler code from RSC bundle",
     },
     {
-      info: state.staticHandlerChunkInfo,
+      infos: state.staticHandlerChunkInfoMap.values(),
       fnName: "Static",
       brand: "staticHandler",
       label: "static handler code",
@@ -57,35 +57,32 @@ export function postprocessBundle(state: DiscoveryState): void {
   ];
 
   for (const target of evictionTargets) {
-    if (!target.info) continue;
-    const chunkPath = resolve(
-      state.projectRoot,
-      "dist/rsc",
-      target.info.fileName,
-    );
-    try {
-      const code = readFileSync(chunkPath, "utf-8");
-      const result = evictHandlerCode(
-        code,
-        target.info.exports,
-        target.fnName,
-        target.brand,
-      );
-      if (result) {
-        writeFileSync(chunkPath, result.code);
-        const savedKB = (result.savedBytes / 1024).toFixed(1);
-        console.log(
-          `[rsc-router] Evicted ${target.label} (${savedKB} KB saved): ${target.info.fileName}`,
+    for (const info of target.infos) {
+      const chunkPath = resolve(state.projectRoot, "dist/rsc", info.fileName);
+      try {
+        const code = readFileSync(chunkPath, "utf-8");
+        const result = evictHandlerCode(
+          code,
+          info.exports,
+          target.fnName,
+          target.brand,
+        );
+        if (result) {
+          writeFileSync(chunkPath, result.code);
+          const savedKB = (result.savedBytes / 1024).toFixed(1);
+          console.log(
+            `[rsc-router] Evicted ${target.label} (${savedKB} KB saved): ${info.fileName}`,
+          );
+        }
+      } catch (replaceErr: any) {
+        console.warn(
+          `[rsc-router] Failed to evict ${target.label}: ${replaceErr.message}`,
         );
       }
-    } catch (replaceErr: any) {
-      console.warn(
-        `[rsc-router] Failed to evict ${target.label}: ${replaceErr.message}`,
-      );
     }
   }
-  state.handlerChunkInfo = null;
-  state.staticHandlerChunkInfo = null;
+  state.handlerChunkInfoMap.clear();
+  state.staticHandlerChunkInfoMap.clear();
 
   // 2. Write prerender data as separate importable asset modules
   // and inject a lazy manifest loader into the RSC entry.
@@ -138,7 +135,7 @@ export function postprocessBundle(state: DiscoveryState): void {
   // and inject a __STATIC_MANIFEST import into the RSC entry.
   if (hasStaticData && existsSync(rscEntryPath)) {
     const rscCode = readFileSync(rscEntryPath, "utf-8");
-    if (!rscCode.includes("__STATIC_MANIFEST")) {
+    if (!rscCode.includes("__static-manifest.js")) {
       try {
         const manifestEntries: string[] = [];
         let totalBytes = copyStagedBuildAssets(

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

@@ -48,9 +48,8 @@ export async function discoverRouters(
     // No RSC routers found directly. Check for host routers with lazy handlers
     // that need to be resolved to trigger sub-app createRouter() calls.
     try {
-      const hostMod = await rscEnv.runner.import("@rangojs/router/host");
       const hostRegistry: Map<string, any> | undefined =
-        hostMod.HostRouterRegistry;
+        serverMod.HostRouterRegistry;
 
       if (hostRegistry && hostRegistry.size > 0) {
         console.log(
@@ -89,7 +88,7 @@ export async function discoverRouters(
         }
       }
     } catch {
-      // @rangojs/router/host not available or import failed, skip
+      // Host-router discovery is best-effort; skip if unavailable
     }
 
     // If still no routers after host router resolution, fail
@@ -136,7 +135,11 @@ export async function discoverRouters(
       continue;
     }
 
-    const manifest = generateManifestFull(router.urlpatterns, routerMountIndex);
+    const manifest = generateManifestFull(
+      router.urlpatterns,
+      routerMountIndex,
+      router.__basename ? { urlPrefix: router.__basename } : undefined,
+    );
     routerMountIndex++;
     allManifests.push({ id, manifest });
     const routeCount = Object.keys(manifest.routeManifest).length;

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

@@ -54,11 +54,12 @@ export async function expandPrerenderRoutes(
   for (const { manifest } of allManifests) {
     if (!manifest.prerenderRoutes) continue;
     const defs = manifest._prerenderDefs || {};
+    const passthroughSet = new Set(manifest.passthroughRoutes || []);
     for (const routeName of manifest.prerenderRoutes) {
       const pattern = manifest.routeManifest[routeName];
       if (!pattern) continue;
       const def = defs[routeName];
-      const isPassthroughRoute = !!def?.options?.passthrough;
+      const isPassthroughRoute = passthroughSet.has(routeName);
       const hasDynamic = pattern.includes(":") || pattern.includes("*");
       if (!hasDynamic) {
         // Static route: use pattern directly (strip trailing slash for URL)
@@ -73,12 +74,21 @@ export async function expandPrerenderRoutes(
         if (def?.getParams) {
           try {
             const buildVars: Record<string, any> = {};
+            const buildEnv = state.resolvedBuildEnv;
             const getParamsCtx = {
               build: true as const,
+              dev: !state.isBuildMode,
               set: ((keyOrVar: any, value: any) => {
                 contextSet(buildVars, keyOrVar, value);
               }) as any,
               reverse: getParamsReverse,
+              get env() {
+                if (buildEnv !== undefined) return buildEnv;
+                throw new Error(
+                  "[rsc-router] ctx.env is not available during build-time getParams(). " +
+                    "Configure buildEnv in your rango() plugin options to enable build-time env access.",
+                );
+              },
             };
             const paramsList = await def.getParams(getParamsCtx);
             const concurrency = def.options?.concurrency ?? 1;
@@ -175,6 +185,7 @@ export async function expandPrerenderRoutes(
               {},
               entry.buildVars,
               entry.isPassthroughRoute,
+              state.resolvedBuildEnv,
             );
             if (!result) continue;
 
@@ -326,6 +337,8 @@ export async function renderStaticHandlers(
             def.handler,
             def.$$id,
             (def as any).$$routePrefix,
+            state.resolvedBuildEnv,
+            !state.isBuildMode,
           );
           if (result) {
             const hasHandles = Object.keys(result.handles).length > 0;

package/src/vite/discovery/state.ts

@@ -13,11 +13,13 @@ export const VIRTUAL_ROUTES_MANIFEST_ID = "virtual:rsc-router/routes-manifest";
 export interface PluginOptions {
   enableBuildPrerender?: boolean;
   staticRouteTypesGeneration?: boolean;
-  include?: string[];
-  exclude?: string[];
   // Mutable ref for deferred auto-discovery (node preset).
   // The auto-discover config() hook populates this before configResolved.
   routerPathRef?: { path?: string };
+  /** Build-time env option from rango() config. */
+  buildEnv?: import("../plugin-types.js").BuildEnvOption;
+  /** Deployment preset (needed for buildEnv "auto" resolution). */
+  preset?: "node" | "cloudflare";
 }
 
 export interface PrecomputedEntry {
@@ -58,8 +60,8 @@ export interface DiscoveryState {
 
   prerenderManifestEntries: Record<string, string> | null;
   staticManifestEntries: Record<string, string> | null;
-  handlerChunkInfo: ChunkInfo | null;
-  staticHandlerChunkInfo: ChunkInfo | null;
+  handlerChunkInfoMap: Map<string, ChunkInfo>;
+  staticHandlerChunkInfoMap: Map<string, ChunkInfo>;
   rscEntryFileName: string | null;
   resolvedPrerenderModules: Map<string, string[]> | undefined;
   resolvedStaticModules: Map<string, string[]> | undefined;
@@ -69,6 +71,11 @@ export interface DiscoveryState {
   devServer: any;
   selfWrittenGenFiles: Map<string, { at: number; hash: string }>;
   SELF_WRITE_WINDOW_MS: number;
+
+  /** Resolved build-time env bindings (set during buildStart/configureServer). */
+  resolvedBuildEnv?: Record<string, unknown>;
+  /** Cleanup function for build-time env resources (e.g., miniflare). */
+  buildEnvDispose?: (() => Promise<void> | void) | null;
 }
 
 export function createDiscoveryState(
@@ -95,8 +102,8 @@ export function createDiscoveryState(
 
     prerenderManifestEntries: null,
     staticManifestEntries: null,
-    handlerChunkInfo: null,
-    staticHandlerChunkInfo: null,
+    handlerChunkInfoMap: new Map(),
+    staticHandlerChunkInfoMap: new Map(),
     rscEntryFileName: null,
     resolvedPrerenderModules: undefined,
     resolvedStaticModules: undefined,

package/src/vite/index.ts

@@ -1,15 +1,20 @@
 /**
  * Public API for @rangojs/router/vite
  *
- * Only the rango() plugin factory and its option types are part of the
- * public API. All other utilities are internal implementation details
- * consumed via direct imports within the package.
+ * Exports: rango() plugin factory, poke() dev utility plugin,
+ * and related option types. All other utilities are internal implementation
+ * details consumed via direct imports within the package.
  */
 
 export { rango } from "./rango.js";
+export { poke } from "./plugins/refresh-cmd.js";
 
 export type {
   RangoNodeOptions,
   RangoCloudflareOptions,
   RangoOptions,
+  BuildEnvOption,
+  BuildEnvFactory,
+  BuildEnvFactoryContext,
+  BuildEnvResult,
 } from "./plugin-types.js";

package/src/vite/plugin-types.ts

@@ -1,38 +1,53 @@
+// -- Build-time environment types -------------------------------------------
+
 /**
- * RSC plugin entry points configuration.
- * All entries use virtual modules by default. Specify a path to use a custom entry file.
+ * Context passed to a buildEnv factory function.
+ * Provides Vite config details for conditional env setup.
  */
-export interface RscEntries {
-  /**
-   * Path to a custom browser/client entry file.
-   * If not specified, a default virtual entry is used.
-   */
-  client?: string;
+export interface BuildEnvFactoryContext {
+  /** Vite project root directory. */
+  root: string;
+  /** Vite mode (e.g. "development", "production"). */
+  mode: string;
+  /** Vite command ("serve" for dev, "build" for production). */
+  command: "serve" | "build";
+  /** Router deployment preset. */
+  preset: "node" | "cloudflare";
+}
 
-  /**
-   * Path to a custom SSR entry file.
-   * If not specified, a default virtual entry is used.
-   */
-  ssr?: string;
+/**
+ * Factory function that creates build-time environment bindings.
+ * Called once at plugin startup. Return `dispose` to clean up resources.
+ */
+export type BuildEnvFactory = (
+  ctx: BuildEnvFactoryContext,
+) => Promise<BuildEnvResult> | BuildEnvResult;
 
-  /**
-   * Path to a custom RSC entry file.
-   * If not specified, a default virtual entry is used that imports the router from the `entry` option.
-   */
-  rsc?: string;
+/**
+ * Result of resolving build-time environment bindings.
+ */
+export interface BuildEnvResult {
+  /** Environment bindings available to Prerender/Static handlers via ctx.env. */
+  env: Record<string, unknown>;
+  /** Called after build completes to clean up resources (e.g., miniflare). */
+  dispose?: () => Promise<void> | void;
 }
 
 /**
- * Options for @vitejs/plugin-rsc integration
+ * Build-time environment configuration for Prerender and Static handlers.
+ *
+ * - `false` (default): no build-time env, `ctx.env` throws.
+ * - `"auto"`: calls `wrangler.getPlatformProxy()` (cloudflare preset only).
+ * - Object: used directly as `ctx.env` during build.
+ * - Factory: called once at startup, must return `{ env, dispose? }`.
  */
-export interface RscPluginOptions {
-  /**
-   * Entry points for client, ssr, and rsc environments.
-   * All entries use virtual modules by default.
-   * Specify paths only when you need custom entry files.
-   */
-  entries?: RscEntries;
-}
+export type BuildEnvOption =
+  | false
+  | "auto"
+  | Record<string, unknown>
+  | BuildEnvFactory;
+
+// -- Plugin options ---------------------------------------------------------
 
 /**
  * Base options shared by all presets
@@ -45,27 +60,16 @@ interface RangoBaseOptions {
   banner?: boolean;
 
   /**
-   * Generate named-routes.gen.ts by parsing url modules at startup.
-   * Provides type-safe Handler<"name"> and href() without executing router code.
-   * Set to `false` to disable (run `npx rango extract-names` manually instead).
-   * @default true
-   */
-  staticRouteTypesGeneration?: boolean;
-
-  /**
-   * Glob patterns for files to include in route type scanning.
-   * Only files matching at least one pattern will be scanned.
-   * Patterns are relative to the project root.
-   * When unset, all .ts/.tsx files are scanned.
-   */
-  include?: string[];
-
-  /**
-   * Glob patterns for files to exclude from route type scanning.
-   * Takes precedence over `include`. Patterns are relative to the project root.
-   * Defaults to common test/build directories.
+   * 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.
+   *
+   * @default false
    */
-  exclude?: string[];
+  buildEnv?: BuildEnvOption;
 }
 
 /**
@@ -76,38 +80,6 @@ export interface RangoNodeOptions extends RangoBaseOptions {
    * Deployment preset. Defaults to 'node' when not specified.
    */
   preset?: "node";
-
-  /**
-   * Path to your router configuration file that exports the route tree.
-   * This file must export a `router` object created with `createRouter()`.
-   *
-   * When omitted, auto-discovers the router by scanning for files containing
-   * `createRouter`. If exactly one is found, it is used automatically.
-   * If multiple are found, an error is thrown with the list of candidates.
-   *
-   * @example
-   * ```ts
-   * rango({ router: './src/router.tsx' })
-   * // or simply:
-   * rango()
-   * ```
-   */
-  router?: string;
-
-  /**
-   * RSC plugin configuration. By default, rsc-router includes @vitejs/plugin-rsc
-   * with sensible defaults.
-   *
-   * Entry files (browser, ssr, rsc) are optional - if they don't exist,
-   * virtual defaults are used.
-   *
-   * - Omit or pass `true`/`{}` to use defaults (recommended)
-   * - Pass `{ entries: {...} }` to customize entry paths
-   * - Pass `false` to disable (for manual @vitejs/plugin-rsc configuration)
-   *
-   * @default true
-   */
-  rsc?: boolean | RscPluginOptions;
 }
 
 /**

package/src/vite/plugins/expose-action-id.ts

@@ -278,9 +278,7 @@ export function exposeActionId(): Plugin {
       if (!rscPluginApi) {
         throw new Error(
           "[rsc-router] Could not find @vitejs/plugin-rsc. " +
-            "@rangojs/router requires the Vite RSC plugin.\n" +
-            "The RSC plugin should be included automatically. If you disabled it with\n" +
-            "rango({ rsc: false }), add rsc() before rango() in your config.",
+            "@rangojs/router requires the Vite RSC plugin, which is included automatically by rango().",
         );
       }
 

package/src/vite/plugins/performance-tracks.ts

@@ -0,0 +1,88 @@
+/**
+ * React Performance Tracks — RSDW client patch
+ *
+ * Patches the RSDW client so _debugInfo recovery works for plain-object
+ * payloads (our RscPayload shape). Without this, the Server Components
+ * track in Chrome DevTools stays empty.
+ *
+ * React's flushComponentPerformance uses splice(0) to empty _debugInfo
+ * after resolution, then recovers it from the resolved value — but only
+ * for arrays, async iterables, React elements, and lazy types. Since our
+ * RscPayload is a plain object, _debugInfo is lost. This patch relaxes
+ * the check so _debugInfo is recovered from any object.
+ */
+
+import type { Plugin } from "vite";
+import { readFile } from "node:fs/promises";
+
+const RSDW_PATCH_RE =
+  /((?:var|let|const)\s+\w+\s*=\s*root\._children\s*,\s*(\w+)\s*=\s*root\._debugInfo\s*[;,])/;
+
+function buildPatchReplacement(match: string, debugInfoVar: string): string {
+  return `${match}
+if (${debugInfoVar} && 0 === ${debugInfoVar}.length && "fulfilled" === root.status) {
+  var _resolved = "function" === typeof resolveLazy ? resolveLazy(root.value) : root.value;
+  if ("object" === typeof _resolved && null !== _resolved && isArrayImpl(_resolved._debugInfo)) {
+    ${debugInfoVar} = _resolved._debugInfo;
+  }
+}`;
+}
+
+export function patchRsdwClientDebugInfoRecovery(code: string): {
+  code: string;
+  debugInfoVar: string | null;
+} {
+  const match = code.match(RSDW_PATCH_RE);
+  if (!match) {
+    return { code, debugInfoVar: null };
+  }
+
+  return {
+    code: code.replace(match[1]!, buildPatchReplacement(match[1]!, match[2]!)),
+    debugInfoVar: match[2]!,
+  };
+}
+
+export function performanceTracksOptimizeDepsPlugin(): {
+  name: string;
+  setup(build: any): void;
+} {
+  return {
+    name: "@rangojs/router:performance-tracks-optimize-deps",
+    setup(build: any): void {
+      build.onLoad(
+        {
+          filter:
+            /react-server-dom-webpack-client\.browser\.(development|production)\.js$/,
+        },
+        async (args: { path: string }) => {
+          const code = await readFile(args.path, "utf8");
+          const patched = patchRsdwClientDebugInfoRecovery(code);
+          return {
+            contents: patched.code,
+            loader: "js",
+          };
+        },
+      );
+    },
+  };
+}
+
+export function performanceTracksPlugin(): Plugin {
+  return {
+    name: "@rangojs/router:performance-tracks",
+
+    transform(code, id) {
+      if (!id.includes("react-server-dom") || !id.includes("client")) return;
+      const patched = patchRsdwClientDebugInfoRecovery(code);
+      if (!patched.debugInfoVar) return;
+      if (process.env.INTERNAL_RANGO_DEBUG)
+        console.log(
+          "[perf-tracks] patched RSDW client (var:",
+          patched.debugInfoVar,
+          ")",
+        );
+      return patched.code;
+    },
+  };
+}