@rangojs/router 0.16.0 → 0.17.0

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

package/src/router/segment-resolution/fresh.ts

@@ -120,12 +120,8 @@ export async function resolveLoaders<TEnv>(
   // loading-disabled entries consult it), so normal requests are unchanged.
   const emitStreaming = !loadingDisabled || isShellCaptureActive();
 
-  // PPR lane decision for this entry's loaders (loader-container-bake): an
-  // entry WITHOUT renderable loading() puts its loaders on the BAKE lane —
-  // executed at capture (container bakes, nested pending promises hole at the
-  // consumer's Suspense) and overlay-pinned from the shell snapshot on a HIT.
-  // Renderable loading() keeps the LIVE lane (masked at capture, always
-  // fresh). Computed per entry; resolveLoaderData applies the policy.
+  // PPR bake/seed key input only; lane rule: see resolveLoaderData
+  // (loader-cache.ts). Unflagged loaders mask at capture regardless of the key.
   const bakeLane = !entryLoadingMasksLoaders(entry.loading);
 
   // Error context for wrapLoaderPromise: without it, a throwing DSL loader never
@@ -146,9 +142,9 @@ export async function resolveLoaders<TEnv>(
     // barrier), and the loader body can call rendered() before the await below
     // is reached.
     //
-    // Shell-capture renders await too: flagged loaders BAKE at capture
-    // (loader-mask masks only LIVE-lane loaders). Capture must await them so
-    // bake-lane handle pushes land in the prelude.
+    // Shell-capture renders await too: flagged loaders execute at capture
+    // (lane rule: see resolveLoaderData, loader-cache.ts), so their handle
+    // pushes must land in the prelude.
     const awaitedIndices = registerAwaitBeforeFlushIds(loaderEntries);
 
     // Streaming loaders: promises kick off now, settle during RSC serialization.
@@ -276,6 +272,16 @@ export interface ResolveSegmentOptions {
    * so error boundaries keep catching at request time.
    */
   throwOnError?: boolean;
+  /**
+   * The matched route's full entry chain. resolveAllSegments defaults it to
+   * its `entries`; withCacheLookup passes it when it resolves only the entries
+   * above a cache() boundary. An orphan list can hold an entry of the chain: a
+   * bare cache() marker sits in its layout's layout[] (it wraps that layout's
+   * routes) and is the parent of the routes after it. For those routes it
+   * resolves once, as a chain entry, below the cache() header latch (issue
+   * #918: resolved twice on a MISS, once and discarded on a HIT).
+   */
+  chain?: readonly EntryData[];
 }
 
 /**
@@ -349,6 +355,7 @@ export async function resolveSegment<TEnv>(
     }
 
     for (const orphan of entry.layout) {
+      if (options?.chain?.includes(orphan)) continue;
       const orphanSegments = await resolveOrphanLayout(
         orphan,
         params,
@@ -578,6 +585,26 @@ export async function resolveOrphanLayout<TEnv>(
     resolvedParallelEntries.add(parallelEntry.id);
   }
 
+  // Routeless entries nested in this one (a layout() after a bare cache()
+  // marker, a wrapper inside a routeless wrapper) wrap the same content one
+  // level deeper. Issue #918: they were never rendered. None is in the
+  // matched chain: that would put this orphan in it, and resolveSegment
+  // skips those.
+  for (const nested of orphan.layout) {
+    segments.push(
+      ...(await resolveOrphanLayout(
+        nested,
+        params,
+        context,
+        loaderPromises,
+        belongsToRoute,
+        deps,
+        options,
+        routeKey,
+      )),
+    );
+  }
+
   return segments;
 }
 
@@ -736,6 +763,10 @@ export async function resolveAllSegments<TEnv>(
 ): Promise<ResolvedSegment[]> {
   const allSegments: ResolvedSegment[] = [];
   const seenIds = new Set<string>();
+  const segmentOptions: ResolveSegmentOptions = {
+    ...options,
+    chain: options?.chain ?? entries,
+  };
 
   // ppr routes are document-scoped cached territory: the whole chain (root
   // layout down to the page) bakes into the shared shell, so the header-write
@@ -760,8 +791,9 @@ export async function resolveAllSegments<TEnv>(
     // Set ALS flag when entering a cache() boundary so that ctx.get()
     // can guard non-cacheable variable reads. Also latch the header-write
     // scope (response-level side effects — headers/cookies/status).
-    // Persists for all descendant entries.
-    if (entry.type === "cache") {
+    // Persists for all descendant entries. A route entry carries `cache` when
+    // cache() is among its own children (dsl-helpers.ts cache()).
+    if (entry.cache) {
       const store = RangoContext.getStore();
       if (store) store.insideCacheScope = true;
       latchCachedHeaderScope("cache", routeKey);
@@ -779,7 +811,7 @@ export async function resolveAllSegments<TEnv>(
           loaderPromises,
           deps,
           false,
-          options,
+          segmentOptions,
         ),
       (seg) => [seg],
       deps,