@timber-js/app 0.2.0-alpha.16 → 0.2.0-alpha.160

package/src/adapters/compress-module.ts

@@ -1,101 +1,36 @@
-// Generated compression module template for self-hosted deployments.
+// Compiles server/compress.ts into a standalone ESM module (_compress.mjs)
+// for self-hosted deployments. The adapter writes this to the build output
+// during buildOutput(). It's imported by the Nitro entry and preview server
+// at runtime.
 //
-// This file generates a standalone ESM module (_compress.mjs) that is
-// written to the build output during adapter buildOutput(). It's imported
-// by the Nitro entry and preview server at runtime.
-//
-// Uses CompressionStream (Web API) for gzip. Brotli is left to CDNs/reverse
-// proxies — at streaming quality levels its ratio advantage is marginal and
-// node:zlib buffers output internally, breaking streaming.
-// Cloudflare Workers don't need this — the edge auto-compresses.
-//
-// See design/25-production-deployments.md.
+// By compiling the actual TypeScript source rather than maintaining a
+// hand-written string template, any fix to server/compress.ts automatically
+// flows to the production module. See design/18-build-system.md ("entry
+// modules are real TypeScript files, not codegen strings").
+
+import { transformWithOxc } from 'vite';
+// Vite's ?raw import embeds the file as a string at build time — works
+// in both dev (Vite resolves the TS source) and the published package
+// (the string is inlined into the compiled adapter entry).
+import compressSource from '../server/compress.ts?raw';
 
 /**
- * Generate a standalone ESM module that exports compressResponse().
+ * Compile server/compress.ts into a standalone ESM module.
  *
- * Written to `_compress.mjs` during buildOutput. Imported by the Nitro entry
- * and preview server.
+ * Uses Vite's OXC transform to strip TypeScript types from the
+ * embedded source. The result is written to `_compress.mjs` during
+ * buildOutput.
  *
  * @internal Exported for testing.
  */
-export function generateCompressModule(): string {
-  return `// Generated by @timber-js/app — response compression for self-hosted deployments.
-// Do not edit — this file is regenerated on each build.
-// Uses CompressionStream (Web API) for gzip. Brotli is left to CDNs/reverse
-// proxies — at streaming quality levels its ratio advantage is marginal and
-// node:zlib buffers output internally, breaking streaming.
-
-const COMPRESSIBLE_TYPES = new Set([
-  'text/html', 'text/css', 'text/plain', 'text/xml', 'text/javascript',
-  'text/x-component', 'application/json', 'application/javascript',
-  'application/xml', 'application/xhtml+xml', 'application/rss+xml',
-  'application/atom+xml', 'image/svg+xml',
-]);
-
-const NO_COMPRESS_STATUSES = new Set([204, 304]);
-
-function negotiateEncoding(acceptEncoding) {
-  if (!acceptEncoding) return null;
-  // Parse tokens with quality values. Per RFC 9110 §12.5.3, q=0 means
-  // "not acceptable" — the client explicitly rejects that encoding.
-  // Brotli (br) is intentionally not handled at the application level.
-  const parts = acceptEncoding.split(',');
-  for (const part of parts) {
-    const [token, ...params] = part.split(';');
-    const name = token.trim().toLowerCase();
-    if (name !== 'gzip') continue;
-    let qValue = 1;
-    for (const param of params) {
-      const trimmed = param.trim().toLowerCase();
-      if (trimmed.startsWith('q=')) {
-        qValue = parseFloat(trimmed.slice(2));
-        if (Number.isNaN(qValue)) qValue = 1;
-        break;
-      }
-    }
-    if (qValue > 0) return 'gzip';
-  }
-  return null;
-}
-
-function shouldCompress(response) {
-  if (!response.body) return false;
-  if (NO_COMPRESS_STATUSES.has(response.status)) return false;
-  if (response.headers.has('Content-Encoding')) return false;
-  const contentType = response.headers.get('Content-Type');
-  if (!contentType) return false;
-  const mimeType = contentType.split(';')[0].trim().toLowerCase();
-  if (mimeType === 'text/event-stream') return false;
-  return COMPRESSIBLE_TYPES.has(mimeType);
-}
-
-function compressWithGzip(body) {
-  return body.pipeThrough(new CompressionStream('gzip'));
-}
-
-export function compressResponse(request, response) {
-  if (!shouldCompress(response)) return response;
-  const acceptEncoding = request.headers.get('Accept-Encoding') || '';
-  const encoding = negotiateEncoding(acceptEncoding);
-  if (!encoding) return response;
-  const compressedBody = compressWithGzip(response.body);
-  const headers = new Headers(response.headers);
-  headers.set('Content-Encoding', encoding);
-  headers.delete('Content-Length');
-  const existingVary = headers.get('Vary');
-  if (existingVary) {
-    if (!existingVary.toLowerCase().includes('accept-encoding')) {
-      headers.set('Vary', existingVary + ', Accept-Encoding');
-    }
-  } else {
-    headers.set('Vary', 'Accept-Encoding');
-  }
-  return new Response(compressedBody, {
-    status: response.status,
-    statusText: response.statusText,
-    headers,
+export async function generateCompressModule(): Promise<string> {
+  const result = await transformWithOxc(compressSource, 'compress.ts', {
+    lang: 'ts',
   });
-}
-`;
+
+  return (
+    '// Generated by @timber-js/app — compiled from server/compress.ts.\n' +
+    '// Do not edit — this file is regenerated on each build.\n' +
+    result.code
+  );
 }

package/src/adapters/nitro.ts

@@ -5,28 +5,13 @@
 // compression, graceful shutdown, static file serving, and platform quirks.
 // See design/11-platform.md and design/25-production-deployments.md.
 
-import { writeFile, readFile, mkdir, cp } from 'node:fs/promises';
+import { writeFile, readFile } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
 import { join, relative } from 'node:path';
 import type { TimberPlatformAdapter, TimberConfig } from './types';
 import { generateCompressModule } from './compress-module.js';
-// Inlined from server/asset-headers.ts — adapters are loaded by Node at
-// Vite startup time, before Vite's module resolver is available, so cross-
-// directory .ts imports don't resolve.
-const IMMUTABLE_CACHE = 'public, max-age=31536000, immutable';
-const STATIC_CACHE = 'public, max-age=3600, must-revalidate';
-
-function generateHeadersFile(): string {
-  return `# Auto-generated by @timber-js/app — static asset cache headers.
-# See design/25-production-deployments.md §"CDN / Edge Cache"
-
-/assets/*
-  Cache-Control: ${IMMUTABLE_CACHE}
-
-/*
-  Cache-Control: ${STATIC_CACHE}
-`;
-}
+import { IMMUTABLE_CACHE } from './shared.js';
+import { runSharedBuildSteps } from './build-output-helper.js';
 
 // ─── Presets ─────────────────────────────────────────────────────────────────
 
@@ -202,39 +187,20 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
 
     async buildOutput(config: TimberConfig, buildDir: string) {
       const outDir = join(buildDir, 'nitro');
-      await mkdir(outDir, { recursive: true });
-
-      // Copy client assets to public directory.
-      // When client JavaScript is disabled, skip .js files — only CSS,
-      // fonts, images, and other static assets are needed.
-      const clientDir = join(buildDir, 'client');
-      const publicDir = join(outDir, 'public');
-      await mkdir(publicDir, { recursive: true });
-      await cp(clientDir, publicDir, {
-        recursive: true,
-        filter: config.clientJavascriptDisabled ? (src: string) => !src.endsWith('.js') : undefined,
-      }).catch(() => {
-        // Client dir may not exist when client JavaScript is disabled
-      });
 
-      // Write _headers file for platforms that support it (Netlify, etc.).
-      // See design/25-production-deployments.md §"CDN / Edge Cache"
-      await writeFile(join(publicDir, '_headers'), generateHeadersFile());
-
-      // Write the build manifest init module (if manifest data was produced).
-      if (config.manifestInit) {
-        await writeFile(join(outDir, '_timber-manifest-init.js'), config.manifestInit);
-      }
+      // Steps 1–5: shared across all adapters (mkdir, copy client/rsc/ssr,
+      // write _headers, write manifest-init).
+      await runSharedBuildSteps({
+        config,
+        buildDir,
+        outDir,
+        publicDirName: 'public',
+      });
 
       // Write the compression helper module for runtime use.
       // 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'), generateCompressModule());
-
-      // Copy rsc/ssr build output into the nitro dir so imports stay local
-      // during the Nitro bundling step (avoids broken relative paths in output).
-      await cp(join(buildDir, 'rsc'), join(outDir, 'rsc'), { recursive: true });
-      await cp(join(buildDir, 'ssr'), join(outDir, 'ssr'), { recursive: true }).catch(() => {});
+      await writeFile(join(outDir, '_compress.mjs'), await generateCompressModule());
 
       // Prepend the manifest assignment directly into the RSC entry so
       // globalThis.__TIMBER_BUILD_MANIFEST__ is set before any module reads it.
@@ -291,8 +257,7 @@ export function generateNitroEntry(
   buildDir: string,
   outDir: string,
   preset: NitroPreset,
-  compress = true,
-  hasManifestInit = false
+  compress = true
 ): string {
   // The RSC entry is the main request handler — it exports the fetch handler as default.
   // rsc/ is copied into the nitro dir so the import is local.
@@ -349,11 +314,6 @@ export function generateNitroEntry(
     handlerCall = `  const webResponse = await handler(webRequest)`;
   }
 
-  // Build manifest init must be imported before the handler so that
-  // globalThis.__TIMBER_BUILD_MANIFEST__ is set when the virtual module evaluates.
-  // ESM guarantees imports are evaluated in order.
-  const manifestImport = hasManifestInit ? "import './_timber-manifest-init.js'\n" : '';
-
   // Import runWithWaitUntil only when the preset supports it.
   const waitUntilImport = supportsWaitUntil ? ', runWithWaitUntil' : '';
 
@@ -363,7 +323,7 @@ export function generateNitroEntry(
   return `// Generated by @timber-js/app/adapters/nitro
 // Do not edit — this file is regenerated on each build.
 
-${manifestImport}import handler, { runWithEarlyHintsSender${waitUntilImport} } from '${serverEntryRelative}'
+import handler, { runWithEarlyHintsSender${waitUntilImport} } from '${serverEntryRelative}'
 ${compressImport}
 // Set TIMBER_RUNTIME for instrumentation.ts conditional SDK initialization.
 // See design/25-production-deployments.md §"TIMBER_RUNTIME".
@@ -383,37 +343,6 @@ ${handlerCall}
 `;
 }
 
-/** @internal Exported for testing. */
-export function generateNitroConfig(
-  preset: NitroPreset,
-  userConfig?: Record<string, unknown>
-): string {
-  const presetConfig = PRESET_CONFIGS[preset];
-
-  const config: Record<string, unknown> = {
-    preset: presetConfig.nitroPreset,
-    entry: './entry.ts',
-    output: { dir: presetConfig.outputDir },
-    // Static asset cache headers — hashed assets are immutable, others get 1h.
-    // See design/25-production-deployments.md §"CDN / Edge Cache"
-    routeRules: {
-      '/assets/**': { headers: { 'Cache-Control': IMMUTABLE_CACHE } },
-    },
-    ...presetConfig.extraConfig,
-    ...userConfig,
-  };
-
-  const configJson = JSON.stringify(config, null, 2);
-
-  return `// Generated by @timber-js/app/adapters/nitro
-// Do not edit — this file is regenerated on each build.
-
-import { defineNitroConfig } from 'nitro/config'
-
-export default defineNitroConfig(${configJson})
-`;
-}
-
 // ─── Preview ─────────────────────────────────────────────────────────────────
 
 /** Presets that produce a locally-runnable server entry. */
@@ -486,11 +415,32 @@ const MIME_TYPES = {
 };
 
 const publicDir = join(__dirname, '${publicDir}');
-const port = parseInt(process.env.PORT || '3000', 10);
+
+// Port resolution (TIM-842):
+//   - Default to 3000
+//   - If PORT env var is set, honor it strictly (fail loudly on conflict)
+//   - Otherwise auto-bump from 3000 until a free port is found
+// Mirrors the dev server behavior so timber dev/preview/production all
+// behave the same way around port selection.
+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';
 
+// Set after listenWithBump() resolves so request handlers can build
+// absolute URLs from the actual bound port (which may differ from
+// startPort after an auto-bump).
+let boundPort = startPort;
+
 const server = createServer(async (req, res) => {
-  const url = new URL(req.url || '/', \`http://\${host}:\${port}\`);
+  // Scheme from the socket's TLS state — a hardcoded http:// breaks CSRF
+  // origin comparison and absolute-URL construction when TLS is terminated
+  // at this server (TIM-1073; mirrors the dev-server fix in TIM-1067).
+  // X-Forwarded-Proto is intentionally not consulted here: on a direct
+  // connection it would be attacker-controlled. The CSRF layer honors it
+  // separately for reverse-proxy deployments.
+  const scheme = req.socket?.encrypted ? 'https' : 'http';
+  const url = new URL(req.url || '/', \`\${scheme}://\${host}:\${boundPort}\`);
 
   // Try serving static files from the public directory first.
   const filePath = join(publicDir, url.pathname);
@@ -503,7 +453,9 @@ const server = createServer(async (req, res) => {
         const contentType = MIME_TYPES[ext] || 'application/octet-stream';
         const body = await readFile(filePath);
         // Hashed assets get immutable cache, others get short cache.
-        const cacheControl = url.pathname.startsWith('/assets/')
+        const isImmutable =
+          url.pathname.startsWith('/assets/') || url.pathname.startsWith('/_timber/fonts/');
+        const cacheControl = isImmutable
           ? 'public, max-age=31536000, immutable'
           : 'public, max-age=3600, must-revalidate';
         res.writeHead(200, {
@@ -561,18 +513,64 @@ const server = createServer(async (req, res) => {
     const webResponse = compressResponse(webRequest, rawResponse);
 
     // Write the response back to the Node response.
-    res.writeHead(webResponse.status, Object.fromEntries(webResponse.headers.entries()));
+    //
+    // 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();
-      const pump = async () => {
+
+      // 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) { res.end(); return; }
+          if (done) break;
           res.write(value);
         }
-      };
-      await pump();
+      } 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();
     }
@@ -585,13 +583,49 @@ const server = createServer(async (req, res) => {
   }
 });
 
-server.listen(port, host, () => {
+function listenWithBump(port, attempt = 0) {
+  return new Promise((resolveListen, rejectListen) => {
+    const onError = (err) => {
+      server.removeListener('listening', onListening);
+      if (err && err.code === 'EADDRINUSE' && !portIsExplicit && attempt < 100) {
+        if (attempt === 0) {
+          console.log(\`  [timber] Port \${port} in use, trying \${port + 1}...\`);
+        }
+        listenWithBump(port + 1, attempt + 1).then(resolveListen, rejectListen);
+        return;
+      }
+      rejectListen(err);
+    };
+    const onListening = () => {
+      server.removeListener('error', onError);
+      resolveListen(port);
+    };
+    server.once('error', onError);
+    server.once('listening', onListening);
+    server.listen(port, host);
+  });
+}
+
+try {
+  boundPort = await listenWithBump(startPort);
+  if (boundPort !== startPort) {
+    console.log();
+    console.log(\`  [timber] Port \${startPort} in use, using \${boundPort}\`);
+  }
   console.log();
   console.log('  ⚡ timber preview server running at:');
   console.log();
-  console.log(\`    ➜  http://\${host}:\${port}\`);
+  console.log(\`    ➜  http://\${host}:\${boundPort}\`);
   console.log();
-});
+} catch (err) {
+  if (err && err.code === 'EADDRINUSE') {
+    console.error(\`[timber] Port \${startPort} is already in use. \` +
+      'Set PORT to a free port, or unset PORT to auto-pick.');
+  } else {
+    console.error('[timber] Failed to start preview server:', err);
+  }
+  process.exit(1);
+}
 `;
 }
 
@@ -649,6 +683,7 @@ async function runNitroBuild(
     output: { dir: join(nitroDir, presetConfig.outputDir) },
     routeRules: {
       '/assets/**': { headers: { 'Cache-Control': IMMUTABLE_CACHE } },
+      '/_timber/fonts/**': { headers: { 'Cache-Control': IMMUTABLE_CACHE } },
     },
     // Don't bundle the timber RSC/SSR build output — it has its own
     // internal file references that nitro's bundler can't follow.

package/src/adapters/raw-imports.d.ts

@@ -0,0 +1,5 @@
+// Vite ?raw import — embeds a file as a string at build time.
+declare module '*?raw' {
+  const content: string;
+  export default content;
+}

package/src/adapters/shared.ts

@@ -0,0 +1,68 @@
+// Shared adapter utilities — leaf module with zero deps on server/, client/,
+// or any Vite-dependent code.
+//
+// Adapters are loaded by Node at Vite startup time, before Vite's module
+// resolver is available. This module uses only Node built-ins and can be
+// imported by both adapters via a relative path.
+//
+// IMPORTANT: Do NOT add imports from ../server/, ../client/, ../plugins/,
+// or any module that transitively depends on Vite. A test in
+// tests/adapters/shared-no-forbidden-imports.test.ts enforces this.
+
+// ─── Static asset cache headers ──────────────────────────────────────────
+
+/** Cache-Control value for hashed (immutable) assets. */
+export const IMMUTABLE_CACHE = 'public, max-age=31536000, immutable';
+
+/** Cache-Control value for unhashed static assets. */
+export const STATIC_CACHE = 'public, max-age=3600, must-revalidate';
+
+/**
+ * Generate a `_headers` file for static asset cache control.
+ *
+ * The `_headers` file is a platform convention supported by Cloudflare Workers
+ * Static Assets, Cloudflare Pages, and Netlify. It maps URL patterns to
+ * HTTP response headers.
+ *
+ * Only hashed (immutable) asset paths are listed here by default. When
+ * `unhashedPaths` is provided, per-file rules are appended for unhashed
+ * static assets (favicon.ico, robots.txt, etc.) so they get Cache-Control
+ * on platforms like Cloudflare Workers Static Assets where the server
+ * handler never sees static file requests.
+ *
+ * A `/*` catch-all is NOT used — it would be additive on Cloudflare,
+ * producing duplicate Cache-Control directives on hashed assets
+ * (invalid per RFC 9111).
+ */
+// Cloudflare Workers Static Assets caps _headers at 100 rules.
+// Reserve 2 for the wildcard hashed-asset rules.
+const MAX_UNHASHED_RULES = 98;
+
+export function generateHeadersFile(unhashedPaths?: string[]): string {
+  let content = `# Auto-generated by @timber-js/app — static asset cache headers.
+# See design/25-production-deployments.md §"CDN / Edge Cache"
+
+/assets/*
+  Cache-Control: ${IMMUTABLE_CACHE}
+
+/_timber/fonts/*
+  Cache-Control: ${IMMUTABLE_CACHE}
+`;
+
+  if (unhashedPaths && unhashedPaths.length > 0) {
+    const capped = unhashedPaths.slice(0, MAX_UNHASHED_RULES);
+    if (unhashedPaths.length > MAX_UNHASHED_RULES) {
+      console.warn(
+        `[timber] _headers: ${unhashedPaths.length} unhashed static files found, ` +
+          `but Cloudflare limits _headers to 100 rules. Only the first ${MAX_UNHASHED_RULES} ` +
+          `unhashed files will get Cache-Control headers.`
+      );
+    }
+    content += `\n# Unhashed static assets — short-lived cache with revalidation\n`;
+    for (const p of capped) {
+      content += `\n${p}\n  Cache-Control: ${STATIC_CACHE}\n`;
+    }
+  }
+
+  return content;
+}

package/src/adapters/wrangler.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Type stub for the optional `wrangler` peer dependency.
+ * Prevents TS2307 during declaration emit when wrangler is not installed.
+ */
+declare module 'wrangler' {
+  export function getPlatformProxy(opts?: any): Promise<any>;
+}

package/src/cache/cache-api.ts

@@ -0,0 +1,107 @@
+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)`.
+ *
+ * Wraps an async function with cross-request caching. Uses the configured
+ * cache handler (defaults to MemoryCacheHandler, overridable via timber.config.ts).
+ *
+ * ```ts
+ * import { cache } from '@timber-js/app/cache';
+ *
+ * const getUser = cache(
+ *   async (id: string) => db.users.findUnique({ where: { id } }),
+ *   { ttl: 60, tags: (id) => [`user:${id}`] }
+ * );
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function cache<Fn extends (...args: any[]) => Promise<any>>(
+  fn: Fn,
+  opts: CacheOptions<Fn>,
+  stableId?: string
+): Fn {
+  // Pass the getter, not a resolved handler: the wrapper re-resolves it on
+  // every call, so module-scope wrappers created before the framework's boot
+  // wiring calls setCacheHandler() still pick up the configured handler
+  // instead of permanently binding the in-memory fallback (TIM-1029).
+  return createCache(fn, opts, getCacheHandler, stableId);
+}
+
+/**
+ * Invalidate cache entries by tag or key.
+ *
+ * ```ts
+ * cache.invalidate({ tag: 'products' });
+ * cache.invalidate({ key: 'user:abc' });
+ * ```
+ */
+cache.invalidate = async function invalidate(opts: { key?: string; tag?: string }): Promise<void> {
+  // Record before the handler delete so a cached fn in flight skips its
+  // 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;
+};