@rangojs/router 0.1.0 → 0.1.1

package/src/browser/types.ts

@@ -65,6 +65,8 @@ export interface RscMetadata {
    * Used to detect version mismatches after HMR/deployment.
    */
   version?: string;
+  /** Cloudflare dev worker generation used for stale-document convergence. */
+  devDiscoveryEpoch?: number;
   /**
    * TTL in milliseconds for the client-side in-memory prefetch cache.
    * Sent on initial render so the browser can configure its cache duration.
@@ -430,24 +432,10 @@ export type StateListener = () => void;
 /**
  * Navigation store interface
  *
- * Manages both:
- * - NavigationState: Public state exposed via useNavigation hook
- * - SegmentState: Internal segment management for partial updates
+ * Owns segment state, history snapshots, and partial-update notifications.
+ * EventController owns the public navigation lifecycle exposed by hooks.
  */
 export interface NavigationStore {
-  // Public state (for useNavigation hook)
-  getState(): NavigationState;
-  setState(partial: Partial<NavigationState>): void;
-  subscribe(listener: StateListener): () => void;
-
-  // Inflight action management
-  addInflightAction(action: InflightAction): void;
-  removeInflightAction(id: string): void;
-
-  // Action state (for controlling update behavior during server actions)
-  isActionInProgress(): boolean;
-  setActionInProgress(value: boolean): void;
-
   // Internal segment state (for bridges)
   getSegmentState(): SegmentState;
   setPath(path: string): void;
@@ -459,8 +447,6 @@ export interface NavigationStore {
   setHistoryKey(key: string): void;
   /** Monotonic token of the most recently committed navigation. */
   getNavInstance(): number;
-  /** Nav-instance token recorded on a cache entry (undefined if absent). */
-  getCacheEntryInstance(historyKey: string): number | undefined;
   cacheSegmentsForHistory(
     historyKey: string,
     segments: ResolvedSegment[],
@@ -506,7 +492,6 @@ export interface NavigationStore {
     stale?: boolean,
     handlesPending?: boolean,
   ): void;
-  markCacheAsStale(): void;
   markHistoryCacheStale(): void;
   markCacheAsStaleAndBroadcast(): void;
   clearHistoryCache(): void;
@@ -525,14 +510,6 @@ export interface NavigationStore {
   // UI update notifications
   onUpdate(callback: UpdateSubscriber): () => void;
   emitUpdate(update: NavigationUpdate): void;
-
-  // Action state tracking (for useAction hook)
-  getActionState(actionId: string): TrackedActionState;
-  setActionState(actionId: string, state: Partial<TrackedActionState>): void;
-  subscribeToAction(
-    actionId: string,
-    listener: ActionStateListener,
-  ): () => void;
 }
 
 // ============================================================================

package/src/build/generate-manifest.ts

@@ -115,6 +115,7 @@ async function buildPrefixTreeNode(
   passthroughRoutes?: string[],
   responseTypeRoutes?: Record<string, string>,
   routeSearchSchemas?: Record<string, Record<string, string>>,
+  routerId?: string,
 ): Promise<PrefixTreeNode> {
   // Resolve an async include provider (`() => import("./routes")`) so its routes
   // are walked into the build-time manifest/types/href. Runtime matching still
@@ -156,6 +157,7 @@ async function buildPrefixTreeNode(
         parent: null,
         counters: {},
         mountIndex,
+        ...(routerId ? { routerId } : {}),
         trackedIncludes, // Enable nested include tracking
       },
       () => {
@@ -227,6 +229,7 @@ async function buildPrefixTreeNode(
         passthroughRoutes,
         responseTypeRoutes,
         routeSearchSchemas,
+        routerId,
       ),
     );
 
@@ -296,6 +299,12 @@ export async function generateManifestFull<TEnv>(
   mountIndex: number = 0,
   options?: {
     urlPrefix?: string;
+    /**
+     * Owning router id. Threaded into the evaluation store so path() scopes
+     * its search-schema/root-scope registrations per router — same-named
+     * routes in different routers must not clobber each other.
+     */
+    routerId?: string;
     /**
      * Called once per `"use client"` component registered as an
      * errorBoundary/notFoundBoundary fallback, with its client-reference key
@@ -328,6 +337,7 @@ export async function generateManifestFull<TEnv>(
       parent: null,
       counters: {},
       mountIndex,
+      ...(options?.routerId ? { routerId: options.routerId } : {}),
       trackedIncludes, // Enable include tracking
       // basename sets the initial URL prefix for all path() registrations
       ...(options?.urlPrefix ? { urlPrefix: options.urlPrefix } : {}),
@@ -402,6 +412,7 @@ export async function generateManifestFull<TEnv>(
       passthroughRoutes,
       responseTypeRoutes,
       routeSearchSchemas,
+      options?.routerId,
     ),
   );
 

package/src/cache/cache-scope.ts

@@ -89,6 +89,7 @@ function getDefaultRouteCacheKey(
   pathname: string,
   params?: Record<string, string>,
   isIntercept?: boolean,
+  prefixOverride?: "doc",
 ): string {
   const ctx = getRequestContext();
   const isPartial = ctx?.originalUrl?.searchParams.has("_rsc_partial") ?? false;
@@ -96,7 +97,9 @@ function getDefaultRouteCacheKey(
   const host = ctx?.url.host ?? "localhost";
 
   // Intercept navigations get their own cache namespace
-  const prefix = isIntercept ? "intercept" : isPartial ? "partial" : "doc";
+  const prefix = isIntercept
+    ? "intercept"
+    : (prefixOverride ?? (isPartial ? "partial" : "doc"));
 
   return `${prefix}:${cacheKeyBase(host, pathname, searchParams, params)}`;
 }
@@ -131,6 +134,7 @@ export class CacheScope {
   constructor(
     config: PartialCacheOptions | false,
     parent: CacheScope | null = null,
+    private readonly defaultKeyPrefix?: "doc",
   ) {
     this.config = config;
     this.parent = parent;
@@ -209,7 +213,12 @@ export class CacheScope {
     params: Record<string, string>,
     isIntercept?: boolean,
   ): Promise<string> {
-    const defaultKey = getDefaultRouteCacheKey(pathname, params, isIntercept);
+    const defaultKey = getDefaultRouteCacheKey(
+      pathname,
+      params,
+      isIntercept,
+      this.defaultKeyPrefix,
+    );
     const keyFn = this.config !== false ? this.config.key : undefined;
     return resolveCacheKey(keyFn, this.getStore(), defaultKey, "CacheScope");
   }
@@ -529,10 +538,11 @@ export function createCacheScope(
 /**
  * Shell fast path: when the route tree derived NO cache scope and the current
  * request context carries the `_shellImplicitCache` marker (a shell capture,
- * or a HIT tail serving an eligible entry), substitute an implicit doc-level
- * scope so withCacheLookup/withCacheStore treat the WHOLE matched route as a
- * cache() boundary — the shell entry IS a cache() of the handler layer, with
- * loaders as the live carve-outs (resolveFreshLoadersAndYield).
+ * an eligible HIT tail, or a normal partial navigation replay), substitute an
+ * implicit doc-level scope so withCacheLookup/withCacheStore treat the WHOLE
+ * matched route as a cache() boundary — the shell entry IS a cache() of the
+ * handler layer, with loaders as the live carve-outs
+ * (resolveFreshLoadersAndYield).
  *
  * An existing scope — including an explicit cache(false) opt-out — always
  * wins: the consumer's cache() semantics (their ttl/swr/store/condition) are
@@ -548,5 +558,6 @@ export function resolveShellImplicitCacheScope(
   return new CacheScope(
     { ttl: marker.ttl, swr: marker.swr, store: marker.store },
     null,
+    marker.keyPrefix,
   );
 }

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

@@ -272,7 +272,7 @@ interface KVShellEnvelope {
   rv: string;
   /** Build version captured at prerender time (ShellCacheEntry.buildVersion) */
   bv?: string;
-  /** createdAt (ms epoch) */
+  /** Capture-generation start time (ms epoch), used by tag marker checks. */
   c: number;
   /** When entry becomes stale (ms epoch) */
   s: number;
@@ -293,6 +293,8 @@ interface KVShellEnvelope {
    * their holes only a handler re-run can fill.
    */
   lh?: boolean;
+  /** ShellCacheEntry.transitionWhen; conditional transitions must re-run. */
+  tw?: true;
 }
 
 /**
@@ -323,6 +325,7 @@ interface KVResponseEnvelope {
 // ============================================================================
 
 export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
+  readonly supportsPassiveShellReads: true = true;
   readonly defaults?: CacheDefaults;
   readonly keyGenerator?: (
     ctx: RequestContext<TEnv>,
@@ -1743,7 +1746,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   // per-colo L1 for them is a deliberate follow-up (see the PPR shell-resume
   // design doc). Shell entries live only in KV (the global tier), so the family
   // requires a configured KV namespace; without one, getShell/putShell no-op and
-  // the shell-cache middleware fails open to a full HTML render. Tag invalidation
+  // the integrated PPR serve path fails open to a full HTML render. Tag invalidation
   // still applies: shell entries carry tags/taggedAt and are checked against the
   // same KV markers isGloballyInvalidated() reads for every other tier.
 
@@ -1772,7 +1775,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * Get a cached PPR shell entry by key from KV (no L1). Applies the KV read
    * budget, corrupt-entry eviction, hard-expiry, and tag invalidation exactly
    * like kvGetItem, minus the L1 promote. SWR is a plain staleness flag — KV has
-   * no REVALIDATING herd guard, so the shell-cache middleware's module-level
+   * no REVALIDATING herd guard, so the capture scheduler's module-level
    * in-flight set is the recapture stampede guard.
    */
   async getShell(
@@ -1815,6 +1818,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           initialTheme: envelope.i,
           snapshot: envelope.sn,
           handlerLiveHoles: envelope.lh,
+          transitionWhen: envelope.tw,
           createdAt: envelope.c,
         },
         shouldRevalidate,
@@ -1826,8 +1830,9 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   }
 
   /**
-   * Store a PPR shell entry in KV with TTL and optional SWR window. Non-blocking
-   * (waitUntil) like the other KV writes. The tags/taggedAt ride in the envelope
+   * Store a PPR shell entry in KV with TTL and optional SWR window. The write is
+   * registered with waitUntil and awaited so invalidation rejection can be
+   * acknowledged to the capture scheduler. The tags/taggedAt ride in the envelope
    * so isGloballyInvalidated() can invalidate the shell via the shared KV markers.
    */
   async putShell(
@@ -1836,8 +1841,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     ttlSeconds?: number,
     swrSeconds?: number,
     tags?: string[],
-  ): Promise<void> {
-    // KV-only tier: needs a KV namespace and waitUntil (writes are non-blocking).
+  ): Promise<"stored" | "invalidated" | void> {
+    // KV-only tier: needs a KV namespace and waitUntil. The same write promise is
+    // registered for isolate lifetime and awaited so invalidation rejection can
+    // be acknowledged to the capture scheduler.
     if (!this.kv) {
       this.warnShellFamilyInertOnce();
       return;
@@ -1851,9 +1858,15 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       // letting kv.put reject inside waitUntil (mirrors setItem/kvSetSegment).
       if (totalTtl < 60) return;
 
-      const staleAt = Date.now() + ttl * 1000;
+      const retentionTtl =
+        tags && tags.length > 0 && this.tagInvalidationTtl
+          ? Math.min(totalTtl, this.tagInvalidationTtl)
+          : totalTtl;
+      const now = Date.now();
+      const staleAt = now + ttl * 1000;
+      const expiresAt = now + retentionTtl * 1000;
       const taggedAt =
-        Array.isArray(tags) && tags.length > 0 ? Date.now() : undefined;
+        Array.isArray(tags) && tags.length > 0 ? entry.createdAt : undefined;
 
       const kvKey = this.toKVKey(`shell:${key}`);
       // A key over the KV limit makes kv.put reject deep inside waitUntil; report
@@ -1871,31 +1884,43 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         return;
       }
 
-      this.waitUntil(() =>
-        reportingAsync(
-          () => {
-            const envelope: KVShellEnvelope = {
-              p: entry.prelude,
-              po: entry.postponed,
-              rv: entry.reactVersion,
-              bv: entry.buildVersion,
-              c: entry.createdAt,
-              s: staleAt,
-              e: staleAt + swrWindow * 1000,
-              t: tags,
-              ta: taggedAt,
-              i: entry.initialTheme,
-              sn: entry.snapshot,
-              lh: entry.handlerLiveHoles,
-            };
-            return this.kv!.put(kvKey, JSON.stringify(envelope), {
-              expirationTtl: totalTtl,
-            });
-          },
-          "cache-write",
-          "[CFCacheStore] putShell",
-        ),
-      );
+      const write = (async (): Promise<"stored" | "invalidated" | void> => {
+        try {
+          if (
+            tags &&
+            tags.length > 0 &&
+            (await this.isGloballyInvalidated(tags, entry.createdAt))
+          ) {
+            return "invalidated";
+          }
+          const envelope: KVShellEnvelope = {
+            p: entry.prelude,
+            po: entry.postponed,
+            rv: entry.reactVersion,
+            bv: entry.buildVersion,
+            c: entry.createdAt,
+            s: staleAt,
+            e: expiresAt,
+            t: tags,
+            ta: taggedAt,
+            i: entry.initialTheme,
+            sn: entry.snapshot,
+            lh: entry.handlerLiveHoles,
+            tw: entry.transitionWhen,
+          };
+          await this.kv!.put(kvKey, JSON.stringify(envelope), {
+            expirationTtl: retentionTtl,
+          });
+          return "stored";
+        } catch (error) {
+          reportCacheError(error, "cache-write", "[CFCacheStore] putShell");
+          return undefined;
+        }
+      })();
+      this.waitUntil(async () => {
+        await write;
+      });
+      return await write;
     } catch (error) {
       reportCacheError(error, "cache-write", "[CFCacheStore] putShell");
     }
@@ -2610,11 +2635,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * eager purge still fires for the whole batch first (it is additive).
    */
   /**
-   * Build-shell read-through gate (SegmentCacheStore.isTagsInvalidatedSince):
-   * a baked shell entry is immutable in the build manifest, so eviction is
-   * answered by the SAME KV tag markers updateTag() writes, compared against
-   * the entry's build-time createdAt. Thin public wrapper over the private
-   * envelope check (identical semantics: marker >= since, fail open).
+   * Shell tag-generation gate (SegmentCacheStore.isTagsInvalidatedSince): the
+   * SAME KV markers used by runtime envelopes also evict immutable build shells
+   * and captures whose write races updateTag(). Thin public wrapper over the
+   * private envelope check (marker >= since, fail open).
    */
   async isTagsInvalidatedSince(
     tags: string[],

package/src/cache/memory-segment-store.ts

@@ -188,6 +188,7 @@ const DEFAULT_MAX_ENTRIES = 1000;
 export class MemorySegmentCacheStore<
   TEnv = unknown,
 > implements SegmentCacheStore<TEnv> {
+  readonly supportsPassiveShellReads: true = true;
   private cache: Map<string, CachedEntryData>;
   private responseCache: Map<string, CachedResponseEntry>;
   private itemCache: Map<string, CachedItemEntry>;
@@ -197,11 +198,9 @@ export class MemorySegmentCacheStore<
   /** prefixed cache key -> set of tags (reverse index for O(tags) unregister) */
   private keyTags: Map<string, Set<string>>;
   /**
-   * tag -> epoch ms of its latest invalidateTags() call. The build-shell
-   * read-through's isTagsInvalidatedSince gate: baked shell entries are
-   * immutable in the build manifest, so eviction is answered by comparing
-   * these markers against the entry's build-time createdAt. Per-isolate,
-   * like every other map here — matching this store's tag semantics.
+   * tag -> epoch ms of its latest invalidateTags() call. Runtime capture races
+   * and immutable build shells are gated by comparing these markers with the
+   * shell generation start. Per-isolate, like every other map here.
    */
   private tagInvalidatedAt: Map<string, number>;
   readonly defaults?: CacheDefaults;
@@ -459,7 +458,14 @@ export class MemorySegmentCacheStore<
     ttlSeconds?: number,
     swrSeconds?: number,
     tags?: string[],
-  ): Promise<void> {
+  ): Promise<"stored" | "invalidated"> {
+    if (
+      tags &&
+      tags.length > 0 &&
+      this.tagsInvalidatedSince(tags, entry.createdAt)
+    ) {
+      return "invalidated";
+    }
     const ttl = resolveTtl(ttlSeconds, this.defaults, DEFAULT_FUNCTION_TTL);
     const swrWindow = resolveSwrWindow(swrSeconds, this.defaults);
     const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
@@ -470,12 +476,17 @@ export class MemorySegmentCacheStore<
     if (tags && tags.length > 0) {
       this.registerTags(tags, prefixedKey);
     }
+    return "stored";
   }
 
   async isTagsInvalidatedSince(
     tags: string[],
     sinceMs: number,
   ): Promise<boolean> {
+    return this.tagsInvalidatedSince(tags, sinceMs);
+  }
+
+  private tagsInvalidatedSince(tags: string[], sinceMs: number): boolean {
     for (const tag of tags) {
       const at = this.tagInvalidatedAt.get(tag);
       // >= so a same-millisecond invalidation wins (freshness over staleness),

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,13 @@ export interface ShellCacheEntry {
    * their holes always fill.
    */
   handlerLiveHoles?: boolean;
-  /** Epoch ms when the shell was captured. */
+  /**
+   * The capture encountered transition({ when }). Its effective hold policy is
+   * request-dependent, so handler-free document and navigation replay must
+   * re-run resolution to collect and evaluate the predicate.
+   */
+  transitionWhen?: true;
+  /** Capture-generation start time; tag invalidations at or after it win. */
   createdAt: number;
 }