@rangojs/router 0.0.0-experimental.7dc955ec → 0.0.0-experimental.8123bb7e

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

@@ -24,12 +24,11 @@ import {
   type ContextVar,
   contextGet,
   contextSet,
-  isContextVar,
   isNonCacheable,
 } from "../context-var.js";
 import { createHandleStore, type HandleStore } from "./handle-store.js";
 import { isHandle } from "../handle.js";
-import { track, RSCRouterContext, type MetricsStore } from "./context.js";
+import { track, type MetricsStore } from "./context.js";
 import { getFetchableLoader } from "./fetchable-loader-store.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
@@ -288,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;
+  };
 }
 
 /**
@@ -317,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);
   /**
@@ -301,8 +301,11 @@ export type HandlerContext<
    * and server components rendered within the request context.
    *
    * For loaders: Returns a promise that resolves to the loader data.
-   * Loaders are executed in parallel and memoized per request — calling
-   * `ctx.use(SameLoader)` multiple times returns the same promise.
+   * Loaders are executed in parallel and memoized per request.
+   * Prefer DSL `loader()` + client `useLoader()` over `ctx.use(Loader)` —
+   * DSL loaders are always fresh and cache-safe. Use `ctx.use(Loader)` only
+   * when you need loader data in the handler itself (e.g., to set context
+   * variables or make routing decisions).
    *
    * For handles: Returns a push function to add data for this segment.
    * Handle data accumulates across all matched route segments.
@@ -310,10 +313,11 @@ export type HandlerContext<
    *
    * @example
    * ```typescript
-   * // Loader usage
-   * route("cart", async (ctx) => {
-   *   const cart = await ctx.use(CartLoader);
-   *   return <CartPage cart={cart} />;
+   * // Loader escape hatch — use when handler needs the data directly
+   * route("product", async (ctx) => {
+   *   const { product } = await ctx.use(ProductLoader);
+   *   ctx.set(Product, product); // make available to children
+   *   return <ProductPage />;
    * });
    *
    * // Handle usage - direct value

package/src/types/loader-types.ts

@@ -166,11 +166,11 @@ export type LoadOptions =
  *   return await db.products.findBySlug(slug);
  * });
  *
- * // Server usage
- * const cart = ctx.use(CartLoader);
+ * // Client usage (preferred — cache-safe, always fresh)
+ * const { data } = useLoader(CartLoader);
  *
- * // Client usage (fn is stripped, only name remains)
- * const cart = useLoader(CartLoader);
+ * // Server escape hatch (handler needs data directly)
+ * const cart = await ctx.use(CartLoader);
  * ```
  */
 export type LoaderDefinition<

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

@@ -0,0 +1,235 @@
+/**
+ * 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.
+ *
+ * Uses globalThis to share state between the Vite plugin (main process)
+ * and the RSC handler (RSC module graph) — they run in the same Node.js
+ * process but different module evaluation contexts.
+ */
+
+import type { Plugin } 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 {
+  cmdController?: ReadableStreamDefaultController<Uint8Array>;
+  pendingChunks?: Uint8Array[];
+  ended: boolean;
+}
+
+type DebugChannelRegistry = {
+  channels: Map<
+    string,
+    {
+      readable: ReadableStream<Uint8Array>;
+      writable: WritableStream<Uint8Array>;
+    }
+  >;
+  sessions: Map<string, DebugSession>;
+};
+
+const GLOBAL_KEY = "__RANGO_DEBUG_CHANNELS__";
+
+// Use Node.js `Module` built-in as carrier — Vite's RSC module runner
+// uses a separate VM context where both `globalThis` and `process` are
+// different objects, but built-in module singletons ARE shared.
+import { Module } from "node:module";
+function getRegistry(): DebugChannelRegistry {
+  return ((Module as any)[GLOBAL_KEY] ??= {
+    channels: new Map(),
+    sessions: new Map(),
+  });
+}
+
+/**
+ * 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.
+ *
+ * This works across module graphs because the channel is pre-created
+ * by the Vite plugin and stored on globalThis.
+ */
+export function createServerDebugChannel(debugId: string): {
+  readable: ReadableStream<Uint8Array>;
+  writable: WritableStream<Uint8Array>;
+} | null {
+  const registry = getRegistry();
+  const channel = registry.channels.get(debugId);
+  if (channel) {
+    registry.channels.delete(debugId);
+    console.log("[perf-tracks] debug channel attached for", debugId);
+    return channel;
+  }
+  console.log(
+    "[perf-tracks] no channel found for",
+    debugId,
+    "channels:",
+    registry.channels.size,
+  );
+  return null;
+}
+
+const bytesToBase64 = (bytes: Uint8Array) =>
+  Buffer.from(bytes).toString("base64");
+
+const base64ToBytes = (base64: string) =>
+  new Uint8Array(Buffer.from(base64, "base64"));
+
+export function performanceTracksPlugin(): Plugin {
+  return {
+    name: "@rangojs/router:performance-tracks",
+    // Only configureServer hook — naturally dev-only
+
+    configureServer(server) {
+      console.log("[perf-tracks] plugin loaded, configureServer called");
+      const hot = server.environments.client.hot;
+      const registry = getRegistry();
+      const sessions = registry.sessions;
+
+      const sendChunk = (debugId: string, chunk: Uint8Array) => {
+        hot.send(DEBUG_S2C_EVENT, {
+          i: debugId,
+          b: bytesToBase64(chunk),
+        } satisfies DebugPayload);
+      };
+
+      const cleanupIfEnded = (debugId: string, session: DebugSession) => {
+        if (session.pendingChunks || !session.ended) return;
+        sessions.delete(debugId);
+        hot.send(DEBUG_S2C_EVENT, {
+          i: debugId,
+          d: true,
+        } satisfies DebugPayload);
+      };
+
+      const registerDebugChannel = (debugId: string) => {
+        let session = sessions.get(debugId);
+        if (!session) {
+          session = { pendingChunks: [], ended: false };
+          sessions.set(debugId, session);
+        }
+
+        // Readable: receives client-to-server commands via WS
+        const readable = new ReadableStream<Uint8Array>({
+          start(controller) {
+            session!.cmdController = controller;
+          },
+          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) {
+              session!.pendingChunks.push(chunk);
+            } else {
+              sendChunk(debugId, chunk);
+            }
+          },
+          close() {
+            session!.ended = true;
+            cleanupIfEnded(debugId, session!);
+          },
+          abort() {
+            session!.ended = true;
+            cleanupIfEnded(debugId, session!);
+          },
+        });
+
+        // Store on globalThis so the RSC handler can retrieve it
+        registry.channels.set(debugId, { readable, writable });
+      };
+
+      // Listen for client-to-server debug messages
+      // Payload shapes: { i, d: true } (done), { i, b } (chunk), { i } (ready)
+      hot.on(DEBUG_C2S_EVENT, (raw: unknown) => {
+        const payload = raw as { i: string; b?: string; d?: true };
+        const session = sessions.get(payload.i);
+
+        if (payload.d) {
+          if (session?.cmdController) {
+            try {
+              session.cmdController.close();
+            } catch {
+              // ignore
+            }
+            delete session.cmdController;
+          }
+          return;
+        }
+
+        if (payload.b) {
+          if (session?.cmdController) {
+            try {
+              session.cmdController.enqueue(base64ToBytes(payload.b));
+            } catch {
+              delete session!.cmdController;
+            }
+          }
+          return;
+        }
+
+        // Ready signal — flush pending chunks
+        if (session) {
+          if (session.pendingChunks) {
+            for (const chunk of session.pendingChunks) {
+              sendChunk(payload.i, chunk);
+            }
+            delete session.pendingChunks;
+          }
+          cleanupIfEnded(payload.i, session);
+        } else {
+          sessions.set(payload.i, { ended: false });
+        }
+      });
+
+      // Register middleware directly (not as post-hook) so it runs
+      // BEFORE the RSC handler — the channel must exist before rendering.
+      server.middlewares.use((req: any, _res: any, next: any) => {
+        const existingId = req.headers[DEBUG_ID_HEADER.toLowerCase()] as string;
+        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);
+          }
+        }
+
+        registerDebugChannel(debugId);
+        console.log(
+          "[perf-tracks] middleware: created channel for",
+          debugId,
+          "from",
+          existingId ? "client header" : "SSR inject",
+        );
+        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.
@@ -54,6 +55,7 @@ import { createRouterDiscoveryPlugin } from "./router-discovery.js";
 export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
   const resolvedOptions: RangoOptions = options ?? { preset: "node" };
   const preset = resolvedOptions.preset ?? "node";
+  console.log("[perf-tracks] rango() called, preset:", preset);
   const showBanner = resolvedOptions.banner ?? true;
 
   const plugins: PluginOption[] = [];
@@ -334,6 +336,15 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
     // Add virtual entries plugin (RSC entry generated lazily from routerRef)
     plugins.push(createVirtualEntriesPlugin(finalEntries, routerRef));
 
+    // Dev-only: React Performance Tracks (debugChannel transport via HMR WS)
+    // Must be before rsc() so middleware runs before RSC handler.
+    const perfPlugin = performanceTracksPlugin();
+    console.log(
+      "[perf-tracks] rango: plugin created, has configureServer:",
+      !!perfPlugin.configureServer,
+    );
+    plugins.push(perfPlugin);
+
     plugins.push(
       rsc({
         entries: finalEntries,