@rangojs/router 0.0.0-experimental.79 → 0.0.0-experimental.7d061845

package/src/server/context.ts

@@ -10,7 +10,7 @@ import type {
   ShouldRevalidateFn,
   TransitionConfig,
 } from "../types";
-import { invariant } from "../errors";
+import { invariant, DslContextError } from "../errors";
 import type { DefaultRouteName } from "../types/global-namespace.js";
 
 // ============================================================================
@@ -40,7 +40,7 @@ export interface MetricsStore {
   metrics: PerformanceMetric[];
 }
 // ============================================================================
-//  RSC Router Context
+//  Rango Context
 // ============================================================================
 
 /**
@@ -71,6 +71,10 @@ export type EntryPropCommon = {
 };
 
 /**
+ * Attachments resolved by walking the parent chain, not owned by the entry:
+ * middleware composes downward; revalidate and the error/notFound boundaries are
+ * resolved by nearest-ancestor lookup. Inherited, not a single execution chain.
+ *
  * @internal This type is an implementation detail and may change without notice.
  */
 export type EntryPropDatas = {
@@ -80,6 +84,16 @@ export type EntryPropDatas = {
   notFoundBoundary: (ReactNode | NotFoundBoundaryHandler)[];
 };
 
+/**
+ * Render-time presentation fields shared by every entry variant.
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type EntryPropRender = {
+  loading?: ReactNode | false;
+  transition?: TransitionConfig;
+};
+
 /**
  * Loader entry stored in EntryData
  * Contains the loader definition and its revalidation rules
@@ -158,11 +172,9 @@ export type InterceptEntry = {
 };
 
 export interface ParallelEntryData
-  extends EntryPropCommon, EntryPropDatas, EntryPropSegments {
+  extends EntryPropCommon, EntryPropDatas, EntryPropSegments, EntryPropRender {
   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 */
@@ -171,6 +183,13 @@ export interface ParallelEntryData
 
 export type ParallelEntries = Partial<Record<`@${string}`, ParallelEntryData>>;
 
+/**
+ * This entry's own structural children plus its owned loaders. `loader` lives
+ * here (not in EntryPropDatas) because loaders are owned by the entry, not
+ * inherited from ancestors.
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
 export type EntryPropSegments = {
   loader: LoaderEntry[];
   layout: EntryData[];
@@ -182,8 +201,6 @@ export type EntryData =
   | ({
       type: "route";
       handler: Handler<any, any, any>;
-      loading?: ReactNode | false;
-      transition?: TransitionConfig;
       /** URL pattern for this route (used by path() in urls()) */
       pattern?: string;
       /** Set when handler is a Prerender definition */
@@ -205,29 +222,28 @@ export type EntryData =
       responseType?: string;
     } & EntryPropCommon &
       EntryPropDatas &
-      EntryPropSegments)
+      EntryPropSegments &
+      EntryPropRender)
   | ({
       type: "layout";
       handler: ReactNode | Handler<any, any, any>;
-      loading?: ReactNode | false;
-      transition?: TransitionConfig;
       /** Set when handler is a Static definition (build-time only) */
       isStaticPrerender?: true;
       /** Static handler $$id for build-time store lookup */
       staticHandlerId?: string;
     } & EntryPropCommon &
       EntryPropDatas &
-      EntryPropSegments)
+      EntryPropSegments &
+      EntryPropRender)
   | ParallelEntryData
   | ({
       type: "cache";
       /** Cache entries create cache boundaries and render like layouts (with Outlet) */
       handler: ReactNode | Handler<any, any, any>;
-      loading?: ReactNode | false;
-      transition?: TransitionConfig;
     } & EntryPropCommon &
       EntryPropDatas &
-      EntryPropSegments);
+      EntryPropSegments &
+      EntryPropRender);
 
 /**
  * Tracked include info for build-time manifest generation
@@ -303,10 +319,28 @@ interface HelperContext {
 // hold references to the old instance — causing getStore() to return
 // undefined even inside a run() callback.
 const RSC_CONTEXT_KEY = Symbol.for("rangojs-router:rsc-context");
-export const RSCRouterContext: AsyncLocalStorage<HelperContext> = ((
+export const RangoContext: AsyncLocalStorage<HelperContext> = ((
   globalThis as any
 )[RSC_CONTEXT_KEY] ??= new AsyncLocalStorage<HelperContext>());
 
+/** shortCode prefix letter per entry type (e.g. "L0", "R2", "M1C0"). */
+const SHORT_CODE_PREFIX: Record<
+  "layout" | "parallel" | "route" | "loader" | "cache",
+  string
+> = {
+  layout: "L",
+  parallel: "P",
+  route: "R",
+  loader: "D",
+  cache: "C",
+};
+
+/** Post-increment a named per-store counter, returning the prior value. */
+function bumpCounter(store: HelperContext, key: string): number {
+  store.counters[key] ??= 0;
+  return store.counters[key]++;
+}
+
 export const getContext = (): {
   context: AsyncLocalStorage<HelperContext>;
   getStore: () => HelperContext;
@@ -330,12 +364,12 @@ export const getContext = (): {
     callback: (...args: any[]) => T,
   ) => T;
 } => {
-  const context = RSCRouterContext;
+  const context = RangoContext;
 
   return {
     context,
     getOrCreateStore: (forRoute?: string): HelperContext => {
-      let store = RSCRouterContext.getStore();
+      let store = RangoContext.getStore();
       if (!store) {
         store = {
           manifest: new Map<string, EntryData>(),
@@ -355,7 +389,7 @@ export const getContext = (): {
       const store = context.getStore();
       if (!store) {
         throw new Error(
-          "RSC Router context store is not available. Make sure to run within RSC Router context.",
+          "Rango context store is not available. Make sure to run within Rango context.",
         );
       }
       return store;
@@ -372,29 +406,17 @@ export const getContext = (): {
       type: (string & {}) | "layout" | "parallel" | "middleware" | "revalidate",
     ) => {
       const store = context.getStore();
-      invariant(store, "No context RSCRouterContext available");
-      store.counters[type] ??= 0;
-      const index = store.counters[type];
-      store.counters[type] = index + 1;
-      return `$${type}.${index}`;
+      invariant(store, "No context RangoContext available");
+      return `$${type}.${bumpCounter(store, type)}`;
     },
     getShortCode: (
       type: "layout" | "parallel" | "route" | "loader" | "cache",
     ) => {
       const store = context.getStore();
-      invariant(store, "No context RSCRouterContext available");
+      invariant(store, "No context RangoContext available");
 
       const parent = store.parent;
-      const prefix =
-        type === "layout"
-          ? "L"
-          : type === "parallel"
-            ? "P"
-            : type === "loader"
-              ? "D"
-              : type === "cache"
-                ? "C"
-                : "R";
+      const prefix = SHORT_CODE_PREFIX[type];
       const mountPrefix =
         store.mountIndex !== undefined ? `M${store.mountIndex}` : "";
 
@@ -405,10 +427,7 @@ export const getContext = (): {
         const counterKey = mountPrefix
           ? `${mountPrefix}_root_${type}`
           : `root_${type}`;
-        store.counters[counterKey] ??= 0;
-        const index = store.counters[counterKey];
-        store.counters[counterKey] = index + 1;
-        return `${mountPrefix}${prefix}${index}`;
+        return `${mountPrefix}${prefix}${bumpCounter(store, counterKey)}`;
       } else {
         // Child entry: use parent-scoped counter with includeScope appended.
         // When we're evaluating a lazy include's direct children, includeScope
@@ -416,10 +435,7 @@ export const getContext = (): {
         // 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}${includeScope}${prefix}${index}`;
+        return `${parent.shortCode}${includeScope}${prefix}${bumpCounter(store, counterKey)}`;
       }
     },
     runWithStore: <T>(
@@ -493,6 +509,31 @@ export const getContext = (): {
   };
 };
 
+/**
+ * Acquire the active DSL build context, throwing `message` if a helper was
+ * called outside a urls()/map() builder. Returns the store API and the live
+ * HelperContext so callers avoid a second getContext() lookup.
+ */
+export function requireDslContext(message: string): {
+  store: ReturnType<typeof getContext>;
+  ctx: HelperContext;
+} {
+  const store = getContext();
+  const ctx = store.context.getStore();
+  if (!ctx) {
+    // The only reason the store is absent here is that a route-definition helper
+    // ran with no active RangoContext — i.e. outside a urls()/map() builder.
+    // Record that as the cause so the throw is self-explanatory, not a bare
+    // "must be called inside urls()" with no indication of the mechanism.
+    throw new DslContextError(message, {
+      cause:
+        "RangoContext store is undefined: a route-definition helper was called " +
+        "outside an active urls()/map() builder.",
+    });
+  }
+  return { store, ctx };
+}
+
 /**
  * Run a callback with specific URL and name prefixes
  * Used by include() to apply prefixes to nested patterns
@@ -502,7 +543,7 @@ export function runWithPrefixes<T>(
   namePrefix: string | undefined,
   callback: () => T,
 ): T {
-  const store = RSCRouterContext.getStore();
+  const store = RangoContext.getStore();
   if (!store) {
     throw new Error("runWithPrefixes must be called within router context");
   }
@@ -547,7 +588,7 @@ export function runWithPrefixes<T>(
         ? (store.rootScoped ?? false)
         : store.rootScoped;
 
-  return RSCRouterContext.run(
+  return RangoContext.run(
     {
       ...store,
       urlPrefix: combinedUrlPrefix,
@@ -562,7 +603,7 @@ export function runWithPrefixes<T>(
  * Get current URL prefix from context
  */
 export function getUrlPrefix(): string {
-  const store = RSCRouterContext.getStore();
+  const store = RangoContext.getStore();
   return store?.urlPrefix || "";
 }
 
@@ -570,7 +611,7 @@ export function getUrlPrefix(): string {
  * Get current name prefix from context
  */
 export function getNamePrefix(): string | undefined {
-  const store = RSCRouterContext.getStore();
+  const store = RangoContext.getStore();
   return store?.namePrefix;
 }
 
@@ -579,7 +620,7 @@ export function getNamePrefix(): string | undefined {
  * Returns true at root or inside { name: "" } includes, false inside named includes.
  */
 export function getRootScoped(): boolean {
-  const store = RSCRouterContext.getStore();
+  const store = RangoContext.getStore();
   return store?.rootScoped ?? true;
 }
 
@@ -676,7 +717,7 @@ export function getParallelSlotCount(
  * ```
  */
 export function track(label: string, depth?: number): () => void {
-  const store = RSCRouterContext.getStore();
+  const store = RangoContext.getStore();
 
   // No-op if context unavailable or metrics not enabled
   if (!store?.metrics?.enabled) {
@@ -699,25 +740,40 @@ export function track(label: string, depth?: number): () => void {
 
 /**
  * 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.
+ * Uses a dedicated ALS (not RangoContext) to avoid issues with
+ * nested RangoContext.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 }>());
 
+// Purity-only scope: marks that a loader FUNCTION BODY is executing, regardless
+// of how the loader was invoked (DSL via runInsideLoaderScope, or handler-
+// invoked via ctx.use). Consulted ONLY by isInsideCacheScope() to exempt
+// request-scoped reads. It deliberately does NOT affect isInsideLoaderScope(),
+// so rendered()/barrier/deadlock gating (which must distinguish DSL from
+// handler-invoked loaders) is unchanged.
+const LOADER_BODY_SCOPE_KEY = Symbol.for("rangojs-router:loader-body-scope");
+const loaderBodyScopeALS: AsyncLocalStorage<{ active: true }> = ((
+  globalThis as any
+)[LOADER_BODY_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;
+  if (RangoContext.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;
+  // Also exempt handler-invoked loaders: their bodies run in a loader-body
+  // scope (not the DSL loader scope above), so request-scoped reads inside any
+  // loader — however invoked — are safe (loaders always re-run fresh).
+  if (loaderBodyScopeALS.getStore()?.active) return false;
   return true;
 }
 
@@ -738,3 +794,14 @@ export function isInsideLoaderScope(): boolean {
 export function runInsideLoaderScope<T>(fn: () => T): T {
   return loaderScopeALS.run({ active: true }, fn);
 }
+
+/**
+ * Run `fn` inside a loader BODY scope. Marks loader-function execution for the
+ * cache-purity guard only (isInsideCacheScope), WITHOUT affecting
+ * isInsideLoaderScope()/rendered() gating. Applied to every loader body (DSL
+ * and handler-invoked via ctx.use) so request-scoped reads inside a loader
+ * never trip the cache-scope guards — loaders always run fresh.
+ */
+export function runInsideLoaderBodyScope<T>(fn: () => T): T {
+  return loaderBodyScopeALS.run({ active: true }, fn);
+}

package/src/server/cookie-store.ts

@@ -9,6 +9,7 @@
 
 import type { CookieOptions } from "../router/middleware-types.js";
 import { getRequestContext } from "./request-context.js";
+import { isInsideCacheScope } from "./context.js";
 import { INSIDE_CACHE_EXEC } from "../cache/taint.js";
 
 /**
@@ -84,10 +85,23 @@ export interface ReadonlyHeaders {
 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.
+ * Throw if called inside a cache boundary — either a "use cache" function
+ * (`INSIDE_CACHE_EXEC` stamped on ctx by the cache runtime) or a `cache()`
+ * DSL boundary (`isInsideCacheScope()` — the render-store flag set while
+ * resolving a `type: "cache"` route entry).
+ *
+ * Reading request-scoped data (cookies, headers) inside a cached scope
+ * produces per-request values that are NOT reflected in the cache key, so
+ * they would be frozen into the shared cache entry and served to the wrong
+ * users. This is the same hazard for both scopes: a `cache()` boundary caches
+ * everything except loaders (it is the document-level "PPR shell"), so a read
+ * here is baked into the shell exactly like a `"use cache"` return value is
+ * baked into its cache entry.
+ *
+ * `isInsideCacheScope()` returns false inside loaders (loaders always run
+ * fresh on every request, even on a cache hit), so reading cookies()/headers()
+ * from a loader is allowed — loaders are the dynamic "holes" of a cached
+ * document.
  */
 function assertNotInsideCacheContext(ctx: unknown, fnName: string): void {
   if (
@@ -106,6 +120,16 @@ function assertNotInsideCacheContext(ctx: unknown, fnName: string): void {
         `  const data = await getCachedData(locale); // locale is now in the cache key`,
     );
   }
+  if (isInsideCacheScope()) {
+    throw new Error(
+      `${fnName}() cannot be called inside a cache() boundary. ` +
+        `A cache() scope caches everything except loaders, so request-scoped ` +
+        `data (cookies, headers) read here would be frozen into the shared ` +
+        `cached shell and served to other users. Read it inside a loader ` +
+        `instead — loaders always run fresh on every request, even on a cache hit:\n\n` +
+        `  loader("user", () => getUser(cookies().get("session")?.value));`,
+    );
+  }
 }
 
 const HEADERS_MUTATION_METHODS = new Set(["set", "append", "delete"]);

package/src/server/request-context.ts

@@ -37,6 +37,8 @@ import { track, type MetricsStore } from "./context.js";
 import { getFetchableLoader } from "./fetchable-loader-store.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
+import type { ExecutionContext, RequestScope } from "../types/request-scope.js";
+import { fireAndForgetWaitUntil } from "../types/request-scope.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";
@@ -58,22 +60,7 @@ import { isAutoGeneratedRouteName } from "../route-name.js";
 export interface RequestContext<
   TEnv = DefaultEnv,
   TParams = Record<string, string>,
-> {
-  /** Platform bindings (Cloudflare env, etc.) */
-  env: TEnv;
-  /** Original HTTP request */
-  request: Request;
-  /** Parsed URL (with internal `_rsc*` params stripped) */
-  url: URL;
-  /**
-   * The original request URL with all parameters intact, including
-   * internal `_rsc*` transport params.
-   */
-  originalUrl: URL;
-  /** URL pathname */
-  pathname: string;
-  /** URL search params (with internal `_rsc*` params stripped, same as `url.searchParams`) */
-  searchParams: URLSearchParams;
+> extends RequestScope<TEnv> {
   /** @internal Shared variable backing store for ctx.get()/ctx.set(). */
   _variables: Record<string, any>;
   /** Get a variable set by middleware */
@@ -159,20 +146,6 @@ export interface RequestContext<
     import("../cache/profile-registry.js").CacheProfile
   >;
 
-  /**
-   * Schedule work to run after the response is sent.
-   * On Cloudflare Workers, uses ctx.waitUntil().
-   * On Node.js, runs as fire-and-forget.
-   *
-   * @example
-   * ```typescript
-   * ctx.waitUntil(async () => {
-   *   await cacheStore.set(key, data, ttl);
-   * });
-   * ```
-   */
-  waitUntil(fn: () => Promise<void>): void;
-
   /**
    * Register a callback to run when the response is created.
    * Callbacks are sync and receive the response. They can:
@@ -349,6 +322,15 @@ export interface RequestContext<
    * to avoid a second resolveRoute call. Cleared on HMR invalidation.
    */
   _classifiedRoute?: import("../router/route-snapshot.js").RouteSnapshot;
+
+  /**
+   * @internal Coarse route-level cache signal for the X-Rango-Cache debug
+   * header. Populated by match/matchPartial only when the debug cache signal
+   * gate is enabled (debugCacheSignal option or RANGO_TEST_SIGNALS=1). Read by
+   * the response-finalization path (createResponseWithMergedHeaders). Undefined
+   * when the gate is off, so no header is emitted.
+   */
+  _cacheSignal?: import("../router/telemetry.js").CacheSegmentSignal[];
 }
 
 /**
@@ -389,6 +371,7 @@ export type PublicRequestContext<
   | "_setStatus"
   | "_variables"
   | "_classifiedRoute"
+  | "_cacheSignal"
   | "res"
 >;
 
@@ -498,13 +481,7 @@ export function requireRequestContext<
   return getRequestContext<TEnv>();
 }
 
-/**
- * Cloudflare Workers ExecutionContext (subset we need)
- */
-export interface ExecutionContext {
-  waitUntil(promise: Promise<any>): void;
-  passThroughOnException(): void;
-}
+export type { ExecutionContext };
 
 /**
  * Options for creating a request context
@@ -768,16 +745,14 @@ export function createRequestContext<TEnv>(
 
     waitUntil(fn: () => Promise<void>): void {
       if (executionContext?.waitUntil) {
-        // Cloudflare Workers: use native waitUntil
         executionContext.waitUntil(fn());
       } else {
-        // Node.js / dev: fire-and-forget with error logging
-        fn().catch((err) =>
-          console.error("[waitUntil] Background task failed:", err),
-        );
+        fireAndForgetWaitUntil(fn);
       }
     },
 
+    executionContext,
+
     _onResponseCallbacks: [],
 
     onResponse(callback: (response: Response) => Response): void {
@@ -1043,7 +1018,10 @@ export function createUseFunction<TEnv>(
       search: (ctx as any).search ?? {},
       pathname: ctx.pathname,
       url: ctx.url,
+      originalUrl: ctx.originalUrl,
       env: ctx.env as any,
+      waitUntil: ctx.waitUntil.bind(ctx),
+      executionContext: ctx.executionContext,
       get: ctx.get as any,
       use: (<TDep, TDepParams = any>(
         dep: LoaderDefinition<TDep, TDepParams>,

package/src/ssr/index.tsx

@@ -162,9 +162,13 @@ function createSsrEventController(opts: {
 }): EventController {
   const location = new URL(opts.pathname, "http://localhost");
   let params = opts.params ?? {};
+  const rawMatched = opts.matched ?? [];
   const handleState = {
     data: opts.handleData ?? {},
-    segmentOrder: filterSegmentOrder(opts.matched ?? []),
+    segmentOrder: filterSegmentOrder(rawMatched),
+    routeSegmentIds: rawMatched.filter(
+      (id) => !id.includes(".@") && !/D\d+\./.test(id),
+    ),
   };
   const state: DerivedNavigationState = {
     state: "idle",

package/src/static-handler.ts

@@ -96,7 +96,7 @@ export function Static<TParams extends Record<string, any>>(
 
   if (!id) {
     throw new Error(
-      "[rsc-router] Static: missing $$id. " +
+      "[rango] Static: missing $$id. " +
         "Ensure the exposeInternalIds Vite plugin is configured.",
     );
   }