@timber-js/app 0.2.0-alpha.161 → 0.2.0-alpha.164

package/docs/learn/00-introduction.mdx

@@ -9,68 +9,102 @@ notAI: true
 
 ## Basics
 
-Timber is a react-based web framework built on vite and server components. It is inspired by next.js, tanstack start, and remix however it brings an independent approach built on a more modern foundation.
+Timber is a react-based web framework built on Vite and Server Components. It is inspired by next.js, tanstack start, and remix however it brings an independent approach built on a modern and flexible foundation.
 
-It is built on web standards and attempts to use as little framework magic as possible. We feel it unlocks both the most flexible UX and DX possible. Rather than using heuristics to adjust how the framework operates, it gives you the knobs to fine-tune your website to your liking.
+It is designed to align with web standards and attempts to use as little framework magic as possible. We feel it unlocks both the most flexible UX and DX possible. Rather than using heuristics to adjust how the framework operates, it gives you the knobs to fine-tune your website to your liking.
 
-That means it is entirely possible to write an inefficient website with timber, however, you will also _understand_ exactly what is happening and have clear eyes on how to fix it.
+---
+
+Here are some of the ideas that drive Timber.
+
+### Architectural Optionality
+
+Timber is a framework that aims to bring architectural optionality. All websites run in three environments:
+
+* The Server
+* The Server and the Client (often called SSR or pre-rendering)
+* The Client
+
+The server brings forth access control, privacy, and performance and sets up the initial response to the user.
+
+The client unlocks interactivity, dynamic rendering, and cross-route state.
+
+SSR and pre-rendering bridge the two.
+
+Server Components unlock each environment to its fullest capacity, while allowing you to step through them via one unified component tree. And timber embraces them fully.
+
+### Upside-Down Astro
+
+Astro is a framework built for content and it's philsophy is: static first, islands of interactivity and dynamic content.
+
+Timber is the inverse of this approach: dynamic first, with islands of static content. In our experience, most webpages require some form of dynamic rendering. Expensive stuff, cached stuff, is usually on the leafier side – a component tree here and there. Only caching subsets of your tree gives you powerful performance without sacrificing the full server functionality (access control, middleware, logging, and more).
+
+We also find this to be a simpler mental model. Requests flow through the server – subsets of the page are cached. Interactivity and state exists throughout the tree and across routes.
+
+### Serialized Building Blocks: Cookies, Search Params, Segment Params
+
+Timber takes all of the building blocks of the web that are effectively: serialize data to a string and back and it gives you the guard rails to properly type and validate them. Things like cookies, search params, and segment params.
+
+Everything is driven by standard schemas (zod, valibot, nuqs, custom, etc.) and you create factory functions to access that data on the server and the client.
+
+```tsx
+import { defineSearchParams } from '@timber-js/app/search-params';
+import { z } from 'zod/v4';
+
+export const searchParams = defineSearchParams({
+  month: z.string().optional(),
+  day: z.string().optional(),
+  slug: z.string().optional(),
+});
+
+// later on
+const sp = searchParams.get();
+
+// or on the client
+
+const [sp, setSearchParams] = searchParams.useQueryState();
+```
 
-We believe that the best UX is often invisible, but the best DX is _transparent_. You shouldn't ever be confused about where something is running and why.
+### Typed Routes
 
-Timber is not a framework that comes with the simplest mental model – rather it embraces the _inherent complexity_ of the web and gives you the tools to define your boundaries as you see fit. Server and client, static and dynamic, build-time and run-time. So on and so forth. There is no one true _best_ place to put these boundaries, so it is incumbent on the developer to _choose_ where to place them.
+All routing in timber is fully typed and integrated. So you can write a `<Link>` as:
 
-Timber is a tool for frontend professionals. Though a beginner could pick it up and learn both the framework and the platform (the web) incrementally, it is best utilized by people who have a deep understanding of both the web and building websites.
+```tsx
+<Link href="/blog/[slug]" segmentParams={{ slug: 'a-post' }} searchParams={{ foo: 'bar' }}>Page</Link>
+```
 
-Think of it as a flexible toolbelt of tools: the mental model to understand each of these tools and how to use them is high, but once you do, the framework clicks into place. A simpler mental model may come with it an easier skill curve, but at the sacrifice of both user experience and developer experience.
+Or just normal `<a>` tags work too.
 
-Timber is understandable, but you'll have to be patient in understanding it. We feel it's worth the investment.
+### Middleware and Access Control
 
-## Philosophy
+Timber's routing and layouting system is almost 1:1 inspired by next.js. This file based routing structure lends itself to a compositional architecture, where you can build up layers of functionality as you go deeper into the route tree.
 
-All web frameworks are created out of some basic philosophies of how its creators feel websites should be built. Timber is no exception.
+The filesystem maps directly to the route tree. On top of that, because our architecture is dynamic first, we can give you: proper middleware and `access.ts` access control.
 
-Here's ours:
+When you hit a route, every segment's `middleware.ts` and `access.ts` is executed in series. Though some would call this slow, with a proper data architecture, we find that this is rarely the bottleneck to building a fast and performant website.
 
-A good web architecture _embraces_ the complexity of building websites. Since building a website is inherently complex, a framework that embraces that complexity will inevitably feel overwhelming at first. But I'd implore you to imagine it as a toolbelt that gives you access to each tool in the toolkit. As you understand the tools, the toolbelt falls into place.
+And the DX clarity and functionality gains are immense. Give it a try, you'll be surprised how nice it feels.
 
-So while a beginner could pick up this framework, and it could incrementally teach them each component of building a powerful website, this framework is _not_ designed to be the simplest mental model. This is a framework for the frontend professional. Or a team building a complex and powerful web experience.
+### Forms
 
-------
+Forms have long been the biggest pain point of building React apps. They are chonky, buggy, and painful to write. Timber flips forms on their head and make the whole process feel a lot more like _react_.
 
-This all sounds like a lot. I'm not here to say it isn't. But if you're building a serious website, if you work on a team of experienced engineers, an architecture that sits across these complexities and doesn't abstract them gives you the power to define your boundaries: server and client, static and dynamic, client js and not.
+Here are our rules for forms:
 
-To learn the inherent complexity of these ideas, you internalize an architecture that can scale up and down. One that gives you access to both UX and DX that is unparalleled and not limited. Timber does not dumb down our abstractions to make it easier to _understand_, because that comes at the cost of optionality.
+1. Forms must work consistently with or without javascript
+2. Inputs must _own their own state_ or be uncontrolled – no more hoisting your logic and context above the form. This makes sure forms are composable.
+3. You should be able to have global validation and input-level validation
+4. Validation should be possible to run on either the server, or the client
+5. Forms should maintain their data if submission fails (whether you are on the JS or non-JS track)
 
-Other frameworks that have pursued this have either abstracted away too much, leaned on too much magic, or ignored web standards. Timber is _not_ smarter than you. It doesn't try to be. You can write an inefficient website in Timber, and it won't stop you. But it also won't project onto you _how_ to build a website. It just gives you the foundation to control it yourself.
+Now you might say, wow, these are a lot of rules – even though they all sound good. But to handle all of these features, you'd need way more code.
 
-Again, if you're new to building websites, this is a tall task.
+Turns out – the opposite. It's way less code. It's more functional, more flexible, and you write less code to handle it all. Does the science back it up? Let's see:
 
-But the good news is, you don't have to understand this all immediately. You can layer on your understanding one by one. And I promise, in the long-term it will click. But you may have to touch it yourself one by one.
+### Developer Clarity
 
-{/* Here are our basic philosophies:
+We believe the good UX is invisible, but good DX is _transparent_. You should always be able to see what's going on. No caching is implicit.
 
-- All websites sit somewhere across three environments. Embracing these three as first-party targets is a bid for developer autonomy, not confusion.
-  - Server
-  - Client
-  - Isomorphic (Universal SSR)
-- Serverless is a flawed paradigm for rendering
-  - Though it can be useful at times, owning your _own_ server (and CPU cycles) will always be more performant and cost effective at anything beyond a basic scale
-  - An inefficiency in serverless means an unbounded/infinite bill, on a server it only means degraded performance
-  - A server means your database can live _next_ to your rendering layer, which will always outperform _holistic_ edge rendering in generic real-world scenarios
-- Your framework should never be smarter than you
-  - Good UX is invisible, good DX is transparent
-  - It's better to be understandable than magic, which means performance is fine tunable – rather than automatic
-- The web constantly serializes and deserializes strings, the framework should provide typing and parsing to those edges
-  - Search Params
-  - Cookies
-  - Segment URL Params
-  - and more...
-- A good web-framework scales horizontally across your surface API (routes)
-  - Adding more routes or components shouldn't affect performance on others
-- A good web framework has finely-tuned control over static (build-time) and dynamic (run-time) rendering
-- A good web framework has the ability to scale up and down functionally and with developer clarity, which means deploying a website that:
-  - Can ship zero client javascript
-  - Can ship static content
-  - And can scale up to a completely dynamic website */}
+-----
 
-More here soon...
+These are the core tenants of Timber. It's the framework I wish existed. Thanks for taking the time to look into it.

package/docs/learn/13-configuration.mdx

@@ -122,14 +122,33 @@ Server actions still work — HTML forms submit natively via POST without JavaSc
 
 ## All Options
 
-| Option             | Type                    | Default                      | Description               |
-| ------------------ | ----------------------- | ---------------------------- | ------------------------- |
-| `output`           | `'server' \| 'static'` | `'server'`                   | Output mode               |
-| `adapter`          | `TimberPlatformAdapter` | —                            | Deployment adapter        |
-| `cacheHandler`     | `CacheHandler`          | `MemoryCacheHandler`         | Cache backend             |
-| `clientJavascript` | `boolean \| object`     | `true`                       | Control client-side JS    |
-| `pageExtensions`   | `string[]`              | `['tsx', 'ts', 'jsx', 'js']` | File extensions for pages |
-| `mdx`              | `object`                | —                            | MDX remark/rehype plugins |
+| Option              | Type                        | Default                      | Description                              |
+| ------------------- | --------------------------- | ---------------------------- | ---------------------------------------- |
+| `output`            | `'server' \| 'static'`     | `'server'`                   | Output mode                              |
+| `debug`             | `boolean`                   | `false`                      | Enable timber debug logging in prod      |
+| `buildDir`          | `string`                    | `'.timber/dist'`             | Build output directory                   |
+| `clientJavascript`  | `boolean \| object`         | `true`                       | Control client-side JS                   |
+| `adapter`           | `TimberPlatformAdapter`     | —                            | Deployment adapter                       |
+| `cacheHandler`      | `CacheHandler`              | `MemoryCacheHandler`         | Cache backend                            |
+| `cdnPurge`          | `CdnPurgeHandler`           | —                            | CDN purge on revalidation                |
+| `serverTiming`      | `'detailed' \| 'total' \| false` | `'detailed'` / `'total'` | Server-Timing header                     |
+| `allowedOrigins`    | `string[]`                  | —                            | CORS / CSRF allowed origins              |
+| `csrf`              | `boolean`                   | `true`                       | CSRF protection                          |
+| `limits`            | `object`                    | —                            | Request body size limits                 |
+| `actions`           | `object`                    | —                            | Server action behavior                   |
+| `forms`             | `object`                    | —                            | Form handling (sensitive field stripping) |
+| `pageExtensions`    | `string[]`                  | `['tsx', 'ts', 'jsx', 'js']` | File extensions for pages                |
+| `slowRequestMs`     | `number`                    | `3000`                       | Slow request warning threshold (ms)      |
+| `renderTimeoutMs`   | `number`                    | `30000`                      | Render abort timeout (ms)                |
+| `devBrowserLogs`    | `string`                    | `'warn'`                     | Forward browser console to server in dev |
+| `dev`               | `object`                    | —                            | Dev-mode options                         |
+| `budget`            | `object`                    | —                            | Build-time performance budgets           |
+| `appDir`            | `string`                    | auto-detected                | Override app directory location          |
+| `mdx`               | `object`                    | —                            | MDX remark/rehype plugins                |
+| `actionEncryption`  | `object`                    | —                            | Server action bound args encryption      |
+| `reactCompiler`     | `boolean \| object`         | `false`                      | React Compiler auto-memoization          |
+| `sitemap`           | `object`                    | —                            | Auto-generated sitemap.xml               |
+| `topLoader`         | `object`                    | enabled                      | Navigation progress bar                  |
 
 For the full type definition, see the [Config API Reference](/docs/api-config).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.161",
+  "version": "0.2.0-alpha.164",
   "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",
@@ -156,7 +156,8 @@
     "@opentelemetry/sdk-trace-base": "^2.8.0",
     "cookie": "^1.1.1",
     "magic-string": "^0.30.21",
-    "nitro": "3.0.260610-beta"
+    "nitro": "3.0.260610-beta",
+    "srvx": "^0.11.17"
   },
   "peerDependencies": {
     "@content-collections/core": "^0.14.0 || ^0.15.0",

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

@@ -112,7 +112,11 @@ export class CloudflareKVCacheHandler implements CacheHandler {
     return { value: entry.value, stale };
   }
 
-  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void> {
+  async set(
+    key: string,
+    value: unknown,
+    opts: { ttl: number; tags: string[]; generation?: number }
+  ): Promise<void> {
     const kv = this.getKV();
     const entry: KVCacheEntry = {
       value,

package/src/adapters/nitro.ts

@@ -195,11 +195,14 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
         publicDirName: 'public',
       });
 
-      // Write the compression helper module for runtime use.
+      // Write runtime helper modules used by the preview server.
       // See design/25-production-deployments.md — self-hosted deployments
       // need application-level compression (Cloudflare handles it at the edge).
       await writeFile(join(outDir, '_compress.mjs'), await generateCompressModule());
 
+      // Web→Node response bridge with backpressure. See TIM-1154.
+      await writeFile(join(outDir, '_send-response.mjs'), generateSendResponseModule());
+
       // Prepend the manifest assignment directly into the RSC entry so
       // globalThis.__TIMBER_BUILD_MANIFEST__ is set before any module reads it.
       // This must be top-level code, not an import, because rollup tree-shakes
@@ -378,6 +381,9 @@ const { default: handler, runWithEarlyHintsSender } = await import('${rscEntry}'
 // Import compression helper for self-hosted response compression.
 const { compressResponse } = await import('./_compress.mjs');
 
+// Web→Node response bridge with backpressure (TIM-1154).
+const { sendNodeResponse } = await import('./_send-response.mjs');
+
 const MIME_TYPES = {
   '.html': 'text/html',
   '.js': 'application/javascript',
@@ -414,7 +420,7 @@ const publicDir = join(__dirname, '${publicDir}');
 const envPort = process.env.PORT ? parseInt(process.env.PORT, 10) : null;
 const portIsExplicit = envPort != null && Number.isFinite(envPort) && envPort > 0;
 const startPort = portIsExplicit ? envPort : 3000;
-const host = process.env.HOST || process.env.HOSTNAME || 'localhost';
+const host = process.env.HOST || 'localhost';
 
 // Set after listenWithBump() resolves so request handlers can build
 // absolute URLs from the actual bound port (which may differ from
@@ -501,68 +507,11 @@ const server = createServer(async (req, res) => {
     // Compress the response for self-hosted deployments.
     const webResponse = compressResponse(webRequest, rawResponse);
 
-    // Write the response back to the Node response.
-    //
-    // Set-Cookie needs special handling: Headers.entries() joins multiple
-    // Set-Cookie values with ", " into a single entry, but each cookie must
-    // be its own header per RFC 6265 §4.1. Object.fromEntries() would then
-    // collapse them into one malformed Set-Cookie header that browsers reject
-    // (or only honor partially). Use getSetCookie() to preserve individual
-    // values, and pass them as an array — Node's writeHead accepts
-    // Record<string, string | string[]> and emits one header per array entry.
-    //
-    // Without this, EVERY cookie set by the framework on Node—/Nitro deployments
-    // is silently dropped: defineCookie().setCookie() in actions, middleware
-    // cookie writes, the framework's own session cookies, all of it. See
-    // LOCAL-741.
-    const responseHeaders = {};
-    webResponse.headers.forEach((value, key) => {
-      if (key.toLowerCase() !== 'set-cookie') {
-        responseHeaders[key] = value;
-      }
-    });
-    const setCookies = webResponse.headers.getSetCookie();
-    if (setCookies.length > 0) {
-      responseHeaders['set-cookie'] = setCookies;
-    }
-    res.writeHead(webResponse.status, responseHeaders);
-
-    if (webResponse.body) {
-      const reader = webResponse.body.getReader();
-
-      // Cancel the reader when the client disconnects. This causes any
-      // pending reader.read() to reject, breaking the pump loop. Critical
-      // for SSE and other infinite streams — without this, disconnected
-      // clients leak readers.
-      let clientDisconnected = false;
-      const onClose = () => {
-        clientDisconnected = true;
-        reader.cancel('Client disconnected').catch(() => {});
-      };
-      res.on('close', onClose);
-
-      try {
-        while (true) {
-          const { done, value } = await reader.read();
-          if (done) break;
-          res.write(value);
-        }
-      } catch (err) {
-        // reader.cancel() from the close handler causes read() to reject.
-        // This is expected on client disconnect — not an error.
-        if (!clientDisconnected) {
-          throw err;
-        }
-      } finally {
-        res.off('close', onClose);
-        reader.releaseLock();
-        if (!res.writableEnded) {
-          res.end();
-        }
-      }
-    } else {
-      res.end();
-    }
+    // Write the response to Node's ServerResponse. sendNodeResponse handles
+    // status, headers (including Set-Cookie splitting via [...headers]),
+    // body streaming with backpressure, and client disconnect cleanup.
+    // See TIM-1154.
+    await sendNodeResponse(res, webResponse);
   } catch (err) {
     console.error('[timber preview] Request error:', err);
     if (!res.headersSent) {
@@ -702,6 +651,75 @@ function spawnNitroPreview(command: string, args: string[], cwd: string): Promis
   });
 }
 
+// ─── Send Response Module ───────────────────────────────────────────────────
+
+/**
+ * Generate a standalone ESM module that exports sendNodeResponse.
+ *
+ * Mirrors srvx/node's sendNodeResponse: status + headers via writeHead,
+ * body streaming with backpressure (waits for drain on write() === false),
+ * and client disconnect cleanup. Written to `_send-response.mjs` during
+ * buildOutput for use by the preview server script. See TIM-1154.
+ *
+ * @internal Exported for testing.
+ */
+export function generateSendResponseModule(): string {
+  return `// Generated by @timber-js/app — Web→Node response bridge.
+// Do not edit — this file is regenerated on each build.
+// Mirrors srvx/node's sendNodeResponse with backpressure support.
+
+export function sendNodeResponse(nodeRes, webRes) {
+  if (!webRes) {
+    nodeRes.statusCode = 500;
+    return new Promise((resolve) => nodeRes.end(resolve));
+  }
+  const rawHeaders = [...webRes.headers];
+  const writeHeaders = rawHeaders.flat();
+  if (!nodeRes.headersSent) {
+    if (nodeRes.req?.httpVersion === '2.0') {
+      nodeRes.writeHead(webRes.status, writeHeaders);
+    } else {
+      nodeRes.writeHead(webRes.status, webRes.statusText, writeHeaders);
+    }
+  }
+  if (!webRes.body) {
+    return new Promise((resolve) => nodeRes.end(resolve));
+  }
+  // Stream with backpressure: pause reading when the kernel buffer is
+  // full (write() returns false) and resume on 'drain'.
+  if (nodeRes.destroyed) {
+    webRes.body.cancel();
+    return;
+  }
+  const reader = webRes.body.getReader();
+  function streamCancel(error) {
+    reader.cancel(error).catch(() => {});
+    if (error) nodeRes.destroy(error);
+  }
+  function streamHandle({ done, value }) {
+    try {
+      if (done) {
+        nodeRes.end();
+      } else if (nodeRes.write(value)) {
+        reader.read().then(streamHandle, streamCancel);
+      } else {
+        nodeRes.once('drain', () => reader.read().then(streamHandle, streamCancel));
+      }
+    } catch (error) {
+      streamCancel(error instanceof Error ? error : undefined);
+    }
+  }
+  nodeRes.on('close', streamCancel);
+  nodeRes.on('error', streamCancel);
+  reader.read().then(streamHandle, streamCancel);
+  return reader.closed.catch(streamCancel).finally(() => {
+    nodeRes.off('close', streamCancel);
+    nodeRes.off('error', streamCancel);
+  });
+}
+`;
+}
+
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
 /**

package/src/cache/index.ts

@@ -4,7 +4,11 @@ import { estimateByteSize } from './sizeof.js';
 
 export interface CacheHandler {
   get(key: string): Promise<{ value: unknown; stale: boolean } | null>;
-  set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void>;
+  set(
+    key: string,
+    value: unknown,
+    opts: { ttl: number; tags: string[]; generation?: number }
+  ): Promise<void>;
   invalidate(opts: { key?: string; tag?: string }): Promise<void>;
 }
 
@@ -38,6 +42,7 @@ export class MemoryCacheHandler implements CacheHandler {
     string,
     { value: unknown; expiresAt: number; tags: string[]; byteSize: number }
   >();
+  private generations = new Map<string, number>();
   private maxEntries: number;
   private maxBytes: number | undefined;
   private maxEntryBytes: number | undefined;
@@ -64,7 +69,17 @@ export class MemoryCacheHandler implements CacheHandler {
     return { value: entry.value, stale };
   }
 
-  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }) {
+  async set(
+    key: string,
+    value: unknown,
+    opts: { ttl: number; tags: string[]; generation?: number }
+  ) {
+    // CAS guard: skip write if a newer generation has already been written
+    if (opts.generation !== undefined) {
+      const current = this.generations.get(key) ?? 0;
+      if (opts.generation < current) return;
+    }
+
     const byteSize = this._trackBytes ? estimateByteSize(value) : 0;
 
     // Reject entries exceeding per-entry byte limit
@@ -95,6 +110,11 @@ export class MemoryCacheHandler implements CacheHandler {
       }
     }
 
+    // Record generation only after all admission checks pass
+    if (opts.generation !== undefined) {
+      this.generations.set(key, opts.generation);
+    }
+
     this.store.set(key, {
       value,
       expiresAt: Date.now() + opts.ttl * 1000,
@@ -111,12 +131,14 @@ export class MemoryCacheHandler implements CacheHandler {
         this.currentBytes -= entry.byteSize;
         this.store.delete(opts.key);
       }
+      this.generations.delete(opts.key);
     }
     if (opts.tag) {
       for (const [key, entry] of this.store) {
         if (entry.tags.includes(opts.tag)) {
           this.currentBytes -= entry.byteSize;
           this.store.delete(key);
+          this.generations.delete(key);
         }
       }
     }
@@ -139,6 +161,7 @@ export class MemoryCacheHandler implements CacheHandler {
       const entry = this.store.get(oldest)!;
       this.currentBytes -= entry.byteSize;
       this.store.delete(oldest);
+      this.generations.delete(oldest);
     }
   }
 }

package/src/cache/redis-handler.ts

@@ -141,7 +141,11 @@ export class RedisCacheHandler implements CacheHandler {
     return { value: entry.value, stale };
   }
 
-  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void> {
+  async set(
+    key: string,
+    value: unknown,
+    opts: { ttl: number; tags: string[]; generation?: number }
+  ): Promise<void> {
     const ck = this.cacheKey(key);
     const expiresAt = Date.now() + opts.ttl * 1000;
     const payload = JSON.stringify({ value, expiresAt, tags: opts.tags });
@@ -186,13 +190,29 @@ export class RedisCacheHandler implements CacheHandler {
       const tk = this.tagKey(opts.tag);
       const keys = await this.client.smembers(tk);
 
-      // One del per key: the only multi-key shape every client accepts.
-      // ioredis takes del(...keys), node-redis takes del(key | key[]), and
-      // @upstash/redis takes del(...keys) but breaks on an array argument.
-      await Promise.all(keys.map((k) => this.client.del(this.cacheKey(k))));
+      // Re-check each member before deleting — the tag set can contain stale
+      // memberships from entries whose tags changed since they were added.
+      // Mirrors TagAwareCacheHandler's eager strategy (tag-aware-handler.ts:183-198).
+      await Promise.all(
+        keys.map(async (k) => {
+          const raw = await this.client.get(this.cacheKey(k));
+          if (raw === null) {
+            await this.client.srem(tk, k);
+            return;
+          }
+          const entry = JSON.parse(raw) as { tags?: string[] };
+          if (entry.tags?.includes(opts.tag!)) {
+            await this.client.del(this.cacheKey(k));
+          }
+          await this.client.srem(tk, k);
+        })
+      );
 
-      // Clean up the tag set itself
-      await this.client.del(tk);
+      // Clean up the now-empty tag set so it doesn't consume memory
+      const remaining = await this.client.smembers(tk);
+      if (remaining.length === 0) {
+        await this.client.del(tk);
+      }
     }
   }
 }

package/src/cache/tag-aware-handler.ts

@@ -105,7 +105,11 @@ export class TagAwareCacheHandler implements CacheHandler {
     return { value: entry.value, stale };
   }
 
-  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void> {
+  async set(
+    key: string,
+    value: unknown,
+    opts: { ttl: number; tags: string[]; generation?: number }
+  ): Promise<void> {
     const physicalTtl = Math.max(opts.ttl * 2 + 60, 120);
 
     if (this.strategy === 'native') {

package/src/cache/timber-cache.ts

@@ -13,6 +13,22 @@ import { fnv1aHash } from './fast-hash.js';
 
 let defaultSingleflight = createSingleflight();
 
+/**
+ * Per-key monotonic generation counter for CAS writes (TIM-1158).
+ *
+ * Unbounded, like the singleflight map — the key space is the same set of
+ * cache keys the handler already tracks. Pruning was removed because it
+ * desyncs from MemoryCacheHandler.generations: a pruned key restarts at 1
+ * while the handler still holds the old higher generation, causing fresh
+ * writes to be rejected as stale.
+ */
+const writeGenerations = new Map<string, number>();
+function nextGeneration(key: string): number {
+  const gen = (writeGenerations.get(key) ?? 0) + 1;
+  writeGenerations.set(key, gen);
+  return gen;
+}
+
 /**
  * Set the timeout for the module-level default singleflight.
  * Called at framework boot with renderTimeoutMs from timber.config.ts so that
@@ -164,21 +180,16 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
      * - the key/tags were invalidated after fn started (TIM-1028), or
      * - the singleflight timed out (signal aborted) — the timed-out
      *   flight's write could overwrite a newer value from a subsequent
-     *   flight (TIM-1092).
-     *
-     * Residual race: if fn() completes within the timeout but
-     * handler.set() is slow enough that the timeout fires during the
-     * set, the write lands with stale data. This window is narrow
-     * (requires set latency to straddle the timeout boundary) and
-     * self-healing (next cache miss triggers a fresh write). Fully
-     * closing it requires CAS/versioned writes on CacheHandler —
-     * tracked in TIM-1158.
+     *   flight (TIM-1092), or
+     * - the handler rejects the write because a newer generation has
+     *   already been stored (TIM-1158 CAS guard).
      */
     const executeAndStore = async (signal: AbortSignal): Promise<Awaited<ReturnType<Fn>>> => {
       const startEpoch = currentInvalidationEpoch();
+      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 });
+        await getHandler().set(key, result, { ttl: opts.ttl, tags, generation });
       }
       return result;
     };

package/src/client/segment-cache.ts

@@ -128,14 +128,13 @@ export function buildSegmentTree(segments: SegmentInfo[]): SegmentNode | undefin
   // Need at least a root segment to build a tree
   if (segments.length === 0) return undefined;
 
-  // Exclude the leaf (page) — pages always re-render on navigation.
-  // Only layouts are cached in the segment tree.
-  const layouts = segments.length > 1 ? segments.slice(0, -1) : segments;
-
+  // All entries are layout segments — the server filters out layoutless
+  // segments (including the page leaf) in buildSegmentInfo. Cache every
+  // entry; pages are never sent.
   let root: SegmentNode | undefined;
   let parent: SegmentNode | undefined;
 
-  for (const info of layouts) {
+  for (const info of segments) {
     const id = info.segmentId ?? info.path;
     const node: SegmentNode = {
       segment: id,