@rangojs/router 0.0.0-experimental.29 → 0.0.0-experimental.2a0dea97

package/src/router/match-result.ts

@@ -67,10 +67,11 @@
  *   Keep if:
  *     - component !== null (needs rendering)
  *     - type === "loader" (carries data even with null component)
+ *     - client doesn't have the segment (structurally required parent node)
  *
  *   Skip if:
- *     - component === null AND type !== "loader"
- *     - (Client already has this segment's UI)
+ *     - component === null AND type !== "loader" AND client has it cached
+ *     - (Revalidation skip — client already has this segment's UI)
  *
  *
  * INTERCEPT HANDLING
@@ -109,6 +110,7 @@
 import type { MatchResult, ResolvedSegment } from "../types.js";
 import type { MatchContext, MatchPipelineState } from "./match-context.js";
 import { debugLog } from "./logging.js";
+import { appendMetric } from "./metrics.js";
 
 /**
  * Collect all segments from an async generator
@@ -123,6 +125,69 @@ export async function collectSegments(
   return segments;
 }
 
+/**
+ * Deduplicate inherited loader segments by loaderId.
+ *
+ * When a route has loaders and a child layout has parallel slots, the same
+ * loader is resolved twice: once for the route and once inherited into the
+ * layout (tagged with `_inherited`). The inherited copy is only needed when
+ * the route uses `loading()` — in that case, the loader data is inside a
+ * LoaderBoundary/Suspense that parallel slots can't reach through. Without
+ * loading(), useLoader() traverses parent contexts and finds the data.
+ */
+function deduplicateLoaderSegments(
+  segments: ResolvedSegment[],
+  logPrefix: string,
+): ResolvedSegment[] {
+  // First pass: collect loaderIds of original (non-inherited) segments
+  // and whether their parent entry uses loading()
+  const originalLoaders = new Set<string>();
+  const loadersWithLoading = new Set<string>();
+  for (const s of segments) {
+    if (s.type === "loader" && s.loaderId && !s._inherited) {
+      originalLoaders.add(s.loaderId);
+      // If the segment has a sibling with loading, the parent uses loading()
+      // We detect this by checking if any non-loader segment in the same
+      // namespace has loading defined
+    }
+  }
+  // Check if any layout/route segment has loading — if a loader's namespace
+  // matches a segment with loading, the inherited copy is needed
+  for (const s of segments) {
+    if (s.type !== "loader" && s.loading !== undefined && s.loading !== false) {
+      // Find loaders in this namespace
+      for (const l of segments) {
+        if (l.type === "loader" && l.namespace === s.namespace && l.loaderId) {
+          loadersWithLoading.add(l.loaderId);
+        }
+      }
+    }
+  }
+
+  const result: ResolvedSegment[] = [];
+  let dedupCount = 0;
+
+  for (const s of segments) {
+    if (
+      s.type === "loader" &&
+      s.loaderId &&
+      s._inherited &&
+      originalLoaders.has(s.loaderId) &&
+      !loadersWithLoading.has(s.loaderId)
+    ) {
+      dedupCount++;
+      continue;
+    }
+    result.push(s);
+  }
+
+  if (dedupCount > 0) {
+    debugLog(logPrefix, `deduped ${dedupCount} inherited loader segment(s)`);
+  }
+
+  return result;
+}
+
 /**
  * Build the final MatchResult from collected segments and context
  */
@@ -167,13 +232,23 @@ export function buildMatchResult<TEnv>(
     // Deduplicate allIds (defense-in-depth for partial match path)
     allIds = [...new Set(allIds)];
 
-    // Filter out segments with null components (client already has them)
-    // BUT always include loader segments - they carry data even with null component
+    // Filter out null-component segments only when the client already has
+    // them cached (revalidation skip). If the client doesn't have the segment,
+    // it must be included even with null component — it's structurally required
+    // as a parent node for child layouts/parallels to reconcile against.
+    // Loader segments are always included as they carry data.
+    const clientIdSet = new Set(ctx.clientSegmentIds);
     segmentsToRender = allSegments.filter(
-      (s) => s.component !== null || s.type === "loader",
+      (s) =>
+        s.component !== null || s.type === "loader" || !clientIdSet.has(s.id),
     );
   }
 
+  const dedupedSegments = deduplicateLoaderSegments(
+    segmentsToRender,
+    logPrefix,
+  );
+
   debugLog(logPrefix, "all segments", {
     segments: allSegments.map((s) => ({
       id: s.id,
@@ -182,13 +257,23 @@ export function buildMatchResult<TEnv>(
     })),
   });
   debugLog(logPrefix, "segments to render", {
-    segmentIds: segmentsToRender.map((s) => s.id),
+    segmentIds: dedupedSegments.map((s) => s.id),
   });
 
+  // Remove deduped loader IDs from matched so the client doesn't treat
+  // them as missing segments and trigger a fallback refetch.
+  const removedIds = new Set(
+    segmentsToRender
+      .filter((s) => !dedupedSegments.includes(s))
+      .map((s) => s.id),
+  );
+  const matchedIds =
+    removedIds.size > 0 ? allIds.filter((id) => !removedIds.has(id)) : allIds;
+
   return {
-    segments: segmentsToRender,
-    matched: allIds,
-    diff: segmentsToRender.map((s) => s.id),
+    segments: dedupedSegments,
+    matched: matchedIds,
+    diff: dedupedSegments.map((s) => s.id),
     params: ctx.matched.params,
     routeName: ctx.routeKey,
     slots: Object.keys(state.slots).length > 0 ? state.slots : undefined,
@@ -210,10 +295,19 @@ export async function collectMatchResult<TEnv>(
 ): Promise<MatchResult> {
   const allSegments = await collectSegments(pipeline);
 
+  const buildStart = performance.now();
+
   // Update state with collected segments if not already set
   if (state.segments.length === 0) {
     state.segments = allSegments;
   }
 
-  return buildMatchResult(allSegments, ctx, state);
+  const result = buildMatchResult(allSegments, ctx, state);
+  appendMetric(
+    ctx.metricsStore,
+    "collect-result",
+    buildStart,
+    performance.now() - buildStart,
+  );
+  return result;
 }

package/src/router/metrics.ts

@@ -15,7 +15,12 @@ function formatMs(value: number): string {
 }
 
 function sortMetrics(metrics: PerformanceMetric[]): PerformanceMetric[] {
-  return [...metrics].sort((a, b) => a.startTime - b.startTime);
+  return [...metrics].sort((a, b) => {
+    // handler:total always goes last (it wraps everything)
+    if (a.label === "handler:total") return 1;
+    if (b.label === "handler:total") return -1;
+    return a.startTime - b.startTime;
+  });
 }
 
 interface Span {

package/src/router/middleware-types.ts

@@ -27,8 +27,12 @@ type GetVariableFn = {
  * Set variable function type
  */
 type SetVariableFn = {
-  <T>(contextVar: ContextVar<T>, value: T): void;
-  <K extends keyof DefaultVars>(key: K, value: DefaultVars[K]): void;
+  <T>(contextVar: ContextVar<T>, value: T, options?: { cache?: boolean }): void;
+  <K extends keyof DefaultVars>(
+    key: K,
+    value: DefaultVars[K],
+    options?: { cache?: boolean },
+  ): void;
 };
 
 /**
@@ -57,9 +61,15 @@ export interface MiddlewareContext<
   /** Original request */
   request: Request;
 
-  /** Parsed URL */
+  /** Parsed URL (with internal `_rsc*` params stripped) */
   url: URL;
 
+  /**
+   * The original request URL with all parameters intact, including
+   * internal `_rsc*` transport params.
+   */
+  originalUrl: URL;
+
   /** URL pathname */
   pathname: string;
 
@@ -73,16 +83,7 @@ export interface MiddlewareContext<
   params: TParams;
 
   /**
-   * Response stub (read-only). Before `next()`, returns the shared response stub
-   * where headers and cookies accumulate. After `next()`, returns the downstream response.
-   *
-   * Use `ctx.header()` to set response headers, or `cookies()` for cookie mutations.
-   * To replace the response entirely, return a new `Response` from the middleware.
-   */
-  readonly res: Response;
-
-  /**
-   * Shorthand for ctx.res.headers — response headers.
+   * Response headers.
    * Before `next()`, returns headers from the shared response stub.
    * After `next()`, returns headers from the downstream response.
    */
@@ -95,17 +96,10 @@ export interface MiddlewareContext<
   set: SetVariableFn;
 
   /**
-   * Middleware-injected variables.
-   * Same shared dictionary as `ctx.get()`/`ctx.set()`.
-   */
-  var: DefaultVars;
-
-  /**
-   * Set a response header - can be called before or after `next()`
+   * Set a response header - can be called before or after `next()`.
    *
    * When called before `next()`, headers are queued and merged into the final response.
    * When called after `next()`, headers are set directly on the response.
-   * Shorthand for `ctx.res.headers.set()`.
    */
   header(name: string, value: string): void;
 
@@ -202,7 +196,7 @@ export interface MiddlewareEntry<TEnv = any> {
 }
 
 /**
- * Mutable response holder - allows ctx.res to be updated after next() is called
+ * Mutable response holder - tracks the current response through the middleware chain.
  */
 export interface ResponseHolder {
   response: Response | null;

package/src/router/middleware.ts

@@ -21,6 +21,7 @@ import type {
 import { _getRequestContext } from "../server/request-context.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { appendMetric, createMetricsStore } from "./metrics.js";
+import { stripInternalParams } from "./handler-context.js";
 
 // Re-export types and cookie utilities for backward compatibility
 export type {
@@ -147,7 +148,7 @@ export function createMiddlewareContext<TEnv>(
     search?: Record<string, unknown>,
   ) => string,
 ): MiddlewareContext<TEnv> {
-  const url = new URL(request.url);
+  const url = stripInternalParams(new URL(request.url));
 
   // Track the initial response to detect pre/post-next() phase.
   // Before next(): responseHolder.response === initialResponse (the stub).
@@ -163,9 +164,25 @@ export function createMiddlewareContext<TEnv>(
   // Cookie operations are handled by the standalone cookies() function which
   // delegates to the shared RequestContext internally.
   // The runtime implementation - types are enforced at call sites via MiddlewareContext<TEnv>
+  // Internal helper: resolve the current response (stub before next(), real after).
+  // Not exposed on the public MiddlewareContext type — use ctx.headers instead.
+  const getResponse = (): Response => {
+    if (isPreNext()) {
+      const reqCtx = _getRequestContext();
+      if (reqCtx) return reqCtx.res;
+    }
+    if (!responseHolder.response) {
+      throw new Error(
+        "Response is not available - responseHolder was not initialized",
+      );
+    }
+    return responseHolder.response;
+  };
+
   return {
     request,
     url,
+    originalUrl: new URL(request.url),
     pathname: url.pathname,
     searchParams: url.searchParams,
     env: env as MiddlewareContext<TEnv>["env"],
@@ -180,39 +197,16 @@ export function createMiddlewareContext<TEnv>(
       ) as MiddlewareContext<TEnv>["routeName"];
     },
 
-    get res(): Response {
-      // Before next(): return shared RequestContext stub so headers
-      // set via ctx.header() are visible on ctx.res.
-      if (isPreNext()) {
-        const reqCtx = _getRequestContext();
-        if (reqCtx) return reqCtx.res;
-      }
-      if (!responseHolder.response) {
-        throw new Error(
-          "ctx.res is not available - responseHolder was not initialized",
-        );
-      }
-      return responseHolder.response;
-    },
-    set res(_: Response) {
-      throw new Error(
-        "ctx.res is read-only. Use ctx.header() to set response headers, or cookies() for cookie mutations.",
-      );
-    },
-
     get headers(): Headers {
-      return this.res.headers;
+      return getResponse().headers;
     },
 
     get: ((keyOrVar: any) =>
       contextGet(variables, keyOrVar)) as MiddlewareContext<TEnv>["get"],
 
-    set: ((keyOrVar: any, value: unknown) => {
-      contextSet(variables, keyOrVar, value);
+    set: ((keyOrVar: any, value: unknown, options?: any) => {
+      contextSet(variables, keyOrVar, value, options);
     }) as MiddlewareContext<TEnv>["set"],
-
-    var: variables as MiddlewareContext<TEnv>["var"],
-
     header(name: string, value: string): void {
       // Before next(): delegate to shared RequestContext stub
       if (isPreNext()) {
@@ -302,9 +296,9 @@ export function matchMiddleware<TEnv>(
  *
  * Features:
  * - `await next()` returns actual Response
- * - `ctx.res` available after `await next()` (like Hono's `c.res`)
- * - `ctx.header()` shorthand for setting headers
- * - Forgiving: if middleware doesn't return, uses `ctx.res`
+ * - `ctx.headers` available before and after `await next()`
+ * - `ctx.header()` shorthand for setting a single header
+ * - Forgiving: if middleware doesn't return, uses the downstream response
  * - Short-circuit: return Response to stop chain
  * - Error catching: try/catch around `next()` works
  */

package/src/router/navigation-snapshot.ts

@@ -0,0 +1,182 @@
+/**
+ * Navigation Snapshot
+ *
+ * Pure data type representing the navigation-specific state for partial requests.
+ * Consolidates the header parsing, previous-route matching, intercept-context
+ * detection, and segment ID filtering that previously lived inline in
+ * createMatchContextForPartial (match-api.ts).
+ *
+ * resolveNavigation() is the factory: given a request + URL + current route key,
+ * it returns a NavigationSnapshot (or null if no previous URL).
+ */
+
+import type { RouteMatchResult } from "./pattern-matching.js";
+
+/**
+ * Snapshot of navigation state for a partial (navigation/action) request.
+ *
+ * Contains the "where are we coming from?" data: previous route, intercept
+ * source, client segment state, and derived flags.
+ */
+export interface NavigationSnapshot {
+  /** Previous page URL (from X-RSC-Router-Client-Path or Referer) */
+  prevUrl: URL;
+  /** Params from the previous route match */
+  prevParams: Record<string, string>;
+  /** Previous route match result (null if prev URL doesn't match any route) */
+  prevMatch: RouteMatchResult | null;
+
+  /** URL used as intercept context source */
+  interceptContextUrl: URL;
+  /** Route match for the intercept context URL */
+  interceptContextMatch: RouteMatchResult | null;
+
+  /** Raw segment IDs the client currently has */
+  clientSegmentIds: string[];
+  /** Set version for O(1) lookup */
+  clientSegmentSet: Set<string>;
+  /** Segment IDs filtered to remove parallel (.@) and loader (D\d+.) entries */
+  filteredSegmentIds: string[];
+
+  /** Whether client considers its cache stale */
+  stale: boolean;
+
+  /** Whether the intercept context route is the same as the current route */
+  isSameRouteNavigation: boolean;
+
+  /** Effective "from" URL (intercept source URL when present, else prevUrl) */
+  effectiveFromUrl: URL;
+  /** Effective "from" match (intercept source match when present, else prevMatch) */
+  effectiveFromMatch: RouteMatchResult | null;
+
+  /** Whether an intercept source header was present */
+  hasInterceptSource: boolean;
+
+  /** Whether an HMR request header was present */
+  isHmr: boolean;
+}
+
+export interface ResolveNavigationDeps {
+  findMatch: (pathname: string) => RouteMatchResult | null;
+}
+
+/**
+ * Resolve navigation state from a partial request.
+ *
+ * Returns null if no previous URL is available (required for partial navigation).
+ *
+ * @param request - The incoming HTTP request
+ * @param url - Parsed URL of the request
+ * @param currentRouteKey - Route key of the current (target) route match
+ * @param deps - Dependencies (findMatch)
+ */
+export function resolveNavigation(
+  request: Request,
+  url: URL,
+  currentRouteKey: string,
+  deps: ResolveNavigationDeps,
+): NavigationSnapshot | null {
+  // Parse client state from RSC request params/headers
+  const clientSegmentIds =
+    url.searchParams.get("_rsc_segments")?.split(",").filter(Boolean) || [];
+  const stale = url.searchParams.get("_rsc_stale") === "true";
+  const previousUrl =
+    request.headers.get("X-RSC-Router-Client-Path") ||
+    request.headers.get("Referer");
+  const interceptSourceUrl = request.headers.get(
+    "X-RSC-Router-Intercept-Source",
+  );
+  const isHmr = !!request.headers.get("X-RSC-HMR");
+
+  if (!previousUrl) {
+    return null;
+  }
+
+  // Parse previous URL
+  let prevUrl: URL;
+  try {
+    prevUrl = new URL(previousUrl, url.origin);
+  } catch {
+    return null;
+  }
+
+  // Parse intercept context URL
+  let interceptContextUrl: URL;
+  try {
+    interceptContextUrl = interceptSourceUrl
+      ? new URL(interceptSourceUrl, url.origin)
+      : prevUrl;
+  } catch {
+    interceptContextUrl = prevUrl;
+  }
+
+  // Match previous and intercept context routes
+  const prevMatch = deps.findMatch(prevUrl.pathname);
+  const prevParams = prevMatch?.params || {};
+  const interceptContextMatch = interceptSourceUrl
+    ? deps.findMatch(interceptContextUrl.pathname)
+    : prevMatch;
+
+  // Derived state
+  const isSameRouteNavigation = !!(
+    interceptContextMatch && interceptContextMatch.routeKey === currentRouteKey
+  );
+
+  const hasInterceptSource = !!interceptSourceUrl;
+  const effectiveFromUrl = hasInterceptSource ? interceptContextUrl : prevUrl;
+  const effectiveFromMatch = hasInterceptSource
+    ? interceptContextMatch
+    : prevMatch;
+
+  // Filter segment IDs: remove parallel (.@) and loader (D\d+.) entries
+  const filteredSegmentIds = clientSegmentIds.filter((id) => {
+    if (id.includes(".@")) return false;
+    if (/D\d+\./.test(id)) return false;
+    return true;
+  });
+
+  const clientSegmentSet = new Set(clientSegmentIds);
+
+  return {
+    prevUrl,
+    prevParams,
+    prevMatch,
+    interceptContextUrl,
+    interceptContextMatch,
+    clientSegmentIds,
+    clientSegmentSet,
+    filteredSegmentIds,
+    stale,
+    isSameRouteNavigation,
+    effectiveFromUrl,
+    effectiveFromMatch,
+    hasInterceptSource,
+    isHmr,
+  };
+}
+
+/**
+ * Test helper: create a NavigationSnapshot with sensible defaults and overrides.
+ */
+export function createNavigationSnapshot(
+  overrides?: Partial<NavigationSnapshot>,
+): NavigationSnapshot {
+  const defaultUrl = new URL("http://localhost/");
+  return {
+    prevUrl: defaultUrl,
+    prevParams: {},
+    prevMatch: null,
+    interceptContextUrl: defaultUrl,
+    interceptContextMatch: null,
+    clientSegmentIds: [],
+    clientSegmentSet: new Set(),
+    filteredSegmentIds: [],
+    stale: false,
+    isSameRouteNavigation: false,
+    effectiveFromUrl: defaultUrl,
+    effectiveFromMatch: null,
+    hasInterceptSource: false,
+    isHmr: false,
+    ...overrides,
+  };
+}