@rangojs/router 0.0.0-experimental.122 → 0.0.0-experimental.125

package/src/prerender/store.ts

@@ -1,11 +1,7 @@
 /**
- * Prerender Store
- *
- * 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.
+ * Prerender Store — reads pre-rendered segment data from the worker bundle.
+ * Manifest module (injected via globalThis.__loadPrerenderManifestModule)
+ * contains key-to-specifier map and loadPrerenderAsset for import() resolution.
  */
 
 import type { SerializedSegmentData } from "../cache/types.js";
@@ -101,13 +97,20 @@ export function createPrerenderStore(): PrerenderStore | null {
   if (!globalThis.__loadPrerenderManifestModule) return null;
 
   const cache = new Map<string, Promise<PrerenderEntry | null>>();
-  let manifestModulePromise: Promise<PrerenderManifestModule | null> | null =
-    null;
+  let manifestModulePromise: Promise<PrerenderManifestModule> | null = null;
 
-  function loadManifestModule(): Promise<PrerenderManifestModule | null> {
+  function loadManifestModule(): Promise<PrerenderManifestModule> {
     if (!manifestModulePromise) {
+      // Do not cache a failed manifest-module load: clear the memoized promise
+      // on rejection so the next get() retries, and let the error propagate
+      // (consistent with the per-asset load policy below) instead of caching a
+      // null for the isolate lifetime, which would silently degrade every
+      // prerendered route to a miss after one transient failure.
       manifestModulePromise = globalThis.__loadPrerenderManifestModule!().catch(
-        () => null,
+        (err) => {
+          manifestModulePromise = null;
+          throw err;
+        },
       );
     }
     return manifestModulePromise;
@@ -120,7 +123,6 @@ export function createPrerenderStore(): PrerenderStore | null {
       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
@@ -129,29 +131,20 @@ export function createPrerenderStore(): PrerenderStore | null {
         // (which the handler stub would misreport as a 404).
         return mod.loadPrerenderAsset(specifier).then((asset) => asset.default);
       });
-      cache.set(key, promise);
+      // Only memoize once the manifest module resolved: a manifest-load
+      // rejection must not poison the per-key cache, or the retry above is moot.
+      cache.set(
+        key,
+        promise.catch((err) => {
+          cache.delete(key);
+          throw err;
+        }),
+      );
       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

@@ -38,6 +38,7 @@ import type { ReverseFunction } from "./reverse.js";
 import type { DefaultReverseRouteMap } from "./types/global-namespace.js";
 import type { UseItems, HandlerUseItem } from "./route-types.js";
 import { isCachedFunction } from "./cache/taint.js";
+import { isUnderTestRunner } from "./runtime-env.js";
 
 // -- Named route resolution types -------------------------------------------
 
@@ -273,6 +274,11 @@ export interface PrerenderHandlerDefinition<
   use?: () => UseItems<HandlerUseItem>;
 }
 
+// Process-stable fallback id counter (mirrors createHandle / createLoader). Only
+// assigned in a bare unit test where the Vite plugin did not inject an id; never
+// fires in a real build (the plugin always injects).
+let runtimePrerenderIdCounter = 0;
+
 // -- Overloads --------------------------------------------------------------
 //
 // T accepts: named route string (global or .local) OR explicit param object.
@@ -376,12 +382,27 @@ export function Prerender<TParams extends Record<string, any>>(
     );
   }
 
-  if (!id) {
+  // Throw unless under a test runner. The plugin always injects $$id for a
+  // supported `export const` Prerender on every build, so a missing id means
+  // either no plugin (a bare test — fall back below) or an UNSUPPORTED shape the
+  // plugin silently skipped (dev OR a real build — fail loud; a synthetic id
+  // would degrade to a silent prerender miss). The message is already small (no
+  // stack-parsing diagnostic), so it ships as-is. isUnderTestRunner() is
+  // runtime-safe — never a bare `process.env` access.
+  if (!id && !isUnderTestRunner()) {
     throw new Error(
-      "[rango] Prerender: missing $$id. " +
-        "Ensure the exposeInternalIds Vite plugin is configured.",
+      "[rango] Prerender: missing $$id. Use `export const X = Prerender(...)` " +
+        "and ensure the exposeInternalIds Vite plugin is configured.",
     );
   }
+  // Under vitest with no plugin id: assign a process-stable runtime id so a
+  // whole-app router with Prerender routes constructs in a bare test (for
+  // dispatch / assertGeneratedRoutesMatch). Never reached in a real build (the
+  // throw above fires there); prerender storage/lookup keys on routeName +
+  // paramHash, never $$id (mirrors createHandle / createLoader).
+  if (!id) {
+    id = `__rango_runtime_prerender_${runtimePrerenderIdCounter++}`;
+  }
 
   return {
     __brand: "prerenderHandler" as const,
@@ -421,6 +442,40 @@ export function isPrerenderPassthrough(
   );
 }
 
+/**
+ * Detect whether any resolved segment carries the passthrough sentinel.
+ *
+ * A build handler signals passthrough by returning `ctx.passthrough()` (the
+ * PRERENDER_PASSTHROUGH sentinel), which lands on the segment's `component`.
+ * But when the route declares `loading()`, the handler result is deferred
+ * upstream (segment-resolution/fresh.ts), so `component` is a thenable resolving
+ * to the sentinel rather than the sentinel itself — a synchronous
+ * `isPrerenderPassthrough(component)` on the Promise returns false and the build
+ * bakes a corrupt artifact instead of deferring. Resolve thenables first.
+ *
+ * Rejections are swallowed here: a throwing build handler resurfaces during
+ * segment serialization, preserving the prior error-handling behavior.
+ */
+export async function detectPrerenderPassthrough(
+  segments: ReadonlyArray<{ component: unknown }>,
+): Promise<boolean> {
+  for (const seg of segments) {
+    let component: unknown = seg.component;
+    if (
+      component &&
+      typeof (component as { then?: unknown }).then === "function"
+    ) {
+      try {
+        component = await component;
+      } catch {
+        continue;
+      }
+    }
+    if (isPrerenderPassthrough(component)) return true;
+  }
+  return false;
+}
+
 // -- Type guards ------------------------------------------------------------
 
 /**

package/src/root-error-boundary.tsx

@@ -3,26 +3,17 @@
 import { Component, useState, type ReactNode } from "react";
 import type { ClientErrorBoundaryFallbackProps } from "./types.js";
 
-/**
- * Check if an error is a network-related error
- */
 function isNetworkError(error: Error): boolean {
   return error.name === "NetworkError";
 }
 
-/**
- * Network error fallback UI with retry functionality
- * Shows a connection-specific message and allows retrying via page refresh
- */
 function NetworkErrorFallback({
   error,
-  reset,
 }: ClientErrorBoundaryFallbackProps): ReactNode {
   const [isRetrying, setIsRetrying] = useState(false);
 
   const handleRetry = (): void => {
     setIsRetrying(true);
-    // Refresh the page to retry the request
     window.location.reload();
   };
 
@@ -42,7 +33,6 @@ function NetworkErrorFallback({
           marginBottom: "1rem",
         }}
       >
-        {/* Simple cloud with x icon using CSS */}
         <span style={{ color: "#9ca3af" }}>&#9729;</span>
       </div>
       <h1
@@ -101,10 +91,6 @@ function NetworkErrorFallback({
   );
 }
 
-/**
- * Default fallback UI for root error boundary
- * This is shown when an unhandled error bubbles up to the root
- */
 function RootErrorFallback({
   error,
   reset,
@@ -230,7 +216,6 @@ export class RootErrorBoundary extends Component<
   }
 
   componentDidMount(): void {
-    // Listen for popstate (back/forward navigation) to reset error state
     window.addEventListener("popstate", this.handlePopState);
   }
 
@@ -247,15 +232,13 @@ export class RootErrorBoundary extends Component<
   }
 
   componentDidUpdate(prevProps: { children: ReactNode }): void {
-    // Reset error state when children change (e.g., navigation)
-    // This allows the app to recover after navigation away from an errored route
+    // Reset error on children change (navigation).
     if (this.state.hasError && prevProps.children !== this.props.children) {
       this.setState({ hasError: false, error: null });
     }
   }
 
   handlePopState = (): void => {
-    // Reset error state on back/forward navigation
     if (this.state.hasError) {
       this.setState({ hasError: false, error: null });
     }
@@ -276,7 +259,6 @@ export class RootErrorBoundary extends Component<
         segmentType: "route" as const,
       };
 
-      // Use specialized fallback for network errors
       if (isNetworkError(this.state.error)) {
         return <NetworkErrorFallback error={errorInfo} reset={this.reset} />;
       }

package/src/route-content-wrapper.tsx

@@ -1,6 +1,6 @@
 "use client";
 import type { ReactNode } from "react";
-import { Suspense, use, useId } from "react";
+import { Suspense, use } from "react";
 import { invariant } from "./errors";
 import { OutletProvider } from "./outlet-provider.js";
 import type { ResolvedSegment } from "./types.js";
@@ -36,37 +36,6 @@ export function RouteContentWrapper({
   );
 }
 
-export function RouteContentWrapperCallback<T>({
-  resolve,
-  fallback,
-  children,
-}: {
-  resolve: Promise<T> | T;
-  fallback?: ReactNode;
-  children: (data: T) => ReactNode;
-}): ReactNode {
-  const id = useId();
-  invariant(children, "RouteContentWrapperCallback requires children");
-  invariant(
-    typeof children === "function",
-    "RouteContentWrapperCallback requires children to be a function",
-  );
-  invariant(
-    resolve !== undefined,
-    "RouteContentWrapperCallback requires resolve",
-  );
-  return (
-    <Suspense
-      fallback={fallback ?? null}
-      key={"route-content-suspense-callback-" + id}
-    >
-      <SuspenderCallback resolve={resolve} key={id}>
-        {children}
-      </SuspenderCallback>
-    </Suspense>
-  );
-}
-
 const Suspender = ({
   content,
 }: {
@@ -77,18 +46,6 @@ const Suspender = ({
   return use(content);
 };
 
-const SuspenderCallback = <T,>({
-  resolve,
-  children,
-}: {
-  resolve: Promise<T> | T;
-  children: (data: T) => ReactNode;
-}): ReactNode => {
-  return resolve instanceof Promise
-    ? children(use(resolve))
-    : children(resolve);
-};
-
 /**
  * LoaderBoundary - Client component that resolves loader promises and renders OutletProvider
  *

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

@@ -302,15 +302,15 @@ const when: RouteHelpers<any, any>["when"] = (fn) => {
  * Supports these call signatures:
  * - cache() - no args, uses app-level defaults (for loader caching)
  * - cache(() => [...]) - wraps children with app-level defaults
- * - cache('profileName') - uses a named cache profile
- * - cache('profileName', () => [...]) - named profile with children
  * - cache({ ttl: 60 }, () => [...]) - with explicit options
+ *
+ * Named cache profiles are applied via the `"use cache: <profile>"` directive,
+ * not a `cache("profileName")` form in the route tree.
  */
 const cache: RouteHelpers<any, any>["cache"] = (
   optionsOrChildren?:
     | PartialCacheOptions
     | false
-    | string
     | (() => UseItems<AllUseItems>),
   maybeChildren?: () => UseItems<AllUseItems>,
 ) => {
@@ -326,18 +326,6 @@ const cache: RouteHelpers<any, any>["cache"] = (
     // cache() - no args, use defaults
     options = {};
     children = undefined;
-  } else if (typeof optionsOrChildren === "string") {
-    // cache('profileName') or cache('profileName', () => [...])
-    // Resolve from context-scoped profiles (set per-router via HelperContext).
-    const ctxStore = RangoContext.getStore();
-    const profile = ctxStore?.cacheProfiles?.[optionsOrChildren];
-    invariant(
-      profile,
-      `cache("${optionsOrChildren}"): unknown cache profile. ` +
-        `Define it in createRouter({ cacheProfiles: { "${optionsOrChildren}": { ttl: ... } } }).`,
-    );
-    options = { ttl: profile.ttl, swr: profile.swr, tags: profile.tags };
-    children = maybeChildren;
   } else if (typeof optionsOrChildren === "function") {
     // cache(() => [...]) - use empty options (will use defaults)
     options = {};
@@ -393,10 +381,10 @@ const cache: RouteHelpers<any, any>["cache"] = (
     return { name: namespace, type: "cache" } as CacheItem;
   }
 
-  // Inside a loader() use() callback, only the direct form — cache()/cache(opts)/
-  // cache("profile") — writes cache config to the loader entry. The wrapper
-  // form creates a structural cache boundary with its own children scope, which
-  // has no effect on the loader and would silently no-op.
+  // Inside a loader() use() callback, only the direct form — cache()/cache(opts)
+  // — writes cache config to the loader entry. The wrapper form creates a
+  // structural cache boundary with its own children scope, which has no effect
+  // on the loader and would silently no-op.
   invariant(
     !(ctx.parent && (ctx.parent as any).type === "loader"),
     "cache() wrapper form is not valid inside loader() use(). Use cache({...}) without children to configure the loader's cache.",

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

@@ -441,10 +441,8 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
   cache: {
     (): CacheItem;
     (children: () => UseItems<AllUseItems>): CacheItem;
-    (profileName: string): CacheItem;
-    (profileName: string, use: () => UseItems<AllUseItems>): CacheItem;
     (
-      options: PartialCacheOptions | false,
+      options: PartialCacheOptions<TEnv> | false,
       use?: () => UseItems<AllUseItems>,
     ): CacheItem;
   };
@@ -497,6 +495,8 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    * @param children - Optional callback returning child routes to wrap
    */
   transition: {
+    (): TransitionItem;
+    (children: () => UseItems<AllUseItems>): TransitionItem;
     (config: TransitionConfig): TransitionItem;
     (
       config: TransitionConfig,

package/src/route-definition/redirect.ts

@@ -85,9 +85,19 @@ export function redirect(
   }
 
   // Auto-prefix root-relative URLs with basename for app-local redirects.
+  // Treat the URL as already-prefixed when the basename is followed by a path
+  // separator, a query, a fragment, or end-of-string, so "/admin?tab=x" and
+  // "/admin#frag" are not double-prefixed into "/admin/admin?tab=x".
   const bn = _getRequestContext()?._basename;
   let resolvedUrl = url;
-  if (bn && url.startsWith("/") && !url.startsWith(bn + "/") && url !== bn) {
+  if (
+    bn &&
+    url.startsWith("/") &&
+    url !== bn &&
+    !url.startsWith(bn + "/") &&
+    !url.startsWith(bn + "?") &&
+    !url.startsWith(bn + "#")
+  ) {
     resolvedUrl = url === "/" ? bn : bn + url;
   }
 

package/src/route-map-builder.ts

@@ -8,15 +8,10 @@
  * See docs/manifests.md for the full data flow.
  */
 
-// Singleton route map instance - populated incrementally as routes are encountered
 let globalRouteMap: Record<string, string> = {};
 
-// Cached complete manifest - includes all routes (including lazy includes)
-// Set from runtime cache or build-time import
 let cachedManifest: Record<string, string> | null = null;
 
-// Pre-computed route entries from build-time prefix tree leaf nodes.
-// Used by evaluateLazyEntry() to skip running the handler for route matching.
 let cachedPrecomputedEntries: Array<{
   staticPrefix: string;
   routes: Record<string, string>;
@@ -43,7 +38,6 @@ export function registerRouteMap(map: Record<string, string>): void {
  * @internal
  */
 export function getGlobalRouteMap(): Record<string, string> {
-  // Cached manifest is complete (includes lazy routes), so prefer it
   if (cachedManifest) {
     return cachedManifest;
   }
@@ -231,10 +225,6 @@ export function waitForManifestReady(): Promise<void> | null {
   return manifestReadyPromise;
 }
 
-// ============================================================================
-// Route Scope Registry
-// ============================================================================
-
 // Tracks whether each route is at root scope (no named include boundary above).
 // Used by dot-local reverse resolution to decide whether bare-name fallback
 // is allowed after scoped lookups are exhausted.
@@ -259,14 +249,8 @@ export function isRouteRootScoped(routeName: string): boolean | undefined {
   return rootScopeRoutes.get(routeName);
 }
 
-// ============================================================================
-// Search Schema Registry
-// ============================================================================
-
 import type { SearchSchema } from "./search-params.js";
 
-// Global search schema map: route name -> search schema descriptor.
-// Populated by path() when a search option is provided.
 const globalSearchSchemas: Map<string, SearchSchema> = new Map();
 
 export function registerSearchSchema(

package/src/router/basename.ts

@@ -0,0 +1,14 @@
+/**
+ * Normalize a router basename to its canonical form: a single leading slash,
+ * no trailing slash, and `undefined` for an empty or bare-"/" value.
+ *
+ * This is the single source of truth used by both createRouter() (so the RSC
+ * handler stores a canonical basename on the request context) and the testing
+ * primitives (so a consumer can pass the same un-normalized string their
+ * createRouter() accepts and observe the same redirect() prefixing).
+ */
+export function normalizeBasename(basename?: string): string | undefined {
+  if (!basename) return undefined;
+  const trimmed = basename.replace(/^\/+|\/+$/g, "");
+  return trimmed ? "/" + trimmed : undefined;
+}

package/src/router/content-negotiation.ts

@@ -14,7 +14,6 @@ import { traverseBack } from "./pattern-matching.js";
 import type { RouteMatchResult } from "./pattern-matching.js";
 import type { RouteSnapshot } from "./route-snapshot.js";
 
-// Response type -> MIME type used for Accept header matching
 export const RESPONSE_TYPE_MIME: Record<string, string> = {
   json: "application/json",
   text: "text/plain",
@@ -23,7 +22,6 @@ export const RESPONSE_TYPE_MIME: Record<string, string> = {
   md: "text/markdown",
 };
 
-// Reverse lookup: MIME type -> response type tag (e.g. "text/html" -> "html")
 export const MIME_RESPONSE_TYPE: Record<string, string> = Object.fromEntries(
   Object.entries(RESPONSE_TYPE_MIME).map(([tag, mime]) => [mime, tag]),
 );
@@ -71,12 +69,10 @@ export function parseAcceptTypes(accept: string): AcceptEntry[] {
     }
     entries.push({ mime, q, order: i });
   }
-  // Sort: highest q first, then lowest client order first (stable)
   entries.sort((a, b) => b.q - a.q || a.order - b.order);
   return entries;
 }
 
-// Sentinel response type for RSC routes in negotiation candidates
 export const RSC_RESPONSE_TYPE = "__rsc__";
 
 /**
@@ -89,7 +85,6 @@ export function pickNegotiateVariant(
   acceptEntries: AcceptEntry[],
   candidates: Array<{ routeKey: string; responseType: string }>,
 ): { routeKey: string; responseType: string } {
-  // Build a MIME -> candidate lookup for O(1) matching
   const byCandidateMime = new Map<
     string,
     { routeKey: string; responseType: string }
@@ -106,9 +101,7 @@ export function pickNegotiateVariant(
 
   for (const entry of acceptEntries) {
     if (entry.q === 0) continue;
-    // Wildcard matches first candidate
     if (entry.mime === "*/*") return candidates[0]!;
-    // Type wildcard (e.g. "text/*") -- match first candidate with that type
     if (entry.mime.endsWith("/*")) {
       const typePrefix = entry.mime.slice(0, entry.mime.indexOf("/"));
       for (const [mime, candidate] of byCandidateMime) {
@@ -119,7 +112,6 @@ export function pickNegotiateVariant(
     const match = byCandidateMime.get(entry.mime);
     if (match) return match;
   }
-  // No match -- use first candidate as default
   return candidates[0]!;
 }
 
@@ -173,7 +165,6 @@ export async function negotiateRoute(
 
   const acceptEntries = parseAcceptTypes(request.headers.get("accept") || "");
 
-  // Build candidate list preserving definition order.
   const variants = matched.negotiateVariants;
   let candidates: Array<{ routeKey: string; responseType: string }>;
   if (responseType) {
@@ -190,12 +181,10 @@ export async function negotiateRoute(
 
   const variant = pickNegotiateVariant(acceptEntries, candidates);
 
-  // RSC won negotiation
   if (variant.responseType === RSC_RESPONSE_TYPE) {
     return null;
   }
 
-  // Primary response-type won — use existing manifest entry and middleware
   if (responseType && variant.routeKey === matched.routeKey) {
     return {
       responseType,
@@ -205,8 +194,6 @@ export async function negotiateRoute(
       negotiated: true,
     };
   }
-
-  // Different variant won — load its manifest entry
   const negotiateEntry = await loadManifest(
     matched.entry,
     variant.routeKey,

package/src/router/error-handling.ts

@@ -117,16 +117,10 @@ export function findNearestErrorBoundary(
   let current: EntryData | null = entry;
 
   while (current) {
-    // Check if this entry has error boundaries defined
     if (current.errorBoundary && current.errorBoundary.length > 0) {
-      // Return the last error boundary (most recently defined takes precedence)
       return current.errorBoundary[current.errorBoundary.length - 1];
     }
 
-    // Check orphan layouts for error boundaries
-    // Orphan layouts are siblings that render alongside the main route chain
-    // They can define error boundaries that catch errors from routes in the same route group
-    // Check from first to last (first sibling takes precedence as the "outer" wrapper)
     if (current.layout && current.layout.length > 0) {
       for (const orphan of current.layout) {
         if (orphan.errorBoundary && orphan.errorBoundary.length > 0) {
@@ -153,11 +147,21 @@ export function findNearestNotFoundBoundary(
   let current: EntryData | null = entry;
 
   while (current) {
-    // Check if this entry has notFound boundaries defined
     if (current.notFoundBoundary && current.notFoundBoundary.length > 0) {
-      // Return the last notFound boundary (most recently defined takes precedence)
       return current.notFoundBoundary[current.notFoundBoundary.length - 1];
     }
+
+    // Check orphan layouts mirroring findNearestErrorBoundary: notFoundBoundary
+    // attaches identically (onto parent.notFoundBoundary), and an orphan layout
+    // (parent=null) is reachable only via this scan. First sibling is "outer".
+    if (current.layout && current.layout.length > 0) {
+      for (const orphan of current.layout) {
+        if (orphan.notFoundBoundary && orphan.notFoundBoundary.length > 0) {
+          return orphan.notFoundBoundary[orphan.notFoundBoundary.length - 1];
+        }
+      }
+    }
+
     current = current.parent;
   }
 
@@ -207,22 +211,17 @@ export function createErrorSegment(
   entry: EntryData,
   params: Record<string, string>,
 ): ResolvedSegment {
-  // Determine the component to render
   let component: ReactNode;
 
   if (typeof fallback === "function") {
-    // ErrorBoundaryHandler - call with error info
     const props: ErrorBoundaryFallbackProps = {
       error: errorInfo,
     };
     component = fallback(props);
   } else {
-    // Static ReactNode fallback
     component = fallback;
   }
 
-  // Error segment uses the same ID as the layout that has the error boundary
-  // The error boundary content replaces the layout's outlet content
   return {
     id: entry.shortCode,
     namespace: entry.id,
@@ -261,17 +260,14 @@ export function createNotFoundSegment(
   entry: EntryData,
   params: Record<string, string>,
 ): ResolvedSegment {
-  // Determine the component to render
   let component: ReactNode;
 
   if (typeof fallback === "function") {
-    // NotFoundBoundaryHandler - call with props
     const props: NotFoundBoundaryFallbackProps = {
       notFound: notFoundInfo,
     };
     component = fallback(props);
   } else {
-    // Static ReactNode fallback
     component = fallback;
   }