@timber-js/app 0.2.0-alpha.196 → 0.2.0-alpha.198

package/docs/learn/13-configuration.mdx

@@ -1,166 +0,0 @@
----
-title: 'Configuration'
-description: 'timber.config.ts — output mode, adapters, caching, and the two-phase model.'
-slug: 'configuration'
----
-
-# Configuration
-
-timber.js is configured through `timber.config.ts` at the project root. Vite configuration lives separately in `vite.config.ts`.
-
-## Minimal Config
-
-```ts title="timber.config.ts"
-export default {
-  output: 'server',
-};
-```
-
-That's it for most projects. The defaults are sensible.
-
-## How the Config Is Loaded
-
-`timber.config.ts` is loaded by Node.js itself using built-in type stripping — it is not bundled by Vite. This requires Node.js 22.18 or newer, and the file must stick to erasable TypeScript syntax: type annotations, interfaces, and `satisfies` are fine, but enums, namespaces, and constructor parameter properties will fail to load. Your `package.json` should declare `"type": "module"` (the default for new timber projects) so the `export default` syntax parses correctly.
-
-If the config file fails to load for any reason, every command — `timber dev`, `timber build`, and `timber preview` — stops with an error naming the file. A broken config never silently falls back to defaults.
-
-## Output Modes
-
-| Mode                                   | Server required | Client JS                 | Server Actions |
-| -------------------------------------- | --------------- | ------------------------- | -------------- |
-| `'server'`                             | Yes             | Yes                       | Yes            |
-| `'static'`                             | No              | Yes (hydration + SPA nav) | Via adapter    |
-| `'static'` + `clientJavascript: false` | No              | None                      | Build error    |
-
-```ts title="timber.config.ts"
-// Static site with no JavaScript
-export default {
-  output: 'static',
-  clientJavascript: false,
-};
-```
-
-## Build Time vs Request Time
-
-The `output` field shifts work between two phases:
-
-**Build time** happens once when you run `timber build`. There's no request, no user, no cookies. Route scanning, client boundary discovery, server action extraction, font downloading, and asset bundling all happen here.
-
-**Request time** happens per incoming HTTP request. Middleware, access checks, server components, caching, cookies, and server actions all run here.
-
-| `output`   | `middleware.ts`       | Server components              | Server actions                              |
-| ---------- | --------------------- | ------------------------------ | ------------------------------------------- |
-| `'server'` | Request time          | Request time                   | Request time                                |
-| `'static'` | **Build time only**   | **Build time** (once, to HTML) | **Request time**, split-deployed as endpoints |
-
-This is why `cookies()` and `headers()` are build errors in static mode — there's no request at the moment components render.
-
-Dynamic routes (`[param]`) must export `generateStaticSegmentParams` when using `output: 'static'` — the build needs to know which URLs to render. API routes (`route.ts`) are also pre-rendered at build time.
-
-For each page, the build generates both HTML (for initial loads) and RSC flight data (for client-side SPA navigation). No server is needed at runtime.
-
-## Adapters
-
-Adapters transform the build output for your deployment platform:
-
-```ts title="timber.config.ts"
-import { cloudflare } from '@timber-js/app/adapters/cloudflare';
-
-export default {
-  output: 'server',
-  adapter: cloudflare(),
-};
-```
-
-```ts title="timber.config.ts"
-import { nitro } from '@timber-js/app/adapters/nitro';
-
-export default {
-  output: 'server',
-  adapter: nitro({ preset: 'node-server' }),
-};
-```
-
-`cloudflare()` for Cloudflare Workers. `nitro({ preset })` for everything else — Node.js, Vercel, Netlify, AWS Lambda, Deno, Bun, Azure.
-
-## Cache Handler
-
-Cache handler configuration lives in a separate `timber.cache.ts` file (not `timber.config.ts`). This keeps runtime cache instances separate from build-time config, preventing build dependencies from leaking into the server bundle.
-
-```ts title="timber.cache.ts"
-import { MemoryCacheHandler } from '@timber-js/app/cache';
-
-export default new MemoryCacheHandler();
-```
-
-The default export is the `CacheHandler` instance. Export `cdnPurge` as a named export for CDN purge handlers. The default handler is in-memory. See [Caching](/docs/caching) for Redis, KV, and custom handlers.
-
-## `clientJavascript`
-
-Control whether client-side JavaScript is included in the build. Useful for static content sites, documentation, and marketing pages that don't need interactivity.
-
-```ts title="timber.config.ts"
-// Disable all client JS
-export default {
-  output: 'static',
-  clientJavascript: false,
-};
-```
-
-```ts title="timber.config.ts"
-// No client JS in production, but keep HMR in dev
-export default {
-  output: 'static',
-  clientJavascript: { disabled: true, enableHMRInDev: true },
-};
-```
-
-| Value                                      | Behavior                                                    |
-| ------------------------------------------ | ----------------------------------------------------------- |
-| `true` (default)                           | Client JS enabled — hydration, SPA navigation, etc.         |
-| `false`                                    | All client JS disabled. No hydration, no SPA navigation.    |
-| `{ disabled: true, enableHMRInDev: true }` | No client JS in production, but HMR still works in dev.     |
-
-Server actions still work — HTML forms submit natively via POST without JavaScript.
-
-## All Options
-
-| Option              | Type                        | Default                      | Description                              |
-| ------------------- | --------------------------- | ---------------------------- | ---------------------------------------- |
-| `output`            | `'server' \| 'static'`     | `'server'`                   | Output mode                              |
-| `debug`             | `boolean`                   | `false`                      | Enable timber debug logging in prod      |
-| `buildDir`          | `string`                    | `'.timber/dist'`             | Build output directory                   |
-| `clientJavascript`  | `boolean \| object`         | `true`                       | Control client-side JS                   |
-| `adapter`           | `TimberPlatformAdapter`     | —                            | Deployment adapter                       |
-| `serverTiming`      | `'detailed' \| 'total' \| false` | `'detailed'` / `'total'` | Server-Timing header                     |
-| `allowedOrigins`    | `string[]`                  | —                            | CORS / CSRF allowed origins              |
-| `csrf`              | `boolean`                   | `true`                       | CSRF protection                          |
-| `limits`            | `object`                    | —                            | Request body size limits                 |
-| `actions`           | `object`                    | —                            | Server action behavior                   |
-| `forms`             | `object`                    | —                            | Form handling (sensitive field stripping) |
-| `pageExtensions`    | `string[]`                  | `['tsx', 'ts', 'jsx', 'js']` | File extensions for pages                |
-| `slowRequestMs`     | `number`                    | `3000`                       | Slow request warning threshold (ms)      |
-| `renderTimeoutMs`   | `number`                    | `30000`                      | Render abort timeout (ms)                |
-| `devBrowserLogs`    | `string`                    | `'warn'`                     | Forward browser console to server in dev |
-| `dev`               | `object`                    | —                            | Dev-mode options                         |
-| `budget`            | `object`                    | —                            | Build-time performance budgets           |
-| `appDir`            | `string`                    | auto-detected                | Override app directory location          |
-| `mdx`               | `object`                    | —                            | MDX remark/rehype plugins                |
-| `actionEncryption`  | `object`                    | —                            | Server action bound args encryption      |
-| `reactCompiler`     | `boolean \| object`         | `true`                       | React Compiler auto-memoization          |
-| `sitemap`           | `object`                    | —                            | Auto-generated sitemap.xml               |
-| `clientSegmentCache`| `boolean`                   | `false`                      | Opt-in client segment cache for partial nav |
-| `topLoader`         | `object`                    | enabled                      | Navigation progress bar                  |
-
-For the full type definition, see the [Config API Reference](/docs/api-config).
-
-## .gitignore
-
-Add these to your `.gitignore` — they're generated at build/dev time and should not be committed:
-
-```txt title=".gitignore"
-.timber
-.content-collections
-```
-
-`.timber` contains the build output (default `.timber/dist`). `.content-collections` contains generated modules from [content collections](/docs/content-collections). `create-timber-app` adds both automatically.

package/docs/more/01-advanced-routing.mdx

@@ -1,344 +0,0 @@
----
-title: 'Advanced Routing'
-description: 'Route groups, parallel routes (slots), intercepting routes, catch-all segments, affixed dynamic segments, and API routes.'
-slug: 'advanced-routing'
----
-
-# Advanced Routing
-
-This page covers routing patterns beyond the basics in [Pages and Layouts](/docs/pages-and-layouts). It assumes you understand `page.tsx`, `layout.tsx`, and nesting.
-
-## Dynamic Segments
-
-Wrap a directory name in brackets to capture a URL parameter:
-
-```
-app/
-  products/
-    [id]/
-      page.tsx          # /products/42, /products/abc
-```
-
-Access the param with `getSegmentParams(SEGMENT_PATH)` using the `$segment` module — see [Typed Params](/docs/typed-params) for the full codec system.
-
-## Catch-All Segments
-
-```
-app/docs/[...slug]/page.tsx    # /docs/a, /docs/a/b, /docs/a/b/c
-app/docs/[[...slug]]/page.tsx  # Same, plus /docs (zero segments)
-```
-
-With optional catch-all segments (`[[...slug]]`), the param is `undefined` when no segments match — not an empty array:
-
-| URL           | `slug` value      |
-| ------------- | ----------------- |
-| `/docs`       | `undefined`       |
-| `/docs/intro` | `['intro']`       |
-| `/docs/a/b/c` | `['a', 'b', 'c']` |
-
-### Not Supported: Optional Single Segments
-
-timber does not support `[[foo]]` (optional single dynamic segment). Use `[[...foo]]` and check `slug?.[0]`, or create two separate pages:
-
-```
-app/blog/page.tsx           # /blog (index)
-app/blog/[year]/page.tsx    # /blog/2024 (filtered)
-```
-
-## Affixed Dynamic Segments
-
-Dynamic segments can have literal prefixes and/or suffixes:
-
-```
-app/
-  images/
-    [id].png/
-      route.ts             # /images/123.png → id = "123"
-  user-[name]/
-    page.tsx               # /user-alice → name = "alice"
-  img-[id].webp/
-    page.tsx               # /img-photo.webp → id = "photo"
-```
-
-This is useful for CDN-cacheable file-extension routes (e.g. image generation endpoints) and prefixed slugs. The literal parts must match exactly; the dynamic middle is extracted as the param value.
-
-**Rules:**
-- The param must be non-empty — `img-[id].png` does NOT match `img-.png`
-- One param per segment — `[foo]-[bar]` is not supported
-- Affixes cannot be used with catch-all (`[...slug].png`) or optional catch-all segments
-- Matching is greedy: `[id].png` matching `a.png.png` yields `id = "a.png"`
-- `app/schema.ts` codecs use the bare bracket form (`[id]`), not the full segment pattern
-
-**Priority:** static → affixed dynamic → bare dynamic → catch-all → optional catch-all. A static `foo.png` always wins over `[id].png`.
-
-`<Link>` interpolates affixed segments automatically:
-
-```tsx
-<Link href="/images/[id].png" segmentParams={{ id: 'photo' }}>
-  {/* renders href="/images/photo.png" */}
-</Link>
-```
-
-## Parallel Routes (Slots)
-
-Directories prefixed with `@` are slots — they render simultaneously within a parent layout:
-
-```
-app/
-  dashboard/
-    layout.tsx          # Receives { children, sidebar }
-    page.tsx            # Renders as children
-    @sidebar/
-      page.tsx          # Renders as sidebar prop
-      default.tsx       # Fallback when no match
-```
-
-```tsx title="app/dashboard/layout.tsx"
-export default function DashboardLayout({
-  children,
-  sidebar,
-}: {
-  children: React.ReactNode;
-  sidebar: React.ReactNode;
-}) {
-  return (
-    <div className="flex">
-      <aside className="w-64">{sidebar}</aside>
-      <main className="flex-1">{children}</main>
-    </div>
-  );
-}
-```
-
-Slots don't add URL depth. Each slot independently matches the current URL and can have its own `access.ts`, `error.tsx`, and layouts. If a slot's access check fails, the slot degrades gracefully — the rest of the page is unaffected (see [Access Control](/docs/access-control)).
-
-**A slot cannot be nested inside another slot.** Slots are resolved for segments on the matched route chain, and a slot's own subtree is not on that chain — so a nested slot could never render, and the build rejects it:
-
-```
-app/dashboard/layout.tsx                     ← receives { children, sidebar }
-app/dashboard/@sidebar/page.tsx              ✓
-app/dashboard/settings/layout.tsx            ← receives { children, panel }
-app/dashboard/settings/@panel/page.tsx       ✓ a second slot deeper on the main chain
-app/dashboard/@sidebar/@panel/page.tsx       ✗ build error — nested inside @sidebar
-app/dashboard/@sidebar/settings/@panel/...   ✗ build error — same, further down
-```
-
-This is a build error rather than a documented limit because nothing at request time could tell you: a slot that never rendered looks exactly like a slot that simply didn't match. Put the second slot on a segment of the main route chain instead.
-
-Note the `layout.tsx` beside each slot. A slot is handed to its owning segment's layout as a named prop, so **the owner must have one** — `app/dashboard/@sidebar/` with no `app/dashboard/layout.tsx` has nothing to be passed to and never renders. That case is dead in the same way as a nested slot, and the build does not currently catch it.
-
-Each slot is also its own collision space: a slot page sharing a URL with the parent page is the point of parallel routes, but two pages inside one slot that answer the same URL (`@side/(a)/x/page.tsx` + `@side/(b)/x/page.tsx`) fail the build, just like the same collision outside a slot. Interceptors that start at the same URL are their own space on the same principle — see [Intercepting routes](#intercepting-routes).
-
-Every collision space is checked the same way: routes are compared by the URLs they match rather than by how they are spelled, so `(a)/[id]` and `(b)/[slug]` collide even though their paths read differently, and a page collides with an optional catch-all beside it because `[[...rest]]` also matches with zero segments. Segment kinds stay distinct — `[id]` beside `[...rest]`, or an affixed `img-[id]` beside a bare `[slug]`, are ordered deterministically and keep building.
-
-## Intercepting Routes
-
-Intercepting routes show a different component on soft navigation (client-side link click) vs hard navigation (direct URL).
-
-| Marker     | Meaning       |
-| ---------- | ------------- |
-| `(.)`      | Same level    |
-| `(..)`     | One level up  |
-| `(..)(..)` | Two levels up |
-| `(...)`    | Root level    |
-
-Where you put the intercepting directory picks between two behaviours.
-
-**Inside a parallel slot → modal overlay.** The slot renders the intercepting page on top; the page you came from stays mounted behind it.
-
-```
-app/feed/@modal/(.)photo/[id]/page.tsx   ← soft nav: modal over the feed
-app/feed/photo/[id]/page.tsx             ← hard nav: the full page
-```
-
-**As a plain child of a segment or route group → sibling layout swap.** No overlay and no slot: the intercepting page replaces the content of *its own* directory's layout chain. This is how two route groups can serve one URL with different layouts.
-
-```
-app/(landing)/layout.tsx
-app/(landing)/[artistSlug]/[year]/page.tsx      ← hard nav renders this
-app/(browse)/layout.tsx
-app/(browse)/(...)[artistSlug]/[year]/page.tsx  ← soft nav from inside (browse) renders this
-```
-
-Navigate directly to `/grateful-dead/1977` and you get `(landing)`'s page under `(landing)`'s layout. Click a link to it from anywhere inside `(browse)` and you stay in `(browse)`'s layout with the intercepting page beneath it. Unlike the modal shape, the intercepting page's params come from the URL you navigated to, so `getSegmentParams()` works exactly as it does on a canonical route.
-
-An intercepting directory must be a **direct** child of one or the other. A marker one directory deeper inside a slot, or nested inside another intercepting subtree, would match the navigation and then have nothing to render — the build fails naming the directory rather than silently serving the wrong page.
-
-```
-app/feed/@modal/(.)photo/[id]/page.tsx   ✓ modal overlay
-app/feed/(.)photo/[id]/page.tsx          ✓ layout swap (feed/layout.tsx required)
-app/(browse)/(...)photo/[id]/page.tsx    ✓ layout swap, scoped to (browse)
-app/feed/@modal/(x)/(.)photo/page.tsx    ✗ build error — not a direct slot child
-app/feed/(.)a/(.)b/page.tsx              ✗ build error — nested interception
-app/feed/@modal/(.)photo/[id]/route.ts   ✗ build error — route handler in interception
-```
-
-Outside a slot, the directory holding the marker must have a `layout.tsx`. That is the directory the swap is scoped to, and the browser reports which directories it has mounted from its layouts — a scope it cannot report would let the swap fire once and then quietly stop. In practice you already have one, since rendering inside that layout is the point.
-
-```
-app/(browse)/layout.tsx                  ✓ required
-app/(browse)/(...)photo/[id]/page.tsx
-```
-
-Also outside a slot, every directory above the marker must be a static segment or a route group. The swapped page renders its own layouts against the URL you navigated to, and that URL carries no values for params declared above the marker — so a dynamic ancestor is a build error rather than a layout that renders with a missing param. Put the same interception in a slot if you need one: the modal shape re-matches the source route, which supplies them.
-
-```
-app/(browse)/(...)photo/[id]/page.tsx    ✓
-app/docs/guides/(.)[id]/page.tsx         ✓
-app/[team]/(..)photo/[id]/page.tsx       ✗ build error — [team] is above the marker
-app/[team]/@modal/(.)photo/[id]/page.tsx ✓ a slot supplies [team] from the source route
-```
-
-Two pages that intercept the same URL are a build error when both sit under interceptors that **start at the same URL** — the set timber resolves in one pass. Route groups are transparent here just as they are elsewhere, so two of them under one marker both claim the same target; and two markers that compute the same starting point are the same case one level up. Either way, which page renders would come down to the order the filesystem happens to list them in.
-
-Pages are compared by the URLs they match, not by how you spell them — so param names don't make two dynamic segments different, and an optional catch-all also matches with *zero* segments.
-
-```
-app/feed/(.)photo/(a)/page.tsx           ✗ build error — both intercept /feed/photo
-app/feed/(.)photo/(b)/page.tsx
-
-app/feed/(.)photo/(a)/[id]/page.tsx      ✗ build error — [id] and [slug] match the same URLs
-app/feed/(.)photo/(b)/[slug]/page.tsx
-
-app/feed/(.)photo/(a)/page.tsx           ✗ build error — [[...rest]] also matches zero segments,
-app/feed/(.)photo/(b)/[[...rest]]/page.tsx    so it claims /feed/photo too
-
-app/feed/(.)photo/page.tsx               ✓ a page plus a tail — the page always wins
-app/feed/(.)photo/[[...rest]]/page.tsx        /feed/photo, the catch-all takes the rest
-
-app/feed/(.)photo/(x)/a/page.tsx         ✓ different URLs
-app/feed/(.)photo/(y)/b/page.tsx
-
-app/feed/(.)photo/(x)/[id]/page.tsx      ✓ different kinds — a single segment always
-app/feed/(.)photo/(y)/[...rest]/page.tsx      beats a catch-all, so this is unambiguous
-
-app/feed/@modal/(.)[a]/page.tsx          ✗ build error — two markers, one starting point,
-app/feed/@modal/(.)[b]/page.tsx               same kind: nothing separates them
-
-app/feed/@modal/(.)photo/[id]/page.tsx   ✓ same starting point, different kinds — the
-app/feed/@modal/(.)[albumSlug]/page.tsx       literal `photo` wins, everything else the second
-```
-
-A route group is transparent for matching, so putting a page inside one does not give it a URL of its own:
-
-```
-app/feed/(.)photo/page.tsx               ✗ build error — both are /feed/photo, so the
-app/feed/(.)photo/(a)/page.tsx                one in the group could never render
-```
-
-Interceptors that start at **different** URLs stay legal even when they target one page — `(.)x` beside `(..)x`, or interceptors in two different slots. Those are separate spaces, and the resolver orders them (deepest marker first).
-
-### Dynamic intercepted segments
-
-The marker is a prefix on an ordinary segment name, so the name after it uses the same bracket syntax as anywhere else:
-
-```
-app/gallery/@modal/(.)photo/[id]/page.tsx    # intercepts /gallery/photo/{id}
-app/gallery/@modal/(.)[albumSlug]/page.tsx   # intercepts /gallery/{albumSlug}
-app/gallery/@modal/(.)[...rest]/page.tsx     # intercepts the whole tail
-```
-
-Intercepting siblings in one slot follow the usual priority — static, then dynamic, then catch-all — so `(.)photo/[id]` and `(.)[albumSlug]` can live in the same `@modal` without ambiguity.
-
-Two affixed interceptors are the one case priority cannot separate: `(.)a-[id]` and `(.)[slug]-b` both match `/gallery/a-b` with the same combined affix length, so which modal opened would come down to filesystem order. That fails the build, exactly as it does for ordinary affixed siblings.
-
-One placement fails the build: an interception whose intercepted level lands below a catch-all. Markers count URL segments, and a catch-all matches a number of them that changes per request, so "same level as `/docs/[...path]`" has no fixed position in `/docs/a/b/c`. Such an interception would fire only when the catch-all consumed exactly one segment and be silently dropped otherwise, so timber names the directory in a build error instead. Climbing past the catch-all avoids it:
-
-```
-app/docs/[...path]/@modal/(.)photo/[id]/page.tsx    ✗ build error
-app/docs/[...path]/@modal/(..)photo/[id]/page.tsx   ✓ (..) climbs past it, basing at /docs
-app/docs/[...path]/@modal/(...)photo/[id]/page.tsx  ✓ (...) bases at the root
-app/[artistSlug]/@modal/(.)photo/[id]/page.tsx      ✓ a dynamic segment is one URL part
-```
-
-A catch-all inside an intercepting route must also be the last segment — nothing below a catch-all can ever match, and the rewrite generated for the unreachable page would hijack the navigation with nothing to render:
-
-```
-app/feed/@modal/(.)[...rest]/page.tsx              ✓
-app/feed/@modal/(.)photo/[...rest]/page.tsx        ✓
-app/feed/@modal/(.)[...rest]/child/page.tsx        ✗ build error — child is unreachable
-app/feed/@modal/(.)photo/[...rest]/child/page.tsx  ✗ build error — same, one level down
-```
-
-### Params in intercepting directories
-
-A dynamic intercepted segment binds a param like any other, so the ordinary param rules apply to it:
-
-```
-app/feed/@modal/(.)[id]/[id]/page.tsx      ✗ build error — duplicate param name
-app/feed/@modal/(.)[albumSlug]/[id]/...    ✓
-```
-
-### Params inside an intercepting page
-
-This section is about the **modal** shape. A layout-swap interception has nothing special going on: its chain is the main route, so `getSegmentParams()` returns the URL's params everywhere in it, exactly as on a canonical route.
-
-Inside a slot, `getSegmentParams()` returns **the intercepted route's** params — what the page's own directories declare:
-
-```tsx title="app/gallery/@modal/(.)photo/[id]/page.tsx"
-export default async function PhotoModal() {
-  const { id } = getSegmentParams(); // the photo's id, not the gallery's params
-  return <Modal photo={await getPhoto(id)} />;
-}
-```
-
-That is worth stating because the request itself is matched against the *source* route (`/gallery`) — the page still rendering behind the modal. The modal's own params are scoped to it, and the source page underneath keeps reading its own.
-
-This is the general slot rule: inside a parallel slot, a no-arg `getSegmentParams()` returns that slot's own params merged over the main route's — the same value as passing the slot's segment path explicitly. Params the slot re-derives win, so a slot that reads a URL part as `[...year]` gets `string[]` even when the main route read it as `[year]`.
-
-### Scope
-
-An interception fires only when the departing page renders the directory that owns it — the slot's parent for a modal, the marker's own parent for a layout swap. For `app/feed/@modal/(.)photo/`, that directory is `/feed`: clicking a photo link from `/feed` or `/feed/trending` opens the modal; clicking one from `/settings` does not.
-
-Route groups count here even though they are invisible in the URL. Anything owned by `app/(browse)/` is scoped to `(browse)`, so a navigation starting in a sibling `(landing)` group renders the normal route, not the interception — that is what makes the layout-swap shape work. A directory at the app root is scoped to the root, which every page renders, which is why `(...)` at the root intercepts from anywhere.
-
-**When two interceptions both apply, the innermost one wins.** A directory and a directory beneath it may each hold a marker for the same URL, and a page inside the inner one renders both — so `app/feed/(.)photo/` and `app/feed/(a)/(.)photo/` both qualify for a click made inside `(a)`. The one scoped to `(a)` renders, on the same reasoning that a `(.)` marker beats a `(...)` one beside it: the more local directory is the more specific statement. Directories that are *not* on one chain — `(a)` beside `(b)` — never both qualify, so they stay independent.
-
-Because scope depends on where the click starts, so does a prefetch: `<Link prefetch>` fetches the variant for the page the link is on, and the cached payload is only used by a click that starts there. Hovering an intercepting link gets you the modal; the same URL prefetched from elsewhere stays the full page.
-
-## API Routes
-
-Export HTTP method handlers from `route.ts`:
-
-```ts title="app/api/hello/route.ts"
-export async function GET(ctx: RouteContext) {
-  return Response.json({ message: 'Hello' });
-}
-
-export async function POST(ctx: RouteContext) {
-  const body = await ctx.request.json();
-  return Response.json({ received: body });
-}
-```
-
-## The Segment Tree
-
-Every directory in your `app/` directory is a **segment**. Segments nest into a tree that connects your URL structure, component structure, and HTML structure:
-
-| Concern           | Segment mapping                                               |
-| ----------------- | ------------------------------------------------------------- |
-| URL matching      | Each segment consumes URL segments (except groups and slots)  |
-| Params            | Dynamic segments extract params, accumulate top-down          |
-| Authorization     | `access.ts` per segment, top-down, shallowest failure wins    |
-| Layouts           | `layout.tsx` per segment, persist across navigation           |
-| Streaming         | `<Suspense>` placement controls flush boundary per segment    |
-| Error handling    | `error.tsx` / status files per segment, leaf-to-root fallback |
-| Client navigation | Segment cache mirrors the tree, skips mounted sync layouts    |
-| Slot isolation    | `@slot` branches render independently, fail gracefully        |
-
-## The Request Lifecycle
-
-``` leading="none"
-Request
-  ├── URL canonicalization
-  ├── proxy.ts (global — every request)
-  ├── Route matching
-  ├── Param coercion (schema.ts codecs)
-  ├── middleware.ts chain (root → leaf)
-  └── Single renderToReadableStream call
-        Root Segment → AccessGate → Layout
-          Child Segment → AccessGate → Layout
-            Leaf Segment → Page
-```
-
-The entire route renders in a **single `renderToReadableStream` call**. One React tree, one `React.cache` scope.

package/docs/more/02-advanced-forms.mdx

@@ -1,137 +0,0 @@
----
-title: 'Advanced Forms'
-description: 'Coercion helpers, parseFormData, form flash internals, and sensitive field stripping.'
-slug: 'advanced-forms'
----
-
-# Advanced Forms
-
-This page covers advanced form patterns beyond [Forms and Actions](/docs/forms-and-actions): coercion helpers, raw FormData parsing, form flash internals, and sensitive field stripping.
-
-## Coercing FormData Values
-
-HTML forms send everything as strings. Use `coerce` helpers to convert FormData values before schema validation:
-
-```ts
-import { coerce } from '@timber-js/app/server';
-import { z } from 'zod/v4';
-
-const eventSchema = z.object({
-  title: z.string().min(1),
-  maxAttendees: z.preprocess(coerce.number, z.number().min(1)),
-  isPublic: z.preprocess(coerce.checkbox, z.boolean()),
-  date: z.preprocess(coerce.date, z.date()),
-});
-```
-
-| Helper            | Input               | Output              |
-| ----------------- | ------------------- | ------------------- |
-| `coerce.number`   | `"42"`, `""`        | `42`, `undefined`   |
-| `coerce.checkbox` | `"on"`, `undefined` | `true`, `false`     |
-| `coerce.json`     | `'{"a":1}'`         | `{ a: 1 }`          |
-| `coerce.date`     | `"2024-01-15"`      | `Date`              |
-| `coerce.file`     | `File`, empty input | `File`, `undefined` |
-
-`coerce.file` accepts options for validation:
-
-```ts
-z.preprocess(
-  coerce.file({ maxSize: 5 * 1024 * 1024, accept: ['image/png', 'image/jpeg'] }),
-  z.instanceof(File)
-);
-```
-
-## `parseFormData`
-
-For advanced cases, `parseFormData` converts raw `FormData` into a plain object before schema validation:
-
-```ts
-import { parseFormData } from '@timber-js/app/server';
-
-const obj = parseFormData(formData);
-```
-
-It handles common patterns:
-
-- **Duplicate keys → arrays**: `tags=js&tags=ts` → `{ tags: ["js", "ts"] }`
-- **Dot-path nesting**: `user.name=Alice` → `{ user: { name: "Alice" } }`
-- **Empty strings → undefined**: Enables `.optional()` semantics
-- **Empty file inputs → undefined**: File inputs with no selection become `undefined`
-
-`createActionClient` calls `parseFormData` automatically — you only need it for manual FormData handling.
-
-## Form Flash Internals
-
-When JavaScript is disabled and a server action returns validation errors, timber re-renders the page with flash data available via `getFormFlash()`:
-
-```ts
-interface FormFlashData {
-  validationErrors: Record<string, string[]>;
-  submittedValues: Record<string, unknown>;
-  serverError?: { code: string; data?: Record<string, unknown> };
-}
-```
-
-- `validationErrors` — field-level errors keyed by field name
-- `submittedValues` — raw input for repopulating form fields (File objects excluded, sensitive fields stripped)
-- `serverError` — present if an `ActionError` was thrown
-
-Flash data is server-side only — stored in AsyncLocalStorage for the duration of the re-render. Never serialized to cookies or headers.
-
-## Sensitive Field Stripping
-
-On validation failure timber echoes submitted form values back so users don't re-type everything. To prevent plaintext passwords or credit-card numbers from leaking through the RSC payload or into HTML `defaultValue` attributes, timber automatically strips a deny-list of sensitive field names.
-
-**Built-in deny-list** (case-insensitive, nested objects walked recursively):
-
-- `password`, `passwd`, `pwd` (and variants like `currentPassword`, `newPassword`)
-- `secret`, `apiKey`, `accessToken`, `refreshToken`, `privateKey`
-- `cvv`, `cvc`, `cardNumber`, `cardCvc`
-- `ssn`, `socialSecurityNumber`
-- `otp`, `totp`, `mfaCode`, `twoFactorCode`
-- `token` (exact match only — `csrfToken` is preserved)
-
-Stripped fields are omitted from `submittedValues` entirely — not replaced with empty strings.
-
-### Global Configuration
-
-```ts title="timber.config.ts"
-import { defineConfig } from '@timber-js/app';
-
-export default defineConfig({
-  forms: {
-    // true / omitted — use built-in deny-list (default)
-    // false — disable all stripping (NEVER in prod)
-    // string[] — extra field names merged with built-in list
-    stripSensitiveFields: ['internalCode', 'bankAccount'],
-  },
-});
-```
-
-### Per-Action Override
-
-```ts
-import { createActionClient } from '@timber-js/app/server';
-
-const action = createActionClient({
-  stripSensitiveFields: (name) => name.startsWith('secret_'),
-});
-```
-
-Per-action config takes precedence over global config, which takes precedence over the built-in default.
-
-## Shared Schemas for Client + Server Validation
-
-Define Zod schemas in shared files and import them on both sides for instant client-side validation while keeping the server as the source of truth:
-
-```ts title="lib/schemas/contact.ts"
-import { z } from 'zod/v4';
-
-export const contactSchema = z.object({
-  name: z.string().min(1, 'Name is required').max(100),
-  email: z.string().email('Invalid email address'),
-  message: z.string().min(10).max(2000),
-});
-```
-
-Use in the server action via `.schema(contactSchema)` and in the client form for `onBlur` validation. Client validation is a UX enhancement — always validate on the server.