@rangojs/router 0.0.0-experimental.49 → 0.0.0-experimental.4ffa0f9b

package/src/router/match-middleware/cache-lookup.ts

@@ -96,6 +96,7 @@ import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext } from "../router-context.js";
 import { resolveSink, safeEmit } from "../telemetry.js";
 import { pushRevalidationTraceEntry, isTraceActive } from "../logging.js";
+import { treeHasStreaming } from "./segment-resolution.js";
 import type { PrerenderStore, PrerenderEntry } from "../../prerender/store.js";
 import type { HandleStore } from "../../server/handle-store.js";
 import {
@@ -193,6 +194,14 @@ async function* yieldFromStore<TEnv>(
   state.cachedSegments = segments;
   state.cachedMatchedIds = segments.map((s) => s.id);
 
+  // Set streaming flag and resolve render barrier.
+  const reqCtx = handleStoreRef ? undefined : _lazyGetRequestContext?.();
+  const barrierReqCtx = reqCtx ?? _getRequestContext();
+  if (barrierReqCtx) {
+    barrierReqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
+    barrierReqCtx._resolveRenderBarrier(segments);
+  }
+
   // For partial navigation, nullify components the client already has
   // so parent layouts stay live (client keeps its existing versions).
   // When params changed (e.g., different guide slug), the segments have
@@ -316,14 +325,15 @@ export function withCacheLookup<TEnv>(
 
     // Prerender lookup: check build-time cached data before runtime cache.
     // Prerender data is available regardless of runtime cache configuration.
-    if (!ctx.isAction && ctx.matched.pr) {
+    // Skip for HMR requests — the dev prerender endpoint reads from a stale
+    // RouterRegistry snapshot; rendering fresh ensures edits are visible.
+    const isHmr = !!ctx.request.headers.get("X-RSC-HMR");
+    if (!ctx.isAction && !isHmr && ctx.matched.pr) {
       await ensurePrerenderDeps();
       if (prerenderStoreInstance) {
         const paramHash = _hashParams!(ctx.matched.params);
         const isPassthroughPrerenderRoute = ctx.entries.some(
-          (entry) =>
-            entry.type === "route" &&
-            entry.prerenderDef?.options?.passthrough === true,
+          (entry) => entry.type === "route" && entry.isPassthrough === true,
         );
 
         if (ctx.isIntercept) {
@@ -393,9 +403,7 @@ export function withCacheLookup<TEnv>(
         if (prerenderStoreInstance) {
           const paramHash = _hashParams!(ctx.matched.params);
           const isPassthroughPrerenderRoute = ctx.entries.some(
-            (entry) =>
-              entry.type === "route" &&
-              entry.prerenderDef?.options?.passthrough === true,
+            (entry) => entry.type === "route" && entry.isPassthrough === true,
           );
 
           if (ctx.isIntercept) {
@@ -615,6 +623,13 @@ export function withCacheLookup<TEnv>(
       yield segment;
     }
 
+    // Set streaming flag and resolve render barrier.
+    const barrierReqCtx = _getRequestContext();
+    if (barrierReqCtx) {
+      barrierReqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
+      barrierReqCtx._resolveRenderBarrier(cacheResult.segments);
+    }
+
     // Resolve loaders fresh (loaders are NOT cached by default)
     // This ensures fresh data even on cache hit
     const Store = ctx.Store;

package/src/router/match-middleware/cache-store.ts

@@ -302,6 +302,11 @@ export function withCacheStore<TEnv>(
       } else {
         // All segments have components - cache directly
         // Schedule caching in waitUntil since cacheRoute is now async (key resolution)
+        if (INTERNAL_RANGO_DEBUG) {
+          console.log(
+            `[RSC CacheStore][req:${reqId}] Direct cache path: scheduling cacheRoute for ${ctx.pathname} (${allSegmentsToCache.length} segments, hasNullComponents=${hasNullComponents})`,
+          );
+        }
         requestCtx.waitUntil(async () => {
           const start = performance.now();
           await cacheScope.cacheRoute(

package/src/router/match-middleware/segment-resolution.ts

@@ -87,10 +87,49 @@
  *   if (state.cacheHit) return;   // Now we can check
  */
 import type { ResolvedSegment } from "../../types.js";
+import type { EntryData } from "../../server/context.js";
+import { _getRequestContext } from "../../server/request-context.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext } from "../router-context.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
 
+/**
+ * Check whether any entry in the tree uses loading() (streaming).
+ * Matches the router's streaming semantics in fresh.ts: streaming is
+ * enabled when `loading` is defined AND not `false`. `loading: false`
+ * explicitly disables streaming; `undefined` means no loading at all.
+ */
+export function treeHasStreaming(entries: EntryData[]): boolean {
+  for (const entry of entries) {
+    if (
+      "loading" in entry &&
+      entry.loading !== undefined &&
+      entry.loading !== false
+    )
+      return true;
+    if (entry.layout) {
+      if (treeHasStreaming(entry.layout)) return true;
+    }
+    if (entry.parallel) {
+      for (const key in entry.parallel) {
+        const parallelEntry = entry.parallel[key as `@${string}`];
+        if (parallelEntry) {
+          if (
+            "loading" in parallelEntry &&
+            parallelEntry.loading !== undefined &&
+            parallelEntry.loading !== false
+          )
+            return true;
+          if (parallelEntry.layout) {
+            if (treeHasStreaming(parallelEntry.layout)) return true;
+          }
+        }
+      }
+    }
+  }
+  return false;
+}
+
 /**
  * Creates segment resolution middleware
  *
@@ -116,6 +155,7 @@ export function withSegmentResolution<TEnv>(
     const ownStart = performance.now();
 
     // If cache hit, segments were already yielded by cache lookup
+    // (render barrier is resolved on the cache-hit path)
     if (state.cacheHit) {
       if (ms) {
         ms.metrics.push({
@@ -127,6 +167,11 @@ export function withSegmentResolution<TEnv>(
       return;
     }
 
+    const reqCtx = _getRequestContext();
+    if (reqCtx) {
+      reqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
+    }
+
     const { resolveAllSegmentsWithRevalidation, resolveAllSegments } =
       getRouterContext<TEnv>();
 
@@ -148,6 +193,10 @@ export function withSegmentResolution<TEnv>(
       state.segments = segments;
       state.matchedIds = segments.map((s: { id: string }) => s.id);
 
+      if (reqCtx) {
+        reqCtx._resolveRenderBarrier(segments);
+      }
+
       // Yield all resolved segments
       for (const segment of segments) {
         yield segment;
@@ -178,6 +227,10 @@ export function withSegmentResolution<TEnv>(
       state.segments = result.segments;
       state.matchedIds = result.matchedIds;
 
+      if (reqCtx) {
+        reqCtx._resolveRenderBarrier(result.segments);
+      }
+
       // Yield all resolved segments
       for (const segment of result.segments) {
         yield segment;

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;
 };
 
 /**
@@ -91,12 +95,6 @@ export interface MiddlewareContext<
   /** Set a context variable (shared with route handlers) */
   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()`.
    *

package/src/router/middleware.ts

@@ -204,12 +204,9 @@ export function createMiddlewareContext<TEnv>(
     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()) {

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,
+  };
+}

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 =