@rangojs/router 0.0.0-experimental.112 → 0.0.0-experimental.113

package/skills/hooks/SKILL.md

@@ -268,7 +268,11 @@ reads (keyed or not) reset on navigation from fresh route data, as before.
 **Refreshing multiple loaders together (`refreshGroup` + `useRefreshLoaders`)**:
 
 `key` groups readers of one loader. To refresh **different** loaders together,
-tag them with the same `refreshGroup` and trigger them with `useRefreshLoaders`:
+tag them with a shared `refreshGroup` name and trigger them with
+`useRefreshLoaders()`. The hook takes no argument; you pass the group(s) to the
+function it returns, so one `useRefreshLoaders()` can refresh different groups
+depending on context. A read may carry **several** tags — pass an array — and is
+refreshed when **any** of its groups is refreshed:
 
 ```tsx
 function Profile() {
@@ -279,33 +283,47 @@ function Profile() {
   return <span>{data.name}</span>;
 }
 function Orders() {
+  // Tagged into two groups: refreshed by "account" (the whole set) or the
+  // finer "orders" tag.
   const { data } = useLoader(OrdersLoader, {
     key: userId,
-    refreshGroup: "account",
+    refreshGroup: ["account", "orders"],
   });
   return <span>{data.count} orders</span>;
 }
-function RefreshButton() {
-  const refreshAccount = useRefreshLoaders("account");
-  return <button onClick={() => refreshAccount()}>Refresh</button>;
+function RefreshButtons() {
+  const refresh = useRefreshLoaders();
+  return (
+    <>
+      <button onClick={() => refresh("account")}>Refresh account</button>
+      <button onClick={() => refresh("orders")}>Refresh orders only</button>
+      <button onClick={() => refresh(["account", "orders"])}>
+        Refresh both
+      </button>
+    </>
+  );
 }
 ```
 
-`refreshAccount()` re-runs every currently-mounted member with a **plain GET**
-against the current route URL — no params, no body, no mutation methods, because
-a group spans loaders with different shapes. It returns a promise that resolves
+`refresh(groups)` accepts one name or an array and re-runs every currently-mounted
+member tagged with **any** of them, with a **plain GET** against the current route
+URL — no params, no body, no mutation methods, because a group spans loaders with
+different shapes. A member that sits in two of the requested groups is fetched
+once (members are unioned and deduped by read). It returns a promise that resolves
 when all members settle and **rejects with an `AggregateError`** if any fail;
 group refresh never render-throws, so handle failures at the await site
-(`await refreshAccount().catch(...)`). Each failing member also exposes its error
-via its own read's `error`.
-
-Sharing within a group is opt-in via `key`: members that share a `key` share one
-value (and one fetch); a grouped reader **without** a `key` gets its own private
-bucket, so a group refresh updates only that read and never leaks into unrelated
-unkeyed reads of the same loader. A bucket may belong to several groups at once
-(different reads can tag the same keyed bucket with different group names).
-Keep parameterized loaders on the single-loader `key` — a plain-GET group refresh
-sends no params.
+(`await refresh("account").catch(...)`). Each failing member also exposes its
+error via its own read's `error`.
+
+Multiple tags give you granular vs. whole-set refresh from one place: a coarse
+tag (`"account"`) covers everything, while a finer tag (`"orders"`) targets a
+subset. Sharing within a group is opt-in via `key`: members that share a `key`
+share one value (and one fetch); a grouped reader **without** a `key` gets its own
+private bucket, so a group refresh updates only that read and never leaks into
+unrelated unkeyed reads of the same loader. A bucket may belong to several groups
+at once (one read tagged with multiple names, or different reads tagging the same
+keyed bucket with different names). Keep parameterized loaders on the single-loader
+`key` — a plain-GET group refresh sends no params.
 
 **Load options**:
 
@@ -888,7 +906,7 @@ See `/links` for the full URL generation guide. `ctx.reverse()` is server-only;
 | `useLinkStatus()`     | Link pending state                | { pending }                                                        |
 | `useLoader()`         | Loader data (strict)              | data, isLoading, error                                             |
 | `useFetchLoader()`    | Loader with on-demand fetch       | data, load, isLoading                                              |
-| `useRefreshLoaders()` | Refresh a cross-loader group      | `(group) => () => Promise<void>`                                   |
+| `useRefreshLoaders()` | Refresh cross-loader group(s)     | `() => (groups: string \| string[]) => Promise<void>`              |
 | `useHandle()`         | Accumulated handle data           | T (handle type)                                                    |
 | `useAction()`         | Server action state               | state, error, result                                               |
 | `useLocationState()`  | History state (persists or flash) | T \| undefined                                                     |

package/skills/loader/SKILL.md

@@ -98,9 +98,9 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 >   **client** refresh identity. It groups which mounted reads of one loader
 >   refresh together when one calls `load()`. It never touches the server
 >   request. For refreshing **different** loaders together, tag them with
->   `{ refreshGroup }` and call `useRefreshLoaders(name)()` (plain GET only).
->   See the hooks skill ("Scoping refetch with a `key`" and "Refreshing multiple
->   loaders together").
+>   `{ refreshGroup }` (one name or several) and call `useRefreshLoaders()(name)`
+>   (plain GET only). See the hooks skill ("Scoping refetch with a `key`" and
+>   "Refreshing multiple loaders together").
 > - `cache({ key })` — a **server** cache identity (storage hit/miss/ttl/swr).
 > - `revalidate()` — which **server** segments/loaders recompute during
 >   navigation and action refreshes.

package/skills/rango/SKILL.md

@@ -28,7 +28,10 @@ with the shape, then pick a primitive.
   cache hit streams UI instantly while loaders resolve fresh alongside). Opt into
   caching explicitly. See `/loader` → "Parallel and streaming".
 - **One identity, one store** — loaders, handles, cached fns, and actions are all
-  `path#export`; all caches share one store; `revalidateTag` cuts across them.
+  `path#export`; all caches share one store. Entries expire by TTL/SWR; cache
+  entries accept an optional `tags` field, but built-in stores do not yet index
+  or invalidate by tag, so tag-based invalidation (`revalidateTag`) is a
+  forward-looking API requiring a custom store.
 - **Type-safe end to end** — route names, params, search schemas, loader return
   types, context vars, and `href` / `reverse` are checked at compile time
   (`/typesafety`).
@@ -82,8 +85,10 @@ To decide where something can live: **does it define a URL? structure, stays in
   (`set`/`header`/`setTheme`/`onResponse`/`setLocationState`) throw; `ctx.use(Handle)`
   is captured on miss and replayed on hit. (The non-cacheable read guard is a
   separate `cache()`-boundary check — see the correctness bullet below.)
-- One identity `path#export` (`functionId`/`$$id`/`actionId`); one store;
-  `revalidateTag` cuts across all cache mechanisms.
+- One identity `path#export` (`functionId`/`$$id`/`actionId`); one store. The
+  cross-cutting freshness mechanism today is TTL/SWR expiry; cache entries accept
+  an optional `tags` field, but built-in stores do not yet index or invalidate by
+  tag, so `revalidateTag` is forward-looking (requires a custom store).
 - `useLoader` / `useHandle` / `useFetchLoader` are client-only.
 - Caches are correctness-first: persistent store keys are version-segmented (no
   cross-deploy drift), the forward/back cache is mutation-aware, and
@@ -106,13 +111,13 @@ To decide where something can live: **does it define a URL? structure, stays in
 Same words, different jobs — this is the most common source of the
 `revalidate()`-is-caching misread.
 
-| You may know                               | Maps to Rango axis | Watch out                                                                                                                                                      |
-| ------------------------------------------ | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Next.js `export const revalidate = N`      | **Axis 1** (cache) | Same word, opposite meaning. Next's `revalidate` is time-based cache expiry; Rango's `revalidate()` is **axis 2**. Use `cache({ ttl })` for the Next behavior. |
-| Next.js `revalidatePath` / `revalidateTag` | **Axis 1** (cache) | Cache busting. Rango's tag bust is `revalidateTag`; there is no `revalidatePath`.                                                                              |
-| React Router / Remix `shouldRevalidate`    | **Axis 2**         | This is the correct mental model for Rango's `revalidate()`.                                                                                                   |
-| HTTP `Cache-Control` / ISR                 | **Axis 1**         | Edge/document layer — see `/document-cache`. Separate from both `cache()` and `revalidate()`.                                                                  |
-| Remix/RR `loader`                          | live data          | Like Rango loaders, fresh per request — but Rango loaders run in parallel and stream (latency overlaps first paint), and can opt into caching on demand.       |
+| You may know                               | Maps to Rango axis | Watch out                                                                                                                                                                                                                       |
+| ------------------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Next.js `export const revalidate = N`      | **Axis 1** (cache) | Same word, opposite meaning. Next's `revalidate` is time-based cache expiry; Rango's `revalidate()` is **axis 2**. Use `cache({ ttl })` for the Next behavior.                                                                  |
+| Next.js `revalidatePath` / `revalidateTag` | **Axis 1** (cache) | Cache busting. No shipped equivalent: entries accept `tags`, but built-in stores don't yet index/invalidate by tag, so `revalidateTag` is forward-looking (custom store); today entries expire by TTL/SWR. No `revalidatePath`. |
+| React Router / Remix `shouldRevalidate`    | **Axis 2**         | This is the correct mental model for Rango's `revalidate()`.                                                                                                                                                                    |
+| HTTP `Cache-Control` / ISR                 | **Axis 1**         | Edge/document layer — see `/document-cache`. Separate from both `cache()` and `revalidate()`.                                                                                                                                   |
+| Remix/RR `loader`                          | live data          | Like Rango loaders, fresh per request — but Rango loaders run in parallel and stream (latency overlaps first paint), and can opt into caching on demand.                                                                        |
 
 See `/cache-guide` for the axis-1 decision guide, `/loader` and `/route` for
 `revalidate()` (axis 2), and `/document-cache` for the edge layer.

package/skills/use-cache/SKILL.md

@@ -68,7 +68,10 @@ createRouter({
 
 - `"use cache"` (no name) resolves to `default`.
 - `"use cache: short"` resolves to the `short` profile.
-- Unknown profile names throw at build/boot time.
+- Unknown profile names throw at runtime, on the first invocation of the cached
+  function (the Vite transform does not validate names at build/boot). The error
+  is actionable -- it names the missing profile and shows the `createRouter({
+cacheProfiles: { ... } })` entry to add.
 
 ## Cache Key
 
@@ -77,18 +80,33 @@ use-cache:{functionId}:{serializedArgs}
 ```
 
 - `functionId` -- stable ID from Vite transform (module path + export name).
-- `serializedArgs` -- non-tainted arguments serialized via RSC `encodeReply()`.
+- `serializedArgs` -- key-generating arguments serialized via RSC `encodeReply()`.
+
+When there are no key-generating arguments, the key has no trailing colon -- it is
+just `use-cache:{functionId}`.
 
 Different functions always produce different cache keys, even for the same route.
 This is important for intercepted routes -- the path handler and intercept handler
 each have their own `functionId` and therefore their own cache entries.
 
+### Route context is folded into the key
+
+The tainted `ctx` object is excluded from arg serialization (see below), but
+route-identifying fields read off it are extracted into `serializedArgs`:
+`url.host`, route name (`_routeName`), `pathname`, `params`, response type
+(`_responseType`), and the user-facing sorted search params (internal `_rsc*`/`__`
+params excluded). The same cached function called with `ctx` on different routes,
+param combinations, hosts, response types, or query variants therefore produces
+distinct cache entries -- not one shared entry.
+
 ## Tainted Arguments (ctx, env, req)
 
 Request-scoped objects are branded with `Symbol.for('rango:nocache')` at creation.
 When detected:
 
 1. **Excluded from cache key** -- request-scoped, not meaningful for keying.
+   (The route-identifying fields read off `ctx` are still folded in -- see
+   "Route context is folded into the key" above.)
 2. **Handle data captured on miss** -- side effects via `ctx.use(Handle)` are recorded.
 3. **Handle data replayed on hit** -- restored into the current request's HandleStore.
 
@@ -122,12 +140,16 @@ const data = await getCachedData(locale); // locale is now in the cache key
 These ctx methods **throw** inside a `"use cache"` function because their effects
 are lost on cache hit (the function body is skipped):
 
-- `ctx.set()` / `ctx.get()` for passing values to children
+- `ctx.set()` for passing values to children
 - `ctx.header()`
 - `ctx.setTheme()`
 - `ctx.setLocationState()`
 - `ctx.onResponse()`
 
+`ctx.get()` is **not** exec-guarded inside `"use cache"` -- it is a read, so it is
+safe. (It only throws when reading a non-cacheable variable inside the separate
+route-level `cache()` DSL boundary.)
+
 The error message recommends two alternatives:
 
 1. Extract the data fetch into a separate cached function and call ctx methods outside it.
@@ -304,8 +326,15 @@ export async function getProducts() {
 ## Backing Store
 
 Writes to the same `SegmentCacheStore` as `cache()` DSL, `Static()`, and `Prerender()`.
-One store, one configuration, one invalidation API. Tag-based invalidation
-(`revalidateTag`) works across all mechanisms.
+One store, one configuration.
+
+Cache entries (and `cacheProfiles`) accept an optional `tags` field, but the
+built-in stores (`MemorySegmentCacheStore`, `CFCacheStore`) do not yet index or
+invalidate by tag -- tags are passed through to the store and otherwise ignored.
+Tag-based invalidation (`revalidateTag`) is a forward-looking API that requires a
+custom store with secondary indices. Today entries expire by TTL/SWR. The separate
+`revalidate()` export is the client-update axis (which segments re-render on a
+navigation or action), not a cache bust.
 
 ## Interaction with Other Caching
 

package/src/browser/react/location-state-shared.ts

@@ -3,6 +3,8 @@
  * No "use client" directive so it can be imported from RSC
  */
 
+import type { ReactElement } from "react";
+
 /**
  * Internal entry representing a state value with its unique key.
  * When __rsc_ls_lazy is true, __rsc_ls_value holds a getter function
@@ -22,6 +24,88 @@ export interface LocationStateOptions {
   flash?: boolean;
 }
 
+type LocationStateUnsafeFn = (...args: never[]) => unknown;
+
+// Broadest constructor signature (`abstract` covers both abstract and concrete
+// classes). A class passed as state has a `new` signature, not a call signature,
+// so it slips past LocationStateUnsafeFn; at runtime the lazy-getter path
+// (`typeof value === "function"`) then mistakes it for a getter and throws.
+type LocationStateUnsafeCtor = abstract new (...args: never[]) => unknown;
+
+// `unknown` cannot be verified serializable, so it is rejected (callers must
+// supply a concrete type). `any` deliberately defeats type checking and is NOT
+// guardable — it is assignable to the branded error too, so the check always
+// passes; it remains an explicit escape hatch.
+type IsAny<T> = 0 extends 1 & T ? true : false;
+type IsUnknown<T> =
+  IsAny<T> extends true ? false : unknown extends T ? true : false;
+
+/**
+ * Branded error surfaced when a value that cannot live in location state is
+ * used. Location state is written into `history.state`, which uses the
+ * structured clone algorithm; React elements, functions, and symbols throw a
+ * `DataCloneError` at runtime. Carries a human-readable reason so the compile
+ * error explains the fix.
+ */
+export type LocationStateUnsafe<Reason extends string> = {
+  readonly __rango_location_state_unsafe: Reason;
+};
+
+/**
+ * Maps `T` to itself when it is safe to store in location state, or to a branded
+ * {@link LocationStateUnsafe} error for the disallowed parts: `unknown`, React
+ * elements (RSC/JSX content), functions, class constructors, and symbols.
+ * Recurses through arrays, `Map`, `Set`, and plain objects; structured-clone
+ * built-ins (`Date`, `RegExp`, typed arrays, `Blob`, `File`, `FormData`) pass
+ * through. Consumed by {@link ValidateLocationState}, which is intersected into a
+ * definition's value parameter so posting RSC content is a COMPILE error, not a
+ * runtime `DataCloneError`. (`any` is unguardable and remains an escape hatch.)
+ */
+export type LocationStateSafe<T> =
+  IsUnknown<T> extends true
+    ? LocationStateUnsafe<"location state needs an explicit, concrete type; `unknown` cannot be verified as serializable">
+    : T extends LocationStateUnsafeFn
+      ? LocationStateUnsafe<"functions cannot be stored in location state">
+      : T extends LocationStateUnsafeCtor
+        ? LocationStateUnsafe<"class constructors cannot be stored in location state">
+        : T extends symbol
+          ? LocationStateUnsafe<"symbols cannot be stored in location state">
+          : T extends ReactElement
+            ? LocationStateUnsafe<"React/RSC content cannot be stored in location state; store plain data and render it on arrival">
+            : T extends string | number | boolean | bigint | null | undefined
+              ? T
+              : T extends
+                    | Date
+                    | RegExp
+                    | ArrayBuffer
+                    | ArrayBufferView
+                    | Blob
+                    | File
+                    | FormData
+                ? T
+                : T extends ReadonlyMap<infer K, infer V>
+                  ? ReadonlyMap<LocationStateSafe<K>, LocationStateSafe<V>>
+                  : T extends ReadonlySet<infer V>
+                    ? ReadonlySet<LocationStateSafe<V>>
+                    : T extends readonly unknown[]
+                      ? { [K in keyof T]: LocationStateSafe<T[K]> }
+                      : T extends object
+                        ? { [K in keyof T]: LocationStateSafe<T[K]> }
+                        : T;
+
+/**
+ * `unknown` (a no-op) when `T` is safe to store in location state, otherwise a
+ * branded {@link LocationStateUnsafe} object. Intersected into the value
+ * parameter of a definition's call and `write()` so POSTING RSC content (or any
+ * non-serializable value) is a compile error whose text carries the reason —
+ * without a `TState extends ...` self-constraint, which TypeScript rejects as
+ * circular (TS2313). For safe `T`, `value & unknown` collapses back to `value`,
+ * so valid usage is unchanged.
+ */
+export type ValidateLocationState<T> = [T] extends [LocationStateSafe<T>]
+  ? unknown
+  : LocationStateUnsafe<"location state must be serializable: React/RSC content, functions, and symbols cannot be stored — pass plain data and render it on arrival">;
+
 /**
  * Type-safe location state definition
  *
@@ -59,7 +143,7 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
    *
    * Client-only: throws when called on the server (no history available).
    */
-  write(value: TState): void;
+  write(value: TState & ValidateLocationState<TState>): void;
   /**
    * Statically remove this definition's slot from the current history entry,
    * leaving any other keys on history.state untouched. Idempotent: removing
@@ -118,7 +202,10 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
  */
 export function createLocationState<TState>(
   options?: LocationStateOptions,
-): LocationStateDefinition<[TState | (() => TState)], TState> {
+): LocationStateDefinition<
+  [(TState | (() => TState)) & ValidateLocationState<TState>],
+  TState
+> {
   const flash = options?.flash ?? false;
   let _key: string | undefined;
 
@@ -209,7 +296,10 @@ export function createLocationState<TState>(
     enumerable: true,
   });
 
-  return fn as LocationStateDefinition<[TState | (() => TState)], TState>;
+  return fn as unknown as LocationStateDefinition<
+    [(TState | (() => TState)) & ValidateLocationState<TState>],
+    TState
+  >;
 }
 
 /**

package/src/build/route-types/per-module-writer.ts

@@ -97,7 +97,10 @@ export function writePerModuleRouteTypesForFile(filePath: string): void {
       routes = extractRoutesFromSource(source);
     }
 
-    const genPath = filePath.replace(/\.(tsx?)$/, ".gen.ts");
+    // Match .ts/.tsx/.js/.jsx (same as router-processing.ts / router-transform.ts).
+    // Without the jsx? branch a .jsx/.js source produced genPath === filePath,
+    // overwriting the source file instead of writing a sibling .gen.ts.
+    const genPath = filePath.replace(/\.(tsx?|jsx?)$/, ".gen.ts");
 
     // When a urls() variable was found but static resolution yields zero
     // routes, write an empty placeholder so generated imports stay

package/src/cache/cache-scope.ts

@@ -187,6 +187,32 @@ export class CacheScope {
     return resolveCacheKey(keyFn, this.getStore(), defaultKey, "CacheScope");
   }
 
+  /**
+   * Evaluate the cache `condition` predicate. Returns false (skip the cache
+   * operation) when the predicate returns false or throws; returns true when
+   * there is no condition or no request context to evaluate it against.
+   */
+  private conditionAllows(op: "read" | "write"): boolean {
+    if (this.config === false || !this.config.condition) return true;
+    const requestCtx = getRequestContext();
+    if (!requestCtx) return true;
+    try {
+      if (!this.config.condition(requestCtx)) {
+        debugCacheLog(
+          `[CacheScope] condition returned false, skipping cache ${op}`,
+        );
+        return false;
+      }
+      return true;
+    } catch (error) {
+      console.error(
+        `[CacheScope] condition function threw, skipping cache ${op}:`,
+        error,
+      );
+      return false;
+    }
+  }
+
   /**
    * Lookup cached segments for a route (single cache entry per request).
    * Returns { segments, shouldRevalidate } or null if cache miss.
@@ -204,27 +230,7 @@ export class CacheScope {
     shouldRevalidate: boolean;
   } | null> {
     if (!this.enabled) return null;
-
-    // Evaluate condition — skip cache read when condition returns false
-    if (this.config !== false && this.config.condition) {
-      const requestCtx = getRequestContext();
-      if (requestCtx) {
-        try {
-          if (!this.config.condition(requestCtx)) {
-            debugCacheLog(
-              `[CacheScope] condition returned false, skipping cache read`,
-            );
-            return null;
-          }
-        } catch (error) {
-          console.error(
-            `[CacheScope] condition function threw, skipping cache read:`,
-            error,
-          );
-          return null;
-        }
-      }
-    }
+    if (!this.conditionAllows("read")) return null;
 
     const store = this.getStore();
     if (!store) return null;
@@ -284,27 +290,7 @@ export class CacheScope {
     isIntercept?: boolean,
   ): Promise<void> {
     if (!this.enabled || segments.length === 0) return;
-
-    // Evaluate condition — skip cache write when condition returns false
-    if (this.config !== false && this.config.condition) {
-      const conditionCtx = getRequestContext();
-      if (conditionCtx) {
-        try {
-          if (!this.config.condition(conditionCtx)) {
-            debugCacheLog(
-              `[CacheScope] condition returned false, skipping cache write`,
-            );
-            return;
-          }
-        } catch (error) {
-          console.error(
-            `[CacheScope] condition function threw, skipping cache write:`,
-            error,
-          );
-          return;
-        }
-      }
-    }
+    if (!this.conditionAllows("write")) return;
 
     const store = this.getStore();
     if (!store) return;

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

@@ -56,6 +56,15 @@ export const CACHE_STALE_AT_HEADER = "x-edge-cache-stale-at";
 /** Header storing cache status: HIT | REVALIDATING */
 export const CACHE_STATUS_HEADER = "x-edge-cache-status";
 
+/**
+ * Header stashing the route author's original Cache-Control on L1 document
+ * entries. putResponse/promoteResponseToL1 overwrite Cache-Control with a long
+ * `max-age` so the CF Cache API retains the entry across the whole SWR window;
+ * getResponse restores this original value before serving so the client and any
+ * upstream CDN see the author's intended directive, not the internal edge TTL.
+ */
+const CACHE_ORIG_CC_HEADER = "x-edge-cache-orig-cc";
+
 /**
  * Maximum age in seconds for REVALIDATING status before allowing new revalidation.
  * After this period, a stale entry in REVALIDATING status will trigger revalidation again.
@@ -182,7 +191,7 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
    * 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 `rsc-router:version` virtual module.
+   * 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;
@@ -419,7 +428,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       }
 
       // L2: persist to KV
-      this.kvSetSegment(key, data, staleAt, totalTtl);
+      this.kvSetSegment(key, data, staleAt, totalTtl, swrWindow);
     } catch (error) {
       console.error("[CFCacheStore] set failed:", error);
     }
@@ -478,7 +487,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       const isStale = staleAt > 0 && Date.now() > staleAt;
 
       return {
-        response,
+        response: this.toClientResponse(response),
         shouldRevalidate: isStale,
       };
     } catch (error) {
@@ -487,6 +496,30 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     }
   }
 
+  /**
+   * Strip internal edge headers and restore the author's Cache-Control before a
+   * cached document Response is served to a client. L1 entries carry the
+   * internal staleness/status headers and a rewritten Cache-Control; none of
+   * those should reach the browser or an upstream CDN.
+   */
+  private toClientResponse(response: Response): Response {
+    const headers = new Headers(response.headers);
+    const originalCacheControl = headers.get(CACHE_ORIG_CC_HEADER);
+    if (originalCacheControl !== null) {
+      headers.set("Cache-Control", originalCacheControl);
+    } else {
+      headers.delete("Cache-Control");
+    }
+    headers.delete(CACHE_ORIG_CC_HEADER);
+    headers.delete(CACHE_STALE_AT_HEADER);
+    headers.delete(CACHE_STATUS_HEADER);
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    });
+  }
+
   /**
    * Store a Response with TTL and optional SWR window (for document-level caching).
    * When KV is configured, also persists to L2.
@@ -513,8 +546,14 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           : [null, null]
         : [response.body, null];
 
-      // Clone and add cache headers
+      // Clone and add cache headers. The author's Cache-Control is stashed and
+      // replaced with a long max-age so the CF Cache API holds the entry across
+      // the SWR window; getResponse restores the original before serving.
       const headers = new Headers(response.headers);
+      const originalCacheControl = response.headers.get("Cache-Control");
+      if (originalCacheControl !== null) {
+        headers.set(CACHE_ORIG_CC_HEADER, originalCacheControl);
+      }
       headers.set("Cache-Control", `public, max-age=${totalTtl}`);
       headers.set(CACHE_STALE_AT_HEADER, String(staleAt));
 
@@ -764,13 +803,13 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     data: CachedEntryData,
     staleAt: number,
     totalTtl: number,
+    swrWindow: number,
   ): void {
     // KV requires expirationTtl >= 60s. Skip write for short-lived entries.
     if (!this.kv || !this.waitUntil || totalTtl < 60) return;
 
     const kvKey = this.toKVKey(key);
-    const swrWindow = totalTtl * 1000 - (staleAt - Date.now());
-    const expiresAt = staleAt + swrWindow;
+    const expiresAt = staleAt + swrWindow * 1000;
 
     this.waitUntil(async () => {
       try {
@@ -937,6 +976,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         const request = this.keyToRequest(`doc:${key}`);
 
         const headers = new Headers(envelope.hd);
+        const originalCacheControl = headers.get("Cache-Control");
+        if (originalCacheControl !== null) {
+          headers.set(CACHE_ORIG_CC_HEADER, originalCacheControl);
+        }
         headers.set("Cache-Control", `public, max-age=${remainingTtl}`);
         headers.set(CACHE_STALE_AT_HEADER, String(envelope.s));