@rangojs/router 0.0.0-experimental.f2337aef → 0.0.0-experimental.f2d1a2f1

package/src/router/prerender-match.ts

@@ -54,6 +54,9 @@ export async function matchForPrerender<TEnv = any>(
   deps: PrerenderMatchDeps<TEnv>,
   buildVars?: Record<string, any>,
   isPassthroughRoute?: boolean,
+  buildEnv?: TEnv,
+  /** Dev-only: check getParams() for passthrough routes to skip unknown params. */
+  devMode?: boolean,
 ): Promise<{
   segments: SerializedSegmentData[];
   handles: Record<string, SegmentHandleData>;
@@ -90,21 +93,106 @@ export async function matchForPrerender<TEnv = any>(
       entries.push(entry);
     }
 
+    // 3b. Dev-mode passthrough shortcut: if the route is a Passthrough route
+    // and has getParams(), check if the matched params are in the known list.
+    // In production, only known params are pre-rendered; unknown params fall
+    // through to the live handler. Mirror that behavior in dev mode to avoid
+    // rendering unknown params with build: true.
+    // Vars collected from getParams() probe — merged into render context below.
+    let devProbeBuildVars: Record<string, any> | undefined;
+
+    if (devMode && matchedPassthroughRoute) {
+      const routeEntry = entries.find(
+        (
+          e,
+        ): e is EntryData & {
+          type: "route";
+          prerenderDef: { getParams: (ctx: any) => Promise<any[]> | any[] };
+        } =>
+          e.type === "route" &&
+          !!(e as any).isPassthrough &&
+          !!(e as any).prerenderDef?.getParams,
+      );
+      if (routeEntry) {
+        try {
+          const probeBuildVars: Record<string, any> = {};
+          const knownParamsList = await routeEntry.prerenderDef.getParams({
+            build: true as const,
+            dev: true,
+            set: ((keyOrVar: any, value: any) => {
+              contextSet(probeBuildVars, keyOrVar, value);
+            }) as any,
+            reverse: createReverseFunction(deps.mergedRouteMap),
+            get env() {
+              if (buildEnv !== undefined) return buildEnv;
+              throw new Error(
+                "[rsc-router] ctx.env is not available during dev-mode getParams(). " +
+                  "Configure buildEnv in your rango() plugin options to enable build-time env access.",
+              );
+            },
+          });
+          // Compare only the keys returned by getParams — ignore mount params
+          // from include() prefixes that aren't part of the handler's params.
+          const isKnown = knownParamsList.some((known: Record<string, any>) => {
+            const knownKeys = Object.keys(known);
+            return knownKeys.every(
+              (k) => String(known[k]) === String(matchedParams[k]),
+            );
+          });
+          if (!isKnown) {
+            return {
+              segments: [],
+              handles: {},
+              routeName: matched.routeKey,
+              params: matchedParams,
+              passthrough: true as const,
+            };
+          }
+          // Preserve vars set by getParams() for the render context
+          if (
+            Object.keys(probeBuildVars).length > 0 ||
+            Object.getOwnPropertySymbols(probeBuildVars).length > 0
+          ) {
+            devProbeBuildVars = probeBuildVars;
+          }
+        } catch (err: any) {
+          // Mirror production semantics (prerender-collection.ts):
+          // Skip errors are intentional — treat as passthrough.
+          // All other errors propagate so dev surfaces them.
+          if (err?.name === "Skip") {
+            return {
+              segments: [],
+              handles: {},
+              routeName: matched.routeKey,
+              params: matchedParams,
+              passthrough: true as const,
+            };
+          }
+          throw err;
+        }
+      }
+    }
+
     // 4. Create handle store for collecting handle data
     const handleStore = createHandleStore();
 
     // 5. Create a minimal request context with the handle store
-    // Shallow-copy getParams vars so each param set is independent
-    const variables: Record<string, any> = buildVars ? { ...buildVars } : {};
+    // Shallow-copy getParams vars so each param set is independent.
+    // In dev mode, merge vars from the getParams() probe if the caller
+    // didn't provide buildVars (production passes them from expandPrerenderRoutes).
+    const effectiveBuildVars = buildVars ?? devProbeBuildVars;
+    const variables: Record<string, any> = effectiveBuildVars
+      ? { ...effectiveBuildVars }
+      : {};
     const stubRes = new Response(null, { status: 200 });
     const minimalRequestContext: RequestContext<TEnv> = {
-      env: {} as TEnv,
+      env: buildEnv ?? ({} as TEnv),
       request: new Request("http://prerender" + pathname),
       url: new URL("http://prerender" + pathname),
       originalUrl: new URL("http://prerender" + pathname),
       pathname,
       searchParams: new URLSearchParams(),
-      var: variables,
+      _variables: variables,
       get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
       set: ((keyOrVar: any, value: any) => {
         contextSet(variables, keyOrVar, value);
@@ -128,6 +216,8 @@ export async function matchForPrerender<TEnv = any>(
       _onResponseCallbacks: [],
       setLocationState() {},
       _locationState: undefined,
+      _renderBarrier: Promise.resolve(),
+      _resolveRenderBarrier: () => {},
       _reportedErrors: new WeakSet<object>(),
       reverse: createReverseFunction(
         deps.mergedRouteMap,
@@ -140,7 +230,7 @@ export async function matchForPrerender<TEnv = any>(
     return runWithRequestContext(minimalRequestContext, async () => {
       // 6. Create prerender context with synthetic URL.
       // Prerender handlers get params, pathname, url, searchParams, search,
-      // reverse, and use(handle) — but no request, env, headers, or cookies.
+      // reverse, use(handle), and optionally env (when buildEnv is configured).
       const buildCtx = createPrerenderContext<TEnv>(
         matchedParams,
         pathname,
@@ -148,6 +238,8 @@ export async function matchForPrerender<TEnv = any>(
         matched.routeKey,
         variables,
         matchedPassthroughRoute,
+        buildEnv,
+        devMode,
       );
 
       // 7. Wire use() for handles only (loaders throw)
@@ -320,6 +412,8 @@ export async function renderStaticSegment<TEnv = any>(
   handlerId: string,
   mergedRouteMap: Record<string, string>,
   routeName?: string,
+  buildEnv?: TEnv,
+  devMode?: boolean,
 ): Promise<{ encoded: string; handles: Record<string, unknown[]> } | null> {
   const syntheticUrl = new URL("http://prerender/");
   const syntheticRequest = new Request(syntheticUrl);
@@ -330,13 +424,13 @@ export async function renderStaticSegment<TEnv = any>(
   // Minimal request context so setupBuildUse can find the HandleStore
   const stubRes = new Response(null, { status: 200 });
   const minimalRequestContext: RequestContext<TEnv> = {
-    env: {} as TEnv,
+    env: buildEnv ?? ({} as TEnv),
     request: syntheticRequest,
     url: syntheticUrl,
     originalUrl: syntheticUrl,
     pathname: "/",
     searchParams: syntheticUrl.searchParams,
-    var: {},
+    _variables: {},
     get: () => undefined as any,
     set: () => {},
     params: {},
@@ -358,6 +452,8 @@ export async function renderStaticSegment<TEnv = any>(
     _onResponseCallbacks: [],
     setLocationState() {},
     _locationState: undefined,
+    _renderBarrier: Promise.resolve(),
+    _resolveRenderBarrier: () => {},
     _reportedErrors: new WeakSet<object>(),
     reverse: createReverseFunction(
       mergedRouteMap,
@@ -368,9 +464,13 @@ export async function renderStaticSegment<TEnv = any>(
   };
 
   return runWithRequestContext(minimalRequestContext, async () => {
-    // Static handlers get only reverse and use(handle) — no URL, params,
-    // request, env, headers, or cookies.
-    const buildCtx = createStaticContext<TEnv>(mergedRouteMap, routeName);
+    // Static handlers get only reverse, use(handle), and optionally env.
+    const buildCtx = createStaticContext<TEnv>(
+      mergedRouteMap,
+      routeName,
+      buildEnv,
+      devMode,
+    );
 
     // Set segment ID so handle pushes are keyed correctly
     (buildCtx as InternalHandlerContext<any, TEnv>)._currentSegmentId =

package/src/router/preview-match.ts

@@ -1,15 +1,9 @@
-import { loadManifest } from "./manifest.js";
-import { traverseBack } from "./pattern-matching.js";
-import { collectRouteMiddleware } from "./middleware.js";
-import {
-  parseAcceptTypes,
-  RSC_RESPONSE_TYPE,
-  pickNegotiateVariant,
-} from "./content-negotiation.js";
+import { negotiateRoute } from "./content-negotiation.js";
 import { runWithRouterLogContext, withRouterLogScope } from "./logging.js";
 import type { EntryData } from "../server/context";
 import type { RouteMatchResult } from "./pattern-matching.js";
 import type { MiddlewareFn } from "./middleware.js";
+import { resolveRoute } from "./route-snapshot.js";
 
 export interface PreviewMatchDeps<TEnv = any> {
   findMatch: (pathname: string) => RouteMatchResult<TEnv> | null;
@@ -42,110 +36,44 @@ export async function previewMatch<TEnv = any>(
         const url = new URL(request.url);
         const pathname = url.pathname;
 
-        // Quick route matching
-        const matched = deps.findMatch(pathname);
-        if (!matched) {
+        // Route resolution via snapshot (lite mode: skip entries/cacheScope
+        // since previewMatch only needs matched, manifestEntry, routeMiddleware,
+        // and responseType)
+        const result = await resolveRoute<TEnv>(pathname, {
+          findMatch: deps.findMatch,
+          lite: true,
+        });
+
+        if (!result) {
           return null;
         }
 
         // Skip redirect check - will be handled in full match
-        if (matched.redirectTo) {
+        if (result.type === "redirect") {
           return { routeMiddleware: undefined };
         }
 
-        // Load manifest (without segment resolution)
-        const manifestEntry = await loadManifest(
-          matched.entry,
-          matched.routeKey,
-          pathname,
-          undefined, // No metrics store for preview
-          false, // isSSR - doesn't matter for preview
-        );
-
-        // Collect route-level middleware from entry tree
-        // Includes middleware from orphan layouts (inline layouts within routes)
-        const routeMiddleware = collectRouteMiddleware(
-          traverseBack(manifestEntry),
-          matched.params,
-        );
-
-        // Check for response type (from trie match or manifest entry)
-        const responseType =
-          matched.responseType ||
-          (manifestEntry.type === "route"
-            ? manifestEntry.responseType
-            : undefined);
-
-        // Content negotiation: when negotiate variants exist, pick the best
-        // handler based on the Accept header. Uses q-values and client order
-        // as tiebreaker (matching Express/Hono behavior). RSC routes participate
-        // as text/html candidates so browsers naturally get HTML without
-        // special-casing.
-        if (matched.negotiateVariants && matched.negotiateVariants.length > 0) {
-          const acceptEntries = parseAcceptTypes(
-            request.headers.get("accept") || "",
-          );
-
-          // Build candidate list preserving definition order.
-          // For wildcard (*/*) and no-Accept fallback, the first candidate wins.
-          const variants = matched.negotiateVariants;
-          let candidates: Array<{ routeKey: string; responseType: string }>;
-          if (responseType) {
-            // Primary is response-type — include it as a candidate
-            candidates = [
-              ...variants,
-              { routeKey: matched.routeKey, responseType },
-            ];
-          } else {
-            // Primary is RSC — insert as text/html candidate in definition order
-            const rscCandidate = {
-              routeKey: matched.routeKey,
-              responseType: RSC_RESPONSE_TYPE,
-            };
-            candidates = matched.rscFirst
-              ? [rscCandidate, ...variants]
-              : [...variants, rscCandidate];
-          }
-
-          const variant = pickNegotiateVariant(acceptEntries, candidates);
+        const snapshot = result.snapshot;
+        const { matched, manifestEntry, routeMiddleware, responseType } =
+          snapshot;
 
-          // If the winner is RSC, fall through to default RSC handling
-          if (variant.responseType === RSC_RESPONSE_TYPE) {
-            // Fall through — RSC won negotiation
-          } else if (responseType && variant.routeKey === matched.routeKey) {
-            // Fall through — response-type primary won, already set
-          } else {
-            const negotiateEntry = await loadManifest(
-              matched.entry,
-              variant.routeKey,
-              pathname,
-              undefined,
-              false,
-            );
-            // Recompute middleware from the selected variant's entry tree
-            // since different variants can have different middleware chains.
-            const variantMiddleware = collectRouteMiddleware(
-              traverseBack(negotiateEntry),
-              matched.params,
-            );
-            return {
-              routeMiddleware:
-                variantMiddleware.length > 0 ? variantMiddleware : undefined,
-              responseType: variant.responseType,
-              handler:
-                negotiateEntry.type === "route"
-                  ? negotiateEntry.handler
-                  : undefined,
-              params: matched.params,
-              negotiated: true,
-              manifestEntry: negotiateEntry,
-              routeKey: matched.routeKey,
-            };
-          }
+        const negotiation = await negotiateRoute(request, pathname, snapshot);
+        if (negotiation) {
+          return {
+            routeMiddleware:
+              negotiation.routeMiddleware.length > 0
+                ? negotiation.routeMiddleware
+                : undefined,
+            responseType: negotiation.responseType,
+            handler: negotiation.handler,
+            params: matched.params,
+            negotiated: true,
+            manifestEntry: negotiation.manifestEntry,
+            routeKey: matched.routeKey,
+          };
         }
 
-        // If we passed through the negotiation block (variants exist), mark as
-        // negotiated so the handler sets Vary: Accept on the response.
+        // No negotiation or RSC won — return default route info
         const hasVariants =
           matched.negotiateVariants && matched.negotiateVariants.length > 0;
         return {

package/src/router/request-classification.ts

@@ -0,0 +1,310 @@
+/**
+ * Request Classification
+ *
+ * Replaces the implicit "preview then match again" model with a clean
+ * two-stage architecture:
+ *
+ * 1. Classification — classifyRequest() produces a RequestPlan that answers
+ *    all routing questions once: target route, request mode, route middleware,
+ *    response-route info, negotiation state.
+ *
+ * 2. Execution — executeRequest() dispatches on the plan to the appropriate
+ *    handler (response route, loader fetch, full render, partial render,
+ *    action revalidation, PE render).
+ *
+ * Builds on RouteSnapshot from route-snapshot.ts.
+ */
+
+import { RouteNotFoundError } from "../errors.js";
+import type { EntryData } from "../server/context.js";
+import type { CollectedMiddleware } from "./middleware-types.js";
+import type { RouteMatchResult } from "./pattern-matching.js";
+import { negotiateRoute } from "./content-negotiation.js";
+import { stripInternalParams } from "./handler-context.js";
+import { resolveRoute, type RouteSnapshot } from "./route-snapshot.js";
+
+// ---------------------------------------------------------------------------
+// RequestPlan — discriminated union
+// ---------------------------------------------------------------------------
+
+interface RedirectPlan<TEnv = any> {
+  mode: "redirect";
+  route: RouteSnapshot<TEnv>;
+  redirectUrl: string;
+}
+
+interface VersionMismatchPlan<TEnv = any> {
+  mode: "version-mismatch";
+  /** May be undefined when version mismatch is detected before route resolution */
+  route?: RouteSnapshot<TEnv>;
+  reloadUrl: string;
+}
+
+interface ResponseRoutePlan<TEnv = any> {
+  mode: "response";
+  route: RouteSnapshot<TEnv>;
+  handler: Function;
+  responseType: string;
+  negotiated: boolean;
+  manifestEntry: EntryData;
+  routeMiddleware: CollectedMiddleware[];
+}
+
+interface LoaderFetchPlan<TEnv = any> {
+  mode: "loader";
+  route: RouteSnapshot<TEnv>;
+}
+
+interface PeRenderPlan<TEnv = any> {
+  mode: "pe-render";
+  route: RouteSnapshot<TEnv>;
+}
+
+interface ActionPlan<TEnv = any> {
+  mode: "action";
+  route: RouteSnapshot<TEnv>;
+  actionId: string;
+  negotiated: boolean;
+}
+
+interface FullRenderPlan<TEnv = any> {
+  mode: "full-render";
+  route: RouteSnapshot<TEnv>;
+  negotiated: boolean;
+}
+
+interface PartialRenderPlan<TEnv = any> {
+  mode: "partial-render";
+  route: RouteSnapshot<TEnv>;
+  negotiated: boolean;
+}
+
+/**
+ * The output of request classification. A discriminated union where each
+ * variant carries exactly the fields needed for its execution path.
+ */
+export type RequestPlan<TEnv = any> =
+  | RedirectPlan<TEnv>
+  | VersionMismatchPlan<TEnv>
+  | ResponseRoutePlan<TEnv>
+  | LoaderFetchPlan<TEnv>
+  | PeRenderPlan<TEnv>
+  | ActionPlan<TEnv>
+  | FullRenderPlan<TEnv>
+  | PartialRenderPlan<TEnv>;
+
+/**
+ * Plans that have passed the terminal-check gate (version-mismatch handled)
+ * and are ready for execution. Always have a `route` field.
+ */
+export type ExecutableRequestPlan<TEnv = any> = Exclude<
+  RequestPlan<TEnv>,
+  VersionMismatchPlan<TEnv>
+>;
+
+/**
+ * Re-export individual plan types for consumers that need to narrow.
+ */
+export type {
+  RedirectPlan,
+  VersionMismatchPlan,
+  ResponseRoutePlan,
+  LoaderFetchPlan,
+  PeRenderPlan,
+  ActionPlan,
+  FullRenderPlan,
+  PartialRenderPlan,
+};
+
+// ---------------------------------------------------------------------------
+// classifyRequest — the single authoritative classification step
+// ---------------------------------------------------------------------------
+
+export interface ClassifyRequestDeps<TEnv = any> {
+  findMatch: (pathname: string) => RouteMatchResult<TEnv> | null;
+  routerVersion: string;
+  routerId: string;
+}
+
+/**
+ * Classify an incoming request into a RequestPlan.
+ *
+ * This is the single source of truth for request mode detection. It replaces
+ * the scattered previewMatch + isAction/isLoaderFetch/isPartial checks in
+ * handler.ts.
+ *
+ * Classification order:
+ * 1. Route resolution (findMatch + loadManifest via resolveRoute lite)
+ * 2. Redirect detection
+ * 3. Version mismatch
+ * 4. Response route + content negotiation
+ * 5. Mode detection from headers/params
+ */
+export async function classifyRequest<TEnv = any>(
+  request: Request,
+  url: URL,
+  deps: ClassifyRequestDeps<TEnv>,
+): Promise<RequestPlan<TEnv>> {
+  const pathname = url.pathname;
+  const isAction =
+    request.headers.has("rsc-action") || url.searchParams.has("_rsc_action");
+
+  // Version mismatch — runs BEFORE route resolution so stale clients
+  // requesting removed routes get a reload, not a 404.
+  const clientVersion = url.searchParams.get("_rsc_v");
+  if (
+    deps.routerVersion &&
+    clientVersion &&
+    clientVersion !== deps.routerVersion
+  ) {
+    // Strip internal _rsc_* params so the browser reloads to a clean URL
+    let reloadUrl = stripInternalParams(url).toString();
+    if (isAction) {
+      const referer = request.headers.get("referer");
+      if (referer) {
+        try {
+          const refererUrl = new URL(referer);
+          if (refererUrl.origin === url.origin) {
+            reloadUrl = referer;
+          }
+        } catch {
+          // Malformed referer, fall back to stripped url
+        }
+      }
+    }
+
+    return {
+      mode: "version-mismatch",
+      reloadUrl,
+    };
+  }
+
+  // No metricsStore — classification is a lightweight gating step.
+  // Route-matching and manifest-loading metrics belong in the match path
+  // (createMatchContextForFull/Partial) which runs the authoritative resolution.
+  const result = await resolveRoute<TEnv>(pathname, {
+    findMatch: deps.findMatch,
+    lite: true,
+  });
+
+  if (!result) {
+    throw new RouteNotFoundError(`No route matched for ${pathname}`, {
+      cause: { pathname, method: request.method },
+    });
+  }
+
+  // Redirect
+  if (result.type === "redirect") {
+    const snapshot: RouteSnapshot<TEnv> = {
+      matched: result as any,
+      manifestEntry: null as any,
+      entries: [],
+      routeKey: "",
+      localRouteName: "",
+      params: {},
+      routeMiddleware: [],
+      cacheScope: null,
+      isPassthrough: false,
+    };
+    return {
+      mode: "redirect",
+      route: snapshot,
+      redirectUrl: result.redirectTo + url.search,
+    };
+  }
+
+  const snapshot = result.snapshot;
+
+  // Response route — non-RSC short-circuit (JSON, streaming, etc.)
+  const responseResult = await classifyResponseRoute(
+    request,
+    pathname,
+    snapshot,
+  );
+  if (responseResult) {
+    return responseResult;
+  }
+
+  // Mode detection from request signals
+  const actionId =
+    request.headers.get("rsc-action") || url.searchParams.get("_rsc_action");
+  const isLoaderFetch = url.searchParams.has("_rsc_loader");
+
+  const hasVariants =
+    snapshot.matched.negotiateVariants &&
+    snapshot.matched.negotiateVariants.length > 0;
+  const negotiated = !!hasVariants;
+
+  if (isAction && actionId) {
+    return { mode: "action", route: snapshot, actionId, negotiated };
+  }
+
+  if (isLoaderFetch) {
+    return { mode: "loader", route: snapshot };
+  }
+
+  // PE detection: POST with form content-type, but not a server action
+  const contentType = request.headers.get("content-type") || "";
+  const isFormSubmission =
+    contentType.includes("multipart/form-data") ||
+    contentType.includes("application/x-www-form-urlencoded");
+  if (request.method === "POST" && !isAction && isFormSubmission) {
+    return { mode: "pe-render", route: snapshot };
+  }
+
+  // App switch: client's routerId doesn't match this router
+  const clientRouterId = url.searchParams.get("_rsc_rid");
+  const isAppSwitch = !!(clientRouterId && clientRouterId !== deps.routerId);
+  const isPartial = url.searchParams.has("_rsc_partial") && !isAppSwitch;
+
+  if (isPartial) {
+    return { mode: "partial-render", route: snapshot, negotiated };
+  }
+
+  return { mode: "full-render", route: snapshot, negotiated };
+}
+
+// ---------------------------------------------------------------------------
+// Content negotiation for response routes
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if the route is a response route and perform content negotiation
+ * if negotiate variants exist. Returns a ResponseRoutePlan if the route
+ * is a response route, null otherwise (RSC route).
+ */
+async function classifyResponseRoute<TEnv>(
+  request: Request,
+  pathname: string,
+  snapshot: RouteSnapshot<TEnv>,
+): Promise<ResponseRoutePlan<TEnv> | null> {
+  const { manifestEntry, responseType } = snapshot;
+
+  const negotiation = await negotiateRoute(request, pathname, snapshot);
+  if (negotiation) {
+    return {
+      mode: "response",
+      route: snapshot,
+      ...negotiation,
+    };
+  }
+
+  // Non-negotiated response route (no variants, or RSC won negotiation)
+  if (responseType) {
+    const handler =
+      manifestEntry.type === "route" ? manifestEntry.handler : undefined;
+    if (handler) {
+      return {
+        mode: "response",
+        route: snapshot,
+        handler,
+        responseType,
+        negotiated: false,
+        manifestEntry,
+        routeMiddleware: snapshot.routeMiddleware,
+      };
+    }
+  }
+
+  return null;
+}