@rangojs/router 0.0.0-experimental.f3c21dba → 0.0.0-experimental.f681f24a

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,21 @@ 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);
+      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;
+        }
+      }
+    }
     // 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 +1062,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/context.ts

@@ -273,6 +273,9 @@ interface HelperContext {
     string,
     import("../cache/profile-registry.js").CacheProfile
   >;
+  /** True when resolving handlers inside a cache() DSL boundary.
+   *  Read by ctx.get() to guard non-cacheable variable reads. */
+  insideCacheScope?: boolean;
 }
 // Use a global symbol key so the AsyncLocalStorage instance survives HMR
 // module re-evaluation. Without this, Vite's RSC module runner may create
@@ -666,3 +669,12 @@ export function track(label: string, depth?: number): () => void {
     });
   };
 }
+
+/**
+ * Check if the current execution is inside a cache() DSL boundary.
+ * Returns false inside loader execution — loaders are always fresh
+ * (never cached), so non-cacheable reads are safe.
+ */
+export function isInsideCacheScope(): boolean {
+  return RSCRouterContext.getStore()?.insideCacheScope === true;
+}

package/src/server/request-context.ts

@@ -20,7 +20,12 @@ import type {
   DefaultRouteName,
 } from "../types/global-namespace.js";
 import type { Handle } from "../handle.js";
-import { type ContextVar, contextGet, contextSet } from "../context-var.js";
+import {
+  type ContextVar,
+  contextGet,
+  contextSet,
+  isNonCacheable,
+} from "../context-var.js";
 import { createHandleStore, type HandleStore } from "./handle-store.js";
 import { isHandle } from "../handle.js";
 import { track, type MetricsStore } from "./context.js";
@@ -30,6 +35,7 @@ import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
 import { THEME_COOKIE } from "../theme/constants.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
+import { isInsideCacheScope } from "./context.js";
 import {
   createReverseFunction,
   stripInternalParams,
@@ -72,8 +78,12 @@ export interface RequestContext<
   };
   /** Set a variable (shared with middleware and handlers) */
   set: {
-    <T>(contextVar: ContextVar<T>, value: T): void;
-    <K extends string>(key: K, value: any): void;
+    <T>(
+      contextVar: ContextVar<T>,
+      value: T,
+      options?: { cache?: boolean },
+    ): void;
+    <K extends string>(key: K, value: any, options?: { cache?: boolean }): void;
   };
   /**
    * Route params (populated after route matching)
@@ -277,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;
+  };
 }
 
 /**
@@ -306,6 +322,7 @@ export type PublicRequestContext<
   | "_reportBackgroundError"
   | "_debugPerformance"
   | "_metricsStore"
+  | "_debugChannel"
   | "_setStatus"
   | "res"
 >;
@@ -506,6 +523,18 @@ export function createRequestContext<TEnv>(
     responseCookieCache = null;
   };
 
+  // Guard: throw if a response-level side effect is called inside a cache() scope.
+  // Uses ALS to detect the scope (set during segment resolution).
+  function assertNotInsideCacheScopeALS(methodName: string): void {
+    if (isInsideCacheScope()) {
+      throw new Error(
+        `ctx.${methodName}() cannot be called inside a cache() boundary. ` +
+          `On cache hit the handler is skipped, so this side effect would be lost. ` +
+          `Move ctx.${methodName}() to a middleware or layout outside the cache() scope.`,
+      );
+    }
+  }
+
   // Effective cookie read: response stub Set-Cookie wins, then original header.
   // The stub IS the source of truth for same-request mutations.
   const effectiveCookie = (name: string): string | undefined => {
@@ -570,11 +599,19 @@ export function createRequestContext<TEnv>(
     pathname: url.pathname,
     searchParams: cleanUrl.searchParams,
     var: variables,
-    get: ((keyOrVar: any) =>
-      contextGet(variables, keyOrVar)) as RequestContext<TEnv>["get"],
-    set: ((keyOrVar: any, value: any) => {
+    get: ((keyOrVar: any) => {
+      if (isNonCacheable(variables, keyOrVar) && isInsideCacheScope()) {
+        throw new Error(
+          `ctx.get() for a non-cacheable variable cannot be called inside a cache() boundary. ` +
+            `The variable was created with { cache: false } or set with { cache: false }, ` +
+            `and its value would be stale on cache hit. Move the read outside the cached scope.`,
+        );
+      }
+      return contextGet(variables, keyOrVar);
+    }) as RequestContext<TEnv>["get"],
+    set: ((keyOrVar: any, value: any, options?: any) => {
       assertNotInsideCacheExec(ctx, "set");
-      contextSet(variables, keyOrVar, value);
+      contextSet(variables, keyOrVar, value, options);
     }) as RequestContext<TEnv>["set"],
     params: {} as Record<string, string>,
 
@@ -612,6 +649,7 @@ export function createRequestContext<TEnv>(
 
     setCookie(name: string, value: string, options?: CookieOptions): void {
       assertNotInsideCacheExec(ctx, "setCookie");
+      assertNotInsideCacheScopeALS("setCookie");
       stubResponse.headers.append(
         "Set-Cookie",
         serializeCookieValue(name, value, options),
@@ -624,6 +662,7 @@ export function createRequestContext<TEnv>(
       options?: Pick<CookieOptions, "domain" | "path">,
     ): void {
       assertNotInsideCacheExec(ctx, "deleteCookie");
+      assertNotInsideCacheScopeALS("deleteCookie");
       stubResponse.headers.append(
         "Set-Cookie",
         serializeCookieValue(name, "", { ...options, maxAge: 0 }),
@@ -633,11 +672,13 @@ export function createRequestContext<TEnv>(
 
     header(name: string, value: string): void {
       assertNotInsideCacheExec(ctx, "header");
+      assertNotInsideCacheScopeALS("header");
       stubResponse.headers.set(name, value);
     },
 
     setStatus(status: number): void {
       assertNotInsideCacheExec(ctx, "setStatus");
+      assertNotInsideCacheScopeALS("setStatus");
       stubResponse = new Response(null, {
         status,
         headers: stubResponse.headers,
@@ -676,6 +717,7 @@ export function createRequestContext<TEnv>(
 
     onResponse(callback: (response: Response) => Response): void {
       assertNotInsideCacheExec(ctx, "onResponse");
+      assertNotInsideCacheScopeALS("onResponse");
       this._onResponseCallbacks.push(callback);
     },
 
@@ -906,7 +948,6 @@ export function createUseFunction<TEnv>(
       ),
     };
 
-    // Start loader execution with tracking
     const doneLoader = track(`loader:${loader.$$id}`, 2);
     const promise = Promise.resolve(loaderFn(loaderCtx)).finally(() => {
       doneLoader();

package/src/types/handler-context.ts

@@ -272,8 +272,16 @@ export type HandlerContext<
    * ```
    */
   set: {
-    <T>(contextVar: ContextVar<T>, value: T): void;
-  } & (<K extends keyof DefaultVars>(key: K, value: DefaultVars[K]) => void);
+    <T>(
+      contextVar: ContextVar<T>,
+      value: T,
+      options?: { cache?: boolean },
+    ): void;
+  } & (<K extends keyof DefaultVars>(
+    key: K,
+    value: DefaultVars[K],
+    options?: { cache?: boolean },
+  ) => void);
   /**
    * Response headers. Headers set here are merged into the final response.
    *
@@ -293,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.
@@ -302,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,231 @@
+/**
+ * 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__";
+
+function getRegistry(): DebugChannelRegistry {
+  return ((globalThis 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",
+    apply: "serve",
+    enforce: "pre",
+
+    configureServer(server) {
+      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.
@@ -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;
 }