@rangojs/router 0.16.0 → 0.18.0

package/dist/types/cache/tag-invalidation.d.ts

@@ -21,7 +21,32 @@
  * primitive for each tag. A single configured store (the common case) owns its
  * own tag index and distributed invalidation - there is no separate
  * tag-invalidation store.
+ *
+ * Both call invalidateTags() synchronously, inside the request (#973). A store
+ * masks the tags for the rest of the request before its first await (the
+ * built-in stores write their per-request marker state there), so the request
+ * that ran either verb reads its own writes; revalidateTag() leaves only the
+ * durable remainder (KV marker put, tag purge, expireTag) to waitUntil.
+ * Invariant: the mask only turns the invalidating request's hits into misses.
+ * If the durable write then fails, that request paid extra misses, never a
+ * stale read, and other requests read the durable state. Both also record
+ * the tags on the request (markInvalidated), so a "use cache" execution or
+ * stale refresh this request started before one of its own tags was
+ * invalidated is neither joined nor written (cache-runtime.ts). Its own tags
+ * only: a nested "use cache" function's tags do not reach the enclosing
+ * entry (#980), for this gate as for eviction. Not covered (#977): such an
+ * execution in another request, or a loader cache() write, still lands, and
+ * the store accepts it (docs/design/caching.md "Read-your-own-writes").
+ */
+import { type RequestContext } from "../server/request-context.js";
+/** The current position in that order; an execution records it at start. */
+export declare function currentCacheSeq(): number;
+/**
+ * Whether the request invalidated any of `tags` after `since` (a
+ * currentCacheSeq() value an execution recorded when it started): its value
+ * may predate the invalidation, so the request neither joins nor writes it.
  */
+export declare function invalidatedSince(ctx: RequestContext<any, any> | undefined, tags: readonly string[] | undefined, since: number): boolean;
 /**
  * Immediately expire every cache entry tagged with any of `tags`, resolving
  * once in-process invalidation across all configured stores completes.
@@ -47,10 +72,12 @@ export declare function updateTag(...tags: string[]): Promise<void>;
  * This is NOT stale-while-revalidate: like updateTag() it hard-purges, so the
  * next read after the invalidation lands is a miss that re-renders fresh. The
  * only difference from updateTag() is awaitability - revalidateTag() defers the
- * purge off the response path and is not awaited.
+ * durable write off the response path and is not awaited.
  *
- * Use in Route Handlers / webhooks. For read-your-own-writes inside a Server
- * Action, use updateTag() instead so the action's own response is fresh.
+ * Read-your-own-writes (#973): each built-in store masks the tags for the rest
+ * of this request before revalidateTag() returns, so a Server Action's own
+ * re-render after it is fresh, as after `await updateTag()`. Other requests see
+ * the invalidation once the durable write lands.
  *
  * Fire-and-forget: because this returns void and runs in the background, a
  * failed durable marker write (e.g. a transient KV outage) is NOT surfaced to

package/dist/types/cache/taint.d.ts

@@ -1,7 +1,7 @@
 /**
  * Taint symbol for request-scoped objects.
  *
- * Objects branded with NOCACHE_SYMBOL (ctx, env, req) are excluded from
+ * Objects branded with NOCACHE_SYMBOL (ctx objects) are excluded from
  * "use cache" cache keys and trigger handle capture mode so that side
  * effects (breadcrumbs, metadata) are recorded and replayed on cache hit.
  */

package/dist/types/cache/types.d.ts

@@ -99,7 +99,11 @@ export interface SegmentCacheStore<TEnv = unknown> {
      */
     get(key: string): Promise<CacheGetResult | null | CacheReadError>;
     /**
-     * Store entry data with TTL
+     * Store entry data with TTL. Resolve once a later `get(key)` from the same
+     * location observes the entry: the route cache() write runs in a background
+     * task, and a PPR shell capture awaits that task before it reads the entry
+     * back (#957). A store that resolves earlier makes the capture re-render
+     * the page instead of replaying the entry.
      * @param key - Cache key
      * @param data - Serialized entry data
      * @param ttl - Time-to-live in seconds
@@ -156,8 +160,14 @@ export interface SegmentCacheStore<TEnv = unknown> {
      * upgrade — the reactVersion field on the entry gates that at read time).
      * @param key - Cache key
      * @param entry - The shell prelude/postponed/version/createdAt bundle
-     * @param ttlSeconds - Time-to-live in seconds
-     * @param swrSeconds - Optional stale-while-revalidate window in seconds
+     * @param ttlSeconds - Time-to-live in seconds: the route's `ppr.ttl`
+     *   (undefined: the store's default), capped to the route cache() entry
+     *   the capture replayed or wrote. A capped window arrives in whole
+     *   seconds, rounded up, with ttl + swr at least 1; its ttl can be 0 (a
+     *   shell stale from the start, captured from a record inside its swr
+     *   window).
+     * @param swrSeconds - Optional stale-while-revalidate window in seconds,
+     *   under the same cap
      * @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,
@@ -169,6 +179,40 @@ export interface SegmentCacheStore<TEnv = unknown> {
      *   without acknowledgements.
      */
     putShell?(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | "uncacheable" | void>;
+    /**
+     * @internal The document serve path's shell read, for built-in stores. The
+     * serve path prefers it over getShell: it resolves with the entry and the
+     * raw (decoded) prelude, the snapshot on its own promise, and the read's
+     * `debugPerformance` stats. CFCacheStore's layout keeps the snapshot behind
+     * the prelude, so its HIT can commit before the snapshot is read;
+     * VercelCacheStore reads the whole entry and decodes the prelude once per
+     * memoized shell (issue #941, docs/design/shell-entry-layout.md). Not part
+     * of the custom-store contract.
+     */
+    readShellDocument?(key: string, options?: ShellDocumentReadOptions): Promise<ShellDocumentRead | null>;
+    /**
+     * @internal How long (ms) this store's isolate memos (shell, tag markers)
+     * can serve a read that predates a tag invalidation made elsewhere. After
+     * updateTag()/revalidateTag(), the response's fresh-reads cookie lasts the
+     * longest of these, and the same user's requests skip the memos meanwhile.
+     * Absent or 0: nothing to cover.
+     */
+    readonly freshReadsWindowMs?: number;
+    /**
+     * @internal Drop this isolate's memoized copy of a shell (shell-memo.ts) so
+     * the next read goes to the store. A HIT whose doc record failed to decode
+     * calls it after replacing the entry with a tombstone: the memoized copy
+     * holds the same record. Built-in stores only; not part of the custom-store
+     * contract.
+     */
+    dropShellMemo?(key: string): void;
+    /**
+     * @internal The largest shell entry (prelude, postponed state, and snapshot
+     * bytes) this store can hold in one value. The capture refuses a bigger
+     * entry instead of letting the write fail inside waitUntil. Absent: the
+     * capture applies DEFAULT_SHELL_ENTRY_MAX_BYTES (Cloudflare KV's 25 MiB).
+     */
+    readonly maxShellEntryBytes?: number;
     /**
      * Declares the shell family present-but-inert: getShell/putShell exist but
      * no-op (a custom store whose backing tier is conditionally unavailable).
@@ -210,6 +254,20 @@ export interface SegmentCacheStore<TEnv = unknown> {
      * APIs delegate to. Receives ALL of one invalidation call's tags at once so
      * stores can batch their work (e.g. a single CDN purge request rather than
      * one per tag). Stores that do not support tags simply omit this method.
+     *
+     * Both verbs call it synchronously, inside the request that invalidates
+     * (#973); revalidateTag() then hands the returned promise to waitUntil
+     * without awaiting it. Read-your-own-writes for that request comes from
+     * what the store does before its first await: record the tags as
+     * invalidated in state its reads consult for the rest of the request (the
+     * built-in stores key a map by the request's root context and the store,
+     * so contexts derived from the request share it, and compare each hit's
+     * tags and write time against it), then start the
+     * durable write. Such a mask must only ever turn hits into misses, and only
+     * in that request: a durable write that later fails then costs extra
+     * misses, never a stale read. A store that records nothing before its
+     * first await still works; the request that ran revalidateTag() can read
+     * entries the invalidation covers until the durable write lands.
      * @param tags - The cache tags to invalidate
      */
     invalidateTags?(tags: string[]): Promise<void>;
@@ -295,12 +353,13 @@ export interface ShellCacheEntry {
      */
     buildVersion?: string;
     /**
-     * The initialTheme the CAPTURE render was built with (the derived context's
-     * reqCtx.theme). The resume tail must render ThemeProvider with the SAME
+     * The initialTheme the CAPTURE render was built with: the no-cookie default
+     * (payloadInitialTheme, rsc/full-payload.ts), never the capturing visitor's
+     * theme (#971). The resume tail must render ThemeProvider with the SAME
      * initialTheme the frozen prelude was rendered with: React resume requires the
      * tree above the holes to match the prerendered tree, and initialTheme is
      * per-request METADATA, not part of the cached segments — a visitor whose
-     * theme differs from the capturer's would otherwise produce a divergent resume
+     * theme differs from the capture's would otherwise produce a divergent resume
      * tree (broken stitching/hydration). The visitor's real theme is applied
      * pre-paint by the FOUC script and re-synced from the cookie post-mount by
      * ThemeProvider.
@@ -321,17 +380,21 @@ export interface ShellCacheEntry {
      */
     snapshot?: ShellSnapshotRecord[];
     /**
-     * The key of the CANONICAL document segment record inside `snapshot` — the
-     * one navigation replay can actually consume (resolved under the implicit
-     * doc namespace at capture; see CacheScope.cacheRoute). Replay eligibility
-     * requires this exact record: the snapshot also carries incidentally
-     * recorded explicit-tier records (RecordingShellStore passthroughs) whose
-     * keys a partial lookup can never resolve, and counting those declared
-     * entries "replayable" that always missed (`snapshot-miss` flip-flop).
-     * Absent on entries captured before the field existed OR when the capture
-     * recorded no doc record (cache(false)/condition-false routes, prerender
-     * short-circuit) — both read as `no-segment-snapshot`; recapture heals the
-     * former.
+     * Records the capture dropped from `snapshot` because no reader of this
+     * entry consumes them, by family (`item:4/response:1`). Diagnostic only: the
+     * HIT tail timing reports it next to the kept records. See
+     * docs/design/shell-entry-layout.md ("Record only what a HIT reads").
+     */
+    prunedRecords?: string;
+    /**
+     * The key of the document segment record inside `snapshot`: the handler
+     * layer every HIT replays (a document HIT tail looks the record up by this
+     * key, so a store keyGenerator or a build-time capture host cannot send it
+     * elsewhere) and the record navigation replay consumes (resolved under the
+     * implicit doc namespace at capture; see CacheScope.cacheRoute). A capture
+     * that ran handlers always stores it; only a prerender-served entry (the
+     * prerender store supplies the handler layer) has none. A document entry
+     * without it is served as a MISS.
      */
     docKey?: string;
     /**
@@ -340,26 +403,6 @@ export interface ShellCacheEntry {
      * the partial request's headers and middleware state are not document state.
      */
     navigationOnly?: true;
-    /**
-     * 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;
-    /**
-     * 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;
 }
@@ -374,12 +417,122 @@ export type DocumentShellCacheEntry = ShellCacheEntry & {
     prelude: string;
     postponed: string | null;
 };
+/** @internal Options of {@link SegmentCacheStore.readShellDocument}. */
+export interface ShellDocumentReadOptions {
+    /**
+     * Tag names the route declares for its shell (`ppr.tags`), known before the
+     * entry is read: their marker reads can start alongside the entry read.
+     */
+    tagHints?: readonly string[];
+}
+/**
+ * @internal Why a prelude-first read's snapshot is missing although the entry
+ * stored one: `unavailable` (the read timed out or failed; the entry may be
+ * sound) or `corrupt` (the bytes arrived and do not parse; the store evicted
+ * the entry).
+ */
+export type ShellSnapshotFailure = "unavailable" | "corrupt";
+/**
+ * @internal Result of {@link SegmentCacheStore.readShellDocument}.
+ */
+export interface ShellDocumentRead {
+    /** The entry without its prelude and snapshot (delivered separately). */
+    entry: ShellCacheEntry;
+    /** Raw prelude bytes (empty for a navigationOnly entry). */
+    prelude: Uint8Array;
+    shouldRevalidate?: boolean;
+    /**
+     * The capture snapshot, read after the prelude. Resolves undefined when the
+     * entry has none or it could not be read (`snapshotFailure` says which); a
+     * document HIT then cannot replay its doc record and degrades
+     * (rsc-rendering.ts serveShellHit).
+     * Never rejects.
+     */
+    snapshot: Promise<ShellSnapshotRecord[] | undefined>;
+    /**
+     * Why `snapshot` resolved undefined although the entry stored one, or
+     * undefined when it did not fail. A document HIT that cannot replay its
+     * doc record replaces the entry only when it is broken, not when its read
+     * was merely slow (rsc-rendering.ts serveShellHit). Never rejects.
+     */
+    snapshotFailure?: Promise<ShellSnapshotFailure | undefined>;
+    /**
+     * Where the read's time and bytes went, for the `debugPerformance` metrics
+     * (rsc-rendering.ts) and the store's own debug trace. Present only when one
+     * of them is on for the request.
+     */
+    stats?: ShellReadStats;
+}
+/**
+ * @internal Sub-steps of a prelude-first shell read. Times are ms. workerd
+ * advances its clock only on I/O, so a CPU-only field
+ * (`snapshot.parseMs`) reads 0 on a deployed worker: the byte counts are the
+ * cost signal there.
+ */
+export interface ShellReadStats {
+    /**
+     * The tier that answered: `memo` (the store's shell memo), `l1`/`kv`
+     * (CFCacheStore), or `store` (a single-tier store, VercelCacheStore).
+     */
+    tier: "memo" | "l1" | "kv" | "store";
+    /** The per-isolate memo's outcome for this read and its size after it. */
+    memo?: {
+        hit: boolean;
+        bytes: number;
+    };
+    /**
+     * A KV read after an L1 attempt: how long the L1 attempt took and why it
+     * missed. The KV fields below then restart from the KV read.
+     */
+    l1MissMs?: number;
+    l1MissReason?: string;
+    /** Cache API match (L1) or KV get (KV) until the body was available. */
+    matchMs?: number;
+    /** Frame head read (I/O) and parse. */
+    headMs?: number;
+    /** Prelude bytes read. */
+    preludeMs?: number;
+    /** Tag-marker read, start to resolve (runs alongside the prelude read). */
+    markerMs?: number;
+    /** How long the read waited for the marker after the prelude was read. */
+    markerWaitMs?: number;
+    /**
+     * The marker check was awaited after the entry read (VercelCacheStore), not
+     * alongside the prelude read; hinted reads still start with the entry read.
+     */
+    markerSerial?: true;
+    /**
+     * How the isolate marker memo answered the shell's tags (the most
+     * store-bound outcome across them): `fresh`, `stale` (served, refreshing in
+     * the background), `read` (from the store), `bypass` (fresh-reads cookie).
+     */
+    markerMemo?: "fresh" | "stale" | "read" | "bypass";
+    /** Tags whose marker reads were started before the entry's head (hints). */
+    markerHinted?: readonly string[];
+    /** When the hinted marker reads started (performance.now()). */
+    markerHintStartedAt?: number;
+    /** How many of the shell's tags were hinted. */
+    markerHintHits?: number;
+    /** How long the hinted marker reads ran before the entry named its tags. */
+    markerLeadMs?: number;
+    /** The request carried the fresh-reads cookie: no isolate memo was used. */
+    freshReads?: true;
+    headBytes?: number;
+    preludeBytes?: number;
+    /** Number of the shell's tags the marker read covered. */
+    tags?: number;
+    /** Filled after the commit, once the snapshot has been read. */
+    snapshot?: {
+        readMs: number;
+        parseMs: number;
+        bytes: number;
+    };
+}
 /**
  * The families a shell snapshot pins. The item/segment/response families are
  * cache-store reads/writes (recorded by RecordingShellStore); the loader family
- * pins the settled CONTAINER of a bake-lane loader (a loader on an entry with
- * no renderable loading(), executed during capture — see
- * docs/design/loader-container-bake.md). Excludes the shell family itself
+ * pins the settled CONTAINER of a bake-lane loader (lane rule: see
+ * resolveLoaderData, loader-cache.ts). Excludes the shell family itself
  * (getShell/putShell) — the snapshot rides INSIDE a shell entry, so recording
  * it would be self-referential.
  */
@@ -399,12 +552,20 @@ export interface ShellSnapshotLoaderValue {
      * 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.
+     * the pin and does not run the loader body (unless `runs`). Absent on
+     * pre-bit snapshots, which keep the gated path.
      */
     holes?: 0 | 1;
+    /**
+     * 1 when the capture saw a loader push it could not record (a deferred
+     * push, one with masked nested promises, or one made outside any loader
+     * body): a HIT then still runs the loader body in the background
+     * (pin-first) so those pushes reach the page. 0: a hole-free record is
+     * served from the pin alone and its body does not run on a HIT. Absent (a
+     * snapshot written before the bit, which lacks the loader-owned pushes)
+     * reads as 1, so the body supplies them.
+     */
+    runs?: 0 | 1;
 }
 /** A serialized cached Response for the response family of a shell snapshot. */
 export interface ShellSnapshotResponseValue {
@@ -481,6 +642,11 @@ export interface CachedEntryData {
      *  (see handle-snapshot.ts encodeHandles) so Promise/ReactNode handle values
      *  round-trip through JSON-serializing stores instead of being flattened. */
     handles: string;
+    /**
+     * Owning loader ids index-aligned with the decoded `handles` values
+     * (HandleOwners). Absent: every value restores as a plain replay.
+     */
+    handleOwners?: HandleOwners;
     /** Expiration timestamp (ms since epoch) */
     expiresAt: number;
     /** Cache tags for invalidation */
@@ -520,3 +686,13 @@ export interface CacheDefaults {
  * Structure: { handleName: [values...] }
  */
 export type SegmentHandleData = Record<string, unknown[]>;
+/**
+ * segmentId -> handleName -> the owning loader id of each recorded value, by
+ * index (null: not owned). Only a PPR shell capture writes owners: the
+ * settled pushes of the loader bodies it ran (an `ssr: false` loader's own,
+ * the loaders it awaits, and its own cache() replays), which the record keeps
+ * because the prelude rendered them. restoreHandles replays an owned value
+ * through HandleStore.pushReplayed, so a loader that does run on the HIT
+ * replaces it with its live push.
+ */
+export type HandleOwners = Record<string, Record<string, (string | null)[]>>;

package/dist/types/cache/vercel/vercel-cache-store.d.ts

@@ -5,9 +5,10 @@
  * `@vercel/functions`). It is the production store analogue to CFCacheStore, but
  * far smaller: Vercel's Runtime Cache already IS a distributed, tag-aware cache
  * (regional storage, global tag-expire within ~300ms), so none of CFCacheStore's
- * L1/L2 tiering, KV tag-marker comparison, marker memoization, or per-tier
- * timeout budgets are needed here - the platform does that work. What this store
- * adds on top of the raw primitive is the parts Vercel does NOT give us:
+ * L1/L2 tiering or per-tier timeout budgets are needed here - the platform does
+ * that work. Tag markers exist only for the shell family (`tm`, see
+ * isTagsInvalidatedSince), and only PPR shell reads memoize them. What this
+ * store adds on top of the raw primitive is the parts Vercel does NOT give us:
  *
  *   1. Stale-while-revalidate. `getCache` has no stale-but-serve: a TTL'd entry
  *      simply becomes a miss. We store our own {staleAt, expiresAt} envelope and
@@ -30,8 +31,9 @@
  * `getCache(...)` result, which satisfies the shape structurally. That keeps the
  * router free of a hard Vercel dependency.
  */
-import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, CacheReadError } from "../types.js";
-import type { RequestContext } from "../../server/request-context.js";
+import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, ShellDocumentRead, ShellDocumentReadOptions, CacheReadError } from "../types.js";
+import { type RequestContext } from "../../server/request-context.js";
+import { type StoreMemoOptions } from "../shell-memo.js";
 /**
  * Minimal structural shape of the Vercel Runtime Cache returned by `getCache()`
  * from `@vercel/functions`. Declared locally so @rangojs/router carries no hard
@@ -69,7 +71,7 @@ export declare const VERCEL_MAX_TAGS_PER_ITEM: number;
 /** Max tag length in UTF-8 bytes accepted by Vercel; longer tags are skipped. */
 export declare const VERCEL_MAX_TAG_BYTES: number;
 /** Read-path outcome for the debug sink. */
-export type VercelCacheReadOutcome = "miss" | "fresh" | "stale-revalidate" | "expired" | "corrupt" | "error";
+export type VercelCacheReadOutcome = "miss" | "memo-hit" | "fresh" | "stale-revalidate" | "expired" | "corrupt" | "error";
 /** Diagnostic event emitted on every read when `debug` is set. */
 export interface VercelCacheReadDebugEvent {
     op: "get" | "getItem" | "getResponse" | "getShell";
@@ -100,10 +102,13 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
      */
     cache: VercelRuntimeCache;
     /**
-     * `waitUntil` from `@vercel/functions`. Used only to run the stale-read lock
-     * write (herd dampening) off the response path - the router already
-     * backgrounds the actual writes. When omitted, the lock write runs detached
-     * (fire-and-forget) instead.
+     * `waitUntil` from `@vercel/functions`. Keeps two background reads/writes
+     * alive past the response: the stale-read lock write (herd dampening; the
+     * router already backgrounds the actual writes) and the PPR shell reads'
+     * tag-marker memo refreshes (`memo.markerMaxStaleMs`). When omitted, both
+     * run detached (fire-and-forget), and the platform may end a refresh when
+     * the response ends; the next read past the stale window then reads the
+     * marker itself.
      */
     waitUntil?: (promise: Promise<unknown>) => void;
     /**
@@ -136,6 +141,26 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
      * receives the structured VercelCacheReadDebugEvent.
      */
     debug?: VercelCacheDebug;
+    /**
+     * Per-process memos ({@link StoreMemoOptions}), kept per `cache` handle:
+     * create the `getCache()` handle once per process, not per request, or the
+     * memos never hit. `shellMs` (default 2000) and `shellMaxBytes` (default
+     * 16 MiB) size the PPR shell memo; `markerFreshMs` (default 300) and
+     * `markerMaxStaleMs` (default 2000) the memo of the tag markers
+     * `invalidateTags()` writes, which PPR shell reads use
+     * (stale-while-revalidate). The process that invalidates writes the new
+     * marker into its memo; another process in the region rejects a memoized
+     * shell once its marker memo sees it (up to `markerMaxStaleMs`). The
+     * markers are a regional `cache.set` (only `expireTag` is global), so
+     * another region serves a shell it memoized before the invalidation until
+     * its window passes, where without the memo `expireTag` removes it within
+     * about 300 ms; a platform `expireTag` issued outside rango is likewise
+     * seen once the window passes. The response of a request that ran
+     * `updateTag()` / `revalidateTag()` sets the fresh-reads cookie, and the
+     * same user's requests carrying it skip both memos. `{ shellMs: 0 }` turns
+     * the shell memo off, `{ markerFreshMs: 0 }` the marker memo.
+     */
+    memo?: StoreMemoOptions;
 }
 /**
  * Vercel Runtime Cache-backed segment cache store.
@@ -170,12 +195,18 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
  * import { getCache, waitUntil } from "@vercel/functions";
  * import { VercelCacheStore } from "@rangojs/router/cache";
  *
+ * // One handle per process: getCache() resolves the platform cache on every
+ * // call, and the PPR shell and tag-marker memos are kept per handle.
+ * // `process.env` (not `import.meta.env`, which needs a VITE_ prefix and
+ * // would be undefined here) so cross-deploy busting via `version` works.
+ * const runtimeCache = getCache({
+ *   namespace: process.env.VERCEL_DEPLOYMENT_ID,
+ * });
+ *
  * export const router = createRouter({
  *   cache: () => ({
  *     store: new VercelCacheStore({
- *       // `process.env` (not `import.meta.env`, which needs a VITE_ prefix and
- *       // would be undefined here) so cross-deploy busting via `version` works.
- *       cache: getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID }),
+ *       cache: runtimeCache,
  *       waitUntil,
  *       defaults: { ttl: 60, swr: 300 },
  *     }),
@@ -191,6 +222,16 @@ export declare class VercelCacheStore<TEnv = unknown> implements SegmentCacheSto
     private readonly waitUntil?;
     private readonly version?;
     private readonly maxItemBytes;
+    private readonly memo;
+    private readonly handleMemos;
+    /** @internal SegmentCacheStore.freshReadsWindowMs */
+    readonly freshReadsWindowMs: number;
+    /**
+     * @internal SegmentCacheStore.maxShellEntryBytes: the item cap, less the
+     * base64 expansion of the prelude the shell envelope stores (the capture
+     * measures raw prelude bytes).
+     */
+    readonly maxShellEntryBytes: number;
     private readonly name?;
     private readonly debug?;
     constructor(options: VercelCacheStoreOptions<TEnv>);
@@ -210,6 +251,46 @@ export declare class VercelCacheStore<TEnv = unknown> implements SegmentCacheSto
         entry: ShellCacheEntry;
         shouldRevalidate?: boolean;
     } | null>;
+    /**
+     * @internal The document serve path's read (SegmentCacheStore
+     * .readShellDocument): the same read as getShell, with the prelude decoded
+     * here, once per memoized shell rather than once per HIT, and the read's
+     * `debugPerformance` stats. The runtime cache returns a parsed value, so
+     * there is no prelude-first read and the tag-marker read follows the entry
+     * read (`markerSerial`).
+     */
+    readShellDocument(key: string, options?: ShellDocumentReadOptions): Promise<ShellDocumentRead | null>;
+    /** @internal SegmentCacheStore.dropShellMemo */
+    dropShellMemo(key: string): void;
+    /**
+     * getShell's read, shared with readShellDocument: the shell memo first
+     * (shell-memo.ts), then the runtime cache. A memoized shell still runs the
+     * tag-marker check; `memoized` is the memo slot's value when the read came
+     * from, or went into, the memo (readShellDocument keeps the decoded prelude
+     * there).
+     */
+    private readShell;
+    /**
+     * The shell's tag-marker check, timed into `stats`. Markers a prefetch
+     * already started (hinted tags) are awaited, not re-read; the check itself
+     * always uses the entry's own tags.
+     */
+    private shellTagsInvalidated;
+    /**
+     * Start the tm-marker reads of the tags this shell key carried last time
+     * (and the route's static tags) alongside the entry read.
+     */
+    private prefetchShellMarkers;
+    /**
+     * A tag's latest invalidatedAt (or null). With `isolateMemo` (PPR shell
+     * reads only) through the per-process marker memo (isolate-tag-memo.ts):
+     * fresh values are used as is, stale ones are used and refreshed in the
+     * background, older ones block on the runtime-cache read. A request
+     * carrying the fresh-reads cookie skips the memo. A failed read rejects and
+     * is never memoized. The shell write gate and build shells
+     * (isTagsInvalidatedSince) read the runtime cache every time.
+     */
+    private readTagMarker;
     putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | void>;
     /**
      * Shell tag-generation gate (SegmentCacheStore.isTagsInvalidatedSince).
@@ -218,7 +299,24 @@ export declare class VercelCacheStore<TEnv = unknown> implements SegmentCacheSto
      * generation start wins; read errors fail open like the CF marker check.
      */
     isTagsInvalidatedSince(tags: string[], sinceMs: number): Promise<boolean>;
+    private tagsInvalidatedSince;
     invalidateTags(tags: string[]): Promise<void>;
+    /**
+     * The request-local half of invalidateTags(), run before its first await
+     * (#973): see requestInvalidations. revalidateTag() waits for nothing
+     * after it.
+     */
+    private maskTagsForRequest;
+    /**
+     * Whether this request invalidated one of `tags` through this store at or
+     * after `taggedAt`. `>=`, as the marker check: an entry written in the
+     * invalidation's millisecond may hold a value computed before it, so it
+     * misses (a false miss, never a stale read). An entry without a stamp was
+     * written before the stamp existed and counts as older.
+     */
+    private maskedForRequest;
+    /** A data read's mask check: reports the miss and returns true when masked. */
+    private maskedMiss;
     private toStoreKey;
     private write;
     /**

package/dist/types/client.d.ts

@@ -1,4 +1,5 @@
 import { Component, type ReactNode } from "react";
+import * as Html from "./html.js";
 import { type ClientErrorBoundaryFallbackProps } from "./types";
 /**
  * Outlet component - renders child content in layouts
@@ -125,7 +126,7 @@ interface ErrorBoundaryState {
  * @example
  * ```tsx
  * "use client";
- * import { ErrorBoundary } from "rsc-router/client";
+ * import { ErrorBoundary } from "@rangojs/router/client";
  *
  * function MyComponent() {
  *   return (
@@ -172,14 +173,13 @@ export { useSegments, type SegmentsState, } from "./browser/react/use-segments.j
 export { NavigationProvider, type NavigationProviderProps, } from "./browser/react/NavigationProvider.js";
 export { Link, type LinkProps, type PrefetchStrategy, type StateOrGetter, type LinkState, } from "./browser/react/Link.js";
 export { useLinkStatus, type LinkStatus, } from "./browser/react/use-link-status.js";
-export { ScrollRestoration, useScrollRestoration, type ScrollRestorationProps, } from "./browser/react/ScrollRestoration.js";
+export { useScrollRestoration, type ScrollRestorationProps, } from "./browser/react/ScrollRestoration.js";
 export { type Handle } from "./handle.js";
 export { useHandle } from "./browser/react/use-handle.js";
 export { Meta } from "./handles/meta.js";
-export { MetaTags } from "./handles/MetaTags.js";
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
 export { Script, type ScriptConfig, type ScriptAttributes, } from "./handles/script.js";
-export { Scripts } from "./handles/Scripts.js";
+export { Html };
 export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
 export { createLocationState, useLocationState, type LocationStateDefinition, type LocationStateEntry, type LocationStateOptions, } from "./browser/react/location-state.js";
 export { href, type PatternToPath } from "./href-client.js";