@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.191

package/docs/learn/14-deploying.mdx

@@ -0,0 +1,287 @@
+---
+title: 'Deploying'
+description: 'Deploy timber.js to Cloudflare Workers, Node.js, Vercel, Netlify, AWS Lambda, and more.'
+slug: 'deploying'
+---
+
+# Deploying
+
+timber.js uses **adapters** to transform the build output for your platform. There are exactly two first-party adapters.
+
+## The Two Adapters
+
+**`cloudflare()`** — Cloudflare Workers and Pages. Workers are architecturally different from Node.js (no file system, no `node:http`, different lifecycle model), so they get a dedicated adapter with direct binding access and native `waitUntil()`.
+
+**`nitro({ preset })`** — Everything else. Pick the preset that matches your platform:
+
+| Preset            | Platform               | `waitUntil()` |
+| ----------------- | ---------------------- | ------------- |
+| `node-server`     | Node.js, Docker, VPS   | ✅            |
+| `bun`             | Bun.serve()            | ✅            |
+| `vercel`          | Vercel Serverless      | ✅            |
+| `vercel-edge`     | Vercel Edge Functions  | ✅            |
+| `netlify`         | Netlify Functions      | ❌            |
+| `netlify-edge`    | Netlify Edge Functions | ✅            |
+| `aws-lambda`      | AWS Lambda             | ❌            |
+| `deno-deploy`     | Deno Deploy            | ✅            |
+| `azure-functions` | Azure Functions        | ❌            |
+
+## Build Commands
+
+```bash
+timber build      # Production build
+timber preview    # Local preview of the build output
+```
+
+## Cloudflare Workers
+
+```ts title="timber.config.ts"
+import { cloudflare } from '@timber-js/app/adapters/cloudflare';
+
+export default {
+  output: 'server',
+  adapter: cloudflare(),
+};
+```
+
+```bash
+timber build
+wrangler deploy
+```
+
+The adapter generates a `wrangler.jsonc` with sensible defaults. Access KV, D1, R2, and Queues bindings via `getCloudflareBindings()`:
+
+```ts
+import { getCloudflareBindings } from '@timber-js/app/adapters/cloudflare';
+
+export default async function Page() {
+  const { MY_KV, MY_DB } = getCloudflareBindings();
+  const data = await MY_KV.get('key');
+  // ...
+}
+```
+
+For caching, use `CloudflareKVCacheHandler`:
+
+```ts title="timber.config.ts"
+import { cloudflare } from '@timber-js/app/adapters/cloudflare';
+
+export default {
+  output: 'server',
+  adapter: cloudflare(),
+};
+```
+
+```ts title="timber.cache.ts"
+import { CloudflareKVCacheHandler } from '@timber-js/app/adapters/cloudflare/cache';
+
+export default new CloudflareKVCacheHandler({ bindingName: 'TIMBER_CACHE' });
+```
+
+**Constraints:** no file system, 10ms/30s CPU time limits, 10MB/25MB bundle size.
+
+## Node.js & Docker
+
+```ts title="timber.config.ts"
+import { nitro } from '@timber-js/app/adapters/nitro';
+
+export default {
+  output: 'server',
+  adapter: nitro({ preset: 'node-server' }),
+};
+```
+
+```bash
+timber build
+node .timber/dist/nitro/.output/server/index.mjs
+```
+
+A dedicated server is timber's sweet spot: no cold starts, warm in-process cache, and the ability to co-locate with your database. Five sequential fetches that take 1000ms from serverless take 10ms co-located.
+
+### Docker
+
+```dockerfile
+FROM node:24-slim AS build
+RUN corepack enable
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile
+COPY . .
+RUN pnpm run build
+
+FROM node:24-slim AS runtime
+RUN corepack enable
+RUN groupadd --system timber && useradd --system --gid timber --create-home timber
+WORKDIR /app
+COPY --from=build --chown=timber:timber /app/.timber/dist/nitro/.output ./.output
+COPY --from=build --chown=timber:timber /app/package.json /app/pnpm-lock.yaml ./
+RUN pnpm install --prod --frozen-lockfile
+USER timber
+ENV NODE_ENV=production PORT=3000 HOST=0.0.0.0
+EXPOSE 3000
+CMD ["node", ".output/server/index.mjs"]
+```
+
+For multiple replicas, switch from `MemoryCacheHandler` to `RedisCacheHandler`.
+
+## Vercel
+
+```ts title="timber.config.ts"
+import { nitro } from '@timber-js/app/adapters/nitro';
+
+export default {
+  output: 'server',
+  adapter: nitro({ preset: 'vercel' }),
+};
+```
+
+```bash
+timber build
+vercel deploy --prebuilt
+```
+
+Or connect your git repository — Vercel deploys automatically on push. Use `vercel-edge` preset for Edge Functions. Serverless functions are ephemeral — always use an external cache handler.
+
+## Netlify
+
+```ts title="timber.config.ts"
+import { nitro } from '@timber-js/app/adapters/nitro';
+
+export default {
+  output: 'server',
+  adapter: nitro({ preset: 'netlify' }),
+};
+```
+
+```bash
+timber build
+netlify deploy --prod
+```
+
+Netlify Functions (Lambda-based) don't support `waitUntil()`. Use `netlify-edge` for Deno-based edge execution with `waitUntil()` support.
+
+## AWS Lambda
+
+```ts title="timber.config.ts"
+import { nitro } from '@timber-js/app/adapters/nitro';
+
+export default {
+  output: 'server',
+  adapter: nitro({ preset: 'aws-lambda' }),
+};
+```
+
+Deploy with CDK, SAM, Serverless Framework, or Terraform. Lambda doesn't support `waitUntil()` — use SQS or EventBridge for background work. Use provisioned concurrency to mitigate cold starts.
+
+## Deno, Azure & Bun
+
+```ts title="timber.config.ts"
+import { nitro } from '@timber-js/app/adapters/nitro';
+
+// Deno Deploy
+export default { output: 'server', adapter: nitro({ preset: 'deno-deploy' }) };
+
+// Azure Functions
+export default { output: 'server', adapter: nitro({ preset: 'azure-functions' }) };
+
+// Bun
+export default { output: 'server', adapter: nitro({ preset: 'bun' }) };
+```
+
+## Static Export
+
+For sites that don't need a server:
+
+```ts title="timber.config.ts"
+export default {
+  output: 'static',
+};
+```
+
+Pre-renders every route to HTML at build time. Add `clientJavascript: false` for zero-JavaScript output. Deploy to any static file host — S3, CloudFront, Cloudflare Pages, GitHub Pages, Netlify, or any HTTP server.
+
+### Serving from a sub-path
+
+To deploy under a path instead of a domain root — `https://user.github.io/repo/` on GitHub Pages, for example — set Vite's `base`:
+
+```ts title="vite.config.ts"
+export default defineConfig({
+  base: '/repo/',
+  plugins: [timber()],
+});
+```
+
+Every URL timber emits picks up the prefix: client assets, fonts, and the RSC payloads behind client-side navigation.
+
+Your own links are not rewritten. `base` prefixes emitted assets, not application URLs, so an `href` must include the prefix itself:
+
+```tsx
+<Link href={`${import.meta.env.BASE_URL}about`}>About</Link>
+```
+
+A plain `href="/about"` points at the domain root, outside your deployment.
+
+A relative base (`'./'`) can't tell timber where the site lives, so payload URLs fall back to the domain root and client-side navigation degrades to full page loads on a sub-path deployment. The build warns when it sees one — use an absolute base like `'/repo/'`.
+
+## CDN Integration
+
+timber.js provides typed helpers for CDN caching headers and tag-based purging. CDN caching is always developer-elected — the framework never sets cache headers automatically.
+
+### Header Helpers
+
+```ts title="app/proxy.ts"
+import { cacheControl, cacheTag } from '@timber-js/app/cdn';
+
+export default async function proxy(ctx) {
+  if (ctx.pathname.startsWith('/products/')) {
+    ctx.headers.set('Cache-Control', cacheControl({
+      public: true,
+      maxAge: 600,
+      staleWhileRevalidate: 60,
+    }));
+    // Use cacheTag for Cloudflare Workers Cache (all plans)
+    ctx.headers.set('Cache-Tag', cacheTag(['products']));
+    // Or surrogateKey for Fastly/Akamai/Varnish
+    // ctx.headers.set('Surrogate-Key', surrogateKey(['products']));
+  }
+}
+```
+
+### Purge on `revalidateTag`
+
+When using the Cloudflare adapter, CDN purge is **automatic** — no configuration needed. The adapter auto-wires `WorkersCachePurge`, which uses `ctx.cache.purge({ tags })` from the Workers runtime. Available on all Cloudflare plans with no API token required. Just set `Cache-Tag` headers on your responses using `cacheTag()`.
+
+For non-Workers Cloudflare zones (Enterprise), or other CDNs, configure a purge handler manually:
+
+```ts title="timber.cache.ts"
+import { CloudflarePurge } from '@timber-js/app/cdn/cloudflare';
+
+// Only needed for non-Workers Cloudflare zones (Enterprise)
+export const cdnPurge = new CloudflarePurge({
+  zoneId: process.env.CF_ZONE_ID!,
+  apiToken: process.env.CF_API_TOKEN!,
+});
+```
+
+Fastly:
+
+```ts title="timber.cache.ts"
+import { FastlyPurge } from '@timber-js/app/cdn/fastly';
+
+export const cdnPurge = new FastlyPurge({
+  serviceId: process.env.FASTLY_SERVICE_ID!,
+  apiToken: process.env.FASTLY_API_TOKEN!,
+  softPurge: true,
+});
+```
+
+When `revalidateTag('products')` fires, it clears the application cache **and** calls the CDN purge handler. CDN purge is best-effort — failures are logged but don't break cache invalidation.
+
+## Cache Handler Selection
+
+| Deployment                  | Recommended Handler  | Why                                           |
+| --------------------------- | -------------------- | --------------------------------------------- |
+| Single server (VPS, Docker) | `MemoryCacheHandler` | In-process LRU, no external dependency        |
+| Multi-instance (k8s, ECS)   | `RedisCacheHandler`  | Shared store, tag invalidation across replicas |
+| Cloudflare Workers          | `KVCacheHandler`     | Workers KV, global edge distribution          |
+| Serverless (Vercel, Lambda) | `RedisCacheHandler`  | Ephemeral functions need an external store     |

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

@@ -0,0 +1,343 @@
+---
+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
+```
+
+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.