@rangojs/router 0.0.0-experimental.d7eeaa75 → 0.0.0-experimental.dacec167

package/src/router/telemetry.ts

@@ -90,6 +90,34 @@ export interface HandlerErrorEvent extends BaseEvent {
   params?: Record<string, string>;
 }
 
+/**
+ * Per-segment (or coarse route-level) cache status carried on the
+ * cache.decision telemetry event and the X-Rango-Cache debug header.
+ *
+ * v1 is COARSE: the router's pipeline tracks cache decisions at the
+ * route/entry level (cacheHit/cacheSource/shouldRevalidate), not per
+ * individual segment. The `segments` array therefore contains a single
+ * route-level entry keyed by the route key. The shape is forward-compatible
+ * with genuine per-segment status if the pipeline later exposes it.
+ */
+export type CacheSegmentStatus =
+  | "hit"
+  | "miss"
+  | "stale"
+  | "prerendered"
+  | "passthrough";
+
+export interface CacheSegmentSignal {
+  /** Segment id (v1: the route key, since status is route-level). */
+  id: string;
+  /** Segment type (v1: "route" for the coarse route-level entry). */
+  type: string;
+  /** Resolved cache status for this segment. */
+  cacheStatus: CacheSegmentStatus;
+  /** Whether stale-while-revalidate was triggered for this segment. */
+  shouldRevalidate?: boolean;
+}
+
 export interface CacheDecisionEvent extends BaseEvent {
   type: "cache.decision";
   pathname: string;
@@ -98,6 +126,12 @@ export interface CacheDecisionEvent extends BaseEvent {
   /** Whether stale-while-revalidate was triggered */
   shouldRevalidate: boolean;
   source?: "runtime" | "prerender";
+  /**
+   * Optional per-segment (v1: coarse route-level) cache status. Present only
+   * when telemetry or the debug cache signal is enabled. Optional so existing
+   * sinks are unaffected.
+   */
+  segments?: CacheSegmentSignal[];
 }
 
 export interface RevalidationDecisionEvent extends BaseEvent {
@@ -140,6 +174,71 @@ export type TelemetryEvent =
   | RequestTimeoutEvent
   | OriginCheckRejectedEvent;
 
+// ---------------------------------------------------------------------------
+// Cache signal derivation (coarse, route-level)
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive the coarse, route-level cache status from pipeline cache state.
+ *
+ * v1 mapping (route-level — see CacheSegmentSignal):
+ *   - prerender hit                         -> "prerendered"
+ *   - runtime hit + shouldRevalidate (SWR)  -> "stale"
+ *   - runtime hit                           -> "hit"
+ *   - no hit                                -> "miss"
+ *
+ * Note: "passthrough" is a build-time prerender concept (a route opts out of
+ * being prerendered for some params). At runtime a passthrough route renders
+ * fresh and is indistinguishable from a normal miss in the pipeline state, so
+ * v1 reports it as "miss". The "passthrough" status remains in the type union
+ * for forward compatibility.
+ */
+export function deriveCacheStatus(state: {
+  cacheHit: boolean;
+  cacheSource?: "runtime" | "prerender";
+  shouldRevalidate?: boolean;
+}): CacheSegmentStatus {
+  if (state.cacheHit) {
+    if (state.cacheSource === "prerender") return "prerendered";
+    if (state.shouldRevalidate) return "stale";
+    return "hit";
+  }
+  return "miss";
+}
+
+/**
+ * Build the coarse route-level cache signal array (a single entry keyed by
+ * the route key). Used for both the cache.decision telemetry event and the
+ * X-Rango-Cache debug header.
+ */
+export function buildCacheSignalSegments(
+  routeKey: string,
+  state: {
+    cacheHit: boolean;
+    cacheSource?: "runtime" | "prerender";
+    shouldRevalidate?: boolean;
+  },
+): CacheSegmentSignal[] {
+  return [
+    {
+      id: routeKey,
+      type: "route",
+      cacheStatus: deriveCacheStatus(state),
+      shouldRevalidate: !!state.shouldRevalidate,
+    },
+  ];
+}
+
+/**
+ * Serialize cache signal segments into the X-Rango-Cache header value:
+ * `<segId>=<status>, <segId2>=<status2>`.
+ */
+export function formatCacheSignalHeader(
+  segments: CacheSegmentSignal[],
+): string {
+  return segments.map((s) => `${s.id}=${s.cacheStatus}`).join(", ");
+}
+
 // ---------------------------------------------------------------------------
 // Sink interface
 // ---------------------------------------------------------------------------

package/src/router/trie-matching.ts

@@ -6,6 +6,7 @@
  */
 
 import type { TrieNode, TrieLeaf } from "../build/route-trie.js";
+import { safeDecodeURIComponent } from "./url-params.js";
 
 export interface TrieMatchResult {
   /** Route name */
@@ -14,7 +15,9 @@ export interface TrieMatchResult {
   sp: string;
   /** Matched route params */
   params: Record<string, string>;
-  /** Optional param names (absent params have empty string value) */
+  /** Optional param names declared on the route. Absent params are omitted
+   * from `params` (read as `undefined`), matching the
+   * `ExtractParams<"/:locale?/...">` type. */
   optionalParams?: string[];
   /** Ancestry shortCodes for layout pruning */
   ancestry: string[];
@@ -173,20 +176,25 @@ function validateAndBuild(
   originalPathname: string,
   pathnameHasTrailingSlash: boolean,
 ): TrieMatchResult | null {
-  // Build named params by zipping leaf.pa with positional paramValues
+  // Build named params by zipping leaf.pa with positional paramValues.
+  // Params are URL-decoded at this boundary so ctx.params holds the values
+  // apps expect (matching Express/React Router) and round-trip cleanly
+  // through ctx.reverse.
   const params: Record<string, string> = {};
   if (leaf.pa) {
     for (let i = 0; i < leaf.pa.length && i < paramValues.length; i++) {
-      params[leaf.pa[i]] = paramValues[i];
+      params[leaf.pa[i]] = safeDecodeURIComponent(paramValues[i]);
     }
   }
 
   // Add wildcard param (wildcard leaves have pn from TrieNode.w type)
   if (wildcardValue !== undefined && "pn" in leaf) {
-    params[(leaf as TrieLeaf & { pn: string }).pn] = wildcardValue;
+    params[(leaf as TrieLeaf & { pn: string }).pn] =
+      safeDecodeURIComponent(wildcardValue);
   }
 
-  // Validate constraints
+  // Validate constraints against decoded values so constraint lists can be
+  // written in decoded form (e.g. ["en-GB", "en US"]).
   if (leaf.cv) {
     for (const paramName in leaf.cv) {
       const allowed = leaf.cv[paramName]!;
@@ -197,14 +205,11 @@ function validateAndBuild(
     }
   }
 
-  // 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] = "";
-      }
-    }
-  }
+  // Optional params that weren't matched are left absent from `params` so
+  // `ctx.params.locale` reads as `undefined`, matching the
+  // `ExtractParams<"/:locale?/...">` type (`{ locale?: string }`). Both
+  // internal consumers — the constraint check above and `reverse()` —
+  // already treat missing/undefined as the absent form.
 
   // Trailing slash handling
   const tsMode = leaf.ts as "never" | "always" | "ignore" | undefined;

package/src/router/types.ts

@@ -98,6 +98,14 @@ export interface SegmentResolutionDeps<TEnv = any> {
   ) => ReactNode | NotFoundBoundaryHandler | null;
   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;
 }
 
 /**

package/src/router/url-params.ts

@@ -0,0 +1,49 @@
+/**
+ * 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;
+  }
+}
+
+// encodeURIComponent over-encodes for path segments. After running it,
+// un-encode the pchar sub-delims + (`:` / `@`) so the resulting URL
+// keeps human-readable characters that are legal in a path segment.
+// Everything dangerous — `/ ? # %` and space/control/non-ASCII — stays
+// encoded.
+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,
+  );
+}

package/src/router.ts

@@ -22,10 +22,9 @@ import type { UrlPatterns } from "./urls.js";
 import type { UrlBuilder } from "./urls/pattern-types.js";
 import { urls } from "./urls.js";
 import {
-  EntryData,
-  InterceptSelectorContext,
+  type EntryData,
   getContext,
-  RSCRouterContext,
+  RangoContext,
   type MetricsStore,
 } from "./server/context";
 import { createHandleStore, type HandleStore } from "./server/handle-store.js";
@@ -57,6 +56,7 @@ import { buildDebugManifest } from "./router/debug-manifest.js";
 
 import type { SegmentResolutionDeps, MatchApiDeps } from "./router/types.js";
 import { createHandlerContext } from "./router/handler-context.js";
+import { normalizeBasename } from "./router/basename.js";
 import {
   setupLoaderAccess,
   setupLoaderAccessSilent,
@@ -91,13 +91,10 @@ import {
   RouterRegistry,
   nextRouterAutoId,
 } from "./router/router-registry.js";
+import type { RangoOptions, RootLayoutProps } from "./router/router-options.js";
 import type {
-  RSCRouterOptions,
-  RootLayoutProps,
-} from "./router/router-options.js";
-import type {
-  RSCRouter,
-  RSCRouterInternal,
+  Rango,
+  RangoInternal,
   RouterRequestInput,
 } from "./router/router-interfaces.js";
 
@@ -116,22 +113,22 @@ import {
 // Re-export public types and values from extracted modules
 export { RSC_ROUTER_BRAND, RouterRegistry } from "./router/router-registry.js";
 export type {
-  RSCRouterOptions,
+  RangoOptions,
   RootLayoutProps,
   SSRStreamMode,
   SSROptions,
   ResolveStreamingContext,
 } from "./router/router-options.js";
 export type {
-  RSCRouter,
-  RSCRouterInternal,
+  Rango,
+  RangoInternal,
   RouterRequestInput,
 } from "./router/router-interfaces.js";
 export { toInternal } from "./router/router-interfaces.js";
 
 export function createRouter<TEnv = any>(
-  options: RSCRouterOptions<TEnv> = {},
-): RSCRouter<TEnv, {}> {
+  options: RangoOptions<TEnv> = {},
+): Rango<TEnv, {}> {
   const {
     id: userProvidedId,
     $$id: injectedId,
@@ -159,14 +156,23 @@ export function createRouter<TEnv = any>(
     timeouts: timeoutsOption,
     onTimeout,
     originCheck: originCheckOption,
+    viewTransition: viewTransitionOption = "auto",
+    debugCacheSignal: debugCacheSignalOption = false,
   } = options;
 
+  // Debug cache signal gate (DEVELOPMENT/TEST ONLY). Enabled by the
+  // debugCacheSignal option OR the RANGO_TEST_SIGNALS=1 env flag. When off,
+  // no X-Rango-Cache header is emitted and output is byte-identical.
+  const cacheSignalEnabled =
+    debugCacheSignalOption ||
+    (typeof process !== "undefined" &&
+      (process as { env?: Record<string, string | undefined> }).env
+        ?.RANGO_TEST_SIGNALS === "1");
+
   // Normalize basename: ensure leading slash, strip trailing slash.
-  // A bare "/" is equivalent to no basename.
-  const basename =
-    basenameOption && basenameOption.replace(/^\/+|\/+$/g, "")
-      ? "/" + basenameOption.replace(/^\/+|\/+$/g, "")
-      : undefined;
+  // A bare "/" is equivalent to no basename. Shared with the testing
+  // primitives via normalizeBasename so they can never drift.
+  const basename = normalizeBasename(basenameOption);
 
   // Resolve telemetry sink (no-op when not configured)
   const telemetry = resolveSink(telemetrySink);
@@ -538,6 +544,7 @@ export function createRouter<TEnv = any>(
     findNearestNotFoundBoundary,
     notFoundComponent: notFound,
     callOnError,
+    viewTransitionDefault: viewTransitionOption,
   };
 
   // Match API dependencies
@@ -665,6 +672,7 @@ export function createRouter<TEnv = any>(
     findMatch,
     findInterceptForRoute,
     telemetry: telemetrySink,
+    cacheSignalEnabled,
   });
 
   const { match, matchPartial, matchError, previewMatch } = matchHandlers;
@@ -674,7 +682,7 @@ export function createRouter<TEnv = any>(
    * The type system tracks accumulated routes through the builder chain
    * Initial TRoutes is {} (empty) to avoid poisoning accumulated types with Record<string, string>
    */
-  const router: RSCRouterInternal<TEnv, {}> = {
+  const router: RangoInternal<TEnv, {}> = {
     __brand: RSC_ROUTER_BRAND,
     id: routerId,
     basename,
@@ -722,7 +730,7 @@ export function createRouter<TEnv = any>(
       };
 
       let handlerResult: AllUseItems[] = [];
-      RSCRouterContext.run(
+      RangoContext.run(
         {
           manifest,
           patterns: routePatterns,
@@ -1000,6 +1008,13 @@ export function createRouter<TEnv = any>(
     // Expose basename for runtime manifest generation
     __basename: basename,
 
+    // Expose router-level boundary defaults for build-time clientChunks
+    // discovery (so a "use client" default boundary lands in app-fallback).
+    // These are createRouter options, never pushed onto EntryData.
+    __defaultErrorBoundary: defaultErrorBoundary,
+    __defaultNotFoundBoundary: defaultNotFoundBoundary,
+    __notFound: notFound,
+
     // RSC request handler (lazily created on first call)
     fetch: (() => {
       // Handler is created on first call and reused
@@ -1046,9 +1061,9 @@ export function createRouter<TEnv = any>(
 
   // If urls option was provided, auto-register them
   if (typeof urlsOption === "function") {
-    return router.routes(urlsOption) as RSCRouter<TEnv, {}>;
+    return router.routes(urlsOption) as Rango<TEnv, {}>;
   } else if (urlsOption) {
-    return router.routes(urlsOption) as RSCRouter<TEnv, {}>;
+    return router.routes(urlsOption) as Rango<TEnv, {}>;
   }
 
   return router;

package/src/rsc/handler-context.ts

@@ -6,14 +6,14 @@
  * RSC rendering) so they can be standalone modules without closure coupling.
  */
 
-import type { RSCRouterInternal } from "../router/router-interfaces.js";
+import type { RangoInternal } from "../router/router-interfaces.js";
 import type { ErrorPhase } from "../types.js";
 import type { InvokeOnErrorContext } from "../router/error-handling.js";
 import type { RSCDependencies, LoadSSRModule } from "./types.js";
 import type { SSRStreamMode } from "../router/router-options.js";
 
 export interface HandlerContext<TEnv = unknown> {
-  router: RSCRouterInternal<TEnv, any>;
+  router: RangoInternal<TEnv, any>;
   version: string;
   renderToReadableStream: RSCDependencies["renderToReadableStream"];
   decodeReply: RSCDependencies["decodeReply"];

package/src/rsc/handler.ts

@@ -8,7 +8,7 @@
  */
 
 import { createElement } from "react";
-import { RouteNotFoundError } from "../errors.js";
+import { isRouteNotFoundError } from "../errors.js";
 import { matchMiddleware, executeMiddleware } from "../router/middleware.js";
 import {
   runWithRequestContext,
@@ -31,6 +31,7 @@ import {
   interceptRedirectForPartial,
   buildRouteMiddlewareEntries,
 } from "./helpers.js";
+import { isWebSocketUpgradeResponse } from "../response-utils.js";
 import {
   handleResponseRoute,
   type ResponseRouteMatch,
@@ -56,6 +57,7 @@ import {
   getRouterTrie,
 } from "../route-map-builder.js";
 import type { HandlerContext } from "./handler-context.js";
+import type { SegmentCacheStore } from "../cache/types.js";
 import { buildRouterTrieFromUrlpatterns } from "./manifest-init.js";
 import { handleProgressiveEnhancement } from "./progressive-enhancement.js";
 import {
@@ -64,7 +66,10 @@ import {
   type ActionContinuation,
 } from "./server-action.js";
 import { handleLoaderFetch } from "./loader-fetch.js";
-import { checkRequestOrigin, type OriginCheckPhase } from "./origin-guard.js";
+import {
+  checkRequestOrigin,
+  ORIGIN_CHECK_PHASE_BY_MODE,
+} from "./origin-guard.js";
 import { handleRscRendering } from "./rsc-rendering.js";
 import {
   withTimeout,
@@ -81,6 +86,7 @@ import {
   startSSRSetup,
   getSSRSetup,
   mayNeedSSR,
+  isRscRequest,
   SSR_SETUP_VAR,
 } from "./ssr-setup.js";
 import {
@@ -352,7 +358,7 @@ export function createRSCHandler<
     // Resolve cache store configuration
     // Priority: options.cache (handler override) > router.cache (router default)
     // Store is enabled only if: config provided, enabled, and no ?__no_cache query param
-    let cacheStore = undefined;
+    let cacheStore: SegmentCacheStore | undefined;
     const cacheOption = options.cache ?? router.cache;
     if (cacheOption && !url.searchParams.has("__no_cache")) {
       const cacheConfig =
@@ -533,7 +539,9 @@ export function createRSCHandler<
       }
 
       const fullTiming = timingParts.join(", ");
-      if (fullTiming) response.headers.set("Server-Timing", fullTiming);
+      if (fullTiming && !isWebSocketUpgradeResponse(response)) {
+        response.headers.set("Server-Timing", fullTiming);
+      }
 
       return response;
     });
@@ -593,10 +601,7 @@ export function createRSCHandler<
         routerId: router.id,
       });
     } catch (error) {
-      if (
-        error instanceof RouteNotFoundError ||
-        (error instanceof Error && error.name === "RouteNotFoundError")
-      ) {
+      if (isRouteNotFoundError(error)) {
         // Let the render path handle 404 — match()/matchPartial() will
         // re-throw RouteNotFoundError and the catch block in
         // executeRenderWithMiddleware renders the not-found page.
@@ -647,14 +652,7 @@ export function createRSCHandler<
     }
 
     // ---- 3. Origin guard (gate for action/loader/PE modes) ----
-    const originPhase: OriginCheckPhase | null =
-      plan.mode === "action"
-        ? "action"
-        : plan.mode === "loader"
-          ? "loader"
-          : plan.mode === "pe-render"
-            ? "pe-form"
-            : null;
+    const originPhase = ORIGIN_CHECK_PHASE_BY_MODE[plan.mode];
     if (originPhase) {
       const originResult = await checkRequestOrigin(
         request,
@@ -804,7 +802,7 @@ export function createRSCHandler<
         );
       }
       const response = responseOutcome.result;
-      if (plan.negotiated) {
+      if (plan.negotiated && !isWebSocketUpgradeResponse(response)) {
         response.headers.append("Vary", "Accept");
       }
       return response;
@@ -921,47 +919,17 @@ export function createRSCHandler<
       );
     }
 
-    // ---- Full render / Partial render (or PE that fell through) ----
-    if (plan.mode === "full-render" || plan.mode === "partial-render") {
-      const isPartial = plan.mode === "partial-render";
-      return executeRenderWithMiddleware(
-        plan.route.routeMiddleware,
-        plan.negotiated,
-        plan.route.routeKey,
-        routeReverse,
-        request,
-        env,
-        url,
-        variables,
-        nonce,
-        handleStore,
-        isPartial,
-      );
-    }
-
-    // PE that fell through (handleProgressiveEnhancement returned null)
-    // falls back to full render
-    if (plan.mode === "pe-render") {
-      return executeRenderWithMiddleware(
-        plan.route.routeMiddleware,
-        false,
-        plan.route.routeKey,
-        routeReverse,
-        request,
-        env,
-        url,
-        variables,
-        nonce,
-        handleStore,
-        false,
-      );
-    }
-
-    // Redirect plan that wasn't handled above (full-page redirect — let
-    // the pipeline handle it via match() which returns { redirect: url })
+    // Full render, partial render, fallen-through PE, and full-page redirect all
+    // render through the same middleware-wrapped path. Only full/partial-render
+    // carry negotiation + the partial flag; pe/redirect render plainly.
+    const isPartial = plan.mode === "partial-render";
+    const negotiated =
+      plan.mode === "full-render" || plan.mode === "partial-render"
+        ? plan.negotiated
+        : false;
     return executeRenderWithMiddleware(
       plan.route.routeMiddleware,
-      false,
+      negotiated,
       plan.route.routeKey,
       routeReverse,
       request,
@@ -970,7 +938,7 @@ export function createRSCHandler<
       variables,
       nonce,
       handleStore,
-      false,
+      isPartial,
     );
   }
 
@@ -1014,7 +982,7 @@ export function createRSCHandler<
             nonce,
           );
         }
-        if (negotiated) {
+        if (negotiated && !isWebSocketUpgradeResponse(response)) {
           response.headers.append("Vary", "Accept");
         }
         return response;
@@ -1050,10 +1018,7 @@ export function createRSCHandler<
         }
 
         // Render 404 page for unmatched routes
-        const isRouteNotFound =
-          error instanceof RouteNotFoundError ||
-          (error instanceof Error && error.name === "RouteNotFoundError");
-        if (isRouteNotFound) {
+        if (isRouteNotFoundError(error)) {
           callOnError(error, "routing", {
             request,
             url,
@@ -1100,13 +1065,7 @@ export function createRSCHandler<
             },
           });
 
-          const isRscRequest =
-            isPartial ||
-            (!request.headers.get("accept")?.includes("text/html") &&
-              !url.searchParams.has("__html")) ||
-            url.searchParams.has("__rsc");
-
-          if (isRscRequest) {
+          if (isRscRequest(request, url, isPartial)) {
             return createResponseWithMergedHeaders(rscStream, {
               status: 404,
               headers: { "content-type": "text/x-component;charset=utf-8" },