@timber-js/app 0.2.0-alpha.157 → 0.2.0-alpha.159

package/docs/learn/14-deploying.mdx

@@ -196,6 +196,58 @@ export default {
 
 Pre-renders every route to HTML at build time. Add `clientJavascript: false` for zero-JavaScript output. Deploy to any static file host — S3, CloudFront, Cloudflare Pages, GitHub Pages, Netlify, or any HTTP server.
 
+## CDN Integration
+
+timber.js provides typed helpers for CDN caching headers and tag-based purging. CDN caching is always developer-elected — the framework never sets cache headers automatically.
+
+### Header Helpers
+
+```ts title="app/proxy.ts"
+import { cacheControl, surrogateKey } from '@timber-js/app/cdn';
+
+export default async function proxy(ctx) {
+  if (ctx.pathname.startsWith('/products/')) {
+    ctx.headers.set('Cache-Control', cacheControl({
+      public: true,
+      maxAge: 600,
+      staleWhileRevalidate: 60,
+    }));
+    ctx.headers.set('Surrogate-Key', surrogateKey(['products']));
+  }
+}
+```
+
+### Purge on `revalidateTag`
+
+Configure a CDN purge handler so `revalidateTag()` also purges the CDN:
+
+```ts title="timber.config.ts"
+import { CloudflarePurge } from '@timber-js/app/cdn/cloudflare';
+
+export default {
+  cdnPurge: new CloudflarePurge({
+    zoneId: process.env.CF_ZONE_ID!,
+    apiToken: process.env.CF_API_TOKEN!,
+  }),
+};
+```
+
+Fastly:
+
+```ts title="timber.config.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,
+  }),
+};
+```
+
+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.
+
 ## Cache Handler Selection
 
 | Deployment                  | Recommended Handler  | Why                                           |

package/docs/more/06-instrumentation.mdx

@@ -115,7 +115,7 @@ const sid = getSpanId(); // "1234567890abcdef" or undefined
 
 ### `withSpan(name, attributes, fn)`
 
-Run a function within an OTEL span. If OTEL is not available, the function runs directly with zero overhead.
+Run a function within a span. Emits an OTEL span when an SDK is active, and a native platform span on Cloudflare (see [Cloudflare Native Traces](#cloudflare-native-traces)). With neither, the function runs directly with zero overhead.
 
 ```ts
 import { withSpan } from '@timber-js/app/server';
@@ -144,6 +144,32 @@ import { addSpanEvent } from '@timber-js/app/server';
 await addSpanEvent('cache.hit', { key: 'user:123' });
 ```
 
+## Cloudflare Native Traces
+
+When you deploy with the Cloudflare adapter, timber's pipeline spans (`timber.proxy`, `timber.middleware`, `timber.access`, `timber.render`, `timber.action`, …) appear **natively in the Cloudflare Observability dashboard** — no OTEL SDK required. They nest alongside Cloudflare's auto-instrumented D1, KV, and `fetch` spans with the same attributes timber emits over OTEL (`http.request.method`, `url.path`, `http.route`, `http.response.status_code`, `timber.result`, …).
+
+This works out of the box:
+
+- The generated `_worker.js` registers timber's spans with the Workers custom spans API (`tracing.enterSpan()` from `cloudflare:workers`).
+- The generated `wrangler.jsonc` enables the trace destination (`observability.traces.enabled`).
+
+To turn native traces off, use the `wrangler` escape hatch:
+
+```ts
+// timber.config.ts
+import { cloudflare } from '@timber-js/app/adapters/cloudflare';
+
+export default {
+  adapter: cloudflare({
+    wrangler: { observability: { traces: { enabled: false } } },
+  }),
+};
+```
+
+Native emission is additive — if you also initialize an OTEL SDK in `register()`, spans are emitted on both channels, so external collectors (Honeycomb, Jaeger, Datadog) keep working. `timber.cache` HIT/MISS **span events** are OTEL-only; the Workers span API has no event equivalent.
+
+On runtimes without the custom spans API (older compatibility dates or an outdated local `wrangler`), the worker silently falls back to OTEL-only emission.
+
 ## Server-Timing
 
 timber.js can emit `Server-Timing` headers for browser DevTools performance inspection.

package/docs/more/07-security.mdx

@@ -60,6 +60,8 @@ node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
 
 ## Redirect Safety
 
+Open redirect vulnerabilities let an attacker craft a URL on your domain that redirects users to a malicious site (e.g., `/login?next=https://evil.com`). timber prevents this structurally — `redirect()` cannot produce an external redirect.
+
 ### `redirect()` is relative-only
 
 The `redirect()` function only accepts relative paths. Absolute URLs and protocol-relative URLs are rejected:
@@ -72,11 +74,11 @@ redirect('https://evil.com'); // ❌ throws — absolute URL
 redirect('//evil.com'); // ❌ throws — protocol-relative
 ```
 
-This prevents open redirect vulnerabilities where an attacker tricks your app into redirecting users to a malicious site.
+This applies everywhere — middleware, access checks, server actions, and server components. There is no code path where `redirect()` can send users off-site.
 
 ### `redirectExternal()` with allow-list
 
-When you need to redirect to an external URL, use `redirectExternal()` with an explicit origin allow-list. Only `http:` and `https:` schemes are permitted:
+When you legitimately need to redirect to an external URL (e.g., an OAuth provider), use `redirectExternal()` with an explicit origin allow-list. Only `http:` and `https:` schemes are permitted:
 
 ```ts
 import { redirectExternal } from '@timber-js/app/server';
@@ -89,6 +91,10 @@ redirectExternal('https://docs.example.com/guide', ['https://docs.example.com'],
 
 If the target origin isn't in the allow-list, the scheme isn't http(s), or the URL is invalid, the call throws. This gives you external redirects without the open redirect risk.
 
+<Callout variant="tip" title="vs. Next.js">
+  Next.js `redirect()` accepts absolute URLs by default. In timber, external redirects require an explicit allow-list — open redirect bugs are structurally impossible.
+</Callout>
+
 ## Header Immutability
 
 Request headers are immutable after the request enters the pipeline:

package/docs/more/08-developer-experience.mdx

@@ -0,0 +1,134 @@
+---
+title: 'Developer Experience'
+description: 'Dev logging, hydration diffs, Server-Timing headers, build reports, and more.'
+slug: 'developer-experience'
+---
+
+# Developer Experience
+
+timber.js includes a suite of development tools that surface what your app is doing — where time is spent, what's cached, where errors come from — without reaching for external profiling tools.
+
+## Dev Logging
+
+Every request in development emits a structured tree to `stderr` showing the full execution pipeline with timing:
+
+```
+POST /dashboard/projects/123  trace_id: 4bf92f3577b34da6a3ce929d0e0e4736
+├─ [proxy]   proxy.ts                               0ms →  2ms
+├─ [rsc]     middleware.ts                           2ms →  4ms
+│  ├── fired: requireUser()                    (timber.cache prefetch)
+│  ├── fired: getProject("123")               (timber.cache prefetch)
+│  └── fired: getTaskCounts("123")            (timber.cache prefetch)
+├─ [rsc]     render                                 4ms
+│  ├─ [rsc]  AccessGate (authenticated)             4ms →  5ms
+│  │  └── requireUser()                        timber.cache HIT  <1ms
+│  ├─ [rsc]  ProjectPage                            8ms → 12ms
+│  │  └── getTaskCounts("123")                 timber.cache HIT  <1ms
+│  └── onShellReady                                12ms
+├─ [ssr]     hydration render                      13ms → 18ms
+└─ ✓ 200 OK                              total    18ms
+```
+
+The tree mirrors the execution structure. `[rsc]`/`[ssr]`/`[client]` labels show which Vite environment each phase runs in. Cache hits and misses are annotated inline.
+
+### Fetch Instrumentation
+
+`fetch()` calls from server components appear as children of the component that made them:
+
+```
+├─ [rsc]  page /                              6ms → 101ms
+│     ├─ fetch GET https://api.example.com/products  12ms → 89ms (77ms)
+│     └─ fetch GET https://api.example.com/user      12ms → 45ms (33ms) [cdn: HIT]
+```
+
+Start times reveal whether fetches ran concurrently or sequentially. Cache status from `X-Cache` or `CF-Cache-Status` headers is surfaced automatically. Fetch instrumentation is dev-only — `globalThis.fetch` is not patched in production.
+
+### Log Modes
+
+Control the verbosity with `TIMBER_DEV_LOG`:
+
+| Mode      | Output                                                     |
+| --------- | ---------------------------------------------------------- |
+| `tree`    | Full indented tree per request (default)                   |
+| `verbose` | Detailed tree showing every component render               |
+| `summary` | One line per request: `POST /path → 200 OK  18ms`         |
+| `json`    | Chronological NDJSON of all spans with full attributes     |
+
+Suppress all dev logging with `TIMBER_DEV_QUIET=1`.
+
+### Slow Phase Warnings
+
+Phases that exceed a configurable threshold are highlighted in the tree output. The default is 200ms:
+
+```ts title="timber.config.ts"
+export default {
+  dev: {
+    slowPhaseMs: 200,
+  },
+};
+```
+
+This surfaces performance bottlenecks during development without requiring explicit profiling.
+
+## Server-Timing Header
+
+timber.js emits a `Server-Timing` HTTP header for every response. The level of detail is configurable:
+
+| Value        | Output                                                   | Default in  |
+| ------------ | -------------------------------------------------------- | ----------- |
+| `'detailed'` | Per-phase breakdown: proxy, middleware, render, SSR       | Development |
+| `'total'`    | Single `total;dur=N` entry                               | Production  |
+| `false`      | No header                                                | —           |
+
+```ts title="timber.config.ts"
+export default {
+  serverTiming: 'detailed',
+};
+```
+
+In production, you can opt into `'detailed'` for APM integration — browser DevTools and monitoring tools parse `Server-Timing` automatically.
+
+## Hydration Mismatch Diff
+
+When React 19 detects a hydration mismatch, timber parses the diff and renders it with color-coded lines:
+
+- Green (`+`) lines show the client-side markup
+- Red (`-`) lines show the server-side markup
+
+This replaces Vite's plain-text rendering of hydration errors, making mismatches easy to spot and fix. Multiple hydration errors accumulate in the same overlay.
+
+## Error Overlay
+
+Errors during development are shown in a browser overlay with:
+
+- **Component stacks** — the React component hierarchy leading to the error
+- **Phase labels** — whether the error occurred in middleware, access check, RSC render, SSR, or a client component
+- **Source-mapped stack traces** — pointing to your original source files
+
+Client-side errors are forwarded to the overlay via Vite's HMR channel, so they get the same treatment as server errors.
+
+## Compiling Indicator
+
+A small "Compiling…" indicator appears in the bottom-left corner during HMR updates. It has a 200ms debounce — fast updates never show it. It fades out when the update completes.
+
+## Build Report
+
+After `timber build`, a route table shows every route with its bundle size, route type, and first-load JS:
+
+| Symbol | Meaning        |
+| ------ | -------------- |
+| ○      | Static page    |
+| λ      | Dynamic (SSR)  |
+| ƒ      | API route      |
+
+This helps identify large bundles and verify route classification.
+
+## HTTPS / HTTP-2 Dev Server
+
+timber supports `server.https` in your Vite config for local HTTPS development. The request scheme is derived from the TLS socket (not hardcoded), so CSRF protection works correctly under HTTPS. HTTP/2 pseudo-headers are handled automatically.
+
+## What's Next
+
+- [Instrumentation](/docs/instrumentation) — production tracing with OpenTelemetry
+- [Configuration](/docs/configuration) — all config options
+- [Streaming](/docs/streaming) — Suspense placement and `deferSuspenseFor`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.157",
+  "version": "0.2.0-alpha.159",
   "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",
@@ -68,6 +68,34 @@
       "types": "./dist/cache/index.d.ts",
       "import": "./dist/cache/index.js"
     },
+    "./cache/stores/memory": {
+      "types": "./dist/cache/stores/memory.d.ts",
+      "import": "./dist/cache/stores/memory.js"
+    },
+    "./cache/stores/redis": {
+      "types": "./dist/cache/stores/redis.d.ts",
+      "import": "./dist/cache/stores/redis.js"
+    },
+    "./cache/stores/cloudflare-kv": {
+      "types": "./dist/cache/stores/cloudflare-kv.d.ts",
+      "import": "./dist/cache/stores/cloudflare-kv.js"
+    },
+    "./cache/stores/vercel": {
+      "types": "./dist/cache/stores/vercel.d.ts",
+      "import": "./dist/cache/stores/vercel.js"
+    },
+    "./cdn": {
+      "types": "./dist/cdn/index.d.ts",
+      "import": "./dist/cdn/index.js"
+    },
+    "./cdn/cloudflare": {
+      "types": "./dist/cdn/cloudflare-purge.d.ts",
+      "import": "./dist/cdn/cloudflare-purge.js"
+    },
+    "./cdn/fastly": {
+      "types": "./dist/cdn/fastly-purge.d.ts",
+      "import": "./dist/cdn/fastly-purge.js"
+    },
     "./codec": {
       "types": "./dist/codec.d.ts",
       "import": "./dist/codec.js"
@@ -121,6 +149,7 @@
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/context-async-hooks": "^2.8.0",
     "@opentelemetry/sdk-trace-base": "^2.8.0",
+    "cookie": "^1.1.1",
     "magic-string": "^0.30.21",
     "nitro": "3.0.260610-beta"
   },
@@ -134,7 +163,7 @@
     "nuqs": "^2.0.0",
     "react": "19.2.7",
     "react-dom": "19.2.7",
-    "vite": "^8.0.16",
+    "vite": "^8.1.0",
     "wrangler": "^4.0.0",
     "zod": "^3.22.0 || ^4.0.0"
   },

package/src/adapters/build-output-helper.ts

@@ -89,6 +89,16 @@ export async function runSharedBuildSteps(opts: BuildOutputBaseOptions): Promise
     }
   );
 
+  // 4b. Copy prebuilt/ flight payloads if present (cache.component artifacts).
+  // These are produced by the post-build capture pass (design/44) and read
+  // at request time via the adapter's PrebuiltPayloadSource.
+  await cp(join(buildDir, 'prebuilt'), join(outDir, 'prebuilt'), { recursive: true }).catch(
+    (e: NodeJS.ErrnoException) => {
+      // No prebuilt dir when the app has no cache.component calls
+      if (e.code !== 'ENOENT') throw e;
+    }
+  );
+
   // 5. Write manifest-init module if present.
   if (config.manifestInit) {
     await writeFile(join(outDir, '_timber-manifest-init.js'), config.manifestInit);

package/src/adapters/cloudflare.ts

@@ -3,7 +3,7 @@
 // Primary deployment target. Generates a Workers-compatible entry point
 // and wrangler.jsonc configuration. See design/11-platform.md §"Cloudflare Workers".
 
-import { writeFile } from 'node:fs/promises';
+import { writeFile, readFile, cp, rm, readdir } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
 import { join, relative } from 'node:path';
 import { AsyncLocalStorage } from 'node:async_hooks';
@@ -228,6 +228,16 @@ export function cloudflare(options: CloudflareAdapterOptions = {}): TimberPlatfo
     async buildOutput(config: TimberConfig, buildDir: string) {
       const outDir = join(buildDir, 'cloudflare');
 
+      // Clean stale prebuilt artifacts BEFORE the shared copy step.
+      // The shared step uses cp (merge, not replace), so old .flight files
+      // from removed/renamed components would persist and get picked up by
+      // find_additional_modules. Also clean static/prebuilt/ from pre-TIM-1162
+      // builds where prebuilt was copied into static assets.
+      await rm(join(outDir, 'prebuilt'), { recursive: true, force: true }).catch(() => {});
+      await rm(join(outDir, 'static', 'prebuilt'), { recursive: true, force: true }).catch(
+        () => {}
+      );
+
       // Steps 1–5: shared across all adapters (mkdir, copy client/rsc/ssr,
       // write _headers, write manifest-init).
       await runSharedBuildSteps({
@@ -256,13 +266,25 @@ export function cloudflare(options: CloudflareAdapterOptions = {}): TimberPlatfo
             emptyOutDir: false,
             minify: false,
             rollupOptions: {
-              external: [/^node:/],
+              external: [/^node:/, /^cloudflare:/],
             },
           },
         });
         hasWorkerHandlers = true;
       }
 
+      // Embed prebuilt flight payloads directly into the worker module
+      // (TIM-1162). Previously, prebuilt/ was copied into static assets and
+      // read via env.ASSETS.fetch() — but that made .flight files and
+      // manifest.json publicly fetchable, bypassing middleware and access
+      // gates. Now payloads are imported as native wrangler Data/Text modules
+      // from outDir/prebuilt/ (outside static/), keeping them server-side only.
+      const prebuiltData = await readPrebuiltData(buildDir);
+      await writeFile(
+        join(outDir, '_timber-prebuilt-source.js'),
+        generatePrebuiltSourceModule(prebuiltData)
+      );
+
       // Generate the Workers entry point
       const hasManifestInit = !!config.manifestInit;
       const workerEntry = generateWorkerEntry(outDir, outDir, hasManifestInit, hasWorkerHandlers);
@@ -320,6 +342,10 @@ export function generateWorkerEntry(
 // Do not edit — this file is regenerated on each build.
 
 import { AsyncLocalStorage } from 'node:async_hooks'
+// Side-effect import: sets globalThis.__TIMBER_PREBUILT_SOURCE__ before the
+// RSC handler evaluates. Must be a static import (not body code) so ESM
+// evaluation order guarantees it runs before ./rsc/index.js.
+import './_timber-prebuilt-source.js'
 ${manifestImport}import handler, { runWithWaitUntil } from '${rscEntryRelative}'
 ${handlersImport}
 // Set TIMBER_RUNTIME for instrumentation.ts conditional SDK initialization.
@@ -336,8 +362,35 @@ if (!bindingsAls) {
   globalThis[ALS_KEY] = bindingsAls
 }
 
+// Register timber's platform tracer so pipeline phase spans (timber.proxy,
+// timber.middleware, timber.render, timber.access, timber.action, …) appear
+// as native Cloudflare spans in the Observability dashboard, nested under
+// the auto-instrumented fetch/KV/D1 spans. Requires observability.traces
+// enabled in wrangler.jsonc (generated by default).
+//
+// Lazily imported and guarded: runtimes without the custom spans API
+// (older compatibility dates, older local workerd) fall back to OTEL-only
+// emission. withSpan() in the framework composes both channels.
+const TRACER_KEY = Symbol.for('timber:platform-tracer')
+let tracerInit
+function initPlatformTracer() {
+  tracerInit ??= import('cloudflare:workers')
+    .then(({ tracing }) => {
+      if (tracing && typeof tracing.enterSpan === 'function') {
+        globalThis[TRACER_KEY] ??= {
+          enterSpan: (name, fn) => tracing.enterSpan(name, fn),
+        }
+      }
+    })
+    .catch(() => {})
+  return tracerInit
+}
+
 export default {
 ${handlersSpread}  async fetch(request, env, ctx) {
+    // One-time on first request; resolved-promise await thereafter.
+    await initPlatformTracer()
+
     // Edge-cache GET/HEAD responses via the Cache API. RSC navigation
     // requests (Accept: text/x-component) are excluded — they vary by
     // X-Timber-State-Tree which the cache key doesn't capture.
@@ -379,6 +432,99 @@ ${handlersSpread}  async fetch(request, env, ctx) {
 `;
 }
 
+/** Build-time prebuilt file list read from `.timber/dist/prebuilt/`. */
+export interface PrebuiltModuleData {
+  /** Payload file paths relative to prebuilt/ (e.g. "comp_abc/deadbeef.flight"). */
+  payloadFiles: string[];
+}
+
+/**
+ * Discover prebuilt flight payload files from the build directory.
+ * Returns null when no prebuilt artifacts exist (no cache.component usage).
+ *
+ * @internal Exported for testing.
+ */
+export async function readPrebuiltData(buildDir: string): Promise<PrebuiltModuleData | null> {
+  const prebuiltDir = join(buildDir, 'prebuilt');
+  try {
+    await readFile(join(prebuiltDir, 'manifest.json'));
+  } catch {
+    return null;
+  }
+  const payloadFiles: string[] = [];
+  try {
+    const componentDirs = await readdir(prebuiltDir, { withFileTypes: true });
+    for (const dir of componentDirs) {
+      if (!dir.isDirectory()) continue;
+      const files = await readdir(join(prebuiltDir, dir.name));
+      for (const file of files) {
+        if (file.endsWith('.flight')) {
+          payloadFiles.push(`${dir.name}/${file}`);
+        }
+      }
+    }
+  } catch {
+    // No subdirectories — manifest exists but no payloads
+  }
+  return { payloadFiles };
+}
+
+/**
+ * Generate the prebuilt payload source module for Cloudflare Workers.
+ *
+ * Imports prebuilt flight payloads as native wrangler Data/Text modules
+ * from the worker's module graph (NOT from static assets — TIM-1162).
+ * Files live at `outDir/prebuilt/` which is outside `static/` and thus
+ * not publicly fetchable. Wrangler discovers them via
+ * `find_additional_modules: true` with Data/Text rules.
+ *
+ * This is a separate ESM module so it evaluates before the RSC handler —
+ * static imports are hoisted, guaranteeing `globalThis.__TIMBER_PREBUILT_SOURCE__`
+ * is set before `createRequestHandler()` reads it.
+ *
+ * @internal Exported for testing.
+ */
+export function generatePrebuiltSourceModule(data: PrebuiltModuleData | null): string {
+  if (!data) {
+    return `// Generated by @timber-js/app/adapters/cloudflare
+// No prebuilt artifacts — all cache.component wrappers render dynamically.
+globalThis.__TIMBER_PREBUILT_SOURCE__ = {
+  async loadManifest() { return null },
+  async readPayload() { return null },
+}
+`;
+  }
+
+  const imports: string[] = [];
+  const entries: string[] = [];
+
+  imports.push(`import _manifestText from './prebuilt/manifest.json'`);
+
+  for (let i = 0; i < data.payloadFiles.length; i++) {
+    const file = data.payloadFiles[i];
+    imports.push(`import _p${i} from './prebuilt/${file}'`);
+    entries.push(`  ${JSON.stringify(file)}: new Uint8Array(_p${i})`);
+  }
+
+  return `// Generated by @timber-js/app/adapters/cloudflare
+// Prebuilt payload source — imports cache.component flight payloads as
+// native wrangler modules from the worker bundle (TIM-1162). Files live
+// at outDir/prebuilt/, outside static/, so they are not publicly fetchable.
+${imports.join('\n')}
+
+const _manifest = JSON.parse(_manifestText)
+
+const _payloads = {
+${entries.join(',\n')}
+}
+
+globalThis.__TIMBER_PREBUILT_SOURCE__ = {
+  async loadManifest() { return _manifest },
+  async readPayload(file) { return _payloads[file] ?? null },
+}
+`;
+}
+
 /** Wrangler binding sections generated from `CloudflareBindings`. */
 export interface WranglerBindingsConfig {
   kv_namespaces?: Array<{ binding: string; id: string }>;
@@ -517,6 +663,11 @@ export function generateWranglerConfig(
 
   const flags = options.compatibilityFlags ?? ['nodejs_compat'];
 
+  const PREBUILT_MODULE_RULES = [
+    { type: 'Text' as const, globs: ['prebuilt/**/*.json'] },
+    { type: 'Data' as const, globs: ['prebuilt/**/*.flight'] },
+  ];
+
   const base: Record<string, unknown> = {
     name: 'timber-app',
     main: '_worker.js',
@@ -526,9 +677,18 @@ export function generateWranglerConfig(
     // esbuild pass to avoid issues with top-level await and module format.
     no_bundle: true,
     find_additional_modules: true,
-    rules: [{ type: 'ESModule', globs: ['**/*.js'] }],
+    rules: [{ type: 'ESModule', globs: ['**/*.js'] }, ...PREBUILT_MODULE_RULES],
     assets: {
       directory: './static',
+      binding: 'ASSETS',
+    },
+    // Native trace destination — required for timber's pipeline spans
+    // (emitted via tracing.enterSpan in the generated _worker.js) to appear
+    // in the Cloudflare Observability dashboard. Gates traces only; does
+    // not enable Workers Logs. Override via the `wrangler` escape hatch:
+    // wrangler: { observability: { traces: { enabled: false } } }.
+    observability: {
+      traces: { enabled: true },
     },
   };
 
@@ -542,7 +702,21 @@ export function generateWranglerConfig(
   // durable_objects.bindings. Deep merge preserves generated keys while
   // letting wrangler override on actual key-level conflicts.
   if (options.wrangler) {
-    return shallowDeepMerge(merged, options.wrangler);
+    const result = shallowDeepMerge(merged, options.wrangler);
+    // Ensure required prebuilt module rules survive a user `rules` override.
+    // Without this, `wrangler: { rules: [...] }` replaces the entire array
+    // and drops the Text/Data rules that _timber-prebuilt-source.js needs.
+    if (options.wrangler.rules) {
+      const userRules = result.rules as Array<Record<string, unknown>>;
+      for (const required of PREBUILT_MODULE_RULES) {
+        const exists = userRules.some(
+          (r) =>
+            r.type === required.type && JSON.stringify(r.globs) === JSON.stringify(required.globs)
+        );
+        if (!exists) userRules.push(required);
+      }
+    }
+    return result;
   }
 
   return merged;

package/src/cache/cache-api.ts

@@ -1,7 +1,10 @@
 import type { CacheOptions } from './index';
+import type { PrebuiltComponentOptions } from '../server/prebuilt-runtime';
 import { createCache } from './timber-cache';
 import { getCacheHandler } from './handler-store';
 import { recordInvalidation } from './invalidation-epoch';
+import { writeTombstonesForTag } from '../server/prebuilt/overlay.js';
+import { getCdnPurgeHandler } from '../cdn/purge-store.js';
 
 /**
  * Public caching API: `cache(fn, opts)`.
@@ -44,4 +47,61 @@ cache.invalidate = async function invalidate(opts: { key?: string; tag?: string
   // post-resolve set instead of resurrecting the invalidated value (TIM-1028).
   recordInvalidation(opts);
   await getCacheHandler().invalidate(opts);
+  // Write tombstones for build-seed entries carrying the tag (design/45
+  // §ISR mechanics). Runs AFTER handler.invalidate so the tombstone
+  // overwrites the cleared overlay slot. This covers ALL invalidation
+  // paths — actions, webhooks, route handlers — not just executeAction.
+  if (opts.tag) {
+    await writeTombstonesForTag(opts.tag);
+  }
+  // Trigger CDN purge if a handler is configured (design/25 §Layer 2).
+  // Purge is best-effort: a CDN API failure or timeout must not block
+  // cache invalidation. 10s ceiling prevents a hung CDN API from stalling
+  // the entire revalidateTag/action flow.
+  if (opts.tag) {
+    const purgeHandler = getCdnPurgeHandler();
+    if (purgeHandler) {
+      try {
+        await Promise.race([
+          purgeHandler.purgeTags([opts.tag]),
+          new Promise<void>((_, reject) =>
+            setTimeout(() => reject(new Error('CDN purge timed out (10s)')), 10_000)
+          ),
+        ]);
+      } catch (err) {
+        console.error('[timber] CDN purge failed for tag:', err);
+      }
+    }
+  }
+};
+
+const componentFallbackWarned = new WeakSet<object>();
+
+/**
+ * Runtime fallback for `cache.component(...)` callsites the timber-prebuilt
+ * transform does not rewrite — nested/computed/argument-position forms (see
+ * plugins/prebuilt.ts). Only module-scope `const X = cache.component(...)`
+ * declarations are transformed and eligible for prebuilding; everything else
+ * lands here, warns once per component, and renders dynamically. Same
+ * safety-net pattern as the data cache's runtime fnId fallback (TIM-1054):
+ * an untraceable callsite degrades in performance, never in correctness.
+ *
+ * The full public surface (types, docs, `timber` namespace) is TIM-1121;
+ * design/45-cache-lifetimes.md specifies the options.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+cache.component = function component<C extends (props: any) => unknown>(
+  componentFn: C,
+  _options?: PrebuiltComponentOptions
+): C {
+  if (!componentFallbackWarned.has(componentFn)) {
+    componentFallbackWarned.add(componentFn);
+    const name = componentFn.name || 'anonymous component';
+    console.warn(
+      `[timber] cache.component: "${name}" was not transformed at build time — ` +
+        `rendering dynamically. Only module-scope declarations ` +
+        `(const X = cache.component(...)) are prebuilt.`
+    );
+  }
+  return componentFn;
 };