@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.1878aa49

package/src/prerender/store.ts

@@ -2,9 +2,10 @@
  * Prerender Store
  *
  * Reads pre-rendered segment data from the worker bundle at build time.
- * The data is stored as globalThis.__PRERENDER_MANIFEST, a map of
- * "<routeName>/<paramHash>" to dynamic import functions that resolve
- * individual prerender entry modules.
+ * 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 {
@@ -21,7 +22,7 @@ export interface PrerenderStore {
   get(
     routeName: string,
     paramHash: string,
-    meta?: { pathname: string },
+    meta?: { pathname: string; isPassthroughRoute?: boolean },
   ): PrerenderEntry | null | Promise<PrerenderEntry | null>;
 }
 
@@ -34,11 +35,20 @@ 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: map of key -> () => import("./assets/__pr-*.js")
+  // 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 __PRERENDER_MANIFEST:
-    | Record<string, () => Promise<{ default: PrerenderEntry }>>
+  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.
@@ -58,11 +68,12 @@ declare global {
  */
 export function createDevPrerenderStore(devUrl: string): PrerenderStore {
   return {
-    async get(_routeName, paramHash, meta) {
+    async get(routeName, paramHash, meta) {
       if (!meta?.pathname) return null;
       const isIntercept = paramHash.endsWith("/i");
-      let url = `${devUrl}/__rsc_prerender?pathname=${encodeURIComponent(meta.pathname)}`;
+      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;
@@ -77,17 +88,28 @@ export function createDevPrerenderStore(devUrl: string): PrerenderStore {
 /**
  * Create a prerender store.
  * Dev mode: on-demand fetch from Vite dev server (node:fs works there).
- * Production: backed by globalThis.__PRERENDER_MANIFEST injected at build time.
+ * 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 {
   if (globalThis.__PRERENDER_DEV_URL) {
     return createDevPrerenderStore(globalThis.__PRERENDER_DEV_URL);
   }
-  const manifest = globalThis.__PRERENDER_MANIFEST;
-  if (!manifest || Object.keys(manifest).length === 0) return null;
+  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): Promise<PrerenderEntry | null> {
@@ -95,18 +117,38 @@ export function createPrerenderStore(): PrerenderStore | null {
       const cached = cache.get(key);
       if (cached) return cached;
 
-      const loader = manifest[key];
-      if (!loader) return Promise.resolve(null);
-
-      const promise = loader()
-        .then((mod) => mod.default)
-        .catch(() => null);
+      const promise = loadManifestModule().then((mod) => {
+        if (!mod) return null;
+        const specifier = mod.default[key];
+        if (!specifier) return null;
+        return mod
+          .loadPrerenderAsset(specifier)
+          .then((asset) => asset.default)
+          .catch(() => null);
+      });
       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.

package/src/prerender.ts

@@ -34,10 +34,36 @@ import type {
 } from "./types.js";
 import type { Handle } from "./handle.js";
 import type { ContextVar } from "./context-var.js";
+import type { ReverseFunction } from "./reverse.js";
+import type { DefaultReverseRouteMap } from "./types/global-namespace.js";
 import { isCachedFunction } from "./cache/taint.js";
 
 // -- Named route resolution types -------------------------------------------
 
+/**
+ * Reverse function for build contexts (BuildContext, StaticBuildContext, GetParamsContext).
+ * Global names get full autocomplete and param validation from the generated route map.
+ * Local `.name` calls are accepted but not validated (the include() scope is unknown
+ * at the type level).
+ */
+type BuildReverseFunction = [DefaultReverseRouteMap] extends [
+  Record<string, string>,
+]
+  ? // No generated route map — permissive fallback
+    (
+      name: string,
+      params?: Record<string, string>,
+      search?: Record<string, unknown>,
+    ) => string
+  : // Generated route map available — typed globals + permissive locals
+    ReverseFunction<DefaultReverseRouteMap> & {
+      (
+        name: `.${string}`,
+        params?: Record<string, string>,
+        search?: Record<string, unknown>,
+      ): string;
+    };
+
 /**
  * Default route map for Prerender named route resolution.
  * Uses GeneratedRouteMap (from gen file) to avoid circular dependencies.
@@ -143,11 +169,14 @@ export interface BuildContext<TParams> {
   search: {};
 
   /** URL generation by route name. */
-  reverse: (
-    name: string,
-    params?: Record<string, string>,
-    search?: Record<string, unknown>,
-  ) => string;
+  reverse: BuildReverseFunction;
+
+  /**
+   * Signal that this param set should not produce a local prerender artifact.
+   * At runtime the handler runs live instead. Only valid on routes declared
+   * with `{ passthrough: true }`.
+   */
+  passthrough: () => PrerenderPassthroughResult;
 }
 
 /**
@@ -174,11 +203,7 @@ export interface StaticBuildContext {
   use: <T>(handle: Handle<T>) => (data: T) => void;
 
   /** URL generation by route name. */
-  reverse: (
-    name: string,
-    params?: Record<string, string>,
-    search?: Record<string, unknown>,
-  ) => string;
+  reverse: BuildReverseFunction;
 }
 
 /**
@@ -196,11 +221,7 @@ export interface GetParamsContext {
   };
 
   /** URL generation by route name. */
-  reverse: (
-    name: string,
-    params?: Record<string, string>,
-    search?: Record<string, unknown>,
-  ) => string;
+  reverse: BuildReverseFunction;
 }
 
 /**
@@ -216,7 +237,9 @@ export interface GetParamsContext {
 export type PrerenderPassthroughContext<
   TParams = {},
   TEnv = DefaultEnv,
-> = HandlerContext<TParams, TEnv>;
+> = HandlerContext<TParams, TEnv> & {
+  passthrough: () => PrerenderPassthroughResult;
+};
 
 export interface PrerenderHandlerDefinition<
   TParams extends Record<string, any> = any,
@@ -269,7 +292,10 @@ export function Prerender<
       ResolvePrerenderParams<T, TRouteMap>,
       TEnv
     >,
-  ) => ReactNode | Promise<ReactNode>,
+  ) =>
+    | ReactNode
+    | PrerenderPassthroughResult
+    | Promise<ReactNode | PrerenderPassthroughResult>,
   options: PrerenderOptions & { passthrough: true },
   __injectedId?: string,
 ): PrerenderHandlerDefinition<ResolvePrerenderParams<T, TRouteMap>>;
@@ -313,7 +339,10 @@ export function Prerender<
       ResolvePrerenderParams<T, TRouteMap>,
       TEnv
     >,
-  ) => ReactNode | Promise<ReactNode>,
+  ) =>
+    | ReactNode
+    | PrerenderPassthroughResult
+    | Promise<ReactNode | PrerenderPassthroughResult>,
   options: PrerenderOptions & { passthrough: true },
   __injectedId?: string,
 ): PrerenderHandlerDefinition<ResolvePrerenderParams<T, TRouteMap>>;
@@ -388,6 +417,35 @@ export function Prerender<TParams extends Record<string, any>>(
   };
 }
 
+// -- Passthrough sentinel ---------------------------------------------------
+
+/**
+ * Sentinel returned by `ctx.passthrough()` to signal that a specific param set
+ * should not produce a local prerender artifact. The build skips writing the
+ * entry; at runtime the handler runs live (requires `{ passthrough: true }`).
+ */
+export const PRERENDER_PASSTHROUGH: Readonly<{
+  __brand: "prerenderPassthrough";
+}> = Object.freeze({
+  __brand: "prerenderPassthrough" as const,
+});
+
+export type PrerenderPassthroughResult = typeof PRERENDER_PASSTHROUGH;
+
+/**
+ * Type guard to check if a value is the passthrough sentinel.
+ */
+export function isPrerenderPassthrough(
+  value: unknown,
+): value is PrerenderPassthroughResult {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "__brand" in value &&
+    (value as { __brand: unknown }).__brand === "prerenderPassthrough"
+  );
+}
+
 // -- Type guard -------------------------------------------------------------
 
 /**

package/src/reverse.ts

@@ -304,13 +304,17 @@ export function createReverse<TRoutes extends Record<string, string>>(
     let result = pattern;
     if (params) {
       // Replace :param placeholders with actual values
-      result = result.replace(/:([^/]+)/g, (_: string, key: string) => {
-        const value = params[key];
-        if (value === undefined) {
-          throw new Error(`Missing param "${key}" for route "${name}"`);
-        }
-        return encodeURIComponent(value);
-      });
+      // Strip constraint syntax: :param(a|b) -> use "param" as key
+      result = result.replace(
+        /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?\??/g,
+        (_, key) => {
+          const value = params[key];
+          if (value === undefined) {
+            throw new Error(`Missing param "${key}" for route "${name}"`);
+          }
+          return encodeURIComponent(value);
+        },
+      );
     }
 
     // Append search params as query string

package/src/root-error-boundary.tsx

@@ -109,6 +109,8 @@ function RootErrorFallback({
   error,
   reset,
 }: ClientErrorBoundaryFallbackProps): ReactNode {
+  const isDev = process.env.NODE_ENV !== "production";
+
   return (
     <div
       style={{
@@ -135,38 +137,40 @@ function RootErrorFallback({
       >
         An unexpected error occurred while processing your request.
       </p>
-      <div
-        style={{
-          background: "#fef2f2",
-          border: "1px solid #fecaca",
-          borderRadius: "0.5rem",
-          padding: "1rem",
-          marginBottom: "1rem",
-        }}
-      >
-        <p
+      {isDev && (
+        <div
           style={{
-            fontWeight: 600,
-            color: "#991b1b",
-            marginBottom: "0.5rem",
+            background: "#fef2f2",
+            border: "1px solid #fecaca",
+            borderRadius: "0.5rem",
+            padding: "1rem",
+            marginBottom: "1rem",
           }}
         >
-          {error.name}: {error.message}
-        </p>
-        {error.stack && (
-          <pre
+          <p
             style={{
-              fontSize: "0.75rem",
-              color: "#6b7280",
-              overflow: "auto",
-              whiteSpace: "pre-wrap",
-              wordBreak: "break-word",
+              fontWeight: 600,
+              color: "#991b1b",
+              marginBottom: "0.5rem",
             }}
           >
-            {error.stack}
-          </pre>
-        )}
-      </div>
+            {error.name}: {error.message}
+          </p>
+          {error.stack && (
+            <pre
+              style={{
+                fontSize: "0.75rem",
+                color: "#6b7280",
+                overflow: "auto",
+                whiteSpace: "pre-wrap",
+                wordBreak: "break-word",
+              }}
+            >
+              {error.stack}
+            </pre>
+          )}
+        </div>
+      )}
       <div style={{ display: "flex", gap: "1rem" }}>
         <button
           type="button"

package/src/route-definition/dsl-helpers.ts

@@ -16,7 +16,7 @@ import {
 } from "../server/context";
 import { invariant } from "../errors";
 import { isCachedFunction } from "../cache/taint.js";
-import { getCacheProfile } from "../cache/profile-registry.js";
+import { RSCRouterContext } from "../server/context";
 import { isStaticHandler } from "../static-handler.js";
 import RootLayout from "../server/root-layout";
 import type {
@@ -227,7 +227,9 @@ const cache: RouteHelpers<any, any>["cache"] = (
     children = undefined;
   } else if (typeof optionsOrChildren === "string") {
     // cache('profileName') or cache('profileName', () => [...])
-    const profile = getCacheProfile(optionsOrChildren);
+    // Resolve from context-scoped profiles (set per-router via HelperContext).
+    const ctxStore = RSCRouterContext.getStore();
+    const profile = ctxStore?.cacheProfiles?.[optionsOrChildren];
     invariant(
       profile,
       `cache("${optionsOrChildren}"): unknown cache profile. ` +
@@ -245,7 +247,9 @@ const cache: RouteHelpers<any, any>["cache"] = (
     children = maybeChildren;
   }
 
-  const name = `$${store.getNextIndex("cache")}`;
+  // Allocate a single index for this cache() call (used in all paths)
+  const cacheIndex = store.getNextIndex("cache");
+  const name = `$${cacheIndex}`;
   const cacheConfig = { options };
 
   // If no children, create an orphan cache entry (like orphan layouts)
@@ -262,7 +266,7 @@ const cache: RouteHelpers<any, any>["cache"] = (
 
     // Create orphan cache entry (like orphan layout)
     // Subsequent siblings in the same array will attach to this entry
-    const namespace = `${ctx.namespace}.${store.getNextIndex("cache")}`;
+    const namespace = `${ctx.namespace}.${cacheIndex}`;
     const cacheUrlPrefix = getUrlPrefix();
 
     const entry = {
@@ -278,7 +282,7 @@ const cache: RouteHelpers<any, any>["cache"] = (
       errorBoundary: [],
       notFoundBoundary: [],
       layout: [],
-      parallel: [],
+      parallel: {},
       intercept: [],
       loader: [],
       ...(cacheUrlPrefix ? { mountPath: cacheUrlPrefix } : {}),
@@ -297,8 +301,7 @@ const cache: RouteHelpers<any, any>["cache"] = (
   }
 
   // With children: create a cache entry (like layout with caching semantics)
-  const cacheNextIndex = store.getNextIndex("cache");
-  const namespace = `${ctx.namespace}.${cacheNextIndex}`;
+  const namespace = `${ctx.namespace}.${cacheIndex}`;
   const cacheShortCode = store.getShortCode("cache");
 
   const cacheUrlPrefix2 = getUrlPrefix();
@@ -317,7 +320,7 @@ const cache: RouteHelpers<any, any>["cache"] = (
     errorBoundary: [],
     notFoundBoundary: [],
     layout: [],
-    parallel: [],
+    parallel: {},
     intercept: [],
     loader: [],
     ...(cacheUrlPrefix2 ? { mountPath: cacheUrlPrefix2 } : {}),
@@ -390,6 +393,8 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
     "parallel() cannot be nested inside another parallel()",
   );
 
+  const slotNames = Object.keys(slots as Record<string, any>) as `@${string}`[];
+
   const namespace = `${ctx.namespace}.$${store.getNextIndex("parallel")}`;
 
   // Unwrap any static handler definitions in parallel slots
@@ -428,7 +433,7 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
     errorBoundary: [],
     notFoundBoundary: [],
     layout: [],
-    parallel: [],
+    parallel: {},
     intercept: [],
     loader: [],
     ...(parallelUrlPrefix ? { mountPath: parallelUrlPrefix } : {}),
@@ -451,7 +456,30 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
     );
   }
 
-  ctx.parent.parallel.push(entry);
+  for (const slotName of slotNames) {
+    const slotEntry = {
+      ...entry,
+      handler: { [slotName]: unwrappedSlots[slotName]! },
+      middleware: [...entry.middleware],
+      revalidate: [...entry.revalidate],
+      errorBoundary: [...entry.errorBoundary],
+      notFoundBoundary: [...entry.notFoundBoundary],
+      layout: [...entry.layout],
+      parallel: { ...entry.parallel },
+      intercept: [...entry.intercept],
+      loader: [...entry.loader],
+      ...(entry.staticHandlerIds?.[slotName]
+        ? {
+            isStaticPrerender: true as const,
+            staticHandlerIds: { [slotName]: entry.staticHandlerIds[slotName]! },
+          }
+        : {
+            isStaticPrerender: undefined,
+            staticHandlerIds: undefined,
+          }),
+    } satisfies EntryData;
+    ctx.parent.parallel[slotName] = slotEntry;
+  }
   return { name: namespace, type: "parallel" } as ParallelItem;
 };
 
@@ -684,7 +712,7 @@ const transitionFn = (
     errorBoundary: [],
     notFoundBoundary: [],
     layout: [],
-    parallel: [],
+    parallel: {},
     intercept: [],
     loader: [],
   } as EntryData;
@@ -731,7 +759,7 @@ const routeFn: RouteHelpers<any, any>["route"] = (name, handler, use) => {
     errorBoundary: [],
     notFoundBoundary: [],
     layout: [],
-    parallel: [],
+    parallel: {},
     intercept: [],
     loader: [],
   } satisfies EntryData;
@@ -788,7 +816,7 @@ const layout: RouteHelpers<any, any>["layout"] = (handler, use) => {
     revalidate: [],
     errorBoundary: [],
     notFoundBoundary: [],
-    parallel: [],
+    parallel: {},
     intercept: [],
     layout: [],
     loader: [],

package/src/route-definition/helpers-types.ts

@@ -228,11 +228,12 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
    * ])
    *
-   * // Access loader data in handlers via ctx.use()
-   * route("products.detail", async (ctx) => {
-   *   const product = await ctx.use(ProductLoader);
-   *   return <ProductPage product={product} />;
-   * })
+   * // Consume in client components with useLoader()
+   * // (preferred — cache-safe, always fresh)
+   * function ProductDetails() {
+   *   const { data } = useLoader(ProductLoader);
+   *   return <div>{data.name}</div>;
+   * }
    * ```
    * @param loaderDef - Loader created with createLoader()
    * @param use - Optional callback for loader-specific revalidation rules

package/src/route-definition/index.ts

@@ -1,6 +1,3 @@
-// Route definition
-export { route, type RouteDefinitionResult } from "./route-function.js";
-
 // Type definitions
 export type { RouteHelpers } from "./helpers-types.js";
 export type {

package/src/route-definition/redirect.ts

@@ -2,6 +2,7 @@ import type { LocationStateEntry } from "../browser/react/location-state-shared.
 import {
   requireRequestContext,
   getRequestContext,
+  _getRequestContext,
 } from "../server/request-context.js";
 
 /**
@@ -43,11 +44,16 @@ import {
 export function redirect(url: string, status?: number): Response;
 export function redirect(
   url: string,
-  options: { status?: number; state?: LocationStateEntry[] },
+  options: {
+    status?: number;
+    state?: LocationStateEntry | LocationStateEntry[];
+  },
 ): Response;
 export function redirect(
   url: string,
-  statusOrOptions?: number | { status?: number; state?: LocationStateEntry[] },
+  statusOrOptions?:
+    | number
+    | { status?: number; state?: LocationStateEntry | LocationStateEntry[] },
 ): Response {
   const status =
     typeof statusOrOptions === "number"
@@ -62,7 +68,14 @@ export function redirect(
 
     if (process.env.NODE_ENV !== "production") {
       const reqCtx = getRequestContext();
-      if (reqCtx && !reqCtx.url.searchParams.has("_rsc_partial")) {
+      // Warn only on true full-page SSR loads. SPA partial requests and server
+      // actions both deliver state through Flight payloads, so suppress for those.
+      if (
+        reqCtx &&
+        !reqCtx.originalUrl.searchParams.has("_rsc_partial") &&
+        !reqCtx.request.headers.has("rsc-action") &&
+        !reqCtx.originalUrl.searchParams.has("_rsc_action")
+      ) {
         console.warn(
           `[Router] redirect() with state during a full-page (SSR) request to "${url}". ` +
             "Location state is only delivered during SPA navigations and will be lost on this request.",
@@ -71,10 +84,17 @@ export function redirect(
     }
   }
 
+  // Auto-prefix root-relative URLs with basename for app-local redirects.
+  const bn = _getRequestContext()?._basename;
+  let resolvedUrl = url;
+  if (bn && url.startsWith("/") && !url.startsWith(bn + "/") && url !== bn) {
+    resolvedUrl = url === "/" ? bn : bn + url;
+  }
+
   return new Response(null, {
     status,
     headers: {
-      Location: url,
+      Location: resolvedUrl,
       "X-RSC-Redirect": "soft",
     },
   });