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

package/src/index.rsc.ts

@@ -75,6 +75,13 @@ export type {
   ResolveStreamingContext,
 } from "./router.js";
 
+// Origin-check callback types (referenced by the RangoOptions.originCheck JSDoc)
+export type {
+  OriginCheckConfig,
+  OriginCheckContext,
+  OriginCheckPhase,
+} from "./rsc/origin-guard.js";
+
 // Server-side createLoader and redirect
 export {
   createLoader,
@@ -124,10 +131,15 @@ export {
   type BuildContext,
   type StaticBuildContext,
   type GetParamsContext,
+  type PrerenderPassthroughResult,
 } from "./prerender.js";
 
 // Static handler API
-export { Static, type StaticHandlerDefinition } from "./static-handler.js";
+export {
+  Static,
+  type StaticHandlerDefinition,
+  type StaticHandlerOptions,
+} from "./static-handler.js";
 
 // Django-style URL patterns (RSC/server context)
 export {
@@ -202,7 +214,13 @@ export { updateTag, revalidateTag } from "./cache/tag-invalidation.js";
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
 
 // Middleware context types
-export type { MiddlewareContext, CookieOptions } from "./router/middleware.js";
+export type {
+  MiddlewareContext,
+  CookieOptions,
+  // The function type of a middleware. Public so the documented "extract the
+  // middleware and unit-test it with runMiddleware" pattern has a nameable type.
+  MiddlewareFn,
+} from "./router/middleware.js";
 
 // Reverse type utilities for type-safe URL generation (Django-style URL reversal)
 export type {

package/src/internal-debug.ts

@@ -1,7 +1,5 @@
-// Internal debug gate. Enable with INTERNAL_RANGO_DEBUG=1 in the environment.
-// Uses a Vite define (__RANGO_DEBUG__) for compile-time injection so it works
-// in all runtimes including Cloudflare Workers where process.env is unavailable.
-// Falls back to process.env for non-Vite contexts (tests, direct Node usage).
+// Vite define for compile-time injection; falls back to process.env (tests, Node).
+// Works in all runtimes including Cloudflare Workers where process.env is unavailable.
 export const INTERNAL_RANGO_DEBUG: boolean =
   typeof __RANGO_DEBUG__ !== "undefined"
     ? __RANGO_DEBUG__

package/src/loader.rsc.ts

@@ -26,8 +26,7 @@ import { isUnderTestRunner } from "./runtime-env.js";
 
 export { getFetchableLoader };
 
-// Counter for runtime-fallback loader ids assigned only in a bare unit test
-// (no Vite plugin to inject one). Process-stable; never reached in a real build.
+// Runtime-fallback counter for bare unit tests (no Vite plugin); process-stable.
 let runtimeLoaderIdCounter = 0;
 
 // Overload 1: With function only (not fetchable)
@@ -54,17 +53,10 @@ export function createLoader<T>(
   // 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
   let loaderId = __injectedId || "";
 
-  // No build-injected id. Under a test runner: fall back to a synthetic id so the
-  // fn registers below and the loader is exercisable via runLoader(loaderHandle)
-  // (it recovers the fn from the registry by $$id). Otherwise (dev or a real
-  // build) it means an UNSUPPORTED shape (e.g. a namespace import
-  // `rango.createLoader(...)`) the plugin skipped — fail loud. The rich
-  // diagnostic stays behind the NODE_ENV check so production folds it away and
-  // ships the small throw. isUnderTestRunner() is runtime-safe. Mirrors createHandle.
+  // Under test runner, fall back to synthetic id (recovers fn from registry by $$id).
+  // Otherwise (dev or prod), missing id means unsupported shape — fail loud.
   if (!loaderId) {
     if (isUnderTestRunner()) {
       loaderId = `__rango_runtime_loader_${runtimeLoaderIdCounter++}`;
@@ -90,12 +82,9 @@ export function createLoader<T>(
     };
   }
 
-  // Fetchable loader - store fn in registry and return a serializable object
+  // Fetchable loader - store fn in registry and return a serializable object.
   const middleware: MiddlewareFn[] =
     fetchable === true ? [] : fetchable?.middleware || [];
-
-  // Register the function in the internal registry by $$id (server-side only)
-  // The loader fetch handler looks it up by $$id when load() is called from the client.
   if (fn && loaderId) {
     registerFetchableLoader(loaderId, fn, middleware, true);
   }

package/src/loader.ts

@@ -38,8 +38,7 @@ export function createLoader<T>(
   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
+// Implementation - client stub ($$id injected by Vite plugin, not user-provided)
 export function createLoader<T>(
   _fn: LoaderFn<T, Record<string, string | undefined>, any>,
   _fetchable?: true | FetchableLoaderOptions,
@@ -47,13 +46,8 @@ export function createLoader<T>(
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>> {
   const loaderId = __injectedId || "";
 
-  // Client/SSR build of createLoader. Under a test runner it needs no id
-  // (loaderId stays ""; the react-server build in loader.rsc.ts adds the runtime
-  // fallback for whole-router construction). Otherwise (dev or a real build) a
-  // missing id means an UNSUPPORTED shape the plugin skipped — fail loud rather
-  // than ship `$$id: ""` (which would make a client useLoader read the wrong
-  // key). The rich diagnostic stays behind the NODE_ENV check so production folds
-  // it away and ships the small throw. isUnderTestRunner() is runtime-safe.
+  // Under test runner, no id needed (loaderId stays ""; loader.rsc.ts provides fallback).
+  // Otherwise, missing id means unsupported shape — fail loud to avoid wrong key.
   if (!loaderId && !isUnderTestRunner()) {
     if (process.env.NODE_ENV !== "production") {
       throw missingInjectedIdError("Loader", "createLoader");

package/src/network-error-thrower.tsx

@@ -9,12 +9,7 @@ interface NetworkErrorThrowerProps {
 
 /**
  * Client component that throws a NetworkError during render.
- * Used to trigger the root error boundary when a network error occurs
- * during navigation or server actions.
- *
- * This must be a separate component because:
- * 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
+ * Errors thrown during render are caught by error boundaries; async errors are not.
  */
 export function NetworkErrorThrower({
   error,

package/src/outlet-provider.tsx

@@ -5,11 +5,7 @@ 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.
+ * Outlet content provider — stores parent context for useLoader chain walking.
  */
 export function OutletProvider({
   content,

package/src/prerender/param-hash.ts

@@ -1,18 +1,10 @@
 /**
  * Deterministic param hashing for prerender storage keys.
- *
- * Used at build time (child process) to generate filenames and at
- * runtime (worker) to look up pre-rendered data. Both environments
- * must produce identical hashes for the same params.
- *
- * Uses a simple DJB2-based hash that works in all JS environments
- * (Node.js, Cloudflare Workers, browsers) without crypto imports.
+ * Used at build time and runtime; both must produce identical hashes.
+ * DJB2-based; works in all JS environments without crypto imports.
  */
 
-/**
- * Compute a deterministic hash string from route params.
- * For static routes (no params), returns "_".
- */
+// For static routes (no params), returns "_".
 export function hashParams(params: Record<string, string>): string {
   const entries = Object.entries(params);
   if (entries.length === 0) return "_";
@@ -27,6 +19,13 @@ export function hashParams(params: Record<string, string>): string {
 /**
  * DJB2 hash returning an 8-char hex string.
  * Deterministic across all JS runtimes.
+ *
+ * 32-bit output: per-route collision probability hits ~50% near ~77k distinct
+ * param sets (birthday bound). The production store keys solely on
+ * routeName/paramHash and does not verify the canonical param string, so a
+ * collision serves the surviving entry for both param sets. Benign for typical
+ * catalogs; revisit (wider hash or stored-param verification) before
+ * pre-rendering hundreds of thousands of pages per route.
  */
 function djb2Hex(str: string): string {
   let hash = 5381;

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

@@ -442,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(