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

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.163",
+  "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/slot-context.ts

@@ -0,0 +1,48 @@
+/**
+ * SlotContext — delivers live slot content to SlotOutlet holes inside
+ * cached component shells (TIM-1173).
+ *
+ * A `cache.component(Fn, { slots: [...] })` shell is captured with a
+ * stable <SlotOutlet slot={name} /> client reference in place of each
+ * declared slot prop. At request time the revived shell is wrapped in a
+ * SlotsProvider carrying the live slot values; each outlet reads its
+ * value from this context by name.
+ *
+ * The value is a per-instance record — the NEAREST provider wins, so two
+ * instances of the same cached component on one page each resolve their
+ * own children, and a slot component nested inside another slot
+ * component's children reads its own provider, not the outer one.
+ *
+ * Generalizes the ChildSegmentContext pattern (TIM-1181) from a single
+ * implicit `children` hole on layouts to explicitly declared, named slot
+ * props on any cached component.
+ *
+ * SINGLETON GUARANTEE: globalThis + Symbol.for — the RSC client bundler
+ * can duplicate this module across chunks; globalThis guarantees a single
+ * context instance. Same pattern as ChildSegmentContext.
+ *
+ * See design/45-cache-lifetimes.md §Slot Components.
+ */
+
+'use client';
+
+import React, { type ReactNode } from 'react';
+
+export type SlotValues = Record<string, ReactNode>;
+
+const CTX_KEY = Symbol.for('__timber_slot_ctx');
+
+function getOrCreateContext(): React.Context<SlotValues | null> {
+  const existing = (globalThis as Record<symbol, unknown>)[CTX_KEY] as
+    | React.Context<SlotValues | null>
+    | undefined;
+  if (existing !== undefined) return existing;
+  if (typeof React.createContext === 'function') {
+    const ctx = React.createContext<SlotValues | null>(null);
+    (globalThis as Record<symbol, unknown>)[CTX_KEY] = ctx;
+    return ctx;
+  }
+  return undefined as unknown as React.Context<SlotValues | null>;
+}
+
+export const SlotContext = getOrCreateContext();

package/src/client/slot-outlet.tsx

@@ -0,0 +1,22 @@
+/**
+ * SlotOutlet — the hole in a cached component shell (TIM-1173).
+ *
+ * At capture time the prebuilt runtime renders the wrapped component with
+ * <SlotOutlet slot={name} /> in place of each declared slot prop. Being a
+ * client component, it serializes into the flight payload as a stable,
+ * deterministic client reference — the same bytes regardless of what live
+ * content will fill the hole. At request time the revived shell sits under
+ * a SlotsProvider and each outlet reads its live value from SlotContext.
+ *
+ * See design/45-cache-lifetimes.md §Slot Components.
+ */
+
+'use client';
+
+import { useContext } from 'react';
+import { SlotContext } from './slot-context.js';
+
+export function SlotOutlet({ slot }: { slot: string }) {
+  const values = useContext(SlotContext);
+  return values ? (values[slot] ?? null) : null;
+}

package/src/client/slot-provider.tsx

@@ -0,0 +1,25 @@
+/**
+ * SlotsProvider — wraps a revived cached shell to supply live slot content
+ * to the SlotOutlet holes inside it (TIM-1173).
+ *
+ * Tree structure per cached-component instance:
+ *   SlotsProvider(values={children: <Live />})
+ *     └── revived shell
+ *          └── SlotOutlet(slot="children") → reads context → <Live />
+ *
+ * See design/45-cache-lifetimes.md §Slot Components.
+ */
+
+'use client';
+
+import { createElement, type ReactNode } from 'react';
+import { SlotContext, type SlotValues } from './slot-context.js';
+
+interface SlotsProviderProps {
+  values: SlotValues;
+  children: ReactNode;
+}
+
+export function SlotsProvider({ values, children }: SlotsProviderProps) {
+  return createElement(SlotContext.Provider, { value: values }, children);
+}

package/src/config-types.ts

@@ -137,7 +137,8 @@ export interface TimberUserConfig {
    * the connection is closed. Protects against hung fetches and Suspense
    * components that never resolve.
    *
-   * Set to 0 to disable (not recommended in production).
+   * Setting 0 uses a 120-second safety ceiling rather than disabling
+   * the timeout entirely.
    * Default: 30000 (30 seconds).
    *
    * See design/02-rendering-pipeline.md §"Streaming Constraints".

package/src/dev-tools/logs.ts

@@ -228,6 +228,13 @@ function patchConsole(server: ViteDevServer, projectRoot: string): () => void {
       // Server runtime logs (render errors, action errors, etc.) are preserved.
       if (isFrameworkInternalCaller()) return;
 
+      // Break the server→browser→server console forwarding loop. Vite's
+      // forwardConsole re-logs browser console output on the server via
+      // `logger.error("[console.error] ...")`. Our patch would send it back
+      // to the browser, Vite's client patch forwards it again → exponential
+      // log spam. Detect the `[console.<level>]` prefix Vite adds and skip.
+      if (typeof args[0] === 'string' && args[0].includes('[console.')) return;
+
       // Serialize and forward to browser
       try {
         const payload: ServerLogPayload = {

package/src/plugin-context.ts

@@ -11,6 +11,7 @@
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { createRequire } from 'node:module';
+import { parseAst } from 'vite';
 import type { RouteTree } from './routing/types';
 import type { BuildManifest } from './server/build-manifest';
 import type { CaptureSummary } from './server/prebuilt-builder';
@@ -18,6 +19,7 @@ import type { StartupTimer } from './utils/startup-timer';
 import { createStartupTimer } from './utils/startup-timer';
 import type { TimberUserConfig, ClientJavascriptConfig } from './config-types.js';
 import type { HoldingServer } from './dev-tools/holding-server.js';
+import type { ProgramNode } from './plugins/callsite-ast.js';
 
 // Re-export for sub-plugin convenience — they import from plugin-context.ts
 export type { TimberUserConfig, ClientJavascriptConfig } from './config-types.js';
@@ -147,6 +149,57 @@ export interface PluginContext {
   prebuiltLazyChunks?: Map<string, string>;
   /** Post-build prebuilt capture summary (populated by timber-prebuilt, consumed by build-report). */
   captureSummary?: CaptureSummary;
+  /**
+   * Content-keyed AST parse memo shared across cache/prebuilt/prerender-sugar
+   * transforms. Collapses both cross-plugin and cross-environment duplicate
+   * parses: identical code hits, rewritten code misses (correct because Vite
+   * transforms chain — a rewrite produces different code). Bounded LRU (32
+   * entries) so it doesn't hold programs for the whole build.
+   *
+   * Consumers MUST treat the returned ProgramNode as read-only — they collect
+   * ranges and rewrite CODE via MagicString; the AST itself is never mutated.
+   */
+  parseCached?: ParseMemo;
+}
+
+// ── AST parse memo ───────────────────────────────────────────────────────
+
+const PARSE_MEMO_CAPACITY = 32;
+
+/**
+ * Content-keyed LRU memo for `parseAst`. Transforms for the same module run
+ * back-to-back across plugins and environments, so a tiny window captures the
+ * wins. The returned ProgramNode is shared — callers MUST NOT mutate it.
+ */
+export class ParseMemo {
+  private cache = new Map<string, ProgramNode>();
+
+  /**
+   * Parse code, returning a cached ProgramNode if the same code was parsed
+   * before. The returned AST MUST NOT be mutated — it may be shared across
+   * multiple consumers.
+   */
+  parse(code: string): ProgramNode {
+    const existing = this.cache.get(code);
+    if (existing) {
+      // LRU refresh: move to end
+      this.cache.delete(code);
+      this.cache.set(code, existing);
+      return existing;
+    }
+    const program = parseAst(code, { lang: 'tsx' }) as unknown as ProgramNode;
+    if (this.cache.size >= PARSE_MEMO_CAPACITY) {
+      // Evict oldest (first inserted)
+      const firstKey = this.cache.keys().next().value!;
+      this.cache.delete(firstKey);
+    }
+    this.cache.set(code, program);
+    return program;
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
 }
 
 // ── App directory resolution ──────────────────────────────────────────────
@@ -197,6 +250,7 @@ export function createPluginContext(config?: TimberUserConfig, root?: string): P
     timer: createStartupTimer(),
     holdingServer: null,
     buildDir: resolveBuildDir(projectRoot, resolvedConfig.buildDir),
+    parseCached: new ParseMemo(),
   };
 }