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

package/src/router/match-result.ts

@@ -111,10 +111,8 @@ 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";
+import { collectInterceptTargetNames } from "./intercept-resolution.js";
 
-/**
- * Collect all segments from an async generator
- */
 export async function collectSegments(
   generator: AsyncGenerator<ResolvedSegment>,
 ): Promise<ResolvedSegment[]> {
@@ -138,34 +136,36 @@ 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);
-        }
-      }
+
+  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,22 +175,22 @@ 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 };
 }
 
-/**
- * Build the final MatchResult from collected segments and context
- */
 export function buildMatchResult<TEnv>(
   allSegments: ResolvedSegment[],
   ctx: MatchContext<TEnv>,
@@ -202,92 +202,90 @@ export function buildMatchResult<TEnv>(
 
   let allIds: string[];
   let segmentsToRender: ResolvedSegment[];
+  let resolvedIds: string[];
 
   if (ctx.isFullMatch) {
-    // Full match (document request) - all segments are rendered
-    // Deduplicate by segment ID (defense-in-depth). The primary dedup is in
-    // resolveAllSegments, but this guards against any path that bypasses it.
-    // include() scopes can produce entries that resolve the same shared layout,
-    // and duplicate IDs change the client's React tree depth causing remounts.
+    // One pass over allSegments: dedup by id (segmentsToRender + allIds) while
+    // collecting every id for resolvedIds, which keeps duplicates unlike allIds.
     const seen = new Set<string>();
     segmentsToRender = [];
+    allIds = [];
+    resolvedIds = [];
     for (const s of allSegments) {
+      resolvedIds.push(s.id);
       if (!seen.has(s.id)) {
         seen.add(s.id);
         segmentsToRender.push(s);
+        allIds.push(s.id);
       }
     }
-    allIds = segmentsToRender.map((s) => s.id);
   } else {
-    // Partial match (navigation) - filter and handle intercepts
-    // When intercepting, tell browser to keep its current segments + add modal
-    // This prevents the browser from discarding the current page content
-    // If client sent empty segments (HMR recovery), use segment IDs from allSegments
     allIds = ctx.interceptResult
       ? ctx.clientSegmentIds.length > 0
         ? [...ctx.clientSegmentIds, ...state.interceptSegments.map((s) => s.id)]
-        : allSegments.map((s) => s.id) // Use actual segments, not matchedIds
+        : allSegments.map((s) => s.id)
       : [...state.matchedIds, ...state.interceptSegments.map((s) => s.id)];
 
-    // Deduplicate allIds (defense-in-depth for partial match path)
     allIds = [...new Set(allIds)];
 
-    // 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.
+    // One pass over allSegments: keep renderable segments and collect the
+    // handler-ran ids (resolvedIds) together.
     const clientIdSet = new Set(ctx.clientSegmentIds);
-    segmentsToRender = allSegments.filter(
-      (s) =>
-        s.component !== null || s.type === "loader" || !clientIdSet.has(s.id),
-    );
+    segmentsToRender = [];
+    resolvedIds = [];
+    for (const s of allSegments) {
+      if (s._handlerRan) resolvedIds.push(s.id);
+      if (
+        s.component !== null ||
+        s.type === "loader" ||
+        !clientIdSet.has(s.id)
+      ) {
+        segmentsToRender.push(s);
+      }
+    }
   }
 
-  const dedupedSegments = deduplicateLoaderSegments(
+  const { segments: dedupedSegments, removedIds } = deduplicateLoaderSegments(
     segmentsToRender,
     logPrefix,
   );
 
-  debugLog(logPrefix, "all segments", {
-    segments: allSegments.map((s) => ({
-      id: s.id,
-      type: s.type,
-      hasComponent: s.component !== null,
-    })),
-  });
-  debugLog(logPrefix, "segments to render", {
-    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;
 
+  // One pass over dedupedSegments: strip the internal _handlerRan marker and
+  // collect the diff ids (id is unchanged by the strip) together.
+  const cleanedSegments: ResolvedSegment[] = [];
+  const diff: string[] = [];
+  for (const s of dedupedSegments) {
+    if (s._handlerRan === undefined) {
+      cleanedSegments.push(s);
+    } else {
+      const { _handlerRan: _drop, ...rest } = s;
+      cleanedSegments.push(rest as ResolvedSegment);
+    }
+    diff.push(s.id);
+  }
+
+  // Intercept targets reachable when THIS location becomes a navigation
+  // origin — the browser-local clientUrls matcher declines its optimistic
+  // presentation for these (see collectInterceptTargetNames).
+  const interceptTargets = collectInterceptTargetNames(ctx.manifestEntry);
+
   return {
-    segments: dedupedSegments,
+    segments: cleanedSegments,
     matched: matchedIds,
-    diff: dedupedSegments.map((s) => s.id),
+    diff,
+    resolvedIds,
     params: ctx.matched.params,
     routeName: ctx.routeKey,
     slots: Object.keys(state.slots).length > 0 ? state.slots : undefined,
+    ...(interceptTargets.length > 0 ? { interceptTargets } : {}),
     routeMiddleware:
       ctx.routeMiddleware.length > 0 ? ctx.routeMiddleware : undefined,
   };
 }
 
-/**
- * Collect segments from pipeline and build MatchResult
- *
- * This is the main entry point for building the final result after
- * the pipeline has processed all segments.
- */
 export async function collectMatchResult<TEnv>(
   pipeline: AsyncGenerator<ResolvedSegment>,
   ctx: MatchContext<TEnv>,
@@ -297,7 +295,6 @@ export async function collectMatchResult<TEnv>(
 
   const buildStart = performance.now();
 
-  // Update state with collected segments if not already set
   if (state.segments.length === 0) {
     state.segments = allSegments;
   }

package/src/router/metrics.ts

@@ -1,9 +1,3 @@
-/**
- * Router Metrics Utilities
- *
- * Performance metrics collection and reporting for RSC Router.
- */
-
 import type { MetricsStore, PerformanceMetric } from "../server/context";
 
 const BASE_INDENT = 2;
@@ -16,7 +10,6 @@ function formatMs(value: number): string {
 
 function sortMetrics(metrics: PerformanceMetric[]): PerformanceMetric[] {
   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;
@@ -68,11 +61,6 @@ function createTimelineAxis(total: number): string {
   )}${totalLabel}`;
 }
 
-/**
- * Create a metrics store for the request if debugPerformance is enabled.
- * An optional `requestStart` timestamp can anchor the store to an earlier
- * point (e.g. handler start) so that handler:total has startTime=0.
- */
 export function createMetricsStore(
   debugPerformance: boolean,
   requestStart?: number,
@@ -85,15 +73,13 @@ export function createMetricsStore(
   };
 }
 
-/**
- * Append a metric to the request store using an absolute start timestamp.
- */
 export function appendMetric(
   metricsStore: MetricsStore | undefined,
   label: string,
   start: number,
   duration: number,
   depth?: number,
+  desc?: string,
 ): void {
   if (!metricsStore) return;
   metricsStore.metrics.push({
@@ -101,12 +87,10 @@ export function appendMetric(
     duration,
     startTime: start - metricsStore.requestStart,
     depth,
+    desc,
   });
 }
 
-/**
- * Log the current request metrics and return the corresponding Server-Timing value.
- */
 export function buildMetricsTiming(
   method: string,
   pathname: string,
@@ -117,21 +101,16 @@ export function buildMetricsTiming(
   return generateServerTiming(metricsStore) || undefined;
 }
 
-/** Display row produced by merging :pre/:post metric pairs. */
 interface DisplayRow {
   label: string;
   startTime: number;
   duration: number;
   depth: number | undefined;
+  desc: string | undefined;
   spans: Span[];
 }
 
-/**
- * Build display rows from sorted metrics, merging :pre/:post pairs into
- * a single row with disjoint timeline segments.
- */
 function buildDisplayRows(sorted: PerformanceMetric[]): DisplayRow[] {
-  // Index :pre and :post metrics by their base label
   const preMap = new Map<string, PerformanceMetric>();
   const postMap = new Map<string, PerformanceMetric>();
   const consumed = new Set<PerformanceMetric>();
@@ -161,6 +140,7 @@ function buildDisplayRows(sorted: PerformanceMetric[]): DisplayRow[] {
           startTime: m.startTime,
           duration: m.duration + post.duration,
           depth: m.depth,
+          desc: m.desc,
           spans: [
             { startTime: m.startTime, duration: m.duration },
             { startTime: post.startTime, duration: post.duration },
@@ -175,6 +155,7 @@ function buildDisplayRows(sorted: PerformanceMetric[]): DisplayRow[] {
         startTime: m.startTime,
         duration: m.duration,
         depth: m.depth,
+        desc: m.desc,
         spans: [{ startTime: m.startTime, duration: m.duration }],
       });
       continue;
@@ -193,6 +174,7 @@ function buildDisplayRows(sorted: PerformanceMetric[]): DisplayRow[] {
         startTime: m.startTime,
         duration: m.duration,
         depth: m.depth,
+        desc: m.desc,
         spans: [{ startTime: m.startTime, duration: m.duration }],
       });
       continue;
@@ -204,6 +186,7 @@ function buildDisplayRows(sorted: PerformanceMetric[]): DisplayRow[] {
       startTime: m.startTime,
       duration: m.duration,
       depth: m.depth,
+      desc: m.desc,
       spans: [{ startTime: m.startTime, duration: m.duration }],
     });
   }
@@ -211,11 +194,6 @@ function buildDisplayRows(sorted: PerformanceMetric[]): DisplayRow[] {
   return rows;
 }
 
-/**
- * Log metrics to console in a formatted way.
- * Uses a shared-axis timeline so overlapping work stays visible.
- * Merges :pre/:post pairs onto one row with disjoint timeline segments.
- */
 export function logMetrics(
   method: string,
   pathname: string,
@@ -228,7 +206,9 @@ export function logMetrics(
 
   const labels = displayRows.map(
     (r) =>
-      `${" ".repeat(BASE_INDENT + (r.depth ?? 0) * DEPTH_INDENT)}${r.label}`,
+      `${" ".repeat(BASE_INDENT + (r.depth ?? 0) * DEPTH_INDENT)}${r.label}${
+        r.desc ? ` (${r.desc})` : ""
+      }`,
   );
   const startValues = displayRows.map((r) => formatMs(r.startTime));
   const durationValues = displayRows.map((r) => formatMs(r.duration));
@@ -267,11 +247,6 @@ export function logMetrics(
   }
 }
 
-/**
- * Generate Server-Timing header value from metrics
- * Format: metric-name;dur=X.XX
- * Depth is encoded as a "d{N}-" prefix for nested metrics.
- */
 export function generateServerTiming(metricsStore: MetricsStore): string {
   return metricsStore.metrics
     .map((m) => {
@@ -281,7 +256,13 @@ export function generateServerTiming(metricsStore: MetricsStore): string {
         .replace(/[^a-zA-Z0-9-]/g, "")
         .toLowerCase();
       const name = m.depth ? `d${m.depth}-${base}` : base;
-      return `${name};dur=${m.duration.toFixed(2)}`;
+      // desc is a quoted-string: backslash-escape the two delimiters; our
+      // producers emit plain printable text, so nothing else needs stripping.
+      const desc =
+        m.desc !== undefined
+          ? `;desc="${m.desc.replace(/[\\"]/g, "\\$&")}"`
+          : "";
+      return `${name};dur=${m.duration.toFixed(2)}${desc}`;
     })
     .join(", ");
 }

package/src/router/middleware-types.ts

@@ -1,10 +1,3 @@
-/**
- * Middleware Types
- *
- * Type definitions and interfaces for the middleware system.
- * Separated from execution logic for cleaner imports.
- */
-
 import type { ContextVar } from "../context-var.js";
 import type {
   DefaultReverseRouteMap,
@@ -16,17 +9,11 @@ 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
- */
 type GetVariableFn = {
   <T>(contextVar: ContextVar<T>): T | undefined;
   <K extends keyof DefaultVars>(key: K): DefaultVars[K];
 };
 
-/**
- * Set variable function type
- */
 type SetVariableFn = {
   <T>(contextVar: ContextVar<T>, value: T, options?: { cache?: boolean }): void;
   <K extends keyof DefaultVars>(
@@ -36,9 +23,6 @@ type SetVariableFn = {
   ): void;
 };
 
-/**
- * Cookie options for setting cookies
- */
 export interface CookieOptions {
   domain?: string;
   path?: string;
@@ -49,151 +33,77 @@ export interface CookieOptions {
   sameSite?: "strict" | "lax" | "none";
 }
 
-/**
- * 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)
- */
 export interface MiddlewareContext<
   TEnv = any,
-  TParams = Record<string, string>,
+  TParams = Record<string, string | undefined>,
 > extends RequestScope<TEnv> {
-  /** URL params extracted from route/middleware pattern */
   params: TParams;
 
   /**
-   * Response headers.
-   * Before `next()`, returns headers from the shared response stub.
-   * After `next()`, returns headers from the downstream response.
+   * True for build-time render/capture requests. Live requests use false.
+   * Build-time PPR shell capture sets this while replaying middleware.
    */
+  readonly build: boolean;
+
+  /**
+   * Opt this request out of PPR shell serving/capture.
+   * During middleware this runs before the shell HIT commit point, so it can
+   * force the request onto the dynamic axis.
+   *
+   * Scope: the PPR SHELL axis only. It does NOT disable prerender B-segment
+   * (Prerender/Static) serving — a Prerender() route still replays its
+   * build-baked segments at runtime.
+   */
+  dynamic(): void;
+
   readonly headers: Headers;
 
-  /** Get a context variable (shared with route handlers) */
   get: GetVariableFn;
 
-  /** Set a context variable (shared with route handlers) */
   set: SetVariableFn;
 
-  /**
-   * 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.
-   */
   header(name: string, value: string): void;
 
-  /**
-   * The matched route name, if available and the route has an explicit name.
-   * Undefined for global middleware (runs before route matching) or unnamed routes.
-   */
   routeName?: DefaultRouteName;
 
-  /**
-   * Enable performance metrics for this request.
-   * When called, granular timing breakdown is logged to console and
-   * included in the Server-Timing response header, regardless of the
-   * router-level `debugPerformance` option.
-   *
-   * Call **before** `await next()` so the metrics store exists when
-   * downstream phases (route matching, rendering, SSR) record their
-   * spans. Calling after `next()` returns still emits `handler:total`
-   * but misses all upstream metrics.
-   */
   debugPerformance(): void;
 
-  /**
-   * Current theme (from cookie or default).
-   * Only available when theme is enabled in router config.
-   */
   theme?: Theme;
 
-  /**
-   * Set the theme (only available when theme is enabled in router config).
-   * Sets a cookie with the new theme value.
-   */
   setTheme?: (theme: Theme) => void;
 
-  /**
-   * Attach location state entries to this response.
-   * State is delivered to the client via history.pushState and accessible
-   * through the useLocationState() hook.
-   */
   setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void;
 
-  /**
-   * Generate URLs from route names.
-   * - `name` — global route, from the named-routes definition
-   */
   reverse: ScopedReverseFunction<
     Record<string, string>,
     DefaultReverseRouteMap
   >;
 }
 
-/**
- * Middleware function signature
- *
- * @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
- * annotate your middleware functions, or the types will be inferred from context:
- *
- * @example
- * ```typescript
- * // With explicit annotation (recommended for reusable middleware)
- * const authMiddleware: MiddlewareFn<AppEnv> = async (ctx, next) => {...}
- *
- * // Types inferred from router.use() call
- * 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>;
 
-/**
- * Stored middleware entry with pattern matching info
- * @internal - uses any for internal flexibility
- */
 export interface MiddlewareEntry<TEnv = any> {
-  /** Original pattern string */
   pattern: string | null;
-
-  /** Compiled regex for matching */
   regex: RegExp | null;
-
-  /** Param names extracted from pattern */
   paramNames: string[];
-
-  /** The middleware function */
   handler: MiddlewareFn<TEnv>;
-
-  /** Mount prefix this middleware is scoped to (null = global) */
-  mountPrefix: string | null;
 }
 
-/**
- * Mutable response holder - tracks the current response through the middleware chain.
- */
 export interface ResponseHolder {
   response: Response | null;
 }
 
-/**
- * Entry type for middleware collection
- * Matches the shape of EntryData used in router.ts
- */
 export interface MiddlewareCollectableEntry {
   middleware?: MiddlewareFn<any, any>[];
   layout?: MiddlewareCollectableEntry[];
 }
 
-/**
- * Collected route middleware with params
- */
 export interface CollectedMiddleware {
   handler: MiddlewareFn<any, any>;
   params: Record<string, string>;