@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.1

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"],
@@ -110,6 +113,19 @@ export class RecordingShellStore<
     this.writes.push(p);
   }
 
+  /**
+   * Record a segment-family write into the snapshot WITHOUT touching the inner
+   * store. The shell fast path's implicit doc-cache scope writes through this
+   * (via {@link SnapshotOnlySegmentStore}): the recorded doc entry must ride
+   * ONLY inside the shell entry — a passthrough write would leave a doc-keyed
+   * entry in the real store that the NEXT capture's lookup would hit, replaying
+   * the previous generation's segments instead of re-running handlers (breaking
+   * SWR recapture freshness).
+   */
+  recordSegmentWrite(key: string, data: CachedEntryData): void {
+    this.record("segment", key, data);
+  }
+
   /**
    * Await the tracked deferred writes so their records are present before drain.
    * Drains ITERATIVELY: a write task can schedule a NESTED write (the ring-3
@@ -219,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(
@@ -229,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);
   }
 
@@ -245,6 +262,40 @@ export function getRecordingStore<TEnv>(
   return store instanceof RecordingShellStore ? store : undefined;
 }
 
+/**
+ * The store the shell fast path's IMPLICIT doc-cache scope resolves during a
+ * capture: reads pass through the recording store (a real-store hit is
+ * recorded, exactly like any capture read), but segment WRITES are recorded
+ * into the snapshot only — see {@link RecordingShellStore.recordSegmentWrite}
+ * for why passthrough would break SWR recapture. Routes with their OWN
+ * cache() config never see this store (their scope resolves the app-level
+ * recording store and keeps today's record-and-write behavior).
+ */
+export class SnapshotOnlySegmentStore<
+  TEnv = unknown,
+> implements SegmentCacheStore<TEnv> {
+  constructor(private readonly recording: RecordingShellStore<TEnv>) {}
+
+  get defaults(): SegmentCacheStore<TEnv>["defaults"] {
+    return this.recording.defaults;
+  }
+  get keyGenerator(): SegmentCacheStore<TEnv>["keyGenerator"] {
+    return this.recording.keyGenerator;
+  }
+
+  async get(key: string): Promise<CacheGetResult | null> {
+    return this.recording.get(key);
+  }
+
+  async set(key: string, data: CachedEntryData): Promise<void> {
+    this.recording.recordSegmentWrite(key, data);
+  }
+
+  async delete(key: string): Promise<boolean> {
+    return this.recording.delete(key);
+  }
+}
+
 /**
  * Materialize the loader-family seed from a shell snapshot for a HIT's tail
  * render: Flight-deserialize each recorded (promise-elided) bake-lane
@@ -259,9 +310,21 @@ export function getRecordingStore<TEnv>(
  * HIT). Returns undefined when the snapshot carries no loader records, without
  * touching the Flight codec (kept lazy for cold paths and non-RSC configs).
  */
+export interface ShellLoaderSeedEntry {
+  /** The Flight-deserialized elided container (recorded paths + markers). */
+  container: unknown;
+  /**
+   * True when the record carries hole markers (or predates the capture-side
+   * hole bit, where hole-ness is unknown): the HIT overlay must gate on the
+   * fresh run. False = fully pinned; the payload promise resolves immediately
+   * from the pin (loader-cache.ts pin-first path).
+   */
+  holes: boolean;
+}
+
 export async function buildShellLoaderSeed(
   snapshot: ShellSnapshotRecord[],
-): Promise<Map<string, unknown> | undefined> {
+): Promise<Map<string, ShellLoaderSeedEntry> | undefined> {
   const loaderRecords: ShellSnapshotRecord[] = [];
   for (const rec of snapshot) {
     if (rec.family === "loader") loaderRecords.push(rec);
@@ -270,20 +333,26 @@ export async function buildShellLoaderSeed(
 
   const { deserializeResult } = await import("./segment-codec.js");
   const entries = await Promise.all(
-    loaderRecords.map(async (rec): Promise<[string, unknown] | null> => {
-      try {
-        return [
-          rec.key,
-          await deserializeResult(
-            (rec.value as ShellSnapshotLoaderValue).value,
-          ),
-        ];
-      } catch {
-        return null;
-      }
-    }),
+    loaderRecords.map(
+      async (rec): Promise<[string, ShellLoaderSeedEntry] | null> => {
+        try {
+          const stored = rec.value as ShellSnapshotLoaderValue;
+          return [
+            rec.key,
+            {
+              container: await deserializeResult(stored.value),
+              // A record without the bit (pre-bit snapshot) reads as
+              // hole-carrying: unknown hole-ness must keep the gated path.
+              holes: stored.holes !== 0,
+            },
+          ];
+        } catch {
+          return null;
+        }
+      },
+    ),
   );
-  const seed = new Map<string, unknown>();
+  const seed = new Map<string, ShellLoaderSeedEntry>();
   for (const entry of entries) {
     if (entry) seed.set(entry[0], entry[1]);
   }
@@ -295,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
@@ -330,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);
   }
 
@@ -343,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);
   }
 
@@ -357,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 };
     }
@@ -375,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,
@@ -397,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(
@@ -407,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.
@@ -196,6 +208,19 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * @param tags - The cache tags to invalidate
    */
   invalidateTags?(tags: string[]): Promise<void>;
+
+  /**
+   * True when ANY of `tags` was invalidated (invalidateTags/updateTag) at or
+   * after `sinceMs` (>= so a same-millisecond invalidation wins, favouring
+   * 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
+   * degrade to "still valid", the same posture as the envelope tag checks.
+   */
+  isTagsInvalidatedSince?(tags: string[], sinceMs: number): Promise<boolean>;
 }
 
 /**
@@ -280,7 +305,26 @@ export interface ShellCacheEntry {
    * heals it. See docs/design/ppr-shell-resume.md ("the capture data snapshot").
    */
   snapshot?: ShellSnapshotRecord[];
-  /** Epoch ms when the shell was captured. */
+  /**
+   * True when the capture's HANDLER layer declared per-request liveness: a
+   * handle pushed OUTSIDE a DSL loader scope carried a nested thenable (the
+   * capture mask turns it into a never-filling hole), such a push was still
+   * pending when the entry was written, or a handler-invoked loader
+   * (ctx.use(loader) from a handler body — the consumption lane, #672)
+   * executed during the capture. The serve tail then must NOT take the
+   * handler-free fast path (the implicit doc-cache hit): only a handler
+   * re-run can mint that hole's live promise or refresh that consumed value.
+   * DSL-loader pushes never set this — loaders re-run fresh on every HIT, so
+   * their holes always fill.
+   */
+  handlerLiveHoles?: boolean;
+  /**
+   * 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;
 }
 
@@ -305,6 +349,17 @@ export type ShellSnapshotFamily = "item" | "segment" | "response" | "loader";
 export interface ShellSnapshotLoaderValue {
   /** RSC-serialized elided container (see loader-snapshot.ts). */
   value: string;
+  /**
+   * Hole bit, capture-computed (elide already walks every node): 1 = the
+   * container carries hole markers, so a HIT must gate the overlay on the
+   * fresh run (only the loader body can mint the live nested promises);
+   * 0 = fully pinned, so a HIT resolves the payload promise immediately from
+   * the pin while the fresh run proceeds ungated (side effects and cache
+   * read-through writes preserved; its values were discarded either way —
+   * recorded paths win wholesale). Absent on pre-bit snapshots, which keep
+   * the gated path.
+   */
+  holes?: 0 | 1;
 }
 
 /** A serialized cached Response for the response family of a shell snapshot. */

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

@@ -127,7 +127,18 @@ const REVALIDATION_LOCK_MS = 30_000;
 /** Family prefixes that keep the value tiers from colliding in the single Vercel
  *  keyspace. The router's own semantic prefixes (doc:/partial:/use-cache:) become
  *  the suffix; `rg:` namespaces every Rango entry. `h` is the PPR shell tier. */
-type CacheFamily = "s" | "i" | "r" | "h";
+type CacheFamily = "s" | "i" | "r" | "h" | "tm";
+
+/**
+ * TTL for tag-invalidation marker entries ("tm" family), written by
+ * 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: 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;
 
 /** Stored envelope for a segment-tree entry (get/set). */
 interface VercelSegmentEnvelope {
@@ -179,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;
@@ -191,6 +202,15 @@ interface VercelShellEnvelope {
   i?: string;
   /** Capture data snapshot: recorded cache-store hits/writes for HIT parity. */
   sn?: ShellSnapshotRecord[];
+  /**
+   * ShellCacheEntry.handlerLiveHoles. Must round-trip: the serve side arms the
+   * handler-free fast path on `!entry.handlerLiveHoles`, so dropping the flag
+   * here silently fast-pathed handler-live entries after a store round trip —
+   * 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. */
@@ -337,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>,
@@ -713,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();
@@ -756,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,
@@ -781,6 +814,8 @@ export class VercelCacheStore<
         buildVersion: env.bv,
         initialTheme: env.i,
         snapshot: env.sn,
+        handlerLiveHoles: env.lh,
+        transitionWhen: env.tw,
         createdAt: env.c,
       },
       shouldRevalidate,
@@ -793,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.
@@ -804,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,
@@ -811,21 +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");
     }
@@ -833,6 +884,38 @@ export class VercelCacheStore<
 
   // --- Tags ---
 
+  /**
+   * 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[],
+    sinceMs: number,
+  ): Promise<boolean> {
+    try {
+      const markers = await Promise.all(
+        tags.map((tag) => this.cache.get(this.toStoreKey(tag, "tm"))),
+      );
+      for (const raw of markers) {
+        if (raw == null) continue;
+        const decoded = this.decodeRaw(raw) as { at?: unknown } | null;
+        const at =
+          decoded && typeof decoded.at === "number" ? decoded.at : null;
+        if (at !== null && at >= sinceMs) return true;
+      }
+      return false;
+    } catch (error) {
+      reportCacheError(
+        error,
+        "cache-read",
+        "[VercelCacheStore] tag invalidation check",
+      );
+      return false;
+    }
+  }
+
   async invalidateTags(tags: string[]): Promise<void> {
     if (!tags || tags.length === 0) return;
     // No per-item cap here: an invalidation must reach every requested tag.
@@ -842,6 +925,20 @@ export class VercelCacheStore<
       "cache-invalidate",
     );
     if (safe.length === 0) return;
+    // Marker writes FIRST, and strict: isTagsInvalidatedSince() is how an
+    // updateTag() reaches a build-time shell entry (expireTag cannot delete
+    // what lives in the build manifest), so a failed marker write must reject
+    // like a failed expireTag — silently resolving would report success while
+    // the baked shell keeps serving.
+    await Promise.all(
+      safe.map((tag) =>
+        this.cache.set(
+          this.toStoreKey(tag, "tm"),
+          JSON.stringify({ at: Date.now() }),
+          { ttl: TAG_MARKER_TTL_SECONDS },
+        ),
+      ),
+    );
     try {
       await this.cache.expireTag(safe);
     } catch (error) {
@@ -1095,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 } = 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;
@@ -1111,6 +1208,8 @@ export class VercelCacheStore<
       t: Array.isArray(t) ? (t as string[]) : undefined,
       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/deps/ssr.ts

@@ -1 +1,4 @@
-export { createFromReadableStream } from "@vitejs/plugin-rsc/ssr";
+export {
+  createFromReadableStream,
+  setOnClientReference,
+} from "@vitejs/plugin-rsc/ssr";

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/index.rsc.ts

@@ -88,6 +88,12 @@ export type {
   OriginCheckPhase,
 } from "./rsc/origin-guard.js";
 
+// PPR shell-capture debug sink types (RangoOptions.debugShellCapture)
+export type {
+  ShellCaptureDebug,
+  ShellCaptureDebugEvent,
+} from "./rsc/shell-capture.js";
+
 // Server-side createLoader and redirect
 export {
   createLoader,
@@ -317,4 +323,5 @@ export type {
   RouterTimeouts,
   TimeoutPhase,
   TimeoutContext,
+  RenderTimeoutContext,
 } from "./router/timeout.js";

package/src/index.ts

@@ -398,4 +398,5 @@ export type {
   RouterTimeouts,
   TimeoutPhase,
   TimeoutContext,
+  RenderTimeoutContext,
 } from "./router/timeout.js";