@rangojs/router 0.0.0-experimental.146 → 0.0.0-experimental.148

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.146",
+  "version": "0.0.0-experimental.148",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -128,6 +128,11 @@
       "types": "./src/build/index.ts",
       "import": "./src/build/index.ts"
     },
+    "./build/shell-capture": {
+      "types": "./src/prerender/build-shell-capture.ts",
+      "react-server": "./src/prerender/build-shell-capture.ts",
+      "import": "./src/prerender/build-shell-capture.ts"
+    },
     "./host": {
       "types": "./src/host/index.ts",
       "react-server": "./src/host/index.ts",

package/skills/mime-routes/SKILL.md

@@ -41,26 +41,33 @@ When an API client requests the same URL (`Accept: application/json`), the JSON
 1. **Q-value priority** — higher `q` wins (`Accept: application/json;q=0.9, text/html;q=1.0` serves RSC)
 2. **Client order tiebreaker** — when q-values are equal, the type listed first in Accept wins (matches Express/Hono behavior)
 3. **Specific MIME match** — the variant whose MIME type appears in Accept wins
-4. **Wildcard / empty Accept** — `*/*` and missing Accept fall back to route definition order (the first-defined variant wins)
+4. **Wildcard / empty Accept** — `*/*` and missing Accept fall back to route definition order (the first-defined variant wins); when the RSC route wins this way, it serves the HTML document
 5. **All responses** on a negotiated URL get `Vary: Accept` header, including the RSC side
 
-RSC participates as a `text/html` candidate alongside response-type variants.
-There is no special short-circuit — RSC follows the same negotiation rules as other types.
+RSC participates as a candidate alongside response-type variants under two MIME
+types: `text/html` (the document — its canonical representation) and
+`text/x-component` (the RSC flight wire format). There is no special
+short-circuit — RSC follows the same negotiation rules as other types.
 
 The MIME mapping used for matching:
 
-| Tag                  | MIME type                                                    |
-| -------------------- | ------------------------------------------------------------ |
-| RSC (plain `path()`) | `text/html` (negotiation) / `text/x-component` (wire format) |
-| `json`               | `application/json`                                           |
-| `text`               | `text/plain`                                                 |
-| `xml`                | `application/xml`                                            |
-| `html`               | `text/html`                                                  |
-| `md`                 | `text/markdown`                                              |
-
-RSC routes negotiate as `text/html` but respond with `text/x-component` (the RSC wire format).
-The browser's RSC runtime decodes this transparently — clients requesting `text/html` get
-the RSC page rendered normally.
+| Tag                  | MIME type                              |
+| -------------------- | -------------------------------------- |
+| RSC (plain `path()`) | `text/html` **and** `text/x-component` |
+| `json`               | `application/json`                     |
+| `text`               | `text/plain`                           |
+| `xml`                | `application/xml`                      |
+| `html`               | `text/html`                            |
+| `md`                 | `text/markdown`                        |
+
+Which representation an RSC win renders is decided by the same Accept header:
+the flight wire format is **explicit opt-in only** (`Accept: text/x-component`,
+or the internal `_rsc_*`/`__rsc` transport params the client runtime sends).
+Everything else — browsers, `curl` (`*/*`), a missing Accept header, mismatched
+types like `application/json` on a URL with no JSON variant — gets the HTML
+document. A generic HTTP client never sees the wire format by accident, and an
+explicit `Accept: text/x-component` selects the RSC flight stream even on a
+route where a response variant is defined first.
 
 Tags `image`, `stream`, and `any` are pass-through and do not participate in Accept matching.
 
@@ -77,11 +84,12 @@ export const urlpatterns = urls(({ path }) => [
 ]);
 ```
 
-- `Accept: text/html` — RSC page
+- `Accept: text/html` — RSC page (HTML document)
 - `Accept: application/json` — JSON handler
 - `Accept: text/plain` — text handler
 - `Accept: application/xml` — XML handler
-- `Accept: */*` — RSC page (the primary, since it was registered first)
+- `Accept: */*` — RSC page as HTML (the primary, since it was registered first)
+- `Accept: text/x-component` — RSC page as the flight wire format
 
 ## Wildcard Routes
 

package/skills/ppr/SKILL.md

@@ -171,13 +171,12 @@ auth middleware anywhere (global or route DSL) and it guards PPR for free.
 
 ## Verifying it works
 
-The header exists on DOCUMENT responses only. A bare `curl` (no `Accept`)
-content-negotiates a Flight payload (`text/x-component`) with NO
-`x-rango-shell` header at all — which reads as "PPR is off" but is only the
-wrong request shape:
+The header exists on DOCUMENT responses only. A bare `curl` gets the HTML
+document (Flight is explicit-opt-in via `Accept: text/x-component`), so it
+sees the header directly; only an explicit Flight request shape lacks it:
 
 ```
-curl -s -D - -o /dev/null -H "Accept: text/html" https://app.example.com/products/1 | grep -i x-rango-shell
+curl -s -D - -o /dev/null https://app.example.com/products/1 | grep -i x-rango-shell
 ```
 
 - First document GET: `MISS`, plus a background capture.
@@ -193,6 +192,16 @@ curl -s -D - -o /dev/null -H "Accept: text/html" https://app.example.com/product
 - A ppr-declared route that CANNOT be honored (missing shell store family,
   per-request nonce) serves plain axis 1 with NO header and warns once per
   key — no header + a declared `ppr` means look for that warning.
+- On Cloudflare, `CFCacheStore` WITHOUT a KV namespace has an inert shell
+  family (the shell tier is KV-only): every ppr route stays `MISS` forever.
+  The store warns once per isolate — bind KV
+  (`new CFCacheStore({ ctx, kv: env.CACHE_KV })`) or use another store.
+- Structured capture diagnostics: `createRouter({ debugShellCapture: true })`
+  logs one line per capture attempt/skip (outcome, durations, prelude and
+  snapshot bytes, backoff state); pass a function to receive each
+  `ShellCaptureDebugEvent` instead. In dev, with `debugPerformance` on, the
+  last capture outcome for a key also rides the next document GET's
+  `Server-Timing` as `ppr-capture;desc="…"`.
 
 ## The hole doctrine (encode this in your head)
 
@@ -505,11 +514,12 @@ path(
 );
 ```
 
-| Field  | Default | Notes                                                                                              |
-| ------ | ------- | -------------------------------------------------------------------------------------------------- |
-| `ttl`  | `300`   | shell freshness window in seconds (`ppr: true` uses the default)                                   |
-| `swr`  | —       | stale window: serve the stale shell + background recapture                                         |
-| `tags` | —       | operational tags UNIONED with the tags the capture render auto-collects — see "Invalidation" below |
+| Field              | Default | Notes                                                                                                                                                     |
+| ------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ttl`              | `300`   | shell freshness window in seconds (`ppr: true` uses the default)                                                                                          |
+| `swr`              | —       | stale window: serve the stale shell + background recapture                                                                                                |
+| `tags`             | —       | operational tags UNIONED with the tags the capture render auto-collects — see "Invalidation" below                                                        |
+| `maxSnapshotBytes` | 8 MiB   | cap on the entry's capture data snapshot; over it the snapshot is skipped (shell still stored, warned once per key) so the entry stays under store limits |
 
 The shell store is always the app-level `createRouter({ cache })` store; the
 default key is `${host}${pathname}${sortedSearch}:shell` (host-scoped so

package/src/browser/event-controller.ts

@@ -615,8 +615,22 @@ export function createEventController(
     const arbitration = arb;
     arbitration.inflight++;
 
-    // Track if this action started while others were pending (concurrent)
-    const hadConcurrent = inflightActions.size > 0;
+    // Track if this action started while another was genuinely in-flight.
+    // Completed entries don't count: complete()/fail() ran, so the prior
+    // action's response was fully processed and applied — a request dispatched
+    // after that point is strictly ordered behind the prior action's server
+    // execution, and there is no skipped render or order uncertainty for
+    // consolidation to repair. Completed entries still linger in the map for
+    // the 100ms doSettle window (useAction reads) and, on a slow connection,
+    // while the Flight stream drains its EOF after complete(). Counting them
+    // latched hadAnyConcurrentActions for back-to-back sequential actions,
+    // which made the LAST action classify as consolidation-needed; the
+    // consolidation refetch omits every concurrently-revalidated segment id
+    // from _rsc_segments, so the server re-ran gated loaders as "new-segment"
+    // — bypassing revalidate(({ isAction }) => ...) on a plain GET (#675).
+    const hadConcurrent = [...inflightActions.values()].some(
+      (a) => !a.completed,
+    );
     if (hadConcurrent) {
       hadAnyConcurrentActions = true;
     }

package/src/browser/rsc-router.tsx

@@ -22,6 +22,7 @@ import type {
 } from "./types.js";
 import type { EventController } from "./event-controller.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
+import { expandSegmentFragments } from "../segment-fragments.js";
 import { initRangoState } from "./rango-state.js";
 import { registerNavigationStore } from "./navigation-store-handle.js";
 import { initPrefetchCache } from "./prefetch/cache.js";
@@ -162,6 +163,16 @@ export async function initBrowserApp(
   const initialPayload =
     await deps.createFromReadableStream<RscPayload>(rscStream);
 
+  // Shell-HIT documents carry replayed segments as VERBATIM stored fragments
+  // (segment-fragments.ts, issue #700); expand them through the browser
+  // deserializer BEFORE any consumer reads the segments (store seed,
+  // renderSegments, history cache). Non-HIT payloads have no envelopes and pay
+  // one field scan. The SSR resume pass ran the same expansion (ssr-root.tsx),
+  // so the hydrated tree matches the server-rendered one by construction.
+  await expandSegmentFragments(initialPayload.metadata?.segments, (stream) =>
+    deps.createFromReadableStream(stream),
+  );
+
   // Extract themeConfig and initialTheme from payload if not explicitly provided
   // This allows virtual entries to work without importing the router
   const effectiveThemeConfig =

package/src/cache/cache-scope.ts

@@ -285,10 +285,19 @@ export class CacheScope {
       // partial: evict the entry (self-heal - the re-render re-caches under the
       // same key) and report it as corruption, distinct from a transient infra
       // error (handled by the outer catch).
+      //
+      // Shell-HIT tail (_shellFragmentPayload, issue #700): skip the decode and
+      // carry the stored fragment strings verbatim — the payload consumers
+      // expand them (segment-fragments.ts). Read off the ambient context at the
+      // same point the cache key was resolved (getDefaultRouteCacheKey), so the
+      // flag shares fate with the key: a disrupted ALS already missed the
+      // seeded record and degraded to the full tail.
       let segments: ResolvedSegment[];
       try {
-        const { deserializeSegments } = await import("./segment-codec.js");
-        segments = await deserializeSegments(cached.segments);
+        const codec = await import("./segment-codec.js");
+        segments = _getRequestContext()?._shellFragmentPayload
+          ? await codec.fragmentSegments(cached.segments)
+          : await codec.deserializeSegments(cached.segments);
       } catch (error) {
         reportCacheError(
           error,

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

@@ -137,6 +137,13 @@ const warnedNoKvReadInvalidation = new Set<string>();
  */
 const warnedTagInvalidationTtlFloor = new Set<string>();
 
+/**
+ * Stores (by namespace) already warned about the shell family being inert
+ * (getShell/putShell no-op without a KV namespace), so a ppr route hitting the
+ * silent fail-open warns once per isolate instead of on every request.
+ */
+const warnedShellFamilyInert = new Set<string>();
+
 /**
  * Stores (by namespace) already warned that tag invalidation is writing KV
  * markers with no expiry (tagInvalidationTtl unset), so the unbounded-growth
@@ -227,6 +234,13 @@ interface KVShellEnvelope {
   i?: string;
   /** Capture data snapshot: recorded cache-store hits/writes for HIT parity */
   sn?: import("../types.js").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 KV round trip —
+   * their holes only a handler re-run can fill.
+   */
+  lh?: boolean;
 }
 
 /**
@@ -1635,6 +1649,27 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   // still applies: shell entries carry tags/taggedAt and are checked against the
   // same KV markers isGloballyInvalidated() reads for every other tier.
 
+  /**
+   * Warn once per isolate that the shell family is inert: getShell/putShell
+   * are ONLY called for routes that declared the `ppr` path option, so firing
+   * here (not in the constructor) scopes the warning to apps that actually
+   * use PPR — a KV-less CFCacheStore is a perfectly fine config otherwise.
+   * Without it, the correctness-first fail-open (issue #651) is invisible:
+   * every ppr route is a permanent MISS with zero diagnostics.
+   * @internal
+   */
+  private warnShellFamilyInertOnce(): void {
+    this.warnOncePerNamespace(
+      warnedShellFamilyInert,
+      `[CFCacheStore] a ppr route resolved to this store, but no KV namespace ` +
+        `is configured, so the shell family (getShell/putShell) is a no-op: ` +
+        `every ppr route stays a permanent shell MISS (the page still serves ` +
+        `via a full render). Bind a KV namespace and pass it — ` +
+        `new CFCacheStore({ ctx, kv: env.CACHE_KV }) — or use a shell-capable ` +
+        `store via createRouter({ cache }).`,
+    );
+  }
+
   /**
    * 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
@@ -1645,7 +1680,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   async getShell(
     key: string,
   ): Promise<{ entry: ShellCacheEntry; shouldRevalidate?: boolean } | null> {
-    if (!this.kv) return null;
+    if (!this.kv) {
+      this.warnShellFamilyInertOnce();
+      return null;
+    }
     try {
       const kvKey = this.toKVKey(`shell:${key}`);
       const { value: envelope, timedOut } =
@@ -1678,6 +1716,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           buildVersion: envelope.bv,
           initialTheme: envelope.i,
           snapshot: envelope.sn,
+          handlerLiveHoles: envelope.lh,
           createdAt: envelope.c,
         },
         shouldRevalidate,
@@ -1701,7 +1740,11 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     tags?: string[],
   ): Promise<void> {
     // KV-only tier: needs a KV namespace and waitUntil (writes are non-blocking).
-    if (!this.kv || !this.waitUntil) return;
+    if (!this.kv) {
+      this.warnShellFamilyInertOnce();
+      return;
+    }
+    if (!this.waitUntil) return;
     try {
       const ttl = resolveTtl(ttlSeconds, this.defaults, DEFAULT_FUNCTION_TTL);
       const swrWindow = resolveSwrWindow(swrSeconds, this.defaults);
@@ -1745,6 +1788,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
               ta: taggedAt,
               i: entry.initialTheme,
               sn: entry.snapshot,
+              lh: entry.handlerLiveHoles,
             };
             return this.kv!.put(kvKey, JSON.stringify(envelope), {
               expirationTtl: totalTtl,
@@ -2260,6 +2304,20 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * silently reporting success while other requests/colos serve stale data. The
    * 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).
+   */
+  async isTagsInvalidatedSince(
+    tags: string[],
+    sinceMs: number,
+  ): Promise<boolean> {
+    return this.isGloballyInvalidated(tags, sinceMs);
+  }
+
   async invalidateTags(tags: string[]): Promise<void> {
     if (tags.length === 0) return;
     const invalidatedAt = Date.now();

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

@@ -30,6 +30,8 @@ const ITEM_CACHE_REGISTRY_KEY = "__rsc_router_item_cache_registry__";
 const SHELL_CACHE_REGISTRY_KEY = "__rsc_router_shell_cache_registry__";
 const TAG_INDEX_REGISTRY_KEY = "__rsc_router_tag_index_registry__";
 const KEY_TAGS_REGISTRY_KEY = "__rsc_router_key_tags_registry__";
+const TAG_INVALIDATED_AT_REGISTRY_KEY =
+  "__rsc_router_tag_invalidated_at_registry__";
 
 /**
  * Get or create a named Map from a globalThis-backed registry.
@@ -194,6 +196,14 @@ export class MemorySegmentCacheStore<
   private tagIndex: Map<string, Set<string>>;
   /** 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.
+   */
+  private tagInvalidatedAt: Map<string, number>;
   readonly defaults?: CacheDefaults;
   readonly keyGenerator?: (
     ctx: RequestContext<TEnv>,
@@ -228,6 +238,10 @@ export class MemorySegmentCacheStore<
         KEY_TAGS_REGISTRY_KEY,
         options.name,
       );
+      this.tagInvalidatedAt = getNamedMap<number>(
+        TAG_INVALIDATED_AT_REGISTRY_KEY,
+        options.name,
+      );
     } else {
       this.cache = new Map<string, CachedEntryData>();
       this.responseCache = new Map<string, CachedResponseEntry>();
@@ -235,6 +249,7 @@ export class MemorySegmentCacheStore<
       this.shellCache = new Map<string, CachedShellEntry>();
       this.tagIndex = new Map<string, Set<string>>();
       this.keyTags = new Map<string, Set<string>>();
+      this.tagInvalidatedAt = new Map<string, number>();
     }
     this.defaults = options?.defaults;
     this.keyGenerator = options?.keyGenerator;
@@ -457,8 +472,25 @@ export class MemorySegmentCacheStore<
     }
   }
 
+  async isTagsInvalidatedSince(
+    tags: string[],
+    sinceMs: number,
+  ): Promise<boolean> {
+    for (const tag of tags) {
+      const at = this.tagInvalidatedAt.get(tag);
+      // >= so a same-millisecond invalidation wins (freshness over staleness),
+      // matching the CF marker comparison.
+      if (at !== undefined && at >= sinceMs) return true;
+    }
+    return false;
+  }
+
   async invalidateTags(tags: string[]): Promise<void> {
+    const invalidatedAt = Date.now();
     for (const tag of tags) {
+      // Marker first: build-shell entries evict by marker comparison even when
+      // no runtime entry currently carries the tag (tagIndex miss below).
+      this.tagInvalidatedAt.set(tag, invalidatedAt);
       const keys = this.tagIndex.get(tag);
       if (!keys || keys.size === 0) continue;
 

package/src/cache/segment-codec.ts

@@ -11,6 +11,7 @@
 import type { ResolvedSegment } from "../types.js";
 import type { SerializedSegmentData } from "./types.js";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
+import { segmentFragment } from "../segment-fragments.js";
 import {
   renderToReadableStream,
   createTemporaryReferenceSet,
@@ -206,6 +207,52 @@ export async function serializeSegments(
   );
 }
 
+/**
+ * Build ResolvedSegments that carry the STORED fragment strings verbatim
+ * instead of decoding them (PPR fast-path payload splice, issue #700; see
+ * segment-fragments.ts). The ReactNode fields (component/layout/loading)
+ * become {@link segmentFragment} envelopes the outer Flight render serializes
+ * as a string copy; the CONSUMER (SSR resume + browser hydration) expands them
+ * through its own deserializer. Loader data fields are NOT enveloped — they
+ * are consumer data of any shape (a marker there could collide) and decode
+ * server-side exactly as deserializeSegments does; on the doc/prerender
+ * records this path serves they are absent in practice (loaders are never
+ * cached with the route record).
+ *
+ * The loading "null" sentinel decodes here (not on the consumer): loading:null
+ * must survive as null, and shipping the raw sentinel would change the
+ * deduplicateLoaderSegments loading-presence check.
+ */
+export async function fragmentSegments(
+  data: SerializedSegmentData[],
+): Promise<ResolvedSegment[]> {
+  return Promise.all(
+    data.map(async (item): Promise<ResolvedSegment> => {
+      const loadingIsNullSentinel = item.encodedLoading === "null";
+      const [loaderData, loaderDataPromise] = await Promise.all([
+        rscDeserialize(item.encodedLoaderData),
+        rscDeserialize(item.encodedLoaderDataPromise),
+      ]);
+      return {
+        ...item.metadata,
+        // Envelopes ride ReactNode-typed fields; the consumer expansion pass
+        // (segment-fragments.ts) replaces them before any render reads them.
+        component: segmentFragment(item.encoded) as unknown,
+        layout: item.encodedLayout
+          ? (segmentFragment(item.encodedLayout) as unknown)
+          : undefined,
+        loading: loadingIsNullSentinel
+          ? null
+          : item.encodedLoading !== undefined
+            ? (segmentFragment(item.encodedLoading) as unknown)
+            : undefined,
+        loaderData,
+        loaderDataPromise,
+      } as ResolvedSegment;
+    }),
+  );
+}
+
 /**
  * Deserialize segments from storage.
  * Reconstructs ResolvedSegment objects from RSC-serialized data.

package/src/cache/types.ts

@@ -196,6 +196,20 @@ 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 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.
+   * 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>;
 }
 
 /**

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: 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.
+ */
+const TAG_MARKER_TTL_SECONDS = 365 * 24 * 60 * 60;
 
 /** Stored envelope for a segment-tree entry (get/set). */
 interface VercelSegmentEnvelope {
@@ -191,6 +202,13 @@ 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;
 }
 
 /** Read-path outcome for the debug sink. */
@@ -781,6 +799,7 @@ export class VercelCacheStore<
         buildVersion: env.bv,
         initialTheme: env.i,
         snapshot: env.sn,
+        handlerLiveHoles: env.lh,
         createdAt: env.c,
       },
       shouldRevalidate,
@@ -815,6 +834,7 @@ export class VercelCacheStore<
         t: safeTags.length > 0 ? safeTags : undefined,
         i: entry.initialTheme,
         sn: entry.snapshot,
+        lh: entry.handlerLiveHoles,
       };
       // write() enforces the 2 MB per-item ceiling (withinSizeLimit): an
       // oversized shell prelude is reported and skipped (fail-open to a full
@@ -833,6 +853,40 @@ 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.
+   */
+  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 +896,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 +1163,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 } = 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 +1179,7 @@ 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,
     };
   }
 

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,