@rangojs/router 0.0.0-experimental.98 → 0.0.0-experimental.98914650

package/src/router/request-classification.ts

@@ -23,10 +23,6 @@ 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>;
@@ -40,6 +36,12 @@ interface VersionMismatchPlan<TEnv = any> {
   reloadUrl: string;
 }
 
+interface AppSwitchReloadPlan {
+  mode: "app-switch";
+  /** Clean target URL (internal _rsc_* params stripped) to navigate to. */
+  reloadUrl: string;
+}
+
 interface ResponseRoutePlan<TEnv = any> {
   mode: "response";
   route: RouteSnapshot<TEnv>;
@@ -86,6 +88,7 @@ interface PartialRenderPlan<TEnv = any> {
 export type RequestPlan<TEnv = any> =
   | RedirectPlan<TEnv>
   | VersionMismatchPlan<TEnv>
+  | AppSwitchReloadPlan
   | ResponseRoutePlan<TEnv>
   | LoaderFetchPlan<TEnv>
   | PeRenderPlan<TEnv>
@@ -94,12 +97,13 @@ export type RequestPlan<TEnv = any> =
   | PartialRenderPlan<TEnv>;
 
 /**
- * Plans that have passed the terminal-check gate (version-mismatch handled)
- * and are ready for execution. Always have a `route` field.
+ * Plans that have passed the terminal-check gate (version-mismatch and
+ * app-switch reloads handled) and are ready for execution. Always have a
+ * `route` field.
  */
 export type ExecutableRequestPlan<TEnv = any> = Exclude<
   RequestPlan<TEnv>,
-  VersionMismatchPlan<TEnv>
+  VersionMismatchPlan<TEnv> | AppSwitchReloadPlan
 >;
 
 /**
@@ -116,10 +120,6 @@ export type {
   PartialRenderPlan,
 };
 
-// ---------------------------------------------------------------------------
-// classifyRequest — the single authoritative classification step
-// ---------------------------------------------------------------------------
-
 export interface ClassifyRequestDeps<TEnv = any> {
   findMatch: (pathname: string) => RouteMatchResult<TEnv> | null;
   routerVersion: string;
@@ -149,15 +149,12 @@ export async function classifyRequest<TEnv = any>(
   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");
@@ -167,9 +164,7 @@ export async function classifyRequest<TEnv = any>(
           if (refererUrl.origin === url.origin) {
             reloadUrl = referer;
           }
-        } catch {
-          // Malformed referer, fall back to stripped url
-        }
+        } catch {}
       }
     }
 
@@ -179,9 +174,18 @@ export async function classifyRequest<TEnv = any>(
     };
   }
 
-  // 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 clientRouterId = url.searchParams.get("_rsc_rid");
+  if (
+    clientRouterId &&
+    clientRouterId !== deps.routerId &&
+    url.searchParams.has("_rsc_partial")
+  ) {
+    return {
+      mode: "app-switch",
+      reloadUrl: stripInternalParams(url).toString(),
+    };
+  }
+
   const result = await resolveRoute<TEnv>(pathname, {
     findMatch: deps.findMatch,
     lite: true,
@@ -193,7 +197,6 @@ export async function classifyRequest<TEnv = any>(
     });
   }
 
-  // Redirect
   if (result.type === "redirect") {
     const snapshot: RouteSnapshot<TEnv> = {
       matched: result as any,
@@ -215,7 +218,6 @@ export async function classifyRequest<TEnv = any>(
 
   const snapshot = result.snapshot;
 
-  // Response route — non-RSC short-circuit (JSON, streaming, etc.)
   const responseResult = await classifyResponseRoute(
     request,
     pathname,
@@ -225,7 +227,6 @@ export async function classifyRequest<TEnv = any>(
     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");
@@ -243,7 +244,6 @@ export async function classifyRequest<TEnv = any>(
     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") ||
@@ -252,22 +252,13 @@ export async function classifyRequest<TEnv = any>(
     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) {
+  if (url.searchParams.has("_rsc_partial")) {
     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
@@ -278,33 +269,8 @@ async function classifyResponseRoute<TEnv>(
   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;
+  return negotiation
+    ? { mode: "response", route: snapshot, ...negotiation }
+    : null;
 }

package/src/router/revalidation.ts

@@ -4,7 +4,7 @@
  * Evaluates whether segments should revalidate based on params, actions, and custom functions.
  */
 
-import type { ResolvedSegment, HandlerContext } from "../types";
+import type { ResolvedSegment, HandlerContext, ActionRef } from "../types";
 import type { ActionContext } from "./types";
 import {
   debugLog,
@@ -14,21 +14,52 @@ import {
 import type { RevalidationTraceEntry } from "./logging.js";
 import { _getRequestContext } from "../server/request-context.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
+import { paramsEqual } from "./params-util.js";
 
-function paramsEqual(
-  a: Record<string, string>,
-  b: Record<string, string>,
-): boolean {
-  if (a === b) return true;
-
-  const keysA = Object.keys(a);
-  if (keysA.length !== Object.keys(b).length) return false;
-
-  for (const key of keysA) {
-    if (a[key] !== b[key]) return false;
-  }
+/**
+ * Resolve a server-action reference's stable id, mirroring how the action
+ * boundary derives `actionContext.actionId` in `rsc/server-action.ts`
+ * (`$id ?? $$id`): the file-path `$id` set by the expose-action-id plugin in a
+ * production RSC build when present, otherwise React's `$$id`. Resolving both
+ * the incoming `actionId` and the reference with the same precedence makes
+ * `isAction()` form-agnostic across dev and production.
+ */
+function resolveActionRefId(ref: unknown): string | undefined {
+  if (ref == null) return undefined;
+  const r = ref as { $id?: unknown; $$id?: unknown };
+  if (typeof r.$id === "string") return r.$id;
+  if (typeof r.$$id === "string") return r.$$id;
+  return undefined;
+}
 
-  return true;
+/**
+ * Build the `isAction()` helper bound to the current action's id. Called with no
+ * arguments it answers "is this request an action at all?" (any action) — `true`
+ * during action handling, `false` on plain navigation. Called with one or more
+ * action references it narrows to those: a single imported action, several
+ * (variadic), or any export of a namespace import (`import * as Mod`). Returns
+ * `false` when there is no action (plain navigation) or nothing matches.
+ */
+function makeIsAction(
+  currentActionId: string | undefined,
+): (...actions: ActionRef[]) => boolean {
+  return (...actions: ActionRef[]): boolean => {
+    if (!currentActionId) return false;
+    // Bare isAction(): an action is in flight (currentActionId is set) and the
+    // caller did not narrow to a specific action, so this is "any action".
+    if (actions.length === 0) return true;
+    for (const action of actions) {
+      if (typeof action === "function") {
+        if (resolveActionRefId(action) === currentActionId) return true;
+      } else if (action && typeof action === "object") {
+        // Namespace import: match any export of the module.
+        for (const value of Object.values(action)) {
+          if (resolveActionRefId(value) === currentActionId) return true;
+        }
+      }
+    }
+    return false;
+  };
 }
 
 /**
@@ -95,8 +126,6 @@ export async function evaluateRevalidation<TEnv>(
   const paramsChanged = !paramsEqual(nextParams, prevParams);
   const searchChanged = prevUrl.search !== nextUrl.search;
 
-  // Trace helper: push a structured entry to the request-scoped trace buffer.
-  // Guarded by isTraceActive() so object construction is skipped in production.
   function pushTrace(
     defaultVal: boolean,
     finalVal: boolean,
@@ -115,43 +144,28 @@ export async function evaluateRevalidation<TEnv>(
     });
   }
 
-  // Calculate default revalidation based on segment type and request method
   let defaultShouldRevalidate: boolean;
   let defaultReason: string;
 
   if (defaultOverride) {
-    // Caller injected the seed (e.g. parallel slot not in clientSegmentIds).
-    // Skip the type-derived heuristic — caller knows better in this context.
     defaultShouldRevalidate = defaultOverride.value;
     defaultReason = defaultOverride.reason;
   } else if (request.method === "POST") {
-    // Actions: revalidate segments that belong to the route, skip parent chain
     if (segment.type === "route") {
-      // Route segment always revalidates on actions
       defaultShouldRevalidate = true;
       defaultReason = "action:route-segment";
     } else if (segment.type === "loader") {
-      // Loaders always revalidate on actions - they often contain action-sensitive data
-      // (e.g., cart count after add-to-cart action)
       defaultShouldRevalidate = true;
       defaultReason = "action:loader-segment";
     } else if (segment.belongsToRoute) {
-      // Segment belongs to route (orphan layouts/parallels) - revalidate
       defaultShouldRevalidate = true;
       defaultReason = "action:belongs-to-route";
     } else {
-      // Parent chain segment (shared layouts/parallels) - don't revalidate
       defaultShouldRevalidate = false;
       defaultReason = "action:parent-chain-skip";
     }
   } else {
-    // Navigation (GET): Conservative defaults to minimize unnecessary revalidations
-    // Only the route segment revalidates by default - all others require explicit opt-in
-
     if (segment.type === "route") {
-      // Route segments revalidate when path params OR search params change.
-      // Search params (e.g., ?page=2&sort=price) are server-parsed via ctx.search,
-      // so the handler must re-execute to produce updated content.
       const routeChanged = paramsChanged || searchChanged;
       defaultShouldRevalidate = routeChanged;
       defaultReason = paramsChanged
@@ -167,8 +181,6 @@ export async function evaluateRevalidation<TEnv>(
         });
       }
     } else if (segment.belongsToRoute && (paramsChanged || searchChanged)) {
-      // Children of the route path (loaders, orphan layouts/parallels)
-      // revalidate when path params or search params change
       defaultShouldRevalidate = true;
       defaultReason = paramsChanged
         ? "nav:route-child-params-changed"
@@ -180,9 +192,6 @@ export async function evaluateRevalidation<TEnv>(
         searchChanged,
       });
     } else {
-      // Parent layouts and parallels default to no revalidation
-      // Cannot assume these segments depend on params without explicit declaration
-      // Use custom revalidation functions to opt-in when needed
       defaultShouldRevalidate = false;
       defaultReason = "nav:non-route-skip";
       debugLog("revalidation", "non-route segment skipped by default", {
@@ -192,7 +201,6 @@ export async function evaluateRevalidation<TEnv>(
     }
   }
 
-  // No custom revalidations defined - return default behavior without prev segment
   if (revalidations.length === 0) {
     if (defaultShouldRevalidate) {
       debugLog("revalidation", "default revalidate=true", {
@@ -209,14 +217,10 @@ export async function evaluateRevalidation<TEnv>(
     return defaultShouldRevalidate;
   }
 
-  // Custom revalidations exist - may need full prev segment
-  // Lazy load prev segment only if getPrevSegment provided
   const prevSegment = getPrevSegment ? await getPrevSegment() : null;
 
-  // Execute revalidation functions with soft/hard decision pattern
   let currentSuggestion = defaultShouldRevalidate;
 
-  // Compute public route names (filtered: undefined for auto-generated routes)
   const toRouteName =
     routeKey && !isAutoGeneratedRouteName(routeKey) ? routeKey : undefined;
   const reqCtx = _getRequestContext();
@@ -240,23 +244,18 @@ export async function evaluateRevalidation<TEnv>(
       slotName: segment.slot,
       // Action context (only populated when triggered by server action)
       actionId: actionContext?.actionId,
+      isAction: makeIsAction(actionContext?.actionId),
       actionUrl: actionContext?.actionUrl,
       actionResult: actionContext?.actionResult,
       formData: actionContext?.formData,
-      method: request.method, // GET for navigation, POST for actions
-      routeName: toRouteName, // Navigation target route name (filtered)
-      fromRouteName, // Navigation source route name (filtered)
-      toRouteName, // Navigation target route name (filtered)
-      // Stale cache context (only true for background revalidation after stale cache render)
+      method: request.method,
+      routeName: toRouteName,
+      fromRouteName,
+      toRouteName,
       stale,
     });
 
-    // Check return type:
-    // - boolean: hard decision, short-circuit immediately
-    // - { defaultShouldRevalidate: boolean }: soft decision, update suggestion and continue
-    // - null/undefined: use default behavior (equivalent to returning { defaultShouldRevalidate })
     if (typeof result === "boolean") {
-      // Hard decision - short-circuit
       debugLog("revalidation", "hard decision", {
         segmentId: segment.id,
         revalidator: name,
@@ -269,7 +268,6 @@ export async function evaluateRevalidation<TEnv>(
       typeof result === "object" &&
       "defaultShouldRevalidate" in result
     ) {
-      // Soft decision - update suggestion and continue
       currentSuggestion = result.defaultShouldRevalidate;
       debugLog("revalidation", "soft decision", {
         segmentId: segment.id,
@@ -277,18 +275,14 @@ export async function evaluateRevalidation<TEnv>(
         revalidate: currentSuggestion,
       });
     } else if (result === null || result === undefined) {
-      // Defer to default - equivalent to { defaultShouldRevalidate: currentSuggestion }
-      // This means "I don't care, use whatever the default is"
       debugLog("revalidation", "deferred to current default", {
         segmentId: segment.id,
         revalidator: name,
         revalidate: currentSuggestion,
       });
-      // currentSuggestion stays the same, continue to next function
     }
   }
 
-  // All revalidators completed - use final suggestion
   debugLog("revalidation", "final decision", {
     segmentId: segment.id,
     revalidate: currentSuggestion,

package/src/router/route-snapshot.ts

@@ -230,7 +230,6 @@ export function createRouteSnapshot<TEnv = any>(
       entry: {} as any,
       routeKey: "test",
       params: {},
-      optionalParams: new Set(),
     } as RouteMatchResult<TEnv>,
     manifestEntry: { type: "route", shortCode: "R0", parent: null } as any,
     entries: [],

package/src/router/router-context.ts

@@ -54,10 +54,8 @@ export interface InterceptResult {
  * Instead of passing 20+ parameters, middleware calls getRouterContext() to access them.
  */
 export interface RouterContext<TEnv = any> {
-  // Route matching
   findMatch: (pathname: string) => RouteMatchResult | null;
 
-  // Manifest loading
   loadManifest: (
     entry: any,
     routeKey: string,
@@ -66,10 +64,8 @@ export interface RouterContext<TEnv = any> {
     isSSR?: boolean,
   ) => Promise<EntryData>;
 
-  // Entry traversal
   traverseBack: (entry: EntryData) => Generator<EntryData>;
 
-  // Handler context creation
   createHandlerContext: (
     params: Record<string, string>,
     request: Request,
@@ -83,7 +79,6 @@ export interface RouterContext<TEnv = any> {
     isPassthroughRoute?: boolean,
   ) => HandlerContext<any, TEnv>;
 
-  // Loader setup
   setupLoaderAccess: (
     ctx: HandlerContext<any, TEnv>,
     loaderPromises: Map<string, Promise<any>>,
@@ -94,7 +89,6 @@ export interface RouterContext<TEnv = any> {
     loaderPromises: Map<string, Promise<any>>,
   ) => void;
 
-  // Context access
   getContext: () => {
     getOrCreateStore: (key: string) => any;
     runWithStore: <T>(
@@ -105,16 +99,13 @@ export interface RouterContext<TEnv = any> {
     ) => T;
   };
 
-  // Metrics
   getMetricsStore: () => MetricsStore | undefined;
 
-  // Cache
   createCacheScope: (
     cacheConfig: any,
     parent: CacheScope | null,
   ) => CacheScope | null;
 
-  // Intercept detection
   findInterceptForRoute: (
     routeKey: string,
     parentEntry: EntryData | null,
@@ -122,7 +113,6 @@ export interface RouterContext<TEnv = any> {
     isAction: boolean,
   ) => InterceptResult | null;
 
-  // Segment resolution (with revalidation)
   resolveAllSegmentsWithRevalidation: (
     entries: EntryData[],
     routeKey: string,
@@ -133,7 +123,6 @@ export interface RouterContext<TEnv = any> {
     request: Request,
     prevUrl: URL,
     nextUrl: URL,
-    loaderPromises: Map<string, Promise<any>>,
     actionContext: any | undefined,
     interceptResult: InterceptResult | null,
     localRouteName: string,
@@ -166,12 +155,10 @@ export interface RouterContext<TEnv = any> {
     revalidationContext?: RevalidationContext,
   ) => Promise<ResolvedSegment[]>;
 
-  // Collect with markers
   collectWithMarkers?: <T>(
     gen: AsyncGenerator<T | { __type: "id"; id: string }>,
   ) => Promise<{ items: T[]; matchedIds: string[] }>;
 
-  // Revalidation evaluation
   evaluateRevalidation: (params: {
     segment: ResolvedSegment;
     prevParams: Record<string, string>;
@@ -195,7 +182,6 @@ export interface RouterContext<TEnv = any> {
       | "intercept-loader";
   }) => Promise<boolean>;
 
-  // Request context
   getRequestContext: () =>
     | {
         waitUntil: (fn: () => Promise<void>) => void;
@@ -203,7 +189,6 @@ export interface RouterContext<TEnv = any> {
       }
     | undefined;
 
-  // Simple segment resolution (without revalidation - for full match)
   resolveAllSegments: (
     entries: EntryData[],
     routeKey: string,
@@ -213,7 +198,6 @@ export interface RouterContext<TEnv = any> {
     options?: { skipLoaders?: boolean },
   ) => Promise<ResolvedSegment[]>;
 
-  // Generator-based simple resolution
   resolveAllSegmentsGenerator?: (
     entries: EntryData[],
     routeKey: string,
@@ -222,21 +206,17 @@ export interface RouterContext<TEnv = any> {
     loaderPromises: Map<string, Promise<any>>,
   ) => AsyncGenerator<ResolvedSegment | { __type: "id"; id: string }>;
 
-  // Collect segments from generator
   collectSegmentsFromGenerator?: <T>(
     gen: AsyncGenerator<T | { __type: "id"; id: string }>,
   ) => Promise<T[]>;
 
-  // Handle store
   createHandleStore: () => any;
 
-  // Loaders-only resolution (for full match cache hit - no revalidation)
   resolveLoadersOnly?: (
     entries: EntryData[],
     handlerContext: HandlerContext<any, TEnv>,
   ) => Promise<ResolvedSegment[]>;
 
-  // Loaders-only resolution (for cache hit scenarios)
   resolveLoadersOnlyWithRevalidation?: (
     entries: EntryData[],
     handlerContext: HandlerContext<any, TEnv>,
@@ -258,10 +238,8 @@ export interface RouterContext<TEnv = any> {
   // Telemetry sink (optional, no-op when undefined)
   telemetry?: TelemetrySink;
 
-  // Request ID for telemetry span correlation (set per-request in match handlers)
   requestId?: string;
 
-  // Intercept loaders only (for cache hit + intercept scenarios)
   resolveInterceptLoadersOnly?: (
     intercept: InterceptEntry,
     entry: EntryData,
@@ -284,7 +262,6 @@ export interface RouterContext<TEnv = any> {
   } | null>;
 }
 
-// AsyncLocalStorage instance for router context
 const routerContext = new AsyncLocalStorage<RouterContext<any>>();
 
 /**
@@ -308,10 +285,6 @@ export function getRouterContext<TEnv = any>(): RouterContext<TEnv> {
  *
  * All async code within fn() can call getRouterContext() to access router closures.
  * This works across async boundaries thanks to AsyncLocalStorage.
- *
- * @param deps Router dependencies to make available
- * @param fn Function to run with dependencies available
- * @returns Result of fn()
  */
 export function runWithRouterContext<T, TEnv = any>(
   deps: RouterContext<TEnv>,