@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/src/adapters/cloudflare.ts

@@ -3,36 +3,59 @@
 // Primary deployment target. Generates a Workers-compatible entry point
 // and wrangler.jsonc configuration. See design/11-platform.md §"Cloudflare Workers".
 
-import { writeFile, mkdir, cp } from 'node:fs/promises';
+import { writeFile, readFile, cp, rm, readdir, access, mkdtemp, rename } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
 import { execFile } from 'node:child_process';
-import { join, relative } from 'node:path';
+import { join } from 'node:path';
+import { parse as parseJsonc } from 'jsonc-parser';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import type { TimberPlatformAdapter, TimberConfig } from './types';
-// 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 type {
+  BuildArtifacts,
+  PreviewTarget,
+  StaticBuildArtifacts,
+  TimberPlatformAdapter,
+  TimberConfig,
+} from './types.ts';
+import {
+  runSharedBuildSteps,
+  buildStaticDirectoryOutput,
+  writeHeadersFile,
+} from './build-output-helper.ts';
+import { adapterBase, generateHeadersFile } from './shared.ts';
+// Isomorphic, zero-import module — safe to load from an adapter, which Node's
+// native ESM loader evaluates before Vite's resolver exists. Same precedent as
+// `adapters/shared.ts` importing `../shared/base-path.js`.
+import { RSC_KEY_HEADERS } from '../shared/rsc-cache-key.ts';
+// Same reasoning: the media type the origin's own RSC gate matches on, so the
+// two predicates cannot drift apart. See `shared/rsc-media-type.ts`.
+import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.ts';
 
 // ─── Bindings passthrough ─────────────────────────────────────────────────
 // ALS stores the env object per-request so server components and middleware
 // can access KV, D1, DO, R2, Queues, etc. via getCloudflareBindings().
 // No global fallback — if called outside a request, it throws.
 // See design/11-platform.md §"Platform Target" and design/25-production-deployments.md.
-
-const bindingsAls = new AsyncLocalStorage<Record<string, unknown>>();
+//
+// The ALS is stored on globalThis via Symbol.for so it survives Vite's
+// module instance split in dev mode. The Vite host process (where
+// cloudflareDevBindings → runWithBindings runs) and the RSC module runner
+// (where getCloudflareBindings runs) load separate instances of this file,
+// each with their own module-level variables. globalThis + Symbol.for
+// ensures both share the same ALS — same pattern React uses for
+// Symbol.for('react.element').
+
+const BINDINGS_ALS_KEY = Symbol.for('timber:cf-bindings-als');
+
+function getBindingsAls(): AsyncLocalStorage<Record<string, unknown>> {
+  let als = (globalThis as any)[BINDINGS_ALS_KEY] as
+    | AsyncLocalStorage<Record<string, unknown>>
+    | undefined;
+  if (!als) {
+    als = new AsyncLocalStorage<Record<string, unknown>>();
+    (globalThis as any)[BINDINGS_ALS_KEY] = als;
+  }
+  return als;
+}
 
 /**
  * Get Cloudflare Worker bindings for the current request.
@@ -55,10 +78,8 @@ const bindingsAls = new AsyncLocalStorage<Record<string, unknown>>();
  * }
  * ```
  */
-export function getCloudflareBindings<
-  T extends Record<string, unknown> = Record<string, unknown>,
->(): T {
-  const env = bindingsAls.getStore();
+export function getCloudflareBindings<T = Record<string, unknown>>(): T {
+  const env = getBindingsAls().getStore();
   if (!env) {
     throw new Error(
       'getCloudflareBindings() called outside a Cloudflare Workers request context. ' +
@@ -71,14 +92,98 @@ export function getCloudflareBindings<
 
 /**
  * Run a function with Cloudflare bindings available via getCloudflareBindings().
- * @internal Used by wrapWithExecutionContext.
+ * @internal Used by cloudflareDevBindings() to wrap dev-server requests.
  */
 export function runWithBindings<T>(env: Record<string, unknown>, fn: () => T): T {
-  return bindingsAls.run(env, fn);
+  return getBindingsAls().run(env, fn);
+}
+
+// ─── Binding configuration types ──────────────────────────────────────────────
+// Declarative binding config that maps to wrangler.jsonc binding sections.
+// See design/35-cloudflare-primitives.md §"Binding Declarations in Adapter Config".
+
+/** KV namespace binding. `id` defaults to `''` (filled in by wrangler or dashboard). */
+export interface CloudflareKVBinding {
+  name: string;
+  id?: string;
+}
+
+/** D1 database binding. `database_id` is required (from Cloudflare dashboard). */
+export interface CloudflareD1Binding {
+  name: string;
+  database_id: string;
+}
+
+/** R2 bucket binding. `bucket_name` must match the bucket created in Cloudflare. */
+export interface CloudflareR2Binding {
+  name: string;
+  bucket_name: string;
+}
+
+/** Queue producer binding. `queue` is the queue name in Cloudflare. */
+export interface CloudflareQueueProducer {
+  name: string;
+  queue: string;
+}
+
+/** Queue consumer declaration. Attached to the worker, not a binding name. */
+export interface CloudflareQueueConsumer {
+  queue: string;
+  max_batch_size?: number;
+  max_retries?: number;
+  dead_letter_queue?: string;
+}
+
+/** Durable Object binding. `script_name` is for external DO references. */
+export interface CloudflareDurableObjectBinding {
+  name: string;
+  class_name: string;
+  script_name?: string;
+}
+
+/**
+ * Declarative Cloudflare bindings configuration.
+ *
+ * These are converted to the appropriate wrangler.jsonc sections
+ * (`kv_namespaces`, `d1_databases`, `r2_buckets`, `queues`, `durable_objects`).
+ * The `wrangler` escape hatch overrides any generated binding sections
+ * if there's a conflict.
+ *
+ * @example
+ * ```ts
+ * cloudflare({
+ *   bindings: {
+ *     kv: [{ name: 'TIMBER_CACHE' }],
+ *     d1: [{ name: 'MY_DB', database_id: 'xxxx' }],
+ *     r2: [{ name: 'MY_BUCKET', bucket_name: 'my-bucket' }],
+ *     queues: {
+ *       producers: [{ name: 'EMAIL_QUEUE', queue: 'email-queue' }],
+ *       consumers: [{ queue: 'email-queue', max_batch_size: 10 }],
+ *     },
+ *     durableObjects: [{ name: 'MY_DO', class_name: 'MyDurableObject' }],
+ *   },
+ * })
+ * ```
+ */
+export interface CloudflareBindings {
+  kv?: CloudflareKVBinding[];
+  d1?: CloudflareD1Binding[];
+  r2?: CloudflareR2Binding[];
+  queues?: {
+    producers?: CloudflareQueueProducer[];
+    consumers?: CloudflareQueueConsumer[];
+  };
+  durableObjects?: CloudflareDurableObjectBinding[];
 }
 
 /** Options for the Cloudflare Workers adapter. */
 export interface CloudflareAdapterOptions {
+  /**
+   * Worker name used in the generated wrangler.jsonc.
+   * @default 'timber-app'
+   */
+  name?: string;
+
   /**
    * Cloudflare compatibility date.
    * @default Current date in YYYY-MM-DD format at build time.
@@ -91,11 +196,42 @@ export interface CloudflareAdapterOptions {
    */
   compatibilityFlags?: string[];
 
+  /**
+   * Declarative Cloudflare bindings. Generates the appropriate
+   * `kv_namespaces`, `d1_databases`, `r2_buckets`, `queues`, and
+   * `durable_objects` sections in wrangler.jsonc.
+   *
+   * If both `bindings` and `wrangler` specify the same section,
+   * `wrangler` wins (it's the escape hatch).
+   */
+  bindings?: CloudflareBindings;
+
   /**
    * Custom wrangler.jsonc fields to merge.
-   * Overrides generated values.
+   * Overrides generated values (including bindings-generated sections).
    */
   wrangler?: Record<string, unknown>;
+
+  /**
+   * Path to a module that exports additional Worker handlers (queue, scheduled, email, etc.).
+   * The module is imported in the generated `_worker.js` and its named exports are
+   * spread into the default export alongside `fetch`.
+   *
+   * The module receives `(batch/event, env, ctx)` — standard Cloudflare handler signatures.
+   * It does NOT have access to timber's request pipeline (no ALS, no getCloudflareBindings).
+   * Use `env` directly for bindings.
+   *
+   * @example
+   * ```ts
+   * // timber.config.ts
+   * adapter: cloudflare({ workerHandlers: './src/worker-handlers.ts' })
+   *
+   * // src/worker-handlers.ts
+   * export async function queue(batch, env) { ... }
+   * export async function scheduled(controller, env, ctx) { ... }
+   * ```
+   */
+  workerHandlers?: string;
 }
 
 /**
@@ -115,164 +251,648 @@ export function cloudflare(options: CloudflareAdapterOptions = {}): TimberPlatfo
   return {
     name: 'cloudflare',
 
-    async buildOutput(config: TimberConfig, buildDir: string) {
-      const outDir = join(buildDir, 'cloudflare');
-      await mkdir(outDir, { recursive: true });
-
-      // Copy client assets to static output.
-      // When client JavaScript is disabled, skip .js files — only CSS,
-      // fonts, images, and other static assets are needed.
-      const clientDir = join(buildDir, 'client');
-      const staticDir = join(outDir, 'static');
-      await mkdir(staticDir, { recursive: true });
-      await cp(clientDir, staticDir, {
-        recursive: true,
-        filter: config.clientJavascriptDisabled ? (src: string) => !src.endsWith('.js') : undefined,
-      }).catch(() => {
-        // Client dir may not exist when client JavaScript is disabled
+    async buildOutput(config: TimberConfig, artifacts: BuildArtifacts) {
+      const outDir = join(artifacts.outputDir, 'cloudflare');
+
+      // ── Static mode: Cloudflare Pages-compatible output ──────────────
+      // No Workers entry — just HTML files + client assets in a flat
+      // directory that Cloudflare Pages can serve directly.
+      if (artifacts.output === 'static') {
+        await buildStaticOutput(config, artifacts, outDir, options);
+        return;
+      }
+
+      // Clean stale prebuilt artifacts from prior builds.
+      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).
+      // Prebuilt payloads are inlined into the worker below rather than
+      // copied: Workers has no filesystem to read them from.
+      await runSharedBuildSteps({
+        config,
+        artifacts: { ...artifacts, prebuilt: undefined },
+        outDir,
+        publicDirName: 'static',
       });
 
-      // Write _headers file for static asset cache control.
-      // Cloudflare Workers Static Assets reads this to set Cache-Control
-      // headers on responses. Hashed assets get immutable; others get 1h.
-      await writeFile(join(staticDir, '_headers'), generateHeadersFile());
-
-      // Copy server bundles (rsc + ssr) into the output directory.
-      // These are already fully bundled by Vite with resolve.noExternal: true.
-      const rscDir = join(buildDir, 'rsc');
-      const ssrDir = join(buildDir, 'ssr');
-      await cp(rscDir, join(outDir, 'rsc'), { recursive: true });
-      await cp(ssrDir, join(outDir, 'ssr'), { recursive: true });
-
-      // Write the build manifest init module (if manifest data was produced).
-      // This must be imported before the RSC handler so the global is set
-      // when virtual:timber-build-manifest evaluates.
-      if (config.manifestInit) {
-        await writeFile(join(outDir, '_timber-manifest-init.js'), config.manifestInit);
+      // Compile optional worker handlers (queue, scheduled, etc.)
+      // Uses Vite's build API to bundle the TypeScript source into ESM.
+      let hasWorkerHandlers = false;
+      if (options.workerHandlers) {
+        const handlersEntry = join(process.cwd(), options.workerHandlers);
+        const { build: viteBuild } = await import('vite');
+        await viteBuild({
+          configFile: false,
+          logLevel: 'info',
+          build: {
+            lib: {
+              entry: handlersEntry,
+              formats: ['es'],
+              fileName: () => '_worker-handlers.js',
+            },
+            outDir,
+            emptyOutDir: false,
+            minify: false,
+            rollupOptions: {
+              external: [/^node:/, /^cloudflare:/],
+            },
+          },
+        });
+        hasWorkerHandlers = true;
       }
 
+      // Inline prebuilt flight payloads into the worker JS module (TIM-1162).
+      // Data is read from the build's prebuilt/ artifact and embedded as
+      // literals — no external Text/Data module imports needed.
+      const prebuiltData = artifacts.prebuilt
+        ? await readPrebuiltData(artifacts.prebuilt.path)
+        : null;
+      await writeFile(
+        join(outDir, '_timber-prebuilt-source.js'),
+        generatePrebuiltSourceModule(prebuiltData)
+      );
+
+      // Write the runtime init module — sets process.env.TIMBER_RUNTIME
+      // BEFORE the RSC entry evaluates (ESM import order). Without this,
+      // createRequestHandler's auto-wire for WorkersCachePurge would not
+      // detect the Cloudflare runtime (TIM-1170).
+      await writeFile(join(outDir, '_timber-runtime-init.js'), generateRuntimeInitModule());
+
       // Generate the Workers entry point
-      const hasManifestInit = !!config.manifestInit;
-      const workerEntry = generateWorkerEntry(outDir, outDir, hasManifestInit);
+      const hasManifestInit = !!artifacts.manifestInit;
+      const workerEntry = generateWorkerEntry(hasManifestInit, hasWorkerHandlers);
       await writeFile(join(outDir, '_worker.js'), workerEntry);
 
-      // Generate wrangler.jsonc
-      const wranglerConfig = generateWranglerConfig(config, options);
+      // Generate wrangler.jsonc — merges user's wrangler config from disk if present
+      const root = config.root ?? process.cwd();
+      const userConfig = await readUserWranglerConfig(root);
+      const wranglerConfig = generateWranglerConfig(config, options, userConfig);
       await writeFile(join(outDir, 'wrangler.jsonc'), JSON.stringify(wranglerConfig, null, 2));
     },
 
-    async preview(_config: TimberConfig, buildDir: string) {
-      const cmd = generatePreviewCommand(buildDir);
-      await spawnPreviewProcess(cmd.command, cmd.args, cmd.cwd);
-    },
-
-    // Default no-op. wrapWithExecutionContext() replaces this per-request
-    // with a function that routes to ctx.waitUntil().
-    waitUntil(_promise: Promise<unknown>) {},
-  };
-}
-
-/**
- * Wrap a timber request handler to bind the Cloudflare execution context
- * for `waitUntil()` support and env bindings passthrough.
- * Called from the generated worker entry.
- *
- * This function:
- * 1. Binds `adapter.waitUntil()` to `ctx.waitUntil()` per-request
- * 2. Makes `env` accessible via `getCloudflareBindings()` per-request via ALS
- */
-export function wrapWithExecutionContext(
-  adapter: TimberPlatformAdapter,
-  handler: (req: Request) => Promise<Response>
-): ExportedHandler<Record<string, unknown>> {
-  return {
-    async fetch(
-      request: Request,
-      env: Record<string, unknown>,
-      ctx: ExecutionContext
-    ): Promise<Response> {
-      // Bind the adapter's waitUntil to the Workers execution context
-      const originalWaitUntil = adapter.waitUntil;
-      adapter.waitUntil = (promise: Promise<unknown>) => {
-        ctx.waitUntil(promise);
-      };
-
+    async preview(config: TimberConfig, target: PreviewTarget) {
+      const base = adapterBase(config);
+      if (target.output !== 'static' || base === '/') {
+        const cmd = generatePreviewCommand(target);
+        await spawnPreviewProcess(cmd.command, cmd.args, cmd.cwd);
+        return;
+      }
+      // A static build under a base: serve a staged copy with the site
+      // mounted at the base, as the deployment is reached.
+      const stage = await mkdtemp(join(tmpdir(), 'timber-pages-preview-'));
       try {
-        // Run the handler within ALS so getCloudflareBindings() works
-        return await runWithBindings(env, () => handler(request));
+        await stagePagesPreview(join(target.outputDir, 'cloudflare'), base, stage);
+        const cmd = generatePreviewCommand(target, stage);
+        await spawnPreviewProcess(cmd.command, cmd.args, cmd.cwd);
       } finally {
-        // Restore (in case adapter is reused across isolate resets)
-        adapter.waitUntil = originalWaitUntil;
+        await rm(stage, { recursive: true, force: true });
       }
     },
+
+    // No adapter-level waitUntil: on Workers there is no ambient
+    // ExecutionContext outside a request, so support is provided
+    // per-request by the generated _worker.js, which bridges
+    // ctx.waitUntil() into the ALS via runWithWaitUntil().
+    // See design/11-platform.md §"waitUntil()".
   };
 }
 
 // ─── Exported helpers (used by tests and build) ─────────────────────────────
 
 /** @internal Exported for testing. */
-export function generateWorkerEntry(
-  buildDir: string,
-  outDir: string,
-  hasManifestInit = false
-): string {
-  // The RSC entry is the main request handler — it exports the fetch handler as default.
-  // The Vite RSC plugin outputs it to rsc/index.js.
-  let rscEntryRelative = relative(outDir, join(buildDir, 'rsc', 'index.js'));
-  // Ensure the import path starts with ./ for ESM compatibility
-  if (!rscEntryRelative.startsWith('.')) {
-    rscEntryRelative = './' + rscEntryRelative;
-  }
-
+export function generateWorkerEntry(hasManifestInit = false, hasWorkerHandlers = false): string {
   // Build manifest init must be imported before the RSC 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" : '';
 
+  // Optional additional Worker handlers (queue, scheduled, email, etc.)
+  // Compiled by buildOutput via Vite's build API into _worker-handlers.js.
+  // The module's named exports are spread into the default export alongside fetch.
+  const handlersImport = hasWorkerHandlers
+    ? "import * as workerHandlers from './_worker-handlers.js'\n"
+    : '';
+  const handlersSpread = hasWorkerHandlers ? '  ...workerHandlers,\n' : '';
+
   return `// Generated by @timber-js/app/adapters/cloudflare
 // Do not edit — this file is regenerated on each build.
 
-${manifestImport}import handler from '${rscEntryRelative}'
+import { AsyncLocalStorage } from 'node:async_hooks'
+// Side-effect imports: evaluated IN ORDER before the _worker.js body runs.
+// _timber-runtime-init.js sets TIMBER_RUNTIME before createRequestHandler()
+// runs (during the RSC entry's top-level await) so the auto-wire for
+// WorkersCachePurge can detect the Cloudflare runtime (TIM-1170).
+// _timber-prebuilt-source.js sets globalThis.__TIMBER_PREBUILT_SOURCE__
+// for cache.component payloads.
+import './_timber-runtime-init.js'
+import './_timber-prebuilt-source.js'
+${manifestImport}import handler, { runWithWaitUntil, runWithWorkersCachePurge, stripHeadBody } from './rsc/index.js'
+${handlersImport}
+
+// Bind Cloudflare env to ALS so getCloudflareBindings() works at runtime.
+// Uses the same Symbol.for key as getCloudflareBindings() reads from.
+const ALS_KEY = Symbol.for('timber:cf-bindings-als')
+let bindingsAls = globalThis[ALS_KEY]
+if (!bindingsAls) {
+  bindingsAls = new AsyncLocalStorage()
+  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
+}
+
+// The \`Vary\` tokens this cache can serve a correct answer for.
+//
+// Cloudflare's Cache API keys on the request URL. It does not implement
+// RFC 9111 §4.1 secondary key selection, so a stored response is handed to
+// every request for that URL regardless of what \`Vary\` nominates — except
+// \`Accept-Encoding\`, which the platform segregates itself. Storing a
+// response whose \`Vary\` says "this answer is specific to header H" under a
+// key that ignores H is cross-client reuse (TIM-1269): a developer writing
+// the correct \`public, s-maxage=60\` + \`Vary: Cookie\` gets their logged-in
+// page served to anonymous visitors. Refusing to store is the conservative
+// answer, and the only one available without rewriting the key.
+//
+// The framework's own tokens are on this list because the adapter already
+// segregates them, more strictly than \`Vary\` would:
+//
+//   - \`Accept\` — \`isRsc\` above excludes \`text/x-component\` from both lookup
+//     and store, so the HTML/Flight split \`Vary: Accept\` exists to protect
+//     never reaches this cache in the first place.
+//   - \`X-Timber-State-Tree\`, \`X-Timber-URL\`, \`X-Timber-Deployment-Id\` — the
+//     origin reads all three only on RSC requests (version skew at
+//     \`server/pipeline-phases.ts\`, interception rewrites likewise, state-tree
+//     diffing at \`server/rsc-entry/render-route.ts\`). On the non-RSC requests
+//     this cache stores, they cannot change the response.
+//
+// That second bullet is a coupling, not an observation: if any of those
+// headers ever starts varying a document response, this list is wrong and
+// the cache poisons. Because the list is derived, a header added to
+// \`RSC_KEY_HEADERS\` inherits the exemption silently — so
+// \`tests/adapters/cloudflare-vary.test.ts\` fails until that header is named
+// there alongside the evidence for its gate, and the gates themselves are
+// covered there, in \`tests/render-route.test.ts\`, and in
+// \`tests/interception-x-timber-url.test.ts\`.
+//
+// Interpolated from \`RSC_KEY_HEADERS\` rather than spelled again — "which
+// headers vary an RSC response" has one answer, and a hand-copied second
+// list here would drift silently on the fallback path nobody exercises.
+//
+// Known residual: a route handler that content-negotiates on \`Accept\`
+// (JSON vs HTML) *and* marks itself \`public\` is still mis-keyed, because the
+// \`isRsc\` split is binary and does not separate those two. That is no worse
+// than the pre-TIM-1269 behaviour, which stored every \`Vary\` but \`*\`.
+const VARY_HONORED = new Set(${JSON.stringify(['accept-encoding', ...RSC_KEY_HEADERS.map((h) => h.toLowerCase())])})
+
+// Applied to BOTH sides of the cache — what may be stored, and what a hit
+// may serve. Refusing to store only stops new poisoning: entries a previous
+// deployment wrote under the old predicate stay servable for whatever
+// s-maxage the developer chose, which can be a day. Checking on the way out
+// makes the fix take effect on deploy rather than on expiry, and costs one
+// header read per hit. A rejected entry falls through to the origin and is
+// then declined by the same predicate on the way back in, so it is not
+// rewritten — it simply ages out.
+function canHonorVary(vary) {
+  // Absent or empty Vary nominates nothing — the URL is the whole key.
+  if (!vary) return true
+  return vary.split(',').every((token) => VARY_HONORED.has(token.trim().toLowerCase()))
+}
+
+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 (caches.default).
+    // caches.default and ctx.cache.purge() operate on the same underlying
+    // Cloudflare CDN cache — "independent" in the CF docs means independent
+    // write APIs, not independent stores (TIM-1172). Tag-based purging via
+    // revalidateTag() clears entries stored here when their Cache-Tag header
+    // matches the invalidated tag. See design/25 §TIM-1172.
+    //
+    // RSC navigation requests (Accept: text/x-component) are excluded.
+    // Their varying inputs are now in the URL via ?_rsc= (TIM-1268), but
+    // this cache keys on the request URL alone and cannot honour Vary, so a
+    // payload request that arrives without the param — stripped query,
+    // hand-rolled client — would share a key with the document.
+    //
+    // This exclusion is load-bearing in the other direction too: the store
+    // predicate below treats "Vary: Accept" as honoured *because* of it
+    // (see VARY_HONORED). Removing it would make that allowlist unsound.
+    const isRsc = request.headers.get('Accept')?.includes(${JSON.stringify(RSC_CONTENT_TYPE)})
+    const reqCc = request.headers.get('Cache-Control') || ''
+    const bypassCache = reqCc.includes('no-cache') || reqCc.includes('max-age=0')
+        || request.headers.has('Pragma')
+    const cacheable = !isRsc && !bypassCache
+        && (request.method === 'GET' || request.method === 'HEAD')
+    const cache = cacheable && typeof caches !== 'undefined' ? caches.default : null
+    if (cache) {
+      const cached = await cache.match(request)
+      // A hit whose Vary this cache cannot key on is treated as a miss —
+      // see canHonorVary. Entries written before that predicate existed are
+      // exactly the ones that would be served to the wrong client.
+      if (cached) {
+        if (canHonorVary(cached.headers.get('Vary'))) return stripHeadBody(cached, request.method)
+        // Declining the hit means nobody will ever read this body. Release
+        // it rather than leaving the stream dangling for the rest of the
+        // request (design/02-rendering-pipeline.md §"Cancel Readers When You
+        // No Longer Need the Stream").
+        cached.body?.cancel().catch(() => {})
+      }
+    }
+
+    // Bridge ctx.cache into the per-request ALS so WorkersCachePurge can
+    // call ctx.cache.purge({ tags }) during cache.invalidate/revalidateTag.
+    // Workers Cache is available on all Cloudflare plans — no API token needed.
+    const workersCacheCtx = ctx.cache && typeof ctx.cache.purge === 'function' ? ctx.cache : null
+    const runHandler = () =>
+      runWithWaitUntil((promise) => ctx.waitUntil(promise), () => handler(request))
+    const response = await bindingsAls.run(env, () =>
+      workersCacheCtx
+        ? runWithWorkersCachePurge(workersCacheCtx, runHandler)
+        : runHandler()
+    )
+
+    // Cache public responses at the edge. A response is edge-cacheable if
+    // it has 'public' or 's-maxage' (a shared-cache TTL directive) and no
+    // 'no-store' or 'private'. Cloudflare's cache.put() only accepts GET
+    // requests and rejects 206, so only store GET 200s. HEAD requests
+    // are served from cache.match() hits with the body stripped (TIM-1325).
+    // See design/25-production-deployments.md §"CDN / Edge Cache".
+    if (cache && request.method === 'GET' && response.status === 200) {
+      const cc = response.headers.get('Cache-Control')
+      if (cc && !cc.includes('no-store') && !cc.includes('private')
+          && (cc.includes('public') || cc.includes('s-maxage'))
+          && canHonorVary(response.headers.get('Vary'))
+          && !response.headers.has('Set-Cookie')) {
+        ctx.waitUntil(cache.put(request, response.clone()))
+      }
+    }
+
+    return response
+  }
+}
+`;
+}
+
+/** Build-time prebuilt data read from `.timber/dist/prebuilt/`. */
+export interface PrebuiltModuleData {
+  /** Raw manifest.json content. */
+  manifestJson: string;
+  /** Payload file paths and their raw bytes. */
+  payloads: Array<{ file: string; bytes: Buffer }>;
+}
+
+/**
+ * Read the prebuilt flight payloads the capture pass wrote. Called only
+ * when the build produced a `prebuilt` artifact, which always carries its
+ * `manifest.json` — so a read failure here is a real error, not absence.
+ *
+ * @internal Exported for testing.
+ */
+export async function readPrebuiltData(prebuiltDir: string): Promise<PrebuiltModuleData> {
+  const manifestJson = await readFile(join(prebuiltDir, 'manifest.json'), 'utf-8');
+  const payloads: PrebuiltModuleData['payloads'] = [];
+  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')) {
+        const filePath = `${dir.name}/${file}`;
+        const bytes = await readFile(join(prebuiltDir, filePath));
+        payloads.push({ file: filePath, bytes });
+      }
+    }
+  }
+  return { manifestJson, payloads };
+}
+
+/**
+ * Generate the prebuilt payload source module for Cloudflare Workers.
+ *
+ * Inlines manifest JSON and flight payload bytes directly into the module
+ * so they're part of the worker's JS bundle — no external Text/Data module
+ * imports needed. This avoids depending on wrangler's find_additional_modules
+ * to discover non-JS files, which doesn't reliably resolve Text/Data imports.
+ *
+ * @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 entries: string[] = [];
+  for (const { file, bytes } of data.payloads) {
+    const b64 = Buffer.from(bytes).toString('base64');
+    entries.push(`  ${JSON.stringify(file)}: ${JSON.stringify(b64)}`);
+  }
+
+  return `// Generated by @timber-js/app/adapters/cloudflare
+// Prebuilt payload source — inlines cache.component flight payloads
+// directly into the worker bundle (TIM-1162).
+const _manifest = ${data.manifestJson.trim()}
+
+function _decode(b64) {
+  const bin = atob(b64)
+  const buf = new Uint8Array(bin.length)
+  for (let i = 0; i < bin.length; i++) buf[i] = bin.charCodeAt(i)
+  return buf
+}
+
+const _payloads = {
+${entries.join(',\n')}
+}
 
-// Set TIMBER_RUNTIME for instrumentation.ts conditional SDK initialization.
-// See design/25-production-deployments.md §"TIMBER_RUNTIME".
+globalThis.__TIMBER_PREBUILT_SOURCE__ = {
+  async loadManifest() { return _manifest },
+  async readPayload(file) {
+    const b64 = _payloads[file]
+    return b64 ? _decode(b64) : null
+  },
+}
+`;
+}
+
+/**
+ * Generate the runtime init module that sets TIMBER_RUNTIME before the
+ * RSC entry evaluates. Imported as a side-effect module in _worker.js.
+ *
+ * @internal Exported for testing.
+ */
+export function generateRuntimeInitModule(): string {
+  return `// Generated by @timber-js/app/adapters/cloudflare
+// Sets TIMBER_RUNTIME before the RSC handler evaluates (TIM-1170).
+// Must be a separate module imported before rsc/index.js so that ESM
+// evaluation order guarantees the env var is set when
+// createRequestHandler() runs its auto-wire logic.
 globalThis.process ??= { env: {} }
 process.env.TIMBER_RUNTIME = 'cloudflare'
-
-export default { fetch: handler }
 `;
 }
 
+/** Wrangler binding sections generated from `CloudflareBindings`. */
+export interface WranglerBindingsConfig {
+  kv_namespaces?: Array<{ binding: string; id: string }>;
+  d1_databases?: Array<{ binding: string; database_id: string }>;
+  r2_buckets?: Array<{ binding: string; bucket_name: string }>;
+  queues?: {
+    producers?: Array<{ binding: string; queue: string }>;
+    consumers?: Array<Record<string, unknown>>;
+  };
+  durable_objects?: {
+    bindings: Array<Record<string, string>>;
+  };
+}
+
+/**
+ * Convert declarative `CloudflareBindings` into wrangler.jsonc binding sections.
+ *
+ * Maps:
+ * - `kv`             → `kv_namespaces`
+ * - `d1`             → `d1_databases`
+ * - `r2`             → `r2_buckets`
+ * - `queues`         → `queues` (producers + consumers)
+ * - `durableObjects` → `durable_objects`
+ *
+ * Empty arrays are omitted from the output.
+ *
+ * @internal Exported for testing.
+ */
+export function generateBindingsConfig(
+  bindings: CloudflareBindings | undefined
+): WranglerBindingsConfig {
+  if (!bindings) return {};
+
+  const result: WranglerBindingsConfig = {};
+
+  // KV namespaces
+  if (bindings.kv && bindings.kv.length > 0) {
+    result.kv_namespaces = bindings.kv.map((kv) => ({
+      binding: kv.name,
+      id: kv.id ?? '',
+    }));
+  }
+
+  // D1 databases
+  if (bindings.d1 && bindings.d1.length > 0) {
+    result.d1_databases = bindings.d1.map((d1) => ({
+      binding: d1.name,
+      database_id: d1.database_id,
+    }));
+  }
+
+  // R2 buckets
+  if (bindings.r2 && bindings.r2.length > 0) {
+    result.r2_buckets = bindings.r2.map((r2) => ({
+      binding: r2.name,
+      bucket_name: r2.bucket_name,
+    }));
+  }
+
+  // Queues (producers and/or consumers)
+  if (bindings.queues) {
+    const queues: Record<string, unknown> = {};
+    if (bindings.queues.producers && bindings.queues.producers.length > 0) {
+      queues.producers = bindings.queues.producers.map((p) => ({
+        binding: p.name,
+        queue: p.queue,
+      }));
+    }
+    if (bindings.queues.consumers && bindings.queues.consumers.length > 0) {
+      queues.consumers = bindings.queues.consumers.map((c) => {
+        const consumer: Record<string, unknown> = { queue: c.queue };
+        if (c.max_batch_size !== undefined) consumer.max_batch_size = c.max_batch_size;
+        if (c.max_retries !== undefined) consumer.max_retries = c.max_retries;
+        if (c.dead_letter_queue !== undefined) consumer.dead_letter_queue = c.dead_letter_queue;
+        return consumer;
+      });
+    }
+    if (Object.keys(queues).length > 0) {
+      result.queues = queues;
+    }
+  }
+
+  // Durable Objects
+  if (bindings.durableObjects && bindings.durableObjects.length > 0) {
+    result.durable_objects = {
+      bindings: bindings.durableObjects.map((dobj) => {
+        const entry: Record<string, string> = {
+          name: dobj.name,
+          class_name: dobj.class_name,
+        };
+        if (dobj.script_name) entry.script_name = dobj.script_name;
+        return entry;
+      }),
+    };
+  }
+
+  return result;
+}
+
+/**
+ * One-level deep merge: for each key in `override`, if both the base and
+ * override values are plain objects (not arrays, not null), merge their
+ * keys with override winning on conflicts. Everything else (primitives,
+ * arrays, null) is replaced outright — matching the intuitive behavior
+ * where `kv_namespaces: [...]` replaces fully but
+ * `durable_objects: { migrations }` merges with generated `bindings`.
+ */
+function shallowDeepMerge(
+  base: Record<string, unknown>,
+  override: Record<string, unknown>
+): Record<string, unknown> {
+  const result = { ...base };
+  for (const key of Object.keys(override)) {
+    const baseVal = result[key];
+    const overVal = override[key];
+    if (isPlainObject(baseVal) && isPlainObject(overVal)) {
+      result[key] = { ...baseVal, ...overVal };
+    } else {
+      result[key] = overVal;
+    }
+  }
+  return result;
+}
+
+/** True for `{}` literals — false for arrays, null, Date, etc. */
+function isPlainObject(val: unknown): val is Record<string, unknown> {
+  return val !== null && typeof val === 'object' && !Array.isArray(val);
+}
+
+const WRANGLER_CONFIG_FILES = ['wrangler.jsonc', 'wrangler.json'] as const;
+
+/**
+ * Read the user's wrangler config from the project root, if one exists.
+ * Checks wrangler.jsonc first, then wrangler.json.
+ * @internal Exported for testing.
+ */
+export async function readUserWranglerConfig(
+  root: string
+): Promise<Record<string, unknown> | null> {
+  for (const filename of WRANGLER_CONFIG_FILES) {
+    const filepath = join(root, filename);
+    try {
+      await access(filepath);
+    } catch {
+      continue;
+    }
+    const content = await readFile(filepath, 'utf-8');
+    return parseJsonc(content) as Record<string, unknown>;
+  }
+  return null;
+}
+
 /** @internal Exported for testing. */
 export function generateWranglerConfig(
   config: TimberConfig,
-  options: CloudflareAdapterOptions
+  options: CloudflareAdapterOptions,
+  userConfig?: Record<string, unknown> | null
 ): Record<string, unknown> {
-  const compatDate = options.compatibilityDate ?? new Date().toISOString().slice(0, 10);
-
-  const flags = options.compatibilityFlags ?? ['nodejs_compat'];
-
   const base: Record<string, unknown> = {
     name: 'timber-app',
     main: '_worker.js',
-    compatibility_date: compatDate,
-    compatibility_flags: flags,
-    // The build output is already fully bundled by Vite — skip wrangler's
-    // esbuild pass to avoid issues with top-level await and module format.
+    compatibility_date: new Date().toISOString().slice(0, 10),
+    compatibility_flags: ['nodejs_compat'],
     no_bundle: true,
     find_additional_modules: true,
     rules: [{ type: 'ESModule', globs: ['**/*.js'] }],
     assets: {
       directory: './static',
+      binding: 'ASSETS',
+    },
+    observability: {
+      traces: { enabled: true },
     },
   };
 
-  // Merge user overrides
+  // Layer 1: user's wrangler.jsonc / wrangler.json from disk
+  let merged: Record<string, unknown> = userConfig ? shallowDeepMerge(base, userConfig) : base;
+
+  // Layer 2: explicit adapter options override disk config
+  const explicit: Record<string, unknown> = {};
+  if (options.name != null) explicit.name = options.name;
+  if (options.compatibilityDate != null) explicit.compatibility_date = options.compatibilityDate;
+  if (options.compatibilityFlags != null) explicit.compatibility_flags = options.compatibilityFlags;
+  if (Object.keys(explicit).length > 0) {
+    merged = { ...merged, ...explicit };
+  }
+
+  // Layer 3: declarative bindings
+  const bindingsConfig = generateBindingsConfig(options.bindings);
+  merged = shallowDeepMerge(merged, bindingsConfig as Record<string, unknown>);
+
+  // Layer 4: wrangler escape hatch — highest priority, deep merge.
   if (options.wrangler) {
-    return { ...base, ...options.wrangler };
+    merged = shallowDeepMerge(merged, options.wrangler);
   }
 
-  return base;
+  // Generated config targets a single environment — env blocks can override
+  // main/assets per-environment and break the build output.
+  delete merged.env;
+
+  // These fields are required for the build output to work correctly.
+  merged.main = '_worker.js';
+  merged.find_additional_modules = true;
+
+  return merged;
+}
+
+// ─── Static output ──────────────────────────────────────────────────────────
+
+/**
+ * Build a Cloudflare Pages-compatible static output directory.
+ *
+ * No Workers entry — just pre-rendered HTML, RSC flight files, and client
+ * assets in a flat directory. Uses the shared buildStaticDirectoryOutput
+ * then adds a `_headers` file for cache control.
+ *
+ * @internal Exported for testing.
+ */
+export async function buildStaticOutput(
+  config: TimberConfig,
+  artifacts: StaticBuildArtifacts,
+  outDir: string,
+  _options: CloudflareAdapterOptions
+): Promise<void> {
+  // Cloudflare Pages serves from the outDir root directly (no subdirectory).
+  // Use '.' as publicDirName so files land at outDir/ not outDir/static/.
+  await buildStaticDirectoryOutput(config, artifacts, outDir, '.');
+
+  // Write _headers file for cache control + content-type rules.
+  await writeHeadersFile(outDir, config, artifacts);
 }
 
 // ─── Preview ─────────────────────────────────────────────────────────────────
@@ -284,9 +904,22 @@ export interface PreviewCommand {
   cwd: string;
 }
 
-/** @internal Exported for testing. */
-export function generatePreviewCommand(buildDir: string): PreviewCommand {
-  const cfDir = join(buildDir, 'cloudflare');
+/**
+ * A server build runs its Worker under `wrangler dev` with the generated
+ * wrangler.jsonc. A static build writes no Worker and no wrangler.jsonc — its
+ * output is a Pages directory (`_headers`, `_redirects`, the site) — so it
+ * is served by `wrangler pages dev`, which applies those files as Pages does.
+ *
+ * @internal Exported for testing.
+ */
+export function generatePreviewCommand(
+  { output, outputDir }: PreviewTarget,
+  pagesRoot = join(outputDir, 'cloudflare')
+): PreviewCommand {
+  if (output === 'static') {
+    return { command: 'wrangler', args: ['pages', 'dev', pagesRoot], cwd: pagesRoot };
+  }
+  const cfDir = join(outputDir, 'cloudflare');
   return {
     command: 'wrangler',
     args: ['dev', '--local', '--config', join(cfDir, 'wrangler.jsonc')],
@@ -294,6 +927,35 @@ export function generatePreviewCommand(buildDir: string): PreviewCommand {
   };
 }
 
+/** Pages config files, read from the served root; their rules are in deployed-URL space. */
+const PAGES_ROOT_FILES = ['_headers', '_redirects'];
+
+/**
+ * Stage a static Cloudflare build for `wrangler pages dev` under a non-root
+ * base. The build writes the site at the directory root (a Pages project is
+ * served at its domain root, and the base path is supplied by whatever routes
+ * to it), but its HTML requests `/repo/...` and its `_headers`/`_redirects`
+ * rules are base-prefixed. Serving the directory as-is would 404 every page
+ * and asset, so the preview mounts the site at the base and keeps the rule
+ * files at the root, where Pages reads them and where their prefixed
+ * patterns match.
+ *
+ * @param base Normalized deployment base, not `/`.
+ * @internal Exported for testing.
+ */
+export async function stagePagesPreview(
+  siteDir: string,
+  base: string,
+  stageDir: string
+): Promise<void> {
+  const mount = join(stageDir, ...base.split('/').filter(Boolean));
+  await cp(siteDir, mount, { recursive: true });
+  const rootFiles = new Set(await readdir(mount));
+  for (const name of PAGES_ROOT_FILES) {
+    if (rootFiles.has(name)) await rename(join(mount, name), join(stageDir, name));
+  }
+}
+
 /**
  * Spawn a long-running preview process and pipe stdio to the parent.
  * Resolves when the process exits.
@@ -310,16 +972,13 @@ function spawnPreviewProcess(command: string, args: string[], cwd: string): Prom
 }
 
 // ─── Cloudflare Workers type stubs ───────────────────────────────────────────
-// Minimal type declarations so this file compiles without @cloudflare/workers-types.
-// In production builds, users install @cloudflare/workers-types themselves.
-
-declare global {
-  interface ExecutionContext {
-    waitUntil(promise: Promise<unknown>): void;
-    passThroughOnException(): void;
-  }
-
-  interface ExportedHandler<Env = Record<string, unknown>> {
-    fetch?(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> | Response;
-  }
+// Local type declarations so this file compiles without @cloudflare/workers-types.
+// These are NOT declared globally — that would clash with @cloudflare/workers-types
+// when users install it. Instead, they're module-scoped and used only within
+// this file's function signatures.
+
+/** @internal Minimal stub — use @cloudflare/workers-types for full types. */
+export interface CfExecutionContext {
+  waitUntil(promise: Promise<unknown>): void;
+  passThroughOnException(): void;
 }