@rangojs/router 0.24.4 → 0.26.0

package/src/index.ts

@@ -134,6 +134,14 @@ function serverOnlyStubError(name: string): Error {
   );
 }
 
+/** A stub whose name `@rangojs/router/client` exports for clientUrls(). */
+function clientUrlsHelperStubError(name: string): Error {
+  return new Error(
+    `${name}() is only available from "@rangojs/router" in a react-server/RSC environment. ` +
+      `In a "use client" module (a clientUrls() component's .use), import ${name}() from "@rangojs/router/client".`,
+  );
+}
+
 /**
  * Error-throwing stub for server-only `urls` function.
  */
@@ -276,7 +284,7 @@ export function middleware(): never {
   throw serverOnlyStubError("middleware");
 }
 export function revalidate(): never {
-  throw serverOnlyStubError("revalidate");
+  throw clientUrlsHelperStubError("revalidate");
 }
 // Cache tag APIs are server-only (real implementations in index.rsc.ts). These
 // stubs keep the named-export shape identical under the default/non-react-server
@@ -291,10 +299,10 @@ export function revalidateTag(): never {
   throw serverOnlyStubError("revalidateTag");
 }
 export function loader(): never {
-  throw serverOnlyStubError("loader");
+  throw clientUrlsHelperStubError("loader");
 }
 export function loading(): never {
-  throw serverOnlyStubError("loading");
+  throw clientUrlsHelperStubError("loading");
 }
 export function parallel(): never {
   throw serverOnlyStubError("parallel");
@@ -309,7 +317,7 @@ export function notFoundBoundary(): never {
   throw serverOnlyStubError("notFoundBoundary");
 }
 export function transition(): never {
-  throw serverOnlyStubError("transition");
+  throw clientUrlsHelperStubError("transition");
 }
 
 // Request context type (safe for client)

package/src/loader-redirect.tsx

@@ -19,9 +19,8 @@ import { resolveSameOriginRedirect } from "./redirect-origin.js";
  *
  * Own module (not route-content-wrapper.tsx) because BOTH consumers need it
  * without a cycle: the StreamedLoaderErrorBoundary redirect branch (read-site
- * throw path) and decodeLoaderResults (aggregate forceAwait/action path, which
- * runs during the server tree build and cannot throw — it plants this element
- * in the errorFallback slot instead).
+ * throw path) and decodeLoaderResults (the tree build's settled results, which
+ * cannot throw — it plants this element in the errorFallback slot instead).
  */
 export function LoaderRedirect({
   to,

package/src/outlet-context.ts

@@ -13,18 +13,19 @@ export interface OutletContextValue {
    * $$id. A value may be a pending Promise (loader still streaming) or an
    * already-settled result entry. useLoader `use()`es a pending value at the
    * read site — implicit suspension to the nearest consumer Suspense boundary —
-   * and decodes via decodeLoaderEntry. Populated instead of `loaderData` on
-   * streaming lanes (plain navs, document SSR); forceAwait/action lanes keep
-   * the resolved `loaderData` record.
+   * and decodes via decodeLoaderEntry. Populated instead of `loaderData` for
+   * a route's or layout's loaders on every lane; forceAwait/action lanes hand
+   * settled entries. `loaderData` is a slot's decoded aggregate.
    */
   loaderStreams?: Record<string, unknown>;
   /**
    * Loader $$ids on this segment that the render awaited before first flush
    * (loader(Def, { ssr: false })). Dev-diagnostic input only: useLoader uses
    * it to warn when a read still suspends during SSR on a render that awaited
-   * flagged loaders (ssr-suspension-warning.ts). Present only on streaming
-   * lanes with flagged loaders (document and shell-capture renders); absent
-   * on forceAwait/action lanes.
+   * flagged loaders (ssr-suspension-warning.ts). Present only where a
+   * segment carries flagged loaders (document and shell-capture renders, and
+   * a client lane that re-renders their segments); a settled read never
+   * suspends, so it never warns.
    */
   awaitedLoaderIds?: readonly string[];
   parent?: OutletContextValue | null;

package/src/prefetch-markers.ts

@@ -1,9 +1,9 @@
 /**
- * The wire markers of `prefetch: false` (docs/design/prefetch-false.md):
- * shared by the browser that sends them and the server that reads them
- * (router/segment-resolution/prefetch-deferral.ts requestKind). Dependency
- * free, like segment-fragments.ts: the browser must not import the server
- * module that reads them.
+ * The wire markers of prefetches and of `prefetch: false`
+ * (docs/design/prefetch-false.md): shared by the browser and the server
+ * (router/segment-resolution/prefetch-deferral.ts requestKind,
+ * rsc/prefetch-render-error.ts). Dependency free, like segment-fragments.ts:
+ * the browser must not import the server modules that use them.
  */
 
 /** Request header of a `<Link>` prefetch (browser/prefetch/fetch.ts). */
@@ -11,3 +11,13 @@ export const PREFETCH_HEADER = "X-Rango-Prefetch";
 
 /** Query param of a fill request (browser/navigation-client.ts). */
 export const FILL_PARAM = "_rsc_fill";
+
+/**
+ * The last row of a prefetch whose render reported an error
+ * (rsc/prefetch-render-error.ts): a Flight hint with a code React does not
+ * dispatch, so the decoder skips it (pinned by
+ * src/__tests__/flight-unknown-hint.test.ts), and browser/response-adapter.ts
+ * reads the stream as not ended cleanly. Five bytes: teeWithCompletion keeps
+ * the last five.
+ */
+export const PREFETCH_FAILED_ROW = ":H_0\n";

package/src/prerender/build-shell-capture.ts

@@ -106,8 +106,7 @@ export interface BuildShellCaptureOptions {
   /** Build-time env bindings (rango plugin buildEnv), if configured. */
   buildEnv?: unknown;
   /**
-   * The versions the SHIPPED build serves this router with (the build table,
-   * or the router's consumer-set version) — NOT the temp server's own
+   * The versions the SHIPPED build serves this router with (the build table) — NOT the temp server's own
    * version-plugin stamp. The serve-side isValidShellHit gate compares
    * entry.buildVersion against the running worker's ctx.version, which is the
    * document version; stamping the temp server's would make every build entry

package/src/prerender/writable-store.ts

@@ -22,9 +22,8 @@ import { paramsEqual } from "../router/params-util.js";
 export interface PrerenderKey {
   routerId: string;
   /**
-   * The owning router's cache version (its data version, or
-   * `createRouter({ version })`). Opaque: never set or read by app code; a
-   * store keys off it as given.
+   * The owning router's cache version (its data version). Opaque: never set
+   * or read by app code; a store keys off it as given.
    */
   version: string;
   routeName: string;

package/src/reverse.ts

@@ -406,9 +406,9 @@ export function createReverse<TRoutes extends Record<string, string>>(
       throw new Error(`Unknown route: ${name}`);
     }
 
-    let result = params
-      ? substitutePatternParams(pattern, params, name)
-      : pattern;
+    // Always substitute: a required param with no params object throws
+    // `Missing param` rather than returning the raw `:param` pattern.
+    let result = substitutePatternParams(pattern, params ?? {}, name);
 
     // Append search params as query string
     if (search) {

package/src/route-content-wrapper.tsx

@@ -18,6 +18,7 @@ import {
   useRevealAudit,
 } from "./suspense-audit-react.js";
 import { SETTLED_THENABLE } from "./thenable-status.js";
+import { shallowEqual } from "./browser/react/shallow-equal.js";
 
 /**
  * Router-owned error boundary for read-site loader errors. segment-system
@@ -40,12 +41,12 @@ import { SETTLED_THENABLE } from "./thenable-status.js";
  * Errors without any marker rethrow to the app's own boundaries.
  */
 export class StreamedLoaderErrorBoundary extends Component<
-  { children: ReactNode; resetKey?: string },
-  { error: unknown; resetKey?: string }
+  { children: ReactNode; reset: unknown[] },
+  { error: unknown; reset: unknown[] }
 > {
-  state: { error: unknown; resetKey?: string } = {
+  state: { error: unknown; reset: unknown[] } = {
     error: null,
-    resetKey: this.props.resetKey,
+    reset: this.props.reset,
   };
 
   static getDerivedStateFromError(error: unknown): { error: unknown } {
@@ -54,20 +55,21 @@ export class StreamedLoaderErrorBoundary extends Component<
 
   /**
    * A caught marker (redirect, notFound, error fallback) belongs to ONE route
-   * + params. Group-keyed segments (ResolvedSegment.clientGroup) keep this
-   * instance alive across in-group navigations, so the error must clear when
-   * the route or params change — otherwise a redirect caught for /legacy
-   * keeps rendering LoaderRedirect for /state. `resetKey` is the segment's
-   * id-params identity, the cadence the per-route remount used to provide.
+   * + params and ONE delivery of the segment's loader data. `reset` is the
+   * segment's id-params identity followed by each of its loaders' data; the
+   * error clears when any of them changes. Group-keyed segments
+   * (ResolvedSegment.clientGroup) keep this instance alive across in-group
+   * navigations, so a redirect caught for /legacy must not keep rendering
+   * LoaderRedirect for /state. A rerun hands a loader new data, a held loader
+   * keeps its own: a later action or navigation that re-ran the loader clears
+   * an error fallback left by an earlier failure, and a tree that re-ran
+   * nothing here keeps it.
    */
   static getDerivedStateFromProps(
-    props: { resetKey?: string },
-    state: { error: unknown; resetKey?: string },
-  ): { error: unknown; resetKey?: string } | null {
-    if (props.resetKey !== state.resetKey) {
-      return { error: null, resetKey: props.resetKey };
-    }
-    return null;
+    { reset }: { reset: unknown[] },
+    state: { reset: unknown[] },
+  ): { error: null; reset: unknown[] } | null {
+    return shallowEqual(reset, state.reset) ? null : { error: null, reset };
   }
 
   render(): ReactNode {
@@ -311,7 +313,7 @@ function AuditedLoaderResolver({
  * Without streams, the pre-spike behavior is preserved: a pending aggregate
  * resolves ABOVE via use() (parallel/intercept slots still take this path —
  * ResolvedSegment carries only the aggregate for slots), and a resolved
- * array decodes synchronously (forceAwait/action lanes commit whole).
+ * array decodes synchronously (a slot on the forceAwait/action lanes).
  */
 function LoaderResolver({
   loaderDataPromise,

package/src/route-definition/dsl-helpers.ts

@@ -9,8 +9,11 @@ import type {
   TransitionConfig,
 } from "../types.js";
 import {
+  applyDocumentModeLoading,
+  documentModeLoader,
   getContext,
   getNamePrefix,
+  getReverseScope,
   getUrlPrefix,
   requireDslContext,
   stampStaticDefScope,
@@ -52,6 +55,7 @@ import {
   validateInterceptUseItems,
 } from "./resolve-handler-use.js";
 import { ALL_USE_ITEM_TYPES } from "./use-item-types.js";
+import { toShouldRevalidateFn } from "../router/revalidation.js";
 
 /**
  * Check if an item contains routes (directly or inside nested wrappers).
@@ -189,6 +193,10 @@ const revalidate: RouteHelpers<any, any>["revalidate"] = (fn) => {
   const { store, ctx } = requireDslContext(
     "revalidate() must be called inside urls()",
   );
+  invariant(
+    typeof fn === "function" || typeof fn === "boolean",
+    `revalidate() expects a predicate or a boolean, got ${fn === null ? "null" : typeof fn}`,
+  );
 
   // Attach to last entry in stack
   const parent = ctx.parent;
@@ -196,7 +204,7 @@ const revalidate: RouteHelpers<any, any>["revalidate"] = (fn) => {
     invariant(false, "No parent entry available for revalidate()");
   }
   const name = `$${store.getNextIndex("revalidate")}`;
-  parent.revalidate.push(fn);
+  parent.revalidate.push(toShouldRevalidateFn(fn));
   return { name, type: "revalidate" } as RevalidateItem;
 };
 
@@ -394,6 +402,7 @@ const cache: RouteHelpers<any, any>["cache"] = (
       cache: cacheConfig,
       handler: RootLayout,
       ...(urlPrefix ? { mountPath: urlPrefix } : {}),
+      reverseScope: getReverseScope(),
     } satisfies EntryData;
 
     // Attach to parent's layout array (cache entries are structural like layouts)
@@ -433,6 +442,7 @@ const cache: RouteHelpers<any, any>["cache"] = (
     // Cache entries render like layouts (with Outlet as default handler)
     handler: RootLayout, // RootLayout just renders <Outlet />
     ...(urlPrefix ? { mountPath: urlPrefix } : {}),
+    reverseScope: getReverseScope(),
   } satisfies EntryData;
 
   // Run children with cache entry as parent
@@ -522,6 +532,7 @@ const middleware: RouteHelpers<any, any>["middleware"] = (...args: any[]) => {
     handler: RootLayout,
     middleware: [...fns],
     ...(urlPrefix ? { mountPath: urlPrefix } : {}),
+    reverseScope: getReverseScope(),
   } satisfies EntryData;
 
   // Run children callback. If the second arg was actually a middleware fn
@@ -643,6 +654,7 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
     parent: null, // Parallels don't participate in parent chain traversal
     handler: unwrappedSlots,
     ...(parallelUrlPrefix ? { mountPath: parallelUrlPrefix } : {}),
+    reverseScope: getReverseScope(),
     ...(hasStaticSlot
       ? {
           isStaticPrerender: true as const,
@@ -777,12 +789,11 @@ const intercept = (
   const prefixedRouteName =
     isLocal && namePrefix ? `${namePrefix}.${bareRouteName}` : bareRouteName;
 
-  // Create intercept entry with its own loaders/middleware/when
+  // Create intercept entry with its own loaders/when
   const entry: InterceptEntry = {
     slotName: slotName as `@${string}`,
     routeName: prefixedRouteName,
     handler,
-    middleware: [],
     loader: [],
     when: [], // Selector conditions for conditional interception
   };
@@ -800,12 +811,12 @@ const intercept = (
   const handlerUseFn = resolveHandlerUse(handler);
   const mergedUse = mergeHandlerUse(handlerUseFn, useFn, null);
 
-  // Run merged use callback to collect loaders, middleware, etc.
+  // Run merged use callback to collect loaders, loading, layout, etc.
   if (mergedUse) {
     // Capture layout() calls into a temporary array
     const capturedLayouts: EntryData[] = [];
 
-    // Temporary parent so middleware/loader attach to the intercept entry;
+    // Temporary parent so loader() attaches to the intercept entry;
     // the loading get/set accessor mirrors writes onto `entry`. It is a
     // shallow spread of the enclosing entry, so every field a rejected helper
     // writes to points at a throwaway here: a helper called but not returned
@@ -814,8 +825,12 @@ const intercept = (
     // is a route.
     //
     // Why an intercept rejects these (validateInterceptUseItems):
+    // - middleware(): only the live render resolved the intercept's own
+    //   middleware; a cache() hit or a Prerender() target skipped it, so a
+    //   guard in it was bypassed. The target route's middleware runs on every
+    //   pass, the modal's included.
     // - revalidate(): an intercept only evaluates its loaders' revalidate()
-    //   (router/intercept-resolution.ts).
+    //   (loader segments of its slot, router/intercept-resolution.ts).
     // - errorBoundary()/notFoundBoundary(): error lookup walks EntryData
     //   parent chains (router/error-handling.ts), which never include an
     //   InterceptEntry; intercept loader errors resolve against the declaring
@@ -824,7 +839,7 @@ const intercept = (
     //   cache() scope, with its own "intercept:" key (cache/cache-scope.ts).
     const tempParent = {
       ...ctx.parent,
-      middleware: entry.middleware,
+      middleware: [],
       loader: entry.loader,
       layout: capturedLayouts,
       revalidate: [],
@@ -833,6 +848,8 @@ const intercept = (
       parallel: {},
       intercept: [],
       cache: undefined,
+      // Its loaders resolve `.name` like the intercept handler: from the route.
+      reverseScope: undefined,
       get loading() {
         return entry.loading;
       },
@@ -913,18 +930,19 @@ const loader: RouteHelpers<any, any>["loader"] = (
 
   const name = `${ctx.namespace}.$${store.getNextIndex("loader")}`;
 
-  // Create loader entry with empty revalidate array. awaitBeforeFlush is
-  // resolved here, at DSL-evaluation time, for the same reason
-  // loading({ ssr: false }) is (below) — per-isSSR entry caching makes the
-  // flag request-mode-correct with no isSSR threading; see LoaderEntry.
-  // `bake` is the lane, the same on both evaluations.
+  // Create loader entry with empty revalidate array. `bake` is the lane, the
+  // same on both evaluations; a document evaluation adds awaitBeforeFlush at
+  // the push (documentModeLoader) — per-isSSR entry caching makes the flag
+  // request-mode-correct with no isSSR threading; see LoaderEntry.
   const loaderEntry: LoaderEntry = {
     loader: loaderDef,
     revalidate: [] as ShouldRevalidateFn<any, any>[],
     ...(optionsGiven?.ssr === false && { bake: true as const }),
-    ...(optionsGiven?.ssr === false &&
-      ctx.isSSR && { awaitBeforeFlush: true as const }),
     ...(optionsGiven?.prefetch === false && { prefetch: false as const }),
+    // The declaring layout's / parallel's / cache()'s scope. A route's (and
+    // an intercept's) loaders have none: they resolve from the route's name,
+    // like the handler.
+    ...(ctx.parent.reverseScope && { reverseScope: ctx.parent.reverseScope }),
   };
 
   // Merge handler.use defaults (attached to the loader definition) with explicit use
@@ -959,7 +977,9 @@ const loader: RouteHelpers<any, any>["loader"] = (
     validateUseItems(result, name, "loader", "use");
   }
 
-  ctx.parent.loader.push(loaderEntry);
+  ctx.parent.loader.push(
+    ctx.isSSR ? documentModeLoader(loaderEntry) : loaderEntry,
+  );
   return { name, type: "loader" } as LoaderItem;
 };
 
@@ -987,12 +1007,11 @@ const loading: RouteHelpers<any, any>["loading"] = (component, options) => {
   const resolved =
     typeof component === "function" ? (component as () => any)() : component;
 
-  // If ssr: false and we're in SSR, set loading to false
-  if (options?.ssr === false && ctx.isSSR) {
-    parent.loading = false;
-  } else {
-    parent.loading = resolved;
-  }
+  // `loadingSsr` records ssr: false on both evaluations; a document drops
+  // the fallback (applyDocumentModeLoading).
+  parent.loading = resolved;
+  parent.loadingSsr = options?.ssr === false ? false : undefined;
+  if (ctx.isSSR) applyDocumentModeLoading(parent);
 
   // The flag means "what this fallback covers": without a fallback to show
   // there is nothing to defer behind. Recorded from `resolved`, not
@@ -1156,6 +1175,7 @@ const layout: RouteHelpers<any, any>["layout"] = (handler, use) => {
     parent: ctx.parent,
     handler: unwrappedHandler,
     ...(urlPrefix ? { mountPath: urlPrefix } : {}),
+    reverseScope: getReverseScope(),
     ...(isStatic
       ? {
           isStaticPrerender: true as const,

package/src/route-definition/helpers-types.ts

@@ -183,7 +183,7 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    * // With loaders and revalidation (revalidate() goes on the loader;
    * // an intercept-level revalidate() throws)
    * intercept("@modal", "card", () => <CardModal />, () => [
-   *   loader(CardModalLoader, () => [revalidate(() => false)]),
+   *   loader(CardModalLoader, () => [revalidate(false)]),
    * ])
    *
    * // Conditional activation via the config object's `when` selector
@@ -288,6 +288,9 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    * revalidate(({ defaultShouldRevalidate }) =>
    *   ({ defaultShouldRevalidate: true })
    * )
+   *
+   * // Shorthand for a constant hard decision: revalidate(() => false)
+   * revalidate(false)
    * ```
    * Not valid directly inside intercept() use() (throws at definition time):
    * intercepts only revalidate their loaders, so attach it there with
@@ -298,8 +301,10 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *     for downstream revalidators),
    *   - or nothing / `null` / `undefined` (defer — leaves the suggestion
    *     unchanged and continues to the next revalidator).
+   *   Or `true` / `false`: shorthand for `() => true` / `() => false`. A
+   *   defer has no shorthand; write the function.
    */
-  revalidate: (fn: ShouldRevalidateFn<any, TEnv>) => RevalidateItem;
+  revalidate: (fn: ShouldRevalidateFn<any, TEnv> | boolean) => RevalidateItem;
   /**
    * Attach a data loader to the current route/layout
    * ```typescript

package/src/route-definition/resolve-handler-use.ts

@@ -93,14 +93,7 @@ const MOUNT_SITE_ALLOWED_TYPES: Record<string, Set<string>> = {
   ]),
   // intercept() checks its whole merged use() (explicit and handler.use)
   // against this set via validateInterceptUseItems below.
-  intercept: new Set([
-    "middleware",
-    "loader",
-    "loading",
-    "layout",
-    "route",
-    "transition",
-  ]),
+  intercept: new Set(["loader", "loading", "layout", "route", "transition"]),
   // LoaderUseItem — only revalidate + cache can attach to a loader entry
   loader: new Set(["revalidate", "cache"]),
 };
@@ -113,6 +106,8 @@ const INTERCEPT_BOUNDARY_HINT =
  * hold them is documented at intercept() in dsl-helpers.ts.
  */
 const INTERCEPT_REJECTION_HINTS: Record<string, string> = {
+  middleware:
+    "move it to the route's middleware() (it runs for the modal too) or into the loaders",
   revalidate:
     "attach it to the intercept's loader: loader(YourLoader, () => [revalidate(...)])",
   errorBoundary: INTERCEPT_BOUNDARY_HINT,
@@ -134,7 +129,7 @@ function rejectInterceptItem(
 
 /**
  * Validate every item an intercept's merged use() returned (explicit use()
- * and handler.use) against MOUNT_SITE_ALLOWED_TYPES.intercept, plus two
+ * and handler.use) against MOUNT_SITE_ALLOWED_TYPES.intercept, plus three
  * structural rules:
  * - a nested layout() is only the modal chrome (intercept() keeps its
  *   handler), so it may not carry use() items of its own;
@@ -142,13 +137,20 @@ function rejectInterceptItem(
  *   it was not returned; its orphan form re-parents the following siblings
  *   onto that entry, so it is rejected the same way. Inside a path, cache()
  *   writes `sinks.cache` instead (dsl-helpers.ts cache()).
+ * - middleware on a `capturedLayouts` entry is rejected like `sinks.middleware`:
+ *   it is an unreturned middleware(fn, () => [...]) or one called inside the
+ *   chrome layout's use(), and nothing would run it.
  */
 export function validateInterceptUseItems(
   items: AllUseItems[],
-  capturedLayouts: readonly { type: string }[],
+  capturedLayouts: readonly {
+    type: string;
+    middleware?: readonly unknown[];
+  }[],
   slotName: string,
   routeName: string,
   sinks: {
+    readonly middleware: readonly unknown[];
     readonly revalidate: readonly unknown[];
     readonly errorBoundary: readonly unknown[];
     readonly notFoundBoundary: readonly unknown[];
@@ -206,6 +208,17 @@ export function validateInterceptUseItems(
       routeName,
     );
   }
+  if (
+    sinks.middleware.length > 0 ||
+    capturedLayouts.some((l) => l.middleware?.length)
+  ) {
+    rejectInterceptItem(
+      "middleware()",
+      INTERCEPT_REJECTION_HINTS.middleware!,
+      slotName,
+      routeName,
+    );
+  }
   if (
     capturedLayouts.some((l) => l.type === "cache") ||
     sinks.cache !== undefined