@rangojs/router 0.0.0-experimental.9c87b9aa → 0.0.0-experimental.9c9afef3

package/dist/vite/index.js

@@ -9,18 +9,18 @@ import fs from "node:fs";
 
 // src/vite/plugins/expose-id-utils.ts
 import path from "node:path";
-import crypto from "node:crypto";
+import crypto2 from "node:crypto";
 function normalizePath(p) {
   return p.split(path.sep).join("/");
 }
 function hashId(filePath, exportName) {
   const input = `${filePath}#${exportName}`;
-  const hash = crypto.createHash("sha256").update(input).digest("hex");
+  const hash = crypto2.createHash("sha256").update(input).digest("hex");
   return `${hash.slice(0, 8)}#${exportName}`;
 }
 function hashInlineId(filePath, lineNumber, index) {
   const input = index !== void 0 && index > 0 ? `${filePath}:${lineNumber}:${index}` : `${filePath}:${lineNumber}`;
-  return crypto.createHash("sha256").update(input).digest("hex").slice(0, 8);
+  return crypto2.createHash("sha256").update(input).digest("hex").slice(0, 8);
 }
 function buildExportMap(program) {
   const exportMap = /* @__PURE__ */ new Map();
@@ -1745,7 +1745,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.9c87b9aa",
+  version: "0.0.0-experimental.9c9afef3",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -2712,9 +2712,9 @@ function createVersionPlugin() {
     configResolved(config) {
       isDev = config.command === "serve";
     },
-    configureServer(devServer) {
-      server = devServer;
-      devServer.watcher.on("unlink", (filePath) => {
+    configureServer(devServer2) {
+      server = devServer2;
+      devServer2.watcher.on("unlink", (filePath) => {
         if (!isDev) return;
         if (!clientModuleSignatures.has(filePath)) return;
         clientModuleSignatures.delete(filePath);
@@ -4861,6 +4861,68 @@ ${details}`
   };
 }
 
+// src/vite/plugins/performance-tracks.ts
+var DEBUG_ID_HEADER = "X-RSC-Debug-Id";
+var DEBUG_C2S_EVENT = "rango:perf-c2s";
+var base64ToBytes = (base64) => new Uint8Array(Buffer.from(base64, "base64"));
+var devServer = null;
+var sessions = /* @__PURE__ */ new Map();
+function performanceTracksPlugin() {
+  return {
+    name: "@rangojs/router:performance-tracks",
+    apply: "serve",
+    configureServer(server) {
+      devServer = server;
+      const hot = server.environments.client.hot;
+      hot.on(DEBUG_C2S_EVENT, (payload) => {
+        const session = sessions.get(payload.i);
+        if ("d" in payload) {
+          if (session?.cmdController) {
+            try {
+              session.cmdController.close();
+            } catch {
+            }
+            delete session.cmdController;
+          }
+          return;
+        }
+        if ("b" in payload) {
+          if (session?.cmdController) {
+            try {
+              session.cmdController.enqueue(base64ToBytes(payload.b));
+            } catch {
+              delete session.cmdController;
+            }
+          }
+          return;
+        }
+      });
+      return () => {
+        server.middlewares.use((req, _res, next) => {
+          const existingId = req.headers[DEBUG_ID_HEADER.toLowerCase()];
+          const isHtml = req.headers.accept?.includes("text/html");
+          if (!existingId && !isHtml) {
+            next();
+            return;
+          }
+          const debugId = existingId || crypto.randomUUID();
+          if (!existingId) {
+            const lowerName = DEBUG_ID_HEADER.toLowerCase();
+            req.headers[lowerName] = debugId;
+            if (req.rawHeaders) {
+              req.rawHeaders.push(DEBUG_ID_HEADER, debugId);
+            }
+          }
+          if (!sessions.has(debugId)) {
+            sessions.set(debugId, { pendingChunks: [], ended: false });
+          }
+          next();
+        });
+      };
+    }
+  };
+}
+
 // src/vite/rango.ts
 async function rango(options) {
   const resolvedOptions = options ?? { preset: "node" };
@@ -5125,6 +5187,7 @@ ${list}`);
       staticRouteTypesGeneration: resolvedOptions.staticRouteTypesGeneration
     })
   );
+  plugins.push(performanceTracksPlugin());
   return plugins;
 }
 

package/package.json

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

package/skills/loader/SKILL.md

@@ -554,7 +554,7 @@ export const ProductLoader = createLoader(async (ctx) => {
     .first();
 
   if (!product) {
-    throw new Response("Product not found", { status: 404 });
+    notFound("Product not found");
   }
 
   return { product };

package/skills/router-setup/SKILL.md

@@ -84,10 +84,10 @@ interface RSCRouterOptions<TEnv> {
   // Default error boundary
   defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler;
 
-  // Default not-found boundary
+  // Default not-found boundary for notFound() thrown in handlers/loaders
   defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler;
 
-  // Component for 404 routes
+  // Component for 404 (no route match, or notFound() without a boundary)
   notFound?: ReactNode | ((props: { pathname: string }) => ReactNode);
 
   // Error logging callback
@@ -290,6 +290,56 @@ const router = createRouter({
 export default router;
 ```
 
+## Not Found Handling
+
+Two distinct 404 scenarios:
+
+**1. No route matches the URL** — the router renders the `notFound` component from `createRouter()` config. This is automatic.
+
+**2. A handler/loader calls `notFound()`** — signals that the route matched but the data doesn't exist (e.g., invalid product ID).
+
+```typescript
+import { notFound } from "@rangojs/router";
+
+// In a handler or loader
+path("/product/:slug", async (ctx) => {
+  const product = await db.getProduct(ctx.params.slug);
+  if (!product) notFound("Product not found");
+  return <ProductPage product={product} />;
+});
+```
+
+### Fallback chain for `notFound()`
+
+When `notFound()` is thrown, the router looks for a fallback in this order:
+
+1. **`notFoundBoundary()`** — nearest boundary in the route tree (route-level)
+2. **`defaultNotFoundBoundary`** — from `createRouter()` config (app-level)
+3. **`notFound`** — from `createRouter()` config (same component used for no-route-match)
+4. **Default `<h1>Not Found</h1>`** — built-in fallback
+
+All cases set HTTP 404 status.
+
+### notFoundBoundary
+
+Wrap routes with `notFoundBoundary()` for route-specific not-found UI:
+
+```typescript
+urls(({ path, layout }) => [
+  layout(ShopLayout, () => [
+    notFoundBoundary(({ notFound: info }) => (
+      <div>
+        <h1>Not Found</h1>
+        <p>{info.message}</p>
+      </div>
+    )),
+    path("/product/:slug", ProductPage),
+  ]),
+]);
+```
+
+`notFoundBoundary` receives `{ notFound: NotFoundInfo }` where `NotFoundInfo` contains `message`, `segmentId`, `segmentType`, and `pathname`.
+
 ## Including Sub-patterns
 
 ```typescript

package/src/browser/debug-channel.ts

@@ -0,0 +1,93 @@
+/**
+ * Client-side debug channel for React Performance Tracks.
+ *
+ * Creates a bidirectional channel that communicates with the server-side
+ * debug channel via Vite's HMR WebSocket. Used with createFromFetch()
+ * so Chrome DevTools can display Server Components in the Performance tab.
+ *
+ * Dev-only — gated behind import.meta.hot.
+ */
+
+export const DEBUG_ID_HEADER = "X-RSC-Debug-Id";
+const DEBUG_S2C_EVENT = "rango:perf-s2c";
+const DEBUG_C2S_EVENT = "rango:perf-c2s";
+
+type DebugPayload =
+  | { i: string; b: string } // chunk (base64)
+  | { i: string; d: true }; // done
+
+const bytesToBase64 = (bytes: Uint8Array) => {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]!);
+  }
+  return btoa(binary);
+};
+
+const base64ToBytes = (base64: string) =>
+  Uint8Array.from(atob(base64), (char) => char.charCodeAt(0));
+
+/**
+ * Create a client-side debug channel for the given debugId.
+ * The channel communicates with the server via Vite's HMR WebSocket.
+ */
+export function createClientDebugChannel(debugId: string): {
+  readable: ReadableStream<Uint8Array>;
+  writable: WritableStream<Uint8Array>;
+} | null {
+  const hot = (import.meta as any).hot;
+  if (!hot) return null;
+
+  let closed = false;
+  let onServerData: ((payload: DebugPayload) => void) | undefined;
+
+  const cleanup = (notify?: boolean) => {
+    if (closed) return;
+    closed = true;
+    if (onServerData) {
+      hot.off(DEBUG_S2C_EVENT, onServerData);
+    }
+    if (notify) {
+      hot.send(DEBUG_C2S_EVENT, { i: debugId, d: true } satisfies DebugPayload);
+    }
+  };
+
+  // Readable: receives server-to-client debug data via HMR WS
+  const readable = new ReadableStream<Uint8Array>({
+    start(controller) {
+      onServerData = (payload: DebugPayload) => {
+        if (closed || payload.i !== debugId) return;
+        if ("b" in payload) {
+          controller.enqueue(base64ToBytes(payload.b));
+        }
+        if ("d" in payload) {
+          cleanup();
+          controller.close();
+        }
+      };
+      hot.on(DEBUG_S2C_EVENT, onServerData);
+    },
+    cancel() {
+      cleanup(true);
+    },
+  });
+
+  // Writable: sends client-to-server commands via HMR WS
+  const writable = new WritableStream<Uint8Array>({
+    write(chunk) {
+      if (closed) throw new TypeError("Channel is closed");
+      hot.send(DEBUG_C2S_EVENT, {
+        i: debugId,
+        b: bytesToBase64(chunk),
+      } satisfies DebugPayload);
+    },
+    close() {
+      cleanup(true);
+    },
+    abort() {
+      cleanup(true);
+    },
+  });
+
+  return { readable, writable };
+}

package/src/browser/navigation-client.ts

@@ -12,6 +12,7 @@ import {
   startBrowserTransaction,
 } from "./logging.js";
 import { getRangoState } from "./rango-state.js";
+import { createClientDebugChannel, DEBUG_ID_HEADER } from "./debug-channel.js";
 import {
   extractRscHeaderUrl,
   emptyResponse,
@@ -107,6 +108,14 @@ export function createNavigationClient(
         resolveStreamComplete = resolve;
       });
 
+      // Dev-only: create debug channel for React Performance Tracks
+      const debugId = (import.meta as any).hot
+        ? crypto.randomUUID()
+        : undefined;
+      const debugChannel = debugId
+        ? createClientDebugChannel(debugId)
+        : undefined;
+
       /** Start a fresh navigation fetch (no cache / inflight hit). */
       const doFreshFetch = (): Promise<Response> => {
         if (tx) {
@@ -124,6 +133,7 @@ export function createNavigationClient(
               "X-RSC-Router-Intercept-Source": interceptSourceUrl,
             }),
             ...(hmr && { "X-RSC-HMR": "1" }),
+            ...(debugId && { [DEBUG_ID_HEADER]: debugId }),
           },
           signal,
         }).then((response) => {
@@ -220,7 +230,12 @@ export function createNavigationClient(
 
       try {
         // Deserialize RSC payload
-        const payload = await deps.createFromFetch<RscPayload>(responsePromise);
+        const payload = await deps.createFromFetch<RscPayload>(
+          responsePromise,
+          {
+            ...(debugChannel && { debugChannel }),
+          },
+        );
         if (tx) {
           browserDebugLog(tx, "response received", {
             isPartial: payload.metadata?.isPartial,

package/src/browser/react/NavigationProvider.tsx

@@ -289,8 +289,10 @@ export function NavigationProvider({
     };
   }, [warmupEnabled]);
 
-  // Cancel speculative prefetches when navigation starts.
-  // Viewport/render prefetches should not compete with navigation fetches.
+  // Cancel non-matching prefetches when navigation starts.
+  // Frees connections so the navigation fetch isn't competing with
+  // speculative prefetches. The prefetch matching the navigation target
+  // is kept alive so it can be reused via consumeInflightPrefetch.
   useEffect(() => {
     let wasIdle = true;
     const unsub = eventController.subscribe(() => {

package/src/browser/server-action-bridge.ts

@@ -4,6 +4,7 @@ import type {
   RscPayload,
 } from "./types.js";
 import { createPartialUpdater } from "./partial-update.js";
+import { createClientDebugChannel, DEBUG_ID_HEADER } from "./debug-channel.js";
 import { createNavigationTransaction } from "./navigation-transaction.js";
 import {
   reconcileSegments,
@@ -199,6 +200,14 @@ export function createServerActionBridge(
       const onHandleAbort = () => fetchAbort.abort();
       handle.signal.addEventListener("abort", onHandleAbort, { once: true });
 
+      // Dev-only: create debug channel for React Performance Tracks
+      const debugId = (import.meta as any).hot
+        ? crypto.randomUUID()
+        : undefined;
+      const debugChannel = debugId
+        ? createClientDebugChannel(debugId)
+        : undefined;
+
       // Send action request with stream tracking
       const responsePromise = fetch(url, {
         method: "POST",
@@ -210,6 +219,7 @@ export function createServerActionBridge(
           ...(interceptSourceUrl && {
             "X-RSC-Router-Intercept-Source": interceptSourceUrl,
           }),
+          ...(debugId && { [DEBUG_ID_HEADER]: debugId }),
         },
         body: encodedBody,
         signal: fetchAbort.signal,
@@ -272,6 +282,7 @@ export function createServerActionBridge(
       try {
         payload = await deps.createFromFetch<RscPayload>(responsePromise, {
           temporaryReferences,
+          ...(debugChannel && { debugChannel }),
         });
       } catch (error) {
         // Clean up streaming token on error (may be null if fetch failed before .then() ran)

package/src/browser/types.ts

@@ -341,7 +341,10 @@ export type ReadonlyURLSearchParams = Omit<
 export interface RscBrowserDependencies {
   createFromFetch: <T>(
     response: Promise<Response>,
-    options?: { temporaryReferences?: any },
+    options?: {
+      temporaryReferences?: any;
+      debugChannel?: { readable?: ReadableStream; writable?: WritableStream };
+    },
   ) => Promise<T>;
   createFromReadableStream: <T>(stream: ReadableStream) => Promise<T>;
   encodeReply: (

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

@@ -8,7 +8,7 @@
  * - Error boundary segment creation
  */
 
-import type { ReactNode } from "react";
+import { createElement, type ReactNode } from "react";
 import { DataNotFoundError } from "../../errors";
 import {
   createErrorInfo,
@@ -180,34 +180,39 @@ export function catchSegmentError<TEnv>(
 
   if (error instanceof DataNotFoundError) {
     const notFoundFallback = deps.findNearestNotFoundBoundary(entry);
+    // Fall back to router's notFound component, then a plain default
+    const notFoundOption = deps.notFoundComponent;
+    const defaultFallback =
+      typeof notFoundOption === "function"
+        ? notFoundOption({ pathname: pathname ?? "" })
+        : (notFoundOption ?? createElement("h1", null, "Not Found"));
+    const effectiveNotFoundFallback = notFoundFallback ?? defaultFallback;
 
-    if (notFoundFallback) {
-      const notFoundInfo = createNotFoundInfo(
-        error,
-        entry.shortCode,
-        entry.type,
-        pathname,
-      );
+    const notFoundInfo = createNotFoundInfo(
+      error,
+      entry.shortCode,
+      entry.type,
+      pathname,
+    );
 
-      reportError(true, {
-        notFound: true,
-        message: notFoundInfo.message,
-      });
+    reportError(true, {
+      notFound: true,
+      message: notFoundInfo.message,
+    });
 
-      debugLog("segment", "notFound boundary handled error", {
-        segmentId: entry.shortCode,
-        message: notFoundInfo.message,
-      });
+    debugLog("segment", "notFound boundary handled error", {
+      segmentId: entry.shortCode,
+      message: notFoundInfo.message,
+    });
 
-      setResponseStatus(404);
+    setResponseStatus(404);
 
-      return createNotFoundSegment(
-        notFoundInfo,
-        notFoundFallback,
-        entry,
-        params,
-      );
-    }
+    return createNotFoundSegment(
+      notFoundInfo,
+      effectiveNotFoundFallback,
+      entry,
+      params,
+    );
   }
 
   const fallback = deps.findNearestErrorBoundary(entry);

package/src/router/types.ts

@@ -96,6 +96,7 @@ export interface SegmentResolutionDeps<TEnv = any> {
   findNearestNotFoundBoundary: (
     entry: EntryData | null,
   ) => ReactNode | NotFoundBoundaryHandler | null;
+  notFoundComponent?: ReactNode | ((props: { pathname: string }) => ReactNode);
   callOnError: (error: unknown, phase: ErrorPhase, context: any) => void;
 }
 

package/src/router.ts

@@ -526,6 +526,7 @@ export function createRouter<TEnv = any>(
     trackHandler,
     findNearestErrorBoundary,
     findNearestNotFoundBoundary,
+    notFoundComponent: notFound,
     callOnError,
   };
 

package/src/rsc/handler.ts

@@ -14,9 +14,14 @@ import {
   runWithRequestContext,
   setRequestContextParams,
   requireRequestContext,
+  getRequestContext,
   createRequestContext,
 } from "../server/request-context.js";
 import * as rscDeps from "@vitejs/plugin-rsc/rsc";
+import {
+  DEBUG_ID_HEADER,
+  createServerDebugChannel,
+} from "../vite/plugins/performance-tracks.js";
 
 import type {
   RscPayload,
@@ -262,7 +267,10 @@ export function createRSCHandler<
         ...(locationState && { locationState }),
       },
     };
-    const rscStream = renderToReadableStream<RscPayload>(redirectPayload);
+    const debugChannel = getRequestContext()?._debugChannel;
+    const rscStream = renderToReadableStream<RscPayload>(redirectPayload, {
+      ...(debugChannel && { debugChannel }),
+    });
     return createResponseWithMergedHeaders(rscStream, {
       status: 200,
       headers: { "content-type": "text/x-component;charset=utf-8" },
@@ -418,6 +426,16 @@ export function createRSCHandler<
       requestContext._debugPerformance = true;
       requestContext._metricsStore = earlyMetricsStore;
     }
+    // Dev-only: wire debug channel for React Performance Tracks
+    if (process.env.NODE_ENV !== "production") {
+      const debugId = request.headers.get(DEBUG_ID_HEADER);
+      if (debugId) {
+        const channel = createServerDebugChannel(debugId);
+        if (channel) {
+          requestContext._debugChannel = channel;
+        }
+      }
+    }
     // Wire background error reporting so "use cache" and other subsystems
     // can surface non-fatal errors through the router's onError callback.
     requestContext._reportBackgroundError = (
@@ -1039,7 +1057,10 @@ export function createRSCHandler<
           },
         };
 
-        const rscStream = renderToReadableStream(payload);
+        const debugChannel = requireRequestContext()._debugChannel;
+        const rscStream = renderToReadableStream(payload, {
+          ...(debugChannel && { debugChannel }),
+        });
 
         // Determine if this is an RSC request or HTML request.
         // Partial requests are always RSC (see main isRscRequest comment).

package/src/rsc/loader-fetch.ts

@@ -168,8 +168,13 @@ export async function handleLoaderFetch<TEnv>(
             loaderResult: unknown;
           }
           const loaderPayload: LoaderPayload = { loaderResult: result };
-          const rscStream =
-            ctx.renderToReadableStream<LoaderPayload>(loaderPayload);
+          const debugChannel = reqCtx._debugChannel;
+          const rscStream = ctx.renderToReadableStream<LoaderPayload>(
+            loaderPayload,
+            {
+              ...(debugChannel && { debugChannel }),
+            },
+          );
 
           return createResponseWithMergedHeaders(rscStream, {
             headers: { "content-type": "text/x-component;charset=utf-8" },

package/src/rsc/progressive-enhancement.ts

@@ -257,7 +257,10 @@ export async function handleProgressiveEnhancement<TEnv>(
       formState: actionResult,
     };
 
-    const rscStream = ctx.renderToReadableStream<RscPayload>(payload);
+    const debugChannel = requireRequestContext()._debugChannel;
+    const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+      ...(debugChannel && { debugChannel }),
+    });
     // metricsStore=undefined is safe: the handler already stashed the early
     // SSR setup promise on request variables, so getSSRSetup returns it
     // without falling back to a fresh startSSRSetup.

package/src/rsc/rsc-rendering.ts

@@ -168,7 +168,10 @@ export async function handleRscRendering<TEnv>(
 
   // Serialize to RSC stream
   const rscSerializeStart = performance.now();
-  const rscStream = ctx.renderToReadableStream<RscPayload>(payload);
+  const debugChannel = reqCtx._debugChannel;
+  const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+    ...(debugChannel && { debugChannel }),
+  });
   const rscSerializeDur = performance.now() - rscSerializeStart;
   // This measures synchronous stream creation, not end-to-end stream consumption.
   appendMetric(

package/src/rsc/server-action.ts

@@ -223,8 +223,10 @@ export async function executeServerAction<TEnv>(
       // location state is a success-only semantic. Error boundary responses
       // update the error UI but should not mutate browser history state.
 
+      const debugChannel = requireRequestContext()._debugChannel;
       const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
         temporaryReferences,
+        ...(debugChannel && { debugChannel }),
       });
 
       return createResponseWithMergedHeaders(rscStream, {

package/src/rsc/types.ts

@@ -63,7 +63,13 @@ export interface RSCDependencies {
    */
   renderToReadableStream: <T>(
     payload: T,
-    options?: { temporaryReferences?: unknown },
+    options?: {
+      temporaryReferences?: unknown;
+      debugChannel?: {
+        readable?: ReadableStream;
+        writable?: WritableStream;
+      };
+    },
   ) => ReadableStream<Uint8Array>;
 
   /**

package/src/server/request-context.ts

@@ -287,6 +287,12 @@ export interface RequestContext<
 
   /** @internal Request-scoped performance metrics store */
   _metricsStore?: MetricsStore;
+
+  /** @internal Dev-only: debug channel for React Performance Tracks */
+  _debugChannel?: {
+    readable: ReadableStream;
+    writable: WritableStream;
+  };
 }
 
 /**
@@ -316,6 +322,7 @@ export type PublicRequestContext<
   | "_reportBackgroundError"
   | "_debugPerformance"
   | "_metricsStore"
+  | "_debugChannel"
   | "_setStatus"
   | "res"
 >;

package/src/types/handler-context.ts

@@ -277,9 +277,9 @@ export type HandlerContext<
       value: T,
       options?: { cache?: boolean },
     ): void;
-  } & ((
-    key: keyof DefaultVars,
-    value: DefaultVars[keyof DefaultVars],
+  } & (<K extends keyof DefaultVars>(
+    key: K,
+    value: DefaultVars[K],
     options?: { cache?: boolean },
   ) => void);
   /**

package/src/vite/plugins/performance-tracks.ts

@@ -0,0 +1,195 @@
+/**
+ * React Performance Tracks — Vite plugin
+ *
+ * Dev-only plugin that enables Chrome DevTools Performance tab integration
+ * for React Server Components. Creates a bidirectional debug channel per
+ * RSC request and transports data over Vite's HMR WebSocket.
+ *
+ * Architecture:
+ * - Server: renderToReadableStream writes timing data to debugChannel.writable
+ * - Transport: chunks are base64-encoded and sent via HMR custom events
+ * - Client: createFromFetch reads from debugChannel.readable
+ *
+ * Each request gets a unique debugId (UUID) to correlate the two sides.
+ */
+
+import type { Plugin, ViteDevServer } from "vite";
+
+export const DEBUG_ID_HEADER = "X-RSC-Debug-Id";
+const DEBUG_S2C_EVENT = "rango:perf-s2c";
+const DEBUG_C2S_EVENT = "rango:perf-c2s";
+
+type DebugPayload =
+  | { i: string; b: string } // chunk (base64)
+  | { i: string; d: true }; // done
+
+interface DebugSession {
+  // Server → Client: writable that React writes to, we read and forward via WS
+  // Server → Client: readable that client commands come into
+  cmdController?: ReadableStreamDefaultController<Uint8Array>;
+  pendingChunks?: Uint8Array[];
+  ended: boolean;
+}
+
+const bytesToBase64 = (bytes: Uint8Array) =>
+  Buffer.from(bytes).toString("base64");
+
+const base64ToBytes = (base64: string) =>
+  new Uint8Array(Buffer.from(base64, "base64"));
+
+// Module-level registry shared with RSC handler code (same Node.js process in dev)
+let devServer: ViteDevServer | null = null;
+const sessions = new Map<string, DebugSession>();
+
+/**
+ * Create a debug channel for a given request.
+ * Called by the RSC handler for each request that has a debugId.
+ * Returns the { readable, writable } pair for renderToReadableStream.
+ */
+export function createServerDebugChannel(debugId: string): {
+  readable: ReadableStream<Uint8Array>;
+  writable: WritableStream<Uint8Array>;
+} | null {
+  if (!devServer) return null;
+
+  const hot = devServer.environments.client.hot;
+  let session = sessions.get(debugId);
+  if (!session) {
+    session = { pendingChunks: [], ended: false };
+    sessions.set(debugId, session);
+  }
+
+  const sendChunk = (chunk: Uint8Array) => {
+    hot.send(DEBUG_S2C_EVENT, {
+      i: debugId,
+      b: bytesToBase64(chunk),
+    } satisfies DebugPayload);
+  };
+
+  const flushPendingChunks = () => {
+    if (!session!.pendingChunks) return;
+    for (const chunk of session!.pendingChunks) {
+      sendChunk(chunk);
+    }
+    delete session!.pendingChunks;
+  };
+
+  const cleanupIfEnded = () => {
+    if (session!.pendingChunks || !session!.ended) return;
+    sessions.delete(debugId);
+    hot.send(DEBUG_S2C_EVENT, {
+      i: debugId,
+      d: true,
+    } satisfies DebugPayload);
+  };
+
+  // Readable: receives client-to-server commands via WS
+  const readable = new ReadableStream<Uint8Array>({
+    start(controller) {
+      session!.cmdController = controller;
+      // If client already sent "ready", flush buffered data
+      flushPendingChunks();
+      cleanupIfEnded();
+    },
+    cancel() {
+      delete session!.cmdController;
+    },
+  });
+
+  // Writable: React writes debug data here, we forward to client via WS
+  const writable = new WritableStream<Uint8Array>({
+    write(chunk) {
+      if (session!.pendingChunks) {
+        // Client not connected yet — buffer
+        session!.pendingChunks.push(chunk);
+      } else {
+        sendChunk(chunk);
+      }
+    },
+    close() {
+      session!.ended = true;
+      cleanupIfEnded();
+    },
+    abort() {
+      session!.ended = true;
+      cleanupIfEnded();
+    },
+  });
+
+  return { readable, writable };
+}
+
+export function performanceTracksPlugin(): Plugin {
+  return {
+    name: "@rangojs/router:performance-tracks",
+    apply: "serve",
+
+    configureServer(server) {
+      devServer = server;
+      const hot = server.environments.client.hot;
+
+      // Listen for client-to-server debug messages
+      hot.on(DEBUG_C2S_EVENT, (payload: DebugPayload) => {
+        const session = sessions.get(payload.i);
+
+        if ("d" in payload) {
+          // Client closed channel
+          if (session?.cmdController) {
+            try {
+              session.cmdController.close();
+            } catch {
+              // ignore
+            }
+            delete session.cmdController;
+          }
+          return;
+        }
+
+        if ("b" in payload) {
+          // Client sent command data
+          if (session?.cmdController) {
+            try {
+              session.cmdController.enqueue(base64ToBytes(payload.b));
+            } catch {
+              delete session!.cmdController;
+            }
+          }
+          return;
+        }
+      });
+
+      // Intercept requests to inject debugId
+      return () => {
+        server.middlewares.use((req, _res, next) => {
+          const existingId = req.headers[
+            DEBUG_ID_HEADER.toLowerCase()
+          ] as string;
+          const isHtml = req.headers.accept?.includes("text/html");
+
+          if (!existingId && !isHtml) {
+            next();
+            return;
+          }
+
+          // Use existing debugId from client or generate one for SSR
+          const debugId = existingId || crypto.randomUUID();
+          if (!existingId) {
+            // Inject header so the RSC handler can read it
+            const lowerName = DEBUG_ID_HEADER.toLowerCase();
+            req.headers[lowerName] = debugId;
+            if (req.rawHeaders) {
+              req.rawHeaders.push(DEBUG_ID_HEADER, debugId);
+            }
+          }
+
+          // Pre-create session so the channel is ready when handler runs
+          if (!sessions.has(debugId)) {
+            sessions.set(debugId, { pendingChunks: [], ended: false });
+          }
+
+          next();
+        });
+      };
+    },
+  };
+}

package/src/vite/rango.ts

@@ -26,6 +26,7 @@ import { printBanner, rangoVersion } from "./utils/banner.js";
 import { createVersionInjectorPlugin } from "./plugins/version-injector.js";
 import { createCjsToEsmPlugin } from "./plugins/cjs-to-esm.js";
 import { createRouterDiscoveryPlugin } from "./router-discovery.js";
+import { performanceTracksPlugin } from "./plugins/performance-tracks.js";
 
 /**
  * Vite plugin for @rangojs/router.
@@ -441,5 +442,8 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
     }),
   );
 
+  // Dev-only: React Performance Tracks (debugChannel transport via HMR WS)
+  plugins.push(performanceTracksPlugin());
+
   return plugins;
 }