@rangojs/router 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -176,22 +176,9 @@
     "access": "public",
     "tag": "latest"
   },
-  "scripts": {
-    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
-    "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
-    "prepublishOnly": "pnpm build",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
-    "test": "playwright test",
-    "test:ui": "playwright test --ui",
-    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-basename --project=hmr-prerender --no-deps --workers=1 && RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
-    "test:hmr-routes-local": "RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
-    "test:unit": "pnpm run build:types && vitest run",
-    "test:unit:watch": "vitest",
-    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
-  },
   "dependencies": {
     "@types/debug": "^4.1.12",
-    "@vitejs/plugin-rsc": "^0.5.30",
+    "@vitejs/plugin-rsc": "^0.5.31",
     "debug": "^4.4.1",
     "magic-string": "^0.30.17",
     "picomatch": "^4.0.4",
@@ -205,18 +192,18 @@
     "@opentelemetry/context-async-hooks": "^2.9.0",
     "@opentelemetry/sdk-trace-base": "^2.9.0",
     "@playwright/test": "^1.49.1",
-    "@shared/e2e": "workspace:*",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^24.10.1",
-    "@types/react": "catalog:",
-    "@types/react-dom": "catalog:",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
     "esbuild": "^0.28.1",
     "happy-dom": "^20.10.1",
     "jiti": "^2.7.0",
-    "react": "catalog:",
-    "react-dom": "catalog:",
-    "vitest": "^4.1.9"
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "vitest": "^4.1.9",
+    "@shared/e2e": "0.0.1"
   },
   "peerDependencies": {
     "@cloudflare/vite-plugin": "^1.42.1",
@@ -224,9 +211,9 @@
     "@playwright/test": "^1.49.1",
     "@testing-library/react": ">=16",
     "@vercel/functions": "^3.0.0",
-    "@vitejs/plugin-rsc": "^0.5.30",
-    "react": ">=19.2.6 <20",
-    "react-dom": ">=19.2.6 <20",
+    "@vitejs/plugin-rsc": "^0.5.31",
+    "react": ">=19.2.8 <20",
+    "react-dom": ">=19.2.8 <20",
     "vite": "^8.0.16",
     "vitest": ">=3"
   },
@@ -255,5 +242,18 @@
   },
   "engines": {
     "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
+    "test": "playwright test",
+    "test:preload": "playwright test --config=playwright.preload.config.ts",
+    "test:ui": "playwright test --ui",
+    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-basename --project=hmr-prerender --no-deps --workers=1 && RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
+    "test:hmr-routes-local": "RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
+    "test:unit": "pnpm run build:types && vitest run",
+    "test:unit:watch": "vitest",
+    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
   }
-}
+}

package/skills/client-urls/SKILL.md

@@ -118,15 +118,15 @@ typing work exactly as for server routes (`/typesafety`).
 
 ## Helpers: what exists inside clientUrls()
 
-| Helper         | Notes                                                                                 |
-| -------------- | ------------------------------------------------------------------------------------- |
-| `path()`       | Options are `name`, `search`, `trailingSlash` only (no `ppr`, no response variants)   |
-| `layout()`     | Must contain at least one `path()`                                                    |
-| `loader()`     | `loader(Def, use?)` or `loader(Def, { stream: "navigation" }, use?)` — see below      |
-| `loading()`    | Route/layout-level pending UI; inline `<Suspense>` at read sites is usually better    |
-| `revalidate()` | Valid **inside a loader() use callback only**; runs in the browser                    |
-| `transition()` | Data-only ViewTransition config — no `when` (that is a server-executed predicate)     |
-| `intercept()`  | Dot-local named target in the SAME definition; use may contain `loader()`/`loading()` |
+| Helper         | Notes                                                                                                                                                          |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `path()`       | Options are `name`, `search`, `trailingSlash`, `ppr` (shell caching — see /ppr skill; loader routes need `loading()` or capture refuses); no response variants |
+| `layout()`     | Must contain at least one `path()`                                                                                                                             |
+| `loader()`     | `loader(Def, use?)` or `loader(Def, { stream: "navigation" }, use?)` — see below                                                                               |
+| `loading()`    | Route/layout-level pending UI; inline `<Suspense>` at read sites is usually better                                                                             |
+| `revalidate()` | Valid **inside a loader() use callback only**; runs in the browser                                                                                             |
+| `transition()` | Data-only ViewTransition config — no `when` (that is a server-executed predicate)                                                                              |
+| `intercept()`  | Dot-local named target in the SAME definition; use may contain `loader()`/`loading()`                                                                          |
 
 `include`, `parallel`, `cache`, `middleware`, `errorBoundary`,
 `notFoundBoundary` **throw** — and that is a design position, not a gap.

package/skills/cloudflare/SKILL.md

@@ -130,9 +130,11 @@ export const router = createRouter<AppBindings>({
 ```
 
 PPR shells use Cache API as the per-colo L1 and KV as the durable cross-colo
-L2; a KV hit promotes the coupled shell envelope back into L1. KV remains
-required for this family. `CFCacheStore` without `kv` can still cache
-segment/response entries in Cache API, but its shell family is inert.
+L2; a KV hit promotes the coupled shell envelope back into L1. KV is optional:
+`CFCacheStore` without `kv` runs the shell family L1-only (edge-only ppr —
+each colo captures and serves its own shell). Tag eviction then needs purge
+mode (`tagPurge`); a tagged shell without either warns once and expires by
+ttl+swr only.
 
 ## Commands
 

package/skills/ppr/SKILL.md

@@ -356,13 +356,17 @@ curl -s -D - -o /dev/null https://app.example.com/products/1 | grep -i x-rango-s
   key — no header + a declared `ppr` means look for that warning.
 - On Cloudflare, `CFCacheStore` reads PPR shells from the per-colo Cache API,
   falls through to KV on a miss, and promotes the KV hit back into that colo.
-  WITHOUT a KV namespace its shell family remains inert: 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. An
-  inert store also stops captures at the gate: the store declares
-  `shellFamilyInert` and the scheduler skips the background render entirely
-  (`skip-inert-store` on the debug event) instead of burning a full capture per
-  MISS whose write could only no-op.
+  WITHOUT a KV namespace the family runs L1-only (edge-only ppr): every colo
+  captures and serves its own shell from the Cache API. What changes KV-less
+  is tag eviction — with `tagPurge` the purge-by-tag evicts shell L1 entries;
+  without it a TAGGED shell warns once that `updateTag()` cannot reach it
+  (ttl/swr-only freshness). Untagged edge-only ppr is warning-free. Tagged
+  BUILD-manifest shells decline on a KV-less store (`tagHistoryInert` — the
+  immutable asset could never be evicted), and an over-limit tag set is
+  acknowledged `"uncacheable"` so the capture backs off instead of
+  re-rendering per MISS. A custom store can still declare `shellFamilyInert`
+  to stop captures at the gate (`skip-inert-store` on the debug event); the
+  built-in stores never do.
 - 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

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

@@ -145,11 +145,12 @@ 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.
+ * Stores (by namespace) already warned that a TAGGED shell was written on a
+ * KV-less store without tagPurge: no markers and no purge means updateTag()
+ * cannot reach the shell (freshness is ttl/swr only). Once per isolate, not
+ * per capture (CFCacheStore is constructed per request).
  */
-const warnedShellFamilyInert = new Set<string>();
+const warnedShellTagsNoEviction = new Set<string>();
 
 /**
  * Stores (by namespace) already warned that tag invalidation is writing KV
@@ -412,8 +413,6 @@ interface KVResponseEnvelope {
 
 export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   readonly supportsPassiveShellReads: true = true;
-  /** True when constructed without KV: the shell family no-ops (see ctor). */
-  readonly shellFamilyInert?: boolean;
   readonly defaults?: CacheDefaults;
   readonly keyGenerator?: (
     ctx: RequestContext<TEnv>,
@@ -429,6 +428,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   private readonly kvReadTimeoutMs: number;
   private readonly debug?: (event: CFCacheReadDebugEvent) => void;
   private readonly kv?: KVNamespace;
+  /** True when constructed without KV: no durable tag history (see ctor). */
+  readonly tagHistoryInert?: boolean;
   private readonly onRevalidateTag?: (tags: string[]) => Promise<void>;
   private readonly tagPurge?: (cacheTags: string[]) => Promise<void>;
   private readonly tagInvalidationTtl?: number;
@@ -485,11 +486,13 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     this.keyGenerator = options.keyGenerator;
     this.waitUntil = (fn) => options.ctx.waitUntil(fn());
     this.kv = options.kv;
-    // The shell family requires KV (getShell/putShell no-op without it — see
-    // warnShellFamilyInertOnce). Declaring it lets scheduleShellCapture skip
-    // captures whose write could only no-op instead of burning a background
-    // render per MISS that still occupies the serialized capture queue.
-    this.shellFamilyInert = options.kv ? undefined : true;
+    // Without KV, isTagsInvalidatedSince has no durable history — it answers
+    // from the per-request memo at best. Runtime shells tolerate that (purge
+    // eviction + ttl/swr bound the staleness), but an immutable TAGGED
+    // build-manifest shell must not serve on such a store: nothing could ever
+    // evict it (purge cannot delete a build asset), so the manifest gate
+    // declines on this flag (shell-build-manifest.ts).
+    this.tagHistoryInert = options.kv ? undefined : true;
     this.onRevalidateTag = options.onRevalidateTag;
     // tagPurge accepts a ready purge function or a credentials object; the
     // object form is normalized through the built-in zone purge client, which
@@ -506,9 +509,12 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     // marker write throw and break ALL invalidation. Floor it (and warn once);
     // a non-finite/non-positive value falls back to the no-expiry default
     // (markers persist) rather than silently sailing a NaN into expirationTtl.
-    this.tagInvalidationTtl = this.sanitizeTagInvalidationTtl(
-      options.tagInvalidationTtl,
-    );
+    // KV-less the option is dead config — no markers to expire, and the
+    // retention cap it used to imply is KV-conditional (putShell) — so it is
+    // dropped without the KV-floor validation/warning, which would misdirect.
+    this.tagInvalidationTtl = options.kv
+      ? this.sanitizeTagInvalidationTtl(options.tagInvalidationTtl)
+      : undefined;
     // tagCacheTtl gates the L1 marker cache via `> 0`. A non-finite value (NaN
     // from `Number(env.UNSET)`) is not null/undefined, so `?? 0` would let it
     // through and silently disable the cache while reading as "configured".
@@ -1876,40 +1882,75 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   }
 
   // ============================================================================
-  // Shell Cache Methods (PPR shell resume) — Cache API L1 + KV L2
+  // Shell Cache Methods (PPR shell resume) — Cache API L1 + optional KV L2
   // ============================================================================
   //
-  // KV remains the durable, cross-colo shell tier. Cache API is a per-colo
-  // read-through accelerator: writes populate both tiers, and a valid KV hit
-  // promotes the same coupled envelope into L1. The family still requires KV;
-  // without it, getShell/putShell no-op and PPR fails open to a full HTML render.
+  // With KV it is the durable, cross-colo shell tier: writes populate both
+  // tiers, a valid KV hit promotes the same coupled envelope into L1, and
+  // shell L1 hits deliberately keep the KV generation-marker check even in
+  // purge mode. A shell's taggedAt is its CAPTURE START, not its write time:
+  // an invalidation can purge while an older capture is still running, then
+  // that capture can land after the purge. The marker check rejects that
+  // resurrection.
   //
-  // Shell L1 hits deliberately keep the KV generation-marker check even in
-  // purge mode. A shell's taggedAt is its CAPTURE START, not its write time: an
-  // invalidation can purge while an older capture is still running, then that
-  // capture can land after the purge. The marker check rejects that resurrection.
+  // Without KV the family is L1-only (edge-only ppr): every colo captures and
+  // serves its own shell from the Cache API. Tag eviction then needs purge
+  // mode (tagPurge) — shell L1 entries carry the same namespaced Cache-Tag
+  // tokens as the data families, read-your-own-writes comes from the
+  // per-request marker memo, and the capture resurrection race narrows to
+  // cross-request timing bounded by ttl+swr (the data families' documented
+  // purge-mode stance). KV-less WITHOUT tagPurge still caches: freshness is
+  // ttl/swr only, and a tagged write warns once that invalidation cannot
+  // reach it (see warnShellTagsNoEvictionOnce).
 
   /**
-   * 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.
+   * Warn once per isolate that a TAGGED shell landed on a store with no
+   * eviction path for it: no KV (markers) and no tagPurge (purge-by-tag).
+   * The shell still caches and expires by ttl+swr, but updateTag()/
+   * revalidateTag() cannot reach it — silent staleness a consumer who tagged
+   * the route clearly did not intend. Fired from putShell (not the
+   * constructor) so an untagged edge-only ppr config stays warning-free.
    * @internal
    */
-  private warnShellFamilyInertOnce(): void {
+  private warnShellTagsNoEvictionOnce(): 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 }).`,
+      warnedShellTagsNoEviction,
+      `[CFCacheStore] a ppr shell with tags was stored on a KV-less store ` +
+        `without tagPurge: tag invalidation cannot evict it (no KV markers, ` +
+        `no purge-by-tag), so updateTag()/revalidateTag() will not reach ` +
+        `this shell — it serves until ttl+swr expiry. Configure { kv } for ` +
+        `marker invalidation or { tagPurge } for purge-by-tag eviction; ` +
+        `untagged ppr routes (ttl/swr freshness) are unaffected.`,
     );
   }
 
+  /**
+   * Generation gate for shell writes and the capture scheduler
+   * (isTagsInvalidatedSince). With KV it is the durable marker cascade.
+   * Without KV there are no markers: in purge mode the per-request memo is
+   * the only signal — a capture racing THIS request's updateTag() is still
+   * rejected (read-your-own-writes), while cross-request races are bounded
+   * by ttl+swr exactly like the data families' purge-mode writes. Without
+   * either, fail open (ttl/swr-only semantics, warned at putShell).
+   * @internal
+   */
+  private async isShellGenerationInvalidated(
+    tags: string[] | undefined,
+    since: number | undefined,
+  ): Promise<boolean> {
+    if (this.kv) return this.isGloballyInvalidated(tags, since);
+    if (!this.tagPurge || !Array.isArray(tags) || tags.length === 0 || !since)
+      return false;
+    const ctx = _getRequestContext();
+    if (!ctx) return false;
+    const memo = getTagMarkerMemo(ctx, this);
+    for (const tag of tags) {
+      const marker = memo.get(tag);
+      if (marker != null && marker >= since) return true;
+    }
+    return false;
+  }
+
   /**
    * Get a cached PPR shell entry from Cache API, falling through to KV and
    * promoting a valid KV hit. Both tiers store one envelope so the prelude,
@@ -1920,10 +1961,6 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   async getShell(
     key: string,
   ): Promise<{ entry: ShellCacheEntry; shouldRevalidate?: boolean } | null> {
-    if (!this.kv) {
-      this.warnShellFamilyInertOnce();
-      return null;
-    }
     try {
       const cache = await this.getCache();
       const request = this.keyToRequest(`shell:${key}`);
@@ -2005,10 +2042,17 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         return this.kvGetShell(key);
       }
 
-      // Unlike other L1 families, shells always check the durable generation
-      // marker. See the capture-start/purge race documented above.
+      // Unlike other L1 families, shells with KV always check the durable
+      // generation marker — see the capture-start/purge race documented
+      // above. Without KV there are no markers: L1-only shells adopt the
+      // data families' purge-mode read semantics (a hit that survived the
+      // purge is trusted; the per-request memo masks this request's own
+      // updateTag() writes; entries a purge cannot reach fall back to the
+      // marker check, which fails open KV-less).
       const markerStartedAt = INTERNAL_RANGO_DEBUG ? Date.now() : 0;
-      const invalidated = await this.isGloballyInvalidated(value.t, value.ta);
+      const invalidated = this.kv
+        ? await this.isGloballyInvalidated(value.t, value.ta)
+        : await this.isL1Invalidated(value.t, value.ta, response.headers);
       const markerMs = INTERNAL_RANGO_DEBUG
         ? Date.now() - markerStartedAt
         : undefined;
@@ -2042,11 +2086,12 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   }
 
   /**
-   * Store a PPR shell envelope in Cache API and, when its retention meets KV's
-   * 60-second floor, KV. The shared write is registered with waitUntil and
-   * awaited so invalidation rejection can be acknowledged to the capture
-   * scheduler. Short-lived shells remain useful in L1 even though KV rejects
-   * them.
+   * Store a PPR shell envelope in Cache API and, when KV is configured and
+   * the retention meets its 60-second floor, KV. The shared write is
+   * registered with waitUntil and awaited so invalidation rejection can be
+   * acknowledged to the capture scheduler. Short-lived shells remain useful
+   * in L1 even though KV rejects them; a KV-less store is L1-only by design
+   * (edge-only ppr — see the section comment).
    */
   async putShell(
     key: string,
@@ -2054,20 +2099,29 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     ttlSeconds?: number,
     swrSeconds?: number,
     tags?: string[],
-  ): Promise<"stored" | "invalidated" | void> {
-    // KV remains required for durable generation markers and cross-colo reads.
-    if (!this.kv) {
-      this.warnShellFamilyInertOnce();
-      return;
-    }
+  ): Promise<"stored" | "invalidated" | "uncacheable" | void> {
     if (!this.waitUntil) return;
+    // Same write gate as the data families: in KV-less purge mode an
+    // over-limit tag set has NO eviction path (no tokens, no markers), so the
+    // shell is not cached rather than becoming un-invalidatable. Unlike the
+    // void-returning data puts, this is ACKNOWLEDGED — the capture scheduler
+    // must back the key off (every write would refuse identically), not
+    // treat the capture as stored and re-render on every MISS.
+    if (this.skipUncacheableTagSet(tags)) return "uncacheable";
+    if (!this.kv && !this.tagPurge && Array.isArray(tags) && tags.length > 0) {
+      this.warnShellTagsNoEvictionOnce();
+    }
     try {
       const ttl = resolveTtl(ttlSeconds, this.defaults, DEFAULT_FUNCTION_TTL);
       const swrWindow = resolveSwrWindow(swrSeconds, this.defaults);
       const totalTtl = ttl + swrWindow;
 
+      // The tagInvalidationTtl cap exists so a tagged entry can never outlive
+      // its KV markers (an expired marker would resurrect it). Without KV
+      // there are no markers to outlive — capping would just hard-expire the
+      // shell below its declared ttl+swr — so the cap is KV-conditional.
       const retentionTtl =
-        tags && tags.length > 0 && this.tagInvalidationTtl
+        tags && tags.length > 0 && this.kv && this.tagInvalidationTtl
           ? Math.min(totalTtl, this.tagInvalidationTtl)
           : totalTtl;
       const now = Date.now();
@@ -2076,14 +2130,14 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       const taggedAt =
         Array.isArray(tags) && tags.length > 0 ? entry.createdAt : undefined;
 
-      const kvKey = await this.toKVKey(`shell:${key}`);
-      const writeKv = retentionTtl >= KV_MIN_EXPIRATION_TTL;
+      const writeKv = !!this.kv && retentionTtl >= KV_MIN_EXPIRATION_TTL;
+      const kvKey = writeKv ? await this.toKVKey(`shell:${key}`) : null;
 
       const write = (async (): Promise<"stored" | "invalidated" | void> => {
         if (
           tags &&
           tags.length > 0 &&
-          (await this.isGloballyInvalidated(tags, entry.createdAt))
+          (await this.isShellGenerationInvalidated(tags, entry.createdAt))
         ) {
           this.debugShell(key, "write-invalidated");
           return "invalidated";
@@ -2132,7 +2186,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
             }
           })(),
         ];
-        if (writeKv) {
+        if (writeKv && kvKey !== null) {
           writes.push(
             (async () => {
               try {
@@ -3029,13 +3083,15 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * Shell tag-generation gate (SegmentCacheStore.isTagsInvalidatedSince): the
    * SAME KV markers used by runtime envelopes also evict immutable build shells
    * and captures whose write races updateTag(). Thin public wrapper over the
-   * private envelope check (marker >= since, fail open).
+   * shell generation check (marker >= since, fail open); KV-less it degrades
+   * to the per-request memo in purge mode and to false otherwise — see
+   * isShellGenerationInvalidated.
    */
   async isTagsInvalidatedSince(
     tags: string[],
     sinceMs: number,
   ): Promise<boolean> {
-    return this.isGloballyInvalidated(tags, sinceMs);
+    return this.isShellGenerationInvalidated(tags, sinceMs);
   }
 
   async invalidateTags(tags: string[]): Promise<void> {

package/src/cache/shell-snapshot.ts

@@ -250,7 +250,7 @@ export class RecordingShellStore<
     ttlSeconds?: number,
     swrSeconds?: number,
     tags?: string[],
-  ): Promise<"stored" | "invalidated" | void> {
+  ): Promise<"stored" | "invalidated" | "uncacheable" | void> {
     return this.inner.putShell?.(key, entry, ttlSeconds, swrSeconds, tags);
   }
 
@@ -506,7 +506,7 @@ export class SeededShellStore<
     ttlSeconds?: number,
     swrSeconds?: number,
     tags?: string[],
-  ): Promise<"stored" | "invalidated" | void> {
+  ): Promise<"stored" | "invalidated" | "uncacheable" | void> {
     return this.inner.putShell?.(key, entry, ttlSeconds, swrSeconds, tags);
   }
 

package/src/cache/types.ts

@@ -188,7 +188,12 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * @param tags - Optional cache tags for invalidation (participates in
    *   invalidateTags via the same tag machinery as the item family)
    * @returns `invalidated` when a generation marker rejected the write,
-   *   `stored` when acknowledged, or void for stores without acknowledgements.
+   *   `stored` when acknowledged, `uncacheable` when the entry can NEVER be
+   *   stored under the current configuration (every retry would refuse
+   *   identically — the capture scheduler backs the key off instead of
+   *   recapturing per MISS; CFCacheStore returns it for a tag set whose
+   *   Cache-Tag header overflows in KV-less purge mode), or void for stores
+   *   without acknowledgements.
    */
   putShell?(
     key: string,
@@ -196,18 +201,33 @@ export interface SegmentCacheStore<TEnv = unknown> {
     ttlSeconds?: number,
     swrSeconds?: number,
     tags?: string[],
-  ): Promise<"stored" | "invalidated" | void>;
+  ): Promise<"stored" | "invalidated" | "uncacheable" | void>;
 
   /**
    * Declares the shell family present-but-inert: getShell/putShell exist but
-   * no-op (CFCacheStore without a KV namespace). scheduleShellCapture skips
-   * captures whose only write target is inert — the background render would be
-   * dead work that still occupies the per-isolate serialized capture queue
-   * (a promise-heavy route bakes for seconds per MISS with nothing stored).
-   * Absent/false means the family, when present, actually stores.
+   * no-op (a custom store whose backing tier is conditionally unavailable).
+   * scheduleShellCapture skips captures whose only write target is inert —
+   * the background render would be dead work that still occupies the
+   * per-isolate serialized capture queue (a promise-heavy route bakes for
+   * seconds per MISS with nothing stored). Absent/false means the family,
+   * when present, actually stores. The built-in stores never declare it:
+   * CFCacheStore is L1-only without KV (edge-only ppr), not inert.
    */
   shellFamilyInert?: boolean;
 
+  /**
+   * Declares isTagsInvalidatedSince present-but-inert: the store implements
+   * the method but has no DURABLE invalidation history behind it (a KV-less
+   * CFCacheStore answers from the per-request memo at best). Runtime shells
+   * tolerate that — purge eviction plus ttl/swr bound their staleness — but
+   * a TAGGED build-manifest shell is immutable with no ttl of its own, so
+   * serving it on such a store would make updateTag() a permanent no-op for
+   * it. The build-shell read-through declines tagged entries on this flag
+   * (same declared-intent-cannot-be-honored doctrine as a store missing the
+   * method entirely). Absent/false means answers are durably backed.
+   */
+  tagHistoryInert?: boolean;
+
   /**
    * Get a cached function result by key.
    * Returns the serialized value, optional handle data, and staleness flag.

package/src/client-urls/client-urls.ts

@@ -31,6 +31,56 @@ const TRANSITION_CONFIG_KEYS = new Set<PropertyKey>([
   "viewTransition",
 ]);
 
+const PPR_NUMBER_KEYS = new Set<PropertyKey>([
+  "ttl",
+  "swr",
+  "captureTimeout",
+  "maxSnapshotBytes",
+]);
+
+/**
+ * DSL-time shape check for the projected `ppr` path option. Mirrors
+ * PartialPrerenderProps but validates by hand: the value must survive the
+ * JSON projection to the server, so only `true` or a plain object of finite
+ * numbers plus a string[] `tags` is legal. The projection serializer
+ * (server-projection.ts) re-validates independently — this copy exists so a
+ * bad value fails in the authoring module with a DSL-shaped message.
+ */
+function validateClientPpr(value: unknown): void {
+  if (value === true) return;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(
+      "clientUrls() path() ppr must be true or a PartialPrerenderProps object",
+    );
+  }
+  for (const key of Reflect.ownKeys(value)) {
+    if (PPR_NUMBER_KEYS.has(key)) {
+      const n = (value as Record<PropertyKey, unknown>)[key];
+      if (typeof n !== "number" || !Number.isFinite(n)) {
+        throw new Error(
+          `clientUrls() path() ppr.${String(key)} must be a finite number`,
+        );
+      }
+      continue;
+    }
+    if (key === "tags") {
+      const tags = (value as { tags: unknown }).tags;
+      if (
+        !Array.isArray(tags) ||
+        tags.some((tag) => typeof tag !== "string" || tag === "")
+      ) {
+        throw new Error(
+          "clientUrls() path() ppr.tags must be an array of non-empty strings",
+        );
+      }
+      continue;
+    }
+    throw new Error(
+      `clientUrls() path() ppr received unsupported key ${JSON.stringify(String(key))}`,
+    );
+  }
+}
+
 const UNSUPPORTED_HELPERS = new Set([
   "include",
   "parallel",
@@ -173,6 +223,31 @@ function assertNamedComponent(
   component: unknown,
   helper: "path" | "layout" | "intercept",
 ): asserts component is ComponentType {
+  // Build-time handler wrappers get a TARGETED rejection ahead of the generic
+  // shape check: their handler code cannot live in a "use client" bundle and
+  // their render runs at build, so accepting one could only fail later and
+  // further from the mistake. Brand strings checked directly — importing
+  // static-handler.ts/prerender.ts here would pull server modules into the
+  // client graph for an error message.
+  const brand =
+    component !== null &&
+    (typeof component === "object" || typeof component === "function")
+      ? (component as { __brand?: unknown }).__brand
+      : undefined;
+  if (
+    brand === "staticHandler" ||
+    brand === "prerenderHandler" ||
+    brand === "prerenderPassthrough"
+  ) {
+    const wrapper = brand === "staticHandler" ? "Static()" : "Prerender()";
+    throw new Error(
+      `clientUrls() ${helper}() received a ${wrapper} handler. Build-time ` +
+        "handlers are server-DSL surface and cannot mount inside a client " +
+        "group — routes in a group render client components. For shell " +
+        "caching of a group route use the `ppr` path option; build-time " +
+        "prerendering belongs to the server tree around the include.",
+    );
+  }
   if (typeof component !== "function" || component.name.trim() === "") {
     throw new Error(
       `clientUrls() ${helper}() expects a named client component value`,
@@ -249,6 +324,9 @@ function createHelpers(): ClientUrlHelpers {
         'clientUrls() path() trailingSlash must be "always", "never", or "ignore"',
       );
     }
+    if (options?.ppr !== undefined) {
+      validateClientPpr(options.ppr);
+    }
 
     const items = use ? runUse(use, "path use") : [];
     rejectItems(items, new Set(["loader", "loading", "transition"]), "path");