@rangojs/router 0.0.0-experimental.50 → 0.0.0-experimental.5035014b

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,220 @@
+/**
+ * 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);
+    return channel;
+  }
+  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",
+
+    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 });
+        }
+      });
+
+      // Intercept requests to create debug channels
+      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;
+          }
+
+          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);
+          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;
 }