@rangojs/router 0.0.0-experimental.132 → 0.0.0-experimental.133

package/src/router/prefetch-cache-ttl.ts

@@ -0,0 +1,51 @@
+/**
+ * Resolve the prefetch cache TTL once, at router init, into the three derived
+ * values the rest of the router consumes: seconds (for the Cache-Control
+ * max-age), milliseconds (for the client-side in-memory cache), and the
+ * Cache-Control header string (or false when caching is disabled).
+ *
+ * `false` disables prefetch caching (seconds 0). A non-finite input
+ * (NaN/Infinity, e.g. from an env-derived number that failed to parse) is
+ * treated as the default rather than producing a malformed
+ * `Cache-Control: max-age=NaN` header; CDNs/browsers ignore such a directive,
+ * which would silently disable caching on EVERY prefetch response. Negative
+ * finite values clamp to 0 (disabled).
+ *
+ * Policy note: this is the prefetch-TTL policy specifically. Other finite-number
+ * guards in the codebase deliberately differ — defer.ts treats Infinity as an
+ * intentional disable, and profile-registry.ts THROWS on non-finite/negative ttl
+ * at config time. They are NOT the same guard, so don't unify them.
+ */
+export interface ResolvedPrefetchCacheTTL {
+  /** TTL in seconds for the Cache-Control max-age directive. */
+  seconds: number;
+  /** TTL in milliseconds for the client-side in-memory prefetch cache. */
+  ms: number;
+  /** Cache-Control header value, or false when caching is disabled. */
+  cacheControl: string | false;
+}
+
+const DEFAULT_PREFETCH_CACHE_TTL_SECONDS = 300;
+
+export function resolvePrefetchCacheTTL(
+  rawTTL: number | false | undefined,
+): ResolvedPrefetchCacheTTL {
+  let seconds: number;
+  if (rawTTL === false) {
+    seconds = 0;
+  } else if (rawTTL === undefined) {
+    seconds = DEFAULT_PREFETCH_CACHE_TTL_SECONDS;
+  } else if (typeof rawTTL === "number" && Number.isFinite(rawTTL)) {
+    seconds = Math.max(0, Math.floor(rawTTL));
+  } else {
+    // Non-finite (NaN/Infinity): fall back to the default rather than emit a
+    // malformed max-age=NaN/Infinity that CDNs and browsers reject.
+    seconds = DEFAULT_PREFETCH_CACHE_TTL_SECONDS;
+  }
+
+  return {
+    seconds,
+    ms: seconds * 1000,
+    cacheControl: seconds === 0 ? false : `private, max-age=${seconds}`,
+  };
+}

package/src/router/router-interfaces.ts

@@ -315,6 +315,13 @@ export interface RangoInternal<
    */
   readonly warmupEnabled: boolean;
 
+  /**
+   * Whether the client hydrates inside React.StrictMode. Resolved from
+   * createRouter({ strictMode }) (default true) and shipped to the client in
+   * the initial payload metadata.
+   */
+  readonly strictMode: boolean;
+
   /**
    * Whether router-wide performance debugging is enabled.
    * Used by the request handler to create metrics before middleware runs.

package/src/router/router-options.ts

@@ -523,6 +523,29 @@ export interface RangoOptions<TEnv = any> {
    */
   warmup?: boolean;
 
+  /**
+   * Wrap the hydrated client tree in `React.StrictMode`.
+   *
+   * The Rango browser entry hydrates the app inside `<React.StrictMode>` by
+   * default. StrictMode double-invokes render and (in development) mounts,
+   * unmounts, then remounts every effect to surface impure renders and missing
+   * effect cleanup. Production builds treat StrictMode as a no-op, so this flag
+   * only changes development behavior in a normal app.
+   *
+   * Set to `false` to hydrate without the StrictMode wrapper. The main reason to
+   * opt out is to isolate StrictMode's intentional double-render/double-effect
+   * from genuine re-renders when measuring client-hook stability — with
+   * StrictMode off, render counts are exact in development too.
+   *
+   * The value is resolved server-side at router creation and shipped to the
+   * client in the initial payload metadata; the browser entry reads it once at
+   * hydration. Changing it does not affect the SSR HTML (StrictMode emits no
+   * DOM), so toggling it never causes a hydration mismatch.
+   *
+   * @default true
+   */
+  strictMode?: boolean;
+
   /**
    * Shorthand timeout (ms) applied to both action execution and render start.
    * Does NOT apply to streamIdleMs.

package/src/router/segment-resolution/fresh.ts

@@ -26,6 +26,7 @@ import {
   resolveLayoutComponent,
   resolveWithErrorBoundary,
   warnOnStreamedResponse,
+  buildLoaderErrorContext,
 } from "./helpers.js";
 import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { getRouterContext } from "../router-context.js";
@@ -59,6 +60,13 @@ export async function resolveLoaders<TEnv>(
   const hasLoading = "loading" in entry && entry.loading !== undefined;
   const loadingDisabled = hasLoading && entry.loading === false;
 
+  // Error context for wrapLoaderPromise: without it, a throwing DSL loader never
+  // fires createRouter({ onError }) (phase "loader") nor emits the loader.error
+  // telemetry event — wrapLoaderPromise only builds the onError/telemetry path
+  // when errorContext is supplied. Built from ctx so the live render path reports
+  // loader failures the same way handlers/actions/routing/fetchable-loaders do.
+  const errorContext = buildLoaderErrorContext(ctx);
+
   if (!loadingDisabled) {
     // Streaming loaders: promises kick off now, settle during RSC serialization.
     const segments = loaderEntries.map((loaderEntry, i) => {
@@ -79,6 +87,7 @@ export async function resolveLoaders<TEnv>(
           entry,
           segmentId,
           ctx.pathname,
+          errorContext,
         ),
         belongsToRoute,
       };
@@ -107,6 +116,7 @@ export async function resolveLoaders<TEnv>(
       entry,
       segmentId,
       ctx.pathname,
+      errorContext,
     );
     return { wrapped, segmentId };
   });

package/src/router/segment-resolution/helpers.ts

@@ -19,7 +19,12 @@ import {
 import { getRequestContext } from "../../server/request-context.js";
 import { DefaultErrorFallback } from "../../default-error-boundary.js";
 import type { EntryData } from "../../server/context";
-import type { ResolvedSegment, ErrorInfo, HandlerContext } from "../../types";
+import type {
+  ResolvedSegment,
+  ErrorInfo,
+  HandlerContext,
+  InternalHandlerContext,
+} from "../../types";
 import type { SegmentResolutionDeps } from "../types.js";
 import { debugLog } from "../logging.js";
 import { tryStaticLookup } from "./static-store.js";
@@ -27,6 +32,35 @@ import { observeHandler } from "../instrument.js";
 import type { TelemetrySink } from "../telemetry.js";
 import { resolveSink, safeEmit, getRequestId } from "../telemetry.js";
 
+/** The errorContext shape wrapLoaderPromise expects as its 5th argument. */
+type LoaderErrorContext<TEnv> = NonNullable<
+  Parameters<SegmentResolutionDeps<TEnv>["wrapLoaderPromise"]>[4]
+>;
+
+/**
+ * Build the errorContext passed to wrapLoaderPromise so a throwing DSL loader
+ * fires createRouter({ onError }) (phase "loader") and emits the loader.error
+ * telemetry event. wrapLoaderPromise only wires the onError/telemetry path when
+ * this 5th argument is present; every real call site previously omitted it, so
+ * loaders were the one phase whose failures were silently dropped (handlers,
+ * actions, routing, rendering, and fetchable loaders all reported correctly).
+ *
+ * The fields come off the handler context, which already carries the request,
+ * url, params, env, and (on the internal shape) the matched route name.
+ */
+export function buildLoaderErrorContext<TEnv>(
+  ctx: HandlerContext<any, TEnv>,
+): LoaderErrorContext<TEnv> {
+  const internal = ctx as InternalHandlerContext<any, TEnv>;
+  return {
+    request: ctx.request,
+    url: ctx.url,
+    routeKey: internal._routeName,
+    params: ctx.params as Record<string, string>,
+    env: ctx.env,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Handler result processing
 // ---------------------------------------------------------------------------

package/src/router/segment-resolution/loader-cache.ts

@@ -147,12 +147,6 @@ export function resolveLoaderData<TEnv>(
 
   const loaderId = loaderEntry.loader.$$id;
 
-  const ttl = resolveTtl(options.ttl, store.defaults, DEFAULT_ROUTE_TTL);
-  const swrWindow = resolveSwrWindow(options.swr, store.defaults);
-  const swr = swrWindow || undefined;
-  const tags = resolveTags(loaderEntry);
-  recordRequestTags(tags);
-
   // A handler that later awaits this same loader via ctx.use(loader) must get
   // THIS memoized promise, not a fresh execution. Rather than rebind ctx.use
   // once per cached loader (O(N) chained wrappers + a synchronous
@@ -188,6 +182,16 @@ export function resolveLoaderData<TEnv>(
   const existing = overrides.get(loaderId);
   if (existing) return existing;
 
+  // Compute ttl/swr/tags only AFTER the dedup short-circuit: a deduped second
+  // resolution of the same loaderId (the orphan-layout inheritance path) must
+  // not re-run the user tags() callback. These values are only consumed inside
+  // the read-through below, so they belong here, past the dedup gate.
+  const ttl = resolveTtl(options.ttl, store.defaults, DEFAULT_ROUTE_TTL);
+  const swrWindow = resolveSwrWindow(options.swr, store.defaults);
+  const swr = swrWindow || undefined;
+  const tags = resolveTags(loaderEntry);
+  recordRequestTags(tags);
+
   const dataPromise = (async () => {
     const codec = await getCodec();
     const key = await resolveLoaderKey(

package/src/router/segment-resolution/revalidation.ts

@@ -40,6 +40,7 @@ import {
   tryStaticSlot,
   resolveLayoutComponent,
   resolveWithErrorBoundary,
+  buildLoaderErrorContext,
 } from "./helpers.js";
 import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { getRouterContext } from "../router-context.js";
@@ -199,6 +200,10 @@ export async function resolveLoadersWithRevalidation<TEnv>(
     ),
   );
 
+  // Partial (revalidation) render path: a throwing DSL loader must still fire
+  // onError/loader.error. isPartial flags the reporting phase accordingly.
+  const errorContext = { ...buildLoaderErrorContext(ctx), isPartial: true };
+
   const loadersToRun = revalidationChecks.filter((c) => c.shouldRun);
   const segments: ResolvedSegment[] = loadersToRun.map(
     ({ loaderEntry, loader, segmentId, index }) => ({
@@ -216,6 +221,7 @@ export async function resolveLoadersWithRevalidation<TEnv>(
         entry,
         segmentId,
         ctx.pathname,
+        errorContext,
       ),
       belongsToRoute,
     }),

package/src/router/segment-resolution.ts

@@ -2,6 +2,7 @@
 export {
   handleHandlerResult,
   warnOnStreamedResponse,
+  buildLoaderErrorContext,
 } from "./segment-resolution/helpers.js";
 export {
   resolveLoaders,

package/src/router/trie-matching.ts

@@ -5,7 +5,11 @@
  * 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 {
@@ -24,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;
 }
@@ -231,7 +235,13 @@ function walkTrie(
     }
   }
 
-  if (node.p) {
+  // 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();
@@ -256,12 +266,7 @@ function walkTrie(
 
 function joinRemainingSegments(segments: string[], start: number): string {
   if (start >= segments.length) return "";
-
-  let rest = segments[start]!;
-  for (let i = start + 1; i < segments.length; i++) {
-    rest += "/" + segments[i]!;
-  }
-  return rest;
+  return segments.slice(start).join("/");
 }
 
 /**

package/src/router.ts

@@ -110,6 +110,7 @@ import {
   renderStaticSegment as _renderStaticSegment,
 } from "./router/prerender-match.js";
 import { resolveStateCookieName } from "./router/state-cookie-name.js";
+import { resolvePrefetchCacheTTL } from "./router/prefetch-cache-ttl.js";
 
 // Re-export public types and values from extracted modules
 export { RSC_ROUTER_BRAND, RouterRegistry } from "./router/router-registry.js";
@@ -161,6 +162,7 @@ export function createRouter<TEnv = any>(
     originCheck: originCheckOption,
     viewTransition: viewTransitionOption = "auto",
     debugCacheSignal: debugCacheSignalOption = false,
+    strictMode: strictModeOption = true,
   } = options;
 
   // Debug cache signal gate (DEVELOPMENT/TEST ONLY). Enabled by the
@@ -230,21 +232,24 @@ export function createRouter<TEnv = any>(
     routerId,
   );
 
-  // Resolve prefetch cache TTL (default: 300 seconds / 5 minutes)
-  // Clamp to a non-negative integer for valid Cache-Control max-age.
-  const rawTTL =
-    prefetchCacheTTLOption !== undefined ? prefetchCacheTTLOption : 300;
-  const prefetchCacheTTLSeconds =
-    rawTTL === false ? 0 : Math.max(0, Math.floor(rawTTL));
-  const prefetchCacheTTL = prefetchCacheTTLSeconds * 1000;
+  // Resolve prefetch cache TTL (default: 300 seconds / 5 minutes). Clamps to a
+  // non-negative integer and guards non-finite (NaN/Infinity) inputs so a
+  // malformed `Cache-Control: max-age=NaN` can never reach the wire.
+  const resolvedPrefetchCacheTTL = resolvePrefetchCacheTTL(
+    prefetchCacheTTLOption,
+  );
+  const prefetchCacheTTL = resolvedPrefetchCacheTTL.ms;
   const prefetchCacheControl: string | false =
-    prefetchCacheTTLSeconds === 0
-      ? false
-      : `private, max-age=${prefetchCacheTTLSeconds}`;
+    resolvedPrefetchCacheTTL.cacheControl;
 
   // Resolve warmup enabled flag (default: true)
   const warmupEnabled = warmupOption !== false;
 
+  // Resolve StrictMode flag (default: true). Shipped to the client in payload
+  // metadata; the browser entry reads it once to decide whether to wrap the
+  // hydrated tree in React.StrictMode.
+  const strictMode = strictModeOption !== false;
+
   // Resolve theme config (null if theme not enabled)
   const resolvedThemeConfig = themeOption
     ? resolveThemeConfig(themeOption)
@@ -971,6 +976,9 @@ export function createRouter<TEnv = any>(
     // Expose warmup enabled flag for handler and client
     warmupEnabled,
 
+    // Expose StrictMode flag for the initial-render payload metadata
+    strictMode,
+
     // Expose router-wide performance debugging for request-level metrics setup
     debugPerformance,
 

package/src/rsc/handler.ts

@@ -13,7 +13,6 @@ import { matchMiddleware, executeMiddleware } from "../router/middleware.js";
 import {
   runWithRequestContext,
   setRequestContextParams,
-  requireRequestContext,
   getRequestContext,
   _getRequestContext,
   createRequestContext,
@@ -32,7 +31,10 @@ import {
   buildRouteMiddlewareEntries,
 } from "./helpers.js";
 import { guardOutgoingRedirect } from "./redirect-guard.js";
-import { isWebSocketUpgradeResponse } from "../response-utils.js";
+import {
+  isWebSocketUpgradeResponse,
+  appendVaryAccept,
+} from "../response-utils.js";
 import {
   handleResponseRoute,
   type ResponseRouteMatch,
@@ -294,7 +296,17 @@ export function createRSCHandler<
         ...(locationState && { locationState }),
       },
     };
-    const rscStream = renderToReadableStream<RscPayload>(redirectPayload);
+    const rscStream = renderToReadableStream<RscPayload>(redirectPayload, {
+      onError: (error: unknown) => {
+        const reqCtx = _getRequestContext<TEnv>();
+        if (!reqCtx) return;
+        callOnError(error, "rendering", {
+          request: reqCtx.request,
+          url: reqCtx.url,
+          env: reqCtx.env,
+        });
+      },
+    });
     return createResponseWithMergedHeaders(rscStream, {
       status: 200,
       headers: { "content-type": "text/x-component;charset=utf-8" },
@@ -762,11 +774,11 @@ export function createRSCHandler<
     nonce: string | undefined,
   ): Promise<Response> {
     // Common setup
-    const handleStore = requireRequestContext()._handleStore;
+    const handleStore = getRequestContext()._handleStore;
 
     // Wire up error reporting for late streaming-handle failures
     handleStore.onError = (error: Error) => {
-      const reqCtx = requireRequestContext();
+      const reqCtx = getRequestContext();
       callOnError(error, "handler", {
         request,
         url,
@@ -790,7 +802,7 @@ export function createRSCHandler<
     // instead of calling resolveRoute again.
     if (plan.mode !== "redirect") {
       setRequestContextParams(plan.route.params, plan.route.routeKey);
-      requireRequestContext()._classifiedRoute = plan.route;
+      getRequestContext()._classifiedRoute = plan.route;
     }
 
     const routeReverse = createReverseFunction(getRequiredRouteMap());
@@ -831,7 +843,9 @@ export function createRSCHandler<
       }
       const response = responseOutcome.result;
       if (plan.negotiated && !isWebSocketUpgradeResponse(response)) {
-        response.headers.append("Vary", "Accept");
+        // handleResponseRoute (callHandlerWithVary) already appends Vary: Accept
+        // for negotiated responses; dedup so we don't emit Vary: Accept, Accept.
+        appendVaryAccept(response);
       }
       return response;
     }
@@ -839,14 +853,28 @@ export function createRSCHandler<
     // SSR setup: kick off in parallel for modes that need HTML rendering.
     // Placed after response-route short-circuit so response/mime routes
     // never pay for SSR work.
-    if (plan.mode !== "loader" && mayNeedSSR(request, url)) {
+    //
+    // Only kick off when the request will actually render HTML, so the
+    // eager loadSSRModule() + user resolveStreaming() are not started (and
+    // never consumed) for a request that returns an RSC stream — that wasted
+    // work also leaves an orphaned Promise.all that can reject (D7). PE form
+    // submissions always render HTML (handleProgressiveEnhancement renders via
+    // getSSRSetup regardless of Accept). For full/partial-render and action,
+    // the render-time HTML decision is exactly !isRscRequest — mayNeedSSR is
+    // the coarse transport pre-filter, isRscRequest is the precise Accept call
+    // (it, unlike mayNeedSSR, treats a MISSING Accept as RSC). Both must pass.
+    const willRenderHtml =
+      plan.mode === "pe-render" ||
+      (mayNeedSSR(request, url) &&
+        !isRscRequest(request, url, plan.mode === "partial-render"));
+    if (plan.mode !== "loader" && willRenderHtml) {
       variables[SSR_SETUP_VAR] = startSSRSetup(
         handlerCtx,
         request,
         env,
         url,
         router.debugPerformance
-          ? () => requireRequestContext()._metricsStore
+          ? () => getRequestContext()._metricsStore
           : undefined,
       );
     }
@@ -989,7 +1017,7 @@ export function createRSCHandler<
     url: URL,
     variables: Record<string, any>,
     nonce: string | undefined,
-    handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
+    handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
     isPartial: boolean,
     actionContinuation?: ActionContinuation,
   ): Promise<Response> {
@@ -1017,7 +1045,9 @@ export function createRSCHandler<
           );
         }
         if (negotiated && !isWebSocketUpgradeResponse(response)) {
-          response.headers.append("Vary", "Accept");
+          // handleRscRendering bakes `accept` into the RSC response's Vary list;
+          // dedup so the negotiated append does not list accept twice.
+          appendVaryAccept(response);
         }
         return response;
       } catch (error) {
@@ -1092,14 +1122,23 @@ export function createRSCHandler<
               segments: [notFoundSegment],
               matched: [],
               diff: [],
+              // Shape parity with buildFullPayload (rsc-rendering.ts): the 404
+              // payload carries params/resolvedIds/prefetchCacheTTL the same way a
+              // matched full render does. resolvedIds mirrors the rendered segment
+              // list (the single notFound segment) like the error-boundary path
+              // (match-api.ts) does for its boundary segment.
+              resolvedIds: [notFoundSegment.id],
+              params: {},
               isPartial: false,
               rootLayout: router.rootLayout,
               handles: handleStore.stream(),
               version,
+              prefetchCacheTTL: router.prefetchCacheTTL,
               stateCookieName: router.resolvedStateCookieName,
               themeConfig: router.themeConfig,
               warmupEnabled: router.warmupEnabled,
-              initialTheme: requireRequestContext().theme,
+              strictMode: router.strictMode,
+              initialTheme: getRequestContext().theme,
             },
           };
 
@@ -1126,7 +1165,7 @@ export function createRSCHandler<
             request,
             env,
             url,
-            requireRequestContext()._metricsStore,
+            getRequestContext()._metricsStore,
           );
           const htmlStream = await ssrModule.renderHTML(rscStream, {
             nonce,

package/src/rsc/helpers.ts

@@ -65,8 +65,14 @@ function applyStubHeaders(target: Headers, stub: Headers): void {
  * Drain ctx._onResponseCallbacks onto a response. Swapping the array before
  * iteration prevents re-entrant registrations from double-firing and matches
  * the contract that each callback runs at most once per request.
+ *
+ * Exported so the testing primitives' buildRunResponse can reuse the exact
+ * production drain (swap-before-iterate + external-redirect brand preservation)
+ * rather than maintain a hand-synced copy. This module is plugin-rsc-free on its
+ * eager graph (dispatch.ts already statically imports from here in the same
+ * testing barrel), so importing it adds nothing to the unit runner's graph.
  */
-function drainOnResponseCallbacks(
+export function drainOnResponseCallbacks(
   ctx: RequestContext,
   response: Response,
 ): Response {

package/src/rsc/index.ts

@@ -30,7 +30,4 @@ export type {
 } from "./types.js";
 
 // Re-export request context utilities for server-side access to env/request/params
-export {
-  getRequestContext,
-  requireRequestContext,
-} from "../server/request-context.js";
+export { getRequestContext } from "../server/request-context.js";