@rangojs/router 0.6.0 → 0.8.0

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/rsc/shell-build-manifest.ts

@@ -306,20 +306,27 @@ export async function lookupBuildShell(
     const entry = record.entry;
     if (record.tags && record.tags.length > 0) {
       const check = store.isTagsInvalidatedSince;
-      if (typeof check !== "function") {
+      if (typeof check !== "function" || store.tagHistoryInert) {
         // A tagged build entry on a store that cannot answer "was this tag
         // invalidated since the build" must not serve: updateTag() could
-        // never evict it. Declared intent that cannot be honored deserves a
+        // never evict it. That covers a store missing the method AND one
+        // whose answers have no durable history behind them
+        // (SegmentCacheStore.tagHistoryInert — a KV-less CFCacheStore's
+        // memo-only answers would let the immutable asset resurrect on the
+        // next request). Declared intent that cannot be honored deserves a
         // diagnostic; the route keeps runtime-capture semantics.
         const key = buildShellManifestKey(url.pathname);
         if (!warnedTagCheckUnsupported.has(key)) {
           warnedTagCheckUnsupported.add(key);
           console.warn(
             `[rango] Build-time shell for "${url.pathname}" carries cache tags, but ` +
-              "the app cache store does not implement isTagsInvalidatedSince(), so " +
-              "updateTag() could not evict it. The entry is not served; the route " +
-              "keeps runtime shell capture. Use MemorySegmentCacheStore, CFCacheStore, " +
-              "or VercelCacheStore (or add the method to your custom store).",
+              "the app cache store cannot answer tag-invalidation history durably " +
+              (typeof check !== "function"
+                ? "(isTagsInvalidatedSince() is not implemented), "
+                : "(no durable tag history — a CFCacheStore without a KV namespace), ") +
+              "so updateTag() could not evict it. The entry is not served; the route " +
+              "keeps runtime shell capture. Use MemorySegmentCacheStore, a KV-backed " +
+              "CFCacheStore, or VercelCacheStore (or add the method to your custom store).",
           );
         }
         return null;

package/src/rsc/shell-capture.ts

@@ -509,9 +509,10 @@ export interface ShellCaptureDebugEvent {
    *   the capture was not attempted
    * - skip-capacity: the isolate capture queue is full; a later request may retry
    * - skip-inert-store: the resolved store's shell family is missing or
-   *   declared inert (SegmentCacheStore.shellFamilyInert — a CFCacheStore
-   *   without a KV namespace); nothing could store the result, so the
-   *   background render was not scheduled at all
+   *   declared inert (SegmentCacheStore.shellFamilyInert — a custom store
+   *   whose backing tier is unavailable; built-in stores never declare it);
+   *   nothing could store the result, so the background render was not
+   *   scheduled at all
    * - skip-queue-timeout: the capture waited past CAPTURE_QUEUE_WAIT_BUDGET_MS
    *   behind other captures and was dropped unrun (no backoff — the route is
    *   not doomed, the isolate was busy; a later request re-probes). Carries
@@ -554,7 +555,7 @@ export interface ShellCaptureDebugEvent {
   /** A bake-lane loader settled into a shell that uses TTL/SWR-only invalidation. */
   untaggedBake?: true;
   /** Outcome reported by a store that supports shell-write acknowledgements. */
-  storeWrite?: "stored" | "invalidated";
+  storeWrite?: "stored" | "invalidated" | "uncacheable";
   /** Consecutive failure count in the key's backoff entry, when one exists. */
   backoffFailures?: number;
   /** Ms remaining in the key's backoff window, when one exists. */
@@ -1005,7 +1006,8 @@ export function scheduleShellCapture(
   // serialized queue (a promise-heavy route bakes for seconds per MISS),
   // starving captures that CAN store. Skip scheduling entirely when the
   // resolved store (same defaulting as captureAndStoreShell) has no shell
-  // family or declared it inert (CFCacheStore without a KV namespace).
+  // family or declared it inert (a custom-store escape hatch; built-in
+  // stores never declare it — a KV-less CFCacheStore stores L1-only).
   const scheduledStore = descriptor.store ?? reqCtx._cacheStore;
   if (!scheduledStore?.putShell || scheduledStore.shellFamilyInert) {
     publishCaptureDebugEvent(descriptor, { key, outcome: "skip-inert-store" });
@@ -2028,6 +2030,21 @@ async function captureAndStoreShell(
           );
           return "refused";
         }
+        if (storeWrite === "uncacheable") {
+          // The store declared the entry unstorable under its current
+          // configuration — every retry would refuse identically, so back
+          // the key off like any refused capture instead of burning a full
+          // serialized render per MISS. Store-neutral on purpose: the
+          // acknowledging store emits its own diagnostic naming the specific
+          // limit (CFCacheStore warns about the over-limit Cache-Tag set).
+          warnCaptureRefusedOnce(
+            capture.key,
+            "the store cannot cache this shell under its current configuration and acknowledged " +
+              "the write as permanently refusable, so the key is backed off. See the cache store's " +
+              "own warning for the specific limit and remedy.",
+          );
+          return "refused";
+        }
       } catch (error) {
         // Best-effort: a failed put must never throw out of the background task.
         reportCacheError(

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>,