@rangojs/router 0.0.0-experimental.eb0645d3 → 0.0.0-experimental.f1468e3c

package/src/route-types.ts

@@ -5,47 +5,43 @@
  */
 
 /**
- * Branded return types for route helpers
+ * Brand for UrlPatterns nominal typing (see pattern-types.ts). The route-item
+ * types below are discriminated by their `type` literal, so they carry no brand.
  */
-export declare const LayoutBrand: unique symbol;
-export declare const RouteBrand: unique symbol;
-export declare const ParallelBrand: unique symbol;
-export declare const InterceptBrand: unique symbol;
-export declare const MiddlewareBrand: unique symbol;
-export declare const RevalidateBrand: unique symbol;
-export declare const LoaderBrand: unique symbol;
-export declare const LoadingBrand: unique symbol;
-export declare const ErrorBoundaryBrand: unique symbol;
-export declare const NotFoundBoundaryBrand: unique symbol;
-export declare const WhenBrand: unique symbol;
-export declare const CacheBrand: unique symbol;
-export declare const TransitionBrand: unique symbol;
-export declare const IncludeBrand: unique symbol;
 export declare const UrlPatternsBrand: unique symbol;
 
 export type LayoutItem = {
   name: string;
   type: "layout";
   uses?: AllUseItems[];
-  [LayoutBrand]: void;
 };
 
 /**
- * Typed layout item that carries child routes as phantom type
- * Used for type inference in urls() API
+ * Phantom inference fields attached to wrapper items (layout/cache/transition)
+ * so the urls() type extractor can read their child routes/responses. The fields
+ * never exist at runtime.
  */
-export type TypedLayoutItem<
+type WithChildren<
+  TBase,
   TChildRoutes extends Record<string, any> = Record<string, string>,
   TChildResponses extends Record<string, unknown> = Record<string, unknown>,
-> = LayoutItem & {
+> = TBase & {
   readonly __childRoutes?: TChildRoutes;
   readonly __childResponses?: TChildResponses;
 };
+
+/**
+ * Typed layout item that carries child routes as phantom type
+ * Used for type inference in urls() API
+ */
+export type TypedLayoutItem<
+  TChildRoutes extends Record<string, any> = Record<string, string>,
+  TChildResponses extends Record<string, unknown> = Record<string, unknown>,
+> = WithChildren<LayoutItem, TChildRoutes, TChildResponses>;
 export type RouteItem = {
   name: string;
   type: "route";
   uses?: AllUseItems[];
-  [RouteBrand]: void;
 };
 
 /**
@@ -67,64 +63,49 @@ export type ParallelItem = {
   name: string;
   type: "parallel";
   uses?: ParallelUseItem[];
-  [ParallelBrand]: void;
 };
 export type InterceptItem = {
   name: string;
   type: "intercept";
   uses?: InterceptUseItem[];
-  [InterceptBrand]: void;
 };
 export type LoaderItem = {
   name: string;
   type: "loader";
   uses?: LoaderUseItem[];
-  [LoaderBrand]: void;
 };
 export type MiddlewareItem = {
   name: string;
   type: "middleware";
   uses?: AllUseItems[];
-  [MiddlewareBrand]: void;
 };
 export type RevalidateItem = {
   name: string;
   type: "revalidate";
   uses?: AllUseItems[];
-  [RevalidateBrand]: void;
 };
 export type LoadingItem = {
   name: string;
   type: "loading";
-  [LoadingBrand]: void;
 };
 export type ErrorBoundaryItem = {
   name: string;
   type: "errorBoundary";
   uses?: AllUseItems[];
-  [ErrorBoundaryBrand]: void;
 };
 export type NotFoundBoundaryItem = {
   name: string;
   type: "notFoundBoundary";
   uses?: AllUseItems[];
-  [NotFoundBoundaryBrand]: void;
-};
-export type WhenItem = {
-  name: string;
-  type: "when";
-  [WhenBrand]: void;
 };
 export type CacheItem = {
   name: string;
   type: "cache";
   uses?: AllUseItems[];
-  [CacheBrand]: void;
 };
 export type TransitionItem = {
   name: string;
   type: "transition";
-  [TransitionBrand]: void;
 };
 
 /**
@@ -134,10 +115,7 @@ export type TransitionItem = {
 export type TypedTransitionItem<
   TChildRoutes extends Record<string, any> = Record<string, string>,
   TChildResponses extends Record<string, unknown> = Record<string, unknown>,
-> = TransitionItem & {
-  readonly __childRoutes?: TChildRoutes;
-  readonly __childResponses?: TChildResponses;
-};
+> = WithChildren<TransitionItem, TChildRoutes, TChildResponses>;
 
 /**
  * Typed cache item that carries child routes as phantom type
@@ -146,10 +124,7 @@ export type TypedTransitionItem<
 export type TypedCacheItem<
   TChildRoutes extends Record<string, any> = Record<string, string>,
   TChildResponses extends Record<string, unknown> = Record<string, unknown>,
-> = CacheItem & {
-  readonly __childRoutes?: TChildRoutes;
-  readonly __childResponses?: TChildResponses;
-};
+> = WithChildren<CacheItem, TChildRoutes, TChildResponses>;
 
 /**
  * Include item for URL pattern composition (used by urls() API)
@@ -184,7 +159,6 @@ export type IncludeItem = {
      */
     includeScope?: string;
   };
-  [IncludeBrand]: void;
 };
 
 /**
@@ -253,7 +227,6 @@ export type InterceptUseItem =
   | NotFoundBoundaryItem
   | LayoutItem
   | RouteItem
-  | WhenItem
   | TransitionItem;
 export type LoaderUseItem = RevalidateItem | CacheItem;
 

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

@@ -7,6 +7,7 @@
  */
 
 import type { EntryData } from "../server/context.js";
+import type { NegotiateVariant } from "../build/route-trie.js";
 import type { CollectedMiddleware } from "./middleware-types.js";
 import { collectRouteMiddleware } from "./middleware.js";
 import { loadManifest } from "./manifest.js";
@@ -14,7 +15,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 +23,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 +70,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__";
 
 /**
@@ -85,15 +82,10 @@ export const RSC_RESPONSE_TYPE = "__rsc__";
  * candidate serves that type. Wildcards match the first candidate.
  * Falls back to the first candidate if nothing matches.
  */
-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 }
-  >();
+export function pickNegotiateVariant<
+  T extends { routeKey: string; responseType: string },
+>(acceptEntries: AcceptEntry[], candidates: T[]): T {
+  const byCandidateMime = new Map<string, T>();
   for (const c of candidates) {
     const mime =
       c.responseType === RSC_RESPONSE_TYPE
@@ -106,9 +98,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,10 +109,52 @@ export function pickNegotiateVariant(
     const match = byCandidateMime.get(entry.mime);
     if (match) return match;
   }
-  // No match -- use first candidate as default
   return candidates[0]!;
 }
 
+/**
+ * Re-key params from the primary leaf's names to a winning variant's names.
+ *
+ * The trie match builds `params` positionally under the primary leaf's pa, so
+ * `/widgets/:id` matched as the primary yields `{ id }` even when the winning
+ * `/widgets/:file` response variant expects `{ file }`. Both share the same trie
+ * terminal, so they bind the same number of positional named params; we zip the
+ * variant's pa against the named values in insertion order (which is the
+ * primary's pa order). The wildcard key (`*`) is positional-independent and left
+ * untouched.
+ *
+ * Mutates `params` in place. No-op when `variantPa` is absent, when names already
+ * match (the common case), or when the positional count diverges (defensive:
+ * never corrupt params by zipping mismatched lengths).
+ */
+export function rekeyParamsForVariant(
+  params: Record<string, string>,
+  variantPa: string[] | undefined,
+): void {
+  if (!variantPa || variantPa.length === 0) return;
+
+  const namedKeys: string[] = [];
+  for (const key in params) {
+    if (key !== "*") namedKeys.push(key);
+  }
+  if (namedKeys.length !== variantPa.length) return;
+
+  let identical = true;
+  for (let i = 0; i < variantPa.length; i++) {
+    if (namedKeys[i] !== variantPa[i]) {
+      identical = false;
+      break;
+    }
+  }
+  if (identical) return;
+
+  const values = namedKeys.map((k) => params[k]!);
+  for (const key of namedKeys) delete params[key];
+  for (let i = 0; i < variantPa.length; i++) {
+    params[variantPa[i]!] = values[i]!;
+  }
+}
+
 /**
  * Result of content negotiation for a route with negotiate variants.
  */
@@ -135,8 +167,8 @@ export interface NegotiationResult {
   manifestEntry: EntryData;
   /** Route middleware for the winning variant */
   routeMiddleware: CollectedMiddleware[];
-  /** Always true — negotiation occurred */
-  negotiated: true;
+  /** True when negotiation selected a variant; false for a plain response route. */
+  negotiated: boolean;
 }
 
 /**
@@ -155,14 +187,28 @@ export async function negotiateRoute(
 ): Promise<NegotiationResult | null> {
   const { matched, manifestEntry, routeMiddleware, responseType } = snapshot;
   if (!matched.negotiateVariants || matched.negotiateVariants.length === 0) {
+    // No variants: a plain response route still yields a result (negotiated:false)
+    // so callers don't re-derive it; RSC routes (no responseType/handler) -> null.
+    const handler =
+      manifestEntry.type === "route" ? manifestEntry.handler : undefined;
+    if (responseType && handler) {
+      return {
+        responseType,
+        handler: handler as Function,
+        manifestEntry,
+        routeMiddleware,
+        negotiated: false,
+      };
+    }
     return null;
   }
 
   const acceptEntries = parseAcceptTypes(request.headers.get("accept") || "");
 
-  // Build candidate list preserving definition order.
-  const variants = matched.negotiateVariants;
-  let candidates: Array<{ routeKey: string; responseType: string }>;
+  // Variants carry the variant's own pa (positional param names); the synthetic
+  // primary/RSC candidates have none (their params are already keyed correctly).
+  const variants = matched.negotiateVariants as NegotiateVariant[];
+  let candidates: NegotiateVariant[];
   if (responseType) {
     candidates = [...variants, { routeKey: matched.routeKey, responseType }];
   } else {
@@ -177,12 +223,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,
@@ -192,8 +236,12 @@ export async function negotiateRoute(
       negotiated: true,
     };
   }
-
-  // Different variant won — load its manifest entry
+  // The trie extracted params under the PRIMARY leaf's pa, but the winning
+  // variant's handler is keyed by the variant's own param names. Re-key in place
+  // so plan.route.params (and the variant middleware collected just below) see
+  // the variant's names. No-op when the variant has no pa or shares the primary's
+  // names (the common case).
+  rekeyParamsForVariant(matched.params, variant.pa);
   const negotiateEntry = await loadManifest(
     matched.entry,
     variant.routeKey,

package/src/router/error-handling.ts

@@ -1,7 +1,7 @@
 /**
  * Router Error Handling Utilities
  *
- * Error boundary and not-found boundary handling for RSC Router.
+ * Error boundary and not-found boundary handling for Rango.
  * Also includes the shared invokeOnError utility for error callback invocation.
  */
 
@@ -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;
   }
 
@@ -165,6 +169,37 @@ export function findNearestNotFoundBoundary(
   return defaultNotFoundBoundary || null;
 }
 
+/**
+ * Normalize an error's cause into a Flight-serializable shape.
+ * ErrorInfo.cause crosses the RSC serialization boundary (via
+ * LoaderDataResult.error + error-segment fallback props); a non-serializable
+ * cause (function, class instance, circular object) would make Flight
+ * serialization throw and mask the original loader error.
+ */
+function normalizeCause(cause: unknown): unknown {
+  if (cause == null) return undefined;
+  const t = typeof cause;
+  if (t === "string" || t === "number" || t === "boolean") return cause;
+  // The whole body is guarded: even `instanceof`/clone can run user code (a
+  // Proxy trap, a throwing getter), and this helper must never throw —
+  // throwing here would mask the original loader error it exists to protect.
+  try {
+    if (cause instanceof Error) {
+      return { name: cause.name, message: cause.message, stack: cause.stack };
+    }
+    // Prefer preserving a serializable object/array intact (Flight uses
+    // structured-clone-like semantics); fall back to a string when the value
+    // is circular, host-bound, or otherwise non-serializable.
+    return structuredClone(cause);
+  } catch {
+    try {
+      return String(cause);
+    } catch {
+      return "[unstringifiable cause]";
+    }
+  }
+}
+
 /**
  * Create ErrorInfo from an error object
  * Sanitizes error details in production
@@ -182,7 +217,7 @@ export function createErrorInfo(
       name: error.name,
       code: (error as any).code,
       stack: isDev ? error.stack : undefined,
-      cause: isDev ? error.cause : undefined,
+      cause: isDev ? normalizeCause(error.cause) : undefined,
       segmentId,
       segmentType,
     };
@@ -207,22 +242,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 +291,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;
   }
 

package/src/router/find-match.ts

@@ -1,5 +1,5 @@
 import { tryTrieMatch } from "./trie-matching.js";
-import { getRouteTrie, getRouterTrie } from "../route-map-builder.js";
+import { getRouterTrie } from "../route-map-builder.js";
 import {
   findMatch as findRouteMatch,
   isLazyEvaluationNeeded,
@@ -8,6 +8,16 @@ import {
 import type { MetricsStore } from "../server/context";
 import type { RouteEntry } from "../types";
 
+// The single-entry cache is module-lifetime, keyed only on pathname, so the same
+// result object is handed to every same-pathname request. ctx.params aliases
+// this object, so handlers mutating it would corrupt the cache for later requests.
+// Clone params; entry/flags are read-only and shared safely.
+function cloneMatchResult<TEnv>(
+  r: RouteMatchResult<TEnv> | null,
+): RouteMatchResult<TEnv> | null {
+  return r ? { ...r, params: { ...r.params } } : null;
+}
+
 export interface FindMatchDeps<TEnv = any> {
   routesEntries: RouteEntry<TEnv>[];
   evaluateLazyEntry: (entry: RouteEntry<TEnv>) => void;
@@ -27,20 +37,14 @@ export function createFindMatch<TEnv = any>(
   let lastFindMatchPathname: string | null = null;
   let lastFindMatchResult: RouteMatchResult<TEnv> | null = null;
 
-  // Wrapper for findMatch that uses routesEntries
-  // Handles lazy evaluation by evaluating lazy entries on first match.
-  // Phase 1: try O(path_length) trie match.
-  // Phase 2: fall back to regex iteration.
   return function findMatch(
     pathname: string,
     ms?: MetricsStore,
   ): RouteMatchResult<TEnv> | null {
-    // Return cached result if same pathname (avoids double-match per request)
     if (lastFindMatchPathname === pathname) {
-      return lastFindMatchResult;
+      return cloneMatchResult(lastFindMatchResult);
     }
 
-    // Helper to push sub-metrics
     const pushMetric = ms
       ? (label: string, start: number) => {
           ms.metrics.push({
@@ -51,17 +55,15 @@ export function createFindMatch<TEnv = any>(
         }
       : undefined;
 
-    // Phase 1: Try trie match (O(path_length))
-    // Only use the per-router trie. The global trie merges routes from ALL
-    // routers and must not be used — in multi-router setups (host routing)
-    // overlapping paths like "/" would match the wrong app's route.
     const routeTrie = getRouterTrie(deps.routerId);
+    let trieMatched = false;
     if (routeTrie) {
       const trieStart = performance.now();
       const trieResult = tryTrieMatch(routeTrie, pathname);
       pushMetric?.("match:trie", trieStart);
 
       if (trieResult) {
+        trieMatched = true;
         // Find the RouteEntry that contains this route.
         // Multiple entries can share the same staticPrefix (e.g., several
         // include("/", patterns) calls all produce staticPrefix=""). Evaluate
@@ -83,12 +85,8 @@ export function createFindMatch<TEnv = any>(
           }
         }
 
-        // If no entry had the route in its routes map, use the first matching
-        // entry as fallback (handles main entry with inline routes not yet
-        // reflected in its routes object).
         if (!entry) entry = fallbackEntry;
 
-        // If entry not found (nested include not yet discovered), evaluate parent
         if (!entry) {
           const parent = deps.routesEntries.find(
             (e) =>
@@ -112,9 +110,7 @@ export function createFindMatch<TEnv = any>(
             entry,
             routeKey: trieResult.routeKey,
             params: trieResult.params,
-            optionalParams: new Set(trieResult.optionalParams || []),
             redirectTo: trieResult.redirectTo,
-            ancestry: trieResult.ancestry,
             ...(trieResult.pr ? { pr: true } : {}),
             ...(trieResult.pt ? { pt: true } : {}),
             ...(trieResult.responseType
@@ -125,17 +121,14 @@ export function createFindMatch<TEnv = any>(
               : {}),
             ...(trieResult.rscFirst ? { rscFirst: true } : {}),
           };
-          return lastFindMatchResult;
+          return cloneMatchResult(lastFindMatchResult);
         }
       }
     }
 
-    // Phase 2: Fall back to existing matching (regex iteration)
     const regexStart = performance.now();
     let result = findRouteMatch(pathname, deps.routesEntries);
 
-    // If we hit a lazy entry that needs evaluation, evaluate and retry.
-    // Cap iterations to prevent infinite loops from pathological nesting.
     const MAX_LAZY_ITERATIONS = 100;
     let iterations = 0;
     while (isLazyEvaluationNeeded(result)) {
@@ -153,8 +146,36 @@ export function createFindMatch<TEnv = any>(
     }
     pushMetric?.("match:regex-fallback", regexStart);
 
+    // The trie is the single source of truth and is built before findMatch in
+    // both dev (handler rebuild) and production (ensureRouterManifest). If the
+    // trie was present yet the regex fallback resolved a real match, the trie
+    // has a gap (e.g. a route shape it cannot represent) and dev/prod could
+    // diverge if the trie were ever absent. Surface it in dev; folded out in
+    // production builds.
+    //
+    // Suppress when the trie DID match (`trieMatched`): that path falls through
+    // to the regex fallback only on the first request to a not-yet-spliced lazy
+    // entry (e.g. a 2+-level nested include whose deeper parent has not been
+    // evaluated). The trie knew the route; runtime lazy discovery simply lagged.
+    // That is the supported lazy-include flow, not a trie gap, so warning on it
+    // is a false positive (it manufactures bug reports and erodes the signal).
+    if (
+      process.env.NODE_ENV !== "production" &&
+      routeTrie &&
+      !trieMatched &&
+      result &&
+      !isLazyEvaluationNeeded(result)
+    ) {
+      console.warn(
+        `[@rangojs/router] Route "${pathname}" resolved via the regex fallback ` +
+          `even though the route trie was present. The trie should be the single ` +
+          `matching source of truth; this indicates a trie gap. Please report this ` +
+          `with your route configuration.`,
+      );
+    }
+
     lastFindMatchPathname = pathname;
     lastFindMatchResult = result;
-    return result;
+    return cloneMatchResult(result);
   };
 }