@rangojs/router 0.0.0-experimental.b9cb8739 → 0.0.0-experimental.c873df95

package/src/router/match-result.ts

@@ -62,15 +62,12 @@
  * SEGMENT FILTERING RULES
  * =======================
  *
- * For partial match, segments are filtered:
- *
- *   Keep if:
- *     - component !== null (needs rendering)
- *     - type === "loader" (carries data even with null component)
- *
- *   Skip if:
- *     - component === null AND type !== "loader"
- *     - (Client already has this segment's UI)
+ * For partial match, all segments are included — even those with
+ * component === null. A null component means the handler returned null
+ * or revalidation was skipped, but the segment is still structurally
+ * required: the client needs it in the diff to reconcile its children
+ * (child layouts, parallels). The client reconciler handles null
+ * components gracefully (preserves cached component if available).
  *
  *
  * INTERCEPT HANDLING
@@ -109,6 +106,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
@@ -167,11 +165,14 @@ 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
-    segmentsToRender = allSegments.filter(
-      (s) => s.component !== null || s.type === "loader",
-    );
+    // Include all segments — even those with null components.
+    // A null component means "no visual output" (handler returned null or
+    // revalidation skipped), but the segment is still structurally required:
+    // the client needs it in the diff to reconcile children (child layouts,
+    // parallels). Filtering null-component segments here would cause the
+    // client to error with "Missing segment" when the ID appears in matched
+    // but is absent from both the server payload and the client cache.
+    segmentsToRender = allSegments;
   }
 
   debugLog(logPrefix, "all segments", {
@@ -210,10 +211,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.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).

package/src/router/router-context.ts

@@ -138,6 +138,7 @@ export interface RouterContext<TEnv = any> {
     interceptResult: InterceptResult | null,
     localRouteName: string,
     pathname: string,
+    stale?: boolean,
   ) => Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }>;
 
   // Generator-based segment resolution (for pipeline)
@@ -188,7 +189,10 @@ export interface RouterContext<TEnv = any> {
       | "cache-hit"
       | "loader"
       | "parallel"
-      | "orphan-layout";
+      | "orphan-layout"
+      | "route-handler"
+      | "layout-handler"
+      | "intercept-loader";
   }) => Promise<boolean>;
 
   // Request context

package/src/router/segment-resolution/fresh.ts

@@ -7,7 +7,11 @@
 
 import type { ReactNode } from "react";
 import { invariant } from "../../errors";
-import type { EntryData } from "../../server/context";
+import {
+  getParallelEntries,
+  getParallelSlotEntries,
+  type EntryData,
+} from "../../server/context";
 import type {
   HandlerContext,
   InternalHandlerContext,
@@ -15,6 +19,8 @@ import type {
 } from "../../types";
 import type { SegmentResolutionDeps } from "../types.js";
 import { resolveLoaderData } from "./loader-cache.js";
+import { _getRequestContext } from "../../server/request-context.js";
+import { appendMetric } from "../metrics.js";
 import {
   handleHandlerResult,
   tryStaticHandler,
@@ -90,8 +96,12 @@ export async function resolveLoaders<TEnv>(
   const shortCode = shortCodeOverride ?? entry.shortCode;
   const hasLoading = "loading" in entry && entry.loading !== undefined;
   const loadingDisabled = hasLoading && entry.loading === false;
+  const ms = _getRequestContext()?._metricsStore;
 
   if (!loadingDisabled) {
+    // Streaming loaders: promises kick off now, settle during RSC serialization.
+    // No per-loader timing here — settlement happens asynchronously during
+    // RSC/SSR stream consumption, after the perf timeline is logged.
     return loaderEntries.map((loaderEntry, i) => {
       const { loader } = loaderEntry;
       const segmentId = `${shortCode}D${i}.${loader.$$id}`;
@@ -116,14 +126,31 @@ export async function resolveLoaders<TEnv>(
 
   // Loading disabled: still start all loaders in parallel, but only emit
   // settled promises so handlers don't stream loading placeholders.
-  const pendingLoaderData = loaderEntries.map((loaderEntry) =>
-    resolveLoaderData(loaderEntry, ctx, ctx.pathname),
-  );
-  await Promise.all(pendingLoaderData);
+  // We can measure actual execution time here since we await all loaders.
+  const pendingLoaderData = loaderEntries.map((loaderEntry) => {
+    const start = performance.now();
+    const promise = resolveLoaderData(loaderEntry, ctx, ctx.pathname);
+    return { promise, start, loaderId: loaderEntry.loader.$$id };
+  });
+  await Promise.all(pendingLoaderData.map((p) => p.promise));
 
   return loaderEntries.map((loaderEntry, i) => {
     const { loader } = loaderEntry;
     const segmentId = `${shortCode}D${i}.${loader.$$id}`;
+    const pending = pendingLoaderData[i]!;
+    if (ms && !ms.metrics.some((m) => m.label === `loader:${loader.$$id}`)) {
+      // All loaders ran in parallel via Promise.all — each span covers
+      // from its own kickoff to the batch settlement, giving a ceiling
+      // on that loader's contribution to the overall wait.
+      const batchEnd = performance.now();
+      appendMetric(
+        ms,
+        `loader:${loader.$$id}`,
+        pending.start,
+        batchEnd - pending.start,
+        2,
+      );
+    }
     return {
       id: segmentId,
       namespace: entry.id,
@@ -133,7 +160,7 @@ export async function resolveLoaders<TEnv>(
       params: ctx.params,
       loaderId: loader.$$id,
       loaderData: deps.wrapLoaderPromise(
-        pendingLoaderData[i]!,
+        pending.promise,
         entry,
         segmentId,
         ctx.pathname,
@@ -197,7 +224,10 @@ export async function resolveSegment<TEnv>(
       ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
     });
 
-    for (const parallelEntry of entry.parallel) {
+    const resolvedParallelEntries = new Set<string>();
+    for (const { slot, entry: parallelEntry } of getParallelSlotEntries(
+      entry.parallel,
+    )) {
       const parallelSegments = await resolveParallelEntry(
         parallelEntry,
         params,
@@ -207,8 +237,11 @@ export async function resolveSegment<TEnv>(
         deps,
         options,
         routeKey,
+        [slot],
+        !resolvedParallelEntries.has(parallelEntry.id),
       );
       segments.push(...parallelSegments);
+      resolvedParallelEntries.add(parallelEntry.id);
     }
 
     for (const orphan of entry.layout) {
@@ -286,7 +319,10 @@ export async function resolveSegment<TEnv>(
       segments.push(...orphanSegments);
     }
 
-    for (const parallelEntry of entry.parallel) {
+    const resolvedParallelEntries = new Set<string>();
+    for (const { slot, entry: parallelEntry } of getParallelSlotEntries(
+      entry.parallel,
+    )) {
       const parallelSegments = await resolveParallelEntry(
         parallelEntry,
         params,
@@ -296,8 +332,11 @@ export async function resolveSegment<TEnv>(
         deps,
         options,
         routeKey,
+        [slot],
+        !resolvedParallelEntries.has(parallelEntry.id),
       );
       segments.push(...parallelSegments);
+      resolvedParallelEntries.add(parallelEntry.id);
     }
 
     segments.push({
@@ -305,7 +344,7 @@ export async function resolveSegment<TEnv>(
       namespace: entry.id,
       type: "route",
       index: 0,
-      component,
+      component: component ?? null,
       loading: entry.loading === false ? null : entry.loading,
       transition: entry.transition,
       params,
@@ -368,7 +407,10 @@ export async function resolveOrphanLayout<TEnv>(
     ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
   });
 
-  for (const parallelEntry of orphan.parallel) {
+  const resolvedParallelEntries = new Set<string>();
+  for (const { slot, entry: parallelEntry } of getParallelSlotEntries(
+    orphan.parallel,
+  )) {
     const parallelSegments = await resolveParallelEntry(
       parallelEntry,
       params,
@@ -378,8 +420,11 @@ export async function resolveOrphanLayout<TEnv>(
       deps,
       options,
       routeKey,
+      [slot],
+      !resolvedParallelEntries.has(parallelEntry.id),
     );
     segments.push(...parallelSegments);
+    resolvedParallelEntries.add(parallelEntry.id);
   }
 
   return segments;
@@ -397,6 +442,8 @@ export async function resolveParallelEntry<TEnv>(
   deps: SegmentResolutionDeps<TEnv>,
   options?: ResolveSegmentOptions,
   routeKey?: string,
+  slotNames?: `@${string}`[],
+  includeLoaders: boolean = true,
 ): Promise<ResolvedSegment[]> {
   invariant(
     parallelEntry.type === "parallel",
@@ -411,7 +458,12 @@ export async function resolveParallelEntry<TEnv>(
     | ReactNode
   >;
 
-  for (const [slot, handler] of Object.entries(slots)) {
+  const slotsToResolve = slotNames ?? (Object.keys(slots) as `@${string}`[]);
+
+  for (const slot of slotsToResolve) {
+    // Try static lookup first — in production, handler bodies are evicted
+    // and replaced with stubs that have no .handler property (undefined).
+    // The static store holds the pre-rendered component for these slots.
     let component: ReactNode | undefined = await tryStaticSlot(
       parallelEntry,
       slot,
@@ -419,6 +471,10 @@ export async function resolveParallelEntry<TEnv>(
     );
 
     if (component === undefined) {
+      const handler = slots[slot];
+      if (handler === undefined) {
+        continue;
+      }
       const doneParallelHandler = track(
         `handler:${parallelEntry.id}.${slot}`,
         2,
@@ -472,7 +528,7 @@ export async function resolveParallelEntry<TEnv>(
     });
   }
 
-  if (!parallelEntry.loading && !options?.skipLoaders) {
+  if (!options?.skipLoaders && includeLoaders) {
     const loaderSegments = await resolveLoaders(
       parallelEntry,
       context,
@@ -480,6 +536,15 @@ export async function resolveParallelEntry<TEnv>(
       deps,
       parentShortCode,
     );
+    // Tag parallel-owned loaders so renderSegments can stream them
+    // using the parallel's loading() instead of awaiting on the layout
+    const parallelLoading =
+      parallelEntry.loading === false ? undefined : parallelEntry.loading;
+    if (parallelLoading) {
+      for (const seg of loaderSegments) {
+        seg.parallelLoading = parallelLoading;
+      }
+    }
     segments.push(...loaderSegments);
   }
 
@@ -559,11 +624,53 @@ export async function resolveLoadersOnly<TEnv>(
   deps: SegmentResolutionDeps<TEnv>,
 ): Promise<ResolvedSegment[]> {
   const loaderSegments: ResolvedSegment[] = [];
+  const seenIds = new Set<string>();
+
+  async function collectEntryLoaders(
+    entry: EntryData,
+    belongsToRoute: boolean,
+    shortCodeOverride?: string,
+  ): Promise<void> {
+    // Skip if all loaders from this entry have already been resolved
+    // via a parent (e.g., cache boundary wrapping a layout with shared loaders).
+    const entryLoaders = entry.loader ?? [];
+    const sc = shortCodeOverride ?? entry.shortCode;
+    const allAlreadySeen =
+      entryLoaders.length > 0 &&
+      entryLoaders.every((le, i) =>
+        seenIds.has(`${sc}D${i}.${le.loader.$$id}`),
+      );
+    if (!allAlreadySeen) {
+      const segments = await resolveLoaders(
+        entry,
+        context,
+        belongsToRoute,
+        deps,
+        shortCodeOverride,
+      );
+      for (const seg of segments) {
+        if (!seenIds.has(seg.id)) {
+          seenIds.add(seg.id);
+          loaderSegments.push(seg);
+        }
+      }
+    }
+
+    const seenParallelEntryIds = new Set<string>();
+    for (const parallelEntry of getParallelEntries(entry.parallel)) {
+      if (seenParallelEntryIds.has(parallelEntry.id)) continue;
+      seenParallelEntryIds.add(parallelEntry.id);
+      await collectEntryLoaders(parallelEntry, belongsToRoute, entry.shortCode);
+    }
+
+    const childBelongsToRoute = belongsToRoute || entry.type === "route";
+    for (const layoutEntry of entry.layout) {
+      await collectEntryLoaders(layoutEntry, childBelongsToRoute);
+    }
+  }
 
   for (const entry of entries) {
-    const belongsToRoute = entry.type === "route";
-    const segments = await resolveLoaders(entry, context, belongsToRoute, deps);
-    loaderSegments.push(...segments);
+    await collectEntryLoaders(entry, entry.type === "route");
   }
 
   return loaderSegments;

package/src/router/segment-resolution/loader-cache.ts

@@ -147,6 +147,7 @@ export function resolveLoaderData<TEnv>(
   }
 
   const loaderId = loaderEntry.loader.$$id;
+
   const ttl = resolveTtl(options.ttl, store.defaults, DEFAULT_ROUTE_TTL);
   const swrWindow = resolveSwrWindow(options.swr, store.defaults);
   const swr = swrWindow || undefined;