@rangojs/router 0.0.0-experimental.ffbe1b7f → 0.0.0-experimental.preview.1774275339

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.ffbe1b7f",
+  version: "0.0.0-experimental.preview.1774275339",
   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"
@@ -2784,6 +2784,258 @@ function createVersionPlugin() {
 
 // src/vite/utils/shared-utils.ts
 import * as Vite from "vite";
+
+// src/vite/plugins/performance-tracks.ts
+import { readFile } from "node:fs/promises";
+var DEBUG_S2C_EVENT = "rango:perf-s2c";
+var DEBUG_C2S_EVENT = "rango:perf-c2s";
+var DEBUG_RELAY_PREFIX = "/__rango_devtools__/perf";
+function getRegistry() {
+  return globalThis.__RANGO_DEBUG_CHANNELS__ ??= {
+    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 patchRsdwClientDebugInfoRecovery(code) {
+  const match = code.match(RSDW_PATCH_RE);
+  if (!match) {
+    return { code, debugInfoVar: null };
+  }
+  return {
+    code: code.replace(
+      match[1],
+      buildPatchReplacement(match[1], match[2])
+    ),
+    debugInfoVar: match[2]
+  };
+}
+function performanceTracksOptimizeDepsPlugin() {
+  return {
+    name: "@rangojs/router:performance-tracks-optimize-deps",
+    setup(build) {
+      build.onLoad(
+        {
+          filter: /react-server-dom-webpack-client\.browser\.(development|production)\.js$/
+        },
+        async (args) => {
+          const code = await readFile(args.path, "utf8");
+          const patched = patchRsdwClientDebugInfoRecovery(code);
+          return {
+            contents: patched.code,
+            loader: "js"
+          };
+        }
+      );
+    }
+  };
+}
+function performanceTracksPlugin() {
+  return {
+    name: "@rangojs/router:performance-tracks",
+    // configureServer + transform — naturally dev-only
+    transform(code, id) {
+      if (!id.includes("react-server-dom") || !id.includes("client")) return;
+      const patched = patchRsdwClientDebugInfoRecovery(code);
+      if (!patched.debugInfoVar) return;
+      console.log(
+        "[perf-tracks] patched RSDW client for plain-object _debugInfo recovery (var:",
+        patched.debugInfoVar,
+        ")"
+      );
+      return patched.code;
+    },
+    configureServer(server) {
+      console.log("[perf-tracks] plugin loaded, configureServer called");
+      const hot = server.environments.client.hot;
+      const registry = getRegistry();
+      const sessions = registry.sessions;
+      const getSession = (debugId) => {
+        let session = sessions.get(debugId);
+        if (!session) {
+          session = {
+            pendingClientChunks: [],
+            pendingServerMessages: [],
+            waiters: [],
+            ready: false,
+            ended: false,
+            browserDoneSent: false
+          };
+          sessions.set(debugId, session);
+        }
+        return session;
+      };
+      const sendChunk = (debugId, chunk) => {
+        hot.send(DEBUG_S2C_EVENT, {
+          i: debugId,
+          b: bytesToBase64(chunk)
+        });
+      };
+      const flushBrowserDoneIfReady = (debugId, session) => {
+        if (!session.ended || !session.ready || session.browserDoneSent) return;
+        session.browserDoneSent = true;
+        hot.send(DEBUG_S2C_EVENT, {
+          i: debugId,
+          d: true
+        });
+      };
+      const closeRuntimeWaiters = (session) => {
+        const waiters = session.waiters.splice(0);
+        for (const waiter of waiters) {
+          waiter({ type: "done" });
+        }
+      };
+      const cleanupIfSettled = (debugId, session) => {
+        if (!session.ended || !session.browserDoneSent || session.waiters.length > 0 || session.pendingServerMessages.length > 0) {
+          return;
+        }
+        sessions.delete(debugId);
+      };
+      const readRequestBody = async (req) => {
+        const chunks = [];
+        for await (const chunk of req) {
+          chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        }
+        return new Uint8Array(Buffer.concat(chunks));
+      };
+      server.middlewares.use(async (req, res, next) => {
+        const url = new URL(req.url || "/", "http://localhost");
+        if (!url.pathname.startsWith(DEBUG_RELAY_PREFIX)) {
+          next();
+          return;
+        }
+        const debugId = url.searchParams.get("i");
+        if (!debugId) {
+          res.statusCode = 400;
+          res.end("missing debugId");
+          return;
+        }
+        const session = getSession(debugId);
+        if (url.pathname === `${DEBUG_RELAY_PREFIX}/s2c`) {
+          if (url.searchParams.get("done") === "1") {
+            session.ended = true;
+            closeRuntimeWaiters(session);
+            flushBrowserDoneIfReady(debugId, session);
+            cleanupIfSettled(debugId, session);
+            res.statusCode = 204;
+            res.end();
+            return;
+          }
+          const chunk = await readRequestBody(req);
+          if (chunk.byteLength <= 3) {
+            console.log(
+              "[perf-tracks] writable: chunk size:",
+              chunk.byteLength,
+              "for",
+              debugId.slice(0, 8),
+              session.ready ? "(sent)" : "(buffered)"
+            );
+          }
+          if (session.ready) {
+            sendChunk(debugId, chunk);
+          } else {
+            session.pendingClientChunks.push(chunk);
+          }
+          res.statusCode = 204;
+          res.end();
+          return;
+        }
+        if (url.pathname === `${DEBUG_RELAY_PREFIX}/c2s`) {
+          const nextMessage = session.pendingServerMessages.shift();
+          if (nextMessage) {
+            res.setHeader("Content-Type", "application/json");
+            res.end(
+              JSON.stringify(
+                nextMessage.type === "done" ? { d: true } : { b: bytesToBase64(nextMessage.chunk) }
+              )
+            );
+            cleanupIfSettled(debugId, session);
+            return;
+          }
+          if (session.ended) {
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ d: true }));
+            cleanupIfSettled(debugId, session);
+            return;
+          }
+          const timeout = setTimeout(() => {
+            const index = session.waiters.indexOf(waiter);
+            if (index >= 0) session.waiters.splice(index, 1);
+            res.statusCode = 204;
+            res.end();
+          }, 3e4);
+          const waiter = (message) => {
+            clearTimeout(timeout);
+            if (!message) {
+              res.statusCode = 204;
+              res.end();
+              return;
+            }
+            res.setHeader("Content-Type", "application/json");
+            res.end(
+              JSON.stringify(
+                message.type === "done" ? { d: true } : { b: bytesToBase64(message.chunk) }
+              )
+            );
+          };
+          session.waiters.push(waiter);
+          return;
+        }
+        res.statusCode = 404;
+        res.end();
+      });
+      hot.on(DEBUG_C2S_EVENT, (raw) => {
+        const payload = raw;
+        const session = getSession(payload.i);
+        const pushServerMessage = (message) => {
+          const waiter = session.waiters.shift();
+          if (waiter) {
+            waiter(message);
+          } else {
+            session.pendingServerMessages.push(message);
+          }
+        };
+        if (payload.d) {
+          pushServerMessage({ type: "done" });
+          cleanupIfSettled(payload.i, session);
+          return;
+        }
+        if (payload.b) {
+          pushServerMessage({ type: "chunk", chunk: base64ToBytes(payload.b) });
+          return;
+        }
+        session.ready = true;
+        const pending = session.pendingClientChunks.length;
+        console.log(
+          "[perf-tracks] ready signal for",
+          payload.i.slice(0, 8),
+          "pending:",
+          pending,
+          "ended:",
+          session.ended
+        );
+        for (const chunk of session.pendingClientChunks) {
+          sendChunk(payload.i, chunk);
+        }
+        session.pendingClientChunks = [];
+        flushBrowserDoneIfReady(payload.i, session);
+        cleanupIfSettled(payload.i, session);
+      });
+    }
+  };
+}
+
+// src/vite/utils/shared-utils.ts
 var versionEsbuildPlugin = {
   name: "@rangojs/router-version",
   setup(build) {
@@ -2801,7 +3053,7 @@ var versionEsbuildPlugin = {
   }
 };
 var sharedEsbuildOptions = {
-  plugins: [versionEsbuildPlugin]
+  plugins: [versionEsbuildPlugin, performanceTracksOptimizeDepsPlugin()]
 };
 function createVirtualEntriesPlugin(entries, routerPathRef) {
   const virtualModules = {};
@@ -4865,10 +5117,20 @@ ${details}`
 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();
-  const excludeDeps = getExcludeDeps();
+  const excludeDeps = [
+    ...getExcludeDeps(),
+    // The public browser entry re-exports the RSDW browser client.
+    // Excluding both keeps Vite from freezing the unpatched bundle into
+    // .vite/deps before our source transforms run.
+    "@vitejs/plugin-rsc/browser",
+    // Keep the browser RSDW client out of Vite's dep optimizer so our
+    // cjs-to-esm and performance-tracks transforms can patch the real file.
+    "@vitejs/plugin-rsc/vendor/react-server-dom/client.browser"
+  ];
   const routerRef = { path: void 0 };
   const prerenderEnabled = true;
   if (preset === "cloudflare") {
@@ -4964,6 +5226,12 @@ async function rango(options) {
       }
     });
     plugins.push(createVirtualEntriesPlugin(finalEntries));
+    const perfPlugin = performanceTracksPlugin();
+    console.log(
+      "[perf-tracks] rango: plugin created, has configureServer:",
+      !!perfPlugin.configureServer
+    );
+    plugins.push(perfPlugin);
     plugins.push(
       rsc({
         entries: finalEntries,
@@ -5082,6 +5350,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.ffbe1b7f",
+  "version": "0.0.0-experimental.preview.1774275339",
   "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/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,112 @@
+/**
+ * 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) {
+      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);
+    },
+  });
+
+  // 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,8 @@ import {
   startBrowserTransaction,
 } from "./logging.js";
 import { getRangoState } from "./rango-state.js";
+import { createClientDebugChannel, DEBUG_ID_HEADER } from "./debug-channel.js";
+import { findSourceMapURL } from "../deps/browser.js";
 import {
   extractRscHeaderUrl,
   emptyResponse,
@@ -107,8 +109,25 @@ export function createNavigationClient(
         resolveStreamComplete = resolve;
       });
 
+      // 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}`,
@@ -124,6 +143,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 +240,10 @@ export function createNavigationClient(
 
       try {
         // Deserialize RSC payload
-        const payload = await deps.createFromFetch<RscPayload>(responsePromise);
+        const payload = await deps.createFromFetch<RscPayload>(
+          responsePromise,
+          debugChannel ? { debugChannel, findSourceMapURL } : undefined,
+        );
         if (tx) {
           browserDebugLog(tx, "response received", {
             isPartial: payload.metadata?.isPartial,

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/server-action-bridge.ts

@@ -4,6 +4,8 @@ import type {
   RscPayload,
 } from "./types.js";
 import { createPartialUpdater } from "./partial-update.js";
+import { createClientDebugChannel, DEBUG_ID_HEADER } from "./debug-channel.js";
+import { findSourceMapURL } from "../deps/browser.js";
 import { createNavigationTransaction } from "./navigation-transaction.js";
 import {
   reconcileSegments,
@@ -199,6 +201,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 +220,7 @@ export function createServerActionBridge(
           ...(interceptSourceUrl && {
             "X-RSC-Router-Intercept-Source": interceptSourceUrl,
           }),
+          ...(debugId && { [DEBUG_ID_HEADER]: debugId }),
         },
         body: encodedBody,
         signal: fetchAbort.signal,
@@ -272,6 +283,7 @@ export function createServerActionBridge(
       try {
         payload = await deps.createFromFetch<RscPayload>(responsePromise, {
           temporaryReferences,
+          ...(debugChannel && { debugChannel, findSourceMapURL }),
         });
       } catch (error) {
         // Clean up streaming token on error (may be null if fetch failed before .then() ran)