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

package/docs/more/41-timber-vs-nextjs.mdx

@@ -0,0 +1,81 @@
+---
+title: 'timber.js vs Next.js'
+description: 'An honest comparison of timber.js and Next.js — where they differ and why.'
+slug: 'timber-vs-nextjs'
+---
+
+# timber.js vs Next.js
+
+Next.js is the most widely used React framework. It's mature, well-documented, and backed by Vercel. timber.js would not exist without it — the app directory routing model, server components, and many API patterns are directly inspired by Next.js.
+
+That said, we made different design decisions in a few areas. Here's an honest comparison.
+
+## HTTP Semantics
+
+| Behavior           | Next.js                                          | timber.js                                        |
+| ------------------ | ------------------------------------------------ | ------------------------------------------------ |
+| Status codes       | Always 200 (streaming commits early)             | Real status codes (flush held until shell ready) |
+| 404 pages          | 200 + `not-found.tsx` error boundary             | HTTP 404 + `404.tsx`                             |
+| Redirects in pages | Client-side via `redirect()` after 200           | HTTP 302/301 before any bytes sent               |
+| Works without JS   | Partially (primary content yes, interactions no) | Fully (forms, navigation, status codes all work) |
+
+This is the core philosophical difference. Next.js optimizes for earliest possible TTFB. timber.js optimizes for correct HTTP responses, at the cost of ~20ms additional server buffering.
+
+## Streaming
+
+Both frameworks support React Suspense streaming. The difference is when it starts:
+
+- **Next.js:** Streams immediately. `loading.tsx` renders while data loads. Status code is already committed.
+- **timber.js:** Holds until the shell is ready (everything outside `<Suspense>`). Then streams Suspense content. No `loading.tsx` — `<Suspense>` is opt-in only.
+
+## Routing
+
+Both use file-system routing in an `app/` directory. The models are similar:
+
+- Layouts, pages, dynamic segments, catch-all routes — same patterns
+- Parallel routes (slots) — both support `@sidebar`, `@modal` patterns
+- Route groups — both support `(group)` directories
+
+**Differences:**
+
+- **Middleware:** Next.js has a single global `middleware.ts`. timber.js has per-segment `middleware.ts` files.
+- **Authorization:** timber.js has `access.ts` files for per-segment access control with `deny()`. Next.js uses middleware or in-component checks.
+- **Typed routes:** timber.js generates route types at build time — `<Link>` type-checks `href` and params.
+
+## Caching
+
+| Behavior          | Next.js                                              | timber.js                                             |
+| ----------------- | ---------------------------------------------------- | ----------------------------------------------------- |
+| `fetch()` caching | Cached by default (opt out with `cache: 'no-store'`) | Never cached (explicit is better)                     |
+| Cache API         | `unstable_cache` / `'use cache'`                     | `timber.cache()` with TTL, tags, staleWhileRevalidate |
+| Revalidation      | `revalidateTag()`, `revalidatePath()`                | `revalidateTag()`                                     |
+
+timber.js takes the position that implicit caching causes more bugs than it prevents. Nothing is cached unless you wrap it in `timber.cache()`.
+
+## Build System
+
+|                  | Next.js             | timber.js                             |
+| ---------------- | ------------------- | ------------------------------------- |
+| Bundler          | Turbopack / Webpack | Vite 7 (Rolldown)                     |
+| Config           | `next.config.js`    | `vite.config.ts` + `timber.config.ts` |
+| Plugin ecosystem | Next.js-specific    | Full Vite plugin ecosystem            |
+
+## Platform Support
+
+Next.js is optimized for Vercel and works on other platforms through community adapters. timber.js ships a first-party Cloudflare Workers adapter and a Nitro adapter that covers Node.js, Vercel, Bun, Netlify, AWS Lambda, and more.
+
+## When to Use Next.js
+
+- You need the largest ecosystem and community support
+- You're deploying to Vercel
+- You need features timber.js hasn't built yet (image optimization, ISR, etc.)
+- Your team is already productive with Next.js
+
+## When to Use timber.js
+
+- You care about correct HTTP status codes and headers
+- You want pages that work fully without JavaScript
+- You're deploying to Cloudflare Workers
+- You prefer explicit caching over implicit
+- You want per-segment middleware and authorization
+- You want Vite's build speed and plugin ecosystem

package/docs/more/42-timber-vs-others.mdx

@@ -0,0 +1,68 @@
+---
+title: 'timber.js vs Other Frameworks'
+description: 'How timber.js compares to Vinext, Remix, and other React server frameworks.'
+slug: 'timber-vs-others'
+---
+
+# timber.js vs Other Frameworks
+
+Beyond Next.js, there are several React frameworks worth comparing against. Each makes different trade-offs.
+
+## Vinext (Cloudflare)
+
+Vinext is Cloudflare's implementation of Next.js on Vite. It aims for Next.js API compatibility running natively on Cloudflare Workers.
+
+**Shared ground:** Both timber.js and Vinext target Cloudflare Workers, use Vite, and support React Server Components.
+
+**Key differences:**
+
+|              | Vinext                                 | timber.js                                |
+| ------------ | -------------------------------------- | ---------------------------------------- |
+| Goal         | Next.js compatibility on Vite          | Independent design, different trade-offs |
+| Streaming    | Streams immediately (Next.js behavior) | Holds until shell ready                  |
+| Status codes | 200 for everything (Next.js behavior)  | Real HTTP status codes                   |
+| API surface  | Next.js-compatible                     | Similar but divergent where we disagree  |
+| Caching      | Next.js caching model                  | Explicit-only caching                    |
+
+If you want Next.js on Cloudflare with minimal code changes, Vinext is the right choice. If you want a different rendering model with correct HTTP semantics, that's timber.js.
+
+## Remix / React Router
+
+Remix (now React Router v7) pioneered many of the ideas timber.js agrees with: progressive enhancement, forms that work without JavaScript, and server-first rendering.
+
+**Shared philosophy:**
+
+- Forms should work without JS
+- Server rendering is the default
+- Progressive enhancement over client-side-first
+
+**Key differences:**
+
+|               | Remix / React Router                 | timber.js                                |
+| ------------- | ------------------------------------ | ---------------------------------------- |
+| Routing model | Flat route config or file convention | Nested `app/` directory (Next.js-style)  |
+| Data loading  | `loader` / `action` functions        | Async server components + server actions |
+| RSC support   | Not yet (planned)                    | Built on RSC from day one                |
+| Streaming     | Supports `defer()` for streaming     | `<Suspense>` with explicit flush point   |
+| Build system  | Vite (React Router v7)               | Vite                                     |
+
+Remix's `loader`/`action` model is elegant and well-understood. timber.js bets on RSC as the data loading primitive — your components are your data layer.
+
+## TanStack Start
+
+TanStack Start is a full-stack React framework from the TanStack Router team.
+
+**Shared ground:** Both use Vite, both aim for good TypeScript support, both support server-side rendering.
+
+**Key differences:**
+
+|                | TanStack Start                          | timber.js                                  |
+| -------------- | --------------------------------------- | ------------------------------------------ |
+| Routing        | TanStack Router (code-based, type-safe) | File-system routing with generated types   |
+| Data loading   | TanStack Query integration              | Async server components + `timber.cache()` |
+| RSC support    | Experimental                            | Core architecture                          |
+| Platform focus | General-purpose                         | Cloudflare-first, works everywhere         |
+
+## Summary
+
+Every framework makes trade-offs. timber.js trades streaming speed for HTTP correctness and trades API surface size for explicitness. If those trade-offs align with how you think about web development, it's worth trying. If they don't, the frameworks above are all excellent choices.

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/llms.txt

@@ -0,0 +1,55 @@
+# @timber-js/app
+
+> Vite-native React Server Components framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript.
+
+timber.js is a React framework built on Vite and React Server Components. It uses file-system routing (app/ directory), server components by default, and produces real HTTP status codes. It deploys to Cloudflare Workers, Node.js, Vercel, Netlify, and more via adapters.
+
+It is inspired by, but _not_ next.js. Do not assume next.js features work in timber, though the routing is similar, much of the rest diverges.
+
+## Docs
+
+Documentation ships with this package in the `docs/` directory. All files are MDX.
+
+### Learn (core concepts, read in order)
+
+- [Introduction](docs/learn/00-introduction.mdx)
+- [Quick Start](docs/learn/01-quick-start.mdx)
+- [Pages and Layouts](docs/learn/02-pages-and-layouts.mdx)
+- [Fetching Data](docs/learn/03-fetching-data.mdx)
+- [Access Control](docs/learn/03b-access-control.mdx)
+- [Loading States](docs/learn/04-loading-states.mdx)
+- [The Flush Point](docs/learn/04b-the-flush-point.mdx)
+- [Typed Params](docs/learn/05-typed-params.mdx)
+- [Forms and Actions](docs/learn/06-forms-and-actions.mdx)
+- [Streaming](docs/learn/08-streaming.mdx)
+- [Caching](docs/learn/09-caching.mdx)
+- [Middleware](docs/learn/10-middleware.mdx)
+- [Error Handling](docs/learn/11-error-handling.mdx)
+- [Client Navigation](docs/learn/12-client-navigation.mdx)
+- [Configuration](docs/learn/13-configuration.mdx)
+- [Deploying](docs/learn/14-deploying.mdx)
+
+### More (advanced topics)
+
+- [Advanced Routing](docs/more/01-advanced-routing.mdx)
+- [Advanced Forms](docs/more/02-advanced-forms.mdx)
+- [Coming from Next.js](docs/more/03-coming-from-nextjs.mdx)
+- [Metadata and Fonts](docs/more/04-metadata-and-fonts.mdx)
+- [MDX](docs/more/04b-mdx.mdx)
+- [Content Collections](docs/more/05-content-collections.mdx)
+- [Instrumentation & Tracing](docs/more/06-instrumentation.mdx)
+- [Security](docs/more/07-security.mdx)
+
+### API Reference
+
+- [@timber-js/app/server](docs/api/30-api-server.mdx)
+- [@timber-js/app/client](docs/api/31-api-client.mdx)
+- [@timber-js/app/cache](docs/api/32-api-cache.mdx)
+- [Search & Segment Params](docs/api/33-api-search-params.mdx)
+- [timber.config.ts](docs/api/34-api-config.mdx)
+- [TypeScript](docs/api/35-api-typescript.mdx)
+- [CLI](docs/api/36-cli.mdx)
+
+## AI Agent Skill
+
+A Claude Code skill is included at `agent-skill.md`. Load it for guidance on building timber.js applications.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.154",
+  "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",
@@ -26,6 +26,9 @@
     "dist",
     "src",
     "bin",
+    "docs",
+    "agent-skill.md",
+    "llms.txt",
     "README.md",
     "LICENSE"
   ],
@@ -122,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",
@@ -159,7 +162,8 @@
     "node": ">=22.18.0"
   },
   "scripts": {
-    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist",
+    "copy-docs": "node scripts/copy-docs.js",
+    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist && pnpm run copy-docs",
     "typecheck": "tsgo --noEmit"
   }
 }

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;
 }