@rangojs/router 0.15.1 → 0.17.0

package/src/router/match-middleware/cache-store.ts

@@ -103,7 +103,7 @@
 import type { ResolvedSegment } from "../../types.js";
 import {
   getRequestContext,
-  runWithRequestContext,
+  type RequestContext,
 } from "../../server/request-context.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { createShellImplicitDocScope } from "../../cache/cache-scope.js";
@@ -111,6 +111,7 @@ import { getRouterContext } from "../router-context.js";
 import { debugLog, debugWarn, getOrCreateRequestId } from "../logging.js";
 import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
+import { rerenderAndCacheRoute } from "./background-revalidation.js";
 
 /**
  * Creates cache store middleware
@@ -159,13 +160,9 @@ export function withCacheStore<TEnv>(
       return;
     }
 
-    const {
-      createHandlerContext,
-      setupLoaderAccess,
-      resolveAllSegments,
-      resolveInterceptEntry,
-      createHandleStore,
-    } = getRouterContext<TEnv>();
+    // Read synchronously in the pipeline: the proactive write runs in
+    // waitUntil, where the router-context ALS may be gone.
+    const routerCtx = getRouterContext<TEnv>();
 
     // On a fresh intercept miss the intercept slot segments flow through
     // `source` into allSegments AND are also recorded on state.interceptSegments.
@@ -178,18 +175,21 @@ export function withCacheStore<TEnv>(
       ...state.interceptSegments.filter((s) => !seenSegmentIds.has(s.id)),
     ];
 
+    const cacheScope = ctx.cacheScope;
+
+    // Only the segments the entry stores count: a null layout above the
+    // boundary (the client kept it) is never written, so it needs no re-render.
     const hasNullComponents = allSegmentsToCache.some(
       (s) =>
         s.component === null &&
         s.type !== "loader" &&
-        ctx.clientSegmentSet.has(s.id),
+        ctx.clientSegmentSet.has(s.id) &&
+        cacheScope.covers(s.id, s.namespace),
     );
 
     const requestCtx = getRequestContext();
     if (!requestCtx) return;
 
-    const cacheScope = ctx.cacheScope;
-
     // Record the route's segment-DSL cache tags into the request tag union NOW,
     // synchronously in the pipeline. The actual store write (cacheRoute) runs in
     // requestCtx.waitUntil() below — and the proactive path re-resolves the whole
@@ -216,91 +216,21 @@ export function withCacheStore<TEnv>(
 
       if (hasNullComponents) {
         requestCtx.waitUntil(async () => {
-          const savedMetrics = ctx.Store.metrics;
-          ctx.Store.metrics = undefined;
-
           const start = performance.now();
           debugLog("cacheStore", "proactive caching started", {
             pathname: ctx.pathname,
           });
-          const originalHandleStore = requestCtx._handleStore;
-          requestCtx._handleStore = createHandleStore();
           try {
-            const proactiveHandlerContext = createHandlerContext(
-              ctx.matched.params,
-              ctx.request,
-              ctx.url.searchParams,
-              ctx.pathname,
-              ctx.url,
-              ctx.env,
-              ctx.routeMap,
-              ctx.matched.routeKey,
-              ctx.matched.responseType,
-              ctx.matched.pt === true,
-            );
-            const proactiveLoaderPromises = new Map<string, Promise<any>>();
-
-            setupLoaderAccess(proactiveHandlerContext, proactiveLoaderPromises);
-
-            const Store = ctx.Store;
-            // Re-establish the request-context ALS around the re-render. Store
-            // is a different ALS (DSL build context); on workerd a waitUntil
-            // task runs detached from the request's I/O context, so a handler/
-            // component that reads the ambient getRequestContext() during this
-            // background re-render would otherwise throw "called outside of a
-            // request context".
-            const freshSegments = await runWithRequestContext(requestCtx, () =>
-              Store.run(() =>
-                resolveAllSegments(
-                  ctx.entries,
-                  ctx.routeKey,
-                  ctx.matched.params,
-                  proactiveHandlerContext,
-                  proactiveLoaderPromises,
-                  { skipLoaders: true },
-                ),
-              ),
-            );
-
-            let freshInterceptSegments: ResolvedSegment[] = [];
-            if (ctx.interceptResult) {
-              freshInterceptSegments = await runWithRequestContext(
-                requestCtx,
-                () =>
-                  Store.run(() =>
-                    resolveInterceptEntry(
-                      ctx.interceptResult!.intercept,
-                      ctx.interceptResult!.entry,
-                      ctx.matched.params,
-                      proactiveHandlerContext,
-                      true, // belongsToRoute
-                      // No revalidationContext = render fresh
-                      undefined,
-                      // Skip intercept middleware: the foreground already ran it
-                      // before the response was sent. Re-running here (post-
-                      // response, background) would fire side effects twice and a
-                      // short-circuit Response would silently abort this write.
-                      { skipMiddleware: true },
-                    ),
-                  ),
-              );
-            }
-
-            const completeSegments = [
-              ...freshSegments,
-              ...freshInterceptSegments,
-            ];
-            requestCtx._handleStore.seal();
-            await cacheScope.cacheRoute(
-              ctx.pathname,
-              ctx.matched.params,
-              completeSegments,
-              ctx.isIntercept,
+            const count = await rerenderAndCacheRoute<TEnv>(
+              ctx,
+              requestCtx as RequestContext<TEnv>,
+              cacheScope,
+              routerCtx,
             );
             if (INTERNAL_RANGO_DEBUG) {
               const dur = performance.now() - start;
               console.log(
-                `[RSC Background][req:${reqId}] Proactive cache ${ctx.pathname} (${dur.toFixed(2)}ms) segments=${completeSegments.length}`,
+                `[RSC Background][req:${reqId}] Proactive cache ${ctx.pathname} (${dur.toFixed(2)}ms) segments=${count}`,
               );
             }
             debugLog("cacheStore", "proactive caching complete", {
@@ -317,9 +247,6 @@ export function withCacheStore<TEnv>(
               pathname: ctx.pathname,
               error: String(error),
             });
-          } finally {
-            requestCtx._handleStore = originalHandleStore;
-            ctx.Store.metrics = savedMetrics;
           }
         });
       } else {

package/src/router/middleware-types.ts

@@ -4,7 +4,7 @@ import type {
   DefaultRouteName,
   DefaultVars,
 } from "../types/global-namespace.js";
-import type { ScopedReverseFunction } from "../reverse.js";
+import type { GlobalReverseFunction } from "../reverse.js";
 import type { Theme } from "../theme/types.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
 import type { RequestScope } from "../types/request-scope.js";
@@ -74,10 +74,8 @@ export interface MiddlewareContext<
 
   setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void;
 
-  reverse: ScopedReverseFunction<
-    Record<string, string>,
-    DefaultReverseRouteMap
-  >;
+  /** Global route names only; see {@link GlobalReverseFunction}. */
+  reverse: GlobalReverseFunction<DefaultReverseRouteMap>;
 }
 
 export type MiddlewareFn<

package/src/router/middleware.ts

@@ -1,6 +1,6 @@
 /// <reference types="vite/types/importMeta.d.ts" />
 
-import { contextGet, contextSet } from "../context-var.js";
+import { contextGet, contextSet, isNonCacheable } from "../context-var.js";
 import { escapeRegExp } from "../regex-escape.js";
 import { parsePattern as parseRoutePattern } from "./pattern-matching.js";
 import { safeDecodeURIComponent } from "./url-params.js";
@@ -22,8 +22,15 @@ import {
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { appendMetric, createMetricsStore } from "./metrics.js";
 import { observePhase, PHASES } from "./instrument.js";
-import { stripInternalParams } from "./handler-context.js";
+import { guardHeaderWrites, stripInternalParams } from "./handler-context.js";
 import { isWebSocketUpgradeResponse } from "../response-utils.js";
+import {
+  INSIDE_CACHE_EXEC,
+  NOCACHE_SYMBOL,
+  assertNotInsideCacheExec,
+} from "../cache/taint.js";
+import { getCacheExecScope } from "../cache/cache-exec-scope.js";
+import { assertNonCacheableReadAllowed } from "../server/context.js";
 
 // Re-export types consumed through this module's path.
 export type {
@@ -230,7 +237,12 @@ export function createMiddlewareContext<TEnv>(
   // so snapshotting beats re-reading ALS on every access. The lazy getters
   // below (routeName, theme, setTheme) stay lazy because those can change
   // during `await next()`.
-  return {
+  //
+  // Request-scoped like the handler ctx (issue #940): the NOCACHE_SYMBOL brand
+  // below makes a "use cache" function taking it key by host, _routeName,
+  // pathname, params and search; set/header/headers throw inside that
+  // function, and non-cacheable get reads run the shared guard.
+  const ctx: MiddlewareContext<TEnv> & { readonly _routeName?: string } = {
     request,
     url,
     originalUrl: reqCtx?.originalUrl ?? new URL(request.url),
@@ -254,17 +266,43 @@ export function createMiddlewareContext<TEnv>(
       ) as MiddlewareContext<TEnv>["routeName"];
     },
 
+    // The matched route key, auto-generated names included (the handler
+    // ctx's _routeName); undefined before routing.
+    get _routeName(): string | undefined {
+      return _getRequestContext()?._routeName;
+    },
+
+    // Guarded only inside a "use cache" body: the stamp covers a miss that
+    // took this ctx as an argument, the exec scope a stale refresh (which does
+    // not stamp its args, cache-runtime.ts). A write there is lost on a hit.
     get headers(): Headers {
-      return getResponse().headers;
+      const headers = getResponse().headers;
+      return (INSIDE_CACHE_EXEC as symbol) in ctx ||
+        getCacheExecScope() !== undefined
+        ? guardHeaderWrites(headers, () =>
+            assertNotInsideCacheExec(ctx, "headers"),
+          )
+        : headers;
     },
 
-    get: ((keyOrVar: any) =>
-      contextGet(variables, keyOrVar)) as MiddlewareContext<TEnv>["get"],
+    get: ((keyOrVar: any) => {
+      // "use cache" only: intercept middleware runs inside a cache()
+      // subtree's render scope, and a middleware read is never cached there.
+      if (
+        isNonCacheable(variables, keyOrVar) &&
+        getCacheExecScope() !== undefined
+      ) {
+        assertNonCacheableReadAllowed(keyOrVar);
+      }
+      return contextGet(variables, keyOrVar);
+    }) as MiddlewareContext<TEnv>["get"],
 
     set: ((keyOrVar: any, value: unknown, options?: any) => {
+      assertNotInsideCacheExec(ctx, "set");
       contextSet(variables, keyOrVar, value, options);
     }) as MiddlewareContext<TEnv>["set"],
     header(name: string, value: string): void {
+      assertNotInsideCacheExec(ctx, "header");
       // Before next(): delegate to shared RequestContext stub
       if (isPreNext()) {
         const reqCtx = _getRequestContext();
@@ -323,6 +361,8 @@ export function createMiddlewareContext<TEnv>(
       }
     },
   };
+  (ctx as any)[NOCACHE_SYMBOL] = true;
+  return ctx;
 }
 
 /**
@@ -852,6 +892,7 @@ export function collectRouteMiddleware(
   params: Record<string, string>,
 ): CollectedMiddleware[] {
   const result: CollectedMiddleware[] = [];
+  const chain = [...entries];
 
   const collect = (entry: MiddlewareCollectableEntry): void => {
     // Collect entry's own middleware
@@ -860,15 +901,17 @@ export function collectRouteMiddleware(
         result.push({ handler: mw, params });
       }
     }
-    // Collect middleware from orphan layouts (recursive)
+    // Collect middleware from orphan layouts (recursive). A bare cache()
+    // marker is both its layout's orphan and a chain entry of the routes
+    // after it; it is collected once, at its chain position (issue #918).
     if (entry.layout && entry.layout.length > 0) {
       for (const orphan of entry.layout) {
-        collect(orphan);
+        if (!chain.includes(orphan)) collect(orphan);
       }
     }
   };
 
-  for (const entry of entries) {
+  for (const entry of chain) {
     collect(entry);
   }
 

package/src/router/prerender-match.ts

@@ -15,6 +15,7 @@ import {
 import { detectPrerenderPassthrough } from "../prerender.js";
 import { isRouteRootScoped } from "../route-map-builder.js";
 import { setupBuildUse } from "./loader-resolution.js";
+import { findInOrphans } from "./error-handling.js";
 import { loadManifest } from "./manifest.js";
 import { traverseBack } from "./pattern-matching.js";
 import type { RouterContext } from "./router-context.js";
@@ -306,7 +307,18 @@ export async function matchForPrerender<TEnv = any>(
       // 12. Serialize segments using the cache serializer
       const { serializeSegments } = await import("../cache/segment-codec.js");
       const { encodeHandles } = await import("../cache/handle-snapshot.js");
-      const serializedSegments = await serializeSegments(nonLoaderSegments);
+      // Flight encodes a component that throws (an async server component in
+      // the tree) as an error row and completes normally. Rethrown below like
+      // a handler throw, so the caller's policy decides instead of baking the
+      // error (#914).
+      const flightErrors: unknown[] = [];
+      const onFlightError = (error: unknown): void => {
+        flightErrors.push(error);
+      };
+      const serializedSegments = await serializeSegments(
+        nonLoaderSegments,
+        onFlightError,
+      );
 
       // 13. Collect handle data per segment (skip segments with no handle data).
       // Encoded through the Flight codec (not stored raw) so Promise/ReactNode
@@ -322,7 +334,9 @@ export async function matchForPrerender<TEnv = any>(
           handlesRecord[seg.id] = await resolveSegmentHandleValues(segHandles);
         }
       }
-      const handles = await encodeHandles(handlesRecord);
+      const handles = await encodeHandles(handlesRecord, onFlightError);
+      // Before intercept resolution, as a handler throw would be.
+      if (flightErrors.length > 0) throw flightErrors[0];
 
       // Use the trie-level route key (e.g., "docs", "docs.article")
       const routeName = matched.routeKey;
@@ -350,19 +364,23 @@ export async function matchForPrerender<TEnv = any>(
         intercept: InterceptEntry;
         entry: EntryData;
       }[] = [];
-      let current: EntryData | null = manifestEntry;
-      while (current) {
-        // Flatten the entry and its sibling layouts into one source list, the
-        // same traversal findInterceptForRoute uses; the build keeps ALL matches
-        // (not just the innermost) and skips when(). intercept/layout are
-        // non-optional arrays, so empty ones are a no-op here.
-        for (const source of [current, ...current.layout]) {
-          for (const ic of source.intercept) {
-            if (ic.routeName === matched.routeKey) {
-              foundIntercepts.push({ intercept: ic, entry: source });
-            }
+      // The entry, then its orphans (nested ones included): the same traversal
+      // findInterceptForRoute uses; the build keeps ALL matches (not just the
+      // innermost) and skips when().
+      const collect = (source: EntryData): undefined => {
+        for (const ic of source.intercept) {
+          if (ic.routeName === matched.routeKey) {
+            foundIntercepts.push({ intercept: ic, entry: source });
           }
         }
+        return undefined;
+      };
+      let current: EntryData | null = manifestEntry;
+      let prev: EntryData | null = null;
+      while (current) {
+        collect(current);
+        findInOrphans(current, collect, prev);
+        prev = current;
         current = current.parent;
       }
 
@@ -427,6 +445,7 @@ export async function matchForPrerender<TEnv = any>(
           await handleStore.settled;
           interceptSegments = await serializeSegments(
             interceptResolvedSegments,
+            onFlightError,
           );
           const interceptHandlesRecord: Record<string, SegmentHandleData> = {};
           for (const seg of interceptResolvedSegments) {
@@ -439,13 +458,18 @@ export async function matchForPrerender<TEnv = any>(
           // The intercept artifact serves main + intercept segments together, so
           // encode the MERGED handle map here (the sinks no longer merge raw
           // records — they store this pre-encoded string as-is).
-          interceptHandles = await encodeHandles({
-            ...handlesRecord,
-            ...interceptHandlesRecord,
-          });
+          interceptHandles = await encodeHandles(
+            {
+              ...handlesRecord,
+              ...interceptHandlesRecord,
+            },
+            onFlightError,
+          );
         }
       }
 
+      if (flightErrors.length > 0) throw flightErrors[0];
+
       return {
         segments: serializedSegments,
         handles,
@@ -576,7 +600,12 @@ export async function renderStaticSegment<TEnv = any>(
 
     const { serializeSegments } = await import("../cache/segment-codec.js");
     const { encodeHandleValue } = await import("../cache/handle-snapshot.js");
-    const [serialized] = await serializeSegments([segment]);
+    // Same error-row guard as matchForPrerender (#914).
+    const flightErrors: unknown[] = [];
+    const onFlightError = (error: unknown): void => {
+      flightErrors.push(error);
+    };
+    const [serialized] = await serializeSegments([segment], onFlightError);
 
     // Collect handle data pushed during rendering and Flight-encode it (so
     // Promise/ReactNode handle values survive the JSON build artifact). "" when
@@ -584,9 +613,14 @@ export async function renderStaticSegment<TEnv = any>(
     const segHandles = handleStore.getDataForSegment(handlerId);
     const handles =
       Object.keys(segHandles).length > 0
-        ? await encodeHandleValue(await resolveSegmentHandleValues(segHandles))
+        ? await encodeHandleValue(
+            await resolveSegmentHandleValues(segHandles),
+            onFlightError,
+          )
         : "";
 
+    if (flightErrors.length > 0) throw flightErrors[0];
+
     return { encoded: serialized.encoded, handles };
   });
 }

package/src/router/route-snapshot.ts

@@ -15,6 +15,7 @@
 import type { CacheScope } from "../cache/cache-scope.js";
 import { createCacheScope } from "../cache/cache-scope.js";
 import type { EntryData, MetricsStore } from "../server/context.js";
+import { isPprEntry } from "../server/context.js";
 import { loadManifest } from "./manifest.js";
 import { collectRouteMiddleware } from "./middleware.js";
 import type { CollectedMiddleware } from "./middleware-types.js";
@@ -222,10 +223,19 @@ function buildEntriesAndCacheScope(manifestEntry: EntryData): {
   cacheScope: CacheScope | null;
 } {
   const entries = [...traverseBack(manifestEntry)];
+  // A cache() boundary keeps the entries above it live. A ppr route is a
+  // document-scoped cache(): its whole chain bakes into the shell, and the
+  // shell HIT tail must replay it to match the prelude, so its scope covers
+  // the whole chain.
+  const wholeChain = isPprEntry(manifestEntry);
   let cacheScope: CacheScope | null = null;
   for (const entry of entries) {
     if (entry.cache) {
-      cacheScope = createCacheScope(entry.cache, cacheScope);
+      cacheScope = createCacheScope(
+        entry.cache,
+        cacheScope,
+        wholeChain ? undefined : entry.shortCode,
+      );
     }
   }
   return { entries, cacheScope };

package/src/router/router-context.ts

@@ -131,6 +131,8 @@ export interface RouterContext<TEnv = any> {
     localRouteName: string,
     pathname: string,
     stale?: boolean,
+    /** The matched route's full chain when `entries` is part of it (ResolveSegmentOptions.chain). */
+    chain?: readonly EntryData[],
   ) => Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }>;
 
   // Generator-based segment resolution (for pipeline)

package/src/router/router-interfaces.ts

@@ -177,6 +177,23 @@ export interface Rango<
    */
   readonly routeMap: TRoutes;
 
+  /**
+   * Serialize the route manifest for inspection: every route and layout the
+   * router's `.routes()` / `urls` mounts register, with shortCodes, parent
+   * links, and loader/middleware/error-boundary/parallel/intercept flags.
+   *
+   * Server-only development aid. It re-evaluates each mount's `urls()` tree.
+   * Groups mounted with `include()` are lazy and are not expanded: their
+   * routes are absent from the result.
+   *
+   * @example
+   * ```typescript
+   * const manifest = await router.debugManifest();
+   * console.log(manifest.totalRoutes, Object.keys(manifest.routes));
+   * ```
+   */
+  debugManifest(): Promise<SerializedManifest>;
+
   /**
    * Handle an RSC request.
    *
@@ -187,7 +204,13 @@ export interface Rango<
    * ```tsx
    * import { router } from "./router";
    *
-   * export default { fetch: router.fetch };
+   * // Workers call fetch(request, env, ctx); `{ fetch: router.fetch }` would
+   * // drop env and ctx.
+   * export default {
+   *   fetch(request, env, ctx) {
+   *     return router.fetch(request, { env, ctx });
+   *   },
+   * } satisfies ExportedHandler;
    * ```
    *
    * @example Direct export
@@ -316,7 +339,7 @@ export interface RangoInternal<
 
   /**
    * Resolved theme configuration (null if theme not enabled)
-   * Used by NavigationProvider to include ThemeProvider and by MetaTags to render theme script
+   * Used by NavigationProvider to include ThemeProvider and by `Html.Meta` to render theme script
    */
   readonly themeConfig: import("../theme/types.js").ResolvedThemeConfig | null;
 

package/src/router/router-options.ts

@@ -164,8 +164,10 @@ export interface RangoOptions<TEnv = any> {
    *
    * Must be a client component ("use client") that accepts { children }.
    *
-   * If not provided, a default document with basic HTML structure is used:
-   * `<html><head><meta charset/viewport></head><body>{children}</body></html>`
+   * If not provided, a default document is used: `Html.Meta` and `Html.Scripts`
+   * in `<head>`, `Html.Scripts position="body"` before `{children}` and
+   * `Html.ScrollRestoration` after it. Pass your own to set `getKey` or to
+   * leave back/forward scrolling to the browser.
    *
    * @example
    * ```typescript
@@ -201,7 +203,8 @@ export interface RangoOptions<TEnv = any> {
 
   /**
    * Default not-found boundary fallback used when no notFoundBoundary is defined in the route tree
-   * If not provided, DataNotFoundError will be treated as a regular error
+   * If not provided, notFound() renders the `notFound` option, else a plain
+   * `<h1>Not Found</h1>` (status 404)
    */
   defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler;
 
@@ -211,7 +214,7 @@ export interface RangoOptions<TEnv = any> {
    * This is rendered within your document/app shell with a 404 status code.
    * Use this for a custom 404 page that maintains your app's look and feel.
    *
-   * If not provided, a default "Page not found" component is rendered.
+   * If not provided, a plain `<h1>Not Found</h1>` is rendered.
    *
    * Can be a static ReactNode or a function receiving the pathname.
    *
@@ -368,7 +371,7 @@ export interface RangoOptions<TEnv = any> {
    * When provided, enables:
    * - ctx.theme and ctx.setTheme() in route handlers
    * - useTheme() hook for client components
-   * - FOUC prevention via inline script in MetaTags
+   * - FOUC prevention via inline script in `<Html.Meta />`
    * - Automatic ThemeProvider wrapping in NavigationProvider
    *
    * @example