@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.2",
-  "description": "Vite-native React framework for Cloudflare Workers — correct HTTP semantics, real status codes, pages that work without JavaScript",
+  "version": "0.2.0-alpha.200",
+  "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",
@@ -26,12 +26,27 @@
     "dist",
     "src",
     "bin",
+    "docs",
+    "agent-skill.md",
+    "llms.txt",
     "README.md",
     "LICENSE"
   ],
   "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"
+    },
+    "#server-only-guard": "./src/server/server-only-guard-noop.js"
   },
   "exports": {
     ".": {
@@ -46,13 +61,49 @@
       "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"
+    "./cache/stores/memory": {
+      "types": "./dist/cache/stores/memory.d.ts",
+      "import": "./dist/cache/stores/memory.js"
+    },
+    "./cache/stores/redis": {
+      "types": "./dist/cache/stores/redis.d.ts",
+      "import": "./dist/cache/stores/redis.js"
+    },
+    "./cache/stores/cloudflare-kv": {
+      "types": "./dist/cache/stores/cloudflare-kv.d.ts",
+      "import": "./dist/cache/stores/cloudflare-kv.js"
+    },
+    "./cache/stores/vercel": {
+      "types": "./dist/cache/stores/vercel.d.ts",
+      "import": "./dist/cache/stores/vercel.js"
+    },
+    "./cdn": {
+      "types": "./dist/cdn/index.d.ts",
+      "import": "./dist/cdn/index.js"
+    },
+    "./cdn/cloudflare": {
+      "types": "./dist/cdn/cloudflare-purge.d.ts",
+      "import": "./dist/cdn/cloudflare-purge.js"
+    },
+    "./cdn/cloudflare-workers": {
+      "types": "./dist/cdn/workers-cache-purge.d.ts",
+      "import": "./dist/cdn/workers-cache-purge.js"
+    },
+    "./cdn/fastly": {
+      "types": "./dist/cdn/fastly-purge.d.ts",
+      "import": "./dist/cdn/fastly-purge.js"
+    },
+    "./codec": {
+      "types": "./dist/codec.d.ts",
+      "import": "./dist/codec.js"
     },
     "./cookies": {
       "types": "./dist/cookies/index.d.ts",
@@ -62,45 +113,65 @@
       "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"
+    "./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.11.0",
+    "@opentelemetry/sdk-trace-base": "^2.11.0",
+    "cookie": "^2.0.1",
+    "jsonc-parser": "^3.3.1",
+    "magic-string": "^1.3.1",
+    "nitro": "3.0.260903-beta",
+    "oxc-transform-react": "^0.150.0",
+    "srvx": "^1.0.5"
   },
   "peerDependencies": {
-    "@content-collections/core": "^0.14.0",
+    "@content-collections/core": "^0.14.0 || ^0.15.0",
     "@content-collections/mdx": "^0.2.0",
-    "@content-collections/vite": "^0.2.0",
-    "@mdx-js/rollup": "^3.0.0",
-    "@vitejs/plugin-react": "^6.0.0",
-    "@vitejs/plugin-rsc": ">=0.5.21",
+    "@content-collections/vite": "^0.2.0 || ^0.3.0",
+    "@typescript/native-preview": "^7.0.0-dev.0",
+    "@vitejs/plugin-react": "^6.1.0",
+    "@vitejs/plugin-rsc": ">=0.5.28",
     "nuqs": "^2.0.0",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
-    "vite": "^8.0.1",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "react-server-dom-webpack": "19.3.0",
+    "satteri": "^0.9.5",
+    "vite": "8.3.0",
+    "vite-plugin-satteri": "^0.2.15",
+    "wrangler": "^4.0.0",
     "zod": "^3.22.0 || ^4.0.0"
   },
   "peerDependenciesMeta": {
@@ -113,14 +184,31 @@
     "@content-collections/vite": {
       "optional": true
     },
-    "@mdx-js/rollup": {
+    "satteri": {
+      "optional": true
+    },
+    "vite-plugin-satteri": {
+      "optional": true
+    },
+    "@typescript/native-preview": {
+      "optional": true
+    },
+    "wrangler": {
       "optional": true
     },
     "zod": {
       "optional": true
     }
   },
+  "devDependencies": {
+    "@typescript/native-preview": "7.0.0-dev.20260707.2"
+  },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "copy-docs": "node scripts/copy-docs.js",
+    "build": "vite build --config vite.lib.config.ts && node scripts/build-types.js && pnpm run copy-docs",
+    "typecheck": "tsgo --noEmit"
   }
-}
+}

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

@@ -0,0 +1,351 @@
+// 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, rm, readdir, readFile } from 'node:fs/promises';
+import { join, basename, relative } from 'node:path';
+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 {
+  HEADERS_FILE,
+  USER_MERGED_PLATFORM_FILES,
+  USER_PLATFORM_DIR,
+} from '../shared/static-platform-files.ts';
+import { detectFsIdentity, fsKey } from './fs-identity.ts';
+import type { TimberConfig } from './types.ts';
+
+/** 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.
+  // Scan for unhashed files so they get per-file Cache-Control rules in the
+  // _headers file. On platforms like Cloudflare Workers Static Assets, the
+  // worker never sees static file requests — _headers is the only mechanism.
+  await writeHeadersFile(publicDir, config, await findUnhashedStaticFiles(publicDir));
+
+  // 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;
+    }
+  );
+
+  // 4b. Copy prebuilt/ flight payloads if present (cache.component artifacts).
+  // These are produced by the post-build capture pass (design/44) and read
+  // at request time via the adapter's PrebuiltPayloadSource.
+  await cp(join(buildDir, 'prebuilt'), join(outDir, 'prebuilt'), { recursive: true }).catch(
+    (e: NodeJS.ErrnoException) => {
+      // No prebuilt dir when the app has no cache.component calls
+      if (e.code !== 'ENOENT') throw e;
+    }
+  );
+
+  // 5. Write manifest-init module if present.
+  if (config.manifestInit) {
+    await writeFile(join(outDir, '_timber-manifest-init.js'), config.manifestInit);
+  }
+
+  return publicDir;
+}
+
+/**
+ * Find unhashed static files in the public directory that need per-file
+ * Cache-Control rules in the `_headers` file.
+ *
+ * Excludes:
+ * - Files under `assets/` and `_timber/` (covered by wildcard rules)
+ * - Underscore-prefixed files (`_headers`, `_worker.js`, etc.)
+ *
+ * @internal Exported for testing.
+ */
+// Well-known metadata files that should be prioritized when capping
+// _headers rules, so they're never dropped in favor of less important files.
+const PRIORITY_FILES = new Set([
+  '/favicon.ico',
+  '/robots.txt',
+  '/sitemap.xml',
+  '/manifest.json',
+  '/manifest.webmanifest',
+  '/apple-touch-icon.png',
+]);
+
+export async function findUnhashedStaticFiles(publicDir: string): Promise<string[]> {
+  let files: string[];
+  try {
+    files = await collectFiles(publicDir);
+  } catch {
+    return [];
+  }
+
+  const priority: string[] = [];
+  const rest: string[] = [];
+  for (const file of files) {
+    const rel = relative(publicDir, file).replace(/\\/g, '/');
+    if (rel.startsWith('assets/') || rel.startsWith('_timber/')) continue;
+    if (rel.startsWith('rsc/') || rel.startsWith('ssr/') || rel.startsWith('_rsc/')) continue;
+    if (basename(rel).startsWith('_')) continue;
+    const urlPath = '/' + rel;
+    if (PRIORITY_FILES.has(urlPath)) {
+      priority.push(urlPath);
+    } else {
+      rest.push(urlPath);
+    }
+  }
+
+  return [...priority.sort(), ...rest.sort()];
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Build a static-only output directory (no server entry). Copies client
+ * assets and pre-rendered HTML/RSC/API files into `outDir/publicDirName`.
+ * Used by both Cloudflare and Nitro adapters in `output: 'static'` mode.
+ */
+export async function buildStaticDirectoryOutput(
+  config: TimberConfig,
+  buildDir: string,
+  outDir: string,
+  publicDirName: string
+): Promise<void> {
+  // Clean stale artifacts from prior builds (e.g. server-mode builds that
+  // left rsc/, ssr/, _worker.js in the outDir). Without this, a static
+  // build after a server build inherits 140+ unused server chunks.
+  await rm(outDir, { recursive: true, force: true }).catch(() => {});
+  await mkdir(outDir, { recursive: true });
+
+  const publicDir = join(outDir, publicDirName);
+  await mkdir(publicDir, { recursive: true });
+
+  // Copy client assets (JS, CSS, fonts, images).
+  const clientDir = join(buildDir, 'client');
+  await cp(clientDir, publicDir, {
+    recursive: true,
+    filter: (src: string) => {
+      if (config.clientJavascriptDisabled && src.endsWith('.js')) return false;
+      return true;
+    },
+  }).catch((e: NodeJS.ErrnoException) => {
+    if (e.code !== 'ENOENT') throw e;
+  });
+
+  // Copy pre-rendered static pages (HTML + RSC flight + API routes).
+  //
+  // This is the one place the build merges two independently-produced trees
+  // into a single directory, and `cp` resolves an overlap by overwriting with
+  // no diagnostic — the deployment then contains one of the two artifacts and
+  // nothing recorded which. Refuse instead (TIM-1266).
+  if (config.staticPagesDir) {
+    await assertNoTreeCollision(config.staticPagesDir, publicDir);
+    await cp(config.staticPagesDir, publicDir, { recursive: true });
+  }
+}
+
+/**
+ * Write the `_headers` file, folding in the user's `public/_headers`.
+ *
+ * Every adapter used to `writeFile` a generated `_headers` over whatever
+ * Vite had copied out of `public/`, so an app shipping its own CSP, CORS, or
+ * cache rules deployed without them and without a word (TIM-1326). The
+ * generated rules and the user's are not competitors — they address different
+ * paths — so this merges rather than refusing, the way `_redirects` has since
+ * TIM-1249.
+ *
+ * **Read from the project, not the output.** The generated file lands under
+ * the same name in the output directory, and `runSharedBuildSteps` does not
+ * clean `outDir`; a reader aimed there would fold the previous build's
+ * generated rules back in and compound them on every rebuild — the defect
+ * this pass fixed for `_redirects`.
+ *
+ * User rules go last. On Cloudflare and Netlify a `_headers` file applies
+ * every matching rule, so appending means the user's rules take effect; where
+ * a platform resolves a conflict in favour of the earlier rule instead, the
+ * framework keeps the paths it owns and the user keeps the rest. Under either
+ * reading this is no worse than the previous behaviour, which was to drop the
+ * user's rules entirely.
+ *
+ * @internal Exported for testing.
+ */
+export async function writeHeadersFile(
+  dir: string,
+  config: TimberConfig,
+  unhashedPaths: string[]
+): Promise<void> {
+  const userRules = await readUserPlatformFile(config.root, HEADERS_FILE);
+  await writeFile(
+    join(dir, HEADERS_FILE),
+    generateHeadersFile({
+      base: adapterBase(config),
+      unhashedPaths,
+      contentTypes: config.staticContentTypes,
+      userRules: userRules ?? undefined,
+    })
+  );
+}
+
+/**
+ * Read a user-authored platform file from the project's `public/` directory.
+ * Returns null when the project has none, or when no root is configured —
+ * a caller without a root cannot locate the project at all, and inventing
+ * one from `process.cwd()` would read a different project's file.
+ */
+async function readUserPlatformFile(
+  root: string | undefined,
+  name: string
+): Promise<string | null> {
+  if (!root) return null;
+  try {
+    return await readFile(join(root, USER_PLATFORM_DIR, name), 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Throw if copying `srcDir` over `destDir` would overwrite an existing file.
+ *
+ * Compared against the destination **as it stands**, not against the other
+ * source tree: the first copy is filtered (client JS is dropped when client
+ * JavaScript is disabled), so the files that are actually there are the only
+ * ones a second copy can clobber.
+ *
+ * @internal Exported for testing.
+ */
+export async function assertNoTreeCollision(srcDir: string, destDir: string): Promise<void> {
+  const [srcFiles, destFiles, identity] = await Promise.all([
+    collectFiles(srcDir).catch(() => [] as string[]),
+    collectFiles(destDir).catch(() => [] as string[]),
+    // `cp` will resolve these paths the way the destination filesystem does,
+    // so the comparison predicting it has to as well: on macOS a hand-written
+    // `public/About/index.html` and a generated `about/index.html` are one
+    // file, and an exact-string set waves the overwrite through (TIM-1266).
+    detectFsIdentity(destDir),
+  ]);
+
+  const key = (p: string) => fsKey(p, identity);
+  const existing = new Set(destFiles.map((f) => key(relative(destDir, f).replace(/\\/g, '/'))));
+  const exempt = new Set(USER_MERGED_PLATFORM_FILES.map(key));
+  const collisions = srcFiles
+    .map((f) => relative(srcDir, f).replace(/\\/g, '/'))
+    .filter((rel) => existing.has(key(rel)) && !exempt.has(key(rel)))
+    .sort();
+
+  if (collisions.length === 0) return;
+
+  throw new Error(
+    `[timber] Build output: ${collisions.length} file(s) in the pre-rendered site ` +
+      `collide with files already in the output directory. Copying would silently ` +
+      `overwrite them — a generated page and a file in public/ cannot share a path:\n` +
+      collisions.map((c) => `  - ${c}`).join('\n')
+  );
+}
+
+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;
+}