@rangojs/router 0.0.0-experimental.25 → 0.0.0-experimental.25dbaac3

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,8 +109,8 @@
  */
 import type { MatchResult, ResolvedSegment } from "../types.js";
 import type { MatchContext, MatchPipelineState } from "./match-context.js";
-import { generateServerTiming } from "./metrics.js";
 import { debugLog } from "./logging.js";
+import { appendMetric } from "./metrics.js";
 
 /**
  * Collect all segments from an async generator
@@ -124,6 +125,69 @@ export async function collectSegments(
   return segments;
 }
 
+/**
+ * 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,
+): ResolvedSegment[] {
+  // First pass: collect loaderIds of original (non-inherited) segments
+  // and whether their parent entry uses loading()
+  const originalLoaders = new Set<string>();
+  const loadersWithLoading = 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
+    }
+  }
+  // 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 result: ResolvedSegment[] = [];
+  let dedupCount = 0;
+
+  for (const s of segments) {
+    if (
+      s.type === "loader" &&
+      s.loaderId &&
+      s._inherited &&
+      originalLoaders.has(s.loaderId) &&
+      !loadersWithLoading.has(s.loaderId)
+    ) {
+      dedupCount++;
+      continue;
+    }
+    result.push(s);
+  }
+
+  if (dedupCount > 0) {
+    debugLog(logPrefix, `deduped ${dedupCount} inherited loader segment(s)`);
+  }
+
+  return result;
+}
+
 /**
  * Build the final MatchResult from collected segments and context
  */
@@ -168,13 +232,23 @@ 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
+    // 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.
+    const clientIdSet = new Set(ctx.clientSegmentIds);
     segmentsToRender = allSegments.filter(
-      (s) => s.component !== null || s.type === "loader",
+      (s) =>
+        s.component !== null || s.type === "loader" || !clientIdSet.has(s.id),
     );
   }
 
+  const dedupedSegments = deduplicateLoaderSegments(
+    segmentsToRender,
+    logPrefix,
+  );
+
   debugLog(logPrefix, "all segments", {
     segments: allSegments.map((s) => ({
       id: s.id,
@@ -183,22 +257,44 @@ export function buildMatchResult<TEnv>(
     })),
   });
   debugLog(logPrefix, "segments to render", {
-    segmentIds: segmentsToRender.map((s) => s.id),
+    segmentIds: dedupedSegments.map((s) => s.id),
   });
 
-  // Output metrics if enabled
-  let serverTiming: string | undefined;
-  if (ctx.metricsStore) {
-    serverTiming = generateServerTiming(ctx.metricsStore);
-  }
+  // 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: segmentsToRender,
-    matched: allIds,
-    diff: segmentsToRender.map((s) => s.id),
+    segments: cleanedSegments,
+    matched: matchedIds,
+    diff: cleanedSegments.map((s) => s.id),
+    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,
@@ -218,10 +314,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

@@ -11,14 +11,24 @@ const DEPTH_INDENT = 2;
 const TIMELINE_WIDTH = 40;
 
 function formatMs(value: number): string {
-  return `${value.toFixed(1)}ms`;
+  return `${value.toFixed(2)}ms`;
 }
 
 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 {
+  startTime: number;
+  duration: number;
 }
 
-function renderTimeline(metric: PerformanceMetric, total: number): string {
+function renderTimeline(spans: Span[], total: number): string {
   if (TIMELINE_WIDTH <= 0) {
     return "||";
   }
@@ -30,21 +40,24 @@ function renderTimeline(metric: PerformanceMetric, total: number): string {
     return `|${cells.join("")}|`;
   }
 
-  const start = Math.max(0, metric.startTime);
-  const end = Math.max(start, metric.startTime + metric.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),
-    ),
-  );
+  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);
+  }
 
-  cells.fill("#", startColumn, endColumn);
   return `|${cells.join("")}|`;
 }
 
@@ -56,15 +69,18 @@ function createTimelineAxis(total: number): string {
 }
 
 /**
- * Create a metrics store for the request if debugPerformance is enabled
+ * 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,
 ): MetricsStore | undefined {
   if (!debugPerformance) return undefined;
   return {
     enabled: true,
-    requestStart: performance.now(),
+    requestStart: requestStart ?? performance.now(),
     metrics: [],
   };
 }
@@ -90,24 +106,115 @@ export function appendMetric(
 
 /**
  * Log the current request metrics and return the corresponding Server-Timing value.
- * Falls back to an existing header value when no metrics store is active.
  */
 export function buildMetricsTiming(
   method: string,
   pathname: string,
   metricsStore: MetricsStore | undefined,
-  fallback?: string,
 ): string | undefined {
-  if (!metricsStore) {
-    return fallback;
-  }
+  if (!metricsStore) return undefined;
   logMetrics(method, pathname, metricsStore);
   return generateServerTiming(metricsStore) || undefined;
 }
 
+/** Display row produced by merging :pre/:post metric pairs. */
+interface DisplayRow {
+  label: string;
+  startTime: number;
+  duration: number;
+  depth: number | 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>();
+
+  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;
+}
+
 /**
  * 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,
@@ -117,12 +224,14 @@ export function logMetrics(
   const total = performance.now() - metricsStore.requestStart;
 
   const sorted = sortMetrics(metricsStore.metrics);
-  const labels = sorted.map(
-    (m) =>
-      `${" ".repeat(BASE_INDENT + (m.depth ?? 0) * DEPTH_INDENT)}${m.label}`,
+  const displayRows = buildDisplayRows(sorted);
+
+  const labels = displayRows.map(
+    (r) =>
+      `${" ".repeat(BASE_INDENT + (r.depth ?? 0) * DEPTH_INDENT)}${r.label}`,
   );
-  const startValues = sorted.map((m) => formatMs(m.startTime));
-  const durationValues = sorted.map((m) => formatMs(m.duration));
+  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),
@@ -140,20 +249,20 @@ export function logMetrics(
     startWidth + 2 + durationWidth + 2 + spanWidth + 2,
   );
 
-  console.log(`[RSC Perf] ${method} ${pathname} (${total.toFixed(1)}ms)`);
+  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)}`);
 
-  for (let index = 0; index < sorted.length; index++) {
-    const metric = sorted[index];
+  for (let index = 0; index < displayRows.length; index++) {
+    const row = displayRows[index];
     const label = labels[index].padEnd(spanWidth);
-    const start = formatMs(metric.startTime).padStart(startWidth);
-    const duration = formatMs(metric.duration).padStart(durationWidth);
+    const start = formatMs(row.startTime).padStart(startWidth);
+    const duration = formatMs(row.duration).padStart(durationWidth);
 
     console.log(
-      `${start}  ${duration}  ${label}  ${renderTimeline(metric, total)}`,
+      `${start}  ${duration}  ${label}  ${renderTimeline(row.spans, total)}`,
     );
   }
 }

package/src/router/middleware-types.ts

@@ -12,6 +12,9 @@ import type {
   DefaultVars,
 } from "../types/global-namespace.js";
 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
@@ -25,8 +28,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;
 };
 
 /**
@@ -51,33 +58,16 @@ export interface CookieOptions {
 export interface MiddlewareContext<
   TEnv = any,
   TParams = Record<string, string>,
-> {
-  /** Original request */
-  request: Request;
-
-  /** Parsed URL */
-  url: URL;
-
-  /** URL pathname */
-  pathname: string;
-
-  /** URL search params */
-  searchParams: URLSearchParams;
-
-  /** Platform bindings (Cloudflare, etc.) */
-  env: TEnv;
-
+> extends RequestScope<TEnv> {
   /** URL params extracted from route/middleware pattern */
   params: TParams;
 
   /**
-   * Response stub (read-only). Before `next()`, returns the shared response stub
-   * where headers and cookies accumulate. After `next()`, returns the downstream response.
-   *
-   * Use `ctx.header()` to set response headers, or `cookies()` for cookie mutations.
-   * To replace the response entirely, return a new `Response` from the middleware.
+   * Response headers.
+   * Before `next()`, returns headers from the shared response stub.
+   * After `next()`, returns headers from the downstream response.
    */
-  readonly res: Response;
+  readonly headers: Headers;
 
   /** Get a context variable (shared with route handlers) */
   get: GetVariableFn;
@@ -86,11 +76,10 @@ export interface MiddlewareContext<
   set: SetVariableFn;
 
   /**
-   * Set a response header - can be called before or after `next()`
+   * 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.
-   * Shorthand for `ctx.res.headers.set()`.
    */
   header(name: string, value: string): void;
 
@@ -106,12 +95,32 @@ export interface MiddlewareContext<
    * included in the Server-Timing response header, regardless of the
    * router-level `debugPerformance` option.
    *
-   * Must be called **before** `await next()` — the metrics store is
-   * created at the start of route matching inside `next()`, so calling
-   * this after `next()` returns has no effect.
+   * 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
@@ -167,7 +176,7 @@ export interface MiddlewareEntry<TEnv = any> {
 }
 
 /**
- * Mutable response holder - allows ctx.res to be updated after next() is called
+ * Mutable response holder - tracks the current response through the middleware chain.
  */
 export interface ResponseHolder {
   response: Response | null;