@rangojs/router 0.0.0-experimental.10 → 0.0.0-experimental.100

package/src/loader.rsc.ts

@@ -5,9 +5,9 @@
  * Only used in react-server context via export conditions.
  *
  * For non-fetchable loaders: returns a loader definition with fn included
- * For fetchable loaders: stores fn in registry and returns a serializable loader with action
+ * For fetchable loaders: stores fn in registry and returns a serializable loader
  *
- * The $$id is injected by the Vite exposeLoaderId plugin as a hidden parameter.
+ * The $$id is injected by the Vite exposeInternalIds plugin as a hidden parameter.
  * Users don't need to pass any name - IDs are auto-generated from file path.
  */
 
@@ -17,90 +17,54 @@ import type {
   LoaderFn,
 } from "./types.js";
 import type { MiddlewareFn } from "./router/middleware.js";
-import { getRequestContext } from "./server/request-context.js";
+import {
+  registerFetchableLoader,
+  getFetchableLoader,
+} from "./server/fetchable-loader-store.js";
 
-// Internal registry for fetchable loaders (server-side only)
-// Maps loader $$id to its function and middleware
-//
-// WHY TWO REGISTRIES?
-// This registry (fetchableLoaderRegistry) is populated immediately when createLoader() runs.
-// The other registry in loader-registry.ts (loaderRegistry) is a cache used by the RSC handler
-// for GET-based fetching. The RSC handler calls getFetchableLoader() from here to populate
-// its cache. This separation allows:
-// 1. Server actions to look up loaders directly without going through lazy loading
-// 2. The RSC handler to use lazy loading for production builds
-// 3. Both to share the same source of truth (this registry)
-const fetchableLoaderRegistry = new Map<
-  string,
-  { fn: LoaderFn<any, any, any>; middleware: MiddlewareFn[] }
->();
-
-/**
- * Register a fetchable loader's function internally
- * Called during module initialization with the $$id
- */
-function registerFetchableLoader(
-  id: string,
-  fn: LoaderFn<any, any, any>,
-  middleware: MiddlewareFn[]
-): void {
-  fetchableLoaderRegistry.set(id, { fn, middleware });
-}
-
-/**
- * Get a fetchable loader's function from the internal registry by $$id
- *
- * This is used internally by:
- * - Server actions (loaderAction) to execute loader functions
- * - loader-registry.ts to populate the main registry for GET-based fetching
- *
- * Loaders are registered here when createLoader() is called with fetchable: true.
- * The $$id is injected by the Vite exposeLoaderId plugin.
- *
- * @param id - The loader's $$id (auto-generated from file path + export name)
- * @returns The loader function and middleware, or undefined if not found
- *
- * @internal This is primarily for internal use by the router infrastructure
- */
-export function getFetchableLoader(
-  id: string
-): { fn: LoaderFn<any, any, any>; middleware: MiddlewareFn[] } | undefined {
-  return fetchableLoaderRegistry.get(id);
-}
+export { getFetchableLoader };
 
 // Overload 1: With function only (not fetchable)
 export function createLoader<T>(
-  fn: LoaderFn<T, Record<string, string | undefined>, any>
+  fn: LoaderFn<T, Record<string, string | undefined>, any>,
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
 
 // Overload 2: Fetchable with `true` (no middleware)
 export function createLoader<T>(
   fn: LoaderFn<T, Record<string, string | undefined>, any>,
-  fetchable: true
+  fetchable: true,
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
 
 // Overload 3: Fetchable with middleware options
 export function createLoader<T>(
   fn: LoaderFn<T, Record<string, string | undefined>, any>,
-  options: FetchableLoaderOptions
+  options: FetchableLoaderOptions,
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
 
 // Implementation - the $$id parameter is injected by Vite plugin, not user-provided
 export function createLoader<T>(
   fn: LoaderFn<T, Record<string, string | undefined>, any>,
   fetchable?: true | FetchableLoaderOptions,
-  // Hidden parameter injected by Vite exposeLoaderId plugin
-  __injectedId?: string
+  // Hidden parameter injected by Vite exposeInternalIds plugin
+  __injectedId?: string,
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>> {
   // The $$id will be set on the returned object by Vite plugin
   // For fetchable loaders, __injectedId is also passed as a parameter
   const loaderId = __injectedId || "";
 
-  // If not fetchable, store fn in registry and return a plain object.
-  // Server-side code looks up fn via getFetchableLoader($$id).
+  if (!loaderId && process.env.NODE_ENV === "development") {
+    throw new Error(
+      "[rsc-router] Loader is missing $$id. " +
+        "Make sure the exposeInternalIds Vite plugin is enabled and " +
+        "the loader is exported with: export const MyLoader = createLoader(...)",
+    );
+  }
+
+  // If not fetchable, store fn in registry (for SSR ctx.use() resolution)
+  // but mark fetchable=false so the _rsc_loader endpoint rejects it.
   if (fetchable === undefined) {
     if (fn && loaderId) {
-      registerFetchableLoader(loaderId, fn, []);
+      registerFetchableLoader(loaderId, fn, [], false);
     }
     return {
       __brand: "loader",
@@ -113,95 +77,13 @@ export function createLoader<T>(
     fetchable === true ? [] : fetchable?.middleware || [];
 
   // Register the function in the internal registry by $$id (server-side only)
-  // The server action will look it up by $$id when executed
+  // The loader fetch handler looks it up by $$id when load() is called from the client.
   if (fn && loaderId) {
-    registerFetchableLoader(loaderId, fn, middleware);
-  }
-
-  // Create server action for form-based fetching
-  // This action is serializable and can be passed to client components
-  // The loaderId is captured in closure (it's a primitive string)
-  //
-  // IMPORTANT: The signature must be (prevState, formData) for useActionState compatibility.
-  // When used with useActionState, React passes the previous state as the first argument.
-  // The prevState is ignored here since loaders are stateless data fetchers.
-  async function loaderAction(
-    _prevState: Awaited<T> | null,
-    formData: FormData
-  ): Promise<Awaited<T>> {
-    "use server";
-
-    // Look up the loader from registry by $$id
-    const registered = fetchableLoaderRegistry.get(loaderId);
-    if (!registered) {
-      throw new Error(`Loader "${loaderId}" not found in registry`);
-    }
-
-    // Get request context (env, request, url, variables) from the RSC handler
-    // This is set by runWithRequestContext in rsc/index.ts when executing actions
-    const requestCtx = getRequestContext();
-
-    // Convert FormData to params object
-    const params: Record<string, string> = {};
-    formData.forEach((value, key) => {
-      if (typeof value === "string") {
-        params[key] = value;
-      }
-    });
-
-    // Use real request/url from context, or fall back to synthetic for edge cases
-    const actionUrl = requestCtx?.url ?? new URL("http://localhost/");
-    const actionRequest = requestCtx?.request ?? new Request(actionUrl, { method: "POST" });
-    const env = requestCtx?.env ?? {};
-
-    // Merge variables from request context (app-level middleware) with loader-specific variables
-    // requestCtx.var is the shared variables object from the handler
-    const variables: Record<string, any> = { ...requestCtx?.var };
-
-    // Execute middleware for auth checks, headers, cookies
-    // Headers/cookies set on ctx.res will be merged into the final response
-    if (registered.middleware.length > 0 && requestCtx?.res) {
-      const { executeServerActionMiddleware } = await import(
-        "./router/middleware.js"
-      );
-      await executeServerActionMiddleware(
-        registered.middleware,
-        actionRequest,
-        env,
-        params,
-        variables,
-        requestCtx.res
-      );
-    }
-
-    // Build context using createHandlerContext for consistency with route handlers
-    // Variables are now accessed from request context via getRequestContext()
-    const { createHandlerContext } = await import("./router/handler-context.js");
-    const baseCtx = createHandlerContext(
-      params,
-      actionRequest,
-      actionUrl.searchParams,
-      actionUrl.pathname,
-      actionUrl,
-      env
-    );
-
-    // Extend with server action specific properties
-    const ctx: any = {
-      ...baseCtx,
-      method: "POST",
-      formData,
-    };
-
-    // Execute and return result
-    return registered.fn(ctx);
+    registerFetchableLoader(loaderId, fn, middleware, true);
   }
 
-  // Return a plain object with action for form-based fetching.
-  // loaderAction has "use server" so RSC Flight serializes it natively as a server action reference.
   return {
     __brand: "loader",
     $$id: loaderId,
-    action: loaderAction,
   };
 }

package/src/loader.ts

@@ -2,10 +2,15 @@
  * rsc-router/loader (client version)
  *
  * Client-only stub for createLoader. Returns a minimal loader definition
- * that can be passed to hooks like useLoader. The actual loader function
- * is not included - it only exists on the server.
+ * ({ __brand, $$id }) that can be passed to hooks like useLoader.
+ * The actual loader function is not included -- it only exists on the server.
  *
- * The $$id is injected by the Vite exposeLoaderId plugin.
+ * For export-only loader files, the Vite plugin replaces the entire file with
+ * object literals (bypassing this function). Those stubs only contain
+ * { __brand, $$id }.
+ * This function only runs when loaders are in mixed files (not export-only).
+ *
+ * The $$id is injected by the Vite exposeInternalIds plugin.
  */
 
 import type {
@@ -16,32 +21,44 @@ import type {
 
 // Overload 1: With function only (not fetchable)
 export function createLoader<T>(
-  fn: LoaderFn<T, Record<string, string | undefined>, any>
+  fn: LoaderFn<T, Record<string, string | undefined>, any>,
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
 
 // Overload 2: Fetchable with `true` (no middleware)
 export function createLoader<T>(
   fn: LoaderFn<T, Record<string, string | undefined>, any>,
-  fetchable: true
+  fetchable: true,
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
 
 // Overload 3: Fetchable with middleware options
 export function createLoader<T>(
   fn: LoaderFn<T, Record<string, string | undefined>, any>,
-  options: FetchableLoaderOptions
+  options: FetchableLoaderOptions,
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
 
 // Implementation - client stub that just returns the loader definition
 // The $$id parameter is injected by Vite plugin, not user-provided
+//
+// NOTE: For export-only loader files, the Vite plugin replaces the entire
+// file with object literals (bypassing this function). This function only
+// runs when loaders are in mixed files (not export-only).
 export function createLoader<T>(
   _fn: LoaderFn<T, Record<string, string | undefined>, any>,
   _fetchable?: true | FetchableLoaderOptions,
-  __injectedId?: string
+  __injectedId?: string,
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>> {
-  // Client only needs the $$id for identification
-  // The actual loader function is only used on the server
+  const loaderId = __injectedId || "";
+
+  if (!loaderId && process.env.NODE_ENV === "development") {
+    throw new Error(
+      "[rsc-router] Loader is missing $$id. " +
+        "Make sure the exposeInternalIds Vite plugin is enabled and " +
+        "the loader is exported with: export const MyLoader = createLoader(...)",
+    );
+  }
+
   return {
     __brand: "loader",
-    $$id: __injectedId || "",
+    $$id: loaderId,
   };
 }

package/src/network-error-thrower.tsx

@@ -16,6 +16,8 @@ interface NetworkErrorThrowerProps {
  * 1. Errors must be thrown during React's render phase to be caught by error boundaries
  * 2. The error occurs in async code (fetch), so we need to propagate it to React's render
  */
-export function NetworkErrorThrower({ error }: NetworkErrorThrowerProps): ReactNode {
+export function NetworkErrorThrower({
+  error,
+}: NetworkErrorThrowerProps): ReactNode {
   throw error;
 }

package/src/outlet-context.ts

@@ -1,4 +1,4 @@
-import { Context, createContext, type ReactNode } from "react";
+import { type Context, createContext, type ReactNode } from "react";
 import type { ResolvedSegment } from "./types";
 
 export interface OutletContextValue {

package/src/outlet-provider.tsx

@@ -0,0 +1,45 @@
+"use client";
+
+import { useContext, useMemo, type ReactNode } from "react";
+import { OutletContext, type OutletContextValue } from "./outlet-context.js";
+import type { ResolvedSegment } from "./types.js";
+
+/**
+ * Provider for outlet content - used internally by renderSegments
+ *
+ * Stores a reference to parent context so useLoader can walk up the chain
+ * to find loader data from parent layouts. If this segment defines a loading
+ * component, Outlet will wrap content with Suspense using that as fallback.
+ */
+export function OutletProvider({
+  content,
+  parallel,
+  segment,
+  loaderData,
+  children,
+}: {
+  content: ReactNode;
+  parallel?: ResolvedSegment[];
+  segment?: ResolvedSegment;
+  loaderData?: Record<string, any>;
+  children: ReactNode;
+}): ReactNode {
+  // Get parent context to enable walking up the chain for loader lookups
+  const parentContext = useContext(OutletContext);
+
+  const value = useMemo(
+    () => ({
+      content,
+      parallel,
+      segment,
+      loaderData,
+      parent: parentContext,
+      loading: segment?.loading,
+    }),
+    [content, parallel, segment, loaderData, parentContext],
+  );
+
+  return (
+    <OutletContext.Provider value={value}>{children}</OutletContext.Provider>
+  );
+}

package/src/prerender/param-hash.ts

@@ -17,8 +17,10 @@ export function hashParams(params: Record<string, string>): string {
   const entries = Object.entries(params);
   if (entries.length === 0) return "_";
 
-  const sorted = entries.sort(([a], [b]) => a.localeCompare(b));
-  const str = sorted.map(([k, v]) => `${k}=${v}`).join("&");
+  const sorted = entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  const str = sorted
+    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+    .join("&");
   return djb2Hex(str);
 }
 

package/src/prerender/store.ts

@@ -1,12 +1,17 @@
 /**
  * Prerender Store
  *
- * Reads pre-rendered segment data injected into the worker bundle at build time.
- * The data is stored as globalThis.__PRERENDER_DATA, a JSON object keyed by
- * "<routeName>/<paramHash>".
+ * Reads pre-rendered segment data from the worker bundle at build time.
+ * The manifest module is lazily loaded via globalThis.__loadPrerenderManifestModule,
+ * a function injected into the RSC entry that returns the manifest module
+ * containing a key-to-specifier map and a `loadPrerenderAsset` function
+ * that anchors import() resolution relative to the manifest file.
  */
 
-import type { SerializedSegmentData, SegmentHandleData } from "../cache/types.js";
+import type {
+  SerializedSegmentData,
+  SegmentHandleData,
+} from "../cache/types.js";
 
 export interface PrerenderEntry {
   segments: SerializedSegmentData[];
@@ -14,27 +19,168 @@ export interface PrerenderEntry {
 }
 
 export interface PrerenderStore {
-  get(routeName: string, paramHash: string): PrerenderEntry | null;
+  get(
+    routeName: string,
+    paramHash: string,
+    meta?: { pathname: string; isPassthroughRoute?: boolean },
+  ): PrerenderEntry | null | Promise<PrerenderEntry | null>;
+}
+
+export interface StaticEntry {
+  encoded: string;
+  handles: Record<string, unknown[]>;
+}
+
+export interface StaticStore {
+  get(handlerId: string): Promise<StaticEntry | null>;
+}
+
+interface PrerenderManifestModule {
+  default: Record<string, string>;
+  loadPrerenderAsset: (
+    specifier: string,
+  ) => Promise<{ default: PrerenderEntry }>;
 }
 
 declare global {
-  // Injected by closeBundle post-processing
+  // Injected by closeBundle post-processing: lazy loader for the prerender
+  // manifest module. The module exports a key→specifier map and a
+  // loadPrerenderAsset function that anchors import() relative to the manifest.
+  // eslint-disable-next-line no-var
+  var __loadPrerenderManifestModule:
+    | (() => Promise<PrerenderManifestModule>)
+    | undefined;
+  // Injected by closeBundle post-processing: map of handlerId -> () => import("./assets/__st-*.js")
+  // Asset default export is either a string (no handles) or { encoded, handles } object.
   // eslint-disable-next-line no-var
-  var __PRERENDER_DATA: Record<string, PrerenderEntry> | undefined;
+  var __STATIC_MANIFEST:
+    | Record<string, () => Promise<{ default: string | StaticEntry }>>
+    | undefined;
+  // Injected by virtual module in dev mode for on-demand prerender
+  // eslint-disable-next-line no-var
+  var __PRERENDER_DEV_URL: string | undefined;
 }
 
 /**
- * Create a prerender store backed by globalThis.__PRERENDER_DATA.
- * Returns null if no prerender data is available (dev mode or no prerendered routes).
+ * Create a dev-mode prerender store that fetches on-demand from the
+ * Vite dev server's /__rsc_prerender endpoint (runs in Node.js where
+ * node:fs works, unlike workerd).
+ */
+export function createDevPrerenderStore(devUrl: string): PrerenderStore {
+  return {
+    async get(routeName, paramHash, meta) {
+      if (!meta?.pathname) return null;
+      const isIntercept = paramHash.endsWith("/i");
+      let url = `${devUrl}/__rsc_prerender?pathname=${encodeURIComponent(meta.pathname)}&routeName=${encodeURIComponent(routeName)}`;
+      if (isIntercept) url += "&intercept=1";
+      if (meta.isPassthroughRoute) url += "&passthrough=1";
+      try {
+        const res = await fetch(url);
+        if (!res.ok) return null;
+        return res.json();
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+/**
+ * Create a prerender store.
+ * Dev mode: on-demand fetch from Vite dev server (node:fs works there).
+ * Production: backed by globalThis.__loadPrerenderManifestModule which lazily
+ * loads the manifest module on first access.
+ * Returns null if no prerender data is available.
  */
 export function createPrerenderStore(): PrerenderStore | null {
-  const data = globalThis.__PRERENDER_DATA;
-  if (!data || Object.keys(data).length === 0) return null;
+  if (globalThis.__PRERENDER_DEV_URL) {
+    return createDevPrerenderStore(globalThis.__PRERENDER_DEV_URL);
+  }
+  if (!globalThis.__loadPrerenderManifestModule) return null;
+
+  const cache = new Map<string, Promise<PrerenderEntry | null>>();
+  let manifestModulePromise: Promise<PrerenderManifestModule | null> | null =
+    null;
+
+  function loadManifestModule(): Promise<PrerenderManifestModule | null> {
+    if (!manifestModulePromise) {
+      manifestModulePromise = globalThis.__loadPrerenderManifestModule!().catch(
+        () => null,
+      );
+    }
+    return manifestModulePromise;
+  }
 
   return {
-    get(routeName: string, paramHash: string): PrerenderEntry | null {
+    get(routeName: string, paramHash: string): Promise<PrerenderEntry | null> {
       const key = `${routeName}/${paramHash}`;
-      return data[key] ?? null;
+      const cached = cache.get(key);
+      if (cached) return cached;
+
+      const promise = loadManifestModule().then((mod) => {
+        if (!mod) return null;
+        const specifier = mod.default[key];
+        if (!specifier) return null;
+        // Let asset load errors propagate — a missing/corrupted artifact
+        // for a key that exists in the manifest is a build/deploy error
+        // and should surface as a 500, not be silently swallowed as null
+        // (which the handler stub would misreport as a 404).
+        return mod.loadPrerenderAsset(specifier).then((asset) => asset.default);
+      });
+      cache.set(key, promise);
+      return promise;
+    },
+  };
+}
+
+/**
+ * Load the prerender manifest index for test introspection.
+ * Returns the key→specifier map or null if unavailable.
+ */
+export async function loadPrerenderManifestIndex(): Promise<Record<
+  string,
+  string
+> | null> {
+  if (!globalThis.__loadPrerenderManifestModule) return null;
+  try {
+    const mod = await globalThis.__loadPrerenderManifestModule();
+    return mod.default;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Create a static segment store.
+ * Production only: backed by globalThis.__STATIC_MANIFEST injected at build time.
+ * Returns null if no static data is available (dev mode or no Static handlers).
+ */
+export function createStaticStore(): StaticStore | null {
+  const manifest = globalThis.__STATIC_MANIFEST;
+  if (!manifest || Object.keys(manifest).length === 0) return null;
+
+  const cache = new Map<string, Promise<StaticEntry | null>>();
+
+  return {
+    get(handlerId: string): Promise<StaticEntry | null> {
+      const cached = cache.get(handlerId);
+      if (cached) return cached;
+
+      const importFn = manifest[handlerId];
+      if (!importFn) return Promise.resolve(null);
+
+      const promise = importFn()
+        .then((mod) => {
+          const val = mod.default;
+          // Normalize: string-only (no handles) or { encoded, handles }
+          if (typeof val === "string") {
+            return { encoded: val, handles: {} } as StaticEntry;
+          }
+          return val as StaticEntry;
+        })
+        .catch(() => null);
+      cache.set(handlerId, promise);
+      return promise;
     },
   };
 }