@rangojs/router 0.1.0 → 0.2.0

package/src/cache/shell-snapshot.ts

@@ -96,6 +96,9 @@ export class RecordingShellStore<
   get keyGenerator(): SegmentCacheStore<TEnv>["keyGenerator"] {
     return this.inner.keyGenerator;
   }
+  get supportsPassiveShellReads(): true | undefined {
+    return this.inner.supportsPassiveShellReads;
+  }
 
   private record(
     family: ShellSnapshotRecord["family"],
@@ -232,8 +235,9 @@ export class RecordingShellStore<
 
   async getShell(
     key: string,
+    options?: { claimRevalidation?: boolean },
   ): Promise<{ entry: ShellCacheEntry; shouldRevalidate?: boolean } | null> {
-    return this.inner.getShell ? this.inner.getShell(key) : null;
+    return this.inner.getShell ? this.inner.getShell(key, options) : null;
   }
 
   async putShell(
@@ -242,7 +246,7 @@ export class RecordingShellStore<
     ttlSeconds?: number,
     swrSeconds?: number,
     tags?: string[],
-  ): Promise<void> {
+  ): Promise<"stored" | "invalidated" | void> {
     return this.inner.putShell?.(key, entry, ttlSeconds, swrSeconds, tags);
   }
 
@@ -360,28 +364,42 @@ export async function buildShellLoaderSeed(
  * the snapshot it serves the recorded value AS FRESH (shouldRevalidate: false —
  * a pinned key must NOT kick SWR background revalidation) so the tail's payload
  * matches the frozen prelude. Every other read falls through to the real store
- * (the holes — masked loaders were never recorded — stay live). ALL writes pass
- * through unchanged: a live hole's loader may legitimately write. The shell
- * family always passes through.
+ * (the holes — masked loaders were never recorded — stay live). Writes pass
+ * through so a live hole may legitimately write, except that `segmentsOnly`
+ * fully isolates the segment family: misses do not fall through, and writes or
+ * deletes stay local to the navigation overlay. The shell family always passes
+ * through. With `segmentsOnly`, item and response reads also pass through so a
+ * partial navigation cannot freeze captured data or write a partial result into
+ * the canonical document namespace.
  */
 export class SeededShellStore<
   TEnv = unknown,
 > implements SegmentCacheStore<TEnv> {
-  private readonly items = new Map<string, ShellSnapshotItemValue>();
+  private readonly items: Map<string, ShellSnapshotItemValue> | undefined;
   private readonly segments = new Map<string, CachedEntryData>();
-  private readonly responses = new Map<string, ShellSnapshotResponseValue>();
+  private readonly responses:
+    | Map<string, ShellSnapshotResponseValue>
+    | undefined;
+  private readonly segmentsOnly: boolean;
 
   constructor(
     private readonly inner: SegmentCacheStore<TEnv>,
     snapshot: ShellSnapshotRecord[],
+    options?: { segmentsOnly?: boolean },
   ) {
+    this.segmentsOnly = options?.segmentsOnly === true;
+    this.items = this.segmentsOnly ? undefined : new Map();
+    this.responses = this.segmentsOnly ? undefined : new Map();
     for (const rec of snapshot) {
-      if (rec.family === "item") {
-        this.items.set(rec.key, rec.value as ShellSnapshotItemValue);
-      } else if (rec.family === "segment") {
+      if (!rec || typeof rec !== "object") continue;
+      if (rec.family === "segment") {
         this.segments.set(rec.key, rec.value as CachedEntryData);
+      } else if (this.segmentsOnly) {
+        continue;
+      } else if (rec.family === "item") {
+        this.items?.set(rec.key, rec.value as ShellSnapshotItemValue);
       } else if (rec.family === "response") {
-        this.responses.set(rec.key, rec.value as ShellSnapshotResponseValue);
+        this.responses?.set(rec.key, rec.value as ShellSnapshotResponseValue);
       }
       // "loader" family records are not store reads — serveShellHit seeds them
       // onto the tail context (_shellLoaderSeed) for the resolveLoaderData
@@ -395,10 +413,14 @@ export class SeededShellStore<
   get keyGenerator(): SegmentCacheStore<TEnv>["keyGenerator"] {
     return this.inner.keyGenerator;
   }
+  get supportsPassiveShellReads(): true | undefined {
+    return this.inner.supportsPassiveShellReads;
+  }
 
   async get(key: string): Promise<CacheGetResult | null> {
     const seeded = this.segments.get(key);
     if (seeded) return { data: seeded, shouldRevalidate: false };
+    if (this.segmentsOnly) return null;
     return this.inner.get(key);
   }
 
@@ -408,10 +430,17 @@ export class SeededShellStore<
     ttl: number,
     swr?: number,
   ): Promise<void> {
+    if (this.segmentsOnly) {
+      this.segments.set(key, data);
+      return;
+    }
     return this.inner.set(key, data, ttl, swr);
   }
 
   async delete(key: string): Promise<boolean> {
+    if (this.segmentsOnly) {
+      return this.segments.delete(key);
+    }
     return this.inner.delete(key);
   }
 
@@ -422,7 +451,7 @@ export class SeededShellStore<
   async getResponse(
     key: string,
   ): Promise<{ response: Response; shouldRevalidate: boolean } | null> {
-    const seeded = this.responses.get(key);
+    const seeded = this.responses?.get(key);
     if (seeded) {
       return { response: deserializeResponse(seeded), shouldRevalidate: false };
     }
@@ -440,7 +469,7 @@ export class SeededShellStore<
   }
 
   async getItem(key: string): Promise<CacheItemResult | null> {
-    const seeded = this.items.get(key);
+    const seeded = this.items?.get(key);
     if (seeded) {
       return {
         value: seeded.value,
@@ -462,8 +491,9 @@ export class SeededShellStore<
 
   async getShell(
     key: string,
+    options?: { claimRevalidation?: boolean },
   ): Promise<{ entry: ShellCacheEntry; shouldRevalidate?: boolean } | null> {
-    return this.inner.getShell ? this.inner.getShell(key) : null;
+    return this.inner.getShell ? this.inner.getShell(key, options) : null;
   }
 
   async putShell(
@@ -472,7 +502,7 @@ export class SeededShellStore<
     ttlSeconds?: number,
     swrSeconds?: number,
     tags?: string[],
-  ): Promise<void> {
+  ): Promise<"stored" | "invalidated" | void> {
     return this.inner.putShell?.(key, entry, ttlSeconds, swrSeconds, tags);
   }
 

package/src/cache/types.ts

@@ -36,6 +36,13 @@ export interface CacheGetResult {
  * @typeParam TEnv - Platform bindings type (e.g., Cloudflare env)
  */
 export interface SegmentCacheStore<TEnv = unknown> {
+  /**
+   * The store honors getShell(..., { claimRevalidation: false }) without
+   * claiming an SWR lock. Navigation replay requires this opt-in because it
+   * cannot recapture an HTML shell after observing a stale entry.
+   */
+  readonly supportsPassiveShellReads?: true;
+
   /**
    * Default cache options for this store.
    * Used by cache() boundaries when ttl/swr are not explicitly specified.
@@ -144,9 +151,12 @@ export interface SegmentCacheStore<TEnv = unknown> {
    *
    * Optional: a store that does not implement the shell family disables the
    * shell-cache middleware (it fails open to the normal HTML render path).
+   * A passive read reports a stale entry as `shouldRevalidate: true` without
+   * claiming store-specific revalidation ownership.
    */
   getShell?(
     key: string,
+    options?: { claimRevalidation?: boolean },
   ): Promise<{ entry: ShellCacheEntry; shouldRevalidate?: boolean } | null>;
 
   /**
@@ -160,6 +170,8 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * @param swrSeconds - Optional stale-while-revalidate window in seconds
    * @param tags - Optional cache tags for invalidation (participates in
    *   invalidateTags via the same tag machinery as the item family)
+   * @returns `invalidated` when a generation marker rejected the write,
+   *   `stored` when acknowledged, or void for stores without acknowledgements.
    */
   putShell?(
     key: string,
@@ -167,7 +179,7 @@ export interface SegmentCacheStore<TEnv = unknown> {
     ttlSeconds?: number,
     swrSeconds?: number,
     tags?: string[],
-  ): Promise<void>;
+  ): Promise<"stored" | "invalidated" | void>;
 
   /**
    * Get a cached function result by key.
@@ -200,10 +212,9 @@ export interface SegmentCacheStore<TEnv = unknown> {
   /**
    * True when ANY of `tags` was invalidated (invalidateTags/updateTag) at or
    * after `sinceMs` (>= so a same-millisecond invalidation wins, favouring
-   * freshness). Consulted by the build-time shell read-through
-   * (rsc/shell-build-manifest.ts): a baked shell entry is immutable in the
-   * build manifest, so "was it evicted" is answered by the store's tag
-   * markers against the entry's createdAt rather than by deleting anything.
+   * freshness). Consulted by build-shell read-through and runtime shell stores:
+   * "was it evicted" is answered by tag markers against the entry's createdAt,
+   * including when invalidation races a capture that has not been written yet.
    * Optional: without it, TAGGED build entries are not served (untagged ones
    * are unaffected — they are evictable only by deploy/buildVersion anyway).
    * Fail open to `false` on marker-read errors: a transient store fault must
@@ -307,7 +318,14 @@ export interface ShellCacheEntry {
    * their holes always fill.
    */
   handlerLiveHoles?: boolean;
-  /** Epoch ms when the shell was captured. */
+  /**
+   * Legacy/fallback marker for a transition({ when }) predicate that was not
+   * evaluated by the PPR pre-handler gate. Such an entry stays conservatively
+   * ineligible for handler-free replay. New PPR matches evaluate known segment
+   * predicates before the pipeline and do not set this marker.
+   */
+  transitionWhen?: true;
+  /** Capture-generation start time; tag invalidations at or after it win. */
   createdAt: number;
 }
 

package/src/cache/vercel/vercel-cache-store.ts

@@ -134,9 +134,9 @@ type CacheFamily = "s" | "i" | "r" | "h" | "tm";
  * invalidateTags for the build-shell read-through's isTagsInvalidatedSince
  * gate. The platform's expireTag() DELETES tagged entries (no queryable
  * history), so the markers are rango's own record of "tag X was invalidated
- * at T". One year: markers must outlive any build's shell entries (which the
- * buildVersion gate retires on the next deploy anyway); an expired marker
- * would silently resurrect an updateTag()-evicted build shell.
+ * at T". One year: runtime tagged-shell retention is capped to this lifetime,
+ * while buildVersion retires build shells on the next deploy. An expired marker
+ * therefore cannot resurrect a runtime shell that outlived its invalidation.
  */
 const TAG_MARKER_TTL_SECONDS = 365 * 24 * 60 * 60;
 
@@ -190,7 +190,7 @@ interface VercelShellEnvelope {
   rv: string;
   /** Build version at capture (ShellCacheEntry.buildVersion). */
   bv?: string;
-  /** createdAt (ms since epoch). */
+  /** Capture-generation start time, used by tag marker checks. */
   c: number;
   /** staleAt (ms since epoch). */
   s: number;
@@ -209,6 +209,8 @@ interface VercelShellEnvelope {
    * their holes only a handler re-run can fill.
    */
   lh?: boolean;
+  /** ShellCacheEntry.transitionWhen; conditional transitions must re-run. */
+  tw?: true;
 }
 
 /** Read-path outcome for the debug sink. */
@@ -355,6 +357,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 export class VercelCacheStore<
   TEnv = unknown,
 > implements SegmentCacheStore<TEnv> {
+  readonly supportsPassiveShellReads: true = true;
   readonly defaults?: CacheDefaults;
   readonly keyGenerator?: (
     ctx: RequestContext<TEnv>,
@@ -731,6 +734,7 @@ export class VercelCacheStore<
 
   async getShell(
     key: string,
+    options?: { claimRevalidation?: boolean },
   ): Promise<{ entry: ShellCacheEntry; shouldRevalidate?: boolean } | null> {
     const storeKey = this.toStoreKey(key, "h");
     const started = Date.now();
@@ -774,14 +778,25 @@ export class VercelCacheStore<
       return null;
     }
 
+    if (
+      env.t &&
+      env.t.length > 0 &&
+      (await this.isTagsInvalidatedSince(env.t, env.c))
+    ) {
+      void this.safeDelete(storeKey);
+      this.emitDebug({ op: "getShell", key, outcome: "miss", readMs });
+      return null;
+    }
+
     const isStale = env.s > 0 && now > env.s;
-    const shouldRevalidate = isStale
-      ? await this.claimRevalidation(
-          storeKey,
-          env.e,
-          "[VercelCacheStore] getShell",
-        )
-      : false;
+    let shouldRevalidate = isStale;
+    if (isStale && options?.claimRevalidation !== false) {
+      shouldRevalidate = await this.claimRevalidation(
+        storeKey,
+        env.e,
+        "[VercelCacheStore] getShell",
+      );
+    }
     this.emitDebug({
       op: "getShell",
       key,
@@ -800,6 +815,7 @@ export class VercelCacheStore<
         initialTheme: env.i,
         snapshot: env.sn,
         handlerLiveHoles: env.lh,
+        transitionWhen: env.tw,
         createdAt: env.c,
       },
       shouldRevalidate,
@@ -812,10 +828,12 @@ export class VercelCacheStore<
     ttlSeconds?: number,
     swrSeconds?: number,
     tags?: string[],
-  ): Promise<void> {
+  ): Promise<"stored" | "invalidated" | void> {
     try {
       const ttl = resolveTtl(ttlSeconds, this.defaults, DEFAULT_FUNCTION_TTL);
       const swrWindow = resolveSwrWindow(swrSeconds, this.defaults);
+      const totalTtl = ttl + swrWindow;
+      const now = Date.now();
       const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
       // Store the CLAMPED tags (see putResponse/setItem) so dropped tags don't
       // resurface on a hit; write() re-clamps idempotently.
@@ -823,6 +841,17 @@ export class VercelCacheStore<
         tags,
         "[VercelCacheStore] putShell",
       );
+      const storeKey = this.toStoreKey(key, "h");
+      if (
+        safeTags.length > 0 &&
+        (await this.isTagsInvalidatedSince(safeTags, entry.createdAt))
+      ) {
+        return "invalidated";
+      }
+      const retentionTtl =
+        safeTags.length > 0
+          ? Math.min(totalTtl, TAG_MARKER_TTL_SECONDS)
+          : totalTtl;
       const env: VercelShellEnvelope = {
         p: entry.prelude,
         po: entry.postponed,
@@ -830,22 +859,24 @@ export class VercelCacheStore<
         bv: entry.buildVersion,
         c: entry.createdAt,
         s: staleAt,
-        e: expiresAt,
+        e: Math.min(expiresAt, now + retentionTtl * 1000),
         t: safeTags.length > 0 ? safeTags : undefined,
         i: entry.initialTheme,
         sn: entry.snapshot,
         lh: entry.handlerLiveHoles,
+        tw: entry.transitionWhen,
       };
       // write() enforces the 2 MB per-item ceiling (withinSizeLimit): an
       // oversized shell prelude is reported and skipped (fail-open to a full
       // render), never silently no-op'd on the platform.
       await this.write(
-        this.toStoreKey(key, "h"),
+        storeKey,
         env,
-        ttl + swrWindow,
+        retentionTtl,
         safeTags,
         "[VercelCacheStore] putShell",
       );
+      return "stored";
     } catch (error) {
       reportCacheError(error, "cache-write", "[VercelCacheStore] putShell");
     }
@@ -854,12 +885,10 @@ export class VercelCacheStore<
   // --- Tags ---
 
   /**
-   * Build-shell read-through gate (SegmentCacheStore.isTagsInvalidatedSince).
-   * The platform's expireTag() DELETES tagged entries and keeps no queryable
-   * history, so invalidateTags() below writes its own "tm" marker entries and
-   * this compares them against the baked entry's build-time createdAt
-   * (>= so a same-millisecond invalidation wins). Fails open to `false` on
-   * read errors — the same posture as the CF marker check.
+   * Shell tag-generation gate (SegmentCacheStore.isTagsInvalidatedSince).
+   * expireTag() keeps no queryable history, so invalidateTags() writes "tm"
+   * markers for runtime capture races and immutable build shells. Marker >=
+   * generation start wins; read errors fail open like the CF marker check.
    */
   async isTagsInvalidatedSince(
     tags: string[],
@@ -1163,7 +1192,7 @@ export class VercelCacheStore<
 
   private asShellEnvelope(raw: unknown): VercelShellEnvelope | null {
     if (!isRecord(raw)) return null;
-    const { p, po, rv, bv, c, s, e, t, i, sn, lh } = raw;
+    const { p, po, rv, bv, c, s, e, t, i, sn, lh, tw } = raw;
     if (typeof p !== "string" || typeof rv !== "string") return null;
     if (po !== null && typeof po !== "string") return null;
     if (typeof c !== "number") return null;
@@ -1180,6 +1209,7 @@ export class VercelCacheStore<
       i: typeof i === "string" ? i : undefined,
       sn: Array.isArray(sn) ? (sn as ShellSnapshotRecord[]) : undefined,
       lh: lh === true ? true : undefined,
+      tw: tw === true ? true : undefined,
     };
   }
 

package/src/dev-discovery-protocol.ts

@@ -0,0 +1,11 @@
+export const DEV_DISCOVERY_READY_EVENT = "rango:dev-discovery-ready";
+
+export const DEV_DISCOVERY_QUERY_EVENT = "rango:dev-discovery-query";
+
+export const DEV_DISCOVERY_PROBE_HEADER = "x-rango-dev-discovery-probe";
+
+export const DEV_DISCOVERY_EPOCH_HEADER = "x-rango-dev-discovery-epoch";
+
+export function isValidDevDiscoveryEpoch(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}

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

@@ -44,7 +44,7 @@ import { isRouteNotFoundError } from "../errors.js";
 import { createReverseFunction } from "../router/handler-context.js";
 import { executeMiddleware, matchMiddleware } from "../router/middleware.js";
 import type { MiddlewareEntry } from "../router/middleware.js";
-import { getGlobalRouteMap } from "../route-map-builder.js";
+import { getGlobalRouteMap, isRouteRootScoped } from "../route-map-builder.js";
 import {
   resolvePprConfig,
   type ResolvedPprConfig,
@@ -183,6 +183,9 @@ async function attemptBuildCapture(
     stateCookieName: router.resolvedStateCookieName,
     version: opts.buildVersion,
   });
+  // Scope registry lookups (root-scope/search-schema) per router during the
+  // bake, mirroring rsc/handler.ts on the request path (#762).
+  baseCtx._routerId = router.id;
 
   // Entry collector: captureAndStoreShell's sink. putShell never fails here,
   // so a "stored" outcome always carries the entry.
@@ -235,6 +238,9 @@ async function attemptBuildCapture(
       getGlobalRouteMap(),
       preview?.routeKey,
       preview?.params ?? {},
+      preview?.routeKey
+        ? isRouteRootScoped(preview.routeKey, router.id)
+        : undefined,
     );
 
     const runCapture = () =>

package/src/prerender/store.ts

@@ -54,6 +54,11 @@ declare global {
   var __STATIC_MANIFEST:
     | Record<string, () => Promise<{ default: string | StaticEntry }>>
     | undefined;
+  // Injected by closeBundle post-processing: lazy loader for the static
+  // manifest module (which assigns __STATIC_MANIFEST on evaluation). Resolved
+  // by static-store.ts on the first Static() lookup — issue #760.
+  // eslint-disable-next-line no-var
+  var __loadStaticManifestModule: (() => Promise<unknown>) | undefined;
   // Injected by virtual module in dev mode for on-demand prerender
   // eslint-disable-next-line no-var
   var __PRERENDER_DEV_URL: string | undefined;

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

@@ -12,6 +12,7 @@ import {
   getNamePrefix,
   getUrlPrefix,
   requireDslContext,
+  stampStaticDefScope,
   type EntryData,
   type EntryPropDatas,
   type EntryPropSegments,
@@ -560,6 +561,7 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
         if (ctx.namePrefix) {
           (slotHandler as any).$$routePrefix = ctx.namePrefix;
         }
+        stampStaticDefScope(slotHandler);
       }
     } else {
       unwrappedSlots[slotName] = slotHandler;
@@ -1016,8 +1018,11 @@ const layout: RouteHelpers<any, any>["layout"] = (handler, use) => {
   } satisfies EntryData;
 
   // Capture namespace prefix on static handler for build-time reverse() resolution
-  if (isStatic && handler.$$id && ctx.namePrefix) {
-    (handler as any).$$routePrefix = ctx.namePrefix;
+  if (isStatic && handler.$$id) {
+    if (ctx.namePrefix) {
+      (handler as any).$$routePrefix = ctx.namePrefix;
+    }
+    stampStaticDefScope(handler);
   }
 
   // Merge handler.use defaults with explicit use

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

@@ -460,11 +460,11 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    * startTransition only when the router sets viewTransition: false.
    *
    * Conditional hold: pass `when: (ctx) => boolean` to gate the transition per
-   * request. It runs server-side AFTER the route handler (so it can read state
-   * the handler set via `ctx.get(...)`); returning false drops this transition
-   * for the request, so the navigation streams its loading() skeleton instead of
-   * holding. This is a post-handler predicate — distinct from intercept()'s
-   * match-time `when` config selector (`intercept(slot, route, Comp, { when })`).
+   * request. It normally runs server-side after the route handler. On a `ppr`
+   * route it is automatically hoisted before route handlers and reevaluated on
+   * every replay, so it may read URL/params/action/env and middleware-set context
+   * but not handler-set context. Returning false drops this transition for the
+   * request. This is distinct from intercept()'s match-time `when` selector.
    *
    * ```typescript
    * // Attach to a single route
@@ -491,7 +491,7 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    * @param config - ViewTransition configuration (enter, exit, update, share,
    *   default, name), `viewTransition: "auto" | false` to toggle the router
    *   boundary (createRouter({ viewTransition }) sets the app-wide default), and
-   *   `when: (ctx) => boolean` to gate the transition per request post-handler
+   *   `when: (ctx) => boolean` to gate the transition per request
    * @param children - Optional callback returning child routes to wrap
    */
   transition: {