@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.140

package/src/router/trie-matching.ts

@@ -5,7 +5,12 @@
  * Falls back to null when no match is found (caller uses regex fallback).
  */
 
-import type { TrieNode, TrieLeaf } from "../build/route-trie.js";
+import type {
+  TrieNode,
+  TrieLeaf,
+  NegotiateVariant,
+} from "../build/route-trie.js";
+import { safeDecodeURIComponent } from "./url-params.js";
 
 export interface TrieMatchResult {
   /** Route name */
@@ -14,10 +19,6 @@ export interface TrieMatchResult {
   sp: string;
   /** Matched route params */
   params: Record<string, string>;
-  /** Optional param names (absent params have empty string value) */
-  optionalParams?: string[];
-  /** Ancestry shortCodes for layout pruning */
-  ancestry: string[];
   /** Redirect target if trailing slash requires it */
   redirectTo?: string;
   /** Route has pre-rendered data available */
@@ -27,7 +28,7 @@ export interface TrieMatchResult {
   /** Response type for non-RSC routes (json, text, image, any) */
   responseType?: string;
   /** Negotiate variants: response-type routes sharing this path */
-  negotiateVariants?: Array<{ routeKey: string; responseType: string }>;
+  negotiateVariants?: NegotiateVariant[];
   /** RSC-first: RSC route was defined before response-type variants */
   rscFirst?: true;
 }
@@ -42,25 +43,51 @@ export function tryTrieMatch(
 ): TrieMatchResult | null {
   if (!trie) return null;
 
-  // Split pathname into segments, filtering empty strings from leading/trailing slashes
-  const pathnameHasTrailingSlash = pathname.length > 1 && pathname.endsWith("/");
-  const normalizedPath = pathnameHasTrailingSlash ? pathname.slice(0, -1) : pathname;
+  const pathnameHasTrailingSlash =
+    pathname.length > 1 && pathname.endsWith("/");
+  const normalizedPath = pathnameHasTrailingSlash
+    ? pathname.slice(0, -1)
+    : pathname;
 
-  // Handle root path
   if (normalizedPath === "" || normalizedPath === "/") {
     if (trie.r) {
-      return validateAndBuild(trie.r, {}, pathname, pathnameHasTrailingSlash);
+      return validateAndBuild(
+        trie.r,
+        [],
+        undefined,
+        pathname,
+        pathnameHasTrailingSlash,
+      );
+    }
+    // A root-level wildcard ("/*") matches "/" with an empty remainder, the
+    // same value the regex matcher produces for the bare prefix. Without this
+    // the trie misses, the regex fallback runs, and its no-config branch emits
+    // a corrupt slice-off redirect. The static terminal still wins above.
+    // A one-or-more catch-all (`w1`, from `:name+`) rejects this empty case.
+    if (trie.w && !trie.w.w1) {
+      return validateAndBuild(
+        trie.w,
+        [],
+        "",
+        pathname,
+        pathnameHasTrailingSlash,
+      );
     }
     return null;
   }
 
-  // Remove leading slash and split
   const segments = normalizedPath.slice(1).split("/");
 
-  // Try exact match with normalized path (no trailing slash)
-  const result = walkTrie(trie, segments, 0, {});
+  const result = walkTrie(trie, segments, 0, []);
   if (result) {
-    return validateAndBuild(result.leaf, result.params, pathname, pathnameHasTrailingSlash);
+    return validateAndBuild(
+      result.leaf,
+      result.paramValues,
+      result.wildcardValue,
+      pathname,
+      pathnameHasTrailingSlash,
+      result.validatedParams,
+    );
   }
 
   return null;
@@ -68,105 +95,257 @@ export function tryTrieMatch(
 
 interface WalkResult {
   leaf: TrieLeaf;
-  params: Record<string, string>;
+  paramValues: string[];
+  wildcardValue?: string;
+  /**
+   * For a constraint-bearing leaf (leaf.cv set), the params map that
+   * leafConstraintsPass already decoded AND validated during the walk. Carried
+   * forward so validateAndBuild reuses it instead of re-decoding paramValues and
+   * re-running constraintsSatisfied a second time on the winning leaf. Undefined
+   * for unconstrained leaves (no decode/validate happened in the walk).
+   */
+  validatedParams?: Record<string, string>;
+}
+
+/**
+ * Check a leaf's constraints (leaf.cv) against already-resolved named params.
+ * Empty/undefined values are exempt (optional params that were not bound).
+ */
+function constraintsSatisfied(
+  leaf: TrieLeaf,
+  params: Record<string, string>,
+): boolean {
+  if (!leaf.cv) return true;
+  for (const paramName in leaf.cv) {
+    const allowed = leaf.cv[paramName]!;
+    const value = params[paramName];
+    if (value !== undefined && value !== "" && !allowed.includes(value)) {
+      return false;
+    }
+  }
+  return true;
 }
 
 /**
- * Walk the trie by segments with priority: static > param > wildcard.
- * Uses backtracking to try all possible matches.
+ * Constraint check for a candidate terminal DURING the walk. Builds the named
+ * params from positional walk values (decoded the same way validateAndBuild
+ * does) and validates leaf.cv. Returning null lets walkTrie unwind to a
+ * lower-priority sibling instead of committing to a leaf that would only be
+ * rejected post-walk — that post-walk rejection is what forced the regex
+ * fallback (and its false "trie gap" R3 warning) for perfectly valid configs.
+ *
+ * On success returns the built+validated params for a constraint-bearing leaf so
+ * walkTrie can carry them to validateAndBuild (avoiding a second decode + a
+ * second constraintsSatisfied pass on the winner); returns the shared EMPTY_PASS
+ * sentinel for an unconstrained leaf (no work was done, nothing to carry).
+ */
+const EMPTY_PASS: Record<string, string> = {};
+function leafConstraintsPass(
+  leaf: TrieLeaf,
+  paramValues: string[],
+  wildcardValue: string | undefined,
+): Record<string, string> | null {
+  if (!leaf.cv) return EMPTY_PASS;
+  const params: Record<string, string> = {};
+  if (leaf.pa) {
+    for (let i = 0; i < leaf.pa.length && i < paramValues.length; i++) {
+      params[leaf.pa[i]] = safeDecodeURIComponent(paramValues[i]);
+    }
+  }
+  if (wildcardValue !== undefined && "pn" in leaf) {
+    params[(leaf as TrieLeaf & { pn: string }).pn] =
+      safeDecodeURIComponent(wildcardValue);
+  }
+  return constraintsSatisfied(leaf, params) ? params : null;
+}
+
+/**
+ * Walk the trie by segments with priority: static > suffix-param > param >
+ * wildcard (Priority 1-4 below; matches the canonical M4 ordering in
+ * docs/internal/matching-and-lazy-discovery.md).
+ * Uses backtracking to try all possible matches. Per-leaf constraints are
+ * enforced at each candidate terminal so a constraint miss backtracks to a
+ * lower-priority sibling rather than aborting the whole match.
  */
 function walkTrie(
   node: TrieNode,
   segments: string[],
   index: number,
-  params: Record<string, string>,
+  paramValues: string[],
 ): WalkResult | null {
-  // All segments consumed: check for terminal
   if (index === segments.length) {
     if (node.r) {
-      return { leaf: node.r, params };
+      const validatedParams = leafConstraintsPass(
+        node.r,
+        paramValues,
+        undefined,
+      );
+      if (validatedParams) {
+        return {
+          leaf: node.r,
+          paramValues: [...paramValues],
+          validatedParams,
+        };
+      }
+    }
+    // A wildcard at this node matches the bare prefix with an empty remainder
+    // (e.g. "/files" against "/files/*"), mirroring the regex matcher's `*=""`.
+    // walkTrie otherwise only reaches node.w in the index<length branch below,
+    // so without this a request to the wildcard's own prefix misses the trie
+    // and the regex fallback emits a corrupt redirect. A static terminal
+    // (node.r) still wins. A one-or-more catch-all (`w1`, from `:name+`) rejects
+    // this empty case — it requires at least one trailing segment.
+    if (node.w && !node.w.w1) {
+      const validatedParams = leafConstraintsPass(node.w, paramValues, "");
+      if (validatedParams) {
+        return {
+          leaf: node.w,
+          paramValues: [...paramValues],
+          wildcardValue: "",
+          validatedParams,
+        };
+      }
     }
     return null;
   }
 
   const segment = segments[index];
+  const staticChild = node.s?.[segment];
 
-  // Priority 1: Static match
-  if (node.s?.[segment]) {
-    const result = walkTrie(node.s[segment], segments, index + 1, params);
+  if (staticChild) {
+    const result = walkTrie(staticChild, segments, index + 1, paramValues);
     if (result) return result;
   }
 
-  // Priority 2: Param match
-  if (node.p) {
-    const result = walkTrie(node.p.c, segments, index + 1, {
-      ...params,
-      [node.p.n]: segment,
-    });
+  if (node.xp) {
+    // node.xp keys are pre-sorted longest-suffix-first at build time
+    // (route-trie.ts sortSuffixParams), so the first match is the most specific
+    // suffix: `/app.min.js` matches `:file.min.js` before `:file.js`.
+    for (const suffix in node.xp) {
+      if (segment.endsWith(suffix) && segment.length > suffix.length) {
+        const paramValue = segment.slice(0, -suffix.length);
+        paramValues.push(paramValue);
+        const result = walkTrie(
+          node.xp[suffix].c,
+          segments,
+          index + 1,
+          paramValues,
+        );
+        paramValues.pop();
+        if (result) return result;
+      }
+    }
+  }
+
+  // A required single-segment param captures 1+ chars (the regex matcher emits
+  // `([^/]+)`), so an empty path segment from a double slash (`/a//b`) must NOT
+  // bind `:s` to "". Reject it here so the trie matches the regex contract and
+  // a malformed URL 404s instead of running the handler with an empty param.
+  // The suffix-param branch above already requires `segment.length > suffix`,
+  // and node.w may legitimately be empty, so only this branch needs the guard.
+  if (node.p && segment !== "") {
+    paramValues.push(segment);
+    const result = walkTrie(node.p.c, segments, index + 1, paramValues);
+    paramValues.pop();
     if (result) return result;
   }
 
-  // Priority 3: Wildcard match (consumes rest)
   if (node.w) {
-    const rest = segments.slice(index).join("/");
-    return {
-      leaf: node.w,
-      params: { ...params, [node.w.pn]: rest },
-    };
+    const rest = joinRemainingSegments(segments, index);
+    // A one-or-more catch-all (`w1`, from `:name+`) requires at least one
+    // non-empty trailing segment. `rest` can still be "" here on a malformed
+    // double-slash URL (e.g. `/docs//` splits to a trailing "" segment), so
+    // guard this in-path site the same way the root and base-case sites are.
+    if (!(node.w.w1 && rest === "")) {
+      const validatedParams = leafConstraintsPass(node.w, paramValues, rest);
+      if (validatedParams) {
+        return {
+          leaf: node.w,
+          paramValues: [...paramValues],
+          wildcardValue: rest,
+          validatedParams,
+        };
+      }
+    }
   }
 
   return null;
 }
 
+function joinRemainingSegments(segments: string[], start: number): string {
+  if (start >= segments.length) return "";
+  return segments.slice(start).join("/");
+}
+
 /**
  * Post-match: validate constraints and handle trailing slash logic.
+ *
+ * `validatedParams` is the params map walkTrie already decoded AND validated via
+ * leafConstraintsPass for a constraint-bearing winning leaf. When present (and
+ * non-empty) we reuse it verbatim and SKIP the second decode + the second
+ * constraintsSatisfied pass — both are byte-identical to the walk-time work.
+ * When absent (unconstrained leaf, or the root-path call sites that never walk)
+ * we still BUILD the params here (that is not redundant — they must be returned)
+ * and run constraintsSatisfied for safety; an unconstrained leaf's check is a
+ * cheap early `!leaf.cv` return.
  */
 function validateAndBuild(
   leaf: TrieLeaf,
-  params: Record<string, string>,
+  paramValues: string[],
+  wildcardValue: string | undefined,
   originalPathname: string,
   pathnameHasTrailingSlash: boolean,
+  validatedParams?: Record<string, string>,
 ): TrieMatchResult | null {
-  // Validate constraints
-  if (leaf.cv) {
-    for (const [paramName, allowed] of Object.entries(leaf.cv)) {
-      const value = params[paramName];
-      if (value !== undefined && value !== "" && !allowed.includes(value)) {
-        return null;
+  let params: Record<string, string>;
+  // EMPTY_PASS (the unconstrained sentinel) and undefined both mean "nothing was
+  // pre-validated"; only a populated map carried from a constraint-bearing leaf
+  // lets us skip the rebuild + re-check.
+  if (validatedParams && validatedParams !== EMPTY_PASS) {
+    params = validatedParams;
+  } else {
+    params = {};
+    if (leaf.pa) {
+      for (let i = 0; i < leaf.pa.length && i < paramValues.length; i++) {
+        params[leaf.pa[i]] = safeDecodeURIComponent(paramValues[i]);
       }
     }
-  }
 
-  // Fill in empty strings for optional params that weren't matched
-  if (leaf.op) {
-    for (const name of leaf.op) {
-      if (!(name in params)) {
-        params[name] = "";
-      }
+    if (wildcardValue !== undefined && "pn" in leaf) {
+      params[(leaf as TrieLeaf & { pn: string }).pn] =
+        safeDecodeURIComponent(wildcardValue);
+    }
+
+    if (!constraintsSatisfied(leaf, params)) {
+      return null;
     }
   }
 
-  // Trailing slash handling
   const tsMode = leaf.ts as "never" | "always" | "ignore" | undefined;
   let redirectTo: string | undefined;
 
-  if (tsMode === "always" && !pathnameHasTrailingSlash && originalPathname !== "/") {
+  if (
+    tsMode === "always" &&
+    !pathnameHasTrailingSlash &&
+    originalPathname !== "/"
+  ) {
     redirectTo = originalPathname + "/";
   } else if (tsMode === "never" && pathnameHasTrailingSlash) {
     redirectTo = originalPathname.slice(0, -1);
   }
 
-  return {
+  const result: TrieMatchResult = {
     routeKey: leaf.n,
     sp: leaf.sp,
     params,
-    optionalParams: leaf.op,
-    ancestry: leaf.a,
-    ...(redirectTo ? { redirectTo } : {}),
-    ...(leaf.pr ? { pr: true } : {}),
-    ...(leaf.pt ? { pt: true } : {}),
-    ...(leaf.rt ? { responseType: leaf.rt } : {}),
-    ...(leaf.nv ? { negotiateVariants: leaf.nv } : {}),
-    ...(leaf.rf ? { rscFirst: true } : {}),
   };
+
+  if (redirectTo) result.redirectTo = redirectTo;
+  if (leaf.pr) result.pr = true;
+  if (leaf.pt) result.pt = true;
+  if (leaf.rt) result.responseType = leaf.rt;
+  if (leaf.nv) result.negotiateVariants = leaf.nv;
+  if (leaf.rf) result.rscFirst = true;
+
+  return result;
 }

package/src/router/types.ts

@@ -5,7 +5,11 @@
  */
 
 import type { ReactNode } from "react";
-import type { EntryData, InterceptEntry, InterceptSelectorContext } from "../server/context";
+import type {
+  EntryData,
+  InterceptEntry,
+  InterceptSelectorContext,
+} from "../server/context";
 import type {
   ErrorInfo,
   ErrorPhase,
@@ -18,27 +22,11 @@ import type {
   ShouldRevalidateFn,
 } from "../types";
 
-/**
- * Result of resolving loaders with revalidation
- * Contains both segments to render and all matched segment IDs
- */
-export interface LoaderRevalidationResult {
-  segments: ResolvedSegment[];
-  matchedIds: string[];
-}
-
-/**
- * Result of resolving segments with revalidation
- * Contains both segments to render and all matched segment IDs
- */
 export interface SegmentRevalidationResult {
   segments: ResolvedSegment[];
   matchedIds: string[];
 }
 
-/**
- * Action context type for revalidation
- */
 export type ActionContext = {
   actionId?: string;
   actionUrl?: URL;
@@ -46,23 +34,6 @@ export type ActionContext = {
   formData?: FormData;
 };
 
-/**
- * Dependencies passed to segment resolution functions
- * These are created within createRouter and passed to extracted utilities
- */
-export interface RouterDependencies<TEnv> {
-  findNearestErrorBoundary: (
-    entry: EntryData | null
-  ) => ReactNode | ErrorBoundaryHandler | null;
-  findNearestNotFoundBoundary: (
-    entry: EntryData | null
-  ) => ReactNode | NotFoundBoundaryHandler | null;
-}
-
-/**
- * Dependencies injected from createRouter closure into extracted segment resolution functions.
- * These are the closure-bound helpers that cannot be imported directly.
- */
 export interface SegmentResolutionDeps<TEnv = any> {
   wrapLoaderPromise: <T>(
     promise: Promise<T>,
@@ -79,35 +50,31 @@ export interface SegmentResolutionDeps<TEnv = any> {
       requestStartTime?: number;
     },
   ) => Promise<LoaderDataResult<T>>;
-  trackHandler: <T>(promise: Promise<T>) => Promise<T>;
+  trackHandler: <T>(
+    promise: Promise<T>,
+    errorContext?: {
+      segmentId?: string;
+      segmentType?: string;
+    },
+  ) => Promise<T>;
   findNearestErrorBoundary: (
     entry: EntryData | null,
   ) => ReactNode | ErrorBoundaryHandler | null;
   findNearestNotFoundBoundary: (
     entry: EntryData | null,
   ) => ReactNode | NotFoundBoundaryHandler | null;
-  callOnError: (
-    error: unknown,
-    phase: ErrorPhase,
-    context: any,
-  ) => void;
-}
-
-/**
- * Dependencies injected from createRouter closure into extracted intercept resolution functions.
- */
-export interface InterceptResolutionDeps<TEnv = any> {
-  wrapLoaderPromise: SegmentResolutionDeps<TEnv>["wrapLoaderPromise"];
-  evaluateInterceptWhen: (
-    intercept: InterceptEntry,
-    selectorContext: InterceptSelectorContext | null,
-    isAction: boolean,
-  ) => boolean;
+  notFoundComponent?: ReactNode | ((props: { pathname: string }) => ReactNode);
+  callOnError: (error: unknown, phase: ErrorPhase, context: any) => void;
+  /**
+   * Router-level default for the per-segment `transition({ viewTransition })`
+   * flag, from createRouter({ viewTransition }). Resolved into each segment's
+   * transition config during resolution (only `false` is stamped) so the render
+   * gate reads the boundary decision off the segment on both server and client.
+   * Undefined is treated as "auto" (wrap).
+   */
+  viewTransitionDefault?: "auto" | false;
 }
 
-/**
- * Dependencies injected from createRouter closure into extracted match API functions.
- */
 export interface MatchApiDeps<TEnv = any> {
   findMatch: (pathname: string, ms?: any) => any;
   getMetricsStore: () => any;
@@ -122,23 +89,13 @@ export interface MatchApiDeps<TEnv = any> {
   getRouteMap: () => Record<string, string>;
 }
 
-/**
- * Title descriptor types for template support
- */
 export type TitleDescriptor =
   | string
   | { template: string; default: string } // For layouts - template applied to child titles
-  | { absolute: string }; // Bypass parent template
+  | { absolute: string };
 
-/**
- * Unset descriptor to remove inherited meta
- * Key format matches getMetaKey output: "title", "name:description", "property:og:image"
- */
 export type UnsetDescriptor = { unset: string };
 
-/**
- * Base meta descriptor types (sync values)
- */
 export type MetaDescriptorBase =
   | { charSet: "utf-8" }
   | { title: TitleDescriptor }
@@ -150,10 +107,6 @@ export type MetaDescriptorBase =
   | UnsetDescriptor
   | { [name: string]: unknown };
 
-/**
- * Meta descriptor that can be sync or async.
- * Use Promise<MetaDescriptorBase> for streaming meta that resolves after initial render.
- */
 export type MetaDescriptor = MetaDescriptorBase | Promise<MetaDescriptorBase>;
 
 type LdJsonObject = { [Key in string]: LdJsonValue } & {

package/src/router/url-params.ts

@@ -0,0 +1,57 @@
+/**
+ * URL param encode/decode at the route boundary.
+ *
+ * Extraction (decode): regex/trie matchers keep param values URL-encoded;
+ * `safeDecodeURIComponent` turns them back into raw strings so `ctx.params`
+ * matches the contract apps expect (Express/React Router/Fastify/Koa) and
+ * round-trips through reverse stay stable. Malformed %-encoding is
+ * preserved as-is so a broken URL doesn't crash matching.
+ *
+ * Reversal (encode): `encodePathSegment` escapes only what RFC 3986
+ * requires for a path segment — `/`, `?`, `#`, space, control chars,
+ * non-ASCII — and leaves pchar sub-delims (`@ : $ & + , ; =` and friends)
+ * readable. `encodeURIComponent` over-encodes for path segments, which
+ * makes generated URLs harder for humans to read in the address bar
+ * (e.g. mailbox IDs like `ivo@example.com` would become
+ * `ivo%40example.com` even though `@` is path-legal).
+ */
+
+export function safeDecodeURIComponent(raw: string): string {
+  if (raw === "" || raw.indexOf("%") === -1) return raw;
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return raw;
+  }
+}
+
+const PATH_SAFE_ESCAPES: Record<string, string> = {
+  "%3A": ":",
+  "%40": "@",
+  "%24": "$",
+  "%26": "&",
+  "%2B": "+",
+  "%2C": ",",
+  "%3B": ";",
+  "%3D": "=",
+};
+
+export function encodePathSegment(value: string): string {
+  return encodeURIComponent(value).replace(
+    /%(?:3A|40|24|26|2B|2C|3B|3D)/gi,
+    (match) => PATH_SAFE_ESCAPES[match.toUpperCase()] ?? match,
+  );
+}
+
+/**
+ * Encode a catch-all remainder: encode each `/`-separated segment but keep the
+ * separators, so `a/b c` -> `a/b%20c` (not `a%2Fb%20c`). Shared by the reverse
+ * helper and the build-time prerender substitution so both produce identical
+ * URLs. `encode` defaults to the path-safe `encodePathSegment`.
+ */
+export function encodePathRemainder(
+  value: string,
+  encode: (segment: string) => string = encodePathSegment,
+): string {
+  return value.split("/").map(encode).join("/");
+}