@rangojs/router 0.0.0-experimental.a769fbe7 → 0.0.0-experimental.ae6e7825

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.a769fbe7",
+  version: "0.0.0-experimental.ae6e7825",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -1887,7 +1887,7 @@ var package_default = {
     "test:unit:watch": "vitest"
   },
   dependencies: {
-    "@vitejs/plugin-rsc": "^0.5.14",
+    "@vitejs/plugin-rsc": "^0.5.19",
     "magic-string": "^0.30.17",
     picomatch: "^4.0.3",
     "rsc-html-stream": "^0.0.7"
@@ -4862,24 +4862,50 @@ ${details}`
 }
 
 // src/vite/plugins/performance-tracks.ts
+import { Module } from "node:module";
 var DEBUG_ID_HEADER = "X-RSC-Debug-Id";
 var DEBUG_S2C_EVENT = "rango:perf-s2c";
 var DEBUG_C2S_EVENT = "rango:perf-c2s";
 var GLOBAL_KEY = "__RANGO_DEBUG_CHANNELS__";
 function getRegistry() {
-  return globalThis[GLOBAL_KEY] ??= {
+  return Module[GLOBAL_KEY] ??= {
     channels: /* @__PURE__ */ new Map(),
     sessions: /* @__PURE__ */ new Map()
   };
 }
 var bytesToBase64 = (bytes) => Buffer.from(bytes).toString("base64");
 var base64ToBytes = (base64) => new Uint8Array(Buffer.from(base64, "base64"));
+var RSDW_PATCH_RE = /((?:var|let|const)\s+\w+\s*=\s*root\._children\s*,\s*(\w+)\s*=\s*root\._debugInfo\s*[;,])/;
+function buildPatchReplacement(match, debugInfoVar) {
+  return `${match}
+if (${debugInfoVar} && 0 === ${debugInfoVar}.length && "fulfilled" === root.status) {
+  var _resolved = "function" === typeof resolveLazy ? resolveLazy(root.value) : root.value;
+  if ("object" === typeof _resolved && null !== _resolved && isArrayImpl(_resolved._debugInfo)) {
+    ${debugInfoVar} = _resolved._debugInfo;
+  }
+}`;
+}
 function performanceTracksPlugin() {
   return {
     name: "@rangojs/router:performance-tracks",
-    apply: "serve",
-    enforce: "pre",
+    // configureServer + transform — naturally dev-only
+    transform(code, id) {
+      if (!id.includes("react-server-dom") || !id.includes("client")) return;
+      const match = code.match(RSDW_PATCH_RE);
+      if (!match) return;
+      const patched = code.replace(
+        match[1],
+        buildPatchReplacement(match[1], match[2])
+      );
+      console.log(
+        "[perf-tracks] patched RSDW client for plain-object _debugInfo recovery (var:",
+        match[2],
+        ")"
+      );
+      return patched;
+    },
     configureServer(server) {
+      console.log("[perf-tracks] plugin loaded, configureServer called");
       const hot = server.environments.client.hot;
       const registry = getRegistry();
       const sessions = registry.sessions;
@@ -4911,8 +4937,20 @@ function performanceTracksPlugin() {
             delete session.cmdController;
           }
         });
+        let chunkCount = 0;
         const writable = new WritableStream({
           write(chunk) {
+            chunkCount++;
+            if (chunkCount <= 3) {
+              console.log(
+                "[perf-tracks] writable: chunk #" + chunkCount,
+                "size:",
+                chunk.byteLength,
+                "for",
+                debugId.slice(0, 8),
+                session.pendingChunks ? "(buffered)" : "(sent)"
+              );
+            }
             if (session.pendingChunks) {
               session.pendingChunks.push(chunk);
             } else {
@@ -4920,6 +4958,12 @@ function performanceTracksPlugin() {
             }
           },
           close() {
+            console.log(
+              "[perf-tracks] writable: closed after",
+              chunkCount,
+              "chunks for",
+              debugId.slice(0, 8)
+            );
             session.ended = true;
             cleanupIfEnded(debugId, session);
           },
@@ -4954,6 +4998,16 @@ function performanceTracksPlugin() {
           return;
         }
         if (session) {
+          const pending = session.pendingChunks?.length ?? 0;
+          const ended = session.ended;
+          console.log(
+            "[perf-tracks] ready signal for",
+            payload.i.slice(0, 8),
+            "pending:",
+            pending,
+            "ended:",
+            ended
+          );
           if (session.pendingChunks) {
             for (const chunk of session.pendingChunks) {
               sendChunk(payload.i, chunk);
@@ -4962,13 +5016,20 @@ function performanceTracksPlugin() {
           }
           cleanupIfEnded(payload.i, session);
         } else {
+          console.log(
+            "[perf-tracks] ready signal for",
+            payload.i.slice(0, 8),
+            "(no session yet)"
+          );
           sessions.set(payload.i, { ended: false });
         }
       });
       server.middlewares.use((req, _res, next) => {
+        const url = req.url || "";
         const existingId = req.headers[DEBUG_ID_HEADER.toLowerCase()];
         const isHtml = req.headers.accept?.includes("text/html");
-        if (!existingId && !isHtml) {
+        const isRsc = url.includes("_rsc_partial");
+        if (!existingId && !isHtml && !isRsc) {
           next();
           return;
         }
@@ -4982,10 +5043,11 @@ function performanceTracksPlugin() {
         }
         registerDebugChannel(debugId);
         console.log(
-          "[perf-tracks] middleware: created channel for",
+          "[perf-tracks] middleware: channel for",
           debugId,
-          "from",
-          existingId ? "client header" : "SSR inject"
+          "url:",
+          url.slice(0, 80),
+          existingId ? "(client)" : isHtml ? "(SSR)" : "(RSC partial)"
         );
         next();
       });
@@ -4997,6 +5059,7 @@ function performanceTracksPlugin() {
 async function rango(options) {
   const resolvedOptions = options ?? { preset: "node" };
   const preset = resolvedOptions.preset ?? "node";
+  console.log("[perf-tracks] rango() called, preset:", preset);
   const showBanner = resolvedOptions.banner ?? true;
   const plugins = [];
   const rangoAliases = getPackageAliases();
@@ -5214,6 +5277,12 @@ ${list}`);
       }
     });
     plugins.push(createVirtualEntriesPlugin(finalEntries, routerRef));
+    const perfPlugin = performanceTracksPlugin();
+    console.log(
+      "[perf-tracks] rango: plugin created, has configureServer:",
+      !!perfPlugin.configureServer
+    );
+    plugins.push(perfPlugin);
     plugins.push(
       rsc({
         entries: finalEntries
@@ -5257,7 +5326,6 @@ ${list}`);
       staticRouteTypesGeneration: resolvedOptions.staticRouteTypesGeneration
     })
   );
-  plugins.push(performanceTracksPlugin());
   return plugins;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.a769fbe7",
+  "version": "0.0.0-experimental.ae6e7825",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -142,7 +142,7 @@
     "test:unit:watch": "vitest"
   },
   "dependencies": {
-    "@vitejs/plugin-rsc": "^0.5.14",
+    "@vitejs/plugin-rsc": "^0.5.19",
     "magic-string": "^0.30.17",
     "picomatch": "^4.0.3",
     "rsc-html-stream": "^0.0.7"

package/src/browser/debug-channel.ts

@@ -55,17 +55,36 @@ export function createClientDebugChannel(debugId: string): {
   // Readable: receives server-to-client debug data via HMR WS
   const readable = new ReadableStream<Uint8Array>({
     start(controller) {
+      let chunks = 0;
       onServerData = (payload: DebugPayload) => {
         if (closed || payload.i !== debugId) return;
         if ("b" in payload) {
+          chunks++;
+          if (chunks <= 3)
+            console.log(
+              "[perf-tracks] client readable: chunk #" + chunks,
+              "size:",
+              base64ToBytes(payload.b).byteLength,
+            );
           controller.enqueue(base64ToBytes(payload.b));
         }
         if ("d" in payload) {
+          console.log(
+            "[perf-tracks] client readable: done after",
+            chunks,
+            "chunks",
+          );
           cleanup();
           controller.close();
         }
       };
       hot.on(DEBUG_S2C_EVENT, onServerData);
+      // Send "ready" signal so the server flushes buffered debug data
+      console.log(
+        "[perf-tracks] client: sending ready signal for",
+        debugId.slice(0, 8),
+      );
+      hot.send(DEBUG_C2S_EVENT, { i: debugId });
     },
     cancel() {
       cleanup(true);

package/src/browser/navigation-client.ts

@@ -109,24 +109,25 @@ 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;
-      if (debugId) {
-        console.log(
-          "[perf-tracks] client: debugId =",
-          debugId,
-          "channel =",
-          debugChannel ? "created" : "null (no HMR)",
-        );
-      }
+      // Dev-only: debug channel is created lazily only for fresh fetches.
+      // Cached/inflight responses don't have a server-side channel, so passing
+      // debugChannel to createFromFetch would hang waiting for data that never comes.
+      let debugChannel: {
+        readable: ReadableStream<Uint8Array>;
+        writable: WritableStream<Uint8Array>;
+      } | null = null;
 
       /** Start a fresh navigation fetch (no cache / inflight hit). */
       const doFreshFetch = (): Promise<Response> => {
+        // Dev-only: create debug channel for React Performance Tracks
+        const debugId = (import.meta as any).hot
+          ? crypto.randomUUID()
+          : undefined;
+        if (debugId) {
+          debugChannel = createClientDebugChannel(debugId);
+          console.log("[perf-tracks] client: fresh fetch, debugId =", debugId);
+        }
+
         if (tx) {
           browserDebugLog(tx, "fetching", {
             path: `${fetchUrl.pathname}${fetchUrl.search}`,
@@ -241,9 +242,7 @@ export function createNavigationClient(
         // Deserialize RSC payload
         const payload = await deps.createFromFetch<RscPayload>(
           responsePromise,
-          {
-            ...(debugChannel && { debugChannel, findSourceMapURL }),
-          },
+          debugChannel ? { debugChannel, findSourceMapURL } : undefined,
         );
         if (tx) {
           browserDebugLog(tx, "response received", {

package/src/browser/rsc-router.tsx

@@ -11,6 +11,8 @@ import { createEventController } from "./event-controller.js";
 import { createNavigationClient } from "./navigation-client.js";
 import { createServerActionBridge } from "./server-action-bridge.js";
 import { createNavigationBridge } from "./navigation-bridge.js";
+import { createClientDebugChannel } from "./debug-channel.js";
+import { findSourceMapURL } from "../deps/browser.js";
 import { NavigationProvider } from "./react/index.js";
 import type {
   RscPayload,
@@ -139,9 +141,24 @@ export async function initBrowserApp(
     initialTheme,
   } = options;
 
+  // Dev-only: create debug channel for React Performance Tracks.
+  // The debugId was injected into the HTML bootstrap by the SSR handler.
+  // The client sends a "ready" signal so the server flushes buffered data.
+  const ssrDebugId = (globalThis as any).__RANGO_DEBUG_ID__ as
+    | string
+    | undefined;
+  const ssrDebugChannel =
+    ssrDebugId && (import.meta as any).hot
+      ? createClientDebugChannel(ssrDebugId)
+      : undefined;
+
   // Load initial payload from SSR-injected __FLIGHT_DATA__
-  const initialPayload =
-    await deps.createFromReadableStream<RscPayload>(rscStream);
+  const initialPayload = await deps.createFromReadableStream<RscPayload>(
+    rscStream,
+    ssrDebugChannel
+      ? { debugChannel: ssrDebugChannel, findSourceMapURL }
+      : undefined,
+  );
 
   // Extract themeConfig and initialTheme from payload if not explicitly provided
   // This allows virtual entries to work without importing the router

package/src/browser/types.ts

@@ -350,7 +350,16 @@ export interface RscBrowserDependencies {
       ) => string | null;
     },
   ) => Promise<T>;
-  createFromReadableStream: <T>(stream: ReadableStream) => Promise<T>;
+  createFromReadableStream: <T>(
+    stream: ReadableStream,
+    options?: {
+      debugChannel?: { readable?: ReadableStream; writable?: WritableStream };
+      findSourceMapURL?: (
+        filename: string,
+        environmentName: string,
+      ) => string | null;
+    },
+  ) => Promise<T>;
   encodeReply: (
     args: any[],
     options?: { temporaryReferences?: any },

package/src/rsc/handler.ts

@@ -428,17 +428,17 @@ export function createRSCHandler<
     }
     // Dev-only: wire debug channel for React Performance Tracks
     if (process.env.NODE_ENV !== "production") {
-      const debugId = request.headers.get(DEBUG_ID_HEADER);
-      console.log("[perf-tracks] handler: debugId header =", debugId);
-      if (debugId) {
-        const channel = createServerDebugChannel(debugId);
-        console.log(
-          "[perf-tracks] handler: channel =",
-          channel ? "created" : "NOT FOUND",
-        );
-        if (channel) {
-          requestContext._debugChannel = channel;
-        }
+      // Client navigations send the debugId as a header.
+      // SSR requests have no client — generate one and create the channel directly.
+      const clientDebugId = request.headers.get(DEBUG_ID_HEADER);
+      const debugId = clientDebugId || crypto.randomUUID();
+      const channel = clientDebugId
+        ? createServerDebugChannel(debugId)
+        : createServerDebugChannel(debugId);
+      if (channel) {
+        requestContext._debugChannel = channel;
+        requestContext._debugId = debugId;
+        console.log("[perf-tracks] debug channel attached for", debugId);
       }
     }
     // Wire background error reporting so "use cache" and other subsystems

package/src/rsc/rsc-rendering.ts

@@ -227,6 +227,7 @@ export async function handleRscRendering<TEnv>(
   const htmlStream = await ssrModule.renderHTML(rscStream, {
     nonce,
     streamMode,
+    debugId: reqCtx._debugId,
   });
   const ssrRenderDur = performance.now() - ssrRenderStart;
   appendMetric(metricsStore, "ssr-render-html", ssrRenderStart, ssrRenderDur);

package/src/rsc/types.ts

@@ -130,6 +130,9 @@ export interface SSRRenderOptions {
    * - `"allReady"` — await `stream.allReady` before returning.
    */
   streamMode?: import("../router/router-options.js").SSRStreamMode;
+
+  /** @internal Dev-only: debug channel ID for React Performance Tracks */
+  debugId?: string;
 }
 
 /**

package/src/server/request-context.ts

@@ -293,6 +293,9 @@ export interface RequestContext<
     readable: ReadableStream;
     writable: WritableStream;
   };
+
+  /** @internal Dev-only: debug channel ID for React Performance Tracks */
+  _debugId?: string;
 }
 
 /**
@@ -323,6 +326,7 @@ export type PublicRequestContext<
   | "_debugPerformance"
   | "_metricsStore"
   | "_debugChannel"
+  | "_debugId"
   | "_setStatus"
   | "res"
 >;

package/src/ssr/index.tsx

@@ -64,6 +64,9 @@ export interface SSRRenderOptions {
    * - `"allReady"` — await `stream.allReady` before returning.
    */
   streamMode?: import("../router/router-options.js").SSRStreamMode;
+
+  /** @internal Dev-only: debug channel ID for React Performance Tracks */
+  debugId?: string;
 }
 
 /**
@@ -329,7 +332,16 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
       }
 
       // Get bootstrap script content
-      const bootstrapScriptContent = await loadBootstrapScriptContent();
+      let bootstrapScriptContent = await loadBootstrapScriptContent();
+
+      // Dev-only: inject debugId for React Performance Tracks.
+      // The client reads this during hydration to create the matching WS channel.
+      const debugId = options?.debugId;
+      if (debugId) {
+        bootstrapScriptContent =
+          `globalThis.__RANGO_DEBUG_ID__=${JSON.stringify(debugId)};` +
+          bootstrapScriptContent;
+      }
 
       // Render React tree to HTML stream
       // Pass formState for useActionState progressive enhancement if provided

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

@@ -46,8 +46,12 @@ type DebugChannelRegistry = {
 
 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 ((globalThis as any)[GLOBAL_KEY] ??= {
+  return ((Module as any)[GLOBAL_KEY] ??= {
     channels: new Map(),
     sessions: new Map(),
   });
@@ -87,13 +91,51 @@ const bytesToBase64 = (bytes: Uint8Array) =>
 const base64ToBytes = (base64: string) =>
   new Uint8Array(Buffer.from(base64, "base64"));
 
+// Patch for RSDW client: React's flushComponentPerformance uses splice(0) to
+// empty chunk._debugInfo after resolution, then tries to recover it from the
+// resolved value. The fallback only works for arrays, async iterables, React
+// elements, and lazy types — not plain objects. Since our RscPayload is a
+// plain object, _debugInfo is lost and the Server Components track stays empty.
+// This patch relaxes the check so _debugInfo is recovered from any object.
+//
+// Uses regex to be resilient to Vite's dep optimizer reformatting.
+const RSDW_PATCH_RE =
+  /((?:var|let|const)\s+\w+\s*=\s*root\._children\s*,\s*(\w+)\s*=\s*root\._debugInfo\s*[;,])/;
+
+function buildPatchReplacement(match: string, debugInfoVar: string): string {
+  return `${match}
+if (${debugInfoVar} && 0 === ${debugInfoVar}.length && "fulfilled" === root.status) {
+  var _resolved = "function" === typeof resolveLazy ? resolveLazy(root.value) : root.value;
+  if ("object" === typeof _resolved && null !== _resolved && isArrayImpl(_resolved._debugInfo)) {
+    ${debugInfoVar} = _resolved._debugInfo;
+  }
+}`;
+}
+
 export function performanceTracksPlugin(): Plugin {
   return {
     name: "@rangojs/router:performance-tracks",
-    apply: "serve",
-    enforce: "pre",
+    // configureServer + transform — naturally dev-only
+
+    transform(code, id) {
+      // Only patch RSDW client browser bundle
+      if (!id.includes("react-server-dom") || !id.includes("client")) return;
+      const match = code.match(RSDW_PATCH_RE);
+      if (!match) return;
+      const patched = code.replace(
+        match[1]!,
+        buildPatchReplacement(match[1]!, match[2]!),
+      );
+      console.log(
+        "[perf-tracks] patched RSDW client for plain-object _debugInfo recovery (var:",
+        match[2],
+        ")",
+      );
+      return patched;
+    },
 
     configureServer(server) {
+      console.log("[perf-tracks] plugin loaded, configureServer called");
       const hot = server.environments.client.hot;
       const registry = getRegistry();
       const sessions = registry.sessions;
@@ -131,9 +173,21 @@ export function performanceTracksPlugin(): Plugin {
           },
         });
 
+        let chunkCount = 0;
         // Writable: React writes debug data here, we forward to client via WS
         const writable = new WritableStream<Uint8Array>({
           write(chunk) {
+            chunkCount++;
+            if (chunkCount <= 3) {
+              console.log(
+                "[perf-tracks] writable: chunk #" + chunkCount,
+                "size:",
+                chunk.byteLength,
+                "for",
+                debugId.slice(0, 8),
+                session!.pendingChunks ? "(buffered)" : "(sent)",
+              );
+            }
             if (session!.pendingChunks) {
               session!.pendingChunks.push(chunk);
             } else {
@@ -141,6 +195,12 @@ export function performanceTracksPlugin(): Plugin {
             }
           },
           close() {
+            console.log(
+              "[perf-tracks] writable: closed after",
+              chunkCount,
+              "chunks for",
+              debugId.slice(0, 8),
+            );
             session!.ended = true;
             cleanupIfEnded(debugId, session!);
           },
@@ -185,6 +245,16 @@ export function performanceTracksPlugin(): Plugin {
 
         // Ready signal — flush pending chunks
         if (session) {
+          const pending = session.pendingChunks?.length ?? 0;
+          const ended = session.ended;
+          console.log(
+            "[perf-tracks] ready signal for",
+            payload.i.slice(0, 8),
+            "pending:",
+            pending,
+            "ended:",
+            ended,
+          );
           if (session.pendingChunks) {
             for (const chunk of session.pendingChunks) {
               sendChunk(payload.i, chunk);
@@ -193,17 +263,26 @@ export function performanceTracksPlugin(): Plugin {
           }
           cleanupIfEnded(payload.i, session);
         } else {
+          console.log(
+            "[perf-tracks] ready signal for",
+            payload.i.slice(0, 8),
+            "(no session yet)",
+          );
           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.
+      // Create debug channels only for RSC-handled requests:
+      // - HTML page requests (SSR)
+      // - RSC partial requests (client navigation)
+      // - Requests with existing debug header (client-initiated)
       server.middlewares.use((req: any, _res: any, next: any) => {
+        const url: string = req.url || "";
         const existingId = req.headers[DEBUG_ID_HEADER.toLowerCase()] as string;
         const isHtml = req.headers.accept?.includes("text/html");
+        const isRsc = url.includes("_rsc_partial");
 
-        if (!existingId && !isHtml) {
+        if (!existingId && !isHtml && !isRsc) {
           next();
           return;
         }
@@ -219,10 +298,11 @@ export function performanceTracksPlugin(): Plugin {
 
         registerDebugChannel(debugId);
         console.log(
-          "[perf-tracks] middleware: created channel for",
+          "[perf-tracks] middleware: channel for",
           debugId,
-          "from",
-          existingId ? "client header" : "SSR inject",
+          "url:",
+          url.slice(0, 80),
+          existingId ? "(client)" : isHtml ? "(SSR)" : "(RSC partial)",
         );
         next();
       });

package/src/vite/rango.ts

@@ -55,6 +55,7 @@ import { performanceTracksPlugin } from "./plugins/performance-tracks.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[] = [];
@@ -335,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,
@@ -442,8 +452,5 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
     }),
   );
 
-  // Dev-only: React Performance Tracks (debugChannel transport via HMR WS)
-  plugins.push(performanceTracksPlugin());
-
   return plugins;
 }