@timber-js/app 0.2.0-alpha.167 → 0.2.0-alpha.169

package/docs/learn/14-deploying.mdx

@@ -65,15 +65,19 @@ For caching, use `CloudflareKVCacheHandler`:
 
 ```ts title="timber.config.ts"
 import { cloudflare } from '@timber-js/app/adapters/cloudflare';
-import { CloudflareKVCacheHandler } from '@timber-js/app/adapters/cloudflare/cache';
 
 export default {
   output: 'server',
   adapter: cloudflare(),
-  cacheHandler: new CloudflareKVCacheHandler({ bindingName: 'TIMBER_CACHE' }),
 };
 ```
 
+```ts title="timber.cache.ts"
+import { CloudflareKVCacheHandler } from '@timber-js/app/adapters/cloudflare/cache';
+
+export default new CloudflareKVCacheHandler({ bindingName: 'TIMBER_CACHE' });
+```
+
 **Constraints:** no file system, 10ms/30s CPU time limits, 10MB/25MB bundle size.
 
 ## Node.js & Docker
@@ -226,30 +230,26 @@ When using the Cloudflare adapter, CDN purge is **automatic** — no configurati
 
 For non-Workers Cloudflare zones (Enterprise), or other CDNs, configure a purge handler manually:
 
-```ts title="timber.config.ts"
+```ts title="timber.cache.ts"
 import { CloudflarePurge } from '@timber-js/app/cdn/cloudflare';
 
-export default {
-  // Only needed for non-Workers Cloudflare zones (Enterprise)
-  cdnPurge: new CloudflarePurge({
-    zoneId: process.env.CF_ZONE_ID!,
-    apiToken: process.env.CF_API_TOKEN!,
-  }),
-};
+// Only needed for non-Workers Cloudflare zones (Enterprise)
+export const cdnPurge = new CloudflarePurge({
+  zoneId: process.env.CF_ZONE_ID!,
+  apiToken: process.env.CF_API_TOKEN!,
+});
 ```
 
 Fastly:
 
-```ts title="timber.config.ts"
+```ts title="timber.cache.ts"
 import { FastlyPurge } from '@timber-js/app/cdn/fastly';
 
-export default {
-  cdnPurge: new FastlyPurge({
-    serviceId: process.env.FASTLY_SERVICE_ID!,
-    apiToken: process.env.FASTLY_API_TOKEN!,
-    softPurge: true,
-  }),
-};
+export const cdnPurge = new FastlyPurge({
+  serviceId: process.env.FASTLY_SERVICE_ID!,
+  apiToken: process.env.FASTLY_API_TOKEN!,
+  softPurge: true,
+});
 ```
 
 When `revalidateTag('products')` fires, it clears the application cache **and** calls the CDN purge handler. CDN purge is best-effort — failures are logged but don't break cache invalidation.

package/docs/more/04-metadata-and-fonts.mdx

@@ -87,7 +87,7 @@ Special files in your route tree generate metadata endpoints:
 
 When `opengraph-image.tsx` exists in a segment, timber automatically emits both `<meta property="og:image">` and `<meta name="twitter:image">` in `<head>` — no need to declare them in your `metadata` export. The auto-linked URL includes a cache-busting hash so social platforms pick up changes on redeploy.
 
-If you declare `openGraph.images` in your metadata, the auto-linked tags are suppressed (user-declared metadata wins).
+If you declare `openGraph.images` in your metadata, both auto-linked tags are suppressed. If you declare only `twitter.images`, the auto-linked `twitter:image` is suppressed but `og:image` is still emitted. User-declared metadata always wins.
 
 `favicon.tsx` lets you generate favicons dynamically (e.g. tenant branding). The URL stays `/favicon.ico` for browser compatibility.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.167",
+  "version": "0.2.0-alpha.169",
   "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",
@@ -158,13 +158,13 @@
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
-    "@opentelemetry/context-async-hooks": "^2.8.0",
-    "@opentelemetry/sdk-trace-base": "^2.8.0",
+    "@opentelemetry/context-async-hooks": "^2.9.0",
+    "@opentelemetry/sdk-trace-base": "^2.9.0",
     "cookie": "^1.1.1",
+    "jsonc-parser": "^3.3.1",
     "magic-string": "^0.30.21",
     "nitro": "3.0.260610-beta",
-    "srvx": "^0.11.17",
-    "jsonc-parser": "^3.3.1"
+    "srvx": "^0.11.22"
   },
   "peerDependencies": {
     "@content-collections/core": "^0.14.0 || ^0.15.0",
@@ -176,7 +176,7 @@
     "nuqs": "^2.0.0",
     "react": "19.2.7",
     "react-dom": "19.2.7",
-    "vite": "^8.1.0",
+    "vite": "8.1.0",
     "wrangler": "^4.0.0",
     "zod": "^3.22.0 || ^4.0.0"
   },

package/src/adapters/cloudflare-kv-cache.ts

@@ -1,5 +1,6 @@
 import type { CacheHandler } from '../cache/index';
 import { getCloudflareBindings } from './cloudflare';
+import { warnLossyJsonValue } from '../cache/json-lossy-check.js';
 
 /**
  * Cloudflare Workers KV interface — the subset of KVNamespace we depend on.
@@ -117,6 +118,7 @@ export class CloudflareKVCacheHandler implements CacheHandler {
     value: unknown,
     opts: { ttl: number; tags: string[]; generation?: number }
   ): Promise<void> {
+    warnLossyJsonValue(value, key);
     const kv = this.getKV();
     const entry: KVCacheEntry = {
       value,
@@ -127,12 +129,16 @@ export class CloudflareKVCacheHandler implements CacheHandler {
     // KV expirationTtl minimum is 60s. Use 2× TTL (min 60s) so stale entries
     // survive for staleWhileRevalidate background refetches.
     const kvTtl = Math.max(opts.ttl * 2, 60);
-    await kv.put(this.dataKey(key), JSON.stringify(entry), { expirationTtl: kvTtl });
 
-    // Update tag indexes — prune physically expired members on each write so
-    // indexes don't grow unboundedly. Uses the physical KV expiry (2× TTL) as
-    // the deadline, not the logical expiresAt, so stale entries in the SWR
-    // window remain in the index for invalidate({tag}) to find.
+    // Serialize upfront so BigInt/non-serializable errors throw before any
+    // writes — prevents tag indexes pointing at stale data from a prior set().
+    const payload = JSON.stringify(entry);
+
+    // Tag indexes are written BEFORE the data key so that a partial network
+    // failure on the data write never leaves an entry invisible to
+    // invalidate({tag}). A dangling tag-index reference to a non-existent
+    // data key is harmless — invalidate() re-checks stored tags and cleans
+    // up on the next pass.
     const now = Date.now();
     const kvExpiresAt = now + kvTtl * 1000;
     await Promise.all(
@@ -145,6 +151,8 @@ export class CloudflareKVCacheHandler implements CacheHandler {
         });
       })
     );
+
+    await kv.put(this.dataKey(key), payload, { expirationTtl: kvTtl });
   }
 
   async invalidate(opts: { key?: string; tag?: string }): Promise<void> {
@@ -175,7 +183,20 @@ export class CloudflareKVCacheHandler implements CacheHandler {
     if (opts.tag) {
       const entries = parseTagIndex(await kv.get(this.tagKey(opts.tag), { type: 'json' }));
       if (entries.length > 0) {
-        await Promise.all(entries.map((e) => kv.delete(this.dataKey(e.key))));
+        // Re-check each member's stored tags before deleting — the tag index
+        // can contain stale references from partial writes or entries whose
+        // tags changed since they were indexed. Mirrors Redis handler behavior.
+        await Promise.all(
+          entries.map(async (e) => {
+            const raw = (await kv.get(this.dataKey(e.key), {
+              type: 'json',
+            })) as KVCacheEntry | null;
+            if (!raw) return;
+            if (raw.tags?.includes(opts.tag!)) {
+              await kv.delete(this.dataKey(e.key));
+            }
+          })
+        );
       }
       await kv.delete(this.tagKey(opts.tag));
     }

package/src/cache/index.ts

@@ -167,7 +167,7 @@ export class MemoryCacheHandler implements CacheHandler {
 }
 
 export { RedisCacheHandler } from './redis-handler';
-export type { RedisClient } from './redis-handler';
+export type { RedisClient, RedisWriteOp } from './redis-handler';
 export { cache } from './cache-api';
 export { setCacheHandler, getCacheHandler } from './handler-store';
 export { setDefaultSingleflightTimeout } from './timber-cache';

package/src/cache/json-lossy-check.ts

@@ -0,0 +1,75 @@
+const LOSSY_TYPES = ['Date', 'Map', 'Set', 'BigInt'] as const;
+
+let hasWarned = false;
+
+/**
+ * Dev-mode warning when a cache value contains types that lose fidelity
+ * through JSON round-trip. Only runs in development — no-op in production.
+ *
+ * Detects: Date (→ ISO string), Map/Set (→ {}), BigInt (→ throws).
+ * Emits once per process to avoid log spam.
+ */
+export function warnLossyJsonValue(value: unknown, cacheKey: string): void {
+  if (hasWarned) return;
+  if (process.env.NODE_ENV === 'production') return;
+
+  const lossy = findLossyTypes(value, new Set(), 0);
+  if (lossy.size === 0) return;
+
+  hasWarned = true;
+  const types = [...lossy].join(', ');
+  console.warn(
+    `[timber] cache value for key "${cacheKey}" contains ${types} — ` +
+      'these types lose fidelity through JSON serialization in Redis/KV cache handlers. ' +
+      'Date becomes an ISO string, Map/Set become {}, BigInt throws. ' +
+      'The MemoryCacheHandler preserves them. Consider transforming values ' +
+      'to JSON-safe types before caching, or use MemoryCacheHandler for ' +
+      'values that require type preservation.'
+  );
+}
+
+function findLossyTypes(value: unknown, seen: Set<unknown>, depth: number): Set<string> {
+  const lossy = new Set<string>();
+  if (depth > 8 || value === null || value === undefined) return lossy;
+  if (typeof value === 'bigint') {
+    lossy.add('BigInt');
+    return lossy;
+  }
+  if (typeof value !== 'object' && typeof value !== 'function') return lossy;
+  if (seen.has(value)) return lossy;
+  seen.add(value);
+
+  if (value instanceof Date) {
+    lossy.add('Date');
+    return lossy;
+  }
+  if (value instanceof Map) {
+    lossy.add('Map');
+    return lossy;
+  }
+  if (value instanceof Set) {
+    lossy.add('Set');
+    return lossy;
+  }
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      for (const t of findLossyTypes(item, seen, depth + 1)) lossy.add(t);
+      if (lossy.size === LOSSY_TYPES.length) return lossy;
+    }
+    return lossy;
+  }
+
+  for (const k of Object.keys(value as Record<string, unknown>)) {
+    for (const t of findLossyTypes((value as Record<string, unknown>)[k], seen, depth + 1)) {
+      lossy.add(t);
+    }
+    if (lossy.size === LOSSY_TYPES.length) return lossy;
+  }
+  return lossy;
+}
+
+/** Reset warning state — for tests only. */
+export function _resetLossyWarning(): void {
+  hasWarned = false;
+}

package/src/cache/redis-handler.ts

@@ -1,4 +1,5 @@
 import type { CacheHandler } from './index';
+import { warnLossyJsonValue } from './json-lossy-check.js';
 
 /**
  * Minimal Redis client contract for `RedisCacheHandler`.
@@ -27,6 +28,19 @@ import type { CacheHandler } from './index';
  *   srem: (k, ...m) => redis.srem(k, ...m),
  *   smembers: (k) => redis.smembers(k),
  *   ttl: (k) => redis.ttl(k),
+ *   execMulti: async (ops) => {
+ *     const p = redis.multi();
+ *     for (const op of ops) {
+ *       switch (op.op) {
+ *         case 'set': p.set(op.key, op.value, 'EX', op.ttlSeconds); break;
+ *         case 'sadd': p.sadd(op.key, ...op.members); break;
+ *         case 'expireNX': p.expire(op.key, op.seconds, 'NX'); break;
+ *         case 'expireGT': p.expire(op.key, op.seconds, 'GT'); break;
+ *         case 'del': p.del(op.key); break;
+ *       }
+ *     }
+ *     await p.exec();
+ *   },
  * };
  * ```
  *
@@ -67,6 +81,13 @@ import type { CacheHandler } from './index';
  * };
  * ```
  */
+export type RedisWriteOp =
+  | { op: 'set'; key: string; value: string; ttlSeconds: number }
+  | { op: 'sadd'; key: string; members: string[] }
+  | { op: 'expireNX'; key: string; seconds: number }
+  | { op: 'expireGT'; key: string; seconds: number }
+  | { op: 'del'; key: string };
+
 export interface RedisClient {
   /** `GET key` — the stored string, or null when absent. */
   get(key: string): Promise<string | null>;
@@ -99,6 +120,13 @@ export interface RedisClient {
    * not exist, -1 if the key exists but has no expiry.
    */
   ttl(key: string): Promise<number>;
+  /**
+   * Execute a batch of write operations atomically via `MULTI/EXEC`.
+   * When provided, `set()` uses this to make tag-index writes and the data
+   * write atomic — no `invalidate({tag})` can interleave. Optional: when
+   * absent, operations run sequentially (correct but not race-free).
+   */
+  execMulti?(ops: RedisWriteOp[]): Promise<void>;
 }
 
 const KEY_PREFIX = 'timber:cache:';
@@ -146,8 +174,12 @@ export class RedisCacheHandler implements CacheHandler {
     value: unknown,
     opts: { ttl: number; tags: string[]; generation?: number }
   ): Promise<void> {
+    warnLossyJsonValue(value, key);
     const ck = this.cacheKey(key);
     const expiresAt = Date.now() + opts.ttl * 1000;
+
+    // Serialize upfront so BigInt/non-serializable errors throw before any
+    // writes — prevents tag indexes pointing at stale data from a prior set().
     const payload = JSON.stringify({ value, expiresAt, tags: opts.tags });
 
     // Redis TTL with generous margin beyond the logical TTL to allow SWR reads
@@ -155,22 +187,41 @@ export class RedisCacheHandler implements CacheHandler {
     // We use 2x TTL + 60s as the Redis expiry so stale entries remain
     // available for SWR background refetches.
     const redisTtlSeconds = Math.max(opts.ttl * 2 + 60, 120);
-    await this.client.set(ck, payload, redisTtlSeconds);
 
-    // Track key membership in each tag set, and expire the set so it doesn't
-    // outlive all its members. Only extend the TTL, never shorten — a short-TTL
-    // entry must not shrink a tag set that already contains long-TTL entries,
-    // otherwise invalidate({tag}) would miss the long-lived entries.
+    const writeOps: RedisWriteOp[] = [];
     for (const tag of opts.tags) {
-      await this.client.sadd(this.tagKey(tag), key);
-      // Two atomic EXPIRE calls cover both the initial-set and extend cases:
-      // - NX: sets the TTL only if the key has no expiry (new tag set from SADD)
-      // - GT: extends the TTL only if the new value is greater than current
-      // Together they close the race where concurrent workers could shrink the
-      // tag set lifetime (TIM-1093), while ensuring new tag sets always get an
-      // initial expiry (without NX, GT is a no-op on non-volatile keys).
-      await this.client.expireNX(this.tagKey(tag), redisTtlSeconds);
-      await this.client.expireGT(this.tagKey(tag), redisTtlSeconds);
+      writeOps.push({ op: 'sadd', key: this.tagKey(tag), members: [key] });
+      writeOps.push({ op: 'expireNX', key: this.tagKey(tag), seconds: redisTtlSeconds });
+      writeOps.push({ op: 'expireGT', key: this.tagKey(tag), seconds: redisTtlSeconds });
+    }
+    writeOps.push({ op: 'set', key: ck, value: payload, ttlSeconds: redisTtlSeconds });
+
+    if (this.client.execMulti) {
+      await this.client.execMulti(writeOps);
+    } else {
+      for (const op of writeOps) {
+        await this.execOp(op);
+      }
+    }
+  }
+
+  private async execOp(op: RedisWriteOp): Promise<void> {
+    switch (op.op) {
+      case 'set':
+        await this.client.set(op.key, op.value, op.ttlSeconds);
+        break;
+      case 'sadd':
+        await this.client.sadd(op.key, ...op.members);
+        break;
+      case 'expireNX':
+        await this.client.expireNX(op.key, op.seconds);
+        break;
+      case 'expireGT':
+        await this.client.expireGT(op.key, op.seconds);
+        break;
+      case 'del':
+        await this.client.del(op.key);
+        break;
     }
   }
 

package/src/cache/timber-cache.ts

@@ -7,7 +7,7 @@ import {
   wasInvalidatedSince,
 } from './invalidation-epoch';
 import { addSpanEventSync } from '../server/tracing.js';
-import { logSwrRefetchFailed } from '../server/logger.js';
+import { logSwrRefetchFailed, swallow } from '../server/logger.js';
 import { getWaitUntil } from '../server/waituntil-bridge.js';
 import { fnv1aHash } from './fast-hash.js';
 
@@ -189,7 +189,15 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
       const generation = nextGeneration(key);
       const result = await fn(...args);
       if (!signal.aborted && !wasInvalidatedSince(startEpoch, key, tags)) {
-        await getHandler().set(key, result, { ttl: opts.ttl, tags, generation });
+        try {
+          await getHandler().set(key, result, { ttl: opts.ttl, tags, generation });
+        } catch (err) {
+          // Cache-write failure must not fail the request (TIM-1046).
+          // JSON-serializing handlers (Redis, KV) throw on BigInt; network
+          // errors can surface from any shared handler. The result is valid
+          // — serve it uncached rather than rejecting a successful fn().
+          swallow(err, `cache set failed for key "${key}"`);
+        }
       }
       return result;
     };

package/src/client/browser-entry/index.ts

@@ -76,6 +76,8 @@ function bootstrap(runtimeConfig: typeof config): void {
   // Step 3: Create router + Navigation API integration
   const { router, navApiController } = createTimberRouter({
     initialElement: rscResult?.element ?? undefined,
+    clientSegmentCache:
+      ((runtimeConfig as Record<string, unknown>).clientSegmentCache as boolean) ?? false,
   });
 
   // Step 4: Pre-hydration — set params + navigation state (MUST run after router init)

package/src/client/browser-entry/router-init.ts

@@ -29,6 +29,7 @@ import { getScrollY, scrollToHashTarget } from './scroll.js';
 
 export interface RouterInitOptions {
   initialElement?: unknown;
+  clientSegmentCache?: boolean;
 }
 
 export interface RouterInitResult {
@@ -136,6 +137,7 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
   };
 
   const deps: RouterDeps = {
+    clientSegmentCache: options?.clientSegmentCache ?? false,
     fetch: (url, init) => window.fetch(url, init),
     pushState: (data, unused, url) => {
       gFlags[ROUTER_HISTORY_FLAG] = true;

package/src/client/router.ts

@@ -155,6 +155,13 @@ export interface RouterDeps {
    * as a full page load with an unknown fragment landing at the top.
    */
   scrollToHash?: (hash: string) => boolean;
+
+  /**
+   * Whether the client segment cache is enabled. When false (the default),
+   * the router does not send X-Timber-State-Tree headers and does not
+   * populate the segment cache. Every navigation gets a full RSC payload.
+   */
+  clientSegmentCache?: boolean;
 }
 
 export interface RouterInstance {
@@ -292,6 +299,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
   /** Update the segment cache from server-provided segment metadata. */
   function updateSegmentCache(segmentInfo: SegmentInfo[] | null | undefined): void {
+    if (!deps.clientSegmentCache) return;
     if (!segmentInfo || segmentInfo.length === 0) return;
     const tree = buildSegmentTree(segmentInfo);
     if (tree) {
@@ -540,7 +548,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     if (result === undefined) {
       // Fetch RSC payload with state tree for partial rendering.
       // Send current URL for intercepting route resolution (modal pattern).
-      const stateTree = segmentCache.serializeStateTree();
+      const stateTree = deps.clientSegmentCache ? segmentCache.serializeStateTree() : undefined;
       const rawCurrentUrl = deps.getCurrentUrl();
       const currentUrl = rawCurrentUrl.startsWith('http')
         ? new URL(rawCurrentUrl).pathname
@@ -734,7 +742,9 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         url,
         async (navAbort) => {
           await renderViaTransition(url, async () => {
-            const stateTree = segmentCache.serializeStateTree();
+            const stateTree = deps.clientSegmentCache
+              ? segmentCache.serializeStateTree()
+              : undefined;
             const result = await fetchRscPayload(url, deps, stateTree, undefined, navAbort.signal);
             const payload = await resolveForFallback(result.payload);
             const navState = commitNavigation(url, {
@@ -767,7 +777,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     if (historyStack.has(fetchUrl)) return;
 
     // Fire-and-forget fetch
-    const stateTree = segmentCache.serializeStateTree();
+    const stateTree = deps.clientSegmentCache ? segmentCache.serializeStateTree() : undefined;
     void fetchRscPayload(fetchUrl, deps, stateTree).then(
       (result) => {
         result.decodePromise?.catch(() => {});

package/src/codec.ts

@@ -80,8 +80,10 @@ export const codec = {
   integer: {
     parse(value: string | string[] | undefined): number {
       const str = Array.isArray(value) ? value[0] : value;
+      if (!str || !/^(?:0|-?[1-9]\d*)$/.test(str))
+        throw new Error(`Expected integer, got '${str}'`);
       const n = Number(str);
-      if (!Number.isInteger(n)) throw new Error(`Expected integer, got '${str}'`);
+      if (!Number.isSafeInteger(n)) throw new Error(`Expected integer, got '${str}'`);
       return n;
     },
     serialize(value: number): string | null {

package/src/config-types.ts

@@ -46,9 +46,6 @@ export interface TimberUserConfig {
    */
   clientJavascript?: boolean | ClientJavascriptConfig;
   adapter?: unknown;
-  cacheHandler?: unknown;
-  /** CDN purge handler — called on revalidateTag/cache.invalidate to purge CDN-cached responses. */
-  cdnPurge?: unknown;
   allowedOrigins?: string[];
   csrf?: boolean;
   limits?: {
@@ -56,40 +53,6 @@ export interface TimberUserConfig {
     uploadBodySize?: string;
     maxFields?: number;
   };
-  /**
-   * Server-action form handling.
-   *
-   * See design/08-forms-and-actions.md §"Validation errors" and
-   * design/13-security.md §"Sensitive field stripping".
-   */
-  /**
-   * Server action runtime behavior.
-   *
-   * See design/08-forms-and-actions.md §"Middleware for Server Actions".
-   */
-  actions?: {
-    /**
-     * Run `middleware.ts` on server action requests before dispatching.
-     *
-     * **Default: `true`** — middleware runs on every action POST so
-     * authentication, rate limiting, tenant isolation, IP allow-listing,
-     * and request-header injection apply uniformly to page renders, route
-     * handlers, and server actions. This closes the auth-bypass class of
-     * issue identified by Next.js CVE-2025-29927: developers can put a
-     * single auth check in `middleware.ts` and trust that it gates every
-     * unsafe-method request.
-     *
-     * Set to `false` to restore the legacy behavior where actions skip
-     * middleware entirely. This is **not recommended** outside of niche
-     * cases (e.g. middleware that rewrites POST bodies and would corrupt
-     * action submissions). When false, you are responsible for placing
-     * auth, rate limiting, and other cross-cutting checks inside every
-     * action — typically via `createActionClient({ middleware: ... })`.
-     *
-     * See TIM-871.
-     */
-    runMiddleware?: boolean;
-  };
   forms?: {
     /**
      * Strip sensitive fields (passwords, tokens, CVV, SSN, etc.) from the
@@ -286,6 +249,22 @@ export interface TimberUserConfig {
    * ```
    */
   buildDir?: string;
+  /**
+   * Enable the client-side segment cache for partial navigation.
+   *
+   * When enabled, the router serializes the mounted segment tree into an
+   * `X-Timber-State-Tree` header on every client navigation. The server
+   * skips re-rendering unchanged sync layouts and sends a partial RSC
+   * payload. The client merges the partial payload with its cached segments.
+   *
+   * When disabled (the default), every navigation gets a full RSC payload.
+   *
+   * This is a performance optimization only — not a security boundary.
+   * The server always runs all `access.ts` files regardless.
+   *
+   * See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+   */
+  clientSegmentCache?: boolean;
   topLoader?: {
     /** Whether the top-loader is enabled. Default: true. */
     enabled?: boolean;

package/src/config-validation.ts

@@ -30,12 +30,9 @@ const KNOWN_CONFIG_KEYS = {
   debug: true,
   clientJavascript: true,
   adapter: true,
-  cacheHandler: true,
-  cdnPurge: true,
   allowedOrigins: true,
   csrf: true,
   limits: true,
-  actions: true,
   forms: true,
   pageExtensions: true,
   slowRequestMs: true,
@@ -49,6 +46,7 @@ const KNOWN_CONFIG_KEYS = {
   reactCompiler: true,
   sitemap: true,
   buildDir: true,
+  clientSegmentCache: true,
   topLoader: true,
   budget: true,
 } satisfies Record<keyof TimberUserConfig, true>;
@@ -197,12 +195,16 @@ export function validateConfig(config: TimberUserConfig): ConfigError[] {
     }
   }
 
+  const MOVED_TO_CACHE_FILE = new Set(['cacheHandler', 'cdnPurge']);
+
   for (const key of Object.keys(config)) {
     if (!knownKeys.has(key)) {
       errors.push({
         field: key,
         message: `Unknown config option: "${key}".`,
-        suggestion: `Check for typos. Known options: ${[...knownKeys].sort().join(', ')}.`,
+        suggestion: MOVED_TO_CACHE_FILE.has(key)
+          ? `"${key}" has moved to timber.cache.ts. Export cacheHandler as default, cdnPurge as a named export.`
+          : `Check for typos. Known options: ${[...knownKeys].sort().join(', ')}.`,
       });
     }
   }
@@ -248,7 +250,7 @@ const VIRTUAL_MODULE_NAMES: Record<string, string> = {
   'virtual:timber-config': 'Runtime config (timber.config.ts)',
   'virtual:timber-route-manifest': 'Route manifest (app/ file tree)',
   'virtual:timber-instrumentation': 'Instrumentation (instrumentation.ts)',
-  'virtual:timber-cache-handler': 'Cache handler (cacheHandler config)',
+  'virtual:timber-cache-handler': 'Cache handler (timber.cache.ts)',
   'virtual:timber-build-manifest': 'Build manifest (asset mapping)',
 };
 

package/src/fonts/pipeline.ts

@@ -208,6 +208,38 @@ export class FontPipeline {
     }
   }
 
+  /** True if at least one entry is registered under `importer`. */
+  hasImporter(importer: string): boolean {
+    for (const entry of this._entries.values()) {
+      if (entry.importer === importer) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Drop **every** registry entry that originated from `importer`,
+   * regardless of family.
+   *
+   * Called at the start of the transform hook before re-registering the
+   * current extraction set. This handles the cases `pruneFor` misses:
+   *
+   * - **Family rename** (Inter → Roboto): the old family's entries are
+   *   cleared because we prune by importer, not by (importer, family).
+   * - **Font call deleted**: the old entries are cleared even though no
+   *   new call provides a family to prune against.
+   *
+   * Other importers' fonts are untouched.
+   *
+   * See TIM-1087.
+   */
+  pruneImporter(importer: string): void {
+    for (const [id, entry] of this._entries) {
+      if (entry.importer === importer) {
+        this._entries.delete(id);
+      }
+    }
+  }
+
   /** Drop every registered font. Used by tests and rebuild flows. */
   clear(): void {
     this._entries.clear();