@rangojs/router 0.1.0 → 0.2.0

package/src/rsc/shell-capture.ts

@@ -476,6 +476,8 @@ export interface ShellCaptureDebugEvent {
   snapshotBytes?: number;
   /** True when the snapshot exceeded maxSnapshotBytes and was dropped. */
   snapshotSkipped?: boolean;
+  /** Outcome reported by a store that supports shell-write acknowledgements. */
+  storeWrite?: "stored" | "invalidated";
   /** 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. */
@@ -516,6 +518,9 @@ export function describeShellCaptureEvent(
       `snapshot=${event.snapshotBytes}b${event.snapshotSkipped ? " (over cap, skipped)" : ""}`,
     );
   }
+  if (event.storeWrite !== undefined) {
+    parts.push(`store-write=${event.storeWrite}`);
+  }
   if (event.backoffFailures !== undefined) {
     parts.push(`backoff-failures=${event.backoffFailures}`);
   }
@@ -941,13 +946,15 @@ type CaptureAttemptOutcome = "stored" | "redirect" | "no-shell" | "refused";
  * bag, not a return value: captureAndStoreShell's outcome type stays a string
  * union its existing callers (producer B, tests) consume unchanged.
  */
-interface CaptureAttemptStats {
-  barrierWaitMs?: number;
-  writeSettleMs?: number;
-  preludeBytes?: number;
-  snapshotBytes?: number;
-  snapshotSkipped?: boolean;
-}
+type CaptureAttemptStats = Pick<
+  ShellCaptureDebugEvent,
+  | "barrierWaitMs"
+  | "writeSettleMs"
+  | "preludeBytes"
+  | "snapshotBytes"
+  | "snapshotSkipped"
+  | "storeWrite"
+>;
 
 /**
  * Run the shell capture with a single in-place retry, then store the result.
@@ -1116,6 +1123,7 @@ async function attemptCapture(
     reqCtx,
     descriptor,
   );
+  const captureStartedAt = Date.now();
 
   return runWithRequestContext(derivedCtx, async () => {
     const match = await ctx.router.match(request, { env });
@@ -1157,6 +1165,7 @@ async function attemptCapture(
       derivedCtx,
       descriptor,
       stats,
+      captureStartedAt,
     );
   });
 }
@@ -1329,6 +1338,7 @@ export function deriveShellCaptureContext(
       ttl: descriptor.ttl,
       swr: descriptor.swr,
       store: new SnapshotOnlySegmentStore(recordingStore),
+      keyPrefix: "doc",
     };
   }
 
@@ -1355,6 +1365,7 @@ async function captureAndStoreShell(
   reqCtx: RequestContext<any>,
   capture: ShellCaptureDescriptor,
   stats?: CaptureAttemptStats,
+  captureStartedAt: number = Date.now(),
 ): Promise<Exclude<CaptureAttemptOutcome, "redirect">> {
   const captureShellHTML = ssrModule.captureShellHTML!;
 
@@ -1661,15 +1672,26 @@ async function captureAndStoreShell(
           handlerLiveHoles: handlerLayerIsLive(
             reqCtx._shellCaptureHandleLiveness,
           ),
-          createdAt: Date.now(),
+          transitionWhen: reqCtx._transitionWhen?.length ? true : undefined,
+          createdAt: captureStartedAt,
         };
-        await store.putShell(
+        const storeWrite = await store.putShell(
           capture.key,
           entry,
           capture.ttl,
           capture.swr,
           shellTags,
         );
+        if (stats && storeWrite) stats.storeWrite = storeWrite;
+        if (storeWrite === "invalidated") {
+          warnCaptureRefusedOnce(
+            capture.key,
+            "one of the shell's tags was invalidated after this capture generation started, so the store rejected the write. " +
+              "If capture code deterministically calls updateTag() on its own shell tag, move that mutation out of the render; " +
+              "otherwise every generation is invalidated before it can be served.",
+          );
+          return "refused";
+        }
       } catch (error) {
         // Best-effort: a failed put must never throw out of the background task.
         reportCacheError(
@@ -1680,8 +1702,9 @@ async function captureAndStoreShell(
         );
       }
     }
-    // A shell was captured (the store I/O may have failed, but that is reported,
-    // not retried) — so this attempt is `stored` and the caller does not retry.
+    // A shell was captured (ordinary store I/O failure is reported, not retried).
+    // An acknowledged invalidation rejection returned `refused` above so the
+    // scheduler backs the key off instead of recapturing on every request.
     return "stored";
   } finally {
     // Stop the hop loop for the pathological never-quiets path (quiesce never

package/src/rsc/shell-serve.ts

@@ -24,6 +24,9 @@ import type { ShellCacheEntry, SegmentCacheStore } from "../cache/types.js";
 /** Debug/status header the browser (and e2e assertions) can read: HIT | MISS. */
 export const SHELL_STATUS_HEADER = "x-rango-shell";
 
+/** Partial-navigation status header set only after captured PPR segments are consumed. */
+export const PPR_REPLAY_STATUS_HEADER = "x-rango-ppr-replay";
+
 /**
  * Default shell ttl (seconds) for `ppr: true` and for a PartialPrerenderProps
  * that omits `ttl`.

package/src/rsc/transition-gate.ts

@@ -1,41 +1,58 @@
 import type { MatchResult } from "../types.js";
-import type { TransitionWhenContext } from "../types/segments.js";
 import type { getRequestContext } from "../server/request-context.js";
 import { invokeOnError } from "../router/error-handling.js";
 import type { OnErrorCallback } from "../types/error-types.js";
+import { createTransitionWhenContext } from "../router/transition-when.js";
 
 /**
  * Apply transition({ when }) gates to a payload's segments.
  *
- * The predicates were collected during resolution (keyed by segment id) and
- * stripped from the serialized config; here — after handlers ran and outside any
- * cache scope — we evaluate each and drop the segment's transition when the
- * predicate does not hold, so the navigation streams its loading fallback
- * instead of holding the previous content. A predicate that throws is reported
- * to the router's onError (phase "rendering") and then treated as "do not hold"
- * (conservative), so a buggy predicate degrades to no transition rather than
- * failing the response.
+ * PPR predicates were evaluated from the manifest before cache lookup and route
+ * handlers; their request-specific decisions are projected onto a copy so they
+ * never mutate reusable cache/prerender/shell records. Ordinary-route predicates
+ * were collected during fresh resolution and are evaluated here after handlers.
+ * Both paths drop the segment transition when the predicate does not hold.
  *
  * Mutating the segments here is safe: the segment cache stores a serialized copy
  * (segment-codec), written during match() BEFORE this gate runs, so dropping a
- * transition never corrupts a cache entry. The flip side is that a cache hit
+ * transition never corrupts a cache entry. On an ordinary route, a cache hit
  * skips resolution, collects no predicate, and replays the cached transition
- * as-is (it was serialized before the gate) — combining transition({ when })
- * with cache() on the same segment freezes the gate to its cached state, so
- * avoid caching a route whose transition decision is request-dependent.
+ * as-is (it was serialized before the gate). PPR routes are the exception: their
+ * manifest predicates were evaluated before lookup and apply to replayed data.
  *
- * Returns the same array (mutated) for inline use at the payload's `segments`
- * field.
+ * Returns the same array for the ordinary post-handler path. A PPR drop returns a
+ * copy containing only the request-specific transition changes.
  */
 export function gateTransitions(
   segments: MatchResult["segments"],
   ctx: ReturnType<typeof getRequestContext>,
   onError?: OnErrorCallback,
 ): MatchResult["segments"] {
+  const pprDecisions = ctx._pprTransitionDecisions;
+  let gatedSegments = segments;
+
+  const dropTransition = (id: string): void => {
+    const index = gatedSegments.findIndex((segment) => segment.id === id);
+    if (index === -1) return;
+    if (!pprDecisions) {
+      gatedSegments[index].transition = undefined;
+      return;
+    }
+    if (gatedSegments === segments) gatedSegments = [...segments];
+    gatedSegments[index] = {
+      ...gatedSegments[index],
+      transition: undefined,
+    };
+  };
+
+  if (pprDecisions) {
+    for (const [id, keep] of pprDecisions) {
+      if (!keep) dropTransition(id);
+    }
+  }
   const predicates = ctx._transitionWhen;
-  if (predicates && predicates.length) {
+  if (predicates) {
     for (const { id, when } of predicates) {
-      let drop: boolean;
       try {
         // Assemble the ShouldRevalidateFn-shaped predicate context from the
         // request context. Source fields (currentUrl/currentParams/fromRouteName)
@@ -44,28 +61,11 @@ export function gateTransitions(
         // method/get/env come straight off ctx (setRequestContextParams ran
         // before the gate). Source/action fields are undefined when absent —
         // never fabricated (see TransitionWhenContext).
-        const whenCtx: TransitionWhenContext = {
-          currentUrl: ctx._gateCurrentUrl,
-          currentParams: ctx._gateCurrentParams,
-          fromRouteName:
-            ctx._prevRouteKey as TransitionWhenContext["fromRouteName"],
-          nextUrl: ctx.url,
-          nextParams: ctx.params,
-          toRouteName: ctx.routeName,
-          actionId: ctx._gateActionId,
-          actionUrl: ctx._gateActionUrl,
-          actionResult: ctx._gateActionResult,
-          formData: ctx._gateFormData,
-          method: ctx.request.method,
-          get: ctx.get,
-          env: ctx.env,
-        };
-        drop = when(whenCtx) === false;
+        if (when(createTransitionWhenContext(ctx)) !== false) continue;
       } catch (error) {
         // A throwing predicate must not fail the response: report it and treat
         // the transition as gated off (do not hold). invokeOnError no-ops when
         // onError is undefined.
-        drop = true;
         invokeOnError(
           onError,
           error,
@@ -79,11 +79,8 @@ export function gateTransitions(
           "RSC",
         );
       }
-      if (drop) {
-        const seg = segments.find((s) => s.id === id);
-        if (seg) seg.transition = undefined;
-      }
+      dropTransition(id);
     }
   }
-  return segments;
+  return gatedSegments;
 }

package/src/rsc/types.ts

@@ -41,6 +41,8 @@ export interface RscPayload {
     handles?: AsyncGenerator<HandleData, void, unknown>;
     /** RSC version string for cache invalidation */
     version?: string;
+    /** Cloudflare dev worker generation used for stale-document convergence. */
+    devDiscoveryEpoch?: number;
     /** TTL in milliseconds for the client-side in-memory prefetch cache */
     prefetchCacheTTL?: number;
     /** Max entries in the client-side in-memory prefetch cache (FIFO eviction) */

package/src/server/context.ts

@@ -298,6 +298,10 @@ interface HelperContext {
   counters: Record<string, number>;
   forRoute?: string;
   mountIndex?: number;
+  /** Owning router id, when known (threaded by generateManifestFull). Scopes
+   *  the search-schema/root-scope registries so same-named routes in
+   *  different routers don't clobber each other (route-map-builder.ts). */
+  routerId?: string;
   metrics?: MetricsStore;
   /** True when rendering for SSR (document requests) */
   isSSR?: boolean;
@@ -491,6 +495,7 @@ export const getContext = (): {
           counters: store.counters,
           forRoute: store.forRoute,
           mountIndex: store.mountIndex,
+          routerId: store.routerId,
           metrics: store.metrics,
           isSSR: store.isSSR,
           patterns: store.patterns,
@@ -533,6 +538,7 @@ export const getContext = (): {
           counters,
           forRoute: store?.forRoute,
           mountIndex: store?.mountIndex,
+          routerId: store?.routerId,
           metrics: store?.metrics,
           isSSR: store?.isSSR,
           patterns,
@@ -666,6 +672,28 @@ export function getRootScoped(): boolean {
   return store?.rootScoped ?? true;
 }
 
+/**
+ * Stamp build-time scope identity onto a Static() definition at mount time.
+ * The bake collector (prerender-collection.ts) renders defs OUTSIDE any
+ * evaluation scope and used to iterate the registry first-non-null, so these
+ * are the ONLY reliable carriers of the def's owning router, root-scope, and
+ * full route name — a name-keyed registry lookup at bake time reproduces the
+ * cross-router collision #757/#762 fixed (and the collector's historical
+ * `$$routePrefix` argument is a name PREFIX, which the root-scope registry
+ * never contains, silently degrading to the dot-heuristic).
+ * A definition mounted more than once is stamped each time; the last mount wins.
+ */
+export function stampStaticDefScope(
+  handler: unknown,
+  routeName?: string,
+): void {
+  const store = RangoContext.getStore();
+  const def = handler as Record<string, unknown>;
+  if (routeName !== undefined) def.$$routeName = routeName;
+  def.$$rootScoped = getRootScoped();
+  if (store?.routerId !== undefined) def.$$routerId = store.routerId;
+}
+
 // Export HelperContext type for use in other modules
 export type { HelperContext };
 

package/src/server/request-context.ts

@@ -208,6 +208,9 @@ export interface RequestContext<
    */
   _transitionWhen?: Array<{ id: string; when: TransitionWhenFn }>;
 
+  /** @internal PPR transition decisions evaluated before cache lookup/handlers. */
+  _pprTransitionDecisions?: Map<string, boolean>;
+
   /** @internal Cache store for segment caching (optional, used by CacheScope) */
   _cacheStore?: SegmentCacheStore;
 
@@ -254,21 +257,30 @@ export interface RequestContext<
   >;
 
   /**
-   * @internal Shell fast-path marker: makes the NEXT full match treat the whole
-   * matched route as an implicit doc-level cache() boundary (see
+   * @internal Shell fast-path marker: makes the next eligible match treat the
+   * whole matched route as an implicit doc-level cache() boundary (see
    * resolveShellImplicitCacheScope in cache/cache-scope.ts). Set ONLY on
    * (a) the capture's derived context — with a record-only store so the
    * capture's cacheRoute write lands in the snapshot, never the real store —
-   * and (b) a HIT tail's seeded context when the entry is eligible
-   * (!handlerLiveHoles), where the SeededShellStore serves the recorded doc
-   * entry and the match skips handler execution entirely. Routes with their
-   * own cache() config (including cache(false)) are never overridden: the
-   * marker only applies when the route tree derived NO cache scope.
+   * (b) a HIT tail's seeded context, and (c) an eligible normal-route partial
+   * replay, where `store` is a request-local segment overlay. Handler-live holes
+   * and conditional transitions decline replay.
+   * Routes with their own cache() config (including cache(false)) are never
+   * overridden: the marker only applies when the route tree derived NO cache
+   * scope.
    */
   _shellImplicitCache?: {
     ttl?: number;
     swr?: number;
     store?: SegmentCacheStore;
+    /**
+     * @internal Override the implicit scope's default cache namespace. Shell
+     * captures and navigation replay both consume the canonical document
+     * segment record even when the triggering request is partial.
+     */
+    keyPrefix?: "doc";
+    /** @internal Called only after the implicit cache hit decodes successfully. */
+    onHit?: () => void;
   };
 
   /**
@@ -606,6 +618,10 @@ export interface RequestContext<
   /** @internal Router basename for this request (used by redirect()) */
   _basename?: string;
 
+  /** @internal Owning router id; scopes the search-schema/root-scope registry
+   *  lookups per router (route-map-builder.ts) */
+  _routerId?: string;
+
   /**
    * @internal RouteSnapshot from classifyRequest, reused by match/matchPartial
    * to avoid a second resolveRoute call. Cleared on HMR invalidation.
@@ -639,14 +655,22 @@ export type PublicRequestContext<
   | "deleteCookie"
   | "_handleStore"
   | "_transitionWhen"
+  | "_pprTransitionDecisions"
   | "_cacheStore"
   | "_shellCaptureRun"
+  | "_shellImplicitCache"
+  | "_shellLoaderSeed"
+  | "_shellCaptureLoaderRecords"
+  | "_shellCaptureHandleLiveness"
+  | "_shellCaptureLoaderHandleValues"
   | "_shellFragmentPayload"
+  | "_shellCaptureGuardTripped"
   | "_shellCaptureGuardTrippedLoaderId"
   | "_explicitTaggedStores"
   | "_requestTags"
   | "_cacheProfiles"
   | "_onResponseCallbacks"
+  | "_pendingBackgroundTasks"
   | "_themeConfig"
   | "_locationState"
   | "_routeName"
@@ -673,7 +697,9 @@ export type PublicRequestContext<
   | "_renderForeground"
   | "_renderDiagnosticsEnabled"
   | "_handlerStart"
+  | "_tracing"
   | "_basename"
+  | "_routerId"
   | "_setStatus"
   | "_rotateStateCookie"
   | "_setKeepCacheDirective"
@@ -765,7 +791,7 @@ export function setRequestContextParams(
       routeMap ?? getGlobalRouteMap(),
       routeName,
       params,
-      routeName ? isRouteRootScoped(routeName) : undefined,
+      routeName ? isRouteRootScoped(routeName, ctx._routerId) : undefined,
     );
   }
 }
@@ -1496,7 +1522,7 @@ export function createUseFunction<TEnv>(
     // RequestContext carries no `search` field, so reading `(ctx as any).search`
     // here always yielded {} — dropping typed search for action/dispatch loaders.
     const searchSchema = ctx._routeName
-      ? getSearchSchema(ctx._routeName)
+      ? getSearchSchema(ctx._routeName, ctx._routerId)
       : undefined;
     const loaderSearch = searchSchema
       ? parseSearchParams(ctx.searchParams, searchSchema)
@@ -1526,7 +1552,9 @@ export function createUseFunction<TEnv>(
         getGlobalRouteMap(),
         ctx._routeName,
         ctx.params as Record<string, string>,
-        ctx._routeName ? isRouteRootScoped(ctx._routeName) : undefined,
+        ctx._routeName
+          ? isRouteRootScoped(ctx._routeName, ctx._routerId)
+          : undefined,
       ),
       rendered: () => {
         throw new Error(

package/src/server.ts

@@ -25,8 +25,6 @@ export {
   clearAllRouterData,
   getGlobalRouteMap,
   getRouterManifest,
-  setPrecomputedEntries,
-  setRouteTrie,
   setManifestReadyPromise,
   setRouterManifest,
   setRouterTrie,

package/src/testing/dispatch.ts

@@ -413,6 +413,7 @@ export async function dispatch<TEnv = any>(
   // with it. Mirror it so basename-redirect tests behave as they do in a real
   // mounted app instead of always seeing no prefix.
   requestContext._basename = router.basename;
+  requestContext._routerId = routerId;
 
   // Match production's response-route reverse EXACTLY: the real handler builds
   // it from the route map alone (response-route-handler.ts), with NO matched

package/src/testing/e2e/index.ts

@@ -41,10 +41,15 @@ export {
   type CacheStatusTarget,
 } from "../cache-status.js";
 export {
+  assertPprReplayStatus,
   assertShellStatus,
+  parsePprReplayStatus,
   parseShellStatus,
+  PPR_REPLAY_STATUS_HEADER,
   shellCacheKey,
   SHELL_STATUS_HEADER,
+  type PprReplayBypassReason,
+  type PprReplayStatus,
   type ShellStatus,
   type ShellStatusTarget,
 } from "../shell-status.js";

package/src/testing/index.ts

@@ -77,12 +77,20 @@ export type {
 } from "../router/telemetry.js";
 
 export {
+  assertPprReplayStatus,
   assertShellStatus,
+  parsePprReplayStatus,
   parseShellStatus,
+  PPR_REPLAY_STATUS_HEADER,
   shellCacheKey,
   SHELL_STATUS_HEADER,
 } from "./shell-status.js";
-export type { ShellStatus, ShellStatusTarget } from "./shell-status.js";
+export type {
+  PprReplayBypassReason,
+  PprReplayStatus,
+  ShellStatus,
+  ShellStatusTarget,
+} from "./shell-status.js";
 
 export { collectHandle } from "./collect-handle.js";
 

package/src/testing/run-transition-when.ts

@@ -1,10 +1,9 @@
 /**
  * runTransitionWhen — unit-test a transition({ when }) predicate in isolation.
  *
- * Runs the SAME two server functions the router uses — applyViewTransitionDefault
- * (strips the `when` function from the serialized config and records the
- * predicate on the request context) and gateTransitions (assembles the
- * TransitionWhenContext and evaluates the predicate post-handler). So the
+ * Runs the SAME server functions the router uses — the PPR pre-handler evaluator
+ * when `ppr: true`, applyViewTransitionDefault (which strips the server-only
+ * function), and gateTransitions. So the
  * predicate sees exactly the navigation/action metadata it would at runtime
  * (currentUrl/currentParams/fromRouteName, nextUrl/nextParams/toRouteName,
  * actionId/actionUrl/actionResult/formData/method, get/env), and `kept` reflects
@@ -33,6 +32,9 @@ import type {
   TransitionWhenContext,
 } from "../types/segments.js";
 import type { OnErrorCallback } from "../types/error-types.js";
+import type { EntryData } from "../server/context.js";
+import { evaluatePprTransitionWhen } from "../router/transition-when.js";
+import { invokeOnError } from "../router/error-handling.js";
 
 const toURL = (v: string | URL, base: URL): URL =>
   typeof v === "string" ? new URL(v, base.origin) : v;
@@ -53,7 +55,7 @@ export interface RunTransitionWhenOptions<TEnv = any> {
   toRouteName?: string;
   /** Environment bindings surfaced as `env` (and `ctx.env`). */
   env?: TEnv;
-  /** Variables a handler/middleware would have set this request, readable via the predicate's `get()`. */
+  /** Variables readable via the predicate's `get()`. With `ppr`, these model pre-handler middleware/input state. */
   vars?: VarsInit;
   /** Navigation SOURCE url (`currentUrl`): a URL or path string. */
   currentUrl?: string | URL;
@@ -71,6 +73,8 @@ export interface RunTransitionWhenOptions<TEnv = any> {
   formData?: FormData;
   /** Receives an error thrown by the predicate (the gate reports to `router.onError`, phase `"rendering"`). */
   onError?: OnErrorCallback;
+  /** Model a route with `ppr`, where the predicate runs before route handlers and cache lookup. */
+  ppr?: boolean;
 }
 
 /**
@@ -138,8 +142,37 @@ export function runTransitionWhen<TEnv = any>(
     : config;
 
   return runWithRequestContext(reqCtx, () => {
-    // The real resolution-time collection + post-handler gate, so the predicate
-    // sees the production-assembled TransitionWhenContext.
+    if (opts.ppr) {
+      const entry = {
+        type: "route",
+        id: "tx-when-entry",
+        shortCode: "tx-when-seg",
+        parent: null,
+        transition: configForGate,
+        layout: [],
+        parallel: {},
+      } as unknown as EntryData;
+      evaluatePprTransitionWhen(
+        [entry],
+        reqCtx,
+        { params: reqCtx.params, routeName: opts.toRouteName },
+        (error, segmentId) =>
+          invokeOnError(
+            opts.onError,
+            error,
+            "rendering",
+            {
+              request: reqCtx.request,
+              url: reqCtx.url,
+              params: reqCtx.params,
+              segmentId,
+            },
+            "RSC",
+          ),
+      );
+    }
+    // Ordinary predicates are collected here and evaluated by the gate. PPR
+    // predicates keep the decision already evaluated before this step.
     const serialized = applyViewTransitionDefault(
       configForGate,
       undefined,
@@ -153,12 +186,12 @@ export function runTransitionWhen<TEnv = any>(
       component: null,
       transition: serialized,
     } as ResolvedSegment;
-    gateTransitions(
+    const [gatedSegment] = gateTransitions(
       [segment],
       reqCtx as Parameters<typeof gateTransitions>[1],
       opts.onError,
     );
-    const kept = segment.transition !== undefined;
+    const kept = gatedSegment.transition !== undefined;
     return { kept, dropped: !kept, whenContext, ctx: reqCtx };
   });
 }