@rangojs/router 0.0.0-experimental.19 → 0.0.0-experimental.190fb30d

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
@@ -108,12 +109,9 @@
  */
 import type { MatchResult, ResolvedSegment } from "../types.js";
 import type { MatchContext, MatchPipelineState } from "./match-context.js";
-import { generateServerTiming, logMetrics } from "./metrics.js";
 import { debugLog } from "./logging.js";
+import { appendMetric } from "./metrics.js";
 
-/**
- * Collect all segments from an async generator
- */
 export async function collectSegments(
   generator: AsyncGenerator<ResolvedSegment>,
 ): Promise<ResolvedSegment[]> {
@@ -125,8 +123,73 @@ export async function collectSegments(
 }
 
 /**
- * Build the final MatchResult from collected segments and context
+ * 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,
+): { 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 loaderIdsByNamespace = new Map<string, string[]>();
+  const namespacesWithLoading = new Set<string>();
+  for (const s of segments) {
+    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);
+    }
+  }
+
+  const loadersWithLoading = new Set<string>();
+  for (const ns of namespacesWithLoading) {
+    for (const id of loaderIdsByNamespace.get(ns) ?? []) {
+      loadersWithLoading.add(id);
+    }
+  }
+
+  const result: ResolvedSegment[] = [];
+  const removedIds = new Set<string>();
+
+  for (const s of segments) {
+    if (
+      s.type === "loader" &&
+      s.loaderId &&
+      s._inherited &&
+      originalLoaders.has(s.loaderId) &&
+      !loadersWithLoading.has(s.loaderId)
+    ) {
+      removedIds.add(s.id);
+      continue;
+    }
+    result.push(s);
+  }
+
+  if (removedIds.size > 0) {
+    debugLog(
+      logPrefix,
+      `deduped ${removedIds.size} inherited loader segment(s)`,
+    );
+  }
+
+  return { segments: result, removedIds };
+}
+
 export function buildMatchResult<TEnv>(
   allSegments: ResolvedSegment[],
   ctx: MatchContext<TEnv>,
@@ -138,80 +201,84 @@ 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 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",
-    );
+    // One pass over allSegments: keep renderable segments and collect the
+    // handler-ran ids (resolvedIds) together.
+    const clientIdSet = new Set(ctx.clientSegmentIds);
+    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);
+      }
+    }
   }
 
-  debugLog(logPrefix, "all segments", {
-    segments: allSegments.map((s) => ({
-      id: s.id,
-      type: s.type,
-      hasComponent: s.component !== null,
-    })),
-  });
-  debugLog(logPrefix, "segments to render", {
-    segmentIds: segmentsToRender.map((s) => s.id),
-  });
-
-  // Output metrics if enabled
-  let serverTiming: string | undefined;
-  if (ctx.metricsStore) {
-    logMetrics(ctx.request.method, ctx.pathname, ctx.metricsStore);
-    serverTiming = generateServerTiming(ctx.metricsStore);
+  const { segments: dedupedSegments, removedIds } = deduplicateLoaderSegments(
+    segmentsToRender,
+    logPrefix,
+  );
+
+  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);
   }
 
   return {
-    segments: segmentsToRender,
-    matched: allIds,
-    diff: segmentsToRender.map((s) => s.id),
+    segments: cleanedSegments,
+    matched: matchedIds,
+    diff,
+    resolvedIds,
     params: ctx.matched.params,
     routeName: ctx.routeKey,
-    serverTiming,
     slots: Object.keys(state.slots).length > 0 ? state.slots : undefined,
     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>,
@@ -219,10 +286,18 @@ export async function collectMatchResult<TEnv>(
 ): Promise<MatchResult> {
   const allSegments = await collectSegments(pipeline);
 
-  // Update state with collected segments if not already set
+  const buildStart = performance.now();
+
   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

@@ -1,28 +1,192 @@
-/**
- * Router Metrics Utilities
- *
- * Performance metrics collection and reporting for RSC Router.
- */
+import type { MetricsStore, PerformanceMetric } from "../server/context";
 
-import type { MetricsStore } from "../server/context";
+const BASE_INDENT = 2;
+const DEPTH_INDENT = 2;
+const TIMELINE_WIDTH = 40;
+
+function formatMs(value: number): string {
+  return `${value.toFixed(2)}ms`;
+}
+
+function sortMetrics(metrics: PerformanceMetric[]): PerformanceMetric[] {
+  return [...metrics].sort((a, b) => {
+    if (a.label === "handler:total") return 1;
+    if (b.label === "handler:total") return -1;
+    return a.startTime - b.startTime;
+  });
+}
+
+interface Span {
+  startTime: number;
+  duration: number;
+}
+
+function renderTimeline(spans: Span[], total: number): string {
+  if (TIMELINE_WIDTH <= 0) {
+    return "||";
+  }
+
+  const cells = Array(TIMELINE_WIDTH).fill(".");
+
+  if (!(total > 0)) {
+    cells[0] = "#";
+    return `|${cells.join("")}|`;
+  }
+
+  for (const span of spans) {
+    const start = Math.max(0, span.startTime);
+    const end = Math.max(start, span.startTime + span.duration);
+    const startColumn = Math.min(
+      TIMELINE_WIDTH - 1,
+      Math.floor((start / total) * TIMELINE_WIDTH),
+    );
+    const endColumn = Math.max(
+      startColumn + 1,
+      Math.min(
+        TIMELINE_WIDTH,
+        Math.ceil((Math.min(total, end) / total) * TIMELINE_WIDTH),
+      ),
+    );
+
+    cells.fill("#", startColumn, endColumn);
+  }
+
+  return `|${cells.join("")}|`;
+}
+
+function createTimelineAxis(total: number): string {
+  const totalLabel = formatMs(total);
+  return `0ms${" ".repeat(
+    Math.max(1, TIMELINE_WIDTH - "0ms".length - totalLabel.length),
+  )}${totalLabel}`;
+}
 
-/**
- * Create a metrics store for the request if debugPerformance is enabled
- */
 export function createMetricsStore(
   debugPerformance: boolean,
+  requestStart?: number,
 ): MetricsStore | undefined {
   if (!debugPerformance) return undefined;
   return {
     enabled: true,
-    requestStart: performance.now(),
+    requestStart: requestStart ?? performance.now(),
     metrics: [],
   };
 }
 
-/**
- * Log metrics to console in a formatted way
- */
+export function appendMetric(
+  metricsStore: MetricsStore | undefined,
+  label: string,
+  start: number,
+  duration: number,
+  depth?: number,
+): void {
+  if (!metricsStore) return;
+  metricsStore.metrics.push({
+    label,
+    duration,
+    startTime: start - metricsStore.requestStart,
+    depth,
+  });
+}
+
+export function buildMetricsTiming(
+  method: string,
+  pathname: string,
+  metricsStore: MetricsStore | undefined,
+): string | undefined {
+  if (!metricsStore) return undefined;
+  logMetrics(method, pathname, metricsStore);
+  return generateServerTiming(metricsStore) || undefined;
+}
+
+interface DisplayRow {
+  label: string;
+  startTime: number;
+  duration: number;
+  depth: number | undefined;
+  spans: Span[];
+}
+
+function buildDisplayRows(sorted: PerformanceMetric[]): DisplayRow[] {
+  const preMap = new Map<string, PerformanceMetric>();
+  const postMap = new Map<string, PerformanceMetric>();
+  const consumed = new Set<PerformanceMetric>();
+
+  for (const m of sorted) {
+    if (m.label.endsWith(":pre")) {
+      preMap.set(m.label.slice(0, -4), m);
+    } else if (m.label.endsWith(":post")) {
+      postMap.set(m.label.slice(0, -5), m);
+    }
+  }
+
+  const rows: DisplayRow[] = [];
+
+  for (const m of sorted) {
+    if (consumed.has(m)) continue;
+
+    if (m.label.endsWith(":pre")) {
+      const base = m.label.slice(0, -4);
+      const post = postMap.get(base);
+      if (post) {
+        // Merge into a single row with two disjoint spans
+        consumed.add(m);
+        consumed.add(post);
+        rows.push({
+          label: base,
+          startTime: m.startTime,
+          duration: m.duration + post.duration,
+          depth: m.depth,
+          spans: [
+            { startTime: m.startTime, duration: m.duration },
+            { startTime: post.startTime, duration: post.duration },
+          ],
+        });
+        continue;
+      }
+      // Lone :pre — display with base label
+      consumed.add(m);
+      rows.push({
+        label: base,
+        startTime: m.startTime,
+        duration: m.duration,
+        depth: m.depth,
+        spans: [{ startTime: m.startTime, duration: m.duration }],
+      });
+      continue;
+    }
+
+    if (m.label.endsWith(":post")) {
+      const base = m.label.slice(0, -5);
+      if (preMap.has(base)) {
+        // Already consumed as part of the pair above
+        continue;
+      }
+      // Lone :post — display with base label
+      consumed.add(m);
+      rows.push({
+        label: base,
+        startTime: m.startTime,
+        duration: m.duration,
+        depth: m.depth,
+        spans: [{ startTime: m.startTime, duration: m.duration }],
+      });
+      continue;
+    }
+
+    // Regular metric
+    rows.push({
+      label: m.label,
+      startTime: m.startTime,
+      duration: m.duration,
+      depth: m.depth,
+      spans: [{ startTime: m.startTime, duration: m.duration }],
+    });
+  }
+
+  return rows;
+}
+
 export function logMetrics(
   method: string,
   pathname: string,
@@ -30,32 +194,59 @@ export function logMetrics(
 ): void {
   const total = performance.now() - metricsStore.requestStart;
 
-  // Find max label length for alignment
-  const maxLabelLen = Math.max(
-    ...metricsStore.metrics.map((m) => m.label.length),
-    20,
+  const sorted = sortMetrics(metricsStore.metrics);
+  const displayRows = buildDisplayRows(sorted);
+
+  const labels = displayRows.map(
+    (r) =>
+      `${" ".repeat(BASE_INDENT + (r.depth ?? 0) * DEPTH_INDENT)}${r.label}`,
+  );
+  const startValues = displayRows.map((r) => formatMs(r.startTime));
+  const durationValues = displayRows.map((r) => formatMs(r.duration));
+  const startWidth = Math.max(
+    "start".length,
+    ...startValues.map((v) => v.length),
+  );
+  const durationWidth = Math.max(
+    "dur".length,
+    ...durationValues.map((v) => v.length),
+  );
+  const spanWidth = Math.max(
+    "span".length,
+    ...labels.map((label) => label.length),
+    22,
+  );
+  const timelinePadding = " ".repeat(
+    startWidth + 2 + durationWidth + 2 + spanWidth + 2,
+  );
+
+  console.log(`[RSC Perf] ${method} ${pathname} (${total.toFixed(2)}ms)`);
+  console.log(
+    `${"start".padStart(startWidth)}  ${"dur".padStart(durationWidth)}  ${"span".padEnd(spanWidth)}  timeline`,
   );
+  console.log(`${timelinePadding}${createTimelineAxis(total)}`);
 
-  console.log(`[RSC Perf] ${method} ${pathname} (${total.toFixed(1)}ms)`);
+  for (let index = 0; index < displayRows.length; index++) {
+    const row = displayRows[index];
+    const label = labels[index].padEnd(spanWidth);
+    const start = formatMs(row.startTime).padStart(startWidth);
+    const duration = formatMs(row.duration).padStart(durationWidth);
 
-  for (const m of metricsStore.metrics) {
-    const paddedLabel = m.label.padEnd(maxLabelLen);
-    console.log(`  ${paddedLabel} ${m.duration.toFixed(1)}ms`);
+    console.log(
+      `${start}  ${duration}  ${label}  ${renderTimeline(row.spans, total)}`,
+    );
   }
 }
 
-/**
- * Generate Server-Timing header value from metrics
- * Format: metric-name;dur=X.XX
- */
 export function generateServerTiming(metricsStore: MetricsStore): string {
   return metricsStore.metrics
     .map((m) => {
       // Convert label to valid Server-Timing name (alphanumeric and hyphens)
-      const name = m.label
+      const base = m.label
         .replace(/:/g, "-")
         .replace(/[^a-zA-Z0-9-]/g, "")
         .toLowerCase();
+      const name = m.depth ? `d${m.depth}-${base}` : base;
       return `${name};dur=${m.duration.toFixed(2)}`;
     })
     .join(", ");