@timber-js/app 0.2.0-alpha.16 → 0.2.0-alpha.161

package/docs/api/32-api-cache.mdx

@@ -0,0 +1,199 @@
+---
+title: 'API: @timber-js/app/cache'
+description: 'Cache exports — cache, CacheHandler, MemoryCacheHandler, and invalidation.'
+slug: 'api-cache'
+---
+
+# @timber-js/app/cache
+
+Caching primitives and cache handler interface. Import from `@timber-js/app/cache`.
+
+## `cache(fn, options)`
+
+Wrap an async function with cross-request caching.
+
+```ts
+import { cache } from '@timber-js/app/cache';
+
+declare const db: { users: { findUnique(opts: { where: { id: string } }): Promise<{ id: string; name: string }> } };
+
+const getUser = cache(
+  async (userId: string) => {
+    return db.users.findUnique({ where: { id: userId } });
+  },
+  {
+    ttl: 60,
+    key: (userId) => `user:${userId}`,
+    staleWhileRevalidate: true,
+    tags: (userId) => [`user:${userId}`],
+  }
+);
+```
+
+### `CacheOptions<Fn>`
+
+| Option                 | Type                                | Description                                |
+| ---------------------- | ----------------------------------- | ------------------------------------------ |
+| `ttl`                  | `number`                            | Time-to-live in seconds                    |
+| `key`                  | `(...args) => string`               | Custom cache key function (optional)       |
+| `staleWhileRevalidate` | `boolean`                           | Serve stale while refetching in background |
+| `tags`                 | `string[] \| (...args) => string[]` | Tags for invalidation                      |
+
+Default key: FNV-1a hash of function identity + deterministic JSON serialization of arguments.
+
+The function identity is derived at build time from the source text of the `cache(...)` call, so it is stable across restarts, instances, and deploys. With a persistent shared handler (Redis/KV), cached entries survive deploys as long as the call itself is unchanged — reordering calls or editing unrelated code preserves the cache, while editing the wrapped function or its options gives the call a fresh identity (old entries simply expire via TTL). Renaming or moving the file also resets identity for every call in it.
+
+Build-time identity covers calls the bundler can see statically: named imports (including aliases like `import { cache as c }`) and namespace imports (`import * as timber` + `timber.cache(fn, opts)`). Calls it can't trace — a local alias like `const c = cache`, or `cache` re-exported through your own wrapper module — fall back to a hash of the function's source text at runtime. The fallback is still deterministic across instances of the same build, but it resets across deploys, and byte-identical closures produced by a factory can collide — pass an explicit `key` in those cases (timber logs a warning when the fallback is used).
+
+### `cache.invalidate(options)`
+
+Invalidate cache entries by tag or key:
+
+```ts
+import { cache } from '@timber-js/app/cache';
+
+cache.invalidate({ tag: 'products' });
+cache.invalidate({ key: 'user:abc' });
+```
+
+## `CacheHandler` Interface
+
+Implement this to plug in a custom cache backend.
+
+```ts
+interface CacheHandler {
+  get(key: string): Promise<{ value: unknown; tags: string[] } | null>;
+  set(key: string, value: unknown, options: { ttl: number; tags: string[] }): Promise<void>;
+  invalidate(options: { tag: string }): Promise<void>;
+}
+```
+
+## `MemoryCacheHandler`
+
+In-memory cache with LRU eviction. The default handler.
+
+```ts
+import { MemoryCacheHandler } from '@timber-js/app/cache';
+
+const handler = new MemoryCacheHandler({ maxSize: 1000 });
+handler.size; // Current number of entries
+```
+
+### Options
+
+| Option    | Type     | Default | Description                         |
+| --------- | -------- | ------- | ----------------------------------- |
+| `maxSize` | `number` | `1000`  | Maximum entries before LRU eviction |
+
+## `RedisCacheHandler`
+
+Redis-backed cache handler. Takes a client wrapped to timber's `RedisClient` contract — TTL is a required positional argument, so an adapter can't silently drop the expiry:
+
+```ts
+interface RedisClient {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ttlSeconds: number): Promise<unknown>;
+  expireNX(key: string, seconds: number): Promise<unknown>;
+  expireGT(key: string, seconds: number): Promise<unknown>;
+  del(key: string): Promise<unknown>; // single key
+  sadd(key: string, ...members: string[]): Promise<unknown>;
+  srem(key: string, ...members: string[]): Promise<unknown>;
+  smembers(key: string): Promise<string[]>;
+  ttl(key: string): Promise<number>;
+}
+```
+
+`expireNX` and `expireGT` map to Redis 7.0's `EXPIRE key seconds NX|GT` subcommands. `NX` sets the TTL only if none exists, `GT` extends only if greater. Both are used internally for atomic tag set TTL management. Separate methods ensure adapters cannot silently drop the mode. Requires **Redis 7.0+**.
+
+This is deliberately not the native shape of any client library — ioredis, node-redis, and @upstash/redis disagree on TTL argument shapes and method casing, and a contract that pattern-matches one client lets another silently write keys with no expiry. Wrap your client with one of these adapters:
+
+```ts title="ioredis"
+import { RedisCacheHandler } from '@timber-js/app/cache';
+import Redis from 'ioredis';
+
+const redis = new Redis(process.env.REDIS_URL!);
+const handler = new RedisCacheHandler({
+  get: (k) => redis.get(k),
+  set: (k, v, ttl) => redis.set(k, v, 'EX', ttl),
+  expireNX: (k, s) => redis.expire(k, s, 'NX'),
+  expireGT: (k, s) => redis.expire(k, s, 'GT'),
+  del: (k) => redis.del(k),
+  sadd: (k, ...m) => redis.sadd(k, ...m),
+  srem: (k, ...m) => redis.srem(k, ...m),
+  smembers: (k) => redis.smembers(k),
+  ttl: (k) => redis.ttl(k),
+});
+```
+
+```ts title="node-redis"
+import { RedisCacheHandler } from '@timber-js/app/cache';
+import { createClient } from 'redis';
+
+const redis = createClient({ url: process.env.REDIS_URL });
+await redis.connect();
+const handler = new RedisCacheHandler({
+  get: (k) => redis.get(k),
+  set: (k, v, ttl) => redis.set(k, v, { EX: ttl }),
+  expireNX: (k, s) => redis.expire(k, s, 'NX'),
+  expireGT: (k, s) => redis.expire(k, s, 'GT'),
+  del: (k) => redis.del(k),
+  sadd: (k, ...m) => redis.sAdd(k, m),
+  srem: (k, ...m) => redis.sRem(k, m),
+  smembers: (k) => redis.sMembers(k),
+  ttl: (k) => redis.ttl(k),
+});
+```
+
+```ts title="@upstash/redis"
+import { RedisCacheHandler } from '@timber-js/app/cache';
+import { Redis } from '@upstash/redis';
+
+// automaticDeserialization must be off: the handler stores JSON strings
+// and parses them itself.
+const redis = new Redis({
+  url: process.env.UPSTASH_REDIS_REST_URL!,
+  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+  automaticDeserialization: false,
+});
+const handler = new RedisCacheHandler({
+  get: (k) => redis.get(k),
+  set: (k, v, ttl) => redis.set(k, v, { ex: ttl }),
+  expireNX: (k, s) => redis.expire(k, s, 'NX'),
+  expireGT: (k, s) => redis.expire(k, s, 'GT'),
+  del: (k) => redis.del(k),
+  sadd: (k, ...m) => redis.sadd(k, m[0], ...m.slice(1)),
+  srem: (k, ...m) => redis.srem(k, m[0], ...m.slice(1)),
+  smembers: (k) => redis.smembers(k),
+  ttl: (k) => redis.ttl(k),
+});
+```
+
+## `CloudflareKVCacheHandler`
+
+Cloudflare Workers KV–backed cache handler. Resolves the KV binding per-request via `getCloudflareBindings()`. Uses tag index keys for tag-based invalidation. Eventually consistent — TTL is the primary expiry mechanism.
+
+```ts
+import { CloudflareKVCacheHandler } from '@timber-js/app/adapters/cloudflare/cache';
+
+const handler = new CloudflareKVCacheHandler({
+  bindingName: 'TIMBER_CACHE',
+  prefix: 'tc:', // optional, default 'tc:'
+});
+```
+
+## Invalidation
+
+### `revalidateTag(tag)`
+
+Invalidate all cache entries with the given tag. Re-exported from `@timber-js/app/server` for convenience.
+
+```ts
+import { revalidateTag } from '@timber-js/app/server';
+
+revalidateTag('products');
+revalidateTag(`user:${userId}`);
+```
+
+## Singleflight
+
+Request coalescing is built into `cache()` automatically — when multiple concurrent calls miss the cache for the same key, only one executes the underlying function. The singleflight and stable-stringify utilities are internal implementation details and not part of the public API.

package/docs/api/33-api-search-params.mdx

@@ -0,0 +1,141 @@
+---
+title: 'API: @timber-js/app/search-params & Segment Params'
+description: 'Params exports — defineSchema, getSegmentParams, defineSearchParams, codecs, and utilities.'
+slug: 'api-params'
+---
+
+# @timber-js/app/search-params
+
+Typed search parameter definitions.
+
+## `defineSearchParams(codecs)`
+
+Create a typed search params definition for a route.
+
+```ts
+import { defineSearchParams } from '@timber-js/app/search-params';
+import { z } from 'zod/v4';
+
+export const searchParams = defineSearchParams({
+  page: z.coerce.number().default(1),
+  sort: z.enum(['price', 'name', 'date']).default('date'),
+  q: z.string().optional(),
+});
+```
+
+### Returns: `SearchParamsDefinition<T>`
+
+| Method / Property         | Description                                            |
+| ------------------------- | ------------------------------------------------------ |
+| `.get()`                  | Read from ALS and parse (server-only)                  |
+| `.parse(searchParams)`    | Parse and validate from `URLSearchParams` or `Promise` |
+| `.useQueryStates(opts?)`  | Client hook — read and update typed search params      |
+| `.extend(codecs)`         | Add additional params                                  |
+| `.pick(...keys)`          | Create a subset                                        |
+| `.serialize(values)`      | Convert typed values to URL search string              |
+| `.href(base, values)`     | Build a full URL with params                           |
+| `.toSearchParams(values)` | Convert to `URLSearchParams`                           |
+| `.codecs`                 | Read-only codec map                                    |
+| `.urlKeys`                | Read-only URL key alias map                            |
+
+---
+
+# Segment Params
+
+Segment params are defined globally in `app/schema.ts` via `defineSchema`. Access them with `getSegmentParams()` from `@timber-js/app/server` or `useSegmentParams()` from `@timber-js/app/client`.
+
+## `defineSchema(config)`
+
+Define segment param codecs in a single file. Exported from `@timber-js/app`.
+
+```ts
+import { defineSchema } from '@timber-js/app/params';
+import { codec } from '@timber-js/app/codec';
+import { z } from 'zod/v4';
+
+export default defineSchema({
+  segmentParams: {
+    '[id]': z.coerce.number().int().positive(),
+    '[artistSlug]': codec.string,
+    '[year]': codec.integer,
+  },
+});
+```
+
+Each key uses the bracket syntax from the filesystem. Parse failure → 404.
+
+## `getSegmentParams(segmentPath?)`
+
+Read segment params on the server. ALS-backed. Exported from `@timber-js/app/server`.
+
+```ts
+import { SEGMENT_PATH } from './$segment';
+import { getSegmentParams } from '@timber-js/app/server';
+
+const { id } = getSegmentParams(SEGMENT_PATH); // Exact types from schema
+const params = getSegmentParams();       // Partial<AllSegmentParams>
+```
+
+## `useSegmentParams(segmentPath?)`
+
+Read segment params on the client. Context-backed. Exported from `@timber-js/app/client`.
+
+```tsx
+import { SEGMENT_PATH } from './$segment';
+import { useSegmentParams } from '@timber-js/app/client';
+
+const { id } = useSegmentParams(SEGMENT_PATH); // Exact types from schema
+```
+
+See [Typed Params](/docs/typed-params) for the full guide.
+
+## `SearchParamCodec<T>`
+
+The codec protocol shared across search params, segment params, and cookies. See [Codecs](/docs/typed-params) for the full guide.
+
+```ts
+interface SearchParamCodec<T> {
+  parse(value: string | string[] | undefined): T;
+  serialize(value: T): string | null;
+}
+```
+
+Compatible codecs:
+
+- **Zod/Valibot/ArkType schemas** — auto-detected via Standard Schema
+- **nuqs parsers** — `parseAsInteger`, `parseAsString`, `parseAsBoolean`
+- **Custom** — any object implementing the interface
+
+## Built-in Codecs
+
+| Export                         | Description                 |
+| ------------------------------ | --------------------------- |
+| `parseAsString`                | `string \| null`            |
+| `parseAsInteger`               | `number \| null`            |
+| `parseAsFloat`                 | `number \| null`            |
+| `parseAsBoolean`               | `boolean \| null`           |
+| `parseAsStringEnum(values)`    | Enum `T \| null`            |
+| `parseAsStringLiteral(values)` | Literal `T[number] \| null` |
+
+## Codec Wrappers
+
+### `withDefault(codec, value)`
+
+Wrap a codec to replace `null` with a default value.
+
+```ts
+import { withDefault } from '@timber-js/app/search-params';
+import { parseAsInteger } from 'nuqs';
+const page = withDefault(parseAsInteger, 1); // number (never null)
+```
+
+### `withUrlKey(codec, key)`
+
+Attach a URL key alias to a codec.
+
+```ts
+import { withUrlKey } from '@timber-js/app/search-params';
+import { parseAsString } from 'nuqs';
+const query = withUrlKey(parseAsString, 'q');
+// ?q=shoes → { query: 'shoes' }
+```

package/docs/api/34-api-config.mdx

@@ -0,0 +1,189 @@
+---
+title: 'API: timber.config.ts'
+description: 'All configuration options for timber.config.ts.'
+slug: 'api-config'
+---
+
+# timber.config.ts
+
+Project-wide configuration. Export a default object from `timber.config.ts` at the project root.
+
+## Full Type
+
+```ts
+interface TimberUserConfig {
+  output?: 'server' | 'static';
+  buildDir?: string;
+  clientJavascript?: boolean | ClientJavascriptConfig;
+  adapter?: TimberPlatformAdapter;
+  cacheHandler?: CacheHandler;
+  serverTiming?: 'detailed' | 'total' | false;
+  allowedOrigins?: string[];
+  csrf?: boolean;
+  limits?: {
+    actionBodySize?: string;
+    uploadBodySize?: string;
+    maxFields?: number;
+  };
+  actions?: {
+    runMiddleware?: boolean;
+  };
+  forms?: {
+    stripSensitiveFields?: boolean | string[];
+  };
+  pageExtensions?: string[];
+  dev?: {
+    slowPhaseMs?: number;
+  };
+  mdx?: {
+    remarkPlugins?: any[];
+    rehypePlugins?: any[];
+    recmaPlugins?: any[];
+    remarkRehypeOptions?: any;
+  };
+}
+```
+
+## Options
+
+### `output`
+
+- **Type:** `'server' | 'static'`
+- **Default:** `'server'`
+
+Server mode runs on every request. Static mode pre-renders at build time.
+
+### `buildDir`
+
+- **Type:** `string`
+- **Default:** `'.timber/dist'`
+
+Override the build output directory. Relative to the project root. Timber config takes precedence over Vite's `build.outDir`. If neither is set, defaults to `.timber/dist`.
+
+```ts
+buildDir: 'build';       // outputs to <root>/build/
+buildDir: '.output';     // outputs to <root>/.output/
+```
+
+### `clientJavascript`
+
+- **Type:** `boolean | { disabled: boolean; enableHMRInDev?: boolean }`
+- **Default:** `true`
+
+Control client-side JavaScript output. Set to `false` to disable all client JS. Use the object form to disable client JS in production while keeping HMR in development:
+
+```ts
+clientJavascript: { disabled: true, enableHMRInDev: true }
+```
+
+### `adapter`
+
+- **Type:** `TimberPlatformAdapter`
+- **Default:** none
+
+Deployment adapter. See [Deployment](/docs/deploying).
+
+```ts
+import { cloudflare } from '@timber-js/app/adapters/cloudflare';
+import { nitro } from '@timber-js/app/adapters/nitro';
+
+adapter: cloudflare();
+adapter: nitro({ preset: 'node-server' });
+```
+
+### `cacheHandler`
+
+- **Type:** `CacheHandler`
+- **Default:** `MemoryCacheHandler`
+
+Cache backend for `timber.cache()`. See [Cache API](/docs/api-cache).
+
+### `serverTiming`
+
+- **Type:** `'detailed' | 'total' | false`
+- **Default:** `'detailed'` in dev, `'total'` in production
+
+Controls the `Server-Timing` response header. See [Instrumentation & Tracing](/docs/instrumentation).
+
+### `allowedOrigins`
+
+- **Type:** `string[]`
+- **Default:** none
+
+Origins allowed for CORS and CSRF validation.
+
+### `csrf`
+
+- **Type:** `boolean`
+- **Default:** `true` (in server mode)
+
+Enable CSRF protection for server actions and form submissions.
+
+### `limits`
+
+Control request body size limits:
+
+```ts
+limits: {
+  actionBodySize: '1mb',   // Server action body limit
+  uploadBodySize: '10mb',  // File upload body limit
+  maxFields: 1000,         // Maximum FormData fields
+}
+```
+
+### `actions.runMiddleware`
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Run `middleware.ts` on server action requests before dispatching. Keeps authentication, rate limiting, and other cross-cutting checks applied uniformly to page renders, route handlers, and server actions. Set to `false` only if your middleware would corrupt action submissions (e.g. it rewrites POST bodies) — you then own placing those checks inside every action.
+
+### `forms.stripSensitiveFields`
+
+- **Type:** `boolean | string[]`
+- **Default:** `true`
+
+Strip sensitive fields (passwords, tokens, CVV, SSN, etc.) from the `submittedValues` echoed back on validation failure. `true` uses the built-in deny-list; an array adds extra field names to the built-in list; `false` disables stripping (never do this in production). See [Forms & Server Actions](/docs/forms-and-actions) for the full pattern list.
+
+### `pageExtensions`
+
+- **Type:** `string[]`
+- **Default:** `['tsx', 'ts', 'jsx', 'js']`
+
+File extensions recognized for rendering conventions (`page.*`, `layout.*`, `error.*`, `default.*`, `denied.*`, status files). Add `'mdx'` for MDX pages.
+
+Code-only conventions (`middleware.*`, `access.*`, `route.*`, `params.*`) always use `.ts`/`.tsx`/`.js`/`.jsx` regardless of this setting. `.mts`/`.cts`/`.mjs`/`.cjs` are not recognized for any convention.
+
+Two files claiming the same convention in one directory (e.g. `page.tsx` + `page.jsx`) are a build error — filesystem order is platform-dependent, so timber refuses to pick one silently.
+
+### `dev.slowPhaseMs`
+
+- **Type:** `number`
+- **Default:** framework default
+
+Threshold in milliseconds for slow-phase warnings in dev mode.
+
+### `mdx`
+
+MDX compilation options — remark, rehype, and recma plugins:
+
+```ts
+mdx: {
+  remarkPlugins: [remarkGfm],
+  rehypePlugins: [rehypePrism],
+}
+```
+
+## `TimberPlatformAdapter`
+
+The adapter interface for community adapters:
+
+```ts
+interface TimberPlatformAdapter {
+  name: string;
+  buildOutput(config: TimberConfig, buildDir: string): Promise<void>;
+  preview?(config: TimberConfig, buildDir: string): Promise<void>;
+  waitUntil?(promise: Promise<unknown>): void;
+  sendEarlyHints?(links: string[]): void;
+}
+```

package/docs/api/35-api-typescript.mdx

@@ -0,0 +1,170 @@
+---
+title: 'API: TypeScript'
+description: 'Generated route types, $segment modules, typed Link, typed params, and the Routes interface.'
+slug: 'api-typescript'
+---
+
+# TypeScript
+
+timber.js generates route types at build time. Links, params, and search params are type-checked against the actual route tree.
+
+## Generated Route Map
+
+The build system scans your `app/` directory and generates `.timber/routes.d.ts`:
+
+```ts
+// .timber/routes.d.ts (generated, gitignored)
+import type schema from '../app/schema';
+import type { InferCodecType } from '@timber-js/app/params';
+
+export type TimberRoute = keyof TimberSegmentParams;
+
+export interface TimberSegmentParams {
+  '/': {};
+  '/products/[id]': {
+    id: InferCodecType<typeof schema.segmentParams['[id]']>;
+  };
+  '/blog/[...slug]': { slug: string[] };
+}
+
+export type AllSegmentParams = { /* union of all route params */ };
+```
+
+Types reference your `app/schema.ts` codecs directly, so they stay in sync automatically.
+
+## `$segment` — Per-Route Type Narrowing
+
+Each route directory gets a generated `$segment` module (via TypeScript's `rootDirs`). Import `SEGMENT_PATH` for type-safe param access:
+
+```tsx
+// app/products/[id]/page.tsx
+import { SEGMENT_PATH } from './$segment';
+import { getSegmentParams } from '@timber-js/app/server';
+
+export default async function ProductPage() {
+  const { id } = getSegmentParams(SEGMENT_PATH);
+  // id is typed from your schema codec (e.g., number for codec.integer)
+}
+```
+
+### Exports
+
+| Export         | Type                | Description                                                   |
+| -------------- | ------------------- | ------------------------------------------------------------- |
+| `ROUTE`        | String literal      | URL route pattern, groups stripped (e.g., `'/products/[id]'`) |
+| `SEGMENT_PATH` | String literal      | Full tree path including groups and slots                     |
+
+### tsconfig.json
+
+Add `rootDirs` so TypeScript can resolve `$segment` imports:
+
+```jsonc
+{
+  "compilerOptions": {
+    "rootDirs": [".", ".timber/types"]
+  }
+}
+```
+
+## Typed `<Link>`
+
+`<Link>` validates `href` against the route map:
+
+```tsx
+import { Link } from '@timber-js/app/client';
+
+<Link href="/about">About</Link>           // ✓
+<Link href="/nonexistent">Bad</Link>        // ✗ TypeScript error
+```
+
+For dynamic routes, pass `segmentParams`:
+
+```tsx
+import { Link } from '@timber-js/app/client';
+
+<Link href="/products/[id]" segmentParams={{ id: 42 }}>
+  Product
+</Link>
+// → <a href="/products/42">Product</a>
+```
+
+## Typed Segment Params
+
+With `SEGMENT_PATH` from `$segment`, param types are narrowed from your `app/schema.ts` codecs:
+
+```tsx
+// app/products/[id]/page.tsx
+import { SEGMENT_PATH } from './$segment';
+import { getSegmentParams } from '@timber-js/app/server';
+
+export default async function ProductPage() {
+  const { id } = getSegmentParams(SEGMENT_PATH);
+  // id: number (from z.coerce.number().int().positive() in schema.ts)
+}
+```
+
+Without `SEGMENT_PATH`, params are `Partial<AllSegmentParams>` — all optional.
+
+## Typed Search Params
+
+When a `params.ts` file exports `searchParams`, search params are fully typed:
+
+```ts
+// app/products/params.ts
+import { defineSearchParams } from '@timber-js/app/search-params';
+import { z } from 'zod/v4';
+
+export const searchParams = defineSearchParams({
+  page: z.coerce.number().default(1),
+  sort: z.enum(['price', 'name']).default('price'),
+});
+
+// In page.tsx — searchParams.get() returns { page: number; sort: 'price' | 'name' }
+```
+
+## Context Types
+
+### `RouteContext`
+
+Passed to API route handlers (`route.ts`):
+
+```ts
+export async function GET(ctx: RouteContext) {
+  ctx.req; // Request
+  ctx.headers; // Headers (response, writable)
+}
+```
+
+Segment params and query params are read via `segmentParams.get()` / `searchParams.get()` from the colocated `params.ts` / `search-params.ts` — the same accessors pages use. For the raw query string, use `new URL(ctx.req.url).searchParams`.
+
+### `MiddlewareContext`
+
+Passed to `middleware.ts`:
+
+```ts
+export default async function middleware(ctx: MiddlewareContext) {
+  ctx.req; // Request
+  ctx.segmentParams; // Record<string, string | string[]>
+  ctx.headers; // Headers (response, writable)
+  ctx.requestHeaders; // Headers (request, injectable)
+}
+```
+
+### `AccessContext`
+
+Empty interface — `access.ts` takes no arguments. Use ALS-backed imports:
+
+```ts
+import { SEGMENT_PATH } from './$segment';
+import { getSegmentParams } from '@timber-js/app/server';
+
+export default async function access() {
+  const params = getSegmentParams(SEGMENT_PATH);
+}
+```
+
+## Augmenting Routes
+
+The `Routes` interface is generated by the build system and written to `.timber/routes.d.ts`. It's module-augmented onto `@timber-js/app` — you don't need to import it manually.
+
+Run `timber build` or `timber dev` to regenerate types after adding or renaming routes.