@rangojs/router 0.0.0-experimental.142 → 0.0.0-experimental.144

package/skills/ppr/SKILL.md

@@ -169,6 +169,31 @@ On a document GET to a ppr route the router runs:
 point is after the chain, an unauthorized request NEVER sees shell bytes — put
 auth middleware anywhere (global or route DSL) and it guards PPR for free.
 
+## Verifying it works
+
+The header exists on DOCUMENT responses only. A bare `curl` (no `Accept`)
+content-negotiates a Flight payload (`text/x-component`) with NO
+`x-rango-shell` header at all — which reads as "PPR is off" but is only the
+wrong request shape:
+
+```
+curl -s -D - -o /dev/null -H "Accept: text/html" https://app.example.com/products/1 | grep -i x-rango-shell
+```
+
+- First document GET: `MISS`, plus a background capture.
+- Production (workerd/node): the SECOND request is a `HIT`.
+- Dev: expect a few extra MISSes — cold module transforms abort the capture
+  window (per-attempt breadcrumbs: start the server with
+  `INTERNAL_RANGO_DEBUG=1`). This self-heals; only a route that NEVER flips
+  has a real hole/eligibility problem (the once-per-key warning tells the two
+  apart).
+- A HIT is one ordinary document: the frozen prelude first (view-source shows
+  your baked shell, with hole fallbacks in place), then
+  `<div hidden id="S:0">…` segments as the holes resume, per request.
+- A ppr-declared route that CANNOT be honored (missing shell store family,
+  per-request nonce) serves plain axis 1 with NO header and warns once per
+  key — no header + a declared `ppr` means look for that warning.
+
 ## The hole doctrine (encode this in your head)
 
 Holes are **render-defined**, decided by the shape of the tree, on three rules:
@@ -230,7 +255,14 @@ The physics caveat in one line: promise holes are holes because the I/O is
 genuinely pending at capture. If the value can resolve near-instantly (memory
 read, warmed cache), it may bake into the shell — when liveness must be
 guaranteed rather than probable, use the live lane (`loading()`). The same
-physics governs bake-lane nested promises.
+physics governs bake-lane nested promises, with one shape guarantee: a nested
+promise that settles inside the window pins its VALUE, but the container key
+KEEPS its promise shape on HITs (the snapshot rehydrates a
+`Promise.resolve(pinned)`), so an unconditional `use(data.x)` consumer never
+breaks — it just reads the pinned value. Note the timing consequence: whether
+such a value is pinned or live can vary per capture (concurrent loader traffic
+extends the quiet window), so treat "fast-resolving promise on the bake lane"
+as PINNED for correctness purposes.
 
 ### Handles: "nesting = liveness"
 
@@ -278,7 +310,10 @@ Three hard edges (each e2e/unit-pinned):
   throws during capture and the capture REFUSES (deterministic, once-per-key
   warned) — identity can never bake into the shared shell. Give that loader's
   entry `loading()` (the live lane is exempt) or move the identity-dependent
-  part into a nested promise.
+  part into a nested promise. The guard's scope is EXACTLY those two calls:
+  per-user state read from a middleware-provided object (`ctx.get("session")`)
+  does NOT refuse — it bakes silently as the capturing user's data (see
+  Pitfalls: the session-object bake trap).
 - **A rejecting bake-lane loader refuses.** Error UI never bakes.
 - **Baked containers show CAPTURE-time data** for the shell's lifetime on
   document GETs (client navigations stay fresh — axis 1). That IS the bake
@@ -316,10 +351,16 @@ stay live. Your levers, in order of preference:
        loader(BasketLoader),
        loading(<BadgeSkeleton />), // hole the size of a badge, not a page
      ]),
-     parallel({ "@wishlist": WishlistBadge }, () => [
-       loader(WishlistLoader),
-       loading(<BadgeSkeleton />),
-     ]),
+     // Descriptor form when the slot handler needs ctx (annotate it —
+     // StaticHandlerDefinition in the union blocks inference there):
+     parallel({
+       "@wishlist": {
+         handler: (ctx: HandlerContext) => (
+           <WishlistBadge listUrl={ctx.reverse("wishlist")} />
+         ),
+         use: () => [loader(WishlistLoader), loading(<BadgeSkeleton />)],
+       },
+     }),
      path("/", HomePage, { name: "home", ppr: true }),
    ]),
    ```
@@ -327,16 +368,27 @@ stay live. Your levers, in order of preference:
    Slot-owned loaders are masked at capture and GUARANTEED fresh per serve —
    use this where the bake lane's physics (a fast resolve bakes) or pinning
    (capture-time data for the shell's lifetime) is not acceptable, at the cost
-   of a widget-sized fallback in the shell.
+   of a widget-sized fallback in the shell. The slot handler must hand the
+   loader to a CLIENT component (`useLoader` in a `"use client"` component)
+   for the freshness guarantee to reach the rendered value: server-side
+   `await ctx.use(...)` in the handler is the BAKED lane (the consumption-lane
+   rule, `/rango` → Invariants) — it executes at capture with identity reads
+   permitted, but the value it renders is a capture-time copy wherever it is
+   not shielded by the slot's masked LoaderBoundary.
 
 4. **Shared layout data can also leave the loader lane entirely**: an
    un-awaited handler promise under the consumer's `<Suspense>` (a physics
    hole) or `cache()`/`"use cache"` to bake it with tag-invalidation.
 
 The identity rule, stated once: per-user data on a PPR page lives in a NESTED
-promise (a hole, fresh per request) or behind `loading()` (the live lane).
-Reading `cookies()`/`headers()` where the value would bake — handler shell
-material or a bake-lane container — refuses the capture by construction.
+promise (a hole, fresh per request) or behind `loading()` with CLIENT-side
+consumption (the live lane). Reading `cookies()`/`headers()` where the value
+would bake as SEGMENT material — handler/render code or a bake-lane loader
+container — refuses the capture by construction. The one exemption is
+handler-INVOKED loader bodies (`await ctx.use(loader)`): they execute at
+capture with identity reads permitted, and the value bakes as a shared
+capture-time copy — mirroring `cache()` semantics (the consumption-lane
+rule; semantic-matrix row PPR3).
 
 ## Execution matrix
 
@@ -387,9 +439,14 @@ PPR-ineligible by construction; the live lane (`loading()`) stays exempt.
 **(c) Residual hazard — middleware-derived per-user state.** A `ctx` variable
 set by an upstream auth middleware and rendered by shell material is
 photographed into the SHARED shell (the capture inherits post-middleware
-state). That is scope fidelity working as designed — for shared values. If the
-value is per-user: shell-cache only public/shared pages, put per-user content
-in loaders, or key per variant at the CDN tier.
+state). That is scope fidelity working as designed — for shared values. The
+same hazard reaches BAKE-LANE LOADERS: a loader reading a middleware-provided
+session object (`ctx.get("session")`) never calls `cookies()` itself, so the
+guard cannot see it — whatever it returns as settled container data is
+photographed as the CAPTURING user's state. If the
+value is per-user: shell-cache only public/shared pages, keep per-user content
+in nested pending promises or live-lane (`loading()`) loaders — NOT in a
+bake-lane container — or key per variant at the CDN tier.
 
 ## What always stays on axis 1
 
@@ -459,10 +516,11 @@ multi-tenant shells never collide).
 HTML; `revalidate()` is a DATA lever that never touches it.
 
 A captured shell auto-carries the UNION of the non-loader tags recorded during
-the capture render — every `cacheTag(...)` from a `"use cache"` function or
-`cache()` segment that ran as shell material. Loader tags never attach (the
-holes are already live). `ppr.tags` adds operational tags the render cannot
-know (a tenant id, a deploy marker).
+the capture render — every `cacheTag(...)` that ran as shell material, whether
+from a `"use cache"` function, a `cache()` segment, or a render-callable
+`cacheTag()` in a plain server component (no `"use cache"`/`cache()` in its
+tree). Loader tags never attach (the holes are already live). `ppr.tags` adds
+operational tags the render cannot know (a tenant id, a deploy marker).
 
 | Lever                                         | Reaches the frozen shell?                                     | Reaches the holes?                                  |
 | --------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------- |
@@ -470,6 +528,12 @@ know (a tenant id, a deploy marker).
 | `updateTag` / `revalidateTag` on a LOADER tag | no — loader tags never attach to a shell                      | drops that loader's cached value (if it `cache()`s) |
 | `revalidate()` (named revalidation contract)  | **no** — re-runs segments/loaders for the PAYLOAD, never HTML | yes — the hole re-renders with fresh data           |
 
+A server action's automatic invalidation refreshes the CLIENT only — it re-runs
+the holes and streams a fresh payload, but does NOT evict the server shell.
+Shell-baked data stays stale until the shell's TTL unless you tag-invalidate it
+(`updateTag` on a shell tag). Data baked into the shell WITHOUT a tag cannot be
+evicted by tag at all — move always-fresh data under a `loading()` hole.
+
 ## Pitfalls
 
 - **A bake-lane loader that reads `cookies()`/`headers()`**: the capture is
@@ -483,7 +547,27 @@ know (a tenant id, a deploy marker).
 - **Per-user value in shell material**: baked into the shared shell —
   deterministically, not by race (handler promises deep-settle at the ring-3
   write on cached chains; awaited/resolved values bake everywhere). Put
-  per-user data in a loader.
+  per-user data in a nested pending promise or a live-lane (`loading()`)
+  loader — a BAKE-lane loader container bakes just like handler material.
+- **The session-object bake trap (the guard cannot save you here)**: the
+  capture guard sees `cookies()`/`headers()` calls ONLY. A bake-lane loader
+  reading a middleware-provided session object (`ctx.get("session")`) refuses
+  nothing — and its FAST-RESOLVE branch is the killer:
+
+  ```typescript
+  const CartLoader = createLoader(async (ctx) => {
+    const basketId = ctx.get("session")!.get("basketId");
+    if (!basketId) return { cart: Promise.resolve(null) }; // SETTLED → BAKES
+    return { cart: fetchBasket(basketId) }; // pending → hole
+  });
+  ```
+
+  If the capturing request is anonymous (it usually is), `cart: null` bakes
+  and is snapshot-pinned: every logged-in user gets the anonymous badge on
+  every HIT. The branch asymmetry makes it nondeterministic per capture. Any
+  loader whose data is per-user belongs on the live lane — for a header
+  widget, a parallel slot with its own `loading()` (playbook lever 3).
+
 - **Theme on a HIT is capture-then-corrected**: the resume tree replays the
   CAPTURE's `initialTheme` (resume requires it to match the frozen prelude);
   the visitor's cookie theme is applied pre-paint by the FOUC script and
@@ -497,8 +581,11 @@ cache"` value baked into the shell is PINNED at capture (the capture data
   tag-invalidated. This is deliberate — parity beats freshness inside the shell.
   If a shell region needs to be fresh, put it under a hole — `loading()` for
   loader data, or an un-awaited promise under the consumer's `<Suspense>`
-  (holes are never pinned) — or make the SHELL itself invalidatable by adding
-  the tag to `ppr.tags`. Ring-1/ring-3 tag invalidation does NOT drop the shell.
+  (holes are never pinned) — or make the SHELL itself invalidatable by tagging
+  it: call `cacheTag(...)` from the shell-material render code (the render-time
+  lever), or add the tag to `ppr.tags` (operational tags the render cannot know —
+  a tenant id, a deploy marker). Ring-1/ring-3 tag invalidation does NOT drop the
+  shell.
 - **Uncached nondeterminism in the shell is a hydration hazard**: a raw
   `Date.now()` / `Math.random()` / uncached `fetch` rendered directly in shell
   material (outside any cache ring) drifts between capture and hit and the
@@ -520,6 +607,9 @@ cache"` value baked into the shell is PINNED at capture (the capture data
 
 ## Related
 
+- `/defer-hydration` — keep the full body HTML in the shell while moving a
+  heavy subtree's hydration off the initial main-thread task (gated boundary,
+  content-as-fallback)
 - `/document-cache` — whole-response edge caching (no live holes)
 - `/caching` and `/cache-guide` — segment/function caching (axis 1 data)
 - `/shell-manifest` — replayed handles as cache metadata read by live loaders

package/skills/rango/SKILL.md

@@ -117,6 +117,15 @@ stated, greppable contract.
 - `path()`/`include()` are always visible in `urls()`; config helpers are extractable.
 - **Cache decides freshness; `revalidate()` decides client-update.** Orthogonal; compose.
 - Loaders resolve fresh every request (even inside `cache()`) and never run twice/request.
+- **The consumption-lane rule.** For every shared artifact (`cache()`,
+  `"use cache"`, the PPR shell): server-side handler consumption
+  (`await ctx.use(loader)`) yields a BAKED copy — identity reads
+  (`cookies()`/`headers()`) are permitted there and the capture-time value
+  freezes into the shared artifact (a documented footgun; see `/caching` →
+  "Cache purity & tainted objects"). Client-side consumption (`useLoader` in
+  a `"use client"` component) is the LIVE lane. DSL `loader()` segments
+  follow their lane machinery (live under renderable `loading()`, bake
+  otherwise). Pinned by semantic-matrix row PPR3.
 - Inside `"use cache"`: `cookies()`/`headers()` and `ctx` side-effects
   (`set`/`header`/`setTheme`/`onResponse`/`setLocationState`) throw; `ctx.use(Handle)`
   is captured on miss and replayed on hit. (The non-cacheable read guard is a
@@ -273,6 +282,7 @@ Grouped by concern — read when you need to…
 | `/scripts`          | Inject third-party scripts (GTM/analytics) into head/body via the `Script` handle; nonce auto-applied to document-rendered scripts |
 | `/tailwind`         | Set up Tailwind CSS v4 with `?url` imports                                                                                         |
 | `/view-transitions` | React View Transitions on layouts, routes, and parallel slots                                                                      |
+| `/defer-hydration`  | Full body HTML in the PPR shell + hydration off the critical path (gated Suspense boundary, content-as-fallback)                   |
 | `/breadcrumbs`      | Built-in Breadcrumbs handle for breadcrumb navigation                                                                              |
 | `/react-compiler`   | Enable React Compiler (opt-in) the vite-rsc way; client-only scope                                                                 |
 

package/skills/route/SKILL.md

@@ -479,6 +479,14 @@ urls(({ path, layout }) => [
 ])
 ```
 
+For composing whole route MODULES, reach for `include()` — and prefer the
+code-split form `include("/shop", () => import("./shop-patterns"))` for any
+group that is a natural unit: it keeps the group off the cold-start path, and
+measured first-hit cost scales with routes-per-chunk, so many small groups
+beat one giant one. Sizing rules and the numbers behind them:
+[skills/composability](../composability/SKILL.md) → "Sizing async include
+groups (measured)".
+
 ## View Transitions
 
 A route can configure its own `transition()` — the wrap goes around the route's component itself (routes are leaves; they have no separate default outlet channel). If the route component renders a `<ParallelOutlet />` directly, that slot remains inside the route's VT subtree, so prefer mounting parallel slots in a layout when combining intercept modals with route-level transitions. See [skills/view-transitions](../view-transitions/SKILL.md) for examples and the wrap-location rules across layouts, routes, and slots.

package/skills/typesafety/SKILL.md

@@ -25,6 +25,7 @@ below. Read the one for your case.
 | Typed `search` schemas, `RouteSearchParams`/`RouteParams`, loader return types                                       | Search params & loader typing          | [`./params-and-search.md`](./params-and-search.md)             |
 | Typed `env`/bindings, `Rango.Vars`, `createVar()`, handle typing, loader/handle ref props, location state typing     | Environment, context, and state typing | [`./env-and-bindings.md`](./env-and-bindings.md)               |
 | Multi-app / multi-router tsconfig setup, avoiding `GeneratedRouteMap` collisions                                     | Multi-project setup & full walkthrough | [`./generated-files-and-cli.md`](./generated-files-and-cli.md) |
+| Slow typecheck with many `include()` modules (instantiation blowup), wide `UrlPatterns<any>` annotations             | Typecheck cost at route scale          | [`./generated-files-and-cli.md`](./generated-files-and-cli.md) |
 
 ## Companion files
 

package/skills/typesafety/generated-files-and-cli.md

@@ -120,6 +120,36 @@ Do not document or use a public `router.routeNames` API unless one is
 intentionally added. Today, the public extraction surface is `router.routeMap`;
 the generated file and `$$routeNames` are build machinery.
 
+### Typecheck cost when composing many include modules
+
+`urls()` infers a route registry from everything in its array — including the
+module types behind every `include()` thunk, recursively. In an app composing
+MANY include modules (dozens of groups, or factory-produced groups), that
+inference chain can explode: measured on a 26k-route app with 50 nested
+include modules, root inference hit 4.05M type instantiations / 20 s check
+time; the same app checks at ~140k / 3.6 s after widening.
+
+The fix is to annotate the intermediate modules' exports with the wide
+`UrlPatterns` type, which stops per-route literal types from propagating
+upward:
+
+```typescript
+import { urls, type UrlPatterns } from "@rangojs/router";
+
+export const shopPatterns: UrlPatterns<any> = urls(({ path }) => [
+  // ...hundreds of routes
+]);
+export default shopPatterns;
+```
+
+Nothing is lost: named-route typing (`Handler<"name">`, `ctx.reverse`,
+`href`) comes from the generated `router.named-routes.gen.ts`, not from the
+inferred `urls()` type. Keep full inference on modules whose
+`Rango.PathResponse` payloads you assert (e.g. `path.json` response routes);
+widen the big mechanical groups. Use `UrlPatterns<any>` (not
+`UrlPatterns<unknown>` — `unknown` env breaks handler assignability).
+Diagnose with `tsc --extendedDiagnostics` and watch the Instantiations count.
+
 ## Multi-Project tsconfig Setup
 
 For monorepos or multi-app setups, each app should have its own TypeScript

package/skills/use-cache/SKILL.md

@@ -153,6 +153,13 @@ const locale = cookies().get("locale")?.value ?? "en";
 const data = await getCachedData(locale); // locale is now in the cache key
 ```
 
+The guard does not reach into LOADER bodies consumed inside the cached
+function (`await ctx.use(loader)`): loaders always run fresh, so their reads
+are exempt — but the CONSUMED VALUE is captured into the shared cache entry
+like any other computed data. Same rule across `cache()` and the PPR shell:
+handler/cached-scope consumption = baked copy, client-side `useLoader` = live
+(the consumption-lane rule, `/rango` → Invariants).
+
 ### Side-Effect Guards
 
 These ctx methods **throw** inside a `"use cache"` function because their effects
@@ -346,8 +353,11 @@ export async function getProducts() {
 Writes to the same `SegmentCacheStore` as `cache()` DSL, `Static()`, and `Prerender()`.
 One store, one configuration.
 
-Cache entries (and `cacheProfiles`) can be tagged via `cache({ tags })` or, inside
-a `"use cache"` function, runtime `cacheTag(...tags)`. The built-in
+Cache entries (and `cacheProfiles`) can be tagged via `cache({ tags })` or runtime
+`cacheTag(...tags)`. `cacheTag` has two forms: inside a `"use cache"` function it
+tags that entry; called during a request render outside `"use cache"` it tags the
+request's document/shell artifact (rides `_requestTags`) instead of throwing. The
+built-in
 `MemorySegmentCacheStore` and `CFCacheStore` index by tag. Invalidate on demand
 with `updateTag(...tags)` (awaitable, read-your-own-writes; for server actions) or
 `revalidateTag(...tags)` (background, non-blocking; for route handlers/webhooks).

package/src/browser/partial-update.ts

@@ -395,6 +395,13 @@ export function createPartialUpdater(
           return;
         }
         if (mode.type === "action") {
+          // An action refetch that lands on missing segments (navigated away /
+          // consolidation / HMR) drops rather than refetch-all: the action flow
+          // is storeOnly / skipLoadingState, so a full refetch here would fight
+          // it. Keep the stale-but-consistent tree; log so the drop is visible.
+          debugLog(
+            `[Browser] Action refetch: ${missingCount} segments missing; dropping (stale-but-consistent tree kept).`,
+          );
           return;
         }
         console.warn(

package/src/cache/cache-key-utils.ts

@@ -58,3 +58,32 @@ export function sortedRouteParams(
   if (!params) return "";
   return encodeKV(Object.entries(params), { sort: true });
 }
+
+/**
+ * Host-namespaced cache key base: `${host}${pathname}[:params][?search]`.
+ *
+ * The ONE composition of the host-namespacing rule, shared by the segment tier
+ * (cache-scope.ts) and the document tier (document-cache.ts) so the rule cannot
+ * drift between them. Host prefixing matters because VercelCacheStore /
+ * MemorySegmentCacheStore key by the raw string (only CFCacheStore adds host
+ * internally) -- on a single function serving multiple domains an
+ * un-namespaced key bleeds tenant A's cached response to tenant B.
+ *
+ * Output is BYTE-STABLE by contract: changing the composition silently
+ * invalidates every persisted cache entry on upgrade. Callers append their own
+ * tier-specific suffixes (`:rsc`/`:html`, segment hash) after this base.
+ */
+export function cacheKeyBase(
+  host: string,
+  pathname: string,
+  searchParams?: URLSearchParams,
+  params?: Record<string, string>,
+): string {
+  const paramStr = sortedRouteParams(params);
+  const searchStr = searchParams ? sortedSearchString(searchParams) : "";
+
+  let key = `${host}${pathname}`;
+  if (paramStr) key += `:${paramStr}`;
+  if (searchStr) key += `?${searchStr}`;
+  return key;
+}

package/src/cache/cache-scope.ts

@@ -31,7 +31,7 @@ import {
   encodeHandles,
   decodeHandles,
 } from "./handle-snapshot.js";
-import { sortedSearchString, sortedRouteParams } from "./cache-key-utils.js";
+import { cacheKeyBase } from "./cache-key-utils.js";
 import {
   DEFAULT_ROUTE_TTL,
   isFiniteNonNegativeSeconds,
@@ -85,21 +85,6 @@ function validatedSwr(value: number | undefined): number | undefined {
   return isValidCacheSeconds(value, "swr") ? value : undefined;
 }
 
-function getCacheKeyBase(
-  host: string,
-  pathname: string,
-  params?: Record<string, string>,
-  searchParams?: URLSearchParams,
-): string {
-  const paramStr = sortedRouteParams(params);
-  const searchStr = searchParams ? sortedSearchString(searchParams) : "";
-
-  let key = `${host}${pathname}`;
-  if (paramStr) key += `:${paramStr}`;
-  if (searchStr) key += `?${searchStr}`;
-  return key;
-}
-
 function getDefaultRouteCacheKey(
   pathname: string,
   params?: Record<string, string>,
@@ -113,7 +98,7 @@ function getDefaultRouteCacheKey(
   // Intercept navigations get their own cache namespace
   const prefix = isIntercept ? "intercept" : isPartial ? "partial" : "doc";
 
-  return `${prefix}:${getCacheKeyBase(host, pathname, params, searchParams)}`;
+  return `${prefix}:${cacheKeyBase(host, pathname, searchParams, params)}`;
 }
 
 // ============================================================================

package/src/cache/cache-tag.ts

@@ -38,36 +38,82 @@ export function normalizeTags(tags: Iterable<string>): string[] {
 }
 
 /**
- * Tag the current "use cache" entry for later invalidation via
- * updateTag() / revalidateTag().
+ * Tag content for later invalidation via updateTag() / revalidateTag().
  *
- * Must be called inside a function marked with "use cache".
- * Tags are additive - multiple calls accumulate.
+ * cacheTag() serves two forms depending on what is active when it runs:
+ *
+ * 1. Inside a "use cache" function — the DEFAULT. The tags go to the current
+ *    cache entry; `revalidateTag(tag)` drops that entry. Tags are additive
+ *    (multiple calls accumulate), and normalizeTag() is the single chokepoint so
+ *    a padded write matches an unpadded invalidate.
+ *
+ * 2. Render-callable (#648) — no "use cache" scope active, but a request context
+ *    is present. The tags record onto the request's DOCUMENT artifact
+ *    (ctx._requestTags) instead of throwing. The collection layers already exist:
+ *    PPR shell capture unions _requestTags into the shell entry, the document
+ *    cache tags the full-page entry with it, and prerender build contexts seed
+ *    their own set — so a server component that renders into a shell makes
+ *    `revalidateTag("campaign:spring")` evict that shell with ZERO cache()/"use
+ *    cache" in its tree. This is PPR's DERIVATIVE invalidation: PPR is
+ *    execution-PRESERVING (everything still runs underneath; only document bytes
+ *    are shortcut), so its tags ride this existing instrument rather than a
+ *    first-class ppr key/tag API. The shell-expiry invariant holds by
+ *    construction — baked ⇒ evicts (bake-lane loaders execute during capture and
+ *    record here), hole ⇒ fresh (masked loaders behind a renderable loading()
+ *    never execute during capture, so nothing under a hole can tag the shell).
+ *
+ * Inside a cache() DSL segment the render-callable form records at the DOCUMENT
+ * level, not the segment (only the "use cache" runtime enters the tag scope) — a
+ * documented semantic, not a filtered one. An empty/whitespace-only tag is
+ * dropped in both forms (the render-callable form silently, via normalizeTags in
+ * recordRequestTags; the scope form with a dev warning).
+ *
+ * With neither a scope nor a request context, cacheTag() throws.
  *
  * @example
  * ```typescript
+ * // Form 1 — inside "use cache":
  * async function getProduct(ctx) {
  *   "use cache";
  *   cacheTag(`product:${ctx.params.id}`, "products");
  *   return db.getProduct(ctx.params.id);
  * }
+ *
+ * // Form 2 — render-callable, tags the shell/document from a server component:
+ * function CampaignBanner() {
+ *   cacheTag("campaign:spring");
+ *   return <aside>Spring sale</aside>;
+ * }
  * ```
  */
 export function cacheTag(...tags: string[]): void {
   const store = cacheTagStorage.getStore();
-  if (!store) {
-    throw new Error('cacheTag() must be called inside a "use cache" function.');
-  }
-  for (const tag of tags) {
-    const normalized = normalizeTag(tag);
-    if (normalized === null) {
-      if (process.env.NODE_ENV !== "production") {
-        console.warn(`[cacheTag] Ignoring empty or whitespace-only tag.`);
+  if (store) {
+    // Form 1: "use cache" scope wins — tag the cache entry (unchanged).
+    for (const tag of tags) {
+      const normalized = normalizeTag(tag);
+      if (normalized === null) {
+        if (process.env.NODE_ENV !== "production") {
+          console.warn(`[cacheTag] Ignoring empty or whitespace-only tag.`);
+        }
+        continue;
       }
-      continue;
+      store.add(normalized);
     }
-    store.add(normalized);
+    return;
   }
+
+  const reqCtx = _getRequestContext();
+  if (reqCtx?._requestTags) {
+    // Form 2: render-callable — tag the request's document artifact. See the
+    // JSDoc above for the composition doctrine and the baked/hole invariant.
+    recordRequestTags(tags, reqCtx);
+    return;
+  }
+
+  throw new Error(
+    'cacheTag() must be called inside a "use cache" function or during a request render.',
+  );
 }
 
 export function recordRequestTags(

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

@@ -137,6 +137,16 @@ const warnedNoKvReadInvalidation = new Set<string>();
  */
 const warnedTagInvalidationTtlFloor = new Set<string>();
 
+/**
+ * Stores (by namespace) already warned that tag invalidation is writing KV
+ * markers with no expiry (tagInvalidationTtl unset), so the unbounded-growth
+ * warning fires once per process rather than once per invalidateTags call
+ * (CFCacheStore is constructed per request; invalidateTags runs per marker
+ * batch). Distinct from the floor warning: that one only fires for a positive
+ * below-floor value, never for the unset (no-expiry) default that this bounds.
+ */
+const warnedNoTagInvalidationTtl = new Set<string>();
+
 // ============================================================================
 // Types
 // ============================================================================
@@ -340,19 +350,30 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     // kv - yet every tagged read still serves stale data with no other signal.
     // Surface that misconfiguration.
     if (!this.kv && (this.tagCacheTtl > 0 || this.onRevalidateTag)) {
-      const id = this.namespace ?? "default";
-      if (!warnedNoKvReadInvalidation.has(id)) {
-        warnedNoKvReadInvalidation.add(id);
-        console.warn(
-          `[CFCacheStore] tagCacheTtl/onRevalidateTag is configured without a KV ` +
-            `namespace, so tag invalidation has NO read-side effect: tagged reads ` +
-            `are never treated as invalidated and serve stale data. Configure ` +
-            `{ kv } for distributed tag invalidation.`,
-        );
-      }
+      this.warnOncePerNamespace(
+        warnedNoKvReadInvalidation,
+        `[CFCacheStore] tagCacheTtl/onRevalidateTag is configured without a KV ` +
+          `namespace, so tag invalidation has NO read-side effect: tagged reads ` +
+          `are never treated as invalidated and serve stale data. Configure ` +
+          `{ kv } for distributed tag invalidation.`,
+      );
     }
   }
 
+  /**
+   * Warn about a namespace-scoped misconfiguration once per namespace per
+   * isolate. `seen` is the module-level Set for that message family -- Sets
+   * are module-level (not instance fields) so re-constructed stores in the
+   * same isolate don't re-warn.
+   * @internal
+   */
+  private warnOncePerNamespace(seen: Set<string>, message: string): void {
+    const id = this.namespace ?? "default";
+    if (seen.has(id)) return;
+    seen.add(id);
+    console.warn(message);
+  }
+
   /**
    * Validate a consumer-supplied tagInvalidationTtl against CF KV's expirationTtl
    * floor. A finite value below KV_MIN_EXPIRATION_TTL is raised to it (with a
@@ -368,16 +389,13 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (value == null) return undefined;
     if (!Number.isFinite(value) || value <= 0) return undefined;
     if (value < KV_MIN_EXPIRATION_TTL) {
-      const id = this.namespace ?? "default";
-      if (!warnedTagInvalidationTtlFloor.has(id)) {
-        warnedTagInvalidationTtlFloor.add(id);
-        console.warn(
-          `[CFCacheStore] tagInvalidationTtl ${value} is below Cloudflare KV's ` +
-            `${KV_MIN_EXPIRATION_TTL}s expirationTtl floor; raising to ` +
-            `${KV_MIN_EXPIRATION_TTL}. It must still exceed your largest entry ` +
-            `TTL+SWR or invalidated entries can resurrect when the marker expires.`,
-        );
-      }
+      this.warnOncePerNamespace(
+        warnedTagInvalidationTtlFloor,
+        `[CFCacheStore] tagInvalidationTtl ${value} is below Cloudflare KV's ` +
+          `${KV_MIN_EXPIRATION_TTL}s expirationTtl floor; raising to ` +
+          `${KV_MIN_EXPIRATION_TTL}. It must still exceed your largest entry ` +
+          `TTL+SWR or invalidated entries can resurrect when the marker expires.`,
+      );
       return KV_MIN_EXPIRATION_TTL;
     }
     return value;
@@ -2254,6 +2272,22 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     const failedTags = new Set<string>();
     const errors: unknown[] = [];
     if (this.kv) {
+      // Markers written with no expiry (tagInvalidationTtl unset) never expire,
+      // so high-cardinality tags accumulate KV keys unboundedly with no reaper.
+      // Warn once per namespace at the batch entry point (not per marker write,
+      // which would fire once per tag). Kept separate from the floor warning:
+      // that path only fires for a positive below-floor value, never the unset
+      // default sanitizeTagInvalidationTtl passes through as undefined.
+      if (!this.tagInvalidationTtl) {
+        this.warnOncePerNamespace(
+          warnedNoTagInvalidationTtl,
+          `[CFCacheStore] invalidateTags is writing KV markers with no expiry ` +
+            `(tagInvalidationTtl is unset): high-cardinality tags accumulate KV ` +
+            `keys unboundedly (storage + list-scan cost) with no reaper. Set ` +
+            `tagInvalidationTtl above your largest entry TTL+SWR to bound marker ` +
+            `growth; setting it too small resurrects invalidated entries.`,
+        );
+      }
       await Promise.all(
         tags.map(async (tag) => {
           const markerKey = this.tagMarkerKey(tag);