@rangojs/router 0.0.0-experimental.77 → 0.0.0-experimental.77ed8945

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

@@ -114,6 +114,9 @@ let _deserializeSegments:
 let _restoreHandles:
   | typeof import("../../cache/handle-snapshot.js").restoreHandles
   | undefined;
+let _decodeHandles:
+  | typeof import("../../cache/handle-snapshot.js").decodeHandles
+  | undefined;
 let _hashParams:
   | typeof import("../../prerender/param-hash.js").hashParams
   | undefined;
@@ -148,6 +151,7 @@ async function ensurePrerenderDeps() {
     ]);
     _deserializeSegments = codec.deserializeSegments;
     _restoreHandles = snapshot.restoreHandles;
+    _decodeHandles = snapshot.decodeHandles;
     _hashParams = paramHash.hashParams;
     _lazyGetRequestContext = reqCtx.getRequestContext;
     if (prerenderStoreInstance === undefined) {
@@ -174,6 +178,7 @@ async function* yieldFromStore<TEnv>(
   if (
     !_deserializeSegments ||
     !_restoreHandles ||
+    !_decodeHandles ||
     !_hashParams ||
     !_lazyGetRequestContext
   ) {
@@ -182,11 +187,15 @@ async function* yieldFromStore<TEnv>(
 
   const segments = await _deserializeSegments(entry.segments);
 
-  // Replay handle data (same as runtime cache hit path).
-  // Prefer the eagerly-captured handleStoreRef to avoid ALS disruption in workerd.
+  // Replay handle data (same as runtime cache hit path). entry.handles is a
+  // Flight-encoded string ("" when none) — decode before restore so
+  // Promise/ReactNode handle values are revived, not the corrupted JSON form.
   const handleStore = handleStoreRef ?? _lazyGetRequestContext()?._handleStore;
-  if (handleStore) {
-    _restoreHandles(entry.handles, handleStore);
+  if (handleStore && entry.handles) {
+    const handlesRecord = await _decodeHandles(entry.handles);
+    if (handlesRecord) {
+      _restoreHandles(handlesRecord, handleStore);
+    }
   }
 
   state.cacheHit = true;
@@ -282,6 +291,38 @@ async function* yieldFromStore<TEnv>(
   }
 }
 
+/**
+ * Look up a prerendered (build-time cached) entry for the current route and, on
+ * a hit, yield its segments. Returns true when an entry was served (the caller
+ * should stop the pipeline) and false on a miss. Intercept navigations consult
+ * only the intercept-specific entry (`paramHash + "/i"`); a miss there falls
+ * through to the normal pipeline so intercept-resolution can run. Callers must
+ * guard on `prerenderStoreInstance` after `ensurePrerenderDeps()`.
+ */
+async function* tryPrerenderLookup<TEnv>(
+  ctx: MatchContext<TEnv>,
+  state: MatchPipelineState,
+  pipelineStart: number,
+  handleStoreRef?: HandleStore,
+): AsyncGenerator<ResolvedSegment, boolean> {
+  const paramHash = _hashParams!(ctx.matched.params);
+  const isPassthroughPrerenderRoute = ctx.entries.some(
+    (entry) => entry.type === "route" && entry.isPassthrough === true,
+  );
+  const lookupHash = ctx.isIntercept ? paramHash + "/i" : paramHash;
+  const entry = await prerenderStoreInstance!.get(
+    ctx.matched.routeKey,
+    lookupHash,
+    {
+      pathname: ctx.pathname,
+      isPassthroughRoute: isPassthroughPrerenderRoute,
+    },
+  );
+  if (!entry) return false;
+  yield* yieldFromStore(entry, ctx, state, pipelineStart, handleStoreRef);
+  return true;
+}
+
 /**
  * Async generator middleware type
  */
@@ -334,54 +375,13 @@ export function withCacheLookup<TEnv>(
     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.isPassthrough === true,
+        const served = yield* tryPrerenderLookup(
+          ctx,
+          state,
+          pipelineStart,
+          handleStoreRef,
         );
-
-        if (ctx.isIntercept) {
-          // Intercept navigation: try intercept-specific prerender entry
-          const entry = await prerenderStoreInstance.get(
-            ctx.matched.routeKey,
-            paramHash + "/i",
-            {
-              pathname: ctx.pathname,
-              isPassthroughRoute: isPassthroughPrerenderRoute,
-            },
-          );
-          if (entry) {
-            yield* yieldFromStore(
-              entry,
-              ctx,
-              state,
-              pipelineStart,
-              handleStoreRef,
-            );
-            return;
-          }
-          // No intercept prerender -- fall through to normal pipeline
-          // (skip non-intercept prerender to let intercept-resolution run)
-        } else {
-          // Normal navigation: existing behavior
-          const entry = await prerenderStoreInstance.get(
-            ctx.matched.routeKey,
-            paramHash,
-            {
-              pathname: ctx.pathname,
-              isPassthroughRoute: isPassthroughPrerenderRoute,
-            },
-          );
-          if (entry) {
-            yield* yieldFromStore(
-              entry,
-              ctx,
-              state,
-              pipelineStart,
-              handleStoreRef,
-            );
-            return;
-          }
-        }
+        if (served) return;
       }
     }
 
@@ -404,51 +404,13 @@ export function withCacheLookup<TEnv>(
       if (hasStatic) {
         await ensurePrerenderDeps();
         if (prerenderStoreInstance) {
-          const paramHash = _hashParams!(ctx.matched.params);
-          const isPassthroughPrerenderRoute = ctx.entries.some(
-            (entry) => entry.type === "route" && entry.isPassthrough === true,
+          const served = yield* tryPrerenderLookup(
+            ctx,
+            state,
+            pipelineStart,
+            handleStoreRef,
           );
-
-          if (ctx.isIntercept) {
-            const entry = await prerenderStoreInstance.get(
-              ctx.matched.routeKey,
-              paramHash + "/i",
-              {
-                pathname: ctx.pathname,
-                isPassthroughRoute: isPassthroughPrerenderRoute,
-              },
-            );
-            if (entry) {
-              yield* yieldFromStore(
-                entry,
-                ctx,
-                state,
-                pipelineStart,
-                handleStoreRef,
-              );
-              return;
-            }
-            // No intercept prerender -- fall through to normal pipeline
-          } else {
-            const entry = await prerenderStoreInstance.get(
-              ctx.matched.routeKey,
-              paramHash,
-              {
-                pathname: ctx.pathname,
-                isPassthroughRoute: isPassthroughPrerenderRoute,
-              },
-            );
-            if (entry) {
-              yield* yieldFromStore(
-                entry,
-                ctx,
-                state,
-                pipelineStart,
-                handleStoreRef,
-              );
-              return;
-            }
-          }
+          if (served) return;
         }
       }
     }

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

@@ -169,10 +169,11 @@ export function withCacheStore<TEnv>(
     // skip (client already had them). Segments where the handler intentionally
     // returned null are not revalidation skips — re-rendering them will still
     // produce null, so proactive caching would be wasted work.
-    const clientIdSet = new Set(ctx.clientSegmentIds);
     const hasNullComponents = allSegmentsToCache.some(
       (s) =>
-        s.component === null && s.type !== "loader" && clientIdSet.has(s.id),
+        s.component === null &&
+        s.type !== "loader" &&
+        ctx.clientSegmentSet.has(s.id),
     );
 
     const requestCtx = getRequestContext();

package/src/router/match-result.ts

@@ -138,34 +138,38 @@ export async function collectSegments(
 function deduplicateLoaderSegments(
   segments: ResolvedSegment[],
   logPrefix: string,
-): ResolvedSegment[] {
-  // First pass: collect loaderIds of original (non-inherited) segments
-  // and whether their parent entry uses loading()
+): { segments: ResolvedSegment[]; removedIds: Set<string> } {
+  // Single pass: original (non-inherited) loaderIds, all loaderIds grouped by
+  // namespace, and namespaces of segments that declare loading().
   const originalLoaders = new Set<string>();
-  const loadersWithLoading = new Set<string>();
+  const loaderIdsByNamespace = new Map<string, string[]>();
+  const namespacesWithLoading = 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
+    if (s.type === "loader" && s.loaderId) {
+      if (!s._inherited) originalLoaders.add(s.loaderId);
+      const ids = loaderIdsByNamespace.get(s.namespace);
+      if (ids) ids.push(s.loaderId);
+      else loaderIdsByNamespace.set(s.namespace, [s.loaderId]);
+    } else if (
+      s.type !== "loader" &&
+      s.loading !== undefined &&
+      s.loading !== false
+    ) {
+      namespacesWithLoading.add(s.namespace);
     }
   }
-  // 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);
-        }
-      }
+
+  // An inherited loader is needed when it shares a namespace with a
+  // loading-bearing segment (its data sits behind that LoaderBoundary).
+  const loadersWithLoading = new Set<string>();
+  for (const ns of namespacesWithLoading) {
+    for (const id of loaderIdsByNamespace.get(ns) ?? []) {
+      loadersWithLoading.add(id);
     }
   }
 
   const result: ResolvedSegment[] = [];
-  let dedupCount = 0;
+  const removedIds = new Set<string>();
 
   for (const s of segments) {
     if (
@@ -175,17 +179,20 @@ function deduplicateLoaderSegments(
       originalLoaders.has(s.loaderId) &&
       !loadersWithLoading.has(s.loaderId)
     ) {
-      dedupCount++;
+      removedIds.add(s.id);
       continue;
     }
     result.push(s);
   }
 
-  if (dedupCount > 0) {
-    debugLog(logPrefix, `deduped ${dedupCount} inherited loader segment(s)`);
+  if (removedIds.size > 0) {
+    debugLog(
+      logPrefix,
+      `deduped ${removedIds.size} inherited loader segment(s)`,
+    );
   }
 
-  return result;
+  return { segments: result, removedIds };
 }
 
 /**
@@ -244,7 +251,7 @@ export function buildMatchResult<TEnv>(
     );
   }
 
-  const dedupedSegments = deduplicateLoaderSegments(
+  const { segments: dedupedSegments, removedIds } = deduplicateLoaderSegments(
     segmentsToRender,
     logPrefix,
   );
@@ -262,18 +269,32 @@ export function buildMatchResult<TEnv>(
 
   // 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;
 
+  // resolvedIds: every segment whose handler actually ran this request.
+  // For full-match every segment is fresh; for partial-match we filter by
+  // the internal `_handlerRan` flag set in revalidation.ts. Drives the
+  // client's handle-bucket cleanup — a slot that re-resolved and pushed
+  // nothing must have its previous handle data cleared, but `diff` won't
+  // carry it because the segment payload skips null-component cached
+  // segments to save bytes.
+  const resolvedIds = ctx.isFullMatch
+    ? allSegments.map((s) => s.id)
+    : allSegments.filter((s) => s._handlerRan).map((s) => s.id);
+
+  // Strip internal-only fields from the segments going on the wire.
+  const cleanedSegments = dedupedSegments.map((s) => {
+    if (s._handlerRan === undefined) return s;
+    const { _handlerRan: _drop, ...rest } = s;
+    return rest as ResolvedSegment;
+  });
+
   return {
-    segments: dedupedSegments,
+    segments: cleanedSegments,
     matched: matchedIds,
-    diff: dedupedSegments.map((s) => s.id),
+    diff: cleanedSegments.map((s) => s.id),
+    resolvedIds,
     params: ctx.matched.params,
     routeName: ctx.routeKey,
     slots: Object.keys(state.slots).length > 0 ? state.slots : undefined,

package/src/router/metrics.ts

@@ -1,7 +1,7 @@
 /**
  * Router Metrics Utilities
  *
- * Performance metrics collection and reporting for RSC Router.
+ * Performance metrics collection and reporting for Rango.
  */
 
 import type { MetricsStore, PerformanceMetric } from "../server/context";

package/src/router/middleware-types.ts

@@ -14,6 +14,7 @@ import type {
 import type { ScopedReverseFunction } from "../reverse.js";
 import type { Theme } from "../theme/types.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
+import type { RequestScope } from "../types/request-scope.js";
 
 /**
  * Get variable function type
@@ -52,33 +53,15 @@ export interface CookieOptions {
  * Context passed to middleware
  *
  * @template TEnv - Environment type (bindings, variables) - defaults to any for internal flexibility
- * @template TParams - URL params type (typed for route middleware, Record<string, string> for global middleware)
+ * @template TParams - URL params type (typed for route middleware,
+ *   `Record<string, string | undefined>` for global middleware — absent
+ *   optional segments are omitted from the params record at runtime, so
+ *   the index signature must include `undefined`)
  */
 export interface MiddlewareContext<
   TEnv = any,
-  TParams = Record<string, string>,
-> {
-  /** Original request */
-  request: Request;
-
-  /** 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;
-
-  /** URL search params */
-  searchParams: URLSearchParams;
-
-  /** Platform bindings (Cloudflare, etc.) */
-  env: TEnv;
-
+  TParams = Record<string, string | undefined>,
+> extends RequestScope<TEnv> {
   /** URL params extracted from route/middleware pattern */
   params: TParams;
 
@@ -157,7 +140,7 @@ export interface MiddlewareContext<
  * @template TEnv - Environment type - defaults to any for internal flexibility
  * @template TParams - URL params type (typed for route middleware)
  *
- * When using middleware with global augmentation (RSCRouter.Env), explicitly
+ * When using middleware with global augmentation (Rango.Env), explicitly
  * annotate your middleware functions, or the types will be inferred from context:
  *
  * @example
@@ -169,7 +152,10 @@ export interface MiddlewareContext<
  * router.use((ctx, next) => {...}) // ctx is typed from router's TEnv
  * ```
  */
-export type MiddlewareFn<TEnv = any, TParams = Record<string, string>> = (
+export type MiddlewareFn<
+  TEnv = any,
+  TParams = Record<string, string | undefined>,
+> = (
   ctx: MiddlewareContext<TEnv, TParams>,
   next: () => Promise<Response>,
 ) => Response | void | Promise<Response | void>;
@@ -216,5 +202,8 @@ export interface MiddlewareCollectableEntry {
  */
 export interface CollectedMiddleware {
   handler: MiddlewareFn<any, any>;
+  // Internal shape only. The user-facing `MiddlewareContext.params` is
+  // typed `Record<string, string | undefined>` to reflect that absent
+  // optional segments are omitted from the params record at runtime.
   params: Record<string, string>;
 }