@timber-js/app 0.2.0-alpha.15 → 0.2.0-alpha.150

package/dist/utils/state-machine.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Tiny typed state machine utility.
+ *
+ * Enforces discriminated-union states, typed transitions with runtime
+ * guards, subscribe for external store integration, and assertPhase
+ * for function entry guards.
+ *
+ * Designed for 3–5 state consumers (stream transforms, client navigation,
+ * build phase sequencing). No async, no hierarchy, no history.
+ *
+ * Performance: send() is one object lookup + one function call.
+ * Equivalent cost to a boolean check after V8 inlining.
+ */
+/** A state machine instance with typed state and events. */
+export interface Machine<TState extends {
+    phase: string;
+}, TEvent extends {
+    type: string;
+}> {
+    /** Current state (discriminated union — narrowed by phase). */
+    readonly state: TState;
+    /** Transition with runtime guard. Throws on invalid source+event pair. */
+    send(event: TEvent): void;
+    /** Subscribe to state changes. Returns unsubscribe function. */
+    subscribe(listener: (state: TState) => void): () => void;
+    /** Throw if not in the expected phase. Entry guard for functions. */
+    assertPhase<P extends TState['phase']>(phase: P): void;
+}
+/**
+ * Transition map: `transitions[phase][eventType]` returns the next state.
+ *
+ * Each handler receives the current state (narrowed by phase context)
+ * and the event, returning the new state.
+ */
+export type TransitionMap<TState extends {
+    phase: string;
+}, TEvent extends {
+    type: string;
+}> = {
+    [P in TState['phase']]?: {
+        [E in TEvent['type']]?: (state: Extract<TState, {
+            phase: P;
+        }>, event: Extract<TEvent, {
+            type: E;
+        }>) => TState;
+    };
+};
+export interface MachineConfig<TState extends {
+    phase: string;
+}, TEvent extends {
+    type: string;
+}> {
+    initial: TState;
+    transitions: TransitionMap<TState, TEvent>;
+    /** Fires after every valid transition. Use for side effects. */
+    onTransition?: (prev: TState, next: TState, event: TEvent) => void;
+}
+/**
+ * Create a state machine from a config.
+ *
+ * @example
+ * ```ts
+ * type State = { phase: 'idle' } | { phase: 'running'; pid: number };
+ * type Event = { type: 'START'; pid: number } | { type: 'STOP' };
+ *
+ * const m = createMachine<State, Event>({
+ *   initial: { phase: 'idle' },
+ *   transitions: {
+ *     idle: { START: (_s, e) => ({ phase: 'running', pid: e.pid }) },
+ *     running: { STOP: () => ({ phase: 'idle' }) },
+ *   },
+ * });
+ * ```
+ */
+export declare function createMachine<TState extends {
+    phase: string;
+}, TEvent extends {
+    type: string;
+}>(config: MachineConfig<TState, TEvent>): Machine<TState, TEvent>;
+//# sourceMappingURL=state-machine.d.ts.map

package/dist/utils/state-machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.d.ts","sourceRoot":"","sources":["../../src/utils/state-machine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,4DAA4D;AAC5D,MAAM,WAAW,OAAO,CAAC,MAAM,SAAS;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;IACxF,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,0EAA0E;IAC1E,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1B,gEAAgE;IAChE,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAEzD,qEAAqE;IACrE,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;CACxD;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,MAAM,SAAS;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,IAAI;KAC5F,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;SACtB,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CACtB,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE;YAAE,KAAK,EAAE,CAAC,CAAA;SAAE,CAAC,EACpC,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE;YAAE,IAAI,EAAE,CAAC,CAAA;SAAE,CAAC,KAChC,MAAM;KACZ;CACF,CAAC;AAEF,MAAM,WAAW,aAAa,CAAC,MAAM,SAAS;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;IAC9F,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,gEAAgE;IAChE,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACpE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,MAAM,SAAS;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAC7F,MAAM,EAAE,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,GACpC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAwCzB"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.15",
-  "description": "Vite-native React framework for Cloudflare Workers — correct HTTP semantics, real status codes, pages that work without JavaScript",
+  "version": "0.2.0-alpha.150",
+  "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,33 +77,49 @@
       "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",
-    "nitro": "3.0.260311-beta"
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/context-async-hooks": "^2.7.1",
+    "@opentelemetry/sdk-trace-base": "^2.7.1",
+    "magic-string": "^0.30.21",
+    "nitro": "3.0.260603-beta"
   },
   "peerDependencies": {
     "@content-collections/core": "^0.14.0",
@@ -96,11 +127,12 @@
     "@content-collections/vite": "^0.2.0",
     "@mdx-js/rollup": "^3.0.0",
     "@vitejs/plugin-react": "^6.0.0",
-    "@vitejs/plugin-rsc": ">=0.5.21",
+    "@vitejs/plugin-rsc": ">=0.5.27",
     "nuqs": "^2.0.0",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
-    "vite": "^8.0.1",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "vite": "^8.0.16",
+    "wrangler": "^4.0.0",
     "zod": "^3.22.0 || ^4.0.0"
   },
   "peerDependenciesMeta": {
@@ -116,11 +148,18 @@
     "@mdx-js/rollup": {
       "optional": true
     },
+    "wrangler": {
+      "optional": true
+    },
     "zod": {
       "optional": true
     }
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist",
+    "typecheck": "tsgo --noEmit"
   }
-}
+}

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

@@ -0,0 +1,139 @@
+// 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, readdir, readFile } from 'node:fs/promises';
+import { join, basename } 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 });
+  // Find WASM files that are referenced by client JS (legitimate client WASM)
+  // vs orphaned server-only WASM (e.g. @takumi-rs for OG image generation).
+  // Only strip orphaned WASM to avoid breaking client-side WASM usage.
+  const referencedWasm = await findReferencedWasm(clientDir);
+
+  await cp(clientDir, publicDir, {
+    recursive: true,
+    filter: (src: string) => {
+      if (src.endsWith('.wasm') && !referencedWasm.has(basename(src))) {
+        return false;
+      }
+      if (config.clientJavascriptDisabled && src.endsWith('.js')) return false;
+      return true;
+    },
+  }).catch((e: NodeJS.ErrnoException) => {
+    // Client dir may not exist when client JavaScript is disabled
+    if (e.code !== 'ENOENT') throw e;
+  });
+
+  // 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(
+    (e: NodeJS.ErrnoException) => {
+      // SSR dir may not exist for static-only builds
+      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);
+  }
+
+  return publicDir;
+}
+
+/**
+ * Scan client JS files for references to .wasm filenames.
+ * Returns the set of WASM basenames that are actually imported/referenced
+ * by client code and must be preserved in the static output.
+ */
+async function findReferencedWasm(clientDir: string): Promise<Set<string>> {
+  const referenced = new Set<string>();
+
+  let files: string[];
+  try {
+    files = await collectFiles(clientDir);
+  } catch {
+    return referenced;
+  }
+
+  const jsFiles = files.filter((f) => f.endsWith('.js'));
+  const wasmFiles = files.filter((f) => f.endsWith('.wasm')).map((f) => basename(f));
+  if (wasmFiles.length === 0) return referenced;
+
+  for (const jsFile of jsFiles) {
+    const content = await readFile(jsFile, 'utf-8');
+    for (const wasmName of wasmFiles) {
+      if (content.includes(wasmName)) {
+        referenced.add(wasmName);
+      }
+    }
+  }
+
+  return referenced;
+}
+
+async function collectFiles(dir: string): Promise<string[]> {
+  const result: string[] = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      result.push(...(await collectFiles(fullPath)));
+    } else {
+      result.push(fullPath);
+    }
+  }
+  return result;
+}

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.
+        });
+      });
+    },
+  };
+}