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

package/README.md

@@ -515,7 +515,7 @@ function Nav() {
   return (
     <nav>
       <Link to={href("/")}>Home</Link>
-      <Link to={href("/blog")} prefetch="hybrid">
+      <Link to={href("/blog")} prefetch="adaptive">
         Blog
       </Link>
       <Link to={href("/about")}>About</Link>

package/dist/vite/index.js

@@ -1745,7 +1745,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.25",
+  version: "0.0.0-experimental.26",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -5173,6 +5173,42 @@ ${list}`
   );
   return plugins;
 }
+
+// src/vite/plugins/refresh-cmd.ts
+function poke() {
+  return {
+    name: "vite-plugin-poke",
+    apply: "serve",
+    configureServer(server) {
+      const stdin = process.stdin;
+      const previousRawMode = stdin.isTTY ? stdin.isRaw : null;
+      if (stdin.isTTY) {
+        stdin.setRawMode(true);
+      }
+      const onData = (data) => {
+        if (data.length !== 1) return;
+        if (data[0] === 3) {
+          process.emit("SIGINT", "SIGINT");
+          return;
+        }
+        if (data[0] === 18) {
+          server.hot.send({ type: "full-reload", path: "*" });
+          server.config.logger.info("  browser reload (ctrl+r)", {
+            timestamp: true
+          });
+        }
+      };
+      stdin.on("data", onData);
+      server.httpServer?.on("close", () => {
+        stdin.off("data", onData);
+        if (stdin.isTTY && previousRawMode !== null) {
+          stdin.setRawMode(previousRawMode);
+        }
+      });
+    }
+  };
+}
 export {
+  poke,
   rango
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.25",
+  "version": "0.0.0-experimental.26",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/hooks/SKILL.md

@@ -239,22 +239,6 @@ export const FileUploadLoader = createLoader(async (ctx) => {
 }, true); // true = fetchable (can be called from the client via load())
 ```
 
-### useLoaderData()
-
-Get all loader data in current context:
-
-```tsx
-"use client";
-import { useLoaderData } from "@rangojs/router/client";
-
-function DebugPanel() {
-  const allData = useLoaderData();
-  // Record<string, any> - Map of loader ID to data
-
-  return <pre>{JSON.stringify(allData, null, 2)}</pre>;
-}
-```
-
 ## Handle Hooks
 
 ### useHandle()
@@ -696,7 +680,6 @@ See `/links` for full URL generation guide including server-side `ctx.reverse`.
 | `useLinkStatus()`    | Link pending state                | { pending }                                     |
 | `useLoader()`        | Loader data (strict)              | data, isLoading, error                          |
 | `useFetchLoader()`   | Loader with on-demand fetch       | data, load, isLoading                           |
-| `useLoaderData()`    | All loader data                   | Record<string, any>                             |
 | `useHandle()`        | Accumulated handle data           | T (handle type)                                 |
 | `useAction()`        | Server action state               | state, error, result                            |
 | `useLocationState()` | History state (persists or flash) | T \| undefined                                  |

package/skills/route/SKILL.md

@@ -103,8 +103,8 @@ export const SearchPage: Handler<"search"> = (ctx) => {
 ```
 
 Supported types: `"string"`, `"number"`, `"boolean"`, with `?` suffix for optional.
-Required params default to zero values when missing (`""`, `0`, `false`).
-Optional params are omitted from the result when not in the query string.
+Missing params are `undefined` regardless of required/optional. The required/optional
+distinction is a consumer-facing contract (for `href()` and `reverse()` autocomplete).
 
 Use `RouteSearchParams<"name">` and `RouteParams<"name">` to extract types for props:
 

package/skills/router-setup/SKILL.md

@@ -78,7 +78,7 @@ interface RSCRouterOptions<TEnv> {
   // Document component wrapping entire app
   document?: ComponentType<{ children: ReactNode }>;
 
-  // Enable performance metrics
+  // Enable per-request performance timeline (console waterfall + Server-Timing header)
   debugPerformance?: boolean;
 
   // Default error boundary

package/skills/typesafety/SKILL.md

@@ -281,7 +281,7 @@ import type { RouteSearchParams, RouteParams } from "@rangojs/router";
 
 // RouteSearchParams<"name"> resolves the search schema to a typed object
 type SP = RouteSearchParams<"search">;
-// { q: string; page?: number; sort?: string }
+// { q: string | undefined; page?: number; sort?: string }
 
 // RouteParams<"name"> resolves URL params from the route pattern
 type P = RouteParams<"blogPost">;

package/src/browser/react/Link.tsx

@@ -37,7 +37,7 @@ import {
   unobserveForPrefetch,
 } from "../prefetch/observer.js";
 
-// Touch device detection for hybrid strategy.
+// Touch device detection for adaptive strategy.
 // Checked once at module load (Link.tsx is "use client", runs only in browser).
 const isTouchDevice =
   typeof window !== "undefined" && window.matchMedia("(hover: none)").matches;
@@ -47,14 +47,14 @@ const isTouchDevice =
  * - "hover": Prefetch on mouse enter (direct, no queue)
  * - "viewport": Prefetch when link enters viewport (queued, waits for idle)
  * - "render": Prefetch on component mount regardless of visibility (queued, waits for idle)
- * - "hybrid": Hover on pointer devices, viewport on touch devices
+ * - "adaptive": Hover on pointer devices, viewport on touch devices
  * - "none": No prefetching (default)
  */
 export type PrefetchStrategy =
   | "hover"
   | "viewport"
   | "render"
-  | "hybrid"
+  | "adaptive"
   | "none";
 
 /**
@@ -181,9 +181,9 @@ export const Link: ForwardRefExoticComponent<
   const ctx = useContext(NavigationStoreContext);
   const isExternal = isExternalUrl(to);
 
-  // Resolve hybrid: viewport on touch devices, hover on pointer devices
+  // Resolve adaptive: viewport on touch devices, hover on pointer devices
   const resolvedStrategy =
-    prefetch === "hybrid" ? (isTouchDevice ? "viewport" : "hover") : prefetch;
+    prefetch === "adaptive" ? (isTouchDevice ? "viewport" : "hover") : prefetch;
 
   // Internal ref for viewport observation; merge with forwarded ref
   const internalRef = useRef<HTMLAnchorElement | null>(null);

package/src/build/route-trie.ts

@@ -47,6 +47,8 @@ export interface TrieNode {
   s?: Record<string, TrieNode>;
   /** Param child: { n: paramName, c: child node } */
   p?: { n: string; c: TrieNode };
+  /** Suffix-param children keyed by suffix (e.g., ".html" → { n: "productId", c: ... }) */
+  xp?: Record<string, { n: string; c: TrieNode }>;
   /** Wildcard terminal: leaf + paramName */
   w?: TrieLeaf & { pn: string };
 }
@@ -158,6 +160,11 @@ export function extractAncestryFromTrie(
         visit(child);
       }
     }
+    if (node.xp) {
+      for (const child of Object.values(node.xp)) {
+        visit(child.c);
+      }
+    }
     if (node.p) {
       visit(node.p.c);
     }
@@ -235,10 +242,19 @@ function insertSegments(
       mergeLeaf(node, leaf);
       // AND continue with param child (param present)
     }
-    if (!node.p) {
-      node.p = { n: segment.value, c: {} };
+    if (segment.suffix) {
+      // Suffix param: keyed by suffix string (e.g., ".html")
+      if (!node.xp) node.xp = {};
+      if (!node.xp[segment.suffix]) {
+        node.xp[segment.suffix] = { n: segment.value, c: {} };
+      }
+      insertSegments(node.xp[segment.suffix].c, segments, index + 1, leaf);
+    } else {
+      if (!node.p) {
+        node.p = { n: segment.value, c: {} };
+      }
+      insertSegments(node.p.c, segments, index + 1, leaf);
     }
-    insertSegments(node.p.c, segments, index + 1, leaf);
   } else if (segment.type === "wildcard") {
     // Wildcard consumes all remaining segments
     const wildLeaf = { ...leaf, pn: "*" };

package/src/client.rsc.tsx

@@ -17,7 +17,6 @@ export {
   OutletProvider,
   useOutlet,
   useLoader,
-  useLoaderData,
   ErrorBoundary,
   type ErrorBoundaryProps,
 } from "./client.js";

package/src/client.tsx

@@ -313,52 +313,6 @@ export {
   type UseLoaderOptions,
 } from "./use-loader.js";
 
-/**
- * Hook to access all loader data in the current context
- *
- * Returns a record of all loader data available in the current outlet context
- * and all parent contexts. Useful for debugging or when you need access to
- * multiple loaders.
- *
- * @returns Record of loader name to data, or empty object if no loaders
- *
- * @example
- * ```tsx
- * "use client";
- * import { useLoaderData } from "rsc-router/client";
- *
- * export function DebugPanel() {
- *   const loaderData = useLoaderData();
- *   return <pre>{JSON.stringify(loaderData, null, 2)}</pre>;
- * }
- * ```
- */
-export function useLoaderData(): Record<string, any> {
-  const context = useContext(OutletContext);
-
-  // Collect all loader data from the context chain
-  // Child loaders override parent loaders with the same name
-  const result: Record<string, any> = {};
-  const stack: OutletContextValue[] = [];
-
-  // Build stack from current to root
-  let current: OutletContextValue | null | undefined = context;
-  while (current) {
-    stack.push(current);
-    current = current.parent;
-  }
-
-  // Apply from root to current (so children override parents)
-  for (let i = stack.length - 1; i >= 0; i--) {
-    const ctx = stack[i];
-    if (ctx.loaderData) {
-      Object.assign(result, ctx.loaderData);
-    }
-  }
-
-  return result;
-}
-
 /**
  * Client-safe createLoader factory
  *

package/src/router/match-result.ts

@@ -108,7 +108,6 @@
  */
 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";
 
 /**
@@ -186,19 +185,12 @@ export function buildMatchResult<TEnv>(
     segmentIds: segmentsToRender.map((s) => s.id),
   });
 
-  // Output metrics if enabled
-  let serverTiming: string | undefined;
-  if (ctx.metricsStore) {
-    serverTiming = generateServerTiming(ctx.metricsStore);
-  }
-
   return {
     segments: segmentsToRender,
     matched: allIds,
     diff: segmentsToRender.map((s) => s.id),
     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,

package/src/router/metrics.ts

@@ -11,14 +11,19 @@ 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);
 }
 
-function renderTimeline(metric: PerformanceMetric, total: number): string {
+interface Span {
+  startTime: number;
+  duration: number;
+}
+
+function renderTimeline(spans: Span[], total: number): string {
   if (TIMELINE_WIDTH <= 0) {
     return "||";
   }
@@ -30,21 +35,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 +64,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 +101,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 +219,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 +244,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

@@ -106,9 +106,10 @@ 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;
 

package/src/router/middleware.ts

@@ -51,6 +51,8 @@ function warnCtxSetBeforeRedirect(handler: Function): void {
 }
 
 const MIDDLEWARE_METRIC_DEPTH = 1;
+/** Ignore post-next() durations below this threshold (measurement noise). */
+const POST_METRIC_MIN_DURATION_MS = 0.01;
 
 function getMiddlewareMetricBase<TEnv>(
   entry: MiddlewareEntry<TEnv>,
@@ -382,13 +384,14 @@ export async function executeMiddleware<TEnv>(
       reverse,
     );
     const metricStart = performance.now();
+    const metricLabel = getMiddlewareMetricLabel(entry, middlewareOrdinal);
     let middlewareFinished = false;
     const finishMiddleware = () => {
       if (!middlewareFinished) {
         middlewareFinished = true;
         appendMetric(
           _getRequestContext()?._metricsStore,
-          getMiddlewareMetricLabel(entry, middlewareOrdinal),
+          `${metricLabel}:pre`,
           metricStart,
           performance.now() - metricStart,
           MIDDLEWARE_METRIC_DEPTH,
@@ -400,6 +403,7 @@ export async function executeMiddleware<TEnv>(
     // Guard against double-calling: a second call would re-enter the
     // downstream chain and overwrite responseHolder.response.
     let nextPromise: Promise<Response> | null = null;
+    let nextResolvedAt: number | undefined;
     const wrappedNext = (): Promise<Response> => {
       if (nextPromise) {
         throw new Error(
@@ -407,7 +411,17 @@ export async function executeMiddleware<TEnv>(
         );
       }
       finishMiddleware();
-      nextPromise = next();
+      const downstream = next();
+      nextPromise = downstream.then(
+        (res) => {
+          nextResolvedAt = performance.now();
+          return res;
+        },
+        (err) => {
+          nextResolvedAt = performance.now();
+          throw err;
+        },
+      );
       return nextPromise;
     };
 
@@ -430,6 +444,21 @@ export async function executeMiddleware<TEnv>(
     }
     finishMiddleware();
 
+    // Record post-next() processing time when middleware did work after
+    // the downstream chain resolved (e.g. adding headers, logging).
+    if (nextResolvedAt !== undefined) {
+      const postDur = performance.now() - nextResolvedAt;
+      if (postDur > POST_METRIC_MIN_DURATION_MS) {
+        appendMetric(
+          _getRequestContext()?._metricsStore,
+          `${metricLabel}:post`,
+          nextResolvedAt,
+          postDur,
+          MIDDLEWARE_METRIC_DEPTH,
+        );
+      }
+    }
+
     // Explicit return takes precedence (middleware short-circuit).
     // Merge stub headers (from ctx.header before this point) and
     // RequestContext stub headers (from ctx.setCookie) into the