@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.25dbaac3

package/src/server/context.ts

@@ -11,6 +11,7 @@ import type {
   TransitionConfig,
 } from "../types";
 import { invariant } from "../errors";
+import type { DefaultRouteName } from "../types/global-namespace.js";
 
 // ============================================================================
 //  Performance Metrics Types
@@ -25,6 +26,7 @@ export interface PerformanceMetric {
   label: string; // e.g., "route-matching", "loader:UserLoader"
   duration: number; // milliseconds
   startTime: number; // relative to request start
+  depth?: number; // nesting level for hierarchical display (0 = top-level)
 }
 
 /**
@@ -120,6 +122,8 @@ export type InterceptSelectorContext<TEnv = any> = {
   request: Request; // The HTTP request object
   env: TEnv; // Platform bindings (Cloudflare env, etc.)
   segments: InterceptSegmentsState; // Client's current segments (where navigating FROM)
+  fromRouteName?: DefaultRouteName; // Named route being navigated away from (undefined for unnamed routes)
+  toRouteName?: DefaultRouteName; // Named route being navigated to (undefined for unnamed routes)
 };
 
 /**
@@ -153,10 +157,24 @@ export type InterceptEntry = {
   when: InterceptWhenFn[]; // Selector conditions - all must return true to intercept
 };
 
+export interface ParallelEntryData
+  extends EntryPropCommon, EntryPropDatas, EntryPropSegments {
+  type: "parallel";
+  handler: Record<`@${string}`, Handler<any, any, any> | ReactNode>;
+  loading?: ReactNode | false;
+  transition?: TransitionConfig;
+  /** Set when any parallel slot is a Static definition */
+  isStaticPrerender?: true;
+  /** Per-slot static handler $$ids for build-time store lookup */
+  staticHandlerIds?: Record<string, string>;
+}
+
+export type ParallelEntries = Partial<Record<`@${string}`, ParallelEntryData>>;
+
 export type EntryPropSegments = {
   loader: LoaderEntry[];
   layout: EntryData[];
-  parallel: EntryData[]; // type: "parallel" entries with their own loaders/revalidate/loading
+  parallel: ParallelEntries; // slot -> parallel entry (same entry may back multiple slots)
   intercept: InterceptEntry[]; // intercept definitions for soft navigation
 };
 
@@ -173,8 +191,12 @@ export type EntryData =
       /** Original PrerenderHandlerDefinition (for build-time getParams access) */
       prerenderDef?: {
         getParams?: (ctx: any) => Promise<any[]> | any[];
-        options?: { passthrough?: boolean };
+        options?: { concurrency?: number };
       };
+      /** Set when route is wrapped with Passthrough() — has a separate live handler */
+      isPassthrough?: true;
+      /** Live handler for runtime fallback (only set on Passthrough routes) */
+      liveHandler?: Handler<any, any, any>;
       /** Set when handler is a Static definition (build-time only) */
       isStaticPrerender?: true;
       /** Static handler $$id for build-time store lookup */
@@ -196,18 +218,7 @@ export type EntryData =
     } & EntryPropCommon &
       EntryPropDatas &
       EntryPropSegments)
-  | ({
-      type: "parallel";
-      handler: Record<`@${string}`, Handler<any, any, any> | ReactNode>;
-      loading?: ReactNode | false;
-      transition?: TransitionConfig;
-      /** Set when any parallel slot is a Static definition */
-      isStaticPrerender?: true;
-      /** Per-slot static handler $$ids for build-time store lookup */
-      staticHandlerIds?: Record<string, string>;
-    } & EntryPropCommon &
-      EntryPropDatas &
-      EntryPropSegments)
+  | ParallelEntryData
   | ({
       type: "cache";
       /** Cache entries create cache boundaries and render like layouts (with Outlet) */
@@ -254,10 +265,37 @@ interface HelperContext {
   urlPrefix?: string;
   /** Name prefix from include() - applied to all named routes */
   namePrefix?: string;
+  /** True when this scope is at root level (no named include boundary above).
+   *  Routes at root scope allow dot-local reverse to fall back to bare names. */
+  rootScoped?: boolean;
   /** Run helper for cleaner middleware code */
   run?: <T>(fn: () => T | Promise<T>) => T | Promise<T>;
   /** Tracked includes for build-time manifest generation */
   trackedIncludes?: TrackedInclude[];
+  /** Cache profiles for DSL-time cache("profileName") resolution */
+  cacheProfiles?: Record<
+    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;
+  /**
+   * Include scope string applied to direct-descendant shortCodes.
+   *
+   * Each `include(...)` call allocates a sibling-positional token like `I0`,
+   * `I1` from its parent's include counter and stores the composed scope
+   * (`${parentScope}I${idx}`) in its lazyContext. When the include's handler
+   * evaluates lazily, the store's `includeScope` is set from that context so
+   * every direct-descendant shortCode is generated as
+   * `${parent.shortCode}${includeScope}${prefix}${index}` — preventing
+   * collisions with siblings declared outside the include.
+   *
+   * The scope is NOT propagated through `store.run(...)`, so layouts /
+   * parallels / caches inside the include absorb the scope into their own
+   * shortCodes and their children start fresh.
+   */
+  includeScope?: string;
 }
 // Use a global symbol key so the AsyncLocalStorage instance survives HMR
 // module re-evaluation. Without this, Vite's RSC module runner may create
@@ -360,6 +398,8 @@ export const getContext = (): {
       const mountPrefix =
         store.mountIndex !== undefined ? `M${store.mountIndex}` : "";
 
+      const includeScope = store.includeScope ?? "";
+
       if (!parent) {
         // Root entry: prefix with mount index and use mount-scoped counter
         const counterKey = mountPrefix
@@ -370,12 +410,16 @@ export const getContext = (): {
         store.counters[counterKey] = index + 1;
         return `${mountPrefix}${prefix}${index}`;
       } else {
-        // Child entry: use parent-scoped counter (parent already has M prefix)
-        const counterKey = `${parent.shortCode}_${type}`;
+        // Child entry: use parent-scoped counter with includeScope appended.
+        // When we're evaluating a lazy include's direct children, includeScope
+        // is a per-include token like "I0" / "I1I0" that partitions the
+        // parent's counter namespace so routes inside one include cannot
+        // collide with siblings declared outside it.
+        const counterKey = `${parent.shortCode}${includeScope}_${type}`;
         store.counters[counterKey] ??= 0;
         const index = store.counters[counterKey];
         store.counters[counterKey] = index + 1;
-        return `${parent.shortCode}${prefix}${index}`;
+        return `${parent.shortCode}${includeScope}${prefix}${index}`;
       }
     },
     runWithStore: <T>(
@@ -399,7 +443,10 @@ export const getContext = (): {
           searchSchemas: store.searchSchemas,
           urlPrefix: store.urlPrefix,
           namePrefix: store.namePrefix,
+          rootScoped: store.rootScoped,
           trackedIncludes: store.trackedIncludes,
+          cacheProfiles: store.cacheProfiles,
+          includeScope: store.includeScope,
         },
         callback,
       );
@@ -436,7 +483,9 @@ export const getContext = (): {
           searchSchemas,
           urlPrefix: store?.urlPrefix,
           namePrefix: store?.namePrefix,
+          rootScoped: store?.rootScoped,
           trackedIncludes: store?.trackedIncludes,
+          cacheProfiles: store?.cacheProfiles,
         },
         callback,
       );
@@ -469,17 +518,41 @@ export function runWithPrefixes<T>(
   } else {
     combinedUrlPrefix = urlPrefix;
   }
-  const combinedNamePrefix = namePrefix
-    ? store.namePrefix
-      ? `${store.namePrefix}.${namePrefix}`
-      : namePrefix
-    : store.namePrefix;
+  const combinedNamePrefix =
+    namePrefix !== undefined
+      ? namePrefix === ""
+        ? store.namePrefix
+        : store.namePrefix
+          ? `${store.namePrefix}.${namePrefix}`
+          : namePrefix
+      : store.namePrefix;
+
+  // Track root scope for dot-local reverse resolution.
+  //
+  // The flag answers: "can this route reach bare names at root scope?"
+  // It propagates through the include chain:
+  //
+  //   { name: "" }    — transparent: inherit parent, default true
+  //   { name: "foo" } — inherit parent if already set, else create boundary (false)
+  //   no name          — inherit parent unchanged
+  //
+  // This means { name: "" } + nested { name: "sub" } keeps rootScoped=true
+  // (the outer transparent include establishes root access, and the inner
+  // named include inherits it). But a direct { name: "sub" } at root gets
+  // rootScoped=false (no prior root-access grant, so it creates a boundary).
+  const combinedRootScoped =
+    namePrefix === ""
+      ? (store.rootScoped ?? true)
+      : namePrefix !== undefined
+        ? (store.rootScoped ?? false)
+        : store.rootScoped;
 
   return RSCRouterContext.run(
     {
       ...store,
       urlPrefix: combinedUrlPrefix,
       namePrefix: combinedNamePrefix,
+      rootScoped: combinedRootScoped,
     },
     callback,
   );
@@ -501,9 +574,92 @@ export function getNamePrefix(): string | undefined {
   return store?.namePrefix;
 }
 
+/**
+ * Get whether the current scope is at root level (no named include boundary above).
+ * Returns true at root or inside { name: "" } includes, false inside named includes.
+ */
+export function getRootScoped(): boolean {
+  const store = RSCRouterContext.getStore();
+  return store?.rootScoped ?? true;
+}
+
 // Export HelperContext type for use in other modules
 export type { HelperContext };
 
+/**
+ * Return an isolated copy of a lazy include's captured parent entry.
+ *
+ * DSL helpers (loader(), middleware(), etc.) mutate ctx.parent in place.
+ * Multiple include() scopes capture the *same* syntheticMapRoot as their
+ * parent, so without isolation one include's loaders/middleware leak into
+ * every other route that shares that root.
+ *
+ * The clone is shallow: only the mutable arrays are copied so each
+ * include pushes to its own list. The rest of the entry (id, shortCode,
+ * parent pointer, handler) stays shared, which is correct and cheap.
+ */
+export function getIsolatedLazyParent(
+  captured: EntryData | null | undefined,
+): EntryData | null {
+  if (!captured) return null;
+  return {
+    ...captured,
+    loader: [...captured.loader],
+    middleware: [...captured.middleware],
+    revalidate: [...captured.revalidate],
+    errorBoundary: [...captured.errorBoundary],
+    notFoundBoundary: [...captured.notFoundBoundary],
+    layout: [...captured.layout],
+    parallel: { ...captured.parallel },
+    intercept: [...captured.intercept],
+  };
+}
+
+export function getParallelEntries(
+  parallels: ParallelEntries | EntryData[] | undefined,
+): ParallelEntryData[] {
+  if (!parallels) return [];
+  if (Array.isArray(parallels)) {
+    return parallels.filter(
+      (entry): entry is ParallelEntryData => entry.type === "parallel",
+    );
+  }
+  return Object.values(parallels).filter(
+    (entry): entry is ParallelEntryData => !!entry,
+  );
+}
+
+export function getParallelSlotEntries(
+  parallels: ParallelEntries | EntryData[] | undefined,
+): Array<{ slot: `@${string}`; entry: ParallelEntryData }> {
+  if (!parallels) return [];
+
+  if (Array.isArray(parallels)) {
+    return getParallelEntries(parallels).flatMap((entry) =>
+      (Object.keys(entry.handler) as `@${string}`[]).map((slot) => ({
+        slot,
+        entry,
+      })),
+    );
+  }
+
+  return Object.entries(parallels)
+    .filter(([, entry]) => !!entry)
+    .map(([slot, entry]) => ({
+      slot: slot as `@${string}`,
+      entry: entry!,
+    }));
+}
+
+export function getParallelSlotCount(
+  parallels: ParallelEntries | EntryData[] | undefined,
+): number {
+  if (!parallels) return 0;
+  return Array.isArray(parallels)
+    ? parallels.filter((entry) => entry?.type === "parallel").length
+    : Object.keys(parallels).length;
+}
+
 // ============================================================================
 //  Performance Metrics Helpers
 // ============================================================================
@@ -519,7 +675,7 @@ export type { HelperContext };
  * done(); // Records duration
  * ```
  */
-export function track(label: string): () => void {
+export function track(label: string, depth?: number): () => void {
   const store = RSCRouterContext.getStore();
 
   // No-op if context unavailable or metrics not enabled
@@ -532,6 +688,53 @@ export function track(label: string): () => void {
   return () => {
     const duration =
       performance.now() - store.metrics!.requestStart - startTime;
-    store.metrics!.metrics.push({ label, duration, startTime });
+    store.metrics!.metrics.push({
+      label,
+      duration,
+      startTime,
+      ...(depth != null ? { depth } : {}),
+    });
   };
 }
+
+/**
+ * Separate ALS for tracking loader execution scope.
+ * Uses a dedicated ALS (not RSCRouterContext) to avoid issues with
+ * nested RSCRouterContext.run() calls in Vite's module runner.
+ */
+const LOADER_SCOPE_KEY = Symbol.for("rangojs-router:loader-scope");
+const loaderScopeALS: AsyncLocalStorage<{ active: true }> = ((
+  globalThis as any
+)[LOADER_SCOPE_KEY] ??= new AsyncLocalStorage<{ active: true }>());
+
+/**
+ * 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 {
+  if (RSCRouterContext.getStore()?.insideCacheScope !== true) return false;
+  // Loaders are always fresh — even inside a cache() boundary, the loader
+  // function re-executes on every request. Skip the guard when running
+  // inside a loader.
+  if (loaderScopeALS.getStore()?.active) return false;
+  return true;
+}
+
+/**
+ * Check if the current execution is inside a DSL loader scope
+ * (wrapped by runInsideLoaderScope). Used by rendered() barrier
+ * to distinguish DSL loaders from handler-invoked loaders.
+ */
+export function isInsideLoaderScope(): boolean {
+  return loaderScopeALS.getStore()?.active === true;
+}
+
+/**
+ * Run `fn` inside a loader scope. While active, cache-scope guards
+ * are bypassed because loaders are always fresh (never cached) and
+ * their side effects (setCookie, header, etc.) are safe.
+ */
+export function runInsideLoaderScope<T>(fn: () => T): T {
+  return loaderScopeALS.run({ active: true }, fn);
+}

package/src/server/cookie-store.ts

@@ -0,0 +1,190 @@
+/**
+ * Cookie Store — Next.js-style cookie facade backed by the response-derived model.
+ *
+ * `cookies()` returns a CookieStore scoped to the current request.
+ * Reads merge the original Cookie header with Set-Cookie mutations
+ * already queued on the response stub (last-write-wins).
+ * Writes append Set-Cookie to the response stub.
+ */
+
+import type { CookieOptions } from "../router/middleware-types.js";
+import { getRequestContext } from "./request-context.js";
+import { INSIDE_CACHE_EXEC } from "../cache/taint.js";
+
+/**
+ * A single cookie entry returned by get() and getAll().
+ */
+export interface Cookie {
+  name: string;
+  value: string;
+}
+
+/**
+ * Request-scoped cookie store.
+ *
+ * Reads see the effective merged view (original request + same-request mutations).
+ * Writes append Set-Cookie headers to the shared response stub.
+ */
+export interface CookieStore {
+  /** Get a single cookie by name. Returns undefined if not set or deleted. */
+  get(name: string): Cookie | undefined;
+
+  /** Get all effective cookies, or all cookies with a given name. */
+  getAll(name?: string): Cookie[];
+
+  /** Check whether a cookie exists in the effective view. */
+  has(name: string): boolean;
+
+  /** Set a cookie (appends Set-Cookie to the response stub). */
+  set(name: string, value: string, options?: CookieOptions): void;
+
+  /** Delete a cookie (appends Set-Cookie with maxAge=0 to the response stub). */
+  delete(name: string, options?: Pick<CookieOptions, "domain" | "path">): void;
+}
+
+/**
+ * Get the request-scoped cookie store.
+ *
+ * Must be called inside a request context (middleware, handler, loader, action).
+ * Throws if called outside request scope.
+ *
+ * @example
+ * ```typescript
+ * import { cookies } from "@rangojs/router";
+ *
+ * // In a handler, loader, or action:
+ * const session = cookies().get("session")?.value;
+ * cookies().set("session", "new-token", { httpOnly: true });
+ * cookies().delete("session");
+ * ```
+ */
+export function cookies(): CookieStore {
+  const ctx = getRequestContext();
+  assertNotInsideCacheContext(ctx, "cookies");
+  return createCookieStore(ctx);
+}
+
+/**
+ * Read-only view of HTTP headers.
+ * Exposes only the read methods of the Headers API.
+ */
+export interface ReadonlyHeaders {
+  get(name: string): string | null;
+  has(name: string): boolean;
+  entries(): HeadersIterator<[string, string]>;
+  keys(): HeadersIterator<string>;
+  values(): HeadersIterator<string>;
+  forEach(
+    callback: (value: string, name: string, parent: ReadonlyHeaders) => void,
+  ): void;
+  [Symbol.iterator](): HeadersIterator<[string, string]>;
+}
+
+// Minimal iterator interface (avoids pulling IterableIterator from lib.dom)
+type HeadersIterator<T> = IterableIterator<T>;
+
+/**
+ * Throw if called inside a "use cache" function.
+ * Reading request-scoped data (cookies, headers) inside a cached function
+ * produces results that vary per request but the cache key does not include
+ * those values, leading to one user's data being served to another.
+ */
+function assertNotInsideCacheContext(ctx: unknown, fnName: string): void {
+  if (
+    ctx !== null &&
+    ctx !== undefined &&
+    typeof ctx === "object" &&
+    (INSIDE_CACHE_EXEC as symbol) in (ctx as Record<symbol, unknown>)
+  ) {
+    throw new Error(
+      `${fnName}() cannot be called inside a "use cache" function. ` +
+        `Request-scoped data (cookies, headers) varies per request but is not ` +
+        `reflected in the cache key, so cached results would be served to the ` +
+        `wrong users. Extract the value before the cached function and pass it ` +
+        `as an argument:\n\n` +
+        `  const locale = cookies().get("locale")?.value ?? "en";\n` +
+        `  const data = await getCachedData(locale); // locale is now in the cache key`,
+    );
+  }
+}
+
+const HEADERS_MUTATION_METHODS = new Set(["set", "append", "delete"]);
+
+/**
+ * Get the original request headers (read-only).
+ *
+ * Must be called inside a request context.
+ * Returns a read-only view of the incoming request's headers.
+ * Mutation methods (set, append, delete) throw at runtime.
+ *
+ * @example
+ * ```typescript
+ * import { headers } from "@rangojs/router";
+ *
+ * const auth = headers().get("authorization");
+ * const contentType = headers().get("content-type");
+ * ```
+ */
+export function headers(): ReadonlyHeaders {
+  const ctx = getRequestContext();
+  assertNotInsideCacheContext(ctx, "headers");
+  return new Proxy(ctx.request.headers, {
+    get(target, prop, receiver) {
+      if (typeof prop === "string" && HEADERS_MUTATION_METHODS.has(prop)) {
+        return () => {
+          throw new Error(
+            `headers().${prop}() is not allowed. headers() returns a read-only view of request headers. ` +
+              `Use ctx.header() to set response headers.`,
+          );
+        };
+      }
+      const value = Reflect.get(target, prop, receiver);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  }) as unknown as ReadonlyHeaders;
+}
+
+/**
+ * Create a CookieStore backed by a RequestContext.
+ * @internal Shared between cookies() shorthand and context methods.
+ */
+function createCookieStore(ctx: {
+  cookie(name: string): string | undefined;
+  cookies(): Record<string, string>;
+  setCookie(name: string, value: string, options?: CookieOptions): void;
+  deleteCookie(
+    name: string,
+    options?: Pick<CookieOptions, "domain" | "path">,
+  ): void;
+}): CookieStore {
+  return {
+    get(name: string): Cookie | undefined {
+      const value = ctx.cookie(name);
+      return value !== undefined ? { name, value } : undefined;
+    },
+
+    getAll(name?: string): Cookie[] {
+      const all = ctx.cookies();
+      if (name !== undefined) {
+        const value = all[name];
+        return value !== undefined ? [{ name, value }] : [];
+      }
+      return Object.entries(all).map(([n, v]) => ({ name: n, value: v }));
+    },
+
+    has(name: string): boolean {
+      return ctx.cookie(name) !== undefined;
+    },
+
+    set(name: string, value: string, options?: CookieOptions): void {
+      ctx.setCookie(name, value, options);
+    },
+
+    delete(
+      name: string,
+      options?: Pick<CookieOptions, "domain" | "path">,
+    ): void {
+      ctx.deleteCookie(name, options);
+    },
+  };
+}

package/src/server/fetchable-loader-store.ts

@@ -12,21 +12,26 @@
 import type { LoaderFn } from "../types.js";
 import type { MiddlewareFn } from "../router/middleware.js";
 
-const fetchableLoaderRegistry = new Map<
-  string,
-  { fn: LoaderFn<any, any, any>; middleware: MiddlewareFn[] }
->();
+export interface LoaderRegistryEntry {
+  fn: LoaderFn<any, any, any>;
+  middleware: MiddlewareFn[];
+  /** Whether this loader is fetchable via the _rsc_loader endpoint. */
+  fetchable: boolean;
+}
+
+const fetchableLoaderRegistry = new Map<string, LoaderRegistryEntry>();
 
 export function registerFetchableLoader(
   id: string,
   fn: LoaderFn<any, any, any>,
   middleware: MiddlewareFn[],
+  fetchable: boolean,
 ): void {
-  fetchableLoaderRegistry.set(id, { fn, middleware });
+  fetchableLoaderRegistry.set(id, { fn, middleware, fetchable });
 }
 
 export function getFetchableLoader(
   id: string,
-): { fn: LoaderFn<any, any, any>; middleware: MiddlewareFn[] } | undefined {
+): LoaderRegistryEntry | undefined {
   return fetchableLoaderRegistry.get(id);
 }