@rangojs/router 0.0.0-experimental.132 → 0.0.0-experimental.133

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

@@ -0,0 +1,349 @@
+// ============================================================================
+// Types
+// ============================================================================
+//
+// Shared public types for the CF cache store: the minimal KVNamespace shape, the
+// debug-event surface, and the store options. Extracted from cf-cache-store.ts
+// so they can be referenced without importing the class; re-exported from
+// cf-cache-store.ts so existing import paths still resolve. The private KV
+// envelope interfaces stay in cf-cache-store.ts with the methods that use them.
+
+// Imported from the canonical home (also publicly exported from src/index.ts /
+// src/index.rsc.ts) so this module shares the one interface rather than
+// declaring a second that could drift.
+import type { ExecutionContext } from "../../types/request-scope.js";
+import type { CacheDefaults } from "../types.js";
+import type { RequestContext } from "../../server/request-context.js";
+
+/**
+ * Minimal Cloudflare KV Namespace interface.
+ * Avoids hard dependency on @cloudflare/workers-types.
+ */
+export interface KVNamespace {
+  get(key: string, options?: { type?: string }): Promise<any>;
+  put(
+    key: string,
+    value: string,
+    options?: { expirationTtl?: number },
+  ): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+/**
+ * One L1 read decision, surfaced when `debug` is enabled. Lets an operator
+ * confirm on a real deployment (e.g. via `wrangler tail`) that the store's
+ * observed inputs match its decision: which tier answered, the entry's status,
+ * the stale/revalidating timestamps, the raw CF `Age` header (so its
+ * unreliability can be seen next to the explicit revalidating-at stamp), and
+ * the measured match/body-read durations (where the latency tail shows up).
+ */
+export interface CFCacheReadDebugEvent {
+  /**
+   * Which read method produced this event. Only the JSON read paths (segment
+   * `get` and function `getItem`) participate in debug; the document
+   * `getResponse` path streams its body and is intentionally out of scope.
+   */
+  op: "get" | "getItem";
+  /** Cache key (without the internal fn:/doc: prefix or version path). */
+  key: string;
+  /**
+   * What the read resolved to:
+   * - l1-fresh / l1-stale-revalidate / l1-revalidating-guarded: L1 hit outcomes
+   * - match-timeout / body-timeout: the L1 latency budgets fired
+   * - match-error: the L1 match() itself rejected (a transient Cache API infra
+   *   error) -- a miss that falls through to L2/KV and is reported cache-read,
+   *   distinct from a genuine l1-miss (absence) so the two are separable
+   * - body-error: the L1 body read failed fast (corrupt/non-JSON body) -- a miss
+   *   that falls through to L2/KV, distinct from a body-timeout
+   * - non-200: L1 returned a non-200 (treated as a miss)
+   * - l1-miss: no L1 entry
+   * - kv-fresh / kv-stale / kv-miss: L2 fallback outcomes
+   * - kv-stale-suppressed: a stale L2 hit served WITHOUT revalidation because
+   *   the L1 fall-through was degraded (body-timeout / non-200) -- the herd
+   *   mitigation, distinct from kv-stale so the suppression is visible
+   * - kv-timeout: the L2/KV read budget fired (read abandoned, NOT a genuine
+   *   absence -- distinct from kv-miss so a degradation signal is separable)
+   * - tag-invalidated: a live L1/KV entry whose cache tags were invalidated
+   *   after it was written -- treated as a miss so the next render re-populates
+   *   it (the tag-invalidation read path, distinct from a plain miss)
+   * - error: the read threw
+   */
+  outcome:
+    | "l1-fresh"
+    | "l1-stale-revalidate"
+    | "l1-revalidating-guarded"
+    | "match-timeout"
+    | "match-error"
+    | "body-timeout"
+    | "body-error"
+    | "non-200"
+    | "tag-invalidated"
+    | "l1-miss"
+    | "kv-fresh"
+    | "kv-stale"
+    | "kv-stale-suppressed"
+    | "kv-miss"
+    | "kv-timeout"
+    | "error";
+  /** HTTP status of the matched L1 response, when one was returned. */
+  status?: number;
+  /**
+   * Stored cache status header (CACHE_STATUS_HEADER): "HIT" or "REVALIDATING".
+   * Distinct from `isRevalidating`, which also factors in stamp recency -- this
+   * is the raw stored value, so a REVALIDATING entry whose stamp aged out (so
+   * `isRevalidating` is false) is still distinguishable from a plain HIT.
+   */
+  cacheStatus?: string | null;
+  /** Epoch-ms when the entry goes stale (from CACHE_STALE_AT_HEADER). */
+  staleAt?: number;
+  /** Epoch-ms the entry was marked REVALIDATING (from the explicit stamp). */
+  revalidatingAt?: number;
+  /** Raw CF `Age` header, for comparison against revalidatingAt (may be null). */
+  ageHeader?: string | null;
+  isStale?: boolean;
+  isRevalidating?: boolean;
+  shouldRevalidate?: boolean;
+  /** Wall-clock ms spent in cache.match (bounded by edgeLookupTimeoutMs). */
+  matchMs?: number;
+  /**
+   * Wall-clock ms spent resolving the entry's tag-invalidation markers (the
+   * per-request memo -> optional per-colo L1 marker cache -> KV cascade), for a
+   * tagged entry. 0/absent for an untagged entry or a memo hit; a non-trivial
+   * value is the serial marker-read tail that sits between matchMs and
+   * bodyReadMs. Only measured when debug is enabled.
+   */
+  markerMs?: number;
+  /** Wall-clock ms spent reading the body (bounded by edgeReadTimeoutMs). */
+  bodyReadMs?: number;
+}
+
+/**
+ * Debug sink. `true` logs each {@link CFCacheReadDebugEvent} to console; a
+ * function receives the events for programmatic capture.
+ */
+export type CFCacheDebug = boolean | ((event: CFCacheReadDebugEvent) => void);
+
+export interface CFCacheStoreOptions<TEnv = unknown> {
+  /**
+   * Cache namespace. If not provided, uses caches.default (recommended).
+   * Only set this if you need isolated cache storage.
+   */
+  namespace?: string;
+
+  /**
+   * Base URL for cache keys.
+   *
+   * If not provided, derives from request hostname via requestContext:
+   * - Production domains → uses `https://{hostname}/`
+   * - Dev/preview (localhost, workers.dev, pages.dev) → uses internal fallback URL
+   */
+  baseUrl?: string;
+
+  /** Default cache options */
+  defaults?: CacheDefaults;
+
+  /**
+   * Cloudflare ExecutionContext for non-blocking cache writes.
+   * Pass the `ctx` from your worker's fetch handler.
+   *
+   * @example
+   * ```typescript
+   * new CFCacheStore({ ctx: env.ctx })
+   * ```
+   */
+  ctx: ExecutionContext;
+
+  /**
+   * Optional KV namespace for L2 cache persistence.
+   *
+   * When provided, KV acts as a global fallback behind the per-colo Cache API.
+   * On L1 miss, KV is checked and hits are promoted back to L1.
+   * On writes, data is persisted to both L1 and KV.
+   *
+   * @example
+   * ```typescript
+   * new CFCacheStore({ ctx: env.ctx, kv: env.CACHE_KV })
+   * ```
+   *
+   * Tag-based invalidation (updateTag/revalidateTag) requires KV: the
+   * tag-invalidation markers are stored in this same namespace. There is no
+   * separate tag-invalidation store to configure.
+   */
+  kv?: KVNamespace;
+
+  /**
+   * Optional eager-purge hook, called ONCE per updateTag()/revalidateTag() with
+   * the namespaced Cloudflare Cache-Tags to purge (one batched call for the
+   * whole invalidation, not one per tag). These exactly match the `Cache-Tag`
+   * header this store writes on its tag-lookup marker entries
+   * (`rg:{namespace}:lk:{encodedTag}`), so forwarding them to Cloudflare's
+   * purge-by-tag API evicts the cached lookups in every colo - making
+   * cross-colo invalidation prompt instead of waiting out `tagCacheTtl`.
+   *
+   * Only meaningful with `tagCacheTtl > 0` (otherwise there are no cached
+   * lookups to purge). The values are pre-encoded, so commas in tag names are
+   * safe to pass straight to the purge API.
+   *
+   * @example
+   * ```ts
+   * onRevalidateTag: async (cacheTags) => {
+   *   await fetch(`https://api.cloudflare.com/client/v4/zones/${ZONE}/purge_cache`, {
+   *     method: "POST",
+   *     headers: { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json" },
+   *     body: JSON.stringify({ tags: cacheTags }),
+   *   });
+   * }
+   * ```
+   */
+  onRevalidateTag?: (cacheTags: string[]) => Promise<void>;
+
+  /**
+   * Optional expiration (seconds) for tag-invalidation markers in KV. A marker
+   * must outlive every entry tagged before the invalidation, so this MUST
+   * exceed your largest entry TTL+SWR. Defaults to no expiration (markers
+   * persist; they are tiny - one timestamp per distinct invalidated tag).
+   *
+   * Note the opposite sizing from `tagCacheTtl` below: `tagInvalidationTtl` must
+   * be LARGE (outlive data); `tagCacheTtl` should be SMALL (a staleness ceiling).
+   *
+   * Cardinality matters: each DISTINCT invalidated tag writes one permanent KV
+   * marker (with the no-expiry default). Keep tags LOW-cardinality and never
+   * derive an invalidation tag from untrusted input (e.g.
+   * `revalidateTag(req.query.tag)`) - an attacker could otherwise grow your KV
+   * namespace without bound. Set a `tagInvalidationTtl` only if your tags are
+   * unavoidably high-cardinality AND it can still safely exceed your max entry
+   * TTL+SWR.
+   */
+  tagInvalidationTtl?: number;
+
+  /**
+   * Optional TTL (seconds) for caching tag-invalidation markers in the per-colo
+   * Cache API (L1), to avoid a KV marker read on every tagged cache read.
+   *
+   * Default `0` = disabled: the marker is read from KV on every tagged read
+   * (today's behavior), giving the strongest cross-colo invalidation latency
+   * (~KV consistency). A positive value caches each marker (including the
+   * "no marker yet" state) in L1 for that many seconds, so within the window a
+   * colo answers from L1 with no KV read.
+   *
+   * The colo that runs `updateTag`/`revalidateTag` writes the fresh marker
+   * straight into its own L1 (write-through), so the invalidating request and
+   * later reads in that colo observe the invalidation immediately. One caveat: a
+   * read already in flight when the invalidation lands (one that began its KV
+   * marker fetch first) can re-cache the PRIOR marker into L1 after the
+   * write-through, so a racing concurrent reader in the same colo may miss the
+   * invalidation for up to `tagCacheTtl` -- the Cache API exposes no
+   * compare-and-set to close this fully. `tagCacheTtl` is therefore a staleness
+   * CEILING, not a promise of zero same-colo latency; keep it small (or wire
+   * `onRevalidateTag`) when that matters. By default OTHER colos only converge
+   * when their cached marker expires, so `tagCacheTtl` is the MAXIMUM extra
+   * cross-colo invalidation latency for them. Recommended 30-60 for high-read,
+   * low-mutation tags; leave at 0 when prompt global invalidation matters and
+   * you cannot wire a purge.
+   *
+   * To make other colos prompt WITHOUT a short TTL, wire `onRevalidateTag` to a
+   * Cloudflare purge-by-tag call: each marker entry carries a namespaced
+   * `Cache-Tag`, and `onRevalidateTag` is handed exactly those tags to purge, so
+   * the cached lookups are evicted everywhere on invalidation. With a purge
+   * wired, `tagCacheTtl` becomes purely a read-cost reducer + fallback window
+   * (safe to set large) rather than the invalidation-latency ceiling.
+   */
+  tagCacheTtl?: number;
+
+  /**
+   * Cache version string override. When this changes, all cached entries are
+   * effectively invalidated (new keys won't match old entries).
+   *
+   * Defaults to the auto-generated VERSION from the `@rangojs/router:version` virtual module.
+   * Only set this if you need a custom versioning strategy.
+   */
+  version?: string;
+
+  /**
+   * Latency budget (ms) for an L1 edge cache (CF Cache API) read. A `match`
+   * slower than this is abandoned and treated as a miss, so a degraded colo
+   * cannot stall the request; the read then falls through to its normal miss
+   * path (L2/KV or render).
+   *
+   * Defaults to {@link EDGE_LOOKUP_TIMEOUT_MS} (10). Set to 0 (or any value
+   * <= 0) to disable the budget and always await `match`.
+   */
+  edgeLookupTimeoutMs?: number;
+
+  /**
+   * Latency budget (ms) for reading the BODY of a matched L1 entry
+   * (response.json()). CF streams the cache body lazily, so the multi-second
+   * tail can appear after `match` already resolved; this bounds it. On timeout
+   * the read is treated as a miss and falls through to L2/KV or render.
+   *
+   * Separate from {@link edgeLookupTimeoutMs} because a healthy body read
+   * (fetch + JSON parse of a potentially large Flight payload) takes a little
+   * longer than a `match`. Defaults to {@link EDGE_READ_TIMEOUT_MS} (20), which
+   * clears a healthy per-colo read yet fails fast on a degraded one. Set to 0
+   * (or any value <= 0) to disable and always await the body.
+   */
+  edgeReadTimeoutMs?: number;
+
+  /**
+   * Latency budget (ms) for an L2 (KV) read. KV is the last cache tier before a
+   * full render and is a global store (~50ms healthy, seconds when degraded);
+   * this bounds it so a slow namespace cannot pin the request. On timeout the
+   * read is treated as a miss (no L1 promote) and falls through to render.
+   *
+   * Defaults to {@link KV_READ_TIMEOUT_MS} (170) -- a few multiples above the
+   * ~50ms healthy read, with headroom for legitimate tails (large payloads / far
+   * regions) yet still well under a degraded namespace's multi-second tail.
+   * Lower it for a tighter SLA, raise it if your healthy KV p99 runs higher; it
+   * is a degradation guard-rail, not a tuning lever. Set to 0 (or any value
+   * <= 0) to disable and always await KV.
+   */
+  kvReadTimeoutMs?: number;
+
+  /**
+   * Emit a {@link CFCacheReadDebugEvent} per L1 read. `true` logs to console
+   * (visible via `wrangler tail`); pass a function to capture events directly.
+   * Off by default. Intended for validating cache behavior on a real
+   * deployment before relying on it; not for steady-state production.
+   */
+  debug?: CFCacheDebug;
+
+  /**
+   * Custom key generator applied to all cache operations.
+   * Receives the full RequestContext (including env) and the default-generated key.
+   * Return value becomes the final cache key (unless route overrides with `key` option).
+   *
+   * Reserved prefixes: tag-invalidation markers live in the SAME KV namespace as
+   * data, keyed `__tag__/<tag>` (and `__tagmarker__/<tag>` for the L1 cache). A
+   * returned key must NOT begin with `__tag__/` or `__tagmarker__/`, or it can
+   * collide with a tag marker and corrupt invalidation. The documented
+   * prepend-style generators below are safe.
+   *
+   * @example Using headers for user segmentation
+   * ```typescript
+   * keyGenerator: (ctx, defaultKey) => {
+   *   const segment = ctx.request.headers.get('x-user-segment') || 'default';
+   *   return `${segment}:${defaultKey}`;
+   * }
+   * ```
+   *
+   * @example Using env bindings for multi-region
+   * ```typescript
+   * keyGenerator: (ctx, defaultKey) => {
+   *   const region = ctx.env.REGION || 'us';
+   *   return `${region}:${defaultKey}`;
+   * }
+   * ```
+   *
+   * @example Using cookies for locale-aware caching
+   * ```typescript
+   * keyGenerator: (ctx, defaultKey) => {
+   *   const locale = cookies().get('locale')?.value || 'en';
+   *   return `${locale}:${defaultKey}`;
+   * }
+   * ```
+   */
+  keyGenerator?: (
+    ctx: RequestContext<TEnv>,
+    defaultKey: string,
+  ) => string | Promise<string>;
+}

package/src/cache/cf/cf-kv-utils.ts

@@ -0,0 +1,46 @@
+// ============================================================================
+// KV utilities
+// ============================================================================
+//
+// Pure helpers for the CF cache store's KV (L2) tier: key byte-length limits,
+// the expirationTtl floor, and the stale-path Cache-Control recompute. None of
+// these reference the store instance, so they live here as standalone functions.
+
+import { CACHE_EXPIRES_AT_HEADER } from "./cf-cache-constants.js";
+
+/** KV key byte-length ceiling. Cloudflare KV rejects keys larger than this. */
+export const KV_MAX_KEY_BYTES = 512;
+
+/**
+ * Cloudflare KV's minimum `expirationTtl` (seconds). A `put` with a smaller
+ * expirationTtl is rejected outright. Tag-invalidation markers (the only writes
+ * that take a consumer-supplied TTL via tagInvalidationTtl) are floored to this
+ * so a too-small value cannot make EVERY updateTag/revalidateTag throw.
+ */
+export const KV_MIN_EXPIRATION_TTL = 60;
+
+const kvKeyEncoder = new TextEncoder();
+
+/** UTF-8 byte length of a KV key (multibyte tags can exceed the char count). */
+export function kvKeyByteLength(key: string): number {
+  return kvKeyEncoder.encode(key).length;
+}
+
+/**
+ * Compute the Cache-Control directive for a stale-path REVALIDATING re-put from
+ * the entry's stored hard-expiry deadline (CACHE_EXPIRES_AT_HEADER). Returns the
+ * REMAINING ttl so the re-put preserves the original retention deadline instead
+ * of restarting it -- copying set()'s original full-window max-age would reset
+ * CF's retention clock on every re-arm and pin a perpetually-stale entry forever.
+ * An entry lacking a valid deadline (legacy/tampered) floors to max-age=1, so it
+ * hard-expires in ~1s and self-heals via KV. Mirrors promoteSegmentToL1's math.
+ * @internal
+ */
+export function remainingCacheControl(headers: Headers, now: number): string {
+  const expiresAt = Number(headers.get(CACHE_EXPIRES_AT_HEADER));
+  const remainingTtl =
+    Number.isFinite(expiresAt) && expiresAt > 0
+      ? Math.max(1, Math.floor((expiresAt - now) / 1000))
+      : 1;
+  return `public, max-age=${remainingTtl}`;
+}

package/src/cache/cf/cf-tag-marker-memo.ts

@@ -0,0 +1,105 @@
+// ============================================================================
+// Tag-marker memo
+// ============================================================================
+//
+// Per-request memoization of tag-invalidation marker reads, plus the prefix and
+// sentinel used by the optional per-colo L1 marker cache. Extracted from
+// cf-cache-store.ts; the WeakMaps stay MODULE SINGLETONS here (the module is
+// evaluated once), so binding-keyed memo semantics are unchanged: the maps are
+// keyed by the request-context object then the store INSTANCE, identical to
+// before the move.
+
+/**
+ * Cache-API path prefix for the optional per-colo L1 cache of tag-invalidation
+ * markers (enabled by tagCacheTtl). Distinct from data keys (doc:/fn:/segment)
+ * and from the KV marker prefix so the two never collide.
+ */
+export const TAG_MARKER_CACHE_PREFIX = "__tagmarker__/";
+
+/**
+ * Sentinel body for an L1-cached marker meaning "this tag has no invalidation
+ * marker." Distinct from any real ms-epoch timestamp (always a large positive
+ * integer). A Cache API miss (match() === undefined) always means "re-read KV",
+ * never "no marker" - absence is only ever represented by this cached sentinel.
+ */
+export const TAG_MARKER_ABSENT = "none";
+
+/**
+ * Per-request memo of tag-invalidation markers (tag -> latest invalidatedAt, or
+ * null when no marker exists). Keyed first by the request context object (so it
+ * is naturally request-scoped and garbage-collected with the request) and then
+ * by the store INSTANCE.
+ *
+ * The per-store nesting matters because a single request can run more than one
+ * CFCacheStore - the app-level store plus a route's `cache({ store })` override,
+ * which may point at a DIFFERENT KV binding or version. A module-level map keyed
+ * by request alone (the inner map keyed by the raw tag name) would let store B's
+ * memoized marker for a tag mask store A's own KV marker, so A could serve an
+ * entry A's own KV says is invalidated. Keying by the instance isolates them;
+ * two reads through the SAME store still share the memo. A read through one
+ * store never populates another's memo, so each store always consults its own KV
+ * binding. Markers are read only through isGloballyInvalidated(), which already
+ * short-circuits when a store has no KV, so a store without KV never allocates.
+ *
+ * Without the memo, isGloballyInvalidated() issues a KV read per tag on every
+ * tagged cache read, so a page composed of many segments/items sharing a tag
+ * pays that cost N times. The memo collapses it to one KV read per distinct tag
+ * per (request, store). invalidateTags() writes through so a same-request
+ * updateTag() stays read-your-own-writes consistent (the action's own re-render
+ * sees its own invalidation from the memo, without a re-read).
+ *
+ * It does NOT span requests, so a hot single-entry route still pays one KV read
+ * per request; that read hits Cloudflare KV's own edge read cache for hot keys.
+ */
+const tagMarkerMemo = new WeakMap<
+  object,
+  WeakMap<object, Map<string, number | null>>
+>();
+
+export function getTagMarkerMemo(
+  ctx: object,
+  store: object,
+): Map<string, number | null> {
+  let byStore = tagMarkerMemo.get(ctx);
+  if (!byStore) {
+    byStore = new WeakMap();
+    tagMarkerMemo.set(ctx, byStore);
+  }
+  let memo = byStore.get(store);
+  if (!memo) {
+    memo = new Map();
+    byStore.set(store, memo);
+  }
+  return memo;
+}
+
+/**
+ * Per-request map of IN-FLIGHT marker reads (tag -> the pending read promise).
+ * The resolved-value memo above only collapses SEQUENTIAL reads of a tag; the
+ * router resolves sibling segments in PARALLEL, so without this several
+ * concurrently-resolving segments sharing a tag would each issue their own KV
+ * read before any of them populates the memo. Sharing the in-flight promise
+ * collapses those to a single KV read. Entries are dropped once resolved (the
+ * value is then in the memo), so this only spans the concurrent read window.
+ */
+const tagMarkerInflight = new WeakMap<
+  object,
+  WeakMap<object, Map<string, Promise<number | null>>>
+>();
+
+export function getTagMarkerInflight(
+  ctx: object,
+  store: object,
+): Map<string, Promise<number | null>> {
+  let byStore = tagMarkerInflight.get(ctx);
+  if (!byStore) {
+    byStore = new WeakMap();
+    tagMarkerInflight.set(ctx, byStore);
+  }
+  let inflight = byStore.get(store);
+  if (!inflight) {
+    inflight = new Map();
+    byStore.set(store, inflight);
+  }
+  return inflight;
+}

package/src/cache/document-cache.ts

@@ -65,6 +65,17 @@ function parseCacheControl(header: string | null): CacheDirectives | null {
     return null;
   }
 
+  // RFC 7234 §5.2.2.2: a shared cache MUST NOT serve a stored `no-cache`
+  // response without successful origin validation. This store's hit path has no
+  // validation step, so serving a stored no-cache response within s-maxage
+  // would hand the client content the origin marked must-revalidate. Refuse to
+  // store it. Only UNqualified `no-cache` (no `=`) vetoes — the field-name-
+  // scoped `no-cache="set-cookie"` form IS storable per the RFC, so the `=`
+  // boundary is excluded from the lookahead (unlike private/no-store above).
+  if (/(^|[\s,;])no-cache(?=$|[\s,;])/i.test(header)) {
+    return null;
+  }
+
   const directives: CacheDirectives = {};
 
   // Parse s-maxage

package/src/cache/handle-snapshot.ts

@@ -9,7 +9,12 @@
 import type { ResolvedSegment } from "../types.js";
 import type { HandleStore } from "../server/handle-store.js";
 import type { SegmentHandleData } from "./types.js";
-import { serializeResult, deserializeResult } from "./segment-codec.js";
+// segment-codec eagerly pulls @vitejs/plugin-rsc (a virtual: module unresolvable
+// in plain node/vitest). It is imported LAZILY inside the two async encode/decode
+// helpers below so that modules which import handle-snapshot only for the
+// plugin-rsc-free captureHandles/restoreHandles (e.g. cache-scope, on dispatch's
+// lazy response-route cache path) do not pull plugin-rsc at module load. Behavior
+// is unchanged: both helpers are async and already awaited the codec.
 
 const HANDLE_ENCODE_TIMEOUT_MS = 5000;
 
@@ -52,6 +57,7 @@ export function decodeHandles(encoded: string): Promise<HandleRecord | null> {
 }
 
 export async function encodeHandleValue(value: unknown): Promise<string> {
+  const { serializeResult } = await import("./segment-codec.js");
   const encoded = await withTimeout(
     serializeResult(value),
     HANDLE_ENCODE_TIMEOUT_MS,
@@ -67,6 +73,7 @@ export async function encodeHandleValue(value: unknown): Promise<string> {
  */
 export async function decodeHandleValue<T>(encoded: string): Promise<T | null> {
   try {
+    const { deserializeResult } = await import("./segment-codec.js");
     return await deserializeResult<T>(encoded);
   } catch {
     return null;

package/src/cache/profile-registry.ts

@@ -42,7 +42,31 @@ export function resolveCacheProfiles(
             `Profile names must match [a-zA-Z0-9_-]+.`,
         );
       }
-      merged[name] = profiles[name];
+      const profile = profiles[name];
+      // Validate ttl/swr VALUES, not just the name. An unvalidated NaN/Infinity
+      // ttl flows into computeExpiration -> staleAt/expiresAt = NaN, and every
+      // expiry check (`now > NaN`) is false, so the entry never evicts and never
+      // revalidates: it is served fresh forever and accumulates unbounded. A
+      // negative ttl makes every read a guaranteed miss. This guard's policy is
+      // to FAIL FAST at config time on any non-finite/negative ttl — distinct
+      // from prefetch-cache-ttl.ts (falls back to the default) and defer.ts
+      // (treats Infinity as an intentional disable). Do not conflate them.
+      if (!Number.isFinite(profile.ttl) || profile.ttl < 0) {
+        throw new Error(
+          `Invalid cache profile "${name}": ttl must be a finite non-negative ` +
+            `number (got ${profile.ttl}).`,
+        );
+      }
+      if (
+        profile.swr !== undefined &&
+        (!Number.isFinite(profile.swr) || profile.swr < 0)
+      ) {
+        throw new Error(
+          `Invalid cache profile "${name}": swr must be a finite non-negative ` +
+            `number (got ${profile.swr}).`,
+        );
+      }
+      merged[name] = profile;
     }
   }
   return merged;

package/src/cache/segment-codec.ts

@@ -10,6 +10,7 @@
 
 import type { ResolvedSegment } from "../types.js";
 import type { SerializedSegmentData } from "./types.js";
+import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import {
   renderToReadableStream,
   createTemporaryReferenceSet,
@@ -95,7 +96,14 @@ export async function serializeResult(value: unknown): Promise<string | null> {
     const temporaryReferences = createTemporaryReferenceSet();
     const stream = renderToReadableStream(value, { temporaryReferences });
     return await streamToString(stream);
-  } catch {
+  } catch (error) {
+    // Returning null silently turns a non-serializable cache value into a
+    // permanent miss with no trace. Surface it on the internal debug channel so
+    // a failed serialize is diagnosable on wrangler tail, but keep returning
+    // null so the caller falls through to an uncached render rather than throws.
+    if (INTERNAL_RANGO_DEBUG) {
+      console.warn("[segment-codec] serializeResult failed:", error);
+    }
     return null;
   }
 }

package/src/cache/types.ts

@@ -259,11 +259,15 @@ export interface CacheDefaults {
   /**
    * Default time-to-live in seconds.
    * After TTL expires, cached entry is considered stale.
+   * Must be a finite, non-negative number; an invalid value (NaN/Infinity/
+   * negative) falls back to the default at read time.
    */
   ttl?: number;
   /**
    * Default stale-while-revalidate window in seconds.
    * During SWR window, stale content is served while revalidating in background.
+   * Must be a finite, non-negative number; an invalid value (NaN/Infinity/
+   * negative) falls back to the default at read time.
    */
   swr?: number;
 }

package/src/client.rsc.tsx

@@ -20,8 +20,40 @@ export {
   type ErrorBoundaryProps,
 } from "./client.js";
 
+export {
+  useFetchLoader,
+  useRefreshLoaders,
+  type LoadFunction,
+  type UseLoaderResult,
+  type UseFetchLoaderResult,
+  type UseLoaderOptions,
+} from "./use-loader.js";
+
 export { createLoader } from "./route-definition.js";
 
+// "use client" hooks the default ./client entry exports. They are client
+// references in the RSC graph, identical in kind to useHref/useReverse/
+// useHandle already forwarded below; forward them so the RSC client entry's
+// hook surface matches the default entry. useNavigation/useAction stay omitted
+// (they drive client-only navigation/action state — see note below).
+export { useRouter } from "./browser/react/use-router.js";
+export { usePathname } from "./browser/react/use-pathname.js";
+export { useSearchParams } from "./browser/react/use-search-params.js";
+export { useParams } from "./browser/react/use-params.js";
+// CSP nonce for userland head-script components (analytics/GTM/inline init);
+// forwarded so the RSC client entry's hook surface matches the default entry.
+export { useNonce } from "./browser/react/nonce-context.js";
+export { useMount } from "./browser/react/use-mount.js";
+export {
+  useSegments,
+  type SegmentsState,
+} from "./browser/react/use-segments.js";
+export {
+  useLinkStatus,
+  type LinkStatus,
+} from "./browser/react/use-link-status.js";
+export { useScrollRestoration } from "./browser/react/ScrollRestoration.js";
+
 export {
   Link,
   type LinkProps,
@@ -49,6 +81,12 @@ export { createHandle, isHandle, type Handle } from "./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 { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
 
 export {