@timber-js/app 0.2.0-alpha.12 → 0.2.0-alpha.121

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.12",
-  "description": "Vite-native React framework for Cloudflare Workers — correct HTTP semantics, real status codes, pages that work without JavaScript",
+  "version": "0.2.0-alpha.121",
+  "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",
     "framework",
@@ -31,7 +31,18 @@
   ],
   "type": "module",
   "imports": {
-    "#/*": "./src/*"
+    "#server-internal": {
+      "types": "./dist/server/internal.d.ts",
+      "default": "./dist/server/internal.js"
+    },
+    "#client-internal": {
+      "types": "./dist/client/internal.d.ts",
+      "default": "./dist/client/internal.js"
+    },
+    "#routing": {
+      "types": "./dist/routing/index.d.ts",
+      "default": "./dist/routing/index.js"
+    }
   },
   "exports": {
     ".": {
@@ -46,13 +57,17 @@
       "types": "./dist/client/index.d.ts",
       "import": "./dist/client/index.js"
     },
+    "./client/internal": {
+      "types": "./dist/client/internal.d.ts",
+      "import": "./dist/client/internal.js"
+    },
     "./cache": {
       "types": "./dist/cache/index.d.ts",
       "import": "./dist/cache/index.js"
     },
-    "./content": {
-      "types": "./dist/content/index.d.ts",
-      "import": "./dist/content/index.js"
+    "./codec": {
+      "types": "./dist/codec.d.ts",
+      "import": "./dist/codec.js"
     },
     "./cookies": {
       "types": "./dist/cookies/index.d.ts",
@@ -62,27 +77,53 @@
       "types": "./dist/search-params/index.d.ts",
       "import": "./dist/search-params/index.js"
     },
-    "./routing": {
-      "types": "./dist/routing/index.d.ts",
-      "import": "./dist/routing/index.js"
+    "./segment-params": {
+      "types": "./dist/segment-params/index.d.ts",
+      "import": "./dist/segment-params/index.js"
+    },
+    "./params": {
+      "types": "./dist/params/index.d.ts",
+      "import": "./dist/params/index.js"
     },
     "./adapters/cloudflare": {
       "types": "./dist/adapters/cloudflare.d.ts",
       "import": "./dist/adapters/cloudflare.js"
     },
+    "./adapters/cloudflare/cache": {
+      "types": "./dist/adapters/cloudflare-kv-cache.d.ts",
+      "import": "./dist/adapters/cloudflare-kv-cache.js"
+    },
+    "./adapters/cloudflare/dev": {
+      "types": "./dist/adapters/cloudflare-dev.d.ts",
+      "import": "./dist/adapters/cloudflare-dev.js"
+    },
     "./adapters/nitro": {
       "types": "./dist/adapters/nitro.d.ts",
       "import": "./dist/adapters/nitro.js"
     },
+    "./fonts/google": {
+      "types": "./dist/shims/font-google.d.ts",
+      "import": "./dist/shims/font-google.js"
+    },
+    "./fonts/local": {
+      "types": "./dist/shims/font-local.d.ts",
+      "import": "./dist/shims/font-local.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist",
+    "typecheck": "tsgo --noEmit",
+    "prepublishOnly": "pnpm run build"
+  },
   "dependencies": {
-    "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/context-async-hooks": "^2.6.0",
-    "@opentelemetry/sdk-trace-base": "^2.6.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/context-async-hooks": "^2.6.1",
+    "@opentelemetry/sdk-trace-base": "^2.6.1",
+    "magic-string": "^0.30.21",
     "nitro": "3.0.260311-beta"
   },
   "peerDependencies": {
@@ -93,9 +134,10 @@
     "@vitejs/plugin-react": "^6.0.0",
     "@vitejs/plugin-rsc": ">=0.5.21",
     "nuqs": "^2.0.0",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
-    "vite": "^8.0.1",
+    "react": "19.3.0-canary-ed69815c-20260323",
+    "react-dom": "19.3.0-canary-ed69815c-20260323",
+    "vite": "^8.0.3",
+    "wrangler": "^4.0.0",
     "zod": "^3.22.0 || ^4.0.0"
   },
   "peerDependenciesMeta": {
@@ -111,15 +153,14 @@
     "@mdx-js/rollup": {
       "optional": true
     },
+    "wrangler": {
+      "optional": true
+    },
     "zod": {
       "optional": true
     }
   },
   "engines": {
-    "node": ">=20.0.0"
-  },
-  "scripts": {
-    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist",
-    "typecheck": "tsgo --noEmit"
+    "node": ">=22.12.0"
   }
-}
+}

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

@@ -0,0 +1,77 @@
+// Shared build-output helper for adapter buildOutput() methods.
+//
+// Steps 1–5 of every adapter's buildOutput are platform-agnostic:
+//   1. Copy client assets to the public/static directory
+//   2. Write _headers file for static asset cache control
+//   3. Copy RSC + SSR server bundles
+//   4. Write manifest-init module (if present)
+//
+// Only the final steps (entry codegen, platform config) vary per adapter.
+//
+// IMPORTANT: This module must remain a leaf — no imports from ../server/,
+// ../client/, or Vite-dependent code. See adapters/shared.ts header.
+
+import { writeFile, mkdir, cp } from 'node:fs/promises';
+import { join } from 'node:path';
+import { generateHeadersFile } from './shared.js';
+import type { TimberConfig } from './types';
+
+/** Options for the shared build output steps. */
+export interface BuildOutputBaseOptions {
+  /** Resolved timber config. */
+  config: TimberConfig;
+  /** Root build directory (e.g. `.timber/build`). */
+  buildDir: string;
+  /** Adapter-specific output directory (e.g. `.timber/build/nitro`). */
+  outDir: string;
+  /**
+   * Name of the public/static directory within outDir.
+   * Nitro uses 'public', Cloudflare uses 'static'.
+   */
+  publicDirName: string;
+}
+
+/**
+ * Run the platform-agnostic build output steps shared by all adapters:
+ *
+ * 1. Create the output directory
+ * 2. Copy client assets to the public/static directory
+ * 3. Write the `_headers` file for static asset cache control
+ * 4. Copy RSC and SSR server bundles into the output directory
+ * 5. Write the manifest-init module if present
+ *
+ * Returns the resolved public directory path for further adapter-specific use.
+ */
+export async function runSharedBuildSteps(opts: BuildOutputBaseOptions): Promise<string> {
+  const { config, buildDir, outDir, publicDirName } = opts;
+
+  // 1. Create the output directory.
+  await mkdir(outDir, { recursive: true });
+
+  // 2. Copy client assets to public/static 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, publicDirName);
+  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
+  });
+
+  // 3. Write _headers file for static asset cache control.
+  await writeFile(join(publicDir, '_headers'), generateHeadersFile());
+
+  // 4. Copy RSC + SSR server bundles into the output directory.
+  await cp(join(buildDir, 'rsc'), join(outDir, 'rsc'), { recursive: true });
+  await cp(join(buildDir, 'ssr'), join(outDir, 'ssr'), { recursive: true }).catch(() => {});
+
+  // 5. Write manifest-init module if present.
+  if (config.manifestInit) {
+    await writeFile(join(outDir, '_timber-manifest-init.js'), config.manifestInit);
+  }
+
+  return publicDir;
+}

package/src/adapters/cloudflare-dev.ts

@@ -0,0 +1,177 @@
+/**
+ * Cloudflare dev-mode bindings via wrangler's getPlatformProxy().
+ *
+ * This Vite plugin starts a local workerd process (via Miniflare) that
+ * emulates Cloudflare bindings (KV, D1, R2, Queues, Durable Objects, etc.)
+ * during development. The proxy env is injected into the request ALS so
+ * `getCloudflareBindings()` works identically in dev and production.
+ *
+ * Design doc: design/35-cloudflare-primitives.md §"Dev Experience"
+ *
+ * Usage:
+ * ```ts
+ * // vite.config.ts
+ * import { timber } from '@timber-js/app'
+ * import { cloudflare } from '@timber-js/app/adapters/cloudflare'
+ * import { cloudflareDevBindings } from '@timber-js/app/adapters/cloudflare/dev'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     timber({ adapter: cloudflare() }),
+ *     cloudflareDevBindings(),
+ *   ],
+ * })
+ * ```
+ *
+ * Requires `wrangler` as a dev dependency. Install it:
+ * ```bash
+ * pnpm add -D wrangler
+ * ```
+ */
+
+import type { Plugin, ViteDevServer } from 'vite';
+import { runWithBindings } from './cloudflare.js';
+
+/**
+ * Dynamically import wrangler. Extracted as a named export so tests
+ * can mock it without needing wrangler installed.
+ * @internal
+ */
+export async function loadWrangler(): Promise<{ getPlatformProxy: (opts: any) => Promise<any> }> {
+  try {
+    return await import('wrangler');
+  } catch {
+    throw new Error(
+      '[timber] Could not import wrangler. ' +
+        'cloudflareDevBindings() requires wrangler as a dev dependency.\n' +
+        'Install it: pnpm add -D wrangler'
+    );
+  }
+}
+
+// ─── Contract ─────────────────────────────────────────────────────────────
+//
+// The dev request wrapper is stored on the ViteDevServer instance using a
+// well-known Symbol. This allows cross-plugin communication without import
+// dependencies — the dev-server plugin checks for this Symbol per-request
+// and wraps the handler call when present.
+//
+// The wrapper type is: <T>(fn: () => T) => T
+// It runs `fn` inside the Cloudflare bindings ALS so getCloudflareBindings()
+// works throughout the request lifecycle.
+
+/**
+ * Symbol key used to store the dev request wrapper on ViteDevServer.
+ *
+ * @internal Exported for testing. The dev-server plugin uses
+ * `Symbol.for('timber:dev-request-wrapper')` directly to avoid
+ * importing from this module.
+ */
+export const DEV_REQUEST_WRAPPER_KEY = Symbol.for('timber:dev-request-wrapper');
+
+/** Options for the Cloudflare dev bindings plugin. */
+export interface CloudflareDevBindingsOptions {
+  /**
+   * Path to the wrangler configuration file.
+   * @default Auto-detected by wrangler (wrangler.jsonc, wrangler.json, wrangler.toml)
+   */
+  configPath?: string;
+
+  /**
+   * Whether to persist binding data (KV, D1, R2) between dev server restarts.
+   *
+   * - `true` — persist in wrangler's default location (`.wrangler/state/`)
+   * - `{ path: string }` — persist in a custom directory
+   * - `false` — start fresh on every restart
+   *
+   * @default true
+   */
+  persist?: boolean | { path: string };
+
+  /**
+   * Wrangler environment to use (for multi-environment configs).
+   * Maps to `[env.<name>]` sections in wrangler.toml / wrangler.jsonc.
+   */
+  environment?: string;
+
+  /**
+   * @internal Override the wrangler loader for testing.
+   * Not part of the public API — may change without notice.
+   */
+  _loadWrangler?: () => Promise<{ getPlatformProxy: (opts: any) => Promise<any> }>;
+}
+
+/**
+ * Vite plugin that provides Cloudflare bindings in dev mode via
+ * wrangler's `getPlatformProxy()`.
+ *
+ * Starts a local workerd process on dev server startup and injects
+ * the proxy env into the per-request ALS. This makes
+ * `getCloudflareBindings()` return real (emulated) bindings during
+ * development — KV, D1, R2, Queues, Durable Objects, and all other
+ * bindings declared in wrangler.jsonc.
+ *
+ * The proxy is automatically disposed when the dev server closes.
+ *
+ * **Requirements:**
+ * - `wrangler` installed as a dev dependency
+ * - A `wrangler.jsonc` (or `wrangler.toml`) with binding declarations
+ *
+ * @example
+ * ```ts
+ * import { cloudflareDevBindings } from '@timber-js/app/adapters/cloudflare/dev'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     timber({ adapter: cloudflare() }),
+ *     cloudflareDevBindings(),
+ *   ],
+ * })
+ * ```
+ */
+export function cloudflareDevBindings(options: CloudflareDevBindingsOptions = {}): Plugin {
+  return {
+    name: 'timber-cloudflare-dev-bindings',
+
+    // Dev mode only — never active during production builds.
+    // See design/35-cloudflare-primitives.md §"Security Considerations":
+    // "Dev bindings are dev-only. apply: 'serve' ensures it never runs
+    //  in production builds."
+    apply: 'serve',
+
+    async configureServer(server: ViteDevServer) {
+      // Dynamic import — wrangler is an optional peer dependency.
+      // Users must install it themselves: `pnpm add -D wrangler`
+      const { getPlatformProxy } = await (options._loadWrangler ?? loadWrangler)();
+
+      // Build getPlatformProxy options from our public API.
+      const proxyOptions: Record<string, unknown> = {
+        persist: options.persist ?? true,
+      };
+      if (options.configPath) {
+        proxyOptions.configPath = options.configPath;
+      }
+      if (options.environment) {
+        proxyOptions.environment = options.environment;
+      }
+
+      const proxy = await getPlatformProxy(proxyOptions);
+
+      // Store a request wrapper on the server instance. The dev-server
+      // plugin checks for this Symbol per-request and wraps the RSC
+      // handler call so getCloudflareBindings() works throughout the
+      // request lifecycle (server components, middleware, server actions).
+      (server as any)[DEV_REQUEST_WRAPPER_KEY] = <T>(fn: () => T): T => {
+        return runWithBindings(proxy.env as Record<string, unknown>, fn);
+      };
+
+      // Dispose the proxy when the dev server closes. This shuts down
+      // the local workerd process started by getPlatformProxy().
+      server.httpServer?.on('close', () => {
+        proxy.dispose().catch(() => {
+          // Disposal errors are non-fatal — the process is shutting down.
+        });
+      });
+    },
+  };
+}

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

@@ -0,0 +1,142 @@
+import type { CacheHandler } from '../cache/index';
+import { getCloudflareBindings } from './cloudflare';
+
+/**
+ * Cloudflare Workers KV interface — the subset of KVNamespace we depend on.
+ * Users don't need to import this; the handler resolves the binding internally
+ * via `getCloudflareBindings()`.
+ */
+export interface CloudflareKVNamespace {
+  get(key: string, options: { type: 'json' }): Promise<unknown>;
+  get(key: string, options?: { type?: string }): Promise<string | null>;
+  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+interface KVCacheEntry {
+  value: unknown;
+  tags: string[];
+  expiresAt: number;
+}
+
+/**
+ * Cloudflare Workers KV–backed CacheHandler.
+ *
+ * Uses tag index keys for tag-based invalidation (KV has no secondary indexes).
+ * Stores entries with 2× TTL so stale entries survive for `staleWhileRevalidate`
+ * reads. The logical staleness is determined by the `expiresAt` timestamp inside
+ * the entry payload.
+ *
+ * **Consistency:** KV is eventually consistent (~60s propagation). TTL is the
+ * primary expiry mechanism. Tag invalidation is best-effort — do not rely on it
+ * for security-critical cache purging (use short TTLs instead).
+ *
+ * ```ts
+ * // timber.config.ts
+ * import { CloudflareKVCacheHandler } from '@timber-js/app/adapters/cloudflare/cache';
+ *
+ * export default {
+ *   cacheHandler: new CloudflareKVCacheHandler({ bindingName: 'TIMBER_CACHE' }),
+ * };
+ * ```
+ */
+export class CloudflareKVCacheHandler implements CacheHandler {
+  private bindingName: string;
+  private prefix: string;
+
+  constructor(options: { bindingName: string; prefix?: string }) {
+    this.bindingName = options.bindingName;
+    this.prefix = options.prefix ?? 'tc:';
+  }
+
+  /** Resolve the KV binding from the current request's Cloudflare env. */
+  private getKV(): CloudflareKVNamespace {
+    const env = getCloudflareBindings<Record<string, CloudflareKVNamespace>>();
+    const kv = env[this.bindingName];
+    if (!kv) {
+      throw new Error(
+        `CloudflareKVCacheHandler: binding "${this.bindingName}" not found. ` +
+          'Check your wrangler.jsonc kv_namespaces configuration.'
+      );
+    }
+    return kv;
+  }
+
+  private dataKey(key: string): string {
+    return `${this.prefix}d:${key}`;
+  }
+
+  private tagKey(tag: string): string {
+    return `${this.prefix}t:${tag}`;
+  }
+
+  async get(key: string): Promise<{ value: unknown; stale: boolean } | null> {
+    const kv = this.getKV();
+    const raw = await kv.get(this.dataKey(key), { type: 'json' });
+    if (!raw) return null;
+
+    const entry = raw as KVCacheEntry;
+    const stale = Date.now() > entry.expiresAt;
+    return { value: entry.value, stale };
+  }
+
+  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void> {
+    const kv = this.getKV();
+    const entry: KVCacheEntry = {
+      value,
+      tags: opts.tags,
+      expiresAt: Date.now() + opts.ttl * 1000,
+    };
+
+    // KV expirationTtl minimum is 60s. Use 2× TTL (min 60s) so stale entries
+    // survive for staleWhileRevalidate background refetches.
+    const kvTtl = Math.max(opts.ttl * 2, 60);
+    await kv.put(this.dataKey(key), JSON.stringify(entry), { expirationTtl: kvTtl });
+
+    // Update tag indexes (best-effort, eventually consistent).
+    // Tag indexes have no TTL — cleaned up on invalidation.
+    await Promise.all(
+      opts.tags.map(async (tag) => {
+        const existing = (await kv.get(this.tagKey(tag), { type: 'json' })) as string[] | null;
+        const keys: string[] = Array.isArray(existing) ? existing : [];
+        if (!keys.includes(key)) {
+          keys.push(key);
+          await kv.put(this.tagKey(tag), JSON.stringify(keys));
+        }
+      })
+    );
+  }
+
+  async invalidate(opts: { key?: string; tag?: string }): Promise<void> {
+    const kv = this.getKV();
+
+    if (opts.key) {
+      // Read entry to find its tags, then clean up tag indexes
+      const raw = (await kv.get(this.dataKey(opts.key), { type: 'json' })) as KVCacheEntry | null;
+      if (raw) {
+        await Promise.all(
+          raw.tags.map(async (tag) => {
+            const existing = (await kv.get(this.tagKey(tag), { type: 'json' })) as string[] | null;
+            if (Array.isArray(existing)) {
+              const filtered = existing.filter((k: string) => k !== opts.key);
+              if (filtered.length > 0) {
+                await kv.put(this.tagKey(tag), JSON.stringify(filtered));
+              } else {
+                await kv.delete(this.tagKey(tag));
+              }
+            }
+          })
+        );
+      }
+      await kv.delete(this.dataKey(opts.key));
+    }
+
+    if (opts.tag) {
+      const existing = (await kv.get(this.tagKey(opts.tag), { type: 'json' })) as string[] | null;
+      if (Array.isArray(existing)) {
+        await Promise.all(existing.map((key: string) => kv.delete(this.dataKey(key))));
+      }
+      await kv.delete(this.tagKey(opts.tag));
+    }
+  }
+}