@timber-js/app 0.2.0-alpha.155 → 0.2.0-alpha.156

package/dist/server/pipeline-phases.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline-phases.d.ts","sourceRoot":"","sources":["../../src/server/pipeline-phases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAoBH,OAAO,EAA2C,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEpG,OAAO,EAAqB,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAKrF,UAAU,aAAa;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAwBD;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,aAAa,EACvB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,YAAY,CAAC,CAmBvB;AAID;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,oBAAoB,EAAE,OAAO,EAC7B,aAAa,EAAE,aAAa,GAC3B,OAAO,CAAC,YAAY,CAAC,CA6DvB;AAID;;;GAGG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,oBAAoB,EAAE,OAAO,EAC7B,EAAE,iBAAiB,EAAE,YAAY,EAAE,EAAE,aAAa,GACjD,OAAO,CAAC,YAAY,CAAC,CAkBvB;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,OAAO,GACxB,OAAO,CAAC,QAAQ,CAAC,CAwSnB"}
+{"version":3,"file":"pipeline-phases.d.ts","sourceRoot":"","sources":["../../src/server/pipeline-phases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAoBH,OAAO,EAA2C,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEpG,OAAO,EAAqB,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAKrF,UAAU,aAAa;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAwBD;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,aAAa,EACvB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,YAAY,CAAC,CAmBvB;AAID;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,oBAAoB,EAAE,OAAO,EAC7B,aAAa,EAAE,aAAa,GAC3B,OAAO,CAAC,YAAY,CAAC,CA6DvB;AAID;;;GAGG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,oBAAoB,EAAE,OAAO,EAC7B,EAAE,iBAAiB,EAAE,YAAY,EAAE,EAAE,aAAa,GACjD,OAAO,CAAC,YAAY,CAAC,CAkBvB;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,OAAO,GACxB,OAAO,CAAC,QAAQ,CAAC,CAgTnB"}

package/docs/more/50-ai-agent-instructions.mdx

@@ -0,0 +1,169 @@
+---
+title: 'AI Agent Instructions'
+description: 'Structured reference for AI coding agents working with timber.js — key differences from Next.js, import paths, common mistakes, and reading order.'
+slug: 'ai-agent-instructions'
+---
+
+# AI Agent Instructions
+
+This page is for AI coding agents (Claude Code, Cursor, Copilot, Codex, etc.) and developers who paste context into agent prompts. It is concise and structured for machine consumption — but useful as a quick reference for humans too.
+
+## Fetching These Docs as Markdown
+
+Any timber.js documentation page can be fetched as plain markdown by sending an `Accept: text/markdown` header:
+
+```bash
+curl -H 'Accept: text/markdown' https://timberjs.com/docs/ai-agent-instructions
+```
+
+This returns the page content as `text/markdown` with a `203` status code, suitable for piping into agent context or saving to a file.
+
+## How timber.js Docs Are Organized
+
+| Location | Purpose | Audience |
+| --- | --- | --- |
+| `packages/website/content/docs/` | User-facing guides, tutorials, API reference | Developers building with timber |
+| `design/` | Design decisions, architecture, internal specs | Contributors and agents implementing features |
+| `CLAUDE.md` | Contributor workflow, commands, code style | Agents working on timber itself |
+
+**Read the user-facing docs for building apps.** Read the design docs only when you need to understand _why_ something works the way it does or when contributing to timber itself.
+
+## Reading Order by Task
+
+**Starting a new project:**
+1. [Introduction](/docs/introduction) — what timber is and its philosophy
+2. [Quick Start](/docs/quick-start) — project setup
+3. [Pages and Layouts](/docs/pages-and-layouts) — routing basics
+4. [Configuration](/docs/configuration) — `timber.config.ts`
+
+**Adding a feature:**
+1. [API: @timber-js/app/server](/docs/api-server) — server exports
+2. [API: @timber-js/app/client](/docs/api-client) — client exports
+3. The relevant guide (caching, forms, middleware, etc.)
+
+**Debugging:**
+1. [Coming from Next.js](/docs/coming-from-nextjs) — if the code assumes Next.js patterns
+2. [The Flush Point](/docs/the-flush-point) — if status codes or headers are wrong
+3. [Error Handling](/docs/error-handling) — deny, error boundaries, status files
+
+## Key Differences from Next.js
+
+These are the things you will get wrong if you assume Next.js behavior.
+
+| Concept | Next.js | timber.js |
+| --- | --- | --- |
+| Default component type | Client components need `'use client'` | **All components are server components** by default. Only add `'use client'` when you need browser APIs or hooks. |
+| Fetch caching | `fetch()` is patched with implicit caching | `fetch()` is **never patched**. Use `cache()` from `@timber-js/app/cache` explicitly. |
+| ISR | `revalidate` option | **Does not exist.** Use `cache()` with TTL and tags. |
+| `loading.tsx` | Convention for auto-Suspense | **Does not exist.** Use `<Suspense>` explicitly. |
+| Middleware | Single global `middleware.ts` with matchers | Per-segment `middleware.ts` files + global `proxy.ts`. One-arg signature: `middleware(ctx)`. |
+| `notFound()` | `notFound()` from `next/navigation` | `deny(404)` from `@timber-js/app/server`. Sends a real HTTP 404. |
+| `redirect()` | `redirect()` from `next/navigation` | `redirect()` from `@timber-js/app/server`. Same concept, different import. |
+| Search params | Untyped `useSearchParams()` | Typed `defineSearchParams()` with Zod schemas in `params.ts`. |
+| Auth pattern | In middleware or components | `access.ts` per segment with slot degradation. |
+| Forms | `useFormState` / `useFormStatus` | `createActionClient` + `useActionState` returns a 4-tuple. Forms work without JS. |
+
+## Import Map
+
+| What you need | Import from |
+| --- | --- |
+| `deny`, `redirect`, `getHeaders`, `getCookieJar`, `createActionClient` | `@timber-js/app/server` |
+| `Link`, `useRouter`, `usePathname`, `useActionState` | `@timber-js/app/client` |
+| `cache`, `CacheHandler` | `@timber-js/app/cache` |
+| `defineSearchParams` | `@timber-js/app/search-params` |
+| `defineSchema`, `defineSegmentParams` | `@timber-js/app/params` |
+| Content collection data | `content-collections` |
+| `Metadata` type | `@timber-js/app/server` |
+
+There is **no** `@timber-js/app` default import. Always use the subpath exports above.
+
+## Project Structure
+
+```
+app/                    # Route tree — file-system routing
+  proxy.ts              # Global request handler (like global middleware)
+  layout.tsx            # Root layout
+  page.tsx              # Home page
+  [segment]/
+    page.tsx            # Dynamic route
+    middleware.ts       # Per-segment middleware
+    access.ts           # Per-segment authorization
+    denied.tsx          # Rendered when access.ts denies
+    error.tsx           # Error boundary for this segment
+    params.ts           # Search param definitions
+  schema.ts             # Segment param schemas (from @timber-js/app/params)
+content/                # Content collections (outside route tree)
+timber.config.ts        # Framework configuration
+mdx-components.tsx      # Custom MDX component mappings (optional)
+content-collections.ts  # Collection definitions (optional)
+```
+
+## Common Mistakes
+
+1. **Importing from `next/*`** — there is no `next` package. Use `@timber-js/app/server` and `@timber-js/app/client`. Exception: `next/navigation`'s `redirect()` and `notFound()` are shimmed for compatibility.
+
+2. **Adding `'use client'` to everything** — components are server components by default. Only add `'use client'` when you need browser APIs, event handlers, or React hooks like `useState`/`useEffect`.
+
+3. **Using `fetch()` and expecting caching** — timber never patches `fetch`. Wrap data-fetching functions in `cache()` from `@timber-js/app/cache` when you want caching.
+
+4. **Creating `loading.tsx` files** — this convention does not exist. Use `<Suspense>` with an explicit fallback where you want streaming.
+
+5. **Using ISR patterns** (`revalidate`, `unstable_cache`) — ISR does not exist. Use `cache()` with `{ ttl: seconds, tags: ['tag'] }`.
+
+6. **Calling `notFound()`** — use `deny(404)` from `@timber-js/app/server` instead. It sends a real HTTP 404 status code.
+
+7. **Putting all middleware in one file** — middleware is per-segment. Place `middleware.ts` at the route level that matches the concern. Use `proxy.ts` for global concerns.
+
+8. **Assuming `useSearchParams()` exists** — use `defineSearchParams()` in a `params.ts` file with Zod schemas, then access via `.get()` (server) or `.useQueryStates()` (client).
+
+## Quick Patterns
+
+### Data fetching with caching
+
+```tsx
+import { cache } from '@timber-js/app/cache';
+
+const getProducts = cache(
+  async () => db.products.findMany(),
+  { ttl: 300, tags: ['products'] }
+);
+
+export default async function Page() {
+  const products = await getProducts();
+  return <ProductList products={products} />;
+}
+```
+
+### 404 handling
+
+```tsx
+import { deny } from '@timber-js/app/server';
+
+export default async function Page({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
+  const item = await getItem(id);
+  if (!item) deny(404);
+  return <Item item={item} />;
+}
+```
+
+### Per-segment middleware
+
+```ts title="app/dashboard/middleware.ts"
+import type { MiddlewareContext } from '@timber-js/app/server';
+
+export default async function middleware(ctx: MiddlewareContext) {
+  ctx.headers.set('X-Dashboard', 'true');
+}
+```
+
+### Access control
+
+```ts title="app/(auth)/access.ts"
+import { redirect, getCookieJar } from '@timber-js/app/server';
+
+export default async function access() {
+  const session = getSession(getCookieJar());
+  if (!session) redirect('/login');
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.155",
+  "version": "0.2.0-alpha.156",
   "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",
@@ -125,9 +125,9 @@
     "nitro": "3.0.260610-beta"
   },
   "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",
+    "@content-collections/vite": "^0.2.0 || ^0.3.0",
     "@mdx-js/rollup": "^3.0.0",
     "@vitejs/plugin-react": "^6.0.0",
     "@vitejs/plugin-rsc": ">=0.5.27",

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

@@ -12,7 +12,7 @@
 // ../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 { join, basename, relative } from 'node:path';
 import { generateHeadersFile } from './shared.js';
 import type { TimberConfig } from './types';
 
@@ -74,7 +74,11 @@ export async function runSharedBuildSteps(opts: BuildOutputBaseOptions): Promise
   });
 
   // 3. Write _headers file for static asset cache control.
-  await writeFile(join(publicDir, '_headers'), generateHeadersFile());
+  // 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.
+  const unhashedPaths = await findUnhashedStaticFiles(publicDir);
+  await writeFile(join(publicDir, '_headers'), generateHeadersFile(unhashedPaths));
 
   // 4. Copy RSC + SSR server bundles into the output directory.
   await cp(join(buildDir, 'rsc'), join(outDir, 'rsc'), { recursive: true });
@@ -93,6 +97,52 @@ export async function runSharedBuildSteps(opts: BuildOutputBaseOptions): Promise
   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 (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

package/src/adapters/cloudflare.ts

@@ -338,12 +338,42 @@ if (!bindingsAls) {
 
 export default {
 ${handlersSpread}  async fetch(request, env, ctx) {
-    // Bridge ctx.waitUntil into the per-request ALS so waitUntil() calls in
-    // user code keep the isolate alive after the response is sent.
-    // See design/11-platform.md §"waitUntil()".
-    return bindingsAls.run(env, () =>
+    // Edge-cache GET/HEAD responses via the Cache API. RSC navigation
+    // requests (Accept: text/x-component) are excluded — they vary by
+    // X-Timber-State-Tree which the cache key doesn't capture.
+    const isRsc = request.headers.get('Accept')?.includes('text/x-component')
+    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)
+      if (cached) return cached
+    }
+
+    const response = await bindingsAls.run(env, () =>
       runWithWaitUntil((promise) => ctx.waitUntil(promise), () => handler(request))
     )
+
+    // 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
+    // benefit from cache.match() which handles HEAD→GET matching automatically.
+    // See design/25-production-deployments.md §"CDN / Edge Cache".
+    if (cache && request.method === 'GET' && response.status === 200) {
+      const cc = response.headers.get('Cache-Control')
+      const vary = response.headers.get('Vary')
+      if (cc && !cc.includes('no-store') && !cc.includes('private')
+          && (cc.includes('public') || cc.includes('s-maxage'))
+          && vary !== '*' && !response.headers.has('Set-Cookie')) {
+        ctx.waitUntil(cache.put(request, response.clone()))
+      }
+    }
+
+    return response
   }
 }
 `;

package/src/adapters/shared.ts

@@ -24,17 +24,45 @@ export const STATIC_CACHE = 'public, max-age=3600, must-revalidate';
  * Static Assets, Cloudflare Pages, and Netlify. It maps URL patterns to
  * HTTP response headers.
  *
- * Vite places all hashed chunks under `/assets/` — these get immutable caching.
- * Everything else (favicon.ico, robots.txt, etc.) gets a shorter cache.
+ * Only hashed (immutable) asset paths are listed here by default. When
+ * `unhashedPaths` is provided, per-file rules are appended for unhashed
+ * static assets (favicon.ico, robots.txt, etc.) so they get Cache-Control
+ * on platforms like Cloudflare Workers Static Assets where the server
+ * handler never sees static file requests.
+ *
+ * A `/*` catch-all is NOT used — it would be additive on Cloudflare,
+ * producing duplicate Cache-Control directives on hashed assets
+ * (invalid per RFC 9111).
  */
-export function generateHeadersFile(): string {
-  return `# Auto-generated by @timber-js/app — static asset cache headers.
+// Cloudflare Workers Static Assets caps _headers at 100 rules.
+// Reserve 2 for the wildcard hashed-asset rules.
+const MAX_UNHASHED_RULES = 98;
+
+export function generateHeadersFile(unhashedPaths?: string[]): string {
+  let content = `# Auto-generated by @timber-js/app — static asset cache headers.
 # See design/25-production-deployments.md §"CDN / Edge Cache"
 
 /assets/*
   Cache-Control: ${IMMUTABLE_CACHE}
 
-/*
-  Cache-Control: ${STATIC_CACHE}
+/_timber/fonts/*
+  Cache-Control: ${IMMUTABLE_CACHE}
 `;
+
+  if (unhashedPaths && unhashedPaths.length > 0) {
+    const capped = unhashedPaths.slice(0, MAX_UNHASHED_RULES);
+    if (unhashedPaths.length > MAX_UNHASHED_RULES) {
+      console.warn(
+        `[timber] _headers: ${unhashedPaths.length} unhashed static files found, ` +
+          `but Cloudflare limits _headers to 100 rules. Only the first ${MAX_UNHASHED_RULES} ` +
+          `unhashed files will get Cache-Control headers.`
+      );
+    }
+    content += `\n# Unhashed static assets — short-lived cache with revalidation\n`;
+    for (const p of capped) {
+      content += `\n${p}\n  Cache-Control: ${STATIC_CACHE}\n`;
+    }
+  }
+
+  return content;
 }

package/src/fonts/google.ts

@@ -21,6 +21,28 @@ import { join } from 'node:path';
 import type { ExtractedFont, FontFaceDescriptor } from './types.js';
 import { fontUrlPrefix } from './paths.js';
 
+/**
+ * Extract a recognizable error code (ETIMEDOUT, ENOTFOUND, etc.) from a
+ * network error's cause chain. Node's undici-based `fetch` wraps the
+ * system error inside `cause` (sometimes as an AggregateError).
+ */
+function extractNetworkErrorCode(err: unknown): string | undefined {
+  if (!(err instanceof Error)) return undefined;
+  const code = (err as NodeJS.ErrnoException).code;
+  if (code) return code;
+  const cause = (err as { cause?: unknown }).cause;
+  if (cause instanceof AggregateError) {
+    for (const inner of cause.errors) {
+      const innerCode = (inner as NodeJS.ErrnoException).code;
+      if (innerCode) return innerCode;
+    }
+  }
+  if (cause instanceof Error) {
+    return (cause as NodeJS.ErrnoException).code;
+  }
+  return undefined;
+}
+
 /** Google Fonts CSS API v2 base URL. */
 const GOOGLE_FONTS_API = 'https://fonts.googleapis.com/css2';
 
@@ -112,9 +134,20 @@ export function buildGoogleFontsUrl(font: ExtractedFont): string {
  * We parse each block to extract the font URL, unicode-range, and subset label.
  */
 export async function fetchGoogleFontsCss(url: string): Promise<GoogleFontFace[]> {
-  const response = await fetch(url, {
-    headers: { 'User-Agent': WOFF2_USER_AGENT },
-  });
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      headers: { 'User-Agent': WOFF2_USER_AGENT },
+    });
+  } catch (err) {
+    const code = extractNetworkErrorCode(err);
+    throw new Error(
+      `[timber] Failed to fetch Google Fonts CSS from ${url}` +
+        (code ? ` (${code})` : '') +
+        `. Build requires internet access for font optimization.` +
+        ` If building offline, set TIMBER_SKIP_FONTS=1 to skip font downloading.`
+    );
+  }
 
   if (!response.ok) {
     throw new Error(
@@ -205,7 +238,18 @@ export function cacheKey(face: GoogleFontFace): string {
  * Download a single font file from its URL.
  */
 export async function downloadFontFile(url: string): Promise<Buffer> {
-  const response = await fetch(url);
+  let response: Response;
+  try {
+    response = await fetch(url);
+  } catch (err) {
+    const code = extractNetworkErrorCode(err);
+    throw new Error(
+      `[timber] Failed to download font file from ${url}` +
+        (code ? ` (${code})` : '') +
+        `. Build requires internet access for font optimization.` +
+        ` If building offline, set TIMBER_SKIP_FONTS=1 to skip font downloading.`
+    );
+  }
   if (!response.ok) {
     throw new Error(`Failed to download font from ${url}: ${response.status}`);
   }
@@ -232,7 +276,14 @@ export async function downloadAndCacheFonts(
 
   for (const font of googleFonts) {
     const apiUrl = buildGoogleFontsUrl(font);
-    const faces = await fetchGoogleFontsCss(apiUrl);
+    let faces: GoogleFontFace[];
+    try {
+      faces = await fetchGoogleFontsCss(apiUrl);
+    } catch (err) {
+      throw new Error(
+        `[timber] Failed to download font '${font.family}': ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
     const filtered = filterBySubsets(faces, font.subsets);
 
     for (const face of filtered) {

package/src/plugins/fonts.ts

@@ -159,9 +159,15 @@ export function timberFonts(ctx: PluginContext): Plugin {
           return '';
         }
 
+        const skipFonts = process.env.TIMBER_SKIP_FONTS === '1';
+
         for (const font of pipeline.googleFonts()) {
           if (font.importer !== importer) continue;
           if (pipeline.hasFaces(font.id)) continue;
+          if (skipFonts && !ctx.dev) {
+            console.warn(`[timber-fonts] Skipping font "${font.family}" (TIMBER_SKIP_FONTS=1)`);
+            continue;
+          }
           try {
             if (ctx.dev) {
               const faces = await resolveDevFontFaces(font);

package/src/server/asset-headers.ts

@@ -8,9 +8,13 @@
  * Unhashed assets (e.g. /favicon.ico) get a shorter cache with revalidation:
  *   Cache-Control: public, max-age=3600, must-revalidate
  *
- * This is applied automatically by the framework for static assets served
- * from the build output. Page responses are NOT affected — those are
- * controlled by the developer via middleware.ts or proxy.ts.
+ * The `_headers` file lists hashed asset paths (/assets/*, /_timber/fonts/*) as
+ * wildcard rules and unhashed files as per-file rules. At runtime, adapters
+ * that see static file requests (nitro, preview) also set Cache-Control via
+ * `getAssetCacheControl()`. On Cloudflare Workers Static Assets, the worker
+ * never sees static file requests — the `_headers` file is the only mechanism.
+ * Page responses are NOT affected — those are controlled by the developer
+ * via middleware.ts or proxy.ts.
  *
  * Design docs: 18-build-system.md, 06-caching.md
  */

package/src/server/pipeline-phases.ts

@@ -290,13 +290,21 @@ export async function handleRequest(
         // immutable header bag (e.g. user returns Response.redirect()).
         if (handlerResult instanceof Response) {
           if (method === 'HEAD') {
+            const headHeaders = new Headers(handlerResult.headers);
+            if (handlerResult.ok && !headHeaders.has('Cache-Control')) {
+              headHeaders.set('Cache-Control', 'public, max-age=14400, must-revalidate');
+            }
             return new Response(null, {
               status: handlerResult.status,
               statusText: handlerResult.statusText,
-              headers: new Headers(handlerResult.headers),
+              headers: headHeaders,
             });
           }
-          return cloneWithMutableHeaders(handlerResult);
+          const res = cloneWithMutableHeaders(handlerResult);
+          if (res.ok && !res.headers.has('Cache-Control')) {
+            res.headers.set('Cache-Control', 'public, max-age=14400, must-revalidate');
+          }
+          return res;
         }
         // Otherwise, serialize based on content type. The type discriminator
         // here is the metadata route's declared content type (from the file

package/dist/_chunks/build-output-helper-B20ZuTSA.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"build-output-helper-B20ZuTSA.js","names":[],"sources":["../../src/adapters/shared.ts","../../src/adapters/build-output-helper.ts"],"sourcesContent":["// Shared adapter utilities — leaf module with zero deps on server/, client/,\n// or any Vite-dependent code.\n//\n// Adapters are loaded by Node at Vite startup time, before Vite's module\n// resolver is available. This module uses only Node built-ins and can be\n// imported by both adapters via a relative path.\n//\n// IMPORTANT: Do NOT add imports from ../server/, ../client/, ../plugins/,\n// or any module that transitively depends on Vite. A test in\n// tests/adapters/shared-no-forbidden-imports.test.ts enforces this.\n\n// ─── Static asset cache headers ──────────────────────────────────────────\n\n/** Cache-Control value for hashed (immutable) assets. */\nexport const IMMUTABLE_CACHE = 'public, max-age=31536000, immutable';\n\n/** Cache-Control value for unhashed static assets. */\nexport const STATIC_CACHE = 'public, max-age=3600, must-revalidate';\n\n/**\n * Generate a `_headers` file for static asset cache control.\n *\n * The `_headers` file is a platform convention supported by Cloudflare Workers\n * Static Assets, Cloudflare Pages, and Netlify. It maps URL patterns to\n * HTTP response headers.\n *\n * Vite places all hashed chunks under `/assets/` — these get immutable caching.\n * Everything else (favicon.ico, robots.txt, etc.) gets a shorter cache.\n */\nexport function generateHeadersFile(): string {\n  return `# Auto-generated by @timber-js/app — static asset cache headers.\n# See design/25-production-deployments.md §\"CDN / Edge Cache\"\n\n/assets/*\n  Cache-Control: ${IMMUTABLE_CACHE}\n\n/*\n  Cache-Control: ${STATIC_CACHE}\n`;\n}\n","// Shared build-output helper for adapter buildOutput() methods.\n//\n// Steps 1–5 of every adapter's buildOutput are platform-agnostic:\n//   1. Copy client assets to the public/static directory\n//   2. Write _headers file for static asset cache control\n//   3. Copy RSC + SSR server bundles\n//   4. Write manifest-init module (if present)\n//\n// Only the final steps (entry codegen, platform config) vary per adapter.\n//\n// IMPORTANT: This module must remain a leaf — no imports from ../server/,\n// ../client/, or Vite-dependent code. See adapters/shared.ts header.\n\nimport { writeFile, mkdir, cp, readdir, readFile } from 'node:fs/promises';\nimport { join, basename } from 'node:path';\nimport { generateHeadersFile } from './shared.js';\nimport type { TimberConfig } from './types';\n\n/** Options for the shared build output steps. */\nexport interface BuildOutputBaseOptions {\n  /** Resolved timber config. */\n  config: TimberConfig;\n  /** Root build directory (e.g. `.timber/build`). */\n  buildDir: string;\n  /** Adapter-specific output directory (e.g. `.timber/build/nitro`). */\n  outDir: string;\n  /**\n   * Name of the public/static directory within outDir.\n   * Nitro uses 'public', Cloudflare uses 'static'.\n   */\n  publicDirName: string;\n}\n\n/**\n * Run the platform-agnostic build output steps shared by all adapters:\n *\n * 1. Create the output directory\n * 2. Copy client assets to the public/static directory\n * 3. Write the `_headers` file for static asset cache control\n * 4. Copy RSC and SSR server bundles into the output directory\n * 5. Write the manifest-init module if present\n *\n * Returns the resolved public directory path for further adapter-specific use.\n */\nexport async function runSharedBuildSteps(opts: BuildOutputBaseOptions): Promise<string> {\n  const { config, buildDir, outDir, publicDirName } = opts;\n\n  // 1. Create the output directory.\n  await mkdir(outDir, { recursive: true });\n\n  // 2. Copy client assets to public/static directory.\n  // When client JavaScript is disabled, skip .js files — only CSS,\n  // fonts, images, and other static assets are needed.\n  const clientDir = join(buildDir, 'client');\n  const publicDir = join(outDir, publicDirName);\n  await mkdir(publicDir, { recursive: true });\n  // Find WASM files that are referenced by client JS (legitimate client WASM)\n  // vs orphaned server-only WASM (e.g. @takumi-rs for OG image generation).\n  // Only strip orphaned WASM to avoid breaking client-side WASM usage.\n  const referencedWasm = await findReferencedWasm(clientDir);\n\n  await cp(clientDir, publicDir, {\n    recursive: true,\n    filter: (src: string) => {\n      if (src.endsWith('.wasm') && !referencedWasm.has(basename(src))) {\n        return false;\n      }\n      if (config.clientJavascriptDisabled && src.endsWith('.js')) return false;\n      return true;\n    },\n  }).catch((e: NodeJS.ErrnoException) => {\n    // Client dir may not exist when client JavaScript is disabled\n    if (e.code !== 'ENOENT') throw e;\n  });\n\n  // 3. Write _headers file for static asset cache control.\n  await writeFile(join(publicDir, '_headers'), generateHeadersFile());\n\n  // 4. Copy RSC + SSR server bundles into the output directory.\n  await cp(join(buildDir, 'rsc'), join(outDir, 'rsc'), { recursive: true });\n  await cp(join(buildDir, 'ssr'), join(outDir, 'ssr'), { recursive: true }).catch(\n    (e: NodeJS.ErrnoException) => {\n      // SSR dir may not exist for static-only builds\n      if (e.code !== 'ENOENT') throw e;\n    }\n  );\n\n  // 5. Write manifest-init module if present.\n  if (config.manifestInit) {\n    await writeFile(join(outDir, '_timber-manifest-init.js'), config.manifestInit);\n  }\n\n  return publicDir;\n}\n\n/**\n * Scan client JS files for references to .wasm filenames.\n * Returns the set of WASM basenames that are actually imported/referenced\n * by client code and must be preserved in the static output.\n */\nasync function findReferencedWasm(clientDir: string): Promise<Set<string>> {\n  const referenced = new Set<string>();\n\n  let files: string[];\n  try {\n    files = await collectFiles(clientDir);\n  } catch {\n    return referenced;\n  }\n\n  const jsFiles = files.filter((f) => f.endsWith('.js'));\n  const wasmFiles = files.filter((f) => f.endsWith('.wasm')).map((f) => basename(f));\n  if (wasmFiles.length === 0) return referenced;\n\n  for (const jsFile of jsFiles) {\n    const content = await readFile(jsFile, 'utf-8');\n    for (const wasmName of wasmFiles) {\n      if (content.includes(wasmName)) {\n        referenced.add(wasmName);\n      }\n    }\n  }\n\n  return referenced;\n}\n\nasync function collectFiles(dir: string): Promise<string[]> {\n  const result: string[] = [];\n  const entries = await readdir(dir, { withFileTypes: true });\n  for (const entry of entries) {\n    const fullPath = join(dir, entry.name);\n    if (entry.isDirectory()) {\n      result.push(...(await collectFiles(fullPath)));\n    } else {\n      result.push(fullPath);\n    }\n  }\n  return result;\n}\n"],"mappings":";;;;AAcA,IAAa,kBAAkB;;AAG/B,IAAa,eAAe;;;;;;;;;;;AAY5B,SAAgB,sBAA8B;CAC5C,OAAO;;;;mBAIU,gBAAgB;;;mBAGhB,aAAa;;AAEhC;;;;;;;;;;;;;;ACKA,eAAsB,oBAAoB,MAA+C;CACvF,MAAM,EAAE,QAAQ,UAAU,QAAQ,kBAAkB;CAGpD,MAAM,MAAM,QAAQ,EAAE,WAAW,KAAK,CAAC;CAKvC,MAAM,YAAY,KAAK,UAAU,QAAQ;CACzC,MAAM,YAAY,KAAK,QAAQ,aAAa;CAC5C,MAAM,MAAM,WAAW,EAAE,WAAW,KAAK,CAAC;CAI1C,MAAM,iBAAiB,MAAM,mBAAmB,SAAS;CAEzD,MAAM,GAAG,WAAW,WAAW;EAC7B,WAAW;EACX,SAAS,QAAgB;GACvB,IAAI,IAAI,SAAS,OAAO,KAAK,CAAC,eAAe,IAAI,SAAS,GAAG,CAAC,GAC5D,OAAO;GAET,IAAI,OAAO,4BAA4B,IAAI,SAAS,KAAK,GAAG,OAAO;GACnE,OAAO;EACT;CACF,CAAC,EAAE,OAAO,MAA6B;EAErC,IAAI,EAAE,SAAS,UAAU,MAAM;CACjC,CAAC;CAGD,MAAM,UAAU,KAAK,WAAW,UAAU,GAAG,oBAAoB,CAAC;CAGlE,MAAM,GAAG,KAAK,UAAU,KAAK,GAAG,KAAK,QAAQ,KAAK,GAAG,EAAE,WAAW,KAAK,CAAC;CACxE,MAAM,GAAG,KAAK,UAAU,KAAK,GAAG,KAAK,QAAQ,KAAK,GAAG,EAAE,WAAW,KAAK,CAAC,EAAE,OACvE,MAA6B;EAE5B,IAAI,EAAE,SAAS,UAAU,MAAM;CACjC,CACF;CAGA,IAAI,OAAO,cACT,MAAM,UAAU,KAAK,QAAQ,0BAA0B,GAAG,OAAO,YAAY;CAG/E,OAAO;AACT;;;;;;AAOA,eAAe,mBAAmB,WAAyC;CACzE,MAAM,6BAAa,IAAI,IAAY;CAEnC,IAAI;CACJ,IAAI;EACF,QAAQ,MAAM,aAAa,SAAS;CACtC,QAAQ;EACN,OAAO;CACT;CAEA,MAAM,UAAU,MAAM,QAAQ,MAAM,EAAE,SAAS,KAAK,CAAC;CACrD,MAAM,YAAY,MAAM,QAAQ,MAAM,EAAE,SAAS,OAAO,CAAC,EAAE,KAAK,MAAM,SAAS,CAAC,CAAC;CACjF,IAAI,UAAU,WAAW,GAAG,OAAO;CAEnC,KAAK,MAAM,UAAU,SAAS;EAC5B,MAAM,UAAU,MAAM,SAAS,QAAQ,OAAO;EAC9C,KAAK,MAAM,YAAY,WACrB,IAAI,QAAQ,SAAS,QAAQ,GAC3B,WAAW,IAAI,QAAQ;CAG7B;CAEA,OAAO;AACT;AAEA,eAAe,aAAa,KAAgC;CAC1D,MAAM,SAAmB,CAAC;CAC1B,MAAM,UAAU,MAAM,QAAQ,KAAK,EAAE,eAAe,KAAK,CAAC;CAC1D,KAAK,MAAM,SAAS,SAAS;EAC3B,MAAM,WAAW,KAAK,KAAK,MAAM,IAAI;EACrC,IAAI,MAAM,YAAY,GACpB,OAAO,KAAK,GAAI,MAAM,aAAa,QAAQ,CAAE;OAE7C,OAAO,KAAK,QAAQ;CAExB;CACA,OAAO;AACT"}