@rangojs/router 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -182,6 +182,7 @@
     "prepublishOnly": "pnpm build",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
     "test": "playwright test",
+    "test:preload": "playwright test --config=playwright.preload.config.ts",
     "test:ui": "playwright test --ui",
     "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-basename --project=hmr-prerender --no-deps --workers=1 && RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
     "test:hmr-routes-local": "RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
@@ -191,7 +192,7 @@
   },
   "dependencies": {
     "@types/debug": "^4.1.12",
-    "@vitejs/plugin-rsc": "^0.5.30",
+    "@vitejs/plugin-rsc": "^0.5.31",
     "debug": "^4.4.1",
     "magic-string": "^0.30.17",
     "picomatch": "^4.0.4",
@@ -224,9 +225,9 @@
     "@playwright/test": "^1.49.1",
     "@testing-library/react": ">=16",
     "@vercel/functions": "^3.0.0",
-    "@vitejs/plugin-rsc": "^0.5.30",
-    "react": ">=19.2.6 <20",
-    "react-dom": ">=19.2.6 <20",
+    "@vitejs/plugin-rsc": "^0.5.31",
+    "react": ">=19.2.8 <20",
+    "react-dom": ">=19.2.8 <20",
     "vite": "^8.0.16",
     "vitest": ">=3"
   },

package/skills/client-urls/SKILL.md

@@ -118,15 +118,15 @@ typing work exactly as for server routes (`/typesafety`).
 
 ## Helpers: what exists inside clientUrls()
 
-| Helper         | Notes                                                                                 |
-| -------------- | ------------------------------------------------------------------------------------- |
-| `path()`       | Options are `name`, `search`, `trailingSlash` only (no `ppr`, no response variants)   |
-| `layout()`     | Must contain at least one `path()`                                                    |
-| `loader()`     | `loader(Def, use?)` or `loader(Def, { stream: "navigation" }, use?)` — see below      |
-| `loading()`    | Route/layout-level pending UI; inline `<Suspense>` at read sites is usually better    |
-| `revalidate()` | Valid **inside a loader() use callback only**; runs in the browser                    |
-| `transition()` | Data-only ViewTransition config — no `when` (that is a server-executed predicate)     |
-| `intercept()`  | Dot-local named target in the SAME definition; use may contain `loader()`/`loading()` |
+| Helper         | Notes                                                                                                                                                          |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `path()`       | Options are `name`, `search`, `trailingSlash`, `ppr` (shell caching — see /ppr skill; loader routes need `loading()` or capture refuses); no response variants |
+| `layout()`     | Must contain at least one `path()`                                                                                                                             |
+| `loader()`     | `loader(Def, use?)` or `loader(Def, { stream: "navigation" }, use?)` — see below                                                                               |
+| `loading()`    | Route/layout-level pending UI; inline `<Suspense>` at read sites is usually better                                                                             |
+| `revalidate()` | Valid **inside a loader() use callback only**; runs in the browser                                                                                             |
+| `transition()` | Data-only ViewTransition config — no `when` (that is a server-executed predicate)                                                                              |
+| `intercept()`  | Dot-local named target in the SAME definition; use may contain `loader()`/`loading()`                                                                          |
 
 `include`, `parallel`, `cache`, `middleware`, `errorBoundary`,
 `notFoundBoundary` **throw** — and that is a design position, not a gap.

package/src/client-urls/client-urls.ts

@@ -31,6 +31,56 @@ const TRANSITION_CONFIG_KEYS = new Set<PropertyKey>([
   "viewTransition",
 ]);
 
+const PPR_NUMBER_KEYS = new Set<PropertyKey>([
+  "ttl",
+  "swr",
+  "captureTimeout",
+  "maxSnapshotBytes",
+]);
+
+/**
+ * DSL-time shape check for the projected `ppr` path option. Mirrors
+ * PartialPrerenderProps but validates by hand: the value must survive the
+ * JSON projection to the server, so only `true` or a plain object of finite
+ * numbers plus a string[] `tags` is legal. The projection serializer
+ * (server-projection.ts) re-validates independently — this copy exists so a
+ * bad value fails in the authoring module with a DSL-shaped message.
+ */
+function validateClientPpr(value: unknown): void {
+  if (value === true) return;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(
+      "clientUrls() path() ppr must be true or a PartialPrerenderProps object",
+    );
+  }
+  for (const key of Reflect.ownKeys(value)) {
+    if (PPR_NUMBER_KEYS.has(key)) {
+      const n = (value as Record<PropertyKey, unknown>)[key];
+      if (typeof n !== "number" || !Number.isFinite(n)) {
+        throw new Error(
+          `clientUrls() path() ppr.${String(key)} must be a finite number`,
+        );
+      }
+      continue;
+    }
+    if (key === "tags") {
+      const tags = (value as { tags: unknown }).tags;
+      if (
+        !Array.isArray(tags) ||
+        tags.some((tag) => typeof tag !== "string" || tag === "")
+      ) {
+        throw new Error(
+          "clientUrls() path() ppr.tags must be an array of non-empty strings",
+        );
+      }
+      continue;
+    }
+    throw new Error(
+      `clientUrls() path() ppr received unsupported key ${JSON.stringify(String(key))}`,
+    );
+  }
+}
+
 const UNSUPPORTED_HELPERS = new Set([
   "include",
   "parallel",
@@ -173,6 +223,31 @@ function assertNamedComponent(
   component: unknown,
   helper: "path" | "layout" | "intercept",
 ): asserts component is ComponentType {
+  // Build-time handler wrappers get a TARGETED rejection ahead of the generic
+  // shape check: their handler code cannot live in a "use client" bundle and
+  // their render runs at build, so accepting one could only fail later and
+  // further from the mistake. Brand strings checked directly — importing
+  // static-handler.ts/prerender.ts here would pull server modules into the
+  // client graph for an error message.
+  const brand =
+    component !== null &&
+    (typeof component === "object" || typeof component === "function")
+      ? (component as { __brand?: unknown }).__brand
+      : undefined;
+  if (
+    brand === "staticHandler" ||
+    brand === "prerenderHandler" ||
+    brand === "prerenderPassthrough"
+  ) {
+    const wrapper = brand === "staticHandler" ? "Static()" : "Prerender()";
+    throw new Error(
+      `clientUrls() ${helper}() received a ${wrapper} handler. Build-time ` +
+        "handlers are server-DSL surface and cannot mount inside a client " +
+        "group — routes in a group render client components. For shell " +
+        "caching of a group route use the `ppr` path option; build-time " +
+        "prerendering belongs to the server tree around the include.",
+    );
+  }
   if (typeof component !== "function" || component.name.trim() === "") {
     throw new Error(
       `clientUrls() ${helper}() expects a named client component value`,
@@ -249,6 +324,9 @@ function createHelpers(): ClientUrlHelpers {
         'clientUrls() path() trailingSlash must be "always", "never", or "ignore"',
       );
     }
+    if (options?.ppr !== undefined) {
+      validateClientPpr(options.ppr);
+    }
 
     const items = use ? runUse(use, "path use") : [];
     rejectItems(items, new Set(["loader", "loading", "transition"]), "path");

package/src/client-urls/server-projection.ts

@@ -7,7 +7,11 @@ import {
   type InterceptSelectorContext,
 } from "../server/context.js";
 import type { LoaderDefinition, TrailingSlashMode } from "../types.js";
-import type { PathOptions, UrlPatterns } from "../urls/pattern-types.js";
+import type {
+  PartialPrerenderProps,
+  PathOptions,
+  UrlPatterns,
+} from "../urls/pattern-types.js";
 import type { PathHelpers } from "../urls/path-helper-types.js";
 import type { AllUseItems } from "../route-types.js";
 import { urls } from "../urls/urls-function.js";
@@ -45,6 +49,14 @@ const PROJECTION_OPTIONS = new Set<PropertyKey>([
   "name",
   "search",
   "trailingSlash",
+  "ppr",
+]);
+
+const PPR_NUMBER_KEYS = new Set<PropertyKey>([
+  "ttl",
+  "swr",
+  "captureTimeout",
+  "maxSnapshotBytes",
 ]);
 
 const clientUrlProjections = new Map<string, ClientUrlProjection>();
@@ -59,6 +71,15 @@ export type ClientUrlDefinitionSource = ClientUrlReference | ClientUrlPatterns;
 export interface ClientUrlProjectionOptions {
   readonly search?: Readonly<Record<string, SearchSchemaValue>>;
   readonly trailingSlash?: TrailingSlashMode;
+  /**
+   * The `ppr` path option, JSON-projected. Materialization passes it onto
+   * the group route's server `path()` verbatim, so the manifest entry
+   * carries it and the runtime shell capture/serve lanes engage exactly as
+   * for a hand-written server route (search is part of shell identity —
+   * the capture render seeds the key's own search, so group static parts
+   * may read useSearchParams).
+   */
+  readonly ppr?: true | Readonly<PartialPrerenderProps>;
 }
 
 export interface ClientUrlProjectionRoute {
@@ -138,9 +159,6 @@ function serializeOptions(
   if (!source) return Object.freeze({});
 
   for (const key of Reflect.ownKeys(source)) {
-    if (key === "ppr") {
-      throw projectionError(route, 'path option "ppr" is not supported');
-    }
     if (!PROJECTION_OPTIONS.has(key)) {
       throw projectionError(
         route,
@@ -152,6 +170,7 @@ function serializeOptions(
   const options: {
     search?: Readonly<Record<string, SearchSchemaValue>>;
     trailingSlash?: TrailingSlashMode;
+    ppr?: true | Readonly<PartialPrerenderProps>;
   } = {};
   if (source.search !== undefined) {
     options.search = serializeSearchSchema(route, source.search);
@@ -159,9 +178,72 @@ function serializeOptions(
   if (source.trailingSlash !== undefined) {
     options.trailingSlash = source.trailingSlash;
   }
+  if (source.ppr !== undefined) {
+    options.ppr = serializePpr(route, source.ppr);
+  }
   return Object.freeze(options);
 }
 
+/**
+ * Serialize the `ppr` path option for the projection. The DSL already
+ * validated shape in the authoring module (validateClientPpr in
+ * client-urls.ts); this re-validates independently and re-copies
+ * defensively — the projection must carry only JSON, and the copy keeps a
+ * later mutation of the consumer's options object from leaking into the
+ * frozen projection.
+ */
+function serializePpr(
+  route: ClientUrlRouteRecord,
+  source: unknown,
+): true | Readonly<PartialPrerenderProps> {
+  if (source === true) return true;
+  if (typeof source !== "object" || source === null || Array.isArray(source)) {
+    throw projectionError(
+      route,
+      'path option "ppr" must be true or a PartialPrerenderProps object',
+    );
+  }
+  const out: {
+    ttl?: number;
+    swr?: number;
+    captureTimeout?: number;
+    maxSnapshotBytes?: number;
+    tags?: readonly string[];
+  } = {};
+  for (const key of Reflect.ownKeys(source)) {
+    if (PPR_NUMBER_KEYS.has(key)) {
+      const value = (source as Record<PropertyKey, unknown>)[key];
+      if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw projectionError(
+          route,
+          `path option "ppr.${String(key)}" must be a finite number`,
+        );
+      }
+      out[key as "ttl" | "swr" | "captureTimeout" | "maxSnapshotBytes"] = value;
+      continue;
+    }
+    if (key === "tags") {
+      const tags = (source as { tags: unknown }).tags;
+      if (
+        !Array.isArray(tags) ||
+        tags.some((tag) => typeof tag !== "string" || tag === "")
+      ) {
+        throw projectionError(
+          route,
+          'path option "ppr.tags" must be an array of non-empty strings',
+        );
+      }
+      out.tags = Object.freeze([...tags]);
+      continue;
+    }
+    throw projectionError(
+      route,
+      `path option "ppr.${String(key)}" is not supported`,
+    );
+  }
+  return Object.freeze(out) as Readonly<PartialPrerenderProps>;
+}
+
 function serializeTransition(
   route: ClientUrlRouteRecord,
 ): Readonly<ClientTransitionConfig> | undefined {
@@ -393,6 +475,15 @@ function materializedPathOptions(route: ClientUrlProjectionRoute): PathOptions {
     ...(route.options.trailingSlash
       ? { trailingSlash: route.options.trailingSlash }
       : {}),
+    // ppr rides onto the materialized server path() verbatim: path-helper
+    // stamps it on the manifest entry, so resolvePprConfig classifies the
+    // group route exactly like a hand-written ppr page. Shallow-copy the
+    // object form — path-helper receives a mutable PathOptions.
+    ...(route.options.ppr !== undefined
+      ? {
+          ppr: route.options.ppr === true ? true : { ...route.options.ppr },
+        }
+      : {}),
   };
 }
 

package/src/client-urls/types.ts

@@ -28,7 +28,10 @@ export type ClientUrlUse = () => ClientUrlItems;
 export type ClientPathOptions<
   TName extends string = string,
   TSearch extends SearchSchema = SearchSchema,
-> = Pick<PathOptions<TName, TSearch>, "name" | "search" | "trailingSlash">;
+> = Pick<
+  PathOptions<TName, TSearch>,
+  "name" | "search" | "trailingSlash" | "ppr"
+>;
 
 export type ClientPathFn = <
   const TPattern extends string,
@@ -141,7 +144,10 @@ export interface ClientUrlHelpers {
    * Pass `{ stream: "navigation" }` to await this loader before first flush
    * on DOCUMENT requests (see {@link LoaderOptions}) — the opt-in for loaders
    * whose data, handle pushes, or thrown notFound()/redirect() must be in the
-   * SSR'd HTML. Per-loader: a dynamic sibling keeps streaming.
+   * SSR'd HTML. Per-loader: a dynamic sibling keeps streaming. Under a
+   * `ppr` group route the flag BAKES: the loader executes at shell capture
+   * and its settled return freezes into the shell (nested promises stay
+   * live holes).
    */
   readonly loader: <TData>(
     definition: LoaderDefinition<TData>,

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

@@ -148,7 +148,13 @@ export async function resolveLoaders<TEnv>(
               loaderEntry,
               ctx,
               ctx.pathname,
-              bakeLane ? segmentId : null,
+              // The bake key rides for flagged loaders too: stream:"navigation"
+              // bakes at capture regardless of the entry's loading() lane
+              // (loader-cache.ts capture branch) and its HIT-tail seed
+              // overlay needs the same key.
+              bakeLane || loaderEntry.awaitBeforeFlush === true
+                ? segmentId
+                : null,
             ),
           ),
           entry,
@@ -191,7 +197,7 @@ export async function resolveLoaders<TEnv>(
           loaderEntry,
           ctx,
           ctx.pathname,
-          bakeLane ? segmentId : null,
+          bakeLane || loaderEntry.awaitBeforeFlush === true ? segmentId : null,
         ),
       ),
       entry,

package/src/router/segment-resolution/loader-cache.ts

@@ -157,19 +157,40 @@ export function resolveLoaderData<TEnv>(
   //   shell HIT the recorded container is overlaid onto the fresh run so the
   //   payload matches the frozen prelude byte-for-byte.
   if (isShellCaptureActive(reqCtx)) {
-    // EXPERIMENT (streaming useLoader, feat/useloader-suspense): route
-    // loaders are LIVE at capture UNCONDITIONALLY — the loading()-keyed lane
-    // trigger is suspended on this branch. Read-site suspension postpones
-    // each masked stream at the consumer's own Suspense boundary, so holes
-    // no longer require a route-level loading(); baking route data into a
-    // shell is expressed via cache()/"use cache", not by omitting loading().
-    // The former bake-at-capture path (execute + nested-thenable mask +
-    // snapshot pinning via _shellCaptureLoaderRecords, see git history) is
-    // bypassed: with no records registered the serve-side seed overlay is a
-    // no-op and every HIT runs loaders fresh. A masked reader with NO
-    // Suspense above it root-postpones and the capture's <body> sanity gate
-    // refuses the shell (runtime render + eternal-MISS warning), which is
-    // the intended degrade for boundary-less ppr routes.
+    // Capture lane, per LOADER (not per entry):
+    //
+    // - `stream: "navigation"` (awaitBeforeFlush) — the BAKE lane. The flag's
+    //   document promise is "this loader's data is in the HTML before first
+    //   flush"; under ppr the pre-flush HTML IS the frozen prelude, so the
+    //   loader executes at capture and its SETTLED return bakes into the
+    //   shell. Nested-promise SHAPE stays the liveness declaration: nested
+    //   thenables are masked so their subtrees postpone as holes (per-request
+    //   material must be promise-shaped — the #692 cross-session scar). The
+    //   masked container registers on _shellCaptureLoaderRecords: it holds
+    //   the capture gate (bounded by ppr.captureTimeout) and pins into the
+    //   shell snapshot, so a HIT tail replays the baked value and the
+    //   hydration payload matches the frozen prelude byte-for-byte.
+    // - Every other loader — LIVE unconditionally: masked with a
+    //   never-resolving promise, postponed at its boundary (loading() or an
+    //   inline Suspense), streamed fresh per request. A masked reader with NO
+    //   boundary above it root-postpones and the <body> sanity gate refuses
+    //   the shell (eternal-MISS warning) — the degrade for boundary-less ppr
+    //   routes. A route whose loaders are ALL flagged therefore needs no
+    //   loading() at all: nothing masks, the shell captures complete.
+    if (loaderEntry.awaitBeforeFlush && bakeSegmentKey) {
+      const containerPromise = executeLoaderData(loaderEntry, ctx, pathname);
+      // Pre-attach a no-op catch: a bake-lane rejection during capture must
+      // surface through the drain's refusal (and the wrapper's error
+      // boundary), never as an unhandled rejection that can kill the worker
+      // before the drain probes this record.
+      containerPromise.catch(() => {});
+      const maskedPromise = containerPromise.then((container: unknown) =>
+        maskNestedContainerThenables(container),
+      );
+      maskedPromise.catch(() => {});
+      reqCtx?._shellCaptureLoaderRecords?.set(bakeSegmentKey, maskedPromise);
+      return maskedPromise;
+    }
     return createMaskedLoaderPromise();
   }
 

package/src/router/segment-resolution/loader-mask.ts

@@ -42,15 +42,15 @@ export function isShellCaptureActive(
 export { createMaskedLoaderPromise } from "./mask-nested.js";
 
 /**
- * Lane decision for an entry's loaders under PPR (the loading() value decides;
- * docs/design/loader-container-bake.md):
- *
- * - RENDERABLE loading() (the LoaderBoundary Suspense fallback) — the LIVE
- *   lane: masked at capture, guaranteed fresh on every serve. Returns true.
- * - No loading() (absent, or explicitly `false`, incl. `loading(x, { ssr:
- *   false })` under the SSR manifest) — the BAKE lane: the loader executes
- *   during capture, its settled container bakes, nested pending promises hole
- *   at the consumer's own Suspense. Returns false.
+ * Entry-level lane input for an entry's loaders under PPR (the loading()
+ * value; docs/design/loader-container-bake.md). The CAPTURE decision itself
+ * is per LOADER in loader-cache.ts: a `stream: "navigation"`
+ * (awaitBeforeFlush) loader BAKES at capture regardless of this value — the
+ * flag's document promise ("data in the HTML before first flush") maps to
+ * the frozen prelude — while every other loader is LIVE (masked at capture,
+ * fresh on every serve), postponing at loading() or an inline Suspense.
+ * This helper still gates which entries pass a bake segment key for the
+ * legacy loading()-less shape and the HIT-tail seed overlay.
  *
  * Mirrors segment-system's isRenderableLoading so the mask decision and the
  * tree's boundary placement can never disagree.

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

@@ -240,7 +240,9 @@ export async function resolveLoadersWithRevalidation<TEnv>(
             loaderEntry,
             ctx,
             ctx.pathname,
-            bakeLane ? segmentId : null,
+            bakeLane || loaderEntry.awaitBeforeFlush === true
+              ? segmentId
+              : null,
           ),
         ),
         entry,

package/src/urls/path-helper-types.ts

@@ -350,7 +350,10 @@ export type PathHelpers<TEnv> = {
    * Pass `{ stream: "navigation" }` to await this loader before first flush
    * on DOCUMENT requests (see {@link LoaderOptions}) — the opt-in for loaders
    * whose data, handle pushes, or thrown notFound()/redirect() must be in the
-   * SSR'd HTML. Per-loader: a dynamic sibling keeps streaming.
+   * SSR'd HTML. Per-loader: a dynamic sibling keeps streaming. Under a
+   * `ppr` route the flag BAKES: the loader executes at shell capture and
+   * its settled return freezes into the shell (nested promises stay live
+   * holes) — the pre-flush promise applied to the prelude.
    */
   loader: <TData>(
     loaderDef: LoaderDefinition<TData>,