@timber-js/app 0.2.0-alpha.195 → 0.2.0-alpha.197

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.

package/docs/more/03-coming-from-nextjs.mdx

@@ -1,186 +0,0 @@
----
-title: 'Coming from Next.js'
-description: 'A practical mapping for Next.js developers — in Next.js you did X, in timber you do Y.'
-slug: 'coming-from-nextjs'
----
-
-# Coming from Next.js
-
-This page maps Next.js patterns to timber equivalents. It's not a comparison (see [timber vs Next.js](/docs/timber-vs-nextjs) for that) — it's a migration mental model.
-
-## Data Fetching
-
-**Next.js:** `getServerSideProps`, `getStaticProps`, or `fetch()` with implicit caching.
-
-**timber:** Async server components. No loaders, no special functions. `fetch()` is never patched or cached — use `timber.cache()` explicitly when you want caching.
-
-```tsx title="app/products/page.tsx"
-// timber — just an async component
-export default async function ProductsPage() {
-  const products = await db.products.findMany();
-  return <ProductList products={products} />;
-}
-```
-
-## `loading.tsx`
-
-**Next.js:** `loading.tsx` convention inserts a Suspense boundary automatically.
-
-**timber:** No `loading.tsx`. Place `<Suspense>` explicitly where you want it. This keeps you in control of what streams and what blocks the HTTP status code.
-
-```tsx
-// timber — explicit Suspense
-import { Suspense } from 'react';
-
-export default async function Page() {
-  const product = await getProduct(id); // blocks, can affect status code
-  return (
-    <div>
-      <h1>{product.name}</h1>
-      <Suspense fallback={<Skeleton />}>
-        <Reviews productId={id} /> {/* streams in */}
-      </Suspense>
-    </div>
-  );
-}
-```
-
-## Middleware
-
-**Next.js:** Single global `middleware.ts` at the project root. Matcher patterns select routes.
-
-**timber:** Per-segment `middleware.ts` files. Place them at the route level that matches the concern. `proxy.ts` for global concerns (CORS, rate limiting, security headers).
-
-```
-app/
-  proxy.ts                    # Global — every request (like Next.js middleware but with next())
-  dashboard/
-    middleware.ts             # Only runs for /dashboard/*
-    settings/
-      middleware.ts           # Only runs for /dashboard/settings/*
-```
-
-## `useSearchParams`
-
-**Next.js:** `useSearchParams()` hook returns a `URLSearchParams` object.
-
-**timber:** Typed search params via `defineSearchParams` in any module you import. Server reads via `.get()`, client reads/writes via `.useQueryStates()`. Segment params are defined globally in `app/schema.ts` via `defineSchema()`, accessed with `getSegmentParams(SEGMENT_PATH)` using the `$segment` module.
-
-```ts title="app/products/search-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('name'),
-});
-```
-
-## Caching
-
-**Next.js:** Implicit fetch caching, `unstable_cache`, ISR with `revalidate`.
-
-**timber:** No implicit caching. No ISR. Explicit `cache.data()` with TTL and tags:
-
-```ts
-import { cache } from '@timber-js/app/cache';
-
-declare const db: { products: { findPopular(): Promise<{ id: string; name: string }[]> } };
-
-const getProducts = cache.data(
-  async () => db.products.findPopular(),
-  { ttl: 300, tags: ['products'] }
-);
-```
-
-## Authorization
-
-**Next.js:** Usually done in middleware or layout components. No built-in access gate pattern.
-
-**timber:** `access.ts` per segment. Runs inside the React tree with `React.cache` sharing. Supports slot degradation (a denied slot renders `denied.tsx` instead of failing the whole page).
-
-```ts title="app/(auth)/access.ts"
-import { redirect, getCookieJar } from '@timber-js/app/server';
-
-declare function getSessionFromCookie(jar: ReturnType<typeof getCookieJar>): { userId: string } | null;
-
-export default async function access() {
-  const session = getSessionFromCookie(getCookieJar());
-  if (!session) redirect('/login');
-}
-```
-
-## Server Actions
-
-**Next.js:** Server actions with `'use server'`. `useFormState` / `useFormStatus`.
-
-**timber:** `createActionClient` for reusable middleware (auth, validation). `useActionState` from `@timber-js/app/client` returns a 4-tuple with auto-derived errors. Forms work without JavaScript via form flash.
-
-```ts title="lib/action.ts"
-import { createActionClient, ActionError } from '@timber-js/app/server';
-import { getUser } from '@/lib/auth';
-
-export const action = createActionClient({
-  middleware: async () => {
-    const user = await getUser();
-    if (!user) throw new ActionError('UNAUTHORIZED');
-    return { user };
-  },
-});
-```
-
-## `notFound()`
-
-**Next.js:** `notFound()` function.
-
-**timber:** `deny(404)` — sends a real HTTP 404 status code:
-
-```tsx
-import { deny } from '@timber-js/app/server';
-
-if (!product) deny(404);
-```
-
-## `redirect()`
-
-**Next.js:** `redirect()` from `next/navigation`.
-
-**timber:** `redirect()` from `@timber-js/app/server`. Same concept, different import:
-
-```ts
-import { redirect } from '@timber-js/app/server';
-
-redirect('/login');        // 302 by default
-redirect('/login', 301);   // Permanent redirect
-```
-
-Code that imports `redirect()` or `notFound()` from `next/navigation` works unmodified — including calls during client component render, which timber converts into an SPA navigation (`redirect`) or your nearest 404 boundary (`notFound`), matching Next.js behavior.
-
-## Metadata
-
-**Next.js:** `export const metadata` or `export async function generateMetadata()`.
-
-**timber:** Same pattern — export `metadata` (static) or a `metadata()` function (dynamic) from any page or layout.
-
-## Imports
-
-| Next.js import            | timber import                              |
-| ------------------------- | ------------------------------------------ |
-| `next/link`               | `@timber-js/app/client` (`Link`)           |
-| `next/navigation`         | `@timber-js/app/client` (`useRouter`, etc) |
-| `next/headers`            | `@timber-js/app/server` (`getHeaders`)     |
-| `next/server`             | `@timber-js/app/server`                    |
-| `unstable_cache`          | `@timber-js/app/cache` (`cache`)           |
-
-## Key Differences Summary
-
-| Concept              | Next.js                          | timber                                |
-| -------------------- | -------------------------------- | ------------------------------------- |
-| Fetch caching        | Implicit, patched `fetch`        | Explicit `timber.cache()`             |
-| ISR                  | Built-in                         | Not supported (use cache + TTL)       |
-| `loading.tsx`        | Convention                       | Use explicit `<Suspense>`             |
-| Middleware            | Single global file              | Per-segment + global `proxy.ts`       |
-| Status codes         | Often 200 for errors            | Real HTTP status codes always         |
-| Auth                 | In middleware or components      | `access.ts` with slot degradation     |
-| Search params        | Untyped `URLSearchParams`       | Typed codecs with validation          |
-| Forms without JS     | Limited support                 | Full form flash support               |